@ranger1/dx 0.1.85 → 0.1.87

package/codex/skills/error-handling-audit-fixer/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: error-handling-audit-fixer
+description: Use when backend、NestJS、领域异常治理或错误处理审查中，需要检查业务代码是否绕过 DomainException / ErrorCode 体系，区分生产代码与 E2E 测试中的异常写法，识别直接抛出 BadRequestException、HttpException、Error 或直接返回中文 DomainException，并在项目缺少统一异常基础设施时给出补齐路径。
+---
+
+# 错误处理规范检查与修复建议
+
+## 概览
+
+先判断项目是否已经具备统一错误处理基础设施，再扫描业务代码是否绕过 `DomainException` / `ErrorCode` 体系。默认只输出审计结果和修复建议，不自动改代码；只有用户明确要求时才进入自动修复。
+
+## 快速开始
+
+1. 先审计生产代码：
+
+```bash
+CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
+python "$CODEX_HOME/skills/error-handling-audit-fixer/scripts/error_handling_audit.py" \
+  --workspace "$PWD" \
+  --scope src
+```
+
+2. 再按需审计 E2E 或全量：
+
+```bash
+python "$CODEX_HOME/skills/error-handling-audit-fixer/scripts/error_handling_audit.py" \
+  --workspace "$PWD" \
+  --scope all \
+  --output-json /tmp/error-handling-audit.json
+```
+
+3. 当项目尚未具备 `DomainException` / `ErrorCode` / 领域异常目录等基础设施时，先阅读 [references/foundation-bootstrap.md](./references/foundation-bootstrap.md) 再决定是否补齐。
+
+4. 当项目基础设施齐全但出现违规抛错时，按 [references/error-handling-standard.md](./references/error-handling-standard.md) 给出替换建议；如用户明确要求，才实施自动修复。
+
+5. 当结果里 `e2e/raw-error` 数量很大时，不要直接把它和生产代码风险混在一起汇报；先给 `src` 结论，再决定是否单独治理 `e2e`。
+
+## 执行流程
+
+1. 默认先扫描 `apps/backend/src`，只有在用户明确要求或需要评估测试债务时再扫描 `apps/backend/e2e`。
+2. 先判断基础设施状态：
+   - 是否存在 `DomainException`
+   - 是否存在 `ErrorCode`
+   - 是否存在领域异常目录或模块异常类
+   - 是否存在全局异常过滤器或结构化错误输出链路
+3. 再识别四类问题：
+   - 直接实例化 Nest 标准异常，如 `BadRequestException`、`HttpException`
+   - `throw new Error(...)` 或 `Promise.reject(new Error(...))`
+   - 直接 `new DomainException(...)` 但 payload 中未显式带 `code`
+   - `DomainException` 直接返回中文 message
+4. 对每个命中项给出修复建议，优先级固定如下：
+   - 优先复用现有模块异常类
+   - 其次建议在模块 `exceptions/` 目录新增领域异常类
+   - 最后才允许直接使用 `DomainException`，且必须补齐 `code` 与 `args`
+5. 若基础设施缺失，不直接把全部命中项定性为“应立刻改业务代码”，而是先输出“需补齐基础设施”的诊断与最小落地路径。
+6. 只有在用户明确说“自动修复”“直接改”或等价表述时，才进入落代码阶段。
+7. 若脚本结果与实际代码不一致，必须抽样打开命中文件复核，不要把脚本结果当成绝对真相。
+
+## 审计命令
+
+项目具备 ripgrep 时，可先用下列命令快速复核：
+
+```bash
+rg "new (BadRequestException|UnauthorizedException|ForbiddenException|NotFoundException|HttpException|InternalServerErrorException)\(" \
+  apps/backend/src apps/backend/e2e \
+  --glob '!*spec.ts' \
+  --glob '!*exception.ts' \
+  --glob '!apps/backend/src/common/filters/**' \
+  --glob '!apps/backend/src/main.ts'
+```
+
+```bash
+rg "new Error\(" apps/backend/src apps/backend/e2e --glob '!*spec.ts'
+```
+
+```bash
+rg "new DomainException\([^)]*$" -A3 apps/backend/src
+```
+
+```bash
+rg "DomainException\([^)]*[\u4e00-\u9fa5]" apps/backend/src apps/backend/e2e \
+  --glob '!*spec.ts' \
+  --glob '!apps/backend/src/common/exceptions/**'
+```
+
+如果只想快速看生产代码，可优先改成：
+
+```bash
+python "$CODEX_HOME/skills/error-handling-audit-fixer/scripts/error_handling_audit.py" \
+  --workspace "$PWD" \
+  --scope src
+```
+
+如果只想看 E2E 存量问题，可改成：
+
+```bash
+python "$CODEX_HOME/skills/error-handling-audit-fixer/scripts/error_handling_audit.py" \
+  --workspace "$PWD" \
+  --scope e2e
+```
+
+## 修复准则
+
+### 1. 优先复用现有领域异常
+
+- 若模块 `exceptions/` 已有语义匹配的异常类，直接复用。
+- 不要把已可表达为领域异常的问题继续保留成裸 `BadRequestException('字符串')`。
+
+### 2. 缺少模块异常时新增领域异常类
+
+- 在模块 `exceptions/` 下新增异常类。
+- 异常类继承统一 `DomainException`。
+- 构造函数中显式指定 `ErrorCode`。
+- 把上下文放进 `args`，不要把业务文案直接写死到 message。
+- 为新增异常补最小单测。
+
+### 3. 临时直接使用 DomainException
+
+- 仅在尚未抽出专用异常类、但当前修复必须继续推进时使用。
+- payload 中必须显式包含 `code`。
+- `args` 中必须保留排障所需上下文。
+
+### 4. 基础设施缺失时的判断
+
+- 如果仓库里根本没有 `DomainException` 或 `ErrorCode`，优先建议补基础设施，不要直接发散式新增几十个本地异常实现。
+- 如果已有 `DomainException` 但没有统一 `ErrorCode`，先统一错误码来源，再扩展模块异常。
+- 如果已有异常类与错误码，但缺少结构化输出链路，优先补过滤器或输出映射，保证 `code`、`args`、`requestId` 可稳定透出。
+
+## 输出要求
+
+执行这个技能时，最终输出至少包含：
+
+1. 基础设施状态
+2. 命中文件清单
+3. 每个问题的类型、定位与建议替换方式
+4. 是否可复用现有领域异常
+5. 是否需要先补齐基础设施
+6. 若用户要求自动修复，列出拟修改文件、验证方式与剩余风险
+
+补充要求：
+
+7. 明确区分 `src` 与 `e2e` 命中数量，避免测试噪音淹没生产代码风险
+8. 标注哪些命中是脚本结果、哪些已经过源码抽样复核
+9. 若脚本疑似误报，要在结论里明确说明“脚本规则限制”而不是直接要求改代码
+
+## 资源
+
+- 扫描脚本：`scripts/error_handling_audit.py`
+- 规范参考：`references/error-handling-standard.md`
+- 基础设施补齐指南：`references/foundation-bootstrap.md`

