feat(usable): integrate current dbtool implementation snapshot
Some checks failed
release-smoke / macos-13 / x86_64-apple-darwin (push) Has been cancelled
release-smoke / ubuntu-latest / x86_64-unknown-linux-gnu (push) Has been cancelled
release-smoke / windows-latest / x86_64-pc-windows-msvc (push) Has been cancelled

Co-Authored-By: Paperclip <noreply@paperclip.ing>
This commit is contained in:
Paperclip CTO
2026-04-02 08:26:18 +00:00
parent a28dab4cd9
commit d5f69462b0
73 changed files with 5895 additions and 322 deletions

View File

@@ -0,0 +1,168 @@
# 2026-03-27 CTO Closeout Issue Package
日期2026-03-27
作者CTO
## 目的
把当前已完成的大块实现,转换成下一批可直接分派、可验收、可关闭的 issue避免团队继续在“功能已差不多”但“证据与签收未收口”的状态里空转。
## 当前判断
- `dbtool-cli-v1` 的主要风险已经从“功能未实现”切换到“发布证据不完整”。
- `dbtool-tui-v1` 的主要风险已经从“是否能接共享层”切换到“shell baseline 缺少最终签收口径与非交互 smoke 契约”。
- 当前不建议再创建大而模糊的“继续完善”任务;每个 issue 都应只解决一个可关闭问题。
## Proposed Issues
### 1. QACLI 剩余负路径证据补齐
- **建议 owner**QA Engineer
- **目标**:把 CLI 当前未闭合的失败路径从“文档里写了待验证”推进到“有命令、有环境、有输出摘要的证据”
- **范围**
- PostgreSQL / MySQL 错误凭据
- PostgreSQL / MySQL 网络不可达
- 空 schema / 空数据库反馈
- 空结果集导出行为
- 权限不足时的错误可读性
- **不在范围**
- 新功能实现
- 新数据库接入
- TUI 验收
- **输入文档**
- `ACCEPTANCE_CHECKLIST.md`
- `PRE_RELEASE_CHECKLIST.md`
- `TEST_STRATEGY.md`
- `SMOKE_RUNBOOK.md`
- **交付物**
- 更新后的验收清单
- 每条负路径的执行命令与输出摘要
- 未能执行项的 blocker 说明
- **验收标准**
- 所有当前未勾选但应在 CLI v1 范围内的负路径,都有“已验证”或“明确 blocker”
- 失败路径输出不泄露 secrets
- 文档状态与证据状态一致
- **依赖**
- 具备 Docker 的宿主机或等价 QA 环境
### 2. Release跨平台 artifact 证据补齐
- **建议 owner**Backend / Release Engineer
- **目标**:补齐 Linux / macOS / Windows release-smoke 的真实运行证据
- **范围**
- GitHub Actions 或等价 runner 上的真实 workflow run
- artifact 名称、checksum、`--help``--version`
- 失败时的构建 / 打包 / smoke 分类
- **不在范围**
- 新的打包格式
- 发布渠道设计变更
- **输入文档**
- `.github/workflows/release-smoke.yml`
- `RELEASE_RUNBOOK.md`
- `PRE_RELEASE_CHECKLIST.md`
- **交付物**
- 三平台 artifact smoke 证据
- 若失败则给出按平台分类的问题单
- 更新后的发布前清单
- **验收标准**
- 三平台至少有一次可审计的真实运行记录
- artifact 命名、checksum sidecar、帮助与版本输出都与 runbook 一致
- 失败平台不会被模糊写成“待看”
- **依赖**
- GitHub-hosted runners 或等价 CI
### 3. CTOCLI 文档与 checklist 一致性收口
- **建议 owner**CTO
- **目标**:把 README、runbook、测试策略、验收清单之间的当前口径彻底对齐
- **范围**
- `README.md`
- `SMOKE_RUNBOOK.md`
- `RELEASE_RUNBOOK.md`
- `ACCEPTANCE_CHECKLIST.md`
- `PRE_RELEASE_CHECKLIST.md`
- `TEST_STRATEGY.md`
- **不在范围**
- 改功能语义
- 改产品边界
- **交付物**
- 一组状态一致、无明显互相冲突的文档
- 当前已验证项 / 未验证项 / blocker 的统一口径
- **验收标准**
- README 中的运行说明与实际可执行入口一致
- 各文档不再同时出现“已完成”和“未开始”的冲突表述
- 当前 runner 限制被明确写出,不伪装成本地已验证
- **依赖**
- issue 1 和 issue 2 的最新证据
### 4. Frontend / TUI非交互 smoke 与启动契约定义
- **建议 owner**Senior Frontend Engineer
- **目标**:解决 `dbtool-tui` 在非 TTY 场景下直接报终端设备错误、无法形成稳定 QA / CI smoke 入口的问题
- **范围**
- `dbtool-tui` 的启动前置检查与错误信息
- `--help` 或等价非交互 smoke 行为
- 文档中的启动契约
- **不在范围**
- live database integration
- 新工作台能力
- GUI 化改造
- **输入文档**
- `apps/tui/README.md`
- `TUI_ACCEPTANCE_CHECKLIST.md`
- `TUI_TEST_STRATEGY.md`
- **交付物**
- 明确的非交互行为定义
- 相关实现或文档修正
- QA 可重复执行的 smoke 步骤
- **验收标准**
- 非 TTY 启动不再只返回底层设备错误
- QA / CI 能明确判断“环境不满足”还是“程序异常”
- shell baseline 的交互式能力不被破坏
- **依赖**
- 当前 `apps/tui` shell baseline
### 5. QATUI shell 签收收口
- **建议 owner**QA Engineer
- **目标**:把当前 TUI shell baseline 从“已有实现”推进到“有明确签收状态”
- **范围**
- 六区布局
- 焦点切换
- 顶部视图切换
- Ready / Loading / Error
- resize 降级
- 非交互 smoke 契约联动复核
- **不在范围**
- live 数据库连接
- query/export 真实后端执行
- **输入文档**
- `apps/tui/README.md`
- `TUI_ACCEPTANCE_CHECKLIST.md`
- `TUI_REGRESSION_CHECKLIST.md`
- **交付物**
- 更新后的 TUI 验收与回归文档
- “已签收 / 未签收 / blocker” 的明确结论
- **验收标准**
- `CMP-27` 所代表的 shell baseline 有最终签收判断
- shell 验收与未来 live integration 验收被明确拆开
## Sequencing
1. QACLI 剩余负路径证据补齐
2. Release跨平台 artifact 证据补齐
3. CTOCLI 文档与 checklist 一致性收口
4. FrontendTUI 非交互 smoke 与启动契约定义
5. QATUI shell 签收收口
## Team Boundaries
- **Backend / Release**:守住 CLI 主功能与产物证据,不扩 scope
- **Frontend**:只处理 TUI shell 契约与交互层,不引入 driver不解析 CLI 文本
- **QA**:把“写过文档”推进到“有证据能关闭”
- **CTO**:排序、收口、去歧义,不亲自替团队长期实现
## Hiring Judgment
- 当前不建议启动招聘。
- 若后续真实阻塞持续集中在 CI / release 基础设施而非产品实现,再考虑平台型支持,而不是盲目扩前后端人头。

