# 资料要求匹配Skill 设计

## 1. Skill 定位

`资料要求匹配Skill` 负责把当前资料包中的文档事实与法规要求项进行匹配，生成每个要求项的候选命中文档和匹配证据。

英文实现标识建议使用 `RequirementDocumentMatchSkill`。

本 Skill 只判断“是否可能命中”，不负责最终缺失或风险判定。

## 2. 输入

```python
@dataclass
class RequirementDocumentMatchInput:
    documents: list[DocumentFact]
    requirements: list[RequirementItem]
```

## 3. 输出

```python
@dataclass
class RequirementDocumentMatchOutput:
    matches: list[RequirementDocumentMatch]
    unmatched_documents: list[DocumentFact]
    warnings: list[dict]
```

## 4. 匹配策略

### 4.1 章节点编码匹配

最高优先级。

示例：

1. 文档 `CH1.4 申请表.docx`
2. 要求项 `CH1.4 申请表`
3. 结果：高置信命中

### 4.2 文档角色匹配

使用第一步产生的 `document_role`。

示例：

1. `application_form`
2. `product_list`
3. `regulatory_information_catalog`

### 4.3 关键词匹配

使用法规要求项中的关键词表匹配文件名和相对路径。

### 4.4 人工修正字段匹配

如果用户在后台修正了章节点或资料名称，应优先使用修正结果。

## 5. 核心方法

### 5.1 `run(input) -> RequirementDocumentMatchOutput`

主入口方法。

### 5.2 `match_by_chapter_code(document, requirement) -> MatchEvidence | None`

章节点编码完全相等时返回高置信证据。

### 5.3 `match_by_document_role(document, requirement) -> MatchEvidence | None`

文档角色命中期望角色时返回证据。

### 5.4 `match_by_keywords(document, requirement) -> MatchEvidence | None`

文件名、资料名称或相对路径命中关键词时返回证据。

### 5.5 `calculate_match_confidence(evidences) -> str`

置信度：

1. `high`
2. `medium`
3. `low`
4. `none`

## 6. 技术实现

使用技术：

1. Python 字符串规则
2. `re`
3. 中文空白和标点标准化
4. 可选 `rapidfuzz`

V1 中不建议过度依赖模糊匹配，避免把相似但不等价的资料误判为已提供。

## 7. 异常处理

1. 一个要求项命中多个文档：保留全部候选，交给判定 Skill 处理。
2. 一个文档命中多个要求项：标记潜在错放或重复。
3. 文档待人工复核：仍可参与匹配，但置信度不超过 `medium`。
4. 章节点冲突：输出警告。

## 8. 测试要点

1. 章节点完全匹配返回高置信。
2. 文档角色匹配返回中高置信。
3. 只有关键词匹配返回低或中置信。
4. 待复核文档不会被高置信命中。
5. 多重命中输出警告。