202 lines
8.8 KiB
Markdown
202 lines
8.8 KiB
Markdown
# CMP-25 `dbtool-tui-v1` / CLI core 架构边界与模块拆分
|
||
|
||
日期：2026-03-26
|
||
作者：CTO
|
||
对应 issue：`CMP-25`
|
||
|
||
## 1. 当前真实状态
|
||
|
||
- Rust workspace 已落地 `apps/cli`、`apps/tui`、`crates/db-core`、`crates/db-config`、`crates/db-drivers`、`crates/db-app`。
|
||
- `apps/tui` 已有可运行 shell：六区布局、焦点切换、基础键盘导航、`Ready/Loading/Error` 状态框架均已落地。
|
||
- `crates/db-app` 已存在，且已提供 `connect` / `inspect` / `query` / `export` 的结构化响应与统一错误映射。
|
||
- 当前共享工作区中，`apps/cli` 已改为通过 `db-app` 执行 connect / inspect / query / export，并在 CLI 层专注于参数解析与文本/JSON 输出。
|
||
- 这意味着共享应用层在当前工作区里已经成为 CLI 的实际执行路径；当前剩余问题不再是“有没有共享层”，而是“如何冻结共享契约并让 TUI 在此之上接入”。
|
||
|
||
## 2. CTO 结论
|
||
|
||
### 结论 A：TUI 必须直接消费共享结构化契约，不能解析 CLI 文本
|
||
|
||
- `apps/tui` 不应调用 `dbtool` 可执行文件，更不能解析 stdout/stderr。
|
||
- TUI 应直接链接 `crates/db-app`，消费结构化 `Response` / `AppError`。
|
||
- CLI 文本输出仍然存在，但只作为 CLI adapter 的人类可读呈现层。
|
||
|
||
### 结论 B：`db-app` 是 CLI 与 TUI 之间唯一允许共享的用例编排层
|
||
|
||
- `db-core` 负责领域模型、请求/响应对象、输入校验。
|
||
- `db-drivers` 负责 PostgreSQL / MySQL / SQLite 的具体 I/O 和差异处理。
|
||
- `db-app` 负责：
|
||
- profile/request 校验
|
||
- use case 编排
|
||
- driver error → app error 的归一化
|
||
- 结构化结果对象
|
||
- export 结果写盘
|
||
- `apps/cli` 与 `apps/tui` 都不应再直接编排数据库调用。
|
||
|
||
### 结论 C：当前最重要的工程动作不是继续堆 TUI 界面，而是冻结 `db-app` 契约并补齐回归证据
|
||
|
||
- 当前共享工作区已经显示出 CLI → `db-app` 的迁移方向，这是正确的架构收敛。
|
||
- 但 `CMP-31` 在 Paperclip 里仍未正式关闭，也还没有在本 heartbeat 中补到本地 `cargo` 级验证证据。
|
||
- 因此 `CMP-31` 仍应被视为 TUI 集成前的 P0 收尾项：冻结结构化契约、补测试、让 QA 能据此建立回归基线。
|
||
|
||
## 3. 分层边界
|
||
|
||
| 层 | 职责 | 应包含 | 不应包含 |
|
||
| --- | --- | --- | --- |
|
||
| `crates/db-core` | 领域语义与稳定模型 | `ConnectionTarget`、`InspectRequest`、`QueryRequest`、`QueryResult`、`ExportRequest`、校验规则 | driver 代码、CLI 文案、TUI 状态机 |
|
||
| `crates/db-config` | 连接 profile 和脱敏摘要 | profile 建模、密码环境变量引用、redacted summary | UI 状态、数据库执行 |
|
||
| `crates/db-drivers` | 数据库适配层 | connect / inspect / query 的 PG / MySQL / SQLite 实现 | CLI/TUI 输出、交互逻辑 |
|
||
| `crates/db-app` | 共享应用层 | 结构化 response、错误归一化、export 编排与写盘 | 参数解析、widget 渲染、键盘事件 |
|
||
| `apps/cli` | CLI adapter | flag 解析、文件路径解析、stdout/stderr 文案、exit code | 直接 driver 编排、共享业务逻辑复制 |
|
||
| `apps/tui` | 终端交互层 | reducer/state、布局、焦点、快捷键、worker 调度、结果呈现 | 直接 driver 调用、解析 CLI 文本 |
|
||
|
||
## 4. 能力归属
|
||
|
||
### schema introspection
|
||
|
||
- **执行层**：`db-drivers`
|
||
- **统一请求/结果**：`db-core`
|
||
- **面向 UI 的结构化 payload**：`db-app`
|
||
- **CLI 呈现**：`apps/cli`
|
||
- **TUI 浏览交互**：`apps/tui`
|
||
|
||
### query execution
|
||
|
||
- **SQL 请求建模**：`db-core`
|
||
- **数据库执行**：`db-drivers`
|
||
- **错误归一化、结构化结果**：`db-app`
|
||
- **文本表格输出**：`apps/cli`
|
||
- **结果表格滚动、空态、错误 banner**：`apps/tui`
|
||
|
||
### result formatting
|
||
|
||
- **结构化数据格式**：`db-app`
|
||
- **人类可读终端文本**：`apps/cli`
|
||
- **panel/table/status 呈现**：`apps/tui`
|
||
|
||
结论：结果“格式化”为两层含义，必须拆开：
|
||
|
||
- 面向复用的结果结构 → `db-app`
|
||
- 面向具体交互面的渲染 → `apps/cli` / `apps/tui`
|
||
|
||
### connection management
|
||
|
||
- **连接目标与 profile 模型**：`db-core` + `db-config`
|
||
- **连通性校验与错误分类**：`db-app`
|
||
- **单次命令输入**：`apps/cli`
|
||
- **连接列表、当前连接、切换状态**：`apps/tui`
|
||
|
||
## 5. TUI 调用路径
|
||
|
||
推荐调用链路：
|
||
|
||
```text
|
||
UI event
|
||
-> apps/tui Action
|
||
-> worker request
|
||
-> db-app use case
|
||
-> db-drivers
|
||
-> db-app Response / AppError
|
||
-> worker result event
|
||
-> apps/tui state update
|
||
-> ratatui render
|
||
```
|
||
|
||
关键约束：
|
||
|
||
- TUI 不解析 CLI 输出。
|
||
- TUI 不直接依赖 `db_drivers::DriverRegistry`。
|
||
- TUI 主循环不直接执行阻塞数据库 I/O。
|
||
- 第一阶段使用“UI 主线程 + worker 线程 + channel”即可，不需要为了 TUI 先服务化。
|
||
|
||
## 6. 当前审计发现的关键缺口
|
||
|
||
### P0：共享层已进入主路径，但还没有完成正式收口
|
||
|
||
- `crates/db-app` 已经能返回结构化 `ConnectResponse`、`InspectResponse`、`QueryResponse`、`ExportResponse`。
|
||
- 当前共享工作区里的 `apps/cli` 已通过 `db-app` 调用核心用例，这说明架构方向已经正确。
|
||
- 但对应的工程 issue `CMP-31` 仍在进行中，因此当前仍需要以 issue 收口、回归测试和 QA 可验证文档来固定这条共享路径。
|
||
|
||
### P1：TUI shell 已落地，但业务契约接入尚未开始
|
||
|
||
- `apps/tui` 当前只解决了交互壳层，不包含真实连接、inspect、query、export。
|
||
- 这符合 `CMP-27` 范围，但也意味着后续 issue 必须严格走共享契约接入，不能从 shell 直接摸到 driver。
|
||
|
||
### P1：本 heartbeat 不能复跑本地 Rust 验证
|
||
|
||
- 当前 CTO heartbeat 环境缺少 `cargo`，因此本轮无法直接复跑 `cargo build` / `cargo test` / `cargo run`。
|
||
- 仓库中仍保留 `.github/workflows/release-smoke.yml` 与 `dist/` 产物，说明构建与发布链路定义仍在，但本轮只能做静态审计，不能补新执行证据。
|
||
|
||
## 7. 哪些契约必须先稳定
|
||
|
||
在继续推进 `CMP-28` / `CMP-29` / `CMP-30` 前，必须冻结以下共享契约：
|
||
|
||
1. `db-app` 的 `AppErrorKind` 与错误消息分层
|
||
2. `InspectResponse` / `InspectPayload` 的结构和空态语义
|
||
3. `QueryResponse` 的结果集结构、空结果集语义、rows affected 语义
|
||
4. `ExportResponse` 的成功 / 覆盖 / 路径不存在等失败语义
|
||
5. CLI 迁移到 `db-app` 后的回归测试，证明共享层不是只给 TUI 准备的旁路代码
|
||
|
||
## 8. 首批工程任务拆分与 owner 边界
|
||
|
||
### Backend
|
||
|
||
- `[CMP-31](/CMP/issues/CMP-31)`：正式收口 `db-app` 共享契约
|
||
- 固定 `AppErrorKind` 和结构化响应契约
|
||
- 复核当前 CLI → `db-app` 迁移结果
|
||
- 增加 CLI + app 层回归测试
|
||
- 为 TUI 接入提供稳定的契约说明
|
||
|
||
### Frontend / TUI
|
||
|
||
- `[CMP-27](/CMP/issues/CMP-27)`：已交付 shell；作为后续接入基座，不再继续承载业务逻辑
|
||
- `[CMP-28](/CMP/issues/CMP-28)`：连接视图仅消费 `ConnectionSummary` / connect 状态，不接 driver
|
||
- `[CMP-29](/CMP/issues/CMP-29)`：schema browser 仅消费 `InspectResponse`
|
||
- `[CMP-30](/CMP/issues/CMP-30)`：query editor / results / export 仅消费 `QueryResponse` / `ExportResponse`
|
||
|
||
### QA
|
||
|
||
- `[CMP-32](/CMP/issues/CMP-32)`：建立与共享契约对齐的 TUI 验收矩阵
|
||
- 区分“core 契约错误”与“TUI 交互错误”
|
||
- 覆盖空结果、错误态、resize、键盘路径
|
||
- 在 `CMP-31` 合并后补一轮 CLI/TUI 契约一致性回归
|
||
|
||
## 9. 推荐执行顺序
|
||
|
||
1. `CMP-31` 先正式收口共享应用层契约
|
||
2. `CMP-32` 同步固化契约导向的验收矩阵
|
||
3. `CMP-28` 接连接视图
|
||
4. `CMP-29` 接 schema browser
|
||
5. `CMP-30` 最后接 query / results / export
|
||
|
||
说明：
|
||
|
||
- `CMP-27` 已够用，不应继续膨胀为“顺手把业务也做了”。
|
||
- `CMP-28` / `CMP-29` / `CMP-30` 可以在 shell 基座上并行设计，但实际合入顺序仍应受 `CMP-31` 约束。
|
||
|
||
## 10. 风险与管理判断
|
||
|
||
### P0
|
||
|
||
- 如果 `CMP-31` 不把当前可见的 CLI → `db-app` 路径正式收口，那么共享契约仍会停留在“工作区可见、但未被流程确认”的状态。
|
||
|
||
### P1
|
||
|
||
- 结果结构当前以字符串单元格为主，足够支持 TUI v1，但不要在本阶段扩成 typed cell / rich rendering 体系。
|
||
|
||
### P1
|
||
|
||
- `CMP-19` MySQL 中文输出问题未最终关闭前，TUI 结果区应避免过早做“输出显示质量已稳定”的假设。
|
||
|
||
### P2
|
||
|
||
- 当前不是招聘问题。真实瓶颈是共享契约收敛与 issue 节奏，而不是缺少更多实现人手。
|
||
|
||
## 11. CTO 结论
|
||
|
||
- TUI 可以继续推进，但必须建立在 `db-app` 成为唯一共享应用层的前提上。
|
||
- 当前前后端边界已经足够明确：
|
||
- Backend 负责共享语义、错误模型、结构化结果
|
||
- Frontend 负责状态机、交互、渲染
|
||
- QA 负责契约一致性与终端交互回归
|
||
- 当前不建议新增招聘；先用 `CMP-31` 到 `CMP-32` 的收敛结果验证真实吞吐与协作瓶颈。
|