## Context 现状与动机见 `proposal.md`。与设计直接相关的几个约束: - 运行循环是单线程的(`internal/app/app.go` 的 `execute` → `processChunk`),计数分散在 `Stats` 结构体的裸字段里,直接加后台 goroutine 会产生 data race。 - 唯一能让"长阻塞期间仍有输出"的办法是后台定时器:`scan.Next`、fsync、`lag.Wait` 都无法在阻塞点内部插入回调。 - 扫描器(`internal/scan`)的状态不是并发安全的;进度不能从后台线程直接读扫描器或 writer。 - 项目刻意保持零额外依赖(`go.mod` 只有 MySQL 驱动与压缩库),且需兼容 Windows conhost。 - 现有 `--progress N` 是 int,默认 0 = 关闭;`--statistics` 与 `--dry-run` 输出在 stdout。 ## Goals / Non-Goals **Goals:** - 终端里能一眼看到"进行到哪、还剩多久、是不是卡住了"。 - 重定向到日志时可按需得到稳定、完整、可 `tail` 的进度行。 - 估算成本有上界,估不出来就诚实地不显示。 - 进度实现与归档逻辑解耦,可注入时钟与 writer 做单测。 **Non-Goals:** - 不做机器可读事件流(JSONL)、颜色、多行 TUI。 - 不做精确 `COUNT(*)` 或后台异步计数。 - 不改变 chunk / 事务 / 文件 / checkpoint 的任何语义。 - 不为 `export-all` 脚本实现多表聚合进度(脚本可用 `--progress on` 获取日志行)。 ## Decisions ### D1:新增 `internal/progress` 作为深模块 `Reporter` 对外只暴露少量方法:`Start/Stop`、`Phase`、`AddRows`、`SetPosition`、`SetEstimate`、`Message`、`Snapshot`。渲染、TTY 判定、速率窗口、ETA 全部藏在内部。`app` 只负责在正确的时机推送事件,不知道渲染细节。 替代方案是直接在 `app.go` 里加 ticker 和格式化逻辑,但 `app.go` 已经 600 行且承担编排职责;把渲染测试塞进 `app` 会让集成测试更难写。 ### D2:`--progress` 改为 `auto|on|off|N`,而不是新增一堆布尔开关 仓库已有 `--progress N` 的调用方(集成测试、脚本),必须保留 `N>0` 的行阈值语义。把 flag 实现为自定义 `flag.Value`: - `auto`(默认):TTY 时开启,非 TTY 静默。 - `on`:始终开启,非 TTY 时退化为周期行。 - `off` / `0`:关闭。 - `N>0`:开启并额外按行阈值触发。 替代方案是保留 int 并用 `-1` 表示 auto;但 `--progress -1` 语义不直观,且 argparse 风格上容易被误读为错误。字符串取值可以把三种意图明确写进 `--help`。 ### D3:进度写 stderr,消息也收口到 Reporter stderr 是"给人看的诊断流",stdout 留给 `--dry-run` 和显式请求的 `--statistics`。这也让 `archer ... > result.txt` 不会把进度写进结果文件。 `app.go` 现有 6 处直接 `fmt.Fprintln(os.Stderr, ...)`(启动提示、指纹警告、purge 警告、中断警告、lag 等待)必须改走 `Reporter.Message`。`Message` 在 live 模式下先清当前行、打印整行消息,再在下一拍重绘;非 live 模式直接打印。`main.go` 的错误输出发生在 `Run` 返回之后,reporter 已停止,不需要改。 替代方案是让渲染器在检测到行长度变化时自行清行,但那样消息输出顺序无法保证,仍可能撕裂 live 行。 ### D4:TTY 判定与渲染 用标准库 `os.Stderr.Stat()` 判断 `ModeCharDevice`,不引入 `x/term`。live 模式单行渲染: ``` [###############-----] 58% ~4.12M rows 18.2k/s scan 0.4s shard 12 eta ~1m36s ``` - 只用 `\r` 回到行首,行尾用空格补齐到上一次宽度,不使用 `\x1b[K` 或颜色,保证 conhost 正常。 - 行宽目标 ≤ 100 字符;超宽时按优先级裁剪字段(先去掉分片序号与字节数,再缩短 bar),不换行。 - 无百分比时省略 bar/百分比/ETA,只留 rows、rate、phase、elapsed。 - 非 live 模式固定输出 `progress: rows=... pct=... estimate=... rate=... phase=... elapsed=...`,字段顺序稳定。 ### D5:阶段由主循环推送,Reporter 只记录 阶段切换点全部在 `app` 内:`probe`(`setupSource`)、`resume`(`prepareFile` 中 `Manifest.Adopt`)、`estimate`、`scan`/`file`/`db`/`checkpoint`(`processChunk` 内)、`finalize`(`finish`)、`lag-wait`(`lag.OnWait`)。Reporter 为每次 `Phase()` 调用累加前一阶段耗时并重置阶段计时。 扫描器与 writer 的状态**不**由后台线程读取:主循环在 chunk 完成后调用 `SetPosition(bucket, seq, bytes, lastKey)`,把 writer 的 `StatePosition/Stats` 结果和当前键位置复制进快照。这样后台线程只接触 Reporter 内部数据。 ### D6:并发模型:互斥量保护快照 Reporter 内部一个 `sync.Mutex` 保护 `snapshot` 结构(计数、阶段、阶段开始时间、估算、位置、消息代数)。主循环的 `AddRows/Phase/SetPosition` 都是短临界区;ticker 每次加锁复制一份快照,解锁后渲染。相比把每个字段拆成 `atomic.Int64`,互斥量让"一组字段的一致快照"更容易保证,也避免 `atomic.Value` 里放结构体的分配开销。 `Stats` 继续由主循环独占,供 `--statistics` 使用;Reporter 不反向写 `Stats`。两者在结束时由 `app` 汇总。 ### D7:估算查询:有界、只读、可放弃 估算在 `prepare` 之后、进入扫描前执行一次: - 日期模式:`SELECT MIN(shard_col), MAX(shard_col) FROM t WHERE (where) AND shard_col IS NOT NULL`。 - 非日期模式:仅当扫描键为单列整数类型时执行 `SELECT MIN(key), MAX(key) FROM t WHERE (where)`。 - 复合键、字符串/二进制键、或表没有可用索引时直接跳过。 查询在独立 `*sql.Conn` 上执行,`context.WithTimeout(2s)`。超时或出错则 `SetEstimate(nil)`,此后不显示百分比与 ETA,**不重试**。 路径 B 的扫描器稍后还会自己算一次 `MIN/MAX`(`initDays`)。这里接受一次重复的索引范围查询,换取 Reporter 与扫描器解耦;该查询与路径 B 首次查询量级相同,不影响正确性。 替代方案是让扫描器实现 `EstimateProvider` 接口,但那会把并发发布职责扩散到三个扫描器实现里。 ### D8:位置与百分比口径 - 日期模式:位置取当前 chunk 尾行的 bucket(`chunk.Buckets` 已有),百分比 = 已完成天数 / 总天数;显示 `day 37/120`,`estimate=day`。NULL 与零日期阶段单独处理,未进入正常日期前不显示天数进度。 - 非日期模式:位置取 `chunk.LastKey[0]` 的数值,百分比 = (当前键 − 最小键) / (最大键 − 最小键),`estimate=key`。 - 续跑时位置来自游标,天然包含此前进度。 已知口径限制写进 Risks,不在代码里假装精确。 ### D9:速率与 ETA Reporter 维护最近约 5 秒的 `(时间, 进度位置)` 样本环,速率用窗口内差分计算;不足两个样本时回退到累计平均。ETA = 剩余量 / 窗口速率,其中剩余量由百分比口径推导(天数或键跨度),而不是行数——因为总行数未知。ETA 与百分比一样带 `~`,且只在 `estimate != none` 时显示。 ### D10:生命周期 - `execute` 开始时 `Start`,`finish` 与 `interrupt` 结束时 `Stop`。 - `Stop` 先停 ticker、清 live 行;正常完成再输出 `done` 行,中断则输出最终快照行。 - `interrupt` 的执行顺序:停刷新 → 清行 → 快照 → 现有 `SealCurrent` → `saveState`,退出码不变。 - `--dry-run` 不启动 Reporter(没有运行循环)。 ### D11:续跑基线 `prepareFile` 读到 `state.json` 后,除现有游标外记录 `baseRows = st.RowsDone`。Reporter 的 `rows` 指标显示 `baseRows + 本次 RowsRead`;`saveState` 写入 `baseRows + 本次 RowsCommitted`。`--statistics` 增加"本次 / 累计"两列。 ### D12:不新增依赖 TTY 判定用 `os.File.Stat`;时间源注入 `func() time.Time`;渲染目标注入 `io.Writer`。单测不需要伪终端,直接用 `bytes.Buffer` + 手动推进时钟。 ## Risks / Trade-offs - **估算查询在繁忙库上仍可能拖慢启动** → 2s 上下文超时 + 只在启动时一次 + 绝不 `COUNT(*)`;超时后彻底放弃,不重试。 - **键位置百分比在键有空洞或分布不均时偏差大** → 标注 `estimate=key` 与 `~`;日期模式优先按天;任何估算都不影响归档逻辑。 - **日期模式的百分比按天跳变** → 显示 `day 37/120` 原文,让操作者看到真实口径;不把天进度伪装成行进度。 - **升级后首次续跑旧 checkpoint 时 `rows_done` 仍可能偏低** → 旧版本写入的值只是上次运行的行数;无法还原真实累计。文档说明该限制,不做迁移;新写入的值从此正确。 - **live 行与日志交错** → 所有 stderr 消息经 `Reporter.Message`;单测覆盖"消息插入后行内容完整"。 - **Windows conhost 不支持复杂控制序列** → 只使用 `\r` + 空格补齐;不引入颜色与光标移动。 - **进度从 stdout 转到 stderr 会改变现有调用方** → 集成测试更新;README/spec 明确通道;脚本本来就把 stderr 重定向进日志。 - **ticker 增加少量锁竞争** → 每秒一次、临界区仅是字段复制与格式化,开销可忽略。 ## Migration Plan - 仅发布新二进制,无数据迁移;`state.json` 版本不变,旧文件可读。 - 升级后第一次续跑可能沿用旧的偏低 `rows_done`,完成后即恢复累计语义。 - `scripts/export-all.ps1` 的 `-Verify` 在历史 checkpoint 上可能仍报一次差异,重新完成后消失;如需日志内进度,可给 archer 加 `--progress on`。 - 回滚到旧二进制不影响运行;旧二进制会按旧语义覆盖 `rows_done`,仅丢失累计值。