package/codex/skills/error-handling-audit-fixer/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "错误处理规范检查"
+  short_description: "按 src 与 e2e 分开审计后端异常是否绕过 DomainException 与 ErrorCode 体系"
+  default_prompt: "使用 $error-handling-audit-fixer 先审计 backend src，再按需审计 e2e，检查错误处理是否绕过 DomainException / ErrorCode 体系，并在基础设施缺失时给出补齐建议。"
+
+policy:
+  allow_implicit_invocation: true

package/codex/skills/error-handling-audit-fixer/references/error-handling-standard.md

@@ -0,0 +1,152 @@
+# 错误处理规范参考
+
+## 目标
+
+后端业务代码抛出异常时，应统一接入 `DomainException` / `ErrorCode` 体系，避免直接抛出字符串化的 Nest 标准异常或裸 `Error`，以保证：
+
+- 前端可稳定依赖 `error.code`
+- 日志具备结构化 `args`
+- 请求链路可透出 `requestId`
+- 模块内异常语义可复用
+
+## 默认排除范围
+
+- `apps/backend/src/common/exceptions/**/*.ts`
+- `apps/backend/src/common/filters/**/*.ts`
+- `apps/backend/src/main.ts`
+- `*.spec.ts`
+
+说明：
+
+- 领域异常定义文件允许继承和封装 Nest 异常能力
+- 全局过滤器允许直接接触 Nest 异常
+- `main.ts` 中的 `ValidationPipe` 自定义异常通常属于框架接线层
+
+## 检测规则
+
+### 1. 直接实例化 Nest 标准异常
+
+命中对象：
+
+- `BadRequestException`
+- `UnauthorizedException`
+- `ForbiddenException`
+- `NotFoundException`
+- `HttpException`
+- `InternalServerErrorException`
+
+通常表示业务语义绕过了领域异常体系。
+
+### 2. 直接创建 Error
+
+命中对象：
+
+- `throw new Error(...)`
+- `Promise.reject(new Error(...))`
+
+这类写法通常无法提供稳定错误码，也不利于结构化日志。
+
+### 3. DomainException 缺少 code
+
+命中对象：
+
+- `new DomainException(...)` 但 payload 未显式声明 `code`
+
+即使暂时不抽专用异常类，也必须提供 `ErrorCode`。
+
+### 4. DomainException 直接返回中文 message
+
+命中对象：
+
+- `DomainException(...)` 中直接出现中文 message
+
+后端不应直接决定面向用户的中文文案。优先返回稳定错误码，由前端或上层映射展示。
+
+## 修复优先级
+
+1. 复用现有模块异常类
+2. 新增模块领域异常类
+3. 临时直接使用 `DomainException`
+
+## 正反例
+
+### 错误示例
+
+```typescript
+throw new BadRequestException('余额不足, 请充值')
+```
+
+```typescript
+throw new Error('wallet not found')
+```
+
+```typescript
+throw new DomainException('余额不足')
+```
+
+### 正确示例：复用模块异常
+
+```typescript
+throw new InsufficientBalanceException({
+  currentBalance: wallet.available,
+  requestedAmount: dto.amount,
+  isFromFreeze: false,
+})
+```
+
+### 正确示例：临时直接使用 DomainException
+
+```typescript
+throw new DomainException('wallet.insufficient_balance', {
+  code: ErrorCode.WALLET_INSUFFICIENT_BALANCE,
+  args: {
+    currentBalance: wallet.available,
+    requestedAmount: dto.amount,
+  },
+})
+```
+
+## 建议替换策略
+
+### BadRequestException
+
+- 参数校验类错误：优先看是否属于框架输入校验层
+- 业务校验类错误：优先替换为模块领域异常
+
+### NotFoundException
+
+- 若资源查找失败属于明确业务语义，替换为 `XxxNotFoundException`
+
+### ForbiddenException / UnauthorizedException
+
+- 若表达的是业务权限或业务身份限制，替换为模块异常
+- 若是认证框架本身的接入层，可保留在边界层
+
+### HttpException
+
+- 一般视为待治理项，优先改成领域异常或统一异常封装
+
+### Error
+
+- 原则上应全部迁移到领域异常或基础设施异常
+
+## 输出建议模板
+
+每个命中项建议包含：
+
+- 文件路径
+- 行号
+- 问题类型
+- 当前写法
+- 推荐替换方式
+- 是否可复用已有异常类
+- 若不可复用，建议新增的异常类名
+
+## 何时不要直接修
+
+- 仓库尚未定义 `DomainException`
+- 仓库没有统一 `ErrorCode`
+- 现有全局过滤器不会透出 `code` / `args` / `requestId`
+- 当前模块不存在异常目录，且团队尚未确认命名规范
+
+遇到以上情况，先转向基础设施补齐。

