新增 §4.1 'P4 v3 全量收口 (2026-07-21)' 详细段: - 范围修正: scan 估算 ~330 处, 实际 25 文件 33+ 处真表格. 其余分 (a) 树/key:value dump (dict/typelist + storage/info + user/auth-groups + user/info + menu/info) (b) 调试日志 (form/_ai + kb/show + apis/info 等) - 8 批 commit 表格 (15b3361→07463cb, 本 session 19 文件 + 前 session 6 = 25/25) - 迁移模式固化 (代码模板) - 6 条经验教训 (估算偏差 / Edit vs Write / UUID 截断 / --include-actions / 进度条保留 / 不需新 primitive) §3 优先级表 P4 v3 行: '待' → '✅ DONE', 加 8 commit 引用 + ~310 散布分类 原 §4.1-4.4 顺延 → §4.2-4.5 (P0 ROI / P1 紧跟 / P3 不放 P1 前 / P5-P6 风险). 验证: - TS compile baseline 57 不变 - 73/73 vitest PASS - P4 v3 全量收口闭环: 25/25 REAL_TABLE 文件
14 KiB
0015 — 源码遗留清单 + 收口路线 (v2.2+, 2026-07-21)
状态: 接受 (Accepted, 2026-07-21). P0 + P3 已 done. 作者: 上次 session 起草被 revert (
7cdc818), 本 session 重新建 — 实证部分 (P0 + P3 + 文件计数) 基于已 commit 的c637a58/715fcb9. 扫描报告:dacli/docs/cmd-review/scan-2026-07-21.md8 维度扫描 + 4 项新发现 (workflow shim / console.log 范围扩大 / form/create 13 process.exit / DacliError 实际无重复).
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:
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(原本有 localprintEnd合并, 现切到 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 坑 (1 类, 1 文件)
| 文件 | 问题 | 修法 | 状态 |
|---|---|---|---|
dacli/src/commands/dm/drop.ts |
缺 TTY 拦截, 跑在 CI 会无确认删表 | 加 if (!opts.yes && process.stdin.isTTY) 同 form/delete.ts:25 / print/delete.ts:46 / report/delete.ts:39 |
✅ done (本 session) |
storage/info.ts:38 DacliError 分叉 (ADR 早期记的): 实际不存在.
8 维度扫 (本 session) 确认 class DacliError 仅 src/core/types.ts:57 一处定义,
storage/_helpers.ts 已正确 import { DacliError } from '../../core/types.ts'.
ADR 0015 早期记述有误, 现清空.
工作量: 0.5h, 1 文件.
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), P3 ✅ done (715fcb9), P1 ✅ done (5ead157), shim ✅ done (5ead157), P4a ✅ done (22593df), P6 sample ✅ done (22593df), P5 sample ✅ done (45e9f10).
| P | 工作量 | 价值 | 状态 | 起点 (commit/PR) |
|---|---|---|---|---|
| P0 | 1h | 极高 | ✅ DONE | c637a58 (wrapCommand helper + 6 文件迁移 + 17 单测) |
| P3 | 1h | 中 | ✅ DONE | 715fcb9 (18 _validate.ts 删本地说法, 改 import { ValidationError } from '../_error_codes.ts', 净减 113 行) |
| P1 | 0.5h | 高 | ✅ DONE | 5ead157 dm/drop.ts TTY 拦截 (镜像 form/delete.ts:25); storage/info.ts:38 DacliError 分叉实际不存在 (ADR §2.2 修订) |
| shim | 0.5h | 低 | ✅ DONE | 5ead157 workflow/_output.ts 11 import 改写 + 删 shim |
| P4a | 0.3h | 低 | ✅ DONE | 22593df console.error/warn → log.error/warn (11 文件, 17 处); console.log 表格 333 处保留 |
| P6 sample | 1h | 中 | ✅ DONE | 22593df wrapCommand 迁移 7 文件 (dm/list, dm/fields, dict/datalist, dict/typelist, form/info, workflow/info, workflow/list) |
| P5 sample | 0.2h | 中 | ✅ DONE | 45e9f10 throw new Error → DacliError 9 命令路径文件 (datasource/test + integration/* + report/* + storage/info + user/*) |
| P5 全量 | 0.2h | 中 | ✅ DONE | c6b7fe8 portal/create + bigscreen/construct 2 文件 throw → DacliError (剩 ~15 路径不存在, 都在 SDK/test helper) |
| P6 sample 续 | 0.7h | 中 | ✅ DONE | 11f94a3 wrapCommand 续迁 7 文件 (form/list + report/{list,info} + storage/list + integration/{email,smstest,webhook}test); tests/unit/report_wired.test.ts 老 pattern 静态契约更新到 wrapCommand 新约定 |
| P4 v2 | 0.5h | 中 | ✅ DONE | log.printRawTable(headers, rows, opts) 新 primitive + 3 文件迁移 (datasource/list, dm/list, dm/fields) + 5 单测; 剩 ~330 处 console.log 表格后续 session 推广 |
| P4 v3 | ~2h (8 batches) | 中 | ✅ DONE | 19 文件完整 wrapCommand 迁移 + 25/25 REAL_TABLE 文件全部 printRawTable 化 (8 commits: 15b3361 → 07463cb). 详见 §P4 v3 全量收口段. 剩 ~310 处 console.log 散布分两类: (a) 树/key:value dump (dict/typelist + storage/info + user/auth-groups + user/info + menu/info 等), 需另写 printTree helper 或保留 console.log; (b) 调试日志 (form/_ai + kb/show + apis/info 等), 不属 P4 v3 范围. |
| P2 | 2-3h | 高 | 待 | form/create + workflow/create + form/codegen 高严重度 25+ 文件批量审查 |
| P6 大坑 | 8+h | 极高 | 待 (跨多 session) | 350+ 裸 process.exit 全面收口 |
4. 决策依据
4.1 P4 v3 全量收口 (2026-07-21)
范围修正
scan-2026-07-21.md 估算 "剩 ~330 处 console.log 表格待迁移", 实际只有 25 文件 33+ 处 console.log 真表格. 其余散布分两类:
- 树状 dump / 递归结构 (~10 文件):
dict/typelist.ts(printTree 递归),storage/info.ts(Object.entries key:value),user/auth-groups.ts(flattenTree + indent depth),user/info.ts(菜单权限嵌套树),menu/info.ts(16 console.log 调用). 不属 printRawTable 适用范围. - 调试日志 / 状态行 (~20 文件):
form/_ai.ts(AI step 输出),kb/show.ts(KB entry 详情),apis/info.ts(单 API 详情),apis/status.ts(缓存状态) 等. 不属于表格.
8 批 commit (本 session 2026-07-21)
| Batch | Commit | 文件数 | 内容 |
|---|---|---|---|
| 1 | 15b3361 |
3 | 简单 swap (已 wrapCommand): report/list + storage/list + workflow/list |
| 2 | a772647 |
2 | apis/search (双表) + apis/tags 完整 wrapCommand |
| 3 | f25a87e |
3 | app/list + bigscreen/list (原 printCommandEnd → wrapCommand) + portal/list |
| 4 | 399f50f |
4 | doc/list (本地 FS) + doc/toc + form/selector + kb/list (重写, 原 builder 链顺序错) |
| 5 | 12f445b |
7 | msg×2 + monitor/online + org/list (UUID 28+.. 截断保留) + print/list + role×2 |
| 6 | 73784f6 |
3 | schedule/log + user/get-position + user/list (6 列最长) |
| 7 | 4c417cc |
2 | workflow/selector + workflow/tasks |
| 8 | 07463cb |
1 | menu/list.ts (复杂 2 表 + --include-actions 标志) |
合计: 8 commits, 25 文件 (本 session 19 + 前 session 6), 100% REAL_TABLE 收口.
迁移模式固化
每文件统一采用:
import { setupOutputFilter, addOutputOptions, wrapCommand } from '../_output_filter.ts'
interface Opts {
// ... 原 options
/** v2.1+ (2026-07-21): --verbose, addOutputOptions 注入 */
verbose?: boolean
}
// 在 cmd builder:
addOutputOptions(cmd) // 删本地 --verbose/--json
.action(async (opts: Opts) => {
setupOutputFilter(opts)
const c = await JnpfClient.fromToken() // 或无 c (storage/doc/kb 类)
await wrapCommand({
command: '<module> <subcmd>',
appCode: c?.appCode,
startTime: Date.now(),
verbose: opts.verbose,
json: opts.json,
fixes: [],
}, async (ctx) => {
try {
// ... 业务逻辑 ...
const summary = { ... }
if (opts.json) {
printJson(...)
return ctx.success(summary)
}
log.printRawTable(
['COL1', 'COL2', ...],
list.map(d => [String(d.col1 || ''), String(d.col2 || ''), ...]),
{ maxColWidth: 80 }, // 可选, 默认 36
)
ctx.success(summary)
} catch (e) {
ctx.fail(`<cmd> 失败: ${(e as Error).message?.slice(0, 200)}`)
}
})
})
经验教训
- 估算偏差: scan-2026-07-21.md 说 ~330 待迁移, 实际只有 33+ 处真表格. 后续 ADR 估算应明示 "console.log 调用数 ≠ 表格数", 表格需 header + separator + padEnd 三要素判定.
- Edit vs Write: 90% 文件 Edit 工作良好, 但 kb/list.ts 原 builder pattern 链顺序错 (.option() 必须在 .action() 前), Write 更清晰. menu/list.ts 因 2 表 + 多 flag + 大量 import 重排, Write 整文件最稳.
- UUID 截断保留: org/list.ts 原
'..' + slice(0, 28)截断逻辑不能直接交给 printRawTable 的…截断 (视觉不一致), 用 pre-truncate 保留. - --include-actions 默认 ON: menu/list.ts 用
--include-actions/--no-include-actions双写 (commander 默认 true), 不能简单addOutputOptions覆盖. - 进度条保留: menu/list.ts 的
process.stderr.write('\r 扫描 form: ...')直接写 stderr, 不走 quiet buffer, 真实进度可见. 不能用 log.* (会被缓冲). - 不需新 primitive: tree dump (dict/typelist 等) 不属本 ADR 范围, 后续如需 printTree helper 再单独立 ADR.
验证
- TS compile baseline=57 (无新错误) — 每个 batch 后立即验证
- vitest 73/73 PASS (含 printRawTable 5 单测) — 每个 batch 后立即验证
- CI 关卡 G WARN (pre-existing, 2 个白名单: integration/storage 已知)
- 8 commits 全部 git push 成功, 累计本 session 19 文件 P4 v3 改造
4.2 为什么 P0 ROI 极高
- 一行 helper = 30+ 行样板: 39 文件每处 5c + process.exit(1) 是 6 行, wrapCommand 提供的 ctx 让 handler 模板减到 1-3 行.
- 合并 + 稳定性:
menu/create.ts之前已有 localprintEnd, 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.3 为什么 P1 紧跟 P0
P1 是 2 个独立 1 文件修改, 跟 P0 同 PR 不合适 (应独立 commit), 但风险极低 (只 1 文件 + 1 import).
4.4 为什么 P3 不放在 P1 之前
P3 是 18 文件批量改 import, 改完不引入新功能 (只增一致性), 而 P1 解决已知不变量违反. 修已知坑优先于批量调整.
4.5 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 项检查