# CMP-20 `dbtool-tui-v1` 范围、架构边界与执行建议

日期：2026-03-26  
作者：CTO

> 状态刷新（2026-03-27）：本文档保留为 `CMP-20` 的边界决策记录。当前共享工作区已落地 `crates/db-app` 与 `apps/tui` 基线；实时推进状态请以 `plans/2026-03-26-dbtool-tui-v1-delivery-tracking.md`、`backlog/dbtool-tui-v1-first-wave-issues.md` 和 `apps/tui/README.md` 为准。

## 1. 当前真实状态

- `dbtool-cli-v1` 已具备 PostgreSQL / MySQL / SQLite 的 `connect`、`inspect`、`query`、`export` 主链路。
- 当前产品验收范围仍然是 CLI；TUI 不应混入 `dbtool-cli-v1` 的首发完成定义。
- 当前仓库没有任何 TUI 入口或终端 UI 基线，也没有事件循环、焦点管理、键盘导航或终端渲染代码。
- 代码层面，`apps/cli/src/main.rs` 仍同时承担参数解析、用例编排和终端文本渲染；这意味着当前“core”还不足以被 TUI 直接复用。

## 2. CTO 结论

### 结论 A：应作为独立 project 推进

- 建议在 Paperclip 中把 TUI 作为独立 project：`dbtool-tui-v1`。
- 原因不是要分裂代码仓库，而是要分离目标、验收和 owner 节奏。
- 这样可以明确：
  - `dbtool-cli-v1` 继续对 CLI 首发负责
  - `dbtool-tui-v1` 单独承担终端交互层探索和交付
  - QA 不会把 TUI 误纳入当前 CLI 发布阻塞项

### 结论 B：必须复用现有 Rust core，而不是另写业务逻辑

- TUI 不应重新实现数据库连接、schema inspect、query 执行和 export 语义。
- TUI 应复用现有 `crates/db-core`、`crates/db-config`、`crates/db-drivers`，并新增一层共享应用编排层。
- 当前不建议为 TUI 单独建立另一套数据库访问栈，也不建议先走服务化 / 守护进程架构。

### 结论 C：先补“共享应用层”，再做 TUI 界面

- 当前最关键的前置项不是先画界面，而是把 `apps/cli` 中的用例编排抽出。
- 建议新增 `crates/db-app`（名称可调整），承载跨 CLI / TUI 共享的应用级用例与状态对象。
- 在这一步完成前，直接进入 TUI 编码会造成：
  - CLI / TUI 各自复制一套执行编排
  - 错误模型和状态文案分叉
  - QA 需要维护两套行为定义

## 3. 推荐边界：Core / CLI / TUI

| 层 | 职责 | 当前状态 | 建议 |
| --- | --- | --- | --- |
| `crates/db-core` | 领域对象、请求/响应模型、通用错误、稳定产品语义 | 已存在 | 保持数据库无关，不放任何 UI 代码 |
| `crates/db-config` | 连接 profile、脱敏摘要、配置抽象 | 已存在 | 继续作为共享配置边界 |
| `crates/db-drivers` | PostgreSQL / MySQL / SQLite 具体实现 | 已存在 | 继续承载数据库差异 |
| `crates/db-app` | connect / inspect / query / export 用例编排、会话摘要、可展示执行状态 | 缺失 | 应先补齐，作为 CLI / TUI 共享应用层 |
| `apps/cli` | flag 解析、stdout/stderr 渲染、退出码 | 已存在但偏重 | 逐步瘦身为“CLI adapter” |
| `apps/tui` | 终端布局、焦点切换、快捷键、交互状态机、结果浏览 | 尚未开始 | 作为新 app 单独推进 |

## 4. 能力归属建议

### 必须留在 shared core / app 层的能力

- 连接目标建模
- 连接测试
- schema / table / column inspect 结果结构
- query 请求、结果和错误分类
- export 请求与结果
- 空结果成功、执行失败、导出失败等标准状态语义
- 脱敏规则与用户可展示错误摘要

### 应属于 CLI adapter 的能力

- 参数解析
- `--help` / `--version`
- 文本表格与命令行输出文案
- shell 退出码
- `.sql` 文件路径解析和命令行参数到请求对象的映射

### 应属于 TUI adapter 的能力

- 多 panel 布局
- 焦点管理
- 键盘导航与快捷键
- query editor buffer
- schema tree 展开 / 折叠 / 搜索
- results table 翻页与滚动
- execution banner、status bar、bottom panel

## 5. 推荐技术方案

### 终端渲染与输入

- 推荐：`ratatui` + `crossterm`
- 原因：
  - Rust 生态成熟度足够
  - 易于实现 panel、table、status bar、快捷键
  - 不需要引入桌面壳或前端运行时

### 状态管理

- 推荐 reducer/event-driven 结构：
  - `AppState`
  - `Action`
  - `update(state, action) -> state`
