# 2026-03-27 `dbtool-usable-v1` 第一轮 issue package

日期：2026-03-27  
作者：CTO  
对应父 issue：`CMP-40`

## 设计原则

- 先有 parent issue，再有 narrow child issue。
- child issue 必须能被单个 owner 清晰完成。
- 不复制 `dbtool-cli-v1` 和 `dbtool-tui-v1` 既有执行链。
- 若只是发现风险但还没有具体缺陷，不创建“继续完善”式大包。

## 第一轮 child issues

### 1. PM child issue

- **标题**：同步 `dbtool-usable-v1` 的里程碑、依赖图与项目状态口径
- **Parent**：`CMP-41`
- **Owner**：Project Manager
- **Why now**：usable-v1 已经有独立 parent issue，但还没有自己的共享 tracking 文档和固定同步口径。
- **Scope**
  - 建 usable-v1 delivery tracking 文档
  - 标出当前关键路径、依赖关系、真实 blocker
  - 明确与 `dbtool-cli-v1` / `dbtool-tui-v1` 的项目边界
- **Acceptance**
  - 有共享 tracking 文档
  - 有固定状态同步规则
  - 没有无 owner 的 open 工作包

### 2. Backend child issue

- **标题**：冻结 `dbtool-usable-v1` 的 shared app / CLI 契约与错误边界
- **Parent**：`CMP-42`
- **Owner**：Senior Backend Engineer
- **Why now**：usable-v1 的 CLI 与 TUI 结论都依赖 `db-app` 成为唯一可信共享契约；当前需要把这一层正式收口成可被 QA 和前端引用的稳定边界。
- **Scope**
  - 盘点 `db-app` 对 `connect`、`inspect`、`query`、`export` 的结构化状态
  - 识别 CLI 侧是否还有 shared contract 漏洞或错误边界不一致
  - 输出 usable-v1 视角的 contract gap / blocker list
- **Non-goals**
  - 不重做 `CMP-34` 的 live wiring 方案
  - 不扩新的数据库能力
  - 不把 defect 修复和契约盘点混成大包
- **Acceptance**
  - 有 contract snapshot 或等价共享说明
  - 有 gap / blocker 清单
  - 新发现的后端缺陷被拆成单独 issue，而不是留在描述里

### 3. Frontend child issue A

- **标题**：定义并收口 `dbtool-tui` 的 TTY smoke 契约与启动限制
- **Parent**：`CMP-43`
- **Owner**：Senior Frontend Engineer
- **Why now**：当前 `dbtool-tui --help` 在非 TTY 场景直接失败，TUI 还没有 usable-v1 可接受的 smoke / 启动口径。
- **Scope**
  - 明确 TTY-required 启动路径
  - 明确非 TTY 场景的预期行为或错误提示
  - 补 TUI smoke runbook / README 对应说明
  - 为 QA / CI 提供最小可重复入口
- **Acceptance**
  - 有明确 smoke 契约
  - QA 能按文档复现最小启动验证
  - 当前限制被明确记录，不再靠口头说明

### 4. Frontend child issue B

- **标题**：完成 `dbtool-tui` 的 usable-v1 状态恢复与键盘一致性签收修正
- **Parent**：`CMP-43`
- **Owner**：Senior Frontend Engineer
- **Why now**：当前 TUI 已有真实工作台，但 usable-v1 还缺“失败后怎么恢复、空状态怎么看、键盘路径是否一致”的签收收口。
- **Dependencies**
  - 依赖 `CMP-35`、`CMP-36` 的 live integration 结果
- **Scope**
  - 收口 loading / empty / error / retry / export feedback 的连续性
  - 收口关键键位在不同视图下的一致性与可理解性
  - 仅做 usable-v1 签收所需的交互修正
- **Non-goals**
  - 不进入新功能扩张
  - 不新增 GUI 化需求
- **Acceptance**
  - QA 可按 checklist 复核关键恢复路径
  - 关键键盘路径无自相矛盾行为
  - 当前不支持的行为被明确标为限制

### 5. QA child issue

- **标题**：建立 `dbtool-usable-v1` 的统一验收矩阵、证据台账与发布门槛
- **Parent**：`CMP-44`
- **Owner**：QA Engineer
- **Why now**：当前 CLI、TUI、runtime、artifact、TTY smoke 分散在多份文档中，usable-v1 还缺一个统一的 evidence ledger。
- **Scope**
  - 建 usable-v1 acceptance matrix
  - 建已验证 / 未验证 / blocked / out-of-scope 台账
  - 建 release gate 结论模板
  - 区分环境 blocker 与产品 blocker
- **Acceptance**
  - 有统一矩阵
  - 有 blocker / risk 清单
  - 可对 usable-v1 给出 evidence-based 通过/不通过结论

## 当前不立即创建的 issue

- **CLI 新功能扩张 issue**：当前不需要；CLI 主功能已齐，重点是证据与一致性。
- **TUI 重做架构 issue**：当前不需要；现有问题更偏启动契约和签收收口。
- **招聘相关 issue**：当前不需要；还没有证据证明吞吐瓶颈来自 headcount。

## 推荐执行顺序

```text
PM tracking child
      ↓
Backend contract child
      ↓
Frontend TTY smoke child
      ↓
Frontend usability signoff child
      ↓
QA unified acceptance child
```

并行说明：

- PM tracking 可立即启动
- Backend contract child 可立即启动
- QA matrix 可先搭框，但最终结论依赖前置 child issue
- Frontend usability signoff child 受 `CMP-35` / `CMP-36` gating