# dbtool-cli-v1 CTO 需求交接说明

日期：2026-03-26  
作者：Product Manager

## 1. 目的

这份文档是当前阶段给 CTO 的执行型交接说明，用来回答三件事：

- 当前 demo 到底已经有什么
- V1 到底要交付什么、不交付什么
- CLI demo 应如何演进为更完整的产品流程，而不发生范围失控

如需查看完整背景，请同时参考：

- `PRODUCT_REQUIREMENTS.md`
- `DATABASE_SUPPORT_MATRIX.md`
- `apps/tui/README.md`
- `gui/desktop-foundation.md`

## 2. 当前 demo 能力盘点

截至 2026-03-26，仓库已经不是“空白项目”，而是一个可运行的跨数据库 demo：

- `apps/cli` 已提供 `connect`、`inspect`、`query`、`export` 四条主命令
- 当前支持 PostgreSQL、MySQL、SQLite
- 已支持 inline SQL 与 `.sql` 文件执行
- 已支持参数化查询
- 已支持导出 CSV / JSON
- 已支持 `--password-env` 注入密码，输出保持脱敏
- 仓库内已有 smoke / release / QA 相关 runbook 和检查清单

同时，仓库已经出现两类“未来产品面”基础，但它们**不改变 CLI V1 首发范围**：

- `crates/db-app`：共享应用编排层基础，说明产品对象已开始从 CLI 适配层抽离
- `apps/tui`：终端工作台 shell baseline，当前只验证布局、焦点、状态和键盘路径

结论：当前阶段不是“发散功能想法”，而是“冻结首版产品边界，稳住三库共同主流程，并给后续界面演进留下统一对象模型”。

## 3. 目标用户

### 主用户

具备终端操作能力、但不想在不同数据库工具之间来回切换的技术操作型用户：

- 后端工程师
- 数据工程师
- QA / 支持工程师

### 核心需求

用户需要一套一致的本地工具，在 PostgreSQL、MySQL、SQLite 之间稳定完成：

1. 验证连接
2. 查看结构
3. 执行 SQL
4. 导出结果

当前产品卖点是**一致性与低切换成本**，不是“替代所有数据库管理工具”。

## 4. 最重要的用户场景

### 场景 A：线上/测试环境数据排查

后端或支持工程师要确认某个异常是不是数据问题：

1. 指向 PostgreSQL 或 MySQL 目标
2. 验证连接成功
3. inspect schema / table / column
4. 执行针对性 SQL
5. 导出 JSON / CSV 作为问题证据

### 场景 B：本地 SQLite 文件验证

QA 拿到一个 SQLite 文件，需要快速确认内容：

1. 指向本地文件
2. 查看可用表
3. 运行验证 SQL
4. 导出记录用于测试结论

如果以上场景不顺，V1 就不算完成。

## 5. V1 核心流程

当前必须围绕这条产品主路径定义与验收：

`choose target -> connect -> inspect -> query -> export`

细化为：

1. 选择一个受支持的数据库目标
2. 明确知道是否连通成功
3. 定位 schema / table / column
4. 执行 inline SQL 或 `.sql` 文件
5. 读取结果或执行摘要
6. 在需要时导出为 CSV / JSON

这条流程是 CLI、未来 TUI、未来 GUI 共享的产品骨架。

## 6. 当前阶段范围

### In Scope

- 本地 CLI 首发面
- PostgreSQL / MySQL / SQLite 三库 Tier A 核心闭环
- 每次显式传入连接目标
- schema / table / column inspect
- inline SQL 与 `.sql` 文件执行
- 参数化查询
- 结果导出到 CSV / JSON
- 清晰、可行动、且不泄露秘密的错误反馈

### 当前阶段产品边界

- “完整支持”指核心闭环完整，不指 DBA 全家桶完整
- CLI 是当前正式交付面；TUI 和 GUI 只允许做后续演进准备
- 优先保证一致性、正确性和失败路径，而不是追求快捷功能堆叠

## 7. 非目标

以下内容明确不进入当前 V1：

