Files

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

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

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

14 KiB

Raw Blame History

商户配置管理

**本文档引用文件** - [config.go](file://api/merchant/v1/config.go) - [model.go](file://api/merchant/v1/model.go) - [merchant_v1_merchant_config_add.go](file://internal/controller/merchant/merchant_v1_merchant_config_add.go) - [merchant_v1_merchant_config_list.go](file://internal/controller/merchant/merchant_v1_merchant_config_list.go) - [merchant_v1_merchant_config_update.go](file://internal/controller/merchant/merchant_v1_merchant_config_update.go) - [merchant_v1_merchant_config_status.go](file://internal/controller/merchant/merchant_v1_merchant_config_status.go) - [merchant_v1_merchant_config_detail.go](file://internal/controller/merchant/merchant_v1_merchant_config_detail.go) - [merchant.go](file://internal/service/merchant.go) - [v_1_merchant_info.go](file://internal/model/do/v_1_merchant_info.go) - [common.go](file://api/commonApi/common.go) - [auth.go](file://internal/middleware/auth.go)

简介

本文档详细说明了商户配置管理API的使用方法，涵盖商户配置的增删改查操作。系统提供了完整的商户配置生命周期管理功能，包括创建、查询、更新、状态管理和详情获取等核心接口。所有接口均遵循RESTful设计原则，通过HTTP方法和URL路径实现对商户配置资源的操作。

商户配置管理功能
商户配置管理是系统核心功能之一，支持对商户基本信息、支付方式、费率策略等关键业务参数的全面管理。系统通过结构化的API设计，确保商户配置操作的安全性、一致性和可追溯性。

API端点概览

商户配置管理API提供以下核心端点：

商户配置创建

HTTP方法: POST
URL路径: /api/merchant/config/add
功能描述: 创建新的商户配置
请求参数: MerchantConfigAddReq
响应格式: MerchantConfigAddRes

商户配置列表查询

HTTP方法: GET
URL路径: /api/merchant/config/getList
功能描述: 查询商户配置列表（支持分页）
请求参数: MerchantConfigListReq
响应格式: MerchantConfigListRes

商户配置更新

HTTP方法: POST
URL路径: /api/merchant/config/updateDetail
功能描述: 更新商户配置信息
请求参数: MerchantConfigUpdateReq
响应格式: MerchantConfigUpdateRes

商户配置状态管理

HTTP方法: POST
URL路径: /api/merchant/config/switchStatus
功能描述: 切换商户状态（启用/禁用）
请求参数: MerchantConfigStatusReq
响应格式: MerchantConfigStatusRes

商户配置详情获取

HTTP方法: GET
URL路径: /api/merchant/config/getDetail
功能描述: 获取指定商户的详细配置信息
请求参数: MerchantConfigDetailReq
响应格式: MerchantConfigDetailRes

API端点关系图

flowchart TD
A["客户端"] --> B["创建商户配置"]
A --> C["查询商户列表"]
A --> D["获取商户详情"]
A --> E["更新商户配置"]
A --> F["管理商户状态"]
B --> |POST /add| G[商户配置服务]
C --> |GET /getList| G
D --> |GET /getDetail| G
E --> |POST /updateDetail| G
F --> |POST /switchStatus| G
G --> H[数据库]
G --> I[权限验证]
G --> J[事务管理]
style G fill:#4CAF50,stroke:#388E3C,color:white
style H fill:#2196F3,stroke:#1976D2,color:white
style I fill:#FF9800,stroke:#F57C00,color:white

图示来源

商户配置数据结构

核心数据模型

商户记录（MerchantRecord）

商户创建时所需的基本信息：

字段名	类型	必填	描述	验证规则
status	string	是	商户状态	必须提供
merchantName	string	是	商户名称	必须提供
loginAccount	string	是	登录账号	必须提供
remark	string	否	备注信息	-
loginPassword	string	是	登录密码	必须提供

Section sources

model.go

商户简单信息记录（MerchantSimpleInfoRecord）

商户基本信息，用于更新和详情展示：

字段名	类型	必填	描述	验证规则
merchantName	string	是	商户名称	必须提供
merchantUid	string	是	商户唯一标识	必须提供
loginAccount	string	是	登录账号	必须提供
whiteIps	string	否	IP白名单配置	-
remark	string	否	备注信息	-

Section sources

model.go

商户信息记录（MerchantInfoRecord）

完整的商户配置信息，包含所有字段：

字段名	类型	描述
status	string	商户状态
belongAgentUid	string	所属代理UID
belongAgentName	string	所属代理名称
merchantName	string	商户名称
merchantUid	string	商户唯一标识
merchantKey	string	商户密钥
merchantSecret	string	商户密钥
loginAccount	string	登录账号
clearTextPassword	string	明文密码
autoSettle	string	是否自动结算
autoPayFor	string	是否自动代付
whiteIps	string	IP白名单配置
remark	string	备注信息
singlePayForRoadUid	string	单代付通道UID
singlePayForRoadName	string	单代付通道名称
rollPayForRoadCode	string	轮询代付通道编码
rollPayForRoadName	string	轮询代付通道名称
payforFee	float64	代付手续费
updateTime	*gtime.Time	更新时间
createTime	*gtime.Time	创建时间

Section sources

model.go

数据库实体映射

商户配置信息在数据库中的存储结构：

erDiagram
MERCHANT_INFO {
uint id PK
string status
string belong_agent_uid
string belong_agent_name
string merchant_name
string merchant_uid UK
string merchant_key
string merchant_secret
string login_account UK
string login_password
string auto_settle
string auto_pay_for
string white_ips
string remark
string single_pay_for_road_uid
string single_pay_for_road_name
string roll_pay_for_road_code
string roll_pay_for_road_name
float payfor_fee
timestamp update_time
timestamp create_time
string otp_secret
}

图示来源

v_1_merchant_info.go

权限控制机制

认证流程

系统采用多层认证机制确保商户配置操作的安全性：

sequenceDiagram
participant Client as 客户端
participant Auth as 认证中间件
participant Service as 商户服务
participant DB as 数据库
Client->>Auth : 发送请求 (含Token)
Auth->>Auth : 检查白名单
alt 在白名单中
Auth-->>Client : 直接放行
else 不在白名单
Auth->>Auth : 验证Token有效性
Auth->>Auth : 检查Redis中Token
Auth->>Auth : 续签Token
Auth-->>Service : 认证通过
Service->>DB : 执行业务逻辑
DB-->>Service : 返回结果
Service-->>Client : 返回响应
end

图示来源

权限验证规则

Token验证: 所有非白名单接口必须提供有效的JWT Token
Token续签: 每次请求成功后自动续签Token有效期
Redis同步: Token状态与Redis保持同步，确保即时失效
双因素认证: 敏感操作支持二次验证机制

授权策略

创建权限: 仅管理员角色可创建新商户
更新权限: 仅商户所属管理员可修改配置
状态管理: 需要高级管理员权限才能切换商户状态
详情查看: 具有查看权限的用户均可获取商户详情

Section sources

错误处理策略

常见错误码

系统定义了统一的错误处理机制，返回标准化的错误响应：

错误码	HTTP状态码	错误信息	场景说明
400	400	参数验证失败	请求参数缺失或格式错误
401	401	认证失败	Token无效或过期
403	403	权限不足	用户无权执行该操作
404	404	资源不存在	指定商户UID不存在
409	409	配置冲突	商户名称或账号已存在
500	500	服务器内部错误	系统异常或数据库错误

异常处理流程

flowchart TD
A[接收请求] --> B{参数验证}
B --> |失败| C[返回400错误]
B --> |通过| D{权限验证}
D --> |失败| E[返回401/403错误]
D --> |通过| F[执行业务逻辑]
F --> G{操作成功?}
G --> |是| H[返回成功响应]
G --> |否| I{错误类型}
I --> |商户不存在| J[返回404错误]
I --> |配置冲突| K[返回409错误]
I --> |其他错误| L[返回500错误]
style C fill:#F44336,stroke:#D32F2F,color:white
style E fill:#F44336,stroke:#D32F2F,color:white
style J fill:#F44336,stroke:#D32F2F,color:white
style K fill:#F44336,stroke:#D32F2F,color:white
style L fill:#F44336,stroke:#D32F2F,color:white

图示来源

具体错误场景

创建商户时的错误处理

商户名称重复: 返回409错误，提示"商户名称已存在"
登录账号重复: 返回409错误，提示"登录账号已存在"
参数缺失: 返回400错误，明确指出缺失的字段
数据库异常: 返回500错误，记录详细日志

更新商户时的错误处理

商户不存在: 返回404错误，提示"指定商户不存在"
权限不足: 返回403错误，提示"无权修改该商户配置"
状态冲突: 返回409错误，当尝试对已删除商户进行更新

状态管理时的错误处理

状态切换失败: 返回500错误，记录事务回滚原因
关联账户异常: 返回500错误，当商户钱包状态更新失败时

Section sources

使用示例

创建商户配置

POST /api/merchant/config/add
Content-Type: application/json

{
  "status": "active",
  "merchantName": "测试商户",
  "loginAccount": "test_merchant",
  "loginPassword": "password123",
  "remark": "测试商户备注"
}

成功响应:

{
  "code": 0,
  "message": "OK",
  "data": {}
}

查询商户配置列表

GET /api/merchant/config/getList?current=1&pageSize=10&merchantName=测试
Authorization: Bearer {{token}}

成功响应:

{
  "code": 0,
  "message": "OK",
  "data": {
    "total": 1,
    "list": [
      {
        "status": "active",
        "belongAgentUid": "",
        "belongAgentName": "",
        "merchantName": "测试商户",
        "merchantUid": "8888a1b2c3d4e5f6",
        "merchantKey": "kkkkx1y2z3w4v5u6",
        "merchantSecret": "ssssm1n2o3p4q5r6",
        "loginAccount": "test_merchant",
        "autoSettle": "no",
        "autoPayFor": "no",
        "whiteIps": "",
        "remark": "测试商户备注",
        "singlePayForRoadUid": "",
        "singlePayForRoadName": "",
        "rollPayForRoadCode": "",
        "rollPayForRoadName": "",
        "payforFee": 0,
        "updateTime": "2024-01-01T10:00:00+08:00",
        "createTime": "2024-01-01T10:00:00+08:00"
      }
    ]
  }
}

更新商户配置

POST /api/merchant/config/updateDetail
Content-Type: application/json
Authorization: Bearer {{token}}

{
  "merchantName": "更新后的商户名称",
  "merchantUid": "8888a1b2c3d4e5f6",
  "loginAccount": "test_merchant",
  "whiteIps": "192.168.1.1,192.168.1.2",
  "remark": "更新后的备注信息"
}

获取商户详情

GET /api/merchant/config/getDetail?merchantUid=8888a1b2c3d4e5f6
Authorization: Bearer {{token}}

成功响应:

{
  "code": 0,
  "message": "OK",
  "data": {
    "merchantName": "更新后的商户名称",
    "merchantUid": "8888a1b2c3d4e5f6",
    "loginAccount": "test_merchant",
    "whiteIps": "192.168.1.1,192.168.1.2",
    "remark": "更新后的备注信息"
  }
}

切换商户状态

POST /api/merchant/config/switchStatus
Content-Type: application/json
Authorization: Bearer {{token}}

{
  "merchantUid": "8888a1b2c3d4e5f6",
  "status": "inactive"
}

Section sources

14 KiB Raw Blame History Unescape Escape

商户配置管理

目录

简介

API端点概览

商户配置创建

商户配置列表查询

商户配置更新

商户配置状态管理

商户配置详情获取

商户配置数据结构

核心数据模型

商户记录（MerchantRecord）

商户简单信息记录（MerchantSimpleInfoRecord）

商户信息记录（MerchantInfoRecord）

数据库实体映射

权限控制机制

认证流程

权限验证规则

授权策略

错误处理策略

常见错误码

异常处理流程

具体错误场景

创建商户时的错误处理

更新商户时的错误处理

状态管理时的错误处理

使用示例

创建商户配置

查询商户配置列表

更新商户配置

获取商户详情

切换商户状态

14 KiB

Raw Blame History