docs(详细设计): 新增风险预警设计

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

@@ -0,0 +1,477 @@
+# 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 输入
+
+```json
+{
+  "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`：
+
+```json
+{
+  "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. 主工作流
+
+```text
+用户发起风险预警
+-> 读取前序任务报告
+-> 加载风险规则
+-> 从完整性报告生成缺失/错放风险
+-> 从字段抽取报告生成抽取不确定风险
+-> 从一致性报告生成冲突/混档风险
+-> 合并重复和关联风险
+-> 计算风险等级和准入状态
+-> 生成整改建议和责任角色
+-> 生成综合风险报告
+-> 写入审计留痕
+-> 返回 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. 加载整改建议模板。
+
+建议规则目录：
+
+```text
+configs/registration/risk/
+  ivd_registration_risk_v1.yaml
+```
+
+规则示例：
+
+```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](skill/风险预警编排Skill.md)
+2. [前序报告汇总Skill](skill/前序报告汇总Skill.md)
+3. [风险规则加载Skill](skill/风险规则加载Skill.md)
+4. [风险项生成Skill](skill/风险项生成Skill.md)
+5. [风险归并Skill](skill/风险归并Skill.md)
+6. [准入判定Skill](skill/准入判定Skill.md)
+7. [整改建议生成Skill](skill/整改建议生成Skill.md)
+8. [风险报告生成Skill](skill/风险报告生成Skill.md)
+
+## 7. 风险项结构
+
+```json
+{
+  "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. 后台风险规则维护。
+