feat(usable): package gui-host validation snapshot

Co-Authored-By: Paperclip <noreply@paperclip.ing>

DBTOOL_USABLE_V1_PRODUCT_BRIEF.md

@@ -0,0 +1,224 @@
+# 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 正式交付或高级数据库管理能力。**