kami_backend/docs/JD_ORDER_REUSE_IMPLEMENTATION.md

京东订单复用功能实现报告

功能概述

为京东Cookie管理模块实现了订单复用功能，优化了订单创建流程，支持复用未支付的京东订单，减少不必要的订单创建。

核心功能

1. 京东订单支付状态检测

API接口: POST /jd-cookie/order/jd-payment-status

功能描述: 通过调用京东接口检查订单的实时支付状态

实现文件:

• API定义: api/jd_cookie/v1/cookie.go
• 控制器: internal/controller/jd_cookie/jd_cookie_v1_check_jd_order_payment.go
• 服务层: internal/service/jd_cookie.go
• 逻辑层: internal/logic/jd_cookie/order.go
• 京东集成: utility/integration/originalJd/client.go

请求参数:

{
  "jd_order_id": "京东订单号"
}

响应参数:

{
  "jd_order_id": "京东订单号",
  "is_paid": false,
  "payment_status": 1,
  "message": "待支付",
  "can_reuse": true
}

2. 订单复用逻辑

实现方式: 在创建订单时优先查找可复用的京东订单

复用条件:

1. 金额和商品品类相同
2. 订单状态为待支付
3. 没有当前关联订单或关联订单已过期
4. 京东订单未过期

复用策略:

• 优先使用最早创建的符合条件的订单
• 如果支付链接过期，自动刷新支付链接
• 记录订单关联关系和历史变更

3. 15分钟超时复用机制

功能描述: 京东订单创建15分钟后如果未支付，可以被其他订单复用

实现逻辑:

• 在检查支付状态时计算订单创建时间
• 超过15分钟的未支付订单标记为可复用
• 定时任务自动释放过期订单的关联关系

定时任务:

• CleanupExpiredOrders(): 清理过期订单
• ReleaseExpiredJdOrders(): 释放超时订单关联

核心方法实现

1. CreateOrder() 方法更新

// 优先尝试复用现有的京东订单
reusableJdOrder, err := s.findReusableJdOrder(ctx, amount, category)
if err != nil {
    glog.Warning(ctx, "查找可复用京东订单失败", err)
}

if reusableJdOrder != nil {
    // 使用可复用的京东订单
    jdOrderId = reusableJdOrder.JdOrderId
    cookieId = reusableJdOrder.CookieId
    wxPayUrl = reusableJdOrder.WxPayUrl
} else {
    // 无可复用订单，创建新的京东订单
    // ... 原有创建逻辑
}

2. 新增辅助方法

• findReusableJdOrder(): 查找可复用的京东订单
• updateJdOrderPaymentUrl(): 更新京东订单支付链接
• updateJdOrderCurrentOrderId(): 更新订单关联关系
• getCookieById(): 根据ID获取Cookie信息
• callJdCheckPayment(): 调用京东支付状态检查接口

数据库结构支持

关键字段

jd_cookie_jd_order表:

• current_order_id: 当前关联的用户订单ID
• order_expire_at: 京东订单过期时间
• wx_pay_expire_at: 支付链接过期时间

这些字段支持订单复用逻辑和过期管理。

常量配置

// JdOrderReuseTimeout 京东订单复用超时时间（分钟）
JdOrderReuseTimeout = 15

集成服务更新

originalJd服务扩展

新增了 CheckOrderPayment() 方法，用于调用京东接口检查订单支付状态：

// CheckOrderPayment 检查京东订单支付状态
func (c *Client) CheckOrderPayment(ctx context.Context, input *CheckOrderPaymentReq) (*CheckOrderPaymentResp, error)

使用流程

1. 创建订单流程

1. 用户请求创建订单
2. 系统检查是否已存在该订单
3. 查找可复用的京东订单
4. 如果找到可复用订单：
   • 检查支付链接是否过期
   • 如过期则刷新支付链接
   • 创建新的用户订单记录
   • 更新京东订单关联关系
5. 如果没有可复用订单：
   • 分配可用Cookie
   • 调用京东下单接口
   • 创建新的京东订单和用户订单记录

2. 支付状态检查流程

1. 接收检查请求
2. 查询京东订单信息
3. 获取关联Cookie
4. 调用京东接口检查支付状态
5. 更新本地订单状态
6. 记录状态变更历史
7. 返回支付状态和复用可能性

优势

1. 减少订单创建成本: 复用现有订单避免重复调用京东接口
2. 提高系统效率: 减少Cookie消耗和接口调用频率
3. 灵活的超时机制: 15分钟超时确保订单可以被及时复用
4. 完整的状态追踪: 记录所有订单状态变更和关联关系变化
5. 自动清理机制: 定时任务确保系统数据的一致性

注意事项

1. 订单复用逻辑确保了数据一致性和业务正确性
2. 支付链接过期会自动刷新，确保用户体验
3. 完整的历史记录支持问题追踪和数据审计
4. 京东接口调用集成了错误处理和日志记录

测试建议

1. 测试订单复用的各种场景
2. 验证15分钟超时机制
3. 测试支付链接刷新功能
4. 验证京东接口集成的正确性
5. 测试定时清理任务的效果