14 KiB
14 KiB
技术栈
**本文引用的文件** - [backend/requirements.txt](file://backend/requirements.txt) - [frontend/package.json](file://frontend/package.json) - [backend/app/core/config.py](file://backend/app/core/config.py) - [backend/app/main.py](file://backend/app/main.py) - [backend/app/core/database.py](file://backend/app/core/database.py) - [backend/alembic/env.py](file://backend/alembic/env.py) - [backend/alembic.ini](file://backend/alembic.ini) - [frontend/vite.config.js](file://frontend/vite.config.js) - [frontend/src/main.js](file://frontend/src/main.js) - [frontend/src/router/index.js](file://frontend/src/router/index.js) - [frontend/src/stores/index.js](file://frontend/src/stores/index.js) - [frontend/src/stores/user.js](file://frontend/src/stores/user.js) - [backend/app/models/models.py](file://backend/app/models/models.py) - [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py)目录
简介
本项目为医院绩效管理系统，采用前后端分离架构。后端使用 Python 3.10+、FastAPI 框架、SQLAlchemy 2.0 ORM、PostgreSQL 数据库以及 Alembic 进行数据库迁移；前端采用 Vue 3、Element Plus、ECharts、Pinia 等现代前端技术栈，配合 Vite 构建工具与 Uvicorn 开发服务器。本文档系统梳理技术选型、版本兼容性、依赖关系与架构设计，并提供可视化图示帮助理解。
项目结构
项目采用“backend + frontend + 文档”三层组织方式：
- 后端：FastAPI 应用、数据库模型与服务层、API 路由、配置与 Alembic 迁移
- 前端：Vue 3 单页应用、路由与 Pinia 状态管理、Element Plus UI 组件库、ECharts 图表
- 文档：系统设计、数据库设计、前后端说明与接口文档
graph TB
subgraph "后端"
A["FastAPI 应用<br/>app/main.py"]
B["配置模块<br/>app/core/config.py"]
C["数据库引擎与会话<br/>app/core/database.py"]
D["模型定义<br/>app/models/models.py"]
E["API 路由聚合<br/>app/api/v1/__init__.py"]
F["Alembic 迁移环境<br/>alembic/env.py"]
G["Alembic 配置<br/>alembic.ini"]
end
subgraph "前端"
H["Vite 构建与代理<br/>vite.config.js"]
I["入口应用<br/>src/main.js"]
J["路由配置<br/>src/router/index.js"]
K["状态管理(Pinia)<br/>src/stores/*"]
end
A --> B
A --> E
A --> C
C --> D
F --> D
H --> A
I --> J
I --> K
图表来源
- backend/app/main.py
- backend/app/core/config.py
- backend/app/core/database.py
- backend/app/models/models.py
- backend/app/api/v1/init.py
- backend/alembic/env.py
- backend/alembic.ini
- frontend/vite.config.js
- frontend/src/main.js
- frontend/src/router/index.js
- frontend/src/stores/index.js
章节来源
核心组件
- 后端核心
- Web 框架：FastAPI（异步支持、自动 OpenAPI 文档）
- ORM：SQLAlchemy 2.0（异步引擎、声明式映射）
- 数据库：PostgreSQL（生产）、SQLite（迁移/测试）
- 迁移：Alembic（异步迁移）
- 认证与安全：Pydantic 设置、JWt、Passlib、CORS
- 服务器：Uvicorn（开发/生产）
- 前端核心
- 框架：Vue 3（组合式 API、响应式系统）
- 路由：Vue Router 4
- 状态：Pinia（轻量状态管理）
- UI：Element Plus（中文化、图标库）
- 图表：ECharts（统计与趋势展示）
- 构建：Vite（快速热更新、按需打包）
章节来源
- backend/requirements.txt
- frontend/package.json
- backend/app/core/config.py
- backend/app/main.py
- frontend/src/main.js
架构总览
系统采用前后端分离架构，前端通过 Axios 发起请求，后端提供 RESTful API，数据库通过 SQLAlchemy 异步访问，迁移通过 Alembic 管理。
graph TB
FE["前端应用<br/>Vue 3 + Element Plus + ECharts + Pinia"]
RT["路由<br/>Vue Router"]
ST["状态管理<br/>Pinia Store"]
AX["HTTP 客户端<br/>Axios"]
API["后端 API<br/>FastAPI"]
DB["数据库<br/>PostgreSQL"]
AS["异步引擎<br/>SQLAlchemy 2.0"]
AL["迁移<br/>Alembic"]
FE --> RT
FE --> ST
FE --> AX
AX --> API
API --> AS
AS --> DB
API --> AL
图表来源
- frontend/src/router/index.js
- frontend/src/stores/user.js
- frontend/src/main.js
- backend/app/main.py
- backend/app/core/database.py
- backend/alembic/env.py
组件详解
后端技术栈与实现要点
- FastAPI 应用与中间件
- 应用实例创建、CORS 中间件、异常处理、健康检查端点
- 文档地址与 API 前缀统一管理
- 配置管理
- 使用 Pydantic Settings 加载 .env，集中管理数据库、JWT、跨域、分页等配置
- 数据库与 ORM
- 异步引擎与会话工厂，自动事务提交/回滚/关闭
- 模型定义覆盖科室、员工、指标、考核、工资、计划、菜单、模板等业务实体
- API 路由
- v1 版本路由聚合，包含认证、基础数据、考核、工资、统计、财务、计划、菜单、模板等模块
- 迁移与版本控制
- Alembic 异步迁移环境，支持离线/在线模式，基于配置加载数据库元数据
classDiagram
class Settings {
+APP_NAME
+DATABASE_URL
+SECRET_KEY
+CORS_ORIGINS
+API_PREFIX
}
class DatabaseEngine {
+create_async_engine()
+async_sessionmaker()
}
class Base {
<<declarative_base>>
}
class Department
class Staff
class Indicator
class Assessment
class AssessmentDetail
class SalaryRecord
class PerformancePlan
class PlanKpiRelation
class Menu
class IndicatorTemplate
class TemplateIndicator
Settings --> DatabaseEngine : "提供连接配置"
DatabaseEngine --> Base : "创建异步引擎"
Base <|-- Department
Base <|-- Staff
Base <|-- Indicator
Base <|-- Assessment
Base <|-- AssessmentDetail
Base <|-- SalaryRecord
Base <|-- PerformancePlan
Base <|-- PlanKpiRelation
Base <|-- Menu
Base <|-- IndicatorTemplate
Base <|-- TemplateIndicator
图表来源
章节来源
- backend/app/main.py
- backend/app/core/config.py
- backend/app/core/database.py
- backend/app/models/models.py
- backend/app/api/v1/init.py
前端技术栈与实现要点
- 应用入口与插件
- Vue 3 应用挂载、Pinia、Vue Router、Element Plus 国际化与全局注册图标
- 路由与导航
- 基于 Vue Router 的历史模式路由，动态导入视图组件，路由守卫校验登录态
- 状态管理
- Pinia Store 导出用户相关状态与方法，持久化 Token 与用户信息
- 构建与开发
- Vite 作为构建工具，本地开发服务器端口与后端 API 代理配置
sequenceDiagram
participant U as "用户"
participant V as "Vue 应用"
participant R as "路由守卫"
participant S as "用户状态(Pinia)"
participant A as "认证API(Axios)"
U->>V : "访问系统"
V->>R : "进入路由"
R->>S : "读取本地Token"
alt "未登录"
R-->>U : "重定向到登录页"
else "已登录"
R-->>V : "放行"
V->>A : "调用登录/获取用户信息"
A-->>S : "写入Token与用户信息"
V-->>U : "渲染页面"
end
图表来源
章节来源
- frontend/src/main.js
- frontend/src/router/index.js
- frontend/src/stores/index.js
- frontend/src/stores/user.js
数据模型与关系
系统数据模型围绕“科室—员工—指标—考核—工资—计划—模板—菜单”等核心实体展开，采用 SQLAlchemy 2.0 的声明式映射与异步引擎，支持复杂查询与关系映射。
erDiagram
DEPARTMENTS ||--o{ STAFF : "属于"
STAFF ||--o{ ASSESSMENTS : "参与"
STAFF ||--o{ SALARY_RECORDS : "产生"
INDICATORS ||--o{ ASSESSMENT_DETAILS : "被考核"
ASSESSMENTS ||--o{ ASSESSMENT_DETAILS : "包含"
PERFORMANCE_PLANS ||--o{ PLAN_KPI_RELATIONS : "关联"
INDICATORS ||--o{ PLAN_KPI_RELATIONS : "被关联"
USERS ||--o{ PERFORMANCE_PLANS : "提交/审批"
DEPARTMENTS ||--o{ PERFORMANCE_PLANS : "归属"
STAFF ||--o{ PERFORMANCE_PLANS : "责任人"
INDICATOR_TEMPLATES ||--o{ TEMPLATE_INDICATORS : "包含"
INDICATORS ||--o{ TEMPLATE_INDICATORS : "被包含"
MENUS ||--o{ MENUS : "父子关系"
图表来源
章节来源
依赖关系分析
- 后端依赖
- Web 框架与服务器：FastAPI、Uvicorn
- ORM 与数据库：SQLAlchemy 2.0、asyncpg（异步 PostgreSQL 驱动）、aiosqlite（异步 SQLite）
- 配置与安全：Pydantic Settings、python-jose、passlib、email-validator、python-dotenv
- 测试与工具：httpx、pytest、pytest-asyncio、Alembic
- 前端依赖
- 框架与生态：Vue 3、Vue Router、Pinia、Axios
- UI 与图标：Element Plus、Element Plus Icons
- 图表与工具：ECharts、Day.js
- 构建与开发：Vite、@vitejs/plugin-vue、Sass
graph LR
subgraph "后端"
RQ["requirements.txt"]
FA["FastAPI"]
UV["Uvicorn"]
SA["SQLAlchemy 2.0"]
AP["asyncpg"]
AI["aiosqlite"]
AL["Alembic"]
PY["Pydantic Settings/JWT/Passlib"]
end
subgraph "前端"
PN["package.json"]
VUE["Vue 3"]
VR["Vue Router"]
PI["Pinia"]
AX["Axios"]
EP["Element Plus"]
IC["Element Plus Icons"]
EC["ECharts"]
DJ["Day.js"]
VI["Vite/@vitejs/plugin-vue"]
end
RQ --> FA
RQ --> UV
RQ --> SA
RQ --> AP
RQ --> AI
RQ --> AL
RQ --> PY
PN --> VUE
PN --> VR
PN --> PI
PN --> AX
PN --> EP
PN --> IC
PN --> EC
PN --> DJ
PN --> VI
图表来源
章节来源
性能考量
- 异步优先
- 后端使用 SQLAlchemy 2.0 异步引擎与 FastAPI 异步特性，提升高并发下的吞吐与资源利用率
- 数据库连接池
- 通过配置连接池大小与溢出数量，平衡并发与资源占用
- 前端按需加载
- 路由动态导入与组件懒加载，减少首屏体积与加载时间
- 构建优化
- Vite 提供快速冷启动与热更新，生产构建进行 Tree Shaking 与压缩
- API 文档与调试
- 自动生成 OpenAPI 文档，便于联调与问题定位
故障排查指南
- 后端常见问题
- 数据库连接失败：检查数据库 URL、驱动安装与网络连通性
- 迁移执行异常：确认 Alembic 配置与异步迁移环境正确
- CORS 跨域错误：核对允许源与请求头配置
- 前端常见问题
- 接口 404/跨域：检查 Vite 代理配置与后端 API 前缀
- 登录后无法跳转：检查路由守卫逻辑与 Token 存储
- 日志与监控
- 后端日志输出与异常捕获有助于定位问题
- 前端控制台与网络面板用于排查接口与路由问题
章节来源
结论
本项目在后端采用 FastAPI + SQLAlchemy 2.0 + PostgreSQL 的现代化异步技术栈，在前端采用 Vue 3 + Element Plus + ECharts + Pinia 的高效开发体验。结合 Alembic 的数据库迁移能力与 Vite 的工程化工具链，整体具备良好的性能、可维护性与扩展性。建议在生产环境中进一步完善数据库索引、缓存策略与安全加固，并持续演进前端组件化与自动化测试。
附录
- 版本与兼容性
- Python 3.10+（后端）
- FastAPI >= 0.115.0
- Uvicorn[standard] >= 0.32.0
- SQLAlchemy >= 2.0.36
- asyncpg >= 0.30.0（异步 PostgreSQL 驱动）
- aiosqlite >= 0.19.0（异步 SQLite 驱动）
- Alembic >= 1.14.0
- Pydantic >= 2.10.0
- Pydantic Settings >= 2.6.0
- Vue >= 3.4.15
- Vue Router >= 4.2.5
- Pinia >= 2.1.7
- Element Plus >= 2.5.3
- ECharts >= 5.4.3
- Vite >= 5.0.11
- 配置与部署要点
- 后端通过 .env 与 Pydantic Settings 管理配置，生产环境务必替换默认密钥与数据库凭据
- 前端开发服务器端口与代理需与后端监听端口一致
- 数据库迁移建议在开发环境使用 Alembic 异步迁移，生产环境谨慎操作并备份
章节来源