# 系统架构

<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/core/security.py](file://backend/app/core/security.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/models/models.py](file://backend/app/models/models.py)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.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/src/router/index.js](file://frontend/src/router/index.js)
- [frontend/src/stores/user.js](file://frontend/src/stores/user.js)
- [frontend/src/api/request.js](file://frontend/src/api/request.js)
- [frontend/package.json](file://frontend/package.json)
</cite>

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

## 简介
本系统为“医院绩效管理系统”，采用前后端分离架构，后端基于 FastAPI + SQLAlchemy 2.0 + PostgreSQL 的异步数据访问栈，前端基于 Vue 3 + Pinia + Element Plus。系统围绕“分层架构 + 微服务理念（按功能域拆分 API 路由）”组织模块，覆盖用户认证、基础数据管理（科室、员工、指标）、绩效考核（含流程化状态机）、工资核算、数据分析与报表、系统管理（菜单）等核心领域。

## 项目结构
- 后端（Python/FastAPI）
  - 应用入口与中间件：app/main.py
  - 配置中心：app/core/config.py
  - 数据库连接与会话：app/core/database.py
  - 安全与认证：app/core/security.py
  - API 路由聚合：app/api/v1/__init__.py
  - 典型业务路由：app/api/v1/auth.py 等
  - 数据模型：app/models/models.py
  - 服务层：app/services/*（如 assessment_service.py、staff_service.py）
  - 依赖声明：backend/requirements.txt
- 前端（Vue 3）
  - 应用入口：frontend/src/main.js
  - 路由：frontend/src/router/index.js
  - 状态管理：frontend/src/stores/user.js
  - HTTP 封装：frontend/src/api/request.js
  - 依赖声明：frontend/package.json

```mermaid
graph TB
subgraph "前端"
FE_Main["frontend/src/main.js"]
FE_Router["frontend/src/router/index.js"]
FE_Store["frontend/src/stores/user.js"]
FE_API["frontend/src/api/request.js"]
end
subgraph "后端"
BE_App["backend/app/main.py"]
BE_Config["backend/app/core/config.py"]
BE_DB["backend/app/core/database.py"]
BE_Security["backend/app/core/security.py"]
BE_API_Auth["backend/app/api/v1/auth.py"]
BE_API_Router["backend/app/api/v1/__init__.py"]
BE_Models["backend/app/models/models.py"]
BE_Svc_Assess["backend/app/services/assessment_service.py"]
BE_Svc_Staff["backend/app/services/staff_service.py"]
end
FE_Main --> FE_Router
FE_Main --> FE_Store
FE_Main --> FE_API
FE_API --> BE_App
BE_App --> BE_API_Router
BE_API_Router --> BE_API_Auth
BE_App --> BE_DB
BE_App --> BE_Security
BE_DB --> BE_Models
BE_API_Auth --> BE_Security
BE_API_Auth --> BE_DB
BE_Svc_Assess --> BE_DB
BE_Svc_Staff --> BE_DB
```

图表来源
- [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/api/v1/auth.py](file://backend/app/api/v1/auth.py#L1-L74)
- [backend/app/core/database.py](file://backend/app/core/database.py#L1-L39)
- [backend/app/core/security.py](file://backend/app/core/security.py#L1-L110)
- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L438)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
- [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)
- [frontend/src/api/request.js](file://frontend/src/api/request.js#L1-L66)

章节来源
- [backend/app/main.py](file://backend/app/main.py#L15-L77)
- [backend/app/core/config.py](file://backend/app/core/config.py#L1-L47)
- [backend/app/core/database.py](file://backend/app/core/database.py#L1-L39)
- [backend/app/core/security.py](file://backend/app/core/security.py#L1-L110)
- [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/models/models.py](file://backend/app/models/models.py#L1-L438)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
- [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)
- [frontend/src/api/request.js](file://frontend/src/api/request.js#L1-L66)
- [frontend/package.json](file://frontend/package.json#L1-L27)
- [backend/requirements.txt](file://backend/requirements.txt#L1-L17)

## 核心组件
- 应用入口与生命周期
  - 后端通过 create_app 构建 FastAPI 实例，注册 CORS、全局异常处理器、健康检查端点，并挂载 API 路由前缀。
  - 前端通过 main.js 初始化应用、注册插件与路由，挂载到 DOM。
- 配置中心
  - 统一读取 .env，提供应用名、版本、API 前缀、数据库连接、JWT 参数、跨域白名单、分页参数等。
- 数据库与会话
  - 使用 SQLAlchemy 2.0 异步引擎与会话工厂，提供 get_db 依赖注入，自动事务提交/回滚与关闭。
- 安全与认证
  - 基于 OAuth2 密码流，JWT 生成与校验，支持当前用户解析、活跃用户校验、管理员/经理权限校验。
- API 路由聚合
  - v1 路由聚合器统一 include 各业务模块路由（认证、基础数据、考核、工资、统计、财务、计划、菜单、模板等）。
- 数据模型
  - 覆盖科室、员工、指标、考核记录、考核明细、工资记录、绩效计划、计划-KPI 关联、菜单、指标模板等。
- 服务层
  - AssessmentService 提供考核的增删改查、批量创建、状态流转（草稿/提交/审核/确认）。
  - StaffService 提供员工的查询、创建、更新、删除、按科室检索。
- 前端
  - 路由定义页面级视图；Pinia Store 管理用户态；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/core/security.py](file://backend/app/core/security.py#L21-L110)
- [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py#L1-L17)
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L438)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L14-L263)
- [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py#L13-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)
- [frontend/src/api/request.js](file://frontend/src/api/request.js#L1-L66)

## 架构总览
系统采用“前后端分离 + 分层架构 + 微服务理念（按功能域拆分 API）”：
- 展示层：Vue 3 单页应用，Element Plus 组件库，Pinia 状态管理。
- 控制层：FastAPI 路由与依赖注入，OAuth2/JWT 认证，CORS 放通。
- 业务层：服务类封装业务规则与流程（如考核状态机）。
- 数据层：SQLAlchemy 2.0 ORM + 异步数据库连接，PostgreSQL。
- 数据模型：强类型枚举与关系映射，确保数据一致性与可维护性。

```mermaid
graph TB
UI["前端界面<br/>Vue 3 + Element Plus"] --> API["后端 API<br/>FastAPI"]
API --> AUTH["认证与授权<br/>JWT/OAuth2"]
API --> SVC["服务层<br/>业务规则与流程"]
API --> ORM["数据访问<br/>SQLAlchemy 异步"]
ORM --> DB["数据库<br/>PostgreSQL"]
AUTH --- SEC["安全工具<br/>密码哈希/令牌"]
SVC --- MODELS["数据模型<br/>枚举/关系"]
```

图表来源
- [backend/app/main.py](file://backend/app/main.py#L19-L48)
- [backend/app/core/security.py](file://backend/app/core/security.py#L24-L110)
- [backend/app/core/database.py](file://backend/app/core/database.py#L10-L39)
- [backend/app/models/models.py](file://backend/app/models/models.py#L16-L61)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L14-L206)
- [frontend/src/main.js](file://frontend/src/main.js#L1-L24)

## 详细组件分析

### 认证与授权组件
- 后端
  - OAuth2 密码流令牌端点，登录时校验用户名/密码与账户状态，签发 JWT。
  - 当前用户解析与权限校验（活跃用户、管理员、经理）。
- 前端
  - 登录成功写入本地存储 token，后续请求自动附加 Authorization 头。
  - 401 自动跳转登录页，统一错误提示。

```mermaid
sequenceDiagram
participant U as "用户"
participant FE as "前端"
participant API as "后端 API"
participant SEC as "安全模块"
participant DB as "数据库"
U->>FE : 输入账号密码
FE->>API : POST /api/v1/auth/login
API->>SEC : 校验密码/账户状态
SEC->>DB : 查询用户
DB-->>SEC : 用户信息
SEC-->>API : 生成访问令牌
API-->>FE : 返回 access_token
FE->>FE : 保存 token 到本地存储
FE->>API : 后续请求携带 Authorization
```

图表来源
- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L17-L38)
- [backend/app/core/security.py](file://backend/app/core/security.py#L55-L91)
- [frontend/src/api/request.js](file://frontend/src/api/request.js#L15-L26)
- [frontend/src/stores/user.js](file://frontend/src/stores/user.js#L11-L20)

章节来源
- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L17-L38)
- [backend/app/core/security.py](file://backend/app/core/security.py#L55-L110)
- [frontend/src/api/request.js](file://frontend/src/api/request.js#L15-L63)
- [frontend/src/stores/user.js](file://frontend/src/stores/user.js#L11-L49)

### 绩效考核组件
- 服务层
  - 支持按条件筛选、分页、关联加载（员工与科室、指标）。
  - 创建/更新时计算总分与加权得分，支持批量为科室员工初始化考核。
  - 状态机：草稿 → 提交 → 审核（通过/驳回）→ 确认。
- 数据模型
  - Assessment/AssessmentDetail/Indicator/Staff 等多表关联，索引覆盖常用查询字段。

```mermaid
flowchart TD
Start(["开始"]) --> Create["创建考核记录<br/>计算总分/加权分"]
Create --> Details["创建明细项<br/>关联指标"]
Details --> Submit["提交考核<br/>状态=提交"]
Submit --> Review{"审核通过？"}
Review --> |是| Approve["审核通过<br/>状态=审核通过"]
Review --> |否| Reject["审核驳回<br/>状态=驳回"]
Approve --> Finalize["确认考核<br/>状态=确认"]
Reject --> End(["结束"])
Finalize --> End
```

图表来源
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L71-L206)
- [backend/app/models/models.py](file://backend/app/models/models.py#L149-L203)

章节来源
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L18-L263)
- [backend/app/models/models.py](file://backend/app/models/models.py#L149-L203)

### 员工管理组件
- 服务层
  - 支持按科室、状态、关键词搜索，分页返回员工列表与总数。
  - 提供创建、更新、删除、按科室获取在职员工等能力。
- 数据模型
  - Staff 与 Department 多对一关系，索引覆盖常用过滤字段。

```mermaid
classDiagram
class Staff {
+int id
+string employee_id
+string name
+int department_id
+string position
+float base_salary
+float performance_ratio
+StaffStatus status
}
class Department {
+int id
+string name
+string code
+DeptType dept_type
}
Staff --> Department : "属于"
```

图表来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L88-L114)
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L86)

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

### 数据模型与关系
- 关键实体与枚举：科室类型、平衡计分卡维度、员工状态、考核状态、指标类型、计划状态、菜单类型、模板类型等。
- 主要关系：部门-员工（一对多）、员工-考核（一对多）、考核-明细（一对多）、明细-指标（多对一）、计划-KPI 关联、菜单父子关系等。
- 索引策略：在常用过滤字段上建立索引，提升查询性能。

```mermaid
erDiagram
DEPARTMENTS ||--o{ STAFF : "拥有"
STAFF ||--o{ ASSESSMENTS : "被考核"
ASSESSMENTS ||--o{ ASSESSMENT_DETAILS : "包含"
INDICATORS ||--o{ ASSESSMENT_DETAILS : "被使用"
STAFF ||--o{ SALARY_RECORDS : "产生"
PERFORMANCE_PLANS ||--o{ PLAN_KPI_RELATIONS : "关联"
INDICATORS ||--o{ PLAN_KPI_RELATIONS : "被纳入"
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#L16-L438)

### 前后端交互与路由
- 前端
  - 路由定义页面级视图，包含仪表盘、基础数据、考核管理、工资核算、统计报表、经济核算、绩效计划、系统管理等。
  - 路由守卫校验 token，未登录重定向至登录页。
- 后端
  - API 路由前缀统一为 /api/v1，各模块独立注册。
  - 认证模块提供登录、注册、当前用户信息接口。

```mermaid
sequenceDiagram
participant R as "浏览器"
participant RT as "前端路由"
participant AX as "Axios 请求"
participant AP as "FastAPI 路由"
participant DB as "数据库"
R->>RT : 访问 / 或具体页面
RT->>AX : 发起 API 请求
AX->>AP : /api/v1/...带 Authorization
AP->>DB : 查询/写入数据
DB-->>AP : 返回结果
AP-->>AX : JSON 响应
AX-->>RT : 渲染页面
```

图表来源
- [frontend/src/router/index.js](file://frontend/src/router/index.js#L104-L113)
- [frontend/src/api/request.js](file://frontend/src/api/request.js#L7-L12)
- [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py#L1-L17)

章节来源
- [frontend/src/router/index.js](file://frontend/src/router/index.js#L1-L116)
- [frontend/src/api/request.js](file://frontend/src/api/request.js#L1-L66)
- [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py#L1-L17)

## 依赖关系分析
- 后端依赖
  - Web 框架：FastAPI
  - 异步数据库：SQLAlchemy 2.0 + asyncpg
  - 安全：python-jose + passlib[bcrypt]
  - 配置：pydantic-settings
  - 测试：pytest + pytest-asyncio
- 前端依赖
  - 运行时：vue、vue-router、pinia、axios、element-plus
  - 构建：vite、sass

```mermaid
graph LR
subgraph "后端"
F["FastAPI"]
S["SQLAlchemy 2.0"]
P["asyncpg"]
J["python-jose"]
B["passlib[bcrypt]"]
PS["pydantic-settings"]
PY["pytest + pytest-asyncio"]
end
subgraph "前端"
V["Vue 3"]
VR["vue-router"]
PI["Pinia"]
AX["axios"]
EP["Element Plus"]
VT["vite"]
SC["sass"]
end
F --> S
S --> P
F --> J
F --> B
F --> PS
F --> PY
V --> VR
V --> PI
V --> AX
V --> EP
V --> VT
V --> SC
```

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

## 性能考虑
- 异步 I/O：后端使用 SQLAlchemy 2.0 异步引擎与会话，降低高并发下的阻塞。
- 连接池：通过配置池大小与溢出参数，平衡吞吐与资源占用。
- 查询优化：模型中为高频过滤字段建立索引，服务层使用 selectinload 减少 N+1 查询。
- 分页与总数：服务层先统计总数再分页，避免一次性加载大结果集。
- 前端缓存：合理利用浏览器缓存与 Pinia 状态持久化，减少重复请求。

## 故障排查指南
- 登录失败
  - 检查用户名/密码与账户状态；确认 JWT 生成与返回。
  - 前端：确认 Authorization 头是否正确附加。
- 权限错误（403）
  - 确认当前用户角色与所需权限；检查 get_current_admin_user/get_current_manager_user 逻辑。
- 数据库连接问题
  - 检查 DATABASE_URL、池大小与超时配置；确认 PostgreSQL 可达。
- 健康检查
  - 访问 /health 端点确认服务可用与版本信息。

章节来源
- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L30-L34)
- [backend/app/core/security.py](file://backend/app/core/security.py#L94-L109)
- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L21)
- [backend/app/main.py](file://backend/app/main.py#L54-L56)
- [frontend/src/api/request.js](file://frontend/src/api/request.js#L39-L62)

## 结论
本系统以“前后端分离 + 分层架构 + 微服务理念”实现模块化与可扩展性，结合异步数据库访问与严格的权限控制，满足医院绩效管理在数据一致性、安全性与可维护性方面的关键需求。建议持续完善测试覆盖、日志与监控体系，并在生产环境调整安全密钥与跨域策略。

## 附录
- 部署建议
  - 后端：使用 uvicorn 运行，配置反向代理（Nginx）与 HTTPS；分离 .env 与敏感配置。
  - 前端：构建产物部署至静态服务器或 CDN，配置正确的 API 前缀与跨域。
- 开发建议
  - 使用 Alembic 管理数据库迁移；完善单元与集成测试；引入 OpenAPI 文档与 Redoc。