From 7cdc8187cced42188a07d63c762453eedd009f91 Mon Sep 17 00:00:00 2001 From: ssw Date: Tue, 21 Jul 2026 16:38:00 +0800 Subject: [PATCH] =?UTF-8?q?Revert=20"docs(0015-source-leftovers):=20?= =?UTF-8?q?=E6=BA=90=E7=A0=81=205=20=E7=B1=BB=E9=81=97=E7=95=99=E6=B8=85?= =?UTF-8?q?=E5=8D=95=20+=20P0-P6=20=E4=BC=98=E5=85=88=E7=BA=A7=E8=B7=AF?= =?UTF-8?q?=E7=BA=BF"?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This reverts commit 86d9dac83dca54c25b62d9d342f7aa3a99892725. --- docs/decisions/0015-source-leftovers.md | 179 ------------------------ 1 file changed, 179 deletions(-) delete mode 100644 docs/decisions/0015-source-leftovers.md diff --git a/docs/decisions/0015-source-leftovers.md b/docs/decisions/0015-source-leftovers.md deleted file mode 100644 index 14a156d..0000000 --- a/docs/decisions/0015-source-leftovers.md +++ /dev/null @@ -1,179 +0,0 @@ -# 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