Files

caoxiaozhu 787bc3a481 feat(platform): close AI expense value loop

Add tenant-safe value, telemetry, connector, commercial, and production-readiness foundations.

2026-07-17 14:14:08 +08:00

11 KiB

Raw Permalink Blame History

AI 费用闭环工程收口与生产就绪边界

日期：2026-07-17

功能一句话

把 X-Financial 收口为一条租户安全、可学习、可解释、可计量的费用闭环：用户从申请、票据、报销、预审、审批到付款归档尽量少填少等，企业能看见风险、节省和真实成本，同时不把模拟数据包装成生产价值。

背景与问题

此前系统已经有申请、报销、审批、AI 助手和分析页面，但存在四类系统性断点：

业务链路能跑，但申请、票据、审批、支付、ERP、归档和价值事实没有统一闭环。
AI 能给建议，但用户反馈、工作流结果、记忆、few-shot 和发布质量没有形成受控学习链。
单租户演示可用，但员工、知识、规则资产、Hermes、报告、缓存、向量库和文档编辑仍有跨租户风险。
能展示费用，却不能严格区分确认现金节省、工时价值、风险暴露、预计机会、平台收入和内部成本。

本轮工程改造围绕上述断点逐步完成，不以页面数量或 mock 日志作为完成标准。

目标与非目标

目标

完成申请到付款、ERP、归档和冲回的可验证费用链路。
让 AI 从可信的字段修改、提交、审批、付款、风险处置和人工标签中学习，并保留解释、撤销和发布门禁。
对本轮纳入的 Claim、Employee、Agent Asset、Knowledge、Ontology、Hermes、Report 等共享核心数据建立可信会话、显式租户、复合约束、首层查询过滤和跨租户失败关闭；仍以 JSON 保存 tenant 的 legacy 状态继续列为后续迁移。
建立 Savings Ledger、CFO 价值看板、商业权益、资源计量、客户 ROI、平台成本和定价走廊。
将大型 Service 按访问策略、身份解析、持久化、规则、附件、计量和投影职责拆分，受代码体积门禁的核心类/组件保持低于 800 行。

非目标

不替客户决定首个支付/ERP provider、签名映射、会计期间、汇率来源、退款口径或大额双签阈值。
不用 mock 回执冒充真实现金、真实开票、真实回款或真实客户 ROI。
不在没有生产域名、可信 TLS、备份副本和真实 SMTP 的情况下声称完成生产上线。
不以一次工程验证替代 30/90 天真实企业试点和商业定价验证。

用户与场景

员工：通过 AI 预填、票据归集、结构化预审和断点续办，减少填表和退回。
直属领导、预算负责人和财务：在租户安全的任务队列中处理例外、风险、豁免、支付和财务确认。
CFO/管理层：按币种和证据等级查看节省、机会、周期、预算、风险护栏和数据质量。
租户管理员：管理企业知识、规则资产、记忆、报告配置和商业权益，但不能越权替业务人员自证。
平台运营：管理套餐、订阅、计量、成本、发布门禁和连接器配置，不能跨租户读取业务正文。

功能能力

费用闭环

Expense Case、Link、Business Event 将申请、票据、报销、预审、审批、付款、ERP、归档和冲回串成可回放链路。
服务端预览决策、预审握手、审批动作和风险处置使用版本、指纹、请求 ID、事务和乐观前置条件防止陈旧重放。
财务连接器区分 production-mode 外部事件契约、内部人工确认和 test/mock/staging 模拟事实；错误金额、币种、单据或状态不会推进付款，真实外部现金仍须 provider 联调证明。

越用越智能

AI Decision、Feedback、Workflow Outcome、Memory Evidence 和 few-shot 按租户、主体、场景、规则版本与证据等级隔离。
个人及企业/部门低敏偏好可解释、可过期、可撤销；企业规则和当前输入始终高于个人记忆。
发布遥测从真实 observation、可信人工 label、盲审负样本和保守 recall 进入 Canary/Release Guard；证据不足保持 collecting。

风险与安全

不透明 Bearer 会话是身份事实；请求中的 tenant、actor、reviewer、role 不能覆盖服务端上下文。
Employee、Claim、Agent Asset、Knowledge、Ontology、Hermes、Report、Qdrant、文件路径和缓存键均按租户隔离。
ONLYOFFICE 使用数据库一次性会话、资源绑定 token、DNS/IP 校验、可信 origin、大小/MIME/OOXML 校验和重放拒绝。

节省与商业闭环

Savings Ledger 分离 baseline、opportunity、realization、evidence 和 append-only event；未确认结果不进入确认现金 KPI。
CFO 看板将现金、工时、风险暴露和预计机会分开，并显式展示 collecting、unavailable 和 coverage gap。
商业层分离套餐、订阅、权益、用量、内部成本、账期、客户 ROI、贡献毛利和定价建议。
Orchestrator、OCR、Runtime Chat、连接器和附件源文件写入均接入权威 permit/reserve/commit/release 计量边界。

方案设计

flowchart LR
  A["申请与票据"] --> B["服务端预览与预审"]
  B --> C["审批任务与风险处置"]
  C --> D["支付/ERP 连接器"]
  D --> E["归档与冲回"]
  B --> F["反馈、记忆与 few-shot"]
  C --> F
  D --> G["Savings Ledger"]
  E --> G
  G --> H["CFO 价值与 ROI"]
  A --> I["商业预占与计量"]
  B --> I
  D --> I
  F --> J["盲审遥测与 Release Guard"]

核心边界如下：

