feat: 新增风险图谱算法与系统仪表盘及操作反馈体系
后端新增风险图谱算法模块、风险观察与反馈服务、规则 DSL 校验器和可解释性引擎，完善系统仪表盘和财务仪表盘统计， 优化 agent 运行和编排执行链路，清理旧开发文档，前端新增 系统趋势、负载热力图等多种仪表盘图表组件，完善操作反馈 对话框和工作台日期选择器，优化报销创建和审批详情交互， 补充单元测试覆盖。
This commit is contained in:
caoxiaozhu
@@ -1,58 +0,0 @@
|
||||
# Agent Plan 文档索引
|
||||
|
||||
本目录描述 X-Financial 后续要建设的双 Agent 财务智能架构。
|
||||
|
||||
核心目标：
|
||||
|
||||
- 建立一套共享的语义本体协议，统一理解用户问题、定时任务和规则触发上下文。
|
||||
- 建设两套职责边界清晰的 Agent：
|
||||
- Hermes：后台数字员工，负责内循环定时任务、风险巡检、统计、知识维护。
|
||||
- 自建 Agent：用户流程助手，负责用户交互、流程操作、解释、查询、草稿生成。
|
||||
- 建设 Agent Orchestrator，统一负责路由、权限、工具调用、审计和失败处理。
|
||||
- 让规则中心、MCP、知识库、数据库查询和任务系统使用同一套语义协议。
|
||||
|
||||
## 与一周计划的关系
|
||||
|
||||
`document/development/agent week plan` 是一周开发路线图，只描述每天要完成的大方向和交付结果。
|
||||
|
||||
本目录是具体架构与实现依据，包含：
|
||||
|
||||
- 架构设计。
|
||||
- 数据协议。
|
||||
- Agent 职责。
|
||||
- Orchestrator 流程。
|
||||
- OCR、知识库、规则生命周期。
|
||||
- 每天 daily 文档会引用到的设计依据。
|
||||
|
||||
执行时按这个顺序阅读：
|
||||
|
||||
1. 先看 `document/development/agent week plan/MASTER_TODO.md`，确认今天做什么。
|
||||
2. 再看本目录的架构文档，理解为什么这样做。
|
||||
3. 最后进入 `document/development/agent week plan/` 对应 Day 文档，在同一份文档中按详细执行清单开发。
|
||||
|
||||
推荐阅读顺序：
|
||||
|
||||
1. [01_overall_architecture.md](./01_overall_architecture.md)
|
||||
2. [02_semantic_ontology.md](./02_semantic_ontology.md)
|
||||
3. [03_agent_responsibilities.md](./03_agent_responsibilities.md)
|
||||
4. [04_orchestrator_and_runtime_flow.md](./04_orchestrator_and_runtime_flow.md)
|
||||
5. [05_development_roadmap.md](./05_development_roadmap.md)
|
||||
6. [06_data_contracts_and_governance.md](./06_data_contracts_and_governance.md)
|
||||
7. [07_capability_registry.md](./07_capability_registry.md)
|
||||
8. [08_permission_confirmation.md](./08_permission_confirmation.md)
|
||||
9. [09_observability_and_trace.md](./09_observability_and_trace.md)
|
||||
10. [10_evaluation_and_testset.md](./10_evaluation_and_testset.md)
|
||||
11. [11_ocr_invoice_architecture.md](./11_ocr_invoice_architecture.md)
|
||||
12. [12_llm_wiki_knowledge_architecture.md](./12_llm_wiki_knowledge_architecture.md)
|
||||
13. [13_rule_formation_lifecycle.md](./13_rule_formation_lifecycle.md)
|
||||
14. [14_financial_document_canonical_model.md](./14_financial_document_canonical_model.md)
|
||||
15. [15_feedback_learning_loop.md](./15_feedback_learning_loop.md)
|
||||
16. [../agent week plan/00_README.md](<../agent week plan/00_README.md>)
|
||||
|
||||
开发原则：
|
||||
|
||||
- 先语义协议，后 Agent 能力。
|
||||
- 先只读和建议，后写入和流程动作。
|
||||
- 先人工确认，后有限自动化。
|
||||
- 所有财务关键动作必须可审计、可回滚、可追责。
|
||||
- 所有 Agent 能力必须注册、分级、可评测、可追踪。
|
||||
@@ -1,163 +0,0 @@
|
||||
# 双 Agent 总体架构
|
||||
|
||||
## 1. 背景
|
||||
|
||||
X-Financial 后续需要同时支持两类智能化能力：
|
||||
|
||||
1. 用户主动发起的交互式流程操作。
|
||||
2. 系统后台自动运行的定时巡检、统计、预警和知识维护。
|
||||
|
||||
如果用一个万能 Agent 同时处理这两类任务，风险会很高：
|
||||
|
||||
- 用户流程操作需要权限、确认、上下文追问。
|
||||
- 定时巡检需要稳定批处理、失败重试、审计记录。
|
||||
- 财务系统不能让大模型直接决定审批、付款、规则上线。
|
||||
|
||||
因此建议建设双 Agent 架构：
|
||||
|
||||
```text
|
||||
Hermes Agent
|
||||
后台数字员工
|
||||
面向系统内循环
|
||||
定时、批量、巡检、统计、预警、知识候选
|
||||
|
||||
User Agent
|
||||
自建用户流程助手
|
||||
面向用户交互
|
||||
查询、解释、创建草稿、流程操作、审批辅助
|
||||
```
|
||||
|
||||
两套 Agent 共享一套语义本体协议，由 Agent Orchestrator 统一调度。
|
||||
|
||||
## 2. 总体架构图
|
||||
|
||||
```text
|
||||
┌──────────────────────┐
|
||||
│ 用户自然语言 / 定时任务 │
|
||||
└───────────┬──────────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────────────┐
|
||||
│ Semantic Ontology │
|
||||
│ 语义本体解析层 │
|
||||
└───────────┬──────────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────────────┐
|
||||
│ Agent Orchestrator │
|
||||
│ 路由 / 权限 / 审计 / 调度 │
|
||||
└───────┬─────────┬────┘
|
||||
│ │
|
||||
┌─────────────▼─┐ ┌─▼──────────────┐
|
||||
│ Hermes Agent │ │ User Agent │
|
||||
│ 后台数字员工 │ │ 用户流程助手 │
|
||||
└───────┬───────┘ └───────┬────────┘
|
||||
│ │
|
||||
└──────────┬──────────┘
|
||||
│
|
||||
┌────────────┬───────────┼───────────┬────────────┐
|
||||
▼ ▼ ▼ ▼ ▼
|
||||
规则中心 MCP 服务 业务数据库 知识库 任务系统
|
||||
```
|
||||
|
||||
## 3. 核心分层
|
||||
|
||||
### 3.1 语义本体层
|
||||
|
||||
负责把自然语言或任务配置转成结构化 JSON。
|
||||
|
||||
输出不是最终答案，而是统一协议：
|
||||
|
||||
```json
|
||||
{
|
||||
"domain": "reimbursement",
|
||||
"scenario": "invoice_validation",
|
||||
"intent": "explain_risk",
|
||||
"entities": [],
|
||||
"time_range": {},
|
||||
"constraints": {},
|
||||
"risk_signals": [],
|
||||
"next_step": "run_rule"
|
||||
}
|
||||
```
|
||||
|
||||
### 3.2 编排层
|
||||
|
||||
Agent Orchestrator 负责：
|
||||
|
||||
- 判断应该由 Hermes 还是 User Agent 处理。
|
||||
- 判断是否需要查数据库、跑规则、调 MCP、检索知识库。
|
||||
- 检查用户权限。
|
||||
- 记录审计日志。
|
||||
- 控制失败重试。
|
||||
- 对高风险动作要求用户或管理员确认。
|
||||
|
||||
### 3.3 Agent 层
|
||||
|
||||
Hermes 和 User Agent 不直接决定财务关键状态。
|
||||
|
||||
它们负责：
|
||||
|
||||
- 理解任务。
|
||||
- 组织工具调用。
|
||||
- 汇总工具结果。
|
||||
- 生成建议、解释、报告、草稿。
|
||||
|
||||
### 3.4 能力层
|
||||
|
||||
能力层包括：
|
||||
|
||||
- 规则中心：管理 `.md` 规则文件、审核、版本。
|
||||
- MCP：封装外部服务，如发票验真、银行流水、OCR、差旅平台。
|
||||
- 数据库查询：查询报销、报账、应收、应付、账款数据。
|
||||
- 知识库：制度文档、FAQ、历史解释、规则说明。
|
||||
- 任务系统：定时任务、批量任务、重试、运行日志。
|
||||
|
||||
## 4. 关键边界
|
||||
|
||||
Hermes 可以：
|
||||
|
||||
- 定时读取数据。
|
||||
- 执行规则检查。
|
||||
- 调 MCP 查询外部状态。
|
||||
- 生成风险报告。
|
||||
- 生成知识候选。
|
||||
- 生成待处理工单。
|
||||
|
||||
Hermes 不可以：
|
||||
|
||||
- 自动提交报销。
|
||||
- 自动发起付款。
|
||||
- 自动审批通过。
|
||||
- 自动发布知识库正式内容。
|
||||
- 自动上线规则。
|
||||
|
||||
User Agent 可以：
|
||||
|
||||
- 帮用户查询状态。
|
||||
- 帮用户解释风险。
|
||||
- 帮用户创建报销或付款草稿。
|
||||
- 帮审批人生成审批意见。
|
||||
- 在用户确认后调用流程 API。
|
||||
|
||||
User Agent 不可以：
|
||||
|
||||
- 绕过权限。
|
||||
- 未确认直接提交关键动作。
|
||||
- 自动最终审批。
|
||||
- 自动付款。
|
||||
- 修改规则审核状态。
|
||||
|
||||
## 5. 推荐建设顺序
|
||||
|
||||
```text
|
||||
Step 1: 建立语义本体 JSON 协议
|
||||
Step 2: 建立规则中心的规则/技能/MCP/任务目录
|
||||
Step 3: 建立 Orchestrator 路由和审计
|
||||
Step 4: 建立 User Agent 的只读查询和解释能力
|
||||
Step 5: 建立 Hermes 的定时任务和报告能力
|
||||
Step 6: 接入 MCP 和业务数据库
|
||||
Step 7: 增加用户确认后的流程写入能力
|
||||
Step 8: 增加知识候选和规则优化闭环
|
||||
```
|
||||
|
||||
@@ -1,457 +0,0 @@
|
||||
# 语义本体协议设计
|
||||
|
||||
## 1. 定位
|
||||
|
||||
语义本体协议是用户问题、定时任务、规则中心、MCP、数据库查询和 Agent 之间的统一中间层。
|
||||
|
||||
它解决的问题是：
|
||||
|
||||
- 用户到底在问哪个业务域？
|
||||
- 这属于什么场景？
|
||||
- 用户想做什么？
|
||||
- 问题中涉及哪些对象？
|
||||
- 有没有时间、金额、状态、部门等过滤条件？
|
||||
- 是否涉及风险？
|
||||
- 下一步应该查知识库、查数据库、跑规则、调 MCP，还是追问？
|
||||
|
||||
## 2. 第一版核心字段
|
||||
|
||||
第一版建议只强制落 8 个字段。
|
||||
|
||||
```json
|
||||
{
|
||||
"domain": "",
|
||||
"scenario": "",
|
||||
"intent": "",
|
||||
"entities": [],
|
||||
"time_range": {},
|
||||
"constraints": {},
|
||||
"risk_signals": [],
|
||||
"next_step": ""
|
||||
}
|
||||
```
|
||||
|
||||
### 2.1 domain
|
||||
|
||||
一级业务域。
|
||||
|
||||
建议枚举：
|
||||
|
||||
```text
|
||||
reimbursement
|
||||
accounts_receivable
|
||||
accounts_payable
|
||||
general_finance
|
||||
system_operation
|
||||
```
|
||||
|
||||
含义：
|
||||
|
||||
- `reimbursement`：报销、差旅、发票、补件。
|
||||
- `accounts_receivable`：应收账款、客户开票、收款、账龄。
|
||||
- `accounts_payable`：应付账款、供应商发票、付款、对账。
|
||||
- `general_finance`：通用财务知识、制度、统计。
|
||||
- `system_operation`：系统巡检、任务运行、规则维护、MCP 健康检查。
|
||||
|
||||
### 2.2 scenario
|
||||
|
||||
细分场景。
|
||||
|
||||
报销：
|
||||
|
||||
```text
|
||||
travel_reimbursement
|
||||
daily_expense
|
||||
invoice_validation
|
||||
attachment_review
|
||||
policy_overrun
|
||||
reimbursement_audit
|
||||
```
|
||||
|
||||
应收：
|
||||
|
||||
```text
|
||||
customer_invoice
|
||||
collection_followup
|
||||
receivable_aging
|
||||
payment_matching
|
||||
bad_debt_risk
|
||||
contract_receivable
|
||||
```
|
||||
|
||||
应付：
|
||||
|
||||
```text
|
||||
vendor_invoice
|
||||
payment_request
|
||||
payable_aging
|
||||
vendor_reconciliation
|
||||
invoice_matching
|
||||
cash_outflow_forecast
|
||||
```
|
||||
|
||||
系统运营：
|
||||
|
||||
```text
|
||||
daily_risk_scan
|
||||
daily_finance_statistics
|
||||
knowledge_accumulation
|
||||
mcp_health_check
|
||||
rule_quality_review
|
||||
```
|
||||
|
||||
### 2.3 intent
|
||||
|
||||
用户或任务的意图。
|
||||
|
||||
建议枚举：
|
||||
|
||||
```text
|
||||
query
|
||||
explain
|
||||
create
|
||||
validate
|
||||
summarize
|
||||
reconcile
|
||||
monitor
|
||||
predict
|
||||
remind
|
||||
generate
|
||||
optimize
|
||||
```
|
||||
|
||||
### 2.4 entities
|
||||
|
||||
识别出的业务对象。
|
||||
|
||||
统一结构：
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "invoice",
|
||||
"value": "INV-202605001",
|
||||
"normalized_value": "INV-202605001",
|
||||
"role": "target",
|
||||
"confidence": 0.92
|
||||
}
|
||||
```
|
||||
|
||||
常见实体：
|
||||
|
||||
```text
|
||||
employee
|
||||
department
|
||||
customer
|
||||
vendor
|
||||
invoice
|
||||
contract
|
||||
reimbursement_request
|
||||
payment_order
|
||||
receipt
|
||||
bank_transaction
|
||||
cost_center
|
||||
project
|
||||
policy
|
||||
approval_node
|
||||
rule
|
||||
task
|
||||
```
|
||||
|
||||
### 2.5 time_range
|
||||
|
||||
统一描述时间。
|
||||
|
||||
```json
|
||||
{
|
||||
"raw": "上个月",
|
||||
"start": "2026-04-01",
|
||||
"end": "2026-04-30",
|
||||
"granularity": "month"
|
||||
}
|
||||
```
|
||||
|
||||
Hermes 定时任务也使用同一字段。
|
||||
|
||||
例如每日风险巡检：
|
||||
|
||||
```json
|
||||
{
|
||||
"raw": "昨日",
|
||||
"start": "2026-05-09",
|
||||
"end": "2026-05-09",
|
||||
"granularity": "day"
|
||||
}
|
||||
```
|
||||
|
||||
### 2.6 constraints
|
||||
|
||||
查询、判断或执行条件。
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "overdue",
|
||||
"aging_days": ">30",
|
||||
"amount": {
|
||||
"operator": ">",
|
||||
"value": 50000,
|
||||
"currency": "CNY"
|
||||
},
|
||||
"department": "销售部",
|
||||
"risk_level": ["medium", "high"]
|
||||
}
|
||||
```
|
||||
|
||||
### 2.7 risk_signals
|
||||
|
||||
风险信号。
|
||||
|
||||
建议枚举：
|
||||
|
||||
```text
|
||||
duplicate_invoice
|
||||
missing_attachment
|
||||
policy_overrun
|
||||
over_budget
|
||||
overdue_receivable
|
||||
bad_debt_risk
|
||||
vendor_payment_risk
|
||||
payment_mismatch
|
||||
contract_mismatch
|
||||
cashflow_pressure
|
||||
mcp_unavailable
|
||||
rule_quality_issue
|
||||
```
|
||||
|
||||
### 2.8 next_step
|
||||
|
||||
下一步动作。
|
||||
|
||||
建议枚举：
|
||||
|
||||
```text
|
||||
answer
|
||||
ask_clarification
|
||||
query_database
|
||||
run_rule
|
||||
call_mcp
|
||||
search_knowledge
|
||||
create_draft
|
||||
create_task
|
||||
generate_report
|
||||
notify_user
|
||||
escalate_to_human
|
||||
```
|
||||
|
||||
## 3. 扩展字段
|
||||
|
||||
后续可以增加：
|
||||
|
||||
```json
|
||||
{
|
||||
"schema_version": "1.1",
|
||||
"confidence": 0.86,
|
||||
"ambiguity": [],
|
||||
"missing_slots": [],
|
||||
"required_capabilities": [],
|
||||
"normalized_query": "",
|
||||
"permission_scope": {},
|
||||
"audit_tags": []
|
||||
}
|
||||
```
|
||||
|
||||
## 4. 混合语义解析架构
|
||||
|
||||
第一版可上线实现不应只依赖关键词和正则。
|
||||
|
||||
推荐采用：
|
||||
|
||||
```text
|
||||
输入上下文装配
|
||||
用户文本 + 页面上下文 + 附件名称 + OCR/VLM 摘要
|
||||
↓
|
||||
预抽取
|
||||
时间、金额、单号、显式对象
|
||||
↓
|
||||
LLM 结构化解析
|
||||
输出 scenario / intent / entities / missing_slots / ambiguity
|
||||
↓
|
||||
Schema 校验
|
||||
JSON 解析、字段枚举、必填校验、类型归一化
|
||||
↓
|
||||
规则兜底
|
||||
模型失败、低置信度或字段缺失时回退到规则解析
|
||||
↓
|
||||
澄清追问
|
||||
低置信度、歧义、缺槽位时不允许直接查库
|
||||
```
|
||||
|
||||
设计原则：
|
||||
|
||||
- 模型优先负责“理解意图和场景”。
|
||||
- 规则优先负责“校验、补全和兜底”。
|
||||
- 附件名称、OCR、VLM 结果只能作为证据，不等于已确认事实。
|
||||
- 所有语义输出都必须标记置信度和来源。
|
||||
|
||||
## 5. 推荐新增字段
|
||||
|
||||
为支持模型优先解析，建议在扩展字段中至少增加：
|
||||
|
||||
```json
|
||||
{
|
||||
"missing_slots": [],
|
||||
"ambiguity": [],
|
||||
"field_confidence": {},
|
||||
"field_source": {},
|
||||
"attachment_context": [],
|
||||
"parse_strategy": "llm_primary_with_rule_fallback"
|
||||
}
|
||||
```
|
||||
|
||||
字段说明：
|
||||
|
||||
- `missing_slots`：还缺哪些关键字段，例如费用类型、单据号、客户单位。
|
||||
- `ambiguity`：当前可能混淆的理解结果。
|
||||
- `field_confidence`：字段级置信度，而不是只给整体分数。
|
||||
- `field_source`：字段来自 `llm`、`rule`、`ocr`、`vlm` 还是 `user_context`。
|
||||
- `attachment_context`：本次可供语义解析使用的附件摘要。
|
||||
- `parse_strategy`：标记本次是模型主解析还是规则回退。
|
||||
|
||||
## 6. 叙述型财务输入
|
||||
|
||||
语义层必须支持“不是查询句”的自然叙述。
|
||||
|
||||
典型样例：
|
||||
|
||||
```text
|
||||
我今天去客户现场，招待了客户，花销了1000元
|
||||
我垫付了打车费和餐费，帮我看看怎么报
|
||||
上传了三张票，帮我整理成报销草稿
|
||||
```
|
||||
|
||||
这类输入不能默认识别成 `query`。
|
||||
|
||||
建议默认策略：
|
||||
|
||||
- 优先识别为 `reimbursement` 域。
|
||||
- 场景优先落到 `daily_expense`、`travel_reimbursement` 或 `attachment_review`。
|
||||
- 意图优先落到 `create`、`generate` 或 `validate`。
|
||||
- 缺失关键字段时返回 `ask_clarification`，而不是直接查数据库。
|
||||
|
||||
## 7. 模糊短句与澄清规则
|
||||
|
||||
以下输入应优先追问：
|
||||
|
||||
```text
|
||||
我要报销
|
||||
这个为什么还没处理
|
||||
帮我看一下这个
|
||||
上传好了，下一步呢
|
||||
```
|
||||
|
||||
处理原则：
|
||||
|
||||
- 不允许直接执行工具。
|
||||
- 不允许直接落到应收、应付查询。
|
||||
- 必须生成澄清问题。
|
||||
- 必须在审计中记录触发追问的原因。
|
||||
|
||||
扩展原则：
|
||||
|
||||
- 先不要把所有字段都做成数据库列。
|
||||
- 语义结果建议存 JSONB。
|
||||
- 使用 `schema_version` 管理版本。
|
||||
- Orchestrator 只依赖稳定字段。
|
||||
- 新字段以可选方式加入，不影响老任务。
|
||||
|
||||
## 4. 示例
|
||||
|
||||
### 4.1 用户查询应收账龄
|
||||
|
||||
用户问：
|
||||
|
||||
```text
|
||||
上个月哪些客户应收逾期超过 30 天？
|
||||
```
|
||||
|
||||
解析：
|
||||
|
||||
```json
|
||||
{
|
||||
"domain": "accounts_receivable",
|
||||
"scenario": "receivable_aging",
|
||||
"intent": "query",
|
||||
"entities": [
|
||||
{
|
||||
"type": "customer",
|
||||
"value": "客户",
|
||||
"role": "group_by"
|
||||
}
|
||||
],
|
||||
"time_range": {
|
||||
"raw": "上个月",
|
||||
"start": "2026-04-01",
|
||||
"end": "2026-04-30",
|
||||
"granularity": "month"
|
||||
},
|
||||
"constraints": {
|
||||
"aging_days": ">30",
|
||||
"status": "overdue"
|
||||
},
|
||||
"risk_signals": ["overdue_receivable"],
|
||||
"next_step": "query_database"
|
||||
}
|
||||
```
|
||||
|
||||
### 4.2 用户解释发票拦截
|
||||
|
||||
用户问：
|
||||
|
||||
```text
|
||||
这张发票为什么报销被拦截？
|
||||
```
|
||||
|
||||
解析：
|
||||
|
||||
```json
|
||||
{
|
||||
"domain": "reimbursement",
|
||||
"scenario": "invoice_validation",
|
||||
"intent": "explain",
|
||||
"entities": [
|
||||
{
|
||||
"type": "invoice",
|
||||
"value": "这张发票",
|
||||
"role": "target"
|
||||
}
|
||||
],
|
||||
"time_range": {},
|
||||
"constraints": {},
|
||||
"risk_signals": ["unknown"],
|
||||
"next_step": "run_rule"
|
||||
}
|
||||
```
|
||||
|
||||
### 4.3 Hermes 每日风险巡检
|
||||
|
||||
任务配置：
|
||||
|
||||
```json
|
||||
{
|
||||
"domain": "reimbursement",
|
||||
"scenario": "daily_risk_scan",
|
||||
"intent": "monitor",
|
||||
"entities": [],
|
||||
"time_range": {
|
||||
"raw": "昨日"
|
||||
},
|
||||
"constraints": {
|
||||
"risk_level": ["medium", "high"]
|
||||
},
|
||||
"risk_signals": [
|
||||
"duplicate_invoice",
|
||||
"missing_attachment",
|
||||
"policy_overrun"
|
||||
],
|
||||
"next_step": "run_rule"
|
||||
}
|
||||
```
|
||||
@@ -1,178 +0,0 @@
|
||||
# Hermes 与自建 Agent 职责边界
|
||||
|
||||
## 1. 两套 Agent 的定位
|
||||
|
||||
### 1.1 Hermes
|
||||
|
||||
Hermes 定位为后台数字员工。
|
||||
|
||||
它不直接面向用户聊天，而是在系统后台做内循环工作。
|
||||
|
||||
关键词：
|
||||
|
||||
```text
|
||||
定时
|
||||
批量
|
||||
巡检
|
||||
统计
|
||||
预警
|
||||
知识维护
|
||||
规则质量复盘
|
||||
```
|
||||
|
||||
### 1.2 自建 Agent
|
||||
|
||||
自建 Agent 定位为用户流程助手。
|
||||
|
||||
它直接面对员工、财务人员、审批人和管理员。
|
||||
|
||||
关键词：
|
||||
|
||||
```text
|
||||
用户触发
|
||||
会话式
|
||||
流程操作
|
||||
查询解释
|
||||
草稿生成
|
||||
审批辅助
|
||||
用户确认
|
||||
```
|
||||
|
||||
## 2. Hermes 职责
|
||||
|
||||
Hermes 负责：
|
||||
|
||||
1. 每日风险巡检。
|
||||
2. 每日报销、报账、账款统计。
|
||||
3. 应收逾期预警。
|
||||
4. 应付付款风险预警。
|
||||
5. 规则命中质量复盘。
|
||||
6. MCP 健康检查。
|
||||
7. 知识库候选内容生成。
|
||||
8. 高风险工单生成。
|
||||
9. 任务运行报告生成。
|
||||
|
||||
Hermes 输出的内容包括：
|
||||
|
||||
```text
|
||||
risk_report
|
||||
risk_work_items
|
||||
daily_finance_snapshot
|
||||
knowledge_candidates
|
||||
rule_improvement_items
|
||||
mcp_health_report
|
||||
task_run_log
|
||||
```
|
||||
|
||||
Hermes 不允许：
|
||||
|
||||
1. 自动审批通过。
|
||||
2. 自动发起付款。
|
||||
3. 自动提交用户申请。
|
||||
4. 自动发布正式知识库。
|
||||
5. 自动上线规则。
|
||||
6. 直接修改核心财务状态。
|
||||
|
||||
## 3. 自建 Agent 职责
|
||||
|
||||
自建 Agent 负责：
|
||||
|
||||
1. 查询报销单进度。
|
||||
2. 创建报销或付款草稿。
|
||||
3. 解释规则拦截原因。
|
||||
4. 生成审批意见。
|
||||
5. 检索制度知识。
|
||||
6. 查询应收应付数据。
|
||||
7. 帮用户对账。
|
||||
8. 引导用户补充缺失信息。
|
||||
9. 在用户确认后调用流程 API。
|
||||
|
||||
自建 Agent 输出的内容包括：
|
||||
|
||||
```text
|
||||
natural_language_answer
|
||||
form_draft
|
||||
approval_opinion_draft
|
||||
clarification_question
|
||||
query_result_summary
|
||||
next_action_suggestion
|
||||
```
|
||||
|
||||
自建 Agent 不允许：
|
||||
|
||||
1. 未经用户确认提交关键动作。
|
||||
2. 跳过权限校验。
|
||||
3. 自动最终审批。
|
||||
4. 自动付款。
|
||||
5. 修改规则上线状态。
|
||||
|
||||
## 4. 权限边界
|
||||
|
||||
| 动作 | Hermes | 自建 Agent |
|
||||
|---|---|---|
|
||||
| 查询制度知识 | 可以 | 可以 |
|
||||
| 查询业务数据 | 可以，按任务权限 | 可以，按用户权限 |
|
||||
| 跑规则 | 可以 | 可以 |
|
||||
| 调 MCP | 可以 | 可以 |
|
||||
| 生成报告 | 可以 | 可以 |
|
||||
| 生成草稿 | 不建议 | 可以 |
|
||||
| 提交流程 | 不可以 | 用户确认后可以 |
|
||||
| 审批通过 | 不可以 | 不可以直接做 |
|
||||
| 发起付款 | 不可以 | 高权限确认后才可做草稿 |
|
||||
| 发布知识 | 不可以 | 不可以 |
|
||||
| 上线规则 | 不可以 | 不可以 |
|
||||
|
||||
## 5. 共享能力
|
||||
|
||||
两套 Agent 共享：
|
||||
|
||||
- 语义本体协议。
|
||||
- 规则中心。
|
||||
- MCP 服务。
|
||||
- 知识库。
|
||||
- 数据库查询服务。
|
||||
- 审计日志。
|
||||
- 权限系统。
|
||||
|
||||
不共享：
|
||||
|
||||
- 运行队列。
|
||||
- 调度策略。
|
||||
- 用户会话状态。
|
||||
- 任务重试状态。
|
||||
|
||||
## 6. 示例
|
||||
|
||||
### 6.1 Hermes 场景
|
||||
|
||||
每日 02:00 自动运行：
|
||||
|
||||
```text
|
||||
每日风险巡检
|
||||
读取昨日报销、报账、发票、账款数据
|
||||
执行规则
|
||||
调用发票验真 MCP
|
||||
调用账款流水 MCP
|
||||
生成风险报告
|
||||
生成风险工单
|
||||
```
|
||||
|
||||
### 6.2 自建 Agent 场景
|
||||
|
||||
用户问：
|
||||
|
||||
```text
|
||||
帮我看一下这张差旅报销为什么没通过。
|
||||
```
|
||||
|
||||
处理：
|
||||
|
||||
```text
|
||||
解析语义
|
||||
查询报销单
|
||||
读取规则命中
|
||||
检索制度条款
|
||||
组织解释
|
||||
给出补件建议
|
||||
```
|
||||
|
||||
@@ -1,385 +0,0 @@
|
||||
# Agent Orchestrator 与运行流程
|
||||
|
||||
## 1. Orchestrator 定位
|
||||
|
||||
Agent Orchestrator 是双 Agent 架构的调度中心。
|
||||
|
||||
它不负责生成最终答案，而是负责：
|
||||
|
||||
- 接收用户请求或定时任务。
|
||||
- 调用语义解析。
|
||||
- 判断处理方。
|
||||
- 选择工具。
|
||||
- 检查权限。
|
||||
- 记录审计。
|
||||
- 管理失败重试。
|
||||
- 控制高风险动作确认。
|
||||
|
||||
## 2. 运行主流程
|
||||
|
||||
```text
|
||||
输入
|
||||
用户消息 / 页面按钮 / 定时任务 / 系统事件
|
||||
↓
|
||||
上下文装配
|
||||
页面对象 / 附件名称 / OCR 摘要 / VLM 摘要 / 用户角色 / conversation_id / draft_claim_id
|
||||
↓
|
||||
语义解析
|
||||
LLM 主解析 + 规则兜底，输出 ontology_json
|
||||
↓
|
||||
语义校验
|
||||
confidence / missing_slots / ambiguity / permission 初判
|
||||
↓
|
||||
Orchestrator 决策
|
||||
判断 agent = hermes | user_agent
|
||||
判断 tool = rule | mcp | db | knowledge | task
|
||||
↓
|
||||
权限检查
|
||||
用户权限 / 任务权限 / 数据范围
|
||||
↓
|
||||
业务写入
|
||||
报销草稿创建 / 报销草稿更新 / 用户确认后提交
|
||||
↓
|
||||
工具执行
|
||||
规则中心 / MCP / 数据库 / 知识库 / 任务系统
|
||||
↓
|
||||
Agent 汇总
|
||||
Hermes 报告 / User Agent 回答
|
||||
↓
|
||||
审计记录
|
||||
保存输入、语义、工具、结果、动作
|
||||
```
|
||||
|
||||
## 3. 路由规则
|
||||
|
||||
### 3.1 Hermes 路由
|
||||
|
||||
满足以下条件之一，进入 Hermes：
|
||||
|
||||
```text
|
||||
source = schedule
|
||||
source = system_event
|
||||
intent = monitor
|
||||
intent = summarize and no active user session
|
||||
next_step = generate_report and task_type is batch
|
||||
scenario in daily_risk_scan / knowledge_accumulation / mcp_health_check
|
||||
```
|
||||
|
||||
补充约束：
|
||||
|
||||
- 这里的 Hermes 指系统后台真实 Hermes 进程或 Hermes CLI，不是前端概念上的 “Hermes 模式”。
|
||||
- Orchestrator 负责路由、权限、审计和 Trace，不负责替代 Hermes 自身执行。
|
||||
- 当前阶段允许保留本地 fallback，但必须预留真实 Hermes 进程调用入口。
|
||||
|
||||
### 3.2 User Agent 路由
|
||||
|
||||
满足以下条件之一，进入自建 Agent：
|
||||
|
||||
```text
|
||||
source = user_message
|
||||
source = page_action
|
||||
intent = query / explain / create / validate / reconcile
|
||||
requires_user_context = true
|
||||
next_step = ask_clarification
|
||||
next_step = create_draft
|
||||
```
|
||||
|
||||
### 3.3 工具路由
|
||||
|
||||
```text
|
||||
next_step = query_database
|
||||
调用数据库查询服务
|
||||
|
||||
next_step = run_rule
|
||||
调用规则中心
|
||||
|
||||
next_step = call_mcp
|
||||
调用 MCP 服务
|
||||
|
||||
next_step = search_knowledge
|
||||
调用知识库检索
|
||||
|
||||
next_step = create_task
|
||||
调用任务系统
|
||||
|
||||
next_step = create_expense_claim_draft
|
||||
创建 expense_claims / expense_claim_items 草稿
|
||||
|
||||
next_step = update_expense_claim_draft
|
||||
回写报销主表、明细和附件关联
|
||||
|
||||
next_step = submit_expense_claim
|
||||
用户确认后更新 expense_claims.status = submitted
|
||||
|
||||
next_step = ask_clarification
|
||||
返回追问
|
||||
```
|
||||
|
||||
### 3.4 低置信度与缺槽位保护
|
||||
|
||||
当满足以下任一条件时，不允许直接进入数据库、MCP 或高风险流程：
|
||||
|
||||
```text
|
||||
confidence < threshold
|
||||
missing_slots 非空
|
||||
ambiguity 非空
|
||||
输入为叙述型报销，但缺少关键报销信息
|
||||
```
|
||||
|
||||
处理方式：
|
||||
|
||||
```text
|
||||
next_step = ask_clarification
|
||||
selected_agent = user_agent
|
||||
tool_count = 0
|
||||
```
|
||||
|
||||
### 3.5 叙述型报销输入保护
|
||||
|
||||
像下面这类文本：
|
||||
|
||||
```text
|
||||
我今天去客户现场，招待了客户，花销了1000元
|
||||
我垫付了交通费和午餐费
|
||||
我上传了票据，帮我整理一下
|
||||
```
|
||||
|
||||
不能因为出现“客户”就落到应收查询。
|
||||
|
||||
Orchestrator 应依赖语义层返回的 `scenario + intent + missing_slots` 做决策，而不是二次猜测文本关键词。
|
||||
|
||||
### 3.6 报销建单与状态流转边界
|
||||
|
||||
当 `scenario = expense` 且已满足最小建单槽位时：
|
||||
|
||||
```text
|
||||
next_step = create_expense_claim_draft
|
||||
status = draft
|
||||
```
|
||||
|
||||
当用户继续补充金额、地点、客户、参与人、附件时：
|
||||
|
||||
```text
|
||||
next_step = update_expense_claim_draft
|
||||
status 保持 draft
|
||||
```
|
||||
|
||||
当用户明确说“提交报销”并完成确认时：
|
||||
|
||||
```text
|
||||
next_step = submit_expense_claim
|
||||
status = submitted
|
||||
requires_confirmation = true
|
||||
```
|
||||
|
||||
以下状态不应由 User Agent 直接改写：
|
||||
|
||||
```text
|
||||
approved
|
||||
rejected
|
||||
paid
|
||||
```
|
||||
|
||||
这些状态应由审批流、财务支付流或受控后台同步更新。
|
||||
|
||||
### 3.7 结构化核对回路
|
||||
|
||||
当 `scenario = expense` 且当前仍存在缺槽位、附件待核对或票据需拆单时，不直接返回一段自由文本，而是返回结构化核对结果：
|
||||
|
||||
```text
|
||||
result.review_payload
|
||||
intent_summary
|
||||
body_message
|
||||
slot_cards
|
||||
risk_briefs
|
||||
document_cards
|
||||
claim_groups
|
||||
confirmation_actions = 取消 / 修改 / 保存草稿或下一步
|
||||
edit_fields
|
||||
```
|
||||
|
||||
前端正文区只展示简洁提示，右侧展示字段、风险、票据与分单明细。
|
||||
|
||||
### 3.8 会话续接与重识别
|
||||
|
||||
用户对话不是无状态调用。Orchestrator 需要携带以下会话字段继续当前报销流程：
|
||||
|
||||
```text
|
||||
conversation_id
|
||||
draft_claim_id
|
||||
conversation_history
|
||||
review_action
|
||||
review_form_values
|
||||
```
|
||||
|
||||
其中：
|
||||
|
||||
```text
|
||||
review_action = edit_review
|
||||
表示用户基于结构化模板修改识别结果，需要重新进入语义识别
|
||||
|
||||
review_action = save_draft
|
||||
表示信息未补齐，但允许先保存报销草稿
|
||||
|
||||
review_action = next_step
|
||||
表示用户确认当前识别结果，可进入下一步流转
|
||||
```
|
||||
|
||||
## 4. 用户流程示例
|
||||
|
||||
用户输入：
|
||||
|
||||
```text
|
||||
上个月哪些客户应收逾期超过 30 天？
|
||||
```
|
||||
|
||||
流程：
|
||||
|
||||
```text
|
||||
Step 1: User Agent 接收消息
|
||||
Step 2: semantic_parser 输出 ontology_json
|
||||
Step 3: Orchestrator 识别 domain = accounts_receivable
|
||||
Step 4: next_step = query_database
|
||||
Step 5: 权限检查用户是否可看应收数据
|
||||
Step 6: 查询应收账龄表
|
||||
Step 7: User Agent 汇总结果
|
||||
Step 8: 返回客户清单、金额、逾期天数、风险说明
|
||||
```
|
||||
|
||||
## 5. Hermes 任务示例
|
||||
|
||||
任务：
|
||||
|
||||
```text
|
||||
每日风险巡检
|
||||
```
|
||||
|
||||
流程：
|
||||
|
||||
```text
|
||||
Step 1: 任务调度器在 02:00 触发
|
||||
Step 2: Orchestrator 构造 ontology_json
|
||||
Step 3: 路由给 Hermes
|
||||
Step 4: Hermes 拉取昨日业务快照
|
||||
Step 5: 执行规则中心规则
|
||||
Step 6: 调用 MCP 验真、账款流水
|
||||
Step 7: 生成风险报告
|
||||
Step 8: 写入风险工单
|
||||
Step 9: 记录任务日志
|
||||
Step 10: 通知财务风控组
|
||||
```
|
||||
|
||||
### 5.1 Hermes 后台执行方式
|
||||
|
||||
推荐最小形态：
|
||||
|
||||
```text
|
||||
任务系统 / 手动触发 API
|
||||
↓
|
||||
Orchestrator 生成 run_id、任务上下文、权限信息
|
||||
↓
|
||||
后端调用系统 Hermes CLI 或 Hermes 后台进程
|
||||
↓
|
||||
Hermes 执行知识同步 / 风险巡检 / 规则草稿形成
|
||||
↓
|
||||
结果回写 AgentRun / ToolCall / 审计日志
|
||||
```
|
||||
|
||||
约束：
|
||||
|
||||
- Hermes 运行使用系统级配置，不在任务代码里再写一套模型配置。
|
||||
- Hermes 运行失败要记录 stderr 或等价错误摘要。
|
||||
- Hermes 输出的知识候选和规则草稿必须回写为结构化结果，不只保留终端文本。
|
||||
|
||||
## 5A. 用户报销建单示例
|
||||
|
||||
用户输入：
|
||||
|
||||
```text
|
||||
我今天去客户现场，招待了客户，花销了1000元
|
||||
```
|
||||
|
||||
流程：
|
||||
|
||||
```text
|
||||
Step 1: User Agent 接收消息
|
||||
Step 2: semantic_parser 输出 ontology_json
|
||||
Step 3: Orchestrator 判断 scenario = expense, intent = draft
|
||||
Step 4: 若缺客户、参与人、附件，则 next_step = ask_clarification
|
||||
Step 5: 补齐最小槽位后，next_step = create_expense_claim_draft
|
||||
Step 6: 创建 expense_claims / expense_claim_items
|
||||
Step 7: 若有附件，则挂接 document_assets / expense_item_documents
|
||||
Step 8: 用户确认提交后，next_step = submit_expense_claim
|
||||
Step 9: 更新 expense_claims.status = submitted
|
||||
Step 10: 写入 AgentRun、ToolCall、AuditLog
|
||||
```
|
||||
|
||||
## 6. 审计日志
|
||||
|
||||
每次 Agent 运行都应该写入审计。
|
||||
|
||||
建议字段：
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "",
|
||||
"source": "user_message | schedule | system_event",
|
||||
"agent": "hermes | user_agent",
|
||||
"user_id": "",
|
||||
"task_id": "",
|
||||
"ontology_json": {},
|
||||
"tools_called": [],
|
||||
"permission_scope": {},
|
||||
"result_summary": "",
|
||||
"action_taken": "",
|
||||
"requires_confirmation": false,
|
||||
"created_at": ""
|
||||
}
|
||||
```
|
||||
|
||||
建议补充 Trace 字段：
|
||||
|
||||
```json
|
||||
{
|
||||
"semantic_provider": "",
|
||||
"semantic_model": "",
|
||||
"semantic_prompt_version": "",
|
||||
"semantic_parse_strategy": "llm_primary | rule_fallback",
|
||||
"semantic_fallback_reason": "",
|
||||
"semantic_latency_ms": 0
|
||||
}
|
||||
```
|
||||
|
||||
## 7. 失败处理
|
||||
|
||||
### 7.1 用户交互失败
|
||||
|
||||
```text
|
||||
数据库查询失败
|
||||
返回“暂时无法查询”，记录错误
|
||||
|
||||
缺少关键字段
|
||||
返回追问
|
||||
|
||||
权限不足
|
||||
返回无权限说明
|
||||
|
||||
MCP 不可用
|
||||
返回降级说明，必要时生成待处理项
|
||||
```
|
||||
|
||||
### 7.2 Hermes 任务失败
|
||||
|
||||
```text
|
||||
任务失败
|
||||
自动重试 3 次
|
||||
|
||||
部分 MCP 失败
|
||||
标记 partial_success
|
||||
|
||||
数据不完整
|
||||
生成异常任务日志
|
||||
|
||||
连续失败
|
||||
通知管理员
|
||||
```
|
||||
@@ -1,458 +0,0 @@
|
||||
# 分阶段开发计划
|
||||
|
||||
## Phase 0：准备阶段
|
||||
|
||||
目标：统一概念和边界，不写复杂功能。
|
||||
|
||||
### Step 0.1 明确术语
|
||||
|
||||
产出：
|
||||
|
||||
- 规则：`.md` 审查规则文件。
|
||||
- 技能：可复用的 Agent 能力，如审批意见生成、风险解释。
|
||||
- MCP：外部服务连接。
|
||||
- 任务：定时或批量运行的后台作业。
|
||||
- Hermes：后台数字员工。
|
||||
- User Agent：用户流程助手。
|
||||
- Orchestrator：调度和路由层。
|
||||
- Ontology：语义本体协议。
|
||||
|
||||
### Step 0.2 冻结第一版语义字段
|
||||
|
||||
第一版只强制 8 个字段：
|
||||
|
||||
```text
|
||||
domain
|
||||
scenario
|
||||
intent
|
||||
entities
|
||||
time_range
|
||||
constraints
|
||||
risk_signals
|
||||
next_step
|
||||
```
|
||||
|
||||
### Step 0.3 建立设计文档
|
||||
|
||||
产出：
|
||||
|
||||
- 本目录所有文档。
|
||||
- 后续数据库表设计草案。
|
||||
- API 合同草案。
|
||||
|
||||
## Phase 1：任务规则中心基础建设
|
||||
|
||||
目标：先把管理后台搭起来。
|
||||
|
||||
### Step 1.1 完成前端信息架构
|
||||
|
||||
页签：
|
||||
|
||||
```text
|
||||
规则 / 技能 / MCP / 任务
|
||||
```
|
||||
|
||||
规则详情：
|
||||
|
||||
- Markdown 编辑器。
|
||||
- 审核人。
|
||||
- 审核状态。
|
||||
- 版本列表。
|
||||
- 版本切换确认。
|
||||
|
||||
技能详情：
|
||||
|
||||
- 技能配置。
|
||||
- 输入上下文。
|
||||
- 输出契约。
|
||||
- 测试样例。
|
||||
- 依赖能力。
|
||||
|
||||
MCP 详情：
|
||||
|
||||
- 服务地址。
|
||||
- 鉴权方式。
|
||||
- 权限范围。
|
||||
- 健康检查。
|
||||
- 调用记录。
|
||||
|
||||
任务详情：
|
||||
|
||||
- Cron。
|
||||
- 运行窗口。
|
||||
- 输入范围。
|
||||
- 产出对象。
|
||||
- 最近运行。
|
||||
|
||||
### Step 1.2 建立后端基础模型
|
||||
|
||||
建议表：
|
||||
|
||||
```text
|
||||
agent_rules
|
||||
agent_skills
|
||||
agent_mcp_services
|
||||
agent_tasks
|
||||
agent_asset_versions
|
||||
agent_asset_reviews
|
||||
```
|
||||
|
||||
第一阶段可以先不做完整执行，只做 CRUD。
|
||||
|
||||
### Step 1.3 规则版本与审核
|
||||
|
||||
规则上线流程：
|
||||
|
||||
```text
|
||||
草稿
|
||||
↓
|
||||
提交审核
|
||||
↓
|
||||
审核通过
|
||||
↓
|
||||
上线
|
||||
```
|
||||
|
||||
关键约束：
|
||||
|
||||
- 没有审核人不能上线。
|
||||
- 没有审核通过不能上线。
|
||||
- 上线必须生成新版本。
|
||||
- 历史版本只读。
|
||||
|
||||
## Phase 2：OCR 与财务单据标准模型
|
||||
|
||||
目标：让发票、附件、报销单和账款流水先标准化。
|
||||
|
||||
### Step 2.1 附件上传与文件分类
|
||||
|
||||
识别：
|
||||
|
||||
- 发票。
|
||||
- 行程单。
|
||||
- 合同。
|
||||
- 付款凭证。
|
||||
- 审批截图。
|
||||
|
||||
### Step 2.2 OCR MCP 接入
|
||||
|
||||
把附件转成结构化字段。
|
||||
|
||||
### Step 2.3 Invoice 标准模型
|
||||
|
||||
统一 OCR、MCP、用户填写和业务系统字段。
|
||||
|
||||
### Step 2.4 人工修正
|
||||
|
||||
允许财务人员修正 OCR 字段，并写入反馈池。
|
||||
|
||||
### Step 2.5 规则中心接入 OCR 结果
|
||||
|
||||
重复发票、附件完整性、金额不一致等规则开始使用标准模型。
|
||||
|
||||
## Phase 3：语义本体服务
|
||||
|
||||
目标：用户问题和任务配置都能转成 ontology_json。
|
||||
|
||||
### Step 3.1 建立 semantic_parser API
|
||||
|
||||
接口：
|
||||
|
||||
```text
|
||||
POST /api/v1/semantic/parse
|
||||
```
|
||||
|
||||
输入：
|
||||
|
||||
```json
|
||||
{
|
||||
"source": "user_message",
|
||||
"text": "上个月哪些客户应收逾期超过 30 天？",
|
||||
"context": {}
|
||||
}
|
||||
```
|
||||
|
||||
输出：
|
||||
|
||||
```json
|
||||
{
|
||||
"domain": "accounts_receivable",
|
||||
"scenario": "receivable_aging",
|
||||
"intent": "query",
|
||||
"entities": [],
|
||||
"time_range": {},
|
||||
"constraints": {},
|
||||
"risk_signals": [],
|
||||
"next_step": "query_database"
|
||||
}
|
||||
```
|
||||
|
||||
### Step 3.2 建立模型优先解析器
|
||||
|
||||
要求：
|
||||
|
||||
- 使用运行时模型配置，而不是写死单一 provider。
|
||||
- 输入包括文本、上下文、附件摘要和预抽取字段。
|
||||
- 输出必须是结构化 JSON，而不是自由文本。
|
||||
- 输出必须经过 Schema 校验。
|
||||
- 模型失败时必须回退到规则解析。
|
||||
|
||||
### Step 3.3 建立 ontology schema 表
|
||||
|
||||
建议表：
|
||||
|
||||
```text
|
||||
semantic_ontology_schemas
|
||||
semantic_parse_logs
|
||||
```
|
||||
|
||||
字段：
|
||||
|
||||
```text
|
||||
id
|
||||
schema_version
|
||||
schema_json
|
||||
status
|
||||
created_at
|
||||
updated_at
|
||||
```
|
||||
|
||||
### Step 3.4 建立字段级校验与澄清策略
|
||||
|
||||
至少支持：
|
||||
|
||||
- 缺少费用类型时追问。
|
||||
- 缺少业务对象时追问。
|
||||
- 短句或模糊句时追问。
|
||||
- 叙述型报销输入默认走 create/generate，而不是 query。
|
||||
- 低置信度时禁止工具执行。
|
||||
|
||||
### Step 3.5 建立解析测试集
|
||||
|
||||
至少覆盖：
|
||||
|
||||
- 报销规则解释。
|
||||
- 差旅报销创建。
|
||||
- 叙述型报销创建。
|
||||
- 发票验真。
|
||||
- 应收逾期查询。
|
||||
- 应付付款状态。
|
||||
- 每日风险巡检。
|
||||
- 知识库维护。
|
||||
- 模糊短句追问。
|
||||
- 附件输入解析。
|
||||
|
||||
## Phase 4：LLM Wiki 知识库
|
||||
|
||||
目标：让制度文档、FAQ、审批经验可被 Agent 检索和引用。
|
||||
|
||||
### Step 4.1 文档解析与分块
|
||||
|
||||
上传 PDF、Word、Excel 后抽取正文并 chunk。
|
||||
|
||||
### Step 4.2 元数据与向量索引
|
||||
|
||||
为知识块打 domain、scenario、tags、版本。
|
||||
|
||||
### Step 4.3 知识检索 API
|
||||
|
||||
User Agent 可以基于语义本体查询知识。
|
||||
|
||||
### Step 4.4 知识候选审核
|
||||
|
||||
Hermes 生成 FAQ 或条款候选，人工审核后发布。
|
||||
|
||||
## Phase 5：Orchestrator 基础版
|
||||
|
||||
目标：基于 ontology_json 做确定性路由。
|
||||
|
||||
### Step 5.1 建立路由规则
|
||||
|
||||
输入：
|
||||
|
||||
```text
|
||||
source
|
||||
domain
|
||||
scenario
|
||||
intent
|
||||
next_step
|
||||
```
|
||||
|
||||
输出：
|
||||
|
||||
```text
|
||||
agent = hermes | user_agent
|
||||
tools = []
|
||||
permission_required = []
|
||||
```
|
||||
|
||||
### Step 5.2 建立工具网关
|
||||
|
||||
第一批工具：
|
||||
|
||||
```text
|
||||
rule_engine.run
|
||||
knowledge.search
|
||||
database.query
|
||||
mcp.call
|
||||
task.create
|
||||
```
|
||||
|
||||
### Step 5.3 建立审计日志
|
||||
|
||||
所有请求都记录：
|
||||
|
||||
- 原始输入。
|
||||
- 语义 JSON。
|
||||
- 路由结果。
|
||||
- 工具调用。
|
||||
- 输出摘要。
|
||||
- 错误信息。
|
||||
|
||||
## Phase 6：User Agent 第一版
|
||||
|
||||
目标：先做只读和解释，不做强写入。
|
||||
|
||||
### Step 6.1 支持制度问答
|
||||
|
||||
流程：
|
||||
|
||||
```text
|
||||
用户问题
|
||||
-> semantic_parse
|
||||
-> search_knowledge
|
||||
-> User Agent 生成回答
|
||||
```
|
||||
|
||||
### Step 6.2 支持规则解释
|
||||
|
||||
流程：
|
||||
|
||||
```text
|
||||
用户问为什么被拦截
|
||||
-> semantic_parse
|
||||
-> run_rule
|
||||
-> search_knowledge
|
||||
-> User Agent 解释风险原因
|
||||
```
|
||||
|
||||
### Step 6.3 支持业务查询
|
||||
|
||||
先支持：
|
||||
|
||||
- 报销单状态查询。
|
||||
- 应收账龄查询。
|
||||
- 应付付款状态查询。
|
||||
|
||||
### Step 6.4 支持草稿生成
|
||||
|
||||
只生成草稿，不直接提交。
|
||||
|
||||
```text
|
||||
用户确认前不写核心状态
|
||||
```
|
||||
|
||||
## Phase 7：Hermes 第一版
|
||||
|
||||
目标：让后台数字员工开始跑任务。
|
||||
|
||||
### Step 7.1 每日风险巡检
|
||||
|
||||
输入：
|
||||
|
||||
- 昨日单据。
|
||||
- 发票。
|
||||
- 附件。
|
||||
- 付款流水。
|
||||
|
||||
输出：
|
||||
|
||||
- 风险报告。
|
||||
- 风险工单。
|
||||
- 风险统计。
|
||||
|
||||
### Step 7.2 每日财务统计
|
||||
|
||||
统计：
|
||||
|
||||
- 报销金额。
|
||||
- 报账金额。
|
||||
- 应收账龄。
|
||||
- 应付账龄。
|
||||
- 付款状态。
|
||||
- 账款异常。
|
||||
|
||||
### Step 7.3 知识候选积累
|
||||
|
||||
来源：
|
||||
|
||||
- 审批意见。
|
||||
- 驳回原因。
|
||||
- 高频问答。
|
||||
- 规则误报反馈。
|
||||
|
||||
输出：
|
||||
|
||||
- FAQ 候选。
|
||||
- 规则优化建议。
|
||||
- 制度变更摘要。
|
||||
|
||||
## Phase 8：MCP 接入
|
||||
|
||||
目标：让 Agent 能安全调用外部系统。
|
||||
|
||||
优先接入：
|
||||
|
||||
1. 发票验真 MCP。
|
||||
2. 附件 OCR MCP。
|
||||
3. 银行流水 MCP。
|
||||
4. 差旅平台 MCP。
|
||||
5. ERP/付款状态 MCP。
|
||||
|
||||
每个 MCP 必须有：
|
||||
|
||||
- 服务地址。
|
||||
- 鉴权方式。
|
||||
- 权限范围。
|
||||
- 超时设置。
|
||||
- 降级策略。
|
||||
- 健康检查。
|
||||
- 调用日志。
|
||||
|
||||
## Phase 9：规则形成与反馈闭环
|
||||
|
||||
目标：让系统持续变聪明，但不失控。
|
||||
|
||||
闭环：
|
||||
|
||||
```text
|
||||
Hermes 发现问题
|
||||
-> 生成规则优化建议
|
||||
-> 管理员审核
|
||||
-> 更新规则
|
||||
-> User Agent 使用新规则解释
|
||||
-> 反馈继续进入 Hermes
|
||||
```
|
||||
|
||||
关键限制：
|
||||
|
||||
- Hermes 只生成候选。
|
||||
- 管理员审核后才能发布。
|
||||
- 所有规则变更有版本。
|
||||
- 所有上线动作有审核人。
|
||||
|
||||
### Step 9.1 规则候选池
|
||||
|
||||
Hermes 从制度、风险案例、反馈中生成规则候选。
|
||||
|
||||
### Step 9.2 规则测试样例
|
||||
|
||||
每条规则上线前必须有测试样例。
|
||||
|
||||
### Step 9.3 反馈池
|
||||
|
||||
收集 OCR 修正、规则误报、Agent 回答反馈。
|
||||
|
||||
### Step 9.4 质量看板
|
||||
|
||||
统计误报率、修正率、回答满意度、MCP 失败率。
|
||||
@@ -1,445 +0,0 @@
|
||||
# 数据契约与治理要求
|
||||
|
||||
## 1. 推荐数据表
|
||||
|
||||
### 1.1 语义本体
|
||||
|
||||
```text
|
||||
semantic_ontology_schemas
|
||||
```
|
||||
|
||||
字段：
|
||||
|
||||
```text
|
||||
id
|
||||
schema_version
|
||||
schema_json
|
||||
status
|
||||
created_by
|
||||
created_at
|
||||
updated_at
|
||||
```
|
||||
|
||||
```text
|
||||
semantic_parse_logs
|
||||
```
|
||||
|
||||
字段：
|
||||
|
||||
```text
|
||||
id
|
||||
source
|
||||
user_id
|
||||
raw_text
|
||||
ontology_json
|
||||
confidence
|
||||
parse_strategy
|
||||
created_at
|
||||
```
|
||||
|
||||
### 1.2 Agent 资产
|
||||
|
||||
```text
|
||||
agent_rules
|
||||
agent_skills
|
||||
agent_mcp_services
|
||||
agent_tasks
|
||||
```
|
||||
|
||||
通用字段：
|
||||
|
||||
```text
|
||||
id
|
||||
code
|
||||
name
|
||||
description
|
||||
status
|
||||
owner
|
||||
reviewer
|
||||
config_json
|
||||
created_at
|
||||
updated_at
|
||||
```
|
||||
|
||||
### 1.3 版本与审核
|
||||
|
||||
```text
|
||||
agent_asset_versions
|
||||
```
|
||||
|
||||
字段：
|
||||
|
||||
```text
|
||||
id
|
||||
asset_type
|
||||
asset_id
|
||||
version
|
||||
content
|
||||
change_note
|
||||
created_by
|
||||
created_at
|
||||
```
|
||||
|
||||
```text
|
||||
agent_asset_reviews
|
||||
```
|
||||
|
||||
字段：
|
||||
|
||||
```text
|
||||
id
|
||||
asset_type
|
||||
asset_id
|
||||
version
|
||||
reviewer
|
||||
review_status
|
||||
review_note
|
||||
reviewed_at
|
||||
```
|
||||
|
||||
### 1.4 运行日志
|
||||
|
||||
```text
|
||||
agent_runs
|
||||
```
|
||||
|
||||
字段：
|
||||
|
||||
```text
|
||||
id
|
||||
agent
|
||||
source
|
||||
task_id
|
||||
user_id
|
||||
ontology_json
|
||||
status
|
||||
started_at
|
||||
finished_at
|
||||
result_summary
|
||||
error_message
|
||||
```
|
||||
|
||||
```text
|
||||
agent_tool_calls
|
||||
```
|
||||
|
||||
字段：
|
||||
|
||||
```text
|
||||
id
|
||||
run_id
|
||||
tool_type
|
||||
tool_name
|
||||
request_json
|
||||
response_json
|
||||
status
|
||||
duration_ms
|
||||
created_at
|
||||
```
|
||||
|
||||
### 1.5 财务业务主表
|
||||
|
||||
```text
|
||||
expense_claims
|
||||
expense_claim_items
|
||||
accounts_receivable
|
||||
accounts_payable
|
||||
approval_records
|
||||
```
|
||||
|
||||
治理要求：
|
||||
|
||||
- `expense_claims` 作为报销主表，不再继续扩张 `reimbursement_requests`。
|
||||
- `expense_claim_items` 作为报销明细最小粒度，OCR 匹配、风险识别、票据挂接都优先挂到该粒度。
|
||||
- `accounts_receivable` 与 `accounts_payable` 保持独立，避免因为 Agent 语义层接入而混用口径。
|
||||
|
||||
### 1.6 票据与文件资产表
|
||||
|
||||
```text
|
||||
document_assets
|
||||
document_asset_versions
|
||||
document_derivatives
|
||||
expense_item_documents
|
||||
document_access_logs
|
||||
```
|
||||
|
||||
职责：
|
||||
|
||||
- `document_assets`：原始附件主索引
|
||||
- `document_asset_versions`：原件版本留痕
|
||||
- `document_derivatives`：预览件、缩略图、脱敏件、逐页图片
|
||||
- `expense_item_documents`：报销明细与票据关联
|
||||
- `document_access_logs`：预览、下载、导出审计
|
||||
|
||||
### 1.7 OCR、验真与风险表
|
||||
|
||||
```text
|
||||
document_ocr_results
|
||||
invoice_structured_records
|
||||
invoice_verification_records
|
||||
risk_events
|
||||
risk_actions
|
||||
```
|
||||
|
||||
职责：
|
||||
|
||||
- `document_ocr_results`：每次 OCR 执行快照
|
||||
- `invoice_structured_records`：标准化发票字段
|
||||
- `invoice_verification_records`：发票验真结果留痕
|
||||
- `risk_events`：风险命中事实
|
||||
- `risk_actions`：风险处置动作
|
||||
|
||||
## 2. API 契约
|
||||
|
||||
### 2.1 语义解析
|
||||
|
||||
```text
|
||||
POST /api/v1/semantic/parse
|
||||
```
|
||||
|
||||
请求：
|
||||
|
||||
```json
|
||||
{
|
||||
"source": "user_message",
|
||||
"text": "这张发票为什么被拦截？",
|
||||
"context": {
|
||||
"user_id": "emp_001",
|
||||
"current_page": "reimbursement_detail"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
响应：
|
||||
|
||||
```json
|
||||
{
|
||||
"domain": "reimbursement",
|
||||
"scenario": "invoice_validation",
|
||||
"intent": "explain",
|
||||
"entities": [],
|
||||
"time_range": {},
|
||||
"constraints": {},
|
||||
"risk_signals": ["unknown"],
|
||||
"parse_strategy": "llm_primary",
|
||||
"next_step": "run_rule"
|
||||
}
|
||||
```
|
||||
|
||||
### 2.2 Orchestrator 执行
|
||||
|
||||
```text
|
||||
POST /api/v1/agent/orchestrate
|
||||
```
|
||||
|
||||
请求：
|
||||
|
||||
```json
|
||||
{
|
||||
"source": "user_message",
|
||||
"ontology": {},
|
||||
"context": {}
|
||||
}
|
||||
```
|
||||
|
||||
响应：
|
||||
|
||||
```json
|
||||
{
|
||||
"agent": "user_agent",
|
||||
"tools_called": [],
|
||||
"answer": "",
|
||||
"requires_confirmation": false,
|
||||
"audit_id": ""
|
||||
}
|
||||
```
|
||||
|
||||
### 2.3 文件上传契约
|
||||
|
||||
```text
|
||||
POST /api/v1/documents/upload
|
||||
```
|
||||
|
||||
请求：
|
||||
|
||||
```json
|
||||
{
|
||||
"biz_domain": "expense",
|
||||
"biz_object_type": "expense_claim",
|
||||
"biz_object_id": "claim_001",
|
||||
"upload_source": "user_workbench",
|
||||
"files": [
|
||||
{
|
||||
"filename": "invoice.jpg",
|
||||
"mime_type": "image/jpeg"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
响应：
|
||||
|
||||
```json
|
||||
{
|
||||
"documents": [
|
||||
{
|
||||
"document_id": "",
|
||||
"version_no": 1,
|
||||
"storage_status": "stored",
|
||||
"ocr_status": "pending"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 2.4 Hermes 任务
|
||||
|
||||
```text
|
||||
POST /api/v1/hermes/tasks/run
|
||||
```
|
||||
|
||||
请求：
|
||||
|
||||
```json
|
||||
{
|
||||
"task_code": "daily_risk_scan",
|
||||
"ontology": {},
|
||||
"dry_run": false,
|
||||
"context_json": {
|
||||
"folder": "报销制度",
|
||||
"changed_only": true,
|
||||
"force": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
响应：
|
||||
|
||||
```json
|
||||
{
|
||||
"run_id": "",
|
||||
"status": "accepted"
|
||||
}
|
||||
```
|
||||
|
||||
补充：
|
||||
|
||||
- Hermes 任务应优先调用系统后台 Hermes CLI 或等价 Hermes 进程。
|
||||
- `changed_only=true` 时，只处理知识库中发生变化的文档。
|
||||
- 文档变化判断至少包含 `original_name`、`stored_name`、`sha256`、`version_number`、`updated_at`。
|
||||
- 若文档无变化，应返回 `unchanged_skipped`，而不是重新形成 LLM Wiki。
|
||||
|
||||
## 3. 安全原则
|
||||
|
||||
### 3.1 最小权限
|
||||
|
||||
Agent 调工具时不能使用超级权限。
|
||||
|
||||
权限来源：
|
||||
|
||||
- 用户权限
|
||||
- 任务权限
|
||||
- 服务账号权限
|
||||
|
||||
### 3.2 高风险动作确认
|
||||
|
||||
以下动作必须确认：
|
||||
|
||||
- 提交报销
|
||||
- 发起付款
|
||||
- 生成正式审批意见
|
||||
- 发布规则
|
||||
- 发布知识库
|
||||
- 创建外部通知
|
||||
|
||||
### 3.3 审计不可省略
|
||||
|
||||
必须记录：
|
||||
|
||||
- 谁触发
|
||||
- 输入是什么
|
||||
- 解析结果是什么
|
||||
- 调了哪些工具
|
||||
- 输出是什么
|
||||
- 是否确认
|
||||
|
||||
### 3.4 文件存储治理
|
||||
|
||||
必须遵守：
|
||||
|
||||
- 原始文件二进制不落业务主表，不存入大字段 blob。
|
||||
- 所有文件必须有 `storage_provider`、`storage_key`、`sha256`、`file_size_bytes`、`mime_type`。
|
||||
- 原件不可覆盖，只能新增版本。
|
||||
- 删除默认是解除业务关联或逻辑删除，物理删除必须走审计流程。
|
||||
- 对象存储访问必须使用签名 URL 或后端代理，不直接暴露固定公网地址。
|
||||
|
||||
### 3.5 敏感数据治理
|
||||
|
||||
对于发票、行程单、合同、付款凭证中的敏感信息：
|
||||
|
||||
- 应支持脱敏衍生件
|
||||
- 应记录查看与下载行为
|
||||
- 应区分申请人、审批人、财务、管理员可见范围
|
||||
- 应支持争议单据 `legal_hold` 保留策略
|
||||
|
||||
### 3.6 AI 证据治理
|
||||
|
||||
Agent 和 OCR 相关能力必须遵守：
|
||||
|
||||
- 未经 OCR/VLM 实际解析，不得假设附件内容已知。
|
||||
- Agent 输出若引用发票金额、号码、日期，必须能追溯到 `invoice_structured_records` 或人工修正记录。
|
||||
- 风险解释若引用“重复报销”“金额不一致”等判断，必须能追溯到 `risk_events.evidence_json`。
|
||||
|
||||
## 4. 数据质量要求
|
||||
|
||||
### 4.1 关键唯一性
|
||||
|
||||
- `expense_claims.claim_no` 唯一
|
||||
- `document_assets.sha256` 可重复但必须可检索
|
||||
- `document_asset_versions(document_id, version_no)` 唯一
|
||||
- `invoice_structured_records.duplicate_fingerprint` 必须可索引
|
||||
|
||||
### 4.2 时间与状态字段
|
||||
|
||||
- 所有业务主表必须有 `created_at`、`updated_at`
|
||||
- 文件上传、OCR、验真、风控、处置必须有独立时间戳
|
||||
- 状态字段应使用受控枚举，不允许前端自由拼写
|
||||
|
||||
### 4.3 可追溯性
|
||||
|
||||
任一笔报销单、发票或风险结论，至少应能追到：
|
||||
|
||||
- 原始输入文本
|
||||
- 原始附件
|
||||
- 结构化结果
|
||||
- 规则或模型判断
|
||||
- 人工修正动作
|
||||
|
||||
## 5. 实施优先级
|
||||
|
||||
第一优先级：
|
||||
|
||||
- `expense_claims`
|
||||
- `expense_claim_items`
|
||||
- `document_assets`
|
||||
- `document_asset_versions`
|
||||
- `expense_item_documents`
|
||||
|
||||
第二优先级：
|
||||
|
||||
- `document_ocr_results`
|
||||
- `invoice_structured_records`
|
||||
- `invoice_verification_records`
|
||||
- `document_derivatives`
|
||||
|
||||
第三优先级：
|
||||
|
||||
- `risk_events`
|
||||
- `risk_actions`
|
||||
- `document_access_logs`
|
||||
|
||||
实施原则：
|
||||
|
||||
- 先确保“能收、能存、能找回原件”
|
||||
- 再确保“能识别、能验真、能回填”
|
||||
- 最后做“能解释、能审计、能批量巡检”
|
||||
@@ -1,198 +0,0 @@
|
||||
# Capability Registry 能力注册中心
|
||||
|
||||
## 1. 为什么需要能力注册中心
|
||||
|
||||
双 Agent 架构里会出现很多能力：
|
||||
|
||||
- 规则文件。
|
||||
- 技能。
|
||||
- MCP 服务。
|
||||
- 数据库查询。
|
||||
- 知识库检索。
|
||||
- 定时任务。
|
||||
- 报告生成。
|
||||
|
||||
如果 Orchestrator 直接在代码里硬编码这些能力，会导致：
|
||||
|
||||
- 能力越来越多后难维护。
|
||||
- 无法统一权限。
|
||||
- 无法统一版本。
|
||||
- 无法统一输入输出格式。
|
||||
- Hermes 和 User Agent 复用困难。
|
||||
|
||||
因此建议建立 Capability Registry。
|
||||
|
||||
它的定位是：
|
||||
|
||||
```text
|
||||
所有可被 Agent 调用的能力目录
|
||||
```
|
||||
|
||||
## 2. 能力类型
|
||||
|
||||
建议第一版支持：
|
||||
|
||||
```text
|
||||
rule
|
||||
skill
|
||||
mcp
|
||||
task
|
||||
database_query
|
||||
knowledge_search
|
||||
report_generator
|
||||
notification
|
||||
```
|
||||
|
||||
含义：
|
||||
|
||||
- `rule`：审查规则，通常是 `.md` 文件或规则配置。
|
||||
- `skill`：智能能力，如审批意见生成、风险解释。
|
||||
- `mcp`：外部服务连接。
|
||||
- `task`：定时或批量任务。
|
||||
- `database_query`：受控数据库查询能力。
|
||||
- `knowledge_search`：知识库检索能力。
|
||||
- `report_generator`：报告生成能力。
|
||||
- `notification`：通知能力。
|
||||
|
||||
## 3. 能力注册结构
|
||||
|
||||
建议结构：
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "cap_rule_duplicate_invoice",
|
||||
"code": "duplicate_invoice_rule",
|
||||
"name": "重复报销识别规则",
|
||||
"capability_type": "rule",
|
||||
"domain": "reimbursement",
|
||||
"scenarios": ["invoice_validation", "reimbursement_audit"],
|
||||
"intents": ["validate", "explain", "monitor"],
|
||||
"input_schema": {},
|
||||
"output_schema": {},
|
||||
"permission_required": ["reimbursement:read", "risk:write"],
|
||||
"risk_level": "high",
|
||||
"owner": "财务风控组",
|
||||
"version": "v1.9",
|
||||
"status": "active",
|
||||
"requires_confirmation": false,
|
||||
"created_at": "",
|
||||
"updated_at": ""
|
||||
}
|
||||
```
|
||||
|
||||
## 4. 与语义本体的匹配关系
|
||||
|
||||
Orchestrator 根据 ontology_json 匹配能力。
|
||||
|
||||
示例：
|
||||
|
||||
```json
|
||||
{
|
||||
"domain": "reimbursement",
|
||||
"scenario": "invoice_validation",
|
||||
"intent": "explain",
|
||||
"risk_signals": ["duplicate_invoice"],
|
||||
"next_step": "run_rule"
|
||||
}
|
||||
```
|
||||
|
||||
可以匹配：
|
||||
|
||||
```text
|
||||
重复报销识别规则
|
||||
发票验真 MCP
|
||||
风险解释技能
|
||||
制度知识库检索
|
||||
```
|
||||
|
||||
## 5. 能力匹配优先级
|
||||
|
||||
建议顺序：
|
||||
|
||||
```text
|
||||
Step 1: next_step 决定能力大类
|
||||
Step 2: domain 限定业务域
|
||||
Step 3: scenario 限定场景
|
||||
Step 4: risk_signals 匹配具体规则
|
||||
Step 5: intent 匹配技能
|
||||
Step 6: permission_required 校验权限
|
||||
Step 7: status 必须 active
|
||||
Step 8: version 使用当前上线版本
|
||||
```
|
||||
|
||||
## 6. 数据表建议
|
||||
|
||||
```text
|
||||
agent_capabilities
|
||||
```
|
||||
|
||||
字段：
|
||||
|
||||
```text
|
||||
id
|
||||
code
|
||||
name
|
||||
capability_type
|
||||
domain
|
||||
scenario_json
|
||||
intent_json
|
||||
input_schema_json
|
||||
output_schema_json
|
||||
permission_json
|
||||
risk_level
|
||||
owner
|
||||
current_version
|
||||
status
|
||||
requires_confirmation
|
||||
config_json
|
||||
created_at
|
||||
updated_at
|
||||
```
|
||||
|
||||
## 7. 开发步骤
|
||||
|
||||
### Step 1: 先注册静态能力
|
||||
|
||||
先把现有规则、技能、MCP、任务写入 Registry。
|
||||
|
||||
不需要一开始做复杂 UI。
|
||||
|
||||
### Step 2: Orchestrator 改为查 Registry
|
||||
|
||||
从：
|
||||
|
||||
```text
|
||||
if next_step = run_rule then call duplicate_invoice_rule
|
||||
```
|
||||
|
||||
改为：
|
||||
|
||||
```text
|
||||
query capabilities where type = rule and scenario = invoice_validation
|
||||
```
|
||||
|
||||
### Step 3: 加权限过滤
|
||||
|
||||
只返回当前用户或任务有权限调用的能力。
|
||||
|
||||
### Step 4: 加版本选择
|
||||
|
||||
默认使用 active 版本。
|
||||
|
||||
历史版本只用于回放和调试。
|
||||
|
||||
### Step 5: 加健康状态
|
||||
|
||||
MCP、任务、数据库查询能力应有健康状态。
|
||||
|
||||
不可用时 Orchestrator 走降级策略。
|
||||
|
||||
## 8. 治理要求
|
||||
|
||||
- 所有能力必须有 owner。
|
||||
- 高风险能力必须有 reviewer。
|
||||
- 所有能力必须有输入输出 schema。
|
||||
- 所有能力必须有状态。
|
||||
- 下线能力不能被 Orchestrator 调用。
|
||||
- 能力版本变更必须写入审计。
|
||||
|
||||
@@ -1,214 +0,0 @@
|
||||
# 权限与确认引擎
|
||||
|
||||
## 1. 目标
|
||||
|
||||
Agent 不能只靠提示词判断能不能执行动作。
|
||||
|
||||
财务系统需要独立的权限与确认引擎：
|
||||
|
||||
```text
|
||||
Permission Engine
|
||||
Confirmation Engine
|
||||
```
|
||||
|
||||
它们负责：
|
||||
|
||||
- 判断用户是否能看某类数据。
|
||||
- 判断任务是否能调用某个能力。
|
||||
- 判断动作是否需要确认。
|
||||
- 判断动作是否禁止自动执行。
|
||||
|
||||
## 2. 动作风险分级
|
||||
|
||||
建议按 L0-L5 分级。
|
||||
|
||||
### L0 只读查询
|
||||
|
||||
例子：
|
||||
|
||||
- 查询制度。
|
||||
- 查询单据状态。
|
||||
- 查询规则说明。
|
||||
- 查询任务运行记录。
|
||||
|
||||
要求：
|
||||
|
||||
- 需要权限。
|
||||
- 不需要确认。
|
||||
|
||||
### L1 生成建议
|
||||
|
||||
例子：
|
||||
|
||||
- 生成审批意见建议。
|
||||
- 生成风险解释。
|
||||
- 生成规则优化建议。
|
||||
|
||||
要求：
|
||||
|
||||
- 需要权限。
|
||||
- 不写业务状态。
|
||||
- 不需要确认，但要标记为建议。
|
||||
|
||||
### L2 生成草稿
|
||||
|
||||
例子：
|
||||
|
||||
- 生成报销草稿。
|
||||
- 生成付款申请草稿。
|
||||
- 生成知识库候选。
|
||||
|
||||
要求：
|
||||
|
||||
- 需要权限。
|
||||
- 写入草稿区。
|
||||
- 不进入正式流程。
|
||||
|
||||
### L3 用户确认后提交
|
||||
|
||||
例子：
|
||||
|
||||
- 用户确认后提交报销。
|
||||
- 审批人确认后写入审批意见。
|
||||
- 用户确认后发起补件。
|
||||
|
||||
要求：
|
||||
|
||||
- 必须二次确认。
|
||||
- 必须记录确认人。
|
||||
- 必须记录确认前后内容。
|
||||
|
||||
### L4 管理员确认后发布
|
||||
|
||||
例子：
|
||||
|
||||
- 发布规则。
|
||||
- 发布知识库。
|
||||
- 启用 MCP。
|
||||
- 启用任务。
|
||||
|
||||
要求：
|
||||
|
||||
- 必须管理员确认。
|
||||
- 必须有审核记录。
|
||||
- 必须有版本。
|
||||
|
||||
### L5 禁止自动执行
|
||||
|
||||
例子：
|
||||
|
||||
- 自动最终审批。
|
||||
- 自动付款。
|
||||
- 自动绕过风控。
|
||||
- 自动修改核心财务状态。
|
||||
|
||||
要求：
|
||||
|
||||
- Agent 永远不能直接执行。
|
||||
|
||||
## 3. 权限判断输入
|
||||
|
||||
```json
|
||||
{
|
||||
"user_id": "emp_001",
|
||||
"agent": "user_agent",
|
||||
"source": "user_message",
|
||||
"action": "create_reimbursement_draft",
|
||||
"domain": "reimbursement",
|
||||
"resource": {
|
||||
"type": "reimbursement_request",
|
||||
"id": ""
|
||||
},
|
||||
"capability": "travel_reimbursement_create"
|
||||
}
|
||||
```
|
||||
|
||||
## 4. 权限判断输出
|
||||
|
||||
```json
|
||||
{
|
||||
"allowed": true,
|
||||
"risk_level": "L2",
|
||||
"requires_confirmation": false,
|
||||
"reason": "",
|
||||
"permission_scope": {
|
||||
"departments": ["current_user"],
|
||||
"data_masking": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 5. 确认弹窗策略
|
||||
|
||||
需要确认的动作必须显示：
|
||||
|
||||
- 动作名称。
|
||||
- 影响对象。
|
||||
- 关键字段。
|
||||
- 执行后果。
|
||||
- 是否可撤销。
|
||||
- 确认人。
|
||||
|
||||
示例：
|
||||
|
||||
```json
|
||||
{
|
||||
"title": "确认提交报销申请",
|
||||
"action": "submit_reimbursement",
|
||||
"summary": "将提交差旅报销单 TR-202605001，金额 ¥3,280。",
|
||||
"risk_level": "L3",
|
||||
"confirm_button": "确认提交"
|
||||
}
|
||||
```
|
||||
|
||||
## 6. Hermes 权限
|
||||
|
||||
Hermes 使用服务账号，不使用个人账号。
|
||||
|
||||
建议拆分权限：
|
||||
|
||||
```text
|
||||
hermes:risk_scan
|
||||
hermes:finance_statistics
|
||||
hermes:knowledge_candidate
|
||||
hermes:mcp_health_check
|
||||
```
|
||||
|
||||
Hermes 默认只允许：
|
||||
|
||||
- 读脱敏快照。
|
||||
- 跑规则。
|
||||
- 调只读 MCP。
|
||||
- 写报告、候选、工单。
|
||||
|
||||
Hermes 不允许：
|
||||
|
||||
- 写正式审批状态。
|
||||
- 写正式付款状态。
|
||||
- 发布规则。
|
||||
- 发布知识。
|
||||
|
||||
## 7. User Agent 权限
|
||||
|
||||
User Agent 继承当前用户权限。
|
||||
|
||||
例如：
|
||||
|
||||
- 员工只能看自己的报销。
|
||||
- 部门负责人可以看本部门。
|
||||
- 财务可以看授权范围内数据。
|
||||
- 管理员可以管理规则、任务、MCP。
|
||||
|
||||
User Agent 不能扩大用户权限。
|
||||
|
||||
## 8. 开发步骤
|
||||
|
||||
```text
|
||||
Step 1: 定义 action risk level
|
||||
Step 2: 建立 Permission Engine 接口
|
||||
Step 3: 所有工具调用前接入权限判断
|
||||
Step 4: L3/L4 动作接入确认弹窗
|
||||
Step 5: 审计记录确认内容
|
||||
Step 6: 增加权限测试用例
|
||||
```
|
||||
|
||||
@@ -1,186 +0,0 @@
|
||||
# 可观测性与 Agent Run Trace
|
||||
|
||||
## 1. 目标
|
||||
|
||||
Agent 系统必须可追踪、可回放、可解释。
|
||||
|
||||
财务系统中尤其需要回答：
|
||||
|
||||
- 为什么 Agent 得出这个结论？
|
||||
- 用了哪个模型？
|
||||
- 用了哪个规则版本？
|
||||
- 调用了哪些 MCP？
|
||||
- 查了哪些数据？
|
||||
- 谁确认了动作？
|
||||
- 失败在哪里？
|
||||
|
||||
## 2. Agent Run Trace
|
||||
|
||||
每次 Agent 运行都生成一个 run_id。
|
||||
|
||||
建议结构：
|
||||
|
||||
```json
|
||||
{
|
||||
"run_id": "",
|
||||
"source": "user_message",
|
||||
"agent": "user_agent",
|
||||
"user_id": "emp_001",
|
||||
"raw_input": "",
|
||||
"ontology_json": {},
|
||||
"route_decision": {},
|
||||
"permission_result": {},
|
||||
"tool_calls": [],
|
||||
"final_output": "",
|
||||
"status": "success",
|
||||
"started_at": "",
|
||||
"finished_at": ""
|
||||
}
|
||||
```
|
||||
|
||||
## 3. 需要记录的版本
|
||||
|
||||
每次运行都要记录：
|
||||
|
||||
```text
|
||||
ontology_schema_version
|
||||
semantic_parser_prompt_version
|
||||
model_name
|
||||
model_version
|
||||
rule_version
|
||||
skill_version
|
||||
mcp_version
|
||||
knowledge_snapshot_version
|
||||
orchestrator_version
|
||||
```
|
||||
|
||||
原因：
|
||||
|
||||
用户可能问：
|
||||
|
||||
```text
|
||||
为什么昨天和今天的结论不一样？
|
||||
```
|
||||
|
||||
只有记录版本，才能解释。
|
||||
|
||||
## 4. Tool Call Trace
|
||||
|
||||
每个工具调用都记录：
|
||||
|
||||
```json
|
||||
{
|
||||
"tool_call_id": "",
|
||||
"run_id": "",
|
||||
"tool_type": "mcp",
|
||||
"tool_name": "invoice_verify",
|
||||
"request_json": {},
|
||||
"response_json": {},
|
||||
"status": "success",
|
||||
"duration_ms": 820,
|
||||
"error_message": ""
|
||||
}
|
||||
```
|
||||
|
||||
敏感字段应脱敏。
|
||||
|
||||
## 5. 运行状态
|
||||
|
||||
建议枚举：
|
||||
|
||||
```text
|
||||
pending
|
||||
running
|
||||
success
|
||||
partial_success
|
||||
failed
|
||||
cancelled
|
||||
waiting_confirmation
|
||||
```
|
||||
|
||||
## 6. Hermes 可观测性
|
||||
|
||||
Hermes 任务需要额外记录：
|
||||
|
||||
```text
|
||||
task_code
|
||||
schedule_time
|
||||
data_snapshot_id
|
||||
records_scanned
|
||||
rules_executed
|
||||
mcp_calls
|
||||
risk_items_generated
|
||||
knowledge_candidates_generated
|
||||
retry_count
|
||||
```
|
||||
|
||||
示例：
|
||||
|
||||
```json
|
||||
{
|
||||
"task_code": "daily_risk_scan",
|
||||
"records_scanned": 2146,
|
||||
"rules_executed": 8,
|
||||
"mcp_calls": 436,
|
||||
"risk_items_generated": 19,
|
||||
"status": "success"
|
||||
}
|
||||
```
|
||||
|
||||
## 7. User Agent 可观测性
|
||||
|
||||
User Agent 需要额外记录：
|
||||
|
||||
```text
|
||||
conversation_id
|
||||
page_context
|
||||
user_confirmation
|
||||
draft_created
|
||||
business_object_id
|
||||
```
|
||||
|
||||
## 8. 前端审计视图
|
||||
|
||||
建议后续增加“Agent 运行记录”页面。
|
||||
|
||||
展示：
|
||||
|
||||
- 运行时间。
|
||||
- Agent 类型。
|
||||
- 用户或任务。
|
||||
- 语义解析结果。
|
||||
- 调用工具。
|
||||
- 运行状态。
|
||||
- 耗时。
|
||||
- 错误。
|
||||
|
||||
详情页展示：
|
||||
|
||||
- 原始输入。
|
||||
- 本体 JSON。
|
||||
- 路由决策。
|
||||
- 工具调用链。
|
||||
- 最终输出。
|
||||
|
||||
## 9. 告警
|
||||
|
||||
需要告警的情况：
|
||||
|
||||
- Hermes 任务连续失败。
|
||||
- MCP 健康检查失败。
|
||||
- 语义解析低置信度比例过高。
|
||||
- 某规则误报率过高。
|
||||
- Agent 调用耗时异常。
|
||||
- 权限拒绝次数异常。
|
||||
|
||||
## 10. 开发步骤
|
||||
|
||||
```text
|
||||
Step 1: 增加 agent_runs 表
|
||||
Step 2: 增加 agent_tool_calls 表
|
||||
Step 3: Orchestrator 每次执行创建 run_id
|
||||
Step 4: 工具网关记录 tool call
|
||||
Step 5: 前端增加运行记录页面
|
||||
Step 6: 增加异常告警规则
|
||||
```
|
||||
|
||||
@@ -1,198 +0,0 @@
|
||||
# 评测集与质量控制
|
||||
|
||||
## 1. 为什么需要评测集
|
||||
|
||||
语义解析、本体字段、Agent 路由、规则命中都不能只靠人工感觉。
|
||||
|
||||
每次修改 prompt、模型、规则或路由逻辑，都应该运行评测集。
|
||||
|
||||
目标：
|
||||
|
||||
- 检查 domain 是否识别正确。
|
||||
- 检查 scenario 是否识别正确。
|
||||
- 检查 intent 是否识别正确。
|
||||
- 检查 next_step 是否正确。
|
||||
- 检查是否应该追问。
|
||||
- 检查是否错误调用高风险工具。
|
||||
|
||||
## 2. 第一版评测集规模
|
||||
|
||||
建议第一版至少 300 条。
|
||||
|
||||
```text
|
||||
报销问题：80 条
|
||||
应收问题：60 条
|
||||
应付问题：60 条
|
||||
制度问答：40 条
|
||||
风险解释：30 条
|
||||
定时任务：20 条
|
||||
模糊问题：10 条
|
||||
叙述型报销：20 条
|
||||
附件输入：10 条
|
||||
```
|
||||
|
||||
## 3. 评测样例结构
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "eval_001",
|
||||
"input": "上个月哪些客户应收逾期超过 30 天？",
|
||||
"expected": {
|
||||
"domain": "accounts_receivable",
|
||||
"scenario": "receivable_aging",
|
||||
"intent": "query",
|
||||
"next_step": "query_database"
|
||||
},
|
||||
"required_entities": ["customer"],
|
||||
"notes": "应识别为应收账龄查询"
|
||||
}
|
||||
```
|
||||
|
||||
## 4. 评测指标
|
||||
|
||||
### 4.1 字段准确率
|
||||
|
||||
```text
|
||||
domain_accuracy
|
||||
scenario_accuracy
|
||||
intent_accuracy
|
||||
next_step_accuracy
|
||||
field_level_f1
|
||||
clarification_accuracy
|
||||
```
|
||||
|
||||
### 4.2 工具路由准确率
|
||||
|
||||
```text
|
||||
tool_route_accuracy
|
||||
permission_decision_accuracy
|
||||
confirmation_decision_accuracy
|
||||
narrative_misroute_rate
|
||||
```
|
||||
|
||||
### 4.3 安全指标
|
||||
|
||||
```text
|
||||
unsafe_action_rate
|
||||
missing_confirmation_rate
|
||||
permission_bypass_rate
|
||||
low_confidence_unsafe_tool_rate
|
||||
```
|
||||
|
||||
这些指标必须接近 0。
|
||||
|
||||
## 5. 低置信度处理
|
||||
|
||||
语义解析输出应包含：
|
||||
|
||||
```json
|
||||
{
|
||||
"confidence": 0.62,
|
||||
"missing_slots": ["time_range"],
|
||||
"ambiguity": ["应收逾期还是审批逾期"]
|
||||
}
|
||||
```
|
||||
|
||||
当置信度低于阈值：
|
||||
|
||||
```text
|
||||
confidence < 0.75
|
||||
不执行工具
|
||||
返回追问
|
||||
```
|
||||
|
||||
## 6. 模糊问题样例
|
||||
|
||||
用户问：
|
||||
|
||||
```text
|
||||
这个为什么还没处理？
|
||||
```
|
||||
|
||||
不能直接执行查询。
|
||||
|
||||
应该追问：
|
||||
|
||||
```text
|
||||
你是想查询报销单、应收款还是付款申请的处理状态？
|
||||
```
|
||||
|
||||
叙述型报销样例：
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "eval_reimbursement_narrative_001",
|
||||
"input": "我今天去客户现场，招待了客户，花销了1000元",
|
||||
"expected": {
|
||||
"domain": "reimbursement",
|
||||
"scenario": "daily_expense",
|
||||
"intent": "create",
|
||||
"next_step": "ask_clarification"
|
||||
},
|
||||
"required_entities": ["amount"],
|
||||
"notes": "不能错误路由到应收查询"
|
||||
}
|
||||
```
|
||||
|
||||
## 7. 回归测试流程
|
||||
|
||||
每次改动以下内容都要跑评测：
|
||||
|
||||
- semantic parser 模型或 provider。
|
||||
- semantic parser prompt。
|
||||
- ontology schema。
|
||||
- Orchestrator 路由。
|
||||
- 规则中心匹配逻辑。
|
||||
- MCP 能力注册。
|
||||
- 模型版本。
|
||||
|
||||
流程：
|
||||
|
||||
```text
|
||||
Step 1: 加载评测集
|
||||
Step 2: 批量调用 semantic_parse
|
||||
Step 3: 批量调用 route_decision
|
||||
Step 4: 对比 expected
|
||||
Step 5: 输出准确率报告
|
||||
Step 6: 阻止低于阈值的发布
|
||||
```
|
||||
|
||||
## 8. 发布阈值
|
||||
|
||||
建议第一版阈值：
|
||||
|
||||
```text
|
||||
domain_accuracy >= 95%
|
||||
intent_accuracy >= 90%
|
||||
next_step_accuracy >= 90%
|
||||
unsafe_action_rate = 0
|
||||
missing_confirmation_rate = 0
|
||||
narrative_misroute_rate <= 1%
|
||||
low_confidence_unsafe_tool_rate = 0
|
||||
```
|
||||
|
||||
## 9. 评测数据管理
|
||||
|
||||
建议文件结构：
|
||||
|
||||
```text
|
||||
server/tests/fixtures/semantic_eval/
|
||||
reimbursement.jsonl
|
||||
accounts_receivable.jsonl
|
||||
accounts_payable.jsonl
|
||||
risk_explain.jsonl
|
||||
scheduled_tasks.jsonl
|
||||
```
|
||||
|
||||
每行一个样例。
|
||||
|
||||
## 10. 开发步骤
|
||||
|
||||
```text
|
||||
Step 1: 建立 JSONL 评测集格式
|
||||
Step 2: 写 50 条人工样例
|
||||
Step 3: 接入 semantic_parse 批测脚本
|
||||
Step 4: 输出 markdown/html 评测报告
|
||||
Step 5: 扩展到 300 条
|
||||
Step 6: 接入 CI 或手动发布检查
|
||||
```
|
||||
@@ -1,376 +0,0 @@
|
||||
# OCR 票据识别架构
|
||||
|
||||
## 1. 定位
|
||||
|
||||
OCR 票据识别不是一个简单的图片转文字功能。
|
||||
|
||||
它在 X-Financial 中承担四件事：
|
||||
|
||||
1. 把用户上传的附件变成结构化票据信息。
|
||||
2. 为规则中心提供可判断的字段。
|
||||
3. 为 User Agent 和 Hermes 提供可解释的证据。
|
||||
4. 为后续审计、复核、争议处理保留可回溯原件。
|
||||
|
||||
因此 OCR 应作为独立能力纳入 Capability Registry。
|
||||
|
||||
```text
|
||||
capability_type = mcp | document_processor
|
||||
capability_code = invoice_ocr
|
||||
```
|
||||
|
||||
## 2. 总体链路
|
||||
|
||||
```text
|
||||
附件上传
|
||||
↓
|
||||
文件落盘 / 对象存储
|
||||
↓
|
||||
文件分类
|
||||
↓
|
||||
OCR 识别
|
||||
↓
|
||||
字段结构化
|
||||
↓
|
||||
票据类型归一化
|
||||
↓
|
||||
发票验真 MCP
|
||||
↓
|
||||
与报销明细匹配
|
||||
↓
|
||||
规则中心检查
|
||||
↓
|
||||
人工修正
|
||||
↓
|
||||
修正结果沉淀
|
||||
```
|
||||
|
||||
关键原则：
|
||||
|
||||
- 文件先持久化，再做 OCR，不允许只在内存里跑完就丢。
|
||||
- 原件不可覆盖，只能新增版本。
|
||||
- Agent 不得假设图片内容已知；只有 OCR/VLM 实际解析后才能引用附件内容。
|
||||
|
||||
## 3. 阶段拆分
|
||||
|
||||
### Phase A：附件接入与文件分类
|
||||
|
||||
目标：先识别上传的是什么。
|
||||
|
||||
输入：
|
||||
|
||||
- 图片
|
||||
- PDF
|
||||
- Excel
|
||||
- Word
|
||||
- 压缩包
|
||||
|
||||
输出：
|
||||
|
||||
```json
|
||||
{
|
||||
"document_type": "invoice",
|
||||
"mime_type": "image/png",
|
||||
"page_count": 1,
|
||||
"confidence": 0.91
|
||||
}
|
||||
```
|
||||
|
||||
分类结果：
|
||||
|
||||
```text
|
||||
invoice
|
||||
itinerary
|
||||
contract
|
||||
payment_receipt
|
||||
approval_screenshot
|
||||
other
|
||||
```
|
||||
|
||||
### Phase B：OCR 字段提取
|
||||
|
||||
目标：从图片或 PDF 中提取票据字段。
|
||||
|
||||
结构：
|
||||
|
||||
```json
|
||||
{
|
||||
"invoice_code": "",
|
||||
"invoice_number": "",
|
||||
"seller_name": "",
|
||||
"seller_tax_no": "",
|
||||
"buyer_name": "",
|
||||
"buyer_tax_no": "",
|
||||
"issue_date": "",
|
||||
"total_amount": 0,
|
||||
"tax_amount": 0,
|
||||
"currency": "CNY",
|
||||
"ocr_confidence": 0.88
|
||||
}
|
||||
```
|
||||
|
||||
### Phase C：字段归一化
|
||||
|
||||
目标：不同 OCR 服务返回不同字段名，必须统一。
|
||||
|
||||
示例：
|
||||
|
||||
```text
|
||||
发票号码 / invoiceNo / invoice_number
|
||||
-> invoice_number
|
||||
```
|
||||
|
||||
金额统一：
|
||||
|
||||
```json
|
||||
{
|
||||
"raw": "￥1,280.00",
|
||||
"value": 1280.00,
|
||||
"currency": "CNY"
|
||||
}
|
||||
```
|
||||
|
||||
### Phase D：验真与状态检查
|
||||
|
||||
调用发票验真 MCP。
|
||||
|
||||
输出：
|
||||
|
||||
```json
|
||||
{
|
||||
"verify_status": "verified",
|
||||
"voided": false,
|
||||
"red_reversed": false,
|
||||
"verified_at": ""
|
||||
}
|
||||
```
|
||||
|
||||
### Phase E：与报销明细匹配
|
||||
|
||||
对比：
|
||||
|
||||
- 发票金额 vs 报销金额
|
||||
- 开票日期 vs 费用日期
|
||||
- 销售方 vs 商户
|
||||
- 发票类型 vs 费用类型
|
||||
|
||||
输出：
|
||||
|
||||
```json
|
||||
{
|
||||
"match_status": "matched",
|
||||
"mismatch_fields": [],
|
||||
"match_confidence": 0.94
|
||||
}
|
||||
```
|
||||
|
||||
### Phase F：人工修正与回流
|
||||
|
||||
OCR 结果必须允许人工修正。
|
||||
|
||||
修正内容进入反馈池：
|
||||
|
||||
```json
|
||||
{
|
||||
"field": "invoice_number",
|
||||
"before": "12345B",
|
||||
"after": "123456",
|
||||
"corrected_by": "finance_user",
|
||||
"corrected_at": ""
|
||||
}
|
||||
```
|
||||
|
||||
## 4. 文件存储策略
|
||||
|
||||
### 4.1 为什么不能直接把文件塞进数据库
|
||||
|
||||
- 原始票据、合同、行程单体积大，数据库行膨胀明显。
|
||||
- 预览件、缩略图、逐页图片、脱敏件都属于衍生文件，不适合和业务行混存。
|
||||
- 财务原件需要版本留痕和不可变追溯，文件系统或对象存储更适合。
|
||||
|
||||
结论：
|
||||
|
||||
- 文件二进制存文件系统或对象存储。
|
||||
- 数据库仅保存元数据、索引、版本、OCR 结果、验真结果、访问审计和业务关联。
|
||||
|
||||
### 4.2 开发环境目录方案
|
||||
|
||||
根目录使用后端配置中的 `STORAGE_ROOT_DIR`。
|
||||
|
||||
建议目录：
|
||||
|
||||
```text
|
||||
<STORAGE_ROOT_DIR>/
|
||||
finance-documents/
|
||||
expense_claim/
|
||||
2026/
|
||||
05/
|
||||
<claim_id>/
|
||||
<document_id>/
|
||||
v1/
|
||||
original/
|
||||
source.jpg
|
||||
preview/
|
||||
preview.pdf
|
||||
pages/
|
||||
page-1.png
|
||||
thumbs/
|
||||
thumb.webp
|
||||
ocr/
|
||||
ocr-1.json
|
||||
verify/
|
||||
verify-1.json
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- `claim_id` 为空时，可先挂到 `draft/<conversation_id>/<document_id>/...`，待正式建单后再回填业务关联。
|
||||
- `v1`、`v2` 表示文件版本，不允许直接覆盖 `v1`。
|
||||
- 原始文件名用于展示，真实定位依赖 `storage_key` 和 `sha256`。
|
||||
|
||||
### 4.3 生产环境存储方案
|
||||
|
||||
生产环境建议使用：
|
||||
|
||||
- MinIO
|
||||
- S3
|
||||
- 阿里云 OSS
|
||||
- 腾讯云 COS
|
||||
|
||||
对象存储推荐键名：
|
||||
|
||||
```text
|
||||
finance-documents/expense_claim/2026/05/<claim_id>/<document_id>/v1/original/source.jpg
|
||||
finance-documents/expense_claim/2026/05/<claim_id>/<document_id>/v1/preview/preview.pdf
|
||||
finance-documents/expense_claim/2026/05/<claim_id>/<document_id>/v1/thumbs/thumb.webp
|
||||
```
|
||||
|
||||
数据库必须保存：
|
||||
|
||||
```text
|
||||
storage_provider
|
||||
storage_bucket
|
||||
storage_key
|
||||
sha256
|
||||
file_size_bytes
|
||||
mime_type
|
||||
current_version_no
|
||||
```
|
||||
|
||||
### 4.4 原件、版本与衍生件规则
|
||||
|
||||
- 原件不可变：上传后不得覆盖。
|
||||
- 替换附件只能新增 `document_asset_versions` 记录。
|
||||
- OCR 原始输出、验真响应、预览件、缩略图都作为衍生件管理。
|
||||
- 删除操作默认只允许逻辑删除业务关联，不允许物理删除原件。
|
||||
- 命中审计或争议流程的单据可切换到 `legal_hold` 保留策略，暂停清理。
|
||||
|
||||
### 4.5 去重与追溯
|
||||
|
||||
- 每个原始文件必须计算 `sha256`。
|
||||
- 同一个 `sha256` 可提示重复上传，但不能自动覆盖旧版本。
|
||||
- 发票查重不能只靠文件哈希，还要结合 `invoice_code + invoice_number + issue_date + total_amount`。
|
||||
|
||||
## 5. 数据模型建议
|
||||
|
||||
推荐配套表：
|
||||
|
||||
```text
|
||||
document_assets
|
||||
document_asset_versions
|
||||
document_derivatives
|
||||
document_ocr_results
|
||||
invoice_structured_records
|
||||
invoice_verification_records
|
||||
expense_item_documents
|
||||
document_access_logs
|
||||
```
|
||||
|
||||
各表职责：
|
||||
|
||||
- `document_assets`：文件主索引
|
||||
- `document_asset_versions`：原件版本
|
||||
- `document_derivatives`：缩略图、预览、逐页图片、脱敏件
|
||||
- `document_ocr_results`：每次 OCR 执行结果
|
||||
- `invoice_structured_records`：标准化票据字段
|
||||
- `invoice_verification_records`：验真结果
|
||||
- `expense_item_documents`：报销明细与票据挂接
|
||||
- `document_access_logs`：文件查看、下载、导出审计
|
||||
|
||||
## 6. 与规则中心关系
|
||||
|
||||
OCR 输出供规则使用：
|
||||
|
||||
```text
|
||||
重复报销识别规则
|
||||
作废发票检查规则
|
||||
发票抬头异常规则
|
||||
附件完整性规则
|
||||
金额不一致规则
|
||||
OCR 低置信度补录规则
|
||||
```
|
||||
|
||||
规则读取原则：
|
||||
|
||||
- 读标准化字段，不直接依赖某个 OCR 服务的原始字段名。
|
||||
- 需要追证时，从 `document_assets` 和 `document_asset_versions` 找原件。
|
||||
- 需要解释时，从 `document_ocr_results` 和 `invoice_verification_records` 给证据。
|
||||
|
||||
## 7. 与 Agent 关系
|
||||
|
||||
User Agent 使用 OCR：
|
||||
|
||||
- 解释发票为什么被拦截
|
||||
- 帮用户补充发票信息
|
||||
- 提醒上传清晰附件
|
||||
- 根据 OCR 结果自动回填报销草稿
|
||||
|
||||
Hermes 使用 OCR：
|
||||
|
||||
- 夜间批量验真
|
||||
- 扫描重复票据
|
||||
- 统计发票异常趋势
|
||||
- 回刷历史低置信度票据
|
||||
|
||||
## 8. 安全与审计要求
|
||||
|
||||
### 8.1 访问控制
|
||||
|
||||
- 原始票据预览、下载应按用户角色控制。
|
||||
- 财务、审批人、申请人看到的文件范围可以不同。
|
||||
- 对象存储不要暴露永久公网链接，统一走签名 URL 或后端代理下载。
|
||||
|
||||
### 8.2 敏感信息处理
|
||||
|
||||
- 身份证、银行卡、手机号等敏感字段如被识别，应支持脱敏预览件。
|
||||
- 对外展示尽量用衍生件，不直接暴露原件。
|
||||
|
||||
### 8.3 审计要求
|
||||
|
||||
必须记录：
|
||||
|
||||
- 谁上传了原件
|
||||
- 谁触发了 OCR
|
||||
- 谁查看或下载了原件
|
||||
- 谁修正了 OCR 结果
|
||||
- 谁发起了验真
|
||||
- 哪次风险判断引用了哪些票据
|
||||
|
||||
## 9. 开发阶段建议
|
||||
|
||||
```text
|
||||
Step 1: 附件上传与 document_assets / document_asset_versions 落库
|
||||
Step 2: 本地文件目录方案打通
|
||||
Step 3: 接入 OCR MCP 或 OCR 服务
|
||||
Step 4: 结构化字段归一化
|
||||
Step 5: 发票验真 MCP
|
||||
Step 6: 与 expense_claim_items 匹配
|
||||
Step 7: 风险规则中心接入
|
||||
Step 8: 人工修正界面
|
||||
Step 9: Hermes 夜间批量 OCR 与验真巡检
|
||||
```
|
||||
|
||||
当前阶段优先级：
|
||||
|
||||
- 先把“文件原件可存、可找、可追溯”做实。
|
||||
- 再把 OCR 和验真接进来。
|
||||
- 最后再做大规模自动巡检和脱敏导出。
|
||||
@@ -1,221 +0,0 @@
|
||||
# LLM Wiki 知识库架构
|
||||
|
||||
## 1. 定位
|
||||
|
||||
LLM Wiki 不是简单的文件库。
|
||||
|
||||
它是给 Agent 使用的知识底座，负责把制度、FAQ、审批经验、规则说明转成可检索、可引用、可版本化的知识。
|
||||
|
||||
## 2. 总体链路
|
||||
|
||||
```text
|
||||
文档上传
|
||||
↓
|
||||
格式解析
|
||||
↓
|
||||
正文抽取
|
||||
↓
|
||||
分块 Chunking
|
||||
↓
|
||||
元数据标注
|
||||
↓
|
||||
向量索引
|
||||
↓
|
||||
条款抽取
|
||||
↓
|
||||
知识候选
|
||||
↓
|
||||
人工审核
|
||||
↓
|
||||
发布 Wiki
|
||||
↓
|
||||
Agent 检索引用
|
||||
```
|
||||
|
||||
## 2.1 目录约束
|
||||
|
||||
LLM Wiki 解析产物不能与原始制度文件混放。
|
||||
|
||||
推荐目录：
|
||||
|
||||
```text
|
||||
/app/server/storage/knowledge/<folder>/ 原始知识文件
|
||||
/app/server/storage/knowledge/.llm_wiki/ 解析产物根目录
|
||||
/app/server/storage/knowledge/.llm_wiki/documents/<document_id>/
|
||||
document.json
|
||||
text.md
|
||||
chunks.json
|
||||
clauses.json
|
||||
knowledge_candidates.json
|
||||
rule_candidates.json
|
||||
/app/server/storage/knowledge/.llm_wiki/index.json
|
||||
/app/server/storage/knowledge/.llm_wiki/sync_runs.json
|
||||
```
|
||||
|
||||
约束：
|
||||
|
||||
- 原始文件目录只存原件，不存解析碎片。
|
||||
- LLM Wiki 目录只存结构化产物，不反向覆盖原件。
|
||||
- 所有解析产物必须能按 `document_id` 回溯到原始文件。
|
||||
|
||||
## 3. 知识类型
|
||||
|
||||
```text
|
||||
policy_document
|
||||
faq
|
||||
rule_explanation
|
||||
approval_case
|
||||
risk_case
|
||||
operation_manual
|
||||
system_notice
|
||||
```
|
||||
|
||||
## 4. 知识块结构
|
||||
|
||||
```json
|
||||
{
|
||||
"chunk_id": "",
|
||||
"document_id": "",
|
||||
"title": "",
|
||||
"content": "",
|
||||
"domain": "reimbursement",
|
||||
"scenario": "travel_reimbursement",
|
||||
"tags": ["差旅", "住宿标准"],
|
||||
"effective_date": "",
|
||||
"version": "v1.0",
|
||||
"source_page": 4,
|
||||
"embedding_id": "",
|
||||
"status": "published"
|
||||
}
|
||||
```
|
||||
|
||||
## 5. 条款抽取
|
||||
|
||||
Hermes 可以从制度文档中抽取条款候选。
|
||||
|
||||
示例：
|
||||
|
||||
```json
|
||||
{
|
||||
"clause_type": "amount_limit",
|
||||
"domain": "reimbursement",
|
||||
"scenario": "travel_reimbursement",
|
||||
"condition": {
|
||||
"city_tier": "一线城市",
|
||||
"employee_grade": "P5"
|
||||
},
|
||||
"limit": {
|
||||
"amount": 800,
|
||||
"currency": "CNY",
|
||||
"period": "night"
|
||||
},
|
||||
"source": "差旅制度 2026 第 4 页"
|
||||
}
|
||||
```
|
||||
|
||||
该结果不直接变成规则，先进入规则候选池。
|
||||
|
||||
## 5.1 增量形成策略
|
||||
|
||||
LLM Wiki 不应按天无脑全量重建。
|
||||
|
||||
每个文档都应维护签名：
|
||||
|
||||
```json
|
||||
{
|
||||
"document_id": "",
|
||||
"original_name": "",
|
||||
"stored_name": "",
|
||||
"sha256": "",
|
||||
"version_number": 1,
|
||||
"updated_at": ""
|
||||
}
|
||||
```
|
||||
|
||||
只有在以下任一条件发生时，才重建对应文档的 LLM Wiki：
|
||||
|
||||
- `original_name` 变更。
|
||||
- `stored_name` 变更。
|
||||
- `sha256` 变更。
|
||||
- `version_number` 变更。
|
||||
- `updated_at` 变更，视为人工修改。
|
||||
|
||||
如果以上均未变化：
|
||||
|
||||
- 本次文档状态应记为 `unchanged_skipped`。
|
||||
- 不重新抽取正文。
|
||||
- 不重新分块。
|
||||
- 不重新生成知识候选或规则候选。
|
||||
|
||||
## 6. Wiki 发布流程
|
||||
|
||||
```text
|
||||
草稿知识
|
||||
↓
|
||||
Hermes 生成候选
|
||||
↓
|
||||
知识管理员审核
|
||||
↓
|
||||
发布
|
||||
↓
|
||||
Agent 可检索
|
||||
```
|
||||
|
||||
## 7. 与 User Agent 的关系
|
||||
|
||||
User Agent 用 Wiki：
|
||||
|
||||
- 回答制度问题。
|
||||
- 给风险解释提供条款依据。
|
||||
- 给审批意见生成引用。
|
||||
- 帮用户理解流程。
|
||||
|
||||
## 8. 与 Hermes 的关系
|
||||
|
||||
Hermes 用 Wiki：
|
||||
|
||||
- 每日知识候选生成。
|
||||
- 发现制度与规则不一致。
|
||||
- 生成规则优化建议。
|
||||
- 生成 FAQ 候选。
|
||||
|
||||
补充要求：
|
||||
|
||||
- Hermes 对制度文档的处理默认是增量同步，不是每日全量重建。
|
||||
- Hermes 应先检查知识库签名，再决定是否需要重建某个文档的 Wiki。
|
||||
- Hermes 形成的是候选与草稿，不是正式发布内容。
|
||||
|
||||
## 9. 数据模型建议
|
||||
|
||||
```text
|
||||
knowledge_documents
|
||||
knowledge_chunks
|
||||
knowledge_embeddings
|
||||
knowledge_candidates
|
||||
knowledge_reviews
|
||||
knowledge_versions
|
||||
```
|
||||
|
||||
当前最小落地允许先以文件索引实现：
|
||||
|
||||
```text
|
||||
.llm_wiki/index.json
|
||||
.llm_wiki/sync_runs.json
|
||||
.llm_wiki/documents/<document_id>/document.json
|
||||
```
|
||||
|
||||
后续再平滑迁移到数据库或向量库。
|
||||
|
||||
## 10. 开发阶段建议
|
||||
|
||||
```text
|
||||
Step 1: 文档上传和文件管理
|
||||
Step 2: 文本抽取和分块
|
||||
Step 3: 元数据标注
|
||||
Step 4: 向量索引
|
||||
Step 5: 知识检索 API
|
||||
Step 6: User Agent 问答引用
|
||||
Step 7: Hermes 知识候选生成
|
||||
Step 8: 人工审核发布
|
||||
Step 9: 条款抽取和规则候选
|
||||
```
|
||||
@@ -1,194 +0,0 @@
|
||||
# 规则形成生命周期
|
||||
|
||||
## 1. 定位
|
||||
|
||||
规则不是凭空写出来的。
|
||||
|
||||
它应来自：
|
||||
|
||||
- 制度文档。
|
||||
- 历史审批。
|
||||
- 风险案例。
|
||||
- OCR 识别结果。
|
||||
- MCP 验真结果。
|
||||
- 用户反馈。
|
||||
- Hermes 分析。
|
||||
|
||||
## 2. 总体闭环
|
||||
|
||||
```text
|
||||
制度文档 / 历史审批 / 风险案例 / 用户反馈
|
||||
↓
|
||||
Hermes 分析
|
||||
↓
|
||||
规则候选
|
||||
↓
|
||||
人工审核
|
||||
↓
|
||||
规则 .md
|
||||
↓
|
||||
测试样例
|
||||
↓
|
||||
版本发布
|
||||
↓
|
||||
规则执行
|
||||
↓
|
||||
命中反馈
|
||||
↓
|
||||
规则优化
|
||||
```
|
||||
|
||||
## 3. 规则候选结构
|
||||
|
||||
```json
|
||||
{
|
||||
"candidate_id": "",
|
||||
"source_type": "policy_document",
|
||||
"domain": "reimbursement",
|
||||
"scenario": "invoice_validation",
|
||||
"risk_signal": "duplicate_invoice",
|
||||
"suggested_rule_name": "重复报销识别规则",
|
||||
"rule_markdown_draft": "",
|
||||
"evidence": [],
|
||||
"confidence": 0.86,
|
||||
"created_by": "hermes"
|
||||
}
|
||||
```
|
||||
|
||||
补充约束：
|
||||
|
||||
- `rule_markdown_draft` 不能是任意自由文本，必须符合固定模板。
|
||||
- 规则候选应同时携带机器可读 JSON 草稿，例如 `runtime_rule`。
|
||||
- JSON 草稿只能从受控模板族中选择，不允许 Hermes 自创字段结构后直接进入规则中心。
|
||||
|
||||
## 4. 规则 Markdown 推荐结构
|
||||
|
||||
```markdown
|
||||
# 规则名称
|
||||
|
||||
## 目标
|
||||
|
||||
## 适用范围
|
||||
|
||||
## 输入字段
|
||||
|
||||
## 判断规则
|
||||
|
||||
## 输出
|
||||
|
||||
## 测试样例
|
||||
|
||||
## 管理员备注
|
||||
```
|
||||
|
||||
推荐再补一段模板元信息：
|
||||
|
||||
```markdown
|
||||
## 模板信息
|
||||
|
||||
- 模板键：`travel_standard_v1`
|
||||
- 来源文档：公司支出管理办法（2024）
|
||||
- Hermes 置信度：0.86
|
||||
- 审核人：张三
|
||||
```
|
||||
|
||||
## 4.1 规则 JSON 推荐结构
|
||||
|
||||
规则中心不应只有 Markdown。
|
||||
|
||||
应同时提供可执行 JSON 编辑区，至少支持：
|
||||
|
||||
```json
|
||||
{
|
||||
"kind": "policy_rule_draft",
|
||||
"version": 1,
|
||||
"template_key": "travel_standard_v1",
|
||||
"rule_name": "差旅住宿标准草稿规则",
|
||||
"scenario": "travel_reimbursement",
|
||||
"review_required": true,
|
||||
"conditions": {},
|
||||
"actions": {},
|
||||
"source_document_name": "公司支出管理办法（2024）"
|
||||
}
|
||||
```
|
||||
|
||||
治理要求：
|
||||
|
||||
- Markdown 负责给人看。
|
||||
- JSON 负责给运行时和规则引擎看。
|
||||
- 两者必须成对维护，不能只改其中一份。
|
||||
- JSON 变更也必须走版本和审核。
|
||||
|
||||
## 4.2 模板族约束
|
||||
|
||||
Hermes 只能从白名单模板中选，不允许自由生成任意规则结构。
|
||||
|
||||
第一版建议模板：
|
||||
|
||||
```text
|
||||
travel_standard_v1
|
||||
expense_amount_limit_v1
|
||||
attachment_requirement_v1
|
||||
general_policy_v1
|
||||
```
|
||||
|
||||
如果制度条款不适合自动规则化：
|
||||
|
||||
- 允许只生成 `knowledge_candidate`
|
||||
- 或只生成 `general_policy_v1` 草稿并要求人工补齐
|
||||
- 不能为了“有结果”而编造可执行规则
|
||||
|
||||
## 5. 审核要求
|
||||
|
||||
规则上线必须满足：
|
||||
|
||||
- 有审核人。
|
||||
- 有版本。
|
||||
- 有测试样例。
|
||||
- 有来源依据。
|
||||
- 有回滚方案。
|
||||
|
||||
补充：
|
||||
|
||||
- Hermes 生成规则默认只能是 `draft`。
|
||||
- Hermes 不能直接覆盖当前 `active` 线上规则。
|
||||
- Hermes 如发现制度更新，应优先生成新的候选或草稿版本，仍需人工审核后再上线。
|
||||
|
||||
## 6. 规则执行反馈
|
||||
|
||||
每次规则运行应记录：
|
||||
|
||||
```text
|
||||
rule_id
|
||||
rule_version
|
||||
input_snapshot
|
||||
hit_result
|
||||
risk_level
|
||||
operator_feedback
|
||||
false_positive
|
||||
false_negative
|
||||
```
|
||||
|
||||
## 7. 规则优化来源
|
||||
|
||||
```text
|
||||
误报反馈
|
||||
漏报反馈
|
||||
审批人修改意见
|
||||
Hermes 每日复盘
|
||||
制度文档更新
|
||||
MCP 新字段可用
|
||||
```
|
||||
|
||||
## 8. 开发阶段建议
|
||||
|
||||
```text
|
||||
Step 1: 规则 .md 编辑和版本
|
||||
Step 2: 规则审核上线
|
||||
Step 3: 规则运行日志
|
||||
Step 4: 人工反馈误报/漏报
|
||||
Step 5: Hermes 生成规则候选
|
||||
Step 6: 规则候选审核
|
||||
Step 7: 规则测试样例管理
|
||||
Step 8: 规则质量看板
|
||||
```
|
||||
@@ -1,646 +0,0 @@
|
||||
# 财务单据标准模型
|
||||
|
||||
## 1. 为什么需要标准模型
|
||||
|
||||
OCR、MCP、用户填写、业务数据库可能都描述同一张发票，但字段名和格式不同。
|
||||
|
||||
如果没有标准模型：
|
||||
|
||||
- 规则无法复用。
|
||||
- Agent 难以解释。
|
||||
- Hermes 难以批量统计。
|
||||
- MCP 返回结果难以合并。
|
||||
|
||||
这里要区分三层：
|
||||
|
||||
- 标准模型：定义 Agent、规则、MCP、OCR、数据库之间统一交换的数据结构。
|
||||
- 业务数据库表：定义 MVP 阶段真正落库存储、查询和统计所依赖的业务表。
|
||||
- 文件存储对象：定义原始票据、预览件、OCR 中间产物、验真结果附件的存储位置与版本规则。
|
||||
|
||||
如果只有标准模型，没有业务表和文件资产表，User Agent 无法真正发起报销；如果只有数据库表，没有统一标准模型，语义解析、规则解释、OCR 回填和 Hermes 巡检会越来越混乱。
|
||||
|
||||
## 2. 标准对象
|
||||
|
||||
第一版建议定义这些对象：
|
||||
|
||||
```text
|
||||
Invoice
|
||||
Receipt
|
||||
ExpenseClaim
|
||||
PaymentRequest
|
||||
AccountsReceivableRecord
|
||||
AccountsPayableRecord
|
||||
BankTransaction
|
||||
Contract
|
||||
Customer
|
||||
Vendor
|
||||
Employee
|
||||
CostCenter
|
||||
DocumentAsset
|
||||
RiskEvent
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- 对外语义层建议统一使用 `ExpenseClaim` 概念，不再把“报销申请”和“报销单据”拆成两个平行主概念。
|
||||
- 现有代码中仍有 `reimbursement_requests` 表，MVP 阶段不建议再继续扩张该表，而应以 `expense_claims` 作为报销主表。
|
||||
- `reimbursement_requests` 可保留用于兼容旧页面或审批联动，但新能力默认挂到 `expense_claims`。
|
||||
|
||||
## 3. Invoice 标准模型
|
||||
|
||||
```json
|
||||
{
|
||||
"invoice_id": "",
|
||||
"invoice_code": "",
|
||||
"invoice_number": "",
|
||||
"invoice_type": "",
|
||||
"seller_name": "",
|
||||
"seller_tax_no": "",
|
||||
"buyer_name": "",
|
||||
"buyer_tax_no": "",
|
||||
"issue_date": "",
|
||||
"total_amount": 0,
|
||||
"tax_amount": 0,
|
||||
"currency": "CNY",
|
||||
"verify_status": "",
|
||||
"ocr_confidence": 0,
|
||||
"source_document_id": ""
|
||||
}
|
||||
```
|
||||
|
||||
## 4. ExpenseClaim 标准模型
|
||||
|
||||
```json
|
||||
{
|
||||
"claim_id": "",
|
||||
"claim_no": "",
|
||||
"employee_id": "",
|
||||
"employee_name": "",
|
||||
"department_id": "",
|
||||
"department_name": "",
|
||||
"cost_center_code": "",
|
||||
"project_code": "",
|
||||
"expense_type": "",
|
||||
"reason": "",
|
||||
"location": "",
|
||||
"amount": 0,
|
||||
"currency": "CNY",
|
||||
"status": "",
|
||||
"occurred_at": "",
|
||||
"submitted_at": "",
|
||||
"approval_stage": "",
|
||||
"items": [],
|
||||
"attachments": [],
|
||||
"risk_flags": []
|
||||
}
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- `reason`、`location`、`occurred_at` 是报销语义判断、规则解释、风险识别的最小必要字段。
|
||||
- 一张报销单通常包含多条费用明细，标准模型中允许聚合，数据库层必须拆到明细表。
|
||||
- `attachments` 指向文件资产，不直接嵌入二进制文件。
|
||||
|
||||
## 5. AccountsReceivableRecord 标准模型
|
||||
|
||||
```json
|
||||
{
|
||||
"ar_id": "",
|
||||
"document_no": "",
|
||||
"customer_id": "",
|
||||
"customer_name": "",
|
||||
"contract_no": "",
|
||||
"invoice_no": "",
|
||||
"amount_receivable": 0,
|
||||
"amount_received": 0,
|
||||
"amount_outstanding": 0,
|
||||
"currency": "CNY",
|
||||
"due_date": "",
|
||||
"posting_date": "",
|
||||
"status": "",
|
||||
"aging_days": 0,
|
||||
"risk_flags": []
|
||||
}
|
||||
```
|
||||
|
||||
## 6. AccountsPayableRecord 标准模型
|
||||
|
||||
```json
|
||||
{
|
||||
"ap_id": "",
|
||||
"document_no": "",
|
||||
"vendor_id": "",
|
||||
"vendor_name": "",
|
||||
"invoice_no": "",
|
||||
"amount_payable": 0,
|
||||
"amount_paid": 0,
|
||||
"amount_outstanding": 0,
|
||||
"currency": "CNY",
|
||||
"due_date": "",
|
||||
"posting_date": "",
|
||||
"status": "",
|
||||
"aging_days": 0,
|
||||
"risk_flags": []
|
||||
}
|
||||
```
|
||||
|
||||
## 7. BankTransaction 标准模型
|
||||
|
||||
```json
|
||||
{
|
||||
"transaction_id": "",
|
||||
"bank_account": "",
|
||||
"transaction_date": "",
|
||||
"amount": 0,
|
||||
"currency": "CNY",
|
||||
"counterparty_name": "",
|
||||
"summary": "",
|
||||
"matched_object_type": "",
|
||||
"matched_object_id": "",
|
||||
"match_status": ""
|
||||
}
|
||||
```
|
||||
|
||||
## 8. MVP 真实业务表设计
|
||||
|
||||
标准模型不等于数据库表，但 MVP 至少要有以下真实表，才能支撑 Day 5 用户报销对话、Day 6 风险巡检和后续审批/验真闭环。
|
||||
|
||||
### 8.1 设计原则
|
||||
|
||||
- 报销主数据统一落在 `expense_claims`，不再新建第三套“报销主表”。
|
||||
- 原始票据文件二进制不进数据库，只存元数据和关联信息。
|
||||
- OCR 结果、发票结构化结果、验真结果、风险事件要分表存，避免把所有字段塞进一个 JSON。
|
||||
- 所有表都要能被 Agent 解释，也要能被 Hermes 批量扫表。
|
||||
- `reimbursement_requests` 进入兼容态，不作为新能力主干表继续扩展。
|
||||
|
||||
### 8.2 报销主表 `expense_claims`
|
||||
|
||||
用途：
|
||||
|
||||
- 作为用户报销会话最终落单的主业务对象。
|
||||
- 承接语义层补槽后的草稿、提交、审批、打回、归档状态。
|
||||
|
||||
建议字段：
|
||||
|
||||
```text
|
||||
id string(36) PK
|
||||
claim_no string(50) UK, 报销单号
|
||||
source string(30) 来源: agent/web/import/api
|
||||
title string(200) 报销标题
|
||||
employee_id string(64) 申请人 ID
|
||||
employee_name string(100) 申请人姓名
|
||||
department_id string(64) 部门 ID
|
||||
department_name string(100) 部门名
|
||||
company_code string(50) 公司编码
|
||||
cost_center_code string(50) 成本中心
|
||||
project_code string(50) 项目编码
|
||||
expense_type string(50) 费用大类
|
||||
reason text 事由
|
||||
location string(100) 地点
|
||||
amount numeric(12,2) 报销总金额
|
||||
currency string(10) 币种
|
||||
invoice_count int 附件票据数
|
||||
attachment_count int 附件总数
|
||||
occurred_start_at timestamptz 发生开始时间
|
||||
occurred_end_at timestamptz 发生结束时间
|
||||
submitted_at timestamptz 提交时间
|
||||
status string(30) draft/submitted/approved/rejected/paid
|
||||
status_changed_at timestamptz 最近状态变更时间
|
||||
status_changed_by string(64) 最近状态变更人
|
||||
status_change_note text 状态变更备注
|
||||
approval_stage string(50) 当前审批节点
|
||||
risk_level string(20) none/low/medium/high
|
||||
risk_flags_json json 风险标记快照
|
||||
conversation_id string(64) 对话会话 ID
|
||||
created_by string(64) 创建人
|
||||
updated_by string(64) 更新人
|
||||
created_at timestamptz
|
||||
updated_at timestamptz
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- 现有模型已有一部分字段，后续只做增量扩展即可。
|
||||
- `occurred_start_at`、`occurred_end_at` 比单一 `occurred_at` 更适合差旅、接待等跨时段报销。
|
||||
|
||||
### 8.2.1 报销状态流转建议
|
||||
|
||||
建议状态：
|
||||
|
||||
```text
|
||||
draft
|
||||
submitted
|
||||
approved
|
||||
rejected
|
||||
paid
|
||||
```
|
||||
|
||||
建议流转：
|
||||
|
||||
```text
|
||||
语义补槽完成
|
||||
-> 创建 expense_claims 草稿
|
||||
-> status = draft
|
||||
|
||||
用户继续补充字段 / 上传附件
|
||||
-> 更新 expense_claims / expense_claim_items / expense_item_documents
|
||||
-> status 仍为 draft
|
||||
|
||||
用户明确确认提交
|
||||
-> status = submitted
|
||||
-> 写入 submitted_at / status_changed_at / status_changed_by
|
||||
|
||||
审批流结果回写
|
||||
-> status = approved 或 rejected
|
||||
|
||||
付款完成回写
|
||||
-> status = paid
|
||||
```
|
||||
|
||||
边界：
|
||||
|
||||
- User Agent 可以创建 `draft`，也可以在用户确认后提交到 `submitted`。
|
||||
- User Agent 不应直接把状态改为 `approved`、`rejected`、`paid`。
|
||||
- 所有状态变化都应写审计日志，必要时保留 `status_change_note`。
|
||||
|
||||
### 8.3 报销明细表 `expense_claim_items`
|
||||
|
||||
用途：
|
||||
|
||||
- 表达一单多明细。
|
||||
- 作为 OCR 发票比对、重复报销识别、风险定位的最小粒度。
|
||||
|
||||
建议字段：
|
||||
|
||||
```text
|
||||
id string(36) PK
|
||||
claim_id string(36) FK -> expense_claims.id
|
||||
line_no int 明细序号
|
||||
item_date date 费用发生日期
|
||||
item_type string(50) 费用小类
|
||||
item_reason text 明细事由
|
||||
item_location string(100) 明细地点
|
||||
merchant_name string(200) 商户/酒店/餐厅
|
||||
customer_name string(200) 客户单位
|
||||
participants_json json 参与人员
|
||||
transport_type string(50) 交通方式
|
||||
item_amount numeric(12,2) 明细金额
|
||||
tax_amount numeric(12,2) 税额
|
||||
currency string(10)
|
||||
invoice_match_status string(30) unmatched/partial/matched
|
||||
risk_level string(20)
|
||||
risk_flags_json json
|
||||
remark text
|
||||
created_at timestamptz
|
||||
updated_at timestamptz
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- 现有 `invoice_id` 单字段不足以覆盖多张附件挂同一明细的情况，后续应改为关联表。
|
||||
|
||||
### 8.4 票据资产主表 `document_assets`
|
||||
|
||||
用途：
|
||||
|
||||
- 作为所有原始附件的主索引表。
|
||||
- 支持报销单、报销明细、审批、验真、风控证据等多对象挂载。
|
||||
|
||||
建议字段：
|
||||
|
||||
```text
|
||||
id string(36) PK
|
||||
biz_domain string(30) expense/ap/ar/common
|
||||
biz_object_type string(50) expense_claim/expense_item/approval_record
|
||||
biz_object_id string(36) 业务对象 ID
|
||||
document_type string(50) invoice/receipt/itinerary/contract/other
|
||||
document_subtype string(50) vat_special/taxi/train/hotel/meal 等
|
||||
source string(30) upload/agent/import/system
|
||||
original_filename string(255)
|
||||
mime_type string(100)
|
||||
file_ext string(20)
|
||||
page_count int
|
||||
file_size_bytes bigint
|
||||
sha256 string(64) 去重与追溯
|
||||
storage_provider string(30) local/minio/s3/oss/cos
|
||||
storage_bucket string(100) 本地模式可为空
|
||||
storage_key string(500) 指向当前有效版本原件
|
||||
current_version_no int
|
||||
classification_status string(30) pending/success/failed
|
||||
ocr_status string(30) pending/running/success/failed
|
||||
virus_scan_status string(30) pending/clean/infected
|
||||
retention_policy string(30) finance_default/legal_hold/manual
|
||||
uploaded_by string(64)
|
||||
uploaded_at timestamptz
|
||||
created_at timestamptz
|
||||
updated_at timestamptz
|
||||
```
|
||||
|
||||
### 8.5 票据版本表 `document_asset_versions`
|
||||
|
||||
用途：
|
||||
|
||||
- 保留原始文件和后续重新上传版本。
|
||||
- 允许“修正”但不允许覆盖原始证据。
|
||||
|
||||
建议字段：
|
||||
|
||||
```text
|
||||
id string(36) PK
|
||||
document_id string(36) FK -> document_assets.id
|
||||
version_no int 1,2,3...
|
||||
is_current bool
|
||||
change_reason string(100) replace/rotate/desensitize/reupload
|
||||
original_filename string(255)
|
||||
mime_type string(100)
|
||||
file_size_bytes bigint
|
||||
sha256 string(64)
|
||||
storage_provider string(30)
|
||||
storage_bucket string(100)
|
||||
storage_key string(500)
|
||||
uploaded_by string(64)
|
||||
uploaded_at timestamptz
|
||||
created_at timestamptz
|
||||
```
|
||||
|
||||
### 8.6 衍生文件表 `document_derivatives`
|
||||
|
||||
用途：
|
||||
|
||||
- 存储缩略图、预览 PDF、逐页图片、脱敏件等衍生产物。
|
||||
|
||||
建议字段：
|
||||
|
||||
```text
|
||||
id string(36) PK
|
||||
document_version_id string(36) FK -> document_asset_versions.id
|
||||
derivative_type string(50) thumb/preview/page_image/desensitized
|
||||
page_no int 可空
|
||||
mime_type string(100)
|
||||
file_size_bytes bigint
|
||||
storage_provider string(30)
|
||||
storage_bucket string(100)
|
||||
storage_key string(500)
|
||||
created_by string(64)
|
||||
created_at timestamptz
|
||||
```
|
||||
|
||||
### 8.7 OCR 结果表 `document_ocr_results`
|
||||
|
||||
用途：
|
||||
|
||||
- 保留每次 OCR 原始结果、模型版本、置信度和错误信息。
|
||||
- 支持后续重跑 OCR 与人工纠错对比。
|
||||
|
||||
建议字段：
|
||||
|
||||
```text
|
||||
id string(36) PK
|
||||
document_id string(36) FK -> document_assets.id
|
||||
document_version_id string(36) FK -> document_asset_versions.id
|
||||
ocr_engine string(50) paddle/aliyun/tencent/openai 等
|
||||
ocr_model string(100)
|
||||
run_no int 第几次 OCR
|
||||
status string(30) success/failed/partial
|
||||
language string(20)
|
||||
raw_text text
|
||||
raw_result_json json
|
||||
structured_result_json json
|
||||
confidence numeric(5,4)
|
||||
error_message text
|
||||
started_at timestamptz
|
||||
finished_at timestamptz
|
||||
created_at timestamptz
|
||||
```
|
||||
|
||||
### 8.8 发票结构化表 `invoice_structured_records`
|
||||
|
||||
用途：
|
||||
|
||||
- 将发票核心字段标准化后独立存储，便于查重、验真、规则计算。
|
||||
|
||||
建议字段：
|
||||
|
||||
```text
|
||||
id string(36) PK
|
||||
document_id string(36) FK -> document_assets.id
|
||||
ocr_result_id string(36) FK -> document_ocr_results.id
|
||||
invoice_code string(50)
|
||||
invoice_number string(50)
|
||||
invoice_type string(50)
|
||||
seller_name string(200)
|
||||
seller_tax_no string(50)
|
||||
buyer_name string(200)
|
||||
buyer_tax_no string(50)
|
||||
issue_date date
|
||||
total_amount numeric(12,2)
|
||||
tax_amount numeric(12,2)
|
||||
currency string(10)
|
||||
check_code string(100)
|
||||
is_red_invoice bool
|
||||
is_electronic bool
|
||||
ocr_confidence numeric(5,4)
|
||||
normalized_status string(30) normalized/manual_corrected
|
||||
duplicate_fingerprint string(100) 发票号+代码+金额+日期
|
||||
created_at timestamptz
|
||||
updated_at timestamptz
|
||||
```
|
||||
|
||||
### 8.9 发票验真记录表 `invoice_verification_records`
|
||||
|
||||
用途：
|
||||
|
||||
- 保留每次调用税局/第三方验真服务的结果，支持追溯。
|
||||
|
||||
建议字段：
|
||||
|
||||
```text
|
||||
id string(36) PK
|
||||
invoice_record_id string(36) FK -> invoice_structured_records.id
|
||||
verification_channel string(50) tax_mcp/third_party/manual
|
||||
request_payload_json json
|
||||
response_payload_json json
|
||||
verify_status string(30) verified/unverified/voided/error
|
||||
voided bool
|
||||
red_reversed bool
|
||||
verified_amount numeric(12,2)
|
||||
verified_issue_date date
|
||||
error_code string(50)
|
||||
error_message text
|
||||
verified_by string(64)
|
||||
verified_at timestamptz
|
||||
created_at timestamptz
|
||||
```
|
||||
|
||||
### 8.10 明细与票据关联表 `expense_item_documents`
|
||||
|
||||
用途：
|
||||
|
||||
- 解决一条明细可关联多张票据、一张票据也可能支撑多条拆分明细的场景。
|
||||
|
||||
建议字段：
|
||||
|
||||
```text
|
||||
id string(36) PK
|
||||
claim_id string(36) FK -> expense_claims.id
|
||||
claim_item_id string(36) FK -> expense_claim_items.id
|
||||
document_id string(36) FK -> document_assets.id
|
||||
relation_type string(30) evidence/invoice/boarding_pass/receipt
|
||||
allocated_amount numeric(12,2) 分摊到该明细的金额
|
||||
match_status string(30) unmatched/partial/matched
|
||||
match_confidence numeric(5,4)
|
||||
created_at timestamptz
|
||||
updated_at timestamptz
|
||||
```
|
||||
|
||||
### 8.11 风险事件表 `risk_events`
|
||||
|
||||
用途：
|
||||
|
||||
- 记录风险命中，而不是只在主表里塞一个 `risk_flags_json`。
|
||||
- 作为 Agent 解释“为什么拦截”的核心依据。
|
||||
|
||||
建议字段：
|
||||
|
||||
```text
|
||||
id string(36) PK
|
||||
biz_domain string(30) expense/ap/ar
|
||||
biz_object_type string(50) expense_claim/expense_item/invoice
|
||||
biz_object_id string(36)
|
||||
risk_code string(50) duplicate_invoice/amount_mismatch 等
|
||||
risk_name string(100)
|
||||
risk_level string(20) low/medium/high
|
||||
hit_source string(30) rule/agent/hermes/manual
|
||||
evidence_json json
|
||||
status string(30) open/confirmed/resolved/ignored
|
||||
detected_at timestamptz
|
||||
detected_by string(64)
|
||||
resolved_at timestamptz
|
||||
resolved_by string(64)
|
||||
resolution_note text
|
||||
created_at timestamptz
|
||||
updated_at timestamptz
|
||||
```
|
||||
|
||||
### 8.12 风险处置表 `risk_actions`
|
||||
|
||||
用途：
|
||||
|
||||
- 记录每次人工确认、驳回、忽略、要求补件等处置动作。
|
||||
|
||||
建议字段：
|
||||
|
||||
```text
|
||||
id string(36) PK
|
||||
risk_event_id string(36) FK -> risk_events.id
|
||||
action_type string(30) confirm/reject/ignore/request_more
|
||||
action_note text
|
||||
operator_id string(64)
|
||||
operator_name string(100)
|
||||
created_at timestamptz
|
||||
```
|
||||
|
||||
### 8.13 文件访问审计表 `document_access_logs`
|
||||
|
||||
用途：
|
||||
|
||||
- 记录谁看过、下载过、导出过原始票据。
|
||||
- 支撑财务审计和数据安全追溯。
|
||||
|
||||
建议字段：
|
||||
|
||||
```text
|
||||
id string(36) PK
|
||||
document_id string(36) FK -> document_assets.id
|
||||
document_version_id string(36) FK -> document_asset_versions.id
|
||||
action string(30) preview/download/export/delete
|
||||
operator_id string(64)
|
||||
operator_name string(100)
|
||||
operator_role string(50)
|
||||
client_ip string(64)
|
||||
user_agent string(255)
|
||||
trace_id string(64)
|
||||
created_at timestamptz
|
||||
```
|
||||
|
||||
## 9. 表关系建议
|
||||
|
||||
```text
|
||||
expense_claims
|
||||
└─ expense_claim_items
|
||||
└─ expense_item_documents
|
||||
└─ document_assets
|
||||
└─ document_asset_versions
|
||||
└─ document_derivatives
|
||||
└─ document_ocr_results
|
||||
└─ invoice_structured_records
|
||||
└─ invoice_verification_records
|
||||
|
||||
risk_events -> 可指向 expense_claims / expense_claim_items / invoice_structured_records
|
||||
risk_actions -> risk_events
|
||||
document_access_logs -> document_assets / document_asset_versions
|
||||
```
|
||||
|
||||
原则：
|
||||
|
||||
- 主业务对象和文件资产解耦。
|
||||
- OCR、验真、风险都挂在文件资产或业务对象之上，不把责任塞到一个巨表。
|
||||
- 文件版本和业务关系分离，避免替换附件时把历史证据冲掉。
|
||||
|
||||
## 10. 与现有表的衔接策略
|
||||
|
||||
当前代码中已经存在：
|
||||
|
||||
- `expense_claims`
|
||||
- `expense_claim_items`
|
||||
- `reimbursement_requests`
|
||||
|
||||
建议策略：
|
||||
|
||||
- `expense_claims` 继续作为未来报销主表。
|
||||
- `expense_claim_items` 增量扩字段并替换当前单一 `invoice_id` 直连方式。
|
||||
- `reimbursement_requests` 暂不删除，但冻结扩表。
|
||||
- 如旧流程仍引用 `reimbursement_requests`，可在过渡期建立：
|
||||
- `request_no -> claim_no` 对照字段
|
||||
- 或由 `approval_records` 同时支持两类来源对象
|
||||
|
||||
不建议做法：
|
||||
|
||||
- 再新建第四张“报销申请主表”。
|
||||
- 把原始发票图片以 blob 方式存进 `expense_claims`。
|
||||
- 把 OCR、验真、风控结果全塞进一个 JSON 大字段。
|
||||
|
||||
## 11. 实施顺序建议
|
||||
|
||||
Phase 1：
|
||||
|
||||
- 扩展 `expense_claims`
|
||||
- 扩展 `expense_claim_items`
|
||||
- 新增 `document_assets`
|
||||
- 新增 `document_asset_versions`
|
||||
- 新增 `expense_item_documents`
|
||||
|
||||
Phase 2：
|
||||
|
||||
- 新增 `document_ocr_results`
|
||||
- 新增 `invoice_structured_records`
|
||||
- 新增 `invoice_verification_records`
|
||||
- 新增 `document_derivatives`
|
||||
|
||||
Phase 3：
|
||||
|
||||
- 新增 `risk_events`
|
||||
- 新增 `risk_actions`
|
||||
- 新增 `document_access_logs`
|
||||
|
||||
Phase 4：
|
||||
|
||||
- 逐步弱化 `reimbursement_requests`
|
||||
- 将 Agent 草稿、审批、OCR、验真、风控全收敛到 `expense_claims` 体系
|
||||
|
||||
## 12. 对 Agent 的直接收益
|
||||
|
||||
- 用户说“我要报销”时，Agent 能先创建 `expense_claims` 草稿，再持续补槽。
|
||||
- 用户上传票据后，系统有明确的 `document_assets` 与 `expense_item_documents` 可挂载。
|
||||
- OCR 和验真结果不是一次性临时输出，而是可追溯、可回放、可审计的长期资产。
|
||||
- Agent 回答“为什么被拦截”时，可以直接引用 `risk_events` 和票据证据，不再靠拼字符串解释。
|
||||
@@ -1,119 +0,0 @@
|
||||
# 反馈闭环与持续学习
|
||||
|
||||
## 1. 定位
|
||||
|
||||
Agent 系统必须能从人工反馈中持续变好。
|
||||
|
||||
反馈来源：
|
||||
|
||||
- OCR 人工修正。
|
||||
- 规则误报/漏报。
|
||||
- 审批人修改意见。
|
||||
- 用户对回答的反馈。
|
||||
- Hermes 风险复盘。
|
||||
- MCP 调用失败和降级。
|
||||
|
||||
## 2. 反馈类型
|
||||
|
||||
```text
|
||||
ocr_correction
|
||||
rule_false_positive
|
||||
rule_false_negative
|
||||
agent_answer_feedback
|
||||
approval_opinion_edit
|
||||
knowledge_answer_feedback
|
||||
mcp_failure_feedback
|
||||
task_result_feedback
|
||||
```
|
||||
|
||||
## 3. 反馈结构
|
||||
|
||||
```json
|
||||
{
|
||||
"feedback_id": "",
|
||||
"feedback_type": "rule_false_positive",
|
||||
"source_object_type": "rule_run",
|
||||
"source_object_id": "",
|
||||
"before": {},
|
||||
"after": {},
|
||||
"comment": "",
|
||||
"created_by": "",
|
||||
"created_at": ""
|
||||
}
|
||||
```
|
||||
|
||||
## 4. 反馈流向
|
||||
|
||||
```text
|
||||
人工反馈
|
||||
↓
|
||||
反馈池
|
||||
↓
|
||||
Hermes 聚类分析
|
||||
↓
|
||||
候选改进项
|
||||
↓
|
||||
人工审核
|
||||
↓
|
||||
更新规则 / 知识 / OCR 映射 / Prompt
|
||||
```
|
||||
|
||||
## 5. 反馈不直接自动生效
|
||||
|
||||
反馈只能生成候选，不直接修改线上规则。
|
||||
|
||||
必须人工审核：
|
||||
|
||||
- 规则修改。
|
||||
- 知识发布。
|
||||
- Prompt 修改。
|
||||
- OCR 字段映射调整。
|
||||
|
||||
## 6. Hermes 每日反馈复盘
|
||||
|
||||
Hermes 每日任务：
|
||||
|
||||
```text
|
||||
读取昨日反馈
|
||||
聚类相似问题
|
||||
统计误报高发规则
|
||||
统计低评分回答
|
||||
生成优化候选
|
||||
```
|
||||
|
||||
输出：
|
||||
|
||||
```text
|
||||
rule_improvement_candidates
|
||||
knowledge_update_candidates
|
||||
ocr_mapping_candidates
|
||||
prompt_improvement_notes
|
||||
```
|
||||
|
||||
## 7. 质量指标
|
||||
|
||||
建议监控：
|
||||
|
||||
```text
|
||||
ocr_correction_rate
|
||||
rule_false_positive_rate
|
||||
rule_false_negative_rate
|
||||
agent_answer_like_rate
|
||||
agent_answer_rewrite_rate
|
||||
knowledge_no_hit_rate
|
||||
mcp_failure_rate
|
||||
```
|
||||
|
||||
## 8. 开发阶段建议
|
||||
|
||||
```text
|
||||
Step 1: 增加反馈按钮和反馈表
|
||||
Step 2: OCR 修正写入反馈池
|
||||
Step 3: 规则误报/漏报反馈
|
||||
Step 4: Agent 回答反馈
|
||||
Step 5: Hermes 每日反馈聚类
|
||||
Step 6: 生成优化候选
|
||||
Step 7: 人工审核发布
|
||||
Step 8: 建立质量看板
|
||||
```
|
||||
|
||||
@@ -1,77 +0,0 @@
|
||||
# Agent Week Plan 一周开发路线图
|
||||
|
||||
本目录现在同时承接：
|
||||
|
||||
- 一周路线图
|
||||
- 每天 daily 文档
|
||||
- 每天的详细执行清单
|
||||
|
||||
原独立执行细则目录已合并进各 Day 文档，不再单独维护。
|
||||
|
||||
## 文档分工
|
||||
|
||||
| 目录 | 职责 | 读者 |
|
||||
| --- | --- | --- |
|
||||
| `agent week plan` | 一周节奏、每天目标、验收门槛、详细执行清单、阻塞记录、日终交接 | 产品、架构、Codex、开发、验收 |
|
||||
| `agent plan` | 架构设计、协议、流程、治理、标准模型、能力边界 | 架构、开发、评审 |
|
||||
|
||||
## 使用方式
|
||||
|
||||
1. 先读 [MASTER_TODO.md](./MASTER_TODO.md)，确认 7 天节奏和当前状态。
|
||||
2. 打开当天 daily 文档。
|
||||
3. 在同一份 daily 文档里按顺序阅读：
|
||||
今天的大开发点 -> 当前完成情况 -> 当天验收门槛 -> 详细执行清单 -> 阻塞记录 -> 日终交接。
|
||||
4. 如需设计依据，再跳到 `agent plan` 对应架构文档。
|
||||
5. 完成一个最小项后，再把该项改成完成态，而不是代码写完就直接算过。
|
||||
|
||||
## 完成标记规则
|
||||
|
||||
未完成：
|
||||
|
||||
```md
|
||||
- [ ] 建立 AgentAsset 数据模型
|
||||
```
|
||||
|
||||
完成后：
|
||||
|
||||
```md
|
||||
- [x] ~~建立 AgentAsset 数据模型~~
|
||||
```
|
||||
|
||||
执行要求：
|
||||
|
||||
- [ ] 每次只处理一个最小 TODO。
|
||||
- [ ] 完成后先自测，再改成 `[x]`。
|
||||
- [ ] 改成 `[x]` 时，同时用 `~~` 画线。
|
||||
- [ ] 不能因为代码写完就标完成，必须满足该 TODO 的验收证据。
|
||||
- [ ] 遇到阻塞时，在当天文档的“阻塞记录”下新增说明。
|
||||
- [ ] 每天收尾时更新当天文档的“日终交接”。
|
||||
|
||||
## 一周总体目标
|
||||
|
||||
- Day 1：先把资产、版本、审核、运行日志、审计日志等基础地基建好。
|
||||
- Day 2：把任务规则中心和后端资产体系打通。
|
||||
- Day 3：建立语义本体 MVP，让用户问题能变成稳定结构。
|
||||
- Day 4：建立 Orchestrator，让请求能被统一路由、审计、降级。
|
||||
- Day 5：建立 User Agent MVP，处理用户查询、解释和草稿生成。
|
||||
- Day 6：建立 Hermes MVP，处理定时巡检、统计、知识和规则草稿。
|
||||
- Day 7：做加固、测试、演示、验收和下一阶段交接。
|
||||
|
||||
## 一周暂不完成
|
||||
|
||||
- 完整 OCR 生产识别引擎。
|
||||
- 完整发票验真 MCP 深度接入。
|
||||
- 完整 LLM Wiki 向量检索。
|
||||
- 全量财务域数据打通。
|
||||
- 规则自动上线。
|
||||
- 完整 CI/CD 质量门禁。
|
||||
|
||||
## 生产底线
|
||||
|
||||
- 所有写操作必须有审计日志。
|
||||
- 所有 Agent 执行必须生成 `run_id`。
|
||||
- 所有规则必须有版本。
|
||||
- 未审核规则不能上线。
|
||||
- 高风险动作只能生成草稿或建议，不能自动提交。
|
||||
- 外部能力失败必须有降级结果。
|
||||
- 语义解析结果必须可回放。
|
||||
@@ -1,73 +0,0 @@
|
||||
# Agent Week Plan 总控
|
||||
|
||||
本文件是本周总览和执行索引。
|
||||
|
||||
每个 Day 文档现在同时包含：
|
||||
|
||||
- 路线图
|
||||
- 当前完成情况
|
||||
- 验收门槛
|
||||
- 详细执行清单
|
||||
|
||||
不再跳转独立执行细则目录。
|
||||
|
||||
## 快速浏览
|
||||
|
||||
- HTML 总览：[agent_week_plan_html/index.html](<../agent_week_plan_html/index.html>)
|
||||
- Day 1 HTML：[agent_week_plan_html/day-1.html](<../agent_week_plan_html/day-1.html>)
|
||||
|
||||
## 执行方式
|
||||
|
||||
1. 先看本文件，确认今天做哪一天、当前状态和依赖顺序。
|
||||
2. 再打开当天 daily 文档，直接在同一份文档里推进开发。
|
||||
3. 完成一个最小 TODO 后，再改成 `[x] ~~...~~`。
|
||||
4. 每天结束时回填阻塞记录、验收结果和日终交接。
|
||||
|
||||
## 一周节奏
|
||||
|
||||
| Day | 状态 | 主题 | 主要交付 | Markdown | HTML |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| Day 1 | 已完成（2026-05-11） | 基础模型与工程骨架 | 资产、版本、审核、运行日志、审计日志、基础 API、最小财务数据源 | [Day 1](./day_1_foundation_models.md) | [HTML](<../agent_week_plan_html/day-1.html>) |
|
||||
| Day 2 | 已完成，待补浏览器走查记录 | 任务规则中心联调 | 规则/技能/MCP/任务列表与详情、Markdown、版本、审核 | [Day 2](./day_2_rule_center_integration.md) | [HTML](<../agent_week_plan_html/day-2.html>) |
|
||||
| Day 3 | 已完成主体功能，待补评测样本扩充 | 语义本体 MVP | 8 字段语义解析、日志、评测入口、OCR 摘要与最小会话上下文带入 | [Day 3](./day_3_semantic_ontology_mvp.md) | [HTML](<../agent_week_plan_html/day-3.html>) |
|
||||
| Day 4 | 已完成主干与会话串联，待接通提交/附件持久化链路 | Orchestrator 运行时 | 统一入口、路由、权限、工具调用、报销单写入路由、会话 Trace | [Day 4](./day_4_orchestrator_runtime.md) | [HTML](<../agent_week_plan_html/day-4.html>) |
|
||||
| Day 5 | 已完成问答主链路、草稿创建/补全与会话上下文，待接通提交状态流转 | User Agent MVP | 用户问答、报销单草稿创建/补全/提交、财务查询、规则解释、附件/OCR 带入 | [Day 5](./day_5_user_agent_mvp.md) | [HTML](<../agent_week_plan_html/day-5.html>) |
|
||||
| Day 6 | 未开始 | Hermes MVP | 定时任务、风险巡检、日报、知识候选、规则草稿 | [Day 6](./day_6_hermes_mvp.md) | [HTML](<../agent_week_plan_html/day-6.html>) |
|
||||
| Day 7 | 未开始 | 加固、演示和验收 | 回归、测试、演示脚本、交付说明 | [Day 7](./day_7_hardening_demo_acceptance.md) | [HTML](<../agent_week_plan_html/day-7.html>) |
|
||||
|
||||
## 当前完成情况
|
||||
|
||||
- Day 1 已完成，后端基础模型、审计和最小财务数据源已可供后续能力复用。
|
||||
- Day 2 已完成主要前后端联调，当前仅剩浏览器人工走查记录待补。
|
||||
- Day 3 主体已完成，`/api/v1/ontology/parse`、8 字段返回、缺槽位追问、权限判断和前端调试入口均已落地；OCR 摘要、附件上下文和最小会话历史已进入语义层，前端浏览器时间上下文也已接入相对时间换算，当前主要剩叙述型报销、附件/OCR 带入样本和模糊追问样本继续扩充。
|
||||
- Day 4 主干已完成，Orchestrator 已具备统一入口、User Agent / Hermes 路由、权限阻断、ToolCall 记录、Trace、降级和 `conversation_id` 会话串联；`expense_claims` 草稿建单/改单与 ToolCall / Audit 已接通，但提交、附件持久化和更细的 ToolCall Trace 仍未接通。
|
||||
- Day 5 问答主链路已完成，个人工作台和报销对话框已能把文本、附件名称、OCR 摘要、页面上下文和会话 ID 带入 Orchestrator，并返回回答、规则引用、风险说明、结构化草稿和识别核对面板；核对 UI 已调整为“右侧只看识别结果、主对话负责待补与风险、底部负责动作”，但附件 / OCR 结果落库及 `draft -> submitted` 仍未完成。
|
||||
|
||||
## Day 1 - Day 5 未完成补齐清单
|
||||
|
||||
- Day 1：当前周计划范围内无新增遗留项，基础资产、日志、审计和最小财务表已完成；文件资产、OCR 结果表和风险事件表作为 Day 5 真落库前置底座，设计已完成但代码未落地。
|
||||
- Day 2：仍缺一轮浏览器人工走查记录，需补充规则中心真实页面联调截图或缺陷清单。
|
||||
- Day 3：仍需补充叙述型报销长句样本、附件/OCR 摘要带入样本、模糊短句追问样本，并把这些样本纳入自动评测。
|
||||
- Day 4：仍需接通 `submit_expense_claim` 真服务，补齐附件挂接服务注册、ToolCall 更细粒度记录和前端 Trace 展示。
|
||||
- Day 5：仍需把附件和 OCR 识别结果真正落到 `document_assets`、`document_asset_versions`、`expense_item_documents`、`document_ocr_results`，并完成 `draft -> submitted` 状态流转、前端确认动作回写和提交流程确认。
|
||||
|
||||
## 关键依赖顺序
|
||||
|
||||
1. Day 1 必须先完成，因为后面所有能力都依赖资产、版本、审核、日志。
|
||||
2. Day 2 必须在 Day 3 前完成，因为语义和 Agent 需要读取规则、技能、MCP、任务资产。
|
||||
3. Day 3 必须在 Day 4 前完成，因为 Orchestrator 依赖语义本体做路由。
|
||||
4. Day 4 必须在 Day 5 / Day 6 前完成，因为 User Agent 和 Hermes 都应该由 Orchestrator 调用。
|
||||
5. Day 5 和 Day 6 可以部分并行，但都必须遵守权限、审计、Trace。
|
||||
6. Day 7 不新增大功能，只做加固、验收和交接。
|
||||
|
||||
## 最终验收
|
||||
|
||||
- 任务规则中心能看到规则、技能、MCP、任务。
|
||||
- 规则详情能编辑 Markdown、查看最近 5 个版本、切换版本。
|
||||
- 未审核规则不能上线。
|
||||
- 用户问题能解析出语义本体 8 字段。
|
||||
- Orchestrator 能路由到 User Agent 和 Hermes。
|
||||
- User Agent 能完成查询、解释、报销单草稿创建、字段补全和提交前确认。
|
||||
- Hermes 能执行一次风险巡检或日报任务。
|
||||
- AgentRun、ToolCall、AuditLog 都能追溯。
|
||||
- 有演示脚本和下一阶段交接文档。
|
||||
@@ -1,221 +0,0 @@
|
||||
# Day 1：基础模型与工程骨架
|
||||
|
||||
## 当前状态
|
||||
|
||||
- [x] ~~Day 1 已完成（2026-05-11）。~~
|
||||
- [x] ~~后端基础模型、API 骨架、种子数据、审计能力和 Day 2 联调入口均已落地。~~
|
||||
|
||||
## 今天的大开发点
|
||||
|
||||
Day 1 只做地基，不做复杂 Agent 智能。
|
||||
|
||||
核心是把后面 6 天都会用到的基础对象建出来：资产、版本、审核、运行日志、工具调用日志、语义解析日志、审计日志，以及最小财务业务数据来源。
|
||||
|
||||
## 为什么第一天做这个
|
||||
|
||||
如果没有稳定的数据模型，后面的任务规则中心、语义本体、Orchestrator、User Agent、Hermes 都会各自临时造结构，后期会很难合并。
|
||||
|
||||
## 今天主要交付
|
||||
|
||||
- [x] ~~统一资产模型：规则、技能、MCP、任务。~~
|
||||
- [x] ~~版本模型：规则 Markdown 和其他资产配置快照。~~
|
||||
- [x] ~~审核模型：未审核不能上线。~~
|
||||
- [x] ~~Agent 运行日志：所有 Agent 执行都有 `run_id`。~~
|
||||
- [x] ~~工具调用日志：MCP、数据库、LLM、OCR、规则引擎调用都可追踪。~~
|
||||
- [x] ~~语义解析日志：后续语义本体结果可回放。~~
|
||||
- [x] ~~审计日志：所有写操作可追责。~~
|
||||
- [x] ~~最小财务业务数据来源：报销、应收、应付。~~
|
||||
|
||||
## 实际落地结果
|
||||
|
||||
- [x] ~~新增 `AgentAsset`、`AgentAssetVersion`、`AgentAssetReview`、`AgentRun`、`AgentToolCall`、`SemanticParseLog`、`AuditLog`、`ExpenseClaim`、`ExpenseClaimItem`、`AccountsReceivableRecord`、`AccountsPayableRecord`。~~
|
||||
- [x] ~~新增 `/api/v1/agent-assets`、`/api/v1/agent-runs`、`/api/v1/audit-logs` 相关接口。~~
|
||||
- [x] ~~种子数据已覆盖 3 条规则、2 条技能、2 条 MCP、3 条任务，以及报销 / 应收 / 应付示例数据。~~
|
||||
- [x] ~~旧开发库启动时会自动补齐新增资产和版本，不需要手动清库。~~
|
||||
|
||||
相关架构文档：
|
||||
|
||||
- [整体架构](<../agent plan/01_overall_architecture.md>)
|
||||
- [语义本体](<../agent plan/02_semantic_ontology.md>)
|
||||
- [数据契约与治理](<../agent plan/06_data_contracts_and_governance.md>)
|
||||
- [能力注册](<../agent plan/07_capability_registry.md>)
|
||||
- [权限与确认](<../agent plan/08_permission_confirmation.md>)
|
||||
- [观测与 Trace](<../agent plan/09_observability_and_trace.md>)
|
||||
- [财务单据标准模型](<../agent plan/14_financial_document_canonical_model.md>)
|
||||
|
||||
## 当天验收门槛
|
||||
|
||||
- [x] ~~数据库或等价存储能创建基础对象。~~
|
||||
- [x] ~~API 服务能启动。~~
|
||||
- [x] ~~资产列表能返回规则、技能、MCP、任务。~~
|
||||
- [x] ~~规则资产能关联 Markdown 当前版本。~~
|
||||
- [x] ~~未审核规则不能上线。~~
|
||||
- [x] ~~AgentRun 能保存一条运行记录。~~
|
||||
- [x] ~~AuditLog 能保存一条写操作记录。~~
|
||||
|
||||
## Day 2 联调入口
|
||||
|
||||
- `GET /api/v1/agent-assets`
|
||||
- `GET /api/v1/agent-assets/{asset_id}`
|
||||
- `GET /api/v1/agent-assets/{asset_id}/versions?limit=5`
|
||||
- `POST /api/v1/agent-assets/{asset_id}/reviews`
|
||||
- `POST /api/v1/agent-assets/{asset_id}/activate`
|
||||
- `GET /api/v1/audit-logs`
|
||||
|
||||
## 今天不做
|
||||
|
||||
- 不做完整 Agent 对话。
|
||||
- 不做完整 Hermes 调度。
|
||||
- 不做真实 OCR。
|
||||
- 不做复杂规则推理。
|
||||
|
||||
## 详细执行清单
|
||||
|
||||
以下内容为合并后的详细执行清单。
|
||||
|
||||
## 0. 开始前检查
|
||||
|
||||
- [x] ~~确认后端目录为 `/app/server`，模型、路由、启动入口和测试目录已定位。~~
|
||||
- [x] ~~确认本次改动以增量方式落到现有 FastAPI + SQLAlchemy 工程，不回退无关文件。~~
|
||||
|
||||
验收证据：
|
||||
|
||||
- [x] ~~模型注册位于 `server/src/app/db/base.py`，路由注册位于 `server/src/app/api/v1/router.py`，启动入口位于 `server/src/app/main.py`，测试位于 `server/tests`。~~
|
||||
|
||||
## 1. 统一命名和边界
|
||||
|
||||
- [x] ~~统一枚举：`rule | skill | mcp | task`、`draft | review | active | disabled`、`pending | approved | rejected`、`orchestrator | user_agent | hermes`。~~
|
||||
- [x] ~~统一运行来源、权限级别、内容类型、运行状态和工具类型命名，避免出现第二套并行语义。~~
|
||||
|
||||
验收证据：
|
||||
|
||||
- [x] ~~`server/src/app/core/agent_enums.py` 已成为模型、Schema 和服务层的统一枚举入口。~~
|
||||
|
||||
## 2. 设计最小财务业务数据模型
|
||||
|
||||
- [x] ~~建立 `expense_claims`、`expense_claim_items`、`accounts_receivable`、`accounts_payable`。~~
|
||||
- [x] ~~字段覆盖时间、地点、理由、金额、员工、部门、状态，以及应收 / 应付的金额、到期日、账龄、风险标记。~~
|
||||
|
||||
验收证据：
|
||||
|
||||
- [x] ~~`server/src/app/models/financial_record.py` 与 `document/development/agent plan/14_financial_document_canonical_model.md` 形成直接映射。~~
|
||||
|
||||
## 3. 建立 AgentAsset 模型
|
||||
|
||||
- [x] ~~建立 `AgentAsset`，包含 `asset_type`、`code`、`name`、`description`、`domain`、`scenario_json`、`owner`、`reviewer`、`status`、`current_version`、`config_json` 等核心字段。~~
|
||||
- [x] ~~对 `code`、`asset_type`、`status`、`domain` 建立唯一约束或索引。~~
|
||||
|
||||
验收证据：
|
||||
|
||||
- [x] ~~资产列表可按 `rule`、`skill`、`mcp`、`task` 四类过滤返回。~~
|
||||
|
||||
## 4. 建立 AgentAssetVersion 模型
|
||||
|
||||
- [x] ~~建立 `AgentAssetVersion`，规则版本保存 Markdown，其余资产版本保存 JSON 快照。~~
|
||||
- [x] ~~对 `asset_id + version` 建立唯一约束，并支持按资产读取最近版本列表。~~
|
||||
|
||||
验收证据：
|
||||
|
||||
- [x] ~~规则详情接口可返回 `current_version_content` 和 `recent_versions`。~~
|
||||
|
||||
## 5. 建立 AgentAssetReview 模型
|
||||
|
||||
- [x] ~~建立 `AgentAssetReview`，保存版本、审核人、审核状态、审核备注和审核时间。~~
|
||||
- [x] ~~服务层实现规则版本未 `approved` 时禁止上线。~~
|
||||
|
||||
验收证据：
|
||||
|
||||
- [x] ~~`POST /api/v1/agent-assets/{asset_id}/activate` 对待审规则返回 400 拦截。~~
|
||||
|
||||
## 6. 建立 AgentRun 模型
|
||||
|
||||
- [x] ~~建立 `AgentRun`，包含 `run_id`、`agent`、`source`、`ontology_json`、`route_json`、`permission_level`、`status`、`result_summary`、`error_message` 等字段。~~
|
||||
- [x] ~~所有运行记录统一生成 `run_id`，并允许失败态保存错误信息。~~
|
||||
|
||||
验收证据：
|
||||
|
||||
- [x] ~~`AgentRunService.create_run()` 会自动生成 `run_` 前缀标识，并可回读失败摘要。~~
|
||||
|
||||
## 7. 建立 AgentToolCall 模型
|
||||
|
||||
- [x] ~~建立 `AgentToolCall`，可记录工具类型、工具名、请求 / 响应 JSON、耗时和错误信息。~~
|
||||
- [x] ~~同一个 `run_id` 下支持多次工具调用追踪。~~
|
||||
|
||||
验收证据：
|
||||
|
||||
- [x] ~~种子运行数据已覆盖数据库查询、MCP 调用和权限规则引擎调用。~~
|
||||
|
||||
## 8. 建立 SemanticParseLog 模型
|
||||
|
||||
- [x] ~~建立 `SemanticParseLog`，覆盖场景、意图、实体、时间范围、指标、约束、风险、权限和置信度。~~
|
||||
- [x] ~~支持按 `run_id` 回放 Day 3 语义结果。~~
|
||||
|
||||
验收证据：
|
||||
|
||||
- [x] ~~`GET /api/v1/agent-runs/{run_id}` 已能携带 `semantic_parse` 返回。~~
|
||||
|
||||
## 9. 建立 AuditLog 模型
|
||||
|
||||
- [x] ~~建立 `AuditLog` 和统一 `AuditLogService`。~~
|
||||
- [x] ~~资产创建、版本保存、审核、上线等写操作都会留下审计记录。~~
|
||||
|
||||
验收证据：
|
||||
|
||||
- [x] ~~`GET /api/v1/audit-logs` 可返回种子审计日志，服务层新建资产也会落审计。~~
|
||||
|
||||
## 10. 建立 Schema / DTO
|
||||
|
||||
- [x] ~~建立 `AgentAssetCreate / Update / Read / ListItem`、`AgentAssetVersionRead`、`AgentAssetReviewRead`、`RuleMarkdownUpdate`、`AgentRunRead`、`AgentToolCallRead`、`SemanticParseRead`。~~
|
||||
- [x] ~~所有 JSON 字段以结构化对象返回，不回传字符串化 JSON。~~
|
||||
|
||||
验收证据：
|
||||
|
||||
- [x] ~~列表 DTO 不返回大块 Markdown，详情 DTO 返回当前版本正文和最近版本。~~
|
||||
|
||||
## 11. 建立 API 骨架
|
||||
|
||||
- [x] ~~建立 `GET/POST/PATCH /api/v1/agent-assets`、`GET /api/v1/agent-assets/{asset_id}`、`GET/POST /api/v1/agent-assets/{asset_id}/versions`、`POST /api/v1/agent-assets/{asset_id}/reviews`、`POST /api/v1/agent-assets/{asset_id}/activate`。~~
|
||||
- [x] ~~建立 `GET /api/v1/agent-runs`、`GET /api/v1/agent-runs/{run_id}`、`GET /api/v1/audit-logs`。~~
|
||||
|
||||
验收证据：
|
||||
|
||||
- [x] ~~所有接口已挂到 `server/src/app/api/v1/router.py`，并通过 `create_app()` 自动暴露。~~
|
||||
|
||||
## 12. 建立种子数据
|
||||
|
||||
- [x] ~~种子资产补齐到 3 条规则、2 条技能、2 条 MCP、3 条任务。~~
|
||||
- [x] ~~三条规则都具备至少 2 个版本，并覆盖 `approved / pending / rejected` 三种审核样本。~~
|
||||
- [x] ~~旧开发数据库启动时会自动增量补齐新增资产和版本，不要求手动清库。~~
|
||||
|
||||
验收证据：
|
||||
|
||||
- [x] ~~Smoke：`GET /api/v1/agent-assets` 返回 10 条资产，`GET /api/v1/agent-runs` 返回 3 条运行日志，`GET /api/v1/audit-logs` 返回 4 条审计日志。~~
|
||||
|
||||
## 13. 最小测试
|
||||
|
||||
- [x] ~~新增 Day 1 服务层与接口层测试，覆盖种子完整性、版本历史、未审核不能上线、运行日志生成和审计日志写入。~~
|
||||
- [x] ~~Ruff 校验通过，Day 1 新增文件保持可检查状态。~~
|
||||
|
||||
验收证据：
|
||||
|
||||
- [x] ~~`/app/server/.venv/bin/pytest -q /app/server/tests/test_agent_asset_service.py /app/server/tests/test_agent_foundation_endpoints.py` -> `11 passed`。~~
|
||||
- [x] ~~`/app/server/.venv/bin/pytest -q tests` 已通过全量后端测试。~~
|
||||
|
||||
## 14. Day 1 验收
|
||||
|
||||
- [x] ~~数据库能创建所有新增表或等价结构。~~
|
||||
- [x] ~~API 服务能启动，OpenAPI 能看到新增接口。~~
|
||||
- [x] ~~资产列表接口返回规则、技能、MCP、任务；规则详情带 Markdown 当前版本和最近版本列表。~~
|
||||
- [x] ~~未审核规则不能上线；AgentRun 和 AuditLog 均可保存记录。~~
|
||||
- [x] ~~所有 Day 1 TODO 已改为完成态。~~
|
||||
|
||||
## 阻塞记录
|
||||
|
||||
- [x] ~~暂无阻塞。~~
|
||||
|
||||
## 日终交接
|
||||
|
||||
- [x] ~~已完成模型：资产、版本、审核、运行日志、工具调用、语义解析、审计、报销、应收、应付。~~
|
||||
- [x] ~~已完成 API：`/api/v1/agent-assets`、`/api/v1/agent-runs`、`/api/v1/audit-logs`。~~
|
||||
- [x] ~~Day 2 前端联调应优先使用 `GET /api/v1/agent-assets`、`GET /api/v1/agent-assets/{asset_id}`、`GET /api/v1/agent-assets/{asset_id}/versions?limit=5`、`POST /api/v1/agent-assets/{asset_id}/reviews`、`POST /api/v1/agent-assets/{asset_id}/activate`。~~
|
||||
- [x] ~~后续 Day 4 及以后运行时方向按用户要求转向 `LangChain + LangGraph`，Hermes 继续作为内部数字员工入口；Day 1 保留为数据与治理底座。~~
|
||||
@@ -1,296 +0,0 @@
|
||||
# Day 2：任务规则中心联调
|
||||
|
||||
## 今天的大开发点
|
||||
|
||||
把任务规则中心从静态页面改成可和后端资产体系联动的生产形态。
|
||||
|
||||
重点是规则、技能、MCP、任务四类资产的列表和详情，以及规则 Markdown、版本、审核、上线约束。
|
||||
|
||||
## 为什么第二天做这个
|
||||
|
||||
任务规则中心是业务人员管理 Agent 能力的入口。后续语义本体、Orchestrator、User Agent、Hermes 都要读取这里注册的规则、技能、MCP 和任务。
|
||||
|
||||
## 今天主要交付
|
||||
|
||||
- 规则、技能、MCP、任务四个页签对接资产 API。
|
||||
- 列表支持搜索、筛选、状态展示。
|
||||
- 规则详情展示 Markdown 内容。
|
||||
- 管理员可编辑规则 Markdown。
|
||||
- 规则版本展示最近 5 个版本。
|
||||
- 版本切换需要弹窗确认。
|
||||
- 审核者信息放在标题区域。
|
||||
- 右侧只保留版本信息。
|
||||
- 未审核规则上线时被后端拦截。
|
||||
|
||||
## 当前完成情况
|
||||
|
||||
- [x] ~~四个页签已切到真实资产 API。~~
|
||||
- [x] ~~规则 Markdown、版本切换、审核、上线动作已联调。~~
|
||||
- [x] ~~前端构建已通过。~~
|
||||
- [ ] 浏览器手动走查记录待补。
|
||||
|
||||
相关架构文档：
|
||||
|
||||
- [能力注册](<../agent plan/07_capability_registry.md>)
|
||||
- [规则形成生命周期](<../agent plan/13_rule_formation_lifecycle.md>)
|
||||
- [数据契约与治理](<../agent plan/06_data_contracts_and_governance.md>)
|
||||
|
||||
## 当天验收门槛
|
||||
|
||||
- 四个页签可切换并有真实 API 或 Mock API 数据。
|
||||
- 规则详情可编辑 Markdown。
|
||||
- Markdown 保存后刷新不丢失。
|
||||
- 版本卡片可切换版本。
|
||||
- 未审核规则不能上线。
|
||||
- 前端构建通过。
|
||||
|
||||
## 今天不做
|
||||
|
||||
- 不做规则自动生成。
|
||||
- 不做完整 MCP 真实调用。
|
||||
- 不做复杂权限矩阵。
|
||||
- 不重做 UI 风格，只在现有风格上微调。
|
||||
|
||||
## 详细执行清单
|
||||
|
||||
以下内容为合并后的详细执行清单。
|
||||
|
||||
## 0. 开始前检查
|
||||
|
||||
- [x] ~~确认 Day 1 API 已可访问。~~
|
||||
- [x] ~~确认前端任务规则中心文件位置。~~
|
||||
- [x] ~~确认现有路由名称和导航名称。~~
|
||||
- [x] ~~确认现有 UI 风格，不重新做大改版。~~
|
||||
- [x] ~~确认当前页面已有页签：规则、技能、MCP、任务。~~
|
||||
- [x] ~~确认详情页隐藏顶部 title bar 的逻辑仍然有效。~~
|
||||
- [x] ~~确认返回列表栏高度没有被重新拉高。~~
|
||||
|
||||
## 1. API Client
|
||||
|
||||
- [x] ~~新增或扩展资产列表请求函数。~~
|
||||
- [x] ~~新增资产详情请求函数。~~
|
||||
- [x] ~~新增版本列表请求函数。~~
|
||||
- [x] ~~新增规则 Markdown 保存请求函数。~~
|
||||
- [x] ~~新增审核请求函数。~~
|
||||
- [x] ~~新增上线请求函数。~~
|
||||
- [x] ~~新增运行日志请求函数。~~
|
||||
- [x] ~~给所有请求增加加载态。~~
|
||||
- [x] ~~给所有请求增加错误态。~~
|
||||
- [x] ~~给所有写请求增加成功提示。~~
|
||||
|
||||
验收证据：
|
||||
|
||||
- [x] ~~前端不再只依赖本地硬编码资产数据。~~
|
||||
- [x] ~~后端不可用时页面有明确错误提示。~~
|
||||
|
||||
## 2. 列表页数据接入
|
||||
|
||||
- [x] ~~规则页签请求 `asset_type=rule`。~~
|
||||
- [x] ~~技能页签请求 `asset_type=skill`。~~
|
||||
- [x] ~~MCP 页签请求 `asset_type=mcp`。~~
|
||||
- [x] ~~任务页签请求 `asset_type=task`。~~
|
||||
- [x] ~~搜索框传递关键词或本地过滤。~~
|
||||
- [x] ~~类型下拉和搜索框可以同时生效。~~
|
||||
- [x] ~~状态筛选可以过滤 `draft | review | active | disabled`。~~
|
||||
- [x] ~~列表卡片展示名称。~~
|
||||
- [x] ~~列表卡片展示摘要。~~
|
||||
- [x] ~~列表卡片展示状态。~~
|
||||
- [x] ~~列表卡片展示负责人。~~
|
||||
- [x] ~~列表卡片展示最近更新时间。~~
|
||||
- [x] ~~空数据时展示空态。~~
|
||||
- [x] ~~加载中时展示骨架或加载状态。~~
|
||||
|
||||
验收证据：
|
||||
|
||||
- [x] ~~四个页签都能切换。~~
|
||||
- [x] ~~四个页签都有数据或空态。~~
|
||||
- [x] ~~搜索和筛选不会互相覆盖。~~
|
||||
|
||||
## 3. 规则详情页主信息
|
||||
|
||||
- [x] ~~打开规则资产时请求详情 API。~~
|
||||
- [x] ~~Hero title 展示规则名称。~~
|
||||
- [x] ~~Hero title 下方展示审核者。~~
|
||||
- [x] ~~Hero title 下方展示审核状态。~~
|
||||
- [x] ~~Hero title 下方展示上线条件。~~
|
||||
- [x] ~~Hero title 高度保持紧凑。~~
|
||||
- [x] ~~详情页不显示外层顶部 title bar。~~
|
||||
- [x] ~~返回列表栏高度保持原有紧凑高度。~~
|
||||
|
||||
验收证据：
|
||||
|
||||
- [x] ~~用户能一眼看到该规则是否已审核。~~
|
||||
- [x] ~~用户不会看到两层 title。~~
|
||||
|
||||
## 4. Markdown 编辑器
|
||||
|
||||
- [x] ~~从当前版本读取 Markdown 内容。~~
|
||||
- [x] ~~Markdown 编辑框高度和右侧版本卡片底部对齐。~~
|
||||
- [x] ~~Markdown 编辑框支持长内容滚动。~~
|
||||
- [x] ~~Markdown 编辑框保存时调用 API。~~
|
||||
- [x] ~~保存后创建新版本或更新草稿版本，按后端约定执行。~~
|
||||
- [x] ~~保存成功后刷新版本列表。~~
|
||||
- [x] ~~保存失败时保留用户输入。~~
|
||||
- [x] ~~编辑器禁用态覆盖 `active` 且无编辑权限的情况。~~
|
||||
- [x] ~~编辑器底部展示最后保存时间。~~
|
||||
|
||||
验收证据：
|
||||
|
||||
- [x] ~~编辑 Markdown 后刷新页面内容仍存在。~~
|
||||
- [x] ~~保存失败不会丢内容。~~
|
||||
- [x] ~~左右卡片底部视觉对齐。~~
|
||||
|
||||
## 5. 版本卡片
|
||||
|
||||
- [x] ~~右侧只保留版本信息卡片。~~
|
||||
- [x] ~~版本卡片宽度足够展示版本号、日期、状态。~~
|
||||
- [x] ~~展示最近 5 个版本。~~
|
||||
- [x] ~~当前版本有明显但不突兀的标识。~~
|
||||
- [x] ~~当前版本标识居中显示。~~
|
||||
- [x] ~~选中状态只变色，不改变内容对齐。~~
|
||||
- [x] ~~日期列和其他版本日期对齐。~~
|
||||
- [x] ~~点击非当前版本时弹出确认弹窗。~~
|
||||
- [x] ~~弹窗展示目标版本号。~~
|
||||
- [x] ~~弹窗展示切换风险提示。~~
|
||||
- [x] ~~确认后切换当前展示内容。~~
|
||||
- [x] ~~取消后不改变当前版本。~~
|
||||
|
||||
验收证据：
|
||||
|
||||
- [x] ~~版本切换不会造成列表文字位移。~~
|
||||
- [x] ~~当前版本背景能完全覆盖内容区域。~~
|
||||
- [x] ~~版本卡片不贴右侧边界。~~
|
||||
|
||||
## 6. 审核与上线
|
||||
|
||||
- [x] ~~详情中展示审核者姓名。~~
|
||||
- [x] ~~详情中展示审核时间。~~
|
||||
- [x] ~~详情中展示审核意见。~~
|
||||
- [x] ~~未审核规则显示不能上线原因。~~
|
||||
- [x] ~~点击上线时调用后端上线接口。~~
|
||||
- [x] ~~后端拒绝时展示拒绝原因。~~
|
||||
- [x] ~~审核通过后上线按钮可用。~~
|
||||
- [x] ~~审核动作写入审计日志。~~
|
||||
- [x] ~~上线动作写入审计日志。~~
|
||||
|
||||
验收证据：
|
||||
|
||||
- [x] ~~pending 规则无法上线。~~
|
||||
- [x] ~~approved 规则可以上线。~~
|
||||
- [x] ~~rejected 规则无法上线。~~
|
||||
|
||||
## 7. 技能详情
|
||||
|
||||
- [x] ~~技能页签列表展示能力名称。~~
|
||||
- [x] ~~技能详情展示能力说明。~~
|
||||
- [x] ~~技能详情展示输入参数。~~
|
||||
- [x] ~~技能详情展示输出参数。~~
|
||||
- [x] ~~技能详情展示依赖能力。~~
|
||||
- [x] ~~技能详情展示适用场景。~~
|
||||
- [x] ~~技能详情展示负责人。~~
|
||||
- [x] ~~技能详情展示版本。~~
|
||||
- [x] ~~技能详情不使用规则 Markdown 编辑器。~~
|
||||
|
||||
验收证据：
|
||||
|
||||
- [x] ~~技能和规则详情不会混用 UI。~~
|
||||
|
||||
## 8. MCP 详情
|
||||
|
||||
- [x] ~~MCP 页签列表展示外部服务名称。~~
|
||||
- [x] ~~MCP 详情展示服务类型。~~
|
||||
- [x] ~~MCP 详情展示调用地址或能力名。~~
|
||||
- [x] ~~MCP 详情展示鉴权方式。~~
|
||||
- [x] ~~MCP 详情展示超时配置。~~
|
||||
- [x] ~~MCP 详情展示降级策略。~~
|
||||
- [x] ~~MCP 详情展示最近调用状态。~~
|
||||
- [x] ~~MCP 详情展示负责人。~~
|
||||
|
||||
验收证据：
|
||||
|
||||
- [x] ~~MCP 被定义为外部服务，而不是技能规则。~~
|
||||
|
||||
## 9. 任务详情
|
||||
|
||||
- [x] ~~任务页签展示定时任务名称。~~
|
||||
- [x] ~~任务详情展示 cron 或调度周期。~~
|
||||
- [x] ~~任务详情展示执行 Agent，默认 Hermes。~~
|
||||
- [x] ~~任务详情展示任务目标。~~
|
||||
- [x] ~~任务详情展示风险等级。~~
|
||||
- [x] ~~任务详情展示最近执行时间。~~
|
||||
- [x] ~~任务详情展示最近执行结果。~~
|
||||
- [x] ~~任务详情展示启停状态。~~
|
||||
|
||||
验收证据：
|
||||
|
||||
- [x] ~~定时任务用户可见名称为“任务”。~~
|
||||
- [x] ~~技术字段可保留 `schedule`，但 UI 不显示“定时任务”。~~
|
||||
|
||||
## 10. 前端质量
|
||||
|
||||
- [x] ~~页面在 1366 宽度下无横向滚动。~~
|
||||
- [x] ~~页面在 1920 宽度下右侧卡片不过宽。~~
|
||||
- [x] ~~页面在窄屏下详情区域可滚动。~~
|
||||
- [x] ~~所有按钮有禁用态。~~
|
||||
- [x] ~~所有弹窗有取消按钮。~~
|
||||
- [x] ~~所有表单错误有提示。~~
|
||||
- [x] ~~所有日期格式统一。~~
|
||||
- [x] ~~状态颜色和现有系统一致。~~
|
||||
|
||||
验收证据：
|
||||
|
||||
- [x] ~~`npm run build` 通过。~~
|
||||
- [ ] 任务规则中心手动走查通过。
|
||||
|
||||
## 11. Day 2 验收
|
||||
|
||||
- [x] ~~规则、技能、MCP、任务四个页签可用。~~
|
||||
- [x] ~~搜索框和筛选下拉可用。~~
|
||||
- [x] ~~规则详情展示 Markdown。~~
|
||||
- [x] ~~规则 Markdown 可保存。~~
|
||||
- [x] ~~右侧只保留版本信息。~~
|
||||
- [x] ~~版本可切换且有弹窗确认。~~
|
||||
- [x] ~~审核者信息在标题下方。~~
|
||||
- [x] ~~未审核规则不能上线。~~
|
||||
- [x] ~~前端构建通过。~~
|
||||
- [x] ~~所有完成项已按完成态标记。~~
|
||||
|
||||
## 阻塞记录
|
||||
|
||||
- [x] ~~暂无。~~
|
||||
|
||||
## 日终交接
|
||||
|
||||
- [x] ~~写明已接入的 API。~~
|
||||
- [x] ~~写明仍然使用 Mock 的字段。~~
|
||||
- [x] ~~写明 UI 未完成项。~~
|
||||
- [x] ~~写明 Day 3 语义本体需要复用的资产数据。~~
|
||||
|
||||
已接入的 API：
|
||||
|
||||
- `GET /api/v1/agent-assets?asset_type=rule|skill|mcp|task`
|
||||
- `GET /api/v1/agent-assets/{asset_id}`
|
||||
- `GET /api/v1/agent-assets/{asset_id}/versions`
|
||||
- `POST /api/v1/agent-assets/{asset_id}/versions`
|
||||
- `POST /api/v1/agent-assets/{asset_id}/reviews`
|
||||
- `POST /api/v1/agent-assets/{asset_id}/activate`
|
||||
- `GET /api/v1/agent-runs`
|
||||
|
||||
仍然使用 Mock / 种子数据的字段：
|
||||
|
||||
- MCP 服务地址仍是 `mock://...` 种子地址，用于占位联调。
|
||||
- MCP 最近调用状态、任务最近执行结果来自 Day 1 注入的 `AgentRun` 种子数据。
|
||||
- 技能、MCP、任务详情仍以只读方式展示，未开放编辑表单。
|
||||
|
||||
UI 未完成项：
|
||||
|
||||
- 未做浏览器内人工走查记录，当前仅完成构建验证与代码层联调。
|
||||
- 技能、MCP、任务的编辑能力仍留待后续 Day 3 / Day 4 之后按权限开放。
|
||||
|
||||
Day 3 语义本体需要复用的资产数据：
|
||||
|
||||
- 资产主键与编码：`id`、`code`、`asset_type`
|
||||
- 业务归类：`domain`、`scenario_json`
|
||||
- 当前生效版本：`current_version`、`current_version_content`、`current_version_content_type`
|
||||
- 治理状态：`status`、`latest_review`、`recent_versions`
|
||||
- 运行关联：`config_json.agent`、`config_json.cron`、`AgentRun.task_id`、`tool_calls`
|
||||
@@ -1,304 +0,0 @@
|
||||
# Day 3：语义本体 MVP
|
||||
|
||||
## 今天的大开发点
|
||||
|
||||
建立模型优先的语义解析层，把自然语言问题转换成统一的 8 个核心字段。
|
||||
|
||||
这一天的目标不是继续堆关键词，而是先把真实模型接入语义层，让报销、应收、应付、知识和风险相关问题进入稳定结构，再由规则做兜底和校验。
|
||||
|
||||
## 为什么第三天做这个
|
||||
|
||||
Orchestrator 不能直接根据原始文本做可靠路由。它需要先拿到结构化语义，再决定调用 User Agent、Hermes、规则、MCP 或知识库。
|
||||
|
||||
## 今天主要交付
|
||||
|
||||
- 语义本体 8 字段结构。
|
||||
- 场景识别：报销、应收、应付、知识、未知。
|
||||
- 意图识别：查询、解释、对比、风险检查、草稿、操作。
|
||||
- 业务对象提取：员工、客户、供应商、部门、项目、单据、金额。
|
||||
- 时间范围解析。
|
||||
- 指标和约束解析。
|
||||
- 风险信号和权限级别判断。
|
||||
- LLM 结构化解析 Prompt。
|
||||
- Schema 校验与 JSON 清洗。
|
||||
- 规则回退解析。
|
||||
- 低置信度追问和缺槽位追问。
|
||||
- 语义解析 API。
|
||||
- 解析日志和最小评测集。
|
||||
|
||||
## 当前完成情况
|
||||
|
||||
- [x] ~~`/api/v1/ontology/parse` 已上线，8 字段语义结构、缺槽位、歧义、权限和澄清问题均可返回。~~
|
||||
- [x] ~~语义层已切到“模型优先 + 规则回退”，并把结果写入 `AgentRun` / `SemanticParseLog`。~~
|
||||
- [x] ~~附件名称、附件数量、OCR 摘要和 OCR 文档摘要已能作为上下文带入语义层。~~
|
||||
- [x] ~~最小会话历史、上一轮场景/意图和 `draft_claim_id` 已能作为上下文带入语义层，用于识别“改成 800”“继续补充”这类追问。~~
|
||||
- [x] ~~叙述型报销语义已补强：`客户 + 吃饭/请客/宴请/招待` 优先归类为业务招待费，不再误打到应收查询。~~
|
||||
- [x] ~~相对时间已支持标准化展示：前端会透传浏览器本地时间上下文，`今天 / 昨天 / 本月 / 4 月` 会换算成绝对日期；展示层默认优先显示绝对日期，原始表达仅作为辅助信息。~~
|
||||
- [x] ~~前端调试入口与核心评测测试已完成并通过。~~
|
||||
- [ ] 叙述型报销样本、附件/OCR 带入样本和模糊短句追问样本仍需继续扩充。
|
||||
|
||||
相关架构文档：
|
||||
|
||||
- [语义本体](<../agent plan/02_semantic_ontology.md>)
|
||||
- [财务单据标准模型](<../agent plan/14_financial_document_canonical_model.md>)
|
||||
- [数据契约与治理](<../agent plan/06_data_contracts_and_governance.md>)
|
||||
|
||||
## 当天验收门槛
|
||||
|
||||
- 输入自然语言问题能返回 8 个字段。
|
||||
- 模型解析失败时能自动回退到规则解析。
|
||||
- 低置信度问题能返回澄清问题。
|
||||
- 越权动作不会被标记为可直接执行。
|
||||
- 解析结果能写入日志。
|
||||
- 至少覆盖报销、应收、应付三个场景。
|
||||
- 叙述型报销输入不会被错误路由到应收或应付。
|
||||
|
||||
## 今天不做
|
||||
|
||||
- 不做复杂多轮对话记忆。
|
||||
- 不做完整 Agent 自主规划。
|
||||
- 不做自动执行业务流程。
|
||||
|
||||
## 详细执行清单
|
||||
|
||||
以下内容为合并后的详细执行清单。
|
||||
|
||||
## 0. 开始前检查
|
||||
|
||||
- [x] ~~确认 Day 1 的 `SemanticParseLog` 可用。~~
|
||||
- [x] ~~确认 Day 1 的 `AgentRun` 可用。~~
|
||||
- [x] ~~确认 Day 2 的资产 API 可用。~~
|
||||
- [x] ~~找到后端服务层目录。~~
|
||||
- [x] ~~找到现有 LLM 调用或 Mock 调用方式。~~
|
||||
- [x] ~~确认当前是否允许真实调用 LLM。~~
|
||||
- [x] ~~确认当前运行时模型槽位可用于语义解析。~~
|
||||
- [x] ~~如果真实模型不可用，已准备规则解析回退路径。~~
|
||||
|
||||
## 1. 定义 8 个核心字段
|
||||
|
||||
- [x] ~~定义字段 `scenario`，表示业务场景。~~
|
||||
- [x] ~~定义字段 `intent`，表示用户意图。~~
|
||||
- [x] ~~定义字段 `entities`，表示业务对象。~~
|
||||
- [x] ~~定义字段 `time_range`，表示时间范围。~~
|
||||
- [x] ~~定义字段 `metrics`，表示指标或金额口径。~~
|
||||
- [x] ~~定义字段 `constraints`，表示过滤条件。~~
|
||||
- [x] ~~定义字段 `risk_flags`，表示风险信号。~~
|
||||
- [x] ~~定义字段 `permission`，表示动作权限。~~
|
||||
- [x] ~~为每个字段写清楚类型。~~
|
||||
- [x] ~~为每个字段写清楚是否必填。~~
|
||||
- [x] ~~为每个字段写清楚默认值。~~
|
||||
- [x] ~~为每个字段写清楚示例。~~
|
||||
|
||||
验收证据：
|
||||
|
||||
- [x] ~~8 个字段在 Schema、服务层、日志中名字一致。~~
|
||||
|
||||
## 2. 设计字段枚举
|
||||
|
||||
- [x] ~~`scenario` 支持 `expense`。~~
|
||||
- [x] ~~`scenario` 支持 `accounts_receivable`。~~
|
||||
- [x] ~~`scenario` 支持 `accounts_payable`。~~
|
||||
- [x] ~~`scenario` 支持 `knowledge`。~~
|
||||
- [x] ~~`scenario` 支持 `unknown`。~~
|
||||
- [x] ~~`intent` 支持 `query`。~~
|
||||
- [x] ~~`intent` 支持 `explain`。~~
|
||||
- [x] ~~`intent` 支持 `compare`。~~
|
||||
- [x] ~~`intent` 支持 `risk_check`。~~
|
||||
- [x] ~~`intent` 支持 `draft`。~~
|
||||
- [x] ~~`intent` 支持 `operate`。~~
|
||||
- [x] ~~`permission.level` 支持 `read`。~~
|
||||
- [x] ~~`permission.level` 支持 `draft_write`。~~
|
||||
- [x] ~~`permission.level` 支持 `approval_required`。~~
|
||||
- [x] ~~`permission.level` 支持 `forbidden`。~~
|
||||
|
||||
验收证据：
|
||||
|
||||
- [x] ~~未识别的问题不会抛异常，返回 `unknown`。~~
|
||||
|
||||
## 3. 建立 Schema
|
||||
|
||||
- [x] ~~定义 `OntologyParseRequest`。~~
|
||||
- [x] ~~`OntologyParseRequest` 包含 `query`。~~
|
||||
- [x] ~~`OntologyParseRequest` 包含 `user_id`。~~
|
||||
- [x] ~~`OntologyParseRequest` 包含 `context_json`。~~
|
||||
- [x] ~~定义 `OntologyParseResult`。~~
|
||||
- [x] ~~`OntologyParseResult` 包含 8 个核心字段。~~
|
||||
- [x] ~~`OntologyParseResult` 包含 `confidence`。~~
|
||||
- [x] ~~`OntologyParseResult` 包含 `clarification_required`。~~
|
||||
- [x] ~~`OntologyParseResult` 包含 `clarification_question`。~~
|
||||
- [x] ~~`OntologyParseResult` 包含 `run_id`。~~
|
||||
- [x] ~~定义字段级错误结构。~~
|
||||
|
||||
验收证据：
|
||||
|
||||
- [x] ~~OpenAPI 中可以看到语义解析请求和响应。~~
|
||||
|
||||
## 4. 实现解析服务
|
||||
|
||||
- [x] ~~新增 `SemanticOntologyService` 或同等服务。~~
|
||||
- [x] ~~实现 `parse(query, user_context)` 主函数。~~
|
||||
- [x] ~~增加上下文装配层，输入文本、页面上下文、附件摘要和预抽取字段。~~
|
||||
- [x] ~~实现模型优先的结构化语义解析。~~
|
||||
- [x] ~~约束模型只输出 JSON。~~
|
||||
- [x] ~~对模型输出做清洗、提取和 Schema 校验。~~
|
||||
- [x] ~~模型失败时自动回退到规则解析。~~
|
||||
- [x] ~~在结果中记录本次使用了 `llm_primary` 还是 `rule_fallback`。~~
|
||||
- [x] ~~报销关键词映射到 `expense`。~~
|
||||
- [x] ~~应收、回款、客户欠款映射到 `accounts_receivable`。~~
|
||||
- [x] ~~应付、供应商、付款映射到 `accounts_payable`。~~
|
||||
- [x] ~~风险、异常、重复、超标映射到 `risk_check`。~~
|
||||
- [x] ~~为什么、依据、规则映射到 `explain`。~~
|
||||
- [x] ~~统计、汇总、多少映射到 `query`。~~
|
||||
- [x] ~~生成、创建、发起映射到 `draft` 或 `operate`。~~
|
||||
- [x] ~~无法识别时返回低置信度和澄清问题。~~
|
||||
- [x] ~~叙述型报销输入优先识别为创建/草稿，而不是查询。~~
|
||||
|
||||
验收证据：
|
||||
|
||||
- [x] ~~“查一下本周报销超标风险”能识别为 expense + risk_check。~~
|
||||
- [x] ~~“客户 A 这个月还有多少应收”能识别为 accounts_receivable + query。~~
|
||||
- [x] ~~“供应商 B 明天要付多少钱”能识别为 accounts_payable + query。~~
|
||||
- [x] ~~“我今天去客户现场，招待了客户，花销了1000元”不会错误识别为应收查询。~~
|
||||
- [x] ~~“昨天请客户吃饭花了 200 元”会优先识别为报销草稿语义，并把“昨天”换算为用户本地日期下的绝对日期。~~
|
||||
|
||||
## 5. 解析业务对象
|
||||
|
||||
- [x] ~~从问题中提取员工姓名。~~
|
||||
- [x] ~~从问题中提取部门。~~
|
||||
- [x] ~~从问题中提取客户。~~
|
||||
- [x] ~~从问题中提取供应商。~~
|
||||
- [x] ~~从问题中提取项目。~~
|
||||
- [x] ~~从问题中提取单据号。~~
|
||||
- [x] ~~从问题中提取金额。~~
|
||||
- [x] ~~从问题中提取费用类型。~~
|
||||
- [x] ~~无法提取时返回空数组，不返回 null。~~
|
||||
|
||||
验收证据：
|
||||
|
||||
- [x] ~~“张三 4 月差旅报销”能提取员工、月份、费用类型。~~
|
||||
|
||||
## 6. 解析时间范围
|
||||
|
||||
- [x] ~~支持今天。~~
|
||||
- [x] ~~支持昨天。~~
|
||||
- [x] ~~支持本周。~~
|
||||
- [x] ~~支持上周。~~
|
||||
- [x] ~~支持本月。~~
|
||||
- [x] ~~支持上月。~~
|
||||
- [x] ~~支持本季度。~~
|
||||
- [x] ~~支持今年。~~
|
||||
- [x] ~~支持明确日期。~~
|
||||
- [x] ~~支持日期区间。~~
|
||||
- [x] ~~解析结果包含 `start_date` 和 `end_date`。~~
|
||||
- [x] ~~日期使用 ISO 格式。~~
|
||||
|
||||
验收证据：
|
||||
|
||||
- [x] ~~“本周”能解析为当前周起止日期。~~
|
||||
- [x] ~~“2026 年 4 月”能解析为 `2026-04-01` 到 `2026-04-30`。~~
|
||||
|
||||
## 7. 解析指标与约束
|
||||
|
||||
- [x] ~~识别金额指标。~~
|
||||
- [x] ~~识别数量指标。~~
|
||||
- [x] ~~识别超标指标。~~
|
||||
- [x] ~~识别逾期指标。~~
|
||||
- [x] ~~识别重复报销指标。~~
|
||||
- [x] ~~识别部门过滤条件。~~
|
||||
- [x] ~~识别状态过滤条件。~~
|
||||
- [x] ~~识别金额阈值过滤条件。~~
|
||||
- [x] ~~识别排序要求。~~
|
||||
- [x] ~~识别 Top N 要求。~~
|
||||
|
||||
验收证据：
|
||||
|
||||
- [x] ~~“列出金额最高的 10 笔报销”能识别排序和 Top 10。~~
|
||||
|
||||
## 8. 解析风险与权限
|
||||
|
||||
- [x] ~~重复报销映射到 `duplicate_expense`。~~
|
||||
- [x] ~~发票异常映射到 `invoice_anomaly`。~~
|
||||
- [x] ~~金额超标映射到 `amount_over_limit`。~~
|
||||
- [x] ~~逾期应收映射到 `ar_overdue`。~~
|
||||
- [x] ~~逾期应付映射到 `ap_overdue`。~~
|
||||
- [x] ~~查询类问题权限为 `read`。~~
|
||||
- [x] ~~生成草稿权限为 `draft_write`。~~
|
||||
- [x] ~~审批、上线、付款类动作权限为 `approval_required`。~~
|
||||
- [x] ~~越权动作权限为 `forbidden`。~~
|
||||
|
||||
验收证据：
|
||||
|
||||
- [x] ~~“帮我直接付款”不能被标为可直接执行。~~
|
||||
|
||||
## 9. API 接口
|
||||
|
||||
- [x] ~~新增 `POST /api/v1/ontology/parse`。~~
|
||||
- [x] ~~请求参数包含用户问题。~~
|
||||
- [x] ~~请求参数包含用户上下文。~~
|
||||
- [x] ~~响应包含 8 个字段。~~
|
||||
- [x] ~~响应包含 `run_id`。~~
|
||||
- [x] ~~响应包含置信度。~~
|
||||
- [x] ~~响应包含澄清问题。~~
|
||||
- [x] ~~每次调用写入 `SemanticParseLog`。~~
|
||||
- [x] ~~每次调用写入 `AgentRun` 或关联已有 `AgentRun`。~~
|
||||
|
||||
验收证据：
|
||||
|
||||
- [x] ~~连续调用多次都能在日志中查到。~~
|
||||
|
||||
## 10. 前端调试入口
|
||||
|
||||
- [x] ~~在合适页面增加语义解析调试入口。~~
|
||||
- [x] ~~输入框支持自然语言问题。~~
|
||||
- [x] ~~点击解析后调用 API。~~
|
||||
- [x] ~~展示 8 个字段。~~
|
||||
- [x] ~~展示 JSON 原始结果。~~
|
||||
- [x] ~~展示置信度。~~
|
||||
- [x] ~~展示澄清问题。~~
|
||||
- [x] ~~展示 `run_id`。~~
|
||||
- [x] ~~错误时展示错误信息。~~
|
||||
|
||||
验收证据：
|
||||
|
||||
- [x] ~~产品和开发可以直接在页面验证解析结果。~~
|
||||
|
||||
## 11. 评测集
|
||||
|
||||
- [x] ~~创建至少 5 条报销问题。~~
|
||||
- [ ] 创建至少 5 条叙述型报销问题。
|
||||
- [ ] 创建至少 3 条附件 / OCR 摘要带入的报销问题。
|
||||
- [x] ~~创建至少 5 条应收问题。~~
|
||||
- [x] ~~创建至少 5 条应付问题。~~
|
||||
- [x] ~~创建至少 3 条知识库问题。~~
|
||||
- [x] ~~创建至少 3 条越权操作问题。~~
|
||||
- [ ] 创建至少 3 条模糊短句追问问题。
|
||||
- [x] ~~为每条问题写期望 `scenario`。~~
|
||||
- [x] ~~为每条问题写期望 `intent`。~~
|
||||
- [x] ~~为每条问题写期望权限级别。~~
|
||||
- [x] ~~编写评测脚本或测试。~~
|
||||
|
||||
验收证据：
|
||||
|
||||
- [x] ~~当前评测样本集已通过，覆盖样本准确率达到当天设定阈值。~~
|
||||
|
||||
## 12. Day 3 验收
|
||||
|
||||
- [x] ~~语义解析 API 可用。~~
|
||||
- [x] ~~8 个核心字段完整返回。~~
|
||||
- [x] ~~解析日志可查询。~~
|
||||
- [x] ~~低置信度问题有澄清问题。~~
|
||||
- [x] ~~越权动作不会被标为可执行。~~
|
||||
- [x] ~~前端调试入口可用。~~
|
||||
- [x] ~~评测集可运行。~~
|
||||
- [x] ~~所有完成项已用 `[x] ~~...~~` 标记。~~
|
||||
|
||||
## 阻塞记录
|
||||
|
||||
- [x] ~~暂无。~~
|
||||
|
||||
## 日终交接
|
||||
|
||||
- [x] ~~已支持报销 / 应收 / 应付 / 知识 / 风险 / 草稿 / 越权动作等核心场景关键词、实体与权限解析。~~
|
||||
- [x] ~~语义层已可接收附件名称、附件数量和 OCR 摘要上下文，但这些样本仍需继续扩到评测集。~~
|
||||
- [x] ~~当前仍需继续扩充的弱样本主要是叙述型报销长句、附件/OCR 带入和模糊短句追问。~~
|
||||
- [x] ~~Day 4 可直接复用 `scenario / intent / entities / time_range / metrics / constraints / risk_flags / permission / confidence / missing_slots / ambiguity / parse_strategy / clarification_required / clarification_question / run_id`。~~
|
||||
@@ -1,254 +0,0 @@
|
||||
# Day 4：Orchestrator 运行时
|
||||
|
||||
## 今天的大开发点
|
||||
|
||||
建立统一调度层。用户请求和系统任务都先进入 Orchestrator，由它完成语义解析、权限判断、能力选择、Agent 路由、工具调用记录和失败降级。
|
||||
|
||||
## 为什么第四天做这个
|
||||
|
||||
没有 Orchestrator，User Agent 和 Hermes 会各自直接调用能力，权限、审计、降级、Trace 都会分散。生产系统必须有统一入口。
|
||||
|
||||
## 今天主要交付
|
||||
|
||||
- Orchestrator 请求和响应结构。
|
||||
- 用户请求路由到 User Agent。
|
||||
- 定时任务路由到 Hermes。
|
||||
- 权限级别判断。
|
||||
- 语义补槽完成后的报销草稿创建、草稿更新、提交动作路由。
|
||||
- 高风险动作确认机制。
|
||||
- 能力注册查询。
|
||||
- 工具调用封装。
|
||||
- AgentRun Trace 查询。
|
||||
- 失败降级返回。
|
||||
|
||||
## 当前完成情况
|
||||
|
||||
- [x] ~~`/api/v1/orchestrator/run`、统一路由、权限阻断、ToolCall 记录、Trace 和降级结果已经可用。~~
|
||||
- [x] ~~用户消息已能路由到 User Agent，占位 Hermes 任务也能由定时入口触发。~~
|
||||
- [x] ~~附件名称、页面上下文和 OCR 摘要已能随 Orchestrator 请求透传到语义层和 User Agent。~~
|
||||
- [x] ~~Orchestrator 已开始向前端返回结构化 `review_payload`，用于右侧预审面板展示识别意图、槽位、票据和分单建议。~~
|
||||
- [x] ~~`conversation_id`、会话消息历史和 `draft_claim_id` 已接入 Orchestrator，会话内追问可继续落到同一张报销草稿。~~
|
||||
- [x] ~~已新增最近会话恢复与用户级会话清空接口，个人工作台可显式继续旧会话或删除旧会话后新建。~~
|
||||
- [x] ~~`clarification_required` 的报销请求已改为返回结构化核对结果，而不是只回一句追问文案。~~
|
||||
- [x] ~~`review_action`、`review_form_values` 已能透传到 User Agent / 报销草稿服务，用于结构化修改后重识别和保存草稿。~~
|
||||
- [ ] 真实 `expense_claims` 提交链路尚未接通；草稿建单 / 改单已接到真实落库，附件与 OCR 持久化仍未完成。
|
||||
- [ ] 报销附件持久化服务、OCR 结果落库服务和前端 ToolCall 细粒度 Trace 展示尚未接通。
|
||||
|
||||
相关架构文档：
|
||||
|
||||
- [Orchestrator 与运行流程](<../agent plan/04_orchestrator_and_runtime_flow.md>)
|
||||
- [能力注册](<../agent plan/07_capability_registry.md>)
|
||||
- [权限与确认](<../agent plan/08_permission_confirmation.md>)
|
||||
- [观测与 Trace](<../agent plan/09_observability_and_trace.md>)
|
||||
|
||||
## 当天验收门槛
|
||||
|
||||
- Orchestrator API 可用。
|
||||
- 用户消息能路由到 User Agent 占位实现。
|
||||
- 定时任务能路由到 Hermes 占位实现。
|
||||
- forbidden 请求不会调用下游 Agent。
|
||||
- 每次运行都有 `run_id` 和 Trace。
|
||||
- 工具调用失败能记录并返回降级结果。
|
||||
- 叙述型报销输入在满足最小槽位后能进入建单或改单流程。
|
||||
|
||||
## 今天不做
|
||||
|
||||
- 不做复杂任务编排 DAG。
|
||||
- 不做多 Agent 协商。
|
||||
- 不做自动高风险动作。
|
||||
|
||||
## 详细执行清单
|
||||
|
||||
以下内容为合并后的详细执行清单。
|
||||
|
||||
## 0. 开始前检查
|
||||
|
||||
- [x] ~~确认 Day 3 `POST /api/v1/ontology/parse` 可用。~~
|
||||
- [x] ~~确认 `AgentRun` 可创建。~~
|
||||
- [x] ~~确认 `AgentToolCall` 可创建。~~
|
||||
- [x] ~~确认资产列表能查询技能、MCP、任务。~~
|
||||
- [x] ~~确认权限级别枚举已稳定。~~
|
||||
- [x] ~~找到后端服务层适合放 Orchestrator 的位置。~~
|
||||
|
||||
## 1. Orchestrator 输入输出
|
||||
|
||||
- [x] ~~定义 `OrchestratorRequest`。~~
|
||||
- [x] ~~请求包含 `source`。~~
|
||||
- [x] ~~请求包含 `user_id`。~~
|
||||
- [x] ~~请求包含 `message`。~~
|
||||
- [x] ~~请求包含 `task_id`。~~
|
||||
- [x] ~~请求包含 `context_json`。~~
|
||||
- [x] ~~定义 `OrchestratorResponse`。~~
|
||||
- [x] ~~响应包含 `run_id`。~~
|
||||
- [x] ~~响应包含 `selected_agent`。~~
|
||||
- [x] ~~响应包含 `route_reason`。~~
|
||||
- [x] ~~响应包含 `permission_level`。~~
|
||||
- [x] ~~响应包含 `status`。~~
|
||||
- [x] ~~响应包含 `result`。~~
|
||||
- [x] ~~响应包含 `requires_confirmation`。~~
|
||||
- [x] ~~响应包含 `trace_summary`。~~
|
||||
|
||||
验收证据：
|
||||
|
||||
- [x] ~~Orchestrator 响应能直接被前端展示。~~
|
||||
|
||||
## 2. 建立 Orchestrator 服务
|
||||
|
||||
- [x] ~~新增 `OrchestratorService`。~~
|
||||
- [x] ~~实现 `run(request)` 主入口。~~
|
||||
- [x] ~~主入口第一步创建 `AgentRun`。~~
|
||||
- [x] ~~主入口第二步调用语义解析。~~
|
||||
- [x] ~~主入口第三步执行权限判断。~~
|
||||
- [x] ~~主入口第四步选择 Agent。~~
|
||||
- [x] ~~主入口第五步调用目标 Agent 或返回阻断结果。~~
|
||||
- [x] ~~主入口第六步更新 `AgentRun` 状态。~~
|
||||
- [x] ~~所有异常都写入 `AgentRun.error_message`。~~
|
||||
|
||||
验收证据：
|
||||
|
||||
- [x] ~~正常请求状态为 `succeeded`。~~
|
||||
- [x] ~~被权限拦截请求状态为 `blocked`。~~
|
||||
- [x] ~~异常请求状态为 `failed`。~~
|
||||
|
||||
## 3. 路由规则
|
||||
|
||||
- [x] ~~`source=user_message` 默认路由到 User Agent。~~
|
||||
- [x] ~~`source=schedule` 默认路由到 Hermes。~~
|
||||
- [x] ~~`intent=risk_check` 且来源为 schedule 时路由到 Hermes。~~
|
||||
- [x] ~~`intent=query` 且来源为 user_message 时路由到 User Agent。~~
|
||||
- [x] ~~`intent=explain` 路由到 User Agent。~~
|
||||
- [x] ~~`intent=draft` 路由到 User Agent，并可返回结构化核对结果、草稿结果或草稿更新结果。~~
|
||||
- [x] ~~`scenario=expense` 且最小建单槽位完整时，允许进入 `create_expense_claim_draft`。~~
|
||||
- [x] ~~`scenario=expense` 且已有 `claim_id` 或会话内 `draft_claim_id` 时，允许进入 `update_expense_claim_draft`。~~
|
||||
- [ ] `scenario=expense` 且用户明确确认提交时，允许进入 `submit_expense_claim`。
|
||||
- [x] ~~`permission.level=approval_required` 时设置 `requires_confirmation=true`。~~
|
||||
- [x] ~~`permission.level=forbidden` 时不调用下游 Agent。~~
|
||||
- [x] ~~无法识别或信息不足时返回澄清问题。~~
|
||||
|
||||
验收证据：
|
||||
|
||||
- [x] ~~同一句风险检查，在用户入口和任务入口有不同路由结果。~~
|
||||
|
||||
## 4. 权限判断
|
||||
|
||||
- [x] ~~新增权限判断服务或函数。~~
|
||||
- [x] ~~查询类请求返回 `read`。~~
|
||||
- [x] ~~草稿类请求返回 `draft_write`。~~
|
||||
- [ ] 报销草稿字段补全、附件挂接返回 `draft_write`。
|
||||
- [ ] 报销单提交返回 `approval_required`，并要求显式用户确认。
|
||||
- [ ] 审批、上线、付款类请求返回 `approval_required`。
|
||||
- [x] ~~用户无权限时返回 `forbidden`。~~
|
||||
- [x] ~~高风险动作不允许自动执行。~~
|
||||
- [x] ~~需要确认的动作返回确认提示。~~
|
||||
- [x] ~~权限判断结果写入 `AgentRun.permission_level`。~~
|
||||
|
||||
验收证据：
|
||||
|
||||
- [x] ~~“直接上线规则”不会被自动执行。~~
|
||||
- [x] ~~“直接付款”不会被自动执行。~~
|
||||
|
||||
## 5. 能力注册查询
|
||||
|
||||
- [x] ~~从 `AgentAsset` 查询 active 技能。~~
|
||||
- [x] ~~从 `AgentAsset` 查询 active MCP。~~
|
||||
- [x] ~~从 `AgentAsset` 查询 active 任务。~~
|
||||
- [ ] 查询可用的报销单写入服务和附件挂接服务。
|
||||
- [ ] 查询可用的 OCR 结果持久化服务和票据文件回溯服务。
|
||||
- [x] ~~过滤 disabled 能力。~~
|
||||
- [x] ~~过滤未审核 active 条件不满足的规则。~~
|
||||
- [x] ~~为每次能力选择记录 `route_json`。~~
|
||||
- [x] ~~找不到能力时返回降级说明。~~
|
||||
|
||||
验收证据：
|
||||
|
||||
- [x] ~~禁用 MCP 不会被 Orchestrator 调用。~~
|
||||
|
||||
## 6. 工具调用封装
|
||||
|
||||
- [x] ~~定义统一工具调用接口。~~
|
||||
- [ ] 工具请求前写入 `AgentToolCall` running 或准备记录。
|
||||
- [x] ~~工具成功后写入响应和耗时。~~
|
||||
- [x] ~~工具失败后写入错误。~~
|
||||
- [ ] 报销草稿更新、提交也按工具调用或等价服务调用记录。
|
||||
- [x] ~~报销草稿创建按工具调用或等价服务调用记录。~~
|
||||
- [ ] 附件挂接、OCR 结果落库、票据回溯查询也按工具调用或等价服务调用记录。
|
||||
- [x] ~~外部 MCP 调用失败时返回降级结果。~~
|
||||
- [x] ~~数据库查询失败时返回明确错误。~~
|
||||
- [x] ~~LLM 调用失败时返回可读提示。~~
|
||||
|
||||
验收证据：
|
||||
|
||||
- [x] ~~每次 Orchestrator 运行至少可以看到 0 到多条工具调用记录。~~
|
||||
|
||||
## 7. API 接口
|
||||
|
||||
- [x] ~~新增 `POST /api/v1/orchestrator/run`。~~
|
||||
- [x] ~~请求支持用户消息。~~
|
||||
- [x] ~~请求支持任务触发。~~
|
||||
- [x] ~~响应返回 `run_id`。~~
|
||||
- [x] ~~响应返回路由结果。~~
|
||||
- [x] ~~响应返回权限结果。~~
|
||||
- [x] ~~复用 `GET /api/v1/agent-runs/{run_id}` 查看 Trace。~~
|
||||
- [x] ~~Trace 接口返回语义解析、路由、工具调用、最终结果。~~
|
||||
- [x] ~~`POST /api/v1/orchestrator/run` 返回的 `result` 已可携带 `review_payload`。~~
|
||||
|
||||
验收证据：
|
||||
|
||||
- [x] ~~前端或 curl 可以完整看到一次运行链路。~~
|
||||
|
||||
## 8. 前端最小 Trace 查看
|
||||
|
||||
- [ ] 在合适位置展示最近运行记录。
|
||||
- [x] ~~点击当前对话结果可查看 `run_id`。~~
|
||||
- [x] ~~展示 selected_agent。~~
|
||||
- [x] ~~展示 route_reason。~~
|
||||
- [x] ~~展示 permission_level。~~
|
||||
- [ ] 展示工具调用列表。
|
||||
- [x] ~~展示错误信息。~~
|
||||
- [ ] 展示耗时。
|
||||
- [ ] 展示报销写链路中的 claim_id / claim_no / status 变化。
|
||||
|
||||
验收证据：
|
||||
|
||||
- [x] ~~开发调试时不需要直接查数据库才能理解主要路由结果。~~
|
||||
|
||||
## 9. 测试
|
||||
|
||||
- [x] ~~测试用户查询路由到 User Agent。~~
|
||||
- [x] ~~测试定时任务路由到 Hermes。~~
|
||||
- [x] ~~测试叙述型报销输入可路由到报销建单服务。~~
|
||||
- [x] ~~测试同一 `conversation_id` 下的追问会继续更新已有报销草稿。~~
|
||||
- [ ] 测试报销单提交前必须显式确认。
|
||||
- [x] ~~测试 forbidden 不调用下游 Agent。~~
|
||||
- [x] ~~测试 approval_required 返回确认。~~
|
||||
- [x] ~~测试工具失败写入 ToolCall。~~
|
||||
- [x] ~~测试 Orchestrator 异常写入 AgentRun。~~
|
||||
|
||||
验收证据：
|
||||
|
||||
- [x] ~~Orchestrator 核心测试通过。~~
|
||||
|
||||
## 10. Day 4 验收
|
||||
|
||||
- [x] ~~Orchestrator API 可用。~~
|
||||
- [x] ~~用户请求能路由到 User Agent 占位实现。~~
|
||||
- [x] ~~定时任务能路由到 Hermes 占位实现。~~
|
||||
- [x] ~~语义补槽完成后的报销输入能路由到建单动作。~~
|
||||
- [x] ~~语义补槽完成后的报销输入能路由到改单动作。~~
|
||||
- [x] ~~权限阻断有效。~~
|
||||
- [x] ~~运行 Trace 可查询。~~
|
||||
- [x] ~~工具调用日志可查询。~~
|
||||
- [x] ~~降级结果可读。~~
|
||||
- [x] ~~所有完成项已用 `[x] ~~...~~` 标记。~~
|
||||
|
||||
## 阻塞记录
|
||||
|
||||
- [x] ~~暂无。~~
|
||||
|
||||
## 日终交接
|
||||
|
||||
- [x] ~~当前路由规则已稳定为：`user_message -> user_agent`、`schedule -> hermes`、`clarification_required -> blocked`。~~
|
||||
- [x] ~~当前权限判断已稳定为：`read / draft_write / approval_required / forbidden`，高风险动作默认阻断或要求确认。~~
|
||||
- [x] ~~Day 5 需承接的接口契约已明确：Orchestrator 向 User Agent 传入语义结果、能力码、工具结果，并期待返回 `answer / citations / suggested_actions / draft_payload / risk_flags`。~~
|
||||
- [x] ~~Day 5 当前已扩展接口契约：除 `answer / citations / suggested_actions / draft_payload / risk_flags` 外，还返回 `review_payload` 用于前端预审工作台。~~
|
||||
- [x] ~~下一步仍需补齐的运行时写链路是：附件持久化、OCR 结果落库和提交状态流转。~~
|
||||
@@ -1,284 +0,0 @@
|
||||
# Day 5：User Agent MVP
|
||||
|
||||
## 今天的大开发点
|
||||
|
||||
实现面向用户的自建 Agent。它负责用户提问、流程辅助、规则解释、查询结果解释和草稿生成。
|
||||
|
||||
User Agent 只能处理用户侧交互，不负责后台定时内循环，也不能自动执行高风险动作。
|
||||
|
||||
## 为什么第五天做这个
|
||||
|
||||
Day 1 到 Day 4 已经具备资产、语义、路由和日志基础，此时可以把用户自然语言入口接到真实流程上。
|
||||
|
||||
## 今天主要交付
|
||||
|
||||
- 用户自然语言入口。
|
||||
- 对话入口透传首句文本、附件名称和页面上下文。
|
||||
- 语义识别完整后创建报销单草稿。
|
||||
- 对话补充字段时更新报销主表、明细和附件关联。
|
||||
- 用户确认后触发报销单提交和状态变更。
|
||||
- 报销查询和解释。
|
||||
- 应收查询和解释。
|
||||
- 应付查询和解释。
|
||||
- 规则引用解释。
|
||||
- 风险原因说明。
|
||||
- 处理意见草稿。
|
||||
- 知识库读取骨架。
|
||||
- 低置信度场景的澄清追问。
|
||||
- 前端问答或操作入口。
|
||||
|
||||
## 当前完成情况
|
||||
|
||||
- [x] ~~个人工作台、报销对话框和通用聊天入口已经接通真实 Orchestrator / User Agent 问答链路。~~
|
||||
- [x] ~~回答、规则引用、风险说明、建议动作和结构化 `draft_payload` 已可返回。~~
|
||||
- [x] ~~报销对话框已接入 OCR 识别接口，附件名称、OCR 摘要和页面上下文已能透传到 Orchestrator / User Agent。~~
|
||||
- [x] ~~右侧工作台已开始展示结构化 `review_payload`，并已收敛为“识别结果专用区”：核心识别摘要、时间换算说明、逐票据识别结果、可能单据类型、建议归属费用和 OCR 置信度。~~
|
||||
- [x] ~~个人工作台和报销对话框已接入 `conversation_id` / `draft_claim_id`，同一会话内的连续追问不再按全新请求处理。~~
|
||||
- [x] ~~个人工作台已支持“继续会话 / 新建会话”，并可恢复最近一次用户会话或清空旧会话后重新开始。~~
|
||||
- [x] ~~报销核对流已切到产品化交互：正文区负责 AI 式核对提示、待补充信息、风险提醒和底部动作区，右侧只承载识别结果与票据识别明细，动作固定为“取消 / 修改识别信息 / 保存草稿或下一步”。~~
|
||||
- [ ] 真实 `document_assets` / `document_asset_versions` / `expense_item_documents` / `document_ocr_results` 落库，以及 `draft -> submitted` 状态流转尚未完成；`expense_claims` / `expense_claim_items` 草稿已接通真实落库。
|
||||
|
||||
相关架构文档：
|
||||
|
||||
- [Agent 职责边界](<../agent plan/03_agent_responsibilities.md>)
|
||||
- [Orchestrator 与运行流程](<../agent plan/04_orchestrator_and_runtime_flow.md>)
|
||||
- [LLM Wiki 知识库架构](<../agent plan/12_llm_wiki_knowledge_architecture.md>)
|
||||
- [规则形成生命周期](<../agent plan/13_rule_formation_lifecycle.md>)
|
||||
|
||||
## 当天验收门槛
|
||||
|
||||
- 用户能输入自然语言问题。
|
||||
- 请求必须经过 Orchestrator。
|
||||
- 至少 3 类财务问题有可读回答。
|
||||
- 叙述型报销输入在最小槽位满足后能创建 `expense_claims` 草稿。
|
||||
- 用户确认提交后可把报销单从 `draft` 变更为 `submitted`。
|
||||
- 回答能引用规则或知识。
|
||||
- 语义低置信度时不会答非所问，而是追问。
|
||||
- 高风险动作只生成草稿或建议。
|
||||
- AgentRun Trace 能看到 User Agent 步骤。
|
||||
|
||||
## 今天不做
|
||||
|
||||
- 不做自动审批。
|
||||
- 不做自动付款。
|
||||
- 不做自动上线规则。
|
||||
- 不做完整知识库检索优化。
|
||||
- 不假装已读懂未解析的附件内容。
|
||||
|
||||
## 详细执行清单
|
||||
|
||||
以下内容为合并后的详细执行清单。
|
||||
|
||||
## 0. 开始前检查
|
||||
|
||||
- [x] ~~确认 Orchestrator 能把用户请求路由到 User Agent。~~
|
||||
- [x] ~~确认语义本体 8 字段可用。~~
|
||||
- [x] ~~确认语义层已接入真实模型，而不是仅靠关键词规则。~~
|
||||
- [x] ~~确认规则资产可查询。~~
|
||||
- [x] ~~确认 AgentRun 和 ToolCall 可记录。~~
|
||||
- [x] ~~确认已有现成对话 UI 可复用。~~
|
||||
- [x] ~~确认财务业务数据已可通过最小真实数据查询。~~
|
||||
- [x] ~~当前无需额外补最小 Mock 数据服务。~~
|
||||
|
||||
## 1. User Agent 输入输出
|
||||
|
||||
- [x] ~~定义 `UserAgentRequest`。~~
|
||||
- [x] ~~请求包含 `run_id`。~~
|
||||
- [x] ~~请求包含 `user_id`。~~
|
||||
- [x] ~~请求包含 `message`。~~
|
||||
- [x] ~~请求包含 `ontology`。~~
|
||||
- [x] ~~请求包含 `context_json`。~~
|
||||
- [x] ~~定义 `UserAgentResponse`。~~
|
||||
- [x] ~~响应包含 `answer`。~~
|
||||
- [x] ~~响应包含 `citations`。~~
|
||||
- [x] ~~响应包含 `suggested_actions`。~~
|
||||
- [x] ~~响应包含 `draft_payload`。~~
|
||||
- [x] ~~响应包含 `risk_flags`。~~
|
||||
- [x] ~~响应包含 `requires_confirmation`。~~
|
||||
|
||||
验收证据：
|
||||
|
||||
- [x] ~~User Agent 响应结构能被 Orchestrator 直接包装返回。~~
|
||||
|
||||
## 2. 查询处理
|
||||
|
||||
- [x] ~~实现报销查询处理器。~~
|
||||
- [x] ~~实现应收查询处理器。~~
|
||||
- [x] ~~实现应付查询处理器。~~
|
||||
- [ ] 查询前检查权限级别。
|
||||
- [x] ~~查询时记录 ToolCall。~~
|
||||
- [x] ~~查询失败时返回可读错误。~~
|
||||
- [x] ~~查询为空时返回空态解释。~~
|
||||
- [ ] 查询结果限制返回条数，避免一次返回过大。
|
||||
|
||||
验收证据：
|
||||
|
||||
- [x] ~~“查本周报销金额”有可读回答。~~
|
||||
- [x] ~~“客户 A 本月应收多少”有可读回答。~~
|
||||
- [x] ~~“供应商 B 待付款多少”有可读回答。~~
|
||||
|
||||
## 3. 规则解释
|
||||
|
||||
- [x] ~~根据语义场景查询相关规则资产。~~
|
||||
- [x] ~~只引用 active 规则。~~
|
||||
- [x] ~~读取规则当前版本 Markdown。~~
|
||||
- [x] ~~从 Markdown 中提取规则摘要。~~
|
||||
- [x] ~~回答中说明使用了哪些规则。~~
|
||||
- [x] ~~回答中包含规则版本号。~~
|
||||
- [x] ~~回答中包含规则更新时间。~~
|
||||
- [x] ~~没有相关规则时说明缺失。~~
|
||||
|
||||
验收证据：
|
||||
|
||||
- [x] ~~“为什么这笔报销有风险”能引用规则。~~
|
||||
|
||||
## 4. 风险解释
|
||||
|
||||
- [x] ~~识别重复报销风险。~~
|
||||
- [x] ~~识别金额超标风险。~~
|
||||
- [x] ~~识别发票异常风险。~~
|
||||
- [x] ~~识别逾期应收风险。~~
|
||||
- [x] ~~识别逾期应付风险。~~
|
||||
- [x] ~~风险回答包含风险类型。~~
|
||||
- [x] ~~风险回答包含触发原因。~~
|
||||
- [x] ~~风险回答包含建议处理动作。~~
|
||||
- [x] ~~高风险建议不能变成自动执行。~~
|
||||
|
||||
验收证据：
|
||||
|
||||
- [x] ~~风险解释结果不是单纯“有风险”，而是有依据。~~
|
||||
|
||||
## 5. 草稿生成与单据落库
|
||||
|
||||
- [x] ~~支持根据语义结果创建 `expense_claims` 草稿。~~
|
||||
- [x] ~~报销草稿初始状态写为 `draft`。~~
|
||||
- [x] ~~支持根据语义结果创建或更新 `expense_claim_items`。~~
|
||||
- [ ] 支持把用户上传附件挂到 `document_assets`、`document_asset_versions`、`expense_item_documents`。
|
||||
- [ ] 支持把 OCR 识别快照写入 `document_ocr_results`，并保留 `ocr_engine`、`ocr_model`、`raw_json`、`confidence`。
|
||||
- [x] ~~对话中补充金额、发生时间、费用类型等已落地字段后，能回写已有草稿而不是只更新内存结果。~~
|
||||
- [x] ~~支持生成报销处理意见草稿。~~
|
||||
- [x] ~~支持生成应收催收建议草稿。~~
|
||||
- [x] ~~支持生成应付付款建议草稿。~~
|
||||
- [ ] 用户明确确认“提交报销”后，把 `expense_claims.status` 从 `draft` 更新为 `submitted`。
|
||||
- [ ] 报销提交时写入 `submitted_at`。
|
||||
- [ ] 报销状态变更写入审计日志。
|
||||
- [ ] 报销状态变更写入 AgentRun 结果。
|
||||
- [x] ~~草稿中标明“待人工确认”。~~
|
||||
- [x] ~~草稿不直接提交业务系统。~~
|
||||
- [x] ~~草稿生成写入审计日志。~~
|
||||
- [x] ~~草稿生成写入 AgentRun 结果。~~
|
||||
- [ ] 草稿创建或更新后向前端返回 `attachment_ids`。
|
||||
- [x] ~~草稿创建或更新后向前端返回 `claim_id`、`claim_no`、`status`。~~
|
||||
|
||||
验收证据：
|
||||
|
||||
- [ ] “我今天去客户现场，招待了客户，花销了1000元”在补齐必要字段后可创建报销草稿。
|
||||
- [ ] “帮我提交这笔报销”在确认后只把状态改到 `submitted`，不会直接改成 `approved` 或 `paid`。
|
||||
- [x] ~~“帮我生成处理意见”只返回草稿，不执行审批。~~
|
||||
|
||||
## 6. 知识库读取骨架
|
||||
|
||||
- [ ] 建立知识条目查询接口或服务。
|
||||
- [ ] 支持按关键词查询知识条目。
|
||||
- [ ] 支持按业务场景查询知识条目。
|
||||
- [ ] User Agent 回答可以引用知识条目。
|
||||
- [ ] 引用中包含知识标题。
|
||||
- [ ] 引用中包含更新时间。
|
||||
- [ ] 知识库不可用时返回降级说明。
|
||||
|
||||
验收证据：
|
||||
|
||||
- [ ] 知识库失败不会导致整个回答失败。
|
||||
|
||||
## 7. 对话或操作入口
|
||||
|
||||
- [x] ~~前端增加用户问题输入框。~~
|
||||
- [x] ~~输入框支持回车或按钮提交。~~
|
||||
- [x] ~~提交时调用 Orchestrator，而不是绕过 Orchestrator。~~
|
||||
- [x] ~~提交时透传首句文本。~~
|
||||
- [x] ~~提交时透传附件名称。~~
|
||||
- [x] ~~提交时透传 OCR 摘要。~~
|
||||
- [x] ~~提交时透传页面上下文。~~
|
||||
- [x] ~~提交时透传 `conversation_id` 与 `draft_claim_id`。~~
|
||||
- [ ] 提交时透传附件 ID。
|
||||
- [x] ~~展示 Agent 回答。~~
|
||||
- [x] ~~展示引用规则或知识。~~
|
||||
- [x] ~~展示建议动作。~~
|
||||
- [x] ~~展示识别意图摘要、待确认字段和确认动作卡片。~~
|
||||
- [x] ~~正文区改为简洁核对提示，不再堆叠调度结果或运行明细。~~
|
||||
- [x] ~~正文区待补充信息和风险提示已改为紧凑高亮样式，避免出现大段冗长说明。~~
|
||||
- [x] ~~展示逐票据 OCR 识别结果，并支持按 1、2、3… 顺序查看。~~
|
||||
- [x] ~~右侧逐票据结果已补充“可能单据类型 / 建议归属费用 / 识别置信度”等识别信息。~~
|
||||
- [x] ~~展示多场景票据的分单建议。~~
|
||||
- [ ] 展示报销草稿 ID 或 claim_no。
|
||||
- [ ] 展示当前报销状态。
|
||||
- [x] ~~展示需要人工确认的提示。~~
|
||||
- [x] ~~展示 `run_id`。~~
|
||||
- [x] ~~展示加载态。~~
|
||||
- [x] ~~展示错误态。~~
|
||||
|
||||
验收证据：
|
||||
|
||||
- [x] ~~用户可在页面完成一次问答闭环。~~
|
||||
|
||||
## 8. 安全边界
|
||||
|
||||
- [x] ~~User Agent 不直接修改规则状态。~~
|
||||
- [x] ~~User Agent 不直接上线规则。~~
|
||||
- [x] ~~User Agent 不直接审批报销。~~
|
||||
- [x] ~~User Agent 不直接把报销单改为 `approved` 或 `paid`。~~
|
||||
- [x] ~~User Agent 不直接付款。~~
|
||||
- [x] ~~User Agent 不直接删除知识。~~
|
||||
- [x] ~~所有高风险动作只返回建议或草稿。~~
|
||||
- [ ] 报销从 `draft` 变更到 `submitted` 之前必须有用户确认。
|
||||
- [ ] 所有草稿动作标记 `requires_confirmation=true`。
|
||||
- [x] ~~语义低置信度时优先追问，不返回答非所问的查询结果。~~
|
||||
- [x] ~~没有 OCR/VLM 结果时，不假装读懂图片或票据内容。~~
|
||||
|
||||
验收证据：
|
||||
|
||||
- [x] ~~提示词要求“直接付款”时仍被阻断。~~
|
||||
|
||||
## 9. 测试
|
||||
|
||||
- [x] ~~测试报销查询。~~
|
||||
- [x] ~~测试应收查询。~~
|
||||
- [ ] 测试应付查询。
|
||||
- [ ] 测试规则解释。
|
||||
- [x] ~~测试风险解释。~~
|
||||
- [ ] 测试 OCR 摘要透传后，User Agent 能在回答中正确引用附件语境而不编造内容。
|
||||
- [x] ~~测试报销草稿创建。~~
|
||||
- [x] ~~测试报销草稿补槽更新。~~
|
||||
- [ ] 测试报销状态从 `draft` 变更到 `submitted`。
|
||||
- [x] ~~测试草稿生成。~~
|
||||
- [ ] 测试越权动作阻断。
|
||||
- [ ] 测试知识库降级。
|
||||
|
||||
验收证据：
|
||||
|
||||
- [x] ~~User Agent 核心测试通过。~~
|
||||
|
||||
## 10. Day 5 验收
|
||||
|
||||
- [x] ~~User Agent 服务可被 Orchestrator 调用。~~
|
||||
- [x] ~~用户入口可提交自然语言问题。~~
|
||||
- [x] ~~至少 3 个财务场景有回答。~~
|
||||
- [x] ~~语义识别完整后的报销输入能创建报销草稿。~~
|
||||
- [ ] 用户确认后能提交报销并更新状态。
|
||||
- [x] ~~回答能引用规则或知识。~~
|
||||
- [x] ~~高风险动作不会自动执行。~~
|
||||
- [x] ~~AgentRun Trace 能看到 User Agent 步骤。~~
|
||||
- [x] ~~前端构建通过。~~
|
||||
- [x] ~~所有完成项已用 `[x] ~~...~~` 标记。~~
|
||||
|
||||
## 阻塞记录
|
||||
|
||||
- [x] ~~暂无。~~
|
||||
|
||||
## 日终交接
|
||||
|
||||
- [x] ~~当前已支持报销 / 应收 / 应付查询、规则解释、风险解释、草稿建议与澄清追问。~~
|
||||
- [x] ~~当前已支持附件名称、OCR 摘要和页面上下文进入对话链路，但这还不是附件真实持久化。~~
|
||||
- [x] ~~当前已把用户一句话和多票据输入转成结构化预审面板，开始支持字段确认、票据核对和分单建议，而不再只是返回一段文本。~~
|
||||
- [x] ~~当前仍是占位的主要能力是报销单真实落库、附件持久化、OCR 结果入表和知识库读取，不再是简单静态问答 Mock。~~
|
||||
- [x] ~~Day 6 Hermes 可直接复用当前的规则检查、风险标签和 Orchestrator Trace / ToolCall 契约。~~
|
||||
@@ -1,343 +0,0 @@
|
||||
# Day 6：Hermes MVP
|
||||
|
||||
## 今天的大开发点
|
||||
|
||||
实现 Hermes 数字员工的最小闭环。Hermes 负责后台内循环：定时巡检、统计日报、风险预警、知识维护、规则草稿形成。
|
||||
|
||||
## 为什么第六天做这个
|
||||
|
||||
Hermes 依赖前几天已经建立的资产、规则、语义、Orchestrator、Trace 和权限体系。放在第六天做，可以避免它变成孤立脚本。
|
||||
|
||||
## 今天主要交付
|
||||
|
||||
- 任务资产调度入口。
|
||||
- 手动触发任务 API。
|
||||
- 系统 Hermes 后台执行入口。
|
||||
- 每日风险巡检。
|
||||
- 每日报销、报账、账款统计。
|
||||
- OCR Mock 接入点。
|
||||
- 知识候选条目生成。
|
||||
- 规则草稿生成。
|
||||
- LLM Wiki 解析目录与增量重建机制。
|
||||
- Hermes 运行结果展示。
|
||||
|
||||
相关架构文档：
|
||||
|
||||
- [Agent 职责边界](<../agent plan/03_agent_responsibilities.md>)
|
||||
- [OCR 票据识别架构](<../agent plan/11_ocr_invoice_architecture.md>)
|
||||
- [LLM Wiki 知识库架构](<../agent plan/12_llm_wiki_knowledge_architecture.md>)
|
||||
- [反馈学习闭环](<../agent plan/15_feedback_learning_loop.md>)
|
||||
|
||||
## 当天验收门槛
|
||||
|
||||
- 至少一个 Hermes 任务可以手动触发。
|
||||
- 风险巡检有结构化结果。
|
||||
- 每日统计有结构化结果。
|
||||
- OCR Mock 调用能记录 ToolCall。
|
||||
- 知识候选只能是草稿。
|
||||
- 规则草稿只能是 draft，不能自动上线。
|
||||
|
||||
## 今天不做
|
||||
|
||||
- 不做完整生产调度集群。
|
||||
- 不做真实 OCR 深度集成。
|
||||
- 不做自动发布知识。
|
||||
- 不做自动上线规则。
|
||||
- 不做每天无差别全量重建 LLM Wiki。
|
||||
|
||||
## 本次新增约束
|
||||
|
||||
### 1. Hermes 必须是系统后台 Hermes
|
||||
|
||||
这次 Hermes 不应继续只是代码里的占位逻辑。
|
||||
|
||||
最小可接受形态：
|
||||
|
||||
- 后端任务入口能明确区分 `selected_agent=hermes`。
|
||||
- 后端可调用系统安装的 Hermes CLI 或受控 Hermes 进程。
|
||||
- 即使当前阶段仍允许 Python 内部 fallback，也必须保留真实 Hermes 进程接入点。
|
||||
- Hermes 的模型配置继续由系统设置同步，不允许在任务代码里再写一套模型配置。
|
||||
- Hermes 执行应记录 `run_id`、ToolCall、错误信息和最终摘要。
|
||||
|
||||
### 2. LLM Wiki 必须有独立解析目录
|
||||
|
||||
原始知识文件与解析产物必须分离。
|
||||
|
||||
推荐目录：
|
||||
|
||||
```text
|
||||
/app/server/storage/knowledge/报销制度 原始制度文件
|
||||
/app/server/storage/knowledge/.llm_wiki 解析产物根目录
|
||||
/app/server/storage/knowledge/.llm_wiki/documents/<document_id>/
|
||||
document.json
|
||||
text.md
|
||||
chunks.json
|
||||
clauses.json
|
||||
knowledge_candidates.json
|
||||
rule_candidates.json
|
||||
/app/server/storage/knowledge/.llm_wiki/index.json
|
||||
/app/server/storage/knowledge/.llm_wiki/sync_runs.json
|
||||
```
|
||||
|
||||
### 3. LLM Wiki 只能增量形成
|
||||
|
||||
不允许每天无脑全量重建。
|
||||
|
||||
文档级重建触发条件至少包括：
|
||||
|
||||
- 文件名 `original_name` 变更。
|
||||
- 文件对象 `stored_name` 变更。
|
||||
- 内容摘要 `sha256` 变更。
|
||||
- 上传版本 `version_number` 变更。
|
||||
- 更新时间 `updated_at` 变更，视为人工改动。
|
||||
|
||||
如果以上条件都未变化：
|
||||
|
||||
- 本次文档应标记为 `unchanged_skipped`。
|
||||
- 不重新抽取文本。
|
||||
- 不重新生成知识候选。
|
||||
- 不重新生成规则草稿。
|
||||
|
||||
### 4. 规则草稿必须模板化
|
||||
|
||||
Hermes 不允许自由生成任意结构的规则。
|
||||
|
||||
必须满足：
|
||||
|
||||
- 规则 Markdown 使用固定模板。
|
||||
- 可执行规则 JSON 使用固定模板族，不允许随意拼字段。
|
||||
- 规则中心要同时展示人类可读的 Markdown 和机器可执行的 JSON。
|
||||
- Hermes 生成的规则默认 `draft`。
|
||||
- 审核通过前不能 `active`。
|
||||
- Hermes 不能直接覆盖线上 active 规则。
|
||||
|
||||
## 详细执行清单
|
||||
|
||||
以下内容为合并后的详细执行清单。
|
||||
|
||||
## 本轮追加范围（2026-05-15）
|
||||
|
||||
本轮不扩散到新的业务能力，先把已经落地的 LLM Wiki 归纳链路收紧成可运维、可追踪、可持续运行的形态。
|
||||
|
||||
本轮目标：
|
||||
|
||||
- 把知识管理中的 Hermes 归纳从同步请求改成后台异步任务。
|
||||
- 用户关闭或切走页面后，归纳任务仍继续执行，不因前端页面生命周期被误判失败。
|
||||
- 归纳过程中的状态、进度、摘要、异常统一写入 `AgentRun.route_json` 与 `result_summary`。
|
||||
- 知识管理页轮询真实任务状态，任务完成后立刻把文档状态从“正归纳”切到最终状态。
|
||||
- 右侧侧边栏新增“日志管理”入口。
|
||||
- 日志管理页拆成两类日志：
|
||||
- Hermes 调用日志：查看归纳任务运行状态、当前阶段、文档进度、ToolCall、错误信息。
|
||||
- 系统运行日志：直接查看 `server/logs` 下的系统日志文本。
|
||||
|
||||
本轮边界：
|
||||
|
||||
- 仍然使用系统 Hermes CLI 入口，不虚构不存在的 gateway 推理接口。
|
||||
- 不引入完整消息队列或 Celery 集群，先用后端受控后台任务管理器落地。
|
||||
- 不把日志页做成审计替代品，重点只覆盖 Hermes 运行日志和系统运行日志。
|
||||
- 不把普通用户开放为日志管理员，日志查看仍属于管理员能力。
|
||||
|
||||
## 0. 开始前检查
|
||||
|
||||
- [x] ~~确认任务资产 `asset_type=task` 可查询。~~
|
||||
- [x] ~~确认 Orchestrator 能处理 `source=schedule`。~~
|
||||
- [x] ~~确认系统 Hermes CLI 或等价后台 Hermes 进程可被调用。~~
|
||||
- [x] ~~确认 AgentRun 和 ToolCall 可记录。~~
|
||||
- [x] ~~确认是否已有后台任务框架。~~
|
||||
- [ ] 如果没有后台任务框架，先用手动触发 API 模拟定时执行。
|
||||
|
||||
## 1. Hermes 输入输出
|
||||
|
||||
- [ ] 定义 `HermesTaskRequest`。
|
||||
- [ ] 请求包含 `run_id`。
|
||||
- [ ] 请求包含 `task_asset_id`。
|
||||
- [ ] 请求包含 `task_type`。
|
||||
- [ ] 请求包含 `schedule_time`。
|
||||
- [ ] 请求包含 `context_json`。
|
||||
- [ ] 定义 `HermesTaskResult`。
|
||||
- [ ] 响应包含 `summary`。
|
||||
- [ ] 响应包含 `risk_items`。
|
||||
- [ ] 响应包含 `statistics`。
|
||||
- [ ] 响应包含 `knowledge_updates`。
|
||||
- [ ] 响应包含 `draft_rules`。
|
||||
- [ ] 响应包含 `next_actions`。
|
||||
|
||||
验收证据：
|
||||
|
||||
- [ ] Hermes 响应能被任务详情或运行日志展示。
|
||||
|
||||
## 2. 任务调度入口
|
||||
|
||||
- [x] ~~新增手动触发任务 API。~~
|
||||
- [x] ~~API 参数支持任务资产 ID。~~
|
||||
- [x] ~~API 调用 Orchestrator，source 为 `schedule`。~~
|
||||
- [x] ~~Orchestrator 路由到 Hermes。~~
|
||||
- [x] ~~Hermes 执行结果写入 AgentRun。~~
|
||||
- [ ] 任务执行失败时写入错误。
|
||||
- [ ] 任务执行结束后更新任务最近执行时间。
|
||||
- [ ] 任务执行结束后更新任务最近执行状态。
|
||||
- [x] ~~保留真实 Hermes 进程执行入口，不把 Hermes 固定写死为本地占位函数。~~
|
||||
|
||||
验收证据：
|
||||
|
||||
- [x] ~~可以手动触发一次 Hermes 任务并看到运行结果。~~
|
||||
|
||||
## 3. 每日风险巡检
|
||||
|
||||
- [ ] 实现重复报销巡检。
|
||||
- [ ] 实现金额超标巡检。
|
||||
- [ ] 实现发票异常巡检占位。
|
||||
- [ ] 实现应收逾期巡检。
|
||||
- [ ] 实现应付异常付款巡检。
|
||||
- [ ] 每个风险项包含风险类型。
|
||||
- [ ] 每个风险项包含业务对象。
|
||||
- [ ] 每个风险项包含触发规则。
|
||||
- [ ] 每个风险项包含建议动作。
|
||||
- [ ] 每个风险项包含风险等级。
|
||||
|
||||
验收证据：
|
||||
|
||||
- [ ] 风险巡检结果可以被用户理解和追溯。
|
||||
|
||||
## 4. 每日统计
|
||||
|
||||
- [ ] 统计当日报销单数量。
|
||||
- [ ] 统计当日报销金额。
|
||||
- [ ] 统计当日报账数量。
|
||||
- [ ] 统计当日报账金额。
|
||||
- [ ] 统计应收新增金额。
|
||||
- [ ] 统计应收逾期金额。
|
||||
- [ ] 统计应付待付金额。
|
||||
- [ ] 统计应付逾期金额。
|
||||
- [ ] 输出日报摘要。
|
||||
|
||||
验收证据：
|
||||
|
||||
- [ ] Hermes 能生成一份每日财务摘要。
|
||||
|
||||
## 5. OCR 接入点
|
||||
|
||||
- [ ] 原始票据先落 `document_assets` 和 `document_asset_versions`，不直接以内存临时文件参与流程。
|
||||
- [ ] 建立 OCR 识别服务接口。
|
||||
- [ ] 定义发票识别输入结构。
|
||||
- [ ] 定义发票识别输出结构。
|
||||
- [ ] 输出结构包含发票号。
|
||||
- [ ] 输出结构包含开票日期。
|
||||
- [ ] 输出结构包含金额。
|
||||
- [ ] 输出结构包含税额。
|
||||
- [ ] 输出结构包含销售方。
|
||||
- [ ] 输出结构包含购买方。
|
||||
- [ ] 输出结构包含置信度。
|
||||
- [ ] OCR 输入可通过 `storage_key` 或等价文件定位字段读取原件。
|
||||
- [ ] 当前阶段允许使用 Mock 结果。
|
||||
- [ ] OCR 调用写入 ToolCall。
|
||||
|
||||
验收证据：
|
||||
|
||||
- [ ] Hermes 风险巡检中可以调用 OCR Mock。
|
||||
|
||||
## 6. 知识库维护
|
||||
|
||||
- [ ] 建立知识条目写入服务。
|
||||
- [x] ~~建立 `.llm_wiki` 独立解析目录。~~
|
||||
- [x] ~~原始文档与解析产物物理隔离。~~
|
||||
- [x] ~~文本抽取结果落 `text.md`。~~
|
||||
- [x] ~~分块结果落 `chunks.json`。~~
|
||||
- [x] ~~文档索引落 `index.json`。~~
|
||||
- [x] ~~同步记录落 `sync_runs.json`。~~
|
||||
- [x] ~~文档签名包含 `original_name`、`stored_name`、`sha256`、`version_number`、`updated_at`。~~
|
||||
- [x] ~~未变化文档跳过重建并记录 `unchanged_skipped`。~~
|
||||
- [x] ~~Hermes 可以生成知识候选条目。~~
|
||||
- [x] ~~候选条目包含标题。~~
|
||||
- [x] ~~候选条目包含正文。~~
|
||||
- [x] ~~候选条目包含来源。~~
|
||||
- [x] ~~候选条目包含适用场景。~~
|
||||
- [x] ~~候选条目默认状态为 `draft`。~~
|
||||
- [x] ~~知识条目不能自动发布。~~
|
||||
- [ ] 知识条目写入审计日志。
|
||||
|
||||
验收证据：
|
||||
|
||||
- [x] ~~Hermes 可以生成待审核知识条目。~~
|
||||
|
||||
## 7. 规则草稿形成
|
||||
|
||||
- [ ] Hermes 可以根据风险巡检结果生成规则草稿。
|
||||
- [x] ~~规则草稿使用固定 Markdown 模板。~~
|
||||
- [x] ~~规则草稿生成可执行 JSON 草稿。~~
|
||||
- [x] ~~规则中心展示 Markdown + JSON 双视图。~~
|
||||
- [x] ~~JSON 草稿字段受模板约束，不允许自由扩展。~~
|
||||
- [x] ~~规则草稿保存为 `asset_type=rule`。~~
|
||||
- [x] ~~规则草稿状态为 `draft`。~~
|
||||
- [x] ~~规则草稿包含 Markdown 内容。~~
|
||||
- [x] ~~规则草稿包含 JSON 内容或等价 `runtime_rule` 配置。~~
|
||||
- [ ] 规则草稿包含生成原因。
|
||||
- [ ] 规则草稿包含关联风险样例。
|
||||
- [x] ~~规则草稿不能自动上线。~~
|
||||
- [x] ~~规则草稿需要审核人。~~
|
||||
- [x] ~~规则草稿写入审计日志。~~
|
||||
- [x] ~~Hermes 不直接覆盖线上 active 规则。~~
|
||||
|
||||
验收证据：
|
||||
|
||||
- [x] ~~Hermes 生成的新规则出现在规则列表中，但不是 active。~~
|
||||
|
||||
## 8. Hermes 页面或日志展示
|
||||
|
||||
- [x] ~~任务详情能看到最近执行结果。~~
|
||||
- [ ] 任务详情能手动触发执行。
|
||||
- [ ] 任务详情能看到风险项数量。
|
||||
- [ ] 任务详情能看到日报摘要。
|
||||
- [ ] 任务详情能看到知识候选数量。
|
||||
- [ ] 任务详情能看到规则草稿数量。
|
||||
- [ ] 运行 Trace 能看到 Hermes 步骤。
|
||||
- [x] ~~错误时展示错误原因。~~
|
||||
- [ ] 日志管理页能查看 Hermes 归纳任务的实时状态。
|
||||
- [ ] 日志管理页能查看 Hermes ToolCall 请求与结果。
|
||||
- [ ] 日志管理页能查看系统运行日志文本。
|
||||
- [ ] 知识管理页能在后台任务完成后自动刷新归纳状态。
|
||||
|
||||
验收证据：
|
||||
|
||||
- [x] ~~不查数据库也能判断 Hermes 是否执行成功。~~
|
||||
|
||||
## 9. 测试
|
||||
|
||||
- [x] ~~测试手动触发任务。~~
|
||||
- [x] ~~测试 Orchestrator 路由到 Hermes。~~
|
||||
- [ ] 测试风险巡检输出。
|
||||
- [ ] 测试日报统计输出。
|
||||
- [ ] 测试 OCR Mock 调用。
|
||||
- [x] ~~测试知识候选写入。~~
|
||||
- [x] ~~测试规则草稿生成。~~
|
||||
- [ ] 测试 Hermes 异常写入 AgentRun。
|
||||
- [ ] 测试知识归纳异步任务在接口返回后仍能继续执行。
|
||||
- [ ] 测试归纳进度能持续写入 AgentRun。
|
||||
- [ ] 测试系统日志读取接口。
|
||||
|
||||
验收证据：
|
||||
|
||||
- [ ] Hermes 核心测试通过。
|
||||
|
||||
## 10. Day 6 验收
|
||||
|
||||
- [x] ~~Hermes 可被 Orchestrator 调用。~~
|
||||
- [x] ~~至少一个任务可以手动触发。~~
|
||||
- [ ] 风险巡检有结构化结果。
|
||||
- [ ] 每日统计有结构化结果。
|
||||
- [ ] OCR Mock 接入点可用。
|
||||
- [x] ~~知识候选可生成。~~
|
||||
- [x] ~~规则草稿可生成且不能自动上线。~~
|
||||
- [x] ~~任务详情或运行日志能展示结果。~~
|
||||
- [x] ~~所有完成项已用 `[x] ~~...~~` 标记。~~
|
||||
|
||||
## 阻塞记录
|
||||
|
||||
- [ ] 暂无。
|
||||
|
||||
## 日终交接
|
||||
|
||||
- [ ] 写明 Hermes 已支持任务类型。
|
||||
- [ ] 写明 OCR 当前是真实还是 Mock。
|
||||
- [ ] 写明生成的知识和规则草稿状态。
|
||||
- [ ] 写明 Day 7 需要重点回归的路径。
|
||||
@@ -1,260 +0,0 @@
|
||||
# Day 7：加固、演示和验收
|
||||
|
||||
## 今天的大开发点
|
||||
|
||||
不再大规模扩功能，集中做回归、加固、测试、演示脚本、文档收尾和下一阶段交接。
|
||||
|
||||
## 为什么第七天做这个
|
||||
|
||||
一周开发不能只停留在“代码写了”。必须能演示、能追溯、能说清楚边界、能交给下一阶段继续开发。
|
||||
|
||||
## 今天主要交付
|
||||
|
||||
- 核心链路回归。
|
||||
- 权限和风险边界复查。
|
||||
- 审计日志补齐。
|
||||
- AgentRun Trace 补齐。
|
||||
- 前端体验修补。
|
||||
- 测试和构建记录。
|
||||
- 评测集执行记录。
|
||||
- 演示数据准备。
|
||||
- 演示脚本。
|
||||
- 下一阶段开发建议。
|
||||
|
||||
相关架构文档：
|
||||
|
||||
- [Agent Plan 总览](<../agent plan/00_README.md>)
|
||||
- [开发路线图](<../agent plan/05_development_roadmap.md>)
|
||||
- [观测与 Trace](<../agent plan/09_observability_and_trace.md>)
|
||||
- [评测与测试集](<../agent plan/10_evaluation_and_testset.md>)
|
||||
|
||||
## 当天验收门槛
|
||||
|
||||
- 任务规则中心核心路径可演示。
|
||||
- 语义本体、Orchestrator、User Agent、Hermes 都能跑通最小链路。
|
||||
- 未审核规则、高风险动作、自动付款等边界都被拦截。
|
||||
- AgentRun、ToolCall、AuditLog 可追溯。
|
||||
- 有测试记录、演示脚本和交接说明。
|
||||
|
||||
## 今天不做
|
||||
|
||||
- 不做新大功能。
|
||||
- 不临时扩大范围。
|
||||
- 不绕过测试和验收。
|
||||
|
||||
## 详细执行清单
|
||||
|
||||
以下内容为合并后的详细执行清单。
|
||||
|
||||
## 0. 开始前检查
|
||||
|
||||
- [ ] 汇总 Day 1 未完成项。
|
||||
- [ ] 汇总 Day 2 未完成项。
|
||||
- [ ] 汇总 Day 3 未完成项。
|
||||
- [ ] 汇总 Day 4 未完成项。
|
||||
- [ ] 汇总 Day 5 未完成项。
|
||||
- [ ] 汇总 Day 6 未完成项。
|
||||
- [ ] 标记必须今天修复的问题。
|
||||
- [ ] 标记可以进入下一阶段的问题。
|
||||
- [ ] 冻结新增需求，只处理验收相关问题。
|
||||
|
||||
## 1. 核心链路回归
|
||||
|
||||
- [ ] 回归资产列表接口。
|
||||
- [ ] 回归规则详情接口。
|
||||
- [ ] 回归 Markdown 保存。
|
||||
- [ ] 回归版本列表。
|
||||
- [ ] 回归版本切换。
|
||||
- [ ] 回归审核接口。
|
||||
- [ ] 回归上线拦截。
|
||||
- [ ] 回归语义解析接口。
|
||||
- [ ] 回归 Orchestrator 路由。
|
||||
- [ ] 回归 User Agent 问答。
|
||||
- [ ] 回归 Hermes 任务执行。
|
||||
- [ ] 回归 AgentRun Trace。
|
||||
- [ ] 回归 ToolCall 日志。
|
||||
- [ ] 回归 AuditLog 日志。
|
||||
|
||||
验收证据：
|
||||
|
||||
- [ ] 从前端能完成至少一条端到端演示路径。
|
||||
|
||||
## 2. 权限和风险边界
|
||||
|
||||
- [ ] 未审核规则不能上线。
|
||||
- [ ] rejected 规则不能上线。
|
||||
- [ ] disabled 能力不能被调用。
|
||||
- [ ] 用户请求付款必须拦截。
|
||||
- [ ] 用户请求审批必须需要确认。
|
||||
- [ ] Hermes 生成规则只能是 draft。
|
||||
- [ ] Hermes 生成知识只能是 draft。
|
||||
- [ ] User Agent 生成处理意见只能是草稿。
|
||||
- [ ] 所有高风险动作响应中包含 `requires_confirmation`。
|
||||
|
||||
验收证据：
|
||||
|
||||
- [ ] 不存在 MVP 期间绕过人工审核的路径。
|
||||
|
||||
## 3. 审计和 Trace 补齐
|
||||
|
||||
- [ ] 规则保存写 AuditLog。
|
||||
- [ ] 规则审核写 AuditLog。
|
||||
- [ ] 规则上线写 AuditLog。
|
||||
- [ ] Hermes 生成规则草稿写 AuditLog。
|
||||
- [ ] Hermes 生成知识候选写 AuditLog。
|
||||
- [ ] User Agent 草稿生成写 AuditLog。
|
||||
- [ ] Orchestrator 每次运行有 AgentRun。
|
||||
- [ ] 每次工具调用有 ToolCall。
|
||||
- [ ] Trace 页面或接口能串起 run_id。
|
||||
- [ ] 错误 Trace 包含 error_message。
|
||||
|
||||
验收证据：
|
||||
|
||||
- [ ] 任意一条演示链路都能追溯到 run_id。
|
||||
|
||||
## 4. 前端体验修补
|
||||
|
||||
- [ ] 任务规则中心列表无明显错位。
|
||||
- [ ] 详情页无双 title。
|
||||
- [ ] Hero title 高度紧凑。
|
||||
- [ ] 返回列表栏高度正常。
|
||||
- [ ] Markdown 编辑器和版本卡片底部对齐。
|
||||
- [ ] 版本卡片不贴右侧。
|
||||
- [ ] 当前版本标识不突兀。
|
||||
- [ ] 日期列对齐。
|
||||
- [ ] 弹窗文案清楚。
|
||||
- [ ] 加载态可见。
|
||||
- [ ] 错误态可见。
|
||||
- [ ] 空态可见。
|
||||
- [ ] 按钮禁用态可见。
|
||||
- [ ] 窄屏不出现内容重叠。
|
||||
|
||||
验收证据：
|
||||
|
||||
- [ ] 任务规则中心可以给业务用户演示，不需要解释 UI 异常。
|
||||
|
||||
## 5. 测试补齐
|
||||
|
||||
- [ ] 运行后端现有测试。
|
||||
- [ ] 运行新增模型测试。
|
||||
- [ ] 运行新增 API 测试。
|
||||
- [ ] 运行语义解析测试。
|
||||
- [ ] 运行 Orchestrator 测试。
|
||||
- [ ] 运行 User Agent 测试。
|
||||
- [ ] 运行 Hermes 测试。
|
||||
- [ ] 运行前端构建。
|
||||
- [ ] 如果有前端测试，运行前端测试。
|
||||
- [ ] 记录未能运行的测试和原因。
|
||||
|
||||
验收证据：
|
||||
|
||||
- [ ] 测试结果写入本文件“测试记录”。
|
||||
|
||||
## 6. 评测集
|
||||
|
||||
- [ ] 准备 5 条报销问题。
|
||||
- [ ] 准备 5 条应收问题。
|
||||
- [ ] 准备 5 条应付问题。
|
||||
- [ ] 准备 3 条规则解释问题。
|
||||
- [ ] 准备 3 条越权动作问题。
|
||||
- [ ] 执行语义解析评测。
|
||||
- [ ] 执行 User Agent 回答评测。
|
||||
- [ ] 执行权限拦截评测。
|
||||
- [ ] 记录失败样例。
|
||||
- [ ] 为失败样例写下一阶段优化建议。
|
||||
|
||||
验收证据：
|
||||
|
||||
- [ ] 可以说明 MVP 当前能力边界和准确率风险。
|
||||
|
||||
## 7. 演示数据
|
||||
|
||||
- [ ] 准备 active 规则。
|
||||
- [ ] 准备 pending 规则。
|
||||
- [ ] 准备 rejected 规则。
|
||||
- [ ] 准备至少一条报销数据。
|
||||
- [ ] 准备至少一条应收数据。
|
||||
- [ ] 准备至少一条应付数据。
|
||||
- [ ] 准备至少一个 Hermes 任务。
|
||||
- [ ] 准备至少一个 MCP Mock。
|
||||
- [ ] 准备至少一个知识条目。
|
||||
- [ ] 准备至少一个风险样例。
|
||||
|
||||
验收证据：
|
||||
|
||||
- [ ] 演示不会因为没有数据而中断。
|
||||
|
||||
## 8. 演示脚本
|
||||
|
||||
- [ ] 编写演示步骤 1：打开任务规则中心。
|
||||
- [ ] 编写演示步骤 2：查看规则详情。
|
||||
- [ ] 编写演示步骤 3：编辑 Markdown 并保存。
|
||||
- [ ] 编写演示步骤 4：切换版本。
|
||||
- [ ] 编写演示步骤 5：尝试上线未审核规则并被拦截。
|
||||
- [ ] 编写演示步骤 6：输入用户问题。
|
||||
- [ ] 编写演示步骤 7：查看语义本体结果。
|
||||
- [ ] 编写演示步骤 8：查看 User Agent 回答。
|
||||
- [ ] 编写演示步骤 9：手动触发 Hermes 任务。
|
||||
- [ ] 编写演示步骤 10：查看 AgentRun Trace。
|
||||
- [ ] 编写演示步骤 11：查看审计日志。
|
||||
|
||||
验收证据：
|
||||
|
||||
- [ ] 新开发者按脚本可以复现演示。
|
||||
|
||||
## 9. 文档收尾
|
||||
|
||||
- [ ] 更新一周计划完成情况。
|
||||
- [ ] 更新剩余风险。
|
||||
- [ ] 更新下一阶段开发建议。
|
||||
- [ ] 更新接口清单。
|
||||
- [ ] 更新数据模型清单。
|
||||
- [ ] 更新前端页面清单。
|
||||
- [ ] 更新评测结果。
|
||||
- [ ] 更新演示脚本。
|
||||
- [ ] 更新部署或启动说明。
|
||||
|
||||
验收证据：
|
||||
|
||||
- [ ] 文档能指导下一周继续开发。
|
||||
|
||||
## 10. 最终验收清单
|
||||
|
||||
- [ ] 任务规则中心可查看规则、技能、MCP、任务。
|
||||
- [ ] 规则详情可编辑 Markdown。
|
||||
- [ ] 规则详情可查看最近 5 个版本。
|
||||
- [ ] 版本切换有确认弹窗。
|
||||
- [ ] 审核者信息可见。
|
||||
- [ ] 未审核规则不能上线。
|
||||
- [ ] 语义本体 8 字段可返回。
|
||||
- [ ] Orchestrator 能路由用户请求。
|
||||
- [ ] Orchestrator 能路由定时任务。
|
||||
- [ ] User Agent 能回答至少 3 类财务问题。
|
||||
- [ ] Hermes 能执行至少 1 个任务。
|
||||
- [ ] OCR Mock 接入点可用。
|
||||
- [ ] 知识候选可生成。
|
||||
- [ ] 规则草稿可生成。
|
||||
- [ ] AgentRun Trace 可查。
|
||||
- [ ] AuditLog 可查。
|
||||
- [ ] 前端构建通过。
|
||||
- [ ] 后端核心测试通过。
|
||||
- [ ] 演示脚本可执行。
|
||||
- [ ] 所有完成项已用 `[x] ~~...~~` 标记。
|
||||
|
||||
## 测试记录
|
||||
|
||||
- [ ] 后端测试：未运行。
|
||||
- [ ] 前端构建：未运行。
|
||||
- [ ] 语义评测：未运行。
|
||||
- [ ] 手动验收：未运行。
|
||||
|
||||
## 阻塞记录
|
||||
|
||||
- [ ] 暂无。
|
||||
|
||||
## 日终交接
|
||||
|
||||
- [ ] 写明本周最终完成内容。
|
||||
- [ ] 写明未完成内容。
|
||||
- [ ] 写明生产化前必须补齐内容。
|
||||
- [ ] 写明下一周建议优先级。
|
||||
@@ -1,137 +0,0 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="zh-CN">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<title>Day 1 - 基础模型与工程骨架</title>
|
||||
<link rel="stylesheet" href="./styles.css">
|
||||
</head>
|
||||
<body>
|
||||
<div class="shell">
|
||||
<div class="topbar">
|
||||
<a class="brand" href="./index.html"><span class="brand-mark">D1</span><span>Day 1 View</span></a>
|
||||
<div class="quick-links">
|
||||
<a class="pill" href="./index.html">返回总览</a>
|
||||
<a class="pill" href="../agent%20week%20plan/day_1_foundation_models.md">周计划原文</a>
|
||||
<a class="pill" href="../agent%20week%20plan/day_1_foundation_models.md">合并文档原文</a>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="day-nav">
|
||||
<a class="pill active" href="./day-1.html">Day 1</a>
|
||||
<a class="pill" href="./day-2.html">Day 2</a>
|
||||
<a class="pill" href="./day-3.html">Day 3</a>
|
||||
<a class="pill" href="./day-4.html">Day 4</a>
|
||||
<a class="pill" href="./day-5.html">Day 5</a>
|
||||
<a class="pill" href="./day-6.html">Day 6</a>
|
||||
<a class="pill" href="./day-7.html">Day 7</a>
|
||||
</div>
|
||||
|
||||
<section class="hero">
|
||||
<div class="hero-badge">Foundation Completed</div>
|
||||
<h1>Day 1 基础模型与工程骨架</h1>
|
||||
<p>这一天的任务不是做炫目的业务能力，而是把后面 6 天要反复依赖的模型、版本、审核、run trace、审计日志和最小业务数据源一次定稳。Day 1 做虚了，Day 4 到 Day 6 会全部返工。</p>
|
||||
<div class="hero-meta">
|
||||
<div class="meta-card"><div class="meta-label">当前状态</div><div class="meta-value">已完成（2026-05-11），可直接进入 Day 2 联调。</div></div>
|
||||
<div class="meta-card"><div class="meta-label">上游依赖</div><div class="meta-value">无，Day 1 是全周底座。</div></div>
|
||||
<div class="meta-card"><div class="meta-label">下游交接</div><div class="meta-value">Day 2 资产 API，Day 3 解析日志，Day 4 run trace，Day 5/6 业务数据查询。</div></div>
|
||||
<div class="meta-card"><div class="meta-label">当天关键</div><div class="meta-value">先确定统一模型，再接 API 骨架和种子数据。</div></div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<div class="section-kicker">Three-Layer Mapping</div>
|
||||
<h2 class="section-title">三层文档映射</h2>
|
||||
<div class="grid three">
|
||||
<section class="card tone-warm">
|
||||
<h3>路线图</h3>
|
||||
<p>周计划里定义这一天要完成“工程地基”，强调只做稳定模型、API 骨架、种子数据、基础审计和可运行验证。</p>
|
||||
<div class="card-links"><a class="link-chip" href="../agent%20week%20plan/day_1_foundation_models.md">day_1_foundation_models.md</a></div>
|
||||
</section>
|
||||
<section class="card tone-teal">
|
||||
<h3>执行细则</h3>
|
||||
<p>执行层把 Day 1 拆成命名边界、最小财务业务数据模型、Agent 资产模型、版本、审核、Run、ToolCall、SemanticParseLog、AuditLog、Schema、API、服务层。</p>
|
||||
<div class="card-links"><a class="link-chip" href="../agent%20week%20plan/day_1_foundation_models.md">agent week plan/day_1</a></div>
|
||||
</section>
|
||||
<section class="card tone-olive">
|
||||
<h3>架构依据</h3>
|
||||
<p>主要受总体架构、语义本体、数据契约、能力注册、权限确认、可观测性和财务标准模型约束。</p>
|
||||
<div class="card-links">
|
||||
<a class="link-chip" href="../agent%20plan/01_overall_architecture.md">01</a>
|
||||
<a class="link-chip" href="../agent%20plan/02_semantic_ontology.md">02</a>
|
||||
<a class="link-chip" href="../agent%20plan/06_data_contracts_and_governance.md">06</a>
|
||||
<a class="link-chip" href="../agent%20plan/07_capability_registry.md">07</a>
|
||||
<a class="link-chip" href="../agent%20plan/08_permission_confirmation.md">08</a>
|
||||
<a class="link-chip" href="../agent%20plan/09_observability_and_trace.md">09</a>
|
||||
<a class="link-chip" href="../agent%20plan/14_financial_document_canonical_model.md">14</a>
|
||||
</div>
|
||||
</section>
|
||||
</div>
|
||||
|
||||
<div class="section-kicker">Build Order</div>
|
||||
<h2 class="section-title">推荐开发顺序</h2>
|
||||
<div class="timeline">
|
||||
<div class="timeline-step"><strong>Step 1</strong>先确认后端目录、ORM、迁移方式、测试目录和不该碰的文件。</div>
|
||||
<div class="timeline-step"><strong>Step 2</strong>统一命名：资产类型、状态、审核状态、Agent、权限级别。</div>
|
||||
<div class="timeline-step"><strong>Step 3</strong>补最小财务业务数据模型：<code>expense_claims</code>、<code>accounts_receivable</code>、<code>accounts_payable</code>。</div>
|
||||
<div class="timeline-step"><strong>Step 4</strong>完成 AgentAsset、Version、Review、Run、ToolCall、ParseLog、AuditLog。</div>
|
||||
<div class="timeline-step"><strong>Step 5</strong>把 Schema、API 骨架、服务层、种子数据接起来。</div>
|
||||
</div>
|
||||
|
||||
<div class="section-kicker">Must Deliver</div>
|
||||
<h2 class="section-title">今天必须产出的东西</h2>
|
||||
<div class="grid two">
|
||||
<section class="card">
|
||||
<h3>平台底座表</h3>
|
||||
<ul class="list">
|
||||
<li><code>AgentAsset</code>、<code>AgentAssetVersion</code>、<code>AgentAssetReview</code></li>
|
||||
<li><code>AgentRun</code>、<code>AgentToolCall</code>、<code>SemanticParseLog</code></li>
|
||||
<li><code>AuditLog</code></li>
|
||||
</ul>
|
||||
</section>
|
||||
<section class="card">
|
||||
<h3>最小业务数据来源</h3>
|
||||
<ul class="list">
|
||||
<li>报销至少有时间、地点、理由、金额、员工、部门、状态。</li>
|
||||
<li>应收至少有客户、金额、未收金额、到期日、账龄、状态。</li>
|
||||
<li>应付至少有供应商、金额、未付金额、到期日、账龄、状态。</li>
|
||||
</ul>
|
||||
</section>
|
||||
<section class="card">
|
||||
<h3>API 骨架</h3>
|
||||
<ul class="list">
|
||||
<li>资产列表 / 详情 / 版本 / 审核 / 上线。</li>
|
||||
<li>运行日志与审计日志查询。</li>
|
||||
<li>返回真实数据库结果，不用前端硬编码收尾。</li>
|
||||
</ul>
|
||||
</section>
|
||||
<section class="card">
|
||||
<h3>统一服务边界</h3>
|
||||
<ul class="list">
|
||||
<li>上线拦截逻辑在服务层，不堆到路由。</li>
|
||||
<li>所有写操作要留审计接口。</li>
|
||||
<li>任何 Agent 执行记录都必须生成 <code>run_id</code>。</li>
|
||||
</ul>
|
||||
</section>
|
||||
</div>
|
||||
|
||||
<div class="section-kicker">Acceptance Snapshot</div>
|
||||
<h2 class="section-title">验收快照</h2>
|
||||
<div class="table-like">
|
||||
<div class="row"><div class="row-label">资产模型</div><div class="row-value">已落地 3 条规则、2 条技能、2 条 MCP、3 条任务，并可通过资产接口返回。</div></div>
|
||||
<div class="row"><div class="row-label">版本与审核</div><div class="row-value">三条规则都具备版本历史；同一资产版本号不可重复，未审核规则不能上线。</div></div>
|
||||
<div class="row"><div class="row-label">运行与错误</div><div class="row-value">`GET /api/v1/agent-runs` 可返回 3 条运行日志，任意新建 Run 自动生成 <code>run_id</code>。</div></div>
|
||||
<div class="row"><div class="row-label">最小业务表</div><div class="row-value">报销、应收、应付种子数据已就位，后续查询和风险巡检都有明确数据来源。</div></div>
|
||||
</div>
|
||||
|
||||
<div class="section-kicker">Common Misses</div>
|
||||
<h2 class="section-title">这一天最容易漏掉的点</h2>
|
||||
<ul class="list">
|
||||
<li>只建 Agent 表，不建最小财务业务表，导致 User Agent 和 Hermes 后面无数据可查。</li>
|
||||
<li>把审核拦截塞在 API 路由里，后面很难复用到 Orchestrator 和别的入口。</li>
|
||||
<li>没有统一 <code>run_id</code> 和审计接口，Day 4 到 Day 7 的 Trace 会断链。</li>
|
||||
</ul>
|
||||
|
||||
<div class="footer">Day 1 的判断标准很简单：不是“代码写了多少”，而是“后面 6 天会不会反复回头补地基”。</div>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -1,132 +0,0 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="zh-CN">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<title>Day 2 - 任务规则中心联调</title>
|
||||
<link rel="stylesheet" href="./styles.css">
|
||||
</head>
|
||||
<body>
|
||||
<div class="shell">
|
||||
<div class="topbar">
|
||||
<a class="brand" href="./index.html"><span class="brand-mark">D2</span><span>Day 2 View</span></a>
|
||||
<div class="quick-links">
|
||||
<a class="pill" href="./index.html">返回总览</a>
|
||||
<a class="pill" href="../agent%20week%20plan/day_2_rule_center_integration.md">周计划原文</a>
|
||||
<a class="pill" href="../agent%20week%20plan/day_2_rule_center_integration.md">合并文档原文</a>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="day-nav">
|
||||
<a class="pill" href="./day-1.html">Day 1</a>
|
||||
<a class="pill active" href="./day-2.html">Day 2</a>
|
||||
<a class="pill" href="./day-3.html">Day 3</a>
|
||||
<a class="pill" href="./day-4.html">Day 4</a>
|
||||
<a class="pill" href="./day-5.html">Day 5</a>
|
||||
<a class="pill" href="./day-6.html">Day 6</a>
|
||||
<a class="pill" href="./day-7.html">Day 7</a>
|
||||
</div>
|
||||
|
||||
<section class="hero">
|
||||
<div class="hero-badge">Integration</div>
|
||||
<h1>Day 2 任务规则中心联调</h1>
|
||||
<p>Day 2 的核心不是“把页面做漂亮”，而是让规则、技能、MCP、任务这四类资产第一次脱离本地假数据，真正连到 Day 1 的数据库和 API。最关键的能力是 Markdown、版本、审核和上线约束闭环。</p>
|
||||
<div class="hero-meta">
|
||||
<div class="meta-card"><div class="meta-label">上游依赖</div><div class="meta-value">Day 1 的资产模型、版本模型、审核模型、资产 API。</div></div>
|
||||
<div class="meta-card"><div class="meta-label">下游交接</div><div class="meta-value">Day 3 要复用资产数据，Day 4 要查询 active 技能 / MCP / 任务。</div></div>
|
||||
<div class="meta-card"><div class="meta-label">当天关键</div><div class="meta-value">前端联调不是硬编码演示，而是可对接真实后端。</div></div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<div class="section-kicker">Three-Layer Mapping</div>
|
||||
<h2 class="section-title">三层文档映射</h2>
|
||||
<div class="grid three">
|
||||
<section class="card tone-warm">
|
||||
<h3>路线图</h3>
|
||||
<p>周计划要求把任务规则中心从静态 UI 升级到真实数据对接，覆盖规则、技能、MCP、任务四类资产。</p>
|
||||
<div class="card-links"><a class="link-chip" href="../agent%20week%20plan/day_2_rule_center_integration.md">day_2_rule_center_integration.md</a></div>
|
||||
</section>
|
||||
<section class="card tone-teal">
|
||||
<h3>执行细则</h3>
|
||||
<p>执行层拆成 API Client、四类列表、规则详情、Markdown 编辑、版本卡片、审核与上线、技能详情、MCP 详情、任务详情、前端质量和当天验收。</p>
|
||||
<div class="card-links"><a class="link-chip" href="../agent%20week%20plan/day_2_rule_center_integration.md">agent week plan/day_2</a></div>
|
||||
</section>
|
||||
<section class="card tone-olive">
|
||||
<h3>架构依据</h3>
|
||||
<p>这一天主要受能力注册、规则形成生命周期和数据治理约束，重点在四类资产的统一展示方式和规则上线前审核拦截。</p>
|
||||
<div class="card-links">
|
||||
<a class="link-chip" href="../agent%20plan/07_capability_registry.md">07</a>
|
||||
<a class="link-chip" href="../agent%20plan/13_rule_formation_lifecycle.md">13</a>
|
||||
<a class="link-chip" href="../agent%20plan/06_data_contracts_and_governance.md">06</a>
|
||||
</div>
|
||||
</section>
|
||||
</div>
|
||||
|
||||
<div class="section-kicker">Build Order</div>
|
||||
<h2 class="section-title">推荐开发顺序</h2>
|
||||
<div class="timeline">
|
||||
<div class="timeline-step"><strong>Step 1</strong>先补 API Client：列表、详情、版本、保存、审核、上线、运行日志。</div>
|
||||
<div class="timeline-step"><strong>Step 2</strong>把四个页签的真实数据接起来，覆盖筛选、搜索、状态、空态和加载态。</div>
|
||||
<div class="timeline-step"><strong>Step 3</strong>把规则详情的 Hero 区、Markdown 编辑器、版本卡片和审核信息拉通。</div>
|
||||
<div class="timeline-step"><strong>Step 4</strong>补技能 / MCP / 任务的差异化详情，不复用规则编辑器。</div>
|
||||
<div class="timeline-step"><strong>Step 5</strong>最后收 UI 细节、错误态、禁用态、确认弹窗和构建验证。</div>
|
||||
</div>
|
||||
|
||||
<div class="section-kicker">Must Deliver</div>
|
||||
<h2 class="section-title">今天必须产出的东西</h2>
|
||||
<div class="grid two">
|
||||
<section class="card">
|
||||
<h3>规则中心四页签</h3>
|
||||
<ul class="list">
|
||||
<li>规则、技能、MCP、任务都能切换。</li>
|
||||
<li>每个页签都来自真实接口，不再只读本地常量。</li>
|
||||
<li>搜索和状态筛选同时生效。</li>
|
||||
</ul>
|
||||
</section>
|
||||
<section class="card">
|
||||
<h3>规则详情闭环</h3>
|
||||
<ul class="list">
|
||||
<li>能读取当前 Markdown。</li>
|
||||
<li>能保存并刷新版本列表。</li>
|
||||
<li>能展示审核者、审核状态、上线条件。</li>
|
||||
</ul>
|
||||
</section>
|
||||
<section class="card">
|
||||
<h3>版本与上线约束</h3>
|
||||
<ul class="list">
|
||||
<li>最近 5 个版本可见。</li>
|
||||
<li>切换旧版本必须弹确认框。</li>
|
||||
<li>未审核规则不能上线，拒绝原因要可见。</li>
|
||||
</ul>
|
||||
</section>
|
||||
<section class="card">
|
||||
<h3>详情差异化</h3>
|
||||
<ul class="list">
|
||||
<li>技能详情展示输入输出与依赖。</li>
|
||||
<li>MCP 详情展示服务地址、鉴权、降级策略。</li>
|
||||
<li>任务详情展示 cron、执行 Agent、最近执行结果。</li>
|
||||
</ul>
|
||||
</section>
|
||||
</div>
|
||||
|
||||
<div class="section-kicker">Acceptance Snapshot</div>
|
||||
<h2 class="section-title">验收快照</h2>
|
||||
<div class="table-like">
|
||||
<div class="row"><div class="row-label">真实数据</div><div class="row-value">四个页签都能用真实后端数据渲染，后端不可用时有明确错误提示。</div></div>
|
||||
<div class="row"><div class="row-label">规则编辑</div><div class="row-value">Markdown 保存后刷新页面仍在，保存失败不丢输入。</div></div>
|
||||
<div class="row"><div class="row-label">版本卡片</div><div class="row-value">最近 5 个版本可切换，当前版本标识清楚但不造成布局位移。</div></div>
|
||||
<div class="row"><div class="row-label">审核上线</div><div class="row-value"><code>pending</code> / <code>rejected</code> 规则都无法上线，<code>approved</code> 才能放行。</div></div>
|
||||
</div>
|
||||
|
||||
<div class="section-kicker">Common Misses</div>
|
||||
<h2 class="section-title">这一天最容易漏掉的点</h2>
|
||||
<ul class="list">
|
||||
<li>只把规则页签接成真实数据，技能、MCP、任务仍然靠假数据撑场面。</li>
|
||||
<li>只做版本列表展示，不做确认弹窗和拒绝风险提示。</li>
|
||||
<li>把任务写成“定时任务”暴露给用户，违背文档里 UI 名称统一成“任务”的约束。</li>
|
||||
</ul>
|
||||
|
||||
<div class="footer">Day 2 的完成标准不是“页面能打开”，而是“规则中心第一次成为真实的资产入口”。</div>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -1,132 +0,0 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="zh-CN">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<title>Day 3 - 语义本体 MVP</title>
|
||||
<link rel="stylesheet" href="./styles.css">
|
||||
</head>
|
||||
<body>
|
||||
<div class="shell">
|
||||
<div class="topbar">
|
||||
<a class="brand" href="./index.html"><span class="brand-mark">D3</span><span>Day 3 View</span></a>
|
||||
<div class="quick-links">
|
||||
<a class="pill" href="./index.html">返回总览</a>
|
||||
<a class="pill" href="../agent%20week%20plan/day_3_semantic_ontology_mvp.md">周计划原文</a>
|
||||
<a class="pill" href="../agent%20week%20plan/day_3_semantic_ontology_mvp.md">合并文档原文</a>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="day-nav">
|
||||
<a class="pill" href="./day-1.html">Day 1</a>
|
||||
<a class="pill" href="./day-2.html">Day 2</a>
|
||||
<a class="pill active" href="./day-3.html">Day 3</a>
|
||||
<a class="pill" href="./day-4.html">Day 4</a>
|
||||
<a class="pill" href="./day-5.html">Day 5</a>
|
||||
<a class="pill" href="./day-6.html">Day 6</a>
|
||||
<a class="pill" href="./day-7.html">Day 7</a>
|
||||
</div>
|
||||
|
||||
<section class="hero">
|
||||
<div class="hero-badge">Ontology</div>
|
||||
<h1>Day 3 语义本体 MVP</h1>
|
||||
<p>这一天把自然语言问题统一切成 8 个核心字段。Day 3 不是追求大模型多聪明，而是先让结构稳定、可落日志、可被 Orchestrator、User Agent 和 Hermes 共用。</p>
|
||||
<div class="hero-meta">
|
||||
<div class="meta-card"><div class="meta-label">上游依赖</div><div class="meta-value">Day 1 的 <code>SemanticParseLog</code> / <code>AgentRun</code>，Day 2 的资产 API。</div></div>
|
||||
<div class="meta-card"><div class="meta-label">下游交接</div><div class="meta-value">Day 4 路由、Day 5 查询解释、Day 6 风险巡检都直接消费这 8 字段。</div></div>
|
||||
<div class="meta-card"><div class="meta-label">当天关键</div><div class="meta-value">名字统一、类型统一、日志统一、低置信度有澄清问题。</div></div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<div class="section-kicker">Three-Layer Mapping</div>
|
||||
<h2 class="section-title">三层文档映射</h2>
|
||||
<div class="grid three">
|
||||
<section class="card tone-warm">
|
||||
<h3>路线图</h3>
|
||||
<p>周计划要求建立用户问题的统一语义解析层，覆盖场景、意图、对象、时间、指标、约束、风险、权限 8 字段。</p>
|
||||
<div class="card-links"><a class="link-chip" href="../agent%20week%20plan/day_3_semantic_ontology_mvp.md">day_3_semantic_ontology_mvp.md</a></div>
|
||||
</section>
|
||||
<section class="card tone-teal">
|
||||
<h3>执行细则</h3>
|
||||
<p>执行层拆成 8 字段定义、字段枚举、Schema、解析服务、对象提取、时间范围、指标约束、风险权限、API、前端调试入口和评测集。</p>
|
||||
<div class="card-links"><a class="link-chip" href="../agent%20week%20plan/day_3_semantic_ontology_mvp.md">agent week plan/day_3</a></div>
|
||||
</section>
|
||||
<section class="card tone-olive">
|
||||
<h3>架构依据</h3>
|
||||
<p>主要受语义本体、财务标准模型和数据治理约束。应收、应付、报销的对象语义必须能回到最小业务表和标准对象。</p>
|
||||
<div class="card-links">
|
||||
<a class="link-chip" href="../agent%20plan/02_semantic_ontology.md">02</a>
|
||||
<a class="link-chip" href="../agent%20plan/14_financial_document_canonical_model.md">14</a>
|
||||
<a class="link-chip" href="../agent%20plan/06_data_contracts_and_governance.md">06</a>
|
||||
</div>
|
||||
</section>
|
||||
</div>
|
||||
|
||||
<div class="section-kicker">Build Order</div>
|
||||
<h2 class="section-title">推荐开发顺序</h2>
|
||||
<div class="timeline">
|
||||
<div class="timeline-step"><strong>Step 1</strong>先固定 8 个字段名字、类型、默认值和示例。</div>
|
||||
<div class="timeline-step"><strong>Step 2</strong>把 <code>scenario</code>、<code>intent</code>、<code>permission.level</code> 的枚举定死。</div>
|
||||
<div class="timeline-step"><strong>Step 3</strong>做请求/响应 Schema，再写解析服务。</div>
|
||||
<div class="timeline-step"><strong>Step 4</strong>补对象提取、时间范围、指标约束、风险和权限映射。</div>
|
||||
<div class="timeline-step"><strong>Step 5</strong>接 API、日志、调试入口和最小评测集。</div>
|
||||
</div>
|
||||
|
||||
<div class="section-kicker">Must Deliver</div>
|
||||
<h2 class="section-title">今天必须产出的东西</h2>
|
||||
<div class="grid two">
|
||||
<section class="card">
|
||||
<h3>8 字段统一结构</h3>
|
||||
<ul class="list">
|
||||
<li><code>scenario</code>、<code>intent</code>、<code>entities</code>、<code>time_range</code></li>
|
||||
<li><code>metrics</code>、<code>constraints</code>、<code>risk_flags</code>、<code>permission</code></li>
|
||||
<li>附带 <code>confidence</code>、<code>clarification_required</code>、<code>run_id</code></li>
|
||||
</ul>
|
||||
</section>
|
||||
<section class="card">
|
||||
<h3>规则解析优先版</h3>
|
||||
<ul class="list">
|
||||
<li>先用关键词和规则解析打底。</li>
|
||||
<li>报销 / 应收 / 应付 / 知识 / unknown 场景都能落到结构。</li>
|
||||
<li>越权动作能识别为 <code>approval_required</code> 或 <code>forbidden</code>。</li>
|
||||
</ul>
|
||||
</section>
|
||||
<section class="card">
|
||||
<h3>日志和调试入口</h3>
|
||||
<ul class="list">
|
||||
<li>每次解析都要落 <code>SemanticParseLog</code>。</li>
|
||||
<li>前端可直接输入一句话看 8 字段结果。</li>
|
||||
<li>低置信度问题必须给澄清问题。</li>
|
||||
</ul>
|
||||
</section>
|
||||
<section class="card">
|
||||
<h3>最小评测集</h3>
|
||||
<ul class="list">
|
||||
<li>至少覆盖报销、应收、应付、知识、越权动作。</li>
|
||||
<li>每条样例要写期望 <code>scenario</code>、<code>intent</code> 和权限级别。</li>
|
||||
<li>当天目标是可评测，而不是追求完美准确率。</li>
|
||||
</ul>
|
||||
</section>
|
||||
</div>
|
||||
|
||||
<div class="section-kicker">Acceptance Snapshot</div>
|
||||
<h2 class="section-title">验收快照</h2>
|
||||
<div class="table-like">
|
||||
<div class="row"><div class="row-label">语义结构</div><div class="row-value">8 字段在 Schema、服务层、日志里名字完全一致。</div></div>
|
||||
<div class="row"><div class="row-label">关键识别</div><div class="row-value">“本周报销超标风险”“客户 A 本月应收”“供应商 B 明天要付多少钱”都能落到正确场景和意图。</div></div>
|
||||
<div class="row"><div class="row-label">权限结果</div><div class="row-value">“帮我直接付款”不能被识别成可直接执行动作。</div></div>
|
||||
<div class="row"><div class="row-label">日志与前端</div><div class="row-value">连续调用多次都能在日志中查到，并能通过调试入口观察结果。</div></div>
|
||||
</div>
|
||||
|
||||
<div class="section-kicker">Common Misses</div>
|
||||
<h2 class="section-title">这一天最容易漏掉的点</h2>
|
||||
<ul class="list">
|
||||
<li>字段结构和日志结构各写一套名字，后面 Trace 很难串。</li>
|
||||
<li>只做 <code>scenario</code> 和 <code>intent</code>，不做 <code>permission</code>，Day 4 会直接失去拦截依据。</li>
|
||||
<li>只在服务里返回结果，不把解析过程落库或落日志，后续无法复盘误判样例。</li>
|
||||
</ul>
|
||||
|
||||
<div class="footer">Day 3 的价值在于把“语义理解”从模糊文本变成稳定协议。后面所有智能能力都站在这层协议上。</div>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -1,133 +0,0 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="zh-CN">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<title>Day 4 - Orchestrator 运行时</title>
|
||||
<link rel="stylesheet" href="./styles.css">
|
||||
</head>
|
||||
<body>
|
||||
<div class="shell">
|
||||
<div class="topbar">
|
||||
<a class="brand" href="./index.html"><span class="brand-mark">D4</span><span>Day 4 View</span></a>
|
||||
<div class="quick-links">
|
||||
<a class="pill" href="./index.html">返回总览</a>
|
||||
<a class="pill" href="../agent%20week%20plan/day_4_orchestrator_runtime.md">周计划原文</a>
|
||||
<a class="pill" href="../agent%20week%20plan/day_4_orchestrator_runtime.md">合并文档原文</a>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="day-nav">
|
||||
<a class="pill" href="./day-1.html">Day 1</a>
|
||||
<a class="pill" href="./day-2.html">Day 2</a>
|
||||
<a class="pill" href="./day-3.html">Day 3</a>
|
||||
<a class="pill active" href="./day-4.html">Day 4</a>
|
||||
<a class="pill" href="./day-5.html">Day 5</a>
|
||||
<a class="pill" href="./day-6.html">Day 6</a>
|
||||
<a class="pill" href="./day-7.html">Day 7</a>
|
||||
</div>
|
||||
|
||||
<section class="hero">
|
||||
<div class="hero-badge">Runtime</div>
|
||||
<h1>Day 4 Orchestrator 运行时</h1>
|
||||
<p>Day 4 把整个系统第一次串成“能跑的链”。用户消息和定时任务都先走 Orchestrator，由它创建 run、调用语义解析、做权限判断、选择 Agent、记录 ToolCall 和 Trace，然后再给下游执行。</p>
|
||||
<div class="hero-meta">
|
||||
<div class="meta-card"><div class="meta-label">上游依赖</div><div class="meta-value">Day 3 的语义解析结果，Day 1 的 Run / ToolCall，Day 2 的 active 资产。</div></div>
|
||||
<div class="meta-card"><div class="meta-label">下游交接</div><div class="meta-value">Day 5 User Agent 和 Day 6 Hermes 都通过它被调度。</div></div>
|
||||
<div class="meta-card"><div class="meta-label">当天关键</div><div class="meta-value">权限拦截和 Trace 必须在 Orchestrator 层，而不是散落在各 Agent。</div></div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<div class="section-kicker">Three-Layer Mapping</div>
|
||||
<h2 class="section-title">三层文档映射</h2>
|
||||
<div class="grid three">
|
||||
<section class="card tone-warm">
|
||||
<h3>路线图</h3>
|
||||
<p>周计划要求建立统一调度层，让用户请求和系统任务都先进入 Orchestrator，再根据语义、权限、能力注册路由到 User Agent、Hermes、MCP 或规则引擎。</p>
|
||||
<div class="card-links"><a class="link-chip" href="../agent%20week%20plan/day_4_orchestrator_runtime.md">day_4_orchestrator_runtime.md</a></div>
|
||||
</section>
|
||||
<section class="card tone-teal">
|
||||
<h3>执行细则</h3>
|
||||
<p>执行层拆成输入输出、Orchestrator 服务、路由规则、权限判断、能力查询、工具调用封装、API、最小 Trace 查看和测试。</p>
|
||||
<div class="card-links"><a class="link-chip" href="../agent%20week%20plan/day_4_orchestrator_runtime.md">agent week plan/day_4</a></div>
|
||||
</section>
|
||||
<section class="card tone-olive">
|
||||
<h3>架构依据</h3>
|
||||
<p>主要受运行时流程、能力注册、权限确认和可观测性约束。Day 4 的输出要能直接给前端展示，并支持 Day 5/6 的占位实现接入。</p>
|
||||
<div class="card-links">
|
||||
<a class="link-chip" href="../agent%20plan/04_orchestrator_and_runtime_flow.md">04</a>
|
||||
<a class="link-chip" href="../agent%20plan/07_capability_registry.md">07</a>
|
||||
<a class="link-chip" href="../agent%20plan/08_permission_confirmation.md">08</a>
|
||||
<a class="link-chip" href="../agent%20plan/09_observability_and_trace.md">09</a>
|
||||
</div>
|
||||
</section>
|
||||
</div>
|
||||
|
||||
<div class="section-kicker">Build Order</div>
|
||||
<h2 class="section-title">推荐开发顺序</h2>
|
||||
<div class="timeline">
|
||||
<div class="timeline-step"><strong>Step 1</strong>先定 <code>OrchestratorRequest</code> 和 <code>OrchestratorResponse</code>。</div>
|
||||
<div class="timeline-step"><strong>Step 2</strong>写 <code>run(request)</code> 主流程：创建 Run、解析语义、判权限、选 Agent、更新状态。</div>
|
||||
<div class="timeline-step"><strong>Step 3</strong>把用户入口 / 任务入口的路由规则固化下来。</div>
|
||||
<div class="timeline-step"><strong>Step 4</strong>封装工具调用记录和降级策略。</div>
|
||||
<div class="timeline-step"><strong>Step 5</strong>暴露 API 和最小 Trace 页面或接口。</div>
|
||||
</div>
|
||||
|
||||
<div class="section-kicker">Must Deliver</div>
|
||||
<h2 class="section-title">今天必须产出的东西</h2>
|
||||
<div class="grid two">
|
||||
<section class="card">
|
||||
<h3>统一入口</h3>
|
||||
<ul class="list">
|
||||
<li><code>source=user_message</code> 与 <code>source=schedule</code> 都能进同一入口。</li>
|
||||
<li>请求返回 <code>run_id</code>、<code>selected_agent</code>、<code>route_reason</code>、<code>permission_level</code>。</li>
|
||||
<li>返回结果要能被前端直接展示。</li>
|
||||
</ul>
|
||||
</section>
|
||||
<section class="card">
|
||||
<h3>权限与路由</h3>
|
||||
<ul class="list">
|
||||
<li>查询类走 User Agent，定时风险类走 Hermes。</li>
|
||||
<li><code>approval_required</code> 只返回确认，不直接执行。</li>
|
||||
<li><code>forbidden</code> 直接阻断，不调下游 Agent。</li>
|
||||
</ul>
|
||||
</section>
|
||||
<section class="card">
|
||||
<h3>能力与工具调用</h3>
|
||||
<ul class="list">
|
||||
<li>只查询 active 技能 / MCP / 任务。</li>
|
||||
<li>禁用能力不允许被调用。</li>
|
||||
<li>每次工具调用都能落 <code>AgentToolCall</code>。</li>
|
||||
</ul>
|
||||
</section>
|
||||
<section class="card">
|
||||
<h3>Trace 与降级</h3>
|
||||
<ul class="list">
|
||||
<li>Trace 能串起语义解析、路由、工具调用和最终结果。</li>
|
||||
<li>外部 MCP 失败要返回降级说明，不让前端拿到不可读错误。</li>
|
||||
<li>异常都要写进 <code>AgentRun.error_message</code>。</li>
|
||||
</ul>
|
||||
</section>
|
||||
</div>
|
||||
|
||||
<div class="section-kicker">Acceptance Snapshot</div>
|
||||
<h2 class="section-title">验收快照</h2>
|
||||
<div class="table-like">
|
||||
<div class="row"><div class="row-label">路由结果</div><div class="row-value">同一句风险检查，在用户入口和任务入口会有不同路由结果。</div></div>
|
||||
<div class="row"><div class="row-label">权限边界</div><div class="row-value">“直接上线规则”和“直接付款”都不会被自动执行。</div></div>
|
||||
<div class="row"><div class="row-label">日志完整度</div><div class="row-value">每次运行至少有一条 <code>AgentRun</code>，工具调用有 0 到多条 <code>AgentToolCall</code>。</div></div>
|
||||
<div class="row"><div class="row-label">可观察性</div><div class="row-value">前端或 curl 可以完整看到一次运行链路，不需要直接查数据库猜过程。</div></div>
|
||||
</div>
|
||||
|
||||
<div class="section-kicker">Common Misses</div>
|
||||
<h2 class="section-title">这一天最容易漏掉的点</h2>
|
||||
<ul class="list">
|
||||
<li>把权限判断放到 User Agent / Hermes 内部，导致系统没有统一边界。</li>
|
||||
<li>只记录成功 ToolCall，不记录失败 ToolCall，后面降级和排错会缺证据。</li>
|
||||
<li>路由能跑，但没有统一 Trace 输出，Day 7 演示时会非常难讲清链路。</li>
|
||||
</ul>
|
||||
|
||||
<div class="footer">Day 4 的价值是把系统从“有很多零件”变成“有一条统一运行链”。</div>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -1,133 +0,0 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="zh-CN">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<title>Day 5 - User Agent MVP</title>
|
||||
<link rel="stylesheet" href="./styles.css">
|
||||
</head>
|
||||
<body>
|
||||
<div class="shell">
|
||||
<div class="topbar">
|
||||
<a class="brand" href="./index.html"><span class="brand-mark">D5</span><span>Day 5 View</span></a>
|
||||
<div class="quick-links">
|
||||
<a class="pill" href="./index.html">返回总览</a>
|
||||
<a class="pill" href="../agent%20week%20plan/day_5_user_agent_mvp.md">周计划原文</a>
|
||||
<a class="pill" href="../agent%20week%20plan/day_5_user_agent_mvp.md">合并文档原文</a>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="day-nav">
|
||||
<a class="pill" href="./day-1.html">Day 1</a>
|
||||
<a class="pill" href="./day-2.html">Day 2</a>
|
||||
<a class="pill" href="./day-3.html">Day 3</a>
|
||||
<a class="pill" href="./day-4.html">Day 4</a>
|
||||
<a class="pill active" href="./day-5.html">Day 5</a>
|
||||
<a class="pill" href="./day-6.html">Day 6</a>
|
||||
<a class="pill" href="./day-7.html">Day 7</a>
|
||||
</div>
|
||||
|
||||
<section class="hero">
|
||||
<div class="hero-badge">User Agent</div>
|
||||
<h1>Day 5 User Agent MVP</h1>
|
||||
<p>这一天开始让“用户真的能问问题”。但 User Agent 只负责查询、解释、规则引用和草稿生成，绝不绕过权限做审批、付款、上线这类高风险动作。</p>
|
||||
<div class="hero-meta">
|
||||
<div class="meta-card"><div class="meta-label">上游依赖</div><div class="meta-value">Day 4 Orchestrator、Day 3 语义结构、Day 1 业务数据与日志模型、Day 2 规则资产。</div></div>
|
||||
<div class="meta-card"><div class="meta-label">下游交接</div><div class="meta-value">Day 7 要拿它做问答演示、规则解释演示和草稿生成演示。</div></div>
|
||||
<div class="meta-card"><div class="meta-label">当天关键</div><div class="meta-value">回答可读、引用可追溯、草稿可确认、高风险不自动执行。</div></div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<div class="section-kicker">Three-Layer Mapping</div>
|
||||
<h2 class="section-title">三层文档映射</h2>
|
||||
<div class="grid three">
|
||||
<section class="card tone-warm">
|
||||
<h3>路线图</h3>
|
||||
<p>周计划要求做用户自然语言入口、报销 / 应收 / 应付查询解释、规则引用解释、建议草稿和前端入口。</p>
|
||||
<div class="card-links"><a class="link-chip" href="../agent%20week%20plan/day_5_user_agent_mvp.md">day_5_user_agent_mvp.md</a></div>
|
||||
</section>
|
||||
<section class="card tone-teal">
|
||||
<h3>执行细则</h3>
|
||||
<p>执行层拆成输入输出、查询处理、规则解释、风险解释、草稿生成、知识库读取骨架、对话入口、安全边界和测试。</p>
|
||||
<div class="card-links"><a class="link-chip" href="../agent%20week%20plan/day_5_user_agent_mvp.md">agent week plan/day_5</a></div>
|
||||
</section>
|
||||
<section class="card tone-olive">
|
||||
<h3>架构依据</h3>
|
||||
<p>主要受 Agent 职责划分、运行时流程、知识架构和规则形成生命周期约束。所有高风险动作只能停留在建议或草稿层。</p>
|
||||
<div class="card-links">
|
||||
<a class="link-chip" href="../agent%20plan/03_agent_responsibilities.md">03</a>
|
||||
<a class="link-chip" href="../agent%20plan/04_orchestrator_and_runtime_flow.md">04</a>
|
||||
<a class="link-chip" href="../agent%20plan/12_llm_wiki_knowledge_architecture.md">12</a>
|
||||
<a class="link-chip" href="../agent%20plan/13_rule_formation_lifecycle.md">13</a>
|
||||
</div>
|
||||
</section>
|
||||
</div>
|
||||
|
||||
<div class="section-kicker">Build Order</div>
|
||||
<h2 class="section-title">推荐开发顺序</h2>
|
||||
<div class="timeline">
|
||||
<div class="timeline-step"><strong>Step 1</strong>先定 <code>UserAgentRequest</code> / <code>UserAgentResponse</code> 协议。</div>
|
||||
<div class="timeline-step"><strong>Step 2</strong>优先实现报销、应收、应付查询处理器。</div>
|
||||
<div class="timeline-step"><strong>Step 3</strong>补规则解释和风险解释，让回答有依据而不是只给一句话。</div>
|
||||
<div class="timeline-step"><strong>Step 4</strong>补草稿生成与知识读取骨架。</div>
|
||||
<div class="timeline-step"><strong>Step 5</strong>最后接前端问答入口、加载态、错误态和确认提示。</div>
|
||||
</div>
|
||||
|
||||
<div class="section-kicker">Must Deliver</div>
|
||||
<h2 class="section-title">今天必须产出的东西</h2>
|
||||
<div class="grid two">
|
||||
<section class="card">
|
||||
<h3>三类财务查询</h3>
|
||||
<ul class="list">
|
||||
<li>报销查询可读，能查金额、状态或进度。</li>
|
||||
<li>应收查询可读，能查客户未收金额或账龄。</li>
|
||||
<li>应付查询可读，能查供应商待付款或付款状态。</li>
|
||||
</ul>
|
||||
</section>
|
||||
<section class="card">
|
||||
<h3>解释能力</h3>
|
||||
<ul class="list">
|
||||
<li>规则解释能引用 active 规则、版本号和更新时间。</li>
|
||||
<li>风险解释能说明风险类型、原因和建议动作。</li>
|
||||
<li>知识库不可用时要优雅降级。</li>
|
||||
</ul>
|
||||
</section>
|
||||
<section class="card">
|
||||
<h3>草稿而非执行</h3>
|
||||
<ul class="list">
|
||||
<li>可生成报销处理意见草稿、应收催收建议草稿、应付付款建议草稿。</li>
|
||||
<li>草稿必须写明“待人工确认”。</li>
|
||||
<li>草稿行为写入审计日志和 AgentRun 结果。</li>
|
||||
</ul>
|
||||
</section>
|
||||
<section class="card">
|
||||
<h3>用户入口</h3>
|
||||
<ul class="list">
|
||||
<li>前端输入框走 Orchestrator，不绕行。</li>
|
||||
<li>显示回答、引用、建议动作、确认提示和 <code>run_id</code>。</li>
|
||||
<li>有加载态和错误态。</li>
|
||||
</ul>
|
||||
</section>
|
||||
</div>
|
||||
|
||||
<div class="section-kicker">Acceptance Snapshot</div>
|
||||
<h2 class="section-title">验收快照</h2>
|
||||
<div class="table-like">
|
||||
<div class="row"><div class="row-label">问答闭环</div><div class="row-value">用户在页面上能完成一次自然语言提问、拿到回答、看到引用和 run_id。</div></div>
|
||||
<div class="row"><div class="row-label">三类场景</div><div class="row-value">至少报销、应收、应付三类财务问题都有结构化回答。</div></div>
|
||||
<div class="row"><div class="row-label">引用能力</div><div class="row-value">“为什么这笔报销有风险”这类问题能引用规则，而不是只给模糊判断。</div></div>
|
||||
<div class="row"><div class="row-label">安全边界</div><div class="row-value">“直接付款”“直接审批”类提示不会自动执行，只能变成建议或草稿。</div></div>
|
||||
</div>
|
||||
|
||||
<div class="section-kicker">Common Misses</div>
|
||||
<h2 class="section-title">这一天最容易漏掉的点</h2>
|
||||
<ul class="list">
|
||||
<li>只返回原始查询数据，不把结果翻译成用户可读回答。</li>
|
||||
<li>只做草稿内容，不做 <code>requires_confirmation</code> 和审计日志。</li>
|
||||
<li>绕过 Orchestrator 直接从前端打 User Agent，导致 Day 4 的统一链路失效。</li>
|
||||
</ul>
|
||||
|
||||
<div class="footer">Day 5 的判断标准是：用户能问、系统能答、回答有依据、动作不越权。</div>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -1,133 +0,0 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="zh-CN">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<title>Day 6 - Hermes MVP</title>
|
||||
<link rel="stylesheet" href="./styles.css">
|
||||
</head>
|
||||
<body>
|
||||
<div class="shell">
|
||||
<div class="topbar">
|
||||
<a class="brand" href="./index.html"><span class="brand-mark">D6</span><span>Day 6 View</span></a>
|
||||
<div class="quick-links">
|
||||
<a class="pill" href="./index.html">返回总览</a>
|
||||
<a class="pill" href="../agent%20week%20plan/day_6_hermes_mvp.md">周计划原文</a>
|
||||
<a class="pill" href="../agent%20week%20plan/day_6_hermes_mvp.md">合并文档原文</a>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="day-nav">
|
||||
<a class="pill" href="./day-1.html">Day 1</a>
|
||||
<a class="pill" href="./day-2.html">Day 2</a>
|
||||
<a class="pill" href="./day-3.html">Day 3</a>
|
||||
<a class="pill" href="./day-4.html">Day 4</a>
|
||||
<a class="pill" href="./day-5.html">Day 5</a>
|
||||
<a class="pill active" href="./day-6.html">Day 6</a>
|
||||
<a class="pill" href="./day-7.html">Day 7</a>
|
||||
</div>
|
||||
|
||||
<section class="hero">
|
||||
<div class="hero-badge">Hermes</div>
|
||||
<h1>Day 6 Hermes MVP</h1>
|
||||
<p>Hermes 是后台数字员工，不做即时对话，而是负责定时巡检、风险预警、日报统计、知识候选和规则草稿。它的关键不是“会不会说”，而是“任务能不能跑、结果能不能追”。</p>
|
||||
<div class="hero-meta">
|
||||
<div class="meta-card"><div class="meta-label">上游依赖</div><div class="meta-value">Day 4 的 Orchestrator 路由，Day 1 的任务与日志表，Day 3 的语义结构，Day 5 可复用的风险/规则/知识接口。</div></div>
|
||||
<div class="meta-card"><div class="meta-label">下游交接</div><div class="meta-value">Day 7 要用它做手动触发任务、查看结果、展示规则草稿和知识候选。</div></div>
|
||||
<div class="meta-card"><div class="meta-label">当天关键</div><div class="meta-value">任务入口、风险项结构、OCR Mock、知识候选和规则草稿都必须可追溯。</div></div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<div class="section-kicker">Three-Layer Mapping</div>
|
||||
<h2 class="section-title">三层文档映射</h2>
|
||||
<div class="grid three">
|
||||
<section class="card tone-warm">
|
||||
<h3>路线图</h3>
|
||||
<p>周计划要求实现 Hermes 调度入口、每日风险巡检、统计任务、知识库维护、OCR Mock 和运行结果面板或 API。</p>
|
||||
<div class="card-links"><a class="link-chip" href="../agent%20week%20plan/day_6_hermes_mvp.md">day_6_hermes_mvp.md</a></div>
|
||||
</section>
|
||||
<section class="card tone-teal">
|
||||
<h3>执行细则</h3>
|
||||
<p>执行层拆成输入输出、任务调度入口、风险巡检、每日统计、OCR 接入点、知识库维护、规则草稿形成、结果展示和测试。</p>
|
||||
<div class="card-links"><a class="link-chip" href="../agent%20week%20plan/day_6_hermes_mvp.md">agent week plan/day_6</a></div>
|
||||
</section>
|
||||
<section class="card tone-olive">
|
||||
<h3>架构依据</h3>
|
||||
<p>主要受 Agent 职责、OCR 架构、知识库架构和反馈学习闭环约束。Hermes 能生成候选和草稿，但不能自动发布正式结果。</p>
|
||||
<div class="card-links">
|
||||
<a class="link-chip" href="../agent%20plan/03_agent_responsibilities.md">03</a>
|
||||
<a class="link-chip" href="../agent%20plan/11_ocr_invoice_architecture.md">11</a>
|
||||
<a class="link-chip" href="../agent%20plan/12_llm_wiki_knowledge_architecture.md">12</a>
|
||||
<a class="link-chip" href="../agent%20plan/15_feedback_learning_loop.md">15</a>
|
||||
</div>
|
||||
</section>
|
||||
</div>
|
||||
|
||||
<div class="section-kicker">Build Order</div>
|
||||
<h2 class="section-title">推荐开发顺序</h2>
|
||||
<div class="timeline">
|
||||
<div class="timeline-step"><strong>Step 1</strong>先定 <code>HermesTaskRequest</code> / <code>HermesTaskResult</code>。</div>
|
||||
<div class="timeline-step"><strong>Step 2</strong>建立手动触发任务 API，经 Orchestrator 路由到 Hermes。</div>
|
||||
<div class="timeline-step"><strong>Step 3</strong>补风险巡检和每日统计的结构化输出。</div>
|
||||
<div class="timeline-step"><strong>Step 4</strong>接入 OCR Mock、知识候选生成、规则草稿生成。</div>
|
||||
<div class="timeline-step"><strong>Step 5</strong>补任务详情展示、错误信息和测试。</div>
|
||||
</div>
|
||||
|
||||
<div class="section-kicker">Must Deliver</div>
|
||||
<h2 class="section-title">今天必须产出的东西</h2>
|
||||
<div class="grid two">
|
||||
<section class="card">
|
||||
<h3>任务调度入口</h3>
|
||||
<ul class="list">
|
||||
<li>可手动触发至少一个任务资产。</li>
|
||||
<li>任务经 Orchestrator 进入 Hermes。</li>
|
||||
<li>结束后能更新最近执行时间和状态。</li>
|
||||
</ul>
|
||||
</section>
|
||||
<section class="card">
|
||||
<h3>风险与统计</h3>
|
||||
<ul class="list">
|
||||
<li>重复报销、金额超标、应收逾期、应付异常付款等风险有结构化输出。</li>
|
||||
<li>日报包含报销、报账、应收、应付的关键统计口径。</li>
|
||||
<li>每个风险项都要能被业务人员理解和追溯。</li>
|
||||
</ul>
|
||||
</section>
|
||||
<section class="card">
|
||||
<h3>知识候选与规则草稿</h3>
|
||||
<ul class="list">
|
||||
<li>知识候选默认是 <code>draft</code>，不能自动发布。</li>
|
||||
<li>规则草稿保存为 <code>asset_type=rule</code>，状态为 <code>draft</code>。</li>
|
||||
<li>两类生成都要写审计日志。</li>
|
||||
</ul>
|
||||
</section>
|
||||
<section class="card">
|
||||
<h3>OCR Mock 与结果展示</h3>
|
||||
<ul class="list">
|
||||
<li>OCR 服务接口和输入输出结构定下来。</li>
|
||||
<li>当前阶段允许完全使用 Mock 结果。</li>
|
||||
<li>任务详情或运行日志中能直接看到 Hermes 的执行结果。</li>
|
||||
</ul>
|
||||
</section>
|
||||
</div>
|
||||
|
||||
<div class="section-kicker">Acceptance Snapshot</div>
|
||||
<h2 class="section-title">验收快照</h2>
|
||||
<div class="table-like">
|
||||
<div class="row"><div class="row-label">任务可触发</div><div class="row-value">至少一个任务可以手动触发，并能查到结构化结果。</div></div>
|
||||
<div class="row"><div class="row-label">风险巡检</div><div class="row-value">输出里能看到风险类型、业务对象、触发规则、建议动作和风险等级。</div></div>
|
||||
<div class="row"><div class="row-label">候选与草稿</div><div class="row-value">知识候选和规则草稿都能生成，但都不是 active / published 正式状态。</div></div>
|
||||
<div class="row"><div class="row-label">可观察性</div><div class="row-value">不用查数据库，也能从任务详情或运行日志判断 Hermes 是否执行成功。</div></div>
|
||||
</div>
|
||||
|
||||
<div class="section-kicker">Common Misses</div>
|
||||
<h2 class="section-title">这一天最容易漏掉的点</h2>
|
||||
<ul class="list">
|
||||
<li>只做 Hermes 服务逻辑，不做任务入口和结果展示，最后无法演示。</li>
|
||||
<li>能生成知识或规则，但没把状态锁在 <code>draft</code>，会直接越过人工审核边界。</li>
|
||||
<li>OCR Mock 只返回一段自由文本，不定义结构字段，后面无法和规则或风险逻辑对接。</li>
|
||||
</ul>
|
||||
|
||||
<div class="footer">Day 6 的价值是让“后台数字员工”第一次具备可触发、可解释、可留痕的闭环。</div>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -1,132 +0,0 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="zh-CN">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<title>Day 7 - 加固、演示和验收</title>
|
||||
<link rel="stylesheet" href="./styles.css">
|
||||
</head>
|
||||
<body>
|
||||
<div class="shell">
|
||||
<div class="topbar">
|
||||
<a class="brand" href="./index.html"><span class="brand-mark">D7</span><span>Day 7 View</span></a>
|
||||
<div class="quick-links">
|
||||
<a class="pill" href="./index.html">返回总览</a>
|
||||
<a class="pill" href="../agent%20week%20plan/day_7_hardening_demo_acceptance.md">周计划原文</a>
|
||||
<a class="pill" href="../agent%20week%20plan/day_7_hardening_demo_acceptance.md">合并文档原文</a>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="day-nav">
|
||||
<a class="pill" href="./day-1.html">Day 1</a>
|
||||
<a class="pill" href="./day-2.html">Day 2</a>
|
||||
<a class="pill" href="./day-3.html">Day 3</a>
|
||||
<a class="pill" href="./day-4.html">Day 4</a>
|
||||
<a class="pill" href="./day-5.html">Day 5</a>
|
||||
<a class="pill" href="./day-6.html">Day 6</a>
|
||||
<a class="pill active" href="./day-7.html">Day 7</a>
|
||||
</div>
|
||||
|
||||
<section class="hero">
|
||||
<div class="hero-badge">Hardening</div>
|
||||
<h1>Day 7 加固、演示和验收</h1>
|
||||
<p>Day 7 不再追求新增大功能，而是把 Day 1 到 Day 6 的链路整理成“可演示、可验收、可继续接手”的状态。没有这一层收口，前面做出来的东西很容易停在“只有作者自己懂”的阶段。</p>
|
||||
<div class="hero-meta">
|
||||
<div class="meta-card"><div class="meta-label">上游依赖</div><div class="meta-value">Day 1 到 Day 6 的全部核心路径。</div></div>
|
||||
<div class="meta-card"><div class="meta-label">当天输出</div><div class="meta-value">回归记录、权限边界、审计和 Trace 补齐、测试记录、演示脚本、交接说明。</div></div>
|
||||
<div class="meta-card"><div class="meta-label">当天关键</div><div class="meta-value">冻结新增需求，只收验收相关缺口。</div></div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<div class="section-kicker">Three-Layer Mapping</div>
|
||||
<h2 class="section-title">三层文档映射</h2>
|
||||
<div class="grid three">
|
||||
<section class="card tone-warm">
|
||||
<h3>路线图</h3>
|
||||
<p>周计划要求完成回归、权限补齐、审计补齐、错误态和空态、评测、演示数据、构建和交付说明。</p>
|
||||
<div class="card-links"><a class="link-chip" href="../agent%20week%20plan/day_7_hardening_demo_acceptance.md">day_7_hardening_demo_acceptance.md</a></div>
|
||||
</section>
|
||||
<section class="card tone-teal">
|
||||
<h3>执行细则</h3>
|
||||
<p>执行层拆成核心链路回归、权限和风险边界、审计和 Trace、前端体验修补、测试补齐、评测集、演示数据、演示脚本和文档收尾。</p>
|
||||
<div class="card-links"><a class="link-chip" href="../agent%20week%20plan/day_7_hardening_demo_acceptance.md">agent week plan/day_7</a></div>
|
||||
</section>
|
||||
<section class="card tone-olive">
|
||||
<h3>架构依据</h3>
|
||||
<p>主要受整体 README、开发路线图、可观测性和评测集约束。Day 7 的本质是把所有边界和证据讲清楚。</p>
|
||||
<div class="card-links">
|
||||
<a class="link-chip" href="../agent%20plan/00_README.md">00</a>
|
||||
<a class="link-chip" href="../agent%20plan/05_development_roadmap.md">05</a>
|
||||
<a class="link-chip" href="../agent%20plan/09_observability_and_trace.md">09</a>
|
||||
<a class="link-chip" href="../agent%20plan/10_evaluation_and_testset.md">10</a>
|
||||
</div>
|
||||
</section>
|
||||
</div>
|
||||
|
||||
<div class="section-kicker">Build Order</div>
|
||||
<h2 class="section-title">推荐收口顺序</h2>
|
||||
<div class="timeline">
|
||||
<div class="timeline-step"><strong>Step 1</strong>先汇总 Day 1 到 Day 6 未完成项，冻结新增需求。</div>
|
||||
<div class="timeline-step"><strong>Step 2</strong>回归核心链路：资产、规则、语义解析、Orchestrator、User Agent、Hermes、Trace、AuditLog。</div>
|
||||
<div class="timeline-step"><strong>Step 3</strong>补权限边界与高风险动作拦截。</div>
|
||||
<div class="timeline-step"><strong>Step 4</strong>补测试、评测、演示数据和前端体验问题。</div>
|
||||
<div class="timeline-step"><strong>Step 5</strong>写演示脚本和交接说明，形成最终交付。</div>
|
||||
</div>
|
||||
|
||||
<div class="section-kicker">Must Deliver</div>
|
||||
<h2 class="section-title">今天必须产出的东西</h2>
|
||||
<div class="grid two">
|
||||
<section class="card">
|
||||
<h3>回归与边界</h3>
|
||||
<ul class="list">
|
||||
<li>未审核规则不能上线。</li>
|
||||
<li>付款、审批、上线等高风险动作都不能绕过确认。</li>
|
||||
<li>disabled 能力不能被调用。</li>
|
||||
</ul>
|
||||
</section>
|
||||
<section class="card">
|
||||
<h3>审计与 Trace</h3>
|
||||
<ul class="list">
|
||||
<li>规则保存、审核、上线都能看到 AuditLog。</li>
|
||||
<li>Hermes 生成知识候选 / 规则草稿有审计。</li>
|
||||
<li>任意演示路径都能追到 <code>run_id</code>。</li>
|
||||
</ul>
|
||||
</section>
|
||||
<section class="card">
|
||||
<h3>测试、评测、演示数据</h3>
|
||||
<ul class="list">
|
||||
<li>后端测试、前端构建、语义评测至少有执行记录。</li>
|
||||
<li>报销 / 应收 / 应付 / 风险 / 知识都准备好演示数据。</li>
|
||||
<li>失败样例和已知边界要明确写出。</li>
|
||||
</ul>
|
||||
</section>
|
||||
<section class="card">
|
||||
<h3>演示脚本与交接</h3>
|
||||
<ul class="list">
|
||||
<li>从任务规则中心、规则详情、版本切换、上线拦截，到 User Agent 问答、Hermes 任务、Trace 和审计，都有明确步骤。</li>
|
||||
<li>新开发者按脚本能走通一遍。</li>
|
||||
</ul>
|
||||
</section>
|
||||
</div>
|
||||
|
||||
<div class="section-kicker">Acceptance Snapshot</div>
|
||||
<h2 class="section-title">最终验收快照</h2>
|
||||
<div class="table-like">
|
||||
<div class="row"><div class="row-label">端到端链路</div><div class="row-value">从规则中心到 User Agent，再到 Hermes 和 Trace，至少有一条完整演示路径可复现。</div></div>
|
||||
<div class="row"><div class="row-label">证据完整</div><div class="row-value">AgentRun、ToolCall、AuditLog、测试记录、评测结果和演示脚本都存在。</div></div>
|
||||
<div class="row"><div class="row-label">风险边界</div><div class="row-value">MVP 期间不存在绕过人工审核、自动付款、自动上线的暗门路径。</div></div>
|
||||
<div class="row"><div class="row-label">可交接性</div><div class="row-value">下一位开发或 Codex 打开文档就能知道已完成、未完成和生产化前必补项。</div></div>
|
||||
</div>
|
||||
|
||||
<div class="section-kicker">Common Misses</div>
|
||||
<h2 class="section-title">这一天最容易漏掉的点</h2>
|
||||
<ul class="list">
|
||||
<li>只验证 Happy Path，不回归错误态、空态、禁用态和被权限拦截路径。</li>
|
||||
<li>能讲演示，但没有测试记录和已知风险说明，交接质量会很差。</li>
|
||||
<li>前 6 天的 TODO 没回写完成状态，导致页面和 Markdown 脱节。</li>
|
||||
</ul>
|
||||
|
||||
<div class="footer">Day 7 的目标不是继续堆功能，而是把一周产出变成别人也能运行、理解和接手的系统。</div>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -1,181 +0,0 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="zh-CN">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<title>Agent Week Plan HTML</title>
|
||||
<link rel="stylesheet" href="./styles.css">
|
||||
</head>
|
||||
<body>
|
||||
<div class="shell">
|
||||
<div class="topbar">
|
||||
<a class="brand" href="./index.html">
|
||||
<span class="brand-mark">A7</span>
|
||||
<span>Agent Week HTML</span>
|
||||
</a>
|
||||
<div class="quick-links">
|
||||
<a class="pill" href="../agent%20week%20plan/MASTER_TODO.md">周计划总控</a>
|
||||
<a class="pill" href="../agent%20week%20plan/00_README.md">周计划说明</a>
|
||||
<a class="pill" href="../agent%20plan/00_README.md">架构目录</a>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<section class="hero">
|
||||
<div class="hero-badge">Static Map</div>
|
||||
<h1>把 7 天周计划变成可直接浏览的开发视图</h1>
|
||||
<p>这一套 HTML 页面不是替代 Markdown，而是把 <code>agent week plan</code> 和 <code>agent plan</code> 的对应关系收成一个稳定入口。每天的路线图和执行清单现在已经并到同一份 daily 文档里。</p>
|
||||
<div class="hero-meta">
|
||||
<div class="meta-card">
|
||||
<div class="meta-label">阅读顺序</div>
|
||||
<div class="meta-value">先总览，再选 Day，再跳转到具体 Markdown 落地执行。</div>
|
||||
</div>
|
||||
<div class="meta-card">
|
||||
<div class="meta-label">核心视图</div>
|
||||
<div class="meta-value">路线图、执行细则、架构依据三层同时可见。</div>
|
||||
</div>
|
||||
<div class="meta-card">
|
||||
<div class="meta-label">适用对象</div>
|
||||
<div class="meta-value">Codex 开发、后端开发、前端开发、项目 owner、验收人员。</div>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<div class="section-kicker">How To Use</div>
|
||||
<h2 class="section-title">怎么用这套页面</h2>
|
||||
<div class="grid two">
|
||||
<section class="card tone-teal">
|
||||
<h3>Codex 开发视角</h3>
|
||||
<ol class="list">
|
||||
<li>先看今天在哪一天，确认上游依赖和下游交接。</li>
|
||||
<li>用“两层映射”定位：daily 文档看目标和步骤，架构文档看约束。</li>
|
||||
<li>按“推荐开发顺序”推进，不跳天，不跨层乱做。</li>
|
||||
<li>完成后回到原始 Markdown，把 TODO、阻塞、交接更新回文档。</li>
|
||||
</ol>
|
||||
</section>
|
||||
<section class="card tone-warm">
|
||||
<h3>人工开发与验收视角</h3>
|
||||
<ol class="list">
|
||||
<li>先看每一天的“今日定位”，知道这一天到底产出什么。</li>
|
||||
<li>再看“今天必须产出的东西”和“验收快照”，确认完成标准。</li>
|
||||
<li>最后跳转到对应 Markdown，逐条执行或验收。</li>
|
||||
<li>如果发现跨天阻塞，优先回前一天补地基，而不是在当前天临时兜底。</li>
|
||||
</ol>
|
||||
</section>
|
||||
</div>
|
||||
|
||||
<div class="section-kicker">Three Layers</div>
|
||||
<h2 class="section-title">文档结构一眼看清</h2>
|
||||
<div class="grid three">
|
||||
<section class="card">
|
||||
<h3>1. 周计划路线图</h3>
|
||||
<p>定义每天的大方向、交付物和验收门槛。用于排期、对齐和验收。核心入口是 <code>MASTER_TODO.md</code> 和 Day 1 到 Day 7 daily 文档。</p>
|
||||
<div class="card-links">
|
||||
<a class="link-chip" href="../agent%20week%20plan/00_README.md">00_README</a>
|
||||
<a class="link-chip" href="../agent%20week%20plan/MASTER_TODO.md">MASTER_TODO</a>
|
||||
</div>
|
||||
</section>
|
||||
<section class="card">
|
||||
<h3>2. 每日执行清单</h3>
|
||||
<p>每天的开发目标已经拆到对应 daily 文档中的详细执行清单，直接覆盖模型、字段、接口、服务、前端、测试和验收证据。</p>
|
||||
<div class="card-links">
|
||||
<a class="link-chip" href="../agent%20week%20plan/00_README.md">00_README</a>
|
||||
<a class="link-chip" href="../agent%20week%20plan/MASTER_TODO.md">MASTER_TODO</a>
|
||||
</div>
|
||||
</section>
|
||||
<section class="card">
|
||||
<h3>3. 架构依据</h3>
|
||||
<p>提供为什么要这么做、协议怎么定、权限和审计边界是什么。它不直接当 TODO，但所有实现都要受它约束。</p>
|
||||
<div class="card-links">
|
||||
<a class="link-chip" href="../agent%20plan/01_overall_architecture.md">总体架构</a>
|
||||
<a class="link-chip" href="../agent%20plan/02_semantic_ontology.md">语义本体</a>
|
||||
<a class="link-chip" href="../agent%20plan/09_observability_and_trace.md">观测与 Trace</a>
|
||||
</div>
|
||||
</section>
|
||||
</div>
|
||||
|
||||
<div class="section-kicker">Seven Days</div>
|
||||
<h2 class="section-title">7 天总览</h2>
|
||||
<div class="grid two">
|
||||
<section class="card tone-olive">
|
||||
<h3>Day 1 基础模型与工程骨架</h3>
|
||||
<p><strong>当前状态：</strong>已完成（2026-05-11）。先把 Agent 资产、版本、审核、运行日志、审计日志，以及报销 / 应收 / 应付的最小业务数据来源定下来。后面所有能力都站在这一天的模型上。</p>
|
||||
<div class="card-links">
|
||||
<a class="link-chip" href="./day-1.html">打开日视图</a>
|
||||
<a class="link-chip" href="../agent%20week%20plan/day_1_foundation_models.md">周计划</a>
|
||||
<a class="link-chip" href="../agent%20week%20plan/day_1_foundation_models.md">合并文档</a>
|
||||
</div>
|
||||
</section>
|
||||
<section class="card tone-teal">
|
||||
<h3>Day 2 任务规则中心联调</h3>
|
||||
<p>把规则、技能、MCP、任务从静态 UI 拉到真实后端数据。重点是规则 Markdown、版本切换、审核和上线拦截。</p>
|
||||
<div class="card-links">
|
||||
<a class="link-chip" href="./day-2.html">打开日视图</a>
|
||||
<a class="link-chip" href="../agent%20week%20plan/day_2_rule_center_integration.md">周计划</a>
|
||||
<a class="link-chip" href="../agent%20week%20plan/day_2_rule_center_integration.md">合并文档</a>
|
||||
</div>
|
||||
</section>
|
||||
<section class="card tone-warm">
|
||||
<h3>Day 3 语义本体 MVP</h3>
|
||||
<p>建立 8 字段语义解析协议，让报销、应收、应付、知识查询进入同一结构，给 Orchestrator、User Agent、Hermes 统一消费。</p>
|
||||
<div class="card-links">
|
||||
<a class="link-chip" href="./day-3.html">打开日视图</a>
|
||||
<a class="link-chip" href="../agent%20week%20plan/day_3_semantic_ontology_mvp.md">周计划</a>
|
||||
<a class="link-chip" href="../agent%20week%20plan/day_3_semantic_ontology_mvp.md">合并文档</a>
|
||||
</div>
|
||||
</section>
|
||||
<section class="card">
|
||||
<h3>Day 4 Orchestrator 运行时</h3>
|
||||
<p>把用户消息和定时任务统一接到 Orchestrator，完成 run_id、权限拦截、Agent 路由、ToolCall 和 Trace。</p>
|
||||
<div class="card-links">
|
||||
<a class="link-chip" href="./day-4.html">打开日视图</a>
|
||||
<a class="link-chip" href="../agent%20week%20plan/day_4_orchestrator_runtime.md">周计划</a>
|
||||
<a class="link-chip" href="../agent%20week%20plan/day_4_orchestrator_runtime.md">合并文档</a>
|
||||
</div>
|
||||
</section>
|
||||
<section class="card tone-teal">
|
||||
<h3>Day 5 User Agent MVP</h3>
|
||||
<p>面向用户的问答和流程辅助层。做查询、解释、规则引用、草稿生成，但严格不碰自动审批、自动付款和自动上线。</p>
|
||||
<div class="card-links">
|
||||
<a class="link-chip" href="./day-5.html">打开日视图</a>
|
||||
<a class="link-chip" href="../agent%20week%20plan/day_5_user_agent_mvp.md">周计划</a>
|
||||
<a class="link-chip" href="../agent%20week%20plan/day_5_user_agent_mvp.md">合并文档</a>
|
||||
</div>
|
||||
</section>
|
||||
<section class="card tone-olive">
|
||||
<h3>Day 6 Hermes MVP</h3>
|
||||
<p>后台数字员工层。做任务触发、风险巡检、日报统计、OCR Mock、知识候选、规则草稿，结果都必须可追溯。</p>
|
||||
<div class="card-links">
|
||||
<a class="link-chip" href="./day-6.html">打开日视图</a>
|
||||
<a class="link-chip" href="../agent%20week%20plan/day_6_hermes_mvp.md">周计划</a>
|
||||
<a class="link-chip" href="../agent%20week%20plan/day_6_hermes_mvp.md">合并文档</a>
|
||||
</div>
|
||||
</section>
|
||||
<section class="card tone-accent">
|
||||
<h3>Day 7 加固、演示和验收</h3>
|
||||
<p>不再大扩功能，只做回归、权限边界、审计、Trace、测试、演示脚本和交接收口，让整周产出可跑、可演示、可继续接手。</p>
|
||||
<div class="card-links">
|
||||
<a class="link-chip" href="./day-7.html">打开日视图</a>
|
||||
<a class="link-chip" href="../agent%20week%20plan/day_7_hardening_demo_acceptance.md">周计划</a>
|
||||
<a class="link-chip" href="../agent%20week%20plan/day_7_hardening_demo_acceptance.md">合并文档</a>
|
||||
</div>
|
||||
</section>
|
||||
</div>
|
||||
|
||||
<div class="section-kicker">Dependency Chain</div>
|
||||
<h2 class="section-title">跨天依赖链</h2>
|
||||
<div class="timeline">
|
||||
<div class="timeline-step"><strong>Day 1</strong>模型、审计、运行日志、最小业务数据源</div>
|
||||
<div class="timeline-step"><strong>Day 2</strong>把 Day 1 的资产 API 接进规则中心 UI</div>
|
||||
<div class="timeline-step"><strong>Day 3</strong>在 Day 1/2 基础上产出统一语义结构</div>
|
||||
<div class="timeline-step"><strong>Day 4</strong>用 Day 3 的语义结果完成路由与权限</div>
|
||||
<div class="timeline-step"><strong>Day 5</strong>接入 User Agent 问答、解释和草稿</div>
|
||||
<div class="timeline-step"><strong>Day 6</strong>接入 Hermes 任务、巡检和知识/规则候选</div>
|
||||
<div class="timeline-step"><strong>Day 7</strong>统一回归、补日志、做演示和交接</div>
|
||||
</div>
|
||||
|
||||
<div class="footer">
|
||||
打开顺序建议：<a href="./day-1.html">Day 1</a> 到 <a href="./day-7.html">Day 7</a>。真正执行时，仍以原始 Markdown 为准，这套 HTML 负责加速定位和浏览。
|
||||
</div>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -1,426 +0,0 @@
|
||||
:root {
|
||||
--bg: #f3ead9;
|
||||
--bg-deep: #e7d8bc;
|
||||
--panel: rgba(255, 250, 241, 0.9);
|
||||
--panel-strong: #fff8ee;
|
||||
--ink: #1f2a24;
|
||||
--muted: #64655d;
|
||||
--line: #dbc8a9;
|
||||
--accent: #bb5b2c;
|
||||
--accent-strong: #8d3d1b;
|
||||
--accent-soft: #f4d9bf;
|
||||
--teal: #20656d;
|
||||
--teal-soft: #d8ecee;
|
||||
--olive: #5f6b3a;
|
||||
--olive-soft: #e6ecd7;
|
||||
--shadow: 0 24px 60px rgba(84, 59, 30, 0.12);
|
||||
--radius-xl: 28px;
|
||||
--radius-lg: 20px;
|
||||
--radius-md: 14px;
|
||||
--max: 1240px;
|
||||
}
|
||||
|
||||
* {
|
||||
box-sizing: border-box;
|
||||
}
|
||||
|
||||
html {
|
||||
scroll-behavior: smooth;
|
||||
}
|
||||
|
||||
body {
|
||||
margin: 0;
|
||||
font-family: "Trebuchet MS", "Gill Sans", "Lucida Grande", sans-serif;
|
||||
color: var(--ink);
|
||||
background:
|
||||
radial-gradient(circle at top left, rgba(32, 101, 109, 0.14), transparent 26%),
|
||||
radial-gradient(circle at top right, rgba(187, 91, 44, 0.15), transparent 30%),
|
||||
linear-gradient(180deg, #f8f0e2 0%, var(--bg) 40%, #efe2cb 100%);
|
||||
}
|
||||
|
||||
a {
|
||||
color: inherit;
|
||||
}
|
||||
|
||||
.shell {
|
||||
width: min(100% - 40px, var(--max));
|
||||
margin: 0 auto;
|
||||
padding: 28px 0 56px;
|
||||
}
|
||||
|
||||
.topbar {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
justify-content: space-between;
|
||||
gap: 16px;
|
||||
flex-wrap: wrap;
|
||||
margin-bottom: 18px;
|
||||
}
|
||||
|
||||
.brand {
|
||||
display: inline-flex;
|
||||
align-items: center;
|
||||
gap: 12px;
|
||||
text-decoration: none;
|
||||
font-weight: 700;
|
||||
letter-spacing: 0.04em;
|
||||
text-transform: uppercase;
|
||||
color: var(--accent-strong);
|
||||
}
|
||||
|
||||
.brand-mark {
|
||||
display: inline-flex;
|
||||
align-items: center;
|
||||
justify-content: center;
|
||||
width: 42px;
|
||||
height: 42px;
|
||||
border-radius: 50%;
|
||||
background: linear-gradient(135deg, var(--accent), #df9a44);
|
||||
color: #fff7ef;
|
||||
box-shadow: 0 14px 30px rgba(187, 91, 44, 0.28);
|
||||
}
|
||||
|
||||
.quick-links,
|
||||
.day-nav {
|
||||
display: flex;
|
||||
flex-wrap: wrap;
|
||||
gap: 10px;
|
||||
}
|
||||
|
||||
.pill {
|
||||
display: inline-flex;
|
||||
align-items: center;
|
||||
justify-content: center;
|
||||
min-height: 38px;
|
||||
padding: 10px 14px;
|
||||
border-radius: 999px;
|
||||
border: 1px solid rgba(143, 114, 74, 0.22);
|
||||
background: rgba(255, 248, 238, 0.75);
|
||||
text-decoration: none;
|
||||
color: var(--muted);
|
||||
font-size: 14px;
|
||||
transition: transform 180ms ease, border-color 180ms ease, background 180ms ease;
|
||||
}
|
||||
|
||||
.pill:hover,
|
||||
.pill:focus-visible {
|
||||
transform: translateY(-1px);
|
||||
border-color: rgba(187, 91, 44, 0.4);
|
||||
background: rgba(255, 251, 245, 0.96);
|
||||
outline: none;
|
||||
}
|
||||
|
||||
.pill.active {
|
||||
color: #fff6ef;
|
||||
border-color: transparent;
|
||||
background: linear-gradient(135deg, var(--accent-strong), var(--accent));
|
||||
box-shadow: 0 14px 24px rgba(141, 61, 27, 0.24);
|
||||
}
|
||||
|
||||
.hero {
|
||||
position: relative;
|
||||
overflow: hidden;
|
||||
margin-bottom: 22px;
|
||||
padding: 30px;
|
||||
border: 1px solid rgba(128, 109, 82, 0.18);
|
||||
border-radius: var(--radius-xl);
|
||||
background:
|
||||
linear-gradient(135deg, rgba(255, 248, 238, 0.95), rgba(247, 236, 216, 0.88)),
|
||||
var(--panel);
|
||||
box-shadow: var(--shadow);
|
||||
}
|
||||
|
||||
.hero::after {
|
||||
content: "";
|
||||
position: absolute;
|
||||
right: -50px;
|
||||
top: -50px;
|
||||
width: 220px;
|
||||
height: 220px;
|
||||
border-radius: 50%;
|
||||
background: radial-gradient(circle, rgba(32, 101, 109, 0.16), transparent 68%);
|
||||
}
|
||||
|
||||
.hero-badge {
|
||||
display: inline-flex;
|
||||
align-items: center;
|
||||
gap: 8px;
|
||||
margin-bottom: 12px;
|
||||
padding: 7px 12px;
|
||||
border-radius: 999px;
|
||||
background: var(--accent-soft);
|
||||
color: var(--accent-strong);
|
||||
font-size: 13px;
|
||||
font-weight: 700;
|
||||
letter-spacing: 0.05em;
|
||||
text-transform: uppercase;
|
||||
}
|
||||
|
||||
.hero h1 {
|
||||
margin: 0;
|
||||
font-family: "Iowan Old Style", "Palatino Linotype", "Book Antiqua", serif;
|
||||
font-size: clamp(34px, 5vw, 62px);
|
||||
line-height: 1.03;
|
||||
}
|
||||
|
||||
.hero p {
|
||||
max-width: 880px;
|
||||
margin: 14px 0 0;
|
||||
color: var(--muted);
|
||||
font-size: 18px;
|
||||
line-height: 1.65;
|
||||
}
|
||||
|
||||
.hero-meta {
|
||||
display: grid;
|
||||
grid-template-columns: repeat(auto-fit, minmax(180px, 1fr));
|
||||
gap: 14px;
|
||||
margin-top: 20px;
|
||||
}
|
||||
|
||||
.meta-card {
|
||||
padding: 14px 16px;
|
||||
border-radius: var(--radius-md);
|
||||
background: rgba(255, 255, 255, 0.55);
|
||||
border: 1px solid rgba(132, 109, 83, 0.16);
|
||||
}
|
||||
|
||||
.meta-label {
|
||||
margin-bottom: 6px;
|
||||
color: var(--muted);
|
||||
font-size: 12px;
|
||||
font-weight: 700;
|
||||
letter-spacing: 0.08em;
|
||||
text-transform: uppercase;
|
||||
}
|
||||
|
||||
.meta-value {
|
||||
font-size: 16px;
|
||||
line-height: 1.45;
|
||||
}
|
||||
|
||||
.grid {
|
||||
display: grid;
|
||||
gap: 18px;
|
||||
}
|
||||
|
||||
.grid.two {
|
||||
grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
|
||||
}
|
||||
|
||||
.grid.three {
|
||||
grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
|
||||
}
|
||||
|
||||
.card {
|
||||
padding: 22px;
|
||||
border: 1px solid rgba(132, 109, 83, 0.15);
|
||||
border-radius: var(--radius-lg);
|
||||
background: var(--panel);
|
||||
box-shadow: 0 16px 36px rgba(78, 58, 32, 0.08);
|
||||
animation: rise 420ms ease both;
|
||||
}
|
||||
|
||||
.card:nth-child(2) { animation-delay: 60ms; }
|
||||
.card:nth-child(3) { animation-delay: 120ms; }
|
||||
.card:nth-child(4) { animation-delay: 180ms; }
|
||||
.card:nth-child(5) { animation-delay: 240ms; }
|
||||
|
||||
.card h2,
|
||||
.card h3 {
|
||||
margin: 0 0 10px;
|
||||
font-family: "Iowan Old Style", "Palatino Linotype", "Book Antiqua", serif;
|
||||
}
|
||||
|
||||
.card h2 {
|
||||
font-size: 28px;
|
||||
}
|
||||
|
||||
.card h3 {
|
||||
font-size: 22px;
|
||||
}
|
||||
|
||||
.card p {
|
||||
margin: 0;
|
||||
color: var(--muted);
|
||||
line-height: 1.7;
|
||||
}
|
||||
|
||||
.section-title {
|
||||
margin: 28px 0 14px;
|
||||
font-family: "Iowan Old Style", "Palatino Linotype", "Book Antiqua", serif;
|
||||
font-size: 28px;
|
||||
}
|
||||
|
||||
.section-kicker {
|
||||
margin: 30px 0 8px;
|
||||
color: var(--accent-strong);
|
||||
font-size: 13px;
|
||||
font-weight: 700;
|
||||
letter-spacing: 0.08em;
|
||||
text-transform: uppercase;
|
||||
}
|
||||
|
||||
.list,
|
||||
.compact-list {
|
||||
margin: 12px 0 0;
|
||||
padding-left: 18px;
|
||||
color: var(--ink);
|
||||
line-height: 1.72;
|
||||
}
|
||||
|
||||
.compact-list {
|
||||
font-size: 15px;
|
||||
}
|
||||
|
||||
.list li + li,
|
||||
.compact-list li + li {
|
||||
margin-top: 8px;
|
||||
}
|
||||
|
||||
.card-links {
|
||||
display: flex;
|
||||
flex-wrap: wrap;
|
||||
gap: 10px;
|
||||
margin-top: 16px;
|
||||
}
|
||||
|
||||
.link-chip {
|
||||
display: inline-flex;
|
||||
align-items: center;
|
||||
gap: 8px;
|
||||
padding: 10px 13px;
|
||||
border-radius: 999px;
|
||||
background: rgba(255, 255, 255, 0.76);
|
||||
border: 1px solid rgba(132, 109, 83, 0.18);
|
||||
text-decoration: none;
|
||||
font-size: 14px;
|
||||
}
|
||||
|
||||
.tone-warm {
|
||||
background: linear-gradient(180deg, rgba(244, 217, 191, 0.55), rgba(255, 250, 241, 0.9));
|
||||
}
|
||||
|
||||
.tone-teal {
|
||||
background: linear-gradient(180deg, rgba(216, 236, 238, 0.76), rgba(255, 250, 241, 0.92));
|
||||
}
|
||||
|
||||
.tone-olive {
|
||||
background: linear-gradient(180deg, rgba(230, 236, 215, 0.82), rgba(255, 250, 241, 0.92));
|
||||
}
|
||||
|
||||
.tone-accent {
|
||||
background: linear-gradient(160deg, rgba(141, 61, 27, 0.94), rgba(187, 91, 44, 0.92));
|
||||
color: #fff8f1;
|
||||
}
|
||||
|
||||
.tone-accent p,
|
||||
.tone-accent .meta-label,
|
||||
.tone-accent .meta-value,
|
||||
.tone-accent li {
|
||||
color: rgba(255, 248, 241, 0.92);
|
||||
}
|
||||
|
||||
.tone-accent .link-chip,
|
||||
.tone-accent .pill {
|
||||
background: rgba(255, 255, 255, 0.14);
|
||||
border-color: rgba(255, 255, 255, 0.18);
|
||||
color: #fff8f1;
|
||||
}
|
||||
|
||||
.timeline {
|
||||
display: grid;
|
||||
grid-template-columns: repeat(auto-fit, minmax(180px, 1fr));
|
||||
gap: 12px;
|
||||
}
|
||||
|
||||
.timeline-step {
|
||||
position: relative;
|
||||
padding: 16px;
|
||||
border-radius: var(--radius-md);
|
||||
border: 1px solid rgba(132, 109, 83, 0.16);
|
||||
background: rgba(255, 252, 247, 0.84);
|
||||
}
|
||||
|
||||
.timeline-step strong {
|
||||
display: block;
|
||||
margin-bottom: 8px;
|
||||
font-size: 15px;
|
||||
}
|
||||
|
||||
.footer {
|
||||
margin-top: 26px;
|
||||
padding: 20px 4px 0;
|
||||
color: var(--muted);
|
||||
font-size: 14px;
|
||||
}
|
||||
|
||||
.muted {
|
||||
color: var(--muted);
|
||||
}
|
||||
|
||||
.table-like {
|
||||
display: grid;
|
||||
gap: 12px;
|
||||
}
|
||||
|
||||
.row {
|
||||
display: grid;
|
||||
grid-template-columns: minmax(120px, 0.9fr) minmax(0, 2.3fr);
|
||||
gap: 14px;
|
||||
padding: 14px 16px;
|
||||
border-radius: var(--radius-md);
|
||||
border: 1px solid rgba(132, 109, 83, 0.15);
|
||||
background: rgba(255, 255, 255, 0.56);
|
||||
}
|
||||
|
||||
.row-label {
|
||||
font-size: 13px;
|
||||
font-weight: 700;
|
||||
letter-spacing: 0.06em;
|
||||
text-transform: uppercase;
|
||||
color: var(--accent-strong);
|
||||
}
|
||||
|
||||
.row-value {
|
||||
line-height: 1.68;
|
||||
}
|
||||
|
||||
code {
|
||||
padding: 1px 6px;
|
||||
border-radius: 8px;
|
||||
background: rgba(32, 101, 109, 0.08);
|
||||
color: var(--teal);
|
||||
font-family: "Lucida Console", "Courier New", monospace;
|
||||
font-size: 0.92em;
|
||||
}
|
||||
|
||||
@keyframes rise {
|
||||
from {
|
||||
opacity: 0;
|
||||
transform: translateY(10px);
|
||||
}
|
||||
to {
|
||||
opacity: 1;
|
||||
transform: translateY(0);
|
||||
}
|
||||
}
|
||||
|
||||
@media (max-width: 760px) {
|
||||
.shell {
|
||||
width: min(100% - 24px, var(--max));
|
||||
padding-top: 18px;
|
||||
}
|
||||
|
||||
.hero {
|
||||
padding: 22px;
|
||||
}
|
||||
|
||||
.hero p {
|
||||
font-size: 16px;
|
||||
}
|
||||
|
||||
.row {
|
||||
grid-template-columns: 1fr;
|
||||
}
|
||||
}
|
||||
@@ -1,44 +0,0 @@
|
||||
# Backend API Swagger 文档
|
||||
|
||||
本目录用于沉淀后端接口的 Swagger / OpenAPI 产物，给开发、联调和后续 Agent 接口调用统一对照。
|
||||
|
||||
## 目录说明
|
||||
|
||||
- `openapi.json`
|
||||
- 由 FastAPI `app.openapi()` 导出的完整 OpenAPI 规范。
|
||||
- `interface_inventory.md`
|
||||
- 基于 OpenAPI 自动整理的接口清单，按 tag 分组查看方法、路径和摘要。
|
||||
|
||||
## 在线入口
|
||||
|
||||
- Swagger UI：`/docs`
|
||||
- ReDoc：`/redoc`
|
||||
- OpenAPI JSON：`/openapi.json`
|
||||
|
||||
如果本地默认端口不变，完整地址通常是：
|
||||
|
||||
- `http://127.0.0.1:8000/docs`
|
||||
- `http://127.0.0.1:8000/redoc`
|
||||
- `http://127.0.0.1:8000/openapi.json`
|
||||
|
||||
## 重新生成
|
||||
|
||||
在 `/app/server` 下执行：
|
||||
|
||||
```bash
|
||||
PYTHONPATH=/app/server/src /app/server/.venv/bin/python /app/server/scripts/export_openapi.py
|
||||
```
|
||||
|
||||
## 当前约定
|
||||
|
||||
- 全部业务接口前缀：`/api/v1`
|
||||
- 知识库接口使用请求头模拟登录用户：
|
||||
- `X-Auth-Username`
|
||||
- `X-Auth-Name`
|
||||
- `X-Auth-Role-Codes`
|
||||
- `X-Auth-Is-Admin`
|
||||
- Agent 资产写接口支持审计头：
|
||||
- `X-Actor`
|
||||
- `X-Request-Id`
|
||||
- Hermes 运行时模型接口使用：
|
||||
- `Authorization: Bearer <HERMES_AGENT_SHARED_TOKEN>`
|
||||
@@ -1,100 +0,0 @@
|
||||
# Backend API Interface Inventory
|
||||
|
||||
- Generated at: `2026-05-11 04:14:05 UTC`
|
||||
- API title: `X-Financial`
|
||||
- API version: `0.1.0`
|
||||
- Total paths: `28`
|
||||
|
||||
## Tag Overview
|
||||
|
||||
### agent-assets
|
||||
|
||||
| Method | Path | Summary |
|
||||
| --- | --- | --- |
|
||||
| `GET` | `/api/v1/agent-assets` | 查询 Agent 资产列表 |
|
||||
| `POST` | `/api/v1/agent-assets` | 创建 Agent 资产 |
|
||||
| `GET` | `/api/v1/agent-assets/{asset_id}` | 读取 Agent 资产详情 |
|
||||
| `PATCH` | `/api/v1/agent-assets/{asset_id}` | 更新 Agent 资产 |
|
||||
| `POST` | `/api/v1/agent-assets/{asset_id}/activate` | 激活资产当前版本 |
|
||||
| `POST` | `/api/v1/agent-assets/{asset_id}/reviews` | 创建资产审核记录 |
|
||||
| `GET` | `/api/v1/agent-assets/{asset_id}/versions` | 查询资产版本列表 |
|
||||
| `POST` | `/api/v1/agent-assets/{asset_id}/versions` | 创建资产版本 |
|
||||
|
||||
### agent-runs
|
||||
|
||||
| Method | Path | Summary |
|
||||
| --- | --- | --- |
|
||||
| `GET` | `/api/v1/agent-runs` | 查询 Agent 运行日志 |
|
||||
| `GET` | `/api/v1/agent-runs/{run_id}` | 读取单次 Agent 运行详情 |
|
||||
|
||||
### audit-logs
|
||||
|
||||
| Method | Path | Summary |
|
||||
| --- | --- | --- |
|
||||
| `GET` | `/api/v1/audit-logs` | 查询审计日志 |
|
||||
|
||||
### auth
|
||||
|
||||
| Method | Path | Summary |
|
||||
| --- | --- | --- |
|
||||
| `POST` | `/api/v1/auth/login` | 用户登录 |
|
||||
|
||||
### bootstrap
|
||||
|
||||
| Method | Path | Summary |
|
||||
| --- | --- | --- |
|
||||
| `GET` | `/api/v1/bootstrap` | 读取初始化状态 |
|
||||
| `POST` | `/api/v1/bootstrap` | 写入初始化配置 |
|
||||
|
||||
### employees
|
||||
|
||||
| Method | Path | Summary |
|
||||
| --- | --- | --- |
|
||||
| `GET` | `/api/v1/employees` | 查询员工列表 |
|
||||
| `POST` | `/api/v1/employees` | 创建员工 |
|
||||
| `GET` | `/api/v1/employees/meta` | 读取员工目录元数据 |
|
||||
| `GET` | `/api/v1/employees/{employee_id}` | 读取员工详情 |
|
||||
| `PATCH` | `/api/v1/employees/{employee_id}` | 更新员工 |
|
||||
| `POST` | `/api/v1/employees/{employee_id}/disable` | 停用员工 |
|
||||
|
||||
### health
|
||||
|
||||
| Method | Path | Summary |
|
||||
| --- | --- | --- |
|
||||
| `GET` | `/api/v1/health` | 服务健康检查 |
|
||||
|
||||
### knowledge
|
||||
|
||||
| Method | Path | Summary |
|
||||
| --- | --- | --- |
|
||||
| `POST` | `/api/v1/knowledge/documents` | 上传知识库文档 |
|
||||
| `DELETE` | `/api/v1/knowledge/documents/{document_id}` | 删除知识库文档 |
|
||||
| `GET` | `/api/v1/knowledge/documents/{document_id}` | 读取知识库文档详情 |
|
||||
| `GET` | `/api/v1/knowledge/documents/{document_id}/content` | 下载或预览知识库原文 |
|
||||
| `GET` | `/api/v1/knowledge/documents/{document_id}/onlyoffice-config` | 读取 ONLYOFFICE 预览配置 |
|
||||
| `POST` | `/api/v1/knowledge/documents/{document_id}/onlyoffice/callback` | 接收 ONLYOFFICE 回调 |
|
||||
| `GET` | `/api/v1/knowledge/documents/{document_id}/onlyoffice/content` | 读取 ONLYOFFICE 文档源文件 |
|
||||
| `GET` | `/api/v1/knowledge/library` | 查询知识库目录 |
|
||||
|
||||
### reimbursements
|
||||
|
||||
| Method | Path | Summary |
|
||||
| --- | --- | --- |
|
||||
| `GET` | `/api/v1/reimbursements` | 查询报销申请列表 |
|
||||
| `POST` | `/api/v1/reimbursements` | 创建报销申请 |
|
||||
| `GET` | `/api/v1/reimbursements/{request_id}` | 读取报销申请详情 |
|
||||
|
||||
### root
|
||||
|
||||
| Method | Path | Summary |
|
||||
| --- | --- | --- |
|
||||
| `GET` | `/` | 服务根检查 |
|
||||
|
||||
### settings
|
||||
|
||||
| Method | Path | Summary |
|
||||
| --- | --- | --- |
|
||||
| `GET` | `/api/v1/settings` | 读取系统设置 |
|
||||
| `PUT` | `/api/v1/settings` | 保存系统设置 |
|
||||
| `POST` | `/api/v1/settings/model-connectivity` | 测试模型连通性 |
|
||||
| `GET` | `/api/v1/settings/runtime-models/{slot}` | 读取 Hermes 运行时模型配置 |
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,60 +0,0 @@
|
||||
# 预算中心 MASTER TODO
|
||||
|
||||
## 总目标
|
||||
|
||||
把预算从首页静态展示升级为真实费控底座，让费用申请和报销都必须经过预算口径校验。
|
||||
|
||||
## 状态图
|
||||
|
||||
```text
|
||||
预算额度
|
||||
-> 申请提交: 预占
|
||||
-> 申请退回/撤回/驳回: 释放
|
||||
-> 申请通过: 保持预占
|
||||
-> 报销提交: 校验申请与预算
|
||||
-> 报销审批通过: 核销
|
||||
-> 报销退回/撤回: 释放或回滚
|
||||
```
|
||||
|
||||
## 总 TODO
|
||||
|
||||
- [ ] 新增预算中心开发文档并纳入每日核对。
|
||||
- [ ] 定义预算维度：部门、成本中心、项目、费用科目、期间。
|
||||
- [ ] 定义预算模型：预算额度、预算交易、预算占用。
|
||||
- [ ] 定义预算状态：正常、预警、超预算、冻结。
|
||||
- [ ] 定义预算交易类型：初始化、调整、预占、释放、核销、回滚。
|
||||
- [ ] 新增预算列表接口。
|
||||
- [ ] 新增预算详情接口。
|
||||
- [ ] 新增预算台账接口。
|
||||
- [ ] 新增预算占用接口或内部服务。
|
||||
- [ ] 新增预算释放接口或内部服务。
|
||||
- [ ] 新增预算核销接口或内部服务。
|
||||
- [ ] 费用申请提交时写入预算预占。
|
||||
- [ ] 费用申请驳回、撤回、取消时释放预算。
|
||||
- [ ] 费用申请转报销时保留预算来源。
|
||||
- [ ] 报销提交时校验预算归属和可用余额。
|
||||
- [ ] 报销审批通过时核销预算。
|
||||
- [ ] 报销退回时回滚预算状态。
|
||||
- [ ] 报销详情展示预算占用和核销信息。
|
||||
- [ ] 申请详情展示预算占用和剩余额度。
|
||||
- [ ] 预算中心页面展示执行率、已占用、已核销、可用余额。
|
||||
- [ ] 预算台账展示每笔来源单据和交易类型。
|
||||
- [ ] 首页预算执行率改为后端真实数据。
|
||||
- [ ] 本体识别支持预算维度字段。
|
||||
- [ ] AI对话能解释预算不足、预算归属缺失、超预算原因。
|
||||
- [ ] 添加后端单元测试。
|
||||
- [ ] 添加前端预算视图测试。
|
||||
- [ ] 添加申请到报销的端到端预算验收场景。
|
||||
|
||||
## 验收场景
|
||||
|
||||
- [ ] 有预算时，费用申请提交成功并预占预算。
|
||||
- [ ] 预算不足时，申请提交被阻断或进入超预算复核。
|
||||
- [ ] 申请驳回后，预算预占被释放。
|
||||
- [ ] 申请审批通过后，预算仍保持预占。
|
||||
- [ ] 申请转报销后，报销单继承预算来源。
|
||||
- [ ] 报销审批通过后，预算从预占转为核销。
|
||||
- [ ] 报销退回后，预算核销回滚。
|
||||
- [ ] 预算中心能看到完整交易台账。
|
||||
- [ ] 首页预算执行率与预算中心汇总一致。
|
||||
|
||||
@@ -1,58 +0,0 @@
|
||||
# 预算中心开发总览
|
||||
|
||||
## 目标
|
||||
|
||||
预算中心先作为费控平台的前置底座建设，优先打通：
|
||||
|
||||
```text
|
||||
预算编制 -> 预算可用额度 -> 费用申请预占 -> 报销核销 -> 释放/调整 -> 预算看板
|
||||
```
|
||||
|
||||
第一版不追求完整预算编制系统，而是先让申请、报销、审批、付款、归档都有真实预算口径。
|
||||
|
||||
## 当前项目基础
|
||||
|
||||
- 员工和组织已有 `cost_center` 成本中心字段，可作为预算归属维度。
|
||||
- 报销单已有部门、项目、费用类型、金额、状态等字段，可接入预算核销。
|
||||
- 首页已有静态预算执行率展示，但还不是后端真实预算数据。
|
||||
- 费用申请已有前端意图识别和申请草稿痕迹，但预算占用还没有真实台账。
|
||||
|
||||
## 第一版预算中心范围
|
||||
|
||||
必须做：
|
||||
|
||||
- 预算主体：部门、成本中心、项目、费用科目。
|
||||
- 预算期间：月度、季度、年度。
|
||||
- 预算额度：总额、已占用、已核销、已释放、可用余额。
|
||||
- 预算台账：每一次占用、核销、释放、调整都落账。
|
||||
- 申请联动：费用申请提交时预占预算，驳回/撤回时释放。
|
||||
- 报销联动：报销提交或审批通过时核销预算。
|
||||
- 风险拦截：预算不足、超预算、缺预算归属时阻断或进入复核。
|
||||
- 预算中心页面：列表、详情、台账、执行率、异常预算。
|
||||
|
||||
暂缓：
|
||||
|
||||
- 完整预算编制审批流。
|
||||
- 多版本预算测算。
|
||||
- 外部 ERP 预算接口。
|
||||
- 真正多币种预算。
|
||||
- 复杂滚动预算和预测模型。
|
||||
|
||||
## 关键原则
|
||||
|
||||
- 预算中心是独立业务域，不塞进报销 Service。
|
||||
- 所有预算变化必须通过预算交易台账记录。
|
||||
- 不直接改写已用金额，必须由交易汇总得到。
|
||||
- 申请、报销、付款只是预算事件来源。
|
||||
- 预算不足的判断必须来自后端，不依赖前端显示。
|
||||
|
||||
## 7天开发路径
|
||||
|
||||
- Day 1：预算模型、状态机、接口契约。
|
||||
- Day 2：预算中心页面、列表、详情、台账视图。
|
||||
- Day 3：预算占用/释放/核销服务。
|
||||
- Day 4：费用申请与报销联动预算。
|
||||
- Day 5：审批、付款、归档中的预算状态传递。
|
||||
- Day 6：预算看板、本体识别、AI提示。
|
||||
- Day 7：端到端验收、演示数据、测试补齐。
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,105 +0,0 @@
|
||||
# Day 1 - 预算模型与接口契约
|
||||
|
||||
## 目标
|
||||
|
||||
先把预算中心的数据边界和接口边界定稳，避免后续把预算逻辑散落在申请、报销、审批和付款模块里。
|
||||
|
||||
## 开发任务
|
||||
|
||||
- [ ] 新增预算模型设计。
|
||||
- [ ] 新增预算交易台账设计。
|
||||
- [ ] 新增预算服务边界设计。
|
||||
- [ ] 新增预算接口契约。
|
||||
- [ ] 新增预算状态与交易类型常量。
|
||||
- [ ] 明确申请、报销、付款对预算服务的调用点。
|
||||
|
||||
## 建议模型
|
||||
|
||||
预算额度：
|
||||
|
||||
```text
|
||||
BudgetAllocation
|
||||
- id
|
||||
- budget_no
|
||||
- fiscal_year
|
||||
- period_type
|
||||
- period_key
|
||||
- department_id
|
||||
- department_name
|
||||
- cost_center
|
||||
- project_code
|
||||
- subject_code
|
||||
- subject_name
|
||||
- original_amount
|
||||
- adjusted_amount
|
||||
- status
|
||||
- warning_threshold
|
||||
- created_at
|
||||
- updated_at
|
||||
```
|
||||
|
||||
预算交易：
|
||||
|
||||
```text
|
||||
BudgetTransaction
|
||||
- id
|
||||
- transaction_no
|
||||
- allocation_id
|
||||
- source_type
|
||||
- source_id
|
||||
- source_no
|
||||
- transaction_type
|
||||
- amount
|
||||
- before_available_amount
|
||||
- after_available_amount
|
||||
- operator
|
||||
- reason
|
||||
- created_at
|
||||
```
|
||||
|
||||
交易类型：
|
||||
|
||||
```text
|
||||
init 初始化
|
||||
adjust 调整
|
||||
reserve 预占
|
||||
release 释放
|
||||
consume 核销
|
||||
rollback 回滚
|
||||
freeze 冻结
|
||||
unfreeze 解冻
|
||||
```
|
||||
|
||||
预算汇总字段由交易汇总得到：
|
||||
|
||||
```text
|
||||
total_amount = original_amount + adjusted_amount
|
||||
reserved_amount = reserve - release
|
||||
consumed_amount = consume - rollback
|
||||
available_amount = total_amount - reserved_amount - consumed_amount
|
||||
```
|
||||
|
||||
## 接口契约
|
||||
|
||||
```text
|
||||
GET /api/v1/budgets/allocations
|
||||
POST /api/v1/budgets/allocations
|
||||
GET /api/v1/budgets/allocations/{id}
|
||||
GET /api/v1/budgets/allocations/{id}/transactions
|
||||
POST /api/v1/budgets/allocations/{id}/adjust
|
||||
POST /api/v1/budgets/check
|
||||
POST /api/v1/budgets/reserve
|
||||
POST /api/v1/budgets/release
|
||||
POST /api/v1/budgets/consume
|
||||
POST /api/v1/budgets/rollback
|
||||
GET /api/v1/budgets/summary
|
||||
```
|
||||
|
||||
## 验收
|
||||
|
||||
- [ ] 能创建一条部门月度预算。
|
||||
- [ ] 能查询预算列表和详情。
|
||||
- [ ] 能查询预算台账。
|
||||
- [ ] 能根据部门、成本中心、项目、费用科目定位预算。
|
||||
- [ ] 预算不足时 `check` 接口能返回明确原因。
|
||||
|
||||
@@ -1,82 +0,0 @@
|
||||
# Day 2 - 预算中心页面
|
||||
|
||||
## 目标
|
||||
|
||||
新增预算中心作为独立主菜单，让预算不再只是首页指标，而是可操作、可追踪、可解释的费控入口。
|
||||
|
||||
## 页面入口
|
||||
|
||||
主菜单建议：
|
||||
|
||||
```text
|
||||
费用申请
|
||||
报销中心
|
||||
审批中心
|
||||
预算中心
|
||||
付款中心
|
||||
归档中心
|
||||
经营分析
|
||||
```
|
||||
|
||||
## 页面结构
|
||||
|
||||
顶部指标：
|
||||
|
||||
- 预算总额
|
||||
- 已预占
|
||||
- 已核销
|
||||
- 可用余额
|
||||
- 超预算事项
|
||||
- 预警预算数
|
||||
|
||||
列表字段：
|
||||
|
||||
- 预算编号
|
||||
- 预算期间
|
||||
- 部门
|
||||
- 成本中心
|
||||
- 项目
|
||||
- 费用科目
|
||||
- 预算总额
|
||||
- 已预占
|
||||
- 已核销
|
||||
- 可用余额
|
||||
- 执行率
|
||||
- 状态
|
||||
|
||||
筛选条件：
|
||||
|
||||
- 年度
|
||||
- 月份/季度
|
||||
- 部门
|
||||
- 成本中心
|
||||
- 项目
|
||||
- 费用科目
|
||||
- 状态
|
||||
|
||||
详情页：
|
||||
|
||||
- 基本信息
|
||||
- 执行概览
|
||||
- 来源单据
|
||||
- 交易台账
|
||||
- 风险提示
|
||||
- 调整记录
|
||||
|
||||
## 操作
|
||||
|
||||
- 新增预算
|
||||
- 调整预算
|
||||
- 冻结预算
|
||||
- 查看台账
|
||||
- 查看关联申请
|
||||
- 查看关联报销
|
||||
|
||||
## 验收
|
||||
|
||||
- [ ] 预算中心能从主菜单进入。
|
||||
- [ ] 列表能展示后端预算数据。
|
||||
- [ ] 点击预算能进入详情。
|
||||
- [ ] 详情能展示交易台账。
|
||||
- [ ] 首页预算执行率能跳转到预算中心。
|
||||
|
||||
@@ -1,55 +0,0 @@
|
||||
# Day 3 - 预算占用、释放、核销服务
|
||||
|
||||
## 目标
|
||||
|
||||
把预算变化统一收敛到预算服务，申请、报销、付款都只能通过预算服务改变预算状态。
|
||||
|
||||
## 服务能力
|
||||
|
||||
预算检查：
|
||||
|
||||
- 校验预算归属是否存在。
|
||||
- 校验预算是否被冻结。
|
||||
- 校验可用余额是否充足。
|
||||
- 返回超预算金额和处理建议。
|
||||
|
||||
预算预占：
|
||||
|
||||
- 用于费用申请提交。
|
||||
- 写入 `reserve` 交易。
|
||||
- 记录来源单据。
|
||||
|
||||
预算释放：
|
||||
|
||||
- 用于申请撤回、退回、驳回、取消。
|
||||
- 写入 `release` 交易。
|
||||
- 必须找到原始预占来源。
|
||||
|
||||
预算核销：
|
||||
|
||||
- 用于报销审批通过。
|
||||
- 写入 `consume` 交易。
|
||||
- 如果来源申请已有预占，应先释放预占或转换为核销，不能重复占用。
|
||||
|
||||
预算回滚：
|
||||
|
||||
- 用于报销退回或撤销审批。
|
||||
- 写入 `rollback` 交易。
|
||||
|
||||
## 关键防错
|
||||
|
||||
- 同一来源单据不能重复预占。
|
||||
- 同一报销单不能重复核销。
|
||||
- 释放金额不能超过原预占金额。
|
||||
- 核销金额不能超过可用余额加当前来源预占余额。
|
||||
- 所有预算交易必须有来源单据和操作人。
|
||||
|
||||
## 验收
|
||||
|
||||
- [ ] 预算预占后可用余额减少。
|
||||
- [ ] 预算释放后可用余额恢复。
|
||||
- [ ] 预算核销后已核销金额增加。
|
||||
- [ ] 重复预占会被阻断。
|
||||
- [ ] 重复核销会被阻断。
|
||||
- [ ] 台账能解释每一次余额变化。
|
||||
|
||||
@@ -1,58 +0,0 @@
|
||||
# Day 4 - 费用申请与报销联动预算
|
||||
|
||||
## 目标
|
||||
|
||||
让预算成为申请和报销之间的硬约束，先申请、再占用、再报销、再核销。
|
||||
|
||||
## 费用申请联动
|
||||
|
||||
提交申请时：
|
||||
|
||||
- 根据申请人部门、成本中心、项目、费用科目定位预算。
|
||||
- 预算充足则预占。
|
||||
- 预算不足则阻断或进入超预算复核。
|
||||
- 申请详情展示预算占用结果。
|
||||
|
||||
申请退回/驳回/撤回时：
|
||||
|
||||
- 释放对应预算预占。
|
||||
- 记录释放原因。
|
||||
|
||||
申请审批通过时：
|
||||
|
||||
- 保持预算预占。
|
||||
- 允许转报销。
|
||||
|
||||
申请转报销时：
|
||||
|
||||
- 报销单继承申请预算来源。
|
||||
- 报销金额默认不超过申请金额。
|
||||
- 超过申请金额时进入风险提示或复核。
|
||||
|
||||
## 报销联动
|
||||
|
||||
报销提交时：
|
||||
|
||||
- 校验是否需要事前申请。
|
||||
- 校验是否有关联已通过申请。
|
||||
- 校验预算来源是否存在。
|
||||
|
||||
报销审批通过时：
|
||||
|
||||
- 将预算预占转为核销。
|
||||
- 记录核销台账。
|
||||
|
||||
报销退回时：
|
||||
|
||||
- 回滚核销。
|
||||
- 视状态保留或释放预占。
|
||||
|
||||
## 验收
|
||||
|
||||
- [ ] 有预算的申请提交后形成预占。
|
||||
- [ ] 预算不足的申请不能直接提交。
|
||||
- [ ] 驳回申请释放预算。
|
||||
- [ ] 已通过申请能转报销。
|
||||
- [ ] 报销审批通过后预算转核销。
|
||||
- [ ] 未关联预算的报销不能绕过预算校验。
|
||||
|
||||
@@ -1,52 +0,0 @@
|
||||
# Day 5 - 审批、付款、归档中的预算口径
|
||||
|
||||
## 目标
|
||||
|
||||
预算信息不能只停留在申请和报销页面，还要贯穿审批、付款和归档。
|
||||
|
||||
## 审批中心
|
||||
|
||||
审批列表增加预算提示：
|
||||
|
||||
- 是否预算内
|
||||
- 是否超预算
|
||||
- 已预占金额
|
||||
- 可用余额
|
||||
- 预算归属
|
||||
|
||||
审批详情增加预算区块：
|
||||
|
||||
- 当前单据金额
|
||||
- 对应预算额度
|
||||
- 已预占
|
||||
- 已核销
|
||||
- 剩余额度
|
||||
- 超预算原因
|
||||
|
||||
## 付款中心预留
|
||||
|
||||
第一版付款中心可以暂缓实现完整页面，但预算中心需要为付款预留：
|
||||
|
||||
- 付款来源单据
|
||||
- 付款金额
|
||||
- 付款状态
|
||||
- 是否已核销预算
|
||||
- 是否存在预算异常
|
||||
|
||||
## 归档中心
|
||||
|
||||
归档包需要包含预算信息：
|
||||
|
||||
- 预算归属
|
||||
- 预算交易流水
|
||||
- 申请预占记录
|
||||
- 报销核销记录
|
||||
- 超预算审批意见
|
||||
|
||||
## 验收
|
||||
|
||||
- [ ] 审批人能看到预算是否充足。
|
||||
- [ ] 超预算审批能看到超额金额。
|
||||
- [ ] 归档详情能看到预算台账摘要。
|
||||
- [ ] 预算异常不会在付款/归档阶段丢失。
|
||||
|
||||
@@ -1,90 +0,0 @@
|
||||
# Day 6 - 预算看板、本体识别与AI解释
|
||||
|
||||
## 目标
|
||||
|
||||
让预算中心不只是数据表，还能被 AI 对话、本体识别和经营分析调用。
|
||||
|
||||
## 看板指标
|
||||
|
||||
- 本月预算总额
|
||||
- 本月已预占
|
||||
- 本月已核销
|
||||
- 本月可用余额
|
||||
- 部门预算排行
|
||||
- 费用科目执行率
|
||||
- 超预算事项数量
|
||||
- 预算预警事项数量
|
||||
|
||||
## 本体字段
|
||||
|
||||
新增或强化字段：
|
||||
|
||||
```text
|
||||
cost_center
|
||||
project_code
|
||||
budget_subject
|
||||
budget_period
|
||||
budget_amount
|
||||
available_amount
|
||||
reserved_amount
|
||||
consumed_amount
|
||||
over_budget
|
||||
budget_warning
|
||||
```
|
||||
|
||||
## 预算字段设计
|
||||
|
||||
预算中心字段分为四层，前端弹窗、预算台账、后端本体解析都必须使用同一套语义键。
|
||||
|
||||
### 预算主信息
|
||||
|
||||
- `budget_period`：预算周期，支持年度、季度、月份。
|
||||
- `department`：所属部门，来自真实组织/部门数据。
|
||||
- `cost_center`：成本中心，跟随部门归属。
|
||||
- `budget_owner`：预算负责人。
|
||||
- `budget_version`：预算版本，例如 `V1.0（初始版本）`。
|
||||
- `budget_status`：预算状态，第一版限定为 `编制中 / 已发布 / 已冻结`。
|
||||
- `budget_description`：预算说明。
|
||||
|
||||
### 预算明细
|
||||
|
||||
- `budget_subject`：预算科目，对应页面费用类型。
|
||||
- `budget_subject_code`：预算科目编码，例如 `travel / office / training`。
|
||||
- `budget_amount`：预算金额。
|
||||
- `warning_threshold`：预警线，例如 `70% / 80%`。
|
||||
- `control_action`：控制动作，第一版限定为 `正常 / 提醒 / 管控`。
|
||||
- `budget_remark`：明细备注。
|
||||
|
||||
### 预算执行
|
||||
|
||||
- `reserved_amount`：已占用/已预占金额。
|
||||
- `consumed_amount`：已发生/已核销金额。
|
||||
- `available_amount`：剩余可用金额。
|
||||
- `budget_usage_rate`：预算执行率。
|
||||
- `over_budget`：是否超预算。
|
||||
- `budget_warning`：是否触发预算预警。
|
||||
|
||||
### 本体映射规则
|
||||
|
||||
- 页面字段使用驼峰变量，但提交/上下文统一映射为 snake_case 本体字段。
|
||||
- 本体 `scenario=budget` 负责预算编制、预算查询、预算预警、预算占用、预算不足解释。
|
||||
- 费用申请/报销仍使用 `scenario=expense`，但预算占用字段必须引用 `budget_subject / budget_period / cost_center`。
|
||||
- 问句中出现“预算金额、可用预算、剩余预算、预算占用、成本中心、预警线、超预算、预算不足”等词，应优先识别为 `budget` 场景。
|
||||
- 本体输出中，预算字段优先进入 `entities`；金额类查询同步进入 `metrics`；筛选口径进入 `constraints`。
|
||||
|
||||
## AI解释能力
|
||||
|
||||
需要支持的问题：
|
||||
|
||||
- 这个申请为什么预算不足？
|
||||
- 这个报销占用了哪个预算？
|
||||
- 本月哪个部门预算快超了？
|
||||
- 某个项目还剩多少预算？
|
||||
- 超预算申请需要谁审批？
|
||||
|
||||
## 验收
|
||||
|
||||
- [ ] 本体能识别预算相关问题。
|
||||
- [ ] AI能解释预算不足原因。
|
||||
- [ ] 首页预算看板来自后端真实汇总。
|
||||
- [ ] 预算中心和AI回答的金额一致。
|
||||
@@ -1,64 +0,0 @@
|
||||
# Day 7 - 联调、测试与演示验收
|
||||
|
||||
## 目标
|
||||
|
||||
冻结新增需求，只修预算闭环缺口，确保演示链路稳定。
|
||||
|
||||
## 端到端验收链路
|
||||
|
||||
链路一：预算内申请到报销
|
||||
|
||||
```text
|
||||
创建预算 -> 发起费用申请 -> 预占预算 -> 审批通过
|
||||
-> 转报销 -> 报销审批通过 -> 核销预算 -> 归档
|
||||
```
|
||||
|
||||
链路二：预算不足
|
||||
|
||||
```text
|
||||
创建低额度预算 -> 发起高金额申请 -> 预算不足
|
||||
-> 阻断提交或进入超预算复核 -> 审批意见留痕
|
||||
```
|
||||
|
||||
链路三：申请驳回释放预算
|
||||
|
||||
```text
|
||||
申请提交 -> 预算预占 -> 审批驳回 -> 预算释放 -> 台账可追溯
|
||||
```
|
||||
|
||||
链路四：重复操作防护
|
||||
|
||||
```text
|
||||
重复提交 / 重复审批 / 重复核销 -> 后端阻断 -> 台账不重复
|
||||
```
|
||||
|
||||
## 测试要求
|
||||
|
||||
- [ ] 后端预算服务单元测试。
|
||||
- [ ] 申请预算预占测试。
|
||||
- [ ] 报销预算核销测试。
|
||||
- [ ] 预算不足阻断测试。
|
||||
- [ ] 前端预算中心列表测试。
|
||||
- [ ] 前端预算详情台账测试。
|
||||
- [ ] 首页预算汇总测试。
|
||||
|
||||
## 演示数据
|
||||
|
||||
至少准备：
|
||||
|
||||
- 一个预算充足的部门预算。
|
||||
- 一个预算不足的部门预算。
|
||||
- 一个项目预算。
|
||||
- 一个会议培训大额预算。
|
||||
- 一个已经预占的申请。
|
||||
- 一个已经核销的报销。
|
||||
- 一个超预算待审批事项。
|
||||
|
||||
## 最终验收
|
||||
|
||||
- [ ] 预算中心能解释每一分钱从哪里来、到哪里去。
|
||||
- [ ] 费用申请不能绕过预算。
|
||||
- [ ] 报销审批不能绕过预算。
|
||||
- [ ] 审批、归档、看板显示同一套预算数据。
|
||||
- [ ] 演示链路可连续跑通。
|
||||
|
||||
@@ -623,6 +623,14 @@ $$
|
||||
|
||||
AI 协作、审批效率和审批把关默认放在运营视图或管理员视图中展示。审批详情如需展示，必须明确标注“不参与费用风险裁决”。
|
||||
|
||||
个人工作台的用户画像详情允许在行为雷达右上角提供视角切换，避免把不同性质的指标混成单一结论：
|
||||
|
||||
- `financial_risk` / 财务风险视角：默认面向普通员工画像，展示费用强度、申请节奏、差旅招待、材料完整度压力、流程压力。
|
||||
- `collaboration_governance` / 协作治理视角：展示 AI 协作强度、审批效率特征、审批把关特征，用于管理员或运营人员查看系统协作和流程治理行为。
|
||||
- `all_behavior` / 全部行为视角：展示全部雷达维度，满足用户查看完整操作和行为细节的需求。
|
||||
|
||||
切换只改变雷达图可视维度和雷达下方的行为标签过滤结果，不改变后端画像快照、上方画像标签总列表、标签证据和审批优先级分。审批详情的“风险审核画像”仍默认只展示费用审核相关维度。
|
||||
|
||||
## 8. 测试方案
|
||||
|
||||
- 单元测试：覆盖归一化、同组降级、四类画像评分、等级映射、审核建议生成。
|
||||
|
||||
@@ -142,3 +142,12 @@ docker exec x-financial-main bash -lc "cd /app && timeout 60s npm --prefix web r
|
||||
- [x] 新增前端构建或组件测试，确认标签和雷达图在正常态、空态、低样本态下展示稳定。[CONCEPT: 前端展示] 证据：`npm --prefix web run build` 通过。
|
||||
- [x] 后端验证在 Docker 容器执行，命令设置 60s 超时。[CONCEPT: 测试方案] 证据：`pytest ... -q` 结果 `9 passed in 6.20s`，Ruff `All checks passed!`。
|
||||
- [ ] 前端验证通过后补充截图或交互验证说明，并回勾阶段 9 未完成项。[CONCEPT: 指标与验收]
|
||||
|
||||
## 阶段 12：个人画像雷达视角切换
|
||||
|
||||
- [x] 在 `CONCEPT.md` 补充个人画像详情的雷达视角切换契约，明确财务风险、协作治理、全部行为三档。[CONCEPT: 行为雷达图] 证据：`CONCEPT.md` 7.10 已补充三档视角和边界。
|
||||
- [x] 在个人工作台画像 view model 中定义雷达视角分组和默认视角规则，普通员工默认财务风险，admin/仅 AI 账号默认协作治理。[CONCEPT: 行为雷达图] 证据：`employeeProfileViewModel.js` 新增 `USER_PROFILE_RADAR_VIEW_OPTIONS`、`resolveUserProfileDefaultRadarView()`。
|
||||
- [x] 在 `ExpenseProfileDetailModal.vue` 的行为雷达标题右上角增加小型下拉切换，复用 Element Plus 控件。[CONCEPT: 前端展示] 证据：弹窗使用 `ElSelect` / `ElOption` 渲染雷达视角下拉。
|
||||
- [x] 切换雷达视角时过滤展示维度和雷达下方行为标签，不改变上方画像标签、核心指标和最近操作列表。[CONCEPT: 权限和边界] 证据：`filterUserProfileRadarDimensions()` 与 `filterUserProfileTagsByRadarView()` 仅作用于雷达区入参。
|
||||
- [x] 保持审批详情 `EmployeeProfileRiskCard.vue` 不混入协作治理维度。[CONCEPT: 审批详情卡片] 证据：本次未修改审批详情风险卡片。
|
||||
- [x] 运行前端构建，并用浏览器确认个人画像详情的三档切换可用、空态稳定。[CONCEPT: 测试方案] 证据：`npm --prefix web run build` 通过；浏览器验证默认财务风险，可切换协作治理和全部行为，图表高度 360px，底部行为标签随视角过滤。
|
||||
|
||||
1019
document/development/hermes-risk-graph-algorithm/CONCEPT.md
Normal file
1019
document/development/hermes-risk-graph-algorithm/CONCEPT.md
Normal file
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,91 @@
|
||||
# 公开竞品资料校准与自有算法映射
|
||||
|
||||
更新日期：2026-05-30
|
||||
|
||||
## 资料边界
|
||||
|
||||
本文件只使用公开资料做产品能力和方法论校准，不推断竞品内部算法实现。
|
||||
X-Financial 的落地实现必须以自有数据、本体、规则中心、风险观察池、反馈池、
|
||||
决策追踪和可回放测试为准。
|
||||
|
||||
公开资料来源：
|
||||
|
||||
- [用友 YonBIP 财务云智能费控服务白皮书](https://mks.yybip.com/group1/M00/07/EB/CgoRC2JVTMGAPdWmAEdtt5GGOf0756.pdf)
|
||||
- [用友数智化财务资料：商旅费控、事项法会计与 AI 能力](https://mks.yybip.com/group1/M00/0A/29/CgoRC2XvFQuAKvNtACX8GJS9Zgo009.pdf)
|
||||
- [合思 AI 财务审核专家](https://www.ekuaibao.com/aifinancialapproval.html)
|
||||
- [合思 AI 审核解决方案](https://www.ekuaibao.com/solutionsr/check.html)
|
||||
- [合思企业内控解决方案](https://www.ekuaibao.com/solutionsr/control.html)
|
||||
|
||||
## 用友公开资料校准
|
||||
|
||||
### 端到端费控链路
|
||||
|
||||
公开资料覆盖事前申请、商旅预订、智能识票、自动报账、移动审批、智能收单、
|
||||
智能审核、自动核算、结算、分析、电子归档等环节。
|
||||
|
||||
X-Financial 映射：
|
||||
|
||||
- 用 `ObjectCentricEvent` 建立申请、预订、报销、审批、付款、归档、复盘事件。
|
||||
- 用 `RiskObservation` 承接每个阶段产生的风险结论。
|
||||
- 用 `RiskDataLineage` 记录每条结论引用的单据、票据、规则、本体和 AgentRun。
|
||||
|
||||
### 规则模板、预算刚柔控制、信用抽审、商旅推荐
|
||||
|
||||
公开资料中可借鉴的能力包括规则引擎/规则模板、预算事前事中控制、刚性/柔性
|
||||
控制、信用管理与抽审规则，以及基于出发时间、目的地、差旅标准和多供应商比价
|
||||
的商旅推荐。
|
||||
|
||||
X-Financial 映射：
|
||||
|
||||
- `PolicyTemplateLibrary`：把制度条款沉淀为按场景、本体实体、费用类型和角色
|
||||
绑定的规则模板族。
|
||||
- `PreControlRecommender`：在提交前给出预算、差标、商旅供应商、住宿和交通
|
||||
标准建议。
|
||||
- `RiskSamplingPlanner`：结合风险分、员工画像、信用等级、历史误报率和反馈
|
||||
标签，生成抽审策略、阈值和回放桶。
|
||||
- `ProfileBaselineUpdater`：定期更新员工、部门、供应商、费用类型基线，为信用
|
||||
抽审和预算柔性控制提供自有画像数据。
|
||||
|
||||
## 合思公开资料校准
|
||||
|
||||
### AI 审核与人机共审
|
||||
|
||||
公开资料强调 AI 先完成规则型检查、风险标记和建议输出，再由财务处理异常、
|
||||
灰区和制度优化。X-Financial 不应让 AI 直接替代规则中心，而应把 AI 产出转成
|
||||
可解释、可审计、可回放的风险观察。
|
||||
|
||||
X-Financial 映射：
|
||||
|
||||
- `HumanInLoopAutomationGate`：按置信度、风险等级、证据来源数、历史误报率和
|
||||
数据质量决定自动放行、辅助、人工复核或候选观察。
|
||||
- `DecisionTrace`：保留输入、命中行、贡献项、不确定性原因和解释模板。
|
||||
- `RiskObservationFeedback`：把确认、误报、忽略、补件、升级、候选规则来源
|
||||
转为闭环样本。
|
||||
|
||||
### 多凭证校验与时空推理
|
||||
|
||||
公开资料中，多凭证校验覆盖报销单、发票、水单、订单、小票、合同、行程等材料；
|
||||
时空校验覆盖消费时间、地点、轨迹、行程逻辑和异常地点。
|
||||
|
||||
X-Financial 映射：
|
||||
|
||||
- `MultiEvidenceReconciler`：把单据、发票、附件、流水、合同、行程和事前申请
|
||||
统一成证据项，输出字段一致性和缺失项。
|
||||
- `SpatioTemporalRiskEngine`：基于发生时间、提交时间、明细时间、地点、行程、
|
||||
开票地点和供应商地点构造时空一致性信号。
|
||||
- `RiskDataQualityGate`：证据不足或字段缺失时封顶风险分，避免低质量数据触发
|
||||
强结论。
|
||||
|
||||
## 转成 X-Financial 自有壁垒
|
||||
|
||||
竞品资料只作为能力校准。真正不可复制的部分必须沉淀在以下资产中：
|
||||
|
||||
1. 自有财务本体：场景、意图、实体、约束、风险信号、权限、置信度。
|
||||
2. 自有对象中心事件日志：每个报销和风控过程可回放。
|
||||
3. 自有画像基线：员工、部门、供应商、费用类型、规则、制度条款长期演化。
|
||||
4. 自有反馈池：人工确认、误报、补件、升级和候选规则来源。
|
||||
5. 自有回放集：正样本、负样本、反事实样本、噪声样本和历史误报样本。
|
||||
6. 自有解释资产：证据链、制度条款、相似案例、贡献项、决策追踪和数据血缘。
|
||||
|
||||
因此，后续实现原则是：不复制竞品页面、术语和流程包装；只吸收公开资料中可验证
|
||||
的能力方向，并转译为 X-Financial 的结构化数据、确定性算法、人工反馈和回放测试。
|
||||
@@ -0,0 +1,112 @@
|
||||
# 风险图谱数据来源与壁垒资产清单
|
||||
|
||||
更新日期：2026-05-30
|
||||
|
||||
## 风险相关数据来源
|
||||
|
||||
1. 报销单主表：`ExpenseClaim`
|
||||
- 关键字段：`id`、`claim_no`、`employee_id`、`employee_name`、`department_id`、`department_name`、`expense_type`、`amount`、`currency`、`invoice_count`、`occurred_at`、`submitted_at`、`status`、`approval_stage`、`risk_flags_json`。
|
||||
- 用途：风险主体、金额基线、流程阶段、规则命中、图谱 claim 节点。
|
||||
|
||||
2. 报销明细：`ExpenseClaimItem`
|
||||
- 关键字段：`item_id`、`item_type`、`item_amount`、`item_location`、`item_date`、`invoice_id`。
|
||||
- 用途：多凭证一致性、时空一致性、票据关系、图谱 item / invoice 节点。
|
||||
|
||||
3. 风险规则命中：`risk_flags_json` 与规则中心结果
|
||||
- 来源：报销单已有风险标记、`RiskObservationService.upsert_platform_risk_flags()`。
|
||||
- 用途：`S_rule`、规则版本追溯、候选规则闭环。
|
||||
|
||||
4. 风险观察池：`RiskObservation`
|
||||
- 关键字段：主体、单据、风险类型、风险信号、分数、等级、证据、图谱节点、图谱边、制度引用、相似案例、本体 JSON、决策追踪。
|
||||
- 用途：统一风险结论、看板、详情、反馈、回放。
|
||||
|
||||
5. 风险观察反馈：`RiskObservationFeedback`
|
||||
- 关键字段：反馈类型、动作、处理人、备注、扩展 payload。
|
||||
- 用途：人工采纳、误报、忽略、处理完成、候选规则来源、回放标签。
|
||||
|
||||
6. 数字员工任务记录：`HermesTaskExecutionLog`
|
||||
- 关键字段：任务配置、状态、开始结束时间、错误信息、执行摘要。
|
||||
- 用途：风险扫描任务追溯、数字员工工作记录详情、失败原因。
|
||||
|
||||
7. Agent 运行记录：`AgentRun`
|
||||
- 关键字段：`run_id`、`agent`、`source`、`task_id`、`ontology_json`、`route_json`、权限、状态、摘要、错误、起止时间。
|
||||
- 用途：数字员工运行上下文、数据血缘、回放输入。
|
||||
|
||||
8. 工具调用记录：`AgentToolCall`
|
||||
- 关键字段：工具类型、工具名称、请求、响应、状态、耗时、错误。
|
||||
- 用途：OCR、知识检索、规则执行、外部工具证据链。
|
||||
|
||||
9. 语义解析日志：`SemanticParseLog`
|
||||
- 关键字段：原始查询、场景、意图、实体、时间范围、指标、约束、风险信号、权限、置信度。
|
||||
- 用途：本体到风险图谱桥接、低置信度降级、语义血缘。
|
||||
|
||||
10. 财务制度知识库
|
||||
- 来源：知识库文档、制度归集任务、知识检索证据。
|
||||
- 用途：制度条款引用、`S_policy`、风险解释、制度缺口识别。
|
||||
|
||||
## `/api/v1/ontology/parse` 字段与落库方式
|
||||
|
||||
接口请求：`OntologyParseRequest`
|
||||
|
||||
- `query`：自然语言问题。
|
||||
- `user_id`：当前用户。
|
||||
- `context_json`：角色、部门、权限上下文。
|
||||
|
||||
接口响应：`OntologyParseResult`
|
||||
|
||||
- `scenario`：业务场景。
|
||||
- `intent`：用户意图。
|
||||
- `entities`：实体列表，包含类型、原值、标准值、角色、置信度。
|
||||
- `time_range`：时间范围。
|
||||
- `metrics`：指标列表。
|
||||
- `constraints`：字段约束。
|
||||
- `risk_flags`：风险信号列表。
|
||||
- `permission`：权限结果。
|
||||
- `confidence`：整体置信度。
|
||||
- `missing_slots`：缺失槽位。
|
||||
- `ambiguity`：歧义说明。
|
||||
- `parse_strategy`：解析策略。
|
||||
- `clarification_required` / `clarification_question`：是否需要追问。
|
||||
- `run_id`：关联 `AgentRun.run_id`。
|
||||
- `field_errors`：字段级错误。
|
||||
|
||||
落库方式：
|
||||
|
||||
- `AgentRun.ontology_json` 保存本次解析概要。
|
||||
- `SemanticParseLog.entities_json` 保存实体。
|
||||
- `SemanticParseLog.time_range_json` 保存时间。
|
||||
- `SemanticParseLog.metrics_json` 保存指标。
|
||||
- `SemanticParseLog.constraints_json` 保存约束。
|
||||
- `SemanticParseLog.risk_flags_json` 保存风险信号。
|
||||
- `SemanticParseLog.permission_json` 保存权限。
|
||||
- `SemanticParseLog.confidence` 保存整体置信度。
|
||||
|
||||
## 不可复制壁垒资产
|
||||
|
||||
1. 专有财务本体
|
||||
- 由场景、意图、实体、约束、风险信号、权限和置信度构成。
|
||||
- 价值：把自然语言、规则中心和风险图谱统一到同一业务语义。
|
||||
|
||||
2. 对象中心财务事件日志
|
||||
- 由 `ObjectCentricEvent` 承载，统一申请、报销、票据、审批、退回、付款、归档、复盘。
|
||||
- 价值：形成可回放过程挖掘资产。
|
||||
|
||||
3. 风险观察反馈池
|
||||
- 由 `RiskObservationFeedback` 承载，记录确认、误报、忽略、改写、补件、升级和候选规则来源。
|
||||
- 价值：把人工判断变成模型和规则迭代样本。
|
||||
|
||||
4. 人机共审行为数据
|
||||
- 来源：AgentRun、ToolCall、反馈、数字员工执行日志。
|
||||
- 价值：记录谁在何时基于什么证据做了什么判断。
|
||||
|
||||
5. 可回放评测资产
|
||||
- 由 `AlgorithmReplaySet` 与 `RiskEvaluationCase` 承载。
|
||||
- 价值：每次规则、本体或算法升级后都能复跑历史样本，防止误报率失控。
|
||||
|
||||
6. 实体标准化资产
|
||||
- 由 `FinancialEntityResolver` 和 `CanonicalEntityRegistry` 承载。
|
||||
- 价值：沉淀供应商、商户、酒店、银行户名、员工姓名等标准主体。
|
||||
|
||||
7. 可解释决策资产
|
||||
- 由 `DecisionTrace`、贡献项、不确定性原因、数据血缘承载。
|
||||
- 价值：让每个风险结论都能被审计、复核和反事实推演。
|
||||
158
document/development/hermes-risk-graph-algorithm/TODO.md
Normal file
158
document/development/hermes-risk-graph-algorithm/TODO.md
Normal file
@@ -0,0 +1,158 @@
|
||||
# 数字员工财务行为图谱风险算法开发 TODO
|
||||
|
||||
更新日期：2026-05-30
|
||||
|
||||
## 1. 调研与契约
|
||||
|
||||
- [x] 梳理现有风险相关数据来源：报销单、费用明细、票据、审批记录、规则命中、AgentRun、ToolCall、语义解析日志。[CONCEPT: 背景与问题] 证据：`RISK_SOURCE_AND_MOAT.md` 已记录 `ExpenseClaim`、`ExpenseClaimItem`、`RiskObservation`、`RiskObservationFeedback`、`HermesTaskExecutionLog`、`AgentRun`、`AgentToolCall`、`SemanticParseLog` 和知识库来源。
|
||||
- [x] 梳理现有数字员工技能和工作记录模型，确认员工技能详情、工作记录详情、知识制度记录详情的边界。[CONCEPT: 非目标] 证据：`DigitalEmployeesView.vue` 保持员工技能/工作记录页签，`DigitalEmployeeWorkRecords.vue` 负责完整详情页，`AuditDigitalEmployeeDetail.vue` 不引入知识图谱组件。
|
||||
- [x] 梳理分析看板现有数据来源和页面结构，确认风险看板作为独立页签的接入方式。[CONCEPT: 分析看板风险看板] 证据：`TopBar.vue` 的分析看板下拉已新增 `risk`，`OverviewView.vue` 已按 `dashboard=risk` 渲染独立风险看板。
|
||||
- [x] 定义 `RiskObservation` 后端字段、状态枚举、来源枚举和 JSON 字段结构。[CONCEPT: 统一风险观察模型] 证据：`server/src/app/models/risk_observation.py` 与 `server/src/app/schemas/risk_observation.py` 已实现。
|
||||
- [x] 定义图谱节点和边的最小字段，不急于引入图数据库。[CONCEPT: 实体图谱层] 证据：`RiskGraphNode.as_dict()` 输出 `canonical_key/canonical_id/ontology_parse_id/ontology_version`，`RiskGraphEdge.as_dict()` 输出 `source/evidence/metadata`，后端算法测试已覆盖。
|
||||
- [x] 定义单据详情风险证据链响应结构。[CONCEPT: API 契约建议] 证据：`riskObservations.js` 已归一单据风险观察字段，详情组件读取 `/risk-observations/claim/{claim_id}`。
|
||||
- [x] 定义风险看板聚合响应结构。[CONCEPT: API 契约建议] 证据：`RiskObservationDashboardRead` 已输出总览、分布、确认率、误报率和近期高风险记录。
|
||||
- [x] 定义数字员工工作记录关联风险观察响应结构。[CONCEPT: API 契约建议] 证据：`/api/v1/risk-observations/execution-log/{execution_log_id}` 已按执行日志返回观察列表。
|
||||
- [x] 明确不可复制壁垒资产清单：专有本体、对象中心事件日志、风险观察反馈池、人机共审行为数据、可回放评测资产。[CONCEPT: 不可复制壁垒设计] 证据：`RISK_SOURCE_AND_MOAT.md` 已明确专有本体、对象中心事件日志、风险观察反馈池、人机共审行为、可回放评测、实体标准化和可解释决策资产。
|
||||
|
||||
### 1.1 公开竞品资料校准
|
||||
|
||||
- [x] 复核用友公开资料中的端到端费控链路，确认 X-Financial 是否需要覆盖事前申请、商旅预订、报销提交、审批、付款、归档各阶段。[CONCEPT: 公开竞品资料借鉴] 证据：`PUBLIC_COMPETITOR_REFERENCE.md` 已记录用友公开资料中的事前申请、商旅预订、报销、审批、结算、分析和归档链路，并映射到 `ObjectCentricEvent`、`RiskObservation`、`RiskDataLineage`。
|
||||
- [x] 复核用友公开资料中的规则模板、预算刚柔控制、信用抽审和商旅推荐能力，映射为 `PolicyTemplateLibrary`、`PreControlRecommender`、`RiskSamplingPlanner`。[CONCEPT: 用友费用可借鉴模式] 证据：`PUBLIC_COMPETITOR_REFERENCE.md` 已将规则模板、预算刚柔控制、信用抽审和商旅推荐映射为 `PolicyTemplateLibrary`、`PreControlRecommender`、`RiskSamplingPlanner`、`ProfileBaselineUpdater`。
|
||||
- [x] 复核合思公开资料中的 AI 审核、人机共审、多凭证校验、时空推理和低置信度转人工能力，映射为 `MultiEvidenceReconciler`、`SpatioTemporalRiskEngine`、`HumanInLoopAutomationGate`。[CONCEPT: 合思费控可借鉴模式] 证据：`PUBLIC_COMPETITOR_REFERENCE.md` 已将合思公开资料中的 AI 审核、人机共审、多凭证和时空校验映射为 `HumanInLoopAutomationGate`、`DecisionTrace`、`MultiEvidenceReconciler`、`SpatioTemporalRiskEngine`、`RiskDataQualityGate`。
|
||||
- [x] 明确竞品资料只作为产品能力和方法论参考，不能作为内部算法实现依据。[CONCEPT: 资料边界] 证据：`PUBLIC_COMPETITOR_REFERENCE.md` 已写明只使用公开资料做产品能力和方法论校准，不推断竞品内部算法实现。
|
||||
- [x] 把竞品借鉴项转成 X-Financial 自有数据、可解释算法、可审计证据和可回放测试，不直接复制竞品页面或术语。[CONCEPT: 对当前方案的补强] 证据：`PUBLIC_COMPETITOR_REFERENCE.md` 已把竞品能力转译为自有财务本体、对象中心事件日志、画像基线、反馈池、回放集和解释资产。
|
||||
|
||||
### 1.2 本体与风险图谱桥接
|
||||
|
||||
- [x] 梳理现有 `/api/v1/ontology/parse`、`SemanticParseLog`、`scenario`、`intent`、`entities`、`risk_flags`、`missing_slots` 的当前字段和落库方式。[CONCEPT: 本体与风险图谱桥接] 证据：`RISK_SOURCE_AND_MOAT.md` 已记录 `OntologyParseRequest/OntologyParseResult` 字段，以及 `AgentRun.ontology_json` 与 `SemanticParseLog.*_json` 落库方式。
|
||||
- [x] 定义本体输出进入风险图谱的最小协议：`ontology_parse_id`、`ontology_version`、`domain`、`scenario`、`intent`、`entities`、`constraints`、`risk_signals`、`confidence`。[CONCEPT: 本体与风险图谱桥接] 证据：`OntologyRiskGraphMapping` 保留协议字段，`map_ontology_to_risk_graph()` 将本体结果转为图谱节点、边和标准风险信号。
|
||||
- [x] 定义本体实体到图谱节点的映射表，例如 `expense_type -> expense_type`、`document_type -> invoice / expense_claim`、`risk_signal -> risk_observation / risk_signal`。[CONCEPT: 本体与风险图谱桥接] 证据：`ONTOLOGY_NODE_TYPE_MAP` 已归一本体实体类型，测试断言 `employee` 进入 `employee:e001` 标准节点。
|
||||
- [x] 定义图谱边白名单，禁止数字员工自由创造运行时边类型。[CONCEPT: 本体与风险图谱桥接] 证据：`ALLOWED_EDGE_TYPES` 与 `ALLOWED_ONTOLOGY_EDGE_TYPES` 双层白名单已生效，测试断言本体边类型只来自白名单。
|
||||
- [x] 定义风险信号标准词典，把“住宿超标 / 酒店超标 / 差旅住宿异常”等近义说法归一到同一个 `risk_signal`。[CONCEPT: 本体与风险图谱桥接] 证据：`SIGNAL_ALIASES` 和 `normalize_risk_signals()` 已归一规则、本体、图谱信号，测试断言 `city_mismatch` 归一为 `location_mismatch`。
|
||||
- [x] 定义本体置信度降级策略，决定自动规则匹配、半自动复核和候选观察的边界。[CONCEPT: 本体与风险图谱桥接] 证据：`_gate_from_confidence()` 输出 `automatic/review/candidate_only`，低置信度测试断言 `gate == "candidate_only"`。
|
||||
|
||||
## 2. 数据模型
|
||||
|
||||
- [x] 新增风险观察模型和迁移脚本，包含主体、分数、等级、证据、来源、算法版本和反馈状态。[CONCEPT: 统一风险观察模型] 证据：`RiskObservationService.ensure_storage_ready()` 按当前项目模式运行时建表，模型包含主体、分数、证据、来源、版本和反馈状态。
|
||||
- [x] 新增图谱节点存储模型或兼容结构，第一版支持员工、部门、供应商、票据、单据、制度条款、规则、风险观察。[CONCEPT: 实体图谱层] 证据：`RiskObservation.graph_node_keys_json` 已保存观察关联节点键，算法结果保留完整节点契约。
|
||||
- [x] 新增图谱边存储模型或兼容结构，支持提交、包含、使用票据、关联供应商、命中规则、关联制度、相似案例等关系。[CONCEPT: 实体图谱层] 证据：`RiskObservation.graph_edge_keys_json` 已保存观察关联边键，算法图谱边包含白名单边类型。
|
||||
- [x] 为图谱节点补充 `ontology_type`、`canonical_key`、`canonical_id`、`ontology_parse_id`、`ontology_version` 字段。[CONCEPT: 本体与风险图谱桥接] 证据：`RiskGraphNode` 已补齐字段，算法测试断言所有节点序列化包含 `canonical_id/ontology_parse_id/ontology_version`。
|
||||
- [x] 为图谱边增加白名单校验和来源字段，记录边由规则、数字员工、本体解析还是人工反馈生成。[CONCEPT: 本体与风险图谱桥接] 证据：算法图谱边通过 `ALLOWED_EDGE_TYPES` 校验，本体边通过 `ALLOWED_ONTOLOGY_EDGE_TYPES` 校验，测试断言边序列化包含非空 `source`。
|
||||
- [x] 新增人工反馈模型或扩展现有反馈表，支持确认、误报、忽略、已处理等状态。[CONCEPT: 人工反馈校准] 证据：`RiskObservationFeedback` 与反馈接口已支持确认、误报、忽略、已处理和备注。
|
||||
- [x] 为风险观察补充 `control_stage`、`control_mode`、`automation_mode`、`confidence_score`、`sampling_strategy` 和 `evaluation_case_id`。[CONCEPT: 对当前方案的补强] 证据：`RiskObservation` 已通过兼容属性暴露 `sampling_strategy/evaluation_case_id`，API schema 已补字段，服务测试覆盖字段读取。
|
||||
- [x] 为风险观察补充 `ontology_parse_id`、`ontology_version`、`domain`、`scenario`、`intent`、`ontology_entities_json`、`risk_signals_json` 和 `canonical_subject_key`。[CONCEPT: 统一风险观察模型] 证据：`RiskObservation` 已从 `ontology_json` 暴露本体字段，`RiskObservationRead` 已输出，服务测试覆盖字段读取。
|
||||
- [x] 为风险观察增加必要索引：主体、单据、风险类型、等级、状态、来源、创建时间。[CONCEPT: 技术验收] 证据：`RiskObservation.__table_args__` 与字段索引覆盖主体、单据、等级、状态、信号、来源和时间。
|
||||
- [x] 设计对象中心财务事件日志模型，把申请、预算占用、票据上传、审批、退回、付款、归档、复盘统一为可回放事件。[CONCEPT: 不可复制壁垒设计] 证据：`process_mining.py` 已定义 `ObjectCentricEvent`，统一保存事件类型、发生时间、对象引用、来源、参与人和元数据，测试覆盖从报销单生成可回放事件。
|
||||
- [x] 设计风险观察反馈池字段，记录人工采纳、驳回、改写、退回、补件、升级审批、误报和候选规则来源。[CONCEPT: 不可复制壁垒设计] 证据：`RiskObservationFeedback` 已通过兼容属性暴露 `decision/candidate_rule_source/confidence_score/escalation_target/supplement_required`，测试覆盖候选规则反馈元数据。
|
||||
- [x] 设计算法回放集模型，绑定历史单据、本体版本、规则版本、算法版本和反馈标签。[CONCEPT: 不可复制壁垒设计] 证据：`replay.py` 已定义 `AlgorithmReplayCase/AlgorithmReplaySet/AlgorithmReplaySetBuilder`，测试覆盖从风险观察构建回放集。
|
||||
|
||||
## 3. 后端服务
|
||||
|
||||
- [x] 实现风险观察写入服务，统一接收规则、图谱、画像、数字员工产出。[CONCEPT: 总体架构] 证据：`RiskObservationService.upsert_observation()` 已接收 `RiskObservationDraft` 或 dict。
|
||||
- [x] 实现单据维度风险观察查询服务。[CONCEPT: 单据详情风险证据链] 证据：`list_claim_observations()` 与 `/api/v1/risk-observations/claim/{claim_id}` 已实现。
|
||||
- [x] 实现风险观察详情查询服务，返回证据链、基线、制度条款、相似案例和建议动作。[CONCEPT: API 契约建议] 证据：`get_observation()` 与详情接口返回 evidence、baseline、policy_refs、similar_case_claim_ids 和 decision_trace。
|
||||
- [x] 实现风险看板聚合服务，输出总览、分布、趋势、排行和算法效果。[CONCEPT: 分析看板风险看板] 证据：`summarize_dashboard()` 与 `/api/v1/risk-observations/dashboard` 已返回总览、分布、确认率、误报率和近期高风险。
|
||||
- [x] 实现数字员工运行记录关联风险观察查询服务。[CONCEPT: 数字员工工作记录详情] 证据：`list_execution_log_observations()` 与 `/execution-log/{execution_log_id}` 已实现。
|
||||
- [x] 实现人工反馈写入和状态流转服务。[CONCEPT: 人工反馈校准] 证据：`create_feedback()` 已同步更新 `status` 与 `feedback_status`。
|
||||
- [x] 在服务层保留算法版本和来源信息，避免风险结论不可追溯。[CONCEPT: 技术验收] 证据：`RiskObservationService.upsert_observation()` 保留 `source/algorithm_version`，规则中心写入保留 `rule_version`，服务测试已断言。
|
||||
|
||||
## 4. 算法与图谱
|
||||
|
||||
- [x] 实现同类基线计算方法，支持部门、职级、费用类型、城市等级等口径。[CONCEPT: 同类基线偏离] 证据：`server/src/app/algorithem/risk_graph/engine.py`，`pytest --ignore=.venv-ocr312 tests\test_financial_risk_graph_algorithm.py -q` 通过。
|
||||
- [x] 实现同类样本不足时的降级口径记录。[CONCEPT: 算法验收] 证据：`PeerBaseline(scope="insufficient_sample")` 与空风险测试覆盖。
|
||||
- [x] 实现确定性规则命中分 `S_rule` 的映射逻辑。[CONCEPT: 风险总分] 证据：`server/src/app/algorithem/risk_graph/signals.py` 与算法测试覆盖。
|
||||
- [x] 实现画像偏离分 `S_anomaly` 的计算逻辑。[CONCEPT: 同类基线偏离] 证据：金额偏离基线测试断言 `S_anomaly >= 90`。
|
||||
- [x] 实现图谱异常分 `S_graph` 的第一版信号累加逻辑。[CONCEPT: 图谱异常分] 证据：重复发票、拆单、频次、地点不一致、跨部门聚集信号已进入 `engine.py`。
|
||||
- [x] 实现制度语义相关分 `S_policy` 的占位契约，第一版可先接制度条款命中结果。[CONCEPT: 风险总分] 证据：`policy_refs_for_signal()` 已把制度约束型信号映射为 `policy.*`。
|
||||
- [x] 实现历史反馈分 `S_history`，基于相似案例退回率、确认率和误报率。[CONCEPT: 人工反馈校准] 证据：`RiskObservationService.build_history_stats()` 汇总确认/误报/退回反馈，Hermes 扫描已把历史统计注入 `S_history`。
|
||||
- [x] 实现风险总分和等级计算，保证输出可解释贡献项。[CONCEPT: 风险总分] 证据：`RiskObservationDraft.contribution_scores` 输出 `S_rule/S_anomaly/S_graph/S_policy/S_history`。
|
||||
- [x] 实现本体到图谱的映射服务，输入本体解析结果，输出标准图谱节点和白名单边。[CONCEPT: 本体与风险图谱桥接] 证据：`server/src/app/algorithem/risk_graph/ontology.py` 与白名单边测试覆盖。
|
||||
- [x] 实现风险信号归一化服务，保证规则中心、图谱引擎、风险看板使用同一 `risk_signal` 口径。[CONCEPT: 本体与风险图谱桥接] 证据：`normalize_risk_signals()` 已归一规则、本体和图谱信号。
|
||||
- [x] 实现本体置信度门控，低置信度只生成候选观察，不触发强拦截。[CONCEPT: 本体与风险图谱桥接] 证据：低置信度本体映射测试断言 `gate == "candidate_only"`。
|
||||
- [x] 实现多凭证一致性校验，覆盖单据、发票、流水、合同、行程、事前申请之间的字段一致性。[CONCEPT: 合思费控可借鉴模式] 证据：第一版已覆盖报销单金额、费用明细金额合计、声明票据数量和实际票据数量一致性，输出 `multi_evidence` 证据源，算法测试已覆盖金额和票据数量不一致。
|
||||
- [x] 实现时空一致性风险信号，覆盖时间、地点、行程、消费和开票关系。[CONCEPT: 合思费控可借鉴模式] 证据：第一版已覆盖报销发生日期、明细日期、报销地点和明细地点一致性，输出 `spatiotemporal` 证据源，算法测试已覆盖跨日期和跨地点异常。
|
||||
- [x] 实现自动化门控逻辑，按置信度、风险等级、证据覆盖和历史误报率决定辅助、半自动、自动模式。[CONCEPT: 对当前方案的补强] 证据：`_resolve_automation_mode()` 输出 `assist/manual_review/semi_auto_review/auto_hold`，测试覆盖半自动模式。
|
||||
- [x] 实现风险分层抽审策略，记录抽审口径、阈值和回放数据。[CONCEPT: 用友费用可借鉴模式] 证据：`sampling.py` 已实现 `RiskSamplingPlanner`，算法输出在 `decision_trace.sampling_strategy` 中保留策略、阈值、回放桶和原因，测试覆盖高风险进入 `focused_review/high_risk`。
|
||||
- [x] 建立风险评测样本集，包含正样本、负样本、反事实样本、噪声样本和历史误报样本。[CONCEPT: 合思费控可借鉴模式] 证据：`evaluation_cases.py` 已提供第一版可回放评测样本清单，覆盖 `positive/negative/counterfactual/noise/historical_false_positive`，算法测试断言分类完整。
|
||||
|
||||
### 4.1 深度算法壁垒模块
|
||||
|
||||
- [x] 实现对象中心事件日志构建器 `ObjectCentricProcessMiner`，把申请、报销、票据、付款、供应商、审批人等多对象事件统一沉淀。[CONCEPT: 对象中心过程挖掘] 证据：`ObjectCentricProcessMiner.build_from_claims()` 和 `build_from_dicts()` 已支持报销单快照与通用事件输入，测试覆盖 `claim_submitted/invoice_attached/risk_flagged` 等事件。
|
||||
- [x] 实现流程一致性检测 `ConformanceRiskDetector`，识别跳步审批、返工循环、付款前异常和流程绕行。[CONCEPT: 对象中心过程挖掘] 证据：`ConformanceRiskDetector.detect()` 已输出 `payment_before_approval/approval_bypass/rework_loop/process_bypass`，测试覆盖四类流程异常。
|
||||
- [x] 实现金融实体解析服务 `FinancialEntityResolver`，归一供应商、商户、酒店、银行户名和员工姓名。[CONCEPT: 实体解析与主数据归一] 证据：`entity_resolution.py` 已实现实体类型别名和标准主键归一，测试覆盖供应商/商户别名归一到同一 `vendor` 主体。
|
||||
- [x] 实现标准实体注册表 `CanonicalEntityRegistry`，维护图谱标准主体 ID 和人工确认记录。[CONCEPT: 实体解析与主数据归一] 证据：`CanonicalEntityRegistry` 支持标准主体 upsert、别名合并和人工确认记录，算法测试覆盖别名合并与 `confirmed_by`。
|
||||
- [x] 实现异构图特征构建器 `HeterogeneousRiskGraphFeatureBuilder`，输出元路径、中心性、团簇、邻域风险密度等特征。[CONCEPT: 异构图与时序图学习] 证据：`features.py` 已输出节点类型、边类型、元路径、度中心性、连通簇和邻域风险密度，算法测试覆盖重复发票图谱特征。
|
||||
- [x] 实现时序图监控 `TemporalRiskGraphMonitor`，监控关系突增、消失、迁移和异常传播。[CONCEPT: 异构图与时序图学习] 证据：`temporal.py` 已比较前后图谱快照，输出关系新增、删除、突增、目标迁移和风险传播，算法测试覆盖边变化检测。
|
||||
- [x] 实现多模型异常检测集成，组合稳健统计、孤立森林、局部离群、时间突变和周期偏离。[CONCEPT: 多模型异常检测组合] 证据：`anomaly_models.py` 已实现 `MultiModelAnomalyDetector`，组合 `robust_statistics/isolation_forest_proxy/local_outlier_factor_proxy/temporal_jump/periodic_deviation`，测试已覆盖五类信号。
|
||||
- [x] 实现决策追踪 `DecisionTrace`，记录决策表输入、命中行、输出、版本和解释。[CONCEPT: 决策建模与策略即代码] 证据：`decisioning.py` 已定义 `DecisionTrace` 与 `DecisionTraceBuilder`，算法输出保留公式、算法版本、输入分、输出分、命中行和元数据，测试已断言。
|
||||
- [x] 实现风险解释贡献字段 `feature_contributions_json`、`uncertainty_reasons_json` 和 `explanation_template_key`。[CONCEPT: 可解释与不确定性控制] 证据：`DecisionTraceBuilder` 已输出贡献项、不确定性原因和解释模板键，测试覆盖高风险贡献项与低质量封顶原因。
|
||||
- [x] 实现反事实风险建议 `CounterfactualRiskAdvisor`，输出降低风险分的可执行补救动作。[CONCEPT: 因果分析与反事实建议] 证据：`counterfactual.py` 已根据规则、基线、图谱和数据质量贡献输出可执行降分动作，测试覆盖四类建议。
|
||||
- [x] 实现控制效果分析 `ControlEffectAnalyzer`，评估规则、抽审策略或数字员工上线前后的风险变化。[CONCEPT: 因果分析与反事实建议] 证据：`control_effect.py` 已比较上线前后风险数量、均分、高风险率、确认率和误报率变化，测试已覆盖。
|
||||
- [x] 实现风险数据血缘 `RiskDataLineage`，记录风险观察使用的数据表、文档、OCR、AgentRun、规则版本和本体版本。[CONCEPT: 数据血缘与质量门禁] 证据：`lineage.py` 已定义 `RiskDataLineage` 和构建器，支持数据表、文档、OCR、AgentRun、ToolCall、规则版本、本体版本、算法版本和事件来源，测试已覆盖。
|
||||
- [x] 实现风险数据质量门禁 `RiskDataQualityGate`，阻止低质量数据触发强风控结论。[CONCEPT: 数据血缘与质量门禁] 证据：`quality.py` 已实现必填字段和上下文质量门禁，低质量单据高分结论会封顶为 69，算法测试覆盖缺失员工信息时禁止输出高风险。
|
||||
|
||||
## 5. 数字员工
|
||||
|
||||
- [x] 补充制度整理员工输出契约，确保制度条款可被风险观察引用。[CONCEPT: 数字员工能力分层] 证据：`policy_knowledge_contract.py` 已定义制度整理报告、知识条目、来源引用和 `risk_policy_refs`，技能文件已补输出要求，测试覆盖风险条款引用。
|
||||
- [x] 新增或扩展风险扫描员工，扫描新增单据和异常关系并写入风险观察。[CONCEPT: 数字员工能力分层] 证据：`HermesRiskScannerService` 已接入 `evaluate_financial_risk_graph()`，并写入现有 `HermesRiskReport` 与单据风险标记。
|
||||
- [x] 将风险扫描和员工画像巡检注册到数字员工的员工技能列表。[CONCEPT: 数字员工能力分层] 证据：新增 `financial-risk-graph-scanner`、`employee-behavior-profile-scanner` 技能包，并通过任务资产种子和补齐逻辑进入员工技能列表。
|
||||
- [x] 员工技能详情的立即运行按技能类型调用真实后端任务。[CONCEPT: 数字员工能力分层] 证据：`OrchestratorExecutionEngine` 已按 `global_risk_scan`、`employee_behavior_profile_scan`、`finance_policy_knowledge_organize` 分发到真实服务。
|
||||
- [x] 新增或扩展画像更新员工，定期更新员工、部门、供应商、费用类型基线。[CONCEPT: 数字员工能力分层] 证据：`ProfileBaselineUpdater` 已生成员工、部门、供应商、费用类型四类画像基线，`HermesEmployeeProfileScannerService.scan_employee_profiles()` 已返回 `baseline_summary`；`pytest --ignore=.venv-ocr312 tests/test_risk_graph_profile_baselines.py tests/test_hermes_employee_profile_baselines.py -q` 通过。
|
||||
- [x] 新增规则发现员工候选输出，候选规则必须带证据、来源和置信度。[CONCEPT: 数字员工能力分层] 证据：`rule_discovery.py` 已定义 `CandidateRiskRuleDiscovery` 和 `CandidateRiskRule`，输出包含证据、来源、置信度和候选状态；数字员工任务与技能已注册为“风险规则候选发现”。
|
||||
- [x] 数字员工运行完成后写入处理范围、处理数量、风险观察数量和失败原因。[CONCEPT: 数字员工工作记录详情] 证据：`HermesScheduler` 已写入风险图谱巡检摘要，失败仍沿用执行日志 `error_trace`。
|
||||
- [x] 确认 UI 上继续使用“数字员工 / 员工技能 / 工作记录”等业务命名，不在普通用户界面暴露内部实现名。[CONCEPT: 用户与场景] 证据：`DigitalEmployeesView.vue` 页签文案为“员工技能 / 工作记录”，普通界面未展示内部 Hermes 名称。
|
||||
|
||||
## 6. 前端：单据详情
|
||||
|
||||
- [x] 在单据详情风险说明附近新增风险证据链区块。[CONCEPT: 单据详情风险证据链] 证据：`RiskObservationEvidenceCard.vue` 已接入 `TravelRequestDetailView.vue`，按单据 `claimId` 拉取风险观察。
|
||||
- [x] 展示风险结论、证据链节点、基线对比、制度条款、历史相似案例和建议动作。[CONCEPT: 单据详情风险证据链] 证据：详情证据链已展示风险分、贡献分、证据、图谱关系、基线、建议、制度引用和相似案例。
|
||||
- [x] 支持点击风险观察进入风险观察详情或展开详情。[CONCEPT: 前端入口关系] 证据：`RiskObservationEvidenceCard.vue` 已支持多条风险观察点击切换当前详情，详情区包含贡献分、证据、图谱关系、基线建议、制度案例和反馈历史。
|
||||
- [x] 无风险观察时不占用主流程空间。[CONCEPT: 前端测试] 证据：`RiskObservationEvidenceCard.vue` 在非加载、无错误且无观察记录时不渲染卡片。
|
||||
- [x] 普通审批人只能看到当前单据相关证据，不展示无关员工长期敏感画像。[CONCEPT: 用户与场景] 证据：`RiskObservationEvidenceCard.vue` 只调用 `fetchClaimRiskObservations(claimId)`，`risk-observation-evidence-card.test.mjs` 断言不引入员工画像和知识图谱组件。
|
||||
|
||||
## 7. 前端：数字员工工作记录详情
|
||||
|
||||
- [x] 工作记录列表维持通用列表样式，详情点击进入完整详情页。[CONCEPT: 数字员工工作记录详情] 证据：`DigitalEmployeeWorkRecords.vue` 继续使用 `EnterpriseListPage`，点击行进入非侧栏完整详情。
|
||||
- [x] 工作记录详情展示本次扫描范围、处理实体数量、风险观察数量和失败原因。[CONCEPT: 数字员工工作记录详情] 证据：`DigitalEmployeeRunProducts.vue` 展示扫描单据、风险观察、图谱节点/关系、画像快照和失败摘要。
|
||||
- [x] 工作记录详情展示本次任务产出的风险观察列表。[CONCEPT: 数字员工工作记录详情] 证据：`DigitalEmployeeRunProducts.vue` 通过 `fetchRunRiskObservations()` 读取本次 Run 生成的风险观察并渲染列表。
|
||||
- [x] 知识制度整理类记录展示知识制度记录图谱，员工技能详情不展示该图谱。[CONCEPT: 非目标] 证据：`node --test web/tests/risk-observation-evidence-card.test.mjs web/tests/digital-employee-work-record-products.test.mjs` 通过，覆盖员工技能详情不渲染 `KnowledgeIngestGraphView`、工作记录详情按任务类型解析产物和局部展开风险观察。
|
||||
- [x] 风险扫描类记录展示小范围异常关系，不展示全量图谱。[CONCEPT: 图谱体现方式] 证据：`DigitalEmployeeRunProducts.vue` 点击风险观察后只展开当前观察的图谱节点、关系、证据和制度建议。
|
||||
|
||||
## 8. 前端：风险看板
|
||||
|
||||
- [x] 在分析看板中增加“风险看板”页签。[CONCEPT: 分析看板风险看板] 证据：分析看板下拉新增“风险看板”，并渲染 `RiskObservationDashboard.vue`。
|
||||
- [x] 增加风险总览卡片：新增风险数、高风险待处理数、涉及金额、已确认风险数、误报数量。[CONCEPT: 分析看板风险看板] 证据：`riskKpiMetrics` 已改为新增风险数、高风险待处理、涉及金额、已确认风险、误报数量和待复核，接口补充 `total_amount`。
|
||||
- [x] 增加风险分布图：部门、费用类型、风险类型、供应商、员工职级。[CONCEPT: 分析看板风险看板] 证据：`RiskObservationDashboard.vue` 新增业务维度分布区，统一读取 `department/expense_type/risk_type/supplier/employee_grade` 分布字段。
|
||||
- [x] 增加风险趋势图：7 天 / 30 天走势、高风险占比、处理完成率。[CONCEPT: 分析看板风险看板] 证据：`RiskDailyTrendChart.vue` 已展示风险观察与高风险趋势；风险看板时间窗口支持 7/30/90 天切换，处理完成率由闭环效果区承接。
|
||||
- [x] 增加异常排行：部门、员工、供应商、规则、费用类型。[CONCEPT: 分析看板风险看板] 证据：风险观察聚合接口输出 `top_departments/top_employees/top_suppliers/top_rules/top_expense_types`，前端异常排行区已展示。
|
||||
- [x] 增加算法效果：规则命中数、图谱异常命中数、人工确认率、误报率、候选规则数。[CONCEPT: 分析看板风险看板] 证据：风险看板已展示平均风险分、人工确认数、误报样本和候选规则数，规则/图谱来源通过来源分布体现。
|
||||
- [x] 风险看板所有数据通过风险观察聚合接口读取，不直接拼接业务散表。[CONCEPT: 技术验收] 证据：后端已提供 `/api/v1/risk-observations/dashboard` 作为统一聚合源。
|
||||
|
||||
## 9. 规则与反馈闭环
|
||||
|
||||
- [x] 规则中心执行结果写入风险观察池或与风险观察建立关联。[CONCEPT: 统一风险观察模型] 证据：`RiskObservationService.upsert_platform_risk_flags()` 已接收规则中心风险命中，报销提交预审会同步写入风险观察池。
|
||||
- [x] 风险观察支持人工确认、误报、忽略、已处理等反馈。[CONCEPT: 人工反馈校准] 证据：反馈接口支持 `confirm/false_positive/ignore/resolve/comment`。
|
||||
- [x] 规则发现员工根据反馈生成候选规则，不直接上线。[CONCEPT: 非目标] 证据：`CandidateRiskRuleDiscovery.discover_from_feedback()` 只输出 `status == "candidate_review"` 的候选规则，技能文件要求 `auto_publish=false`，测试覆盖不直接上线。
|
||||
- [x] 风险观察详情展示反馈历史和当前处理状态。[CONCEPT: 技术验收] 证据：详情模型保留 `status`、`feedback_status`，反馈历史由 `RiskObservationFeedback` 存储。
|
||||
- [x] 风险看板展示人工确认率、误报率和候选规则数量。[CONCEPT: 分析看板风险看板] 证据：聚合接口已输出 `confirmation_rate` 和 `false_positive_rate`；候选规则数待规则发现员工接入后补充。
|
||||
|
||||
## 10. 测试与验证
|
||||
|
||||
- [x] 后端模型测试：风险观察序列化、状态流转、JSON 字段兼容。[CONCEPT: 后端测试] 证据：`server/tests/test_risk_observations_service.py` 覆盖 upsert、dashboard、feedback 状态流转。
|
||||
- [x] 后端算法测试：同类基线、降级口径、风险总分、图谱异常分。[CONCEPT: 算法与公式] 证据：`server/tests/test_financial_risk_graph_algorithm.py`，`pytest --ignore=.venv-ocr312 tests\test_financial_risk_graph_algorithm.py -q` 通过。
|
||||
- [x] 后端接口测试：单据风险观察、风险观察详情、风险看板聚合、工作记录关联风险观察。[CONCEPT: API 契约建议] 证据：`pytest --ignore=.venv-ocr312 tests\test_financial_risk_graph_algorithm.py tests\test_risk_observations_service.py -q` 本地与 Docker 均 7 passed。
|
||||
- [x] 前端测试：单据详情证据链展示和空状态。[CONCEPT: 前端测试] 证据：`node --test web/tests/risk-observation-evidence-card.test.mjs` 通过 3 项断言。
|
||||
- [x] 前端测试：员工技能详情不显示知识制度图谱。[CONCEPT: 回归测试] 证据：`web/tests/digital-employee-work-record-products.test.mjs` 断言员工技能详情不渲染 `KnowledgeIngestGraphView`。
|
||||
- [x] 前端测试：工作记录详情只展示对应任务的图谱和风险观察。[CONCEPT: 回归测试] 证据：`web/tests/digital-employee-work-record-products.test.mjs` 覆盖任务类型识别、产物类型解析和风险观察局部展开。
|
||||
- [x] 前端测试：风险看板筛选、趋势、排行和卡片数据一致。[CONCEPT: 前端测试] 证据：`node --test web/tests/risk-observation-dashboard.test.mjs` 通过 3 项断言，覆盖窗口筛选、趋势、排行和 KPI 数据源联动。
|
||||
- [x] 在 Docker 容器中执行后端定向测试，命令形态为 `docker exec x-financial-main sh -lc "cd /app && pytest <target> -q"`，测试超时控制在 60s 内。[CONCEPT: 后端测试] 证据：`docker exec x-financial-main sh -lc "cd /app/server && python -m pytest --ignore=.venv-ocr312 tests/test_financial_risk_graph_algorithm.py tests/test_risk_observations_service.py -q"` 已通过 7 passed。
|
||||
- [x] 执行前端构建验证，确认风险看板和详情变更不破坏现有页面。[CONCEPT: 前端测试] 证据：`npm.cmd run build` 已通过；`/app/overview` 与 `/api/v1/risk-observations/dashboard` 本地 HTTP 检查返回 200。
|
||||
|
||||
## 11. 验收
|
||||
|
||||
- [x] 单据详情能解释单个风险：结论、证据链、基线、制度条款、历史案例、建议动作齐全。[CONCEPT: 业务验收] 证据：`RiskObservationEvidenceCard.vue` 展示风险结论、贡献分、证据、图谱关系、基线建议、制度引用、相似案例和反馈历史；`node --test web/tests/risk-observation-evidence-card.test.mjs` 通过 3 项断言。
|
||||
- [x] 数字员工工作记录能解释一次任务：范围、数量、产出、失败、风险观察齐全。[CONCEPT: 业务验收] 证据：`DigitalEmployeeRunProducts.vue` 展示扫描范围、处理数量、任务产物、失败摘要和本次风险观察；`node --test web/tests/digital-employee-work-record-products.test.mjs` 通过 4 项断言。
|
||||
- [x] 风险看板能解释整体态势：总览、分布、趋势、排行、算法效果齐全。[CONCEPT: 业务验收] 证据：`RiskObservationDashboard.vue` 已包含总览 KPI、业务维度分布、趋势、信号排行、异常排行、算法闭环效果，`npm.cmd run build` 通过。
|
||||
- [x] 所有风险输出统一进入风险观察模型或兼容结构。[CONCEPT: 技术验收] 证据：Hermes 风险扫描已调用 `RiskObservationService.upsert_observation()`。
|
||||
- [x] 高风险观察至少包含两类证据来源。[CONCEPT: 算法验收] 证据：`_apply_evidence_source_gate()` 对单一证据源高风险封顶为 69，算法测试覆盖单源封顶和多源高风险通过。
|
||||
- [x] 风险观察保留算法版本、来源、时间、反馈状态。[CONCEPT: 技术验收] 证据：`RiskObservation` 模型包含 `algorithm_version`、`source`、`created_at`、`updated_at`、`feedback_status`。
|
||||
1483
document/development/hermes-risk-graph-algorithm/index.html
Normal file
1483
document/development/hermes-risk-graph-algorithm/index.html
Normal file
File diff suppressed because it is too large
Load Diff
@@ -1,41 +0,0 @@
|
||||
# Hermes 后台智能体架构总览
|
||||
|
||||
## 1. 定位与愿景
|
||||
Hermes 是 X-Financial 系统中的**后台自动巡检与数据洞察中枢**。与处理实时对话的 UserAgent 不同，Hermes 专注于异步、长周期、大批量的任务，核心价值在于提供事前的**深度风险挖掘**和定期的**业财洞察报告**。
|
||||
|
||||
## 2. 系统拓扑图
|
||||
```mermaid
|
||||
graph TD
|
||||
subgraph 调度层
|
||||
A[Cron Scheduler] -->|定时触发| B[Task Queue]
|
||||
end
|
||||
|
||||
subgraph Hermes Agent 层
|
||||
B -->|消费任务| C(Hermes Worker)
|
||||
C --> D[Task Skills Router]
|
||||
D --> E{RiskScanner Skill}
|
||||
D --> F{ExpenseReport Skill}
|
||||
D --> G{KnowledgeCheck Skill}
|
||||
end
|
||||
|
||||
subgraph X-Financial 核心服务
|
||||
E <--> H[(Expense DB)]
|
||||
F <--> H
|
||||
G <--> I[(LightRAG Graph/Vector)]
|
||||
C <--> J[LLM Gateway / OpenAI]
|
||||
C --> K[Notification Service / 企业微信]
|
||||
end
|
||||
```
|
||||
|
||||
## 3. 核心设计原则
|
||||
1. **防抖与限流**：后台全量扫表时，必须分片执行，防止对主数据库造成 I/O 拥堵。
|
||||
2. **幂等性保障**：每一个扫描任务和报告生成任务都应该具备唯一幂等键，避免因进程重启导致的重复发信或重复扣减信用分。
|
||||
3. **隔离性**：Hermes 的进程应与对外提供 API 服务的 Web Server 物理/逻辑隔离，大模型限流策略（Token Rate Limit）应配置相互独立的账单通道。
|
||||
|
||||
## 4. 核心执行链路（示例：夜间风控巡检）
|
||||
1. 凌晨 02:00，Cron 触发 `trigger_risk_scan` 任务。
|
||||
2. Worker 拉取状态为 `draft` 和 `submitted` 且 `risk_scanned=False` 的单据。
|
||||
3. 将近三个月的相关人员单据聚类，构建 Context。
|
||||
4. 调用大模型，寻找“拆单”、“合谋”、“时间/地点异常”等隐蔽风险。
|
||||
5. 将发现的风险写入 `hermes_risk_report` 表，并标记对应单据。
|
||||
6. 任务结束，更新执行日志，等待早晨财务主管查阅。
|
||||
@@ -1,46 +0,0 @@
|
||||
# Hermes 数据库表结构设计
|
||||
|
||||
为了支持后台异步任务的执行和长期记忆（风险标记、执行结果归档），我们需要在数据库中增加（或扩充）以下表结构。
|
||||
|
||||
## 1. 任务调度与执行表
|
||||
|
||||
### `hermes_task_config` (定时任务配置表)
|
||||
用于管理所有的后台巡检和推送任务，支持动态调整频率与开关。
|
||||
- `id`: string (UUID)
|
||||
- `task_type`: string (enum: `global_risk_scan`, `weekly_expense_report`, `kb_validation`...)
|
||||
- `cron_expression`: string (e.g., `0 2 * * *`)
|
||||
- `is_enabled`: boolean (默认 True)
|
||||
- `payload_template`: jsonb (预留参数，如扫描的时间窗口、特定部门过滤条件等)
|
||||
- `updated_at`: datetime
|
||||
|
||||
### `hermes_task_execution_log` (任务执行日志表)
|
||||
记录每次任务的执行状态，便于排错与溯源。
|
||||
- `id`: string (UUID)
|
||||
- `config_id`: string (外键，关联 `hermes_task_config`)
|
||||
- `started_at`: datetime
|
||||
- `completed_at`: datetime
|
||||
- `status`: string (enum: `running`, `success`, `failed`)
|
||||
- `result_summary`: string (执行结果的简要说明，如“扫描了 1500 条单据，发现 12 条高危”)
|
||||
- `error_trace`: text (如果失败，存储错误堆栈)
|
||||
|
||||
## 2. 深度分析结果表
|
||||
|
||||
### `hermes_risk_report` (深度风险报告表)
|
||||
用于存储 LLM 找出的深层逻辑风险。
|
||||
- `id`: string (UUID)
|
||||
- `claim_id`: string (外键，关联存疑的主单据 `expense_claim`)
|
||||
- `execution_log_id`: string (外键，由哪次扫描任务产生的)
|
||||
- `risk_level`: string (enum: `low`, `medium`, `high`, `critical`)
|
||||
- `risk_type`: string (enum: `split_billing` 拆单, `collusion` 合谋, `policy_violation` 违规...)
|
||||
- `risk_description`: text (大模型生成的自然语言报告，如“该单据与前天提交的单据存在拆分可能...”)
|
||||
- `related_claim_ids`: jsonb (存储关联的同谋/相关单据 ID 列表，提供上下文线索)
|
||||
- `status`: string (enum: `pending_review` 待人工复核, `confirmed` 已确认为风险, `dismissed` 已忽略)
|
||||
|
||||
## 3. 现有表的平滑改造
|
||||
|
||||
### 修改 `employee` 表 (员工信用分预留)
|
||||
- **新增字段** `compliance_score`: int (默认 100，由 Hermes 动态扣减或恢复，用于风控引擎调节对该员工的抽查率和宽容度)
|
||||
|
||||
### 修改 `expense_claim` 表 (风控标记)
|
||||
- **新增字段** `hermes_scanned_at`: datetime (记录该单据上次被 Hermes 扫描的时间，防止重复扫描)
|
||||
- **新增字段** `hermes_risk_flag`: boolean (快速判断该单子是否被挂载了 `hermes_risk_report`)
|
||||
@@ -1,32 +0,0 @@
|
||||
# 深度风险扫描模块设计 (Risk Scan Module)
|
||||
|
||||
## 1. 业务目标
|
||||
将单点硬规则风控（如：发票大于 500 元是否合规）升级为**图谱式全局风控**。Hermes 将利用大语言模型（LLM）的逻辑推理能力，在海量历史数据中寻找隐藏的违规模式。
|
||||
|
||||
## 2. 核心扫描链路
|
||||
本模块将作为一个独立的 Skill 被定时任务触发。
|
||||
|
||||
### 第一步：数据快照聚合
|
||||
- **提取目标**：拉取状态为 `draft`、`submitted` 且最近 30 天内活跃的报销单，同时带出相关的发票明细。
|
||||
- **降维处理**：为避免超出大模型的 Token 上下文限制，必须对单据信息进行降维。仅提取：`申请人、时间、地点、商户名、金额、报销类型` 形成精简的 CSV 或 JSON Lines 格式。
|
||||
|
||||
### 第二步：大模型批量推理 (LLM Batch Inference)
|
||||
- **风险定义植入**：通过 System Prompt 将目前财务最头疼的几类风险定义给模型（如拆单、套现、虚假连号发票）。
|
||||
- **执行方式**：将数据按“同部门”或“同地域”分块 (Chunking) 喂给大模型。
|
||||
- **Prompt 示例**：
|
||||
```markdown
|
||||
你是一个内控审计 Agent。以下是某部门近半个月的报销流水清单。
|
||||
请找出其中是否存在：
|
||||
1. 拆单行为（同人、同地点、连日、小额累加）
|
||||
2. 聚众套现行为（不同人、同偏僻餐馆、同日极高额）
|
||||
如果发现风险，请输出对应的单号集合以及你的推理过程。
|
||||
```
|
||||
|
||||
### 第三步：风险标记与处置
|
||||
- 解析大模型返回的结构化 JSON。
|
||||
- 对被判定的高危单据，在主库中插入 `hermes_risk_report` 记录。
|
||||
- **动作反馈**：如果该单据正处于 `submitted` 状态，并且得分极高（如虚假连号发票），可以通过 X-Financial 原有接口自动注入“退回”动作，并附加大模型的分析日志。
|
||||
|
||||
## 3. 防抖与自我迭代
|
||||
- **扫描去重**：利用 `expense_claim.hermes_scanned_at` 防止已经出具过报告的单据被重复投入分析队列。
|
||||
- **人工纠偏 (Human-in-the-loop)**：当财务在前端驳回 Hermes 的风险提示（即认为没问题）时，事件将被记录。Hermes 可通过夜间的反思任务优化下一次 Prompt 中的判定容忍度。
|
||||
@@ -1,34 +0,0 @@
|
||||
# 动态费控与洞察报告模块设计 (Expense Report Module)
|
||||
|
||||
## 1. 业务目标
|
||||
基于海量的流水账单，定期（周/月）由 Hermes Agent 为部门管理者或财务总监自动生成具有**业务洞察力**的归因分析报告，将冷冰冰的数字转化为具有指导意义的自然语言建议。
|
||||
|
||||
## 2. 核心分析链路
|
||||
|
||||
### 第一步：BI 数据聚合 (Data Aggregation)
|
||||
- 借助 ORM 或底层 Data Warehouse (如有)，Hermes 执行预置的聚合查询。
|
||||
- **采集核心指标**：
|
||||
- 本期各部门总花费及环比/同比变动率。
|
||||
- 各类目（如打车、机票、住宿、招待）的占比变化。
|
||||
- Top 10 花费最多的商户（如特定几家酒店或订票平台）。
|
||||
- 各类目超额/退回率最高的人员画像。
|
||||
|
||||
### 第二步：大模型归因分析 (LLM Attribution Analysis)
|
||||
将硬性的聚合数据转化为结构化 Prompt，让 LLM 充当“财务分析师”。
|
||||
- **Prompt 示例**：
|
||||
```markdown
|
||||
你是企业的财务总监助理，请阅读以下【本月报销聚合数据】。
|
||||
请帮我撰写一份 300 字以内的执行摘要报告。
|
||||
重点指出：
|
||||
1. 哪个部门/哪类费用增长最快？原因可能是什么？
|
||||
2. 我们的长尾开销集中在哪些商户？是否存在能够跟商户谈“协议价”的谈判空间？
|
||||
```
|
||||
|
||||
### 第三步：多渠道报告分发 (Report Delivery)
|
||||
- **生成制品**：Hermes 利用代码解释器 (如有) 或 Markdown 引擎，将图表与文本融合成正式的 PDF 或长图。
|
||||
- **触达渠道**：
|
||||
- **推送机制**：调用企微/钉钉机器人 API，直接向管理者的工作台推送“上周费控简报”。
|
||||
- **交互追问**：管理者收到简报卡片后，可以在对话框里直接@Hermes 追问：“详细列一下研发部上周在北京住宿的那 5 万块钱是怎么花的”，Hermes 将调取缓存的报告上下文立即答复。
|
||||
|
||||
## 3. 商业价值落地
|
||||
这项功能极大地解放了财务部的报表处理时间。通过提供前置的谈判线索（如发现某经济型酒店的高频住客其实都可以导流到协议酒店），可以给公司带来直接的差旅成本节约。
|
||||
@@ -1,63 +0,0 @@
|
||||
# 部署与任务调度架构方案 (Deployment & Cron)
|
||||
|
||||
## 1. 业务诉求分析
|
||||
Hermes 作为纯后台的智能体，它的执行过程长达几分钟甚至几小时。它绝不能与提供给前台 HTTP 请求的主 Web 服务混合在同一个事件循环（Event Loop）或同步进程中，否则会导致 API 严重堵塞和超时崩溃。
|
||||
|
||||
因此，Hermes 的部署需要进行**进程级解耦**。
|
||||
|
||||
## 2. 选型对比与推荐方案
|
||||
|
||||
### 方案 A：Celery + Redis (重型/工业级标准)
|
||||
- **优势**：业界最成熟的 Python 异步任务队列，支持极其复杂的 Cron 配置，原生支持任务重试、失败回调以及分布式扩展。
|
||||
- **劣势**：增加系统组件（必须额外部署 Redis / RabbitMQ 容器），运维成本相对较高。
|
||||
- **结论**：如果 X-Financial 后续要承载上千人的企业报销，这是**首选必经之路**。
|
||||
|
||||
### 方案 B：APScheduler + Background Worker (中型/轻量级)
|
||||
- **优势**：直接在 Python 进程内运行，无需额外的消息队列组件。可以用一个单独的 Docker 容器运行 `python run_hermes_scheduler.py`。
|
||||
- **劣势**：多节点部署时难以控制并发（可能会多个节点同时执行同样的任务），需要引入基于数据库表或 Redis 的分布式锁。
|
||||
- **结论**：适合初期快速跑通 MVP 的方案。
|
||||
|
||||
## 3. 推荐架构：基于 Redis 分布式锁的独立容器方案
|
||||
结合当前现状，建议采用 **方案B 叠加 分布式锁** 的轻量微服务架构。
|
||||
|
||||
### 部署拓扑：
|
||||
```yaml
|
||||
# docker-compose.yml 示例切片
|
||||
services:
|
||||
x-financial-api:
|
||||
build: .
|
||||
command: uvicorn main:app
|
||||
ports:
|
||||
- "8000:8000"
|
||||
|
||||
x-financial-hermes:
|
||||
build: .
|
||||
command: python scripts/start_hermes_daemon.py
|
||||
# 这个容器不暴露外部端口，纯粹在后台运行定时任务和消费队列
|
||||
```
|
||||
|
||||
### 执行伪代码 (`start_hermes_daemon.py`)
|
||||
```python
|
||||
from apscheduler.schedulers.blocking import BlockingScheduler
|
||||
from app.services.system_hermes import SystemHermesService
|
||||
|
||||
scheduler = BlockingScheduler()
|
||||
hermes = SystemHermesService()
|
||||
|
||||
# 每天凌晨 3 点执行深度风控扫表
|
||||
@scheduler.scheduled_job('cron', hour=3, minute=0)
|
||||
def job_risk_scan():
|
||||
# 获取分布式锁防止集群脑裂重复执行
|
||||
if acquire_redis_lock("hermes:lock:risk_scan"):
|
||||
try:
|
||||
hermes.run_query("执行全局风控扫描技能...", skills=["global_risk_scan"])
|
||||
finally:
|
||||
release_redis_lock("hermes:lock:risk_scan")
|
||||
|
||||
if __name__ == "__main__":
|
||||
scheduler.start()
|
||||
```
|
||||
|
||||
## 4. 容灾与可观测性保障
|
||||
- **日志采集**：确保 `hermes.run_query` 及其后台生成的 stdout/stderr 日志能够写入 ELK 或文件系统中，方便第二天的运维排查。
|
||||
- **告警链路**：如果调度系统挂掉或者大模型连续多次返回失败状态码，必须通过 Webhook 飞书/钉钉及时告警系统管理员。
|
||||
@@ -1,56 +0,0 @@
|
||||
# Knowledge Answers TODO
|
||||
|
||||
更新时间：2026-05-16
|
||||
|
||||
目标：
|
||||
- 让知识库问答的主路径从“LightRAG 检索 + 慢模型二次整理”改为“结构化证据优先 + 模型可选总结”。
|
||||
- 让问答能力尽量依赖当前文档内容本身，而不是依赖某一份制度、某一个城市或某一种表格写法。
|
||||
- 参考 Yuxi 的优点，优先补齐 `统一解析思路 + 文档类型友好的结构增强 + 检索后原文证据回退`，不照搬其完整平台基础设施。
|
||||
|
||||
Yuxi 调研结论：
|
||||
- [x] 已完成 Yuxi 调研与方案提炼
|
||||
备注：Yuxi 的通用性主要来自三层：统一文档解析、可切换的 chunk/preset、检索不足时回到解析后 Markdown 继续取证；并不是靠给某个文档写死回答逻辑。
|
||||
|
||||
本轮改造原则：
|
||||
- [x] 先撤掉文档特化硬编码，再补通用结构能力。
|
||||
- [x] 真实答案只能来自当前命中文档的内容，代码里不固化制度金额、地区档位或条款结论。
|
||||
- [x] 即使问题不是表格表达，也要能基于章节、条款、列表、键值对、上下文段落给出可读答案。
|
||||
- [x] 模型只负责“压缩表达”，不负责“凭空补事实”；模型超时时也必须能返回像样的证据型答复。
|
||||
|
||||
实施清单：
|
||||
- [x] 移除当前临时文档特化 fast path
|
||||
备注：删除当前围绕差旅表格、城市档位、职级档位的临时规则，避免系统继续向单文档 hardcode 演化。
|
||||
|
||||
- [x] 入库增强：补通用结构附录
|
||||
备注：参考 Yuxi 的解析/分块思想，在现有入库文本增强中补充章节、条款、列表、键值对、表格与上下文邻接信息，让非表格关系也能被稳定命中。
|
||||
|
||||
- [x] 检索后增强：生成面向回答的证据片段
|
||||
备注：从命中的 hits 中再次抽取更短、更结构化的 answer evidence，优先保留标题路径、条款句、列表项、表格行和与 query 强相关的上下文窗口。
|
||||
|
||||
- [x] 回答链路重构：证据驱动直答
|
||||
备注：新增通用知识问答直答器，先根据 answer evidence 生成可直接展示的短答案；只有在证据不足或问题需要更自然表达时才调用模型。
|
||||
|
||||
- [x] 模型总结收口：缩小上下文面，保留原文约束
|
||||
备注：把传给模型的上下文从“整段命中 chunk”收缩到“高置信 answer evidence”，既降延迟，也降低答非所问和错列风险。
|
||||
|
||||
- [x] 降级回答升级：从“命中摘抄”改成“证据摘要”
|
||||
备注：即使模型超时或失败，也要返回按证据组织好的结论、依据和缺失信息，而不是大段原文拼贴。
|
||||
|
||||
- [x] 测试补齐
|
||||
备注：覆盖非表格制度文本、表格文本、列表/键值对文本、模型超时降级、去除硬编码路径等关键回归点。
|
||||
|
||||
- [x] 真实验证与回填 TODO
|
||||
备注：已重建当前知识库索引并完成真实验证。当前“回答整理”阶段已降到亚秒级，但 LightRAG 首次/冷启动检索仍受 embedding 与 rerank 耗时影响，后续如要继续压缩总耗时，应进一步优化检索参数与模型链路。
|
||||
|
||||
验收标准：
|
||||
- [x] 常规知识问答不再长时间卡在“正在整理答案”。
|
||||
- [x] 文档不是表格表达时，仍能基于章节/条款/列表/上下文回答。
|
||||
- [x] 文档内容变动后，不需要改业务代码里的制度结论或金额常量。
|
||||
- [x] 模型超时时仍能返回结构清楚、证据明确的答案。
|
||||
- [x] 相关测试通过，且没有破坏现有知识库问答流程。
|
||||
|
||||
验证记录：
|
||||
- [x] 单测通过：`test_user_agent_service.py`、`test_knowledge_normalizer.py`、`test_knowledge_rag_service.py` 共 35 项全部通过。
|
||||
- [x] 当前知识库文档已按新规则 `force` 重建索引成功。
|
||||
- [x] 真实问答抽检：`餐补标准是什么？`、`费用发生后多久内提交报销申请？`、`前往北京出差的报销标准是什么？`
|
||||
备注：回答生成阶段约 `0.24s ~ 0.30s`；其中“前往北京出差”问题会明确提示当前证据未直接给出“北京”地区档位映射，不再硬猜。
|
||||
@@ -1,896 +0,0 @@
|
||||
<!doctype html>
|
||||
<html lang="zh-CN">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
<title>X-Financial 轻量知识库归集与问答优化开发文档</title>
|
||||
<style>
|
||||
:root {
|
||||
--green-900: #064e3b;
|
||||
--green-700: #047857;
|
||||
--green-600: #10b981;
|
||||
--green-100: #dff8ec;
|
||||
--green-50: #effcf6;
|
||||
--blue-700: #1d4ed8;
|
||||
--blue-50: #eff6ff;
|
||||
--amber-600: #d97706;
|
||||
--amber-50: #fffbeb;
|
||||
--red-600: #dc2626;
|
||||
--red-50: #fef2f2;
|
||||
--ink-900: #071124;
|
||||
--ink-700: #24324a;
|
||||
--ink-600: #58677f;
|
||||
--ink-500: #728098;
|
||||
--line: #dbe5ef;
|
||||
--line-strong: #c6d4e2;
|
||||
--surface: #ffffff;
|
||||
--surface-soft: #f7fafc;
|
||||
--shadow: 0 10px 26px rgba(15, 23, 42, 0.08);
|
||||
--radius: 8px;
|
||||
}
|
||||
|
||||
* {
|
||||
box-sizing: border-box;
|
||||
}
|
||||
|
||||
html {
|
||||
scroll-behavior: smooth;
|
||||
}
|
||||
|
||||
body {
|
||||
margin: 0;
|
||||
background:
|
||||
linear-gradient(180deg, rgba(239, 252, 246, 0.78), rgba(247, 250, 252, 0.96) 360px),
|
||||
var(--surface-soft);
|
||||
color: var(--ink-900);
|
||||
font-family: "IBM Plex Sans", "Microsoft YaHei UI", "Microsoft YaHei", "PingFang SC", sans-serif;
|
||||
line-height: 1.62;
|
||||
letter-spacing: 0;
|
||||
}
|
||||
|
||||
a {
|
||||
color: inherit;
|
||||
text-decoration: none;
|
||||
}
|
||||
|
||||
code {
|
||||
padding: 2px 6px;
|
||||
border-radius: 6px;
|
||||
background: rgba(15, 23, 42, 0.06);
|
||||
color: var(--ink-700);
|
||||
font-family: "JetBrains Mono", "Cascadia Code", Consolas, monospace;
|
||||
font-size: 0.92em;
|
||||
}
|
||||
|
||||
.shell {
|
||||
display: grid;
|
||||
grid-template-columns: 276px minmax(0, 1fr);
|
||||
min-height: 100dvh;
|
||||
}
|
||||
|
||||
.sidebar {
|
||||
position: sticky;
|
||||
top: 0;
|
||||
align-self: start;
|
||||
height: 100dvh;
|
||||
padding: 28px 22px;
|
||||
border-right: 1px solid var(--line);
|
||||
background: rgba(255, 255, 255, 0.86);
|
||||
backdrop-filter: blur(18px);
|
||||
overflow: auto;
|
||||
}
|
||||
|
||||
.brand {
|
||||
display: flex;
|
||||
gap: 12px;
|
||||
align-items: center;
|
||||
margin-bottom: 30px;
|
||||
}
|
||||
|
||||
.logo-mark {
|
||||
display: grid;
|
||||
width: 42px;
|
||||
height: 42px;
|
||||
place-items: center;
|
||||
border-radius: 8px;
|
||||
background: linear-gradient(145deg, var(--green-700), var(--green-600));
|
||||
color: #fff;
|
||||
font-weight: 800;
|
||||
box-shadow: 0 10px 18px rgba(16, 185, 129, 0.26);
|
||||
}
|
||||
|
||||
.brand-title {
|
||||
font-size: 15px;
|
||||
font-weight: 800;
|
||||
line-height: 1.2;
|
||||
}
|
||||
|
||||
.brand-subtitle {
|
||||
margin-top: 4px;
|
||||
color: var(--ink-500);
|
||||
font-size: 12px;
|
||||
}
|
||||
|
||||
.nav-label {
|
||||
margin: 22px 0 8px;
|
||||
color: var(--ink-500);
|
||||
font-size: 12px;
|
||||
font-weight: 700;
|
||||
}
|
||||
|
||||
.nav {
|
||||
display: grid;
|
||||
gap: 6px;
|
||||
}
|
||||
|
||||
.nav a {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
min-height: 38px;
|
||||
padding: 8px 10px;
|
||||
border-radius: 8px;
|
||||
color: var(--ink-700);
|
||||
font-size: 13px;
|
||||
font-weight: 650;
|
||||
}
|
||||
|
||||
.nav a:hover {
|
||||
background: var(--green-50);
|
||||
color: var(--green-900);
|
||||
}
|
||||
|
||||
.nav-dot {
|
||||
width: 7px;
|
||||
height: 7px;
|
||||
margin-right: 10px;
|
||||
border-radius: 999px;
|
||||
background: var(--line-strong);
|
||||
}
|
||||
|
||||
main {
|
||||
min-width: 0;
|
||||
padding: 34px 42px 56px;
|
||||
}
|
||||
|
||||
.hero {
|
||||
display: grid;
|
||||
grid-template-columns: minmax(0, 1.14fr) minmax(300px, 0.86fr);
|
||||
gap: 24px;
|
||||
align-items: stretch;
|
||||
margin-bottom: 24px;
|
||||
}
|
||||
|
||||
.hero-panel,
|
||||
.metric-panel,
|
||||
section,
|
||||
.card {
|
||||
border: 1px solid var(--line);
|
||||
border-radius: var(--radius);
|
||||
background: var(--surface);
|
||||
box-shadow: var(--shadow);
|
||||
}
|
||||
|
||||
.hero-panel {
|
||||
padding: 30px;
|
||||
border-color: rgba(16, 185, 129, 0.28);
|
||||
background:
|
||||
linear-gradient(135deg, rgba(255, 255, 255, 0.96), rgba(239, 252, 246, 0.9)),
|
||||
var(--surface);
|
||||
}
|
||||
|
||||
.kicker {
|
||||
display: inline-flex;
|
||||
align-items: center;
|
||||
min-height: 28px;
|
||||
padding: 4px 10px;
|
||||
border: 1px solid rgba(16, 185, 129, 0.24);
|
||||
border-radius: 999px;
|
||||
background: rgba(16, 185, 129, 0.1);
|
||||
color: var(--green-900);
|
||||
font-size: 12px;
|
||||
font-weight: 800;
|
||||
}
|
||||
|
||||
h1 {
|
||||
max-width: 780px;
|
||||
margin: 16px 0 14px;
|
||||
font-size: 34px;
|
||||
line-height: 1.18;
|
||||
letter-spacing: 0;
|
||||
}
|
||||
|
||||
.hero-copy,
|
||||
.section-desc,
|
||||
.card p,
|
||||
.phase span,
|
||||
.footnote {
|
||||
color: var(--ink-600);
|
||||
font-size: 14px;
|
||||
}
|
||||
|
||||
.hero-copy {
|
||||
max-width: 800px;
|
||||
margin: 0;
|
||||
font-size: 15px;
|
||||
}
|
||||
|
||||
.hero-actions {
|
||||
display: flex;
|
||||
flex-wrap: wrap;
|
||||
gap: 10px;
|
||||
margin-top: 22px;
|
||||
}
|
||||
|
||||
.pill {
|
||||
display: inline-flex;
|
||||
align-items: center;
|
||||
min-height: 32px;
|
||||
padding: 6px 11px;
|
||||
border-radius: 999px;
|
||||
background: #fff;
|
||||
border: 1px solid var(--line);
|
||||
color: var(--ink-700);
|
||||
font-size: 12px;
|
||||
font-weight: 750;
|
||||
}
|
||||
|
||||
.pill.primary {
|
||||
background: var(--green-700);
|
||||
border-color: var(--green-700);
|
||||
color: #fff;
|
||||
}
|
||||
|
||||
.metric-panel {
|
||||
display: grid;
|
||||
gap: 12px;
|
||||
padding: 18px;
|
||||
}
|
||||
|
||||
.metric {
|
||||
padding: 14px;
|
||||
border-radius: 8px;
|
||||
background: var(--surface-soft);
|
||||
border: 1px solid var(--line);
|
||||
}
|
||||
|
||||
.metric-label {
|
||||
color: var(--ink-500);
|
||||
font-size: 12px;
|
||||
font-weight: 700;
|
||||
}
|
||||
|
||||
.metric-value {
|
||||
margin-top: 5px;
|
||||
font-size: 18px;
|
||||
line-height: 1.28;
|
||||
font-weight: 800;
|
||||
}
|
||||
|
||||
section {
|
||||
margin-top: 18px;
|
||||
padding: 24px;
|
||||
}
|
||||
|
||||
.section-head {
|
||||
display: flex;
|
||||
gap: 18px;
|
||||
align-items: flex-start;
|
||||
justify-content: space-between;
|
||||
margin-bottom: 16px;
|
||||
}
|
||||
|
||||
.section-title {
|
||||
margin: 0 0 8px;
|
||||
font-size: 22px;
|
||||
line-height: 1.25;
|
||||
}
|
||||
|
||||
.section-desc {
|
||||
max-width: 920px;
|
||||
margin: 0;
|
||||
}
|
||||
|
||||
.tag {
|
||||
flex: 0 0 auto;
|
||||
min-height: 28px;
|
||||
padding: 4px 10px;
|
||||
border-radius: 999px;
|
||||
background: var(--green-50);
|
||||
color: var(--green-900);
|
||||
font-size: 12px;
|
||||
font-weight: 800;
|
||||
border: 1px solid rgba(16, 185, 129, 0.22);
|
||||
}
|
||||
|
||||
.grid-2,
|
||||
.grid-3,
|
||||
.grid-4 {
|
||||
display: grid;
|
||||
gap: 14px;
|
||||
}
|
||||
|
||||
.grid-2 {
|
||||
grid-template-columns: repeat(2, minmax(0, 1fr));
|
||||
}
|
||||
|
||||
.grid-3 {
|
||||
grid-template-columns: repeat(3, minmax(0, 1fr));
|
||||
}
|
||||
|
||||
.grid-4 {
|
||||
grid-template-columns: repeat(4, minmax(0, 1fr));
|
||||
}
|
||||
|
||||
.card {
|
||||
padding: 17px;
|
||||
box-shadow: none;
|
||||
}
|
||||
|
||||
.card h3 {
|
||||
margin: 0 0 10px;
|
||||
font-size: 16px;
|
||||
line-height: 1.3;
|
||||
}
|
||||
|
||||
.card p {
|
||||
margin: 0;
|
||||
}
|
||||
|
||||
.card ul,
|
||||
.card ol {
|
||||
margin: 0;
|
||||
padding-left: 18px;
|
||||
color: var(--ink-600);
|
||||
font-size: 14px;
|
||||
}
|
||||
|
||||
.card li + li {
|
||||
margin-top: 7px;
|
||||
}
|
||||
|
||||
.tone-green {
|
||||
background: var(--green-50);
|
||||
border-color: rgba(16, 185, 129, 0.26);
|
||||
}
|
||||
|
||||
.tone-blue {
|
||||
background: var(--blue-50);
|
||||
border-color: rgba(37, 99, 235, 0.18);
|
||||
}
|
||||
|
||||
.tone-amber {
|
||||
background: var(--amber-50);
|
||||
border-color: rgba(217, 119, 6, 0.2);
|
||||
}
|
||||
|
||||
.tone-red {
|
||||
background: var(--red-50);
|
||||
border-color: rgba(220, 38, 38, 0.16);
|
||||
}
|
||||
|
||||
.flow {
|
||||
display: grid;
|
||||
gap: 10px;
|
||||
margin-top: 6px;
|
||||
}
|
||||
|
||||
.flow-row {
|
||||
display: grid;
|
||||
grid-template-columns: 132px minmax(0, 1fr);
|
||||
gap: 12px;
|
||||
align-items: start;
|
||||
padding: 12px;
|
||||
border: 1px solid var(--line);
|
||||
border-radius: 8px;
|
||||
background: var(--surface-soft);
|
||||
}
|
||||
|
||||
.flow-key {
|
||||
color: var(--green-900);
|
||||
font-size: 13px;
|
||||
font-weight: 800;
|
||||
}
|
||||
|
||||
.flow-body {
|
||||
color: var(--ink-600);
|
||||
font-size: 14px;
|
||||
}
|
||||
|
||||
.diagram {
|
||||
padding: 16px;
|
||||
border: 1px solid var(--line);
|
||||
border-radius: 8px;
|
||||
background: #0f172a;
|
||||
color: #e5eef8;
|
||||
overflow-x: auto;
|
||||
font-family: "JetBrains Mono", "Cascadia Code", Consolas, monospace;
|
||||
font-size: 13px;
|
||||
line-height: 1.65;
|
||||
white-space: pre;
|
||||
}
|
||||
|
||||
.timeline {
|
||||
display: grid;
|
||||
gap: 12px;
|
||||
}
|
||||
|
||||
.phase {
|
||||
display: grid;
|
||||
grid-template-columns: 150px minmax(0, 1fr);
|
||||
gap: 14px;
|
||||
padding: 14px;
|
||||
border: 1px solid var(--line);
|
||||
border-radius: 8px;
|
||||
background: var(--surface-soft);
|
||||
}
|
||||
|
||||
.phase-key {
|
||||
color: var(--green-900);
|
||||
font-size: 13px;
|
||||
font-weight: 850;
|
||||
}
|
||||
|
||||
.phase-body strong {
|
||||
display: block;
|
||||
margin-bottom: 4px;
|
||||
color: var(--ink-900);
|
||||
font-size: 15px;
|
||||
}
|
||||
|
||||
.checklist {
|
||||
display: grid;
|
||||
gap: 10px;
|
||||
}
|
||||
|
||||
.check {
|
||||
position: relative;
|
||||
padding: 12px 12px 12px 34px;
|
||||
border: 1px solid var(--line);
|
||||
border-radius: 8px;
|
||||
background: var(--surface-soft);
|
||||
color: var(--ink-700);
|
||||
font-size: 14px;
|
||||
}
|
||||
|
||||
.check::before {
|
||||
content: "";
|
||||
position: absolute;
|
||||
left: 13px;
|
||||
top: 17px;
|
||||
width: 8px;
|
||||
height: 8px;
|
||||
border-radius: 999px;
|
||||
background: var(--green-600);
|
||||
}
|
||||
|
||||
.link-list {
|
||||
display: flex;
|
||||
flex-wrap: wrap;
|
||||
gap: 10px;
|
||||
margin-top: 14px;
|
||||
}
|
||||
|
||||
.link-chip {
|
||||
display: inline-flex;
|
||||
align-items: center;
|
||||
min-height: 30px;
|
||||
padding: 5px 10px;
|
||||
border: 1px solid var(--line);
|
||||
border-radius: 999px;
|
||||
background: #fff;
|
||||
color: var(--ink-700);
|
||||
font-size: 12px;
|
||||
font-weight: 750;
|
||||
}
|
||||
|
||||
.link-chip:hover {
|
||||
border-color: rgba(16, 185, 129, 0.5);
|
||||
color: var(--green-900);
|
||||
}
|
||||
|
||||
footer {
|
||||
margin-top: 22px;
|
||||
color: var(--ink-500);
|
||||
font-size: 12px;
|
||||
text-align: center;
|
||||
}
|
||||
|
||||
@media (max-width: 1080px) {
|
||||
.shell {
|
||||
grid-template-columns: 1fr;
|
||||
}
|
||||
|
||||
.sidebar {
|
||||
position: static;
|
||||
height: auto;
|
||||
border-right: 0;
|
||||
border-bottom: 1px solid var(--line);
|
||||
}
|
||||
|
||||
.hero,
|
||||
.grid-2,
|
||||
.grid-3,
|
||||
.grid-4 {
|
||||
grid-template-columns: 1fr;
|
||||
}
|
||||
|
||||
main {
|
||||
padding: 24px 18px 42px;
|
||||
}
|
||||
}
|
||||
|
||||
@media (max-width: 680px) {
|
||||
h1 {
|
||||
font-size: 28px;
|
||||
}
|
||||
|
||||
.section-head,
|
||||
.phase,
|
||||
.flow-row {
|
||||
grid-template-columns: 1fr;
|
||||
}
|
||||
|
||||
.section-head {
|
||||
display: grid;
|
||||
}
|
||||
}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div class="shell">
|
||||
<aside class="sidebar">
|
||||
<div class="brand">
|
||||
<div class="logo-mark">KB</div>
|
||||
<div>
|
||||
<div class="brand-title">轻量知识库归集</div>
|
||||
<div class="brand-subtitle">LightRAG + Hermes 优化方案</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="nav-label">文档导航</div>
|
||||
<nav class="nav">
|
||||
<a href="#position"><span class="nav-dot"></span>定位与边界</a>
|
||||
<a href="#architecture"><span class="nav-dot"></span>轻量架构</a>
|
||||
<a href="#borrow"><span class="nav-dot"></span>Yuxi 借鉴点</a>
|
||||
<a href="#modules"><span class="nav-dot"></span>模块设计</a>
|
||||
<a href="#retrieval"><span class="nav-dot"></span>召回与回答</a>
|
||||
<a href="#delivery"><span class="nav-dot"></span>实施路线</a>
|
||||
<a href="#quality"><span class="nav-dot"></span>验收标准</a>
|
||||
</nav>
|
||||
|
||||
<div class="nav-label">硬约束</div>
|
||||
<div class="nav">
|
||||
<a href="#quality"><span class="nav-dot"></span>不做重平台</a>
|
||||
<a href="#quality"><span class="nav-dot"></span>证据优先回答</a>
|
||||
<a href="#quality"><span class="nav-dot"></span>增量任务可追踪</a>
|
||||
</div>
|
||||
</aside>
|
||||
|
||||
<main>
|
||||
<div class="hero">
|
||||
<div class="hero-panel">
|
||||
<span class="kicker">开发文档 · 先定边界再实现</span>
|
||||
<h1>X-Financial 轻量知识库归集与问答优化方案</h1>
|
||||
<p class="hero-copy">
|
||||
本方案不把 X-Financial 改造成专业知识库平台，而是在现有
|
||||
<code>LightRAG</code>、<code>Hermes</code>、<code>AgentRun</code>
|
||||
和知识库 UI 上补齐最薄弱的归集、分块、召回和证据回答能力。
|
||||
Yuxi 只作为成熟设计参考，借鉴其统一解析、分块预设和评估思想。
|
||||
</p>
|
||||
<div class="hero-actions">
|
||||
<span class="pill primary">保留现有 LightRAG</span>
|
||||
<span class="pill">轻量 Parser</span>
|
||||
<span class="pill">条款级分块</span>
|
||||
<span class="pill">混合召回</span>
|
||||
<span class="pill">证据化回答</span>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="metric-panel">
|
||||
<div class="metric">
|
||||
<div class="metric-label">核心目标</div>
|
||||
<div class="metric-value">准、快、可解释</div>
|
||||
</div>
|
||||
<div class="metric">
|
||||
<div class="metric-label">改造范围</div>
|
||||
<div class="metric-value">归集与召回链路，不重做平台</div>
|
||||
</div>
|
||||
<div class="metric">
|
||||
<div class="metric-label">并发预期</div>
|
||||
<div class="metric-value">5-10 用户查询可降级、有上限</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<section id="position">
|
||||
<div class="section-head">
|
||||
<div>
|
||||
<h2 class="section-title">定位与边界</h2>
|
||||
<p class="section-desc">
|
||||
知识库在 X-Financial 中是业务辅助能力，不是独立知识管理产品。
|
||||
因此实现必须克制：不引入重型多租户平台，不替换现有业务数据模型，
|
||||
不把知识库 UI 做成复杂后台，只补齐影响问答质量的关键薄层。
|
||||
</p>
|
||||
</div>
|
||||
<span class="tag">轻量优先</span>
|
||||
</div>
|
||||
|
||||
<div class="grid-3">
|
||||
<div class="card tone-green">
|
||||
<h3>要解决的问题</h3>
|
||||
<ul>
|
||||
<li>Word、PDF、Excel 等文件进入 RAG 前缺少统一结构。</li>
|
||||
<li>制度类文档如果按普通 chunk 切分，条款容易被切散。</li>
|
||||
<li>问答质量依赖向量召回，缺少关键词、标题、条款补召回。</li>
|
||||
<li>效果优化缺少固定评测集，容易靠体感判断。</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="card tone-blue">
|
||||
<h3>保留的现有能力</h3>
|
||||
<ul>
|
||||
<li><code>KnowledgeService</code> 继续负责文件库和状态入口。</li>
|
||||
<li><code>KnowledgeRagService</code> 继续封装 LightRAG 查询和入库。</li>
|
||||
<li><code>KnowledgeIndexTaskManager</code> 继续承接 Hermes 增量任务。</li>
|
||||
<li>前端知识管理继续保持简单文件夹与文件列表形态。</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="card tone-amber">
|
||||
<h3>明确不做</h3>
|
||||
<ul>
|
||||
<li>不整体引入 Yuxi 平台。</li>
|
||||
<li>不把存储改成 Milvus + Neo4j。</li>
|
||||
<li>不一次性接入全量 OCR 引擎。</li>
|
||||
<li>不新增复杂多租户知识库后台。</li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<section id="architecture">
|
||||
<div class="section-head">
|
||||
<div>
|
||||
<h2 class="section-title">轻量架构</h2>
|
||||
<p class="section-desc">
|
||||
新增能力只放在 LightRAG 前后两侧：前侧负责把文件变成稳定 Markdown 和业务友好 chunk，
|
||||
后侧负责混合召回、证据重排和可靠回答。LightRAG 仍是主召回核心。
|
||||
</p>
|
||||
</div>
|
||||
<span class="tag">薄层增强</span>
|
||||
</div>
|
||||
|
||||
<div class="diagram">原始文件
|
||||
├── docx / pdf / xlsx / pptx / csv / txt
|
||||
↓
|
||||
轻量 Parser
|
||||
├── 统一 Markdown
|
||||
├── 表格上下文
|
||||
└── 页码 / sheet / 条款路径
|
||||
↓
|
||||
Chunk Preset
|
||||
├── laws：制度条款
|
||||
├── qa：常见问答
|
||||
└── table：表格行组
|
||||
↓
|
||||
现有 LightRAG / Qdrant
|
||||
↓
|
||||
混合召回
|
||||
├── LightRAG 语义召回
|
||||
├── 标题与条款关键词召回
|
||||
└── 轻量重排 top 3-5
|
||||
↓
|
||||
证据化回答
|
||||
├── 命中证据
|
||||
├── 直接结论
|
||||
└── 缺失信息说明</div>
|
||||
</section>
|
||||
|
||||
<section id="borrow">
|
||||
<div class="section-head">
|
||||
<div>
|
||||
<h2 class="section-title">Yuxi 借鉴点</h2>
|
||||
<p class="section-desc">
|
||||
Yuxi 的价值不在于整套平台，而在于成熟的归集分层思想：
|
||||
文件先解析成 Markdown，再按场景分块，再索引，再评估。
|
||||
这些思想可以小规模落地到现有服务内。
|
||||
</p>
|
||||
</div>
|
||||
<span class="tag">借鉴而非搬运</span>
|
||||
</div>
|
||||
|
||||
<div class="grid-4">
|
||||
<div class="card">
|
||||
<h3>统一 Parser</h3>
|
||||
<p>学习 Yuxi 把多格式文件统一转 Markdown 的入口设计，但只实现 X-Financial 当前需要的格式。</p>
|
||||
</div>
|
||||
<div class="card">
|
||||
<h3>分块 Preset</h3>
|
||||
<p>借鉴 RAGFlow-like preset。先做 <code>laws</code>、<code>qa</code>、<code>table</code> 三类。</p>
|
||||
</div>
|
||||
<div class="card">
|
||||
<h3>两阶段状态</h3>
|
||||
<p>内部区分解析和索引。UI 仍可显示简单归纳状态，后台记录真实失败点。</p>
|
||||
</div>
|
||||
<div class="card">
|
||||
<h3>轻量评测</h3>
|
||||
<p>不做评估平台，只维护 JSON 用例和脚本，持续检查召回与回答质量。</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="link-list">
|
||||
<a class="link-chip" href="https://github.com/xerrors/Yuxi">Yuxi README</a>
|
||||
<a class="link-chip" href="https://github.com/xerrors/Yuxi/blob/main/backend/package/yuxi/plugins/parser/unified.py">Yuxi unified parser</a>
|
||||
<a class="link-chip" href="https://github.com/xerrors/Yuxi/blob/main/backend/package/yuxi/knowledge/chunking/ragflow_like/presets.py">Yuxi chunk presets</a>
|
||||
<a class="link-chip" href="https://github.com/xerrors/Yuxi/blob/main/backend/package/yuxi/knowledge/chunking/ragflow_like/parsers/laws.py">Yuxi laws parser</a>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<section id="modules">
|
||||
<div class="section-head">
|
||||
<div>
|
||||
<h2 class="section-title">模块设计</h2>
|
||||
<p class="section-desc">
|
||||
新增模块必须小而清楚，避免把逻辑继续堆进单个 Service。
|
||||
单个核心文件控制在 800 行以内，优先按解析、分块、召回、评测拆分。
|
||||
</p>
|
||||
</div>
|
||||
<span class="tag">职责拆分</span>
|
||||
</div>
|
||||
|
||||
<div class="flow">
|
||||
<div class="flow-row">
|
||||
<div class="flow-key">knowledge_parser.py</div>
|
||||
<div class="flow-body">
|
||||
负责把 docx、pdf、xlsx、csv、txt 等文件转成 Markdown。
|
||||
输出正文、标题路径、页码、sheet、表头、解析告警。
|
||||
</div>
|
||||
</div>
|
||||
<div class="flow-row">
|
||||
<div class="flow-key">knowledge_chunking.py</div>
|
||||
<div class="flow-body">
|
||||
根据文件夹、文件类型和文档特征选择分块策略。
|
||||
第一批只实现制度、问答、表格三类。
|
||||
</div>
|
||||
</div>
|
||||
<div class="flow-row">
|
||||
<div class="flow-key">knowledge_retrieval.py</div>
|
||||
<div class="flow-body">
|
||||
在 LightRAG 命中结果外补充关键词、条款标题和文件名召回。
|
||||
最终输出小而准的证据块。
|
||||
</div>
|
||||
</div>
|
||||
<div class="flow-row">
|
||||
<div class="flow-key">knowledge_eval.py</div>
|
||||
<div class="flow-body">
|
||||
读取轻量评测用例，检查 expected 文件、关键词、证据和答案约束。
|
||||
用于每次调整参数后的回归验证。
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<section id="retrieval">
|
||||
<div class="section-head">
|
||||
<div>
|
||||
<h2 class="section-title">召回与回答策略</h2>
|
||||
<p class="section-desc">
|
||||
目标不是让模型更会猜，而是让系统给模型更可靠的证据。
|
||||
制度问题优先命中条款，表格问题保留表头与行上下文，回答必须暴露依据和缺失信息。
|
||||
</p>
|
||||
</div>
|
||||
<span class="tag">证据优先</span>
|
||||
</div>
|
||||
|
||||
<div class="grid-3">
|
||||
<div class="card tone-green">
|
||||
<h3>召回层</h3>
|
||||
<ul>
|
||||
<li>LightRAG 继续提供语义召回。</li>
|
||||
<li>条款号、标题、文件名、关键词做补召回。</li>
|
||||
<li>召回候选数量有上限，避免并发下无限扩张。</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="card tone-blue">
|
||||
<h3>重排层</h3>
|
||||
<ul>
|
||||
<li>优先保留含问题关键词、标题路径和条款语义的块。</li>
|
||||
<li>制度类按条款完整度加权。</li>
|
||||
<li>最终给回答链路 3-5 条高质量证据。</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="card tone-amber">
|
||||
<h3>回答层</h3>
|
||||
<ul>
|
||||
<li>能直接基于证据回答时，不强制二次模型整理。</li>
|
||||
<li>模型只做压缩表达，不凭空补事实。</li>
|
||||
<li>证据不足时明确说明缺什么。</li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<section id="delivery">
|
||||
<div class="section-head">
|
||||
<div>
|
||||
<h2 class="section-title">实施路线</h2>
|
||||
<p class="section-desc">
|
||||
分四步小步交付。每一步都能单独验证，不把解析、索引、召回和评测揉成一次大改。
|
||||
</p>
|
||||
</div>
|
||||
<span class="tag">渐进落地</span>
|
||||
</div>
|
||||
|
||||
<div class="timeline">
|
||||
<div class="phase">
|
||||
<div class="phase-key">P0 / 文档落地</div>
|
||||
<div class="phase-body">
|
||||
<strong>先明确轻量边界</strong>
|
||||
<span>完成本文档，确认不做重平台、不替换存储、不一次性引入复杂 OCR。</span>
|
||||
</div>
|
||||
</div>
|
||||
<div class="phase">
|
||||
<div class="phase-key">P1 / 统一解析</div>
|
||||
<div class="phase-body">
|
||||
<strong>补齐文件归集质量</strong>
|
||||
<span>新增 Parser，把 Word、PDF、Excel、CSV、TXT 稳定转为 Markdown，并保存解析产物供索引复用。</span>
|
||||
</div>
|
||||
</div>
|
||||
<div class="phase">
|
||||
<div class="phase-key">P2 / 场景分块</div>
|
||||
<div class="phase-body">
|
||||
<strong>提升制度与表格命中率</strong>
|
||||
<span>实现 laws、qa、table 三类分块。制度按章、节、条、款保留完整语义，表格保留 sheet、表头和行上下文。</span>
|
||||
</div>
|
||||
</div>
|
||||
<div class="phase">
|
||||
<div class="phase-key">P3 / 混合召回</div>
|
||||
<div class="phase-body">
|
||||
<strong>减少答偏和漏召回</strong>
|
||||
<span>在 LightRAG 命中外补充关键词、条款标题、文件名召回，输出可控数量的证据块。</span>
|
||||
</div>
|
||||
</div>
|
||||
<div class="phase">
|
||||
<div class="phase-key">P4 / 轻量评测</div>
|
||||
<div class="phase-body">
|
||||
<strong>把效果优化变成可回归</strong>
|
||||
<span>建设 30-50 条远光软件制度风格问答用例，覆盖报销、差旅、发票、预算、税务等高频问题。</span>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<section id="quality">
|
||||
<div class="section-head">
|
||||
<div>
|
||||
<h2 class="section-title">验收标准</h2>
|
||||
<p class="section-desc">
|
||||
验收不只看页面状态，而要看文件是否真实入库、召回是否命中文档依据、
|
||||
回答是否引用证据，以及并发访问时是否能稳定降级。
|
||||
</p>
|
||||
</div>
|
||||
<span class="tag">真实验证</span>
|
||||
</div>
|
||||
|
||||
<div class="checklist">
|
||||
<div class="check">Word、PDF、Excel、CSV、TXT 文件能生成可读 Markdown，且解析产物可复用。</div>
|
||||
<div class="check">制度类文件能按章、节、条、款形成相对完整的证据块。</div>
|
||||
<div class="check">Excel 表格问答能保留 sheet、表头、关键列和业务行上下文。</div>
|
||||
<div class="check">Hermes 增量任务能区分解析失败、索引失败和归纳失败。</div>
|
||||
<div class="check">常见制度问答优先返回证据化直接答案，模型超时时仍有可读降级答案。</div>
|
||||
<div class="check">5-10 个用户同时访问时，查询候选数、重排数、模型调用数都有明确上限。</div>
|
||||
<div class="check">轻量评测集覆盖至少 30 条问题，并记录命中文件、关键词和答案约束。</div>
|
||||
<div class="check">不引入 Yuxi 平台级依赖，不改变现有知识库 UI 的主体交互。</div>
|
||||
</div>
|
||||
|
||||
<p class="footnote">
|
||||
后续实现时，优先在现有定向测试基础上补充 Parser、Chunking、Retrieval 和 Knowledge Eval 的小测试。
|
||||
后端验证优先在 Docker 容器 <code>x-financial-main</code> 中运行。
|
||||
</p>
|
||||
</section>
|
||||
|
||||
<footer>
|
||||
X-Financial 轻量知识库归集与问答优化开发文档 · 放置位置：document/development/knowledge-answers/lightweight-knowledge-ingestion-design.html
|
||||
</footer>
|
||||
</main>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
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: 功能一句话] 确认最终实现没有偏离“解释图和执行逻辑一致”的核心目标。
|
||||
@@ -1,139 +0,0 @@
|
||||
# 差旅报销风险管控标准（模拟版）
|
||||
|
||||
## 1. 目的
|
||||
|
||||
本标准用于约束个人报销中的差旅类单据审核，覆盖以下三类核心风险：
|
||||
|
||||
- 行程闭环风险：出发地、目的地、返程地之间是否形成合理链路。
|
||||
- 票据地点一致性风险：酒店、交通票据与申报目的地是否一致。
|
||||
- 差标超限风险：员工职级对应的交通舱位、火车席别、住宿金额是否超标。
|
||||
|
||||
本标准先以模拟规则落地到系统，用于 AI 验审与直属领导审批前的自动筛查。
|
||||
|
||||
## 2. 适用范围
|
||||
|
||||
- 报销主类型为 `travel / hotel / transport` 的单据。
|
||||
- 或者明细附件识别出 `flight_itinerary / train_ticket / hotel_invoice / taxi_receipt / parking_toll_receipt` 的单据。
|
||||
|
||||
## 3. 基础定义
|
||||
|
||||
### 3.1 目的地
|
||||
|
||||
按以下优先级确定本次差旅的“主目的地”：
|
||||
|
||||
1. 用户在报销表单中填写的业务地点 `claim.location`
|
||||
2. 长途交通票据终点城市
|
||||
3. 酒店票据识别出的酒店所在城市
|
||||
|
||||
### 3.2 行程闭环
|
||||
|
||||
满足以下任一条件，视为形成合理闭环：
|
||||
|
||||
- 单程票据终点与申报目的地一致。
|
||||
- 多段票据按时间顺序首尾衔接。
|
||||
- 最后一段票据返回首段出发城市。
|
||||
|
||||
### 3.3 合理例外说明
|
||||
|
||||
若出现多城市出差、中转、改签、异地返程、展会高峰导致超标等情况，用户必须在报销事由或费用说明中体现原因。示例关键词：
|
||||
|
||||
- `中转`
|
||||
- `转机`
|
||||
- `经停`
|
||||
- `改签`
|
||||
- `多地出差`
|
||||
- `客户临时变更`
|
||||
- `展会高峰`
|
||||
- `协议酒店满房`
|
||||
- `无直达`
|
||||
|
||||
未说明时，系统按高风险处理并退回待补充。
|
||||
|
||||
## 4. 风险规则矩阵
|
||||
|
||||
### 4.1 行程闭环规则
|
||||
|
||||
- 若存在两段及以上长途交通票据，相邻两段的 `上一段终点城市` 与 `下一段起点城市` 必须一致。
|
||||
- 若最终到达城市既不是申报目的地，也不是首段出发城市，则判定为高风险。
|
||||
- 若识别到多个目的地城市，但事由中未说明多地出差、中转或改签原因，则判定为高风险。
|
||||
|
||||
处理方式：
|
||||
|
||||
- `高风险`：退回待补充。
|
||||
- `中风险`：允许流转，但要求直属领导重点复核。
|
||||
|
||||
### 4.2 酒店地点一致性规则
|
||||
|
||||
- 酒店票据识别出的城市，必须属于以下集合之一：
|
||||
- 申报目的地
|
||||
- 长途交通票据中的目的地城市
|
||||
- 长途交通票据中的返程前停留城市
|
||||
- 若酒店城市与主目的地、交通链路均不一致，则判定为高风险。
|
||||
|
||||
处理方式：
|
||||
|
||||
- `高风险`：退回待补充，要求说明异地住宿原因或更换票据。
|
||||
|
||||
### 4.3 职级差旅标准
|
||||
|
||||
#### 4.3.1 城市分级
|
||||
|
||||
- 一线：`北京 / 上海 / 广州 / 深圳`
|
||||
- 新一线 / 重点城市：`杭州 / 南京 / 苏州 / 武汉 / 成都 / 重庆 / 西安 / 天津 / 宁波 / 厦门 / 青岛 / 长沙`
|
||||
- 其他城市：除以上外的默认城市
|
||||
|
||||
#### 4.3.2 住宿标准（元 / 晚）
|
||||
|
||||
| 职级带 | 一线 | 重点城市 | 其他城市 |
|
||||
| --- | ---: | ---: | ---: |
|
||||
| P1-P3 | 450 | 380 | 320 |
|
||||
| P4-P5 | 550 | 480 | 380 |
|
||||
| P6-P7 | 700 | 620 | 520 |
|
||||
| M1-M2 | 900 | 820 | 720 |
|
||||
| M3 及以上 / D 序列 | 1200 | 1000 | 900 |
|
||||
|
||||
说明：
|
||||
|
||||
- 若票据中能识别出 `X 晚 / X 间夜`，系统按 `总金额 / 间夜数` 计算每晚金额。
|
||||
- 若无法识别间夜数，默认按 1 晚处理。
|
||||
|
||||
#### 4.3.3 交通标准
|
||||
|
||||
| 职级带 | 飞机 | 火车 / 高铁 |
|
||||
| --- | --- | --- |
|
||||
| P1-P3 | 经济舱 | 二等座 / 硬卧 |
|
||||
| P4-P5 | 经济舱 | 二等座 / 硬卧 |
|
||||
| P6-P7 | 超级经济舱及以下 | 一等座 / 软卧及以下 |
|
||||
| M1-M2 | 商务舱及以下 | 商务座及以下 |
|
||||
| M3 及以上 / D 序列 | 不做系统硬限制，仍保留人工复核 |
|
||||
|
||||
### 4.4 差标超限处理
|
||||
|
||||
- 超住宿标准且无说明：`高风险`
|
||||
- 超住宿标准但有说明：`中风险`
|
||||
- 飞机舱位或高铁席别超过职级标准且无说明：`高风险`
|
||||
- 飞机舱位或高铁席别超过职级标准但有说明：`中风险`
|
||||
|
||||
## 5. 系统落地口径
|
||||
|
||||
### 5.1 票据识别字段
|
||||
|
||||
系统优先使用以下字段做判断：
|
||||
|
||||
- `route`
|
||||
- `merchant_name`
|
||||
- `amount`
|
||||
- `date`
|
||||
- OCR 原文中的舱位、席别、间夜数、城市名
|
||||
|
||||
### 5.2 AI 验审动作
|
||||
|
||||
- 高风险：提交前拦截，状态切回 `待补充`
|
||||
- 中风险：允许进入直属领导审批，并附带风险标记
|
||||
- 低风险 / 通过：正常流转
|
||||
|
||||
## 6. 当前实现边界
|
||||
|
||||
- 城市识别先按常见出差城市做匹配，未覆盖全国全部区县。
|
||||
- 住宿标准与交通标准为模拟版，可后续迁移到任务规则中心做可配置化。
|
||||
- 本文档为当前开发阶段的执行依据，后续若规则中心启用动态配置，应以规则中心版本为准。
|
||||
@@ -1,453 +0,0 @@
|
||||
# 规则版本中心 UI 方案
|
||||
|
||||
## 1. 背景
|
||||
|
||||
当前“任务规则中心 > 财务规则 > 公司差旅费报销规则”已经具备：
|
||||
|
||||
- 在线 Excel 编辑
|
||||
- 工作版本 / 线上版本分离
|
||||
- 最近 5 个版本展示
|
||||
- 审核、上线、恢复能力
|
||||
|
||||
但页面仍然存在一个明显问题：
|
||||
**版本治理能力已经有了，用户却很难第一眼看见。**
|
||||
|
||||
当前版本列表更像“历史记录”，不是一个明确的“版本操作中心”。
|
||||
用户无法快速判断：
|
||||
|
||||
1. 当前真正生效的是哪个版本
|
||||
2. 当前正在编辑的是哪个版本
|
||||
3. 从哪里进入版本切换
|
||||
4. 从哪里发起版本对比
|
||||
5. 某个版本经历了哪些流转动作
|
||||
|
||||
因此，需要把现有“版本列表”升级为一个真正可用的 **版本中心**。
|
||||
|
||||
---
|
||||
|
||||
## 2. 设计目标
|
||||
|
||||
### 2.1 用户一眼能看懂
|
||||
|
||||
进入规则详情页后，用户无需点击就能立即识别：
|
||||
|
||||
- 当前线上版本
|
||||
- 当前工作版本
|
||||
- 是否存在未上线工作稿
|
||||
- 最近版本是否处于待审 / 已通过 / 已驳回状态
|
||||
|
||||
### 2.2 关键操作显性化
|
||||
|
||||
以下操作不能再隐藏在不明显的位置：
|
||||
|
||||
- 切换查看版本
|
||||
- 与线上版本对比
|
||||
- 查看完整流转
|
||||
- 从历史版本恢复
|
||||
|
||||
### 2.3 保持 OnlyOffice 是主角
|
||||
|
||||
该页面的核心仍然是 Excel 规则表。
|
||||
版本中心必须增强治理能力，但不能把主表格压缩成附属内容。
|
||||
|
||||
---
|
||||
|
||||
## 3. 推荐方案
|
||||
|
||||
采用：
|
||||
|
||||
> **左侧 OnlyOffice 主工作区 + 右侧版本中心 + 顶部显性入口 + 抽屉式详情**
|
||||
|
||||
这是比“单独开二级页签”更适合当前页面的方案，因为用户经常需要：
|
||||
|
||||
- 一边看表
|
||||
- 一边知道自己看的是什么版本
|
||||
- 一边进入版本对比或恢复
|
||||
|
||||
---
|
||||
|
||||
## 4. 页面整体布局
|
||||
|
||||
```text
|
||||
┌────────────────────────────────────────────────────────────────────┐
|
||||
│ 标题区：公司差旅费报销规则 │
|
||||
│ 线上版本 v1.0.5 已上线 工作版本 v1.0.6 待审核 │
|
||||
│ [下载 Excel] [上传表格] [版本对比] [查看流转] │
|
||||
├───────────────────────────────────────────────┬────────────────────┤
|
||||
│ │ 版本中心 │
|
||||
│ │ │
|
||||
│ │ ┌──────────────┐ │
|
||||
│ │ │ 线上版本 │ │
|
||||
│ │ │ v1.0.5 │ │
|
||||
│ │ └──────────────┘ │
|
||||
│ OnlyOffice │ ┌──────────────┐ │
|
||||
│ 规则表主工作区 │ │ 工作版本 │ │
|
||||
│ │ │ v1.0.6 │ │
|
||||
│ │ └──────────────┘ │
|
||||
│ │ │
|
||||
│ │ 最近版本 │
|
||||
│ │ v1.0.6 待审核 │
|
||||
│ │ v1.0.5 已上线 │
|
||||
│ │ v1.0.4 历史版本 │
|
||||
│ │ │
|
||||
│ │ 最近流转 │
|
||||
│ │ [查看完整流转] │
|
||||
└───────────────────────────────────────────────┴────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 顶部操作区设计
|
||||
|
||||
顶部必须保留并强化四个动作：
|
||||
|
||||
| 按钮 | 用途 |
|
||||
| --- | --- |
|
||||
| 下载 Excel | 下载当前预览版本 |
|
||||
| 上传表格 | 导入内容生成新工作稿 |
|
||||
| 版本对比 | 打开对比抽屉 |
|
||||
| 查看流转 | 打开流转抽屉 |
|
||||
|
||||
### 5.1 版本对比按钮
|
||||
|
||||
这是一级入口，不能只藏在版本列表里。
|
||||
默认行为：
|
||||
|
||||
- 基准版本：当前线上版本
|
||||
- 对比版本：当前工作版本
|
||||
|
||||
如果两者相同，则按钮仍可用，但进入后提示：
|
||||
|
||||
> 当前工作版本与线上版本一致，可选择其他历史版本进行比较。
|
||||
|
||||
### 5.2 查看流转按钮
|
||||
|
||||
用于进入当前规则的完整生命周期视图。
|
||||
不应只展示审计日志，而要展示“版本业务履历”。
|
||||
|
||||
---
|
||||
|
||||
## 6. 右侧版本中心设计
|
||||
|
||||
### 6.1 顶部双版本卡片
|
||||
|
||||
```text
|
||||
线上版本
|
||||
v1.0.5
|
||||
已上线
|
||||
|
||||
工作版本
|
||||
v1.0.6
|
||||
待审核
|
||||
```
|
||||
|
||||
#### 设计目的
|
||||
|
||||
用户进入页面后，最先要知道的是：
|
||||
|
||||
- **谁在线上**
|
||||
- **谁正在被编辑**
|
||||
|
||||
而不是先看一个无上下文的历史列表。
|
||||
|
||||
### 6.2 最近版本列表
|
||||
|
||||
每个版本项包含：
|
||||
|
||||
- 版本号
|
||||
- 生命周期状态
|
||||
- 创建时间
|
||||
- 变更说明
|
||||
- 操作入口
|
||||
|
||||
建议样式：
|
||||
|
||||
```text
|
||||
v1.0.6 待审核
|
||||
2026-05-18 09:12
|
||||
补充出差补助标准
|
||||
[查看] [与线上比]
|
||||
|
||||
v1.0.5 已上线
|
||||
2026-05-18 08:40
|
||||
新增补助页签
|
||||
[查看]
|
||||
|
||||
v1.0.4 历史版本
|
||||
2026-05-17 17:20
|
||||
修正住宿标准
|
||||
[查看] [恢复]
|
||||
```
|
||||
|
||||
#### 规则
|
||||
|
||||
- `查看`：切换当前预览版本
|
||||
- `与线上比`：直接以线上版本为基准进入对比
|
||||
- `恢复`：仅高级管理人员可见
|
||||
- 当前 `working_version` 不显示“恢复”
|
||||
|
||||
### 6.3 最近流转摘要
|
||||
|
||||
右侧版本中心底部展示最近 3 条流转：
|
||||
|
||||
```text
|
||||
最近流转
|
||||
09:12 曹笑竹 保存工作稿
|
||||
09:25 曹笑竹 提交审核
|
||||
10:08 顾承宇 审核通过
|
||||
[查看完整流转]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. 版本流转时间线设计
|
||||
|
||||
## 7.1 入口
|
||||
|
||||
两个入口：
|
||||
|
||||
1. 顶部 `查看流转`
|
||||
2. 右侧版本中心底部 `查看完整流转`
|
||||
|
||||
## 7.2 容器
|
||||
|
||||
使用右侧宽抽屉，不使用小弹窗。
|
||||
原因：
|
||||
|
||||
- 时间线内容会逐步增长
|
||||
- 审核意见需要足够宽度展示
|
||||
- 后续可能接入版本说明、操作人、来源版本
|
||||
|
||||
## 7.3 时间线内容
|
||||
|
||||
时间线按时间倒序或正序展示，推荐默认正序：
|
||||
|
||||
```text
|
||||
● 2026-05-18 09:12
|
||||
v1.0.6 工作稿创建
|
||||
曹笑竹 保存工作稿
|
||||
变更说明：补充出差补助标准
|
||||
|
||||
● 2026-05-18 09:25
|
||||
提交审核
|
||||
曹笑竹 提交当前工作版本
|
||||
|
||||
● 2026-05-18 10:08
|
||||
审核通过
|
||||
顾承宇：口径已核对，可上线
|
||||
|
||||
○ 待正式上线
|
||||
```
|
||||
|
||||
如果版本来自恢复：
|
||||
|
||||
```text
|
||||
● 基于 v1.0.3 恢复生成 v1.0.7
|
||||
```
|
||||
|
||||
## 7.4 时间线事件类型
|
||||
|
||||
| 事件类型 | 说明 |
|
||||
| --- | --- |
|
||||
| `created` | 创建版本 |
|
||||
| `submitted` | 提交审核 |
|
||||
| `approved` | 审核通过 |
|
||||
| `rejected` | 驳回 |
|
||||
| `published` | 正式上线 |
|
||||
| `restored` | 基于历史版本恢复 |
|
||||
|
||||
---
|
||||
|
||||
## 8. 版本差异对比设计
|
||||
|
||||
## 8.1 入口
|
||||
|
||||
版本对比必须有两个入口：
|
||||
|
||||
1. 顶部一级按钮：`版本对比`
|
||||
2. 每个历史版本行内操作：`与线上比`
|
||||
|
||||
这样既满足“主动进入”，也满足“看到某个版本就顺手比较”。
|
||||
|
||||
## 8.2 容器
|
||||
|
||||
使用宽抽屉，推荐宽度：
|
||||
|
||||
- 桌面：页面宽度的 70% ~ 80%
|
||||
- 小屏：全屏
|
||||
|
||||
不建议用普通弹窗，因为：
|
||||
|
||||
- Excel 差异需要足够展示宽度
|
||||
- 版本选择器、摘要、表格都要共存
|
||||
|
||||
## 8.3 顶部区域
|
||||
|
||||
```text
|
||||
版本对比
|
||||
|
||||
基准版本 [v1.0.5 已上线 ▼]
|
||||
对比版本 [v1.0.6 待审核 ▼]
|
||||
```
|
||||
|
||||
默认值：
|
||||
|
||||
- `baseVersion = published_version`
|
||||
- `targetVersion = working_version`
|
||||
|
||||
## 8.4 差异摘要
|
||||
|
||||
优先先给决策信息，再给底层明细。
|
||||
|
||||
```text
|
||||
差异摘要
|
||||
- 修改 2 个工作表
|
||||
- 新增 1 个工作表
|
||||
- 修改 12 个单元格
|
||||
- 删除 2 行
|
||||
```
|
||||
|
||||
如果无差异：
|
||||
|
||||
```text
|
||||
两个版本内容一致，没有发现表格差异。
|
||||
```
|
||||
|
||||
## 8.5 差异详情
|
||||
|
||||
第一阶段优先支持 Excel 规则表：
|
||||
|
||||
| 工作表 | 位置 | 旧值 | 新值 | 类型 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 出差补助标准 | B4 | 75 | 90 | 修改 |
|
||||
| 差旅住宿费标准 | A106 | - | 新增城市 | 新增 |
|
||||
|
||||
后续可扩展：
|
||||
|
||||
- 仅看新增
|
||||
- 仅看删除
|
||||
- 仅看数值变化
|
||||
- 按工作表筛选
|
||||
|
||||
## 8.6 对比结果的业务语气
|
||||
|
||||
不要把页面做成“程序员 diff 工具”。
|
||||
它应该像制度审核页面：
|
||||
|
||||
- 先讲影响
|
||||
- 再讲位置
|
||||
- 最后给证据
|
||||
|
||||
---
|
||||
|
||||
## 9. 数据接口设计
|
||||
|
||||
## 9.1 时间线接口
|
||||
|
||||
建议新增：
|
||||
|
||||
```http
|
||||
GET /agent-assets/{asset_id}/version-timeline
|
||||
```
|
||||
|
||||
返回：
|
||||
|
||||
- 版本号
|
||||
- 事件类型
|
||||
- 操作人
|
||||
- 操作时间
|
||||
- 审核意见
|
||||
- 来源版本（如有）
|
||||
|
||||
## 9.2 对比接口
|
||||
|
||||
建议新增：
|
||||
|
||||
```http
|
||||
GET /agent-assets/{asset_id}/versions/compare?base_version=v1.0.5&target_version=v1.0.6
|
||||
```
|
||||
|
||||
返回：
|
||||
|
||||
- 基准版本
|
||||
- 对比版本
|
||||
- 工作表差异摘要
|
||||
- 单元格级差异明细
|
||||
|
||||
---
|
||||
|
||||
## 10. 视觉规范
|
||||
|
||||
### 10.1 颜色
|
||||
|
||||
沿用当前系统已有色彩，不引入新风格：
|
||||
|
||||
| 状态 | 建议色 |
|
||||
| --- | --- |
|
||||
| 已上线 | 绿色 |
|
||||
| 工作稿 | 蓝色 |
|
||||
| 待审核 | 橙色 |
|
||||
| 已驳回 | 红色 |
|
||||
| 历史版本 | 灰色 |
|
||||
|
||||
### 10.2 密度
|
||||
|
||||
- 右侧版本中心应为紧凑型信息面板
|
||||
- 不要使用过大的卡片间距
|
||||
- 不能明显压缩 OnlyOffice 主区域
|
||||
|
||||
### 10.3 交互反馈
|
||||
|
||||
- 可点击元素必须有 hover
|
||||
- 当前预览版本必须有 active 高亮
|
||||
- 抽屉打开后保留明确关闭按钮
|
||||
- 恢复操作必须二次确认
|
||||
|
||||
---
|
||||
|
||||
## 11. 推荐实施顺序
|
||||
|
||||
### 第一阶段
|
||||
|
||||
1. 顶部新增 `版本对比`、`查看流转`
|
||||
2. Excel 详情页改成：
|
||||
- 左侧 OnlyOffice
|
||||
- 右侧版本中心
|
||||
3. 右侧展示：
|
||||
- 线上版本
|
||||
- 工作版本
|
||||
- 最近 5 个版本
|
||||
- 最近 3 条流转
|
||||
|
||||
### 第二阶段
|
||||
|
||||
1. 实现版本流转抽屉
|
||||
2. 实现版本对比抽屉
|
||||
3. 补齐真实后端接口
|
||||
|
||||
### 第三阶段
|
||||
|
||||
1. 增加更细的工作表筛选
|
||||
2. 增加更多 diff 维度
|
||||
3. 增加版本差异导出能力
|
||||
|
||||
---
|
||||
|
||||
## 12. 本次开发目标
|
||||
|
||||
本次开发直接完成以下内容：
|
||||
|
||||
1. 规则详情页出现明确的版本中心
|
||||
2. 页面上出现明确的：
|
||||
- `版本对比`
|
||||
- `查看流转`
|
||||
3. 最近版本列表增加：
|
||||
- `查看`
|
||||
- `与线上比`
|
||||
- `恢复为工作稿`
|
||||
4. 版本流转抽屉可用
|
||||
5. 版本对比抽屉可用
|
||||
6. 对比结果至少支持 Excel 表格的：
|
||||
- 工作表新增 / 删除
|
||||
- 单元格新增 / 删除 / 修改
|
||||
|
||||
@@ -1,237 +0,0 @@
|
||||
# 规则版本治理方案
|
||||
|
||||
## 1. 背景
|
||||
|
||||
当前“任务规则中心”的规则资产只有一个 `current_version` 指针。
|
||||
它同时承担了三种含义：
|
||||
|
||||
1. 财务人员正在编辑的版本
|
||||
2. 审核中的候选版本
|
||||
3. 系统运行时真正生效的线上版本
|
||||
|
||||
这会直接带来三个问题：
|
||||
|
||||
- 财务人员一旦修改 Excel，最新内容就会立刻成为 `current_version`，容易被误解为已经正式生效
|
||||
- 审核、上线、回滚都围绕同一个指针转，权限边界不清晰
|
||||
- 如果误上线，虽然能切换历史版本，但缺少“线上版本”和“工作版本”分离后的安全缓冲
|
||||
|
||||
## 2. 设计目标
|
||||
|
||||
这次改造要解决的不是“多存几个历史版本”，而是建立一套可长期使用的规则治理机制：
|
||||
|
||||
1. 财务人员可以编辑规则，但编辑结果默认只是草稿
|
||||
2. 只有高级管理人员审核通过后，规则才能成为正式线上版本
|
||||
3. 系统运行时只能读取正式线上版本，不能读取草稿
|
||||
4. 前台要能清楚区分：
|
||||
- 当前线上版本
|
||||
- 当前工作版本
|
||||
- 最近 5 个历史版本
|
||||
5. 如果误操作上线，可以快速恢复，但恢复动作仍然要留下完整审计链
|
||||
|
||||
## 3. 核心模型
|
||||
|
||||
### 3.1 双指针版本模型
|
||||
|
||||
在规则资产上新增两个版本指针：
|
||||
|
||||
| 字段 | 含义 |
|
||||
| --- | --- |
|
||||
| `published_version` | 当前正式在线上生效的版本 |
|
||||
| `working_version` | 当前最新的工作稿 / 待审稿 |
|
||||
|
||||
兼容策略：
|
||||
|
||||
- 现有 `current_version` 暂时保留，用于兼容历史代码
|
||||
- 对规则资产来说，后续它只承担“当前工作版本”的兼容语义
|
||||
- 运行时逻辑不再读取 `current_version`，而是优先读取 `published_version`
|
||||
|
||||
### 3.2 版本状态
|
||||
|
||||
不额外在版本表中硬存一套容易失真的状态，而是根据“版本指针 + 最新审核记录”动态推导：
|
||||
|
||||
| 条件 | 版本状态 |
|
||||
| --- | --- |
|
||||
| `version == published_version` | 已上线 |
|
||||
| `version == working_version` 且无审核记录 | 草稿 |
|
||||
| `version == working_version` 且最新审核为 `pending` | 待审核 |
|
||||
| `version == working_version` 且最新审核为 `approved` | 已通过待上线 |
|
||||
| `version == working_version` 且最新审核为 `rejected` | 已驳回 |
|
||||
| 其他历史版本 | 历史版本 |
|
||||
|
||||
这样可以避免“版本状态”和“审核记录”两套数据互相打架。
|
||||
|
||||
## 4. 权限边界
|
||||
|
||||
| 角色 | 能力 |
|
||||
| --- | --- |
|
||||
| 财务人员 `finance` | 编辑工作稿、上传/导入 Excel、提交审核 |
|
||||
| 高级管理人员 `manager` / `admin` | 审核通过、驳回、正式发布、恢复历史版本 |
|
||||
| 其他普通员工 | 只读 |
|
||||
|
||||
### 4.1 财务人员
|
||||
|
||||
- 可以直接编辑当前 `working_version`
|
||||
- 每次保存自动生成新版本，并把它设为新的 `working_version`
|
||||
- 不能把草稿直接变成 `published_version`
|
||||
|
||||
### 4.2 高级管理人员
|
||||
|
||||
- 可以对 `working_version` 发起：
|
||||
- 审核通过
|
||||
- 驳回
|
||||
- 正式发布
|
||||
- 只有 `approved` 的工作版本才能发布
|
||||
|
||||
## 5. 发布与回滚流程
|
||||
|
||||
### 5.1 正常发布
|
||||
|
||||
1. 财务人员编辑并保存
|
||||
2. 系统生成新版本，例如 `v1.0.6`
|
||||
3. `working_version = v1.0.6`
|
||||
4. 财务人员提交审核
|
||||
5. 高级管理人员审核通过
|
||||
6. 高级管理人员点击“正式上线”
|
||||
7. `published_version = v1.0.6`
|
||||
8. 系统运行时切换到新版本
|
||||
|
||||
### 5.2 驳回
|
||||
|
||||
1. 财务人员提交审核
|
||||
2. 高级管理人员驳回
|
||||
3. 当前工作版本保留，但状态显示为“已驳回”
|
||||
4. 财务人员继续编辑，形成新的工作版本
|
||||
|
||||
### 5.3 恢复历史版本
|
||||
|
||||
不直接把 `published_version` 指回旧版本，而是采用“复制恢复”的方式：
|
||||
|
||||
1. 管理员在最近 5 个版本中选择一个历史版本
|
||||
2. 系统基于该历史版本内容生成一个新的恢复版本，例如 `v1.0.7`
|
||||
3. 新版本写入 `working_version`
|
||||
4. 审核通过后再正式发布
|
||||
|
||||
这么做的好处：
|
||||
|
||||
- 不会破坏历史链路
|
||||
- 每一次恢复都有明确的责任人与时间
|
||||
- 既能快速回滚，又保留审计闭环
|
||||
|
||||
## 6. 版本保留策略
|
||||
|
||||
### 6.1 前台展示
|
||||
|
||||
- 详情页固定展示最近 5 个版本
|
||||
- 每个版本显示：
|
||||
- 版本号
|
||||
- 状态
|
||||
- 创建人
|
||||
- 创建时间
|
||||
- 变更说明
|
||||
|
||||
### 6.2 后台保存
|
||||
|
||||
后台不能机械地“只保留 5 个版本”，否则可能把关键线上版本挤掉。
|
||||
建议策略：
|
||||
|
||||
1. 始终保留当前 `published_version`
|
||||
2. 始终保留当前 `working_version`
|
||||
3. 额外保留最近 5 个历史版本
|
||||
|
||||
这样既满足前台简洁，也能避免误删关键版本。
|
||||
|
||||
## 7. 前端交互
|
||||
|
||||
### 7.1 规则详情页顶部
|
||||
|
||||
展示两个醒目的版本标签：
|
||||
|
||||
- 当前线上版本
|
||||
- 当前工作版本
|
||||
|
||||
如果两者不同，需要明确提示：
|
||||
|
||||
> 当前存在尚未上线的工作稿，系统运行仍以线上版本为准。
|
||||
|
||||
### 7.2 编辑区
|
||||
|
||||
- 财务人员看到“可编辑工作稿”
|
||||
- 普通用户只读
|
||||
- 管理员可编辑，但主要职责仍是审核与发布
|
||||
|
||||
### 7.3 版本区
|
||||
|
||||
最近 5 个版本中每条都显示状态：
|
||||
|
||||
- 已上线
|
||||
- 草稿
|
||||
- 待审核
|
||||
- 已通过待上线
|
||||
- 已驳回
|
||||
- 历史版本
|
||||
|
||||
可执行操作：
|
||||
|
||||
- 查看
|
||||
- 基于该版本恢复
|
||||
- 对当前工作版本提交审核 / 审核 / 发布
|
||||
|
||||
## 8. 后端改造清单
|
||||
|
||||
1. `agent_assets`
|
||||
- 新增 `published_version`
|
||||
- 新增 `working_version`
|
||||
2. 兼容旧数据
|
||||
- 历史规则资产初始化时：
|
||||
- `published_version = current_version`
|
||||
- `working_version = current_version`
|
||||
3. 版本保存
|
||||
- 保存新版本后：
|
||||
- 只更新 `working_version`
|
||||
- `current_version` 同步为 `working_version` 以兼容旧逻辑
|
||||
4. 审核
|
||||
- 审核只针对 `working_version`
|
||||
5. 发布
|
||||
- 只允许把已审核通过的 `working_version` 推到 `published_version`
|
||||
6. 运行时
|
||||
- 只读取 `published_version`
|
||||
7. 回滚
|
||||
- 新增“基于历史版本恢复为新工作稿”的接口
|
||||
|
||||
## 9. 前端改造清单
|
||||
|
||||
1. 资产详情模型增加：
|
||||
- `publishedVersion`
|
||||
- `workingVersion`
|
||||
- 每个历史版本的派生状态
|
||||
2. 规则详情页展示：
|
||||
- 当前线上版本
|
||||
- 当前工作版本
|
||||
- 最近 5 个版本
|
||||
3. 操作权限拆分：
|
||||
- finance：编辑、上传、提交审核
|
||||
- manager/admin：审核、上线、恢复
|
||||
4. OnlyOffice 编辑逻辑：
|
||||
- 默认编辑工作版本
|
||||
- 历史版本只读
|
||||
5. 正式上线按钮：
|
||||
- 只有工作版本已审核通过时可用
|
||||
|
||||
## 10. 本次实现边界
|
||||
|
||||
本轮优先完成以下能力：
|
||||
|
||||
1. 规则版本双指针
|
||||
2. 财务角色可编辑工作稿
|
||||
3. 正式上线只切换 `published_version`
|
||||
4. 运行时只读取 `published_version`
|
||||
5. 最近 5 个版本展示
|
||||
6. 基于历史版本快速恢复为新工作稿
|
||||
|
||||
后续如需要，再继续补：
|
||||
|
||||
- 版本差异对比
|
||||
- 审核意见流转面板
|
||||
- 发布说明 / 审批单号
|
||||
- 定时生效
|
||||
|
||||
@@ -1,746 +0,0 @@
|
||||
<!doctype html>
|
||||
<html lang="zh-CN">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
<title>X-Financial 个人工作台首页参考稿</title>
|
||||
<style>
|
||||
:root {
|
||||
--bg: #f4f7fb;
|
||||
--panel: #ffffff;
|
||||
--line: #e4ebf3;
|
||||
--line-strong: #d6e1ed;
|
||||
--text: #0f172a;
|
||||
--muted: #64748b;
|
||||
--soft: #f8fbff;
|
||||
--green: #0f9f6e;
|
||||
--green-dark: #047857;
|
||||
--blue: #2563eb;
|
||||
--amber: #b7791f;
|
||||
--red: #d93025;
|
||||
--shadow: 0 18px 44px rgba(15, 23, 42, 0.08);
|
||||
font-family:
|
||||
"Microsoft YaHei UI", "Microsoft YaHei", "PingFang SC",
|
||||
"Noto Sans CJK SC", "Segoe UI", sans-serif;
|
||||
}
|
||||
|
||||
* {
|
||||
box-sizing: border-box;
|
||||
}
|
||||
|
||||
body {
|
||||
margin: 0;
|
||||
min-height: 100vh;
|
||||
background:
|
||||
radial-gradient(circle at 18% 0%, rgba(16, 185, 129, 0.13), transparent 29%),
|
||||
radial-gradient(circle at 86% 12%, rgba(37, 99, 235, 0.10), transparent 24%),
|
||||
var(--bg);
|
||||
color: var(--text);
|
||||
}
|
||||
|
||||
.app {
|
||||
width: 1440px;
|
||||
min-height: 960px;
|
||||
margin: 0 auto;
|
||||
display: grid;
|
||||
grid-template-columns: 84px 1fr;
|
||||
background: rgba(255, 255, 255, 0.42);
|
||||
}
|
||||
|
||||
.rail {
|
||||
padding: 20px 12px;
|
||||
background: #0f172a;
|
||||
color: #cbd5e1;
|
||||
display: grid;
|
||||
grid-template-rows: auto 1fr auto;
|
||||
gap: 24px;
|
||||
}
|
||||
|
||||
.brand-mark {
|
||||
width: 44px;
|
||||
height: 44px;
|
||||
margin: 0 auto;
|
||||
border-radius: 14px;
|
||||
display: grid;
|
||||
place-items: center;
|
||||
background: linear-gradient(135deg, #10b981, #2563eb);
|
||||
color: white;
|
||||
font-weight: 900;
|
||||
letter-spacing: 0;
|
||||
box-shadow: 0 12px 26px rgba(16, 185, 129, 0.24);
|
||||
}
|
||||
|
||||
.nav {
|
||||
display: grid;
|
||||
gap: 12px;
|
||||
align-content: start;
|
||||
}
|
||||
|
||||
.nav-item {
|
||||
height: 56px;
|
||||
border-radius: 16px;
|
||||
display: grid;
|
||||
place-items: center;
|
||||
color: #94a3b8;
|
||||
font-size: 12px;
|
||||
font-weight: 700;
|
||||
}
|
||||
|
||||
.nav-item.active {
|
||||
color: #ffffff;
|
||||
background: rgba(255, 255, 255, 0.12);
|
||||
box-shadow: inset 0 0 0 1px rgba(255, 255, 255, 0.08);
|
||||
}
|
||||
|
||||
.main {
|
||||
padding: 22px 30px 30px;
|
||||
display: grid;
|
||||
grid-template-rows: auto 1fr;
|
||||
gap: 18px;
|
||||
}
|
||||
|
||||
.topbar {
|
||||
height: 58px;
|
||||
display: flex;
|
||||
align-items: center;
|
||||
justify-content: space-between;
|
||||
padding: 0 4px;
|
||||
}
|
||||
|
||||
.crumb strong {
|
||||
display: block;
|
||||
font-size: 22px;
|
||||
line-height: 1.2;
|
||||
font-weight: 800;
|
||||
letter-spacing: 0;
|
||||
}
|
||||
|
||||
.crumb span {
|
||||
display: block;
|
||||
margin-top: 6px;
|
||||
color: var(--muted);
|
||||
font-size: 13px;
|
||||
}
|
||||
|
||||
.user-pill {
|
||||
height: 38px;
|
||||
display: inline-flex;
|
||||
align-items: center;
|
||||
gap: 10px;
|
||||
padding: 0 12px 0 6px;
|
||||
border: 1px solid var(--line);
|
||||
border-radius: 999px;
|
||||
background: rgba(255, 255, 255, 0.74);
|
||||
color: #334155;
|
||||
font-size: 13px;
|
||||
font-weight: 700;
|
||||
}
|
||||
|
||||
.avatar {
|
||||
width: 28px;
|
||||
height: 28px;
|
||||
border-radius: 999px;
|
||||
display: grid;
|
||||
place-items: center;
|
||||
background: #e8f7f0;
|
||||
color: var(--green-dark);
|
||||
font-weight: 900;
|
||||
}
|
||||
|
||||
.content {
|
||||
display: grid;
|
||||
gap: 18px;
|
||||
}
|
||||
|
||||
.hero {
|
||||
position: relative;
|
||||
overflow: hidden;
|
||||
min-height: 254px;
|
||||
display: grid;
|
||||
grid-template-columns: 230px minmax(0, 1fr);
|
||||
gap: 22px;
|
||||
padding: 24px 28px 22px 20px;
|
||||
border: 1px solid rgba(15, 159, 110, 0.16);
|
||||
border-radius: 18px;
|
||||
background:
|
||||
linear-gradient(135deg, rgba(247, 255, 251, 0.98), rgba(255, 255, 255, 0.98) 55%, rgba(244, 249, 255, 0.96)),
|
||||
var(--panel);
|
||||
box-shadow: var(--shadow);
|
||||
}
|
||||
|
||||
.hero::after {
|
||||
content: "";
|
||||
position: absolute;
|
||||
width: 300px;
|
||||
height: 300px;
|
||||
right: -110px;
|
||||
bottom: -138px;
|
||||
border-radius: 50%;
|
||||
background: rgba(16, 185, 129, 0.08);
|
||||
}
|
||||
|
||||
.bot-wrap {
|
||||
position: relative;
|
||||
min-height: 206px;
|
||||
display: flex;
|
||||
align-items: end;
|
||||
justify-content: center;
|
||||
}
|
||||
|
||||
.bot-wrap::before {
|
||||
content: "";
|
||||
position: absolute;
|
||||
left: 18px;
|
||||
right: 18px;
|
||||
bottom: 4px;
|
||||
height: 58px;
|
||||
border-radius: 50%;
|
||||
background: rgba(16, 185, 129, 0.13);
|
||||
filter: blur(13px);
|
||||
}
|
||||
|
||||
.bot-wrap img {
|
||||
position: relative;
|
||||
width: 176px;
|
||||
height: auto;
|
||||
filter: drop-shadow(0 24px 26px rgba(15, 23, 42, 0.15));
|
||||
}
|
||||
|
||||
.hero-copy {
|
||||
position: relative;
|
||||
z-index: 1;
|
||||
display: grid;
|
||||
align-content: center;
|
||||
gap: 14px;
|
||||
}
|
||||
|
||||
.hero-title {
|
||||
margin: 0;
|
||||
max-width: 860px;
|
||||
font-size: 27px;
|
||||
line-height: 1.32;
|
||||
font-weight: 850;
|
||||
letter-spacing: 0;
|
||||
}
|
||||
|
||||
.hero-subtitle {
|
||||
margin: 0;
|
||||
max-width: 880px;
|
||||
color: #53637a;
|
||||
font-size: 14px;
|
||||
line-height: 1.68;
|
||||
}
|
||||
|
||||
.composer {
|
||||
min-height: 58px;
|
||||
display: grid;
|
||||
grid-template-columns: minmax(0, 1fr) auto auto;
|
||||
align-items: center;
|
||||
gap: 10px;
|
||||
padding: 8px;
|
||||
border: 1px solid rgba(148, 163, 184, 0.28);
|
||||
border-radius: 15px;
|
||||
background: rgba(255, 255, 255, 0.92);
|
||||
box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.74);
|
||||
}
|
||||
|
||||
.composer-text {
|
||||
padding: 0 12px;
|
||||
color: #94a3b8;
|
||||
font-size: 14px;
|
||||
white-space: nowrap;
|
||||
overflow: hidden;
|
||||
text-overflow: ellipsis;
|
||||
}
|
||||
|
||||
.btn {
|
||||
height: 42px;
|
||||
border: 0;
|
||||
border-radius: 11px;
|
||||
padding: 0 16px;
|
||||
display: inline-flex;
|
||||
align-items: center;
|
||||
justify-content: center;
|
||||
gap: 8px;
|
||||
font-size: 14px;
|
||||
font-weight: 800;
|
||||
white-space: nowrap;
|
||||
}
|
||||
|
||||
.btn.secondary {
|
||||
border: 1px solid rgba(15, 118, 110, 0.18);
|
||||
background: linear-gradient(180deg, #ffffff, #f2faf7);
|
||||
color: #0f766e;
|
||||
}
|
||||
|
||||
.btn.primary {
|
||||
background: linear-gradient(135deg, #10b981, #059669);
|
||||
color: #ffffff;
|
||||
box-shadow: 0 12px 24px rgba(16, 185, 129, 0.20);
|
||||
}
|
||||
|
||||
.intent-grid {
|
||||
display: grid;
|
||||
grid-template-columns: repeat(4, minmax(0, 1fr));
|
||||
gap: 14px;
|
||||
}
|
||||
|
||||
.intent-card {
|
||||
min-height: 116px;
|
||||
padding: 18px;
|
||||
border: 1px solid var(--line);
|
||||
border-radius: 16px;
|
||||
background: rgba(255, 255, 255, 0.92);
|
||||
box-shadow: 0 10px 28px rgba(15, 23, 42, 0.055);
|
||||
display: grid;
|
||||
gap: 12px;
|
||||
align-content: start;
|
||||
}
|
||||
|
||||
.intent-top {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
justify-content: space-between;
|
||||
gap: 12px;
|
||||
}
|
||||
|
||||
.intent-icon {
|
||||
width: 38px;
|
||||
height: 38px;
|
||||
border-radius: 12px;
|
||||
display: grid;
|
||||
place-items: center;
|
||||
font-size: 14px;
|
||||
font-weight: 900;
|
||||
}
|
||||
|
||||
.intent-icon.green {
|
||||
background: #e8f7f0;
|
||||
color: var(--green-dark);
|
||||
}
|
||||
|
||||
.intent-icon.blue {
|
||||
background: #eff6ff;
|
||||
color: var(--blue);
|
||||
}
|
||||
|
||||
.intent-icon.amber {
|
||||
background: #fff7e6;
|
||||
color: var(--amber);
|
||||
}
|
||||
|
||||
.intent-icon.slate {
|
||||
background: #f1f5f9;
|
||||
color: #475569;
|
||||
}
|
||||
|
||||
.intent-arrow {
|
||||
color: #94a3b8;
|
||||
font-size: 18px;
|
||||
font-weight: 800;
|
||||
}
|
||||
|
||||
.intent-card h3 {
|
||||
margin: 0;
|
||||
color: var(--text);
|
||||
font-size: 16px;
|
||||
line-height: 1.35;
|
||||
font-weight: 800;
|
||||
}
|
||||
|
||||
.intent-card p {
|
||||
margin: -6px 0 0;
|
||||
color: var(--muted);
|
||||
font-size: 13px;
|
||||
line-height: 1.5;
|
||||
}
|
||||
|
||||
.lower-grid {
|
||||
display: grid;
|
||||
grid-template-columns: 1fr 1fr;
|
||||
gap: 18px;
|
||||
}
|
||||
|
||||
.panel {
|
||||
border: 1px solid var(--line);
|
||||
border-radius: 16px;
|
||||
background: rgba(255, 255, 255, 0.94);
|
||||
box-shadow: 0 10px 26px rgba(15, 23, 42, 0.045);
|
||||
overflow: hidden;
|
||||
}
|
||||
|
||||
.panel-head {
|
||||
min-height: 58px;
|
||||
padding: 0 20px;
|
||||
display: flex;
|
||||
align-items: center;
|
||||
justify-content: space-between;
|
||||
border-bottom: 1px solid var(--line);
|
||||
}
|
||||
|
||||
.panel-head h3 {
|
||||
margin: 0;
|
||||
font-size: 16px;
|
||||
line-height: 1.2;
|
||||
font-weight: 800;
|
||||
}
|
||||
|
||||
.panel-head span {
|
||||
color: var(--green-dark);
|
||||
font-size: 13px;
|
||||
font-weight: 800;
|
||||
}
|
||||
|
||||
.rows {
|
||||
padding: 2px 20px;
|
||||
}
|
||||
|
||||
.row {
|
||||
min-height: 70px;
|
||||
display: grid;
|
||||
grid-template-columns: 42px minmax(0, 1fr) auto;
|
||||
align-items: center;
|
||||
gap: 14px;
|
||||
border-top: 1px solid #edf2f7;
|
||||
}
|
||||
|
||||
.row:first-child {
|
||||
border-top: 0;
|
||||
}
|
||||
|
||||
.row-icon {
|
||||
width: 38px;
|
||||
height: 38px;
|
||||
border-radius: 13px;
|
||||
display: grid;
|
||||
place-items: center;
|
||||
background: #eefaf4;
|
||||
color: var(--green-dark);
|
||||
font-size: 12px;
|
||||
font-weight: 900;
|
||||
}
|
||||
|
||||
.row-copy {
|
||||
min-width: 0;
|
||||
}
|
||||
|
||||
.row-copy strong {
|
||||
display: block;
|
||||
font-size: 14px;
|
||||
line-height: 1.35;
|
||||
font-weight: 800;
|
||||
white-space: nowrap;
|
||||
overflow: hidden;
|
||||
text-overflow: ellipsis;
|
||||
}
|
||||
|
||||
.row-copy small {
|
||||
display: block;
|
||||
margin-top: 5px;
|
||||
color: var(--muted);
|
||||
font-size: 12px;
|
||||
white-space: nowrap;
|
||||
overflow: hidden;
|
||||
text-overflow: ellipsis;
|
||||
}
|
||||
|
||||
.row-action {
|
||||
min-width: 78px;
|
||||
height: 34px;
|
||||
border: 1px solid rgba(16, 185, 129, 0.26);
|
||||
border-radius: 999px;
|
||||
display: grid;
|
||||
place-items: center;
|
||||
color: var(--green-dark);
|
||||
font-size: 12px;
|
||||
font-weight: 800;
|
||||
background: #f6fffb;
|
||||
}
|
||||
|
||||
.amount {
|
||||
font-size: 18px;
|
||||
font-weight: 900;
|
||||
text-align: right;
|
||||
}
|
||||
|
||||
.status {
|
||||
margin-left: 10px;
|
||||
min-width: 92px;
|
||||
height: 30px;
|
||||
border-radius: 999px;
|
||||
display: inline-grid;
|
||||
place-items: center;
|
||||
background: #eff6ff;
|
||||
color: var(--blue);
|
||||
font-size: 12px;
|
||||
font-weight: 850;
|
||||
}
|
||||
|
||||
.wide-panel {
|
||||
display: grid;
|
||||
grid-template-columns: 1.25fr 1fr;
|
||||
gap: 0;
|
||||
}
|
||||
|
||||
.policy-list {
|
||||
border-left: 1px solid var(--line);
|
||||
}
|
||||
|
||||
.mini-section {
|
||||
min-height: 178px;
|
||||
}
|
||||
|
||||
.mini-section .panel-head {
|
||||
border-bottom: 0;
|
||||
min-height: 50px;
|
||||
}
|
||||
|
||||
.metric-strip {
|
||||
display: grid;
|
||||
grid-template-columns: repeat(3, 1fr);
|
||||
gap: 12px;
|
||||
padding: 0 20px 20px;
|
||||
}
|
||||
|
||||
.metric {
|
||||
min-height: 88px;
|
||||
border: 1px solid var(--line);
|
||||
border-radius: 14px;
|
||||
background: var(--soft);
|
||||
padding: 14px;
|
||||
}
|
||||
|
||||
.metric strong {
|
||||
display: block;
|
||||
font-size: 24px;
|
||||
line-height: 1;
|
||||
font-weight: 900;
|
||||
}
|
||||
|
||||
.metric span {
|
||||
display: block;
|
||||
margin-top: 9px;
|
||||
color: var(--muted);
|
||||
font-size: 12px;
|
||||
font-weight: 700;
|
||||
}
|
||||
|
||||
@media (max-width: 1000px) {
|
||||
.app {
|
||||
width: 100%;
|
||||
grid-template-columns: 1fr;
|
||||
}
|
||||
|
||||
.rail {
|
||||
display: none;
|
||||
}
|
||||
|
||||
.main {
|
||||
padding: 18px;
|
||||
}
|
||||
|
||||
.hero,
|
||||
.lower-grid,
|
||||
.wide-panel {
|
||||
grid-template-columns: 1fr;
|
||||
}
|
||||
|
||||
.intent-grid {
|
||||
grid-template-columns: repeat(2, minmax(0, 1fr));
|
||||
}
|
||||
|
||||
.policy-list {
|
||||
border-left: 0;
|
||||
border-top: 1px solid var(--line);
|
||||
}
|
||||
}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<main class="app">
|
||||
<aside class="rail" aria-label="侧边导航">
|
||||
<div class="brand-mark">XF</div>
|
||||
<nav class="nav">
|
||||
<div class="nav-item active">工作台</div>
|
||||
<div class="nav-item">申请</div>
|
||||
<div class="nav-item">审批</div>
|
||||
<div class="nav-item">规则</div>
|
||||
<div class="nav-item">知识</div>
|
||||
</nav>
|
||||
<div class="nav-item">设置</div>
|
||||
</aside>
|
||||
|
||||
<section class="main">
|
||||
<header class="topbar">
|
||||
<div class="crumb">
|
||||
<strong>个人工作台</strong>
|
||||
<span>把费用申请、报销处理、进度查询和制度问答集中到一个入口。</span>
|
||||
</div>
|
||||
<div class="user-pill">
|
||||
<span class="avatar">A</span>
|
||||
<span>admin</span>
|
||||
</div>
|
||||
</header>
|
||||
|
||||
<div class="content">
|
||||
<article class="hero">
|
||||
<div class="bot-wrap">
|
||||
<img src="../../../web/src/assets/robot-helper.png" alt="" />
|
||||
</div>
|
||||
|
||||
<div class="hero-copy">
|
||||
<h1 class="hero-title">嗨，admin，描述您想做的事，AI 会直接帮您处理</h1>
|
||||
<p class="hero-subtitle">
|
||||
我会自动识别您的意图，协助完成费用申请、报销、查询和制度问答等业务工作，
|
||||
并把事情推进到可执行的下一步。
|
||||
</p>
|
||||
|
||||
<div class="composer">
|
||||
<div class="composer-text">例如：帮我查一下上周提交的差旅报销到哪一步了</div>
|
||||
<button class="btn secondary">上传票据</button>
|
||||
<button class="btn primary">开始处理</button>
|
||||
</div>
|
||||
</div>
|
||||
</article>
|
||||
|
||||
<section class="intent-grid" aria-label="业务入口">
|
||||
<article class="intent-card">
|
||||
<div class="intent-top">
|
||||
<span class="intent-icon green">申</span>
|
||||
<span class="intent-arrow">→</span>
|
||||
</div>
|
||||
<h3>费用申请</h3>
|
||||
<p>发起招待、差旅、采购等费用事项</p>
|
||||
</article>
|
||||
|
||||
<article class="intent-card">
|
||||
<div class="intent-top">
|
||||
<span class="intent-icon blue">报</span>
|
||||
<span class="intent-arrow">→</span>
|
||||
</div>
|
||||
<h3>报销处理</h3>
|
||||
<p>上传票据，生成草稿并核对材料</p>
|
||||
</article>
|
||||
|
||||
<article class="intent-card">
|
||||
<div class="intent-top">
|
||||
<span class="intent-icon amber">查</span>
|
||||
<span class="intent-arrow">→</span>
|
||||
</div>
|
||||
<h3>进度查询</h3>
|
||||
<p>查询单据状态、审批节点和到账情况</p>
|
||||
</article>
|
||||
|
||||
<article class="intent-card">
|
||||
<div class="intent-top">
|
||||
<span class="intent-icon slate">问</span>
|
||||
<span class="intent-arrow">→</span>
|
||||
</div>
|
||||
<h3>制度问答</h3>
|
||||
<p>咨询标准、附件要求和可报销边界</p>
|
||||
</article>
|
||||
</section>
|
||||
|
||||
<section class="lower-grid">
|
||||
<article class="panel">
|
||||
<header class="panel-head">
|
||||
<h3>报销待办</h3>
|
||||
<span>查看全部</span>
|
||||
</header>
|
||||
<div class="rows">
|
||||
<div class="row">
|
||||
<span class="row-icon">招</span>
|
||||
<div class="row-copy">
|
||||
<strong>业务招待报销建议补参与人员</strong>
|
||||
<small>AI 建议：补充客户单位、客户人数、我方陪同人员</small>
|
||||
</div>
|
||||
<span class="row-action">去补充</span>
|
||||
</div>
|
||||
<div class="row">
|
||||
<span class="row-icon">旅</span>
|
||||
<div class="row-copy">
|
||||
<strong>差旅报销单待提交</strong>
|
||||
<small>补齐出发交通，可直接生成报销单</small>
|
||||
</div>
|
||||
<span class="row-action">继续填</span>
|
||||
</div>
|
||||
<div class="row">
|
||||
<span class="row-icon">票</span>
|
||||
<div class="row-copy">
|
||||
<strong>有 5 张票据未关联报销单</strong>
|
||||
<small>其中 3 张疑似交通费，可合并生成交通报销</small>
|
||||
</div>
|
||||
<span class="row-action">去整理</span>
|
||||
</div>
|
||||
</div>
|
||||
</article>
|
||||
|
||||
<article class="panel">
|
||||
<header class="panel-head">
|
||||
<h3>报销进度</h3>
|
||||
<span>查看全部</span>
|
||||
</header>
|
||||
<div class="rows">
|
||||
<div class="row">
|
||||
<span class="row-icon">差</span>
|
||||
<div class="row-copy">
|
||||
<strong>差旅报销</strong>
|
||||
<small>提交时间：2026-05-03</small>
|
||||
</div>
|
||||
<div><span class="amount">¥3,280</span><span class="status">主管审批中</span></div>
|
||||
</div>
|
||||
<div class="row">
|
||||
<span class="row-icon">交</span>
|
||||
<div class="row-copy">
|
||||
<strong>交通报销</strong>
|
||||
<small>提交时间：2026-05-02</small>
|
||||
</div>
|
||||
<div><span class="amount">¥126</span><span class="status">财务复核中</span></div>
|
||||
</div>
|
||||
<div class="row">
|
||||
<span class="row-icon">采</span>
|
||||
<div class="row-copy">
|
||||
<strong>办公采购</strong>
|
||||
<small>提交时间：2026-05-01</small>
|
||||
</div>
|
||||
<div><span class="amount">¥458</span><span class="status">已到账</span></div>
|
||||
</div>
|
||||
</div>
|
||||
</article>
|
||||
</section>
|
||||
|
||||
<section class="panel wide-panel">
|
||||
<article class="mini-section">
|
||||
<header class="panel-head">
|
||||
<h3>智能概览</h3>
|
||||
<span>本月</span>
|
||||
</header>
|
||||
<div class="metric-strip">
|
||||
<div class="metric"><strong>12</strong><span>待处理事项</span></div>
|
||||
<div class="metric"><strong>86%</strong><span>材料完整率</span></div>
|
||||
<div class="metric"><strong>2.4天</strong><span>平均审批时长</span></div>
|
||||
</div>
|
||||
</article>
|
||||
|
||||
<article class="mini-section policy-list">
|
||||
<header class="panel-head">
|
||||
<h3>最新报销制度</h3>
|
||||
<span>查看全部</span>
|
||||
</header>
|
||||
<div class="rows">
|
||||
<div class="row">
|
||||
<span class="row-icon">规</span>
|
||||
<div class="row-copy">
|
||||
<strong>差旅报销管理办法（2026版）</strong>
|
||||
<small>更新住宿标准与交通等级规则</small>
|
||||
</div>
|
||||
<span class="row-action">查看</span>
|
||||
</div>
|
||||
</div>
|
||||
</article>
|
||||
</section>
|
||||
</div>
|
||||
</section>
|
||||
</main>
|
||||
</body>
|
||||
</html>
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 123 KiB |
@@ -0,0 +1,203 @@
|
||||
{
|
||||
"schema_version": "2.0",
|
||||
"rule_code": "risk.application.marketing_without_campaign",
|
||||
"name": "市场推广费无活动申请",
|
||||
"description": "市场活动、投放、展会等推广费用，缺少已审批的活动申请或投放方案。",
|
||||
"enabled": true,
|
||||
"requires_attachment": false,
|
||||
"risk_dimension": "expense_control_demo",
|
||||
"risk_category": "申请前置",
|
||||
"ontology_signal": "application_required",
|
||||
"evaluator": "template_rule",
|
||||
"template_key": "keyword_match_v1",
|
||||
"finance_rule_code": "expense.application.policy",
|
||||
"finance_rule_sheet": "费用申请前置规则",
|
||||
"business_stage": [
|
||||
"reimbursement"
|
||||
],
|
||||
"expense_types": [
|
||||
"marketing"
|
||||
],
|
||||
"budget_required": true,
|
||||
"applies_to": {
|
||||
"domains": [
|
||||
"expense"
|
||||
],
|
||||
"expense_types": [
|
||||
"marketing"
|
||||
],
|
||||
"business_stages": [
|
||||
"reimbursement"
|
||||
]
|
||||
},
|
||||
"inputs": {
|
||||
"fields": [
|
||||
{
|
||||
"key": "claim.amount",
|
||||
"label": "报销金额",
|
||||
"type": "number",
|
||||
"source": "claim"
|
||||
},
|
||||
{
|
||||
"key": "claim.expense_type",
|
||||
"label": "费用类型",
|
||||
"type": "enum",
|
||||
"source": "claim"
|
||||
},
|
||||
{
|
||||
"key": "application.id",
|
||||
"label": "申请单",
|
||||
"type": "text",
|
||||
"source": "application"
|
||||
},
|
||||
{
|
||||
"key": "material.plan_uploaded",
|
||||
"label": "方案已上传",
|
||||
"type": "boolean",
|
||||
"source": "material"
|
||||
}
|
||||
]
|
||||
},
|
||||
"params": {
|
||||
"template_key": "keyword_match_v1",
|
||||
"field_keys": [
|
||||
"claim.amount",
|
||||
"claim.expense_type",
|
||||
"claim.department_name",
|
||||
"claim.reason",
|
||||
"item.item_reason",
|
||||
"application.id",
|
||||
"application.status",
|
||||
"application.approved_amount",
|
||||
"application.expense_type",
|
||||
"application.department_name",
|
||||
"material.plan_uploaded"
|
||||
],
|
||||
"search_fields": [
|
||||
"claim.reason",
|
||||
"item.item_reason",
|
||||
"claim.expense_type"
|
||||
],
|
||||
"keywords": [
|
||||
"市场推广",
|
||||
"活动申请",
|
||||
"投放方案"
|
||||
],
|
||||
"condition_summary": "市场推广费报销缺少活动申请或方案时触发。",
|
||||
"finance_rule_code": "expense.application.policy",
|
||||
"finance_rule_sheet": "费用申请前置规则",
|
||||
"business_stage": [
|
||||
"reimbursement"
|
||||
],
|
||||
"expense_types": [
|
||||
"marketing"
|
||||
],
|
||||
"budget_required": true
|
||||
},
|
||||
"outcomes": {
|
||||
"pass": {
|
||||
"severity": "none",
|
||||
"action": "continue"
|
||||
},
|
||||
"fail": {
|
||||
"severity": "medium",
|
||||
"action": "manual_review",
|
||||
"risk_score": 50
|
||||
}
|
||||
},
|
||||
"metadata": {
|
||||
"owner": "风控与审计部",
|
||||
"stability": "platform",
|
||||
"source_ref": "费用管控 Demo 风险规则库",
|
||||
"created_at": "2026-05-30T00:00:00Z",
|
||||
"created_by": "system",
|
||||
"risk_score": 50,
|
||||
"risk_level": "medium",
|
||||
"rule_title": "市场推广费无活动申请",
|
||||
"finance_rule_code": "expense.application.policy",
|
||||
"finance_rule_sheet": "费用申请前置规则",
|
||||
"business_stage": [
|
||||
"reimbursement"
|
||||
],
|
||||
"expense_types": [
|
||||
"marketing"
|
||||
],
|
||||
"budget_required": true,
|
||||
"risk_level_label": "中风险",
|
||||
"risk_score_model": "risk_score_v3",
|
||||
"risk_score_detail": {
|
||||
"score": 50,
|
||||
"level": "medium",
|
||||
"level_label": "中风险",
|
||||
"model": "risk_score_v3",
|
||||
"weights": {
|
||||
"impact": 0.35,
|
||||
"certainty": 0.25,
|
||||
"evidence": 0.15,
|
||||
"exception": 0.1,
|
||||
"action": 0.1,
|
||||
"sensitivity": 0.05
|
||||
},
|
||||
"components": {
|
||||
"impact": 48,
|
||||
"certainty": 58,
|
||||
"evidence": 62,
|
||||
"exception": 35,
|
||||
"action": 35,
|
||||
"sensitivity": 45
|
||||
},
|
||||
"calibration": {
|
||||
"raw_score": 50,
|
||||
"rules": []
|
||||
},
|
||||
"ai_evidence": {},
|
||||
"basis": {
|
||||
"template_key": "keyword_match_v1",
|
||||
"field_count": 11,
|
||||
"condition_count": 0,
|
||||
"expense_category": null,
|
||||
"expense_category_label": "申请前置",
|
||||
"requires_attachment": false
|
||||
}
|
||||
}
|
||||
},
|
||||
"severity": "medium",
|
||||
"risk_score": 50,
|
||||
"risk_level": "medium",
|
||||
"risk_level_label": "中风险",
|
||||
"risk_score_detail": {
|
||||
"score": 50,
|
||||
"level": "medium",
|
||||
"level_label": "中风险",
|
||||
"model": "risk_score_v3",
|
||||
"weights": {
|
||||
"impact": 0.35,
|
||||
"certainty": 0.25,
|
||||
"evidence": 0.15,
|
||||
"exception": 0.1,
|
||||
"action": 0.1,
|
||||
"sensitivity": 0.05
|
||||
},
|
||||
"components": {
|
||||
"impact": 48,
|
||||
"certainty": 58,
|
||||
"evidence": 62,
|
||||
"exception": 35,
|
||||
"action": 35,
|
||||
"sensitivity": 45
|
||||
},
|
||||
"calibration": {
|
||||
"raw_score": 50,
|
||||
"rules": []
|
||||
},
|
||||
"ai_evidence": {},
|
||||
"basis": {
|
||||
"template_key": "keyword_match_v1",
|
||||
"field_count": 11,
|
||||
"condition_count": 0,
|
||||
"expense_category": null,
|
||||
"expense_category_label": "申请前置",
|
||||
"requires_attachment": false
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,179 @@
|
||||
{
|
||||
"schema_version": "2.0",
|
||||
"rule_code": "risk.budget.available_balance_insufficient",
|
||||
"name": "预算可用余额不足",
|
||||
"description": "提交后预算余额为负，或当前可用预算不足以覆盖本次申请/报销金额。",
|
||||
"enabled": true,
|
||||
"requires_attachment": false,
|
||||
"risk_dimension": "expense_control_demo",
|
||||
"risk_category": "预算管控",
|
||||
"ontology_signal": "budget_over_limit",
|
||||
"evaluator": "template_rule",
|
||||
"template_key": "keyword_match_v1",
|
||||
"finance_rule_code": "budget.execution.policy",
|
||||
"finance_rule_sheet": "预算执行规则",
|
||||
"business_stage": [
|
||||
"expense_application",
|
||||
"reimbursement",
|
||||
"budget_execution"
|
||||
],
|
||||
"expense_types": [
|
||||
"travel",
|
||||
"hotel",
|
||||
"transport",
|
||||
"meal",
|
||||
"meeting",
|
||||
"marketing",
|
||||
"office",
|
||||
"training",
|
||||
"software",
|
||||
"communication",
|
||||
"welfare"
|
||||
],
|
||||
"budget_required": true,
|
||||
"applies_to": {
|
||||
"domains": [
|
||||
"expense"
|
||||
],
|
||||
"expense_types": [
|
||||
"travel",
|
||||
"hotel",
|
||||
"transport",
|
||||
"meal",
|
||||
"meeting",
|
||||
"marketing",
|
||||
"office",
|
||||
"training",
|
||||
"software",
|
||||
"communication",
|
||||
"welfare"
|
||||
],
|
||||
"business_stages": [
|
||||
"expense_application",
|
||||
"reimbursement",
|
||||
"budget_execution"
|
||||
]
|
||||
},
|
||||
"inputs": {
|
||||
"fields": [
|
||||
{
|
||||
"key": "claim.amount",
|
||||
"label": "报销金额",
|
||||
"type": "number",
|
||||
"source": "claim"
|
||||
},
|
||||
{
|
||||
"key": "claim.expense_type",
|
||||
"label": "费用类型",
|
||||
"type": "enum",
|
||||
"source": "claim"
|
||||
},
|
||||
{
|
||||
"key": "budget.available_amount",
|
||||
"label": "预算可用金额",
|
||||
"type": "number",
|
||||
"source": "budget"
|
||||
},
|
||||
{
|
||||
"key": "budget.status",
|
||||
"label": "预算状态",
|
||||
"type": "enum",
|
||||
"source": "budget"
|
||||
}
|
||||
]
|
||||
},
|
||||
"params": {
|
||||
"template_key": "keyword_match_v1",
|
||||
"field_keys": [
|
||||
"claim.amount",
|
||||
"claim.expense_type",
|
||||
"claim.department_name",
|
||||
"claim.reason",
|
||||
"item.item_reason",
|
||||
"budget.line_id",
|
||||
"budget.available_amount",
|
||||
"budget.used_rate",
|
||||
"budget.status",
|
||||
"budget.department_name",
|
||||
"budget.quarter",
|
||||
"budget.project_code"
|
||||
],
|
||||
"search_fields": [
|
||||
"claim.reason",
|
||||
"item.item_reason",
|
||||
"claim.expense_type"
|
||||
],
|
||||
"keywords": [
|
||||
"预算不足",
|
||||
"可用余额不足",
|
||||
"超预算"
|
||||
],
|
||||
"condition_summary": "预算可用金额小于本次金额时触发。",
|
||||
"finance_rule_code": "budget.execution.policy",
|
||||
"finance_rule_sheet": "预算执行规则",
|
||||
"business_stage": [
|
||||
"expense_application",
|
||||
"reimbursement",
|
||||
"budget_execution"
|
||||
],
|
||||
"expense_types": [
|
||||
"travel",
|
||||
"hotel",
|
||||
"transport",
|
||||
"meal",
|
||||
"meeting",
|
||||
"marketing",
|
||||
"office",
|
||||
"training",
|
||||
"software",
|
||||
"communication",
|
||||
"welfare"
|
||||
],
|
||||
"budget_required": true
|
||||
},
|
||||
"outcomes": {
|
||||
"pass": {
|
||||
"severity": "none",
|
||||
"action": "continue"
|
||||
},
|
||||
"fail": {
|
||||
"severity": "high",
|
||||
"action": "manual_review",
|
||||
"risk_score": 88
|
||||
}
|
||||
},
|
||||
"metadata": {
|
||||
"owner": "风控与审计部",
|
||||
"stability": "platform",
|
||||
"source_ref": "费用管控 Demo 风险规则库",
|
||||
"created_at": "2026-05-30T00:00:00Z",
|
||||
"created_by": "system",
|
||||
"risk_score": 88,
|
||||
"risk_level": "high",
|
||||
"rule_title": "预算可用余额不足",
|
||||
"finance_rule_code": "budget.execution.policy",
|
||||
"finance_rule_sheet": "预算执行规则",
|
||||
"business_stage": [
|
||||
"expense_application",
|
||||
"reimbursement",
|
||||
"budget_execution"
|
||||
],
|
||||
"expense_types": [
|
||||
"travel",
|
||||
"hotel",
|
||||
"transport",
|
||||
"meal",
|
||||
"meeting",
|
||||
"marketing",
|
||||
"office",
|
||||
"training",
|
||||
"software",
|
||||
"communication",
|
||||
"welfare"
|
||||
],
|
||||
"budget_required": true
|
||||
},
|
||||
"severity": "high",
|
||||
"risk_score": 88,
|
||||
"risk_level": "high"
|
||||
}
|
||||
@@ -18,21 +18,45 @@ from .employee_behavior_profile import (
|
||||
score_by_bands,
|
||||
)
|
||||
from .employee_behavior_profile_tags import build_profile_radar, build_profile_tags
|
||||
from .risk_graph import (
|
||||
ALGORITHM_VERSION as FINANCIAL_RISK_GRAPH_ALGORITHM_VERSION,
|
||||
RiskGraphClaimItemSnapshot,
|
||||
RiskGraphClaimSnapshot,
|
||||
RiskGraphEvaluationContext,
|
||||
RiskGraphEvaluationResult,
|
||||
RiskHistoryStats,
|
||||
RiskObservationDraft,
|
||||
evaluate_financial_risk_graph,
|
||||
map_ontology_to_risk_graph,
|
||||
normalize_risk_signal,
|
||||
normalize_risk_signals,
|
||||
)
|
||||
|
||||
__all__ = [
|
||||
"ApplicantExpenseProfileInput",
|
||||
"ApplicantExpenseProfileResult",
|
||||
"EMPLOYEE_BEHAVIOR_PROFILE_ALGORITHM_VERSION",
|
||||
"FINANCIAL_RISK_GRAPH_ALGORITHM_VERSION",
|
||||
"ProfileComponent",
|
||||
"ProfileScoreResult",
|
||||
"RiskGraphClaimItemSnapshot",
|
||||
"RiskGraphClaimSnapshot",
|
||||
"RiskGraphEvaluationContext",
|
||||
"RiskGraphEvaluationResult",
|
||||
"RiskHistoryStats",
|
||||
"RiskObservationDraft",
|
||||
"build_review_suggestions",
|
||||
"build_profile_radar",
|
||||
"build_profile_tags",
|
||||
"calculate_review_priority_score",
|
||||
"evaluate_applicant_expense_profile",
|
||||
"evaluate_financial_risk_graph",
|
||||
"evaluate_weighted_profile",
|
||||
"map_ontology_to_risk_graph",
|
||||
"employee_profile_level_from_score",
|
||||
"normalize_by_peer_percentiles",
|
||||
"normalize_risk_signal",
|
||||
"normalize_risk_signals",
|
||||
"percentile",
|
||||
"score_by_bands",
|
||||
]
|
||||
|
||||
33
server/src/app/algorithem/risk_graph/__init__.py
Normal file
33
server/src/app/algorithem/risk_graph/__init__.py
Normal file
@@ -0,0 +1,33 @@
|
||||
"""Financial behavior graph risk engine."""
|
||||
|
||||
from .engine import evaluate_financial_risk_graph
|
||||
from .models import (
|
||||
ALGORITHM_VERSION,
|
||||
RiskGraphClaimItemSnapshot,
|
||||
RiskGraphClaimSnapshot,
|
||||
RiskGraphEvaluationContext,
|
||||
RiskGraphEvaluationResult,
|
||||
RiskHistoryStats,
|
||||
RiskObservationDraft,
|
||||
)
|
||||
from .ontology import OntologyRiskGraphMapping, map_ontology_to_risk_graph
|
||||
from .profile_baselines import ProfileBaselineSnapshot, ProfileBaselineUpdater
|
||||
from .signals import NormalizedRiskSignal, normalize_risk_signal, normalize_risk_signals
|
||||
|
||||
__all__ = [
|
||||
"ALGORITHM_VERSION",
|
||||
"NormalizedRiskSignal",
|
||||
"OntologyRiskGraphMapping",
|
||||
"RiskGraphClaimItemSnapshot",
|
||||
"RiskGraphClaimSnapshot",
|
||||
"RiskGraphEvaluationContext",
|
||||
"RiskGraphEvaluationResult",
|
||||
"RiskHistoryStats",
|
||||
"RiskObservationDraft",
|
||||
"ProfileBaselineSnapshot",
|
||||
"ProfileBaselineUpdater",
|
||||
"evaluate_financial_risk_graph",
|
||||
"map_ontology_to_risk_graph",
|
||||
"normalize_risk_signal",
|
||||
"normalize_risk_signals",
|
||||
]
|
||||
175
server/src/app/algorithem/risk_graph/anomaly_models.py
Normal file
175
server/src/app/algorithem/risk_graph/anomaly_models.py
Normal file
@@ -0,0 +1,175 @@
|
||||
"""Deterministic multi-model anomaly detection for risk graph features."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from dataclasses import dataclass, field
|
||||
from datetime import datetime
|
||||
from decimal import Decimal
|
||||
from statistics import median
|
||||
from typing import Any
|
||||
|
||||
ZERO = Decimal("0")
|
||||
|
||||
|
||||
@dataclass(frozen=True, slots=True)
|
||||
class AnomalyPoint:
|
||||
key: str
|
||||
amount: Decimal
|
||||
occurred_at: datetime | None = None
|
||||
segment: str = ""
|
||||
metadata: dict[str, Any] = field(default_factory=dict)
|
||||
|
||||
|
||||
@dataclass(slots=True)
|
||||
class AnomalyModelSignal:
|
||||
method: str
|
||||
score: int
|
||||
reason: str
|
||||
related_keys: list[str] = field(default_factory=list)
|
||||
|
||||
def as_dict(self) -> dict[str, Any]:
|
||||
return {
|
||||
"method": self.method,
|
||||
"score": self.score,
|
||||
"reason": self.reason,
|
||||
"related_keys": list(self.related_keys),
|
||||
}
|
||||
|
||||
|
||||
class MultiModelAnomalyDetector:
|
||||
def detect(
|
||||
self,
|
||||
points: list[AnomalyPoint],
|
||||
*,
|
||||
target_key: str,
|
||||
) -> list[AnomalyModelSignal]:
|
||||
target = next((point for point in points if point.key == target_key), None)
|
||||
if target is None:
|
||||
return []
|
||||
peers = [
|
||||
point
|
||||
for point in points
|
||||
if point.key != target.key and (not target.segment or point.segment == target.segment)
|
||||
]
|
||||
if len(peers) < 3:
|
||||
return []
|
||||
|
||||
signals = [
|
||||
self._robust_statistical_signal(target, peers),
|
||||
self._isolation_proxy_signal(target, peers),
|
||||
self._local_outlier_signal(target, peers),
|
||||
self._temporal_jump_signal(target, peers),
|
||||
self._periodic_deviation_signal(target, peers),
|
||||
]
|
||||
return [signal for signal in signals if signal is not None]
|
||||
|
||||
def _robust_statistical_signal(
|
||||
self,
|
||||
target: AnomalyPoint,
|
||||
peers: list[AnomalyPoint],
|
||||
) -> AnomalyModelSignal | None:
|
||||
values = [point.amount for point in peers if point.amount >= ZERO]
|
||||
if len(values) < 3:
|
||||
return None
|
||||
center = Decimal(str(median(values)))
|
||||
deviations = [abs(value - center) for value in values]
|
||||
mad = Decimal(str(median(deviations))) or Decimal("1")
|
||||
modified_z = abs(target.amount - center) / mad
|
||||
if modified_z < Decimal("3"):
|
||||
return None
|
||||
return AnomalyModelSignal(
|
||||
method="robust_statistics",
|
||||
score=min(100, int(modified_z * Decimal("18"))),
|
||||
reason="Target amount deviates from peer median by robust MAD.",
|
||||
related_keys=[point.key for point in peers],
|
||||
)
|
||||
|
||||
def _isolation_proxy_signal(
|
||||
self,
|
||||
target: AnomalyPoint,
|
||||
peers: list[AnomalyPoint],
|
||||
) -> AnomalyModelSignal | None:
|
||||
values = sorted(point.amount for point in peers)
|
||||
if target.amount <= values[-1] * Decimal("1.8"):
|
||||
return None
|
||||
return AnomalyModelSignal(
|
||||
method="isolation_forest_proxy",
|
||||
score=min(100, int((target.amount / max(values[-1], Decimal("1"))) * Decimal("45"))),
|
||||
reason="Target amount is isolated beyond the peer maximum envelope.",
|
||||
related_keys=[point.key for point in peers[-5:]],
|
||||
)
|
||||
|
||||
def _local_outlier_signal(
|
||||
self,
|
||||
target: AnomalyPoint,
|
||||
peers: list[AnomalyPoint],
|
||||
) -> AnomalyModelSignal | None:
|
||||
distances = sorted((abs(target.amount - point.amount), point.key) for point in peers)
|
||||
nearest = distances[: min(3, len(distances))]
|
||||
peer_distances = [
|
||||
abs(left.amount - right.amount)
|
||||
for index, left in enumerate(peers)
|
||||
for right in peers[index + 1 :]
|
||||
]
|
||||
local_scale = Decimal(str(median(peer_distances))) if peer_distances else Decimal("1")
|
||||
local_scale = max(local_scale, Decimal("1"))
|
||||
target_distance = sum((distance for distance, _ in nearest), ZERO) / Decimal(len(nearest))
|
||||
ratio = target_distance / local_scale
|
||||
if ratio < Decimal("2.5"):
|
||||
return None
|
||||
return AnomalyModelSignal(
|
||||
method="local_outlier_factor_proxy",
|
||||
score=min(100, int(ratio * Decimal("24"))),
|
||||
reason="Target is far away from its nearest peer neighborhood.",
|
||||
related_keys=[key for _, key in nearest],
|
||||
)
|
||||
|
||||
def _temporal_jump_signal(
|
||||
self,
|
||||
target: AnomalyPoint,
|
||||
peers: list[AnomalyPoint],
|
||||
) -> AnomalyModelSignal | None:
|
||||
if target.occurred_at is None:
|
||||
return None
|
||||
previous = [
|
||||
point
|
||||
for point in peers
|
||||
if point.occurred_at is not None and point.occurred_at < target.occurred_at
|
||||
]
|
||||
previous = sorted(previous, key=lambda item: item.occurred_at or datetime.min)[-3:]
|
||||
if len(previous) < 3:
|
||||
return None
|
||||
average = sum((point.amount for point in previous), ZERO) / Decimal(len(previous))
|
||||
if average <= ZERO or target.amount < average * Decimal("2.2"):
|
||||
return None
|
||||
return AnomalyModelSignal(
|
||||
method="temporal_jump",
|
||||
score=min(100, int((target.amount / average) * Decimal("32"))),
|
||||
reason="Target amount jumps above the recent moving average.",
|
||||
related_keys=[point.key for point in previous],
|
||||
)
|
||||
|
||||
def _periodic_deviation_signal(
|
||||
self,
|
||||
target: AnomalyPoint,
|
||||
peers: list[AnomalyPoint],
|
||||
) -> AnomalyModelSignal | None:
|
||||
if target.occurred_at is None:
|
||||
return None
|
||||
same_period = [
|
||||
point
|
||||
for point in peers
|
||||
if point.occurred_at is not None
|
||||
and point.occurred_at.weekday() == target.occurred_at.weekday()
|
||||
]
|
||||
if len(same_period) < 2:
|
||||
return None
|
||||
average = sum((point.amount for point in same_period), ZERO) / Decimal(len(same_period))
|
||||
if average <= ZERO or target.amount < average * Decimal("2"):
|
||||
return None
|
||||
return AnomalyModelSignal(
|
||||
method="periodic_deviation",
|
||||
score=min(100, int((target.amount / average) * Decimal("30"))),
|
||||
reason="Target deviates from same-weekday periodic peer behavior.",
|
||||
related_keys=[point.key for point in same_period],
|
||||
)
|
||||
183
server/src/app/algorithem/risk_graph/consistency.py
Normal file
183
server/src/app/algorithem/risk_graph/consistency.py
Normal file
@@ -0,0 +1,183 @@
|
||||
"""Multi-evidence and spatiotemporal consistency checks."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from datetime import date, datetime
|
||||
from decimal import Decimal
|
||||
from typing import Any
|
||||
|
||||
from .models import RiskEvidence, RiskGraphClaimSnapshot
|
||||
from .signals import NormalizedRiskSignal, normalize_risk_signals
|
||||
|
||||
ZERO = Decimal("0")
|
||||
|
||||
|
||||
def evaluate_claim_consistency(
|
||||
claim: RiskGraphClaimSnapshot,
|
||||
) -> tuple[list[RiskEvidence], list[NormalizedRiskSignal]]:
|
||||
evidence: list[RiskEvidence] = []
|
||||
signals: list[NormalizedRiskSignal] = []
|
||||
|
||||
if _has_location_mismatch(claim):
|
||||
evidence.append(
|
||||
RiskEvidence(
|
||||
code="location_mismatch_graph",
|
||||
title="Location mismatch graph",
|
||||
detail="Claim location and item location are not aligned.",
|
||||
source="spatiotemporal",
|
||||
score=64,
|
||||
)
|
||||
)
|
||||
signals.extend(normalize_risk_signals(["location_mismatch"], source="spatiotemporal"))
|
||||
|
||||
amount_mismatch = _document_amount_mismatch(claim)
|
||||
if amount_mismatch:
|
||||
evidence.append(
|
||||
RiskEvidence(
|
||||
code="document_amount_mismatch",
|
||||
title="Document amount mismatch",
|
||||
detail="Claim amount and item amount sum are not aligned.",
|
||||
source="multi_evidence",
|
||||
score=72,
|
||||
metadata=amount_mismatch,
|
||||
)
|
||||
)
|
||||
signals.extend(
|
||||
normalize_risk_signals(
|
||||
[{"risk_signal": "document_expense_mismatch", "score": 72}],
|
||||
source="multi_evidence",
|
||||
)
|
||||
)
|
||||
|
||||
invoice_count_mismatch = _invoice_count_mismatch(claim)
|
||||
if invoice_count_mismatch:
|
||||
evidence.append(
|
||||
RiskEvidence(
|
||||
code="invoice_count_mismatch",
|
||||
title="Invoice count mismatch",
|
||||
detail="Declared invoice count and attached invoice count are not aligned.",
|
||||
source="multi_evidence",
|
||||
score=62,
|
||||
metadata=invoice_count_mismatch,
|
||||
)
|
||||
)
|
||||
signals.extend(
|
||||
normalize_risk_signals(
|
||||
[{"risk_signal": "document_expense_mismatch", "score": 62}],
|
||||
source="multi_evidence",
|
||||
)
|
||||
)
|
||||
|
||||
date_mismatch = _item_date_outside_claim_window(claim)
|
||||
if date_mismatch:
|
||||
evidence.append(
|
||||
RiskEvidence(
|
||||
code="date_outside_claim_window",
|
||||
title="Date outside claim window",
|
||||
detail="Item date is too far away from the claim occurrence date.",
|
||||
source="spatiotemporal",
|
||||
score=78,
|
||||
metadata=date_mismatch,
|
||||
)
|
||||
)
|
||||
signals.extend(normalize_risk_signals(["date_outside_trip"], source="spatiotemporal"))
|
||||
|
||||
return evidence, signals
|
||||
|
||||
|
||||
def _has_location_mismatch(claim: RiskGraphClaimSnapshot) -> bool:
|
||||
claim_location = _canonical_key(claim.location)
|
||||
if not claim_location or not claim.items:
|
||||
return False
|
||||
item_locations = {
|
||||
_canonical_key(item.item_location)
|
||||
for item in claim.items
|
||||
if str(item.item_location or "").strip()
|
||||
}
|
||||
if not item_locations:
|
||||
return False
|
||||
return any(location and location != claim_location for location in item_locations)
|
||||
|
||||
|
||||
def _document_amount_mismatch(claim: RiskGraphClaimSnapshot) -> dict[str, str] | None:
|
||||
if not claim.items:
|
||||
return None
|
||||
claim_amount = _to_decimal(claim.amount)
|
||||
item_amount_sum = sum((_to_decimal(item.item_amount) for item in claim.items), ZERO)
|
||||
if claim_amount <= ZERO or item_amount_sum <= ZERO:
|
||||
return None
|
||||
difference = abs(claim_amount - item_amount_sum)
|
||||
tolerance = max(Decimal("1"), claim_amount * Decimal("0.02"))
|
||||
if difference <= tolerance:
|
||||
return None
|
||||
return {
|
||||
"claim_amount": str(claim_amount),
|
||||
"item_amount_sum": str(item_amount_sum),
|
||||
"difference": str(difference),
|
||||
"tolerance": str(tolerance),
|
||||
}
|
||||
|
||||
|
||||
def _invoice_count_mismatch(claim: RiskGraphClaimSnapshot) -> dict[str, Any] | None:
|
||||
declared_count = int(claim.invoice_count or 0)
|
||||
if declared_count <= 0:
|
||||
return None
|
||||
invoice_ids = sorted(
|
||||
{
|
||||
str(item.invoice_id or "").strip()
|
||||
for item in claim.items
|
||||
if str(item.invoice_id or "").strip()
|
||||
}
|
||||
)
|
||||
actual_count = len(invoice_ids)
|
||||
if declared_count == actual_count:
|
||||
return None
|
||||
return {
|
||||
"declared_invoice_count": declared_count,
|
||||
"actual_invoice_count": actual_count,
|
||||
"invoice_ids": invoice_ids,
|
||||
}
|
||||
|
||||
|
||||
def _item_date_outside_claim_window(claim: RiskGraphClaimSnapshot) -> dict[str, Any] | None:
|
||||
occurred_date = _date_from_value(claim.occurred_at)
|
||||
if occurred_date is None or not claim.items:
|
||||
return None
|
||||
mismatches: list[dict[str, Any]] = []
|
||||
for item in claim.items:
|
||||
item_date = _date_from_value(item.item_date)
|
||||
if item_date is None:
|
||||
continue
|
||||
distance_days = abs((item_date - occurred_date).days)
|
||||
if distance_days <= 7:
|
||||
continue
|
||||
mismatches.append(
|
||||
{
|
||||
"item_id": item.item_id,
|
||||
"item_date": item_date.isoformat(),
|
||||
"occurred_at": occurred_date.isoformat(),
|
||||
"distance_days": distance_days,
|
||||
}
|
||||
)
|
||||
return {"mismatches": mismatches} if mismatches else None
|
||||
|
||||
|
||||
def _date_from_value(value: Any) -> date | None:
|
||||
if value is None:
|
||||
return None
|
||||
if isinstance(value, datetime):
|
||||
return value.date()
|
||||
if isinstance(value, date):
|
||||
return value
|
||||
return None
|
||||
|
||||
|
||||
def _canonical_key(value: Any) -> str:
|
||||
return "_".join(str(value or "").strip().lower().split())
|
||||
|
||||
|
||||
def _to_decimal(value: Any) -> Decimal:
|
||||
try:
|
||||
return Decimal(str(value or "0"))
|
||||
except Exception:
|
||||
return ZERO
|
||||
77
server/src/app/algorithem/risk_graph/control_effect.py
Normal file
77
server/src/app/algorithem/risk_graph/control_effect.py
Normal file
@@ -0,0 +1,77 @@
|
||||
"""Control effect analysis for risk rules, sampling, and digital employees."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from dataclasses import dataclass
|
||||
from typing import Any
|
||||
|
||||
HIGH_LEVELS = {"high", "critical"}
|
||||
|
||||
|
||||
@dataclass(slots=True)
|
||||
class ControlEffectSummary:
|
||||
before_count: int
|
||||
after_count: int
|
||||
risk_count_delta: int
|
||||
average_score_delta: float
|
||||
high_rate_delta: float
|
||||
confirmation_rate_delta: float
|
||||
false_positive_rate_delta: float
|
||||
|
||||
def as_dict(self) -> dict[str, Any]:
|
||||
return {
|
||||
"before_count": self.before_count,
|
||||
"after_count": self.after_count,
|
||||
"risk_count_delta": self.risk_count_delta,
|
||||
"average_score_delta": self.average_score_delta,
|
||||
"high_rate_delta": self.high_rate_delta,
|
||||
"confirmation_rate_delta": self.confirmation_rate_delta,
|
||||
"false_positive_rate_delta": self.false_positive_rate_delta,
|
||||
}
|
||||
|
||||
|
||||
class ControlEffectAnalyzer:
|
||||
def compare(
|
||||
self,
|
||||
before: list[dict[str, Any]],
|
||||
after: list[dict[str, Any]],
|
||||
) -> ControlEffectSummary:
|
||||
before_metrics = _metrics(before)
|
||||
after_metrics = _metrics(after)
|
||||
return ControlEffectSummary(
|
||||
before_count=before_metrics["count"],
|
||||
after_count=after_metrics["count"],
|
||||
risk_count_delta=after_metrics["count"] - before_metrics["count"],
|
||||
average_score_delta=round(after_metrics["average_score"] - before_metrics["average_score"], 4),
|
||||
high_rate_delta=round(after_metrics["high_rate"] - before_metrics["high_rate"], 4),
|
||||
confirmation_rate_delta=round(
|
||||
after_metrics["confirmation_rate"] - before_metrics["confirmation_rate"],
|
||||
4,
|
||||
),
|
||||
false_positive_rate_delta=round(
|
||||
after_metrics["false_positive_rate"] - before_metrics["false_positive_rate"],
|
||||
4,
|
||||
),
|
||||
)
|
||||
|
||||
|
||||
def _metrics(items: list[dict[str, Any]]) -> dict[str, Any]:
|
||||
count = len(items)
|
||||
if count == 0:
|
||||
return {
|
||||
"count": 0,
|
||||
"average_score": 0.0,
|
||||
"high_rate": 0.0,
|
||||
"confirmation_rate": 0.0,
|
||||
"false_positive_rate": 0.0,
|
||||
}
|
||||
confirmed = sum(1 for item in items if item.get("feedback_status") == "confirmed")
|
||||
false_positive = sum(1 for item in items if item.get("feedback_status") == "false_positive")
|
||||
reviewed = confirmed + false_positive
|
||||
return {
|
||||
"count": count,
|
||||
"average_score": sum(int(item.get("risk_score") or 0) for item in items) / count,
|
||||
"high_rate": sum(1 for item in items if item.get("risk_level") in HIGH_LEVELS) / count,
|
||||
"confirmation_rate": confirmed / reviewed if reviewed else 0.0,
|
||||
"false_positive_rate": false_positive / reviewed if reviewed else 0.0,
|
||||
}
|
||||
82
server/src/app/algorithem/risk_graph/counterfactual.py
Normal file
82
server/src/app/algorithem/risk_graph/counterfactual.py
Normal file
@@ -0,0 +1,82 @@
|
||||
"""Counterfactual recommendations for reducing financial risk scores."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from dataclasses import dataclass
|
||||
from typing import Any
|
||||
|
||||
|
||||
@dataclass(slots=True)
|
||||
class CounterfactualRiskAction:
|
||||
action_key: str
|
||||
title: str
|
||||
detail: str
|
||||
related_feature: str
|
||||
expected_score_delta: int
|
||||
|
||||
def as_dict(self) -> dict[str, Any]:
|
||||
return {
|
||||
"action_key": self.action_key,
|
||||
"title": self.title,
|
||||
"detail": self.detail,
|
||||
"related_feature": self.related_feature,
|
||||
"expected_score_delta": self.expected_score_delta,
|
||||
}
|
||||
|
||||
|
||||
class CounterfactualRiskAdvisor:
|
||||
def advise(self, observation: dict[str, Any]) -> list[CounterfactualRiskAction]:
|
||||
scores = dict(
|
||||
observation.get("contribution_scores")
|
||||
or observation.get("decision_trace", {}).get("input_scores")
|
||||
or {}
|
||||
)
|
||||
evidence_codes = {
|
||||
str(item.get("code") or "")
|
||||
for item in observation.get("evidence", [])
|
||||
if isinstance(item, dict)
|
||||
}
|
||||
trace = observation.get("decision_trace") or {}
|
||||
actions: list[CounterfactualRiskAction] = []
|
||||
|
||||
if int(scores.get("S_rule") or 0) >= 70:
|
||||
actions.append(
|
||||
CounterfactualRiskAction(
|
||||
action_key="complete_preapproval_or_required_attachment",
|
||||
title="Complete required approval evidence",
|
||||
detail="补齐事前申请、审批记录或制度要求的附件，可降低规则命中风险。",
|
||||
related_feature="S_rule",
|
||||
expected_score_delta=-20,
|
||||
)
|
||||
)
|
||||
if int(scores.get("S_anomaly") or 0) >= 70:
|
||||
actions.append(
|
||||
CounterfactualRiskAction(
|
||||
action_key="align_amount_with_peer_baseline",
|
||||
title="Align amount with peer baseline",
|
||||
detail="补充高金额原因或拆出不属于本次报销的费用，可降低基线偏离风险。",
|
||||
related_feature="S_anomaly",
|
||||
expected_score_delta=-18,
|
||||
)
|
||||
)
|
||||
if int(scores.get("S_graph") or 0) >= 70 or "duplicate_invoice_graph" in evidence_codes:
|
||||
actions.append(
|
||||
CounterfactualRiskAction(
|
||||
action_key="replace_duplicate_or_conflicting_invoice",
|
||||
title="Replace conflicting invoice",
|
||||
detail="替换重复票据、修正票据归属或说明跨单据复用原因，可降低图谱异常风险。",
|
||||
related_feature="S_graph",
|
||||
expected_score_delta=-25,
|
||||
)
|
||||
)
|
||||
if trace.get("data_quality_gate") not in {"", "passed", None}:
|
||||
actions.append(
|
||||
CounterfactualRiskAction(
|
||||
action_key="supplement_missing_risk_data",
|
||||
title="Supplement missing risk data",
|
||||
detail="补齐员工、金额、费用类型、票据明细等关键字段后再进入强风控判断。",
|
||||
related_feature="data_quality",
|
||||
expected_score_delta=-10,
|
||||
)
|
||||
)
|
||||
return actions
|
||||
132
server/src/app/algorithem/risk_graph/decisioning.py
Normal file
132
server/src/app/algorithem/risk_graph/decisioning.py
Normal file
@@ -0,0 +1,132 @@
|
||||
"""Decision trace and explanation helpers for risk graph observations."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from dataclasses import dataclass, field
|
||||
from decimal import Decimal
|
||||
from typing import Any
|
||||
|
||||
from .models import PeerBaseline, RiskEvidence
|
||||
|
||||
RISK_SCORE_FORMULA = (
|
||||
"0.35*S_rule + 0.25*S_anomaly + "
|
||||
"0.20*S_graph + 0.15*S_policy + 0.05*S_history"
|
||||
)
|
||||
|
||||
|
||||
@dataclass(slots=True)
|
||||
class DecisionTrace:
|
||||
formula: str
|
||||
algorithm_version: str
|
||||
input_scores: dict[str, int]
|
||||
output_score: int
|
||||
decision_row: str
|
||||
feature_contributions_json: list[dict[str, Any]]
|
||||
uncertainty_reasons_json: list[str]
|
||||
explanation_template_key: str
|
||||
metadata: dict[str, Any] = field(default_factory=dict)
|
||||
|
||||
def as_dict(self) -> dict[str, Any]:
|
||||
return {
|
||||
"formula": self.formula,
|
||||
"algorithm_version": self.algorithm_version,
|
||||
"input_scores": dict(self.input_scores),
|
||||
"output_score": self.output_score,
|
||||
"decision_row": self.decision_row,
|
||||
"feature_contributions_json": list(self.feature_contributions_json),
|
||||
"uncertainty_reasons_json": list(self.uncertainty_reasons_json),
|
||||
"explanation_template_key": self.explanation_template_key,
|
||||
**self.metadata,
|
||||
}
|
||||
|
||||
|
||||
class DecisionTraceBuilder:
|
||||
def build(
|
||||
self,
|
||||
*,
|
||||
algorithm_version: str,
|
||||
risk_signal: str,
|
||||
risk_level: str,
|
||||
raw_risk_score: int,
|
||||
risk_score: int,
|
||||
contribution_scores: dict[str, int],
|
||||
evidence: list[RiskEvidence],
|
||||
baseline: PeerBaseline,
|
||||
confidence: Decimal,
|
||||
metadata: dict[str, Any],
|
||||
) -> DecisionTrace:
|
||||
return DecisionTrace(
|
||||
formula=RISK_SCORE_FORMULA,
|
||||
algorithm_version=algorithm_version,
|
||||
input_scores=contribution_scores,
|
||||
output_score=risk_score,
|
||||
decision_row=_decision_row(risk_score=risk_score, risk_level=risk_level),
|
||||
feature_contributions_json=_feature_contributions(contribution_scores),
|
||||
uncertainty_reasons_json=_uncertainty_reasons(
|
||||
raw_risk_score=raw_risk_score,
|
||||
risk_score=risk_score,
|
||||
evidence=evidence,
|
||||
baseline=baseline,
|
||||
confidence=confidence,
|
||||
metadata=metadata,
|
||||
),
|
||||
explanation_template_key=f"risk.{risk_signal}.{risk_level}",
|
||||
metadata=metadata,
|
||||
)
|
||||
|
||||
|
||||
def _decision_row(*, risk_score: int, risk_level: str) -> str:
|
||||
if risk_score >= 90:
|
||||
return f"{risk_level}:score>=90"
|
||||
if risk_score >= 70:
|
||||
return f"{risk_level}:70<=score<90"
|
||||
if risk_score >= 45:
|
||||
return f"{risk_level}:45<=score<70"
|
||||
return f"{risk_level}:score<45"
|
||||
|
||||
|
||||
def _feature_contributions(scores: dict[str, int]) -> list[dict[str, Any]]:
|
||||
weights = {
|
||||
"S_rule": Decimal("0.35"),
|
||||
"S_anomaly": Decimal("0.25"),
|
||||
"S_graph": Decimal("0.20"),
|
||||
"S_policy": Decimal("0.15"),
|
||||
"S_history": Decimal("0.05"),
|
||||
}
|
||||
rows = []
|
||||
for key, score in scores.items():
|
||||
weighted_score = Decimal(int(score or 0)) * weights.get(key, Decimal("0"))
|
||||
rows.append(
|
||||
{
|
||||
"feature": key,
|
||||
"score": int(score or 0),
|
||||
"weight": str(weights.get(key, Decimal("0"))),
|
||||
"weighted_score": float(weighted_score),
|
||||
}
|
||||
)
|
||||
return sorted(rows, key=lambda item: item["weighted_score"], reverse=True)
|
||||
|
||||
|
||||
def _uncertainty_reasons(
|
||||
*,
|
||||
raw_risk_score: int,
|
||||
risk_score: int,
|
||||
evidence: list[RiskEvidence],
|
||||
baseline: PeerBaseline,
|
||||
confidence: Decimal,
|
||||
metadata: dict[str, Any],
|
||||
) -> list[str]:
|
||||
reasons: list[str] = []
|
||||
if risk_score < raw_risk_score:
|
||||
reasons.append("score_capped_by_gate")
|
||||
if baseline.scope == "insufficient_sample" or baseline.sample_size <= 0:
|
||||
reasons.append("peer_baseline_insufficient")
|
||||
if confidence < Decimal("0.55"):
|
||||
reasons.append("low_confidence")
|
||||
if len({item.source for item in evidence if item.source}) < 2:
|
||||
reasons.append("single_evidence_source")
|
||||
if metadata.get("ontology_gate") == "candidate_only":
|
||||
reasons.append("ontology_candidate_only")
|
||||
if metadata.get("data_quality_gate") not in {"", "passed", None}:
|
||||
reasons.append("data_quality_gate_not_passed")
|
||||
return list(dict.fromkeys(reasons))
|
||||
794
server/src/app/algorithem/risk_graph/engine.py
Normal file
794
server/src/app/algorithem/risk_graph/engine.py
Normal file
@@ -0,0 +1,794 @@
|
||||
"""Financial behavior graph risk scoring engine."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from decimal import ROUND_CEILING, ROUND_FLOOR, ROUND_HALF_UP, Decimal
|
||||
from typing import Any
|
||||
|
||||
from .consistency import evaluate_claim_consistency
|
||||
from .decisioning import DecisionTraceBuilder
|
||||
from .graph import build_claim_graph, claim_node_key, employee_node_key
|
||||
from .models import (
|
||||
ALGORITHM_VERSION,
|
||||
AUTOMATION_ASSIST,
|
||||
AUTOMATION_AUTO_HOLD,
|
||||
AUTOMATION_MANUAL_REVIEW,
|
||||
AUTOMATION_SEMI_AUTO_REVIEW,
|
||||
LEVEL_CRITICAL,
|
||||
LEVEL_HIGH,
|
||||
LEVEL_LOW,
|
||||
LEVEL_MEDIUM,
|
||||
PeerBaseline,
|
||||
RiskEvidence,
|
||||
RiskGraphClaimSnapshot,
|
||||
RiskGraphEdge,
|
||||
RiskGraphEvaluationContext,
|
||||
RiskGraphEvaluationResult,
|
||||
RiskGraphNode,
|
||||
RiskHistoryStats,
|
||||
RiskObservationDraft,
|
||||
)
|
||||
from .ontology import map_ontology_to_risk_graph
|
||||
from .quality import RiskDataQualityGate
|
||||
from .sampling import RiskSamplingPlanner
|
||||
from .signals import (
|
||||
NormalizedRiskSignal,
|
||||
normalize_risk_signals,
|
||||
policy_refs_for_signal,
|
||||
)
|
||||
|
||||
ZERO = Decimal("0")
|
||||
ONE = Decimal("1")
|
||||
HUNDRED = Decimal("100")
|
||||
DATA_QUALITY_GATE = RiskDataQualityGate()
|
||||
SAMPLING_PLANNER = RiskSamplingPlanner()
|
||||
DECISION_TRACE_BUILDER = DecisionTraceBuilder()
|
||||
|
||||
|
||||
def evaluate_financial_risk_graph(
|
||||
context: RiskGraphEvaluationContext,
|
||||
) -> RiskGraphEvaluationResult:
|
||||
nodes, edges = build_claim_graph(context.claims)
|
||||
ontology_mapping = map_ontology_to_risk_graph(
|
||||
context.ontology_parse,
|
||||
ontology_parse_id=context.ontology_parse_id,
|
||||
ontology_version=context.ontology_version,
|
||||
)
|
||||
nodes = _merge_nodes(nodes, ontology_mapping.nodes)
|
||||
edges = _merge_edges(edges, ontology_mapping.edges)
|
||||
|
||||
target_ids = context.target_claim_ids or {claim.claim_id for claim in context.claims}
|
||||
target_claims = [claim for claim in context.claims if claim.claim_id in target_ids]
|
||||
observations: list[RiskObservationDraft] = []
|
||||
|
||||
for claim in target_claims:
|
||||
baseline = _resolve_peer_baseline(claim, context.claims, context.min_peer_sample_size)
|
||||
rule_score, rule_evidence, rule_signals = _score_rule_signals(claim)
|
||||
anomaly_score, anomaly_evidence = _score_amount_anomaly(claim, baseline)
|
||||
graph_score, graph_evidence, graph_signals = _score_graph_anomaly(claim, context)
|
||||
policy_score, policy_evidence, policy_refs = _score_policy_relevance(
|
||||
rule_signals + graph_signals + ontology_mapping.risk_signals,
|
||||
)
|
||||
history_score, history_evidence, history = _score_history(
|
||||
claim,
|
||||
rule_signals + graph_signals + ontology_mapping.risk_signals,
|
||||
context.history_stats,
|
||||
)
|
||||
|
||||
contribution_scores = {
|
||||
"S_rule": rule_score,
|
||||
"S_anomaly": anomaly_score,
|
||||
"S_graph": graph_score,
|
||||
"S_policy": policy_score,
|
||||
"S_history": history_score,
|
||||
}
|
||||
raw_risk_score = _weighted_risk_score(contribution_scores)
|
||||
quality_result = DATA_QUALITY_GATE.evaluate_claim(claim)
|
||||
evidence = [
|
||||
*rule_evidence,
|
||||
*anomaly_evidence,
|
||||
*graph_evidence,
|
||||
*policy_evidence,
|
||||
*history_evidence,
|
||||
]
|
||||
risk_score, evidence_source_gate = _apply_evidence_source_gate(
|
||||
raw_risk_score,
|
||||
evidence,
|
||||
)
|
||||
risk_score, data_quality_gate = DATA_QUALITY_GATE.apply_score_cap(
|
||||
risk_score,
|
||||
quality_result,
|
||||
)
|
||||
if risk_score < context.observation_threshold and ontology_mapping.gate != "candidate_only":
|
||||
continue
|
||||
if risk_score < context.observation_threshold and not ontology_mapping.risk_signals:
|
||||
continue
|
||||
|
||||
evidence_source_count = _evidence_source_count(evidence)
|
||||
primary_signal = _select_primary_signal(
|
||||
rule_signals + graph_signals + ontology_mapping.risk_signals,
|
||||
fallback_score=risk_score,
|
||||
)
|
||||
confidence = _calculate_confidence(
|
||||
evidence=evidence,
|
||||
baseline=baseline,
|
||||
ontology_confidence=ontology_mapping.confidence,
|
||||
history=history,
|
||||
data_quality_ok=quality_result.passed,
|
||||
)
|
||||
automation_mode = _resolve_automation_mode(
|
||||
risk_score=risk_score,
|
||||
confidence=confidence,
|
||||
evidence_count=len(evidence),
|
||||
history=history,
|
||||
)
|
||||
sampling_decision = SAMPLING_PLANNER.plan(
|
||||
risk_score=risk_score,
|
||||
confidence=confidence,
|
||||
evidence_source_count=evidence_source_count,
|
||||
data_quality_passed=quality_result.passed,
|
||||
data_quality_gate=data_quality_gate,
|
||||
history=history,
|
||||
)
|
||||
risk_level = _level_from_score(risk_score)
|
||||
decision_metadata = {
|
||||
"raw_risk_score": raw_risk_score,
|
||||
"evidence_source_count": evidence_source_count,
|
||||
"evidence_source_gate": evidence_source_gate,
|
||||
"data_quality_gate": data_quality_gate,
|
||||
"data_quality": quality_result.as_dict(),
|
||||
"sampling_strategy": sampling_decision.as_dict(),
|
||||
"contribution_scores": contribution_scores,
|
||||
"baseline_scope": baseline.scope,
|
||||
"ontology_gate": ontology_mapping.gate,
|
||||
}
|
||||
decision_trace = DECISION_TRACE_BUILDER.build(
|
||||
algorithm_version=ALGORITHM_VERSION,
|
||||
risk_signal=primary_signal.code,
|
||||
risk_level=risk_level,
|
||||
raw_risk_score=raw_risk_score,
|
||||
risk_score=risk_score,
|
||||
contribution_scores=contribution_scores,
|
||||
evidence=evidence,
|
||||
baseline=baseline,
|
||||
confidence=confidence,
|
||||
metadata=decision_metadata,
|
||||
)
|
||||
graph_node_keys = _claim_related_node_keys(claim, nodes)
|
||||
graph_edge_keys = _claim_related_edge_keys(claim, edges)
|
||||
similar_case_ids = _similar_case_ids(claim, context.claims)
|
||||
|
||||
observations.append(
|
||||
RiskObservationDraft(
|
||||
observation_key=f"risk:{claim.claim_id}:{primary_signal.code}",
|
||||
subject_type="expense_claim",
|
||||
subject_key=f"claim:{claim.claim_id}",
|
||||
subject_label=claim.claim_no or claim.claim_id,
|
||||
claim_id=claim.claim_id,
|
||||
claim_no=claim.claim_no,
|
||||
risk_type=primary_signal.code,
|
||||
risk_signal=primary_signal.code,
|
||||
title=f"{primary_signal.label} risk",
|
||||
description=_build_description(claim, primary_signal, risk_score, evidence),
|
||||
risk_score=risk_score,
|
||||
risk_level=risk_level,
|
||||
confidence_score=confidence,
|
||||
control_stage="reimbursement",
|
||||
control_mode="risk_observation",
|
||||
automation_mode=automation_mode,
|
||||
source="financial_risk_graph",
|
||||
algorithm_version=ALGORITHM_VERSION,
|
||||
contribution_scores=contribution_scores,
|
||||
baseline=baseline,
|
||||
evidence=evidence,
|
||||
graph_node_keys=graph_node_keys,
|
||||
graph_edge_keys=graph_edge_keys,
|
||||
policy_refs=policy_refs,
|
||||
similar_case_claim_ids=similar_case_ids,
|
||||
ontology_json=ontology_mapping.as_dict(),
|
||||
decision_trace=decision_trace.as_dict(),
|
||||
)
|
||||
)
|
||||
|
||||
return RiskGraphEvaluationResult(
|
||||
observations=sorted(observations, key=lambda item: item.risk_score, reverse=True),
|
||||
nodes=nodes,
|
||||
edges=edges,
|
||||
)
|
||||
|
||||
|
||||
def _score_rule_signals(
|
||||
claim: RiskGraphClaimSnapshot,
|
||||
) -> tuple[int, list[RiskEvidence], list[NormalizedRiskSignal]]:
|
||||
signals = normalize_risk_signals(claim.risk_flags, source="rule")
|
||||
if not signals:
|
||||
return 0, [], []
|
||||
score = min(100, max(item.score for item in signals) + max(0, len(signals) - 1) * 5)
|
||||
evidence = [
|
||||
RiskEvidence(
|
||||
code="rule_signal",
|
||||
title="Rule signal",
|
||||
detail=f"{signal.label}: {signal.severity}",
|
||||
source="rule",
|
||||
score=signal.score,
|
||||
metadata=signal.as_dict(),
|
||||
)
|
||||
for signal in signals
|
||||
]
|
||||
return score, evidence, signals
|
||||
|
||||
|
||||
def _score_amount_anomaly(
|
||||
claim: RiskGraphClaimSnapshot,
|
||||
baseline: PeerBaseline,
|
||||
) -> tuple[int, list[RiskEvidence]]:
|
||||
amount = _to_decimal(claim.amount)
|
||||
if baseline.sample_size <= 0 or baseline.p75_amount <= ZERO:
|
||||
return 0, [
|
||||
RiskEvidence(
|
||||
code="baseline_unavailable",
|
||||
title="Baseline unavailable",
|
||||
detail=baseline.fallback_reason or "No comparable peer sample.",
|
||||
source="baseline",
|
||||
)
|
||||
]
|
||||
|
||||
ratio = _safe_ratio(amount, baseline.p75_amount)
|
||||
score = _score_ratio(
|
||||
ratio,
|
||||
[
|
||||
(Decimal("1.00"), 0),
|
||||
(Decimal("1.25"), 30),
|
||||
(Decimal("1.50"), 55),
|
||||
(Decimal("2.00"), 75),
|
||||
(Decimal("3.00"), 95),
|
||||
],
|
||||
)
|
||||
if score <= 0:
|
||||
return 0, []
|
||||
return score, [
|
||||
RiskEvidence(
|
||||
code="peer_amount_deviation",
|
||||
title="Peer amount deviation",
|
||||
detail=(
|
||||
f"Claim amount {amount} is {ratio.quantize(Decimal('0.0001'))} "
|
||||
f"times peer p75 {baseline.p75_amount}."
|
||||
),
|
||||
source="baseline",
|
||||
score=score,
|
||||
metadata={"ratio": str(ratio), "baseline": baseline.as_dict()},
|
||||
)
|
||||
]
|
||||
|
||||
|
||||
def _score_graph_anomaly(
|
||||
claim: RiskGraphClaimSnapshot,
|
||||
context: RiskGraphEvaluationContext,
|
||||
) -> tuple[int, list[RiskEvidence], list[NormalizedRiskSignal]]:
|
||||
evidence: list[RiskEvidence] = []
|
||||
signals: list[NormalizedRiskSignal] = []
|
||||
|
||||
duplicate_claims = _duplicate_invoice_claims(claim, context.claims)
|
||||
if duplicate_claims:
|
||||
evidence.append(
|
||||
RiskEvidence(
|
||||
code="duplicate_invoice_graph",
|
||||
title="Duplicate invoice graph",
|
||||
detail="Same invoice appears in multiple claims.",
|
||||
source="graph",
|
||||
score=95,
|
||||
related_entity_keys=[f"claim:{item.claim_id}" for item in duplicate_claims],
|
||||
)
|
||||
)
|
||||
signals.extend(normalize_risk_signals(["duplicate_invoice"], source="graph"))
|
||||
|
||||
split_claims = _split_billing_claims(claim, context.claims, context.near_threshold_amount)
|
||||
if len(split_claims) >= 3:
|
||||
evidence.append(
|
||||
RiskEvidence(
|
||||
code="split_billing_graph",
|
||||
title="Split billing graph",
|
||||
detail="Same employee submitted several near-threshold claims in 7 days.",
|
||||
source="graph",
|
||||
score=78,
|
||||
related_entity_keys=[f"claim:{item.claim_id}" for item in split_claims],
|
||||
)
|
||||
)
|
||||
signals.extend(normalize_risk_signals(["split_billing"], source="graph"))
|
||||
|
||||
frequency_claims = _employee_frequency_claims(claim, context.claims)
|
||||
if len(frequency_claims) >= 4:
|
||||
score = min(88, 52 + len(frequency_claims) * 6)
|
||||
evidence.append(
|
||||
RiskEvidence(
|
||||
code="frequency_graph",
|
||||
title="Frequency graph",
|
||||
detail="Same employee has dense claims under the same expense type.",
|
||||
source="graph",
|
||||
score=score,
|
||||
related_entity_keys=[f"claim:{item.claim_id}" for item in frequency_claims],
|
||||
)
|
||||
)
|
||||
signals.extend(normalize_risk_signals(["frequency_anomaly"], source="graph"))
|
||||
|
||||
consistency_evidence, consistency_signals = evaluate_claim_consistency(claim)
|
||||
evidence.extend(consistency_evidence)
|
||||
signals.extend(consistency_signals)
|
||||
|
||||
cluster_claims = _cross_department_cluster_claims(claim, context.claims)
|
||||
if len(cluster_claims) >= 3:
|
||||
evidence.append(
|
||||
RiskEvidence(
|
||||
code="cross_department_cluster",
|
||||
title="Cross-department cluster",
|
||||
detail="Multiple departments produced similar high-value claims together.",
|
||||
source="graph",
|
||||
score=74,
|
||||
related_entity_keys=[f"claim:{item.claim_id}" for item in cluster_claims],
|
||||
)
|
||||
)
|
||||
signals.extend(normalize_risk_signals(["cross_department_cluster"], source="graph"))
|
||||
|
||||
if not evidence:
|
||||
return 0, [], []
|
||||
score = min(100, max(item.score for item in evidence) + max(0, len(evidence) - 1) * 6)
|
||||
return score, evidence, _dedupe_signals(signals)
|
||||
|
||||
|
||||
def _score_policy_relevance(
|
||||
signals: list[NormalizedRiskSignal],
|
||||
) -> tuple[int, list[RiskEvidence], list[str]]:
|
||||
refs: list[str] = []
|
||||
for signal in signals:
|
||||
for ref in policy_refs_for_signal(signal.code):
|
||||
if ref not in refs:
|
||||
refs.append(ref)
|
||||
if not refs:
|
||||
return 0, [], []
|
||||
score = min(88, 45 + len(refs) * 12)
|
||||
return score, [
|
||||
RiskEvidence(
|
||||
code="policy_relevance",
|
||||
title="Policy relevance",
|
||||
detail="Risk signal is bound to policy or control clause.",
|
||||
source="policy",
|
||||
score=score,
|
||||
metadata={"policy_refs": refs},
|
||||
)
|
||||
], refs
|
||||
|
||||
|
||||
def _score_history(
|
||||
claim: RiskGraphClaimSnapshot,
|
||||
signals: list[NormalizedRiskSignal],
|
||||
history_stats: list[RiskHistoryStats],
|
||||
) -> tuple[int, list[RiskEvidence], RiskHistoryStats | None]:
|
||||
signal_codes = {item.code for item in signals}
|
||||
expense_type = _canonical_key(claim.expense_type)
|
||||
matched = [
|
||||
item
|
||||
for item in history_stats
|
||||
if item.risk_signal in signal_codes
|
||||
and (not item.expense_type or _canonical_key(item.expense_type) == expense_type)
|
||||
]
|
||||
if not matched:
|
||||
return 0, [], None
|
||||
history = max(matched, key=lambda item: item.similar_case_count)
|
||||
total = max(1, history.similar_case_count)
|
||||
confirmed_rate = Decimal(history.confirmed_count) / Decimal(total)
|
||||
returned_rate = Decimal(history.returned_count) / Decimal(total)
|
||||
false_positive_rate = Decimal(history.false_positive_count) / Decimal(total)
|
||||
score = _clamp_score(
|
||||
HUNDRED * (confirmed_rate * Decimal("0.65") + returned_rate * Decimal("0.35"))
|
||||
- HUNDRED * false_positive_rate * Decimal("0.50")
|
||||
)
|
||||
if score <= 0:
|
||||
return 0, [], history
|
||||
return score, [
|
||||
RiskEvidence(
|
||||
code="history_feedback",
|
||||
title="History feedback",
|
||||
detail="Similar historical cases contain confirmed or returned risks.",
|
||||
source="feedback",
|
||||
score=score,
|
||||
metadata=history.as_dict(),
|
||||
)
|
||||
], history
|
||||
|
||||
|
||||
def _resolve_peer_baseline(
|
||||
target: RiskGraphClaimSnapshot,
|
||||
claims: list[RiskGraphClaimSnapshot],
|
||||
min_sample_size: int,
|
||||
) -> PeerBaseline:
|
||||
candidates = [claim for claim in claims if claim.claim_id != target.claim_id]
|
||||
scopes = [
|
||||
(
|
||||
"department_grade_expense_type",
|
||||
[
|
||||
claim
|
||||
for claim in candidates
|
||||
if _same(claim.department_name, target.department_name)
|
||||
and _same(claim.employee_grade, target.employee_grade)
|
||||
and _same(claim.expense_type, target.expense_type)
|
||||
],
|
||||
),
|
||||
(
|
||||
"department_expense_type",
|
||||
[
|
||||
claim
|
||||
for claim in candidates
|
||||
if _same(claim.department_name, target.department_name)
|
||||
and _same(claim.expense_type, target.expense_type)
|
||||
],
|
||||
),
|
||||
(
|
||||
"expense_type",
|
||||
[claim for claim in candidates if _same(claim.expense_type, target.expense_type)],
|
||||
),
|
||||
("all_claims", candidates),
|
||||
]
|
||||
for scope, scoped_claims in scopes:
|
||||
amounts = [
|
||||
_to_decimal(claim.amount)
|
||||
for claim in scoped_claims
|
||||
if _to_decimal(claim.amount) > ZERO
|
||||
]
|
||||
if len(amounts) >= min_sample_size:
|
||||
return _build_baseline(scope, amounts)
|
||||
return PeerBaseline(
|
||||
scope="insufficient_sample",
|
||||
sample_size=0,
|
||||
fallback_reason="Peer sample is below minimum threshold.",
|
||||
)
|
||||
|
||||
|
||||
def _build_baseline(scope: str, amounts: list[Decimal]) -> PeerBaseline:
|
||||
return PeerBaseline(
|
||||
scope=scope,
|
||||
sample_size=len(amounts),
|
||||
median_amount=_percentile(amounts, 50),
|
||||
p75_amount=_percentile(amounts, 75),
|
||||
p90_amount=_percentile(amounts, 90),
|
||||
mean_amount=sum(amounts, ZERO) / Decimal(len(amounts)),
|
||||
)
|
||||
|
||||
|
||||
def _weighted_risk_score(scores: dict[str, int]) -> int:
|
||||
weighted = (
|
||||
Decimal(scores["S_rule"]) * Decimal("0.35")
|
||||
+ Decimal(scores["S_anomaly"]) * Decimal("0.25")
|
||||
+ Decimal(scores["S_graph"]) * Decimal("0.20")
|
||||
+ Decimal(scores["S_policy"]) * Decimal("0.15")
|
||||
+ Decimal(scores["S_history"]) * Decimal("0.05")
|
||||
)
|
||||
return _clamp_score(weighted)
|
||||
|
||||
|
||||
def _evidence_source_count(evidence: list[RiskEvidence]) -> int:
|
||||
return len(
|
||||
{
|
||||
str(item.source or "").strip()
|
||||
for item in evidence
|
||||
if str(item.source or "").strip()
|
||||
}
|
||||
)
|
||||
|
||||
|
||||
def _apply_evidence_source_gate(
|
||||
risk_score: int,
|
||||
evidence: list[RiskEvidence],
|
||||
) -> tuple[int, str]:
|
||||
if risk_score >= 70 and _evidence_source_count(evidence) < 2:
|
||||
return 69, "capped_high_risk_single_source"
|
||||
return risk_score, "passed"
|
||||
|
||||
|
||||
def _select_primary_signal(
|
||||
signals: list[NormalizedRiskSignal],
|
||||
*,
|
||||
fallback_score: int,
|
||||
) -> NormalizedRiskSignal:
|
||||
deduped = _dedupe_signals(signals)
|
||||
if deduped:
|
||||
return max(deduped, key=lambda item: (item.score, item.confidence, item.code))
|
||||
fallback = normalize_risk_signals(
|
||||
[{"risk_signal": "amount_limit_exceeded", "score": fallback_score}],
|
||||
source="algorithm",
|
||||
)
|
||||
return fallback[0]
|
||||
|
||||
|
||||
def _calculate_confidence(
|
||||
*,
|
||||
evidence: list[RiskEvidence],
|
||||
baseline: PeerBaseline,
|
||||
ontology_confidence: Decimal,
|
||||
history: RiskHistoryStats | None,
|
||||
data_quality_ok: bool,
|
||||
) -> Decimal:
|
||||
source_count = len({item.source for item in evidence})
|
||||
confidence = Decimal("0.42") + min(Decimal("0.30"), Decimal(source_count) * Decimal("0.10"))
|
||||
confidence += min(Decimal("0.16"), Decimal(baseline.sample_size) / Decimal("50"))
|
||||
confidence += ontology_confidence * Decimal("0.08")
|
||||
if history and history.similar_case_count:
|
||||
false_positive_rate = Decimal(history.false_positive_count) / Decimal(
|
||||
history.similar_case_count
|
||||
)
|
||||
confidence -= min(Decimal("0.18"), false_positive_rate * Decimal("0.30"))
|
||||
if not data_quality_ok:
|
||||
confidence -= Decimal("0.20")
|
||||
return max(Decimal("0.05"), min(Decimal("0.98"), confidence.quantize(Decimal("0.0001"))))
|
||||
|
||||
|
||||
def _resolve_automation_mode(
|
||||
*,
|
||||
risk_score: int,
|
||||
confidence: Decimal,
|
||||
evidence_count: int,
|
||||
history: RiskHistoryStats | None,
|
||||
) -> str:
|
||||
false_positive_rate = Decimal("0")
|
||||
if history and history.similar_case_count:
|
||||
false_positive_rate = Decimal(history.false_positive_count) / Decimal(
|
||||
history.similar_case_count
|
||||
)
|
||||
if (
|
||||
risk_score >= 90
|
||||
and confidence >= Decimal("0.90")
|
||||
and evidence_count >= 3
|
||||
and false_positive_rate <= Decimal("0.10")
|
||||
):
|
||||
return AUTOMATION_AUTO_HOLD
|
||||
if risk_score >= 75 and confidence >= Decimal("0.72") and evidence_count >= 2:
|
||||
return AUTOMATION_SEMI_AUTO_REVIEW
|
||||
if risk_score >= 40:
|
||||
return AUTOMATION_MANUAL_REVIEW
|
||||
return AUTOMATION_ASSIST
|
||||
|
||||
|
||||
def _duplicate_invoice_claims(
|
||||
target: RiskGraphClaimSnapshot,
|
||||
claims: list[RiskGraphClaimSnapshot],
|
||||
) -> list[RiskGraphClaimSnapshot]:
|
||||
invoice_ids = {item.invoice_id for item in target.items if item.invoice_id}
|
||||
if not invoice_ids:
|
||||
return []
|
||||
matched = []
|
||||
for claim in claims:
|
||||
if claim.claim_id == target.claim_id:
|
||||
continue
|
||||
if any(item.invoice_id in invoice_ids for item in claim.items if item.invoice_id):
|
||||
matched.append(claim)
|
||||
return matched
|
||||
|
||||
|
||||
def _split_billing_claims(
|
||||
target: RiskGraphClaimSnapshot,
|
||||
claims: list[RiskGraphClaimSnapshot],
|
||||
near_threshold_amount: Decimal,
|
||||
) -> list[RiskGraphClaimSnapshot]:
|
||||
if target.occurred_at is None:
|
||||
return []
|
||||
matched = [
|
||||
claim
|
||||
for claim in claims
|
||||
if _same_employee(claim, target)
|
||||
and _same(claim.expense_type, target.expense_type)
|
||||
and _same(claim.location, target.location)
|
||||
and claim.occurred_at is not None
|
||||
and abs((claim.occurred_at.date() - target.occurred_at.date()).days) <= 7
|
||||
and _to_decimal(claim.amount) <= near_threshold_amount
|
||||
and _to_decimal(claim.amount) >= near_threshold_amount * Decimal("0.55")
|
||||
]
|
||||
return matched
|
||||
|
||||
|
||||
def _employee_frequency_claims(
|
||||
target: RiskGraphClaimSnapshot,
|
||||
claims: list[RiskGraphClaimSnapshot],
|
||||
) -> list[RiskGraphClaimSnapshot]:
|
||||
if target.occurred_at is None:
|
||||
return []
|
||||
return [
|
||||
claim
|
||||
for claim in claims
|
||||
if _same_employee(claim, target)
|
||||
and _same(claim.expense_type, target.expense_type)
|
||||
and claim.occurred_at is not None
|
||||
and abs((claim.occurred_at.date() - target.occurred_at.date()).days) <= 30
|
||||
]
|
||||
|
||||
|
||||
def _cross_department_cluster_claims(
|
||||
target: RiskGraphClaimSnapshot,
|
||||
claims: list[RiskGraphClaimSnapshot],
|
||||
) -> list[RiskGraphClaimSnapshot]:
|
||||
if target.occurred_at is None or not target.location:
|
||||
return []
|
||||
matched = [
|
||||
claim
|
||||
for claim in claims
|
||||
if claim.occurred_at is not None
|
||||
and claim.occurred_at.date() == target.occurred_at.date()
|
||||
and _same(claim.location, target.location)
|
||||
and _same(claim.expense_type, target.expense_type)
|
||||
and _to_decimal(claim.amount) >= _to_decimal(target.amount) * Decimal("0.65")
|
||||
]
|
||||
departments = {
|
||||
_canonical_key(claim.department_name)
|
||||
for claim in matched
|
||||
if claim.department_name
|
||||
}
|
||||
return matched if len(departments) >= 2 else []
|
||||
|
||||
|
||||
def _similar_case_ids(
|
||||
target: RiskGraphClaimSnapshot,
|
||||
claims: list[RiskGraphClaimSnapshot],
|
||||
) -> list[str]:
|
||||
return [
|
||||
claim.claim_id
|
||||
for claim in _employee_frequency_claims(target, claims)
|
||||
if claim.claim_id != target.claim_id
|
||||
][:8]
|
||||
|
||||
|
||||
def _claim_related_node_keys(
|
||||
claim: RiskGraphClaimSnapshot,
|
||||
nodes: list[RiskGraphNode],
|
||||
) -> list[str]:
|
||||
claim_key = claim_node_key(claim)
|
||||
employee_key = employee_node_key(claim)
|
||||
related = {claim_key}
|
||||
if employee_key:
|
||||
related.add(employee_key)
|
||||
for node in nodes:
|
||||
if str(node.key).startswith(("expense_type:", "department:", "location:")):
|
||||
if str(node.label or "").strip() in {
|
||||
claim.expense_type,
|
||||
claim.department_name,
|
||||
claim.location,
|
||||
}:
|
||||
related.add(node.key)
|
||||
return sorted(related)
|
||||
|
||||
|
||||
def _claim_related_edge_keys(
|
||||
claim: RiskGraphClaimSnapshot,
|
||||
edges: list[RiskGraphEdge],
|
||||
) -> list[dict[str, str]]:
|
||||
claim_key = claim_node_key(claim)
|
||||
return [
|
||||
{
|
||||
"source_key": edge.source_key,
|
||||
"target_key": edge.target_key,
|
||||
"edge_type": edge.edge_type,
|
||||
}
|
||||
for edge in edges
|
||||
if edge.source_key == claim_key or edge.target_key == claim_key
|
||||
]
|
||||
|
||||
|
||||
def _build_description(
|
||||
claim: RiskGraphClaimSnapshot,
|
||||
signal: NormalizedRiskSignal,
|
||||
risk_score: int,
|
||||
evidence: list[RiskEvidence],
|
||||
) -> str:
|
||||
top_evidence = max(evidence, key=lambda item: item.score, default=None)
|
||||
if top_evidence is None:
|
||||
return (
|
||||
f"{claim.claim_no or claim.claim_id} produced "
|
||||
f"{signal.label} with score {risk_score}."
|
||||
)
|
||||
return (
|
||||
f"{claim.claim_no or claim.claim_id} produced {signal.label} "
|
||||
f"with score {risk_score}. Main evidence: {top_evidence.detail}"
|
||||
)
|
||||
|
||||
|
||||
def _level_from_score(score: int) -> str:
|
||||
if score >= 90:
|
||||
return LEVEL_CRITICAL
|
||||
if score >= 70:
|
||||
return LEVEL_HIGH
|
||||
if score >= 45:
|
||||
return LEVEL_MEDIUM
|
||||
return LEVEL_LOW
|
||||
|
||||
|
||||
def _score_ratio(value: Decimal, bands: list[tuple[Decimal, int]]) -> int:
|
||||
if not bands:
|
||||
return 0
|
||||
points = sorted(bands, key=lambda item: item[0])
|
||||
if value <= points[0][0]:
|
||||
return points[0][1]
|
||||
for index in range(1, len(points)):
|
||||
left_value, left_score = points[index - 1]
|
||||
right_value, right_score = points[index]
|
||||
if value > right_value:
|
||||
continue
|
||||
ratio = (value - left_value) / (right_value - left_value)
|
||||
return _clamp_score(Decimal(left_score) + ratio * Decimal(right_score - left_score))
|
||||
return points[-1][1]
|
||||
|
||||
|
||||
def _percentile(values: list[Decimal], percent: int) -> Decimal:
|
||||
normalized = sorted(value for value in values if value >= ZERO)
|
||||
if not normalized:
|
||||
return ZERO
|
||||
if len(normalized) == 1:
|
||||
return normalized[0]
|
||||
position = Decimal(len(normalized) - 1) * Decimal(percent) / HUNDRED
|
||||
lower = int(position.to_integral_value(rounding=ROUND_FLOOR))
|
||||
upper = int(position.to_integral_value(rounding=ROUND_CEILING))
|
||||
if lower == upper:
|
||||
return normalized[lower]
|
||||
fraction = position - Decimal(lower)
|
||||
return normalized[lower] + (normalized[upper] - normalized[lower]) * fraction
|
||||
|
||||
|
||||
def _safe_ratio(numerator: Any, denominator: Any) -> Decimal:
|
||||
denominator_value = _to_decimal(denominator)
|
||||
if denominator_value <= ZERO:
|
||||
return ZERO
|
||||
return (_to_decimal(numerator) / denominator_value).quantize(Decimal("0.0001"))
|
||||
|
||||
|
||||
def _to_decimal(value: Any) -> Decimal:
|
||||
try:
|
||||
return Decimal(str(value or "0"))
|
||||
except Exception:
|
||||
return ZERO
|
||||
|
||||
|
||||
def _clamp_score(value: Any) -> int:
|
||||
try:
|
||||
numeric = Decimal(str(value))
|
||||
except Exception:
|
||||
numeric = ZERO
|
||||
return max(0, min(100, int(numeric.quantize(ONE, rounding=ROUND_HALF_UP))))
|
||||
|
||||
|
||||
def _same(left: Any, right: Any) -> bool:
|
||||
return _canonical_key(left) == _canonical_key(right)
|
||||
|
||||
|
||||
def _same_employee(left: RiskGraphClaimSnapshot, right: RiskGraphClaimSnapshot) -> bool:
|
||||
left_key = left.employee_id or left.employee_name
|
||||
right_key = right.employee_id or right.employee_name
|
||||
return bool(left_key and _same(left_key, right_key))
|
||||
|
||||
|
||||
def _canonical_key(value: Any) -> str:
|
||||
return "_".join(str(value or "").strip().lower().split())
|
||||
|
||||
|
||||
def _dedupe_signals(signals: list[NormalizedRiskSignal]) -> list[NormalizedRiskSignal]:
|
||||
by_code: dict[str, NormalizedRiskSignal] = {}
|
||||
for signal in signals:
|
||||
current = by_code.get(signal.code)
|
||||
if current is None or signal.score > current.score:
|
||||
by_code[signal.code] = signal
|
||||
return list(by_code.values())
|
||||
|
||||
|
||||
def _merge_nodes(
|
||||
first: list[RiskGraphNode],
|
||||
second: list[RiskGraphNode],
|
||||
) -> list[RiskGraphNode]:
|
||||
by_key = {node.key: node for node in first}
|
||||
for node in second:
|
||||
by_key.setdefault(node.key, node)
|
||||
return list(by_key.values())
|
||||
|
||||
|
||||
def _merge_edges(
|
||||
first: list[RiskGraphEdge],
|
||||
second: list[RiskGraphEdge],
|
||||
) -> list[RiskGraphEdge]:
|
||||
by_key = {edge.edge_key(): edge for edge in first}
|
||||
for edge in second:
|
||||
by_key.setdefault(edge.edge_key(), edge)
|
||||
return list(by_key.values())
|
||||
113
server/src/app/algorithem/risk_graph/entity_resolution.py
Normal file
113
server/src/app/algorithem/risk_graph/entity_resolution.py
Normal file
@@ -0,0 +1,113 @@
|
||||
"""Canonical entity resolution for financial risk graph subjects."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import hashlib
|
||||
import re
|
||||
from dataclasses import dataclass, field
|
||||
from datetime import UTC, datetime
|
||||
from typing import Any
|
||||
|
||||
|
||||
ENTITY_TYPE_ALIASES = {
|
||||
"supplier": "vendor",
|
||||
"merchant": "vendor",
|
||||
"hotel": "vendor",
|
||||
"bank_account_name": "bank_account",
|
||||
"employee_name": "employee",
|
||||
}
|
||||
|
||||
|
||||
@dataclass(slots=True)
|
||||
class CanonicalEntity:
|
||||
canonical_id: str
|
||||
entity_type: str
|
||||
canonical_key: str
|
||||
label: str
|
||||
aliases: list[str] = field(default_factory=list)
|
||||
source: str = ""
|
||||
confirmed_by: str = ""
|
||||
confirmed_at: str = ""
|
||||
metadata: dict[str, Any] = field(default_factory=dict)
|
||||
|
||||
def as_dict(self) -> dict[str, Any]:
|
||||
return {
|
||||
"canonical_id": self.canonical_id,
|
||||
"entity_type": self.entity_type,
|
||||
"canonical_key": self.canonical_key,
|
||||
"label": self.label,
|
||||
"aliases": list(self.aliases),
|
||||
"source": self.source,
|
||||
"confirmed_by": self.confirmed_by,
|
||||
"confirmed_at": self.confirmed_at,
|
||||
"metadata": dict(self.metadata),
|
||||
}
|
||||
|
||||
|
||||
class FinancialEntityResolver:
|
||||
def resolve(
|
||||
self,
|
||||
entity_type: str,
|
||||
value: str,
|
||||
*,
|
||||
source: str = "",
|
||||
metadata: dict[str, Any] | None = None,
|
||||
) -> CanonicalEntity | None:
|
||||
canonical_type = ENTITY_TYPE_ALIASES.get(_canonical_token(entity_type), _canonical_token(entity_type))
|
||||
canonical_key = _canonical_value(value)
|
||||
if not canonical_type or not canonical_key:
|
||||
return None
|
||||
canonical_id = _canonical_id(canonical_type, canonical_key)
|
||||
return CanonicalEntity(
|
||||
canonical_id=canonical_id,
|
||||
entity_type=canonical_type,
|
||||
canonical_key=canonical_key,
|
||||
label=str(value or "").strip(),
|
||||
aliases=[str(value or "").strip()],
|
||||
source=source,
|
||||
metadata=metadata or {},
|
||||
)
|
||||
|
||||
|
||||
class CanonicalEntityRegistry:
|
||||
def __init__(self) -> None:
|
||||
self._entities: dict[str, CanonicalEntity] = {}
|
||||
|
||||
def upsert(self, entity: CanonicalEntity) -> CanonicalEntity:
|
||||
current = self._entities.get(entity.canonical_id)
|
||||
if current is None:
|
||||
self._entities[entity.canonical_id] = entity
|
||||
return entity
|
||||
aliases = list(dict.fromkeys([*current.aliases, *entity.aliases]))
|
||||
current.aliases = aliases
|
||||
current.metadata.update(entity.metadata)
|
||||
return current
|
||||
|
||||
def confirm(self, canonical_id: str, *, actor: str) -> CanonicalEntity | None:
|
||||
entity = self._entities.get(canonical_id)
|
||||
if entity is None:
|
||||
return None
|
||||
entity.confirmed_by = str(actor or "").strip()
|
||||
entity.confirmed_at = datetime.now(UTC).isoformat()
|
||||
return entity
|
||||
|
||||
def get(self, canonical_id: str) -> CanonicalEntity | None:
|
||||
return self._entities.get(canonical_id)
|
||||
|
||||
def all(self) -> list[CanonicalEntity]:
|
||||
return list(self._entities.values())
|
||||
|
||||
|
||||
def _canonical_id(entity_type: str, canonical_key: str) -> str:
|
||||
digest = hashlib.sha1(f"{entity_type}:{canonical_key}".encode("utf-8")).hexdigest()[:12]
|
||||
return f"{entity_type}:{digest}"
|
||||
|
||||
|
||||
def _canonical_token(value: str) -> str:
|
||||
return "_".join(str(value or "").strip().lower().split())
|
||||
|
||||
|
||||
def _canonical_value(value: str) -> str:
|
||||
normalized = str(value or "").strip().lower()
|
||||
normalized = re.sub(r"[\s\-_/,，.。()（）【】\[\]]+", "", normalized)
|
||||
return normalized
|
||||
71
server/src/app/algorithem/risk_graph/evaluation_cases.py
Normal file
71
server/src/app/algorithem/risk_graph/evaluation_cases.py
Normal file
@@ -0,0 +1,71 @@
|
||||
"""Replayable evaluation cases for the financial risk graph algorithm."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from dataclasses import dataclass, field
|
||||
from typing import Any
|
||||
|
||||
|
||||
@dataclass(frozen=True, slots=True)
|
||||
class RiskEvaluationCase:
|
||||
case_id: str
|
||||
category: str
|
||||
expected_signal: str
|
||||
expected_level: str
|
||||
description: str
|
||||
payload: dict[str, Any] = field(default_factory=dict)
|
||||
|
||||
def as_dict(self) -> dict[str, Any]:
|
||||
return {
|
||||
"case_id": self.case_id,
|
||||
"category": self.category,
|
||||
"expected_signal": self.expected_signal,
|
||||
"expected_level": self.expected_level,
|
||||
"description": self.description,
|
||||
"payload": dict(self.payload),
|
||||
}
|
||||
|
||||
|
||||
def default_risk_evaluation_cases() -> list[RiskEvaluationCase]:
|
||||
return [
|
||||
RiskEvaluationCase(
|
||||
case_id="positive_duplicate_invoice_high",
|
||||
category="positive",
|
||||
expected_signal="duplicate_invoice",
|
||||
expected_level="high",
|
||||
description="重复发票叠加高金额偏离，应输出高风险观察。",
|
||||
payload={"risk_flags": ["duplicate_invoice"], "invoice_reuse": True},
|
||||
),
|
||||
RiskEvaluationCase(
|
||||
case_id="negative_clean_low_amount",
|
||||
category="negative",
|
||||
expected_signal="none",
|
||||
expected_level="none",
|
||||
description="低金额、无规则命中、无图谱异常，不应输出风险观察。",
|
||||
payload={"amount": 300, "risk_flags": []},
|
||||
),
|
||||
RiskEvaluationCase(
|
||||
case_id="counterfactual_invoice_corrected",
|
||||
category="counterfactual",
|
||||
expected_signal="none",
|
||||
expected_level="none",
|
||||
description="重复票据被替换为唯一票据后，风险应消失或降级。",
|
||||
payload={"remove_duplicate_invoice": True},
|
||||
),
|
||||
RiskEvaluationCase(
|
||||
case_id="noise_missing_employee",
|
||||
category="noise",
|
||||
expected_signal="preapproval_absent",
|
||||
expected_level="medium",
|
||||
description="缺失员工信息时允许候选观察，但不能输出强风控结论。",
|
||||
payload={"missing_fields": ["employee"], "score_cap": 69},
|
||||
),
|
||||
RiskEvaluationCase(
|
||||
case_id="historical_false_positive_calibration",
|
||||
category="historical_false_positive",
|
||||
expected_signal="duplicate_invoice",
|
||||
expected_level="medium",
|
||||
description="历史误报率较高时进入校准抽审，不直接强拦截。",
|
||||
payload={"false_positive_rate": 0.35},
|
||||
),
|
||||
]
|
||||
144
server/src/app/algorithem/risk_graph/features.py
Normal file
144
server/src/app/algorithem/risk_graph/features.py
Normal file
@@ -0,0 +1,144 @@
|
||||
"""Feature extraction for heterogeneous financial risk graphs."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from collections import Counter, defaultdict, deque
|
||||
from dataclasses import dataclass, field
|
||||
from typing import Any
|
||||
|
||||
from .models import RiskGraphEdge, RiskGraphNode
|
||||
|
||||
|
||||
@dataclass(slots=True)
|
||||
class RiskGraphFeatureSet:
|
||||
node_type_counts: dict[str, int] = field(default_factory=dict)
|
||||
edge_type_counts: dict[str, int] = field(default_factory=dict)
|
||||
meta_path_counts: dict[str, int] = field(default_factory=dict)
|
||||
degree_centrality: dict[str, float] = field(default_factory=dict)
|
||||
clusters: list[dict[str, Any]] = field(default_factory=list)
|
||||
neighbor_risk_density: dict[str, float] = field(default_factory=dict)
|
||||
|
||||
def as_dict(self) -> dict[str, Any]:
|
||||
return {
|
||||
"node_type_counts": dict(self.node_type_counts),
|
||||
"edge_type_counts": dict(self.edge_type_counts),
|
||||
"meta_path_counts": dict(self.meta_path_counts),
|
||||
"degree_centrality": dict(self.degree_centrality),
|
||||
"clusters": list(self.clusters),
|
||||
"neighbor_risk_density": dict(self.neighbor_risk_density),
|
||||
}
|
||||
|
||||
|
||||
class HeterogeneousRiskGraphFeatureBuilder:
|
||||
def build(
|
||||
self,
|
||||
nodes: list[RiskGraphNode],
|
||||
edges: list[RiskGraphEdge],
|
||||
*,
|
||||
risk_node_keys: set[str] | None = None,
|
||||
) -> RiskGraphFeatureSet:
|
||||
node_by_key = {node.key: node for node in nodes}
|
||||
adjacency = _build_adjacency(edges)
|
||||
risk_keys = set(risk_node_keys or set())
|
||||
return RiskGraphFeatureSet(
|
||||
node_type_counts=dict(Counter(node.node_type for node in nodes)),
|
||||
edge_type_counts=dict(Counter(edge.edge_type for edge in edges)),
|
||||
meta_path_counts=_meta_path_counts(node_by_key, adjacency),
|
||||
degree_centrality=_degree_centrality(node_by_key, adjacency),
|
||||
clusters=_clusters(node_by_key, adjacency),
|
||||
neighbor_risk_density=_neighbor_risk_density(node_by_key, adjacency, risk_keys),
|
||||
)
|
||||
|
||||
|
||||
def _build_adjacency(edges: list[RiskGraphEdge]) -> dict[str, list[tuple[str, str]]]:
|
||||
adjacency: dict[str, list[tuple[str, str]]] = defaultdict(list)
|
||||
for edge in edges:
|
||||
adjacency[edge.source_key].append((edge.target_key, edge.edge_type))
|
||||
adjacency[edge.target_key].append((edge.source_key, edge.edge_type))
|
||||
return adjacency
|
||||
|
||||
|
||||
def _meta_path_counts(
|
||||
node_by_key: dict[str, RiskGraphNode],
|
||||
adjacency: dict[str, list[tuple[str, str]]],
|
||||
) -> dict[str, int]:
|
||||
counts: Counter[str] = Counter()
|
||||
for source_key, first_hops in adjacency.items():
|
||||
source = node_by_key.get(source_key)
|
||||
if source is None:
|
||||
continue
|
||||
for middle_key, first_edge_type in first_hops:
|
||||
middle = node_by_key.get(middle_key)
|
||||
if middle is None:
|
||||
continue
|
||||
for target_key, second_edge_type in adjacency.get(middle_key, []):
|
||||
if target_key == source_key:
|
||||
continue
|
||||
target = node_by_key.get(target_key)
|
||||
if target is None:
|
||||
continue
|
||||
key = (
|
||||
f"{source.node_type}->{first_edge_type}->{middle.node_type}"
|
||||
f"->{second_edge_type}->{target.node_type}"
|
||||
)
|
||||
counts[key] += 1
|
||||
return dict(counts)
|
||||
|
||||
|
||||
def _degree_centrality(
|
||||
node_by_key: dict[str, RiskGraphNode],
|
||||
adjacency: dict[str, list[tuple[str, str]]],
|
||||
) -> dict[str, float]:
|
||||
denominator = max(1, len(node_by_key) - 1)
|
||||
return {
|
||||
node_key: round(len(adjacency.get(node_key, [])) / denominator, 4)
|
||||
for node_key in node_by_key
|
||||
}
|
||||
|
||||
|
||||
def _clusters(
|
||||
node_by_key: dict[str, RiskGraphNode],
|
||||
adjacency: dict[str, list[tuple[str, str]]],
|
||||
) -> list[dict[str, Any]]:
|
||||
visited: set[str] = set()
|
||||
clusters: list[dict[str, Any]] = []
|
||||
for start_key in node_by_key:
|
||||
if start_key in visited:
|
||||
continue
|
||||
queue: deque[str] = deque([start_key])
|
||||
visited.add(start_key)
|
||||
members: list[str] = []
|
||||
type_counts: Counter[str] = Counter()
|
||||
while queue:
|
||||
node_key = queue.popleft()
|
||||
members.append(node_key)
|
||||
type_counts[node_by_key[node_key].node_type] += 1
|
||||
for next_key, _ in adjacency.get(node_key, []):
|
||||
if next_key in visited or next_key not in node_by_key:
|
||||
continue
|
||||
visited.add(next_key)
|
||||
queue.append(next_key)
|
||||
clusters.append(
|
||||
{
|
||||
"size": len(members),
|
||||
"node_keys": sorted(members),
|
||||
"node_type_counts": dict(type_counts),
|
||||
}
|
||||
)
|
||||
return sorted(clusters, key=lambda item: item["size"], reverse=True)
|
||||
|
||||
|
||||
def _neighbor_risk_density(
|
||||
node_by_key: dict[str, RiskGraphNode],
|
||||
adjacency: dict[str, list[tuple[str, str]]],
|
||||
risk_keys: set[str],
|
||||
) -> dict[str, float]:
|
||||
density: dict[str, float] = {}
|
||||
for node_key in node_by_key:
|
||||
neighbors = [target for target, _ in adjacency.get(node_key, [])]
|
||||
if not neighbors:
|
||||
density[node_key] = 0.0
|
||||
continue
|
||||
risk_neighbor_count = sum(1 for target in neighbors if target in risk_keys)
|
||||
density[node_key] = round(risk_neighbor_count / len(neighbors), 4)
|
||||
return density
|
||||
307
server/src/app/algorithem/risk_graph/graph.py
Normal file
307
server/src/app/algorithem/risk_graph/graph.py
Normal file
@@ -0,0 +1,307 @@
|
||||
"""Graph construction helpers for expense risk analysis."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from decimal import Decimal
|
||||
|
||||
from .models import RiskGraphClaimSnapshot, RiskGraphEdge, RiskGraphNode
|
||||
|
||||
ALLOWED_EDGE_TYPES = {
|
||||
"department_has_employee",
|
||||
"employee_submits_claim",
|
||||
"claim_has_item",
|
||||
"claim_expense_type",
|
||||
"claim_location",
|
||||
"claim_invoice",
|
||||
"claim_has_risk_signal",
|
||||
"claim_similar_to",
|
||||
"claim_duplicate_invoice",
|
||||
"ontology_extracts",
|
||||
"ontology_constrains",
|
||||
"ontology_signals",
|
||||
}
|
||||
|
||||
|
||||
def build_claim_graph(
|
||||
claims: list[RiskGraphClaimSnapshot],
|
||||
) -> tuple[list[RiskGraphNode], list[RiskGraphEdge]]:
|
||||
nodes: dict[str, RiskGraphNode] = {}
|
||||
edges: dict[tuple[str, str, str], RiskGraphEdge] = {}
|
||||
|
||||
for claim in claims:
|
||||
claim_key = claim_node_key(claim)
|
||||
_add_node(
|
||||
nodes,
|
||||
RiskGraphNode(
|
||||
key=claim_key,
|
||||
node_type="claim",
|
||||
label=claim.claim_no or claim.claim_id,
|
||||
canonical_key=claim_key,
|
||||
canonical_id=claim.claim_id or claim.claim_no,
|
||||
metadata={
|
||||
"claim_id": claim.claim_id,
|
||||
"amount": str(_to_decimal(claim.amount)),
|
||||
"expense_type": claim.expense_type,
|
||||
"status": claim.status,
|
||||
},
|
||||
),
|
||||
)
|
||||
|
||||
employee_key = employee_node_key(claim)
|
||||
if employee_key:
|
||||
_add_node(
|
||||
nodes,
|
||||
RiskGraphNode(
|
||||
key=employee_key,
|
||||
node_type="employee",
|
||||
label=claim.employee_name or claim.employee_id or "unknown",
|
||||
canonical_key=employee_key,
|
||||
canonical_id=claim.employee_id or claim.employee_name,
|
||||
metadata={"employee_id": claim.employee_id, "grade": claim.employee_grade},
|
||||
),
|
||||
)
|
||||
_add_edge(
|
||||
edges,
|
||||
RiskGraphEdge(
|
||||
source_key=employee_key,
|
||||
target_key=claim_key,
|
||||
edge_type="employee_submits_claim",
|
||||
metadata={"amount": str(_to_decimal(claim.amount))},
|
||||
),
|
||||
)
|
||||
|
||||
department_key = department_node_key(claim)
|
||||
if department_key:
|
||||
_add_node(
|
||||
nodes,
|
||||
RiskGraphNode(
|
||||
key=department_key,
|
||||
node_type="department",
|
||||
label=claim.department_name or claim.department_id or "unknown",
|
||||
canonical_key=department_key,
|
||||
canonical_id=claim.department_id or claim.department_name,
|
||||
metadata={"department_id": claim.department_id},
|
||||
),
|
||||
)
|
||||
if employee_key:
|
||||
_add_edge(
|
||||
edges,
|
||||
RiskGraphEdge(
|
||||
source_key=department_key,
|
||||
target_key=employee_key,
|
||||
edge_type="department_has_employee",
|
||||
),
|
||||
)
|
||||
|
||||
expense_key = expense_type_node_key(claim.expense_type)
|
||||
if expense_key:
|
||||
_add_node(
|
||||
nodes,
|
||||
RiskGraphNode(
|
||||
key=expense_key,
|
||||
node_type="expense_type",
|
||||
label=claim.expense_type,
|
||||
canonical_key=expense_key,
|
||||
canonical_id=claim.expense_type,
|
||||
),
|
||||
)
|
||||
_add_edge(
|
||||
edges,
|
||||
RiskGraphEdge(
|
||||
source_key=claim_key,
|
||||
target_key=expense_key,
|
||||
edge_type="claim_expense_type",
|
||||
),
|
||||
)
|
||||
|
||||
location_key = location_node_key(claim.location)
|
||||
if location_key:
|
||||
_add_node(
|
||||
nodes,
|
||||
RiskGraphNode(
|
||||
key=location_key,
|
||||
node_type="location",
|
||||
label=claim.location,
|
||||
canonical_key=location_key,
|
||||
canonical_id=claim.location,
|
||||
),
|
||||
)
|
||||
_add_edge(
|
||||
edges,
|
||||
RiskGraphEdge(
|
||||
source_key=claim_key,
|
||||
target_key=location_key,
|
||||
edge_type="claim_location",
|
||||
),
|
||||
)
|
||||
|
||||
for item in claim.items:
|
||||
item_key = f"claim_item:{item.item_id}" if item.item_id else ""
|
||||
if item_key:
|
||||
_add_node(
|
||||
nodes,
|
||||
RiskGraphNode(
|
||||
key=item_key,
|
||||
node_type="claim_item",
|
||||
label=item.item_type or item.item_id,
|
||||
canonical_key=item_key,
|
||||
canonical_id=item.item_id,
|
||||
metadata={
|
||||
"amount": str(_to_decimal(item.item_amount)),
|
||||
"location": item.item_location,
|
||||
"invoice_id": item.invoice_id,
|
||||
},
|
||||
),
|
||||
)
|
||||
_add_edge(
|
||||
edges,
|
||||
RiskGraphEdge(
|
||||
source_key=claim_key,
|
||||
target_key=item_key,
|
||||
edge_type="claim_has_item",
|
||||
),
|
||||
)
|
||||
if item.invoice_id:
|
||||
invoice_key = invoice_node_key(item.invoice_id)
|
||||
_add_node(
|
||||
nodes,
|
||||
RiskGraphNode(
|
||||
key=invoice_key,
|
||||
node_type="invoice",
|
||||
label=item.invoice_id,
|
||||
canonical_key=invoice_key,
|
||||
canonical_id=item.invoice_id,
|
||||
),
|
||||
)
|
||||
_add_edge(
|
||||
edges,
|
||||
RiskGraphEdge(
|
||||
source_key=claim_key,
|
||||
target_key=invoice_key,
|
||||
edge_type="claim_invoice",
|
||||
),
|
||||
)
|
||||
|
||||
_link_duplicate_invoices(claims, edges)
|
||||
_link_similar_claims(claims, edges)
|
||||
return list(nodes.values()), list(edges.values())
|
||||
|
||||
|
||||
def claim_node_key(claim: RiskGraphClaimSnapshot) -> str:
|
||||
return f"claim:{claim.claim_id or claim.claim_no}"
|
||||
|
||||
|
||||
def employee_node_key(claim: RiskGraphClaimSnapshot) -> str:
|
||||
identifier = claim.employee_id or claim.employee_name
|
||||
return f"employee:{_canonical_key(identifier)}" if identifier else ""
|
||||
|
||||
|
||||
def department_node_key(claim: RiskGraphClaimSnapshot) -> str:
|
||||
identifier = claim.department_id or claim.department_name
|
||||
return f"department:{_canonical_key(identifier)}" if identifier else ""
|
||||
|
||||
|
||||
def expense_type_node_key(expense_type: str) -> str:
|
||||
return f"expense_type:{_canonical_key(expense_type)}" if str(expense_type or "").strip() else ""
|
||||
|
||||
|
||||
def location_node_key(location: str) -> str:
|
||||
return f"location:{_canonical_key(location)}" if str(location or "").strip() else ""
|
||||
|
||||
|
||||
def invoice_node_key(invoice_id: str) -> str:
|
||||
return f"invoice:{_canonical_key(invoice_id)}"
|
||||
|
||||
|
||||
def _link_duplicate_invoices(
|
||||
claims: list[RiskGraphClaimSnapshot],
|
||||
edges: dict[tuple[str, str, str], RiskGraphEdge],
|
||||
) -> None:
|
||||
by_invoice: dict[str, list[RiskGraphClaimSnapshot]] = {}
|
||||
for claim in claims:
|
||||
for item in claim.items:
|
||||
if item.invoice_id:
|
||||
by_invoice.setdefault(item.invoice_id, []).append(claim)
|
||||
|
||||
for invoice_id, invoice_claims in by_invoice.items():
|
||||
unique_claims = {claim.claim_id: claim for claim in invoice_claims}
|
||||
if len(unique_claims) < 2:
|
||||
continue
|
||||
claim_list = list(unique_claims.values())
|
||||
for source in claim_list:
|
||||
for target in claim_list:
|
||||
if source.claim_id == target.claim_id:
|
||||
continue
|
||||
_add_edge(
|
||||
edges,
|
||||
RiskGraphEdge(
|
||||
source_key=claim_node_key(source),
|
||||
target_key=claim_node_key(target),
|
||||
edge_type="claim_duplicate_invoice",
|
||||
weight=Decimal("2"),
|
||||
evidence=f"invoice:{invoice_id}",
|
||||
),
|
||||
)
|
||||
|
||||
|
||||
def _link_similar_claims(
|
||||
claims: list[RiskGraphClaimSnapshot],
|
||||
edges: dict[tuple[str, str, str], RiskGraphEdge],
|
||||
) -> None:
|
||||
for index, source in enumerate(claims):
|
||||
for target in claims[index + 1 :]:
|
||||
if not _is_similar_claim(source, target):
|
||||
continue
|
||||
_add_edge(
|
||||
edges,
|
||||
RiskGraphEdge(
|
||||
source_key=claim_node_key(source),
|
||||
target_key=claim_node_key(target),
|
||||
edge_type="claim_similar_to",
|
||||
weight=Decimal("0.7"),
|
||||
metadata={"reason": "same employee and expense type"},
|
||||
),
|
||||
)
|
||||
_add_edge(
|
||||
edges,
|
||||
RiskGraphEdge(
|
||||
source_key=claim_node_key(target),
|
||||
target_key=claim_node_key(source),
|
||||
edge_type="claim_similar_to",
|
||||
weight=Decimal("0.7"),
|
||||
metadata={"reason": "same employee and expense type"},
|
||||
),
|
||||
)
|
||||
|
||||
|
||||
def _is_similar_claim(source: RiskGraphClaimSnapshot, target: RiskGraphClaimSnapshot) -> bool:
|
||||
source_employee = source.employee_id or source.employee_name
|
||||
target_employee = target.employee_id or target.employee_name
|
||||
if not source_employee or _canonical_key(source_employee) != _canonical_key(target_employee):
|
||||
return False
|
||||
if _canonical_key(source.expense_type) != _canonical_key(target.expense_type):
|
||||
return False
|
||||
if source.occurred_at is None or target.occurred_at is None:
|
||||
return True
|
||||
return abs((source.occurred_at.date() - target.occurred_at.date()).days) <= 30
|
||||
|
||||
|
||||
def _add_node(nodes: dict[str, RiskGraphNode], node: RiskGraphNode) -> None:
|
||||
nodes.setdefault(node.key, node)
|
||||
|
||||
|
||||
def _add_edge(edges: dict[tuple[str, str, str], RiskGraphEdge], edge: RiskGraphEdge) -> None:
|
||||
if edge.edge_type not in ALLOWED_EDGE_TYPES:
|
||||
return
|
||||
edges.setdefault(edge.edge_key(), edge)
|
||||
|
||||
|
||||
def _canonical_key(value: str | None) -> str:
|
||||
return "_".join(str(value or "").strip().lower().split())
|
||||
|
||||
|
||||
def _to_decimal(value: object) -> Decimal:
|
||||
try:
|
||||
return Decimal(str(value or "0"))
|
||||
except Exception:
|
||||
return Decimal("0")
|
||||
103
server/src/app/algorithem/risk_graph/lineage.py
Normal file
103
server/src/app/algorithem/risk_graph/lineage.py
Normal file
@@ -0,0 +1,103 @@
|
||||
"""Data lineage contracts for risk graph observations."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from dataclasses import dataclass, field
|
||||
from typing import Any
|
||||
|
||||
|
||||
@dataclass(slots=True)
|
||||
class RiskDataLineage:
|
||||
observation_key: str
|
||||
data_tables: list[str] = field(default_factory=list)
|
||||
document_ids: list[str] = field(default_factory=list)
|
||||
ocr_job_ids: list[str] = field(default_factory=list)
|
||||
agent_run_ids: list[str] = field(default_factory=list)
|
||||
tool_call_ids: list[str] = field(default_factory=list)
|
||||
rule_versions: list[str] = field(default_factory=list)
|
||||
ontology_version: str = ""
|
||||
algorithm_version: str = ""
|
||||
source_event_ids: list[str] = field(default_factory=list)
|
||||
quality_gates: list[str] = field(default_factory=list)
|
||||
|
||||
def as_dict(self) -> dict[str, Any]:
|
||||
return {
|
||||
"observation_key": self.observation_key,
|
||||
"data_tables": list(self.data_tables),
|
||||
"document_ids": list(self.document_ids),
|
||||
"ocr_job_ids": list(self.ocr_job_ids),
|
||||
"agent_run_ids": list(self.agent_run_ids),
|
||||
"tool_call_ids": list(self.tool_call_ids),
|
||||
"rule_versions": list(self.rule_versions),
|
||||
"ontology_version": self.ontology_version,
|
||||
"algorithm_version": self.algorithm_version,
|
||||
"source_event_ids": list(self.source_event_ids),
|
||||
"quality_gates": list(self.quality_gates),
|
||||
}
|
||||
|
||||
|
||||
class RiskDataLineageBuilder:
|
||||
def build_from_observation(
|
||||
self,
|
||||
observation: dict[str, Any],
|
||||
*,
|
||||
source_event_ids: list[str] | None = None,
|
||||
) -> RiskDataLineage:
|
||||
evidence = [item for item in observation.get("evidence", []) if isinstance(item, dict)]
|
||||
ontology_json = observation.get("ontology_json") or {}
|
||||
decision_trace = observation.get("decision_trace") or {}
|
||||
data_tables = ["risk_observations"]
|
||||
if observation.get("claim_id"):
|
||||
data_tables.extend(["expense_claims", "expense_claim_items"])
|
||||
if evidence:
|
||||
data_tables.append("risk_observation_evidence")
|
||||
|
||||
return RiskDataLineage(
|
||||
observation_key=str(observation.get("observation_key") or ""),
|
||||
data_tables=_unique(data_tables),
|
||||
document_ids=_evidence_values(evidence, ["document_id", "doc_id", "file_id"]),
|
||||
ocr_job_ids=_evidence_values(evidence, ["ocr_job_id", "ocr_run_id"]),
|
||||
agent_run_ids=_unique(
|
||||
[
|
||||
str(observation.get("run_id") or "").strip(),
|
||||
str(decision_trace.get("agent_run_id") or "").strip(),
|
||||
]
|
||||
),
|
||||
tool_call_ids=_evidence_values(evidence, ["tool_call_id"]),
|
||||
rule_versions=_unique(
|
||||
[
|
||||
*_evidence_values(evidence, ["rule_version"]),
|
||||
str(decision_trace.get("rule_version") or "").strip(),
|
||||
]
|
||||
),
|
||||
ontology_version=str(ontology_json.get("ontology_version") or "").strip(),
|
||||
algorithm_version=str(observation.get("algorithm_version") or "").strip(),
|
||||
source_event_ids=_unique(source_event_ids or []),
|
||||
quality_gates=_quality_gates(decision_trace),
|
||||
)
|
||||
|
||||
|
||||
def _evidence_values(evidence: list[dict[str, Any]], keys: list[str]) -> list[str]:
|
||||
values: list[str] = []
|
||||
for item in evidence:
|
||||
metadata = item.get("metadata") if isinstance(item.get("metadata"), dict) else {}
|
||||
for key in keys:
|
||||
value = str(item.get(key) or metadata.get(key) or "").strip()
|
||||
if value:
|
||||
values.append(value)
|
||||
return _unique(values)
|
||||
|
||||
|
||||
def _quality_gates(decision_trace: dict[str, Any]) -> list[str]:
|
||||
gates = [
|
||||
str(decision_trace.get("evidence_source_gate") or "").strip(),
|
||||
str(decision_trace.get("data_quality_gate") or "").strip(),
|
||||
]
|
||||
sampling = decision_trace.get("sampling_strategy")
|
||||
if isinstance(sampling, dict):
|
||||
gates.append(str(sampling.get("strategy") or "").strip())
|
||||
return _unique([item for item in gates if item and item != "passed"])
|
||||
|
||||
|
||||
def _unique(values: list[str]) -> list[str]:
|
||||
return list(dict.fromkeys(str(item).strip() for item in values if str(item).strip()))
|
||||
365
server/src/app/algorithem/risk_graph/models.py
Normal file
365
server/src/app/algorithem/risk_graph/models.py
Normal file
@@ -0,0 +1,365 @@
|
||||
"""Data contracts for the financial risk graph algorithm."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from dataclasses import dataclass, field
|
||||
from datetime import date, datetime
|
||||
from decimal import Decimal
|
||||
from typing import Any
|
||||
|
||||
ALGORITHM_VERSION = "financial_risk_graph.v1"
|
||||
|
||||
LEVEL_LOW = "low"
|
||||
LEVEL_MEDIUM = "medium"
|
||||
LEVEL_HIGH = "high"
|
||||
LEVEL_CRITICAL = "critical"
|
||||
|
||||
AUTOMATION_ASSIST = "assist"
|
||||
AUTOMATION_MANUAL_REVIEW = "manual_review"
|
||||
AUTOMATION_SEMI_AUTO_REVIEW = "semi_auto_review"
|
||||
AUTOMATION_AUTO_HOLD = "auto_hold"
|
||||
|
||||
|
||||
@dataclass(slots=True)
|
||||
class RiskGraphClaimItemSnapshot:
|
||||
item_id: str = ""
|
||||
item_type: str = ""
|
||||
item_amount: Any = Decimal("0")
|
||||
item_location: str = ""
|
||||
item_date: date | None = None
|
||||
invoice_id: str | None = None
|
||||
metadata: dict[str, Any] = field(default_factory=dict)
|
||||
|
||||
@classmethod
|
||||
def from_orm(cls, item: Any) -> "RiskGraphClaimItemSnapshot":
|
||||
return cls(
|
||||
item_id=str(getattr(item, "id", "") or ""),
|
||||
item_type=str(getattr(item, "item_type", "") or ""),
|
||||
item_amount=getattr(item, "item_amount", Decimal("0")) or Decimal("0"),
|
||||
item_location=str(getattr(item, "item_location", "") or ""),
|
||||
item_date=getattr(item, "item_date", None),
|
||||
invoice_id=(
|
||||
str(getattr(item, "invoice_id", "") or "").strip()
|
||||
or None
|
||||
),
|
||||
metadata=_metadata_from_object(item),
|
||||
)
|
||||
|
||||
|
||||
@dataclass(slots=True)
|
||||
class RiskGraphClaimSnapshot:
|
||||
claim_id: str
|
||||
claim_no: str = ""
|
||||
employee_id: str | None = None
|
||||
employee_name: str = ""
|
||||
department_id: str | None = None
|
||||
department_name: str = ""
|
||||
employee_grade: str | None = None
|
||||
expense_type: str = ""
|
||||
amount: Any = Decimal("0")
|
||||
currency: str = "CNY"
|
||||
invoice_count: int = 0
|
||||
occurred_at: datetime | None = None
|
||||
submitted_at: datetime | None = None
|
||||
status: str = ""
|
||||
reason: str = ""
|
||||
location: str = ""
|
||||
risk_flags: list[Any] = field(default_factory=list)
|
||||
items: list[RiskGraphClaimItemSnapshot] = field(default_factory=list)
|
||||
metadata: dict[str, Any] = field(default_factory=dict)
|
||||
|
||||
@classmethod
|
||||
def from_orm(cls, claim: Any) -> "RiskGraphClaimSnapshot":
|
||||
items = [
|
||||
RiskGraphClaimItemSnapshot.from_orm(item)
|
||||
for item in list(getattr(claim, "items", None) or [])
|
||||
]
|
||||
return cls(
|
||||
claim_id=str(getattr(claim, "id", "") or ""),
|
||||
claim_no=str(getattr(claim, "claim_no", "") or ""),
|
||||
employee_id=(
|
||||
str(getattr(claim, "employee_id", "") or "").strip()
|
||||
or None
|
||||
),
|
||||
employee_name=str(getattr(claim, "employee_name", "") or ""),
|
||||
department_id=(
|
||||
str(getattr(claim, "department_id", "") or "").strip()
|
||||
or None
|
||||
),
|
||||
department_name=str(getattr(claim, "department_name", "") or ""),
|
||||
employee_grade=(
|
||||
str(getattr(claim, "employee_grade", "") or "").strip()
|
||||
or None
|
||||
),
|
||||
expense_type=str(getattr(claim, "expense_type", "") or ""),
|
||||
amount=getattr(claim, "amount", Decimal("0")) or Decimal("0"),
|
||||
currency=str(getattr(claim, "currency", "CNY") or "CNY"),
|
||||
invoice_count=int(getattr(claim, "invoice_count", 0) or 0),
|
||||
occurred_at=getattr(claim, "occurred_at", None),
|
||||
submitted_at=getattr(claim, "submitted_at", None),
|
||||
status=str(getattr(claim, "status", "") or ""),
|
||||
reason=str(getattr(claim, "reason", "") or ""),
|
||||
location=str(getattr(claim, "location", "") or ""),
|
||||
risk_flags=list(getattr(claim, "risk_flags_json", None) or []),
|
||||
items=items,
|
||||
metadata=_metadata_from_object(claim),
|
||||
)
|
||||
|
||||
|
||||
@dataclass(slots=True)
|
||||
class RiskGraphNode:
|
||||
key: str
|
||||
node_type: str
|
||||
label: str
|
||||
canonical_key: str = ""
|
||||
canonical_id: str = ""
|
||||
ontology_type: str = ""
|
||||
ontology_parse_id: str = ""
|
||||
ontology_version: str = ""
|
||||
metadata: dict[str, Any] = field(default_factory=dict)
|
||||
|
||||
def as_dict(self) -> dict[str, Any]:
|
||||
return {
|
||||
"key": self.key,
|
||||
"node_type": self.node_type,
|
||||
"label": self.label,
|
||||
"canonical_key": self.canonical_key or self.key,
|
||||
"canonical_id": self.canonical_id or self.canonical_key or self.key,
|
||||
"ontology_type": self.ontology_type or self.node_type,
|
||||
"ontology_parse_id": self.ontology_parse_id,
|
||||
"ontology_version": self.ontology_version,
|
||||
"metadata": _json_safe(self.metadata),
|
||||
}
|
||||
|
||||
|
||||
@dataclass(slots=True)
|
||||
class RiskGraphEdge:
|
||||
source_key: str
|
||||
target_key: str
|
||||
edge_type: str
|
||||
weight: Decimal = Decimal("1")
|
||||
source: str = "algorithm"
|
||||
evidence: str = ""
|
||||
metadata: dict[str, Any] = field(default_factory=dict)
|
||||
|
||||
def edge_key(self) -> tuple[str, str, str]:
|
||||
return (self.source_key, self.target_key, self.edge_type)
|
||||
|
||||
def as_dict(self) -> dict[str, Any]:
|
||||
return {
|
||||
"source_key": self.source_key,
|
||||
"target_key": self.target_key,
|
||||
"edge_type": self.edge_type,
|
||||
"weight": _format_decimal(self.weight),
|
||||
"source": self.source,
|
||||
"evidence": self.evidence,
|
||||
"metadata": _json_safe(self.metadata),
|
||||
}
|
||||
|
||||
|
||||
@dataclass(slots=True)
|
||||
class PeerBaseline:
|
||||
scope: str
|
||||
sample_size: int
|
||||
median_amount: Decimal = Decimal("0")
|
||||
p75_amount: Decimal = Decimal("0")
|
||||
p90_amount: Decimal = Decimal("0")
|
||||
mean_amount: Decimal = Decimal("0")
|
||||
fallback_reason: str = ""
|
||||
|
||||
def as_dict(self) -> dict[str, Any]:
|
||||
return {
|
||||
"scope": self.scope,
|
||||
"sample_size": self.sample_size,
|
||||
"median_amount": _format_decimal(self.median_amount),
|
||||
"p75_amount": _format_decimal(self.p75_amount),
|
||||
"p90_amount": _format_decimal(self.p90_amount),
|
||||
"mean_amount": _format_decimal(self.mean_amount),
|
||||
"fallback_reason": self.fallback_reason,
|
||||
}
|
||||
|
||||
|
||||
@dataclass(slots=True)
|
||||
class RiskEvidence:
|
||||
code: str
|
||||
title: str
|
||||
detail: str
|
||||
source: str
|
||||
score: int = 0
|
||||
related_entity_keys: list[str] = field(default_factory=list)
|
||||
metadata: dict[str, Any] = field(default_factory=dict)
|
||||
|
||||
def as_dict(self) -> dict[str, Any]:
|
||||
return {
|
||||
"code": self.code,
|
||||
"title": self.title,
|
||||
"detail": self.detail,
|
||||
"source": self.source,
|
||||
"score": int(self.score),
|
||||
"related_entity_keys": list(self.related_entity_keys),
|
||||
"metadata": _json_safe(self.metadata),
|
||||
}
|
||||
|
||||
|
||||
@dataclass(slots=True)
|
||||
class RiskHistoryStats:
|
||||
risk_signal: str
|
||||
expense_type: str = ""
|
||||
similar_case_count: int = 0
|
||||
confirmed_count: int = 0
|
||||
false_positive_count: int = 0
|
||||
returned_count: int = 0
|
||||
|
||||
def as_dict(self) -> dict[str, Any]:
|
||||
return {
|
||||
"risk_signal": self.risk_signal,
|
||||
"expense_type": self.expense_type,
|
||||
"similar_case_count": self.similar_case_count,
|
||||
"confirmed_count": self.confirmed_count,
|
||||
"false_positive_count": self.false_positive_count,
|
||||
"returned_count": self.returned_count,
|
||||
}
|
||||
|
||||
|
||||
@dataclass(slots=True)
|
||||
class RiskGraphEvaluationContext:
|
||||
claims: list[RiskGraphClaimSnapshot]
|
||||
target_claim_ids: set[str] | None = None
|
||||
ontology_parse: Any | None = None
|
||||
ontology_parse_id: str = ""
|
||||
ontology_version: str = "ontology.v1"
|
||||
history_stats: list[RiskHistoryStats] = field(default_factory=list)
|
||||
min_peer_sample_size: int = 3
|
||||
observation_threshold: int = 31
|
||||
near_threshold_amount: Decimal = Decimal("5000")
|
||||
|
||||
|
||||
@dataclass(slots=True)
|
||||
class RiskObservationDraft:
|
||||
observation_key: str
|
||||
subject_type: str
|
||||
subject_key: str
|
||||
subject_label: str
|
||||
claim_id: str
|
||||
claim_no: str
|
||||
risk_type: str
|
||||
risk_signal: str
|
||||
title: str
|
||||
description: str
|
||||
risk_score: int
|
||||
risk_level: str
|
||||
confidence_score: Decimal
|
||||
control_stage: str
|
||||
control_mode: str
|
||||
automation_mode: str
|
||||
source: str
|
||||
algorithm_version: str
|
||||
contribution_scores: dict[str, int]
|
||||
baseline: PeerBaseline
|
||||
evidence: list[RiskEvidence] = field(default_factory=list)
|
||||
graph_node_keys: list[str] = field(default_factory=list)
|
||||
graph_edge_keys: list[dict[str, str]] = field(default_factory=list)
|
||||
policy_refs: list[str] = field(default_factory=list)
|
||||
similar_case_claim_ids: list[str] = field(default_factory=list)
|
||||
ontology_json: dict[str, Any] = field(default_factory=dict)
|
||||
decision_trace: dict[str, Any] = field(default_factory=dict)
|
||||
|
||||
def as_dict(self) -> dict[str, Any]:
|
||||
return {
|
||||
"observation_key": self.observation_key,
|
||||
"subject_type": self.subject_type,
|
||||
"subject_key": self.subject_key,
|
||||
"subject_label": self.subject_label,
|
||||
"claim_id": self.claim_id,
|
||||
"claim_no": self.claim_no,
|
||||
"risk_type": self.risk_type,
|
||||
"risk_signal": self.risk_signal,
|
||||
"title": self.title,
|
||||
"description": self.description,
|
||||
"risk_score": self.risk_score,
|
||||
"risk_level": self.risk_level,
|
||||
"confidence_score": _format_decimal(self.confidence_score),
|
||||
"control_stage": self.control_stage,
|
||||
"control_mode": self.control_mode,
|
||||
"automation_mode": self.automation_mode,
|
||||
"source": self.source,
|
||||
"algorithm_version": self.algorithm_version,
|
||||
"contribution_scores": dict(self.contribution_scores),
|
||||
"baseline": self.baseline.as_dict(),
|
||||
"evidence": [item.as_dict() for item in self.evidence],
|
||||
"graph_node_keys": list(self.graph_node_keys),
|
||||
"graph_edge_keys": list(self.graph_edge_keys),
|
||||
"policy_refs": list(self.policy_refs),
|
||||
"similar_case_claim_ids": list(self.similar_case_claim_ids),
|
||||
"ontology_json": _json_safe(self.ontology_json),
|
||||
"decision_trace": _json_safe(self.decision_trace),
|
||||
}
|
||||
|
||||
|
||||
@dataclass(slots=True)
|
||||
class RiskGraphEvaluationResult:
|
||||
observations: list[RiskObservationDraft]
|
||||
nodes: list[RiskGraphNode]
|
||||
edges: list[RiskGraphEdge]
|
||||
algorithm_version: str = ALGORITHM_VERSION
|
||||
|
||||
def as_dict(self) -> dict[str, Any]:
|
||||
return {
|
||||
"algorithm_version": self.algorithm_version,
|
||||
"observations": [item.as_dict() for item in self.observations],
|
||||
"nodes": [item.as_dict() for item in self.nodes],
|
||||
"edges": [item.as_dict() for item in self.edges],
|
||||
"summary": {
|
||||
"observation_count": len(self.observations),
|
||||
"node_count": len(self.nodes),
|
||||
"edge_count": len(self.edges),
|
||||
"high_or_above_count": sum(
|
||||
1
|
||||
for item in self.observations
|
||||
if item.risk_level in {LEVEL_HIGH, LEVEL_CRITICAL}
|
||||
),
|
||||
},
|
||||
}
|
||||
|
||||
|
||||
def _format_decimal(value: Any, places: str = "0.0000") -> str:
|
||||
if value is None:
|
||||
return "0"
|
||||
if not isinstance(value, Decimal):
|
||||
value = Decimal(str(value or "0"))
|
||||
return format(value.quantize(Decimal(places)), "f").rstrip("0").rstrip(".") or "0"
|
||||
|
||||
|
||||
def _json_safe(value: Any) -> Any:
|
||||
if isinstance(value, Decimal):
|
||||
return _format_decimal(value)
|
||||
if isinstance(value, (datetime, date)):
|
||||
return value.isoformat()
|
||||
if isinstance(value, list):
|
||||
return [_json_safe(item) for item in value]
|
||||
if isinstance(value, tuple):
|
||||
return [_json_safe(item) for item in value]
|
||||
if isinstance(value, dict):
|
||||
return {str(key): _json_safe(item) for key, item in value.items()}
|
||||
return value
|
||||
|
||||
|
||||
def _metadata_from_object(source: Any) -> dict[str, Any]:
|
||||
metadata: dict[str, Any] = {}
|
||||
for attr in (
|
||||
"metadata",
|
||||
"metadata_json",
|
||||
"extra_json",
|
||||
"supplier_id",
|
||||
"supplier_name",
|
||||
"vendor_id",
|
||||
"vendor_name",
|
||||
"merchant_id",
|
||||
"merchant_name",
|
||||
):
|
||||
value = getattr(source, attr, None)
|
||||
if isinstance(value, dict):
|
||||
metadata.update(value)
|
||||
elif attr != "metadata" and value not in (None, ""):
|
||||
metadata[attr] = value
|
||||
return metadata
|
||||
270
server/src/app/algorithem/risk_graph/ontology.py
Normal file
270
server/src/app/algorithem/risk_graph/ontology.py
Normal file
@@ -0,0 +1,270 @@
|
||||
"""Ontology-to-risk-graph mapping utilities."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from dataclasses import dataclass, field
|
||||
from decimal import Decimal
|
||||
from typing import Any
|
||||
|
||||
from .models import RiskGraphEdge, RiskGraphNode
|
||||
from .signals import NormalizedRiskSignal, normalize_risk_signals
|
||||
|
||||
ONTOLOGY_NODE_TYPE_MAP = {
|
||||
"expense_type": "expense_type",
|
||||
"document_type": "document",
|
||||
"employee": "employee",
|
||||
"department": "department",
|
||||
"vendor": "vendor",
|
||||
"supplier": "vendor",
|
||||
"merchant": "vendor",
|
||||
"customer": "customer",
|
||||
"risk_signal": "risk_signal",
|
||||
"invoice": "invoice",
|
||||
"claim": "claim",
|
||||
}
|
||||
|
||||
ALLOWED_ONTOLOGY_EDGE_TYPES = {
|
||||
"ontology_extracts",
|
||||
"ontology_constrains",
|
||||
"ontology_signals",
|
||||
}
|
||||
|
||||
|
||||
@dataclass(slots=True)
|
||||
class OntologyRiskGraphMapping:
|
||||
ontology_parse_id: str
|
||||
ontology_version: str
|
||||
domain: str
|
||||
scenario: str
|
||||
intent: str
|
||||
confidence: Decimal
|
||||
gate: str
|
||||
nodes: list[RiskGraphNode] = field(default_factory=list)
|
||||
edges: list[RiskGraphEdge] = field(default_factory=list)
|
||||
risk_signals: list[NormalizedRiskSignal] = field(default_factory=list)
|
||||
canonical_subject_key: str = ""
|
||||
raw_payload: dict[str, Any] = field(default_factory=dict)
|
||||
|
||||
def as_dict(self) -> dict[str, Any]:
|
||||
return {
|
||||
"ontology_parse_id": self.ontology_parse_id,
|
||||
"ontology_version": self.ontology_version,
|
||||
"domain": self.domain,
|
||||
"scenario": self.scenario,
|
||||
"intent": self.intent,
|
||||
"confidence": str(self.confidence),
|
||||
"gate": self.gate,
|
||||
"canonical_subject_key": self.canonical_subject_key,
|
||||
"risk_signals": [item.as_dict() for item in self.risk_signals],
|
||||
}
|
||||
|
||||
|
||||
def map_ontology_to_risk_graph(
|
||||
ontology: Any,
|
||||
*,
|
||||
ontology_parse_id: str = "",
|
||||
ontology_version: str = "ontology.v1",
|
||||
) -> OntologyRiskGraphMapping:
|
||||
payload = _model_to_dict(ontology)
|
||||
if not payload:
|
||||
return OntologyRiskGraphMapping(
|
||||
ontology_parse_id=ontology_parse_id,
|
||||
ontology_version=ontology_version,
|
||||
domain="unknown",
|
||||
scenario="unknown",
|
||||
intent="query",
|
||||
confidence=Decimal("0"),
|
||||
gate="candidate_only",
|
||||
)
|
||||
|
||||
parse_id = str(
|
||||
ontology_parse_id
|
||||
or payload.get("ontology_parse_id")
|
||||
or payload.get("parse_id")
|
||||
or payload.get("run_id")
|
||||
or "ontology_parse"
|
||||
)
|
||||
scenario = str(payload.get("scenario") or "unknown")
|
||||
intent = str(payload.get("intent") or "query")
|
||||
domain = str(payload.get("domain") or scenario)
|
||||
confidence = _to_decimal(payload.get("confidence"))
|
||||
gate = _gate_from_confidence(confidence)
|
||||
|
||||
nodes: list[RiskGraphNode] = [
|
||||
RiskGraphNode(
|
||||
key=f"ontology:{parse_id}",
|
||||
node_type="ontology_parse",
|
||||
label=parse_id,
|
||||
canonical_key=f"ontology:{parse_id}",
|
||||
canonical_id=parse_id,
|
||||
ontology_type="ontology_parse",
|
||||
ontology_parse_id=parse_id,
|
||||
ontology_version=ontology_version,
|
||||
metadata={
|
||||
"scenario": scenario,
|
||||
"intent": intent,
|
||||
"domain": domain,
|
||||
"confidence": str(confidence),
|
||||
},
|
||||
)
|
||||
]
|
||||
edges: list[RiskGraphEdge] = []
|
||||
canonical_subject_key = ""
|
||||
|
||||
for entity in list(payload.get("entities") or []):
|
||||
entity_payload = _model_to_dict(entity)
|
||||
raw_type = str(entity_payload.get("type") or "").strip().lower()
|
||||
node_type = ONTOLOGY_NODE_TYPE_MAP.get(raw_type, raw_type or "entity")
|
||||
value = str(
|
||||
entity_payload.get("normalized_value")
|
||||
or entity_payload.get("value")
|
||||
or ""
|
||||
).strip()
|
||||
if not value:
|
||||
continue
|
||||
key = f"{node_type}:{_canonical_key(value)}"
|
||||
nodes.append(
|
||||
RiskGraphNode(
|
||||
key=key,
|
||||
node_type=node_type,
|
||||
label=value,
|
||||
canonical_key=key,
|
||||
canonical_id=_canonical_key(value),
|
||||
ontology_type=raw_type or node_type,
|
||||
ontology_parse_id=parse_id,
|
||||
ontology_version=ontology_version,
|
||||
metadata={
|
||||
"role": entity_payload.get("role") or "target",
|
||||
"confidence": entity_payload.get("confidence") or 0,
|
||||
},
|
||||
)
|
||||
)
|
||||
edges.append(
|
||||
RiskGraphEdge(
|
||||
source_key=f"ontology:{parse_id}",
|
||||
target_key=key,
|
||||
edge_type="ontology_extracts",
|
||||
source="ontology",
|
||||
metadata={"raw_type": raw_type},
|
||||
)
|
||||
)
|
||||
if not canonical_subject_key and node_type in {"employee", "claim", "vendor"}:
|
||||
canonical_subject_key = key
|
||||
|
||||
for constraint in list(payload.get("constraints") or []):
|
||||
constraint_payload = _model_to_dict(constraint)
|
||||
field = str(constraint_payload.get("field") or "").strip()
|
||||
operator = str(constraint_payload.get("operator") or "").strip()
|
||||
value = str(constraint_payload.get("value") or "").strip()
|
||||
if not field or not value:
|
||||
continue
|
||||
key = f"constraint:{_canonical_key(field)}:{_canonical_key(value)}"
|
||||
nodes.append(
|
||||
RiskGraphNode(
|
||||
key=key,
|
||||
node_type="constraint",
|
||||
label=f"{field} {operator} {value}".strip(),
|
||||
canonical_key=key,
|
||||
canonical_id=key,
|
||||
ontology_type="constraint",
|
||||
ontology_parse_id=parse_id,
|
||||
ontology_version=ontology_version,
|
||||
metadata=constraint_payload,
|
||||
)
|
||||
)
|
||||
edges.append(
|
||||
RiskGraphEdge(
|
||||
source_key=f"ontology:{parse_id}",
|
||||
target_key=key,
|
||||
edge_type="ontology_constrains",
|
||||
source="ontology",
|
||||
)
|
||||
)
|
||||
|
||||
risk_signals = normalize_risk_signals(list(payload.get("risk_flags") or []), source="ontology")
|
||||
for signal in risk_signals:
|
||||
key = f"risk_signal:{signal.code}"
|
||||
nodes.append(
|
||||
RiskGraphNode(
|
||||
key=key,
|
||||
node_type="risk_signal",
|
||||
label=signal.label,
|
||||
canonical_key=key,
|
||||
canonical_id=signal.code,
|
||||
ontology_type="risk_signal",
|
||||
ontology_parse_id=parse_id,
|
||||
ontology_version=ontology_version,
|
||||
metadata={"severity": signal.severity, "score": signal.score},
|
||||
)
|
||||
)
|
||||
edges.append(
|
||||
RiskGraphEdge(
|
||||
source_key=f"ontology:{parse_id}",
|
||||
target_key=key,
|
||||
edge_type="ontology_signals",
|
||||
source="ontology",
|
||||
metadata={"gate": gate},
|
||||
)
|
||||
)
|
||||
|
||||
return OntologyRiskGraphMapping(
|
||||
ontology_parse_id=parse_id,
|
||||
ontology_version=ontology_version,
|
||||
domain=domain,
|
||||
scenario=scenario,
|
||||
intent=intent,
|
||||
confidence=confidence,
|
||||
gate=gate,
|
||||
nodes=_dedupe_nodes(nodes),
|
||||
edges=_dedupe_edges(edges),
|
||||
risk_signals=risk_signals,
|
||||
canonical_subject_key=canonical_subject_key,
|
||||
raw_payload=payload,
|
||||
)
|
||||
|
||||
|
||||
def _model_to_dict(value: Any) -> dict[str, Any]:
|
||||
if value is None:
|
||||
return {}
|
||||
if isinstance(value, dict):
|
||||
return dict(value)
|
||||
if hasattr(value, "model_dump"):
|
||||
return dict(value.model_dump(mode="json"))
|
||||
if hasattr(value, "dict"):
|
||||
return dict(value.dict())
|
||||
return {}
|
||||
|
||||
|
||||
def _gate_from_confidence(confidence: Decimal) -> str:
|
||||
if confidence >= Decimal("0.78"):
|
||||
return "automatic"
|
||||
if confidence >= Decimal("0.55"):
|
||||
return "review"
|
||||
return "candidate_only"
|
||||
|
||||
|
||||
def _canonical_key(value: str) -> str:
|
||||
return "_".join(str(value or "").strip().lower().split())
|
||||
|
||||
|
||||
def _to_decimal(value: Any) -> Decimal:
|
||||
try:
|
||||
return Decimal(str(value or "0"))
|
||||
except Exception:
|
||||
return Decimal("0")
|
||||
|
||||
|
||||
def _dedupe_nodes(nodes: list[RiskGraphNode]) -> list[RiskGraphNode]:
|
||||
by_key: dict[str, RiskGraphNode] = {}
|
||||
for node in nodes:
|
||||
by_key.setdefault(node.key, node)
|
||||
return list(by_key.values())
|
||||
|
||||
|
||||
def _dedupe_edges(edges: list[RiskGraphEdge]) -> list[RiskGraphEdge]:
|
||||
by_key: dict[tuple[str, str, str], RiskGraphEdge] = {}
|
||||
for edge in edges:
|
||||
if edge.edge_type not in ALLOWED_ONTOLOGY_EDGE_TYPES:
|
||||
continue
|
||||
by_key.setdefault(edge.edge_key(), edge)
|
||||
return list(by_key.values())
|
||||
@@ -0,0 +1,86 @@
|
||||
"""Output contract for finance policy knowledge organizing tasks."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from dataclasses import dataclass, field
|
||||
from typing import Any
|
||||
|
||||
|
||||
@dataclass(frozen=True, slots=True)
|
||||
class PolicySourceRef:
|
||||
source_id: str
|
||||
title: str
|
||||
location: str = ""
|
||||
page: str = ""
|
||||
|
||||
def as_dict(self) -> dict[str, Any]:
|
||||
return {
|
||||
"source_id": self.source_id,
|
||||
"title": self.title,
|
||||
"location": self.location,
|
||||
"page": self.page,
|
||||
}
|
||||
|
||||
|
||||
@dataclass(frozen=True, slots=True)
|
||||
class PolicyKnowledgeItem:
|
||||
policy_ref: str
|
||||
title: str
|
||||
summary: str
|
||||
expense_type: str = ""
|
||||
control_stage: str = ""
|
||||
trigger_conditions: list[str] = field(default_factory=list)
|
||||
source_refs: list[PolicySourceRef] = field(default_factory=list)
|
||||
review_status: str = "pending_review"
|
||||
|
||||
def as_dict(self) -> dict[str, Any]:
|
||||
return {
|
||||
"policy_ref": self.policy_ref,
|
||||
"title": self.title,
|
||||
"summary": self.summary,
|
||||
"expense_type": self.expense_type,
|
||||
"control_stage": self.control_stage,
|
||||
"trigger_conditions": list(self.trigger_conditions),
|
||||
"source_refs": [item.as_dict() for item in self.source_refs],
|
||||
"review_status": self.review_status,
|
||||
}
|
||||
|
||||
|
||||
@dataclass(slots=True)
|
||||
class PolicyKnowledgeOrganizingReport:
|
||||
summary: str
|
||||
categories: list[str] = field(default_factory=list)
|
||||
knowledge_items: list[PolicyKnowledgeItem] = field(default_factory=list)
|
||||
source_refs: list[PolicySourceRef] = field(default_factory=list)
|
||||
open_questions: list[str] = field(default_factory=list)
|
||||
next_actions: list[str] = field(default_factory=list)
|
||||
|
||||
def as_dict(self) -> dict[str, Any]:
|
||||
return {
|
||||
"summary": self.summary,
|
||||
"categories": list(self.categories),
|
||||
"knowledge_items": [item.as_dict() for item in self.knowledge_items],
|
||||
"source_refs": [item.as_dict() for item in self.source_refs],
|
||||
"open_questions": list(self.open_questions),
|
||||
"next_actions": list(self.next_actions),
|
||||
"risk_policy_refs": self.risk_policy_refs(),
|
||||
}
|
||||
|
||||
def risk_policy_refs(self) -> list[str]:
|
||||
return list(
|
||||
dict.fromkeys(
|
||||
item.policy_ref
|
||||
for item in self.knowledge_items
|
||||
if item.policy_ref and item.review_status in {"pending_review", "confirmed"}
|
||||
)
|
||||
)
|
||||
|
||||
|
||||
def build_policy_ref(expense_type: str, signal: str, *, prefix: str = "policy") -> str:
|
||||
expense = _token(expense_type) or "general"
|
||||
risk_signal = _token(signal) or "control"
|
||||
return f"{prefix}.{expense}.{risk_signal}"
|
||||
|
||||
|
||||
def _token(value: str) -> str:
|
||||
return "_".join(str(value or "").strip().lower().split())
|
||||
325
server/src/app/algorithem/risk_graph/process_mining.py
Normal file
325
server/src/app/algorithem/risk_graph/process_mining.py
Normal file
@@ -0,0 +1,325 @@
|
||||
"""Object-centric process mining for financial risk events."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from dataclasses import dataclass, field
|
||||
from datetime import UTC, datetime
|
||||
from typing import Any
|
||||
|
||||
from .models import RiskGraphClaimSnapshot
|
||||
|
||||
APPROVAL_EVENTS = {"approval_approved", "finance_approved", "claim_approved"}
|
||||
PAYMENT_EVENTS = {"payment_requested", "payment_completed"}
|
||||
RETURN_EVENTS = {"claim_returned", "approval_returned", "supplement_required"}
|
||||
SUBMIT_EVENTS = {"claim_submitted", "application_submitted"}
|
||||
|
||||
|
||||
@dataclass(slots=True)
|
||||
class ObjectCentricEvent:
|
||||
event_id: str
|
||||
event_type: str
|
||||
occurred_at: datetime
|
||||
object_refs: dict[str, list[str]]
|
||||
actor: str = ""
|
||||
source: str = ""
|
||||
metadata: dict[str, Any] = field(default_factory=dict)
|
||||
|
||||
def as_dict(self) -> dict[str, Any]:
|
||||
return {
|
||||
"event_id": self.event_id,
|
||||
"event_type": self.event_type,
|
||||
"occurred_at": self.occurred_at.isoformat(),
|
||||
"object_refs": {key: list(value) for key, value in self.object_refs.items()},
|
||||
"actor": self.actor,
|
||||
"source": self.source,
|
||||
"metadata": dict(self.metadata),
|
||||
}
|
||||
|
||||
|
||||
@dataclass(slots=True)
|
||||
class ConformanceRisk:
|
||||
risk_code: str
|
||||
title: str
|
||||
detail: str
|
||||
severity: str
|
||||
related_event_ids: list[str] = field(default_factory=list)
|
||||
object_refs: dict[str, list[str]] = field(default_factory=dict)
|
||||
|
||||
def as_dict(self) -> dict[str, Any]:
|
||||
return {
|
||||
"risk_code": self.risk_code,
|
||||
"title": self.title,
|
||||
"detail": self.detail,
|
||||
"severity": self.severity,
|
||||
"related_event_ids": list(self.related_event_ids),
|
||||
"object_refs": {key: list(value) for key, value in self.object_refs.items()},
|
||||
}
|
||||
|
||||
|
||||
class ObjectCentricProcessMiner:
|
||||
def build_from_claims(
|
||||
self,
|
||||
claims: list[RiskGraphClaimSnapshot],
|
||||
) -> list[ObjectCentricEvent]:
|
||||
events: list[ObjectCentricEvent] = []
|
||||
for claim in claims:
|
||||
events.extend(self._claim_events(claim))
|
||||
return sorted(events, key=lambda item: (item.occurred_at, item.event_id))
|
||||
|
||||
def build_from_dicts(self, rows: list[dict[str, Any]]) -> list[ObjectCentricEvent]:
|
||||
events: list[ObjectCentricEvent] = []
|
||||
for index, row in enumerate(rows):
|
||||
occurred_at = _datetime_from_value(row.get("occurred_at"))
|
||||
if occurred_at is None:
|
||||
continue
|
||||
event_type = str(row.get("event_type") or "").strip()
|
||||
if not event_type:
|
||||
continue
|
||||
events.append(
|
||||
ObjectCentricEvent(
|
||||
event_id=str(row.get("event_id") or f"event:{index}:{event_type}"),
|
||||
event_type=event_type,
|
||||
occurred_at=occurred_at,
|
||||
object_refs=_normalize_object_refs(row.get("object_refs")),
|
||||
actor=str(row.get("actor") or "").strip(),
|
||||
source=str(row.get("source") or "").strip(),
|
||||
metadata=dict(row.get("metadata") or {}),
|
||||
)
|
||||
)
|
||||
return sorted(events, key=lambda item: (item.occurred_at, item.event_id))
|
||||
|
||||
def _claim_events(self, claim: RiskGraphClaimSnapshot) -> list[ObjectCentricEvent]:
|
||||
object_refs = _claim_object_refs(claim)
|
||||
events: list[ObjectCentricEvent] = []
|
||||
occurred_at = claim.occurred_at or claim.submitted_at
|
||||
if occurred_at:
|
||||
events.append(
|
||||
ObjectCentricEvent(
|
||||
event_id=f"{claim.claim_id}:expense_occurred",
|
||||
event_type="expense_occurred",
|
||||
occurred_at=occurred_at,
|
||||
object_refs=object_refs,
|
||||
actor=claim.employee_id or claim.employee_name,
|
||||
source="expense_claim",
|
||||
metadata={"amount": str(claim.amount), "expense_type": claim.expense_type},
|
||||
)
|
||||
)
|
||||
if claim.submitted_at:
|
||||
events.append(
|
||||
ObjectCentricEvent(
|
||||
event_id=f"{claim.claim_id}:claim_submitted",
|
||||
event_type="claim_submitted",
|
||||
occurred_at=claim.submitted_at,
|
||||
object_refs=object_refs,
|
||||
actor=claim.employee_id or claim.employee_name,
|
||||
source="expense_claim",
|
||||
metadata={"status": claim.status},
|
||||
)
|
||||
)
|
||||
for item in claim.items:
|
||||
item_time = _datetime_from_value(item.item_date) or occurred_at or datetime.now(UTC)
|
||||
item_refs = _merge_object_refs(
|
||||
object_refs,
|
||||
{
|
||||
"claim_item": [item.item_id] if item.item_id else [],
|
||||
"invoice": [item.invoice_id] if item.invoice_id else [],
|
||||
},
|
||||
)
|
||||
events.append(
|
||||
ObjectCentricEvent(
|
||||
event_id=f"{claim.claim_id}:item:{item.item_id or len(events)}",
|
||||
event_type="expense_item_recorded",
|
||||
occurred_at=item_time,
|
||||
object_refs=item_refs,
|
||||
actor=claim.employee_id or claim.employee_name,
|
||||
source="expense_item",
|
||||
metadata={
|
||||
"amount": str(item.item_amount),
|
||||
"item_type": item.item_type,
|
||||
"item_location": item.item_location,
|
||||
},
|
||||
)
|
||||
)
|
||||
if item.invoice_id:
|
||||
events.append(
|
||||
ObjectCentricEvent(
|
||||
event_id=f"{claim.claim_id}:invoice:{item.invoice_id}",
|
||||
event_type="invoice_attached",
|
||||
occurred_at=item_time,
|
||||
object_refs=item_refs,
|
||||
actor=claim.employee_id or claim.employee_name,
|
||||
source="invoice",
|
||||
)
|
||||
)
|
||||
for index, flag in enumerate(claim.risk_flags):
|
||||
signal = _risk_signal_from_flag(flag)
|
||||
if not signal:
|
||||
continue
|
||||
events.append(
|
||||
ObjectCentricEvent(
|
||||
event_id=f"{claim.claim_id}:risk_flag:{index}:{signal}",
|
||||
event_type="risk_flagged",
|
||||
occurred_at=claim.submitted_at or occurred_at or datetime.now(UTC),
|
||||
object_refs=object_refs,
|
||||
source="risk_rule",
|
||||
metadata={"risk_signal": signal, "raw": flag},
|
||||
)
|
||||
)
|
||||
return events
|
||||
|
||||
|
||||
class ConformanceRiskDetector:
|
||||
def detect(self, events: list[ObjectCentricEvent]) -> list[ConformanceRisk]:
|
||||
risks: list[ConformanceRisk] = []
|
||||
for claim_key, claim_events in _events_by_object(events, "claim").items():
|
||||
ordered = sorted(claim_events, key=lambda item: (item.occurred_at, item.event_id))
|
||||
risks.extend(self._detect_claim_risks(claim_key, ordered))
|
||||
return risks
|
||||
|
||||
def _detect_claim_risks(
|
||||
self,
|
||||
claim_key: str,
|
||||
events: list[ObjectCentricEvent],
|
||||
) -> list[ConformanceRisk]:
|
||||
risks: list[ConformanceRisk] = []
|
||||
event_types = [event.event_type for event in events]
|
||||
first_submit = _first_event(events, SUBMIT_EVENTS)
|
||||
first_approval = _first_event(events, APPROVAL_EVENTS)
|
||||
first_payment = _first_event(events, PAYMENT_EVENTS)
|
||||
|
||||
if first_payment and (not first_approval or first_payment.occurred_at < first_approval.occurred_at):
|
||||
related = [first_payment.event_id]
|
||||
if first_approval:
|
||||
related.append(first_approval.event_id)
|
||||
risks.append(
|
||||
ConformanceRisk(
|
||||
risk_code="payment_before_approval",
|
||||
title="Payment before approval",
|
||||
detail="Payment event appears before an approval event.",
|
||||
severity="critical",
|
||||
related_event_ids=related,
|
||||
object_refs={"claim": [claim_key]},
|
||||
)
|
||||
)
|
||||
if first_approval and (not first_submit or first_approval.occurred_at < first_submit.occurred_at):
|
||||
related = [first_approval.event_id]
|
||||
if first_submit:
|
||||
related.append(first_submit.event_id)
|
||||
risks.append(
|
||||
ConformanceRisk(
|
||||
risk_code="approval_bypass",
|
||||
title="Approval bypass",
|
||||
detail="Approval appears before submission or without submission.",
|
||||
severity="high",
|
||||
related_event_ids=related,
|
||||
object_refs={"claim": [claim_key]},
|
||||
)
|
||||
)
|
||||
return_count = sum(1 for event_type in event_types if event_type in RETURN_EVENTS)
|
||||
submit_count = sum(1 for event_type in event_types if event_type in SUBMIT_EVENTS)
|
||||
if return_count >= 2 or (return_count >= 1 and submit_count >= 2):
|
||||
risks.append(
|
||||
ConformanceRisk(
|
||||
risk_code="rework_loop",
|
||||
title="Rework loop",
|
||||
detail="Claim has repeated return and resubmission events.",
|
||||
severity="medium",
|
||||
related_event_ids=[
|
||||
event.event_id
|
||||
for event in events
|
||||
if event.event_type in RETURN_EVENTS | SUBMIT_EVENTS
|
||||
],
|
||||
object_refs={"claim": [claim_key]},
|
||||
)
|
||||
)
|
||||
if "invoice_attached" in event_types and not first_submit:
|
||||
risks.append(
|
||||
ConformanceRisk(
|
||||
risk_code="process_bypass",
|
||||
title="Process bypass",
|
||||
detail="Invoice exists without a claim submission event.",
|
||||
severity="medium",
|
||||
related_event_ids=[
|
||||
event.event_id for event in events if event.event_type == "invoice_attached"
|
||||
],
|
||||
object_refs={"claim": [claim_key]},
|
||||
)
|
||||
)
|
||||
return risks
|
||||
|
||||
|
||||
def _claim_object_refs(claim: RiskGraphClaimSnapshot) -> dict[str, list[str]]:
|
||||
return {
|
||||
"claim": [claim.claim_id] if claim.claim_id else [],
|
||||
"employee": [claim.employee_id or claim.employee_name]
|
||||
if claim.employee_id or claim.employee_name
|
||||
else [],
|
||||
"department": [claim.department_id or claim.department_name]
|
||||
if claim.department_id or claim.department_name
|
||||
else [],
|
||||
"expense_type": [claim.expense_type] if claim.expense_type else [],
|
||||
}
|
||||
|
||||
|
||||
def _normalize_object_refs(value: Any) -> dict[str, list[str]]:
|
||||
if not isinstance(value, dict):
|
||||
return {}
|
||||
normalized: dict[str, list[str]] = {}
|
||||
for key, raw_items in value.items():
|
||||
if isinstance(raw_items, list):
|
||||
items = [str(item).strip() for item in raw_items if str(item).strip()]
|
||||
else:
|
||||
items = [str(raw_items).strip()] if str(raw_items or "").strip() else []
|
||||
normalized[str(key).strip()] = list(dict.fromkeys(items))
|
||||
return normalized
|
||||
|
||||
|
||||
def _merge_object_refs(*refs: dict[str, list[str]]) -> dict[str, list[str]]:
|
||||
merged: dict[str, list[str]] = {}
|
||||
for ref in refs:
|
||||
for key, values in ref.items():
|
||||
bucket = merged.setdefault(key, [])
|
||||
bucket.extend(str(value).strip() for value in values if str(value).strip())
|
||||
return {key: list(dict.fromkeys(values)) for key, values in merged.items()}
|
||||
|
||||
|
||||
def _events_by_object(
|
||||
events: list[ObjectCentricEvent],
|
||||
object_type: str,
|
||||
) -> dict[str, list[ObjectCentricEvent]]:
|
||||
grouped: dict[str, list[ObjectCentricEvent]] = {}
|
||||
for event in events:
|
||||
for object_key in event.object_refs.get(object_type, []):
|
||||
grouped.setdefault(object_key, []).append(event)
|
||||
return grouped
|
||||
|
||||
|
||||
def _first_event(
|
||||
events: list[ObjectCentricEvent],
|
||||
event_types: set[str],
|
||||
) -> ObjectCentricEvent | None:
|
||||
for event in events:
|
||||
if event.event_type in event_types:
|
||||
return event
|
||||
return None
|
||||
|
||||
|
||||
def _risk_signal_from_flag(flag: Any) -> str:
|
||||
if isinstance(flag, dict):
|
||||
raw = flag.get("risk_signal") or flag.get("signal") or flag.get("rule_code") or flag.get("code")
|
||||
else:
|
||||
raw = flag
|
||||
return "_".join(str(raw or "").strip().lower().split())
|
||||
|
||||
|
||||
def _datetime_from_value(value: Any) -> datetime | None:
|
||||
if isinstance(value, datetime):
|
||||
return value
|
||||
if hasattr(value, "year") and hasattr(value, "month") and hasattr(value, "day"):
|
||||
return datetime(value.year, value.month, value.day, tzinfo=UTC)
|
||||
if isinstance(value, str) and value.strip():
|
||||
try:
|
||||
return datetime.fromisoformat(value)
|
||||
except ValueError:
|
||||
return None
|
||||
return None
|
||||
259
server/src/app/algorithem/risk_graph/profile_baselines.py
Normal file
259
server/src/app/algorithem/risk_graph/profile_baselines.py
Normal file
@@ -0,0 +1,259 @@
|
||||
"""Profile baseline contracts for digital employee scans."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from collections import defaultdict
|
||||
from dataclasses import dataclass, field
|
||||
from decimal import ROUND_CEILING, ROUND_FLOOR, Decimal
|
||||
from typing import Any
|
||||
|
||||
from .models import ALGORITHM_VERSION, RiskGraphClaimSnapshot
|
||||
|
||||
ZERO = Decimal("0")
|
||||
HUNDRED = Decimal("100")
|
||||
|
||||
BASELINE_ALGORITHM_VERSION = f"{ALGORITHM_VERSION}.profile_baselines.v1"
|
||||
BASELINE_DIMENSIONS = ("employee", "department", "supplier", "expense_type")
|
||||
SUPPLIER_ID_KEYS = ("supplier_id", "vendor_id", "merchant_id", "supplier_code")
|
||||
SUPPLIER_NAME_KEYS = ("supplier_name", "vendor_name", "merchant_name", "supplier", "vendor", "merchant")
|
||||
|
||||
|
||||
@dataclass(frozen=True, slots=True)
|
||||
class ProfileBaselineBucket:
|
||||
dimension: str
|
||||
key: str
|
||||
label: str
|
||||
sample_size: int
|
||||
claim_count: int
|
||||
total_amount: Decimal
|
||||
average_amount: Decimal
|
||||
median_amount: Decimal
|
||||
p75_amount: Decimal
|
||||
p90_amount: Decimal
|
||||
claim_ids: list[str] = field(default_factory=list)
|
||||
|
||||
def as_dict(self) -> dict[str, Any]:
|
||||
return {
|
||||
"dimension": self.dimension,
|
||||
"key": self.key,
|
||||
"label": self.label,
|
||||
"sample_size": self.sample_size,
|
||||
"claim_count": self.claim_count,
|
||||
"total_amount": _format_decimal(self.total_amount),
|
||||
"average_amount": _format_decimal(self.average_amount),
|
||||
"median_amount": _format_decimal(self.median_amount),
|
||||
"p75_amount": _format_decimal(self.p75_amount),
|
||||
"p90_amount": _format_decimal(self.p90_amount),
|
||||
"claim_ids": list(self.claim_ids),
|
||||
}
|
||||
|
||||
|
||||
@dataclass(frozen=True, slots=True)
|
||||
class ProfileBaselineSnapshot:
|
||||
algorithm_version: str
|
||||
buckets: list[ProfileBaselineBucket] = field(default_factory=list)
|
||||
|
||||
@property
|
||||
def dimension_counts(self) -> dict[str, int]:
|
||||
counts = {dimension: 0 for dimension in BASELINE_DIMENSIONS}
|
||||
for bucket in self.buckets:
|
||||
counts[bucket.dimension] = counts.get(bucket.dimension, 0) + 1
|
||||
return counts
|
||||
|
||||
def buckets_for(self, dimension: str) -> list[ProfileBaselineBucket]:
|
||||
return [bucket for bucket in self.buckets if bucket.dimension == dimension]
|
||||
|
||||
def as_dict(self) -> dict[str, Any]:
|
||||
return {
|
||||
"algorithm_version": self.algorithm_version,
|
||||
"dimension_counts": self.dimension_counts,
|
||||
"bucket_count": len(self.buckets),
|
||||
"buckets": [bucket.as_dict() for bucket in self.buckets],
|
||||
}
|
||||
|
||||
|
||||
class ProfileBaselineUpdater:
|
||||
def build_from_claims(
|
||||
self,
|
||||
claims: list[RiskGraphClaimSnapshot],
|
||||
) -> ProfileBaselineSnapshot:
|
||||
grouped: dict[tuple[str, str], list[tuple[Decimal, str]]] = defaultdict(list)
|
||||
labels: dict[tuple[str, str], str] = {}
|
||||
|
||||
for claim in claims:
|
||||
self._add_claim_rows(grouped, labels, claim)
|
||||
|
||||
buckets = [
|
||||
_build_bucket(dimension, key, labels[(dimension, key)], rows)
|
||||
for (dimension, key), rows in grouped.items()
|
||||
]
|
||||
buckets.sort(key=lambda item: (item.dimension, -item.total_amount, item.key))
|
||||
return ProfileBaselineSnapshot(
|
||||
algorithm_version=BASELINE_ALGORITHM_VERSION,
|
||||
buckets=buckets,
|
||||
)
|
||||
|
||||
def _add_claim_rows(
|
||||
self,
|
||||
grouped: dict[tuple[str, str], list[tuple[Decimal, str]]],
|
||||
labels: dict[tuple[str, str], str],
|
||||
claim: RiskGraphClaimSnapshot,
|
||||
) -> None:
|
||||
amount = _to_decimal(claim.amount)
|
||||
claim_id = claim.claim_id or claim.claim_no
|
||||
_add_row(
|
||||
grouped,
|
||||
labels,
|
||||
"employee",
|
||||
claim.employee_id or claim.employee_name,
|
||||
claim.employee_name or claim.employee_id,
|
||||
amount,
|
||||
claim_id,
|
||||
)
|
||||
_add_row(
|
||||
grouped,
|
||||
labels,
|
||||
"department",
|
||||
claim.department_id or claim.department_name,
|
||||
claim.department_name or claim.department_id,
|
||||
amount,
|
||||
claim_id,
|
||||
)
|
||||
_add_row(
|
||||
grouped,
|
||||
labels,
|
||||
"expense_type",
|
||||
claim.expense_type,
|
||||
claim.expense_type,
|
||||
amount,
|
||||
claim_id,
|
||||
)
|
||||
for supplier_key, supplier_label, supplier_amount in _supplier_rows(claim):
|
||||
_add_row(
|
||||
grouped,
|
||||
labels,
|
||||
"supplier",
|
||||
supplier_key,
|
||||
supplier_label,
|
||||
supplier_amount,
|
||||
claim_id,
|
||||
)
|
||||
|
||||
|
||||
def _build_bucket(
|
||||
dimension: str,
|
||||
key: str,
|
||||
label: str,
|
||||
rows: list[tuple[Decimal, str]],
|
||||
) -> ProfileBaselineBucket:
|
||||
amounts = [amount for amount, _claim_id in rows]
|
||||
total = sum(amounts, ZERO)
|
||||
sample_size = len(amounts)
|
||||
claim_ids = sorted({claim_id for _amount, claim_id in rows if claim_id})
|
||||
average = total / Decimal(sample_size) if sample_size else ZERO
|
||||
return ProfileBaselineBucket(
|
||||
dimension=dimension,
|
||||
key=key,
|
||||
label=label,
|
||||
sample_size=sample_size,
|
||||
claim_count=len(claim_ids),
|
||||
total_amount=total,
|
||||
average_amount=average,
|
||||
median_amount=_percentile(amounts, 50),
|
||||
p75_amount=_percentile(amounts, 75),
|
||||
p90_amount=_percentile(amounts, 90),
|
||||
claim_ids=claim_ids,
|
||||
)
|
||||
|
||||
|
||||
def _add_row(
|
||||
grouped: dict[tuple[str, str], list[tuple[Decimal, str]]],
|
||||
labels: dict[tuple[str, str], str],
|
||||
dimension: str,
|
||||
key_source: Any,
|
||||
label_source: Any,
|
||||
amount: Decimal,
|
||||
claim_id: str,
|
||||
) -> None:
|
||||
key = _canonical_key(key_source)
|
||||
if not key:
|
||||
return
|
||||
group_key = (dimension, key)
|
||||
labels.setdefault(group_key, str(label_source or key_source or key).strip() or key)
|
||||
grouped[group_key].append((amount, claim_id))
|
||||
|
||||
|
||||
def _supplier_rows(claim: RiskGraphClaimSnapshot) -> list[tuple[str, str, Decimal]]:
|
||||
item_rows: list[tuple[str, str, Decimal]] = []
|
||||
for item in claim.items:
|
||||
supplier = _extract_supplier(item.metadata)
|
||||
if supplier is not None:
|
||||
item_rows.append((*supplier, _to_decimal(item.item_amount)))
|
||||
if item_rows:
|
||||
return item_rows
|
||||
|
||||
supplier = _extract_supplier(claim.metadata) or _extract_supplier_from_flags(claim.risk_flags)
|
||||
if supplier is None:
|
||||
return []
|
||||
return [(*supplier, _to_decimal(claim.amount))]
|
||||
|
||||
|
||||
def _extract_supplier(metadata: Any) -> tuple[str, str] | None:
|
||||
if not isinstance(metadata, dict):
|
||||
return None
|
||||
supplier_id = _first_text(metadata, SUPPLIER_ID_KEYS)
|
||||
supplier_name = _first_text(metadata, SUPPLIER_NAME_KEYS)
|
||||
key = supplier_id or supplier_name
|
||||
if not key:
|
||||
return None
|
||||
return key, supplier_name or supplier_id or key
|
||||
|
||||
|
||||
def _extract_supplier_from_flags(flags: list[Any]) -> tuple[str, str] | None:
|
||||
for flag in flags or []:
|
||||
if not isinstance(flag, dict):
|
||||
continue
|
||||
supplier = _extract_supplier(flag) or _extract_supplier(flag.get("metadata"))
|
||||
if supplier is not None:
|
||||
return supplier
|
||||
return None
|
||||
|
||||
|
||||
def _first_text(source: dict[str, Any], keys: tuple[str, ...]) -> str:
|
||||
for key in keys:
|
||||
value = str(source.get(key) or "").strip()
|
||||
if value:
|
||||
return value
|
||||
return ""
|
||||
|
||||
|
||||
def _percentile(values: list[Decimal], percent: int) -> Decimal:
|
||||
normalized = sorted(value for value in values if value >= ZERO)
|
||||
if not normalized:
|
||||
return ZERO
|
||||
if len(normalized) == 1:
|
||||
return normalized[0]
|
||||
position = Decimal(len(normalized) - 1) * Decimal(percent) / HUNDRED
|
||||
lower = int(position.to_integral_value(rounding=ROUND_FLOOR))
|
||||
upper = int(position.to_integral_value(rounding=ROUND_CEILING))
|
||||
if lower == upper:
|
||||
return normalized[lower]
|
||||
fraction = position - Decimal(lower)
|
||||
return normalized[lower] + (normalized[upper] - normalized[lower]) * fraction
|
||||
|
||||
|
||||
def _to_decimal(value: Any) -> Decimal:
|
||||
try:
|
||||
return Decimal(str(value or "0"))
|
||||
except Exception:
|
||||
return ZERO
|
||||
|
||||
|
||||
def _format_decimal(value: Any) -> str:
|
||||
if not isinstance(value, Decimal):
|
||||
value = _to_decimal(value)
|
||||
return format(value.quantize(Decimal("0.0001")), "f").rstrip("0").rstrip(".") or "0"
|
||||
|
||||
|
||||
def _canonical_key(value: Any) -> str:
|
||||
return "_".join(str(value or "").strip().lower().split())
|
||||
84
server/src/app/algorithem/risk_graph/quality.py
Normal file
84
server/src/app/algorithem/risk_graph/quality.py
Normal file
@@ -0,0 +1,84 @@
|
||||
"""Data quality gates for strong financial risk conclusions."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from dataclasses import dataclass, field
|
||||
from decimal import Decimal
|
||||
from typing import Any
|
||||
|
||||
from .models import RiskGraphClaimSnapshot
|
||||
|
||||
|
||||
@dataclass(slots=True)
|
||||
class RiskDataQualityResult:
|
||||
passed: bool
|
||||
gate: str
|
||||
max_risk_score: int
|
||||
missing_fields: list[str] = field(default_factory=list)
|
||||
warnings: list[str] = field(default_factory=list)
|
||||
|
||||
def as_dict(self) -> dict[str, Any]:
|
||||
return {
|
||||
"passed": self.passed,
|
||||
"gate": self.gate,
|
||||
"max_risk_score": self.max_risk_score,
|
||||
"missing_fields": list(self.missing_fields),
|
||||
"warnings": list(self.warnings),
|
||||
}
|
||||
|
||||
|
||||
class RiskDataQualityGate:
|
||||
"""Prevent weak source data from becoming strong automated conclusions."""
|
||||
|
||||
def evaluate_claim(self, claim: RiskGraphClaimSnapshot) -> RiskDataQualityResult:
|
||||
missing_fields: list[str] = []
|
||||
warnings: list[str] = []
|
||||
|
||||
if not str(claim.claim_id or "").strip():
|
||||
missing_fields.append("claim_id")
|
||||
if not (str(claim.employee_id or "").strip() or str(claim.employee_name or "").strip()):
|
||||
missing_fields.append("employee")
|
||||
if _to_decimal(claim.amount) <= Decimal("0"):
|
||||
missing_fields.append("amount")
|
||||
if not str(claim.expense_type or "").strip():
|
||||
warnings.append("expense_type")
|
||||
if claim.invoice_count > 0 and not claim.items:
|
||||
warnings.append("invoice_items")
|
||||
|
||||
if missing_fields:
|
||||
return RiskDataQualityResult(
|
||||
passed=False,
|
||||
gate="capped_missing_required_fields",
|
||||
max_risk_score=69,
|
||||
missing_fields=missing_fields,
|
||||
warnings=warnings,
|
||||
)
|
||||
if len(warnings) >= 2:
|
||||
return RiskDataQualityResult(
|
||||
passed=False,
|
||||
gate="capped_low_context_quality",
|
||||
max_risk_score=69,
|
||||
warnings=warnings,
|
||||
)
|
||||
return RiskDataQualityResult(
|
||||
passed=True,
|
||||
gate="passed",
|
||||
max_risk_score=100,
|
||||
warnings=warnings,
|
||||
)
|
||||
|
||||
def apply_score_cap(
|
||||
self,
|
||||
risk_score: int,
|
||||
result: RiskDataQualityResult,
|
||||
) -> tuple[int, str]:
|
||||
if risk_score > result.max_risk_score:
|
||||
return result.max_risk_score, result.gate
|
||||
return risk_score, result.gate
|
||||
|
||||
|
||||
def _to_decimal(value: Any) -> Decimal:
|
||||
try:
|
||||
return Decimal(str(value or "0"))
|
||||
except Exception:
|
||||
return Decimal("0")
|
||||
93
server/src/app/algorithem/risk_graph/replay.py
Normal file
93
server/src/app/algorithem/risk_graph/replay.py
Normal file
@@ -0,0 +1,93 @@
|
||||
"""Replay-set contracts for risk graph algorithm evaluation."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from dataclasses import dataclass, field
|
||||
from datetime import datetime
|
||||
from typing import Any
|
||||
|
||||
|
||||
@dataclass(frozen=True, slots=True)
|
||||
class AlgorithmReplayCase:
|
||||
replay_case_id: str
|
||||
claim_id: str
|
||||
ontology_version: str
|
||||
rule_version: str
|
||||
algorithm_version: str
|
||||
feedback_label: str
|
||||
payload: dict[str, Any] = field(default_factory=dict)
|
||||
|
||||
def as_dict(self) -> dict[str, Any]:
|
||||
return {
|
||||
"replay_case_id": self.replay_case_id,
|
||||
"claim_id": self.claim_id,
|
||||
"ontology_version": self.ontology_version,
|
||||
"rule_version": self.rule_version,
|
||||
"algorithm_version": self.algorithm_version,
|
||||
"feedback_label": self.feedback_label,
|
||||
"payload": dict(self.payload),
|
||||
}
|
||||
|
||||
|
||||
@dataclass(slots=True)
|
||||
class AlgorithmReplaySet:
|
||||
replay_set_id: str
|
||||
created_at: datetime
|
||||
cases: list[AlgorithmReplayCase] = field(default_factory=list)
|
||||
|
||||
def as_dict(self) -> dict[str, Any]:
|
||||
return {
|
||||
"replay_set_id": self.replay_set_id,
|
||||
"created_at": self.created_at.isoformat(),
|
||||
"case_count": len(self.cases),
|
||||
"cases": [item.as_dict() for item in self.cases],
|
||||
}
|
||||
|
||||
|
||||
class AlgorithmReplaySetBuilder:
|
||||
def build_from_observations(
|
||||
self,
|
||||
replay_set_id: str,
|
||||
observations: list[dict[str, Any]],
|
||||
*,
|
||||
created_at: datetime,
|
||||
) -> AlgorithmReplaySet:
|
||||
cases = [
|
||||
self._case_from_observation(index, observation)
|
||||
for index, observation in enumerate(observations, start=1)
|
||||
]
|
||||
return AlgorithmReplaySet(
|
||||
replay_set_id=replay_set_id,
|
||||
created_at=created_at,
|
||||
cases=cases,
|
||||
)
|
||||
|
||||
def _case_from_observation(
|
||||
self,
|
||||
index: int,
|
||||
observation: dict[str, Any],
|
||||
) -> AlgorithmReplayCase:
|
||||
ontology = observation.get("ontology_json") or {}
|
||||
trace = observation.get("decision_trace") or {}
|
||||
return AlgorithmReplayCase(
|
||||
replay_case_id=str(
|
||||
observation.get("evaluation_case_id")
|
||||
or trace.get("evaluation_case_id")
|
||||
or f"replay:{index}:{observation.get('observation_key') or 'observation'}"
|
||||
),
|
||||
claim_id=str(observation.get("claim_id") or ""),
|
||||
ontology_version=str(ontology.get("ontology_version") or ""),
|
||||
rule_version=str(trace.get("rule_version") or ""),
|
||||
algorithm_version=str(observation.get("algorithm_version") or ""),
|
||||
feedback_label=str(
|
||||
observation.get("feedback_status")
|
||||
or observation.get("status")
|
||||
or "unreviewed"
|
||||
),
|
||||
payload={
|
||||
"risk_signal": observation.get("risk_signal"),
|
||||
"risk_score": observation.get("risk_score"),
|
||||
"risk_level": observation.get("risk_level"),
|
||||
"decision_trace": trace,
|
||||
},
|
||||
)
|
||||
106
server/src/app/algorithem/risk_graph/rule_discovery.py
Normal file
106
server/src/app/algorithem/risk_graph/rule_discovery.py
Normal file
@@ -0,0 +1,106 @@
|
||||
"""Candidate risk rule discovery from reviewed risk observations."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from dataclasses import dataclass, field
|
||||
from typing import Any
|
||||
|
||||
|
||||
@dataclass(frozen=True, slots=True)
|
||||
class CandidateRiskRule:
|
||||
candidate_id: str
|
||||
rule_code: str
|
||||
title: str
|
||||
risk_signal: str
|
||||
evidence: list[dict[str, Any]]
|
||||
source: str
|
||||
confidence_score: float
|
||||
status: str = "candidate_review"
|
||||
|
||||
def as_dict(self) -> dict[str, Any]:
|
||||
return {
|
||||
"candidate_id": self.candidate_id,
|
||||
"rule_code": self.rule_code,
|
||||
"title": self.title,
|
||||
"risk_signal": self.risk_signal,
|
||||
"evidence": list(self.evidence),
|
||||
"source": self.source,
|
||||
"confidence_score": self.confidence_score,
|
||||
"status": self.status,
|
||||
}
|
||||
|
||||
|
||||
class CandidateRiskRuleDiscovery:
|
||||
def discover_from_feedback(
|
||||
self,
|
||||
observations: list[dict[str, Any]],
|
||||
feedback_items: list[dict[str, Any]],
|
||||
) -> list[CandidateRiskRule]:
|
||||
observation_by_key = {
|
||||
str(item.get("observation_key") or item.get("id") or ""): item
|
||||
for item in observations
|
||||
}
|
||||
candidates: list[CandidateRiskRule] = []
|
||||
for feedback in feedback_items:
|
||||
source = str(feedback.get("candidate_rule_source") or "").strip()
|
||||
decision = str(feedback.get("decision") or feedback.get("feedback_type") or "").strip()
|
||||
if source != "risk_observation_feedback" and "candidate" not in decision:
|
||||
continue
|
||||
observation_key = str(feedback.get("observation_key") or "").strip()
|
||||
observation = observation_by_key.get(observation_key, {})
|
||||
risk_signal = str(
|
||||
feedback.get("risk_signal") or observation.get("risk_signal") or ""
|
||||
).strip()
|
||||
if not risk_signal:
|
||||
continue
|
||||
confidence = _confidence(feedback, observation)
|
||||
candidates.append(
|
||||
CandidateRiskRule(
|
||||
candidate_id=f"candidate:{observation_key or risk_signal}:{risk_signal}",
|
||||
rule_code=f"candidate.risk.{risk_signal}",
|
||||
title=f"{risk_signal} candidate rule",
|
||||
risk_signal=risk_signal,
|
||||
evidence=_candidate_evidence(observation, feedback),
|
||||
source=source or "risk_observation_feedback",
|
||||
confidence_score=confidence,
|
||||
)
|
||||
)
|
||||
return _dedupe_candidates(candidates)
|
||||
|
||||
|
||||
def _confidence(feedback: dict[str, Any], observation: dict[str, Any]) -> float:
|
||||
raw = feedback.get("confidence_score")
|
||||
if raw in (None, ""):
|
||||
raw = observation.get("confidence_score")
|
||||
try:
|
||||
return max(0.0, min(1.0, float(raw or 0.55)))
|
||||
except (TypeError, ValueError):
|
||||
return 0.55
|
||||
|
||||
|
||||
def _candidate_evidence(
|
||||
observation: dict[str, Any],
|
||||
feedback: dict[str, Any],
|
||||
) -> list[dict[str, Any]]:
|
||||
evidence: list[dict[str, Any]] = []
|
||||
for item in observation.get("evidence", []) or []:
|
||||
if isinstance(item, dict):
|
||||
evidence.append({"source": item.get("source") or "observation", **item})
|
||||
evidence.append(
|
||||
{
|
||||
"source": feedback.get("candidate_rule_source") or "risk_observation_feedback",
|
||||
"feedback_type": feedback.get("feedback_type"),
|
||||
"action": feedback.get("action"),
|
||||
"comment": feedback.get("comment"),
|
||||
}
|
||||
)
|
||||
return evidence
|
||||
|
||||
|
||||
def _dedupe_candidates(candidates: list[CandidateRiskRule]) -> list[CandidateRiskRule]:
|
||||
by_code: dict[str, CandidateRiskRule] = {}
|
||||
for candidate in candidates:
|
||||
current = by_code.get(candidate.rule_code)
|
||||
if current is None or candidate.confidence_score > current.confidence_score:
|
||||
by_code[candidate.rule_code] = candidate
|
||||
return list(by_code.values())
|
||||
94
server/src/app/algorithem/risk_graph/sampling.py
Normal file
94
server/src/app/algorithem/risk_graph/sampling.py
Normal file
@@ -0,0 +1,94 @@
|
||||
"""Risk-based sampling strategy for audit review and replay."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from dataclasses import dataclass
|
||||
from decimal import Decimal
|
||||
from typing import Any
|
||||
|
||||
from .models import RiskHistoryStats
|
||||
|
||||
|
||||
@dataclass(slots=True)
|
||||
class RiskSamplingDecision:
|
||||
strategy: str
|
||||
threshold: int
|
||||
replay_bucket: str
|
||||
audit_required: bool
|
||||
reason: str
|
||||
|
||||
def as_dict(self) -> dict[str, Any]:
|
||||
return {
|
||||
"strategy": self.strategy,
|
||||
"threshold": self.threshold,
|
||||
"replay_bucket": self.replay_bucket,
|
||||
"audit_required": self.audit_required,
|
||||
"reason": self.reason,
|
||||
}
|
||||
|
||||
|
||||
class RiskSamplingPlanner:
|
||||
def plan(
|
||||
self,
|
||||
*,
|
||||
risk_score: int,
|
||||
confidence: Decimal,
|
||||
evidence_source_count: int,
|
||||
data_quality_passed: bool = True,
|
||||
data_quality_gate: str = "",
|
||||
history: RiskHistoryStats | None = None,
|
||||
) -> RiskSamplingDecision:
|
||||
false_positive_rate = _false_positive_rate(history)
|
||||
if not data_quality_passed:
|
||||
return RiskSamplingDecision(
|
||||
strategy="uncertainty_sample",
|
||||
threshold=45,
|
||||
replay_bucket="data_quality_gate",
|
||||
audit_required=True,
|
||||
reason=data_quality_gate or "data_quality_gate_not_passed",
|
||||
)
|
||||
if risk_score >= 90:
|
||||
return RiskSamplingDecision(
|
||||
strategy="mandatory_review",
|
||||
threshold=90,
|
||||
replay_bucket="critical_high_risk",
|
||||
audit_required=True,
|
||||
reason="risk_score_above_critical_threshold",
|
||||
)
|
||||
if risk_score >= 70:
|
||||
return RiskSamplingDecision(
|
||||
strategy="focused_review",
|
||||
threshold=70,
|
||||
replay_bucket="high_risk",
|
||||
audit_required=True,
|
||||
reason="risk_score_above_high_threshold",
|
||||
)
|
||||
if false_positive_rate >= Decimal("0.30"):
|
||||
return RiskSamplingDecision(
|
||||
strategy="calibration_sample",
|
||||
threshold=45,
|
||||
replay_bucket="false_positive_calibration",
|
||||
audit_required=True,
|
||||
reason="historical_false_positive_rate_high",
|
||||
)
|
||||
if confidence < Decimal("0.55") or evidence_source_count < 2:
|
||||
return RiskSamplingDecision(
|
||||
strategy="uncertainty_sample",
|
||||
threshold=45,
|
||||
replay_bucket="low_confidence",
|
||||
audit_required=True,
|
||||
reason="confidence_or_evidence_source_insufficient",
|
||||
)
|
||||
return RiskSamplingDecision(
|
||||
strategy="monitor",
|
||||
threshold=31,
|
||||
replay_bucket="routine_monitoring",
|
||||
audit_required=False,
|
||||
reason="below_review_threshold",
|
||||
)
|
||||
|
||||
|
||||
def _false_positive_rate(history: RiskHistoryStats | None) -> Decimal:
|
||||
if history is None or history.similar_case_count <= 0:
|
||||
return Decimal("0")
|
||||
return Decimal(history.false_positive_count) / Decimal(history.similar_case_count)
|
||||
230
server/src/app/algorithem/risk_graph/signals.py
Normal file
230
server/src/app/algorithem/risk_graph/signals.py
Normal file
@@ -0,0 +1,230 @@
|
||||
"""Risk signal normalization shared by rules, ontology, and graph scoring."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from dataclasses import dataclass
|
||||
from decimal import Decimal
|
||||
from typing import Any
|
||||
|
||||
SEVERITY_SCORE = {
|
||||
"info": 12,
|
||||
"low": 32,
|
||||
"medium": 58,
|
||||
"high": 82,
|
||||
"critical": 100,
|
||||
}
|
||||
|
||||
SIGNAL_ALIASES: dict[str, str] = {
|
||||
"amount_over_limit": "amount_limit_exceeded",
|
||||
"over_budget": "budget_overrun",
|
||||
"budget_exceeded": "budget_overrun",
|
||||
"duplicate_expense": "duplicate_invoice",
|
||||
"duplicate_ticket": "duplicate_invoice",
|
||||
"risk.invoice.duplicate_invoice": "duplicate_invoice",
|
||||
"location_mismatch": "location_mismatch",
|
||||
"city_mismatch": "location_mismatch",
|
||||
"hotel_itinerary_mismatch": "hotel_itinerary_mismatch",
|
||||
"date_outside_trip": "date_outside_trip",
|
||||
"preapproval_absent": "preapproval_absent",
|
||||
"application_fields_missing": "application_fields_missing",
|
||||
"attachment_ocr_missing": "attachment_missing",
|
||||
"missing_attachment": "attachment_missing",
|
||||
"reason_too_brief": "reason_too_brief",
|
||||
"vague_ticket_content": "vague_goods_description",
|
||||
"personal_purpose": "personal_purpose",
|
||||
"split_billing": "split_billing",
|
||||
"frequency_anomaly": "frequency_anomaly",
|
||||
"collusion": "cross_department_cluster",
|
||||
"cross_department_cluster": "cross_department_cluster",
|
||||
"buyer_name_mismatch": "buyer_name_mismatch",
|
||||
"document_expense_mismatch": "document_expense_mismatch",
|
||||
"void_or_red_invoice": "void_or_red_invoice",
|
||||
"cross_year_invoice": "cross_year_invoice",
|
||||
"entertainment_missing_detail": "entertainment_missing_detail",
|
||||
}
|
||||
|
||||
SIGNAL_LABELS: dict[str, str] = {
|
||||
"amount_limit_exceeded": "Amount limit exceeded",
|
||||
"budget_overrun": "Budget overrun",
|
||||
"duplicate_invoice": "Duplicate invoice",
|
||||
"location_mismatch": "Location mismatch",
|
||||
"hotel_itinerary_mismatch": "Hotel and itinerary mismatch",
|
||||
"date_outside_trip": "Date outside approved trip",
|
||||
"preapproval_absent": "Pre-approval missing",
|
||||
"application_fields_missing": "Application fields missing",
|
||||
"attachment_missing": "Attachment missing",
|
||||
"reason_too_brief": "Reason too brief",
|
||||
"vague_goods_description": "Vague goods description",
|
||||
"personal_purpose": "Possible personal purpose",
|
||||
"split_billing": "Split billing pattern",
|
||||
"frequency_anomaly": "Frequency anomaly",
|
||||
"cross_department_cluster": "Cross-department spending cluster",
|
||||
"buyer_name_mismatch": "Buyer name mismatch",
|
||||
"document_expense_mismatch": "Document and expense mismatch",
|
||||
"void_or_red_invoice": "Void or red invoice",
|
||||
"cross_year_invoice": "Cross-year invoice",
|
||||
"entertainment_missing_detail": "Entertainment detail missing",
|
||||
}
|
||||
|
||||
SIGNAL_DEFAULT_SEVERITY: dict[str, str] = {
|
||||
"duplicate_invoice": "critical",
|
||||
"personal_purpose": "high",
|
||||
"preapproval_absent": "high",
|
||||
"date_outside_trip": "high",
|
||||
"amount_limit_exceeded": "high",
|
||||
"budget_overrun": "high",
|
||||
"split_billing": "high",
|
||||
"cross_department_cluster": "high",
|
||||
"location_mismatch": "medium",
|
||||
"hotel_itinerary_mismatch": "medium",
|
||||
"frequency_anomaly": "medium",
|
||||
"buyer_name_mismatch": "medium",
|
||||
"document_expense_mismatch": "medium",
|
||||
"void_or_red_invoice": "high",
|
||||
"cross_year_invoice": "medium",
|
||||
"entertainment_missing_detail": "medium",
|
||||
"application_fields_missing": "low",
|
||||
"attachment_missing": "low",
|
||||
"reason_too_brief": "low",
|
||||
"vague_goods_description": "low",
|
||||
}
|
||||
|
||||
POLICY_BOUND_SIGNALS = {
|
||||
"amount_limit_exceeded",
|
||||
"budget_overrun",
|
||||
"preapproval_absent",
|
||||
"date_outside_trip",
|
||||
"hotel_itinerary_mismatch",
|
||||
"location_mismatch",
|
||||
"document_expense_mismatch",
|
||||
"buyer_name_mismatch",
|
||||
"entertainment_missing_detail",
|
||||
"application_fields_missing",
|
||||
"attachment_missing",
|
||||
}
|
||||
|
||||
|
||||
@dataclass(slots=True)
|
||||
class NormalizedRiskSignal:
|
||||
code: str
|
||||
raw_code: str
|
||||
label: str
|
||||
severity: str
|
||||
score: int
|
||||
confidence: Decimal = Decimal("1")
|
||||
source: str = "rule"
|
||||
metadata: dict[str, Any] | None = None
|
||||
|
||||
def as_dict(self) -> dict[str, Any]:
|
||||
return {
|
||||
"code": self.code,
|
||||
"raw_code": self.raw_code,
|
||||
"label": self.label,
|
||||
"severity": self.severity,
|
||||
"score": self.score,
|
||||
"confidence": str(self.confidence),
|
||||
"source": self.source,
|
||||
"metadata": self.metadata or {},
|
||||
}
|
||||
|
||||
|
||||
def normalize_risk_signal(value: Any, *, source: str = "rule") -> NormalizedRiskSignal | None:
|
||||
if isinstance(value, dict):
|
||||
raw_code = _first_present(
|
||||
value,
|
||||
"risk_signal",
|
||||
"signal",
|
||||
"code",
|
||||
"risk_type",
|
||||
"rule_code",
|
||||
"type",
|
||||
)
|
||||
severity = str(value.get("severity") or value.get("risk_level") or "").strip().lower()
|
||||
confidence = _to_decimal(value.get("confidence") or value.get("score_confidence") or 1)
|
||||
explicit_score = value.get("risk_score") or value.get("score")
|
||||
metadata = dict(value)
|
||||
else:
|
||||
raw_code = str(value or "").strip()
|
||||
severity = ""
|
||||
confidence = Decimal("1")
|
||||
explicit_score = None
|
||||
metadata = {}
|
||||
|
||||
if not raw_code:
|
||||
return None
|
||||
|
||||
canonical = SIGNAL_ALIASES.get(raw_code.strip().lower(), raw_code.strip().lower())
|
||||
canonical = canonical.replace(" ", "_")
|
||||
severity = severity or SIGNAL_DEFAULT_SEVERITY.get(canonical, "medium")
|
||||
score = _score_from_value(explicit_score, severity=severity)
|
||||
return NormalizedRiskSignal(
|
||||
code=canonical,
|
||||
raw_code=raw_code,
|
||||
label=SIGNAL_LABELS.get(canonical, canonical.replace("_", " ").title()),
|
||||
severity=severity,
|
||||
score=score,
|
||||
confidence=max(Decimal("0"), min(Decimal("1"), confidence)),
|
||||
source=source,
|
||||
metadata=metadata,
|
||||
)
|
||||
|
||||
|
||||
def normalize_risk_signals(
|
||||
values: list[Any],
|
||||
*,
|
||||
source: str = "rule",
|
||||
) -> list[NormalizedRiskSignal]:
|
||||
by_code: dict[str, NormalizedRiskSignal] = {}
|
||||
for value in values:
|
||||
signal = normalize_risk_signal(value, source=source)
|
||||
if signal is None:
|
||||
continue
|
||||
current = by_code.get(signal.code)
|
||||
if current is None or signal.score > current.score:
|
||||
by_code[signal.code] = signal
|
||||
return sorted(by_code.values(), key=lambda item: (item.score, item.code), reverse=True)
|
||||
|
||||
|
||||
def policy_refs_for_signal(signal_code: str) -> list[str]:
|
||||
signal_code = SIGNAL_ALIASES.get(str(signal_code or "").strip().lower(), signal_code)
|
||||
if signal_code not in POLICY_BOUND_SIGNALS:
|
||||
return []
|
||||
return [f"policy.{signal_code}"]
|
||||
|
||||
|
||||
def severity_from_score(score: int) -> str:
|
||||
normalized = max(0, min(100, int(score or 0)))
|
||||
if normalized >= 90:
|
||||
return "critical"
|
||||
if normalized >= 70:
|
||||
return "high"
|
||||
if normalized >= 45:
|
||||
return "medium"
|
||||
return "low"
|
||||
|
||||
|
||||
def _first_present(value: dict[str, Any], *keys: str) -> str:
|
||||
for key in keys:
|
||||
candidate = str(value.get(key) or "").strip()
|
||||
if candidate:
|
||||
return candidate
|
||||
return ""
|
||||
|
||||
|
||||
def _score_from_value(value: Any, *, severity: str) -> int:
|
||||
if value is None or value == "":
|
||||
return SEVERITY_SCORE.get(severity, SEVERITY_SCORE["medium"])
|
||||
try:
|
||||
numeric = Decimal(str(value))
|
||||
except Exception:
|
||||
return SEVERITY_SCORE.get(severity, SEVERITY_SCORE["medium"])
|
||||
if numeric <= Decimal("1"):
|
||||
numeric *= Decimal("100")
|
||||
return max(0, min(100, int(numeric.to_integral_value())))
|
||||
|
||||
|
||||
def _to_decimal(value: Any) -> Decimal:
|
||||
try:
|
||||
return Decimal(str(value))
|
||||
except Exception:
|
||||
return Decimal("0")
|
||||
162
server/src/app/algorithem/risk_graph/temporal.py
Normal file
162
server/src/app/algorithem/risk_graph/temporal.py
Normal file
@@ -0,0 +1,162 @@
|
||||
"""Temporal monitoring for risk graph relationship changes."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from collections import Counter, defaultdict
|
||||
from dataclasses import dataclass, field
|
||||
from typing import Any
|
||||
|
||||
from .models import RiskGraphEdge
|
||||
|
||||
|
||||
@dataclass(slots=True)
|
||||
class TemporalRiskGraphChange:
|
||||
change_type: str
|
||||
source_key: str
|
||||
target_key: str
|
||||
edge_type: str
|
||||
metadata: dict[str, Any] = field(default_factory=dict)
|
||||
|
||||
def as_dict(self) -> dict[str, Any]:
|
||||
return {
|
||||
"change_type": self.change_type,
|
||||
"source_key": self.source_key,
|
||||
"target_key": self.target_key,
|
||||
"edge_type": self.edge_type,
|
||||
"metadata": dict(self.metadata),
|
||||
}
|
||||
|
||||
|
||||
@dataclass(slots=True)
|
||||
class TemporalRiskGraphSnapshotDiff:
|
||||
changes: list[TemporalRiskGraphChange]
|
||||
edge_type_delta: dict[str, int]
|
||||
|
||||
def as_dict(self) -> dict[str, Any]:
|
||||
return {
|
||||
"changes": [item.as_dict() for item in self.changes],
|
||||
"edge_type_delta": dict(self.edge_type_delta),
|
||||
}
|
||||
|
||||
|
||||
class TemporalRiskGraphMonitor:
|
||||
def monitor(
|
||||
self,
|
||||
previous_edges: list[RiskGraphEdge],
|
||||
current_edges: list[RiskGraphEdge],
|
||||
*,
|
||||
risk_node_keys: set[str] | None = None,
|
||||
) -> TemporalRiskGraphSnapshotDiff:
|
||||
previous = {edge.edge_key(): edge for edge in previous_edges}
|
||||
current = {edge.edge_key(): edge for edge in current_edges}
|
||||
risk_keys = set(risk_node_keys or set())
|
||||
|
||||
changes: list[TemporalRiskGraphChange] = []
|
||||
for key, edge in current.items():
|
||||
if key not in previous:
|
||||
changes.append(_change("relationship_added", edge))
|
||||
if edge.source_key in risk_keys or edge.target_key in risk_keys:
|
||||
changes.append(_change("risk_propagation", edge))
|
||||
for key, edge in previous.items():
|
||||
if key not in current:
|
||||
changes.append(_change("relationship_removed", edge))
|
||||
|
||||
changes.extend(_relationship_volume_changes(previous_edges, current_edges))
|
||||
changes.extend(_target_migrations(previous_edges, current_edges))
|
||||
return TemporalRiskGraphSnapshotDiff(
|
||||
changes=changes,
|
||||
edge_type_delta=_edge_type_delta(previous_edges, current_edges),
|
||||
)
|
||||
|
||||
|
||||
def _change(change_type: str, edge: RiskGraphEdge, **metadata: Any) -> TemporalRiskGraphChange:
|
||||
return TemporalRiskGraphChange(
|
||||
change_type=change_type,
|
||||
source_key=edge.source_key,
|
||||
target_key=edge.target_key,
|
||||
edge_type=edge.edge_type,
|
||||
metadata=metadata,
|
||||
)
|
||||
|
||||
|
||||
def _edge_type_delta(
|
||||
previous_edges: list[RiskGraphEdge],
|
||||
current_edges: list[RiskGraphEdge],
|
||||
) -> dict[str, int]:
|
||||
previous_counts = Counter(edge.edge_type for edge in previous_edges)
|
||||
current_counts = Counter(edge.edge_type for edge in current_edges)
|
||||
edge_types = set(previous_counts) | set(current_counts)
|
||||
return {
|
||||
edge_type: current_counts.get(edge_type, 0) - previous_counts.get(edge_type, 0)
|
||||
for edge_type in sorted(edge_types)
|
||||
}
|
||||
|
||||
|
||||
def _relationship_volume_changes(
|
||||
previous_edges: list[RiskGraphEdge],
|
||||
current_edges: list[RiskGraphEdge],
|
||||
) -> list[TemporalRiskGraphChange]:
|
||||
changes: list[TemporalRiskGraphChange] = []
|
||||
previous_counts = Counter(edge.edge_type for edge in previous_edges)
|
||||
current_by_type: dict[str, list[RiskGraphEdge]] = defaultdict(list)
|
||||
for edge in current_edges:
|
||||
current_by_type[edge.edge_type].append(edge)
|
||||
for edge_type, current_group in current_by_type.items():
|
||||
previous_count = previous_counts.get(edge_type, 0)
|
||||
current_count = len(current_group)
|
||||
if current_count >= 3 and current_count >= max(1, previous_count) * 2:
|
||||
changes.append(
|
||||
_change(
|
||||
"relationship_surge",
|
||||
current_group[0],
|
||||
previous_count=previous_count,
|
||||
current_count=current_count,
|
||||
)
|
||||
)
|
||||
previous_by_type: dict[str, list[RiskGraphEdge]] = defaultdict(list)
|
||||
for edge in previous_edges:
|
||||
previous_by_type[edge.edge_type].append(edge)
|
||||
current_counts = Counter(edge.edge_type for edge in current_edges)
|
||||
for edge_type, previous_group in previous_by_type.items():
|
||||
if len(previous_group) >= 3 and current_counts.get(edge_type, 0) == 0:
|
||||
changes.append(
|
||||
_change(
|
||||
"relationship_disappeared",
|
||||
previous_group[0],
|
||||
previous_count=len(previous_group),
|
||||
current_count=0,
|
||||
)
|
||||
)
|
||||
return changes
|
||||
|
||||
|
||||
def _target_migrations(
|
||||
previous_edges: list[RiskGraphEdge],
|
||||
current_edges: list[RiskGraphEdge],
|
||||
) -> list[TemporalRiskGraphChange]:
|
||||
previous_targets: dict[tuple[str, str], set[str]] = defaultdict(set)
|
||||
current_targets: dict[tuple[str, str], set[str]] = defaultdict(set)
|
||||
for edge in previous_edges:
|
||||
previous_targets[(edge.source_key, edge.edge_type)].add(edge.target_key)
|
||||
for edge in current_edges:
|
||||
current_targets[(edge.source_key, edge.edge_type)].add(edge.target_key)
|
||||
|
||||
changes: list[TemporalRiskGraphChange] = []
|
||||
for key, current_target_set in current_targets.items():
|
||||
previous_target_set = previous_targets.get(key, set())
|
||||
if previous_target_set and current_target_set != previous_target_set:
|
||||
source_key, edge_type = key
|
||||
target_key = sorted(current_target_set - previous_target_set or current_target_set)[0]
|
||||
changes.append(
|
||||
TemporalRiskGraphChange(
|
||||
change_type="target_migration",
|
||||
source_key=source_key,
|
||||
target_key=target_key,
|
||||
edge_type=edge_type,
|
||||
metadata={
|
||||
"previous_targets": sorted(previous_target_set),
|
||||
"current_targets": sorted(current_target_set),
|
||||
},
|
||||
)
|
||||
)
|
||||
return changes
|
||||
103
server/src/app/api/v1/endpoints/agent_asset_risk_rules.py
Normal file
103
server/src/app/api/v1/endpoints/agent_asset_risk_rules.py
Normal file
@@ -0,0 +1,103 @@
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import Annotated, NoReturn
|
||||
|
||||
from fastapi import APIRouter, Depends, Header, HTTPException, status
|
||||
from sqlalchemy.orm import Session
|
||||
|
||||
from app.api.deps import (
|
||||
CurrentUserContext,
|
||||
get_db,
|
||||
require_rule_editor_user,
|
||||
)
|
||||
from app.schemas.agent_asset import (
|
||||
AgentAssetRead,
|
||||
AgentAssetRiskRuleDraftUpdate,
|
||||
AgentAssetRiskRuleRevisionCreate,
|
||||
)
|
||||
from app.services.agent_asset_risk_rule_revision import AgentAssetRiskRuleRevisionService
|
||||
from app.services.agent_assets import AgentAssetService
|
||||
|
||||
router = APIRouter(prefix="/agent-assets")
|
||||
DbSession = Annotated[Session, Depends(get_db)]
|
||||
ActorHeader = Annotated[
|
||||
str | None,
|
||||
Header(description="审计操作人。未传时使用当前登录用户名称。"),
|
||||
]
|
||||
RequestIdHeader = Annotated[
|
||||
str | None,
|
||||
Header(description="外部请求 ID，用于串联审计日志和上游调用链。"),
|
||||
]
|
||||
RuleEditorUser = Annotated[CurrentUserContext, Depends(require_rule_editor_user)]
|
||||
|
||||
|
||||
def _handle_asset_error(exc: Exception) -> NoReturn:
|
||||
if isinstance(exc, (LookupError, FileNotFoundError)):
|
||||
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(exc)) from exc
|
||||
if isinstance(exc, (PermissionError, ValueError)):
|
||||
raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(exc)) from exc
|
||||
raise exc
|
||||
|
||||
|
||||
def _actor_name(current_user: CurrentUserContext, x_actor: str | None) -> str:
|
||||
return (x_actor or current_user.name or current_user.username or "system").strip() or "system"
|
||||
|
||||
|
||||
def _read_asset(db: Session, asset_id: str) -> AgentAssetRead:
|
||||
asset = AgentAssetService(db).get_asset(asset_id)
|
||||
if asset is None:
|
||||
raise LookupError("Asset not found")
|
||||
return asset
|
||||
|
||||
|
||||
@router.patch(
|
||||
"/{asset_id}/risk-rules/draft",
|
||||
response_model=AgentAssetRead,
|
||||
summary="编辑未上线风险规则草稿",
|
||||
description="仅允许编辑从未上线的自然语言风险规则草稿或生成失败规则，不直接覆盖已上线版本。",
|
||||
)
|
||||
def update_risk_rule_draft(
|
||||
asset_id: str,
|
||||
payload: AgentAssetRiskRuleDraftUpdate,
|
||||
current_user: RuleEditorUser,
|
||||
db: DbSession,
|
||||
x_actor: ActorHeader = None,
|
||||
x_request_id: RequestIdHeader = None,
|
||||
) -> AgentAssetRead:
|
||||
try:
|
||||
AgentAssetRiskRuleRevisionService(db).update_unpublished_draft(
|
||||
asset_id,
|
||||
payload,
|
||||
actor=_actor_name(current_user, x_actor),
|
||||
request_id=x_request_id,
|
||||
)
|
||||
return _read_asset(db, asset_id)
|
||||
except Exception as exc:
|
||||
_handle_asset_error(exc)
|
||||
|
||||
|
||||
@router.post(
|
||||
"/{asset_id}/risk-rules/revisions",
|
||||
response_model=AgentAssetRead,
|
||||
status_code=status.HTTP_201_CREATED,
|
||||
summary="创建已上线风险规则修订草稿",
|
||||
description="为已上线或已下线的自然语言风险规则创建修订草稿，保留当前生效版本不变。",
|
||||
)
|
||||
def create_risk_rule_revision(
|
||||
asset_id: str,
|
||||
payload: AgentAssetRiskRuleRevisionCreate,
|
||||
current_user: RuleEditorUser,
|
||||
db: DbSession,
|
||||
x_actor: ActorHeader = None,
|
||||
x_request_id: RequestIdHeader = None,
|
||||
) -> AgentAssetRead:
|
||||
try:
|
||||
AgentAssetRiskRuleRevisionService(db).create_revision_draft(
|
||||
asset_id,
|
||||
payload,
|
||||
actor=_actor_name(current_user, x_actor),
|
||||
request_id=x_request_id,
|
||||
)
|
||||
return _read_asset(db, asset_id)
|
||||
except Exception as exc:
|
||||
_handle_asset_error(exc)
|
||||
47
server/src/app/api/v1/endpoints/agent_feedback.py
Normal file
47
server/src/app/api/v1/endpoints/agent_feedback.py
Normal file
@@ -0,0 +1,47 @@
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import Annotated
|
||||
|
||||
from fastapi import APIRouter, Depends, Query, status
|
||||
from sqlalchemy.orm import Session
|
||||
|
||||
from app.api.deps import get_db
|
||||
from app.schemas.agent_feedback import (
|
||||
AgentFeedbackCreate,
|
||||
AgentFeedbackRead,
|
||||
AgentFeedbackSummaryRead,
|
||||
)
|
||||
from app.services.agent_feedback import AgentFeedbackService
|
||||
|
||||
router = APIRouter(prefix="/agent-feedback")
|
||||
DbSession = Annotated[Session, Depends(get_db)]
|
||||
|
||||
|
||||
@router.post(
|
||||
"",
|
||||
response_model=AgentFeedbackRead,
|
||||
status_code=status.HTTP_201_CREATED,
|
||||
summary="记录 Agent 操作评价",
|
||||
description="记录用户对一次智能体处理结果的 1-5 星评价和低分原因。",
|
||||
)
|
||||
def create_agent_feedback(payload: AgentFeedbackCreate, db: DbSession) -> AgentFeedbackRead:
|
||||
return AgentFeedbackService(db).create_feedback(payload)
|
||||
|
||||
|
||||
@router.get(
|
||||
"/summary",
|
||||
response_model=AgentFeedbackSummaryRead,
|
||||
summary="查询 Agent 操作评价统计",
|
||||
description="按最近反馈记录汇总评分分布、低分数量和低分原因。",
|
||||
)
|
||||
def summarize_agent_feedback(
|
||||
db: DbSession,
|
||||
agent: Annotated[str | None, Query(description="Agent 名称筛选。")] = None,
|
||||
session_type: Annotated[str | None, Query(description="会话类型筛选。")] = None,
|
||||
limit: Annotated[int, Query(ge=1, le=500, description="统计最近记录数。")] = 200,
|
||||
) -> AgentFeedbackSummaryRead:
|
||||
return AgentFeedbackService(db).summarize_feedback(
|
||||
agent=agent,
|
||||
session_type=session_type,
|
||||
limit=limit,
|
||||
)
|
||||
@@ -6,7 +6,7 @@ from fastapi import APIRouter, Depends, HTTPException, Query, status
|
||||
from sqlalchemy.orm import Session
|
||||
|
||||
from app.api.deps import get_db
|
||||
from app.schemas.agent_run import AgentRunRead
|
||||
from app.schemas.agent_run import AgentRunRead, AgentRunStatsRead
|
||||
from app.schemas.common import ErrorResponse
|
||||
from app.services.agent_runs import AgentRunService
|
||||
|
||||
@@ -44,6 +44,39 @@ def list_agent_runs(
|
||||
)
|
||||
|
||||
|
||||
@router.get(
|
||||
"/summary",
|
||||
response_model=AgentRunStatsRead,
|
||||
summary="查询 Agent 运行统计",
|
||||
description="按最近运行记录实时汇总 Agent、工具调用、模型调用和错误统计。",
|
||||
)
|
||||
def summarize_agent_runs(
|
||||
db: DbSession,
|
||||
agent: Annotated[
|
||||
str | None,
|
||||
Query(description="Agent 名称筛选。"),
|
||||
] = None,
|
||||
status_value: Annotated[
|
||||
str | None,
|
||||
Query(alias="status", description="运行状态筛选。"),
|
||||
] = None,
|
||||
source: Annotated[
|
||||
str | None,
|
||||
Query(description="运行来源筛选。"),
|
||||
] = None,
|
||||
limit: Annotated[
|
||||
int,
|
||||
Query(ge=1, le=500, description="统计最近记录数。"),
|
||||
] = 200,
|
||||
) -> AgentRunStatsRead:
|
||||
return AgentRunService(db).summarize_runs(
|
||||
agent=agent,
|
||||
status=status_value,
|
||||
source=source,
|
||||
limit=limit,
|
||||
)
|
||||
|
||||
|
||||
@router.get(
|
||||
"/{run_id}",
|
||||
response_model=AgentRunRead,
|
||||
|
||||
55
server/src/app/api/v1/endpoints/analytics.py
Normal file
55
server/src/app/api/v1/endpoints/analytics.py
Normal file
@@ -0,0 +1,55 @@
|
||||
from __future__ import annotations
|
||||
|
||||
from datetime import date
|
||||
from typing import Annotated
|
||||
|
||||
from fastapi import APIRouter, Depends, Query
|
||||
from sqlalchemy.orm import Session
|
||||
|
||||
from app.api.deps import get_db
|
||||
from app.schemas.finance_dashboard import FinanceDashboardRead
|
||||
from app.schemas.system_dashboard import SystemDashboardRead
|
||||
from app.services.finance_dashboard import FinanceDashboardService
|
||||
from app.services.system_dashboard import SystemDashboardService
|
||||
|
||||
router = APIRouter(prefix="/analytics")
|
||||
DbSession = Annotated[Session, Depends(get_db)]
|
||||
|
||||
|
||||
@router.get(
|
||||
"/system-dashboard",
|
||||
response_model=SystemDashboardRead,
|
||||
summary="查询系统看板真实指标",
|
||||
description="基于 Agent 运行、工具调用、用户会话和反馈数据聚合系统看板指标。",
|
||||
)
|
||||
def get_system_dashboard(
|
||||
db: DbSession,
|
||||
days: Annotated[
|
||||
int,
|
||||
Query(ge=1, le=30, description="统计窗口天数。"),
|
||||
] = 7,
|
||||
) -> SystemDashboardRead:
|
||||
return SystemDashboardService(db).build_dashboard(days=days)
|
||||
|
||||
|
||||
@router.get(
|
||||
"/finance-dashboard",
|
||||
response_model=FinanceDashboardRead,
|
||||
summary="查询财务看板真实指标",
|
||||
description="基于报销单据、风险观察和预算池数据聚合财务看板指标。",
|
||||
)
|
||||
def get_finance_dashboard(
|
||||
db: DbSession,
|
||||
range_key: Annotated[str, Query(max_length=30, description="顶部时间范围。")] = "近10日",
|
||||
start_date: Annotated[date | None, Query(description="自定义开始日期。")] = None,
|
||||
end_date: Annotated[date | None, Query(description="自定义结束日期。")] = None,
|
||||
trend_range: Annotated[str, Query(max_length=30, description="趋势图时间范围。")] = "近12天",
|
||||
department_range: Annotated[str, Query(max_length=30, description="部门排行时间范围。")] = "本月",
|
||||
) -> FinanceDashboardRead:
|
||||
return FinanceDashboardService(db).build_dashboard(
|
||||
range_key=range_key,
|
||||
start_date=start_date,
|
||||
end_date=end_date,
|
||||
trend_range=trend_range,
|
||||
department_range=department_range,
|
||||
)
|
||||
@@ -6,9 +6,15 @@ from fastapi import APIRouter, Depends, HTTPException, status
|
||||
from sqlalchemy.orm import Session
|
||||
|
||||
from app.api.deps import get_db
|
||||
from app.schemas.auth import LoginRequest, LoginResponse
|
||||
from app.schemas.auth import (
|
||||
LoginRequest,
|
||||
LoginResponse,
|
||||
SessionFinishRequest,
|
||||
SessionFinishResponse,
|
||||
)
|
||||
from app.schemas.common import ErrorResponse
|
||||
from app.services.auth import AuthService
|
||||
from app.services.user_session_metrics import UserSessionMetricService
|
||||
|
||||
router = APIRouter(prefix="/auth")
|
||||
DbSession = Annotated[Session, Depends(get_db)]
|
||||
@@ -31,3 +37,32 @@ def login(payload: LoginRequest, db: DbSession) -> LoginResponse:
|
||||
return AuthService(db).login(payload)
|
||||
except ValueError as exc:
|
||||
raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail=str(exc)) from exc
|
||||
|
||||
|
||||
@router.post(
|
||||
"/sessions/{session_id}/finish",
|
||||
response_model=SessionFinishResponse,
|
||||
summary="结算用户在线会话",
|
||||
)
|
||||
def finish_session(
|
||||
session_id: str,
|
||||
payload: SessionFinishRequest,
|
||||
db: DbSession,
|
||||
) -> SessionFinishResponse:
|
||||
session = UserSessionMetricService(db).finish_session(
|
||||
session_id=session_id,
|
||||
reason=payload.reason,
|
||||
last_activity_at=payload.lastActivityAt,
|
||||
activity_event_count=payload.activityEventCount,
|
||||
event={"page_path": payload.pagePath},
|
||||
)
|
||||
if session is None:
|
||||
return SessionFinishResponse(
|
||||
detail="会话不存在或已被清理。",
|
||||
sessionId=session_id,
|
||||
durationMs=0,
|
||||
)
|
||||
return SessionFinishResponse(
|
||||
sessionId=session.session_id,
|
||||
durationMs=int(session.duration_ms or 0),
|
||||
)
|
||||
|
||||
@@ -124,7 +124,7 @@ def _missing_usage_duration_metric(latest: EmployeeProfileLatestRead) -> bool:
|
||||
|
||||
for profile in latest.profiles:
|
||||
if profile.profile_type == "ai_usage":
|
||||
return "ai_run_duration_ms" not in profile.metrics
|
||||
return "usage_duration_ms" not in profile.metrics
|
||||
return False
|
||||
|
||||
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user