# 商户配置API

<cite>
**本文档引用的文件**
- [kami-api-merchant-v1-merchant-config-add-req.ts](file://src/api/generated/models/kami-api-merchant-v1-merchant-config-add-req.ts)
- [kami-api-merchant-v1-merchant-config-update-req.ts](file://src/api/generated/models/kami-api-merchant-v1-merchant-config-update-req.ts)
- [kami-api-merchant-v1-steal-create-req.ts](file://src/api/generated/models/kami-api-merchant-v1-steal-create-req.ts)
- [kami-api-merchant-v1-steal-list-req.ts](file://src/api/generated/models/kami-api-merchant-v1-steal-list-req.ts)
- [kami-api-merchant-v1-steal-update-req.ts](file://src/api/generated/models/kami-api-merchant-v1-steal-update-req.ts)
- [kami-api-merchant-v1-steal-status-set-req.ts](file://src/api/generated/models/kami-api-merchant-v1-steal-status-set-req.ts)
- [merchant-list.ts](file://src/api/merchant-list.ts)
- [merchant-deploy.ts](file://src/api/merchant-deploy.ts)
- [ck-api.ts](file://src/api/generated/apis/ck-api.ts)
- [index.ts](file://src/api/index.ts)
- [config/index.vue](file://src/views/merchant/config/index.vue)
- [steal-card/list.vue](file://src/views/merchant/steal-card/list.vue)
- [steal-setting/index.vue](file://src/views/merchant/steal-setting/index.vue)
</cite>

## 目录

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

## 简介

本文档全面介绍了商户信息管理接口，涵盖商户的增删改查操作、配置状态管理、抽卡规则设置与更新、抽卡状态控制等功能。详细说明了KamiApiMerchantV1MerchantConfigAddReq、KamiApiMerchantV1MerchantConfigUpdateReq等请求模型的字段含义和使用方法。解释了商户抽卡管理接口，包括抽卡创建、更新、删除、状态设置及抽卡记录查询等功能，并提供KamiApiMerchantV1StealCreateReq、KamiApiMerchantV1StealListReq等接口的具体使用示例。描述了商户信息查询API，包括商户列表获取、配置详情查询、平台费率查询等操作。提供完整的代码示例，展示如何通过这些API实现商户全生命周期管理。说明API的权限验证机制、数据校验规则和错误处理策略，为开发者提供集成测试建议。

## 项目结构

本项目采用模块化设计，主要分为配置、部署、API接口、视图组件等部分。核心的商户配置功能位于src/views/merchant目录下，包含config（商户配置）、steal-card（抽卡管理）和steal-setting（抽卡设置）三个主要模块。API接口定义在src/api/generated目录下，通过TypeScript接口定义了所有请求和响应模型。前端API调用封装在src/api目录下，提供了对后端API的抽象访问。

```mermaid
graph TB
subgraph "前端视图"
Config[商户配置]
StealCard[抽卡管理]
StealSetting[抽卡设置]
end
subgraph "API接口"
Models[请求/响应模型]
Apis[API定义]
Services[服务封装]
end
subgraph "核心功能"
MerchantConfig[商户配置管理]
StealRule[抽卡规则管理]
StatusControl[状态控制]
end
Config --> MerchantConfig
StealCard --> StealRule
StealSetting --> StealRule
Models --> Apis
Apis --> Services
Services --> MerchantConfig
Services --> StealRule
Services --> StatusControl
```

**图示来源**

- [config/index.vue](file://src/views/merchant/config/index.vue)
- [steal-card/list.vue](file://src/views/merchant/steal-card/list.vue)
- [steal-setting/index.vue](file://src/views/merchant/steal-setting/index.vue)
- [merchant-list.ts](file://src/api/merchant-list.ts)
- [merchant-deploy.ts](file://src/api/merchant-deploy.ts)

**章节来源**

- [src/views/merchant](file://src/views/merchant)

## 核心组件

核心组件包括商户配置管理、抽卡规则管理和状态控制。商户配置管理提供商户的增删改查功能，通过KamiApiMerchantV1MerchantConfigAddReq和KamiApiMerchantV1MerchantConfigUpdateReq接口实现。抽卡规则管理提供抽卡规则的创建、更新、删除和查询功能，通过KamiApiMerchantV1StealCreateReq、KamiApiMerchantV1StealUpdateReq等接口实现。状态控制提供全局抽卡开关和单个规则状态控制功能。

**章节来源**

- [kami-api-merchant-v1-merchant-config-add-req.ts](file://src/api/generated/models/kami-api-merchant-v1-merchant-config-add-req.ts)
- [kami-api-merchant-v1-merchant-config-update-req.ts](file://src/api/generated/models/kami-api-merchant-v1-merchant-config-update-req.ts)
- [kami-api-merchant-v1-steal-create-req.ts](file://src/api/generated/models/kami-api-merchant-v1-steal-create-req.ts)

## 架构概述

系统采用前后端分离架构，前端通过API调用与后端进行通信。前端使用Vue 3框架，结合TypeScript提供类型安全的开发体验。API接口通过OpenAPI Generator自动生成，确保前后端接口的一致性。商户配置和抽卡管理功能通过独立的服务模块进行封装，提供清晰的API边界。

```mermaid
graph LR
A[前端界面] --> B[API服务]
B --> C[商户配置服务]
B --> D[抽卡管理服务]
B --> E[状态控制服务]
C --> F[数据库]
D --> F
E --> F
```

**图示来源**

- [ck-api.ts](file://src/api/generated/apis/ck-api.ts)
- [index.ts](file://src/api/index.ts)
- [merchant-list.ts](file://src/api/merchant-list.ts)

## 详细组件分析

### 商户配置管理分析

商户配置管理组件提供商户的全生命周期管理功能，包括商户的创建、更新、状态切换和列表查询。通过merchant-list.ts中的函数封装了对后端API的调用，提供了类型安全的接口访问。

#### 类图

```mermaid
classDiagram
class MerchantConfigAddRecord {
+string merchantName
+string loginAccount
+string loginPassword
+string remark
+string status
}
class MerchantConfigResRecord {
+string status
+string belongAgentUid
+string belongAgentName
+string merchantName
+string merchantUid
+string merchantKey
+string merchantSecret
+string loginAccount
+string whiteIps
+string remark
+string singlePayForRoadUid
+string singlePayForRoadName
+string rollPayForRoadCode
+string rollPayForRoadName
+number payforFee
+string updateTime
+string createTime
}
class MerchantConfigDetailRecord {
+string loginAccount
+string merchantName
+string merchantUid
+string whiteIps
+string remark
}
class MerchantConfigParams {
+string merchantName
+string loginAccount
+string merchantUid
+number current
+number pageSize
}
class MerchantConfigAddReq {
+string status
+string merchantName
+string loginAccount
+string remark
+string loginPassword
}
class MerchantConfigUpdateReq {
+string merchantName
+string merchantUid
+string loginAccount
+string whiteIps
+string remark
}
MerchantConfigAddRecord <|-- MerchantConfigAddReq
MerchantConfigDetailRecord <|-- MerchantConfigUpdateReq
MerchantConfigParams <|-- Pagination
```

**图示来源**

- [kami-api-merchant-v1-merchant-config-add-req.ts](file://src/api/generated/models/kami-api-merchant-v1-merchant-config-add-req.ts)
- [kami-api-merchant-v1-merchant-config-update-req.ts](file://src/api/generated/models/kami-api-merchant-v1-merchant-config-update-req.ts)
- [merchant-list.ts](file://src/api/merchant-list.ts)

### 抽卡规则管理分析

抽卡规则管理组件提供抽卡规则的创建、更新、删除和查询功能。通过steal-card/list.vue组件实现规则列表的展示和操作，支持分页查询、状态切换和规则删除。

#### 序列图

```mermaid
sequenceDiagram
participant UI as "用户界面"
participant Service as "API服务"
participant Backend as "后端API"
UI->>Service : 获取抽卡规则列表
Service->>Backend : GET /api/merchant/config/steal/rule/list
Backend-->>Service : 返回规则列表
Service-->>UI : 显示规则列表
UI->>Service : 创建抽卡规则
Service->>Backend : POST /api/merchant/config/steal/rule/add
Backend-->>Service : 返回创建结果
Service-->>UI : 刷新列表
UI->>Service : 更新抽卡规则状态
Service->>Backend : POST /api/merchant/config/steal/rule/update/status
Backend-->>Service : 返回更新结果
Service-->>UI : 更新界面显示
```

**图示来源**

- [kami-api-merchant-v1-steal-create-req.ts](file://src/api/generated/models/kami-api-merchant-v1-steal-create-req.ts)
- [kami-api-merchant-v1-steal-update-req.ts](file://src/api/generated/models/kami-api-merchant-v1-steal-update-req.ts)
- [steal-card/list.vue](file://src/views/merchant/steal-card/list.vue)

### 状态控制分析

状态控制组件提供全局抽卡开关和单个规则状态控制功能。通过开关组件实现状态的实时切换，确保用户操作的即时反馈。

#### 流程图

```mermaid
flowchart TD
Start([开始]) --> CheckStatus["检查当前状态"]
CheckStatus --> Status{"状态是否改变?"}
Status --> |是| UpdateStatus["更新状态"]
UpdateStatus --> CallAPI["调用API更新状态"]
CallAPI --> APIResult{"API调用成功?"}
APIResult --> |是| RefreshUI["刷新界面"]
APIResult --> |否| ShowError["显示错误信息"]
Status --> |否| End([结束])
RefreshUI --> End
ShowError --> End
```

**图示来源**

- [kami-api-merchant-v1-steal-status-set-req.ts](file://src/api/generated/models/kami-api-merchant-v1-steal-status-set-req.ts)
- [steal-card/list.vue](file://src/views/merchant/steal-card/list.vue)

**章节来源**

- [kami-api-merchant-v1-steal-status-set-req.ts](file://src/api/generated/models/kami-api-merchant-v1-steal-status-set-req.ts)
- [steal-card/list.vue](file://src/views/merchant/steal-card/list.vue)

## 依赖分析

系统各组件之间存在明确的依赖关系。视图组件依赖于API服务，API服务依赖于生成的模型定义。商户配置管理、抽卡规则管理和状态控制功能相互独立，但共享相同的API调用机制和数据模型。

```mermaid
graph TD
A[视图组件] --> B[API服务]
B --> C[生成的模型]
C --> D[TypeScript接口]
B --> E[axios]
F[OpenAPI Generator] --> C
G[配置文件] --> F
```

**图示来源**

- [index.ts](file://src/api/index.ts)
- [ck-api.ts](file://src/api/generated/apis/ck-api.ts)
- [models目录](file://src/api/generated/models)

**章节来源**

- [index.ts](file://src/api/index.ts)
- [ck-api.ts](file://src/api/generated/apis/ck-api.ts)

## 性能考虑

系统在设计时考虑了性能优化，采用分页查询避免一次性加载大量数据，通过状态管理减少不必要的API调用。前端使用Vue的响应式系统，确保界面更新的高效性。API调用采用axios进行封装，支持请求拦截和响应处理，便于性能监控和优化。

## 故障排除指南

常见问题包括API调用失败、数据加载异常和状态更新不及时。建议检查网络连接、API端点配置和请求参数。对于状态更新问题，确保正确处理API响应并及时刷新界面状态。对于数据加载问题，检查分页参数和查询条件是否正确。

**章节来源**

- [merchant-list.ts](file://src/api/merchant-list.ts)
- [merchant-deploy.ts](file://src/api/merchant-deploy.ts)
- [steal-card/list.vue](file://src/views/merchant/steal-card/list.vue)

## 结论

商户配置API提供了完整的商户管理和抽卡规则管理功能，通过清晰的接口设计和类型安全的实现，确保了系统的稳定性和可维护性。系统采用模块化设计，各组件职责明确，便于扩展和维护。建议在使用时遵循API文档的指导，正确处理错误情况，确保系统的稳定运行。

## 附录

### 请求模型字段说明

#### KamiApiMerchantV1MerchantConfigAddReq

- **status**: 商户状态，表示商户的激活或冻结状态
- **merchantName**: 商户名称，用于标识商户
- **loginAccount**: 登录账号，商户的登录凭证
- **remark**: 备注，可选字段，用于添加额外信息
- **loginPassword**: 登录密码，商户的登录凭证

#### KamiApiMerchantV1MerchantConfigUpdateReq

- **merchantName**: 商户名称，用于更新商户信息
- **merchantUid**: 商户uid，用于标识要更新的商户
- **loginAccount**: 登录账号，用于更新登录信息
- **whiteIps**: 配置ip白名单，可选字段，用于安全控制
- **remark**: 备注，可选字段，用于更新额外信息

#### KamiApiMerchantV1StealCreateReq

- **name**: 规则名称，用于标识抽卡规则
- **merchantUid**: 商户id，关联抽卡规则到特定商户
- **roadUid**: 通道id，指定抽卡的通道
- **extraReturnInfo**: 返回信息，可选字段，用于附加信息
- **amount**: 偷卡金额间隔，定义抽卡的金额范围
- **faceAmount**: 偷卡面额，定义抽卡的面额
- **delayDurationMin**: 最小延迟时间，定义抽卡的最小延迟
- **delayDurationMax**: 最大延迟时间，定义抽卡的最大延迟
- **enable**: 启用状态，定义规则是否启用
- **strategy**: 抽卡策略，定义抽卡的具体策略
- **amountRule**: 金额规则，定义抽卡的金额规则

### API使用示例

```typescript
// 添加商户配置
const addMerchantConfig = (data: MerchantConfigAddRecord) => {
  return axios.post('/api/merchant/config/add', data);
};

// 更新商户信息
const updateMerchantInfo = (data: MerchantConfigDetailRecord) => {
  return axios.post('/api/merchant/config/updateDetail', data);
};

// 切换商户状态
const switchMerchantStatus = (params: {
  merchantUid: string;
  status: string;
}) => {
  return axios.post('/api/merchant/config/switchStatus', params);
};

// 获取商户配置列表
const queryMerchantConfigList = (params: MerchantConfigParams) => {
  return axios.get<CommonPageResult<MerchantConfigResRecord>>(
    '/api/merchant/config/getList',
    {
      params,
      paramsSerializer: obj => {
        return qs.stringify(obj);
      }
    }
  );
};
```
