# API集成与数据处理

<cite>
**本文引用的文件**
- [frontend/src/api/request.js](file://frontend/src/api/request.js)
- [frontend/src/api/index.js](file://frontend/src/api/index.js)
- [frontend/src/api/auth.js](file://frontend/src/api/auth.js)
- [frontend/src/api/department.js](file://frontend/src/api/department.js)
- [frontend/src/api/staff.js](file://frontend/src/api/staff.js)
- [frontend/src/api/indicator.js](file://frontend/src/api/indicator.js)
- [frontend/src/api/assessment.js](file://frontend/src/api/assessment.js)
- [frontend/src/api/salary.js](file://frontend/src/api/salary.js)
- [frontend/src/api/template.js](file://frontend/src/api/template.js)
- [frontend/src/api/stats.js](file://frontend/src/api/stats.js)
- [frontend/src/stores/user.js](file://frontend/src/stores/user.js)
- [frontend/src/stores/app.js](file://frontend/src/stores/app.js)
- [frontend/src/router/index.js](file://frontend/src/router/index.js)
- [frontend/package.json](file://frontend/package.json)
- [frontend/vite.config.js](file://frontend/vite.config.js)
</cite>

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

## 简介
本指南围绕前端API集成与数据处理展开，覆盖HTTP请求封装、拦截器配置与错误处理、认证token管理、请求参数与查询条件传递、响应数据处理与状态码判断、分页与筛选排序、以及开发环境代理与生产部署要点。文档同时给出常见问题排查建议，帮助开发者快速理解并扩展该系统的API层。

## 项目结构
前端采用模块化API目录组织，按业务域拆分接口文件，并通过统一的请求封装与拦截器实现跨域代理、鉴权、错误提示等横切能力；Pinia用于状态管理，Vue Router负责路由与鉴权守卫；Vite提供开发服务器与代理配置。

```mermaid
graph TB
subgraph "前端"
VUE["Vue 应用<br/>main.js"]
ROUTER["路由<br/>router/index.js"]
STORE_USER["用户状态<br/>stores/user.js"]
STORE_APP["应用状态<br/>stores/app.js"]
API_INDEX["API聚合<br/>api/index.js"]
API_REQ["请求封装<br/>api/request.js"]
API_AUTH["认证接口<br/>api/auth.js"]
API_DEPT["科室接口<br/>api/department.js"]
API_STAFF["员工接口<br/>api/staff.js"]
API_IND["指标接口<br/>api/indicator.js"]
API_ASSESS["考核接口<br/>api/assessment.js"]
API_SAL["工资接口<br/>api/salary.js"]
API_TPL["模板接口<br/>api/template.js"]
API_STATS["统计接口<br/>api/stats.js"]
end
VUE --> ROUTER
VUE --> STORE_USER
VUE --> STORE_APP
VUE --> API_INDEX
API_INDEX --> API_REQ
API_INDEX --> API_AUTH
API_INDEX --> API_DEPT
API_INDEX --> API_STAFF
API_INDEX --> API_IND
API_INDEX --> API_ASSESS
API_INDEX --> API_SAL
API_INDEX --> API_TPL
API_INDEX --> API_STATS
```

图表来源
- [frontend/src/router/index.js](file://frontend/src/router/index.js#L1-L116)
- [frontend/src/stores/user.js](file://frontend/src/stores/user.js#L1-L49)
- [frontend/src/stores/app.js](file://frontend/src/stores/app.js#L1-L31)
- [frontend/src/api/index.js](file://frontend/src/api/index.js#L1-L9)
- [frontend/src/api/request.js](file://frontend/src/api/request.js#L1-L66)
- [frontend/src/api/auth.js](file://frontend/src/api/auth.js#L1-L22)
- [frontend/src/api/department.js](file://frontend/src/api/department.js#L1-L32)
- [frontend/src/api/staff.js](file://frontend/src/api/staff.js#L1-L32)
- [frontend/src/api/indicator.js](file://frontend/src/api/indicator.js#L1-L32)
- [frontend/src/api/assessment.js](file://frontend/src/api/assessment.js#L1-L50)
- [frontend/src/api/salary.js](file://frontend/src/api/salary.js#L1-L42)
- [frontend/src/api/template.js](file://frontend/src/api/template.js#L1-L62)
- [frontend/src/api/stats.js](file://frontend/src/api/stats.js#L1-L43)

章节来源
- [frontend/src/api/index.js](file://frontend/src/api/index.js#L1-L9)
- [frontend/src/api/request.js](file://frontend/src/api/request.js#L1-L66)
- [frontend/src/router/index.js](file://frontend/src/router/index.js#L1-L116)
- [frontend/src/stores/user.js](file://frontend/src/stores/user.js#L1-L49)
- [frontend/src/stores/app.js](file://frontend/src/stores/app.js#L1-L31)

## 核心组件
- 统一请求封装与拦截器
  - 基础配置：基础URL、超时、默认Content-Type
  - 请求拦截：自动注入Authorization头（Bearer Token）
  - 响应拦截：统一错误码判断、状态码分支处理、消息提示与路由跳转
- 认证与会话管理
  - 登录、获取当前用户、登出
  - Token持久化与路由守卫联动
- 状态管理
  - 用户状态：token、userInfo、登录/登出
  - 应用状态：侧边栏折叠、科室树加载
- 路由与鉴权
  - 全局前置守卫：未登录禁止访问受保护页面
- 开发代理与构建
  - Vite代理到后端服务
  - 构建脚本与依赖

章节来源
- [frontend/src/api/request.js](file://frontend/src/api/request.js#L1-L66)
- [frontend/src/api/auth.js](file://frontend/src/api/auth.js#L1-L22)
- [frontend/src/stores/user.js](file://frontend/src/stores/user.js#L1-L49)
- [frontend/src/router/index.js](file://frontend/src/router/index.js#L103-L113)
- [frontend/vite.config.js](file://frontend/vite.config.js#L12-L20)
- [frontend/package.json](file://frontend/package.json#L6-L10)

## 架构总览
下图展示从前端调用到后端服务的整体链路，包括请求拦截、认证、响应处理与错误反馈。

```mermaid
sequenceDiagram
participant View as "视图组件"
participant Store as "Pinia状态"
participant API as "API模块"
participant Req as "请求封装(request.js)"
participant Axios as "Axios实例"
participant Proxy as "Vite代理(/api)"
participant Backend as "后端服务"
View->>Store : 触发动作(如登录/加载数据)
Store->>API : 调用具体接口函数
API->>Req : 发起HTTP请求
Req->>Axios : 配置headers/params/timeout
Axios->>Proxy : 将/api前缀转发
Proxy->>Backend : 代理到后端地址
Backend-->>Proxy : 返回JSON响应
Proxy-->>Axios : 返回响应
Axios-->>Req : 进入响应拦截器
Req-->>API : 统一处理code/status
API-->>Store : 返回标准化数据
Store-->>View : 更新UI
```

图表来源
- [frontend/src/api/request.js](file://frontend/src/api/request.js#L6-L12)
- [frontend/src/api/request.js](file://frontend/src/api/request.js#L14-L26)
- [frontend/src/api/request.js](file://frontend/src/api/request.js#L28-L63)
- [frontend/vite.config.js](file://frontend/vite.config.js#L14-L19)
- [frontend/src/router/index.js](file://frontend/src/router/index.js#L103-L113)

## 详细组件分析

### 统一请求封装与拦截器
- 基础配置
  - 基础URL为/api/v1，所有接口以此为前缀
  - 默认超时30秒，Content-Type为application/json
- 请求拦截器
  - 从localStorage读取token并在请求头Authorization中附加Bearer前缀
- 响应拦截器
  - 自定义code字段判断：当code不等于200时，弹出错误消息并reject
  - 对常见HTTP状态码进行分支处理：401清理token并跳转登录、403无权限、404资源不存在、500服务器错误
  - 其他错误：优先展示后端detail，否则提示网络错误

```mermaid
flowchart TD
Start(["进入响应拦截器"]) --> CheckCode["检查自定义code字段"]
CheckCode --> CodeOK{"code是否为200?"}
CodeOK --> |是| ReturnRes["返回data"]
CodeOK --> |否| ShowMsg["弹出错误消息"]
ShowMsg --> RejectErr["Promise.reject(error)"]
ReturnRes --> End(["结束"])
RejectErr --> End
```

图表来源
- [frontend/src/api/request.js](file://frontend/src/api/request.js#L28-L37)

章节来源
- [frontend/src/api/request.js](file://frontend/src/api/request.js#L6-L12)
- [frontend/src/api/request.js](file://frontend/src/api/request.js#L14-L26)
- [frontend/src/api/request.js](file://frontend/src/api/request.js#L28-L63)

### 认证与会话管理
- 登录
  - 使用表单编码提交用户名与密码
  - 成功后保存access_token至localStorage并写入store
- 获取当前用户
  - 通过受保护接口获取用户信息
- 登出
  - 清空token与用户信息，删除localStorage中的token并跳转登录页
- 路由守卫
  - 未携带token访问受保护路由时重定向至登录页

```mermaid
sequenceDiagram
participant View as "登录页"
participant Store as "useUserStore"
participant API as "auth.js"
participant Req as "request.js"
participant Router as "router/index.js"
View->>Store : 调用login(username,password)
Store->>API : 调用login接口
API->>Req : POST /auth/login(表单编码)
Req-->>API : 返回{access_token}
API-->>Store : 返回token
Store->>Store : 写入localStorage与store
Store->>Router : 登录成功后继续导航
```

图表来源
- [frontend/src/api/auth.js](file://frontend/src/api/auth.js#L4-L11)
- [frontend/src/stores/user.js](file://frontend/src/stores/user.js#L11-L20)
- [frontend/src/router/index.js](file://frontend/src/router/index.js#L103-L113)

章节来源
- [frontend/src/api/auth.js](file://frontend/src/api/auth.js#L1-L22)
- [frontend/src/stores/user.js](file://frontend/src/stores/user.js#L1-L49)
- [frontend/src/router/index.js](file://frontend/src/router/index.js#L103-L113)

### 数据格式与参数传递
- 查询参数
  - 多数GET接口通过{ params }传入查询条件，支持分页、筛选、排序等
- 特殊场景
  - 批量创建考核时，后端期望重复的查询参数名，前端使用URLSearchParams拼接数组值
- 表单提交
  - 登录接口使用application/x-www-form-urlencoded，其余接口默认JSON

章节来源
- [frontend/src/api/department.js](file://frontend/src/api/department.js#L4-L5)
- [frontend/src/api/assessment.js](file://frontend/src/api/assessment.js#L40-L49)
- [frontend/src/api/auth.js](file://frontend/src/api/auth.js#L5-L10)

### 响应数据处理与状态码判断
- 自定义code字段
  - 当响应data.code不为200时，统一视为业务错误并提示
- HTTP状态码分支
  - 401：清除token并跳转登录
  - 403/404/500：分别提示对应错误
  - 其他：展示后端detail或网络错误
- 返回值
  - 成功时返回data，便于上层直接消费

章节来源
- [frontend/src/api/request.js](file://frontend/src/api/request.js#L28-L63)

### 分页、搜索与排序
- 分页
  - 通过查询参数传递页码与每页数量，后端返回总数与列表
- 搜索与过滤
  - 通过查询参数传入关键词与筛选条件
- 排序
  - 通过查询参数传入排序字段与方向
- 示例接口
  - 科室、员工、指标、模板、统计等均支持上述模式

章节来源
- [frontend/src/api/department.js](file://frontend/src/api/department.js#L4-L5)
- [frontend/src/api/staff.js](file://frontend/src/api/staff.js#L4-L5)
- [frontend/src/api/indicator.js](file://frontend/src/api/indicator.js#L4-L5)
- [frontend/src/api/template.js](file://frontend/src/api/template.js#L4-L5)
- [frontend/src/api/stats.js](file://frontend/src/api/stats.js#L4-L16)

### 文件上传与下载
- 上传
  - 使用multipart/form-data提交文件，后端返回上传结果
- 下载
  - 通过a链接或Blob对象触发浏览器下载
- 进度显示
  - 可通过axios上传配置的onUploadProgress回调实现
- 取消请求
  - 可使用AbortController在组件卸载或切换时取消未完成请求

说明：当前仓库未发现具体的上传/下载实现代码，以上为通用实践建议。

### Mock数据与开发环境
- 开发代理
  - Vite将/api前缀代理到本地后端服务，避免跨域问题
- Mock策略
  - 可在开发阶段引入mock库或后端模拟服务，便于联调与前端独立开发

章节来源
- [frontend/vite.config.js](file://frontend/vite.config.js#L12-L20)

### 生产环境部署
- 构建产物
  - 使用Vite构建静态资源，输出至dist目录
- 静态部署
  - 将dist作为静态站点部署，保持/api前缀不变
- 后端代理
  - 生产环境需确保/api请求能正确转发至后端服务

章节来源
- [frontend/package.json](file://frontend/package.json#L6-L10)
- [frontend/vite.config.js](file://frontend/vite.config.js#L12-L20)

## 依赖关系分析
- 组件耦合
  - API模块仅依赖统一请求封装，低耦合高内聚
  - 路由守卫与状态管理共同保障鉴权
- 外部依赖
  - axios：HTTP客户端
  - element-plus：消息提示与UI组件
  - pinia/vue-router：状态与路由

```mermaid
graph LR
API_REQ["api/request.js"] --> AXIOS["axios"]
API_AUTH["api/auth.js"] --> API_REQ
API_DEPT["api/department.js"] --> API_REQ
API_STAFF["api/staff.js"] --> API_REQ
API_IND["api/indicator.js"] --> API_REQ
API_ASSESS["api/assessment.js"] --> API_REQ
API_SAL["api/salary.js"] --> API_REQ
API_TPL["api/template.js"] --> API_REQ
API_STATS["api/stats.js"] --> API_REQ
STORE_USER["stores/user.js"] --> API_AUTH
STORE_APP["stores/app.js"] --> API_DEPT
ROUTER["router/index.js"] --> STORE_USER
```

图表来源
- [frontend/src/api/request.js](file://frontend/src/api/request.js#L1-L66)
- [frontend/src/api/auth.js](file://frontend/src/api/auth.js#L1-L22)
- [frontend/src/api/department.js](file://frontend/src/api/department.js#L1-L32)
- [frontend/src/api/staff.js](file://frontend/src/api/staff.js#L1-L32)
- [frontend/src/api/indicator.js](file://frontend/src/api/indicator.js#L1-L32)
- [frontend/src/api/assessment.js](file://frontend/src/api/assessment.js#L1-L50)
- [frontend/src/api/salary.js](file://frontend/src/api/salary.js#L1-L42)
- [frontend/src/api/template.js](file://frontend/src/api/template.js#L1-L62)
- [frontend/src/api/stats.js](file://frontend/src/api/stats.js#L1-L43)
- [frontend/src/stores/user.js](file://frontend/src/stores/user.js#L1-L49)
- [frontend/src/stores/app.js](file://frontend/src/stores/app.js#L1-L31)
- [frontend/src/router/index.js](file://frontend/src/router/index.js#L1-L116)

章节来源
- [frontend/src/api/index.js](file://frontend/src/api/index.js#L1-L9)
- [frontend/src/api/request.js](file://frontend/src/api/request.js#L1-L66)
- [frontend/src/stores/user.js](file://frontend/src/stores/user.js#L1-L49)
- [frontend/src/stores/app.js](file://frontend/src/stores/app.js#L1-L31)
- [frontend/src/router/index.js](file://frontend/src/router/index.js#L1-L116)

## 性能考虑
- 请求合并与去抖
  - 对频繁触发的搜索/筛选操作，可在组件层增加防抖
- 缓存策略
  - 对不常变动的数据（如字典、类型列表）可加入内存缓存
- 分页与懒加载
  - 列表页使用分页，结合虚拟滚动提升渲染性能
- 体积优化
  - 按需引入Element Plus组件，减少打包体积

## 故障排查指南
- 登录后仍被重定向至登录页
  - 检查localStorage中token是否存在，确认路由守卫逻辑
- 401错误频繁出现
  - 检查请求头Authorization是否正确附加，确认后端token有效期
- 403/404/500错误
  - 查看后端日志与接口文档，确认权限与资源存在性
- 网络错误提示
  - 检查Vite代理配置与后端服务连通性
- 批量参数传递异常
  - 确认后端期望的重复参数名与数值类型

章节来源
- [frontend/src/router/index.js](file://frontend/src/router/index.js#L103-L113)
- [frontend/src/api/request.js](file://frontend/src/api/request.js#L38-L61)
- [frontend/vite.config.js](file://frontend/vite.config.js#L14-L19)
- [frontend/src/api/assessment.js](file://frontend/src/api/assessment.js#L40-L49)

## 结论
该前端API层通过统一的请求封装与拦截器实现了鉴权、错误处理与跨域代理，配合Pinia与路由守卫形成清晰的认证与状态管理闭环。业务接口按模块化组织，查询参数传递规范，具备良好的扩展性。建议在后续迭代中补充文件上传/下载与Mock能力，并完善批量参数与分页的通用工具方法，以进一步提升开发效率与用户体验。

## 附录
- 常用接口一览（示例）
  - 认证：登录、获取当前用户、注册
  - 基础数据：科室、员工、指标、模板
  - 考核与工资：创建、提交、审核、生成、确认
  - 统计：部门统计、周期统计、趋势、排名、仪表盘、预警
- 开发与部署
  - 开发：npm run dev（Vite启动+代理）
  - 构建：npm run build（输出dist）
  - 预览：npm run preview

章节来源
- [frontend/src/api/index.js](file://frontend/src/api/index.js#L1-L9)
- [frontend/src/api/auth.js](file://frontend/src/api/auth.js#L1-L22)
- [frontend/src/api/department.js](file://frontend/src/api/department.js#L1-L32)
- [frontend/src/api/staff.js](file://frontend/src/api/staff.js#L1-L32)
- [frontend/src/api/indicator.js](file://frontend/src/api/indicator.js#L1-L32)
- [frontend/src/api/template.js](file://frontend/src/api/template.js#L1-L62)
- [frontend/src/api/assessment.js](file://frontend/src/api/assessment.js#L1-L50)
- [frontend/src/api/salary.js](file://frontend/src/api/salary.js#L1-L42)
- [frontend/src/api/stats.js](file://frontend/src/api/stats.js#L1-L43)
- [frontend/package.json](file://frontend/package.json#L6-L10)
- [frontend/vite.config.js](file://frontend/vite.config.js#L12-L20)