提交文件

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,545 @@
+# 核心数据模型
+
+<cite>
+**本文档引用的文件**
+- [models.py](file://backend/app/models/models.py)
+- [finance.py](file://backend/app/models/finance.py)
+- [database.py](file://backend/app/core/database.py)
+- [init_db.py](file://backend/app/core/init_db.py)
+- [schemas.py](file://backend/app/schemas/schemas.py)
+- [staff_service.py](file://backend/app/services/staff_service.py)
+- [assessment_service.py](file://backend/app/services/assessment_service.py)
+- [salary_service.py](file://backend/app/services/salary_service.py)
+- [database.md](file://docs/database.md)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构概览](#架构概览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖分析](#依赖分析)
+7. [性能考虑](#性能考虑)
+8. [故障排除指南](#故障排除指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+
+本文件详细阐述医院绩效系统的核心数据模型设计，重点涵盖Department（科室）、Staff（员工）、Assessment（考核记录）、AssessmentDetail（考核明细）、SalaryRecord（工资核算记录）等核心业务模型。文档从设计理念、实现细节、字段定义、数据类型、约束条件、业务规则、模型关联关系、索引设计、性能优化策略等多个维度进行全面解析，并提供使用示例和最佳实践指导。
+
+## 项目结构
+
+该系统采用分层架构，核心模型位于 `backend/app/models/` 目录，数据库连接通过 `backend/app/core/database.py` 管理，初始化逻辑在 `backend/app/core/init_db.py` 中实现。数据验证通过 Pydantic 模式在 `backend/app/schemas/schemas.py` 中定义，服务层负责业务逻辑处理。
+
+```mermaid
+graph TB
+subgraph "模型层"
+M1[models.py<br/>核心业务模型]
+M2[finance.py<br/>财务核算模型]
+end
+subgraph "核心配置"
+C1[database.py<br/>数据库连接]
+C2[init_db.py<br/>数据库初始化]
+end
+subgraph "数据验证"
+S1[schemas.py<br/>Pydantic模式]
+end
+subgraph "服务层"
+SV1[staff_service.py]
+SV2[assessment_service.py]
+SV3[salary_service.py]
+end
+M1 --> C1
+M2 --> C1
+C2 --> M1
+S1 --> SV1
+S1 --> SV2
+S1 --> SV3
+SV1 --> M1
+SV2 --> M1
+SV3 --> M1
+```
+
+**图表来源**
+- [models.py](file://backend/app/models/models.py#L62-L231)
+- [finance.py](file://backend/app/models/finance.py#L45-L74)
+- [database.py](file://backend/app/core/database.py#L9-L25)
+- [init_db.py](file://backend/app/core/init_db.py#L1-L115)
+- [schemas.py](file://backend/app/schemas/schemas.py#L1-L743)
+
+**章节来源**
+- [models.py](file://backend/app/models/models.py#L1-L438)
+- [finance.py](file://backend/app/models/finance.py#L1-L79)
+- [database.py](file://backend/app/core/database.py#L1-L39)
+- [init_db.py](file://backend/app/core/init_db.py#L1-L115)
+- [schemas.py](file://backend/app/schemas/schemas.py#L1-L743)
+
+## 核心组件
+
+本节概述五个核心业务模型的设计理念和实现要点：
+
+### Department（科室）
+- 设计理念：支持多层级组织架构，通过自关联实现父子关系
+- 关键特性：科室类型枚举、层级管理、排序机制、激活状态控制
+- 外键关系：自关联 parent_id 指向自身，children 反向关系
+- 索引设计：按科室类型和父级ID建立索引
+
+### Staff（员工）
+- 设计理念：员工与科室的一对多关系，支持多种状态管理
+- 关键特性：工号唯一性、基本工资和绩效系数、状态枚举
+- 外键关系：department_id 指向 Department，一对多关系
+- 索引设计：按科室ID和状态建立复合索引
+
+### Assessment（考核记录）
+- 设计理念：支持多周期、多状态的考核流程管理
+- 关键特性：总分和加权得分计算、多角色参与（考核人、审核人）
+- 外键关系：staff_id 指向 Staff，assessor_id 和 reviewer_id 自关联
+- 索引设计：按员工ID、考核周期、状态建立复合索引
+
+### AssessmentDetail（考核明细）
+- 设计理念：一对一关联 Assessment，支持多指标明细记录
+- 关键特性：实际值和得分记录、佐证材料管理
+- 外键关系：assessment_id 和 indicator_id 的双向关联
+- 索引设计：按考核记录ID和指标ID建立索引
+
+### SalaryRecord（工资核算记录）
+- 设计理念：基于考核结果的自动化工资核算
+- 关键特性：基本工资、绩效奖金、扣款、补贴的统一管理
+- 外键关系：staff_id 指向 Staff
+- 索引设计：按员工ID和考核周期建立复合索引
+
+**章节来源**
+- [models.py](file://backend/app/models/models.py#L62-L231)
+- [database.md](file://docs/database.md#L99-L216)
+
+## 架构概览
+
+系统采用分层架构，核心数据模型通过 SQLAlchemy ORM 映射到数据库表，配合 Pydantic 模式进行数据验证，服务层封装业务逻辑。
+
+```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
+datetime created_at
+datetime updated_at
+children : List[Department]
+staff : List[Staff]
+}
+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
+datetime created_at
+datetime updated_at
+department : Department
+assessments : List[Assessment]
+salary_records : List[SalaryRecord]
+}
+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
+datetime created_at
+datetime updated_at
+staff : Staff
+assessor : Staff
+reviewer : Staff
+details : List[AssessmentDetail]
+}
+class AssessmentDetail {
+int id
+int assessment_id
+int indicator_id
+float actual_value
+float score
+string evidence
+string remark
+datetime created_at
+datetime updated_at
+assessment : Assessment
+indicator : Indicator
+}
+class SalaryRecord {
+int id
+int staff_id
+int period_year
+int period_month
+float base_salary
+float performance_score
+float performance_bonus
+float deduction
+float allowance
+float total_salary
+string status
+string remark
+datetime created_at
+datetime updated_at
+staff : Staff
+}
+Department "1" <-- "N" Staff : "一对多"
+Staff "1" <-- "N" Assessment : "一对多"
+Assessment "1" <-- "N" AssessmentDetail : "一对多"
+Staff "1" <-- "N" SalaryRecord : "一对多"
+Assessment "N" --> "1" Staff : "多对一"
+AssessmentDetail "N" --> "1" Assessment : "多对一"
+AssessmentDetail "N" --> "1" Indicator : "多对一"
+SalaryRecord "N" --> "1" Staff : "多对一"
+```
+
+**图表来源**
+- [models.py](file://backend/app/models/models.py#L62-L231)
+
+## 详细组件分析
+
+### Department（科室）模型
+
+#### 字段定义与数据类型
+- id: 主键，整数类型，自动递增
+- name: 科室名称，字符串类型，最大长度100，必填
+- code: 科室编码，字符串类型，最大长度20，唯一且必填
+- dept_type: 科室类型枚举，支持临床、医技、医辅、行政、后勤等类型
+- parent_id: 上级科室ID，整数类型，自关联外键
+- level: 层级，整数类型，默认1，范围1-5
+- sort_order: 排序，整数类型，默认0
+- is_active: 是否启用，布尔类型，默认True
+- description: 描述信息，文本类型
+- created_at/updated_at: 时间戳，自动维护
+
+#### 约束条件与业务规则
+- 唯一性约束：code 字段唯一
+- 枚举约束：dept_type 必须属于预定义类型集合
+- 自关联约束：parent_id 引用自身主键
+- 层级限制：level 范围1-5
+
+#### 关联关系
+- 一对多：Department → Staff（children）
+- 自关联：parent_id → Department（parent）
+
+#### 索引设计
+- idx_dept_type：按科室类型查询优化
+- idx_dept_parent：按父级科室查询优化
+
+**章节来源**
+- [models.py](file://backend/app/models/models.py#L62-L86)
+- [database.md](file://docs/database.md#L99-L115)
+
+### Staff（员工）模型
+
+#### 字段定义与数据类型
+- id: 主键，整数类型，自动递增
+- employee_id: 工号，字符串类型，最大长度20，唯一且必填
+- name: 姓名，字符串类型，最大长度50，必填
+- department_id: 所属科室ID，整数类型，外键约束
+- position: 职位，字符串类型，最大长度50，必填
+- title: 职称，字符串类型，最大长度50
+- phone/email: 联系方式，字符串类型
+- base_salary: 基本工资，数值类型，精度10,2，默认0
+- performance_ratio: 绩效系数，数值类型，精度5,2，默认1.0，范围0-5
+- status: 员工状态枚举，默认active
+- hire_date: 入职日期，日期时间类型
+- created_at/updated_at: 时间戳
+
+#### 约束条件与业务规则
+- 唯一性约束：employee_id 唯一
+- 数值范围约束：performance_ratio 范围0-5
+- 外键约束：department_id 引用 Department.id
+- 状态枚举：仅允许预定义状态值
+
+#### 关联关系
+- 多对一：Staff → Department（department）
+- 一对多：Department → Staff（staff）
+- 一对多：Staff → Assessment（assessments）
+- 一对多：Staff → SalaryRecord（salary_records）
+
+#### 索引设计
+- idx_staff_dept：按科室ID查询优化
+- idx_staff_status：按状态查询优化
+
+**章节来源**
+- [models.py](file://backend/app/models/models.py#L88-L114)
+- [database.md](file://docs/database.md#L117-L136)
+
+### Assessment（考核记录）模型
+
+#### 字段定义与数据类型
+- id: 主键，整数类型，自动递增
+- staff_id: 员工ID，整数类型，外键约束
+- period_year: 考核年度，整数类型，必填
+- period_month: 考核月份，整数类型，必填
+- period_type: 考核周期类型，字符串类型，默认monthly
+- total_score: 总分，数值类型，精度5,2，默认0
+- weighted_score: 加权得分，数值类型，精度5,2，默认0
+- status: 考核状态枚举，默认draft
+- assessor_id/reviewer_id: 考核人/审核人ID，整数类型，自关联外键
+- submit_time/review_time: 提交/审核时间，日期时间类型
+- remark: 备注，文本类型
+- created_at/updated_at: 时间戳
+
+#### 约束条件与业务规则
+- 外键约束：staff_id 引用 Staff.id
+- 自关联约束：assessor_id/reviewer_id 引用 Staff.id
+- 状态枚举：支持草稿、提交、审核、确认、驳回等状态
+- 计算规则：total_score 为明细得分之和，weighted_score 为按指标权重加权
+
+#### 关联关系
+- 多对一：Assessment → Staff（staff）
+- 多对一：Assessment → Staff（assessor）
+- 多对一：Assessment → Staff（reviewer）
+- 一对多：Assessment → AssessmentDetail（details）
+- 级联删除：details 支持级联删除
+
+#### 索引设计
+- idx_assessment_staff：按员工ID查询优化
+- idx_assessment_period：按考核周期查询优化
+- idx_assessment_status：按状态查询优化
+
+**章节来源**
+- [models.py](file://backend/app/models/models.py#L149-L178)
+- [database.md](file://docs/database.md#L159-L179)
+
+### AssessmentDetail（考核明细）模型
+
+#### 字段定义与数据类型
+- id: 主键，整数类型，自动递增
+- assessment_id: 考核记录ID，整数类型，外键约束
+- indicator_id: 指标ID，整数类型，外键约束
+- actual_value: 实际值，数值类型，精度10,2
+- score: 得分，数值类型，精度5,2，默认0
+- evidence: 佐证材料，文本类型
+- remark: 备注，文本类型
+- created_at/updated_at: 时间戳
+
+#### 约束条件与业务规则
+- 外键约束：assessment_id 引用 Assessment.id，indicator_id 引用 Indicator.id
+- 计算规则：Assessment.total_score = Σ(AssessmentDetail.score)
+
+#### 关联关系
+- 多对一：AssessmentDetail → Assessment（assessment）
+- 多对一：AssessmentDetail → Indicator（indicator）
+
+#### 索引设计
+- idx_detail_assessment：按考核记录ID查询优化
+- idx_detail_indicator：按指标ID查询优化
+
+**章节来源**
+- [models.py](file://backend/app/models/models.py#L181-L202)
+- [database.md](file://docs/database.md#L181-L195)
+
+### SalaryRecord（工资核算记录）模型
+
+#### 字段定义与数据类型
+- id: 主键，整数类型，自动递增
+- staff_id: 员工ID，整数类型，外键约束
+- period_year: 年度，整数类型，必填
+- period_month: 月份，整数类型，必填
+- base_salary: 基本工资，数值类型，精度10,2，默认0
+- performance_score: 绩效得分，数值类型，精度5,2，默认0
+- performance_bonus: 绩效奖金，数值类型，精度10,2，默认0
+- deduction: 扣款，数值类型，精度10,2，默认0
+- allowance: 补贴，数值类型，精度10,2，默认0
+- total_salary: 应发工资，数值类型，精度10,2，默认0
+- status: 状态，默认pending
+- remark: 备注，文本类型
+- created_at/updated_at: 时间戳
+
+#### 约束条件与业务规则
+- 外键约束：staff_id 引用 Staff.id
+- 计算规则：total_salary = base_salary + performance_bonus + allowance - deduction
+- 状态管理：支持pending、confirmed、paid等状态
+
+#### 关联关系
+- 多对一：SalaryRecord → Staff（staff）
+
+#### 索引设计
+- idx_salary_staff：按员工ID查询优化
+- idx_salary_period：按考核周期查询优化
+
+**章节来源**
+- [models.py](file://backend/app/models/models.py#L205-L230)
+- [database.md](file://docs/database.md#L197-L216)
+
+### 数据验证规则
+
+系统采用 Pydantic 模式进行数据验证，确保输入数据的完整性和正确性：
+
+#### 员工数据验证
+- employee_id: 长度不超过20字符，必填
+- base_salary: 非负数，最小值0
+- performance_ratio: 范围0-5
+- name/position/title: 长度限制和必填约束
+
+#### 考核数据验证
+- period_year: 范围2020-2100
+- period_month: 范围1-12
+- score: 非负数，最小值0
+
+#### 工资数据验证
+- 所有金额字段：非负数约束
+- 计算字段：自动计算，不允许直接修改
+
+**章节来源**
+- [schemas.py](file://backend/app/schemas/schemas.py#L107-L149)
+- [schemas.py](file://backend/app/schemas/schemas.py#L220-L271)
+- [schemas.py](file://backend/app/schemas/schemas.py#L274-L311)
+
+## 依赖分析
+
+系统模型间存在清晰的依赖关系，遵循数据库规范化原则：
+
+```mermaid
+graph TD
+A[Department] --> B[Staff]
+B --> C[Assessment]
+C --> D[AssessmentDetail]
+B --> E[SalaryRecord]
+C -.-> F[Indicator]
+G[Assessment] -.自关联.-> B
+H[AssessmentDetail] -.多对一.-> F
+subgraph "索引优化"
+I[idx_dept_type]
+J[idx_staff_dept]
+K[idx_assessment_staff]
+L[idx_detail_assessment]
+M[idx_salary_staff]
+end
+A -.-> I
+B -.-> J
+C -.-> K
+D -.-> L
+E -.-> M
+```
+
+**图表来源**
+- [models.py](file://backend/app/models/models.py#L62-L231)
+- [database.md](file://docs/database.md#L99-L216)
+
+### 外键约束与级联操作
+
+- Assessment → AssessmentDetail: 级联删除（delete-orphan）
+- Department → Staff: 一对多关系
+- Staff → Assessment: 一对多关系
+- Staff → SalaryRecord: 一对多关系
+
+### 性能优化策略
+
+#### 查询优化
+- 使用复合索引优化常用查询条件
+- 通过 selectinload 减少 N+1 查询问题
+- 分页查询避免大数据集加载
+
+#### 数据库连接
+- 异步数据库连接提高并发性能
+- 连接池管理优化资源使用
+
+**章节来源**
+- [models.py](file://backend/app/models/models.py#L173-L173)
+- [staff_service.py](file://backend/app/services/staff_service.py#L26-L49)
+- [assessment_service.py](file://backend/app/services/assessment_service.py#L29-L55)
+- [salary_service.py](file://backend/app/services/salary_service.py#L32-L58)
+
+## 性能考虑
+
+### 索引策略
+- 单列索引：按枚举类型、状态、激活状态快速过滤
+- 复合索引：按员工ID+状态、考核周期、科室ID+状态等组合查询优化
+
+### 查询优化
+- 使用 selectinload 预加载关联数据
+- 分页查询限制结果集大小
+- 条件查询精确匹配减少扫描范围
+
+### 缓存策略
+- 频繁访问的枚举类型缓存
+- 常用查询结果短期缓存
+
+## 故障排除指南
+
+### 常见问题与解决方案
+
+#### 数据重复错误
+- 症状：插入重复的工号或科室编码
+- 解决：检查唯一性约束，使用去重逻辑
+
+#### 外键约束错误
+- 症状：插入不存在的员工或科室ID
+- 解决：先创建关联实体，再创建子实体
+
+#### 数据验证失败
+- 症状：字段超出范围或格式不正确
+- 解决：检查 Pydantic 模式的验证规则
+
+#### 性能问题
+- 症状：查询响应缓慢
+- 解决：检查索引使用情况，优化查询条件
+
+**章节来源**
+- [init_db.py](file://backend/app/core/init_db.py#L12-L115)
+- [schemas.py](file://backend/app/schemas/schemas.py#L107-L149)
+
+## 结论
+
+本核心数据模型设计充分体现了医院绩效管理的业务需求，通过清晰的实体关系、严格的约束条件、完善的索引策略和合理的性能优化，为系统的稳定运行提供了坚实基础。模型间的层次化设计支持复杂的组织架构，灵活的状态管理适应不同的业务流程，而完善的验证机制确保了数据质量。
+
+## 附录
+
+### 模型使用示例
+
+#### 创建员工
+```python
+# 通过服务层创建员工
+staff = await StaffService.create(db, staff_data)
+```
+
+#### 创建考核记录
+```python
+# 通过服务层创建考核
+assessment = await AssessmentService.create(db, assessment_data)
+```
+
+#### 生成工资记录
+```python
+# 基于考核结果生成工资
+salary_record = await SalaryService.generate_from_assessment(db, staff_id, year, month)
+```
+
+### 最佳实践
+
+1. **数据完整性**：始终使用 Pydantic 模式进行数据验证
+2. **事务管理**：在复杂操作中使用数据库事务保证一致性
+3. **索引优化**：根据查询模式合理创建索引
+4. **错误处理**：完善异常处理和回滚机制
+5. **性能监控**：定期分析慢查询日志优化性能
+
+**章节来源**
+- [staff_service.py](file://backend/app/services/staff_service.py#L70-L91)
+- [assessment_service.py](file://backend/app/services/assessment_service.py#L71-L108)
+- [salary_service.py](file://backend/app/services/salary_service.py#L127-L190)