Files

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

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

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

18 KiB

Raw Blame History

API端点参考

**本文档中引用的文件** - [card_info_apple.go](file://api/card_info_apple/card_info_apple.go) - [card_info_jd.go](file://api/card_info_jd/card_info_jd.go) - [card_info_walmart.go](file://api/card_info_walmart/card_info_walmart.go) - [card_info_c_trip.go](file://api/card_info_c_trip/card_info_c_trip.go) - [card_info_t_mall_game.go](file://api/card_info_t_mall_game/card_info_t_mall_game.go) - [card_redeem_jd.go](file://api/card_redeem_jd/card_redeem_jd.go) - [order.go](file://api/order/order.go) - [merchant.go](file://api/merchant/merchant.go) - [sysUser.go](file://api/sysUser/sysUser.go) - [monitor.go](file://api/monitor/monitor.go) - [restriction.go](file://api/restriction/restriction.go) - [common.go](file://api/commonApi/common.go) - [config.go](file://internal/consts/sys_config_dict.go)

简介

本文档提供了kami_backend系统所有公共API端点的完整参考。文档覆盖了权限管理、卡密信息管理、订单处理、商户管理、系统监控和限制管理等核心模块。每个API端点都详细记录了HTTP方法、URL模式、请求/响应模式、认证方法和参数说明。文档基于代码库中的实际实现，确保与系统真实数据结构和接口定义完全一致。

API架构概述

系统采用基于GoFrame框架的RESTful API架构，所有API端点遵循统一的版本控制和响应格式。API基础路径为/api/v1，支持JSON格式的数据交换。系统实现了统一的错误处理机制和认证授权体系。

graph TB
Client[客户端] --> |HTTP请求| APIGateway[API网关]
APIGateway --> Auth[认证中间件]
Auth --> RateLimit[速率限制]
RateLimit --> Controller[控制器层]
Controller --> Service[服务层]
Service --> DAO[数据访问层]
DAO --> Database[(数据库)]
subgraph "核心模块"
Controller --> CardInfo[卡密信息管理]
Controller --> Order[订单处理]
Controller --> Merchant[商户管理]
Controller --> Monitor[系统监控]
Controller --> Restriction[限制管理]
end

图源

权限管理模块

权限管理模块提供用户、角色和菜单的完整管理功能，支持基于RBAC（基于角色的访问控制）的权限体系。

用户管理

提供用户创建、删除、更新和查询功能，支持用户状态管理和权限分配。

端点列表

POST /api/v1/sysUser/user/add - 创建用户
DELETE /api/v1/sysUser/user/delete - 删除用户
PUT /api/v1/sysUser/user/edit - 编辑用户
GET /api/v1/sysUser/user/get/all - 获取所有用户
PUT /api/v1/sysUser/user/forbidden/by/id - 禁用/启用用户

请求参数示例

{
  "username": "example_user",
  "password": "encrypted_password",
  "roleId": 1,
  "status": 1
}

响应格式

{
  "code": 0,
  "message": "操作成功",
  "data": {
    "userId": "123456"
  }
}

节源

角色管理

管理角色定义和权限分配，支持角色的增删改查操作。

端点列表

POST /api/v1/sysRole/role/add - 添加角色
DELETE /api/v1/sysRole/role/delete - 删除角色
PUT /api/v1/sysRole/role/edit - 编辑角色
GET /api/v1/sysRole/role/list - 获取角色列表

节源

菜单管理

管理系统菜单结构和权限规则，支持菜单的层级管理和动态配置。

端点列表

POST /api/v1/authority/menu/create - 创建菜单
DELETE /api/v1/authority/menu/delete - 删除菜单
PUT /api/v1/authority/menu/update - 更新菜单
GET /api/v1/authority/menu/list - 获取菜单列表

节源

卡密信息管理模块

卡密信息管理模块支持多种平台的卡密信息管理，包括Apple、京东、沃尔玛、C-Trip和天猫游戏等。

Apple卡密管理

提供Apple卡密的全生命周期管理，包括卡密的创建、查询、更新和删除。

端点列表

POST /api/v1/card_info_apple/card/info/create - 创建Apple卡密
GET /api/v1/card_info_apple/card/info/list - 获取卡密列表
PUT /api/v1/card_info_apple/card/info/update - 更新卡密信息
DELETE /api/v1/card_info_apple/card/info/delete - 删除卡密
PUT /api/v1/card_info_apple/card/info/suspend_or_continue - 暂停/继续卡密

请求参数说明

cardNumber: 卡密号码
password: 卡密密码
status: 卡密状态（1:启用, 0:禁用）
batchId: 批次ID

节源

京东卡密管理

管理京东平台的卡密信息，支持批量操作和历史记录查询。

端点列表

POST /api/v1/card_info_jd/jd/account/create - 创建京东账号
GET /api/v1/card_info_jd/jd/account/list - 获取账号列表
PUT /api/v1/card_info_jd/jd/account/update - 更新账号信息
POST /api/v1/card_info_jd/jd/account/cookie/batch/add - 批量添加Cookie
GET /api/v1/card_info_jd/jd/account/wallet/list - 获取钱包列表

节源

沃尔玛卡密管理

提供沃尔玛平台卡密的全面管理功能。

端点列表

POST /api/v1/card_info_walmart/account/create - 创建沃尔玛账号
GET /api/v1/card_info_walmart/account/list - 获取账号列表
PUT /api/v1/card_info_walmart/account/update - 更新账号信息
GET /api/v1/card_info_walmart/account/wallet/list - 获取钱包列表
GET /api/v1/card_info_walmart/order/summary/list - 订单汇总列表

节源

C-Trip卡密管理

管理C-Trip平台的卡密信息。

端点列表

POST /api/v1/card_info_c_trip/account/create - 创建C-Trip账号
GET /api/v1/card_info_c_trip/account/list - 获取账号列表
PUT /api/v1/card_info_c_trip/account/update - 更新账号信息
POST /api/v1/card_info_c_trip/account/cookie/batch/add - 批量添加Cookie

节源

天猫游戏卡密管理

提供天猫游戏平台卡密的管理功能。

端点列表

POST /api/v1/card_info_t_mall_game/t_mall_game/account/create - 创建天猫游戏账号
GET /api/v1/card_info_t_mall_game/t_mall_game/account/list - 获取账号列表
PUT /api/v1/card_info_t_mall_game/t_mall_game/account/toggle - 切换账号状态
GET /api/v1/card_info_t_mall_game/t_mall_game/order/list - 获取订单列表
POST /api/v1/card_info_t_mall_game/t_mall_game/order/submit - 提交订单

节源

订单处理模块

订单处理模块负责所有平台的订单生命周期管理，包括订单创建、查询、更新和回调处理。

订单管理

提供统一的订单管理接口，支持多平台订单的集中处理。

端点列表

POST /api/v1/order/form/create - 创建订单
GET /api/v1/order/form/list - 获取订单列表
PUT /api/v1/order/form/update - 更新订单
DELETE /api/v1/order/form/delete - 删除订单
GET /api/v1/order/summary/get/list - 获取订单汇总

请求参数说明

orderId: 订单ID
platform: 平台类型（apple, jd, walmart等）
amount: 订单金额
status: 订单状态
userId: 用户ID

响应格式

{
  "code": 0,
  "message": "success",
  "data": {
    "list": [
      {
        "orderId": "ORD123456",
        "platform": "apple",
        "amount": 100.00,
        "status": "completed",
        "createdAt": "2023-01-01T00:00:00Z"
      }
    ],
    "total": 1
  }
}

节源

订单历史

管理订单的历史记录和日志。

端点列表

GET /api/v1/order/log/list - 获取订单日志列表
DELETE /api/v1/order/log/delete - 删除订单日志
GET /api/v1/order/summary/daily/get/list - 获取每日订单汇总

节源

商户管理模块

商户管理模块提供商户配置、部署和订单处理功能。

商户配置

管理商户的基本信息和配置参数。

端点列表

POST /api/v1/merchant/config/add - 添加商户配置
GET /api/v1/merchant/config/list - 获取商户配置列表
PUT /api/v1/merchant/config/update - 更新商户配置
PUT /api/v1/merchant/config/status - 更新商户配置状态

节源

商户部署

管理商户的部署信息和状态。

端点列表

POST /api/v1/merchant/deploy/add - 添加商户部署
GET /api/v1/merchant/deploy/list - 获取部署列表
PUT /api/v1/merchant/deploy/update - 更新部署信息
DELETE /api/v1/merchant/deploy/delete - 删除部署

节源

商户订单

处理商户相关的订单查询和统计。

端点列表

GET /api/v1/merchant/order/query - 查询商户订单
GET /api/v1/merchant/steal/stats - 获取商户抢单统计
GET /api/v1/merchant/steal/record/list - 获取抢单记录列表

节源

系统监控模块

系统监控模块提供健康检查和系统状态监控功能。

健康检查

提供系统健康状态的检查接口。

端点列表

GET /api/v1/monitor/health/check - 健康检查

响应示例

{
  "code": 0,
  "message": "OK",
  "data": {
    "status": "healthy",
    "timestamp": "2023-01-01T00:00:00Z",
    "services": {
      "database": "connected",
      "cache": "connected",
      "message_queue": "connected"
    }
  }
}

节源

限制管理模块

限制管理模块提供IP限制、区域限制和用户信息收集功能。

IP限制管理

管理IP访问限制规则。

端点列表

GET /api/v1/restriction/check/ip/allowed - 检查IP是否允许访问
POST /api/v1/restriction/block/order - 阻止订单
GET /api/v1/restriction/query/all/province - 查询所有省份

节源

用户信息收集

管理用户信息收集规则。

端点列表

POST /api/v1/restriction/user/info/collection - 用户信息收集

节源

认证与安全

系统采用基于JWT的认证机制，所有API端点都需要有效的认证令牌。

认证机制

认证方式: Bearer Token
令牌类型: JWT
有效期: 24小时
刷新机制: 支持令牌刷新

认证头

所有请求需要在HTTP头中包含认证信息：

Authorization: Bearer <token>

安全考虑

所有API通信必须通过HTTPS
敏感数据在传输过程中必须加密
密码等敏感信息在存储时必须哈希处理
实施CSRF防护机制
定期进行安全审计和漏洞扫描

节源

错误处理策略

系统采用统一的错误处理机制，所有错误响应遵循标准格式。

错误响应格式

{
  "code": 1001,
  "message": "订单不存在",
  "data": null
}

常见错误码

错误码	错误信息	说明
1001	订单不存在	请求的订单ID不存在
1002	账号不存在	请求的账号ID不存在
1003	账号已存在	尝试创建已存在的账号
1004	订单已支付	订单状态已经是支付完成
1005	卡密错误	卡密号码或密码错误
1006	上传账号失败，当日已上传过	当天已经上传过账号
2006	文件损坏	上传的文件格式不正确或损坏
3001	用户名或密码错误	登录凭据不正确
3002	用户不存在	请求的用户ID不存在
3003	用户被禁用	用户账户已被禁用
3004	用户未激活	用户账户尚未激活
3005	用户不存在或已被禁用	用户不存在或已被禁用
3006	密码错误	密码不正确
3007	二步验证错误	两步验证代码不正确
4001	操作被禁止	当前用户没有权限执行此操作
5001	token错误	认证令牌不正确
5002	token过期	认证令牌已过期
5003	token不存在	请求中缺少认证令牌
6001	ck失效	Cookie已失效

节源

速率限制

系统实施基于Redis的速率限制机制，防止API滥用和DDoS攻击。

速率限制策略

全局限制: 每分钟最多1000次请求
用户限制: 每个用户每分钟最多100次请求
IP限制: 每个IP地址每分钟最多500次请求

限流类型

限流类型	说明	限制值
cardInfo:jd:account:cookie	京东账号Cookie检查	10次/分钟
cardInfo:jd:account🍪set	京东账号Cookie设置	5次/分钟
cardInfo:account:cookie:checker	通用账号Cookie检查	15次/分钟
cardInfo:account:cookie:set	通用账号Cookie设置	8次/分钟

限流响应头

当接近限流阈值时，响应头中会包含以下信息：

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 10
X-RateLimit-Reset: 60

节源

客户端实现指南

本节提供客户端实现的最佳实践和示例代码。

请求示例 (Python)

import requests
import json

url = "https://api.example.com/api/v1/card_info_apple/card/info/create"
headers = {
    "Authorization": "Bearer your_token_here",
    "Content-Type": "application/json"
}
data = {
    "cardNumber": "1234567890",
    "password": "your_password",
    "status": 1
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

请求示例 (JavaScript)

const url = 'https://api.example.com/api/v1/card_info_apple/card/info/create';
const options = {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer your_token_here',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        cardNumber: '1234567890',
        password: 'your_password',
        status: 1
    })
};

