# Apple卡密账户管理

<cite>
**本文档引用的文件**
- [account_info.go](file://api/card_info_apple/v1/account_info.go)
- [card_apple_account.go](file://internal/model/card_apple_account.go)
- [v_1_card_apple_account_info.go](file://internal/dao/v_1_card_apple_account_info.go)
- [card_info_apple_v1_card_info_create.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_info_create.go)
- [card_info_apple_v1_card_info_list.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_info_list.go)
- [card_info_apple_v1_card_info_update.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_info_update.go)
- [card_info_apple_v1_card_info_delete.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_info_delete.go)
- [card_info_apple_v1_card_info_suspend_or_continue.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_info_suspend_or_continue.go)
- [card_info_apple_v1_card_info_download_template.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_info_download_template.go)
- [card_info_apple_v1_card_info_batch_add_from_xlsx.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_info_batch_add_from_xlsx.go)
- [card_apple_account.go](file://internal/service/card_apple_account.go)
- [account.go](file://internal/logic/card_apple_account/account.go)
- [card_apple.go](file://internal/consts/card_apple.go)
</cite>

## 目录
1. [简介](#简介)
2. [核心功能](#核心功能)
3. [数据模型](#数据模型)
4. [API端点](#api端点)
5. [账户状态管理](#账户状态管理)
6. [批量操作](#批量操作)
7. [错误处理](#错误处理)
8. [安全考虑](#安全考虑)
9. [客户端实现指南](#客户端实现指南)
10. [性能优化建议](#性能优化建议)

## 简介
本文档详细介绍了Apple卡密账户管理API的功能和使用方法。该API提供了一套完整的账户管理解决方案，支持账户的创建、查询、更新、删除等基本操作，以及账户状态管理、批量导入等高级功能。系统设计考虑了大规模账户管理的性能需求，提供了相应的优化建议。

**Section sources**
- [account_info.go](file://api/card_info_apple/v1/account_info.go)

## 核心功能
Apple卡密账户管理API提供以下核心功能：
- 账户的增删改查操作
- 账户状态的启用/暂停管理
- 批量导入账户信息
- 账户信息的分页查询
- 账户模板下载

这些功能通过RESTful API接口提供，支持标准的HTTP方法和JSON数据格式。

**Section sources**
- [account_info.go](file://api/card_info_apple/v1/account_info.go)

## 数据模型
### 账户信息数据模型
Apple卡密账户的核心数据模型包含以下字段：

| 字段名 | 类型 | 必填 | 描述 | 验证规则 |
|-------|------|------|------|---------|
| account | string | 是 | 账户名 | 必须提供 |
| password | string | 是 | 密码 | 必须提供 |
| maxAmountLimit | int | 是 | 最大充值金额 | 必须提供 |
| maxCountLimit | int | 是 | 最大充值次数 | 必须提供 |
| remark | string | 否 | 备注 | 无 |
| balance | float64 | 否 | 余额 | 只读 |
| status | int32 | 否 | 状态 | 0:停用, 1:正常使用, 2:正在充值, 3:已达到单日充值限制 |

**Section sources**
- [card_apple_account.go](file://internal/model/card_apple_account.go)
- [account_info.go](file://api/card_info_apple/v1/account_info.go)

## API端点
### 账户创建
创建新的Apple卡密账户。

**请求信息**
- **HTTP方法**: POST
- **URL模式**: `/cardInfo/AppleCard/account/create`
- **认证机制**: 需要有效的用户会话

**请求体**
```json
{
  "account": "string",
  "password": "string",
  "maxAmountLimit": 0,
  "maxCountLimit": 0,
  "remark": "string"
}
```

**响应**
- **成功**: 200 OK
- **失败**: 400 Bad Request (参数错误), 401 Unauthorized (权限不足), 409 Conflict (账号已存在)

**Section sources**
- [account_info.go](file://api/card_info_apple/v1/account_info.go)
- [card_info_apple_v1_card_info_create.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_info_create.go)

### 账户查询
查询Apple卡密账户列表。

**请求信息**
- **HTTP方法**: GET
- **URL模式**: `/cardInfo/AppleCard/account/getList`
- **认证机制**: 需要有效的用户会话

**查询参数**
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| account | string | 否 | 账户名，支持模糊查询 |
| current | int | 否 | 当前页码，默认1 |
| pageSize | int | 否 | 每页数量，默认10 |

**响应**
```json
{
  "total": 0,
  "list": [
    {
      "id": "string",
      "account": "string",
      "password": "string",
      "maxAmountLimit": 0,
      "maxCountLimit": 0,
      "remark": "string",
      "balance": 0,
      "status": 0
    }
  ]
}
```

**Section sources**
- [account_info.go](file://api/card_info_apple/v1/account_info.go)
- [card_info_apple_v1_card_info_list.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_info_list.go)

### 账户更新
更新现有Apple卡密账户信息。

**请求信息**
- **HTTP方法**: PUT
- **URL模式**: `/cardInfo/AppleCard/account/update`
- **认证机制**: 需要有效的用户会话

**请求体**
```json
{
  "id": "string",
  "account": "string",
  "password": "string",
  "maxAmountLimit": 0,
  "maxCountLimit": 0,
  "remark": "string"
}
```

**响应**
- **成功**: 200 OK
- **失败**: 400 Bad Request, 401 Unauthorized, 404 Not Found

**Section sources**
- [account_info.go](file://api/card_info_apple/v1/account_info.go)
- [card_info_apple_v1_card_info_update.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_info_update.go)

### 账户删除
删除指定的Apple卡密账户。

**请求信息**
- **HTTP方法**: DELETE
- **URL模式**: `/cardInfo/AppleCard/account/delete`
- **认证机制**: 需要有效的用户会话

**请求体**
```json
{
  "id": "string"
}
```

**响应**
- **成功**: 200 OK
- **失败**: 400 Bad Request, 401 Unauthorized, 500 Internal Server Error

**Section sources**
- [account_info.go](file://api/card_info_apple/v1/account_info.go)
- [card_info_apple_v1_card_info_delete.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_info_delete.go)

## 账户状态管理
### 修改账户状态
直接修改账户状态。

**请求信息**
- **HTTP方法**: PUT
- **URL模式**: `/cardInfo/AppleCard/account/updateStatus`
- **认证机制**: 需要有效的用户会话

**请求体**
```json
{
  "id": "string",
  "status": 10
}
```

**状态值**
- 10: 正常
- 20: 停用

**Section sources**
- [account_info.go](file://api/card_info_apple/v1/account_info.go)

### 暂停/恢复账户充值
切换账户的暂停/恢复状态。

**请求信息**
- **HTTP方法**: PUT
- **URL模式**: `/cardInfo/AppleCard/account/status/continueOrRestart`
- **认证机制**: 需要有效的用户会话

**请求体**
```json
{
  "id": "string"
}
```

**逻辑说明**
- 如果账户当前状态为"正常"，则将其暂停
- 如果账户当前状态为"停用"，则将其恢复为正常状态
- 其他状态返回错误

```mermaid
flowchart TD
Start([开始]) --> CheckStatus["检查账户状态"]
CheckStatus --> StatusDecision{"状态是正常吗?"}
StatusDecision --> |是| SetForbidden["设置为停用状态"]
StatusDecision --> |否| StatusIsForbidden{"状态是停用吗?"}
StatusIsForbidden --> |是| SetNormal["设置为正常状态"]
StatusIsForbidden --> |否| ReturnError["返回错误：状态不正确"]
SetForbidden --> End([结束])
SetNormal --> End
ReturnError --> End
```

**Diagram sources**
- [card_info_apple_v1_card_info_suspend_or_continue.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_info_suspend_or_continue.go)

## 批量操作
### 下载导入模板
下载批量导入账户信息的Excel模板。

**请求信息**
- **HTTP方法**: GET
- **URL模式**: `/cardInfo/AppleCard/account/downloadTemplate`
- **认证机制**: 需要有效的用户会话

**响应**
- 返回Excel文件，MIME类型为`application/vnd.ms-excel`

**Section sources**
- [account_info.go](file://api/card_info_apple/v1/account_info.go)
- [card_info_apple_v1_card_info_download_template.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_info_download_template.go)

### 批量导入账户
从Excel文件批量导入Apple卡密账户。

**请求信息**
- **HTTP方法**: POST
- **URL模式**: `/cardInfo/AppleCard/account/batchAdd`
- **认证机制**: 需要有效的用户会话

**请求体**
```json
{
  "file": "文件对象"
}
```

**文件格式要求**
- Excel文件格式
- 第一行为标题行：账号、密码、最大充值金额、最大充值次数、备注
- 支持.csv格式

**处理逻辑**
1. 验证文件格式和内容
2. 检查账户是否已存在
3. 批量创建账户
4. 返回导入结果统计

```mermaid
flowchart TD
Start([开始]) --> ValidateFile["验证文件"]
ValidateFile --> ReadFile["读取Excel数据"]
ReadFile --> CheckData["检查数据有效性"]
CheckData --> ProcessRows["逐行处理"]
ProcessRows --> CheckDuplicate["检查重复"]
CheckDuplicate --> |已存在| SkipRow["跳过该行"]
CheckDuplicate --> |不存在| CreateAccount["创建账户"]
CreateAccount --> UpdateCounters["更新计数器"]
UpdateCounters --> NextRow["处理下一行"]
NextRow --> MoreRows{"还有更多行吗?"}
MoreRows --> |是| ProcessRows
MoreRows --> |否| GenerateResult["生成结果"]
GenerateResult --> ReturnResult["返回结果"]
SkipRow --> NextRow
ReturnResult --> End([结束])
```

**Diagram sources**
- [card_info_apple_v1_card_info_batch_add_from_xlsx.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_info_batch_add_from_xlsx.go)

## 错误处理
### 常见错误码
| 错误码 | 描述 | 解决方案 |
|-------|------|---------|
| 400 | 参数错误 | 检查请求参数是否符合要求 |
| 401 | 权限不足 | 确保已正确登录并具有相应权限 |
| 404 | 资源未找到 | 检查ID是否正确 |
| 409 | 账号已存在 | 使用不同的账户名 |
| 500 | 服务器内部错误 | 联系管理员 |

### 验证规则
- 账户名和密码为必填项
- 账户名不能重复
- 最大充值金额和次数不能为空
- 状态值必须在允许范围内

**Section sources**
- [account_info.go](file://api/card_info_apple/v1/account_info.go)
- [card_apple.go](file://internal/consts/card_apple.go)

## 安全考虑
### 认证机制
所有API端点都需要用户认证，通过会话令牌验证用户身份。

### 数据验证
- 输入参数严格验证
- 防止SQL注入
- 限制文件上传类型和大小

### 敏感信息保护
- 密码在传输过程中加密
- 敏感操作需要二次确认
- 操作日志记录

**Section sources**
- [card_info_apple_v1_card_info_create.go](file://internal/controller/card_info_apple/card_info_apple_v1_card_info_create.go)

## 客户端实现指南
### 基本使用示例
```javascript
// 创建账户
fetch('/cardInfo/AppleCard/account/create', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your-token'
  },
  body: JSON.stringify({
    account: 'apple_user',
    password: 'secure_password',
    maxAmountLimit: 1000,
    maxCountLimit: 10
  })
});

// 查询账户列表
fetch('/cardInfo/AppleCard/account/getList?account=apple', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer your-token'
  }
});
```

### 批量导入示例
```javascript
const formData = new FormData();
formData.append('file', fileInput.files[0]);

fetch('/cardInfo/AppleCard/account/batchAdd', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your-token'
  },
  body: formData
});
```

**Section sources**
- [account_info.go](file://api/card_info_apple/v1/account_info.go)

## 性能优化建议
### 大规模账户管理
当管理大量账户时，建议采取以下优化措施：

1. **批量操作**: 尽可能使用批量导入功能，减少API调用次数
2. **分页查询**: 使用分页参数避免一次性获取过多数据
3. **缓存策略**: 对频繁查询的数据进行缓存
4. **异步处理**: 对耗时操作采用异步处理模式

### 数据库优化
- 确保账户名字段有索引
- 定期清理历史数据
- 监控查询性能

### 系统监控
- 监控API响应时间
- 跟踪错误率
- 设置适当的超时机制

**Section sources**
- [account.go](file://internal/logic/card_apple_account/account.go)
- [card_apple_account.go](file://internal/service/card_apple_account.go)