# 模板字段映射加载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. 缺失必填映射时报错。