# 商户配置管理

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

## 目录
1. [简介](#简介)
2. [API端点概览](#api端点概览)
3. [商户配置数据结构](#商户配置数据结构)
4. [权限控制机制](#权限控制机制)
5. [错误处理策略](#错误处理策略)
6. [使用示例](#使用示例)

## 简介
本文档详细说明了商户配置管理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端点关系图**
```mermaid
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
```

**图示来源**
- [config.go](file://api/merchant/v1/config.go#L39-L52)
- [merchant.go](file://internal/service/merchant.go#L15-L25)

## 商户配置数据结构

### 核心数据模型

#### 商户记录（MerchantRecord）
商户创建时所需的基本信息：

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

**Section sources**
- [model.go](file://api/merchant/v1/model.go#L14-L20)

#### 商户简单信息记录（MerchantSimpleInfoRecord）
商户基本信息，用于更新和详情展示：

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

**Section sources**
- [model.go](file://api/merchant/v1/model.go#L45-L51)

#### 商户信息记录（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](file://api/merchant/v1/model.go#L22-L43)

### 数据库实体映射
商户配置信息在数据库中的存储结构：

```mermaid
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](file://internal/model/do/v_1_merchant_info.go#L10-L37)

## 权限控制机制

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

```mermaid
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
```

**图示来源**
- [auth.go](file://internal/middleware/auth.go#L50-L154)
- [config.go](file://api/merchant/v1/config.go#L10-L52)

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

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

**Section sources**
- [auth.go](file://internal/middleware/auth.go#L50-L154)
- [merchant.go](file://internal/service/merchant.go#L15-L25)

## 错误处理策略

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

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

### 异常处理流程
```mermaid
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
```

**图示来源**
- [merchant_v1_merchant_config_add.go](file://internal/controller/merchant/merchant_v1_merchant_config_add.go#L10-L48)
- [merchant_v1_merchant_config_status.go](file://internal/controller/merchant/merchant_v1_merchant_config_status.go#L10-L53)

### 具体错误场景
#### 创建商户时的错误处理
- **商户名称重复**: 返回409错误，提示"商户名称已存在"
- **登录账号重复**: 返回409错误，提示"登录账号已存在"
- **参数缺失**: 返回400错误，明确指出缺失的字段
- **数据库异常**: 返回500错误，记录详细日志

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

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

**Section sources**
- [merchant_v1_merchant_config_add.go](file://internal/controller/merchant/merchant_v1_merchant_config_add.go#L10-L48)
- [merchant_v1_merchant_config_update.go](file://internal/controller/merchant/merchant_v1_merchant_config_update.go#L10-L16)
- [merchant_v1_merchant_config_status.go](file://internal/controller/merchant/merchant_v1_merchant_config_status.go#L10-L53)

## 使用示例

### 创建商户配置
```json
POST /api/merchant/config/add
Content-Type: application/json

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

**成功响应**:
```json
{
  "code": 0,
  "message": "OK",
  "data": {}
}
```

### 查询商户配置列表
```json
GET /api/merchant/config/getList?current=1&pageSize=10&merchantName=测试
Authorization: Bearer {{token}}
```

**成功响应**:
```json
{
  "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"
      }
    ]
  }
}
```

### 更新商户配置
```json
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": "更新后的备注信息"
}
```

### 获取商户详情
```json
GET /api/merchant/config/getDetail?merchantUid=8888a1b2c3d4e5f6
Authorization: Bearer {{token}}
```

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

### 切换商户状态
```json
POST /api/merchant/config/switchStatus
Content-Type: application/json
Authorization: Bearer {{token}}

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

**Section sources**
- [merchant_v1_merchant_config_add.go](file://internal/controller/merchant/merchant_v1_merchant_config_add.go#L10-L48)
- [merchant_v1_merchant_config_list.go](file://internal/controller/merchant/merchant_v1_merchant_config_list.go#L10-L34)
- [merchant_v1_merchant_config_update.go](file://internal/controller/merchant/merchant_v1_merchant_config_update.go#L10-L16)
- [merchant_v1_merchant_config_status.go](file://internal/controller/merchant/merchant_v1_merchant_config_status.go#L10-L53)
- [merchant_v1_merchant_config_detail.go](file://internal/controller/merchant/merchant_v1_merchant_config_detail.go#L10-L21)