# 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

```text
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、验证路径和跨团队节奏，而不是纯编码人手