提交文件

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/系统架构/组件交互关系.md
+++ b/.qoder/repowiki/zh/content/系统架构/组件交互关系.md
@@ -0,0 +1,387 @@
+# 组件交互关系
+
+<cite>
+**本文引用的文件**
+- [backend/app/main.py](file://backend/app/main.py)
+- [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py)
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py)
+- [backend/app/core/config.py](file://backend/app/core/config.py)
+- [backend/app/core/database.py](file://backend/app/core/database.py)
+- [backend/app/core/security.py](file://backend/app/core/security.py)
+- [backend/app/models/models.py](file://backend/app/models/models.py)
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py)
+- [frontend/src/main.js](file://frontend/src/main.js)
+- [frontend/src/router/index.js](file://frontend/src/router/index.js)
+- [frontend/src/api/request.js](file://frontend/src/api/request.js)
+- [frontend/src/api/assessment.js](file://frontend/src/api/assessment.js)
+- [frontend/src/stores/user.js](file://frontend/src/stores/user.js)
+- [frontend/src/views/Dashboard.vue](file://frontend/src/views/Dashboard.vue)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构总览](#架构总览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖分析](#依赖分析)
+7. [性能考虑](#性能考虑)
+8. [故障排查指南](#故障排查指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+本文件面向“医院绩效系统”的前后端交互与内部架构，聚焦以下主题：
+- 前端 Vue 组件与后端 FastAPI 服务的交互模式：HTTP 请求/响应流程、API 封装与错误处理
+- 组件间通信方式：父子、兄弟与跨组件状态共享
+- 数据库连接池管理、ORM 查询优化与事务处理
+- 中间件作用：CORS、身份验证、日志与异常捕获
+- 数据流与组件依赖关系图
+
+## 项目结构
+系统采用前后端分离架构：
+- 前端：Vue 3 + Pinia + Element Plus + Vue Router
+- 后端：FastAPI + SQLAlchemy 2.0（异步）+ PostgreSQL
+- 数据模型统一定义于 ORM 层，服务层负责业务逻辑，API 层提供 REST 接口
+
+```mermaid
+graph TB
+subgraph "前端"
+FE_Main["main.js<br/>应用入口"]
+FE_Router["router/index.js<br/>路由与守卫"]
+FE_API["api/request.js<br/>Axios封装"]
+FE_AsmAPI["api/assessment.js<br/>考核API"]
+FE_UserStore["stores/user.js<br/>用户状态"]
+FE_Dashboard["views/Dashboard.vue<br/>工作台视图"]
+end
+subgraph "后端"
+BE_App["app/main.py<br/>应用与中间件"]
+BE_Config["core/config.py<br/>配置"]
+BE_DB["core/database.py<br/>异步引擎/会话"]
+BE_Security["core/security.py<br/>JWT/认证"]
+BE_Models["models/models.py<br/>ORM模型"]
+BE_Svc_Asm["services/assessment_service.py<br/>服务层"]
+BE_API_Init["api/v1/__init__.py<br/>路由聚合"]
+BE_API_Auth["api/v1/auth.py<br/>认证接口"]
+end
+FE_Main --> FE_Router
+FE_Main --> FE_API
+FE_API --> BE_App
+FE_AsmAPI --> FE_API
+FE_UserStore --> FE_API
+FE_Dashboard --> FE_AsmAPI
+BE_App --> BE_Config
+BE_App --> BE_DB
+BE_App --> BE_API_Init
+BE_API_Init --> BE_API_Auth
+BE_Security --> BE_DB
+BE_Svc_Asm --> BE_DB
+BE_Svc_Asm --> BE_Models
+```
+
+图表来源
+- [backend/app/main.py](file://backend/app/main.py#L15-L77)
+- [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py#L1-L17)
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L1-L74)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L1-L47)
+- [backend/app/core/database.py](file://backend/app/core/database.py#L1-L39)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L1-L110)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L438)
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
+- [frontend/src/main.js](file://frontend/src/main.js#L1-L24)
+- [frontend/src/router/index.js](file://frontend/src/router/index.js#L1-L116)
+- [frontend/src/api/request.js](file://frontend/src/api/request.js#L1-L66)
+- [frontend/src/api/assessment.js](file://frontend/src/api/assessment.js#L1-L50)
+- [frontend/src/stores/user.js](file://frontend/src/stores/user.js#L1-L49)
+- [frontend/src/views/Dashboard.vue](file://frontend/src/views/Dashboard.vue#L1-L1082)
+
+章节来源
+- [backend/app/main.py](file://backend/app/main.py#L15-L77)
+- [frontend/src/main.js](file://frontend/src/main.js#L1-L24)
+
+## 核心组件
+- 前端应用入口与插件注册：初始化 Vue 实例、Pinia、路由、Element Plus，并挂载应用。
+- 路由与导航守卫：统一设置页面标题、校验登录态（localStorage token），未登录重定向至登录页。
+- Axios 封装：统一基础 URL、超时、请求头；自动注入 Authorization；统一封装响应体结构与错误处理。
+- 用户状态管理：登录、获取当前用户、登出，持久化 token 并跳转登录页。
+- API 模块：按功能拆分，如考核 API，支持列表、详情、创建、更新、提交、审核、确认、批量创建等。
+- 后端应用：创建 FastAPI 实例，注册 CORS、路由前缀、健康检查与全局异常处理器。
+- 安全与认证：JWT 生成与解析、OAuth2 密钥流、当前用户解析与权限校验。
+- 数据库：异步引擎与会话工厂，依赖注入式获取会话，自动提交/回滚/关闭。
+- 业务服务：如考核服务，实现分页、过滤、明细计算、状态流转、批量创建等。
+
+章节来源
+- [frontend/src/main.js](file://frontend/src/main.js#L1-L24)
+- [frontend/src/router/index.js](file://frontend/src/router/index.js#L103-L113)
+- [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/api/assessment.js](file://frontend/src/api/assessment.js#L1-L50)
+- [backend/app/main.py](file://backend/app/main.py#L15-L77)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L1-L110)
+- [backend/app/core/database.py](file://backend/app/core/database.py#L1-L39)
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
+
+## 架构总览
+系统采用“前端 SPA + 后端 API”模式，数据流自上而下：
+- 前端组件通过 API 模块发起 HTTP 请求，Axios 统一拦截器注入 token 并处理响应。
+- 后端 FastAPI 解析请求，路由到对应控制器，依赖注入数据库会话，调用服务层执行业务逻辑。
+- 服务层操作 ORM 模型，进行查询、计算与写入，返回标准化结果。
+- 异常在后端统一捕获并记录日志，前端根据响应体或 HTTP 状态码进行提示与跳转。
+
+```mermaid
+sequenceDiagram
+participant View as "Dashboard.vue"
+participant API as "assessment.js"
+participant Axios as "request.js"
+participant FastAPI as "main.py"
+participant Router as "api/v1/auth.py"
+participant Sec as "core/security.py"
+participant DB as "core/database.py"
+View->>API : "调用获取考核列表/详情/趋势等"
+API->>Axios : "GET /api/v1/...带Authorization"
+Axios->>FastAPI : "HTTP 请求"
+FastAPI->>Router : "路由匹配"
+Router->>Sec : "依赖注入当前用户JWT"
+Sec->>DB : "获取 AsyncSession"
+DB-->>Sec : "会话可用"
+Sec-->>Router : "返回当前用户"
+Router-->>Axios : "业务处理读取/写入"
+Axios-->>View : "返回标准化数据"
+```
+
+图表来源
+- [frontend/src/views/Dashboard.vue](file://frontend/src/views/Dashboard.vue#L329-L421)
+- [frontend/src/api/assessment.js](file://frontend/src/api/assessment.js#L1-L50)
+- [frontend/src/api/request.js](file://frontend/src/api/request.js#L1-L66)
+- [backend/app/main.py](file://backend/app/main.py#L58-L74)
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L17-L37)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L55-L82)
+- [backend/app/core/database.py](file://backend/app/core/database.py#L28-L39)
+
+## 详细组件分析
+
+### 前端组件与 API 交互
+- 登录流程
+  - 用户输入账号密码 → 调用登录 API → 成功后保存 token 到 localStorage → 跳转首页
+  - 失败时返回错误，前端不保存 token
+- 路由守卫
+  - 进入受保护路由前检查 token，缺失则重定向登录
+- Axios 封装
+  - 自动注入 Authorization: Bearer token
+  - 统一响应体结构：当 res.code !== 200 时提示错误并 reject
+  - 对 401/403/404/500 等状态码分别处理，401 清除 token 并跳转登录
+- Dashboard 视图
+  - 使用多个 API 方法加载统计数据、趋势、排名、财务趋势与预警
+  - 通过 ECharts 渲染图表，监听窗口 resize 事件保持图表尺寸一致
+
+```mermaid
+sequenceDiagram
+participant Comp as "Dashboard.vue"
+participant Store as "user.js"
+participant API as "assessment.js"
+participant Req as "request.js"
+participant BE as "auth.py"
+Comp->>Store : "登录用户名/密码"
+Store->>BE : "POST /api/v1/auth/login"
+BE-->>Store : "返回 access_token"
+Store->>Store : "保存 token 到 localStorage"
+Store-->>Comp : "登录成功"
+Comp->>API : "getPeriodStats/getTrendData/..."
+API->>Req : "GET /api/v1/stats/...含Authorization"
+Req-->>Comp : "返回数据并渲染图表"
+```
+
+图表来源
+- [frontend/src/views/Dashboard.vue](file://frontend/src/views/Dashboard.vue#L329-L421)
+- [frontend/src/stores/user.js](file://frontend/src/stores/user.js#L11-L20)
+- [frontend/src/api/assessment.js](file://frontend/src/api/assessment.js#L1-L50)
+- [frontend/src/api/request.js](file://frontend/src/api/request.js#L14-L63)
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L17-L37)
+
+章节来源
+- [frontend/src/router/index.js](file://frontend/src/router/index.js#L103-L113)
+- [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/views/Dashboard.vue](file://frontend/src/views/Dashboard.vue#L329-L421)
+
+### 后端 API 与服务层
+- 应用与中间件
+  - 注册 CORS：允许指定 origins、credentials、methods、headers
+  - 注册路由前缀与健康检查
+  - 全局异常处理：HTTP 异常、请求验证异常、通用异常均记录日志并抛出
+- 认证与安全
+  - 登录：校验用户名与密码，检查用户是否激活，签发 JWT
+  - 当前用户：OAuth2 密钥流 + JWT 解码 + 数据库查询
+  - 权限校验：管理员、经理等角色校验
+- 服务层（示例：考核）
+  - 支持多条件分页查询、预加载关联、计算总分与加权得分
+  - 状态机：草稿/已提交/已审核/已确认/已驳回
+  - 批量创建：按科室与周期批量生成考核记录与明细
+
+```mermaid
+flowchart TD
+Start(["请求进入"]) --> CORS["CORS 中间件校验"]
+CORS --> Router["路由匹配/api/v1/..."]
+Router --> Auth["OAuth2/JWT 校验当前用户"]
+Auth --> Service["服务层业务处理查询/计算/写入"]
+Service --> ORM["ORM 操作异步会话"]
+ORM --> Resp["返回标准化响应"]
+Resp --> End(["结束"])
+Router -.->|异常| Log["记录日志并抛出异常"]
+Log --> End
+```
+
+图表来源
+- [backend/app/main.py](file://backend/app/main.py#L41-L74)
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L17-L37)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L55-L82)
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L18-L55)
+
+章节来源
+- [backend/app/main.py](file://backend/app/main.py#L41-L74)
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L1-L74)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L1-L110)
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
+
+### 数据库连接池与事务
+- 异步引擎与会话工厂
+  - 使用异步驱动创建引擎，开启调试输出
+  - 会话工厂设置类为 AsyncSession，关闭提交行为，避免每次提交后失效
+- 依赖注入
+  - get_db 作为依赖，在 try 块中 yield 会话，成功提交，异常回滚并抛出，finally 关闭
+- 事务语义
+  - 单次请求内使用同一会话，异常自动回滚，保证一致性
+- 查询优化
+  - 使用 selectinload 预加载关联，减少 N+1 查询
+  - 多处使用索引字段过滤与排序，结合分页 limit/offset
+
+```mermaid
+flowchart TD
+S(["进入依赖 get_db"]) --> New["创建 AsyncSession"]
+New --> Try["yield 会话给业务"]
+Try --> Ok{"是否异常？"}
+Ok -- 是 --> Rollback["session.rollback()"]
+Rollback --> Throw["raise 异常"]
+Ok -- 否 --> Commit["session.commit()"]
+Commit --> Close["session.close()"]
+Throw --> Close
+Close --> E(["退出依赖"])
+```
+
+图表来源
+- [backend/app/core/database.py](file://backend/app/core/database.py#L28-L39)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L78-L85)
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L29-L31)
+
+章节来源
+- [backend/app/core/database.py](file://backend/app/core/database.py#L1-L39)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L438)
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
+
+### 组件间通信与状态共享
+- 父子组件通信
+  - Dashboard.vue 通过 props 传递图表容器引用与数据，内部通过 ECharts 实例渲染
+- 兄弟组件通信
+  - 通过 Pinia store 共享用户 token 与基本信息，任一组件可读写
+- 跨组件状态共享
+  - 用户 store 统一管理登录态，路由守卫依赖其 token 判断访问权限
+  - API 层通过 Axios 拦截器自动注入 Authorization，避免重复处理
+
+章节来源
+- [frontend/src/views/Dashboard.vue](file://frontend/src/views/Dashboard.vue#L423-L448)
+- [frontend/src/stores/user.js](file://frontend/src/stores/user.js#L1-L49)
+- [frontend/src/api/request.js](file://frontend/src/api/request.js#L14-L26)
+
+## 依赖分析
+- 前端
+  - main.js 依赖 router、store、Element Plus
+  - router/index.js 依赖懒加载组件与 beforeEach 守卫
+  - api/request.js 依赖 axios、Element Plus Message、router
+  - api/assessment.js 依赖 request
+  - stores/user.js 依赖 api/auth 与 router
+  - views/Dashboard.vue 依赖多个统计 API 与 ECharts
+- 后端
+  - app/main.py 依赖 core/config、core/logging_config、api/v1
+  - api/v1/__init__.py 依赖各功能路由模块
+  - api/v1/auth.py 依赖 core/database、core/security、schemas、models
+  - core/security.py 依赖 core/config、core/database、jose、bcrypt
+  - core/database.py 依赖 core/config
+  - models/models.py 依赖 core/database
+  - services/assessment_service.py 依赖 models、schemas、sqlalchemy
+
+```mermaid
+graph LR
+FE_Main["main.js"] --> FE_Router["router/index.js"]
+FE_Main --> FE_API["api/request.js"]
+FE_API --> FE_AsmAPI["api/assessment.js"]
+FE_AsmAPI --> FE_Dashboard["views/Dashboard.vue"]
+BE_App["app/main.py"] --> BE_API_Init["api/v1/__init__.py"]
+BE_API_Init --> BE_API_Auth["api/v1/auth.py"]
+BE_App --> BE_Config["core/config.py"]
+BE_App --> BE_DB["core/database.py"]
+BE_API_Auth --> BE_Security["core/security.py"]
+BE_Security --> BE_DB
+BE_Svc_Asm["services/assessment_service.py"] --> BE_Models["models/models.py"]
+```
+
+图表来源
+- [frontend/src/main.js](file://frontend/src/main.js#L1-L24)
+- [frontend/src/router/index.js](file://frontend/src/router/index.js#L1-L116)
+- [frontend/src/api/request.js](file://frontend/src/api/request.js#L1-L66)
+- [frontend/src/api/assessment.js](file://frontend/src/api/assessment.js#L1-L50)
+- [frontend/src/views/Dashboard.vue](file://frontend/src/views/Dashboard.vue#L1-L1082)
+- [backend/app/main.py](file://backend/app/main.py#L1-L92)
+- [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py#L1-L17)
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L1-L74)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L1-L47)
+- [backend/app/core/database.py](file://backend/app/core/database.py#L1-L39)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L1-L110)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L438)
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
+
+章节来源
+- [frontend/src/main.js](file://frontend/src/main.js#L1-L24)
+- [backend/app/main.py](file://backend/app/main.py#L1-L92)
+
+## 性能考虑
+- 异步 I/O 与连接池
+  - 使用 SQLAlchemy 2.0 异步引擎与连接池，提升并发吞吐
+  - 通过依赖注入复用会话，避免频繁创建销毁
+- 查询优化
+  - 使用 selectinload 预加载关联，减少 N+1 查询
+  - 多处对常用过滤字段建立索引，配合分页 limit/offset
+- 前端性能
+  - ECharts 图表按需渲染，窗口 resize 时统一触发重绘
+  - API 返回结构化数据，前端仅渲染必要字段，降低 DOM 压力
+
+## 故障排查指南
+- 登录失败
+  - 检查用户名/密码是否正确，用户是否被禁用
+  - 查看后端日志与前端错误提示，确认 401/403 场景
+- 401 未授权
+  - 前端移除本地 token 并跳转登录；确认 JWT 未过期
+- 403 权限不足
+  - 确认用户角色是否满足接口要求（管理员/经理）
+- 500 服务器错误
+  - 查看后端日志定位异常堆栈，确认数据库事务是否回滚
+- 前端网络错误
+  - 检查 baseURL 是否正确（/api/v1），CORS 是否放行
+  - 确认 Axios 拦截器是否正确注入 Authorization
+
+章节来源
+- [frontend/src/api/request.js](file://frontend/src/api/request.js#L38-L63)
+- [backend/app/main.py](file://backend/app/main.py#L58-L74)
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L30-L34)
+
+## 结论
+本系统通过清晰的前后端职责划分与中间件、安全、数据库与服务层的协同，实现了稳定高效的绩效管理能力。前端以组件为中心，通过 API 模块与状态管理实现松耦合；后端以 FastAPI 为核心，结合异步 ORM 与严格的安全策略，确保高并发下的可靠性与可维护性。建议持续关注查询索引、分页与缓存策略，进一步优化大数据量场景下的性能表现。
+
+## 附录
+- 配置项参考
+  - 应用名、版本、API 前缀、数据库连接、JWT 密钥与过期时间、CORS 允许源、分页大小
+- 数据模型概览
+  - 部门、员工、指标、考核、明细、工资、计划、菜单、模板等核心实体及其关系
+
+章节来源
+- [backend/app/core/config.py](file://backend/app/core/config.py#L13-L33)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L438)