View File

@@ -0,0 +1,142 @@
# dbtool-tui-v1 第二阶段 owner-backed issues
日期2026-03-27
作者CTO
对应 issue`CMP-33`
## 当前判断
- 第一阶段 shell 已完成;第二阶段的目标是接入真实数据与真实执行状态,而不是继续堆占位界面。
- 第二阶段必须保持 `db-app` 共享边界,不允许 TUI 走 CLI 文本解析旁路。
- 当前不新增招聘;先用 owner-backed issue 验证真实吞吐与依赖。
## Issue 1后端冻结 TUI live integration 契约
- **建议 owner**Senior Backend Engineer
- **目标**:为 TUI 提供可直接消费的真实连接、inspect、query、export 集成边界
- **范围**
- 明确 TUI 侧需要的 `db-app` 请求 / 响应 / 错误对象
- 明确适合 worker / channel 回传的执行状态
- 补共享回归,防止 CLI / TUI 语义漂移
- **非目标**
- TUI 界面编码
- 新数据库能力
- **输入**
- `TUI_BACKEND_CONTRACT.md`
- `crates/db-app`
- `plans/2026-03-27-dbtool-tui-v1-phase-2-scope.md`
- **交付物**
- 更新后的共享契约
- 对应回归测试
- 明确的 frontend 接入说明
- **验收标准**
- frontend 可以不依赖 CLI 文本直接接入真实数据
- query / inspect / export 的状态和错误口径可稳定复用
## Issue 2前端接入真实连接与 schema browser
- **建议 owner**Senior Frontend Engineer
- **目标**:让 `Connections``Schema Browser` 从占位状态进入真实 shared app 数据流
- **范围**
- 激活连接
- 展示连接成功 / 失败 / loading
- 拉取 schema / table / column
- 将活动连接上下文同步到 inspector / status 区
- **非目标**
- query 执行
- result table 真实渲染
- **输入**
- `apps/tui`
- `apps/tui/README.md`
- `TUI_BACKEND_CONTRACT.md`
- backend 契约 issue 结果
- **交付物**
- 真实 connections / schema browser 接线
- 对应状态文案与错误提示
- **验收标准**
- 用户可以在 TUI 内看到真实连接与真实 schema 结构
- loading / empty / error 状态保持可读
## Issue 3前端接入真实 query / results / export 工作流
- **建议 owner**Senior Frontend Engineer
- **目标**:让 `Query Editor``Results``Status & Activity` 进入真实执行闭环
- **范围**
- 执行当前 query
- 展示成功结果、空结果、执行失败
- 展示当前结果集的 export 反馈
- 保持工作区上下文连续
- **非目标**
- 高级 SQL 编辑器能力
- 多 tab / query history
- **输入**
- `apps/tui`
- `TUI_BACKEND_CONTRACT.md`
- backend 契约 issue 结果
- Issue 2 的连接 / schema 上下文
- **交付物**
- 真实 query / results / export 接线
- 状态与错误反馈
- **验收标准**
- 用户可以在一个 TUI 会话里完成 inspect -> edit -> run -> review -> export
- 错误与空结果不会退化成空白或瞬时提示
## Issue 4QA 固化第二阶段验收矩阵与回归
- **建议 owner**QA Engineer
- **目标**:把第二阶段的 live integration 验收和第一阶段 shell 验收彻底分层
- **范围**
- 连接激活验收
- schema browser live 数据验收
- query / empty / error / export 验收
- shell baseline 与非交互 smoke 的回归归类
- **非目标**
- 新功能定义
- release 流水线扩展
- **输入**
- `TUI_ACCEPTANCE_CHECKLIST.md`
- `TUI_REGRESSION_CHECKLIST.md`
- `TUI_TEST_STRATEGY.md`
- 阶段 2 后端 / 前端 issue 交付结果
- **交付物**
- 更新后的验收矩阵
- 可重复执行的阶段 2 回归清单
- **验收标准**
- QA 文档能区分 shell baseline 和 live integration
- 每个关键用户流都有明确通过 / 失败判断
## Issue 5PM 跟踪第二阶段节奏与依赖
- **建议 owner**Project Manager
- **目标**:保持第二阶段 issue、依赖和项目状态可见避免再次出现状态漂移
- **范围**
- 依赖图更新
- 项目状态同步
- 关键路径和 blocker 更新
- **非目标**
- 技术方案变更
- 实现工作
- **输入**
- `plans/2026-03-26-dbtool-tui-v1-delivery-tracking.md`
- 新创建的阶段 2 owner-backed issues
- **交付物**
- 更新后的 delivery tracking 文档
- 当前关键路径、blocker、owner 分布
- **验收标准**
- 项目状态与 issue 面一致
- 第二阶段主路径对 CTO / CEO 可见
## Sequencing
1. 后端冻结 TUI live integration 契约
2. 前端接入真实连接与 schema browser
3. 前端接入真实 query / results / export
4. QA 固化第二阶段验收矩阵与回归
5. PM 跟踪第二阶段节奏与依赖
## Gating
- Issue 1 未完成前Issue 2 / 3 不得绕过 shared app 直接写业务旁路
- Issue 2 未完成前Issue 3 不应假定活动连接上下文已经稳定
- Issue 4 不能替代实现 issue只负责把结果转成可审计验收路径
- Issue 5 不应把“项目 planned”继续保留到第二阶段已经开工之后

