# 2026-03-27 `dbtool-usable-v1` 技术边界、阶段拆分与执行方案

日期：2026-03-27  
作者：CTO  
对应 issue：`CMP-40`

## 1. 当前真实落地情况

### CLI

- 当前仓库不是空白项目；`apps/cli` 已稳定提供 `connect`、`inspect`、`query`、`export` 四条主命令。
- `README.md`、`PRODUCT_REQUIREMENTS.md`、`DATABASE_SUPPORT_MATRIX.md`、`SMOKE_RUNBOOK.md`、`RELEASE_RUNBOOK.md` 已共同定义首版产品边界、数据库支持等级和发布路径。
- 2026-03-27 当前 heartbeat 已再次在本机复核：
  - `scripts/release/smoke-binary.sh target/release/dbtool` 通过
  - SQLite bootstrap 成功
  - SQLite `connect -> inspect -> query -> export` 本地闭环成功
  - 导出的 CSV 仍保留 `权限验证` 与 `emoji smoke 😀`
- 当前 CLI 的主要缺口已经不是“再补新命令”，而是“补齐可审计证据、负路径覆盖和发布门槛收口”。

### Shared App / Core

- 当前共享工程分层已经存在：
  - `crates/db-core`：领域对象、输入校验、错误模型
  - `crates/db-config`：连接 profile 与脱敏摘要
  - `crates/db-drivers`：PostgreSQL / MySQL / SQLite 具体实现
  - `crates/db-app`：CLI / TUI 共享应用编排层
- `apps/cli` 当前已走 `db-app` 主路径，不再是直接拼接驱动调用的早期状态。
- `db-app` 已提供 `AppOperation`、`OperationState`、`AppEvent<T>`，这已经是 usable-v1 应继续冻结和复用的共享业务契约。

### TUI

- `apps/tui` 已不是纯静态草图；当前工作台、焦点管理、键盘导航、`sqlite-local` 真实 connect / inspect / query / export 路径都已存在。
- 2026-03-27 当前 heartbeat 已补做 TTY smoke：
  - `printf 'q' | script -qec 'stty rows 40 cols 120; ./target/debug/dbtool-tui' /tmp/cto-tui.log`
  - 退出码为 `0`
  - 日志能看到六区布局、`Loading`、`Execution Idle` 和 `sqlite-local` 工作台
- 当前已知限制仍成立：
  - `./target/debug/dbtool-tui --help` 在非 TTY 场景直接报 `No such device or address`
  - TUI 仍缺 CI / release artifact / 非交互 smoke 契约
  - TUI 的 usable-v1 风险更偏向“启动契约、状态恢复、可验收性”，而不是“再扩命令面”

## 2. `dbtool-usable-v1` 的项目边界

### 本项目负责

- 把现有 CLI / shared app / TUI 资产从“可演示”推进到“可审计、可验收、可给出通过/不通过结论”
- 冻结 usable-v1 的共享技术边界，避免 CLI / TUI 分叉
- 识别真实 blocker，并把 blocker 拆成 owner-backed issue
- 建立 usable-v1 的第一轮验收矩阵、证据台账和发布门槛

### 本项目不负责

- 重开 `dbtool-cli-v1` 的首版范围定义
- 重新做 `dbtool-tui-v1` Phase 2 的 live wiring 规划
- 新增 Tier C 产品能力
- 把 GUI、profile 管理、migration、导入、权限管理混入当前承诺

## 3. 与旧项目的边界

### 与 `dbtool-cli-v1` 的边界

- `dbtool-cli-v1` 已完成“首版主功能与发布脚手架基线”的历史任务。
- `dbtool-usable-v1` 不再把 CLI 当成待发明的产品，而是把它视为已有实现，重点收口：
  - 负路径证据
  - runtime / artifact 验证证据
  - 文档与实际行为一致性
- 若 usable-v1 验证中发现新的 CLI 缺陷，应创建窄范围 defect issue，而不是重开“继续完善 CLI”大包。

### 与 `dbtool-tui-v1` 的边界

- `dbtool-tui-v1` 继续拥有 TUI Phase 2 的核心实现链：shared app live contract、真实连接/schema/query/results/export 接线。
- `dbtool-usable-v1` 不复制 `CMP-34` 到 `CMP-38` 的实现责任。
- `dbtool-usable-v1` 只负责：
  - 把 usable-v1 对 TUI 的质量门槛定义清楚
  - 为 TUI 的 smoke / 可用性 / 验收缺口创建 narrow issues
  - 用证据判断 TUI 哪些能力已可纳入 usable-v1，哪些仍 gated

## 4. core / CLI / TUI 的技术边界

### Core

- `db-core` 负责稳定产品对象：
  - `ConnectionTarget`
  - `InspectRequest`
  - `QueryRequest`
  - `ExportRequest`
  - 标准错误模型与标准化结果对象
