hospital_performance/.qoder/repowiki/zh/content/数据库设计/数据库设计.md

数据库设计

**本文引用的文件** - [backend/app/models/models.py](file://backend/app/models/models.py) - [backend/app/models/finance.py](file://backend/app/models/finance.py) - [backend/alembic/versions/001_initial.py](file://backend/alembic/versions/001_initial.py) - [backend/alembic/versions/002_template.py](file://backend/alembic/versions/002_template.py) - [backend/alembic/env.py](file://backend/alembic/env.py) - [backend/alembic.ini](file://backend/alembic.ini) - [backend/app/core/database.py](file://backend/app/core/database.py) - [backend/app/core/config.py](file://backend/app/core/config.py) - [backend/init_db.py](file://backend/init_db.py) - [docs/database.md](file://docs/database.md) - [docs/详细设计文档.md](file://docs/详细设计文档.md) - [backend/create_menu_tables.py](file://backend/create_menu_tables.py) - [backend/create_plan_tables.py](file://backend/create_plan_tables.py)

目录

1. 简介
2. 项目结构
3. 核心组件
4. 架构总览
5. 详细组件分析
6. 依赖分析
7. 性能考虑
8. 故障排查指南
9. 结论
10. 附录

简介

本文件面向“医院绩效系统”的数据库设计，围绕核心数据模型（Department、Staff、Assessment、AssessmentDetail、SalaryRecord）给出完整的ER实体关系图、表结构与字段定义、主键/外键/索引/约束设计原则、数据类型与长度限制、业务规则实现、数据字典、典型数据示例、数据库迁移策略与版本管理、以及性能优化建议。文档同时结合后端模型定义与迁移脚本，确保设计与实现一致。

项目结构

后端采用 SQLAlchemy ORM + Alembic 进行模型定义与迁移管理，数据库连接通过异步引擎实现；迁移脚本位于 alembic/versions 下，环境配置由 alembic/env.py 和 alembic.ini 提供；核心模型集中在 backend/app/models/models.py，财务相关模型在 backend/app/models/finance.py。

graph TB
subgraph "数据库层"
DB[(PostgreSQL/SQLite)]
end
subgraph "迁移与配置"
AEnv["alembic/env.py"]
AIni["alembic.ini"]
V001["versions/001_initial.py"]
V002["versions/002_template.py"]
end
subgraph "模型与服务"
Models["models.py<br/>核心模型"]
Finance["finance.py<br/>财务模型"]
DBMod["database.py<br/>异步引擎/会话"]
Cfg["config.py<br/>配置"]
InitDB["init_db.py<br/>初始化脚本"]
end
AEnv --> V001
AEnv --> V002
AIni --> AEnv
DBMod --> Models
DBMod --> Finance
Cfg --> DBMod
InitDB --> Models
InitDB --> DBMod
Models --> DB
Finance --> DB
V001 --> DB
V002 --> DB

图表来源

• backend/alembic/env.py
• backend/alembic/versions/001_initial.py
• backend/alembic/versions/002_template.py
• backend/app/models/models.py
• backend/app/models/finance.py
• backend/app/core/database.py
• backend/app/core/config.py
• backend/init_db.py

章节来源

• backend/alembic/env.py
• backend/alembic/versions/001_initial.py
• backend/alembic/versions/002_template.py
• backend/app/models/models.py
• backend/app/models/finance.py
• backend/app/core/database.py
• backend/app/core/config.py
• backend/init_db.py

核心组件

本节聚焦于系统的核心数据模型：Department（科室）、Staff（员工）、Assessment（考核记录）、AssessmentDetail（考核明细）、SalaryRecord（工资核算记录）。这些模型通过外键形成稳定的层次关系，支撑绩效计划、指标模板、财务核算等扩展能力。

• Department（科室）

  • 主键：id
  • 外键：parent_id → departments.id（自关联，支持多级组织树）
  • 索引：idx_dept_type、idx_dept_parent
  • 约束：code 唯一；is_active 默认启用
  • 关系：与 Staff 一对多；与自身一对一（子/父）

• Staff（员工）

  • 主键：id
  • 外键：department_id → departments.id
  • 索引：idx_staff_dept、idx_staff_status
  • 约束：employee_id 唯一；status 枚举；base_salary/performance_ratio 数值范围合理
  • 关系：与 Department 多对一；与 Assessment、SalaryRecord 一对多

• Assessment（考核记录）

  • 主键：id
  • 外键：staff_id → staff.id；assessor_id/reviewer_id → staff.id（自关联）
  • 索引：idx_assessment_staff、idx_assessment_period、idx_assessment_status
  • 约束：period_year/period_month 组合用于周期查询；status 枚举
  • 关系：与 Staff 多对一；与 AssessmentDetail 一对多（级联删除）

• AssessmentDetail（考核明细）

  • 主键：id
  • 外键：assessment_id → assessments.id；indicator_id → indicators.id
  • 索引：idx_detail_assessment、idx_detail_indicator
  • 关系：与 Assessment、Indicator 多对一

• SalaryRecord（工资核算记录）

  • 主键：id
  • 外键：staff_id → staff.id
  • 索引：idx_salary_staff、idx_salary_period
  • 约束：total_salary 由基础字段计算得出；status 字符串枚举
  • 关系：与 Staff 多对一

章节来源

• backend/app/models/models.py

架构总览

下图展示核心模型之间的实体关系与依赖方向，体现从组织结构到人员、再到考核与薪酬的完整闭环。

erDiagram
DEPARTMENTS {
int id PK
string name
string code UK
string dept_type
int parent_id FK
int level
int sort_order
boolean is_active
text description
datetime created_at
datetime updated_at
}
STAFF {
int id PK
string employee_id UK
string name
int department_id FK
string position
string title
string phone
string email
numeric base_salary
numeric performance_ratio
string status
datetime hire_date
datetime created_at
datetime updated_at
}
ASSESSMENTS {
int id PK
int staff_id FK
int period_year
int period_month
string period_type
numeric total_score
numeric weighted_score
string status
int assessor_id FK
int reviewer_id FK
datetime submit_time
datetime review_time
text remark
datetime created_at
datetime updated_at
}
ASSESSMENT_DETAILS {
int id PK
int assessment_id FK
int indicator_id FK
numeric actual_value
numeric score
text evidence
text remark
datetime created_at
datetime updated_at
}
SALARY_RECORDS {
int id PK
int staff_id FK
int period_year
int period_month
numeric base_salary
numeric performance_score
numeric performance_bonus
numeric deduction
numeric allowance
numeric total_salary
string status
text remark
datetime created_at
datetime updated_at
}
DEPARTMENTS ||--o{ STAFF : "1:N"
STAFF ||--o{ ASSESSMENTS : "1:N"
STAFF ||--o{ SALARY_RECORDS : "1:N"
ASSESSMENTS ||--o{ ASSESSMENT_DETAILS : "1:N"

图表来源

• backend/app/models/models.py

详细组件分析

Department（科室）分析

• 设计要点
  • 自关联 parent_id 支持多层级组织树，level 与 sort_order 辅助排序与层级判断。
  • dept_type 使用枚举，统一管理 9 类科室类型，便于筛选与报表统计。
  • idx_dept_type、idx_dept_parent 提升按类型与父子关系的查询效率。
• 业务规则
  • code 唯一，保证科室编码规范；is_active 控制启用状态。
• 典型数据示例
  • 内科、外科、妇产科、儿科、放射科、检验科、财务科、人事科等。

章节来源

• backend/app/models/models.py
• backend/init_db.py

Staff（员工）分析

• 设计要点
  • employee_id 唯一，作为外部识别码；department_id 外键关联科室。
  • base_salary 与 performance_ratio 为薪酬计算基础；status 枚举管理在职状态。
  • idx_staff_dept、idx_staff_status 优化按科室与状态的检索。
• 业务规则
  • hire_date 记录入职时间；updated_at 自动更新时间戳。
• 典型数据示例
  • 张三、李四、王五、赵六、钱七、孙八、周九、吴十等员工信息。

章节来源

• backend/app/models/models.py
• backend/init_db.py

Assessment（考核记录）分析

• 设计要点
  • period_year 与 period_month 组合唯一性可用于周期性考核的快速定位。
  • assessor_id 与 reviewer_id 自关联 staff，支持多人协作与审核流程。
  • status 枚举覆盖草稿、提交、审核、确认、驳回等状态流转。
  • idx_assessment_staff、idx_assessment_period、idx_assessment_status 提升查询性能。
• 业务规则
  • total_score 与 weighted_score 用于汇总与加权计算；submit_time、review_time 记录关键节点时间。
• 典型数据示例
  • 某员工某年某月的考核记录，包含多个指标得分与佐证材料链接。

章节来源

• backend/app/models/models.py

AssessmentDetail（考核明细）分析

• 设计要点
  • assessment_id 与 indicator_id 组成明细项，支持多指标、多周期的细粒度记录。
  • actual_value 与 score 记录实际值与得分；evidence 与 remark 支持审计与说明。
  • idx_detail_assessment、idx_detail_indicator 优化明细查询。
• 业务规则
  • 与 Assessment 的级联删除保证数据一致性；与 Indicator 的关联确保指标有效性。

章节来源

• backend/app/models/models.py

SalaryRecord（工资核算记录）分析

• 设计要点
  • period_year 与 period_month 组合用于月度工资归集；staff_id 外键关联员工。
  • total_salary 由基础字段计算，避免冗余存储；status 字符串枚举控制流程状态。
  • idx_salary_staff、idx_salary_period 优化按员工与周期的检索。
• 业务规则
  • 仅允许待确认状态下的更新；最终结算后冻结变更。
• 典型数据示例
  • 基本工资、绩效得分、绩效奖金、扣款、补贴、应发工资等字段构成完整薪酬清单。

章节来源

• backend/app/models/models.py

财务核算模型（DepartmentFinance）分析

• 设计要点
  • department_id 外键关联科室；finance_type 与 category 组合区分收入/支出与具体类别。
  • amount 使用数值类型并带非负校验；period_year/period_month 用于月度归集。
  • idx_finance_dept、idx_finance_period、idx_finance_type、idx_finance_category 提升财务报表查询效率。
• 业务规则
  • amount ≥ 0；category 与 finance_type 枚举化，便于多维分析。

章节来源

• backend/app/models/finance.py

指标模板与计划管理（扩展能力）

• 指标模板（IndicatorTemplate）与模板指标（TemplateIndicator）
  • 通过模板类型与维度权重，支持不同科室类型的指标套用；模板与指标的多对多关系通过中间表维护。
  • idx_template_type、idx_template_active 与 idx_ti_unique 索引提升模板与关联查询效率。
• 绩效计划（PerformancePlan）与计划指标（PlanKpiRelation）
  • 支持医院级、科室级、个人级三层计划；parent_plan_id 形成计划树；version 字段用于版本管理。

章节来源

• backend/app/models/models.py
• backend/alembic/versions/002_template.py

依赖分析

• 模型依赖
  • models.py 定义了核心实体与关系；finance.py 作为财务扩展模型，通过延迟导入避免循环依赖。
  • Alembic 迁移脚本 versions/001_initial.py 与 versions/002_template.py 与模型定义保持一一对应。
• 运行时依赖
  • database.py 提供异步引擎与会话工厂；config.py 提供数据库连接字符串与池参数；env.py 与 alembic.ini 配置迁移环境。

graph LR
Cfg["config.py"] --> DB["database.py"]
DB --> Models["models.py"]
DB --> Finance["finance.py"]
AEnv["alembic/env.py"] --> V001["versions/001_initial.py"]
AEnv --> V002["versions/002_template.py"]
AIni["alembic.ini"] --> AEnv
InitDB["init_db.py"] --> DB
InitDB --> Models

图表来源

• backend/app/core/config.py
• backend/app/core/database.py
• backend/app/models/models.py
• backend/app/models/finance.py
• backend/alembic/env.py
• backend/alembic/versions/001_initial.py
• backend/alembic/versions/002_template.py
• backend/alembic.ini
• backend/init_db.py

章节来源

• backend/app/core/config.py
• backend/app/core/database.py
• backend/app/models/models.py
• backend/app/models/finance.py
• backend/alembic/env.py
• backend/alembic/versions/001_initial.py
• backend/alembic/versions/002_template.py
• backend/alembic.ini
• backend/init_db.py

性能考虑

• 索引策略
  • 按查询热点建立复合索引：如 assessments 的 (period_year, period_month)，salary_records 的 (period_year, period_month)，有效降低周期性统计的扫描成本。
  • 对枚举字段（如 dept_type、status）建立单列索引，提升过滤效率。
• 数值精度
  • 金额与分数使用 Numeric(precision, scale) 精确存储，避免浮点误差；例如 base_salary、performance_bonus、deduction 等均采用 DECIMAL(10,2)。
• 查询优化
  • 使用关系预加载（relationship）减少 N+1 查询；对高频报表场景可引入物化视图或汇总表。
• 连接池与并发
  • 通过 DATABASE_POOL_SIZE 与 DATABASE_MAX_OVERFLOW 控制连接池大小，避免高并发下的连接争用。
• 异步执行
  • 异步引擎与会话减少阻塞，适合高吞吐的 API 场景。

章节来源

• backend/app/models/models.py
• backend/app/models/models.py
• backend/app/models/models.py
• backend/app/models/models.py
• backend/app/models/models.py
• backend/app/core/config.py

故障排查指南

• 迁移失败
  • 确认 alembic.ini 中 sqlalchemy.url 与 config.py 中 DATABASE_URL 一致；检查 Alembic 环境配置（env.py）是否正确指向 Base.metadata。
  • 使用离线模式验证迁移脚本语法：alembic -c backend/alembic.ini --raiseerr revision --autogenerate -m "test"。
• 连接问题
  • 检查 DATABASE_URL 是否可达；确认数据库服务运行状态；查看 DEBUG 输出定位异常。
• 数据不一致
  • 核对 Assessment 与 AssessmentDetail 的级联删除策略；确认 SalaryRecord 的状态机（仅待确认可更新）。
• 初始化数据
  • 使用 init_db.py 创建表并插入测试数据；若已有数据则跳过插入逻辑，避免重复。

章节来源

• backend/alembic/env.py
• backend/alembic.ini
• backend/app/core/config.py
• backend/init_db.py

结论

本数据库设计以 Department、Staff、Assessment、AssessmentDetail、SalaryRecord 为核心，配合财务核算与指标模板/计划管理扩展，形成从组织到个人、从指标到薪酬的完整闭环。通过合理的索引、数值精度与异步连接池配置，兼顾了查询性能与并发稳定性。借助 Alembic 的迁移机制，能够安全地演进数据库结构并管理版本。

附录

数据字典（核心表）

• departments（科室）
  • 字段：id、name、code（UNIQUE）、dept_type、parent_id、level、sort_order、is_active、description、created_at、updated_at
  • 索引：idx_dept_type、idx_dept_parent
• staff（员工）
  • 字段：id、employee_id（UNIQUE）、name、department_id、position、title、phone、email、base_salary、performance_ratio、status、hire_date、created_at、updated_at
  • 索引：idx_staff_dept、idx_staff_status
• assessments（考核记录）
  • 字段：id、staff_id、period_year、period_month、period_type、total_score、weighted_score、status、assessor_id、reviewer_id、submit_time、review_time、remark、created_at、updated_at
  • 索引：idx_assessment_staff、idx_assessment_period、idx_assessment_status
• assessment_details（考核明细）
  • 字段：id、assessment_id、indicator_id、actual_value、score、evidence、remark、created_at、updated_at
  • 索引：idx_detail_assessment、idx_detail_indicator
• salary_records（工资核算记录）
  • 字段：id、staff_id、period_year、period_month、base_salary、performance_score、performance_bonus、deduction、allowance、total_salary、status、remark、created_at、updated_at
  • 索引：idx_salary_staff、idx_salary_period

章节来源

• docs/database.md
• backend/app/models/models.py

数据库迁移与版本管理

• 迁移命令
  • 生成迁移：alembic -c backend/alembic.ini --raiseerr revision --autogenerate -m "描述"
  • 升级到最新：alembic -c backend/alembic.ini upgrade head
  • 回滚一步：alembic -c backend/alembic.ini downgrade -1
• 版本文件
  • 初始版本：versions/001_initial.py
  • 指标模板版本：versions/002_template.py
• 环境配置
  • alembic/env.py 指向 Base.metadata 并支持异步迁移
  • alembic.ini 提供默认 SQLite 路径，生产环境请替换为 PostgreSQL URL

章节来源

• backend/alembic/env.py
• backend/alembic/versions/001_initial.py
• backend/alembic/versions/002_template.py
• backend/alembic.ini

典型数据示例

• 科室：内科、外科、妇产科、儿科、放射科、检验科、财务科、人事科
• 员工：张三、李四、王五、赵六、钱七、孙八、周九、吴十
• 考核：某员工某年某月的多指标得分与佐证材料
• 工资：基本工资、绩效得分、绩效奖金、扣款、补贴、应发工资

章节来源

• backend/init_db.py
• docs/详细设计文档.md