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