package/codex/skills/error-handling-audit-fixer/references/foundation-bootstrap.md

@@ -0,0 +1,85 @@
+# 错误处理基础设施补齐指南
+
+## 适用场景
+
+当项目执行错误处理规范审计时，若发现缺少以下任一基础设施，应先补齐，再推进大规模业务修复：
+
+- `DomainException`
+- `ErrorCode`
+- 领域异常目录约定
+- 全局异常过滤器或统一错误输出链路
+
+## 最小可用基础设施
+
+### 1. DomainException
+
+需要具备：
+
+- 统一异常基类
+- 接收稳定 `messageKey` 或内部 message
+- payload 至少支持：
+  - `code`
+  - `args`
+  - `cause`
+  - 可扩展的 `meta`
+
+### 2. ErrorCode
+
+需要具备：
+
+- 集中定义的枚举或常量集
+- 可按模块分组命名
+- 命名稳定，不直接耦合中文文案
+
+示例命名：
+
+- `WALLET_INSUFFICIENT_BALANCE`
+- `USER_NOT_FOUND`
+- `AUTH_LOGIN_EXPIRED`
+
+### 3. 模块异常目录
+
+推荐：
+
+- 每个业务模块使用 `exceptions/` 目录
+- 每个异常类表达单一明确业务语义
+- 不在 Service 里散落大量 `new DomainException(...)`
+
+### 4. 全局异常过滤器
+
+输出应至少包含：
+
+- `code`
+- `message`
+- `args`
+- `requestId`
+- `timestamp`
+- `path`
+
+如果现有过滤器只输出字符串 message，需要先升级输出结构。
+
+## 推荐补齐顺序
+
+1. 建立 `ErrorCode`
+2. 建立 `DomainException`
+3. 建立全局异常过滤器输出契约
+4. 在一个模块内先试点 1 到 2 个领域异常类
+5. 再批量治理业务代码中的裸异常
+
+## 迁移原则
+
+- 先收敛契约，再批量替换调用点
+- 先在高频模块试点，再扩散到全仓
+- 保持旧错误响应的兼容窗口，避免前端瞬间失配
+- 中文文案不要直接塞进后端异常 message，优先使用 code + args
+
+## 自动修复前的门槛
+
+只有在以下条件满足时，才适合让 AI 直接批量修代码：
+
+- `DomainException` 已可复用
+- `ErrorCode` 已有统一来源
+- 全局过滤器已能稳定透出结构化字段
+- 模块异常类命名规则已经明确
+
+否则默认只给建议，不默认改业务代码。