# 日志系统迁移 - 阶段 2 准备就绪

**日期**: 2026-01-29  
**类型**: 迁移准备  
**影响范围**: 服务层（5 个文件）

---

## 概述

阶段 1（核心模块）已完成并验证通过。现在准备执行阶段 2 - 服务层迁移。

---

## 阶段 2 文件清单

| # | 文件路径 | 行数 | 日志调用数 | 复杂度 | 状态 |
|---|---------|------|-----------|--------|------|
| 1 | `app/services/payment_service.py` | ~100 | 8 | 中 | ⏳ 待执行 |
| 2 | `app/services/payment/wechat_payment.py` | ~80 | 6 | 中 | ⏳ 待执行 |
| 3 | `app/services/payment/alipay_payment.py` | ~80 | 6 | 中 | ⏳ 待执行 |
| 4 | `app/services/recharge_service.py` | ~350 | 15 | 高 | ⏳ 待执行 |
| 5 | `app/services/attachment_service.py` | ~400 | 10 | 高 | ⏳ 待执行 |

**总计**: 5 个文件，约 1010 行代码，45 处日志调用

---

## 执行步骤

### 步骤 1: 创建备份

```bash
# 备份所有待迁移文件
cp server/app/services/payment_service.py server/app/services/payment_service.py.bak
cp server/app/services/payment/wechat_payment.py server/app/services/payment/wechat_payment.py.bak
cp server/app/services/payment/alipay_payment.py server/app/services/payment/alipay_payment.py.bak
cp server/app/services/recharge_service.py server/app/services/recharge_service.py.bak
cp server/app/services/attachment_service.py server/app/services/attachment_service.py.bak

echo "✅ 备份完成"
```

### 步骤 2: 执行迁移

#### 文件 1: `app/services/payment_service.py`

**需要替换的内容**:

```python
# 第 6 行 - 导入语句
# Before:
from loguru import logger

# After:
import logging
logger = logging.getLogger(__name__)
```

**日志调用替换**（8 处）:

| 行号 | Before | After |
|------|--------|-------|
| 23 | `logger.info("PaymentService 初始化成功")` | `logger.info("PaymentService 初始化成功")` |
| 48-50 | `logger.info(f"创建支付订单: order_no={order_no}, amount={amount}元, payment_method={payment_method}, description={description}")` | `logger.info("创建支付订单: order_no=%s, amount=%.2f元, payment_method=%s, description=%s", order_no, amount, payment_method, description)` |
| 58 | `logger.error(error_msg)` | `logger.error("不支持的支付方式: %s", payment_method)` |
| 62 | `logger.error(f"创建支付订单失败: order_no={order_no}, error={str(e)}")` | `logger.error("创建支付订单失败: order_no=%s", order_no, exc_info=True)` |
| 79 | `logger.info(f"验证支付回调: payment_method={payment_method}, order_no={order_no}")` | `logger.info("验证支付回调: payment_method=%s, order_no=%s", payment_method, order_no)` |
| 87 | `logger.warning(f"不支持的支付方式: {payment_method}")` | `logger.warning("不支持的支付方式: %s", payment_method)` |
| 90 | `logger.error(f"验证回调签名失败: payment_method={payment_method}, error={str(e)}")` | `logger.error("验证回调签名失败: payment_method=%s", payment_method, exc_info=True)` |

#### 文件 2-3: `app/services/payment/wechat_payment.py` 和 `alipay_payment.py`

**相同的替换模式**:

```python
# 导入语句
from loguru import logger
→
import logging
logger = logging.getLogger(__name__)

# 日志调用
logger.info(f"调用微信支付 API: {order_no}, {amount}元")
→
logger.info("调用微信支付 API: order_no=%s, amount=%.2f元", order_no, amount)

logger.error(f"微信支付订单创建失败: {order_no}, {message}")
→
logger.error("微信支付订单创建失败: order_no=%s, code=%s, message=%s", order_no, code, message)

logger.error(f"微信支付回调验证失败: {str(e)}")
→
logger.error("微信支付回调验证失败", exc_info=True)
```

#### 文件 4: `app/services/recharge_service.py`

**需要替换的内容**（15 处日志调用）:

```python
# 导入语句（第 14 行）
from loguru import logger
→
import logging
logger = logging.getLogger(__name__)

# 主要日志调用模式
logger.info(f"创建充值订单: user_id={user_id}, package_id={package_id}, amount={amount}, payment_method={payment_method}")
→
logger.info("创建充值订单: user_id=%s, package_id=%s, amount=%s, payment_method=%s", user_id, package_id, amount, payment_method)

logger.error(f"创建支付失败: {str(e)}")
→
logger.error("创建支付失败", exc_info=True)

logger.info(f"充值订单创建成功: {order_no}")
→
logger.info("充值订单创建成功: order_no=%s", order_no)
```

#### 文件 5: `app/services/attachment_service.py`

**需要替换的内容**（10 处日志调用）:

```python
# 导入语句（第 11 行）
from loguru import logger
→
import logging
logger = logging.getLogger(__name__)

# 主要日志调用模式
logger.info(f"上传附件: user_id={user_id}, filename={file.filename}, related_type={related_type}, purpose={attachment_purpose}")
→
logger.info("上传附件: user_id=%s, filename=%s, related_type=%s, purpose=%s", user_id, file.filename, related_type, attachment_purpose)

logger.info(f"附件上传成功: {created_attachment.attachment_id}")
→
logger.info("附件上传成功: attachment_id=%s", created_attachment.attachment_id)

logger.info(f"附件删除成功: {attachment_id}")
→
logger.info("附件删除成功: attachment_id=%s", attachment_id)
```

