diff --git a/README.md b/README.md index 2027c09..eaf8588 100644 --- a/README.md +++ b/README.md @@ -70,7 +70,7 @@ dacli --help # Step 3: 标准 commander 帮助 (含选项 + 描 | 命名规范 (snake/camelCase/f_ 前缀) | `dacli/docs/decisions/0001-fk-relation-form-required.md` + `0002-form-create-ai-4-limitations.md` | | 找 web 源码位置 | 用 IDE 全局搜索 (`Cmd+Shift+F` / `grep -rn`) 找 `formData` / `flowNodes` / `columnList` | | 命令评审历史 | `dacli/docs/cmd-review/` | -| 历史决策 | `dacli/docs/decisions/` (0001-0014 系列, 决策记录; 含 ADR 0014 app clear 覆盖) | +| 历史决策 | `dacli/docs/decisions/` (0001-0015 系列, 决策记录; ADR 0014 app clear + ADR 0015 源码遗留清单 + P0 wrapCommand 收口) | | 历史漂移分析 | `dacli/docs/drift/` (round7/10 等修复记录) | | 跨项目教训 | `dacli/docs/尚数网基本开发规范v3.0.md` (公司规范) | | 反模式 | `dacli/docs/anti-patterns.md` (Web 组件 / 后端约束踩坑) | @@ -332,4 +332,4 @@ dacli form update --fields='[...]' # 按 suggestion 建议的修正 --- **最后更新**: 2026-07-21 -**版本**: v0.13+ 镜像架构 + v2.0+ 输出过滤 + v2.1+ 跨命令 auto-fix +**版本**: v0.13+ 镜像架构 + v2.0+ 输出过滤 + v2.1+ 跨命令 auto-fix + v2.2+ wrapCommand helper diff --git a/docs/decisions/0015-source-leftovers.md b/docs/decisions/0015-source-leftovers.md new file mode 100644 index 0000000..9065bf1 --- /dev/null +++ b/docs/decisions/0015-source-leftovers.md @@ -0,0 +1,174 @@ +# 0015 — 源码遗留清单 + 收口路线 (v2.2+, 2026-07-21) + +> **状态**: 接受 (Accepted, 2026-07-21). +> **作者**: 上次 session 起草被 revert (`7cdc818`), 本 session 重新建 — 实证部分 (P0 + 文件计数) 基于已 commit 的 `c637a58`. + +## 1. 背景 + +2026-07-21 累 3 轮 commit (c637a58 + 7cdc818 + 6 other AUTO_MERGE) 完成了 +dacli 三层接入 (L1 stdout / L2 silent+assertive+suggest / L3 CommandLog 落盘), +26 模块命令接入 `setupOutputFilter + addOutputOptions + printCommandEnd`. + +但接入中暴露的源码问题没顺手收, 留 5 类遗留 (本文档 §2). +优先级按 ROI + 风险排序 (§3), P0 已 commit, 剩 P1-P6 待排期. + +## 2. 5 类遗留 (各带文件数 + 典型示例) + +### 2.1 P0: printCommandEnd 5c 样板散布 ❌→✅ **DONE (c637a58)** + +**症状**: 39 个命令文件散布 `printCommandEnd` 调用, 每个出错分支都要 +copy-paste 5 个固定字段: + +| # | 字段 | 重复 | +|---|------|------| +| 1 | `command: 'xxx create'` (字符串字面量) | 39 处 | +| 2 | `appCode: c.appCode` | 39 处 | +| 3 | `fixes: [...cmdFix.silent, ...cmdFix.assertive, ...cmdFix.suggestions]` | 31 处 | +| 4 | `duration_ms: Date.now() - startTime` | 39 处 | +| 5 | `verbose: opts.verbose, json: opts.json` | 39 处 | +| + | `process.exit(1)` 紧随其后 | 30+ 处 | + +**修复**: `_output_filter.ts:107` 加 `wrapCommand(handler)` helper: + +```ts +wrapCommand({ + command: 'datasource create', + appCode: c.appCode, + startTime: Date.now(), + verbose: opts.verbose, + json: opts.json, + fixes: [...cmdFix.silent, ...cmdFix.assertive, ...cmdFix.suggestions], +}, async (ctx) => { + if (validationFails) { + ctx.fail('msg', { enCode: opts.enCode }) // exit 1, 落 failure log + return + } + // ... 业务逻辑 ... + ctx.success({ id, enCode }) // 落 success log +}) +``` + +**已迁移 6 文件** (commit c637a58): +- `datasource/create.ts` (validation fail + backend fail + success 三路径) +- `datasource/delete.ts` (fail + success) +- `datasource/list.ts` (try/catch/finally → ctx.fail) +- `datasource/test.ts` (try/catch/finally → ctx.fail) +- `dict/typecreate.ts` (含 partial 路径 → `ctx.partial()`) +- `menu/create.ts` (原本有 local `printEnd` 合并, 现切到 wrapCommand, + Mode A/B 双路径 + D-4/P0-4 fallback 多 ctx 调用) + +**测试**: `tests/unit/output_filter.test.ts` 加 6 describe blocks +(success / partial / fail / throw / fixes 透传 / 无 appCode), **17/17 PASS**. + +**端到端验证**: `datasource list/test --json`, `--help`, validation fail 路径 +(bscode 含 `!` + dbType=MySQL 缺 serviceName) → exit 1 + 错误 log 完整保留. + +### 2.2 P1: 已知 baseline 坑 (2 类, 各 1 文件) + +| 文件 | 问题 | 修法 | +|------|------|------| +| `dacli/src/commands/dm/drop.ts` | 缺 TTY 拦截, 跑在 CI 会无确认删表 | 加 `if (!opts.yes && process.stdin.isTTY)` 同 datasource/delete | +| `dacli/src/commands/storage/info.ts:38` | 同文件内 `DacliError` 类分叉 (vs `src/core/types.ts` 统一) | 统一 import `'../../core/types.ts'` | + +**工作量**: 0.5h, 1 文件 P0-1, 1 文件 import 修改. + +### 2.3 P2: 25+ 高严重度文件批量改造 (validator 模式) + +待列 (本次 session 没时间跑全 `validateXxx` 函数审查). +预估: 大多 `form/create.ts` 子模块 + `workflow/create.ts` step machine 等. + +### 2.4 P3: per-module `_validate.ts` 错误码 import 不一致 + +**症状**: 18 个 `_validate.ts` 文件 (form/dict/menu/workflow 等模块各自), +有的从 `../_error_codes.ts` import, 有的内联 error 字符串. + +**修法**: 全改 `import { ValidationError } from '../_error_codes.ts'`, +让 step machine 输出格式全平台一致 (供 `dacli log last` 统一聚合). + +**工作量**: 1h (18 文件 × 5min/file × 4-5 改动点 = 1.5h). + +### 2.5 P4: `addOutputOptions` 已加, 但 stdout 文案风格未统一 + +**症状**: `addOutputOptions` 已迁移 38 文件 (含 v2.2 wrapCommand 6 文件), +但 `--verbose` 输出仍有 console.log vs log.info 混用 (`datasource/list.ts:49-56` +直接 `console.log` 画表格 → verbose 模式不参与). + +**修法**: 把表格打印也走 `log.flush()`, 让 verbose 模式下能完整 trace 流程. + +**工作量**: 1h (38 文件逐个修). + +### 2.6 P5: `console.log` + `throw new Error` 统一 + +**症状**: 部分文件用裸 `console.log` (e.g. `datasource/list.ts` 表格), +部分 throw `new Error(...)` 而非 `new DacliError(...)` (dacli/src/core/types.ts:57), +导致 throw 时落 L2 catch 路径走 bad path. + +**修法**: 全改 `log.*` + `DacliError` 统一 (跨 100+ 文件). + +**工作量**: 4+h (风险高, 需逐步推进). + +### 2.7 P6: 350+ 裸 `process.exit(1)` 跨 session 治理 + +**症状**: 350+ 处 `process.exit(1)` 散布 88+ 文件, 跨 session 复用 state 不能 +等 `exit` 后清干净 (test/auto-fix/silent fixes 等). +详细统计: `grep -rcn "process.exit(1)" src/commands | grep -v ":0" | wc -l` = 86+ 行. + +**修法**: 统一 `wrapCommand(ctx.fail)` 收口 (见 §2.1). +**风险**: process.exit() 之后部分资源未释放 (file watcher / log buffer flush 不完整), +整体迁移风险大, 需先 P0 + P1 + P3 + P4 完成后逐模块切. + +**工作量**: 大坑 (8+h), 跨 session. + +## 3. 优先级路线 (按 ROI + 风险) + +> 已接顺路 (本节验证): P0 ✅ done (c637a58). + +| P | 工作量 | 价值 | 状态 | 起点 (commit/PR) | +|---|--------|------|------|-------------------| +| **P0** | 1h | 极高 | ✅ **DONE** | c637a58 (wrapCommand helper + 6 文件迁移 + 17 单测) | +| **P1** | 0.5h | 高 | 待 | `dacli/src/commands/dm/drop.ts` + `dacli/src/commands/storage/info.ts:38` | +| P2 | 2-3h | 高 | 待 | form/create.ts 子模块验证函数审查清单 | +| P3 | 1h | 中 | 待 | 18 个 `**/_validate.ts` 改错误码 import | +| P4 | 1h | 中 | 待 | `addOutputOptions` 已加, stdout 文案不统一 → 走 log.flush | +| P5 | 4+h | 中低 | 待 | console.log + throw new Error 统一收口 | +| P6 | 大坑 | 极高 | 待 | 350+ 裸 process.exit 跨 session 治理 | + +## 4. 决策依据 + +### 4.1 为什么 P0 ROI 极高 + +- **一行 helper = 30+ 行样板**: 39 文件每处 5c + process.exit(1) 是 6 行, + wrapCommand 提供的 ctx 让 handler 模板减到 1-3 行. +- **合并 + 稳定性**: `menu/create.ts` 之前已有 local `printEnd`, wrapCommand + 是其超集 + 收口 (包括 throw 自动 catch → fail, success/partial/fail 单一语义). +- **可观测性**: 已经独立单测 17 条, 后续 39 文件可放心迁移. +- **未来 P6 解套**: P6 (350+ 裸 process.exit) 的非 wrapper exit 全部能被 + P0 的 wrapCommand 收口 (e.g. `dict/typecreate.ts` 多处 `process.exit(1)` 现 + 切到 `ctx.fail`), 后续 P6 改造时只需要看 wrapCommand 是否覆盖到对应路径. + +### 4.2 为什么 P1 紧跟 P0 + +P1 是 2 个独立 1 文件修改, 跟 P0 同 PR 不合适 (应独立 commit), +但风险极低 (只 1 文件 + 1 import). + +### 4.3 为什么 P3 不放在 P1 之前 + +P3 是 18 文件批量改 import, 改完不引入新功能 (只增一致性), +而 P1 解决已知不变量违反. **修已知坑优先于批量调整**. + +### 4.4 P5/P6 风险评估 + +P5 涉及大量文件 (100+) 改 console.log → log.* + throw new Error → DacliError, +每次改动都需单测覆盖 (避免 console.log → log.* 后 silent 模式吞掉表格). + +P6 是大坑, 因为 350+ process.exit(1) 跨 session 的状态清理 (file watcher ++ log buffer flush) 没系统化. 建议: +- 先做 P3 + P4 + P5 (低风险清理) +- P6 单独排期, 跨 session 推进, 每次只切 1-2 个模块的 process.exit. + +## 5. 相关决策 + +- ADR 0010: `dacli v2 self-correcting CLI` (L1/L2/L3 三层, 输出过滤 + auto-fix) +- ADR 0014: `app clear docs coverage` (docs/{app}/ 清理决策) +- `dacli/README.md:213` 三层处理总结 (§第一/第二/第三层) +- `dacli/README.md:240` 修改前的 5 项检查