Bruce/DEMO-AGENT
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
bruce
2026-06-03 21:12:04 +08:00
parent 2876a1b028
commit cc200a32c4
9 changed files with 1017 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

456
docs/详细设计/6.Word回填导出.md Normal file
View File

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

90
docs/详细设计/skill/Word回填导出编排Skill.md Normal file
View File

@@ -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. 输出报告稳定。

67
docs/详细设计/skill/Word模板渲染Skill.md Normal file
View File

@@ -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. 输出文件存在。

62
docs/详细设计/skill/回填字段集构建Skill.md Normal file
View File

@@ -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. 待复核字段可识别。

70
docs/详细设计/skill/回填拦截检查Skill.md Normal file
View File

@@ -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. 无拦截时正式导出。

65
docs/详细设计/skill/导出版式校验Skill.md Normal file
View File

@@ -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. 正常文档通过校验。

75
docs/详细设计/skill/导出记录生成Skill.md Normal file
View File

@@ -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. 审计载荷完整。

67
docs/详细设计/skill/模板字段映射加载Skill.md Normal file
View File

@@ -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. 缺失必填映射时报错。

65
docs/详细设计/skill/模板选择Skill.md Normal file
View File

@@ -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. 流程不匹配时报错。