# 日志规范

## 指定框架

项目统一使用内部日志库：`rmdc-common/wdd_log/log_utils.go`

## 日志级别定义

### Debug
- **用途**：开发调试，记录程序执行流程、变量值等详细信息
- **场景**：默认开发日志级别
- **示例**：
```go
log.Debug(ctx, "开始处理用户请求", map[string]interface{}{
    "userID":    userID,
    "requestID": requestID,
})
```

### Info
- **用途**：记录关键业务操作节点
- **场景**：用户登录、订单创建、支付成功等关键业务
- **示例**：
```go
log.Info(ctx, "用户登录成功", map[string]interface{}{
    "userID":   user.ID,
    "username": user.Username,
    "ip":       c.ClientIP(),
})

log.Info(ctx, "订单创建成功", map[string]interface{}{
    "orderID": order.ID,
    "amount":  order.Amount,
    "userID":  order.UserID,
})
```

### Warning
- **用途**：记录可预期的、非致命的异常情况，程序仍可继续运行
- **场景**：外部 API 超时启用备用方案、配置缺失使用默认值等
- **示例**：
```go
log.Warning(ctx, "外部API调用超时,已启用备用方案", map[string]interface{}{
    "api":      "payment-gateway",
    "timeout":  "5s",
    "fallback": "local-cache",
})
```

### Error
- **用途**：记录严重错误，导致当前业务流程无法继续
- **场景**：数据库连接失败、关键参数校验失败等
- **要求**：必须详细记录错误信息和堆栈
- **示例**：
```go
log.Error(ctx, "数据库连接失败", map[string]interface{}{
    "host":  dbConfig.Host,
    "port":  dbConfig.Port,
    "error": err.Error(),
    "stack": debug.Stack(),
})
```

## 日志内容规范

### 必须包含
1. **TraceID** - 请求追踪 ID
2. **UserID** - 用户标识（如适用）
3. **操作描述** - 简练的中文描述
4. **关键参数** - 与操作相关的关键数据

### 格式要求
```go
log.Info(ctx, "操作描述", map[string]interface{}{
    "key1": value1,
    "key2": value2,
})
```

## 各层日志职责

### Handler 层
- 使用 `ResponseErrorWithDetail` 自动记录 Error 日志
- 一般不主动记录日志

### Service 层
- **Info**：关键业务操作成功（创建订单、支付、用户注册等）
- **Warning**：业务逻辑异常但可处理
- **Error**：通过 ResponseErrorWithDetail 在 Handler 层统一记录

### DAO 层
- 一般不记录日志
- 错误向上抛出，由 Handler 层统一处理

## 禁止事项

1. 禁止在日志中记录敏感信息（密码、Token、完整银行卡号等）
2. 禁止使用 `fmt.Println` 或 `log.Println`
3. 禁止在循环中大量记录日志
4. Error 日志禁止缺少堆栈信息
