# 日志系统迁移 RFC 创建

**日期**: 2026-01-29  
**类型**: RFC 文档  
**影响范围**: 全项目日志系统

## 概述

创建了 RFC 201，规划从 `loguru` 迁移到 Python 标准库 `logging` 的完整方案。

## 背景

在修复 `payment-service.md` 文档的技术栈合规性时，发现项目中大量使用了 `loguru`，而技术栈规范要求使用标准库 `logging`。

## RFC 内容

### 1. 影响范围分析

通过全局代码扫描，确认了 **23 个文件**使用 `loguru`：

- **服务层**: 5 个文件
- **API 层**: 2 个文件
- **仓储层**: 2 个文件
- **任务层**: 5 个文件
- **核心模块**: 3 个文件（包括关键的 `app/core/logging.py`）
- **迁移脚本**: 6 个文件
- **中间件**: 1 个文件

### 2. 设计方案

#### 2.1 新的日志配置模块

设计了完整的 `app/core/logging.py` 模块，提供：

- ✅ **彩色输出**: 开发环境支持彩色日志
- ✅ **结构化日志**: 生产环境支持结构化日志（request_id, user_id）
- ✅ **日志轮转**: 自动按天轮转，保留 30 天应用日志，90 天错误日志
- ✅ **多级别输出**: 控制台 + 应用日志 + 错误日志
- ✅ **第三方库控制**: 合理设置第三方库日志级别

#### 2.2 配置项

添加环境变量配置：
- `LOG_LEVEL`: 日志级别（默认 INFO）
- `LOG_DIR`: 日志目录（默认 logs）
- `ENVIRONMENT`: 运行环境（development/production）

### 3. 迁移策略

#### 分 6 个阶段执行

1. **阶段 1**: 核心模块（2 小时）- 最高优先级
2. **阶段 2**: 服务层（3 小时）- 高优先级
3. **阶段 3**: API 和仓储层（2 小时）- 中优先级
4. **阶段 4**: 任务层（2 小时）- 中优先级
5. **阶段 5**: 迁移脚本（1 小时）- 低优先级
6. **阶段 6**: 清理和验证（1 小时）- 最高优先级

**总预计时间**: 11 小时

#### 代码替换模式

**替换前**:
```python
from loguru import logger
logger.info(f"用户 {user_id} 创建订单 {order_no}")
```

**替换后**:
```python
import logging
logger = logging.getLogger(__name__)
logger.info("用户 %s 创建订单 %s", user_id, order_no)
```

### 4. 风险管理

#### 高风险
- 日志格式变化 → 保持相似格式
- 性能影响 → 使用异步处理器

#### 中风险
- 遗漏文件 → 全局搜索验证
- 第三方库兼容性 → 集成测试

#### 低风险
- 开发体验 → 提供迁移指南

### 5. 回滚计划

提供了完整的回滚脚本，可以快速恢复到迁移前状态。

## 成功标准

1. ✅ 所有文件不再使用 `loguru`
2. ✅ `requirements.txt` 中移除 `loguru` 依赖
3. ✅ 所有测试通过
4. ✅ 日志功能正常
5. ✅ 应用性能无明显下降
6. ✅ 文档已更新

## 附录内容

RFC 包含了详细的附录：

- **附录 A**: 日志级别使用指南
- **附录 B**: 常见日志模式示例
- **附录 C**: 迁移检查清单

## 下一步

1. **立即**: 团队评审 RFC 201
2. **批准后**: 开始阶段 1（核心模块迁移）
3. **持续**: 按计划执行后续阶段

## 相关文档

- [RFC 201: 日志系统迁移](../rfcs/201-logging-system-migration.md)
- [Payment Service 技术栈合规性修复](./2026-01-29-payment-service-tech-stack-compliance.md)
- [Jointo 技术栈规范](/.claude/skills/jointo-tech-stack/SKILL.md)

## 备注

此 RFC 是在修复 payment-service 文档时发现的全局性问题。虽然 payment-service 文档已修复完成，但实际代码实现时仍需遵循此 RFC 的日志规范。

建议优先执行日志系统迁移，然后再开始新服务的实现，以避免引入更多使用 `loguru` 的代码。