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

商业计量、客户 ROI 与可持续定价 开发 TODO

更新时间：2026-07-17

使用规则

• 每项必须回链 CONCEPT.md 对应章节。
• 只有代码、接口或容器验证提供证据后才能勾选。
• 客户价值、平台收入、内部成本和工时估值必须分账；mock 与手工事件不得标记为生产事实。

1. 调研与边界

• [CONCEPT: 背景与问题] 明确商业权益、用量、成本、客户 ROI、平台毛利和定价不是同一事实。 证据：CONCEPT.md“背景与问题”“目标与非目标”。
• [CONCEPT: 目标与非目标] 确认不硬编码客户价格、不混算风险暴露、不跨币种求和、不让付费绕过安全门禁。 证据：CONCEPT.md“目标与非目标”。

2. 契约与设计

• [CONCEPT: 数据] 定义套餐、订阅、权益、用量和内部成本五类事实及状态。 证据：commercial.py 模型与 schema、20260716_0016_commercial_metering.py。
• [CONCEPT: 算法与公式] 定义客户 ROI、贡献毛利和可持续定价走廊公式。 证据：CONCEPT.md“算法与公式”、commercial_analytics.py、commercial_pricing.py。
• [CONCEPT: 权限] 定义平台配置、租户只读和商业/安全门禁分离。 证据：commercial_access_policy.py、commercial_entitlements.py。

3. 后端实现

