# 结构化日志系统（稳定性诊断）设计

- 日期：2026-06-24
- 状态：设计（已口头确认，待实现）
- 范围：v1 聚焦**稳定性诊断**——捕获错误与崩溃（尤其 `/api/export-excel` 的 OOM 路径）。

## 1. 背景与问题

当前服务端只有 3 处 ad-hoc `console.error/warn`，且只记 `err.message`（**丢失堆栈**）。
输出被 NSSM 原样灌进 `logs/stdout.log`/`stderr.log`，追加、不轮转——导致崩溃堆栈堆积、不可检索。
诊断 export 的 OOM（单次全量导出峰值 ~1.3GB 堆）时，缺少"哪次导出、多少行、耗时多久"的现场。

约束：114 不通外网 → 自包含文件日志，排除 SaaS；单 Node 进程、内部工具、低流量。

## 2. 目标

在不改动业务逻辑的前提下，新增一层**结构化、分级、同步落盘、自带轮转**的应用日志，
让"出错/崩溃时能查到完整现场"。

## 3. 非目标（YAGNI）

- 不做请求级全量审计 / 用户行为追踪（属"运行可见性/审计"，非 v1）。
- 不做客户端（浏览器）错误采集。
- 不做集中式日志聚合（ELK 等）。
- 不重构 `dbConfig` 两处重复（不属于本次范围）。

## 4. 方案

### 4.1 选型：log4js `fileSync`

- **`fileSync` appender 同步写**（`fs.appendFileSync`）→ 进程 OOM/被杀前日志已落盘，满足崩溃诊断刚需。
- 内置按大小轮转（`maxLogSize` + `backups`），无需手写。
- 分级、category、pattern layout，成熟轻量。
- 引入依赖 `log4js`（约 ~3 个小间接依赖）。

### 4.2 分层

```
应用日志（新增）  log4js fileSync → logs/app/app.log（同步 + 10MB×5 轮转）  ← 查错误/崩溃
框架/致命日志     NSSM 的 stdout/stderr（Next 启动、V8 崩溃栈）            ← 兜底，保持不动
```

### 4.3 logger 模块 `src/server/logger.ts`

```ts
import log4js from "log4js";

log4js.configure({
  appenders: {
    app: {
      type: "fileSync",
      filename: "logs/app/app.log",
      maxLogSize: 10 * 1024 * 1024, // 10MB
      backups: 5,
      layout: { type: "pattern", pattern: "[%d{ISO8601}] [%p] [%c] %m" },
    },
  },
  categories: { default: { appenders: ["app"], level: "info" } },
});

export const apiLogger = log4js.getLogger("api");
export const exportLogger = log4js.getLogger("export");
```

- `filename` 用相对路径，`next start`（NSSM 的 `AppDirectory`）/`next dev` 的 cwd 均为项目根，解析正确。
- 输出样例：
  `[2026-06-24T10:30:01.123] [ERROR] [export] Excel export failed · rows=33142 · dur=18234ms · RangeError: Invalid string length\n    at ...`

### 4.4 记什么（诊断聚焦，不给常规成功查询加噪）

| 事件 | 级别 | 字段 |
|----|----|----|
| production-data 查询失败 | ERROR | workshopNo、完整堆栈 |
| production-data 慢查询（>3s） | WARN | workshopNo、耗时 |
| export 锁被并发占用（429） | WARN | — |
| export 锁超时回收 | WARN | 取代现有 `console.warn` |
| export 开始 / 成功 | INFO | rows、bytes、耗时（OOM 诊断核心线索） |
| export 失败 | ERROR | 完整堆栈、rows、耗时 |
| 进程启动 | INFO | logger ready |

要点：现有 3 处 `console.error/warn` **全部替换**为 logger 调用；`err.message` **升级为完整 `err.stack`**。

### 4.5 路由改造

- `production-data/route.ts`：catch 分支用 `apiLogger.error(...)` 带栈 + workshopNo；查询耗时 >3s 时 `apiLogger.warn(...)`。
- `export-excel/route.ts`：锁占用/回收 `exportLogger.warn`；开始记 `rows`、成功记 `rows/bytes/dur`、失败 `exportLogger.error` 带栈 + dur；保留现有返回逻辑不变。
- 用一个纯函数 `formatError(err): string` 统一提取 `err.stack ?? String(err)`，便于单测。

### 4.6 涉及文件

| 文件 | 动作 |
|----|----|
| `src/server/logger.ts` | 新增（log4js 配置 + 导出 logger + `formatError`） |
| `src/app/api/production-data/route.ts` | 改：失败 ERROR（带栈）+ 慢查询 WARN |
| `src/app/api/export-excel/route.ts` | 改：锁/开始/成功/失败 全套日志（带栈） |
| `package.json` | +`log4js` 依赖 |

## 5. 边界情况

- **OOM 落盘**：fileSync 同步写，每行即时 flush，崩溃前已写入。
- **首次写入**：log4js 自动创建 `logs/app/` 目录与文件。
- **轮转**：达到 `maxLogSize` 自动滚动为 `app.log.1..5`，更早的删除。
- **本地 dev vs 114 生产**：均写入项目根下 `logs/app/app.log`；不影响 NSSM 的 stdout/stderr。

## 6. 测试

- 纯函数 `formatError(err)`：用 vitest 单测（Error→stack、非 Error→字符串、null/undefined 安全）。
- 路由日志为副作用，以**手验**为准：本地断开 DB 触发 production-data 失败 → 确认 `logs/app/app.log` 有 ERROR 带栈行；触发一次导出 → 确认 INFO（rows/bytes/dur）/ 失败 ERROR 行。
- 不引入 log4js 行为的单测（第三方，按项目惯例不测）。

## 7. 部署注意

新增 `log4js` 依赖，114 部署须执行 `npm install`（CLAUDE.local.md 第 3 步），再 `next build` + 重启。