# 充值历史管理

<cite>
**本文档引用文件**  
- [recharge-history.vue](file://src/views/apple-card-info/recharge-history/index.vue)
- [change-amount.vue](file://src/views/apple-card-info/recharge-history/components/change-amount.vue)
- [recharge-history.vue](file://src/views/apple-card-info/recharge-history/components/recharge-history.vue)
- [apple-card-recharge-history.ts](file://src/api/apple-card-recharge-history.ts)
- [KamiApiCardInfoAppleV1RechargeSubmitReq.md](file://src/api/generated/docs/KamiApiCardInfoAppleV1RechargeSubmitReq.md)
- [KamiApiCardInfoAppleV1RechargeOrderResetStatusReq.md](file://src/api/generated/docs/KamiApiCardInfoAppleV1RechargeOrderResetStatusReq.md)
- [DefaultApi.md](file://src/api/generated/docs/DefaultApi.md)
</cite>

## 目录

1. [简介](#简介)
2. [充值订单查询与状态管理](#充值订单查询与状态管理)
3. [数据展示逻辑](#数据展示逻辑)
4. [金额修改流程](#金额修改流程)
5. [核心接口使用说明](#核心接口使用说明)
6. [特殊场景处理机制](#特殊场景处理机制)
7. [数据导出功能](#数据导出功能)
8. [操作最佳实践](#操作最佳实践)

## 简介

本文档详细介绍了Apple Card充值历史管理功能，涵盖充值订单的查询、状态管理、金额修改等核心功能。重点说明了recharge-history.vue组件的数据展示逻辑和change-amount.vue组件的金额修改流程。文档还解释了KamiApiCardInfoAppleV1RechargeSubmitReq充值提交接口和KamiApiCardInfoAppleV1RechargeOrderResetStatusReq订单状态重置接口的使用方法，描述了手动回调处理、重复卡密处理等特殊场景的实现机制，并提供了充值历史数据导出功能的使用指南。

## 充值订单查询与状态管理

系统提供了完整的充值订单查询功能，支持通过账户、系统订单号、商户订单号、卡密、创建时间范围等多种条件进行筛选查询。订单状态通过颜色标签直观展示，包括成功（绿色）、失败（红色）、调度中（橙色）、等待（蓝色）、卡密重复（蓝色）和冻结（红色）等状态。

订单状态管理功能允许管理员对异常订单进行处理，包括手动回调、状态重置和金额修正等操作。系统通过状态码映射机制将数字状态转换为可读的文本描述，并通过不同颜色进行视觉区分，便于快速识别订单状态。

**Section sources**

- [recharge-history.vue](file://src/views/apple-card-info/recharge-history/index.vue#L282-L339)
- [recharge-history.vue](file://src/views/apple-card-info/recharge-history/index.vue#L336-L403)

## 数据展示逻辑

recharge-history.vue组件实现了充值历史数据的表格展示功能。组件使用Arco Design的a-table组件进行数据渲染，通过slot机制自定义列的显示内容。表格包含序号、订单号、系统订单号、商户订单号、分配账号、卡密、卡面金额、支付金额、创建时间和状态等列。

数据展示逻辑包括：

- 序号列通过计算`rowIndex + 1 + (pagination.current - 1) * pagination.pageSize`实现分页序号连续
- 状态列使用`getStatusColorMap`函数将状态码转换为对应的颜色和文本描述
- 操作列提供详情查看、状态重置、金额修正和手动回调等操作按钮
- 支持分页、每页显示条数切换和数据刷新

组件通过`queryAppleCardRechargeOrderList` API获取数据，并在mounted生命周期钩子中自动加载初始数据。

**Section sources**

- [recharge-history.vue](file://src/views/apple-card-info/recharge-history/index.vue#L180-L222)
- [recharge-history.vue](file://src/views/apple-card-info/recharge-history/index.vue#L282-L339)

## 金额修改流程

金额修改功能通过change-amount.vue组件实现，允许管理员修正充值订单的实际金额。该组件以模态框形式展示，包含订单号、卡片金额、实际金额和二次验证等字段。

金额修改流程如下：

1. 用户点击"修正"按钮，触发`showActualAmountModal`函数
2. 显示change-amount模态框，预填充订单信息
3. 用户输入实际金额和TOTP二次验证码
4. 点击确定按钮，触发`handleOk`函数进行表单验证
5. 验证通过后，调用`modityActualAmountAPI`接口提交修改请求
6. 请求成功后关闭模态框并刷新数据列表

该流程确保了金额修改的安全性，通过TOTP二次验证防止误操作。

**Section sources**

- [change-amount.vue](file://src/views/apple-card-info/recharge-history/components/change-amount.vue#L0-L66)
- [recharge-history.vue](file://src/views/apple-card-info/recharge-history/index.vue#L180-L222)

## 核心接口使用说明

### KamiApiCardInfoAppleV1RechargeSubmitReq 充值提交接口

该接口用于提交Apple Card充值请求，接收以下参数：

| 参数        | 类型   | 说明                         |
| ----------- | ------ | ---------------------------- |
| cardNo      | string | 卡号                         |
| cardPass    | string | 密码（必填）                 |
| faceValue   | number | 面值（必填）                 |
| callbackUrl | string | 回调地址                     |
| attach      | string | 附加信息（目前是上游订单号） |
| timeStamp   | number | 时间戳                       |
| sign        | string | 签名                         |
| merchantId  | string | 商户ID                       |

**Section sources**

- [KamiApiCardInfoAppleV1RechargeSubmitReq.md](file://src/api/generated/docs/KamiApiCardInfoAppleV1RechargeSubmitReq.md#L19-L68)

### KamiApiCardInfoAppleV1RechargeOrderResetStatusReq 订单状态重置接口

该接口用于重置充值订单状态，接收以下参数：

| 参数    | 类型   | 说明           |
| ------- | ------ | -------------- |
| orderNo | string | 订单ID（必填） |
| remark  | string | 备注           |

该接口主要用于处理冻结状态（状态码16）的订单，将其重置为可处理状态。

**Section sources**

- [KamiApiCardInfoAppleV1RechargeOrderResetStatusReq.md](file://src/api/generated/docs/KamiApiCardInfoAppleV1RechargeOrderResetStatusReq.md#L19-L32)

## 特殊场景处理机制

### 手动回调处理

对于状态为失败或成功的订单，系统提供手动回调功能。通过调用`callBackOrderManualAPI`接口，可以重新触发订单回调流程，确保订单状态同步。该功能在订单回调失败或需要重新通知下游系统时特别有用。

```mermaid
sequenceDiagram
participant 用户界面
participant recharge-history.vue
participant API
participant 后端服务
用户界面->>recharge-history.vue : 点击"回调"按钮
recharge-history.vue->>API : 调用callBackOrderManualAPI
API->>后端服务 : POST /api/cardInfo/appleCard/rechargeOrder/callbackByManual
后端服务-->>API : 返回结果
API-->>recharge-history.vue : 处理响应
recharge-history.vue-->>用户界面 : 显示"回调成功"消息
```

**Diagram sources**

- [recharge-history.vue](file://src/views/apple-card-info/recharge-history/index.vue#L180-L222)
- [apple-card-recharge-history.ts](file://src/api/apple-card-recharge-history.ts#L82-L90)

### 重复卡密处理

当系统检测到重复卡密时，订单状态会设置为"卡密重复(需人工介入)"（状态码14）。此时需要管理员人工介入处理，可能的处理方式包括：

- 联系客户确认卡密使用情况
- 手动修正订单状态
- 退款处理
- 记录异常情况供后续分析

系统通过状态码和颜色标识突出显示此类订单，便于管理员快速识别和处理。

**Section sources**

- [recharge-history.vue](file://src/views/apple-card-info/recharge-history/index.vue#L336-L403)

## 数据导出功能

系统提供充值历史数据导出功能，允许用户将查询结果导出为Excel文件。导出功能支持与查询界面相同的筛选条件，包括账户、系统订单号、商户订单号、卡密和创建时间范围等。

导出流程：

1. 在查询界面设置所需的筛选条件
2. 点击"下载"按钮
3. 系统调用`downloadDataListApi`接口获取数据
4. 浏览器自动下载名为"apple.xlsx"的文件

该功能基于`axios`的blob响应类型实现，确保大文件导出的稳定性和性能。

**Section sources**

- [recharge-history.vue](file://src/views/apple-card-info/recharge-history/index.vue#L180-L222)
- [apple-card-recharge-history.ts](file://src/api/apple-card-recharge-history.ts#L107-L119)

## 操作最佳实践

### 异常订单处理流程

1. **识别异常订单**：通过状态颜色快速识别失败、冻结或卡密重复的订单
2. **分析原因**：查看订单详情和操作日志，了解异常原因
3. **选择处理方式**：
   - 对于回调失败的订单：使用手动回调功能
   - 对于金额错误的订单：使用金额修正功能
   - 对于冻结的订单：使用状态重置功能
   - 对于卡密重复的订单：人工介入处理
4. **记录处理结果**：在系统中添加处理备注，便于后续追踪

### 数据一致性保证

- **操作日志**：所有状态修改和金额修正操作都会记录在操作日志中，可通过recharge-history组件查看
- **二次验证**：敏感操作（如金额修改）需要TOTP二次验证，防止误操作
- **权限控制**：关键操作（如状态重置）仅对特定权限的用户开放
- **数据验证**：前端和后端都进行数据验证，确保数据完整性

### 性能优化建议

- **合理使用分页**：避免一次性加载过多数据，建议每页显示50-100条记录
- **精确查询条件**：使用时间范围和其他筛选条件缩小查询结果集
- **避免频繁刷新**：非必要情况下不要频繁手动刷新数据列表
- **批量处理**：对于需要处理的多个异常订单，考虑批量处理机制

**Section sources**

- [recharge-history.vue](file://src/views/apple-card-info/recharge-history/index.vue#L180-L222)
- [apple-card-recharge-history.ts](file://src/api/apple-card-recharge-history.ts#L38-L64)
