# 技术栈与依赖

<cite>
**本文档引用的文件**  
- [package.json](file://package.json)
- [tsconfig.json](file://tsconfig.json)
- [eslint.config.js](file://eslint.config.js)
- [stylelint.config.js](file://stylelint.config.js)
- [commitlint.config.js](file://commitlint.config.js)
- [src/plugins/tanstack-query.ts](file://src/plugins/tanstack-query.ts)
- [src/router/index.ts](file://src/router/index.ts)
- [src/store/index.ts](file://src/store/index.ts)
- [src/main.ts](file://src/main.ts)
- [config/plugin/arcoResolver.ts](file://config/plugin/arcoResolver.ts)
- [config/plugin/arcoStyleImport.ts](file://config/plugin/arcoStyleImport.ts)
- [vite.config.ts](file://vite.config.ts)
</cite>

## 目录

1. [技术选型概述](#技术选型概述)
2. [核心框架与库](#核心框架与库)
3. [TypeScript 配置](#typescript-配置)
4. [Vite 构建配置](#vite-构建配置)
5. [开发与生产依赖](#开发与生产依赖)
6. [代码质量工具](#代码质量工具)
7. [依赖管理最佳实践](#依赖管理最佳实践)
8. [性能优化建议](#性能优化建议)
9. [常见问题与解决方案](#常见问题与解决方案)

## 技术选型概述

kami_frontend 项目采用现代化的前端技术栈，基于 Vue 3 的 Composition API 构建，结合 Pinia 进行状态管理，使用 Vue Router 实现路由控制，并采用 Arco Design 作为 UI 框架。项目通过 Vite 作为构建工具，利用其快速的开发服务器和高效的打包能力。HTTP 请求通过 Axios 进行管理，数据查询则采用 @tanstack/vue-query 库实现缓存、重试和状态同步。整个项目使用 TypeScript 提供类型安全，并通过 ESLint、Stylelint 和 Commitlint 确保代码质量和提交规范。

**Section sources**

- [src/main.ts](file://src/main.ts#L1-L50)
- [package.json](file://package.json#L1-L100)

## 核心框架与库

### Vue 3 与 Composition API

项目基于 Vue 3 构建，充分利用 Composition API 提供的逻辑复用、更好的类型推断和更灵活的代码组织能力。通过 `setup` 函数和 `ref`、`reactive`、`computed` 等响应式 API，实现组件逻辑的高效组织。

### Pinia 状态管理

Pinia 作为 Vue 官方推荐的状态管理库，替代了 Vuex。项目在 `src/store` 目录下组织模块化 store，包括 app、tab-bar 和 user 等模块，通过定义 actions、getters 和 state 实现全局状态的集中管理。

```mermaid
classDiagram
class Store {
+state : Object
+getters : Object
+actions : Object
}
class UserStore {
+userInfo : Object
+token : string
+login(credentials)
+logout()
+getUserInfo()
}
class AppStore {
+sidebarCollapsed : boolean
+toggleSidebar()
+setTheme(theme)
}
class TabBarStore {
+tabs : Array
+addTab(tab)
+removeTab(tabId)
+clearTabs()
}
Store <|-- UserStore
Store <|-- AppStore
Store <|-- TabBarStore
```

**Diagram sources**

- [src/store/index.ts](file://src/store/index.ts#L1-L20)
- [src/store/modules/user/index.ts](file://src/store/modules/user/index.ts#L5-L40)

### Vue Router 路由系统

Vue Router 4 用于管理应用的路由。项目在 `src/router` 目录下定义路由配置，包括基础路由、路由守卫和菜单映射。通过路由守卫实现权限控制和用户登录状态检查。

```mermaid
flowchart TD
A[路由导航] --> B{是否已登录?}
B --> |否| C[重定向到登录页]
B --> |是| D{是否有权限?}
D --> |否| E[显示无权限页面]
D --> |是| F[加载目标页面]
F --> G[更新Tab标签]
G --> H[完成导航]
```

**Diagram sources**

- [src/router/index.ts](file://src/router/index.ts#L1-L100)
- [src/router/guard/permission.ts](file://src/router/guard/permission.ts#L1-L50)

### Arco Design UI 框架

Arco Design 作为企业级 UI 框架，提供了一套完整的设计系统和组件库。项目通过 `arcoResolver` 和 `arcoStyleImport` 插件实现按需加载和样式自动导入，有效减少打包体积。

**Section sources**

- [config/plugin/arcoResolver.ts](file://config/plugin/arcoResolver.ts#L1-L30)
- [config/plugin/arcoStyleImport.ts](file://config/plugin/arcoStyleImport.ts#L1-L25)

### Axios HTTP 客户端

Axios 用于处理所有 HTTP 请求。项目在 `src/api` 目录下组织 API 调用，通过拦截器实现请求和响应的统一处理，包括添加认证头、错误处理和加载状态管理。

### @tanstack/vue-query 查询库

@tanstack/vue-query 用于管理服务端状态，提供数据获取、缓存、同步和更新的完整解决方案。项目通过插件方式集成，在 `src/plugins/tanstack-query.ts` 中配置查询客户端。

```mermaid
sequenceDiagram
participant Component as "组件"
participant Query as "@tanstack/vue-query"
participant API as "API服务"
Component->>Query : useQuery(key, fetchFn)
Query->>Query : 检查缓存
Query->>API : 发起请求
API-->>Query : 返回数据
Query->>Query : 缓存数据
Query-->>Component : 提供数据和状态
Component->>Component : 渲染UI
```

**Diagram sources**

- [src/plugins/tanstack-query.ts](file://src/plugins/tanstack-query.ts#L1-L40)
- [src/api/interceptor.ts](file://src/api/interceptor.ts#L1-L30)

## TypeScript 配置

项目通过 `tsconfig.json` 文件配置 TypeScript 编译选项，启用严格类型检查，确保代码质量和类型安全。

```json
{
  "compilerOptions": {
    "target": "ES2020",
    "useDefineForClassFields": true,
    "module": "ESNext",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "skipLibCheck": true,
    "allowJs": false,
    "strict": true,
    "forceConsistentCasingInFileNames": true,
    "noFallthroughCasesInSwitch": true,
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,
    "jsx": "preserve",
    "incremental": true,
    "plugins": [
      {
        "name": "typescript-plugin-css-modules"
      }
    ],
    "paths": {
      "@/*": ["src/*"]
    }
  },
  "include": ["src", "types", "env.d.ts"],
  "references": [{ "path": "./tsconfig.node.json" }]
}
```

配置中启用了严格模式，包括 `strictNullChecks`、`strictFunctionTypes` 等，确保类型安全。通过 `paths` 配置实现了路径别名，使用 `@/` 指代 `src/` 目录，提高导入语句的可读性。

**Section sources**

- [tsconfig.json](file://tsconfig.json#L1-L50)
- [src/types/global.ts](file://src/types/global.ts#L1-L20)

## Vite 构建配置

项目使用 Vite 作为构建工具，在根目录下配置 `vite.config.ts` 文件，针对开发和生产环境进行优化。

### 开发环境配置

开发环境利用 Vite 的原生 ES 模块支持，提供快速的冷启动和热模块替换（HMR）。配置了代理服务器解决跨域问题，支持按需编译和懒加载。

### 生产环境优化

生产环境配置了多种优化策略：

- 使用 `vite-plugin-compress` 插件进行 gzip 和 brotli 压缩
- 通过 `vite-plugin-imagemin` 优化图片资源
- 使用 `rollup-plugin-visualizer` 分析打包体积
- 配置代码分割和懒加载策略

```mermaid
graph TB
A[Vite构建流程] --> B[源代码]
B --> C{环境}
C --> |开发| D[ESM按需编译]
C --> |生产| E[Rollup打包]
D --> F[热模块替换]
E --> G[代码分割]
E --> H[Tree Shaking]
E --> I[资源压缩]
E --> J[代码混淆]
F --> K[开发服务器]
G --> L[生产包]
H --> L
I --> L
J --> L
```

**Diagram sources**

- [vite.config.ts](file://vite.config.ts#L1-L100)
- [config/plugin/compress.ts](file://config/plugin/compress.ts#L1-L20)

**Section sources**

- [vite.config.ts](file://vite.config.ts#L1-L150)

## 开发与生产依赖

### 生产依赖

生产依赖是项目运行所必需的库：

- **vue**: Vue 3 核心框架
- **vue-router**: 路由管理
- **pinia**: 状态管理
- **@arco-design/web-vue**: Arco Design 组件库
- **axios**: HTTP 客户端
- **@tanstack/vue-query**: 服务端状态管理
- **nprogress**: 页面加载进度条
- **echarts**: 数据可视化图表

### 开发依赖

开发依赖用于开发、构建和测试过程：

- **vite**: 构建工具
- **typescript**: 类型系统
- **@vitejs/plugin-vue**: Vue 支持
- **vite-plugin-compress**: 打包压缩
- **vite-plugin-imagemin**: 图片优化
- **vite-plugin-visualizer**: 打包分析
- **@vitejs/plugin-vue-jsx**: JSX 支持
- **@types/node**: Node.js 类型定义

**Section sources**

- [package.json](file://package.json#L50-L150)

## 代码质量工具

### ESLint 配置

ESLint 用于 JavaScript/TypeScript 代码的静态分析，确保代码风格一致和避免常见错误。配置文件 `eslint.config.js` 定义了规则集，包括：

- 使用 Vue 3 的推荐规则
- TypeScript 类型检查
- 代码风格规范（缩进、分号、引号等）
- 最佳实践和潜在错误检测

### Stylelint 配置

Stylelint 用于 CSS/SCSS 代码的检查，确保样式代码的质量和一致性。配置文件 `stylelint.config.js` 包含：

- CSS 语法检查
- 属性顺序规范
- 命名约定
- 空格和缩进规则

### Commitlint 配置

Commitlint 用于规范 Git 提交消息格式，确保提交历史的可读性和可维护性。配置文件 `commitlint.config.js` 定义了提交消息的格式规则，通常采用 Conventional Commits 规范。

```mermaid
flowchart TD
A[编写代码] --> B[git commit]
B --> C{提交消息格式}
C --> |符合规范| D[提交成功]
C --> |不符合规范| E[提交失败]
E --> F[修改提交消息]
F --> C
```

**Diagram sources**

- [commitlint.config.js](file://commitlint.config.js#L1-L15)
- [eslint.config.js](file://eslint.config.js#L1-L30)
- [stylelint.config.js](file://stylelint.config.js#L1-L25)

**Section sources**

- [eslint.config.js](file://eslint.config.js#L1-L50)
- [stylelint.config.js](file://stylelint.config.js#L1-L30)
- [commitlint.config.js](file://commitlint.config.js#L1-L20)

## 依赖管理最佳实践

### 依赖更新策略

1. **定期更新**: 建立定期检查依赖更新的机制，建议每月进行一次
2. **安全更新**: 优先处理安全漏洞相关的更新
3. **测试验证**: 更新依赖后必须运行完整的测试套件
4. **渐进更新**: 对于重大版本更新，采用渐进式迁移策略

### 版本锁定

使用 `pnpm-lock.yaml` 锁定依赖版本，确保团队成员和生产环境使用完全相同的依赖版本。建议在 `package.json` 中使用精确版本号或锁定主版本号。

### 依赖审查

定期审查依赖树，移除未使用的依赖，减少项目体积和安全风险。可以使用 `npm ls` 或 `pnpm list` 命令分析依赖关系。

## 性能优化建议

### 代码分割

利用 Vue Router 的懒加载功能，将不同路由的组件分割成独立的代码块，实现按需加载：

```javascript
const routes = [
  {
    path: '/dashboard',
    component: () => import('@/views/dashboard/index.vue')
  }
];
```

### 图片优化

- 使用适当的图片格式（WebP 优先）
- 实施响应式图片
- 延迟加载非关键图片
- 压缩图片资源

### 缓存策略

- 利用 @tanstack/vue-query 的缓存机制
- 配置 HTTP 缓存头
- 使用浏览器本地存储

### 减少重渲染

- 使用 `v-memo` 指令
- 合理使用 `computed` 和 `watch`
- 避免在模板中使用复杂表达式

## 常见问题与解决方案

### 类型错误

**问题**: TypeScript 类型推断错误或类型不匹配  
**解决方案**:

- 检查接口定义是否正确
- 使用类型断言谨慎
- 更新类型定义文件

### 路由守卫无限循环

**问题**: 路由守卫配置不当导致无限重定向  
**解决方案**:

- 确保白名单路由正确配置
- 检查登录状态判断逻辑
- 添加调试日志

### 打包体积过大

**问题**: 生产包体积超出预期  
**解决方案**:

- 使用打包分析工具定位大体积模块
- 实施代码分割
- 移除未使用的依赖
- 启用压缩插件

### 环境变量未生效

**问题**: 环境变量在不同环境中未正确加载  
**解决方案**:

- 检查 `.env` 文件命名和位置
- 确保变量名以 `VITE_` 开头
- 重启开发服务器
