# 抽卡列表

<cite>
**本文档中引用的文件**  
- [list.vue](file://src/views/card-walmart-info/account/list.vue)
- [index.vue](file://src/views/card-jd-info/account/index.vue)
- [index.vue](file://src/views/card-jd-info/order/index.vue)
- [list.vue](file://src/views/merchant/steal-card/list.vue)
- [add-modal.vue](file://src/views/merchant/steal-card/components/add-modal.vue)
- [apple-card-steal-settings.ts](file://src/api/apple-card-steal-settings.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-list-res.ts](file://src/api/generated/models/kami-api-merchant-v1-steal-list-res.ts)
- [kami-api-merchant-v1-merchant-hidden-config-entity.ts](file://src/api/generated/models/kami-api-merchant-v1-merchant-hidden-config-entity.ts)
</cite>

## 目录

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

## 介绍

本文档详细介绍了抽卡列表功能的实现，包括抽卡规则列表的展示方式、数据加载机制和分页处理逻辑。文档还详细说明了列表组件的交互功能，如搜索、筛选、排序和状态管理。此外，提供了抽卡规则创建、编辑和删除操作的完整指南，包括表单验证和错误处理。文档包含实际代码示例，展示如何通过API获取抽卡规则列表和执行CRUD操作。还解释了列表性能优化策略，如虚拟滚动或懒加载技术的应用。最后，文档说明了权限控制机制，确保用户只能操作其授权范围内的抽卡规则，并提供了常见问题的解决方案。

## 项目结构

项目结构清晰地组织了前端代码，主要分为以下几个部分：

- `config`：配置文件，包括插件和工具的配置。
- `deploy`：部署相关文件，如Docker配置。
- `src`：源代码目录，包含API、资产、组件、指令、钩子、布局、模拟数据、插件、路由器、存储、类型、工具和视图。
- `views`：视图组件，按功能模块组织，如`card-jd-info`、`card-walmart-info`和`merchant`。

```mermaid
graph TB
subgraph "配置"
config[config]
end
subgraph "部署"
deploy[deploy]
end
subgraph "源代码"
src[src]
subgraph "API"
api[api]
end
subgraph "资产"
assets[assets]
end
subgraph "组件"
components[components]
end
subgraph "指令"
directive[directive]
end
subgraph "钩子"
hooks[hooks]
end
subgraph "布局"
layout[layout]
end
subgraph "模拟数据"
mock[mock]
end
subgraph "插件"
plugins[plugins]
end
subgraph "路由器"
router[router]
end
subgraph "存储"
store[store]
end
subgraph "类型"
types[types]
end
subgraph "工具"
utils[utils]
end
subgraph "视图"
views[views]
end
end
config --> src
deploy --> src
src --> api
src --> assets
src --> components
src --> directive
src --> hooks
src --> layout
src --> mock
src --> plugins
src --> router
src --> store
src --> types
src --> utils
src --> views
```

**图源**

- [list.vue](file://src/views/card-walmart-info/account/list.vue)
- [index.vue](file://src/views/card-jd-info/account/index.vue)

## 核心组件

抽卡列表功能的核心组件包括：

- `list.vue`：负责展示抽卡规则列表，支持分页、搜索和筛选。
- `index.vue`：包含抽卡规则的创建、编辑和删除功能。
- `add-modal.vue`：用于创建和编辑抽卡规则的模态框。

**节源**

- [list.vue](file://src/views/merchant/steal-card/list.vue)
- [index.vue](file://src/views/card-jd-info/account/index.vue)
- [add-modal.vue](file://src/views/merchant/steal-card/components/add-modal.vue)

## 架构概述

抽卡列表功能的架构主要包括以下几个部分：

- **数据加载**：通过API从后端获取抽卡规则列表。
- **分页处理**：支持分页显示，用户可以切换页面和调整每页显示的条目数。
- **搜索和筛选**：用户可以通过输入关键词进行搜索，也可以通过下拉菜单进行筛选。
- **状态管理**：使用Vue的响应式系统管理组件状态，如加载状态、分页信息等。
- **表单验证**：在创建和编辑抽卡规则时，对表单数据进行验证，确保数据的正确性。

```mermaid
graph TB
subgraph "前端"
UI[用户界面]
API[API客户端]
State[状态管理]
end
subgraph "后端"
Server[服务器]
DB[(数据库)]
end
UI --> API
API --> Server
Server --> DB
DB --> Server
Server --> API
API --> UI
UI --> State
State --> UI
```

**图源**

- [apple-card-steal-settings.ts](file://src/api/apple-card-steal-settings.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-list-res.ts](file://src/api/generated/models/kami-api-merchant-v1-steal-list-res.ts)

## 详细组件分析

### 抽卡规则列表组件

抽卡规则列表组件负责展示抽卡规则的详细信息，支持分页、搜索和筛选功能。

#### 数据加载

组件通过API从后端获取抽卡规则列表。请求参数包括当前页码和每页显示的条目数。

```typescript
const fetchData = async (
  params: AppleCardStealListParams = { current: 1, pageSize: 50 }
) => {
  setLoading(true);
  try {
    const {
      data: { list, total }
    } = await apiClient.apiMerchantConfigStealRuleListGet({
      current: params.current,
      pageSize: params.pageSize as ApiMerchantConfigStealRuleListGetPageSizeEnum
    });
    renderData.value = list;
    pagination.current = params.current;
    pagination.pageSize = params.pageSize;
    pagination.total = total;
  } catch (err) {
    // 处理错误
  } finally {
    setLoading(false);
  }
};
```

#### 分页处理

组件支持分页显示，用户可以切换页面和调整每页显示的条目数。分页信息通过`pagination`对象管理。

```typescript
const onPageChange = (current: number) => {
  fetchData({ ...pagination, current });
};

const onPageSizeChange = (pageSize: number) => {
  fetchData({ ...pagination, pageSize });
};
```

#### 搜索和筛选

用户可以通过输入关键词进行搜索，也可以通过下拉菜单进行筛选。搜索和筛选功能通过`formModel`对象管理。

```typescript
const search = () => {
  fetchData({
    ...basePagination,
    ...formModel.value
  } as unknown as AppleCardStealListParams);
};
```

#### 状态管理

组件使用Vue的响应式系统管理状态，如加载状态、分页信息等。

```typescript
const { loading, setLoading } = useLoading(true);
const renderData = ref<KamiApiMerchantV1MerchantHiddenConfigEntity[]>([]);
const formModel = ref(generateFormModel());
const state = reactive<{
  addModalVisible: boolean;
  deployModalVisible: boolean;
  accountDetailVisible: boolean;
  targetRule: Required<KamiApiMerchantV1MerchantHiddenConfigEntity> | null;
  switchValue: boolean;
  roadInfos: KamiApiRoadV1RoadSimpleInfo[];
  merchantInfos: KamiInternalModelEntityV1MerchantInfo[];
}>({
  addModalVisible: false,
  deployModalVisible: false,
  accountDetailVisible: false,
  targetRule: null,
  switchValue: false,
  roadInfos: [],
  merchantInfos: []
});
```

**图源**

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

### 抽卡规则创建和编辑组件

抽卡规则创建和编辑组件通过模态框实现，用户可以在模态框中输入抽卡规则的详细信息。

#### 表单验证

在创建和编辑抽卡规则时，对表单数据进行验证，确保数据的正确性。

```typescript
const handleOk = (done: (closed: boolean) => void) => {
  formDataRef.value.validate().then(async res => {
    if (res) return done(false);
    // 面额不能大于金额
    if (formData.value.faceAmount > formData.value.amount) {
      Message.error({
        content: '面额不能大于金额'
      });
      return done(false);
    }
    try {
      setLoading(true);
      if (isNull(props.rule) || isUndefined(props.rule)) {
        await apiClient.apiMerchantConfigStealRuleCreatePost({
          kamiApiMerchantV1StealCreateReq: formData.value
        });
      } else {
        await apiClient.apiMerchantConfigStealRuleUpdatePost({
          kamiApiMerchantV1StealUpdateReq: {
            id: props.rule.id,
            ...formData.value
          }
        });
      }
      done(true);
      visible.value = false;
      formData.value = generateFormData();
    } catch (error) {
      done(false);
    } finally {
      setLoading(false);
    }
  });
};
```

**图源**

- [add-modal.vue](file://src/views/merchant/steal-card/components/add-modal.vue)

## 依赖分析

抽卡列表功能依赖于以下几个主要模块：

- **API客户端**：用于与后端API进行通信。
- **Vue**：用于构建用户界面和管理组件状态。
- **Arco Design**：用于UI组件库，提供丰富的UI组件。
- **Axios**：用于HTTP请求，与后端API进行数据交互。

```mermaid
graph TB
subgraph "前端"
UI[用户界面]
API[API客户端]
State[状态管理]
Axios[Axios]
Vue[Vue]
ArcoDesign[Arco Design]
end
subgraph "后端"
Server[服务器]
DB[(数据库)]
end
UI --> API
API --> Axios
Axios --> Server
Server --> DB
DB --> Server
Server --> Axios
Axios --> API
API --> UI
UI --> State
State --> UI
UI --> Vue
UI --> ArcoDesign
```

**图源**

- [apple-card-steal-settings.ts](file://src/api/apple-card-steal-settings.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-list-res.ts](file://src/api/generated/models/kami-api-merchant-v1-steal-list-res.ts)

## 性能考虑

为了提高抽卡列表的性能，采取了以下措施：

- **分页加载**：通过分页加载数据，减少一次性加载大量数据的开销。
- **懒加载**：对于长列表，采用懒加载技术，只加载当前可见区域的数据。
- **虚拟滚动**：使用虚拟滚动技术，只渲染当前可见的列表项，减少DOM节点的数量。

## 故障排除指南

### 数据加载失败

如果数据加载失败，可以检查以下几点：

- 确认网络连接是否正常。
- 检查API端点是否正确。
- 查看浏览器控制台是否有错误信息。

### 操作无响应

如果操作无响应，可以检查以下几点：

- 确认组件状态是否正确。
- 检查是否有未处理的异常。
- 查看浏览器控制台是否有错误信息。

## 结论

本文档详细介绍了抽卡列表功能的实现，包括数据加载、分页处理、搜索和筛选、状态管理、表单验证和错误处理。通过这些功能，用户可以方便地管理和操作抽卡规则。文档还提供了性能优化策略和故障排除指南，帮助开发者更好地维护和优化抽卡列表功能。
