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-16/feature/commercial-metering-and-roi/CONCEPT.md
+++ b/document/development/2026-07-16/feature/commercial-metering-and-roi/CONCEPT.md
@@ -0,0 +1,237 @@
+# 商业计量、客户 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 行。
--- a/document/development/2026-07-16/feature/commercial-metering-and-roi/TODO.md
+++ b/document/development/2026-07-16/feature/commercial-metering-and-roi/TODO.md
@@ -0,0 +1,87 @@
+# 商业计量、客户 ROI 与可持续定价 开发 TODO
+
+更新时间：2026-07-17
+
+## 使用规则
+
+- 每项必须回链 `CONCEPT.md` 对应章节。
+- 只有代码、接口或容器验证提供证据后才能勾选。
+- 客户价值、平台收入、内部成本和工时估值必须分账；mock 与手工事件不得标记为生产事实。
+
+## 1. 调研与边界
+
+- [x] [CONCEPT: 背景与问题] 明确商业权益、用量、成本、客户 ROI、平台毛利和定价不是同一事实。
+  证据：`CONCEPT.md`“背景与问题”“目标与非目标”。
+- [x] [CONCEPT: 目标与非目标] 确认不硬编码客户价格、不混算风险暴露、不跨币种求和、不让付费绕过安全门禁。
+  证据：`CONCEPT.md`“目标与非目标”。
+
+## 2. 契约与设计
+
+- [x] [CONCEPT: 数据] 定义套餐、订阅、权益、用量和内部成本五类事实及状态。
+  证据：`commercial.py` 模型与 schema、`20260716_0016_commercial_metering.py`。
+- [x] [CONCEPT: 算法与公式] 定义客户 ROI、贡献毛利和可持续定价走廊公式。
+  证据：`CONCEPT.md`“算法与公式”、`commercial_analytics.py`、`commercial_pricing.py`。
+- [x] [CONCEPT: 权限] 定义平台配置、租户只读和商业/安全门禁分离。
+  证据：`commercial_access_policy.py`、`commercial_entitlements.py`。
+
+## 3. 后端实现
+
+- [x] [CONCEPT: 数据] 新增五张商业表、复合租户约束、幂等、冲回和 append-only 迁移。
+  证据：`models/commercial.py`、`20260716_0016_commercial_metering.py`、迁移/模型测试。
+- [x] [CONCEPT: 数据] 新增运行时预占运营表、状态约束、复合租户外键、全局 tool call 幂等和迁移所有权。
+  证据：`models/commercial_runtime.py`、`20260716_0019_commercial_runtime_reservations.py`、`commercial_migration_assertions.py`；0019→0020 一次性 PostgreSQL 完整升降级循环通过。
+- [x] [CONCEPT: 后端] 实现套餐版本、订阅、权益、配额、用量、成本与商业分析服务。
+  证据：`commercial_admin.py`、`commercial_entitlements.py`、`commercial_metering.py`、`commercial_analytics.py`。
+- [x] [CONCEPT: 生命周期与查询] 实现暂停、逾期、取消、过期、恢复与五类历史查询。
+  证据：`CommercialAdminService.transition_subscription()`、`commercial_queries.py`、`/commercial/admin/tenants/{tenant_id}/...` 分资源接口。
+- [x] [CONCEPT: 定价走廊] 实现成本下限、确认价值上限、成功费封顶和商业模式建议。
+  证据：`commercial_pricing.py`、`POST /commercial/admin/tenants/{tenant_id}/pricing-scenarios`。
+- [x] [CONCEPT: 后端] 把中央 Orchestrator 工具接入执行前预占、真实 AgentToolCall 结算和失败释放。
+  证据：`orchestrator_tool_execution.py`、`agent_runs.py`、`commercial_runtime_bridge.py`；无配置兼容，配置后先 reserve 再执行，成功只追加真实用量/成本，失败和阻断不计量。
+- [x] [CONCEPT: 降级策略] 持久化缺预占和计量故障补偿状态，并安全处理过期预占。
+  证据：`commercial_runtime_reservations.py`、`commercial_runtime_reconciler.py`；直接调用形成 reconciliation_required，运行中/未知终态继续持有额度，终态无调用才过期释放；用量成功但成本失败形成 committed_reconciliation_required，重试只补成本且不重复冻结额度。
+- [x] [CONCEPT: 风险与开放问题] 把已识别的权威运行入口迁移到 permit 契约。
+  证据：中央 Orchestrator、`ocr_commercial.py`、`runtime_chat_commercial.py`、`financial_connector_commercial.py` 和 `expense_claim_attachment_commercial.py` 已接通预占/结算/释放；资源组合 63 项通过。
+- [ ] [CONCEPT: 风险与开放问题] 对后续新增的知识库/ONLYOFFICE 存储、实施和支持等资源入口持续执行 meter 盘点，不允许绕过 permit。
+  证据要求：新增真实资源入口时提供权威数量口径、事务边界、成本来源和回归测试；当前不把未发生的未来入口伪装成已计量。
+- [x] [CONCEPT: 风险与开放问题] 通过不可变 billing period 和幂等 rollover 实现 `auto_renew` 周期滚动。
+  证据：`20260716_0021_commercial_billing_periods.py`、`commercial_billing_periods.py`、`commercial_subscription_rollover.py`、`commercial_rollover_scheduler.py`；月/季/年自动滚动，合同制和 `ends_at` 越界失败关闭，PostgreSQL 双线程仅生成一个账期，数据库触发器拒绝重叠账期。
+- [x] [CONCEPT: 数据] 让用量、成本、运行时预占和配额历史绑定不可变账期，并分离配额重置键。
+  证据：`UsageMeterEvent`、`CommercialCostEvent`、`CommercialRuntimeReservation` 的 `billing_period_id`，以及 usage/reservation 的 `quota_period_key`；收费分析从账期快照读取基础费和币种。
+- [x] [CONCEPT: 权限] 为套餐、订阅、权益和续期建立脱敏追加式审计与租户安全历史 API。
+  证据：`commercial_admin_events`、`commercial_admin_audit.py`、`commercial_billing.py`；管理写接口强制 `X-Request-Id` 和原因，普通 finance/executive 只能读本租户账期，审计仅平台管理员可读。
+- [ ] [CONCEPT: 非目标] 对接真实开票/收款/订阅提供商并区分合同计费、已开票与已收现金。
+  证据：等待目标客户和 provider 选择，不使用 mock 冒充完成。
+
+## 4. 前端实现
+
+- [x] [CONCEPT: 前端] 完成商业工作台的账户、套餐/订阅、权益/配额、用量/成本、价值/定价五块。
+  证据：`CommercialWorkspace.vue` 组合账户、生命周期、权益、用量成本、价值分析与定价场景面板。
+- [x] [CONCEPT: 前端] 接入订阅暂停/取消/恢复、历史查询和操作确认。
+  证据：`useCommercialWorkspace.js`、`CommercialSubscriptionLifecyclePanel.vue`；终态和定价均有确认步骤，操作后按租户重新加载。
+- [x] [CONCEPT: 前端] 严格分开展示客户 ROI 与平台毛利，并支持多币种和证据缺口状态。
+  证据：`CommercialValueAnalysisPanel.vue`、`CommercialPricingScenarioPanel.vue`、`commercialWorkspaceModel.js`；按币种分组，null/unavailable 显示“不可用”，不跨币种合计。
+- [x] [CONCEPT: 前端] 接入现有应用入口、权限态、移动端和生产构建。
+  证据：`OverviewView.vue`/顶部导航已接入“商业化管理”；商业定向 35 项、全量 web 802 项、code-size 与 Vite 2246 modules 构建通过。
+
+## 5. 测试与验证
+
+- [x] [CONCEPT: 测试方案] 后端模型、服务、HTTP、权限、生命周期、查询和定价回归通过。
+  证据：容器内 Ruff 通过；`test_commercial_models.py`、`test_commercial_services.py`、`test_commercial_endpoints.py` 当前 12 项通过。
+- [x] [CONCEPT: 测试方案] 一次性 PostgreSQL 并发用量、原子预占、硬配额和成本冲回验证通过并记录当前命令结果。
+  证据：一次性 PostgreSQL 17 中 `test_commercial_concurrency_postgres.py` 4 项通过；两个并发工具竞争 1 份额度时仅一个 reservation 成功。
+- [x] [CONCEPT: 测试方案] 运行时预占、结算、释放、幂等、变量上限、历史配置和补偿回归通过。
+  证据：`test_commercial_runtime_metering.py`、`test_commercial_runtime_reservations.py` 27 项通过；商业/Agent/权限/迁移相关组合 183 项通过、1 项因未显式配置外部迁移库跳过，Ruff、compileall 和相关类 800 行检查通过。
+- [x] [CONCEPT: 测试方案] 前端行为测试、全量 web 测试、code-size 门禁和 Vite 构建通过。
+  证据：商业定向 35 项、全量 web 802 项通过；code-size 通过；Vite production build 转换 2246 个模块。
+- [x] [CONCEPT: 测试方案] 不可变账期、脱敏审计、自动续期和调度器验证通过。
+  证据：容器内商业/迁移前置定向 131 项、前端商业 35 项及 Vite build 通过；PostgreSQL 17 商业并发 5 项通过，含双线程续期单赢家；0021 升级、重叠账期阻断、运行不变量和 0021→0020 降级通过。
+- [x] [CONCEPT: 指标与验收] 逐项核对 A1-A7，并回填最终文件、接口和容器证据。
+  证据：商业模型/服务/API/前端、硬配额、账期、生命周期、ROI/毛利分账和定价走廊均有回归；资源边界组合 63 项、PostgreSQL 商业并发 5 项、Web 全量 815 项及 Vite build 通过。
+
+## 6. 商业与试点收尾
+
+- [ ] [CONCEPT: 风险与开放问题] 用真实试点 30/90 天数据冻结目标毛利率、最大价值分享、包含量、超额策略和封顶。
+- [ ] [CONCEPT: 风险与开放问题] 确认发票、税率、回款、坏账、渠道和收入确认边界。
+- [x] [CONCEPT: 本轮实现记录] 同步更新上位闭环文档与工程验收手册，不删除证据不足项。
+  证据：上位 AI 闭环 TODO 与 `engineering-closure-and-production-readiness` CONCEPT/TODO 已区分工程完成、生产上线和真实试点。