## [ERR-20260417-001] uuid v13 ESM-only 与 ts-node/CommonJS require 冲突

**日期**: 2026-04-17
**类别**: 构建/运行时依赖
**严重度**: 中（阻断后端以 node/ts-node 直启）

### 问题描述

以 `npx ts-node -r tsconfig-paths/register src/main.ts` 或 `node dist/main.js` 启动后端时报错：

```
Error [ERR_REQUIRE_ESM]: require() of ES Module
  .../node_modules/uuid/dist-node/index.js
  from .../src/core/observability/audit/audit.service.ts not supported.
```

### 根本原因

`backend/package.json` 依赖 `uuid: ^13.0.0`（pure ESM），但后端代码用 `import { v4 as uuidv4 } from 'uuid'` 被 tsc/ts-node 编译为 CommonJS `require('uuid')`，v10+ 的 uuid 包不再提供 CJS 入口，直接触发 `ERR_REQUIRE_ESM`。

### 为什么某些场景能跑

- **Jest 集成测试**：ts-jest 使用独立的模块解析器，能透明处理 ESM-only 包。L1 65/65 正常通过。
- **NestJS 正常 dev**：`npm run start:dev` 经 nest CLI 路径时通常 OK（原因待查，但实测不总是）。
- **直接 `ts-node src/main.ts` / `node dist/main.js`**：报 ERR_REQUIRE_ESM 崩溃。

### 绕行方案

1. **跑 L1 集成测试不受影响**，直接用 `bash testing/scripts/run-backend-integration.sh`
2. **必须直启测试后端时**：
   - 方案 A：把代码中 `import { v4 as uuidv4 } from 'uuid'` 改为 `import { randomUUID } from 'crypto'`（Node 内置，无 ESM 问题）
   - 方案 B：在 `backend/package.json` 加 `"overrides": { "uuid": "^9.0.1" }` 锁到兼容 CJS 的旧版
   - 方案 C：全项目改 `"type": "module"` 并配 ts-node ESM loader（代价很大）

### 预防措施

- 升级 uuid（或其他 ESM-only 包）时先确认 `tsconfig.json` 的 `module` 设置和 ts-node 启动方式
- 在 `package.json` 里固定 `uuid: ^9.x` 直到全项目切 ESM

### Metadata
- Reproducible: yes（在当前 uuid v13.0.0 下 `node dist/main.js` 必现）
- Related Files: backend/src/core/observability/audit/audit.service.ts, backend/package.json