chenqi/hospital_performance
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
fd53ff36a89fa32a6914edcf2d4357326ac85a2f
hospital_performance/.qoder/repowiki/zh/content/系统架构/数据流架构.md
chenqi 44f250f58e 提交文件
2026-02-28 15:16:15 +08:00

21 KiB
Raw Blame History

数据流架构

**本文引用的文件** - [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)

目录

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

简介

本文件面向“医院绩效系统”的数据流架构，覆盖从前端用户交互到后端服务处理，再到数据库持久化的完整链路。重点说明：

  • 前端状态管理（Pinia Store）的状态变更、组件数据绑定与响应式更新机制
  • 后端服务层的数据处理流程（业务逻辑、数据验证、异常处理、结果返回）
  • 数据库层的数据存储与查询优化策略
  • 典型业务场景的数据流示例与性能优化建议

项目结构

系统采用前后端分离架构：

  • 前端基于 Vue 3 + Pinia + Element Plus，通过路由驱动页面导航与状态管理
  • 后端基于 FastAPI + SQLAlchemy 2.0 异步 ORM，提供 RESTful 接口与统一异常处理
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

图表来源

章节来源

核心组件

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

章节来源

架构总览

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

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 : 渲染表格与分页

图表来源

详细组件分析

前端状态管理与组件数据绑定

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

图表来源

章节来源

后端服务层数据处理流程

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

图表来源

章节来源

数据库层存储与查询优化

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

章节来源

典型业务场景数据流示例

场景一：批量创建考核

  • 前端
    • 打开批量创建对话框，选择科室、考核周期与指标集合
    • 调用批量创建接口，后端按科室在职员工生成考核记录并写入明细
  • 后端
    • 服务层查询在职员工，去重检查后批量创建
    • 返回创建数量与成功状态
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 : 刷新列表

图表来源

场景二：财务核算数据展示与编辑

  • 前端
    • 选择科室与月份，加载收入/支出/汇总与结余数据
    • 支持新增/编辑/删除财务记录，统一金额格式化显示
  • 后端
    • 提供收入/支出查询、结余汇总、科室汇总、类别枚举等接口
    • 服务层按条件过滤与聚合，返回结构化结果
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 : 刷新数据

图表来源

章节来源

依赖关系分析

  • 前端
    • 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 提供配置项
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"]

图表来源

章节来源

性能考虑

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

章节来源

故障排查指南

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

章节来源

结论

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

附录

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