feat: 扩展风险规则体系、审批动态路由与预算中心列表化改造

- 新增 25+ 条风险规则(预算/报销/申请/通用类),完善风险规则模拟与反馈发布机制
- 引入费用审批动态路由、平台风险分级、预审与风险阶段管理
- 预算中心列表化改造,优化票据夹仪表盘与数字员工工作看板
- 新增 Hermes 风险线索收集器、Agent 链路追踪中心
- 扩展数字员工能力库(18 个领域 Skill)与交通费用自动预估
- 完善报销申请快速预览、权限控制与前端测试覆盖
This commit is contained in:
caoxiaozhu
2026-06-01 17:07:14 +08:00
parent 7989f3a159
commit 92444e7eae
285 changed files with 25075 additions and 2986 deletions

View File

@@ -0,0 +1,132 @@
# Agent链路追踪中心 概念文档
## 功能一句话
为 Orchestrator 全链路运行提供统一 trace 采集、查询和前端回放入口,让管理员能按 `run_id``conversation_id` 还原一次 Agent 对话从意图识别到最终回复的全过程。
## 背景与问题
- 当前现状:系统已有 `agent_runs``agent_tool_calls``semantic_parse_logs` 和对话消息,但它们分散在运行记录、工具调用、语义解析与系统日志中。
- 用户痛点:线上 Agent 回答异常时,只能看局部日志或 Hermes 工作记录,难以判断问题出在意图路由、知识检索、规则引擎、数字员工任务还是回复生成。
- 业务影响Agent 链路越长,排障成本越高;没有可重放视图会影响交付、演示和运维可信度。
## 目标与非目标
### 目标
- [G1] 后端沉淀统一的 Agent trace 事件模型,按运行顺序记录关键阶段输入、输出、状态、耗时和错误。
- [G2] 提供 trace 查询接口,支持按 `run_id` 查看单次运行,按 `conversation_id` 查看多轮会话链路。
- [G3] 前端新增 Agent Trace Center 入口,展示运行时间线、工具调用、语义解析、路由上下文和最终回复。
- [G4] 保留现有 Agent Run / ToolCall 数据结构,避免破坏数字员工工作记录和系统日志页面。
### 非目标
- [NG1] 本轮不做重新执行真实业务动作的“调试重跑”,只做历史重放。
- [NG2] 本轮不接入 OpenTelemetry、Jaeger 等外部分布式追踪系统。
- [NG3] 本轮不改造总账、预算、报销审批等业务语义。
- [NG4] 本轮不做跨服务链路采样策略和海量归档策略。
## 用户与场景
- 目标用户系统管理员、财务系统运维、Agent 能力开发者、实施顾问。
- 使用入口:系统日志详情、数字员工工作记录、报销助手消息中的 `run_id`、新增 Trace Center 页面。
- 核心场景:
- 管理员打开某次异常回复,查看每一步输入输出和耗时。
- 实施人员按会话查看多轮上下文,判断上下文是否被错误继承。
- 开发者定位工具调用失败、语义识别降级或路由选错 Agent 的原因。
- 异常场景:
- 运行失败但没有工具调用时,仍展示已记录的 orchestration 阶段。
- 旧数据没有 trace event 时,接口回退展示 `agent_runs``semantic_parse``tool_calls`
## 功能能力
- [C1] 输入能力:接收 `run_id``conversation_id`、Agent、状态、来源、关键字等查询条件。
- [C2] 采集能力:记录 `received``context_hydrated``semantic_parsed``agent_selected``capability_selected``tool_invoked``response_built``conversation_updated``failed` 等事件。
- [C3] 输出能力:返回 trace 摘要、事件时间线、工具调用、语义解析、路由 JSON、最终回复和关联会话消息。
- [C4] 状态与权限:复用现有登录与页面权限,管理员/可访问设置页用户可查看全量 trace。
- [C5] 边界与降级:旧运行没有 trace events 时,按现有 run/tool/semantic 数据合成最小时间线。
## 方案设计
### 前端
- 页面/组件:
- 新增 `AgentTraceCenterView` 或设置页内 Trace Center 分区。
- 新增 trace 详情组件,复用现有日志详情的直角企业级视觉。
- 从日志详情、数字员工工作记录、报销助手操作反馈中可跳转到 trace 详情。
- 交互状态:
- 列表支持关键字、状态、Agent、来源筛选。
- 详情展示左侧时间线、右侧输入输出 JSON、顶部摘要。
- 支持加载、空态、错误态和刷新。
- 展示规则:
- 事件按 `started_at``sequence` 升序展示。
- 失败事件突出错误信息。
- 大 JSON 使用可滚动代码块,避免撑破页面。
### 后端
- 接口/服务:
- `GET /api/v1/agent-traces`:查询 trace 列表。
- `GET /api/v1/agent-traces/{run_id}`:读取单次运行 trace。
- `GET /api/v1/agent-traces/conversations/{conversation_id}`:读取会话 trace。
- 权限与校验:
- 复用当前 API 依赖和系统登录态。
- 不允许通过 trace 接口修改业务数据。
- 持久化:
- 新增 `agent_trace_events` 表。
- 通过 `AgentTraceService` 封装记录、查询、合成旧数据时间线。
### 算法与规则
- 规则输入Agent 运行阶段、工具调用结果、语义解析结果和会话消息。
- 规则流程:
- 采集阶段按固定事件名记录。
- 查询阶段按事件序列合并 run、semantic、tool、conversation。
- 无事件时从历史 run 数据合成 fallback timeline。
- 结果解释:
- 每个事件输出 `title``summary``status``duration_ms``input_json``output_json``error_message`
## 算法与公式
当前功能不涉及评分、预算或风控公式,只涉及耗时统计:
$$
duration\_ms = finished\_at - started\_at
$$
变量说明:
- $duration\_ms$:阶段耗时,单位毫秒。
- $finished\_at$:阶段结束时间。
- $started\_at$:阶段开始时间。
## 测试方案
- 单元测试:覆盖 `AgentTraceService` 记录事件、查询详情、旧 run fallback 时间线。
- 接口测试:覆盖 trace 列表、单 run 详情、会话详情。
- 前端交互测试:覆盖 trace 数据归一化、状态文案、空态和错误态。
- 端到端测试:通过一次 Orchestrator 用户消息生成 `run_id`,验证详情接口能返回语义解析、路由和至少一个事件。
- 回归测试:确认原 `agent-runs` 接口、数字员工工作记录、系统日志详情不破坏。
- 手工验证:在浏览器打开 Trace Center检查列表、详情和 JSON 展示。
## 指标与验收
- [A1] 功能验收:一次 Orchestrator 调用后,能通过 `run_id` 查询到完整 trace 详情。
- [A2] 性能指标:单次 trace 详情查询在常规数据量下不引入明显慢查询;默认列表限制数量。
- [A3] 质量指标:后端定向测试在 Docker `x-financial-main` 容器内 60s 超时内通过。
- [A4] 安全/权限指标trace 接口只读,不触发业务动作或副作用。
- [A5] 可观测性:失败运行也能看到最后成功事件和失败事件。
## 风险与开放问题
- 风险:当前工作树已有大量未提交改动,本轮实现必须避免覆盖既有业务改动。
- 已处理依赖:新增 trace 模型已纳入 `Base` 导入,`AgentTraceService.ensure_storage_ready()` 会按需创建 trace 事件表。
- 待确认:后续是否需要接 OpenTelemetry、跨容器 trace 或长期归档策略。
- 降级策略:没有 trace event 的旧 run 通过 `semantic_parse``tool_calls``route_json` 合成只读时间线。
## 本轮实现记录
- 后端已完成 `AgentTraceEvent``AgentTraceService``/api/v1/agent-traces` 只读接口。
- Orchestrator 已在接收请求、会话补全、语义识别、路由、工具调用、会话写回、最终回复和失败路径写入 trace event。
- 前端已在系统设置中新增 Agent Trace Center并从日志详情、数字员工工作记录跳转到指定 `run_id`
- 本轮保持非目标不变:不做真实业务重跑、不接 OpenTelemetry、不处理 GL/总账体系和前端统一状态管理。

View File

