提交文件
This commit is contained in:
462
.qoder/repowiki/zh/content/数据模型详解/枚举类型定义.md
Normal file
462
.qoder/repowiki/zh/content/数据模型详解/枚举类型定义.md
Normal file
@@ -0,0 +1,462 @@
|
||||
# 枚举类型定义
|
||||
|
||||
<cite>
|
||||
**本文档引用的文件**
|
||||
- [models.py](file://backend/app/models/models.py)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py)
|
||||
- [stats_service.py](file://backend/app/services/stats_service.py)
|
||||
- [assessment_service.py](file://backend/app/services/assessment_service.py)
|
||||
- [init_indicator_templates.py](file://backend/init_indicator_templates.py)
|
||||
- [indicators.py](file://backend/app/api/v1/indicators.py)
|
||||
- [stats.py](file://backend/app/api/v1/stats.py)
|
||||
- [IMPLEMENTATION_SUMMARY.md](file://IMPLEMENTATION_SUMMARY.md)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心枚举类型](#核心枚举类型)
|
||||
4. [架构概览](#架构概览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考虑](#性能考虑)
|
||||
8. [故障排除指南](#故障排除指南)
|
||||
9. [结论](#结论)
|
||||
|
||||
## 简介
|
||||
|
||||
本文档详细介绍了医院绩效管理系统中的所有自定义枚举类型。这些枚举类型是系统的核心数据结构，用于定义和约束业务实体的状态和分类。系统包含五个主要的枚举类型：科室类型（DeptType）、平衡计分卡维度（BSCDimension）、员工状态（StaffStatus）、考核状态（AssessmentStatus）和指标类型（IndicatorType）。
|
||||
|
||||
这些枚举类型不仅在数据库模型中使用，还在API接口、服务层逻辑、统计分析和前端展示等多个层面发挥重要作用，确保了整个系统的数据一致性和业务规则的正确执行。
|
||||
|
||||
## 项目结构
|
||||
|
||||
系统采用典型的三层架构设计，枚举类型分布在不同的层次中：
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "数据访问层"
|
||||
Models[models.py<br/>数据库模型]
|
||||
end
|
||||
subgraph "业务逻辑层"
|
||||
Services[services/<br/>服务层]
|
||||
StatsService[stats_service.py<br/>统计服务]
|
||||
AssessmentService[assessment_service.py<br/>考核服务]
|
||||
end
|
||||
subgraph "表示层"
|
||||
API[api/v1/<br/>API接口]
|
||||
IndicatorsAPI[indicators.py<br/>指标API]
|
||||
StatsAPI[stats.py<br/>统计API]
|
||||
Schemas[schemas.py<br/>数据模式]
|
||||
end
|
||||
subgraph "初始化数据"
|
||||
InitTemplates[init_indicator_templates.py<br/>指标模板]
|
||||
end
|
||||
Models --> Services
|
||||
Services --> API
|
||||
Schemas --> API
|
||||
InitTemplates --> Models
|
||||
StatsService --> Models
|
||||
AssessmentService --> Models
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [models.py](file://backend/app/models/models.py#L15-L61)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L12-L44)
|
||||
- [stats_service.py](file://backend/app/services/stats_service.py#L16-L218)
|
||||
- [assessment_service.py](file://backend/app/services/assessment_service.py#L160-L263)
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L1-L438)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L1-L743)
|
||||
|
||||
## 核心枚举类型
|
||||
|
||||
### 科室类型（DeptType）
|
||||
|
||||
科室类型枚举定义了医院中各种类型的科室分类，从最初的5种扩展到了9种现代医院组织结构。
|
||||
|
||||
| 枚举值 | 值 | 描述 | 适用场景 |
|
||||
|--------|-----|------|----------|
|
||||
| CLINICAL_SURGICAL | clinical_surgical | 手术临床科室 | 外科、骨科、心胸外科等需要手术治疗的科室 |
|
||||
| CLINICAL_NONSURGICAL_WARD | clinical_nonsurgical_ward | 非手术有病房科室 | 内科、儿科、神经内科等有病床的临床科室 |
|
||||
| CLINICAL_NONSURGICAL_NOWARD | clinical_nonsurgical_noward | 非手术无病房科室 | 急诊科、门诊部等无病床的临床科室 |
|
||||
| MEDICAL_TECH | medical_tech | 医技科室 | 检验科、放射科、超声科等医学技术科室 |
|
||||
| MEDICAL_AUXILIARY | medical_auxiliary | 医辅科室 | 病理科、输血科等辅助医疗科室 |
|
||||
| NURSING | nursing | 护理单元 | 各病区护理单元 |
|
||||
| ADMIN | admin | 行政科室 | 人事科、财务科、办公室等行政部门 |
|
||||
| FINANCE | finance | 财务科室 | 财务科、审计科等财务管理部门 |
|
||||
| LOGISTICS | logistics | 后勤保障科室 | 设备科、总务科、保卫科等后勤部门 |
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L16-L27)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L12-L22)
|
||||
|
||||
### 平衡计分卡维度（BSCDimension）
|
||||
|
||||
平衡计分卡维度枚举提供了四个关键的绩效评估维度，支持全面的组织绩效管理。
|
||||
|
||||
| 枚举值 | 值 | 描述 | 业务意义 |
|
||||
|--------|-----|------|----------|
|
||||
| FINANCIAL | financial | 财务维度 | 关注财务表现和经济效益，如收入增长、成本控制 |
|
||||
| CUSTOMER | customer | 客户维度 | 关注患者满意度和服务质量，如服务态度、治疗效果 |
|
||||
| INTERNAL_PROCESS | internal_process | 内部流程维度 | 关注运营效率和质量控制，如流程标准化、安全指标 |
|
||||
| LEARNING_GROWTH | learning_growth | 学习与成长维度 | 关注员工发展和组织能力提升，如培训参与、技术创新 |
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L29-L35)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L98-L104)
|
||||
|
||||
### 员工状态（StaffStatus）
|
||||
|
||||
员工状态枚举定义了员工在组织中的不同状态，支持完整的人力资源管理。
|
||||
|
||||
| 枚举值 | 值 | 描述 | 业务规则 |
|
||||
|--------|-----|------|----------|
|
||||
| ACTIVE | active | 在职 | 可参与考核、享受绩效奖金 |
|
||||
| LEAVE | leave | 休假 | 暂停考核，保留绩效记录 |
|
||||
| RESIGNED | resigned | 离职 | 不再参与考核，绩效记录归档 |
|
||||
| RETIRED | retired | 退休 | 不再参与考核，仅保留历史记录 |
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L37-L43)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L24-L29)
|
||||
|
||||
### 考核状态（AssessmentStatus）
|
||||
|
||||
考核状态枚举实现了完整的考核流程管理，支持多级审核和状态追踪。
|
||||
|
||||
| 枚举值 | 值 | 描述 | 流程作用 |
|
||||
|--------|-----|------|----------|
|
||||
| DRAFT | draft | 草稿 | 初始状态，允许修改和补充 |
|
||||
| SUBMITTED | submitted | 已提交 | 完成填写，等待审核 |
|
||||
| REVIEWED | reviewed | 已审核 | 审核通过，等待最终确认 |
|
||||
| FINALIZED | finalized | 已确认 | 最终状态，生成正式结果 |
|
||||
| REJECTED | rejected | 已驳回 | 审核不通过，需要重新提交 |
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L45-L52)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L31-L37)
|
||||
|
||||
### 指标类型（IndicatorType）
|
||||
|
||||
指标类型枚举从5种扩展到8种，支持更全面的绩效管理需求。
|
||||
|
||||
| 枚举值 | 值 | 描述 | 适用场景 |
|
||||
|--------|-----|------|----------|
|
||||
| QUALITY | quality | 质量指标 | 关注工作质量和标准达成度 |
|
||||
| QUANTITY | quantity | 数量指标 | 关注工作量和产出数量 |
|
||||
| EFFICIENCY | efficiency | 效率指标 | 关注工作效率和资源利用 |
|
||||
| SERVICE | service | 服务指标 | 关注服务质量和服务水平 |
|
||||
| COST | cost | 成本指标 | 关注成本控制和费用管理 |
|
||||
| SAFETY | safety | 安全指标 | 关注医疗安全和风险管理 |
|
||||
| LEARNING | learning | 学习成长指标 | 关注员工培训和发展 |
|
||||
| COMPLIANCE | compliance | 合规指标 | 关注规章制度执行 |
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L54-L61)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L39-L44)
|
||||
|
||||
## 架构概览
|
||||
|
||||
枚举类型在整个系统中的应用架构如下：
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "数据模型层"
|
||||
DeptTypeModel[DeptType<br/>科室类型模型]
|
||||
BSCDimensionModel[BSCDimension<br/>平衡计分卡维度]
|
||||
StaffStatusModel[StaffStatus<br/>员工状态模型]
|
||||
AssessmentStatusModel[AssessmentStatus<br/>考核状态模型]
|
||||
IndicatorTypeModel[IndicatorType<br/>指标类型模型]
|
||||
end
|
||||
subgraph "业务逻辑层"
|
||||
AssessmentService[AssessmentService<br/>考核服务]
|
||||
StatsService[StatsService<br/>统计服务]
|
||||
IndicatorService[IndicatorService<br/>指标服务]
|
||||
end
|
||||
subgraph "API接口层"
|
||||
AssessmentAPI[AssessmentAPI<br/>考核API]
|
||||
StatsAPI[StatsAPI<br/>统计API]
|
||||
IndicatorAPI[IndicatorAPI<br/>指标API]
|
||||
end
|
||||
subgraph "数据传输层"
|
||||
PydanticSchemas[Pydantic Schemas<br/>数据验证]
|
||||
end
|
||||
DeptTypeModel --> AssessmentService
|
||||
BSCDimensionModel --> StatsService
|
||||
StaffStatusModel --> AssessmentService
|
||||
AssessmentStatusModel --> AssessmentService
|
||||
IndicatorTypeModel --> IndicatorService
|
||||
AssessmentService --> AssessmentAPI
|
||||
StatsService --> StatsAPI
|
||||
IndicatorService --> IndicatorAPI
|
||||
AssessmentAPI --> PydanticSchemas
|
||||
StatsAPI --> PydanticSchemas
|
||||
IndicatorAPI --> PydanticSchemas
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [models.py](file://backend/app/models/models.py#L15-L61)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L12-L44)
|
||||
- [stats_service.py](file://backend/app/services/stats_service.py#L16-L218)
|
||||
- [assessment_service.py](file://backend/app/services/assessment_service.py#L160-L263)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 数据模型中的枚举使用
|
||||
|
||||
在数据模型中，枚举类型被用作SQLAlchemy列类型，确保数据库存储的一致性：
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class Department {
|
||||
+int id
|
||||
+string name
|
||||
+string code
|
||||
+DeptType dept_type
|
||||
+int parent_id
|
||||
+int level
|
||||
+int sort_order
|
||||
+bool is_active
|
||||
+string description
|
||||
}
|
||||
class Staff {
|
||||
+int id
|
||||
+string employee_id
|
||||
+string name
|
||||
+int department_id
|
||||
+string position
|
||||
+string title
|
||||
+string phone
|
||||
+string email
|
||||
+float base_salary
|
||||
+float performance_ratio
|
||||
+StaffStatus status
|
||||
+datetime hire_date
|
||||
}
|
||||
class Assessment {
|
||||
+int id
|
||||
+int staff_id
|
||||
+int period_year
|
||||
+int period_month
|
||||
+string period_type
|
||||
+float total_score
|
||||
+float weighted_score
|
||||
+AssessmentStatus status
|
||||
+int assessor_id
|
||||
+int reviewer_id
|
||||
+datetime submit_time
|
||||
+datetime review_time
|
||||
+string remark
|
||||
}
|
||||
Department --> DeptType : uses
|
||||
Staff --> StaffStatus : uses
|
||||
Assessment --> AssessmentStatus : uses
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [models.py](file://backend/app/models/models.py#L62-L178)
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L62-L178)
|
||||
|
||||
### 服务层中的枚举应用
|
||||
|
||||
服务层通过枚举类型实现业务逻辑控制：
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant API as API接口
|
||||
participant Service as 服务层
|
||||
participant Model as 数据模型
|
||||
participant DB as 数据库
|
||||
API->>Service : 提交考核请求
|
||||
Service->>Model : 获取考核记录
|
||||
Model->>DB : 查询数据库
|
||||
DB-->>Model : 返回考核数据
|
||||
Model-->>Service : 返回Assessment对象
|
||||
Service->>Service : 检查AssessmentStatus
|
||||
alt 状态为DRAFT
|
||||
Service->>Service : 设置状态为SUBMITTED
|
||||
Service->>DB : 更新数据库
|
||||
DB-->>Service : 更新成功
|
||||
Service-->>API : 返回更新后的考核
|
||||
else 状态不正确
|
||||
Service-->>API : 返回错误
|
||||
end
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [assessment_service.py](file://backend/app/services/assessment_service.py#L160-L205)
|
||||
|
||||
**章节来源**
|
||||
- [assessment_service.py](file://backend/app/services/assessment_service.py#L160-L205)
|
||||
|
||||
### 统计分析中的枚举使用
|
||||
|
||||
统计服务利用枚举类型进行数据分析：
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([开始统计]) --> GetParams[获取查询参数]
|
||||
GetParams --> FilterStatus[过滤已确认状态]
|
||||
FilterStatus --> GroupByDim[按BSC维度分组]
|
||||
GroupByDim --> CalcScore[计算维度得分]
|
||||
CalcScore --> CalcWeight[计算权重和指标数量]
|
||||
CalcWeight --> FormatResult[格式化结果]
|
||||
FormatResult --> End([返回统计结果])
|
||||
FilterStatus --> |使用AssessmentStatus.FINALIZED| FilterStatus
|
||||
GroupByDim --> |使用BSCDimension枚举| GroupByDim
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [stats_service.py](file://backend/app/services/stats_service.py#L20-L72)
|
||||
|
||||
**章节来源**
|
||||
- [stats_service.py](file://backend/app/services/stats_service.py#L20-L72)
|
||||
|
||||
### API接口中的枚举应用
|
||||
|
||||
API接口层通过Pydantic模式使用枚举类型：
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
subgraph "API请求"
|
||||
Request[HTTP请求]
|
||||
Params[查询参数]
|
||||
end
|
||||
subgraph "Pydantic验证"
|
||||
IndicatorSchema[IndicatorSchema]
|
||||
DeptTypeEnum[DeptType枚举]
|
||||
IndicatorTypeEnum[IndicatorType枚举]
|
||||
end
|
||||
subgraph "业务处理"
|
||||
Service[服务层]
|
||||
DB[数据库操作]
|
||||
end
|
||||
Request --> IndicatorSchema
|
||||
Params --> IndicatorSchema
|
||||
IndicatorSchema --> DeptTypeEnum
|
||||
IndicatorSchema --> IndicatorTypeEnum
|
||||
IndicatorSchema --> Service
|
||||
Service --> DB
|
||||
DB --> Service
|
||||
Service --> IndicatorSchema
|
||||
IndicatorSchema --> Response[HTTP响应]
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [indicators.py](file://backend/app/api/v1/indicators.py#L20-L41)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L153-L192)
|
||||
|
||||
**章节来源**
|
||||
- [indicators.py](file://backend/app/api/v1/indicators.py#L20-L41)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L153-L192)
|
||||
|
||||
## 依赖关系分析
|
||||
|
||||
枚举类型之间的依赖关系和使用模式：
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "核心枚举"
|
||||
DeptType[DeptType]
|
||||
BSCDimension[BSCDimension]
|
||||
StaffStatus[StaffStatus]
|
||||
AssessmentStatus[AssessmentStatus]
|
||||
IndicatorType[IndicatorType]
|
||||
end
|
||||
subgraph "数据模型"
|
||||
Department[Department模型]
|
||||
Staff[Staff模型]
|
||||
Assessment[Assessment模型]
|
||||
Indicator[Indicator模型]
|
||||
end
|
||||
subgraph "服务层"
|
||||
AssessmentService[AssessmentService]
|
||||
StatsService[StatsService]
|
||||
IndicatorService[IndicatorService]
|
||||
end
|
||||
subgraph "API层"
|
||||
AssessmentAPI[AssessmentAPI]
|
||||
StatsAPI[StatsAPI]
|
||||
IndicatorAPI[IndicatorAPI]
|
||||
end
|
||||
DeptType --> Department
|
||||
StaffStatus --> Staff
|
||||
AssessmentStatus --> Assessment
|
||||
BSCDimension --> Indicator
|
||||
IndicatorType --> Indicator
|
||||
Department --> AssessmentService
|
||||
Staff --> AssessmentService
|
||||
Assessment --> AssessmentService
|
||||
Indicator --> IndicatorService
|
||||
AssessmentService --> AssessmentAPI
|
||||
StatsService --> StatsAPI
|
||||
IndicatorService --> IndicatorAPI
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [models.py](file://backend/app/models/models.py#L62-L178)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L12-L44)
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L62-L178)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L12-L44)
|
||||
|
||||
## 性能考虑
|
||||
|
||||
枚举类型在系统中的性能优势：
|
||||
|
||||
1. **内存效率**：枚举值在内存中只存储一次，避免重复字符串存储
|
||||
2. **类型安全**：编译时检查，减少运行时错误
|
||||
3. **数据库优化**：使用SQLAlchemy Enum类型，数据库层面的约束和索引优化
|
||||
4. **序列化效率**：字符串枚举值在网络传输中占用更少空间
|
||||
|
||||
最佳实践建议：
|
||||
- 在数据库查询中使用枚举值进行WHERE条件过滤
|
||||
- 在API响应中使用字符串形式的枚举值便于前端处理
|
||||
- 在服务层逻辑中使用枚举类型进行状态判断和流程控制
|
||||
|
||||
## 故障排除指南
|
||||
|
||||
常见问题和解决方案：
|
||||
|
||||
### 枚举值不匹配问题
|
||||
**问题**：API请求中的枚举值与数据库存储不一致
|
||||
**解决方案**：
|
||||
- 确保API层使用正确的枚举类型
|
||||
- 在数据验证阶段添加枚举值检查
|
||||
- 使用统一的枚举转换函数
|
||||
|
||||
### 状态流转异常
|
||||
**问题**：考核状态无法正常流转
|
||||
**解决方案**：
|
||||
- 检查AssessmentStatus的流转顺序
|
||||
- 验证当前状态与预期状态的匹配
|
||||
- 添加状态检查和错误处理逻辑
|
||||
|
||||
### 维度统计错误
|
||||
**问题**：BSC维度统计结果不正确
|
||||
**解决方案**：
|
||||
- 验证BSCDimension枚举值的使用
|
||||
- 检查数据库中指标的维度设置
|
||||
- 确认统计查询的JOIN条件和WHERE条件
|
||||
|
||||
**章节来源**
|
||||
- [assessment_service.py](file://backend/app/services/assessment_service.py#L160-L205)
|
||||
- [stats_service.py](file://backend/app/services/stats_service.py#L20-L72)
|
||||
|
||||
## 结论
|
||||
|
||||
枚举类型是医院绩效管理系统的核心基础设施，它们提供了：
|
||||
|
||||
1. **业务一致性**：确保不同模块间使用相同的业务概念和规则
|
||||
2. **类型安全**：在编译时发现潜在的类型错误
|
||||
3. **维护便利**：集中管理业务规则，便于后续扩展和修改
|
||||
4. **性能优化**：减少字符串比较，提高系统运行效率
|
||||
|
||||
通过合理设计和使用这些枚举类型，系统能够支持复杂的医院绩效管理需求，包括多维度的平衡计分卡分析、完整的考核流程管理和全面的统计报表功能。这些枚举类型为系统的稳定性和可维护性奠定了坚实的基础。
|
||||
|
||||
随着系统的持续发展，这些枚举类型将继续发挥重要作用，支持新的业务需求和功能扩展。
|
||||
Reference in New Issue
Block a user