DEMO-AGENT/docs/详细设计/5.风险预警.md

5. 风险预警详细设计

1. 设计目标

本步骤承接法规完整性检查、字段抽取与一致性核查结果，目标是把缺失项、错放项、字段冲突、混档风险、待人工复核项和交付风险统一汇总成可执行的合规风险清单，并给出是否通过、整改优先级和责任建议。

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

1. 汇总前序任务报告。
2. 加载风险分级和准入规则。
3. 将完整性、字段抽取、一致性等结果映射为风险项。
4. 合并重复风险和关联风险。
5. 计算最高风险等级和是否通过。
6. 生成整改建议、处理优先级和责任角色。
7. 输出结构化 registration_risk_report。
8. 为飞书通知步骤生成风险摘要载荷。

本步骤不重新执行完整性检查、字段抽取或一致性核查。它只消费前序结构化报告，并在规则基础上生成综合风险预警。

2. 所属模块与边界

2.1 Agent Core

agent_core 是本步骤的执行主体，负责编排报告加载、风险规则加载、风险项生成、风险归并、准入判定、整改建议生成和报告输出。

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

1. 风险预警编排Skill
2. 前序报告汇总Skill
3. 风险规则加载Skill
4. 风险项生成Skill
5. 风险归并Skill
6. 准入判定Skill
7. 整改建议生成Skill
8. 风险报告生成Skill

2.2 LLM Provider

LLM 可以用于将规则风险结论整理为自然语言建议，但不能改变风险等级、是否通过和整改优先级。

LLM 可以处理：

1. 风险摘要润色。
2. 整改建议文案组织。
3. 飞书通知摘要表达。

LLM 不可处理：

1. 修改规则判定的风险等级。
2. 将高风险降级。
3. 将不通过改为通过。

2.3 Audit

apps.audit 记录风险预警的输入报告、风险规则版本、风险项、准入结论和建议动作。

审计中必须保留：

1. batch_id
2. source_report_ids
3. risk_rule_version
4. risk_items
5. pass_status
6. highest_risk_level
7. manual_review_items
8. owner_roles
9. suggestions

3. 输入输出

3.1 输入

{
  "batch_id": 1001,
  "scenario_id": "registration_risk_report",
  "risk_rule_id": "ivd_registration_risk_v1",
  "include_reports": [
    "registration_completeness_report",
    "registration_field_extraction_report",
    "registration_consistency_report"
  ],
  "enable_llm_summary": true
}

3.2 输出

本步骤输出 registration_risk_report：

{
  "report_type": "registration_risk_report",
  "batch_id": 1001,
  "risk_rule_id": "ivd_registration_risk_v1",
  "summary": {
    "risk_item_count": 6,
    "high_risk_count": 2,
    "medium_risk_count": 2,
    "low_risk_count": 1,
    "manual_review_count": 1,
    "highest_risk_level": "high",
    "pass_status": "failed"
  },
  "risk_items": [],
  "manual_review_items": [],
  "suggestions": [],
  "owner_notifications": []
}

4. 主工作流

用户发起风险预警
-> 读取前序任务报告
-> 加载风险规则
-> 从完整性报告生成缺失/错放风险
-> 从字段抽取报告生成抽取不确定风险
-> 从一致性报告生成冲突/混档风险
-> 合并重复和关联风险
-> 计算风险等级和准入状态
-> 生成整改建议和责任角色
-> 生成综合风险报告
-> 写入审计留痕
-> 返回 Web/飞书可展示结果

5. 节点详细设计

5.1 节点一：前序报告汇总

业务功能：

1. 读取当前批次的完整性检查报告。
2. 读取字段抽取报告。
3. 读取一致性核查报告。
4. 判断哪些报告缺失或过期。
5. 将报告统一转为风险输入上下文。

使用技术：

1. Django ORM
2. JSONField
3. 报告版本号
4. dataclass/Pydantic

产生方法：

