# 组件交互关系

<cite>
**本文引用的文件**
- [backend/app/main.py](file://backend/app/main.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/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/models/models.py](file://backend/app/models/models.py)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py)
- [frontend/src/main.js](file://frontend/src/main.js)
- [frontend/src/router/index.js](file://frontend/src/router/index.js)
- [frontend/src/api/request.js](file://frontend/src/api/request.js)
- [frontend/src/api/assessment.js](file://frontend/src/api/assessment.js)
- [frontend/src/stores/user.js](file://frontend/src/stores/user.js)
- [frontend/src/views/Dashboard.vue](file://frontend/src/views/Dashboard.vue)
</cite>

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

## 简介
本文件面向“医院绩效系统”的前后端交互与内部架构，聚焦以下主题：
- 前端 Vue 组件与后端 FastAPI 服务的交互模式：HTTP 请求/响应流程、API 封装与错误处理
- 组件间通信方式：父子、兄弟与跨组件状态共享
- 数据库连接池管理、ORM 查询优化与事务处理
- 中间件作用：CORS、身份验证、日志与异常捕获
- 数据流与组件依赖关系图

## 项目结构
系统采用前后端分离架构：
- 前端：Vue 3 + Pinia + Element Plus + Vue Router
- 后端：FastAPI + SQLAlchemy 2.0（异步）+ PostgreSQL
- 数据模型统一定义于 ORM 层，服务层负责业务逻辑，API 层提供 REST 接口

```mermaid
graph TB
subgraph "前端"
FE_Main["main.js<br/>应用入口"]
FE_Router["router/index.js<br/>路由与守卫"]
FE_API["api/request.js<br/>Axios封装"]
FE_AsmAPI["api/assessment.js<br/>考核API"]
FE_UserStore["stores/user.js<br/>用户状态"]
FE_Dashboard["views/Dashboard.vue<br/>工作台视图"]
end
subgraph "后端"
BE_App["app/main.py<br/>应用与中间件"]
BE_Config["core/config.py<br/>配置"]
BE_DB["core/database.py<br/>异步引擎/会话"]
BE_Security["core/security.py<br/>JWT/认证"]
BE_Models["models/models.py<br/>ORM模型"]
BE_Svc_Asm["services/assessment_service.py<br/>服务层"]
BE_API_Init["api/v1/__init__.py<br/>路由聚合"]
BE_API_Auth["api/v1/auth.py<br/>认证接口"]
end
FE_Main --> FE_Router
FE_Main --> FE_API
FE_API --> BE_App
FE_AsmAPI --> FE_API
FE_UserStore --> FE_API
FE_Dashboard --> FE_AsmAPI
BE_App --> BE_Config
BE_App --> BE_DB
BE_App --> BE_API_Init
BE_API_Init --> BE_API_Auth
BE_Security --> BE_DB
BE_Svc_Asm --> BE_DB
BE_Svc_Asm --> BE_Models
```

图表来源
- [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/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/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)
- [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/api/request.js](file://frontend/src/api/request.js#L1-L66)
- [frontend/src/api/assessment.js](file://frontend/src/api/assessment.js#L1-L50)
- [frontend/src/stores/user.js](file://frontend/src/stores/user.js#L1-L49)
- [frontend/src/views/Dashboard.vue](file://frontend/src/views/Dashboard.vue#L1-L1082)

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

## 核心组件
- 前端应用入口与插件注册：初始化 Vue 实例、Pinia、路由、Element Plus，并挂载应用。
- 路由与导航守卫：统一设置页面标题、校验登录态（localStorage token），未登录重定向至登录页。
- Axios 封装：统一基础 URL、超时、请求头；自动注入 Authorization；统一封装响应体结构与错误处理。
- 用户状态管理：登录、获取当前用户、登出，持久化 token 并跳转登录页。
- API 模块：按功能拆分，如考核 API，支持列表、详情、创建、更新、提交、审核、确认、批量创建等。
- 后端应用：创建 FastAPI 实例，注册 CORS、路由前缀、健康检查与全局异常处理器。
- 安全与认证：JWT 生成与解析、OAuth2 密钥流、当前用户解析与权限校验。
- 数据库：异步引擎与会话工厂，依赖注入式获取会话，自动提交/回滚/关闭。
- 业务服务：如考核服务，实现分页、过滤、明细计算、状态流转、批量创建等。

章节来源
- [frontend/src/main.js](file://frontend/src/main.js#L1-L24)
- [frontend/src/router/index.js](file://frontend/src/router/index.js#L103-L113)
- [frontend/src/api/request.js](file://frontend/src/api/request.js#L1-L66)
- [frontend/src/stores/user.js](file://frontend/src/stores/user.js#L1-L49)
- [frontend/src/api/assessment.js](file://frontend/src/api/assessment.js#L1-L50)
- [backend/app/main.py](file://backend/app/main.py#L15-L77)
- [backend/app/core/security.py](file://backend/app/core/security.py#L1-L110)
- [backend/app/core/database.py](file://backend/app/core/database.py#L1-L39)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)

## 架构总览
系统采用“前端 SPA + 后端 API”模式，数据流自上而下：
- 前端组件通过 API 模块发起 HTTP 请求，Axios 统一拦截器注入 token 并处理响应。
- 后端 FastAPI 解析请求，路由到对应控制器，依赖注入数据库会话，调用服务层执行业务逻辑。
- 服务层操作 ORM 模型，进行查询、计算与写入，返回标准化结果。
- 异常在后端统一捕获并记录日志，前端根据响应体或 HTTP 状态码进行提示与跳转。

```mermaid
sequenceDiagram
participant View as "Dashboard.vue"
participant API as "assessment.js"
participant Axios as "request.js"
participant FastAPI as "main.py"
participant Router as "api/v1/auth.py"
participant Sec as "core/security.py"
participant DB as "core/database.py"
View->>API : "调用获取考核列表/详情/趋势等"
API->>Axios : "GET /api/v1/...带Authorization"
Axios->>FastAPI : "HTTP 请求"
FastAPI->>Router : "路由匹配"
Router->>Sec : "依赖注入当前用户JWT"
Sec->>DB : "获取 AsyncSession"
DB-->>Sec : "会话可用"
Sec-->>Router : "返回当前用户"
Router-->>Axios : "业务处理读取/写入"
Axios-->>View : "返回标准化数据"
```

图表来源
- [frontend/src/views/Dashboard.vue](file://frontend/src/views/Dashboard.vue#L329-L421)
- [frontend/src/api/assessment.js](file://frontend/src/api/assessment.js#L1-L50)
- [frontend/src/api/request.js](file://frontend/src/api/request.js#L1-L66)
- [backend/app/main.py](file://backend/app/main.py#L58-L74)
- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L17-L37)
- [backend/app/core/security.py](file://backend/app/core/security.py#L55-L82)
- [backend/app/core/database.py](file://backend/app/core/database.py#L28-L39)

## 详细组件分析

### 前端组件与 API 交互
- 登录流程
  - 用户输入账号密码 → 调用登录 API → 成功后保存 token 到 localStorage → 跳转首页
  - 失败时返回错误，前端不保存 token
- 路由守卫
  - 进入受保护路由前检查 token，缺失则重定向登录
- Axios 封装
  - 自动注入 Authorization: Bearer token
  - 统一响应体结构：当 res.code !== 200 时提示错误并 reject
  - 对 401/403/404/500 等状态码分别处理，401 清除 token 并跳转登录
- Dashboard 视图
  - 使用多个 API 方法加载统计数据、趋势、排名、财务趋势与预警
  - 通过 ECharts 渲染图表，监听窗口 resize 事件保持图表尺寸一致

```mermaid
sequenceDiagram
participant Comp as "Dashboard.vue"
participant Store as "user.js"
participant API as "assessment.js"
participant Req as "request.js"
participant BE as "auth.py"
Comp->>Store : "登录用户名/密码"
Store->>BE : "POST /api/v1/auth/login"
BE-->>Store : "返回 access_token"
Store->>Store : "保存 token 到 localStorage"
Store-->>Comp : "登录成功"
Comp->>API : "getPeriodStats/getTrendData/..."
API->>Req : "GET /api/v1/stats/...含Authorization"
Req-->>Comp : "返回数据并渲染图表"
```

图表来源
- [frontend/src/views/Dashboard.vue](file://frontend/src/views/Dashboard.vue#L329-L421)
- [frontend/src/stores/user.js](file://frontend/src/stores/user.js#L11-L20)
- [frontend/src/api/assessment.js](file://frontend/src/api/assessment.js#L1-L50)
- [frontend/src/api/request.js](file://frontend/src/api/request.js#L14-L63)
- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L17-L37)

章节来源
- [frontend/src/router/index.js](file://frontend/src/router/index.js#L103-L113)
- [frontend/src/api/request.js](file://frontend/src/api/request.js#L1-L66)
- [frontend/src/stores/user.js](file://frontend/src/stores/user.js#L1-L49)
- [frontend/src/views/Dashboard.vue](file://frontend/src/views/Dashboard.vue#L329-L421)

### 后端 API 与服务层
- 应用与中间件
  - 注册 CORS：允许指定 origins、credentials、methods、headers
  - 注册路由前缀与健康检查
  - 全局异常处理：HTTP 异常、请求验证异常、通用异常均记录日志并抛出
- 认证与安全
  - 登录：校验用户名与密码，检查用户是否激活，签发 JWT
  - 当前用户：OAuth2 密钥流 + JWT 解码 + 数据库查询
  - 权限校验：管理员、经理等角色校验
- 服务层（示例：考核）
  - 支持多条件分页查询、预加载关联、计算总分与加权得分
  - 状态机：草稿/已提交/已审核/已确认/已驳回
  - 批量创建：按科室与周期批量生成考核记录与明细

```mermaid
flowchart TD
Start(["请求进入"]) --> CORS["CORS 中间件校验"]
CORS --> Router["路由匹配/api/v1/..."]
Router --> Auth["OAuth2/JWT 校验当前用户"]
Auth --> Service["服务层业务处理查询/计算/写入"]
Service --> ORM["ORM 操作异步会话"]
ORM --> Resp["返回标准化响应"]
Resp --> End(["结束"])
Router -.->|异常| Log["记录日志并抛出异常"]
Log --> End
```

图表来源
- [backend/app/main.py](file://backend/app/main.py#L41-L74)
- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L17-L37)
- [backend/app/core/security.py](file://backend/app/core/security.py#L55-L82)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L18-L55)

章节来源
- [backend/app/main.py](file://backend/app/main.py#L41-L74)
- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L1-L74)
- [backend/app/core/security.py](file://backend/app/core/security.py#L1-L110)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)

### 数据库连接池与事务
- 异步引擎与会话工厂
  - 使用异步驱动创建引擎，开启调试输出
  - 会话工厂设置类为 AsyncSession，关闭提交行为，避免每次提交后失效
- 依赖注入
  - get_db 作为依赖，在 try 块中 yield 会话，成功提交，异常回滚并抛出，finally 关闭
- 事务语义
  - 单次请求内使用同一会话，异常自动回滚，保证一致性
- 查询优化
  - 使用 selectinload 预加载关联，减少 N+1 查询
  - 多处使用索引字段过滤与排序，结合分页 limit/offset

```mermaid
flowchart TD
S(["进入依赖 get_db"]) --> New["创建 AsyncSession"]
New --> Try["yield 会话给业务"]
Try --> Ok{"是否异常？"}
Ok -- 是 --> Rollback["session.rollback()"]
Rollback --> Throw["raise 异常"]
Ok -- 否 --> Commit["session.commit()"]
Commit --> Close["session.close()"]
Throw --> Close
Close --> E(["退出依赖"])
```

图表来源
- [backend/app/core/database.py](file://backend/app/core/database.py#L28-L39)
- [backend/app/models/models.py](file://backend/app/models/models.py#L78-L85)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L29-L31)

章节来源
- [backend/app/core/database.py](file://backend/app/core/database.py#L1-L39)
- [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)

### 组件间通信与状态共享
- 父子组件通信
  - Dashboard.vue 通过 props 传递图表容器引用与数据，内部通过 ECharts 实例渲染
- 兄弟组件通信
  - 通过 Pinia store 共享用户 token 与基本信息，任一组件可读写
- 跨组件状态共享
  - 用户 store 统一管理登录态，路由守卫依赖其 token 判断访问权限
  - API 层通过 Axios 拦截器自动注入 Authorization，避免重复处理

章节来源
- [frontend/src/views/Dashboard.vue](file://frontend/src/views/Dashboard.vue#L423-L448)
- [frontend/src/stores/user.js](file://frontend/src/stores/user.js#L1-L49)
- [frontend/src/api/request.js](file://frontend/src/api/request.js#L14-L26)

## 依赖分析
- 前端
  - main.js 依赖 router、store、Element Plus
  - router/index.js 依赖懒加载组件与 beforeEach 守卫
  - api/request.js 依赖 axios、Element Plus Message、router
  - api/assessment.js 依赖 request
  - stores/user.js 依赖 api/auth 与 router
  - views/Dashboard.vue 依赖多个统计 API 与 ECharts
- 后端
  - app/main.py 依赖 core/config、core/logging_config、api/v1
  - api/v1/__init__.py 依赖各功能路由模块
  - api/v1/auth.py 依赖 core/database、core/security、schemas、models
  - core/security.py 依赖 core/config、core/database、jose、bcrypt
  - core/database.py 依赖 core/config
  - models/models.py 依赖 core/database
  - services/assessment_service.py 依赖 models、schemas、sqlalchemy

```mermaid
graph LR
FE_Main["main.js"] --> FE_Router["router/index.js"]
FE_Main --> FE_API["api/request.js"]
FE_API --> FE_AsmAPI["api/assessment.js"]
FE_AsmAPI --> FE_Dashboard["views/Dashboard.vue"]
BE_App["app/main.py"] --> BE_API_Init["api/v1/__init__.py"]
BE_API_Init --> BE_API_Auth["api/v1/auth.py"]
BE_App --> BE_Config["core/config.py"]
BE_App --> BE_DB["core/database.py"]
BE_API_Auth --> BE_Security["core/security.py"]
BE_Security --> BE_DB
BE_Svc_Asm["services/assessment_service.py"] --> BE_Models["models/models.py"]
```

图表来源
- [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/api/request.js](file://frontend/src/api/request.js#L1-L66)
- [frontend/src/api/assessment.js](file://frontend/src/api/assessment.js#L1-L50)
- [frontend/src/views/Dashboard.vue](file://frontend/src/views/Dashboard.vue#L1-L1082)
- [backend/app/main.py](file://backend/app/main.py#L1-L92)
- [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/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/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)

章节来源
- [frontend/src/main.js](file://frontend/src/main.js#L1-L24)
- [backend/app/main.py](file://backend/app/main.py#L1-L92)

## 性能考虑
- 异步 I/O 与连接池
  - 使用 SQLAlchemy 2.0 异步引擎与连接池，提升并发吞吐
  - 通过依赖注入复用会话，避免频繁创建销毁
- 查询优化
  - 使用 selectinload 预加载关联，减少 N+1 查询
  - 多处对常用过滤字段建立索引，配合分页 limit/offset
- 前端性能
  - ECharts 图表按需渲染，窗口 resize 时统一触发重绘
  - API 返回结构化数据，前端仅渲染必要字段，降低 DOM 压力

## 故障排查指南
- 登录失败
  - 检查用户名/密码是否正确，用户是否被禁用
  - 查看后端日志与前端错误提示，确认 401/403 场景
- 401 未授权
  - 前端移除本地 token 并跳转登录；确认 JWT 未过期
- 403 权限不足
  - 确认用户角色是否满足接口要求（管理员/经理）
- 500 服务器错误
  - 查看后端日志定位异常堆栈，确认数据库事务是否回滚
- 前端网络错误
  - 检查 baseURL 是否正确（/api/v1），CORS 是否放行
  - 确认 Axios 拦截器是否正确注入 Authorization

章节来源
- [frontend/src/api/request.js](file://frontend/src/api/request.js#L38-L63)
- [backend/app/main.py](file://backend/app/main.py#L58-L74)
- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L30-L34)

## 结论
本系统通过清晰的前后端职责划分与中间件、安全、数据库与服务层的协同，实现了稳定高效的绩效管理能力。前端以组件为中心，通过 API 模块与状态管理实现松耦合；后端以 FastAPI 为核心，结合异步 ORM 与严格的安全策略，确保高并发下的可靠性与可维护性。建议持续关注查询索引、分页与缓存策略，进一步优化大数据量场景下的性能表现。

## 附录
- 配置项参考
  - 应用名、版本、API 前缀、数据库连接、JWT 密钥与过期时间、CORS 允许源、分页大小
- 数据模型概览
  - 部门、员工、指标、考核、明细、工资、计划、菜单、模板等核心实体及其关系

章节来源
- [backend/app/core/config.py](file://backend/app/core/config.py#L13-L33)
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L438)