# 商户部署管理

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

## 目录
1. [简介](#简介)
2. [核心数据结构](#核心数据结构)
3. [API端点说明](#api端点说明)
4. [部署创建接口](#部署创建接口)
5. [部署列表查询接口](#部署列表查询接口)
6. [部署更新接口](#部署更新接口)
7. [部署删除接口](#部署删除接口)
8. [部署详情获取接口](#部署详情获取接口)
9. [权限与安全](#权限与安全)
10. [错误处理策略](#错误处理策略)

## 简介
商户部署管理API用于配置和管理商户在不同支付通道上的部署信息。该系统支持商户在单通道和轮询通道上的灵活配置，包括费率设置、自动结算、自动代付、限制策略等关键功能。部署信息与商户配置紧密关联，确保支付流程的安全性和可控性。

**本文档中引用的文件**  
- [deploy.go](file://api/merchant/v1/deploy.go)

## 核心数据结构

### 商户部署记录结构
商户部署记录包含商户在特定支付通道上的完整配置信息。

```mermaid
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 : "包含"
```

**图示来源**  
- [model.go](file://api/merchant/v1/model.go#L53-L97)

**本节来源**  
- [model.go](file://api/merchant/v1/model.go#L53-L97)

## API端点说明
商户部署管理API提供以下核心端点：

| 端点 | HTTP方法 | 路径 | 功能 |
|------|--------|------|------|
| 创建部署 | POST | /merchant/deploy/add | 添加商户部署通道信息 |
| 查询部署列表 | GET | /merchant/deploy/getList | 获取商户部署通道信息 |
| 更新部署 | POST | /merchant/deploy/update | 更新商户部署通道信息 |
| 删除部署 | DELETE | /merchant/deploy/delete | 删除商户部署通道信息 |
| 获取部署详情 | GET | /merchant/deploy/getDetail | 获取商户部署通道详情 |

**本节来源**  
- [deploy.go](file://api/merchant/v1/deploy.go#L8-L50)

## 部署创建接口

### 请求参数
`merchant_v1_merchant_deploy_add` 接口用于创建新的商户部署配置。

```mermaid
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_add.go](file://internal/controller/merchant/merchant_v1_merchant_deploy_add.go#L15-L50)
- [v_1_road_pool.go](file://internal/service/v_1_road_pool.go#L16)
- [v_1_road.go](file://internal/service/v_1_road.go#L16)
- [merchant_deploy_info.go](file://internal/service/merchant_deploy_info.go#L21)

**本节来源**  
- [deploy.go](file://api/merchant/v1/deploy.go#L29-L32)
- [merchant_v1_merchant_deploy_add.go](file://internal/controller/merchant/merchant_v1_merchant_deploy_add.go#L15-L50)

## 部署列表查询接口
`merchant_v1_merchant_deploy_list` 接口用于查询商户的部署列表。

```go
type MerchantDeployListReq struct {
	g.Meta      `path:"/merchant/deploy/getList" tags:"商户部署信息" method:"get" summary:"获取商户部署通道信息"`
	MerchantUid string `json:"merchantUid"          description:"商户uid"`
}
```

该接口需要提供商户UID作为查询参数，返回该商户在所有支付通道上的部署配置列表。

**本节来源**  
- [deploy.go](file://api/merchant/v1/deploy.go#L8-L11)

## 部署更新接口
`merchant_v1_merchant_deploy_update` 接口用于更新现有的商户部署配置。

```go
type MerchantDeployUpdateReq struct {
	g.Meta `path:"/merchant/deploy/update" tags:"商户部署信息" method:"post" summary:"更新商户部署通道信息"`
	MerchantDeployRateAdd
}
```

更新操作会验证通道信息的有效性，并更新数据库中的部署记录。系统会自动同步通道名称等关联信息。

**本节来源**  
- [deploy.go](file://api/merchant/v1/deploy.go#L38-L41)

## 部署删除接口
`merchant_v1_merchant_deploy_delete` 接口用于删除指定的商户部署配置。

```go
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来唯一标识要删除的部署配置。

**本节来源**  
- [deploy.go](file://api/merchant/v1/deploy.go#L18-L23)

## 部署详情获取接口
`merchant_v1_merchant_deploy_get_detail` 接口用于获取特定部署配置的详细信息。

```go
type MerchantDeployGetDetailReq struct {
	g.Meta `path:"merchant/deploy/getDetail" tags:"商户部署信息" method:"get" summary:"获取商户部署通道详情"`
	commonApi.CommonIntId
}
```

该接口通过部署记录的ID来查询详细信息，返回完整的部署配置数据。

**本节来源**  
- [deploy.go](file://api/merchant/v1/deploy.go#L47-L50)

## 权限与安全
商户部署管理API实施严格的权限验证机制：

1. **身份验证**：所有请求必须包含有效的身份令牌
2. **权限检查**：操作者必须具有管理商户部署的权限
3. **数据隔离**：商户只能访问和修改自己的部署配置
4. **输入验证**：所有输入参数都经过严格的格式和业务规则验证
5. **操作审计**：关键操作会被记录到审计日志中

系统通过服务间调用验证通道和轮询通道的有效性，确保配置的准确性。

**本节来源**  
- [merchant_v1_merchant_deploy_add.go](file://internal/controller/merchant/merchant_v1_merchant_deploy_add.go#L15-L50)
- [merchant_deploy_info.go](file://internal/service/merchant_deploy_info.go#L21)

## 错误处理策略
API提供详细的错误响应，帮助客户端正确处理异常情况：

| 错误类型 | HTTP状态码 | 响应码 | 错误信息 |
|---------|-----------|--------|---------|
| 参数验证失败 | 400 | 400 | 缺失必填字段或格式错误 |
| 通道信息无效 | 400 | 400 | 选取通道错误或轮询通道错误 |
| 资源不存在 | 404 | 404 | 指定的部署配置不存在 |
| 服务器内部错误 | 500 | 500 | 系统处理异常 |

常见错误场景包括：
- 提供的单通道UID或轮询通道编码无效
- 必填字段缺失或格式不正确
- 商户UID不存在或已被禁用
- 并发修改导致的数据冲突

**本节来源**  
- [merchant_v1_merchant_deploy_add.go](file://internal/controller/merchant/merchant_v1_merchant_deploy_add.go#L15-L50)
- [deploy.go](file://api/merchant/v1/deploy.go#L8-L50)