# 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. 后台模板字段映射维护。