# 整体架构设计

<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