paperclip/dbtool-cli-v1
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d5f69462b062dcb281ebcabc8d0d62a4239cb6a8
dbtool-cli-v1/plans/2026-03-27-dbtool-usable-v1-technical-boundary-and-execution.md
Paperclip CTO d5f69462b0
Some checks failed
release-smoke / macos-13 / x86_64-apple-darwin (push) Has been cancelled
Details
release-smoke / ubuntu-latest / x86_64-unknown-linux-gnu (push) Has been cancelled
Details
release-smoke / windows-latest / x86_64-pc-windows-msvc (push) Has been cancelled
Details
feat(usable): integrate current dbtool implementation snapshot 
Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-04-02 08:26:18 +00:00

8.1 KiB
Raw Blame History

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 当前不需要招聘