# 抽卡管理

<cite>
**本文档引用文件**  
- [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)
- [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)
- [add-modal.vue](file://src/views/merchant/steal-setting/components/add-modal.vue)
- [kami-internal-model-entity-v1-card-apple-hidden-settings.ts](file://src/api/generated/models/kami-internal-model-entity-v1-card-apple-hidden-settings.ts)
- [kami-api-card-info-apple-v1-recharge-steal-rule-add-req.ts](file://src/api/generated/models/kami-api-card-info-apple-v1-recharge-steal-rule-add-req.ts)
- [kami-api-card-info-apple-v1-recharge-steal-rule-update-req.ts](file://src/api/generated/models/kami-api-card-info-apple-v1-recharge-steal-rule-update-req.ts)
- [kami-api-card-info-apple-v1-recharge-steal-rule-delete-req.ts](file://src/api/generated/models/kami-api-card-info-apple-v1-recharge-steal-rule-delete-req.ts)
- [kami-api-card-info-apple-v1-recharge-steal-rule-list-req.ts](file://src/api/generated/models/kami-api-card-info-apple-v1-recharge-steal-rule-list-req.ts)
</cite>

## 目录

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

## 简介

本文档详细介绍了 kami_frontend 项目中的抽卡管理功能，涵盖抽卡规则管理、抽卡记录查询、抽卡统计分析等核心功能的实现机制。文档深入解析了前端界面的数据展示方式与交互逻辑，包括抽卡列表、记录查询、统计图表等组件的设计与实现。同时提供了抽卡规则创建、编辑、删除的操作指南，解释了抽卡数据的统计方法和可视化呈现方式。文档还包含实际 API 调用示例，说明了安全控制机制和性能优化策略，并为常见问题提供了解决方案。

## 项目结构

抽卡管理功能主要位于 `src/views/merchant` 目录下，分为 `steal-setting` 和 `steal-card` 两个主要模块。`steal-setting` 模块负责抽卡规则的增删改查，`steal-card` 模块则提供规则列表、匹配记录和统计分析的综合视图。API 接口定义位于 `src/api` 目录下的 `apple-card-steal-settings.ts` 文件中，而相关的数据模型则在 `src/api/generated/models` 目录下自动生成。

```mermaid
graph TD
subgraph "视图层 Views"
A[steal-setting/index.vue] --> B[规则管理主界面]
C[steal-card/index.vue] --> D[抽卡管理主入口]
E[steal-card/list.vue] --> F[规则列表]
G[steal-card/record.vue] --> H[匹配记录]
I[steal-card/stats.vue] --> J[统计分析]
K[steal-setting/components/add-modal.vue] --> L[规则编辑弹窗]
end
subgraph "API层"
M[apple-card-steal-settings.ts] --> N[抽卡规则API]
end
subgraph "模型层"
O[kami-internal-model-entity-v1-card-apple-hidden-settings.ts] --> P[抽卡规则数据模型]
end
B --> M
D --> M
F --> M
H --> M
J --> M
L --> M
M --> O
```

**图示来源**

- [steal-setting/index.vue](file://src/views/merchant/steal-setting/index.vue)
- [steal-card/index.vue](file://src/views/merchant/steal-card/index.vue)
- [apple-card-steal-settings.ts](file://src/api/apple-card-steal-settings.ts)
- [kami-internal-model-entity-v1-card-apple-hidden-settings.ts](file://src/api/generated/models/kami-internal-model-entity-v1-card-apple-hidden-settings.ts)

**章节来源**

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

## 核心组件

抽卡管理的核心功能由 `apple-card-steal-settings.ts` 中定义的 API 函数和 `steal-setting/index.vue`、`steal-card` 系列组件共同实现。核心数据模型 `KamiInternalModelEntityV1CardAppleHiddenSettings` 定义了抽卡规则的所有属性，包括规则名称、状态、目标用户ID、存储用户ID、金额、目标金额、偷卡总额和时间间隔等。前端通过调用 `getAppleCardStealList`、`addAppleCardStealRule`、`editAppleCardStealRule` 和 `deleteAppleCardStealRule` 等函数与后端进行交互，实现了完整的CRUD操作。

**章节来源**

- [apple-card-steal-settings.ts](file://src/api/apple-card-steal-settings.ts#L22-L71)
- [kami-internal-model-entity-v1-card-apple-hidden-settings.ts](file://src/api/generated/models/kami-internal-model-entity-v1-card-apple-hidden-settings.ts#L19-L92)

## 架构概述

抽卡管理功能采用典型的前后端分离架构。前端使用 Vue 3 和 Arco Design 组件库构建用户界面，通过 Axios 发起 HTTP 请求调用后端 API。后端提供 RESTful API 接口，处理前端的请求并返回 JSON 格式的数据。前端组件通过组合式 API（Composition API）组织逻辑，使用 Pinia 进行状态管理，并通过自定义 Hook（如 `useLoading`）复用通用逻辑。

```mermaid
sequenceDiagram
participant 用户 as "用户"
participant 前端 as "前端 (Vue)"
participant API as "API Client"
participant 后端 as "后端服务"
用户->>前端 : 点击“添加规则”
前端->>前端 : 打开 add-modal.vue
用户->>前端 : 填写表单并提交
前端->>API : 调用 addAppleCardStealRule(data)
API->>后端 : POST /api/cardInfo/appleCard/steal/addRule
后端-->>API : 返回结果
API-->>前端 : 返回成功/失败
前端->>前端 : 刷新列表，关闭弹窗
前端-->>用户 : 显示操作结果
```

**图示来源**

- [add-modal.vue](file://src/views/merchant/steal-setting/components/add-modal.vue#L1-L190)
- [apple-card-steal-settings.ts](file://src/api/apple-card-steal-settings.ts#L65-L71)

## 详细组件分析

### 抽卡规则管理分析

`steal-setting/index.vue` 组件是抽卡规则管理的核心界面，提供了规则的列表展示、添加、编辑和删除功能。该组件使用 `a-table` 组件展示规则列表，并通过 `a-switch` 控件全局开启或关闭抽卡功能。

#### 对象导向组件

```mermaid
classDiagram
class AppleCardStealAdd {
+string name
+string targetUserId
+string storageUserId
+number amount
+number targetAmount
+number intervalTime
+number status
}
class AppleCardStealEdit {
+number id
}
class AppleCardStealList {
+number stealTotalAmount
+string createdAt
+string updatedAt
}
class KamiInternalModelEntityV1CardAppleHiddenSettings {
+number id
+string name
+number status
+string targetUserId
+string storageUserId
+number amount
+number targetAmount
+number stealTotalAmount
+number intervalTime
+string createdAt
+string updatedAt
}
AppleCardStealEdit --> AppleCardStealAdd : "extends"
AppleCardStealList --> AppleCardStealEdit : "extends"
KamiInternalModelEntityV1CardAppleHiddenSettings --> AppleCardStealList : "implements"
```

**图示来源**

- [apple-card-steal-settings.ts](file://src/api/apple-card-steal-settings.ts#L22-L40)
- [kami-internal-model-entity-v1-card-apple-hidden-settings.ts](file://src/api/generated/models/kami-internal-model-entity-v1-card-apple-hidden-settings.ts#L19-L92)

#### API/服务组件

```mermaid
sequenceDiagram
participant 前端 as "前端"
participant API as "API Client"
participant 后端 as "后端"
前端->>API : getAppleCardStealList(params)
API->>后端 : GET /api/cardInfo/appleCard/steal/getRuleList?current=1&pageSize=50
后端-->>API : 返回 { total : 10, list : [...] }
API-->>前端 : 返回分页数据
前端->>前端 : 渲染表格
```

**图示来源**

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

### 抽卡综合管理分析

`steal-card/index.vue` 组件提供了一个更全面的抽卡管理视图，通过标签页（Tab）的形式集成了规则列表、匹配记录和统计分析三个功能模块。

#### 复杂逻辑组件

```mermaid
flowchart TD
Start([组件初始化]) --> FetchList["获取规则列表"]
FetchList --> FetchSetting["获取全局开关状态"]
FetchSetting --> RenderUI["渲染UI界面"]
RenderUI --> UserAction["用户操作"]
UserAction --> |点击标签页| SwitchTab["切换模块：list/record/stats"]
UserAction --> |点击添加| ShowModal["显示添加弹窗"]
UserAction --> |切换全局开关| ToggleGlobal["调用setAppleCardStealSetting"]
SwitchTab --> RenderUI
ShowModal --> HandleSubmit["处理表单提交"]
HandleSubmit --> CallAPI["调用addAppleCardStealRule"]
CallAPI --> Refresh["刷新列表"]
Refresh --> RenderUI
ToggleGlobal --> UpdateState["更新本地状态"]
UpdateState --> RenderUI
```

**图示来源**

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

**章节来源**

- [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)

### 抽卡记录与统计分析

`steal-card/record.vue` 和 `steal-card/stats.vue` 组件分别负责展示抽卡的匹配记录和统计分析数据。`record.vue` 使用 `a-table` 展示每次抽卡操作的详细信息，包括替换订单、原始订单、偷卡金额和状态等。`stats.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)

## 依赖分析

抽卡管理功能依赖于多个核心模块和外部库。前端框架依赖 Vue 3 和 Vue Router 进行页面路由和组件化开发，UI 组件库依赖 Arco Design 提供丰富的界面组件。状态管理依赖 Pinia，HTTP 请求依赖 Axios。此外，还依赖 `query-string` 库进行 URL 参数序列化，以及 `echarts` 和 `vue-echarts` 进行数据可视化。

```mermaid
graph TD
A[抽卡管理] --> B[Vue 3]
A --> C[Vue Router]
A --> D[Pinia]
A --> E[Axios]
A --> F[Arco Design]
A --> G[query-string]
A --> H[echarts]
A --> I[vue-echarts]
B --> J[JavaScript/TypeScript]
C --> J
D --> J
E --> J
F --> J
G --> J
H --> J
I --> J
```

**图示来源**

- [package.json](file://package.json)
- [src/main.ts](file://src/main.ts)

**章节来源**

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

## 性能考虑

为了优化性能，抽卡管理功能在多个层面进行了优化。在数据获取方面，采用了分页加载机制，避免一次性加载大量数据导致页面卡顿。在组件设计上，使用了 `v-if` 按需渲染不同的功能模块（规则列表、记录、统计），减少了不必要的 DOM 渲染。在状态管理上，通过 `reactive` 和 `ref` 精确控制响应式数据，避免了过度的依赖追踪。此外，`useLoading` Hook 的使用也提供了良好的用户反馈，提升了用户体验。

## 故障排除指南

当抽卡管理功能出现问题时，可以按照以下步骤进行排查：

1.  **检查网络请求**：打开浏览器开发者工具的 Network 面板，检查 `getRuleList`、`addRule` 等 API 请求是否成功。如果请求失败，请检查后端服务是否正常运行，以及网络连接是否正常。
2.  **检查表单验证**：在添加或编辑规则时，确保所有必填字段都已填写，且“面额”不能大于“金额”。前端有相应的验证逻辑，如果验证失败，会弹出错误提示。
3.  **检查用户权限**：确认当前登录用户是否有操作抽卡规则的权限。权限不足可能导致操作被拒绝。
4.  **检查数据模型**：如果列表数据为空或显示异常，请检查后端返回的 JSON 数据结构是否与前端定义的 `KamiInternalModelEntityV1CardAppleHiddenSettings` 模型一致。
5.  **检查依赖项**：确保所有必要的依赖项（如 Axios、Arco Design）都已正确安装和导入。

**章节来源**

- [add-modal.vue](file://src/views/merchant/steal-setting/components/add-modal.vue#L130-L150)
- [steal-setting/index.vue](file://src/views/merchant/steal-setting/index.vue#L150-L180)

## 结论

kami_frontend 项目的抽卡管理功能设计合理，实现了完整的规则管理、记录查询和统计分析能力。通过清晰的组件划分和模块化设计，代码具有良好的可维护性和可扩展性。前端与后端通过定义良好的 API 接口进行通信，确保了系统的稳定性和可靠性。未来可以考虑增加更丰富的统计图表（如折线图、柱状图）来提升数据可视化效果，并进一步优化大规模数据下的加载性能。
