## 1. CLI 参数与校验 - [x] 1.1 把 `--progress` 从 int 改为自定义 `flag.Value`,支持 `auto|on|off|N`,默认 `auto` - [x] 1.2 新增 `--progress-interval`(默认 `1s`),并接入 `cli.Config` - [x] 1.3 在 `validate.go` 中校验 `--progress` 取值与 `--progress-interval > 0`,错误走 KindConfig - [x] 1.4 更新 `--help` 文案与 `cli_test.go`,覆盖 `auto`、`on`、`off`、`0`、正整数、非法值 ## 2. internal/progress 模块 - [x] 2.1 定义 `Reporter` 与内部快照结构,用互斥量保护计数、阶段、估算、位置与消息 - [x] 2.2 实现 `Start/Stop` 与 ticker 生命周期,支持注入时钟与 `io.Writer` - [x] 2.3 实现 TTY 判定(`os.File.Stat` 的 `ModeCharDevice`)与 live/line 渲染器选择 - [x] 2.4 实现 live 单行渲染:`\r` 覆盖、空格补齐、宽度上限与字段优先级裁剪 - [x] 2.5 实现非 TTY 的稳定 key=value 行渲染 - [x] 2.6 实现 5 秒窗口速率与 ETA(基于本次运行的推进速率,不使用 elapsed/pct) - [x] 2.7 实现 `Message`:清 live 行、整行输出、下一拍重绘 - [x] 2.8 实现 `done` 汇总行与中断时的最终快照行 - [x] 2.9 单元测试:live/line 输出、间隔节流、行阈值触发、清行补齐、消息不撕裂、速率窗口、ETA 降级 ## 3. 廉价总量估算 - [x] 3.1 实现有界估算查询:独立连接、`context.WithTimeout(2s)`、失败/超时静默返回无估算 - [x] 3.2 日期模式:`MIN/MAX(shard_column)` 得到天范围,发布 `estimate=day` - [x] 3.3 非日期模式:仅单列整数唯一键时用 `MIN/MAX(key)`,发布 `estimate=key` - [x] 3.4 复合键、字符串/二进制键、无索引时跳过并保持 `estimate=none` - [x] 3.5 单测覆盖估算可用、超时降级、口径不适用;集成测试覆盖日期与主键两种口径 ## 4. 运行循环接入 - [x] 4.1 在 `execute` 启动 Reporter,在 `finish`/`interrupt` 停止 - [x] 4.2 推送阶段:`probe`、`resume`(`Manifest.Adopt`)、`estimate`、`scan`、`file`、`db`、`checkpoint`、`finalize` - [x] 4.3 每个 chunk 完成后发布 RowsRead/committed、分片序号、已写字节与当前键位置 - [x] 4.4 把 `lag.OnWait` 改为 `lag-wait` 阶段并携带原因,移除裸 `waiting:` 输出 - [x] 4.5 把 `app.go` 中直接写 `os.Stderr` 的警告与提示改为 `Reporter.Message` - [x] 4.6 读取 `state.json` 时记录 `baseRows`,进度显示 `base + 本次 RowsRead` - [x] 4.7 `saveState` 写入 `baseRows + 本次 RowsCommitted`,修复续跑后 `rows_done` 重置 - [x] 4.8 `--statistics` 分开展示本次运行与含续跑的累计值 - [x] 4.9 中断顺序:停刷新 → 清行 → 最终快照 → `SealCurrent` → `saveState`,退出码保持 130 ## 5. 测试与验证 - [x] 5.1 更新 `internal/app/integration_test.go` 中从 stdout 抓 `progress:` 的用例,改为 stderr 与新模式 - [x] 5.2 新增集成测试:续跑后 `state.json` 的 `rows_done` 为累计值 - [x] 5.3 新增集成测试:`--progress off` 与默认非 TTY 时 stderr 无进度行 - [ ] 5.4 手动验证 Windows conhost 的 live 刷新、重定向日志的 `--progress on` 输出、SIGINT 快照 - [ ] 5.5 运行 `go test ./...` 与 `go vet ./...`,确认无 data race(`go test -race` 覆盖 progress 单测) ## 6. 文档与收尾 - [x] 6.1 README 增加进度章节:模式、默认行为、通道、估算口径与限制 - [x] 6.2 说明 `scripts/export-all.ps1` 可用 `--progress on` 让日志可 tail,并说明 `-Verify` 的续跑语义变化 - [x] 6.3 运行 `openspec validate add-realtime-progress --strict` 并修复所有告警