Add implementation plan: structured logging (log4js fileSync)

2026-06-24 13:32:18 +08:00
parent 2bd177faf6
commit e495a9b142
1 changed files with 454 additions and 0 deletions
--- a/docs/superpowers/plans/2026-06-24-structured-logging.md
+++ b/docs/superpowers/plans/2026-06-24-structured-logging.md
@@ -0,0 +1,454 @@
+# 结构化日志（log4js fileSync）Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 给生产数据查询工具加上结构化、分级、同步落盘、自带轮转的服务端日志，聚焦错误与崩溃诊断（尤其 export OOM）。
+
+**Architecture:** log4js 的 `fileSync` appender（同步写 = 崩溃前可靠落盘）写到 `logs/app/app.log`（10MB×5 轮转），由 `src/server/logger.ts` 单例配置；纯函数 `formatError` 抽到 `log-format.ts` 单测；两个 API 路由替换 `console.*` 为带完整堆栈与耗时字段的 logger 调用。NSSM 的 stdout/stderr 保持不动作兜底。
+
+**Tech Stack:** Next 16.2.9（route handlers，server-only）、log4js 6.9.1（新增依赖）、vitest（node 环境，仅测纯逻辑）。
+
+## Global Constraints
+
+- 新增依赖 **log4js@6.9.1**，用其 **`fileSync`** appender（同步写）。部署到 114 时**必须** `npm install`。
+- logger 仅在服务端（API route）使用，依赖 Node `fs`；不得被客户端组件引入。
+- 日志文件：项目根下 `logs/app/app.log`，`maxLogSize=10MB`、`backups=5`，pattern 布局 `[%d{ISO8601}] [%p] [%c] %m`，默认级别 `info`。
+- 测试：vitest（`environment: node`，匹配 `src/**/*.test.ts`）。**仅** `formatError` 做单测；路由日志为副作用，手验。
+- 不改 `dbConfig` 重复、不改业务返回逻辑、不动 NSSM stdout/stderr。
+- commit message 用英文；实现后启动本地 `next dev` 供验证，**通过后再部署**。
+
+## File Structure
+
+| 文件 | 责任 | 动作 |
+|------|------|------|
+| `src/server/log-format.ts` | 纯函数 `formatError(err)`：提取堆栈/字符串 | 新增 |
+| `src/server/log-format.test.ts` | `formatError` 单测 | 新增 |
+| `src/server/logger.ts` | log4js configure（fileSync）+ 导出 `apiLogger`/`exportLogger` + 再导出 `formatError` | 新增 |
+| `src/app/api/production-data/route.ts` | 失败 ERROR（带栈+workshopNo+dur）、慢查询 WARN(>3s) | 修改 |
+| `src/app/api/export-excel/route.ts` | 锁占用/回收 WARN、开始/成功 INFO(rows/bytes/dur)、失败 ERROR(带栈+dur) | 修改 |
+| `package.json` | +`log4js` | 修改 |
+
+---
+
+## Task 1: log4js 依赖 + `formatError`（TDD）+ logger 模块
+
+**Files:**
+- Create: `src/server/log-format.ts`
+- Test: `src/server/log-format.test.ts`
+- Create: `src/server/logger.ts`
+- Modify: `package.json`（`npm install log4js`）
+
+**Interfaces:**
+- Produces:
+  - `formatError(err: unknown): string`（来自 `log-format.ts`，`logger.ts` 再导出）。
+  - `apiLogger`、`exportLogger`：log4js Logger 实例（category 分别为 `"api"`、`"export"`）。
+
+- [ ] **Step 1: 安装依赖**
+
+Run: `npm install log4js`
+Expected: `added N packages`，`package.json` 出现 `"log4js": "^6.9.1"`。
+
+- [ ] **Step 2: 写失败测试**
+
+Create `src/server/log-format.test.ts`:
+
+```ts
+import { describe, it, expect } from "vitest";
+import { formatError } from "./log-format";
+
+describe("formatError", () => {
+  it("returns stack for Error", () => {
+    const e = new Error("boom");
+    expect(formatError(e)).toBe(e.stack);
+  });
+  it("falls back to message when stack missing", () => {
+    const e = new Error("boom");
+    e.stack = undefined as unknown as string;
+    expect(formatError(e)).toBe("boom");
+  });
+  it("stringifies non-Error primitives", () => {
+    expect(formatError("oops")).toBe("oops");
+    expect(formatError(42)).toBe("42");
+  });
+  it("handles null / undefined", () => {
+    expect(formatError(null)).toBe("Unknown error");
+    expect(formatError(undefined)).toBe("Unknown error");
+  });
+});
+```
+
+- [ ] **Step 3: 运行测试确认失败**
+
+Run: `npx vitest run src/server/log-format.test.ts`
+Expected: FAIL — `Cannot find module './log-format'`。
+
+- [ ] **Step 4: 写 `formatError` 实现**
+
+Create `src/server/log-format.ts`:
+
+```ts
+/**
+ * 把任意错误/值格式化为带堆栈的字符串，用于日志记录。
+ * - Error：优先 stack，缺则 message
+ * - null/undefined：'Unknown error'
+ * - 其它：String(value)
+ */
+export function formatError(err: unknown): string {
+  if (err instanceof Error) return err.stack || err.message;
+  if (err === null || err === undefined) return "Unknown error";
+  return String(err);
+}
+```
+
+- [ ] **Step 5: 运行测试确认通过**
+
+Run: `npx vitest run src/server/log-format.test.ts`
+Expected: PASS（4 用例）。
+
+- [ ] **Step 6: 写 logger 模块**
+
+Create `src/server/logger.ts`:
+
+```ts
+import log4js from "log4js";
+
+// fileSync = 同步写：进程 OOM/被杀前日志已落盘，满足崩溃诊断刚需。
+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 { formatError } from "./log-format";
+
+export const apiLogger = log4js.getLogger("api");
+export const exportLogger = log4js.getLogger("export");
+```
+
+- [ ] **Step 7: 跑全量测试 + lint**
+
+Run: `npm test`
+Expected: 全部 PASS（原 `table-filters`/`record-detail` + 新 `log-format`）。
+
+Run: `npm run lint`
+Expected: 0 error（`log-format.ts` 被 eslint 覆盖；`logger.ts` 仅在服务端被路由引用，不进客户端）。
+
+- [ ] **Step 8: 提交**
+
+```bash
+git add package.json package-lock.json src/server/log-format.ts src/server/log-format.test.ts src/server/logger.ts
+git commit -m "Add log4js fileSync logger module and formatError helper"
+```
+
+---
+
+## Task 2: 给 `/api/production-data` 接日志
+
+**Files:**
+- Modify: `src/app/api/production-data/route.ts`
+
+**Interfaces:**
+- Consumes: Task 1 的 `apiLogger`、`formatError`（`import { apiLogger, formatError } from "../../../server/logger"`）。
+
+- [ ] **Step 1: 改 import 与加常量**
+
+在文件顶部 import 区，`import sql from "mssql";` 之后加：
+
+```ts
+import { apiLogger, formatError } from "../../../server/logger";
+
+const SLOW_QUERY_MS = 3000;
+```
+
+- [ ] **Step 2: 计时 + 失败带栈 + 慢查询 WARN**
+
+把 `export async function GET(request: NextRequest) {` 内的 try/catch/finally 改为（`dbConfig` 不变，中间序列化逻辑不变，仅在外围加计时与日志）：
+
+```ts
+  let pool: sql.ConnectionPool | undefined;
+  const t0 = Date.now();
+  try {
+    pool = await sql.connect(dbConfig);
+    const result = await pool
+      .request()
+      .input("车间号", sql.NVarChar(50), workshopNo)
+      .execute("[productionContractData].[sp_压力表合同生产数据_按车间号]");
+
+    const recordset = result.recordset;
+    if (!recordset || recordset.length === 0) {
+      return NextResponse.json({ columns: [], data: [], total: 0 });
+    }
+
+    const columns = Object.keys(recordset[0]);
+    const data = recordset.map((row: Record<string, unknown>) => {
+      const serialized: Record<string, unknown> = {};
+      for (const key of columns) {
+        const val = row[key];
+        if (val instanceof Date) {
+          serialized[key] = val.toISOString().split("T")[0];
+        } else {
+          serialized[key] = val;
+        }
+      }
+      return serialized;
+    });
+
+    const dur = Date.now() - t0;
+    if (dur > SLOW_QUERY_MS) {
+      apiLogger.warn(`slow query · workshopNo=${workshopNo} · dur=${dur}ms · rows=${data.length}`);
+    }
+    return NextResponse.json({ columns, data, total: data.length });
+  } catch (err) {
+    const dur = Date.now() - t0;
+    const message = err instanceof Error ? err.message : "Unknown error";
+    apiLogger.error(`query failed · workshopNo=${workshopNo} · dur=${dur}ms · ${formatError(err)}`);
+    return NextResponse.json({ error: message }, { status: 500 });
+  } finally {
+    if (pool) {
+      await pool.close();
+    }
+  }
+```
+
+> 注意：删除原 `console.error("DB query error:", message);`，由 `apiLogger.error(...)` 取代。
+
+- [ ] **Step 3: 测试 + lint**
+
+Run: `npm test && npm run lint`
+Expected: 测试全 PASS、lint 0 error。
+
+- [ ] **Step 4: 提交**
+
+```bash
+git add src/app/api/production-data/route.ts
+git commit -m "Log production-data query failures (with stack) and slow queries"
+```
+
+---
+
+## Task 3: 给 `/api/export-excel` 接日志
+
+**Files:**
+- Modify: `src/app/api/export-excel/route.ts`
+
+**Interfaces:**
+- Consumes: Task 1 的 `exportLogger`、`formatError`（`import { exportLogger, formatError } from "../../../server/logger"`）。
+
+- [ ] **Step 1: 加 import**
+
+`import ExcelJS from "exceljs";` 之后加：
+
+```ts
+import { exportLogger, formatError } from "../../../server/logger";
+```
+
+- [ ] **Step 2: 锁回收 WARN（替换 console.warn）**
+
+把 `acquireExportLock` 里的：
+
+```ts
+  if (exportLocked && Date.now() - exportLockedAt > EXPORT_LOCK_TIMEOUT_MS) {
+    console.warn("Export lock reclaimed after timeout");
+    exportLocked = false;
+  }
+```
+
+改为：
+
+```ts
+  if (exportLocked && Date.now() - exportLockedAt > EXPORT_LOCK_TIMEOUT_MS) {
+    exportLogger.warn("export lock reclaimed after timeout");
+    exportLocked = false;
+  }
+```
+
+- [ ] **Step 3: 429 占用 WARN + 计时 + 成功 INFO + 失败 ERROR**
+
+把 `export async function GET() {` 改为（返回逻辑/锁释放不变，仅加日志与计时）：
+
+```ts
+export async function GET() {
+  if (!acquireExportLock()) {
+    exportLogger.warn("export skipped: another export in progress (429)");
+    return NextResponse.json(
+      { error: "正在导出，请稍候" },
+      { status: 429, headers: { "Retry-After": "3" } }
+    );
+  }
+  const t0 = Date.now();
+  exportLogger.info("export started");
+  let pool: sql.ConnectionPool | undefined;
+  try {
+    pool = await sql.connect(dbConfig);
+    const result = await pool
+      .request()
+      .execute("[productionContractData].[sp_压力表合同生产数据_全部]");
+
+    const recordset = result.recordset;
+    if (!recordset || recordset.length === 0) {
+      exportLogger.warn("export empty: no data");
+      return NextResponse.json({ error: "没有数据可导出" }, { status: 404 });
+    }
+
+    const columns = Object.keys(recordset[0]);
+
+    const workbook = new ExcelJS.Workbook();
+    const sheet = workbook.addWorksheet("压力表合同生产数据");
+
+    // Header row
+    const headerRow = sheet.addRow(columns);
+    headerRow.eachCell((cell) => {
+      cell.font = { bold: true };
+      cell.fill = {
+        type: "pattern",
+        pattern: "solid",
+        fgColor: { argb: "FFE0EAF6" },
+      };
+      cell.alignment = { horizontal: "center" };
+    });
+
+    // Data rows
+    for (const row of recordset) {
+      const values = columns.map((col) => {
+        const val = row[col];
+        if (val instanceof Date) {
+          return val;
+        }
+        if (val === null || val === undefined) return "";
+        return val;
+      });
+      sheet.addRow(values);
+    }
+
+    // Format date columns and auto-width
+    const dateColIndices: number[] = [];
+    const maxWidths: number[] = columns.map((col) => col.length);
+
+    columns.forEach((col, idx) => {
+      if (DATE_COLUMNS.has(col)) {
+        dateColIndices.push(idx + 1);
+      }
+    });
+
+    sheet.eachRow((row, rowNumber) => {
+      row.eachCell({ includeEmpty: false }, (cell, colNumber) => {
+        if (rowNumber > 1 && dateColIndices.includes(colNumber)) {
+          if (cell.value instanceof Date) {
+            cell.numFmt = "yyyy/mm/dd";
+          }
+        }
+        const text = cell.text || "";
+        const width = Math.max(maxWidths[colNumber - 1] || 0, text.length + 2);
+        maxWidths[colNumber - 1] = width;
+      });
+    });
+
+    columns.forEach((_, idx) => {
+      sheet.getColumn(idx + 1).width = Math.min(Math.max(maxWidths[idx], 8), 50);
+    });
+
+    sheet.views = [{ state: "frozen", ySplit: 1 }];
+
+    const buffer = await workbook.xlsx.writeBuffer();
+    const bytes = typeof buffer === "object" && buffer && "byteLength" in buffer
+      ? (buffer as { byteLength: number }).byteLength
+      : 0;
+    const dur = Date.now() - t0;
+    exportLogger.info(`export ok · rows=${recordset.length} · bytes=${bytes} · dur=${dur}ms`);
+
+    return new NextResponse(buffer, {
+      status: 200,
+      headers: {
+        "Content-Type":
+          "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+        "Content-Disposition":
+          "attachment; filename*=UTF-8''" + encodeURIComponent("压力表合同生产数据.xlsx"),
+      },
+    });
+  } catch (err) {
+    const dur = Date.now() - t0;
+    const message = err instanceof Error ? err.message : "Unknown error";
+    exportLogger.error(`export failed · dur=${dur}ms · ${formatError(err)}`);
+    return NextResponse.json({ error: message }, { status: 500 });
+  } finally {
+    if (pool) {
+      await pool.close();
+    }
+    releaseExportLock();
+  }
+}
+```
+
+> 注意：删除原 `console.error("Excel export error:", message);`，由 `exportLogger.error(...)` 取代。
+
+- [ ] **Step 4: 测试 + lint**
+
+Run: `npm test && npm run lint`
+Expected: 测试全 PASS、lint 0 error。
+
+- [ ] **Step 5: 提交**
+
+```bash
+git add src/app/api/export-excel/route.ts
+git commit -m "Log export lifecycle (start/ok/fail/lock) with stack and timing"
+```
+
+---
+
+## Task 4: 本地验证（不部署）
+
+- [ ] **Step 1: 启动本地服务**
+
+Run（后台）: `npm run dev`
+打开: http://localhost:3000
+
+- [ ] **Step 2: 触发 production-data 失败，确认 ERROR 带栈**
+
+临时让 DB 查询失败（如临时把 `.env.local` 的 `DB_SERVER` 改成不可达值再重启，或直接断网/停 DB），查询一个车间号。
+Expected: `logs/app/app.log` 出现一行：
+`[...] [ERROR] [api] query failed · workshopNo=<值> · dur=<N>ms · <Error 类型>: <msg>\n    at ...`（**含完整堆栈**）。
+
+- [ ] **Step 3: 触发导出，确认 INFO/ERROR**
+
+恢复 DB，查询出数据后点「导出全部」。
+Expected: `logs/app/app.log` 依次出现：
+- `[INFO] [export] export started`
+- `[INFO] [export] export ok · rows=<N> · bytes=<N> · dur=<N>ms`
+
+（可选）导出过程中再点一次导出，确认 `[WARN] [export] export skipped: another export in progress (429)`。
+
+- [ ] **Step 4: 确认轮转目录**
+
+确认 `logs/app/` 目录被创建，`app.log` 存在；NSSM 的 `logs/stdout.log`/`stderr.log` 不再混入这些应用日志（只有 Next 框架输出）。
+
+- [ ] **Step 5: 停止本地服务 + 推送**
+
+Run: 停止 dev；`git push`。
+
+> 部署到 114：pull → `npm install`（新增 log4js）→ `next build` → 重启 WebTable。验证通过后再执行。
+
+---
+
+## Self-Review
+
+**Spec coverage:**
+- 4.1 log4js fileSync → Task 1 Step 6 ✅
+- 4.2 分层（不动 NSSM）→ Global Constraints + Task 4 Step 4 ✅
+- 4.3 logger 模块 + 输出样例 → Task 1 Step 6（pattern 与字段在路由日志中体现）✅
+- 4.4 记什么矩阵：production 失败 ERROR / 慢查询 WARN → Task 2；export 锁占用/回收 WARN、开始/成功 INFO、失败 ERROR、启动 INFO → Task 3 Step 3（含 `export started`）；console.* 全替换 → Task 2/3 ✅
+- 4.5 formatError + 路由带栈 → Task 1（formatError）+ Task 2/3（带栈）✅
+- 4.6 涉及文件 → File Structure ✅
+- 5 边界（OOM 落盘/目录/轮转/dev 与生产）→ Global Constraints + Task 4 ✅
+- 6 测试（formatError 单测 + 手验）→ Task 1 Step 2-5 + Task 4 ✅
+- 7 部署注意（npm install）→ Global Constraints + Task 4 Step 5 ✅
+
+**Placeholder scan:** 无 TBD/TODO；每步含完整代码与命令。
+
+**Type consistency:** `formatError(err: unknown): string` 在 Task 1 定义，Task 2/3 调用一致；`apiLogger`/`exportLogger` 来自 Task 1 的 `logger.ts`；import 路径 `../../../server/logger`（两路由同深，正确）。