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

4.6 KiB

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 透明)。