5.1 KiB
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 时拒绝发布。