# Apple Card充值历史API

<cite>
**Referenced Files in This Document**  
- [apple-card-recharge-history.ts](file://src/api/apple-card-recharge-history.ts)
- [kami-api-card-info-apple-v1-recharge-history-list-req.ts](file://src/api/generated/models/kami-api-card-info-apple-v1-recharge-history-list-req.ts)
- [kami-api-card-info-apple-v1-recharge-history-list-res.ts](file://src/api/generated/models/kami-api-card-info-apple-v1-recharge-history-list-res.ts)
- [kami-internal-model-entity-v1-card-apple-history-info.ts](file://src/api/generated/models/kami-internal-model-entity-v1-card-apple-history-info.ts)
- [KamiApiCardInfoAppleV1RechargeHandlerReq.md](file://src/api/generated/docs/KamiApiCardInfoAppleV1RechargeHandlerReq.md)
- [KamiApiCardInfoAppleV1RechargeOrderResetStatusReq.md](file://src/api/generated/docs/KamiApiCardInfoAppleV1RechargeOrderResetStatusReq.md)
</cite>

## 目录

1. [简介](#简介)
2. [核心模型结构](#核心模型结构)
3. [查询接口参数过滤机制](#查询接口参数过滤机制)
4. [充值订单状态变更接口](#充值订单状态变更接口)
5. [特殊操作API调用方式](#特殊操作api调用方式)
6. [数据获取与处理示例](#数据获取与处理示例)
7. [性能优化建议](#性能优化建议)

## 简介

本文档详细介绍了Apple Card充值历史查询API的功能和使用方法。该API系统为开发者提供了完整的充值历史管理能力，包括历史记录查询、订单状态管理、操作日志获取等功能。通过本API，可以实现对Apple Card充值订单的全面监控和管理。

## 核心模型结构

### 请求模型：KamiApiCardInfoAppleV1RechargeHistoryListReq

该请求模型用于查询Apple Card充值历史记录，主要包含以下属性：

**Section sources**

- [kami-api-card-info-apple-v1-recharge-history-list-req.ts](file://src/api/generated/models/kami-api-card-info-apple-v1-recharge-history-list-req.ts#L19-L26)

### 响应模型：KamiApiCardInfoAppleV1RechargeHistoryListRes

该响应模型包含充值历史记录的列表数据，其结构如下：

```mermaid
classDiagram
class KamiApiCardInfoAppleV1RechargeHistoryListRes {
+list : Array<KamiInternalModelEntityV1CardAppleHistoryInfo>
}
class KamiInternalModelEntityV1CardAppleHistoryInfo {
+id : number
+accountId : string
+orderNo : string
+rechargeId : number
+operation : string
+remark : string
+createdAt : string
+accountName : string
}
KamiApiCardInfoAppleV1RechargeHistoryListRes --> KamiInternalModelEntityV1CardAppleHistoryInfo : "包含"
```

**Diagram sources**

- [kami-api-card-info-apple-v1-recharge-history-list-res.ts](file://src/api/generated/models/kami-api-card-info-apple-v1-recharge-history-list-res.ts#L23-L30)
- [kami-internal-model-entity-v1-card-apple-history-info.ts](file://src/api/generated/models/kami-internal-model-entity-v1-card-apple-history-info.ts#L19-L68)

**Section sources**

- [kami-api-card-info-apple-v1-recharge-history-list-res.ts](file://src/api/generated/models/kami-api-card-info-apple-v1-recharge-history-list-res.ts#L23-L30)
- [kami-internal-model-entity-v1-card-apple-history-info.ts](file://src/api/generated/models/kami-internal-model-entity-v1-card-apple-history-info.ts#L19-L68)

## 查询接口参数过滤机制

### 时间范围筛选

API支持通过时间范围参数进行筛选，开发者可以使用`dateRange`参数指定查询的时间区间。系统会自动将`dateRange`转换为`startDate`和`endDate`参数进行查询。

### 状态筛选

通过`operation`字段可以筛选不同状态的充值记录，支持的状态包括：

- created：订单创建
- failed：充值失败
- recharging：充值中

### 分页处理

API实现了标准的分页机制，通过`Pagination`接口提供分页功能，包含页码和每页大小等参数。

```mermaid
flowchart TD
Start([开始查询]) --> ValidateParams["验证参数"]
ValidateParams --> CheckDateRange{"是否有dateRange?"}
CheckDateRange --> |是| ProcessDateRange["处理日期范围"]
ProcessDateRange --> SetStartDate["设置startDate"]
SetStartDate --> SetEndDate["设置endDate"]
CheckDateRange --> |否| SkipDateProcess["跳过日期处理"]
SetEndDate --> RemoveDateRange["移除dateRange参数"]
SkipDateProcess --> RemoveDateRange
RemoveDateRange --> MakeRequest["发起API请求"]
MakeRequest --> End([结束])
```

**Section sources**

- [apple-card-recharge-history.ts](file://src/api/apple-card-recharge-history.ts#L27-L55)

## 充值订单状态变更接口

### 手动回调订单

通过`callBackOrderManualAPI`接口可以手动触发订单回调，适用于需要重新通知业务系统的场景。

### 修改实际充值金额

`modityActualAmountAPI`接口允许修改订单的实际充值金额，需要提供TOTP验证码进行安全验证。

### 设置订单成功状态

`modifyStatusToSucceedAPI`接口可将指定订单状态设置为成功，用于处理特殊情况下的订单状态更新。

```mermaid
sequenceDiagram
participant Client as "客户端"
participant API as "API服务"
participant System as "业务系统"
Client->>API : 调用modifyStatusToSucceedAPI
API->>API : 验证订单权限
API->>System : 更新订单状态为成功
System-->>API : 返回更新结果
API-->>Client : 返回操作结果
Note over Client,System : 订单状态成功变更流程
```

**Section sources**

- [apple-card-recharge-history.ts](file://src/api/apple-card-recharge-history.ts#L77-L85)

## 特殊操作API调用方式

### 重复卡券处理

系统提供了处理重复卡券的机制，可以通过特定接口识别和处理重复的充值请求。

### 订单状态重置

`resetOrderStatusAPI`接口用于重置订单状态，使订单回到初始状态，便于重新处理。

```mermaid
flowchart LR
A[重置订单状态] --> B[验证订单号]
B --> C{订单是否存在?}
C --> |是| D[检查订单当前状态]
C --> |否| E[返回错误]
D --> F{是否允许重置?}
F --> |是| G[重置状态并清空记录]
F --> |否| H[返回权限错误]
G --> I[返回成功]
```

**Section sources**

- [apple-card-recharge-history.ts](file://src/api/apple-card-recharge-history.ts#L118-L125)
- [KamiApiCardInfoAppleV1RechargeOrderResetStatusReq.md](file://src/api/generated/docs/KamiApiCardInfoAppleV1RechargeOrderResetStatusReq.md#L1-L22)

## 数据获取与处理示例

### 获取充值列表

```typescript
const params = {
  orderNo: 'ORDER123',
  dateRange: [startDate, endDate],
  page: 1,
  size: 20
};

queryAppleCardRechargeOrderList(params).then(response => {
  // 处理返回的充值列表数据
  console.log(response.data.list);
});
```

### 获取操作历史

```typescript
queryAppleCardOperationHistoryList({ orderNo: 'ORDER123' }).then(response => {
  // 处理操作历史记录
  console.log(response.data);
});
```

### 下载数据

```typescript
downloadDataListApi({ orderNo: 'ORDER123' }).then(() => {
  // 数据已下载为apple.xlsx文件
  console.log('下载完成');
});
```

**Section sources**

- [apple-card-recharge-history.ts](file://src/api/apple-card-recharge-history.ts#L57-L116)

## 性能优化建议

### 分页大小设置

建议将分页大小设置在20-50条记录之间，避免一次性获取过多数据导致性能下降。

### 缓存策略

对于频繁查询但变化不频繁的数据，建议在客户端实现缓存机制，减少API调用次数。

### 批量操作

当需要处理多个订单时，尽量使用批量接口而非逐个调用，提高处理效率。

### 错误处理

实现完善的错误处理机制，对网络异常、接口错误等情况进行妥善处理，确保系统的稳定性。
