# 实体关系设计

<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)
- [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)
- [database.md](file://docs/database.md)
- [staff.py](file://backend/app/api/v1/staff.py)
- [assessments.py](file://backend/app/api/v1/assessments.py)
- [performance_plans.py](file://backend/app/api/v1/performance_plans.py)
- [salary.py](file://backend/app/api/v1/salary.py)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心实体](#核心实体)
4. [架构概览](#架构概览)
5. [详细实体分析](#详细实体分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)

## 简介

本文件为医院绩效系统的实体关系设计文档，详细描述了系统中所有核心实体之间的关系映射。该系统采用基于平衡计分卡的绩效管理体系，涵盖了科室管理、员工管理、绩效考核、工资核算、指标模板等多个业务领域。文档重点解释了一对一、一对多、多对多关系的设计原理和业务逻辑，包含外键约束、级联操作和引用完整性保证，并提供了完整的ER图说明。

## 项目结构

系统采用前后端分离架构，后端使用FastAPI + SQLAlchemy异步ORM框架，数据库采用PostgreSQL。项目结构清晰地按照功能模块组织：

```mermaid
graph TB
subgraph "后端架构"
API[API路由层]
Services[业务服务层]
Models[数据模型层]
Database[数据库层]
end
subgraph "前端架构"
Vue[Vue.js前端]
Components[组件库]
Router[路由系统]
end
API --> Services
Services --> Models
Models --> Database
Vue --> API
```

**图表来源**
- [database.py](file://backend/app/core/database.py#L1-L39)
- [config.py](file://backend/app/core/config.py#L1-L47)

**章节来源**
- [database.py](file://backend/app/core/database.py#L1-L39)
- [config.py](file://backend/app/core/config.py#L1-L47)

## 核心实体

系统包含以下核心实体，每个实体都承载着特定的业务职责：

### 基础实体
- **Department**: 科室信息管理，支持多级组织架构
- **Staff**: 员工信息管理，包含职位、职称、薪资等信息
- **User**: 系统用户管理，支持角色权限控制

### 考核相关实体
- **Assessment**: 绩效考核记录，管理考核流程状态
- **AssessmentDetail**: 考核明细，记录具体指标得分
- **Indicator**: 考核指标定义，支持多种指标类型

### 计划与模板实体
- **PerformancePlan**: 绩效计划管理，支持多层级计划
- **PlanKpiRelation**: 计划与指标关联关系
- **IndicatorTemplate**: 指标模板，支持按科室类型分类
- **TemplateIndicator**: 模板与指标关联关系

### 财务实体
- **SalaryRecord**: 工资核算记录
- **DepartmentFinance**: 科室财务记录

**章节来源**
- [models.py](file://backend/app/models/models.py#L62-L438)
- [finance.py](file://backend/app/models/finance.py#L45-L79)

## 架构概览

系统采用分层架构设计，确保业务逻辑与数据访问的分离：

```mermaid
graph TB
subgraph "表现层"
Frontend[前端Vue应用]
end
subgraph "应用层"
API[FastAPI路由]
Services[业务服务]
end
subgraph "数据层"
ORM[SQLAlchemy ORM]
DB[(PostgreSQL数据库)]
end
Frontend --> API
API --> Services
Services --> ORM
ORM --> DB
subgraph "核心实体关系"
Department --> Staff
Staff --> Assessment
Assessment --> AssessmentDetail
AssessmentDetail --> Indicator
Staff --> SalaryRecord
Department --> DepartmentFinance
PerformancePlan --> PlanKpiRelation
IndicatorTemplate --> TemplateIndicator
end
```

**图表来源**
- [models.py](file://backend/app/models/models.py#L62-L438)
- [finance.py](file://backend/app/models/finance.py#L45-L79)

## 详细实体分析

### Department - 科室实体

Department实体是整个系统的核心组织单元，支持多级嵌套的科室结构：

```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
}
class Staff {
+int id
+string employee_id
+string name
+int department_id
+string position
+string title
+float base_salary
+float performance_ratio
+StaffStatus status
+datetime hire_date
}
Department "1" o-- "N" Staff : "包含"
Department "1" <-- "N" Department : "子科室"
```

**图表来源**
- [models.py](file://backend/app/models/models.py#L62-L86)
- [models.py](file://backend/app/models/models.py#L88-L115)

**业务逻辑**：
- 支持多级科室嵌套（parent_id自关联）
- 通过level字段维护层级关系
- dept_type枚举定义了8种科室类型
- 提供sort_order进行排序管理

**外键约束**：
- parent_id -> departments.id (自关联)
- 外键约束确保引用完整性

**索引设计**：
- idx_dept_type: 加速科室类型查询
- idx_dept_parent: 加速父子关系查询

### Staff - 员工实体

Staff实体管理所有员工信息，与Department形成一对多关系：

```mermaid
classDiagram
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
+float total_score
+float weighted_score
+AssessmentStatus status
+int assessor_id
+int reviewer_id
}
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
}
class User {
+int id
+string username
+string password_hash
+int staff_id
+string role
+bool is_active
}
Department --> Staff : "1 : N"
Staff --> Assessment : "1 : N"
Staff --> SalaryRecord : "1 : N"
Staff --> User : "1 : 1"
```

**图表来源**
- [models.py](file://backend/app/models/models.py#L88-L115)
- [models.py](file://backend/app/models/models.py#L149-L179)
- [models.py](file://backend/app/models/models.py#L205-L231)
- [models.py](file://backend/app/models/models.py#L244-L261)

**业务逻辑**：
- employee_id唯一标识员工身份
- performance_ratio影响最终绩效奖金计算
- status枚举管理员工生命周期状态
- 与User实体建立一对一关系用于系统权限

**外键约束**：
- department_id -> departments.id (强制约束)
- staff_id (Assessment) -> staff.id (级联更新/删除)

**索引设计**：
- idx_staff_dept: 加速科室员工查询
- idx_staff_status: 加速状态过滤查询

### Assessment - 考核记录实体

Assessment实体管理完整的考核流程，包含多个角色参与：

```mermaid
sequenceDiagram
participant Employee as 员工
participant Assessor as 考核人
participant Reviewer as 审核人
participant System as 系统
Employee->>System : 创建考核记录
System->>Assessor : 分配考核任务
Assessor->>System : 填写考核结果
System->>Reviewer : 提交审核
Reviewer->>System : 审核通过/驳回
System->>Employee : 通知考核结果
System->>System : 生成工资记录
```

**图表来源**
- [models.py](file://backend/app/models/models.py#L149-L179)
- [assessments.py](file://backend/app/api/v1/assessments.py#L105-L146)

**业务逻辑**：
- 支持草稿、已提交、已审核、已确认、已驳回等状态
- assessor_id和reviewer_id允许同一人或不同人
- 自动计算total_score和weighted_score
- 与AssessmentDetail形成一对多关系

**外键约束**：
- staff_id -> staff.id (RESTRICT)
- assessor_id -> staff.id (SET NULL)
- reviewer_id -> staff.id (SET NULL)

**级联操作**：
- Assessment删除时，details自动删除 (DELETE-ORPHAN)

### AssessmentDetail - 考核明细实体

AssessmentDetail实体记录具体的指标得分：

```mermaid
classDiagram
class AssessmentDetail {
+int id
+int assessment_id
+int indicator_id
+float actual_value
+float score
+string evidence
+string remark
}
class Indicator {
+int id
+string name
+string code
+IndicatorType indicator_type
+BSCDimension bs_dimension
+float weight
+float max_score
+float target_value
+string calculation_method
+bool is_veto
}
Assessment --> AssessmentDetail : "1 : N"
Indicator --> AssessmentDetail : "1 : N"
```

**图表来源**
- [models.py](file://backend/app/models/models.py#L181-L203)
- [models.py](file://backend/app/models/models.py#L117-L147)

**业务逻辑**：
- 记录每个指标的实际值和计算得分
- 支持证据材料上传
- is_veto字段实现一票否决机制

**外键约束**：
- assessment_id -> assessments.id (CASCADE DELETE)
- indicator_id -> indicators.id (RESTRICT)

### Indicator - 指标实体

Indicator实体定义了完整的考核指标体系：

```mermaid
classDiagram
class Indicator {
+int id
+string name
+string code
+IndicatorType indicator_type
+BSCDimension bs_dimension
+float weight
+float max_score
+float target_value
+string target_unit
+string calculation_method
+string assessment_method
+string deduction_standard
+string data_source
+string applicable_dept_types
+bool is_veto
+bool is_active
}
class AssessmentDetail {
+int id
+int assessment_id
+int indicator_id
+float actual_value
+float score
}
Indicator --> AssessmentDetail : "1 : N"
```

**图表来源**
- [models.py](file://backend/app/models/models.py#L117-L147)

**业务逻辑**：
- 支持质量、数量、效率、服务、成本五种指标类型
- BSC维度支持财务、客户、内部流程、学习与成长四个维度
- applicable_dept_types存储适用科室类型的JSON数组
- 支持复杂的计算方法和扣分标准

**约束条件**：
- weight > 0 的检查约束
- code唯一性约束

### SalaryRecord - 工资记录实体

SalaryRecord实体管理工资核算过程：

```mermaid
flowchart TD
Start([开始工资核算]) --> CheckAssessment["检查是否存在已确认的考核记录"]
CheckAssessment --> HasAssessment{"存在已确认考核？"}
HasAssessment --> |否| Error["返回错误：未找到已确认的考核记录"]
HasAssessment --> |是| CheckExisting["检查是否已存在工资记录"]
CheckExisting --> HasExisting{"已存在工资记录？"}
HasExisting --> |是| Error
HasExisting --> |否| Calculate["计算各项工资项目"]
Calculate --> Generate["生成工资记录"]
Generate --> Confirm["设置状态为已确认"]
Confirm --> End([完成])
Error --> End
```

**图表来源**
- [models.py](file://backend/app/models/models.py#L205-L231)
- [salary.py](file://backend/app/api/v1/salary.py#L96-L111)

**业务逻辑**：
- 基于考核结果计算绩效奖金
- 支持批量生成功能
- 与Assessment形成间接关联关系

**外键约束**：
- staff_id -> staff.id (RESTRICT)

### PerformancePlan - 绩效计划实体

PerformancePlan实体管理多层次的绩效计划：

```mermaid
classDiagram
class PerformancePlan {
+int id
+string plan_name
+string plan_code
+PlanLevel plan_level
+int plan_year
+int plan_month
+string plan_type
+int department_id
+int staff_id
+int parent_plan_id
+string description
+string strategic_goals
+string key_initiatives
+PlanStatus status
+int submitter_id
+int approver_id
+int version
+bool is_active
}
class PlanKpiRelation {
+int id
+int plan_id
+int indicator_id
+float target_value
+string target_unit
+float weight
+string scoring_method
+string scoring_params
}
PerformancePlan --> PlanKpiRelation : "1 : N"
PerformancePlan --> PerformancePlan : "1 : N (父子计划)"
```

**图表来源**
- [models.py](file://backend/app/models/models.py#L270-L312)
- [models.py](file://backend/app/models/models.py#L314-L339)

**业务逻辑**：
- 支持医院级、科室级、个人级三个层级
- 支持年度和月度两种计划类型
- parent_plan_id实现计划的层次化管理

**外键约束**：
- department_id -> departments.id (SET NULL)
- staff_id -> staff.id (SET NULL)
- parent_plan_id -> performance_plans.id (SET NULL)

### IndicatorTemplate & TemplateIndicator - 模板实体

模板系统支持按科室类型预设指标组合：

```mermaid
classDiagram
class IndicatorTemplate {
+int id
+string template_name
+string template_code
+TemplateType template_type
+string description
+string dimension_weights
+string assessment_cycle
+bool is_active
}
class TemplateIndicator {
+int id
+int template_id
+int indicator_id
+string category
+float target_value
+string target_unit
+float weight
+string scoring_method
+string scoring_params
+int sort_order
}
IndicatorTemplate --> TemplateIndicator : "1 : N"
TemplateIndicator --> Indicator : "M : N"
```

**图表来源**
- [models.py](file://backend/app/models/models.py#L387-L409)
- [models.py](file://backend/app/models/models.py#L411-L438)

**业务逻辑**：
- 按科室类型提供标准化的指标模板
- 支持维度权重配置
- sort_order控制指标显示顺序

**约束条件**：
- template_code唯一性
- template_id + indicator_id唯一性组合

### DepartmentFinance - 科室财务实体

DepartmentFinance实体管理科室财务数据：

```mermaid
classDiagram
class DepartmentFinance {
+int id
+int department_id
+int period_year
+int period_month
+FinanceType finance_type
+string category
+float amount
+string source
+string remark
}
class Department {
+int id
+string name
+string code
+DeptType dept_type
}
Department --> DepartmentFinance : "1 : N"
```

**图表来源**
- [finance.py](file://backend/app/models/finance.py#L45-L75)

**业务逻辑**：
- 支持收入和支出两类财务记录
- category字段区分具体财务项目
- amount字段强制非负数

**约束条件**：
- amount >= 0 的检查约束
- 复合索引优化查询性能

## 依赖关系分析

系统实体间存在复杂的依赖关系，通过外键约束确保数据一致性：

```mermaid
graph TB
subgraph "组织架构依赖"
Department --> Staff
Staff --> Assessment
Assessment --> AssessmentDetail
AssessmentDetail --> Indicator
end
subgraph "计划管理依赖"
PerformancePlan --> PlanKpiRelation
PlanKpiRelation --> Indicator
PerformancePlan --> PerformancePlan
end
subgraph "模板系统依赖"
IndicatorTemplate --> TemplateIndicator
TemplateIndicator --> Indicator
end
subgraph "财务关联依赖"
Department --> DepartmentFinance
Staff --> SalaryRecord
end
subgraph "用户系统依赖"
Staff --> User
PerformancePlan --> User
end
```

**图表来源**
- [models.py](file://backend/app/models/models.py#L62-L438)
- [finance.py](file://backend/app/models/finance.py#L45-L79)

**外键约束策略**：
- 强制约束：department_id, staff_id, indicator_id
- 级联约束：Assessment删除时自动删除AssessmentDetail
- 设置为空：staff_id在User中可为空，便于用户与员工解耦

**级联操作配置**：
- Assessment.cascade(delete-orphan): 删除Assessment时自动清理明细
- PlanKpiRelation.cascade(delete-orphan): 删除计划时清理指标关联
- 多对多关系通过中间表实现，避免复杂的级联操作

## 性能考虑

系统在设计时充分考虑了性能优化：

### 索引策略
- 复合索引优化常用查询模式
- 枚举字段建立独立索引
- 时间字段建立范围查询索引

### 查询优化
- 使用selectinload减少N+1查询问题
- 合理的连接策略避免笛卡尔积
- 分页查询限制结果集大小

### 缓存策略
- 配置数据库连接池
- 异步查询提升并发性能
- 合理的事务管理避免锁竞争

## 故障排除指南

### 常见问题及解决方案

**1. 外键约束冲突**
- 症状：插入或更新数据时报外键约束错误
- 解决：检查关联实体是否存在且状态有效
- 预防：在业务层先验证关联关系

**2. 数据重复问题**
- 症状：唯一约束冲突
- 解决：检查employee_id、code、template_code等唯一字段
- 预防：在创建前进行唯一性检查

**3. 级联删除问题**
- 症状：删除主记录时意外删除相关数据
- 解决：检查cascade配置，必要时调整为RESTRICT
- 预防：在删除前确认级联影响范围

**4. 性能问题**
- 症状：查询响应缓慢
- 解决：检查索引使用情况，优化查询条件
- 预防：定期分析查询执行计划

**章节来源**
- [models.py](file://backend/app/models/models.py#L144-L146)
- [finance.py](file://backend/app/models/finance.py#L73-L74)

## 结论

本实体关系设计文档全面阐述了医院绩效系统的数据模型架构。系统采用规范化的数据库设计，通过合理的实体划分和关系映射，实现了以下目标：

1. **业务完整性**：完整覆盖医院绩效管理的各个业务环节
2. **数据一致性**：通过外键约束和级联操作确保数据完整性
3. **扩展性**：支持多层级组织架构和灵活的指标模板系统
4. **性能优化**：合理的索引设计和查询策略
5. **安全性**：通过用户权限管理和数据访问控制

该设计为后续的功能扩展和系统维护奠定了坚实的基础，能够满足医院绩效管理的复杂业务需求。