@@ -0,0 +1,55 @@
# Agent链路追踪中心 开发 TODO
## 使用规则
- 每个 TODO 必须对应 `CONCEPT.md` 中的目标、能力或验收点。
- 只有完成并验证后,才能把 `[ ]` 改成 `[x]`
- 勾选时在任务后补充简短证据,例如文件、接口、命令或验证结果。
- 如果需求发生变化,先更新 `CONCEPT.md`,再调整本 TODO。
## 1. 调研与边界
- [x] [CONCEPT: 背景与问题] 阅读相关页面、接口、服务、测试和历史文档,记录当前实现事实。证据:已确认 `agent_runs``agent_tool_calls``semantic_parse_logs``LogDetailView``DigitalEmployeeWorkRecords` 现状。
- [x] [CONCEPT: 目标与非目标] 确认本轮开发范围,写清楚不做项。证据:`CONCEPT.md` 明确只做历史重放,不做调试重跑和 OpenTelemetry。
- [x] [CONCEPT: 风险与开放问题] 标记无法立即确认的依赖、风险和假设。证据:`CONCEPT.md` 风险章节记录脏工作树和数据库初始化依赖。
## 2. 契约与设计
- [x] [CONCEPT: 功能能力] 定义输入、输出、状态、权限和边界条件。证据:`CONCEPT.md` 功能能力章节。
- [x] [CONCEPT: 方案设计] 明确前端、后端、算法、数据的职责边界。证据:`CONCEPT.md` 方案设计章节。
- [x] [CONCEPT: 算法与公式] 补全耗时公式和变量解释。证据:`CONCEPT.md` 算法与公式章节。
- [x] [CONCEPT: 指标与验收] 把验收标准转成可验证的检查点。证据:`CONCEPT.md` 指标与验收章节。
## 3. 后端实现
- [x] [CONCEPT: 后端] 新增 trace 事件模型、schema、repository/service。证据`AgentTraceEvent``agent_trace.py``AgentTraceService`
- [x] [CONCEPT: 后端] 新增 `agent-traces` 只读接口和路由注册。证据:`agent_traces.py` endpoint 与 `router.py` 注册。
- [x] [CONCEPT: 后端] 在 Orchestrator 关键节点写入 trace event。证据`orchestrator.py` 记录接收、会话、语义、路由、回复、失败事件;`orchestrator_execution.py` 记录工具调用事件。
- [x] [CONCEPT: 数据] 实现旧 run fallback 时间线,避免旧数据详情为空。证据:`AgentTraceService.get_trace()` 在无事件时由 `AgentRun``SemanticParseLog``AgentToolCall` 合成只读时间线。
## 4. 算法/规则实现
- [x] [CONCEPT: 算法与规则] 实现 trace 事件排序、耗时计算和状态归一化。证据:`AgentTraceService._next_sequence()``_resolve_duration_ms()``agentTraceViewModel.js`
- [x] [CONCEPT: 结果解释] 输出可读事件标题、摘要、输入输出和错误信息。证据Trace event schema 与 `AgentTraceCenterView.vue` 详情面板。
## 5. 前端实现
- [x] [CONCEPT: 前端] 新增 trace 服务 API 和数据归一化工具。证据:`agentTraces.js``agentTraceViewModel.js`
- [x] [CONCEPT: 前端] 新增 Trace Center 列表与详情视图。证据:`AgentTraceCenterView.vue`
- [x] [CONCEPT: 前端] 从现有日志详情和工作记录补充 trace 跳转入口。证据:`LogDetailView.vue``DigitalEmployeeWorkRecords.vue`
- [x] [CONCEPT: 前端] 实现加载、空态、错误态和刷新。证据:`AgentTraceCenterView.vue` 列表/详情状态与刷新按钮。
- [x] [CONCEPT: 前端] 对齐现有企业级直角、低饱和、密集信息风格。证据:`agent-trace-center-view.css` 使用面板、表格、状态徽标和紧凑信息布局。
## 6. 测试与验证
- [x] [CONCEPT: 测试方案] 补充后端 service/API 定向测试。证据:`test_agent_trace_service.py` 覆盖事件记录、fallback、接口列表和详情。
- [x] [CONCEPT: 测试方案] 补充前端数据归一化测试或可构建验证。证据:`npm.cmd --prefix web run build` 通过。
- [x] [CONCEPT: 测试方案] 在 60s 超时内运行 Docker 后端定向验证。证据:`docker exec ... pytest -q server/tests/test_agent_trace_service.py server/tests/test_agent_runs_service.py`7 passed。
- [x] [CONCEPT: 测试方案] 运行 `npm.cmd --prefix web run build`。证据Vite build 成功。
- [x] [CONCEPT: 指标与验收] 记录验证命令、结果和未覆盖风险。证据:后端测试 7 passed、Vite build 成功、重启后 `/api/v1/agent-traces/{run_id}` live 返回 8 个 fallback 事件;浏览器插件后续不可用,未完成最终截图巡检。
## 7. 文档收尾
- [x] [CONCEPT: 指标与验收] 回看所有验收点,确认均有实现或验证证据。证据:后端 service/API 测试、前端构建、入口接入均已完成。
- [x] [CONCEPT: 风险与开放问题] 更新剩余风险、后续任务和明确不做项。证据:`CONCEPT.md` 保留 OpenTelemetry、跨容器 trace、长期归档为后续待定。
- [x] [CONCEPT: 功能一句话] 确认最终实现没有偏离原始目标。证据:本轮只做 Agent Trace Center未处理 GL/前端状态管理两项待定问题。

View File

@@ -4,7 +4,9 @@
## 1. 功能一句话
以数字员工为后台执行入口,持续把财务业务数据转成行为画像、制度语义和风险观察,再通过图谱证据链、单据详情和风险看板提供可解释的风险判断。
以数字员工为后台分析入口,持续把财务业务数据转成行为画像、制度语义和风险观察,再通过图谱证据链、单据详情和风险看板提供可解释的风险判断。
规则中心、审批和报销主流程仍由外层智能体流程负责调度;数字员工只消费事实、规则命中和反馈结果,生成后台分析、报告、知识库材料和待复核线索。
## 2. 背景与问题
@@ -16,7 +18,7 @@ X-Financial 已经具备费用申请、报销、审批、规则中心、知识
- 分析看板如果只从散表拼统计图,会成为展示型页面,不能反映算法效果。
- 数字员工如果只做定时任务,会变成调度工具,不能形成核心壁垒。
本方案把核心能力定义为“财务行为图谱风险引擎”。它不是单一模型,而是一套闭环:事件沉淀、实体建图、画像基线、风险推理、人工反馈、规则发现
本方案把核心能力定义为“财务行为图谱风险引擎”。它不是单一模型,而是一套闭环:事件沉淀、实体建图、画像基线、风险推理、人工反馈、待复核线索归集
## 3. 核心判断
@@ -78,7 +80,7 @@ X-Financial 已经具备费用申请、报销、审批、规则中心、知识
算法版本
```
这会形成自有训练集、评测集和规则优化样本。竞品能复制算法框架,但复制不了这些被真实审批和财务人员校准过的样本。
这会形成自有训练集、评测集和规则执行校准样本。竞品能复制算法框架,但复制不了这些被真实审批和财务人员校准过的样本。
第四层壁垒:人机共审行为数据。
@@ -92,7 +94,7 @@ X-Financial 已经具备费用申请、报销、审批、规则中心、知识
补件
升级审批
标记误报
生成候选规则
归集待复核线索
```
这些反馈会反向影响规则质量、抽审比例、自动化门控和数字员工能力考核。越使用越贴近企业自己的财务控制风格。
@@ -139,10 +141,10 @@ X-Financial 已经具备费用申请、报销、审批、规则中心、知识
### 4.2 非目标
- 第一版不做独立“大图谱中心”,避免做成展示型页面。
- 不让大模型直接决定风险等级,大模型只参与语义抽取、解释生成和候选规则发现
- 不让大模型直接决定风险等级,大模型只参与语义抽取、解释生成和事实线索整理;不参与规则生成、改写或发布
- 不用画像自动惩罚员工,不给员工永久贴标签。
- 不在员工技能详情中展示知识归集图谱;图谱结果只进入工作记录详情、单据风险详情或画像详情。
- 不让数字员工自动上线规则;规则候选必须经过管理员审核
- 不让数字员工生成、改写或自动上线规则;规则变更只能由管理员在规则中心维护
## 5. 用户与场景
@@ -178,7 +180,7 @@ X-Financial 已经具备费用申请、报销、审批、规则中心、知识
- 数字员工运行是否成功。
- 本次分析处理了多少数据、产出多少风险观察。
- 候选规则是否有足够证据。
- 待复核风险线索是否有足够事实和证据。
- 是否需要调整技能、规则、制度知识或调度配置。
### 5.4 管理层
@@ -201,7 +203,7 @@ X-Financial 已经具备费用申请、报销、审批、规则中心、知识
- 制度整理员工:把公司财务制度整理成条款、适用范围、费用类型、触发条件和引用关系。
- 风险扫描员工:定期扫描新增单据、票据、供应商、审批链和画像偏离,生成风险观察。
- 画像更新员工:定期更新员工、部门、供应商、费用类型画像和同类基线。
- 规则发现员工:从历史退回、误报、漏报、制度变化和高频异常中生成候选规则。
- 风险线索归集员工:从申请、报销、规则命中和人工反馈中归集待复核线索,不生成规则。
### 6.2 图谱体现方式
@@ -259,7 +261,7 @@ X-Financial 已经具备费用申请、报销、审批、规则中心、知识
- 风险分布:按部门、费用类型、风险类型、供应商、员工职级分布。
- 风险趋势7 天 / 30 天风险走势、高风险占比、重复触发趋势、处理完成率。
- 异常排行:风险最多部门、偏离基线最大员工、高频异常供应商、高频触发规则。
- 算法效果:规则命中数、图谱异常命中数、人工确认率、误报率、候选规则数。
- 算法效果:规则命中数、图谱异常命中数、人工确认率、误报率、待复核线索数。
风险看板必须从 `RiskObservation` 聚合,不直接从散表临时拼图表。
@@ -437,7 +439,7 @@ confirmed_by_feedback 由人工反馈确认
图谱引擎canonical node + whitelisted edge 构造证据路径
风险观察ontology fields + evidence path 输出可解释结论
风险看板:按 ontology scenario / expense_type / risk_signal 聚合
数字员工:只能产出本体可识别的候选风险信号和候选规则
数字员工:只能产出本体可识别的事实、规则命中、待复核风险线索和证据引用
```
当本体置信度不足时,风险图谱必须降级:
@@ -602,7 +604,7 @@ $$
### 8.4 人工反馈校准
人工反馈不直接覆盖算法,但会影响后续权重和候选规则优先级:
人工反馈不直接覆盖算法,但会影响后续权重和待复核线索优先级:
$$
confirmed\_rate = \frac{confirmed}{confirmed + false\_positive + ignored}

View File

@@ -43,7 +43,7 @@
- [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: 不可复制壁垒设计] 证据:`RiskObservationFeedback` 已通过兼容属性暴露 `decision/candidate_rule_source/confidence_score/escalation_target/supplement_required`,测试覆盖反馈来源元数据。
- [x] 设计算法回放集模型,绑定历史单据、本体版本、规则版本、算法版本和反馈标签。[CONCEPT: 不可复制壁垒设计] 证据:`replay.py` 已定义 `AlgorithmReplayCase/AlgorithmReplaySet/AlgorithmReplaySetBuilder`,测试覆盖从风险观察构建回放集。
## 3. 后端服务
@@ -98,7 +98,7 @@
- [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: 数字员工能力分层] 证据:数字员工任务与技能已注册为“风险线索归集”,`test_digital_employee_skill_catalog.py` 已锁定不输出候选规则或自动发布语义
- [x] 数字员工运行完成后写入处理范围、处理数量、风险观察数量和失败原因。[CONCEPT: 数字员工工作记录详情] 证据:`HermesScheduler` 已写入风险图谱巡检摘要,失败仍沿用执行日志 `error_trace`
- [x] 确认 UI 上继续使用“数字员工 / 员工技能 / 工作记录”等业务命名,不在普通用户界面暴露内部实现名。[CONCEPT: 用户与场景] 证据:`DigitalEmployeesView.vue` 页签文案为“员工技能 / 工作记录”,普通界面未展示内部 Hermes 名称。
@@ -125,16 +125,16 @@
- [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: 分析看板风险看板] 证据:风险看板已展示平均风险分、人工确认数、误报样本和待复核线索口径,规则/图谱来源通过来源分布体现。
- [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: 非目标] 证据:技能配置统一写入 `writes_rules=false``role_boundary``allowed_outputs`目录测试覆盖不再注册候选规则技能名或规则优化输出格式
- [x] 风险观察详情展示反馈历史和当前处理状态。[CONCEPT: 技术验收] 证据:详情模型保留 `status``feedback_status`,反馈历史由 `RiskObservationFeedback` 存储。
- [x] 风险看板展示人工确认率、误报率和候选规则数量。[CONCEPT: 分析看板风险看板] 证据:聚合接口已输出 `confirmation_rate``false_positive_rate`候选规则数待规则发现员工接入后补充
- [x] 风险看板展示人工确认率、误报率和待复核线索数量。[CONCEPT: 分析看板风险看板] 证据:聚合接口已输出 `confirmation_rate``false_positive_rate`待复核线索口径由风险观察与人工复核状态聚合
## 10. 测试与验证

View File

@@ -526,6 +526,32 @@ docker exec x-financial-main sh -lc "cd /app/server && pytest <target> --timeout
docker exec x-financial-main sh -lc "cd /app/web && npm run build"
```
### 本轮落地结果
已落地接口:
- `GET /agent-assets/risk-rules/templates`:返回预算、票据、差旅、招待、采购/AP、企业卡、通用模板分组包含默认自然语言、字段清单、附件要求和 DSL 样例。
- `PATCH /agent-assets/{asset_id}/risk-rules/draft`:编辑未上线风险规则草稿。
- `POST /agent-assets/{asset_id}/risk-rules/revisions`:为已上线规则创建修订草稿。
- `POST /agent-assets/{asset_id}/risk-rules/regenerate`:重新生成 DSL、流程图、风险评分和业务说明。
- `POST /agent-assets/{asset_id}/risk-rules/feedback``GET /agent-assets/{asset_id}/risk-rules/feedback`:记录和查看误判/漏判反馈。
关键文件:
- 后端模板库与契约:`risk_rule_template_catalog.py``agent_asset.py``agent_asset_risk_rules.py`
- 后端生成、修订、发布、反馈、仿真:`risk_rule_generation*``agent_asset_risk_rule_revision.py``agent_asset_risk_rule_regeneration.py``agent_asset_risk_rule_publish.py``agent_asset_risk_rule_feedback.py``agent_asset_risk_rule_simulation.py`
- 前端新建、详情、测试:`AuditRuleDialogs.vue``AuditJsonRiskRuleDetail.vue``RiskRuleFlowDiagram.vue``RiskRuleTestDialog.vue``auditViewDetailTopBar.js``useAuditRiskRuleActions.js``useAuditAssetData.js`
- 测试:`test_risk_rule_template_catalog.py``test_risk_rule_feedback.py``test_risk_rule_revision_endpoints.py``test_risk_rule_explainability.py``risk-rule-detail-experience.test.mjs`
已执行验证命令:
```bash
docker exec x-financial-main bash -lc "cd /app/server && timeout 60 /tmp/x-financial-server-venv/bin/python -m pytest tests/test_risk_rule_template_catalog.py tests/test_openapi_schema.py -q"
docker exec x-financial-main bash -lc "cd /app/server && timeout 60 /tmp/x-financial-server-venv/bin/python -m pytest tests/test_risk_rule_feedback.py tests/test_risk_rule_revision_endpoints.py tests/test_openapi_schema.py -q"
docker exec x-financial-main bash -lc "cd /app/web && timeout 60 node --test tests/risk-rule-detail-experience.test.mjs"
docker exec x-financial-main bash -lc "cd /app/web && timeout 60 npm run build"
```
## 指标与验收
- [A1] 新建复杂差旅规则后,详情页流程解释不能出现“检查是否包含风险关键词”这类错误表达。
@@ -544,3 +570,12 @@ docker exec x-financial-main sh -lc "cd /app/web && npm run build"
- 老规则没有 `semantic_plan``flow_model`,需要兼容展示并允许重新生成。
- 常见规则模板要避免写成定制逻辑。模板只能提供默认文本、字段和 DSL 样例,最终仍走通用生成链路。
当前仍需持续演进的点:
- 企业卡、采购/AP、预算场景的字段本体还偏少后续应补充企业卡交易流水、供应商、采购订单、合同、预算期间等字段。
- 复杂规则的准确性仍依赖 Hermes 语义计划质量,执行前必须继续保留 DSL validator、执行器 dry-run 和仿真测试。
- 模板库只作为规则编写入口的业务参考,不作为规则执行捷径;新增模板时必须同时提供 DSL 样例和 validator 测试。
## 实现确认
当前实现仍围绕“解释图和执行逻辑一致”推进:自然语言先经字段本体和语义计划形成受控 JSON DSL详情页流程图、文字流程解释、测试 trace、上线版本均围绕同一份 DSL 展示和执行,没有新增流程图编辑器或绕过规则执行器的判断链路。

