Files

2026-02-28 15:16:15 +08:00

18 KiB

Raw Blame History

系统架构

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

简介

本系统为“医院绩效管理系统”，采用前后端分离架构，后端基于 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

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

图表来源

章节来源

核心组件

应用入口与生命周期
- 后端通过 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 封装统一请求/响应拦截与错误提示。

章节来源

架构总览

系统采用“前后端分离 + 分层架构 + 微服务理念（按功能域拆分 API）”：

展示层：Vue 3 单页应用，Element Plus 组件库，Pinia 状态管理。
控制层：FastAPI 路由与依赖注入，OAuth2/JWT 认证，CORS 放通。
业务层：服务类封装业务规则与流程（如考核状态机）。
数据层：SQLAlchemy 2.0 ORM + 异步数据库连接，PostgreSQL。
数据模型：强类型枚举与关系映射，确保数据一致性与可维护性。

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/>枚举/关系"]

图表来源

详细组件分析

认证与授权组件

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

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

图表来源

章节来源

绩效考核组件

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

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

图表来源

章节来源

员工管理组件

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

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 : "属于"

图表来源

章节来源

数据模型与关系

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

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

章节来源

backend/app/models/models.py

前后端交互与路由

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

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 : 渲染页面

图表来源

章节来源

依赖关系分析

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

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

图表来源

章节来源

性能考虑

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

故障排查指南

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

章节来源

结论

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

附录

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

18 KiB Raw Blame History Unescape Escape

系统架构

目录

简介

项目结构

核心组件

架构总览

详细组件分析

认证与授权组件

绩效考核组件

员工管理组件

数据模型与关系

前后端交互与路由

依赖关系分析

性能考虑

故障排查指南

结论

附录

18 KiB

Raw Blame History