DEMO-AGENT/docs/详细设计/4.一致性核查.md

4. 一致性核查详细设计

1. 设计目标

本步骤承接“字段抽取与统一字段池”的输出，目标是核查同一审核范围内不同文档之间的关键字段是否完全一致，并识别跨产品资料混入、字段冲突、来源不确定和需要人工复核的问题。

本步骤需要完成以下业务结果：

1. 明确本次一致性核查的审核范围，避免把不同产品样例直接合并审核。
2. 加载强一致字段规则，V1 默认按完全一致处理。
3. 从统一字段池读取字段候选值和来源证据。
4. 按字段和来源文档分组。
5. 对强一致字段执行完全一致比对。
6. 识别字段冲突、疑似混档、待人工复核和一致通过项。
7. 生成冲突明细、风险建议和证据链。
8. 输出结构化 registration_consistency_report。

本步骤不负责重新抽取字段，不负责综合风险汇总，不负责自动修正字段池。它只对字段池中已有的字段事实进行一致性判断。

2. 所属模块与边界

2.1 Documents

apps.documents 提供文档主数据，用于确认字段来源文档是否属于同一批次、同一审核范围和相同业务资料角色。

本步骤读取：

1. 文档 ID。
2. 文档名称。
3. 章节点。
4. 文档角色。
5. 批次 ID。
6. 处理状态。
7. 是否待人工复核。

2.2 Agent Core

agent_core 是本步骤的执行主体，负责编排审核范围确认、强一致规则加载、字段池读取、字段分组、完全一致比对、混档识别、报告生成和审计留痕。

本步骤建议产生以下中文 Skill：

1. 一致性核查编排Skill
2. 审核范围确认Skill
3. 强一致规则加载Skill
4. 字段分组Skill
5. 字段完全一致比对Skill
6. 混档风险识别Skill
7. 一致性报告生成Skill

2.3 LLM Provider

本步骤默认不使用 LLM 作为判断引擎。

LLM 只可用于：

1. 将规则结论组织成自然语言说明。
2. 生成处理建议文案。
3. 对复杂冲突进行解释性摘要。

LLM 不可用于：

1. 将不一致字段判为一致。
2. 覆盖强一致规则结论。
3. 无证据地解释跨产品资料混入。

2.4 Audit

apps.audit 记录一致性核查的审核范围、字段规则、冲突字段、来源文档、处理建议和最终状态。

审计中必须保留：

1. batch_id
2. selected_document_ids
3. scope_confirmation
4. field_rule_version
5. consistent_fields
6. conflict_fields
7. mixed_package_warnings
8. manual_review_fields
9. evidence_refs

3. 输入输出

3.1 输入

{
  "batch_id": 1001,
  "scenario_id": "registration_consistency_review",
  "selected_document_ids": [11, 12, 13],
  "field_rule_id": "ivd_strict_consistency_v1",
  "target_field_keys": [
    "product_name",
    "applicant_name",
    "package_specification",
    "classification_code"
  ],
  "strict_mode": true
}

3.2 输出

本步骤输出 registration_consistency_report：

{
  "report_type": "registration_consistency_report",
  "batch_id": 1001,
  "field_rule_id": "ivd_strict_consistency_v1",
  "summary": {
    "checked_field_count": 4,
    "consistent_field_count": 2,
    "conflict_field_count": 1,
    "manual_review_field_count": 1,
    "mixed_package_warning_count": 1,
    "highest_risk_level": "high",
    "pass_status": "failed"
  },
  "consistent_fields": [],
  "conflict_fields": [],
  "manual_review_fields": [],
  "mixed_package_warnings": [],
  "suggestions": []
}

3.3 一致性状态

状态	含义
consistent	同一字段在审核范围内完全一致
conflict	同一字段出现不同标准值或原始值
single_source	只有一个来源，无法跨文档比对
manual_review_required	来源文档或字段值不确定
not_checked	字段不在本次核查范围
mixed_package_suspected	疑似跨产品资料混入

4. 主工作流

用户发起一致性核查
-> 读取统一字段池
-> 确认审核范围
-> 加载强一致字段规则
-> 筛选目标字段
-> 按字段分组候选值
-> 按完全一致规则比对
-> 识别字段冲突
-> 识别疑似混档风险
-> 生成处理建议
-> 写入字段池冲突状态
-> 生成一致性报告
-> 写入审计留痕
-> 返回 Web/飞书可展示结果

5. 节点详细设计

5.1 节点一：读取统一字段池

业务功能：

1. 根据 batch_id 读取字段池。
2. 过滤本次目标字段。
3. 读取每个字段的所有候选值和推荐值。
4. 加载字段来源文档信息。

使用技术：