- `db-drivers` 负责数据库差异，不向上暴露数据库原生 API。
- `db-config` 负责 profile 与秘密脱敏，不承载终端输出逻辑。

### Shared App

- `db-app` 是 usable-v1 唯一允许的应用编排入口。
- `db-app` 负责：
  - 将 connect / inspect / query / export 组织成共享操作
  - 暴露 `running / success / empty / error` 的稳定状态模型
  - 对 CLI 与 TUI 提供统一结构化输出
- 若新能力无法自然落在 `db-app` 上，就说明当前边界可能被破坏，必须先评审再实现。

### CLI

- `apps/cli` 只负责命令行参数解析、文本/JSON 输出和退出码。
- CLI 不应重新定义 shared app 语义。
- CLI 文本输出不是 TUI 的数据源，也不是其他界面的契约来源。

### TUI

- `apps/tui` 只负责交互工作台、状态管理、键盘工作流和可视反馈。
- TUI 必须通过 `db-app` 接入业务能力。
- TUI 不应：
  - 直接依赖 `db-drivers`
  - 调用 CLI 二进制
  - 解析 CLI 文本输出来取数

## 5. 当前阶段技术优先级

### Priority 0：收口 usable-v1 的真实验证边界

- 明确哪些结论已经有本机或宿主机证据
- 明确哪些仍只是代码可见或文档声明
- 明确环境 blocker 与产品 blocker 的边界

### Priority 1：冻结 shared contract

- usable-v1 的 CLI 与 TUI 都必须继续围绕 `db-app`
- 任何绕过 `db-app` 的路径都应视为架构偏航

### Priority 2：把 TUI 从“可见”推进到“可验收”

- 当前不是再发散功能，而是补：
  - 启动契约
  - smoke 路径
  - 键盘与状态恢复一致性
  - QA 可复现路径

### Priority 3：把发布判断从“感觉差不多”变成 evidence-based

- CLI 侧需要更清晰的 release gate
- TUI 侧需要明确哪些仍 gated，不允许被口头宣布为 ready

## 6. blocker、依赖与阶段拆分

## Phase A：usable-v1 事实冻结

目标：

- 冻结当前 repo 与运行链路的真实状态
- 明确 usable-v1 范围与旧项目边界

当前状态：

- 本文档已完成

### 当前 blocker

- CTO 本地环境无 `cargo`、无 `docker`
- 因此无法在当前 heartbeat 关闭源码重建与 Docker runtime 证据

## Phase B：owner-backed issue 链启动

目标：

- 把 usable-v1 拆成 backend / frontend / QA / PM 的明确 issue
- 不再允许“一个人自己再想想”的模糊推进

输出：

- 父 issue：`CMP-41`、`CMP-42`、`CMP-43`、`CMP-44`
- 子 issue：见 `backlog/2026-03-27-dbtool-usable-v1-first-wave-issues.md`

## Phase C：验证与签收

目标：

- 形成 usable-v1 的 evidence-based 通过/不通过结论

依赖：

- CLI release/runtime 证据补齐
- TUI smoke / 启动契约明确
- QA 矩阵完成并区分已验证、未验证、blocked

## 7. 各角色第一轮职责

### Backend

- 审计 usable-v1 当前 shared contract 是否足以支撑 CLI / TUI 一致验收
- 明确 `db-app` 的结果、错误和状态边界
- 对真正的稳定性缺陷单独成单，不混进“继续完善”大包

### Frontend

- 收口 TUI 的启动契约、状态恢复和键盘一致性
- 不重写 shared app，不走 CLI 文本旁路
- 对 usable-v1 只承诺可验收的交互路径，不口头扩大范围

### QA

- 建 usable-v1 的统一验收矩阵与证据台账
- 清楚标识：
  - 已执行通过
  - 未执行
  - 环境 blocker
  - 产品 blocker

### Project Manager

- 将 usable-v1 的里程碑、关键路径、open issue 状态同步到共享项目跟踪
- 保持旧项目和新项目的边界清晰，避免重复汇报与重复拆单

## 8. CTO 的当前管理判断

- 当前不建议招聘。
- 真正瓶颈仍是 shared contract、验收证据和跨项目边界治理，而不是工程人手数量。
- 当前最重要的不是“做更多功能”，而是“让已经存在的 CLI / TUI 资产有清晰的质量边界、验证入口和交付判断”。

## 9. 完成标准

满足以下条件，可认为 `CMP-40` 达成：

- 有共享技术方案
- 有 phase-based 工程拆解
- 有明确的 parent/child issue 分发计划
- 明确了 `dbtool-cli-v1`、`dbtool-tui-v1`、`dbtool-usable-v1` 的边界
- 明确了 usable-v1 当前不需要招聘