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/requirements.txt](file://backend/requirements.txt) - [frontend/src/main.js](file://frontend/src/main.js) - [frontend/package.json](file://frontend/package.json) - [frontend/vite.config.js](file://frontend/vite.config.js) - [frontend/src/router/index.js](file://frontend/src/router/index.js) - [frontend/src/stores/user.js](file://frontend/src/stores/user.js) - [docs/backend.md](file://docs/backend.md)

简介

本系统为“医院绩效管理系统”，采用前后端分离架构，后端基于 FastAPI + SQLAlchemy 2.0 + PostgreSQL 的现代化技术栈，前端基于 Vue 3 + Pinia + Element Plus，提供绩效计划、指标模板、员工与科室管理、考核记录、统计分析、薪酬计算与财务核算等核心功能模块。系统通过异步 I/O 和数据库连接池提升并发能力，并通过统一的 API 前缀与跨域策略实现前后端协同。

项目结构

系统分为后端与前端两大子工程，分别位于 backend 与 frontend 目录。后端使用 FastAPI 提供 REST API，按功能模块划分 v1 子路由；前端使用 Vite 构建，通过 Vue Router 实现页面路由，Pinia 管理全局状态，Axios 发起请求并通过代理转发到后端。

graph TB
subgraph "前端(Frontend)"
FE_Main["frontend/src/main.js"]
FE_Router["frontend/src/router/index.js"]
FE_Store["frontend/src/stores/user.js"]
FE_Vite["frontend/vite.config.js"]
end
subgraph "后端(Backend)"
BE_App["backend/app/main.py"]
BE_Config["backend/app/core/config.py"]
BE_DB["backend/app/core/database.py"]
BE_API_Init["backend/app/api/v1/__init__.py"]
BE_Auth["backend/app/api/v1/auth.py"]
BE_StaffSvc["backend/app/services/staff_service.py"]
BE_Req["backend/requirements.txt"]
end
FE_Main --> FE_Router
FE_Main --> FE_Store
FE_Vite --> BE_App
FE_Router --> FE_Store
FE_Store --> BE_Auth
BE_App --> BE_API_Init
BE_API_Init --> BE_Auth
BE_App --> BE_DB
BE_DB --> BE_Config
BE_Req --> BE_App

图表来源

章节来源

核心组件

后端应用实例与中间件
- 应用创建、CORS 中间件、健康检查端点、异常处理器均在后端入口集中配置，确保统一的系统行为与可观测性。
配置中心
- 使用 pydantic-settings 管理应用名称、版本、API 前缀、数据库连接串、JWT 密钥与过期时间、跨域白名单、分页参数等。
数据库层
- 异步 SQLAlchemy 引擎与会话工厂，支持连接池与自动回滚/提交，提供统一的依赖注入接口。
API 路由聚合
- v1 路由聚合器统一注册认证、员工、科室、指标、考核、薪酬、统计、财务、计划、菜单、模板等模块路由。
业务服务层
- 以 StaffService 为代表的典型服务层，封装查询、分页、条件过滤、增删改等操作，保证领域逻辑复用与清晰职责。
前端应用
- Vue 3 应用初始化、Pinia 状态管理、Element Plus UI、路由守卫与本地存储鉴权，Vite 开发服务器与代理配置。
前端状态与路由
- 用户登录状态持久化、路由守卫拦截未登录访问、API 请求通过 Axios 发起并与后端统一前缀对接。

章节来源

架构总览

系统采用前后端分离与模块化 API 设计，后端以 FastAPI 为核心，提供 REST 接口；前端通过 Axios 与后端交互，使用 Vue Router 管理页面导航，Pinia 管理用户态与全局状态。数据库采用 PostgreSQL，配合 SQLAlchemy 2.0 异步 ORM 与 Alembic 迁移工具，保障数据一致性与演进能力。

graph TB
Client["浏览器/客户端"]
FE["前端应用<br/>Vue 3 + Pinia + Element Plus"]
Proxy["Vite 开发代理<br/>/api -> 后端"]
API["FastAPI 应用<br/>路由聚合 + 中间件"]
DB["PostgreSQL 数据库"]
ORM["SQLAlchemy 2.0 异步 ORM"]
Client --> FE
FE --> Proxy
Proxy --> API
API --> ORM
ORM --> DB

图表来源

详细组件分析

后端应用与中间件

应用创建与文档
- 通过工厂函数创建 FastAPI 实例，设置标题、版本、OpenAPI 文档路径与描述，便于自动生成 API 文档。
CORS 与路由
- 注册 CORS 中间件与统一 API 前缀，include_router 将 v1 路由聚合器挂载至指定前缀。
异常处理
- 全局注册 HTTP 异常、请求校验异常与通用异常处理器，统一记录日志并向上抛出，便于调试与监控。
健康检查
- 提供 /health 端点返回系统状态与版本信息，便于容器编排与运维监控。

sequenceDiagram
participant C as "客户端"
participant F as "前端(Vite代理)"
participant A as "FastAPI应用"
participant R as "路由(v1)"
participant S as "服务层"
participant D as "数据库"
C->>F : "GET /api/v1/...示例"
F->>A : "转发请求"
A->>R : "路由匹配"
R->>S : "调用业务方法"
S->>D : "异步查询/写入"
D-->>S : "结果集"
S-->>R : "业务结果"
R-->>A : "响应对象"
A-->>F : "HTTP 响应"
F-->>C : "返回数据"

图表来源

章节来源

backend/app/main.py

配置与数据库层

配置项
- 应用名称、版本、API 前缀、数据库连接串、连接池大小、JWT 签发与过期、跨域白名单、默认/最大分页大小等。
数据库引擎与会话
- 异步引擎与会话工厂，提供 get_db 依赖，自动 commit/rollback/关闭，简化事务管理与资源释放。

flowchart TD
Start(["应用启动"]) --> LoadCfg["加载配置(Settings)"]
LoadCfg --> CreateEngine["创建异步引擎"]
CreateEngine --> CreateSession["创建会话工厂"]
CreateSession --> ProvideDep["提供 get_db 依赖"]
ProvideDep --> End(["服务可用"])

图表来源

章节来源

API 路由与认证

路由聚合
- v1 路由聚合器统一 include 各模块路由，便于扩展与维护。
认证模块
- 提供登录、注册、当前用户信息等接口，使用依赖注入获取数据库会话，结合安全工具进行密码校验与令牌签发。

sequenceDiagram
participant U as "用户"
participant FR as "前端路由"
participant AU as "认证路由"
participant DB as "数据库"
participant SEC as "安全工具"
U->>FR : "提交登录表单"
FR->>AU : "POST /api/v1/auth/login"
AU->>DB : "查询用户"
DB-->>AU : "用户记录"
AU->>SEC : "校验密码"
SEC-->>AU : "校验结果"
AU-->>FR : "返回访问令牌"
FR-->>U : "跳转首页/保存令牌"

图表来源

章节来源

服务层与数据访问

服务层职责
- 封装复杂查询、分页与条件组合，避免在路由层直接编写 SQL，提升可测试性与可维护性。
典型流程
- 列表查询：构造查询条件 → 统计总数 → 分页排序 → 返回数据与总数。

flowchart TD
QStart(["进入服务方法"]) --> Build["构建查询条件"]
Build --> Count["统计总数(subquery)"]
Count --> Page["分页与排序"]
Page --> Exec["执行查询"]
Exec --> Ret["返回结果与总数"]

图表来源

backend/app/services/staff_service.py

章节来源

backend/app/services/staff_service.py

前端应用与状态管理

应用初始化
- 注册 Pinia、路由、Element Plus 与本地化，挂载应用根组件。
路由与守卫
- 定义多级菜单路由，使用 beforeEach 守卫判断本地 token 并重定向至登录页。
状态管理
- 用户 store 管理 token 与用户信息，提供登录、获取用户信息、登出方法，登出时清理本地存储并跳转登录页。
开发代理
- Vite 将 /api 前缀代理到后端地址，解决开发阶段跨域问题。

sequenceDiagram
participant V as "Vue 应用"
participant R as "路由守卫"
participant S as "用户store"
participant A as "认证API"
V->>R : "导航到受保护页面"
R->>S : "读取localStorage.token"
alt 无token
R-->>V : "重定向到 /login"
else 有token
R-->>V : "放行"
V->>S : "调用 getUserInfo()"
S->>A : "GET /api/v1/auth/me"
A-->>S : "返回用户信息"
end

图表来源

章节来源

依赖分析

后端技术栈
- FastAPI、SQLAlchemy 2.0、Pydantic、Alembic、asyncpg、uvicorn、passlib、python-jose 等，构成高性能、强类型、可演进的后端基础设施。
前端技术栈
- Vue 3、Vue Router、Pinia、Axios、Element Plus、Vite，提供现代化的交互体验与开发效率。
外部依赖关系
- 前端通过 /api 前缀代理访问后端；后端通过 asyncpg 连接 PostgreSQL；配置中心统一管理数据库连接串与 JWT 参数。

graph LR
FE["前端依赖(package.json)"] --> AX["Axios"]
FE --> VR["Vue Router"]
FE --> PI["Pinia"]
FE --> EP["Element Plus"]
BE["后端依赖(requirements.txt)"] --> FA["FastAPI"]
BE --> SA["SQLAlchemy 2.0"]
BE --> PG["asyncpg"]
BE --> AL["Alembic"]
BE --> UV["uvicorn"]
BE --> PJ["python-jose"]
BE --> PB["passlib"]
AX --> API["后端API(/api/v1)"]
VR --> API
PI --> API
EP --> FE
API --> PG

图表来源

章节来源

性能考虑

异步 I/O 与连接池
- 使用 SQLAlchemy 2.0 异步引擎与连接池参数，减少阻塞，提升高并发下的吞吐能力。
分页与索引
- 服务层对列表查询进行分页与排序，数据库层通过索引优化常用查询字段，降低查询延迟。
缓存与压缩
- 建议在网关层启用静态资源缓存与 Gzip 压缩，减少带宽占用。
前端懒加载
- 路由与组件采用动态导入，缩短首屏加载时间，提升用户体验。
数据库迁移与版本控制
- 使用 Alembic 管理数据库结构变更，避免生产环境回滚风险。

故障排查指南

后端异常处理
- HTTP 异常、请求校验异常与通用异常均被记录日志并向上抛出，便于定位问题来源。
健康检查
- 通过 /health 端点快速确认服务状态与版本信息。
前端路由守卫
- 未登录访问受保护页面将被重定向至登录页，检查本地存储 token 是否存在。
数据库连接
- 若出现连接失败，检查 DATABASE_URL、连接池参数与数据库服务状态。

章节来源

结论

本系统通过前后端分离与模块化 API 设计，结合 FastAPI 的高性能与强类型特性、Vue 3 的现代开发体验以及 PostgreSQL 的稳定可靠，构建了可扩展、易维护的医院绩效管理平台。建议在生产环境中完善鉴权策略、引入缓存与消息队列、增强监控与日志采集，并持续通过 Alembic 管理数据库演进。

附录

系统边界与集成点
- 系统边界：前端通过 /api 前缀与后端交互；后端仅暴露 REST 接口；数据库为内部存储。
- 集成点：JWT 用于前后端鉴权；Axios 作为 HTTP 客户端；Vite 代理用于开发联调。
架构决策依据
- FastAPI：高性能、自动生成 OpenAPI 文档、强类型校验。
- Vue 3：组合式 API、更好的 TypeScript 支持、生态丰富。
- PostgreSQL：成熟的关系型数据库、异步驱动与迁移工具完善。

16 KiB Raw Blame History Unescape Escape

系统架构

目录

简介

项目结构

核心组件

架构总览

详细组件分析

后端应用与中间件

配置与数据库层

API 路由与认证

服务层与数据访问

前端应用与状态管理

依赖分析

性能考虑

故障排查指南

结论

附录

16 KiB

Raw Blame History