D03 订购与支付域 · 设计文档

本域总览见《账号计费中心 · 结构大纲》。全文分六段：定位与边界 / 角色与依赖 / 数据模型 / 核心流程 / 接口契约 / 关键约束与验收标准。

1. 定位与边界

定位：把「用户想买的东西」变成「账上可用的钱」。本域回答买什么、多少钱（商品与价目）、怎么付（渠道与下单）、钱何时算到账（回调、人工确认、关单与查单自愈），并承载订阅套餐账本与密钥台账。

核心概念

边界

• 不管扣费与资金口径：余额、流水与欠费判定属钱包与账务域；本域只管「钱进得来」，入账后触发一次准入状态发布（读侧契约属账户状态与准入域）。
• 不管退款审批、渠道出款与退款对账：门户只留「申请」入口，其余语义详见 D07。
• 不管发票（D08）、身份凭证与登录（D01，本域只写扫码支付的商户凭据与回调）、用量计量与计费（D05）、风控规则与处置（D09）、工作区与成员组的增删改（D02，本域只消费归属列并做密钥联动失效）、运营面人员与权限模型（D11，只用「在册平台员工」事实作灰度判据）。

关键口径

1. 金额：元、6 位小数、字符串传输；目录定价以分存放，下单时换算为元。渠道收银台按 2 位小数比对，故下单与退款定额都要求等效 2 位小数，有效 3 位以上一律拒绝。
2. 幂等两层：订单级 order_no（全局唯一）与下单意图级 client_request_id（同客户唯一，重复提交返回原单）。
3. 「已入账」唯一判据：流水中 ref_order 等于订单号且类型为 recharge 的那行；赠金等类型同键不阻断入账。
4. 在营态唯一：订阅按客户 × 商品在营唯一；渠道配置按渠道 × 模式唯一、按渠道至多一行启用。

2. 角色与依赖

参与角色：客户（门户下单人，订单与密钥归属工作区、操作人为成员本人）、组织 Owner / Admin（可处置全组织密钥行）、组管理员（密钥可见范围收窄到其管理的组与本人名下）、运营（带运营令牌与操作人标识）、在册平台员工（灰度判据，非权限体系）、数据面网关（以明文密钥现取校验台账）、计量方（读价目规则版本）、渠道（外部支付网关与对公资金账户）。

能力矩阵（组织角色与组内角色相互独立）

上游依赖

下游被引用

3. 数据模型

customers / organizations / groups / users 由他域持有，本域只以归属列引用；订阅周期额度经额度账本的归属列关联（额度账本属钱包与账务域，本域只写归属、不持余额）。

• 与计量域只走价目规则：单价是计量方的输入，本域不拉用量、不核算扣费；账户密钥与组级执行凭证不混用，执行凭证由数据面网关按组翻译，两者只经组关联。

3.3 表清单（7 表）

3.4 设计约束

1. 商品与售价分离：商品 code 唯一、kind 只取 recharge；售价只在 product_prices 上版本化。
2. 售价区间快照：当前价恒为 effective_to 为空那条；调价先关旧价再落新价，新价生效时点不得早于当前价生效时点（不得抹掉价格历史）。
3. 价目版本只增：按整版本发布、版本号自增、不提供单行改写。
4. 订单双重唯一：order_no 全局唯一；(客户, client_request_id) 唯一（部分索引，空值互不相等，未携带该键的下单不受约束）。
5. 订单状态集合固定：pending / paid / failed / cancelled / refunding / refund_processing / refunded / refund_failed / refund_unknown；expires_at 非空，金额为元 6 位小数。
6. 订阅在营唯一：(客户, 商品) 至多一行在营订阅（部分唯一索引）。
7. 渠道配置双唯一：(渠道, 模式) 唯一；每渠道至多一行启用（部分唯一索引，不同渠道可同时启用）。
8. 凭据整体加密：凭据序列化后整体加密落单列，加密密钥经环境注入；对公收款账户面向付款用户公开，明文落库。
9. 密钥不可逆取回：key_hash 唯一、明文不落库；软删（deleted_at 非空即视为不存在）保流水追溯。
10. 密钥额度多周期：quotas 承载 day / week / month / total，缺省即不限；单值上界与请求口径同源（QUOTA_VALUE_MAX）。
11. 来源白名单有上限：逐项须为地址或网段，去重保序，上限 20 条。

4. 核心流程

