# X-Financial 改进路线图

> 本文档基于 2026-06-18 对代码库的算法层、业务层、工程层综合评估生成。
> 每项改进都附有文件路径佐证，便于后续定位和追踪。
> 维护规则：状态变更请在对应章节同步更新；新增改进项追加到对应优先级末尾。

## 状态约定

| 标记 | 含义 |
|---|---|
| ⏳ | 待启动 |
| 🔄 | 进行中 |
| ✅ | 已完成 |
| ⏸️ | 暂缓（需说明原因） |
| ❌ | 取消（需说明原因） |

## 优先级矩阵

| 优先级 | 编号 | 标题 | 状态 |
|---|---|---|---|
| 🔴 P0 安全 | B2 | HTTP Header 权限漏洞 | ⏳ |
| 🔴 P0 业务核心 | B1 | 审批流转交/加签/撤回/会签 | ⏳ |
| 🔴 P0 共识 | B10 | 800 行硬约束破防 | ⏳ |
| 🟠 P1 算法 | A1 | 风险评分权重自适应 | ⏳ |
| 🟠 P1 算法 | A4 | LLM 票据分类 + 字段置信度 | ⏳ |
| 🟠 P1 算法 | A7 | LLM 幻觉检测 | ⏳ |
| 🟠 P1 业务 | B6 | 规则覆盖不均衡 | ⏳ |
| 🟡 P2 业务 | B3 | 申请/报销拆表 | ⏳ |
| 🟡 P2 业务 | B4 | 可配置审批矩阵 | ⏳ |
| 🟡 P2 算法 | A2 | 异常检测自适应阈值 | ⏳ |
| 🟢 P3 算法 | A3 | 多模型异常检测集成 | ⏳ |
| 🟢 P3 算法 | A5 | 票据分类持续学习 | ⏳ |
| 🟢 P3 算法 | A6 | Prompt 模板集中管理 | ⏳ |
| 🟢 P3 算法 | A8 | 规则冗余建模 | ⏳ |
| 🟢 P3 算法 | A9 | 行为画像 fairness 保护 | ⏳ |
| 🟢 P3 业务 | B5 | 预算跨期/跨科边界 | ⏳ |
| 🟢 P3 业务 | B7 | 审计日志防篡改 | ⏳ |
| 🟢 P3 业务 | B8 | 审批 SLA 监控 | ⏳ |
| 🟢 P3 业务 | B9 | 支付与凭证对接 | ⏳ |
| 🟢 P3 算法 | A10 | 算法模块 800 行拆分 | ⏳ |

---

## 一、算法层面改进

### A1. 风险评分权重自适应调优 ⏳

**优先级**：🟠 P1

**证据**：
- `server/src/app/algorithem/risk_graph/engine.py:457-465`
- `server/src/app/services/risk_rule_scoring.py:16-23`

**当前实现**：
```python
risk_score = 0.35*S_rule + 0.25*S_anomaly + 0.20*S_graph + 0.15*S_policy + 0.05*S_history
```
五维权重和六因子权重均为硬编码常量，无法反映规则有效性差异。

**问题**：
- 已有 `RiskObservationFeedback` 表收集人工反馈，但反馈数据**未反向更新权重**
- 不同费用类型（差旅/招待/通信）的合理权重差异大，目前一刀切

**改进方向**：
- 按费用类型分组的权重向量
- 定期基于反馈数据做 logistic regression / Bayesian 更新
- 权重变更需版本化、可回滚

**验收标准**：
- [ ] 权重从配置/数据库读取，不再硬编码
- [ ] 反馈数据能触发权重自动调整
- [ ] 不同费用类型可配置独立权重
- [ ] 调整过程有日志和效果对比

---

### A2. 金额异常检测自适应阈值 ⏳

**优先级**：🟡 P2

**证据**：`server/src/app/algorithem/risk_graph/engine.py:221-261`

**当前实现**：固定分档阈值 `1.0x→0, 1.25x→30, 1.5x→55, 2.0x→75, 3.0x→95`

**问题**：
- 通信费（小额高频）和差旅（大额低频）的"1.5x"含义完全不同
- peer p75 在新部门/新费用类型时样本稀疏
- 已识别 `peer_baseline_insufficient` 不确定性，但无冷启动方案

**改进方向**：
- 改为自适应分位数（基于历史数据动态计算）
- 按 `(费用类型 × 部门层级)` 分组维护基线
- 冷启动：全局基线 + 小样本置信度折扣

