Files

T

weichen 647da98577 Document unified renderer architecture and delivery plan

Why: Define the approved direction for one rule-driven Word renderer, all-template onboarding, human-readable traceability, and review-aware delivery before implementation starts.

Evidence: SELF documentation checks passed for relative links, balanced code fences, JSON parsing, manifest SHA256 coverage, and git diff whitespace.

Impact: Adds a 12-document review set and immutable review manifest; no runtime code, migration, deployment, or published rule changes.

Refs: feature/rdm-two-trees-latest-templates

2026-10-15 09:23:44 +00:00

5.1 KiB

Raw Blame History

02 总体架构与方案

1. 推荐架构

采用“统一内容模型＋统一渲染内核＋格式适配器＋版本化规则包”。第一阶段提供 Word 适配器，后续 PPT/PDF 不改变上游内容和规则生命周期。

本方案建议把渲染内核放入独立的 Agent-Document-Renderer Go 模块。该模块边界是本次待评审的架构决策；在评审通过和任务启动门禁完成前，不创建新仓库、不改变现有模块 pin，也不迁移现有生产路径。若评审决定先以内嵌包落地，公开接口、依赖方向和后续独立化条件仍须保持与本文一致。

Markdown + metadata + source links
              │
              ▼
      MarkdownParser
              │
              ▼
      CanonicalDocument
              │
      ProfileResolver
              │
              ▼
        RenderProfile
              │
      DocumentRenderer
              │
              ▼
       WordAdapter v1
              │
      ┌───────┼────────┐
      ▼       ▼        ▼
  DOCX bytes  diagnostics manifest

2. 模块边界

2.1 CanonicalDocument

格式无关的不可变输入，包括：

文档身份、标题、语言、项目和文档类型。
section/heading/paragraph/list/table/image/callout/attachment/signature 节点。
稳定节点 ID、层级、文本、样式意图和数据类型。
来源引用、置信度、可见范围和内容版本。
批注、修订集合和审签快照引用。

Markdown 只负责表达内容；页面、字体、Word 样式名和 OOXML 不进入内容模型。

2.2 RenderProfileRegistry

保存规则包元数据、版本、适用范围、状态、资产和 schema 版本。职责：

精确解析 profileId@version。
执行四级规则选择。
验证文档类型、项目范围、发布状态和资产哈希。
返回不可变规则快照。

2.3 DocumentRenderer

格式无关调度器：验证输入、解析规则、构建渲染计划、调用格式适配器、运行输出校验并生成清单。它不读项目数据库、不判断用户权限、不访问网络。

2.4 WordAdapter

唯一允许操作 Word 包结构的模块。负责样式、编号、分节、表格、页眉页脚、图片、书签、内容控件、批注、修订、签署区和 OPC 完整性。

2.5 RDM 编排层

RDM 负责项目权限、文档树、审签、规则选择、冻结提交、交付物保存和追溯关系。它把已经授权和冻结的输入交给渲染器，不让渲染器反查项目数据。

2.6 Backend 工作区交付

普通会话交付使用同一公开渲染入口：先保存 Markdown，再提交受限的 RenderRequest。现有 house-style 能力逐步迁移为公司通用规则包和 WordAdapter，不维持第二套独立语义。

3. 关键接口

type RenderRequest struct {
    Document       CanonicalDocument
    Profile        RenderProfileSnapshot
    Review         ReviewSnapshot
    Mode           RenderMode
    FrozenAt       time.Time
    RequestedBy    string
}

type RenderResult struct {
    Artifact       []byte
    MIME           string
    FileName       string
    Manifest       RenderManifest
    Diagnostics    []Diagnostic
}

type Renderer interface {
    Validate(context.Context, RenderRequest) ([]Diagnostic, error)
    Render(context.Context, RenderRequest) (RenderResult, error)
}

RenderMode 第一阶段固定为 working、preview、review、approved。

4. 生成流程

RDM 冻结 Markdown 版本、节点映射、来源和审签状态。
ProfileResolver 选择确切规则；受控文档不存在确切规则则失败。
Parser 生成 CanonicalDocument，并验证稳定节点 ID。
Renderer 编译声明式规则为 RenderPlan。
WordAdapter 克隆受控模板包或公司通用底稿。
按 RenderPlan 写入内容和受控元数据。
运行 OPC、样式、锚点、字段、回读和安全校验。
保存字节、清单、诊断和追溯边。

5. 确定性与缓存

缓存键：

SHA256(
  canonicalDocumentHash ||
  renderProfileSnapshotHash ||
  reviewSnapshotHash ||
  renderMode ||
  adapterVersion
)

相同键返回同一冻结交付物。规则发布、内容修改、审签变化或适配器升级会形成新键，不覆盖旧文件。

6. 失败策略

profile_not_found：无确切规则。
profile_not_published：规则未发布或已退役。
asset_hash_mismatch：模板、Logo、字体或图片资产漂移。
required_field_missing：文件号、版本或规则必填元数据缺失。
mapping_unresolved：Markdown 节点不能映射到模板槽位。
review_state_invalid：导出模式与审签状态不匹配。
word_validation_failed：DOCX 包、样式、锚点或回读失败。

错误不得触发受控文档向默认规则回退。

7. 扩展格式

后续 PdfAdapter 和 PptAdapter 只消费 CanonicalDocument 与各自 RenderProfile format section。跨格式共用来源、权限、版本、审签和清单；格式特有能力由适配器声明 capability，规则引用未知 capability 时拒绝发布。

5.1 KiB Raw Blame History Unescape Escape