Files
go-sms-V2/docs/review/s2-settle-table-review.md
T

5.3 KiB
Raw Blame History

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 迁移范围(已实现)

  1. billing_consume_log 补 unknown_count INT(上家 success_unknown 口径依赖)+ updated_at DATETIME(UPSERT 重跑痕迹);
  2. account_user 补 rebate_rate DECIMAL(5,4);
  3. DROP stats_user_daily(空库路径 v0 已不再建它,DROP IF EXISTS 双方言幂等);
  4. 新表 settle_ladder;
  5. 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 先行)留后续;
  • 阶梯与时间线价并存时:有阶梯档则整月单价按落档价覆写(不做分档混合计价)——单测覆盖边界(恰好落档/跨档/无阶梯回退)。