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 输入

```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. 后台风险规则维护。