Files

2026-02-28 15:16:15 +08:00

18 KiB

Raw Permalink Blame History

组件交互关系

**本文引用的文件** - [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)

简介

本文件面向“医院绩效系统”的前后端交互与内部架构，聚焦以下主题：

前端 Vue 组件与后端 FastAPI 服务的交互模式：HTTP 请求/响应流程、API 封装与错误处理
组件间通信方式：父子、兄弟与跨组件状态共享
数据库连接池管理、ORM 查询优化与事务处理
中间件作用：CORS、身份验证、日志与异常捕获
数据流与组件依赖关系图

项目结构

系统采用前后端分离架构：

前端：Vue 3 + Pinia + Element Plus + Vue Router
后端：FastAPI + SQLAlchemy 2.0（异步）+ PostgreSQL
数据模型统一定义于 ORM 层，服务层负责业务逻辑，API 层提供 REST 接口

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

图表来源

章节来源

核心组件

前端应用入口与插件注册：初始化 Vue 实例、Pinia、路由、Element Plus，并挂载应用。
路由与导航守卫：统一设置页面标题、校验登录态（localStorage token），未登录重定向至登录页。
Axios 封装：统一基础 URL、超时、请求头；自动注入 Authorization；统一封装响应体结构与错误处理。
用户状态管理：登录、获取当前用户、登出，持久化 token 并跳转登录页。
API 模块：按功能拆分，如考核 API，支持列表、详情、创建、更新、提交、审核、确认、批量创建等。
后端应用：创建 FastAPI 实例，注册 CORS、路由前缀、健康检查与全局异常处理器。
安全与认证：JWT 生成与解析、OAuth2 密钥流、当前用户解析与权限校验。
数据库：异步引擎与会话工厂，依赖注入式获取会话，自动提交/回滚/关闭。
业务服务：如考核服务，实现分页、过滤、明细计算、状态流转、批量创建等。

章节来源

架构总览

系统采用“前端 SPA + 后端 API”模式，数据流自上而下：

前端组件通过 API 模块发起 HTTP 请求，Axios 统一拦截器注入 token 并处理响应。
后端 FastAPI 解析请求，路由到对应控制器，依赖注入数据库会话，调用服务层执行业务逻辑。
服务层操作 ORM 模型，进行查询、计算与写入，返回标准化结果。
异常在后端统一捕获并记录日志，前端根据响应体或 HTTP 状态码进行提示与跳转。

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 : "返回标准化数据"

图表来源

详细组件分析

前端组件与 API 交互

登录流程
- 用户输入账号密码 → 调用登录 API → 成功后保存 token 到 localStorage → 跳转首页
- 失败时返回错误，前端不保存 token
路由守卫
- 进入受保护路由前检查 token，缺失则重定向登录
Axios 封装
- 自动注入 Authorization: Bearer token
- 统一响应体结构：当 res.code !== 200 时提示错误并 reject
- 对 401/403/404/500 等状态码分别处理，401 清除 token 并跳转登录
Dashboard 视图
- 使用多个 API 方法加载统计数据、趋势、排名、财务趋势与预警
- 通过 ECharts 渲染图表，监听窗口 resize 事件保持图表尺寸一致

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 : "返回数据并渲染图表"

图表来源

章节来源

后端 API 与服务层

应用与中间件
- 注册 CORS：允许指定 origins、credentials、methods、headers
- 注册路由前缀与健康检查
- 全局异常处理：HTTP 异常、请求验证异常、通用异常均记录日志并抛出
认证与安全
- 登录：校验用户名与密码，检查用户是否激活，签发 JWT
- 当前用户：OAuth2 密钥流 + JWT 解码 + 数据库查询
- 权限校验：管理员、经理等角色校验
服务层（示例：考核）
- 支持多条件分页查询、预加载关联、计算总分与加权得分
- 状态机：草稿/已提交/已审核/已确认/已驳回
- 批量创建：按科室与周期批量生成考核记录与明细

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

图表来源

章节来源

数据库连接池与事务

异步引擎与会话工厂
- 使用异步驱动创建引擎，开启调试输出
- 会话工厂设置类为 AsyncSession，关闭提交行为，避免每次提交后失效
依赖注入
- get_db 作为依赖，在 try 块中 yield 会话，成功提交，异常回滚并抛出，finally 关闭
事务语义
- 单次请求内使用同一会话，异常自动回滚，保证一致性
查询优化
- 使用 selectinload 预加载关联，减少 N+1 查询
- 多处使用索引字段过滤与排序，结合分页 limit/offset

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(["退出依赖"])

图表来源

章节来源

组件间通信与状态共享

父子组件通信
- Dashboard.vue 通过 props 传递图表容器引用与数据，内部通过 ECharts 实例渲染
兄弟组件通信
- 通过 Pinia store 共享用户 token 与基本信息，任一组件可读写
跨组件状态共享
- 用户 store 统一管理登录态，路由守卫依赖其 token 判断访问权限
- API 层通过 Axios 拦截器自动注入 Authorization，避免重复处理

章节来源

依赖分析

前端
- 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

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"]

图表来源

章节来源

性能考虑

异步 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

章节来源

结论

本系统通过清晰的前后端职责划分与中间件、安全、数据库与服务层的协同，实现了稳定高效的绩效管理能力。前端以组件为中心，通过 API 模块与状态管理实现松耦合；后端以 FastAPI 为核心，结合异步 ORM 与严格的安全策略，确保高并发下的可靠性与可维护性。建议持续关注查询索引、分页与缓存策略，进一步优化大数据量场景下的性能表现。

附录

配置项参考
- 应用名、版本、API 前缀、数据库连接、JWT 密钥与过期时间、CORS 允许源、分页大小
数据模型概览
- 部门、员工、指标、考核、明细、工资、计划、菜单、模板等核心实体及其关系

章节来源

18 KiB Raw Permalink Blame History Unescape Escape

组件交互关系

目录

简介

项目结构

核心组件

架构总览

详细组件分析

前端组件与 API 交互

后端 API 与服务层

数据库连接池与事务

组件间通信与状态共享

依赖分析

性能考虑

故障排查指南

结论

附录

18 KiB

Raw Permalink Blame History