# 沃尔玛账户管理

<cite>
**本文档中引用的文件**  
- [kami-api-card-info-walmart-v1-account-create-req.ts](file://src/api/generated/models/kami-api-card-info-walmart-v1-account-create-req.ts)
- [kami-api-card-info-walmart-v1-account-update-req.ts](file://src/api/generated/models/kami-api-card-info-walmart-v1-account-update-req.ts)
- [kami-api-card-info-walmart-v1-account-status-detect-req.ts](file://src/api/generated/models/kami-api-card-info-walmart-v1-account-status-detect-req.ts)
- [kami-api-card-info-walmart-v1-account-list-record.ts](file://src/api/generated/models/kami-api-card-info-walmart-v1-account-list-record.ts)
- [card-walmart-account.ts](file://src/api/card-walmart-account.ts)
</cite>

## 目录

1. [简介](#简介)
2. [核心功能概览](#核心功能概览)
3. [账户创建与更新](#账户创建与更新)
4. [账户状态检测与刷新](#账户状态检测与刷新)
5. [账户列表与数据查询](#账户列表与数据查询)
6. [钱包信息与余额查询](#钱包信息与余额查询)
7. [批量操作与数据导入导出](#批量操作与数据导入导出)
8. [错误处理与最佳实践](#错误处理与最佳实践)
9. [前端API调用示例](#前端api调用示例)

## 简介

本文档详细介绍了沃尔玛账户管理功能的实现机制，涵盖账户的创建、更新、删除、状态检测、每日摘要、钱包信息查询等核心操作。文档深入解析了关键请求参数的使用方法，阐述了账户列表展示、批量操作、数据导入导出等功能的实现细节，并提供了集成API服务的最佳实践建议。

## 核心功能概览

沃尔玛账户管理系统提供了一套完整的账户生命周期管理功能，包括：

- 账户的增删改查（CRUD）操作
- 账户状态的实时检测与同步
- 账户列表的分页查询与筛选
- 钱包交易历史的查询与分析
- 批量导入导出与模板下载
- 分组管理与数据统计

**Section sources**

- [card-walmart-account.ts](file://src/api/card-walmart-account.ts#L1-L124)

## 账户创建与更新

### 创建请求参数详解

`KamiApiCardInfoWalmartV1AccountCreateReq` 接口定义了创建沃尔玛账户所需的参数：

- `cookie`：必填项，用于身份验证的Cookie信息
- `name`：可选项，账户的别名标识
- `groupId`：可选项，所属分组ID
- `maxAmountLimit`：必填项，单次最大充值金额限制
- `maxCountLimit`：必填项，每日最大充值次数限制
- `status`：可选项，账户初始状态（启用/禁用）
- `remark`：可选项，备注信息

### 更新请求参数详解

`KamiApiCardInfoWalmartV1AccountUpdateReq` 接口在创建请求的基础上增加了 `id` 字段，用于指定要更新的账户唯一标识。

### API调用方法

- **创建账户**：调用 `addWalmartCard(data)` 方法，发送POST请求至 `/api/cardInfo/walmart/account/create`
- **更新账户**：调用 `updateWalmartCard(data)` 方法，发送PUT请求至 `/api/cardInfo/walmart/account/update`
- **删除账户**：调用 `deleteWalmartCard(params)` 方法，发送DELETE请求并携带ID参数

**Section sources**

- [kami-api-card-info-walmart-v1-account-create-req.ts](file://src/api/generated/models/kami-api-card-info-walmart-v1-account-create-req.ts#L19-L62)
- [kami-api-card-info-walmart-v1-account-update-req.ts](file://src/api/generated/models/kami-api-card-info-walmart-v1-account-update-req.ts#L19-L68)
- [card-walmart-account.ts](file://src/api/card-walmart-account.ts#L40-L52)

## 账户状态检测与刷新

### 状态检测

通过 `KamiApiCardInfoWalmartV1AccountStatusDetectReq` 接口，仅需提供账户的 `id` 即可发起状态检测请求。后端将返回 `KamiApiCardInfoWalmartV1AccountStatusDetectRes` 响应，其中包含一个布尔类型的 `status` 字段，表示账户当前是否可用。

### 状态刷新

调用 `refreshWalmartCardStatus(data)` 方法，传入账户ID，可强制刷新账户的当前状态。此操作会重新验证Cookie的有效性并更新账户的 `accountStatus` 字段。

**Section sources**

- [kami-api-card-info-walmart-v1-account-status-detect-req.ts](file://src/api/generated/models/kami-api-card-info-walmart-v1-account-status-detect-req.ts#L19-L26)
- [kami-api-card-info-walmart-v1-account-status-detect-res.ts](file://src/api/generated/models/kami-api-card-info-walmart-v1-account-status-detect-res.ts#L1-L27)
- [card-walmart-account.ts](file://src/api/card-walmart-account.ts#L75-L77)

## 账户列表与数据查询

### 列表查询

`queryWalmartCardList(params)` 方法用于获取账户列表。它接受一个包含分页、筛选和排序参数的 `WalmartCardParams` 对象，并返回 `CommonPageResult<KamiApiCardInfoWalmartV1AccountListRecord>` 类型的数据。

### 响应数据结构

`KamiApiCardInfoWalmartV1AccountListRecord` 包含了账户的完整信息：

- 基础信息：`id`, `name`, `nickname`, `username`
- 余额信息：`balance`（余额）, `effectiveBalance`（有效充值余额）
- 统计信息：`amountTotalSum`（总充值金额）, `amountTodaySum`（今日充值金额）
- 状态信息：`status`（管理状态）, `accountStatus`（账号是否可用）
- 时间戳：`createdAt`, `updatedAt`

**Section sources**

- [kami-api-card-info-walmart-v1-account-list-record.ts](file://src/api/generated/models/kami-api-card-info-walmart-v1-account-list-record.ts#L1-L163)
- [kami-api-card-info-walmart-v1-account-list-res.ts](file://src/api/generated/models/kami-api-card-info-walmart-v1-account-list-res.ts#L1-L37)
- [card-walmart-account.ts](file://src/api/card-walmart-account.ts#L59-L69)

## 钱包信息与余额查询

### 钱包交易历史

通过 `queryWalmartAccountWalletList(params)` 方法，可以查询指定账户的钱包交易历史。该方法返回 `CommonPageResult<KamiInternalModelEntityV1CardRedeemAccountHistory>` 类型的数据。

### 交易记录结构

`KamiInternalModelEntityV1CardRedeemAccountHistory` 定义了每条交易记录的字段：

- `orderNo`：关联的订单号
- `amount`：本次金额变化
- `effectiveBalance`：操作后的有效余额
- `balance`：操作后的总余额
- `operationStatus`：操作状态（如“充值成功”）
- `remark`：操作备注

**Section sources**

- [kami-internal-model-entity-v1-card-redeem-account-history.ts](file://src/api/generated/models/kami-internal-model-entity-v1-card-redeem-account-history.ts#L1-L99)
- [kami-api-card-info-walmart-v1-account-wallet-list-res.ts](file://src/api/generated/models/kami-api-card-info-walmart-v1-account-wallet-list-res.ts#L1-L37)
- [card-walmart-account.ts](file://src/api/card-walmart-account.ts#L70-L74)

## 批量操作与数据导入导出

### 批量添加

`batchAdd(data)` 方法支持通过数组形式一次性添加多个账户，数据结构为 `KamiApiCardInfoWalmartV1AccountCookieBatchInfo`。

### 模板下载

`downloadWalmartCardData()` 方法用于下载批量导入所需的Excel模板文件，确保用户按照正确格式准备数据。

### 数据导出

`downloadDataList()` 方法可将当前查询到的账户列表数据导出为Excel文件，便于离线分析和存档。

**Section sources**

- [card-walmart-account.ts](file://src/api/card-walmart-account.ts#L80-L94)

## 错误处理与最佳实践

### 错误处理

- **Cookie验证**：在创建或更新账户前，应先调用 `detectCookie(data)` 方法验证Cookie的有效性。
- **网络异常**：所有API调用都应包裹在try-catch块中，处理网络超时或服务不可用的情况。
- **数据校验**：前端应根据接口定义对输入数据进行严格校验，避免发送无效请求。

### 最佳实践

- **状态同步**：定期调用 `refreshWalmartCardStatus` 以保持账户状态的实时性。
- **性能优化**：利用分页参数 `Pagination` 避免一次性加载过多数据。
- **安全性**：敏感的Cookie信息应在传输过程中加密，且不在前端日志中打印。

**Section sources**

- [card-walmart-account.ts](file://src/api/card-walmart-account.ts#L96-L99)

## 前端API调用示例

### 创建账户示例

```typescript
const createData: KamiApiCardInfoWalmartV1AccountCreateReq = {
  cookie: 'your_walmart_cookie_here',
  name: '我的沃尔玛账户',
  maxAmountLimit: 500,
  maxCountLimit: 10
};

addWalmartCard(createData)
  .then(response => {
    console.log('账户创建成功');
  })
  .catch(error => {
    console.error('创建失败:', error.response?.data || error.message);
  });
```

### 查询账户列表示例

```typescript
const queryParams: WalmartCardParams = {
  page: 1,
  size: 20,
  name: '沃尔玛'
};

queryWalmartCardList(queryParams).then(response => {
  const { list, total } = response.data;
  console.log(`共找到 ${total} 个账户`, list);
});
```

**Section sources**

- [card-walmart-account.ts](file://src/api/card-walmart-account.ts#L40-L69)
