diff --git a/docs/decisions/0015-source-leftovers.md b/docs/decisions/0015-source-leftovers.md new file mode 100644 index 0000000..14a156d --- /dev/null +++ b/docs/decisions/0015-source-leftovers.md @@ -0,0 +1,179 @@ +# 0015-source-leftovers + +> **日期**: 2026-07-21 +> **状态**: Accepted (扫描留待后续) +> **作者**: claude-code + +## Context + +**背景**: 完成三层接入 + docs/{app} clean 闭环后, 系统性扫描 dacli/src/commands/*.ts 源码, 找出其它类型遗留 (除已修的 process.exit + console.log + printCommandEnd 样板). + +**方法**: 用 Explore agent 在 26 个模块 × 全 .ts 文件做 5 类规则扫描, 每类列代表性文件:行号. + +**目标**: 把扫描留档, 留优先级路线给后续迭代. **不动代码** (本 session 已收尾). + +## Decision + +**不做**源码层修复 (本 ADR 写完后停). 留在 ADR 路线让后续 session 跟进. + +理由: +- 已完成核心闭环: 三层接入 10 文件 + ADR 0014 + 关卡 I + P1 fallback (见本 session 累计 6 commits) +- 源码层遗留是 **massive 后续工程** (350+ process.exit / 360 console.log / 37 throw Error), 单 session 不可能完成, 强行做会引入更多问题 +- 优先级路线清楚, 后续 session 拿本 ADR 直接挑目标 + +## 扫描结果 (5 类遗留) + +### 类别 1: 裸 `process.exit()` — **350+ 处 / 35+ 文件** + +**问题**: `printCommandEnd({result:'failure', error:..., fixes:...})` L3 落 CommandLog 是 v2.1+ (2026-07-21) 引入的标准入口. 但 `process.exit(1)` 直接调用绕过此层, 用户/AI 看 `dacli log last` 不见失败记录. + +**代表案例** (高严重度, 用户痛点): + +| 文件 | 处数 | 类型 | +|------|------|------| +| `form/create.ts` | 4+ | release 失败 / step machine 6 处 exit(2) | +| `portal/create.ts` | 4 | **半套**: 已调 `printCommandEnd({result:'failure'})` 后立即 `process.exit(1)` | +| `di/create.ts` | 5 | 同上"半套"模式 | +| `bigscreen/create.ts` + `construct.ts` | 13+ | 整段裸 exit | +| `form/codegen.ts` / `menu/create.ts` / `dict/*` | 8+ | 同上 | +| `workflow/{create,update}.ts` | 15+ | step machine + release 路径 | +| 35+ list/info/test 类 | 1-2 | `if (cmdError) process.exit(1)` finally 块 | + +**严重度判断**: +- **高**: portal/di/bigscreen/datasource/schedule/role (主 CRUD 命令, 半套模式) +- **中**: form/step_machine 等 (走 6 处 exit(2) 但用户能看到退出码混乱) +- **中**: 13 个 list/info/test 类 finally (已 printCommandEnd, exit 只是退出码语义, 应 throw 让统一 catch) +- **低**: app/status 查询类 (纯查询无需落 CommandLog) +- **低**: _selfcheck/_precheck/_dirty_check/_gate_webapi 等 `_` 前缀自检 (CI 关卡无需用户日志) +- **低**: test/browser, test/render, test/run 子命令 (测试独立退出码) + +### 类别 2: `console.log` / `console.error` 残留 — **360 处 / 96 文件** + +**问题**: 应走 `core/log.ts` 的 `log.info/ok/warn/error/dim/raw` helper (保持 quiet 模式 + L1 stdout 一致). 直接 `console.log` 绕过 quiet mode (`dacli xxx --verbose` 时表格也被截断). + +**代表案例** (高严重度, v2 stdout 三模式受影响): + +| 文件 | 处数 | 用途 | +|------|------|------| +| `menu/info.ts` | 16 | L33-48 字段表打印 | +| `user/info.ts` | 15 | 字段 + 表头 | +| `workflow/info.ts` | 11 | 字段打印 | +| `kb/show.ts` | 11 | kb 模块 (低优先 - 没接入 v2) | +| `form/_ai.ts` | 10 | AI 建表结果 | +| `apis/info.ts` | 10 | API 详情 | +| `menu/list.ts` / `di/info.ts` | 9 | 列表表格 | +| `_gate_webapi.ts` | 21 | L333-392 报告输出 (CI 关卡) | +| `_blindspot_guards.ts:725, 731` | 2 | 自检错误应走 log.error | +| 表格类 (`dict/datalist.ts` `dm/list.ts` 等) | 4-5 | 表格输出 | + +**严重度判断**: +- **高**: menu/user/workflow/role/di info 类 (v2 输出过滤标准后, quiet 模式影响 AI 干完活后看到的关键字段) +- **中**: _gate_webapi / _blindspot_guards (CI 关卡视觉面板) +- **中**: dict/datalist 等 table 类 (无颜色 + 绕过 quiet) +- **低**: kb 子模块 (实验期没接 v2 体系) + +### 类别 3: `throw new Error()` 未统一 DacliError — **37 处** + +**问题**: 应统一 `throw new DacliError(msg, code)` (`core/types.ts:57`). 全 codebase 仅 2 文件 import DacliError (`app/clear.ts`, `storage/_helpers.ts`). + +**代表案例** (按严重度): + +| 文件 | 处数 | 严重度 | +|------|------|--------| +| `storage/info.ts:38` | 1 | **高**: 同模块 `storage/_helpers.ts` 已用 DacliError, info.ts 没用, 分叉 | +| `integration/{smstest,emailtest,webhooktest}.ts` | 9 处 | 中: 3 个 test 类命令集中错误抛出, 与 v2.1 output filter 不打通 | +| `form/_ai.ts:420` | 1 | 中: AI workflow 修复失败 | +| `form/_browser_verify.ts` | 3 | 中: playwright 校验 | +| `form/_buildformdata.ts` | 2 | 中: 未初始化检查 | +| `menu/_helpers.ts:34, 66` | 2 | 中: helper 内 throw | +| `report/info.ts:57, report/list.ts:91` | 2 | 中 | +| `test/run.ts:131, 334, 410` `test/render.ts:1367,1392,1409,1426` | 7 | 低: test 子模块独立 | +| `portal/create.ts:76, 93` | 2 | 中: Bug 5 修复点 | +| `bigscreen/construct.ts:269` | 1 | 低: 内部校验, 'empty' 文案太简陋 | +| `user/auth-list.ts:45, batch-state.ts:24` | 2 | 低: 参数校验 | + +### 类别 4: TODO / FIXME / XXX 注释 — **仅 3 处** + +真实未实现 TODO: + +| 位置 | 内容 | 严重度 | +|------|------|--------| +| `form/codegen.ts:17, 1008` | `--auto-menu` 未实现 (CLI help 暴露 "(TODO)") | 中: 用户可见 | +| `dm/drop.ts:7` | 表 drop 缺 TTY 拦截 (`双人工确认`) | 中: destructive 防御缺失 | + +搜索方法: `grep -rnE "TODO|FIXME|HACK" --include="*.ts"` 配合注释过滤. FIXME/HACK 0 处. + +### 类别 5: 重复 boilerplate + +#### 5a. `addOutputOptions(cmd)` helper 覆盖不全 (38 文件手写) + +`_output_filter.ts:66-70` 提供 `addOutputOptions(cmd)` 一行注入 --verbose + --json. 但 38 个文件仍手写 (覆盖 36 子模块). + +**仅 4 个子模块用了 helper**: datasource (4 文件) / integration (3 文件) / storage (2 文件) / dm/fields.ts. + +**手写案例**: form/list.ts:36-37 / form/codegen.ts:629 / form/audit.ts:431 / schedule/create.ts:47-48 / schedule/list.ts:32 / role/* / portal/* / bigscreen/* / workflow/* 11 文件 / di/* / print/* / report/* / monitor/* / dict/* / menu/* / user/* / app/login+context+create+clear / org/* / msg/* / storage/* (除 helper 覆盖). + +文案不统一: "原始 JSON 输出" / "原始 JSON" / "JSON 输出 (供脚本处理)" / "原始 JSON 输出 (推荐 AI 用)" 等混用. + +#### 5b. per-module `_validate.ts` 重复定义 `interface ValidationError / StepValidation` + +`_error_codes.ts:238` 已有 canonical `ValidationError { field?, message, code? }`. 但 **18 个 module 的 `_validate.ts` 都**重新定义**这份 interface, 注释里明确写 "复刻 _error_codes.ts". + +代表: +- `dict/_validate.ts:22-35` / `datasource/_validate.ts:26-37` / `form/_validate.ts:16-31` / `menu/_validate.ts:32-48` +- `role/_validate.ts:29-42` / `workflow/_validate.ts:25-` / `di/_validate.ts:21, 28` +- `bigscreen/_validate.ts` / `org/_validate.ts` / `print/_validate.ts` / `report/_validate.ts` +- `user/_validate.ts` / `integration/_validate.ts` / `schedule/_validate.ts` +- `dm/_validate.ts` / `storage/_validate.ts` / `msg/_validate.ts` / `portal/_validate.ts` + +**风险**: 任何 ValidationError 字段未来改动, 漏改 18 处编译能过但运行时类型不匹配. + +#### 5c. `printCommandEnd({result:'failure', ...})` 失败收口样板重复 + +**30+ 处手写 7-8 行**: 错误构造 → log.error → printCommandEnd (含 fixes/duration_ms) → process.exit(1). + +代表案例: +- `datasource/create.ts:80-92 (validation) + 121-133 (backend)` +- `portal/create.ts:166-182 + 203-216 + 249-264 + 286-304` (4 处) +- `di/create.ts:94-108 + 128-144 + 160-174 + 228-244` (4 处) +- `bigscreen/construct.ts:148-161 + 218-223 + 227-231 + 280-286` +- `schedule/create.ts:78-91 + 108-122 + 127-129` +- `menu/create.ts:151, 158, 208, 255, 276, 377, 408, 652` +- `workflow/create.ts:140, 155, 182, 260, 263, 266, 278, 319, 472` +- `form/codegen.ts:524-545` (validation fail 4 处连续) +- ... 共 30+ 处 + +**无 helper 收口** — 应该抽 `wrapCommand(handler)` 或 `failWith(opts, error)`. + +#### 5d. `history_bak` DB 备份名串拼接 + +**仅 `app/clear.ts` 1 文件重复 6+ 处**: +- L64 常量 `HISTORY_BAK_DB = 'history_bak'` +- L334/401/409/716/770/782/847/855/891/899: 模板字符串 ``\`${HISTORY_BAK_DB}\`.\`D${dbTs}-${name}\` `` + +app/init.ts:16, 78 仅注释提及. **未封装为 `bakName(dbTs, tableName)` helper**. 未来加 `--backup-prefix` 或 PG/MySQL 引号转义需重写多处. + +## 优先级路线 + +| 优先级 | 工作量 | 价值 | 内容 | +|--------|--------|------|------| +| **P0** | 1 h | **极高** | 加 `wrapCommand(handler)` helper 收口 5c (一处改, 后续 30+ 文件可批量复用) | +| **P1** | 0.5 h | 高 | (a) `storage/info.ts:38` 同模块分叉修复 (1 文件); (b) `dm/drop.ts` TTY 拦截 (1 文件) | +| **P2** | 2-3 h | 高 | 大批量 `printCommandEnd + try/catch` 改造 (25+ 高严重度文件, portal/di/bigscreen/datasource/schedule/role 6 个 + form codegen/menu/dict/workflow 等) | +| **P3** | 1 h | 中 | 18 个 per-module `_validate.ts` 改 `import { ValidationError } from '../_error_codes.ts'` (类型分叉修复) | +| **P4** | 1 h | 中 | `addOutputOptions(cmd)` helper 迁移 38 文件 (L1 stdout 文案统一) | +| **P5** | 4+ h | 中低 | 360 console.log 替换为 log helper + 37 throw new Error 统一 DacliError | +| **P6** | 大坑 | 极高 | 350+ 裸 `process.exit` 全部走 try/catch+throw 链路 (单 session 不可能, 留独立 ADR) | + +## Cross-refs + +- **CLAUDE.md §"修改 dacli 前必读"**: 任何后续 session 启动前必读, 本 ADR 优先级路线让计划明确 +- **dacli/README.md §"5 大铁律"**: 第 5 条 "不绕过 dacli 调 curl" — 源码层改造不违反, 但需注意新加 helper 不要破坏现有 schema 校验 +- **dacli/docs/decisions/0014-app-clear-docs-coverage.md**: 同 session 前序 ADR, 范围已收紧到 docs/{app} + ssw-common +- **dacli/src/commands/_output_filter.ts:104** (`printCommandEnd`): P0 wrapCommand helper 应基于此收口 +- **dacli/src/commands/_auto_fix.ts** (`runCommandAutoFix`): 同模式 fix 流水线可借鉴 +- **dacli/src/commands/_error_codes.ts:238** (ValidationError): P3 改 import 来源 +- **dacli/src/core/types.ts:57** (DacliError): P5 全部 throw new Error 统一目标 +- **dacli/src/core/log.ts**: P5 console.log 替换目标 +- **本 session 已完成**: 4 commits dacli 仓库 (bcf874d + 60adaab + f7bc8d5 + cab1bb4 + 1e2a271) + 2 commits .claude 仓库 (48f66ab + 773cc98) +- **触发后续**: 任一优先级 P0-P4 完成时更新本 ADR 状态 ("Superseded by 0016-...") 或新增 ADR