dbtool-cli-v1/CTO_REQUIREMENTS_HANDOFF.md

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 或高级数据库管理能力带偏范围。