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

2026-06-03 21:08:15 +08:00
parent 0e49eea683
commit 2876a1b028
9 changed files with 1055 additions and 0 deletions
--- a/docs/详细设计/skill/准入判定Skill.md
+++ b/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. 无风险通过。
+
--- a/docs/详细设计/skill/前序报告汇总Skill.md
+++ b/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 稳定。
+
--- a/docs/详细设计/skill/整改建议生成Skill.md
+++ b/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 不可用时本地摘要可用。
+
--- a/docs/详细设计/skill/风险归并Skill.md
+++ b/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. 空风险列表可处理。
+
--- a/docs/详细设计/skill/风险报告生成Skill.md
+++ b/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. 飞书载荷包含高风险摘要。
+
--- a/docs/详细设计/skill/风险规则加载Skill.md
+++ b/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. 缺失规则时报错。
+
--- a/docs/详细设计/skill/风险项生成Skill.md
+++ b/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. 手工复核项被保留。
+
--- a/docs/详细设计/skill/风险预警编排Skill.md
+++ b/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 稳定。
+