fetch(url, options)
    .then(response => response.json())
    .then(data => console.log(data))
    .catch(error => console.error('Error:', error));

错误处理示例

def handle_api_response(response):
    if response.status_code == 200:
        data = response.json()
        if data['code'] == 0:
            return data['data']
        else:
            error_code = data['code']
            error_message = data['message']
            # 根据错误码进行相应处理
            if error_code == 5002:  # token过期
                refresh_token()
                retry_request()
            elif error_code == 4001:  # 操作被禁止
                show_permission_error()
            else:
                show_error(error_message)
    else:
        handle_network_error()

性能优化建议

为确保API的高性能和可扩展性，建议遵循以下最佳实践。

批量操作

对于大量数据的操作，建议使用批量接口而不是单个请求：

使用/batch/add接口批量添加卡密
使用/batch/update接口批量更新状态
避免在循环中调用单个创建接口

分页查询

对于列表查询，务必使用分页参数：

{
  "current": 1,
  "pageSize": 50
}

建议pageSize不超过100，避免单次请求返回过多数据。

缓存策略

对于不经常变化的数据，客户端应实施本地缓存
使用ETag或Last-Modified头进行条件请求
设置合理的缓存过期时间

连接复用

使用HTTP Keep-Alive保持连接
实施连接池管理
避免频繁创建和销毁连接

异步处理

对于耗时较长的操作，建议使用异步模式：

提交请求并获取任务ID
通过轮询或WebSocket获取处理状态
处理完成后获取结果

监控与日志

记录关键操作的执行时间
监控API的响应时间和错误率
设置告警阈值，及时发现性能问题

18 KiB Raw Blame History Unescape Escape

API端点参考

目录

简介

API架构概述

权限管理模块

用户管理

角色管理

菜单管理

卡密信息管理模块

Apple卡密管理

京东卡密管理

沃尔玛卡密管理

C-Trip卡密管理

天猫游戏卡密管理

订单处理模块

订单管理

订单历史

商户管理模块

商户配置

商户部署

商户订单

系统监控模块

健康检查

限制管理模块

IP限制管理

用户信息收集

认证与安全

认证机制

认证头

安全考虑

错误处理策略

错误响应格式

常见错误码

速率限制

速率限制策略

限流类型

限流响应头

客户端实现指南

请求示例 (Python)

请求示例 (JavaScript)

错误处理示例

性能优化建议

批量操作

分页查询

缓存策略

连接复用

异步处理

监控与日志

18 KiB

Raw Blame History