paperclip/dbtool-cli-v1
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d5f69462b062dcb281ebcabc8d0d62a4239cb6a8
dbtool-cli-v1/plans/2026-03-27-dbtool-tui-v1-phase-2-scope.md
Paperclip CTO d5f69462b0
Some checks failed
release-smoke / macos-13 / x86_64-apple-darwin (push) Has been cancelled
Details
release-smoke / ubuntu-latest / x86_64-unknown-linux-gnu (push) Has been cancelled
Details
release-smoke / windows-latest / x86_64-pc-windows-msvc (push) Has been cancelled
Details
feat(usable): integrate current dbtool implementation snapshot 
Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-04-02 08:26:18 +00:00

4.0 KiB
Raw Blame History

2026-03-27 dbtool-tui-v1 Phase 2 Scope

日期：2026-03-27
作者：CTO
对应 issue：CMP-33

Goal

把 dbtool-tui-v1 从“可交互的 shell baseline”推进到“可接入真实 shared app 数据、可执行查询、可查看真实结果”的第二阶段准备，并拆出明确的 owner-backed issues。

Current Reality

  • 第一阶段已完成：apps/tui shell、主布局、焦点管理、基础键盘导航、Ready / Loading / Error 状态框架都已落地。
  • crates/db-app 已成为 CLI 可见主路径，说明 TUI 接真实数据时不应绕开 shared app 层。
  • 当前 TUI 仍主要消费占位数据；连接、schema、query、results 还没有形成 live workflow。

Phase 2 Scope

In Scope

  • 连接列表接入真实 shared app / session state
  • schema browser 接入真实 inspect 数据
  • query editor 进入可执行状态
  • results panel 进入真实结果展示状态
  • query / inspect / export 的 loading、success、empty、error 状态保持一致
  • 建立 TUI 第二阶段的 QA 验收矩阵与回归入口

Out Of Scope

  • 多连接并发在线工作区
  • 持久化 profile 管理中心
  • 多 query tab
  • SQL autocomplete / formatter / explain
  • 查询历史持久化
  • GUI 化扩展
  • 为了 TUI 重写一套数据库访问逻辑

Non-Goals

  • 不把 dbtool-tui-v1 变成桌面 GUI 替代品
  • 不把第二阶段误扩成“完整数据库客户端”
  • 不让 TUI 调用 CLI 二进制或解析 CLI 文本
  • 不把 CLI 发布收口问题混进 TUI live 集成 issue

Technical Dependencies

  1. crates/db-app 对外契约必须继续作为唯一业务入口
  2. TUI 需要稳定的结构化状态：
    • 连接激活中 / 成功 / 失败
    • inspect 加载中 / 成功 / 空 / 失败
    • query 执行中 / 成功 / 空结果 / 失败
    • export 成功 / 失败
  3. 当前同步数据库 I/O 不能阻塞 UI 主循环，因此阶段 2 需要明确 worker / channel 的集成方式
  4. QA 需要把 shell baseline 验收与 live integration 验收分层

Critical Path

Backend: shared app live integration contract
        ↓
Frontend: connections + schema browser live wiring
        ↓
Frontend: query + results + export live wiring
        ↓
QA: phase 2 acceptance + regression

并行说明：

  • PM 跟踪 issue 可以并行启动，用于维护阶段 2 节奏和依赖可见性
  • QA 文档可在后端 / 前端实现前先行搭框，但最终验收仍依赖 live wiring 完成

Team Boundaries

Senior Backend Engineer

  • 负责 shared app 层对 TUI 的 live integration 契约
  • 负责 worker-friendly 的请求 / 响应 / 错误状态边界
  • 负责回归测试，保证 CLI / TUI 共享行为不分叉

Senior Frontend Engineer

  • 负责 TUI 状态机、交互层和界面状态落地
  • 负责将真实连接 / inspect / query / result / export 状态接入工作台
  • 不引入 driver 依赖，不解析 CLI 文本

QA Engineer

  • 负责阶段 2 验收矩阵、回归清单和 live smoke 路径
  • 明确 shell baseline、live integration、非交互 smoke 的边界

Project Manager

  • 负责第二阶段依赖图、issue 状态和里程碑同步
  • 不负责技术方案，但负责防止状态漂移

Gating Conditions

  • backend issue 未冻结 live integration 契约前，frontend 不应直接绕过 shared app 做业务接线
  • query / results 接入前，connections 与 schema browser 的活动上下文必须先稳定
  • QA 必须单独保留 shell baseline 验收，不得被阶段 2 live 集成覆盖掉
  • 若 dbtool-tui 非 TTY smoke 契约未定义，QA / CI 启动路径应继续明确标记为限制，不得伪装成已解决

Acceptance Criteria

  • 第二阶段 issue 已按 owner 创建并指派
  • 每个 issue 都有范围、非目标、输入文档、交付物和验收标准
  • 阶段 2 不再通过口头说明推进
  • TUI live integration 明确复用 db-app，没有 CLI 文本解析旁路

Hiring Judgment

  • 当前不建议为第二阶段单独招聘
  • 真正瓶颈仍是 shared contract、验证路径和跨团队节奏，而不是纯编码人手