Files
go-sms-V2/docs/acceptance/s4-d3-partition-archive.md
T
Tory 01c8874831
ci / test (push) Canceled after 0s
ci / web-test (push) Canceled after 0s
ci / build (push) Canceled after 0s
ci / deploy-dev (push) Canceled after 0s
S4-D3: 明细按天分区热5天+ClickHouse冷热切换——S4泳道收官(冷查16ms<1s验收✅): ①分区=迁移v22 PARTITION BY RANGE(id)(雪花时间位当天零点边界,主键即分区键零唯一键改造;热5天+未来3天缓冲+pmax兜底;MySQL守卫sqlite跳过)+archive/partition.go EnsurePartitions幂等滚动(REORGANIZE pmax拆分;过期分区归档校验后才DROP)+真机9分区存量无损;②归档=archive域(CH表toDate分区/ArchiveJob 1h:CH当日分区重写幂等→分批2000迁出→count校验相等才DROP MySQL分区或DELETE兜底=零丢失方向;consumer装配启动即首轮)+metrics archive_rows/errors;③冷查=GET /record/history(CH查询/task_no MySQL转译回填/D26契约直连)真机16ms+mobile筛选✓,导出挂账D29下载中心;④settle-check热窗感知=月中对账DetailPartial=true明细↔汇总退化两方基线(日汇总↔结算单,reconcile头注预声明落地)+settle.Service时钟注入nowFn+测试相对时间/period动态;⑤真机5连坑全修存档:MySQL8.0 information_schema非分区表也返回NULL行(判据加PARTITION_NAME IS NOT NULL)/parseTime下DATE() Scan []string带RFC3339尾巴(DISTINCT时刻Scan []time.Time+Go去重双方言)/CH24.3无DROP PARTITION IF EXISTS(先查system.parts)/CH count()返回UInt64(*int64不支持+count错误不可吞)/CH绑定time.Time UTC歧义(预格式化墙钟串)——techContext存档;⑥门禁=build/vet/lint 0/-race 41包全绿/迁移v16..v22两遍幂等(v15断言随窗口右移移除);archive单测5件+settle热窗外基线用例;验收单s4-d3-partition-archive.md+CHANGELOG+memory-bank(S4收官快照/S5下一步/挂账清单)
2026-11-16 12:11:31 +08:00

56 lines
4.6 KiB
Markdown

