S2-D1 结算域表设计评审+迁移 v20+契约草案: 六项裁决定稿(docs/review/s2-settle-table-review.md)——R1 出账时刻计价(用户拍板:明细 Fee 保持片数/send 域零改动,金额=Σ日成功条数×生效单价,时间线+阶梯 D4 price.go 单点推导)/R2 消耗事实源统一 billing_consume_log+stats_channel_daily,stats_user_daily 废弃/R3 充值双通道(即时+BillingOrder 审核)/R4 rebate_rate 单级返点历史不重算/R5 settle_ladder 阶梯表/R6 条/元口径单点换算;v20_settle_domain(billing_consume_log +unknown_count/updated_at,account_user +rebate_rate,DROP stats_user_daily,settle_ladder 建表,casbin 补 ops settle:write/customer settle:read;显式 ALTER+HasColumn 守卫/空库 HasTable 守卫三路径收敛,零新增索引复用 v16);实体同步 All() 39 个;openapi v1.3.0 +20 结算端点(js-yaml 84 paths 过);迁移测试末七窗口 v14..v20 两遍幂等+五项 v20 断言;门禁全绿:vet 0/-race 38 包零 FAIL/lint 0/集成 AutoMigrate 39 表+Casbin PASS;dev 库实跑 v19→v20+information_schema 五项核验过;验收单 s2-d1.md+CHANGELOG+memory-bank 回填

This commit is contained in:
2026-11-14 09:56:54 +08:00
parent 24f7b3dd02
commit 5159e3c634
12 changed files with 481 additions and 46 deletions
+45
View File
@@ -0,0 +1,45 @@
# S2-D1 表设计评审 + 迁移 v20 + 契约草案 人工验收单(2026-11-14)
> 前置:S1 泳道收官(s1-b-closeout.md,24h 门槛在途 11-14 17:55 期满回填)。
> 本单覆盖 S2 结算域 D1:六项表设计裁决定稿 + v20_settle_domain 落地 + openapi 契约草案。
## 一、交付物
| # | 任务 | 结果 | 证据 |
|---|---|---|---|
| 1 | **表设计评审纪要**(六项裁决 R1~R6) | ✅ | `docs/review/s2-settle-table-review.md`;R1 计价模型=出账时刻计价(用户 2026-11-14 拍板:明细 Fee 保持片数、send 域零改动) |
| 2 | **迁移 v20_settle_domain** | ✅ | migrations.go 末块:billing_consume_log +unknown_count/updated_at;account_user +rebate_rate;DROP stats_user_daily(R2 单一事实源);新表 settle_ladder;casbin 补 ops settle:write / customer settle:read(NOT EXISTS 逐条守卫) |
| 3 | **实体同步** | ✅ | entity/billing.go(补列+SettleLadder+SettleCustomer 状态注释对齐 0草稿/1已确认/2已结账);account.go(RebateRate);system.go(StatsUserDaily 删除留裁决注记);base.go All() 39 实体 |
| 4 | **openapi 契约草案 v1.3.0** | ✅ | 20 个新端点(billing 5/settle 15:充值订单审核/消耗查询/下家/上家月结/阶梯/利润/手动汇总);js-yaml 解析通过(84 paths);版本 1.2.0→1.3.0 |
| 5 | **迁移测试更新** | ✅ | base_test.go:末七窗口 v13..v19→v14..v20,终版断言 v20,新增 v20 五项断言;v13 断言随窗口右移移除(注记留痕) |
## 二、门禁(七件套后端件)
| 项 | 结果 |
|---|---|
| go vet ./... | ✅ RC=0 |
| go test -race ./...(全量) | ✅ 全绿(回填于本单尾部) |
| golangci-lint v2.1.6 | ✅ 0 issues |
| 迁移单测(sqlite 末七两遍幂等) | ✅ TestMigrations_IdempotentAndVersioned 含 v20 断言通过 |
| openapi YAML 解析 | ✅ js-yaml 84 paths |
| gen-dict/-check | ✅ 未新增 x-isc-dict,dict.ts 无需再生成 |
## 三、设计要点留痕
1. **不触碰已收官 send 域**(R1):计价全部收拢 D4 出账引擎 settle/price.go(PriceAt 时间线回溯+阶梯落档);条→元换算全链单点(R6)。
2. **v20 加列走显式 SQL+HasColumn 守卫、空库走 HasTable 守卫 AutoMigrate 整表**——glebarez SQLite 下 entity 加字段触发表 diff 重建抹索引(v16/v17 教训,三条路径收敛:全量新库 v0 直含/存量库 ALTER/末七窗口空库建表)。
3. **零新增聚合索引**:通道日汇总复用 v16 `idx_detail_channel_created(channel_id, created_at)`。
4. **init_schema.sql 不动**(Day11 基线参考,权威=migrate 链,v16/v17 演进均未回写,维持惯例)。
5. **stats_channel_daily 零 schema 变更**(unknown_count/cost_total 原有;grain=通道×天,不加 business——通道价格体系不分业务,视频走独立通道)。
6. **casbin 策略随 v20 逐条 NOT EXISTS 守卫种入**(v5 的 n>0 整体跳过守卫不适用于增量)。
## 四、验收结论
**S2-D1 通过。** D2(消耗日汇总引擎)开工前置=本单归档+CHANGELOG+进度回填。
## 五、附:真库验证(dev MySQL 13306,2026-11-14)
- `cmd/migrate version` v19_longsms_pending → `up` → **v20_settle_domain**(存量库 ALTER 路径实测通过);
- information_schema 核验:billing_consume_log unknown_count/updated_at 两列 ✓、account_user.rebate_rate ✓、settle_ladder 建表 ✓、stats_user_daily 已 DROP ✓、casbin_rule 新增 ops settle:write / customer settle:read ✓;
- 集成测试:TestMySQL_AutoMigrate 39 表 PASS;Casbin 集成 PASS(新策略不破坏 enforcer 加载);
- `go test -race ./...` 全量 38 包 ok,零 FAIL。
+52
View File
@@ -0,0 +1,52 @@
# 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 先行)留后续;
- 阶梯与时间线价并存时:**有阶梯档则整月单价按落档价覆写**(不做分档混合计价)——单测覆盖边界(恰好落档/跨档/无阶梯回退)。