# 技术栈选型
**本文档引用的文件**
- [backend/requirements.txt](file://backend/requirements.txt)
- [frontend/package.json](file://frontend/package.json)
- [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/models/models.py](file://backend/app/models/models.py)
- [backend/alembic/env.py](file://backend/alembic/env.py)
- [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/views/Dashboard.vue](file://frontend/src/views/Dashboard.vue)
- [frontend/src/assets/main.scss](file://frontend/src/assets/main.scss)
- [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)
## 目录
1. [引言](#引言)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概览](#架构概览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考量](#性能考量)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
## 引言
本技术栈选型文档面向医院绩效系统，系统采用前后端分离架构：后端基于 Python 的 FastAPI + SQLAlchemy 2.0 + PostgreSQL，前端基于 Vue 3 + Element Plus + ECharts，构建工具采用 Vite。本文档从性能特征、社区支持度与长期维护性三个维度，系统阐述技术栈选择的理由，并结合代码实现细节进行验证。
## 项目结构
项目采用典型的前后端分离目录组织方式：
- 后端：Python 项目，包含 API 路由、核心配置、数据库模型与 Alembic 迁移等模块
- 前端：Vue 3 单页应用，包含路由、状态管理、视图组件与样式资源
- 文档：系统架构、数据库设计、前后端接口等文档
```mermaid
graph TB
subgraph "后端"
A["FastAPI 应用
app/main.py"]
B["核心配置
app/core/config.py"]
C["数据库引擎
app/core/database.py"]
D["数据模型
app/models/models.py"]
E["API 路由
app/api/v1/*"]
F["服务层
app/services/*"]
G["迁移配置
alembic/env.py"]
end
subgraph "前端"
H["Vite 构建
vite.config.js"]
I["入口应用
src/main.js"]
J["路由配置
src/router/index.js"]
K["视图组件
src/views/*"]
L["全局样式
src/assets/main.scss"]
end
A --> B
A --> C
A --> E
E --> F
F --> C
C --> D
G --> D
H --> I
I --> J
J --> K
I --> L
```
**图表来源**
- [backend/app/main.py](file://backend/app/main.py#L15-L80)
- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L47)
- [backend/app/core/database.py](file://backend/app/core/database.py#L9-L39)
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L438)
- [backend/alembic/env.py](file://backend/alembic/env.py#L10-L65)
- [frontend/vite.config.js](file://frontend/vite.config.js#L1-L22)
- [frontend/src/main.js](file://frontend/src/main.js#L1-L24)
- [frontend/src/router/index.js](file://frontend/src/router/index.js#L1-L116)
**章节来源**
- [backend/app/main.py](file://backend/app/main.py#L15-L80)
- [frontend/vite.config.js](file://frontend/vite.config.js#L1-L22)
## 核心组件
- 后端框架：FastAPI 提供高性能异步 Web 框架，内置 OpenAPI 文档与自动校验，便于构建高质量 API
- ORM 层：SQLAlchemy 2.0 提供异步引擎与声明式映射，支持复杂关系与索引优化
- 数据库：PostgreSQL 支持事务一致性与 JSON/JSONB 字段，满足绩效数据的结构化与半结构化存储需求
- 前端框架：Vue 3 Composition API 提供现代化开发体验与更好的逻辑复用
- UI 生态：Element Plus 提供企业级组件库，覆盖表格、表单、图表等管理场景
- 可视化：ECharts 提供丰富的图表类型，满足多维度数据展示与交互
- 构建工具：Vite 提供快速热更新与高效打包，适配现代前端工程化
**章节来源**
- [backend/requirements.txt](file://backend/requirements.txt#L1-L17)
- [frontend/package.json](file://frontend/package.json#L11-L25)
- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L21)
## 架构概览
系统采用前后端分离架构，后端通过 FastAPI 暴露 REST 接口，前端通过 Axios 发起请求，Vite 提供本地开发代理与构建能力。
```mermaid
graph TB
FE["前端应用
Vue 3 + Element Plus + ECharts"]
VITE["Vite 开发服务器
vite.config.js"]
API["FastAPI 应用
app/main.py"]
DB["PostgreSQL 数据库"]
ORM["SQLAlchemy 2.0
异步引擎"]
FE --> |HTTP 请求| VITE
VITE --> |代理转发| API
API --> ORM
ORM --> DB
```
**图表来源**
- [frontend/vite.config.js](file://frontend/vite.config.js#L14-L20)
- [backend/app/main.py](file://backend/app/main.py#L53-L56)
- [backend/app/core/database.py](file://backend/app/core/database.py#L9-L20)
## 详细组件分析
### 后端技术栈选型分析
- FastAPI 的高性能异步特性
- 应用启动与中间件配置展示了异步应用实例创建、CORS 中间件与健康检查端点
- 异常处理统一记录，便于问题定位与日志审计
- SQLAlchemy 2.0 的对象关系映射能力
- 异步引擎与会话工厂确保并发安全与连接池管理
- 模型定义包含枚举类型、索引与约束，体现业务规则与查询优化
- PostgreSQL 的事务处理与 JSON 支持
- 配置中使用 asyncpg 驱动，支持异步连接
- 模型中多处使用 JSON/JSONB 字段存储结构化配置与参数
```mermaid
classDiagram
class FastAPI应用 {
+创建应用实例()
+注册路由()
+CORS中间件()
+健康检查()
+异常处理()
}
class 异步引擎 {
+create_async_engine()
+连接池配置()
}
class 数据库会话 {
+AsyncSession()
+事务提交()
+回滚处理()
}
class 数据模型 {
+枚举类型()
+索引与约束()
+JSON字段()
}
FastAPI应用 --> 异步引擎 : "使用"
异步引擎 --> 数据库会话 : "创建"
数据库会话 --> 数据模型 : "持久化"
```
**图表来源**
- [backend/app/main.py](file://backend/app/main.py#L15-L77)
- [backend/app/core/database.py](file://backend/app/core/database.py#L9-L39)
- [backend/app/models/models.py](file://backend/app/models/models.py#L117-L146)
**章节来源**
- [backend/app/main.py](file://backend/app/main.py#L15-L77)
- [backend/app/core/database.py](file://backend/app/core/database.py#L9-L39)
- [backend/app/models/models.py](file://backend/app/models/models.py#L117-L146)
### 前端技术栈选型分析
- Vue 3 Composition API 的现代化开发体验
- 入口应用初始化 Pinia、路由与 Element Plus，提供全局组件注册与国际化
- 路由配置采用动态导入与导航守卫，保障页面标题与访问控制
- Element Plus 的 UI 组件生态
- 全局样式覆盖了卡片、表格、搜索栏与状态标签等常用布局
- 图标按需注册，减少包体积
- ECharts 的数据可视化能力
- 仪表盘、趋势图、饼图、柱状图等多种图表类型在仪表板中组合使用
- 图表初始化、选项配置与窗口自适应均在组件内集中处理
```mermaid
sequenceDiagram
participant 浏览器 as "浏览器"
participant Vite as "Vite 代理"
participant 前端 as "Vue 应用"
participant 后端 as "FastAPI"
浏览器->>Vite : 访问 / (开发模式)
Vite-->>浏览器 : 返回前端页面
前端->>后端 : GET /api/v1/auth/login
后端-->>前端 : {access_token}
前端->>后端 : GET /api/v1/staff?page=1&page_size=20
后端-->>前端 : 员工列表数据
前端->>后端 : GET /api/v1/stats/dashboard
后端-->>前端 : 统计与图表数据
前端-->>浏览器 : 渲染仪表板
```
**图表来源**
- [frontend/vite.config.js](file://frontend/vite.config.js#L14-L20)
- [frontend/src/main.js](file://frontend/src/main.js#L12-L21)
- [frontend/src/router/index.js](file://frontend/src/router/index.js#L104-L113)
- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L17-L37)
**章节来源**
- [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/assets/main.scss](file://frontend/src/assets/main.scss#L95-L124)
- [frontend/src/views/Dashboard.vue](file://frontend/src/views/Dashboard.vue#L423-L448)
### 构建工具 Vite 的选择理由
- 开发体验：内置代理与热更新，开发时自动转发 /api 前缀到后端
- 依赖管理：与 Vue 3 生态无缝集成，插件生态完善
- 版本兼容：Vue 3 与 Vite 5.x 均为稳定版本，社区支持度高
**章节来源**
- [frontend/vite.config.js](file://frontend/vite.config.js#L1-L22)
- [frontend/package.json](file://frontend/package.json#L21-L25)
## 依赖分析
后端依赖通过 requirements.txt 明确声明，前端依赖通过 package.json 管理。两者均采用语义化版本控制，保证升级的稳定性与可追踪性。
```mermaid
graph LR
subgraph "后端依赖"
R1["FastAPI"]
R2["SQLAlchemy 2.0"]
R3["asyncpg"]
R4["Alembic"]
R5["Pydantic"]
end
subgraph "前端依赖"
F1["Vue 3"]
F2["Element Plus"]
F3["ECharts"]
F4["Vite"]
end
R1 --> R2
R2 --> R3
R2 --> R4
R1 --> R5
F1 --> F2
F1 --> F3
F4 --> F1
```
**图表来源**
- [backend/requirements.txt](file://backend/requirements.txt#L1-L17)
- [frontend/package.json](file://frontend/package.json#L11-L25)
**章节来源**
- [backend/requirements.txt](file://backend/requirements.txt#L1-L17)
- [frontend/package.json](file://frontend/package.json#L11-L25)
## 性能考量
- 后端性能特征
- 异步 I/O 与连接池：异步引擎与连接池配置提升并发吞吐
- ORM 查询优化：索引与约束定义有助于查询性能
- 事务一致性：PostgreSQL 事务保障数据一致性
- 前端性能特征
- 按需加载：路由与组件动态导入减少首屏体积
- 图表渲染：ECharts 采用 Canvas 渲染，适合大数据量展示
- 样式优化：统一的主题变量与布局样式提升渲染效率
- 社区支持度与长期维护性
- FastAPI、SQLAlchemy、Vue 3、Element Plus、ECharts 均为成熟开源项目，社区活跃，版本迭代稳定
- 依赖版本明确，便于后续升级与安全补丁维护
**章节来源**
- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L21)
- [backend/app/core/database.py](file://backend/app/core/database.py#L9-L20)
- [frontend/src/views/Dashboard.vue](file://frontend/src/views/Dashboard.vue#L423-L448)
- [frontend/src/assets/main.scss](file://frontend/src/assets/main.scss#L15-L26)
## 故障排除指南
- 后端常见问题
- 数据库连接失败：检查 DATABASE_URL 与 asyncpg 驱动安装
- 迁移执行：使用 Alembic 异步迁移配置确保元数据同步
- 异常处理：统一异常记录便于定位问题
- 前端常见问题
- 开发代理：确认 /api 代理指向后端地址
- 路由守卫：登录态失效时重定向至登录页
- 图表渲染：监听窗口 resize 并调用图表 resize 方法
**章节来源**
- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L29)
- [backend/alembic/env.py](file://backend/alembic/env.py#L42-L65)
- [frontend/vite.config.js](file://frontend/vite.config.js#L14-L20)
- [frontend/src/router/index.js](file://frontend/src/router/index.js#L104-L113)
- [frontend/src/views/Dashboard.vue](file://frontend/src/views/Dashboard.vue#L441-L447)
## 结论
本技术栈在性能、功能与可维护性之间取得良好平衡：后端利用 FastAPI 的异步能力与 SQLAlchemy 2.0 的 ORM 能力，结合 PostgreSQL 的事务与 JSON 支持，满足医院绩效系统的高并发与复杂数据建模需求；前端通过 Vue 3 + Element Plus + ECharts 提供现代化的管理界面与强大的数据可视化能力；Vite 则确保了高效的开发与构建体验。整体方案具备良好的社区支持与长期维护性，适合持续演进与扩展。