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

2026-06-03 21:12:04 +08:00
parent 2876a1b028
commit cc200a32c4
9 changed files with 1017 additions and 0 deletions
--- a/docs/详细设计/skill/Word回填导出编排Skill.md
+++ b/docs/详细设计/skill/Word回填导出编排Skill.md
@@ -0,0 +1,90 @@
+# Word回填导出编排Skill 设计
+
+## 1. Skill 定位
+
+`Word回填导出编排Skill` 是第六步工作流的总入口 Skill，负责组织模板选择、字段映射加载、回填字段集构建、回填拦截检查、Word 渲染、版式校验和导出记录生成。
+
+英文实现标识建议使用 `WordFillExportOrchestrateSkill`。
+
+## 2. 输入
+
+```python
+@dataclass
+class WordFillExportOrchestrateInput:
+    batch_id: int
+    template_id: str
+    target_output_type: str
+    selected_field_keys: list[str] = field(default_factory=list)
+    allow_draft_when_blocked: bool = True
+```
+
+## 3. 输出
+
+```python
+@dataclass
+class WordFillExportOrchestrateOutput:
+    report_type: str
+    batch_id: int
+    export_status: str
+    output_file: dict | None
+    filled_fields: list[dict]
+    blocked_fields: list[dict]
+    audit_id: int | None = None
+```
+
+## 4. 依赖 Skill
+
+1. `模板选择Skill`
+2. `模板字段映射加载Skill`
+3. `回填字段集构建Skill`
+4. `回填拦截检查Skill`
+5. `Word模板渲染Skill`
+6. `导出版式校验Skill`
+7. `导出记录生成Skill`
+
+## 5. 核心方法
+
+### 5.1 `run(input) -> WordFillExportOrchestrateOutput`
+
+主入口方法。
+
+### 5.2 `load_export_context(input) -> WordExportContext`
+
+加载字段池、风险报告和一致性报告。
+
+### 5.3 `resolve_export_mode(blockers) -> str`
+
+确认正式、草稿或拦截模式。
+
+## 6. 技术实现
+
+使用技术：
+
+1. Tool Registry
+2. Django ORM
+3. Django Storage
+4. dataclass/Pydantic
+
+建议注册名：
+
+```python
+tool_registry.register(
+    name="word_fill_export_orchestrate",
+    handler=WordFillExportOrchestrateSkill().run,
+)
+```
+
+## 7. 异常处理
+
+1. 模板缺失：任务失败。
+2. 字段池缺失：任务失败。
+3. 正式导出被拦截：按配置生成草稿或直接返回拦截。
+4. 渲染失败：写失败审计。
+
+## 8. 测试要点
+
+1. 能按顺序调用依赖 Skill。
+2. 冲突字段导致正式导出拦截。
+3. 草稿模式可生成文件。
+4. 输出报告稳定。
+
--- a/docs/详细设计/skill/Word模板渲染Skill.md
+++ b/docs/详细设计/skill/Word模板渲染Skill.md
@@ -0,0 +1,67 @@
+# Word模板渲染Skill 设计
+
+## 1. Skill 定位
+
+`Word模板渲染Skill` 负责将回填字段集写入 Word 模板，生成新的 `.docx` 文件。
+
+英文实现标识建议使用 `WordTemplateRenderSkill`。
+
+## 2. 输入
+
+```python
+@dataclass
+class WordTemplateRenderInput:
+    template_file_path: Path
+    fill_dataset: dict
+    export_mode: str
+    output_dir: Path
+```
+
+## 3. 输出
+
+```python
+@dataclass
+class WordTemplateRenderOutput:
+    output_file_path: Path
+    rendered_placeholders: list[str]
+    render_warnings: list[dict]
+```
+
+## 4. 核心方法
+
+### 4.1 `run(input) -> WordTemplateRenderOutput`
+
+主入口方法。
+
+### 4.2 `replace_paragraph_placeholders(document, values) -> None`
+
+替换段落占位符。
+
+### 4.3 `replace_table_placeholders(document, values) -> None`
+
+替换表格占位符。
+
+### 4.4 `save_document(document, output_path) -> Path`
+
+保存文档。
+
+## 5. 技术实现
+
+使用技术：
+
+1. `python-docx`
+2. 可选 `docxtpl`
+3. Django Storage
+
+## 6. 异常处理
+
+1. 模板打不开：任务失败。
+2. 占位符替换失败：记录警告。
+3. 保存失败：任务失败。
+
+## 7. 测试要点
+
+1. 段落占位符可替换。
+2. 表格占位符可替换。
+3. 输出文件存在。
+
--- a/docs/详细设计/skill/回填字段集构建Skill.md
+++ b/docs/详细设计/skill/回填字段集构建Skill.md
@@ -0,0 +1,62 @@
+# 回填字段集构建Skill 设计
+
+## 1. Skill 定位
+
+`回填字段集构建Skill` 负责根据模板字段映射和统一字段池构建实际要写入 Word 模板的字段值集合。
+
+英文实现标识建议使用 `FillDatasetBuildSkill`。
+
+## 2. 输入
+
+```python
+@dataclass
+class FillDatasetBuildInput:
+    field_pool_items: list[FieldPoolItem]
+    template_mappings: list[dict]
+    selected_field_keys: list[str] = field(default_factory=list)
+```
+
+## 3. 输出
+
+```python
+@dataclass
+class FillDatasetBuildOutput:
+    fill_dataset: dict
+    missing_required_fields: list[dict]
+    manual_review_fields: list[dict]
+```
+
+## 4. 核心方法
+
+### 4.1 `run(input) -> FillDatasetBuildOutput`
+
+主入口方法。
+
+### 4.2 `resolve_field_value(mapping, field_pool) -> FillValue`
+
+解析字段值。
+
+### 4.3 `build_placeholder_values(mappings, field_pool) -> dict`
+
+生成占位符和值。
+
+## 5. 技术实现
+
+使用技术：
+
+1. 字段池数据
+2. 模板映射
+3. Python 字典构建
+
+## 6. 异常处理
+
+1. 必填字段缺失：进入缺失列表。
+2. 字段待复核：进入待复核列表。
+3. 字段不可回填：跳过。
+
+## 7. 测试要点
+
+1. 可回填字段进入 dataset。
+2. 必填缺失可识别。
+3. 待复核字段可识别。
+
--- a/docs/详细设计/skill/回填拦截检查Skill.md
+++ b/docs/详细设计/skill/回填拦截检查Skill.md
@@ -0,0 +1,70 @@
+# 回填拦截检查Skill 设计
+
+## 1. Skill 定位
+
+`回填拦截检查Skill` 负责根据字段冲突、风险报告和必填字段缺失情况判断是否允许正式回填导出。
+
+英文实现标识建议使用 `FillBlockerCheckSkill`。
+
+## 2. 输入
+
+```python
+@dataclass
+class FillBlockerCheckInput:
+    fill_dataset: dict
+    risk_report: dict
+    consistency_report: dict
+    missing_required_fields: list[dict]
+    allow_draft_when_blocked: bool
+```
+
+## 3. 输出
+
+```python
+@dataclass
+class FillBlockerCheckOutput:
+    export_mode: str
+    blocked_fields: list[dict]
+    blockers: list[dict]
+```
+
+## 4. 拦截规则
+
+1. 高风险未处理：拦截正式版。
+2. 字段冲突：拦截正式版。
+3. 必填字段缺失：拦截正式版。
+4. 待人工复核：允许草稿，不允许正式版。
+
+## 5. 核心方法
+
+### 5.1 `run(input) -> FillBlockerCheckOutput`
+
+主入口方法。
+
+### 5.2 `detect_high_risk_blocker(risk_report) -> list[dict]`
+
+检测高风险。
+
+### 5.3 `detect_conflict_blocker(consistency_report) -> list[dict]`
+
+检测冲突字段。
+
+### 5.4 `resolve_export_mode(blockers, allow_draft) -> str`
+
+确定导出模式。
+
+## 6. 技术实现
+
+使用技术：
+
+1. 风险报告
+2. 一致性报告
+3. 本地规则
+
+## 7. 测试要点
+
+1. 高风险拦截正式导出。
+2. 冲突字段拦截正式导出。
+3. 草稿模式可用。
+4. 无拦截时正式导出。
+
--- a/docs/详细设计/skill/导出版式校验Skill.md
+++ b/docs/详细设计/skill/导出版式校验Skill.md
@@ -0,0 +1,65 @@
+# 导出版式校验Skill 设计
+
+## 1. Skill 定位
+
+`导出版式校验Skill` 负责检查回填后的 Word 文件是否仍有未替换占位符、必填字段是否落位、基础版式是否完整。
+
+英文实现标识建议使用 `ExportLayoutCheckSkill`。
+
+## 2. 输入
+
+```python
+@dataclass
+class ExportLayoutCheckInput:
+    output_file_path: Path
+    template_mappings: list[dict]
+```
+
+## 3. 输出
+
+```python
+@dataclass
+class ExportLayoutCheckOutput:
+    layout_check_status: str
+    unfilled_placeholders: list[str]
+    layout_warnings: list[dict]
+```
+
+## 4. 核心方法
+
+### 4.1 `run(input) -> ExportLayoutCheckOutput`
+
+主入口方法。
+
+### 4.2 `detect_unfilled_placeholders(file) -> list[str]`
+
+检查残留占位符。
+
+### 4.3 `validate_required_fields(file, mappings) -> list[dict]`
+
+校验必填字段。
+
+### 4.4 `validate_basic_layout(file) -> list[dict]`
+
+校验基础版式元素。
+
+## 5. 技术实现
+
+使用技术：
+
+1. `python-docx`
+2. 可选 LibreOffice 转 PDF
+3. 占位符扫描规则
+
+## 6. 异常处理
+
+1. 文件不存在：校验失败。
+2. 残留占位符：标记待复核。
+3. 版式元素缺失：标记警告。
+
+## 7. 测试要点
+
+1. 残留占位符可识别。
+2. 必填字段缺失可识别。
+3. 正常文档通过校验。
+
--- a/docs/详细设计/skill/导出记录生成Skill.md
+++ b/docs/详细设计/skill/导出记录生成Skill.md
@@ -0,0 +1,75 @@
+# 导出记录生成Skill 设计
+
+## 1. Skill 定位
+
+`导出记录生成Skill` 负责保存导出文件元数据、生成下载入口、构建导出报告并写入审计。
+
+英文实现标识建议使用 `ExportRecordBuildSkill`。
+
+## 2. 输入
+
+```python
+@dataclass
+class ExportRecordBuildInput:
+    batch_id: int
+    output_file_path: Path | None
+    export_mode: str
+    layout_check_result: dict
+    filled_fields: list[dict]
+    blocked_fields: list[dict]
+```
+
+## 3. 输出
+
+```python
+@dataclass
+class ExportRecordBuildOutput:
+    report: dict
+    output_file: dict | None
+    audit_payload: dict
+```
+
+## 4. 核心方法
+
+### 4.1 `run(input) -> ExportRecordBuildOutput`
+
+主入口方法。
+
+### 4.2 `create_export_file_record(file_path) -> ExportedDocument`
+
+创建导出文件记录。
+
+### 4.3 `build_download_url(export_file) -> str`
+
+生成下载 URL。
+
+### 4.4 `build_report(input, output_file) -> dict`
+
+生成导出报告。
+
+### 4.5 `build_audit_payload(report) -> dict`
+
+生成审计载荷。
+
+## 5. 技术实现
+
+使用技术：
+
+1. Django ORM
+2. Django Storage
+3. JSONField
+4. Audit 服务
+
+## 6. 异常处理
+
+1. 文件不存在：只生成拦截报告。
+2. 下载链接生成失败：报告标记异常。
+3. 审计失败：记录系统警告。
+
+## 7. 测试要点
+
+1. 文件记录创建成功。
+2. 下载链接生成成功。
+3. 拦截模式不创建文件。
+4. 审计载荷完整。
+
--- a/docs/详细设计/skill/模板字段映射加载Skill.md
+++ b/docs/详细设计/skill/模板字段映射加载Skill.md
@@ -0,0 +1,67 @@
+# 模板字段映射加载Skill 设计
+
+## 1. Skill 定位
+
+`模板字段映射加载Skill` 负责加载 Word 模板占位符与统一字段池字段之间的映射关系。
+
+英文实现标识建议使用 `TemplateFieldMappingLoadSkill`。
+
+## 2. 输入
+
+```python
+@dataclass
+class TemplateFieldMappingLoadInput:
+    template_id: str
+    template_file_path: Path
+```
+
+## 3. 输出
+
+```python
+@dataclass
+class TemplateFieldMappingLoadOutput:
+    template_id: str
+    mapping_version: str
+    mappings: list[dict]
+    missing_placeholders: list[str]
+    extra_placeholders: list[str]
+```
+
+## 4. 核心方法
+
+### 4.1 `run(input) -> TemplateFieldMappingLoadOutput`
+
+主入口方法。
+
+### 4.2 `load_mapping(template_id) -> dict`
+
+读取映射规则。
+
+### 4.3 `scan_placeholders(template_file) -> list[str]`
+
+扫描模板占位符。
+
+### 4.4 `validate_mapping(mapping, placeholders) -> MappingValidationResult`
+
+校验映射完整性。
+
+## 5. 技术实现
+
+使用技术：
+
+1. YAML
+2. `python-docx`
+3. Pydantic
+
+## 6. 异常处理
+
+1. 映射不存在：任务失败。
+2. 必填占位符缺失：任务失败。
+3. 模板存在未映射占位符：标记警告。
+
+## 7. 测试要点
+
+1. 映射加载成功。
+2. 模板占位符能扫描。
+3. 缺失必填映射时报错。
+
--- a/docs/详细设计/skill/模板选择Skill.md
+++ b/docs/详细设计/skill/模板选择Skill.md
@@ -0,0 +1,65 @@
+# 模板选择Skill 设计
+
+## 1. Skill 定位
+
+`模板选择Skill` 负责根据目标输出类型选择可用 Word 模板，并校验模板适用流程和版本状态。
+
+英文实现标识建议使用 `WordTemplateSelectSkill`。
+
+## 2. 输入
+
+```python
+@dataclass
+class WordTemplateSelectInput:
+    template_id: str
+    target_output_type: str
+    workflow_type: str = "registration"
+```
+
+## 3. 输出
+
+```python
+@dataclass
+class WordTemplateSelectOutput:
+    template_id: str
+    template_version: str
+    template_file_path: Path
+    template_type: str
+    validation_warnings: list[dict]
+```
+
+## 4. 核心方法
+
+### 4.1 `run(input) -> WordTemplateSelectOutput`
+
+主入口方法。
+
+### 4.2 `load_template(template_id) -> WordTemplate`
+
+读取模板记录。
+
+### 4.3 `validate_template(template, workflow_type) -> TemplateValidationResult`
+
+校验模板适用性。
+
+## 5. 技术实现
+
+使用技术：
+
+1. Django ORM
+2. Django Storage
+3. 模板元数据 YAML
+
+## 6. 异常处理
+
+1. 模板不存在：任务失败。
+2. 模板文件丢失：任务失败。
+3. 模板未启用：任务失败。
+4. 流程不匹配：任务失败。
+
+## 7. 测试要点
+
+1. 能选择启用模板。
+2. 禁用模板不可用。
+3. 流程不匹配时报错。
+