# Payment Service 文档技术栈合规性修复

**日期**: 2026-01-29  
**类型**: 文档更新  
**影响范围**: payment-service.md 文档

## 修复内容

### 1. 文档更新

✅ **已完成**：更新 `docs/requirements/backend/04-services/user/payment-service.md`

**主要变更**：
- 日志系统：从 `loguru` 改为标准库 `logging`
- 依赖版本：固定版本号（`wechatpayv3==1.2.6`, `python-alipay-sdk==3.7.0`）
- 配置类：添加 Pydantic `Field` 验证和 `extra="forbid"`
- 异常处理：使用项目自定义异常（`PaymentError`, `ValidationError`）
- 类型注解：金额使用 `Decimal`，定义 `PaymentResult` TypedDict
- 依赖注入：补充 FastAPI `Depends` 使用说明和完整示例
- 测试文档：添加单元测试和集成测试示例

### 2. 依赖更新

✅ **已完成**：更新 `server/requirements.txt`

**变更**：
```diff
- # 日志
- loguru==0.7.2
+ # 日志（使用标准库 logging，无需额外依赖）

- # 支付 SDK
- wechatpayv3>=1.2.0
- python-alipay-sdk>=3.0.0
+ # 支付 SDK
+ wechatpayv3==1.2.6
+ python-alipay-sdk==3.7.0
```

## 发现的全局问题

⚠️ **重要发现**：项目中大量使用了 `loguru`，需要全局替换为标准库 `logging`

**受影响的文件**（共 20+ 个）：
- `app/services/*.py` - 所有服务层
- `app/api/v1/*.py` - 所有 API 路由
- `app/repositories/*.py` - 所有仓储层
- `app/tasks/*.py` - 所有 Celery 任务
- `app/core/*.py` - 核心模块
- `app/migrations/*.py` - 数据库迁移脚本

## 后续工作

### 阶段 1：创建日志迁移计划（优先级：高）

需要创建一个全局的日志系统迁移计划：

1. **评估影响范围**：
   - 统计所有使用 `loguru` 的文件
   - 分析日志配置和格式化需求
   - 确定迁移优先级

2. **设计标准日志配置**：
   - 基于 Python `logging` 模块
   - 保持与 `loguru` 相似的功能（结构化日志、日志轮转等）
   - 统一日志格式和级别

3. **分批迁移**：
   - 优先迁移核心模块（`app/core/logging.py`）
   - 然后迁移服务层和 API 层
   - 最后迁移任务和迁移脚本

### 阶段 2：实现 payment-service（优先级：中）

当前文档已符合技术栈规范，可以开始实现：

1. 创建 `app/services/payment_service.py`
2. 创建 `app/services/payment/wechat_payment.py`
3. 创建 `app/services/payment/alipay_payment.py`
4. 补充 `app/core/exceptions.py` 中的 `PaymentError` 异常
5. 编写单元测试和集成测试

### 阶段 3：更新相关服务文档（优先级：中）

需要检查并更新其他服务文档，确保符合技术栈规范：

- [ ] `recharge-service.md`
- [ ] `credit-service.md`
- [ ] `sms-service.md`
- [ ] `wechat-service.md`
- [ ] `ai-service.md`

## 技术栈合规性检查清单

### ✅ 已修复

- [x] 日志系统：使用标准库 `logging`
- [x] 依赖版本：固定版本号（`==` 而非 `>=`）
- [x] Pydantic Settings：配置 `extra="forbid"`
- [x] 异常处理：使用项目自定义异常
- [x] 类型注解：金额使用 `Decimal`，明确返回类型
- [x] 依赖注入：补充 FastAPI `Depends` 说明
- [x] 测试文档：添加完整测试示例

### ⚠️ 待处理（全局问题）

- [ ] 全局替换 `loguru` 为标准库 `logging`
- [ ] 统一日志配置和格式
- [ ] 更新所有服务、API、任务中的日志调用

## 相关文档

- [技术栈合规性检查](./2026-01-29-payment-service-tech-stack-compliance.md)
- [Jointo 技术栈规范](/.claude/skills/jointo-tech-stack/SKILL.md)
- [后端开发规范](/.claude/skills/jointo-tech-stack/references/backend.md)

## 建议

1. **立即行动**：创建全局日志迁移 RFC，规划 `loguru` 到 `logging` 的迁移路径
2. **分批执行**：避免一次性修改所有文件，按模块分批迁移
3. **保持一致**：新代码必须使用标准库 `logging`，不再引入 `loguru`
4. **文档先行**：所有服务文档必须先符合技术栈规范，再开始实现