Files
archer/openspec/changes/add-realtime-progress/specs/cli-contract/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

69 lines
3.5 KiB
Markdown
Raw 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.
## MODIFIED Requirements
### Requirement: 默认值
系统 SHALL 采用以下默认值:`--chunk-size 2000`、`--shard-by none`、`--shard-rows 0`、`--format dump`、`--compress none`、`--compress-level 3`、`--max-lag 1s`、`--check-interval 1s`、`--retries 1`、`--safe-auto-increment true`、`--progress auto`、`--progress-interval 1s`。
#### Scenario: 最小可运行配置
- **WHEN** 用户只提供 `--source`、`--table`、`--where`、`--file`
- **THEN** 系统以 2000 行一个 chunk、不分片、dump 格式、不压缩的方式导出
#### Scenario: 默认进度模式
- **WHEN** 用户未显式指定 `--progress`
- **THEN** stderr 是终端时显示实时进度,否则不输出进度行
### Requirement: 参数依赖与互斥
系统 MUST 校验以下规则:`--shard-by date` 必须有 `--shard-column`;`--shard-by count|none` 不得带 `--shard-column`;`--shard-rows` 仅在 `--shard-by count` 或 `date` 时有效;`--bulk-delete` 依赖 `--purge` 且在日期模式下禁止;普通插入、`--insert-ignore`、`--replace` 三者互斥;`--compress-level` MUST 在 1–9 范围内;`--compress none` 与非默认档位同时出现时 MUST 视为配置错误;`--progress` MUST 取值 `auto`、`on`、`off` 或非负整数;`--progress-interval` MUST 为正时长。违反时 MUST 在启动阶段报错。
#### Scenario: 数量模式误传日期列
- **WHEN** `--shard-by count` 同时带上 `--shard-column`
- **THEN** 系统报错,说明该参数仅在日期模式下有效
#### Scenario: 未启用 purge 却要求 bulk-delete
- **WHEN** 用户指定 `--bulk-delete` 但未指定 `--purge`
- **THEN** 系统报错,说明 bulk-delete 必须配合 purge
#### Scenario: 插入模式互斥
- **WHEN** 用户同时指定 `--insert-ignore` 与 `--replace`
- **THEN** 系统报错,要求只能选择一种插入模式
#### Scenario: 压缩档位越界
- **WHEN** 用户指定 `--compress-level 0` 或 `--compress-level 10`
- **THEN** 系统在启动阶段报错,说明档位必须在 1–9 之间
#### Scenario: 不压缩却指定非默认档位
- **WHEN** 用户指定 `--compress none` 与 `--compress-level 5`
- **THEN** 系统在启动阶段报错,说明压缩档位仅在启用压缩时有效
#### Scenario: 非法进度参数
- **WHEN** 用户指定 `--progress abc`、`--progress -1` 或 `--progress-interval 0s`
- **THEN** 系统在启动阶段报错,说明取值要求
### Requirement: 进度与统计
`--progress` SHALL 接受 `auto`、`on`、`off` 或非负整数,默认 `auto`。`auto` 时,stderr 是终端则启用实时进度,否则不输出进度行;`on` MUST 始终启用;`off` 与 `0` MUST 关闭;正整数 MUST 额外作为每处理 N 行触发一次的行阈值。`--progress-interval` MUST 控制最小输出间隔,默认 `1s`。所有进度输出 MUST 写入 stderr;`--dry-run` 与 `--statistics` 的输出 MUST 保持在 stdout。启用 `--statistics` 时,系统 MUST 在结束时分别输出本次运行与含续跑的累计读取行数、写入行数、删除行数、分片数与各阶段耗时。
#### Scenario: 周期进度
- **WHEN** `--progress 100000`
- **THEN** 系统至少每 `--progress-interval` 输出一次进度,并在每处理 100000 行时额外输出一次
#### Scenario: 终端实时进度
- **WHEN** stderr 是终端且进度启用
- **THEN** 系统在同一行内刷新进度,并输出到 stderr
#### Scenario: 结束统计
- **WHEN** 启用 `--statistics`
- **THEN** 进程退出前输出汇总统计,并区分本次运行与含续跑的累计值