docs(0015): 源码 5 类遗留清单 (v2.2+ 实证 P0 已 done + P1-P6 待办)
基于c637a58wrapCommand 实证重建 (上次86d9dac因太早被7cdc818revert). 5 类遗留 (§2): - §2.1 P0 printCommandEnd 5c 样板 ✅ DONE (c637a58) - §2.2 P1 2 个已知 baseline 坑 (dm/drop + storage/info) - §2.3 P2 25+ 高严重度文件批量 - §2.4 P3 18 个 _validate.ts 错误码 import 不一致 - §2.5 P4 addOutputOptions 已加但 stdout 风格不统一 - §2.6 P5 console.log + throw 统一 (4+h 大改) - §2.7 P6 350+ 裸 process.exit 跨 session 治理 (大坑) 决策依据 (§4): - P0 为什么 ROI 极高: 一行 helper = 30+ 行样板 + 单测 17 条已稳 - P1 紧跟: 独立 1 文件修改, 风险极低 - P3 不放 P1 前: 批量一致性调整 < 已知坑修复 - P5/P6 大坑单独排期 README §引用: ADR 索引 0001-0015 系列, 版本加 v2.2+ wrapCommand.
This commit is contained in:
1 parent
c637a589a4
commit
a5c22b98d3
2 files changed
+176
-2
No files matched your search
@@ -70,7 +70,7 @@ dacli <cmd> --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 <id> --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
|
||||
@@ -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 项检查
|
||||
Reference in new issue
Block a user