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
parent 242d68c36f
commit 787bc3a481
507 changed files with 82072 additions and 6344 deletions
--- a/document/development/2026-07-17/feature/engineering-closure-and-production-readiness/CONCEPT.md
+++ b/document/development/2026-07-17/feature/engineering-closure-and-production-readiness/CONCEPT.md
@@ -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 管理等产品扩展；它们不阻断本轮六步收口，但属于“完整产品愿景”后续工作。
--- a/document/development/2026-07-17/feature/engineering-closure-and-production-readiness/TODO.md
+++ b/document/development/2026-07-17/feature/engineering-closure-and-production-readiness/TODO.md
@@ -0,0 +1,81 @@
+# AI 费用闭环工程收口与生产就绪 TODO
+
+更新时间：2026-07-17
+
+关联方案：[CONCEPT.md](./CONCEPT.md)
+
+## 使用规则
+
+- 每项必须回链 `CONCEPT.md`；没有代码、迁移、接口、容器或真实环境证据不得勾选。
+- `[x]` 代表本轮工程范围已完成，不代表生产环境或真实商业试点自动完成。
+- mock/test/staging 只能验证契约和降级，不能证明真实现金、开票、回款、客户 ROI 或生产可用性。
+
+## 1. 功能闭环
+
+- [x] [CONCEPT: 费用闭环] 完成申请、票据、报销、预审、审批、付款、ERP、归档和冲回的可回放链路。
+  证据：Expense Case/Business Event、财务连接器、Savings Ledger；`test_expense_financial_value_chain_e2e.py` 与相关服务测试通过。
+- [x] [CONCEPT: 越用越智能] 完成可信反馈、工作流结果、个人/企业记忆、few-shot、盲审遥测、Canary 和 Release Guard。
+  证据：AI learning/memory、release telemetry/review/recall 模块；相关后端与 PostgreSQL 并发测试通过。
+- [x] [CONCEPT: 节省与商业闭环] 完成 Savings Ledger、CFO 价值看板、商业权益/计量/成本/ROI/定价建议。
+  证据：0015/0016/0019/0021/0024 迁移，Savings/CFO/Commercial 服务、端点和前端组件。
+
+## 2. 租户安全与代码结构
+
+- [x] [CONCEPT: 风险与安全] 收口 Bearer 会话、Claim、Employee、Agent Asset、Knowledge、Ontology、Hermes、Report、Qdrant、文件和缓存租户边界。
+  证据：0025-0028 迁移与 tenant security 测试；生产 `CurrentUserContext` 无缺失 tenant 构造。
+- [x] [CONCEPT: 风险与安全] 完成 ONLYOFFICE 一次性会话、资源绑定、SSRF/DNS/IP、格式和重放保护。
+  证据：Agent Asset/Knowledge ONLYOFFICE 安全服务与回归测试。
+- [x] [CONCEPT: 目标与非目标] 完成大型核心模块职责拆分，保持受门禁核心类/组件低于 800 行。
+  证据：Employee 776 行、ExpenseClaimAccessPolicy 701 行；访问策略、身份解析、目录维护、附件计量等均为独立模块。
+
+## 3. 商业资源权威边界
+
+- [x] [CONCEPT: 节省与商业闭环] Orchestrator、OCR、Runtime Chat、连接器和附件写入接入 permit/reserve/commit/release。
+  证据：commercial direct/runtime bridge、connector observer、attachment commercial；资源组合 63 项、附件/端点 54 项通过。
+- [x] [CONCEPT: 算法与规则] 连接器仅按已认证且成功提交的事件计 `events=1`，附件仅按成功持久化源文件计 bytes。
+  证据：`test_commercial_resource_boundaries.py` 覆盖重放、冲突、鉴权失败、回滚、配额、重试和脱敏。
+- [x] [CONCEPT: 算法与规则] 回滚释放、同账期安全重试、硬配额和未配置兼容均保持事务正确。
+  证据：Direct、reservation、OCR、Runtime Chat、连接器和附件组合回归通过。
+
+## 4. 容器验证
+
+- [x] [CONCEPT: 测试方案] 后端 176 个测试文件完成有界分片或专项检查，费用主服务 121 项单独通过。
+  证据：所有分片退出码 0；条件 PostgreSQL 跳过已在真实探针补跑。
+- [x] [CONCEPT: 测试方案] fresh PostgreSQL 完成迁移、降级、再升级、并发和数据库约束专项。
+  证据：`87 passed / 0 skipped / 0 failed`，最终 head `20260717_0028`，一次性数据库已清理。
+- [x] [CONCEPT: 测试方案] Web 全量测试和生产构建通过。
+  证据：`815 passed / 0 failed`；Vite production build 通过。
+- [x] [CONCEPT: 测试方案] Mobile lint 与 TypeScript 静态检查通过。
+  证据：`npm run lint`、`npx tsc --noEmit` 均退出码 0。
+- [x] [CONCEPT: 测试方案] 新增 Python、编译、文件大小和差异质量门禁通过。
+  证据：197 个新增 Python 文件 Ruff 通过；目标 compileall、受门禁核心类/组件 800 行检查和 `git diff --check` 通过；全仓历史 Ruff 债单独披露。
+
+## 5. 文档与可追溯性
+
+- [x] [CONCEPT: 本轮实现记录] 回填 Savings、商业、连接器、发布遥测和上位 AI 闭环 TODO 的真实完成状态。
+  证据：2026-07-13、2026-07-16 对应功能文档及本目录。
+- [x] [CONCEPT: 本轮实现记录] 为本轮生产 bug 创建独立修复日志，并先完成 upstream/local-ahead 检查。
+  证据：`document/development/2026-07-17/dev-logs/bugs/`；`origin/main` 无新提交，本地 ahead 17 已记录。
+- [x] [CONCEPT: 指标与验收] 明确工程完成、生产上线、真实试点三种完成口径。
+  证据：CONCEPT“目标与非目标”“指标与验收”“风险与开放问题”。
+
+## 6. 生产上线（需要目标环境）
+
+- [ ] [CONCEPT: 风险与开放问题] 配置生产 ONLYOFFICE 允许 origin，并在应用容器验证公网 DNS、可信 TLS 和真实编辑回写。
+- [ ] [CONCEPT: 风险与开放问题] 在生产备份副本演练 `0025 → 0028`、历史默认企业归属、回滚保护和恢复。
+- [ ] [CONCEPT: 风险与开放问题] 为每个启用企业配置 SMTP、报告收件人并验证实际投递审计。
+- [ ] [CONCEPT: 风险与开放问题] 完成真实浏览器、移动设备、消息平台和私有部署环境的关键流程验收。
+
+## 7. 客户与商业验证（需要业务决策）
+
+- [ ] [CONCEPT: 风险与开放问题] 确认首个支付/ERP provider、签名、字段映射、SLA、重试、批次、汇率、会计期间、退款和大额双签口径。
+- [ ] [CONCEPT: 真实试点指标] 采集首个企业 30/90 天基线并验证效率、风险、现金节省、工时价值和客户 ROI。
+- [ ] [CONCEPT: 风险与开放问题] 由客户财务签字确认节省归因、去重、汇率、工时价值和报告口径。
+- [ ] [CONCEPT: 风险与开放问题] 冻结目标毛利、包含量、超额策略、价值分享、合同、税率、开票、回款、坏账和收入确认。
+
+## 8. 长期产品路线图（不属于本轮六步阻断）
+
+- [ ] [CONCEPT: 风险与开放问题] 统一所有阶段 correlation/事务 Outbox，并完成 `agent_conversations` 结构化租户、旧 `ReimbursementRequest`、`risk_flags_json` 和少见状态迁移。
+- [ ] [CONCEPT: 风险与开放问题] 完成移动端真实 API、拍照/OCR/票据/草稿实机闭环，以及全浏览器键盘、焦点和响应式验收。
+- [ ] [CONCEPT: 风险与开放问题] 接入租户化供应商/合同/单位价格事实、真实消息/SSO/电子档案模板、删除传播和数据导出。
+- [ ] [CONCEPT: 风险与开放问题] 扩展“我的 AI 记忆”、保留/敏感级别/动作上限配置，以及自动化依据、撤销、抽检和版本可视化。