1. Django ORM
2. JSONField
3. dataclass/Pydantic schema

产生方法：

1. load_field_pool(batch_id) -> list[FieldPoolItem]
2. load_field_candidates(batch_id, field_keys) -> list[FieldCandidateRecord]
3. attach_source_documents(candidates) -> list[FieldCandidateWithDocument]

对应 Skill：

1. 一致性核查编排Skill

5.2 节点二：审核范围确认

业务功能：

1. 确认哪些文档属于同一项目、批次和本次审核范围。
2. 如果用户选择了文档范围，只对选中范围执行。
3. 如果未选择范围，默认使用当前批次业务资料。
4. 对疑似不同产品、不同来源、不同流程资料给出范围警告。

范围确认规则：

1. 同一 batch_id 是最低要求。
2. source_role 必须为 submission。
3. 法规资料不进入一致性核查。
4. 待人工复核文档可以进入，但相关字段不直接判通过。
5. 疑似跨产品文档进入混档风险提示。

使用技术：

1. 文档主数据
2. 资料包批次
3. 文档角色规则
4. 用户选中文档范围

产生方法：

1. resolve_review_scope(batch_id, selected_document_ids) -> ReviewScope
2. validate_scope_documents(documents) -> ScopeValidationResult
3. detect_scope_uncertainties(documents) -> list[ScopeWarning]

对应 Skill：

1. 审核范围确认Skill

5.3 节点三：强一致规则加载

业务功能：

1. 加载强一致字段规则。
2. 确认字段是否要求完全一致。
3. 定义冲突严重度。
4. 定义字段缺少多个来源时的处理方式。

规则示例：

field_rule_id: ivd_strict_consistency_v1
version: "2026-06-03"
strict_mode: true
fields:
  - field_key: product_name
    field_label: 产品名称
    consistency_required: true
    compare_mode: exact
    risk_level_if_conflict: high
  - field_key: performance_index
    consistency_required: false
    compare_mode: not_checked

使用技术：

1. YAML
2. Pydantic schema
3. Django cache

产生方法：

1. load_consistency_rules(field_rule_id) -> ConsistencyRuleSet
2. validate_consistency_rules(rule_set) -> RuleValidationResult
3. select_consistency_fields(rule_set, target_field_keys) -> list[ConsistencyFieldRule]

对应 Skill：

1. 强一致规则加载Skill

5.4 节点四：字段分组

业务功能：

1. 按 field_key 分组字段候选。
2. 按来源文档分组同一字段。
3. 保留标准值、原始值、来源位置、置信度。
4. 标记单来源字段和多来源字段。

使用技术：

1. Python 分组
2. 字段池候选表
3. 文档元数据

产生方法：

1. group_candidates_by_field(candidates) -> dict[str, list[FieldCandidateWithDocument]]
2. group_candidates_by_document(candidates) -> dict[int, list[FieldCandidateWithDocument]]
3. build_field_compare_units(grouped_candidates) -> list[FieldCompareUnit]

对应 Skill：

1. 字段分组Skill

5.5 节点五：字段完全一致比对

业务功能：

1. 对强一致字段执行完全一致比对。
2. 对标准化值不同的字段判定冲突。
3. 对标准化值相同但原始值差异较大的字段标记待复核。
4. 对单来源字段标记无法跨文档比对。

比对规则：

1. compare_mode = exact 时，标准值必须完全一致。
2. 不采用语义相近判定。
3. 空值不参与通过判定。
4. 待人工复核来源不作为通过证据。

使用技术：

1. Python 严格字符串比较
2. 字段标准化结果
3. 风险映射规则

产生方法：

1. compare_exact(field_compare_unit, rule) -> FieldCompareResult
2. detect_value_conflict(values) -> bool
3. detect_raw_value_variation(values) -> bool
4. build_conflict_detail(result) -> ConflictDetail

对应 Skill：

1. 字段完全一致比对Skill

5.6 节点六：混档风险识别

业务功能：

1. 基于产品名称、检测靶标、申请人等核心字段识别疑似跨产品资料混入。
2. 当同一审核范围内出现明显不同产品名称时，输出混档风险。
3. 区分“字段冲突”和“疑似资料包范围错误”。

典型规则：

1. 产品名称出现两个不同值：高风险混档。
2. 检测靶标与产品名称指向明显不同产品：高风险混档。
3. 申请人不同：高风险或待复核。
4. 同一文档角色出现多个版本：中风险或待复核。

使用技术：

1. 字段比对结果
2. 文档角色分析
3. 批次范围校验
4. 规则映射 YAML

产生方法：

1. detect_mixed_package_risk(compare_results, scope) -> list[MixedPackageWarning]
2. detect_product_identity_conflict(field_results) -> MixedPackageWarning | None
3. classify_mixed_package_risk(warning) -> str

