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

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

---

## 变更概述

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

---

## 修正内容

### 1. Pydantic v2 配置升级

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

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

**修正后**：
```python
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 不支持

**修正前**：
```python
@shared_task(name="recharge.check_orphan_orders")
async def check_orphan_recharge_orders():
    """检查孤儿充值订单"""
    async with get_session() as session:
        # ...
```

**修正后**：
```python
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 中未定义

**新增方法**：
```python
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]` 类型导入

**修正**：
```python
from typing import List, Optional, Tuple, Dict, Any
```

---

### 5. 数据库会话修正

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

**修正前**：
```python
async with get_session() as session:
    # ...
```

**修正后**：
```python
from app.core.database import async_session_maker

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

---

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

### ✅ 已符合规范

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

### ✅ 本次修正

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

---

## 影响评估

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

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

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

---

## 后续建议

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

### 2. 单元测试补充
建议为以下功能添加单元测试：
- `RechargeRepository.check_orphan_orders()`
- Celery 任务的异步包装器
- Pydantic Schema 验证逻辑

### 3. 集成测试
建议添加集成测试验证：
- 支付回调的完整流程
- 订单超时自动取消
- 孤儿订单检测和告警

---

## 参考文档

- [jointo-tech-stack Skill](/.claude/skills/jointo-tech-stack/)
- [Backend 规范](/.claude/skills/jointo-tech-stack/references/backend.md)
- [Database 规范](/.claude/skills/jointo-tech-stack/references/database.md)
- [API 设计规范](/.claude/skills/jointo-tech-stack/references/api-design.md)

---

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