## Purpose 定义 archer 面向操作者的实时进度显示:何时显示、显示什么、百分比与 ETA 如何估算与降级,以及完成和中断时的最终反馈,使长时间归档任务的运行状态可被直接观察。 ## ADDED Requirements ### Requirement: 进度模式与输出通道 `--progress` SHALL 接受 `auto`、`on`、`off` 或正整数,默认 `auto`。`auto` 时,当 stderr 是终端则启用实时进度,否则 MUST 不输出任何进度行。`on` MUST 始终启用进度。`off` 或 `0` MUST 关闭进度。正整数 MUST 在按间隔输出之外,额外作为"每处理 N 行至少触发一次"的行阈值。 所有进度输出 MUST 写入 stderr。`--dry-run` 与 `--statistics` 的输出 MUST 保持在 stdout。启用 `--progress-interval` 且值为非正数时 MUST 视为配置错误。 #### Scenario: 终端下的默认模式 - **WHEN** 用户未传 `--progress`,且 stderr 是终端 - **THEN** 系统显示实时进度 #### Scenario: 重定向时的默认模式 - **WHEN** 用户未传 `--progress`,且 stderr 被重定向到文件或管道 - **THEN** 系统不输出进度行,只有警告与错误信息 #### Scenario: 强制开启写入日志 - **WHEN** 用户传 `--progress on`,且 stderr 被重定向 - **THEN** 系统按 `--progress-interval` 向 stderr 输出进度行,每行是一条完整的 key=value 记录 #### Scenario: 关闭进度 - **WHEN** 用户传 `--progress off` 或 `--progress 0` - **THEN** 系统不输出任何进度行 #### Scenario: 非法进度参数 - **WHEN** 用户传 `--progress abc` 或 `--progress-interval 0s` - **THEN** 系统在连接数据库前以配置错误退出 ### Requirement: 刷新节奏 系统 MUST 至少每隔 `--progress-interval`(默认 `1s`)输出一次进度,并在启用行阈值时于跨过阈值的 chunk 边界额外输出。无论是否到达间隔或阈值,完成与中断时 MUST 输出一次最终快照。 #### Scenario: 慢 chunk 仍在刷新 - **WHEN** 单个 chunk 的扫描或写库耗时超过 `--progress-interval` - **THEN** 系统在该 chunk 处理期间仍按间隔输出进度,不出现长时间静默 #### Scenario: 行阈值提前触发 - **WHEN** `--progress 100000`,且两个间隔之间处理行数超过 100000 - **THEN** 系统在跨过阈值时额外输出一次进度 ### Requirement: 显示指标 终端模式下,进度 MUST 以单行原地刷新(使用回车覆盖并以空格补齐,不依赖 ANSI 清行或颜色)。进度行 MUST 包含:已处理行数、当前速率、当前阶段及阶段内耗时、本次运行已用时间。当当前分片存在时 MUST 包含分片序号;写入文件时 MUST 包含已写字节数。存在总量估算时 MUST 额外包含百分比与 ETA,并以 `~` 标注为估算值。 非终端模式下,每行 MUST 是一条独立、完整、稳定的 key=value 记录,至少包含 `rows`、`rate`、`phase`、`elapsed`;存在估算时包含 `pct`、`estimate` 与 `eta`。记录 MUST NOT 使用回车覆盖。 #### Scenario: 终端单行刷新 - **WHEN** stderr 是终端且进度启用 - **THEN** 每秒在同一行内更新进度,不向终端累积刷屏 #### Scenario: 重定向下的一行一记录 - **WHEN** stderr 被重定向且通过 `--progress on` 启用进度 - **THEN** 每行是一条完整记录,不含回车控制字符,可直接 `tail` 或按行解析 ### Requirement: 廉价总量估算与降级 系统 MUST 只使用有界成本的估算方式,MUST NOT 默认执行 `COUNT(*)`。日期分片模式 SHALL 使用分片列的 `MIN`/`MAX` 得到天数进度,并标注估算口径为 `day`;非日期模式仅在扫描键是单列整数唯一键时使用键的 `MIN`/`MAX` 做位置比例,并标注为 `key`。估算查询 MUST 在独立连接上执行并设有超时上限;超时、失败或口径不适用时,系统 MUST 静默降级为不显示百分比与 ETA,并标注 `estimate=none`。 百分比与 ETA MUST 带 `~` 前缀。ETA MUST 基于本次运行的推进速率与剩余量计算,MUST NOT 使用"已用时间 ÷ 百分比"。 #### Scenario: 日期模式按天估算 - **WHEN** `--shard-by date` 且存在可用的分片列索引 - **THEN** 进度显示形如 `day 37/120` 的百分比与 ETA,并标注 `estimate=day` #### Scenario: 单列整数键估算 - **WHEN** 非日期模式,扫描键是单列整数唯一键 - **THEN** 进度显示基于键位置的百分比与 ETA,并标注 `estimate=key` #### Scenario: 复合键或字符串键 - **WHEN** 扫描键为复合键或非整数类型 - **THEN** 进度不显示百分比与 ETA,并标注 `estimate=none` #### Scenario: 估算超时 - **WHEN** 估算查询在超时上限内未返回 - **THEN** 系统放弃本次估算,进度降级为仅显示行数与速率,归档继续执行 ### Requirement: 阶段可见性 系统 MUST 在进度中显示当前阶段,阶段集合为:`probe`、`resume`、`estimate`、`scan`、`file`、`db`、`checkpoint`、`finalize`、`lag-wait`。阶段内耗时 MUST 随时间递增,使操作者可以区分"正在慢"与"已经卡死"。`lag-wait` 阶段 MUST 显示等待原因。 #### Scenario: 等待副本延迟 - **WHEN** 副本延迟超过 `--max-lag` - **THEN** 进度显示 `lag-wait` 阶段与等待原因,而不是只输出一条 `waiting:` 消息 #### Scenario: 长扫描期间保持刷新 - **WHEN** 路径 B 的单日查询长时间未返回首个 chunk - **THEN** 阶段保持 `scan`,进度继续按间隔刷新,阶段内耗时持续增长 ### Requirement: 消息与实时行互斥 在实时进度启用时,任何警告、提示或 lag 等待消息 MUST NOT 与实时行交错。系统 MUST 在输出消息前清除当前实时行,并在下一个刷新周期重新绘制。 #### Scenario: 警告出现在实时行之后 - **WHEN** 实时进度运行期间产生一条警告 - **THEN** 警告单独占一行,实时行不在同一行上被截断或拼接 ### Requirement: 完成与中断反馈 进度启用时,正常完成 MUST 输出一行最终汇总,包含累计行数、耗时、分片数与已写字节(存在文件输出时)。收到中断信号时,系统 MUST 先停止刷新、清除实时行并输出最终快照,然后执行现有的封片与 checkpoint 写入,退出码保持现有语义(130)。 #### Scenario: 正常完成 - **WHEN** 扫描自然结束且进度启用 - **THEN** 在退出前输出一行 `done` 汇总 #### Scenario: 中断时保留现场 - **WHEN** 运行期间收到 SIGINT - **THEN** 进度停止并输出最终快照,随后当前分片被封存、checkpoint 被写入,进程以 130 退出 ### Requirement: 续跑基线 进度中的已处理行数 MUST 包含当前输出目录在续跑前已提交的行数,即 `已处理 = 续跑前累计 + 本次运行读取行数`。续跑后进度 MUST NOT 从零重新起算。 #### Scenario: 续跑后继续累计 - **WHEN** 上次运行处理 10000 行后中断,本次续跑处理 40000 行 - **THEN** 进度显示已处理行数为 50000,而不是 40000