• 订单号 = 时间戳 + 16 位十六进制随机段（64 bit），同秒撞号概率约 1/2^64；重试有限次（上限 3 次）且只对唯一约束冲突生效，外键与校验类冲突原样抛出。
• 重试期间的会话状态：冲突后整事务回滚会使会话内对象过期，重试、日志与审计一律使用回滚前定格的客户与用户标识，不得再访问会话内对象属性，否则懒加载失败会把「自动重试」变成 500。
• 对公渠道收款账户从订单快照读：运营改账号后历史订单的收款信息不跟着变（用户可能已按旧账号转账）。
• 幂等重放的余额读已提交真值（显式加行锁）：并发双充值下，后到者若读本事务未提交视角，会返回未含本笔的旧值。

• 验签先于任何基于订单号的差异化应答：未知订单号与验签失败统一姿态，枚举订单号无法区分「订单是否存在」与「属哪个渠道」。
• 渠道一致性校验放在验签之后：验签已过说明报文确由该渠道签发，此时不匹配属配置或路由错误，用 409 而非探测语义。
• 入账的 DB 兜底：唯一索引使并发双入账在落库时显式冲突并收敛为幂等返回（非 500），本事务加款与流水整块回滚。
• 入账成功后同一请求内同步发布一次准入状态（充值是最主要解封路径），不另调异步发布以免重复事件。
• 拒绝姿态一律留痕（验签失败 / 报文非法 / 未知订单号探测），但审计写入失败绝不阻断拒绝应答。

• 关单幂等：只改「待支付且已过期」的行，多副本并发触发安全；扫描用独立短会话与独立连接池，不随调用方事务回滚丢失，也不占业务请求的连接预算；单轮失败只记日志。
• 关单不是终局：渠道侧已完成收款的订单可由主动查单路径复活（见 4.4）。

• 退避档位按账龄推进：前 60 分钟密查，之后 60 分钟一查，覆盖关单后的补偿窗口；自首次查单起 24 小时仍无法确认即告警转人工。
• 执行范式：无锁快照 → 锁外网络调用 → 收敛入口自行加锁；单笔异常不拖垮整轮，下轮重试。
• 条件关单只用「条件更新 + 状态判定在同一语句内完成」，不用「取锁后复检」：查单路径对象来自锁外快照，行锁不会刷新会话内陈旧对象，复检形同虚设。
• 复活只接受已关单态（超时关单），禁止从回调路径调用——回调可伪造；复活审计与「回调入账」「人工确认」三源可辨。运营可对单笔强制查一次（跳过退避）。

• 对公渠道无网关无回调，收款靠人工核对；确认端点与渠道回调共用同一条入账链路与同一幂等键。
• 两道门禁不可省：只允许人工确认型渠道（否则等于未收款先入账）；实收金额必填（否则比对被跳过而按订单金额直接入账）。
• 操作人门禁与退款审批同口径：必须是在册且具出款范围的平台员工，缺标识 / 标识非法 / 无绑定 / 已停用同一拒绝语义，不泄露绑定状态。

• 四道闸门：凭据就绪、调测完成（真实模式必过）、人工开关、灰度放行；四者齐备才对客户可见，判定只实现一次并在配置面、下单门禁、门户列表三处共用。
• 启用默认落灰度（fail-closed）：启用与对外是两次独立动作；放行对外需重验凭据与探活证据，回退灰度无条件允许。
• 派生生命周期状态只用于运营面徽标展示，不作门禁判定：判定走原始字段，避免派生状态与外部事实漂移。
• 每渠道至多一行启用（部分唯一索引）：启用某行时同渠道其他行在同事务内清零；删除启用行被拒绝，须先停用。

• 凭据读取只有一个入口：解密失败按「未就绪」处理（fail-closed），不上真实渠道；历史键名在该入口归一为规范名；写入字段表创建与编辑共用一份，防字段被静默丢弃。
• 探活相关字段集合是常量（模式、凭据、网关地址、通知与回跳地址、对公账户四要素）；触及任一即作废探活证据，防「改了密钥仍凭旧证据上线」。
• 探活失败不清空已有探活通过时点（网络抖动不应让已上线渠道被降级），但失败同样留痕（谁在何时试过、报了什么）。
• 人工确认型渠道无网关可探，「调测」等价于账户信息完整；模拟模式无真实网关可测。响应只出标识类字段与「是否已配置」布尔，密钥类明文永不回传。

• 目录只展示当前价；历史售价经内部接口按区间回查，用于对账与公示。商品无当前价时下单拒绝（409），无价即不上架。
• 计价规则只按整版本发布，同版本内重叠命中取优先级高者；无匹配即未定价，计量方不产生费用。
• 本域只出单价规则、不参与扣费核算：扣费金额由计量方即算即传，账务扣减在钱包与账务域。

