DEMO-AGENT/docs/详细设计/6.Word回填导出.md

6. Word 回填导出详细设计

1. 设计目标

本步骤承接字段抽取、统一字段池、一致性核查和风险预警结果，目标是将可回填字段按模板映射写入注册申报表格或对照清单，并生成新的 Word 文件供用户下载、复核和归档。

本步骤需要完成以下业务结果：

1. 选择适用的 Word 模板。
2. 加载模板字段映射。
3. 从统一字段池读取可回填字段。
4. 根据风险报告和冲突状态执行回填拦截。
5. 生成回填数据集。
6. 按模板写入 Word 文档。
7. 校验输出文档版式、字段落位和导出状态。
8. 生成导出记录和下载入口。
9. 写入审计留痕。

本步骤不重新抽取字段，不修改法规判断和风险结论。若字段冲突或高风险未处理，应阻止自动生成可报送文件，或者生成“待复核草稿版”并明确标记。

2. 所属模块与边界

2.1 Documents

apps.documents 负责保存生成后的 Word 文件、记录导出文件元数据，并提供下载入口。

2.2 Agent Core

agent_core 负责模板选择、字段映射、回填数据集构建、Word 渲染、版式校验和导出报告生成。

本步骤建议产生以下中文 Skill：

1. Word回填导出编排Skill
2. 模板选择Skill
3. 模板字段映射加载Skill
4. 回填字段集构建Skill
5. 回填拦截检查Skill
6. Word模板渲染Skill
7. 导出版式校验Skill
8. 导出记录生成Skill

2.3 Audit

apps.audit 记录本次回填导出的模板版本、字段映射、回填字段、拦截状态、输出文件和失败原因。

审计中必须保留：

1. batch_id
2. template_id
3. template_version
4. field_mapping_version
5. filled_fields
6. blocked_fields
7. output_file_id
8. export_status
9. layout_check_result

3. 输入输出

3.1 输入

{
  "batch_id": 1001,
  "scenario_id": "registration_word_fill_export",
  "template_id": "registration_application_form_v1",
  "target_output_type": "application_form",
  "allow_draft_when_blocked": true,
  "selected_field_keys": [
    "product_name",
    "detection_target",
    "intended_use",
    "storage_condition",
    "performance_index"
  ]
}

3.2 输出

本步骤输出 registration_word_export_report：

{
  "report_type": "registration_word_export_report",
  "batch_id": 1001,
  "template_id": "registration_application_form_v1",
  "export_status": "draft_generated",
  "summary": {
    "fillable_field_count": 5,
    "filled_field_count": 4,
    "blocked_field_count": 1,
    "manual_review_field_count": 1,
    "layout_check_status": "passed"
  },
  "filled_fields": [],
  "blocked_fields": [],
  "output_file": {
    "file_id": 2001,
    "filename": "注册申报表格_回填草稿.docx",
    "download_url": "/documents/exports/2001/download/"
  }
}

4. 主工作流

用户发起 Word 回填导出
-> 读取字段池和风险报告
-> 选择目标模板
-> 加载模板字段映射
-> 构建回填字段集
-> 执行冲突和风险拦截检查
-> 渲染 Word 模板
-> 校验字段落位和版式
-> 保存导出文件
-> 生成导出报告
-> 写入审计留痕
-> 返回下载入口

5. 节点详细设计

5.1 节点一：导出上下文加载

业务功能：

1. 读取资料包批次。
2. 读取统一字段池。
3. 读取一致性核查报告。
4. 读取风险预警报告。
5. 确认是否允许生成正式版或草稿版。

使用技术：

1. Django ORM
2. JSONField 报告快照
3. dataclass/Pydantic

产生方法：

1. load_export_context(batch_id, template_id) -> WordExportContext
2. load_fillable_field_pool(batch_id) -> list[FieldPoolItem]
3. load_export_blockers(batch_id) -> ExportBlockerContext

对应 Skill：

1. Word回填导出编排Skill

5.2 节点二：模板选择

业务功能：

1. 根据输出目标选择模板。
2. 校验模板是否存在。
3. 校验模板适用流程。
4. 校验模板版本是否启用。

模板类型：

1. 注册申报表格模板。
2. 法规对照清单模板。
3. 注册证或批准证明文件格式模板。

使用技术：

1. 模板库模型
2. Django Storage
3. YAML/JSON 模板元数据

产生方法：

1. select_word_template(template_id, target_output_type) -> WordTemplate
2. validate_template_applicability(template, workflow_type) -> TemplateValidationResult
3. resolve_template_file_path(template) -> Path

对应 Skill：

1. 模板选择Skill

5.3 节点三：模板字段映射加载

业务功能：

1. 加载模板字段和统一字段池字段的映射关系。
2. 校验模板占位符是否完整。
3. 标记必填字段、可选字段和人工复核字段。

映射示例：

template_id: registration_application_form_v1
version: "2026-06-03"
mappings:
  - placeholder: "{{ product_name }}"
    field_key: product_name
    required: true
  - placeholder: "{{ intended_use }}"
    field_key: intended_use
    required: true

使用技术：

1. YAML
2. Pydantic
3. 模板占位符扫描

产生方法：

1. load_template_field_mapping(template_id) -> TemplateFieldMapping
2. validate_mapping_against_template(template, mapping) -> MappingValidationResult
3. scan_template_placeholders(template_file) -> list[str]

对应 Skill：

1. 模板字段映射加载Skill

5.4 节点四：回填字段集构建

业务功能：

1. 从字段池读取映射字段。
2. 选择推荐值。
3. 过滤不可回填字段。
4. 生成待回填字段集。

