6.0 KiB

Raw Blame History

充值服务技术栈合规性修正

日期：2026-01-29
类型：文档修正
影响范围：充值管理服务文档

变更概述

对 recharge-service.md 文档进行全面技术栈合规性检查和修正，确保完全符合 jointo-tech-stack 规范。

修正内容

1. Pydantic v2 配置升级

问题：使用了 Pydantic v1 的 Config 类配置方式

修正前：

class RechargeOrderCreateRequest(BaseModel):
    """创建充值订单请求"""
    package_id: Optional[UUID] = Field(None, alias="packageId")
    
    class Config:
        populate_by_name = True

修正后：

from pydantic import BaseModel, Field, ConfigDict

class RechargeOrderCreateRequest(BaseModel):
    """创建充值订单请求"""
    model_config = ConfigDict(populate_by_name=True)
    
    package_id: Optional[UUID] = Field(None, alias="packageId")

影响的 Schema：

RechargeOrderCreateRequest
RechargeOrderQueryRequest
RechargeOrderResponse
PaymentParamsResponse
RechargeOrderCreateResponse
RechargeOrderListResponse

2. Celery 异步任务修正

问题：直接在 @shared_task 装饰器上使用 async def，Celery 不支持

修正前：

@shared_task(name="recharge.check_orphan_orders")
async def check_orphan_recharge_orders():
    """检查孤儿充值订单"""
    async with get_session() as session:
        # ...

修正后：

import asyncio

@shared_task(name="recharge.check_orphan_orders")
def check_orphan_recharge_orders():
    """检查孤儿充值订单（定期任务）"""
    return asyncio.run(_check_orphan_recharge_orders_async())

async def _check_orphan_recharge_orders_async():
    """异步检查孤儿充值订单"""
    async with async_session_maker() as session:
        # ...

修正的任务：

check_orphan_recharge_orders
cleanup_expired_orders

3. Repository 补充缺失方法

问题：Service 层调用了 repository.check_orphan_orders()，但 Repository 中未定义

新增方法：

async def check_orphan_orders(self) -> List[Dict[str, Any]]:
    """检查孤儿订单（用户或套餐不存在的订单）"""
    query = text("""
        SELECT 
            ro.order_no,
            ro.user_id::text,
            ro.package_id::text,
            ro.amount,
            ro.payment_status
        FROM recharge_orders ro
        LEFT JOIN users u ON ro.user_id = u.user_id AND u.deleted_at IS NULL
        WHERE u.user_id IS NULL
        
        UNION
        
        SELECT 
            ro.order_no,
            ro.user_id::text,
            ro.package_id::text,
            ro.amount,
            ro.payment_status
        FROM recharge_orders ro
        LEFT JOIN credit_packages cp ON ro.package_id = cp.package_id AND cp.is_active = true
        WHERE ro.package_id IS NOT NULL AND cp.package_id IS NULL
    """)
    
    result = await self.session.execute(query)
    rows = result.fetchall()
    
    return [
        {
            'order_no': row[0],
            'user_id': row[1],
            'package_id': row[2],
            'amount': float(row[3]),
            'payment_status': int(row[4])
        }
        for row in rows
    ]

4. 类型提示完善

问题：Repository 缺少 Dict[str, Any] 类型导入

修正：

from typing import List, Optional, Tuple, Dict, Any

5. 数据库会话修正

问题：Celery 任务中使用了不存在的 get_session() 上下文管理器

修正前：

async with get_session() as session:
    # ...

修正后：

from app.core.database import async_session_maker

async with async_session_maker() as session:
    # ...

技术栈合规性检查清单

✅ 已符合规范

枚举类型 - 使用 IntEnum + SMALLINT 存储
UUID v7 主键 - 使用 generate_uuid() 生成
时间戳规范 - 使用 datetime.now(timezone.utc) 和 TIMESTAMPTZ
无外键约束 - 应用层验证引用完整性
索引策略 - 包含单列索引、组合索引、条件索引
依赖注入 - Service 通过构造函数注入依赖
异步模式 - 使用 AsyncSession 和 async/await
API 响应格式 - 使用 ApiResponse[T] 统一格式
字段命名 - 使用 camelCase（通过 alias）

✅ 本次修正

Pydantic v2 配置 - 使用 model_config = ConfigDict()
Celery 异步任务 - 使用同步包装器 + asyncio.run()
Repository 完整性 - 补充 check_orphan_orders() 方法
类型提示完整 - 添加所有必要的类型导入
数据库会话 - 使用正确的 async_session_maker()

影响评估

文档影响

✅ 文档版本升级：v2.3 → v2.4
✅ 所有代码示例可直接使用
✅ 完全符合技术栈规范

代码影响

⚠️ 如果已有实现代码，需要同步更新：
- Pydantic Schema 配置方式
- Celery 任务装饰器模式
- Repository 方法补充

测试影响

⚠️ 需要验证 Celery 任务是否正常执行
⚠️ 需要测试孤儿订单检查功能

后续建议

1. 代码实现同步

如果已有实现代码，建议按照文档修正内容同步更新。

2. 单元测试补充

建议为以下功能添加单元测试：

RechargeRepository.check_orphan_orders()
Celery 任务的异步包装器
Pydantic Schema 验证逻辑

3. 集成测试

建议添加集成测试验证：

支付回调的完整流程
订单超时自动取消
孤儿订单检测和告警

参考文档

修正人员：Kiro AI
审核状态：待审核
文档版本：v2.4

6.0 KiB Raw Blame History

充值服务技术栈合规性修正

变更概述

修正内容

1. Pydantic v2 配置升级

2. Celery 异步任务修正

3. Repository 补充缺失方法

4. 类型提示完善

5. 数据库会话修正

技术栈合规性检查清单

✅ 已符合规范

✅ 本次修正

影响评估

文档影响

代码影响

测试影响

后续建议

1. 代码实现同步

2. 单元测试补充

3. 集成测试

参考文档

6.0 KiB

Raw Blame History