View File

@@ -9,10 +9,10 @@
## 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: 非目标] 明确本期不做流程图编辑器,不增加拖拽、缩放、节点编辑能力。
- [x] [CONCEPT: 背景与问题] 梳理当前风险规则生成链路,记录 `risk_rule_generation.py``risk_rule_template_executor.py` 的真实调用关系。证据:`CONCEPT.md` 后端设计与本轮落地结果记录生成、DSL validator、执行器、流程图、仿真测试链路。
- [x] [CONCEPT: 前端设计] 梳理详情页、新建弹窗、测试弹窗当前字段来源,记录 `AuditRuleDialogs.vue``AuditJsonRiskRuleDetail.vue``RiskRuleTestDialog.vue` 的改造点。证据:`CONCEPT.md` 本轮落地结果列出三个组件及对应职责,`risk-rule-detail-experience.test.mjs` 覆盖关键接线。
- [x] [CONCEPT: 数据设计] 确认 `AgentAssetRead`、版本内容、`config_json` 中已有字段,确定 `semantic_plan``flow_model``flow_diagram_svg` 的落点。证据:`AgentAssetRead` 返回 `latest_test_summary`,版本 JSON metadata 保存 `semantic_plan`/`flow_model`/`flow_diagram_svg`,生成测试覆盖。
- [x] [CONCEPT: 非目标] 明确本期不做流程图编辑器,不增加拖拽、缩放、节点编辑能力。证据:`RiskRuleFlowDiagram.vue` 只渲染静态 SVG/文字说明,无编辑、拖拽、缩放入口;前端回归测试断言不存在 zoom 按钮。
## 2. 语义计划与 DSL 契约
@@ -26,7 +26,7 @@
- [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_semantics.py` 或解释层补齐语义计划解析与错误返回。证据:`risk_rule_generation_semantic_plan.py` 解析 `{ semantic_plan, dsl }` 包装并保留 `metadata.model_semantic_plan`;后台生成失败写入 `generation_error``last_operation=generation_failed`,容器内 `test_risk_rule_generation_failure.py` 与语义计划测试通过
- [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` 通过。
@@ -41,8 +41,8 @@
## 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``handleFileChange` 只把附件加入待发送列表,`sendMessage` 才调用 `recognizeTemporaryFiles``simulateRiskRuleTest`;容器内 `npm run build` 通过。
- [x] [CONCEPT: C5] 测试结果中展示 OCR 原始字段、Hermes 规范化字段、执行器实际输入字段。证据:`AgentAssetRiskRuleSimulationRead` 新增 `ocr_raw_fields``hermes_normalized_fields``executor_input_fields``RiskRuleTestDialog.vue` 展示字段流水线;容器内 `test_risk_rule_explainability.py``test_risk_rule_generation.py` 通过。
- [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`
@@ -50,40 +50,40 @@
- [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] 普通用户误判/漏判反馈进入规则反馈记录,不直接修改规则。
- [x] [CONCEPT: C6] 修订版本保存后重新生成 DSL、流程图、风险评分和业务说明。证据:新增 `AgentAssetRiskRuleRegenerationService``POST /agent-assets/{asset_id}/risk-rules/regenerate`,草稿/修订草稿都会重新生成 JSON DSL、`flow_diagram_svg`、风险评分和版本 Markdown容器内 `test_regenerate_revision_draft_keeps_active_document_unchanged` 通过。
- [x] [CONCEPT: C6] 发布修订版本时归档旧版本,并记录修改人、修改原因和测试报告。证据:新增 `AgentAssetRiskRulePublishMixin`,发布修订时将旧 `rule_document` 写入 `revision_history.previous_rule_document`,切换新 JSON 文件并写入 `last_operation=publish_revision`;容器内 `test_publish_regenerated_revision_replaces_online_document` 通过。
- [x] [CONCEPT: C6] 普通用户误判/漏判反馈进入规则反馈记录,不直接修改规则。证据:新增 `agent_asset_rule_feedback` 模型、`POST/GET /agent-assets/{asset_id}/risk-rules/feedback`、前端服务方法;容器内 `test_risk_rule_feedback.py`、规则回归和 `npm run build` 通过。
## 7. 常见费控规则模板库
- [ ] [CONCEPT: C1] 增加“从常见规则模板创建”入口。
- [ ] [CONCEPT: C1] 模板按预算、票据、差旅、招待、采购/AP、企业卡、通用分组。
- [ ] [CONCEPT: C3] 每个模板提供默认自然语言、字段清单、附件要求和 DSL 样例。
- [ ] [CONCEPT: 非目标] 模板不得绕过通用生成链路,不写定制校准器。
- [x] [CONCEPT: C1] 增加“从常见规则模板创建”入口。证据:`AuditRuleDialogs.vue` 新建风险规则弹窗新增常见规则模板选择,选择后预填标题、附件要求、业务环节、费用领域和自然语言。
- [x] [CONCEPT: C1] 模板按预算、票据、差旅、招待、采购/AP、企业卡、通用分组。证据:新增 `risk_rule_template_catalog.py``GET /agent-assets/risk-rules/templates` 返回 7 个分组;容器内 `test_risk_rule_template_catalog.py` 通过。
- [x] [CONCEPT: C3] 每个模板提供默认自然语言、字段清单、附件要求和 DSL 样例。证据:模板接口返回 `natural_language``fields``requires_attachment``dsl_example`;容器内测试逐个调用 DSL validator 验证通过。
- [x] [CONCEPT: 非目标] 模板不得绕过通用生成链路,不写定制校准器。证据:前端模板只预填 `riskRuleCreateForm`,提交仍走 `generateRiskRuleAsset`;无新增定制校准器,容器内 `npm run build` 通过。
## 8. 前端详情与交互
- [ ] [CONCEPT: 前端设计] 详情页 topbar 展示规则标题、状态、风险分数、风险等级、上线/启用状态。
- [ ] [CONCEPT: C4] 判断流程区域改成左侧文字流程解释、右侧流程图。
- [ ] [CONCEPT: C4] 流程图标题固定为“流程图”,高度与“流程解释”标题对齐。
- [ ] [CONCEPT: C5] 测试弹窗展示字段识别结果、规范化字段、判断路径和测试报告。
- [x] [CONCEPT: 前端设计] 详情页 topbar 展示规则标题、状态、风险分数、风险等级、上线/启用状态。证据:`auditViewDetailTopBar.js` 为风险规则详情输出风险分、风险等级、规则状态、上线状态、启用状态 KPI容器内 `npm run build` 通过。
- [x] [CONCEPT: C4] 判断流程区域改成左侧文字流程解释、右侧流程图。证据:`RiskRuleFlowDiagram.vue` 使用左侧 `risk-rule-flow-explainer` 和右侧 `risk-rule-flow-visual` 的两栏布局;容器内 `npm run build` 通过。
- [x] [CONCEPT: C4] 流程图标题固定为“流程图”,高度与“流程解释”标题对齐。证据:`RiskRuleFlowDiagram.vue` 使用统一 `risk-rule-section-title`,右侧标题固定为“流程图”;容器内 `npm run build` 通过。
- [x] [CONCEPT: C5] 测试弹窗展示字段识别结果、规范化字段、判断路径和测试报告。证据:`RiskRuleTestDialog.vue` 展示字段流水线、执行路径和右侧测试报告摘要;容器内 `cd /app/web && npm run build` 通过。
- [x] [CONCEPT: C6] 已上线规则详情展示“创建修订版本”,草稿规则展示“编辑规则”。证据:`AuditView.vue` 底部动作区按规则状态展示按钮,`AuditRuleDialogs.vue` 提供编辑/修订弹窗,`useAuditRiskRuleActions.js` 调用草稿编辑与修订接口;容器内 `cd /app/web && npm run build` 通过。
- [ ] [CONCEPT: 指标与验收] 列表和详情状态刷新不能造成页面闪烁。
- [x] [CONCEPT: 指标与验收] 列表和详情状态刷新不能造成页面闪烁。证据:`useAuditAssetData.loadSelectedAssetDetail` 增加 `{ silent: true }` 静默刷新,规则保存、送审、审核、上线、回退和版本操作均改为静默刷新;容器内 `npm run build` 通过。
## 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: 接口设计] `POST /agent-assets/{asset_id}/risk-rules/regenerate` 返回生成状态和错误详情。证据:独立路由 `agent_asset_risk_rules.py` 已接入重生成接口,成功返回 `AgentAssetRead.config_json.generation_status`/`revision_draft.generation_status`,接口用例 `test_regenerate_risk_rule_endpoint_returns_updated_detail` 通过。
- [x] [CONCEPT: 接口设计] 仿真测试接口返回 `recognized_fields``normalized_fields``execution_result``trace`。证据:`AgentAssetRiskRuleSimulationRead` 新增 `normalized_fields``trace`,仿真测试覆盖返回值。
- [ ] [CONCEPT: 用户与场景] 普通财务人员只能编辑未上线/修订草稿admin 才能删除和测试,管理员按现有权限上线/下线。
- [ ] [CONCEPT: 数据设计] 所有操作写入 `last_operation`,用于详情页“最后操作”展示。
- [x] [CONCEPT: 用户与场景] 普通财务人员只能编辑未上线/修订草稿admin 才能删除和测试,管理员按现有权限上线/下线。证据:路由依赖使用 `RuleEditorUser``RuleReviewerUser``PlatformAdminUser` 分层,`test_risk_rule_revision_endpoints.py` 覆盖 finance 新建/测试阻断、manager 删除阻断和 manager 启停入口。
- [x] [CONCEPT: 数据设计] 所有操作写入 `last_operation`,用于详情页“最后操作”展示。证据:生成、后台生成、草稿编辑、创建修订、重新生成、发布/下线、测试确认等风险规则服务均写入 `config_json.last_operation`,前端 `AuditJsonRiskRuleDetail.vue` 展示 `lastOperationLabel`
## 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: 测试方案] 后端补充修订版本接口和发布替换接口测试。证据:`test_risk_rule_revision_service.py` 覆盖草稿编辑创建修订、修订重生成和发布替换;`test_risk_rule_revision_endpoints.py` 覆盖草稿编辑、创建修订和重生成接口;容器内相关测试通过
- [x] [CONCEPT: 测试方案] 前端补充详情页流程展示、测试弹窗字段展示、修订版本按钮状态测试。证据:新增 `risk-rule-detail-experience.test.mjs` 覆盖 topbar KPI、左文右图流程、字段流水线和修订按钮容器内 `node --test tests/risk-rule-detail-experience.test.mjs` 通过。
- [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。
@@ -91,6 +91,6 @@
## 11. 文档收尾
- [ ] [CONCEPT: 指标与验收] 开发完成后补充实际接口、文件和测试命令结果。
- [ ] [CONCEPT: 风险与开放问题] 记录暂未解决的字段本体缺口和复杂规则降级策略。
- [ ] [CONCEPT: 功能一句话] 确认最终实现没有偏离“解释图和执行逻辑一致”的核心目标。
- [x] [CONCEPT: 指标与验收] 开发完成后补充实际接口、文件和测试命令结果。证据:`CONCEPT.md` 新增“本轮落地结果”,列出接口、关键文件和容器验证命令。
- [x] [CONCEPT: 风险与开放问题] 记录暂未解决的字段本体缺口和复杂规则降级策略。证据:`CONCEPT.md` 风险与开放问题补充企业卡、采购/AP、预算字段本体缺口和 DSL validator/dry-run/仿真兜底策略。
- [x] [CONCEPT: 功能一句话] 确认最终实现没有偏离“解释图和执行逻辑一致”的核心目标。证据:`CONCEPT.md` 新增“实现确认”明确自然语言、字段本体、JSON DSL、流程图、测试 trace 和上线版本围绕同一 DSL。

View File

@@ -0,0 +1,151 @@
# 数字员工工作看板概念文档
## 功能一句话
在分析看板中新增“数字员工看板”,让用户用一个统一视角看到数字员工每天执行了哪些后台分析、整理、积累和评估工作,以及这些工作产生了什么业务结果。
## 背景与问题
当前数字员工已经有“员工技能”和“工作记录”页面,但工作记录偏运行明细,适合追溯单次任务。管理者在分析看板中缺少一个汇总视角,无法快速回答:
- 今天数字员工是否真的在工作。
- 哪些技能执行最多。
- 成功、失败、运行中的任务分别是多少。
- 风险图谱、风险线索、员工画像和知识整理分别产出了什么。
- 最近失败或异常的后台任务是否需要处理。
新增看板后,分析看板承担“经营和运行洞察”入口,数字员工页面继续承担“技能配置、工作记录详情和人工操作”入口。
## 目标与非目标
### 目标
- 在分析看板顶部切换项中新增“数字员工看板”。
- 用真实 `AgentRun``AgentToolCall` 数据聚合数字员工工作,不使用演示数据伪装真实结果。
- 展示最近 N 天的工作总数、成功数、失败数、运行中数量、产出量和日趋势。
- 区分技能类型:积累、升级、整理、评估。
- 展示最近工作记录,用户能直观看到每天做了什么和产出了什么。
### 非目标
- 不替代数字员工页面的“员工技能”和“工作记录”详情。
- 不让数字员工执行规则中心主流程,也不让数字员工定义、发布或确认风险规则。
- 不展示内部实现名称或技术代号,页面文案统一使用“数字员工”。
- 不在本期新增新的算法执行器,只消费已有执行结果做分析看板聚合。
## 用户与场景
- 财务负责人:查看数字员工每天是否持续产出知识整理、风险观察、画像快照和线索。
- 风控与审计人员:查看评估、升级类任务的失败与产出情况,判断是否需要复核。
- 系统管理员:观察后台任务是否运行稳定,识别失败任务和数据异常。
## 功能能力
### 输入
- `agent_runs`:数字员工运行记录。
- `agent_tool_calls`:每次运行中的工具调用与响应摘要。
- `route_json` / `request_json` / `response_json`:用于识别任务类型、任务编码、报告类型和产出指标。
### 输出
- KPI 指标:工作总数、成功数量、失败数量、运行中数量、业务产出、成功率。
- 每日工作趋势:按日期聚合总数、成功、失败和主要产出量。
- 技能类型分布:积累、升级、整理、评估。
- 工作模块排行:财务风险图谱巡检、员工行为画像巡检、风险线索归集、知识制度整理等。
- 最近工作记录:任务名称、状态、开始时间、耗时、摘要和关键指标。
### 状态
- 成功:`succeeded``success``completed``done`
- 失败:`failed``failure``error``errored`
- 运行中:`running``pending`
- 其他状态统一归入“其他”,但不丢弃记录。
### 权限与边界
- 本期沿用分析看板已有访问控制,不新增独立权限。
- 看板只读,不提供运行、定时、编辑技能等操作。
- 单次运行详情仍在数字员工工作记录页面处理。
## 方案设计
### 后端
新增 `DigitalEmployeeDashboardService`
-`AgentRun` 查询最近 `days` 天数据,最多取 `limit` 条。
- 通过 `agent == "hermes"``source == "schedule"``route_json` 任务字段、工具名 `digital_employee.*` 和知识整理任务类型识别数字员工工作。
- 从工具响应中提取业务产出指标,例如风险观察数、风险线索数、画像快照数、知识文档数。
- 返回稳定结构,前端只负责展示,不重复推断核心聚合逻辑。
新增接口:
```http
GET /api/v1/analytics/digital-employee-dashboard?days=7&limit=300
```
### 前端
新增 `DigitalEmployeeDashboard.vue`
- 复用现有 `OverviewView` 的 KPI 卡片、`dashboard-card``BarChart` 和企业级直角视觉。
- 使用两列到多列的看板网格,避免新增营销化卡片风格。
- 状态、空数据和加载错误保持与风险看板一致。
接入点:
- `TopBar.vue` 增加“数字员工看板”切换项。
- `OverviewView.vue` 新增 `activeDashboard === "digitalEmployee"` 分支。
- `useOverviewView.js` 新增数据加载、KPI 映射、趋势行和排行行。
- `analytics.js` 新增接口调用和字段归一化。
## 算法与公式
### 成功率
$$
success\_rate = \frac{success\_runs}{max(total\_runs, 1)}
$$
### 失败率
$$
failure\_rate = \frac{failed\_runs}{max(total\_runs, 1)}
$$
### 业务产出量
$$
business\_outputs = risk\_observations + risk\_clues + profile\_snapshots + knowledge\_documents
$$
### 日工作负载
$$
daily\_workload_d = total\_runs_d + business\_outputs_d
$$
以上公式只用于看板展示和排序,不参与规则中心决策。
## 测试方案
- 后端单元测试:构造数字员工运行、普通智能体运行、失败运行和工具响应,验证聚合结果。
- 接口测试:验证 `/analytics/digital-employee-dashboard` 返回字段结构和空数据行为。
- 前端静态测试:验证切换项、接口地址、组件分支和核心文案存在。
- 构建验证:运行前端构建,确保新增 Vue 组件可编译。
- 容器验证:在 `x-financial-main` 中运行后端定向测试,并调用真实接口确认返回 JSON。
## 指标与验收
- 分析看板切换中出现“数字员工看板”。
- 选择该看板后页面显示 KPI、每日工作、技能类型分布、任务排行和最近工作。
- 没有真实数据时显示空状态,不使用伪造业务数。
- 接口返回 `has_real_data`,前端可据此判断真实数据状态。
- 后端定向测试和前端定向测试通过。
## 风险与开放问题
- 旧版 `hermes_task_execution_logs` 中的日志没有完整工具响应,本期优先以 `AgentRun` 为准;如需兼容旧日志,可后续做补充。
- 部分新增技能当前可能只有定义,未必已有真实执行结果,看板会显示为 0 或不出现。
- 如果后续新增数字员工技能,需要同步更新任务类型映射,避免看板归类为“其他”。

View File

@@ -0,0 +1,29 @@
# 数字员工工作看板 TODO
## 调研与边界
- [x] 梳理分析看板切换入口和现有数据流。[CONCEPT: 方案设计] 证据:`TopBar.vue``OverviewView.vue``useOverviewView.js`
- [x] 梳理数字员工工作记录数据来源。[CONCEPT: 功能能力] 证据:`AgentRun``AgentToolCall``digitalEmployeeWorkRecordsModel.js`
- [x] 明确本期非目标:不替代数字员工详情、不执行规则中心主流程、不使用演示数据。[CONCEPT: 目标与非目标]
## 契约与后端
- [x] 新增数字员工看板响应 schema。[CONCEPT: 后端] 证据:`DigitalEmployeeDashboardRead`
- [x] 新增 `DigitalEmployeeDashboardService` 聚合运行记录、任务分布、日趋势和最近工作。[CONCEPT: 后端] 证据:`digital_employee_dashboard.py`
- [x] 新增 `/analytics/digital-employee-dashboard` 接口。[CONCEPT: 后端] 证据:`analytics.py` 路由和容器接口返回。
- [x] 补后端定向测试覆盖成功、失败、非数字员工过滤和业务产出统计。[CONCEPT: 测试方案] 证据:`server/tests/test_digital_employee_dashboard_service.py`2 passed。
## 前端
- [x] 在分析看板切换项中增加“数字员工看板”。[CONCEPT: 前端] 证据:`TopBar.vue`
- [x]`analytics.js` 新增接口调用和字段归一化。[CONCEPT: 前端] 证据:`fetchDigitalEmployeeDashboard``normalizeDigitalEmployeeDashboardPayload`
- [x]`useOverviewView.js` 接入加载状态、KPI、趋势和排行数据。[CONCEPT: 前端] 证据:`useOverviewView.js``overviewDigitalEmployeeDashboardModel.js`
- [x] 新增 `DigitalEmployeeDashboard.vue`,复用现有企业看板风格。[CONCEPT: 前端] 证据:看板组件和 ECharts 日趋势组件。
- [x]`OverviewView.vue` 增加数字员工看板分支。[CONCEPT: 前端] 证据:`activeDashboard === "digitalEmployee"`
## 验证与验收
- [x] 运行后端定向测试,超时不超过 60s。[CONCEPT: 测试方案] 证据:`timeout 60s ... pytest server/tests/test_digital_employee_dashboard_service.py -q`2 passed。
- [x] 运行前端定向测试或构建验证。[CONCEPT: 测试方案] 证据:`node --test web/tests/digital-employee-dashboard.test.mjs`3 passed`npm.cmd --prefix web run build` 通过。
- [x] 在 Docker 容器中调用真实接口验证 JSON 返回。[CONCEPT: 指标与验收] 证据:`GET /api/v1/analytics/digital-employee-dashboard?days=7&limit=300` 返回 `True 1 1 知识制度整理`
- [x] 更新本 TODO 的完成证据。[CONCEPT: 指标与验收] 证据:本文档已更新。

View File

@@ -0,0 +1,133 @@
# 数字员工能力库扩展概念文档
更新日期2026-05-31
## 功能一句话
把数字员工从少量后台任务扩展为覆盖事实抽取、规则命中分析、资产积累、报告生成和人工复核辅助的企业级后台分析能力库。
## 背景与问题
当前员工技能数量偏少,只有制度整理、风险图谱巡检、员工画像巡检和少量复核辅助能力。页面观感更像技术演示,不像完整的财务数字员工能力矩阵。
需要把已有风险图谱、制度知识、画像基线、反馈池、回放评测等算法资产拆成用户能理解的员工技能,让列表规模、分类结构和详情内容都更完整。
同时必须收敛数字员工边界:数字员工不是风险专家,也不是规则制定者。风险口径、规则内容、制度解释和最终判断由人负责;规则中心执行归属外层智能体流程,数字员工只负责读取事实、规则命中和反馈结果,生成后台分析、报告、知识库材料和待人工复核线索。
## 目标
- 员工技能数量扩展到不少于 16 个。
- 保持四类技能:积累、升级、整理、评估。
- 每个技能都有名称、描述、技能包、分类、执行场景、输入、输出、是否定时、是否写入工作记录。
- 新增技能进入资产种子和运行时补齐逻辑,已有数据库启动后也能自动补齐。
- 新增技能包落在 `server/src/app/skills/domain`,便于后续同步到数字员工运行侧。
- 明确技能边界:输出事实、规则命中和待人工确认线索,不输出正式规则结论或规则变更裁判。
## 非目标
- 本轮不引入新的数据库结构变更。
- 本轮不要求所有新增技能都接入真实执行器。
- 本轮不复制竞品术语或页面包装,只做 X-Financial 自有能力命名。
- 本轮不让数字员工总结风险规则、发明新规则、修改规则中心或替代人工确认风险。
## 用户与场景
- 风控管理员:查看评估类和升级类技能,理解规则命中分析、异常线索、人工复核样本和回放评测能力。
- 财务制度管理员:查看整理类技能,维护制度条款、政策口径和规则命中样本。
- 数据治理人员:查看积累类技能,理解员工、部门、供应商和反馈样本如何沉淀。
- 系统管理员:配置定时计划、查看工作记录和执行结果。
## 功能能力
完整员工技能库按四类组织:
- 整理:财务制度、制度条款、政策口径、规则命中样本。
- 积累:员工画像、部门基线、供应商画像、误报样本、反馈样本。
- 评估:风险图谱、多凭证一致性、时空一致性、预算超标、供应商异常关系。
- 升级:风险线索归集、算法回放、制度引用缺口提示和人工复核材料整理。
每个技能需要提供:
- `skill_name`:技能包目录名。
- `skill_category`:积累、升级、整理、评估之一。
- `task_type`:由任务 code 派生。
- `schedule` / `cron_expression`:默认定时计划。
- `input_sources`:输入来源。
- `output_format`:产出格式。
- `writes_work_record`:是否产出工作记录。
- `execution_strategy`:真实执行、复用现有扫描器或定义先行。
- `role_boundary`:规则由人定义、风险由人确认、主流程由外层智能体执行,数字员工只做后台分析、报告生成和知识沉淀。
- `allowed_outputs`:只允许输出 `facts``rule_hits``risk_clues``evidence_refs``human_review_required` 等受控字段。
## 数字员工边界
数字员工允许做三件事:
- 事实抽取:从申请单、报销单、票据、附件、审批记录中抽取金额、时间、地点、人员、供应商、票据号、申请关系等事实。
- 规则命中分析:读取外层智能体流程已经产生的规则命中结果、字段依据和原始证据,用于后台报告与复核材料整理。
- 线索归集:基于事实和规则命中输出“待人工复核”的潜在线索,不能把线索升级为正式风险结论。
数字员工禁止做四件事:
- 不总结或发明风险规则。
- 不修改、发布、删除规则中心规则。
- 不把潜在线索判定为最终违规结论。
- 不替代财务、风控或管理员进行制度解释和风险确认。
## 方案设计
### 后端
-`agent_foundation_constants.py` 增加新增任务 code 和分类映射。
-`agent_foundation_digital_employee_tasks.py` 增加运行时任务规格。
- 在初始种子流程完成基础任务 flush 后,调用运行时补齐逻辑,保证新库完整落库。
- 新增技能包目录和 `SKILL.md`,内容包含功能说明、执行时机、输入输出和边界。
- 将容易越权的“规则发现、规则模板整理、制度缺口优化”收敛为“风险线索归集、规则命中样本整理、制度引用缺口提示”。
### 前端
前端列表已按资产接口读取任务类资产,不需要新增页面结构。新增任务落库后会自动进入员工技能列表,并使用已有筛选、分类和详情展示。
### 算法与公式
本轮主要扩展能力目录和角色边界,不新增评分公式。后续每个技能接入真实算法时,再在对应算法文档中补充公式。
数字员工输出的线索置信度只能作为排序依据,不能作为最终风险裁判:
$$
risk\_clue = f(facts, rule\_hits, evidence\_quality)
$$
其中 `facts` 来自申请与报销事实,`rule_hits` 来自外层智能体流程或规则中心已经产生的命中结果,`evidence_quality` 表示证据完整度。数字员工不触发规则主流程,最终是否构成风险由人工复核或规则中心既有处置流程决定。
### 后台分析闭环
风险线索归集不是规则生产流程,而是后台分析闭环的一环:
- 工作记录详情展示本次归集的事实、规则命中、待复核线索和近期反馈样本。
- 风险看板展示待复核线索数和反馈样本数,用于观察后台分析是否形成可复盘资产。
- 人工反馈仍写入风险观察反馈池,数字员工只读取反馈池做线索排序、复核材料整理和后续报告生成。
## 测试方案
- 单元测试:校验数字员工运行时任务规格数量、分类覆盖、技能包目录存在、任务 code 唯一。
- 配置测试:校验每个任务配置都包含 `skill_name``output_format``skill_category_options`
- 容器验证:在 `x-financial-main:/app/server` 运行定向测试。
- 手工验收:进入数字员工员工技能列表,确认技能数量和分类明显完整。
- 接口验收:风险看板接口返回 `risk_clue_count``feedback_sample_count`,工作记录详情能展示风险线索归集的反馈样本摘要。
## 指标与验收
- 员工技能总数不少于 17 个。
- 四类分类都有技能。
- 新增技能包全部存在 `SKILL.md`
- 定向测试通过。
- 风险看板不再展示候选规则指标,改为待复核线索和反馈样本。
- 不引入数据库迁移和破坏性变更。
## 风险与开放问题
- 新增技能中部分为“定义先行”,立即运行时需要后续逐步接入真实执行器。
- 如果用户希望每个技能都能立即产出真实结果,需要继续拆分执行服务和工作记录产物。
- 已接入风险线索归集真实执行器,后续应继续把多凭证、时空、预算、供应商异常从风险图谱主引擎中拆成独立算法模块。
- 若技能命名或说明再次出现“数字员工承担规则主流程、规则发现、规则优化、自动总结风险”等表述,应优先改为读取规则命中结果、事实、线索、复核材料等受控表述。

View File

@@ -0,0 +1,56 @@
# 数字员工能力库扩展 TODO
更新日期2026-05-31
## 1. 调研与契约
- [x] 复核当前员工技能数量、分类和技能包目录。[CONCEPT: 背景与问题] 证据:当前已有基础技能包:制度整理、风险图谱巡检、员工画像巡检、风险线索归集。
- [x] 定义完整能力矩阵,覆盖积累、升级、整理、评估四类。[CONCEPT: 功能能力] 证据:`CONCEPT.md` 已列出 17 个目标技能。
## 2. 后端资产
- [x] 增加新增数字员工任务 code 和分类映射。[CONCEPT: 后端] 证据:`agent_foundation_constants.py` 已新增 13 个任务 code`DIGITAL_EMPLOYEE_TASK_CATEGORY_MAP` 覆盖四类分类。
- [x] 增加运行时任务规格,保证已有数据库可自动补齐新增员工技能。[CONCEPT: 后端] 证据:`agent_foundation_digital_employee_tasks.py` 已扩展到 16 个运行时任务规格,新增技能均包含 `skill_name/input_sources/output_format/execution_strategy`
- [x] 调整初始种子流程,保证空库初始化时也能落齐完整员工技能库。[CONCEPT: 后端] 证据:`agent_foundation_asset_seed.py` 在基础资产 `flush` 后调用 `_upsert_runtime_digital_employee_tasks()`,空库初始化会补齐完整运行时技能。
## 3. 技能包
- [x] 新增制度条款、政策口径、规则命中样本等整理类技能包。[CONCEPT: 功能能力] 证据:已新增 `finance-policy-clause-extractor``expense-policy-alignment``rule-execution-case-organizer` 技能包。
- [x] 新增部门基线、供应商画像、误报样本、反馈样本等积累类技能包。[CONCEPT: 功能能力] 证据:已新增 `department-expense-baseline-accumulator``supplier-risk-profile-accumulator``false-positive-sample-accumulator``risk-feedback-sample-accumulator` 技能包。
- [x] 新增多凭证、时空、预算、供应商关系等评估类技能包。[CONCEPT: 功能能力] 证据:已新增 `multi-evidence-consistency-evaluator``travel-spatiotemporal-consistency-evaluator``budget-overrun-precontrol-evaluator``supplier-abnormal-relation-evaluator` 技能包。
- [x] 新增回放评测、制度引用缺口提示等升级类技能包。[CONCEPT: 功能能力] 证据:已新增 `risk-algorithm-replay-evaluator``policy-reference-gap-hinter` 技能包。
## 4. 测试与验收
- [x] 增加数字员工技能目录测试,校验任务 code 唯一、分类覆盖、技能包存在。[CONCEPT: 测试方案] 证据:新增 `tests/test_digital_employee_skill_catalog.py` 覆盖任务数量、分类、配置和技能包。
- [x] 在 Docker 容器 `x-financial-main:/app` 运行定向测试60s 内完成。[CONCEPT: 测试方案] 证据:`docker exec x-financial-main bash -lc "cd /app && timeout 60s /tmp/x-financial-server-venv/bin/python -m pytest server/tests/test_digital_employee_skill_catalog.py -q"` 通过3 个测试通过。
- [x] 确认最终员工技能总数不少于 17 个,四类分类都有技能。[CONCEPT: 指标与验收] 证据:测试断言运行时 16 个技能加 `整理公司财务知识制度` 共 17 个,分类覆盖积累、升级、整理、评估。
## 5. 边界收敛
- [x] 调整概念文档,明确数字员工不总结风险规则、不发明规则、不替代人工确认风险。[CONCEPT: 数字员工边界] 证据:`CONCEPT.md``hermes-risk-graph-algorithm/CONCEPT.md` 已把数字员工边界收敛为事实抽取、规则命中结果读取、后台分析和待复核线索归集。
- [x] 将“风险规则候选发现、风险规则模板整理、制度缺口与规则变更建议”收敛为事实、规则命中和人工复核辅助类技能。[CONCEPT: 功能能力] 证据:运行时技能已改为 `risk-clue-collector``rule-execution-case-organizer``policy-reference-gap-hinter`
- [x] 在技能配置中增加 `role_boundary``allowed_outputs`,约束输出只能是事实、规则命中、线索和证据引用。[CONCEPT: 数字员工边界] 证据:`agent_foundation_digital_employee_tasks.py` 为运行时技能配置写入 `role_boundary``allowed_outputs``writes_rules=false`
- [x] 更新技能包 Markdown禁止数字员工发布、改写、总结规则风险线索必须待人工复核。[CONCEPT: 后端] 证据:`risk-clue-collector``rule-execution-case-organizer``policy-reference-gap-hinter` 及兼容别名技能包均已声明禁止生成、改写或发布规则。
- [x] 增加目录测试,防止数字员工技能重新出现自动发布、规则变更、候选规则生成等越权语义。[CONCEPT: 测试方案] 证据:`test_digital_employee_skills_do_not_cross_rule_governance_boundary` 已断言旧技能名和危险输出格式不再进入数字员工目录。
## 7. 流程边界收敛
- [x] 明确规则中心命中结果归属外层智能体流程,数字员工只消费规则命中结果。[CONCEPT: 数字员工边界] 证据:`CONCEPT.md` 已改为“规则命中分析”,并声明数字员工不触发规则主流程。
- [x] 更新技能与配置文案,禁止数字员工被描述为规则主流程处理器。[CONCEPT: 后端] 证据:`agent_foundation_digital_employee_tasks.py``risk-clue-collector``rule-execution-case-organizer` 及兼容别名技能包均已改为后台分析和复核材料口径。
- [x] 增加测试,防止 `role_boundary` 再次出现规则主流程越界表述。[CONCEPT: 测试方案] 证据:`test_digital_employee_runtime_specs_build_display_ready_config` 已覆盖主流程归属和禁止数字员工承担规则主流程职责。
## 6. 风险线索归集真实执行器
- [x] 新增 `HermesRiskClueCollectorService`,读取申请/报销事实、规则命中、风险观察和人工反馈,输出 `risk_clue_review_packet`。[CONCEPT: 算法与公式] 证据:`hermes_risk_clue_collector.py` 输出 `facts/rule_hits/risk_clues/evidence_refs/human_review_required`
- [x]`risk_clue_collect` 接入数字员工立即运行分发。[CONCEPT: 后端] 证据:`orchestrator_execution.py` 已新增 `digital_employee.risk_clue.collect` 工具调用,`test_schedule_digital_employee_task_runs_real_service` 覆盖分发。
- [x]`risk_clue_collect` 接入 Hermes 定时调度。[CONCEPT: 后端] 证据:`hermes_scheduler.py` 已新增 `risk_clue_collect` 分支并写入执行摘要。
- [x] 工作记录详情识别风险线索归集产物,展示事实、规则命中、待复核线索和证据引用计数。[CONCEPT: 前端] 证据:`digitalEmployeeWorkRecordsModel.js``DigitalEmployeeRunProducts.vue` 已支持 `risk_clue` 产物,前端测试覆盖。
- [x] 增加执行器测试,验证不写规则、不输出候选规则、线索必须待人工复核。[CONCEPT: 测试方案] 证据:`test_hermes_risk_clue_collector.py` 通过,断言 `writes_rules=false``human_review_required=true` 和无 `candidate_risk_rules/auto_publish`
## 8. 后台分析闭环
- [x] 风险线索归集产物补充观察键、反馈状态和近期反馈样本摘要,方便工作记录详情定位复核上下文。[CONCEPT: 后台分析闭环] 证据:`hermes_risk_clue_collector.py` 输出 `observation_key/feedback_status/next_action/feedback_summary``DigitalEmployeeRunProducts.vue` 展示反馈样本。
- [x] 风险看板聚合接口补充 `risk_clue_count``feedback_sample_count`,把数字员工后台分析结果接入看板指标。[CONCEPT: 后台分析闭环] 证据:`RiskObservationDashboardRead``RiskObservationService.summarize_dashboard()` 已输出线索数和反馈样本数。
- [x] 风险看板前端移除“候选规则”指标,改为“待复核线索”和“反馈样本”。[CONCEPT: 指标与验收] 证据:`RiskObservationDashboard.vue` 的算法闭环效果区已展示 `待复核线索/反馈样本`,前端测试断言不再出现候选规则。
- [x] 增加后端与前端定向测试,并在 Docker 容器内验证核心后端测试通过。[CONCEPT: 测试方案] 证据:`pytest` 定向测试 8 个通过,`node --test` 前端定向测试 8 个通过。

View File

@@ -0,0 +1,127 @@
# 申请交通费用自动预估概念文档
## 功能一句话
在费用申请预览阶段,系统自动生成交通票价 mock 估算,并叠加现有住宿与补助标准,形成申请预估总费用,替代用户手动填写预估金额。
## 背景与问题
当前申请流程要求用户补充“用户预估费用”。对差旅申请来说,用户在申请阶段往往只能确认出行方式、目的地和天数,交通票价又暂时缺少正式票务接口支持,因此让用户手填金额会降低流程顺畅度。
本期先用系统估算补齐申请金额:
- 交通费用:按火车、飞机、轮船三类 mock 票价生成稳定估算。
- 住宿与补助:前端申请预览继续调用现有差旅规则测算,复用住宿上限和补助标准。
- 后端对话:当没有前端预览上下文时,用同口径的兜底估算生成金额,避免选择交通方式后继续追问金额。
## 目标与非目标
目标:
- 申请预览不再要求用户手动填写预估费用。
- 用户选择火车、飞机或轮船后,系统能生成交通费用估算。
- 预估总费用 = mock 交通费 + 住宿标准小计 + 补助标准小计。
- 预览、提交文本和后端对话统一展示“系统预估费用”。
- 保留用户明确输入金额时的兼容能力,不破坏历史提交链路。
非目标:
- 本期不接入真实机票、火车票、船票接口。
- 本期不做票价实时波动、余票、舱等、席别、折扣和路线中转算法。
- 本期不把 mock 估算作为最终报销金额,报销阶段仍应结合真实票据复核。
## 用户与场景
主要用户:
- 员工:在“申请/事前审批”环节快速发起差旅费用申请。
- 财务/审批人:查看申请金额是否由系统按标准测算生成。
典型场景:
1. 用户输入“去上海出差 3 天,火车”。
2. 系统识别地点、天数、出行方式。
3. 系统 mock 生成火车往返票价。
4. 系统调用现有差旅测算拿到住宿与补助小计。
5. 系统在申请预览中展示系统预估费用,并允许进入确认提交。
## 功能能力
输入:
- 地点:用于差旅规则匹配和交通 mock 城市层级判断。
- 天数:用于住宿与补助小计。
- 出行方式:火车、飞机、轮船。
- 职级:沿用现有差旅测算接口的标准匹配入参。
输出:
- 交通费用口径:说明当前是 mock 票价估算,报销阶段按真实票据复核。
- 规则测算参考:展示交通、住宿、补助拆分与合计。
- 系统预估费用:写入申请金额字段,用于后续申请提交。
- 估算来源字段:记录 mock 交通估算和规则测算结果,便于后续审计解释。
边界:
- 缺少地点或天数时,仍不能完成住宿与补助测算,需要继续补齐基础字段。
- 缺少出行方式时,仍需用户选择火车、飞机或轮船。
- 后端纯对话流程没有前端规则测算结果时,使用保守的 mock 住宿/补助兜底。
## 方案设计
前端:
- 新增申请估算工具模块,集中维护交通 mock 票价、金额格式化和总额合成。
- `expenseApplicationPreview` 在差旅规则测算返回后,将交通 mock 金额叠加到住宿与补助小计。
-`amount` 字段改为“系统预估费用”,并设为非手动必填字段。
- 申请提交文本使用系统生成的金额。
后端:
- 新增申请系统预估服务模块,避免继续向已经超过 800 行的 `user_agent_application.py` 堆业务算法。
- 后端对话在基础字段和出行方式齐全时自动补 `amount``transport_policy``policy_estimate`
- 缺失字段追问只保留基础字段和出行方式,不再追问预估金额。
数据与接口:
- 不新增数据库字段。
- 不新增外部接口。
- 申请详情仍通过现有 `risk_flags_json.application_detail` 保存展示字段。
## 算法与公式
交通费用采用稳定 mock
$$
transport\_amount = round\_10(base(mode, location) \times 2)
$$
其中 `mode` 为火车、飞机、轮船,`location` 用于判断一线/远途/沿海等粗粒度场景,默认按往返估算。
总费用:
$$
estimated\_total = transport\_amount + lodging\_amount + allowance\_amount
$$
前端的 `lodging_amount``allowance_amount` 来自现有差旅规则测算结果;后端兜底时按 mock 标准生成。
## 测试方案
- 前端单测:验证交通 mock、规则测算合计、行标签和提交文本。
- 后端单测:验证选择交通方式后不再追问金额,而是直接生成预览。
- 编排流测试:验证申请会话从补充出行方式直接进入确认,再提交成功。
- 回归测试:用户明确输入金额时仍能提交,并保留兼容链路。
## 指标与验收
- 用户选择出行方式后,系统不再提示“用户预估费用”缺失。
- 申请预览中出现“系统预估费用”。
- 规则测算参考包含交通、住宿、补助三项拆分。
- 前端定向测试和后端申请流程测试通过。
## 风险与开放问题
- mock 票价不代表真实票价,只适合作为申请阶段预算参考。
- 后端兜底住宿/补助不能完全替代规则中心,前端有规则测算结果时应优先使用规则中心。
- 后续接入真实票务接口后,应替换交通 mock 模块,不改变申请预览和提交的数据契约。

View File

@@ -0,0 +1,34 @@
# 申请交通费用自动预估开发 TODO
## 调研与契约
- [x] 确认申请预览当前金额字段仍为用户手填。证据:`expenseApplicationPreview.js``amount` 标签为“用户预估费用”。
- [x] 确认住宿与补助已有规则测算入口。证据:前端申请预览调用 `calculateTravelReimbursement` 并读取 `hotel_amount``allowance_amount`
- [x] 确认后端对话仍追问金额。证据:`user_agent_application.py` 的缺失字段包含 `amount`
## 算法
- [x] 新增前端申请估算工具模块,提供火车、飞机、轮船 mock 交通费。证据:`expenseApplicationEstimate.js`
- [x] 将前端规则测算结果合成为交通 + 住宿 + 补助总额。证据:`expenseApplicationPreview.js` 的规则测算合成逻辑和前端定向测试。
- [x] 新增后端申请估算工具模块,提供无前端上下文时的兜底估算。证据:`application_system_estimate.py`
## 前端
- [x] 将申请预览金额标签改为“系统预估费用”。证据:`expenseApplicationPreview.js` 字段定义。
- [x]`amount` 改为系统估算字段,不再作为用户必填项阻塞。证据:`amount` 字段 `required: false``editable: false`
- [x] 更新交通费用口径文案,明确是模拟票价估算。证据:`buildTransportPolicyText` 输出模拟票价口径。
- [x] 在规则测算成功后写入系统预估总费用。证据:前端测试 `application preview merges rule center travel estimate into highlighted rows`
## 后端
- [x] 选择出行方式后自动生成系统预估费用。证据:后端测试 `test_user_agent_application_builds_system_estimate_after_transport_choice`
- [x] 缺失字段追问不再包含 `amount`。证据:后端申请流程定向测试。
- [x] 后端预览和提交摘要统一展示“系统预估费用”。证据:`user_agent_application.py` 摘要表字段。
## 测试与验证
- [x] 更新前端申请预览定向测试。证据:`expense-application-fast-preview.test.mjs`
- [x] 更新后端用户 Agent 申请流程测试。证据:`test_user_agent_service.py`
- [x] 更新编排流申请提交测试。证据:`test_orchestrator_review_flow.py`
- [x] 运行前端定向测试,记录结果。证据:`node --test web/tests/expense-application-fast-preview.test.mjs`14 passed。
- [x]`x-financial-main` 容器内运行后端定向测试,记录结果。证据:申请相关 7 个 UserAgent 用例通过、2 个 Orchestrator 用例通过;整包定向存在无关查询动作测试失败。

View File

@@ -0,0 +1,106 @@
# 费用审批动态路由概念文档
## 功能一句话
让费用申请和报账在直属领导审批后,按预算风险、规则风险和员工历史风险动态决定是否进入预算管理者复核。
## 背景与问题
当前申请单默认进入预算管理者审批,报账单默认进入财务审批,审批路径偏固定。业务上更合理的方式是:预算充足、当前无风险、历史画像正常的单据减少审批层级;存在超预算、规则命中、超标或历史风险异常的单据交给预算管理者做二次确认。
## 目标与非目标
目标:
- 申请环节:低风险且预算充足时,直属领导审批后直接完成申请并生成报销草稿。
- 申请环节:超预算、预算预警、当前风险或历史风险异常时,进入预算管理者审批。
- 报账环节:低风险且预算充足时,直属领导审批后进入财务审批。
- 报账环节:超预算、超标、当前风险或历史风险异常时,先进入预算管理者审批,再进入财务审批。
- 审批记录中保留路由决策依据,便于追溯。
非目标:
- 不改预算占用、释放、核销的资金动作语义。
- 不引入新的审批流配置页面。
- 不让大模型参与最终审批路由裁判。
## 用户与场景
- 普通员工:提交费用申请或报账。
- 直属领导:确认业务必要性。
- 预算管理者:只复核有预算或风险关注项的单据。
- 财务人员:处理报账财务终审和付款前流程。
## 功能能力
路由决策输入:
- 单据基本信息:金额、费用类型、发生时间、部门、项目、申请人。
- 预算测算:预算池匹配、可用余额、预算使用率、预警阈值、超预算金额。
- 当前风险:预算标记、规则中心风险、提交预审风险、票据/附件风险、超标风险。
- 历史风险:同一员工近一段时间内的实质风险记录。
路由决策输出:
- `requires_budget_review`:是否需要预算管理者复核。
- `route`:下一环节建议。
- `reasons`:触发预算复核或跳过的原因。
- `budget_result`:预算模型摘要。
- `current_risk_count``historical_risk_count`:当前和历史风险计数。
## 方案设计
后端新增独立审批路由决策模块,避免在审批主流程中堆条件。
直属领导审批时:
1. 调用预算服务计算当前单据预算影响。
2. 读取当前单据风险标记,过滤审批记录等非风险事件。
3. 查询同一员工近期历史单据,统计实质风险记录。
4. 生成路由决策标记并写入 `risk_flags_json`
5. 根据结果决定下一环节:
- 申请单:预算复核或审批完成。
- 报账单:预算复核或财务审批。
预算管理者审批时:
- 申请单进入审批完成,并生成报销草稿。
- 报账单进入财务审批。
## 算法与公式
路由决策不是单一分数,而是规则化闸口:
$$
requires\_budget\_review =
budget\_risk \lor current\_risk \lor historical\_risk
$$
其中:
- `budget_risk = rating in {block, review, caution} or risk_level in {medium, high, critical}`
- `current_risk = 当前单据存在 medium/high/critical 实质风险标记`
- `historical_risk = 同一员工近期存在实质风险记录`
实质风险标记排除审批通过、退回、付款、路由说明等流程记录只保留预算、规则、AI 预审、附件、政策超标等风险来源。
## 测试方案
- 单元测试:低风险申请跳过预算管理者并生成报销草稿。
- 单元测试:高风险报账进入预算管理者审批,预算审批后进入财务审批。
- 回归测试:原有风险规则生成、申请提交、阶段化风险规则执行继续通过。
- 容器验证:在 `x-financial-main:/app/server` 内运行定向 pytest。
## 指标与验收
- 低风险申请不会固定进入预算管理者审批。
- 风险报账会进入预算管理者审批。
- 报账经过预算管理者审批后仍需进入财务终审。
- 每次动态路由都有可追溯的 `approval_routing` 标记。
- 预算资金动作仍由原有提交、退回、财务终审链路处理。
## 风险与开放问题
- 历史风险的口径会影响预算管理者工作量,当前一期采用“存在实质风险即复核”的严格口径。
- 缺失预算池时是否全部进入预算复核,当前按预算风险处理。
- 后续如要支持可配置路由阈值,应新增配置表或策略服务,而不是继续改审批流分支。

View File

@@ -0,0 +1,9 @@
# 费用审批动态路由 TODO
- [x] 调研现有审批流、预算模型和风险标记结构。[CONCEPT: 方案设计] 证据:已梳理 `expense_claim_approval_flow.py``budget.py``budget_expense_control.py``expense_claim_risk_review.py`
- [x] 新增审批路由决策模块,统一输出是否需要预算复核。[CONCEPT: 功能能力] 证据:新增 `expense_claim_approval_routing.py`
- [x] 接入申请单直属领导审批后的动态路由。[CONCEPT: 方案设计] 证据:`ExpenseClaimApprovalFlowMixin.approve_claim` 根据路由结果完成或进入预算审批。
- [x] 接入报账单直属领导审批后的动态路由,并允许报账经过预算管理者后进入财务审批。[CONCEPT: 方案设计] 证据:报账单预算审批后进入 `FINANCE_APPROVAL_STAGE`
- [x] 审批记录写入 `approval_routing` 决策标记。[CONCEPT: 指标与验收] 证据:审批通过时同时写入路由标记和 `route_decision` 摘要。
- [x] 补充低风险申请跳过预算、高风险报账进入预算的测试。[CONCEPT: 测试方案] 证据:新增 `test_expense_claim_approval_routing.py`
- [x]`x-financial-main:/app/server` 运行 60s 内定向验证。[CONCEPT: 测试方案] 证据:`uv run --with pytest python -m pytest ... -q`6 passed。

View File

@@ -0,0 +1,188 @@
# 预算中心列表化改造概念文档
## 功能一句话
将预算中心从看板式监控页改造成单据中心式预算列表,让预算的正式额度、待审核草案和历史归档有清晰入口。
## 背景与问题
当前预算中心以预算概览、部门切换、预算明细表和图表为主,适合查看执行情况,但不适合承载预算编制后的审核流程。预算从 AI 分析、部门编制、提交审核、高级财务审核、发布生效到归档,天然是对象生命周期,不应该把审核入口硬塞进看板区域。
本次改造采用类似单据中心的列表结构,把预算对象按状态域分成三个入口:
- 全部预算:查看已发布并生效的部门预算。
- 预算审核:查看各部门提交的预算草案,由高级财务人员审核。
- 归档预算:查看历史版本、已驳回、已失效或被新版本替换的预算。
## 目标与非目标
### 目标
- 将预算中心主界面改为列表形态。
- 提供三个 switch/tab全部预算、预算审核、归档预算。
- 全部预算按部门展示正式预算,并在详情中展示年度、季度、月度预算。
- 预算审核按部门展示已提交预算草案,并提供进入审核助手的入口。
- 归档预算展示历史预算版本和审核痕迹。
- 保留预算监控员、高级财务人员、admin 的预算可见性边界。
- 前端 demo 阶段仅覆盖差旅、通信、招待费、办公用品四类预算。
### 非目标
- 本阶段不直接完成后端预算草案表、审核表和发布接口。
- 本阶段不实现真实审核通过或驳回的数据库写入。
- 本阶段不改变报销单据的预算占用和核销逻辑。
- 本阶段不扩大普通员工的预算可见范围。
## 用户与场景
- 预算监控员:查看本部门正式预算、提交草案状态和历史归档。
- 高级财务人员:查看所有部门预算、审核各部门提交的预算草案。
- admin查看所有预算数据并兜底处理异常。
- 普通员工:不进入预算中心,不需要关注预算。
## 功能能力
### 全部预算
输入:
- 年度
- 季度
- 状态
- 关键词
输出:
- 预算编号
- 部门
- 预算周期
- 年度预算
- 季度预算
- 月度预算
- 已发生
- 已占用
- 剩余可用
- 风险状态
- 更新时间
点击行进入预算详情,详情展示:
- 年度预算、季度预算、月度预算
- 四类费用预算明细:差旅、通信、招待费、办公用品
- 已发生、已占用、剩余可用和使用率
- 提醒阈值、告警阈值、风险阈值
### 预算审核
输入:
- 年度
- 季度
- 审核状态
- 关键词
输出:
- 草案编号
- 提交部门
- 编制人
- 提交时间
- 预算周期
- 申请预算
- 较上一版变化
- AI 分析分
- 风险状态
- 审核状态
高级财务人员和 admin 可以通过“进入审核”打开预算编制助手,带入当前部门草案上下文。
### 归档预算
输入:
- 年度
- 季度
- 归档状态
- 关键词
输出:
- 归档编号
- 部门
- 预算周期
- 版本
- 归档类型
- 原预算额
- 审核人
- 归档时间
- 状态
## 方案设计
### 前端
- `BudgetCenterView.vue` 改成列表页结构。
- 复用单据中心的 `status-tabs``table-wrap``list-foot` 视觉结构。
- 保留 `EnterpriseSelect` 作为年度、季度、状态和分页大小控件。
- 使用通用详情页承载预算详情,和票据夹等列表详情页保持同一交互结构。
- 使用预算助手入口处理编制和审核上下文。
- 抽出预算列表 demo 数据和转换逻辑到 `budgetCenterListModel.js`,避免主脚本继续变大。
### 后端
本阶段不改后端。后续应新增预算草案、预算审核和预算发布接口,并将已发布预算写入正式预算池。
### 权限
- 预算监控员:只能看到本部门预算和本部门提交记录。
- 高级财务人员:可以看到全部部门预算,并审核预算草案。
- admin可以看到全部预算并兜底处理。
## 算法与公式
预算使用率:
$$
usageRate = \frac{usedAmount + occupiedAmount}{budgetAmount} \times 100
$$
剩余可用预算:
$$
availableAmount = budgetAmount - usedAmount - occupiedAmount
$$
风险分层:
$$
risk =
\begin{cases}
风险, & usageRate \ge riskThreshold \\
告警, & usageRate \ge alertThreshold \\
提醒, & usageRate \ge reminderThreshold \\
正常, & usageRate < reminderThreshold
\end{cases}
$$
## 测试方案
- 静态检查:预算中心脚本 `node --check`
- 前端构建:`npm.cmd --prefix web run build`
- 交互验证:切换全部预算、预算审核、归档预算,检查筛选、分页、通用详情页和预算助手入口。
- 权限验证:使用 admin、高级财务人员、预算监控员分别检查可见范围。
- 响应式验证:检查笔记本宽度下列表横向滚动、通用详情页和按钮尺寸。
## 指标与验收
- 预算中心首屏为列表,而不是原看板。
- 三个 switch/tab 可切换:全部预算、预算审核、归档预算。
- 全部预算详情能看到年度、季度、月度预算。
- 预算审核列表有进入审核入口。
- 预算监控员不出现跨部门审核能力。
- 构建通过,无新增运行时引用错误。
## 风险与开放问题
- 后端预算草案和审核表尚未落库,本阶段使用前端 demo 数据表达流程。
- 后续需要明确“审核通过”是自动发布,还是高级财务人员审核后再点击发布。
- 归档预算的触发条件需要后续和预算发布版本模型一起设计。

View File

@@ -0,0 +1,37 @@
# 预算中心列表化改造 TODO
## 调研
- [x] 阅读预算中心现有页面结构和脚本。证据:`BudgetCenterView.vue``BudgetCenterView.js`
- [x] 阅读单据中心列表结构。证据:`DocumentsCenterView.vue``document-list-shared.css`
- [x] 确认预算中心 UI 规范。证据:`x-financial-enterprise-ui-style` 技能。
## 契约与数据
- [x] 定义预算中心三个页签:全部预算、预算审核、归档预算。证据:`CONCEPT.md` 功能能力。
- [x] 定义前端 demo 阶段的预算列表字段。证据:`CONCEPT.md` 功能能力。
- [x] 抽出预算列表数据模型与格式化逻辑到独立脚本。证据:`budgetCenterListModel.js``[CONCEPT: 方案设计]`
## 前端实现
- [x] 将预算中心主界面改成单据中心式列表结构。证据:`BudgetCenterView.vue` 使用 `status-tabs``table-wrap``list-foot``[CONCEPT: 前端]`
- [x] 增加全部预算、预算审核、归档预算三个 switch/tab。证据Playwright 验证 `全部预算6 / 预算审核6 / 归档预算6``[CONCEPT: 功能能力]`
- [x] 增加关键词、年度、季度、状态筛选。证据:`BudgetCenterView.vue` 工具栏筛选控件。`[CONCEPT: 全部预算]`
- [x] 增加分页和空状态。证据:`BudgetCenterView.vue` 分页脚与 `TableEmptyState``[CONCEPT: 测试方案]`
- [x] 增加预算通用详情页展示年度、季度、月度预算。证据Playwright 验证详情含年度预算、季度预算、月度预算。`[CONCEPT: 全部预算]`
- [x] 增加预算审核入口,带上下文进入预算助手。证据:预算审核列表操作列显示“进入审核”。`[CONCEPT: 预算审核]`
- [x] 按权限限制预算监控员和高级财务人员可见范围。证据Playwright 验证预算监控员仅 1 条技术部记录,审核操作为“查看进度”。`[CONCEPT: 权限]`
- [x] 将预算工作区纳入单据中心同一外层触底布局。证据:`app.css` 增加 `budget-main``budget-workarea` 高度规则。`[CONCEPT: 前端]`
## 验证
- [x] 运行 `node --check web/src/views/scripts/BudgetCenterView.js`。证据:命令通过。`[CONCEPT: 测试方案]`
- [x] 运行 `node --check web/src/views/scripts/budgetCenterListModel.js`。证据:命令通过。`[CONCEPT: 测试方案]`
- [x] 运行 `npm.cmd --prefix web run build`。证据:构建通过,仅剩既有 VueUse 注释和 chunk 体积 warning。`[CONCEPT: 验收]`
- [x] 做预算页基础渲染验证,确认三个页签、通用详情页、审核入口可用。证据:浏览器验证预算列表 1366×768 视口下触底,详情页无 `ElDrawer`详情四类费用和图表渲染console 无新增错误。`[CONCEPT: 验收]`
## 后续阶段
- [ ] 设计后端预算草案表、预算审核表和发布接口。`[CONCEPT: 后端]`
- [ ] 将审核通过后的预算发布到正式预算池。`[CONCEPT: 后端]`
- [ ] 将报销预算占用、费用控制和预算发布版本打通。`[CONCEPT: 风险与开放问题]`