# cli-contract Specification
## Purpose
定义 archer 的命令行参数、默认值、参数之间的依赖与互斥规则,以及启动校验、错误信息和 dry-run 行为。
## Requirements
### Requirement: 必填参数
归档(导出)模式下,系统 MUST 要求提供 `--source` 与 `--where`,并且 `--file`、`--dest`、`--purge` 至少启用一个。缺少任一前置条件时,系统 MUST 在连接数据库前报错退出。
导入模式(`archer import`)MUST 要求提供 `--file` 与 `--dest`;`--source`、`--where`、`--purge` 在导入模式下 MUST 被拒绝。缺少必需参数时,系统 MUST 在连接目标数据库前报错退出。
#### Scenario: 缺少过滤条件
- **WHEN** 归档模式未提供 `--where`
- **THEN** 系统立即报错,提示 `--where` 必填,不建立数据库连接
#### Scenario: 没有任何输出目标
- **WHEN** 归档模式既未提供 `--file`、`--dest`,也未启用 `--purge`
- **THEN** 系统报错,提示至少需要一种输出目标
#### Scenario: 导入模式缺少目标
- **WHEN** `archer import` 未提供 `--dest`
- **THEN** 系统立即报错,提示 `--dest` 必填,不建立数据库连接
#### Scenario: 导入模式误用导出参数
- **WHEN** `archer import` 带上 `--source` 或 `--where`
- **THEN** 系统在解析阶段报错,说明该参数仅用于归档模式
### Requirement: 导入子命令
系统 MUST 提供 `archer import` 子命令,语法为 `archer import --file
--dest [flags]`。未知参数 MUST 报错。`archer import --help` MUST 打印导入模式的参数说明;`archer --version` 与 `archer import --version` MUST 均可打印版本并退出。
导入模式的参数与默认值:
| 参数 | 默认 | 说明 |
|---|---|---|
| `--file` | 必填 | 归档目录,必须存在且包含 `manifest.jsonl` |
| `--dest` | 必填 | 目标 MySQL DSN |
| `--dest-table` | 归档记录的源表名 | 目标表名;归档未记录表名时必须显式提供 |
| `--columns` | 空 | 按文件字段顺序给出目标列名;与 `--assume-all-columns` 互斥 |
| `--assume-all-columns` | 关闭 | 接受与目标表 ordinal 顺序一致的位置映射,并打印警告 |
| `--select` | `all` | 可重复;`all`、`seq:A-B`、`pk:LO-HI`、`date:D1..D2` |
| `--mode` | `ignore` | `ignore` / `insert` / `replace` |
| `--engine` | `load` | `load` / `insert` |
| `--verify` | `pre` | `pre` / `off` |
| `--workers` | `1` | 并行分片数,必须大于 0 |
| `--charset` | `utf8mb4` | 装载时使用的字符集 |
| `--time-zone` | 空 | 设置目标会话时区;空表示使用服务端默认 |
| `--allow-partial` | 关闭 | 允许导入未完成归档的已封分片 |
| `--allow-warnings` | 关闭 | 服务端告警不视为失败 |
| `--dry-run` | 关闭 | 只打印选片与配置 |
| `--progress` | `auto` | 进度输出 |
| `--statistics` | 关闭 | 结束汇总 |
#### Scenario: 最小导入命令
- **WHEN** 用户执行 `archer import --file ./export/orders --dest 'user:pass@tcp(host:3306)/db'`
- **THEN** 系统按默认值解析为 `all` / `ignore` / `load` / `pre` / 1 个 worker
#### Scenario: 未知参数
- **WHEN** 用户给 `archer import` 传入未定义的参数
- **THEN** 系统报错并以退出码 2 结束
#### Scenario: 非法 worker 数
- **WHEN** 用户指定 `--workers 0`
- **THEN** 系统在连接数据库前报错,说明必须大于 0
#### Scenario: 非法模式
- **WHEN** 用户指定 `--mode merge` 或 `--engine bulk`
- **THEN** 系统在解析阶段报错,列出允许的取值
#### Scenario: 列映射参数互斥
- **WHEN** 用户同时指定 `--columns` 与 `--assume-all-columns`
- **THEN** 系统在连接数据库前报错,说明二者只能选一个
#### Scenario: 归档已记录列清单又显式指定映射
- **WHEN** `state.json` 的 `columns` 非空,且用户仍指定 `--columns` 或 `--assume-all-columns`
- **THEN** 系统报错,避免两套映射来源冲突
### Requirement: 导入模式的 dry-run、进度与退出码
`--dry-run` 时,系统 MUST 打印解析后的导入配置、选中分片与汇总,MUST NOT 执行装载或写入。`--progress` 与 `--statistics` 在导入模式下的语义 SHALL 与归档模式一致,分别输出分片进度与结束汇总。
成功完成 MUST 返回 0;参数或配置错误 MUST 返回 2;连接、校验或装载失败 MUST 返回非零退出码。被信号中断时 MUST 停止开始新的分片并返回非零退出码。
#### Scenario: dry-run
- **WHEN** 用户执行 `archer import ... --dry-run`
- **THEN** 标准输出包含选中分片、总行数与总字节数,目标库没有数据变化
#### Scenario: 结束统计
- **WHEN** 用户执行 `archer import ... --statistics`
- **THEN** 进程退出前输出成功/跳过/失败分片数、行数与耗时
#### Scenario: 配置错误退出码
- **WHEN** `--select` 语法非法
- **THEN** 进程以退出码 2 结束,不建立数据库连接
### 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 0`。
#### Scenario: 最小可运行配置
- **WHEN** 用户只提供 `--source`、`--table`、`--where`、`--file`
- **THEN** 系统以 2000 行一个 chunk、不分片、dump 格式、不压缩的方式导出
### 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 视为配置错误。违反时 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** 系统在启动阶段报错,说明压缩档位仅在启用压缩时有效
### Requirement: 日期列探测与错误提示
启动时,系统 SHALL 读取表元数据并判断 `--shard-column` 是否存在、类型是否受支持、是否可为 NULL。缺少 `--shard-column` 时 MUST 列出所有候选日期/时间列及其类型。整数列缺少单位声明时 MUST 采样最小/最大值,并展示按秒、毫秒、微秒解释后的日期范围。
#### Scenario: 列出候选列
- **WHEN** 用户指定 `--shard-by date` 但未给 `--shard-column`
- **THEN** 错误信息包含表内所有 DATE/DATETIME/TIMESTAMP 列的列名、类型与可空性
#### Scenario: epoch 单位提示
- **WHEN** 分片列为 BIGINT 且未声明单位
- **THEN** 错误信息展示采样范围以及三种单位解释下的日期范围,不自动选择
### Requirement: dry-run
`--dry-run` 时,系统 MUST 打印解析后的配置、索引探测结果、最终生效的分片与格式参数,以及第一条将要执行的 SELECT 和每类写入语句,然后退出。系统 MUST NOT 建立写入连接、创建目录或写文件。
#### Scenario: dry-run 输出 SQL
- **WHEN** 用户传入 `--dry-run`
- **THEN** 标准输出包含解析后的配置和将要执行的 SQL,进程以 0 退出
### Requirement: 进度与统计
当 `--progress N` 大于 0 时,系统 SHALL 每处理 N 行输出一次进度,包含已处理行数、当前分片序号与耗时。启用 `--statistics` 时,系统 MUST 在结束时输出读取行数、写入行数、删除行数、分片数与各阶段耗时。
#### Scenario: 周期进度
- **WHEN** `--progress 100000`
- **THEN** 每处理 100000 行打印一行进度信息
#### Scenario: 结束统计
- **WHEN** 启用 `--statistics`
- **THEN** 进程退出前输出汇总统计
### Requirement: 退出码
系统 SHALL 在成功完成时返回 0;配置错误、连接错误、写入错误或校验失败时返回非零退出码。被信号中断时 MUST 完成当前 chunk 的清理并返回非零退出码。
#### Scenario: 配置错误
- **WHEN** 参数校验失败
- **THEN** 进程以非零退出码结束,且不产生部分输出文件
#### Scenario: 信号中断
- **WHEN** 进程收到 SIGINT
- **THEN** 系统停止拉取新 chunk,关闭并 flush 当前分片,写入 checkpoint,然后以非零退出码结束