• 明文只出现在创建响应里一次，库内只存哈希与展示前缀；软删行视为不存在（明文现取校验返回未找到）。
• 额度多周期（day / week / month / total），缺省即不限，清空即回到不限；来源白名单逐项须为地址或网段、去重保序、上限 20 条，空列表即不限制来源。
• 临时密钥靠过期时点约束，过期即不可用；清空过期时点即转长期密钥。
• 联动失效是单向的：成员移出与组停用只做停用，组恢复启用不自动恢复密钥（避免「密钥显示可用却用不了」）；软删保流水追溯，不做物理删除。

• 在营唯一性：每客户每商品至多一行在营订阅（部分唯一索引兜底）；取消让位后重新订阅开新行。
• 周期额度不做余额计数器：每周期新发一个额度包，剩余量由流水聚合得出；到期即过期，天然实现按周期重置。
• 周期天数、每周期额度、当期价格都在订阅行上快照，后续改价不回改已开订阅；取消后本周期额度用到期为止，取消原因留痕。

5. 接口契约

5.1 门户目录与渠道（/api/account）

5.2 门户订购（/api/account）

5.3 内部商品与定价（/internal）

5.4 内部支付渠道（前缀 /internal/pay，下表为前缀内相对路径）

5.5 内部订单（/internal）

• 同一前缀下的退款申请、审批、驳回、轮询与渠道对账端点属退款与对账域，详见 D07。

5.6 内部密钥现取校验（/internal）

• 鉴权为内部服务令牌的计量范围；状态与过期由调用方（数据面网关鉴权）决策，本端点只回答「是不是一把未软删的账户密钥」。封禁与解封属风控处置语义，详见 D09。

5.7 运营面（/api/account/ops）

• 运营面端点与内部端点共用同一组处理器（鉴权分别为门户令牌 + 运营配置范围、内部运营范围令牌）；出款类动作另加在册实人门禁。运营面端点索引表统一登记在 D11，本节只收主语义属本域的端点。

6. 关键约束与验收标准

6.1 约束

1. 单一幂等键入账：入账以 order_no 为幂等键、以 recharge 类型流水为唯一判据；重复回调、重复确认、查单收敛三源并发时净效果为恰好一次入账。
2. 验签优先且不泄露存在性：回调在任何基于订单号的差异化应答之前完成验签；未知订单号与验签失败同姿态；渠道一致性校验置于验签之后。
3. 非法迁移一律拒绝：只有待支付订单可转为已支付；已支付重复确认按幂等返回；其他状态一律拒绝，不产生状态回退。
4. 金额一致性硬门禁：回调与人工确认的金额必须与订单金额一致，不一致即拒绝且不入账；2 位小数口径由下单门的精度校验前置保证。
5. 关单与入账互斥：关单只在订单仍为待支付时生效，条件更新在单条语句内完成判定与写入，绝不覆盖在途入账结果。
6. 复活路径唯一：只有主动查单可复活已关单订单，且金额必须一致；回调路径不放开。
7. 渠道四闸门：凭据就绪、调测完成、人工开关、灰度放行四者齐备才可见可下单；启用与对外是两次动作；派生状态不作判定。
8. 凭据单向可写：凭据整体加密落单列，读取只有一个入口，解密失败按未就绪处理；响应只出标识类字段与「是否已配置」布尔，密钥类明文永不回传。
9. 探活证据随配置失效：触及探活相关字段即作废调测证据；探活失败不清空既有通过时点但必须留痕。
10. 密钥零明文与可逆停用：明文只在创建响应出现一次，库存哈希；停用与启用可逆；软删保留追溯；成员移出与组停用触发名下令牌一并停用，组恢复不自动恢复密钥。
11. 运营动作实人可追：入账与出款类动作必须带在册且有出款范围的操作人；申请与驳回类动作虽不设实人门禁，但操作人缺失必须显式落审计标记。
12. 价目只增不改：售价按区间追加、计价规则按整版本追加；任何路径都不得抹掉价格历史或改写已发布版本。

6.2 验收标准

6.3 待后续设计细化的开放项

1. 订阅的开通与续费入口编排：周期滚动、取消与重新订阅的行级约束已定，门户侧入口与文案编排待与其他页面统一。
2. 渠道对账的订单侧视图：本域只出订单与渠道配置，账单比对在退款与对账域；跨域差异处置口径需两侧联合定稿。
3. 密钥额度在执行侧的落点：额度字段与口径在本域，扣减时的额度判定归属待与计量与计费域对齐（当前扣费只按金额扣钱包）。
4. 计价规则的套餐级覆盖：字段已就位，套餐级单价的生效范围与切换时机待与计量与计费域共同细化。
5. 渠道凭据轮换：密钥经环境注入、凭据整体加密；轮换期双写与历史密文重加密策略待定。