认证层生成可信 CurrentUserContext，业务入口不得从请求体补造身份。
业务服务以 tenant_id 作为第一层 SQL 条件，ORM 复合外键和数据库约束作为第二层保护。
状态与业务事件在同一事务提交；外部副作用和资源计量使用稳定请求 ID、追加事实和补偿状态。
学习只消费可信服务端事实；自由文本评论、mock 数据和未确认推断不得进入训练或价值 KPI。
分析投影只读事实账本，并保留币种、时间窗口、证据等级和数据质量状态。

数据与契约

Alembic 正式链从 Expense Case、认证、AI 学习一直升级到 20260717_0028，migration-owned 表由启动前置检查统一管理。
20260716_0015 至 0024 建立 Savings、商业计量、连接器、发布遥测、账期、运行事件、盲审和资源数量口径。
20260717_0025 至 0028 建立租户身份、Agent Asset、Knowledge、Hermes/Ontology/Report 安全基础。
关键 append-only 表由数据库 trigger 阻止 UPDATE/DELETE；幂等键和请求指纹区分安全重放与冲突载荷。
production-mode 签名事件、内部确认、模拟回执、确认节省、预计机会、收入和成本使用不同类型，不互相降级替代；本地自签事件不作为真实现金证据。

算法与规则

硬配额：used + held + requested <= hard_limit，预占在业务提交后结算，回滚后释放并允许同账期安全重试。
确认现金节省：仅汇总 finance_confirmed + canonical + cash 的 realization，冲回通过负向追加事实抵消。
客户 ROI：按币种分别计算确认价值与客户费用，不跨币种强行相加；证据不足返回 unavailable。
贡献毛利：平台收入减去可归属模型、OCR、存储、连接器和其他运行成本；内部成本与客户价值分账。
定价走廊：成本下限、确认价值上限、成功费封顶和合同约束共同决定建议，系统不自动替客户签订价格。
发布门禁：只有 observation、独立可信 label、盲审负样本和保守置信下界达到阈值才允许晋级；失败或 collecting 保持 stable。

测试方案

所有后端、集成、迁移和依赖验证以 Docker 容器 local-x-financial-linux 的 /app 为唯一事实来源，单命令限制 60 秒。

后端：176 个测试文件按有界分片或专项运行，费用主服务 121 项单独回归；所有检查通过，条件跳过的 PostgreSQL 项随后在真实 PostgreSQL 探针补跑。
PostgreSQL：fresh schema、完整 upgrade/downgrade/re-upgrade、复合租户约束、append-only、迁移保护和并发专项最终 87 passed / 0 skipped / 0 failed，最终 head 为 20260717_0028。
前端：Node 全量 815 passed / 0 failed，Vite production build 通过；仅保留 chunk size 提示。
移动端：npm run lint 与 npx tsc --noEmit 通过；真实移动 API 与设备浏览器链路仍属于上线验收。
静态质量：所有 197 个新增 Python 文件通过 Ruff；目标模块 compileall、受门禁核心类/组件 800 行检查和 git diff --check 通过。全仓 Ruff 仍包含既有基线格式债，不在本轮批量改写用户已有代码。

指标与验收

工程验收

A1：申请到支付/ERP/归档/冲回的纵向事实链可通过 E2E 重放。
A2：现金、工时、风险和预计机会分账，缺数据不伪造为 0。
A3：身份、租户、角色、业务范围和双人复核在服务端及数据库层失败关闭。
A4：费用基线、预算、异常归因、节省漏斗和 CFO 下钻使用租户安全事实。
A5：商业权益、配额、账期、用量、成本、ROI、毛利和定价建议可审计。
A6：AI 反馈、记忆、few-shot、盲审、Canary 和回滚均有证据等级和降级路径。
A7：迁移、并发、后端、前端、移动静态检查和差异检查形成可重复验证记录。
A8：文档明确区分工程完成、生产上线和真实商业验证，不用 mock 冒充后两者。

真实试点指标

以下指标必须由首个企业在 30/90 天试点中建立基线后评估：报销创建时间、自动填充率、首次提交完整率、退回率、人工触点、完成周期、风险反馈、确认现金节省、工时价值、客户 ROI 和平台贡献毛利。

本轮实现记录

本轮约定的六个工程步骤已完成：商业资源计量与 EmployeeService 拆分、Expense Claim 访问策略与身份解析拆分、全链租户安全、后端/迁移/并发验证、前端/移动静态验证，以及文档与 bug 记录收口。

这六步范围内不再存在需要继续编码才能证明的阻断项。生产上线和商业验证仍需要目标环境与客户决策；上位长期路线图中统一 Outbox/legacy 清理、移动实机闭环、供应商事实和高级 AI 管理等扩展能力也没有被本轮文档悄悄标成完成，详见同目录 TODO.md 第 6-8 节。

风险与开放问题

ONLYOFFICE 生产下载域名必须在应用容器解析为允许的公网地址并使用可信 TLS；开发网络的保留地址会按设计拒绝。
0025 → 0028 必须在生产备份副本演练历史归属和受控回滚，不能用 disposable 空库代替真实数据演练。
首个支付/ERP provider、字段映射、SLA、会计期间、汇率、批次拆分、退款和大额双签需要客户确认。
SMTP、企业报告收件人和实际投递审计需要逐租户配置。
消息平台、移动设备真实流程、浏览器关键链路和私有部署安全验收需要目标环境联调。
30/90 天基线、客户财务签字、目标毛利、价值分享比例、合同、税率、开票和回款边界不能由代码自行完成。
上位长期路线图仍保留统一 correlation/Outbox、旧模型收敛、完整移动端、供应商事实、消息/SSO 模板、数据导出与高级 AI 管理等产品扩展；它们不阻断本轮六步收口，但属于“完整产品愿景”后续工作。

11 KiB Raw Permalink Blame History Unescape Escape