Revert "docs(0015-source-leftovers): 源码 5 类遗留清单 + P0-P6 优先级路线"

This reverts commit 86d9dac83d.
This commit is contained in:
ssw committed 2026-07-21 16:38:00 +08:00
1 parent 86d9dac83d
commit 7cdc8187cc
1 file changed
-179
-179
View File
@@ -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