# 日志系统迁移执行摘要

**创建日期**: 2026-01-29  
**状态**: 待执行  
**优先级**: 高

---

## 快速概览

| 项目 | 内容 |
|------|------|
| **问题** | 项目使用 `loguru`，不符合技术栈规范（要求使用标准库 `logging`） |
| **影响范围** | 23 个文件 |
| **预计时间** | 11 小时 |
| **风险等级** | 中等 |
| **回滚难度** | 低（有完整备份和回滚脚本） |

---

## 为什么要迁移？

1. ✅ **技术栈统一**: 符合 Jointo 技术栈规范
2. ✅ **减少依赖**: 移除不必要的第三方库
3. ✅ **降低成本**: 减少团队学习和维护成本
4. ✅ **文档一致**: 新文档已按标准库编写

---

## 迁移计划

### 阶段划分

```
阶段 1: 核心模块 (2h) ━━━━━━━━━━━━━━━━━━━━ 最高优先级
  └─ app/core/logging.py (关键)
  └─ app/core/database.py
  └─ app/core/cache.py
  └─ app/middleware/logging.py

阶段 2: 服务层 (3h) ━━━━━━━━━━━━━━━━━━━━━ 高优先级
  └─ 5 个服务文件

阶段 3: API + 仓储 (2h) ━━━━━━━━━━━━━━━━ 中优先级
  └─ 4 个文件

阶段 4: 任务层 (2h) ━━━━━━━━━━━━━━━━━━━ 中优先级
  └─ 5 个任务文件

阶段 5: 迁移脚本 (1h) ━━━━━━━━━━━━━━━━━ 低优先级
  └─ 6 个迁移脚本

阶段 6: 清理验证 (1h) ━━━━━━━━━━━━━━━━━ 最高优先级
  └─ 移除依赖、测试、文档
```

### 时间线

```
Day 1 (4h):  阶段 1 + 阶段 2 (部分)
Day 2 (4h):  阶段 2 (完成) + 阶段 3
Day 3 (3h):  阶段 4 + 阶段 5 + 阶段 6
```

---

## 技术方案

### 新的日志配置

```python
# app/core/logging.py - 全新设计

✅ 彩色输出（开发环境）
✅ 结构化日志（生产环境）
✅ 自动日志轮转（按天）
✅ 多级别输出（控制台 + 文件）
✅ 第三方库日志控制
```

### 代码变更示例

**Before**:
```python
from loguru import logger
logger.info(f"用户 {user_id} 登录")
```

**After**:
```python
import logging
logger = logging.getLogger(__name__)
logger.info("用户 %s 登录", user_id)
```

---

## 执行步骤

### 1. 准备阶段

```bash
# 1. 创建分支
git checkout -b feature/logging-migration

# 2. 备份当前代码
./scripts/backup_before_migration.sh
```

### 2. 实施阶段

每个阶段执行：

```bash
# 1. 备份文件
cp <file>.py <file>.py.bak

# 2. 修改代码
# - 替换导入语句
# - 修改日志调用

# 3. 测试验证
docker exec jointo-server-app pytest tests/unit/<test>.py -v

# 4. 提交变更
git add <file>.py
git commit -m "refactor: migrate <file> from loguru to logging"
```

### 3. 验证阶段

```bash
# 1. 全局搜索残留
grep -r "from loguru import" server/app/
grep -r "import loguru" server/app/

# 2. 运行完整测试
docker exec jointo-server-app pytest tests/ -v

# 3. 检查日志输出
docker exec jointo-server-app tail -f logs/app.log

# 4. 性能测试
docker exec jointo-server-app pytest tests/performance/ -v
```

### 4. 清理阶段

```bash
# 1. 移除 loguru 依赖
# 编辑 server/requirements.txt
# 删除: loguru==0.7.2

# 2. 重新构建容器
docker-compose -f server/docker-compose.yml build app
docker-compose -f server/docker-compose.yml up -d

# 3. 删除备份文件
find server/app -name "*.py.bak" -delete
```

---

## 风险控制

### 高风险项

| 风险 | 缓解措施 | 回滚方案 |
|------|---------|---------|
| 日志格式变化 | 保持相似格式 | 恢复备份文件 |
| 性能下降 | 使用异步处理器 | 回滚到 loguru |

### 回滚脚本

```bash
#!/bin/bash
# scripts/rollback_logging_migration.sh

# 1. 恢复备份文件
for file in $(find server/app -name "*.py.bak"); do
    mv "$file" "${file%.bak}"
done

# 2. 恢复 requirements.txt
git checkout server/requirements.txt

# 3. 重新构建容器
docker-compose -f server/docker-compose.yml build app
docker-compose -f server/docker-compose.yml up -d

echo "✅ 回滚完成"
```

---

## 成功标准

- [ ] 所有 23 个文件已迁移
- [ ] `requirements.txt` 中移除 `loguru`
- [ ] 全局搜索无 `loguru` 残留
- [ ] 所有测试通过（单元测试 + 集成测试）
- [ ] 日志功能正常（控制台 + 文件 + 轮转）
- [ ] 彩色输出正常工作
- [ ] 性能无明显下降（< 5%）
- [ ] 文档已更新

---

## 相关文档

- 📄 [RFC 201: 日志系统迁移](./rfcs/201-logging-system-migration.md) - 完整技术方案
- 📄 [Changelog: 日志系统迁移 RFC](./changelogs/2026-01-29-logging-system-migration-rfc.md) - 创建记录
- 📄 [技术栈规范 - 后端](/.claude/skills/jointo-tech-stack/references/backend.md) - 日志规范

---

## 快速开始

### 立即执行阶段 1

```bash
# 1. 创建分支
git checkout -b feature/logging-migration

# 2. 备份核心模块
cp server/app/core/logging.py server/app/core/logging.py.bak
cp server/app/core/database.py server/app/core/database.py.bak
cp server/app/core/cache.py server/app/core/cache.py.bak
cp server/app/middleware/logging.py server/app/middleware/logging.py.bak

# 3. 开始迁移
# 参考 RFC 201 中的代码示例
```

---

## 团队协作

### 分工建议

- **开发者 A**: 阶段 1 + 阶段 2
- **开发者 B**: 阶段 3 + 阶段 4
- **开发者 C**: 阶段 5 + 阶段 6（验证）

### 沟通渠道

- 📢 **进度更新**: 每完成一个阶段在团队频道通知
- 🐛 **问题反馈**: 遇到问题立即在技术频道讨论
- ✅ **代码审查**: 每个阶段完成后进行 Code Review

---

## 常见问题

### Q1: 为什么不能继续使用 loguru？

**A**: 技术栈规范要求使用标准库，减少外部依赖，降低维护成本。

### Q2: 迁移会影响现有功能吗？

**A**: 不会。日志是横切关注点，只要保持相同的日志级别和格式，不影响业务逻辑。

### Q3: 如果迁移出问题怎么办？

**A**: 有完整的备份和回滚脚本，可以在 5 分钟内回滚到迁移前状态。

### Q4: 新的日志系统有什么优势？

**A**: 
- ✅ 无外部依赖
- ✅ 更好的性能
- ✅ 更灵活的配置
- ✅ 更好的生态支持

### Q5: 需要学习新的 API 吗？

**A**: 标准库 `logging` 是 Python 内置模块，大多数开发者已经熟悉。RFC 中提供了完整的使用指南。

---

## 联系方式

- **RFC 作者**: System
- **技术负责人**: [待指定]
- **项目经理**: [待指定]

---

**最后更新**: 2026-01-29  
**文档版本**: v1.0