226 lines
8.1 KiB
Markdown
226 lines
8.1 KiB
Markdown
# 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 当前不需要招聘
|