paperclip/dbtool-cli-v1
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
cmp-66-connection-management-integration
dbtool-cli-v1/plans/2026-03-26-cmp-20-dbtool-tui-v1-scope-and-boundaries.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

8.4 KiB
Raw Permalink Blame History

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 后续可扩展为：
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

工程级

  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 结果验证真实吞吐与协作瓶颈。