**验收标准**：
- [ ] 阈值按业务维度分组，不再全局统一
- [ ] 新部门/新费用类型有冷启动策略
- [ ] 基线样本不足时有降级机制
- [ ] 增加单元测试覆盖冷启动场景

---

### A3. 多模型异常检测集成策略 ⏳

**优先级**：🟢 P3

**证据**：`server/src/app/algorithem/risk_graph/anomaly_models.py`

**当前实现**：5 个模型独立输出（`robust_statistics / isolation_proxy / local_outlier / temporal_jump / periodic_deviation`），无集成。

**问题**：
- 多模型同时报警时聚合规则未定义
- 单模型 vs 多模型共识的严重度差异未体现
- 模型间冲突无裁决机制

**改进方向**：
- 引入 `AnomalyEnsembler` 集成层
- 输出 `consensus_score` + `model_disagreement_flag`
- 高风险图谱评分区分"单点异常"和"多维共识异常"

**验收标准**：
- [ ] 实现集成层并接入 engine.py
- [ ] 集成结果包含共识度指标
- [ ] 单元测试覆盖各种模型组合情况

---

### A4. LLM 票据分类与字段置信度 ⏳

**优先级**：🟠 P1

**证据**：
- `server/src/app/services/document_intelligence.py:143-153`（`_classify_with_model` 当前 `return None`）
- `server/src/app/services/document_intelligence.py:20-37`（字段抽取全正则）

**问题**：
- 规则层单点支撑，非标准票据格式失效
- 无字段级置信度评分，无法判断哪些抽取值需要人工复核
- LLM 分类合并策略代码已存在但未启用

**改进方向**：
1. 启用 LLM 分类层（合并逻辑可直接复用）
2. 字段抽取增加置信度：`{field: {value, confidence, source}}`
3. 低置信度字段（< 0.7）自动标记"需人工核对"

**验收标准**：
- [ ] LLM 分类层启用并通过对比测试
- [ ] 每个抽取字段附带置信度评分
- [ ] 低置信度字段触发人工复核标记
- [ ] 提供准确率回归测试集

---

### A5. 票据分类持续学习 ⏳

**优先级**：🟢 P3

**证据**：`server/src/app/services/document_intelligence_rules.py:120`（`score_bias` 硬编码）

**问题**：新票种（ETC 电子票、滴滴行程单新模板）需开发改代码才能识别。

**改进方向**：
- 分类规则做成可配置 + 可学习
- 管理员上传样本自动更新关键词权重
- 基于历史已分类票据做 TF-IDF 训练

**验收标准**：
- [ ] 后台提供分类规则管理界面
- [ ] 新票种可通过样本上传识别
- [ ] 历史数据可训练关键词权重

---

### A6. Prompt 模板集中管理 ⏳

**优先级**：🟢 P3

**证据**：
- `server/src/app/services/ontology_extraction.py`
- `server/src/app/services/ontology_detection.py`
- `server/src/app/services/risk_rule_generation.py`
- `server/src/app/services/user_agent_response.py`
- `server/src/app/services/user_agent_application.py`
- `server/src/app/services/user_agent_review_core.py`
- `server/src/app/services/knowledge_rag.py:214`（查询重写硬编码在方法内）

**问题**：
- Prompt 散落在 12+ 文件，无版本化、无回滚、无 A/B 测试
- 相同意图的 prompt 在不同 service 中重复

**改进方向**：
- 建立 `prompts/` 集中目录 + `PromptRegistry`
- 按 `(意图, 版本)` 管理
- 支持灰度发布和效果对比

**验收标准**：
- [ ] 所有 prompt 迁移到集中目录
- [ ] 支持版本化与回滚
- [ ] 提供 A/B 测试接口

---

### A7. LLM 幻觉检测与事实校验 ⏳

**优先级**：🟠 P1

**证据**：当前系统缺少 LLM 输出的显式幻觉检测。本体解析有 `confidence` 门禁，但生成的解释文本、规则建议、对话回复无校验。

**问题**：
- LLM 可能编造不存在的政策条款、错误金额阈值、虚构审批人
- 风险图谱解释文本幻觉会误导审批人
- 唯一兜底是 `data_quality_gate`，仅管输入数据质量

**改进方向**：
- 关键输出（金额、政策条款、规则编号）做 grounded check：LLM 输出后用规则引擎反向校验
- 对话回复中的具体数字、日期强制引用证据片段（RAG 引用）

**验收标准**：
- [ ] 关键数值字段有反向校验机制
- [ ] 对话回复中的事实声明可追溯到证据
- [ ] 校验失败时有明确降级策略

---

### A8. 规则冗余/相关性建模 ⏳

