252 lines
7.3 KiB
Markdown
252 lines
7.3 KiB
Markdown
# 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 或高级数据库管理能力带偏范围。**
|