# 沃尔玛兑换配置

<cite>
**本文档引用文件**  
- [kami-api-card-info-walmart-v1-redeem-config-get-res.ts](file://src/api/generated/models/kami-api-card-info-walmart-v1-redeem-config-get-res.ts)
- [kami-api-card-info-walmart-v1-redeem-config-set-req.ts](file://src/api/generated/models/kami-api-card-info-walmart-v1-redeem-config-set-req.ts)
- [card-walmart-order.ts](file://src/api/card-walmart-order.ts)
- [card-walmart-account.ts](file://src/api/card-walmart-account.ts)
- [index.vue](file://src/views/card-walmart-info/order/index.vue)
</cite>

## 目录

1. [介绍](#介绍)
2. [核心组件](#核心组件)
3. [兑换配置接口详解](#兑换配置接口详解)
4. [配置参数说明](#配置参数说明)
5. [业务逻辑与验证规则](#业务逻辑与验证规则)
6. [前端调用示例](#前端调用示例)
7. [与账户管理及订单处理的关联](#与账户管理及订单处理的关联)
8. [配置管理最佳实践](#配置管理最佳实践)
9. [错误处理与安全考虑](#错误处理与安全考虑)

## 介绍

本文档详细介绍了沃尔玛兑换配置功能的实现机制，涵盖配置的获取与设置操作、核心接口的使用方法、配置参数的业务含义以及其在系统中的集成方式。文档旨在为开发人员和系统管理员提供全面的技术参考，确保兑换配置功能的正确使用和高效管理。

## 核心组件

本功能的核心组件包括用于获取和设置兑换配置的API接口模型、执行HTTP请求的API服务函数，以及用于展示和管理配置的前端视图组件。这些组件协同工作，实现了兑换配置的完整生命周期管理。

**本节来源**

- [kami-api-card-info-walmart-v1-redeem-config-get-res.ts](file://src/api/generated/models/kami-api-card-info-walmart-v1-redeem-config-get-res.ts)
- [kami-api-card-info-walmart-v1-redeem-config-set-req.ts](file://src/api/generated/models/kami-api-card-info-walmart-v1-redeem-config-set-req.ts)
- [card-walmart-order.ts](file://src/api/card-walmart-order.ts)
- [card-walmart-account.ts](file://src/api/card-walmart-account.ts)

## 兑换配置接口详解

### 获取兑换配置 (Get)

`KamiApiCardInfoWalmartV1RedeemConfigGetRes` 接口用于从服务器获取当前的沃尔玛兑换配置。该接口返回一个包含所有配置项的对象。

- **HTTP方法**: GET
- **请求路径**: `/api/cardInfo/walmart/config/get`
- **响应模型**: `KamiApiCardInfoWalmartV1RedeemConfigGetRes`

前端通过 `getWalmartConfig()` 函数调用此接口，该函数封装了axios的GET请求。

### 设置兑换配置 (Set)

`KamiApiCardInfoWalmartV1RedeemConfigSetReq` 接口用于向服务器提交新的兑换配置。该接口需要一个包含所有必填配置项的对象作为请求体。

- **HTTP方法**: POST (或PUT，具体取决于后端实现)
- **请求路径**: `/api/cardInfo/walmart/config/set` (路径需根据实际后端API确定)
- **请求体模型**: `KamiApiCardInfoWalmartV1RedeemConfigSetReq`

**本节来源**

- [kami-api-card-info-walmart-v1-redeem-config-get-res.ts](file://src/api/generated/models/kami-api-card-info-walmart-v1-redeem-config-get-res.ts#L19-L74)
- [kami-api-card-info-walmart-v1-redeem-config-set-req.ts](file://src/api/generated/models/kami-api-card-info-walmart-v1-redeem-config-set-req.ts#L19-L74)
- [card-walmart-order.ts](file://src/api/card-walmart-order.ts#L118-L122)

## 配置参数说明

下表详细说明了 `KamiApiCardInfoWalmartV1RedeemConfigGetRes` 和 `KamiApiCardInfoWalmartV1RedeemConfigSetReq` 接口中定义的各个配置参数。

| 参数名                            | 类型          | 是否必填 | 描述                                                                                                           |
| :-------------------------------- | :------------ | :------- | :------------------------------------------------------------------------------------------------------------- |
| `isAllowDifferentAmount`          | boolean       | 是       | **是否允许金额异议充值**。当用户提交的充值金额与卡面金额不一致时，是否允许系统继续处理该订单。                 |
| `isAllowDifferentSucceedCallback` | boolean       | 是       | **是否允许金额异议回调(充值成功)**。当金额异议充值成功后，是否向商户系统发送成功回调通知。                     |
| `isAllowDifferentFailCallback`    | boolean       | 是       | **是否允许金额异议回调(充值失败)**。当金额异议充值失败后，是否向商户系统发送失败回调通知。                     |
| `redeemCardMinAmount`             | number        | 是       | **充值卡最小充值金额**。系统允许的单次充值最低金额限制。                                                       |
| `isAllowCompensatedCallback`      | boolean       | 是       | **是否允许补卡自动回调**。当系统自动为用户补发卡片后，是否自动向商户系统发送补卡成功的回调通知。               |
| `redeemCardRate`                  | number        | 是       | **充值卡充值速率**。可能指单位时间内允许的最大充值次数或金额，用于控制充值频率。                               |
| `isCardAllowRepeated`             | boolean       | 是       | **是否允许重复充值**。是否允许对同一张礼品卡进行多次充值操作。                                                 |
| `maxAccountRedeemCount`           | number        | 否       | **单个账户单日最大充值次数**。限制单个沃尔玛账户在24小时内允许的最大充值次数。                                 |
| `redeemOrderScheduleStrategy`     | string (enum) | 否       | **充值订单调度策略**。定义了如何为订单分配处理账户的策略。可选值：`normal` (正常顺序) 或 `random` (随机分配)。 |

**本节来源**

- [kami-api-card-info-walmart-v1-redeem-config-get-res.ts](file://src/api/generated/models/kami-api-card-info-walmart-v1-redeem-config-get-res.ts#L19-L74)
- [kami-api-card-info-walmart-v1-redeem-config-set-req.ts](file://src/api/generated/models/kami-api-card-info-walmart-v1-redeem-config-set-req.ts#L19-L74)

## 业务逻辑与验证规则

兑换配置的业务逻辑围绕着风险控制、用户体验和系统稳定性展开。

1.  **金额异议处理**：通过 `isAllowDifferentAmount` 及其相关的回调开关，系统可以灵活处理用户输入的金额与卡面金额不符的情况。管理员可以根据业务需求决定是严格匹配还是允许一定范围内的差异。
2.  **频率与额度控制**：`redeemCardMinAmount` 和 `maxAccountRedeemCount` 参数共同作用，防止小额、高频的恶意充值，保护账户安全和系统资源。
3.  **调度策略**：`redeemOrderScheduleStrategy` 决定了订单处理的负载均衡方式。`normal` 策略可能按账户列表顺序分配，而 `random` 策略则可以更均匀地分散负载。
4.  **数据一致性**：`isCardAllowRepeated` 参数确保了对同一张卡的充值行为是幂等的，避免了因重复操作导致的数据错误。

**本节来源**

- [kami-api-card-info-walmart-v1-redeem-config-get-res.ts](file://src/api/generated/models/kami-api-card-info-walmart-v1-redeem-config-get-res.ts)
- [kami-api-card-info-walmart-v1-redeem-config-set-req.ts](file://src/api/generated/models/kami-api-card-info-walmart-v1-redeem-config-set-req.ts)

## 前端调用示例

以下代码片段展示了如何在前端调用相关API来读取和更新兑换配置。

```typescript
import { getWalmartConfig } from '@/api/card-walmart-order';
import { apiClient } from '@/api';

// 读取兑换配置
async function fetchRedeemConfig() {
  try {
    const response = await getWalmartConfig();
    const config = response.data;
    console.log('当前兑换配置:', config);
    // 在表单中填充配置
  } catch (error) {
    console.error('获取配置失败:', error);
  }
}

// 更新兑换配置
async function updateRedeemConfig(newConfig) {
  try {
    // 假设后端有一个对应的set接口
    await apiClient.apiCardInfoWalmartConfigSetPost({
      kamiApiCardInfoWalmartV1RedeemConfigSetReq: newConfig
    });
    Message.success('配置更新成功');
  } catch (error) {
    Message.error('配置更新失败');
    console.error('更新配置失败:', error);
  }
}
```

**本节来源**

- [card-walmart-order.ts](file://src/api/card-walmart-order.ts#L118-L122)
- [index.vue](file://src/views/card-walmart-info/order/index.vue)

## 与账户管理及订单处理的关联

兑换配置是连接账户管理和订单处理的核心枢纽。

- **与账户管理关联**：配置中的 `maxAccountRedeemCount` 直接作用于 `KamiApiCardInfoWalmartV1AccountListRecord` 中的账户实体。当账户的当日充值次数达到上限时，系统会拒绝新的充值请求，状态可能标记为“禁用(充值次数超限)”。
- **与订单处理关联**：所有订单在创建和处理过程中，都会实时查询并应用当前的兑换配置。例如，在 `queryWalmartCardOrderList` 的处理流程中，会根据 `isAllowDifferentAmount` 规则判断订单是否有效，并根据 `redeemOrderScheduleStrategy` 决定由哪个账户执行充值。

```mermaid
flowchart TD
A[商户创建充值订单] --> B{系统检查兑换配置}
B --> C[金额是否匹配?]
C --> |是| D[进入处理队列]
C --> |否| E{isAllowDifferentAmount?}
E --> |是| D
E --> |否| F[拒绝订单]
D --> G{根据redeemOrderScheduleStrategy<br/>分配处理账户}
G --> H[执行充值操作]
H --> I[更新订单状态]
I --> J{充值成功?}
J --> |是| K{isAllowCompensatedCallback?}
J --> |否| L{isAllowDifferentFailCallback?}
K --> |是| M[发送补卡成功回调]
K --> |否| N[不发送回调]
L --> |是| O[发送充值失败回调]
L --> |否| P[不发送回调]
```

**图表来源**

- [kami-api-card-info-walmart-v1-redeem-config-get-res.ts](file://src/api/generated/models/kami-api-card-info-walmart-v1-redeem-config-get-res.ts)
- [card-walmart-account.ts](file://src/api/card-walmart-account.ts)
- [card-walmart-order.ts](file://src/api/card-walmart-order.ts)

## 配置管理最佳实践

1.  **版本控制**：虽然前端配置是动态的，但建议将重要的配置变更记录在案，或通过后端实现配置版本管理，以便于回滚和审计。
2.  **灰度发布**：在修改关键配置（如关闭金额异议）时，应先在小范围内测试，确认无误后再全量发布，以降低业务风险。
3.  **监控与告警**：建立对配置变更的监控，当关键配置被修改时，应有通知机制。同时，监控因配置规则（如次数超限）被拒绝的订单数量，及时发现异常。

**本节来源**

- [kami-api-card-info-walmart-v1-redeem-config-get-res.ts](file://src/api/generated/models/kami-api-card-info-walmart-v1-redeem-config-get-res.ts)
- [kami-api-card-info-walmart-v1-redeem-config-set-req.ts](file://src/api/generated/models/kami-api-card-info-walmart-v1-redeem-config-set-req.ts)

## 错误处理与安全考虑

1.  **输入验证**：前端在提交 `KamiApiCardInfoWalmartV1RedeemConfigSetReq` 时，应对所有数值型参数（如 `redeemCardMinAmount`）进行非负、非零等基本验证。
2.  **权限控制**：设置兑换配置的API必须进行严格的权限校验，仅允许系统管理员或特定角色的用户访问。
3.  **错误处理**：前端应妥善处理API调用失败的情况，例如网络错误或后端验证失败，并向用户给出清晰的错误提示。
4.  **数据安全**：配置数据本身不包含敏感信息，但其变更会影响核心业务流程，因此API传输应通过HTTPS加密。

**本节来源**

- [card-walmart-order.ts](file://src/api/card-walmart-order.ts)
- [card-walmart-account.ts](file://src/api/card-walmart-account.ts)