**优先级**：🟢 P3

**证据**：`server/src/app/services/risk_rule_scoring.py`（多规则命中简单求和/max）

**问题**：相关规则同时命中时分数被夸大。如 `preapproval_absent` 和 `date_outside_trip` 可能高度相关。

**改进方向**：引入规则相关矩阵，对相关规则命中分数做去冗余折扣。

**验收标准**：
- [ ] 建立规则相关矩阵
- [ ] 命中聚合时考虑冗余
- [ ] 测试验证去冗余效果

---

### A9. 行为画像 fairness 保护 ⏳

**优先级**：🟢 P3

**证据**：`server/src/app/algorithem/employee_behavior_profile.py:345`（`evaluate_weighted_profile` / `calculate_review_priority_score`）

**问题**：行为画像影响审核优先级，若基于受保护属性（性别/年龄）产生系统性偏差，会构成隐性歧视。

**改进方向**：
- 增加 fairness audit 接口（按人群分组统计风险分布）
- 评分特征显式排除受保护属性
- 定期输出偏差报告

**验收标准**：
- [ ] 评分特征清单明确排除受保护属性
- [ ] 提供 fairness audit API
- [ ] 定期偏差报告生成

---

### A10. 算法模块 800 行拆分 ⏳

**优先级**：🟢 P3（与 B10 同源，单独追踪算法模块进度）

**证据**：
- `server/src/app/algorithem/employee_behavior_profile_tag_rules.py`: **812 行** 🔴
- `server/src/app/algorithem/risk_graph/engine.py`: **794 行** 🟡 临界

**改进方向**：
- `employee_behavior_profile_tag_rules.py` 按标签类别拆分（差旅类 / 招待类 / 办公类）
- `engine.py` 的 5 个评分维度（rule/anomaly/graph/policy/history）拆为 5 个独立打分器

**验收标准**：
- [ ] 所有算法文件 ≤ 800 行
- [ ] 拆分前后行为等价（单元测试通过）
- [ ] 拆分后职责边界清晰

---

## 二、业务层面改进

### B1. 审批流转交/加签/撤回/会签 ⏳

**优先级**：🔴 P0

**证据**：
- `server/src/app/services/expense_claim_workflow_constants.py`（仅 11 行固定阶段）
- `server/src/app/services/expense_claim_approval_flow.py:28`（`approve_claim` 串行硬编码）
- 转交/加签/撤回代码中**不存在**

**问题**：
- 费控系统核心能力缺失
- 现实中领导出差无法审批是常态
- 无并行审批（会签），多人审批只能串行
- 审批节点调整需改代码

**改进方向**：
- 引入审批矩阵：`费用类型 × 金额区间 × 部门` → 审批节点列表
- 支持节点动作：`{approve, reject, return, transfer, countersign, withdraw, add_approver}`
- 短期优先实现"转交"和"撤回"两个最常用动作

**验收标准**：
- [ ] 支持转交（审批人转给他人）
- [ ] 支持撤回（提交人在审批中撤回）
- [ ] 支持加签（临时增加审批节点）
- [ ] 支持会签（多节点并行）
- [ ] 审批矩阵可后台配置
- [ ] 关键操作有审计日志

---

### B2. HTTP Header 权限漏洞修复 ⏳

**优先级**：🔴 P0（安全）

**证据**：`server/src/app/api/deps.py:33-213`，通过 `X-Auth-Username / X-Auth-Role-Codes / X-Auth-Is-Admin` 等请求头识别身份。

**问题**：
- **任何人只要在请求头加 `X-Auth-Is-Admin: true` 就能获得管理员权限**
- 没有 token、没有签名、没有任何校验
- 足以让所有费控规则形同虚设

**改进方向**：
- 引入真正的身份认证（JWT 或 session cookie）
- 角色信息从服务端 session/token 获取，**绝不信任客户端传来的角色声明**
- 短期方案：前置网关（nginx）剥离这些头并注入真实身份

**验收标准**：
- [ ] 客户端无法通过伪造 Header 越权
- [ ] 所有角色信息来自服务端校验
- [ ] 现有 API 行为兼容（不破坏调用方）
- [ ] 安全测试覆盖权限边界

---

### B3. 申请单与报销单拆表 ⏳

**优先级**：🟡 P2

**证据**：
- `server/src/app/models/financial_record.py`：`ExpenseClaim` 通过 `expense_type` 后缀 + `claim_no` 前缀区分
- `server/src/app/models/reimbursement.py`：`ReimbursementRequest` 几乎废弃（service 仅 54 行 CRUD）

