96ed936079
- 新增API端点参考文档，涵盖权限、卡密、订单、商户、监控、限制等模块 - 详细说明Apple卡密充值处理流程，包括提交、查询、回调和轮询接口 - 描述充值订单状态机及生命周期，支持超时重试和状态迁移 - 介绍签名验证、幂等控制及重复卡密防刷单策略 - 增加商户配置管理、历史记录查询和错误处理机制说明 - 提供API使用示例代码及客户端实现指导 - 删除过时的.drone.yml.bak文件，清理无用配置 - 添加.dockerignore忽略指定目录和文件
8.2 KiB
8.2 KiB
商户部署管理
**本文档中引用的文件** - [deploy.go](file://api/merchant/v1/deploy.go) - [model.go](file://api/merchant/v1/model.go) - [merchant_v1_merchant_deploy_add.go](file://internal/controller/merchant/merchant_v1_merchant_deploy_add.go) - [merchant_deploy_info.go](file://internal/service/merchant_deploy_info.go) - [v_1_merchant_deploy_info.go](file://internal/dao/v_1_merchant_deploy_info.go) - [v_1_road.go](file://internal/service/v_1_road.go) - [v_1_road_pool.go](file://internal/service/v_1_road_pool.go)目录
简介
商户部署管理API用于配置和管理商户在不同支付通道上的部署信息。该系统支持商户在单通道和轮询通道上的灵活配置，包括费率设置、自动结算、自动代付、限制策略等关键功能。部署信息与商户配置紧密关联，确保支付流程的安全性和可控性。
本文档中引用的文件
核心数据结构
商户部署记录结构
商户部署记录包含商户在特定支付通道上的完整配置信息。
classDiagram
class MerchantDeployRecord {
+uint Id
+string Status
+string MerchantUid
+string PayType
+string PayTypeName
+string SingleRoadName
+string RollRoadName
+string RoadSetting
}
class MerchantDeployRateAdd {
+string SingleRoadUid
+[]PlatformRateRecord SingleRoadPlatformRate
+float64 SingleRoadAgentRate
+string RollRoadCode
+float64 RollRoadAgentRate
+float64 RollRoadPlatformRate
+string MerchantUid
+string AutoSettle
+string AutoPayfor
+[]string RestrictArea
+bool IsRestrictAgent
+bool IsRestrictCardPass
+bool IsRestrictDevice
+bool IsRestrictIp
+bool IsRestrictInternalIp
+string SubmitStrategy
}
class PlatformRateRecord {
+float64 FactLabel
+float64 ShowLabel
+string PlatformLabel
+bool IsLinkSingle
+float64 Value
+string LinkID
+int Sort
}
MerchantDeployRecord --> MerchantDeployRateAdd : "包含"
MerchantDeployRateAdd --> PlatformRateRecord : "包含"
图示来源
本节来源
API端点说明
商户部署管理API提供以下核心端点：
| 端点 | HTTP方法 | 路径 | 功能 |
|---|---|---|---|
| 创建部署 | POST | /merchant/deploy/add | 添加商户部署通道信息 |
| 查询部署列表 | GET | /merchant/deploy/getList | 获取商户部署通道信息 |
| 更新部署 | POST | /merchant/deploy/update | 更新商户部署通道信息 |
| 删除部署 | DELETE | /merchant/deploy/delete | 删除商户部署通道信息 |
| 获取部署详情 | GET | /merchant/deploy/getDetail | 获取商户部署通道详情 |
本节来源
部署创建接口
请求参数
merchant_v1_merchant_deploy_add 接口用于创建新的商户部署配置。
sequenceDiagram
participant Client as "客户端"
participant Controller as "ControllerV1"
participant RoadPool as "RoadPool服务"
participant Road as "Road服务"
participant Service as "MerchantDeployInfo服务"
Client->>Controller : POST /merchant/deploy/add
Controller->>RoadPool : GetDetailByCode(rollRoadCode)
RoadPool-->>Controller : 返回轮询通道信息
Controller->>Road : GetDetailByUid(singleRoadUid)
Road-->>Controller : 返回单通道信息
Controller->>Service : AddOrUpdate(部署信息)
Service-->>Controller : 返回结果
Controller-->>Client : 返回响应
图示来源
本节来源
部署列表查询接口
merchant_v1_merchant_deploy_list 接口用于查询商户的部署列表。
type MerchantDeployListReq struct {
g.Meta `path:"/merchant/deploy/getList" tags:"商户部署信息" method:"get" summary:"获取商户部署通道信息"`
MerchantUid string `json:"merchantUid" description:"商户uid"`
}
该接口需要提供商户UID作为查询参数，返回该商户在所有支付通道上的部署配置列表。
本节来源
部署更新接口
merchant_v1_merchant_deploy_update 接口用于更新现有的商户部署配置。
type MerchantDeployUpdateReq struct {
g.Meta `path:"/merchant/deploy/update" tags:"商户部署信息" method:"post" summary:"更新商户部署通道信息"`
MerchantDeployRateAdd
}
更新操作会验证通道信息的有效性，并更新数据库中的部署记录。系统会自动同步通道名称等关联信息。
本节来源
部署删除接口
merchant_v1_merchant_deploy_delete 接口用于删除指定的商户部署配置。
type MerchantDeployDeleteReq struct {
g.Meta `path:"/merchant/deploy/delete" tags:"商户部署信息" method:"delete" summary:"删除商户部署通道信息"`
MerchantUid string `json:"merchantUid" v:"required#商户ID不能为空" description:"商户uid"`
SingleRoadUid string `json:"singleRoadUid" v:"required#单通道uid不能为空" description:"单通道uid"`
}
删除操作需要同时提供商户UID和单通道UID来唯一标识要删除的部署配置。
本节来源
部署详情获取接口
merchant_v1_merchant_deploy_get_detail 接口用于获取特定部署配置的详细信息。
type MerchantDeployGetDetailReq struct {
g.Meta `path:"merchant/deploy/getDetail" tags:"商户部署信息" method:"get" summary:"获取商户部署通道详情"`
commonApi.CommonIntId
}
该接口通过部署记录的ID来查询详细信息，返回完整的部署配置数据。
本节来源
权限与安全
商户部署管理API实施严格的权限验证机制：
- 身份验证：所有请求必须包含有效的身份令牌
- 权限检查：操作者必须具有管理商户部署的权限
- 数据隔离：商户只能访问和修改自己的部署配置
- 输入验证：所有输入参数都经过严格的格式和业务规则验证
- 操作审计：关键操作会被记录到审计日志中
系统通过服务间调用验证通道和轮询通道的有效性，确保配置的准确性。
本节来源
错误处理策略
API提供详细的错误响应，帮助客户端正确处理异常情况：
| 错误类型 | HTTP状态码 | 响应码 | 错误信息 |
|---|---|---|---|
| 参数验证失败 | 400 | 400 | 缺失必填字段或格式错误 |
| 通道信息无效 | 400 | 400 | 选取通道错误或轮询通道错误 |
| 资源不存在 | 404 | 404 | 指定的部署配置不存在 |
| 服务器内部错误 | 500 | 500 | 系统处理异常 |
常见错误场景包括：
- 提供的单通道UID或轮询通道编码无效
- 必填字段缺失或格式不正确
- 商户UID不存在或已被禁用
- 并发修改导致的数据冲突
本节来源