You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
6.0 KiB
6.0 KiB
充值服务技术栈合规性修正
日期：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：
RechargeOrderCreateRequestRechargeOrderQueryRequestRechargeOrderResponsePaymentParamsResponseRechargeOrderCreateResponseRechargeOrderListResponse
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_orderscleanup_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