# 商户管理逻辑

<cite>
**本文档引用的文件**
- [merchant.go](file://internal/model/merchant.go)
- [merchant_v1_merchant_config_list.go](file://internal/controller/merchant/merchant_v1_merchant_config_list.go)
- [merchant_v1_merchant_config_detail.go](file://internal/controller/merchant/merchant_v1_merchant_config_detail.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_sample_all_list.go](file://internal/controller/merchant/merchant_v1_merchant_sample_all_list.go)
- [v_1_merchant_info.go](file://internal/dao/internal/v_1_merchant_info.go)
- [v_1_merchant_deploy_info.go](file://internal/dao/internal/v_1_merchant_deploy_info.go)
- [merchant.go](file://internal/service/merchant.go)
- [config.go](file://api/merchant/v1/config.go)
</cite>

## 目录
1. [引言](#引言)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概述](#架构概述)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
10. [附录](#附录)（如有必要）

## 引言
本文档详细阐述了kami_backend系统中商户管理业务逻辑的实现。重点说明商户配置管理、商户部署信息维护和商户样本管理的功能实现，以及商户与卡密通道、支付方式的关联关系。文档解释了商户配置的增删改查操作流程和权限控制机制，描述了商户部署信息的同步策略和状态管理，并提供了商户管理API的使用示例和最佳实践。同时，包括了商户数据隔离策略和多租户支持的实现细节。

## 项目结构
商户管理功能主要分布在`api/merchant`和`internal/controller/merchant`目录下，通过分层架构实现业务逻辑。API接口定义在`api/merchant/v1`包中，控制器实现位于`internal/controller/merchant`包中，服务层逻辑在`internal/service/merchant.go`中定义，数据访问对象（DAO）则在`internal/dao/internal`包中实现。

```mermaid
graph TB
subgraph "API层"
A[api/merchant/v1/config.go]
B[api/merchant/v1/deploy.go]
C[api/merchant/v1/model.go]
end
subgraph "控制器层"
D[internal/controller/merchant/merchant_v1_merchant_config_list.go]
E[internal/controller/merchant/merchant_v1_merchant_config_detail.go]
F[internal/controller/merchant/merchant_v1_merchant_config_update.go]
G[internal/controller/merchant/merchant_v1_merchant_config_status.go]
H[internal/controller/merchant/merchant_v1_merchant_sample_all_list.go]
end
subgraph "服务层"
I[internal/service/merchant.go]
end
subgraph "数据访问层"
J[internal/dao/internal/v_1_merchant_info.go]
K[internal/dao/internal/v_1_merchant_deploy_info.go]
end
A --> D
B --> D
C --> D
D --> I
E --> I
F --> I
G --> I
H --> I
I --> J
I --> K
```

**图示来源**
- [config.go](file://api/merchant/v1/config.go)
- [merchant_v1_merchant_config_list.go](file://internal/controller/merchant/merchant_v1_merchant_config_list.go)
- [merchant.go](file://internal/service/merchant.go)
- [v_1_merchant_info.go](file://internal/dao/internal/v_1_merchant_info.go)

**章节来源**
- [merchant.go](file://internal/model/merchant.go)
- [merchant_v1_merchant_config_list.go](file://internal/controller/merchant/merchant_v1_merchant_config_list.go)

## 核心组件
商户管理的核心组件包括商户配置管理、商户部署信息维护和商户样本管理。这些功能通过`IMerchant`接口定义，并由`service.Merchant()`实现。系统通过`V1MerchantInfoDao`和`V1MerchantDeployInfoDao`两个数据访问对象分别管理商户基本信息和部署信息。

**章节来源**
- [merchant.go](file://internal/service/merchant.go)
- [v_1_merchant_info.go](file://internal/dao/internal/v_1_merchant_info.go)
- [v_1_merchant_deploy_info.go](file://internal/dao/internal/v_1_merchant_deploy_info.go)

## 架构概述
商户管理模块采用典型的分层架构，从API接口到数据访问层形成清晰的调用链路。API层定义了商户配置的增删改查接口，控制器层处理HTTP请求并调用服务层，服务层封装业务逻辑并协调数据访问，DAO层负责与数据库交互。

```mermaid
sequenceDiagram
participant Client as "客户端"
participant API as "API接口"
participant Controller as "控制器"
participant Service as "服务层"
participant DAO as "数据访问层"
participant DB as "数据库"
Client->>API : 发起商户配置请求
API->>Controller : 路由到对应控制器
Controller->>Service : 调用服务方法
Service->>DAO : 执行数据操作
DAO->>DB : 执行SQL查询
DB-->>DAO : 返回查询结果
DAO-->>Service : 返回数据实体
Service-->>Controller : 返回业务结果
Controller-->>API : 返回响应数据
API-->>Client : 返回JSON响应
Note over Client,DB : 商户管理模块调用流程
```

**图示来源**
- [merchant.go](file://internal/service/merchant.go)
- [merchant_v1_merchant_config_list.go](file://internal/controller/merchant/merchant_v1_merchant_config_list.go)
- [v_1_merchant_info.go](file://internal/dao/internal/v_1_merchant_info.go)

## 详细组件分析
### 商户配置管理分析
商户配置管理功能实现了商户信息的增删改查操作，包括商户基本信息、状态管理和权限控制。系统通过`MerchantConfigList`、`MerchantConfigDetail`、`MerchantConfigUpdate`和`MerchantConfigStatus`等接口提供完整的配置管理能力。

#### 商户配置类图
```mermaid
classDiagram
class MerchantInfoRecord {
+string MerchantName
+string MerchantUid
+string MerchantKey
+string MerchantSecret
+string LoginAccount
+string LoginPassword
+bool AutoSettle
+bool AutoPayFor
+string WhiteIps
+string Remark
+string SinglePayForRoadUid
+string RollPayForRoadCode
+float PayforFee
}
class MerchantSimpleInfoRecord {
+string MerchantUid
+string MerchantName
+string BelongAgentUid
+string BelongAgentName
+int Status
+string OtpSecret
}
class MerchantListParamsInput {
+string MerchantUid
+string MerchantName
+int Current
+int PageSize
}
class MerchantDeployInfoStrategyOutput {
+string[] RestrictArea
+bool IsRestrictAgent
+bool IsRestrictCardPass
+bool IsRestrictDevice
+bool IsRestrictIp
+bool IsRestrictInternalIp
}
MerchantInfoRecord <|-- MerchantSimpleInfoRecord : "继承"
MerchantListParamsInput --> MerchantInfoRecord : "查询参数"
MerchantDeployInfoStrategyOutput --> MerchantSimpleInfoRecord : "部署策略"
```

**图示来源**
- [merchant.go](file://internal/model/merchant.go)
- [v_1_merchant_info.go](file://internal/dao/internal/v_1_merchant_info.go)

#### 商户配置更新序列图
```mermaid
sequenceDiagram
participant Client as "客户端"
participant Controller as "ControllerV1"
participant Service as "IMerchant"
participant DAO as "V1MerchantInfoDao"
participant DB as "数据库"
Client->>Controller : MerchantConfigUpdate请求
Controller->>Service : 调用UpdateDetail方法
Service->>DAO : 获取商户信息
DAO->>DB : 查询merchant_info表
DB-->>DAO : 返回商户数据
DAO-->>Service : 返回数据实体
Service->>Service : 更新商户信息
Service->>DAO : 保存更新
DAO->>DB : 执行UPDATE语句
DB-->>DAO : 返回执行结果
DAO-->>Service : 返回操作结果
Service-->>Controller : 返回成功/失败
Controller-->>Client : 返回响应
Note over Client,DB : 商户配置更新流程
```

**图示来源**
- [merchant_v1_merchant_config_update.go](file://internal/controller/merchant/merchant_v1_merchant_config_update.go)
- [merchant.go](file://internal/service/merchant.go)
- [v_1_merchant_info.go](file://internal/dao/internal/v_1_merchant_info.go)

**章节来源**
- [merchant_v1_merchant_config_update.go](file://internal/controller/merchant/merchant_v1_merchant_config_update.go)
- [merchant.go](file://internal/service/merchant.go)

### 商户部署信息管理分析
商户部署信息管理功能负责维护商户的部署策略和通道配置，包括支付方式、代付通道、区域限制等。系统通过`merchant_deploy_info`表存储这些配置信息，并提供相应的增删改查接口。

#### 商户部署信息类图
```mermaid
classDiagram
class MerchantDeployRecord {
+string MerchantUid
+string PayType
+string SingleRoadUid
+string SingleRoadName
+float SingleRoadPlatformRate
+float SingleRoadAgentRate
+string RollRoadCode
+string RollRoadName
+float RollRoadPlatformRate
+float RollRoadAgentRate
+string[] RestrictArea
+bool IsLoan
+float LoanRate
+int LoanDays
+int UnfreezeHour
+float WaitUnfreezeAmount
+float LoanAmount
+bool AutoSettle
+bool AutoPayfor
+bool IsRestrictAgent
+bool IsRestrictCardPass
+bool IsRestrictDevice
+bool IsRestrictIp
+bool IsRestrictInternalIp
+string SubmitStrategy
}
class MerchantDeployInfoStrategyOutput {
+string[] RestrictArea
+bool IsRestrictAgent
+bool IsRestrictCardPass
+bool IsRestrictDevice
+bool IsRestrictIp
+bool IsRestrictInternalIp
}
MerchantDeployRecord --> MerchantDeployInfoStrategyOutput : "包含"
```

**图示来源**
- [merchant.go](file://internal/model/merchant.go)
- [v_1_merchant_deploy_info.go](file://internal/dao/internal/v_1_merchant_deploy_info.go)

**章节来源**
- [v_1_merchant_deploy_info.go](file://internal/dao/internal/v_1_merchant_deploy_info.go)
- [merchant.go](file://internal/model/merchant.go)

## 依赖分析
商户管理模块与其他系统组件存在明确的依赖关系。它依赖于权限认证系统进行访问控制，依赖于数据库访问层进行数据持久化，并为其他业务模块提供商户信息查询服务。

```mermaid
graph TD
A[商户管理模块] --> B[权限认证系统]
A --> C[数据库访问层]
A --> D[配置管理]
A --> E[代付通道管理]
A --> F[卡密通道管理]
B --> G[SysAuth]
C --> H[V1MerchantInfoDao]
C --> I[V1MerchantDeployInfoDao]
D --> J[SysConfigDict]
E --> K[PayForRoad]
F --> L[CardChannel]
style A fill:#f9f,stroke:#333
style B fill:#bbf,stroke:#333
style C fill:#bbf,stroke:#333
style D fill:#bbf,stroke:#333
style E fill:#bbf,stroke:#333
style F fill:#bbf,stroke:#333
```

**图示来源**
- [merchant.go](file://internal/service/merchant.go)
- [v_1_merchant_info.go](file://internal/dao/internal/v_1_merchant_info.go)
- [v_1_merchant_deploy_info.go](file://internal/dao/internal/v_1_merchant_deploy_info.go)

**章节来源**
- [merchant.go](file://internal/service/merchant.go)
- [sys_auth.go](file://internal/service/sys_auth.go)
- [v_1_merchant_info.go](file://internal/dao/internal/v_1_merchant_info.go)

## 性能考虑
商户管理模块在设计时考虑了性能优化，通过分页查询、缓存机制和数据库索引等方式提高查询效率。对于频繁访问的商户信息，系统可以考虑引入Redis缓存，减少数据库访问压力。同时，所有数据库操作都使用了参数化查询，防止SQL注入攻击。

## 故障排除指南
当商户管理功能出现异常时，可以按照以下步骤进行排查：
1. 检查API接口返回的错误码和错误信息
2. 查看系统日志中的相关错误记录
3. 验证数据库连接是否正常
4. 检查商户信息表中的数据完整性
5. 确认权限认证是否通过

**章节来源**
- [merchant_v1_merchant_config_list.go](file://internal/controller/merchant/merchant_v1_merchant_config_list.go)
- [merchant_v1_merchant_config_detail.go](file://internal/controller/merchant/merchant_v1_merchant_config_detail.go)
- [merchant_v1_merchant_config_status.go](file://internal/controller/merchant/merchant_v1_merchant_config_status.go)

## 结论
kami_backend的商户管理模块实现了完整的商户配置管理、部署信息维护和样本管理功能。系统通过清晰的分层架构和规范的接口设计，提供了稳定可靠的商户管理服务。权限控制机制确保了数据安全，而灵活的配置选项满足了不同商户的个性化需求。该模块为整个系统的商户管理提供了坚实的基础。