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 正式交付或高级数据库管理能力。**