787bc3a481
Add tenant-safe value, telemetry, connector, commercial, and production-readiness foundations.
238 lines
20 KiB
Markdown
238 lines
20 KiB
Markdown
# 商业计量、客户 ROI 与可持续定价 概念文档
|
||
|
||
更新时间：2026-07-17
|
||
|
||
## 功能一句话
|
||
|
||
把套餐、订阅、权益、真实用量、内部成本、客户确认价值和平台毛利拆成可审计事实，并只在成本与价值证据同时成立时给出可持续定价走廊。
|
||
|
||
## 背景与问题
|
||
|
||
- 平台要成为可长期经营的产品，既要证明客户省了钱，也要知道每个租户消耗了多少 OCR、AI、存储、连接器和支持成本。
|
||
- “风险金额”“预计节省”“流程耗时”不能直接作为客户 ROI；平台收入、平台内部成本和客户价值也不能混在一个指标里。
|
||
- 只有套餐创建而没有暂停、取消、历史查询和配额硬门禁，商业后台无法真正运营。
|
||
- 仅在执行前读取 `SUM(usage)` 再放行无法抵抗并发；两个工具可同时看到剩余额度并一起执行，事后计量再准确也已形成不可逆超卖。
|
||
- 固定拍一个价格无法适配客户规模、真实成本和价值覆盖。需要先计算平台可持续下限，再计算客户价值可接受上限；没有交集时不能强行报价。
|
||
- 试点期通常缺少 30/90 天真实成本和财务确认收益，因此系统必须显示“采集中”，而不是用 mock 或估计值伪造单位经济性。
|
||
|
||
本能力是 `2026-07-13/feature/ai-expense-closed-loop-and-value-proof` 中商业模式与价值证明部分的实施拆分。
|
||
|
||
## 目标与非目标
|
||
|
||
### 目标
|
||
|
||
- [G1] 建立租户隔离、版本化的套餐、订阅和权益配置。
|
||
- [G2] 建立追加式用量与内部成本事实，支持幂等、冲回、配额和并发门禁。
|
||
- [G3] 把商业权益门禁与安全门禁做收紧式合并，付费不能绕过高风险人工审核。
|
||
- [G4] 严格分开客户收费、内部成本、平台贡献毛利、财务确认现金节省、客户 ROI 和工时价值。
|
||
- [G5] 支持套餐/订阅/权益生命周期、历史查询、用量成本查询和数据质量状态。
|
||
- [G6] 根据真实成本和财务确认节省给出基础费下限、价值上限和可封顶成功费，不自动改合同。
|
||
- [G7] 形成“试点采集 → 基础订阅 → 基础费 + 封顶成功费”的可验证商业演进路径。
|
||
- [G8] 用不可变账期承载收费、用量、成本与配额历史，并对商业配置和自动续期保留脱敏追加式审计。
|
||
|
||
### 非目标
|
||
|
||
- [NG1] 不在代码中硬编码某个客户的最终价格、税率、折扣或合同条款。
|
||
- [NG2] 不把风险暴露、预计机会、未确认结果、未锁定汇率或未经客户认可的工时估值计入价值定价。
|
||
- [NG3] 不让套餐或配额放宽审批、风险、租户和人工确认门禁。
|
||
- [NG4] 不自建开票、税务、收款或第三方订阅扣费网络；只保存受控外部订阅引用。
|
||
- [NG5] 不跨币种直接求和，也不在缺少同币种成本/价值时生成综合 ROI。
|
||
- [NG6] 不把定价场景结果自动写成生效套餐，最终合同仍需平台商业负责人审批。
|
||
|
||
## 用户与场景
|
||
|
||
### 用户
|
||
|
||
1. 平台商业管理员：维护套餐版本、订阅、权益、状态和定价场景。
|
||
2. 平台运营/财务：查看用量、成本、毛利和异常数据质量。
|
||
3. 客户 CFO/财务负责人：查看自己租户的当前套餐、用量、配额和客户价值口径。
|
||
4. 产品运行时：在执行 OCR、AI 或连接器能力前检查配额，并写入真实用量。
|
||
|
||
### 核心场景
|
||
|
||
1. 试点客户先配置 `pilot` 套餐和明确的合同周期，开始采集真实用量、成本与已确认价值。
|
||
2. 运行时检查某项权益；只有商业配额允许且安全决策为 allow 时才最终允许。
|
||
3. 同一用量事件重试返回首次结果；不同内容复用幂等键返回冲突。
|
||
4. 客户暂停、逾期、取消或过期时，商业权益即时失败关闭，历史用量和成本不被删除。
|
||
5. 商业负责人选择 90 天窗口，输入目标贡献毛利率和客户最大价值分享比例，系统按币种输出定价走廊。
|
||
6. 成本下限高于价值上限时，系统建议先优化单位经济性或扩大可信价值，不生成强行报价。
|
||
|
||
## 功能能力
|
||
|
||
- [C1] 套餐版本：subscription、usage、hybrid、pilot、custom，支持生效区间和旧版本退役。
|
||
- [C2] 订阅快照：合同周期、计费周期、席位、基础费、外部订阅引用和状态历史。
|
||
- [C3] 权益与配额：feature、metered、unlimited，包含量、硬上限、重置周期和超额策略。
|
||
- [C4] 用量事实：usage、credit、adjustment、reversal，保存主体、来源、correlation 和首次请求指纹。
|
||
- [C5] 成本事实：AI、OCR、存储、连接器、支持、实施、基础设施、支付等分类及汇率快照。
|
||
- [C6] 商业分析：收费、成本、贡献毛利、确认节省、客户 ROI 和工时价值分账展示。
|
||
- [C7] 定价走廊：最低可持续收费、最高价值对齐收费、最大成功费和证据状态。
|
||
- [C8] 生命周期与查询：暂停、恢复、逾期、取消、过期，以及套餐/订阅/权益/用量/成本历史。
|
||
- [C9] 账期与审计：月/季/年自动续期、合同边界失败关闭、账期历史和商业管理追加审计。
|
||
|
||
## 方案设计
|
||
|
||
### 前端
|
||
|
||
- 商业工作台分为“当前账户”“套餐与订阅”“权益与配额”“用量与成本”“价值与定价”五块。
|
||
- 客户 ROI 与平台贡献毛利必须使用不同卡片、不同说明，不允许用一个“综合收益”混合展示。
|
||
- 多币种按币种分行；缺成本、缺确认价值、仅有试点数据和证据冲突使用不同状态。
|
||
- 暂停、取消和定价场景均需要确认；终态操作明确提示不能原地恢复。
|
||
- 普通客户财务只能查看本租户账户；平台级配置、成本、毛利和定价仅平台管理员可见。
|
||
|
||
### 后端
|
||
|
||
- `CommercialAdminService` 管理套餐、订阅、权益和状态转换。
|
||
- `CommercialBillingPeriodService` 签发和定位不可变账期；用量、成本和运行时预占必须绑定真实账期编号。
|
||
- `CommercialSubscriptionRolloverService` 在订阅行锁内按月/季/年边界幂等续期；合同制或跨越 `ends_at` 时失败关闭。
|
||
- `CommercialRolloverScheduler` 以 PostgreSQL advisory lock 选举单一执行者，再按订阅行锁串行签发到期账期。
|
||
- `CommercialAdminAuditService` 只记录字段白名单快照，排除合同正文、配置、外部订阅编号、元数据和凭证类字段。
|
||
- `CommercialQueryService` 负责租户范围内历史与追加事实查询。
|
||
- `CommercialEntitlementService` 计算配额和商业/安全合并门禁。
|
||
- `CommercialMeteringService` 写追加式用量和成本、执行幂等与冲回。
|
||
- `CommercialRuntimeReservationService` 在订阅/权益锁内完成执行前额度预占，管理 reserved、committed、released、expired、reconciliation_required 和 committed_reconciliation_required 状态。
|
||
- `CommercialRuntimeBridge` 把可信 AgentRun、中央工具执行、真实 AgentToolCall 和商业事实接成预占—执行—结算链；未配置商业计量时保持兼容。
|
||
- `CommercialRuntimeReconciler` 只根据可验证的工具/运行终态补偿过期预占，不按超时猜测业务是否发生。
|
||
- `CommercialAnalyticsService` 按窗口和币种分账聚合，不伪造缺失数据。
|
||
- `CommercialPricingService` 只读分析真实成本和确认节省，输出价格区间，不写套餐。
|
||
- HTTP 管理入口仅平台管理员可用；租户账户读取仅 finance、executive 或平台管理员可用。
|
||
|
||
### 算法/规则
|
||
|
||
- 用量硬配额在数据库锁内计算，最终用量超过限制时整个写入失败。
|
||
- 真实工具执行前按 `已用量 + 有效预占 + 本次预占 <= 硬上限` 原子判断；成功时真实量不得超过预占，失败/阻断只释放预占，不写用量或成本。
|
||
- call 基准可直接预占一次；token、duration 等变量基准必须由执行器声明并强制最大量。缺少可信 hard max 时拒绝执行，不用正文长度或估算值代替。
|
||
- 已有相同 tool call 的预占请求按指纹稳定重放；真实 AgentToolCall 的用量/成本继续使用追加式幂等键。用量已写入但成本失败时进入 `committed_reconciliation_required`，重试只补缺失成本，不重复占用额度或追加用量。
|
||
- 权益已有用量后，配额、定价和有效期不可回改，只允许暂停/恢复；结构变化必须新建订阅版本。
|
||
- 客户 ROI 只使用财务确认 canonical 现金节省与客户收费。
|
||
- 贡献毛利只使用平台收费与内部成本，不混入客户节省。
|
||
- 定价只在相同币种内计算，并保留成本/价值证据状态。
|
||
|
||
### 数据
|
||
|
||
- `tenant_commercial_plans`：租户、套餐编码、版本、价格模型、基础费、币种、生效期和合同条款摘要。
|
||
- `tenant_subscriptions`：租户、套餐、周期、基础费快照、状态、席位、外部引用和版本。
|
||
- `commercial_entitlements`：租户、订阅、权益键、计量键、配额、状态和有效期。
|
||
- `usage_meter_events`：追加式用量、冲回引用、幂等键、请求指纹和关联链。
|
||
- `commercial_cost_events`：追加式内部成本、原币/报告币、汇率、分摊键和冲回引用。
|
||
- `commercial_runtime_reservations`：工具执行前的可变运营占位，保存 tenant/subscription/entitlement/run/tool call、基准、预占量、真实量、周期、配置快照、状态和补偿原因；它参与配额但不是客户用量事实。
|
||
- `commercial_billing_periods`：不可变账期签发事实，保存订阅/套餐引用、窗口、顺序、币种、基础费、席位、计价模式和来源快照；PostgreSQL 禁止更新和删除。
|
||
- `commercial_admin_events`：套餐、订阅、权益、账期和续期动作的脱敏追加审计，保存 tenant、actor、`X-Request-Id`、原因、动作、资源版本和白名单 before/after。
|
||
- `usage_meter_events.period_key` 表示真实账期键，`quota_period_key` 独立表示权益重置周期；成本与运行时预占同样通过 `billing_period_id` 绑定账期，避免订阅当前周期滚动后污染历史。
|
||
- 事实表在 PostgreSQL 使用触发器禁止 UPDATE/DELETE，租户复合外键防止跨租户引用。
|
||
|
||
运行时占位状态如下：
|
||
|
||
```text
|
||
reserved -> committed # 成功且 actual <= reserved
|
||
reserved -> released # 工具失败或执行前阻断
|
||
reserved -> expired # 运行已终止且没有真实工具调用
|
||
reserved -> reconciliation_required # 已发生调用但缺少执行前预占等人工补偿场景
|
||
committed -> committed_reconciliation_required -> committed
|
||
# 用量已提交、成本等后续事实失败，幂等补齐后恢复
|
||
```
|
||
|
||
过期但运行仍在进行、运行记录缺失或工具终态不确定时继续保留额度，不允许补偿器仅因 TTL 到期释放后造成超卖。
|
||
`committed_reconciliation_required` 已有真实用量事实，因此不再计入有效预占；配额只消费一次，同时保留明确的待补偿队列。
|
||
|
||
### 权限
|
||
|
||
- 平台管理员可配置所有租户商业账户，但商业配置不能授予财务确认或风险审批能力。
|
||
- finance/executive 只读本租户当前账户，不读取平台内部成本或其他租户数据。
|
||
- manager、employee 默认无商业账户与商业分析权限。
|
||
- 所有管理接口从认证上下文判断平台管理员，目标租户来自受控路径参数。
|
||
|
||
### 降级策略
|
||
|
||
- 无订阅：返回 unavailable 和明确说明，不自动赠送无限权益。
|
||
- 订阅非 active/trialing：配额保留展示但最终消费失败关闭。
|
||
- 缺成本：贡献毛利和可持续价格下限不可用。
|
||
- 缺财务确认价值：客户 ROI、价值上限和成功费不可用，建议继续试点采集。
|
||
- 多币种缺少共同币种：分别展示，禁止跨币种净额。
|
||
- 并发或幂等冲突：返回 409，不覆盖首次事实。
|
||
- 生产中央工具路径未配置 runtime meter：兼容执行且不生成商业事实；配置只在当前订阅周期和权益有效期内参与门禁，历史过期配置不会误触发 enforcement。
|
||
- 已发生的旧直接工具路径缺少执行前预占：不补写为正常用量，持久化 `reconciliation_required` 并冻结对应容量，等待受控补偿；即使当前合同已暂停，也保留其唯一可验证的租户、订阅和权益归属。
|
||
- 用量已追加但内部成本写入失败：持久化 `committed_reconciliation_required`，配额以真实用量为准且预占归零；按相同 tool call 重试只补成本，完成后回到 committed。
|
||
- 自动续期只处理 `trialing/active + auto_renew`；月、季、年按自然月边界滚动。合同制、缺少可推导边界或下一完整账期越过 `ends_at` 时失败关闭，不创建部分账期或猜测续约。
|
||
- 调度器即使发生重复扫描或多进程竞争，也先获取 leader lease，再锁定订阅；账期窗口和幂等键的唯一约束保证同一周期最多签发一次。数据库触发器还会按租户与订阅获取事务级 advisory lock，并拒绝任何半开区间重叠账期，防止绕过服务层直接写入破坏时间线。
|
||
|
||
## 算法与公式
|
||
|
||
### 客户 ROI
|
||
|
||
```text
|
||
customer_roi = (verified_cash_savings - customer_charges) / customer_charges
|
||
```
|
||
|
||
- `verified_cash_savings` 只包含独立财务确认、canonical、已计冲回的现金节省。
|
||
- `customer_charges` 来自订阅基础费快照和有可信同币种单价的用量计费。
|
||
- 分母必须大于 0；否则状态为 unavailable。
|
||
|
||
### 平台贡献毛利
|
||
|
||
```text
|
||
contribution_margin = customer_charges - internal_costs
|
||
contribution_margin_rate = contribution_margin / customer_charges
|
||
```
|
||
|
||
- 内部成本来自追加式成本账本，不使用估算页面数字。
|
||
|
||
### 可持续定价走廊
|
||
|
||
```text
|
||
minimum_sustainable_charge = internal_costs / (1 - target_margin_rate)
|
||
maximum_value_aligned_charge = verified_cash_savings * max_value_share
|
||
maximum_success_fee = max(0, maximum_value_aligned_charge - minimum_sustainable_charge)
|
||
```
|
||
|
||
- 当 `minimum_sustainable_charge <= maximum_value_aligned_charge` 时，建议 hybrid：基础费不低于成本下限，成功费封顶为剩余价值空间。
|
||
- 只有成本证据时建议 subscription；成本与价值都不足时建议 pilot_collecting。
|
||
- 成本下限高于价值上限时建议 optimize_unit_economics，不自动提高客户报价。
|
||
|
||
## 测试方案
|
||
|
||
- 模型/迁移：租户复合外键、状态检查、金额符号、冲回引用和 append-only。
|
||
- 服务：套餐版本、订阅终态、权益不可回改、配额硬门禁、幂等、冲回和多币种。
|
||
- 权限：平台管理员、租户财务、manager、employee 与跨租户访问。
|
||
- 分析：收费/成本/节省/毛利/ROI 分账，缺证据状态和 `as_of` 回放。
|
||
- 定价：可行区间、成本高于价值、仅成本、完全无证据和多币种。
|
||
- 前端：状态、权限、操作确认、空态、错误态、币种分组与生产构建。
|
||
- PostgreSQL：并发配额、同幂等键、成本冲回单赢家和迁移完整性。
|
||
- PostgreSQL 账期：0020→0021→0020 升降级、账期/审计 UPDATE/DELETE 拒绝、重叠账期 INSERT 拒绝、历史事实账期绑定和双线程续期单赢家。
|
||
- 运行时预占：无配置兼容、成功结算、失败释放、变量 hard max、真实量超预占、幂等重放、历史配置隔离、直接路径补偿和过期补偿。
|
||
- 所有命令在 `local-x-financial-linux` 容器内执行，单次最长 60 秒。
|
||
|
||
## 指标与验收
|
||
|
||
- [A1] 每个商业消费可追溯到租户、订阅、权益、用量事件、来源和 correlation。
|
||
- [A2] 并发不能突破硬配额；重复事件稳定重放，冲突内容被拒绝。
|
||
- [A3] 付费状态不能绕过安全或人工审核门禁。
|
||
- [A4] 客户 ROI、平台毛利、客户节省和工时价值在 API/UI 中不混算。
|
||
- [A5] 暂停、恢复、取消、过期和历史查询可操作，终态不可原地复活。
|
||
- [A6] 定价场景只使用真实同币种成本与确认节省；证据不足时不输出虚假价格。
|
||
- [A7] 相关后端、PostgreSQL、前端、构建、Ruff 与迁移验证在容器内通过。
|
||
|
||
## 风险与开放问题
|
||
|
||
- 真实计费仍需把 OCR、LLM、存储、连接器和支持运行事件自动接入用量/成本账本；手工管理员写入只能用于校验，不是最终生产采集。
|
||
- 中央 Orchestrator 工具已经执行前预占；绕过中央执行器的其他生产入口仍须逐一迁移到 permit 契约，当前只会形成可见补偿积压，不会伪装成正常计量。
|
||
- 合同制自动续期仍不推断新合同窗口；管理员或外部订阅连接器必须先提供显式续约事实，再创建后继合同/订阅版本。
|
||
- 首个客户的实际套餐金额、席位、包含量、毛利目标、价值分享比例和折扣需要商业负责人确认。
|
||
- 发票、税率、回款、坏账、渠道分成与收入确认尚未接入，当前 `customer_charges` 是合同/用量计费基准，不等同已收现金。
|
||
- 价值分享合同必须定义基线、排除项、冲回、确认人、封顶和争议期。
|
||
- 工时价值默认不进入现金 ROI，只有客户确认活跃工时基线、角色成本和可释放比例后才单独披露。
|
||
|
||
## 本轮实现记录
|
||
|
||
- 2026-07-16：完成五张商业事实表与 0016 迁移、套餐/订阅/权益、用量/成本、配额门禁、幂等和冲回服务。
|
||
- 2026-07-16：完成客户收费、内部成本、贡献毛利、财务确认现金节省、客户 ROI 和工时价值分账分析；修正 ROI 为净收益口径并收紧角色、时区和权益历史不可变边界。
|
||
- 2026-07-16：补齐订阅暂停/逾期/取消/过期、恢复和套餐/订阅/权益/用量/成本历史查询。
|
||
- 2026-07-16：完成基于真实成本下限与确认价值上限的定价场景，禁止风险暴露、预计节省或跨币种混入报价。
|
||
- 2026-07-16：完成商业工作台五块能力、订阅生命周期确认、用量/成本与价值分账、按币种定价场景两步确认；全量前端 802 项、code-size 和生产构建通过。
|
||
- 2026-07-16：一次性 PostgreSQL 17 并发配额、幂等和成本冲回 3 项通过；真实开票、回款与客户合同参数继续保留为外部试点边界，不以 mock 标记完成。
|
||
- 2026-07-16：新增 `0019` 运行时预占迁移和中央 Agent 工具 permit；在订阅/权益锁内按已用量加有效预占原子控额，成功按真实 AgentToolCall 结算，失败/阻断释放，变量用量超过预占拒绝写入。
|
||
- 2026-07-16：新增持久补偿状态和过期补偿器；旧直接调用缺少预占时冻结容量并进入 reconciliation_required，运行终态不确定时不按 TTL 误释放；用量已提交但成本失败进入 committed_reconciliation_required，相同预占与用量/成本均可幂等重试。
|
||
- 2026-07-16：新增 `0021` 不可变账期和商业管理审计；订阅创建即签发首期，月/季/年到期由 leader 调度器和订阅行锁幂等滚动，合同制与越界周期失败关闭。
|
||
- 2026-07-16：用量、成本、运行时预占和配额查询改为绑定 `billing_period_id`，并以独立 `quota_period_key` 保留权益重置语义；客户收费基础费改从账期快照聚合，不再读取可变订阅当前周期。
|
||
- 2026-07-16：容器内商业/迁移前置定向 131 项、前端商业 35 项和 Vite 构建通过；一次性 PostgreSQL 17 商业并发 5 项通过。0021 的升级、模型/约束/触发器（含账期重叠阻断）/运行不变量及 0021→0020 降级通过；全链 44/45 唯一失败来自后继 0023 尚未接管的盲审临时表，不属于 0021。
|
||
- 2026-07-16：容器内商业/Agent/迁移组合 183 项通过、1 项因未显式配置外部迁移库跳过；运行时定向 27 项、PostgreSQL 商业并发 4 项和 0019→0020 完整迁移循环通过；全局 code-size 仅剩共享 `RiskRuleGenerationService` 817 行既有门禁失败，本轮所有相关核心类低于 800 行。
|