Files

danial 96ed936079 docs(api): 添加详细Apple卡密管理API文档

- 新增API端点参考文档，涵盖权限、卡密、订单、商户、监控、限制等模块
- 详细说明Apple卡密充值处理流程，包括提交、查询、回调和轮询接口
- 描述充值订单状态机及生命周期，支持超时重试和状态迁移
- 介绍签名验证、幂等控制及重复卡密防刷单策略
- 增加商户配置管理、历史记录查询和错误处理机制说明
- 提供API使用示例代码及客户端实现指导
- 删除过时的.drone.yml.bak文件，清理无用配置
- 添加.dockerignore忽略指定目录和文件

2025-10-08 20:13:40 +08:00

16 KiB

Raw Blame History

沃尔玛卡密分组管理

**本文档引用文件** - [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)

简介

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

核心功能概述

沃尔玛卡密分组管理系统提供了一套完整的分组管理解决方案，主要包括以下核心功能：

分组创建与管理：支持创建、更新、删除账户分组，实现账户的分类组织
分组列表查询：提供分页查询功能，支持按用户ID、分组名称等条件筛选
统计分析：提供分组级别的统计功能，包括账户状态分布、订单成功率等关键指标
数据导出：支持将分组数据导出为Excel格式，便于离线分析

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

分组管理API接口

分组创建接口

HTTP方法: POST
URL模式: /cardInfo/walmart/group/add
认证机制: 需要有效的用户登录凭证，通过中间件LoginOnlyLogin验证

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

请求参数:

name (string, 必填): 分组名称
notes (string): 备注信息

响应:

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

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

接口来源

分组更新接口

HTTP方法: PUT
URL模式: /cardInfo/walmart/group/update
认证机制: 需要有效的用户登录凭证，通过中间件LoginOnlyLogin验证

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

请求参数:

id (int, 必填): 分组ID
name (string, 必填): 新的分组名称
notes (string): 新的备注信息

响应:

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

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

接口来源

分组列表查询接口

HTTP方法: GET
URL模式: /cardInfo/walmart/group/list
认证机制: 需要有效的用户登录凭证，通过中间件LoginWithIFrameAndLogin验证

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

请求参数:

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

响应:

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

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

接口来源

分组删除接口

HTTP方法: DELETE
URL模式: /cardInfo/walmart/group/delete
认证机制: 需要有效的用户登录凭证，通过中间件LoginOnlyLogin验证

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

请求参数:

id (int, 必填): 分组ID

响应:

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

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

接口来源

所有分组查询接口

HTTP方法: GET
URL模式: /cardInfo/walmart/group/allList
认证机制: 需要有效的用户登录凭证，通过中间件LoginWithIFrameAndLogin验证

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

请求参数:

userId (string): 用户ID

响应:

total (int): 总记录数
list (array): 所有分组列表

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

接口来源

统计分析功能

分组统计接口

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): 统计列表，包含订单日期、分组信息、账户状态统计等

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

接口来源

统计概览接口

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): 成功订单数

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

接口来源

统计数据导出接口

HTTP方法: GET
URL模式: /cardInfo/walmart/stats/overview/download
认证机制: 无特殊认证要求 响应类型: application/xlsx

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

请求参数:

groupId (int64): 分组ID
accountId (string): 账户ID

响应:

Excel文件流

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

接口来源

客户端实现指南

认证流程

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

推荐实现:

用户登录获取会话凭证
在后续请求的Header中携带认证信息
处理401未授权响应，引导用户重新登录

错误处理

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

常见错误码:

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

建议的错误处理策略:

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

分页策略

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

{
  "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: 创建用户名

接口调用示例

创建分组:

POST /cardInfo/walmart/group/add
Content-Type: application/json

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

查询分组列表:

GET /cardInfo/walmart/group/list?page=1&limit=20&name=沃尔玛

获取统计概览:

GET /cardInfo/walmart/stats/overview?groupId=1&dateRange[]=2024-01-01&dateRange[]=2024-01-31

16 KiB Raw Blame History Unescape Escape

沃尔玛卡密分组管理

目录

简介

核心功能概述

分组管理API接口

分组创建接口

分组更新接口

分组列表查询接口

分组删除接口

所有分组查询接口

统计分析功能

分组统计接口

统计概览接口

统计数据导出接口

客户端实现指南

认证流程

错误处理

分页策略

性能优化建议

大规模分组查询优化

统计计算性能优化

错误处理与安全

常见错误场景

安全考虑

附录

数据模型

接口调用示例

16 KiB

Raw Blame History