dbtool-cli-v1/DBTOOL_USABLE_V1_PRODUCT_BRIEF.md

dbtool-usable-v1 Product Brief

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

1. 文档目的

这份文档用于冻结 dbtool-usable-v1 的当前产品边界，回答四个问题：

• 现有 demo 已经具备什么能力
• 当前版本的真实用户是谁
• “usable-v1” 在本阶段到底意味着什么
• CLI demo 应如何演进到更完整的产品界面与产品流程

配套控制文档：

• PRODUCT_REQUIREMENTS.md
• DATABASE_SUPPORT_MATRIX.md
• CTO_REQUIREMENTS_HANDOFF.md
• ACCEPTANCE_CHECKLIST.md

2. 当前 demo 已有能力

截至 2026-03-27，仓库已经具备以下用户可见基线：

• dbtool CLI 已提供 connect、inspect、query、export
• PostgreSQL、MySQL、SQLite 都已有核心 happy path
• 支持 inline SQL、.sql 文件、参数化查询
• 支持导出 CSV / JSON
• 支持 --password-env 注入密码，输出保持脱敏
• 仓库已包含 demo fixtures、smoke runbook、release runbook 和 QA 清单

同时，仓库内已出现两类后续产品演进基础，但它们不改变 usable-v1 当前交付面：

• crates/db-app：CLI / TUI 可复用的共享应用层
• apps/tui 与 gui/：工作台形态与信息架构验证资产

结论：当前不是“从零定义产品”，而是“把已存在 demo 收敛成明确可交付边界”。

3. 目标用户

主用户

第一阶段主用户是熟悉终端的技术操作型用户：

• 后端工程师
• 数据工程师
• QA 工程师
• 支持 / 运维排障人员

不优先服务的用户

• 需要图形化数据库管理台的非终端用户
• 需要完整 DBA 能力的高级数据库管理员
• 需要团队共享工作台、权限编排或云端协作的组织型用户

4. 真实使用场景

场景 A：跨库排障

用户需要在 PostgreSQL 或 MySQL 中快速确认某个异常是否由数据导致：

1. 指向目标数据库
2. 验证能否连通
3. 查看 schema / table / column
4. 执行验证 SQL
5. 导出结果作为问题证据

场景 B：SQLite 本地验证

用户拿到一个 SQLite 文件，需要快速核对数据内容：

1. 指向本地文件
2. 查看可用对象
3. 运行查询
4. 导出结果给 QA 或研发

场景 C：统一心智替代多工具切换

用户不想在 psql、MySQL 工具链和 SQLite 工具之间切换，希望用一套统一命令完成最常见操作。

5. 最重要的产品流程

usable-v1 的核心流程固定为：

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

如果这条路径不能在三种目标数据库上稳定成立，则当前阶段不能称为“真实可用”。

6. usable-v1 定义

本阶段“真实可用”不是指：

• 支持所有数据库
• 覆盖所有数据库管理能力
• 提供完整 GUI / IDE 体验

本阶段“真实可用”指：

• 用户能在本地 CLI 中稳定完成 connect -> inspect -> query -> export
• PostgreSQL、MySQL、SQLite 三库都达到同一核心闭环标准
• 失败路径可理解、可行动、且不会泄露密码
• README、帮助文案、QA 验收和实际行为一致

7. 当前阶段范围

In Scope

• 本地 CLI 作为正式交付面
• PostgreSQL / MySQL / SQLite 三库核心闭环
• ad hoc 连接输入
• schema / table / column inspect
• inline SQL 与 .sql 文件执行
• 参数化查询
• 结果导出到 CSV / JSON
• 清晰的执行结果与错误反馈

Non-Goals

• GUI 正式交付
• 新数据库扩容
• saved profile 用户工作流
• import、migration、schema editing
• transaction UX
• stored procedure / function 管理
• 权限 / 用户管理
• backup / restore
• dashboard、BI、AI 助手、复杂 IDE 能力
• 团队协作空间或云端同步

8. 数据库支持边界

当前数据库支持等级以 DATABASE_SUPPORT_MATRIX.md 为准，摘要如下：

数据库	当前等级	usable-v1 必须做到
PostgreSQL	Tier A	connect、inspect、query、export 核心闭环可用
MySQL	Tier A	connect、inspect、query、export 核心闭环可用
SQLite	Tier A	connect、inspect、query、export 核心闭环可用

补充边界：

• Tier A 只代表核心闭环完整，不代表数据库管理全功能
• PostgreSQL / MySQL / SQLite 都是当前承诺，不是“先做一库，其他顺带”
• SQL Server、MariaDB、DuckDB 仅保留为后续候选

9. usable-v1 验收标准

全局标准

• 三库共享同一套产品心智：connect、inspect、query、export
• 所有失败都必须返回非成功退出并给出可行动提示
• 所有输出都不得泄露密码或明文秘密
• 数据库差异必须被文档化，但不能破坏主流程

Connect

• 用户可显式提供目标数据库和连接输入
• 成功时能确认目标已连接
• 失败时能区分认证、网络、不可达目标和 SQLite 路径问题

Inspect

• 用户可查看 schema 或等价顶层对象
• 用户可继续查看 table / view
• 用户可查看列名、类型、可空性与主键信号
• 空 scope 需给出清晰反馈

Query

• 支持 inline SQL 与 .sql 文件
• 有结果集时输出可读表格或结构化结果
• 无结果集时提供执行摘要
• 空结果是成功，不是故障
• SQL / 权限 / 驱动错误要明确

Export

• 只承诺结果集导出到 CSV / JSON
• 导出路径必须显式
• 不允许静默覆盖已有文件
• 导出成功与失败都必须可判断

10. CLI demo 如何演进为产品界面 / 产品流程

阶段 1：稳定 CLI 产品语义

• 固定 connect / inspect / query / export 的产品对象
• 固定 ready / success / empty / error / exported 等用户可感知状态
• 保证文档、帮助和行为一致

阶段 2：共享应用层复用

• 继续把编排逻辑收敛到 crates/db-app
• 让连接、inspect、query、export 输出成为跨界面复用对象

阶段 3：TUI 验证工作台流程

• 用 TUI 验证单连接工作台、schema browser、query editor、results、status
• TUI 是流程承载层，不是当前 CLI 范围扩张入口

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

• GUI 只是在更强承载层上复用既有产品语义
• 不应借 GUI 开发把范围扩张到 migration、管理面或 BI

11. 给 CTO 的交接边界

CTO 拆任务时应优先围绕：

• 三库核心闭环质量收口
• 错误反馈和失败路径可读性
• README / 帮助 / QA 验收一致性
• 共享应用层对象稳定化

CTO 不应在当前阶段混入：

• 新数据库扩容
• 高级数据库管理能力
• 为未来 GUI/TUI 预埋超出本期的产品承诺

12. 一句话定义

dbtool-usable-v1 的完成标准是：PostgreSQL、MySQL、SQLite 三库都能以一致心智稳定跑通 connect -> inspect -> query -> export，且范围没有扩张到 GUI 正式交付或高级数据库管理能力。