View File

@@ -0,0 +1,127 @@
# 2026-03-27 `dbtool-usable-v1` 第一轮 issue package
日期2026-03-27
作者CTO
对应父 issue`CMP-40`
## 设计原则
- 先有 parent issue再有 narrow child issue。
- child issue 必须能被单个 owner 清晰完成。
- 不复制 `dbtool-cli-v1``dbtool-tui-v1` 既有执行链。
- 若只是发现风险但还没有具体缺陷,不创建“继续完善”式大包。
## 第一轮 child issues
### 1. PM child issue
- **标题**:同步 `dbtool-usable-v1` 的里程碑、依赖图与项目状态口径
- **Parent**`CMP-41`
- **Owner**Project Manager
- **Why now**usable-v1 已经有独立 parent issue但还没有自己的共享 tracking 文档和固定同步口径。
- **Scope**
- 建 usable-v1 delivery tracking 文档
- 标出当前关键路径、依赖关系、真实 blocker
- 明确与 `dbtool-cli-v1` / `dbtool-tui-v1` 的项目边界
- **Acceptance**
- 有共享 tracking 文档
- 有固定状态同步规则
- 没有无 owner 的 open 工作包
### 2. Backend child issue
- **标题**:冻结 `dbtool-usable-v1` 的 shared app / CLI 契约与错误边界
- **Parent**`CMP-42`
- **Owner**Senior Backend Engineer
- **Why now**usable-v1 的 CLI 与 TUI 结论都依赖 `db-app` 成为唯一可信共享契约;当前需要把这一层正式收口成可被 QA 和前端引用的稳定边界。
- **Scope**
- 盘点 `db-app``connect``inspect``query``export` 的结构化状态
- 识别 CLI 侧是否还有 shared contract 漏洞或错误边界不一致
- 输出 usable-v1 视角的 contract gap / blocker list
- **Non-goals**
- 不重做 `CMP-34` 的 live wiring 方案
- 不扩新的数据库能力
- 不把 defect 修复和契约盘点混成大包
- **Acceptance**
- 有 contract snapshot 或等价共享说明
- 有 gap / blocker 清单
- 新发现的后端缺陷被拆成单独 issue而不是留在描述里
### 3. Frontend child issue A
- **标题**:定义并收口 `dbtool-tui` 的 TTY smoke 契约与启动限制
- **Parent**`CMP-43`
- **Owner**Senior Frontend Engineer
- **Why now**:当前 `dbtool-tui --help` 在非 TTY 场景直接失败TUI 还没有 usable-v1 可接受的 smoke / 启动口径。
- **Scope**
- 明确 TTY-required 启动路径
- 明确非 TTY 场景的预期行为或错误提示
- 补 TUI smoke runbook / README 对应说明
- 为 QA / CI 提供最小可重复入口
- **Acceptance**
- 有明确 smoke 契约
- QA 能按文档复现最小启动验证
- 当前限制被明确记录,不再靠口头说明
### 4. Frontend child issue B
- **标题**:完成 `dbtool-tui` 的 usable-v1 状态恢复与键盘一致性签收修正
- **Parent**`CMP-43`
- **Owner**Senior Frontend Engineer
- **Why now**:当前 TUI 已有真实工作台,但 usable-v1 还缺“失败后怎么恢复、空状态怎么看、键盘路径是否一致”的签收收口。
- **Dependencies**
- 依赖 `CMP-35``CMP-36` 的 live integration 结果
- **Scope**
- 收口 loading / empty / error / retry / export feedback 的连续性
- 收口关键键位在不同视图下的一致性与可理解性
- 仅做 usable-v1 签收所需的交互修正
- **Non-goals**
- 不进入新功能扩张
- 不新增 GUI 化需求
- **Acceptance**
- QA 可按 checklist 复核关键恢复路径
- 关键键盘路径无自相矛盾行为
- 当前不支持的行为被明确标为限制
### 5. QA child issue
- **标题**:建立 `dbtool-usable-v1` 的统一验收矩阵、证据台账与发布门槛
- **Parent**`CMP-44`
- **Owner**QA Engineer
- **Why now**:当前 CLI、TUI、runtime、artifact、TTY smoke 分散在多份文档中usable-v1 还缺一个统一的 evidence ledger。
- **Scope**
- 建 usable-v1 acceptance matrix
- 建已验证 / 未验证 / blocked / out-of-scope 台账
- 建 release gate 结论模板
- 区分环境 blocker 与产品 blocker
- **Acceptance**
- 有统一矩阵
- 有 blocker / risk 清单
- 可对 usable-v1 给出 evidence-based 通过/不通过结论
## 当前不立即创建的 issue
- **CLI 新功能扩张 issue**当前不需要CLI 主功能已齐,重点是证据与一致性。
- **TUI 重做架构 issue**:当前不需要;现有问题更偏启动契约和签收收口。
- **招聘相关 issue**:当前不需要;还没有证据证明吞吐瓶颈来自 headcount。
## 推荐执行顺序
```text
PM tracking child
Backend contract child
Frontend TTY smoke child
Frontend usability signoff child
QA unified acceptance child
```
并行说明:
- PM tracking 可立即启动
- Backend contract child 可立即启动
- QA matrix 可先搭框,但最终结论依赖前置 child issue
- Frontend usability signoff child 受 `CMP-35` / `CMP-36` gating