- 原因：
  - 焦点切换、执行状态、结果切页都属于显式 UI 状态变化
  - 这种结构比把逻辑散落在 widget callback 里更适合 QA 和后续扩展

### 数据执行模型

- 当前数据库 I/O 仍为同步模型，因此 TUI 不应在 UI 线程直接执行 query。
- 第一阶段建议使用“UI 主循环 + 后台 worker 线程 + channel 回传结果”。
- 当前不建议为了 TUI 先重构为服务进程或强行引入复杂 async runtime。

### SQL 编辑器

- 第一阶段只需要最小可用多行编辑，不追求完整 IDE 能力。
- syntax highlight、自动补全、query history search 应继续 gated。

## 6. 与 CLI 共存规则

- 代码仓库可以继续共用当前仓库，不必为了 TUI 单独拆 repo。
- Cargo workspace 后续可扩展为：

```text
apps/
  cli/
  tui/
crates/
  db-core/
  db-config/
  db-drivers/
  db-app/
```

- CLI 命令形状继续保持兼容演进，不为了 TUI 去打断当前 CLI 用户心智。
- TUI 不能成为当前 CLI release gate；它应拥有独立 milestone、issue、QA matrix 和完成标准。

## 7. TUI 第一阶段最小范围

### In Scope

- 单连接工作台
- 左侧 schema browser
- 中央 query editor
- 底部 results / problems 区
- 基本执行状态反馈
- 调用共享 inspect / query / export 能力

### Out of Scope

- 多连接同时在线
- 复杂 connection manager
- 多 query tab
- query 历史持久化
- SQL autocomplete / explain / formatter
- dashboard、图表、AI 助手
- 桌面 GUI 与 TUI 同期并行实现

## 8. 必须先完成的 gated 前置项

1. `CMP-19` MySQL 中文输出问题收敛，否则 TUI 只会把现有结果渲染缺陷带入新界面。
2. 抽出共享应用层 `db-app`，避免 CLI / TUI 双份编排。
3. 固定结构化执行结果：
   - connect status
   - inspect tree payload
   - query success / empty / failure
   - export success / failure
4. 明确终端尺寸下限、resize 行为和长结果滚动策略。
5. 为 TUI 单独建立 QA smoke 与键盘导航验收，不复用 CLI 文本输出验收。

## 9. 第一轮角色职责

- 后端：
  - 抽出 `db-app`
  - 统一执行状态和错误对象
  - 保证 inspect / query / export 结果结构可被 TUI 直接消费
- 前端 / TUI 工程：
  - 建立 `apps/tui`
  - 落地 app shell、panel 布局、焦点管理和快捷键
  - 不改数据库语义，不复制驱动逻辑
- QA：
  - 编写 TUI 最小 smoke
  - 覆盖 terminal resize、键盘导航、空结果、错误反馈、导出提示
- CTO：
  - 维护 CLI / TUI 边界
  - 防止 scope creep
  - 评审 shared app 层是否足够稳定再放行 TUI 编码

## 10. 风险与依赖

### P0

- 当前 shared core 仍偏“领域模型 + driver 入口”，尚未形成真正的应用层复用边界。
- 如果跳过 `db-app`，TUI 项目会立即复制 CLI orchestration。

### P1

- 终端 UI 对长结果集、键盘交互、窗口缩放更敏感，QA 复杂度高于 CLI。
- 当前代码是同步数据库 I/O，若线程边界设计不清，TUI 容易出现卡顿或状态错乱。

### P2

- `CMP-9` 已定义未来 desktop GUI 基线；若 TUI 和 GUI 同时推进，团队容易把“终端工作台”和“桌面工作台”混为一谈。

## 11. 首批 issue 拆分建议

### 项目级

1. 新建 project：`dbtool-tui-v1`
2. 立项说明引用本文件与 [CMP-9](/CMP/issues/CMP-9)

### 工程级

1. **Backend**：抽出 `crates/db-app`，承接 connect / inspect / query / export 共享编排
2. **Backend**：稳定结构化执行状态与错误对象，补回归测试
3. **Frontend / TUI**：初始化 `apps/tui`，建立 `ratatui` shell、layout 和 focus model
4. **Frontend / TUI**：接入 schema browser + query editor 最小工作台
5. **Frontend / TUI**：接入 query 执行、result table、error banner、export trigger
6. **QA**：建立 TUI smoke runbook 与最小验收矩阵

## 12. 管理判断

- 现在可以为 TUI 做项目级立项准备，但不建议立刻把它推到与 CLI 同优先级。
- 更合理的节奏是：
  1. 先完成 CLI 当前质量收口
  2. 再抽 shared app 层
  3. 然后启动 `dbtool-tui-v1` 的最小工作台实现
- 当前不建议因 TUI 方向立即扩编；先用第一轮 shared app + shell 结果验证真实吞吐与协作瓶颈。