提交文件

2026-02-28 15:16:15 +08:00
parent 1a4e50e0a4
commit 44f250f58e
159 changed files with 61268 additions and 0 deletions
--- a/.qoder/repowiki/zh/content/数据库设计/表结构设计/枚举类型定义.md
+++ b/.qoder/repowiki/zh/content/数据库设计/表结构设计/枚举类型定义.md
@@ -0,0 +1,582 @@
+# 枚举类型定义
+
+<cite>
+**本文档引用的文件**
+- [models.py](file://backend/app/models/models.py)
+- [schemas.py](file://backend/app/schemas/schemas.py)
+- [init_db.py](file://backend/app/core/init_db.py)
+- [finance.py](file://backend/app/models/finance.py)
+- [001_initial.py](file://backend/alembic/versions/001_initial.py)
+- [departments.py](file://backend/app/api/v1/departments.py)
+- [performance_plans.py](file://backend/app/api/v1/performance_plans.py)
+- [department_service.py](file://backend/app/services/department_service.py)
+- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心枚举类型](#核心枚举类型)
+4. [架构概览](#架构概览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考虑](#性能考虑)
+8. [故障排除指南](#故障排除指南)
+9. [结论](#结论)
+
+## 简介
+
+本文档详细介绍了医院绩效系统中的所有自定义枚举类型定义，包括它们的设计思路、取值范围、业务含义和使用场景。系统采用强类型枚举确保数据的一致性和完整性，通过SQLAlchemy映射到数据库中的字符串字段，并在API层提供类型安全的接口。
+
+## 项目结构
+
+枚举类型主要分布在以下三个层次：
+
+```mermaid
+graph TB
+subgraph "数据模型层"
+A[models.py<br/>数据库模型枚举]
+end
+subgraph "数据验证层"
+B[schemas.py<br/>Pydantic模型枚举]
+end
+subgraph "业务逻辑层"
+C[init_db.py<br/>初始化枚举]
+D[finance.py<br/>财务枚举]
+end
+subgraph "API接口层"
+E[departments.py<br/>科室API]
+F[performance_plans.py<br/>计划API]
+end
+A --> B
+B --> C
+C --> D
+D --> E
+E --> F
+```
+
+**图表来源**
+- [models.py](file://backend/app/models/models.py#L15-L345)
+- [schemas.py](file://backend/app/schemas/schemas.py#L10-L652)
+- [init_db.py](file://backend/app/core/init_db.py#L9-L115)
+
+**章节来源**
+- [models.py](file://backend/app/models/models.py#L1-L438)
+- [schemas.py](file://backend/app/schemas/schemas.py#L1-L743)
+
+## 核心枚举类型
+
+### 科室类型 (DeptType)
+
+科室类型枚举定义了医院各类科室的分类体系，采用字符串值存储，支持多层级科室组织结构。
+
+**设计思路：**
+- 按照医院科室的功能属性进行分类
+- 支持从属关系的层级结构
+- 为指标模板选择提供依据
+
+**取值范围：**
+- `CLINICAL_SURGICAL`: 手术临床科室
+- `CLINICAL_NONSURGICAL_WARD`: 非手术有病房科室  
+- `CLINICAL_NONSURGICAL_NOWARD`: 非手术无病房科室
+- `MEDICAL_TECH`: 医技科室
+- `MEDICAL_AUXILIARY`: 医辅科室
+- `NURSING`: 护理单元
+- `ADMIN`: 行政科室
+- `FINANCE`: 财务科室
+- `LOGISTICS`: 后勤保障科室
+
+**业务含义：**
+- 用于区分不同功能属性的科室
+- 支持按科室类型进行筛选和统计
+- 为绩效指标模板的适用性提供分类依据
+
+**使用场景：**
+- 科室信息管理
+- 绩效指标模板匹配
+- 数据统计分析
+
+**章节来源**
+- [models.py](file://backend/app/models/models.py#L16-L27)
+- [schemas.py](file://backend/app/schemas/schemas.py#L12-L22)
+
+### 平衡计分卡维度 (BSCDimension)
+
+平衡计分卡维度枚举实现了经典的四个维度考核框架。
+
+**设计思路：**
+- 基于平衡计分卡理论框架
+- 四个维度相互补充，全面评估组织绩效
+- 支持多维度的综合评价
+
+**取值范围：**
+- `FINANCIAL`: 财务维度
+- `CUSTOMER`: 客户维度  
+- `INTERNAL_PROCESS`: 内部流程维度
+- `LEARNING_GROWTH`: 学习与成长维度
+
+**业务含义：**
+- 财务维度：关注财务表现和盈利能力
+- 客户维度：关注客户满意度和服务质量
+- 内部流程维度：关注运营效率和流程优化
+- 学习与成长维度：关注员工能力和组织发展
+
+**使用场景：**
+- 绩效指标设计
+- 综合评价体系构建
+- 战略目标分解
+
+**章节来源**
+- [models.py](file://backend/app/models/models.py#L29-L35)
+
+### 员工状态 (StaffStatus)
+
+员工状态枚举跟踪员工在组织中的生命周期状态。
+
+**设计思路：**
+- 覆盖员工从入职到离职的完整生命周期
+- 支持状态变更的审计追踪
+- 为薪资计算和权限管理提供依据
+
+**取值范围：**
+- `ACTIVE`: 在职
+- `LEAVE`: 休假
+- `RESIGNED`: 离职
+- `RETIRED`: 退休
+
+**业务含义：**
+- ACTIVE: 当前在岗工作
+- LEAVE: 正式请假状态
+- RESIGNED: 主动辞职
+- RETIRED: 达到退休年龄
+
+**使用场景：**
+- 员工信息管理
+- 薪资发放控制
+- 系统权限管理
+
+**章节来源**
+- [models.py](file://backend/app/models/models.py#L37-L43)
+- [schemas.py](file://backend/app/schemas/schemas.py#L24-L29)
+
+### 考核状态 (AssessmentStatus)
+
+考核状态枚举管理绩效考核流程的各个阶段。
+
+**设计思路：**
+- 实现完整的考核流程管理
+- 支持多级审批和状态流转
+- 提供清晰的流程可视化
+
+**取值范围：**
+- `DRAFT`: 草稿
+- `SUBMITTED`: 已提交
+- `REVIEWED`: 已审核
+- `FINALIZED`: 已确认
+- `REJECTED`: 已驳回
+
+**业务含义：**
+- DRAFT: 考核记录创建但未提交
+- SUBMITTED: 已提交等待审批
+- REVIEWED: 审核通过等待最终确认
+- FINALIZED: 最终确认完成
+- REJECTED: 审批被拒绝
+
+**使用场景：**
+- 绩效考核流程控制
+- 审批权限管理
+- 数据状态追踪
+
+**章节来源**
+- [models.py](file://backend/app/models/models.py#L45-L52)
+- [schemas.py](file://backend/app/schemas/schemas.py#L31-L37)
+
+### 指标类型 (IndicatorType)
+
+指标类型枚举定义了绩效指标的分类体系。
+
+**设计思路：**
+- 基于平衡计分卡的指标分类
+- 支持不同类型指标的差异化管理
+- 便于指标的统计分析和比较
+
+**取值范围：**
+- `QUALITY`: 质量指标
+- `QUANTITY`: 数量指标
+- `EFFICIENCY`: 效率指标
+- `SERVICE`: 服务指标
+- `COST`: 成本指标
+
+**业务含义：**
+- QUALITY: 关注工作质量和效果
+- QUANTITY: 关注工作量和产出数量
+- EFFICIENCY: 关注资源利用效率
+- SERVICE: 关注服务质量水平
+- COST: 关注成本控制效果
+
+**使用场景：**
+- 指标设计和分类
+- 绩效计算和评分
+- 统计分析和报告
+
+**章节来源**
+- [models.py](file://backend/app/models/models.py#L54-L61)
+- [schemas.py](file://backend/app/schemas/schemas.py#L39-L45)
+
+### 计划状态 (PlanStatus)
+
+计划状态枚举管理绩效计划的生命周期。
+
+**设计思路：**
+- 支持从创建到完成的完整计划管理
+- 提供清晰的状态流转路径
+- 支持计划的版本管理和变更追踪
+
+**取值范围：**
+- `DRAFT`: 草稿
+- `PENDING`: 待审批
+- `APPROVED`: 已批准
+- `REJECTED`: 已驳回
+- `ACTIVE`: 执行中
+- `COMPLETED`: 已完成
+- `CANCELLED`: 已取消
+
+**业务含义：**
+- DRAFT: 计划草稿状态
+- PENDING: 等待上级审批
+- APPROVED: 审批通过准备执行
+- REJECTED: 审批被拒绝
+- ACTIVE: 正在执行的计划
+- COMPLETED: 执行完成的计划
+- CANCELLED: 主动取消的计划
+
+**使用场景：**
+- 绩效计划管理
+- 审批流程控制
+- 计划执行追踪
+
+**章节来源**
+- [models.py](file://backend/app/models/models.py#L233-L242)
+
+### 菜单类型 (MenuType)
+
+菜单类型枚举区分系统界面的导航元素。
+
+**设计思路：**
+- 支持复杂的菜单层级结构
+- 区分页面菜单和操作按钮
+- 为权限控制提供基础
+
+**取值范围：**
+- `MENU`: 菜单
+- `BUTTON`: 按钮
+
+**业务含义：**
+- MENU: 导航菜单项，可包含子菜单
+- BUTTON: 页面上的操作按钮，无子菜单
+
+**使用场景：**
+- 系统权限管理
+- 界面导航控制
+- 功能访问控制
+
+**章节来源**
+- [models.py](file://backend/app/models/models.py#L341-L345)
+- [schemas.py](file://backend/app/schemas/schemas.py#L584-L588)
+
+### 财务相关枚举
+
+#### 收入类别 (RevenueCategory)
+- `EXAMINATION`: 检查费
+- `LAB_TEST`: 检验费  
+- `RADIOLOGY`: 放射费
+- `BED`: 床位费
+- `NURSING`: 护理费
+- `TREATMENT`: 治疗费
+- `SURGERY`: 手术费
+- `INJECTION`: 注射费
+- `OXYGEN`: 吸氧费
+- `OTHER`: 其他
+
+#### 支出类别 (ExpenseCategory)
+- `MATERIAL`: 材料费
+- `PERSONNEL`: 人员支出
+- `MAINTENANCE`: 维修费
+- `UTILITY`: 水电费
+- `OTHER`: 其他
+
+#### 财务类型 (FinanceType)
+- `REVENUE`: 收入
+- `EXPENSE`: 支出
+
+**章节来源**
+- [finance.py](file://backend/app/models/finance.py#L16-L43)
+
+## 架构概览
+
+枚举类型在整个系统中的架构分布如下：
+
+```mermaid
+graph TB
+subgraph "数据持久层"
+A[SQLAlchemy Enum<br/>String存储]
+B[数据库索引<br/>性能优化]
+end
+subgraph "业务逻辑层"
+C[模型定义<br/>类型约束]
+D[服务层<br/>状态流转]
+end
+subgraph "接口层"
+E[API路由<br/>参数验证]
+F[Pydantic模型<br/>数据序列化]
+end
+subgraph "前端展示层"
+G[Vue组件<br/>状态显示]
+H[表格展示<br/>枚举翻译]
+end
+A --> C
+C --> D
+D --> E
+E --> F
+F --> G
+G --> H
+B --> A
+B --> C
+```
+
+**图表来源**
+- [models.py](file://backend/app/models/models.py#L69-L354)
+- [schemas.py](file://backend/app/schemas/schemas.py#L12-L652)
+
+## 详细组件分析
+
+### 数据库存储方式
+
+所有枚举类型在数据库中以字符串形式存储，使用SQLAlchemy的Enum映射：
+
+```mermaid
+erDiagram
+ENUM_VALUES {
+string value PK
+string description
+string category
+}
+DEPARTMENTS {
+int id PK
+string dept_type FK
+}
+STAFF {
+int id PK
+string status FK
+}
+INDICATORS {
+int id PK
+string indicator_type FK
+string bs_dimension FK
+}
+DEPARTMENTS }o--|| ENUM_VALUES : "has"
+STAFF }o--|| ENUM_VALUES : "has"
+INDICATORS }o--|| ENUM_VALUES : "has"
+```
+
+**图表来源**
+- [models.py](file://backend/app/models/models.py#L69-L125)
+- [001_initial.py](file://backend/alembic/versions/001_initial.py#L28-L79)
+
+### 查询优化策略
+
+系统通过以下方式优化枚举查询性能：
+
+1. **数据库索引优化**
+   - 科室类型索引：`idx_dept_type`
+   - 员工状态索引：`idx_staff_status`
+   - 考核状态索引：`idx_assessment_status`
+
+2. **查询条件优化**
+   ```python
+   # 使用枚举值进行精确匹配
+   query = query.where(Department.dept_type == dept_type)
+   query = query.where(Staff.status == StaffStatus.ACTIVE)
+   ```
+
+3. **批量查询优化**
+   - 使用`selectinload`进行关联查询
+   - 避免N+1查询问题
+
+**章节来源**
+- [models.py](file://backend/app/models/models.py#L82-L178)
+- [department_service.py](file://backend/app/services/department_service.py#L25-L43)
+
+### API使用流程
+
+```mermaid
+sequenceDiagram
+participant Client as "客户端"
+participant API as "API接口"
+participant Service as "服务层"
+participant Model as "数据模型"
+participant DB as "数据库"
+Client->>API : GET /departments?type=clinical_surgical
+API->>Service : get_list(dept_type="clinical_surgical")
+Service->>Model : Department.dept_type == "clinical_surgical"
+Model->>DB : SELECT * FROM departments WHERE dept_type = ?
+DB-->>Model : 查询结果
+Model-->>Service : Department对象列表
+Service-->>API : 部门列表
+API-->>Client : JSON响应
+Note over Client,DB : 使用枚举值进行类型安全的查询
+```
+
+**图表来源**
+- [departments.py](file://backend/app/api/v1/departments.py#L20-L41)
+- [department_service.py](file://backend/app/services/department_service.py#L17-L43)
+
+**章节来源**
+- [departments.py](file://backend/app/api/v1/departments.py#L1-L108)
+- [performance_plans.py](file://backend/app/api/v1/performance_plans.py#L21-L65)
+
+### 状态流转流程
+
+```mermaid
+stateDiagram-v2
+[*] --> DRAFT : 创建计划
+DRAFT --> PENDING : 提交审批
+PENDING --> APPROVED : 审批通过
+PENDING --> REJECTED : 审批驳回
+APPROVED --> ACTIVE : 激活执行
+ACTIVE --> COMPLETED : 执行完成
+ACTIVE --> CANCELLED : 取消计划
+COMPLETED --> [*]
+REJECTED --> [*]
+CANCELLED --> [*]
+note right of DRAFT
+草稿状态
+可编辑修改
+end note
+note right of PENDING
+等待审批
+不可修改
+end note
+note right of APPROVED
+已批准
+准备执行
+end note
+note right of ACTIVE
+执行中
+数据录入
+end note
+note right of COMPLETED
+已完成
+统计分析
+end note
+```
+
+**图表来源**
+- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L131-L182)
+- [models.py](file://backend/app/models/models.py#L233-L242)
+
+**章节来源**
+- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L131-L182)
+
+## 依赖关系分析
+
+```mermaid
+graph TD
+subgraph "核心枚举"
+A[DeptType]
+B[StaffStatus]
+C[AssessmentStatus]
+D[IndicatorType]
+E[PlanStatus]
+F[MenuType]
+end
+subgraph "模型映射"
+G[Department.dept_type]
+H[Staff.status]
+I[Assessment.status]
+J[Indicator.indicator_type]
+K[Indicator.bs_dimension]
+L[PerformancePlan.status]
+M[Menu.menu_type]
+end
+subgraph "API使用"
+N[departments.py]
+O[performance_plans.py]
+P[staff.py]
+Q[indicators.py]
+end
+A --> G
+B --> H
+C --> I
+D --> J
+E --> L
+F --> M
+G --> N
+H --> P
+I --> Q
+J --> Q
+L --> O
+M --> N
+style A fill:#e1f5fe
+style E fill:#e8f5e8
+style C fill:#fff3e0
+```
+
+**图表来源**
+- [models.py](file://backend/app/models/models.py#L69-L354)
+- [schemas.py](file://backend/app/schemas/schemas.py#L12-L652)
+
+**章节来源**
+- [models.py](file://backend/app/models/models.py#L1-L438)
+- [schemas.py](file://backend/app/schemas/schemas.py#L1-L743)
+
+## 性能考虑
+
+### 存储优化
+- **字符串存储**：所有枚举值以字符串形式存储，占用空间小
+- **索引优化**：为常用查询字段建立数据库索引
+- **唯一约束**：确保枚举值的唯一性和一致性
+
+### 查询优化
+- **精确匹配**：使用等值查询而非模糊匹配
+- **批量操作**：支持批量枚举值的查询和过滤
+- **缓存策略**：可将常用的枚举值缓存到内存中
+
+### 内存优化
+- **类型安全**：编译时检查枚举值的有效性
+- **序列化开销**：字符串枚举比整数枚举有更高的序列化开销
+
+## 故障排除指南
+
+### 常见问题及解决方案
+
+1. **枚举值不匹配**
+   - 症状：数据库插入失败，提示枚举值无效
+   - 解决：检查枚举定义是否与数据库schema一致
+   - 验证：使用`SELECT DISTINCT column FROM table`检查现有值
+
+2. **查询性能问题**
+   - 症状：大量枚举查询导致性能下降
+   - 解决：添加适当的数据库索引
+   - 优化：使用`EXPLAIN`分析查询计划
+
+3. **状态流转异常**
+   - 症状：计划状态无法正常转换
+   - 解决：检查状态转换逻辑和前置条件
+   - 调试：查看状态转换日志和时间戳
+
+**章节来源**
+- [init_db.py](file://backend/app/core/init_db.py#L33-L115)
+- [department_service.py](file://backend/app/services/department_service.py#L17-L150)
+
+## 结论
+
+该医院绩效系统的枚举类型设计体现了以下特点：
+
+1. **完整性**：覆盖了医院管理的所有关键业务领域
+2. **一致性**：统一的数据存储格式和查询方式
+3. **可扩展性**：支持未来业务需求的变化和扩展
+4. **性能优化**：通过索引和查询优化确保系统性能
+5. **类型安全**：编译时检查确保数据的正确性
+
+通过合理的枚举设计和实现，系统能够有效支撑医院绩效管理的各项业务需求，为决策提供可靠的数据支持。