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

docs/详细设计/skill/准入判定Skill.md

@@ -0,0 +1,70 @@
+# 准入判定Skill 设计
+
+## 1. Skill 定位
+
+`准入判定Skill` 负责根据风险项、人工复核项和准入规则计算最终是否通过。
+
+英文实现标识建议使用 `AdmissionDecisionSkill`。
+
+## 2. 输入
+
+```python
+@dataclass
+class AdmissionDecisionInput:
+    risk_items: list[RiskItem]
+    manual_review_items: list[dict]
+    admission_rules: dict
+```
+
+## 3. 输出
+
+```python
+@dataclass
+class AdmissionDecisionOutput:
+    pass_status: str
+    highest_risk_level: str
+    decision_reason: str
+    score_detail: dict
+```
+
+## 4. 判定规则
+
+1. 任一高风险：不通过。
+2. 多个中风险：待整改后复核。
+3. 只有低风险：条件通过。
+4. 有人工复核项：待复核。
+5. 无风险：通过。
+
+## 5. 核心方法
+
+### 5.1 `run(input) -> AdmissionDecisionOutput`
+
+主入口方法。
+
+### 5.2 `calculate_highest_level(risk_items) -> str`
+
+计算最高风险等级。
+
+### 5.3 `calculate_status(risk_items, manual_review_items, rules) -> str`
+
+计算准入状态。
+
+### 5.4 `build_decision_reason(status, risk_items) -> str`
+
+生成判定理由。
+
+## 6. 技术实现
+
+使用技术：
+
+1. 风险等级枚举
+2. 准入规则 YAML
+3. Python 规则判断
+
+## 7. 测试要点
+
+1. 高风险导致失败。
+2. 中风险过多导致复核。
+3. 低风险条件通过。
+4. 无风险通过。
+

docs/详细设计/skill/前序报告汇总Skill.md

@@ -0,0 +1,67 @@
+# 前序报告汇总Skill 设计
+
+## 1. Skill 定位
+
+`前序报告汇总Skill` 负责读取当前批次已经生成的完整性、字段抽取和一致性核查报告，并统一转为风险评估上下文。
+
+英文实现标识建议使用 `SourceReportCollectSkill`。
+
+## 2. 输入
+
+```python
+@dataclass
+class SourceReportCollectInput:
+    batch_id: int
+    include_reports: list[str]
+```
+
+## 3. 输出
+
+```python
+@dataclass
+class SourceReportCollectOutput:
+    reports: dict[str, dict]
+    missing_reports: list[str]
+    stale_reports: list[str]
+    validation_warnings: list[dict]
+```
+
+## 4. 核心方法
+
+### 4.1 `run(input) -> SourceReportCollectOutput`
+
+主入口方法。
+
+### 4.2 `load_report(batch_id, report_type) -> dict | None`
+
+读取报告快照。
+
+### 4.3 `validate_report_freshness(report) -> bool`
+
+校验报告是否过期。
+
+### 4.4 `build_report_bundle(reports) -> SourceReportBundle`
+
+构建报告集合。
+
+## 5. 技术实现
+
+使用技术：
+
+1. Django ORM
+2. JSONField
+3. 报告版本号
+
+## 6. 异常处理
+
+1. 报告不存在：加入 `missing_reports`。
+2. 报告 schema 不完整：加入警告。
+3. 报告过期：加入 `stale_reports`。
+
+## 7. 测试要点
+
+1. 能读取多个报告。
+2. 缺失报告能识别。
+3. 过期报告能识别。
+4. 输出 bundle 稳定。
+

docs/详细设计/skill/整改建议生成Skill.md

@@ -0,0 +1,71 @@
+# 整改建议生成Skill 设计
+
+## 1. Skill 定位
+
+`整改建议生成Skill` 负责根据风险项生成处理建议、整改优先级和责任角色。
+
+英文实现标识建议使用 `RectificationSuggestionBuildSkill`。
+
+## 2. 输入
+
+```python
+@dataclass
+class RectificationSuggestionBuildInput:
+    risk_items: list[RiskItem]
+    suggestion_templates: dict
+    owner_role_mapping: dict
+    enable_llm_summary: bool = True
+```
+
+## 3. 输出
+
+```python
+@dataclass
+class RectificationSuggestionBuildOutput:
+    suggestions: list[dict]
+    owner_notifications: list[dict]
+    summary_text: str
+```
+
+## 4. 核心方法
+
+### 4.1 `run(input) -> RectificationSuggestionBuildOutput`
+
+主入口方法。
+
+### 4.2 `build_suggestion(risk_item) -> dict`
+
+生成单项建议。
+
+### 4.3 `resolve_owner_role(risk_item) -> str`
+
+映射责任角色。
+
+### 4.4 `sort_by_priority(suggestions) -> list[dict]`
+
+按风险等级和业务优先级排序。
+
+### 4.5 `build_summary_text(suggestions) -> str`
+
+生成摘要，可选使用 LLM Provider。
+
+## 5. 技术实现
+
+使用技术：
+
+1. 建议模板
+2. 责任角色映射
+3. 可选 LLM Provider
+
+## 6. 异常处理
+
+1. 模板缺失：使用默认建议。
+2. 责任角色缺失：使用默认负责人。
+3. LLM 不可用：使用本地摘要。
+
+## 7. 测试要点
+
+1. 高风险建议优先。
+2. 责任角色映射正确。
+3. LLM 不可用时本地摘要可用。
+

