# 结构化日志（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`（两路由同深，正确）。