docs(详细设计): 新增一致性核查设计

2026-06-03 21:04:54 +08:00
parent 4208f29d77
commit 0e49eea683
8 changed files with 1086 additions and 0 deletions
--- a/docs/详细设计/skill/一致性报告生成Skill.md
+++ b/docs/详细设计/skill/一致性报告生成Skill.md
@@ -0,0 +1,88 @@
+# 一致性报告生成Skill 设计
+
+## 1. Skill 定位
+
+`一致性报告生成Skill` 负责将字段比对结果和混档风险组装成稳定的 `registration_consistency_report`，并生成页面展示、审计和飞书摘要载荷。
+
+英文实现标识建议使用 `ConsistencyReportBuildSkill`。
+
+## 2. 输入
+
+```python
+@dataclass
+class ConsistencyReportBuildInput:
+    context: ConsistencyReviewContext
+    compare_results: list[FieldCompareResult]
+    mixed_package_warnings: list[dict]
+```
+
+## 3. 输出
+
+```python
+@dataclass
+class ConsistencyReportBuildOutput:
+    report: dict
+    display_sections: list[dict]
+    audit_payload: dict
+    feishu_summary_payload: dict
+```
+
+## 4. 报告结构
+
+报告必须包含：
+
+1. `report_type`
+2. `batch_id`
+3. `field_rule_id`
+4. `summary`
+5. `consistent_fields`
+6. `conflict_fields`
+7. `manual_review_fields`
+8. `mixed_package_warnings`
+9. `suggestions`
+
+## 5. 核心方法
+
+### 5.1 `run(input) -> ConsistencyReportBuildOutput`
+
+主入口方法。
+
+### 5.2 `build_summary(compare_results, warnings) -> dict`
+
+生成汇总。
+
+### 5.3 `split_compare_results(compare_results) -> dict`
+
+拆分一致、冲突、待复核字段。
+
+### 5.4 `build_suggestions(conflicts, warnings) -> list[dict]`
+
+生成处理建议。
+
+### 5.5 `build_audit_payload(report, context) -> dict`
+
+生成审计载荷。
+
+## 6. 技术实现
+
+使用技术：
+
+1. dataclass/Pydantic
+2. JSONField
+3. Audit 服务
+4. 页面展示 schema
+
+## 7. 异常处理
+
+1. 报告字段缺失：任务失败。
+2. 没有可比对字段：输出空报告。
+3. 飞书摘要构建失败：不影响 Web 报告。
+4. 审计写入失败：记录系统警告。
+
+## 8. 测试要点
+
+1. 冲突字段进入 `conflict_fields`。
+2. 混档风险进入 `mixed_package_warnings`。
+3. 汇总数量正确。
+4. 审计载荷包含审核范围。
+
--- a/docs/详细设计/skill/一致性核查编排Skill.md
+++ b/docs/详细设计/skill/一致性核查编排Skill.md
@@ -0,0 +1,103 @@
+# 一致性核查编排Skill 设计
+
+## 1. Skill 定位
+
+`一致性核查编排Skill` 是第四步工作流的总入口 Skill，负责组织审核范围确认、强一致规则加载、字段分组、完全一致比对、混档风险识别、字段池状态回写和报告生成。
+
+英文实现标识建议使用 `ConsistencyReviewOrchestrateSkill`。
+
+## 2. 输入
+
+```python
+@dataclass
+class ConsistencyReviewOrchestrateInput:
+    batch_id: int
+    scenario_id: str = "registration_consistency_review"
+    selected_document_ids: list[int] = field(default_factory=list)
+    field_rule_id: str = "ivd_strict_consistency_v1"
+    target_field_keys: list[str] = field(default_factory=list)
+    strict_mode: bool = True
+```
+
+## 3. 输出
+
+```python
+@dataclass
+class ConsistencyReviewOrchestrateOutput:
+    report_type: str
+    batch_id: int
+    summary: dict
+    consistent_fields: list[dict]
+    conflict_fields: list[dict]
+    manual_review_fields: list[dict]
+    mixed_package_warnings: list[dict]
+    audit_id: int | None = None
+```
+
+## 4. 依赖 Skill
+
+1. `审核范围确认Skill`
+2. `强一致规则加载Skill`
+3. `字段分组Skill`
+4. `字段完全一致比对Skill`
+5. `混档风险识别Skill`
+6. `一致性报告生成Skill`
+
+## 5. 核心方法
+
+### 5.1 `run(input) -> ConsistencyReviewOrchestrateOutput`
+
+主入口方法。
+
+执行顺序：
+
+1. 读取统一字段池。
+2. 调用 `审核范围确认Skill`。
+3. 调用 `强一致规则加载Skill`。
+4. 调用 `字段分组Skill`。
+5. 调用 `字段完全一致比对Skill`。
+6. 调用 `混档风险识别Skill`。
+7. 回写字段池冲突状态。
+8. 调用 `一致性报告生成Skill`。
+9. 写入审计。
+
+### 5.2 `load_field_pool(batch_id) -> list[FieldPoolItem]`
+
+读取字段池主表和候选值。
+
+### 5.3 `update_field_pool_status(compare_results) -> FieldPoolUpdateResult`
+
+回写一致、冲突、待复核状态。
+
+## 6. 技术实现
+
+使用技术：
+
+1. Django ORM
+2. Tool Registry
+3. dataclass/Pydantic
+4. Audit 服务
+
+建议注册名：
+
+```python
+tool_registry.register(
+    name="consistency_review_orchestrate",
+    handler=ConsistencyReviewOrchestrateSkill().run,
+)
+```
+
+## 7. 异常处理
+
+1. 字段池不存在：任务失败并提示先执行字段抽取。
+2. 审核范围为空：返回业务错误。
+3. 规则缺失：任务失败并写审计。
+4. 字段池回写失败：报告仍生成，但标记系统警告。
+
+## 8. 测试要点
+
+1. 能按顺序调用依赖 Skill。
+2. 字段池缺失时返回清晰错误。
+3. 冲突结果能回写字段池。
+4. 输出报告 schema 稳定。
+
--- a/docs/详细设计/skill/字段分组Skill.md
+++ b/docs/详细设计/skill/字段分组Skill.md
@@ -0,0 +1,66 @@
+# 字段分组Skill 设计
+
+## 1. Skill 定位
+
+`字段分组Skill` 负责将统一字段池中的字段候选按字段编码和来源文档分组，形成可比对的数据单元。
+
+英文实现标识建议使用 `FieldGroupSkill`。
+
+## 2. 输入
+
+```python
+@dataclass
+class FieldGroupInput:
+    field_pool_items: list[FieldPoolItem]
+    field_candidates: list[FieldCandidateRecord]
+    scope_documents: list[DocumentFact]
+```
+
+## 3. 输出
+
+```python
+@dataclass
+class FieldGroupOutput:
+    compare_units: list[FieldCompareUnit]
+    single_source_fields: list[dict]
+    excluded_candidates: list[dict]
+```
+
+## 4. 核心方法
+
+### 4.1 `run(input) -> FieldGroupOutput`
+
+主入口方法。
+
+### 4.2 `group_by_field_key(candidates) -> dict`
+
+按字段编码分组。
+
+### 4.3 `filter_candidates_by_scope(candidates, scope_documents) -> list`
+
+只保留审核范围内来源文档的候选。
+
+### 4.4 `build_compare_unit(field_key, candidates) -> FieldCompareUnit`
+
+构建字段比对单元。
+
+## 5. 技术实现
+
+使用技术：
+
+1. Python 分组
+2. 字段池候选记录
+3. 文档范围过滤
+
+## 6. 异常处理
+
+1. 字段无候选：进入待复核。
+2. 来源文档不在范围内：排除候选。
+3. 单来源字段：标记 `single_source`。
+
+## 7. 测试要点
+
+1. 候选按字段分组正确。
+2. 范围外候选被排除。
+3. 单来源字段识别正确。
+
--- a/docs/详细设计/skill/字段完全一致比对Skill.md
+++ b/docs/详细设计/skill/字段完全一致比对Skill.md
@@ -0,0 +1,77 @@
+# 字段完全一致比对Skill 设计
+
+## 1. Skill 定位
+
+`字段完全一致比对Skill` 负责按强一致规则对同一字段的不同来源值执行完全一致比对。
+
+英文实现标识建议使用 `ExactFieldCompareSkill`。
+
+本 Skill 不做语义相似判断。
+
+## 2. 输入
+
+```python
+@dataclass
+class ExactFieldCompareInput:
+    compare_units: list[FieldCompareUnit]
+    rules: list[ConsistencyFieldRule]
+```
+
+## 3. 输出
+
+```python
+@dataclass
+class ExactFieldCompareOutput:
+    compare_results: list[FieldCompareResult]
+    conflict_fields: list[dict]
+    consistent_fields: list[dict]
+    manual_review_fields: list[dict]
+```
+
+## 4. 比对规则
+
+1. 标准值完全相等才算一致。
+2. 空值不算一致证据。
+3. 待复核来源不算通过证据。
+4. 原始值明显差异但标准值相同，进入待复核。
+
+## 5. 核心方法
+
+### 5.1 `run(input) -> ExactFieldCompareOutput`
+
+主入口方法。
+
+### 5.2 `compare_exact(unit, rule) -> FieldCompareResult`
+
+完全一致比对。
+
+### 5.3 `build_conflict_result(unit, values, rule) -> FieldCompareResult`
+
+构建冲突结果。
+
+### 5.4 `build_consistent_result(unit, rule) -> FieldCompareResult`
+
+构建一致结果。
+
+## 6. 技术实现
+
+使用技术：
+
+1. Python 字符串比较
+2. 字段标准化值
+3. 风险规则
+
+## 7. 异常处理
+
+1. 无候选值：待人工复核。
+2. 单来源：不判冲突。
+3. 字段无规则：不检查。
+4. 候选来源待复核：结果待复核。
+
+## 8. 测试要点
+
+1. 相同标准值判一致。
+2. 不同标准值判冲突。
+3. 单来源不判冲突。
+4. 待复核来源进入人工复核。
+
--- a/docs/详细设计/skill/审核范围确认Skill.md
+++ b/docs/详细设计/skill/审核范围确认Skill.md
@@ -0,0 +1,77 @@
+# 审核范围确认Skill 设计
+
+## 1. Skill 定位
+
+`审核范围确认Skill` 负责确认本次一致性核查的文档范围，避免把不同项目、不同产品或法规依据资料混入同一轮比对。
+
+英文实现标识建议使用 `ReviewScopeResolveSkill`。
+
+## 2. 输入
+
+```python
+@dataclass
+class ReviewScopeResolveInput:
+    batch_id: int
+    documents: list[DocumentFact]
+    selected_document_ids: list[int] = field(default_factory=list)
+```
+
+## 3. 输出
+
+```python
+@dataclass
+class ReviewScopeResolveOutput:
+    scope_documents: list[DocumentFact]
+    excluded_documents: list[dict]
+    scope_warnings: list[dict]
+    scope_status: str
+```
+
+## 4. 范围规则
+
+1. 必须同一批次。
+2. 必须是业务申报资料。
+3. 法规资料排除。
+4. 处理失败资料排除。
+5. 待人工复核资料保留但标记警告。
+6. 用户选中范围优先。
+
+## 5. 核心方法
+
+### 5.1 `run(input) -> ReviewScopeResolveOutput`
+
+主入口方法。
+
+### 5.2 `filter_by_selected_documents(documents, ids) -> list[DocumentFact]`
+
+根据用户选择过滤文档。
+
+### 5.3 `exclude_non_submission_documents(documents) -> list[dict]`
+
+排除法规资料和非业务资料。
+
+### 5.4 `build_scope_warnings(documents) -> list[dict]`
+
+生成范围警告。
+
+## 6. 技术实现
+
+使用技术：
+
+1. 文档主数据
+2. Django ORM
+3. 资料来源角色枚举
+
+## 7. 异常处理
+
+1. 范围为空：任务不可执行。
+2. 只有单个文档：允许执行，但只能输出单来源结果。
+3. 全部文档待复核：输出低可信警告。
+
+## 8. 测试要点
+
+1. 选中文档范围生效。
+2. 法规资料被排除。
+3. 待复核文档输出警告。
+4. 空范围返回错误。
+
--- a/docs/详细设计/skill/强一致规则加载Skill.md
+++ b/docs/详细设计/skill/强一致规则加载Skill.md
@@ -0,0 +1,74 @@
+# 强一致规则加载Skill 设计
+
+## 1. Skill 定位
+
+`强一致规则加载Skill` 负责加载字段一致性核查规则，定义哪些字段必须完全一致、如何比对、冲突风险等级和是否参与回填拦截。
+
+英文实现标识建议使用 `StrictConsistencyRuleLoadSkill`。
+
+## 2. 输入
+
+```python
+@dataclass
+class StrictConsistencyRuleLoadInput:
+    field_rule_id: str
+    target_field_keys: list[str] = field(default_factory=list)
+    strict_mode: bool = True
+```
+
+## 3. 输出
+
+```python
+@dataclass
+class StrictConsistencyRuleLoadOutput:
+    field_rule_id: str
+    version: str
+    rules: list[ConsistencyFieldRule]
+    validation_warnings: list[dict]
+```
+
+## 4. 核心方法
+
+### 4.1 `run(input) -> StrictConsistencyRuleLoadOutput`
+
+主入口方法。
+
+### 4.2 `load_rule_file(field_rule_id) -> dict`
+
+读取 YAML 规则。
+
+### 4.3 `validate_rules(raw_rules) -> RuleValidationResult`
+
+校验规则字段。
+
+### 4.4 `select_target_rules(rules, target_field_keys) -> list[ConsistencyFieldRule]`
+
+筛选本次目标字段规则。
+
+## 5. 技术实现
+
+使用技术：
+
+1. YAML
+2. Pydantic
+3. Django cache
+
+建议路径：
+
+```text
+configs/registration/consistency/ivd_strict_consistency_v1.yaml
+```
+
+## 6. 异常处理
+
+1. 规则文件不存在：任务失败。
+2. 目标字段无规则：标记不检查。
+3. 风险等级缺失：默认中风险并记录警告。
+
+## 7. 测试要点
+
+1. 规则加载成功。
+2. 目标字段筛选正确。
+3. 缺少规则时报错。
+4. `strict_mode` 生效。
+
--- a/docs/详细设计/skill/混档风险识别Skill.md
+++ b/docs/详细设计/skill/混档风险识别Skill.md
@@ -0,0 +1,73 @@
+# 混档风险识别Skill 设计
+
+## 1. Skill 定位
+
+`混档风险识别Skill` 负责基于一致性核查结果识别疑似跨产品、跨批次或错误资料混入风险。
+
+英文实现标识建议使用 `MixedPackageRiskDetectSkill`。
+
+## 2. 输入
+
+```python
+@dataclass
+class MixedPackageRiskDetectInput:
+    compare_results: list[FieldCompareResult]
+    scope_documents: list[DocumentFact]
+```
+
+## 3. 输出
+
+```python
+@dataclass
+class MixedPackageRiskDetectOutput:
+    mixed_package_warnings: list[dict]
+    highest_risk_level: str
+```
+
+## 4. 识别规则
+
+1. 产品名称冲突：高风险。
+2. 检测靶标冲突：高风险。
+3. 产品名称和检测靶标指向不同产品：高风险。
+4. 申请人名称冲突：高风险或待复核。
+5. 相同文档角色出现多份不同产品文件：中风险。
+
+## 5. 核心方法
+
+### 5.1 `run(input) -> MixedPackageRiskDetectOutput`
+
+主入口方法。
+
+### 5.2 `detect_product_name_conflict(results) -> dict | None`
+
+识别产品名称冲突。
+
+### 5.3 `detect_target_conflict(results) -> dict | None`
+
+识别检测靶标冲突。
+
+### 5.4 `classify_warning_risk(warning) -> str`
+
+映射风险等级。
+
+## 6. 技术实现
+
+使用技术：
+
+1. 字段比对结果
+2. 文档角色规则
+3. 风险映射 YAML
+
+## 7. 异常处理
+
+1. 缺少产品名称字段：不输出混档结论，标记待复核。
+2. 只有单来源：不输出混档结论。
+3. 字段已冲突但来源不明：标记待人工确认。
+
+## 8. 测试要点
+
+1. 产品名称冲突输出高风险。
+2. 检测靶标冲突输出高风险。
+3. 单来源不输出混档风险。
+4. 缺少核心字段时输出待复核。
+