Files

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

16 KiB

Raw Blame History

整体架构设计

**本文引用的文件** - [backend/app/main.py](file://backend/app/main.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/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/services/staff_service.py](file://backend/app/services/staff_service.py) - [backend/app/models/models.py](file://backend/app/models/models.py) - [frontend/src/main.js](file://frontend/src/main.js) - [frontend/src/router/index.js](file://frontend/src/router/index.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/api/request.js](file://frontend/src/api/request.js) - [frontend/vite.config.js](file://frontend/vite.config.js) - [backend/requirements.txt](file://backend/requirements.txt) - [frontend/package.json](file://frontend/package.json)

引言

本文件面向“医院绩效系统”的整体架构设计，围绕后端采用 FastAPI 的分层架构与前端 Vue 3 的单页应用（SPA）进行系统化说明。重点涵盖：

分层架构：表现层（前端）、业务逻辑层（后端服务）、数据访问层（SQLAlchemy 异步 ORM）
前后端分离：CORS 配置、API 路由前缀、开发代理与跨域处理
后端应用实例：FastAPI 实例创建、中间件与全局异常处理
前端初始化：应用挂载、路由守卫与状态管理
系统启动流程、健康检查与错误处理策略

项目结构

系统采用前后端分离的工程组织方式：

后端（Python/FastAPI）：app 目录下按功能分层（core、api、models、schemas、services、utils），通过 APIRouter 聚合路由
前端（Vue 3/Pinia/Vite）：src 下按功能模块组织（api、components、router、stores、views），使用 Vite 开发服务器与代理

graph TB
subgraph "后端"
A_main["backend/app/main.py<br/>应用入口与中间件"]
A_cfg["backend/app/core/config.py<br/>配置中心"]
A_db["backend/app/core/database.py<br/>异步数据库引擎"]
A_api["backend/app/api/v1/__init__.py<br/>路由聚合"]
A_auth["backend/app/api/v1/auth.py<br/>认证路由"]
A_srv["backend/app/services/*<br/>业务服务层"]
A_models["backend/app/models/models.py<br/>ORM 模型"]
end
subgraph "前端"
F_main["frontend/src/main.js<br/>应用初始化"]
F_router["frontend/src/router/index.js<br/>路由与守卫"]
F_store_user["frontend/src/stores/user.js<br/>用户状态"]
F_store_app["frontend/src/stores/app.js<br/>应用状态"]
F_req["frontend/src/api/request.js<br/>HTTP 封装与拦截器"]
F_vite["frontend/vite.config.js<br/>开发代理"]
end
F_main --> F_router
F_main --> F_store_user
F_main --> F_store_app
F_router --> F_req
F_store_user --> F_req
F_store_app --> F_req
F_req --> A_api
A_main --> A_cfg
A_main --> A_db
A_api --> A_auth
A_auth --> A_srv
A_srv --> A_models

图表来源

章节来源

核心组件

后端应用实例与中间件
- 应用实例创建：定义标题、版本、OpenAPI 文档路径前缀，并注册统一 API 前缀
- CORS 中间件：允许指定源、凭证、方法与头
- 路由注册：include_router 并设置 API 前缀
- 健康检查：提供 /health 接口返回系统状态与版本
- 全局异常处理：HTTP 异常、请求验证异常与通用异常的日志与抛出
配置中心
- 应用名、版本、调试开关、API 前缀
- 数据库连接串、连接池大小
- JWT 密钥、算法、过期时间
- CORS 允许源列表
- 分页默认与最大页大小
数据库层
- 异步引擎与会话工厂
- 基类与依赖注入 get_db
前端应用初始化
- 创建 Vue 应用、注册 Element Plus、Pinia、路由
- 挂载到 DOM
路由与守卫
- 定义登录页与主布局子路由
- beforeEach 守卫：读取本地 token，未登录跳转登录
状态管理
- Pinia Store：用户登录态与信息、应用侧边栏与科室树
HTTP 封装与拦截器
- axios 实例：baseURL 为 /api/v1
- 请求拦截：自动附加 Bearer Token
- 响应拦截：统一错误提示与 401 自动登出
开发代理
- Vite 代理 /api → 后端 8000 端口，解决开发时跨域问题

章节来源

架构总览

系统采用典型的三层架构与前后端分离模式：

表现层（前端）：Vue 3 SPA，通过 axios 访问后端 API
业务逻辑层（后端）：FastAPI 路由与服务层，封装领域业务
数据访问层（后端）：SQLAlchemy 异步 ORM，提供模型与查询能力

graph TB
FE["前端 Vue 3<br/>src/main.js"] --> RT["路由守卫<br/>router/index.js"]
FE --> ST["状态管理<br/>stores/user.js, app.js"]
FE --> AX["HTTP 封装<br/>api/request.js"]
AX --> API["后端 API 路由<br/>api/v1/*"]
API --> SRV["服务层<br/>services/*"]
SRV --> DB["数据库层<br/>models + database.py"]
DB --> PG["PostgreSQL"]
subgraph "后端"
MAIN["FastAPI 应用<br/>main.py"]
CFG["配置中心<br/>config.py"]
CORS["CORS 中间件"]
HEALTH["健康检查 /health"]
end
FE --> MAIN
MAIN --> CORS
MAIN --> API
MAIN --> CFG
MAIN --> HEALTH

图表来源

详细组件分析

后端应用实例与中间件

应用创建：设置应用元信息、OpenAPI 文档路径、API 前缀
CORS：允许指定源、凭证、通配方法与头
路由注册：include_router 并使用统一前缀
健康检查：/health 返回系统状态与版本
异常处理：HTTP、验证、通用异常分别记录日志并抛出

sequenceDiagram
participant Client as "客户端"
participant FastAPI as "FastAPI 应用"
participant Router as "API 路由"
participant Service as "服务层"
participant DB as "数据库"
Client->>FastAPI : "GET /api/v1/health"
FastAPI-->>Client : "{status : healthy, version}"
Client->>FastAPI : "POST /api/v1/auth/login"
FastAPI->>Router : "转发到 auth 路由"
Router->>Service : "调用认证服务"
Service->>DB : "查询用户并校验密码"
DB-->>Service : "返回用户信息"
Service-->>Router : "生成访问令牌"
Router-->>Client : "返回 Token"

图表来源

章节来源

配置中心与数据库层

配置项：应用名、版本、API 前缀、数据库 URL、JWT、CORS、分页等
数据库：异步引擎、会话工厂、依赖注入 get_db；模型继承 Base

flowchart TD
Start(["启动"]) --> LoadCfg["加载配置<br/>config.py"]
LoadCfg --> InitEngine["创建异步引擎<br/>database.py"]
InitEngine --> InitSession["创建会话工厂<br/>database.py"]
InitSession --> Ready(["就绪"])

图表来源

章节来源

业务服务层与模型

服务层：StaffService 提供员工列表、分页、过滤、增删改查等
模型层：Department、Staff、Assessment、AssessmentDetail、SalaryRecord、PerformancePlan、Indicator、User、Menu、IndicatorTemplate 等

classDiagram
class StaffService {
+get_list(...)
+get_by_id(...)
+get_by_employee_id(...)
+create(...)
+update(...)
+delete(...)
+get_by_department(...)
}
class Department {
+id
+name
+code
+dept_type
+parent_id
+level
+sort_order
+is_active
+description
+created_at
+updated_at
}
class Staff {
+id
+employee_id
+name
+department_id
+position
+title
+phone
+email
+base_salary
+performance_ratio
+status
+hire_date
+created_at
+updated_at
}
Staff --> Department : "属于"

图表来源

章节来源

前端应用初始化与路由守卫

初始化：创建 Vue 应用、注册 Element Plus、Pinia、路由，挂载到 #app
路由：登录页与主布局子路由，面包屑标题动态设置
守卫：未登录且访问非登录页重定向至登录

sequenceDiagram
participant Browser as "浏览器"
participant App as "Vue 应用"
participant Router as "路由"
participant Store as "Pinia Store"
participant API as "后端 API"
Browser->>App : "加载 main.js"
App->>Router : "use(router)"
App->>Store : "use(pinia)"
App->>App : "mount('#app')"
Browser->>Router : "访问 / 或受保护路由"
Router->>Store : "读取 token"
alt 无 token
Router-->>Browser : "重定向 /login"
else 有 token
Router-->>Browser : "放行"
end

图表来源

章节来源

状态管理与 HTTP 封装

用户状态：登录、获取用户信息、登出（维护 token 与本地存储）
应用状态：侧边栏折叠、科室树加载
HTTP 封装：axios 实例、请求头携带 Bearer Token、响应统一错误提示与 401 自动登出

flowchart TD
A["用户登录"] --> B["保存 token 到 localStorage"]
B --> C["store.user.login()"]
C --> D["api.request 发起请求"]
D --> E{"响应 code == 200 ?"}
E --> |是| F["返回数据"]
E --> |否| G["Element Plus 错误提示"]
D --> H{"HTTP 401 ?"}
H --> |是| I["清除 token 并跳转登录"]
H --> |否| J["其他错误处理"]

图表来源

章节来源

开发代理与跨域处理

Vite 代理：将 /api 前缀请求代理到 http://localhost:8000
CORS：后端配置允许前端开发地址（如 3000/5173）

章节来源

依赖关系分析

后端依赖
- FastAPI、Uvicorn、SQLAlchemy 2.0、asyncpg、Pydantic、Pydantic Settings、Passlib、python-dotenv、httpx、pytest
前端依赖
- Vue 3、Vue Router、Pinia、Axios、Element Plus、@element-plus/icons-vue、ECharts、Day.js、Vite

graph LR
subgraph "后端依赖"
R_fastapi["fastapi"]
R_sql["sqlalchemy >= 2.0"]
R_asyncpg["asyncpg"]
R_pyd["pydantic-settings"]
R_pass["passlib[bcrypt]"]
R_httpx["httpx"]
R_uv["uvicorn"]
end
subgraph "前端依赖"
F_vue["vue"]
F_router["vue-router"]
F_pinia["pinia"]
F_axios["axios"]
F_elplus["element-plus"]
F_vite["vite"]
end

图表来源

章节来源

性能考虑

数据库连接池：通过配置项设置连接池大小与溢出数量，避免高并发下的连接争用
异步 I/O：使用 SQLAlchemy 异步引擎与会话，提升并发吞吐
分页与索引：服务层对列表查询使用分页与排序，模型层建立常用查询索引
前端缓存：Pinia Store 缓存用户与科室树，减少重复请求
日志与监控：后端记录异常日志，结合外部日志系统进行追踪

故障排查指南

健康检查
- 访问 /health 确认后端运行状态与版本
CORS 问题
- 确认前端开发端口在后端 CORS 允许列表中
- 确认代理配置正确（/api → 8000）
认证失败
- 检查 token 是否存在与有效
- 查看 401 自动登出逻辑与错误提示
数据库连接
- 检查 DATABASE_URL、连接池配置与 PostgreSQL 可达性
异常定位
- 查看后端日志与异常处理器输出，结合请求方法与 URL 进行定位

章节来源

结论

本系统采用清晰的分层架构与前后端分离模式，后端以 FastAPI 为核心，结合 SQLAlchemy 异步 ORM 与 Pydantic 校验，提供稳定可靠的接口能力；前端以 Vue 3 为基础，配合 Pinia 与 Axios，构建现代化的交互体验。通过统一的 API 前缀、CORS 配置与开发代理，确保跨域与开发效率。建议在生产环境中进一步完善鉴权、限流、审计与监控体系。

附录

启动顺序建议
- 后端：启动 Uvicorn 服务（main.py 中的 if name 主入口）
- 前端：启动 Vite 开发服务器（package.json scripts dev）
常用命令
- 后端：uvicorn --reload app.main:app --host 0.0.0.0 --port 8000
- 前端：npm run dev

16 KiB Raw Blame History Unescape Escape

整体架构设计

目录

引言

项目结构

核心组件

架构总览

详细组件分析

后端应用实例与中间件

配置中心与数据库层

业务服务层与模型

前端应用初始化与路由守卫

状态管理与 HTTP 封装

开发代理与跨域处理

依赖关系分析

性能考虑

故障排查指南

结论

附录

16 KiB

Raw Blame History