docs: add inbox markdown test plans

2026-03-19 10:54:39 +08:00
parent dab0506c5a
commit 9beb7e93eb
18 changed files with 2091 additions and 135 deletions
@@ -0,0 +1,112 @@
+# Inbox `claim` Test Plan
+
+## Scope
+
+This document covers lease acquisition via `inbox claim`.
+
+Shared conventions live in [../_shared/README.md](../_shared/README.md).
+
+## case: claim-acquires-thread-lease
+
+### 用例意义
+
+验证 `claim` 可以把 `pending` 线程切换到 `claimed`，并生成租约事件消息。
+
+### 前置条件
+
+- 已存在一个 `pending` 线程 `THREAD_ID`
+
+### 输入
+
+```bash
+inbox --db TMPDIR/coord.db --json claim --agent worker-a --thread THREAD_ID --lease-seconds 300
+```
+
+### 预期输出
+
+- 命令退出码为 `0`
+- `thread.status == "claimed"`
+- `thread.assigned_to == "worker-a"`
+- `message.kind == "event"`
+- `message.summary == "thread claimed"`
+
+### 断言结论
+
+- `claim` 同时更新线程状态与活跃租约
+- 成功领取会附带一条事件消息，而不是静默改状态
+
+## case: claim-rejects-when-thread-missing
+
+### 用例意义
+
+验证 `claim` 对不存在的线程返回稳定的 not-found 错误契约。
+
+### 前置条件
+
+- 空数据库已完成 `init`
+
+### 输入
+
+```bash
+inbox --db TMPDIR/coord.db --json claim --agent worker-z --thread thr_missing
+```
+
+### 预期输出
+
+- 退出码为 `40`
+- JSON 错误码为 `not_found`
+
+### 断言结论
+
+- 缺失线程会被明确区分为引用错误，而不是 lease 冲突
+
+## case: claim-rejects-when-thread-already-claimed
+
+### 用例意义
+
+验证同一线程在已有活跃租约时，其他执行者无法重复领取。
+
+### 前置条件
+
+- `worker-z` 已成功 `claim` 线程 `THREAD_ID`
+
+### 输入
+
+```bash
+inbox --db TMPDIR/coord.db --json claim --agent worker-y --thread THREAD_ID
+```
+
+### 预期输出
+
+- 退出码为 `20`
+- JSON 错误码为 `lease_conflict`
+
+### 断言结论
+
+- 活跃 lease 是 `claim` 的排他条件
+
+## case: claim-records-requested-lease-duration
+
+### 用例意义
+
+验证 `claim --lease-seconds` 的请求值会进入事件消息 payload，便于后续审计。
+
+### 前置条件
+
+- 已存在一个 `pending` 线程 `THREAD_ID`
+
+### 输入
+
+```bash
+inbox --db TMPDIR/coord.db --json claim --agent worker-a --thread THREAD_ID --lease-seconds 300
+```
+
+### 预期输出
+
+- 命令退出码为 `0`
+- `message.payload_json.lease_seconds == 300`
+- `message.payload_json.lease_token` 存在
+
+### 断言结论
+
+- 请求的租约时长不是仅用于内部计算，也会被持久化到事件消息中