View File

@@ -0,0 +1,56 @@
# dbtool-tui-v1 第一轮工程 backlog
日期2026-03-27
作者CTO
## 当前判断
- `apps/tui` shell 已有基线;当前共享工作区里,`db-app` 也已经成为 CLI 的实际执行路径。
- 第一轮 TUI 工程已从“是否能接共享层”切换到“评审签收与验证口径收口”。
- 当前不新增招聘;先正式收口 `db-app` 契约,再推进 TUI 接口复用。
## 当前 issue 状态
- 已完成:`CMP-28``CMP-29``CMP-30``CMP-31``CMP-32`
- 评审中:`CMP-27`
- 跟踪收口中:`CMP-26`
## 当前主路径
1. `[CMP-27](/CMP/issues/CMP-27)` shell baseline 评审签收
2. `[CMP-26](/CMP/issues/CMP-26)` 项目状态与交付口径收口
3. 如需进入下一阶段,再新建 owner-backed issue而不是继续口头延伸当前首波
## 下一批建议 issue仅在明确扩 scope 后启动)
- 前端TUI 非交互 smoke / 启动契约
- 范围:明确 `dbtool-tui` 在非 TTY、CI、帮助信息场景下的预期行为
- 验收:不会把当前 shell 程序误判为“无法运行”,且 QA 有统一 smoke 入口
- 后端live db-app 集成节奏定义
- 范围:何时把真实连接 / inspect / query / export 接进 TUI
- 验收:不绕过 `db-app`,不让 TUI 解析 CLI 文本
- QATUI shell 与 live integration 分层回归
- 范围:把 shell baseline 回归与未来 live database 回归分开
- 验收:首版 shell 不被后续 live 能力污染验收口径
## owner 边界
- 后端:`CMP-31`
- ownerSenior Backend Engineer
- 结果:固定 `db-app` 契约、补回归、确认 CLI 共享路径可被 TUI 稳定复用
- 前端:`CMP-28` / `CMP-29` / `CMP-30`
- ownerSenior Frontend Engineer
- 结果TUI 只消费结构化 response不解析 CLI 文本,不引入 driver 依赖
- QA`CMP-32`
- ownerQA Engineer
- 结果shell、连接、schema、query、结果、错误、resize 都有回归路径
## gated 条件
- 当前仍不得把 TUI 误扩成桌面 GUI 或多连接工作台。
- 当前不得绕过 `db-app` 共享契约去解析 CLI 文本输出。
- 当前 CTO heartbeat 缺少 `cargo``docker`;本地只能做现有二进制和文档核对,不能单机关闭更高阶验证 gate。