# S4 验收单 D3:明细按天分区热 5 天 + ClickHouse 冷热切换(2026-11-16)
> 泳道:S4 第 3 日;验收项「冷查 <1s」✅(16ms,索引冷缓存口径)。S4 三项验收全过,泳道收官。
## 一、交付范围
### 明细按天 RANGE(id) 分区(热 5 天)
| 组件 | 说明 |
|---|---|
| 迁移 v22 | `ALTER TABLE message_detail PARTITION BY RANGE (id)`——分区键=雪花 id(时间位单调,当天零点边界=`(dayStart-Epoch)<<22` 精确计算;**主键即分区键,唯一键零改造**);分区集=热 5 天+未来 3 天缓冲+pmax 兜底;MySQL only(sqlite 方言守卫) |
| `archive/partition.go` | DayFloorSnowflake/PartName/HotFloor 纯函数 + EnsurePartitions 幂等滚动(缺补 ADD/REORGANIZE pmax 拆分;**过期分区不在此删**——归档校验通过才 DROP)+ DropPartition |
| 真机分区状态 | p20261112..p20261119 + pmax 共 9 分区;存量 3 行无损迁入 |
### CH 冷热归档(`internal/service/archive`)
| 组件 | 说明 |
|---|---|
| CH 表 | sms_detail_archive(MergeTree,PARTITION BY toDate(created_at),ORDER BY id,18 列与 message_detail 对齐;EnsureCHSchema 幂等) |
| ArchiveJob(consumer 进程,1h) | 热窗外逐日:CH DROP 当日分区(重写幂等)→MySQL 分批 2000 读→CH BatchInsert→**count 校验相等才 DROP MySQL 分区/DELETE 兜底**(零丢失方向:不等保留重试) |
| 冷查 | GET /record/history(CH 查询;task_no 经 MySQL message_task 转译+批量回填;契约=web record.ts D26);metrics archive_rows/errors |
### settle-check 热窗感知
对账窗起点早于热窗下限(月中对账常态)→ `DetailPartial=true`:明细↔汇总比对退化为**两方基线(日汇总↔结算单)**,明细侧不判差异(归档清退≠丢失,历史明细核对走 CH 冷查)——reconcile.go 头注预声明口径落地;settle.Service 时钟注入(nowFn)供测试。
## 二、真机全链(dev MySQL/CH,2026-11-16 11:44-11:58)
1. **分区**:v22 迁移→9 分区落地,存量 3 行保留 ✓
2. **归档**:造 6 天前(11-10)2 行+今天 1 行→consumer 重启即首轮归档→`archive_day_done rows=2`(DELETE 兜底分支)→MySQL 冷数据 0 行/热数据保留,CH 2 行(content/mobile 完整),metrics archive_rows_total=2 ✓
3. **冷查**:`GET /record/history?start_time=2026-11-01&end_time=2026-11-12` → **16ms**(**验收线 <1s 达标**,两次测 7.5/16ms),total=2 行数据全对;mobile 精筛 ✓
4. **settle-check**:月中 2026-11 → detail 侧=0(热窗感知生效)+BillMissing 正常列行;all_zero=false 仅因 S2 走查种子残留(account=2 账单 1955 vs 消耗 16050 不齐——用户走查在途数据,不清理)
5. 冒烟数据全清(MySQL 3 行+当日消耗行;CH 20261110 分区 DROP→count=0)
## 三、门禁(七件套)
- 后端:build ✓ / vet ✓ / golangci-lint **0** / **-race 全包绿**(后台终跑) / 迁移测试 v16..v22 两遍幂等(v22 sqlite 守卫跳过;v15 断言随窗口右移移除)。
- 单测:archive 5 件(边界单调/归档全链含幂等/校验不匹配保留/冷查条件)+ settle +1(热窗外两方基线,时钟注入月 20 号稳定复现)。
- 前端:无改动(契约 D26 已在;history 页零改动直连新端点)。
## 四、真机调试教训留痕(5 连坑,全部已修)
1. **MySQL 8.0 information_schema.PARTITIONS 对非分区表也返回一行**(PARTITION_NAME=NULL)——已分区判据必须 `AND PARTITION_NAME IS NOT NULL`(迁移 v22+existingParts 双处)。
2. **go-sql-driver parseTime=True 下 DATE() 结果 Scan 到 []string 带 RFC3339 尾巴**('2026-11-10T00:00:00+08:00')→ Parse 失败静默跳天;改为 DISTINCT 时刻级 created_at Scan []time.Time+Go 侧归一化去重(MySQL/glebarez 双方言兼容)。
3. **CH 24.3 无 `DROP PARTITION IF EXISTS`**(语法错)→ 先查 system.parts 存在才 DROP。
4. **CH count() 返回 UInt64,Scan *int64 不支持**——dropCHPartition/chCountDay 用 *uint64;QueryHistory 的 count Scan 错误曾被 `_=` 吞掉致 total 恒 0(错误不可吞)。
5. **CH 绑定 time.Time 的 UTC 化歧义**——查询时间窗参数预格式化墙钟字符串(与归档写入同口径)。
## 五、口径与假设(诚实标注)
1. **归档 job 单实例**(consumer 进程);多实例重复迁出由「CH 分区重写+count 校验」幂等吸收。
2. **CH 无备份/TTL**(dev 口径);生产建议 CH 副本+冷分区 S3 挂载(S5 运维项)。
3. **history 导出(/record/history/export 与下载中心)挂账 D29/P2**——D26 契约先查后导,异步导出走 MinIO/RustFS 下载中心(S5+ 择机)。
4. **pmax 兜底分区语义**:EnsurePartitions 挂掉期间数据落入 pmax,恢复后 REORGANIZE 拆分(运维 runbook 项)。
5. 明细写入侧零改动(雪花 id 天然落在当日分区);watchdog/明细页查询语义不变(分区对 SQL 透明)。