# Structured Logging

## Purpose

定义结构化日志规范，使用 zap 日志库提供 JSON 格式日志输出、日志文件滚动、请求 ID 追踪和多级别日志控制。

## Requirements

### Requirement: 使用 zap 结构化日志

系统 SHALL 使用 zap 作为结构化日志库。

#### Scenario: 日志初始化

- **WHEN** 应用启动
- **THEN** SHALL 初始化 zap logger
- **THEN** SHALL 根据配置设置日志级别
- **THEN** SHALL 配置日志输出格式为 JSON（文件）和 Console（stdout）

#### Scenario: 日志字段

- **WHEN** 记录日志
- **THEN** SHALL 支持结构化字段（key-value）
- **THEN** SHALL 支持嵌套字段
- **THEN** SHALL 自动包含时间戳和日志级别

#### Scenario: 日志注入

- **WHEN** 创建需要记录日志的组件
- **THEN** SHALL 通过构造函数注入 `*zap.Logger`
- **THEN** 调用方 SHALL 必须传入有效的 logger
- **THEN** SHALL NOT 使用全局 logger `zap.L()`（测试代码除外）

### Requirement: 支持日志滚动

系统 SHALL 支持日志文件滚动，使用 lumberjack。

#### Scenario: 按大小滚动

- **WHEN** 日志文件大小达到配置的最大值（默认 100 MB）
- **THEN** SHALL 创建新的日志文件
- **THEN** SHALL 重命名旧文件（添加序号）

#### Scenario: 按数量清理

- **WHEN** 日志文件数量超过配置的最大备份数（默认 10 个）
- **THEN** SHALL 删除最旧的日志文件

#### Scenario: 按时间清理

- **WHEN** 日志文件超过配置的最大保留天数（默认 30 天）
- **THEN** SHALL 自动删除过期文件

#### Scenario: 压缩旧文件

- **WHEN** 配置启用压缩（默认启用）
- **THEN** SHALL 压缩旧的日志文件为 .gz 格式

### Requirement: 支持请求 ID 追踪

系统 SHALL 支持请求 ID 追踪。

#### Scenario: 生成请求 ID

- **WHEN** 收到 HTTP 请求
- **THEN** SHALL 生成唯一的请求 ID（UUID）
- **THEN** SHALL 设置到响应 header 中（X-Request-ID）
- **THEN** SHALL 添加到日志上下文中

#### Scenario: 复用请求 ID

- **WHEN** 请求 header 中已包含 X-Request-ID
- **THEN** SHALL 复用该请求 ID
- **THEN** SHALL 在整个请求生命周期中使用该 ID

#### Scenario: 日志关联请求 ID

- **WHEN** 记录请求相关的日志
- **THEN** SHALL 从 Context 提取 request_id
- **THEN** SHALL 自动包含 request_id 字段
- **THEN** SHALL 支持通过请求 ID 检索日志

### Requirement: 记录请求日志

系统 SHALL 记录 HTTP 请求日志。

#### Scenario: 请求开始日志

- **WHEN** 收到 HTTP 请求
- **THEN** SHALL 记录请求方法、路径、客户端 IP
- **THEN** SHALL 包含请求 ID

#### Scenario: 请求结束日志

- **WHEN** HTTP 请求处理完成
- **THEN** SHALL 记录响应状态码、响应大小
- **THEN** SHALL 记录请求耗时
- **THEN** SHALL 包含请求 ID

### Requirement: 支持日志级别

系统 SHALL 支持日志级别控制。

#### Scenario: 日志级别配置

- **WHEN** 配置日志级别
- **THEN** SHALL 支持 debug、info、warn、error 级别
- **THEN** SHALL 只记录大于等于配置级别的日志

#### Scenario: 开发环境日志

- **WHEN** 配置为开发模式
- **THEN** SHALL 使用 debug 级别
- **THEN** SHALL 输出到控制台和文件

#### Scenario: 生产环境日志

- **WHEN** 配置为生产模式
- **THEN** SHALL 使用 info 级别
- **THEN** SHALL 输出到控制台和文件

### Requirement: 日志存储位置

日志 SHALL 存储在 `~/.nex/log/` 目录。

#### Scenario: 日志文件路径

- **WHEN** 初始化日志系统
- **THEN** SHALL 使用 `~/.nex/log/` 作为日志目录
- **THEN** SHALL 自动创建目录（如果不存在）

#### Scenario: 日志文件命名

- **WHEN** 创建日志文件
- **THEN** SHALL 使用 `nex-YYYY-MM-DD.log` 格式命名
- **THEN** SHALL 按日期创建新文件

### Requirement: ConversionEngine 日志注入

ConversionEngine SHALL 通过依赖注入获取 logger。

#### Scenario: ConversionEngine 构造函数

- **WHEN** 创建 ConversionEngine 实例
- **THEN** 构造函数 SHALL 接受 `*zap.Logger` 参数
- **THEN** 调用方 SHALL 必须传入有效的 logger
- **THEN** SHALL 将 logger 存储在结构体字段中

#### Scenario: ConversionEngine 日志使用

- **WHEN** ConversionEngine 记录日志
- **THEN** SHALL 使用注入的 logger 字段
- **THEN** SHALL NOT 直接调用 `zap.L()`

### Requirement: 字段标准化

系统 SHALL 使用标准化字段定义。

#### Scenario: 标准字段常量

- **WHEN** 记录日志字段
- **THEN** SHALL 使用 `pkg/logger/field.go` 中定义的常量
- **THEN** 字段名 SHALL 包括：`request_id`、`provider_id`、`model_name`、`method`、`path`、`status`、`latency`

#### Scenario: 错误字段统一

- **WHEN** 记录错误日志
- **THEN** SHALL 使用 `zap.Error(err)`
- **THEN** SHALL NOT 使用 `zap.String("error", err.Error())`

#### Scenario: 字段构造函数

- **WHEN** 构造日志字段
- **THEN** SHALL 优先使用 `pkg/logger` 提供的辅助函数
- **THEN** 辅助函数 SHALL 返回 `zap.Field` 类型

### Requirement: 启动日志统一

系统 SHALL 在启动阶段使用结构化日志。

#### Scenario: 最小化 logger 初始化

- **WHEN** 应用启动时配置加载前
- **THEN** SHALL 初始化最小化 logger（仅 stdout，console 格式）
- **THEN** SHALL 支持记录启动错误

#### Scenario: Logger 升级

- **WHEN** 配置加载完成
- **THEN** SHALL 升级为完整 logger（文件 + stdout）
- **THEN** SHALL 应用配置的日志级别和轮转策略

#### Scenario: 配置摘要结构化

- **WHEN** 打印配置摘要
- **THEN** SHALL 使用结构化日志记录
- **THEN** SHALL NOT 使用 `fmt.Printf` 或 `fmt.Println`

### Requirement: 单行输出

系统 SHALL 保证所有日志单行输出。

#### Scenario: Console 单行

- **WHEN** 输出到 stdout
- **THEN** SHALL 单行输出
- **THEN** 字段之间 SHALL 使用空格分隔

#### Scenario: JSON 单行

- **WHEN** 输出到文件
- **THEN** SHALL 单行紧凑 JSON
- **THEN** SHALL NOT 使用美化缩进

#### Scenario: 多行数据保留

- **WHEN** 日志数据本身包含多行（堆栈跟踪、SQL 换行等）
- **THEN** SHALL 保留原始多行格式