5.3 KiB
5.3 KiB
S2 结算域·表设计评审纪要(D1,2026-11-14)
评审输入:《Go-sms-重建计划.md》S2 行(5 工作日,D 层结算域后端全量,出口=结算单测+对账差异=0)/ 《Go-sms-需求分析.md》§2.6 计费与结算(下家结算·上家结算·消耗日志·充值日志·利润分析,P1)/ 《Go-sms-重建设计规范.md》性能三律与幂等三锚 / 代码实证(结算 5 表实体自 v0 已建且业务代码零使用、 StatsUserDaily/StatsChannelDaily 同为零写入方空壳、明细 Fee=片数非金额、v16 已建 idx_detail_channel_created)。
一、六项裁决
| # | 决策点 | 裁决 | 依据 |
|---|---|---|---|
| R1 | 计价模型 | 出账时刻计价:明细 Fee 保持片数语义(send 域零改动);结算金额=Σ(日成功条数×生效单价),按 AccountPrice/ChannelPrice 时间线(EffectiveAt≤当日取最近)+阶梯档推导 | 用户 2026-11-14 拍板。与需求「分时单价与结算联动」一致;不触碰已收官域;调价可追溯;Fee≡片数口径(Day70)不动摇 |
| R2 | 消耗事实源 | billing_consume_log(账号×业务×天)+ stats_channel_daily(通道×天)为事实源;stats_user_daily 废弃(v20 DROP,实体删除,All() 移除) | 两表同粒度双空壳;单一事实源纪律,双写必漂移;表名即域归属 |
| R3 | 充值双通道 | 保留 /accounts/:id/recharge 即时到账(语义=已确认付款快捷入账)+ 新增 BillingOrder 审核流(0待→1到账/2失败;confirm=状态 CAS+余额自增 count+流水 ref_id=order_no 同事务) |
兼容存量 API 与权限测试;「付款审核确认」为需求 §2.6 明示项 |
| R4 | 返点模型 | account_user.rebate_rate decimal(5,4)(v20 加列;小数表示 0.1200=12%,0=无返点);返点额=直线下级当月结算金额×rate;历史不重算(换上级只影响未来) | 树+Path 基座已备;先落地单级分成,层级分成留扩展 |
| R5 | 阶梯载体 | 新表 settle_ladder(owner_type=account/upstream × owner_id × tier_from 唯一;tier_from=档位下限含,0=首档;出账按月成功总量落档覆写时间线价) | 独立表可审计可单测(「阶梯结算单测」为显式验收项);不塞 JSON |
| R6 | 单位口径 | 余额/预扣/明细 Fee/fee_total=条;BillingOrder.Count=条、Amount=元;结算单/利润/单价=元;条→元换算只发生在出账引擎(settle/price.go)一处 | 消除 balance(条)与 decimal(元)的隐性错位;单点换算单点审计 |
二、v20_settle_domain 迁移范围(已实现)
- billing_consume_log 补
unknown_count INT(上家 success_unknown 口径依赖)+updated_at DATETIME(UPSERT 重跑痕迹); - account_user 补
rebate_rate DECIMAL(5,4); - DROP stats_user_daily(空库路径 v0 已不再建它,DROP IF EXISTS 双方言幂等);
- 新表 settle_ladder;
- casbin 补策略:ops settle:write / customer settle:read(逐条 NOT EXISTS 守卫;单块重放路径 HasTable 守卫)。
加列走显式 SQL+HasColumn 守卫、空库走 HasTable 守卫 AutoMigrate 整表(v16/v17 教训:glebarez 下 entity 加字段触发表 diff 重建抹索引)。
不需要新聚合索引:通道维度日汇总复用 v16 idx_detail_channel_created(channel_id, created_at)。
不改 init_schema.sql(Day11 基线参考、权威=migrate 链,v16/v17 演进均未回写,维持惯例)。
stats_channel_daily 零 schema 变更(unknown_count/cost_total 原有;grain=通道×天,不加 business——通道价格体系本身不分业务,视频走独立通道)。
三、状态机与语义定稿
- 充值订单:pay_status 0待确认→1已到账/2失败;confirm 事务=UPDATE ... WHERE pay_status=0(行数=0 即 409)+balance+=count 原子自增+流水(ref_id=order_no);驳回不涉余额。
- 结算单(下家/上家同构):status 0草稿→1已确认(人工锁账,拒静默重算)→2已结账(写 settle_record,终态);generate 幂等=uk(account|upstream, period)+OnConflict 更新重算,status=2 拒。
- 上家计费口径:按通道
billing_mode——success(仅成功)/success_unknown(成功+未知)/all(全部提交);UNKNOWN 72h 窗语义(部分段事实送达)与 success_unknown 口径天然对齐。 - 日汇总 job:T+1 01:05 核算昨日+启动回补 7 天,幂等 UPSERT(明细热窗 5 天→月结必须走日汇总,job 必须在明细出窗前落账——整域地基,D2 最先做)。
四、任务映射(D2-D5)
| 任务 | 落点 |
|---|---|
| D2 消耗日汇总引擎 | settle/consume.go+job.go(照 StartStatsRefresher 幂等模式)+/billing/consume+/ops/settle/aggregate+Settle 配置段+job 指标 |
| D3 充值审核流 | settle/recharge.go+/billing/orders 族(R3 事务语义) |
| D4 出账引擎+阶梯 | settle/price.go(PriceAt+阶梯落档,R1/R6 唯一换算点)+bill.go+/settle 族(生成/确认/结账/导出) |
| D5 利润/返点/对账 | profit.go(树聚合,R4)+reconcile.go+cmd/reconcile settle-check(三方 diff=0=S2 出口) |
五、遗留与显式不承诺
- est_balance(通道估算余额 2h 刷新,需求 §5.3)语义依赖「校正余额」录入通道,本期字段保留不实现,验收单如实标注;
- 层级返点(多级分成)、月结自动生成调度(手动 generate 先行)留后续;
- 阶梯与时间线价并存时:有阶梯档则整月单价按落档价覆写(不做分档混合计价)——单测覆盖边界(恰好落档/跨档/无阶梯回退)。