# 技术栈 **本文引用的文件** - [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) ## 目录 1. [简介](#简介) 2. [项目结构](#项目结构) 3. [核心组件](#核心组件) 4. [架构总览](#架构总览) 5. [组件详解](#组件详解) 6. [依赖关系分析](#依赖关系分析) 7. [性能考量](#性能考量) 8. [故障排查指南](#故障排查指南) 9. [结论](#结论) 10. [附录](#附录) ## 简介本项目为医院绩效管理系统，采用前后端分离架构。后端使用 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 图表 - 文档：系统设计、数据库设计、前后端说明与接口文档 ```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/__init__.py"] F["Alembic 迁移环境
alembic/env.py"] G["Alembic 配置
alembic.ini"] end subgraph "前端" H["Vite 构建与代理
vite.config.js"] I["入口应用
src/main.js"] J["路由配置
src/router/index.js"] K["状态管理(Pinia)
src/stores/*"] end A --> B A --> E A --> C C --> D F --> D H --> A I --> J I --> K ``` 图表来源 - [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#L1-L438) - [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py#L1-L17) - [backend/alembic/env.py](file://backend/alembic/env.py#L1-L66) - [backend/alembic.ini](file://backend/alembic.ini#L1-L44) - [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) - [frontend/src/stores/index.js](file://frontend/src/stores/index.js#L1-L3) 章节来源 - [backend/app/main.py](file://backend/app/main.py#L1-L92) - [frontend/vite.config.js](file://frontend/vite.config.js#L1-L22) ## 核心组件 - 后端核心 - 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](file://backend/requirements.txt#L1-L17) - [frontend/package.json](file://frontend/package.json#L1-L27) - [backend/app/core/config.py](file://backend/app/core/config.py#L9-L47) - [backend/app/main.py](file://backend/app/main.py#L15-L80) - [frontend/src/main.js](file://frontend/src/main.js#L1-L24) ## 架构总览系统采用前后端分离架构，前端通过 Axios 发起请求，后端提供 RESTful API，数据库通过 SQLAlchemy 异步访问，迁移通过 Alembic 管理。 ```mermaid graph TB FE["前端应用
Vue 3 + Element Plus + ECharts + Pinia"] RT["路由
Vue Router"] ST["状态管理
Pinia Store"] AX["HTTP 客户端
Axios"] API["后端 API
FastAPI"] DB["数据库
PostgreSQL"] AS["异步引擎
SQLAlchemy 2.0"] AL["迁移
Alembic"] FE --> RT FE --> ST FE --> AX AX --> API API --> AS AS --> DB API --> AL ``` 图表来源 - [frontend/src/router/index.js](file://frontend/src/router/index.js#L1-L116) - [frontend/src/stores/user.js](file://frontend/src/stores/user.js#L1-L49) - [frontend/src/main.js](file://frontend/src/main.js#L1-L24) - [backend/app/main.py](file://backend/app/main.py#L15-L80) - [backend/app/core/database.py](file://backend/app/core/database.py#L9-L39) - [backend/alembic/env.py](file://backend/alembic/env.py#L42-L54) ## 组件详解 ### 后端技术栈与实现要点 - FastAPI 应用与中间件 - 应用实例创建、CORS 中间件、异常处理、健康检查端点 - 文档地址与 API 前缀统一管理 - 配置管理 - 使用 Pydantic Settings 加载 .env，集中管理数据库、JWT、跨域、分页等配置 - 数据库与 ORM - 异步引擎与会话工厂，自动事务提交/回滚/关闭 - 模型定义覆盖科室、员工、指标、考核、工资、计划、菜单、模板等业务实体 - API 路由 - v1 版本路由聚合，包含认证、基础数据、考核、工资、统计、财务、计划、菜单、模板等模块 - 迁移与版本控制 - Alembic 异步迁移环境，支持离线/在线模式，基于配置加载数据库元数据 ```mermaid classDiagram class Settings { +APP_NAME +DATABASE_URL +SECRET_KEY +CORS_ORIGINS +API_PREFIX } class DatabaseEngine { +create_async_engine() +async_sessionmaker() } class 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/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/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#L1-L438) - [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py#L1-L17) ### 前端技术栈与实现要点 - 应用入口与插件 - Vue 3 应用挂载、Pinia、Vue Router、Element Plus 国际化与全局注册图标 - 路由与导航 - 基于 Vue Router 的历史模式路由，动态导入视图组件，路由守卫校验登录态 - 状态管理 - Pinia Store 导出用户相关状态与方法，持久化 Token 与用户信息 - 构建与开发 - Vite 作为构建工具，本地开发服务器端口与后端 API 代理配置 ```mermaid 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/router/index.js](file://frontend/src/router/index.js#L104-L113) - [frontend/src/stores/user.js](file://frontend/src/stores/user.js#L11-L31) - [frontend/src/main.js](file://frontend/src/main.js#L19-L21) 章节来源 - [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/stores/index.js](file://frontend/src/stores/index.js#L1-L3) - [frontend/src/stores/user.js](file://frontend/src/stores/user.js#L1-L49) ### 数据模型与关系系统数据模型围绕“科室—员工—指标—考核—工资—计划—模板—菜单”等核心实体展开，采用 SQLAlchemy 2.0 的声明式映射与异步引擎，支持复杂查询与关系映射。 ```mermaid 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 : "父子关系" ``` 图表来源 - [backend/app/models/models.py](file://backend/app/models/models.py#L62-L438) 章节来源 - [backend/app/models/models.py](file://backend/app/models/models.py#L1-L438) ## 依赖关系分析 - 后端依赖 - 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 ```mermaid 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 ``` 图表来源 - [backend/requirements.txt](file://backend/requirements.txt#L1-L17) - [frontend/package.json](file://frontend/package.json#L1-L27) 章节来源 - [backend/requirements.txt](file://backend/requirements.txt#L1-L17) - [frontend/package.json](file://frontend/package.json#L1-L27) ## 性能考量 - 异步优先 - 后端使用 SQLAlchemy 2.0 异步引擎与 FastAPI 异步特性，提升高并发下的吞吐与资源利用率 - 数据库连接池 - 通过配置连接池大小与溢出数量，平衡并发与资源占用 - 前端按需加载 - 路由动态导入与组件懒加载，减少首屏体积与加载时间 - 构建优化 - Vite 提供快速冷启动与热更新，生产构建进行 Tree Shaking 与压缩 - API 文档与调试 - 自动生成 OpenAPI 文档，便于联调与问题定位 ## 故障排查指南 - 后端常见问题 - 数据库连接失败：检查数据库 URL、驱动安装与网络连通性 - 迁移执行异常：确认 Alembic 配置与异步迁移环境正确 - CORS 跨域错误：核对允许源与请求头配置 - 前端常见问题 - 接口 404/跨域：检查 Vite 代理配置与后端 API 前缀 - 登录后无法跳转：检查路由守卫逻辑与 Token 存储 - 日志与监控 - 后端日志输出与异常捕获有助于定位问题 - 前端控制台与网络面板用于排查接口与路由问题章节来源 - [backend/app/main.py](file://backend/app/main.py#L58-L75) - [frontend/vite.config.js](file://frontend/vite.config.js#L12-L20) - [frontend/src/router/index.js](file://frontend/src/router/index.js#L104-L113) ## 结论本项目在后端采用 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 异步迁移，生产环境谨慎操作并备份章节来源 - [backend/requirements.txt](file://backend/requirements.txt#L1-L17) - [frontend/package.json](file://frontend/package.json#L1-L27) - [backend/app/core/config.py](file://backend/app/core/config.py#L18-L33) - [frontend/vite.config.js](file://frontend/vite.config.js#L12-L20) - [backend/alembic.ini](file://backend/alembic.ini#L7-L7)