# 系统架构

<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/requirements.txt](file://backend/requirements.txt)
- [frontend/src/main.js](file://frontend/src/main.js)
- [frontend/package.json](file://frontend/package.json)
- [frontend/vite.config.js](file://frontend/vite.config.js)
- [frontend/src/router/index.js](file://frontend/src/router/index.js)
- [frontend/src/stores/user.js](file://frontend/src/stores/user.js)
- [docs/backend.md](file://docs/backend.md)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本系统为“医院绩效管理系统”，采用前后端分离架构，后端基于 FastAPI + SQLAlchemy 2.0 + PostgreSQL 的现代化技术栈，前端基于 Vue 3 + Pinia + Element Plus，提供绩效计划、指标模板、员工与科室管理、考核记录、统计分析、薪酬计算与财务核算等核心功能模块。系统通过异步 I/O 和数据库连接池提升并发能力，并通过统一的 API 前缀与跨域策略实现前后端协同。

## 项目结构
系统分为后端与前端两大子工程，分别位于 backend 与 frontend 目录。后端使用 FastAPI 提供 REST API，按功能模块划分 v1 子路由；前端使用 Vite 构建，通过 Vue Router 实现页面路由，Pinia 管理全局状态，Axios 发起请求并通过代理转发到后端。

```mermaid
graph TB
subgraph "前端(Frontend)"
FE_Main["frontend/src/main.js"]
FE_Router["frontend/src/router/index.js"]
FE_Store["frontend/src/stores/user.js"]
FE_Vite["frontend/vite.config.js"]
end
subgraph "后端(Backend)"
BE_App["backend/app/main.py"]
BE_Config["backend/app/core/config.py"]
BE_DB["backend/app/core/database.py"]
BE_API_Init["backend/app/api/v1/__init__.py"]
BE_Auth["backend/app/api/v1/auth.py"]
BE_StaffSvc["backend/app/services/staff_service.py"]
BE_Req["backend/requirements.txt"]
end
FE_Main --> FE_Router
FE_Main --> FE_Store
FE_Vite --> BE_App
FE_Router --> FE_Store
FE_Store --> BE_Auth
BE_App --> BE_API_Init
BE_API_Init --> BE_Auth
BE_App --> BE_DB
BE_DB --> BE_Config
BE_Req --> BE_App
```

图表来源
- [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#L1-L74)
- [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py#L1-L112)
- [frontend/src/main.js](file://frontend/src/main.js#L1-L24)
- [frontend/vite.config.js](file://frontend/vite.config.js#L1-L22)
- [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)
- [backend/requirements.txt](file://backend/requirements.txt#L1-L17)

章节来源
- [backend/app/main.py](file://backend/app/main.py#L15-L77)
- [frontend/src/main.js](file://frontend/src/main.js#L1-L24)
- [frontend/vite.config.js](file://frontend/vite.config.js#L1-L22)
- [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)
- [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#L1-L74)
- [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py#L1-L112)
- [backend/requirements.txt](file://backend/requirements.txt#L1-L17)

## 核心组件
- 后端应用实例与中间件
  - 应用创建、CORS 中间件、健康检查端点、异常处理器均在后端入口集中配置，确保统一的系统行为与可观测性。
- 配置中心
  - 使用 pydantic-settings 管理应用名称、版本、API 前缀、数据库连接串、JWT 密钥与过期时间、跨域白名单、分页参数等。
- 数据库层
  - 异步 SQLAlchemy 引擎与会话工厂，支持连接池与自动回滚/提交，提供统一的依赖注入接口。
- API 路由聚合
  - v1 路由聚合器统一注册认证、员工、科室、指标、考核、薪酬、统计、财务、计划、菜单、模板等模块路由。
- 业务服务层
  - 以 StaffService 为代表的典型服务层，封装查询、分页、条件过滤、增删改等操作，保证领域逻辑复用与清晰职责。
- 前端应用
  - Vue 3 应用初始化、Pinia 状态管理、Element Plus UI、路由守卫与本地存储鉴权，Vite 开发服务器与代理配置。
- 前端状态与路由
  - 用户登录状态持久化、路由守卫拦截未登录访问、API 请求通过 Axios 发起并与后端统一前缀对接。

章节来源
- [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/services/staff_service.py](file://backend/app/services/staff_service.py#L1-L112)
- [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/user.js](file://frontend/src/stores/user.js#L1-L49)

## 架构总览
系统采用前后端分离与模块化 API 设计，后端以 FastAPI 为核心，提供 REST 接口；前端通过 Axios 与后端交互，使用 Vue Router 管理页面导航，Pinia 管理用户态与全局状态。数据库采用 PostgreSQL，配合 SQLAlchemy 2.0 异步 ORM 与 Alembic 迁移工具，保障数据一致性与演进能力。

```mermaid
graph TB
Client["浏览器/客户端"]
FE["前端应用<br/>Vue 3 + Pinia + Element Plus"]
Proxy["Vite 开发代理<br/>/api -> 后端"]
API["FastAPI 应用<br/>路由聚合 + 中间件"]
DB["PostgreSQL 数据库"]
ORM["SQLAlchemy 2.0 异步 ORM"]
Client --> FE
FE --> Proxy
Proxy --> API
API --> ORM
ORM --> DB
```

图表来源
- [frontend/vite.config.js](file://frontend/vite.config.js#L12-L20)
- [backend/app/main.py](file://backend/app/main.py#L19-L48)
- [backend/app/core/database.py](file://backend/app/core/database.py#L9-L20)
- [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py#L1-L17)

## 详细组件分析

### 后端应用与中间件
- 应用创建与文档
  - 通过工厂函数创建 FastAPI 实例，设置标题、版本、OpenAPI 文档路径与描述，便于自动生成 API 文档。
- CORS 与路由
  - 注册 CORS 中间件与统一 API 前缀，include_router 将 v1 路由聚合器挂载至指定前缀。
- 异常处理
  - 全局注册 HTTP 异常、请求校验异常与通用异常处理器，统一记录日志并向上抛出，便于调试与监控。
- 健康检查
  - 提供 /health 端点返回系统状态与版本信息，便于容器编排与运维监控。

```mermaid
sequenceDiagram
participant C as "客户端"
participant F as "前端(Vite代理)"
participant A as "FastAPI应用"
participant R as "路由(v1)"
participant S as "服务层"
participant D as "数据库"
C->>F : "GET /api/v1/...示例"
F->>A : "转发请求"
A->>R : "路由匹配"
R->>S : "调用业务方法"
S->>D : "异步查询/写入"
D-->>S : "结果集"
S-->>R : "业务结果"
R-->>A : "响应对象"
A-->>F : "HTTP 响应"
F-->>C : "返回数据"
```

图表来源
- [backend/app/main.py](file://backend/app/main.py#L15-L77)
- [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#L1-L112)
- [backend/app/core/database.py](file://backend/app/core/database.py#L28-L39)

章节来源
- [backend/app/main.py](file://backend/app/main.py#L15-L77)

### 配置与数据库层
- 配置项
  - 应用名称、版本、API 前缀、数据库连接串、连接池大小、JWT 签发与过期、跨域白名单、默认/最大分页大小等。
- 数据库引擎与会话
  - 异步引擎与会话工厂，提供 get_db 依赖，自动 commit/rollback/关闭，简化事务管理与资源释放。

```mermaid
flowchart TD
Start(["应用启动"]) --> LoadCfg["加载配置(Settings)"]
LoadCfg --> CreateEngine["创建异步引擎"]
CreateEngine --> CreateSession["创建会话工厂"]
CreateSession --> ProvideDep["提供 get_db 依赖"]
ProvideDep --> End(["服务可用"])
```

图表来源
- [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)

### API 路由与认证
- 路由聚合
  - v1 路由聚合器统一 include 各模块路由，便于扩展与维护。
- 认证模块
  - 提供登录、注册、当前用户信息等接口，使用依赖注入获取数据库会话，结合安全工具进行密码校验与令牌签发。

```mermaid
sequenceDiagram
participant U as "用户"
participant FR as "前端路由"
participant AU as "认证路由"
participant DB as "数据库"
participant SEC as "安全工具"
U->>FR : "提交登录表单"
FR->>AU : "POST /api/v1/auth/login"
AU->>DB : "查询用户"
DB-->>AU : "用户记录"
AU->>SEC : "校验密码"
SEC-->>AU : "校验结果"
AU-->>FR : "返回访问令牌"
FR-->>U : "跳转首页/保存令牌"
```

图表来源
- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L17-L37)
- [backend/app/core/database.py](file://backend/app/core/database.py#L28-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#L1-L74)

### 服务层与数据访问
- 服务层职责
  - 封装复杂查询、分页与条件组合，避免在路由层直接编写 SQL，提升可测试性与可维护性。
- 典型流程
  - 列表查询：构造查询条件 → 统计总数 → 分页排序 → 返回数据与总数。

```mermaid
flowchart TD
QStart(["进入服务方法"]) --> Build["构建查询条件"]
Build --> Count["统计总数(subquery)"]
Count --> Page["分页与排序"]
Page --> Exec["执行查询"]
Exec --> Ret["返回结果与总数"]
```

图表来源
- [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py#L24-L49)

章节来源
- [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py#L1-L112)

### 前端应用与状态管理
- 应用初始化
  - 注册 Pinia、路由、Element Plus 与本地化，挂载应用根组件。
- 路由与守卫
  - 定义多级菜单路由，使用 beforeEach 守卫判断本地 token 并重定向至登录页。
- 状态管理
  - 用户 store 管理 token 与用户信息，提供登录、获取用户信息、登出方法，登出时清理本地存储并跳转登录页。
- 开发代理
  - Vite 将 /api 前缀代理到后端地址，解决开发阶段跨域问题。

```mermaid
sequenceDiagram
participant V as "Vue 应用"
participant R as "路由守卫"
participant S as "用户store"
participant A as "认证API"
V->>R : "导航到受保护页面"
R->>S : "读取localStorage.token"
alt 无token
R-->>V : "重定向到 /login"
else 有token
R-->>V : "放行"
V->>S : "调用 getUserInfo()"
S->>A : "GET /api/v1/auth/me"
A-->>S : "返回用户信息"
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#L22-L31)
- [frontend/src/main.js](file://frontend/src/main.js#L1-L24)

章节来源
- [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/user.js](file://frontend/src/stores/user.js#L1-L49)
- [frontend/vite.config.js](file://frontend/vite.config.js#L12-L20)

## 依赖分析
- 后端技术栈
  - FastAPI、SQLAlchemy 2.0、Pydantic、Alembic、asyncpg、uvicorn、passlib、python-jose 等，构成高性能、强类型、可演进的后端基础设施。
- 前端技术栈
  - Vue 3、Vue Router、Pinia、Axios、Element Plus、Vite，提供现代化的交互体验与开发效率。
- 外部依赖关系
  - 前端通过 /api 前缀代理访问后端；后端通过 asyncpg 连接 PostgreSQL；配置中心统一管理数据库连接串与 JWT 参数。

```mermaid
graph LR
FE["前端依赖(package.json)"] --> AX["Axios"]
FE --> VR["Vue Router"]
FE --> PI["Pinia"]
FE --> EP["Element Plus"]
BE["后端依赖(requirements.txt)"] --> FA["FastAPI"]
BE --> SA["SQLAlchemy 2.0"]
BE --> PG["asyncpg"]
BE --> AL["Alembic"]
BE --> UV["uvicorn"]
BE --> PJ["python-jose"]
BE --> PB["passlib"]
AX --> API["后端API(/api/v1)"]
VR --> API
PI --> API
EP --> FE
API --> PG
```

图表来源
- [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#L1-L27)
- [backend/requirements.txt](file://backend/requirements.txt#L1-L17)

## 性能考虑
- 异步 I/O 与连接池
  - 使用 SQLAlchemy 2.0 异步引擎与连接池参数，减少阻塞，提升高并发下的吞吐能力。
- 分页与索引
  - 服务层对列表查询进行分页与排序，数据库层通过索引优化常用查询字段，降低查询延迟。
- 缓存与压缩
  - 建议在网关层启用静态资源缓存与 Gzip 压缩，减少带宽占用。
- 前端懒加载
  - 路由与组件采用动态导入，缩短首屏加载时间，提升用户体验。
- 数据库迁移与版本控制
  - 使用 Alembic 管理数据库结构变更，避免生产环境回滚风险。

## 故障排查指南
- 后端异常处理
  - HTTP 异常、请求校验异常与通用异常均被记录日志并向上抛出，便于定位问题来源。
- 健康检查
  - 通过 /health 端点快速确认服务状态与版本信息。
- 前端路由守卫
  - 未登录访问受保护页面将被重定向至登录页，检查本地存储 token 是否存在。
- 数据库连接
  - 若出现连接失败，检查 DATABASE_URL、连接池参数与数据库服务状态。

章节来源
- [backend/app/main.py](file://backend/app/main.py#L53-L76)
- [frontend/src/router/index.js](file://frontend/src/router/index.js#L104-L113)
- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L21)

## 结论
本系统通过前后端分离与模块化 API 设计，结合 FastAPI 的高性能与强类型特性、Vue 3 的现代开发体验以及 PostgreSQL 的稳定可靠，构建了可扩展、易维护的医院绩效管理平台。建议在生产环境中完善鉴权策略、引入缓存与消息队列、增强监控与日志采集，并持续通过 Alembic 管理数据库演进。

## 附录
- 系统边界与集成点
  - 系统边界：前端通过 /api 前缀与后端交互；后端仅暴露 REST 接口；数据库为内部存储。
  - 集成点：JWT 用于前后端鉴权；Axios 作为 HTTP 客户端；Vite 代理用于开发联调。
- 架构决策依据
  - FastAPI：高性能、自动生成 OpenAPI 文档、强类型校验。
  - Vue 3：组合式 API、更好的 TypeScript 支持、生态丰富。
  - PostgreSQL：成熟的关系型数据库、异步驱动与迁移工具完善。