提交文件

2026-02-28 15:16:15 +08:00
parent 1a4e50e0a4
commit 44f250f58e
159 changed files with 61268 additions and 0 deletions
--- a/.qoder/repowiki/zh/content/前端开发指南/API集成与数据处理.md
+++ b/.qoder/repowiki/zh/content/前端开发指南/API集成与数据处理.md
@@ -0,0 +1,397 @@
+# 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)