Add archer import and allow date-mode bulk delete

archer import replays a sealed archive into an existing table: shard
selection (`--select`), SHA-256 pre-verification, idempotent modes
(`ignore`/`insert`/`replace`), and both LOAD DATA and batched-INSERT
engines. It reads manifest.jsonl strictly so corruption is reported
instead of skipped, and supports --dry-run, --allow-partial, and
per-shard workers.

--bulk-delete no longer rejects --shard-by date. Range deletion now
derives its bounds from the chunk's actual keys (date scanners rewrite
LastKey into a resumption cursor) and keeps safe-auto-increment
semantics by excluding the current max key. A startup warning documents
the monotonic-shard-column assumption.

Also splits CLI/format/sharding/progress/safety reference docs out of
the README, and adds the corresponding OpenSpec change artifacts.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
voidandClaude Sonnet 4.6 committed 2026-11-08 21:14:23 +08:00
1 parent bc4a6b504f
commit 366d61ca25
49 files changed
+5099 -342

No files matched your search

@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-11-08
@@ -0,0 +1,50 @@
## Context
现状与动机见 `proposal.md`。与设计直接相关的约束:
- 日期扫描器(路径 A/B)按 `(分片列, 唯一键)` 排序,并把 `chunk.LastKey` 改写为 `(分片列, 键...)` 的复合游标用于续跑;`chunk.FirstKey` 仍是裸键(`internal/scan/date_a.go:72-73`、`internal/scan/date_b.go:87-92`)。
- `Purger.deleteRange` 原先直接使用 `FirstKey/LastKey`(`internal/purge/purge.go`)。放开日期模式后,单列主键会生成 `id BETWEEN <首键> AND <日期>`,复合键则因 `lo` 与 `hi` 长度不同导致参数个数不匹配。
- `DeleteChunk` 在 `--safe-auto-increment=true`(默认)且键为单列自增列时先取 `MAX(pk)`;原逻辑只要 `maxKey != nil` 就退回 IN 列表,因此默认配置下 `--bulk-delete` 实际上从不执行区间删除。
- “日期随主键递增、无回填、无 NULL/零日期”是业务承诺,运行期无法可靠验证:单个 chunk 内的键单调性检查无法发现“整块迟到数据自成一个 chunk”的情况。
## Goals / Non-Goals
**Goals:**
- 在业务承诺成立时,日期模式可以使用区间删除。
- 区间删除严格对应本次 chunk 读到的裸键范围,不因续跑游标的形状而越界。
- 保留 `--safe-auto-increment` 的语义:任何 purge 模式都不删除当前最大自增行。
- 风险以启动警告、spec 和 README 明确表达,而不是静默承担。
**Non-Goals:**
- 运行期校验全局单调不变量。
- 自动检测回填、迟到数据或 NULL/零日期。
- 改变默认删除方式(不使用 `--bulk-delete` 时仍是 IN 列表)。
## Decisions
### D1:放开校验,用启动警告承载风险
删除 `validate.go` 中“日期模式禁止 `--bulk-delete`”的分支,在 `App.execute` 中新增一条仅日期模式出现的警告。替代方案是新增一个 `--allow-unsafe-date-bulk` 之类的二次开关,但那会增加一个只为绕过自身校验而存在的参数;风险提示已经足以表达“这是显式承担前提”。
### D2:区间边界取 `chunk.Keys` 首尾
`Keys` 与扫描行一一对应且始终是裸唯一键;`FirstKey/LastKey` 中的 `LastKey` 会被日期扫描器改写成复合游标。改用 `c.Keys[0]` 与 `c.Keys[len-1]` 后,非日期模式的行为完全不变(两者本就相等),日期模式则得到正确的裸键区间。`FirstKey/LastKey` 继续只承担分片与 checkpoint 职责,不改变其语义。
### D3:区间删除中排除当前最大键,而不是退回 IN 列表
当 `--safe-auto-increment` 生效时,仍先查询 `MAX(pk)`,但区间 SQL 追加 `AND pk <> ?`,参数为当前最大键。最大键不在区间内时该条件无效果;在区间内时恰好跳过该行。这样默认配置下 `--bulk-delete` 真正生效,同时保持“不删除当前最大自增行”的契约。复合键或非自增键不会设置 `maxKey`,SQL 保持原样。
替代方案是在区间删除时把上界改成开区间 `pk < max`,但需要比较 `hi` 与 `maxKey` 的大小并处理并发删除导致的 `hi > max` 情形;`<>` 更简单且对越界情况天然安全。
### D4:测试分两层
- 单元测试:用记录型 `Execer` 直接驱动 `deleteRange`,覆盖日期式 `LastKey`、单列/复合键、以及最大键排除三种 SQL 形状。
- 集成测试:`TestIntegrationDateBulkDelete` 在 `(created_at, id)` 联合索引上分别验证 `--safe-auto-increment=false` 全删、默认开启时保留最大行;无 `ARCHER_TEST_DSN` 时自动跳过。
## Risks / Trade-offs
- **回填/迟到数据仍会误删** → 业务承诺无法运行期验证。缓解:启动警告、spec 与 README 明确前提;建议在生产使用前先用 `--dry-run` 与只导出运行核对。出现回填时应回到默认 IN 列表删除。
- **`--bulk-delete` 的并发窗口仍然存在** → 与既有取舍一致:区间内新插入且满足 `--where` 的行可能被删。日期模式下该风险进一步依赖“日期随主键递增”的假设。
- **`pk <> MAX(pk)` 在并发删除时可能多保留一行** → 只影响“少删”,方向安全;与 IN 列表模式跳过最大行的行为一致。
@@ -0,0 +1,32 @@
## Why
日期分片按 `(分片列, 唯一键)` 排序,日期序与主键序可能不一致。早期设计为规避“区间跨日期误删尚未归档的数据”,直接在启动校验阶段禁止了 `--shard-by date` 与 `--bulk-delete` 的组合。
对于业务上能保证“日期随主键递增、无回填、无 NULL/零日期”的表,这个限制堵死了一条本可安全使用的高吞吐删除路径。本次改动按“显式承担该前提”的方式放开限制,同时修正两处在放开后会暴露的问题:区间边界取错,以及默认 `--safe-auto-increment` 会让区间删除静默退回 IN 列表。
## What Changes
- 允许 `--shard-by date` 与 `--bulk-delete` 同时使用;启动时打印前提警告。
- 区间删除的边界改为 chunk 实际读取行的裸唯一键首尾,不再使用日期扫描器为续跑改写的 `(分片列, 键...)` 复合游标。
- 修正 `--safe-auto-increment` 与 `--bulk-delete` 的交互:区间删除不再退回 IN 列表,而是在 SQL 中显式排除当前最大自增键。
- 同步 `archive-core` 与 `cli-contract` 的行为契约,以及 README 的安全说明。
**Non-goals:**
- 不在运行期验证“日期随主键递增、无回填”这一不变量。
- 不自动识别或隔离迟到/回填数据。
- 不改变 chunk 即事务、提交顺序、checkpoint 等既有语义。
## Capabilities
### Modified Capabilities
- `archive-core`:日期模式下允许区间删除,明确其安全前提;区间边界取 chunk 裸键首尾;`--safe-auto-increment` 在区间删除中以排除最大键的方式生效。
- `cli-contract`:参数依赖与互斥规则中移除“`--bulk-delete` 在日期模式下禁止”。
## Impact
- 代码:`internal/cli/validate.go`(删除日期模式校验)、`internal/purge/purge.go`(区间边界与最大键排除)、`internal/app/app.go`(日期模式启动警告)。
- 测试:新增 `internal/purge/purge_test.go` 单元测试;新增 `TestIntegrationDateBulkDelete` 集成测试。
- 文档:`README.md`、`openspec/specs/{archive-core,cli-contract}/spec.md`。
- 兼容性:此前被拒绝的配置现在可以启动;未使用 `--bulk-delete` 的任务行为不变。
@@ -0,0 +1,30 @@
## MODIFIED Requirements
### Requirement: 删除语义
默认情况下,系统 MUST 以主键 IN 列表删除当前 chunk 实际读取到的行,并将过长的列表分批。启用 `--bulk-delete` 时,系统 SHALL 改为按 chunk 实际读取行的首尾主键区间删除,并 MUST 在语句中附带原始 `--where` 条件。`--bulk-delete` 依赖 `--purge`。日期分片模式下,区间删除仅在“分片列相对扫描键单调、无回填”的前提下安全,系统 SHALL 允许该组合并在启动时打印该前提警告。
#### Scenario: 默认 IN 列表删除
- **WHEN** 一个 chunk 读取到主键 1001..3000,且 `--where "created_at < '2026-01-01'"`
- **THEN** 系统生成 `DELETE ... WHERE id IN (1001,...,3000)`,不删除未被读取的行
#### Scenario: 区间删除附带回填条件
- **WHEN** 启用 `--bulk-delete`,chunk 首尾主键为 1001 与 3000
- **THEN** 系统生成 `DELETE ... WHERE id BETWEEN 1001 AND 3000 AND (<where>)`
#### Scenario: 日期模式启用区间删除
- **WHEN** `--shard-by date` 与 `--bulk-delete` 同时出现
- **THEN** 系统允许执行,并在启动时警告:该组合要求分片列永不相对扫描键回退,否则迟到或回填的行可能在归档前被删除
#### Scenario: 日期模式使用裸键区间
- **WHEN** 日期扫描器把 chunk 的 `LastKey` 改写为 `(分片列, 键...)` 的续跑游标
- **THEN** 区间删除仍使用 chunk 实际读取行的裸唯一键首尾,不把分片列拼入删除上界
#### Scenario: 区间删除保留最大自增行
- **WHEN** 启用 `--bulk-delete` 且 `--safe-auto-increment` 为默认值,chunk 区间包含源表当前 `MAX(pk)`
- **THEN** 区间删除语句额外排除该最大键,最大行不被删除,其余区间内行正常删除
@@ -0,0 +1,25 @@
## MODIFIED Requirements
### 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: 日期模式使用 bulk-delete
- **WHEN** 用户同时指定 `--shard-by date`、`--shard-column`、`--purge` 与 `--bulk-delete`
- **THEN** 系统通过启动校验,并在开始扫描前打印区间删除的安全前提警告
#### Scenario: 插入模式互斥
- **WHEN** 用户同时指定普通插入、`--insert-ignore` 与 `--replace` 中的多项
- **THEN** 系统在启动阶段报错
@@ -0,0 +1,26 @@
## 1. 校验与启动提示
- [x] 1.1 删除 `validate.go` 中“`--bulk-delete` 不能与 `--shard-by date` 同时使用”的校验
- [x] 1.2 更新 `cli_test.go`:日期模式 + `--bulk-delete` 现在应校验通过
- [x] 1.3 在 `App.execute` 中为日期模式 + `--bulk-delete` 增加前提警告
## 2. 区间删除
- [x] 2.1 `deleteRange` 的区间边界改为 `chunk.Keys` 首尾,避免使用被日期扫描器改写为复合游标的 `LastKey`
- [x] 2.2 `--safe-auto-increment` 生效时,区间 SQL 追加 `AND <key> <> ?` 排除当前最大键,不再退回 IN 列表
## 3. 测试
- [x] 3.1 单元测试:日期式 chunk 下单列主键生成裸键 `BETWEEN`
- [x] 3.2 单元测试:日期式 chunk 下复合键生成正确的元组区间与参数个数
- [x] 3.3 单元测试:`--safe-auto-increment` 下区间删除附带最大键排除条件
- [x] 3.4 集成测试 `TestIntegrationDateBulkDelete`:安全开关关闭时全删、默认开启时保留最大行
- [x] 3.5 `gofmt`、`go build ./...`、`go vet ./...`、`go test ./...` 通过
## 4. 文档与 OpenSpec
- [x] 4.1 更新 `openspec/specs/archive-core/spec.md` 的删除语义与日期模式场景
- [x] 4.2 更新 `openspec/specs/cli-contract/spec.md` 的参数依赖与互斥规则
- [x] 4.3 更新 README 安全说明
- [x] 4.4 运行 `openspec validate allow-date-bulk-delete --strict`
- [ ] 4.5 在具备 MySQL 的环境中运行集成测试并完成归档