feat(platform): close AI expense value loop
Add tenant-safe value, telemetry, connector, commercial, and production-readiness foundations.
This commit is contained in:
caoxiaozhu
@@ -0,0 +1,157 @@
|
||||
# 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 计量边界。
|
||||
|
||||
## 方案设计
|
||||
|
||||
```mermaid
|
||||
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"]
|
||||
```
|
||||
|
||||
核心边界如下：
|
||||
|
||||
1. 认证层生成可信 `CurrentUserContext`，业务入口不得从请求体补造身份。
|
||||
2. 业务服务以 `tenant_id` 作为第一层 SQL 条件，ORM 复合外键和数据库约束作为第二层保护。
|
||||
3. 状态与业务事件在同一事务提交；外部副作用和资源计量使用稳定请求 ID、追加事实和补偿状态。
|
||||
4. 学习只消费可信服务端事实；自由文本评论、mock 数据和未确认推断不得进入训练或价值 KPI。
|
||||
5. 分析投影只读事实账本，并保留币种、时间窗口、证据等级和数据质量状态。
|
||||
|
||||
## 数据与契约
|
||||
|
||||
- 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 管理等产品扩展；它们不阻断本轮六步收口，但属于“完整产品愿景”后续工作。
|
||||
Reference in New Issue
Block a user