# 沃尔玛卡密订单处理

<cite>
**本文档引用的文件**  
- [order.go](file://api/card_info_walmart/v1/order.go)
- [card_info_walmart_v1_submit.go](file://internal/controller/card_info_walmart/card_info_walmart_v1_submit.go)
- [card_info_walmart_v1_order_callback.go](file://internal/controller/card_info_walmart/card_info_walmart_v1_order_callback.go)
- [card_info_walmart_v1_order_status_reset.go](file://internal/controller/card_info_walmart/card_info_walmart_v1_order_status_reset.go)
- [card_redeem_order.go](file://internal/service/card_redeem_order.go)
- [card_redeem.go](file://internal/consts/card_redeem.go)
- [v_1_card_redeem_order_info.go](file://internal/model/entity/v_1_card_redeem_order_info.go)
- [order.go](file://internal/logic/card_redeem_order/order.go)
- [callback.go](file://internal/logic/card_redeem_order/callback.go)
- [status.go](file://internal/logic/card_redeem_order/status.go)
- [consume.go](file://internal/logic/card_redeem_order/consume.go)
- [sys_config_dict.go](file://internal/service/sys_config_dict.go)
</cite>

## 目录
1. [简介](#简介)
2. [核心接口说明](#核心接口说明)
3. [订单状态机与处理流程](#订单状态机与处理流程)
4. [回调处理机制](#回调处理机制)
5. [状态重置安全限制](#状态重置安全限制)
6. [客户端实现指南](#客户端实现指南)
7. [性能优化与限流策略](#性能优化与限流策略)
8. [异常恢复场景](#异常恢复场景)
9. [安全验证机制](#安全验证机制)
10. [总结](#总结)

## 简介
本文档详细说明沃尔玛卡密订单处理系统的API接口，涵盖订单提交、第三方回调处理和订单状态重置等核心功能。系统采用微服务架构，通过RESTful API提供服务，支持高并发订单处理和安全回调验证。文档重点阐述沃尔玛卡密订单特有的处理流程，包括订单状态转换规则、回调验证机制和状态重置的安全限制，为开发者提供完整的集成指南。

## 核心接口说明

### 订单提交接口
**HTTP方法**: POST  
**URL模式**: `/cardInfo/walmart/order/submit`  
**认证机制**: JWT令牌认证  

**请求参数**:
- `cardNo`: 卡号 (字符串)
- `giftCardPwd`: 礼品卡密码 (字符串, 必填)
- `notifyUrl`: 回调地址 (字符串, 必填)
- `merchantId`: 商户ID (字符串, 必填)
- `attach`: 附加信息 (字符串)
- `amount`: 充值金额 (浮点数, 必填)

**响应模式**: 空响应体，HTTP状态码表示操作结果

**功能说明**: 接收沃尔玛卡密充值请求，创建待处理订单并触发核销流程。订单创建后立即返回，实际处理在后台异步执行。

**Section sources**
- [order.go](file://api/card_info_walmart/v1/order.go#L6-L28)
- [card_info_walmart_v1_submit.go](file://internal/controller/card_info_walmart/card_info_walmart_v1_submit.go#L1-L32)

### 订单回调接口
**HTTP方法**: GET  
**URL模式**: `/cardInfo/walmart/order/callback`  
**认证机制**: JWT令牌认证  

**请求参数**:
- `orderNo`: 订单ID (字符串, 必填)

**响应模式**: 空响应体，HTTP状态码表示操作结果

**功能说明**: 手动触发对第三方商户的回调操作。仅当订单处于成功或失败状态且未回调时可执行。

**Section sources**
- [order.go](file://api/card_info_walmart/v1/order.go#L58-L67)
- [card_info_walmart_v1_order_callback.go](file://internal/controller/card_info_walmart/card_info_walmart_v1_order_callback.go#L1-L52)

### 订单状态重置接口
**HTTP方法**: PUT  
**URL模式**: `/cardInfo/walmart/order/statusReset`  
**认证机制**: JWT令牌认证  

**请求参数**:
- `id`: 订单ID (字符串, 必填)

**响应模式**: 空响应体，HTTP状态码表示操作结果

**功能说明**: 重置订单状态，仅允许将状态为"最大限制"的订单重置为待处理状态，确保系统安全。

**Section sources**
- [order.go](file://api/card_info_walmart/v1/order.go#L69-L77)
- [card_info_walmart_v1_order_status_reset.go](file://internal/controller/card_info_walmart/card_info_walmart_v1_order_status_reset.go#L1-L29)

## 订单状态机与处理流程

```mermaid
stateDiagram-v2
[*] --> 待处理
待处理 --> 处理中 : 开始处理
处理中 --> 充值成功 : 验证通过
处理中 --> 充值失败 : 验证失败
处理中 --> 账号失效 : 账号问题
处理中 --> 卡密类型错误 : 类型不匹配
处理中 --> 卡片过期 : 过期验证
充值成功 --> 回调成功 : 成功回调
充值失败 --> 回调失败 : 失败回调
回调成功 --> [*]
回调失败 --> [*]
充值成功 --> 订单禁用 : 最大调用次数
订单禁用 --> 待处理 : 手动重置
```

**Diagram sources**
- [card_redeem.go](file://internal/consts/card_redeem.go#L100-L200)
- [status.go](file://internal/logic/card_redeem_order/status.go#L12-L49)

**Section sources**
- [card_redeem.go](file://internal/consts/card_redeem.go#L100-L252)
- [v_1_card_redeem_order_info.go](file://internal/model/entity/v_1_card_redeem_order_info.go#L1-L34)

## 回调处理机制

```mermaid
sequenceDiagram
participant 客户端
participant 控制器
participant 服务层
participant 第三方商户
客户端->>控制器 : GET /callback?orderNo=123
控制器->>服务层 : 验证用户权限
服务层-->>控制器 : 权限验证结果
控制器->>服务层 : 查询订单状态
服务层-->>控制器 : 订单信息
控制器->>服务层 : 验证订单状态
服务层-->>控制器 : 状态验证结果
控制器->>服务层 : 触发回调流程
服务层->>服务层 : 生成签名参数
服务层->>第三方商户 : POST notifyUrl
第三方商户-->>服务层 : 响应结果
服务层->>服务层 : 更新回调状态
服务层-->>控制器 : 回调结果
控制器-->>客户端 : HTTP响应
```

**Diagram sources**
- [card_info_walmart_v1_order_callback.go](file://internal/controller/card_info_walmart/card_info_walmart_v1_order_callback.go#L1-L52)
- [callback.go](file://internal/logic/card_redeem_order/callback.go#L27-L121)

**Section sources**
- [card_info_walmart_v1_order_callback.go](file://internal/controller/card_info_walmart/card_info_walmart_v1_order_callback.go#L1-L52)
- [callback.go](file://internal/logic/card_redeem_order/callback.go#L27-L150)

## 状态重置安全限制

```mermaid
flowchart TD
开始[状态重置请求] --> 验证[验证订单存在]
验证 --> 查询[查询订单实体]
查询 --> 检查状态[检查当前状态]
检查状态 --> 是否为最大限制{状态是否为<br/>最大限制?}
是否为最大限制 --> |是| 重置状态[重置为待处理]
是否为最大限制 --> |否| 返回错误[返回操作失败]
重置状态 --> 重置原始状态[重置订单原本状态]
重置原始状态 --> 重置回调次数[重置回调次数为0]
重置回调次数 --> 结束[操作成功]
返回错误 --> 结束
```

**Diagram sources**
- [card_info_walmart_v1_order_status_reset.go](file://internal/controller/card_info_walmart/card_info_walmart_v1_order_status_reset.go#L1-L29)
- [status.go](file://internal/logic/card_redeem_order/status.go#L12-L49)

**Section sources**
- [card_info_walmart_v1_order_status_reset.go](file://internal/controller/card_info_walmart/card_info_walmart_v1_order_status_reset.go#L1-L29)
- [status.go](file://internal/logic/card_redeem_order/status.go#L12-L73)

## 客户端实现指南

### 订单提交流程
1. 准备请求参数，确保包含必填字段
2. 使用JWT令牌进行身份认证
3. 发送POST请求到提交接口
4. 处理响应，记录订单号用于后续查询

### 第三方回调处理
1. 在商户系统中配置notifyUrl
2. 实现回调接收端点，验证签名
3. 根据回调参数更新本地订单状态
4. 返回"success"确认接收

### 错误处理建议
- 对于重复订单错误，使用唯一订单号避免重复提交
- 对于账号频繁错误，实现指数退避重试策略
- 对于验证失败错误，检查卡密格式和有效性

**Section sources**
- [card_info_walmart_v1_submit.go](file://internal/controller/card_info_walmart/card_info_walmart_v1_submit.go#L1-L32)
- [callback.go](file://internal/logic/card_redeem_order/callback.go#L122-L150)

## 性能优化与限流策略

```mermaid
flowchart LR
客户端 --> |高并发请求| 限流器
限流器 --> |令牌桶算法| 核销触发器
核销触发器 --> |异步处理| 工作池
工作池 --> |并发消费| 账号分配
账号分配 --> |预扣款| 第三方接口
第三方接口 --> |绑定卡密| 响应处理
响应处理 --> |更新状态| 数据库
数据库 --> |回调通知| 商户系统
```

**Diagram sources**
- [consume.go](file://internal/logic/card_redeem_order/consume.go#L244-L357)
- [card_redeem_order.go](file://internal/service/card_redeem_order.go#L1-L80)

**Section sources**
- [consume.go](file://internal/logic/card_redeem_order/consume.go#L1-L357)
- [card_redeem_order.go](file://internal/service/card_redeem_order.go#L1-L80)

## 异常恢复场景

### 订单状态异常恢复
当订单因系统故障处于异常状态时，可通过状态重置接口恢复处理。仅允许重置状态为"订单禁用，最大调用次数"的订单，确保不会影响正常处理流程。

### 回调失败恢复
系统自动重试回调3次，每次间隔递增。若全部失败，可通过手动回调接口重新触发。商户应确保回调端点的高可用性，避免丢失通知。

### 数据一致性保障
使用数据库事务确保状态变更的原子性。在账号分配和预扣款操作中使用事务锁，防止并发问题导致的数据不一致。

**Section sources**
- [card_info_walmart_v1_order_status_reset.go](file://internal/controller/card_info_walmart/card_info_walmart_v1_order_status_reset.go#L1-L29)
- [callback.go](file://internal/logic/card_redeem_order/callback.go#L27-L121)
- [consume.go](file://internal/logic/card_redeem_order/consume.go#L1-L357)

## 安全验证机制

### 回调签名验证
回调请求包含时间戳和签名参数，商户需使用共享密钥验证签名有效性，防止伪造请求。

### 权限控制
所有接口均需JWT令牌认证，确保只有授权用户可访问。回调接口额外验证订单归属，防止越权操作。

### 配置安全
通过系统配置字典控制关键策略，如金额异议回调、补卡自动回调等，提供灵活的安全策略管理。

**Section sources**
- [callback.go](file://internal/logic/card_redeem_order/callback.go#L122-L150)
- [sys_config_dict.go](file://internal/service/sys_config_dict.go#L1-L81)

## 总结
沃尔玛卡密订单处理系统提供了完整的订单生命周期管理功能，从提交、处理到回调和状态重置。系统设计注重安全性、可靠性和性能，通过状态机管理订单流转，使用异步处理提高吞吐量，并提供灵活的配置选项满足不同商户需求。开发者应遵循本文档的实现指南，确保正确集成和使用API接口。