115 lines
4.0 KiB
Markdown
115 lines
4.0 KiB
Markdown
# 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、验证路径和跨团队节奏，而不是纯编码人手
|