# 沃尔玛卡密分组管理

<cite>
**本文档引用文件**  
- [group.go](file://api/card_info_walmart/v1/group.go)
- [stats.go](file://api/card_info_walmart/v1/stats.go)
- [card_info_walmart_v1_group_add.go](file://internal/controller/card_info_walmart/card_info_walmart_v1_group_add.go)
- [card_info_walmart_v1_group_list.go](file://internal/controller/card_info_walmart/card_info_walmart_v1_group_list.go)
- [card_info_walmart_v1_group_stat.go](file://internal/controller/card_info_walmart/card_info_walmart_v1_group_stat.go)
- [card_info_walmart_v1_group_all_list.go](file://internal/controller/card_info_walmart/card_info_walmart_v1_group_all_list.go)
- [card_info_walmart_v1_group_delete.go](file://internal/controller/card_info_walmart/card_info_walmart_v1_group_delete.go)
- [card_info_walmart_v1_group_update.go](file://internal/controller/card_info_walmart/card_info_walmart_v1_group_update.go)
- [card_redeem_account.go](file://internal/service/card_redeem_account.go)
- [v_1_card_redeem_account_group.go](file://internal/model/entity/v_1_card_redeem_account_group.go)
- [v_1_card_redeem_account_info.go](file://internal/model/entity/v_1_card_redeem_account_info.go)
</cite>

## 目录
1. [简介](#简介)
2. [核心功能概述](#核心功能概述)
3. [分组管理API接口](#分组管理api接口)
4. [统计分析功能](#统计分析功能)
5. [客户端实现指南](#客户端实现指南)
6. [性能优化建议](#性能优化建议)
7. [错误处理与安全](#错误处理与安全)
8. [附录](#附录)

## 简介
本文档详细介绍了沃尔玛卡密分组管理系统的API接口，涵盖分组创建、列表查询、统计分析等核心功能。系统为沃尔玛卡密账户提供高效的分组管理能力，支持大规模账户的组织、查询和性能监控。通过本系统，用户可以对沃尔玛卡密账户进行分类管理，实现精细化运营和数据分析。

## 核心功能概述
沃尔玛卡密分组管理系统提供了一套完整的分组管理解决方案，主要包括以下核心功能：
- **分组创建与管理**：支持创建、更新、删除账户分组，实现账户的分类组织
- **分组列表查询**：提供分页查询功能，支持按用户ID、分组名称等条件筛选
- **统计分析**：提供分组级别的统计功能，包括账户状态分布、订单成功率等关键指标
- **数据导出**：支持将分组数据导出为Excel格式，便于离线分析

系统通过RESTful API提供服务，采用标准的HTTP方法和状态码，确保接口的易用性和一致性。

## 分组管理API接口

### 分组创建接口
**HTTP方法**: POST  
**URL模式**: `/cardInfo/walmart/group/add`  
**认证机制**: 需要有效的用户登录凭证，通过中间件`LoginOnlyLogin`验证

创建新的沃尔玛账户分组，每个分组必须有唯一的名称。系统会检查分组名称是否已存在，避免重复创建。

**请求参数**:
- `name` (string, 必填): 分组名称
- `notes` (string): 备注信息

**响应**:
- 成功: 返回空对象，HTTP状态码200
- 失败: 返回错误信息，HTTP状态码400（参数错误）或500（内部错误）

```mermaid
sequenceDiagram
participant 客户端
participant 控制器
participant 服务层
participant 数据库
客户端->>控制器 : POST /cardInfo/walmart/group/add
控制器->>控制器 : 验证用户登录状态
控制器->>服务层 : 调用GroupAdd方法
服务层->>服务层 : 检查分组名称是否已存在
服务层->>数据库 : 插入新分组记录
数据库-->>服务层 : 返回插入结果
服务层-->>控制器 : 返回操作结果
控制器-->>客户端 : 返回响应
```

**接口来源**
- [group.go](file://api/card_info_walmart/v1/group.go#L12-L20)
- [card_info_walmart_v1_group_add.go](file://internal/controller/card_info_walmart/card_info_walmart_v1_group_add.go)

### 分组更新接口
**HTTP方法**: PUT  
**URL模式**: `/cardInfo/walmart/group/update`  
**认证机制**: 需要有效的用户登录凭证，通过中间件`LoginOnlyLogin`验证

更新现有分组的信息，包括名称和备注。系统会检查新名称是否与其他分组冲突。

**请求参数**:
- `id` (int, 必填): 分组ID
- `name` (string, 必填): 新的分组名称
- `notes` (string): 新的备注信息

**响应**:
- 成功: 返回空对象，HTTP状态码200
- 失败: 返回错误信息，HTTP状态码400（参数错误）或500（内部错误）

```mermaid
sequenceDiagram
participant 客户端
participant 控制器
participant 服务层
participant 数据库
客户端->>控制器 : PUT /cardInfo/walmart/group/update
控制器->>控制器 : 验证用户登录状态
控制器->>服务层 : 调用GroupUpdate方法
服务层->>服务层 : 检查新名称是否已存在
服务层->>数据库 : 更新分组记录
数据库-->>服务层 : 返回更新结果
服务层-->>控制器 : 返回操作结果
控制器-->>客户端 : 返回响应
```

**接口来源**
- [group.go](file://api/card_info_walmart/v1/group.go#L22-L29)
- [card_info_walmart_v1_group_update.go](file://internal/controller/card_info_walmart/card_info_walmart_v1_group_update.go)

### 分组列表查询接口
**HTTP方法**: GET  
**URL模式**: `/cardInfo/walmart/group/list`  
**认证机制**: 需要有效的用户登录凭证，通过中间件`LoginWithIFrameAndLogin`验证

查询分组列表，支持分页、按用户ID和分组名称筛选。

**请求参数**:
- `page` (int): 页码，从1开始
- `limit` (int): 每页数量
- `userId` (string): 用户ID
- `name` (string): 分组名称（模糊匹配）

**响应**:
- `total` (int): 总记录数
- `list` (array): 分组列表，包含分组ID、名称、备注、创建时间等信息

```mermaid
sequenceDiagram
participant 客户端
participant 控制器
participant 服务层
participant 数据库
客户端->>控制器 : GET /cardInfo/walmart/group/list
控制器->>控制器 : 验证用户登录状态
控制器->>服务层 : 调用GroupList方法
服务层->>数据库 : 查询分组列表
数据库-->>服务层 : 返回查询结果
服务层-->>控制器 : 返回分组列表和总数
控制器-->>客户端 : 返回分页响应
```

**接口来源**
- [group.go](file://api/card_info_walmart/v1/group.go#L31-L38)
- [card_info_walmart_v1_group_list.go](file://internal/controller/card_info_walmart/card_info_walmart_v1_group_list.go)

### 分组删除接口
**HTTP方法**: DELETE  
**URL模式**: `/cardInfo/walmart/group/delete`  
**认证机制**: 需要有效的用户登录凭证，通过中间件`LoginOnlyLogin`验证

删除指定的分组。删除操作会检查分组是否存在以及用户是否有权限删除。

**请求参数**:
- `id` (int, 必填): 分组ID

**响应**:
- 成功: 返回空对象，HTTP状态码200
- 失败: 返回错误信息，HTTP状态码400（参数错误）或500（内部错误）

```mermaid
sequenceDiagram
participant 客户端
participant 控制器
participant 服务层
participant 数据库
客户端->>控制器 : DELETE /cardInfo/walmart/group/delete
控制器->>控制器 : 验证用户登录状态
控制器->>服务层 : 调用GroupDelete方法
服务层->>数据库 : 删除分组记录
数据库-->>服务层 : 返回删除结果
服务层-->>控制器 : 返回操作结果
控制器-->>客户端 : 返回响应
```

**接口来源**
- [group.go](file://api/card_info_walmart/v1/group.go#L40-L46)
- [card_info_walmart_v1_group_delete.go](file://internal/controller/card_info_walmart/card_info_walmart_v1_group_delete.go)

### 所有分组查询接口
**HTTP方法**: GET  
**URL模式**: `/cardInfo/walmart/group/allList`  
**认证机制**: 需要有效的用户登录凭证，通过中间件`LoginWithIFrameAndLogin`验证

查询所有分组，不进行分页，返回完整的分组列表。

**请求参数**:
- `userId` (string): 用户ID

**响应**:
- `total` (int): 总记录数
- `list` (array): 所有分组列表

```mermaid
sequenceDiagram
participant 客户端
participant 控制器
participant 服务层
participant 数据库
客户端->>控制器 : GET /cardInfo/walmart/group/allList
控制器->>控制器 : 验证用户登录状态
控制器->>服务层 : 调用GroupAllList方法
服务层->>数据库 : 查询所有分组
数据库-->>服务层 : 返回查询结果
服务层-->>控制器 : 返回分组列表和总数
控制器-->>客户端 : 返回响应
```

**接口来源**
- [group.go](file://api/card_info_walmart/v1/group.go#L48-L54)
- [card_info_walmart_v1_group_all_list.go](file://internal/controller/card_info_walmart/card_info_walmart_v1_group_all_list.go)

## 统计分析功能

### 分组统计接口
**HTTP方法**: GET  
**URL模式**: `/cardInfo/walmart/group/stat`  
**认证机制**: 需要有效的用户登录凭证，通过中间件`LoginWithIFrameAndLogin`验证

获取分组的统计信息，包括订单日期、分组ID、分组名称、订单数量、订单金额等。

**请求参数**:
- `page` (int): 页码
- `limit` (int): 每页数量
- `name` (string): 分组名称
- `username` (string): 用户名
- `date` (datetime): 日期
- `userId` (string): 用户ID

**响应**:
- `total` (int): 总记录数
- `list` (array): 统计列表，包含订单日期、分组信息、账户状态统计等

```mermaid
sequenceDiagram
participant 客户端
participant 控制器
participant 服务层
participant 数据库
客户端->>控制器 : GET /cardInfo/walmart/group/stat
控制器->>控制器 : 验证用户登录状态
控制器->>服务层 : 调用GroupStat方法
服务层->>数据库 : 查询分组统计信息
数据库-->>服务层 : 返回统计结果
服务层-->>控制器 : 返回统计列表和总数
控制器-->>客户端 : 返回分页响应
```

**接口来源**
- [group.go](file://api/card_info_walmart/v1/group.go#L56-L78)
- [card_info_walmart_v1_group_stat.go](file://internal/controller/card_info_walmart/card_info_walmart_v1_group_stat.go)

### 统计概览接口
**HTTP方法**: GET  
**URL模式**: `/cardInfo/walmart/stats/overview`  
**认证机制**: 无特殊认证要求

获取沃尔玛卡密的统计概览信息，包括账户数量、订单金额和订单数量等关键指标。

**请求参数**:
- `groupId` (int64): 分组ID
- `dateRange` (array): 日期范围
- `accountId` (string): 账户ID

**响应**:
- `totalActiveAccountCount` (int): 活跃账户总数
- `totalAccountCount` (int): 账户总数
- `totalOrderAmount` (float): 订单总金额
- `totalOrderAmountSuccess` (float): 成功订单金额
- `totalOrderCount` (int): 订单总数
- `totalOrderCountSuccess` (int): 成功订单数

```mermaid
sequenceDiagram
participant 客户端
participant 控制器
participant 服务层
participant 数据库
客户端->>控制器 : GET /cardInfo/walmart/stats/overview
控制器->>服务层 : 调用StatsOverview方法
服务层->>数据库 : 查询统计概览
数据库-->>服务层 : 返回概览数据
服务层-->>控制器 : 返回统计结果
控制器-->>客户端 : 返回响应
```

**接口来源**
- [stats.go](file://api/card_info_walmart/v1/stats.go#L6-L20)
- [card_info_walmart_v1_stats_overview.go](file://internal/controller/card_info_walmart/card_info_walmart_v1_stats_overview.go)

### 统计数据导出接口
**HTTP方法**: GET  
**URL模式**: `/cardInfo/walmart/stats/overview/download`  
**认证机制**: 无特殊认证要求
**响应类型**: application/xlsx

将统计概览数据导出为Excel文件。

**请求参数**:
- `groupId` (int64): 分组ID
- `accountId` (string): 账户ID

**响应**:
- Excel文件流

```mermaid
sequenceDiagram
participant 客户端
participant 控制器
participant 服务层
participant 数据库
客户端->>控制器 : GET /cardInfo/walmart/stats/overview/download
控制器->>服务层 : 调用StatsOverviewDownload方法
服务层->>数据库 : 查询统计数据
数据库-->>服务层 : 返回数据
服务层->>服务层 : 生成Excel文件
服务层-->>控制器 : 返回文件流
控制器-->>客户端 : 返回Excel文件
```

**接口来源**
- [stats.go](file://api/card_info_walmart/v1/stats.go#L22-L32)
- [card_info_walmart_v1_stats_overview_download.go](file://internal/controller/card_info_walmart/card_info_walmart_v1_stats_overview_download.go)

## 客户端实现指南

### 认证流程
客户端在调用任何需要认证的API接口前，必须先完成用户登录。系统通过`LoginOnlyLogin`和`LoginWithIFrameAndLogin`中间件验证用户身份。

**推荐实现**:
1. 用户登录获取会话凭证
2. 在后续请求的Header中携带认证信息
3. 处理401未授权响应，引导用户重新登录

### 错误处理
系统使用标准的HTTP状态码和自定义错误码来表示不同的错误情况。

**常见错误码**:
- `400`: 参数错误，请求参数不符合验证规则
- `401`: 未授权，用户未登录或会话过期
- `404`: 资源不存在
- `500`: 服务器内部错误

**建议的错误处理策略**:
- 捕获并解析错误响应
- 根据错误类型提供用户友好的提示
- 对于可恢复的错误（如网络超时），实现重试机制

### 分页策略
对于列表查询接口，系统采用标准的分页模式：

```json
{
  "total": 100,
  "list": [...],
  "page": 1,
  "limit": 20
}
```

**客户端实现建议**:
- 记录当前页码和每页数量
- 在用户翻页时更新请求参数
- 处理总记录数变化的情况

## 性能优化建议

### 大规模分组查询优化
当处理大量分组数据时，建议采用以下优化策略：

**分页查询**:
- 使用合理的分页大小（建议20-50条/页）
- 避免一次性查询所有数据
- 实现懒加载，只在需要时加载数据

**查询条件优化**:
- 尽可能使用精确的查询条件缩小结果集
- 利用索引字段（如用户ID、分组名称）进行筛选
- 避免在大数据集上进行模糊查询

### 统计计算性能优化
统计功能涉及大量数据聚合计算，建议采取以下措施：

**缓存策略**:
- 对频繁访问的统计结果进行缓存
- 设置合理的缓存过期时间
- 在数据更新时及时清除相关缓存

**异步计算**:
- 对于复杂的统计计算，考虑使用异步任务
- 提供计算进度查询接口
- 计算完成后通过回调或消息通知客户端

**数据预聚合**:
- 定期预计算常用的统计指标
- 存储预聚合结果供快速查询
- 平衡实时性和性能需求

## 错误处理与安全

### 常见错误场景
**分组名称重复**:
- 错误码: 400
- 原因: 创建或更新分组时名称已存在
- 解决方案: 使用唯一的分组名称

**权限不足**:
- 错误码: 401
- 原因: 用户未登录或会话过期
- 解决方案: 重新登录获取有效凭证

**参数验证失败**:
- 错误码: 400
- 原因: 请求参数不符合验证规则
- 解决方案: 检查并修正请求参数

### 安全考虑
**认证安全**:
- 所有敏感操作都需要用户认证
- 会话凭证应安全存储和传输
- 实现会话过期机制

**数据安全**:
- 敏感数据（如账户信息）应加密存储
- API接口应进行输入验证，防止SQL注入等攻击
- 限制单个用户的请求频率，防止滥用

## 附录

### 数据模型
**分组实体 (V1CardRedeemAccountGroup)**:
- `id`: 分组ID
- `name`: 分组名称
- `notes`: 备注
- `category`: 分组类别
- `createdUserId`: 创建用户ID
- `createdAt`: 创建时间
- `updatedAt`: 更新时间
- `deletedAt`: 删除时间

**账户实体 (V1CardRedeemAccountInfo)**:
- `id`: 账户ID
- `groupId`: 所属分组ID
- `name`: 账户名称
- `username`: 用户名
- `status`: 状态（1.正常 0.禁用）
- `balance`: 余额
- `effectiveBalance`: 有效充值余额

**统计实体 (V1CardRedeemAccountGroupStatsEntity)**:
- `orderDate`: 订单日期
- `groupId`: 分组ID
- `groupName`: 分组名称
- `count`: 订单数量
- `sum`: 订单金额
- `createdUserId`: 创建用户ID
- `createdUserName`: 创建用户名

### 接口调用示例
**创建分组**:
```http
POST /cardInfo/walmart/group/add
Content-Type: application/json

{
  "name": "沃尔玛账户分组1",
  "notes": "测试分组"
}
```

**查询分组列表**:
```http
GET /cardInfo/walmart/group/list?page=1&limit=20&name=沃尔玛
```

**获取统计概览**:
```http
GET /cardInfo/walmart/stats/overview?groupId=1&dateRange[]=2024-01-01&dateRange[]=2024-01-31
```