docs/详细设计/skill/风险归并Skill.md

@@ -0,0 +1,62 @@
+# 风险归并Skill 设计
+
+## 1. Skill 定位
+
+`风险归并Skill` 负责合并重复风险、关联同根因风险，并生成可排序的风险组。
+
+英文实现标识建议使用 `RiskMergeSkill`。
+
+## 2. 输入
+
+```python
+@dataclass
+class RiskMergeInput:
+    risk_items: list[RiskItem]
+```
+
+## 3. 输出
+
+```python
+@dataclass
+class RiskMergeOutput:
+    merged_risk_items: list[RiskItem]
+    risk_groups: list[RiskGroup]
+```
+
+## 4. 核心方法
+
+### 4.1 `run(input) -> RiskMergeOutput`
+
+主入口方法。
+
+### 4.2 `build_fingerprint(risk_item) -> str`
+
+生成风险指纹。
+
+### 4.3 `merge_duplicates(items) -> list[RiskItem]`
+
+合并重复风险。
+
+### 4.4 `link_related(items) -> list[RiskGroup]`
+
+关联同根因风险。
+
+## 5. 技术实现
+
+使用技术：
+
+1. Python 分组
+2. 风险指纹
+3. 关联规则
+
+## 6. 异常处理
+
+1. 风险项为空：返回空集合。
+2. 风险缺少关键字段：不合并并记录警告。
+
+## 7. 测试要点
+
+1. 重复风险可合并。
+2. 产品名称冲突和混档风险可关联。
+3. 空风险列表可处理。
+

docs/详细设计/skill/风险报告生成Skill.md

@@ -0,0 +1,88 @@
+# 风险报告生成Skill 设计
+
+## 1. Skill 定位
+
+`风险报告生成Skill` 负责将风险项、准入判定和整改建议组装成稳定的 `registration_risk_report`，并生成页面展示、审计和飞书通知载荷。
+
+英文实现标识建议使用 `RiskReportBuildSkill`。
+
+## 2. 输入
+
+```python
+@dataclass
+class RiskReportBuildInput:
+    context: RiskEvaluationContext
+    risk_items: list[RiskItem]
+    admission_decision: AdmissionDecisionOutput
+    suggestions: list[dict]
+    owner_notifications: list[dict]
+```
+
+## 3. 输出
+
+```python
+@dataclass
+class RiskReportBuildOutput:
+    report: dict
+    display_sections: list[dict]
+    audit_payload: dict
+    feishu_notification_payload: dict
+```
+
+## 4. 报告结构
+
+报告必须包含：
+
+1. `report_type`
+2. `batch_id`
+3. `risk_rule_id`
+4. `summary`
+5. `risk_items`
+6. `manual_review_items`
+7. `suggestions`
+8. `owner_notifications`
+
+## 5. 核心方法
+
+### 5.1 `run(input) -> RiskReportBuildOutput`
+
+主入口方法。
+
+### 5.2 `build_summary(risk_items, admission) -> dict`
+
+生成汇总。
+
+### 5.3 `build_display_sections(report) -> list[dict]`
+
+生成页面展示区块。
+
+### 5.4 `build_audit_payload(report, context) -> dict`
+
+生成审计载荷。
+
+### 5.5 `build_feishu_payload(report) -> dict`
+
+生成飞书通知载荷。
+
+## 6. 技术实现
+
+使用技术：
+
+1. dataclass/Pydantic
+2. JSONField
+3. Audit 服务
+4. 飞书消息 payload schema
+
+## 7. 异常处理
+
+1. 风险项为空：输出通过报告。
+2. 审计失败：报告返回并记录系统警告。
+3. 飞书载荷生成失败：不影响 Web 报告。
+
+## 8. 测试要点
+
+1. 报告 schema 稳定。
+2. 汇总数量正确。
+3. 审计载荷包含规则版本。
+4. 飞书载荷包含高风险摘要。
+

docs/详细设计/skill/风险规则加载Skill.md

@@ -0,0 +1,64 @@
+# 风险规则加载Skill 设计
+
+## 1. Skill 定位
+
+`风险规则加载Skill` 负责加载风险分级、准入规则、责任角色映射和整改建议模板。
+
+英文实现标识建议使用 `RiskRuleLoadSkill`。
+
+## 2. 输入
+
+```python
+@dataclass
+class RiskRuleLoadInput:
+    risk_rule_id: str
+```
+
+## 3. 输出
+
+```python
+@dataclass
+class RiskRuleLoadOutput:
+    risk_rule_id: str
+    version: str
+    risk_type_rules: dict
+    admission_rules: dict
+    owner_role_mapping: dict
+    suggestion_templates: dict
+```
+
+## 4. 核心方法
+
+### 4.1 `run(input) -> RiskRuleLoadOutput`
+
+主入口方法。
+
+### 4.2 `load_rule_file(risk_rule_id) -> dict`
+
+读取 YAML。
+
+### 4.3 `validate_rules(raw_rules) -> RiskRuleValidationResult`
+
+校验规则完整性。
+
+## 5. 技术实现
+
+使用技术：
+
+1. YAML
+2. Pydantic
+3. Django cache
+
+## 6. 异常处理
+
+1. 规则不存在：任务失败。
+2. 准入规则缺失：校验失败。
+3. 责任角色缺失：使用默认角色并警告。
+
+## 7. 测试要点
+
+1. 规则加载成功。
+2. 准入规则可读取。
+3. 责任角色映射可读取。
+4. 缺失规则时报错。
+

