docs(详细设计): 新增Word回填导出设计

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

@@ -0,0 +1,456 @@
+# 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 输入
+
+```json
+{
+  "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`：
+
+```json
+{
+  "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. 主工作流
+
+```text
+用户发起 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. 标记必填字段、可选字段和人工复核字段。
+
+映射示例：
+
+```yaml
+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](skill/Word回填导出编排Skill.md)
+2. [模板选择Skill](skill/模板选择Skill.md)
+3. [模板字段映射加载Skill](skill/模板字段映射加载Skill.md)
+4. [回填字段集构建Skill](skill/回填字段集构建Skill.md)
+5. [回填拦截检查Skill](skill/回填拦截检查Skill.md)
+6. [Word模板渲染Skill](skill/Word模板渲染Skill.md)
+7. [导出版式校验Skill](skill/导出版式校验Skill.md)
+8. [导出记录生成Skill](skill/导出记录生成Skill.md)
+
+## 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. 后台模板字段映射维护。
+