- Desktop GUI 或 Web GUI 正式交付
- 新数据库扩容到 PostgreSQL / MySQL / SQLite 之外
- 用户可见的 saved profile 管理
- import
- migration / schema editing 工作流
- 事务控制 UX
- 存储过程 / function 管理 UX
- 权限 / 用户管理
- 备份 / 恢复
- 图表、dashboard、BI 视图
- AI 助手、自动补全、Explain 可视化、复杂 query history
- 多连接并发会话与团队协作空间

## 8. 验收标准

### 全局

- 三库必须共享同一套操作心智：`connect`、`inspect`、`query`、`export`
- 失败必须返回非成功退出并给出可行动提示
- 输出不得泄露密码
- 数据库差异必须有记录，但不能破坏主流程

### Connect

- 用户能提供目标类型与连接输入并得到明确成功/失败反馈
- 认证错误、网络错误、不可达目标、SQLite 路径错误要可区分
- 成功信息要能确认目标，但不泄露秘密

### Inspect

- 用户能先看到 schema 或等价顶层对象
- 用户能继续看到 table / view
- 用户能查看列名、类型、可空性以及主键信号
- 空库或空 scope 必须有清晰反馈，而不是堆栈信息

### Query

- 支持 inline SQL 与 `.sql` 文件
- 有结果集时可读地输出列与行
- 无结果集时给出执行摘要与影响行数
- SQL 错误、权限失败、执行失败要有明确反馈
- 空结果是成功，不是工具故障

### Export

- 仅承诺导出结果集到 CSV / JSON
- 导出路径必须显式
- 不允许静默覆盖已有文件
- 导出结果的行数必须和查询结果一致
- UTF-8 文本与多语言内容应保持稳定

## 9. CLI demo 如何向产品界面 / 产品流程演进

### 演进原则

- 不另造一套产品语言
- 不借界面开发偷偷扩 scope
- 先稳定共享对象，再增加交互层

### 建议演进顺序

#### 阶段 1：稳住 CLI 产品语义

目标：

- 固定 `connect / inspect / query / export` 的产品对象
- 固定空结果、失败、导出成功等标准状态
- 保证 README、帮助文案、QA 验收与实际行为一致

#### 阶段 2：以共享应用层承接跨界面复用

目标：

- 继续把 CLI adapter 中的编排职责收敛到 `crates/db-app`
- 让连接摘要、inspect payload、query result、export result 变成可复用对象
- 避免未来 TUI / GUI 重新定义结果结构

#### 阶段 3：TUI 作为流程承载层验证工作台形态

当前 TUI 只应承接：

- 单连接工作台
- schema browser
- query editor 容器
- results / inspector / status

它是产品流程验证层，不是 V1 CLI 发布阻塞项，也不是新功能扩张入口。

#### 阶段 4：未来桌面 GUI 复用同一对象模型

未来 GUI 应直接映射以下稳定对象：

- `connect` -> Connection Manager / Test Connection
- `inspect` -> Schema Browser / Object Inspector
- `query` -> Query Editor / Run Action
- `export` -> Export Flow / Export Feedback

GUI 的职责是提升承载方式，不是改写产品流程。

## 10. 对 CTO 的拆解要求

CTO 拆任务时，请围绕以下边界：

### 必须优先拆的

- 三库核心闭环质量收口
- 失败路径与错误可读性收口
- 文档 / 帮助 / QA 验收一致性
- `db-app` 共享对象与执行结果的稳定化

### 不应混入当前阶段的

- 新数据库接入
- 管理面能力扩张
- 为 GUI/TUI 预埋超出 V1 的高级功能
- 把原始 SQL 执行误扩成 migration / admin 产品

### CTO 仍可自主决定的实现项

- 命令命名与 flag 细节
- crate 边界与内部结构
- 连接配置落地方式
- 输出渲染方式
- 打包与发布实现

## 11. 一句话交付定义

`dbtool-cli-v1` 首发完成的标准是：**PostgreSQL、MySQL、SQLite 三库都能稳定完成 `connect -> inspect -> query -> export` 核心闭环，且没有被 GUI/TUI 或高级数据库管理能力带偏范围。**