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

This commit is contained in:
2026-06-03 21:12:04 +08:00
parent 2876a1b028
commit cc200a32c4
9 changed files with 1017 additions and 0 deletions

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