---
tags: []
aliases:
  - 📋 Global Logging Infrastructure - Task Checklist
date created: 星期三, 十二月 10日 2025, 11:55:42 晚上
date modified: 星期三, 十二月 10日 2025, 11:56:24 晚上
---
收到。作为系统架构师，我已根据《全局日志模块详细设计说明书》及 SOP 要求，完成了**依赖隔离任务拆解 (Dependency-Aware MECE Breakdown)**。

此拆解方案严格遵循 **Level 0 (Core)** 与 **Level 1 (Integration)** 的物理隔离，确保核心日志包零依赖于业务框架。

---

# 📋 Global Logging Infrastructure - Task Checklist

## Phase 1: Batch A - Core Implementation (Level 0)

> 目录: internal/pkg/log
>
> 约束: 仅依赖 zap, lumberjack, context。严禁 import gin, viper。

- [ ] **Batch A - Step 1: 配置与标准定义 (`options.go`, `standard.go`)**
    
    - **核心职责:** 定义日志配置结构体 (Config Struct) 及全局统一的键名常量 (Standard Keys)。
    - **关键设计:**
        - `Options` 结构体需包含 `mapstructure` tag 以适配外部 Viper 解析。
        - 预定义 `trace_id`, `user_id` 等常量为 `snake_case`，杜绝魔法字符串。
        - 包含 `DefaultOptions()` 返回生产环境推荐配置 (100MB, Compress=true)。
            
- [ ] **Batch A - Step 2: 核心构建与 IO (`writer.go`, `zap.go`)**
    
    - **核心职责:** 封装 Lumberjack 文件轮转逻辑，构建 `zap.Core` 与 `zap.Logger` 实例。
    - **关键设计:**
        - **IO 分离:** `writer.go` 实现 `zapcore.WriteSyncer`，强制开启 `Compress: true`。
        - **环境隔离:** `zap.go` 根据配置决定使用 `JSON Encoder` (Prod) 或 `Console Encoder` (Dev)。
        - **双写机制:** 实现 Tee 模式，同时输出到文件和控制台 (Stdout)。
            
- [ ] **Batch A - Step 3: 上下文桥接 (`context.go`)**
    
    - **核心职责:** 实现标准 `context.Context` 到 `zap.Field` 的转换逻辑。
    - **关键设计:**
        - **TraceID 注入:** 实现 `WithContext(ctx)`，从 Context 提取 TraceID 并返回带有 `trace_id` 字段的 `*zap.Logger`。
        - **后台播种:** 实现 `StartBackgroundTrace(ctx)`，为 Cron/Goroutine 任务生成根 TraceID。
        - **零侵入:** 仅依赖标准库 Context，不依赖 Gin Context。
            
- [ ] **Batch A - Step 4: 全局门面 (`log.go`)**
    
    - **核心职责:** 管理全局单例 (Singleton)，提供静态代理方法 (Static Proxy)。
    - **关键设计:**
        - **懒汉兜底:** `globalLogger` 默认初始化为 Console Logger (Nop)，防止未调用 `Init` 时 Panic。
        - **Caller 修正:** 静态方法 (`log.Info`) 必须使用 `AddCallerSkip(1)`，确保日志行号指向业务代码而非 `log.go`。
        - **并发安全:** `Init()` 必须使用 `sync.Once` 或互斥锁保护。

---

## Phase 2: Batch B - Middleware Integration (Level 1)

> 目录: internal/middleware
>
> 约束: 依赖 internal/pkg/log, gin, pkg/app。

- [ ] **Batch B - Step 1: 链路追踪中间件 (`trace.go`)**
    
    - **核心职责:** 请求入口处的 TraceID 生成与注入。
    - **关键设计:**
        - 优先读取 Header `X-Trace-ID`，无则生成 UUID。
        - **关键动作:** 调用 `log.WithTraceID(ctx, id)` 将 ID 注入 **Standard Context**，再回写到 `c.Request`，打通后续所有层的日志链路。
            
- [ ] **Batch B - Step 2: 访问日志中间件 (`access_log.go`)**
    
    - **核心职责:** 记录 HTTP 请求的黄金指标 (Golden Signals)。
    - **关键设计:**
        - 必须使用 `log.WithContext(c.Request.Context())` 打印，确保包含 TraceID。
        - 记录字段：`method`, `path`, `status`, `latency` (ms), `client_ip`。
            
- [ ] **Batch B - Step 3: 灾难恢复中间件 (`recovery.go`)**
    
    - **核心职责:** 替换 Gin 默认 Recovery，提供结构化 Panic 日志。
    - **关键设计:**
        - 捕获 `panic` -> 获取 Stack Trace -> 构造 JSON Error 日志 (包含 `stack` 字段)。
        - 联动 `pkg/app` 返回标准 JSON 500 响应，通过 `pkg/log` 记录系统级错误。

---

# 🏁 Next Action

建议按照 Checklist 顺序，从 **Batch A - Step 1** 开始执行。是否现在开始 Phase 0.5 (API 签名锁定) 或直接生成 Step 1 代码？