# 2026-04-02 CMP-66 TUI 连接管理与交互式配置拆解方案

日期：2026-04-02  
作者：CTO  
对应 issue：`CMP-66`

## 当前真实状态

- `apps/tui/src/main.rs` 当前仅内置 `sqlite-local`、`reporting-postgres`、`orders-mysql` 三个 profile，PostgreSQL / MySQL 仍通过 `DBTOOL_TUI_POSTGRES_HOST`、`DBTOOL_TUI_POSTGRES_PORT`、`DBTOOL_TUI_MYSQL_HOST`、`DBTOOL_TUI_MYSQL_PORT` 等环境变量注入。
- `apps/tui/README.md` 当前仍明确写着“不能自定义输入数据库连接”，说明仓库事实与本次需求之间存在清晰 gap。
- `crates/db-config/src/lib.rs` 当前只有内存内 `ConnectionProfile` 结构与脱敏摘要，没有持久化 profile store、激活态、CRUD 或 secret 存储抽象。
- `crates/db-app/src/lib.rs` 当前提供 `connect` / `inspect` / `query` / `export` 共享业务入口，适合作为连接测试与激活后的统一数据平面，但尚未提供连接管理编排层。

## CTO 边界判断

- 这项工作应继续以 `db-app` 为唯一业务入口，TUI 不能直接绕过 shared app / driver 层。
- usable-v1 第一轮不引入云同步、多用户或 GUI 扩张。
- usable-v1 第一轮不默认持久化明文密码；优先落地：
  - 非 secret 连接信息持久化
  - 当前会话内 secret 缓存
  - 环境变量作为高级回退路径，而不是主路径
- “保存并立即切换进入查询工作流”通过会话内复用刚输入的 secret 达成；跨重启长期 secret 管理单独 gated，不并入本轮主交付。

## 第一轮拆解

### Backend / Shared Contract

目标：

- 定义统一连接 profile 持久化模型
- 定义 active profile 与测试连接契约
- 定义 secret 的 session-only 策略与脱敏边界

范围：

- `db-config` 补 profile store / 序列化模型 / 激活态
- `db-app` 补连接测试、加载、保存、切换所需共享编排
- 保证 CLI / TUI 共用同一连接模型，不分叉

验收：

- SQLite / PostgreSQL / MySQL 使用同一 profile 模型
- secret 不进入日志、summary、文档示例或非受控持久化路径
- TUI 可通过共享层完成 test/save/activate 所需后端动作

### Frontend / TUI Workflow

目标：

- 在 TUI 内提供可键盘完成的连接管理主路径
- 将“内置 demo profile”升级为“用户可新增/编辑/删除/切换的 profile 列表”

范围：

- 连接列表与当前连接展示
- 分步式新增 / 编辑流程
- 删除确认
- 测试连接、保存并激活
- 错误内联修正与状态反馈

验收：

- 用户无需预先 `export` 环境变量即可完成 happy path
- 新连接测试通过后可保存并立即进入查询工作流
- 键盘路径一致、可文档化、可在真实 TTY 复核

### QA / 验收与文档

目标：

- 为新连接管理能力建立真实 TTY 验收路径与文档闭环

范围：

- 更新 `apps/tui/README.md`、`TUI_ACCEPTANCE_CHECKLIST.md`、`TUI_SMOKE_RUNBOOK.md`、相关 usable 文档
- 补 SQLite / PostgreSQL / MySQL 三类连接配置的 happy path / failure path 验收步骤
- 明确哪些为 runner 内验证，哪些仍需 GUI host 复核

验收：

- QA 可按文档从零配置连接并复核新增、编辑、删除、测试、切换
- 文档不再把环境变量准备描述为普通用户主路径
- blocker、partial 与 pass 口径保持一致

## 依赖顺序

1. Backend 先冻结 profile store、active profile、session secret contract。
2. Frontend 再接入 TUI 向导式配置、列表管理与错误修正。
3. QA 最后按真实 TTY 路径补 smoke、回归、验收文档。

## 组织与节奏

- 本轮不建议招聘；当前瓶颈是连接模型与 secret 边界，不是人手。
- PM 不新增独立子单，直接在既有 `CMP-41` 里吸收里程碑与依赖更新。
- `CMP-66` 作为此次连接管理拆解入口，交付拆成 backend / frontend / QA 三张 owner-backed 子单执行。