### 步骤 3: 验证语法

```bash
# 验证所有迁移的文件
python -m py_compile server/app/services/payment_service.py
python -m py_compile server/app/services/payment/wechat_payment.py
python -m py_compile server/app/services/payment/alipay_payment.py
python -m py_compile server/app/services/recharge_service.py
python -m py_compile server/app/services/attachment_service.py

# 检查是否有语法错误
if [ $? -eq 0 ]; then
    echo "✅ 所有文件语法检查通过"
else
    echo "❌ 语法检查失败，请检查错误信息"
fi
```

### 步骤 4: 检查进度

```bash
# 检查残留的 loguru 引用
grep -r "from loguru import" server/app/ | wc -l

# 应该显示: 14 (19 - 5 = 14)
```

### 步骤 5: 运行测试（可选）

```bash
# 如果有相关测试，运行它们
pytest server/tests/unit/test_payment_service.py -v
pytest server/tests/unit/test_recharge_service.py -v
pytest server/tests/unit/test_attachment_service.py -v
```

---

## 替换模式总结

### 模式 1: 导入语句

```python
# Before
from loguru import logger

# After
import logging
logger = logging.getLogger(__name__)
```

### 模式 2: 简单信息日志

```python
# Before
logger.info(f"操作成功: {value}")

# After
logger.info("操作成功: %s", value)
```

### 模式 3: 多参数日志

```python
# Before
logger.info(f"用户 {user_id} 创建订单 {order_no}, 金额 {amount}元")

# After
logger.info("用户 %s 创建订单 %s, 金额 %.2f元", user_id, order_no, amount)
```

### 模式 4: 错误日志

```python
# Before
logger.error(f"操作失败: {str(e)}")

# After
logger.error("操作失败", exc_info=True)
```

### 模式 5: 警告日志

```python
# Before
logger.warning(f"警告: {message}")

# After
logger.warning("警告: %s", message)
```

---

## 自动化脚本（可选）

如果需要批量替换，可以使用以下 Python 脚本：

```python
#!/usr/bin/env python3
"""
日志迁移辅助脚本
自动替换 loguru 为 logging
"""
import re
from pathlib import Path

def migrate_file(file_path: Path):
    """迁移单个文件"""
    content = file_path.read_text(encoding='utf-8')
    
    # 1. 替换导入语句
    content = re.sub(
        r'from loguru import logger',
        'import logging\nlogger = logging.getLogger(__name__)',
        content
    )
    
    # 2. 替换 f-string 日志（简单模式）
    # logger.info(f"xxx {var} yyy")
    # → logger.info("xxx %s yyy", var)
    # 注意：这个正则表达式只处理简单情况，复杂的需要手动处理
    
    # 3. 替换错误日志
    content = re.sub(
        r'logger\.error\(f"([^"]+): \{str\(e\)\}"\)',
        r'logger.error("\1", exc_info=True)',
        content
    )
    
    file_path.write_text(content, encoding='utf-8')
    print(f"✅ 已迁移: {file_path}")

# 使用示例
files = [
    Path('server/app/services/payment_service.py'),
    Path('server/app/services/payment/wechat_payment.py'),
    Path('server/app/services/payment/alipay_payment.py'),
    Path('server/app/services/recharge_service.py'),
    Path('server/app/services/attachment_service.py'),
]

for file in files:
    if file.exists():
        migrate_file(file)
```

**注意**: 自动化脚本只能处理简单情况，复杂的日志调用仍需手动检查和修改。

---

## 验证清单

完成迁移后，请检查以下项目：

- [ ] 所有文件的导入语句已替换
- [ ] 所有 f-string 日志已改为 %-formatting
- [ ] 所有错误日志已添加 `exc_info=True`
- [ ] 语法检查通过
- [ ] 残留 loguru 引用数量正确（14 个）
- [ ] 相关测试通过（如果有）
- [ ] 代码审查完成

---

## 回滚方案

如果迁移出现问题，可以快速回滚：

```bash
# 恢复备份文件
mv server/app/services/payment_service.py.bak server/app/services/payment_service.py
mv server/app/services/payment/wechat_payment.py.bak server/app/services/payment/wechat_payment.py
mv server/app/services/payment/alipay_payment.py.bak server/app/services/payment/alipay_payment.py
mv server/app/services/recharge_service.py.bak server/app/services/recharge_service.py
mv server/app/services/attachment_service.py.bak server/app/services/attachment_service.py

echo "✅ 回滚完成"
```

---

## 下一步

完成阶段 2 后：

1. 创建阶段 2 的 Changelog
2. 更新进度跟踪文档
3. 继续执行阶段 3（API + 仓储层）

---

## 相关文档

- [RFC 201: 日志系统迁移](../rfcs/201-logging-system-migration.md)
- [执行总结](../LOGGING_MIGRATION_EXECUTION_SUMMARY.md)
- [进度跟踪](../LOGGING_MIGRATION_PROGRESS.md)
- [阶段 1 Changelog](./2026-01-29-logging-migration-phase1-core-modules.md)

---

**准备状态**: ✅ 就绪  
**预计时间**: 3 小时  
**建议**: 建议手动执行，确保每个文件的日志调用都正确替换