# 数据流架构

<cite>
**本文引用的文件**
- [frontend/src/main.js](file://frontend/src/main.js)
- [frontend/src/router/index.js](file://frontend/src/router/index.js)
- [frontend/src/stores/index.js](file://frontend/src/stores/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/index.js](file://frontend/src/api/index.js)
- [frontend/src/api/assessment.js](file://frontend/src/api/assessment.js)
- [frontend/src/views/assessment/Assessments.vue](file://frontend/src/views/assessment/Assessments.vue)
- [frontend/src/views/finance/Finance.vue](file://frontend/src/views/finance/Finance.vue)
- [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/assessments.py](file://backend/app/api/v1/assessments.py)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py)
- [backend/app/models/models.py](file://backend/app/models/models.py)
- [backend/app/models/finance.py](file://backend/app/models/finance.py)
- [backend/app/core/database.py](file://backend/app/core/database.py)
- [backend/app/core/config.py](file://backend/app/core/config.py)
</cite>

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

## 简介
本文件面向“医院绩效系统”的数据流架构，覆盖从前端用户交互到后端服务处理，再到数据库持久化的完整链路。重点说明：
- 前端状态管理（Pinia Store）的状态变更、组件数据绑定与响应式更新机制
- 后端服务层的数据处理流程（业务逻辑、数据验证、异常处理、结果返回）
- 数据库层的数据存储与查询优化策略
- 典型业务场景的数据流示例与性能优化建议

## 项目结构
系统采用前后端分离架构：
- 前端基于 Vue 3 + Pinia + Element Plus，通过路由驱动页面导航与状态管理
- 后端基于 FastAPI + SQLAlchemy 2.0 异步 ORM，提供 RESTful 接口与统一异常处理

```mermaid
graph TB
subgraph "前端"
FE_Main["main.js<br/>应用初始化"]
FE_Router["router/index.js<br/>路由与守卫"]
FE_Store_User["stores/user.js<br/>用户状态"]
FE_Store_App["stores/app.js<br/>应用状态"]
FE_API["api/*<br/>接口封装"]
FE_View_Assess["views/assessment/Assessments.vue<br/>考核列表视图"]
FE_View_Finance["views/finance/Finance.vue<br/>财务核算视图"]
end
subgraph "后端"
BE_App["app/main.py<br/>FastAPI 应用"]
BE_Router["api/v1/__init__.py<br/>路由聚合"]
BE_API_Assess["api/v1/assessments.py<br/>考核API"]
BE_Service_Assess["services/assessment_service.py<br/>考核服务"]
BE_Models["models/models.py<br/>数据模型"]
BE_DB["core/database.py<br/>异步数据库"]
BE_Config["core/config.py<br/>系统配置"]
end
FE_Main --> FE_Router
FE_Router --> FE_View_Assess
FE_Router --> FE_View_Finance
FE_View_Assess --> FE_Store_User
FE_View_Assess --> FE_Store_App
FE_View_Finance --> FE_Store_App
FE_View_Assess --> FE_API
FE_View_Finance --> FE_API
FE_API --> BE_App
BE_App --> BE_Router
BE_Router --> BE_API_Assess
BE_API_Assess --> BE_Service_Assess
BE_Service_Assess --> BE_Models
BE_Models --> BE_DB
BE_App --> BE_Config
```

图表来源
- [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/stores/app.js](file://frontend/src/stores/app.js#L1-L31)
- [frontend/src/api/index.js](file://frontend/src/api/index.js#L1-L9)
- [frontend/src/views/assessment/Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L1-L311)
- [frontend/src/views/finance/Finance.vue](file://frontend/src/views/finance/Finance.vue#L1-L614)
- [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/assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L438)
- [backend/app/core/database.py](file://backend/app/core/database.py#L1-L39)
- [backend/app/core/config.py](file://backend/app/core/config.py#L1-L47)

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

## 核心组件
- 前端应用入口与依赖注入：注册 Pinia、路由、UI 组件库，挂载应用实例
- 路由与导航：定义页面路由、面包屑标题、登录守卫
- 状态管理：用户登录态与 Token、全局应用状态（如侧边栏折叠、科室树）
- API 层：统一请求封装与各模块接口导出
- 视图组件：业务视图负责数据加载、交互与调用 API
- 后端应用：FastAPI 实例、CORS、异常处理、健康检查
- 路由聚合：按功能模块组织 API 路由
- 服务层：业务逻辑封装（如考核 CRUD、状态机流转）
- 数据模型：ORM 映射与索引、约束
- 数据库：异步引擎、会话工厂、依赖注入
- 配置：应用名、版本、数据库、JWT、跨域、分页等

章节来源
- [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/index.js](file://frontend/src/stores/index.js#L1-L3)
- [frontend/src/stores/user.js](file://frontend/src/stores/user.js#L1-L49)
- [frontend/src/stores/app.js](file://frontend/src/stores/app.js#L1-L31)
- [frontend/src/api/index.js](file://frontend/src/api/index.js#L1-L9)
- [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/services/assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L438)
- [backend/app/core/database.py](file://backend/app/core/database.py#L1-L39)
- [backend/app/core/config.py](file://backend/app/core/config.py#L1-L47)

## 架构总览
以下序列图展示一次“用户登录”到“获取考核列表”的端到端数据流。

```mermaid
sequenceDiagram
participant U as "用户"
participant V as "Assessments.vue"
participant S as "Pinia 用户Store"
participant A as "API 封装"
participant F as "FastAPI 应用"
participant R as "路由/中间件"
participant SVC as "AssessmentService"
participant DB as "数据库"
U->>V : 输入账号密码并点击登录
V->>S : 调用 login(username,password)
S->>A : 调用登录接口(loginApi)
A->>F : POST /api/v1/auth/login
F->>R : CORS/异常处理
R-->>F : 路由匹配
F-->>A : 返回 access_token
A-->>S : 返回 token
S-->>V : 更新 token 与用户信息
V->>S : 调用 getUserInfo()
S->>A : 调用获取用户信息接口
A->>F : GET /api/v1/auth/me
F->>R : 鉴权/异常处理
R-->>F : 路由匹配
F-->>A : 返回用户信息
A-->>S : 返回用户信息
S-->>V : 更新 userInfo
V->>A : 请求考核列表(getAssessments)
A->>F : GET /api/v1/assessments
F->>R : 鉴权/异常处理
R-->>F : 路由匹配
F->>SVC : 调用 AssessmentService.get_list(...)
SVC->>DB : 查询/分页/聚合
DB-->>SVC : 结果集
SVC-->>F : 业务结果
F-->>A : 统一响应包装
A-->>V : 返回列表数据
V-->>U : 渲染表格与分页
```

图表来源
- [frontend/src/views/assessment/Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L178-L195)
- [frontend/src/stores/user.js](file://frontend/src/stores/user.js#L10-L31)
- [frontend/src/api/assessment.js](file://frontend/src/api/assessment.js#L4-L6)
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L20-L52)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L18-L55)
- [backend/app/main.py](file://backend/app/main.py#L58-L74)

## 详细组件分析

### 前端状态管理与组件数据绑定
- Pinia Store
  - 用户 Store：维护 token 与用户信息，支持登录、获取用户信息、登出；登录成功写入本地存储并触发路由跳转
  - 应用 Store：维护侧边栏折叠状态与科室树，提供加载科室树能力
- 组件数据绑定与响应式更新
  - 视图组件通过响应式数据（ref/reactive）绑定表单与表格
  - 组件在 mounted 生命周期触发数据加载，使用 Promise.all 并行拉取多个接口
  - 组件内部通过 ElMessage、ElMessageBox 进行用户反馈与二次确认
- 路由守卫
  - 未登录访问受保护路由时自动跳转登录页

```mermaid
flowchart TD
Start(["组件挂载"]) --> LoadDept["加载科室树"]
LoadDept --> LoadIndicators["加载有效指标"]
LoadIndicators --> LoadAssessments["加载考核列表"]
LoadAssessments --> Render["渲染表格/分页"]
Render --> Interact{"用户交互？"}
Interact --> |查询/分页| LoadAssessments
Interact --> |提交/审核/确认| CallAPI["调用对应 API"]
CallAPI --> Refresh["刷新列表/详情"]
Refresh --> Render
Interact --> |批量创建| Batch["打开批量创建对话框"]
Batch --> SubmitBatch["提交批量创建请求"]
SubmitBatch --> Refresh
```

图表来源
- [frontend/src/views/assessment/Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L178-L292)
- [frontend/src/stores/app.js](file://frontend/src/stores/app.js#L14-L22)
- [frontend/src/stores/user.js](file://frontend/src/stores/user.js#L10-L31)
- [frontend/src/router/index.js](file://frontend/src/router/index.js#L104-L113)

章节来源
- [frontend/src/stores/user.js](file://frontend/src/stores/user.js#L1-L49)
- [frontend/src/stores/app.js](file://frontend/src/stores/app.js#L1-L31)
- [frontend/src/views/assessment/Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L1-L311)
- [frontend/src/router/index.js](file://frontend/src/router/index.js#L1-L116)

### 后端服务层数据处理流程
- API 路由
  - 考核模块提供列表、详情、创建、更新、提交、审核、确认、批量创建等接口
  - 使用依赖注入获取数据库会话与当前用户，进行鉴权与权限校验
- 服务层
  - AssessmentService 封装业务逻辑：列表查询（含多条件过滤与分页）、详情加载（含关联预加载）、创建（计算总分与加权得分、批量写入明细）、更新（状态限制、重建明细）、状态机流转（提交/审核/确认）
- 数据模型与索引
  - 模型定义了主键、外键、枚举、索引与约束，确保数据一致性与查询效率
  - 例如：考核记录按 staff、period、status 建立复合索引，便于筛选与排序
- 数据库与配置
  - 异步引擎与会话工厂，依赖注入在请求生命周期内自动 commit/rollback/close
  - 配置集中管理数据库连接池、JWT、跨域、分页等参数

```mermaid
sequenceDiagram
participant C as "客户端"
participant API as "Assessments API"
participant AUTH as "鉴权中间件"
participant SVC as "AssessmentService"
participant DB as "数据库"
C->>API : POST /api/v1/assessments/{id}/review
API->>AUTH : 校验当前用户(需管理员/经理)
AUTH-->>API : 通过
API->>SVC : review(assessment_id, reviewer_id, approved, remark)
SVC->>DB : 查询考核记录(状态=SUBMITTED)
DB-->>SVC : 考核记录
SVC->>DB : 更新状态/时间/备注
DB-->>SVC : 提交成功
SVC-->>API : 返回结果
API-->>C : 统一响应
```

图表来源
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L118-L145)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L172-L192)
- [backend/app/models/models.py](file://backend/app/models/models.py#L149-L178)

章节来源
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L438)
- [backend/app/core/database.py](file://backend/app/core/database.py#L1-L39)
- [backend/app/core/config.py](file://backend/app/core/config.py#L1-L47)

### 数据库层存储与查询优化
- 异步 ORM 与依赖注入
  - 使用 async_session_maker 管理会话生命周期，确保异常时回滚与关闭
- 索引与约束
  - 模型层面为高频查询字段建立索引（如部门类型、员工状态、考核记录的 staff/period/status 等）
  - 使用 CheckConstraint 等约束保证数据完整性
- 查询优化建议
  - 使用 selectinload 预加载关联对象，减少 N+1 查询
  - 列表查询结合分页与条件过滤，避免一次性加载全量数据
  - 对高并发场景适当调整数据库连接池大小与超时参数

章节来源
- [backend/app/core/database.py](file://backend/app/core/database.py#L1-L39)
- [backend/app/models/models.py](file://backend/app/models/models.py#L82-L85)
- [backend/app/models/models.py](file://backend/app/models/models.py#L111-L114)
- [backend/app/models/models.py](file://backend/app/models/models.py#L174-L178)
- [backend/app/models/models.py](file://backend/app/models/models.py#L227-L230)
- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L22)

### 典型业务场景数据流示例

#### 场景一：批量创建考核
- 前端
  - 打开批量创建对话框，选择科室、考核周期与指标集合
  - 调用批量创建接口，后端按科室在职员工生成考核记录并写入明细
- 后端
  - 服务层查询在职员工，去重检查后批量创建
  - 返回创建数量与成功状态

```mermaid
sequenceDiagram
participant V as "Assessments.vue"
participant A as "API 封装"
participant API as "Assessments API"
participant SVC as "AssessmentService"
participant DB as "数据库"
V->>A : batchCreateAssessments({department_id, period_year, period_month, indicators})
A->>API : POST /api/v1/assessments/batch-create
API->>SVC : batch_create_for_department(...)
SVC->>DB : 查询在职员工
SVC->>DB : 检查是否存在
SVC->>DB : 批量插入Assessment/AssessmentDetail
DB-->>SVC : 插入成功
SVC-->>API : 返回数量
API-->>A : 统一响应
A-->>V : 刷新列表
```

图表来源
- [frontend/src/views/assessment/Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L257-L286)
- [frontend/src/api/assessment.js](file://frontend/src/api/assessment.js#L38-L49)
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L148-L165)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L208-L262)

#### 场景二：财务核算数据展示与编辑
- 前端
  - 选择科室与月份，加载收入/支出/汇总与结余数据
  - 支持新增/编辑/删除财务记录，统一金额格式化显示
- 后端
  - 提供收入/支出查询、结余汇总、科室汇总、类别枚举等接口
  - 服务层按条件过滤与聚合，返回结构化结果

```mermaid
sequenceDiagram
participant V as "Finance.vue"
participant A as "API 封装"
participant API as "Finance API"
participant DB as "数据库"
V->>A : getRevenue/getExpense/getBalance/getDepartmentSummary
A->>API : GET /api/v1/finance/*
API->>DB : 查询/聚合
DB-->>API : 结果集
API-->>A : 统一响应
A-->>V : 渲染汇总与表格
V->>A : create/update/delete
A->>API : POST/PUT/DELETE
API->>DB : 写入/更新/删除
DB-->>API : 成功
API-->>A : 统一响应
A-->>V : 刷新数据
```

图表来源
- [frontend/src/views/finance/Finance.vue](file://frontend/src/views/finance/Finance.vue#L329-L384)
- [frontend/src/views/finance/Finance.vue](file://frontend/src/views/finance/Finance.vue#L451-L505)
- [backend/app/models/finance.py](file://backend/app/models/finance.py#L45-L74)

章节来源
- [frontend/src/views/assessment/Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L1-L311)
- [frontend/src/views/finance/Finance.vue](file://frontend/src/views/finance/Finance.vue#L1-L614)
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L148-L165)
- [backend/app/models/finance.py](file://backend/app/models/finance.py#L1-L79)

## 依赖关系分析
- 前端
  - main.js 作为入口，注册 Pinia 与路由
  - router/index.js 定义路由与守卫
  - stores/* 提供用户与应用状态
  - api/* 封装请求，视图组件通过 API 调用后端
- 后端
  - app/main.py 创建 FastAPI 实例，注册路由与异常处理
  - api/v1/__init__.py 聚合各模块路由
  - api/v1/assessments.py 定义具体接口与依赖注入
  - services/assessment_service.py 实现业务逻辑
  - models/models.py 定义数据模型与索引
  - core/database.py 提供异步数据库依赖
  - core/config.py 提供配置项

```mermaid
graph LR
FE_Main["frontend/src/main.js"] --> FE_Router["frontend/src/router/index.js"]
FE_Router --> FE_Views["frontend/src/views/*"]
FE_Views --> FE_API["frontend/src/api/*"]
FE_API --> BE_App["backend/app/main.py"]
BE_App --> BE_Router["backend/app/api/v1/__init__.py"]
BE_Router --> BE_API_Assess["backend/app/api/v1/assessments.py"]
BE_API_Assess --> BE_Service["backend/app/services/assessment_service.py"]
BE_Service --> BE_Models["backend/app/models/models.py"]
BE_Models --> BE_DB["backend/app/core/database.py"]
BE_App --> BE_Config["backend/app/core/config.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/index.js](file://frontend/src/api/index.js#L1-L9)
- [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/assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L438)
- [backend/app/core/database.py](file://backend/app/core/database.py#L1-L39)
- [backend/app/core/config.py](file://backend/app/core/config.py#L1-L47)

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

## 性能考虑
- 前端
  - 并行加载：视图组件使用 Promise.all 并行请求多个接口，减少等待时间
  - 分页与缓存：合理设置分页大小，避免一次性加载过多数据；对不频繁变动的数据（如科室树）可做本地缓存
  - 响应式更新：仅在必要时刷新列表，避免不必要的重渲染
- 后端
  - 预加载与索引：使用 selectinload 减少 N+1 查询；为高频查询字段建立索引
  - 事务与连接池：利用异步会话工厂与连接池提升吞吐；异常时及时回滚
  - 分页与过滤：接口层严格限制 page_size，防止大页扫描
- 数据库
  - 连接池参数：根据并发与硬件资源调整 pool_size 与 max_overflow
  - 索引策略：针对过滤条件与排序字段建立复合索引，避免全表扫描

章节来源
- [frontend/src/views/assessment/Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L377-L384)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L28-L55)
- [backend/app/core/database.py](file://backend/app/core/database.py#L10-L20)
- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L22)
- [backend/app/models/models.py](file://backend/app/models/models.py#L82-L85)

## 故障排查指南
- 登录失败
  - 检查前端 Store 是否正确保存 token，查看浏览器本地存储
  - 后端异常日志：关注 HTTP 异常与请求验证异常处理器输出
- 接口报错
  - 核对请求路径与参数是否符合后端接口定义（如批量创建的重复查询参数）
  - 查看后端统一异常处理日志，定位具体错误位置
- 数据不一致
  - 确认服务层事务边界与回滚逻辑，检查数据库约束与索引是否生效
- 性能问题
  - 前端：检查是否存在串行请求，是否可以并行加载
  - 后端：确认查询是否命中索引，分页参数是否合理

章节来源
- [frontend/src/stores/user.js](file://frontend/src/stores/user.js#L10-L31)
- [backend/app/main.py](file://backend/app/main.py#L58-L74)
- [frontend/src/api/assessment.js](file://frontend/src/api/assessment.js#L38-L49)
- [backend/app/models/models.py](file://backend/app/models/models.py#L144-L146)

## 结论
本系统通过清晰的前后端职责划分与统一的异常处理机制，实现了从用户交互到数据库持久化的稳定数据流。前端以 Pinia 管理状态与响应式更新，后端以服务层封装业务逻辑并配合 ORM 索引与连接池实现高效查询。建议在高并发场景下进一步优化索引与连接池参数，并持续监控日志与性能指标以保障系统稳定性。

## 附录
- 关键接口与模型概览
  - 考核相关：Assessments API、AssessmentService、Assessment/AssessmentDetail 模型
  - 财务相关：Finance 模型、Finance API
  - 数据库：异步引擎与会话工厂、索引与约束
- 开发与部署建议
  - 前端：使用环境变量区分开发/生产，开启生产模式构建
  - 后端：使用 .env 文件管理敏感配置，启用健康检查与日志轮转