1. load_source_reports(batch_id, include_reports) -> SourceReportBundle
2. validate_source_reports(bundle) -> SourceReportValidationResult
3. build_risk_context(bundle) -> RiskEvaluationContext

对应 Skill：

1. 前序报告汇总Skill

5.2 节点二：风险规则加载

业务功能：

1. 加载风险分级规则。
2. 加载准入规则。
3. 加载风险类型和责任角色映射。
4. 加载整改建议模板。

建议规则目录：

configs/registration/risk/
  ivd_registration_risk_v1.yaml

规则示例：

risk_rule_id: ivd_registration_risk_v1
version: "2026-06-03"
admission:
  high_risk_policy: fail
  multiple_medium_policy: review_required
risk_types:
  missing_required_document:
    default_level: high
    owner_role: 注册申报负责人
  field_conflict:
    default_level: high
    owner_role: 注册资料负责人

使用技术：

1. YAML
2. Pydantic schema
3. Django cache

产生方法：

1. load_risk_rules(risk_rule_id) -> RiskRuleSet
2. validate_risk_rules(rule_set) -> RiskRuleValidationResult
3. load_owner_role_mapping(rule_set) -> dict

对应 Skill：

1. 风险规则加载Skill

5.3 节点三：风险项生成

业务功能：

1. 从完整性报告生成缺失、错放、待复核风险。
2. 从字段抽取报告生成字段缺失、低可信、抽取失败风险。
3. 从一致性报告生成字段冲突、混档风险。
4. 记录风险来源报告和证据。

风险类型：

1. missing_required_document
2. misplaced_document
3. field_missing
4. field_low_confidence
5. field_conflict
6. mixed_package
7. manual_review_required
8. delivery_blocker

使用技术：

1. Python 规则映射
2. 风险规则 YAML
3. 前序报告 schema

产生方法：

1. build_risks_from_completeness(report, rules) -> list[RiskItem]
2. build_risks_from_field_extraction(report, rules) -> list[RiskItem]
3. build_risks_from_consistency(report, rules) -> list[RiskItem]
4. attach_risk_evidence(risk_item, source_report) -> RiskItem

对应 Skill：

1. 风险项生成Skill

5.4 节点四：风险归并

业务功能：

1. 合并重复风险。
2. 关联同一根因风险。
3. 避免同一字段冲突重复出现在多个列表。
4. 保留风险来源链路。

归并示例：

1. 产品名称冲突和混档风险可以关联。
2. 缺失申请表和字段缺失申请人名称可以关联。
3. 文档待复核导致的字段低可信可以关联。

使用技术：

1. 风险指纹
2. risk_type + field_key + document_id
3. Python 分组

产生方法：

1. build_risk_fingerprint(risk_item) -> str
2. merge_duplicate_risks(risk_items) -> list[RiskItem]
3. link_related_risks(risk_items) -> list[RiskGroup]

对应 Skill：

1. 风险归并Skill

5.5 节点五：准入判定

业务功能：

1. 计算最高风险等级。
2. 根据规则判断是否通过。
3. 区分风险等级和人工复核状态。
4. 输出最终准入结论。

准入规则：

1. 任一高风险项：pass_status = failed
2. 无高风险但多个中风险：pass_status = review_required
3. 仅低风险：pass_status = conditional_pass
4. 无风险但有人工复核项：pass_status = review_required
5. 无风险无复核：pass_status = passed

使用技术：

1. 风险规则
2. Python 枚举
3. 评分配置

产生方法：

1. calculate_highest_risk_level(risk_items) -> str
2. calculate_pass_status(risk_items, manual_review_items, rules) -> str
3. build_admission_detail(risk_items, status) -> AdmissionDecision

对应 Skill：

1. 准入判定Skill

5.6 节点六：整改建议生成

业务功能：

1. 为每个风险项生成建议动作。
2. 按高、中、低风险排序。
3. 映射责任角色。
4. 生成可用于飞书通知的摘要。

使用技术：

1. 本地建议模板
2. 责任角色映射
3. 可选 LLM Provider 生成自然语言摘要

