X-Financial/document/development/2026-07-16/feature/commercial-metering-and-roi/TODO.md

# 商业计量、客户 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 已区分工程完成、生产上线和真实试点。