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