产生方法：

1. build_risk_suggestion(risk_item, rules) -> Suggestion
2. sort_suggestions_by_priority(suggestions) -> list[Suggestion]
3. build_owner_notification_payload(risk_items) -> list[OwnerNotificationPayload]
4. summarize_risk_report_with_llm(report) -> str

对应 Skill：

1. 整改建议生成Skill

5.7 节点七：风险报告生成

业务功能：

1. 汇总风险项和建议。
2. 生成结构化风险报告。
3. 生成页面展示区块。
4. 生成飞书通知载荷。
5. 写入审计。

使用技术：

1. dataclass/Pydantic
2. JSONField
3. Audit 服务
4. 飞书摘要 payload schema

产生方法：

1. build_risk_report(context, risk_items, admission, suggestions) -> RegistrationRiskReport
2. build_risk_summary(risk_items, admission) -> dict
3. build_risk_display_sections(report) -> list[dict]
4. record_risk_audit(report, context) -> AuditLog

对应 Skill：

1. 风险报告生成Skill

6. Skill 清单

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

1. 风险预警编排Skill
2. 前序报告汇总Skill
3. 风险规则加载Skill
4. 风险项生成Skill
5. 风险归并Skill
6. 准入判定Skill
7. 整改建议生成Skill
8. 风险报告生成Skill

7. 风险项结构

{
  "risk_id": "RISK-001",
  "risk_type": "field_conflict",
  "risk_level": "high",
  "source_report_type": "registration_consistency_report",
  "related_documents": [11, 12],
  "related_field_key": "product_name",
  "description": "说明书与申请表中的产品名称不一致。",
  "suggestion": "请先确认当前审核范围是否混入其他产品资料。",
  "owner_role": "注册资料负责人",
  "manual_review_required": false
}

8. 页面展示

风险预警页面建议展示：

1. 综合结论。
2. 是否通过。
3. 最高风险等级。
4. 高/中/低风险数量。
5. 待人工复核数量。
6. 风险清单。
7. 整改建议。
8. 责任角色。
9. 审计入口。

9. 异常处理

1. 前序报告缺失：生成“报告不完整”风险或提示先执行对应任务。
2. 风险规则缺失：任务不可执行，写失败审计。
3. LLM 不可用：使用本地模板生成建议。
4. 责任角色未配置：使用默认责任角色并提示维护映射。
5. 风险项为空：输出通过或待复核状态。

10. 与后续步骤的接口

后续 Word 回填读取：

1. pass_status
2. high_risk_count
3. field_conflict 风险项。
4. manual_review_items
5. 可回填风险拦截状态。

后续飞书通知读取：

1. 风险摘要。
2. 高风险清单。
3. 责任角色。
4. 责任人通知载荷。
5. Web 详情页链接。

11. 测试设计

11.1 单元测试

1. 风险规则加载成功。
2. 完整性缺失项生成风险。
3. 字段冲突生成高风险。
4. 混档风险生成高风险。
5. 风险归并正确。
6. 任一高风险判不通过。

11.2 服务层测试

1. 缺少完整性报告时提示前序任务缺失。
2. 有高风险时 pass_status = failed。
3. 只有低风险时 conditional_pass。
4. 待复核项进入人工复核清单。
5. 风险报告写入审计。

11.3 页面测试

1. 页面展示最高风险等级。
2. 页面展示风险清单。
3. 页面展示整改建议。
4. 页面展示责任角色。
5. 页面展示审计入口。

12. V1 实现建议

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

1. 汇总完整性检查和一致性核查报告。
2. 生成缺失风险、字段冲突风险、混档风险。
3. 实现任一高风险即不通过。
4. 生成整改建议和责任角色。
5. 输出 registration_risk_report。
6. 写入审计。

增强阶段再补齐：

1. 多维度风险评分。
2. 历史申报事项风险。
3. 版本一致性风险。
4. 飞书责任人通知联动。
5. 后台风险规则维护。