# 商户管理API

<cite>
**本文档引用的文件**
- [config.go](file://api/merchant/v1/config.go)
- [deploy.go](file://api/merchant/v1/deploy.go)
- [steal.go](file://api/merchant/v1/steal.go)
- [merchant_v1_merchant_config_add.go](file://internal/controller/merchant/merchant_v1_merchant_config_add.go)
- [merchant_v1_merchant_deploy_add.go](file://internal/controller/merchant/merchant_v1_merchant_deploy_add.go)
- [merchant_v1_steal_create.go](file://internal/controller/merchant/merchant_v1_steal_create.go)
- [merchant.go](file://internal/service/merchant.go)
- [steal_rule.go](file://internal/service/steal_rule.go)
- [merchant_deploy_info.go](file://internal/service/merchant_deploy_info.go)
- [v_1_merchant_info.go](file://internal/model/entity/v_1_merchant_info.go)
- [v_1_merchant_deploy_info.go](file://internal/model/entity/v_1_merchant_deploy_info.go)
- [v_1_merchant_hidden_config.go](file://internal/model/entity/v_1_merchant_hidden_config.go)
- [v_1_merchant_hidden_record.go](file://internal/model/entity/v_1_merchant_hidden_record.go)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概述](#架构概述)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)

## 简介
商户管理API提供了一套完整的商户生命周期管理功能，包括商户配置、部署管理和盗单处理等核心功能。该系统实现了多租户架构，支持商户隔离、配置继承和权限控制策略。API设计遵循RESTful原则，通过清晰的端点组织和标准化的请求/响应模式，为商户管理提供了高效、安全的接口。

## 项目结构
商户管理功能主要分布在`api/merchant/v1`目录下，包含配置、部署和盗单处理三个核心模块。每个模块都有对应的请求/响应结构体定义。业务逻辑实现在`internal/controller/merchant`目录中，服务层位于`internal/service`，数据模型定义在`internal/model/entity`目录下。这种分层架构确保了代码的可维护性和扩展性。

```mermaid
graph TD
subgraph "API层"
A[config.go]
B[deploy.go]
C[steal.go]
end
subgraph "控制器层"
D[merchant_v1_merchant_config_*.go]
E[merchant_v1_merchant_deploy_*.go]
F[merchant_v1_steal_*.go]
end
subgraph "服务层"
G[merchant.go]
H[steal_rule.go]
I[merchant_deploy_info.go]
end
subgraph "数据模型层"
J[v_1_merchant_info.go]
K[v_1_merchant_deploy_info.go]
L[v_1_merchant_hidden_config.go]
M[v_1_merchant_hidden_record.go]
end
A --> D
B --> E
C --> F
D --> G
E --> I
F --> H
G --> J
I --> K
H --> L
H --> M
```

**图示来源**
- [config.go](file://api/merchant/v1/config.go)
- [deploy.go](file://api/merchant/v1/deploy.go)
- [steal.go](file://api/merchant/v1/steal.go)
- [merchant_v1_merchant_config_add.go](file://internal/controller/merchant/merchant_v1_merchant_config_add.go)
- [merchant_v1_merchant_deploy_add.go](file://internal/controller/merchant/merchant_v1_merchant_deploy_add.go)
- [merchant_v1_steal_create.go](file://internal/controller/merchant/merchant_v1_steal_create.go)

**章节来源**
- [config.go](file://api/merchant/v1/config.go#L1-L80)
- [deploy.go](file://api/merchant/v1/deploy.go#L1-L56)
- [steal.go](file://api/merchant/v1/steal.go#L1-L116)

## 核心组件
商户管理API的核心组件包括商户配置管理、部署信息管理和盗单规则管理。商户配置管理负责商户的创建、更新、状态切换和查询；部署信息管理处理商户的通道部署配置；盗单规则管理实现盗单策略的配置、状态管理和记录查询。这些组件通过清晰的接口定义和分层架构，确保了系统的可维护性和扩展性。

**章节来源**
- [config.go](file://api/merchant/v1/config.go#L1-L80)
- [deploy.go](file://api/merchant/v1/deploy.go#L1-L56)
- [steal.go](file://api/merchant/v1/steal.go#L1-L116)

## 架构概述
系统采用典型的分层架构，包括API层、控制器层、服务层和数据访问层。API层定义了所有外部接口的请求/响应结构；控制器层处理HTTP请求并调用相应的服务；服务层封装了业务逻辑；数据访问层负责与数据库交互。这种架构实现了关注点分离，提高了代码的可测试性和可维护性。

```mermaid
graph TD
A[客户端] --> B[API层]
B --> C[控制器层]
C --> D[服务层]
D --> E[数据访问层]
E --> F[数据库]
subgraph "API层"
B
end
subgraph "控制器层"
C
end
subgraph "服务层"
D
end
subgraph "数据访问层"
E
end
subgraph "数据存储"
F
end
```

**图示来源**
- [config.go](file://api/merchant/v1/config.go)
- [deploy.go](file://api/merchant/v1/deploy.go)
- [steal.go](file://api/merchant/v1/steal.go)

## 详细组件分析

### 商户配置管理分析
商户配置管理组件提供了商户的全生命周期管理功能，包括创建、查询、更新和状态管理。系统通过多租户架构实现了商户隔离，每个商户都有唯一的商户UID和密钥对，确保了数据的安全性和隔离性。

#### 对象导向组件：
```mermaid
classDiagram
class MerchantConfigListReq {
+string path : /merchant/config/getList
+string tags : 商户信息
+string method : get
+string summary : 获取商户列表信息
}
class MerchantConfigDetailReq {
+string path : /merchant/config/getDetail
+string tags : 商户信息
+string method : get
+string summary : 获取商户详细信息
+string merchantUid : 商户uid
}
class MerchantConfigUpdateReq {
+string path : /merchant/config/updateDetail
+string tags : 商户信息
+string method : post
+string summary : 修改商户信息
}
class MerchantConfigAddReq {
+string path : /merchant/config/add
+string tags : 商户信息
+string method : post
+string summary : 添加商户
}
class MerchantConfigStatusReq {
+string path : /merchant/config/switchStatus
+string tags : 商户信息
+string method : post
+string summary : 切换商户状态
+string merchantUid : 商户uid
+string status : 状态ID
}
MerchantConfigListReq --> MerchantListParamsReq : 包含
MerchantConfigDetailReq --> MerchantUid : 参数
MerchantConfigUpdateReq --> MerchantSimpleInfoRecord : 包含
MerchantConfigAddReq --> MerchantRecord : 包含
MerchantConfigStatusReq --> MerchantUid : 参数
MerchantConfigStatusReq --> Status : 参数
```

**图示来源**
- [config.go](file://api/merchant/v1/config.go#L15-L80)

#### API/服务组件：
```mermaid
sequenceDiagram
participant 客户端
participant Controller
participant Service
participant 数据库
客户端->>Controller : POST /merchant/config/add
Controller->>Controller : 创建事务
Controller->>Service : 调用Merchant().Add()
Service->>数据库 : 插入商户信息
数据库-->>Service : 成功
Service->>Service : 调用Account().Add()
Service->>数据库 : 插入账户信息
数据库-->>Service : 成功
Service-->>Controller : 成功
Controller-->>客户端 : 200 OK
```

**图示来源**
- [merchant_v1_merchant_config_add.go](file://internal/controller/merchant/merchant_v1_merchant_config_add.go#L1-L48)
- [merchant.go](file://internal/service/merchant.go#L17-L25)

**章节来源**
- [config.go](file://api/merchant/v1/config.go#L1-L80)
- [merchant_v1_merchant_config_add.go](file://internal/controller/merchant/merchant_v1_merchant_config_add.go#L1-L48)
- [merchant.go](file://internal/service/merchant.go#L1-L37)

### 部署信息管理分析
部署信息管理组件负责商户的通道部署配置，包括单通道和轮询通道的配置管理。系统支持灵活的部署策略，允许商户根据业务需求配置不同的支付通道和限制策略。

#### 对象导向组件：
```mermaid
classDiagram
class MerchantDeployListReq {
+string path : /merchant/deploy/getList
+string tags : 商户部署信息
+string method : get
+string summary : 获取商户部署通道信息
+string merchantUid : 商户uid
}
class MerchantDeployDeleteReq {
+string path : /merchant/deploy/delete
+string tags : 商户部署信息
+string method : delete
+string summary : 删除商户部署通道信息
+string merchantUid : 商户uid
+string singleRoadUid : 单通道uid
}
class MerchantDeployAddReq {
+string path : /merchant/deploy/add
+string tags : 商户部署信息
+string method : post
+string summary : 添加商户部署通道信息
}
class MerchantDeployUpdateReq {
+string path : /merchant/deploy/update
+string tags : 商户部署信息
+string method : post
+string summary : 更新商户部署通道信息
}
class MerchantDeployGetDetailReq {
+string path : merchant/deploy/getDetail
+string tags : 商户部署信息
+string method : get
+string summary : 获取商户部署通道详情
}
MerchantDeployListReq --> MerchantUid : 参数
MerchantDeployDeleteReq --> MerchantUid : 参数
MerchantDeployDeleteReq --> SingleRoadUid : 参数
MerchantDeployAddReq --> MerchantDeployRateAdd : 包含
MerchantDeployUpdateReq --> MerchantDeployRateUpdate : 包含
MerchantDeployGetDetailReq --> CommonIntId : 继承
```

**图示来源**
- [deploy.go](file://api/merchant/v1/deploy.go#L1-L56)

#### API/服务组件：
```mermaid
sequenceDiagram
participant 客户端
participant Controller
participant Service
participant 数据库
客户端->>Controller : POST /merchant/deploy/add
Controller->>Service : RoadPool().GetDetailByCode()
Service-->>Controller : 通道池信息
Controller->>Service : Road().GetDetailByUid()
Service-->>Controller : 通道信息
Controller->>Service : MerchantDeployInfo().AddOrUpdate()
Service->>数据库 : 插入或更新部署信息
数据库-->>Service : 成功
Service-->>Controller : 成功
Controller-->>客户端 : 200 OK
```

**图示来源**
- [merchant_v1_merchant_deploy_add.go](file://internal/controller/merchant/merchant_v1_merchant_deploy_add.go#L1-L53)
- [merchant_deploy_info.go](file://internal/service/merchant_deploy_info.go#L15-L28)

**章节来源**
- [deploy.go](file://api/merchant/v1/deploy.go#L1-L56)
- [merchant_v1_merchant_deploy_add.go](file://internal/controller/merchant/merchant_v1_merchant_deploy_add.go#L1-L53)
- [merchant_deploy_info.go](file://internal/service/merchant_deploy_info.go#L1-L40)

### 盗单规则管理分析
盗单规则管理组件实现了盗单策略的完整管理功能，包括规则的创建、更新、删除和状态管理。系统通过严格的验证机制确保规则的正确性，并提供详细的记录和统计功能。

#### 对象导向组件：
```mermaid
classDiagram
class StealStatusSetReq {
+string path : /merchant/config/stealRule/status
+string tags : 偷卡设置
+string method : post
+string summary : 设置偷卡状态
+bool status : 状态ID
}
class StealStatusGetReq {
+string path : /merchant/config/stealRule/status
+string tags : 偷卡设置
+string method : get
+string summary : 获取偷卡状态
}
class StealCreateReq {
+string path : /merchant/config/stealRule/create
+string tags : 偷卡设置
+string method : post
+string summary : 添加一条规则
}
class StealUpdateReq {
+string path : /merchant/config/stealRule/update
+string tags : 偷卡设置
+string method : post
+string summary : 更新一条规则
}
class StealUpdateStatusReq {
+string path : /merchant/config/stealRule/updateStatus
+string tags : 偷卡设置
+string method : post
+string summary : 更新一条规则
+int enable : 启用状态
}
class StealDeleteReq {
+string path : /merchant/config/stealRule/update
+string tags : 偷卡设置
+string method : delete
+string summary : 删除一条规则
}
class StealListReq {
+string path : /merchant/config/stealRule/list
+string tags : 偷卡设置
+string method : get
+string summary : 获取列表
}
class StealRecordListReq {
+string path : /merchant/config/stealRule/record
+string tags : 偷卡设置
+string method : get
+string summary : 获取偷卡记录
}
class StealStatsReq {
+string path : /merchant/config/stealRule/stats
+string tags : 偷卡设置
+string method : get
+string summary : 获取偷卡统计
}
StealCreateReq --> MerchantHiddenConfig : 包含
StealUpdateReq --> CommonIntId : 继承
StealUpdateReq --> MerchantHiddenConfig : 包含
StealUpdateStatusReq --> CommonIntId : 继承
StealDeleteReq --> CommonIntId : 继承
StealListReq --> CommonPageReq : 继承
StealRecordListReq --> CommonPageReq : 继承
StealStatsReq --> CommonPageReq : 继承
```

**图示来源**
- [steal.go](file://api/merchant/v1/steal.go#L1-L116)

#### API/服务组件：
```mermaid
sequenceDiagram
participant 客户端
participant Controller
participant Service
participant 数据库
客户端->>Controller : POST /merchant/config/stealRule/create
Controller->>Controller : 验证金额规则
alt 金额规则验证失败
Controller-->>客户端 : 400 Bad Request
else 金额规则验证成功
Controller->>Service : StealRule().Create()
Service->>数据库 : 插入盗单规则
数据库-->>Service : 成功
Service-->>Controller : 成功
Controller-->>客户端 : 200 OK
end
```

**图示来源**
- [merchant_v1_steal_create.go](file://internal/controller/merchant/merchant_v1_steal_create.go#L1-L25)
- [steal_rule.go](file://internal/service/steal_rule.go#L14-L24)

**章节来源**
- [steal.go](file://api/merchant/v1/steal.go#L1-L116)
- [merchant_v1_steal_create.go](file://internal/controller/merchant/merchant_v1_steal_create.go#L1-L25)
- [steal_rule.go](file://internal/service/steal_rule.go#L1-L36)

## 依赖分析
商户管理API的各个组件之间存在清晰的依赖关系。API层依赖于控制器层，控制器层依赖于服务层，服务层依赖于数据访问层。这种分层依赖确保了系统的可维护性和可测试性。服务层组件之间相对独立，通过接口进行通信，降低了耦合度。

```mermaid
graph TD
A[config.go] --> B[merchant_v1_merchant_config_*.go]
B --> C[merchant.go]
C --> D[v_1_merchant_info.go]
E[deploy.go] --> F[merchant_v1_merchant_deploy_*.go]
F --> G[merchant_deploy_info.go]
G --> H[v_1_merchant_deploy_info.go]
I[steal.go] --> J[merchant_v1_steal_*.go]
J --> K[steal_rule.go]
K --> L[v_1_merchant_hidden_config.go]
K --> M[v_1_merchant_hidden_record.go]
```

**图示来源**
- [config.go](file://api/merchant/v1/config.go)
- [deploy.go](file://api/merchant/v1/deploy.go)
- [steal.go](file://api/merchant/v1/steal.go)
- [merchant_v1_merchant_config_add.go](file://internal/controller/merchant/merchant_v1_merchant_config_add.go)
- [merchant_v1_merchant_deploy_add.go](file://internal/controller/merchant/merchant_v1_merchant_deploy_add.go)
- [merchant_v1_steal_create.go](file://internal/controller/merchant/merchant_v1_steal_create.go)

**章节来源**
- [config.go](file://api/merchant/v1/config.go#L1-L80)
- [deploy.go](file://api/merchant/v1/deploy.go#L1-L56)
- [steal.go](file://api/merchant/v1/steal.go#L1-L116)
- [merchant_v1_merchant_config_add.go](file://internal/controller/merchant/merchant_v1_merchant_config_add.go#L1-L48)
- [merchant_v1_merchant_deploy_add.go](file://internal/controller/merchant/merchant_v1_merchant_deploy_add.go#L1-L53)
- [merchant_v1_steal_create.go](file://internal/controller/merchant/merchant_v1_steal_create.go#L1-L25)

## 性能考虑
商户管理API在设计时考虑了性能优化。通过数据库事务确保数据一致性，使用缓存减少数据库访问，采用分页查询避免大数据量传输。对于频繁访问的数据，建议客户端实现本地缓存。API响应时间应控制在200ms以内，对于复杂查询应提供异步处理选项。

## 故障排除指南
常见问题包括商户创建失败、部署配置无效和盗单规则验证错误。对于商户创建失败，检查请求参数是否完整，特别是必填字段如商户名称和登录密码。对于部署配置无效，验证通道UID是否存在且状态正常。对于盗单规则验证错误，确保偷卡金额不大于偷卡面额。所有错误都会返回详细的错误信息，帮助快速定位问题。

**章节来源**
- [merchant_v1_merchant_config_add.go](file://internal/controller/merchant/merchant_v1_merchant_config_add.go#L1-L48)
- [merchant_v1_merchant_deploy_add.go](file://internal/controller/merchant/merchant_v1_merchant_deploy_add.go#L1-L53)
- [merchant_v1_steal_create.go](file://internal/controller/merchant/merchant_v1_steal_create.go#L1-L25)

## 结论
商户管理API提供了一套完整的商户生命周期管理解决方案，通过清晰的分层架构和模块化设计，实现了商户配置、部署管理和盗单处理等核心功能。系统采用多租户架构，确保了商户数据的隔离性和安全性。API设计遵循RESTful原则，提供了标准化的接口，便于客户端集成和使用。