使用技术：

1. Django ORM
2. 字段池数据
3. 映射规则

产生方法：

1. build_fill_dataset(field_pool, mapping) -> FillDataset
2. resolve_field_value(field_key, field_pool) -> FillValue
3. collect_missing_fill_values(mapping, field_pool) -> list[MissingFillValue]

对应 Skill：

1. 回填字段集构建Skill

5.5 节点五：回填拦截检查

业务功能：

1. 检查字段是否存在冲突。
2. 检查字段是否待人工复核。
3. 检查风险报告是否存在高风险。
4. 判断是否允许生成正式版或草稿版。

拦截规则：

1. 高风险未处理：禁止生成正式版。
2. 字段冲突未处理：禁止自动正式回填。
3. 必填字段缺失：禁止正式版。
4. 允许生成草稿版时，输出文件必须标记“待复核草稿”。

使用技术：

1. 风险报告
2. 字段池冲突状态
3. 回填策略规则

产生方法：

1. check_fill_blockers(fill_dataset, risk_report) -> FillBlockerResult
2. determine_export_mode(blockers, allow_draft) -> str
3. build_blocked_field_list(blockers) -> list[BlockedField]

对应 Skill：

1. 回填拦截检查Skill

5.6 节点六：Word 模板渲染

业务功能：

1. 打开 Word 模板。
2. 替换占位符。
3. 写入表格单元格。
4. 保留标题层级、表格、页眉页脚、盖章位和原始样式。
5. 输出新的 Word 文件。

使用技术：

1. python-docx
2. docxtpl 可选
3. Django Storage
4. 临时文件目录

产生方法：

1. render_word_template(template_file, fill_dataset, export_mode) -> RenderedWordFile
2. replace_paragraph_placeholders(document, values) -> None
3. replace_table_placeholders(document, values) -> None
4. save_rendered_document(document, output_path) -> Path

对应 Skill：

1. Word模板渲染Skill

5.7 节点七：导出版式校验

业务功能：

1. 校验输出文件是否存在。
2. 校验必填占位符是否已替换。
3. 校验是否仍残留模板占位符。
4. 校验基础版式元素是否存在。
5. 必要时渲染预览用于人工确认。

使用技术：

1. python-docx
2. 文档占位符扫描
3. 可选 LibreOffice 转 PDF
4. 可选 PDF 渲染检查

产生方法：

1. check_export_layout(output_file, mapping) -> LayoutCheckResult
2. detect_unfilled_placeholders(output_file) -> list[str]
3. validate_required_sections(output_file) -> list[LayoutWarning]

对应 Skill：

1. 导出版式校验Skill

5.8 节点八：导出记录生成

业务功能：

1. 保存输出文件记录。
2. 生成下载地址。
3. 生成导出报告。
4. 写入审计。

使用技术：

1. Django ORM
2. Django Storage
3. JSONField
4. Audit 服务

产生方法：

1. create_export_file_record(batch, output_file) -> ExportedDocument
2. build_download_url(export_file) -> str
3. build_word_export_report(context, result) -> RegistrationWordExportReport
4. record_word_export_audit(report, context) -> AuditLog

对应 Skill：

1. 导出记录生成Skill

6. Skill 清单

本步骤产生以下 Skill 设计文档：

1. Word回填导出编排Skill
2. 模板选择Skill
3. 模板字段映射加载Skill
4. 回填字段集构建Skill
5. 回填拦截检查Skill
6. Word模板渲染Skill
7. 导出版式校验Skill
8. 导出记录生成Skill

7. 导出模式

模式	含义
formal	正式导出，字段无冲突且无高风险
draft	草稿导出，存在待复核项但允许预览
blocked	拦截导出，不生成文件

8. 页面展示

Word 回填导出页面建议展示：

1. 模板名称和版本。
2. 回填字段数量。
3. 已回填字段。
4. 被拦截字段。
5. 导出模式。
6. 版式校验结果。
7. Word 下载入口。
8. 审计入口。

9. 异常处理

1. 模板不存在：任务失败。
2. 模板字段映射缺失：任务失败。
3. 必填字段缺失：正式版导出拦截。
4. 字段冲突：正式版导出拦截。
5. 高风险未处理：正式版导出拦截。
6. Word 渲染失败：记录导出失败。
7. 版式校验失败：生成文件标记待复核。

10. 与后续步骤的接口

飞书通知读取：

1. 导出状态。
2. 下载链接。
3. 被拦截字段。
4. 待复核字段。
5. 责任角色。

11. 测试设计

11.1 单元测试

1. 模板选择正确。
2. 字段映射加载正确。
3. 必填字段缺失被拦截。
4. 冲突字段被拦截。
5. 占位符替换正确。
6. 残留占位符可识别。

11.2 服务层测试

1. 能基于字段池生成 Word 草稿。
2. 高风险存在时禁止正式导出。
3. 导出文件记录生成。
4. 导出报告写入审计。

11.3 页面测试

1. 页面展示导出状态。
2. 页面展示下载入口。
3. 页面展示拦截原因。
4. 页面展示版式校验结果。

12. V1 实现建议

V1 建议先完成以下最小闭环：

1. 维护一个注册申报表格或对照清单模板。
2. 支持字段占位符回填。
3. 支持冲突字段和高风险拦截。
4. 生成新的 .docx 文件。
5. 提供下载入口。
6. 写入审计。

增强阶段再补齐：

1. 多模板库管理。
2. PDF 归档件导出。
3. 高保真版式自动校验。
4. 模板版本审批。
5. 后台模板字段映射维护。