对应 Skill：

1. 混档风险识别Skill

5.7 节点七：字段池冲突状态回写

业务功能：

1. 将一致性核查结果回写到字段池。
2. 对冲突字段标记 conflict。
3. 对待复核字段标记 manual_review_required。
4. 对一致字段标记 consistent。

使用技术：

1. Django ORM
2. 批量更新
3. 字段池版本记录

产生方法：

1. update_field_pool_consistency_status(compare_results) -> FieldPoolUpdateResult
2. mark_conflict_field(field_key, conflict_detail) -> None
3. mark_consistent_field(field_key) -> None

对应 Skill：

1. 一致性核查编排Skill

5.8 节点八：一致性报告生成

业务功能：

1. 汇总一致字段、冲突字段、待复核字段和混档风险。
2. 生成结构化报告。
3. 生成页面展示区块。
4. 生成飞书摘要载荷。
5. 写入审计记录。

使用技术：

1. dataclass/Pydantic
2. JSONField
3. Audit 服务
4. 页面展示 schema

产生方法：

1. build_consistency_report(context, compare_results, mixed_warnings) -> RegistrationConsistencyReport
2. build_consistency_summary(compare_results, mixed_warnings) -> dict
3. build_consistency_display_sections(report) -> list[dict]
4. record_consistency_audit(report, context) -> AuditLog

对应 Skill：

1. 一致性报告生成Skill

6. Skill 清单

本步骤产生以下 Skill 设计文档：

1. 一致性核查编排Skill
2. 审核范围确认Skill
3. 强一致规则加载Skill
4. 字段分组Skill
5. 字段完全一致比对Skill
6. 混档风险识别Skill
7. 一致性报告生成Skill

7. 强一致字段设计

V1 建议强一致字段：

字段编码	中文名	风险等级
product_name	产品名称	高
applicant_name	申请人名称	高
package_specification	包装规格	中
classification_code	分类编码	高
detection_target	检测靶标	高
intended_use	适用范围 / 预期用途	中

8. 页面展示

一致性核查页面建议展示：

1. 当前审核范围。
2. 参与核查文档。
3. 强一致字段规则版本。
4. 一致字段数量。
5. 冲突字段数量。
6. 待人工复核字段数量。
7. 混档风险提示。
8. 字段冲突明细表。
9. 来源证据。
10. 审计入口。

冲突明细表字段：

1. 字段名称。
2. 冲突值。
3. 来源文档。
4. 来源位置。
5. 风险等级。
6. 建议动作。

9. 异常处理

1. 字段池不存在：提示先执行字段抽取。
2. 未选择文档且批次为空：返回业务错误。
3. 审核范围内只有单个文档：输出单来源提示，不判冲突。
4. 强一致规则缺失：任务不可执行，写失败审计。
5. 字段全部为空：标记待人工复核。
6. 来源文档待复核：字段不直接判通过。
7. 混档风险存在：本步骤 pass_status 直接失败。

10. 与后续步骤的接口

后续风险预警读取：

1. pass_status
2. highest_risk_level
3. conflict_fields
4. mixed_package_warnings
5. manual_review_fields
6. suggestions

后续 Word 回填读取：

1. 字段池中的 conflict_status。
2. 冲突字段清单。
3. 待人工复核字段清单。
4. 可安全回填字段清单。

11. 测试设计

11.1 单元测试

1. 审核范围确认正确。
2. 强一致规则加载成功。
3. 字段按 field_key 分组正确。
4. 完全一致比对正确。
5. 字段冲突识别正确。
6. 单来源字段不判冲突。
7. 混档风险识别正确。

11.2 服务层测试

1. 产品名称不同输出高风险冲突。
2. 产品名称相同输出一致。
3. 申请人不同输出冲突。
4. 待复核字段进入人工复核清单。
5. 冲突状态回写字段池。
6. 一致性报告写入审计。

11.3 页面测试

1. 页面展示审核范围。
2. 页面展示冲突字段来源。
3. 页面展示混档风险。
4. 页面展示待人工复核状态。
5. 页面展示审计入口。

12. V1 实现建议

V1 建议先完成以下最小闭环：

1. 从统一字段池读取产品名称、申请人名称、包装规格、分类编码。
2. 按完全一致规则比对。
3. 识别样例中可能出现的产品名称冲突。
4. 输出冲突明细和混档风险。
5. 回写字段池 conflict_status。
6. 生成一致性核查报告并写审计。

增强阶段再补齐：

1. 更多强一致字段。
2. 版本重复识别。
3. 文档结构一致性检查。
4. 人工确认后重新判定。
5. 冲突字段修正建议。