docs/v1.0/server/changelogs/2026-01-29-payment-service-tech-stack-compliance.md

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. 日志系统修复

修改前:

from loguru import logger
logger.info(f"创建支付订单: {order_no}")

修改后:

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

2. 依赖版本规范化

修改前:

wechatpayv3>=1.2.0
python-alipay-sdk>=3.0.0
loguru>=0.7.0

修改后:

wechatpayv3==1.2.6
python-alipay-sdk==3.7.0
# 移除 loguru，使用标准库 logging

3. Pydantic Settings 配置修复

修改前:

class Settings(BaseSettings):
    WECHAT_PAY_MCHID: str
    
    class Config:
        env_file = ".env"

修改后:

from pydantic import Field

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

4. 异常处理规范化

修改前:

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

修改后:

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. 类型注解优化

修改前:

async def create_payment(
    self,
    order_no: str,
    amount: float,
    payment_method: str,
    description: str
) -> Dict[str, Any]:

修改后:

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 的使用示例：

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 技术栈规范
• 后端开发规范
• 测试规范