• [CONCEPT: 数据] 新增五张商业表、复合租户约束、幂等、冲回和 append-only 迁移。 证据：models/commercial.py、20260716_0016_commercial_metering.py、迁移/模型测试。
• [CONCEPT: 数据] 新增运行时预占运营表、状态约束、复合租户外键、全局 tool call 幂等和迁移所有权。 证据：models/commercial_runtime.py、20260716_0019_commercial_runtime_reservations.py、commercial_migration_assertions.py；0019→0020 一次性 PostgreSQL 完整升降级循环通过。
• [CONCEPT: 后端] 实现套餐版本、订阅、权益、配额、用量、成本与商业分析服务。 证据：commercial_admin.py、commercial_entitlements.py、commercial_metering.py、commercial_analytics.py。
• [CONCEPT: 生命周期与查询] 实现暂停、逾期、取消、过期、恢复与五类历史查询。 证据：CommercialAdminService.transition_subscription()、commercial_queries.py、/commercial/admin/tenants/{tenant_id}/... 分资源接口。
• [CONCEPT: 定价走廊] 实现成本下限、确认价值上限、成功费封顶和商业模式建议。 证据：commercial_pricing.py、POST /commercial/admin/tenants/{tenant_id}/pricing-scenarios。
• [CONCEPT: 后端] 把中央 Orchestrator 工具接入执行前预占、真实 AgentToolCall 结算和失败释放。 证据：orchestrator_tool_execution.py、agent_runs.py、commercial_runtime_bridge.py；无配置兼容，配置后先 reserve 再执行，成功只追加真实用量/成本，失败和阻断不计量。
• [CONCEPT: 降级策略] 持久化缺预占和计量故障补偿状态，并安全处理过期预占。 证据：commercial_runtime_reservations.py、commercial_runtime_reconciler.py；直接调用形成 reconciliation_required，运行中/未知终态继续持有额度，终态无调用才过期释放；用量成功但成本失败形成 committed_reconciliation_required，重试只补成本且不重复冻结额度。
• [CONCEPT: 风险与开放问题] 把已识别的权威运行入口迁移到 permit 契约。 证据：中央 Orchestrator、ocr_commercial.py、runtime_chat_commercial.py、financial_connector_commercial.py 和 expense_claim_attachment_commercial.py 已接通预占/结算/释放；资源组合 63 项通过。
• [CONCEPT: 风险与开放问题] 对后续新增的知识库/ONLYOFFICE 存储、实施和支持等资源入口持续执行 meter 盘点，不允许绕过 permit。 证据要求：新增真实资源入口时提供权威数量口径、事务边界、成本来源和回归测试；当前不把未发生的未来入口伪装成已计量。
• [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 双线程仅生成一个账期，数据库触发器拒绝重叠账期。
• [CONCEPT: 数据] 让用量、成本、运行时预占和配额历史绑定不可变账期，并分离配额重置键。 证据：UsageMeterEvent、CommercialCostEvent、CommercialRuntimeReservation 的 billing_period_id，以及 usage/reservation 的 quota_period_key；收费分析从账期快照读取基础费和币种。
• [CONCEPT: 权限] 为套餐、订阅、权益和续期建立脱敏追加式审计与租户安全历史 API。 证据：commercial_admin_events、commercial_admin_audit.py、commercial_billing.py；管理写接口强制 X-Request-Id 和原因，普通 finance/executive 只能读本租户账期，审计仅平台管理员可读。
• [CONCEPT: 非目标] 对接真实开票/收款/订阅提供商并区分合同计费、已开票与已收现金。 证据：等待目标客户和 provider 选择，不使用 mock 冒充完成。

4. 前端实现

• [CONCEPT: 前端] 完成商业工作台的账户、套餐/订阅、权益/配额、用量/成本、价值/定价五块。 证据：CommercialWorkspace.vue 组合账户、生命周期、权益、用量成本、价值分析与定价场景面板。
• [CONCEPT: 前端] 接入订阅暂停/取消/恢复、历史查询和操作确认。 证据：useCommercialWorkspace.js、CommercialSubscriptionLifecyclePanel.vue；终态和定价均有确认步骤，操作后按租户重新加载。
• [CONCEPT: 前端] 严格分开展示客户 ROI 与平台毛利，并支持多币种和证据缺口状态。 证据：CommercialValueAnalysisPanel.vue、CommercialPricingScenarioPanel.vue、commercialWorkspaceModel.js；按币种分组，null/unavailable 显示“不可用”，不跨币种合计。
• [CONCEPT: 前端] 接入现有应用入口、权限态、移动端和生产构建。 证据：OverviewView.vue/顶部导航已接入“商业化管理”；商业定向 35 项、全量 web 802 项、code-size 与 Vite 2246 modules 构建通过。

5. 测试与验证

• [CONCEPT: 测试方案] 后端模型、服务、HTTP、权限、生命周期、查询和定价回归通过。 证据：容器内 Ruff 通过；test_commercial_models.py、test_commercial_services.py、test_commercial_endpoints.py 当前 12 项通过。
• [CONCEPT: 测试方案] 一次性 PostgreSQL 并发用量、原子预占、硬配额和成本冲回验证通过并记录当前命令结果。 证据：一次性 PostgreSQL 17 中 test_commercial_concurrency_postgres.py 4 项通过；两个并发工具竞争 1 份额度时仅一个 reservation 成功。
• [CONCEPT: 测试方案] 运行时预占、结算、释放、幂等、变量上限、历史配置和补偿回归通过。 证据：test_commercial_runtime_metering.py、test_commercial_runtime_reservations.py 27 项通过；商业/Agent/权限/迁移相关组合 183 项通过、1 项因未显式配置外部迁移库跳过，Ruff、compileall 和相关类 800 行检查通过。
• [CONCEPT: 测试方案] 前端行为测试、全量 web 测试、code-size 门禁和 Vite 构建通过。 证据：商业定向 35 项、全量 web 802 项通过；code-size 通过；Vite production build 转换 2246 个模块。
• [CONCEPT: 测试方案] 不可变账期、脱敏审计、自动续期和调度器验证通过。 证据：容器内商业/迁移前置定向 131 项、前端商业 35 项及 Vite build 通过；PostgreSQL 17 商业并发 5 项通过，含双线程续期单赢家；0021 升级、重叠账期阻断、运行不变量和 0021→0020 降级通过。
• [CONCEPT: 指标与验收] 逐项核对 A1-A7，并回填最终文件、接口和容器证据。 证据：商业模型/服务/API/前端、硬配额、账期、生命周期、ROI/毛利分账和定价走廊均有回归；资源边界组合 63 项、PostgreSQL 商业并发 5 项、Web 全量 815 项及 Vite build 通过。

6. 商业与试点收尾

• [CONCEPT: 风险与开放问题] 用真实试点 30/90 天数据冻结目标毛利率、最大价值分享、包含量、超额策略和封顶。
• [CONCEPT: 风险与开放问题] 确认发票、税率、回款、坏账、渠道和收入确认边界。
• [CONCEPT: 本轮实现记录] 同步更新上位闭环文档与工程验收手册，不删除证据不足项。 证据：上位 AI 闭环 TODO 与 engineering-closure-and-production-readiness CONCEPT/TODO 已区分工程完成、生产上线和真实试点。