feat(usable): package gui-host validation snapshot

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

CTO_REQUIREMENTS_HANDOFF.md

@@ -0,0 +1,251 @@
+# 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 或高级数据库管理能力带偏范围。**