feat(usable): integrate current dbtool implementation snapshot

Co-Authored-By: Paperclip <noreply@paperclip.ing>

plans/2026-03-27-dbtool-tui-v1-phase-2-scope.md

@@ -0,0 +1,114 @@
+# 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、验证路径和跨团队节奏，而不是纯编码人手