# 商户管理系统

<cite>
**本文档引用文件**  
- [merchant-list.ts](file://src/api/merchant-list.ts)
- [merchant-deploy.ts](file://src/api/merchant-deploy.ts)
- [apple-card-steal-settings.ts](file://src/api/apple-card-steal-settings.ts)
- [index.vue](file://src/views/merchant/config/index.vue)
- [add-modal.vue](file://src/views/merchant/config/components/add-modal.vue)
- [deploy-modal.vue](file://src/views/merchant/config/components/deploy-modal.vue)
- [steal-setting/index.vue](file://src/views/merchant/steal-setting/index.vue)
- [steal-card/index.vue](file://src/views/merchant/steal-card/index.vue)
- [steal-card/list.vue](file://src/views/merchant/steal-card/list.vue)
- [steal-card/record.vue](file://src/views/merchant/steal-card/record.vue)
- [steal-card/stats.vue](file://src/views/merchant/steal-card/stats.vue)
- [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-deploy-add-req.ts](file://src/api/generated/models/kami-api-merchant-v1-merchant-deploy-add-req.ts)
- [kami-api-merchant-v1-steal-create-req.ts](file://src/api/generated/models/kami-api-merchant-v1-steal-create-req.ts)
</cite>

## 目录

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

## 简介

本系统为kami_frontend项目中的商户管理模块，提供完整的商户配置、抽卡管理、通道部署等功能。系统支持商户的创建、状态管理、权限控制和安全配置，同时提供灵活的抽卡规则定义与执行机制。商户管理系统与其他功能模块如卡券管理、订单处理等深度集成，实现统一的业务流程管理。

## 项目结构

商户管理功能主要集中在`src/views/merchant`目录下，包含配置管理、抽卡设置和抽卡记录三大功能模块。API接口定义位于`src/api`目录，数据模型由后端生成并存放在`src/api/generated`目录中。

```mermaid
graph TD
A[商户管理] --> B[商户配置]
A --> C[抽卡设置]
A --> D[抽卡管理]
B --> E[商户列表]
B --> F[通道部署]
C --> G[规则管理]
D --> H[规则列表]
D --> I[匹配记录]
D --> J[统计分析]
```

**图示来源**

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

**章节来源**

- [index.vue](file://src/views/merchant/config/index.vue)
- [steal-card/index.vue](file://src/views/merchant/steal-card/index.vue)

## 核心组件

系统核心功能包括商户配置管理、通道部署配置和抽卡规则管理。商户配置提供商户基本信息的增删改查功能，通道部署实现商户与支付通道的关联配置，抽卡管理则提供完整的抽卡规则定义、执行和监控能力。

**章节来源**

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

## 架构概览

系统采用前后端分离架构，前端基于Vue3和Arco Design组件库构建用户界面，通过API调用与后端服务交互。商户管理模块遵循模块化设计原则，各功能组件职责分明，通过统一的API服务层进行数据交互。

```mermaid
graph LR
UI[用户界面] --> API[API服务层]
API --> Backend[后端服务]
Backend --> Database[(数据库)]
UI --> Store[状态管理]
Store --> UI
```

**图示来源**

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

## 详细组件分析

### 商户配置分析

商户配置功能提供商户的全生命周期管理，包括创建、查询、修改和状态切换。系统通过表单界面收集商户信息，验证后提交至后端服务进行持久化存储。

#### 对象导向组件

```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
}
MerchantConfigAddRecord --> MerchantConfigResRecord : "扩展"
```

**图示来源**

- [merchant-list.ts](file://src/api/merchant-list.ts)

#### API服务组件

```mermaid
sequenceDiagram
participant 用户 as 用户界面
participant API as API服务
participant 后端 as 后端服务
用户->>API : 提交商户创建请求
API->>后端 : POST /api/merchant/config/add
后端-->>API : 返回创建结果
API-->>用户 : 显示操作结果
用户->>API : 请求商户列表
API->>后端 : GET /api/merchant/config/getList
后端-->>API : 返回商户列表数据
API-->>用户 : 渲染商户列表
```

**图示来源**

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

**章节来源**

- [merchant-list.ts](file://src/api/merchant-list.ts)
- [index.vue](file://src/views/merchant/config/index.vue)
- [add-modal.vue](file://src/views/merchant/config/components/add-modal.vue)

### 抽卡设置分析

抽卡设置功能用于管理系统的抽卡规则，包括全局开关控制、规则增删改查和状态管理。系统提供直观的界面操作，支持批量管理和实时状态更新。

#### 复杂逻辑组件

```mermaid
flowchart TD
Start([开始]) --> CheckStatus["检查抽卡全局状态"]
CheckStatus --> StatusValid{"状态有效?"}
StatusValid --> |是| ShowRules["显示规则列表"]
StatusValid --> |否| ShowDisabled["显示禁用状态"]
ShowRules --> UserAction["用户操作"]
UserAction --> AddRule["添加规则"]
UserAction --> EditRule["编辑规则"]
UserAction --> DeleteRule["删除规则"]
AddRule --> ValidateInput["验证输入"]
EditRule --> ValidateInput
DeleteRule --> ConfirmDelete["确认删除"]
ValidateInput --> InputValid{"输入有效?"}
InputValid --> |否| ShowError["显示错误"]
InputValid --> |是| SubmitRequest["提交请求"]
SubmitRequest --> UpdateUI["更新界面"]
ConfirmDelete --> ExecuteDelete["执行删除"]
ExecuteDelete --> UpdateUI
UpdateUI --> End([结束])
ShowError --> End
```

**图示来源**

- [apple-card-steal-settings.ts](file://src/api/apple-card-steal-settings.ts)
- [steal-setting/index.vue](file://src/views/merchant/steal-setting/index.vue)

**章节来源**

- [apple-card-steal-settings.ts](file://src/api/apple-card-steal-settings.ts)
- [steal-setting/index.vue](file://src/views/merchant/steal-setting/index.vue)

### 抽卡管理分析

抽卡管理功能提供抽卡规则的详细管理，包括规则列表、匹配记录和统计分析三个子模块。用户可以通过标签页在不同视图间切换，获取全面的抽卡执行信息。

#### API服务组件

```mermaid
sequenceDiagram
participant 用户 as 用户界面
participant API as API服务
participant 后端 as 后端服务
用户->>API : 请求抽卡规则列表
API->>后端 : GET /api/merchant/deploy/getList
后端-->>API : 返回规则列表
API-->>用户 : 渲染规则列表
用户->>API : 切换规则状态
API->>后端 : PUT /api/merchant/deploy/updateStatus
后端-->>API : 返回更新结果
API-->>用户 : 更新界面状态
用户->>API : 请求匹配记录
API->>后端 : GET /api/merchant/deploy/getRecord
后端-->>API : 返回匹配记录
API-->>用户 : 渲染记录列表
```

**图示来源**

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

**章节来源**

- [steal-card/list.vue](file://src/views/merchant/steal-card/list.vue)
- [steal-card/record.vue](file://src/views/merchant/steal-card/record.vue)
- [steal-card/stats.vue](file://src/views/merchant/steal-card/stats.vue)

## 依赖分析

商户管理系统依赖多个核心模块和服务，形成完整的功能闭环。系统通过API服务层与后端交互，利用状态管理存储用户会话信息，并集成权限控制确保操作安全。

```mermaid
graph TD
A[商户管理系统] --> B[API服务]
A --> C[状态管理]
A --> D[权限控制]
A --> E[UI组件库]
B --> F[后端服务]
C --> G[浏览器存储]
D --> H[认证服务]
E --> I[Arco Design]
```

**图示来源**

- [merchant-list.ts](file://src/api/merchant-list.ts)
- [merchant-deploy.ts](file://src/api/merchant-deploy.ts)

**章节来源**

- [merchant-list.ts](file://src/api/merchant-list.ts)
- [merchant-deploy.ts](file://src/api/merchant-deploy.ts)

## 性能考虑

系统在设计时充分考虑了性能优化，采用分页加载机制避免大数据量请求，通过状态缓存减少重复API调用。界面响应式设计确保在不同设备上都有良好的用户体验，异步操作避免界面阻塞。

## 故障排除指南

常见问题包括商户创建失败、抽卡规则不生效和数据加载异常。解决方案包括检查网络连接、验证输入数据格式、确认权限配置和查看浏览器控制台错误信息。对于持久性问题，建议清除浏览器缓存并重新登录系统。

**章节来源**

- [merchant-list.ts](file://src/api/merchant-list.ts)
- [apple-card-steal-settings.ts](file://src/api/apple-card-steal-settings.ts)

## 结论

商户管理系统提供了完整的商户管理解决方案，功能完善、架构清晰。系统通过模块化设计实现了高内聚低耦合，便于维护和扩展。用户界面友好，操作流程清晰，能够有效支持商户管理的各项业务需求。
