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

38 lines
3.5 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
## Why
archer 面向的是长时间运行的大表归档/导出,但当前唯一的进度输出(`--progress N`)只在 chunk 完整处理完后按行数阈值打印一行,既没有速率、百分比和 ETA,也不显示当前处于扫描、写文件、写库还是等待副本延迟。路径 B 的单日长查询、fsync 与 `lag.Wait` 期间完全没有输出,操作者无法区分"正在慢"和"已经卡死";续跑后进度与 `state.json` 的行数还会从零重新起算。
这次改动把进度从"稀疏日志"变成"给人看的实时显示",同时修正续跑计数语义。
## What Changes
- 新增默认 `--progress auto`:stderr 是终端时输出单行实时刷新(`\r` 覆盖、空格补齐、不使用 ANSI 清行与颜色,兼容 Windows conhost);非终端时保持静默。
- `--progress on|off|auto|N`:`on` 强制开启(非终端时按间隔输出稳定的 key=value 行,便于 `tail` 日志),`N>0` 保留现有行阈值语义,`off`/`0` 关闭。新增 `--progress-interval`(默认 1s)。
- 进度行统一写 stderr;`--dry-run` 与 `--statistics` 仍在 stdout。
- 显示内容包含 rows、窗口速率、分片序号、已写字节、当前阶段及各阶段耗时、elapsed;在能廉价估算总量时额外显示带 `~` 的百分比与 ETA,并标注估算口径(`day|key`)。
- 新增阶段模型:`probe → resume → estimate → scan → file → db → checkpoint → finalize`,`lag-wait` 作为 scan 前的独立阶段;长阻塞期间持续刷新。
- 进度开启时,结束打印一行 `done` 汇总;中断时停止刷新、清除 live 行并打印最终快照后再执行现有的封片与 checkpoint。
- **BREAKING(行为)**:`state.json` 的 `rows_done` 改为累计值(含续跑前已处理行数)。旧 checkpoint 继续可读;语义变化会影响依赖该字段的校验脚本(修正 `scripts/export-all.ps1 -Verify` 的误报)。
- `--statistics` 分开展示"本次运行"与"累计(含续跑)"。
- 应用内所有面向人的警告与 lag 提示收口到进度 reporter,避免与 live 行交错。
非目标:JSONL/机器可读进度、彩色输出、多行 TUI、精确 `COUNT(*)`、后台异步计数、`export-all` 脚本自身的多表进度条(脚本可通过 `--progress on` 获得日志行)。
## Capabilities
### New Capabilities
- `progress-reporting`: 进度输出的模式与降级、显示指标与格式、廉价总量估算与回退、阶段模型、中断与完成时的最终快照、续跑基线语义。
### Modified Capabilities
- `cli-contract`: `--progress` 的取值与默认值、新增 `--progress-interval`、进度输出通道(stderr)及 TTY/非 TTY 行为。
- `archive-core`: 运行循环的阶段标记、lag 等待期间的进度、中断时的最终快照,以及 `state.json` 中 `rows_done` 的累计语义与 `--statistics` 口径。
## Impact
- 代码:新增 `internal/progress`;修改 `internal/app/app.go`(阶段标记、消息收口、续跑基线、done/中断快照)、`internal/app/probe.go` 或扫描器(暴露日期/键边界供估算)、`internal/cli/{parse,config,validate}.go`、`internal/checkpoint` 使用方、`internal/lag` 的等待回调。
- 输出契约:进度从 stdout 移到 stderr;集成测试中按 stdout 抓 `progress:` 的用例需要更新。
- 脚本:`scripts/export-all.ps1` 的 `-Verify` 恢复正确;可选加 `--progress on` 让日志可 `tail -f`。
- 依赖:不新增第三方库(TTY 判定使用标准库;不使用 ANSI 清行)。