PLAT-04-005 数据与状态
逻辑实体、唯一约束、资金事务与恢复状态设计
本页定义必须表达的数据语义，实体名为逻辑名称，不是已经创建的表。T-01/T-03 审计真实 new-api 用户、quota、Token、日志、订单及任务结构后，决定复用列、扩展表和迁移。迁移前先给出旧资金路径到新操作的映射，不能再建立独立钱包。
逻辑实体
| 实体 | 必需信息与约束 |
|---|---|
| 用户/会话/角色 | 稳定用户 ID、账户状态、会话归属与撤销、平台角色及产品作用域角色；企业专属账户属性二期 |
| API Key | 用户归属、摘要/安全保存、模型权限、额度/有效期/状态；不得以 Key 余额代替用户余额 |
| 价格方案与版本 | 一期标准模型/收费项、单位/精度/舍入、版本、发布状态；引用后不可改写。逐客户方案绑定/有效期二期 |
| 用户组与无分组客户Key | 2026-10-05 D-KEY-ALL-MODELS替代原Key组模型：用户组仅账户归属与审计，不控制个人模型范围；取消KG/获准关系/Key绑定及逐Key模型白名单；历史组数据、原操作和快照兼容处理待G-14，实际数据库变更以正式迁移/契约为准 |
| 客户分类/价格绑定/销售许可/权益/服务策略 | 2026-10-02分组解耦：一期只落个人标准售价、全局开放销售目录/Key额度和有效性、充值与订阅权益、独立角色与服务策略；企业客户分类/基础覆盖方案绑定二期，不先建企业表。独立类型、稳定引用及各自授权/版本/有效期，不共享原生group命名空间。分类不自动定价或授权；Key限制不选择合同；路由与限流不决定价格；订阅不直接覆写User.Group。细则见钱包与计费 |
| 资金账户 | 与既有 quota 的唯一映射，可用/冻结、并发版本或行锁；一用户一份权威余额 |
| 授权/资金操作 | operation_id、可信用户/产品/动作、业务任务、指纹、价格快照、预留额、确认用量、状态和恢复依据 |
| 资金流水 | 原操作、动作与唯一键、可用/冻结变化、单位、前后值或可核对序列、原消费退款引用；不可删除覆盖 |
| 使用记录 | 原操作与调用 ID、来源、模型/收费项、数量/单位、价格和费用；日志修复不重复记账 |
| 平台模型任务 | 用户/产品/操作归属、网关任务 ID、提交状态、确认事实、结果引用和保存状态 |
| 支付订单/事件 | 平台订单、用户、人民币金额、积分/优惠快照、商户/渠道交易、校验结果、入账流水与退款关联 |
| 恢复记录/审计 | 操作、恢复动作、租约/重试时间、确认事实、错误分类；操作人、原因与关联证据 |
产品业务任务/Project/素材表不进入平台库。平台保存结果的归属与必要引用，长期素材由产品保存；链接期限与复制政策待定。
约束与幂等
- 用户资金账户唯一；产品授权创建的幂等键以可信产品、用户、业务操作与动作限定，并保存输入指纹。
- 原操作的同一账务动作只有一个有效流水结果，数据库唯一约束与事务共同保护；仅在内存查“已处理”无效。
- 支付渠道/商户/交易身份唯一，平台订单只能有效入账一次；回调事件可保留多份核对线索，不能产生多份充值。
- 平台任务与原付费操作稳定关联；网关任务映射以网关身份限定，不能假设不同网关 ID 全局唯一。
- 金额序列化为确定的整数最小单位或定点字符串，约定单位、精度与舍入；不以 JavaScript 浮点数做金额权威计算。
资金事务
预留/结算/释放时锁定同一用户资金路径，校验余额、操作归属、状态及指纹，在同一事务写余额变化、冻结变化、操作终态和流水。明确锁顺序避免死锁。事务冲突可有界重试同一动作；外部供应调用和支付网络请求不能在此长事务内等待。
如果现有 Key 额度或日志无法同事务更新，需要持久恢复记录和独立核对，不能因为余额已成功就丢失额度补偿。用量日志可以修复，资金主流水不能靠再次扣费补齐。跨网关无分布式资金事务，靠已保存操作、确认事实及幂等恢复协调。
状态分开保存
以下为目标语义，实际枚举名在 OpenAPI/迁移定稿，不把所有状态塞进一个 status。
| 维度 | 状态语义 | 规则 |
|---|---|---|
| 执行 | 已授权/未开始 → 执行中 → 成功、明确失败或未知 | 确认开始先与到期释放做原子竞争；未知只能核对原执行 |
| 资金 | 已预留 → 已结算或已释放；结算后可有原消费退款 | 终态互斥，退款是关联的新资金动作 |
| 恢复 | 待处理/持有租约/等待重试/待人工核对/完成 | 租约失效触发接管，不能直接释放或认定执行失败 |
| 结果保存 | 未取得/待保存/已保存/保存失败 | 保存失败只恢复结果获取及保存，不重做生成 |
仅预留且确认未开始的操作到期才可释放。确认开始的响应丢失，执行方先查状态，不盲目调用业务。供应提交前落地执行意图；提交响应丢失进入未知并查询，供应不支持可靠查询/幂等时需要人工核对，不自动再次创建。
订单状态单独描述创建、待支付、确认到账、关闭、异常及退款事实。关闭后迟到成功的处理需要明确政策与证据，不能随意入账或忽略已发生支付。
迁移与核对
建议显式版本化 SQL/迁移程序，不仅依赖 GORM 自动建表。每项给出前置条件、回填方式、索引/锁影响、兼容窗口、恢复步骤和验证查询。精度转换、余额回填、退款与增减积分均需保存批次并可复验；不可把生产数据复制到 Git。
产品运营对象扩展
PL-021/T-13的领域细则见全域记录与产品运营。现有operation.Product是可信消费来源，权益AllProducts/Products是消费适用范围；新增商品/活动owner与订单销售入口是独立事实。模板/活动版本、订单/履约/订阅及grant来源保存归属与原快照，真实逻辑订阅关联购买/续订覆盖段与原窗口；产品不新增余额/商业规则的权威表。
产品业务任务仍不迁入平台，增加可重建授权摘要索引和可靠事件收件记录，原用户/产品/父业务任务/operation列表/事件版本稳定关联。产品业务提交与outbox同事务，接收按可信产品+事件ID去重；摘要更新不能改变平台账务/执行事实。具体表/索引、已有对象显式归属与数据回填、权限/资金/去重约束在平台仓库迁移与OpenAPI定稿并隔离验证，不视为本轮已建表。