Files
archer/openspec/changes/add-realtime-progress/specs/progress-reporting/spec.md
T
voidandClaude Sonnet 4.6 bc4a6b504f Initial commit: archer, a Go-native MySQL/MariaDB table archiver
Renamed from arcdb: module path, cmd/archer, internal/archererr,
docs, build scripts and ARCHER_* environment variables.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-11-06 22:12:17 +08:00

139 lines
6.9 KiB
Markdown

## 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