18 KiB
18 KiB
系统管理接口
**本文档引用的文件** - [performance_plans.py](file://backend/app/api/v1/performance_plans.py) - [menus.py](file://backend/app/api/v1/menus.py) - [templates.py](file://backend/app/api/v1/templates.py) - [performance_plan_service.py](file://backend/app/services/performance_plan_service.py) - [menu_service.py](file://backend/app/services/menu_service.py) - [template_service.py](file://backend/app/services/template_service.py) - [models.py](file://backend/app/models/models.py) - [schemas.py](file://backend/app/schemas/schemas.py) - [security.py](file://backend/app/core/security.py) - [database.py](file://backend/app/core/database.py) - [main.py](file://backend/app/main.py) - [config.py](file://backend/app/core/config.py) - [001_initial.py](file://backend/alembic/versions/001_initial.py) - [002_template.py](file://backend/alembic/versions/002_template.py) - [init_templates.py](file://backend/app/scripts/init_templates.py) - [logging_config.py](file://backend/app/core/logging_config.py)目录
简介
本文件面向系统管理接口，围绕绩效计划管理、菜单权限和模板管理三大核心领域，系统化梳理后端API实现、数据模型、服务层逻辑与安全控制机制。文档同时覆盖系统配置的动态管理、角色权限控制、菜单树结构、模板版本与继承、系统初始化与数据迁移、配置备份、日志审计与安全监控，以及性能监控、资源管理与故障恢复策略。
项目结构
后端采用FastAPI + SQLAlchemy 2.0 + 异步数据库的现代架构，按功能域划分API路由、服务层与数据模型，配合Alembic进行数据库版本管理，支持系统初始化脚本与模板数据注入。
graph TB
subgraph "应用入口"
MAIN["app/main.py"]
CONFIG["app/core/config.py"]
LOGCFG["app/core/logging_config.py"]
end
subgraph "API层"
PERF_API["app/api/v1/performance_plans.py"]
MENU_API["app/api/v1/menus.py"]
TPL_API["app/api/v1/templates.py"]
end
subgraph "服务层"
PERF_SRV["app/services/performance_plan_service.py"]
MENU_SRV["app/services/menu_service.py"]
TPL_SRV["app/services/template_service.py"]
end
subgraph "核心模块"
SEC["app/core/security.py"]
DB["app/core/database.py"]
end
subgraph "数据模型与迁移"
MODELS["app/models/models.py"]
ALEMBIC1["backend/alembic/versions/001_initial.py"]
ALEMBIC2["backend/alembic/versions/002_template.py"]
end
MAIN --> PERF_API
MAIN --> MENU_API
MAIN --> TPL_API
PERF_API --> PERF_SRV
MENU_API --> MENU_SRV
TPL_API --> TPL_SRV
PERF_SRV --> MODELS
MENU_SRV --> MODELS
TPL_SRV --> MODELS
PERF_API --> SEC
MENU_API --> SEC
TPL_API --> SEC
PERF_API --> DB
MENU_API --> DB
TPL_API --> DB
CONFIG --> MAIN
LOGCFG --> MAIN
ALEMBIC1 --> MODELS
ALEMBIC2 --> MODELS
图表来源
- main.py
- performance_plans.py
- menus.py
- templates.py
- performance_plan_service.py
- menu_service.py
- template_service.py
- models.py
- config.py
- logging_config.py
- 001_initial.py
- 002_template.py
章节来源
核心组件
- 绩效计划管理API：提供计划的CRUD、状态流转、指标关联、树形结构与统计查询。
- 菜单管理API：提供菜单树、列表、详情、创建/更新/删除与默认菜单初始化。
- 指标模板管理API：提供模板与模板指标的CRUD、批量导入、维度与类型枚举。
- 服务层：封装业务逻辑，统一处理状态机、关联关系与查询优化。
- 数据模型：定义实体、枚举与索引，支撑多维考核与组织结构。
- 安全与配置：JWT认证、权限校验、数据库连接与日志配置。
章节来源
- performance_plans.py
- menus.py
- templates.py
- performance_plan_service.py
- menu_service.py
- template_service.py
- models.py
- schemas.py
- security.py
- database.py
架构概览
系统采用分层架构：API层负责请求解析与响应封装；服务层承载业务规则与状态机；模型层定义数据结构与约束；核心模块提供安全、数据库与配置能力。API层通过依赖注入获取数据库会话与当前用户，确保权限控制与事务一致性。
sequenceDiagram
participant Client as "客户端"
participant API as "API控制器"
participant Service as "服务层"
participant Model as "数据模型"
participant DB as "数据库"
Client->>API : 发起请求(携带JWT)
API->>API : 依赖注入(get_db, get_current_active_user)
API->>Service : 调用业务方法(带参数)
Service->>DB : 查询/更新(ORM操作)
DB-->>Service : 返回结果
Service-->>API : 业务结果
API-->>Client : 统一响应格式
图表来源
详细组件分析
绩效计划管理
- 功能范围：计划列表、树形结构、统计、详情、创建、更新、提交、审批、激活、删除、指标关联增删改。
- 状态机：草稿 → 待审批 → 已批准 → 执行中 → 已完成/已取消；拒绝后可重新提交。
- 关键点：指标关联支持目标值、权重、评分方法与参数；支持父子计划形成树形层级。
- 权限控制：提交、审批、激活、删除等操作需管理员或经理权限。
stateDiagram-v2
[*] --> 草稿
草稿 --> 待审批 : "提交"
待审批 --> 已批准 : "审批通过"
待审批 --> 已驳回 : "审批驳回"
已批准 --> 执行中 : "激活"
执行中 --> 已完成 : "完成"
执行中 --> 已取消 : "取消"
已驳回 --> 草稿 : "重新提交"
图表来源
章节来源
菜单权限管理
- 功能范围：菜单树、列表、详情、创建、更新、删除、默认菜单初始化。
- 树形结构：支持父子关系与可见性过滤；支持按钮级权限标识。
- 权限控制：创建/更新/删除/初始化默认菜单需管理员或经理权限。
flowchart TD
Start(["获取菜单树"]) --> Query["查询根节点(父ID为空)"]
Query --> Filter["按可见性/启用过滤"]
Filter --> Order["按排序与ID排序"]
Order --> Build["递归构建树结构(children)"]
Build --> End(["返回树形结构"])
图表来源
章节来源
指标模板管理
- 功能范围：模板列表、详情、类型与维度枚举、创建、更新、删除；模板指标的增删改与批量导入。
- 版本与继承：模板具备版本号与激活状态；模板指标支持分类、权重、排序与评分参数。
- 初始化：提供脚本批量注入标准模板与指标数据，支持维度权重与评估周期配置。
classDiagram
class IndicatorTemplate {
+template_code
+template_name
+template_type
+dimension_weights
+assessment_cycle
+is_active
+created_at
+updated_at
}
class TemplateIndicator {
+template_id
+indicator_id
+category
+weight
+sort_order
+scoring_method
+scoring_params
+remark
}
class Indicator {
+code
+name
+indicator_type
+bs_dimension
+weight
+max_score
+calculation_method
+assessment_method
+is_veto
}
IndicatorTemplate "1" o-- "*" TemplateIndicator : "包含"
Indicator "1" o-- "*" TemplateIndicator : "被引用"
图表来源
章节来源
数据模型与枚举
- 组织与人员：Department、Staff、User，支持层级与状态管理。
- 考核与工资：Assessment、AssessmentDetail、SalaryRecord，支持周期与状态。
- 计划与指标：PerformancePlan、PlanKpiRelation，支持层级与父子关系。
- 菜单与模板：Menu、IndicatorTemplate、TemplateIndicator，支持树形与关联。
- 枚举：科室类型、指标类型、状态、计划层级与菜单类型等。
章节来源
安全与权限控制
- JWT认证：OAuth2密码模式，支持令牌签发、解码与用户解析。
- 权限校验：当前用户、激活用户、管理员、管理员或经理。
- 依赖注入：API层通过Depends获取数据库会话与当前用户，确保每个请求的安全上下文。
章节来源
系统配置与数据库
- 配置中心：应用名、版本、API前缀、数据库URL、JWT密钥与过期时间、跨域白名单、分页参数。
- 数据库：异步引擎与会话工厂，自动事务提交/回滚与关闭。
- 迁移：初始版本创建核心表，模板版本增加指标模板与关联表，并扩展指标字段。
章节来源
依赖分析
- API层依赖服务层与安全模块，通过依赖注入获取数据库会话与当前用户。
- 服务层依赖数据模型与SQLAlchemy ORM，封装查询、状态机与事务。
- 数据模型定义实体关系与索引，支撑高效查询与数据完整性。
- 迁移脚本定义数据库演进路径，确保版本一致与数据安全。
graph LR
PERF_API["performance_plans.py"] --> PERF_SRV["performance_plan_service.py"]
MENU_API["menus.py"] --> MENU_SRV["menu_service.py"]
TPL_API["templates.py"] --> TPL_SRV["template_service.py"]
PERF_SRV --> MODELS["models.py"]
MENU_SRV --> MODELS
TPL_SRV --> MODELS
PERF_API --> SEC["security.py"]
MENU_API --> SEC
TPL_API --> SEC
PERF_API --> DB["database.py"]
MENU_API --> DB
TPL_API --> DB
ALEMBIC1["001_initial.py"] --> MODELS
ALEMBIC2["002_template.py"] --> MODELS
图表来源
- performance_plans.py
- menus.py
- templates.py
- performance_plan_service.py
- menu_service.py
- template_service.py
- models.py
- 001_initial.py
- 002_template.py
章节来源
- performance_plans.py
- menus.py
- templates.py
- performance_plan_service.py
- menu_service.py
- template_service.py
性能考虑
- 异步数据库：使用异步引擎与会话，提升高并发下的IO吞吐。
- 查询优化：服务层使用selectinload预加载关联，减少N+1查询；索引覆盖常用查询字段。
- 分页与限制：API层对分页参数进行范围校验，避免过大页大小影响性能。
- 缓存策略：建议在热点读取场景引入Redis缓存（如菜单树、模板列表），降低数据库压力。
- 连接池：合理配置数据库连接池大小与溢出，避免连接争用。
[本节为通用指导，无需特定文件引用]
故障排查指南
- 日志系统：应用日志与错误日志分离，按日期轮转，便于定位问题。
- 异常处理：全局异常捕获与记录，HTTP异常与参数校验异常分别处理。
- 数据一致性：服务层事务提交/回滚，确保状态变更原子性。
- 权限问题：确认JWT令牌有效、用户状态正常、角色满足要求。
- 数据迁移：检查Alembic版本与数据库一致，必要时执行升级/降级。
章节来源
结论
本系统管理接口围绕绩效计划、菜单权限与模板管理构建了完整的API体系，配合严谨的数据模型、服务层状态机与安全控制，实现了可配置、可扩展、可审计的医院绩效管理体系。通过完善的初始化与迁移机制、日志与异常处理、以及性能与故障恢复策略，系统具备良好的稳定性与可维护性。
[本节为总结，无需特定文件引用]
附录
API端点速览
-
绩效计划
- GET /plans：获取计划列表
- GET /plans/tree：获取计划树
- GET /plans/stats：获取计划统计
- GET /plans/{plan_id}：获取计划详情
- POST /plans：创建计划
- PUT /plans/{plan_id}：更新计划
- POST /plans/{plan_id}/submit：提交计划
- POST /plans/{plan_id}/approve：审批计划
- POST /plans/{plan_id}/activate：激活计划
- DELETE /plans/{plan_id}：删除计划
- POST /plans/{plan_id}/kpi-relations：添加指标关联
- PUT /plans/kpi-relations/{relation_id}：更新指标关联
- DELETE /plans/kpi-relations/{relation_id}：删除指标关联
-
菜单管理
- GET /menus/tree：获取菜单树
- GET /menus：获取菜单列表
- GET /menus/{menu_id}：获取菜单详情
- POST /menus：创建菜单
- PUT /menus/{menu_id}：更新菜单
- DELETE /menus/{menu_id}：删除菜单
- POST /menus/init：初始化默认菜单
-
指标模板
- GET /templates：获取模板列表
- GET /templates/types：获取模板类型列表
- GET /templates/dimensions：获取BSC维度列表
- GET /templates/{template_id}：获取模板详情
- POST /templates：创建模板
- PUT /templates/{template_id}：更新模板
- DELETE /templates/{template_id}：删除模板
- GET /templates/{template_id}/indicators：获取模板指标列表
- POST /templates/{template_id}/indicators：添加模板指标
- PUT /templates/{template_id}/indicators/{indicator_id}：更新模板指标
- DELETE /templates/{template_id}/indicators/{indicator_id}：移除模板指标
- POST /templates/{template_id}/indicators/batch：批量添加模板指标
章节来源
系统初始化与数据迁移
- 初始版本：创建科室、员工、指标、考核、工资、用户等核心表。
- 模板版本：新增指标模板与模板指标关联表，并扩展指标字段。
- 初始化脚本：批量创建标准模板与指标，支持维度权重与评估周期配置。
章节来源