# Payment Service 技术栈合规性修复

**日期**: 2026-01-29  
**类型**: 文档修复  
**影响范围**: payment-service 文档

## 问题描述

`payment-service.md` 文档存在多处不符合 Jointo 技术栈规范的问题：

1. ❌ 使用 `loguru` 而非标准库 `logging`
2. ❌ 依赖版本格式不规范（使用 `>=` 而非 `==`）
3. ❌ Pydantic Settings 配置缺少 `extra="forbid"`
4. ❌ 异常处理过于宽泛，未使用项目自定义异常
5. ❌ 金额类型使用 `float` 而非 `Decimal`
6. ❌ 返回类型使用 `Dict[str, Any]` 过于宽泛
7. ❌ 缺少依赖注入说明
8. ❌ 缺少测试相关文档

## 修复内容

### 1. 日志系统修复

**修改前**:
```python
from loguru import logger
logger.info(f"创建支付订单: {order_no}")
```

**修改后**:
```python
import logging
logger = logging.getLogger(__name__)
logger.info("创建支付订单: order_no=%s, amount=%s, method=%s", 
            order_no, amount, payment_method)
```

### 2. 依赖版本规范化

**修改前**:
```txt
wechatpayv3>=1.2.0
python-alipay-sdk>=3.0.0
loguru>=0.7.0
```

**修改后**:
```txt
wechatpayv3==1.2.6
python-alipay-sdk==3.7.0
# 移除 loguru，使用标准库 logging
```

### 3. Pydantic Settings 配置修复

**修改前**:
```python
class Settings(BaseSettings):
    WECHAT_PAY_MCHID: str
    
    class Config:
        env_file = ".env"
```

**修改后**:
```python
from pydantic import Field

class Settings(BaseSettings):
    WECHAT_PAY_MCHID: str = Field(..., description="微信支付商户号")
    
    model_config = {
        "env_file": ".env",
        "extra": "forbid"
    }
```

### 4. 异常处理规范化

**修改前**:
```python
except Exception as e:
    logger.error(f"创建支付订单失败: {order_no}, 错误: {str(e)}")
    raise
```

**修改后**:
```python
from app.core.exceptions import PaymentError, ValidationError

except ValidationError:
    raise
except Exception as e:
    logger.error("创建支付订单失败: order_no=%s", order_no, exc_info=True)
    raise PaymentError(f"支付订单创建失败: {str(e)}") from e
```

### 5. 类型注解优化

**修改前**:
```python
async def create_payment(
    self,
    order_no: str,
    amount: float,
    payment_method: str,
    description: str
) -> Dict[str, Any]:
```

**修改后**:
```python
from decimal import Decimal
from typing import TypedDict

class PaymentResult(TypedDict):
    qrcode_url: str
    expires_in: int

async def create_payment(
    self,
    order_no: str,
    amount: Decimal,
    payment_method: str,
    description: str
) -> PaymentResult:
```

### 6. 添加依赖注入说明

补充了 FastAPI `Depends` 的使用示例：

```python
from fastapi import Depends

class RechargeService:
    def __init__(
        self,
        session: AsyncSession,
        payment_service: PaymentService = Depends()
    ):
        self.payment_service = payment_service
```

### 7. 添加测试文档

新增"测试"章节，包含：
- 单元测试示例（mock 第三方 SDK）
- 集成测试示例（使用沙箱环境）
- 测试运行命令

## 技术栈合规性检查

- ✅ 使用标准库 `logging` 而非第三方日志库
- ✅ 依赖版本固定（`==` 而非 `>=`）
- ✅ Pydantic Settings 配置 `extra="forbid"`
- ✅ 使用项目自定义异常（`app.core.exceptions`）
- ✅ 金额类型使用 `Decimal`
- ✅ 明确的类型注解（TypedDict）
- ✅ 依赖注入模式说明
- ✅ 完整的测试文档

## 影响范围

- 📄 文档更新：`docs/requirements/backend/04-services/user/payment-service.md`
- 📦 依赖检查：`server/requirements.txt`（确认支付 SDK 版本）

## 后续工作

1. 实现 payment-service 时严格遵循更新后的文档规范
2. 补充 `app.core.exceptions` 中的 `PaymentError` 异常类
3. 编写完整的单元测试和集成测试

## 相关文档

- [Jointo 技术栈规范](/.claude/skills/jointo-tech-stack/SKILL.md)
- [后端开发规范](/.claude/skills/jointo-tech-stack/references/backend.md)
- [测试规范](/.claude/skills/jointo-tech-stack/references/testing.md)