## 1. CLI 子命令与配置 - [x] 1.1 `cmd/archer/main.go`:在解析参数前识别 `os.Args[1] == "import"`,分发到导入入口;其余参数保持现有行为 - [x] 1.2 新建 `internal/cli/import.go`:`ImportConfig`、`ParseImport`、`ValidateImport`,与现有 `Config` 解耦 - [x] 1.3 实现导入参数与默认值:`--file`、`--dest`、`--dest-table`、`--columns`、`--assume-all-columns`、`--select`、`--mode`、`--engine`、`--verify`、`--workers`、`--charset`、`--time-zone`、`--allow-partial`、`--allow-warnings`、`--dry-run`、`--progress`、`--statistics` - [x] 1.4 拒绝导出专属参数(`--source`、`--where`、`--purge` 等)与未知参数,退出码 2;`--columns` 与 `--assume-all-columns` 互斥 - [x] 1.5 `archer import --help` 与 `archer import --version` 可用 - [x] 1.6 单元测试:默认值、参数互斥、非法 `--mode`/`--engine`/`--workers`/`--select`、导出参数被拒绝、列映射参数冲突 ## 2. 归档读取与选片 - [x] 2.1 在 `internal/shard` 新增严格只读清单加载器:解析失败即报错,不打开追加句柄、不修改归档 - [x] 2.2 从 `Entry.Path` 推导格式与压缩方式,并要求所有选中分片一致;非 `dump` 报错 - [x] 2.3 实现 `--select` 解析:`all`、`seq:A-B`、`pk:LO-HI`、`date:D1..D2`,多次取并集、按 `seq` 去重排序 - [x] 2.4 `pk:` 使用分片区间相交语义;`date:` 在清单无日期桶时报错 - [x] 2.5 使用 `checkpoint.Load` 实现完成度门槛:默认要求 `complete == true`,`--allow-partial` 放开 - [x] 2.6 校验选中分片文件存在;清单损坏、条目文件缺失时在连接数据库前报错 - [x] 2.7 单元测试:四种选择器、并集去重、空选择、日期桶缺失、损坏清单行、缺失文件、完成度门槛 ## 3. 目标库前置检查与列映射 - [x] 3.1 建立目标连接,执行 `SELECT @@local_infile, @@version`;`--engine load` 且关闭时给出可操作错误 - [x] 3.2 校验目标表存在(`information_schema.tables`),不存在时报错 - [x] 3.3 加载目标列元数据(名、ordinal、是否为 `VIRTUAL/STORED GENERATED`) - [x] 3.4 归档记录列清单时:按记录顺序按名校验目标列存在、拒绝包含生成列、生成 `LOAD DATA` 列清单 - [x] 3.5 `--columns` 模式:解析用户提供的文件字段顺序,做与 3.4 相同的名校验 - [x] 3.6 `--assume-all-columns` 模式:按目标 ordinal 生成列清单,生成列替换为 `@_archer_skip_` 丢弃变量,打印位置映射警告 - [x] 3.7 无任何映射来源时拒绝导入,提示 `--columns` 或 `--assume-all-columns` - [x] 3.8 读取首个选中分片首行,按未转义 TAB 统计字段数,与列清单长度比较;不一致在装载前报错 - [x] 3.9 每个 worker 使用固定 `*sql.Conn`,设置 `character_set` 与可选 `time_zone` - [x] 3.10 单元测试:名校验、缺失列、生成列拒绝、位置映射丢弃变量、字段数不一致、映射来源缺失 ## 4. load 引擎 - [x] 4.1 实现单分片流式装载:注册唯一 `Reader` handler → 解压 Reader → 执行 `LOAD DATA LOCAL INFILE 'Reader::'` → 注销 - [x] 4.2 生成与 `dump` 编码严格对应的 SQL:`FIELDS TERMINATED BY '\t' ESCAPED BY '\\' LINES TERMINATED BY '\n'`、`CHARACTER SET`、可选列清单、`IGNORE`/`REPLACE` - [x] 4.3 实现 `--verify pre`:流式计算压缩文件 SHA-256 并与清单比对;`--verify off` 跳过 - [x] 4.4 装载后在同一会话执行 `SHOW WARNINGS`;有告警且未指定 `--allow-warnings` 时失败 - [x] 4.5 实现行数规则:`insert` 要求 affected == rows;`ignore` 要求 affected <= rows 并报告差额;`replace` 只报告 - [x] 4.6 确保失败路径清理 handler 注册与文件句柄 - [x] 4.7 单元测试:SQL 形状、模式映射、哈希不一致、告警失败、行数规则 ## 5. insert 兜底引擎 - [x] 5.1 实现最小 `dump` 行解码器:TAB 分隔、`\N` → NULL、反转义 `\\ \t \n \r \0 \b \Z` - [x] 5.2 复用 `internal/sink.DB` 的分批插入逻辑,按 `max_allowed_packet` 切批 - [x] 5.3 每个分片的所有批次包在同一个事务中,保证分片级原子 - [x] 5.4 单元测试:解码器边界(空串、NULL、转义、中文、emoji、BLOB)、分批与事务提交/回滚 ## 6. 运行编排 - [x] 6.1 实现 worker 池:按连续 `seq` 区间分配,默认 1,结果与串行一致 - [x] 6.2 接入 `internal/progress.Reporter`:以清单总行数为总量,按分片与行数推进 - [x] 6.3 实现 `--statistics`:选片数、成功/失败/跳过分片数、期望/实际/跳过行数、字节与耗时 - [x] 6.4 实现 `--dry-run`:只读清单与首行,打印选片、总行数/字节、目标表与引擎,不连接目标库、不装载 - [x] 6.5 失败即停:报告失败分片 `seq`、原因与累计行数;已成功分片保留 - [x] 6.6 用 `internal/archererr` 映射退出码:配置 2、连接 3、写入 4、校验 5、中断 130 - [x] 6.7 信号中断:停止开始新分片,当前分片完成或安全失败后以非零码退出 ## 7. 测试 - [x] 7.1 单元测试:选片、清单、字段数、SQL、解码器、退出码 - [x] 7.2 集成测试:导出小表 → 导入空表,比较行数与抽样内容(沿用 `ARCHER_TEST_DSN` 门控) - [x] 7.3 集成测试:`none`/`gzip`/`zstd`/`xz` 四种压缩的导入 - [x] 7.4 集成测试:`ignore` 重复导入幂等、`insert` 遇重复失败、`replace` 覆盖 - [x] 7.5 集成测试:篡改分片触发哈希失败、`complete=false` 默认拒绝与 `--allow-partial` 放开 - [x] 7.6 集成测试:`--workers 1` 与 `--workers 4` 导入结果一致 - [x] 7.7 集成测试:`--engine insert` 与 `--engine load` 结果一致 - [x] 7.8 保真测试:NULL、TAB、换行、反斜杠、中文、emoji、BLOB 的导出→导入往返 - [x] 7.9 列映射测试:归档列清单、`--columns`、`--assume-all-columns` 三种来源;目标表含生成列时丢弃变量生效;缺失列/字段数不一致被拒绝 - [x] 7.10 `gofmt`、`go build ./...`、`go vet ./...`、`go test ./...` 通过 ## 8. 文档与 OpenSpec - [x] 8.1 新增 `docs/import.md`:使用示例、选片语义、完整性检查、两种引擎、`local_infile` 与代理限制、导回原表的注意事项 - [x] 8.2 更新 `README.md` 的功能与文档索引 - [x] 8.3 更新 `docs/cli-reference.md` 的导入参数表 - [x] 8.4 运行 `openspec validate add-archive-import --strict` - [x] 8.5 在具备 MySQL 的环境中完成一次真实归档目录的按需导入,并记录结果 - 2026-11-08:临时 MySQL 8.3.0 实例(`local_infile=ON`)。`ARCHER_TEST_DSN` 门控下运行 `go test ./internal/importer -run Integration -v`,导出→导入、四种压缩、三种模式、哈希/完成度门槛、workers 1/4、load/insert 引擎、保真往返、三种列映射全部通过。 - 2026-11-08 手工 CLI:导出一张 7 行表为 3 个 count 分片;`archer import --workers 2 --assume-all-columns --statistics` 导入空表,7/7 行与原表逐列一致(affected=7,skipped=0)。默认 `ignore` 重跑:affected=0,skipped=7。`--dry-run` 未建立连接。 - 同次运行 `go build ./...`、`go vet ./...`、全量 `go test ./...` 均通过。