提交文件

2026-02-28 15:16:15 +08:00
parent 1a4e50e0a4
commit 44f250f58e
159 changed files with 61268 additions and 0 deletions
--- a/.qoder/repowiki/zh/content/系统架构/整体架构设计.md
+++ b/.qoder/repowiki/zh/content/系统架构/整体架构设计.md
@@ -0,0 +1,432 @@
+# 整体架构设计
+
+<cite>
+**本文引用的文件**
+- [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/app/models/models.py](file://backend/app/models/models.py)
+- [frontend/src/main.js](file://frontend/src/main.js)
+- [frontend/src/router/index.js](file://frontend/src/router/index.js)
+- [frontend/src/stores/user.js](file://frontend/src/stores/user.js)
+- [frontend/src/stores/app.js](file://frontend/src/stores/app.js)
+- [frontend/src/api/request.js](file://frontend/src/api/request.js)
+- [frontend/vite.config.js](file://frontend/vite.config.js)
+- [backend/requirements.txt](file://backend/requirements.txt)
+- [frontend/package.json](file://frontend/package.json)
+</cite>
+
+## 目录
+1. [引言](#引言)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构总览](#架构总览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考虑](#性能考虑)
+8. [故障排查指南](#故障排查指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 引言
+本文件面向“医院绩效系统”的整体架构设计，围绕后端采用 FastAPI 的分层架构与前端 Vue 3 的单页应用（SPA）进行系统化说明。重点涵盖：
+- 分层架构：表现层（前端）、业务逻辑层（后端服务）、数据访问层（SQLAlchemy 异步 ORM）
+- 前后端分离：CORS 配置、API 路由前缀、开发代理与跨域处理
+- 后端应用实例：FastAPI 实例创建、中间件与全局异常处理
+- 前端初始化：应用挂载、路由守卫与状态管理
+- 系统启动流程、健康检查与错误处理策略
+
+## 项目结构
+系统采用前后端分离的工程组织方式：
+- 后端（Python/FastAPI）：app 目录下按功能分层（core、api、models、schemas、services、utils），通过 APIRouter 聚合路由
+- 前端（Vue 3/Pinia/Vite）：src 下按功能模块组织（api、components、router、stores、views），使用 Vite 开发服务器与代理
+
+```mermaid
+graph TB
+subgraph "后端"
+A_main["backend/app/main.py<br/>应用入口与中间件"]
+A_cfg["backend/app/core/config.py<br/>配置中心"]
+A_db["backend/app/core/database.py<br/>异步数据库引擎"]
+A_api["backend/app/api/v1/__init__.py<br/>路由聚合"]
+A_auth["backend/app/api/v1/auth.py<br/>认证路由"]
+A_srv["backend/app/services/*<br/>业务服务层"]
+A_models["backend/app/models/models.py<br/>ORM 模型"]
+end
+subgraph "前端"
+F_main["frontend/src/main.js<br/>应用初始化"]
+F_router["frontend/src/router/index.js<br/>路由与守卫"]
+F_store_user["frontend/src/stores/user.js<br/>用户状态"]
+F_store_app["frontend/src/stores/app.js<br/>应用状态"]
+F_req["frontend/src/api/request.js<br/>HTTP 封装与拦截器"]
+F_vite["frontend/vite.config.js<br/>开发代理"]
+end
+F_main --> F_router
+F_main --> F_store_user
+F_main --> F_store_app
+F_router --> F_req
+F_store_user --> F_req
+F_store_app --> F_req
+F_req --> A_api
+A_main --> A_cfg
+A_main --> A_db
+A_api --> A_auth
+A_auth --> A_srv
+A_srv --> A_models
+```
+
+图表来源
+- [backend/app/main.py](file://backend/app/main.py#L15-L77)
+- [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/api/v1/__init__.py](file://backend/app/api/v1/__init__.py#L1-L17)
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L14-L74)
+- [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py#L13-L112)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L114)
+- [frontend/src/main.js](file://frontend/src/main.js#L12-L24)
+- [frontend/src/router/index.js](file://frontend/src/router/index.js#L98-L116)
+- [frontend/src/stores/user.js](file://frontend/src/stores/user.js#L6-L49)
+- [frontend/src/stores/app.js](file://frontend/src/stores/app.js#L5-L31)
+- [frontend/src/api/request.js](file://frontend/src/api/request.js#L5-L66)
+- [frontend/vite.config.js](file://frontend/vite.config.js#L12-L21)
+
+章节来源
+- [backend/app/main.py](file://backend/app/main.py#L15-L77)
+- [frontend/src/main.js](file://frontend/src/main.js#L12-L24)
+
+## 核心组件
+- 后端应用实例与中间件
+  - 应用实例创建：定义标题、版本、OpenAPI 文档路径前缀，并注册统一 API 前缀
+  - CORS 中间件：允许指定源、凭证、方法与头
+  - 路由注册：include_router 并设置 API 前缀
+  - 健康检查：提供 /health 接口返回系统状态与版本
+  - 全局异常处理：HTTP 异常、请求验证异常与通用异常的日志与抛出
+- 配置中心
+  - 应用名、版本、调试开关、API 前缀
+  - 数据库连接串、连接池大小
+  - JWT 密钥、算法、过期时间
+  - CORS 允许源列表
+  - 分页默认与最大页大小
+- 数据库层
+  - 异步引擎与会话工厂
+  - 基类与依赖注入 get_db
+- 前端应用初始化
+  - 创建 Vue 应用、注册 Element Plus、Pinia、路由
+  - 挂载到 DOM
+- 路由与守卫
+  - 定义登录页与主布局子路由
+  - beforeEach 守卫：读取本地 token，未登录跳转登录
+- 状态管理
+  - Pinia Store：用户登录态与信息、应用侧边栏与科室树
+- HTTP 封装与拦截器
+  - axios 实例：baseURL 为 /api/v1
+  - 请求拦截：自动附加 Bearer Token
+  - 响应拦截：统一错误提示与 401 自动登出
+- 开发代理
+  - Vite 代理 /api → 后端 8000 端口，解决开发时跨域问题
+
+章节来源
+- [backend/app/main.py](file://backend/app/main.py#L15-L77)
+- [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)
+- [frontend/src/main.js](file://frontend/src/main.js#L12-L24)
+- [frontend/src/router/index.js](file://frontend/src/router/index.js#L98-L116)
+- [frontend/src/stores/user.js](file://frontend/src/stores/user.js#L6-L49)
+- [frontend/src/stores/app.js](file://frontend/src/stores/app.js#L5-L31)
+- [frontend/src/api/request.js](file://frontend/src/api/request.js#L5-L66)
+- [frontend/vite.config.js](file://frontend/vite.config.js#L12-L21)
+
+## 架构总览
+系统采用典型的三层架构与前后端分离模式：
+- 表现层（前端）：Vue 3 SPA，通过 axios 访问后端 API
+- 业务逻辑层（后端）：FastAPI 路由与服务层，封装领域业务
+- 数据访问层（后端）：SQLAlchemy 异步 ORM，提供模型与查询能力
+
+```mermaid
+graph TB
+FE["前端 Vue 3<br/>src/main.js"] --> RT["路由守卫<br/>router/index.js"]
+FE --> ST["状态管理<br/>stores/user.js, app.js"]
+FE --> AX["HTTP 封装<br/>api/request.js"]
+AX --> API["后端 API 路由<br/>api/v1/*"]
+API --> SRV["服务层<br/>services/*"]
+SRV --> DB["数据库层<br/>models + database.py"]
+DB --> PG["PostgreSQL"]
+subgraph "后端"
+MAIN["FastAPI 应用<br/>main.py"]
+CFG["配置中心<br/>config.py"]
+CORS["CORS 中间件"]
+HEALTH["健康检查 /health"]
+end
+FE --> MAIN
+MAIN --> CORS
+MAIN --> API
+MAIN --> CFG
+MAIN --> HEALTH
+```
+
+图表来源
+- [frontend/src/main.js](file://frontend/src/main.js#L12-L24)
+- [frontend/src/router/index.js](file://frontend/src/router/index.js#L98-L116)
+- [frontend/src/stores/user.js](file://frontend/src/stores/user.js#L6-L49)
+- [frontend/src/stores/app.js](file://frontend/src/stores/app.js#L5-L31)
+- [frontend/src/api/request.js](file://frontend/src/api/request.js#L5-L66)
+- [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py#L1-L17)
+- [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py#L13-L112)
+- [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-L114)
+- [backend/app/main.py](file://backend/app/main.py#L15-L77)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L47)
+
+## 详细组件分析
+
+### 后端应用实例与中间件
+- 应用创建：设置应用元信息、OpenAPI 文档路径、API 前缀
+- CORS：允许指定源、凭证、通配方法与头
+- 路由注册：include_router 并使用统一前缀
+- 健康检查：/health 返回系统状态与版本
+- 异常处理：HTTP、验证、通用异常分别记录日志并抛出
+
+```mermaid
+sequenceDiagram
+participant Client as "客户端"
+participant FastAPI as "FastAPI 应用"
+participant Router as "API 路由"
+participant Service as "服务层"
+participant DB as "数据库"
+Client->>FastAPI : "GET /api/v1/health"
+FastAPI-->>Client : "{status : healthy, version}"
+Client->>FastAPI : "POST /api/v1/auth/login"
+FastAPI->>Router : "转发到 auth 路由"
+Router->>Service : "调用认证服务"
+Service->>DB : "查询用户并校验密码"
+DB-->>Service : "返回用户信息"
+Service-->>Router : "生成访问令牌"
+Router-->>Client : "返回 Token"
+```
+
+图表来源
+- [backend/app/main.py](file://backend/app/main.py#L15-L77)
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L17-L37)
+
+章节来源
+- [backend/app/main.py](file://backend/app/main.py#L15-L77)
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L17-L37)
+
+### 配置中心与数据库层
+- 配置项：应用名、版本、API 前缀、数据库 URL、JWT、CORS、分页等
+- 数据库：异步引擎、会话工厂、依赖注入 get_db；模型继承 Base
+
+```mermaid
+flowchart TD
+Start(["启动"]) --> LoadCfg["加载配置<br/>config.py"]
+LoadCfg --> InitEngine["创建异步引擎<br/>database.py"]
+InitEngine --> InitSession["创建会话工厂<br/>database.py"]
+InitSession --> Ready(["就绪"])
+```
+
+图表来源
+- [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/core/config.py](file://backend/app/core/config.py#L9-L47)
+- [backend/app/core/database.py](file://backend/app/core/database.py#L9-L39)
+
+### 业务服务层与模型
+- 服务层：StaffService 提供员工列表、分页、过滤、增删改查等
+- 模型层：Department、Staff、Assessment、AssessmentDetail、SalaryRecord、PerformancePlan、Indicator、User、Menu、IndicatorTemplate 等
+
+```mermaid
+classDiagram
+class StaffService {
+get_list(...)
+get_by_id(...)
+get_by_employee_id(...)
+create(...)
+update(...)
+delete(...)
+get_by_department(...)
+}
+class Department {
+id
+name
+code
+dept_type
+parent_id
+level
+sort_order
+is_active
+description
+created_at
+updated_at
+}
+class Staff {
+id
+employee_id
+name
+department_id
+position
+title
+phone
+email
+base_salary
+performance_ratio
+status
+hire_date
+created_at
+updated_at
+}
+Staff --> Department : "属于"
+```
+
+图表来源
+- [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py#L13-L112)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L114)
+
+章节来源
+- [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py#L13-L112)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L114)
+
+### 前端应用初始化与路由守卫
+- 初始化：创建 Vue 应用、注册 Element Plus、Pinia、路由，挂载到 #app
+- 路由：登录页与主布局子路由，面包屑标题动态设置
+- 守卫：未登录且访问非登录页重定向至登录
+
+```mermaid
+sequenceDiagram
+participant Browser as "浏览器"
+participant App as "Vue 应用"
+participant Router as "路由"
+participant Store as "Pinia Store"
+participant API as "后端 API"
+Browser->>App : "加载 main.js"
+App->>Router : "use(router)"
+App->>Store : "use(pinia)"
+App->>App : "mount('#app')"
+Browser->>Router : "访问 / 或受保护路由"
+Router->>Store : "读取 token"
+alt 无 token
+Router-->>Browser : "重定向 /login"
+else 有 token
+Router-->>Browser : "放行"
+end
+```
+
+图表来源
+- [frontend/src/main.js](file://frontend/src/main.js#L12-L24)
+- [frontend/src/router/index.js](file://frontend/src/router/index.js#L98-L116)
+- [frontend/src/stores/user.js](file://frontend/src/stores/user.js#L6-L49)
+
+章节来源
+- [frontend/src/main.js](file://frontend/src/main.js#L12-L24)
+- [frontend/src/router/index.js](file://frontend/src/router/index.js#L98-L116)
+- [frontend/src/stores/user.js](file://frontend/src/stores/user.js#L6-L49)
+
+### 状态管理与 HTTP 封装
+- 用户状态：登录、获取用户信息、登出（维护 token 与本地存储）
+- 应用状态：侧边栏折叠、科室树加载
+- HTTP 封装：axios 实例、请求头携带 Bearer Token、响应统一错误提示与 401 自动登出
+
+```mermaid
+flowchart TD
+A["用户登录"] --> B["保存 token 到 localStorage"]
+B --> C["store.user.login()"]
+C --> D["api.request 发起请求"]
+D --> E{"响应 code == 200 ?"}
+E --> |是| F["返回数据"]
+E --> |否| G["Element Plus 错误提示"]
+D --> H{"HTTP 401 ?"}
+H --> |是| I["清除 token 并跳转登录"]
+H --> |否| J["其他错误处理"]
+```
+
+图表来源
+- [frontend/src/stores/user.js](file://frontend/src/stores/user.js#L10-L20)
+- [frontend/src/api/request.js](file://frontend/src/api/request.js#L14-L63)
+
+章节来源
+- [frontend/src/stores/user.js](file://frontend/src/stores/user.js#L6-L49)
+- [frontend/src/api/request.js](file://frontend/src/api/request.js#L5-L66)
+
+### 开发代理与跨域处理
+- Vite 代理：将 /api 前缀请求代理到 http://localhost:8000
+- CORS：后端配置允许前端开发地址（如 3000/5173）
+
+章节来源
+- [frontend/vite.config.js](file://frontend/vite.config.js#L12-L21)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L28-L29)
+- [backend/app/main.py](file://backend/app/main.py#L41-L48)
+
+## 依赖关系分析
+- 后端依赖
+  - FastAPI、Uvicorn、SQLAlchemy 2.0、asyncpg、Pydantic、Pydantic Settings、Passlib、python-dotenv、httpx、pytest
+- 前端依赖
+  - Vue 3、Vue Router、Pinia、Axios、Element Plus、@element-plus/icons-vue、ECharts、Day.js、Vite
+
+```mermaid
+graph LR
+subgraph "后端依赖"
+R_fastapi["fastapi"]
+R_sql["sqlalchemy >= 2.0"]
+R_asyncpg["asyncpg"]
+R_pyd["pydantic-settings"]
+R_pass["passlib[bcrypt]"]
+R_httpx["httpx"]
+R_uv["uvicorn"]
+end
+subgraph "前端依赖"
+F_vue["vue"]
+F_router["vue-router"]
+F_pinia["pinia"]
+F_axios["axios"]
+F_elplus["element-plus"]
+F_vite["vite"]
+end
+```
+
+图表来源
+- [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：使用 SQLAlchemy 异步引擎与会话，提升并发吞吐
+- 分页与索引：服务层对列表查询使用分页与排序，模型层建立常用查询索引
+- 前端缓存：Pinia Store 缓存用户与科室树，减少重复请求
+- 日志与监控：后端记录异常日志，结合外部日志系统进行追踪
+
+## 故障排查指南
+- 健康检查
+  - 访问 /health 确认后端运行状态与版本
+- CORS 问题
+  - 确认前端开发端口在后端 CORS 允许列表中
+  - 确认代理配置正确（/api → 8000）
+- 认证失败
+  - 检查 token 是否存在与有效
+  - 查看 401 自动登出逻辑与错误提示
+- 数据库连接
+  - 检查 DATABASE_URL、连接池配置与 PostgreSQL 可达性
+- 异常定位
+  - 查看后端日志与异常处理器输出，结合请求方法与 URL 进行定位
+
+章节来源
+- [backend/app/main.py](file://backend/app/main.py#L53-L76)
+- [frontend/src/api/request.js](file://frontend/src/api/request.js#L38-L63)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L21)
+
+## 结论
+本系统采用清晰的分层架构与前后端分离模式，后端以 FastAPI 为核心，结合 SQLAlchemy 异步 ORM 与 Pydantic 校验，提供稳定可靠的接口能力；前端以 Vue 3 为基础，配合 Pinia 与 Axios，构建现代化的交互体验。通过统一的 API 前缀、CORS 配置与开发代理，确保跨域与开发效率。建议在生产环境中进一步完善鉴权、限流、审计与监控体系。
+
+## 附录
+- 启动顺序建议
+  - 后端：启动 Uvicorn 服务（main.py 中的 if __name__ 主入口）
+  - 前端：启动 Vite 开发服务器（package.json scripts dev）
+- 常用命令
+  - 后端：uvicorn --reload app.main:app --host 0.0.0.0 --port 8000
+  - 前端：npm run dev