提交文件
This commit is contained in:
397
.qoder/repowiki/zh/content/项目概述/技术栈.md
Normal file
397
.qoder/repowiki/zh/content/项目概述/技术栈.md
Normal file
@@ -0,0 +1,397 @@
|
||||
# 技术栈
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [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)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
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 应用<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](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["前端应用<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](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 {
|
||||
<<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/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)
|
||||
Reference in New Issue
Block a user