docs/详细设计/skill/风险项生成Skill.md

@@ -0,0 +1,66 @@
+# 风险项生成Skill 设计
+
+## 1. Skill 定位
+
+`风险项生成Skill` 负责从前序报告中提取风险事实，并按照风险规则生成标准化风险项。
+
+英文实现标识建议使用 `RiskItemBuildSkill`。
+
+## 2. 输入
+
+```python
+@dataclass
+class RiskItemBuildInput:
+    reports: dict[str, dict]
+    risk_rules: dict
+```
+
+## 3. 输出
+
+```python
+@dataclass
+class RiskItemBuildOutput:
+    risk_items: list[RiskItem]
+    manual_review_items: list[dict]
+    warnings: list[dict]
+```
+
+## 4. 核心方法
+
+### 4.1 `run(input) -> RiskItemBuildOutput`
+
+主入口方法。
+
+### 4.2 `build_from_completeness(report) -> list[RiskItem]`
+
+从缺失、错放、待复核生成风险。
+
+### 4.3 `build_from_field_extraction(report) -> list[RiskItem]`
+
+从字段缺失、低可信、抽取失败生成风险。
+
+### 4.4 `build_from_consistency(report) -> list[RiskItem]`
+
+从字段冲突、混档风险生成风险。
+
+## 5. 技术实现
+
+使用技术：
+
+1. 前序报告 schema
+2. 风险规则映射
+3. dataclass/Pydantic
+
+## 6. 异常处理
+
+1. 报告缺失：生成报告缺失警告。
+2. 风险类型未配置：使用中风险并警告。
+3. 证据缺失：风险仍生成，但标记证据不足。
+
+## 7. 测试要点
+
+1. 缺失项生成风险。
+2. 字段冲突生成风险。
+3. 混档生成高风险。
+4. 手工复核项被保留。
+

docs/详细设计/skill/风险预警编排Skill.md

@@ -0,0 +1,90 @@
+# 风险预警编排Skill 设计
+
+## 1. Skill 定位
+
+`风险预警编排Skill` 是第五步工作流的总入口 Skill，负责组织前序报告汇总、风险规则加载、风险项生成、风险归并、准入判定、整改建议生成和风险报告输出。
+
+英文实现标识建议使用 `RiskWarningOrchestrateSkill`。
+
+## 2. 输入
+
+```python
+@dataclass
+class RiskWarningOrchestrateInput:
+    batch_id: int
+    scenario_id: str = "registration_risk_report"
+    risk_rule_id: str = "ivd_registration_risk_v1"
+    include_reports: list[str] = field(default_factory=list)
+    enable_llm_summary: bool = True
+```
+
+## 3. 输出
+
+```python
+@dataclass
+class RiskWarningOrchestrateOutput:
+    report_type: str
+    batch_id: int
+    summary: dict
+    risk_items: list[dict]
+    manual_review_items: list[dict]
+    suggestions: list[dict]
+    audit_id: int | None = None
+```
+
+## 4. 依赖 Skill
+
+1. `前序报告汇总Skill`
+2. `风险规则加载Skill`
+3. `风险项生成Skill`
+4. `风险归并Skill`
+5. `准入判定Skill`
+6. `整改建议生成Skill`
+7. `风险报告生成Skill`
+
+## 5. 核心方法
+
+### 5.1 `run(input) -> RiskWarningOrchestrateOutput`
+
+主入口方法。
+
+### 5.2 `load_execution_context(input) -> RiskEvaluationContext`
+
+加载批次、场景和前序报告上下文。
+
+### 5.3 `merge_results(risks, admission, suggestions) -> dict`
+
+合并风险、准入和建议。
+
+## 6. 技术实现
+
+使用技术：
+
+1. Tool Registry
+2. dataclass/Pydantic
+3. Django ORM
+4. Audit 服务
+
+建议注册名：
+
+```python
+tool_registry.register(
+    name="risk_warning_orchestrate",
+    handler=RiskWarningOrchestrateSkill().run,
+)
+```
+
+## 7. 异常处理
+
+1. 前序报告缺失：输出业务提示。
+2. 风险规则缺失：任务失败。
+3. LLM 不可用：使用模板摘要。
+4. 审计写入失败：报告返回并记录系统警告。
+
+## 8. 测试要点
+
+1. 能串联所有依赖 Skill。
+2. 高风险导致不通过。
+3. 前序报告缺失时提示清晰。
+4. 输出报告 schema 稳定。
+