feat: 前端统一 Logger 模块 — 接口、双流 Sink、ESLint 规则、测试

docs/development/frontend.md

@@ -179,3 +179,79 @@ Workbench 聊天页面位于 `src/web/consoles/workbench/pages/ChatPage.tsx`，
 ## 更新触发条件
 
 修改前端技术栈、组件边界、数据流、样式规则、测试环境或前端验证方式时，必须更新本文档。
+
+## 日志模块
+
+### Logger 接口
+
+`src/web/utils/logger.ts` 提供与后端镜像的 Logger 抽象：
+
+```typescript
+export interface Logger {
+  child(bindings: Record<string, unknown>): Logger;
+  debug(message: string, data?: unknown): void;
+  error(message: string, data?: unknown): void;
+  info(message: string, data?: unknown): void;
+  setLevel(level: LogLevel): void;
+  warn(message: string, data?: unknown): void;
+}
+```
+
+### 实现
+
+| 实现                    | 工厂函数                                | 用途                                                    |
+| ----------------------- | --------------------------------------- | ------------------------------------------------------- |
+| `DefaultLogger` + Sinks | `useLogger()` / `createDefaultLogger()` | 组件内使用，ConsoleSink + AntdMessageSink 双流          |
+| `ConsoleLogger`         | `createConsoleLogger()`                 | 非组件纯函数（ErrorBoundary、工具函数），仅 ConsoleSink |
+| `NoopLogger`            | `createNoopLogger()`                    | 测试中不需要日志的场景                                  |
+| `MemoryLogger`          | `createMemoryLogger()`                  | 测试断言日志条目                                        |
+
+### 使用方式
+
+**组件内（推荐）：**
+
+```typescript
+import { useLogger } from "../hooks/use-logger";
+
+function MyComponent() {
+  const logger = useLogger();
+  logger.info("数据加载完成", { count: 42 });
+  logger.warn("即将超时");
+  logger.error("操作失败", { error: new Error("...") });
+}
+```
+
+**非组件纯函数：**
+
+```typescript
+import { createConsoleLogger } from "../utils/logger";
+
+const logger = createConsoleLogger();
+logger.debug("调试信息");
+```
+
+**作用域绑定：**
+
+```typescript
+const pageLogger = logger.child({ page: "projects" });
+pageLogger.info("页面加载"); // [Alfred:INFO] 页面加载 [page=projects]
+```
+
+### notification 红线
+
+- `AntdMessageSink` 仅对 **warn**（`message.warning`）和 **error**（`message.error`）触发用户可见通知。
+- `debug` 和 `info` 级别绝不对用户弹出 notification，仅在开发者控制台输出。
+- 错误详情通过 `data` 参数传入（如 `logger.error("提交失败", { error })`），`data` 不经序列化透传，保留 Error 堆栈展开能力。
+
+### 生产环境行为
+
+生产环境（`import.meta.env["PROD"]`）自动将 ConsoleSink 最小级别设为 `warn`，屏蔽 debug/info 输出。`useLogger()` 和 `createConsoleLogger()` 自动处理此逻辑，调用方无需关心环境判断。
+
+### ErrorBoundary 特殊说明
+
+`ErrorBoundary` 是 class 组件，无法使用 `useLogger()` hook。它以 `createConsoleLogger()` 直接创建独立的 ConsoleLogger 实例，仅输出到控制台不触发用户通知。
+
+### 测试
+
+- 单元测试使用 `createMemoryLogger()` 断言日志记录，使用 `createNoopLogger()` 静默无关日志。
+- `createDefaultLogger(sinks, isProduction)` 接受 `isProduction` 参数，测试中可显式控制级别过滤行为，不依赖 `import.meta.env`。