Files

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

17 KiB

Raw Blame History

系统管理接口

**本文档引用的文件** - [backend/app/api/v1/menus.py](file://backend/app/api/v1/menus.py) - [backend/app/services/menu_service.py](file://backend/app/services/menu_service.py) - [backend/app/models/models.py](file://backend/app/models/models.py) - [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py) - [backend/app/core/security.py](file://backend/app/core/security.py) - [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py) - [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py) - [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py) - [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py) - [backend/app/services/department_service.py](file://backend/app/services/department_service.py) - [backend/app/core/logging_config.py](file://backend/app/core/logging_config.py) - [backend/app/main.py](file://backend/app/main.py) - [backend/app/core/config.py](file://backend/app/core/config.py) - [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py) - [frontend/src/router/index.js](file://frontend/src/router/index.js) - [frontend/src/views/system/Menus.vue](file://frontend/src/views/system/Menus.vue) - [frontend/dist/assets/menu-CltzMZXm.js](file://frontend/dist/assets/menu-CltzMZXm.js)

简介

本文档为医院绩效管理系统的系统管理接口提供全面的API文档。该系统采用FastAPI + SQLAlchemy 2.0架构，实现了完整的菜单权限管理、系统配置和用户角色管理功能。

系统的核心特性包括：

菜单权限管理：支持树形菜单结构的增删改查操作
RBAC权限控制：基于角色的访问控制模型
动态菜单生成：根据用户权限动态生成前端路由
系统配置管理：集中化的系统参数配置
日志管理和审计追踪：完整的操作日志记录
用户角色管理：灵活的角色权限模型

项目结构

系统采用分层架构设计，主要分为以下层次：

graph TB
subgraph "前端层"
FE_Router[Vue Router]
FE_API[API请求封装]
FE_Components[业务组件]
end
subgraph "后端层"
API_Router[FastAPI Router]
Security[安全认证]
Services[业务服务层]
Models[数据模型层]
Schemas[数据模式层]
end
subgraph "基础设施层"
Database[(PostgreSQL数据库)]
Logging[日志系统]
Config[配置管理]
end
FE_Router --> FE_API
FE_API --> API_Router
API_Router --> Security
API_Router --> Services
Services --> Models
Models --> Database
Services --> Schemas
API_Router --> Logging
API_Router --> Config

图表来源

章节来源

核心组件

菜单管理模块

菜单管理是系统权限控制的核心组件，提供了完整的菜单树形结构管理功能：

菜单树形结构：支持无限级菜单嵌套
权限标识：每个菜单可绑定特定的权限标识
动态显示：根据用户权限动态过滤可见菜单
排序控制：支持菜单排序和层级管理

用户认证与授权

系统实现了基于JWT的认证机制和RBAC权限控制：

多角色支持：admin(管理员)、manager(经理)、staff(普通员工)
权限验证：不同操作需要不同的权限级别
会话管理：Token过期自动失效

系统配置管理

集中化的配置管理确保了系统的灵活性和可维护性：

环境配置：支持多种部署环境
数据库连接池：优化数据库连接性能
CORS配置：灵活的跨域访问控制

章节来源

架构概览

系统采用经典的三层架构模式，确保了良好的可维护性和扩展性：

graph TB
subgraph "表现层"
Frontend[Vue.js前端]
Router[路由系统]
Store[状态管理]
end
subgraph "应用层"
API[FastAPI API]
Auth[认证服务]
MenuSvc[菜单服务]
StaffSvc[员工服务]
DeptSvc[科室服务]
end
subgraph "数据层"
ORM[SQLAlchemy ORM]
DB[(PostgreSQL)]
Redis[(Redis缓存)]
end
Frontend --> API
API --> Auth
API --> MenuSvc
API --> StaffSvc
API --> DeptSvc
MenuSvc --> ORM
StaffSvc --> ORM
DeptSvc --> ORM
ORM --> DB
Auth --> Redis

图表来源

详细组件分析

菜单权限管理API

菜单树形结构查询

系统提供了获取菜单树形结构的接口，支持根据权限过滤可见菜单：

sequenceDiagram
participant Client as "客户端"
participant API as "菜单API"
participant Service as "菜单服务"
participant DB as "数据库"
Client->>API : GET /menus/tree?visible_only=true
API->>Service : get_tree(visible_only=True)
Service->>DB : 查询根菜单
DB-->>Service : 返回菜单列表
Service->>Service : 递归构建树形结构
Service-->>API : 返回菜单树
API-->>Client : 菜单树形结构

图表来源

菜单增删改查操作

系统提供了完整的菜单管理操作接口：

接口	方法	路径	权限要求	功能描述
获取菜单树	GET	/menus/tree	任意用户	获取完整的菜单树形结构
获取菜单列表	GET	/menus	任意用户	获取菜单列表（可筛选）
获取菜单详情	GET	/menus/{menu_id}	任意用户	获取指定菜单详情
创建菜单	POST	/menus	管理员/经理	创建新的菜单项
更新菜单	PUT	/menus/{menu_id}	管理员/经理	更新现有菜单
删除菜单	DELETE	/menus/{menu_id}	管理员/经理	删除菜单项
初始化菜单	POST	/menus/init	管理员	初始化默认菜单结构

章节来源

backend/app/api/v1/menus.py

菜单数据模型

菜单系统的核心数据模型定义：

classDiagram
class Menu {
+int id
+int parent_id
+MenuType menu_type
+string menu_name
+string menu_icon
+string path
+string component
+string permission
+int sort_order
+bool is_visible
+bool is_active
+datetime created_at
+datetime updated_at
+Menu[] children
+Menu parent
}
class MenuType {
<<enumeration>>
MENU
BUTTON
}
Menu --> MenuType : uses
Menu --> Menu : parent_child

图表来源

backend/app/models/models.py

章节来源

backend/app/models/models.py

RBAC权限控制模型

角色权限架构

系统实现了基于角色的访问控制(RBAC)模型：

graph LR
subgraph "用户角色"
Admin[管理员 - admin]
Manager[经理 - manager]
Staff[员工 - staff]
end
subgraph "权限级别"
Level1[读取权限]
Level2[写入权限]
Level3[管理权限]
end
subgraph "权限矩阵"
MenuAccess[菜单访问]
UserManage[用户管理]
SystemConfig[系统配置]
end
Admin --> Level3
Manager --> Level2
Staff --> Level1
Level3 --> MenuAccess
Level3 --> UserManage
Level3 --> SystemConfig
Level2 --> MenuAccess
Level2 --> UserManage
Level1 --> MenuAccess

图表来源

backend/app/core/security.py

权限验证机制

系统通过装饰器实现权限验证：

装饰器	权限要求	用途
get_current_active_user	有效用户	基础用户验证
get_current_manager_user	管理员或经理	管理操作权限
get_current_admin_user	管理员	系统管理权限

章节来源

backend/app/core/security.py

用户角色管理

用户认证流程

sequenceDiagram
participant Client as "客户端"
participant AuthAPI as "认证API"
participant Security as "安全模块"
participant DB as "用户表"
participant Token as "JWT Token"
Client->>AuthAPI : POST /auth/login
AuthAPI->>Security : 验证用户名密码
Security->>DB : 查询用户信息
DB-->>Security : 返回用户数据
Security->>Security : 验证密码
Security->>Token : 生成访问令牌
Security-->>AuthAPI : 返回Token
AuthAPI-->>Client : {access_token, token_type}
Note over Client,Token : 用户登录成功

图表来源

员工管理API

系统提供了完整的员工信息管理功能：

接口	方法	路径	权限要求	功能描述
获取员工列表	GET	/staff	任意用户	获取员工列表（支持分页和筛选）
获取员工详情	GET	/staff/{staff_id}	任意用户	获取指定员工详情
创建员工	POST	/staff	管理员/经理	创建新员工
更新员工	PUT	/staff/{staff_id}	管理员/经理	更新员工信息
删除员工	DELETE	/staff/{staff_id}	管理员/经理	删除员工
科室员工列表	GET	/staff/department/{department_id}	任意用户	获取科室所有员工

章节来源

backend/app/api/v1/staff.py

科室管理API

科室树形结构管理

flowchart TD
Start([开始]) --> GetTree["获取科室树形结构"]
GetTree --> FilterType{"按类型筛选?"}
FilterType --> |是| ApplyFilter["应用类型过滤条件"]
FilterType --> |否| BuildTree["构建树形结构"]
ApplyFilter --> BuildTree
BuildTree --> ManualBuild["手动构建树节点"]
ManualBuild --> CheckParent{"检查父节点"}
CheckParent --> |有父节点| AddChild["添加到父节点"]
CheckParent --> |无父节点| AddRoot["添加到根节点"]
AddChild --> NextNode["处理下一个节点"]
AddRoot --> NextNode
NextNode --> MoreNodes{"还有节点?"}
MoreNodes --> |是| ManualBuild
MoreNodes --> |否| ReturnTree["返回树形结构"]
ReturnTree --> End([结束])

图表来源

backend/app/services/department_service.py

章节来源

系统配置管理

配置文件结构

系统采用集中式配置管理：

配置项	类型	默认值	描述
APP_NAME	string	"医院绩效考核管理系统"	应用名称
APP_VERSION	string	"1.0.0"	应用版本
DEBUG	boolean	true	调试模式
API_PREFIX	string	"/api/v1"	API前缀
DATABASE_URL	string	PostgreSQL连接串	数据库连接地址
SECRET_KEY	string	JWT密钥	JWT签名密钥
ACCESS_TOKEN_EXPIRE_MINUTES	integer	480	Token过期时间(分钟)

章节来源

backend/app/core/config.py

日志管理和审计追踪

日志系统架构

graph TB
subgraph "日志级别"
INFO[INFO - 控制台输出]
DEBUG[DEBUG - 文件输出]
ERROR[ERROR - 错误文件输出]
end
subgraph "日志处理器"
ConsoleHandler[控制台处理器]
FileHandler[文件处理器]
ErrorHandler[错误处理器]
end
subgraph "日志文件"
AppLog[app_YYYYMMDD.log]
ErrorLog[error_YYYYMMDD.log]
end
INFO --> ConsoleHandler
DEBUG --> FileHandler
ERROR --> ErrorHandler
ConsoleHandler --> AppLog
FileHandler --> AppLog
ErrorHandler --> ErrorLog

图表来源

backend/app/core/logging_config.py

章节来源

backend/app/core/logging_config.py

依赖关系分析

前后端交互关系

系统实现了前后端分离的架构模式：

graph LR
subgraph "前端应用"
Router[Vue Router]
API[API封装]
Components[业务组件]
end
subgraph "后端服务"
FastAPI[FastAPI应用]
Auth[认证中间件]
MenuAPI[菜单API]
StaffAPI[员工API]
DeptAPI[科室API]
end
subgraph "外部服务"
PostgreSQL[(PostgreSQL)]
Redis[(Redis)]
end
Router --> API
API --> FastAPI
FastAPI --> Auth
FastAPI --> MenuAPI
FastAPI --> StaffAPI
FastAPI --> DeptAPI
MenuAPI --> PostgreSQL
StaffAPI --> PostgreSQL
DeptAPI --> PostgreSQL
Auth --> Redis

图表来源

菜单权限与前端路由同步

系统实现了菜单权限与前端路由的实时同步机制：

sequenceDiagram
participant FE as "前端应用"
participant API as "后端API"
participant MenuSvc as "菜单服务"
participant Store as "状态管理"
FE->>Store : 请求菜单权限
Store->>API : GET /menus/tree
API->>MenuSvc : get_tree(visible_only=True)
MenuSvc->>MenuSvc : 过滤可见菜单
MenuSvc->>MenuSvc : 构建权限树
MenuSvc-->>API : 返回权限菜单树
API-->>Store : 菜单权限数据
Store->>Store : 更新路由配置
Store-->>FE : 渲染权限路由
Note over FE,Store : 实时权限更新

图表来源

章节来源

性能考虑

数据库优化策略

系统采用了多项数据库优化措施：

连接池管理：配置合理的连接池大小，避免连接过多导致的性能问题
索引优化：为常用查询字段建立索引，提高查询效率
异步操作：使用异步数据库操作，提升并发处理能力
查询优化：使用selectinload进行关联查询，避免N+1查询问题

缓存策略

系统实现了多层次的缓存机制：

Redis缓存：用于存储用户会话和热点数据
数据库查询缓存：缓存常用的查询结果
静态资源缓存：前端静态资源的长期缓存

性能监控

系统提供了基本的性能监控能力：

健康检查：提供系统健康状态检查接口
日志监控：详细的日志记录和错误追踪
异常处理：完善的异常处理和错误恢复机制

故障排除指南

常见问题诊断

认证相关问题

问题症状	可能原因	解决方案
登录失败	用户名或密码错误	检查用户凭据是否正确
Token过期	访问令牌超时	重新登录获取新Token
权限不足	用户角色权限不够	检查用户角色配置

菜单权限问题

问题症状	可能原因	解决方案
菜单不显示	权限过滤导致	检查菜单的is_visible和is_active状态
路由无法访问	权限标识不匹配	验证菜单的permission字段
菜单层级错误	父子关系配置错误	检查parent_id字段设置

数据库连接问题

问题症状	可能原因	解决方案
连接超时	数据库负载过高	检查数据库连接池配置
查询缓慢	缺少索引	为常用查询字段添加索引
连接数过多	未正确关闭连接	检查数据库连接管理

章节来源

backend/app/core/logging_config.py

系统监控接口

系统提供了基本的监控和诊断接口：

健康检查：GET /health - 检查系统运行状态
日志查看：系统自动记录应用日志和错误日志
配置检查：验证系统配置的有效性

结论

本系统管理接口文档详细介绍了医院绩效管理系统的菜单权限管理、用户角色管理和系统配置功能。系统采用现代化的技术栈和架构设计，实现了：

完整的权限控制：基于RBAC的细粒度权限管理
灵活的菜单系统：支持树形结构和动态权限过滤
可靠的认证机制：基于JWT的安全认证
完善的日志系统：全面的操作审计和错误追踪
良好的扩展性：清晰的分层架构便于功能扩展

通过本文档，开发者可以快速理解和使用系统管理接口，同时为系统的进一步开发和维护提供了清晰的指导。

17 KiB Raw Blame History Unescape Escape

系统管理接口

目录

简介

项目结构

核心组件

菜单管理模块

用户认证与授权

系统配置管理

架构概览

详细组件分析

菜单权限管理API

菜单树形结构查询

菜单增删改查操作

菜单数据模型

RBAC权限控制模型

角色权限架构

权限验证机制

用户角色管理

用户认证流程

员工管理API

科室管理API

科室树形结构管理

系统配置管理

配置文件结构

日志管理和审计追踪

日志系统架构

依赖关系分析

前后端交互关系

菜单权限与前端路由同步

性能考虑

数据库优化策略

缓存策略

性能监控

故障排除指南

常见问题诊断

认证相关问题

菜单权限问题

数据库连接问题

系统监控接口

结论

17 KiB

Raw Blame History