feat: 新增风险图谱算法与系统仪表盘及操作反馈体系
后端新增风险图谱算法模块、风险观察与反馈服务、规则 DSL 校验器和可解释性引擎，完善系统仪表盘和财务仪表盘统计， 优化 agent 运行和编排执行链路，清理旧开发文档，前端新增 系统趋势、负载热力图等多种仪表盘图表组件，完善操作反馈 对话框和工作台日期选择器，优化报销创建和审批详情交互， 补充单元测试覆盖。
This commit is contained in:
caoxiaozhu
546
document/development/risk-rule-explainable-flow/CONCEPT.md
Normal file
546
document/development/risk-rule-explainable-flow/CONCEPT.md
Normal file
@@ -0,0 +1,546 @@
|
||||
# 风险规则可解释流程判断改造方案
|
||||
|
||||
## 功能一句话
|
||||
|
||||
把风险规则从“自然语言生成一段 JSON”升级为“自然语言、字段本体、可执行 JSON DSL、流程判断图、测试命中路径、版本修改”一致闭环，让业务用户能看懂规则怎么判断，让系统按同一套逻辑执行。
|
||||
|
||||
## 背景与问题
|
||||
|
||||
当前风险规则已经具备自然语言创建、JSON 风险规则、风险评分、详情页流程图、仿真测试和上线启用能力，但仍有几个关键缺口：
|
||||
|
||||
- 规则解释不够稳定。用户输入复杂业务规则后，系统可能把“城市是否一致、日期是否越界、是否存在合理说明”解释成“是否出现关键词”，这会导致业务语义失真。
|
||||
- 流程图容易变成展示装饰。如果流程图不严格从可执行 JSON DSL 派生，就会出现“页面看起来是 A，后端实际执行是 B”的问题。
|
||||
- 测试结果缺少路径解释。用户上传票据和输入意图后，需要知道系统识别到了哪些字段、走过哪些判断节点、为什么命中或未命中。
|
||||
- 规则修改缺少版本化闭环。已上线规则不能直接覆盖，应创建修订版本，旧版本继续生效，新版本测试通过后再替换。
|
||||
- 常见费控规则需要模板化扩展。预算、票据、差旅、招待、采购/AP、企业卡等规则应进入规则模板库，但仍必须走同一套解释和执行链路。
|
||||
|
||||
## 目标与非目标
|
||||
|
||||
### 目标
|
||||
|
||||
- [G1] 自然语言规则经过 Hermes 语义理解后，生成结构稳定、可校验、可执行的 JSON DSL。
|
||||
- [G2] 流程判断图必须由 JSON DSL 派生，不能直接由自然语言单独生成。
|
||||
- [G3] 详情页展示“文字流程解释 + 流程图 + 使用字段 + 风险分数 + 规则状态”，让业务用户能确认系统理解是否正确。
|
||||
- [G4] 测试规则时展示本次样例或票据仿真的字段识别结果、判断路径、命中节点和最终结论。
|
||||
- [G5] 用户觉得规则不合理时，通过“创建修订版本”修改，线上版本保持稳定。
|
||||
- [G6] 常见费控规则模板库可以复用同一套 DSL、流程图和测试机制。
|
||||
|
||||
### 非目标
|
||||
|
||||
- [NG1] 本期不做流程图编辑器，不允许拖拽、改节点、缩放编辑或在线画图。
|
||||
- [NG2] 本期不让大模型作为风险命中裁判。Hermes 只负责理解、生成、解释和辅助解析，最终命中由规则执行器决定。
|
||||
- [NG3] 本期不把所有复杂政策一次性建成完整专家系统，先保证规则表达、解释和执行一致。
|
||||
- [NG4] 本期不直接覆盖已上线规则，所有线上修改都走修订版本。
|
||||
|
||||
## 用户与场景
|
||||
|
||||
- 财务规则制定者：创建风险规则，查看系统理解是否正确，修改草稿规则。
|
||||
- 高级财务人员 / admin：审核、上线、下线、启用、停用、删除未发布规则。
|
||||
- 普通报销用户：在真实业务命中风险时看到简明原因，可反馈误判或漏判。
|
||||
- 系统执行链路：报销、费用申请、预算占用、票据识别、采购/AP 等场景只加载已上线且已启用的规则。
|
||||
|
||||
核心场景：
|
||||
|
||||
1. 新建规则：输入规则标题、费用业务环节、费用领域、是否需要附件、自然语言规则。
|
||||
2. 生成规则：Hermes 结合字段本体输出 JSON DSL、业务说明、风险评分、流程模型和 SVG。
|
||||
3. 查看详情：用户确认“系统理解的字段、判断条件、例外说明、命中动作”是否正确。
|
||||
4. 仿真测试：用户上传附件并输入测试意图，系统统一识别字段，再由执行器判断当前规则。
|
||||
5. 修改规则：未上线规则直接编辑；已上线规则创建修订版本，测试通过后发布替换。
|
||||
|
||||
## 功能能力
|
||||
|
||||
### C1. 自然语言输入能力
|
||||
|
||||
新建风险规则表单应包含：
|
||||
|
||||
- 规则标题。
|
||||
- 业务环节：费用申请、报销、预算控制、付款/采购等。
|
||||
- 费用领域：差旅、住宿、交通、招待、办公、培训、会议、软件服务、通讯、福利、预算、发票、采购/AP、通用。
|
||||
- 是否需要附件：需要时测试弹窗开放附件上传；不需要时隐藏上传入口。
|
||||
- 自然语言规则描述。
|
||||
|
||||
风险等级不允许用户手动选择，由评分模型输出风险分数和等级。
|
||||
|
||||
### C2. 语义理解与字段本体映射
|
||||
|
||||
Hermes 需要输出一份中间语义计划，而不是直接写死 JSON：
|
||||
|
||||
- 规则意图：判断什么业务风险。
|
||||
- 适用范围：业务环节、费用领域、费用科目、单据类型。
|
||||
- 所需字段：中文解释、英文字段名、来源、是否必填。
|
||||
- 票据字段：OCR 或文档智能识别得到的城市、日期、金额、销售方、发票号等。
|
||||
- 判断步骤：按顺序表达条件、分支、例外说明和命中动作。
|
||||
- 例外条件：例如延期、改签、跨城办事、临时任务等说明。
|
||||
- 风险动作：提醒、人工复核、要求补充说明、退回修改、禁止提交。
|
||||
|
||||
字段展示统一为：
|
||||
|
||||
```text
|
||||
申报目的地[claim.destination_city]
|
||||
明细发生地点[item.location_city]
|
||||
交通票行程城市[receipt.transport_route_cities]
|
||||
住宿发票城市[receipt.hotel_city]
|
||||
出差开始日期[trip.start_date]
|
||||
出差结束日期[trip.end_date]
|
||||
报销事由[claim.reason]
|
||||
```
|
||||
|
||||
### C3. 可执行 JSON DSL
|
||||
|
||||
JSON DSL 应表达规则执行逻辑，而不是保存自然语言摘要。建议基本结构：
|
||||
|
||||
```json
|
||||
{
|
||||
"rule_id": "risk.travel.city_mismatch",
|
||||
"version": "v1",
|
||||
"scope": {
|
||||
"business_stage": "reimbursement",
|
||||
"expense_types": ["travel", "lodging"]
|
||||
},
|
||||
"required_fields": [
|
||||
{
|
||||
"label": "申报目的地",
|
||||
"field": "claim.destination_city",
|
||||
"source": "claim",
|
||||
"required": true
|
||||
}
|
||||
],
|
||||
"conditions": {
|
||||
"all": [
|
||||
{
|
||||
"op": "in_scope",
|
||||
"field": "expense.type",
|
||||
"values": ["travel", "lodging"]
|
||||
},
|
||||
{
|
||||
"op": "any_present",
|
||||
"fields": [
|
||||
"receipt.transport_route_cities",
|
||||
"receipt.hotel_city",
|
||||
"item.location_city"
|
||||
]
|
||||
},
|
||||
{
|
||||
"op": "none_match",
|
||||
"left_fields": [
|
||||
"receipt.transport_route_cities",
|
||||
"receipt.hotel_city"
|
||||
],
|
||||
"right_fields": [
|
||||
"claim.destination_city",
|
||||
"item.location_city",
|
||||
"trip.route_cities"
|
||||
],
|
||||
"matcher": "city_equivalent"
|
||||
},
|
||||
{
|
||||
"op": "not_contains_any",
|
||||
"field": "claim.reason",
|
||||
"values": ["延期", "改签", "跨城办事", "临时任务", "绕行"]
|
||||
}
|
||||
]
|
||||
},
|
||||
"action": {
|
||||
"risk_level": "high",
|
||||
"risk_score": 76,
|
||||
"decision": "review_required",
|
||||
"message": "票据城市与申报目的地或行程城市不一致，且未说明合理原因。"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
核心要求：
|
||||
|
||||
- 城市、日期、金额、人员、供应商等字段必须使用专门比较算子，不能退化成“关键词出现”。
|
||||
- 复杂规则允许多层条件组合：`all`、`any`、`not`、`branch`、`exists`、`range`、`compare`、`semantic_contains`。
|
||||
- 例外说明可以使用语义包含，但只能影响“是否进入复核/降级/豁免”，不能替代结构化字段判断。
|
||||
- DSL 生成后必须通过 schema 校验和执行器 dry-run。
|
||||
|
||||
### C4. 流程判断图
|
||||
|
||||
流程图不是编辑器，也不是自然语言插图。流程图必须由 JSON DSL 转换成 `flow_model`，再生成 SVG。
|
||||
|
||||
建议 `flow_model`：
|
||||
|
||||
```json
|
||||
{
|
||||
"nodes": [
|
||||
{
|
||||
"id": "start",
|
||||
"type": "start",
|
||||
"title": "开始",
|
||||
"description": "进入差旅住宿报销风险检查"
|
||||
},
|
||||
{
|
||||
"id": "scope",
|
||||
"type": "decision",
|
||||
"title": "是否属于差旅住宿报销",
|
||||
"fields": ["expense.type", "claim.business_stage"]
|
||||
},
|
||||
{
|
||||
"id": "city_match",
|
||||
"type": "decision",
|
||||
"title": "票据城市是否匹配申报或行程城市",
|
||||
"fields": [
|
||||
"receipt.hotel_city",
|
||||
"receipt.transport_route_cities",
|
||||
"claim.destination_city",
|
||||
"trip.route_cities"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "hit",
|
||||
"type": "risk",
|
||||
"title": "命中高风险",
|
||||
"description": "要求补充行程说明或退回修改"
|
||||
}
|
||||
],
|
||||
"edges": [
|
||||
{ "from": "start", "to": "scope", "label": "开始检查" },
|
||||
{ "from": "scope", "to": "end_pass", "label": "否" },
|
||||
{ "from": "scope", "to": "city_match", "label": "是" },
|
||||
{ "from": "city_match", "to": "end_pass", "label": "是" },
|
||||
{ "from": "city_match", "to": "hit", "label": "否" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
流程图展示要求：
|
||||
|
||||
- 详情页左侧为文字流程解释，右侧为“流程图”。
|
||||
- 判断分支用“是 / 否 / 通过 / 不通过 / 缺失 / 存在”等明确标签。
|
||||
- 风险命中框使用风险等级颜色：低风险蓝色，中风险橙色，高风险红色，极高风险深红色。
|
||||
- 普通节点保持 SaaS 白底、细边框、低饱和样式，不能整张图都染成风险色。
|
||||
- 图只做展示，不响应拖拽、编辑、缩放和节点点击。
|
||||
- 节点数量超过 8 个时，需要自动压缩文字、合并说明节点或分页展示，避免图过大。
|
||||
|
||||
### C5. 测试命中路径
|
||||
|
||||
测试规则弹窗应展示三类信息：
|
||||
|
||||
1. 输入与识别结果
|
||||
- 用户自然语言测试意图。
|
||||
- 上传附件清单。
|
||||
- OCR / 文档智能识别字段。
|
||||
- Hermes 辅助规范化后的结构化字段。
|
||||
|
||||
2. 规则执行结果
|
||||
- 是否进入适用范围。
|
||||
- 每个判断节点的输入值、比较方式、判断结果。
|
||||
- 命中的风险动作。
|
||||
- 未命中的原因。
|
||||
|
||||
3. 流程图路径高亮
|
||||
- 使用同一个 `flow_model`。
|
||||
- 本次执行走过的节点和边由执行器输出 `trace`。
|
||||
- 前端按 `trace` 高亮路径。
|
||||
|
||||
执行 trace 示例：
|
||||
|
||||
```json
|
||||
{
|
||||
"trace_id": "run_001",
|
||||
"matched": true,
|
||||
"risk_level": "high",
|
||||
"risk_score": 76,
|
||||
"steps": [
|
||||
{
|
||||
"node_id": "scope",
|
||||
"result": true,
|
||||
"inputs": {
|
||||
"expense.type": "住宿费",
|
||||
"claim.business_stage": "reimbursement"
|
||||
}
|
||||
},
|
||||
{
|
||||
"node_id": "city_match",
|
||||
"result": false,
|
||||
"inputs": {
|
||||
"receipt.hotel_city": "北京",
|
||||
"claim.destination_city": "上海",
|
||||
"trip.route_cities": ["武汉", "上海"]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### C6. 规则修改与版本化
|
||||
|
||||
规则修改分三种：
|
||||
|
||||
- 未上线规则：允许创建者或 admin 直接编辑，保存后重新生成 DSL、流程图、评分和说明。
|
||||
- 已上线规则：不允许直接覆盖，必须点击“创建修订版本”。
|
||||
- 业务用户反馈：只能提交误判/漏判反馈，由管理员决定是否创建修订版本。
|
||||
|
||||
已上线规则修改流程：
|
||||
|
||||
```text
|
||||
线上版本 active
|
||||
↓
|
||||
创建修订版本 draft_revision
|
||||
↓
|
||||
编辑自然语言 / 参数 / 附件要求
|
||||
↓
|
||||
重新生成 JSON DSL + 流程图 + 评分
|
||||
↓
|
||||
仿真测试通过
|
||||
↓
|
||||
发布新版本
|
||||
↓
|
||||
旧版本归档，新版本 active
|
||||
```
|
||||
|
||||
版本记录必须包含：
|
||||
|
||||
- 修改人。
|
||||
- 修改原因。
|
||||
- 修改前后自然语言差异。
|
||||
- 修改前后 DSL 差异。
|
||||
- 测试报告。
|
||||
- 发布时间。
|
||||
- 是否替换线上版本。
|
||||
|
||||
## 方案设计
|
||||
|
||||
### 总体链路
|
||||
|
||||
```text
|
||||
自然语言规则
|
||||
↓
|
||||
字段本体召回与业务域约束
|
||||
↓
|
||||
Hermes 生成语义计划 semantic_plan
|
||||
↓
|
||||
语义计划校验与补全
|
||||
↓
|
||||
生成 JSON DSL
|
||||
↓
|
||||
Schema 校验 + 执行器 dry-run
|
||||
↓
|
||||
风险评分 risk_score / risk_level
|
||||
↓
|
||||
DSL 转 flow_model
|
||||
↓
|
||||
flow_model 转 flow_diagram_svg
|
||||
↓
|
||||
详情展示 + 仿真测试 + 上线执行
|
||||
```
|
||||
|
||||
### 前端设计
|
||||
|
||||
涉及入口：
|
||||
|
||||
- `AuditRuleDialogs.vue`：新建风险规则表单，后续增加修订版本编辑入口。
|
||||
- `AuditJsonRiskRuleDetail.vue`：详情页展示基本信息、测试状态、流程解释、流程图、操作按钮。
|
||||
- `RiskRuleFlowDiagram.vue`：只负责展示 SVG 或由 `flow_model` 派生的静态图，不做编辑。
|
||||
- `RiskRuleTestDialog.vue`：仿真测试窗口，展示输入识别、执行路径、测试报告。
|
||||
- `auditViewRiskRuleModel.js` / `auditViewModel.js`：规则详情视图模型、列表字段和状态映射。
|
||||
|
||||
详情页建议结构：
|
||||
|
||||
```text
|
||||
Topbar：规则标题、状态、风险分数、风险等级、上线/启用状态
|
||||
|
||||
基本信息：费用领域、业务环节、附件要求、创建人、上线时间、最后操作、测试状态
|
||||
|
||||
判断流程：
|
||||
左侧：文字流程解释
|
||||
右侧：流程图
|
||||
|
||||
测试与版本：
|
||||
最近测试报告
|
||||
修订版本 / 历史版本
|
||||
操作按钮
|
||||
```
|
||||
|
||||
修改规则界面建议采用左右布局：
|
||||
|
||||
- 左侧：自然语言规则编辑、规则标题、费用领域、附件要求。
|
||||
- 右侧：系统解释预览，包括字段、本体映射、流程解释、风险分数。
|
||||
- 底部：重新生成、保存草稿、测试规则、提交上线。
|
||||
|
||||
### 后端设计
|
||||
|
||||
已有相关模块应优先复用：
|
||||
|
||||
- `risk_rule_generation.py`：规则生成主流程。
|
||||
- `risk_rule_generation_prompt.py`：Hermes 提示词。
|
||||
- `risk_rule_generation_ontology.py`：字段本体和费用领域约束。
|
||||
- `risk_rule_generation_semantics.py`：自然语言语义解释。
|
||||
- `risk_rule_generation_interpreter.py`：解释结果到 DSL。
|
||||
- `risk_rule_scoring.py`：风险评分。
|
||||
- `risk_rule_flow_diagram.py`：流程图 SVG 生成。
|
||||
- `risk_rule_manifest_normalizer.py`：规则 manifest 规范化。
|
||||
- `risk_rule_template_executor.py`：规则执行器。
|
||||
- `agent_asset_risk_rule_testing.py`：规则测试、删除、发布、启用。
|
||||
- `agent_asset_risk_rule_simulation.py`：仿真测试对话。
|
||||
|
||||
后端需要补齐的能力：
|
||||
|
||||
- 生成 `semantic_plan` 并持久化到 `config_json` 或版本内容中。
|
||||
- 生成并持久化 `flow_model`，再生成 `flow_diagram_svg`。
|
||||
- 执行器输出 `trace`，用于测试解释和流程图高亮。
|
||||
- 支持创建修订版本，避免直接覆盖 active 版本。
|
||||
- 支持从常见模板创建规则，模板也走同一套生成和校验链路。
|
||||
|
||||
### 接口设计
|
||||
|
||||
建议新增或调整：
|
||||
|
||||
```text
|
||||
POST /agent-assets/risk-rules/generate
|
||||
根据自然语言创建生成任务，返回生成中资产。
|
||||
|
||||
POST /agent-assets/{asset_id}/risk-rules/regenerate
|
||||
对草稿或修订版本重新生成 DSL、评分和流程图。
|
||||
|
||||
POST /agent-assets/{asset_id}/risk-rules/revisions
|
||||
基于已上线规则创建修订版本。
|
||||
|
||||
PATCH /agent-assets/{asset_id}/risk-rules/draft
|
||||
保存未上线规则或修订版本的编辑内容。
|
||||
|
||||
POST /agent-assets/{asset_id}/risk-rule-tests/simulate
|
||||
独立仿真测试，返回字段识别、执行结果、trace。
|
||||
|
||||
GET /agent-assets/{asset_id}/risk-rule-tests/latest
|
||||
返回最近测试摘要。
|
||||
|
||||
POST /agent-assets/{asset_id}/publish
|
||||
发布通过测试的规则版本。
|
||||
```
|
||||
|
||||
### 数据设计
|
||||
|
||||
建议在风险规则版本内容或 `config_json` 中保留：
|
||||
|
||||
```json
|
||||
{
|
||||
"source_text": "用户输入的自然语言规则",
|
||||
"semantic_plan": {},
|
||||
"dsl": {},
|
||||
"flow_model": {},
|
||||
"flow_diagram_svg": "<svg>...</svg>",
|
||||
"flow_explanation": [],
|
||||
"risk_score": 76,
|
||||
"risk_level": "high",
|
||||
"required_attachment": true,
|
||||
"required_fields": [],
|
||||
"last_operation": {
|
||||
"action": "publish",
|
||||
"actor": "admin",
|
||||
"at": "2026-05-30T10:00:00+08:00"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
测试记录保留：
|
||||
|
||||
```json
|
||||
{
|
||||
"test_type": "simulation",
|
||||
"input_text": "我去北京出差 3 天，上传武汉到上海车票",
|
||||
"attachments": [],
|
||||
"recognized_fields": {},
|
||||
"normalized_fields": {},
|
||||
"execution_result": {},
|
||||
"trace": {},
|
||||
"passed": true,
|
||||
"tester": "admin",
|
||||
"tested_at": "2026-05-30T10:10:00+08:00"
|
||||
}
|
||||
```
|
||||
|
||||
## 算法与公式
|
||||
|
||||
### 风险评分
|
||||
|
||||
风险评分由模型辅助判断，但必须结构化输出。建议使用可解释加权模型：
|
||||
|
||||
$$
|
||||
score = \min(100, base + \sum_{i=1}^{n} w_i x_i + c + e)
|
||||
$$
|
||||
|
||||
变量说明：
|
||||
|
||||
- $base$：业务领域基础风险分。预算、发票、付款类通常高于普通提示类。
|
||||
- $x_i$：风险因子是否存在或强度，例如金额影响、附件缺失、字段冲突、越权、历史重复。
|
||||
- $w_i$：风险因子权重。
|
||||
- $c$：复杂度修正，例如多字段交叉、跨单据、跨时间窗口、跨附件识别。
|
||||
- $e$：例外说明修正。存在合理说明时可降低，但不能直接清零。
|
||||
|
||||
等级映射：
|
||||
|
||||
- 0-30：低风险。
|
||||
- 31-60：中风险。
|
||||
- 61-80：高风险。
|
||||
- 81-100：极高风险。
|
||||
|
||||
### 流程复杂度控制
|
||||
|
||||
为了避免流程图过大，建议定义流程复杂度：
|
||||
|
||||
$$
|
||||
complexity = node_count + 0.5 \times edge_count + branch_count
|
||||
$$
|
||||
|
||||
处理规则：
|
||||
|
||||
- `complexity <= 12`：单图展示。
|
||||
- `12 < complexity <= 20`：合并说明节点，保留关键判断。
|
||||
- `complexity > 20`：详情页展示主流程，测试弹窗展示完整 trace。
|
||||
|
||||
## 测试方案
|
||||
|
||||
### 单元测试
|
||||
|
||||
- 语义计划生成：复杂差旅城市规则不能退化为关键词判断。
|
||||
- DSL schema 校验：缺字段、非法算子、空 action 必须失败。
|
||||
- 执行器：城市匹配、日期范围、金额阈值、附件缺失、例外说明。
|
||||
- 流程转换：同一 DSL 生成稳定的 `flow_model` 和 SVG。
|
||||
- 风险评分：低/中/高/极高边界分数。
|
||||
|
||||
### 接口测试
|
||||
|
||||
- 新建规则返回生成中资产。
|
||||
- 生成完成后包含 `dsl`、`flow_model`、`flow_diagram_svg`、`risk_score`。
|
||||
- 仿真测试返回 `recognized_fields`、`normalized_fields`、`trace`。
|
||||
- 未测试通过的规则不能发布。
|
||||
- 已上线规则创建修订版本，不覆盖线上版本。
|
||||
|
||||
### 前端测试
|
||||
|
||||
- 新建弹窗不再选择风险等级。
|
||||
- 详情页展示风险分数、流程解释、流程图。
|
||||
- 流程图不可点击、不可拖拽、无工具栏。
|
||||
- 测试弹窗显示字段识别结果和判断路径。
|
||||
- 已上线规则只能创建修订版本修改。
|
||||
|
||||
### 容器验证
|
||||
|
||||
后续开发验证默认在 Docker 容器内执行：
|
||||
|
||||
```bash
|
||||
docker exec x-financial-main sh -lc "cd /app/server && pytest <target> --timeout=60"
|
||||
docker exec x-financial-main sh -lc "cd /app/web && npm run build"
|
||||
```
|
||||
|
||||
## 指标与验收
|
||||
|
||||
- [A1] 新建复杂差旅规则后，详情页流程解释不能出现“检查是否包含风险关键词”这类错误表达。
|
||||
- [A2] 详情页流程图与 JSON DSL 条件数量、分支方向、命中动作一致。
|
||||
- [A3] 仿真测试能显示票据识别字段，并说明为什么命中或未命中。
|
||||
- [A4] 同一条测试样例的执行 trace 可以高亮流程图路径。
|
||||
- [A5] 已上线规则修改时不会改变当前线上执行结果，只有发布修订版本后才替换。
|
||||
- [A6] 低、中、高、极高风险都能由评分模型产出，不应默认集中在中高风险。
|
||||
- [A7] 前端构建通过，后端定向测试 60s 内完成。
|
||||
|
||||
## 风险与开放问题
|
||||
|
||||
- LLM 语义理解仍可能出错，因此必须有 schema 校验、执行器 dry-run、详情解释和仿真测试兜底。
|
||||
- 字段本体不完整会限制规则表达，需要持续扩展费用、票据、预算、采购/AP 字段。
|
||||
- 复杂规则可能产生过大的流程图，需要主流程和完整 trace 分层展示。
|
||||
- 老规则没有 `semantic_plan` 或 `flow_model`，需要兼容展示并允许重新生成。
|
||||
- 常见规则模板要避免写成定制逻辑。模板只能提供默认文本、字段和 DSL 样例，最终仍走通用生成链路。
|
||||
|
||||
96
document/development/risk-rule-explainable-flow/TODO.md
Normal file
96
document/development/risk-rule-explainable-flow/TODO.md
Normal file
@@ -0,0 +1,96 @@
|
||||
# 风险规则可解释流程判断改造 TODO
|
||||
|
||||
## 使用规则
|
||||
|
||||
- 每个 TODO 对应 `CONCEPT.md` 的目标、能力或验收点。
|
||||
- 只有真实完成并通过相应验证后，才能把 `[ ]` 改成 `[x]`。
|
||||
- 如果实现中发现需求变化，先更新 `CONCEPT.md`，再调整本 TODO。
|
||||
- 后端和构建验证默认在 Docker 容器 `x-financial-main` 的 `/app` 下执行。
|
||||
|
||||
## 1. 调研与边界
|
||||
|
||||
- [ ] [CONCEPT: 背景与问题] 梳理当前风险规则生成链路，记录 `risk_rule_generation.py` 到 `risk_rule_template_executor.py` 的真实调用关系。
|
||||
- [ ] [CONCEPT: 前端设计] 梳理详情页、新建弹窗、测试弹窗当前字段来源，记录 `AuditRuleDialogs.vue`、`AuditJsonRiskRuleDetail.vue`、`RiskRuleTestDialog.vue` 的改造点。
|
||||
- [ ] [CONCEPT: 数据设计] 确认 `AgentAssetRead`、版本内容、`config_json` 中已有字段，确定 `semantic_plan`、`flow_model`、`flow_diagram_svg` 的落点。
|
||||
- [ ] [CONCEPT: 非目标] 明确本期不做流程图编辑器，不增加拖拽、缩放、节点编辑能力。
|
||||
|
||||
## 2. 语义计划与 DSL 契约
|
||||
|
||||
- [x] [CONCEPT: C2] 定义 `semantic_plan` schema，包含规则意图、适用范围、字段本体映射、判断步骤、例外条件和风险动作。证据：`risk_rule_explainability.py` 产出 `semantic_plan`，`test_risk_rule_explainability.py` 已验证。
|
||||
- [x] [CONCEPT: C3] 定义 JSON DSL schema，补齐城市、日期、金额、附件、语义说明等通用算子。证据：`risk_rule_dsl_validator.py` 定义受控 DSL 校验，`risk_rule_generation_interpreter.py` 补充 `numeric_compare`，`risk_rule_template_executor.py` 支持日期、字段集合、附件存在性、文本例外和数值比较算子。
|
||||
- [x] [CONCEPT: C3] 增加 DSL validator，禁止复杂字段判断退化为“风险关键词匹配”。证据：`validate_risk_rule_draft` 会将城市一致性关键词规则改写为结构化比较，将预算金额关键词规则改写为 `composite_rule_v1`，`test_risk_rule_dsl_validator.py` 覆盖。
|
||||
- [x] [CONCEPT: C3] 为差旅城市不一致、住宿日期越界、预算阈值、重复发票各准备一条 DSL 样例。证据：新增 `risk_rule_dsl_examples.py`，并通过 `test_risk_rule_dsl_examples.py` 覆盖四类样例的 validator 与执行器命中/未命中回归。
|
||||
- [x] [CONCEPT: C2] 字段展示统一为 `中文[英文]` 格式，并复用字段本体解释。证据：`risk_rule_explainability.py` 的 `semantic_plan.required_fields.display` 使用字段本体生成 `label[key]`。
|
||||
|
||||
## 3. Hermes 生成链路
|
||||
|
||||
- [x] [CONCEPT: 总体链路] 调整 `risk_rule_generation_prompt.py`，要求 Hermes 先输出 `semantic_plan`，再输出 DSL。证据：提示词 `required_json_shape` 改为 `{ semantic_plan, dsl }`，`test_prompt_requires_semantic_plan_then_dsl` 验证。
|
||||
- [x] [CONCEPT: C2] 在提示词中明确：城市、日期、金额、票据关系必须用结构化比较，不允许用关键词替代。证据：`risk_rule_generation_prompt.py` 补充 `numeric_compare` 和预算金额不得关键词匹配的 guardrail。
|
||||
- [ ] [CONCEPT: 后端设计] 在 `risk_rule_generation_semantics.py` 或解释层补齐语义计划解析与错误返回。进度：已新增 `risk_rule_generation_semantic_plan.py` 解析 `{ semantic_plan, dsl }` 包装，并在生成 payload 的 `metadata.model_semantic_plan` 中保留模型语义计划；错误详情返回仍待补齐。
|
||||
- [x] [CONCEPT: 后端设计] 在 `risk_rule_generation_interpreter.py` 中从 `semantic_plan` 生成标准 DSL。证据：新增 `build_dsl_from_semantic_plan`，当 Hermes 仅返回 `semantic_plan` 时生成 `composite_rule_v1` 草稿，再由 DSL validator 基于字段本体规范成受控条件；`test_semantic_plan_only_response_can_generate_standard_dsl` 通过。
|
||||
- [x] [CONCEPT: 指标与验收] 增加复杂差旅规则生成测试，确认判断依据不是关键词匹配。证据：`test_generate_complex_travel_route_rule_uses_formula_not_keyword_match` 验证复杂差旅规则生成后为结构化城市一致性规则，且 `condition_summary` 不含“风险关键词”；容器内 `test_risk_rule_generation.py` 通过。
|
||||
|
||||
## 4. 流程模型与 SVG
|
||||
|
||||
- [x] [CONCEPT: C4] 定义 `flow_model` schema，包含 nodes、edges、字段引用、分支标签和风险节点。证据：`risk_rule_explainability.py` 产出 `flow_model`，生成测试验证 nodes/source/metadata 同步。
|
||||
- [x] [CONCEPT: C4] 修改 `risk_rule_flow_diagram.py`，改为从 DSL 或 `flow_model` 生成 SVG。证据：新增 `build_risk_rule_flow_diagram_spec`，优先从 `flow_model.nodes` 生成图形 spec，缺失时回退 `params.conditions`；`test_flow_diagram_spec_prefers_flow_model_nodes` 通过。
|
||||
- [x] [CONCEPT: C4] 保持 Style 7 / OpenAI Official 风格：白底、细边框、低饱和、风险节点单点强调。证据：`RiskRuleFlowDiagramRenderer` 输出白底、细边框、低饱和风险色，既有 `test_risk_rule_generation.py` 校验高风险红色、无旧绿色和无阴影滤镜。
|
||||
- [x] [CONCEPT: 算法与公式] 实现流程复杂度控制，节点过多时压缩主流程。证据：`_condition_lines_from_flow_nodes` 将超过 4 个判断节点压缩为摘要，`test_flow_diagram_spec_compresses_too_many_decision_nodes` 覆盖。
|
||||
- [x] [CONCEPT: C4] 为老规则缺少 `flow_model` 的情况保留默认静态图兜底。证据：`build_risk_rule_flow_diagram_spec` 在 `flow_model` 缺失时使用 DSL/metadata 生成 spec，`test_flow_diagram_spec_falls_back_to_dsl_when_flow_model_missing` 通过。
|
||||
|
||||
## 5. 执行器 trace 与仿真测试
|
||||
|
||||
- [x] [CONCEPT: C5] 修改 `RiskRuleTemplateExecutor`，输出每个判断节点的 trace。证据：新增 `evaluate_with_trace`，仿真测试返回 `trace.steps` 和 `path_node_ids`。
|
||||
- [ ] [CONCEPT: C5] 仿真测试统一在“用户点击运行”后处理附件和文本，不允许上传后立即判断。
|
||||
- [ ] [CONCEPT: C5] 测试结果中展示 OCR 原始字段、Hermes 规范化字段、执行器实际输入字段。
|
||||
- [x] [CONCEPT: C5] 测试弹窗展示命中路径、未命中原因和最终风险动作。证据：`RiskRuleTestDialog.vue` 展示“执行路径”，`riskRuleTestDialogDisplay.js` 格式化 trace。
|
||||
- [x] [CONCEPT: C5] trace 中的 `node_id` 必须能映射到流程图节点。证据：`flow_model` 使用条件 id 作为节点 id，`risk_rule_execution_trace.py` 输出同名 `node_id`。
|
||||
|
||||
## 6. 规则修改与版本化
|
||||
|
||||
- [x] [CONCEPT: C6] 未上线规则支持编辑标题、费用领域、附件要求和自然语言描述。证据：新增 `AgentAssetRiskRuleRevisionService.update_unpublished_draft` 与 `PATCH /agent-assets/{asset_id}/risk-rules/draft`，容器内 `test_risk_rule_revision_endpoints.py` 覆盖返回字段。
|
||||
- [x] [CONCEPT: C6] 已上线规则新增“创建修订版本”，不直接覆盖 active 版本。证据：新增 `AgentAssetRiskRuleRevisionService.create_revision_draft` 与 `POST /agent-assets/{asset_id}/risk-rules/revisions`，测试验证 `published_version` 保持不变且 `working_version` 进入修订版本。
|
||||
- [ ] [CONCEPT: C6] 修订版本保存后重新生成 DSL、流程图、风险评分和业务说明。
|
||||
- [ ] [CONCEPT: C6] 发布修订版本时归档旧版本，并记录修改人、修改原因和测试报告。
|
||||
- [ ] [CONCEPT: C6] 普通用户误判/漏判反馈进入规则反馈记录，不直接修改规则。
|
||||
|
||||
## 7. 常见费控规则模板库
|
||||
|
||||
- [ ] [CONCEPT: C1] 增加“从常见规则模板创建”入口。
|
||||
- [ ] [CONCEPT: C1] 模板按预算、票据、差旅、招待、采购/AP、企业卡、通用分组。
|
||||
- [ ] [CONCEPT: C3] 每个模板提供默认自然语言、字段清单、附件要求和 DSL 样例。
|
||||
- [ ] [CONCEPT: 非目标] 模板不得绕过通用生成链路，不写定制校准器。
|
||||
|
||||
## 8. 前端详情与交互
|
||||
|
||||
- [ ] [CONCEPT: 前端设计] 详情页 topbar 展示规则标题、状态、风险分数、风险等级、上线/启用状态。
|
||||
- [ ] [CONCEPT: C4] 判断流程区域改成左侧文字流程解释、右侧流程图。
|
||||
- [ ] [CONCEPT: C4] 流程图标题固定为“流程图”，高度与“流程解释”标题对齐。
|
||||
- [ ] [CONCEPT: C5] 测试弹窗展示字段识别结果、规范化字段、判断路径和测试报告。
|
||||
- [x] [CONCEPT: C6] 已上线规则详情展示“创建修订版本”，草稿规则展示“编辑规则”。证据：`AuditView.vue` 底部动作区按规则状态展示按钮，`AuditRuleDialogs.vue` 提供编辑/修订弹窗，`useAuditRiskRuleActions.js` 调用草稿编辑与修订接口；容器内 `cd /app/web && npm run build` 通过。
|
||||
- [ ] [CONCEPT: 指标与验收] 列表和详情状态刷新不能造成页面闪烁。
|
||||
|
||||
## 9. 后端接口与权限
|
||||
|
||||
- [x] [CONCEPT: 接口设计] 实现或调整 `POST /agent-assets/{asset_id}/risk-rules/revisions`。证据：新增独立路由 `agent_asset_risk_rules.py`，容器内 `test_create_risk_rule_revision_endpoint_keeps_active_version` 通过。
|
||||
- [x] [CONCEPT: 接口设计] 实现或调整 `PATCH /agent-assets/{asset_id}/risk-rules/draft`。证据：新增独立路由 `agent_asset_risk_rules.py`，容器内 `test_update_risk_rule_draft_endpoint_updates_unpublished_rule` 与已上线阻断用例通过。
|
||||
- [ ] [CONCEPT: 接口设计] `POST /agent-assets/{asset_id}/risk-rules/regenerate` 返回生成状态和错误详情。
|
||||
- [x] [CONCEPT: 接口设计] 仿真测试接口返回 `recognized_fields`、`normalized_fields`、`execution_result`、`trace`。证据：`AgentAssetRiskRuleSimulationRead` 新增 `normalized_fields` 和 `trace`，仿真测试覆盖返回值。
|
||||
- [ ] [CONCEPT: 用户与场景] 普通财务人员只能编辑未上线/修订草稿，admin 才能删除和测试，管理员按现有权限上线/下线。
|
||||
- [ ] [CONCEPT: 数据设计] 所有操作写入 `last_operation`，用于详情页“最后操作”展示。
|
||||
|
||||
## 10. 测试与验证
|
||||
|
||||
- [x] [CONCEPT: 测试方案] 后端补充语义计划、DSL validator、执行器 trace、流程图转换单元测试。证据：`test_risk_rule_explainability.py` 覆盖语义计划、flow_model、trace；`test_risk_rule_dsl_validator.py` 覆盖 DSL validator 与 `numeric_compare` 执行；容器内相关测试通过。
|
||||
- [ ] [CONCEPT: 测试方案] 后端补充修订版本接口和发布替换接口测试。进度：已补草稿编辑与创建修订版本服务/接口测试，发布替换接口测试仍待补齐。
|
||||
- [ ] [CONCEPT: 测试方案] 前端补充详情页流程展示、测试弹窗字段展示、修订版本按钮状态测试。
|
||||
- [x] [CONCEPT: 容器验证] 在容器执行后端定向测试，单个命令设置 60s 超时。证据：`/tmp/x-financial-server-venv/bin/python -m pytest tests/test_risk_rule_explainability.py -q`、`test_risk_rule_composite_generation.py -q`、`test_risk_rule_generation.py -q` 均通过。
|
||||
- [x] [CONCEPT: 容器验证] 在容器执行 `cd /app/web && npm run build`。证据：容器 `/app/web` 构建通过。
|
||||
- [x] [CONCEPT: 指标与验收] 用“武汉到上海票据 + 北京出差 3 天”样例验证城市不一致规则必须命中或给出明确不命中原因。证据：`test_simulation_returns_execution_trace_for_ticket_city_mismatch` 验证命中并返回 trace。
|
||||
- [x] [CONCEPT: 指标与验收] 用预算阈值、重复发票、住宿日期越界、招待人均超标样例做回归。证据：`risk_rule_dsl_examples.py` 已包含预算阈值、重复发票、住宿日期越界、招待人均超标样例，`test_risk_rule_dsl_examples.py` 在容器内 7 passed。
|
||||
|
||||
## 11. 文档收尾
|
||||
|
||||
- [ ] [CONCEPT: 指标与验收] 开发完成后补充实际接口、文件和测试命令结果。
|
||||
- [ ] [CONCEPT: 风险与开放问题] 记录暂未解决的字段本体缺口和复杂规则降级策略。
|
||||
- [ ] [CONCEPT: 功能一句话] 确认最终实现没有偏离“解释图和执行逻辑一致”的核心目标。
|
||||
Reference in New Issue
Block a user