**问题**：
- 查询复杂度高，每个查询都要带 `expense_type IN (...)` 过滤
- 字段冗余（申请单无发票字段但表里有）
- 业务语义混乱（"claim"分不清是申请还是报销）
- 索引难优化

**改进方向**（需决策）：
- 方案 A（保守）：保留单表，增加 `claim_kind` 字段（`application` / `reimbursement`）显式区分
- 方案 B（彻底）：拆分为 `ExpenseApplication` + `ExpenseReimbursement` 两张表，通过 `application_id` 外键关联
- **涉及数据迁移，需用户确认方案**

**验收标准**：
- [ ] 方案决策完成
- [ ] 数据迁移脚本可重入、可回滚
- [ ] 迁移前后数据等价校验
- [ ] 现有 API 行为兼容或平滑升级

---

### B4. 可配置审批矩阵 ⏳

**优先级**：🟡 P2

**证据**：`server/src/app/services/expense_claim_approval_routing.py`（`_APPLICATION_BUDGET_REVIEW_USAGE_THRESHOLD = 90%` 等阈值硬编码）

**问题**：什么金额走什么审批、什么情况要预算管理者介入，全部硬编码。不同公司/部门差异大，无法运维配置。

**改进方向**：建立审批矩阵配置表：
```
approval_matrix(expense_type, amount_range, department_level, risk_level) 
  → [approver_roles, parallel_or_serial, sla_hours]
```
管理员后台维护，系统按矩阵动态生成审批流。

**验收标准**：
- [ ] 审批矩阵可后台配置
- [ ] 系统按矩阵动态生成审批流
- [ ] 配置变更有版本和审计
- [ ] 矩阵未命中时有合理默认值

---

### B5. 预算管控跨期/跨科边界 ⏳

**优先级**：🟢 P3

**证据**：
- `server/src/app/services/budget.py`（780 行）
- `server/src/app/services/expense_claim_budget_flow.py`（112 行）
- 预算占用/释放/核销/转移已实现，但边界场景验证不足

**潜在漏洞**：
- 跨财年结转：去年冻结的预算今年初未释放
- 跨期占用：Q1 提交的申请 Q2 才审批，占用的是哪个季度？
- 跨科目调剂：差旅预算不够能否临时挪用办公预算？
- 无对应单元测试

**改进方向**：
- 增加预算状态周期性对账任务（每日扫描 orphan reservation）
- 跨期策略明确化（默认跟随申请提交期，可配置）
- 补充跨期/跨科目单元测试

**验收标准**：
- [ ] 跨期/跨科目边界单元测试覆盖
- [ ] 周期性对账任务上线
- [ ] orphan reservation 自动清理

---

### B6. 规则覆盖不均衡补齐 ⏳

**优先级**：🟠 P1

**证据**：`server/rules/risk-rules/` 38 条规则分布：
- 差旅（travel）：13 条
- 预算（budget）：13 条
- 申请（application）：5 条
- 报销（reimbursement）：7 条
- 标准（standard）：5 条

**问题**：
- **招待费、市场推广、培训费、福利费、软件服务费几乎没有专门规则**
- 缺少供应商关联方交易、连号发票重复报销、跨年度重复报销检测
- 这些恰是真实费控场景最易出问题的领域

**改进方向**：
1. 招待费规则（参与人数缺失、人均超标、同城招待、节假日招待）
2. 供应商风险规则（同一供应商高频、关联方、工商信息异常）
3. 重复报销检测（发票号哈希去重、跨期扫描）

**验收标准**：
- [ ] 招待费规则集（≥5 条）
- [ ] 供应商风险规则集（≥3 条）
- [ ] 重复报销检测规则（≥2 条）
- [ ] 每条新规则有对应单元测试

---

### B7. 审计日志防篡改 ⏳

**优先级**：🟢 P3

**证据**：
- `server/src/app/models/audit_log.py`
- `server/src/app/services/audit.py`（72 行）
- before/after JSON 快照完整，但**无 hash chain 或数字签名**

**问题**：数据库管理员（或有 DB 写权限的人）可静默篡改审计日志。

**改进方向**：
- 每条日志附加 `prev_hash + current_hash = sha256(prev_hash + payload)`
- 定期锚定到外部存证（区块链 / 公证处 / WORM 存储）

**验收标准**：
- [ ] 审计日志实现 hash chain
- [ ] 篡改可被检测
- [ ] 外部存证机制（至少文档化）

---

### B8. 审批 SLA 与时效监控 ⏳

**优先级**：🟢 P3

