Files
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

6.9 KiB

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