# 项目概述

<cite>
**本文档引用的文件**
- [main.ts](file://src/main.ts)
- [package.json](file://package.json)
- [interceptor.ts](file://src/api/interceptor.ts)
- [index.ts](file://src/api/index.ts)
- [configuration.ts](file://src/api/generated/configuration.ts)
- [apple-card-info.ts](file://src/api/apple-card-info.ts)
- [card-walmart-account.ts](file://src/api/card-walmart-account.ts)
- [merchant-list.ts](file://src/api/merchant-list.ts)
- [t-mall-game-account.ts](file://src/api/t-mall-game-account.ts)
- [store/index.ts](file://src/store/index.ts)
- [router/index.ts](file://src/router/index.ts)
- [tanstack-query.ts](file://src/plugins/tanstack-query.ts)
</cite>

## 目录

1. [简介](#简介)
2. [项目结构](#项目结构)
3. [技术栈](#技术栈)
4. [核心架构模式](#核心架构模式)
5. [项目初始化流程](#项目初始化流程)
6. [主要功能模块](#主要功能模块)
7. [API 与数据交互](#api-与数据交互)
8. [状态管理](#状态管理)
9. [路由与导航](#路由与导航)
10. [构建与部署](#构建与部署)

## 简介

kami_frontend 是一个基于 Vue 3 和 Arco Design 构建的现代化管理平台前端项目，旨在为多平台卡券信息管理、商户配置和订单处理提供统一的可视化操作界面。该项目通过集成多种第三方平台（如 Apple Card、京东、沃尔玛、携程、天猫游戏等）的 API 接口，实现对卡券账户、充值记录、订单状态等核心业务数据的集中管理。系统支持商户级别的权限控制、用户角色管理以及敏感操作的安全验证机制，确保数据操作的安全性与可追溯性。整体架构采用模块化设计，结合现代前端技术栈，具备良好的可维护性和扩展性。

## 项目结构

项目遵循典型的 Vue 3 单页应用（SPA）目录结构，按功能模块进行清晰划分。

```mermaid
graph TD
A[src] --> B[api]
A --> C[assets]
A --> D[components]
A --> E[directive]
A --> F[hooks]
A --> G[layout]
A --> H[mock]
A --> I[plugins]
A --> J[router]
A --> K[store]
A --> L[types]
A --> M[utils]
A --> N[views]
A --> O[App.vue]
A --> P[main.ts]
B --> Q[generated]
B --> R[interceptor.ts]
J --> S[guard]
J --> T[routes]
K --> U[modules]
```

**Diagram sources**

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

**Section sources**

- [src](file://src)

## 技术栈

本项目采用了一系列先进的前端技术，构建了一个高性能、可维护的现代化 Web 应用。

- **核心框架**: Vue 3 (Composition API) 提供响应式数据绑定和组件化开发能力。
- **UI 组件库**: Arco Design Vue 提供了一套完整、美观且可定制的企业级 UI 组件。
- **状态管理**: Pinia 作为官方推荐的状态管理库，替代 Vuex，提供更简洁的 API 和更好的 TypeScript 支持。
- **路由管理**: Vue Router 4 实现客户端路由导航和页面跳转。
- **HTTP 客户端**: Axios 用于发起网络请求，并通过拦截器统一处理请求和响应。
- **异步状态管理**: @tanstack/vue-query 用于管理服务器状态，简化数据获取、缓存和同步逻辑。
- **构建工具**: Vite 提供了极速的开发服务器启动和热更新体验。
- **类型系统**: TypeScript 提供了强大的静态类型检查，提升代码质量和开发效率。
- **代码规范**: ESLint、Stylelint 和 Prettier 确保代码风格统一和质量。
- **版本控制**: Husky 和 lint-staged 在提交代码时自动执行代码检查和格式化。

**Section sources**

- [package.json](file://package.json)

## 核心架构模式

项目采用了多种设计模式和架构原则，以确保代码的可读性、可测试性和可扩展性。

### 模块化设计

项目通过将功能拆分为独立的模块来组织代码。例如，`src/api` 目录下的每个文件（如 `apple-card-info.ts`）都封装了特定业务领域的 API 调用，实现了关注点分离。`src/views` 目录下的每个子目录代表一个独立的功能页面。

### 依赖注入

在 `main.ts` 入口中，通过 `app.use()` 方法将 Pinia store、Vue Router、自定义插件（如 `tanstack-query`）等核心依赖注入到 Vue 应用实例中，使得这些服务可以在整个应用的任何组件中被访问。

### 拦截器模式

`src/api/interceptor.ts` 文件中使用了 Axios 的请求和响应拦截器。请求拦截器负责在每次请求前自动添加认证令牌（Authorization header），而响应拦截器则统一处理错误码（如 5001, 5002, 5003 表示登录过期）、刷新令牌以及二进制文件的下载，极大地简化了业务组件中的网络逻辑。

```mermaid
sequenceDiagram
participant Component as "业务组件"
participant Axios as "Axios"
participant Interceptor as "拦截器"
participant Server as "后端服务器"
Component->>Axios : 发起请求
Axios->>Interceptor : 请求拦截
Interceptor->>Interceptor : 添加 Authorization Header
Interceptor->>Server : 发送请求
Server-->>Interceptor : 返回响应
Interceptor->>Interceptor : 检查响应码和刷新令牌
Interceptor->>Component : 返回处理后的数据或抛出错误
```

**Diagram sources**

- [interceptor.ts](file://src/api/interceptor.ts)
- [main.ts](file://src/main.ts)

**Section sources**

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

## 项目初始化流程

项目的启动流程从 `src/main.ts` 文件开始，这是整个应用的入口点。

1.  **创建应用实例**: 使用 `createApp(App)` 创建 Vue 应用实例。
2.  **注册全局组件和插件**: 注册 Arco Design 组件库、自定义全局组件（`globalComponents`）和指令（`directive`）。
3.  **配置第三方库**: 调用 `setupTanstackQuery(app)` 来初始化 @tanstack/vue-query。
4.  **安装核心模块**: 依次使用 Pinia store、Vue Router、全局组件和指令。
5.  **挂载应用**: 最后，调用 `app.mount('#app')` 将应用挂载到 DOM 中的 `#app` 元素上。

此流程确保了所有必要的依赖和服务在应用启动时就被正确配置和初始化。

**Section sources**

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

## 主要功能模块

项目围绕多个核心业务领域构建了功能模块。

### 卡券信息管理

- **Apple Card**: 支持苹果账号的增删改查、批量导入、余额查询、充值历史和状态管理。
- **京东 (JD)**: 管理京东账号的 Cookie、订单、钱包信息和商户配置。
- **沃尔玛 (Walmart)**: 提供沃尔玛账号的分组管理、订单处理、状态检测和数据导出功能。
- **携程 (Ctrip)**: 处理携程账号的授权、订单回调和钱包同步。
- **天猫游戏 (TMall Game)**: 管理天猫游戏账号的授权、订单提交、店铺订单和数据同步。

### 商户管理系统

位于 `src/views/merchant` 目录下，提供对商户的全生命周期管理：

- **商户配置**: 添加、编辑、删除商户信息，配置登录凭证、白名单 IP 和支付通道。
- **商户部署**: 管理商户的部署记录和状态。
- **商户盗卡设置**: 配置商户的盗卡规则和状态。

### 用户权限系统

通过 `src/directive/permission/index.ts` 中的自定义指令和 `src/router/guard/permission.ts` 中的路由守卫，实现了基于角色的访问控制（RBAC）。只有拥有相应权限的用户才能访问特定的页面或执行特定的操作。

**Section sources**

- [apple-card-info.ts](file://src/api/apple-card-info.ts)
- [card-walmart-account.ts](file://src/api/card-walmart-account.ts)
- [merchant-list.ts](file://src/api/merchant-list.ts)
- [t-mall-game-account.ts](file://src/api/t-mall-game-account.ts)

## API 与数据交互

项目采用 OpenAPI Generator 自动生成 API 客户端代码，确保前后端接口的一致性。

- **代码生成**: `package.json` 中的 `generate:api` 脚本会根据后端提供的 `api.json` 文件，自动生成位于 `src/api/generated` 目录下的 TypeScript 接口和 API 客户端。
- **API 封装**: 在 `src/api` 目录下，开发者基于生成的客户端，创建更高层次的业务 API 函数。例如，`apple-card-info.ts` 文件中的 `queryAppleCardList` 函数封装了获取苹果卡列表的逻辑。
- **统一客户端**: `src/api/index.ts` 文件导出了 `apiClient` 和 `apiCkClient` 两个单例，它们基于生成的 `DefaultApi` 和 `CkApi`，并使用统一的 `Configuration` 进行配置。

```mermaid
classDiagram
class DefaultApi {
+getList(request : GetListRequest) : Promise~GetListResponse~
+create(request : CreateRequest) : Promise~CreateResponse~
+update(request : UpdateRequest) : Promise~UpdateResponse~
+delete(request : DeleteRequest) : Promise~DeleteResponse~
}
class Configuration {
+basePath : string
+accessToken : string | Promise~string~
+apiKey : string | Promise~string~
}
class apiClient {
<<singleton>>
}
apiClient --> DefaultApi : "使用"
DefaultApi --> Configuration : "依赖"
```

**Diagram sources**

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

**Section sources**

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

## 状态管理

项目使用 Pinia 进行全局状态管理。

- **Store 创建**: `src/store/index.ts` 文件创建了 Pinia 实例，并导出了 `useAppStore`、`useUserStore` 和 `useTabBarStore` 三个模块化的 store。
- **模块化**: 状态被组织在 `src/store/modules` 目录下的不同模块中，如 `user` 模块管理用户登录信息和权限，`app` 模块管理应用级别的配置。
- **集成**: 在 `main.ts` 中，通过 `app.use(store)` 将 Pinia 集成到 Vue 应用中，使得所有组件都可以通过 `useUserStore()` 等函数访问状态。

**Section sources**

- [store/index.ts](file://src/store/index.ts)

## 路由与导航

Vue Router 负责管理应用的路由。

- **路由定义**: 路由配置分散在 `src/router/routes/modules` 目录下的多个文件中，每个文件对应一个功能模块的路由。
- **路由守卫**: `src/router/guard/index.ts` 文件应用了全局前置守卫，用于处理登录验证、页面标题更新和进度条（NProgress）的显示。
- **动态路由**: 系统支持根据用户权限动态加载路由，确保用户只能访问其被授权的页面。

**Section sources**

- [router/index.ts](file://src/router/index.ts)

## 构建与部署

项目提供了完整的构建和部署方案。

- **开发命令**: `pnpm dev` 使用 Vite 启动开发服务器。
- **构建命令**: `pnpm build` 使用 Vite 打包生产环境代码，输出到 `dist` 目录。
- **部署配置**: `deploy` 目录下包含了 Dockerfile 和 docker-compose 文件，支持容器化部署。Nginx 配置文件 `default.conf` 提供了反向代理和静态资源服务的配置示例。

**Section sources**

- [package.json](file://package.json)
- [Dockerfile](file://deploy/Dockerfile)
- [default.conf](file://deploy/nginx/default.conf)
