docs/PERIOD_ALLOWANCE_UPGRADE.md

Rama main · réplica de lectura del repositorio original.

# 周期套餐售价与额度拆分

本说明适用于 Core 0.9.0，解释周期额度契约及已存在计费快照的迁移。公开 Core 0.8.0 尚无此计费模块，正常升级通过正式迁移器新增 063/064，不要求清退真实数据。完整步骤见 [v0.9.0 升级指南](UPGRADE_v0.9.0.md)。

## 周期额度契约

周期套餐需同时提供 `priceUsd > 0`（售价）与 `periodAllowanceUsd > 0`（每周期 USD 额度），金额最多十二位小数、上限 1,000,000,000。额度包继续以 `priceUsd` 提供额度，拒绝 `periodAllowanceUsd`。未知字段继续拒绝，无售价回落、旧字段别名、轮次或请求次数限制。

例如周套餐售价 100 USD、周期额度 20 USD，结算 10 USD 后剩余 10 USD / 50%；跨周重新获得 20 USD。有效期最后不足一周仍获得完整 20 USD，到期后停止新请求。原请求的晚结算归入原周期，原倍率、参考价格和额度池保持不变。套餐编辑只影响后续开通的额度条款，原账户不自动重新开通。

`GET /admin/api/usage/billing/plans` 提供 `period_allowance_supported: true`。旧 Core 不返回此标记时，前端只能预览周期额度，不能保存周期套餐。该标记表示代码能力，不能单独证明数据库已迁移；应同时核对迁移账本和计费结构就绪状态。

## 已部署计费预览实例的迁移

仅在实例已经存在 063 计费数据且周期快照缺少新字段时，需要以下数据核对。废弃测试结构的独立清理不属于本升级流程，不能用于真实客户数据。

1. 确认所有共用状态库的 Core、前端及套餐配置调用方采用新契约。备份计费表与迁移账本，保留旧产物；停止旧版本写入，包括维护结算及业务侧开通/控制请求。已派发请求保留原 ID 与证据，不能重派。
2. 使用官方 Core schema migrator（源码入口 `npm run db:init`）执行未应用的 `064_period_plan_allowance.sql`，按原迁移账本和摘要规则处理。
3. 迁移为每条缺少新字段的周期记录写入其自身旧 `priceUsd`，不是当前套餐售价。范围为套餐 `config_json`、开通快照 `config_json`、原请求 `grant_json`、开通/控制幂等缓存 `result_json.config`，包括历史记录。原历史额度语义和缓存请求哈希不变；已有明确新额度不覆盖，credits 不修改。原额度池、账本、扣费、修订和有效期均不重写。
4. 核对四类周期 JSON 均有合法正数新字段、credits 无新字段。比较迁移前后记录数、原价格、原池额度和账本金额；启动新 Core 与配套界面，验收能力位、历史摘要、原 ID 查询与幂等重放。运行时不会推断缺失字段，不能先启新版本再等待自动兼容。
5. 后续调整售价或周期额度时显式编辑套餐；新条款用于以后开通，不能把模板编辑当作原开通迁移。需要重新开通时按正常开通流程处理。

SQL 只转换缺字段记录，不覆盖已有明确额度；中断后保持停写，按正式迁移器完成剩余步骤并核对后再恢复使用。不要手工修改迁移账本或重跑已记账文件。

## 回退与验证

新字段写入后，旧 Core 的严格校验不能读取新配置。回退需要停写并协调备份和旧产物；如已发生新请求或计费，保留新记录并修复，不能直接恢复旧备份丢弃账本。

检查显式正数与金额精度、credits 拒收周期字段、周期百分比、月末规则、模板编辑与原快照独立、跨周期恢复、原周期晚结算以及最后短周期和到期行为。迁移核对包括模板与原开通金额不同、原请求结算、原幂等键重放及已有新额度不覆盖。

[模型计费契约](MODEL_BILLING.md) · [English](PERIOD_ALLOWANCE_UPGRADE.en.md)