chenqi/hospital_performance
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

提交文件

Browse Source
This commit is contained in:
chenqi
2026-02-28 15:16:15 +08:00
parent 1a4e50e0a4
commit 44f250f58e
159 changed files with 61268 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

476
.qoder/repowiki/zh/content/数据模型详解/核心数据模型/员工信息模型.md Normal file
View File

@@ -0,0 +1,476 @@
# 员工信息模型
<cite>
**本文档引用的文件**
- [models.py](file://backend/app/models/models.py)
- [schemas.py](file://backend/app/schemas/schemas.py)
- [staff.py](file://backend/app/api/v1/staff.py)
- [staff_service.py](file://backend/app/services/staff_service.py)
- [salary_service.py](file://backend/app/services/salary_service.py)
- [database.md](file://docs/database.md)
- [001_initial.py](file://backend/alembic/versions/001_initial.py)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概览](#架构概览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
## 简介
员工信息模型是医院绩效管理系统的核心数据模型之一，负责管理医院全体员工的基础信息、状态管理和薪资相关信息。该模型采用现代化的ORM设计，结合枚举类型、关系映射和约束机制，确保数据的完整性和一致性。
本模型不仅存储员工的基本信息，还通过复杂的业务逻辑处理员工状态变化对系统其他模块的影响，包括与科室的多对一关系、与考核记录的一对多关系、以及与工资记录的一对多关系。
## 项目结构
基于仓库的实际结构，员工信息模型主要分布在以下文件中：
```mermaid
graph TB
subgraph "后端架构"
A[models.py<br/>数据模型定义]
B[schemas.py<br/>数据验证模式]
C[staff.py<br/>API路由]
D[staff_service.py<br/>业务服务层]
E[salary_service.py<br/>工资服务层]
end
subgraph "数据库层"
F[database.md<br/>数据库设计文档]
G[001_initial.py<br/>数据库迁移脚本]
end
A --> B
A --> C
A --> D
A --> E
C --> D
D --> A
E --> A
F --> A
G --> A
```
**图表来源**
- [models.py](file://backend/app/models/models.py#L88-L115)
- [schemas.py](file://backend/app/schemas/schemas.py#L107-L149)
- [staff.py](file://backend/app/api/v1/staff.py#L1-L124)
**章节来源**
- [models.py](file://backend/app/models/models.py#L1-L438)
- [schemas.py](file://backend/app/schemas/schemas.py#L1-L743)
## 核心组件
### 员工状态枚举 (StaffStatus)
员工状态枚举定义了四种核心状态，每种状态都有明确的业务含义：
```mermaid
classDiagram
class StaffStatus {
<<enumeration>>
+ACTIVE
+LEAVE
+RESIGNED
+RETIRED
}
note for StaffStatus : "员工状态枚举\n- ACTIVE : 在职\n- LEAVE : 休假\n- RESIGNED : 离职\n- RETIRED : 退休"
```
**图表来源**
- [models.py](file://backend/app/models/models.py#L37-L43)
### 员工实体模型
员工实体模型包含了完整的员工信息结构：
```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
+datetime created_at
+datetime updated_at
+Department department
+Assessment[] assessments
+SalaryRecord[] salary_records
}
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 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
}
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 --> Department : "多对一"
Staff --> Assessment : "一对多"
Staff --> SalaryRecord : "一对多"
```
**图表来源**
- [models.py](file://backend/app/models/models.py#L88-L115)
- [models.py](file://backend/app/models/models.py#L62-L80)
- [models.py](file://backend/app/models/models.py#L149-L178)
- [models.py](file://backend/app/models/models.py#L205-L230)
**章节来源**
- [models.py](file://backend/app/models/models.py#L88-L115)
## 架构概览
员工信息模型在整个系统架构中扮演着核心角色，连接着多个业务模块：
```mermaid
graph TB
subgraph "表现层"
A[前端界面]
B[API网关]
end
subgraph "业务逻辑层"
C[员工管理API]
D[员工服务层]
E[工资服务层]
F[统计服务层]
end
subgraph "数据访问层"
G[员工模型]
H[科室模型]
I[考核模型]
J[工资模型]
end
subgraph "数据存储"
K[员工表]
L[科室表]
M[考核表]
N[工资记录表]
end
A --> B
B --> C
C --> D
C --> E
C --> F
D --> G
D --> H
E --> G
E --> I
E --> J
G --> K
H --> L
I --> M
J --> N
```
**图表来源**
- [staff.py](file://backend/app/api/v1/staff.py#L1-L124)
- [staff_service.py](file://backend/app/services/staff_service.py#L1-L112)
- [salary_service.py](file://backend/app/services/salary_service.py#L1-L260)
## 详细组件分析
### 员工状态管理
员工状态管理是系统中最复杂的业务逻辑之一，不同状态对系统行为产生不同的影响：
```mermaid
stateDiagram-v2
[*] --> 在职
在职 --> 休假 : "LEAVE"
在职 --> 离职 : "RESIGNED"
在职 --> 退休 : "RETIRED"
休假 --> 在职 : "恢复工作"
休假 --> 离职 : "转为离职"
休假 --> 退休 : "转为退休"
离职 --> [*]
退休 --> [*]
note right of 在职 : "可参与考核\n可生成工资记录\n可进行系统操作"
note right of 休假 : "暂停考核\n暂停工资计算\n但仍可查看信息"
note right of 离职 : "完全停止系统访问\n历史数据保留"
note right of 退休 : "特殊权限限制\n历史数据可查看"
```
**图表来源**
- [models.py](file://backend/app/models/models.py#L37-L43)
- [staff_service.py](file://backend/app/services/staff_service.py#L104-L112)
#### 状态变更对系统的影响
1. **考核模块影响**：
- 休假员工：暂停考核流程，但可查看历史考核记录
- 离职/退休员工：无法参与新的考核，仅能查看历史记录
2. **工资模块影响**：
- 休假员工：暂停工资计算，但可查看历史工资记录
- 离职/退休员工：不再生成新的工资记录
3. **权限控制影响**：
- 离职/退休员工：系统访问权限被限制
- 休假员工：部分功能受限
**章节来源**
- [staff_service.py](file://backend/app/services/staff_service.py#L104-L112)
### 工号唯一性设计
工号作为员工的唯一标识符，在系统中具有极高的重要性：
```mermaid
flowchart TD
A[员工创建请求] --> B{检查工号是否存在}
B --> |是| C[返回错误: 工号已存在]
B --> |否| D[验证工号格式]
D --> E{格式验证通过?}
E --> |否| F[返回错误: 工号格式不正确]
E --> |是| G[创建员工记录]
G --> H[返回成功响应]
I[员工更新请求] --> J{检查工号是否被其他员工使用}
J --> |是| K[返回错误: 工号已被使用]
J --> |否| L[更新员工记录]
L --> M[返回成功响应]
```
**图表来源**
- [staff.py](file://backend/app/api/v1/staff.py#L75-L78)
- [staff_service.py](file://backend/app/services/staff_service.py#L62-L67)
### 薪资系数设计
薪资系数是绩效工资计算的核心参数，直接影响最终的绩效奖金：
```mermaid
flowchart TD
A[绩效奖金计算] --> B[获取员工绩效系数]
B --> C[获取考核加权得分]
B --> D[获取绩效基数]
C --> E[计算公式]
D --> E
D --> F[绩效奖金 = 绩效基数 × (加权得分/100) × 绩效系数]
E --> F
F --> G[生成工资记录]
H[默认系数] --> I[1.0]
J[最小系数] --> K[0.0]
L[最大系数] --> M[5.0]
note right of F : "示例: 基础工资8000元\n绩效系数1.2\n加权得分85分\n绩效奖金 = 3000 × (85/100) × 1.2 = 3060元"
```
**图表来源**
- [salary_service.py](file://backend/app/services/salary_service.py#L71-L74)
- [salary_service.py](file://backend/app/services/salary_service.py#L167-L170)
**章节来源**
- [salary_service.py](file://backend/app/services/salary_service.py#L17-L18)
- [salary_service.py](file://backend/app/services/salary_service.py#L71-L74)
### 联系方式维护
员工联系方式的维护遵循严格的验证规则：
```mermaid
classDiagram
class ContactInfo {
+string phone
+string email
+validatePhone(phone) bool
+validateEmail(email) bool
+formatPhone(phone) string
+formatEmail(email) string
}
note for ContactInfo : "联系方式验证规则\n- 电话 : 最多20位数字\n- 邮箱 : 符合标准邮箱格式\n- 支持空值"
```
**图表来源**
- [schemas.py](file://backend/app/schemas/schemas.py#L126-L136)
### 职位职称管理
职位和职称信息用于区分员工的专业水平和职责范围：
```mermaid
classDiagram
class PositionManagement {
+string position
+string title
+validatePosition(position) bool
+validateTitle(title) bool
+getPositionLevel(position) int
+getTitleRank(title) int
}
note for PositionManagement : "职位管理\n- position : 职位名称\n- title : 职称等级\n- 支持空值\n- 用于权限和薪酬分级"
```
**图表来源**
- [models.py](file://backend/app/models/models.py#L96-L98)
- [schemas.py](file://backend/app/schemas/schemas.py#L112-L117)
## 依赖关系分析
员工信息模型与其他模块的依赖关系如下：
```mermaid
graph TB
subgraph "核心依赖"
A[Staff模型] --> B[Department模型]
A --> C[Assessment模型]
A --> D[SalaryRecord模型]
end
subgraph "服务层依赖"
E[StaffService] --> A
E --> B
F[SalaryService] --> A
F --> C
F --> D
end
subgraph "API层依赖"
G[StaffAPI] --> E
H[SalaryAPI] --> F
end
subgraph "数据验证"
I[StaffCreate] --> A
J[StaffUpdate] --> A
K[StaffResponse] --> A
end
A -.-> L[StaffStatus枚举]
B -.-> M[DeptType枚举]
C -.-> N[AssessmentStatus枚举]
D -.-> O[SalaryStatus枚举]
```
**图表来源**
- [models.py](file://backend/app/models/models.py#L88-L115)
- [staff_service.py](file://backend/app/services/staff_service.py#L9-L10)
- [salary_service.py](file://backend/app/services/salary_service.py#L10-L11)
**章节来源**
- [models.py](file://backend/app/models/models.py#L88-L115)
- [staff_service.py](file://backend/app/services/staff_service.py#L1-L112)
- [salary_service.py](file://backend/app/services/salary_service.py#L1-L260)
## 性能考虑
### 查询优化策略
1. **索引设计**：
- 员工表：`idx_staff_dept`（科室ID）、`idx_staff_status`（状态）
- 考核表：`idx_assessment_staff`（员工ID）、`idx_assessment_period`（考核周期）
- 工资表：`idx_salary_staff`（员工ID）、`idx_salary_period`（考核周期）
2. **查询优化**：
- 使用`selectinload`进行关联查询优化
- 实现分页查询避免大数据量加载
- 缓存常用查询结果
### 数据完整性保证
```mermaid
flowchart TD
A[数据操作] --> B[输入验证]
B --> C[业务规则检查]
C --> D[数据库约束验证]
D --> E[事务处理]
E --> F[数据持久化]
G[输入验证] --> H[字段长度验证]
G --> I[格式验证]
G --> J[范围验证]
K[业务规则检查] --> L[工号唯一性]
K --> M[状态有效性]
K --> N[关联关系验证]
O[数据库约束验证] --> P[唯一约束]
O --> Q[外键约束]
O --> R[检查约束]
```
**图表来源**
- [schemas.py](file://backend/app/schemas/schemas.py#L107-L136)
- [models.py](file://backend/app/models/models.py#L93-L114)
## 故障排除指南
### 常见问题及解决方案
1. **工号重复错误**
- 症状：创建员工时返回"工号已存在"
- 解决：检查现有员工列表，使用唯一工号
2. **状态变更异常**
- 症状：员工状态无法正常切换
- 解决：检查状态枚举值的有效性，确认业务流程
3. **薪资计算错误**
- 症状：绩效奖金计算结果不符合预期
- 解决：验证绩效系数范围（0-5），检查考核得分
4. **关联查询性能问题**
- 症状：员工列表加载缓慢
- 解决：添加适当的索引，优化查询条件
**章节来源**
- [staff.py](file://backend/app/api/v1/staff.py#L75-L78)
- [staff_service.py](file://backend/app/services/staff_service.py#L104-L112)
## 结论
员工信息模型通过精心设计的数据结构和业务逻辑，为医院绩效管理系统提供了坚实的基础。该模型不仅满足了基本的员工信息管理需求，更重要的是通过完善的枚举类型、关系映射和约束机制，确保了数据的完整性和业务逻辑的正确性。
模型的关键优势包括：
1. **清晰的状态管理**：通过枚举类型明确员工状态，便于业务逻辑处理
2. **灵活的薪资计算**：支持可调节的绩效系数，适应不同岗位的薪酬体系
3. **完善的关联关系**：与科室、考核、工资等模块形成完整的业务闭环
4. **严格的数据验证**：通过多种验证机制确保数据质量
5. **良好的扩展性**：模块化设计便于后续功能扩展
该模型为整个系统的稳定运行奠定了坚实基础，是医院绩效管理不可或缺的重要组成部分。

407
.qoder/repowiki/zh/content/数据模型详解/核心数据模型/工资核算模型.md Normal file
View File

@@ -0,0 +1,407 @@
# 工资核算模型
<cite>
**本文引用的文件**
- [backend/app/models/models.py](file://backend/app/models/models.py)
- [backend/app/models/finance.py](file://backend/app/models/finance.py)
- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py)
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.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)
- [frontend/src/views/salary/Salary.vue](file://frontend/src/views/salary/Salary.vue)
- [frontend/src/api/salary.js](file://frontend/src/api/salary.js)
- [docs/database.md](file://docs/database.md)
- [docs/详细设计文档.md](file://docs/详细设计文档.md)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概览](#架构概览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
本文档深入解析医院绩效系统中的工资核算模型，重点围绕SalaryRecord模型的设计理念、实现细节以及与考核系统的集成关系。文档涵盖以下关键内容：
- 基本工资、绩效得分、绩效奖金、扣款补贴的计算逻辑
- 工资核算的时间周期与状态管理（待处理、已确认）
- 应发工资的计算公式与字段约束
- 绩效奖金与绩效得分的关系、扣款与补贴的设置规则
- 与员工的多对一关系、历史记录的版本控制
- 批量核算的性能优化策略
- 工资计算示例、异常处理机制与数据准确性验证方法
## 项目结构
后端采用FastAPI + SQLAlchemy异步ORM架构，工资核算功能位于以下模块：
- 模型层：定义SalaryRecord、Staff、Assessment等实体及其关系
- 服务层：实现工资计算、生成、确认、批量处理等业务逻辑
- API层：提供REST接口，支持按考核生成工资、批量生成与确认
- 前端：提供工资记录查询、编辑、确认等界面
```mermaid
graph TB
subgraph "前端"
FE_View["Salary.vue<br/>视图组件"]
FE_API["salary.js<br/>API封装"]
end
subgraph "后端"
API["salary.py<br/>API路由"]
Service["salary_service.py<br/>服务层"]
Model["models.py<br/>数据模型"]
Schema["schemas.py<br/>数据模式"]
DB["数据库<br/>salary_records表"]
end
FE_View --> FE_API
FE_API --> API
API --> Service
Service --> Model
Model --> DB
Schema --> API
```
**图表来源**
- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L1-L156)
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L1-L260)
- [backend/app/models/models.py](file://backend/app/models/models.py#L205-L231)
- [frontend/src/views/salary/Salary.vue](file://frontend/src/views/salary/Salary.vue#L33-L245)
- [frontend/src/api/salary.js](file://frontend/src/api/salary.js#L1-L42)
**章节来源**
- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L1-L156)
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L1-L260)
- [backend/app/models/models.py](file://backend/app/models/models.py#L205-L231)
- [frontend/src/views/salary/Salary.vue](file://frontend/src/views/salary/Salary.vue#L33-L245)
- [frontend/src/api/salary.js](file://frontend/src/api/salary.js#L1-L42)
## 核心组件
- SalaryRecord模型：存储工资核算结果，包含基本工资、绩效得分、绩效奖金、扣款、补贴、应发工资与状态
- Staff模型：员工基本信息与绩效系数，用于绩效奖金计算
- Assessment模型：考核记录，提供加权得分作为绩效奖金依据
- SalaryService服务：实现工资计算、生成、确认、批量处理等核心逻辑
- API路由：提供查询、创建、更新、按考核生成、批量生成与确认等接口
**章节来源**
- [backend/app/models/models.py](file://backend/app/models/models.py#L205-L231)
- [backend/app/models/models.py](file://backend/app/models/models.py#L88-L115)
- [backend/app/models/models.py](file://backend/app/models/models.py#L149-L179)
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L14-L260)
- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L1-L156)
## 架构概览
工资核算从考核结果出发，通过服务层计算绩效奖金并生成工资记录；前端提供查询与确认操作，后端通过权限控制确保只有管理员或经理可以进行关键操作。
```mermaid
sequenceDiagram
participant Client as "客户端"
participant API as "salary.py"
participant Service as "salary_service.py"
participant DB as "数据库"
Client->>API : POST /salary/generate?staff_id&period_year&period_month
API->>Service : generate_from_assessment(staff_id, year, month)
Service->>DB : 查询员工信息(Staff)
Service->>DB : 查询已确认考核(Assessment.status='finalized')
Service->>Service : calculate_performance_bonus(weighted_score, performance_ratio)
Service->>DB : 插入SalaryRecord(状态=pending)
DB-->>Service : 返回新记录
Service-->>API : 返回记录ID
API-->>Client : {code,message,data : id}
```
**图表来源**
- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L96-L111)
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L127-L190)
**章节来源**
- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L96-L111)
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L127-L190)
## 详细组件分析
### SalaryRecord模型设计
- 字段定义
- 基本工资：base_salary，数值型，精度10位小数2位
- 绩效得分：performance_score，数值型，精度5位小数2位
- 绩效奖金：performance_bonus，数值型，精度10位小数2位
- 扣款：deduction，数值型，精度10位小数2位
- 补贴：allowance，数值型，精度10位小数2位
- 应发工资：total_salary，数值型，精度10位小数2位
- 状态：status，默认"pending"
- 时间周期：period_year、period_month
- 外键：staff_id，关联员工表
- 约束与索引
- 外键约束：staff_id -> staff.id
- 索引：staff_id、(period_year, period_month)
- 关系
- 与Staff为多对一关系，支持反向访问salary_records
```mermaid
classDiagram
class Staff {
+int id
+string employee_id
+string name
+int department_id
+string position
+string title
+float base_salary
+float performance_ratio
+string status
+datetime hire_date
+datetime created_at
+datetime updated_at
+Assessment[] assessments
+SalaryRecord[] salary_records
}
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 "1" o-- "*" SalaryRecord : "多对一"
```
**图表来源**
- [backend/app/models/models.py](file://backend/app/models/models.py#L88-L115)
- [backend/app/models/models.py](file://backend/app/models/models.py#L205-L231)
**章节来源**
- [backend/app/models/models.py](file://backend/app/models/models.py#L205-L231)
- [backend/alembic/versions/001_initial.py](file://backend/alembic/versions/001_initial.py#L133-L154)
- [docs/database.md](file://docs/database.md#L197-L216)
- [docs/详细设计文档.md](file://docs/详细设计文档.md#L642-L662)
### 计算逻辑与公式
- 绩效奖金计算
- 公式：绩效奖金 = 绩效基数 × (绩效得分/100) × 绩效系数
- 绩效基数：固定常量，服务层中定义
- 绩效系数：来自员工表的performance_ratio
- 应发工资计算
- 公式：应发工资 = 基本工资 + 绩效奖金 + 补贴 - 扣款
- 该公式在创建与更新工资记录时均会重新计算并持久化
```mermaid
flowchart TD
Start(["开始"]) --> LoadStaff["加载员工信息<br/>获取base_salary, performance_ratio"]
LoadStaff --> LoadAssessment["加载已确认考核<br/>获取weighted_score"]
LoadAssessment --> CheckExisting{"是否存在同周期工资记录？"}
CheckExisting --> |是| ReturnNone["返回空不重复生成"]
CheckExisting --> |否| CalcBonus["计算绩效奖金<br/>bonus = 基数 × (score/100) × ratio"]
CalcBonus --> CalcTotal["计算应发工资<br/>total = base + bonus + allowance - deduction"]
CalcTotal --> CreateRecord["创建SalaryRecord<br/>状态=pending"]
CreateRecord --> End(["结束"])
ReturnNone --> End
```
**图表来源**
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L71-L74)
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L127-L190)
**章节来源**
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L71-L74)
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L85-L91)
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L127-L190)
### 时间周期与状态管理
- 时间周期
- 由period_year与period_month共同构成，用于唯一标识某员工的某月工资记录
- 数据库层面在salary_records上建立了复合索引(idx_salary_period)，提升查询效率
- 状态管理
- 待处理：pending（默认状态）
- 已确认：confirmed（管理员/经理确认后变更）
- 已发放：paid（当前服务层未实现，但模型预留字段）
- 状态变更流程
- 单条确认：调用确认接口，仅当状态为pending时允许变更
- 批量确认：按年月筛选pending状态记录，可选择按科室过滤
```mermaid
stateDiagram-v2
[*] --> 待处理
待处理 --> 已确认 : "确认工资"
已确认 --> 已发放 : "发放工资"
已发放 --> [*]
```
**图表来源**
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L222-L231)
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L234-L259)
**章节来源**
- [backend/app/models/models.py](file://backend/app/models/models.py#L218-L219)
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L222-L231)
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L234-L259)
### 与员工的多对一关系与历史版本控制
- 多对一关系
- SalaryRecord.staff_id -> Staff.id，每个工资记录对应唯一员工
- Staff.salary_records反向关系，支持按员工查询其历史工资记录
- 历史版本控制
- 当前版本未实现SalaryRecord的版本号字段；如需版本控制，可在模型中增加version字段并在更新时递增
- 绩效计划的版本控制已在其他模型中实现（PerformancePlan.version），可借鉴其模式
**章节来源**
- [backend/app/models/models.py](file://backend/app/models/models.py#L108-L110)
- [backend/app/models/models.py](file://backend/app/models/models.py#L205-L231)
- [backend/app/models/models.py](file://backend/app/models/models.py#L293-L293)
### 批量核算的性能优化
- 批量生成
- 服务层先查询指定科室下所有已确认的考核记录，再逐条生成工资记录
- 建议在大规模数据场景下：
- 使用分批处理（分页查询考核记录）
- 异步并发插入（注意数据库连接池与事务边界）
- 增加数据库索引覆盖查询条件
- 批量确认
- 通过SQL查询一次性筛选出待确认记录，减少多次往返
- 支持按科室过滤，缩小确认范围
**章节来源**
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L192-L219)
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L234-L259)
### 扣款与补贴的设置规则
- 扣款与补贴均为数值型字段，支持在创建或更新时设置
- 服务层在创建与更新时均会重新计算应发工资：total_salary = base_salary + performance_bonus + allowance - deduction
- 建议在业务层增加校验规则：
- 扣款与补贴必须非负
- 应发工资计算后可进行合理性校验（如不得为负）
**章节来源**
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L85-L91)
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L114-L120)
### 绩效奖金与绩效得分的关系
- 绩效奖金 = 绩效基数 × (绩效得分/100) × 绩效系数
- 绩效得分来自Assessment.weighted_score，状态必须为"finalized"
- 绩效系数来自Staff.performance_ratio，不同岗位/级别可设置不同系数
**章节来源**
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L71-L74)
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L143-L153)
### API与前端交互
- API接口
- 列表查询：支持按员工、科室、年份、月份、状态筛选
- 详情查询：返回带员工与科室名称的完整信息
- 创建/更新：仅允许在待处理状态下更新
- 按考核生成：基于已确认考核自动生成工资记录
- 批量生成/确认：支持按科室批量生成与批量确认
- 前端展示
- 列表显示基本工资、绩效得分、绩效奖金、补贴、扣款、应发工资等字段
- 提供编辑弹窗，支持更新扣款、补贴、备注等
**章节来源**
- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L20-L156)
- [frontend/src/views/salary/Salary.vue](file://frontend/src/views/salary/Salary.vue#L33-L245)
- [frontend/src/api/salary.js](file://frontend/src/api/salary.js#L1-L42)
## 依赖分析
- 模型依赖
- SalaryRecord依赖Staff（外键）
- Assessment与SalaryRecord通过staff_id间接关联
- 服务层依赖
- 依赖Staff、Assessment模型进行数据查询与计算
- 依赖Pydantic模式进行请求/响应数据校验
- API层依赖
- 依赖Security中间件进行权限控制（管理员/经理）
- 依赖数据库会话进行异步操作
```mermaid
graph LR
SalaryRecord["SalaryRecord模型"] --> Staff["Staff模型"]
SalaryService["SalaryService"] --> SalaryRecord
SalaryService --> Staff
SalaryService --> Assessment["Assessment模型"]
API["salary.py"] --> SalaryService
API --> Schema["schemas.py"]
```
**图表来源**
- [backend/app/models/models.py](file://backend/app/models/models.py#L205-L231)
- [backend/app/models/models.py](file://backend/app/models/models.py#L88-L115)
- [backend/app/models/models.py](file://backend/app/models/models.py#L149-L179)
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L10-L11)
- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L14-L15)
**章节来源**
- [backend/app/models/models.py](file://backend/app/models/models.py#L205-L231)
- [backend/app/models/models.py](file://backend/app/models/models.py#L88-L115)
- [backend/app/models/models.py](file://backend/app/models/models.py#L149-L179)
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L10-L11)
- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L14-L15)
## 性能考虑
- 查询优化
- salary_records表已建立索引：staff_id、(period_year, period_month)
- API层使用selectinload预加载关联对象，避免N+1查询
- 批量处理
- 批量生成与确认采用SQL查询一次性筛选，减少循环调用
- 建议在高并发场景下增加数据库连接池配置与事务隔离级别
- 数据类型
- 使用Numeric类型保证金额精度，避免浮点误差累积
[本节为通用性能建议，无需特定文件来源]
## 故障排除指南
- 无法生成工资
- 检查是否存在已确认的考核记录且状态为"finalized"
- 检查是否已存在同周期的工资记录（防止重复生成）
- 无法确认工资
- 确认记录状态必须为"pending"
- 检查权限：仅管理员或经理可执行确认操作
- 数据不一致
- 更新扣款/补贴后需重新计算应发工资
- 核对数据库索引是否生效，避免查询性能问题
**章节来源**
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L155-L164)
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L224-L226)
- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L132-L142)
## 结论
SalaryRecord模型通过清晰的字段设计与严格的计算逻辑，实现了从考核到工资的自动化流转。服务层提供了完善的生成、确认与批量处理能力，并通过索引与预加载优化了查询性能。未来可在版本控制、状态扩展（如已发放）与更细粒度的扣款/补贴规则方面进一步增强。
[本节为总结性内容，无需特定文件来源]
## 附录
### 工资计算示例
- 输入
- 员工：基本工资=10000，绩效系数=1.2
- 考核：加权得分=95
- 扣款=0，补贴=500
- 计算过程
- 绩效奖金 = 固定基数 × (95/100) × 1.2
- 应发工资 = 10000 + 绩效奖金 + 500 - 0
- 输出
- 工资记录状态=pending，等待确认
**章节来源**
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L71-L74)
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L172-L173)
### 数据准确性验证方法
- 金额精度：使用Numeric类型，避免浮点误差
- 业务规则：在服务层增加校验（扣款/补贴非负、应发工资合理）
- 索引验证：确认salary_records索引生效，提升查询性能
- 测试覆盖：编写单元测试验证计算逻辑与状态变更流程
**章节来源**
- [backend/alembic/versions/001_initial.py](file://backend/alembic/versions/001_initial.py#L133-L154)
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L85-L91)

545
.qoder/repowiki/zh/content/数据模型详解/核心数据模型/核心数据模型.md Normal file
View File

@@ -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)

453
.qoder/repowiki/zh/content/数据模型详解/核心数据模型/科室信息模型.md Normal file
View File

@@ -0,0 +1,453 @@
# 科室信息模型
<cite>
**本文引用的文件**
- [models.py](file://backend/app/models/models.py)
- [schemas.py](file://backend/app/schemas/schemas.py)
- [departments.py](file://backend/app/api/v1/departments.py)
- [department_service.py](file://backend/app/services/department_service.py)
- [Departments.vue](file://frontend/src/views/basic/Departments.vue)
- [department.js](file://frontend/src/api/department.js)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概览](#架构概览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考量](#性能考量)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
本文档系统化阐述“科室信息模型”的设计理念与实现细节，围绕 Department 模型展开，涵盖：
- 科室类型枚举（DeptType）及其业务分类
- 树形层级结构与父子关系设计
- 字段语义、数据类型、约束条件与业务规则
- 科室编码唯一性、层级计算逻辑、排序机制与状态管理
- 科室类型分类的应用场景与最佳实践
- 数据操作示例、层级查询方法与常见问题排查
## 项目结构
后端采用分层架构：API 层负责请求处理与鉴权，Service 层封装业务逻辑，Model 层定义数据模型与数据库映射；前端通过 API 模块调用后端接口，实现科室数据的增删改查与树形展示。
```mermaid
graph TB
subgraph "前端"
FE_Dialog["Departments.vue<br/>新增/编辑/删除/树形选择"]
FE_API["department.js<br/>HTTP 请求封装"]
end
subgraph "后端"
API["departments.py<br/>FastAPI 路由"]
SVC["department_service.py<br/>业务逻辑"]
MODEL["models.py<br/>Department 模型与 DeptType 枚举"]
end
FE_Dialog --> FE_API
FE_API --> API
API --> SVC
SVC --> MODEL
```
图表来源
- [departments.py](file://backend/app/api/v1/departments.py#L1-L108)
- [department_service.py](file://backend/app/services/department_service.py#L1-L150)
- [models.py](file://backend/app/models/models.py#L62-L85)
- [Departments.vue](file://frontend/src/views/basic/Departments.vue#L103-L272)
- [department.js](file://frontend/src/api/department.js#L1-L32)
章节来源
- [models.py](file://backend/app/models/models.py#L62-L85)
- [schemas.py](file://backend/app/schemas/schemas.py#L64-L103)
- [departments.py](file://backend/app/api/v1/departments.py#L1-L108)
- [department_service.py](file://backend/app/services/department_service.py#L1-L150)
- [Departments.vue](file://frontend/src/views/basic/Departments.vue#L1-L290)
- [department.js](file://frontend/src/api/department.js#L1-L32)
## 核心组件
- Department 模型：定义科室实体的字段、索引与关系
- DeptType 枚举：标准化科室类型，支持多类业务场景
- DepartmentService：封装 CRUD、层级树构建与校验逻辑
- FastAPI 路由：提供列表、树形、详情、创建、更新、删除等接口
- 前端视图与 API：提供交互界面与 HTTP 请求封装
章节来源
- [models.py](file://backend/app/models/models.py#L16-L26)
- [models.py](file://backend/app/models/models.py#L62-L85)
- [department_service.py](file://backend/app/services/department_service.py#L13-L149)
- [departments.py](file://backend/app/api/v1/departments.py#L20-L107)
- [schemas.py](file://backend/app/schemas/schemas.py#L64-L103)
- [Departments.vue](file://frontend/src/views/basic/Departments.vue#L103-L272)
- [department.js](file://frontend/src/api/department.js#L1-L32)
## 架构概览
后端采用 ORM 映射，Department 通过外键维护自引用的父子关系；Service 层在创建时自动计算层级，API 层提供树形结构查询与分页列表查询。
```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
+parent : Department?
+children : Department[]
+staff : Staff[]
}
class DepartmentService {
+get_list(...)
+get_by_id(...)
+get_by_code(...)
+create(...)
+update(...)
+delete(...)
+get_tree(...)
}
class DeptType {
<<enumeration>>
+CLINICAL_SURGICAL
+CLINICAL_NONSURGICAL_WARD
+CLINICAL_NONSURGICAL_NOWARD
+MEDICAL_TECH
+MEDICAL_AUXILIARY
+NURSING
+ADMIN
+FINANCE
+LOGISTICS
}
DepartmentService --> Department : "操作"
Department --> DeptType : "使用"
Department --> Department : "自引用父子关系"
```
图表来源
- [models.py](file://backend/app/models/models.py#L16-L26)
- [models.py](file://backend/app/models/models.py#L62-L85)
- [department_service.py](file://backend/app/services/department_service.py#L13-L149)
## 详细组件分析
### Department 模型与字段规范
- 主键与标识
- id：整型，自增主键
- code：字符串，长度限制，唯一约束，用于业务识别与去重
- 基础信息
- name：字符串，长度限制，必填
- description：文本，可空
- 组织结构
- parent_id：外键指向同表 id，支持树形层级
- level：整型，默认 1，表示层级深度
- sort_order：整型，默认 0，用于排序
- 类型与状态
- dept_type：枚举 DeptType，必填
- is_active：布尔，默认启用
- 时间戳
- created_at、updated_at：自动维护
- 索引与关系
- 索引：按类型、父节点
- 关系：parent（反向 children）、staff（一对多）
字段约束与业务规则
- 唯一性：code 唯一，API 层在创建前进行重复校验
- 层级计算：创建时若指定 parent_id，则 level = 父级 level + 1；否则默认 1
- 排序：列表与树形查询均按 sort_order 与 id 排序
- 状态：is_active 控制启用/停用，影响列表过滤与前端显示
- 父子关系：支持任意层级的树形组织，删除时需确保无子节点
章节来源
- [models.py](file://backend/app/models/models.py#L62-L85)
- [department_service.py](file://backend/app/services/department_service.py#L62-L78)
- [departments.py](file://backend/app/api/v1/departments.py#L74-L77)
### 科室类型枚举（DeptType）
- 分类与含义
- 手术临床：clinical_surgical
- 非手术有病房：clinical_nonsurgical_ward
- 非手术无病房：clinical_nonsurgical_noward
- 医技：medical_tech
- 医辅：medical_auxiliary
- 护理：nursing
- 行政：admin
- 财务：finance
- 后勤：logistics
- 应用场景
- 指标模板匹配：不同类型科室适用不同指标集合
- 权限与菜单：类型决定可访问的功能范围
- 报表与统计：按类型聚合绩效、财务等数据
- 计划与考核：类型驱动 KPI 设定与权重分配
章节来源
- [models.py](file://backend/app/models/models.py#L16-L26)
- [schemas.py](file://backend/app/schemas/schemas.py#L12-L21)
### 树形层级结构与父子关系
- 自引用关系
- Department.parent_id 外键指向 Department.id
- 通过 relationship 建立 parent 与 children 的双向关系
- 层级计算
- 创建时根据 parent_id 查询父级 level 并 +1
- 支持多级嵌套，level 从 1 开始
- 树形构建
- Service 层一次性查询所有科室，按 sort_order 与 id 排序
- 使用字典映射与父子映射构建树根集
- 避免懒加载导致的循环依赖与性能问题
```mermaid
flowchart TD
Start(["开始"]) --> LoadDepts["查询所有科室<br/>按 sort_order,id 排序"]
LoadDepts --> BuildMap["构建 id->节点 映射"]
BuildMap --> Iterate["遍历科室列表"]
Iterate --> HasParent{"存在 parent_id 且父节点在映射中?"}
HasParent --> |是| AppendChild["将当前节点加入父节点 children"]
HasParent --> |否| AddRoot["加入根节点集"]
AppendChild --> Next["下一个科室"]
AddRoot --> Next
Next --> Done(["返回根节点树"])
```
图表来源
- [department_service.py](file://backend/app/services/department_service.py#L113-L149)
章节来源
- [models.py](file://backend/app/models/models.py#L78-L80)
- [department_service.py](file://backend/app/services/department_service.py#L113-L149)
### 数据操作流程与最佳实践
#### 列表查询
- 参数：dept_type（可选）、is_active（可选）、page、page_size
- 排序：sort_order → id
- 返回：分页结果与总数
```mermaid
sequenceDiagram
participant FE as "前端"
participant API as "departments.py"
participant SVC as "department_service.py"
participant DB as "数据库"
FE->>API : GET /departments?page=&page_size=&dept_type=&is_active=
API->>SVC : get_list(dept_type,is_active,page,page_size)
SVC->>DB : select(department) + where + order_by + limit/offset
DB-->>SVC : 列表数据
SVC->>DB : count(*) 子查询
DB-->>SVC : 总数
SVC-->>API : (列表,总数)
API-->>FE : JSON 响应
```
图表来源
- [departments.py](file://backend/app/api/v1/departments.py#L20-L40)
- [department_service.py](file://backend/app/services/department_service.py#L17-L43)
章节来源
- [departments.py](file://backend/app/api/v1/departments.py#L20-L40)
- [department_service.py](file://backend/app/services/department_service.py#L17-L43)
#### 树形查询
- 参数：dept_type（可选）
- 排序：sort_order → id
- 返回：根节点树，支持前端树形选择器
```mermaid
sequenceDiagram
participant FE as "前端"
participant API as "departments.py"
participant SVC as "department_service.py"
participant DB as "数据库"
FE->>API : GET /departments/tree?dept_type=
API->>SVC : get_tree(dept_type)
SVC->>DB : select(department) + order_by(sort_order,id)
DB-->>SVC : 所有科室
SVC->>SVC : 构建 id->节点 映射
SVC->>SVC : 追加到父节点 children 或根集
SVC-->>API : 根节点树
API-->>FE : JSON 响应
```
图表来源
- [departments.py](file://backend/app/api/v1/departments.py#L43-L51)
- [department_service.py](file://backend/app/services/department_service.py#L113-L149)
章节来源
- [departments.py](file://backend/app/api/v1/departments.py#L43-L51)
- [department_service.py](file://backend/app/services/department_service.py#L113-L149)
#### 创建科室
- 前端校验：必填项（编码、名称、类型）
- 服务端校验：编码唯一性
- 层级计算：若 parent_id 存在则 level = 父级 level + 1
- 返回：完整 Department 对象
```mermaid
sequenceDiagram
participant FE as "前端"
participant API as "departments.py"
participant SVC as "department_service.py"
participant DB as "数据库"
FE->>API : POST /departments
API->>SVC : get_by_code(code)
SVC->>DB : select(code)
DB-->>SVC : 结果
SVC-->>API : 若存在则抛错
API->>SVC : create(dept_data)
SVC->>SVC : 计算 level(parent.level+1)
SVC->>DB : insert(department)
DB-->>SVC : 新记录
SVC-->>API : 返回新建对象
API-->>FE : JSON 响应
```
图表来源
- [departments.py](file://backend/app/api/v1/departments.py#L67-L80)
- [department_service.py](file://backend/app/services/department_service.py#L62-L78)
章节来源
- [departments.py](file://backend/app/api/v1/departments.py#L67-L80)
- [department_service.py](file://backend/app/services/department_service.py#L62-L78)
#### 更新与删除
- 更新：支持修改名称、类型、父级、排序、状态、描述
- 删除：若存在子节点则拒绝删除，避免破坏树形结构
```mermaid
flowchart TD
UStart(["更新入口"]) --> GetByID["根据 id 查询科室"]
GetByID --> Exists{"是否存在?"}
Exists --> |否| NotFound["返回 404"]
Exists --> |是| Apply["应用变更字段"]
Apply --> Flush["flush/refresh"]
Flush --> UEnd(["结束"])
DStart(["删除入口"]) --> DGet["根据 id 查询科室"]
DGet --> DExists{"是否存在?"}
DExists --> |否| DNotFound["返回 404"]
DExists --> |是| CheckChildren["检查是否存在子节点"]
CheckChildren --> HasChild{"有子节点?"}
HasChild --> |是| Block["返回错误(不可删除)"]
HasChild --> |否| Delete["删除并返回成功"]
Delete --> DEnd(["结束"])
```
图表来源
- [department_service.py](file://backend/app/services/department_service.py#L80-L110)
章节来源
- [department_service.py](file://backend/app/services/department_service.py#L80-L110)
- [departments.py](file://backend/app/api/v1/departments.py#L83-L107)
### 前端集成与使用示例
- 列表页面：支持按关键字（名称/编码）、类型筛选，分页展示
- 树形选择：上级科室使用树形选择器，便于层级配置
- 新增/编辑：表单校验必填字段，提交后刷新列表与树
- 删除：二次确认，防止误删
章节来源
- [Departments.vue](file://frontend/src/views/basic/Departments.vue#L103-L272)
- [department.js](file://frontend/src/api/department.js#L1-L32)
## 依赖关系分析
- 模型层依赖数据库引擎与枚举类型，定义了 Department 的结构与约束
- 服务层依赖模型层，提供业务逻辑与数据处理
- API 层依赖服务层与安全中间件，提供对外接口
- 前端依赖 API 封装，调用后端接口完成用户交互
```mermaid
graph LR
FE["前端 Views/API"] --> API["FastAPI 路由"]
API --> SVC["Service 业务层"]
SVC --> MODEL["ORM 模型层"]
MODEL --> DB["数据库"]
```
图表来源
- [models.py](file://backend/app/models/models.py#L62-L85)
- [department_service.py](file://backend/app/services/department_service.py#L13-L149)
- [departments.py](file://backend/app/api/v1/departments.py#L1-L108)
- [Departments.vue](file://frontend/src/views/basic/Departments.vue#L103-L272)
- [department.js](file://frontend/src/api/department.js#L1-L32)
## 性能考量
- 查询优化
- 列表与树形查询均按 sort_order 与 id 排序，保证稳定顺序
- 服务层一次性加载所有科室，避免 N+1 查询
- 索引策略
- 按类型与父节点建立索引，提升过滤与层级查询效率
- 缓存建议
- 树形结构可考虑缓存热点数据，减少重复构建
- 分页与并发
- 列表查询支持分页，避免一次性加载过多数据
- 删除前检查子节点，避免事务回滚与锁竞争
## 故障排除指南
- 创建失败：编码重复
- 现象：创建接口返回错误
- 处理：检查是否存在相同编码，修改后重试
- 删除失败：存在子节点
- 现象：删除接口返回错误
- 处理：先删除子节点或调整层级后再删除
- 树形不正确：层级或排序异常
- 现象：树形选择器显示层级混乱
- 处理：检查 parent_id 与 sort_order 设置，重新保存
- 前端显示异常：类型标签或状态开关无效
- 现象：类型标签颜色/文案不一致，状态切换无效
- 处理：确认枚举值与前端映射一致，检查事件绑定
章节来源
- [departments.py](file://backend/app/api/v1/departments.py#L74-L77)
- [department_service.py](file://backend/app/services/department_service.py#L102-L107)
- [Departments.vue](file://frontend/src/views/basic/Departments.vue#L143-L161)
## 结论
Department 模型通过清晰的字段设计、严格的约束与完善的层级计算，为医院绩效系统的组织管理提供了可靠的数据基础。结合 DeptType 的分类与树形结构，能够灵活支撑各类科室的差异化需求，并通过前后端协同实现高效、稳定的科室信息管理。
## 附录
### 字段与约束对照表
- 字段名：name
- 类型：字符串
- 约束：必填，长度 ≤ 100
- 用途：显示与检索
- 字段名：code
- 类型：字符串
- 约束：必填，唯一，长度 ≤ 20
- 用途：业务识别与去重
- 字段名：dept_type
- 类型：枚举
- 约束：必填
- 用途：类型分类与模板匹配
- 字段名：parent_id
- 类型：整型
- 约束：可空，外键指向自身 id
- 用途：树形层级
- 字段名：level
- 类型：整型
- 约束：默认 1，创建时根据父级 +1
- 用途：层级深度
- 字段名：sort_order
- 类型：整型
- 约束：默认 0
- 用途：排序与展示顺序
- 字段名：is_active
- 类型：布尔
- 约束：默认启用
- 用途：启用/停用控制
- 字段名：description
- 类型：文本
- 约束：可空
- 用途：补充说明
- 字段名：created_at/updated_at
- 类型：时间戳
- 约束：自动维护
- 用途：审计与追踪
章节来源
- [models.py](file://backend/app/models/models.py#L66-L76)
- [schemas.py](file://backend/app/schemas/schemas.py#L64-L72)

452
.qoder/repowiki/zh/content/数据模型详解/核心数据模型/系统基础模型.md Normal file
View File

@@ -0,0 +1,452 @@
# 系统基础模型
<cite>
**本文引用的文件**
- [backend/app/models/models.py](file://backend/app/models/models.py)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py)
- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py)
- [backend/app/api/v1/menus.py](file://backend/app/api/v1/menus.py)
- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py)
- [backend/app/services/menu_service.py](file://backend/app/services/menu_service.py)
- [backend/app/services/template_service.py](file://backend/app/services/template_service.py)
- [backend/app/core/security.py](file://backend/app/core/security.py)
- [backend/app/core/config.py](file://backend/app/core/config.py)
- [backend/app/main.py](file://backend/app/main.py)
- [docs/详细设计.md](file://docs/详细设计.md)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
本文件聚焦系统基础模型，围绕以下核心实体展开：用户（User）、菜单（Menu）、指标模板（IndicatorTemplate）、模板指标（TemplateIndicator）。文档将深入解释这些模型的设计理念、实现细节与相互关系，涵盖用户认证与授权、菜单权限管理、指标模板系统、模板与指标的关联关系、用户角色管理、菜单层级结构、模板类型分类、模板指标权重与排序机制、用户与员工的关联关系、菜单父子层级、模板激活状态管理等主题。同时提供系统配置示例、权限控制机制与模板管理最佳实践。
## 项目结构
后端采用 FastAPI + SQLAlchemy 2.0 异步 ORM 的分层架构：
- models 层：定义数据库模型与枚举类型
- schemas 层：定义 Pydantic 数据模式（输入/输出）
- api 层：定义路由与权限依赖
- services 层：封装业务逻辑
- core 层：安全、配置、数据库连接等基础设施
- main：应用入口与中间件注册
```mermaid
graph TB
subgraph "应用层"
API_AUTH["API: /api/v1/auth"]
API_MENUS["API: /api/v1/menus"]
API_TEMPLATES["API: /api/v1/templates"]
end
subgraph "服务层"
S_AUTH["Security 模块"]
S_MENU["MenuService"]
S_TEMPLATE["TemplateService"]
end
subgraph "模型层"
M_USER["User"]
M_MENU["Menu"]
M_INDICATOR["Indicator"]
M_TEMPLATE["IndicatorTemplate"]
M_TINDICATOR["TemplateIndicator"]
end
API_AUTH --> S_AUTH
API_MENUS --> S_MENU
API_TEMPLATES --> S_TEMPLATE
S_AUTH --> M_USER
S_MENU --> M_MENU
S_TEMPLATE --> M_TEMPLATE
S_TEMPLATE --> M_TINDICATOR
S_TEMPLATE --> M_INDICATOR
```
图表来源
- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L1-L74)
- [backend/app/api/v1/menus.py](file://backend/app/api/v1/menus.py#L1-L164)
- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L1-L272)
- [backend/app/services/menu_service.py](file://backend/app/services/menu_service.py#L1-L137)
- [backend/app/services/template_service.py](file://backend/app/services/template_service.py#L1-L293)
- [backend/app/models/models.py](file://backend/app/models/models.py#L244-L438)
章节来源
- [backend/app/main.py](file://backend/app/main.py#L1-L92)
- [backend/app/core/config.py](file://backend/app/core/config.py#L1-L47)
## 核心组件
本节对 User、Menu、IndicatorTemplate、TemplateIndicator 四个核心模型进行系统性解析，包括字段含义、约束、关系与索引策略。
- User（系统用户）
- 关键点：用户名唯一、密码哈希存储、关联员工（可选）、角色（字符串）、启用状态、最后登录时间
- 关系：与 Staff 为一对一（外键关联）
- 权限：通过角色字段区分 admin/manager/staff；安全中间件提供获取当前用户、激活用户、管理员/经理权限校验
- Menu（系统菜单）
- 关键点：父子自引用（parent_id → menus.id）、菜单类型（菜单/按钮）、排序、可见性、启用状态
- 关系：自关联 parent/children；支持树形结构查询
- 权限：菜单权限标识（permission）用于前端路由鉴权
- IndicatorTemplate（指标模板）
- 关键点：模板类型（TemplateType）、维度权重（JSON 字符串）、考核周期、启用状态
- 关系：一对多到 TemplateIndicator
- TemplateIndicator（模板指标）
- 关键点：与 Indicator 多对一、分类（category）、目标值/单位、权重、评分方法/参数、排序、备注
- 关系：与 Indicator 一对一（反向为多对一）
章节来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L244-L438)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L313-L346)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L582-L639)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L698-L743)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L654-L696)
## 架构总览
系统采用前后端分离，后端提供 REST API，前端通过权限标识与菜单树渲染导航。认证采用 JWT，菜单树仅返回可见且启用项，模板管理支持按类型与启用状态筛选。
```mermaid
sequenceDiagram
participant FE as "前端"
participant API as "API 路由"
participant SEC as "安全模块"
participant SVC as "服务层"
participant DB as "数据库"
FE->>API : 登录请求
API->>SEC : 校验用户名/密码
SEC->>DB : 查询用户
DB-->>SEC : 用户记录
SEC-->>API : 生成访问令牌
API-->>FE : 返回令牌
FE->>API : 获取菜单树
API->>SEC : 获取当前激活用户
SEC-->>API : 当前用户
API->>SVC : 查询菜单树
SVC->>DB : 查询根菜单可见且启用
DB-->>SVC : 菜单集合
SVC-->>API : 菜单树
API-->>FE : 返回菜单树
```
图表来源
- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L17-L38)
- [backend/app/api/v1/menus.py](file://backend/app/api/v1/menus.py#L17-L29)
- [backend/app/services/menu_service.py](file://backend/app/services/menu_service.py#L16-L29)
- [backend/app/core/security.py](file://backend/app/core/security.py#L55-L91)
## 详细组件分析
### 用户与认证授权
- 认证流程
- 登录：OAuth2Password 请求表单，校验密码哈希，检查用户启用状态，签发访问令牌
- 注册：检查用户名唯一性，生成密码哈希，创建用户记录
- 当前用户：从 JWT 提取用户 ID，查询用户并校验启用状态
- 权限：管理员（admin）与经理（manager）具备更高操作权限
- 角色与权限
- User.role 控制资源访问范围
- 路由层通过依赖注入校验当前用户角色与状态
```mermaid
sequenceDiagram
participant Client as "客户端"
participant AuthAPI as "Auth API"
participant Security as "Security"
participant DB as "数据库"
Client->>AuthAPI : POST /api/v1/auth/login
AuthAPI->>DB : 查询用户
DB-->>AuthAPI : 用户(含密码哈希)
AuthAPI->>Security : 验证密码
Security-->>AuthAPI : 校验结果
AuthAPI->>Security : 生成访问令牌
AuthAPI-->>Client : {access_token, token_type}
Client->>AuthAPI : GET /api/v1/auth/me
AuthAPI->>Security : 获取当前激活用户
Security->>DB : 查询用户
DB-->>Security : 用户
Security-->>AuthAPI : 当前用户
AuthAPI-->>Client : 用户信息
```
图表来源
- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L17-L74)
- [backend/app/core/security.py](file://backend/app/core/security.py#L24-L91)
章节来源
- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L1-L74)
- [backend/app/core/security.py](file://backend/app/core/security.py#L1-L110)
### 菜单与权限管理
- 菜单模型
- 支持菜单/按钮两类，父子自引用，排序与可见性控制
- 菜单树查询：仅返回顶层、可见且启用的菜单，并递归加载子节点
- 权限控制
- 菜单权限标识（permission）用于前端路由鉴权
- 菜单管理 API 通过角色依赖限制创建/更新/删除操作
- 初始化
- 支持初始化默认菜单，避免重复初始化
```mermaid
flowchart TD
Start(["获取菜单树"]) --> BuildQuery["构建查询: 顶层菜单<br/>可见且启用"]
BuildQuery --> LoadChildren["加载子节点关系"]
LoadChildren --> OrderBy["按排序与ID排序"]
OrderBy --> ToDict["_menu_to_dict 递归转字典"]
ToDict --> End(["返回菜单树"])
```
图表来源
- [backend/app/services/menu_service.py](file://backend/app/services/menu_service.py#L16-L29)
- [backend/app/services/menu_service.py](file://backend/app/services/menu_service.py#L101-L109)
章节来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L347-L373)
- [backend/app/api/v1/menus.py](file://backend/app/api/v1/menus.py#L1-L164)
- [backend/app/services/menu_service.py](file://backend/app/services/menu_service.py#L1-L137)
### 指标模板系统
- 模板类型
- 通用模板、手术临床、非手术有病房、非手术无病房、医技、护理、行政、后勤
- 维度权重
- 模板可配置 BSC 四维度权重（JSON 字符串），用于汇总计算
- 考核周期
- 支持月度/年度等周期配置
- 列表与详情
- 支持按类型与启用状态筛选，返回模板指标数量
- 详情包含模板基本信息与完整指标列表（含指标名称、编码、类型、维度、权重、排序等）
```mermaid
classDiagram
class IndicatorTemplate {
+template_name
+template_code
+template_type
+dimension_weights
+assessment_cycle
+is_active
+indicators[]
}
class TemplateIndicator {
+indicator_id
+category
+target_value
+target_unit
+weight
+scoring_method
+scoring_params
+sort_order
+remark
+indicator
}
class Indicator {
+name
+code
+indicator_type
+bs_dimension
+weight
+max_score
}
IndicatorTemplate "1" --> "many" TemplateIndicator : "包含"
TemplateIndicator "many" --> "1" Indicator : "关联"
```
图表来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L387-L438)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L698-L743)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L654-L696)
章节来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L375-L438)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L640-L743)
- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L1-L272)
- [backend/app/services/template_service.py](file://backend/app/services/template_service.py#L1-L293)
### 模板与指标的关联关系
- 关联表 TemplateIndicator
- 唯一约束：同一模板下指标唯一
- 排序字段 sort_order 决定展示顺序
- 支持批量添加，自动补齐排序
- 权重与排序机制
- 模板层与指标层均支持权重配置
- 汇总时需遵循维度权重与指标权重的乘积规则（由上层业务逻辑决定）
- 激活状态管理
- 模板与指标均可启用/停用，影响使用范围与计算
章节来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L411-L438)
- [backend/app/services/template_service.py](file://backend/app/services/template_service.py#L160-L207)
### 用户与员工的关联关系
- User 与 Staff
- User.staff_id 外键关联 Staff.id，表示系统用户与员工的绑定关系
- 便于登录后获取员工信息与权限边界
- 员工状态与部门
- Staff.status 与 Department.parent_id/level 等字段共同构成组织与人员管理基础
章节来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L88-L114)
- [backend/app/models/models.py](file://backend/app/models/models.py#L244-L261)
### 菜单层级结构
- 自引用关系
- Menu.parent_id → Menu.id，支持任意层级
- 服务层通过 selectinload 预加载 children，避免 N+1 查询
- 树形渲染
- 顶层查询（parent_id IS NULL），按 sort_order 与 id 排序
- 递归转换为字典树，供前端渲染
章节来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L347-L373)
- [backend/app/services/menu_service.py](file://backend/app/services/menu_service.py#L16-L29)
### 模板类型分类逻辑
- TemplateType 枚举覆盖全院主要科室类型，便于按类型匹配模板
- 服务层提供类型标签映射，便于前端展示
章节来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L375-L385)
- [backend/app/services/template_service.py](file://backend/app/services/template_service.py#L270-L283)
### 权重与排序机制
- 指标层权重
- Indicator.weight 与 TemplateIndicator.weight 双层权重
- 数据库层对指标权重设置正数约束
- 排序
- TemplateIndicator.sort_order 决定模板内指标顺序
- 批量添加时可按传入顺序补齐排序
章节来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L124-L146)
- [backend/app/models/models.py](file://backend/app/models/models.py#L421-L427)
- [backend/app/services/template_service.py](file://backend/app/services/template_service.py#L256-L267)
### 激活状态管理
- 模板与菜单均提供 is_active 字段
- 菜单树查询默认仅返回启用项
- 模板列表支持按 is_active 过滤
章节来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L398-L398)
- [backend/app/models/models.py](file://backend/app/models/models.py#L360-L360)
- [backend/app/services/menu_service.py](file://backend/app/services/menu_service.py#L16-L21)
- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L22-L42)
## 依赖分析
- 模型依赖
- User ←→ Staff（一对一外键）
- Menu ←→ Menu（自引用）
- IndicatorTemplate → TemplateIndicator → Indicator（多对一）
- 服务依赖
- MenuService 依赖 Menu 模型
- TemplateService 依赖 IndicatorTemplate、TemplateIndicator、Indicator 模型
- API 依赖
- auth 路由依赖 Security 与 User 模型
- menus 路由依赖 MenuService 与 Menu 模型
- templates 路由依赖 TemplateService 与模板相关 Schema
```mermaid
graph LR
A["User"] <- --> B["Staff"]
C["Menu"] --自引用 --> C
D["IndicatorTemplate"] --> E["TemplateIndicator"]
E --> F["Indicator"]
G["MenuService"] --> C
H["TemplateService"] --> D
H --> E
H --> F
I["Auth API"] --> G
J["Menus API"] --> G
K["Templates API"] --> H
```
图表来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L88-L438)
- [backend/app/services/menu_service.py](file://backend/app/services/menu_service.py#L1-L137)
- [backend/app/services/template_service.py](file://backend/app/services/template_service.py#L1-L293)
- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L1-L74)
- [backend/app/api/v1/menus.py](file://backend/app/api/v1/menus.py#L1-L164)
- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L1-L272)
## 性能考虑
- 查询优化
- 使用 selectinload 预加载关系，减少 N+1 查询
- 菜单树查询限定顶层、可见与启用条件
- 索引策略
- 模型层为常用过滤字段建立索引（如模板类型、菜单可见性、指标权重约束）
- 分页与排序
- 模板列表支持分页与排序，避免一次性加载过多数据
- 缓存与并发
- 配置层提供数据库连接池参数，建议在生产环境按负载调优
章节来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L82-L85)
- [backend/app/models/models.py](file://backend/app/models/models.py#L368-L372)
- [backend/app/models/models.py](file://backend/app/models/models.py#L143-L146)
- [backend/app/services/menu_service.py](file://backend/app/services/menu_service.py#L16-L29)
- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L22-L42)
- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L22)
## 故障排查指南
- 登录失败
- 检查用户名是否存在、密码是否正确、用户是否启用
- 查看安全模块的凭据验证与令牌生成流程
- 菜单不可见
- 确认菜单 is_visible 与 is_active 状态
- 检查菜单树查询是否仅返回可见启用项
- 模板操作失败
- 检查模板编码唯一性、模板与指标是否存在、唯一约束冲突
- 确认排序字段是否正确传递
- 权限不足
- 确认当前用户角色（admin/manager/staff）
- 检查路由依赖是否正确应用
章节来源
- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L17-L38)
- [backend/app/services/menu_service.py](file://backend/app/services/menu_service.py#L86-L98)
- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L136-L140)
- [backend/app/services/template_service.py](file://backend/app/services/template_service.py#L167-L182)
- [backend/app/core/security.py](file://backend/app/core/security.py#L94-L109)
## 结论
本系统基础模型围绕 User、Menu、IndicatorTemplate、TemplateIndicator 构建，通过清晰的枚举与约束、合理的索引与查询策略、严格的权限控制与安全中间件，实现了用户认证授权、菜单权限管理、指标模板体系与模板-指标关联的完整闭环。模板类型覆盖全院主要科室，权重与排序机制满足多维度汇总需求，激活状态管理确保系统灵活性。配合服务层与 API 层的职责分离，系统具备良好的扩展性与可维护性。
## 附录
### 系统配置示例
- JWT 配置
- SECRET_KEY、ALGORITHM、ACCESS_TOKEN_EXPIRE_MINUTES
- 数据库连接
- DATABASE_URL、DATABASE_POOL_SIZE、DATABASE_MAX_OVERFLOW
- 跨域与分页
- CORS_ORIGINS、DEFAULT_PAGE_SIZE、MAX_PAGE_SIZE
章节来源
- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L47)
### 权限控制机制
- 当前用户获取与校验
- 从 JWT 解析用户 ID，查询用户并校验启用状态
- 角色权限
- 管理员（admin）：最高权限
- 经理（manager）：部分管理操作
- 普通员工（staff）：受限操作
章节来源
- [backend/app/core/security.py](file://backend/app/core/security.py#L55-L109)
### 模板管理最佳实践
- 模板类型选择
- 根据科室类型选择对应模板，避免跨类型混用
- 维度权重设计
- 明确财务/客户/内部流程/学习与成长的权重范围与合计
- 指标权重与排序
- 指标层权重与模板层权重协同，排序字段保持连续与稳定
- 激活状态
- 新建模板先启用少量指标进行测试，逐步放开
章节来源
- [docs/详细设计.md](file://docs/详细设计.md#L69-L95)
- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L63-L74)
- [backend/app/services/template_service.py](file://backend/app/services/template_service.py#L270-L283)

587
.qoder/repowiki/zh/content/数据模型详解/核心数据模型/绩效计划模型.md Normal file
View File

@@ -0,0 +1,587 @@
# 绩效计划模型
<cite>
**本文档引用的文件**
- [models.py](file://backend/app/models/models.py)
- [performance_plans.py](file://backend/app/api/v1/performance_plans.py)
- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py)
- [schemas.py](file://backend/app/schemas/schemas.py)
- [001_initial.py](file://backend/alembic/versions/001_initial.py)
- [002_template.py](file://backend/alembic/versions/002_template.py)
- [performance_plan.js](file://frontend/src/api/performance_plan.js)
- [create_plan_tables.py](file://backend/create_plan_tables.py)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概览](#架构概览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
## 简介
本文件详细阐述了医院绩效系统的绩效计划模型设计与实现。该模型支持多层级、多维度的绩效管理需求，涵盖从医院级到个人级的完整计划体系，提供完善的审批流程、版本控制和执行跟踪功能。系统采用现代化的前后端分离架构，后端基于FastAPI和SQLAlchemy，前端使用Vue.js框架。
## 项目结构
绩效计划模型位于后端应用的核心模块中，采用清晰的分层架构设计：
```mermaid
graph TB
subgraph "后端架构"
API[API层<br/>performance_plans.py]
Service[服务层<br/>performance_plan_service.py]
Model[模型层<br/>models.py]
Schema[数据模式<br/>schemas.py]
DB[(数据库)]
end
subgraph "前端架构"
Frontend[前端应用<br/>Vue.js]
APIClient[API客户端<br/>performance_plan.js]
end
Frontend --> APIClient
APIClient --> API
API --> Service
Service --> Model
Model --> DB
```
**图表来源**
- [performance_plans.py](file://backend/app/api/v1/performance_plans.py#L1-L310)
- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L1-L342)
- [models.py](file://backend/app/models/models.py#L270-L342)
**章节来源**
- [performance_plans.py](file://backend/app/api/v1/performance_plans.py#L1-L310)
- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L1-L342)
- [models.py](file://backend/app/models/models.py#L270-L342)
## 核心组件
### 计划层级枚举（PlanLevel）
系统定义了三个层级的计划结构，支持从宏观到微观的逐级分解：
```mermaid
classDiagram
class PlanLevel {
<<enumeration>>
+hospital
+department
+individual
}
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
+datetime submit_time
+int approver_id
+datetime approve_time
+string approve_remark
+int version
+bool is_active
}
PerformancePlan --> PlanLevel : uses
```
**图表来源**
- [models.py](file://backend/app/models/models.py#L263-L268)
- [models.py](file://backend/app/models/models.py#L270-L312)
### 计划状态枚举（PlanStatus）
状态管理贯穿整个计划生命周期，确保流程的规范性和可追溯性：
```mermaid
stateDiagram-v2
[*] --> 草稿
草稿 --> 待审批 : 提交
待审批 --> 已批准 : 审批通过
待审批 --> 已驳回 : 审批驳回
已批准 --> 执行中 : 激活
已批准 --> 已完成 : 结束
执行中 --> 已完成 : 结束
已完成 --> 取消 : 取消
草稿 --> 取消 : 删除
```
**图表来源**
- [models.py](file://backend/app/models/models.py#L233-L242)
### 时间维度管理
系统支持年度和月度两种时间维度，满足不同层级的计划管理需求：
| 时间维度 | 字段 | 用途 | 限制 |
|---------|------|------|------|
| 年度计划 | plan_year | 计划年度 | 必填 |
| 月度计划 | plan_year, plan_month | 计划年度和月份 | 月度计划时必填 |
| 计划类型 | plan_type | annual/monthly | 默认年度 |
**章节来源**
- [models.py](file://backend/app/models/models.py#L277-L280)
## 架构概览
### 数据模型关系图
```mermaid
erDiagram
PERFORMANCE_PLANS {
int id PK
string plan_name
string plan_code UK
enum plan_level
int plan_year
int plan_month
string plan_type
int department_id FK
int staff_id FK
int parent_plan_id FK
text strategic_goals
text key_initiatives
enum status
int submitter_id FK
datetime submit_time
int approver_id FK
datetime approve_time
text approve_remark
int version
bool is_active
datetime created_at
datetime updated_at
}
PLAN_KPI_RELATIONS {
int id PK
int plan_id FK
int indicator_id FK
float target_value
string target_unit
float weight
string scoring_method
text scoring_params
text remark
datetime created_at
datetime updated_at
}
DEPARTMENTS {
int id PK
string name
string code UK
enum dept_type
int parent_id FK
int level
int sort_order
bool 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
enum status
datetime hire_date
datetime created_at
datetime updated_at
}
USERS {
int id PK
string username UK
string password_hash
int staff_id FK
string role
bool is_active
datetime last_login
datetime created_at
datetime updated_at
}
INDICATORS {
int id PK
string name
string code UK
enum indicator_type
enum bs_dimension
numeric weight
numeric max_score
numeric target_value
string target_unit
text calculation_method
text assessment_method
text deduction_standard
string data_source
text applicable_dept_types
bool is_veto
bool is_active
datetime created_at
datetime updated_at
}
PERFORMANCE_PLANS ||--o{ PLAN_KPI_RELATIONS : contains
PLAN_KPI_RELATIONS }o--|| INDICATORS : links_to
PERFORMANCE_PLANS }o--|| DEPARTMENTS : belongs_to
PERFORMANCE_PLANS }o--|| STAFF : responsible_for
PERFORMANCE_PLANS }o--|| USERS : submitted_by
PERFORMANCE_PLANS }o--|| USERS : approved_by
DEPARTMENTS ||--o{ PERFORMANCE_PLANS : hosts
STAFF ||--o{ PERFORMANCE_PLANS : creates
```
**图表来源**
- [models.py](file://backend/app/models/models.py#L62-L438)
### API接口架构
```mermaid
sequenceDiagram
participant Client as 前端客户端
participant API as API层
participant Service as 服务层
participant DB as 数据库
Client->>API : GET /plans
API->>Service : get_list()
Service->>DB : 查询计划列表
DB-->>Service : 返回结果集
Service-->>API : 计划列表
API-->>Client : JSON响应
Client->>API : POST /plans
API->>Service : create()
Service->>DB : 插入新计划
DB-->>Service : 返回新ID
Service-->>API : 完整计划对象
API-->>Client : 创建成功
```
**图表来源**
- [performance_plans.py](file://backend/app/api/v1/performance_plans.py#L21-L66)
- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L76-L102)
**章节来源**
- [models.py](file://backend/app/models/models.py#L270-L342)
- [performance_plans.py](file://backend/app/api/v1/performance_plans.py#L1-L310)
- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L1-L342)
## 详细组件分析
### PerformancePlan模型详解
PerformancePlan是整个绩效计划系统的核心实体，承载着完整的计划信息和业务逻辑：
#### 核心属性设计
| 属性名 | 类型 | 必填 | 描述 | 约束 |
|--------|------|------|------|------|
| plan_name | string | 是 | 计划名称 | 最大长度200 |
| plan_code | string | 是 | 计划编码 | 唯一约束，最大长度50 |
| plan_level | PlanLevel | 是 | 计划层级 | 枚举值：hospital/department/individual |
| plan_year | int | 是 | 计划年度 | 必填 |
| plan_month | int | 否 | 计划月份 | 月度计划时必填 |
| plan_type | string | 否 | 计划类型 | 默认annual，可选monthly |
| department_id | int | 否 | 所属科室ID | 外键约束 |
| staff_id | int | 否 | 责任人ID | 外键约束 |
| parent_plan_id | int | 否 | 上级计划ID | 自引用外键 |
| strategic_goals | text | 否 | 战略目标 | 文本内容 |
| key_initiatives | text | 否 | 关键举措 | 文本内容 |
| version | int | 否 | 版本号 | 默认1，自增 |
| is_active | bool | 否 | 是否启用 | 默认true |
#### 关系映射
```mermaid
classDiagram
class PerformancePlan {
+Department department
+Staff staff
+PerformancePlan parent_plan
+PlanKpiRelation[] kpi_relations
+User submitter
+User approver
+PerformancePlan[] child_plans
}
class PlanKpiRelation {
+PerformancePlan plan
+Indicator indicator
}
class Department {
+PerformancePlan[] performance_plans
}
class Staff {
+PerformancePlan[] performance_plans
}
PerformancePlan --> Department : belongs_to
PerformancePlan --> Staff : responsible_for
PerformancePlan --> PlanKpiRelation : contains
PlanKpiRelation --> Indicator : links_to
PerformancePlan --> PerformancePlan : parent_child
```
**图表来源**
- [models.py](file://backend/app/models/models.py#L298-L304)
- [models.py](file://backend/app/models/models.py#L314-L338)
### 计划层级业务含义
#### 医院级计划（Hospital）
- **覆盖范围**：整个医院层面的战略规划
- **制定主体**：医院管理层
- **关注重点**：医院整体发展战略、资源配置、重大决策
- **典型内容**：医院发展规划、重大投资计划、体制改革方案
#### 科室级计划（Department）
- **覆盖范围**：特定临床或医技科室
- **制定主体**：科室负责人
- **关注重点**：科室业务发展、质量改进、效率提升
- **典型内容**：学科建设、人才培养、技术创新
#### 个人级计划（Individual）
- **覆盖范围**：具体员工个人
- **制定主体**：员工本人或直接上级
- **关注重点**：个人能力发展、工作目标达成
- **典型内容**：技能培训、绩效目标、职业发展规划
### 多级审批流程
系统实现了严格的多级审批机制，确保计划的合规性和权威性：
```mermaid
flowchart TD
Start([开始]) --> Create["创建草稿计划"]
Create --> Submit["提交审批"]
Submit --> Review{"审批状态"}
Review --> |通过| Approve["审批通过"]
Review --> |驳回| Reject["审批驳回"]
Approve --> Activate["激活执行"]
Reject --> Edit["修改后重新提交"]
Activate --> Execute["执行中"]
Execute --> Complete["完成"]
Edit --> Submit
Complete --> Cancel["取消"]
Cancel --> End([结束])
```
**图表来源**
- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L131-L182)
### 计划与指标关联关系
PlanKpiRelation表建立了计划与指标之间的多对多关联：
#### 关联属性设计
| 属性名 | 类型 | 必填 | 描述 | 约束 |
|--------|------|------|------|------|
| target_value | float | 否 | 目标值 | 数值类型 |
| target_unit | string | 否 | 目标值单位 | 最大长度50 |
| weight | float | 否 | 权重 | 默认1.0 |
| scoring_method | string | 否 | 评分方法 | 最大长度50 |
| scoring_params | text | 否 | 评分参数 | JSON格式 |
| remark | text | 否 | 备注 | 文本内容 |
#### 关联规则
```mermaid
erDiagram
PERFORMANCE_PLANS ||--o{ PLAN_KPI_RELATIONS : contains
PLAN_KPI_RELATIONS }o--|| INDICATORS : links_to
PLAN_KPI_RELATIONS {
unique(plan_id, indicator_id)
}
```
**图表来源**
- [models.py](file://backend/app/models/models.py#L314-L338)
### 版本控制机制
系统内置版本控制功能，支持计划的迭代更新：
#### 版本管理策略
1. **初始版本**：新建计划时自动设置为1
2. **版本递增**：每次更新操作时版本号+1
3. **历史追踪**：通过版本号区分不同版本的计划
4. **冲突处理**：并发更新时通过版本号避免数据覆盖
#### 版本控制API
| 接口 | 方法 | 功能 | 权限要求 |
|------|------|------|----------|
| /plans | POST | 创建新计划 | 普通用户 |
| /plans/{id} | PUT | 更新计划 | 管理员/经理 |
| /plans/{id}/submit | POST | 提交审批 | 普通用户 |
| /plans/{id}/approve | POST | 审批计划 | 管理员/经理 |
| /plans/{id}/activate | POST | 激活计划 | 管理员/经理 |
**章节来源**
- [models.py](file://backend/app/models/models.py#L293)
- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L105-L128)
## 依赖关系分析
### 数据库依赖关系
```mermaid
graph LR
subgraph "核心表"
PP[performance_plans]
PKR[plan_kpi_relations]
IND[indicators]
DEPT[departments]
STAFF[staff]
USR[users]
end
PP --> DEPT
PP --> STAFF
PP --> USR
PP --> PP
PKR --> PP
PKR --> IND
DEPT --> DEPT
```
**图表来源**
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L22-L183)
- [002_template.py](file://backend/alembic/versions/002_template.py#L21-L96)
### 前后端交互依赖
```mermaid
sequenceDiagram
participant FE as 前端
participant API as 后端API
participant SVC as 服务层
participant DB as 数据库
FE->>API : 发起HTTP请求
API->>SVC : 调用业务逻辑
SVC->>DB : 执行数据库操作
DB-->>SVC : 返回查询结果
SVC-->>API : 返回业务数据
API-->>FE : 返回JSON响应
```
**图表来源**
- [performance_plan.js](file://frontend/src/api/performance_plan.js#L1-L67)
### 外部依赖
- **FastAPI**：Web框架和API开发
- **SQLAlchemy**：ORM框架和数据库抽象
- **Alembic**：数据库迁移工具
- **Vue.js**：前端框架
- **PostgreSQL**：数据库引擎
**章节来源**
- [performance_plan.js](file://frontend/src/api/performance_plan.js#L1-L67)
- [create_plan_tables.py](file://backend/create_plan_tables.py#L1-L19)
## 性能考虑
### 数据库性能优化
1. **索引策略**
- 计划层级索引：`idx_plan_level`
- 计划年度索引：`idx_plan_year`
- 状态索引：`idx_plan_status`
- 部门索引：`idx_plan_department`
2. **查询优化**
- 使用`selectinload`进行关联查询
- 实现分页查询避免大数据量加载
- 缓存常用查询结果
3. **连接池管理**
- 异步数据库连接
- 连接池大小合理配置
- 连接超时和重试机制
### 前端性能优化
1. **API调用优化**
- 批量数据请求
- 请求去重和缓存
- 错误重试机制
2. **界面渲染优化**
- 组件懒加载
- 虚拟滚动处理大量数据
- 图表组件按需渲染
## 故障排除指南
### 常见问题及解决方案
#### 计划创建失败
**问题**：创建计划时报错
**可能原因**：
- 计划编码重复
- 必填字段缺失
- 外键约束错误
**解决步骤**：
1. 检查计划编码是否唯一
2. 验证所有必填字段
3. 确认关联实体存在
#### 审批流程异常
**问题**：审批状态无法正常流转
**可能原因**：
- 当前状态不正确
- 权限不足
- 数据库事务未提交
**解决步骤**：
1. 检查当前计划状态
2. 验证用户权限
3. 查看数据库事务日志
#### 性能问题
**问题**：查询响应缓慢
**可能原因**：
- 缺少必要索引
- 查询条件不当
- 数据量过大
**解决步骤**：
1. 添加缺失索引
2. 优化查询条件
3. 实施分页查询
**章节来源**
- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L131-L182)
- [performance_plans.py](file://backend/app/api/v1/performance_plans.py#L194-L225)
## 结论
绩效计划模型通过精心设计的数据结构和严谨的业务流程，为医院提供了完整的绩效管理体系。系统的主要优势包括：
1. **层次化设计**：支持从医院级到个人级的多层级计划管理
2. **流程规范化**：完善的审批流程确保计划的合规性
3. **扩展性强**：灵活的指标关联机制支持个性化配置
4. **版本控制**：内置版本管理支持计划的迭代演进
5. **前后端分离**：现代化的技术栈提供良好的开发体验
该模型为医院的绩效管理提供了坚实的技术基础，能够有效支撑医院的战略实施和日常运营管理工作。

428
.qoder/repowiki/zh/content/数据模型详解/核心数据模型/考核指标模型.md Normal file
View File

@@ -0,0 +1,428 @@
# 考核指标模型
<cite>
**本文档引用的文件**
- [models.py](file://backend/app/models/models.py)
- [schemas.py](file://backend/app/schemas/schemas.py)
- [indicators.py](file://backend/app/api/v1/indicators.py)
- [indicator_service.py](file://backend/app/services/indicator_service.py)
- [assessment_service.py](file://backend/app/services/assessment_service.py)
- [001_initial.py](file://backend/alembic/versions/001_initial.py)
- [002_template.py](file://backend/alembic/versions/002_template.py)
- [init_indicator_templates.py](file://backend/init_indicator_templates.py)
- [详细设计文档.md](file://docs/详细设计文档.md)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概览](#架构概览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
## 简介
本文件详细阐述了医院绩效系统中的考核指标模型设计与实现。该模型基于平衡计分卡理论，支持财务、客户、内部流程、学习与成长四个维度，涵盖质量、数量、效率、服务、成本等多种指标类型。系统通过明确的权重管理、评分规则和数据源管理，实现了科学、规范的绩效考核体系。
## 项目结构
后端采用分层架构设计，主要包含以下层次：
```mermaid
graph TB
subgraph "表现层"
API[API路由层]
end
subgraph "服务层"
IndicatorService[指标服务层]
AssessmentService[考核服务层]
end
subgraph "模型层"
Indicator[指标模型]
Assessment[考核记录模型]
AssessmentDetail[考核明细模型]
IndicatorTemplate[指标模板模型]
TemplateIndicator[模板指标关联模型]
end
subgraph "数据层"
Database[(数据库)]
end
API --> IndicatorService
API --> AssessmentService
IndicatorService --> Indicator
AssessmentService --> Assessment
AssessmentService --> AssessmentDetail
Indicator --> AssessmentDetail
IndicatorTemplate --> TemplateIndicator
Indicator --> Database
Assessment --> Database
AssessmentDetail --> Database
IndicatorTemplate --> Database
TemplateIndicator --> Database
```
**图表来源**
- [models.py](file://backend/app/models/models.py#L117-L146)
- [indicators.py](file://backend/app/api/v1/indicators.py#L1-L142)
**章节来源**
- [models.py](file://backend/app/models/models.py#L1-L438)
- [schemas.py](file://backend/app/schemas/schemas.py#L1-L743)
## 核心组件
### 指标类型枚举 (IndicatorType)
系统定义了五种核心指标类型，每种类型都有明确的业务含义和适用场景：
```mermaid
classDiagram
class IndicatorType {
<<enumeration>>
+quality
+quantity
+efficiency
+service
+cost
}
class BSCDimension {
<<enumeration>>
+financial
+customer
+internal_process
+learning_growth
}
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
}
Indicator --> IndicatorType : uses
Indicator --> BSCDimension : uses
```
**图表来源**
- [models.py](file://backend/app/models/models.py#L54-L61)
- [models.py](file://backend/app/models/models.py#L29-L35)
- [models.py](file://backend/app/models/models.py#L117-L146)
### 权重管理机制
权重是指标体系的核心要素，系统通过以下机制确保权重的合理分配：
1. **权重范围约束**：权重必须大于0，确保每个指标都有实际意义
2. **加权得分计算**：在考核过程中，加权得分 = 指标得分 × 指标权重
3. **模板权重继承**：从指标模板中继承权重设置，支持批量配置
**章节来源**
- [models.py](file://backend/app/models/models.py#L126-L127)
- [models.py](file://backend/app/models/models.py#L144-L145)
- [assessment_service.py](file://backend/app/services/assessment_service.py#L76-L84)
## 架构概览
系统采用MVC架构模式，通过清晰的职责分离实现高效的数据处理：
```mermaid
sequenceDiagram
participant Client as 客户端
participant API as API路由
participant Service as 服务层
participant Model as 模型层
participant DB as 数据库
Client->>API : GET /indicators
API->>Service : get_list()
Service->>Model : 查询指标列表
Model->>DB : 执行SQL查询
DB-->>Model : 返回查询结果
Model-->>Service : 返回指标对象
Service-->>API : 返回指标数据
API-->>Client : JSON响应
Note over Client,DB : 数据持久化通过ORM映射
```
**图表来源**
- [indicators.py](file://backend/app/api/v1/indicators.py#L20-L41)
- [indicator_service.py](file://backend/app/services/indicator_service.py#L17-L46)
## 详细组件分析
### 指标模型设计
指标模型是整个系统的核心，包含了完整的考核指标定义：
#### 核心字段设计
| 字段名 | 类型 | 描述 | 约束条件 |
|--------|------|------|----------|
| id | Integer | 主键标识 | 自增 |
| name | String | 指标名称 | 非空，最大100字符 |
| code | String | 指标编码 | 唯一，非空，最大20字符 |
| indicator_type | Enum | 指标类型 | 非空，枚举类型 |
| bs_dimension | Enum | BSC维度 | 非空，枚举类型 |
| weight | Numeric | 权重 | 默认1.0，>0 |
| max_score | Numeric | 最高分值 | 默认100.0 |
| target_value | Numeric | 目标值 | 可选 |
| target_unit | String | 目标值单位 | 可选，最大50字符 |
| calculation_method | Text | 计算方法 | 可选 |
| assessment_method | Text | 考核方法 | 可选 |
| deduction_standard | Text | 扣分标准 | 可选 |
| data_source | String | 数据来源 | 可选，最大100字符 |
| applicable_dept_types | Text | 适用科室类型 | JSON数组 |
| is_veto | Boolean | 一票否决标志 | 默认False |
| is_active | Boolean | 启用状态 | 默认True |
#### 适用科室类型过滤
系统通过JSON格式存储适用科室类型，支持灵活的科室匹配：
```mermaid
flowchart TD
Start([开始筛选]) --> GetDeptTypes["获取指标适用科室类型<br/>JSON数组"]
GetDeptTypes --> ParseJSON["解析JSON字符串"]
ParseJSON --> CompareDept{"匹配当前科室类型？"}
CompareDept --> |是| Include["包含在适用范围内"]
CompareDept --> |否| Exclude["排除在适用范围外"]
Include --> End([结束])
Exclude --> End
```
**图表来源**
- [models.py](file://backend/app/models/models.py#L134)
- [indicator_service.py](file://backend/app/services/indicator_service.py#L112-L154)
**章节来源**
- [models.py](file://backend/app/models/models.py#L121-L138)
- [schemas.py](file://backend/app/schemas/schemas.py#L153-L163)
### 一票否决指标处理
一票否决是系统的重要风控机制，具有以下特点：
#### 特殊处理逻辑
```mermaid
flowchart TD
Start([开始处理指标]) --> CheckVeto{"是否为一票否决指标？"}
CheckVeto --> |否| NormalCalc["正常评分计算"]
CheckVeto --> |是| VetoCheck["检查否决条件"]
VetoCheck --> VetoTrigger{"否决条件触发？"}
VetoTrigger --> |是| ZeroScore["直接得分为0分"]
VetoTrigger --> |否| NormalCalc
NormalCalc --> End([结束])
ZeroScore --> End
```
**图表来源**
- [models.py](file://backend/app/models/models.py#L135)
- [init_indicator_templates.py](file://backend/init_indicator_templates.py#L194-L195)
#### 实际应用场景
在临床手术科室的院感控制指标中，系统设置了"院感控制达标率"作为一票否决指标，确保医疗安全底线。
**章节来源**
- [init_indicator_templates.py](file://backend/init_indicator_templates.py#L180-L196)
### 计算方法与考核方法的区别
系统明确区分了两种不同的指标处理方式：
#### 计算方法 (Calculation Method)
- **定义**：用于计算实际值的具体公式或方法
- **用途**：从原始数据中提取和计算指标的实际数值
- **示例**：`(本期收入 - 同期收入)/同期收入 × 100%`
#### 考核方法 (Assessment Method)
- **定义**：用于验证和确认指标结果的检查方法
- **用途**：提供数据验证和审计依据
- **示例**：统计报表、现场核查、问卷调查
**章节来源**
- [models.py](file://backend/app/models/models.py#L130-L131)
### 指标与模板的关系
系统实现了指标与模板的多对多关系，支持灵活的指标配置：
```mermaid
erDiagram
INDICATORS {
int id PK
string code UK
string name
enum indicator_type
enum bs_dimension
numeric weight
numeric max_score
bool is_active
}
INDICATOR_TEMPLATES {
int id PK
string template_code UK
string template_name
enum template_type
bool is_active
}
TEMPLATE_INDICATORS {
int id PK
int template_id FK
int indicator_id FK
string category
numeric target_value
string target_unit
numeric weight
string scoring_method
text scoring_params
int sort_order
}
INDICATORS ||--o{ TEMPLATE_INDICATORS : "被包含"
INDICATOR_TEMPLATES ||--o{ TEMPLATE_INDICATORS : "包含"
```
**图表来源**
- [models.py](file://backend/app/models/models.py#L387-L438)
- [002_template.py](file://backend/alembic/versions/002_template.py#L65-L95)
**章节来源**
- [models.py](file://backend/app/models/models.py#L411-L437)
- [init_indicator_templates.py](file://backend/init_indicator_templates.py#L23-L200)
### 指标与考核明细的一对多关系
每个指标可以对应多个考核记录，形成完整的历史追踪：
```mermaid
classDiagram
class Indicator {
+int id
+string code
+string name
+AssessmentDetail[] assessment_details
}
class AssessmentDetail {
+int id
+int assessment_id
+int indicator_id
+float actual_value
+float score
+string evidence
+string remark
}
class Assessment {
+int id
+int staff_id
+int period_year
+int period_month
+float total_score
+float weighted_score
+AssessmentDetail[] details
}
Indicator "1" --> "0..*" AssessmentDetail : "被考核"
Assessment "1" --> "0..*" AssessmentDetail : "包含"
AssessmentDetail --> Indicator : "关联"
AssessmentDetail --> Assessment : "属于"
```
**图表来源**
- [models.py](file://backend/app/models/models.py#L117-L146)
- [models.py](file://backend/app/models/models.py#L181-L202)
**章节来源**
- [models.py](file://backend/app/models/models.py#L140-L141)
- [models.py](file://backend/app/models/models.py#L195-L197)
## 依赖关系分析
系统通过清晰的依赖关系实现模块化设计：
```mermaid
graph TD
subgraph "外部依赖"
SQLAlchemy[SQLAlchemy ORM]
FastAPI[FastAPI框架]
Pydantic[Pydantic验证]
end
subgraph "内部模块"
Models[数据模型]
Schemas[数据模式]
Services[业务服务]
API[API路由]
end
SQLAlchemy --> Models
FastAPI --> API
Pydantic --> Schemas
Models --> Services
Schemas --> Services
Services --> API
Models --> API
Schemas --> API
```
**图表来源**
- [models.py](file://backend/app/models/models.py#L1-L13)
- [schemas.py](file://backend/app/schemas/schemas.py#L1-L8)
**章节来源**
- [models.py](file://backend/app/models/models.py#L1-L438)
- [schemas.py](file://backend/app/schemas/schemas.py#L1-L743)
## 性能考虑
系统在设计时充分考虑了性能优化：
### 数据库索引策略
- 指标类型索引：加速指标类型的查询和筛选
- 权重约束：确保数据完整性的同时维护性能
- 多字段复合索引：优化复杂查询场景
### 缓存策略
- 指标列表缓存：减少频繁的数据库查询
- 模板数据缓存：提升模板导入和使用的响应速度
### 异步处理
- 使用异步数据库连接：提高并发处理能力
- 异步服务调用：避免阻塞操作影响整体性能
## 故障排除指南
### 常见问题及解决方案
#### 指标编码重复错误
**问题描述**：创建指标时提示编码已存在
**解决方法**：检查指标编码的唯一性，确保每个编码在整个系统中唯一
#### 权重值异常
**问题描述**：权重值小于等于0导致计算异常
**解决方法**：确保权重值大于0，系统已通过数据库约束保证数据完整性
#### 一票否决触发
**问题描述**：某些情况下指标得分为0分
**解决方法**：检查一票否决条件的触发逻辑，确认是否符合预设的标准
**章节来源**
- [indicators.py](file://backend/app/api/v1/indicators.py#L78-L81)
- [models.py](file://backend/app/models/models.py#L144-L145)
## 结论
考核指标模型通过精心设计的架构和完善的约束机制，为医院绩效管理提供了坚实的技术基础。系统不仅支持灵活的指标配置和权重管理，还通过一票否决机制确保关键指标的严格执行。多对多关系的设计使得指标模板能够灵活复用，而清晰的计算方法与考核方法区分则保证了数据处理的准确性。
该模型的成功实施将有助于医院建立科学、公正、透明的绩效考核体系，为提升医疗质量和患者满意度提供有力支撑。

470
.qoder/repowiki/zh/content/数据模型详解/核心数据模型/考核明细模型.md Normal file
View File

@@ -0,0 +1,470 @@
# 考核明细模型
<cite>
**本文档引用的文件**
- [models.py](file://backend/app/models/models.py)
- [assessment_service.py](file://backend/app/services/assessment_service.py)
- [assessments.py](file://backend/app/api/v1/assessments.py)
- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue)
- [Assessments.vue](file://frontend/src/views/assessment/Assessments.vue)
- [assessment.js](file://frontend/src/api/assessment.js)
- [schemas.py](file://backend/app/schemas/schemas.py)
- [001_initial.py](file://backend/alembic/versions/001_initial.py)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概览](#架构概览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
考核明细模型是医院绩效考核管理系统的核心数据结构，负责记录每个考核周期内员工各项指标的具体表现和得分情况。该模型实现了完整的考核数据管理功能，包括实际值记录、得分计算、佐证材料管理和多对一关系约束。
本系统采用现代化的技术栈，后端基于FastAPI和SQLAlchemy 2.0异步ORM，前端使用Vue 3 Composition API和Element Plus组件库，实现了完整的绩效考核流程管理。
## 项目结构
系统采用分层架构设计，主要包含以下层次：
```mermaid
graph TB
subgraph "前端层"
FE1[Assessments.vue<br/>考核列表页面]
FE2[AssessmentDetail.vue<br/>考核详情页面]
FE3[assessment.js<br/>API请求封装]
end
subgraph "后端层"
BE1[assessments.py<br/>API路由]
BE2[assessment_service.py<br/>业务服务层]
BE3[schemas.py<br/>数据模式定义]
end
subgraph "数据层"
DB1[models.py<br/>数据模型]
DB2[001_initial.py<br/>数据库迁移]
end
FE1 --> FE3
FE2 --> FE3
FE3 --> BE1
BE1 --> BE2
BE2 --> BE3
BE3 --> DB1
DB1 --> DB2
```
**图表来源**
- [Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L1-L311)
- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L1-L257)
- [assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
- [assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
- [models.py](file://backend/app/models/models.py#L181-L203)
**章节来源**
- [Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L1-L311)
- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L1-L257)
- [assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
## 核心组件
### AssessmentDetail模型设计
AssessmentDetail模型是考核明细的核心数据结构，具有以下关键特性：
**数据字段设计**：
- `assessment_id`: 考核记录ID（外键关联）
- `indicator_id`: 指标ID（外键关联）
- `actual_value`: 实际值（数值型，支持小数）
- `score`: 得分（数值型，默认0）
- `evidence`: 佐证材料（文本型）
- `remark`: 备注（文本型）
**关系映射**：
- 与Assessment模型建立多对一关系
- 与Indicator模型建立多对一关系
- 支持级联删除和级联刷新
**索引优化**：
- 为assessment_id和indicator_id建立复合索引
- 提升查询性能和数据完整性
**章节来源**
- [models.py](file://backend/app/models/models.py#L181-L203)
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L114-L132)
### 考核流程集成
系统实现了完整的考核流程，AssessmentDetail模型在整个流程中发挥关键作用：
```mermaid
sequenceDiagram
participant User as 用户
participant Frontend as 前端界面
participant API as API接口
participant Service as 服务层
participant DB as 数据库
User->>Frontend : 输入实际值和得分
Frontend->>API : 提交更新请求
API->>Service : 调用更新方法
Service->>DB : 更新AssessmentDetail记录
DB-->>Service : 返回更新结果
Service->>DB : 计算总分和加权得分
DB-->>Service : 返回计算结果
Service-->>API : 返回更新后的考核记录
API-->>Frontend : 显示更新结果
Frontend-->>User : 展示最新的考核明细
```
**图表来源**
- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L160-L175)
- [assessment_service.py](file://backend/app/services/assessment_service.py#L111-L156)
**章节来源**
- [assessment_service.py](file://backend/app/services/assessment_service.py#L71-L108)
- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L160-L175)
## 架构概览
系统采用MVC架构模式，AssessmentDetail模型位于数据访问层，向上提供业务服务，向下连接数据库存储。
```mermaid
graph TB
subgraph "表现层"
UI1[Assessments.vue<br/>列表展示]
UI2[AssessmentDetail.vue<br/>详情编辑]
end
subgraph "控制器层"
API1[assessments.py<br/>路由处理]
API2[authentication<br/>权限控制]
end
subgraph "业务逻辑层"
SVC1[AssessmentService<br/>考核业务处理]
SVC2[IndicatorService<br/>指标业务处理]
end
subgraph "数据访问层"
MODEL1[Assessment模型]
MODEL2[AssessmentDetail模型]
MODEL3[Indicator模型]
MODEL4[Staff模型]
end
subgraph "数据存储"
DB1[PostgreSQL数据库]
DB2[SQLAlchemy ORM]
end
UI1 --> API1
UI2 --> API1
API1 --> SVC1
API1 --> SVC2
SVC1 --> MODEL1
SVC1 --> MODEL2
SVC2 --> MODEL3
MODEL1 --> DB2
MODEL2 --> DB2
MODEL3 --> DB2
MODEL4 --> DB2
DB2 --> DB1
```
**图表来源**
- [models.py](file://backend/app/models/models.py#L149-L203)
- [assessment_service.py](file://backend/app/services/assessment_service.py#L14-L263)
- [assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
## 详细组件分析
### AssessmentDetail模型类图
```mermaid
classDiagram
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 Assessment {
+int id
+int staff_id
+int period_year
+int period_month
+string period_type
+float total_score
+float weighted_score
+string status
+int assessor_id
+int reviewer_id
+datetime submit_time
+datetime review_time
+string remark
+datetime created_at
+datetime updated_at
+details AssessmentDetail[]
}
class Indicator {
+int id
+string name
+string code
+string indicator_type
+float weight
+float max_score
+float target_value
+string target_unit
+string calculation_method
+string assessment_method
+string deduction_standard
+string data_source
+bool is_veto
+bool is_active
+details AssessmentDetail[]
}
AssessmentDetail --> Assessment : "多对一"
AssessmentDetail --> Indicator : "多对一"
Assessment "1" --> "*" AssessmentDetail : "一对多"
Indicator "1" --> "*" AssessmentDetail : "一对多"
```
**图表来源**
- [models.py](file://backend/app/models/models.py#L149-L203)
### 数据完整性约束
系统通过多种机制确保数据完整性：
**数据库层面约束**：
- 主键约束：确保每条明细记录的唯一性
- 外键约束：维护Assessment和Indicator的引用完整性
- 检查约束：限制权重值必须大于0
- 索引优化：提升查询性能
**业务层面约束**：
- 状态机控制：严格的流程状态转换
- 权限控制：不同角色的操作权限
- 数据验证：输入数据的格式和范围检查
**章节来源**
- [models.py](file://backend/app/models/models.py#L144-L146)
- [models.py](file://backend/app/models/models.py#L199-L202)
### 得分计算算法
系统实现了灵活的得分计算机制：
```mermaid
flowchart TD
Start([开始计算]) --> LoadDetails["加载考核明细"]
LoadDetails --> CalcTotal["计算总分<br/>sum(score)"]
CalcTotal --> CalcWeighted["计算加权得分<br/>sum(score × indicator.weight)"]
CalcWeighted --> ValidateRange["验证分数范围<br/>0 ≤ score ≤ max_score"]
ValidateRange --> CheckVeto{"检查一票否决"}
CheckVeto --> |是| ApplyVeto["应用一票否决规则"]
CheckVeto --> |否| CheckExceptions["检查异常值"]
CheckVeto --> UpdateAssessment["更新考核记录"]
ApplyVeto --> UpdateAssessment
CheckExceptions --> UpdateAssessment
UpdateAssessment --> End([计算完成])
```
**图表来源**
- [assessment_service.py](file://backend/app/services/assessment_service.py#L74-L84)
- [assessment_service.py](file://backend/app/services/assessment_service.py#L129-L149)
**章节来源**
- [assessment_service.py](file://backend/app/services/assessment_service.py#L71-L108)
- [assessment_service.py](file://backend/app/services/assessment_service.py#L111-L156)
### 佐证材料管理
系统提供了完整的佐证材料管理功能：
**存储机制**：
- 佐证材料以文本形式存储
- 支持URL链接和文件路径
- 可扩展为文件上传功能
**使用场景**：
- 质量指标的证明材料
- 数量指标的数据支撑
- 效率指标的计算依据
- 服务指标的客户反馈
**章节来源**
- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L71-L82)
- [models.py](file://backend/app/models/models.py#L190-L190)
### 时间戳跟踪机制
系统实现了全面的时间戳跟踪：
**创建时间**：记录AssessmentDetail的创建时刻
**更新时间**：自动更新记录的修改时间
**流程时间**：记录考核流程各阶段的时间戳
```mermaid
stateDiagram-v2
[*] --> 草稿
草稿 --> 已提交 : 提交审核
已提交 --> 已审核 : 审核通过
已提交 --> 已驳回 : 审核驳回
已审核 --> 已确认 : 确认考核
已确认 --> [*]
state 已提交 {
[*] --> 提交时间记录
}
state 已审核 {
[*] --> 审核时间记录
}
```
**图表来源**
- [models.py](file://backend/app/models/models.py#L163-L164)
- [assessment_service.py](file://backend/app/services/assessment_service.py#L159-L170)
**章节来源**
- [models.py](file://backend/app/models/models.py#L163-L167)
- [assessment_service.py](file://backend/app/services/assessment_service.py#L159-L192)
## 依赖关系分析
系统各组件之间的依赖关系如下：
```mermaid
graph LR
subgraph "外部依赖"
A[FastAPI]
B[SQLAlchemy 2.0]
C[PostgreSQL]
D[Vue 3]
E[Element Plus]
end
subgraph "内部模块"
F[models.py]
G[assessment_service.py]
H[assessments.py]
I[schemas.py]
J[AssessmentDetail.vue]
K[Assessments.vue]
end
A --> H
H --> G
G --> F
F --> C
B --> F
D --> J
D --> K
E --> J
E --> K
J --> I
K --> I
```
**图表来源**
- [models.py](file://backend/app/models/models.py#L1-L13)
- [assessment_service.py](file://backend/app/services/assessment_service.py#L1-L12)
- [assessments.py](file://backend/app/api/v1/assessments.py#L1-L16)
**章节来源**
- [models.py](file://backend/app/models/models.py#L1-L13)
- [assessment_service.py](file://backend/app/services/assessment_service.py#L1-L12)
## 性能考虑
### 查询优化策略
**索引设计**：
- 为assessment_id和indicator_id建立复合索引
- 为常用查询条件建立单独索引
- 使用覆盖索引减少查询开销
**查询优化**：
- 使用selectinload进行关联查询
- 避免N+1查询问题
- 实施分页查询机制
### 缓存策略
**数据缓存**：
- 指标配置信息缓存
- 员工基本信息缓存
- 科室层级结构缓存
**查询结果缓存**：
- 统计报表结果缓存
- 常用查询结果缓存
- 配置信息缓存
## 故障排除指南
### 常见问题及解决方案
**数据同步问题**：
- 确保Assessment和AssessmentDetail的事务一致性
- 检查外键约束是否正确设置
- 验证数据类型和精度匹配
**性能问题**：
- 分析慢查询日志
- 检查索引使用情况
- 优化复杂查询语句
**权限问题**：
- 验证用户角色和权限
- 检查API访问控制
- 确认数据访问范围
**章节来源**
- [assessment_service.py](file://backend/app/services/assessment_service.py#L117-L118)
- [models.py](file://backend/app/models/models.py#L199-L202)
## 结论
考核明细模型作为医院绩效考核管理系统的核心组件，实现了完整的数据管理功能。通过合理的数据结构设计、严格的数据完整性约束和高效的性能优化策略，系统能够满足医院复杂的绩效考核需求。
该模型不仅支持基本的考核数据记录，还提供了灵活的扩展能力，可以适应不同科室和岗位的考核要求。同时，系统的权限控制和审计功能确保了数据的安全性和可追溯性。
## 附录
### 数据录入示例
**单个明细录入**：
1. 选择考核周期（年、月）
2. 选择员工和指标
3. 录入实际值和得分
4. 添加佐证材料
5. 保存并提交审核
**批量处理方法**：
1. 通过批量创建功能生成默认明细
2. 批量导入实际值数据
3. 统一审核和确认流程
4. 生成批量统计报告
### 数据质量保证措施
**数据验证规则**：
- 分数范围验证（0-max_score）
- 权重有效性检查
- 指标类型匹配验证
- 时间范围合理性检查
**异常值处理**：
- 设置合理的阈值范围
- 异常值标记和提醒
- 自动化异常检测机制
- 人工复核流程
**章节来源**
- [schemas.py](file://backend/app/schemas/schemas.py#L196-L218)
- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L47-L68)

504
.qoder/repowiki/zh/content/数据模型详解/核心数据模型/考核记录模型.md Normal file
View File

@@ -0,0 +1,504 @@
# 考核记录模型
<cite>
**本文档引用的文件**
- [models.py](file://backend/app/models/models.py)
- [assessment_service.py](file://backend/app/services/assessment_service.py)
- [assessments.py](file://backend/app/api/v1/assessments.py)
- [schemas.py](file://backend/app/schemas/schemas.py)
- [001_initial.py](file://backend/alembic/versions/001_initial.py)
- [assessment.js](file://frontend/src/api/assessment.js)
- [database.md](file://docs/database.md)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概览](#架构概览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
## 简介
考核记录模型是医院绩效管理系统的核心数据结构，负责管理员工的绩效考核过程。该模型实现了完整的多级审批流程，支持草稿→提交→审核→确认→驳回的状态流转，并提供了灵活的考核周期管理和数据一致性保证机制。
## 项目结构
后端采用典型的三层架构设计，主要包含以下层次：
```mermaid
graph TB
subgraph "表现层"
API[API路由层]
Frontend[前端接口]
end
subgraph "业务逻辑层"
Service[服务层]
Schema[数据模式层]
end
subgraph "数据访问层"
Model[模型层]
DB[(数据库)]
end
Frontend --> API
API --> Service
Service --> Model
Model --> DB
```
**图表来源**
- [models.py](file://backend/app/models/models.py#L149-L178)
- [assessment_service.py](file://backend/app/services/assessment_service.py#L14-L263)
- [assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
**章节来源**
- [models.py](file://backend/app/models/models.py#L1-L438)
- [assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
- [assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
## 核心组件
### 考核状态枚举
考核状态枚举定义了完整的审批流程状态：
```mermaid
stateDiagram-v2
[*] --> 草稿
草稿 --> 已提交 : 提交考核
已提交 --> 已审核 : 审核通过
已提交 --> 已驳回 : 审核驳回
已审核 --> 已确认 : 确认完成
已确认 --> [*]
已驳回 --> 草稿 : 修改后重新提交
```
**图表来源**
- [models.py](file://backend/app/models/models.py#L45-L51)
### 主要数据模型
系统包含四个核心数据模型，形成了完整的考核数据结构：
```mermaid
erDiagram
ASSESSMENTS {
int id PK
int staff_id FK
int period_year
int period_month
string period_type
float total_score
float 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
float actual_value
float score
text evidence
text remark
datetime created_at
datetime updated_at
}
STAFF {
int id PK
int employee_id UK
string name
int department_id FK
string position
string title
string phone
string email
float base_salary
float performance_ratio
string status
datetime hire_date
datetime created_at
datetime updated_at
}
INDICATORS {
int id PK
string name
string code UK
string indicator_type
float weight
float max_score
float target_value
string target_unit
text calculation_method
text assessment_method
text deduction_standard
string data_source
string applicable_dept_types
boolean is_veto
boolean is_active
datetime created_at
datetime updated_at
}
ASSESSMENTS ||--o{ ASSESSMENT_DETAILS : contains
STAFF ||--o{ ASSESSMENTS : evaluates
INDICATORS ||--o{ ASSESSMENT_DETAILS : measures
```
**图表来源**
- [models.py](file://backend/app/models/models.py#L149-L203)
**章节来源**
- [models.py](file://backend/app/models/models.py#L149-L203)
## 架构概览
系统采用RESTful API设计，实现了完整的CRUD操作和业务流程控制：
```mermaid
sequenceDiagram
participant Client as 客户端
participant API as API层
participant Service as 服务层
participant DB as 数据库
Client->>API : 创建考核请求
API->>Service : create_assessment()
Service->>DB : 插入Assessment记录
Service->>DB : 插入AssessmentDetail记录
DB-->>Service : 返回新记录ID
Service-->>API : 返回创建结果
API-->>Client : 返回创建成功
Client->>API : 提交考核请求
API->>Service : submit_assessment()
Service->>DB : 更新状态为SUBMITTED
DB-->>Service : 确认更新
Service-->>API : 返回提交结果
API-->>Client : 返回提交成功
```
**图表来源**
- [assessments.py](file://backend/app/api/v1/assessments.py#L80-L115)
- [assessment_service.py](file://backend/app/services/assessment_service.py#L71-L108)
## 详细组件分析
### Assessment模型详解
Assessment模型是整个考核系统的核心，包含了完整的考核信息和审批状态：
#### 字段设计
| 字段名 | 类型 | 描述 | 约束 |
|--------|------|------|------|
| id | Integer | 主键ID | 自增 |
| staff_id | Integer | 员工ID | 外键，必填 |
| period_year | Integer | 考核年度 | 必填，范围2020-2100 |
| period_month | Integer | 考核月份 | 必填，范围1-12 |
| period_type | String | 考核周期类型 | 默认monthly |
| total_score | Float | 总分 | 默认0 |
| weighted_score | Float | 加权得分 | 默认0 |
| status | Enum | 考核状态 | 默认DRAFT |
| assessor_id | Integer | 考核人ID | 外键，可选 |
| reviewer_id | Integer | 审核人ID | 外键，可选 |
| submit_time | DateTime | 提交时间 | 可选 |
| review_time | DateTime | 审核时间 | 可选 |
| remark | Text | 备注 | 可选 |
#### 关系映射
```mermaid
classDiagram
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
+datetime submit_time
+datetime review_time
+string remark
+staff : Staff
+assessor : Staff
+reviewer : Staff
+details : AssessmentDetail[]
}
class Staff {
+int id
+string employee_id
+string name
+int department_id
+string position
+assessments : Assessment[]
}
class AssessmentDetail {
+int id
+int assessment_id
+int indicator_id
+float actual_value
+float score
+assessment : Assessment
+indicator : Indicator
}
Assessment --> Staff : belongs_to
Assessment --> Staff : evaluated_by
Assessment --> Staff : reviewed_by
Assessment --> AssessmentDetail : has_many
AssessmentDetail --> Indicator : measures
```
**图表来源**
- [models.py](file://backend/app/models/models.py#L149-L173)
#### 状态流转机制
```mermaid
flowchart TD
Start([开始]) --> Draft["草稿状态<br/>DRAFT"]
Draft --> Submit["提交状态<br/>SUBMITTED"]
Submit --> Review["审核状态<br/>REVIEWED"]
Submit --> Reject["驳回状态<br/>REJECTED"]
Review --> Finalize["确认状态<br/>FINALIZED"]
Reject --> Draft2["返回草稿<br/>DRAFT"]
Finalize --> End([结束])
Draft2 --> Submit
style Draft fill:#e1f5fe
style Submit fill:#f3e5f5
style Review fill:#e8f5e8
style Reject fill:#ffebee
style Finalize fill:#fff3e0
```
**图表来源**
- [assessment_service.py](file://backend/app/services/assessment_service.py#L159-L205)
### 计算逻辑实现
#### 总分计算
总分计算逻辑简单直接，将所有考核明细的得分相加：
```python
# 总分 = Σ(明细得分)
total_score = sum(d.score for d in assessment_data.details)
```
#### 加权得分计算
加权得分考虑了指标权重的影响：
```python
# 加权得分 = Σ(明细得分 × 指标权重)
weighted_score = 0.0
for detail in assessment_data.details:
indicator = await db.execute(
select(Indicator).where(Indicator.id == detail.indicator_id)
)
ind = indicator.scalar_one_or_none()
if ind:
weighted_score += detail.score * float(ind.weight)
```
**章节来源**
- [assessment_service.py](file://backend/app/services/assessment_service.py#L71-L108)
### API接口设计
系统提供了完整的RESTful API接口：
| 方法 | 路径 | 功能 | 权限要求 |
|------|------|------|----------|
| GET | /assessments | 获取考核列表 | 任意用户 |
| GET | /assessments/{id} | 获取考核详情 | 任意用户 |
| POST | /assessments | 创建考核记录 | 普通用户 |
| PUT | /assessments/{id} | 更新考核记录 | 普通用户 |
| POST | /assessments/{id}/submit | 提交考核 | 普通用户 |
| POST | /assessments/{id}/review | 审核考核 | 管理员/经理 |
| POST | /assessments/{id}/finalize | 确认考核 | 管理员/经理 |
| POST | /assessments/batch-create | 批量创建考核 | 管理员/经理 |
**章节来源**
- [assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
### 数据一致性保证
#### 级联删除机制
Assessment模型使用了级联删除策略，确保当主记录被删除时，相关的明细记录也会自动清理：
```python
details: Mapped[List["AssessmentDetail"]] = relationship(
"AssessmentDetail",
back_populates="assessment",
cascade="all, delete-orphan"
)
```
#### 索引优化
数据库层面建立了多个索引以提升查询性能：
- `idx_assessment_staff`: 员工ID索引
- `idx_assessment_period`: 年度+月份复合索引
- `idx_assessment_status`: 状态索引
**章节来源**
- [models.py](file://backend/app/models/models.py#L174-L178)
## 依赖关系分析
### 模块间依赖
```mermaid
graph LR
subgraph "外部依赖"
SQLAlchemy[SQLAlchemy ORM]
FastAPI[FastAPI框架]
Pydantic[Pydantic验证]
end
subgraph "内部模块"
Models[数据模型]
Services[业务服务]
API[API路由]
Schemas[数据模式]
end
SQLAlchemy --> Models
FastAPI --> API
Pydantic --> Schemas
API --> Services
Services --> Models
API --> Schemas
Services --> Schemas
```
**图表来源**
- [models.py](file://backend/app/models/models.py#L1-L13)
- [assessment_service.py](file://backend/app/services/assessment_service.py#L1-L11)
- [assessments.py](file://backend/app/api/v1/assessments.py#L1-L15)
### 数据流依赖
```mermaid
flowchart TD
Request[HTTP请求] --> Validation[数据验证]
Validation --> ServiceCall[服务调用]
ServiceCall --> DBQuery[数据库查询]
DBQuery --> BusinessLogic[业务逻辑处理]
BusinessLogic --> DBUpdate[数据库更新]
DBUpdate --> Response[响应生成]
Response --> Client[客户端]
Validation --> |Schema验证| ServiceCall
BusinessLogic --> |状态检查| DBUpdate
```
**图表来源**
- [schemas.py](file://backend/app/schemas/schemas.py#L220-L237)
- [assessment_service.py](file://backend/app/services/assessment_service.py#L111-L156)
**章节来源**
- [models.py](file://backend/app/models/models.py#L1-L438)
- [assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
- [assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
## 性能考虑
### 查询优化
1. **索引策略**: 为常用查询字段建立索引，包括员工ID、考核周期、状态等
2. **延迟加载**: 使用selectinload优化N+1查询问题
3. **分页处理**: 支持大数据集的分页查询
### 缓存策略
虽然当前实现没有内置缓存，但可以考虑：
- 考核状态的热点数据缓存
- 指标权重的静态数据缓存
- 员工基本信息的短期缓存
### 批量操作
系统支持批量创建考核记录，适用于月末批量处理场景：
```python
# 批量创建逻辑
for staff in staff_list:
assessment = Assessment(staff_id=staff.id, ...)
db.add(assessment)
# 为每个指标创建明细
for indicator_id in indicators:
detail = AssessmentDetail(indicator_id=indicator_id, ...)
db.add(detail)
```
## 故障排除指南
### 常见问题及解决方案
#### 状态流转错误
**问题**: 无法从草稿状态提交
**原因**: 考核记录状态不是DRAFT
**解决方案**: 检查当前状态是否为DRAFT
#### 权限不足
**问题**: 审核或确认接口返回400错误
**原因**: 当前用户权限不足
**解决方案**: 确保用户具有管理员或经理权限
#### 数据重复
**问题**: 批量创建时出现重复记录
**原因**: 同一员工在同一考核周期已存在记录
**解决方案**: 系统会自动跳过已存在的记录
### 异常处理机制
系统采用统一的异常处理模式：
```mermaid
flowchart TD
Try[业务操作] --> Success{操作成功?}
Success --> |是| ReturnOK[返回成功响应]
Success --> |否| CheckError{检查错误类型}
CheckError --> |业务错误| Return400[返回400错误]
CheckError --> |权限错误| Return403[返回403错误]
CheckError --> |数据库错误| Return500[返回500错误]
CheckError --> |其他错误| ReturnError[返回通用错误]
Return400 --> Catch[异常捕获]
Return403 --> Catch
Return500 --> Catch
ReturnError --> Catch
Catch --> Log[记录日志]
Log --> ReturnError
```
**图表来源**
- [assessments.py](file://backend/app/api/v1/assessments.py#L105-L132)
**章节来源**
- [assessments.py](file://backend/app/api/v1/assessments.py#L105-L132)
## 结论
考核记录模型设计合理，实现了以下关键特性：
1. **完整的审批流程**: 支持多级审批的完整生命周期管理
2. **灵活的数据模型**: 支持多种考核周期和指标类型
3. **强一致性的数据结构**: 通过外键约束和级联删除保证数据完整性
4. **良好的扩展性**: 模块化设计便于功能扩展和维护
5. **完善的API接口**: 提供RESTful风格的完整接口集合
该模型为医院绩效管理系统的稳定运行奠定了坚实的数据基础，能够有效支撑复杂的绩效考核业务需求。