**证据**：审批节点无超时提醒代码。

**问题**：单据卡在某领导处一周无人管，系统无感知。

**改进方向**：
- 每个审批节点配置 SLA（如 24h/48h）
- 后台定时任务扫描超时单据
- 自动催办 / 升级到上级 / 转交

**验收标准**：
- [ ] SLA 可配置
- [ ] 超时自动催办
- [ ] 超时升级机制
- [ ] SLA 报表可查

---

### B9. 支付与凭证对接 ⏳

**优先级**：🟢 P3（业务延伸方向）

**证据**：状态机到 `paid` 就结束，无银企直连、无会计凭证生成。

**问题**：报销审批通过后仍需财务人工付款、手工录凭证，未形成完整闭环。

**改进方向**：
- 银企直连（用友 / 金蝶 / 远光 API）
- 自动生成会计凭证（借：管理费用-差旅，贷：银行存款/应付职工薪酬）

**验收标准**：
- [ ] 至少接入一个财务系统
- [ ] 凭证自动生成
- [ ] 支付状态回传

---

### B10. 800 行硬约束拆分（业务模块） ⏳

**优先级**：🔴 P0

**证据**：services/ 下 ≥ 800 行的文件，共 **20 个**：

| 文件 | 行数 | 超标幅度 |
|---|---|---|
| `services/user_agent_application.py` | 1451 | +81% |
| `services/risk_rule_template_executor.py` | 1164 | +45% |
| `services/expense_claim_draft_flow.py` | 1064 | +33% |
| `services/expense_claims.py` | 1042 | +30% |
| `services/receipt_folder.py` | 1034 | +29% |
| `services/steward_planner.py` | 935 | +17% |
| `api/v1/endpoints/agent_assets.py` | 925 | +16% |
| `services/orchestrator_execution.py` | 900 | +12.5% |
| `services/finance_dashboard.py` | 884 | +10.5% |
| `services/knowledge_rag.py` | 877 | +9.6% |
| `services/settings.py` | 873 | +9.1% |
| `services/agent_assets.py` | 856 | +7% |
| `services/employee.py` | 850 | +6.25% |
| `services/employee_behavior_profile_service.py` | 823 | +2.9% |
| `services/risk_rule_generation.py` | 821 | +2.6% |
| `services/agent_foundation_asset_topup.py` | 809 | +1.1% |
| `services/ontology_extraction.py` | 808 | +1% |
| `services/demo_company_simulation_seed.py` | 805 | +0.6% |
| `services/knowledge.py` | 800 | 临界 |
| 另约 20 个文件在 700-800 行区间 | | 🟡 |

**前端超大文件**：

| 文件 | 行数 |
|---|---|
| `web/src/views/scripts/TravelReimbursementCreateView.js` | 4066 🔴🔴 |
| `web/src/views/scripts/TravelRequestDetailView.js` | 2861 🔴🔴 |
| `web/src/views/scripts/useTravelReimbursementSubmitComposer.js` | 2173 🔴🔴 |
| `web/src/composables/useRequests.js` | 1799 🔴 |
| `web/src/views/scripts/travelReimbursementReviewModel.js` | 1662 🔴 |
| 多个 `.vue` 文件 | 800-1130 🔴 |

**改进方向**：
- 按 AGENTS.md 既定的拆分原则（编排 / 状态 / 持久化 / 权限 / 文件存储 / OCR / 规则审核 / 响应构建 / 序列化）逐个拆
- 优先 Top 5：`user_agent_application` / `risk_rule_template_executor` / `expense_claim_draft_flow` / `expense_claims` / `receipt_folder`
- 每次拆分配套定向测试

**验收标准**：
- [ ] 所有类/文件 ≤ 800 行
- [ ] 拆分前后行为等价（测试通过）
- [ ] 拆分后职责边界清晰
- [ ] CI 中加入行数检查（防止回潮）

---

## 三、推进原则

1. **P0 优先**：B2（安全）、B1（核心能力）、B10（共识）必须先行。
2. **算法优化在 P0 落地后做**：再准的算法也会被权限漏洞和流程缺失抵消。
3. **小步快跑**：每项改进拆成可独立验证的子任务，配套测试。
4. **不破坏既有协议**：对外 API 尽量稳定，内部实现先拆。
5. **800 行约束**：所有改动前后检查受影响类行数，CI 加入行数门禁。

---

## 四、变更日志

| 日期 | 变更 | 操作人 |
|---|---|---|
| 2026-06-18 | 路线图初始版本，基于代码库全量评估生成 | Sisyphus |
