dbtool-cli-v1/backlog/2026-03-27-dbtool-usable-v1-first-wave-issues.md

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。

推荐执行顺序

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