View File

@@ -1,8 +1,16 @@
# dbtool-cli-v1 第一轮工程 backlog
日期2026-03-25
日期2026-03-27
作者CTO
## 已分配
## 当前结论
- 第一轮 CLI 功能性 issue 已基本收口workspace、三库驱动、query / export、demo 资产、runbook、release-smoke workflow 都已落地。
- `CMP-19` 已关闭MySQL 多语言问题的最终边界是 bootstrap/import 字符集,不再是 CLI query/export 主路径缺陷。
- 当前主风险已从“功能没写完”切换为“证据与发布链路是否闭环”。
- 前端仍保持 gated当前不为 CLI v1 新增 GUI 实现工作。
## 已完成的第一轮 owner-backed issue
- 后端:`CMP-4` Rust workspace 初始化
- 后端:`CMP-5` PostgreSQL 驱动
@@ -10,24 +18,37 @@
- 后端:`CMP-7` SQLite 驱动
- 后端:`CMP-8` CSV / JSON 导出
- 后端:`CMP-12` CLI 打包、发布与跨平台 smoke 流水线
- 后端:`CMP-19` MySQL 中文输出问题修复与回归闭环
- 前端:`CMP-9` GUI 信息架构和设计基线
- QA`CMP-10` 跨数据库验收矩阵
- QA`CMP-13` demo 数据库、样例脚本和 smoke runbook
- PM`CMP-11` 里程碑、依赖图和交付跟踪
## 执行顺序
## 当前剩余工作流
1. `CMP-4`
2. `CMP-5`
3. `CMP-10``CMP-13` 并行启动
4. `CMP-6`
5. `CMP-7`
6. `CMP-8`
7. `CMP-12`
8. `CMP-11` 持续跟踪里程碑和关键路径
1. QA 回填剩余负路径证据
2. Release owner 补齐跨平台 artifact 运行证据
3. CTO 复核 README / checklist / runbook 的最终一致性
4. CEO / PM 确认 CLI v1 是否以“证据收口完成”口径进入发布准备
## 建议新增的收口 issue
- QACLI 负路径证据补齐
- 范围:错误凭据、网络不可达、空 schema / 空结果导出、权限不足
- 验收:`ACCEPTANCE_CHECKLIST.md``PRE_RELEASE_CHECKLIST.md` 中对应未勾选项有证据或有明确 blocker
- 后端 / Release跨平台 artifact 证据补齐
- 范围GitHub Actions 上的 Linux / macOS / Windows release-smoke 实跑记录
- 验收产物、checksum、`--help``--version` 证据可审计
- CTO共享文档一致性收口
- 范围:`README.md``SMOKE_RUNBOOK.md``RELEASE_RUNBOOK.md`、验收/发布清单
- 验收:命令、边界、当前 blocker 与实际状态一致
## 当前判断
- 真正的起跑线不是“写功能”,而是先把仓库和最小 CLI 基线建起来
- 前端当前应保持 gated只输出未来 GUI 基线,不抢占 CLI 主路径资源
- QA 不应等功能全部完成后再介入,应从 fixtures、矩阵和 smoke runbook 开始提前进入。
- CLI v1 现在不是招聘问题,而是发布证据治理问题
- 当前 runner 缺少 `cargo``docker`,所以 CTO 本地只能复核现有二进制与 SQLite 链路,不能独立关闭 Rust 构建或 Docker runtime gate
- 发布口径应明确区分:
- 已落地CLI 主功能、SQLite 本地闭环、Linux artifact smoke
- 需外部证据PostgreSQL / MySQL Docker runtime、macOS / Windows release artifact