5d9981fd7d
- Update 004_architecture_impact_map.md and 005_architecture_data.json - Add audit reports: data-access-audit-framework-v1, data-access-audit-v1-data.json, data-access-audit-v1, g1-g5 audit outputs - Add superpowers plans and specs (logging-refactor, documentation-system-redesign) - Update troubleshooting/known-issues.md
722 lines
24 KiB
Markdown
722 lines
24 KiB
Markdown
# 日志系统重构设计文档
|
||
|
||
| 字段 | 值 |
|
||
|------|---|
|
||
| 文档版本 | v1 |
|
||
| 创建日期 | 2026-07-07 |
|
||
| 作者 | Trae 协作生成 |
|
||
| 状态 | 待用户审查 |
|
||
| 范围 | pino logger 抽象 + Request ID 贯穿 + 静默失败修复 + error.tsx 上报 + track-event 去重 |
|
||
| 策略 | 应用层 SDK 改造，不部署外部可观测性服务（OTel / Sentry / Prometheus 等） |
|
||
|
||
---
|
||
|
||
## 1. 背景与现状
|
||
|
||
### 1.1 现状调研摘要
|
||
|
||
基于 2026-07-07 全项目调研：
|
||
|
||
| 维度 | 状态 | 说明 |
|
||
|------|------|------|
|
||
| 业务审计日志 | ✅ 已成熟 | audit / login / change logger + 3 张 DB 表 + audit 模块管理后台 |
|
||
| 应用层结构化日志 | ❌ 未实现 | 88 处散乱 `console.*`，无级别、无 JSON、无 request ID |
|
||
| Request Correlation | ❌ 未实现 | proxy.ts 中间件零日志、不注入请求 ID |
|
||
| 错误边界上报 | ❌ 全部丢弃 | 130 个 `error.tsx` 接收 `error` prop 后直接丢弃，前端运行时错误对开发者不可见 |
|
||
| 静默失败 | ⚠️ 严重 | 三个 audit-logger 的 catch 块完全吞没错误，运维无法感知审计写入失败 |
|
||
| 统一错误处理 | ⚠️ 部分 | `handleActionError` / `handleApiError` 仅 `console.error`，前缀混乱（`[ExamAction]` / `[ActionError]` / `[ApiError]` / 无前缀混用） |
|
||
| track-event | ⚠️ 重复 | 4 个 no-op stub（shared / rbac / course-plans / questions 各一份） |
|
||
| 架构图覆盖 | ❌ 未覆盖 | 004 / 005 完全未记录可观测性基础设施 |
|
||
|
||
### 1.2 console.* 分布
|
||
|
||
| 类型 | 次数 | 文件数 | 主要位置 |
|
||
|------|------|--------|----------|
|
||
| `console.log` | 2 | 1 | `questions/utils/parse-content.ts` |
|
||
| `console.error` | 67 | 30 | data-access 的 catch 块、`action-utils.ts`、`api-response.ts`、各 Server Action |
|
||
| `console.warn` | 5 | 5 | `api/web-vitals/route.ts`、redis/store 等 |
|
||
| `console.info` | 10 | 6 | `track-event.ts`、`api/web-vitals/route.ts`、notifications channels |
|
||
| `console.debug` | 4 | 3 | 各模块 `track-event.ts`（仅 dev） |
|
||
|
||
### 1.3 关键约束
|
||
|
||
- **proxy.ts 在 Edge Runtime 运行**（[proxy.ts:64](file:///e:/Desktop/CICD/src/proxy.ts#L64) 注释明确说明），`AsyncLocalStorage` 不可用（依赖 `node:async_hooks`，Edge 不支持）
|
||
- 其余部分（RSC、Server Action、Route Handler、data-access）运行在 Node.js runtime，`AsyncLocalStorage` 完全支持
|
||
- 项目自部署（`next.config.ts` 中 `output: "standalone"`），运维通过 `docker logs` 查看日志
|
||
|
||
---
|
||
|
||
## 2. 目标与非目标
|
||
|
||
### 2.1 目标
|
||
|
||
1. **统一 logger 抽象**：pino 替换 88 处散乱 `console.*`，提供 `info/error/warn/debug` + `createModuleLogger(module)` 子 logger
|
||
2. **级别控制**：`LOG_LEVEL` 环境变量控制输出阈值（debug/info/warn/error），Zod 校验
|
||
3. **结构化输出**：生产环境 JSON（含 timestamp/level/module/requestId/msg），开发环境 `pino-pretty` 彩色文本
|
||
4. **Request ID 贯穿**：proxy.ts 生成 ID 并注入请求头，Node.js runtime 通过 `AsyncLocalStorage` 贯穿到 data-access / audit-logger
|
||
5. **静默失败告警**：三个 audit-logger 的 catch 块从 silent 改为 `logger.warn`
|
||
6. **统一错误处理接入**：`handleActionError` / `handleApiError` / `safeActionCall` 接入 logger，前缀通过 `module` 字段规范化
|
||
7. **track-event 去重合并**：4 个 no-op stub 合并为 1 个，统一通过 `createModuleLogger("track")`
|
||
8. **error.tsx 错误上报**：130 个 error.tsx 通过 `useErrorReport` Hook 上报到 `/api/client-error`，含节流防风暴
|
||
9. **架构图同步**：004 / 005 / known-issues.md 全量更新
|
||
|
||
### 2.2 非目标（YAGNI）
|
||
|
||
- OpenTelemetry / 链路追踪（trace）
|
||
- Prometheus / `/metrics` 端点
|
||
- Sentry / Bugsnag / Datadog 等 SaaS 错误监控
|
||
- Web Vitals 后端持久化（保留现有 `console.warn`）
|
||
- 数据库查询日志 / 慢查询日志
|
||
- 日志文件轮转（`docker logs` 已足够）
|
||
- next-auth events 回调改造（与本次重构解耦）
|
||
|
||
---
|
||
|
||
## 3. 架构设计
|
||
|
||
### 3.1 整体数据流
|
||
|
||
```
|
||
[Client] ──HTTP──> [proxy.ts (Edge Runtime)]
|
||
│ requestId = crypto.randomUUID() // Web Crypto API
|
||
│ NextResponse.next({ request: { headers } })
|
||
│ 注入 x-request-id 到下游请求头
|
||
▼
|
||
[RSC / Server Action / Route Handler (Node.js Runtime)]
|
||
│ withRequestContext(fn):
|
||
│ 1. headers().get("x-request-id") 读取
|
||
│ 2. requestContextStorage.run({ requestId }, fn)
|
||
▼
|
||
[data-access / audit-logger / 业务逻辑 (Node.js Runtime)]
|
||
│ logger.info({...}, "msg") 调用
|
||
│ pino mixin 自动从 getRequestContext() 取 requestId
|
||
▼
|
||
[stdout: {"level":"info","time":...,"requestId":"abc-123","module":"audit","msg":"..."}]
|
||
```
|
||
|
||
### 3.2 新增文件清单
|
||
|
||
```
|
||
src/shared/lib/
|
||
├─ logger.ts # pino 实例 + createModuleLogger 工厂
|
||
├─ request-context.ts # AsyncLocalStorage（仅 Node.js runtime）
|
||
└─ with-request-context.ts # Server Action / Route Handler 入口包装
|
||
|
||
src/shared/hooks/
|
||
└─ use-error-report.ts # error.tsx 公共上报 Hook（含节流）
|
||
|
||
src/app/api/client-error/
|
||
└─ route.ts # 客户端错误接收端点
|
||
```
|
||
|
||
### 3.3 修改文件清单
|
||
|
||
| 文件 | 改动类型 | 说明 |
|
||
|------|---------|------|
|
||
| `package.json` | 新增依赖 | `pino`、`pino-pretty`（dev） |
|
||
| `src/env.mjs` | 新增字段 | `LOG_LEVEL`（默认 `info`，Zod enum） |
|
||
| `src/proxy.ts` | 修改 | 生成 requestId 并通过 `NextResponse.next` 注入请求头 |
|
||
| `src/shared/lib/action-utils.ts` | 修改 | `handleActionError` / `safeActionCall` 用 logger |
|
||
| `src/shared/lib/api-response.ts` | 修改 | `handleApiError` 用 logger |
|
||
| `src/shared/lib/audit-logger.ts` | 修改 | catch 块从 silent 改为 `logger.warn` |
|
||
| `src/shared/lib/change-logger.ts` | 修改 | 同上 |
|
||
| `src/shared/lib/login-logger.ts` | 修改 | 同上 |
|
||
| `src/shared/lib/track-event.ts` | 修改 | 改为 `createModuleLogger("track")`，删除 no-op 输出 |
|
||
| `src/modules/rbac/lib/track.ts` | 删除 | 引用方改为从 `@/shared/lib/track-event` 导入 |
|
||
| `src/modules/course-plans/lib/track-event.ts` | 删除 | 同上 |
|
||
| `src/modules/questions/utils/track-event.ts` | 删除 | 同上 |
|
||
| 88 处 `console.*` 调用点 | 修改 | 替换为 `logger.*` 或 `createModuleLogger(module)` |
|
||
| 130 个 `error.tsx` | 修改 | 在 useEffect 中调用 `useErrorReport(error)` |
|
||
| `next.config.ts` | 修改 | 在现有 `serverExternalPackages` 数组中添加 `"pino"`（当前已有 `mysql2`/`tencentcloud-sdk-nodejs`/`exceljs`） |
|
||
| `.eslintrc` / `eslint.config.mjs` | 修改 | 新增 `no-console` 规则，仅允许 `logger.ts` 中使用 console |
|
||
|
||
---
|
||
|
||
## 4. 核心模块设计
|
||
|
||
### 4.1 `src/shared/lib/logger.ts`
|
||
|
||
```ts
|
||
import pino, { type Logger } from "pino"
|
||
import { env } from "@/env.mjs"
|
||
import { getRequestContext } from "./request-context"
|
||
|
||
/**
|
||
* 全局 logger 实例。
|
||
*
|
||
* - 生产环境：JSON 输出到 stdout（docker logs 友好）
|
||
* - 开发环境：pino-pretty 彩色文本
|
||
* - 自动从 AsyncLocalStorage 混入 requestId / userId（若存在）
|
||
*/
|
||
export const logger = pino({
|
||
level: env.LOG_LEVEL,
|
||
base: { service: "cicd-app" },
|
||
formatters: {
|
||
level: (label) => ({ level: label }),
|
||
},
|
||
mixin: () => getRequestContext(),
|
||
...(env.NODE_ENV === "development" && {
|
||
transport: {
|
||
target: "pino-pretty",
|
||
options: { colorize: true, translateTime: "SYS:standard" },
|
||
},
|
||
}),
|
||
})
|
||
|
||
/**
|
||
* 创建模块级子 logger，自动绑定 module 字段。
|
||
*
|
||
* @example
|
||
* ```ts
|
||
* const log = createModuleLogger("audit")
|
||
* log.info({ userId }, "User action logged")
|
||
* // 输出: {"level":"info","module":"audit","msg":"User action logged", ...}
|
||
* ```
|
||
*/
|
||
export function createModuleLogger(module: string): Logger {
|
||
return logger.child({ module })
|
||
}
|
||
|
||
export type { Logger }
|
||
```
|
||
|
||
### 4.2 `src/shared/lib/request-context.ts`
|
||
|
||
```ts
|
||
import { AsyncLocalStorage } from "node:async_hooks"
|
||
|
||
/**
|
||
* 请求上下文，贯穿整个请求生命周期。
|
||
*
|
||
* 仅在 Node.js Runtime 中可用（proxy.ts 是 Edge Runtime，不导入此模块）。
|
||
* 通过 withRequestContext 高阶函数注入。
|
||
*/
|
||
export interface RequestContext {
|
||
requestId: string
|
||
userId?: string
|
||
module?: string
|
||
}
|
||
|
||
export const requestContextStorage = new AsyncLocalStorage<RequestContext>()
|
||
|
||
/**
|
||
* 获取当前请求上下文（若存在）。
|
||
*
|
||
* - 在 withRequestContext 包装的调用栈内：返回完整上下文
|
||
* - 在调用栈外（如顶层模块初始化、定时任务）：返回空对象
|
||
*
|
||
* pino logger 的 mixin 配置会自动调用此函数混入 requestId。
|
||
*/
|
||
export function getRequestContext(): Partial<RequestContext> {
|
||
return requestContextStorage.getStore() ?? {}
|
||
}
|
||
```
|
||
|
||
### 4.3 `src/shared/lib/with-request-context.ts`
|
||
|
||
```ts
|
||
import { headers } from "next/headers"
|
||
import { randomUUID } from "node:crypto"
|
||
import { requestContextStorage, type RequestContext } from "./request-context"
|
||
|
||
/**
|
||
* 包装 Server Action / Route Handler，注入 requestId 到 AsyncLocalStorage。
|
||
*
|
||
* 工作流程：
|
||
* 1. 通过 `headers()` 读取 proxy.ts 注入的 `x-request-id`
|
||
* 2. 若请求头无此字段（如直接调用的内部函数），生成新 UUID
|
||
* 3. 通过 `requestContextStorage.run()` 注入到 AsyncLocalStorage
|
||
* 4. 在调用栈内的所有 logger 调用自动获得 requestId
|
||
*
|
||
* @example
|
||
* ```ts
|
||
* export const createUserAction = withRequestContext(
|
||
* async (state: ActionState<User>, input: CreateUserInput) => {
|
||
* // 此处 logger.info 会自动带 requestId
|
||
* return handleAction(...)
|
||
* }
|
||
* )
|
||
* ```
|
||
*/
|
||
export function withRequestContext<TArgs extends unknown[], TResult>(
|
||
fn: (...args: TArgs) => Promise<TResult>
|
||
): (...args: TArgs) => Promise<TResult> {
|
||
return async (...args: TArgs) => {
|
||
const headersList = await headers()
|
||
const requestId =
|
||
headersList.get("x-request-id") ?? randomUUID()
|
||
const ctx: RequestContext = { requestId }
|
||
return requestContextStorage.run(ctx, () => fn(...args))
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4.4 `src/proxy.ts` 改造
|
||
|
||
```ts
|
||
import { NextResponse } from "next/server"
|
||
import type { NextRequest } from "next/server"
|
||
import { getToken } from "next-auth/jwt"
|
||
// ... 原有 imports
|
||
|
||
export async function proxy(request: NextRequest) {
|
||
const { pathname } = request.nextUrl
|
||
|
||
// 生成或复用 requestId（Web Crypto API，Edge 兼容）
|
||
const requestId =
|
||
request.headers.get("x-request-id") ?? crypto.randomUUID()
|
||
|
||
// 跳过静态资源和登录页
|
||
if (
|
||
pathname.startsWith("/_next") ||
|
||
pathname.startsWith("/api/auth") ||
|
||
pathname === "/login" ||
|
||
pathname === "/register" ||
|
||
pathname === "/favicon.ico"
|
||
) {
|
||
return NextResponse.next({
|
||
request: { headers: injectRequestId(request, requestId) },
|
||
})
|
||
}
|
||
|
||
// ... 原有 token / onboarding / 权限检查逻辑
|
||
// 所有 NextResponse.next() / NextResponse.redirect() 调用保留，
|
||
// 但 NextResponse.next() 调用统一传入 request.headers
|
||
|
||
const response = NextResponse.next({
|
||
request: { headers: injectRequestId(request, requestId) },
|
||
})
|
||
response.headers.set("x-request-id", requestId)
|
||
return response
|
||
}
|
||
|
||
/**
|
||
* 创建包含 x-request-id 的新 Headers 对象。
|
||
* 通过 NextResponse.next({ request: { headers } }) 注入到下游 RSC 请求。
|
||
*/
|
||
function injectRequestId(request: NextRequest, requestId: string): Headers {
|
||
const headers = new Headers(request.headers)
|
||
headers.set("x-request-id", requestId)
|
||
return headers
|
||
}
|
||
```
|
||
|
||
> **说明**：proxy.ts 不导入 `request-context.ts`，避免在 Edge Runtime 中加载 `node:async_hooks` 导致构建错误。
|
||
|
||
### 4.5 `src/shared/hooks/use-error-report.ts`
|
||
|
||
```ts
|
||
"use client"
|
||
|
||
import { useEffect } from "react"
|
||
|
||
interface ClientErrorPayload {
|
||
message: string
|
||
stack?: string
|
||
digest?: string
|
||
url: string
|
||
userAgent: string
|
||
timestamp: string
|
||
}
|
||
|
||
/**
|
||
* 客户端错误上报 Hook。
|
||
*
|
||
* 用于 error.tsx 接收 error prop 后上报到 /api/client-error。
|
||
*
|
||
* 节流策略：
|
||
* - 同一 digest（或 message）在 sessionStorage 中标记，避免 React 重渲染或快速刷新时多次上报
|
||
* - 上报失败时静默忽略，避免无限循环
|
||
*/
|
||
export function useErrorReport(error: Error & { digest?: string }): void {
|
||
useEffect(() => {
|
||
if (!error) return
|
||
|
||
const digest = error.digest ?? error.message
|
||
const storageKey = `error-reported:${digest}`
|
||
if (sessionStorage.getItem(storageKey)) return
|
||
sessionStorage.setItem(storageKey, "1")
|
||
|
||
const payload: ClientErrorPayload = {
|
||
message: error.message,
|
||
stack: error.stack,
|
||
digest: error.digest,
|
||
url: window.location.href,
|
||
userAgent: navigator.userAgent,
|
||
timestamp: new Date().toISOString(),
|
||
}
|
||
|
||
fetch("/api/client-error", {
|
||
method: "POST",
|
||
headers: { "Content-Type": "application/json" },
|
||
body: JSON.stringify(payload),
|
||
keepalive: true, // 即使页面卸载也尝试发送
|
||
}).catch(() => {
|
||
// 上报失败时不再上报，避免无限循环
|
||
})
|
||
}, [error])
|
||
}
|
||
```
|
||
|
||
### 4.6 `src/app/api/client-error/route.ts`
|
||
|
||
```ts
|
||
import { NextResponse } from "next/server"
|
||
import { createModuleLogger } from "@/shared/lib/logger"
|
||
import { withRequestContext } from "@/shared/lib/with-request-context"
|
||
|
||
const log = createModuleLogger("client-error")
|
||
|
||
interface ClientErrorPayload {
|
||
message: string
|
||
stack?: string
|
||
digest?: string
|
||
url: string
|
||
userAgent: string
|
||
timestamp: string
|
||
}
|
||
|
||
/**
|
||
* 接收客户端 error.tsx 上报的错误。
|
||
*
|
||
* 注意：客户端错误的 requestId 与原始请求不同（来自 /api/client-error 的 HTTP 请求），
|
||
* 但 digest 字段可用于关联原始错误。
|
||
*/
|
||
export const POST = withRequestContext(async (request: Request) => {
|
||
try {
|
||
const body = (await request.json()) as ClientErrorPayload
|
||
log.error(
|
||
{
|
||
clientMessage: body.message,
|
||
stack: body.stack,
|
||
digest: body.digest,
|
||
url: body.url,
|
||
userAgent: body.userAgent,
|
||
clientTimestamp: body.timestamp,
|
||
},
|
||
"Client error reported"
|
||
)
|
||
return NextResponse.json({ ok: true })
|
||
} catch (error) {
|
||
log.error({ err: error }, "Failed to parse client error payload")
|
||
return NextResponse.json({ ok: false }, { status: 400 })
|
||
}
|
||
})
|
||
```
|
||
|
||
### 4.7 `src/shared/lib/audit-logger.ts` 改造（静默失败 → 告警）
|
||
|
||
```ts
|
||
import { createModuleLogger } from "@/shared/lib/logger"
|
||
|
||
const log = createModuleLogger("audit-logger")
|
||
|
||
export async function logAudit(params: LogAuditParams): Promise<void> {
|
||
try {
|
||
// ... 原有写入逻辑
|
||
} catch (error) {
|
||
// 旧：catch { /* Silently fail */ }
|
||
// 新：记录到 logger，运维可感知
|
||
log.warn(
|
||
{ err: error, action: params.action, module: params.module },
|
||
"Audit log write failed"
|
||
)
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4.8 `src/shared/lib/action-utils.ts` 改造
|
||
|
||
```ts
|
||
import { createModuleLogger } from "@/shared/lib/logger"
|
||
import type { ActionState } from "@/shared/types/action-state"
|
||
import { PermissionDeniedError } from "@/shared/lib/errors"
|
||
|
||
const log = createModuleLogger("action")
|
||
|
||
export function handleActionError(e: unknown): ActionState<never> {
|
||
if (e instanceof PermissionDeniedError) {
|
||
return { success: false, message: e.message }
|
||
}
|
||
if (e instanceof BusinessError) {
|
||
return { success: false, message: e.message, errorCode: e.code }
|
||
}
|
||
if (e instanceof Error) {
|
||
// 旧：console.error("[ActionError]", e.name, e.message, e.stack)
|
||
log.error({ err: e }, "Action failed")
|
||
return { success: false, message: "操作失败,请稍后重试", errorCode: "unexpected" }
|
||
}
|
||
log.error({ err: e }, "Unknown action error")
|
||
return { success: false, message: "操作失败,请稍后重试", errorCode: "unexpected" }
|
||
}
|
||
|
||
export async function safeActionCall<T>(
|
||
action: () => Promise<ActionState<T>>,
|
||
options?: {
|
||
onError?: (error: unknown) => void
|
||
onFinally?: () => void
|
||
}
|
||
): Promise<ActionState<T> | null> {
|
||
try {
|
||
return await action()
|
||
} catch (e) {
|
||
options?.onError?.(e)
|
||
// 旧：console.error("[SafeActionCall]", e)
|
||
log.error({ err: e }, "Safe action call threw")
|
||
return null
|
||
} finally {
|
||
options?.onFinally?.()
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4.9 `src/shared/lib/track-event.ts` 改造
|
||
|
||
```ts
|
||
import { createModuleLogger } from "@/shared/lib/logger"
|
||
|
||
const log = createModuleLogger("track")
|
||
|
||
/**
|
||
* 业务埋点接口。
|
||
*
|
||
* 不再是 no-op stub，通过 logger.info 输出结构化事件，
|
||
* 后续可扩展为接入外部 analytics 服务。
|
||
*/
|
||
export function trackEvent(
|
||
name: string,
|
||
props?: Record<string, unknown>
|
||
): void {
|
||
log.info({ event: name, ...props }, "track event")
|
||
}
|
||
|
||
export function trackExamEvent(
|
||
name: string,
|
||
props?: Record<string, unknown>
|
||
): void {
|
||
trackEvent(`exam.${name}`, props)
|
||
}
|
||
|
||
export function trackAuthEvent(
|
||
name: string,
|
||
props?: Record<string, unknown>
|
||
): void {
|
||
trackEvent(`auth.${name}`, props)
|
||
}
|
||
```
|
||
|
||
### 4.10 `src/env.mjs` 改造
|
||
|
||
```ts
|
||
// 在 server schema 中添加：
|
||
LOG_LEVEL: z.enum(["debug", "info", "warn", "error"]).default("info"),
|
||
```
|
||
|
||
### 4.11 ESLint 规则
|
||
|
||
```js
|
||
// eslint.config.mjs
|
||
{
|
||
rules: {
|
||
"no-console": ["error", { allow: [], allowWithImplicit: false }]
|
||
},
|
||
// logger.ts 豁免（pino 内部需用 console）
|
||
overrides: [
|
||
{
|
||
files: ["src/shared/lib/logger.ts"],
|
||
rules: { "no-console": "off" }
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 改造范围与策略
|
||
|
||
### 5.1 console.* 替换映射
|
||
|
||
| 类型 | 数量 | 替换为 | 调用方式 |
|
||
|------|------|--------|----------|
|
||
| `console.log` | 2 | `log.debug` | `const log = createModuleLogger("questions")` |
|
||
| `console.error` | 67 | `log.error` | 按文件所属模块创建子 logger |
|
||
| `console.warn` | 5 | `log.warn` | 同上 |
|
||
| `console.info` | 10 | `log.info` | 同上 |
|
||
| `console.debug` | 4 | `log.debug` | 同上 |
|
||
|
||
### 5.2 模块前缀规范化
|
||
|
||
当前散乱前缀 → 统一通过 `module` 字段：
|
||
|
||
| 当前前缀 | 新 module 字段 |
|
||
|---------|----------------|
|
||
| `[ExamAction]` | `exams` |
|
||
| `[ActionError]` | `action` |
|
||
| `[ApiError]` | `api` |
|
||
| `[AuditLogger]` | `audit-logger` |
|
||
| `[SafeActionCall]` | `action` |
|
||
| `[Files]` / `[files]` | `files` |
|
||
| 无前缀 | 按文件所属模块 |
|
||
|
||
### 5.3 Server Action 包装策略
|
||
|
||
由于 Server Action 通过 `"use server"` 自动成为 RPC，不能简单用 `withRequestContext` 包装导出函数（会丢失 Next.js 类型推断）。且 `handleActionError` 是同步函数，无法 `await headers()` 读取请求头。
|
||
|
||
**最终策略**：在每个 Server Action 模块的入口点调用 `withRequestContext` 包装：
|
||
|
||
```ts
|
||
// src/modules/audit/actions.ts
|
||
"use server"
|
||
import { withRequestContext } from "@/shared/lib/with-request-context"
|
||
import { createModuleLogger } from "@/shared/lib/logger"
|
||
|
||
const log = createModuleLogger("audit")
|
||
|
||
export const createAuditLogAction = withRequestContext(
|
||
async (state: ActionState<void>, input: CreateAuditInput) => {
|
||
// 此处 logger 自动带 requestId
|
||
log.info({ input }, "Creating audit log")
|
||
return handleAction(...)
|
||
}
|
||
)
|
||
```
|
||
|
||
**data-access 层无需显式包装**：因为 data-access 总是从 Server Action 调用，AsyncLocalStorage 上下文会自动贯穿到调用栈下游。data-access 中的 logger 调用会自动获得 requestId。
|
||
|
||
**实施时验证项**：
|
||
- Next.js 16 是否允许高阶函数包装 Server Action（保留 NextServerAction 标记）
|
||
- 若不允许，回退方案：在每个 Server Action 函数体首行调用 `await initRequestContext()`，该函数内部读取 headers 并写入 AsyncLocalStorage
|
||
|
||
### 5.4 error.tsx 改造模式
|
||
|
||
130 个 error.tsx 统一改为：
|
||
|
||
```tsx
|
||
"use client"
|
||
import { useEffect } from "react"
|
||
import { useErrorReport } from "@/shared/hooks/use-error-report"
|
||
// ... 原有 imports
|
||
|
||
export default function Error({
|
||
error,
|
||
reset,
|
||
}: {
|
||
error: Error & { digest?: string }
|
||
reset: () => void
|
||
}) {
|
||
useErrorReport(error)
|
||
// ... 原有 UI 渲染
|
||
}
|
||
```
|
||
|
||
每个 error.tsx 仅增加 2 行（import + 调用 Hook）。
|
||
|
||
---
|
||
|
||
## 6. 测试策略
|
||
|
||
### 6.1 单元测试
|
||
|
||
| 测试文件 | 覆盖内容 |
|
||
|---------|---------|
|
||
| `__tests__/logger.test.ts` | level 控制、JSON 输出格式、mixin 注入 requestId、createModuleLogger |
|
||
| `__tests__/request-context.test.ts` | AsyncLocalStorage 读写、嵌套调用、空上下文 |
|
||
| `__tests__/use-error-report.test.tsx` | 节流（sessionStorage 标记）、fetch 调用、错误处理 |
|
||
|
||
### 6.2 集成测试
|
||
|
||
- 启动开发服务器，发起请求，验证日志包含 requestId
|
||
- 触发 Server Action 错误，验证日志包含 module + requestId + error stack
|
||
- 触发 client error.tsx，验证 `/api/client-error` 收到请求并记录日志
|
||
|
||
### 6.3 回归验证
|
||
|
||
- `npx tsc --noEmit` 零错误
|
||
- `npm run lint` 零错误（含新增 `no-console` 规则）
|
||
- 现有 vitest 测试套件全部通过
|
||
|
||
---
|
||
|
||
## 7. 风险与权衡
|
||
|
||
| 风险 | 影响 | 缓解 |
|
||
|------|------|------|
|
||
| pino 在 Next.js bundling 中可能有问题 | 高 | 已配置 `serverExternalPackages`，pino 仅服务端导入；开发期 `pino-pretty` 通过 transport 配置启用 |
|
||
| `AsyncLocalStorage` 在 Server Action 中可能不工作 | 中 | Server Action 运行在 Node.js runtime，完全支持；实施时先做最小验证 |
|
||
| Server Action 高阶函数包装可能丢失 Next.js 类型 | 中 | 实施时验证，必要时回退为显式 `headers()` 调用 |
|
||
| 88 处 console.* 替换可能遗漏 | 低 | 通过 ESLint `no-console` 规则强制，仅允许 `logger.ts` 中使用 |
|
||
| 130 个 error.tsx 改造量大 | 中 | 提取公共 `useErrorReport` Hook，每个 error.tsx 仅加 2 行 |
|
||
| track-event 合并可能破坏调用方 | 低 | 删除前 grep 所有引用，统一改为从 `@/shared/lib/track-event` 导入 |
|
||
| 客户端错误风暴（无限循环上报） | 中 | sessionStorage 节流 + fetch 失败静默 + `keepalive` 选项 |
|
||
| proxy.ts 改造可能影响 Edge Runtime 构建 | 中 | 不导入任何 Node.js 模块，仅用 Web Crypto API |
|
||
|
||
---
|
||
|
||
## 8. 架构图同步（强制）
|
||
|
||
按项目规则"改码必同步图"，重构后必须更新：
|
||
|
||
### 8.1 `docs/architecture/004_architecture_impact_map.md`
|
||
新增章节：
|
||
- `shared/lib/logger.ts` — pino 实例 + createModuleLogger
|
||
- `shared/lib/request-context.ts` — AsyncLocalStorage 请求上下文
|
||
- `shared/lib/with-request-context.ts` — Server Action / Route Handler 入口包装
|
||
- `shared/hooks/use-error-report.ts` — 客户端错误上报 Hook
|
||
- `app/api/client-error/route.ts` — 客户端错误接收端点
|
||
|
||
修改章节：
|
||
- `proxy.ts` — 增加 requestId 注入逻辑
|
||
- `shared/lib/audit-logger.ts` / `change-logger.ts` / `login-logger.ts` — 静默失败改为 logger.warn
|
||
- `shared/lib/track-event.ts` — 实现层从 no-op 改为 logger.info
|
||
- `shared/lib/action-utils.ts` / `api-response.ts` — 接入 logger
|
||
|
||
删除记录：
|
||
- `modules/rbac/lib/track.ts`
|
||
- `modules/course-plans/lib/track-event.ts`
|
||
- `modules/questions/utils/track-event.ts`
|
||
|
||
### 8.2 `docs/architecture/005_architecture_data.json`
|
||
- `modules.shared.lib.exports` 新增 `logger` / `createModuleLogger` / `requestContextStorage` / `getRequestContext` / `withRequestContext`
|
||
- `modules.shared.hooks.exports` 新增 `useErrorReport`
|
||
- `modules.app.api.client-error.exports` 新增 `POST`
|
||
- `dependencyMatrix` 更新：proxy.ts → request-context（仅注入请求头，不导入）
|
||
- 删除 `modules.rbac.lib.track`、`modules.course-plans.lib.track-event`、`modules.questions.utils.track-event`
|
||
|
||
### 8.3 `docs/troubleshooting/known-issues.md`
|
||
新增规则条目：
|
||
- pino 集成：`serverExternalPackages` 配置 + `pino-pretty` 仅 dev
|
||
- Edge Runtime 限制：proxy.ts 不能导入 `node:async_hooks`
|
||
- Server Action 包装：`withRequestContext` 高阶函数使用模式
|
||
- error.tsx 错误上报：`useErrorReport` Hook + 节流策略
|
||
- ESLint `no-console` 规则与豁免
|
||
|
||
---
|
||
|
||
## 9. 实施顺序建议
|
||
|
||
1. **Phase 1：基础底座**
|
||
- 装 pino / pino-pretty
|
||
- 创建 `logger.ts` / `request-context.ts` / `with-request-context.ts`
|
||
- 在 `env.mjs` 添加 LOG_LEVEL
|
||
- 单元测试
|
||
|
||
2. **Phase 2：核心接入**
|
||
- proxy.ts 注入 requestId
|
||
- `action-utils.ts` / `api-response.ts` 接入 logger
|
||
- 三个 audit-logger 静默失败 → logger.warn
|
||
- track-event 去重合并
|
||
|
||
3. **Phase 3：批量替换**
|
||
- 88 处 console.* 替换为 logger.*
|
||
- 前缀规范化
|
||
- ESLint `no-console` 规则启用
|
||
|
||
4. **Phase 4：error.tsx 上报**
|
||
- 创建 `use-error-report` Hook
|
||
- 创建 `/api/client-error` Route Handler
|
||
- 130 个 error.tsx 接入
|
||
|
||
5. **Phase 5：架构同步**
|
||
- 更新 004 / 005 / known-issues.md
|
||
- 验证 tsc / lint / 测试通过
|