Files
dacli/docs/decisions/0015-source-leftovers.md
T
ssw aa21fc57ef docs(ADR 0015): P4 v3 全量收口固化 + §4.1 经验教训段
新增 §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 文件
2026-07-21 18:48:56 +08:00

14 KiB
Raw Blame History

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.md 8 维度扫描 + 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 (原本有 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 坑 (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 真表格. 其余散布分两类:

  1. 树状 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 适用范围.
  2. 调试日志 / 状态行 (~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)}`)
    }
  })
})

经验教训

  1. 估算偏差: scan-2026-07-21.md 说 ~330 待迁移, 实际只有 33+ 处真表格. 后续 ADR 估算应明示 "console.log 调用数 ≠ 表格数", 表格需 header + separator + padEnd 三要素判定.
  2. Edit vs Write: 90% 文件 Edit 工作良好, 但 kb/list.ts 原 builder pattern 链顺序错 (.option() 必须在 .action() 前), Write 更清晰. menu/list.ts 因 2 表 + 多 flag + 大量 import 重排, Write 整文件最稳.
  3. UUID 截断保留: org/list.ts 原 '..' + slice(0, 28) 截断逻辑不能直接交给 printRawTable 的 … 截断 (视觉不一致), 用 pre-truncate 保留.
  4. --include-actions 默认 ON: menu/list.ts 用 --include-actions / --no-include-actions 双写 (commander 默认 true), 不能简单 addOutputOptions 覆盖.
  5. 进度条保留: menu/list.ts 的 process.stderr.write('\r 扫描 form: ...') 直接写 stderr, 不走 quiet buffer, 真实进度可见. 不能用 log.* (会被缓冲).
  6. 不需新 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 之前已有 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.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 项检查