提交文件
This commit is contained in:
660
.qoder/repowiki/zh/content/数据库设计/实体关系设计.md
Normal file
660
.qoder/repowiki/zh/content/数据库设计/实体关系设计.md
Normal file
@@ -0,0 +1,660 @@
|
||||
# 实体关系设计
|
||||
|
||||
<cite>
|
||||
**本文档引用的文件**
|
||||
- [models.py](file://backend/app/models/models.py)
|
||||
- [finance.py](file://backend/app/models/finance.py)
|
||||
- [database.py](file://backend/app/core/database.py)
|
||||
- [config.py](file://backend/app/core/config.py)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py)
|
||||
- [002_template.py](file://backend/alembic/versions/002_template.py)
|
||||
- [database.md](file://docs/database.md)
|
||||
- [staff.py](file://backend/app/api/v1/staff.py)
|
||||
- [assessments.py](file://backend/app/api/v1/assessments.py)
|
||||
- [performance_plans.py](file://backend/app/api/v1/performance_plans.py)
|
||||
- [salary.py](file://backend/app/api/v1/salary.py)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心实体](#核心实体)
|
||||
4. [架构概览](#架构概览)
|
||||
5. [详细实体分析](#详细实体分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考虑](#性能考虑)
|
||||
8. [故障排除指南](#故障排除指南)
|
||||
9. [结论](#结论)
|
||||
|
||||
## 简介
|
||||
|
||||
本文件为医院绩效系统的实体关系设计文档，详细描述了系统中所有核心实体之间的关系映射。该系统采用基于平衡计分卡的绩效管理体系，涵盖了科室管理、员工管理、绩效考核、工资核算、指标模板等多个业务领域。文档重点解释了一对一、一对多、多对多关系的设计原理和业务逻辑，包含外键约束、级联操作和引用完整性保证，并提供了完整的ER图说明。
|
||||
|
||||
## 项目结构
|
||||
|
||||
系统采用前后端分离架构，后端使用FastAPI + SQLAlchemy异步ORM框架，数据库采用PostgreSQL。项目结构清晰地按照功能模块组织：
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "后端架构"
|
||||
API[API路由层]
|
||||
Services[业务服务层]
|
||||
Models[数据模型层]
|
||||
Database[数据库层]
|
||||
end
|
||||
subgraph "前端架构"
|
||||
Vue[Vue.js前端]
|
||||
Components[组件库]
|
||||
Router[路由系统]
|
||||
end
|
||||
API --> Services
|
||||
Services --> Models
|
||||
Models --> Database
|
||||
Vue --> API
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [database.py](file://backend/app/core/database.py#L1-L39)
|
||||
- [config.py](file://backend/app/core/config.py#L1-L47)
|
||||
|
||||
**章节来源**
|
||||
- [database.py](file://backend/app/core/database.py#L1-L39)
|
||||
- [config.py](file://backend/app/core/config.py#L1-L47)
|
||||
|
||||
## 核心实体
|
||||
|
||||
系统包含以下核心实体，每个实体都承载着特定的业务职责：
|
||||
|
||||
### 基础实体
|
||||
- **Department**: 科室信息管理，支持多级组织架构
|
||||
- **Staff**: 员工信息管理，包含职位、职称、薪资等信息
|
||||
- **User**: 系统用户管理，支持角色权限控制
|
||||
|
||||
### 考核相关实体
|
||||
- **Assessment**: 绩效考核记录，管理考核流程状态
|
||||
- **AssessmentDetail**: 考核明细，记录具体指标得分
|
||||
- **Indicator**: 考核指标定义，支持多种指标类型
|
||||
|
||||
### 计划与模板实体
|
||||
- **PerformancePlan**: 绩效计划管理，支持多层级计划
|
||||
- **PlanKpiRelation**: 计划与指标关联关系
|
||||
- **IndicatorTemplate**: 指标模板，支持按科室类型分类
|
||||
- **TemplateIndicator**: 模板与指标关联关系
|
||||
|
||||
### 财务实体
|
||||
- **SalaryRecord**: 工资核算记录
|
||||
- **DepartmentFinance**: 科室财务记录
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L62-L438)
|
||||
- [finance.py](file://backend/app/models/finance.py#L45-L79)
|
||||
|
||||
## 架构概览
|
||||
|
||||
系统采用分层架构设计，确保业务逻辑与数据访问的分离：
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "表现层"
|
||||
Frontend[前端Vue应用]
|
||||
end
|
||||
subgraph "应用层"
|
||||
API[FastAPI路由]
|
||||
Services[业务服务]
|
||||
end
|
||||
subgraph "数据层"
|
||||
ORM[SQLAlchemy ORM]
|
||||
DB[(PostgreSQL数据库)]
|
||||
end
|
||||
Frontend --> API
|
||||
API --> Services
|
||||
Services --> ORM
|
||||
ORM --> DB
|
||||
subgraph "核心实体关系"
|
||||
Department --> Staff
|
||||
Staff --> Assessment
|
||||
Assessment --> AssessmentDetail
|
||||
AssessmentDetail --> Indicator
|
||||
Staff --> SalaryRecord
|
||||
Department --> DepartmentFinance
|
||||
PerformancePlan --> PlanKpiRelation
|
||||
IndicatorTemplate --> TemplateIndicator
|
||||
end
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [models.py](file://backend/app/models/models.py#L62-L438)
|
||||
- [finance.py](file://backend/app/models/finance.py#L45-L79)
|
||||
|
||||
## 详细实体分析
|
||||
|
||||
### Department - 科室实体
|
||||
|
||||
Department实体是整个系统的核心组织单元，支持多级嵌套的科室结构：
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class Department {
|
||||
+int id
|
||||
+string name
|
||||
+string code
|
||||
+DeptType dept_type
|
||||
+int parent_id
|
||||
+int level
|
||||
+int sort_order
|
||||
+bool is_active
|
||||
+string description
|
||||
+datetime created_at
|
||||
+datetime updated_at
|
||||
}
|
||||
class Staff {
|
||||
+int id
|
||||
+string employee_id
|
||||
+string name
|
||||
+int department_id
|
||||
+string position
|
||||
+string title
|
||||
+float base_salary
|
||||
+float performance_ratio
|
||||
+StaffStatus status
|
||||
+datetime hire_date
|
||||
}
|
||||
Department "1" o-- "N" Staff : "包含"
|
||||
Department "1" <-- "N" Department : "子科室"
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [models.py](file://backend/app/models/models.py#L62-L86)
|
||||
- [models.py](file://backend/app/models/models.py#L88-L115)
|
||||
|
||||
**业务逻辑**：
|
||||
- 支持多级科室嵌套（parent_id自关联）
|
||||
- 通过level字段维护层级关系
|
||||
- dept_type枚举定义了8种科室类型
|
||||
- 提供sort_order进行排序管理
|
||||
|
||||
**外键约束**：
|
||||
- parent_id -> departments.id (自关联)
|
||||
- 外键约束确保引用完整性
|
||||
|
||||
**索引设计**：
|
||||
- idx_dept_type: 加速科室类型查询
|
||||
- idx_dept_parent: 加速父子关系查询
|
||||
|
||||
### Staff - 员工实体
|
||||
|
||||
Staff实体管理所有员工信息，与Department形成一对多关系：
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class Staff {
|
||||
+int id
|
||||
+string employee_id
|
||||
+string name
|
||||
+int department_id
|
||||
+string position
|
||||
+string title
|
||||
+string phone
|
||||
+string email
|
||||
+float base_salary
|
||||
+float performance_ratio
|
||||
+StaffStatus status
|
||||
+datetime hire_date
|
||||
}
|
||||
class Assessment {
|
||||
+int id
|
||||
+int staff_id
|
||||
+int period_year
|
||||
+int period_month
|
||||
+float total_score
|
||||
+float weighted_score
|
||||
+AssessmentStatus status
|
||||
+int assessor_id
|
||||
+int reviewer_id
|
||||
}
|
||||
class SalaryRecord {
|
||||
+int id
|
||||
+int staff_id
|
||||
+int period_year
|
||||
+int period_month
|
||||
+float base_salary
|
||||
+float performance_score
|
||||
+float performance_bonus
|
||||
+float deduction
|
||||
+float allowance
|
||||
+float total_salary
|
||||
+string status
|
||||
}
|
||||
class User {
|
||||
+int id
|
||||
+string username
|
||||
+string password_hash
|
||||
+int staff_id
|
||||
+string role
|
||||
+bool is_active
|
||||
}
|
||||
Department --> Staff : "1 : N"
|
||||
Staff --> Assessment : "1 : N"
|
||||
Staff --> SalaryRecord : "1 : N"
|
||||
Staff --> User : "1 : 1"
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [models.py](file://backend/app/models/models.py#L88-L115)
|
||||
- [models.py](file://backend/app/models/models.py#L149-L179)
|
||||
- [models.py](file://backend/app/models/models.py#L205-L231)
|
||||
- [models.py](file://backend/app/models/models.py#L244-L261)
|
||||
|
||||
**业务逻辑**：
|
||||
- employee_id唯一标识员工身份
|
||||
- performance_ratio影响最终绩效奖金计算
|
||||
- status枚举管理员工生命周期状态
|
||||
- 与User实体建立一对一关系用于系统权限
|
||||
|
||||
**外键约束**：
|
||||
- department_id -> departments.id (强制约束)
|
||||
- staff_id (Assessment) -> staff.id (级联更新/删除)
|
||||
|
||||
**索引设计**：
|
||||
- idx_staff_dept: 加速科室员工查询
|
||||
- idx_staff_status: 加速状态过滤查询
|
||||
|
||||
### Assessment - 考核记录实体
|
||||
|
||||
Assessment实体管理完整的考核流程，包含多个角色参与：
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Employee as 员工
|
||||
participant Assessor as 考核人
|
||||
participant Reviewer as 审核人
|
||||
participant System as 系统
|
||||
Employee->>System : 创建考核记录
|
||||
System->>Assessor : 分配考核任务
|
||||
Assessor->>System : 填写考核结果
|
||||
System->>Reviewer : 提交审核
|
||||
Reviewer->>System : 审核通过/驳回
|
||||
System->>Employee : 通知考核结果
|
||||
System->>System : 生成工资记录
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [models.py](file://backend/app/models/models.py#L149-L179)
|
||||
- [assessments.py](file://backend/app/api/v1/assessments.py#L105-L146)
|
||||
|
||||
**业务逻辑**：
|
||||
- 支持草稿、已提交、已审核、已确认、已驳回等状态
|
||||
- assessor_id和reviewer_id允许同一人或不同人
|
||||
- 自动计算total_score和weighted_score
|
||||
- 与AssessmentDetail形成一对多关系
|
||||
|
||||
**外键约束**：
|
||||
- staff_id -> staff.id (RESTRICT)
|
||||
- assessor_id -> staff.id (SET NULL)
|
||||
- reviewer_id -> staff.id (SET NULL)
|
||||
|
||||
**级联操作**：
|
||||
- Assessment删除时，details自动删除 (DELETE-ORPHAN)
|
||||
|
||||
### AssessmentDetail - 考核明细实体
|
||||
|
||||
AssessmentDetail实体记录具体的指标得分：
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class AssessmentDetail {
|
||||
+int id
|
||||
+int assessment_id
|
||||
+int indicator_id
|
||||
+float actual_value
|
||||
+float score
|
||||
+string evidence
|
||||
+string remark
|
||||
}
|
||||
class Indicator {
|
||||
+int id
|
||||
+string name
|
||||
+string code
|
||||
+IndicatorType indicator_type
|
||||
+BSCDimension bs_dimension
|
||||
+float weight
|
||||
+float max_score
|
||||
+float target_value
|
||||
+string calculation_method
|
||||
+bool is_veto
|
||||
}
|
||||
Assessment --> AssessmentDetail : "1 : N"
|
||||
Indicator --> AssessmentDetail : "1 : N"
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [models.py](file://backend/app/models/models.py#L181-L203)
|
||||
- [models.py](file://backend/app/models/models.py#L117-L147)
|
||||
|
||||
**业务逻辑**：
|
||||
- 记录每个指标的实际值和计算得分
|
||||
- 支持证据材料上传
|
||||
- is_veto字段实现一票否决机制
|
||||
|
||||
**外键约束**：
|
||||
- assessment_id -> assessments.id (CASCADE DELETE)
|
||||
- indicator_id -> indicators.id (RESTRICT)
|
||||
|
||||
### Indicator - 指标实体
|
||||
|
||||
Indicator实体定义了完整的考核指标体系：
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class Indicator {
|
||||
+int id
|
||||
+string name
|
||||
+string code
|
||||
+IndicatorType indicator_type
|
||||
+BSCDimension bs_dimension
|
||||
+float weight
|
||||
+float max_score
|
||||
+float target_value
|
||||
+string target_unit
|
||||
+string calculation_method
|
||||
+string assessment_method
|
||||
+string deduction_standard
|
||||
+string data_source
|
||||
+string applicable_dept_types
|
||||
+bool is_veto
|
||||
+bool is_active
|
||||
}
|
||||
class AssessmentDetail {
|
||||
+int id
|
||||
+int assessment_id
|
||||
+int indicator_id
|
||||
+float actual_value
|
||||
+float score
|
||||
}
|
||||
Indicator --> AssessmentDetail : "1 : N"
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [models.py](file://backend/app/models/models.py#L117-L147)
|
||||
|
||||
**业务逻辑**：
|
||||
- 支持质量、数量、效率、服务、成本五种指标类型
|
||||
- BSC维度支持财务、客户、内部流程、学习与成长四个维度
|
||||
- applicable_dept_types存储适用科室类型的JSON数组
|
||||
- 支持复杂的计算方法和扣分标准
|
||||
|
||||
**约束条件**：
|
||||
- weight > 0 的检查约束
|
||||
- code唯一性约束
|
||||
|
||||
### SalaryRecord - 工资记录实体
|
||||
|
||||
SalaryRecord实体管理工资核算过程：
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([开始工资核算]) --> CheckAssessment["检查是否存在已确认的考核记录"]
|
||||
CheckAssessment --> HasAssessment{"存在已确认考核？"}
|
||||
HasAssessment --> |否| Error["返回错误：未找到已确认的考核记录"]
|
||||
HasAssessment --> |是| CheckExisting["检查是否已存在工资记录"]
|
||||
CheckExisting --> HasExisting{"已存在工资记录？"}
|
||||
HasExisting --> |是| Error
|
||||
HasExisting --> |否| Calculate["计算各项工资项目"]
|
||||
Calculate --> Generate["生成工资记录"]
|
||||
Generate --> Confirm["设置状态为已确认"]
|
||||
Confirm --> End([完成])
|
||||
Error --> End
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [models.py](file://backend/app/models/models.py#L205-L231)
|
||||
- [salary.py](file://backend/app/api/v1/salary.py#L96-L111)
|
||||
|
||||
**业务逻辑**：
|
||||
- 基于考核结果计算绩效奖金
|
||||
- 支持批量生成功能
|
||||
- 与Assessment形成间接关联关系
|
||||
|
||||
**外键约束**：
|
||||
- staff_id -> staff.id (RESTRICT)
|
||||
|
||||
### PerformancePlan - 绩效计划实体
|
||||
|
||||
PerformancePlan实体管理多层次的绩效计划：
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class PerformancePlan {
|
||||
+int id
|
||||
+string plan_name
|
||||
+string plan_code
|
||||
+PlanLevel plan_level
|
||||
+int plan_year
|
||||
+int plan_month
|
||||
+string plan_type
|
||||
+int department_id
|
||||
+int staff_id
|
||||
+int parent_plan_id
|
||||
+string description
|
||||
+string strategic_goals
|
||||
+string key_initiatives
|
||||
+PlanStatus status
|
||||
+int submitter_id
|
||||
+int approver_id
|
||||
+int version
|
||||
+bool is_active
|
||||
}
|
||||
class PlanKpiRelation {
|
||||
+int id
|
||||
+int plan_id
|
||||
+int indicator_id
|
||||
+float target_value
|
||||
+string target_unit
|
||||
+float weight
|
||||
+string scoring_method
|
||||
+string scoring_params
|
||||
}
|
||||
PerformancePlan --> PlanKpiRelation : "1 : N"
|
||||
PerformancePlan --> PerformancePlan : "1 : N (父子计划)"
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [models.py](file://backend/app/models/models.py#L270-L312)
|
||||
- [models.py](file://backend/app/models/models.py#L314-L339)
|
||||
|
||||
**业务逻辑**：
|
||||
- 支持医院级、科室级、个人级三个层级
|
||||
- 支持年度和月度两种计划类型
|
||||
- parent_plan_id实现计划的层次化管理
|
||||
|
||||
**外键约束**：
|
||||
- department_id -> departments.id (SET NULL)
|
||||
- staff_id -> staff.id (SET NULL)
|
||||
- parent_plan_id -> performance_plans.id (SET NULL)
|
||||
|
||||
### IndicatorTemplate & TemplateIndicator - 模板实体
|
||||
|
||||
模板系统支持按科室类型预设指标组合：
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class IndicatorTemplate {
|
||||
+int id
|
||||
+string template_name
|
||||
+string template_code
|
||||
+TemplateType template_type
|
||||
+string description
|
||||
+string dimension_weights
|
||||
+string assessment_cycle
|
||||
+bool is_active
|
||||
}
|
||||
class TemplateIndicator {
|
||||
+int id
|
||||
+int template_id
|
||||
+int indicator_id
|
||||
+string category
|
||||
+float target_value
|
||||
+string target_unit
|
||||
+float weight
|
||||
+string scoring_method
|
||||
+string scoring_params
|
||||
+int sort_order
|
||||
}
|
||||
IndicatorTemplate --> TemplateIndicator : "1 : N"
|
||||
TemplateIndicator --> Indicator : "M : N"
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [models.py](file://backend/app/models/models.py#L387-L409)
|
||||
- [models.py](file://backend/app/models/models.py#L411-L438)
|
||||
|
||||
**业务逻辑**：
|
||||
- 按科室类型提供标准化的指标模板
|
||||
- 支持维度权重配置
|
||||
- sort_order控制指标显示顺序
|
||||
|
||||
**约束条件**：
|
||||
- template_code唯一性
|
||||
- template_id + indicator_id唯一性组合
|
||||
|
||||
### DepartmentFinance - 科室财务实体
|
||||
|
||||
DepartmentFinance实体管理科室财务数据：
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class DepartmentFinance {
|
||||
+int id
|
||||
+int department_id
|
||||
+int period_year
|
||||
+int period_month
|
||||
+FinanceType finance_type
|
||||
+string category
|
||||
+float amount
|
||||
+string source
|
||||
+string remark
|
||||
}
|
||||
class Department {
|
||||
+int id
|
||||
+string name
|
||||
+string code
|
||||
+DeptType dept_type
|
||||
}
|
||||
Department --> DepartmentFinance : "1 : N"
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [finance.py](file://backend/app/models/finance.py#L45-L75)
|
||||
|
||||
**业务逻辑**：
|
||||
- 支持收入和支出两类财务记录
|
||||
- category字段区分具体财务项目
|
||||
- amount字段强制非负数
|
||||
|
||||
**约束条件**：
|
||||
- amount >= 0 的检查约束
|
||||
- 复合索引优化查询性能
|
||||
|
||||
## 依赖关系分析
|
||||
|
||||
系统实体间存在复杂的依赖关系，通过外键约束确保数据一致性：
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "组织架构依赖"
|
||||
Department --> Staff
|
||||
Staff --> Assessment
|
||||
Assessment --> AssessmentDetail
|
||||
AssessmentDetail --> Indicator
|
||||
end
|
||||
subgraph "计划管理依赖"
|
||||
PerformancePlan --> PlanKpiRelation
|
||||
PlanKpiRelation --> Indicator
|
||||
PerformancePlan --> PerformancePlan
|
||||
end
|
||||
subgraph "模板系统依赖"
|
||||
IndicatorTemplate --> TemplateIndicator
|
||||
TemplateIndicator --> Indicator
|
||||
end
|
||||
subgraph "财务关联依赖"
|
||||
Department --> DepartmentFinance
|
||||
Staff --> SalaryRecord
|
||||
end
|
||||
subgraph "用户系统依赖"
|
||||
Staff --> User
|
||||
PerformancePlan --> User
|
||||
end
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [models.py](file://backend/app/models/models.py#L62-L438)
|
||||
- [finance.py](file://backend/app/models/finance.py#L45-L79)
|
||||
|
||||
**外键约束策略**：
|
||||
- 强制约束：department_id, staff_id, indicator_id
|
||||
- 级联约束：Assessment删除时自动删除AssessmentDetail
|
||||
- 设置为空：staff_id在User中可为空，便于用户与员工解耦
|
||||
|
||||
**级联操作配置**：
|
||||
- Assessment.cascade(delete-orphan): 删除Assessment时自动清理明细
|
||||
- PlanKpiRelation.cascade(delete-orphan): 删除计划时清理指标关联
|
||||
- 多对多关系通过中间表实现，避免复杂的级联操作
|
||||
|
||||
## 性能考虑
|
||||
|
||||
系统在设计时充分考虑了性能优化：
|
||||
|
||||
### 索引策略
|
||||
- 复合索引优化常用查询模式
|
||||
- 枚举字段建立独立索引
|
||||
- 时间字段建立范围查询索引
|
||||
|
||||
### 查询优化
|
||||
- 使用selectinload减少N+1查询问题
|
||||
- 合理的连接策略避免笛卡尔积
|
||||
- 分页查询限制结果集大小
|
||||
|
||||
### 缓存策略
|
||||
- 配置数据库连接池
|
||||
- 异步查询提升并发性能
|
||||
- 合理的事务管理避免锁竞争
|
||||
|
||||
## 故障排除指南
|
||||
|
||||
### 常见问题及解决方案
|
||||
|
||||
**1. 外键约束冲突**
|
||||
- 症状：插入或更新数据时报外键约束错误
|
||||
- 解决：检查关联实体是否存在且状态有效
|
||||
- 预防：在业务层先验证关联关系
|
||||
|
||||
**2. 数据重复问题**
|
||||
- 症状：唯一约束冲突
|
||||
- 解决：检查employee_id、code、template_code等唯一字段
|
||||
- 预防：在创建前进行唯一性检查
|
||||
|
||||
**3. 级联删除问题**
|
||||
- 症状：删除主记录时意外删除相关数据
|
||||
- 解决：检查cascade配置，必要时调整为RESTRICT
|
||||
- 预防：在删除前确认级联影响范围
|
||||
|
||||
**4. 性能问题**
|
||||
- 症状：查询响应缓慢
|
||||
- 解决：检查索引使用情况，优化查询条件
|
||||
- 预防：定期分析查询执行计划
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L144-L146)
|
||||
- [finance.py](file://backend/app/models/finance.py#L73-L74)
|
||||
|
||||
## 结论
|
||||
|
||||
本实体关系设计文档全面阐述了医院绩效系统的数据模型架构。系统采用规范化的数据库设计，通过合理的实体划分和关系映射，实现了以下目标：
|
||||
|
||||
1. **业务完整性**：完整覆盖医院绩效管理的各个业务环节
|
||||
2. **数据一致性**：通过外键约束和级联操作确保数据完整性
|
||||
3. **扩展性**：支持多层级组织架构和灵活的指标模板系统
|
||||
4. **性能优化**：合理的索引设计和查询策略
|
||||
5. **安全性**：通过用户权限管理和数据访问控制
|
||||
|
||||
该设计为后续的功能扩展和系统维护奠定了坚实的基础，能够满足医院绩效管理的复杂业务需求。
|
||||
599
.qoder/repowiki/zh/content/数据库设计/数据字典/基础数据字段.md
Normal file
599
.qoder/repowiki/zh/content/数据库设计/数据字典/基础数据字段.md
Normal file
@@ -0,0 +1,599 @@
|
||||
# 基础数据字段
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [models.py](file://backend/app/models/models.py)
|
||||
- [finance.py](file://backend/app/models/finance.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)
|
||||
- [database.md](file://docs/database.md)
|
||||
- [departments.py](file://backend/app/api/v1/departments.py)
|
||||
- [staff.py](file://backend/app/api/v1/staff.py)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖分析](#依赖分析)
|
||||
7. [性能考量](#性能考量)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
本文件聚焦于基础数据字段的详细数据字典，覆盖以下核心表：
|
||||
- 科室信息表（Department）
|
||||
- 员工信息表（Staff）
|
||||
- 用户表（User）
|
||||
|
||||
同时补充与基础数据强相关的财务记录表（DepartmentFinance）字段说明，以及与字段相关的枚举类型、索引设计、约束与业务规则。文档提供字段定义、类型与长度、空值与默认值、业务含义、取值范围、注释说明、业务规则约束、字段间关联关系与外键约束、索引设计与性能考虑，并给出实际使用示例与最佳实践建议。
|
||||
|
||||
## 项目结构
|
||||
本项目采用前后端分离架构，后端基于 FastAPI + SQLAlchemy ORM，数据库迁移使用 Alembic。基础数据模型集中在 models 模块，API 路由位于 app/api/v1 下，数据字典与 ER 图见 docs/database.md。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "后端"
|
||||
A["models.py<br/>数据模型"]
|
||||
B["finance.py<br/>财务模型"]
|
||||
C["schemas.py<br/>Pydantic模式"]
|
||||
D["alembic 迁移<br/>001_initial.py / 002_template.py"]
|
||||
E["API 路由<br/>departments.py / staff.py"]
|
||||
end
|
||||
subgraph "文档"
|
||||
F["docs/database.md<br/>ER图与字段说明"]
|
||||
end
|
||||
A --> D
|
||||
B --> D
|
||||
C --> E
|
||||
E --> A
|
||||
F --> A
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [models.py](file://backend/app/models/models.py#L62-L114)
|
||||
- [finance.py](file://backend/app/models/finance.py#L45-L74)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L64-L149)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L22-L64)
|
||||
- [002_template.py](file://backend/alembic/versions/002_template.py#L21-L91)
|
||||
- [departments.py](file://backend/app/api/v1/departments.py#L17-L108)
|
||||
- [staff.py](file://backend/app/api/v1/staff.py#L17-L124)
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L62-L114)
|
||||
- [finance.py](file://backend/app/models/finance.py#L45-L74)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L64-L149)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L22-L64)
|
||||
- [002_template.py](file://backend/alembic/versions/002_template.py#L21-L91)
|
||||
- [database.md](file://docs/database.md#L97-L232)
|
||||
- [departments.py](file://backend/app/api/v1/departments.py#L17-L108)
|
||||
- [staff.py](file://backend/app/api/v1/staff.py#L17-L124)
|
||||
|
||||
## 核心组件
|
||||
- 科室信息表（Department）
|
||||
- 员工信息表（Staff）
|
||||
- 用户表（User）
|
||||
- 科室财务记录表（DepartmentFinance）
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L62-L114)
|
||||
- [models.py](file://backend/app/models/models.py#L244-L261)
|
||||
- [finance.py](file://backend/app/models/finance.py#L45-L74)
|
||||
|
||||
## 架构总览
|
||||
基础数据字段与业务流程的关系如下：
|
||||
- Department 与 Staff 为 1:N 关系（部门-员工）
|
||||
- Staff 与 User 为 N:1 关系（员工-用户）
|
||||
- DepartmentFinance 与 Department 为 1:N 关系（科室-财务记录）
|
||||
|
||||
```mermaid
|
||||
erDiagram
|
||||
DEPARTMENTS {
|
||||
int id PK
|
||||
string name
|
||||
string code UK
|
||||
enum dept_type
|
||||
int parent_id FK
|
||||
int level
|
||||
int sort_order
|
||||
boolean is_active
|
||||
text description
|
||||
datetime created_at
|
||||
datetime updated_at
|
||||
}
|
||||
STAFF {
|
||||
int id PK
|
||||
string employee_id UK
|
||||
string name
|
||||
int department_id FK
|
||||
string position
|
||||
string title
|
||||
string phone
|
||||
string email
|
||||
decimal base_salary
|
||||
decimal 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
|
||||
boolean is_active
|
||||
datetime last_login
|
||||
datetime created_at
|
||||
datetime updated_at
|
||||
}
|
||||
DEPARTMENT_FINANCES {
|
||||
int id PK
|
||||
int department_id FK
|
||||
int period_year
|
||||
int period_month
|
||||
enum finance_type
|
||||
string category
|
||||
decimal amount
|
||||
string source
|
||||
text remark
|
||||
datetime created_at
|
||||
datetime updated_at
|
||||
}
|
||||
DEPARTMENTS ||--o{ STAFF : "1:N"
|
||||
STAFF ||--o{ USERS : "N:1"
|
||||
DEPARTMENTS ||--o{ DEPARTMENT_FINANCES : "1:N"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [models.py](file://backend/app/models/models.py#L62-L114)
|
||||
- [models.py](file://backend/app/models/models.py#L244-L261)
|
||||
- [finance.py](file://backend/app/models/finance.py#L45-L74)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L22-L64)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 科室信息表（Department）
|
||||
- 表名：departments
|
||||
- 主键：id（自增整数）
|
||||
- 唯一键：code（唯一）
|
||||
- 外键：parent_id 引用 departments.id（自关联，表示上级科室）
|
||||
- 索引：idx_dept_type、idx_dept_parent
|
||||
- 枚举：dept_type（来自 DeptType）
|
||||
|
||||
字段定义与规则
|
||||
- id
|
||||
- 类型：整数（主键）
|
||||
- 约束：自增、非空
|
||||
- 默认值：无
|
||||
- 业务含义：科室唯一标识
|
||||
- 取值范围：正整数
|
||||
- 注释：主键
|
||||
- 关联关系：parent_id 自关联指向自身
|
||||
- 索引：PK
|
||||
- name
|
||||
- 类型：字符串（最大长度 100）
|
||||
- 约束：非空
|
||||
- 默认值：无
|
||||
- 业务含义：科室名称
|
||||
- 取值范围：长度不超过 100
|
||||
- 注释：科室名称
|
||||
- code
|
||||
- 类型：字符串（最大长度 20）
|
||||
- 约束：唯一、非空
|
||||
- 默认值：无
|
||||
- 业务含义：科室编码（全局唯一）
|
||||
- 取值范围：长度不超过 20
|
||||
- 注释：科室编码
|
||||
- 索引：UK
|
||||
- dept_type
|
||||
- 类型：枚举（DeptType）
|
||||
- 约束：非空
|
||||
- 默认值：无
|
||||
- 业务含义：科室类型
|
||||
- 取值范围：clinical_surgical、clinical_nonsurgical_ward、clinical_nonsurgical_noward、medical_tech、medical_auxiliary、nursing、admin、finance、logistics
|
||||
- 注释：科室类型
|
||||
- 索引：idx_dept_type
|
||||
- parent_id
|
||||
- 类型：整数
|
||||
- 约束：可空，外键引用 departments.id
|
||||
- 默认值：空
|
||||
- 业务含义：上级科室 ID（自关联）
|
||||
- 取值范围：对应存在的 id 或空
|
||||
- 注释：上级科室
|
||||
- 索引：idx_dept_parent
|
||||
- level
|
||||
- 类型：整数
|
||||
- 约束：默认 1
|
||||
- 默认值：1
|
||||
- 业务含义：层级（1-5）
|
||||
- 取值范围：1-5
|
||||
- 注释：层级
|
||||
- sort_order
|
||||
- 类型：整数
|
||||
- 约束：默认 0
|
||||
- 默认值：0
|
||||
- 业务含义：排序
|
||||
- 注释：排序
|
||||
- is_active
|
||||
- 类型：布尔
|
||||
- 约束：默认 true
|
||||
- 默认值：true
|
||||
- 业务含义：是否启用
|
||||
- 注释：是否启用
|
||||
- description
|
||||
- 类型：文本
|
||||
- 约束：可空
|
||||
- 默认值：空
|
||||
- 业务含义：描述
|
||||
- 注释：描述
|
||||
- created_at / updated_at
|
||||
- 类型：日期时间
|
||||
- 约束：默认当前时间；更新时自动更新
|
||||
- 默认值：无
|
||||
- 业务含义：创建/更新时间
|
||||
- 注释：创建时间、更新时间
|
||||
|
||||
业务规则与最佳实践
|
||||
- 编码唯一性：code 必须全局唯一，新增前需校验重复
|
||||
- 层级与排序：level 与 sort_order 用于树形展示与排序
|
||||
- 自关联：parent_id 支持多级组织架构，查询时注意避免环路
|
||||
- 索引：dept_type 与 parent_id 建议在过滤与树形查询中使用
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L62-L86)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L22-L41)
|
||||
- [database.md](file://docs/database.md#L99-L116)
|
||||
|
||||
### 员工信息表（Staff）
|
||||
- 表名：staff
|
||||
- 主键：id（自增整数）
|
||||
- 唯一键：employee_id（唯一）
|
||||
- 外键：department_id 引用 departments.id
|
||||
- 索引：idx_staff_dept、idx_staff_status
|
||||
- 枚举：status（来自 StaffStatus）
|
||||
|
||||
字段定义与规则
|
||||
- id
|
||||
- 类型：整数（主键）
|
||||
- 约束：自增、非空
|
||||
- 默认值：无
|
||||
- 业务含义：员工唯一标识
|
||||
- 注释：主键
|
||||
- employee_id
|
||||
- 类型：字符串（最大长度 20）
|
||||
- 约束：唯一、非空
|
||||
- 默认值：无
|
||||
- 业务含义：工号（唯一）
|
||||
- 取值范围：长度不超过 20
|
||||
- 注释：工号
|
||||
- 索引：UK
|
||||
- name
|
||||
- 类型：字符串（最大长度 50）
|
||||
- 约束：非空
|
||||
- 默认值：无
|
||||
- 业务含义：姓名
|
||||
- 取值范围：长度不超过 50
|
||||
- 注释：姓名
|
||||
- department_id
|
||||
- 类型：整数
|
||||
- 约束：非空，外键引用 departments.id
|
||||
- 默认值：无
|
||||
- 业务含义：所属科室
|
||||
- 注释：所属科室
|
||||
- 索引：idx_staff_dept
|
||||
- position
|
||||
- 类型：字符串（最大长度 50）
|
||||
- 约束：非空
|
||||
- 默认值：无
|
||||
- 业务含义：职位
|
||||
- 取值范围：长度不超过 50
|
||||
- 注释：职位
|
||||
- title
|
||||
- 类型：字符串（最大长度 50）
|
||||
- 约束：可空
|
||||
- 默认值：空
|
||||
- 业务含义：职称
|
||||
- 注释：职称
|
||||
- phone
|
||||
- 类型：字符串（最大长度 20）
|
||||
- 约束：可空
|
||||
- 默认值：空
|
||||
- 业务含义：联系电话
|
||||
- 注释：联系电话
|
||||
- email
|
||||
- 类型：字符串（最大长度 100）
|
||||
- 约束：可空
|
||||
- 默认值：空
|
||||
- 业务含义：邮箱
|
||||
- 注释：邮箱
|
||||
- base_salary
|
||||
- 类型：数值（精度 10，小数 2）
|
||||
- 约束：默认 0
|
||||
- 默认值：0
|
||||
- 业务含义：基本工资
|
||||
- 取值范围：≥0
|
||||
- 注释：基本工资
|
||||
- performance_ratio
|
||||
- 类型：数值（精度 5，小数 2）
|
||||
- 约束：默认 1.0
|
||||
- 默认值：1.0
|
||||
- 业务含义：绩效系数（0-5）
|
||||
- 取值范围：0-5
|
||||
- 注释：绩效系数
|
||||
- status
|
||||
- 类型：枚举（StaffStatus）
|
||||
- 约束：默认 active
|
||||
- 默认值：active
|
||||
- 业务含义：员工状态
|
||||
- 取值范围：active、leave、resigned、retired
|
||||
- 注释：状态
|
||||
- 索引：idx_staff_status
|
||||
- hire_date
|
||||
- 类型：日期时间
|
||||
- 约束：可空
|
||||
- 默认值：空
|
||||
- 业务含义：入职日期
|
||||
- 注释：入职日期
|
||||
- created_at / updated_at
|
||||
- 类型：日期时间
|
||||
- 约束：默认当前时间；更新时自动更新
|
||||
- 默认值：无
|
||||
- 业务含义：创建/更新时间
|
||||
- 注释：创建时间、更新时间
|
||||
|
||||
业务规则与最佳实践
|
||||
- 工号唯一性：employee_id 必须唯一，新增前需校验重复
|
||||
- 状态枚举：仅允许枚举值，避免脏数据
|
||||
- 薪资与系数：base_salary 与 performance_ratio 用于后续绩效工资计算
|
||||
- 索引：department_id 与 status 用于筛选与分页
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L88-L114)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L42-L64)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L107-L149)
|
||||
- [database.md](file://docs/database.md#L117-L136)
|
||||
|
||||
### 用户表（User）
|
||||
- 表名：users
|
||||
- 主键：id（自增整数）
|
||||
- 唯一键：username（唯一）
|
||||
- 外键：staff_id 引用 staff.id
|
||||
- 索引：idx_user_username
|
||||
|
||||
字段定义与规则
|
||||
- id
|
||||
- 类型：整数（主键）
|
||||
- 约束：自增、非空
|
||||
- 默认值：无
|
||||
- 业务含义：用户唯一标识
|
||||
- 注释：主键
|
||||
- username
|
||||
- 类型：字符串（最大长度 50）
|
||||
- 约束：唯一、非空
|
||||
- 默认值：无
|
||||
- 业务含义：用户名
|
||||
- 取值范围：长度不超过 50
|
||||
- 注释：用户名
|
||||
- 索引：UK
|
||||
- password_hash
|
||||
- 类型：字符串（最大长度 255）
|
||||
- 约束：非空
|
||||
- 默认值：无
|
||||
- 业务含义：密码哈希
|
||||
- 注释：密码哈希
|
||||
- staff_id
|
||||
- 类型：整数
|
||||
- 约束：可空，外键引用 staff.id
|
||||
- 默认值：空
|
||||
- 业务含义：关联员工
|
||||
- 注释：关联员工
|
||||
- role
|
||||
- 类型：字符串（最大长度 20）
|
||||
- 约束：默认 staff
|
||||
- 默认值：staff
|
||||
- 业务含义：角色
|
||||
- 取值范围：admin、manager、staff
|
||||
- 注释：角色
|
||||
- is_active
|
||||
- 类型：布尔
|
||||
- 约束：默认 true
|
||||
- 默认值：true
|
||||
- 业务含义：是否启用
|
||||
- 注释：是否启用
|
||||
- last_login
|
||||
- 类型：日期时间
|
||||
- 约束：可空
|
||||
- 默认值：空
|
||||
- 业务含义：最后登录时间
|
||||
- 注释：最后登录
|
||||
- created_at / updated_at
|
||||
- 类型：日期时间
|
||||
- 约束：默认当前时间；更新时自动更新
|
||||
- 默认值：无
|
||||
- 业务含义：创建/更新时间
|
||||
- 注释：创建时间、更新时间
|
||||
|
||||
业务规则与最佳实践
|
||||
- 用户名唯一性：username 必须唯一
|
||||
- 角色枚举：仅允许 admin、manager、staff
|
||||
- 关联员工：staff_id 可空，表示未绑定员工的系统用户
|
||||
- 登录追踪：last_login 用于审计与安全策略
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L244-L261)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L156-L172)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L314-L345)
|
||||
- [database.md](file://docs/database.md#L218-L232)
|
||||
|
||||
### 科室财务记录表（DepartmentFinance）
|
||||
- 表名：department_finances
|
||||
- 主键：id（自增整数）
|
||||
- 外键：department_id 引用 departments.id
|
||||
- 索引：idx_finance_dept、idx_finance_period、idx_finance_type、idx_finance_category
|
||||
- 枚举：finance_type（来自 FinanceType）
|
||||
- 约束：amount ≥ 0
|
||||
|
||||
字段定义与规则
|
||||
- id
|
||||
- 类型：整数（主键）
|
||||
- 约束：自增、非空
|
||||
- 默认值：无
|
||||
- 业务含义：财务记录唯一标识
|
||||
- 注释：主键
|
||||
- department_id
|
||||
- 类型：整数
|
||||
- 约束：非空，外键引用 departments.id
|
||||
- 默认值：无
|
||||
- 业务含义：所属科室
|
||||
- 注释：科室ID
|
||||
- 索引：idx_finance_dept
|
||||
- period_year / period_month
|
||||
- 类型：整数
|
||||
- 约束：非空
|
||||
- 默认值：无
|
||||
- 业务含义：年度/月份
|
||||
- 注释：年度、月份
|
||||
- 索引：idx_finance_period
|
||||
- finance_type
|
||||
- 类型：枚举（FinanceType）
|
||||
- 约束：非空
|
||||
- 默认值：无
|
||||
- 业务含义：财务类型（收入/支出）
|
||||
- 取值范围：revenue、expense
|
||||
- 注释：财务类型
|
||||
- 索引：idx_finance_type
|
||||
- category
|
||||
- 类型：字符串（最大长度 50）
|
||||
- 约束：非空
|
||||
- 默认值：无
|
||||
- 业务含义：类别（如检查费、床位费等）
|
||||
- 取值范围：长度不超过 50
|
||||
- 注释：类别
|
||||
- 索引：idx_finance_category
|
||||
- amount
|
||||
- 类型：数值（精度 12，小数 2）
|
||||
- 约束：默认 0，且 ≥ 0
|
||||
- 默认值：0
|
||||
- 业务含义：金额
|
||||
- 取值范围：≥0
|
||||
- 注释：金额
|
||||
- 约束：check(amount >= 0)
|
||||
- source
|
||||
- 类型：字符串（最大长度 100）
|
||||
- 约束：可空
|
||||
- 默认值：空
|
||||
- 业务含义：数据来源
|
||||
- 注释：数据来源
|
||||
- remark
|
||||
- 类型：文本
|
||||
- 约束：可空
|
||||
- 默认值：空
|
||||
- 业务含义：备注
|
||||
- 注释：备注
|
||||
- created_at / updated_at
|
||||
- 类型：日期时间
|
||||
- 约束：默认当前时间；更新时自动更新
|
||||
- 默认值：无
|
||||
- 业务含义：创建/更新时间
|
||||
- 注释：创建时间、更新时间
|
||||
|
||||
业务规则与最佳实践
|
||||
- 金额非负：通过约束保证 amount ≥ 0
|
||||
- 类别与类型：category 与 finance_type 组合用于财务归类与统计
|
||||
- 周期聚合：period_year 与 period_month 用于月度/年度汇总
|
||||
|
||||
章节来源
|
||||
- [finance.py](file://backend/app/models/finance.py#L45-L74)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L133-L154)
|
||||
|
||||
## 依赖分析
|
||||
- Department 与 Staff 的关系：1:N（部门-员工），通过 department_id 外键关联
|
||||
- Staff 与 User 的关系：N:1（员工-用户），通过 staff_id 外键关联
|
||||
- Department 与 DepartmentFinance 的关系：1:N（科室-财务记录），通过 department_id 外键关联
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
DEPT["Department"] --> |FK| STAFF["Staff"]
|
||||
STAFF --> |FK| USER["User"]
|
||||
DEPT --> |FK| FIN["DepartmentFinance"]
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [models.py](file://backend/app/models/models.py#L62-L114)
|
||||
- [models.py](file://backend/app/models/models.py#L244-L261)
|
||||
- [finance.py](file://backend/app/models/finance.py#L45-L74)
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L62-L114)
|
||||
- [models.py](file://backend/app/models/models.py#L244-L261)
|
||||
- [finance.py](file://backend/app/models/finance.py#L45-L74)
|
||||
|
||||
## 性能考量
|
||||
- 索引设计
|
||||
- Department：idx_dept_type、idx_dept_parent，适合按类型过滤与树形查询
|
||||
- Staff：idx_staff_dept、idx_staff_status，适合按科室与状态筛选
|
||||
- Assessments：idx_assessment_staff、idx_assessment_period、idx_assessment_status，适合按员工、周期与状态查询
|
||||
- SalaryRecords：idx_salary_staff、idx_salary_period，适合按员工与周期查询
|
||||
- Users：idx_user_username，适合按用户名登录
|
||||
- DepartmentFinance：idx_finance_dept、idx_finance_period、idx_finance_type、idx_finance_category，适合财务统计与聚合
|
||||
- 约束与校验
|
||||
- Staff.performance_ratio 与 Indicator.weight 使用 Pydantic 校验（ge/le），数据库层使用 CheckConstraint（如 DepartmentFinance.amount ≥ 0）
|
||||
- 查询建议
|
||||
- 分页与过滤：优先使用带索引的列进行 where 条件与 order by
|
||||
- 树形查询：Department.parent_id + level 用于层级展示
|
||||
- 聚合统计：DepartmentFinance 按 period_year/month + category + type 聚合
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L82-L86)
|
||||
- [models.py](file://backend/app/models/models.py#L111-L114)
|
||||
- [models.py](file://backend/app/models/models.py#L174-L178)
|
||||
- [models.py](file://backend/app/models/models.py#L227-L230)
|
||||
- [models.py](file://backend/app/models/models.py#L258-L260)
|
||||
- [finance.py](file://backend/app/models/finance.py#L68-L74)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L117-L136)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L158-L176)
|
||||
|
||||
## 故障排查指南
|
||||
- 新增科室失败（编码重复）
|
||||
- 现象：创建接口返回错误，提示编码已存在
|
||||
- 排查：检查 departments.code 是否唯一；确认是否已有相同编码
|
||||
- 处理：修改编码或删除冲突记录
|
||||
- 新增员工失败（工号重复）
|
||||
- 现象：创建接口返回错误，提示工号已存在
|
||||
- 排查：检查 staff.employee_id 是否唯一
|
||||
- 处理：修改工号或删除冲突记录
|
||||
- 删除科室失败（存在子科室）
|
||||
- 现象：删除接口返回错误，提示无法删除
|
||||
- 排查：确认该科室是否存在子科室（parent_id 指向该 id）
|
||||
- 处理：先删除子科室或调整组织架构
|
||||
- 薪资/财务金额异常
|
||||
- 现象：DepartmentFinance.amount 出现负值
|
||||
- 排查：检查数据来源与业务逻辑；确认约束是否生效
|
||||
- 处理：修正数据或调整业务流程
|
||||
|
||||
章节来源
|
||||
- [departments.py](file://backend/app/api/v1/departments.py#L74-L77)
|
||||
- [staff.py](file://backend/app/api/v1/staff.py#L75-L78)
|
||||
- [departments.py](file://backend/app/api/v1/departments.py#L104-L106)
|
||||
- [finance.py](file://backend/app/models/finance.py#L73-L74)
|
||||
|
||||
## 结论
|
||||
本文档对基础数据字段进行了系统梳理，明确了字段类型、长度、空值与默认值、业务含义、取值范围、注释说明、业务规则约束、外键关系与索引设计，并提供了性能考量与故障排查建议。遵循这些字段规范与最佳实践，有助于确保数据一致性、查询性能与业务稳定性。
|
||||
|
||||
## 附录
|
||||
- 字段使用示例（示意）
|
||||
- 新增科室：提供 name、code、dept_type、parent_id、level、sort_order、is_active、description
|
||||
- 新增员工：提供 employee_id、name、department_id、position、title、phone、email、base_salary、performance_ratio、status、hire_date
|
||||
- 新增用户：提供 username、password_hash、staff_id、role、is_active、last_login
|
||||
- 新增财务记录：提供 department_id、finance_type、category、amount、period_year、period_month、source、remark
|
||||
- 最佳实践
|
||||
- 唯一性：严格维护 code 与 employee_id 的唯一性
|
||||
- 枚举：统一使用模型中定义的枚举类型，避免拼写差异
|
||||
- 索引：在高频查询列上保持索引，定期评估查询计划
|
||||
- 校验：前端与后端双重校验，确保数据质量
|
||||
473
.qoder/repowiki/zh/content/数据库设计/数据字典/指标模板字段.md
Normal file
473
.qoder/repowiki/zh/content/数据库设计/数据字典/指标模板字段.md
Normal file
@@ -0,0 +1,473 @@
|
||||
# 指标模板字段
|
||||
|
||||
<cite>
|
||||
**本文档引用的文件**
|
||||
- [models.py](file://backend/app/models/models.py)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py)
|
||||
- [templates.py](file://backend/app/api/v1/templates.py)
|
||||
- [template_service.py](file://backend/app/services/template_service.py)
|
||||
- [002_template.py](file://backend/alembic/versions/002_template.py)
|
||||
- [init_templates.py](file://backend/app/scripts/init_templates.py)
|
||||
- [init_indicator_templates.py](file://backend/init_indicator_templates.py)
|
||||
- [Templates.vue](file://frontend/src/views/basic/Templates.vue)
|
||||
- [template.js](file://frontend/src/api/template.js)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖分析](#依赖分析)
|
||||
7. [性能考虑](#性能考虑)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
|
||||
## 简介
|
||||
本文件聚焦于指标模板相关字段的数据字典，覆盖以下核心实体与关系：
|
||||
- 指标模板表（IndicatorTemplate）
|
||||
- 模板指标关联表（TemplateIndicator）
|
||||
- 模板类型枚举（TemplateType）
|
||||
- 指标与模板的多对多关联关系
|
||||
- 维度权重配置与指标分类管理
|
||||
- 模板版本管理与继承关系设计
|
||||
- 激活状态与使用范围约束
|
||||
|
||||
本文件同时提供字段定义、约束说明、数据流向与前后端交互示例，帮助开发者与运维人员快速理解与使用模板系统。
|
||||
|
||||
## 项目结构
|
||||
模板系统由后端模型与服务、API路由、前端页面与接口组成，形成“模型-服务-接口-视图”的完整链路。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "后端"
|
||||
M["models.py<br/>数据模型"]
|
||||
S["template_service.py<br/>服务层"]
|
||||
A["templates.py<br/>API路由"]
|
||||
SC["schemas.py<br/>Pydantic模式"]
|
||||
ALEMBIC["002_template.py<br/>迁移脚本"]
|
||||
end
|
||||
subgraph "前端"
|
||||
V["Templates.vue<br/>模板管理页面"]
|
||||
API["template.js<br/>模板API封装"]
|
||||
end
|
||||
V --> API
|
||||
API --> A
|
||||
A --> S
|
||||
S --> M
|
||||
M --> ALEMBIC
|
||||
SC --> A
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [models.py](file://backend/app/models/models.py#L387-L438)
|
||||
- [template_service.py](file://backend/app/services/template_service.py#L20-L293)
|
||||
- [templates.py](file://backend/app/api/v1/templates.py#L1-L272)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L640-L743)
|
||||
- [002_template.py](file://backend/alembic/versions/002_template.py#L21-L96)
|
||||
- [Templates.vue](file://frontend/src/views/basic/Templates.vue#L1-L638)
|
||||
- [template.js](file://frontend/src/api/template.js#L1-L62)
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L387-L438)
|
||||
- [templates.py](file://backend/app/api/v1/templates.py#L1-L272)
|
||||
- [template_service.py](file://backend/app/services/template_service.py#L20-L293)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L640-L743)
|
||||
- [002_template.py](file://backend/alembic/versions/002_template.py#L21-L96)
|
||||
- [Templates.vue](file://frontend/src/views/basic/Templates.vue#L1-L638)
|
||||
- [template.js](file://frontend/src/api/template.js#L1-L62)
|
||||
|
||||
## 核心组件
|
||||
- 指标模板表（IndicatorTemplate）
|
||||
- 字段：id、template_name、template_code、template_type、description、dimension_weights、assessment_cycle、is_active、created_at、updated_at
|
||||
- 关系：与模板指标关联表一对多
|
||||
- 约束：唯一索引（template_code）、索引（template_type、is_active）
|
||||
|
||||
- 模板指标关联表（TemplateIndicator）
|
||||
- 字段：id、template_id、indicator_id、category、target_value、target_unit、weight、scoring_method、scoring_params、sort_order、remark、created_at、updated_at
|
||||
- 关系：与模板表、指标表多对一
|
||||
- 约束：唯一索引（template_id, indicator_id）、索引（template_id、indicator_id）
|
||||
|
||||
- 模板类型枚举（TemplateType）
|
||||
- 类型：general、surgical、nonsurgical_ward、nonsurgical_noward、medical_tech、nursing、admin、logistics
|
||||
|
||||
- 指标表（Indicator）
|
||||
- 字段：id、name、code、indicator_type、bs_dimension、weight、max_score、target_value、target_unit、calculation_method、assessment_method、deduction_standard、data_source、applicable_dept_types、is_veto、is_active、created_at、updated_at
|
||||
- 约束：CheckConstraint(weight > 0)
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L387-L438)
|
||||
- [models.py](file://backend/app/models/models.py#L117-L147)
|
||||
- [models.py](file://backend/app/models/models.py#L375-L385)
|
||||
|
||||
## 架构总览
|
||||
模板系统采用“模板-指标”多对多关系，通过模板指标关联表实现灵活配置。模板类型决定适用科室范围，维度权重用于汇总计算，指标分类用于二级归类，权重与评分方法用于最终得分计算。
|
||||
|
||||
```mermaid
|
||||
erDiagram
|
||||
INDICATOR_TEMPLATE {
|
||||
int id PK
|
||||
string template_name
|
||||
string template_code UK
|
||||
string template_type
|
||||
text description
|
||||
text dimension_weights
|
||||
string assessment_cycle
|
||||
boolean is_active
|
||||
datetime created_at
|
||||
datetime updated_at
|
||||
}
|
||||
TEMPLATE_INDICATOR {
|
||||
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
|
||||
text remark
|
||||
datetime created_at
|
||||
datetime updated_at
|
||||
}
|
||||
INDICATOR {
|
||||
int id PK
|
||||
string name
|
||||
string code UK
|
||||
string indicator_type
|
||||
string 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
|
||||
boolean is_veto
|
||||
boolean is_active
|
||||
datetime created_at
|
||||
datetime updated_at
|
||||
}
|
||||
INDICATOR_TEMPLATE ||--o{ TEMPLATE_INDICATOR : "包含"
|
||||
INDICATOR ||--o{ TEMPLATE_INDICATOR : "被包含"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [models.py](file://backend/app/models/models.py#L387-L438)
|
||||
- [models.py](file://backend/app/models/models.py#L117-L147)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 指标模板表（IndicatorTemplate）字段字典
|
||||
- id
|
||||
- 类型：整数
|
||||
- 主键：是
|
||||
- 描述：模板主键
|
||||
- 约束：自增
|
||||
- 章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L391-L391)
|
||||
|
||||
- template_name
|
||||
- 类型：字符串（最大长度200）
|
||||
- 描述：模板名称
|
||||
- 章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L392-L392)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L699-L700)
|
||||
|
||||
- template_code
|
||||
- 类型：字符串（最大长度50）
|
||||
- 描述：模板编码（唯一）
|
||||
- 约束：唯一索引
|
||||
- 章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L393-L393)
|
||||
- [002_template.py](file://backend/alembic/versions/002_template.py#L27-L36)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L700-L701)
|
||||
|
||||
- template_type
|
||||
- 类型：枚举（TemplateType）
|
||||
- 描述：模板类型
|
||||
- 取值：general、surgical、nonsurgical_ward、nonsurgical_noward、medical_tech、nursing、admin、logistics
|
||||
- 章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L394-L394)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L702-L702)
|
||||
- [002_template.py](file://backend/alembic/versions/002_template.py#L28-L28)
|
||||
|
||||
- description
|
||||
- 类型：文本
|
||||
- 描述：模板描述
|
||||
- 章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L395-L395)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L703-L703)
|
||||
|
||||
- dimension_weights
|
||||
- 类型：文本（JSON）
|
||||
- 描述：维度权重配置（财务、客户、内部流程、学习与成长）
|
||||
- 示例：{"financial": 35, "customer": 30, "internal_process": 25, "learning_growth": 10}
|
||||
- 章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L396-L396)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L704-L704)
|
||||
- [init_templates.py](file://backend/app/scripts/init_templates.py#L88-L88)
|
||||
|
||||
- assessment_cycle
|
||||
- 类型：字符串（最大长度20）
|
||||
- 描述：考核周期（monthly/quarterly/annual）
|
||||
- 默认值：monthly
|
||||
- 章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L397-L397)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L705-L705)
|
||||
- [init_templates.py](file://backend/app/scripts/init_templates.py#L89-L89)
|
||||
|
||||
- is_active
|
||||
- 类型：布尔
|
||||
- 描述：是否启用
|
||||
- 默认值：true
|
||||
- 章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L398-L398)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L728-L728)
|
||||
- [002_template.py](file://backend/alembic/versions/002_template.py#L32-L32)
|
||||
|
||||
- created_at/updated_at
|
||||
- 类型：日期时间
|
||||
- 描述：创建与更新时间
|
||||
- 章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L399-L400)
|
||||
- [models.py](file://backend/app/models/models.py#L400-L400)
|
||||
|
||||
- 关系与索引
|
||||
- 关系：与模板指标关联表一对多
|
||||
- 索引：template_type、is_active
|
||||
- 章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L402-L408)
|
||||
- [002_template.py](file://backend/alembic/versions/002_template.py#L38-L39)
|
||||
|
||||
### 模板指标关联表（TemplateIndicator）字段字典
|
||||
- id
|
||||
- 类型：整数
|
||||
- 主键：是
|
||||
- 描述：模板指标关联主键
|
||||
- 章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L415-L415)
|
||||
|
||||
- template_id
|
||||
- 类型：整数
|
||||
- 外键：指向 indicator_templates.id
|
||||
- 描述：模板ID
|
||||
- 章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L416-L416)
|
||||
- [002_template.py](file://backend/alembic/versions/002_template.py#L45-L57)
|
||||
|
||||
- indicator_id
|
||||
- 类型：整数
|
||||
- 外键：指向 indicators.id
|
||||
- 描述：指标ID
|
||||
- 章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L417-L417)
|
||||
- [002_template.py](file://backend/alembic/versions/002_template.py#L46-L57)
|
||||
|
||||
- category
|
||||
- 类型：字符串（最大长度100）
|
||||
- 描述：指标分类（二级指标分类）
|
||||
- 示例：收支管理、患者满意度、质量与安全
|
||||
- 章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L418-L418)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L657-L657)
|
||||
- [init_templates.py](file://backend/app/scripts/init_templates.py#L90-L108)
|
||||
|
||||
- target_value/target_unit
|
||||
- 类型：数值/字符串
|
||||
- 描述：目标值与单位
|
||||
- 章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L419-L420)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L658-L659)
|
||||
|
||||
- weight
|
||||
- 类型：数值（默认1.0）
|
||||
- 描述：在模板内的权重
|
||||
- 章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L421-L421)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L660-L660)
|
||||
- [init_templates.py](file://backend/app/scripts/init_templates.py#L91-L107)
|
||||
|
||||
- scoring_method/scoring_params
|
||||
- 类型：字符串/文本
|
||||
- 描述：评分方法与参数（JSON）
|
||||
- 方法：range、target、deduction、bonus、veto
|
||||
- 章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L422-L423)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L661-L662)
|
||||
- [Templates.vue](file://frontend/src/views/basic/Templates.vue#L211-L217)
|
||||
|
||||
- sort_order
|
||||
- 类型：整数
|
||||
- 描述：排序
|
||||
- 默认值：0
|
||||
- 章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L424-L424)
|
||||
- [template_service.py](file://backend/app/services/template_service.py#L191-L202)
|
||||
|
||||
- remark
|
||||
- 类型：文本
|
||||
- 描述：备注
|
||||
- 章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L425-L425)
|
||||
|
||||
- created_at/updated_at
|
||||
- 类型：日期时间
|
||||
- 描述：创建与更新时间
|
||||
- 章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L426-L427)
|
||||
|
||||
- 关系与索引
|
||||
- 关系：与模板表、指标表多对一
|
||||
- 索引：template_id、indicator_id、(template_id, indicator_id)唯一
|
||||
- 章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L429-L437)
|
||||
- [002_template.py](file://backend/alembic/versions/002_template.py#L61-L63)
|
||||
|
||||
### 模板类型枚举（TemplateType）
|
||||
- 取值与含义
|
||||
- general：通用模板
|
||||
- surgical：手术临床科室
|
||||
- nonsurgical_ward：非手术有病房科室
|
||||
- nonsurgical_noward：非手术无病房科室
|
||||
- medical_tech：医技科室
|
||||
- nursing：护理单元
|
||||
- admin：行政科室
|
||||
- logistics：后勤科室
|
||||
- 使用场景
|
||||
- 用于区分模板适用科室类型，配合指标的适用科室类型字段实现过滤
|
||||
- 章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L375-L385)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L642-L652)
|
||||
|
||||
### 指标分类管理与维度权重配置
|
||||
- 指标分类（category）
|
||||
- 作用：对模板内的指标进行二级分类，便于统计与展示
|
||||
- 示例：收支管理、患者满意度、质量与安全、内部服务效率等
|
||||
- 章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L418-L418)
|
||||
- [init_templates.py](file://backend/app/scripts/init_templates.py#L90-L108)
|
||||
|
||||
- 维度权重（dimension_weights）
|
||||
- 结构：JSON对象，键为维度标识，值为百分比
|
||||
- 维度：financial、customer、internal_process、learning_growth
|
||||
- 用途：用于模板层面的维度汇总与权重分配
|
||||
- 章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L396-L396)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L704-L704)
|
||||
- [init_templates.py](file://backend/app/scripts/init_templates.py#L88-L88)
|
||||
|
||||
- 指标维度（bs_dimension）
|
||||
- 作用：指标所属的平衡计分卡维度，与模板维度权重协同使用
|
||||
- 章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L125-L125)
|
||||
- [init_templates.py](file://backend/init_indicator_templates.py#L28-L38)
|
||||
|
||||
### 模板与指标的多对多关联与权重分配机制
|
||||
- 关联关系
|
||||
- 通过 TemplateIndicator 实现模板与指标的多对多绑定
|
||||
- 每个模板内的指标可独立设置权重、目标值、评分方法等
|
||||
- 权重分配
|
||||
- 模板维度权重：用于模板层面的维度汇总
|
||||
- 指标权重：用于模板内指标的加权计算
|
||||
- 章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L411-L431)
|
||||
- [template_service.py](file://backend/app/services/template_service.py#L110-L124)
|
||||
|
||||
### 模板版本管理与继承关系
|
||||
- 版本字段
|
||||
- 当前模型未内置版本字段；如需版本管理，可在模板表中扩展 version 字段
|
||||
- 继承关系
|
||||
- 可通过模板类型与指标适用科室类型实现“继承”效果：通用模板可作为特定模板的父模板，再叠加差异字段
|
||||
- 章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L391-L400)
|
||||
- [init_templates.py](file://backend/app/scripts/init_templates.py#L82-L186)
|
||||
|
||||
### 激活状态与使用范围约束
|
||||
- 激活状态（is_active）
|
||||
- 控制模板是否可用
|
||||
- 前端通过开关切换，后端接口支持批量更新
|
||||
- 使用范围
|
||||
- 模板类型（template_type）限定适用科室类型
|
||||
- 指标的适用科室类型（applicable_dept_types）进一步限制
|
||||
- 章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L398-L398)
|
||||
- [models.py](file://backend/app/models/models.py#L134-L134)
|
||||
- [templates.py](file://backend/app/api/v1/templates.py#L22-L42)
|
||||
|
||||
## 依赖分析
|
||||
模板系统的关键依赖关系如下：
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
ENUM["TemplateType 枚举"] --> IT["IndicatorTemplate 模型"]
|
||||
IT --> TI["TemplateIndicator 模型"]
|
||||
IND["Indicator 模型"] --> TI
|
||||
SVC["TemplateService 服务"] --> IT
|
||||
SVC --> TI
|
||||
API["templates.py 路由"] --> SVC
|
||||
SCHEMA["schemas.py 模式"] --> API
|
||||
FRONT["Templates.vue 页面"] --> API
|
||||
API --> FRONT
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [models.py](file://backend/app/models/models.py#L375-L385)
|
||||
- [models.py](file://backend/app/models/models.py#L387-L438)
|
||||
- [template_service.py](file://backend/app/services/template_service.py#L20-L293)
|
||||
- [templates.py](file://backend/app/api/v1/templates.py#L1-L272)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L640-L743)
|
||||
- [Templates.vue](file://frontend/src/views/basic/Templates.vue#L1-L638)
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L375-L385)
|
||||
- [models.py](file://backend/app/models/models.py#L387-L438)
|
||||
- [template_service.py](file://backend/app/services/template_service.py#L20-L293)
|
||||
- [templates.py](file://backend/app/api/v1/templates.py#L1-L272)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L640-L743)
|
||||
- [Templates.vue](file://frontend/src/views/basic/Templates.vue#L1-L638)
|
||||
|
||||
## 性能考虑
|
||||
- 查询优化
|
||||
- 模板列表按 template_type 与 is_active 进行过滤，建议保持索引有效
|
||||
- 模板详情加载时使用 selectinload 预加载关联指标，避免 N+1 查询
|
||||
- 写入优化
|
||||
- 批量添加模板指标时，服务层会自动设置排序，减少重复计算
|
||||
- 前端渲染
|
||||
- 前端对维度权重进行 JSON 解析与可视化展示，注意空值处理与错误捕获
|
||||
|
||||
## 故障排查指南
|
||||
- 模板编码冲突
|
||||
- 现象：创建模板时报错“模板编码已存在”
|
||||
- 排查：检查唯一索引约束与迁移脚本
|
||||
- 章节来源
|
||||
- [templates.py](file://backend/app/api/v1/templates.py#L136-L139)
|
||||
- [002_template.py](file://backend/alembic/versions/002_template.py#L36-L36)
|
||||
|
||||
- 指标重复添加
|
||||
- 现象：添加模板指标返回失败
|
||||
- 排查：检查唯一索引（template_id, indicator_id）
|
||||
- 章节来源
|
||||
- [template_service.py](file://backend/app/services/template_service.py#L174-L182)
|
||||
- [002_template.py](file://backend/alembic/versions/002_template.py#L63-L63)
|
||||
|
||||
- 维度权重解析失败
|
||||
- 现象：前端维度权重显示异常
|
||||
- 排查：确认 JSON 格式正确，服务端/前端均做容错处理
|
||||
- 章节来源
|
||||
- [Templates.vue](file://frontend/src/views/basic/Templates.vue#L310-L317)
|
||||
|
||||
- 指标权重校验
|
||||
- 现象：指标权重小于等于0导致异常
|
||||
- 排查：数据库层有 CheckConstraint，前端也应限制输入范围
|
||||
- 章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L145-L145)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L158-L158)
|
||||
|
||||
## 结论
|
||||
指标模板系统通过清晰的模型设计与严格的约束，实现了模板类型、维度权重、指标分类与权重分配的灵活配置。模板与指标的多对多关系通过关联表实现解耦，支持按科室类型与适用范围进行精细化管理。建议后续在模板表中增加版本字段以完善版本管理能力，并在前端增强对 JSON 参数的校验与提示，提升系统的稳定性与易用性。
|
||||
596
.qoder/repowiki/zh/content/数据库设计/数据字典/数据字典.md
Normal file
596
.qoder/repowiki/zh/content/数据库设计/数据字典/数据字典.md
Normal file
@@ -0,0 +1,596 @@
|
||||
# 数据字典
|
||||
|
||||
<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/schemas/schemas.py](file://backend/app/schemas/schemas.py)
|
||||
- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py)
|
||||
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py)
|
||||
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py)
|
||||
- [backend/app/api/v1/performance_plans.py](file://backend/app/api/v1/performance_plans.py)
|
||||
- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py)
|
||||
- [backend/app/api/v1/finance.py](file://backend/app/api/v1/finance.py)
|
||||
- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py)
|
||||
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py)
|
||||
- [backend/app/services/department_service.py](file://backend/app/services/department_service.py)
|
||||
- [backend/app/services/indicator_service.py](file://backend/app/services/indicator_service.py)
|
||||
- [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py)
|
||||
- [backend/app/services/template_service.py](file://backend/app/services/template_service.py)
|
||||
- [docs/database.md](file://docs/database.md)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构概览](#架构概览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖分析](#依赖分析)
|
||||
7. [性能考虑](#性能考虑)
|
||||
8. [故障排除指南](#故障排除指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
本数据字典面向医院绩效管理系统，系统围绕“科室—员工—考核—工资—财务”主线构建，涵盖指标管理、计划管理、模板管理、财务核算等模块。本文档从字段层面梳理每个实体的数据定义（业务含义、数据类型、长度/精度限制、取值范围、默认值），明确枚举类型及其使用场景，阐述字段与业务实体的对应关系，给出数据流转过程，并提供维护更新规范与查询使用指南。
|
||||
|
||||
## 项目结构
|
||||
系统采用前后端分离架构，后端基于FastAPI + SQLAlchemy，采用分层设计（API → Service → Model），前端Vue3 + Vite。数据库采用SQLite（开发环境），通过Alembic进行版本化迁移。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
FE["前端界面<br/>Vue3 + Vite"] --> API["后端API<br/>FastAPI"]
|
||||
API --> SVC["服务层<br/>各模块Service"]
|
||||
SVC --> MODELS["模型层<br/>SQLAlchemy ORM"]
|
||||
MODELS --> DB["数据库<br/>SQLite"]
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py#L1-L124)
|
||||
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L1-L108)
|
||||
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L1-L142)
|
||||
- [backend/app/api/v1/performance_plans.py](file://backend/app/api/v1/performance_plans.py#L1-L310)
|
||||
- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L1-L156)
|
||||
- [backend/app/api/v1/finance.py](file://backend/app/api/v1/finance.py#L1-L217)
|
||||
- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L1-L272)
|
||||
|
||||
章节来源
|
||||
- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py#L1-L124)
|
||||
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L1-L108)
|
||||
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L1-L142)
|
||||
- [backend/app/api/v1/performance_plans.py](file://backend/app/api/v1/performance_plans.py#L1-L310)
|
||||
- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L1-L156)
|
||||
- [backend/app/api/v1/finance.py](file://backend/app/api/v1/finance.py#L1-L217)
|
||||
- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L1-L272)
|
||||
|
||||
## 核心组件
|
||||
- 数据模型层：定义实体、字段、约束、索引、枚举类型
|
||||
- 模式层（Pydantic）：定义API输入输出结构、字段校验规则
|
||||
- API层：定义REST接口、参数、返回结构
|
||||
- 服务层：封装业务逻辑、事务处理、数据聚合
|
||||
|
||||
章节来源
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L438)
|
||||
- [backend/app/models/finance.py](file://backend/app/models/finance.py#L1-L79)
|
||||
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L1-L743)
|
||||
|
||||
## 架构概览
|
||||
系统围绕“绩效考核—工资核算—财务分析”的主流程展开，指标与模板驱动考核，考核结果驱动工资生成，财务模块提供收支与结余分析。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "基础数据"
|
||||
DEPT["科室表<br/>departments"]
|
||||
STAFF["员工表<br/>staff"]
|
||||
USERS["用户表<br/>users"]
|
||||
end
|
||||
subgraph "指标与计划"
|
||||
IND["指标表<br/>indicators"]
|
||||
TPL["模板表<br/>indicator_templates"]
|
||||
TIND["模板指标关联<br/>template_indicators"]
|
||||
PLAN["绩效计划表<br/>performance_plans"]
|
||||
REL["计划指标关联<br/>plan_kpi_relations"]
|
||||
end
|
||||
subgraph "考核与工资"
|
||||
ASSESS["考核记录表<br/>assessments"]
|
||||
DETAIL["考核明细表<br/>assessment_details"]
|
||||
SAL["工资记录表<br/>salary_records"]
|
||||
end
|
||||
subgraph "财务"
|
||||
FIN["科室财务记录<br/>department_finances"]
|
||||
end
|
||||
DEPT <-- "1:N" --> STAFF
|
||||
STAFF <-- "N:1" --> DEPT
|
||||
STAFF <-- "N:1" --> USERS
|
||||
IND <-- "N:1" --> DETAIL
|
||||
ASSESS <-- "1:N" --> DETAIL
|
||||
DETAIL <-- "N:1" --> IND
|
||||
PLAN <-- "1:N" --> REL
|
||||
REL <-- "N:1" --> IND
|
||||
STAFF <-- "N:1" --> ASSESS
|
||||
STAFF <-- "N:1" --> SAL
|
||||
DEPT <-- "N:1" --> FIN
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [docs/database.md](file://docs/database.md#L1-L286)
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L438)
|
||||
- [backend/app/models/finance.py](file://backend/app/models/finance.py#L45-L79)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 1) 基础数据实体
|
||||
|
||||
#### 1.1 科室表 departments
|
||||
- 字段定义
|
||||
- id: 整型, 主键, 自增
|
||||
- name: 字符串, 长度100, 非空, 说明: 科室名称
|
||||
- code: 字符串, 长度20, 唯一, 非空, 说明: 科室编码
|
||||
- dept_type: 枚举, 非空, 说明: 科室类型
|
||||
- parent_id: 整型, 外键, 说明: 上级科室
|
||||
- level: 整型, 默认1, 说明: 层级
|
||||
- sort_order: 整型, 默认0, 说明: 排序
|
||||
- is_active: 布尔, 默认true, 说明: 是否启用
|
||||
- description: 文本, 说明: 描述
|
||||
- created_at/updated_at: 时间戳, 说明: 创建/更新时间
|
||||
- 约束与索引
|
||||
- 唯一键: code
|
||||
- 索引: idx_dept_type, idx_dept_parent
|
||||
- 业务含义
|
||||
- 支持多级组织架构，支持停用/启用；用于员工归属、计划/模板适用范围等
|
||||
- 默认值与取值范围
|
||||
- level: 1-5
|
||||
- sort_order: 任意整数
|
||||
- is_active: true/false
|
||||
- 使用场景
|
||||
- 员工入职时绑定科室；计划/模板按科室类型筛选适用范围
|
||||
|
||||
章节来源
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L86)
|
||||
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L64-L103)
|
||||
- [docs/database.md](file://docs/database.md#L99-L116)
|
||||
|
||||
#### 1.2 员工表 staff
|
||||
- 字段定义
|
||||
- id: 整型, 主键, 自增
|
||||
- employee_id: 字符串, 长度20, 唯一, 非空, 说明: 工号
|
||||
- name: 字符串, 长度50, 非空, 说明: 姓名
|
||||
- department_id: 整型, 外键, 非空, 说明: 所属科室
|
||||
- position: 字符串, 长度50, 非空, 说明: 职位
|
||||
- title: 字符串, 长度50, 说明: 职称
|
||||
- phone/email: 字符串, 长度20/100, 说明: 联系方式
|
||||
- base_salary: 数值, 精度(10,2), 默认0, 说明: 基本工资
|
||||
- performance_ratio: 数值, 精度(5,2), 默认1.0, 说明: 绩效系数
|
||||
- status: 枚举, 默认active, 说明: 员工状态
|
||||
- hire_date: 时间戳, 说明: 入职日期
|
||||
- created_at/updated_at: 时间戳
|
||||
- 约束与索引
|
||||
- 唯一键: employee_id
|
||||
- 索引: idx_staff_dept, idx_staff_status
|
||||
- 业务含义
|
||||
- 基于基本工资与绩效系数计算绩效奖金；参与考核与工资生成
|
||||
- 默认值与取值范围
|
||||
- base_salary ≥ 0
|
||||
- 0 ≤ performance_ratio ≤ 5
|
||||
- 使用场景
|
||||
- 薪资计算、部门统计、计划责任人
|
||||
|
||||
章节来源
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L88-L115)
|
||||
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L107-L150)
|
||||
- [docs/database.md](file://docs/database.md#L117-L137)
|
||||
|
||||
#### 1.3 用户表 users
|
||||
- 字段定义
|
||||
- id: 整型, 主键, 自增
|
||||
- username: 字符串, 长度50, 唯一, 非空, 说明: 用户名
|
||||
- password_hash: 字符串, 长度255, 非空, 说明: 密码哈希
|
||||
- staff_id: 整型, 外键, 说明: 关联员工
|
||||
- role: 字符串, 长度20, 默认staff, 说明: 角色
|
||||
- is_active: 布尔, 默认true, 说明: 是否启用
|
||||
- last_login: 时间戳, 说明: 最后登录
|
||||
- created_at/updated_at: 时间戳
|
||||
- 约束与索引
|
||||
- 唯一键: username
|
||||
- 索引: idx_user_username
|
||||
- 业务含义
|
||||
- 系统访问控制与权限管理的基础
|
||||
|
||||
章节来源
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L244-L261)
|
||||
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L315-L345)
|
||||
|
||||
### 2) 指标与模板
|
||||
|
||||
#### 2.1 指标表 indicators
|
||||
- 字段定义
|
||||
- id: 整型, 主键, 自增
|
||||
- name/code: 字符串, 长度100/20, 唯一, 非空, 说明: 指标名称/编码
|
||||
- indicator_type: 枚举, 非空, 说明: 指标类型
|
||||
- bs_dimension: 枚举, 非空, 说明: 平衡计分卡维度
|
||||
- weight: 数值, 精度(5,2), 默认1.0, 说明: 权重
|
||||
- max_score: 数值, 精度(5,2), 默认100, 说明: 最高分值
|
||||
- target_value/target_unit: 数值/字符串, 说明: 目标值与单位
|
||||
- calculation_method/assessment_method/deduction_standard/data_source: 文本, 说明: 计算/考核/扣分/数据来源
|
||||
- applicable_dept_types: 文本(JSON数组), 说明: 适用科室类型
|
||||
- is_veto: 布尔, 默认false, 说明: 是否一票否决
|
||||
- is_active: 布尔, 默认true, 说明: 是否启用
|
||||
- created_at/updated_at: 时间戳
|
||||
- 约束与索引
|
||||
- 约束: weight > 0
|
||||
- 索引: idx_indicator_type
|
||||
- 业务含义
|
||||
- 考核的最小颗粒，决定评分与权重；支持JSON存储适用范围
|
||||
- 默认值与取值范围
|
||||
- weight > 0
|
||||
- max_score ≥ 0
|
||||
- 使用场景
|
||||
- 考核打分、计划目标设定、模板匹配
|
||||
|
||||
章节来源
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L117-L147)
|
||||
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L153-L193)
|
||||
- [docs/database.md](file://docs/database.md#L138-L158)
|
||||
|
||||
#### 2.2 指标模板表 indicator_templates
|
||||
- 字段定义
|
||||
- id: 整型, 主键, 自增
|
||||
- template_name/code: 字符串, 长度200/50, 唯一, 非空
|
||||
- template_type: 枚举, 非空, 说明: 模板类型
|
||||
- description: 文本, 说明: 模板描述
|
||||
- dimension_weights: 文本(JSON), 说明: 维度权重
|
||||
- assessment_cycle: 字符串, 长度20, 默认monthly, 说明: 考核周期
|
||||
- is_active: 布尔, 默认true
|
||||
- created_at/updated_at: 时间戳
|
||||
- 约束与索引
|
||||
- 索引: idx_template_type, idx_template_active
|
||||
- 业务含义
|
||||
- 为不同科室类型提供标准化指标集合，支持批量导入
|
||||
|
||||
章节来源
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L387-L409)
|
||||
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L698-L732)
|
||||
|
||||
#### 2.3 模板指标关联表 template_indicators
|
||||
- 字段定义
|
||||
- id: 整型, 主键, 自增
|
||||
- template_id/indicator_id: 整型, 外键, 非空, 说明: 模板与指标
|
||||
- category: 字符串, 长度100, 说明: 指标分类(二级指标)
|
||||
- target_value/target_unit: 数值/字符串, 说明: 目标值与单位
|
||||
- weight: 数值, 精度(5,2), 默认1.0
|
||||
- scoring_method/scoring_params: 字符串/文本(JSON), 说明: 评分方法与参数
|
||||
- sort_order: 整型, 默认0, 说明: 排序
|
||||
- remark: 文本, 说明: 备注
|
||||
- created_at/updated_at: 时间戳
|
||||
- 约束与索引
|
||||
- 索引: idx_ti_template, idx_ti_indicator, idx_ti_unique(模板+指标唯一)
|
||||
- 业务含义
|
||||
- 将指标纳入模板，支持排序与评分参数配置
|
||||
|
||||
章节来源
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L411-L438)
|
||||
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L654-L696)
|
||||
|
||||
### 3) 考核与工资
|
||||
|
||||
#### 3.1 考核记录表 assessments
|
||||
- 字段定义
|
||||
- id: 整型, 主键, 自增
|
||||
- staff_id: 整型, 外键, 非空, 说明: 被考核员工
|
||||
- period_year/period_month: 整型, 非空, 说明: 考核年度/月份
|
||||
- period_type: 字符串, 长度20, 默认monthly, 说明: 周期类型
|
||||
- total_score/weighted_score: 数值, 精度(5,2), 默认0, 说明: 总分/加权得分
|
||||
- status: 枚举, 默认draft, 说明: 状态
|
||||
- assessor_id/reviewer_id: 整型, 外键, 说明: 考核人/审核人
|
||||
- submit_time/review_time: 时间戳, 说明: 提交/审核时间
|
||||
- remark: 文本, 说明: 备注
|
||||
- created_at/updated_at: 时间戳
|
||||
- 约束与索引
|
||||
- 索引: idx_assessment_staff, idx_assessment_period, idx_assessment_status
|
||||
- 业务含义
|
||||
- 记录一次完整的考核流程，支持草稿、提交、审核、确认、驳回
|
||||
|
||||
章节来源
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L149-L179)
|
||||
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L220-L271)
|
||||
- [docs/database.md](file://docs/database.md#L159-L180)
|
||||
|
||||
#### 3.2 考核明细表 assessment_details
|
||||
- 字段定义
|
||||
- id: 整型, 主键, 自增
|
||||
- assessment_id/indicator_id: 整型, 外键, 非空
|
||||
- actual_value: 数值, 精度(10,2), 说明: 实际值
|
||||
- score: 数值, 精度(5,2), 默认0, 说明: 得分
|
||||
- evidence: 文本, 说明: 佐证材料
|
||||
- remark: 文本, 说明: 备注
|
||||
- created_at/updated_at: 时间戳
|
||||
- 约束与索引
|
||||
- 索引: idx_detail_assessment, idx_detail_indicator
|
||||
- 业务含义
|
||||
- 记录每个指标的得分与实际值，支撑总分与加权得分计算
|
||||
|
||||
章节来源
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L181-L203)
|
||||
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L196-L219)
|
||||
- [docs/database.md](file://docs/database.md#L181-L196)
|
||||
|
||||
#### 3.3 工资记录表 salary_records
|
||||
- 字段定义
|
||||
- id: 整型, 主键, 自增
|
||||
- staff_id: 整型, 外键, 非空
|
||||
- period_year/period_month: 整型, 非空
|
||||
- base_salary/performance_score/performance_bonus/deduction/allowance: 数值, 精度(10,2)/(5,2), 默认0, 说明: 基本工资/绩效得分/绩效奖金/扣款/补贴
|
||||
- total_salary: 数值, 精度(10,2), 默认0, 说明: 应发工资
|
||||
- status: 字符串, 长度20, 默认pending, 说明: 状态
|
||||
- remark: 文本, 说明: 备注
|
||||
- created_at/updated_at: 时间戳
|
||||
- 约束与索引
|
||||
- 索引: idx_salary_staff, idx_salary_period
|
||||
- 业务含义
|
||||
- 基于考核结果生成工资，支持确认与批量确认
|
||||
|
||||
章节来源
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L205-L231)
|
||||
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L274-L312)
|
||||
- [docs/database.md](file://docs/database.md#L197-L217)
|
||||
|
||||
### 4) 绩效计划
|
||||
|
||||
#### 4.1 绩效计划表 performance_plans
|
||||
- 字段定义
|
||||
- id: 整型, 主键, 自增
|
||||
- plan_name/code: 字符串, 长度200/50, 唯一, 非空
|
||||
- plan_level: 枚举, 非空, 说明: 计划层级(hospital/department/individual)
|
||||
- plan_year/plan_month: 整型/可选, 说明: 年度/月份
|
||||
- plan_type: 字符串, 长度20, 默认annual, 说明: 计划类型(annual/monthly)
|
||||
- department_id/staff_id: 整型/可选, 外键, 说明: 所属科室/责任人
|
||||
- parent_plan_id: 整型, 外键, 说明: 上级计划
|
||||
- description/strategic_goals/key_initiatives: 文本, 说明: 描述/战略目标/关键举措
|
||||
- status: 枚举, 默认draft, 说明: 状态
|
||||
- submitter_id/approver_id: 整型, 外键, 说明: 提交人/审批人
|
||||
- submit_time/approve_time: 时间戳, 说明: 提交/审批时间
|
||||
- approve_remark: 文本, 说明: 审批意见
|
||||
- version: 整型, 默认1, 说明: 版本号
|
||||
- is_active: 布尔, 默认true, 说明: 是否启用
|
||||
- created_at/updated_at: 时间戳
|
||||
- 约束与索引
|
||||
- 索引: idx_plan_level, idx_plan_year, idx_plan_department, idx_plan_status
|
||||
- 业务含义
|
||||
- 支持医院/科室/个人三级计划，支持父子计划与审批流程
|
||||
|
||||
章节来源
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L270-L312)
|
||||
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L519-L570)
|
||||
|
||||
#### 4.2 计划指标关联表 plan_kpi_relations
|
||||
- 字段定义
|
||||
- id: 整型, 主键, 自增
|
||||
- plan_id/indicator_id: 整型, 外键, 非空
|
||||
- target_value/target_unit: 数值/字符串, 说明: 目标值与单位
|
||||
- weight: 数值, 精度(5,2), 默认1.0, 说明: 权重
|
||||
- scoring_method/scoring_params: 字符串/文本(JSON), 说明: 评分方法与参数
|
||||
- remark: 文本, 说明: 备注
|
||||
- created_at/updated_at: 时间戳
|
||||
- 约束与索引
|
||||
- 索引: idx_relation_plan, idx_relation_indicator, idx_relation_unique(计划+指标唯一)
|
||||
- 业务含义
|
||||
- 将指标纳入具体计划，支持目标与权重配置
|
||||
|
||||
章节来源
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L314-L339)
|
||||
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L481-L518)
|
||||
|
||||
### 5) 财务核算
|
||||
|
||||
#### 5.1 科室财务记录表 department_finances
|
||||
- 字段定义
|
||||
- id: 整型, 主键, 自增
|
||||
- department_id: 整型, 外键, 非空
|
||||
- period_year/period_month: 整型, 非空
|
||||
- finance_type: 枚举, 非空, 说明: 收入/支出
|
||||
- category: 字符串, 长度50, 非空, 说明: 类别
|
||||
- amount: 数值, 精度(12,2), 默认0, 说明: 金额
|
||||
- source: 字符串, 长度100, 说明: 数据来源
|
||||
- remark: 文本, 说明: 备注
|
||||
- created_at/updated_at: 时间戳
|
||||
- 约束与索引
|
||||
- 约束: amount ≥ 0
|
||||
- 索引: idx_finance_dept, idx_finance_period, idx_finance_type, idx_finance_category
|
||||
- 业务含义
|
||||
- 记录各科室的收支明细，支持按类别统计与结余计算
|
||||
|
||||
章节来源
|
||||
- [backend/app/models/finance.py](file://backend/app/models/finance.py#L45-L75)
|
||||
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L407-L452)
|
||||
|
||||
### 6) 枚举类型与取值范围
|
||||
|
||||
- 科室类型 DeptType
|
||||
- 取值: clinical_surgical, clinical_nonsurgical_ward, clinical_nonsurgical_noward, medical_tech, medical_auxiliary, nursing, admin, finance, logistics
|
||||
- 用途: 控制模板与计划适用范围
|
||||
|
||||
- 员工状态 StaffStatus
|
||||
- 取值: active, leave, resigned, retired
|
||||
|
||||
- 考核状态 AssessmentStatus
|
||||
- 取值: draft, submitted, reviewed, finalized, rejected
|
||||
|
||||
- 指标类型 IndicatorType
|
||||
- 取值: quality, quantity, efficiency, service, cost
|
||||
|
||||
- 计划层级 PlanLevel
|
||||
- 取值: hospital, department, individual
|
||||
|
||||
- 计划状态 PlanStatus
|
||||
- 取值: draft, pending, approved, rejected, active, completed, cancelled
|
||||
|
||||
- 菜单类型 MenuType
|
||||
- 取值: menu, button
|
||||
|
||||
- 模板类型 TemplateType
|
||||
- 取值: general, surgical, nonsurgical_ward, nonsurgical_noward, medical_tech, nursing, admin, logistics
|
||||
|
||||
- 财务类型 FinanceType
|
||||
- 取值: revenue, expense
|
||||
|
||||
- 收入类别 RevenueCategory
|
||||
- 取值: examination, lab_test, radiology, bed, nursing, treatment, surgery, injection, oxygen, other
|
||||
|
||||
- 支出类别 ExpenseCategory
|
||||
- 取值: material, personnel, maintenance, utility, other
|
||||
|
||||
章节来源
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L16-L43)
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L233-L242)
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L341-L345)
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L375-L385)
|
||||
- [backend/app/models/finance.py](file://backend/app/models/finance.py#L16-L43)
|
||||
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L12-L45)
|
||||
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L463-L479)
|
||||
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L584-L588)
|
||||
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L642-L652)
|
||||
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L378-L405)
|
||||
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L378-L405)
|
||||
|
||||
### 7) 数据流转说明
|
||||
|
||||
#### 7.1 考核到工资的流程
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant API as "API"
|
||||
participant Svc as "SalaryService"
|
||||
participant DB as "数据库"
|
||||
API->>Svc : "根据考核生成工资"
|
||||
Svc->>DB : "查询已确认的考核记录"
|
||||
DB-->>Svc : "返回考核与明细"
|
||||
Svc->>Svc : "计算绩效得分/奖金"
|
||||
Svc->>DB : "写入工资记录"
|
||||
DB-->>Svc : "返回记录ID"
|
||||
Svc-->>API : "生成成功"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L96-L111)
|
||||
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L194-L206)
|
||||
|
||||
#### 7.2 财务收支统计流程
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["开始"]) --> Fetch["查询科室收支记录"]
|
||||
Fetch --> Group["按类别分组统计"]
|
||||
Group --> Sum["计算合计"]
|
||||
Sum --> Balance["结余 = 收入合计 - 支出合计"]
|
||||
Balance --> End(["结束"])
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [backend/app/api/v1/finance.py](file://backend/app/api/v1/finance.py#L21-L155)
|
||||
- [backend/app/models/finance.py](file://backend/app/models/finance.py#L45-L75)
|
||||
|
||||
## 依赖分析
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
STAFF["staff"] --> DEPT["departments"]
|
||||
STAFF --> USERS["users"]
|
||||
ASSESS["assessments"] --> STAFF
|
||||
ASSESS --> DETAIL["assessment_details"]
|
||||
DETAIL --> IND["indicators"]
|
||||
SAL["salary_records"] --> STAFF
|
||||
PLAN["performance_plans"] --> DEPT
|
||||
PLAN --> STAFF
|
||||
PLAN --> REL["plan_kpi_relations"]
|
||||
REL --> IND
|
||||
TPL["indicator_templates"] --> TIND["template_indicators"]
|
||||
TIND --> IND
|
||||
FIN["department_finances"] --> DEPT
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L438)
|
||||
- [backend/app/models/finance.py](file://backend/app/models/finance.py#L45-L79)
|
||||
|
||||
章节来源
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L438)
|
||||
- [backend/app/models/finance.py](file://backend/app/models/finance.py#L45-L79)
|
||||
|
||||
## 性能考虑
|
||||
- 索引策略
|
||||
- 对常用过滤字段建立索引（如科室类型、状态、周期、部门）
|
||||
- 对外键字段建立索引，减少连接开销
|
||||
- 查询优化
|
||||
- 使用selectinload预加载关联对象，避免N+1查询
|
||||
- 分页查询配合COUNT子查询，避免全表扫描
|
||||
- 数据类型选择
|
||||
- 数值使用Decimal保证精度；字符串使用VARCHAR并设置合理上限
|
||||
- 缓存建议
|
||||
- 对静态枚举与模板列表可做内存缓存，降低数据库压力
|
||||
|
||||
## 故障排除指南
|
||||
- 常见错误与定位
|
||||
- “指标/模板/科室编码已存在”：检查唯一约束冲突
|
||||
- “无法删除，存在子记录”：先清理子项再删除
|
||||
- “无法生成/确认工资”：检查考核状态与重复生成
|
||||
- “无效的类别”：确认财务类别枚举值
|
||||
- 排查步骤
|
||||
- 查看API返回状态码与错误信息
|
||||
- 检查数据库约束与索引是否生效
|
||||
- 核对枚举值是否在允许范围内
|
||||
- 使用服务层日志定位业务流程异常点
|
||||
|
||||
章节来源
|
||||
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L78-L82)
|
||||
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L103-L107)
|
||||
- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L104-L110)
|
||||
- [backend/app/api/v1/finance.py](file://backend/app/api/v1/finance.py#L170-L175)
|
||||
|
||||
## 结论
|
||||
本数据字典系统性梳理了医院绩效管理系统的数据结构与业务规则，明确了字段定义、枚举取值、默认值与约束、索引策略与使用场景，并给出了数据流转与维护规范。建议在后续迭代中持续完善字段注释、扩展审计字段、引入字段变更追踪机制，确保数据治理的可追溯性与一致性。
|
||||
|
||||
## 附录
|
||||
|
||||
### A. 字段与业务实体对应关系
|
||||
- 科室 → 员工：一对多
|
||||
- 员工 → 考核：一对多
|
||||
- 考核 → 明细：一对多
|
||||
- 明细 → 指标：多对一
|
||||
- 员工 → 工资：一对多
|
||||
- 计划 → 指标：多对多（通过plan_kpi_relations）
|
||||
- 模板 → 指标：多对多（通过template_indicators）
|
||||
- 科室 → 财务：一对多
|
||||
|
||||
章节来源
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L438)
|
||||
- [backend/app/models/finance.py](file://backend/app/models/finance.py#L45-L79)
|
||||
|
||||
### B. 数据字典维护与更新规范
|
||||
- 新增字段
|
||||
- 在模型层定义字段与约束，补充Pydantic模式
|
||||
- 在API层增加参数校验与默认值
|
||||
- 在服务层处理字段映射与业务逻辑
|
||||
- 更新数据库迁移脚本并升级数据库
|
||||
- 修改字段
|
||||
- 评估兼容性与影响范围
|
||||
- 通过迁移脚本安全变更，保留历史数据
|
||||
- 更新API与模式校验规则
|
||||
- 删除字段
|
||||
- 确认无业务依赖后，通过迁移脚本删除
|
||||
- 清理相关API与服务逻辑
|
||||
|
||||
### C. 数据字典查询与使用指南
|
||||
- 基础查询
|
||||
- 通过API参数过滤（如科室类型、状态、周期）
|
||||
- 使用分页参数控制返回数量
|
||||
- 高级查询
|
||||
- 结合多个条件组合查询
|
||||
- 使用树形结构查询科室层级
|
||||
- 数据导出
|
||||
- 指标与模板支持批量导入/导出
|
||||
- 财务模块支持按类别统计与汇总
|
||||
|
||||
章节来源
|
||||
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L20-L51)
|
||||
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L20-L56)
|
||||
- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L22-L75)
|
||||
- [backend/app/api/v1/finance.py](file://backend/app/api/v1/finance.py#L116-L155)
|
||||
469
.qoder/repowiki/zh/content/数据库设计/数据字典/枚举类型定义.md
Normal file
469
.qoder/repowiki/zh/content/数据库设计/数据字典/枚举类型定义.md
Normal file
@@ -0,0 +1,469 @@
|
||||
# 枚举类型定义
|
||||
|
||||
<cite>
|
||||
**本文档引用的文件**
|
||||
- [models.py](file://backend/app/models/models.py)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py)
|
||||
- [templates.py](file://backend/app/api/v1/templates.py)
|
||||
- [init_templates.py](file://backend/app/scripts/init_templates.py)
|
||||
- [template_service.py](file://backend/app/services/template_service.py)
|
||||
- [002_template.py](file://backend/alembic/versions/002_template.py)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py)
|
||||
- [database.md](file://docs/database.md)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构概览](#架构概览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖分析](#依赖分析)
|
||||
7. [性能考虑](#性能考虑)
|
||||
8. [故障排除指南](#故障排除指南)
|
||||
9. [结论](#结论)
|
||||
|
||||
## 简介
|
||||
|
||||
本文档提供了医院绩效管理系统中所有枚举类型的完整数据字典。系统采用平衡计分卡（BSC）理论框架，通过标准化的枚举类型确保业务逻辑的一致性和可维护性。
|
||||
|
||||
该系统涵盖了从基础科室管理到复杂绩效考核的完整业务流程，所有关键业务状态和分类都通过精心设计的枚举类型来实现。
|
||||
|
||||
## 项目结构
|
||||
|
||||
系统采用分层架构设计，枚举类型分布在多个层次中：
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "数据模型层"
|
||||
A[models.py<br/>数据库模型枚举]
|
||||
end
|
||||
subgraph "API层"
|
||||
B[templates.py<br/>模板管理API]
|
||||
C[departments.py<br/>科室管理API]
|
||||
D[menus.py<br/>菜单管理API]
|
||||
end
|
||||
subgraph "服务层"
|
||||
E[template_service.py<br/>模板服务]
|
||||
F[department_service.py<br/>科室服务]
|
||||
G[menu_service.py<br/>菜单服务]
|
||||
end
|
||||
subgraph "脚本层"
|
||||
H[init_templates.py<br/>模板初始化]
|
||||
end
|
||||
A --> B
|
||||
A --> C
|
||||
A --> D
|
||||
B --> E
|
||||
C --> F
|
||||
D --> G
|
||||
H --> A
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [models.py](file://backend/app/models/models.py#L16-L438)
|
||||
- [templates.py](file://backend/app/api/v1/templates.py#L1-L272)
|
||||
|
||||
## 核心组件
|
||||
|
||||
系统定义了以下主要枚举类型：
|
||||
|
||||
### 科室类型 (DeptType)
|
||||
用于标识医院各类科室的标准化分类体系。
|
||||
|
||||
### 平衡计分卡维度 (BSCDimension)
|
||||
基于财务、客户、内部流程、学习成长四个维度的绩效评估框架。
|
||||
|
||||
### 员工状态 (StaffStatus)
|
||||
员工在组织中的生命周期状态管理。
|
||||
|
||||
### 考核状态 (AssessmentStatus)
|
||||
绩效考核流程中的状态流转控制。
|
||||
|
||||
### 指标类型 (IndicatorType)
|
||||
不同类型绩效指标的分类标准。
|
||||
|
||||
### 计划状态 (PlanStatus)
|
||||
绩效计划执行过程中的状态管理。
|
||||
|
||||
### 菜单类型 (MenuType)
|
||||
系统菜单结构的类型区分。
|
||||
|
||||
### 模板类型 (TemplateType)
|
||||
绩效指标模板的分类体系。
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L16-L438)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L12-L44)
|
||||
|
||||
## 架构概览
|
||||
|
||||
系统采用统一的枚举类型管理策略，确保跨层一致性：
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class DeptType {
|
||||
+CLINICAL_SURGICAL
|
||||
+CLINICAL_NONSURGICAL_WARD
|
||||
+CLINICAL_NONSURGICAL_NOWARD
|
||||
+MEDICAL_TECH
|
||||
+MEDICAL_AUXILIARY
|
||||
+NURSING
|
||||
+ADMIN
|
||||
+FINANCE
|
||||
+LOGISTICS
|
||||
}
|
||||
class BSCDimension {
|
||||
+FINANCIAL
|
||||
+CUSTOMER
|
||||
+INTERNAL_PROCESS
|
||||
+LEARNING_GROWTH
|
||||
}
|
||||
class StaffStatus {
|
||||
+ACTIVE
|
||||
+LEAVE
|
||||
+RESIGNED
|
||||
+RETIRED
|
||||
}
|
||||
class AssessmentStatus {
|
||||
+DRAFT
|
||||
+SUBMITTED
|
||||
+REVIEWED
|
||||
+FINALIZED
|
||||
+REJECTED
|
||||
}
|
||||
class IndicatorType {
|
||||
+QUALITY
|
||||
+QUANTITY
|
||||
+EFFICIENCY
|
||||
+SERVICE
|
||||
+COST
|
||||
}
|
||||
class PlanStatus {
|
||||
+DRAFT
|
||||
+PENDING
|
||||
+APPROVED
|
||||
+REJECTED
|
||||
+ACTIVE
|
||||
+COMPLETED
|
||||
+CANCELLED
|
||||
}
|
||||
class MenuType {
|
||||
+MENU
|
||||
+BUTTON
|
||||
}
|
||||
class TemplateType {
|
||||
+GENERAL
|
||||
+SURGICAL
|
||||
+NON_SURGICAL_WARD
|
||||
+NON_SURGICAL_NOWARD
|
||||
+MEDICAL_TECH
|
||||
+NURSING
|
||||
+ADMIN
|
||||
+LOGISTICS
|
||||
}
|
||||
DeptType --> BSCDimension : "影响"
|
||||
IndicatorType --> BSCDimension : "映射"
|
||||
TemplateType --> DeptType : "适用"
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [models.py](file://backend/app/models/models.py#L16-L438)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 科室类型 (DeptType) 数据字典
|
||||
|
||||
| 枚举值 | 业务含义 | 适用科室 | 使用场景 | 约束条件 |
|
||||
|--------|----------|----------|----------|----------|
|
||||
| clinical_surgical | 手术临床科室 | 外科、骨科、胸外科等 | 手术量、手术质量评估 | DRG/ RBRVS 计费 |
|
||||
| clinical_nonsurgical_ward | 非手术有病房科室 | 内科、儿科、神经科等 | 住院患者管理、病床使用率 | 床位周转率评估 |
|
||||
| clinical_nonsurgical_noward | 非手术无病房科室 | 急诊科、观察室等 | 急诊处理能力、观察患者管理 | 急诊周转时间 |
|
||||
| medical_tech | 医技科室 | 检验科、放射科、超声科等 | 检查报告质量、服务效率 | 报告准确率、及时性 |
|
||||
| medical_auxiliary | 医辅科室 | 病理科、药剂科等 | 辅助诊断支持、药品管理 | 质量控制标准 |
|
||||
| nursing | 护理单元 | 各病区护理单元 | 护理质量、患者满意度 | 护理技术操作规范 |
|
||||
| admin | 行政科室 | 院办、党办、财务科等 | 管理效能、服务支持 | 内部客户满意度 |
|
||||
| finance | 财务科室 | 财务科 | 财务核算、成本控制 | 会计准则遵循 |
|
||||
| logistics | 后勤保障科室 | 总务科、设备科等 | 后勤保障、设备维护 | 设备完好率 |
|
||||
|
||||
**使用场景示例**：
|
||||
- 指标模板选择：不同科室类型适用不同的指标模板
|
||||
- 数据筛选：按科室类型过滤统计数据
|
||||
- 权限控制：特定功能对特定科室类型开放
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L16-L26)
|
||||
- [init_templates.py](file://backend/app/scripts/init_templates.py#L82-L186)
|
||||
|
||||
### 平衡计分卡维度 (BSCDimension) 数据字典
|
||||
|
||||
| 维度值 | 业务含义 | 权重范围 | 关键指标示例 | 适用场景 |
|
||||
|--------|----------|----------|--------------|----------|
|
||||
| financial | 财务维度 | 30%-40% | 收支结余率、成本控制、资产效率 | 财务绩效评估 |
|
||||
| customer | 顾客维度 | 25%-35% | 患者满意度、服务可及性、投诉管理 | 服务质量评估 |
|
||||
| internal_process | 内部流程维度 | 20%-30% | 医疗质量、医疗安全、院感控制 | 运营效率评估 |
|
||||
| learning_growth | 学习成长维度 | 5%-15% | 科研教学、人才培养、业务学习 | 能力发展评估 |
|
||||
|
||||
**权重配置原则**：
|
||||
- 通用模板：财务40%，客户30%，内部流程25%，学习成长5%
|
||||
- 手术科室：财务35%，客户20%，内部流程30%，学习成长15%
|
||||
- 医技科室：财务20%，客户30%，内部流程40%，学习成长10%
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L29-L34)
|
||||
- [templates.py](file://backend/app/api/v1/templates.py#L63-L74)
|
||||
- [init_templates.py](file://backend/app/scripts/init_templates.py#L88-L186)
|
||||
|
||||
### 员工状态 (StaffStatus) 数据字典
|
||||
|
||||
| 状态值 | 业务含义 | 系统行为 | 统计影响 | 权限控制 |
|
||||
|--------|----------|----------|----------|----------|
|
||||
| active | 在职 | 可参与考核、享受绩效 | 计入在岗人员统计 | 完整权限 |
|
||||
| leave | 休假 | 不参与考核、暂停绩效 | 不计入在岗统计 | 有限权限 |
|
||||
| resigned | 离职 | 不参与考核、结算薪酬 | 不再统计 | 无权限 |
|
||||
| retired | 退休 | 不参与考核、结算薪酬 | 不再统计 | 无权限 |
|
||||
|
||||
**状态流转图**：
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> active
|
||||
active --> leave : 请假/调休
|
||||
leave --> active : 返回工作
|
||||
active --> resigned : 离职办理
|
||||
active --> retired : 退休办理
|
||||
resigned --> [*]
|
||||
retired --> [*]
|
||||
```
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L37-L42)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L24-L28)
|
||||
|
||||
### 考核状态 (AssessmentStatus) 数据字典
|
||||
|
||||
| 状态值 | 业务含义 | 系统权限 | 数据处理 | 流程控制 |
|
||||
|--------|----------|----------|----------|----------|
|
||||
| draft | 草稿 | 创建/编辑 | 临时保存 | 初始状态 |
|
||||
| submitted | 已提交 | 审核查看 | 待审核状态 | 提交流程 |
|
||||
| reviewed | 已审核 | 确认审批 | 审核中 | 审核流程 |
|
||||
| finalized | 已确认 | 工资核算 | 生效状态 | 结束状态 |
|
||||
| rejected | 已驳回 | 重新编辑 | 退回修改 | 异常流程 |
|
||||
|
||||
**状态流转流程**：
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant U as 用户
|
||||
participant S as 系统
|
||||
participant A as 审核人
|
||||
participant P as 系统
|
||||
U->>S : 创建/编辑考核
|
||||
S->>S : 状态=draft
|
||||
U->>S : 提交考核
|
||||
S->>S : 状态=submitted
|
||||
A->>S : 审核通过
|
||||
S->>S : 状态=reviewed
|
||||
A->>S : 确认生效
|
||||
S->>S : 状态=finalized
|
||||
S->>P : 生成工资记录
|
||||
```
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L45-L51)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L31-L36)
|
||||
|
||||
### 指标类型 (IndicatorType) 数据字典
|
||||
|
||||
| 类型值 | 业务含义 | 计算方法 | 评估标准 | 示例指标 |
|
||||
|--------|----------|----------|----------|----------|
|
||||
| quality | 质量指标 | 定性/定量评估 | 百分比/分数制 | 甲级病历率、满意度 |
|
||||
| quantity | 数量指标 | 绝对数值统计 | 完成率/达标率 | 手术台次、门诊量 |
|
||||
| efficiency | 效率指标 | 比较/比率分析 | 时间/成本效率 | 住院日、周转率 |
|
||||
| service | 服务指标 | 客户满意度 | 星级/评分制 | 服务态度、及时性 |
|
||||
| cost | 成本指标 | 成本效益分析 | 成本控制效果 | 材料消耗、成本率 |
|
||||
|
||||
**评估方法分类**：
|
||||
- 区间法：设定目标区间，按比例扣分
|
||||
- 目标参照法：与目标值对比，超耗扣分
|
||||
- 加分法：超额完成给予奖励分
|
||||
- 扣分法：违规事件直接扣分
|
||||
- 一票否决：重大事故直接无效
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L54-L60)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L39-L44)
|
||||
|
||||
### 计划状态 (PlanStatus) 数据字典
|
||||
|
||||
| 状态值 | 业务含义 | 审批流程 | 统计作用 | 系统控制 |
|
||||
|--------|----------|----------|----------|----------|
|
||||
| draft | 草稿 | 无需审批 | 临时保存 | 创建/修改 |
|
||||
| pending | 待审批 | 上级审批 | 待执行 | 提交申请 |
|
||||
| approved | 已批准 | 审批通过 | 执行准备 | 正式生效 |
|
||||
| rejected | 已驳回 | 审批拒绝 | 修改调整 | 退回修改 |
|
||||
| active | 执行中 | 开始执行 | 实际执行 | 进行中 |
|
||||
| completed | 已完成 | 执行结束 | 归档统计 | 结束状态 |
|
||||
| cancelled | 已取消 | 主动取消 | 终止执行 | 异常终止 |
|
||||
|
||||
**计划层级**：
|
||||
- hospital：医院级计划，全局性目标
|
||||
- department：科室级计划，部门目标
|
||||
- individual：个人级计划，员工目标
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L233-L241)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L463-L478)
|
||||
|
||||
### 菜单类型 (MenuType) 数据字典
|
||||
|
||||
| 类型值 | 业务含义 | 界面表现 | 权限控制 | 使用场景 |
|
||||
|--------|----------|----------|----------|----------|
|
||||
| menu | 菜单 | 可展开的导航项 | 路由访问权限 | 主要功能入口 |
|
||||
| button | 按钮 | 可点击的操作按钮 | 功能操作权限 | 具体业务操作 |
|
||||
|
||||
**菜单结构**：
|
||||
- 一级菜单：工作台、科室管理、员工管理等
|
||||
- 二级菜单：具体的业务功能页面
|
||||
- 按钮权限：新增、编辑、删除、查看等操作
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L341-L344)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L584-L587)
|
||||
|
||||
### 模板类型 (TemplateType) 数据字典
|
||||
|
||||
| 类型值 | 业务含义 | 适用范围 | 权重配置 | 特殊要求 |
|
||||
|--------|----------|----------|----------|----------|
|
||||
| general | 通用模板 | 全院各科室 | 4维均衡 | 基础通用指标 |
|
||||
| surgical | 手术临床科室 | 外科、妇科、眼科等 | 财务35% | DRG/RBRVS导向 |
|
||||
| nonsurgical_ward | 非手术有病房科室 | 内科、儿科等 | 4维均衡 | 住院管理重点 |
|
||||
| nonsurgical_noward | 非手术无病房科室 | 急诊、观察室等 | 4维均衡 | 急诊效率评估 |
|
||||
| medical_tech | 医技科室 | 检验、放射、超声等 | 内部流程40% | 质量效率双核心 |
|
||||
| nursing | 护理单元 | 各病区护理单元 | 顾客30% | 护理质量优先 |
|
||||
| admin | 行政科室 | 院办、党办、财务等 | 顾客40% | 服务支持导向 |
|
||||
| logistics | 后勤科室 | 总务、设备、基建等 | 内部流程40% | 保障效率优先 |
|
||||
|
||||
**模板特点**：
|
||||
- **通用模板**：平衡四维度，适合大多数科室
|
||||
- **手术模板**：强调财务效率，体现技术价值
|
||||
- **医技模板**：注重质量与效率并重
|
||||
- **行政模板**：突出服务支持能力
|
||||
- **后勤模板**：重视保障及时性
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L375-L384)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L642-L651)
|
||||
- [templates.py](file://backend/app/api/v1/templates.py#L45-L60)
|
||||
|
||||
## 依赖分析
|
||||
|
||||
### 数据库迁移依赖
|
||||
|
||||
系统通过 Alembic 迁移管理枚举类型的数据库存储：
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[初始版本] --> B[添加指标维度字段]
|
||||
B --> C[模板类型定义]
|
||||
C --> D[枚举类型持久化]
|
||||
E[DeptType] --> F[departments表]
|
||||
G[BSCDimension] --> H[indicators表]
|
||||
I[AssessmentStatus] --> J[assessments表]
|
||||
K[TemplateType] --> L[indicator_templates表]
|
||||
F --> M[SQL约束]
|
||||
H --> M
|
||||
J --> M
|
||||
L --> M
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L22-L173)
|
||||
- [002_template.py](file://backend/alembic/versions/002_template.py#L65-L95)
|
||||
|
||||
### 业务流程依赖
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
subgraph "业务流程"
|
||||
A[科室类型] --> B[指标模板]
|
||||
B --> C[绩效考核]
|
||||
C --> D[工资核算]
|
||||
end
|
||||
subgraph "状态管理"
|
||||
E[员工状态] --> F[考核状态]
|
||||
F --> G[计划状态]
|
||||
end
|
||||
subgraph "系统集成"
|
||||
H[菜单类型] --> I[权限控制]
|
||||
I --> J[界面展示]
|
||||
end
|
||||
B --> F
|
||||
C --> G
|
||||
D --> G
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [models.py](file://backend/app/models/models.py#L62-L438)
|
||||
- [template_service.py](file://backend/app/services/template_service.py#L270-L293)
|
||||
|
||||
**章节来源**
|
||||
- [002_template.py](file://backend/alembic/versions/002_template.py#L65-L95)
|
||||
- [template_service.py](file://backend/app/services/template_service.py#L270-L293)
|
||||
|
||||
## 性能考虑
|
||||
|
||||
### 枚举类型性能优化
|
||||
|
||||
1. **数据库索引优化**
|
||||
- 科室类型：departments.dept_type
|
||||
- 员工状态：staff.status
|
||||
- 考核状态：assessments.status
|
||||
- 指标类型：indicators.indicator_type
|
||||
|
||||
2. **查询性能**
|
||||
- 使用枚举值进行精确匹配优于字符串模糊查询
|
||||
- 合理利用数据库索引提高查询效率
|
||||
- 避免在 WHERE 子句中进行枚举值转换
|
||||
|
||||
3. **内存使用**
|
||||
- 枚举类型占用固定内存空间
|
||||
- 避免频繁创建新的枚举实例
|
||||
- 使用枚举缓存机制减少重复创建
|
||||
|
||||
## 故障排除指南
|
||||
|
||||
### 常见问题及解决方案
|
||||
|
||||
**问题1：枚举值不一致**
|
||||
- 症状：数据库中存储的枚举值与代码定义不匹配
|
||||
- 解决方案：检查 Alembic 迁移文件，确保数据库字段类型正确
|
||||
|
||||
**问题2：状态流转异常**
|
||||
- 症状：考核状态无法正常转换
|
||||
- 解决方案：验证状态转换规则，检查业务逻辑实现
|
||||
|
||||
**问题3：模板应用错误**
|
||||
- 症状：指标模板不适用于特定科室类型
|
||||
- 解决方案：检查 applicable_dept_types 字段配置
|
||||
|
||||
**问题4：权限控制失效**
|
||||
- 症状：菜单权限不生效
|
||||
- 解决方案：验证 MenuType 和权限标识配置
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L16-L438)
|
||||
- [template_service.py](file://backend/app/services/template_service.py#L270-L293)
|
||||
|
||||
## 结论
|
||||
|
||||
本系统通过标准化的枚举类型设计，实现了以下目标：
|
||||
|
||||
1. **业务一致性**：统一的枚举定义确保各模块间业务逻辑的一致性
|
||||
2. **可维护性**：集中化的枚举管理便于后续扩展和维护
|
||||
3. **可扩展性**：清晰的枚举层次结构支持业务需求变化
|
||||
4. **数据完整性**：数据库层面的约束保证数据质量
|
||||
|
||||
建议在后续开发中：
|
||||
- 定期审查和更新枚举定义
|
||||
- 建立枚举变更的审批流程
|
||||
- 完善枚举值的业务文档
|
||||
- 加强枚举类型的单元测试
|
||||
414
.qoder/repowiki/zh/content/数据库设计/数据字典/系统菜单字段.md
Normal file
414
.qoder/repowiki/zh/content/数据库设计/数据字典/系统菜单字段.md
Normal file
@@ -0,0 +1,414 @@
|
||||
# 系统菜单字段
|
||||
|
||||
<cite>
|
||||
**本文档引用的文件**
|
||||
- [models.py](file://backend/app/models/models.py)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py)
|
||||
- [menus.py](file://backend/app/api/v1/menus.py)
|
||||
- [menu_service.py](file://backend/app/services/menu_service.py)
|
||||
- [menu.js](file://frontend/src/api/menu.js)
|
||||
- [Menus.vue](file://frontend/src/views/system/Menus.vue)
|
||||
- [Layout.vue](file://frontend/src/views/Layout.vue)
|
||||
- [index.js](file://frontend/src/router/index.js)
|
||||
- [security.py](file://backend/app/core/security.py)
|
||||
- [create_menu_tables.py](file://backend/create_menu_tables.py)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构概览](#架构概览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖分析](#依赖分析)
|
||||
7. [性能考虑](#性能考虑)
|
||||
8. [故障排除指南](#故障排除指南)
|
||||
9. [结论](#结论)
|
||||
|
||||
## 简介
|
||||
|
||||
本文档提供了医院绩效系统中系统菜单相关字段的详细数据字典。涵盖了系统菜单表(Menu)、菜单类型枚举(MenuType)等字段定义，详细说明了菜单层级结构、权限控制、路由配置等相关字段。文档包含了菜单树形结构的父子关系和排序机制，提供了菜单权限验证和动态加载的字段设计说明，以及菜单可见性和激活状态的字段约束。同时说明了菜单与功能权限的关联关系。
|
||||
|
||||
## 项目结构
|
||||
|
||||
系统采用前后端分离架构，菜单管理功能分布在以下层次：
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "前端层"
|
||||
FE_API[菜单API调用]
|
||||
FE_VIEW[菜单管理界面]
|
||||
FE_ROUTER[前端路由]
|
||||
end
|
||||
subgraph "后端层"
|
||||
API[菜单API路由]
|
||||
SERVICE[菜单业务逻辑]
|
||||
MODEL[菜单数据模型]
|
||||
SCHEMA[数据验证模式]
|
||||
end
|
||||
subgraph "数据库层"
|
||||
DB[(MySQL数据库)]
|
||||
end
|
||||
FE_API --> API
|
||||
FE_VIEW --> FE_API
|
||||
FE_ROUTER --> FE_VIEW
|
||||
API --> SERVICE
|
||||
SERVICE --> MODEL
|
||||
MODEL --> DB
|
||||
SCHEMA --> API
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [menus.py](file://backend/app/api/v1/menus.py#L1-L164)
|
||||
- [menu_service.py](file://backend/app/services/menu_service.py#L1-L137)
|
||||
- [models.py](file://backend/app/models/models.py#L347-L373)
|
||||
|
||||
**章节来源**
|
||||
- [menus.py](file://backend/app/api/v1/menus.py#L1-L164)
|
||||
- [menu_service.py](file://backend/app/services/menu_service.py#L1-L137)
|
||||
- [models.py](file://backend/app/models/models.py#L347-L373)
|
||||
|
||||
## 核心组件
|
||||
|
||||
### 菜单数据模型
|
||||
|
||||
系统菜单采用自引用的树形结构设计，支持无限层级的菜单组织。每个菜单项包含完整的元数据信息，用于前端渲染和权限控制。
|
||||
|
||||
### 菜单类型枚举
|
||||
|
||||
系统支持两种菜单类型：
|
||||
- **菜单(Menu)**: 用于页面导航的主要菜单项
|
||||
- **按钮(Button)**: 用于页面内功能按钮的权限控制
|
||||
|
||||
### 菜单字段定义
|
||||
|
||||
| 字段名 | 数据类型 | 是否可空 | 默认值 | 描述 |
|
||||
|--------|----------|----------|--------|------|
|
||||
| id | Integer | 否 | 自增 | 菜单唯一标识符 |
|
||||
| parent_id | Integer | 是 | NULL | 父菜单ID，自引用外键 |
|
||||
| menu_type | Enum | 否 | menu | 菜单类型(MENU/BUTTON) |
|
||||
| menu_name | String(100) | 否 | - | 菜单显示名称 |
|
||||
| menu_icon | String(50) | 是 | NULL | Element Plus图标名称 |
|
||||
| path | String(200) | 否 | - | Vue Router路由路径 |
|
||||
| component | String(200) | 是 | NULL | 页面组件路径 |
|
||||
| permission | String(100) | 是 | NULL | 权限标识符 |
|
||||
| sort_order | Integer | 否 | 0 | 排序权重 |
|
||||
| is_visible | Boolean | 否 | TRUE | 是否在菜单中显示 |
|
||||
| is_active | Boolean | 否 | TRUE | 菜单是否启用 |
|
||||
| created_at | DateTime | 否 | 当前时间 | 创建时间戳 |
|
||||
| updated_at | DateTime | 否 | 当前时间 | 更新时间戳 |
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L347-L373)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L590-L638)
|
||||
|
||||
## 架构概览
|
||||
|
||||
系统菜单架构采用经典的三层架构模式，实现了完整的菜单生命周期管理：
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as 前端客户端
|
||||
participant API as 菜单API
|
||||
participant Service as 菜单服务
|
||||
participant Model as 数据模型
|
||||
participant DB as 数据库
|
||||
Client->>API : GET /menus/tree?visible_only=true
|
||||
API->>Service : get_tree(visible_only)
|
||||
Service->>Model : 查询菜单树
|
||||
Model->>DB : SQL查询
|
||||
DB-->>Model : 菜单数据
|
||||
Model-->>Service : 菜单对象
|
||||
Service->>Service : 转换为字典结构
|
||||
Service-->>API : 菜单树数据
|
||||
API-->>Client : JSON响应
|
||||
Note over Client,DB : 菜单树形结构加载流程
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [menus.py](file://backend/app/api/v1/menus.py#L17-L29)
|
||||
- [menu_service.py](file://backend/app/services/menu_service.py#L16-L29)
|
||||
|
||||
**章节来源**
|
||||
- [menus.py](file://backend/app/api/v1/menus.py#L17-L29)
|
||||
- [menu_service.py](file://backend/app/services/menu_service.py#L16-L29)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 菜单树形结构设计
|
||||
|
||||
系统采用自引用关系实现菜单树形结构，支持无限层级嵌套：
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class Menu {
|
||||
+Integer id
|
||||
+Integer parent_id
|
||||
+MenuType menu_type
|
||||
+String menu_name
|
||||
+String menu_icon
|
||||
+String path
|
||||
+String component
|
||||
+String permission
|
||||
+Integer sort_order
|
||||
+Boolean is_visible
|
||||
+Boolean is_active
|
||||
+DateTime created_at
|
||||
+DateTime updated_at
|
||||
+children : Menu[]
|
||||
+parent : Menu
|
||||
}
|
||||
class MenuType {
|
||||
<<enumeration>>
|
||||
MENU
|
||||
BUTTON
|
||||
}
|
||||
Menu --> Menu : "parent_id -> id"
|
||||
Menu --> Menu : "children"
|
||||
Menu --> MenuType : "uses"
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [models.py](file://backend/app/models/models.py#L347-L373)
|
||||
- [models.py](file://backend/app/models/models.py#L341-L345)
|
||||
|
||||
### 菜单权限控制机制
|
||||
|
||||
系统实现了多层次的权限控制体系：
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([用户请求菜单]) --> CheckAuth["检查用户认证"]
|
||||
CheckAuth --> AuthOK{"认证通过?"}
|
||||
AuthOK --> |否| Deny["拒绝访问"]
|
||||
AuthOK --> |是| LoadTree["加载菜单树"]
|
||||
LoadTree --> FilterVisible["过滤可见菜单"]
|
||||
FilterVisible --> FilterActive["过滤启用菜单"]
|
||||
FilterActive --> SortOrder["按排序字段排序"]
|
||||
SortOrder --> BuildTree["构建菜单树"]
|
||||
BuildTree --> ReturnMenu["返回菜单数据"]
|
||||
Deny --> End([结束])
|
||||
ReturnMenu --> End
|
||||
style Start fill:#e1f5fe
|
||||
style End fill:#ffebee
|
||||
style Deny fill:#ffebee
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [menu_service.py](file://backend/app/services/menu_service.py#L16-L29)
|
||||
- [security.py](file://backend/app/core/security.py#L85-L91)
|
||||
|
||||
### 菜单排序机制
|
||||
|
||||
系统支持多维度排序控制：
|
||||
|
||||
1. **主排序**: `sort_order` 字段，数值越小优先级越高
|
||||
2. **次排序**: `id` 字段，确保相同排序值的稳定性
|
||||
3. **层级排序**: 顶级菜单优先于子菜单
|
||||
|
||||
**章节来源**
|
||||
- [menu_service.py](file://backend/app/services/menu_service.py#L24-L24)
|
||||
- [menu_service.py](file://backend/app/services/menu_service.py#L49-L49)
|
||||
|
||||
### 菜单可见性控制
|
||||
|
||||
系统通过两个独立字段控制菜单的显示状态：
|
||||
|
||||
| 控制字段 | 类型 | 默认值 | 作用域 | 影响范围 |
|
||||
|----------|------|--------|--------|----------|
|
||||
| is_visible | Boolean | TRUE | 菜单树渲染 | 前端菜单树显示 |
|
||||
| is_active | Boolean | TRUE | 功能启用 | 菜单功能可用性 |
|
||||
|
||||
**章节来源**
|
||||
- [menu_service.py](file://backend/app/services/menu_service.py#L20-L21)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L600-L601)
|
||||
|
||||
### 菜单与功能权限关联
|
||||
|
||||
系统通过 `permission` 字段实现菜单与功能权限的关联：
|
||||
|
||||
```mermaid
|
||||
erDiagram
|
||||
MENUS {
|
||||
int id PK
|
||||
int parent_id FK
|
||||
enum menu_type
|
||||
string menu_name
|
||||
string menu_icon
|
||||
string path
|
||||
string component
|
||||
string permission
|
||||
int sort_order
|
||||
boolean is_visible
|
||||
boolean is_active
|
||||
datetime created_at
|
||||
datetime updated_at
|
||||
}
|
||||
USERS {
|
||||
int id PK
|
||||
string username UK
|
||||
string password_hash
|
||||
string role
|
||||
boolean is_active
|
||||
datetime last_login
|
||||
datetime created_at
|
||||
datetime updated_at
|
||||
}
|
||||
USER_PERMISSIONS {
|
||||
int user_id FK
|
||||
string permission
|
||||
boolean granted
|
||||
datetime granted_at
|
||||
}
|
||||
MENUS ||--o{ MENUS : "parent_id -> id"
|
||||
USERS ||--o{ USER_PERMISSIONS : "has"
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [models.py](file://backend/app/models/models.py#L347-L373)
|
||||
- [security.py](file://backend/app/core/security.py#L94-L109)
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L358-L358)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L598-L598)
|
||||
|
||||
### 前端菜单管理界面
|
||||
|
||||
前端提供了完整的菜单管理功能：
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Admin as 管理员
|
||||
participant View as 菜单管理界面
|
||||
participant API as 菜单API
|
||||
participant Service as 菜单服务
|
||||
participant DB as 数据库
|
||||
Admin->>View : 打开菜单管理页面
|
||||
View->>API : 加载菜单列表
|
||||
API->>Service : get_list()
|
||||
Service->>DB : 查询菜单
|
||||
DB-->>Service : 菜单数据
|
||||
Service-->>API : 菜单列表
|
||||
API-->>View : 返回数据
|
||||
View-->>Admin : 显示菜单表格
|
||||
Admin->>View : 新建菜单
|
||||
View->>API : create_menu()
|
||||
API->>Service : create()
|
||||
Service->>DB : 插入菜单
|
||||
DB-->>Service : 成功
|
||||
Service-->>API : 菜单对象
|
||||
API-->>View : 返回结果
|
||||
View-->>Admin : 显示成功消息
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [Menus.vue](file://frontend/src/views/system/Menus.vue#L144-L152)
|
||||
- [menu.js](file://frontend/src/api/menu.js#L18-L21)
|
||||
|
||||
**章节来源**
|
||||
- [Menus.vue](file://frontend/src/views/system/Menus.vue#L1-L265)
|
||||
- [menu.js](file://frontend/src/api/menu.js#L1-L37)
|
||||
|
||||
## 依赖分析
|
||||
|
||||
系统菜单功能涉及多个组件间的复杂依赖关系：
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "数据层"
|
||||
MenuModel[Menu模型]
|
||||
MenuType[MenuType枚举]
|
||||
end
|
||||
subgraph "业务层"
|
||||
MenuService[MenuService]
|
||||
Security[安全模块]
|
||||
end
|
||||
subgraph "接口层"
|
||||
MenuAPI[菜单API]
|
||||
Schema[数据模式]
|
||||
end
|
||||
subgraph "表现层"
|
||||
Frontend[前端界面]
|
||||
Router[Vue Router]
|
||||
end
|
||||
MenuAPI --> MenuService
|
||||
MenuService --> MenuModel
|
||||
MenuService --> Security
|
||||
MenuAPI --> Schema
|
||||
Frontend --> MenuAPI
|
||||
Router --> Frontend
|
||||
MenuModel --> MenuType
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [models.py](file://backend/app/models/models.py#L341-L345)
|
||||
- [models.py](file://backend/app/models/models.py#L347-L373)
|
||||
- [menu_service.py](file://backend/app/services/menu_service.py#L1-L137)
|
||||
- [menus.py](file://backend/app/api/v1/menus.py#L1-L164)
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L341-L345)
|
||||
- [models.py](file://backend/app/models/models.py#L347-L373)
|
||||
- [menu_service.py](file://backend/app/services/menu_service.py#L1-L137)
|
||||
- [menus.py](file://backend/app/api/v1/menus.py#L1-L164)
|
||||
|
||||
## 性能考虑
|
||||
|
||||
### 数据库索引优化
|
||||
|
||||
系统为菜单表建立了多个关键索引以提升查询性能：
|
||||
|
||||
| 索引名称 | 字段组合 | 用途 | 性能影响 |
|
||||
|----------|----------|------|----------|
|
||||
| idx_menu_parent | parent_id | 父子关系查询 | 快速定位子菜单 |
|
||||
| idx_menu_type | menu_type | 类型过滤查询 | 快速筛选菜单类型 |
|
||||
| idx_menu_visible | is_visible | 可见性过滤 | 快速筛选显示菜单 |
|
||||
|
||||
### 查询优化策略
|
||||
|
||||
1. **延迟加载**: 使用 `selectinload` 优化N+1查询问题
|
||||
2. **条件过滤**: 在服务层统一处理查询条件
|
||||
3. **排序优化**: 利用复合索引支持排序查询
|
||||
|
||||
### 前端性能优化
|
||||
|
||||
1. **菜单树缓存**: 避免重复加载相同的菜单树
|
||||
2. **懒加载**: 路由组件按需加载
|
||||
3. **虚拟滚动**: 大数据量时使用虚拟滚动
|
||||
|
||||
## 故障排除指南
|
||||
|
||||
### 常见问题及解决方案
|
||||
|
||||
| 问题类型 | 症状 | 可能原因 | 解决方案 |
|
||||
|----------|------|----------|----------|
|
||||
| 菜单不显示 | 菜单树为空 | is_visible=false 或 is_active=false | 检查菜单状态字段 |
|
||||
| 菜单排序异常 | 菜单顺序错误 | sort_order字段冲突 | 重新设置排序值 |
|
||||
| 子菜单无法删除 | 删除报错 | 存在子菜单依赖 | 先删除子菜单再删除父菜单 |
|
||||
| 权限控制失效 | 无权限访问 | permission字段缺失 | 添加正确的权限标识符 |
|
||||
|
||||
### 调试工具
|
||||
|
||||
1. **数据库查询**: 使用SQL查询验证菜单状态
|
||||
2. **API测试**: 使用Postman测试菜单接口
|
||||
3. **浏览器调试**: 检查前端控制台错误
|
||||
|
||||
**章节来源**
|
||||
- [menu_service.py](file://backend/app/services/menu_service.py#L86-L98)
|
||||
- [security.py](file://backend/app/core/security.py#L94-L109)
|
||||
|
||||
## 结论
|
||||
|
||||
系统菜单字段设计体现了良好的软件工程实践，通过清晰的数据模型、完善的权限控制和高效的查询机制，实现了灵活的菜单管理功能。自引用的树形结构设计支持复杂的菜单层级，而权限标识符则为细粒度的权限控制提供了基础。
|
||||
|
||||
系统的关键优势包括：
|
||||
- **灵活性**: 支持无限层级的菜单结构
|
||||
- **可扩展性**: 易于添加新的菜单类型和字段
|
||||
- **安全性**: 多层次的权限控制机制
|
||||
- **易用性**: 完整的前端管理界面
|
||||
|
||||
未来可以考虑的改进方向：
|
||||
- 增加菜单访问日志功能
|
||||
- 实现菜单模板化管理
|
||||
- 添加菜单权限继承机制
|
||||
- 优化大数据量场景下的性能表现
|
||||
454
.qoder/repowiki/zh/content/数据库设计/数据字典/绩效计划字段.md
Normal file
454
.qoder/repowiki/zh/content/数据库设计/数据字典/绩效计划字段.md
Normal file
@@ -0,0 +1,454 @@
|
||||
# 绩效计划字段
|
||||
|
||||
<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)
|
||||
- [create_plan_tables.py](file://backend/create_plan_tables.py)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py)
|
||||
- [002_template.py](file://backend/alembic/versions/002_template.py)
|
||||
- [database.md](file://docs/database.md)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构概览](#架构概览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考虑](#性能考虑)
|
||||
8. [故障排除指南](#故障排除指南)
|
||||
9. [结论](#结论)
|
||||
|
||||
## 简介
|
||||
|
||||
本文件为医院绩效系统中绩效计划相关字段的详细数据字典，涵盖以下核心实体：
|
||||
- 绩效计划表（PerformancePlan）
|
||||
- 计划层级（PlanLevel）
|
||||
- 计划状态（PlanStatus）
|
||||
- 计划指标关联表（PlanKpiRelation）
|
||||
|
||||
文档详细说明了计划层级结构、计划审批流程、指标权重分配等相关字段，并包含计划执行跟踪和状态管理的字段约束。同时提供计划与指标关联关系的数据字典说明，以及计划版本管理和变更追踪的字段设计。
|
||||
|
||||
## 项目结构
|
||||
|
||||
该系统采用典型的三层架构设计：
|
||||
- API层：处理HTTP请求和响应
|
||||
- 服务层：实现业务逻辑和工作流控制
|
||||
- 数据模型层：定义数据库表结构和关系
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "API层"
|
||||
API[performance_plans.py]
|
||||
end
|
||||
subgraph "服务层"
|
||||
Service[performance_plan_service.py]
|
||||
end
|
||||
subgraph "模型层"
|
||||
Models[models.py]
|
||||
Schemas[schemas.py]
|
||||
end
|
||||
subgraph "数据库"
|
||||
DB[(SQLite/PostgreSQL)]
|
||||
end
|
||||
API --> Service
|
||||
Service --> Models
|
||||
Models --> DB
|
||||
Schemas --> API
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [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-L339)
|
||||
|
||||
## 核心组件
|
||||
|
||||
### 绩效计划表（PerformancePlan）
|
||||
|
||||
绩效计划表是整个绩效管理体系的核心实体，用于存储各级别（医院级、科室级、个人级）的绩效计划信息。
|
||||
|
||||
#### 基础字段定义
|
||||
|
||||
| 字段名 | 类型 | 约束 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| id | Integer | 主键, 自增 | 计划唯一标识符 |
|
||||
| plan_name | String(200) | 非空 | 计划名称 |
|
||||
| plan_code | String(50) | 唯一, 非空 | 计划编码，全局唯一 |
|
||||
| plan_level | Enum | 非空 | 计划层级：hospital/department/individual |
|
||||
| plan_year | Integer | 非空 | 计划年度（2000-2100） |
|
||||
| plan_month | Integer | 可空 | 计划月份（1-12），仅月度计划使用 |
|
||||
| plan_type | String(20) | 默认 annual | 计划类型：annual/monthly |
|
||||
| department_id | Integer | 外键 | 所属科室ID |
|
||||
| staff_id | Integer | 外键 | 责任人ID |
|
||||
| parent_plan_id | Integer | 外键 | 上级计划ID，支持层级结构 |
|
||||
| description | Text | 可空 | 计划描述 |
|
||||
| strategic_goals | Text | 可空 | 战略目标 |
|
||||
| key_initiatives | Text | 可空 | 关键举措 |
|
||||
| status | Enum | 默认 draft | 计划状态：draft/pending/approved/rejected/active/completed/cancelled |
|
||||
| submitter_id | Integer | 外键 | 提交人ID |
|
||||
| submit_time | DateTime | 可空 | 提交时间 |
|
||||
| approver_id | Integer | 外键 | 审批人ID |
|
||||
| approve_time | DateTime | 可空 | 审批时间 |
|
||||
| approve_remark | Text | 可空 | 审批意见 |
|
||||
| version | Integer | 默认 1 | 版本号，用于版本管理 |
|
||||
| is_active | Boolean | 默认 TRUE | 是否启用 |
|
||||
| created_at | DateTime | 默认当前时间 | 创建时间 |
|
||||
| updated_at | DateTime | 默认当前时间 | 更新时间 |
|
||||
|
||||
#### 索引设计
|
||||
|
||||
- idx_plan_level：按计划层级查询优化
|
||||
- idx_plan_year：按年度查询优化
|
||||
- idx_plan_department：按科室查询优化
|
||||
- idx_plan_status：按状态查询优化
|
||||
|
||||
### 计划层级（PlanLevel）
|
||||
|
||||
计划层级枚举定义了绩效计划的组织层次结构：
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class PlanLevel {
|
||||
+hospital : "医院级"
|
||||
+department : "科室级"
|
||||
+individual : "个人级"
|
||||
}
|
||||
class PerformancePlan {
|
||||
+plan_level : PlanLevel
|
||||
+parent_plan_id : int
|
||||
+child_plans : PerformancePlan[]
|
||||
}
|
||||
PerformancePlan --> PlanLevel : "使用"
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [models.py](file://backend/app/models/models.py#L263-L268)
|
||||
- [models.py](file://backend/app/models/models.py#L277-L304)
|
||||
|
||||
### 计划状态（PlanStatus）
|
||||
|
||||
计划状态枚举定义了完整的审批和执行生命周期：
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> 草稿
|
||||
草稿 --> 待审批 : "提交"
|
||||
待审批 --> 已批准 : "审批通过"
|
||||
待审批 --> 已驳回 : "审批驳回"
|
||||
已批准 --> 执行中 : "激活"
|
||||
已批准 --> 已取消 : "取消"
|
||||
执行中 --> 已完成 : "完成"
|
||||
执行中 --> 已取消 : "取消"
|
||||
已完成 --> [*]
|
||||
已取消 --> [*]
|
||||
已驳回 --> [*]
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [models.py](file://backend/app/models/models.py#L233-L242)
|
||||
|
||||
### 计划指标关联表（PlanKpiRelation）
|
||||
|
||||
计划指标关联表建立了计划与具体考核指标之间的多对多关系，支持每个指标在不同计划中的差异化配置。
|
||||
|
||||
#### 关联字段定义
|
||||
|
||||
| 字段名 | 类型 | 约束 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| id | Integer | 主键, 自增 | 关联关系唯一标识符 |
|
||||
| plan_id | Integer | 外键, 非空 | 关联的计划ID |
|
||||
| indicator_id | Integer | 外键, 非空 | 关联的指标ID |
|
||||
| target_value | Decimal(10,2) | 可空 | 目标值 |
|
||||
| target_unit | String(50) | 可空 | 目标值单位 |
|
||||
| weight | Decimal(5,2) | 默认 1.0 | 权重（0-100） |
|
||||
| scoring_method | String(50) | 可空 | 评分方法 |
|
||||
| scoring_params | Text | 可空 | 评分参数（JSON格式） |
|
||||
| remark | Text | 可空 | 备注 |
|
||||
| created_at | DateTime | 默认当前时间 | 创建时间 |
|
||||
| updated_at | DateTime | 默认当前时间 | 更新时间 |
|
||||
|
||||
#### 关联关系
|
||||
|
||||
- 一对多：一个计划可以关联多个指标
|
||||
- 一对多：一个指标可以出现在多个计划中
|
||||
- 唯一约束：同一计划下的指标必须唯一
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L314-L339)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L481-L517)
|
||||
|
||||
## 架构概览
|
||||
|
||||
系统采用RESTful API设计，支持完整的CRUD操作和业务流程控制：
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as "客户端"
|
||||
participant API as "API层"
|
||||
participant Service as "服务层"
|
||||
participant Model as "模型层"
|
||||
participant DB as "数据库"
|
||||
Client->>API : GET /plans/{plan_id}
|
||||
API->>Service : get_by_id(plan_id)
|
||||
Service->>Model : 查询PerformancePlan
|
||||
Model->>DB : SQL查询
|
||||
DB-->>Model : 返回结果
|
||||
Model-->>Service : PerformancePlan对象
|
||||
Service-->>API : 格式化响应
|
||||
API-->>Client : JSON数据
|
||||
Note over Client,DB : 审批流程示例
|
||||
Client->>API : POST /plans/{plan_id}/approve
|
||||
API->>Service : approve(approver_id, approved, remark)
|
||||
Service->>Model : 更新状态和审批信息
|
||||
Model->>DB : 更新操作
|
||||
DB-->>Model : 确认更新
|
||||
Model-->>Service : 更新结果
|
||||
Service-->>API : 审批结果
|
||||
API-->>Client : 审批状态
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [performance_plans.py](file://backend/app/api/v1/performance_plans.py#L194-L241)
|
||||
- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L144-L182)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 计划层级结构
|
||||
|
||||
系统支持三级层级结构，通过parent_plan_id字段实现自关联：
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
HospitalPlan["医院级计划<br/>parent_plan_id: NULL"]
|
||||
DeptPlan1["科室级计划<br/>parent_plan_id: 医院级计划ID"]
|
||||
DeptPlan2["科室级计划<br/>parent_plan_id: 医院级计划ID"]
|
||||
IndividualPlan1["个人级计划<br/>parent_plan_id: 科室级计划ID"]
|
||||
IndividualPlan2["个人级计划<br/>parent_plan_id: 科室级计划ID"]
|
||||
HospitalPlan --> DeptPlan1
|
||||
HospitalPlan --> DeptPlan2
|
||||
DeptPlan1 --> IndividualPlan1
|
||||
DeptPlan1 --> IndividualPlan2
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [models.py](file://backend/app/models/models.py#L283-L301)
|
||||
- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L319-L341)
|
||||
|
||||
### 计划审批流程
|
||||
|
||||
审批流程严格遵循状态机设计，确保业务合规性：
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([开始]) --> Draft["草稿状态<br/>DRAFT"]
|
||||
Draft --> Submit["提交申请<br/>SUBMIT"]
|
||||
Submit --> Pending["待审批<br/>PENDING"]
|
||||
Pending --> Approve{"审批决定"}
|
||||
Approve --> |通过| Approved["已批准<br/>APPROVED"]
|
||||
Approve --> |驳回| Rejected["已驳回<br/>REJECTED"]
|
||||
Approved --> Activate["激活计划<br/>ACTIVE"]
|
||||
Activate --> Completed["完成<br/>COMPLETED"]
|
||||
Rejected --> End([结束])
|
||||
Completed --> End
|
||||
Active --> End
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L131-L182)
|
||||
|
||||
### 指标权重分配
|
||||
|
||||
指标权重分配支持动态配置，每个计划可以为相同指标设置不同的权重：
|
||||
|
||||
#### 权重约束
|
||||
- 权重范围：0-100
|
||||
- 总权重：同一计划内所有指标权重之和通常为100%
|
||||
- 动态调整：支持运行时修改权重分配
|
||||
|
||||
#### 评分参数
|
||||
支持JSON格式的评分参数，如：
|
||||
```json
|
||||
{
|
||||
"threshold": 90,
|
||||
"bonus": 1.2,
|
||||
"penalty": 0.8
|
||||
}
|
||||
```
|
||||
|
||||
**章节来源**
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L486-L488)
|
||||
- [models.py](file://backend/app/models/models.py#L323-L325)
|
||||
|
||||
### 计划执行跟踪
|
||||
|
||||
系统提供完整的过程跟踪机制：
|
||||
|
||||
#### 时间戳管理
|
||||
- created_at：记录创建时间
|
||||
- updated_at：自动更新时间戳
|
||||
- submit_time：提交时间
|
||||
- approve_time：审批时间
|
||||
|
||||
#### 版本管理
|
||||
- version字段：支持版本追踪
|
||||
- is_active：控制计划启用状态
|
||||
- 支持历史版本对比
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L288-L296)
|
||||
- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L120-L128)
|
||||
|
||||
### 计划与指标关联关系
|
||||
|
||||
关联关系通过PlanKpiRelation表实现，支持灵活的配置：
|
||||
|
||||
```mermaid
|
||||
erDiagram
|
||||
PERFORMANCE_PLANS {
|
||||
int id PK
|
||||
string plan_name
|
||||
int plan_year
|
||||
enum plan_level
|
||||
int department_id FK
|
||||
int staff_id FK
|
||||
}
|
||||
PLAN_KPI_RELATIONS {
|
||||
int id PK
|
||||
int plan_id FK
|
||||
int indicator_id FK
|
||||
decimal weight
|
||||
decimal target_value
|
||||
string target_unit
|
||||
}
|
||||
INDICATORS {
|
||||
int id PK
|
||||
string name
|
||||
string code
|
||||
enum indicator_type
|
||||
decimal weight
|
||||
}
|
||||
PERFORMANCE_PLANS ||--o{ PLAN_KPI_RELATIONS : "包含"
|
||||
INDICATORS ||--o{ PLAN_KPI_RELATIONS : "被包含"
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [models.py](file://backend/app/models/models.py#L270-L339)
|
||||
|
||||
## 依赖关系分析
|
||||
|
||||
系统采用清晰的分层依赖关系：
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
subgraph "外部依赖"
|
||||
FastAPI[FastAPI框架]
|
||||
SQLAlchemy[SQLAlchemy ORM]
|
||||
Alembic[Alembic迁移]
|
||||
end
|
||||
subgraph "内部模块"
|
||||
API[API层]
|
||||
Service[服务层]
|
||||
Models[模型层]
|
||||
Schemas[模式层]
|
||||
end
|
||||
FastAPI --> API
|
||||
SQLAlchemy --> Models
|
||||
Alembic --> Models
|
||||
API --> Service
|
||||
Service --> Models
|
||||
Service --> Schemas
|
||||
Models --> Schemas
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [performance_plans.py](file://backend/app/api/v1/performance_plans.py#L1-L18)
|
||||
- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L1-L13)
|
||||
|
||||
### 数据库迁移
|
||||
|
||||
系统使用Alembic进行数据库版本管理，支持增量升级和降级：
|
||||
|
||||
#### 迁移版本
|
||||
- 001_initial：初始版本，创建基础表结构
|
||||
- 002_template：添加指标模板相关表
|
||||
|
||||
#### 迁移特性
|
||||
- 自动检测模型变化
|
||||
- 支持安全的数据库演进
|
||||
- 提供回滚能力
|
||||
|
||||
**章节来源**
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L21-L183)
|
||||
- [002_template.py](file://backend/alembic/versions/002_template.py#L21-L96)
|
||||
|
||||
## 性能考虑
|
||||
|
||||
### 查询优化
|
||||
|
||||
1. **索引策略**
|
||||
- 多列组合索引用于常用查询条件
|
||||
- 唯一索引确保数据完整性
|
||||
- 选择性索引提升查询性能
|
||||
|
||||
2. **查询优化**
|
||||
- 使用selectinload避免N+1查询问题
|
||||
- 分页查询支持大数据集
|
||||
- 条件查询减少数据传输
|
||||
|
||||
### 缓存策略
|
||||
|
||||
- 配置适当的缓存层
|
||||
- 对静态配置数据进行缓存
|
||||
- 利用数据库连接池
|
||||
|
||||
## 故障排除指南
|
||||
|
||||
### 常见问题
|
||||
|
||||
1. **计划状态异常**
|
||||
- 检查状态转换规则
|
||||
- 验证审批权限
|
||||
- 确认时间戳完整性
|
||||
|
||||
2. **指标关联问题**
|
||||
- 验证唯一性约束
|
||||
- 检查权重分配合理性
|
||||
- 确认评分参数格式
|
||||
|
||||
3. **数据库连接问题**
|
||||
- 检查连接池配置
|
||||
- 验证迁移版本一致性
|
||||
- 监控数据库性能
|
||||
|
||||
### 调试建议
|
||||
|
||||
1. **日志记录**
|
||||
- 启用详细的API日志
|
||||
- 记录关键业务操作
|
||||
- 监控错误堆栈
|
||||
|
||||
2. **测试策略**
|
||||
- 单元测试覆盖核心逻辑
|
||||
- 集成测试验证流程
|
||||
- 性能测试评估瓶颈
|
||||
|
||||
**章节来源**
|
||||
- [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-L241)
|
||||
|
||||
## 结论
|
||||
|
||||
本数据字典详细描述了医院绩效系统中绩效计划相关的核心字段和业务逻辑。系统采用清晰的分层架构，支持完整的计划生命周期管理，包括：
|
||||
|
||||
- 多层级的组织结构支持
|
||||
- 完整的审批流程控制
|
||||
- 灵活的指标权重配置
|
||||
- 详细的执行跟踪机制
|
||||
- 强大的版本管理功能
|
||||
|
||||
通过合理的数据库设计和API接口，系统能够有效支撑医院的绩效管理体系，为不同层级的组织提供个性化的绩效管理解决方案。
|
||||
364
.qoder/repowiki/zh/content/数据库设计/数据字典/考核相关字段.md
Normal file
364
.qoder/repowiki/zh/content/数据库设计/数据字典/考核相关字段.md
Normal file
@@ -0,0 +1,364 @@
|
||||
# 考核相关字段
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [models.py](file://backend/app/models/models.py)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py)
|
||||
- [assessments.py](file://backend/app/api/v1/assessments.py)
|
||||
- [assessment_service.py](file://backend/app/services/assessment_service.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)
|
||||
- [stats.py](file://backend/app/api/v1/stats.py)
|
||||
- [database.md](file://docs/数据库设计.md)
|
||||
- [详细设计文档.md](file://docs/详细设计文档.md)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考量](#性能考量)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
本文件聚焦于“考核相关字段”的数据字典与业务规则，覆盖以下对象：
|
||||
- 考核记录表（Assessment）
|
||||
- 考核明细表（AssessmentDetail）
|
||||
- 考核状态枚举（AssessmentStatus）
|
||||
- 考核周期、状态流转、评分计算、完整性校验与一致性保障机制
|
||||
- 考核结果计算与统计分析相关字段说明
|
||||
|
||||
目标是帮助开发者与业务人员快速理解字段含义、取值范围、约束条件、状态转换与计算逻辑，并提供排障建议与最佳实践。
|
||||
|
||||
## 项目结构
|
||||
后端采用分层架构：API 控制器 → 服务层 → ORM 模型；前端通过 API 与后端交互，展示与操作考核流程。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
FE["前端视图<br/>Assessments.vue / AssessmentDetail.vue"] --> API["FastAPI 路由<br/>assessments.py"]
|
||||
API --> SVC["服务层<br/>assessment_service.py"]
|
||||
SVC --> DB["SQLAlchemy 模型<br/>models.py"]
|
||||
DB --> SQL["数据库表<br/>assessments / assessment_details"]
|
||||
API --> STATS["统计接口<br/>stats.py"]
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L1-L311)
|
||||
- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L1-L96)
|
||||
- [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#L149-L202)
|
||||
- [stats.py](file://backend/app/api/v1/stats.py#L1-L242)
|
||||
|
||||
章节来源
|
||||
- [Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L1-L311)
|
||||
- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L1-L96)
|
||||
- [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#L149-L202)
|
||||
- [stats.py](file://backend/app/api/v1/stats.py#L1-L242)
|
||||
|
||||
## 核心组件
|
||||
- Assessment（考核记录表）
|
||||
- 关键字段：period_year、period_month、period_type、total_score、weighted_score、status、assessor_id、reviewer_id、submit_time、review_time、remark
|
||||
- 业务规则：按月度周期生成记录；总分与加权得分由明细计算；状态驱动流程推进
|
||||
- AssessmentDetail（考核明细表）
|
||||
- 关键字段：assessment_id、indicator_id、actual_value、score、evidence、remark
|
||||
- 业务规则：每个指标一条明细；得分与佐证材料可编辑（草稿态）
|
||||
- AssessmentStatus（考核状态枚举）
|
||||
- 草稿（draft）、已提交（submitted）、已审核（reviewed）、已确认（finalized）、已驳回（rejected）
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L149-L202)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L31-L36)
|
||||
- [assessment_service.py](file://backend/app/services/assessment_service.py#L70-L108)
|
||||
|
||||
## 架构总览
|
||||
考核流程由前端触发，经 API 路由进入服务层，持久化到数据库模型，最终支持统计分析。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant FE as "前端"
|
||||
participant API as "API 路由"
|
||||
participant SVC as "服务层"
|
||||
participant DB as "模型/数据库"
|
||||
FE->>API : "提交/审核/确认"
|
||||
API->>SVC : "调用对应方法"
|
||||
SVC->>DB : "读取/更新 Assessment/Details"
|
||||
DB-->>SVC : "返回实体"
|
||||
SVC-->>API : "返回处理结果"
|
||||
API-->>FE : "返回响应"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [assessments.py](file://backend/app/api/v1/assessments.py#L105-L145)
|
||||
- [assessment_service.py](file://backend/app/services/assessment_service.py#L158-L205)
|
||||
- [Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L227-L255)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### Assessment（考核记录表）数据字典
|
||||
- 字段定义与约束
|
||||
- id：主键，自增整数
|
||||
- staff_id：外键指向员工，必填
|
||||
- period_year：整数，必填，年份范围约束见后端校验
|
||||
- period_month：整数，必填，1-12
|
||||
- period_type：字符串，默认 monthly
|
||||
- total_score：数值，总分，创建时由明细得分求和
|
||||
- weighted_score：数值，加权得分，按指标权重加权求和
|
||||
- status：状态枚举，默认 draft
|
||||
- assessor_id：外键，考核人
|
||||
- reviewer_id：外键，审核人
|
||||
- submit_time：提交时间
|
||||
- review_time：审核时间
|
||||
- remark：备注
|
||||
- created_at/updated_at：时间戳
|
||||
|
||||
- 业务规则
|
||||
- 考核周期：以年/月为单位，period_type 默认 monthly
|
||||
- 总分与加权得分：由明细聚合计算
|
||||
- 状态流转：草稿 → 已提交 → 已审核 → 已确认；或草稿 → 已驳回
|
||||
- 时间字段：提交/审核时写入对应时间
|
||||
|
||||
- 约束与索引
|
||||
- 索引：staff_id、period_year+period_month、status
|
||||
- 约束：状态枚举值限定
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L149-L178)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L220-L257)
|
||||
- [assessment_service.py](file://backend/app/services/assessment_service.py#L70-L108)
|
||||
- [database.md](file://docs/数据库设计.md#L159-L177)
|
||||
|
||||
### AssessmentDetail（考核明细表）数据字典
|
||||
- 字段定义与约束
|
||||
- id：主键，自增整数
|
||||
- assessment_id：外键，必填
|
||||
- indicator_id：外键，必填
|
||||
- actual_value：实际值，可选
|
||||
- score：数值，得分，创建默认 0
|
||||
- evidence：佐证材料，可选
|
||||
- remark：备注
|
||||
- created_at/updated_at：时间戳
|
||||
|
||||
- 业务规则
|
||||
- 每个指标一条明细
|
||||
- 草稿态允许编辑得分与佐证材料
|
||||
- 服务层在创建/更新时重新计算总分与加权得分
|
||||
|
||||
- 约束与索引
|
||||
- 索引：assessment_id、indicator_id
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L181-L202)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L196-L218)
|
||||
- [assessment_service.py](file://backend/app/services/assessment_service.py#L70-L108)
|
||||
|
||||
### AssessmentStatus（考核状态枚举）数据字典
|
||||
- 枚举值
|
||||
- draft：草稿
|
||||
- submitted：已提交
|
||||
- reviewed：已审核
|
||||
- finalized：已确认
|
||||
- rejected：已驳回
|
||||
|
||||
- 状态转换规则
|
||||
- 草稿 → 已提交（提交）
|
||||
- 已提交 → 已审核 或 已驳回（审核）
|
||||
- 已审核 → 已确认（确认）
|
||||
- 草稿/已驳回 → 可更新（更新时仅允许草稿或已驳回）
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L45-L52)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L31-L36)
|
||||
- [assessment_service.py](file://backend/app/services/assessment_service.py#L158-L205)
|
||||
|
||||
### 考核周期与状态流转
|
||||
- 考核周期
|
||||
- 默认周期类型为 monthly
|
||||
- 不同指标模板可配置周期（如年度、季度），但记录层面以年/月为单位
|
||||
- 状态流转
|
||||
- 提交：将状态从草稿改为已提交并记录提交时间
|
||||
- 审核：将状态从已提交改为已审核或已驳回，并记录审核时间
|
||||
- 确认：将状态从已审核改为已确认
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> 草稿
|
||||
草稿 --> 已提交 : "提交"
|
||||
已提交 --> 已审核 : "审核通过"
|
||||
已提交 --> 已驳回 : "审核驳回"
|
||||
已审核 --> 已确认 : "确认"
|
||||
已确认 --> [*]
|
||||
已驳回 --> 草稿 : "重新编辑"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [assessment_service.py](file://backend/app/services/assessment_service.py#L158-L205)
|
||||
- [Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L57-L63)
|
||||
|
||||
章节来源
|
||||
- [assessment_service.py](file://backend/app/services/assessment_service.py#L158-L205)
|
||||
- [Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L57-L63)
|
||||
|
||||
### 评分计算与字段约束
|
||||
- 总分计算
|
||||
- 总分 = 明细得分之和
|
||||
- 加权得分计算
|
||||
- 加权得分 = Σ(明细得分 × 指标权重)
|
||||
- 权重来自指标表（指标权重 > 0）
|
||||
- 字段约束
|
||||
- 指标权重必须大于 0（数据库 CheckConstraint）
|
||||
- 年度/月份范围在 Pydantic 层面有限制
|
||||
- 得分字段有最小值 0 的约束
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["创建/更新考核"]) --> LoadDetails["加载明细与指标"]
|
||||
LoadDetails --> SumScore["总分 = Σ 明细.score"]
|
||||
LoadDetails --> WeightCalc["加权得分 = Σ 明细.score × 指标.weight"]
|
||||
SumScore --> SaveAssessment["保存 Assessment"]
|
||||
WeightCalc --> SaveAssessment
|
||||
SaveAssessment --> End(["完成"])
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [assessment_service.py](file://backend/app/services/assessment_service.py#L70-L108)
|
||||
- [models.py](file://backend/app/models/models.py#L149-L178)
|
||||
|
||||
章节来源
|
||||
- [assessment_service.py](file://backend/app/services/assessment_service.py#L70-L108)
|
||||
- [models.py](file://backend/app/models/models.py#L149-L178)
|
||||
|
||||
### 完整性检查与一致性保障
|
||||
- 前端约束
|
||||
- 草稿态允许编辑得分与佐证材料，得分上限为指标最大分值
|
||||
- 状态按钮随状态变化显示
|
||||
- 后端约束
|
||||
- 状态流转严格限制（仅草稿/已驳回可更新；仅已提交可审核；仅已审核可确认）
|
||||
- 批量创建时按年/月/员工去重，避免重复记录
|
||||
- 指标权重 > 0 的数据库约束
|
||||
- 统计一致性
|
||||
- 统计接口基于当前周期与部门维度聚合，确保跨部门/跨周期对比一致
|
||||
|
||||
章节来源
|
||||
- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L57-L96)
|
||||
- [Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L57-L63)
|
||||
- [assessment_service.py](file://backend/app/services/assessment_service.py#L208-L262)
|
||||
- [models.py](file://backend/app/models/models.py#L144-L146)
|
||||
|
||||
### 考核结果计算与统计分析
|
||||
- 计算字段
|
||||
- total_score：总分
|
||||
- weighted_score：加权得分
|
||||
- 统计接口
|
||||
- 科室绩效统计、周期统计、趋势分析、排名等
|
||||
- 前端展示平均分、总人数、奖金汇总等
|
||||
|
||||
章节来源
|
||||
- [stats.py](file://backend/app/api/v1/stats.py#L36-L242)
|
||||
- [Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L31-L74)
|
||||
|
||||
## 依赖关系分析
|
||||
- 模型层
|
||||
- Assessment ←→ AssessmentDetail（一对多）
|
||||
- Assessment ←→ Staff（多对一）
|
||||
- AssessmentDetail ←→ Indicator（多对一）
|
||||
- 服务层
|
||||
- 服务层负责状态流转、计算与批量创建
|
||||
- API 层
|
||||
- 提供 CRUD、提交、审核、确认、批量创建等接口
|
||||
- 前端
|
||||
- 视图根据状态动态渲染按钮与输入框
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
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
|
||||
}
|
||||
class AssessmentDetail {
|
||||
+int id
|
||||
+int assessment_id
|
||||
+int indicator_id
|
||||
+float actual_value
|
||||
+float score
|
||||
+string evidence
|
||||
+string remark
|
||||
}
|
||||
class Staff
|
||||
class Indicator
|
||||
Assessment "1" o-- "*" AssessmentDetail : "明细"
|
||||
Assessment "many" --> "1" Staff : "员工"
|
||||
AssessmentDetail "many" --> "1" Indicator : "指标"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [models.py](file://backend/app/models/models.py#L149-L202)
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L149-L202)
|
||||
|
||||
## 性能考量
|
||||
- 查询性能
|
||||
- 为 staff_id、period_year+period_month、status 建立索引，有利于筛选与排序
|
||||
- 写入性能
|
||||
- 批量创建时按部门与周期预检，避免重复记录
|
||||
- 计算性能
|
||||
- 总分与加权得分在服务层一次性计算，减少多次往返
|
||||
- 建议
|
||||
- 对高频查询增加复合索引
|
||||
- 对大表进行分区或归档策略（如历史周期）
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L174-L178)
|
||||
- [assessment_service.py](file://backend/app/services/assessment_service.py#L208-L262)
|
||||
|
||||
## 故障排查指南
|
||||
- 常见问题
|
||||
- 状态不可变更：仅草稿/已驳回可更新；仅已提交可审核；仅已审核可确认
|
||||
- 无法提交/审核/确认：检查当前状态是否符合预期
|
||||
- 批量创建重复：系统按 staff_id+period_year+period_month 去重
|
||||
- 指标权重异常：数据库约束要求权重 > 0
|
||||
- 前端定位
|
||||
- 查看状态标签与按钮可用性
|
||||
- 校验得分上限与佐证材料输入
|
||||
- 后端定位
|
||||
- 检查服务层状态判断与时间字段写入
|
||||
- 核对明细聚合逻辑与指标权重
|
||||
|
||||
章节来源
|
||||
- [assessment_service.py](file://backend/app/services/assessment_service.py#L158-L205)
|
||||
- [Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L57-L63)
|
||||
- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L57-L96)
|
||||
|
||||
## 结论
|
||||
本数据字典明确了考核记录与明细的核心字段、状态流转、评分计算与约束条件，并结合前后端实现展示了完整的业务闭环。遵循上述规则可确保数据一致性与流程可控性，同时为后续扩展（如维度得分、模板周期等）提供清晰边界。
|
||||
|
||||
## 附录
|
||||
- API 路由与前端交互
|
||||
- 列表/详情/创建/更新/提交/审核/确认/批量创建
|
||||
- 前端通过 assessment.js 发起请求，Assessments.vue 与 AssessmentDetail.vue 控制 UI 行为
|
||||
|
||||
章节来源
|
||||
- [assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
|
||||
- [assessment.js](file://frontend/src/api/assessment.js#L1-L50)
|
||||
- [Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L1-L311)
|
||||
- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L1-L96)
|
||||
438
.qoder/repowiki/zh/content/数据库设计/数据库设计.md
Normal file
438
.qoder/repowiki/zh/content/数据库设计/数据库设计.md
Normal file
@@ -0,0 +1,438 @@
|
||||
# 数据库设计
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py)
|
||||
- [backend/app/models/finance.py](file://backend/app/models/finance.py)
|
||||
- [backend/alembic/versions/001_initial.py](file://backend/alembic/versions/001_initial.py)
|
||||
- [backend/alembic/versions/002_template.py](file://backend/alembic/versions/002_template.py)
|
||||
- [backend/alembic/env.py](file://backend/alembic/env.py)
|
||||
- [backend/alembic.ini](file://backend/alembic.ini)
|
||||
- [backend/app/core/database.py](file://backend/app/core/database.py)
|
||||
- [backend/app/core/config.py](file://backend/app/core/config.py)
|
||||
- [backend/init_db.py](file://backend/init_db.py)
|
||||
- [docs/database.md](file://docs/database.md)
|
||||
- [docs/详细设计文档.md](file://docs/详细设计文档.md)
|
||||
- [backend/create_menu_tables.py](file://backend/create_menu_tables.py)
|
||||
- [backend/create_plan_tables.py](file://backend/create_plan_tables.py)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖分析](#依赖分析)
|
||||
7. [性能考虑](#性能考虑)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
本文件面向“医院绩效系统”的数据库设计，围绕核心数据模型（Department、Staff、Assessment、AssessmentDetail、SalaryRecord）给出完整的ER实体关系图、表结构与字段定义、主键/外键/索引/约束设计原则、数据类型与长度限制、业务规则实现、数据字典、典型数据示例、数据库迁移策略与版本管理、以及性能优化建议。文档同时结合后端模型定义与迁移脚本，确保设计与实现一致。
|
||||
|
||||
## 项目结构
|
||||
后端采用 SQLAlchemy ORM + Alembic 进行模型定义与迁移管理，数据库连接通过异步引擎实现；迁移脚本位于 alembic/versions 下，环境配置由 alembic/env.py 和 alembic.ini 提供；核心模型集中在 backend/app/models/models.py，财务相关模型在 backend/app/models/finance.py。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "数据库层"
|
||||
DB[(PostgreSQL/SQLite)]
|
||||
end
|
||||
subgraph "迁移与配置"
|
||||
AEnv["alembic/env.py"]
|
||||
AIni["alembic.ini"]
|
||||
V001["versions/001_initial.py"]
|
||||
V002["versions/002_template.py"]
|
||||
end
|
||||
subgraph "模型与服务"
|
||||
Models["models.py<br/>核心模型"]
|
||||
Finance["finance.py<br/>财务模型"]
|
||||
DBMod["database.py<br/>异步引擎/会话"]
|
||||
Cfg["config.py<br/>配置"]
|
||||
InitDB["init_db.py<br/>初始化脚本"]
|
||||
end
|
||||
AEnv --> V001
|
||||
AEnv --> V002
|
||||
AIni --> AEnv
|
||||
DBMod --> Models
|
||||
DBMod --> Finance
|
||||
Cfg --> DBMod
|
||||
InitDB --> Models
|
||||
InitDB --> DBMod
|
||||
Models --> DB
|
||||
Finance --> DB
|
||||
V001 --> DB
|
||||
V002 --> DB
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [backend/alembic/env.py](file://backend/alembic/env.py#L1-L66)
|
||||
- [backend/alembic/versions/001_initial.py](file://backend/alembic/versions/001_initial.py#L1-L183)
|
||||
- [backend/alembic/versions/002_template.py](file://backend/alembic/versions/002_template.py#L1-L96)
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L438)
|
||||
- [backend/app/models/finance.py](file://backend/app/models/finance.py#L1-L79)
|
||||
- [backend/app/core/database.py](file://backend/app/core/database.py#L1-L39)
|
||||
- [backend/app/core/config.py](file://backend/app/core/config.py#L1-L47)
|
||||
- [backend/init_db.py](file://backend/init_db.py#L1-L83)
|
||||
|
||||
章节来源
|
||||
- [backend/alembic/env.py](file://backend/alembic/env.py#L1-L66)
|
||||
- [backend/alembic/versions/001_initial.py](file://backend/alembic/versions/001_initial.py#L1-L183)
|
||||
- [backend/alembic/versions/002_template.py](file://backend/alembic/versions/002_template.py#L1-L96)
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L438)
|
||||
- [backend/app/models/finance.py](file://backend/app/models/finance.py#L1-L79)
|
||||
- [backend/app/core/database.py](file://backend/app/core/database.py#L1-L39)
|
||||
- [backend/app/core/config.py](file://backend/app/core/config.py#L1-L47)
|
||||
- [backend/init_db.py](file://backend/init_db.py#L1-L83)
|
||||
|
||||
## 核心组件
|
||||
本节聚焦于系统的核心数据模型：Department（科室）、Staff（员工）、Assessment（考核记录）、AssessmentDetail（考核明细）、SalaryRecord（工资核算记录）。这些模型通过外键形成稳定的层次关系，支撑绩效计划、指标模板、财务核算等扩展能力。
|
||||
|
||||
- Department（科室）
|
||||
- 主键：id
|
||||
- 外键：parent_id → departments.id（自关联，支持多级组织树）
|
||||
- 索引：idx_dept_type、idx_dept_parent
|
||||
- 约束：code 唯一；is_active 默认启用
|
||||
- 关系：与 Staff 一对多；与自身一对一（子/父）
|
||||
|
||||
- Staff（员工）
|
||||
- 主键：id
|
||||
- 外键：department_id → departments.id
|
||||
- 索引：idx_staff_dept、idx_staff_status
|
||||
- 约束：employee_id 唯一；status 枚举；base_salary/performance_ratio 数值范围合理
|
||||
- 关系：与 Department 多对一；与 Assessment、SalaryRecord 一对多
|
||||
|
||||
- Assessment（考核记录）
|
||||
- 主键：id
|
||||
- 外键：staff_id → staff.id；assessor_id/reviewer_id → staff.id（自关联）
|
||||
- 索引：idx_assessment_staff、idx_assessment_period、idx_assessment_status
|
||||
- 约束：period_year/period_month 组合用于周期查询；status 枚举
|
||||
- 关系：与 Staff 多对一；与 AssessmentDetail 一对多（级联删除）
|
||||
|
||||
- AssessmentDetail（考核明细）
|
||||
- 主键：id
|
||||
- 外键：assessment_id → assessments.id；indicator_id → indicators.id
|
||||
- 索引：idx_detail_assessment、idx_detail_indicator
|
||||
- 关系：与 Assessment、Indicator 多对一
|
||||
|
||||
- SalaryRecord（工资核算记录）
|
||||
- 主键：id
|
||||
- 外键：staff_id → staff.id
|
||||
- 索引：idx_salary_staff、idx_salary_period
|
||||
- 约束：total_salary 由基础字段计算得出；status 字符串枚举
|
||||
- 关系：与 Staff 多对一
|
||||
|
||||
章节来源
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L230)
|
||||
|
||||
## 架构总览
|
||||
下图展示核心模型之间的实体关系与依赖方向，体现从组织结构到人员、再到考核与薪酬的完整闭环。
|
||||
|
||||
```mermaid
|
||||
erDiagram
|
||||
DEPARTMENTS {
|
||||
int id PK
|
||||
string name
|
||||
string code UK
|
||||
string dept_type
|
||||
int parent_id FK
|
||||
int level
|
||||
int sort_order
|
||||
boolean is_active
|
||||
text description
|
||||
datetime created_at
|
||||
datetime updated_at
|
||||
}
|
||||
STAFF {
|
||||
int id PK
|
||||
string employee_id UK
|
||||
string name
|
||||
int department_id FK
|
||||
string position
|
||||
string title
|
||||
string phone
|
||||
string email
|
||||
numeric base_salary
|
||||
numeric performance_ratio
|
||||
string status
|
||||
datetime hire_date
|
||||
datetime created_at
|
||||
datetime updated_at
|
||||
}
|
||||
ASSESSMENTS {
|
||||
int id PK
|
||||
int staff_id FK
|
||||
int period_year
|
||||
int period_month
|
||||
string period_type
|
||||
numeric total_score
|
||||
numeric weighted_score
|
||||
string status
|
||||
int assessor_id FK
|
||||
int reviewer_id FK
|
||||
datetime submit_time
|
||||
datetime review_time
|
||||
text remark
|
||||
datetime created_at
|
||||
datetime updated_at
|
||||
}
|
||||
ASSESSMENT_DETAILS {
|
||||
int id PK
|
||||
int assessment_id FK
|
||||
int indicator_id FK
|
||||
numeric actual_value
|
||||
numeric score
|
||||
text evidence
|
||||
text remark
|
||||
datetime created_at
|
||||
datetime updated_at
|
||||
}
|
||||
SALARY_RECORDS {
|
||||
int id PK
|
||||
int staff_id FK
|
||||
int period_year
|
||||
int period_month
|
||||
numeric base_salary
|
||||
numeric performance_score
|
||||
numeric performance_bonus
|
||||
numeric deduction
|
||||
numeric allowance
|
||||
numeric total_salary
|
||||
string status
|
||||
text remark
|
||||
datetime created_at
|
||||
datetime updated_at
|
||||
}
|
||||
DEPARTMENTS ||--o{ STAFF : "1:N"
|
||||
STAFF ||--o{ ASSESSMENTS : "1:N"
|
||||
STAFF ||--o{ SALARY_RECORDS : "1:N"
|
||||
ASSESSMENTS ||--o{ ASSESSMENT_DETAILS : "1:N"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L230)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### Department（科室）分析
|
||||
- 设计要点
|
||||
- 自关联 parent_id 支持多层级组织树，level 与 sort_order 辅助排序与层级判断。
|
||||
- dept_type 使用枚举，统一管理 9 类科室类型，便于筛选与报表统计。
|
||||
- idx_dept_type、idx_dept_parent 提升按类型与父子关系的查询效率。
|
||||
- 业务规则
|
||||
- code 唯一，保证科室编码规范；is_active 控制启用状态。
|
||||
- 典型数据示例
|
||||
- 内科、外科、妇产科、儿科、放射科、检验科、财务科、人事科等。
|
||||
|
||||
章节来源
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L86)
|
||||
- [backend/init_db.py](file://backend/init_db.py#L27-L39)
|
||||
|
||||
### Staff（员工）分析
|
||||
- 设计要点
|
||||
- employee_id 唯一，作为外部识别码；department_id 外键关联科室。
|
||||
- base_salary 与 performance_ratio 为薪酬计算基础；status 枚举管理在职状态。
|
||||
- idx_staff_dept、idx_staff_status 优化按科室与状态的检索。
|
||||
- 业务规则
|
||||
- hire_date 记录入职时间；updated_at 自动更新时间戳。
|
||||
- 典型数据示例
|
||||
- 张三、李四、王五、赵六、钱七、孙八、周九、吴十等员工信息。
|
||||
|
||||
章节来源
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L88-L115)
|
||||
- [backend/init_db.py](file://backend/init_db.py#L42-L53)
|
||||
|
||||
### Assessment（考核记录）分析
|
||||
- 设计要点
|
||||
- period_year 与 period_month 组合唯一性可用于周期性考核的快速定位。
|
||||
- assessor_id 与 reviewer_id 自关联 staff，支持多人协作与审核流程。
|
||||
- status 枚举覆盖草稿、提交、审核、确认、驳回等状态流转。
|
||||
- idx_assessment_staff、idx_assessment_period、idx_assessment_status 提升查询性能。
|
||||
- 业务规则
|
||||
- total_score 与 weighted_score 用于汇总与加权计算；submit_time、review_time 记录关键节点时间。
|
||||
- 典型数据示例
|
||||
- 某员工某年某月的考核记录，包含多个指标得分与佐证材料链接。
|
||||
|
||||
章节来源
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L149-L179)
|
||||
|
||||
### AssessmentDetail（考核明细）分析
|
||||
- 设计要点
|
||||
- assessment_id 与 indicator_id 组成明细项，支持多指标、多周期的细粒度记录。
|
||||
- actual_value 与 score 记录实际值与得分；evidence 与 remark 支持审计与说明。
|
||||
- idx_detail_assessment、idx_detail_indicator 优化明细查询。
|
||||
- 业务规则
|
||||
- 与 Assessment 的级联删除保证数据一致性；与 Indicator 的关联确保指标有效性。
|
||||
|
||||
章节来源
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L181-L203)
|
||||
|
||||
### SalaryRecord（工资核算记录）分析
|
||||
- 设计要点
|
||||
- period_year 与 period_month 组合用于月度工资归集；staff_id 外键关联员工。
|
||||
- total_salary 由基础字段计算，避免冗余存储；status 字符串枚举控制流程状态。
|
||||
- idx_salary_staff、idx_salary_period 优化按员工与周期的检索。
|
||||
- 业务规则
|
||||
- 仅允许待确认状态下的更新；最终结算后冻结变更。
|
||||
- 典型数据示例
|
||||
- 基本工资、绩效得分、绩效奖金、扣款、补贴、应发工资等字段构成完整薪酬清单。
|
||||
|
||||
章节来源
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L205-L230)
|
||||
|
||||
### 财务核算模型（DepartmentFinance）分析
|
||||
- 设计要点
|
||||
- department_id 外键关联科室；finance_type 与 category 组合区分收入/支出与具体类别。
|
||||
- amount 使用数值类型并带非负校验；period_year/period_month 用于月度归集。
|
||||
- idx_finance_dept、idx_finance_period、idx_finance_type、idx_finance_category 提升财务报表查询效率。
|
||||
- 业务规则
|
||||
- amount ≥ 0；category 与 finance_type 枚举化，便于多维分析。
|
||||
|
||||
章节来源
|
||||
- [backend/app/models/finance.py](file://backend/app/models/finance.py#L45-L75)
|
||||
|
||||
### 指标模板与计划管理（扩展能力）
|
||||
- 指标模板（IndicatorTemplate）与模板指标（TemplateIndicator）
|
||||
- 通过模板类型与维度权重，支持不同科室类型的指标套用；模板与指标的多对多关系通过中间表维护。
|
||||
- idx_template_type、idx_template_active 与 idx_ti_unique 索引提升模板与关联查询效率。
|
||||
- 绩效计划（PerformancePlan）与计划指标（PlanKpiRelation）
|
||||
- 支持医院级、科室级、个人级三层计划；parent_plan_id 形成计划树；version 字段用于版本管理。
|
||||
|
||||
章节来源
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L270-L338)
|
||||
- [backend/alembic/versions/002_template.py](file://backend/alembic/versions/002_template.py#L21-L91)
|
||||
|
||||
## 依赖分析
|
||||
- 模型依赖
|
||||
- models.py 定义了核心实体与关系；finance.py 作为财务扩展模型，通过延迟导入避免循环依赖。
|
||||
- Alembic 迁移脚本 versions/001_initial.py 与 versions/002_template.py 与模型定义保持一一对应。
|
||||
- 运行时依赖
|
||||
- database.py 提供异步引擎与会话工厂；config.py 提供数据库连接字符串与池参数；env.py 与 alembic.ini 配置迁移环境。
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
Cfg["config.py"] --> DB["database.py"]
|
||||
DB --> Models["models.py"]
|
||||
DB --> Finance["finance.py"]
|
||||
AEnv["alembic/env.py"] --> V001["versions/001_initial.py"]
|
||||
AEnv --> V002["versions/002_template.py"]
|
||||
AIni["alembic.ini"] --> AEnv
|
||||
InitDB["init_db.py"] --> DB
|
||||
InitDB --> Models
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [backend/app/core/config.py](file://backend/app/core/config.py#L1-L47)
|
||||
- [backend/app/core/database.py](file://backend/app/core/database.py#L1-L39)
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L438)
|
||||
- [backend/app/models/finance.py](file://backend/app/models/finance.py#L1-L79)
|
||||
- [backend/alembic/env.py](file://backend/alembic/env.py#L1-L66)
|
||||
- [backend/alembic/versions/001_initial.py](file://backend/alembic/versions/001_initial.py#L1-L183)
|
||||
- [backend/alembic/versions/002_template.py](file://backend/alembic/versions/002_template.py#L1-L96)
|
||||
- [backend/alembic.ini](file://backend/alembic.ini#L1-L44)
|
||||
- [backend/init_db.py](file://backend/init_db.py#L1-L83)
|
||||
|
||||
章节来源
|
||||
- [backend/app/core/config.py](file://backend/app/core/config.py#L1-L47)
|
||||
- [backend/app/core/database.py](file://backend/app/core/database.py#L1-L39)
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L438)
|
||||
- [backend/app/models/finance.py](file://backend/app/models/finance.py#L1-L79)
|
||||
- [backend/alembic/env.py](file://backend/alembic/env.py#L1-L66)
|
||||
- [backend/alembic/versions/001_initial.py](file://backend/alembic/versions/001_initial.py#L1-L183)
|
||||
- [backend/alembic/versions/002_template.py](file://backend/alembic/versions/002_template.py#L1-L96)
|
||||
- [backend/alembic.ini](file://backend/alembic.ini#L1-L44)
|
||||
- [backend/init_db.py](file://backend/init_db.py#L1-L83)
|
||||
|
||||
## 性能考虑
|
||||
- 索引策略
|
||||
- 按查询热点建立复合索引：如 assessments 的 (period_year, period_month)，salary_records 的 (period_year, period_month)，有效降低周期性统计的扫描成本。
|
||||
- 对枚举字段（如 dept_type、status）建立单列索引，提升过滤效率。
|
||||
- 数值精度
|
||||
- 金额与分数使用 Numeric(precision, scale) 精确存储，避免浮点误差；例如 base_salary、performance_bonus、deduction 等均采用 DECIMAL(10,2)。
|
||||
- 查询优化
|
||||
- 使用关系预加载（relationship）减少 N+1 查询；对高频报表场景可引入物化视图或汇总表。
|
||||
- 连接池与并发
|
||||
- 通过 DATABASE_POOL_SIZE 与 DATABASE_MAX_OVERFLOW 控制连接池大小，避免高并发下的连接争用。
|
||||
- 异步执行
|
||||
- 异步引擎与会话减少阻塞，适合高吞吐的 API 场景。
|
||||
|
||||
章节来源
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L82-L86)
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L111-L115)
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L174-L179)
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L199-L203)
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L227-L230)
|
||||
- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L22)
|
||||
|
||||
## 故障排查指南
|
||||
- 迁移失败
|
||||
- 确认 alembic.ini 中 sqlalchemy.url 与 config.py 中 DATABASE_URL 一致；检查 Alembic 环境配置（env.py）是否正确指向 Base.metadata。
|
||||
- 使用离线模式验证迁移脚本语法：alembic -c backend/alembic.ini --raiseerr revision --autogenerate -m "test"。
|
||||
- 连接问题
|
||||
- 检查 DATABASE_URL 是否可达；确认数据库服务运行状态；查看 DEBUG 输出定位异常。
|
||||
- 数据不一致
|
||||
- 核对 Assessment 与 AssessmentDetail 的级联删除策略；确认 SalaryRecord 的状态机（仅待确认可更新）。
|
||||
- 初始化数据
|
||||
- 使用 init_db.py 创建表并插入测试数据；若已有数据则跳过插入逻辑，避免重复。
|
||||
|
||||
章节来源
|
||||
- [backend/alembic/env.py](file://backend/alembic/env.py#L21-L65)
|
||||
- [backend/alembic.ini](file://backend/alembic.ini#L1-L44)
|
||||
- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L22)
|
||||
- [backend/init_db.py](file://backend/init_db.py#L11-L83)
|
||||
|
||||
## 结论
|
||||
本数据库设计以 Department、Staff、Assessment、AssessmentDetail、SalaryRecord 为核心，配合财务核算与指标模板/计划管理扩展，形成从组织到个人、从指标到薪酬的完整闭环。通过合理的索引、数值精度与异步连接池配置，兼顾了查询性能与并发稳定性。借助 Alembic 的迁移机制，能够安全地演进数据库结构并管理版本。
|
||||
|
||||
## 附录
|
||||
|
||||
### 数据字典（核心表）
|
||||
- departments（科室）
|
||||
- 字段：id、name、code（UNIQUE）、dept_type、parent_id、level、sort_order、is_active、description、created_at、updated_at
|
||||
- 索引：idx_dept_type、idx_dept_parent
|
||||
- staff（员工）
|
||||
- 字段：id、employee_id（UNIQUE）、name、department_id、position、title、phone、email、base_salary、performance_ratio、status、hire_date、created_at、updated_at
|
||||
- 索引：idx_staff_dept、idx_staff_status
|
||||
- assessments（考核记录）
|
||||
- 字段：id、staff_id、period_year、period_month、period_type、total_score、weighted_score、status、assessor_id、reviewer_id、submit_time、review_time、remark、created_at、updated_at
|
||||
- 索引：idx_assessment_staff、idx_assessment_period、idx_assessment_status
|
||||
- assessment_details（考核明细）
|
||||
- 字段：id、assessment_id、indicator_id、actual_value、score、evidence、remark、created_at、updated_at
|
||||
- 索引：idx_detail_assessment、idx_detail_indicator
|
||||
- salary_records（工资核算记录）
|
||||
- 字段：id、staff_id、period_year、period_month、base_salary、performance_score、performance_bonus、deduction、allowance、total_salary、status、remark、created_at、updated_at
|
||||
- 索引：idx_salary_staff、idx_salary_period
|
||||
|
||||
章节来源
|
||||
- [docs/database.md](file://docs/database.md#L99-L216)
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L230)
|
||||
|
||||
### 数据库迁移与版本管理
|
||||
- 迁移命令
|
||||
- 生成迁移：alembic -c backend/alembic.ini --raiseerr revision --autogenerate -m "描述"
|
||||
- 升级到最新：alembic -c backend/alembic.ini upgrade head
|
||||
- 回滚一步：alembic -c backend/alembic.ini downgrade -1
|
||||
- 版本文件
|
||||
- 初始版本：versions/001_initial.py
|
||||
- 指标模板版本：versions/002_template.py
|
||||
- 环境配置
|
||||
- alembic/env.py 指向 Base.metadata 并支持异步迁移
|
||||
- alembic.ini 提供默认 SQLite 路径，生产环境请替换为 PostgreSQL URL
|
||||
|
||||
章节来源
|
||||
- [backend/alembic/env.py](file://backend/alembic/env.py#L1-L66)
|
||||
- [backend/alembic/versions/001_initial.py](file://backend/alembic/versions/001_initial.py#L21-L183)
|
||||
- [backend/alembic/versions/002_template.py](file://backend/alembic/versions/002_template.py#L21-L91)
|
||||
- [backend/alembic.ini](file://backend/alembic.ini#L1-L44)
|
||||
|
||||
### 典型数据示例
|
||||
- 科室：内科、外科、妇产科、儿科、放射科、检验科、财务科、人事科
|
||||
- 员工：张三、李四、王五、赵六、钱七、孙八、周九、吴十
|
||||
- 考核：某员工某年某月的多指标得分与佐证材料
|
||||
- 工资：基本工资、绩效得分、绩效奖金、扣款、补贴、应发工资
|
||||
|
||||
章节来源
|
||||
- [backend/init_db.py](file://backend/init_db.py#L27-L79)
|
||||
- [docs/详细设计文档.md](file://docs/详细设计文档.md#L642-L662)
|
||||
342
.qoder/repowiki/zh/content/数据库设计/数据库迁移.md
Normal file
342
.qoder/repowiki/zh/content/数据库设计/数据库迁移.md
Normal file
@@ -0,0 +1,342 @@
|
||||
# 数据库迁移
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [backend/alembic/env.py](file://backend/alembic/env.py)
|
||||
- [backend/alembic.ini](file://backend/alembic.ini)
|
||||
- [backend/alembic/versions/001_initial.py](file://backend/alembic/versions/001_initial.py)
|
||||
- [backend/alembic/versions/002_template.py](file://backend/alembic/versions/002_template.py)
|
||||
- [backend/app/core/database.py](file://backend/app/core/database.py)
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py)
|
||||
- [backend/init_db.py](file://backend/init_db.py)
|
||||
- [backend/create_menu_tables.py](file://backend/create_menu_tables.py)
|
||||
- [backend/migrate_indicators.py](file://backend/migrate_indicators.py)
|
||||
- [backend/init_indicator_templates.py](file://backend/init_indicator_templates.py)
|
||||
- [backend/app/core/config.py](file://backend/app/core/config.py)
|
||||
- [docs/database.md](file://docs/database.md)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考量](#性能考量)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
本设计文档围绕基于 Alembic 的数据库迁移框架展开，系统阐述版本化数据库变更管理流程、迁移策略与最佳实践，并结合仓库现有迁移脚本与模型定义，给出迁移脚本编写规范、命名约定、初始结构演进策略、数据保护与回滚机制，以及迁移执行命令与工具使用指南。文档同时提供可视化图示帮助读者快速理解迁移架构与数据流。
|
||||
|
||||
## 项目结构
|
||||
后端采用 SQLAlchemy 异步 ORM 与 Alembic 进行数据库版本管理，核心目录与文件如下：
|
||||
- Alembic 配置与环境：backend/alembic.ini、backend/alembic/env.py
|
||||
- 迁移版本脚本：backend/alembic/versions/*.py
|
||||
- 模型定义：backend/app/models/models.py
|
||||
- 数据库连接与会话：backend/app/core/database.py
|
||||
- 初始数据库与测试数据：backend/init_db.py
|
||||
- 菜单与计划表创建脚本：backend/create_menu_tables.py、backend/create_plan_tables.py
|
||||
- 指标表扩展脚本：backend/migrate_indicators.py
|
||||
- 指标模板初始化脚本：backend/init_indicator_templates.py
|
||||
- 系统配置：backend/app/core/config.py
|
||||
- 文档说明：docs/database.md
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
A["Alembic 配置<br/>backend/alembic.ini"] --> B["Alembic 环境<br/>backend/alembic/env.py"]
|
||||
B --> C["迁移版本脚本<br/>backend/alembic/versions/*"]
|
||||
D["模型定义<br/>backend/app/models/models.py"] --> B
|
||||
E["数据库连接<br/>backend/app/core/database.py"] --> B
|
||||
F["初始数据库脚本<br/>backend/init_db.py"] --> E
|
||||
G["菜单表脚本<br/>backend/create_menu_tables.py"] --> E
|
||||
H["指标扩展脚本<br/>backend/migrate_indicators.py"] --> E
|
||||
I["指标模板初始化<br/>backend/init_indicator_templates.py"] --> E
|
||||
J["系统配置<br/>backend/app/core/config.py"] --> E
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [backend/alembic.ini](file://backend/alembic.ini#L1-L44)
|
||||
- [backend/alembic/env.py](file://backend/alembic/env.py#L1-L66)
|
||||
- [backend/alembic/versions/001_initial.py](file://backend/alembic/versions/001_initial.py#L1-L183)
|
||||
- [backend/alembic/versions/002_template.py](file://backend/alembic/versions/002_template.py#L1-L96)
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L438)
|
||||
- [backend/app/core/database.py](file://backend/app/core/database.py#L1-L39)
|
||||
- [backend/init_db.py](file://backend/init_db.py#L1-L83)
|
||||
- [backend/create_menu_tables.py](file://backend/create_menu_tables.py#L1-L27)
|
||||
- [backend/migrate_indicators.py](file://backend/migrate_indicators.py#L1-L46)
|
||||
- [backend/init_indicator_templates.py](file://backend/init_indicator_templates.py#L1-L375)
|
||||
- [backend/app/core/config.py](file://backend/app/core/config.py#L1-L47)
|
||||
|
||||
**章节来源**
|
||||
- [backend/alembic.ini](file://backend/alembic.ini#L1-L44)
|
||||
- [backend/alembic/env.py](file://backend/alembic/env.py#L1-L66)
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L438)
|
||||
- [backend/app/core/database.py](file://backend/app/core/database.py#L1-L39)
|
||||
|
||||
## 核心组件
|
||||
- Alembic 环境与配置
|
||||
- env.py：定义离线/在线迁移执行逻辑，绑定目标元数据 Base.metadata，支持异步引擎连接。
|
||||
- alembic.ini：配置脚本位置、路径分隔符、数据库 URL（默认 SQLite），日志级别等。
|
||||
- 模型与元数据
|
||||
- models.py：定义所有数据模型及其枚举、索引与约束；Base 作为 DeclarativeBase 基类，供 Alembic 识别变更。
|
||||
- database.py：创建异步引擎与会话工厂，提供依赖注入接口。
|
||||
- 迁移版本脚本
|
||||
- 001_initial.py：初始版本，创建 departments、staff、indicators、assessments、assessment_details、salary_records、users 等表及索引。
|
||||
- 002_template.py：新增指标模板与模板指标关联表，并向 indicators 表动态添加字段（兼容性处理）。
|
||||
- 辅助脚本
|
||||
- init_db.py：创建所有表并插入测试数据。
|
||||
- create_menu_tables.py：创建菜单相关表并初始化默认菜单。
|
||||
- migrate_indicators.py：直接通过 SQL 为 indicators 表添加字段（非 Alembic 方式）。
|
||||
- init_indicator_templates.py：初始化各类科室的指标模板数据。
|
||||
- app/core/config.py：提供 DATABASE_URL 等配置，影响 Alembic 连接目标。
|
||||
|
||||
**章节来源**
|
||||
- [backend/alembic/env.py](file://backend/alembic/env.py#L1-L66)
|
||||
- [backend/alembic.ini](file://backend/alembic.ini#L1-L44)
|
||||
- [backend/alembic/versions/001_initial.py](file://backend/alembic/versions/001_initial.py#L1-L183)
|
||||
- [backend/alembic/versions/002_template.py](file://backend/alembic/versions/002_template.py#L1-L96)
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L438)
|
||||
- [backend/app/core/database.py](file://backend/app/core/database.py#L1-L39)
|
||||
- [backend/init_db.py](file://backend/init_db.py#L1-L83)
|
||||
- [backend/create_menu_tables.py](file://backend/create_menu_tables.py#L1-L27)
|
||||
- [backend/migrate_indicators.py](file://backend/migrate_indicators.py#L1-L46)
|
||||
- [backend/init_indicator_templates.py](file://backend/init_indicator_templates.py#L1-L375)
|
||||
- [backend/app/core/config.py](file://backend/app/core/config.py#L1-L47)
|
||||
|
||||
## 架构总览
|
||||
下图展示 Alembic 在本项目中的运行时架构：env.py 读取 alembic.ini 配置，绑定 models.py 中的 Base.metadata，通过异步引擎连接数据库，按版本脚本顺序执行 upgrade/downgrade。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Alembic 运行时"
|
||||
CFG["alembic.ini<br/>配置文件"] --> ENV["env.py<br/>迁移入口"]
|
||||
ENV --> META["models.py: Base.metadata<br/>目标元数据"]
|
||||
ENV --> ENG["database.py: AsyncEngine<br/>异步引擎"]
|
||||
ENV --> V001["versions/001_initial.py<br/>初始迁移"]
|
||||
ENV --> V002["versions/002_template.py<br/>模板迁移"]
|
||||
end
|
||||
ENG --> DB["数据库实例<br/>SQLite 或 PostgreSQL"]
|
||||
META --> DB
|
||||
V001 --> DB
|
||||
V002 --> DB
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [backend/alembic.ini](file://backend/alembic.ini#L1-L44)
|
||||
- [backend/alembic/env.py](file://backend/alembic/env.py#L1-L66)
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L438)
|
||||
- [backend/app/core/database.py](file://backend/app/core/database.py#L1-L39)
|
||||
- [backend/alembic/versions/001_initial.py](file://backend/alembic/versions/001_initial.py#L1-L183)
|
||||
- [backend/alembic/versions/002_template.py](file://backend/alembic/versions/002_template.py#L1-L96)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 组件A：Alembic 环境与配置
|
||||
- 功能职责
|
||||
- 离线模式：直接从 alembic.ini 读取 sqlalchemy.url，配置上下文并执行迁移。
|
||||
- 在线模式：通过 async_engine_from_config 创建异步引擎，连接数据库后执行迁移。
|
||||
- 目标元数据：绑定 models.Base.metadata，确保基于 ORM 模型的自动检测与版本生成。
|
||||
- 关键点
|
||||
- 异步迁移：env.py 使用 asyncio 协程驱动异步引擎，避免阻塞。
|
||||
- 日志配置：alembic.ini 控制日志级别与输出格式，便于调试。
|
||||
- 命令与工具
|
||||
- 生成迁移：alembic revision --autogenerate -m "描述"
|
||||
- 执行迁移：alembic upgrade head
|
||||
- 回滚迁移：alembic downgrade -1
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant CLI as "命令行"
|
||||
participant Env as "env.py"
|
||||
participant Cfg as "alembic.ini"
|
||||
participant Meta as "models.Base.metadata"
|
||||
participant Eng as "AsyncEngine"
|
||||
participant DB as "数据库"
|
||||
CLI->>Env : 运行迁移命令
|
||||
Env->>Cfg : 读取配置(sqlalchemy.url)
|
||||
Env->>Meta : 绑定目标元数据
|
||||
Env->>Eng : 创建异步引擎
|
||||
Env->>DB : 连接并执行迁移
|
||||
DB-->>Env : 返回迁移结果
|
||||
Env-->>CLI : 输出状态
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [backend/alembic/env.py](file://backend/alembic/env.py#L21-L65)
|
||||
- [backend/alembic.ini](file://backend/alembic.ini#L1-L44)
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L23-L25)
|
||||
|
||||
**章节来源**
|
||||
- [backend/alembic/env.py](file://backend/alembic/env.py#L1-L66)
|
||||
- [backend/alembic.ini](file://backend/alembic.ini#L1-L44)
|
||||
- [docs/database.md](file://docs/database.md#L272-L285)
|
||||
|
||||
### 组件B：初始数据库结构与演进
|
||||
- 初始版本（001_initial）
|
||||
- 创建核心表：departments、staff、indicators、assessments、assessment_details、salary_records、users。
|
||||
- 定义索引与外键约束，确保查询效率与数据一致性。
|
||||
- 模板版本（002_template）
|
||||
- 新增指标模板表与模板指标关联表，支持按模板生成指标组合。
|
||||
- 对 indicators 表进行字段扩展（bs_dimension、target_unit、assessment_method、deduction_standard、data_source、applicable_dept_types、is_veto），并通过列存在性检查避免重复添加。
|
||||
- 演进策略
|
||||
- 采用增量迁移：每个版本只做必要变更，保持幂等与可回滚。
|
||||
- 兼容性处理：在字段添加前检查是否存在，避免生产环境报错。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["开始"]) --> CheckCols["检查指标表字段是否存在"]
|
||||
CheckCols --> AddBs["添加 bs_dimension 字段"]
|
||||
CheckCols --> AddUnit["添加 target_unit 字段"]
|
||||
CheckCols --> AddMethod["添加 assessment_method 字段"]
|
||||
CheckCols --> AddDed["添加 deduction_standard 字段"]
|
||||
CheckCols --> AddSource["添加 data_source 字段"]
|
||||
CheckCols --> AddTypes["添加 applicable_dept_types 字段"]
|
||||
CheckCols --> AddVeto["添加 is_veto 字段"]
|
||||
AddBs --> Done(["完成"])
|
||||
AddUnit --> Done
|
||||
AddMethod --> Done
|
||||
AddDed --> Done
|
||||
AddSource --> Done
|
||||
AddTypes --> Done
|
||||
AddVeto --> Done
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [backend/alembic/versions/002_template.py](file://backend/alembic/versions/002_template.py#L65-L91)
|
||||
|
||||
**章节来源**
|
||||
- [backend/alembic/versions/001_initial.py](file://backend/alembic/versions/001_initial.py#L21-L183)
|
||||
- [backend/alembic/versions/002_template.py](file://backend/alembic/versions/002_template.py#L21-L96)
|
||||
|
||||
### 组件C：数据保护与回滚机制
|
||||
- 回滚策略
|
||||
- 每个版本脚本均实现 downgrade，按逆序删除表或字段，确保可回滚到上一版本。
|
||||
- 建议在生产环境执行回滚前备份数据库。
|
||||
- 数据保护
|
||||
- 迁移脚本中对字段添加前进行存在性检查，避免重复执行导致失败。
|
||||
- 使用事务包装迁移操作，失败时回滚，减少不一致风险。
|
||||
- 备选脚本
|
||||
- migrate_indicators.py 通过直接 SQL 扩展字段，适用于紧急修复场景，但不建议作为常规迁移手段。
|
||||
|
||||
**章节来源**
|
||||
- [backend/alembic/versions/001_initial.py](file://backend/alembic/versions/001_initial.py#L175-L183)
|
||||
- [backend/alembic/versions/002_template.py](file://backend/alembic/versions/002_template.py#L93-L96)
|
||||
- [backend/migrate_indicators.py](file://backend/migrate_indicators.py#L9-L42)
|
||||
|
||||
### 组件D：迁移脚本编写规范与命名约定
|
||||
- 版本命名
|
||||
- 使用递增编号（如 001_initial、002_template），确保顺序正确。
|
||||
- 文件名与 revision ID 保持一致，便于追踪。
|
||||
- 脚本结构
|
||||
- 必须包含 upgrade() 与 downgrade() 函数。
|
||||
- 字段添加需先检查是否存在，避免重复执行。
|
||||
- 尽量使用 Alembic API（op.*）而非原生 SQL，保证跨数据库兼容性。
|
||||
- 注释与元信息
|
||||
- 在文件头部包含消息、修订 ID、修订者、创建日期等信息，提升可维护性。
|
||||
|
||||
**章节来源**
|
||||
- [backend/alembic/versions/001_initial.py](file://backend/alembic/versions/001_initial.py#L1-L20)
|
||||
- [backend/alembic/versions/002_template.py](file://backend/alembic/versions/002_template.py#L1-L20)
|
||||
|
||||
### 组件E：迁移执行命令与工具使用
|
||||
- 常用命令
|
||||
- 生成迁移：alembic revision --autogenerate -m "描述"
|
||||
- 执行迁移：alembic upgrade head
|
||||
- 回滚迁移：alembic downgrade -1
|
||||
- 环境变量与配置
|
||||
- DATABASE_URL 来自 app/core/config.py，影响 Alembic 连接目标（默认 SQLite，开发环境可切换 PostgreSQL）。
|
||||
- alembic.ini 中的 sqlalchemy.url 也可直接指定数据库连接字符串。
|
||||
|
||||
**章节来源**
|
||||
- [docs/database.md](file://docs/database.md#L272-L285)
|
||||
- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L22)
|
||||
- [backend/alembic.ini](file://backend/alembic.ini#L7-L7)
|
||||
|
||||
## 依赖关系分析
|
||||
- 模块耦合
|
||||
- env.py 依赖 models.Base.metadata 与 app.core.config.settings，确保迁移目标与数据库连接一致。
|
||||
- database.py 提供 AsyncEngine 与 AsyncSession，被 env.py 用于异步迁移。
|
||||
- 外部依赖
|
||||
- Alembic：提供迁移生成、执行与回滚能力。
|
||||
- SQLAlchemy：ORM 模型与异步引擎，驱动迁移元数据与连接。
|
||||
- 潜在风险
|
||||
- 直接 SQL 扩展（如 migrate_indicators.py）与 Alembic 管理的迁移并存，可能造成版本不一致，建议统一迁移到 Alembic。
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
ENV["env.py"] --> META["models.Base.metadata"]
|
||||
ENV --> CFG["app/core/config.py"]
|
||||
ENV --> ENG["app/core/database.py"]
|
||||
ENG --> DB["数据库"]
|
||||
V1["001_initial.py"] --> DB
|
||||
V2["002_template.py"] --> DB
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [backend/alembic/env.py](file://backend/alembic/env.py#L10-L18)
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L23-L25)
|
||||
- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L22)
|
||||
- [backend/app/core/database.py](file://backend/app/core/database.py#L9-L20)
|
||||
- [backend/alembic/versions/001_initial.py](file://backend/alembic/versions/001_initial.py#L1-L183)
|
||||
- [backend/alembic/versions/002_template.py](file://backend/alembic/versions/002_template.py#L1-L96)
|
||||
|
||||
**章节来源**
|
||||
- [backend/alembic/env.py](file://backend/alembic/env.py#L1-L66)
|
||||
- [backend/app/core/database.py](file://backend/app/core/database.py#L1-L39)
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L438)
|
||||
|
||||
## 性能考量
|
||||
- 索引设计
|
||||
- 初始版本为高频查询字段建立索引（如 departments.dept_type、staff.department_id 等），提升查询性能。
|
||||
- 迁移执行
|
||||
- 使用异步引擎减少阻塞；批量 DDL 操作建议合并，避免频繁连接。
|
||||
- 数据量增长
|
||||
- 随着 assessments、assessment_details 等表数据增长，需定期评估索引有效性与查询计划。
|
||||
|
||||
[本节为通用指导，无需特定文件引用]
|
||||
|
||||
## 故障排查指南
|
||||
- 常见问题
|
||||
- 迁移失败：检查 downgrade 实现是否完整；确认字段存在性检查逻辑；查看 Alembic 日志级别。
|
||||
- 连接错误：核对 alembic.ini 与 app/core/config.py 中的 DATABASE_URL；确认数据库服务可用。
|
||||
- 字段重复添加：确保字段存在性检查逻辑生效；避免 Alembic 与直接 SQL 并行修改同一表。
|
||||
- 排查步骤
|
||||
- 查看 Alembic 输出日志，定位失败节点。
|
||||
- 手动执行 downgrade 指定版本，清理异常状态后再重试。
|
||||
- 备份数据库后进行回滚与重试。
|
||||
|
||||
**章节来源**
|
||||
- [backend/alembic/env.py](file://backend/alembic/env.py#L21-L65)
|
||||
- [backend/alembic/versions/001_initial.py](file://backend/alembic/versions/001_initial.py#L175-L183)
|
||||
- [backend/alembic/versions/002_template.py](file://backend/alembic/versions/002_template.py#L93-L96)
|
||||
- [backend/alembic.ini](file://backend/alembic.ini#L20-L43)
|
||||
|
||||
## 结论
|
||||
本项目采用 Alembic 管理数据库版本，结合 SQLAlchemy 异步 ORM 与明确的迁移脚本规范，实现了从初始结构到模板化的演进。通过字段存在性检查、完善的 downgrade 与日志配置，提升了迁移的安全性与可维护性。建议未来逐步将直接 SQL 扩展迁移纳入 Alembic 管理，统一迁移策略，确保版本一致性与可追溯性。
|
||||
|
||||
[本节为总结性内容，无需特定文件引用]
|
||||
|
||||
## 附录
|
||||
|
||||
### A. 迁移命令速查
|
||||
- 生成迁移：alembic revision --autogenerate -m "描述"
|
||||
- 执行迁移：alembic upgrade head
|
||||
- 回滚迁移：alembic downgrade -1
|
||||
|
||||
**章节来源**
|
||||
- [docs/database.md](file://docs/database.md#L272-L285)
|
||||
|
||||
### B. 初始数据库结构概览
|
||||
- 核心表
|
||||
- departments、staff、indicators、assessments、assessment_details、salary_records、users
|
||||
- 关键索引
|
||||
- 高频过滤字段建立索引，如 dept_type、parent_id、department_id、status 等
|
||||
- 约束与枚举
|
||||
- 外键约束、唯一约束、Check 约束与枚举类型（如 DeptType、IndicatorType 等）
|
||||
|
||||
**章节来源**
|
||||
- [backend/alembic/versions/001_initial.py](file://backend/alembic/versions/001_initial.py#L22-L182)
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L438)
|
||||
493
.qoder/repowiki/zh/content/数据库设计/索引与约束设计.md
Normal file
493
.qoder/repowiki/zh/content/数据库设计/索引与约束设计.md
Normal file
@@ -0,0 +1,493 @@
|
||||
# 索引与约束设计
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [models.py](file://backend/app/models/models.py)
|
||||
- [finance.py](file://backend/app/models/finance.py)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py)
|
||||
- [002_template.py](file://backend/alembic/versions/002_template.py)
|
||||
- [database.py](file://backend/app/core/database.py)
|
||||
- [env.py](file://backend/alembic/env.py)
|
||||
- [init_db.py](file://backend/init_db.py)
|
||||
- [database.md](file://docs/database.md)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构概览](#架构概览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考量](#性能考量)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
本文件聚焦于该医院绩效系统的数据库索引与约束设计，系统性梳理各表的索引策略（单列、复合、唯一）、约束实现（主键、外键、检查、唯一），并结合业务场景给出性能分析、查询优化建议、约束对数据完整性的作用以及索引维护与监控建议。内容严格基于仓库中的模型定义、迁移脚本与文档，避免臆测。
|
||||
|
||||
## 项目结构
|
||||
系统采用 SQLAlchemy ORM + Alembic 迁移的典型后端架构，数据库层通过异步引擎连接，模型文件集中定义表结构、索引与约束，迁移脚本负责版本演进。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "数据库层"
|
||||
Engine["异步引擎<br/>engine"]
|
||||
Session["会话工厂<br/>async_session_maker"]
|
||||
Base["ORM基类<br/>Base"]
|
||||
end
|
||||
subgraph "模型层"
|
||||
Models["模型定义<br/>models.py"]
|
||||
Finance["财务模型<br/>finance.py"]
|
||||
end
|
||||
subgraph "迁移层"
|
||||
Env["Alembic环境<br/>env.py"]
|
||||
V001["初始迁移<br/>001_initial.py"]
|
||||
V002["模板迁移<br/>002_template.py"]
|
||||
end
|
||||
Engine --> Session
|
||||
Session --> Base
|
||||
Base --> Models
|
||||
Base --> Finance
|
||||
Env --> V001
|
||||
Env --> V002
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [database.py](file://backend/app/core/database.py#L10-L20)
|
||||
- [models.py](file://backend/app/models/models.py#L1-L20)
|
||||
- [finance.py](file://backend/app/models/finance.py#L1-L20)
|
||||
- [env.py](file://backend/alembic/env.py#L10-L18)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L21-L183)
|
||||
- [002_template.py](file://backend/alembic/versions/002_template.py#L21-L96)
|
||||
|
||||
章节来源
|
||||
- [database.py](file://backend/app/core/database.py#L1-L39)
|
||||
- [env.py](file://backend/alembic/env.py#L1-L66)
|
||||
|
||||
## 核心组件
|
||||
- 异步数据库引擎与会话工厂：负责连接与事务管理，支持并发读写。
|
||||
- ORM模型基类：统一模型继承，承载索引与约束声明。
|
||||
- 模型定义：集中定义表结构、字段类型、索引与约束。
|
||||
- Alembic迁移：版本化管理数据库结构变更，确保团队协作一致性。
|
||||
|
||||
章节来源
|
||||
- [database.py](file://backend/app/core/database.py#L10-L20)
|
||||
- [models.py](file://backend/app/models/models.py#L1-L20)
|
||||
- [finance.py](file://backend/app/models/finance.py#L1-L15)
|
||||
- [env.py](file://backend/alembic/env.py#L10-L18)
|
||||
|
||||
## 架构概览
|
||||
系统通过 Alembic 将模型定义映射为数据库表结构，并在迁移脚本中显式声明索引与约束。模型层使用 SQLAlchemy 的 Index 与 CheckConstraint 等机制，迁移层通过 op.create_index/op.create_table 等操作同步到数据库。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Dev as "开发者"
|
||||
participant Alembic as "Alembic"
|
||||
participant Env as "env.py"
|
||||
participant Conn as "数据库连接"
|
||||
participant DB as "数据库"
|
||||
Dev->>Alembic : 生成/执行迁移
|
||||
Alembic->>Env : 加载目标元数据
|
||||
Env->>Conn : 获取异步连接
|
||||
Conn->>DB : 执行DDL建表/索引/约束
|
||||
DB-->>Conn : 返回结果
|
||||
Conn-->>Alembic : 提交/回滚
|
||||
Alembic-->>Dev : 迁移完成
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [env.py](file://backend/alembic/env.py#L42-L53)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L21-L183)
|
||||
- [002_template.py](file://backend/alembic/versions/002_template.py#L21-L96)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 员工信息表（staff）
|
||||
- 主键：id（自增）
|
||||
- 唯一约束：employee_id（工号唯一）
|
||||
- 外键：department_id → departments.id
|
||||
- 单列索引：idx_staff_dept（department_id）、idx_staff_status（status）
|
||||
- 复合索引：无
|
||||
- 检查约束：无
|
||||
- 设计要点
|
||||
- 员工工号唯一，便于跨模块引用与去重。
|
||||
- 员工状态与所属科室是高频过滤条件，分别建立单列索引以提升 WHERE 查询效率。
|
||||
- 与部门的多对一关系通过外键约束保证引用完整性。
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L88-L114)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L42-L64)
|
||||
|
||||
### 科室信息表（departments）
|
||||
- 主键：id（自增）
|
||||
- 唯一约束：code（科室编码唯一）
|
||||
- 外键：parent_id → departments.id（自关联，树形结构）
|
||||
- 单列索引：idx_dept_type（dept_type）、idx_dept_parent（parent_id）
|
||||
- 复合索引：无
|
||||
- 检查约束：无
|
||||
- 设计要点
|
||||
- 科室编码唯一，支撑业务识别与报表统计。
|
||||
- 科室类型与层级关系常用于筛选与聚合，单列索引覆盖常见查询模式。
|
||||
- 自关联外键支持组织架构树的层次遍历与父子关系校验。
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L62-L86)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L22-L41)
|
||||
|
||||
### 考核记录表（assessments）
|
||||
- 主键：id（自增）
|
||||
- 外键：staff_id → staff.id；assessor_id/reviewer_id → staff.id（自关联）
|
||||
- 单列索引：idx_assessment_staff（staff_id）、idx_assessment_status（status）
|
||||
- 复合索引：idx_assessment_period（period_year, period_month）
|
||||
- 检查约束：无
|
||||
- 设计要点
|
||||
- 考核周期复合索引覆盖“按年月统计”等典型查询。
|
||||
- 员工与状态索引满足“某员工某状态”的快速检索。
|
||||
- 多个自关联外键确保考核流程的完整性。
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L149-L178)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L87-L112)
|
||||
|
||||
### 考核明细表（assessment_details）
|
||||
- 主键：id（自增）
|
||||
- 外键：assessment_id → assessments.id；indicator_id → indicators.id
|
||||
- 单列索引：idx_detail_assessment（assessment_id）、idx_detail_indicator（indicator_id）
|
||||
- 复合索引：无
|
||||
- 检查约束：无
|
||||
- 设计要点
|
||||
- 明细表按考核记录与指标分别建立单列索引，支撑“查看某考核的所有指标”和“查看某指标在所有考核中的表现”。
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L181-L202)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L114-L131)
|
||||
|
||||
### 工资核算记录表（salary_records）
|
||||
- 主键：id（自增）
|
||||
- 外键：staff_id → staff.id
|
||||
- 单列索引：idx_salary_staff（staff_id）
|
||||
- 复合索引：idx_salary_period（period_year, period_month）
|
||||
- 检查约束：无
|
||||
- 设计要点
|
||||
- 工资按员工与周期查询频繁，分别建立单列与复合索引以优化检索与聚合。
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L205-L230)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L133-L154)
|
||||
|
||||
### 系统用户表（users）
|
||||
- 主键：id（自增）
|
||||
- 唯一约束：username（用户名唯一）
|
||||
- 外键：staff_id → staff.id（可选关联）
|
||||
- 单列索引：idx_user_username（username）
|
||||
- 复合索引：无
|
||||
- 检查约束：无
|
||||
- 设计要点
|
||||
- 登录凭据唯一性由用户名唯一约束保证，索引加速登录与鉴权查询。
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L244-L260)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L156-L172)
|
||||
|
||||
### 绩效计划表（performance_plans）
|
||||
- 主键：id（自增）
|
||||
- 唯一约束：plan_code（计划编码唯一）
|
||||
- 外键：department_id → departments.id；staff_id → staff.id；submitter_id/approver_id → users.id；parent_plan_id → performance_plans.id（自关联）
|
||||
- 单列索引：idx_plan_level（plan_level）、idx_plan_year（plan_year）、idx_plan_department（department_id）、idx_plan_status（status）
|
||||
- 复合索引：无
|
||||
- 检查约束：无
|
||||
- 设计要点
|
||||
- 计划层级、年份、状态与部门是常见的过滤维度，单列索引覆盖主要查询场景。
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L270-L311)
|
||||
|
||||
### 计划-指标关联表（plan_kpi_relations）
|
||||
- 主键：id（自增）
|
||||
- 外键：plan_id → performance_plans.id；indicator_id → indicators.id
|
||||
- 单列索引：idx_relation_plan（plan_id）、idx_relation_indicator（indicator_id）
|
||||
- 复合索引：idx_relation_unique（plan_id, indicator_id, unique=True）
|
||||
- 检查约束：无
|
||||
- 设计要点
|
||||
- 关联表的复合唯一索引确保“同一计划下的同一指标仅出现一次”，避免重复绑定。
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L314-L338)
|
||||
|
||||
### 指标模板表（indicator_templates）
|
||||
- 主键：id（自增）
|
||||
- 唯一约束：template_code（模板编码唯一）
|
||||
- 单列索引：idx_template_type（template_type）、idx_template_active（is_active）
|
||||
- 复合索引：无
|
||||
- 检查约束：无
|
||||
- 设计要点
|
||||
- 模板类型与启用状态是筛选热点，单列索引满足模板选择与激活状态查询。
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L387-L408)
|
||||
- [002_template.py](file://backend/alembic/versions/002_template.py#L22-L39)
|
||||
|
||||
### 模板-指标关联表（template_indicators）
|
||||
- 主键：id（自增）
|
||||
- 外键：template_id → indicator_templates.id；indicator_id → indicators.id
|
||||
- 单列索引：idx_ti_template（template_id）、idx_ti_indicator（indicator_id）
|
||||
- 复合索引：idx_ti_unique（template_id, indicator_id, unique=True）
|
||||
- 检查约束：无
|
||||
- 设计要点
|
||||
- 关联表的复合唯一索引确保“同一模板下的同一指标仅出现一次”，避免重复绑定。
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L411-L437)
|
||||
- [002_template.py](file://backend/alembic/versions/002_template.py#L41-L63)
|
||||
|
||||
### 财务记录表（department_finances）
|
||||
- 主键：id（自增）
|
||||
- 外键：department_id → departments.id
|
||||
- 单列索引：idx_finance_dept（department_id）、idx_finance_period（period_year, period_month）、idx_finance_type（finance_type）、idx_finance_category（category）
|
||||
- 复合索引：无
|
||||
- 检查约束：ck_finance_amount（amount >= 0）
|
||||
- 设计要点
|
||||
- 财务按科室、周期、类型与类别查询频繁，单列索引覆盖这些过滤维度。
|
||||
- 金额非负的检查约束保证财务数据的数值正确性。
|
||||
|
||||
章节来源
|
||||
- [finance.py](file://backend/app/models/finance.py#L45-L74)
|
||||
|
||||
### 考核指标表（indicators）
|
||||
- 主键：id（自增）
|
||||
- 唯一约束：code（指标编码唯一）
|
||||
- 单列索引：idx_indicator_type（indicator_type）
|
||||
- 复合索引：无
|
||||
- 检查约束：ck_indicator_weight（weight > 0）
|
||||
- 设计要点
|
||||
- 指标类型索引满足按类型筛选与统计。
|
||||
- 权重正数检查约束确保指标权重的合理性。
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L117-L146)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L66-L85)
|
||||
|
||||
## 依赖关系分析
|
||||
|
||||
```mermaid
|
||||
erDiagram
|
||||
DEPARTMENTS {
|
||||
int id PK
|
||||
string code UK
|
||||
string dept_type
|
||||
int parent_id FK
|
||||
}
|
||||
STAFF {
|
||||
int id PK
|
||||
string employee_id UK
|
||||
int department_id FK
|
||||
string status
|
||||
}
|
||||
ASSESSMENTS {
|
||||
int id PK
|
||||
int staff_id FK
|
||||
int period_year
|
||||
int period_month
|
||||
string status
|
||||
}
|
||||
ASSESSMENT_DETAILS {
|
||||
int id PK
|
||||
int assessment_id FK
|
||||
int indicator_id FK
|
||||
}
|
||||
SALARY_RECORDS {
|
||||
int id PK
|
||||
int staff_id FK
|
||||
int period_year
|
||||
int period_month
|
||||
}
|
||||
USERS {
|
||||
int id PK
|
||||
string username UK
|
||||
}
|
||||
PERFORMANCE_PLANS {
|
||||
int id PK
|
||||
string plan_code UK
|
||||
string plan_level
|
||||
int department_id FK
|
||||
string status
|
||||
}
|
||||
PLAN_KPI_RELATIONS {
|
||||
int id PK
|
||||
int plan_id FK
|
||||
int indicator_id FK
|
||||
}
|
||||
INDICATOR_TEMPLATES {
|
||||
int id PK
|
||||
string template_code UK
|
||||
string template_type
|
||||
boolean is_active
|
||||
}
|
||||
TEMPLATE_INDICATORS {
|
||||
int id PK
|
||||
int template_id FK
|
||||
int indicator_id FK
|
||||
}
|
||||
DEPARTMENT_FINANCES {
|
||||
int id PK
|
||||
int department_id FK
|
||||
int period_year
|
||||
int period_month
|
||||
string finance_type
|
||||
string category
|
||||
}
|
||||
INDICATORS {
|
||||
int id PK
|
||||
string code UK
|
||||
string indicator_type
|
||||
numeric weight
|
||||
}
|
||||
DEPARTMENTS ||--o{ STAFF : "1:N"
|
||||
STAFF ||--o{ ASSESSMENTS : "1:N"
|
||||
ASSESSMENTS ||--o{ ASSESSMENT_DETAILS : "1:N"
|
||||
STAFF ||--o{ SALARY_RECORDS : "1:N"
|
||||
DEPARTMENTS ||--o{ DEPARTMENT_FINANCES : "1:N"
|
||||
INDICATORS ||--o{ ASSESSMENT_DETAILS : "1:N"
|
||||
INDICATORS ||--o{ PLAN_KPI_RELATIONS : "1:N"
|
||||
INDICATORS ||--o{ TEMPLATE_INDICATORS : "1:N"
|
||||
INDICATOR_TEMPLATES ||--o{ TEMPLATE_INDICATORS : "1:N"
|
||||
PERFORMANCE_PLANS ||--o{ PLAN_KPI_RELATIONS : "1:N"
|
||||
USERS ||--o{ PERFORMANCE_PLANS : "1:N"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [models.py](file://backend/app/models/models.py#L62-L437)
|
||||
- [finance.py](file://backend/app/models/finance.py#L45-L74)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L22-L183)
|
||||
- [002_template.py](file://backend/alembic/versions/002_template.py#L22-L96)
|
||||
|
||||
## 性能考量
|
||||
|
||||
- 索引策略与查询模式匹配
|
||||
- 员工与科室：按部门与状态过滤频繁，单列索引 idx_staff_dept、idx_staff_status、idx_dept_type、idx_dept_parent 能有效降低扫描范围。
|
||||
- 考核与工资：按员工与周期查询最常见，单列索引 idx_assessment_staff、idx_salary_staff，以及复合索引 idx_assessment_period、idx_salary_period 覆盖“某员工某周期”的查询。
|
||||
- 模板与计划：按类型、状态、启用状态过滤，单列索引 idx_template_type、idx_template_active、idx_plan_level、idx_plan_year、idx_plan_department、idx_plan_status。
|
||||
- 财务：按科室、周期、类型、类别过滤，单列索引 idx_finance_dept、idx_finance_period、idx_finance_type、idx_finance_category。
|
||||
|
||||
- 复合索引选择
|
||||
- 考核与工资的“年+月”组合索引能显著提升范围查询与分组统计性能。
|
||||
- 关联表的“计划+指标”复合唯一索引避免重复绑定，同时作为唯一约束提升查询稳定性。
|
||||
|
||||
- 检查约束
|
||||
- 指标权重与财务金额的非负检查约束在写入阶段即拦截异常数据，减少后续修复成本。
|
||||
|
||||
- 查询优化建议
|
||||
- 对高频过滤字段（如 status、dept_type、finance_type）优先使用单列索引。
|
||||
- 对范围查询（如 period_year/period_month）优先使用复合索引。
|
||||
- 避免 SELECT *，明确字段以减少 IO。
|
||||
- 对大表分页查询使用 LIMIT/OFFSET 或基于游标的分页策略，避免深度分页导致的性能退化。
|
||||
|
||||
- 索引维护与监控
|
||||
- 定期分析表与索引统计信息，识别未使用或冗余索引。
|
||||
- 监控慢查询日志，定位缺失索引的查询模式并补充索引。
|
||||
- 在高并发写入场景下，评估索引数量对写入性能的影响，必要时调整索引策略。
|
||||
|
||||
## 故障排查指南
|
||||
|
||||
- 索引缺失导致的慢查询
|
||||
- 症状：WHERE/JOIN/ORDER BY/聚合查询耗时长。
|
||||
- 排查：确认相关字段是否具备单列或复合索引；检查查询执行计划。
|
||||
- 处置：根据查询模式新增索引或调整现有索引顺序。
|
||||
|
||||
- 唯一约束冲突
|
||||
- 症状：插入/更新时报唯一约束冲突。
|
||||
- 排查：确认唯一字段（如 employee_id、code、username、plan_code、template_code）是否重复。
|
||||
- 处置：修正数据或调整业务逻辑，避免重复提交。
|
||||
|
||||
- 外键约束失败
|
||||
- 症状：插入/更新时报外键约束错误。
|
||||
- 排查：确认被引用表是否存在对应记录；确认字段类型与长度一致。
|
||||
- 处置：先创建被引用记录，再进行关联写入。
|
||||
|
||||
- 检查约束触发
|
||||
- 症状：插入/更新时报检查约束错误（如权重非正、金额为负）。
|
||||
- 排查：核对业务输入是否符合约束条件。
|
||||
- 处置：修正业务逻辑或前端校验，确保数据合法。
|
||||
|
||||
- 迁移与版本问题
|
||||
- 症状：迁移失败或版本不一致。
|
||||
- 排查：检查 Alembic 版本历史与当前数据库状态；确认迁移脚本语法正确。
|
||||
- 处置：使用 Alembic 命令检查/回滚/升级至目标版本。
|
||||
|
||||
章节来源
|
||||
- [env.py](file://backend/alembic/env.py#L42-L53)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L21-L183)
|
||||
- [002_template.py](file://backend/alembic/versions/002_template.py#L21-L96)
|
||||
|
||||
## 结论
|
||||
本系统在模型层与迁移层均明确声明了索引与约束，覆盖了业务高频查询与数据完整性需求。通过单列与复合索引的合理布局，配合外键与检查约束，既保证了查询性能，也强化了数据一致性。建议持续监控查询性能与索引使用情况，动态优化索引策略以适应业务增长。
|
||||
|
||||
## 附录
|
||||
|
||||
### 索引与约束清单（按表）
|
||||
|
||||
- departments
|
||||
- 唯一：code
|
||||
- 外键：parent_id → departments.id
|
||||
- 单列索引：idx_dept_type、idx_dept_parent
|
||||
|
||||
- staff
|
||||
- 唯一：employee_id
|
||||
- 外键：department_id → departments.id
|
||||
- 单列索引：idx_staff_dept、idx_staff_status
|
||||
|
||||
- indicators
|
||||
- 唯一：code
|
||||
- 单列索引：idx_indicator_type
|
||||
- 检查约束：weight > 0
|
||||
|
||||
- assessments
|
||||
- 外键：staff_id → staff.id；assessor_id/reviewer_id → staff.id
|
||||
- 单列索引：idx_assessment_staff、idx_assessment_status
|
||||
- 复合索引：idx_assessment_period
|
||||
|
||||
- assessment_details
|
||||
- 外键：assessment_id → assessments.id；indicator_id → indicators.id
|
||||
- 单列索引：idx_detail_assessment、idx_detail_indicator
|
||||
|
||||
- salary_records
|
||||
- 外键：staff_id → staff.id
|
||||
- 单列索引：idx_salary_staff
|
||||
- 复合索引：idx_salary_period
|
||||
|
||||
- users
|
||||
- 唯一：username
|
||||
- 外键：staff_id → staff.id
|
||||
- 单列索引：idx_user_username
|
||||
|
||||
- performance_plans
|
||||
- 唯一：plan_code
|
||||
- 外键：department_id → departments.id；staff_id → staff.id；submitter_id/approver_id → users.id；parent_plan_id → performance_plans.id
|
||||
- 单列索引：idx_plan_level、idx_plan_year、idx_plan_department、idx_plan_status
|
||||
|
||||
- plan_kpi_relations
|
||||
- 外键：plan_id → performance_plans.id；indicator_id → indicators.id
|
||||
- 单列索引：idx_relation_plan、idx_relation_indicator
|
||||
- 复合唯一索引：idx_relation_unique
|
||||
|
||||
- indicator_templates
|
||||
- 唯一：template_code
|
||||
- 单列索引：idx_template_type、idx_template_active
|
||||
|
||||
- template_indicators
|
||||
- 外键：template_id → indicator_templates.id；indicator_id → indicators.id
|
||||
- 单列索引：idx_ti_template、idx_ti_indicator
|
||||
- 复合唯一索引：idx_ti_unique
|
||||
|
||||
- department_finances
|
||||
- 外键：department_id → departments.id
|
||||
- 单列索引：idx_finance_dept、idx_finance_period、idx_finance_type、idx_finance_category
|
||||
- 检查约束：amount >= 0
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L62-L437)
|
||||
- [finance.py](file://backend/app/models/finance.py#L45-L74)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L22-L183)
|
||||
- [002_template.py](file://backend/alembic/versions/002_template.py#L22-L96)
|
||||
582
.qoder/repowiki/zh/content/数据库设计/表结构设计/枚举类型定义.md
Normal file
582
.qoder/repowiki/zh/content/数据库设计/表结构设计/枚举类型定义.md
Normal file
@@ -0,0 +1,582 @@
|
||||
# 枚举类型定义
|
||||
|
||||
<cite>
|
||||
**本文档引用的文件**
|
||||
- [models.py](file://backend/app/models/models.py)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py)
|
||||
- [init_db.py](file://backend/app/core/init_db.py)
|
||||
- [finance.py](file://backend/app/models/finance.py)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py)
|
||||
- [departments.py](file://backend/app/api/v1/departments.py)
|
||||
- [performance_plans.py](file://backend/app/api/v1/performance_plans.py)
|
||||
- [department_service.py](file://backend/app/services/department_service.py)
|
||||
- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心枚举类型](#核心枚举类型)
|
||||
4. [架构概览](#架构概览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考虑](#性能考虑)
|
||||
8. [故障排除指南](#故障排除指南)
|
||||
9. [结论](#结论)
|
||||
|
||||
## 简介
|
||||
|
||||
本文档详细介绍了医院绩效系统中的所有自定义枚举类型定义，包括它们的设计思路、取值范围、业务含义和使用场景。系统采用强类型枚举确保数据的一致性和完整性，通过SQLAlchemy映射到数据库中的字符串字段，并在API层提供类型安全的接口。
|
||||
|
||||
## 项目结构
|
||||
|
||||
枚举类型主要分布在以下三个层次：
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "数据模型层"
|
||||
A[models.py<br/>数据库模型枚举]
|
||||
end
|
||||
subgraph "数据验证层"
|
||||
B[schemas.py<br/>Pydantic模型枚举]
|
||||
end
|
||||
subgraph "业务逻辑层"
|
||||
C[init_db.py<br/>初始化枚举]
|
||||
D[finance.py<br/>财务枚举]
|
||||
end
|
||||
subgraph "API接口层"
|
||||
E[departments.py<br/>科室API]
|
||||
F[performance_plans.py<br/>计划API]
|
||||
end
|
||||
A --> B
|
||||
B --> C
|
||||
C --> D
|
||||
D --> E
|
||||
E --> F
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [models.py](file://backend/app/models/models.py#L15-L345)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L10-L652)
|
||||
- [init_db.py](file://backend/app/core/init_db.py#L9-L115)
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L1-L438)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L1-L743)
|
||||
|
||||
## 核心枚举类型
|
||||
|
||||
### 科室类型 (DeptType)
|
||||
|
||||
科室类型枚举定义了医院各类科室的分类体系，采用字符串值存储，支持多层级科室组织结构。
|
||||
|
||||
**设计思路：**
|
||||
- 按照医院科室的功能属性进行分类
|
||||
- 支持从属关系的层级结构
|
||||
- 为指标模板选择提供依据
|
||||
|
||||
**取值范围：**
|
||||
- `CLINICAL_SURGICAL`: 手术临床科室
|
||||
- `CLINICAL_NONSURGICAL_WARD`: 非手术有病房科室
|
||||
- `CLINICAL_NONSURGICAL_NOWARD`: 非手术无病房科室
|
||||
- `MEDICAL_TECH`: 医技科室
|
||||
- `MEDICAL_AUXILIARY`: 医辅科室
|
||||
- `NURSING`: 护理单元
|
||||
- `ADMIN`: 行政科室
|
||||
- `FINANCE`: 财务科室
|
||||
- `LOGISTICS`: 后勤保障科室
|
||||
|
||||
**业务含义：**
|
||||
- 用于区分不同功能属性的科室
|
||||
- 支持按科室类型进行筛选和统计
|
||||
- 为绩效指标模板的适用性提供分类依据
|
||||
|
||||
**使用场景：**
|
||||
- 科室信息管理
|
||||
- 绩效指标模板匹配
|
||||
- 数据统计分析
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L16-L27)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L12-L22)
|
||||
|
||||
### 平衡计分卡维度 (BSCDimension)
|
||||
|
||||
平衡计分卡维度枚举实现了经典的四个维度考核框架。
|
||||
|
||||
**设计思路：**
|
||||
- 基于平衡计分卡理论框架
|
||||
- 四个维度相互补充，全面评估组织绩效
|
||||
- 支持多维度的综合评价
|
||||
|
||||
**取值范围：**
|
||||
- `FINANCIAL`: 财务维度
|
||||
- `CUSTOMER`: 客户维度
|
||||
- `INTERNAL_PROCESS`: 内部流程维度
|
||||
- `LEARNING_GROWTH`: 学习与成长维度
|
||||
|
||||
**业务含义：**
|
||||
- 财务维度：关注财务表现和盈利能力
|
||||
- 客户维度：关注客户满意度和服务质量
|
||||
- 内部流程维度：关注运营效率和流程优化
|
||||
- 学习与成长维度：关注员工能力和组织发展
|
||||
|
||||
**使用场景：**
|
||||
- 绩效指标设计
|
||||
- 综合评价体系构建
|
||||
- 战略目标分解
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L29-L35)
|
||||
|
||||
### 员工状态 (StaffStatus)
|
||||
|
||||
员工状态枚举跟踪员工在组织中的生命周期状态。
|
||||
|
||||
**设计思路：**
|
||||
- 覆盖员工从入职到离职的完整生命周期
|
||||
- 支持状态变更的审计追踪
|
||||
- 为薪资计算和权限管理提供依据
|
||||
|
||||
**取值范围：**
|
||||
- `ACTIVE`: 在职
|
||||
- `LEAVE`: 休假
|
||||
- `RESIGNED`: 离职
|
||||
- `RETIRED`: 退休
|
||||
|
||||
**业务含义：**
|
||||
- ACTIVE: 当前在岗工作
|
||||
- LEAVE: 正式请假状态
|
||||
- RESIGNED: 主动辞职
|
||||
- RETIRED: 达到退休年龄
|
||||
|
||||
**使用场景：**
|
||||
- 员工信息管理
|
||||
- 薪资发放控制
|
||||
- 系统权限管理
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L37-L43)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L24-L29)
|
||||
|
||||
### 考核状态 (AssessmentStatus)
|
||||
|
||||
考核状态枚举管理绩效考核流程的各个阶段。
|
||||
|
||||
**设计思路：**
|
||||
- 实现完整的考核流程管理
|
||||
- 支持多级审批和状态流转
|
||||
- 提供清晰的流程可视化
|
||||
|
||||
**取值范围：**
|
||||
- `DRAFT`: 草稿
|
||||
- `SUBMITTED`: 已提交
|
||||
- `REVIEWED`: 已审核
|
||||
- `FINALIZED`: 已确认
|
||||
- `REJECTED`: 已驳回
|
||||
|
||||
**业务含义：**
|
||||
- DRAFT: 考核记录创建但未提交
|
||||
- SUBMITTED: 已提交等待审批
|
||||
- REVIEWED: 审核通过等待最终确认
|
||||
- FINALIZED: 最终确认完成
|
||||
- REJECTED: 审批被拒绝
|
||||
|
||||
**使用场景：**
|
||||
- 绩效考核流程控制
|
||||
- 审批权限管理
|
||||
- 数据状态追踪
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L45-L52)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L31-L37)
|
||||
|
||||
### 指标类型 (IndicatorType)
|
||||
|
||||
指标类型枚举定义了绩效指标的分类体系。
|
||||
|
||||
**设计思路：**
|
||||
- 基于平衡计分卡的指标分类
|
||||
- 支持不同类型指标的差异化管理
|
||||
- 便于指标的统计分析和比较
|
||||
|
||||
**取值范围：**
|
||||
- `QUALITY`: 质量指标
|
||||
- `QUANTITY`: 数量指标
|
||||
- `EFFICIENCY`: 效率指标
|
||||
- `SERVICE`: 服务指标
|
||||
- `COST`: 成本指标
|
||||
|
||||
**业务含义：**
|
||||
- QUALITY: 关注工作质量和效果
|
||||
- QUANTITY: 关注工作量和产出数量
|
||||
- EFFICIENCY: 关注资源利用效率
|
||||
- SERVICE: 关注服务质量水平
|
||||
- COST: 关注成本控制效果
|
||||
|
||||
**使用场景：**
|
||||
- 指标设计和分类
|
||||
- 绩效计算和评分
|
||||
- 统计分析和报告
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L54-L61)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L39-L45)
|
||||
|
||||
### 计划状态 (PlanStatus)
|
||||
|
||||
计划状态枚举管理绩效计划的生命周期。
|
||||
|
||||
**设计思路：**
|
||||
- 支持从创建到完成的完整计划管理
|
||||
- 提供清晰的状态流转路径
|
||||
- 支持计划的版本管理和变更追踪
|
||||
|
||||
**取值范围：**
|
||||
- `DRAFT`: 草稿
|
||||
- `PENDING`: 待审批
|
||||
- `APPROVED`: 已批准
|
||||
- `REJECTED`: 已驳回
|
||||
- `ACTIVE`: 执行中
|
||||
- `COMPLETED`: 已完成
|
||||
- `CANCELLED`: 已取消
|
||||
|
||||
**业务含义：**
|
||||
- DRAFT: 计划草稿状态
|
||||
- PENDING: 等待上级审批
|
||||
- APPROVED: 审批通过准备执行
|
||||
- REJECTED: 审批被拒绝
|
||||
- ACTIVE: 正在执行的计划
|
||||
- COMPLETED: 执行完成的计划
|
||||
- CANCELLED: 主动取消的计划
|
||||
|
||||
**使用场景：**
|
||||
- 绩效计划管理
|
||||
- 审批流程控制
|
||||
- 计划执行追踪
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L233-L242)
|
||||
|
||||
### 菜单类型 (MenuType)
|
||||
|
||||
菜单类型枚举区分系统界面的导航元素。
|
||||
|
||||
**设计思路：**
|
||||
- 支持复杂的菜单层级结构
|
||||
- 区分页面菜单和操作按钮
|
||||
- 为权限控制提供基础
|
||||
|
||||
**取值范围：**
|
||||
- `MENU`: 菜单
|
||||
- `BUTTON`: 按钮
|
||||
|
||||
**业务含义：**
|
||||
- MENU: 导航菜单项，可包含子菜单
|
||||
- BUTTON: 页面上的操作按钮，无子菜单
|
||||
|
||||
**使用场景：**
|
||||
- 系统权限管理
|
||||
- 界面导航控制
|
||||
- 功能访问控制
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L341-L345)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L584-L588)
|
||||
|
||||
### 财务相关枚举
|
||||
|
||||
#### 收入类别 (RevenueCategory)
|
||||
- `EXAMINATION`: 检查费
|
||||
- `LAB_TEST`: 检验费
|
||||
- `RADIOLOGY`: 放射费
|
||||
- `BED`: 床位费
|
||||
- `NURSING`: 护理费
|
||||
- `TREATMENT`: 治疗费
|
||||
- `SURGERY`: 手术费
|
||||
- `INJECTION`: 注射费
|
||||
- `OXYGEN`: 吸氧费
|
||||
- `OTHER`: 其他
|
||||
|
||||
#### 支出类别 (ExpenseCategory)
|
||||
- `MATERIAL`: 材料费
|
||||
- `PERSONNEL`: 人员支出
|
||||
- `MAINTENANCE`: 维修费
|
||||
- `UTILITY`: 水电费
|
||||
- `OTHER`: 其他
|
||||
|
||||
#### 财务类型 (FinanceType)
|
||||
- `REVENUE`: 收入
|
||||
- `EXPENSE`: 支出
|
||||
|
||||
**章节来源**
|
||||
- [finance.py](file://backend/app/models/finance.py#L16-L43)
|
||||
|
||||
## 架构概览
|
||||
|
||||
枚举类型在整个系统中的架构分布如下：
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "数据持久层"
|
||||
A[SQLAlchemy Enum<br/>String存储]
|
||||
B[数据库索引<br/>性能优化]
|
||||
end
|
||||
subgraph "业务逻辑层"
|
||||
C[模型定义<br/>类型约束]
|
||||
D[服务层<br/>状态流转]
|
||||
end
|
||||
subgraph "接口层"
|
||||
E[API路由<br/>参数验证]
|
||||
F[Pydantic模型<br/>数据序列化]
|
||||
end
|
||||
subgraph "前端展示层"
|
||||
G[Vue组件<br/>状态显示]
|
||||
H[表格展示<br/>枚举翻译]
|
||||
end
|
||||
A --> C
|
||||
C --> D
|
||||
D --> E
|
||||
E --> F
|
||||
F --> G
|
||||
G --> H
|
||||
B --> A
|
||||
B --> C
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [models.py](file://backend/app/models/models.py#L69-L354)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L12-L652)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 数据库存储方式
|
||||
|
||||
所有枚举类型在数据库中以字符串形式存储，使用SQLAlchemy的Enum映射：
|
||||
|
||||
```mermaid
|
||||
erDiagram
|
||||
ENUM_VALUES {
|
||||
string value PK
|
||||
string description
|
||||
string category
|
||||
}
|
||||
DEPARTMENTS {
|
||||
int id PK
|
||||
string dept_type FK
|
||||
}
|
||||
STAFF {
|
||||
int id PK
|
||||
string status FK
|
||||
}
|
||||
INDICATORS {
|
||||
int id PK
|
||||
string indicator_type FK
|
||||
string bs_dimension FK
|
||||
}
|
||||
DEPARTMENTS }o--|| ENUM_VALUES : "has"
|
||||
STAFF }o--|| ENUM_VALUES : "has"
|
||||
INDICATORS }o--|| ENUM_VALUES : "has"
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [models.py](file://backend/app/models/models.py#L69-L125)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L28-L79)
|
||||
|
||||
### 查询优化策略
|
||||
|
||||
系统通过以下方式优化枚举查询性能：
|
||||
|
||||
1. **数据库索引优化**
|
||||
- 科室类型索引：`idx_dept_type`
|
||||
- 员工状态索引：`idx_staff_status`
|
||||
- 考核状态索引：`idx_assessment_status`
|
||||
|
||||
2. **查询条件优化**
|
||||
```python
|
||||
# 使用枚举值进行精确匹配
|
||||
query = query.where(Department.dept_type == dept_type)
|
||||
query = query.where(Staff.status == StaffStatus.ACTIVE)
|
||||
```
|
||||
|
||||
3. **批量查询优化**
|
||||
- 使用`selectinload`进行关联查询
|
||||
- 避免N+1查询问题
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L82-L178)
|
||||
- [department_service.py](file://backend/app/services/department_service.py#L25-L43)
|
||||
|
||||
### API使用流程
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as "客户端"
|
||||
participant API as "API接口"
|
||||
participant Service as "服务层"
|
||||
participant Model as "数据模型"
|
||||
participant DB as "数据库"
|
||||
Client->>API : GET /departments?type=clinical_surgical
|
||||
API->>Service : get_list(dept_type="clinical_surgical")
|
||||
Service->>Model : Department.dept_type == "clinical_surgical"
|
||||
Model->>DB : SELECT * FROM departments WHERE dept_type = ?
|
||||
DB-->>Model : 查询结果
|
||||
Model-->>Service : Department对象列表
|
||||
Service-->>API : 部门列表
|
||||
API-->>Client : JSON响应
|
||||
Note over Client,DB : 使用枚举值进行类型安全的查询
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [departments.py](file://backend/app/api/v1/departments.py#L20-L41)
|
||||
- [department_service.py](file://backend/app/services/department_service.py#L17-L43)
|
||||
|
||||
**章节来源**
|
||||
- [departments.py](file://backend/app/api/v1/departments.py#L1-L108)
|
||||
- [performance_plans.py](file://backend/app/api/v1/performance_plans.py#L21-L65)
|
||||
|
||||
### 状态流转流程
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> DRAFT : 创建计划
|
||||
DRAFT --> PENDING : 提交审批
|
||||
PENDING --> APPROVED : 审批通过
|
||||
PENDING --> REJECTED : 审批驳回
|
||||
APPROVED --> ACTIVE : 激活执行
|
||||
ACTIVE --> COMPLETED : 执行完成
|
||||
ACTIVE --> CANCELLED : 取消计划
|
||||
COMPLETED --> [*]
|
||||
REJECTED --> [*]
|
||||
CANCELLED --> [*]
|
||||
note right of DRAFT
|
||||
草稿状态
|
||||
可编辑修改
|
||||
end note
|
||||
note right of PENDING
|
||||
等待审批
|
||||
不可修改
|
||||
end note
|
||||
note right of APPROVED
|
||||
已批准
|
||||
准备执行
|
||||
end note
|
||||
note right of ACTIVE
|
||||
执行中
|
||||
数据录入
|
||||
end note
|
||||
note right of COMPLETED
|
||||
已完成
|
||||
统计分析
|
||||
end note
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L131-L182)
|
||||
- [models.py](file://backend/app/models/models.py#L233-L242)
|
||||
|
||||
**章节来源**
|
||||
- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L131-L182)
|
||||
|
||||
## 依赖关系分析
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
subgraph "核心枚举"
|
||||
A[DeptType]
|
||||
B[StaffStatus]
|
||||
C[AssessmentStatus]
|
||||
D[IndicatorType]
|
||||
E[PlanStatus]
|
||||
F[MenuType]
|
||||
end
|
||||
subgraph "模型映射"
|
||||
G[Department.dept_type]
|
||||
H[Staff.status]
|
||||
I[Assessment.status]
|
||||
J[Indicator.indicator_type]
|
||||
K[Indicator.bs_dimension]
|
||||
L[PerformancePlan.status]
|
||||
M[Menu.menu_type]
|
||||
end
|
||||
subgraph "API使用"
|
||||
N[departments.py]
|
||||
O[performance_plans.py]
|
||||
P[staff.py]
|
||||
Q[indicators.py]
|
||||
end
|
||||
A --> G
|
||||
B --> H
|
||||
C --> I
|
||||
D --> J
|
||||
E --> L
|
||||
F --> M
|
||||
G --> N
|
||||
H --> P
|
||||
I --> Q
|
||||
J --> Q
|
||||
L --> O
|
||||
M --> N
|
||||
style A fill:#e1f5fe
|
||||
style E fill:#e8f5e8
|
||||
style C fill:#fff3e0
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [models.py](file://backend/app/models/models.py#L69-L354)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L12-L652)
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L1-L438)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L1-L743)
|
||||
|
||||
## 性能考虑
|
||||
|
||||
### 存储优化
|
||||
- **字符串存储**：所有枚举值以字符串形式存储，占用空间小
|
||||
- **索引优化**：为常用查询字段建立数据库索引
|
||||
- **唯一约束**：确保枚举值的唯一性和一致性
|
||||
|
||||
### 查询优化
|
||||
- **精确匹配**：使用等值查询而非模糊匹配
|
||||
- **批量操作**：支持批量枚举值的查询和过滤
|
||||
- **缓存策略**：可将常用的枚举值缓存到内存中
|
||||
|
||||
### 内存优化
|
||||
- **类型安全**：编译时检查枚举值的有效性
|
||||
- **序列化开销**：字符串枚举比整数枚举有更高的序列化开销
|
||||
|
||||
## 故障排除指南
|
||||
|
||||
### 常见问题及解决方案
|
||||
|
||||
1. **枚举值不匹配**
|
||||
- 症状：数据库插入失败，提示枚举值无效
|
||||
- 解决：检查枚举定义是否与数据库schema一致
|
||||
- 验证：使用`SELECT DISTINCT column FROM table`检查现有值
|
||||
|
||||
2. **查询性能问题**
|
||||
- 症状：大量枚举查询导致性能下降
|
||||
- 解决：添加适当的数据库索引
|
||||
- 优化：使用`EXPLAIN`分析查询计划
|
||||
|
||||
3. **状态流转异常**
|
||||
- 症状：计划状态无法正常转换
|
||||
- 解决：检查状态转换逻辑和前置条件
|
||||
- 调试：查看状态转换日志和时间戳
|
||||
|
||||
**章节来源**
|
||||
- [init_db.py](file://backend/app/core/init_db.py#L33-L115)
|
||||
- [department_service.py](file://backend/app/services/department_service.py#L17-L150)
|
||||
|
||||
## 结论
|
||||
|
||||
该医院绩效系统的枚举类型设计体现了以下特点：
|
||||
|
||||
1. **完整性**：覆盖了医院管理的所有关键业务领域
|
||||
2. **一致性**：统一的数据存储格式和查询方式
|
||||
3. **可扩展性**：支持未来业务需求的变化和扩展
|
||||
4. **性能优化**：通过索引和查询优化确保系统性能
|
||||
5. **类型安全**：编译时检查确保数据的正确性
|
||||
|
||||
通过合理的枚举设计和实现，系统能够有效支撑医院绩效管理的各项业务需求，为决策提供可靠的数据支持。
|
||||
362
.qoder/repowiki/zh/content/数据库设计/表结构设计/核心业务表/员工信息表.md
Normal file
362
.qoder/repowiki/zh/content/数据库设计/表结构设计/核心业务表/员工信息表.md
Normal file
@@ -0,0 +1,362 @@
|
||||
# 员工信息表
|
||||
|
||||
<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)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py)
|
||||
- [database.md](file://docs/database.md)
|
||||
- [salary.py](file://backend/app/api/v1/salary.py)
|
||||
- [salary_service.py](file://backend/app/services/salary_service.py)
|
||||
- [Staff.vue](file://frontend/src/views/basic/Staff.vue)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖分析](#依赖分析)
|
||||
7. [性能考虑](#性能考虑)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
本文件围绕员工信息表（staff）展开，系统性说明字段的业务含义、状态枚举值、与科室表的一对多关系，以及在考核与工资核算中的应用。同时提供索引设计与数据完整性约束说明，并给出典型使用场景与最佳实践。
|
||||
|
||||
## 项目结构
|
||||
员工信息表位于后端数据模型层，配合服务层、API层与前端页面协同工作，形成“数据模型—服务—接口—视图”的完整链路。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "后端"
|
||||
M["models.py<br/>数据模型"]
|
||||
S["staff_service.py<br/>员工服务"]
|
||||
API["staff.py<br/>员工API"]
|
||||
SAL_API["salary.py<br/>工资API"]
|
||||
SAL_SVC["salary_service.py<br/>工资服务"]
|
||||
SCH["schemas.py<br/>数据模式"]
|
||||
end
|
||||
subgraph "前端"
|
||||
FE["Staff.vue<br/>员工管理页面"]
|
||||
end
|
||||
M --> S
|
||||
S --> API
|
||||
API --> FE
|
||||
SAL_API --> SAL_SVC
|
||||
SAL_SVC --> M
|
||||
SCH --> API
|
||||
SCH --> SAL_API
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [models.py](file://backend/app/models/models.py#L88-L115)
|
||||
- [staff_service.py](file://backend/app/services/staff_service.py#L13-L112)
|
||||
- [staff.py](file://backend/app/api/v1/staff.py#L1-L124)
|
||||
- [salary.py](file://backend/app/api/v1/salary.py#L1-L156)
|
||||
- [salary_service.py](file://backend/app/services/salary_service.py#L14-L260)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L107-L149)
|
||||
- [Staff.vue](file://frontend/src/views/basic/Staff.vue#L1-L313)
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L88-L115)
|
||||
- [staff.py](file://backend/app/api/v1/staff.py#L1-L124)
|
||||
- [staff_service.py](file://backend/app/services/staff_service.py#L13-L112)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L107-L149)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L42-L64)
|
||||
- [database.md](file://docs/database.md#L117-L136)
|
||||
|
||||
## 核心组件
|
||||
- 数据模型：定义员工表结构、字段约束、索引与关系。
|
||||
- 服务层：封装员工查询、创建、更新、删除等业务逻辑。
|
||||
- API层：对外暴露REST接口，处理请求与响应。
|
||||
- 数据模式：定义请求/响应的数据结构与校验规则。
|
||||
- 前端页面：提供员工信息的增删改查与筛选能力。
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L88-L115)
|
||||
- [staff_service.py](file://backend/app/services/staff_service.py#L13-L112)
|
||||
- [staff.py](file://backend/app/api/v1/staff.py#L1-L124)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L107-L149)
|
||||
- [Staff.vue](file://frontend/src/views/basic/Staff.vue#L1-L313)
|
||||
|
||||
## 架构总览
|
||||
员工信息表与科室表构成一对多关系：一个科室可包含多名员工；一名员工仅属于一个科室。员工表还与考核记录表、工资记录表存在一对多关系，用于支撑绩效考核与工资核算。
|
||||
|
||||
```mermaid
|
||||
erDiagram
|
||||
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
|
||||
}
|
||||
ASSESSMENTS {
|
||||
int id PK
|
||||
int staff_id FK
|
||||
int period_year
|
||||
int period_month
|
||||
string period_type
|
||||
numeric total_score
|
||||
numeric weighted_score
|
||||
enum status
|
||||
int assessor_id FK
|
||||
int reviewer_id FK
|
||||
datetime submit_time
|
||||
datetime review_time
|
||||
text remark
|
||||
datetime created_at
|
||||
datetime updated_at
|
||||
}
|
||||
SALARY_RECORDS {
|
||||
int id PK
|
||||
int staff_id FK
|
||||
int period_year
|
||||
int period_month
|
||||
numeric base_salary
|
||||
numeric performance_score
|
||||
numeric performance_bonus
|
||||
numeric deduction
|
||||
numeric allowance
|
||||
numeric total_salary
|
||||
string status
|
||||
text remark
|
||||
datetime created_at
|
||||
datetime updated_at
|
||||
}
|
||||
DEPARTMENTS ||--o{ STAFF : "拥有"
|
||||
STAFF ||--o{ ASSESSMENTS : "产生"
|
||||
STAFF ||--o{ SALARY_RECORDS : "产生"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [models.py](file://backend/app/models/models.py#L62-L86)
|
||||
- [models.py](file://backend/app/models/models.py#L88-L115)
|
||||
- [models.py](file://backend/app/models/models.py#L149-L178)
|
||||
- [models.py](file://backend/app/models/models.py#L205-L231)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L22-L64)
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L62-L86)
|
||||
- [models.py](file://backend/app/models/models.py#L88-L115)
|
||||
- [models.py](file://backend/app/models/models.py#L149-L178)
|
||||
- [models.py](file://backend/app/models/models.py#L205-L231)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L22-L64)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 字段业务含义与约束
|
||||
- 工号(employee_id)：唯一标识员工，用于跨系统识别与关联。
|
||||
- 姓名(name)：员工真实姓名。
|
||||
- 所属科室(department_id)：外键关联科室表，限定员工归属。
|
||||
- 职位(position)：员工在岗位上的职责描述。
|
||||
- 职称(title)：专业技术或管理职称。
|
||||
- 联系电话(phone)、邮箱(email)：通讯信息。
|
||||
- 基本工资(base_salary)：固定薪酬基数，参与工资核算。
|
||||
- 绩效系数(performance_ratio)：影响绩效奖金的浮动系数，数值越大，奖金越高。
|
||||
- 状态(status)：员工状态枚举，见下节。
|
||||
- 入职日期(hire_date)：记录入职时间。
|
||||
- created_at/updated_at：记录创建与更新时间戳。
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L88-L115)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L42-L64)
|
||||
- [database.md](file://docs/database.md#L117-L136)
|
||||
|
||||
### 状态枚举与作用机制
|
||||
- 在职(active)：正常在岗，参与考核与工资核算。
|
||||
- 休假(leave)：暂时离岗，通常不参与当期考核或按规则折算。
|
||||
- 离职(resigned)：已离开医院，一般不再参与后续考核与工资核算。
|
||||
- 退休(retired)：达到退休年龄，通常不再参与日常考核与工资核算。
|
||||
|
||||
在服务层与API层中，状态常用于过滤查询与业务判断，例如：
|
||||
- 列表查询时按状态筛选；
|
||||
- 生成工资时仅对在职员工进行计算；
|
||||
- 前端展示时对不同状态使用不同标签样式。
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L37-L43)
|
||||
- [staff_service.py](file://backend/app/services/staff_service.py#L17-L49)
|
||||
- [staff.py](file://backend/app/api/v1/staff.py#L20-L49)
|
||||
- [Staff.vue](file://frontend/src/views/basic/Staff.vue#L13-L18)
|
||||
|
||||
### 绩效系数的作用机制
|
||||
- 绩效奖金 = 绩效基数 × (绩效得分/100) × 绩效系数
|
||||
- 绩效系数越大，相同绩效得分能获得更高奖金，体现对高绩效员工的激励。
|
||||
- 工资服务层提供计算方法，支持按员工的绩效系数与考核得分生成绩效奖金。
|
||||
|
||||
章节来源
|
||||
- [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.py](file://backend/app/api/v1/salary.py#L96-L129)
|
||||
|
||||
### 与科室表的一对多关系
|
||||
- 一个科室可包含多名员工；
|
||||
- 一名员工仅属于一个科室；
|
||||
- 员工表通过外键department_id关联科室表；
|
||||
- 前端页面在展示员工列表时，会补充显示科室名称，便于直观查看。
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L62-L86)
|
||||
- [models.py](file://backend/app/models/models.py#L88-L115)
|
||||
- [staff.py](file://backend/app/api/v1/staff.py#L35-L41)
|
||||
- [Staff.vue](file://frontend/src/views/basic/Staff.vue#L27)
|
||||
|
||||
### 在考核与工资核算中的应用
|
||||
- 考核记录表(assessments)与员工表(staff)是一对多关系，用于记录每位员工的考核周期、得分与状态。
|
||||
- 工资记录表(salary_records)与员工表(staff)是一对多关系，用于记录每月工资构成与状态。
|
||||
- 工资生成流程：根据已确认的考核记录，读取员工的基本工资与绩效系数，计算绩效奖金并生成工资记录。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant FE as "前端页面"
|
||||
participant API as "工资API"
|
||||
participant SVC as "工资服务"
|
||||
participant DB as "数据库"
|
||||
participant ST as "员工表"
|
||||
participant AS as "考核记录表"
|
||||
FE->>API : "POST /salary/generate?staff_id&period_year&period_month"
|
||||
API->>SVC : "generate_from_assessment(staff_id, year, month)"
|
||||
SVC->>DB : "查询员工信息(含performance_ratio)"
|
||||
DB-->>SVC : "返回员工(含基本工资、系数)"
|
||||
SVC->>DB : "查询已确认的考核记录(weighted_score)"
|
||||
DB-->>SVC : "返回考核记录"
|
||||
SVC->>SVC : "计算绩效奖金 = 基数×(得分/100)×系数"
|
||||
SVC->>DB : "插入工资记录(total_salary=基本工资+奖金)"
|
||||
DB-->>SVC : "返回工资记录"
|
||||
SVC-->>API : "返回工资记录ID"
|
||||
API-->>FE : "生成成功"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [salary.py](file://backend/app/api/v1/salary.py#L96-L111)
|
||||
- [salary_service.py](file://backend/app/services/salary_service.py#L127-L191)
|
||||
- [models.py](file://backend/app/models/models.py#L88-L115)
|
||||
- [models.py](file://backend/app/models/models.py#L149-L178)
|
||||
|
||||
### 典型使用场景
|
||||
- 人员管理：新增/编辑/删除员工，按科室、状态、关键词筛选，分页展示。
|
||||
- 考核分配：为员工生成考核任务，记录考核结果与状态流转。
|
||||
- 工资计算：根据考核结果与员工基本信息，自动生成工资记录，支持批量生成与确认。
|
||||
|
||||
章节来源
|
||||
- [staff.py](file://backend/app/api/v1/staff.py#L20-L124)
|
||||
- [staff_service.py](file://backend/app/services/staff_service.py#L13-L112)
|
||||
- [salary.py](file://backend/app/api/v1/salary.py#L20-L156)
|
||||
- [salary_service.py](file://backend/app/services/salary_service.py#L14-L260)
|
||||
- [Staff.vue](file://frontend/src/views/basic/Staff.vue#L1-L313)
|
||||
|
||||
### 索引设计与数据完整性约束
|
||||
- 员工表索引
|
||||
- idx_staff_dept：加速按科室查询；
|
||||
- idx_staff_status：加速按状态查询。
|
||||
- 员工表约束
|
||||
- 唯一约束：employee_id；
|
||||
- 外键约束：department_id 引用 departments.id。
|
||||
- 迁移脚本与文档一致，确保索引与约束在数据库中正确创建。
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L111-L114)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L42-L64)
|
||||
- [database.md](file://docs/database.md#L117-L136)
|
||||
|
||||
## 依赖分析
|
||||
- 模型层依赖SQLAlchemy ORM定义实体与关系；
|
||||
- 服务层依赖模型层进行数据访问与业务计算；
|
||||
- API层依赖服务层与数据模式进行请求处理与响应构造；
|
||||
- 前端页面依赖API层进行数据交互。
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
FE["Staff.vue"] --> API["staff.py"]
|
||||
API --> SVC["staff_service.py"]
|
||||
SVC --> MODELS["models.py"]
|
||||
API --> SCH["schemas.py"]
|
||||
SAL_FE["工资API调用"] --> SAL_API["salary.py"]
|
||||
SAL_API --> SAL_SVC["salary_service.py"]
|
||||
SAL_SVC --> MODELS
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [staff.py](file://backend/app/api/v1/staff.py#L1-L124)
|
||||
- [staff_service.py](file://backend/app/services/staff_service.py#L13-L112)
|
||||
- [models.py](file://backend/app/models/models.py#L88-L115)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L107-L149)
|
||||
- [salary.py](file://backend/app/api/v1/salary.py#L1-L156)
|
||||
- [salary_service.py](file://backend/app/services/salary_service.py#L14-L260)
|
||||
|
||||
章节来源
|
||||
- [staff.py](file://backend/app/api/v1/staff.py#L1-L124)
|
||||
- [staff_service.py](file://backend/app/services/staff_service.py#L13-L112)
|
||||
- [models.py](file://backend/app/models/models.py#L88-L115)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L107-L149)
|
||||
- [salary.py](file://backend/app/api/v1/salary.py#L1-L156)
|
||||
- [salary_service.py](file://backend/app/services/salary_service.py#L14-L260)
|
||||
|
||||
## 性能考虑
|
||||
- 查询优化：利用idx_staff_dept与idx_staff_status索引，避免全表扫描；
|
||||
- 分页与排序：服务层对列表查询进行分页与排序，减轻前端压力；
|
||||
- 关联查询：使用selectinload按需加载关联数据，避免N+1查询问题；
|
||||
- 批量操作：工资模块提供批量生成与批量确认，提升大规模数据处理效率。
|
||||
|
||||
章节来源
|
||||
- [staff_service.py](file://backend/app/services/staff_service.py#L26-L49)
|
||||
- [salary_service.py](file://backend/app/services/salary_service.py#L32-L58)
|
||||
- [salary_service.py](file://backend/app/services/salary_service.py#L193-L219)
|
||||
|
||||
## 故障排查指南
|
||||
- 工号重复：创建员工时若工号已存在，接口会返回错误；
|
||||
- 员工不存在：更新或删除员工时若找不到对应记录，接口会返回错误；
|
||||
- 考核未确认：根据考核生成工资时，要求考核状态为已确认，否则无法生成；
|
||||
- 状态限制：更新工资记录时仅允许对“待确认”状态进行修改；
|
||||
- 权限限制：创建、更新、删除员工与生成/确认工资均需管理员或经理权限。
|
||||
|
||||
章节来源
|
||||
- [staff.py](file://backend/app/api/v1/staff.py#L75-L81)
|
||||
- [staff_service.py](file://backend/app/services/staff_service.py#L79-L91)
|
||||
- [salary.py](file://backend/app/api/v1/salary.py#L104-L110)
|
||||
- [salary_service.py](file://backend/app/services/salary_service.py#L104-L124)
|
||||
- [salary_service.py](file://backend/app/services/salary_service.py#L222-L231)
|
||||
|
||||
## 结论
|
||||
员工信息表是医院绩效系统的基础数据之一，承载着人员管理、考核与工资核算的关键信息。通过合理的字段设计、状态枚举与索引策略，以及完善的前后端协作，能够有效支撑系统的高效运行与业务闭环。
|
||||
|
||||
## 附录
|
||||
- 员工状态枚举值对照
|
||||
- active：在职
|
||||
- leave：休假
|
||||
- resigned：离职
|
||||
- retired：退休
|
||||
- 绩效系数范围：默认1.0，最大不超过5.0，前端输入也做了相应限制。
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L37-L43)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L117)
|
||||
- [Staff.vue](file://frontend/src/views/basic/Staff.vue#L111-L113)
|
||||
382
.qoder/repowiki/zh/content/数据库设计/表结构设计/核心业务表/工资核算记录表.md
Normal file
382
.qoder/repowiki/zh/content/数据库设计/表结构设计/核心业务表/工资核算记录表.md
Normal file
@@ -0,0 +1,382 @@
|
||||
# 工资核算记录表
|
||||
|
||||
<cite>
|
||||
**本文档引用的文件**
|
||||
- [models.py](file://backend/app/models/models.py)
|
||||
- [salary_service.py](file://backend/app/services/salary_service.py)
|
||||
- [salary.py](file://backend/app/api/v1/salary.py)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py)
|
||||
- [Salary.vue](file://frontend/src/views/salary/Salary.vue)
|
||||
- [init_db.py](file://backend/init_db.py)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构概览](#架构概览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考虑](#性能考虑)
|
||||
8. [故障排除指南](#故障排除指南)
|
||||
9. [结论](#结论)
|
||||
|
||||
## 简介
|
||||
|
||||
工资核算记录表（salary_records）是医院绩效管理系统中的核心数据表，用于记录和管理员工的工资核算信息。该表通过与员工信息表（staff）、考核记录表（assessments）等关键表的关联，实现了从绩效考核到工资发放的完整业务流程。
|
||||
|
||||
本表支持按月度周期进行工资核算，包含基本工资、绩效奖金、补贴、扣款等多个维度的工资构成要素，并通过状态字段实现了工资记录的生命周期管理。
|
||||
|
||||
## 项目结构
|
||||
|
||||
工资核算记录表在系统中的位置和作用如下：
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "数据模型层"
|
||||
SR[SalaryRecord<br/>工资核算记录表]
|
||||
ST[Staff<br/>员工信息表]
|
||||
AS[Assessment<br/>考核记录表]
|
||||
end
|
||||
subgraph "服务层"
|
||||
SS[SalaryService<br/>工资核算服务]
|
||||
end
|
||||
subgraph "API层"
|
||||
API[Salary API<br/>工资核算接口]
|
||||
end
|
||||
subgraph "前端界面"
|
||||
UI[Salary.vue<br/>工资管理界面]
|
||||
end
|
||||
ST --> SR
|
||||
AS --> SS
|
||||
SS --> SR
|
||||
SS --> API
|
||||
API --> UI
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [models.py](file://backend/app/models/models.py#L205-L230)
|
||||
- [salary_service.py](file://backend/app/services/salary_service.py#L14-L260)
|
||||
- [salary.py](file://backend/app/api/v1/salary.py#L1-L156)
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L205-L230)
|
||||
- [salary_service.py](file://backend/app/services/salary_service.py#L14-L260)
|
||||
|
||||
## 核心组件
|
||||
|
||||
### 数据模型定义
|
||||
|
||||
工资核算记录表采用SQLAlchemy ORM映射，具有以下核心特性：
|
||||
|
||||
- **主键标识**：自增整数ID作为唯一标识符
|
||||
- **外键关联**：关联到员工信息表（staff_id）
|
||||
- **索引优化**：针对员工ID和工资周期建立复合索引
|
||||
- **数据精度**：使用Numeric类型确保财务数据的精确性
|
||||
|
||||
### 字段详细说明
|
||||
|
||||
| 字段名 | 数据类型 | 默认值 | 业务含义 | 精度要求 |
|
||||
|--------|----------|--------|----------|----------|
|
||||
| id | Integer | 自增 | 工资记录唯一标识 | 无 |
|
||||
| staff_id | Integer | 无 | 员工ID | 外键约束 |
|
||||
| period_year | Integer | 无 | 年度 | 无 |
|
||||
| period_month | Integer | 无 | 月份 | 1-12 |
|
||||
| base_salary | Numeric(10,2) | 0.00 | 基本工资 | 精确到分 |
|
||||
| performance_score | Numeric(5,2) | 0.00 | 绩效得分 | 0-100分 |
|
||||
| performance_bonus | Numeric(10,2) | 0.00 | 绩效奖金 | 精确到分 |
|
||||
| deduction | Numeric(10,2) | 0.00 | 扣款 | 精确到分 |
|
||||
| allowance | Numeric(10,2) | 0.00 | 补贴 | 精确到分 |
|
||||
| total_salary | Numeric(10,2) | 0.00 | 应发工资 | 精确到分 |
|
||||
| status | String(20) | "pending" | 状态 | 枚举值 |
|
||||
| remark | Text | null | 备注 | 文本 |
|
||||
| created_at | DateTime | 当前时间 | 创建时间 | 时间戳 |
|
||||
| updated_at | DateTime | 当前时间 | 更新时间 | 时间戳 |
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L205-L230)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L133-L154)
|
||||
|
||||
## 架构概览
|
||||
|
||||
工资核算系统的整体架构采用分层设计，确保了业务逻辑的清晰分离和数据的一致性：
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant UI as 前端界面
|
||||
participant API as API接口
|
||||
participant Service as 服务层
|
||||
participant Model as 数据模型
|
||||
participant DB as 数据库
|
||||
UI->>API : 查询工资记录
|
||||
API->>Service : get_list()
|
||||
Service->>Model : 查询SalaryRecord
|
||||
Model->>DB : 执行SQL查询
|
||||
DB-->>Model : 返回结果集
|
||||
Model-->>Service : SalaryRecord对象
|
||||
Service-->>API : 处理后的数据
|
||||
API-->>UI : 响应结果
|
||||
Note over UI,DB : 异步数据库操作
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [salary.py](file://backend/app/api/v1/salary.py#L20-L51)
|
||||
- [salary_service.py](file://backend/app/services/salary_service.py#L21-L58)
|
||||
|
||||
**章节来源**
|
||||
- [salary.py](file://backend/app/api/v1/salary.py#L1-L156)
|
||||
- [salary_service.py](file://backend/app/services/salary_service.py#L14-L260)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 工资计算公式
|
||||
|
||||
工资核算的核心计算逻辑遵循以下公式：
|
||||
|
||||
```
|
||||
应发工资 = 基本工资 + 绩效奖金 + 补贴 - 扣款
|
||||
```
|
||||
|
||||
其中，绩效奖金的计算采用以下公式：
|
||||
|
||||
```
|
||||
绩效奖金 = 绩效基数 × (绩效得分/100) × 绩效系数
|
||||
```
|
||||
|
||||
系统中预设的绩效基数为3000.0元，这一数值可以根据医院的实际情况进行调整。
|
||||
|
||||
### 状态管理机制
|
||||
|
||||
工资记录的状态流转遵循严格的业务规则：
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> 待确认
|
||||
待确认 --> 已确认 : 确认操作
|
||||
已确认 --> 待确认 : 状态重置不支持
|
||||
note right of 待确认
|
||||
新创建的工资记录默认状态
|
||||
可进行编辑和确认
|
||||
end note
|
||||
note right of 已确认
|
||||
已确认的工资记录
|
||||
不允许再次编辑
|
||||
end note
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [salary_service.py](file://backend/app/services/salary_service.py#L222-L231)
|
||||
- [salary_service.py](file://backend/app/services/salary_service.py#L234-L259)
|
||||
|
||||
### 业务流程详解
|
||||
|
||||
#### 单个工资记录生成流程
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([开始]) --> GetAssessment["获取考核记录"]
|
||||
GetAssessment --> CheckAssessment{"是否存在已确认的<br/>考核记录？"}
|
||||
CheckAssessment --> |否| ReturnNull["返回空值"]
|
||||
CheckAssessment --> |是| CheckExist["检查是否已存在<br/>工资记录"]
|
||||
CheckExist --> |已存在| ReturnNull
|
||||
CheckExist --> |不存在| CalcBonus["计算绩效奖金"]
|
||||
CalcBonus --> CalcTotal["计算应发工资"]
|
||||
CalcTotal --> CreateRecord["创建工资记录"]
|
||||
CreateRecord --> SetPending["设置状态为待确认"]
|
||||
SetPending --> End([结束])
|
||||
ReturnNull --> End
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [salary_service.py](file://backend/app/services/salary_service.py#L127-L190)
|
||||
|
||||
#### 批量工资生成流程
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Manager as 管理员
|
||||
participant API as 批量生成接口
|
||||
participant Service as 服务层
|
||||
participant DB as 数据库
|
||||
Manager->>API : 请求批量生成
|
||||
API->>Service : batch_generate_for_department()
|
||||
Service->>DB : 查询已确认考核记录
|
||||
DB-->>Service : 考核记录列表
|
||||
Service->>Service : 逐条生成工资记录
|
||||
Service->>DB : 批量插入工资记录
|
||||
DB-->>Service : 插入结果
|
||||
Service-->>API : 返回生成统计
|
||||
API-->>Manager : 显示生成结果
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [salary_service.py](file://backend/app/services/salary_service.py#L193-L219)
|
||||
|
||||
**章节来源**
|
||||
- [salary_service.py](file://backend/app/services/salary_service.py#L71-L190)
|
||||
|
||||
### 数据一致性保证
|
||||
|
||||
系统通过多种机制确保数据的一致性和完整性：
|
||||
|
||||
#### 数据验证机制
|
||||
- **前端验证**：使用Element Plus组件进行输入验证
|
||||
- **后端验证**：Pydantic模型进行数据格式和范围验证
|
||||
- **数据库约束**：Numeric类型确保财务数据精度
|
||||
|
||||
#### 事务处理
|
||||
- **异步事务**：使用SQLAlchemy异步会话确保操作原子性
|
||||
- **批量操作**：支持批量生成和批量确认操作
|
||||
- **错误回滚**：异常情况下自动回滚事务
|
||||
|
||||
#### 并发控制策略
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Request[并发请求] --> CheckStatus{"检查记录状态"}
|
||||
CheckStatus --> |待确认| Proceed[执行操作]
|
||||
CheckStatus --> |已确认| Reject[拒绝操作]
|
||||
Proceed --> UpdateDB[更新数据库]
|
||||
UpdateDB --> Commit[提交事务]
|
||||
Reject --> ErrorResp[返回错误]
|
||||
Commit --> Success[操作成功]
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [salary_service.py](file://backend/app/services/salary_service.py#L104-L124)
|
||||
- [salary_service.py](file://backend/app/services/salary_service.py#L222-L231)
|
||||
|
||||
**章节来源**
|
||||
- [salary_service.py](file://backend/app/services/salary_service.py#L104-L124)
|
||||
- [salary_service.py](file://backend/app/services/salary_service.py#L222-L231)
|
||||
|
||||
## 依赖关系分析
|
||||
|
||||
### 数据模型依赖
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
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
|
||||
+datetime created_at
|
||||
+datetime updated_at
|
||||
+staff : Staff
|
||||
}
|
||||
class Staff {
|
||||
+int id
|
||||
+string employee_id
|
||||
+string name
|
||||
+int department_id
|
||||
+string position
|
||||
+string title
|
||||
+float base_salary
|
||||
+float performance_ratio
|
||||
+StaffStatus status
|
||||
+datetime hire_date
|
||||
+SalaryRecord[] salary_records
|
||||
}
|
||||
class Assessment {
|
||||
+int id
|
||||
+int staff_id
|
||||
+int period_year
|
||||
+int period_month
|
||||
+float total_score
|
||||
+float weighted_score
|
||||
+AssessmentStatus status
|
||||
+datetime created_at
|
||||
+datetime updated_at
|
||||
}
|
||||
SalaryRecord --> Staff : "外键关联"
|
||||
Staff --> SalaryRecord : "一对多关系"
|
||||
Assessment --> Staff : "外键关联"
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [models.py](file://backend/app/models/models.py#L88-L114)
|
||||
- [models.py](file://backend/app/models/models.py#L205-L230)
|
||||
|
||||
### 服务层依赖
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
API[Salary API] --> Service[SalaryService]
|
||||
Service --> Model[SalaryRecord模型]
|
||||
Service --> StaffModel[Staff模型]
|
||||
Service --> AssessmentModel[Assessment模型]
|
||||
Service --> Schema[SalaryRecordSchema]
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [salary.py](file://backend/app/api/v1/salary.py#L14-L15)
|
||||
- [salary_service.py](file://backend/app/services/salary_service.py#L10-L11)
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L205-L230)
|
||||
- [salary_service.py](file://backend/app/services/salary_service.py#L10-L11)
|
||||
|
||||
## 性能考虑
|
||||
|
||||
### 查询优化
|
||||
|
||||
系统通过以下索引优化查询性能：
|
||||
- **员工索引**：`idx_salary_staff` - 加速按员工查询
|
||||
- **周期索引**：`idx_salary_period` - 加速按年月查询
|
||||
- **组合索引**：支持复杂的多条件查询
|
||||
|
||||
### 批量操作优化
|
||||
|
||||
- **批量生成**：支持按科室批量生成工资记录
|
||||
- **批量确认**：支持按年月批量确认工资记录
|
||||
- **分页查询**：默认每页20条记录，支持最大100条/页
|
||||
|
||||
### 内存管理
|
||||
|
||||
- **异步处理**：使用async/await避免阻塞
|
||||
- **流式查询**：Large result set使用流式处理
|
||||
- **连接池**：数据库连接复用减少开销
|
||||
|
||||
## 故障排除指南
|
||||
|
||||
### 常见问题及解决方案
|
||||
|
||||
#### 工资记录状态错误
|
||||
**问题**：尝试编辑已确认的工资记录失败
|
||||
**原因**：状态检查机制阻止了对已确认记录的修改
|
||||
**解决方案**：先将状态重置为待确认，再进行编辑
|
||||
|
||||
#### 绩效奖金计算异常
|
||||
**问题**：绩效奖金计算结果不正确
|
||||
**原因**：绩效基数或绩效系数设置不当
|
||||
**解决方案**：检查员工的绩效系数设置，确认绩效基数配置
|
||||
|
||||
#### 工资记录重复生成
|
||||
**问题**：同一员工同一个月重复生成工资记录
|
||||
**原因**：系统未检测到已存在的工资记录
|
||||
**解决方案**：检查数据库中是否存在重复记录，清理后重新生成
|
||||
|
||||
**章节来源**
|
||||
- [salary_service.py](file://backend/app/services/salary_service.py#L104-L124)
|
||||
- [salary_service.py](file://backend/app/services/salary_service.py#L155-L164)
|
||||
|
||||
## 结论
|
||||
|
||||
工资核算记录表作为医院绩效管理系统的核心组件，通过严谨的数据模型设计、完善的业务流程控制和可靠的技术实现，为医院的薪酬管理提供了完整的解决方案。
|
||||
|
||||
系统的主要优势包括：
|
||||
- **完整的生命周期管理**：从生成到确认的完整状态流转
|
||||
- **灵活的计算机制**：支持多种工资构成要素的动态计算
|
||||
- **强大的扩展性**：支持批量操作和复杂查询需求
|
||||
- **严格的数据一致性**：通过多种机制确保数据的准确性和完整性
|
||||
|
||||
通过合理使用本系统，医院可以实现绩效工资的自动化核算，提高薪酬管理的效率和准确性，为建立科学合理的绩效管理体系奠定坚实基础。
|
||||
463
.qoder/repowiki/zh/content/数据库设计/表结构设计/核心业务表/核心业务表.md
Normal file
463
.qoder/repowiki/zh/content/数据库设计/表结构设计/核心业务表/核心业务表.md
Normal file
@@ -0,0 +1,463 @@
|
||||
# 核心业务表
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py)
|
||||
- [backend/alembic/versions/001_initial.py](file://backend/alembic/versions/001_initial.py)
|
||||
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py)
|
||||
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py)
|
||||
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py)
|
||||
- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py)
|
||||
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py)
|
||||
- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py)
|
||||
- [backend/init_db.py](file://backend/init_db.py)
|
||||
- [backend/app/core/database.py](file://backend/app/core/database.py)
|
||||
- [backend/app/core/config.py](file://backend/app/core/config.py)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖分析](#依赖分析)
|
||||
7. [性能考量](#性能考量)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
本文件聚焦于系统核心业务表的完整结构与使用说明，覆盖以下五张表：
|
||||
- 科室信息表(departments)
|
||||
- 员工信息表(staff)
|
||||
- 考核记录表(assessments)
|
||||
- 考核明细表(assessment_details)
|
||||
- 工资核算记录表(salary_records)
|
||||
|
||||
内容包括：字段定义（数据类型、约束、默认值、业务含义）、主键/外键关系、表间关联关系图、典型使用场景与数据流转过程、索引设计与性能考虑。
|
||||
|
||||
## 项目结构
|
||||
后端采用FastAPI + SQLAlchemy 2.x异步ORM + PostgreSQL，模型定义位于models.py，迁移脚本由Alembic生成，服务层封装业务逻辑，API层提供REST接口。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "后端"
|
||||
A["models/models.py<br/>定义核心模型与关系"]
|
||||
B["alembic/versions/001_initial.py<br/>初始迁移脚本"]
|
||||
C["services/*<br/>业务服务层"]
|
||||
D["api/v1/*<br/>REST API"]
|
||||
E["core/database.py<br/>异步引擎与会话"]
|
||||
F["core/config.py<br/>配置项"]
|
||||
end
|
||||
A --> C
|
||||
B --> A
|
||||
C --> D
|
||||
E --> A
|
||||
F --> E
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L230)
|
||||
- [backend/alembic/versions/001_initial.py](file://backend/alembic/versions/001_initial.py#L21-L183)
|
||||
- [backend/app/core/database.py](file://backend/app/core/database.py#L9-L39)
|
||||
- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L22)
|
||||
|
||||
章节来源
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L230)
|
||||
- [backend/alembic/versions/001_initial.py](file://backend/alembic/versions/001_initial.py#L21-L183)
|
||||
- [backend/app/core/database.py](file://backend/app/core/database.py#L9-L39)
|
||||
- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L22)
|
||||
|
||||
## 核心组件
|
||||
- 科室信息表(departments)
|
||||
- 主键: id
|
||||
- 外键: parent_id → departments.id（自关联，形成树形组织结构）
|
||||
- 约束: code唯一；level默认1；is_active默认true
|
||||
- 索引: idx_dept_type, idx_dept_parent
|
||||
- 员工信息表(staff)
|
||||
- 主键: id
|
||||
- 外键: department_id → departments.id
|
||||
- 约束: employee_id唯一；status枚举；base_salary/performance_ratio默认值
|
||||
- 索引: idx_staff_dept, idx_staff_status
|
||||
- 考核记录表(assessments)
|
||||
- 主键: id
|
||||
- 外键: staff_id → staff.id；assessor_id/reviewer_id → staff.id（自关联）
|
||||
- 约束: period_year/period_month组合用于周期标识；status枚举；默认草稿
|
||||
- 索引: idx_assessment_staff, idx_assessment_period, idx_assessment_status
|
||||
- 考核明细表(assessment_details)
|
||||
- 主键: id
|
||||
- 外键: assessment_id → assessments.id；indicator_id → indicators.id
|
||||
- 约束: 默认score为0；证据与备注支持空值
|
||||
- 索引: idx_detail_assessment, idx_detail_indicator
|
||||
- 工资核算记录表(salary_records)
|
||||
- 主键: id
|
||||
- 外键: staff_id → staff.id
|
||||
- 约束: period_year/period_month组合；默认pending；total_salary为派生字段（base+bonus+allowance-deduction）
|
||||
- 索引: idx_salary_staff, idx_salary_period
|
||||
|
||||
章节来源
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L230)
|
||||
- [backend/alembic/versions/001_initial.py](file://backend/alembic/versions/001_initial.py#L22-L154)
|
||||
|
||||
## 架构总览
|
||||
核心业务表围绕“科室-员工-考核-工资”主线展开，形成如下关系：
|
||||
|
||||
```mermaid
|
||||
erDiagram
|
||||
DEPARTMENTS {
|
||||
int id PK
|
||||
string name
|
||||
string code UK
|
||||
string dept_type
|
||||
int parent_id FK
|
||||
int level
|
||||
int sort_order
|
||||
boolean is_active
|
||||
text description
|
||||
datetime created_at
|
||||
datetime updated_at
|
||||
}
|
||||
STAFF {
|
||||
int id PK
|
||||
string employee_id UK
|
||||
string name
|
||||
int department_id FK
|
||||
string position
|
||||
string title
|
||||
string phone
|
||||
string email
|
||||
numeric base_salary
|
||||
numeric performance_ratio
|
||||
string status
|
||||
datetime hire_date
|
||||
datetime created_at
|
||||
datetime updated_at
|
||||
}
|
||||
ASSESSMENTS {
|
||||
int id PK
|
||||
int staff_id FK
|
||||
int period_year
|
||||
int period_month
|
||||
string period_type
|
||||
numeric total_score
|
||||
numeric weighted_score
|
||||
string status
|
||||
int assessor_id FK
|
||||
int reviewer_id FK
|
||||
datetime submit_time
|
||||
datetime review_time
|
||||
text remark
|
||||
datetime created_at
|
||||
datetime updated_at
|
||||
}
|
||||
ASSESSMENT_DETAILS {
|
||||
int id PK
|
||||
int assessment_id FK
|
||||
int indicator_id FK
|
||||
numeric actual_value
|
||||
numeric score
|
||||
text evidence
|
||||
text remark
|
||||
datetime created_at
|
||||
datetime updated_at
|
||||
}
|
||||
SALARY_RECORDS {
|
||||
int id PK
|
||||
int staff_id FK
|
||||
int period_year
|
||||
int period_month
|
||||
numeric base_salary
|
||||
numeric performance_score
|
||||
numeric performance_bonus
|
||||
numeric deduction
|
||||
numeric allowance
|
||||
numeric total_salary
|
||||
string status
|
||||
text remark
|
||||
datetime created_at
|
||||
datetime updated_at
|
||||
}
|
||||
DEPARTMENTS ||--o{ STAFF : "拥有"
|
||||
STAFF ||--o{ ASSESSMENTS : "产生"
|
||||
STAFF ||--o{ SALARY_RECORDS : "对应"
|
||||
ASSESSMENTS ||--o{ ASSESSMENT_DETAILS : "包含"
|
||||
ASSESSMENTS }o--|| STAFF : "被考核者"
|
||||
ASSESSMENTS }o--|| STAFF : "考核人/审核人(自关联)"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L230)
|
||||
- [backend/alembic/versions/001_initial.py](file://backend/alembic/versions/001_initial.py#L22-L154)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 科室信息表(departments)
|
||||
- 字段与约束
|
||||
- id: 主键，自增
|
||||
- name: 非空，科室名称
|
||||
- code: 非空且唯一，科室编码
|
||||
- dept_type: 非空，枚举类型（含临床、医技、护理、行政、财务、后勤等）
|
||||
- parent_id: 可空，指向自身id，支持树形层级
|
||||
- level: 默认1，层级
|
||||
- sort_order: 默认0，排序
|
||||
- is_active: 默认true，是否启用
|
||||
- description: 描述
|
||||
- created_at/updated_at: 时间戳
|
||||
- 关系
|
||||
- 自关联父子关系（一对多）
|
||||
- 与staff一对多（反向backref: children）
|
||||
- 典型使用场景
|
||||
- 获取科室树形结构（API: GET /api/v1/departments/tree）
|
||||
- 列表查询与筛选（API: GET /api/v1/departments）
|
||||
- 新建/更新/删除（需管理员或经理权限）
|
||||
- 索引
|
||||
- idx_dept_type：按类型过滤
|
||||
- idx_dept_parent：树形查询与层级遍历
|
||||
|
||||
章节来源
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L86)
|
||||
- [backend/alembic/versions/001_initial.py](file://backend/alembic/versions/001_initial.py#L22-L41)
|
||||
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L20-L51)
|
||||
|
||||
### 员工信息表(staff)
|
||||
- 字段与约束
|
||||
- id: 主键，自增
|
||||
- employee_id: 非空且唯一，工号
|
||||
- name: 非空，姓名
|
||||
- department_id: 非空，外键→departments.id
|
||||
- position/title/phone/email: 基本信息
|
||||
- base_salary: 默认0，基本工资
|
||||
- performance_ratio: 默认1.0，绩效系数
|
||||
- status: 枚举，默认active
|
||||
- hire_date: 入职日期
|
||||
- created_at/updated_at: 时间戳
|
||||
- 关系
|
||||
- belongs_to: department（一对一反向：department.staff）
|
||||
- has_many: assessments（按staff_id反向）
|
||||
- has_many: salary_records（按staff_id反向）
|
||||
- 典型使用场景
|
||||
- 查询某科室员工列表（API: GET /api/v1/staff/department/{department_id}）
|
||||
- 列表与筛选（API: GET /api/v1/staff）
|
||||
- 新建/更新/删除（需管理员或经理权限）
|
||||
- 索引
|
||||
- idx_staff_dept：按科室过滤
|
||||
- idx_staff_status：按状态过滤
|
||||
|
||||
章节来源
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L88-L115)
|
||||
- [backend/alembic/versions/001_initial.py](file://backend/alembic/versions/001_initial.py#L42-L64)
|
||||
- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py#L20-L124)
|
||||
|
||||
### 考核记录表(assessments)
|
||||
- 字段与约束
|
||||
- id: 主键，自增
|
||||
- staff_id: 非空，外键→staff.id
|
||||
- period_year/month: 非空，周期标识
|
||||
- period_type: 默认monthly
|
||||
- total_score/weighted_score: 数值型，默认0
|
||||
- status: 枚举，默认draft
|
||||
- assessor_id/reviewer_id: 外键→staff.id（自关联）
|
||||
- submit_time/review_time: 审核流程时间
|
||||
- remark: 备注
|
||||
- created_at/updated_at: 时间戳
|
||||
- 关系
|
||||
- belongs_to: staff（正向），反向：staff.assessments
|
||||
- belongs_to: staff（assessor/reviewer，自关联）
|
||||
- has_many: details（AssessmentDetail，级联删除）
|
||||
- 典型使用场景
|
||||
- 列表与筛选（API: GET /api/v1/assessments）
|
||||
- 详情（带指标名称回填）
|
||||
- 提交/审核/确认（API: POST /{id}/submit, /{id}/review, /{id}/finalize）
|
||||
- 批量创建（按科室与指标集合）
|
||||
- 索引
|
||||
- idx_assessment_staff：按员工过滤
|
||||
- idx_assessment_period：按年月周期过滤
|
||||
- idx_assessment_status：按状态过滤
|
||||
|
||||
章节来源
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L149-L179)
|
||||
- [backend/alembic/versions/001_initial.py](file://backend/alembic/versions/001_initial.py#L87-L113)
|
||||
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L20-L166)
|
||||
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L18-L56)
|
||||
|
||||
### 考核明细表(assessment_details)
|
||||
- 字段与约束
|
||||
- id: 主键，自增
|
||||
- assessment_id: 非空，外键→assessments.id
|
||||
- indicator_id: 非空，外键→indicators.id
|
||||
- actual_value: 实际值
|
||||
- score: 默认0
|
||||
- evidence/remark: 佐证材料与备注
|
||||
- created_at/updated_at: 时间戳
|
||||
- 关系
|
||||
- belongs_to: assessment（反向：details）
|
||||
- belongs_to: indicator（反向：assessment_details）
|
||||
- 典型使用场景
|
||||
- 创建/更新考核时批量写入明细
|
||||
- 读取详情时携带指标名称
|
||||
- 索引
|
||||
- idx_detail_assessment：按考核记录过滤
|
||||
- idx_detail_indicator：按指标过滤
|
||||
|
||||
章节来源
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L181-L203)
|
||||
- [backend/alembic/versions/001_initial.py](file://backend/alembic/versions/001_initial.py#L114-L132)
|
||||
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L71-L109)
|
||||
|
||||
### 工资核算记录表(salary_records)
|
||||
- 字段与约束
|
||||
- id: 主键，自增
|
||||
- staff_id: 非空，外键→staff.id
|
||||
- period_year/month: 非空，周期标识
|
||||
- base_salary/performance_score/performance_bonus/deduction/allowance: 数值型，默认0
|
||||
- total_salary: 默认0，派生字段（base+bonus+allowance−deduction）
|
||||
- status: 默认pending
|
||||
- remark: 备注
|
||||
- created_at/updated_at: 时间戳
|
||||
- 关系
|
||||
- belongs_to: staff（反向：salary_records）
|
||||
- 典型使用场景
|
||||
- 列表与筛选（API: GET /api/v1/salary）
|
||||
- 详情（带员工与科室名称）
|
||||
- 从已确认考核生成工资（API: POST /generate）
|
||||
- 批量生成/确认
|
||||
- 索引
|
||||
- idx_salary_staff：按员工过滤
|
||||
- idx_salary_period：按年月周期过滤
|
||||
|
||||
章节来源
|
||||
- [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)
|
||||
- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L20-L156)
|
||||
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L21-L59)
|
||||
|
||||
## 依赖分析
|
||||
- 数据库连接与引擎
|
||||
- 使用异步SQLAlchemy引擎与会话工厂，PostgreSQL驱动
|
||||
- 迁移与建表
|
||||
- 初始迁移脚本创建上述五张核心表，并建立相应索引
|
||||
- 服务层依赖
|
||||
- AssessmentService与SalaryService分别封装考核与工资的业务逻辑
|
||||
- API层依赖
|
||||
- 各API路由调用对应服务层方法，返回标准化响应
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
CFG["config.py<br/>DATABASE_URL等配置"] --> DB["database.py<br/>异步引擎/会话"]
|
||||
DB --> MODELS["models.py<br/>核心模型"]
|
||||
MIG["001_initial.py<br/>迁移脚本"] --> MODELS
|
||||
MODELS --> SVC_ASSESS["assessment_service.py"]
|
||||
MODELS --> SVC_SALARY["salary_service.py"]
|
||||
SVC_ASSESS --> API_ASSESS["assessments.py"]
|
||||
SVC_SALARY --> API_SALARY["salary.py"]
|
||||
API_DEPT["departments.py"] --> SVC_ASSESS
|
||||
API_STAFF["staff.py"] --> SVC_SALARY
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L22)
|
||||
- [backend/app/core/database.py](file://backend/app/core/database.py#L9-L39)
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L230)
|
||||
- [backend/alembic/versions/001_initial.py](file://backend/alembic/versions/001_initial.py#L21-L183)
|
||||
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L14-L263)
|
||||
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L14-L260)
|
||||
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L17-L108)
|
||||
- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py#L17-L124)
|
||||
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L17-L166)
|
||||
- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L17-L156)
|
||||
|
||||
章节来源
|
||||
- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L22)
|
||||
- [backend/app/core/database.py](file://backend/app/core/database.py#L9-L39)
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L230)
|
||||
- [backend/alembic/versions/001_initial.py](file://backend/alembic/versions/001_initial.py#L21-L183)
|
||||
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L14-L263)
|
||||
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L14-L260)
|
||||
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L17-L108)
|
||||
- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py#L17-L124)
|
||||
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L17-L166)
|
||||
- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L17-L156)
|
||||
|
||||
## 性能考量
|
||||
- 索引策略
|
||||
- departments：按dept_type与parent_id建立索引，支撑类型筛选与树形查询
|
||||
- staff：按department_id与status建立索引，支撑科室与状态过滤
|
||||
- assessments：按staff_id、period_year+period_month、status建立索引，支撑员工周期与状态查询
|
||||
- assessment_details：按assessment_id与indicator_id建立索引，支撑明细查询
|
||||
- salary_records：按staff_id与period_year+period_month建立索引，支撑员工周期查询
|
||||
- 数据类型选择
|
||||
- 数值型采用numeric(precision, scale)，确保财务与评分精度
|
||||
- 日期时间统一使用DateTime，便于排序与范围查询
|
||||
- 查询优化建议
|
||||
- 列表查询尽量结合索引列过滤（如period、status、dept_id）
|
||||
- 使用selectinload或joinedload减少N+1查询（服务层已示范）
|
||||
- 批量操作使用flush/commit合并事务，降低往返开销
|
||||
- 并发与连接池
|
||||
- 通过配置项设置连接池大小与溢出，避免高并发下的连接争用
|
||||
|
||||
章节来源
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L82-L85)
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L111-L114)
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L174-L178)
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L199-L202)
|
||||
- [backend/app/models/models.py](file://backend/app/models/models.py#L227-L230)
|
||||
- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L22)
|
||||
|
||||
## 故障排查指南
|
||||
- 数据库连接问题
|
||||
- 检查DATABASE_URL、数据库是否存在、凭据是否正确
|
||||
- 参考：[QWEN.md](file://QWEN.md#L535-L540)
|
||||
- 迁移失败
|
||||
- 查看迁移状态与历史，必要时降级再升级
|
||||
- 参考：[QWEN.md](file://QWEN.md#L541-L552)
|
||||
- 重复唯一键
|
||||
- 科室编码重复：departments.code唯一
|
||||
- 员工工号重复：staff.employee_id唯一
|
||||
- 参考：API层在创建时进行存在性检查
|
||||
- 业务状态限制
|
||||
- 考核仅允许在草稿或驳回状态下更新
|
||||
- 工资仅允许在pending状态下更新
|
||||
- 参考：服务层状态判断逻辑
|
||||
- 初始化数据
|
||||
- 可运行初始化脚本创建默认科室、员工、指标与管理员账户
|
||||
- 参考：[init_db.py](file://backend/init_db.py#L11-L83)
|
||||
|
||||
章节来源
|
||||
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L74-L78)
|
||||
- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py#L75-L79)
|
||||
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L117-L119)
|
||||
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L107-L108)
|
||||
- [backend/init_db.py](file://backend/init_db.py#L11-L83)
|
||||
- [QWEN.md](file://QWEN.md#L535-L552)
|
||||
|
||||
## 结论
|
||||
本文系统梳理了核心业务表的结构、关系与使用方式，明确了索引设计与性能要点，并提供了常见问题的排查路径。基于该模型，系统实现了从“科室组织—员工—考核—工资”的闭环管理，满足医院绩效管理的关键需求。
|
||||
|
||||
## 附录
|
||||
- 数据流转示例（从考核到工资）
|
||||
- 考核流程：创建→提交→审核→确认（状态变更）
|
||||
- 工资生成：根据已确认考核与员工绩效系数计算绩效奖金，生成工资记录
|
||||
- 确认发放：批量或单条确认，进入待发放状态
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant API as "API 层"
|
||||
participant SvcAssess as "AssessmentService"
|
||||
participant SvcSalary as "SalaryService"
|
||||
participant DB as "数据库"
|
||||
API->>SvcAssess : "创建/提交/审核/确认 考核"
|
||||
SvcAssess->>DB : "写入assessments与assessment_details"
|
||||
API->>SvcSalary : "根据staff_id+period生成工资"
|
||||
SvcSalary->>DB : "读取staff与finalized assessment"
|
||||
SvcSalary->>SvcSalary : "计算绩效奖金与总工资"
|
||||
SvcSalary->>DB : "写入salary_records"
|
||||
API->>SvcSalary : "确认工资"
|
||||
SvcSalary->>DB : "更新status=pending→confirmed"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L80-L146)
|
||||
- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L96-L143)
|
||||
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L71-L206)
|
||||
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L127-L231)
|
||||
402
.qoder/repowiki/zh/content/数据库设计/表结构设计/核心业务表/科室信息表.md
Normal file
402
.qoder/repowiki/zh/content/数据库设计/表结构设计/核心业务表/科室信息表.md
Normal file
@@ -0,0 +1,402 @@
|
||||
# 科室信息表
|
||||
|
||||
<cite>
|
||||
**本文档引用的文件**
|
||||
- [models.py](file://backend/app/models/models.py)
|
||||
- [departments.py](file://backend/app/api/v1/departments.py)
|
||||
- [department_service.py](file://backend/app/services/department_service.py)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py)
|
||||
- [Departments.vue](file://frontend/src/views/basic/Departments.vue)
|
||||
- [database.md](file://docs/database.md)
|
||||
- [api.md](file://docs/api.md)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构概览](#架构概览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考虑](#性能考虑)
|
||||
8. [故障排除指南](#故障排除指南)
|
||||
9. [结论](#结论)
|
||||
|
||||
## 简介
|
||||
|
||||
科室信息表是医院绩效管理系统中的核心基础数据表，用于存储医院各个科室的基本信息和组织架构关系。该表实现了完整的树形结构管理，支持多层级的科室组织关系，并为绩效考核、员工管理、财务核算等功能提供基础数据支撑。
|
||||
|
||||
## 项目结构
|
||||
|
||||
科室信息表在项目中的位置和相关组件分布如下：
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "后端架构"
|
||||
A[models.py<br/>数据模型定义]
|
||||
B[department_service.py<br/>业务逻辑层]
|
||||
C[departments.py<br/>API路由层]
|
||||
D[schemas.py<br/>数据模式定义]
|
||||
end
|
||||
subgraph "前端界面"
|
||||
E[Departments.vue<br/>科室管理界面]
|
||||
end
|
||||
subgraph "数据库"
|
||||
F[departments表<br/>实际数据存储]
|
||||
G[idx_dept_type<br/>类型索引]
|
||||
H[idx_dept_parent<br/>父级索引]
|
||||
end
|
||||
A --> B
|
||||
B --> C
|
||||
C --> E
|
||||
A --> F
|
||||
F --> G
|
||||
F --> H
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [models.py](file://backend/app/models/models.py#L62-L85)
|
||||
- [department_service.py](file://backend/app/services/department_service.py#L13-L150)
|
||||
- [departments.py](file://backend/app/api/v1/departments.py#L1-L108)
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L62-L85)
|
||||
- [department_service.py](file://backend/app/services/department_service.py#L13-L150)
|
||||
- [departments.py](file://backend/app/api/v1/departments.py#L1-L108)
|
||||
|
||||
## 核心组件
|
||||
|
||||
### 数据模型定义
|
||||
|
||||
科室信息表采用SQLAlchemy ORM映射，定义了完整的字段结构和约束条件：
|
||||
|
||||
| 字段名 | 类型 | 约束 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| id | Integer | 主键, 自增 | 科室唯一标识符 |
|
||||
| name | String(100) | 非空 | 科室名称 |
|
||||
| code | String(20) | 唯一, 非空 | 科室编码，全局唯一 |
|
||||
| dept_type | Enum | 非空 | 科室类型枚举 |
|
||||
| parent_id | Integer | 外键 | 上级科室ID，自关联 |
|
||||
| level | Integer | 默认1 | 层级深度，从1开始 |
|
||||
| sort_order | Integer | 默认0 | 排序权重 |
|
||||
| is_active | Boolean | 默认True | 是否启用状态 |
|
||||
| description | Text | 可空 | 科室描述信息 |
|
||||
| created_at | DateTime | 默认当前时间 | 创建时间戳 |
|
||||
| updated_at | DateTime | 默认当前时间 | 更新时间戳 |
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L62-L85)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L23-L40)
|
||||
|
||||
### 科室类型枚举
|
||||
|
||||
系统定义了9种科室类型，每种类型都有明确的业务含义：
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[科室类型枚举] --> B[临床科室]
|
||||
A --> C[医技科室]
|
||||
A --> D[医辅科室]
|
||||
A --> E[护理单元]
|
||||
A --> F[行政科室]
|
||||
A --> G[财务科室]
|
||||
A --> H[后勤保障科室]
|
||||
B --> B1[手术临床科室]
|
||||
B --> B2[非手术有病房科室]
|
||||
B --> B3[非手术无病房科室]
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [models.py](file://backend/app/models/models.py#L16-L26)
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L16-L26)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L12-L22)
|
||||
|
||||
## 架构概览
|
||||
|
||||
科室信息表的完整架构包括数据模型、业务逻辑、API接口和前端界面四个层次：
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant UI as 前端界面
|
||||
participant API as API层
|
||||
participant Service as 业务服务层
|
||||
participant Model as 数据模型层
|
||||
participant DB as 数据库
|
||||
UI->>API : GET /departments/tree
|
||||
API->>Service : get_tree()
|
||||
Service->>Model : 查询所有科室
|
||||
Model->>DB : SELECT * FROM departments
|
||||
DB-->>Model : 科室数据
|
||||
Model-->>Service : Department对象列表
|
||||
Service->>Service : 构建树形结构
|
||||
Service-->>API : DepartmentTree列表
|
||||
API-->>UI : 树形数据
|
||||
Note over UI,DB : 树形结构构建过程
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [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#L1-L108)
|
||||
- [department_service.py](file://backend/app/services/department_service.py#L113-L149)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 数据模型类分析
|
||||
|
||||
```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
|
||||
+Department parent
|
||||
+Staff[] staff
|
||||
}
|
||||
class DeptType {
|
||||
<<enumeration>>
|
||||
+CLINICAL_SURGICAL
|
||||
+CLINICAL_NONSURGICAL_WARD
|
||||
+CLINICAL_NONSURGICAL_NOWARD
|
||||
+MEDICAL_TECH
|
||||
+MEDICAL_AUXILIARY
|
||||
+NURSING
|
||||
+ADMIN
|
||||
+FINANCE
|
||||
+LOGISTICS
|
||||
}
|
||||
class DepartmentService {
|
||||
+get_list() Department[]
|
||||
+get_by_id(int) Department
|
||||
+get_by_code(string) Department
|
||||
+create(DepartmentCreate) Department
|
||||
+update(int, DepartmentUpdate) Department
|
||||
+delete(int) bool
|
||||
+get_tree() DepartmentTree[]
|
||||
}
|
||||
Department --> DeptType : 使用
|
||||
DepartmentService --> Department : 操作
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [models.py](file://backend/app/models/models.py#L62-L85)
|
||||
- [models.py](file://backend/app/models/models.py#L16-L26)
|
||||
- [department_service.py](file://backend/app/services/department_service.py#L13-L150)
|
||||
|
||||
### 树形结构实现机制
|
||||
|
||||
系统通过自关联外键实现树形结构，核心实现逻辑如下：
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[获取所有科室] --> B[创建ID映射表]
|
||||
B --> C[初始化树节点]
|
||||
C --> D[遍历所有科室]
|
||||
D --> E{是否存在父节点?}
|
||||
E --> |是| F[添加到父节点children]
|
||||
E --> |否| G[添加到根节点列表]
|
||||
F --> H[继续下一个科室]
|
||||
G --> H
|
||||
H --> I[返回根节点列表]
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [department_service.py](file://backend/app/services/department_service.py#L124-L149)
|
||||
|
||||
**章节来源**
|
||||
- [department_service.py](file://backend/app/services/department_service.py#L113-L149)
|
||||
|
||||
### 层级计算机制
|
||||
|
||||
层级计算采用递归继承的方式，确保树形结构的完整性：
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[创建新科室] --> B[检查parent_id是否存在]
|
||||
B --> |存在| C[查询父科室]
|
||||
C --> D[level = parent.level + 1]
|
||||
B --> |不存在| E[level = 1]
|
||||
D --> F[保存科室记录]
|
||||
E --> F
|
||||
F --> G[返回新科室]
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [department_service.py](file://backend/app/services/department_service.py#L62-L78)
|
||||
|
||||
**章节来源**
|
||||
- [department_service.py](file://backend/app/services/department_service.py#L62-L78)
|
||||
|
||||
### API接口设计
|
||||
|
||||
系统提供了完整的CRUD接口，支持多种查询和操作场景：
|
||||
|
||||
| 接口 | 方法 | 路径 | 功能描述 |
|
||||
|------|------|------|----------|
|
||||
| 获取科室列表 | GET | /departments | 分页获取科室列表，支持过滤和排序 |
|
||||
| 获取科室树 | GET | /departments/tree | 获取完整的树形结构 |
|
||||
| 获取科室详情 | GET | /departments/{id} | 根据ID获取科室详情 |
|
||||
| 创建科室 | POST | /departments | 创建新的科室记录 |
|
||||
| 更新科室 | PUT | /departments/{id} | 更新现有科室信息 |
|
||||
| 删除科室 | DELETE | /departments/{id} | 删除指定科室（带安全检查） |
|
||||
|
||||
**章节来源**
|
||||
- [departments.py](file://backend/app/api/v1/departments.py#L20-L107)
|
||||
- [api.md](file://docs/api.md#L80-L131)
|
||||
|
||||
### 前端集成实现
|
||||
|
||||
前端界面提供了完整的科室管理功能，包括：
|
||||
|
||||
- **数据展示**：表格形式展示科室基本信息
|
||||
- **树形选择**：使用el-tree-select实现上级科室选择
|
||||
- **类型标签**：不同科室类型显示不同颜色标签
|
||||
- **状态管理**：支持启用/停用状态切换
|
||||
- **权限控制**：仅管理员和经理可以进行CRUD操作
|
||||
|
||||
**章节来源**
|
||||
- [Departments.vue](file://frontend/src/views/basic/Departments.vue#L1-L290)
|
||||
|
||||
## 依赖关系分析
|
||||
|
||||
### 数据库索引设计
|
||||
|
||||
科室信息表采用了合理的索引策略来优化查询性能：
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
A[departments表] --> B[idx_dept_type]
|
||||
A --> C[idx_dept_parent]
|
||||
A --> D[idx_code_unique]
|
||||
B --> E[类型查询优化]
|
||||
C --> F[父子关系查询优化]
|
||||
D --> G[编码唯一性保证]
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [models.py](file://backend/app/models/models.py#L82-L85)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L39-L40)
|
||||
|
||||
### 外部依赖关系
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "外部依赖"
|
||||
A[SQLAlchemy ORM]
|
||||
B[FastAPI框架]
|
||||
C[Element UI]
|
||||
D[PostgreSQL数据库]
|
||||
end
|
||||
subgraph "内部模块"
|
||||
E[models.py]
|
||||
F[department_service.py]
|
||||
G[departments.py]
|
||||
H[schemas.py]
|
||||
end
|
||||
A --> E
|
||||
B --> G
|
||||
C --> I[Departments.vue]
|
||||
D --> E
|
||||
E --> F
|
||||
F --> G
|
||||
G --> I
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [models.py](file://backend/app/models/models.py#L1-L13)
|
||||
- [departments.py](file://backend/app/api/v1/departments.py#L4-L15)
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L1-L13)
|
||||
- [departments.py](file://backend/app/api/v1/departments.py#L4-L15)
|
||||
|
||||
## 性能考虑
|
||||
|
||||
### 查询优化策略
|
||||
|
||||
1. **索引优化**
|
||||
- `idx_dept_type`：优化按科室类型查询
|
||||
- `idx_dept_parent`：优化树形结构查询
|
||||
- `unique(code)`：确保编码唯一性，支持快速查找
|
||||
|
||||
2. **查询模式优化**
|
||||
- 使用`ORDER BY sort_order, id`确保稳定排序
|
||||
- 分页查询避免一次性加载大量数据
|
||||
- 树形结构构建时使用内存映射减少数据库访问
|
||||
|
||||
3. **缓存策略**
|
||||
- 树形结构结果可以考虑缓存
|
||||
- 常用查询结果可以使用Redis缓存
|
||||
|
||||
### 数据一致性保证
|
||||
|
||||
- **事务处理**：所有CRUD操作都在事务中执行
|
||||
- **约束检查**：删除操作前检查是否有子科室
|
||||
- **并发控制**：使用数据库锁防止并发冲突
|
||||
|
||||
## 故障排除指南
|
||||
|
||||
### 常见问题及解决方案
|
||||
|
||||
1. **科室编码重复**
|
||||
- 现象：创建科室时报错"科室编码已存在"
|
||||
- 解决：检查是否存在重复的编码，确保唯一性
|
||||
|
||||
2. **树形结构异常**
|
||||
- 现象：科室树显示不正确或出现循环引用
|
||||
- 解决：检查parent_id字段，确保没有自引用或循环引用
|
||||
|
||||
3. **删除失败**
|
||||
- 现象：删除科室时报错"无法删除，科室下存在子科室"
|
||||
- 解决：先删除子科室，再删除父科室
|
||||
|
||||
4. **层级计算错误**
|
||||
- 现象：新创建科室层级不正确
|
||||
- 解决：检查父科室是否存在，确保正确计算level
|
||||
|
||||
**章节来源**
|
||||
- [departments.py](file://backend/app/api/v1/departments.py#L74-L77)
|
||||
- [department_service.py](file://backend/app/services/department_service.py#L96-L110)
|
||||
|
||||
### 调试技巧
|
||||
|
||||
1. **数据库层面调试**
|
||||
```sql
|
||||
-- 查看所有科室及其层级关系
|
||||
SELECT id, name, code, parent_id, level FROM departments ORDER BY level, sort_order;
|
||||
|
||||
-- 检查树形结构完整性
|
||||
SELECT parent_id, COUNT(*) as child_count
|
||||
FROM departments
|
||||
GROUP BY parent_id
|
||||
HAVING parent_id IS NOT NULL;
|
||||
```
|
||||
|
||||
2. **API层面调试**
|
||||
- 使用Postman测试各种接口
|
||||
- 检查响应状态码和错误信息
|
||||
- 验证数据格式和约束条件
|
||||
|
||||
## 结论
|
||||
|
||||
科室信息表作为医院绩效管理系统的基础数据表，具有以下特点：
|
||||
|
||||
1. **完整的树形结构**：支持多层级的科室组织关系
|
||||
2. **灵活的类型管理**：涵盖医院各类科室类型
|
||||
3. **完善的权限控制**：基于角色的CRUD权限管理
|
||||
4. **良好的扩展性**：为后续功能扩展提供基础支撑
|
||||
|
||||
通过合理的设计和实现，该表能够有效支撑医院的绩效管理、员工管理、财务核算等多个业务领域，为医院的数字化转型提供坚实的数据基础。
|
||||
299
.qoder/repowiki/zh/content/数据库设计/表结构设计/核心业务表/考核指标表.md
Normal file
299
.qoder/repowiki/zh/content/数据库设计/表结构设计/核心业务表/考核指标表.md
Normal file
@@ -0,0 +1,299 @@
|
||||
# 考核指标表
|
||||
|
||||
<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)
|
||||
- [init_indicator_templates.py](file://backend/init_indicator_templates.py)
|
||||
- [Indicators.vue](file://frontend/src/views/basic/Indicators.vue)
|
||||
- [详细设计.md](file://docs/详细设计.md)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考量](#性能考量)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
本文件围绕“考核指标表（indicators）”进行系统化说明，涵盖字段的业务含义、指标类型与平衡计分卡维度的枚举值、权重约束与一票否决机制的设计原理，并结合系统中的模板初始化与前后端交互，给出典型配置场景与使用示例。
|
||||
|
||||
## 项目结构
|
||||
- 后端采用 FastAPI + SQLAlchemy 异步 ORM，指标模型、序列化与 API 路由分别位于 models、schemas、api/v1 与 services 层。
|
||||
- 前端 Vue 页面负责指标的增删改查与状态切换。
|
||||
- 初始化脚本用于批量导入模板指标，便于快速搭建不同科室的指标库。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
FE["前端页面<br/>Indicators.vue"] --> API["API 路由<br/>indicators.py"]
|
||||
API --> SVC["服务层<br/>indicator_service.py"]
|
||||
SVC --> MODEL["数据模型<br/>models.py"]
|
||||
INIT["初始化脚本<br/>init_indicator_templates.py"] --> MODEL
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [Indicators.vue](file://frontend/src/views/basic/Indicators.vue#L1-L296)
|
||||
- [indicators.py](file://backend/app/api/v1/indicators.py#L1-L142)
|
||||
- [indicator_service.py](file://backend/app/services/indicator_service.py#L1-L197)
|
||||
- [models.py](file://backend/app/models/models.py#L117-L147)
|
||||
- [init_indicator_templates.py](file://backend/init_indicator_templates.py#L1-L375)
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L117-L147)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L151-L193)
|
||||
- [indicators.py](file://backend/app/api/v1/indicators.py#L1-L142)
|
||||
- [indicator_service.py](file://backend/app/services/indicator_service.py#L1-L197)
|
||||
- [init_indicator_templates.py](file://backend/init_indicator_templates.py#L1-L375)
|
||||
- [Indicators.vue](file://frontend/src/views/basic/Indicators.vue#L1-L296)
|
||||
|
||||
## 核心组件
|
||||
- 模型层（数据模型）：定义指标表结构、枚举类型（指标类型、BSC 维度、科室类型）、约束与索引。
|
||||
- 序列化层（Pydantic）：定义指标的请求/响应模型与字段校验规则。
|
||||
- 服务层（业务逻辑）：提供指标列表查询、启用状态筛选、创建/更新/删除、模板导入等能力。
|
||||
- API 层（接口）：暴露指标 CRUD 与模板导入接口，带权限控制。
|
||||
- 前端页面：提供指标列表展示、搜索过滤、新增/编辑/删除、状态开关等交互。
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L54-L61)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L39-L44)
|
||||
- [indicators.py](file://backend/app/api/v1/indicators.py#L20-L142)
|
||||
- [indicator_service.py](file://backend/app/services/indicator_service.py#L16-L197)
|
||||
- [Indicators.vue](file://frontend/src/views/basic/Indicators.vue#L17-L118)
|
||||
|
||||
## 架构总览
|
||||
以下类图展示指标相关的核心类与关系，以及与枚举类型的绑定。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class Indicator {
|
||||
+int id
|
||||
+string name
|
||||
+string code
|
||||
+IndicatorType indicator_type
|
||||
+BSCDimension bs_dimension
|
||||
+float weight
|
||||
+float max_score
|
||||
+float target_value
|
||||
+string target_unit
|
||||
+string calculation_method
|
||||
+string assessment_method
|
||||
+string deduction_standard
|
||||
+string data_source
|
||||
+string applicable_dept_types
|
||||
+bool is_veto
|
||||
+bool is_active
|
||||
+datetime created_at
|
||||
+datetime updated_at
|
||||
}
|
||||
class IndicatorType {
|
||||
<<enum>>
|
||||
+quality
|
||||
+quantity
|
||||
+efficiency
|
||||
+service
|
||||
+cost
|
||||
}
|
||||
class BSCDimension {
|
||||
<<enum>>
|
||||
+financial
|
||||
+customer
|
||||
+internal_process
|
||||
+learning_growth
|
||||
}
|
||||
class DeptType {
|
||||
<<enum>>
|
||||
+clinical_surgical
|
||||
+clinical_nonsurgical_ward
|
||||
+clinical_nonsurgical_noward
|
||||
+medical_tech
|
||||
+medical_auxiliary
|
||||
+nursing
|
||||
+admin
|
||||
+finance
|
||||
+logistics
|
||||
}
|
||||
Indicator --> IndicatorType : "使用"
|
||||
Indicator --> BSCDimension : "使用"
|
||||
Indicator --> DeptType : "适用科室类型(JSON)"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [models.py](file://backend/app/models/models.py#L54-L61)
|
||||
- [models.py](file://backend/app/models/models.py#L117-L147)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 字段业务含义与约束
|
||||
- 指标编码（code）：唯一标识指标，用于模板导入与关联，API 层在创建时会校验唯一性。
|
||||
- 指标名称（name）：指标的中文名称，用于展示与报表。
|
||||
- 指标类型（indicator_type）：质量、数量、效率、服务、成本五类，决定评分方法与目标方向。
|
||||
- 平衡计分卡维度（bs_dimension）：财务、客户、内部流程、学习与成长四个维度，用于归类与权重分配。
|
||||
- 权重（weight）：指标在所属维度内的权重，模型层包含正数约束；服务层与前端对权重范围做了进一步限制。
|
||||
- 最高分值（max_score）：指标可能获得的最高得分，用于评分换算与上限控制。
|
||||
- 目标值（target_value）与单位（target_unit）：目标值及其单位，配合评分方法使用。
|
||||
- 计算方法（calculation_method）：实际值的计算公式或口径说明。
|
||||
- 考核方法（assessment_method）：数据采集与认定方式（如统计报表、问卷调查、系统统计等）。
|
||||
- 扣分标准（deduction_standard）：针对扣分法的扣分细则，便于人工复核与申诉处理。
|
||||
- 数据来源（data_source）：数据来自哪个系统或部门，确保可追溯。
|
||||
- 适用科室类型（applicable_dept_types）：JSON 数组，限定该指标对哪些科室生效。
|
||||
- 是否一票否决（is_veto）：当指标为否决项时，若未达标直接判定考核不通过。
|
||||
- 启用状态（is_active）：控制指标是否参与当前周期的考核。
|
||||
- 创建/更新时间（created_at/updated_at）：审计与版本追踪。
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L117-L147)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L153-L193)
|
||||
- [indicators.py](file://backend/app/api/v1/indicators.py#L71-L112)
|
||||
- [indicator_service.py](file://backend/app/services/indicator_service.py#L106-L154)
|
||||
|
||||
### 指标类型与平衡计分卡维度
|
||||
- 指标类型（质量、数量、效率、服务、成本）：用于区分指标性质与评分方法选择。
|
||||
- BSC 四个维度：
|
||||
- 财务维度：关注收入、成本、结余等财务指标。
|
||||
- 客户维度：关注患者满意度、投诉处理等客户服务指标。
|
||||
- 内部流程维度：关注病历质量、院感控制、制度执行等内部运营指标。
|
||||
- 学习与成长维度：关注培训参与、继续教育等能力建设指标。
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L54-L61)
|
||||
- [models.py](file://backend/app/models/models.py#L29-L34)
|
||||
|
||||
### 权重约束与一票否决机制
|
||||
- 权重约束：
|
||||
- 数据库层：通过约束保证权重大于 0。
|
||||
- 服务层与前端：对权重范围做了更严格的限制（如前端最小 0.1、最大 10），避免极端权重影响整体平衡。
|
||||
- 一票否决（is_veto）：
|
||||
- 当某指标被标记为否决项时，若未达到目标，直接判定该考核记录不通过，无需计算其他指标得分。
|
||||
- 该机制常用于安全、合规类关键指标（如院感控制达标率）。
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L144-L146)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L158-L158)
|
||||
- [init_indicator_templates.py](file://backend/init_indicator_templates.py#L180-L196)
|
||||
|
||||
### API 流程与调用链
|
||||
以下序列图展示从前端到后端的关键调用链，包括创建指标与模板导入。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant FE as "前端页面<br/>Indicators.vue"
|
||||
participant API as "API 路由<br/>indicators.py"
|
||||
participant SVC as "服务层<br/>indicator_service.py"
|
||||
participant DB as "数据库"
|
||||
FE->>API : "POST /api/v1/indicators"
|
||||
API->>API : "校验权限与编码唯一性"
|
||||
API->>SVC : "create(indicator_data)"
|
||||
SVC->>DB : "插入新指标记录"
|
||||
DB-->>SVC : "返回持久化后的指标"
|
||||
SVC-->>API : "返回指标对象"
|
||||
API-->>FE : "返回创建成功与数据"
|
||||
FE->>API : "POST /api/v1/indicators/templates/import?overwrite=false"
|
||||
API->>SVC : "import_template(template_data, overwrite)"
|
||||
SVC->>DB : "按模板创建/更新指标"
|
||||
DB-->>SVC : "提交事务"
|
||||
SVC-->>API : "返回创建数量"
|
||||
API-->>FE : "返回导入结果"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [Indicators.vue](file://frontend/src/views/basic/Indicators.vue#L201-L273)
|
||||
- [indicators.py](file://backend/app/api/v1/indicators.py#L71-L142)
|
||||
- [indicator_service.py](file://backend/app/services/indicator_service.py#L67-L154)
|
||||
|
||||
### 典型配置场景与使用示例
|
||||
- 场景一：为“临床手术科室”批量导入模板指标
|
||||
- 使用模板导入接口，传入模板数据与科室类型，系统将根据模板生成指标并设置适用科室类型。
|
||||
- 示例字段：指标编码、名称、类型、维度、权重、最高分值、目标值、计算方法、数据来源、是否否决等。
|
||||
- 场景二：新增自定义指标
|
||||
- 前端填写指标基本信息，后端校验编码唯一性与字段合法性，创建后可在考核中启用。
|
||||
- 场景三：启用/停用指标
|
||||
- 前端通过开关切换 is_active，后端提供按状态筛选的列表查询接口。
|
||||
- 场景四：否决项设置
|
||||
- 对关键安全/合规指标（如院感达标率）设置 is_veto=true，确保未达标即不通过。
|
||||
|
||||
章节来源
|
||||
- [indicators.py](file://backend/app/api/v1/indicators.py#L20-L142)
|
||||
- [indicator_service.py](file://backend/app/services/indicator_service.py#L106-L197)
|
||||
- [init_indicator_templates.py](file://backend/init_indicator_templates.py#L22-L375)
|
||||
- [Indicators.vue](file://frontend/src/views/basic/Indicators.vue#L179-L273)
|
||||
|
||||
### 评分方法与权重换算（概念流程）
|
||||
系统提供了多种评分方法，用于将实际值转换为得分。以下流程图展示常见方法的决策过程（概念示意）：
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["开始"]) --> CheckVeto{"是否为否决项<br/>is_veto = true?"}
|
||||
CheckVeto --> |是| Vetofail["未达标则直接不通过"]
|
||||
CheckVeto --> |否| ChooseMethod["选择评分方法"]
|
||||
ChooseMethod --> Ratio["比值法<br/>实际值/目标值"]
|
||||
ChooseMethod --> Range["区间法<br/>趋高/趋低/趋中"]
|
||||
ChooseMethod --> Deduct["扣分法<br/>权重-扣分"]
|
||||
ChooseMethod --> Bonus["加分法<br/>权重+加分"]
|
||||
Ratio --> WeightCalc["乘以权重得到得分"]
|
||||
Range --> WeightCalc
|
||||
Deduct --> CapZero["扣完为止，不低于0"]
|
||||
Bonus --> CapMax["加分不超过权重50%"]
|
||||
WeightCalc --> End(["结束"])
|
||||
CapZero --> End
|
||||
CapMax --> End
|
||||
Vetofail --> End
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [详细设计.md](file://docs/详细设计.md#L328-L400)
|
||||
|
||||
## 依赖关系分析
|
||||
- 模型层依赖枚举类型（IndicatorType、BSCDimension、DeptType）与 SQLAlchemy 的类型系统。
|
||||
- 服务层依赖模型层进行数据库操作，并对输入数据进行清洗与转换（如适用科室类型 JSON 序列化）。
|
||||
- API 层依赖服务层与权限中间件，提供统一的 HTTP 接口。
|
||||
- 前端依赖 API 提供的数据结构，进行表格展示与表单编辑。
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
ENUM["枚举类型<br/>IndicatorType/BSCDimension/DeptType"] --> MODEL["数据模型<br/>models.py"]
|
||||
MODEL --> SVC["服务层<br/>indicator_service.py"]
|
||||
SVC --> API["API 路由<br/>indicators.py"]
|
||||
API --> FE["前端页面<br/>Indicators.vue"]
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [models.py](file://backend/app/models/models.py#L54-L61)
|
||||
- [models.py](file://backend/app/models/models.py#L117-L147)
|
||||
- [indicator_service.py](file://backend/app/services/indicator_service.py#L1-L197)
|
||||
- [indicators.py](file://backend/app/api/v1/indicators.py#L1-L142)
|
||||
- [Indicators.vue](file://frontend/src/views/basic/Indicators.vue#L1-L296)
|
||||
|
||||
## 性能考量
|
||||
- 查询性能：指标列表接口支持按类型、维度、启用状态筛选与分页，建议在高频查询场景下利用数据库索引（模型层已定义相关索引）。
|
||||
- 写入性能：模板导入采用批量写入与事务提交，减少往返开销；注意在大量导入时控制并发与内存占用。
|
||||
- 前端渲染：表格分页与按需加载有助于提升大列表的交互体验。
|
||||
|
||||
## 故障排查指南
|
||||
- 编码重复：创建指标时若编码已存在，接口会返回错误；请更换唯一编码。
|
||||
- 权重异常：若权重小于等于 0 或超出范围，数据库约束或前端校验会拦截；请调整至有效范围。
|
||||
- 否决项判定：若某指标为否决项且未达标，需先满足该指标目标再进入后续评分。
|
||||
- 数据来源缺失：若数据源不可用，建议在计算方法与数据来源字段中明确口径与系统对接方式。
|
||||
|
||||
章节来源
|
||||
- [indicators.py](file://backend/app/api/v1/indicators.py#L78-L84)
|
||||
- [models.py](file://backend/app/models/models.py#L144-L146)
|
||||
- [init_indicator_templates.py](file://backend/init_indicator_templates.py#L180-L196)
|
||||
|
||||
## 结论
|
||||
考核指标表是医院绩效管理的基础配置单元。通过明确的字段语义、严谨的权重约束与一票否决机制，系统能够支撑多维度、多科室的差异化考核需求。结合模板导入与前后端协同，可高效完成指标库的构建与维护。
|
||||
|
||||
## 附录
|
||||
- 初始化脚本示例：展示了如何为不同科室批量创建指标模板，便于快速落地。
|
||||
- 前端页面示例：展示了指标的增删改查与状态切换，便于一线人员日常维护。
|
||||
|
||||
章节来源
|
||||
- [init_indicator_templates.py](file://backend/init_indicator_templates.py#L22-L375)
|
||||
- [Indicators.vue](file://frontend/src/views/basic/Indicators.vue#L179-L273)
|
||||
351
.qoder/repowiki/zh/content/数据库设计/表结构设计/核心业务表/考核明细表.md
Normal file
351
.qoder/repowiki/zh/content/数据库设计/表结构设计/核心业务表/考核明细表.md
Normal file
@@ -0,0 +1,351 @@
|
||||
# 考核明细表
|
||||
|
||||
<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)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py)
|
||||
- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue)
|
||||
- [assessment.js](file://frontend/src/api/assessment.js)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构概览](#架构概览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考量](#性能考量)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
本文件围绕“考核明细表（assessment_details）”进行系统化说明，涵盖字段业务含义、与考核记录表（assessments）的多对一关系、与指标表（indicators）的一对一关系、得分计算逻辑、数据验证规则、典型使用场景以及索引与查询优化建议。文档同时结合后端模型定义、服务层实现、API接口与前端交互，帮助读者全面理解该表在医院绩效系统中的作用与实现细节。
|
||||
|
||||
## 项目结构
|
||||
- 后端模型定义位于 models.py，包含 AssessmentDetail 的字段、索引与关系。
|
||||
- 服务层 assessment_service.py 实现了明细的增删改查、加权得分计算与批量初始化。
|
||||
- API 层 assessments.py 提供考核与明细的对外接口。
|
||||
- 数据库迁移脚本 001_initial.py 定义了 assessment_details 的建表语句与索引。
|
||||
- 前端 AssessmentDetail.vue 与 assessment.js 展示了明细的录入、校验与提交流程。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "后端"
|
||||
M["models.py<br/>定义 AssessmentDetail 字段/索引/关系"]
|
||||
S["assessment_service.py<br/>明细增删改/加权计算/批量初始化"]
|
||||
A["assessments.py<br/>API 接口"]
|
||||
end
|
||||
subgraph "前端"
|
||||
V["AssessmentDetail.vue<br/>明细展示/编辑/提交"]
|
||||
JS["assessment.js<br/>HTTP 请求封装"]
|
||||
end
|
||||
DB["数据库<br/>assessment_details 表"]
|
||||
V --> JS
|
||||
JS --> A
|
||||
A --> S
|
||||
S --> M
|
||||
M --> DB
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [models.py](file://backend/app/models/models.py#L181-L202)
|
||||
- [assessment_service.py](file://backend/app/services/assessment_service.py#L70-L108)
|
||||
- [assessments.py](file://backend/app/api/v1/assessments.py#L55-L77)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L114-L131)
|
||||
- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L36-L82)
|
||||
- [assessment.js](file://frontend/src/api/assessment.js#L8-L36)
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L181-L202)
|
||||
- [assessment_service.py](file://backend/app/services/assessment_service.py#L70-L108)
|
||||
- [assessments.py](file://backend/app/api/v1/assessments.py#L55-L77)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L114-L131)
|
||||
- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L36-L82)
|
||||
- [assessment.js](file://frontend/src/api/assessment.js#L8-L36)
|
||||
|
||||
## 核心组件
|
||||
- 考核明细表（AssessmentDetail）
|
||||
- 字段与业务含义：
|
||||
- assessment_id：考核记录ID，用于将明细归集到具体考核记录，形成“明细-记录”的多对一关系。
|
||||
- indicator_id：指标ID，用于将明细与具体指标绑定，形成“明细-指标”的一对一关系。
|
||||
- actual_value：实际值，记录该指标的实际测量结果，支持小数点后两位精度。
|
||||
- score：得分，记录该指标的最终得分，支持小数点后一位精度，默认为0。
|
||||
- evidence：佐证材料，记录支撑该得分的相关证明材料（如截图、报表链接、文件名等）。
|
||||
- remark：备注，用于记录审核意见、补充说明等。
|
||||
- 索引与约束：
|
||||
- idx_detail_assessment：assessment_id 上的索引，加速按考核记录查询明细。
|
||||
- idx_detail_indicator：indicator_id 上的索引，加速按指标查询明细。
|
||||
- 关系：
|
||||
- 与 Assessment 多对一：每个明细属于一个考核记录。
|
||||
- 与 Indicator 一对一：每个明细对应一个指标。
|
||||
|
||||
- 考核记录表（Assessment）
|
||||
- 与 AssessmentDetail 的一对多关系：一个考核记录包含多个明细项。
|
||||
- 总分与加权得分由服务层在创建/更新时计算并写入。
|
||||
|
||||
- 指标表（Indicator）
|
||||
- 与 AssessmentDetail 的一对多关系：一个指标可出现在多个明细中（不同考核记录）。
|
||||
- 服务层在计算加权得分时会读取指标权重。
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L181-L202)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L114-L131)
|
||||
|
||||
## 架构概览
|
||||
后端采用“模型-服务-接口-前端”分层架构：
|
||||
- 模型层：定义 AssessmentDetail 的字段、索引与关系。
|
||||
- 服务层：负责明细的创建/更新、删除旧明细、计算总分与加权得分、批量初始化。
|
||||
- 接口层：提供获取详情、创建、更新、提交、审核、确认等 API。
|
||||
- 前端：展示明细、允许编辑实际值与得分、提交审核、审核通过/驳回、确认。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant FE as "前端页面"
|
||||
participant API as "API 接口"
|
||||
participant SVC as "服务层"
|
||||
participant DB as "数据库"
|
||||
FE->>API : GET /assessments/{id}
|
||||
API->>SVC : get_by_id(assessment_id)
|
||||
SVC->>DB : 查询 Assessment + selectinload details + indicator
|
||||
DB-->>SVC : 返回 Assessment 及明细
|
||||
SVC-->>API : Assessment 对象
|
||||
API-->>FE : 返回详情含明细
|
||||
FE->>API : PUT /assessments/{id}更新明细
|
||||
API->>SVC : update(assessment_id, details)
|
||||
SVC->>DB : 删除旧明细按 assessment_id
|
||||
SVC->>DB : 插入新明细并计算总分/加权得分
|
||||
DB-->>SVC : 提交事务
|
||||
SVC-->>API : 返回更新后的 Assessment
|
||||
API-->>FE : 返回成功
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [assessments.py](file://backend/app/api/v1/assessments.py#L55-L77)
|
||||
- [assessment_service.py](file://backend/app/services/assessment_service.py#L57-L156)
|
||||
- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L160-L175)
|
||||
|
||||
章节来源
|
||||
- [assessments.py](file://backend/app/api/v1/assessments.py#L55-L77)
|
||||
- [assessment_service.py](file://backend/app/services/assessment_service.py#L57-L156)
|
||||
- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L160-L175)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 字段业务含义与约束
|
||||
- assessment_id
|
||||
- 类型：整数，外键指向 assessments.id。
|
||||
- 业务含义：标识该明细所属的考核记录，形成“明细-记录”的多对一关系。
|
||||
- 约束：非空；需与现有考核记录关联。
|
||||
- indicator_id
|
||||
- 类型：整数，外键指向 indicators.id。
|
||||
- 业务含义：标识该明细对应的指标，形成“明细-指标”的一对一关系。
|
||||
- 约束：非空；需与现有指标关联。
|
||||
- actual_value
|
||||
- 类型：数值（最多10位，小数点后2位），可为空。
|
||||
- 业务含义：该指标的实际测量值，用于支撑评分或作为输入数据。
|
||||
- 约束：可为空；服务层不强制必填。
|
||||
- score
|
||||
- 类型：数值（最多5位，小数点后1位），默认0。
|
||||
- 业务含义：该指标的最终得分，用于计算总分与加权得分。
|
||||
- 约束：非负；服务层在更新时会累加总分，并按指标权重计算加权得分。
|
||||
- evidence
|
||||
- 类型：文本，可为空。
|
||||
- 业务含义：佐证材料，如图片、文件名、链接等，便于审计与复核。
|
||||
- 约束：可为空。
|
||||
- remark
|
||||
- 类型：文本，可为空。
|
||||
- 业务含义：备注，可用于记录审核意见、调整说明等。
|
||||
- 约束：可为空。
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L181-L202)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L196-L218)
|
||||
|
||||
### 关系与数据一致性
|
||||
- 与 Assessment 的多对一关系
|
||||
- 一个考核记录可包含多个明细；删除考核记录时，明细通过级联删除（由 Assessment 的 cascade 配置决定）。
|
||||
- 与 Indicator 的一对一关系
|
||||
- 一个指标可在多个明细中出现（不同考核记录），但单条明细仅对应一个指标。
|
||||
- 服务层在创建/更新时的处理
|
||||
- 创建：直接插入明细，总分=sum(score)，加权得分=Σ(score × 指标权重)。
|
||||
- 更新：先删除旧明细，再插入新明细，重新计算总分与加权得分。
|
||||
- 批量初始化：为某个科室的每位在职员工生成相同指标集合的明细，初始得分为0。
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L173-L173)
|
||||
- [assessment_service.py](file://backend/app/services/assessment_service.py#L70-L108)
|
||||
- [assessment_service.py](file://backend/app/services/assessment_service.py#L110-L156)
|
||||
- [assessment_service.py](file://backend/app/services/assessment_service.py#L207-L262)
|
||||
|
||||
### 得分计算逻辑
|
||||
- 总分（Assessment.total_score）
|
||||
- 计算方式：明细的 score 之和。
|
||||
- 加权得分（Assessment.weighted_score）
|
||||
- 计算方式：Σ(detail.score × detail.indicator.weight)。
|
||||
- 服务层在创建/更新时读取指标权重并累加。
|
||||
- 一票否决（Indicator.is_veto）
|
||||
- 该字段存在于指标表，用于表示是否为一票否决指标。若存在此类指标且其得分导致不达标，可能触发整体否决流程（具体逻辑取决于业务规则与前端/服务层实现）。当前明细表未直接存储 is_veto，但服务层在计算加权得分时会读取指标权重，体现权重影响。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["开始"]) --> LoadDetails["加载明细列表"]
|
||||
LoadDetails --> SumScore["sum(score) 计算总分"]
|
||||
SumScore --> GetWeights["逐条读取指标权重"]
|
||||
GetWeights --> WeightedCalc["Σ(score × 指标权重) 计算加权得分"]
|
||||
WeightedCalc --> SaveAssessment["保存 Assessment.total_score 与 weighted_score"]
|
||||
SaveAssessment --> 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#L70-L108)
|
||||
- [assessment_service.py](file://backend/app/services/assessment_service.py#L110-L156)
|
||||
|
||||
### 数据验证规则
|
||||
- Pydantic 模式（后端）
|
||||
- AssessmentDetailCreate/AssessmentDetailResponse 中对字段进行了范围与类型约束：
|
||||
- score：默认0，最小≥0。
|
||||
- actual_value：可为空，数值类型。
|
||||
- evidence/remark：可为空，字符串类型。
|
||||
- SQL 约束（数据库）
|
||||
- 字段类型与精度：numeric(10,2)/numeric(5,2) 等，确保存储精度。
|
||||
- 非空约束：assessment_id、indicator_id 非空。
|
||||
- 索引：assessment_id、indicator_id 上的索引，提升查询性能。
|
||||
- 前端校验（前端）
|
||||
- 明细表格中对实际值与得分设置了输入范围与精度：
|
||||
- actual_value：数值，精度2位。
|
||||
- score：数值，最小0，最大为指标最高分，精度1位。
|
||||
- 状态控制：仅草稿状态下允许编辑明细，提交后只读显示。
|
||||
|
||||
章节来源
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L196-L218)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L114-L131)
|
||||
- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L45-L70)
|
||||
|
||||
### 典型使用场景
|
||||
- 详细评分
|
||||
- 在前端页面中，用户可编辑 actual_value 与 score，服务层据此计算总分与加权得分。
|
||||
- 证据管理
|
||||
- evidence 字段用于记录佐证材料，便于后续审计与复核。
|
||||
- 数据追溯
|
||||
- 通过 assessment_id 可快速定位某次考核的所有明细；通过 indicator_id 可查看某指标在不同考核记录中的表现。
|
||||
- 批量初始化
|
||||
- 服务层支持为某个科室的在职员工批量创建明细，初始得分为0，便于后续统一评分。
|
||||
|
||||
章节来源
|
||||
- [assessment_service.py](file://backend/app/services/assessment_service.py#L207-L262)
|
||||
- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L36-L82)
|
||||
|
||||
### API 与前端交互
|
||||
- 获取详情
|
||||
- API 返回 Assessment 及其明细，前端渲染明细表格并注入指标名称。
|
||||
- 更新明细
|
||||
- 前端提交包含 indicator_id、actual_value、score、evidence 的数组，服务层删除旧明细并插入新明细，重新计算总分与加权得分。
|
||||
- 提交/审核/确认
|
||||
- 前端调用提交、审核、确认接口，服务层更新状态并持久化。
|
||||
|
||||
章节来源
|
||||
- [assessments.py](file://backend/app/api/v1/assessments.py#L55-L77)
|
||||
- [assessment_service.py](file://backend/app/services/assessment_service.py#L110-L156)
|
||||
- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L160-L213)
|
||||
- [assessment.js](file://frontend/src/api/assessment.js#L8-L36)
|
||||
|
||||
## 依赖关系分析
|
||||
- AssessmentDetail 与 Assessment 的多对一
|
||||
- 通过 assessment_id 外键关联，Assessment.details 为反向关系。
|
||||
- AssessmentDetail 与 Indicator 的一对一
|
||||
- 通过 indicator_id 外键关联，Indicator.assessment_details 为反向关系。
|
||||
- 服务层依赖
|
||||
- 服务层在创建/更新时读取指标权重，计算加权得分；在批量初始化时遍历在职员工并为每个员工生成明细。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class Assessment {
|
||||
+int id
|
||||
+int staff_id
|
||||
+int period_year
|
||||
+int period_month
|
||||
+float total_score
|
||||
+float weighted_score
|
||||
+string status
|
||||
+AssessmentDetail[] details
|
||||
}
|
||||
class AssessmentDetail {
|
||||
+int id
|
||||
+int assessment_id
|
||||
+int indicator_id
|
||||
+float actual_value
|
||||
+float score
|
||||
+string evidence
|
||||
+string remark
|
||||
+Assessment assessment
|
||||
+Indicator indicator
|
||||
}
|
||||
class Indicator {
|
||||
+int id
|
||||
+string name
|
||||
+string code
|
||||
+float weight
|
||||
+AssessmentDetail[] assessment_details
|
||||
}
|
||||
Assessment "1" <-- "many" AssessmentDetail : "details"
|
||||
Indicator "1" <-- "many" AssessmentDetail : "assessment_details"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [models.py](file://backend/app/models/models.py#L149-L178)
|
||||
- [models.py](file://backend/app/models/models.py#L181-L202)
|
||||
- [models.py](file://backend/app/models/models.py#L117-L146)
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L149-L202)
|
||||
|
||||
## 性能考量
|
||||
- 索引设计
|
||||
- idx_detail_assessment：按 assessment_id 查询明细时使用，适合按考核记录聚合明细。
|
||||
- idx_detail_indicator：按指标查询明细时使用，适合按指标维度统计。
|
||||
- 查询优化建议
|
||||
- 按考核记录查询明细：优先使用 assessment_id 进行过滤与排序。
|
||||
- 按指标查询明细：优先使用 indicator_id 进行过滤与排序。
|
||||
- 分页与排序：结合数据库索引与分页参数，避免全表扫描。
|
||||
- 批量操作：批量创建/更新明细时，尽量减少往返次数，使用服务层提供的批量接口。
|
||||
- 大体量数据的性能考虑
|
||||
- 使用索引覆盖查询，避免隐式转换与函数包裹。
|
||||
- 对高频查询（如按年月/状态/科室）考虑复合索引或物化视图（视数据库能力而定）。
|
||||
- 控制单次明细数量，避免一次性加载过多明细导致内存压力。
|
||||
|
||||
章节来源
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L114-L131)
|
||||
- [assessment_service.py](file://backend/app/services/assessment_service.py#L207-L262)
|
||||
|
||||
## 故障排查指南
|
||||
- 常见问题
|
||||
- 无法提交/审核/确认：检查考核记录状态是否符合要求（草稿、已提交、已审核）。
|
||||
- 明细更新无效：确认前端处于草稿状态，且提交的数据包含完整的 indicator_id、actual_value、score、evidence。
|
||||
- 得分异常：检查指标权重是否正确，以及服务层是否正确读取并参与加权计算。
|
||||
- 排查步骤
|
||||
- 查看 API 返回的状态码与错误信息。
|
||||
- 检查数据库中 assessment_details 的 assessment_id 与 indicator_id 是否有效。
|
||||
- 核对前端传参与后端模式约束是否匹配。
|
||||
- 在服务层增加日志，打印明细集合与计算过程的关键变量。
|
||||
|
||||
章节来源
|
||||
- [assessments.py](file://backend/app/api/v1/assessments.py#L105-L145)
|
||||
- [assessment_service.py](file://backend/app/services/assessment_service.py#L110-L156)
|
||||
|
||||
## 结论
|
||||
考核明细表是连接“考核记录”与“指标”的桥梁，承担着记录实际值、得分与佐证材料的关键职责。通过明确的字段定义、严格的索引设计与服务层的加权计算逻辑，系统能够稳定地支持详细评分、证据管理与数据追溯等核心业务场景。对于大体量数据，建议结合索引与分页策略，持续优化查询路径，确保系统在高并发下的稳定性与性能。
|
||||
|
||||
## 附录
|
||||
- 建议的索引与查询模式
|
||||
- 按 assessment_id 查询明细：使用 idx_detail_assessment。
|
||||
- 按 indicator_id 查询明细：使用 idx_detail_indicator。
|
||||
- 按年月/状态/科室聚合：结合 assessments 表的索引与分页参数进行高效查询。
|
||||
597
.qoder/repowiki/zh/content/数据库设计/表结构设计/核心业务表/考核记录表.md
Normal file
597
.qoder/repowiki/zh/content/数据库设计/表结构设计/核心业务表/考核记录表.md
Normal file
@@ -0,0 +1,597 @@
|
||||
# 考核记录表
|
||||
|
||||
<cite>
|
||||
**本文档引用的文件**
|
||||
- [assessments.py](file://backend/app/api/v1/assessments.py)
|
||||
- [models.py](file://backend/app/models/models.py)
|
||||
- [assessment_service.py](file://backend/app/services/assessment_service.py)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py)
|
||||
- [assessment.js](file://frontend/src/api/assessment.js)
|
||||
- [Assessments.vue](file://frontend/src/views/assessment/Assessments.vue)
|
||||
- [database.md](file://docs/database.md)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py)
|
||||
- [security.py](file://backend/app/core/security.py)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构概览](#架构概览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考虑](#性能考虑)
|
||||
8. [故障排除指南](#故障排除指南)
|
||||
9. [结论](#结论)
|
||||
|
||||
## 简介
|
||||
|
||||
考核记录表(assessments)是医院绩效管理系统的核心数据表，用于存储员工的绩效考核信息。该表实现了完整的考核生命周期管理，包括考核创建、提交、审核、确认等流程，并支持多层级的权限控制和状态管理。
|
||||
|
||||
## 项目结构
|
||||
|
||||
考核记录表相关的代码分布在以下层次：
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "前端层"
|
||||
FE_API[assessment.js]
|
||||
FE_VIEW[Assessments.vue]
|
||||
end
|
||||
subgraph "后端层"
|
||||
API[assessments.py]
|
||||
SERVICE[assessment_service.py]
|
||||
MODELS[models.py]
|
||||
SCHEMAS[schemas.py]
|
||||
SECURITY[security.py]
|
||||
end
|
||||
subgraph "数据库层"
|
||||
DB[assessments表]
|
||||
DETAIL[assessment_details表]
|
||||
INDEX[idx_assessment_staff<br/>idx_assessment_period<br/>idx_assessment_status]
|
||||
end
|
||||
FE_API --> API
|
||||
FE_VIEW --> FE_API
|
||||
API --> SERVICE
|
||||
SERVICE --> MODELS
|
||||
MODELS --> DB
|
||||
DB --> DETAIL
|
||||
DB --> INDEX
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [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#L149-L178)
|
||||
|
||||
**章节来源**
|
||||
- [assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
|
||||
- [models.py](file://backend/app/models/models.py#L149-L178)
|
||||
|
||||
## 核心组件
|
||||
|
||||
### 数据模型定义
|
||||
|
||||
考核记录表采用SQLAlchemy ORM映射，定义了完整的字段结构和关系：
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
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 : AssessmentDetail[]
|
||||
}
|
||||
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 : Assessment[]
|
||||
+salary_records : SalaryRecord[]
|
||||
}
|
||||
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
|
||||
}
|
||||
Assessment --> Staff : "staff_id"
|
||||
Assessment --> Staff : "assessor_id"
|
||||
Assessment --> Staff : "reviewer_id"
|
||||
Assessment --> AssessmentDetail : "details"
|
||||
AssessmentDetail --> Indicator : "indicator_id"
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [models.py](file://backend/app/models/models.py#L149-L178)
|
||||
- [models.py](file://backend/app/models/models.py#L181-L202)
|
||||
|
||||
### 字段业务含义详解
|
||||
|
||||
#### 基础字段
|
||||
- **staff_id**: 员工ID，外键关联到员工表，标识被考核的员工
|
||||
- **period_year**: 考核年度，支持2020-2100年的范围
|
||||
- **period_month**: 考核月份，支持1-12的范围
|
||||
- **period_type**: 考核周期类型，默认为"monthly"(月度)，支持其他周期类型扩展
|
||||
|
||||
#### 绩效计算字段
|
||||
- **total_score**: 总分，所有考核指标得分的简单相加
|
||||
- **weighted_score**: 加权得分，根据指标权重计算的加权平均分
|
||||
|
||||
#### 状态管理字段
|
||||
- **status**: 考核状态，使用AssessmentStatus枚举管理
|
||||
- **assessor_id**: 考核人ID，负责创建和维护考核记录
|
||||
- **reviewer_id**: 审核人ID，负责审核和批准考核结果
|
||||
|
||||
#### 时间戳字段
|
||||
- **submit_time**: 提交时间，记录考核提交到审核阶段的时间
|
||||
- **review_time**: 审核时间，记录考核审核完成的时间
|
||||
|
||||
#### 备注字段
|
||||
- **remark**: 备注信息，用于记录审核意见或其他说明
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L149-L178)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L220-L270)
|
||||
|
||||
## 架构概览
|
||||
|
||||
考核记录表的完整架构包括API层、服务层、数据模型层和数据库层：
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as 前端客户端
|
||||
participant API as API路由层
|
||||
participant Service as 服务层
|
||||
participant DB as 数据库
|
||||
participant Model as 数据模型
|
||||
Client->>API : GET /assessments
|
||||
API->>Service : get_list()
|
||||
Service->>DB : 查询assessments表
|
||||
DB->>Model : 返回ORM对象
|
||||
Model->>Service : Assessment对象列表
|
||||
Service->>API : Assessment列表
|
||||
API->>Client : JSON响应
|
||||
Client->>API : POST /assessments/{id}/submit
|
||||
API->>Service : submit()
|
||||
Service->>DB : 更新状态为SUBMITTED
|
||||
DB->>Model : 返回更新后的Assessment
|
||||
Service->>API : Assessment对象
|
||||
API->>Client : 提交成功
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [assessments.py](file://backend/app/api/v1/assessments.py#L20-L52)
|
||||
- [assessment_service.py](file://backend/app/services/assessment_service.py#L18-L55)
|
||||
|
||||
**章节来源**
|
||||
- [assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
|
||||
- [assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 状态枚举和转换机制
|
||||
|
||||
考核状态枚举定义了完整的状态转换流程：
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> 草稿 : 创建考核
|
||||
草稿 --> 已提交 : 提交考核
|
||||
已提交 --> 已审核 : 审核通过
|
||||
已提交 --> 已驳回 : 审核驳回
|
||||
已审核 --> 已确认 : 确认考核
|
||||
已确认 --> [*]
|
||||
已驳回 --> 草稿 : 修改后重新提交
|
||||
```
|
||||
|
||||
**状态转换规则**：
|
||||
- 草稿状态只能由创建者修改，支持重新编辑
|
||||
- 已提交状态只能由审核人处理，不可直接修改
|
||||
- 已审核状态可以被确认，进入最终状态
|
||||
- 已驳回状态可以返回草稿状态进行修正
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L45-L52)
|
||||
- [assessment_service.py](file://backend/app/services/assessment_service.py#L158-L205)
|
||||
|
||||
### 自关联关系实现
|
||||
|
||||
考核记录表实现了复杂的自关联关系：
|
||||
|
||||
```mermaid
|
||||
erDiagram
|
||||
ASSESSMENTS {
|
||||
int id PK
|
||||
int staff_id FK
|
||||
int assessor_id FK
|
||||
int reviewer_id FK
|
||||
int period_year
|
||||
int period_month
|
||||
string period_type
|
||||
float total_score
|
||||
float weighted_score
|
||||
string status
|
||||
datetime submit_time
|
||||
datetime review_time
|
||||
text remark
|
||||
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
|
||||
decimal base_salary
|
||||
decimal performance_ratio
|
||||
string status
|
||||
datetime hire_date
|
||||
datetime created_at
|
||||
datetime updated_at
|
||||
}
|
||||
ASSESSMENTS ||--|| STAFF : "staff_id"
|
||||
ASSESSMENTS ||--|| STAFF : "assessor_id"
|
||||
ASSESSMENTS ||--|| STAFF : "reviewer_id"
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [models.py](file://backend/app/models/models.py#L149-L178)
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L169-L173)
|
||||
|
||||
### 权限控制和身份验证
|
||||
|
||||
系统实现了多层级的权限控制机制：
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([用户请求]) --> CheckAuth["验证用户身份"]
|
||||
CheckAuth --> CheckRole{"检查用户角色"}
|
||||
CheckRole --> |普通员工| CheckStatus{"检查考核状态"}
|
||||
CheckRole --> |管理员| AllowAdmin["允许所有操作"]
|
||||
CheckRole --> |经理| CheckManager{"检查操作类型"}
|
||||
CheckStatus --> |草稿状态| AllowEdit["允许编辑"]
|
||||
CheckStatus --> |已提交状态| DenyEdit["拒绝编辑"]
|
||||
CheckStatus --> |已审核状态| DenyEdit
|
||||
CheckManager --> |提交/审核| AllowManager["允许审核操作"]
|
||||
CheckManager --> |确认| AllowManager
|
||||
CheckManager --> |创建| DenyManager["拒绝创建"]
|
||||
AllowAdmin --> End([授权通过])
|
||||
AllowEdit --> End
|
||||
AllowManager --> End
|
||||
DenyEdit --> End
|
||||
DenyManager --> End
|
||||
```
|
||||
|
||||
**权限控制规则**：
|
||||
- 普通员工只能操作自己的草稿状态考核
|
||||
- 经理和管理员可以进行审核和确认操作
|
||||
- 不同状态下的操作权限严格限制
|
||||
|
||||
**章节来源**
|
||||
- [security.py](file://backend/app/core/security.py#L94-L109)
|
||||
- [assessments.py](file://backend/app/api/v1/assessments.py#L105-L145)
|
||||
|
||||
### 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#L20-L166)
|
||||
|
||||
### 前端集成和使用场景
|
||||
|
||||
前端提供了完整的用户界面和交互体验：
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
subgraph "前端界面"
|
||||
LIST[考核列表页面]
|
||||
DETAIL[考核详情页面]
|
||||
BATCH[批量创建弹窗]
|
||||
end
|
||||
subgraph "API调用"
|
||||
GET_LIST[getAssessments]
|
||||
GET_DETAIL[getAssessment]
|
||||
CREATE[createAssessment]
|
||||
UPDATE[updateAssessment]
|
||||
SUBMIT[submitAssessment]
|
||||
REVIEW[reviewAssessment]
|
||||
FINALIZE[finalizeAssessment]
|
||||
BATCH_CREATE[batchCreateAssessments]
|
||||
end
|
||||
LIST --> GET_LIST
|
||||
DETAIL --> GET_DETAIL
|
||||
LIST --> CREATE
|
||||
LIST --> UPDATE
|
||||
LIST --> SUBMIT
|
||||
LIST --> REVIEW
|
||||
LIST --> FINALIZE
|
||||
BATCH --> BATCH_CREATE
|
||||
```
|
||||
|
||||
**典型使用场景**：
|
||||
|
||||
1. **流程审批场景**：
|
||||
- 员工创建草稿考核
|
||||
- 直接提交到上级审核
|
||||
- 审核通过后自动进入确认阶段
|
||||
|
||||
2. **状态跟踪场景**：
|
||||
- 实时显示考核状态变化
|
||||
- 支持按状态筛选和排序
|
||||
- 提供状态变更历史记录
|
||||
|
||||
3. **数据统计场景**：
|
||||
- 按科室统计平均分
|
||||
- 按时间段分析趋势
|
||||
- 生成绩效报告和图表
|
||||
|
||||
**章节来源**
|
||||
- [Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L1-L311)
|
||||
- [assessment.js](file://frontend/src/api/assessment.js#L1-L50)
|
||||
|
||||
## 依赖关系分析
|
||||
|
||||
### 数据库依赖关系
|
||||
|
||||
```mermaid
|
||||
erDiagram
|
||||
DEPARTMENTS {
|
||||
int id PK
|
||||
string name
|
||||
string code UK
|
||||
string dept_type
|
||||
int parent_id FK
|
||||
int level
|
||||
int sort_order
|
||||
boolean is_active
|
||||
text description
|
||||
datetime created_at
|
||||
datetime updated_at
|
||||
}
|
||||
STAFF {
|
||||
int id PK
|
||||
string employee_id UK
|
||||
string name
|
||||
int department_id FK
|
||||
string position
|
||||
string title
|
||||
string phone
|
||||
string email
|
||||
decimal base_salary
|
||||
decimal performance_ratio
|
||||
string status
|
||||
datetime hire_date
|
||||
datetime created_at
|
||||
datetime updated_at
|
||||
}
|
||||
ASSESSMENTS {
|
||||
int id PK
|
||||
int staff_id FK
|
||||
int period_year
|
||||
int period_month
|
||||
string period_type
|
||||
decimal total_score
|
||||
decimal 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
|
||||
decimal actual_value
|
||||
decimal score
|
||||
text evidence
|
||||
text remark
|
||||
datetime created_at
|
||||
datetime updated_at
|
||||
}
|
||||
INDICATORS {
|
||||
int id PK
|
||||
string name
|
||||
string code UK
|
||||
string indicator_type
|
||||
decimal weight
|
||||
decimal max_score
|
||||
decimal target_value
|
||||
string unit
|
||||
text calculation_method
|
||||
text description
|
||||
boolean is_active
|
||||
datetime created_at
|
||||
datetime updated_at
|
||||
}
|
||||
DEPARTMENTS ||--o{ STAFF : "1:N"
|
||||
STAFF ||--o{ ASSESSMENTS : "1:N"
|
||||
ASSESSMENTS ||--o{ ASSESSMENT_DETAILS : "1:N"
|
||||
INDICATORS ||--o{ ASSESSMENT_DETAILS : "1:N"
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [models.py](file://backend/app/models/models.py#L62-L85)
|
||||
- [models.py](file://backend/app/models/models.py#L88-L114)
|
||||
- [models.py](file://backend/app/models/models.py#L149-L178)
|
||||
- [models.py](file://backend/app/models/models.py#L181-L202)
|
||||
- [models.py](file://backend/app/models/models.py#L117-L146)
|
||||
|
||||
### 服务层依赖关系
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
API[API路由层] --> Service[AssessmentService]
|
||||
Service --> Model[Assessment模型]
|
||||
Service --> DetailModel[AssessmentDetail模型]
|
||||
Service --> StaffModel[Staff模型]
|
||||
Service --> IndicatorModel[Indicator模型]
|
||||
Service --> Schema[Pydantic Schema]
|
||||
Schema --> CreateSchema[AssessmentCreate]
|
||||
Schema --> UpdateSchema[AssessmentUpdate]
|
||||
Schema --> ResponseSchema[AssessmentResponse]
|
||||
API --> Security[安全验证]
|
||||
Security --> CurrentUser[get_current_active_user]
|
||||
Security --> ManagerUser[get_current_manager_user]
|
||||
Security --> AdminUser[get_current_admin_user]
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [assessment_service.py](file://backend/app/services/assessment_service.py#L14-L11)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L228-L270)
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L1-L438)
|
||||
- [assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
|
||||
|
||||
## 性能考虑
|
||||
|
||||
### 数据库索引设计
|
||||
|
||||
系统采用了多层次的索引策略来优化查询性能：
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
subgraph "主表索引"
|
||||
IDX_STAFF[idx_assessment_staff]
|
||||
IDX_PERIOD[idx_assessment_period]
|
||||
IDX_STATUS[idx_assessment_status]
|
||||
end
|
||||
subgraph "明细表索引"
|
||||
IDX_DETAIL_ASSESS[idx_detail_assessment]
|
||||
IDX_DETAIL_INDICATOR[idx_detail_indicator]
|
||||
end
|
||||
subgraph "查询优化"
|
||||
OPTIMIZE1[按员工ID查询]
|
||||
OPTIMIZE2[按考核周期查询]
|
||||
OPTIMIZE3[按状态过滤]
|
||||
OPTIMIZE4[按指标ID查询明细]
|
||||
end
|
||||
IDX_STAFF --> OPTIMIZE1
|
||||
IDX_PERIOD --> OPTIMIZE2
|
||||
IDX_STATUS --> OPTIMIZE3
|
||||
IDX_DETAIL_ASSESS --> OPTIMIZE4
|
||||
```
|
||||
|
||||
**索引策略说明**：
|
||||
- `idx_assessment_staff`: 优化按员工查询的性能
|
||||
- `idx_assessment_period`: 优化按考核周期查询的性能
|
||||
- `idx_assessment_status`: 优化按状态过滤的性能
|
||||
- `idx_detail_assessment`: 优化明细查询的性能
|
||||
|
||||
### 查询优化策略
|
||||
|
||||
1. **分页查询**：默认每页20条记录，支持最大100条/页
|
||||
2. **条件过滤**：支持按员工ID、科室ID、年度、月份、状态等条件过滤
|
||||
3. **预加载关系**：使用selectinload优化N+1查询问题
|
||||
4. **批量操作**：支持批量创建和批量查询
|
||||
|
||||
### 缓存策略
|
||||
|
||||
虽然当前实现未使用缓存，但建议在以下场景考虑缓存：
|
||||
- 高频查询的考核统计结果
|
||||
- 员工基本信息
|
||||
- 指标模板数据
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L174-L178)
|
||||
- [assessment_service.py](file://backend/app/services/assessment_service.py#L28-L55)
|
||||
|
||||
## 故障排除指南
|
||||
|
||||
### 常见问题和解决方案
|
||||
|
||||
#### 状态转换错误
|
||||
**问题**：尝试在错误状态下进行操作
|
||||
**解决方案**：检查当前考核状态，确保状态转换符合业务规则
|
||||
|
||||
#### 权限不足错误
|
||||
**问题**：403 Forbidden错误
|
||||
**解决方案**：确认用户角色是否具有相应权限，检查当前操作是否在允许范围内
|
||||
|
||||
#### 数据完整性错误
|
||||
**问题**：外键约束违反
|
||||
**解决方案**：确保关联的员工、指标等数据存在且有效
|
||||
|
||||
#### 性能问题
|
||||
**问题**：查询响应缓慢
|
||||
**解决方案**：检查索引使用情况，优化查询条件，考虑分页和缓存策略
|
||||
|
||||
### 调试工具和方法
|
||||
|
||||
1. **日志分析**：查看后端日志文件定位问题
|
||||
2. **数据库监控**：使用EXPLAIN分析慢查询
|
||||
3. **API测试**：使用Swagger UI测试接口功能
|
||||
4. **前端调试**：使用浏览器开发者工具调试前端逻辑
|
||||
|
||||
**章节来源**
|
||||
- [assessments.py](file://backend/app/api/v1/assessments.py#L60-L102)
|
||||
- [assessment_service.py](file://backend/app/services/assessment_service.py#L111-L156)
|
||||
|
||||
## 结论
|
||||
|
||||
考核记录表作为医院绩效管理系统的核心组件，实现了完整的考核生命周期管理和多层级权限控制。通过合理的数据模型设计、完善的API接口、严格的权限控制和优化的数据库索引，系统能够高效地支持医院的绩效管理工作。
|
||||
|
||||
系统的自关联关系设计使得考核人、审核人和被考核员工的身份验证和权限控制变得清晰明确。状态枚举和状态转换机制确保了考核流程的规范性和可追溯性。
|
||||
|
||||
未来可以在现有基础上进一步优化：
|
||||
- 增加缓存机制提升查询性能
|
||||
- 扩展更多统计分析功能
|
||||
- 增强审计日志功能
|
||||
- 支持更多类型的考核周期和指标
|
||||
507
.qoder/repowiki/zh/content/数据库设计/表结构设计/索引与约束设计.md
Normal file
507
.qoder/repowiki/zh/content/数据库设计/表结构设计/索引与约束设计.md
Normal file
@@ -0,0 +1,507 @@
|
||||
# 索引与约束设计
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [models.py](file://backend/app/models/models.py)
|
||||
- [finance.py](file://backend/app/models/finance.py)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py)
|
||||
- [002_template.py](file://backend/alembic/versions/002_template.py)
|
||||
- [database.py](file://backend/app/core/database.py)
|
||||
- [config.py](file://backend/app/core/config.py)
|
||||
- [database.md](file://docs/database.md)
|
||||
- [init_db.py](file://backend/init_db.py)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考量](#性能考量)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
本文件聚焦于该医院绩效系统的数据库索引与约束设计，系统采用 SQLAlchemy ORM + Alembic 进行模型定义与迁移，结合 PostgreSQL 异步驱动，围绕“科室—员工—考核—指标—工资—计划—模板—菜单—财务”等核心业务实体，系统化梳理主键、外键、唯一索引、复合索引、检查约束的设计原则与性能影响，并给出查询优化建议与并发控制考虑。
|
||||
|
||||
## 项目结构
|
||||
- 数据模型集中于 models 目录，通过 Base 声明式基类统一建模。
|
||||
- Alembic 版本化迁移文件定义了初始表结构与索引。
|
||||
- 配置模块提供数据库连接参数与池化配置。
|
||||
- 文档目录包含数据库 ER 图与表结构说明。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "模型层"
|
||||
M1["models.py<br/>核心业务模型"]
|
||||
M2["finance.py<br/>财务核算模型"]
|
||||
end
|
||||
subgraph "迁移层"
|
||||
V1["001_initial.py<br/>初始版本"]
|
||||
V2["002_template.py<br/>模板扩展"]
|
||||
end
|
||||
subgraph "运行时"
|
||||
C["config.py<br/>配置"]
|
||||
D["database.py<br/>引擎/会话"]
|
||||
I["init_db.py<br/>初始化脚本"]
|
||||
end
|
||||
subgraph "文档"
|
||||
DOC["database.md<br/>ER图与表说明"]
|
||||
end
|
||||
M1 --> V1
|
||||
M2 --> V2
|
||||
V1 --> D
|
||||
V2 --> D
|
||||
C --> D
|
||||
I --> D
|
||||
DOC -.参考.-> M1
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [models.py](file://backend/app/models/models.py#L62-L438)
|
||||
- [finance.py](file://backend/app/models/finance.py#L45-L79)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L21-L183)
|
||||
- [002_template.py](file://backend/alembic/versions/002_template.py#L21-L96)
|
||||
- [database.py](file://backend/app/core/database.py#L9-L39)
|
||||
- [config.py](file://backend/app/core/config.py#L18-L22)
|
||||
- [database.md](file://docs/database.md#L1-L286)
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L1-L438)
|
||||
- [finance.py](file://backend/app/models/finance.py#L1-L79)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L1-L183)
|
||||
- [002_template.py](file://backend/alembic/versions/002_template.py#L1-L96)
|
||||
- [database.py](file://backend/app/core/database.py#L1-L39)
|
||||
- [config.py](file://backend/app/core/config.py#L1-L47)
|
||||
- [database.md](file://docs/database.md#L1-L286)
|
||||
|
||||
## 核心组件
|
||||
- 主键与自增：多数表使用整型自增主键，确保全局唯一性与插入性能。
|
||||
- 外键约束：通过 ForeignKey 映射，形成稳定的父子关系与引用完整性。
|
||||
- 唯一约束：对业务唯一字段（如科室编码、员工工号、指标编码、用户名、模板编码）施加唯一约束，避免重复。
|
||||
- 索引策略：针对高频过滤/连接/排序字段建立单列索引；对多条件组合查询建立复合索引；对枚举字段建立索引提升筛选效率。
|
||||
- 检查约束：对数值范围进行约束（如权重>0、金额>=0），保证数据质量与业务规则一致性。
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L62-L438)
|
||||
- [finance.py](file://backend/app/models/finance.py#L45-L79)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L21-L183)
|
||||
- [002_template.py](file://backend/alembic/versions/002_template.py#L21-L96)
|
||||
|
||||
## 架构总览
|
||||
系统采用分层架构，ORM 层负责模型映射与约束声明，迁移层负责表结构演进，运行时提供异步连接与会话管理。
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
A["前端(Vue)"] --> B["后端(FastAPI)"]
|
||||
B --> C["服务层"]
|
||||
C --> D["ORM(SQLAlchemy)"]
|
||||
D --> E["数据库(PostgreSQL)"]
|
||||
D --> F["索引/约束"]
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [database.py](file://backend/app/core/database.py#L9-L39)
|
||||
- [models.py](file://backend/app/models/models.py#L1-L438)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 科室表（departments）
|
||||
- 主键：id（自增）
|
||||
- 唯一索引：code（科室编码）
|
||||
- 单列索引：dept_type（按类型过滤）、parent_id（树形结构查询）
|
||||
- 外键：parent_id 自引用（树形组织）
|
||||
- 设计要点：dept_type 用于快速筛选不同类型的科室；parent_id 支持层级查询；code 唯一保证业务唯一性。
|
||||
|
||||
```mermaid
|
||||
erEntity
|
||||
"departments" {
|
||||
id : integer PK
|
||||
code : varchar(20) UK
|
||||
dept_type : enum
|
||||
parent_id : integer FK
|
||||
level : integer
|
||||
sort_order : integer
|
||||
is_active : boolean
|
||||
created_at : datetime
|
||||
updated_at : datetime
|
||||
}
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [models.py](file://backend/app/models/models.py#L62-L86)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L22-L41)
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L62-L86)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L22-L41)
|
||||
|
||||
### 员工表（staff）
|
||||
- 主键：id（自增）
|
||||
- 唯一索引：employee_id（工号）
|
||||
- 单列索引：department_id（按科室统计/查询）、status（按状态筛选）
|
||||
- 外键：department_id → departments.id
|
||||
- 设计要点：department_id 与 status 的索引支持按科室聚合与状态筛选；unique 约束保证工号唯一。
|
||||
|
||||
```mermaid
|
||||
erEntity
|
||||
"staff" {
|
||||
id : integer PK
|
||||
employee_id : varchar(20) UK
|
||||
department_id : integer FK
|
||||
status : enum
|
||||
created_at : datetime
|
||||
updated_at : datetime
|
||||
}
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [models.py](file://backend/app/models/models.py#L88-L114)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L42-L64)
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L88-L114)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L42-L64)
|
||||
|
||||
### 考核指标表（indicators）
|
||||
- 主键：id（自增）
|
||||
- 唯一索引：code（指标编码）
|
||||
- 单列索引：indicator_type（按类型筛选）
|
||||
- 检查约束：weight > 0（权重必须为正数）
|
||||
- 设计要点：唯一编码保证业务唯一；按类型索引支持快速筛选；检查约束保证权重合法性。
|
||||
|
||||
```mermaid
|
||||
erEntity
|
||||
"indicators" {
|
||||
id : integer PK
|
||||
code : varchar(20) UK
|
||||
indicator_type : enum
|
||||
weight : numeric(5,2)
|
||||
created_at : datetime
|
||||
updated_at : datetime
|
||||
}
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [models.py](file://backend/app/models/models.py#L117-L146)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L66-L85)
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L117-L146)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L66-L85)
|
||||
|
||||
### 考核记录表（assessments）
|
||||
- 主键：id（自增）
|
||||
- 单列索引：staff_id（按员工查询）、status（按状态筛选）
|
||||
- 复合索引：period_year + period_month（按年月组合查询）
|
||||
- 外键：staff_id → staff.id；assessor_id/reviewer_id → staff.id（自关联）
|
||||
- 设计要点：复合索引支持按年月快速定位；staff_id 索引支撑员工维度统计；status 索引便于流程状态筛选。
|
||||
|
||||
```mermaid
|
||||
erEntity
|
||||
"assessments" {
|
||||
id : integer PK
|
||||
staff_id : integer FK
|
||||
period_year : integer
|
||||
period_month : integer
|
||||
status : enum
|
||||
assessor_id : integer FK
|
||||
reviewer_id : integer FK
|
||||
created_at : datetime
|
||||
updated_at : datetime
|
||||
}
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [models.py](file://backend/app/models/models.py#L149-L178)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L87-L112)
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L149-L178)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L87-L112)
|
||||
|
||||
### 考核明细表（assessment_details）
|
||||
- 主键：id（自增）
|
||||
- 单列索引：assessment_id（按考核记录查询明细）、indicator_id（按指标查询明细）
|
||||
- 外键：assessment_id → assessments.id；indicator_id → indicators.id
|
||||
- 设计要点：双外键字段分别建立单列索引，满足“按记录查明细”和“按指标查明细”的常见查询模式。
|
||||
|
||||
```mermaid
|
||||
erEntity
|
||||
"assessment_details" {
|
||||
id : integer PK
|
||||
assessment_id : integer FK
|
||||
indicator_id : integer FK
|
||||
created_at : datetime
|
||||
updated_at : datetime
|
||||
}
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [models.py](file://backend/app/models/models.py#L181-L202)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L114-L131)
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L181-L202)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L114-L131)
|
||||
|
||||
### 工资核算表（salary_records）
|
||||
- 主键：id（自增）
|
||||
- 单列索引：staff_id（按员工查询）、status（按状态筛选）
|
||||
- 复合索引：period_year + period_month（按年月组合查询）
|
||||
- 外键：staff_id → staff.id
|
||||
- 设计要点：复合索引支持按年月快速检索；staff_id 索引支撑员工维度统计。
|
||||
|
||||
```mermaid
|
||||
erEntity
|
||||
"salary_records" {
|
||||
id : integer PK
|
||||
staff_id : integer FK
|
||||
period_year : integer
|
||||
period_month : integer
|
||||
status : varchar(20)
|
||||
created_at : datetime
|
||||
updated_at : datetime
|
||||
}
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [models.py](file://backend/app/models/models.py#L205-L230)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L133-L154)
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L205-L230)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L133-L154)
|
||||
|
||||
### 用户表（users）
|
||||
- 主键：id（自增）
|
||||
- 唯一索引：username（用户名）
|
||||
- 外键：staff_id → staff.id（可选关联）
|
||||
- 设计要点：username 唯一索引支持登录认证；staff_id 外键实现用户与员工的弱关联。
|
||||
|
||||
```mermaid
|
||||
erEntity
|
||||
"users" {
|
||||
id : integer PK
|
||||
username : varchar(50) UK
|
||||
staff_id : integer FK
|
||||
created_at : datetime
|
||||
updated_at : datetime
|
||||
}
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [models.py](file://backend/app/models/models.py#L244-L260)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L156-L172)
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L244-L260)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L156-L172)
|
||||
|
||||
### 绩效计划表（performance_plans）
|
||||
- 主键：id（自增）
|
||||
- 唯一索引：plan_code（计划编码）
|
||||
- 单列索引：plan_level、plan_year、department_id、status
|
||||
- 外键：department_id → departments.id；staff_id → staff.id；submitter_id/approver_id → users.id；parent_plan_id → performance_plans.id（自关联）
|
||||
- 设计要点：多维索引支持按层级、年份、状态、科室等条件筛选；唯一编码保证业务唯一性。
|
||||
|
||||
```mermaid
|
||||
erEntity
|
||||
"performance_plans" {
|
||||
id : integer PK
|
||||
plan_code : varchar(50) UK
|
||||
plan_level : enum
|
||||
plan_year : integer
|
||||
department_id : integer FK
|
||||
status : enum
|
||||
parent_plan_id : integer FK
|
||||
created_at : datetime
|
||||
updated_at : datetime
|
||||
}
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [models.py](file://backend/app/models/models.py#L270-L311)
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L270-L311)
|
||||
|
||||
### 计划-指标关联表（plan_kpi_relations）
|
||||
- 主键：id（自增）
|
||||
- 单列索引：plan_id、indicator_id
|
||||
- 复合唯一索引：plan_id + indicator_id（唯一关联）
|
||||
- 外键：plan_id → performance_plans.id；indicator_id → indicators.id
|
||||
- 设计要点：复合唯一索引防止重复关联；单列索引支撑按计划或指标查询。
|
||||
|
||||
```mermaid
|
||||
erEntity
|
||||
"plan_kpi_relations" {
|
||||
id : integer PK
|
||||
plan_id : integer FK
|
||||
indicator_id : integer FK
|
||||
plan_id+indicator_id : unique
|
||||
created_at : datetime
|
||||
updated_at : datetime
|
||||
}
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [models.py](file://backend/app/models/models.py#L314-L338)
|
||||
- [002_template.py](file://backend/alembic/versions/002_template.py#L41-L63)
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L314-L338)
|
||||
- [002_template.py](file://backend/alembic/versions/002_template.py#L41-L63)
|
||||
|
||||
### 模板-指标关联表（template_indicators）
|
||||
- 主键：id（自增）
|
||||
- 单列索引：template_id、indicator_id
|
||||
- 复合唯一索引：template_id + indicator_id（唯一关联）
|
||||
- 外键：template_id → indicator_templates.id；indicator_id → indicators.id
|
||||
- 设计要点：与计划-指标关联一致的索引策略，确保模板维度的高效查询。
|
||||
|
||||
```mermaid
|
||||
erEntity
|
||||
"template_indicators" {
|
||||
id : integer PK
|
||||
template_id : integer FK
|
||||
indicator_id : integer FK
|
||||
template_id+indicator_id : unique
|
||||
created_at : datetime
|
||||
updated_at : datetime
|
||||
}
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [models.py](file://backend/app/models/models.py#L411-L437)
|
||||
- [002_template.py](file://backend/alembic/versions/002_template.py#L41-L63)
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L411-L437)
|
||||
- [002_template.py](file://backend/alembic/versions/002_template.py#L41-L63)
|
||||
|
||||
### 财务核算表（department_finances）
|
||||
- 主键：id（自增）
|
||||
- 单列索引：department_id、finance_type、category
|
||||
- 复合索引：period_year + period_month（按年月组合查询）
|
||||
- 检查约束：amount >= 0（金额非负）
|
||||
- 外键：department_id → departments.id
|
||||
- 设计要点：多维索引支持按科室、类型、类别、期间的高效查询；检查约束保证财务数据的正向性。
|
||||
|
||||
```mermaid
|
||||
erEntity
|
||||
"department_finances" {
|
||||
id : integer PK
|
||||
department_id : integer FK
|
||||
period_year : integer
|
||||
period_month : integer
|
||||
finance_type : enum
|
||||
category : varchar(50)
|
||||
amount : numeric(12,2)
|
||||
created_at : datetime
|
||||
updated_at : datetime
|
||||
}
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [finance.py](file://backend/app/models/finance.py#L45-L74)
|
||||
|
||||
章节来源
|
||||
- [finance.py](file://backend/app/models/finance.py#L45-L74)
|
||||
|
||||
## 依赖关系分析
|
||||
- 模型层通过 __table_args__ 声明索引与约束，迁移层通过 Alembic 在数据库层面落地。
|
||||
- 外键关系形成稳定的层次结构（如 departments 树形、assessments 与 staff 的自关联）。
|
||||
- 初始化脚本在首次启动时创建表结构并注入基础数据。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "模型定义"
|
||||
MD["models.py"]
|
||||
MF["finance.py"]
|
||||
end
|
||||
subgraph "迁移执行"
|
||||
MI["001_initial.py"]
|
||||
MT["002_template.py"]
|
||||
end
|
||||
subgraph "运行时"
|
||||
DB["database.py"]
|
||||
CFG["config.py"]
|
||||
INIT["init_db.py"]
|
||||
end
|
||||
MD --> MI
|
||||
MF --> MT
|
||||
MI --> DB
|
||||
MT --> DB
|
||||
CFG --> DB
|
||||
INIT --> DB
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [models.py](file://backend/app/models/models.py#L62-L438)
|
||||
- [finance.py](file://backend/app/models/finance.py#L45-L79)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L21-L183)
|
||||
- [002_template.py](file://backend/alembic/versions/002_template.py#L21-L96)
|
||||
- [database.py](file://backend/app/core/database.py#L9-L39)
|
||||
- [config.py](file://backend/app/core/config.py#L18-L22)
|
||||
- [init_db.py](file://backend/init_db.py#L11-L83)
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L62-L438)
|
||||
- [finance.py](file://backend/app/models/finance.py#L45-L79)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L21-L183)
|
||||
- [002_template.py](file://backend/alembic/versions/002_template.py#L21-L96)
|
||||
- [database.py](file://backend/app/core/database.py#L9-L39)
|
||||
- [config.py](file://backend/app/core/config.py#L18-L22)
|
||||
- [init_db.py](file://backend/init_db.py#L11-L83)
|
||||
|
||||
## 性能考量
|
||||
- 索引选择原则
|
||||
- 单列索引：适用于等值/范围查询的过滤字段（如 status、dept_type、indicator_type）。
|
||||
- 复合索引：适用于多条件组合查询（如 assessments 的 period_year + period_month，salary_records 的 period_year + period_month，finance 的 period_year + period_month）。
|
||||
- 唯一索引：保证业务唯一性（code、employee_id、username、plan_code、模板-指标唯一组合）。
|
||||
- 查询优化建议
|
||||
- 使用复合索引覆盖多条件过滤，减少回表与排序开销。
|
||||
- 对枚举字段建立索引，提升 IN/等值过滤效率。
|
||||
- 尽量避免 SELECT *，仅选择必要列，降低 IO。
|
||||
- 对大表的分页查询配合 ORDER BY + LIMIT，确保 ORDER BY 列命中索引。
|
||||
- 并发控制
|
||||
- 使用数据库事务隔离级别与锁策略，避免写放大与死锁。
|
||||
- 对高并发写入场景，合理拆分热点表或引入分区（如按年/月分区）。
|
||||
- 控制批量写入批次大小，避免长事务占用资源。
|
||||
- 数据完整性
|
||||
- 外键约束保证引用完整性；唯一约束保证业务唯一性；检查约束保证数值范围合法。
|
||||
- 在 ORM 层与数据库层双重约束，确保数据一致性。
|
||||
|
||||
[本节为通用性能指导，不直接分析具体文件]
|
||||
|
||||
## 故障排查指南
|
||||
- 索引未生效
|
||||
- 检查查询条件是否与索引列顺序匹配（复合索引前缀匹配）。
|
||||
- 使用 EXPLAIN/ANALYZE 分析执行计划，确认索引扫描路径。
|
||||
- 唯一冲突
|
||||
- 当插入重复唯一键时，捕获数据库异常并提示用户修正（如重复工号、重复指标编码）。
|
||||
- 外键约束失败
|
||||
- 确认被引用记录存在且状态有效；检查删除/更新策略（RESTRICT/CASCADE/SET NULL）。
|
||||
- 检查约束失败
|
||||
- 校验输入数据是否满足约束条件（如权重>0、金额>=0）；在业务层提前校验，减少数据库往返。
|
||||
|
||||
[本节为通用排查建议，不直接分析具体文件]
|
||||
|
||||
## 结论
|
||||
该系统在索引与约束设计上遵循“业务唯一性优先、高频查询覆盖、枚举与复合索引配合”的原则，结合外键与检查约束，有效保障了数据完整性与查询性能。建议在后续迭代中持续关注查询执行计划与热点表，适时引入分区与物化视图，进一步提升大规模数据下的响应能力。
|
||||
|
||||
[本节为总结性内容，不直接分析具体文件]
|
||||
|
||||
## 附录
|
||||
- 数据库连接与池化配置
|
||||
- 数据库 URL、连接池大小与溢出配置，确保高并发下的稳定性。
|
||||
- 初始化脚本
|
||||
- 首次启动自动创建表结构并注入基础数据，便于开发与测试环境快速就绪。
|
||||
|
||||
章节来源
|
||||
- [config.py](file://backend/app/core/config.py#L18-L22)
|
||||
- [init_db.py](file://backend/init_db.py#L11-L83)
|
||||
1164
.qoder/repowiki/zh/content/数据库设计/表结构设计/表结构设计.md
Normal file
1164
.qoder/repowiki/zh/content/数据库设计/表结构设计/表结构设计.md
Normal file
File diff suppressed because it is too large
Load Diff
433
.qoder/repowiki/zh/content/数据库设计/表结构设计/配置管理表/系统用户表.md
Normal file
433
.qoder/repowiki/zh/content/数据库设计/表结构设计/配置管理表/系统用户表.md
Normal file
@@ -0,0 +1,433 @@
|
||||
# 系统用户表
|
||||
|
||||
<cite>
|
||||
**本文档引用的文件**
|
||||
- [models.py](file://backend/app/models/models.py)
|
||||
- [auth.py](file://backend/app/api/v1/auth.py)
|
||||
- [security.py](file://backend/app/core/security.py)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py)
|
||||
- [config.py](file://backend/app/core/config.py)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py)
|
||||
- [init_db.py](file://backend/app/core/init_db.py)
|
||||
- [database.md](file://docs/database.md)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构概览](#架构概览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考虑](#性能考虑)
|
||||
8. [故障排除指南](#故障排除指南)
|
||||
9. [结论](#结论)
|
||||
|
||||
## 简介
|
||||
|
||||
系统用户表(users)是医院绩效考核管理系统的核心数据表，负责存储系统用户的认证和授权信息。该表实现了完整的用户身份管理功能，包括用户名密码管理、角色权限控制、员工关联关系、状态管理和登录认证流程。
|
||||
|
||||
本系统采用现代化的安全架构，使用bcrypt进行密码哈希加密，JWT令牌进行无状态认证，并通过角色权限体系实现细粒度的访问控制。用户表与员工表建立了关联关系，支持将系统用户与实际员工身份进行绑定。
|
||||
|
||||
## 项目结构
|
||||
|
||||
系统用户表位于后端应用的数据模型层，采用SQLAlchemy ORM框架进行数据库映射。整个用户管理系统由以下核心组件构成：
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "数据模型层"
|
||||
User[User模型]
|
||||
Staff[Staff模型]
|
||||
Department[Department模型]
|
||||
end
|
||||
subgraph "认证服务层"
|
||||
Security[Security模块]
|
||||
AuthAPI[Auth API路由]
|
||||
Schemas[Schemas定义]
|
||||
end
|
||||
subgraph "配置管理层"
|
||||
Config[Config配置]
|
||||
InitDB[初始化脚本]
|
||||
end
|
||||
User --> Security
|
||||
AuthAPI --> Security
|
||||
Security --> Config
|
||||
InitDB --> User
|
||||
User --> Staff
|
||||
Staff --> Department
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [models.py](file://backend/app/models/models.py#L244-L261)
|
||||
- [security.py](file://backend/app/core/security.py#L1-L110)
|
||||
- [auth.py](file://backend/app/api/v1/auth.py#L1-L74)
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L244-L261)
|
||||
- [auth.py](file://backend/app/api/v1/auth.py#L1-L74)
|
||||
- [security.py](file://backend/app/core/security.py#L1-L110)
|
||||
|
||||
## 核心组件
|
||||
|
||||
### 用户表结构定义
|
||||
|
||||
系统用户表(users)采用完整的字段定义，确保用户管理的完整性和安全性：
|
||||
|
||||
| 字段名 | 类型 | 约束 | 描述 | 默认值 |
|
||||
|--------|------|------|------|--------|
|
||||
| id | Integer | 主键, 自增 | 用户唯一标识符 | 无 |
|
||||
| username | String(50) | 非空, 唯一 | 用户登录名 | 无 |
|
||||
| password_hash | String(255) | 非空 | 密码哈希值 | 无 |
|
||||
| staff_id | Integer | 外键, 可空 | 关联员工ID | NULL |
|
||||
| role | String(20) | 非空 | 用户角色 | "staff" |
|
||||
| is_active | Boolean | 非空 | 账户启用状态 | TRUE |
|
||||
| last_login | DateTime | 可空 | 最后登录时间 | NULL |
|
||||
| created_at | DateTime | 非空 | 创建时间 | 当前时间 |
|
||||
| updated_at | DateTime | 非空 | 更新时间 | 当前时间 |
|
||||
|
||||
### 角色权限体系
|
||||
|
||||
系统实现了三层角色权限控制机制：
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
subgraph "用户角色层次"
|
||||
Admin[管理员<br/>admin]
|
||||
Manager[经理<br/>manager]
|
||||
Staff[普通员工<br/>staff]
|
||||
end
|
||||
subgraph "权限级别"
|
||||
Level1[完全访问权限]
|
||||
Level2[部分管理权限]
|
||||
Level3[基础操作权限]
|
||||
end
|
||||
Admin --> Level1
|
||||
Manager --> Level2
|
||||
Staff --> Level3
|
||||
Level1 --> Admin
|
||||
Level2 --> Manager
|
||||
Level3 --> Staff
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L321-L327)
|
||||
- [security.py](file://backend/app/core/security.py#L94-L109)
|
||||
|
||||
**章节来源**
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L321-L327)
|
||||
- [security.py](file://backend/app/core/security.py#L94-L109)
|
||||
|
||||
## 架构概览
|
||||
|
||||
系统用户管理采用分层架构设计，确保安全性和可维护性：
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as 客户端
|
||||
participant AuthAPI as 认证API
|
||||
participant Security as 安全模块
|
||||
participant DB as 数据库
|
||||
participant JWT as JWT服务
|
||||
Client->>AuthAPI : POST /auth/login
|
||||
AuthAPI->>DB : 查询用户信息
|
||||
DB-->>AuthAPI : 返回用户记录
|
||||
AuthAPI->>Security : 验证密码
|
||||
Security->>Security : bcrypt校验
|
||||
Security-->>AuthAPI : 验证结果
|
||||
AuthAPI->>JWT : 创建访问令牌
|
||||
JWT-->>AuthAPI : 返回JWT令牌
|
||||
AuthAPI-->>Client : 返回访问令牌
|
||||
Note over Client,JWT : 用户认证完成
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [auth.py](file://backend/app/api/v1/auth.py#L17-L37)
|
||||
- [security.py](file://backend/app/core/security.py#L24-L43)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 用户模型类分析
|
||||
|
||||
用户模型类实现了完整的用户实体定义，包含字段映射、约束条件和索引配置：
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class User {
|
||||
+int id
|
||||
+string username
|
||||
+string password_hash
|
||||
+int staff_id
|
||||
+string role
|
||||
+boolean is_active
|
||||
+datetime last_login
|
||||
+datetime created_at
|
||||
+datetime updated_at
|
||||
+__tablename__ = "users"
|
||||
+__table_args__
|
||||
+Index(idx_user_username)
|
||||
+ForeignKey(staff_id -> staff.id)
|
||||
}
|
||||
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
|
||||
}
|
||||
User --> Staff : "关联员工"
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [models.py](file://backend/app/models/models.py#L244-L261)
|
||||
- [models.py](file://backend/app/models/models.py#L88-L114)
|
||||
|
||||
### 登录认证流程
|
||||
|
||||
系统采用OAuth2密码模式结合JWT令牌的认证机制：
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([用户发起登录]) --> ValidateInput["验证用户名密码格式"]
|
||||
ValidateInput --> InputValid{"输入有效?"}
|
||||
InputValid --> |否| ReturnError["返回错误信息"]
|
||||
InputValid --> |是| QueryUser["查询用户信息"]
|
||||
QueryUser --> UserExists{"用户存在?"}
|
||||
UserExists --> |否| ReturnError
|
||||
UserExists --> |是| VerifyPassword["验证密码"]
|
||||
VerifyPassword --> PasswordValid{"密码正确?"}
|
||||
PasswordValid --> |否| ReturnError
|
||||
PasswordValid --> |是| CheckActive["检查账户状态"]
|
||||
CheckActive --> IsActive{"账户启用?"}
|
||||
IsActive --> |否| ReturnDisabled["账户已禁用"]
|
||||
IsActive --> |是| CreateToken["创建JWT访问令牌"]
|
||||
CreateToken --> SetLastLogin["更新最后登录时间"]
|
||||
SetLastLogin --> ReturnToken["返回访问令牌"]
|
||||
ReturnError --> End([结束])
|
||||
ReturnDisabled --> End
|
||||
ReturnToken --> End
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [auth.py](file://backend/app/api/v1/auth.py#L17-L37)
|
||||
- [security.py](file://backend/app/core/security.py#L24-L31)
|
||||
|
||||
### 密码安全管理
|
||||
|
||||
系统采用bcrypt算法进行密码哈希处理，确保密码存储的安全性：
|
||||
|
||||
| 安全特性 | 实现方式 | 说明 |
|
||||
|----------|----------|------|
|
||||
| 密码哈希 | bcrypt | 使用bcrypt.gensalt()生成盐值 |
|
||||
| 哈希验证 | bcrypt.checkpw() | 验证原始密码与哈希值匹配 |
|
||||
| 令牌加密 | HS256算法 | 使用SECRET_KEY进行JWT签名 |
|
||||
| 过期时间 | 8小时 | ACCESS_TOKEN_EXPIRE_MINUTES=480 |
|
||||
| 传输安全 | HTTPS | 生产环境建议启用HTTPS |
|
||||
|
||||
**章节来源**
|
||||
- [security.py](file://backend/app/core/security.py#L18-L43)
|
||||
- [config.py](file://backend/app/core/config.py#L23-L26)
|
||||
|
||||
### 用户状态管理
|
||||
|
||||
系统实现了灵活的用户状态管理机制：
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> Active : 创建用户时默认激活
|
||||
Active --> Disabled : 管理员禁用账户
|
||||
Disabled --> Active : 管理员重新激活
|
||||
Active --> [*] : 账户删除
|
||||
note right of Active
|
||||
可正常登录
|
||||
可访问系统功能
|
||||
end note
|
||||
note right of Disabled
|
||||
无法登录系统
|
||||
访问被拒绝
|
||||
end note
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [models.py](file://backend/app/models/models.py#L252-L254)
|
||||
- [security.py](file://backend/app/core/security.py#L85-L91)
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L252-L254)
|
||||
- [security.py](file://backend/app/core/security.py#L85-L91)
|
||||
|
||||
### 员工关联关系
|
||||
|
||||
用户表与员工表建立了可选的一对一关联关系：
|
||||
|
||||
```mermaid
|
||||
erDiagram
|
||||
STAFF {
|
||||
int id PK
|
||||
string employee_id UK
|
||||
string name
|
||||
int department_id FK
|
||||
string position
|
||||
string title
|
||||
float base_salary
|
||||
float performance_ratio
|
||||
string 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
|
||||
boolean is_active
|
||||
datetime last_login
|
||||
datetime created_at
|
||||
datetime updated_at
|
||||
}
|
||||
STAFF ||--o| USERS : "关联"
|
||||
note for STAFF "员工表"
|
||||
note for USERS "用户表"
|
||||
note for USERS "staff_id -> staff.id"
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [models.py](file://backend/app/models/models.py#L88-L114)
|
||||
- [models.py](file://backend/app/models/models.py#L244-L261)
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L88-L114)
|
||||
- [models.py](file://backend/app/models/models.py#L244-L261)
|
||||
|
||||
## 依赖关系分析
|
||||
|
||||
系统用户管理模块的依赖关系如下：
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "外部依赖"
|
||||
SQLAlchemy[SQLAlchemy ORM]
|
||||
Bcrypt[bcrypt加密库]
|
||||
JWT[jose JWT库]
|
||||
FastAPI[FastAPI框架]
|
||||
end
|
||||
subgraph "内部模块"
|
||||
UserModel[User模型]
|
||||
SecurityModule[安全模块]
|
||||
AuthAPI[认证API]
|
||||
ConfigModule[配置模块]
|
||||
end
|
||||
subgraph "数据库层"
|
||||
UsersTable[users表]
|
||||
StaffTable[staff表]
|
||||
end
|
||||
SQLAlchemy --> UserModel
|
||||
Bcrypt --> SecurityModule
|
||||
JWT --> SecurityModule
|
||||
FastAPI --> AuthAPI
|
||||
UserModel --> UsersTable
|
||||
UserModel --> StaffTable
|
||||
SecurityModule --> UserModel
|
||||
AuthAPI --> SecurityModule
|
||||
ConfigModule --> SecurityModule
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [models.py](file://backend/app/models/models.py#L1-L13)
|
||||
- [security.py](file://backend/app/core/security.py#L1-L16)
|
||||
- [auth.py](file://backend/app/api/v1/auth.py#L1-L14)
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L1-L13)
|
||||
- [security.py](file://backend/app/core/security.py#L1-L16)
|
||||
- [auth.py](file://backend/app/api/v1/auth.py#L1-L14)
|
||||
|
||||
## 性能考虑
|
||||
|
||||
### 数据库性能优化
|
||||
|
||||
1. **索引策略**
|
||||
- 用户名唯一索引：支持快速用户名查找
|
||||
- 复合索引：用于常用查询条件组合
|
||||
|
||||
2. **连接池配置**
|
||||
- 数据库连接池大小：20
|
||||
- 最大溢出连接：10
|
||||
- 异步数据库连接：提升并发性能
|
||||
|
||||
3. **缓存策略**
|
||||
- JWT令牌本地缓存：减少数据库查询
|
||||
- 用户权限缓存：避免重复权限验证
|
||||
|
||||
### 安全性能平衡
|
||||
|
||||
1. **密码哈希成本**
|
||||
- bcrypt默认成本因子：提供良好安全性
|
||||
- 可根据硬件性能调整成本因子
|
||||
|
||||
2. **令牌过期策略**
|
||||
- 8小时有效期：平衡安全性与用户体验
|
||||
- 可配置的过期时间
|
||||
|
||||
## 故障排除指南
|
||||
|
||||
### 常见问题及解决方案
|
||||
|
||||
| 问题类型 | 症状 | 可能原因 | 解决方案 |
|
||||
|----------|------|----------|----------|
|
||||
| 登录失败 | 401未授权错误 | 用户名或密码错误 | 检查用户名密码，确认大小写 |
|
||||
| 账户禁用 | 403禁止访问 | 用户被管理员禁用 | 联系管理员重新激活 |
|
||||
| 密码错误 | 验证失败 | bcrypt哈希不匹配 | 确认密码正确性 |
|
||||
| 令牌过期 | 401未授权 | JWT过期 | 重新登录获取新令牌 |
|
||||
| 数据库连接 | 连接超时 | 连接池耗尽 | 增加连接池大小 |
|
||||
|
||||
### 调试工具和方法
|
||||
|
||||
1. **日志分析**
|
||||
- 查看认证API日志
|
||||
- 监控数据库查询性能
|
||||
- 跟踪JWT令牌生命周期
|
||||
|
||||
2. **数据库检查**
|
||||
```sql
|
||||
-- 检查用户表结构
|
||||
SELECT * FROM users LIMIT 1;
|
||||
|
||||
-- 验证用户存在性
|
||||
SELECT COUNT(*) FROM users WHERE username = 'admin';
|
||||
|
||||
-- 检查密码哈希
|
||||
SELECT username, password_hash FROM users WHERE username = 'admin';
|
||||
```
|
||||
|
||||
3. **配置验证**
|
||||
- 检查SECRET_KEY配置
|
||||
- 验证ACCESS_TOKEN_EXPIRE_MINUTES设置
|
||||
- 确认CORS配置正确
|
||||
|
||||
**章节来源**
|
||||
- [auth.py](file://backend/app/api/v1/auth.py#L30-L34)
|
||||
- [security.py](file://backend/app/core/security.py#L55-L82)
|
||||
|
||||
## 结论
|
||||
|
||||
系统用户表(users)作为医院绩效考核管理系统的核心组件，实现了完整的用户身份管理功能。通过采用bcrypt密码哈希、JWT令牌认证和三层角色权限控制，系统确保了用户管理的安全性和灵活性。
|
||||
|
||||
用户表的设计充分考虑了医院管理的实际需求，支持与员工表的关联管理，实现了用户身份与实际工作职责的绑定。同时，系统的异步数据库连接和连接池配置保证了良好的性能表现。
|
||||
|
||||
建议在生产环境中：
|
||||
1. 定期更新SECRET_KEY并妥善保管
|
||||
2. 配置HTTPS确保传输安全
|
||||
3. 设置合理的密码复杂度要求
|
||||
4. 定期审查用户权限分配
|
||||
5. 监控用户登录活动日志
|
||||
|
||||
通过这些措施，可以确保系统用户管理的安全性和可靠性，为医院绩效管理提供坚实的技术支撑。
|
||||
394
.qoder/repowiki/zh/content/数据库设计/表结构设计/配置管理表/系统菜单表.md
Normal file
394
.qoder/repowiki/zh/content/数据库设计/表结构设计/配置管理表/系统菜单表.md
Normal file
@@ -0,0 +1,394 @@
|
||||
# 系统菜单表
|
||||
|
||||
<cite>
|
||||
**本文档引用的文件**
|
||||
- [models.py](file://backend/app/models/models.py)
|
||||
- [menus.py](file://backend/app/api/v1/menus.py)
|
||||
- [menu_service.py](file://backend/app/services/menu_service.py)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py)
|
||||
- [Menus.vue](file://frontend/src/views/system/Menus.vue)
|
||||
- [menu.js](file://frontend/src/api/menu.js)
|
||||
- [security.py](file://backend/app/core/security.py)
|
||||
- [config.py](file://backend/app/core/config.py)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py)
|
||||
- [002_template.py](file://backend/alembic/versions/002_template.py)
|
||||
- [create_menu_tables.py](file://backend/create_menu_tables.py)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构概览](#架构概览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考虑](#性能考虑)
|
||||
8. [故障排除指南](#故障排除指南)
|
||||
9. [结论](#结论)
|
||||
|
||||
## 简介
|
||||
|
||||
系统菜单表(menus)是医院绩效考核管理系统的核心导航组件，负责管理整个系统的菜单结构、权限控制和用户界面导航。该表采用自引用的树形结构设计，支持多层级菜单组织，并通过权限标识实现细粒度的访问控制。
|
||||
|
||||
本系统采用前后端分离架构，后端使用FastAPI + SQLAlchemy，前端使用Vue.js + Element Plus，实现了完整的菜单管理功能，包括菜单树形展示、权限控制、动态路由生成等特性。
|
||||
|
||||
## 项目结构
|
||||
|
||||
系统菜单表位于后端应用的models模块中，与API接口、服务层和前端界面形成完整的菜单管理生态系统：
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "后端架构"
|
||||
Models[数据模型层<br/>models.py]
|
||||
API[API接口层<br/>menus.py]
|
||||
Service[服务层<br/>menu_service.py]
|
||||
Schemas[数据模式<br/>schemas.py]
|
||||
Security[安全认证<br/>security.py]
|
||||
end
|
||||
subgraph "前端架构"
|
||||
Vue[Vue组件<br/>Menus.vue]
|
||||
Api[API调用<br/>menu.js]
|
||||
end
|
||||
subgraph "数据库层"
|
||||
DB[(PostgreSQL数据库)]
|
||||
MenusTable[menus表]
|
||||
end
|
||||
Vue --> Api
|
||||
Api --> API
|
||||
API --> Service
|
||||
Service --> Models
|
||||
Models --> DB
|
||||
DB --> MenusTable
|
||||
Security --> API
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [models.py](file://backend/app/models/models.py#L347-L373)
|
||||
- [menus.py](file://backend/app/api/v1/menus.py#L1-L164)
|
||||
- [menu_service.py](file://backend/app/services/menu_service.py#L1-L137)
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L347-L373)
|
||||
- [menus.py](file://backend/app/api/v1/menus.py#L1-L164)
|
||||
- [menu_service.py](file://backend/app/services/menu_service.py#L1-L137)
|
||||
|
||||
## 核心组件
|
||||
|
||||
### 数据模型定义
|
||||
|
||||
系统菜单表采用SQLAlchemy ORM映射，定义了完整的菜单结构和业务规则：
|
||||
|
||||
| 字段名称 | 数据类型 | 约束条件 | 描述 | 默认值 |
|
||||
|---------|---------|---------|------|--------|
|
||||
| id | Integer | 主键, 自增 | 菜单唯一标识符 | - |
|
||||
| parent_id | Integer | 外键(menus.id), 可空 | 父菜单ID | NULL |
|
||||
| menu_type | Enum | 必填, 菜单类型 | 菜单类型(MENU/BUTTON) | MENU |
|
||||
| menu_name | String(100) | 必填, 非空 | 菜单显示名称 | - |
|
||||
| menu_icon | String(50) | 可空 | Element Plus图标名称 | NULL |
|
||||
| path | String(200) | 必填, 非空 | Vue Router路由路径 | - |
|
||||
| component | String(200) | 可空 | 组件路径 | NULL |
|
||||
| permission | String(100) | 可空 | 权限标识符 | NULL |
|
||||
| sort_order | Integer | 必填, ≥0 | 排序权重 | 0 |
|
||||
| is_visible | Boolean | 必填 | 是否对用户可见 | TRUE |
|
||||
| is_active | Boolean | 必填 | 是否启用 | TRUE |
|
||||
| created_at | DateTime | 必填 | 创建时间 | 当前时间 |
|
||||
| updated_at | DateTime | 必填 | 更新时间 | 当前时间 |
|
||||
|
||||
### 菜单类型定义
|
||||
|
||||
系统支持两种菜单类型，用于不同的导航需求：
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class MenuType {
|
||||
<<enumeration>>
|
||||
MENU : "menu"
|
||||
BUTTON : "button"
|
||||
}
|
||||
class Menu {
|
||||
+int id
|
||||
+int parent_id
|
||||
+MenuType menu_type
|
||||
+string menu_name
|
||||
+string menu_icon
|
||||
+string path
|
||||
+string component
|
||||
+string permission
|
||||
+int sort_order
|
||||
+bool is_visible
|
||||
+bool is_active
|
||||
+datetime created_at
|
||||
+datetime updated_at
|
||||
}
|
||||
Menu --> MenuType : uses
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [models.py](file://backend/app/models/models.py#L341-L345)
|
||||
- [models.py](file://backend/app/models/models.py#L347-L373)
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L341-L373)
|
||||
|
||||
## 架构概览
|
||||
|
||||
系统采用分层架构设计，确保菜单管理功能的可维护性和扩展性：
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Frontend as 前端界面
|
||||
participant API as API接口
|
||||
participant Service as 服务层
|
||||
participant Model as 数据模型
|
||||
participant DB as 数据库
|
||||
Frontend->>API : GET /menus/tree
|
||||
API->>Service : get_tree(visible_only)
|
||||
Service->>Model : 查询菜单树
|
||||
Model->>DB : SQL查询
|
||||
DB-->>Model : 返回结果集
|
||||
Model-->>Service : 菜单对象列表
|
||||
Service->>Service : 转换为字典格式
|
||||
Service-->>API : 菜单树数据
|
||||
API-->>Frontend : JSON响应
|
||||
Note over Frontend,DB : 用户权限验证由安全中间件处理
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [menus.py](file://backend/app/api/v1/menus.py#L17-L29)
|
||||
- [menu_service.py](file://backend/app/services/menu_service.py#L16-L29)
|
||||
|
||||
**章节来源**
|
||||
- [menus.py](file://backend/app/api/v1/menus.py#L1-L164)
|
||||
- [menu_service.py](file://backend/app/services/menu_service.py#L1-L137)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 后端API接口
|
||||
|
||||
系统提供了完整的菜单管理RESTful API，支持CRUD操作和菜单树查询：
|
||||
|
||||
#### 菜单树查询接口
|
||||
```mermaid
|
||||
flowchart TD
|
||||
GetTree[GET /menus/tree] --> ValidateParams[验证请求参数]
|
||||
ValidateParams --> CheckPermissions[检查用户权限]
|
||||
CheckPermissions --> BuildQuery[构建查询条件]
|
||||
BuildQuery --> ApplyFilters[应用过滤器]
|
||||
ApplyFilters --> ExecuteQuery[执行数据库查询]
|
||||
ExecuteQuery --> TransformData[转换数据格式]
|
||||
TransformData --> ReturnResponse[返回响应]
|
||||
CheckPermissions --> |用户未认证| Unauthorized[401 未授权]
|
||||
CheckPermissions --> |用户被禁用| Forbidden[403 禁止访问]
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [menus.py](file://backend/app/api/v1/menus.py#L17-L29)
|
||||
- [security.py](file://backend/app/core/security.py#L85-L91)
|
||||
|
||||
#### 菜单管理操作
|
||||
系统支持以下主要操作：
|
||||
- **创建菜单**: POST `/menus` - 需要管理员或经理权限
|
||||
- **更新菜单**: PUT `/menus/{menu_id}` - 需要管理员或经理权限
|
||||
- **删除菜单**: DELETE `/menus/{menu_id}` - 需要管理员或经理权限
|
||||
- **初始化菜单**: POST `/menus/init` - 需要管理员权限
|
||||
|
||||
**章节来源**
|
||||
- [menus.py](file://backend/app/api/v1/menus.py#L98-L164)
|
||||
|
||||
### 服务层实现
|
||||
|
||||
服务层负责业务逻辑处理和数据访问：
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class MenuService {
|
||||
+get_tree(db, visible_only) List[Dict]
|
||||
+get_list(db, menu_type, is_visible) List[Menu]
|
||||
+get_by_id(db, menu_id) Menu
|
||||
+create(db, menu_data) Menu
|
||||
+update(db, menu_id, menu_data) Menu
|
||||
+delete(db, menu_id) bool
|
||||
+init_default_menus(db) void
|
||||
-_menu_to_dict(menu) Dict
|
||||
}
|
||||
class MenuRepository {
|
||||
+find_all() List[Menu]
|
||||
+find_by_id(id) Menu
|
||||
+save(menu) Menu
|
||||
+delete(menu) void
|
||||
}
|
||||
MenuService --> MenuRepository : uses
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [menu_service.py](file://backend/app/services/menu_service.py#L12-L137)
|
||||
|
||||
**章节来源**
|
||||
- [menu_service.py](file://backend/app/services/menu_service.py#L1-L137)
|
||||
|
||||
### 前端界面实现
|
||||
|
||||
前端使用Vue.js实现菜单管理界面，提供直观的可视化操作：
|
||||
|
||||
#### 菜单管理界面功能
|
||||
- **菜单树形展示**: 使用Element Plus Tree组件展示层级关系
|
||||
- **表单编辑**: 支持菜单属性的增删改查
|
||||
- **权限控制**: 基于用户角色的界面元素显示
|
||||
- **实时预览**: 修改后的菜单效果即时反映
|
||||
|
||||
**章节来源**
|
||||
- [Menus.vue](file://frontend/src/views/system/Menus.vue#L1-L265)
|
||||
|
||||
### 权限控制系统
|
||||
|
||||
系统通过多种机制实现菜单权限控制：
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
subgraph "权限层次"
|
||||
Role[用户角色<br/>admin/manager/staff]
|
||||
Permission[权限标识<br/>system:menu:*]
|
||||
Menu[菜单权限<br/>menu.permission]
|
||||
end
|
||||
subgraph "验证流程"
|
||||
Request[请求到达]
|
||||
CheckRole[检查角色]
|
||||
CheckPermission[检查权限]
|
||||
CheckMenu[检查菜单权限]
|
||||
Allow[允许访问]
|
||||
Deny[拒绝访问]
|
||||
end
|
||||
Request --> CheckRole
|
||||
CheckRole --> CheckPermission
|
||||
CheckPermission --> CheckMenu
|
||||
CheckMenu --> |满足条件| Allow
|
||||
CheckMenu --> |不满足| Deny
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [security.py](file://backend/app/core/security.py#L94-L109)
|
||||
- [models.py](file://backend/app/models/models.py#L358-L358)
|
||||
|
||||
**章节来源**
|
||||
- [security.py](file://backend/app/core/security.py#L1-L110)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L584-L638)
|
||||
|
||||
## 依赖关系分析
|
||||
|
||||
系统菜单表与其他组件的依赖关系如下：
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "核心依赖"
|
||||
MenuModel[Menu模型<br/>models.py]
|
||||
MenuAPI[菜单API<br/>menus.py]
|
||||
MenuService[菜单服务<br/>menu_service.py]
|
||||
MenuSchema[菜单模式<br/>schemas.py]
|
||||
end
|
||||
subgraph "安全依赖"
|
||||
Security[安全模块<br/>security.py]
|
||||
User[用户模型<br/>models.py]
|
||||
end
|
||||
subgraph "前端依赖"
|
||||
MenuView[菜单视图<br/>Menus.vue]
|
||||
MenuAPIJS[菜单API<br/>menu.js]
|
||||
end
|
||||
subgraph "数据库依赖"
|
||||
Database[(PostgreSQL)]
|
||||
Migration[数据库迁移<br/>alembic]
|
||||
end
|
||||
MenuAPI --> MenuService
|
||||
MenuService --> MenuModel
|
||||
MenuAPI --> Security
|
||||
Security --> User
|
||||
MenuView --> MenuAPIJS
|
||||
MenuAPIJS --> MenuAPI
|
||||
MenuModel --> Database
|
||||
Migration --> Database
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [models.py](file://backend/app/models/models.py#L347-L373)
|
||||
- [menus.py](file://backend/app/api/v1/menus.py#L1-L164)
|
||||
- [menu_service.py](file://backend/app/services/menu_service.py#L1-L137)
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L1-L438)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L1-L183)
|
||||
|
||||
## 性能考虑
|
||||
|
||||
### 查询优化策略
|
||||
|
||||
1. **索引设计**: 菜单表建立了多个复合索引以优化查询性能
|
||||
2. **懒加载**: 使用selectinload优化N+1查询问题
|
||||
3. **条件过滤**: 支持按类型和可见性进行快速过滤
|
||||
4. **缓存策略**: 可考虑在应用层实现菜单树缓存
|
||||
|
||||
### 数据库设计优化
|
||||
|
||||
```mermaid
|
||||
erDiagram
|
||||
MENUS {
|
||||
integer id PK
|
||||
integer parent_id FK
|
||||
string menu_type
|
||||
string menu_name
|
||||
string menu_icon
|
||||
string path
|
||||
string component
|
||||
string permission
|
||||
integer sort_order
|
||||
boolean is_visible
|
||||
boolean is_active
|
||||
datetime created_at
|
||||
datetime updated_at
|
||||
}
|
||||
MENUS }o--|| MENUS : "parent_id -> id"
|
||||
INDEXES {
|
||||
idx_menu_parent parent_id
|
||||
idx_menu_type menu_type
|
||||
idx_menu_visible is_visible
|
||||
}
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [models.py](file://backend/app/models/models.py#L368-L372)
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L368-L372)
|
||||
|
||||
## 故障排除指南
|
||||
|
||||
### 常见问题及解决方案
|
||||
|
||||
#### 菜单权限问题
|
||||
- **问题**: 用户无法看到某些菜单
|
||||
- **原因**: 菜单is_visible=false或用户权限不足
|
||||
- **解决**: 检查菜单的is_visible状态和用户的role字段
|
||||
|
||||
#### 菜单树加载失败
|
||||
- **问题**: 菜单树无法正常显示
|
||||
- **原因**: 数据库连接问题或查询条件错误
|
||||
- **解决**: 检查数据库连接配置和索引完整性
|
||||
|
||||
#### 权限验证失败
|
||||
- **问题**: API请求返回403错误
|
||||
- **原因**: 用户角色不是admin或manager
|
||||
- **解决**: 确认用户角色配置和权限分配
|
||||
|
||||
**章节来源**
|
||||
- [security.py](file://backend/app/core/security.py#L94-L109)
|
||||
- [menus.py](file://backend/app/api/v1/menus.py#L98-L164)
|
||||
|
||||
## 结论
|
||||
|
||||
系统菜单表设计合理，实现了完整的菜单管理功能。通过清晰的分层架构、完善的权限控制和良好的扩展性，为医院绩效考核管理系统提供了可靠的导航基础。
|
||||
|
||||
关键优势包括：
|
||||
- **灵活的树形结构**: 支持任意层级的菜单组织
|
||||
- **细粒度权限控制**: 通过权限标识实现精确的访问控制
|
||||
- **前后端协同**: 前端提供直观的操作界面，后端保证数据一致性
|
||||
- **可扩展性**: 易于添加新的菜单类型和权限规则
|
||||
|
||||
建议在生产环境中重点关注数据库性能优化和权限配置的安全性，确保系统的稳定运行。
|
||||
388
.qoder/repowiki/zh/content/数据库设计/表结构设计/配置管理表/绩效计划表.md
Normal file
388
.qoder/repowiki/zh/content/数据库设计/表结构设计/配置管理表/绩效计划表.md
Normal file
@@ -0,0 +1,388 @@
|
||||
# 绩效计划表
|
||||
|
||||
<cite>
|
||||
**本文档引用的文件**
|
||||
- [models.py](file://backend/app/models/models.py)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py)
|
||||
- [performance_plans.py](file://backend/app/api/v1/performance_plans.py)
|
||||
- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py)
|
||||
- [performance_plan.js](file://frontend/src/api/performance_plan.js)
|
||||
- [Plans.vue](file://frontend/src/views/plan/Plans.vue)
|
||||
- [create_plan_tables.py](file://backend/create_plan_tables.py)
|
||||
- [详细设计.md](file://docs/详细设计.md)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考虑](#性能考虑)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
本文件面向“绩效计划表”(performance_plans)的完整设计与实现，涵盖字段定义、层级设计理念、状态流转机制、审批流程、版本控制与激活管理、以及与科室、员工、用户的关联关系。同时提供创建、审批、执行的最佳实践与流程规范，帮助读者快速理解并正确使用该模块。
|
||||
|
||||
## 项目结构
|
||||
后端采用分层架构：
|
||||
- 数据模型层：定义实体与关系
|
||||
- 模式层：定义请求/响应数据结构
|
||||
- API 层：暴露 REST 接口
|
||||
- 服务层：封装业务逻辑
|
||||
- 前端：调用 API 并呈现交互
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "前端"
|
||||
FE_API["performance_plan.js<br/>前端API封装"]
|
||||
FE_VIEW["Plans.vue<br/>计划管理视图"]
|
||||
end
|
||||
subgraph "后端"
|
||||
API["performance_plans.py<br/>API路由"]
|
||||
SVC["performance_plan_service.py<br/>服务层"]
|
||||
MODELS["models.py<br/>数据模型"]
|
||||
SCHEMAS["schemas.py<br/>数据模式"]
|
||||
end
|
||||
FE_API --> API
|
||||
FE_VIEW --> FE_API
|
||||
API --> SVC
|
||||
SVC --> MODELS
|
||||
API --> SCHEMAS
|
||||
SVC --> SCHEMAS
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [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-L338)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L519-L570)
|
||||
- [performance_plan.js](file://frontend/src/api/performance_plan.js#L1-L67)
|
||||
- [Plans.vue](file://frontend/src/views/plan/Plans.vue#L1-L742)
|
||||
|
||||
章节来源
|
||||
- [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-L338)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L519-L570)
|
||||
- [performance_plan.js](file://frontend/src/api/performance_plan.js#L1-L67)
|
||||
- [Plans.vue](file://frontend/src/views/plan/Plans.vue#L1-L742)
|
||||
|
||||
## 核心组件
|
||||
- 绩效计划表：存储计划基本信息、层级、年度/月份、状态、审批信息、版本与激活状态等
|
||||
- 计划指标关联表：将计划与指标绑定，记录目标值、权重、评分方法与参数
|
||||
- 相关枚举：计划层级、计划状态、用户、科室类型等
|
||||
- API/服务：提供 CRUD、提交、审批、激活、树形结构、统计等能力
|
||||
- 前端：提供列表、树形、统计卡片、表单编辑与操作按钮
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L270-L338)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L519-L570)
|
||||
- [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)
|
||||
- [performance_plan.js](file://frontend/src/api/performance_plan.js#L1-L67)
|
||||
- [Plans.vue](file://frontend/src/views/plan/Plans.vue#L1-L742)
|
||||
|
||||
## 架构总览
|
||||
系统围绕“计划-指标-执行-结果”的闭环展开，前端通过 API 进行交互，后端服务层负责状态机与业务规则，模型层映射到数据库表。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant U as "用户"
|
||||
participant FE as "前端"
|
||||
participant API as "API路由"
|
||||
participant SVC as "服务层"
|
||||
participant DB as "数据库"
|
||||
U->>FE : 打开计划管理页面
|
||||
FE->>API : GET /plans 列表查询
|
||||
API->>SVC : get_list()
|
||||
SVC->>DB : 查询计划+关联
|
||||
DB-->>SVC : 计划列表
|
||||
SVC-->>API : 返回数据
|
||||
API-->>FE : 渲染列表
|
||||
U->>FE : 新建/编辑计划
|
||||
FE->>API : POST/PUT /plans
|
||||
API->>SVC : create/update
|
||||
SVC->>DB : 写入计划/更新
|
||||
DB-->>SVC : 提交成功
|
||||
SVC-->>API : 返回结果
|
||||
API-->>FE : 成功提示
|
||||
U->>FE : 提交/审批/激活
|
||||
FE->>API : POST /{id}/submit | approve | activate
|
||||
API->>SVC : submit/approve/activate
|
||||
SVC->>DB : 更新状态/时间/审批人
|
||||
DB-->>SVC : 提交成功
|
||||
SVC-->>API : 返回结果
|
||||
API-->>FE : 成功提示
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [performance_plans.py](file://backend/app/api/v1/performance_plans.py#L161-L241)
|
||||
- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L131-L182)
|
||||
- [performance_plan.js](file://frontend/src/api/performance_plan.js#L24-L46)
|
||||
- [Plans.vue](file://frontend/src/views/plan/Plans.vue#L567-L608)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 数据模型与字段定义
|
||||
- 绩效计划表字段
|
||||
- 计划名称、编码、层级(hospital/department/individual)、年度、月份(月度计划可选)、计划类型(annual/monthly)
|
||||
- 所属科室、责任人、上级计划(父子关系)
|
||||
- 描述、战略目标、关键举措
|
||||
- 状态(draft/pending/approved/rejected/active/completed/cancelled)
|
||||
- 提交人、提交时间、审批人、审批时间、审批意见
|
||||
- 版本号、激活状态、创建/更新时间
|
||||
- 计划指标关联表字段
|
||||
- 计划ID、指标ID、目标值、目标单位、权重、评分方法、评分参数(JSON)、备注
|
||||
- 关联关系
|
||||
- 计划与科室、员工、用户(提交人/审批人)的多对一
|
||||
- 计划与指标的多对多(通过关联表)
|
||||
- 计划的父子层级(自关联)
|
||||
|
||||
```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 description
|
||||
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 ||--o{ PERFORMANCE_PLANS : "所属科室"
|
||||
STAFF ||--o{ PERFORMANCE_PLANS : "责任人"
|
||||
USERS ||--o{ PERFORMANCE_PLANS : "提交人/审批人"
|
||||
PERFORMANCE_PLANS ||--o{ PLAN_KPI_RELATIONS : "包含"
|
||||
INDICATORS ||--o{ PLAN_KPI_RELATIONS : "关联指标"
|
||||
PERFORMANCE_PLANS ||--o{ PERFORMANCE_PLANS : "父子层级"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [models.py](file://backend/app/models/models.py#L270-L338)
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L270-L338)
|
||||
|
||||
### 计划层级设计理念与使用场景
|
||||
- 医院级：由院领导制定年度战略目标与关键举措，作为全院计划的顶层目标
|
||||
- 科室级：各科室依据医院级计划分解为本科室的KPI与目标值，形成可执行的中期计划
|
||||
- 个人级：员工依据科室计划制定个人绩效计划，承接关键举措与目标
|
||||
- 层级关系：支持父子计划，便于逐级分解与汇总
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L263-L268)
|
||||
- [详细设计.md](file://docs/详细设计.md#L59-L67)
|
||||
|
||||
### 计划状态管理与流转机制
|
||||
状态机如下：
|
||||
- 草稿(draft) → 待审批(pending)：提交
|
||||
- 待审批(pending) → 已批准(approved)/已驳回(rejected)：审批
|
||||
- 已批准(approved) → 执行中(active)：激活
|
||||
- 执行中(active) → 已完成(completed)/已取消(cancelled)：根据业务需要变更
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> 草稿
|
||||
草稿 --> 待审批 : "提交"
|
||||
待审批 --> 已批准 : "审批通过"
|
||||
待审批 --> 已驳回 : "审批驳回"
|
||||
已批准 --> 执行中 : "激活"
|
||||
执行中 --> 已完成 : "计划完成"
|
||||
执行中 --> 已取消 : "计划取消"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [models.py](file://backend/app/models/models.py#L233-L241)
|
||||
- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L131-L182)
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L233-L241)
|
||||
- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L131-L182)
|
||||
|
||||
### 计划与科室、员工、用户的关联关系
|
||||
- 所属科室：通过外键关联科室表，支持层级树形展示
|
||||
- 责任人：通过外键关联员工表，体现计划执行主体
|
||||
- 提交人/审批人：通过外键关联用户表，记录流程责任人
|
||||
- 计划指标：通过关联表与指标表建立多对多关系，支持权重与评分参数配置
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L299-L304)
|
||||
- [models.py](file://backend/app/models/models.py#L314-L338)
|
||||
|
||||
### 计划审批流程、版本控制与激活管理
|
||||
- 审批流程
|
||||
- 提交：将状态从草稿转为待审批，并记录提交时间
|
||||
- 审批：仅允许处于待审批状态的计划进行审批，通过则进入已批准，否则进入已驳回
|
||||
- 激活：仅已批准的计划可激活，进入执行中并标记为启用
|
||||
- 版本控制
|
||||
- 计划表包含版本号字段，支持后续扩展为版本分支/历史版本追踪
|
||||
- 激活状态管理
|
||||
- is_active 字段与状态共同决定计划是否处于执行中
|
||||
|
||||
章节来源
|
||||
- [performance_plans.py](file://backend/app/api/v1/performance_plans.py#L194-L241)
|
||||
- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L131-L182)
|
||||
- [models.py](file://backend/app/models/models.py#L293-L294)
|
||||
|
||||
### 前端交互与最佳实践
|
||||
- 列表与树形：支持按层级、年度、状态筛选，树形结构展示父子关系
|
||||
- 统计卡片：直观展示各状态数量，便于管理层监控
|
||||
- 表单编辑：支持计划层级、年度/月份、所属科室、责任人、上级计划、KPI关联等
|
||||
- 最佳实践
|
||||
- 新建计划时先完善KPI关联，再提交审批
|
||||
- 审批前确保KPI权重与目标值合理，避免反复退回
|
||||
- 激活前完成所有前置准备（如指标模板、数据源配置）
|
||||
|
||||
章节来源
|
||||
- [performance_plan.js](file://frontend/src/api/performance_plan.js#L1-L67)
|
||||
- [Plans.vue](file://frontend/src/views/plan/Plans.vue#L1-L742)
|
||||
|
||||
## 依赖关系分析
|
||||
- API 依赖服务层，服务层依赖模型层与模式层
|
||||
- 前端通过 API 封装调用后端接口
|
||||
- 计划与指标通过关联表解耦，支持灵活扩展
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
FE["前端视图/接口"] --> API["API路由"]
|
||||
API --> SVC["服务层"]
|
||||
SVC --> MODELS["数据模型"]
|
||||
API --> SCHEMAS["数据模式"]
|
||||
SVC --> SCHEMAS
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [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-L338)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L519-L570)
|
||||
|
||||
章节来源
|
||||
- [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-L338)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L519-L570)
|
||||
|
||||
## 性能考虑
|
||||
- 查询优化：列表接口支持按层级、年度、状态、科室过滤，配合索引提升查询效率
|
||||
- 关联加载：详情接口按需加载科室、员工、指标关联，避免 N+1 查询
|
||||
- 分页与统计：提供分页与统计接口，降低大数据量下的前端渲染压力
|
||||
- 状态机幂等：服务层对状态转换进行边界检查，避免重复提交导致的状态错乱
|
||||
|
||||
章节来源
|
||||
- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L19-L59)
|
||||
- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L62-L73)
|
||||
|
||||
## 故障排查指南
|
||||
- 提交失败：检查计划状态是否为草稿，若非草稿则无法提交
|
||||
- 审批失败：检查计划状态是否为待审批，若非待审批则无法审批
|
||||
- 激活失败：检查计划状态是否为已批准，若非已批准则无法激活
|
||||
- 删除失败：确认计划是否存在且满足删除条件
|
||||
- 前端无数据：检查筛选条件（层级/年度/状态/科室）是否过于严格
|
||||
|
||||
章节来源
|
||||
- [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-L257)
|
||||
|
||||
## 结论
|
||||
绩效计划表模块通过清晰的层级设计、严谨的状态机与完善的审批流程，实现了从战略到执行的闭环管理。结合前端可视化与后端服务层的边界控制，能够有效支撑医院级、科室级与个人级的绩效计划制定与执行。建议在实际使用中遵循“先完善KPI、再提交审批、再激活执行”的流程，确保计划的可执行性与可追溯性。
|
||||
|
||||
## 附录
|
||||
|
||||
### 字段对照表（计划表）
|
||||
- 计划名称：字符串，必填
|
||||
- 计划编码：字符串，唯一，必填
|
||||
- 计划层级：枚举(hospital/department/individual)，必填
|
||||
- 计划年度：整数，必填
|
||||
- 计划月份：整数(月度计划可选)
|
||||
- 计划类型：字符串(annual/monthly)，默认annual
|
||||
- 所属科室ID：整数(可选)
|
||||
- 责任人ID：整数(可选)
|
||||
- 上级计划ID：整数(可选)
|
||||
- 描述：文本(可选)
|
||||
- 战略目标：文本(可选)
|
||||
- 关键举措：文本(可选)
|
||||
- 状态：枚举(draft/pending/approved/rejected/active/completed/cancelled)，默认draft
|
||||
- 提交人ID：整数(可选)
|
||||
- 提交时间：时间戳(可选)
|
||||
- 审批人ID：整数(可选)
|
||||
- 审批时间：时间戳(可选)
|
||||
- 审批意见：文本(可选)
|
||||
- 版本号：整数，默认1
|
||||
- 是否启用：布尔，默认true
|
||||
- 创建/更新时间：时间戳
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L270-L296)
|
||||
|
||||
### 字段对照表（计划指标关联表）
|
||||
- 计划ID：整数，必填
|
||||
- 指标ID：整数，必填
|
||||
- 目标值：数值(可选)
|
||||
- 目标单位：字符串(可选)
|
||||
- 权重：数值，默认1.0
|
||||
- 评分方法：字符串(可选)
|
||||
- 评分参数：JSON(可选)
|
||||
- 备注：文本(可选)
|
||||
- 创建/更新时间：时间戳
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L314-L328)
|
||||
|
||||
### API 接口一览
|
||||
- GET /plans：获取计划列表（支持层级/年度/科室/状态筛选）
|
||||
- GET /plans/tree：获取计划树形结构
|
||||
- GET /plans/stats：获取计划统计
|
||||
- GET /plans/{id}：获取计划详情（含KPI关联）
|
||||
- POST /plans：创建计划（支持KPI关联）
|
||||
- PUT /plans/{id}：更新计划
|
||||
- POST /{id}/submit：提交计划
|
||||
- POST /{id}/approve：审批计划（通过/驳回）
|
||||
- POST /{id}/activate：激活计划
|
||||
- DELETE /{id}：删除计划
|
||||
- POST /{plan_id}/kpi-relations：添加KPI关联
|
||||
- PUT /kpi-relations/{relation_id}：更新KPI关联
|
||||
- DELETE /kpi-relations/{relation_id}：删除KPI关联
|
||||
|
||||
章节来源
|
||||
- [performance_plans.py](file://backend/app/api/v1/performance_plans.py#L21-L310)
|
||||
- [performance_plan.js](file://frontend/src/api/performance_plan.js#L1-L67)
|
||||
|
||||
### 数据库初始化
|
||||
- 使用脚本创建计划相关表，确保表结构与模型一致
|
||||
|
||||
章节来源
|
||||
- [create_plan_tables.py](file://backend/create_plan_tables.py#L1-L20)
|
||||
418
.qoder/repowiki/zh/content/数据库设计/表结构设计/配置管理表/考核指标模板表.md
Normal file
418
.qoder/repowiki/zh/content/数据库设计/表结构设计/配置管理表/考核指标模板表.md
Normal file
@@ -0,0 +1,418 @@
|
||||
# 考核指标模板表
|
||||
|
||||
<cite>
|
||||
**本文档引用的文件**
|
||||
- [models.py](file://backend/app/models/models.py)
|
||||
- [002_template.py](file://backend/alembic/versions/002_template.py)
|
||||
- [init_templates.py](file://backend/app/scripts/init_templates.py)
|
||||
- [init_indicator_templates.py](file://backend/init_indicator_templates.py)
|
||||
- [templates.py](file://backend/app/api/v1/templates.py)
|
||||
- [template_service.py](file://backend/app/services/template_service.py)
|
||||
- [Templates.vue](file://frontend/src/views/basic/Templates.vue)
|
||||
- [template.js](file://frontend/src/api/template.js)
|
||||
- [database.md](file://docs/database.md)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构概览](#架构概览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考虑](#性能考虑)
|
||||
8. [故障排除指南](#故障排除指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
本文件详细说明考核指标模板表（indicator_templates）的设计与实现，涵盖模板表的完整字段定义、模板类型设计理念与适用场景、维度权重配置、模板激活状态管理、模板与指标的关联关系以及模板指标关联表的作用。同时提供模板创建、版本管理、模板应用的最佳实践和使用指南，并给出模板设计、维护、应用的规范和注意事项。
|
||||
|
||||
## 项目结构
|
||||
本项目采用前后端分离架构，后端使用FastAPI + SQLAlchemy，前端使用Vue.js + Element Plus。模板功能涉及以下关键文件：
|
||||
- 数据模型：定义模板表、指标表、模板指标关联表及其关系
|
||||
- 迁移脚本：创建模板表及关联字段
|
||||
- 初始化脚本：提供预设模板数据
|
||||
- API路由：提供模板的增删改查接口
|
||||
- 服务层：封装模板业务逻辑
|
||||
- 前端页面：提供模板管理界面
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "后端"
|
||||
Models["models.py<br/>数据模型"]
|
||||
Migration["002_template.py<br/>数据库迁移"]
|
||||
InitScript["init_templates.py<br/>模板初始化脚本"]
|
||||
APITemplates["templates.py<br/>模板API路由"]
|
||||
Service["template_service.py<br/>模板服务层"]
|
||||
end
|
||||
subgraph "前端"
|
||||
View["Templates.vue<br/>模板管理视图"]
|
||||
API["template.js<br/>前端API封装"]
|
||||
end
|
||||
Models --> Migration
|
||||
Models --> APITemplates
|
||||
APITemplates --> Service
|
||||
Service --> Models
|
||||
View --> API
|
||||
API --> APITemplates
|
||||
InitScript --> Models
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [models.py](file://backend/app/models/models.py#L387-L438)
|
||||
- [002_template.py](file://backend/alembic/versions/002_template.py#L21-L96)
|
||||
- [init_templates.py](file://backend/app/scripts/init_templates.py#L189-L276)
|
||||
- [templates.py](file://backend/app/api/v1/templates.py#L1-L272)
|
||||
- [template_service.py](file://backend/app/services/template_service.py#L20-L293)
|
||||
- [Templates.vue](file://frontend/src/views/basic/Templates.vue#L1-L638)
|
||||
- [template.js](file://frontend/src/api/template.js#L1-L62)
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L387-L438)
|
||||
- [002_template.py](file://backend/alembic/versions/002_template.py#L21-L96)
|
||||
- [init_templates.py](file://backend/app/scripts/init_templates.py#L189-L276)
|
||||
- [templates.py](file://backend/app/api/v1/templates.py#L1-L272)
|
||||
- [template_service.py](file://backend/app/services/template_service.py#L20-L293)
|
||||
- [Templates.vue](file://frontend/src/views/basic/Templates.vue#L1-L638)
|
||||
- [template.js](file://frontend/src/api/template.js#L1-L62)
|
||||
|
||||
## 核心组件
|
||||
本节详细说明模板表的字段定义、模板类型、维度权重配置、激活状态管理，以及模板与指标的关联关系。
|
||||
|
||||
### 模板表字段定义
|
||||
- id：主键，自增整数
|
||||
- template_name：模板名称，字符串，必填
|
||||
- template_code：模板编码，字符串，唯一且必填
|
||||
- template_type：模板类型，枚举，必填
|
||||
- description：模板描述，文本，可选
|
||||
- dimension_weights：维度权重，JSON文本，可选
|
||||
- assessment_cycle：考核周期，字符串，默认"monthly"
|
||||
- is_active：是否启用，布尔，默认True
|
||||
- created_at：创建时间，日期时间
|
||||
- updated_at：更新时间，日期时间
|
||||
|
||||
索引：
|
||||
- idx_template_type：按模板类型索引
|
||||
- idx_template_active：按启用状态索引
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L387-L408)
|
||||
|
||||
### 模板类型与适用场景
|
||||
模板类型枚举包括：
|
||||
- general：通用模板，适用于全院各科室
|
||||
- surgical：手术临床科室，适用于外科、妇科、眼科等手术科室
|
||||
- nonsurgical_ward：非手术有病房科室
|
||||
- nonsurgical_noward：非手术无病房科室
|
||||
- medical_tech：医技科室，如检验科、放射科、超声科、药剂科等
|
||||
- nursing：护理单元
|
||||
- admin：行政科室
|
||||
- logistics：后勤科室
|
||||
|
||||
每种模板类型对应不同的权重分配和指标组合，确保考核内容与科室职责相匹配。
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L375-L385)
|
||||
- [init_templates.py](file://backend/app/scripts/init_templates.py#L82-L186)
|
||||
|
||||
### 维度权重配置
|
||||
维度权重用于平衡计分卡的四个维度：
|
||||
- financial：财务管理，范围30%-40%
|
||||
- customer：顾客服务，范围25%-35%
|
||||
- internal_process：内部流程，范围20%-30%
|
||||
- learning_growth：学习与成长，范围5%-15%
|
||||
|
||||
权重以JSON格式存储在dimension_weights字段中，便于前端展示和用户调整。
|
||||
|
||||
**章节来源**
|
||||
- [templates.py](file://backend/app/api/v1/templates.py#L63-L74)
|
||||
- [init_templates.py](file://backend/app/scripts/init_templates.py#L88-L186)
|
||||
|
||||
### 激活状态管理
|
||||
- is_active字段控制模板的启用状态
|
||||
- 前端提供开关控件，支持一键启用/停用
|
||||
- 后端API提供状态更新接口
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L398-L398)
|
||||
- [Templates.vue](file://frontend/src/views/basic/Templates.vue#L25-L28)
|
||||
- [templates.py](file://backend/app/api/v1/templates.py#L459-L462)
|
||||
|
||||
### 模板与指标的关联关系
|
||||
模板通过模板指标关联表（template_indicators）与指标建立多对多关系：
|
||||
- template_id：外键指向模板表
|
||||
- indicator_id：外键指向指标表
|
||||
- category：指标分类（二级指标）
|
||||
- target_value/target_unit：目标值及单位
|
||||
- weight：指标权重
|
||||
- scoring_method/scoring_params：评分方法及参数
|
||||
- sort_order：排序
|
||||
- remark：备注
|
||||
|
||||
关联表提供灵活的指标组合能力，支持不同模板包含不同指标及其权重。
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L411-L438)
|
||||
- [init_templates.py](file://backend/app/scripts/init_templates.py#L90-L186)
|
||||
|
||||
## 架构概览
|
||||
模板系统的整体架构由数据模型、API路由、服务层和前端界面组成，形成完整的CRUD闭环。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant User as "用户"
|
||||
participant Frontend as "前端界面"
|
||||
participant API as "模板API"
|
||||
participant Service as "模板服务"
|
||||
participant DB as "数据库"
|
||||
User->>Frontend : 访问模板管理页面
|
||||
Frontend->>API : GET /templates
|
||||
API->>Service : 查询模板列表
|
||||
Service->>DB : 查询模板数据
|
||||
DB-->>Service : 返回模板列表
|
||||
Service-->>API : 返回模板数据
|
||||
API-->>Frontend : 渲染模板列表
|
||||
User->>Frontend : 新增模板
|
||||
Frontend->>API : POST /templates
|
||||
API->>Service : 创建模板
|
||||
Service->>DB : 插入模板记录
|
||||
DB-->>Service : 返回模板ID
|
||||
Service-->>API : 返回创建结果
|
||||
API-->>Frontend : 显示成功消息
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [templates.py](file://backend/app/api/v1/templates.py#L22-L42)
|
||||
- [template_service.py](file://backend/app/services/template_service.py#L92-L128)
|
||||
- [Templates.vue](file://frontend/src/views/basic/Templates.vue#L356-L369)
|
||||
|
||||
**章节来源**
|
||||
- [templates.py](file://backend/app/api/v1/templates.py#L1-L272)
|
||||
- [template_service.py](file://backend/app/services/template_service.py#L20-L293)
|
||||
- [Templates.vue](file://frontend/src/views/basic/Templates.vue#L1-L638)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 数据模型类图
|
||||
```mermaid
|
||||
classDiagram
|
||||
class IndicatorTemplate {
|
||||
+int id
|
||||
+string template_name
|
||||
+string template_code
|
||||
+TemplateType template_type
|
||||
+string description
|
||||
+string dimension_weights
|
||||
+string assessment_cycle
|
||||
+boolean is_active
|
||||
+datetime created_at
|
||||
+datetime updated_at
|
||||
+TemplateIndicator[] indicators
|
||||
}
|
||||
class TemplateIndicator {
|
||||
+int id
|
||||
+int template_id
|
||||
+int indicator_id
|
||||
+string category
|
||||
+float target_value
|
||||
+string target_unit
|
||||
+float weight
|
||||
+string scoring_method
|
||||
+string scoring_params
|
||||
+int sort_order
|
||||
+string remark
|
||||
+datetime created_at
|
||||
+datetime updated_at
|
||||
+IndicatorTemplate template
|
||||
+Indicator indicator
|
||||
}
|
||||
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
|
||||
+boolean is_veto
|
||||
+boolean is_active
|
||||
+datetime created_at
|
||||
+datetime updated_at
|
||||
+AssessmentDetail[] assessment_details
|
||||
+TemplateIndicator[] template_relations
|
||||
}
|
||||
IndicatorTemplate "1" --> "many" TemplateIndicator : "包含"
|
||||
TemplateIndicator "many" --> "1" Indicator : "关联"
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [models.py](file://backend/app/models/models.py#L387-L438)
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L387-L438)
|
||||
|
||||
### 模板创建流程
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([开始创建模板]) --> Validate["验证模板编码唯一性"]
|
||||
Validate --> Valid{"编码有效?"}
|
||||
Valid --> |否| Error["返回错误：编码已存在"]
|
||||
Valid --> |是| CreateTemplate["创建模板记录"]
|
||||
CreateTemplate --> AddIndicators["批量添加模板指标"]
|
||||
AddIndicators --> SetSortOrder["设置排序序号"]
|
||||
SetSortOrder --> Commit["提交事务"]
|
||||
Commit --> Success["创建成功"]
|
||||
Error --> End([结束])
|
||||
Success --> End
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [templates.py](file://backend/app/api/v1/templates.py#L129-L143)
|
||||
- [template_service.py](file://backend/app/services/template_service.py#L92-L128)
|
||||
|
||||
**章节来源**
|
||||
- [templates.py](file://backend/app/api/v1/templates.py#L129-L143)
|
||||
- [template_service.py](file://backend/app/services/template_service.py#L92-L128)
|
||||
|
||||
### 模板指标管理流程
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([模板指标管理]) --> LoadTemplate["加载模板详情"]
|
||||
LoadTemplate --> ShowIndicators["显示模板指标列表"]
|
||||
ShowIndicators --> AddIndicator["添加指标"]
|
||||
ShowIndicators --> EditIndicator["编辑指标"]
|
||||
ShowIndicators --> RemoveIndicator["移除指标"]
|
||||
AddIndicator --> CheckExists["检查指标是否已存在"]
|
||||
CheckExists --> Exists{"已存在?"}
|
||||
Exists --> |是| ShowError["显示错误：指标已存在"]
|
||||
Exists --> |否| InsertIndicator["插入新指标记录"]
|
||||
InsertIndicator --> RefreshTemplate["刷新模板详情"]
|
||||
EditIndicator --> UpdateIndicator["更新指标记录"]
|
||||
UpdateIndicator --> RefreshTemplate
|
||||
RemoveIndicator --> DeleteIndicator["删除指标记录"]
|
||||
DeleteIndicator --> RefreshTemplate
|
||||
RefreshTemplate --> ShowIndicators
|
||||
ShowError --> ShowIndicators
|
||||
RefreshTemplate --> End([结束])
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [templates.py](file://backend/app/api/v1/templates.py#L174-L272)
|
||||
- [template_service.py](file://backend/app/services/template_service.py#L160-L253)
|
||||
|
||||
**章节来源**
|
||||
- [templates.py](file://backend/app/api/v1/templates.py#L174-L272)
|
||||
- [template_service.py](file://backend/app/services/template_service.py#L160-L253)
|
||||
|
||||
### 前端交互流程
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant User as "用户"
|
||||
participant View as "Templates.vue"
|
||||
participant API as "template.js"
|
||||
participant Backend as "模板API"
|
||||
User->>View : 点击"新增模板"
|
||||
View->>API : 调用createTemplate()
|
||||
API->>Backend : POST /templates
|
||||
Backend-->>API : 返回创建结果
|
||||
API-->>View : 显示成功消息
|
||||
View->>View : 刷新模板列表
|
||||
User->>View : 点击"添加指标"
|
||||
View->>API : 调用addTemplateIndicator()
|
||||
API->>Backend : POST /templates/{id}/indicators
|
||||
Backend-->>API : 返回添加结果
|
||||
API-->>View : 显示成功消息
|
||||
View->>View : 刷新指标列表
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [Templates.vue](file://frontend/src/views/basic/Templates.vue#L402-L491)
|
||||
- [template.js](file://frontend/src/api/template.js#L23-L56)
|
||||
|
||||
**章节来源**
|
||||
- [Templates.vue](file://frontend/src/views/basic/Templates.vue#L1-L638)
|
||||
- [template.js](file://frontend/src/api/template.js#L1-L62)
|
||||
|
||||
## 依赖关系分析
|
||||
模板系统的关键依赖关系如下：
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "数据层"
|
||||
IndicatorModel["Indicator模型"]
|
||||
TemplateModel["IndicatorTemplate模型"]
|
||||
TemplateIndicatorModel["TemplateIndicator模型"]
|
||||
end
|
||||
subgraph "服务层"
|
||||
TemplateService["TemplateService"]
|
||||
end
|
||||
subgraph "接口层"
|
||||
TemplateAPI["Template API路由"]
|
||||
end
|
||||
subgraph "前端"
|
||||
TemplatesView["Templates.vue"]
|
||||
TemplateAPIJS["template.js"]
|
||||
end
|
||||
TemplateAPI --> TemplateService
|
||||
TemplateService --> TemplateModel
|
||||
TemplateService --> TemplateIndicatorModel
|
||||
TemplateService --> IndicatorModel
|
||||
TemplatesView --> TemplateAPIJS
|
||||
TemplateAPIJS --> TemplateAPI
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [models.py](file://backend/app/models/models.py#L117-L438)
|
||||
- [template_service.py](file://backend/app/services/template_service.py#L10-L17)
|
||||
- [templates.py](file://backend/app/api/v1/templates.py#L1-L18)
|
||||
- [Templates.vue](file://frontend/src/views/basic/Templates.vue#L236-L244)
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L117-L438)
|
||||
- [template_service.py](file://backend/app/services/template_service.py#L10-L17)
|
||||
- [templates.py](file://backend/app/api/v1/templates.py#L1-L18)
|
||||
- [Templates.vue](file://frontend/src/views/basic/Templates.vue#L236-L244)
|
||||
|
||||
## 性能考虑
|
||||
- 数据库索引：模板表按模板类型和启用状态建立索引，提升查询性能
|
||||
- 关联查询：使用selectinload优化N+1查询问题
|
||||
- 分页查询：API支持分页参数，避免一次性加载大量数据
|
||||
- JSON存储：维度权重以JSON格式存储，便于前端直接解析使用
|
||||
|
||||
## 故障排除指南
|
||||
常见问题及解决方案：
|
||||
- 模板编码重复：创建模板时检查编码唯一性，避免重复
|
||||
- 指标重复添加：添加指标前检查是否已存在于模板中
|
||||
- 权重配置错误：前端提供权重范围校验，确保数值在合理范围内
|
||||
- 数据迁移问题：使用Alembic进行数据库版本管理，确保表结构一致
|
||||
|
||||
**章节来源**
|
||||
- [templates.py](file://backend/app/api/v1/templates.py#L136-L142)
|
||||
- [template_service.py](file://backend/app/services/template_service.py#L174-L182)
|
||||
|
||||
## 结论
|
||||
考核指标模板表通过清晰的数据模型设计、完善的API接口、友好的前端界面，实现了灵活的模板管理和指标配置能力。系统支持多种模板类型、维度权重配置、指标组合管理等功能，能够满足不同科室的考核需求。建议在实际使用中遵循最佳实践，定期维护模板数据，确保考核体系的有效性和准确性。
|
||||
|
||||
## 附录
|
||||
|
||||
### 模板初始化数据
|
||||
系统提供了预设的模板数据，包括通用模板和各类科室专用模板，涵盖平衡计分卡的四个维度和相应的指标组合。
|
||||
|
||||
**章节来源**
|
||||
- [init_templates.py](file://backend/app/scripts/init_templates.py#L82-L186)
|
||||
- [init_indicator_templates.py](file://backend/init_indicator_templates.py#L11-L371)
|
||||
|
||||
### 数据库迁移
|
||||
使用Alembic进行数据库版本管理，确保模板表结构的一致性和可追溯性。
|
||||
|
||||
**章节来源**
|
||||
- [002_template.py](file://backend/alembic/versions/002_template.py#L21-L96)
|
||||
- [database.md](file://docs/database.md#L272-L286)
|
||||
421
.qoder/repowiki/zh/content/数据库设计/表结构设计/配置管理表/考核指标表.md
Normal file
421
.qoder/repowiki/zh/content/数据库设计/表结构设计/配置管理表/考核指标表.md
Normal file
@@ -0,0 +1,421 @@
|
||||
# 考核指标表
|
||||
|
||||
<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)
|
||||
- [init_indicator_templates.py](file://backend/init_indicator_templates.py)
|
||||
- [migrate_indicators.py](file://backend/migrate_indicators.py)
|
||||
- [Indicators.vue](file://frontend/src/views/basic/Indicators.vue)
|
||||
- [indicator.js](file://frontend/src/api/indicator.js)
|
||||
- [stats_service.py](file://backend/app/services/stats_service.py)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构概览](#架构概览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考虑](#性能考虑)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
本文件面向“考核指标表（indicators）”的完整文档化需求，涵盖字段定义、枚举类型、业务规则（计算方法、考核方法、扣分标准）、适用科室类型配置、一票否决机制、激活状态管理，以及创建/修改/删除的最佳实践与数据验证规则。文档同时结合后端模型、服务层、API 层与前端界面，形成从数据模型到用户界面的闭环说明。
|
||||
|
||||
## 项目结构
|
||||
- 后端采用 FastAPI + SQLAlchemy 异步 ORM，指标模型位于数据模型层，API 路由与服务层分别提供查询、创建、更新、删除能力，并支持模板导入。
|
||||
- 前端提供指标列表展示、搜索筛选、新增/编辑/删除、状态切换等交互。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
FE["前端界面<br/>Indicators.vue"] --> API["API 路由<br/>indicators.py"]
|
||||
API --> SVC["服务层<br/>indicator_service.py"]
|
||||
SVC --> DB["数据库模型<br/>models.py 中的 Indicator 表"]
|
||||
FE --> APIClient["API 客户端<br/>indicator.js"]
|
||||
DB --> Alembic["迁移脚本<br/>migrate_indicators.py / 001_initial.py"]
|
||||
DB --> Templates["模板初始化<br/>init_indicator_templates.py"]
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [indicators.py](file://backend/app/api/v1/indicators.py#L1-L142)
|
||||
- [indicator_service.py](file://backend/app/services/indicator_service.py#L1-L197)
|
||||
- [models.py](file://backend/app/models/models.py#L117-L146)
|
||||
- [Indicators.vue](file://frontend/src/views/basic/Indicators.vue#L1-L296)
|
||||
- [indicator.js](file://frontend/src/api/indicator.js#L1-L32)
|
||||
- [migrate_indicators.py](file://backend/migrate_indicators.py#L1-L46)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L66-L85)
|
||||
- [init_indicator_templates.py](file://backend/init_indicator_templates.py#L1-L375)
|
||||
|
||||
章节来源
|
||||
- [indicators.py](file://backend/app/api/v1/indicators.py#L1-L142)
|
||||
- [indicator_service.py](file://backend/app/services/indicator_service.py#L1-L197)
|
||||
- [models.py](file://backend/app/models/models.py#L117-L146)
|
||||
- [Indicators.vue](file://frontend/src/views/basic/Indicators.vue#L1-L296)
|
||||
- [indicator.js](file://frontend/src/api/indicator.js#L1-L32)
|
||||
- [migrate_indicators.py](file://backend/migrate_indicators.py#L1-L46)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L66-L85)
|
||||
- [init_indicator_templates.py](file://backend/init_indicator_templates.py#L1-L375)
|
||||
|
||||
## 核心组件
|
||||
- 指标实体（Indicator）：承载指标的全部元数据与业务规则字段。
|
||||
- 枚举类型：
|
||||
- 指标类型（IndicatorType）：质量、数量、效率、服务、成本。
|
||||
- 平衡计分卡维度（BSCDimension）：财务、客户、内部流程、学习与成长。
|
||||
- 科室类型（DeptType）：用于限制指标适用范围。
|
||||
- API 层：提供列表、详情、创建、更新、删除、模板导入等接口。
|
||||
- 服务层：封装查询、创建、更新、删除、模板导入逻辑。
|
||||
- 前端界面：提供指标列表、搜索、新增/编辑/删除、状态切换。
|
||||
|
||||
章节来源
|
||||
- [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#L16-L27)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L39-L44)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L12-L22)
|
||||
|
||||
## 架构概览
|
||||
指标系统围绕“指标模型 + API + 服务 + 前端”的分层架构运行，支持通过模板批量导入指标，支持按科室类型过滤适用指标，支持一票否决与激活状态控制。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant U as "用户"
|
||||
participant FE as "前端界面"
|
||||
participant API as "API 路由"
|
||||
participant SVC as "服务层"
|
||||
participant DB as "数据库模型"
|
||||
U->>FE : 打开指标页面
|
||||
FE->>API : GET /indicators?...分页/筛选
|
||||
API->>SVC : 查询指标列表
|
||||
SVC->>DB : 构造查询类型/维度/状态
|
||||
DB-->>SVC : 返回指标数据
|
||||
SVC-->>API : 返回结果
|
||||
API-->>FE : 渲染表格
|
||||
U->>FE : 新增/编辑指标
|
||||
FE->>API : POST/PUT /indicators
|
||||
API->>SVC : 创建/更新指标
|
||||
SVC->>DB : 写入/更新指标
|
||||
DB-->>SVC : 提交成功
|
||||
SVC-->>API : 返回结果
|
||||
API-->>FE : 刷新列表
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [indicators.py](file://backend/app/api/v1/indicators.py#L20-L112)
|
||||
- [indicator_service.py](file://backend/app/services/indicator_service.py#L16-L93)
|
||||
- [models.py](file://backend/app/models/models.py#L117-L146)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 指标实体与字段定义
|
||||
- 字段清单与含义
|
||||
- id：主键自增
|
||||
- name：指标名称（必填）
|
||||
- code：指标编码（唯一、必填）
|
||||
- indicator_type：指标类型（必填，枚举）
|
||||
- bs_dimension：平衡计分卡维度（必填，枚举）
|
||||
- weight：权重（>0，数值型）
|
||||
- max_score：最高分值（默认100）
|
||||
- target_value：目标值（可选）
|
||||
- target_unit：目标值单位（可选）
|
||||
- calculation_method：计算方法/公式（可选）
|
||||
- assessment_method：考核方法（可选）
|
||||
- deduction_standard：扣分标准（可选）
|
||||
- data_source：数据来源（可选）
|
||||
- applicable_dept_types：适用科室类型（JSON数组字符串，可选）
|
||||
- is_veto：是否一票否决（布尔）
|
||||
- is_active：是否启用（布尔，默认启用）
|
||||
- created_at/updated_at：时间戳
|
||||
|
||||
- 约束与索引
|
||||
- 唯一约束：code
|
||||
- 约束：weight > 0
|
||||
- 索引：indicator_type
|
||||
|
||||
- 关系
|
||||
- 与考核明细（AssessmentDetail）一对多
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L117-L146)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L66-L85)
|
||||
|
||||
### 枚举类型与适用场景
|
||||
- 指标类型（IndicatorType）
|
||||
- 质量（quality）：关注结果与过程质量，如病历合格率、院感达标率
|
||||
- 数量（quantity）：关注产出数量，如门诊/住院人次
|
||||
- 效率（efficiency）：关注资源利用效率，如报告及时率
|
||||
- 服务（service）：关注服务体验与满意度，如患者满意度
|
||||
- 成本（cost）：关注成本控制，如药品比例、医保扣款
|
||||
|
||||
- 平衡计分卡维度（BSCDimension）
|
||||
- 财务（financial）：收入增长、成本控制、资产效率
|
||||
- 客户（customer）：患者满意度、投诉管理、服务可及性
|
||||
- 内部流程（internal_process）：医疗质量、安全、合规、流程执行率
|
||||
- 学习与成长（learning_growth）：培训参与、继续教育、科研教学
|
||||
|
||||
- 科室类型（DeptType）
|
||||
- 临床手术、非手术有病房、非手术无病房、医技、医疗辅助、护理、行政、财务、后勤等
|
||||
|
||||
章节来源
|
||||
- [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#L16-L27)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L39-L44)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L12-L22)
|
||||
|
||||
### 业务规则与计算方法
|
||||
- 计算方法（calculation_method）：用于定义指标的实际计算公式或口径，例如“（本期收入 - 同期收入）/ 同期收入 × 100%”
|
||||
- 考核方法（assessment_method）：用于说明数据采集与评估方式，例如“统计报表”、“问卷调查”、“系统统计”
|
||||
- 扣分标准（deduction_standard）：用于明确未达标时的扣分规则，例如“每降低1%扣2分”、“每例未处理扣5分”
|
||||
|
||||
- 适用科室类型配置（applicable_dept_types）
|
||||
- 以 JSON 数组字符串形式存储，用于限制指标在特定科室类型下的生效范围
|
||||
- 模板导入时会自动写入对应科室类型的 dept_type
|
||||
|
||||
- 一票否决（is_veto）
|
||||
- 当某指标被标记为一票否决时，在考核过程中若该项未达标，将直接判定为不通过
|
||||
- 示例：院感控制达标率（示例来自模板数据）
|
||||
|
||||
- 激活状态管理（is_active）
|
||||
- 控制指标是否参与当前考核周期
|
||||
- 前端提供开关式状态变更入口
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L129-L135)
|
||||
- [init_indicator_templates.py](file://backend/init_indicator_templates.py#L22-L232)
|
||||
- [init_indicator_templates.py](file://backend/init_indicator_templates.py#L309-L362)
|
||||
- [Indicators.vue](file://frontend/src/views/basic/Indicators.vue#L31-L35)
|
||||
|
||||
### API 与服务层行为
|
||||
- 列表查询
|
||||
- 支持按指标类型、BSC 维度、是否启用进行筛选
|
||||
- 支持分页与总数统计
|
||||
- 详情查询
|
||||
- 根据 ID 获取指标详情
|
||||
- 创建/更新/删除
|
||||
- 创建前校验编码唯一性
|
||||
- 更新支持部分字段更新
|
||||
- 删除返回布尔结果
|
||||
- 模板导入
|
||||
- 支持按模板类型批量导入指标
|
||||
- 支持覆盖策略（overwrite）
|
||||
|
||||
章节来源
|
||||
- [indicators.py](file://backend/app/api/v1/indicators.py#L20-L142)
|
||||
- [indicator_service.py](file://backend/app/services/indicator_service.py#L16-L154)
|
||||
|
||||
### 前端交互与数据验证
|
||||
- 列表展示
|
||||
- 支持按指标类型筛选、关键词搜索（名称/编码）
|
||||
- 展示编码、名称、类型、权重、最高分值、目标值、单位、状态等
|
||||
- 新增/编辑
|
||||
- 必填字段：编码、名称、指标类型
|
||||
- 权重范围：≥0.1，支持一位小数
|
||||
- 最高分值范围：≥0，最大1000
|
||||
- 目标值：数值型，保留两位小数
|
||||
- 计算方法与描述：文本域输入
|
||||
- 状态切换
|
||||
- 通过开关直接更新 is_active
|
||||
|
||||
章节来源
|
||||
- [Indicators.vue](file://frontend/src/views/basic/Indicators.vue#L1-L296)
|
||||
- [indicator.js](file://frontend/src/api/indicator.js#L1-L32)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L153-L192)
|
||||
|
||||
### 模板与迁移
|
||||
- 模板初始化
|
||||
- 提供多类科室模板（手术临床、非手术有病房、非手术无病房、医技、行政、后勤等）
|
||||
- 模板中包含指标名称、编码、类型、维度、权重、目标值、计算方法、考核方法、扣分标准、数据来源、适用科室类型、是否一票否决、是否启用等
|
||||
- 迁移脚本
|
||||
- 为历史表添加 bs_dimension、target_unit、assessment_method、deduction_standard、data_source、applicable_dept_types、is_veto 等列
|
||||
|
||||
章节来源
|
||||
- [init_indicator_templates.py](file://backend/init_indicator_templates.py#L1-L375)
|
||||
- [migrate_indicators.py](file://backend/migrate_indicators.py#L1-L46)
|
||||
|
||||
## 依赖关系分析
|
||||
- 指标实体依赖枚举类型（IndicatorType、BSCDimension、DeptType）
|
||||
- API 层依赖服务层；服务层依赖模型层；模型层依赖数据库
|
||||
- 前端通过 API 客户端调用后端接口
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class Indicator {
|
||||
+int id
|
||||
+string name
|
||||
+string code
|
||||
+IndicatorType indicator_type
|
||||
+BSCDimension bs_dimension
|
||||
+float weight
|
||||
+float max_score
|
||||
+float target_value
|
||||
+string target_unit
|
||||
+string calculation_method
|
||||
+string assessment_method
|
||||
+string deduction_standard
|
||||
+string data_source
|
||||
+string applicable_dept_types
|
||||
+bool is_veto
|
||||
+bool is_active
|
||||
}
|
||||
class IndicatorService {
|
||||
+get_list(...)
|
||||
+get_by_id(...)
|
||||
+get_active_indicators(...)
|
||||
+create(...)
|
||||
+update(...)
|
||||
+delete(...)
|
||||
+import_template(...)
|
||||
+get_templates()
|
||||
}
|
||||
class API_Indicators {
|
||||
+get_indicators(...)
|
||||
+get_active_indicators(...)
|
||||
+get_indicator(...)
|
||||
+create_indicator(...)
|
||||
+update_indicator(...)
|
||||
+delete_indicator(...)
|
||||
+get_indicator_templates(...)
|
||||
+import_indicator_template(...)
|
||||
}
|
||||
API_Indicators --> IndicatorService : "调用"
|
||||
IndicatorService --> Indicator : "读写"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [models.py](file://backend/app/models/models.py#L117-L146)
|
||||
- [indicator_service.py](file://backend/app/services/indicator_service.py#L13-L197)
|
||||
- [indicators.py](file://backend/app/api/v1/indicators.py#L1-L142)
|
||||
|
||||
## 性能考虑
|
||||
- 查询优化
|
||||
- 列表查询支持按类型、维度、状态过滤，建议在高频查询上保持索引有效
|
||||
- 分页查询避免一次性加载过多数据
|
||||
- 数据一致性
|
||||
- 编码唯一性约束确保指标识别稳定
|
||||
- 权重大于0的约束保证权重语义正确
|
||||
- 模板导入
|
||||
- 批量导入时建议开启事务，减少多次往返
|
||||
- 覆盖策略需谨慎使用，避免误更新
|
||||
|
||||
[本节为通用指导，无需特定文件来源]
|
||||
|
||||
## 故障排查指南
|
||||
- 创建失败：指标编码重复
|
||||
- 现象：创建接口返回错误
|
||||
- 处理：更换唯一编码后重试
|
||||
- 更新失败：指标不存在
|
||||
- 现象：更新接口返回404
|
||||
- 处理：确认指标ID是否存在
|
||||
- 权重异常：权重≤0
|
||||
- 现象：数据库约束报错
|
||||
- 处理：调整权重至>0
|
||||
- 模板导入未生效
|
||||
- 现象：导入后指标未出现或未覆盖
|
||||
- 处理：检查 overwrite 参数、dept_type 是否匹配、数据库迁移是否完成
|
||||
|
||||
章节来源
|
||||
- [indicators.py](file://backend/app/api/v1/indicators.py#L78-L81)
|
||||
- [indicators.py](file://backend/app/api/v1/indicators.py#L95-L98)
|
||||
- [models.py](file://backend/app/models/models.py#L145)
|
||||
- [migrate_indicators.py](file://backend/migrate_indicators.py#L9-L41)
|
||||
|
||||
## 结论
|
||||
考核指标表通过清晰的字段定义、严谨的枚举约束与完善的业务规则，实现了对不同科室类型的差异化考核。配合模板导入与前端交互，能够高效地完成指标的创建、维护与应用。建议在实际使用中严格遵循数据验证规则与最佳实践，确保指标体系的稳定性与可扩展性。
|
||||
|
||||
[本节为总结性内容，无需特定文件来源]
|
||||
|
||||
## 附录
|
||||
|
||||
### 字段与规则对照表
|
||||
- 字段名：name
|
||||
- 类型：字符串
|
||||
- 必填：是
|
||||
- 用途：指标名称
|
||||
- 字段名：code
|
||||
- 类型：字符串
|
||||
- 必填：是
|
||||
- 唯一性：是
|
||||
- 用途：指标唯一标识
|
||||
- 字段名：indicator_type
|
||||
- 类型：枚举（质量/数量/效率/服务/成本）
|
||||
- 必填：是
|
||||
- 用途：区分指标类别
|
||||
- 字段名：bs_dimension
|
||||
- 类型：枚举（财务/客户/内部流程/学习与成长）
|
||||
- 必填：是
|
||||
- 用途：平衡计分卡维度归属
|
||||
- 字段名：weight
|
||||
- 类型：数值
|
||||
- 必填：是
|
||||
- 约束：>0
|
||||
- 用途：权重，影响加权得分
|
||||
- 字段名：max_score
|
||||
- 类型：数值
|
||||
- 默认值：100
|
||||
- 用途：指标最高分值
|
||||
- 字段名：target_value
|
||||
- 类型：数值
|
||||
- 可选：是
|
||||
- 用途：目标值
|
||||
- 字段名：target_unit
|
||||
- 类型：字符串
|
||||
- 可选：是
|
||||
- 用途：目标值单位
|
||||
- 字段名：calculation_method
|
||||
- 类型：文本
|
||||
- 可选：是
|
||||
- 用途：计算方法/公式
|
||||
- 字段名：assessment_method
|
||||
- 类型：文本
|
||||
- 可选：是
|
||||
- 用途：考核方法
|
||||
- 字段名：deduction_standard
|
||||
- 类型：文本
|
||||
- 可选：是
|
||||
- 用途：扣分标准
|
||||
- 字段名：data_source
|
||||
- 类型：字符串
|
||||
- 可选：是
|
||||
- 用途：数据来源
|
||||
- 字段名：applicable_dept_types
|
||||
- 类型：JSON数组字符串
|
||||
- 可选：是
|
||||
- 用途：适用科室类型
|
||||
- 字段名：is_veto
|
||||
- 类型：布尔
|
||||
- 默认值：false
|
||||
- 用途：一票否决标志
|
||||
- 字段名：is_active
|
||||
- 类型：布尔
|
||||
- 默认值：true
|
||||
- 用途：启用/禁用控制
|
||||
|
||||
章节来源
|
||||
- [models.py](file://backend/app/models/models.py#L117-L146)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L153-L192)
|
||||
|
||||
### 最佳实践与数据验证规则
|
||||
- 创建/修改
|
||||
- 编码必须唯一且必填
|
||||
- 指标类型与平衡计分卡维度必须选择
|
||||
- 权重必须大于0
|
||||
- 最高分值建议合理设置（如100），避免过大或过小
|
||||
- 目标值与单位应配套填写
|
||||
- 计算方法、考核方法、扣分标准应明确可执行
|
||||
- 适用科室类型应与模板一致，避免跨科室误用
|
||||
- 激活状态
|
||||
- 新建指标默认启用；停用时需谨慎评估影响范围
|
||||
- 一票否决
|
||||
- 仅在关键质量/安全指标上启用，避免滥用
|
||||
- 模板导入
|
||||
- 导入前确认 dept_type 与模板类型一致
|
||||
- 使用覆盖模式时注意备份与审计
|
||||
|
||||
[本节为通用指导，无需特定文件来源]
|
||||
357
.qoder/repowiki/zh/content/数据库设计/表结构设计/配置管理表/计划指标关联表.md
Normal file
357
.qoder/repowiki/zh/content/数据库设计/表结构设计/配置管理表/计划指标关联表.md
Normal file
@@ -0,0 +1,357 @@
|
||||
# 计划指标关联表
|
||||
|
||||
<cite>
|
||||
**本文档引用的文件**
|
||||
- [models.py](file://backend/app/models/models.py)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py)
|
||||
- [performance_plans.py](file://backend/app/api/v1/performance_plans.py)
|
||||
- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py)
|
||||
- [database.md](file://docs/database.md)
|
||||
- [002_template.py](file://backend/alembic/versions/002_template.py)
|
||||
- [create_plan_tables.py](file://backend/create_plan_tables.py)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构概览](#架构概览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考虑](#性能考虑)
|
||||
8. [故障排除指南](#故障排除指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
|
||||
计划指标关联表（plan_kpi_relations）是医院绩效管理系统中的核心数据表，用于建立绩效计划与考核指标之间的多对多关联关系。该表实现了计划层面的指标配置功能，支持权重分配、目标值设定、评分方法配置等关键业务需求。
|
||||
|
||||
本表采用多对多关联设计，通过外键约束确保数据完整性，支持灵活的指标组合配置，为不同层级、不同类型的绩效计划提供个性化的指标体系。
|
||||
|
||||
## 项目结构
|
||||
|
||||
基于代码库分析，计划指标关联表涉及以下核心模块：
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "后端架构"
|
||||
API[API层<br/>performance_plans.py]
|
||||
Service[服务层<br/>performance_plan_service.py]
|
||||
Model[模型层<br/>models.py]
|
||||
Schema[Schema层<br/>schemas.py]
|
||||
end
|
||||
subgraph "数据库层"
|
||||
PlanKpi[plan_kpi_relations<br/>关联表]
|
||||
PerformancePlan[performance_plans<br/>计划表]
|
||||
Indicator[indicators<br/>指标表]
|
||||
end
|
||||
subgraph "前端界面"
|
||||
PlanUI[计划管理界面]
|
||||
KPIConfig[KPI配置组件]
|
||||
end
|
||||
API --> Service
|
||||
Service --> Model
|
||||
Model --> PlanKpi
|
||||
PlanKpi --> PerformancePlan
|
||||
PlanKpi --> Indicator
|
||||
PlanUI --> API
|
||||
KPIConfig --> API
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [performance_plans.py](file://backend/app/api/v1/performance_plans.py#L260-L310)
|
||||
- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L195-L249)
|
||||
- [models.py](file://backend/app/models/models.py#L314-L338)
|
||||
|
||||
**章节来源**
|
||||
- [performance_plans.py](file://backend/app/api/v1/performance_plans.py#L260-L310)
|
||||
- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L195-L249)
|
||||
- [models.py](file://backend/app/models/models.py#L314-L338)
|
||||
|
||||
## 核心组件
|
||||
|
||||
### 数据表结构定义
|
||||
|
||||
计划指标关联表采用完整的字段定义，支持全面的业务配置需求：
|
||||
|
||||
| 字段名 | 数据类型 | 约束条件 | 说明 |
|
||||
|--------|----------|----------|------|
|
||||
| id | Integer | 主键, 自增 | 关联关系唯一标识 |
|
||||
| plan_id | Integer | 外键, 非空 | 关联的绩效计划ID |
|
||||
| indicator_id | Integer | 外键, 非空 | 关联的指标ID |
|
||||
| target_value | Numeric(10,2) | 可空 | 指标的计划目标值 |
|
||||
| target_unit | String(50) | 可空 | 目标值计量单位 |
|
||||
| weight | Numeric(5,2) | 默认1.0 | 指标权重值 |
|
||||
| scoring_method | String(50) | 可空 | 评分方法类型 |
|
||||
| scoring_params | Text | 可空 | 评分参数（JSON格式） |
|
||||
| remark | Text | 可空 | 备注说明 |
|
||||
| created_at | DateTime | 默认当前时间 | 记录创建时间 |
|
||||
| updated_at | DateTime | 默认当前时间, 更新时自动更新 | 记录最后更新时间 |
|
||||
|
||||
### 索引与约束
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
subgraph "索引设计"
|
||||
IDX1[idx_relation_plan<br/>plan_id索引]
|
||||
IDX2[idx_relation_indicator<br/>indicator_id索引]
|
||||
IDX3[idx_relation_unique<br/>plan_id+indicator_id唯一索引]
|
||||
end
|
||||
subgraph "约束设计"
|
||||
FK1[FK_performance_plans<br/>plan_id → performance_plans.id]
|
||||
FK2[FK_indicators<br/>indicator_id → indicators.id]
|
||||
CK1[CK_weight_range<br/>weight ∈ [0,100]]
|
||||
end
|
||||
IDX1 --> FK1
|
||||
IDX2 --> FK2
|
||||
IDX3 --> Unique[唯一约束]
|
||||
CK1 --> Weight[权重检查]
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [models.py](file://backend/app/models/models.py#L334-L338)
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L314-L338)
|
||||
|
||||
## 架构概览
|
||||
|
||||
系统采用分层架构设计，实现清晰的职责分离：
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as 客户端
|
||||
participant API as API接口
|
||||
participant Service as 服务层
|
||||
participant DB as 数据库
|
||||
Client->>API : 添加KPI关联请求
|
||||
API->>Service : add_kpi_relation()
|
||||
Service->>DB : 查询计划是否存在
|
||||
DB-->>Service : 计划存在
|
||||
Service->>DB : 创建PlanKpiRelation记录
|
||||
DB-->>Service : 返回新记录
|
||||
Service-->>API : 返回关联关系
|
||||
API-->>Client : 返回结果
|
||||
Note over Client,DB : 数据一致性通过外键约束保证
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [performance_plans.py](file://backend/app/api/v1/performance_plans.py#L260-L275)
|
||||
- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L195-L213)
|
||||
|
||||
**章节来源**
|
||||
- [performance_plans.py](file://backend/app/api/v1/performance_plans.py#L260-L275)
|
||||
- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L195-L213)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 数据模型设计
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class PlanKpiRelation {
|
||||
+int id
|
||||
+int plan_id
|
||||
+int indicator_id
|
||||
+float target_value
|
||||
+string target_unit
|
||||
+float weight
|
||||
+string scoring_method
|
||||
+string scoring_params
|
||||
+string remark
|
||||
+datetime created_at
|
||||
+datetime updated_at
|
||||
+plan : PerformancePlan
|
||||
+indicator : Indicator
|
||||
}
|
||||
class PerformancePlan {
|
||||
+int id
|
||||
+string plan_name
|
||||
+string plan_code
|
||||
+int plan_year
|
||||
+string plan_level
|
||||
+kpi_relations : List[PlanKpiRelation]
|
||||
}
|
||||
class Indicator {
|
||||
+int id
|
||||
+string name
|
||||
+string code
|
||||
+float weight
|
||||
+plan_relations : List[PlanKpiRelation]
|
||||
}
|
||||
PlanKpiRelation --> PerformancePlan : "多对一"
|
||||
PlanKpiRelation --> Indicator : "多对一"
|
||||
PerformancePlan --> PlanKpiRelation : "一对多"
|
||||
Indicator --> PlanKpiRelation : "一对多"
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [models.py](file://backend/app/models/models.py#L314-L332)
|
||||
|
||||
### API接口设计
|
||||
|
||||
系统提供完整的CRUD操作接口：
|
||||
|
||||
| 接口方法 | URL路径 | 功能描述 | 权限要求 |
|
||||
|----------|---------|----------|----------|
|
||||
| POST | /plans/{plan_id}/kpi-relations | 添加计划指标关联 | 管理员/经理 |
|
||||
| PUT | /plans/kpi-relations/{relation_id} | 更新计划指标关联 | 管理员/经理 |
|
||||
| DELETE | /plans/kpi-relations/{relation_id} | 删除计划指标关联 | 管理员/经理 |
|
||||
|
||||
### 业务逻辑处理
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([开始]) --> ValidatePlan["验证计划存在性"]
|
||||
ValidatePlan --> PlanExists{"计划存在?"}
|
||||
PlanExists --> |否| ReturnError["返回错误"]
|
||||
PlanExists --> |是| CreateRelation["创建关联关系"]
|
||||
CreateRelation --> SaveToDB["保存到数据库"]
|
||||
SaveToDB --> RefreshData["刷新数据"]
|
||||
RefreshData --> Success["返回成功"]
|
||||
ReturnError --> End([结束])
|
||||
Success --> End
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L195-L213)
|
||||
|
||||
**章节来源**
|
||||
- [performance_plans.py](file://backend/app/api/v1/performance_plans.py#L260-L310)
|
||||
- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L195-L249)
|
||||
|
||||
## 依赖关系分析
|
||||
|
||||
### 外部依赖
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "核心依赖"
|
||||
SQLAlchemy[SQLAlchemy ORM]
|
||||
FastAPI[FastAPI框架]
|
||||
Pydantic[Pydantic验证]
|
||||
end
|
||||
subgraph "数据库依赖"
|
||||
PostgreSQL[PostgreSQL引擎]
|
||||
Alembic[数据库迁移]
|
||||
end
|
||||
subgraph "前端依赖"
|
||||
Vue3[Vue3框架]
|
||||
ElementPlus[ElementPlus组件库]
|
||||
end
|
||||
SQLAlchemy --> Alembic
|
||||
FastAPI --> Pydantic
|
||||
Vue3 --> ElementPlus
|
||||
```
|
||||
|
||||
### 内部模块依赖
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
API --> Service
|
||||
Service --> Model
|
||||
Model --> Schema
|
||||
Model --> Database
|
||||
Service --> Database
|
||||
API --> Database
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [performance_plans.py](file://backend/app/api/v1/performance_plans.py#L1-L20)
|
||||
- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L1-L20)
|
||||
|
||||
**章节来源**
|
||||
- [performance_plans.py](file://backend/app/api/v1/performance_plans.py#L1-L20)
|
||||
- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L1-L20)
|
||||
|
||||
## 性能考虑
|
||||
|
||||
### 查询优化策略
|
||||
|
||||
1. **索引优化**
|
||||
- plan_id索引：加速按计划查询关联关系
|
||||
- indicator_id索引：加速按指标查询关联关系
|
||||
- 唯一索引：防止重复的计划-指标关联
|
||||
|
||||
2. **连接查询优化**
|
||||
- 使用selectinload优化N+1查询问题
|
||||
- 合理使用join减少查询次数
|
||||
|
||||
3. **缓存策略**
|
||||
- 对常用查询结果进行缓存
|
||||
- 利用数据库连接池提高并发性能
|
||||
|
||||
### 数据一致性保证
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> Draft : 创建关联
|
||||
Draft --> Active : 提交/激活
|
||||
Active --> Completed : 完成计划
|
||||
Active --> Cancelled : 取消关联
|
||||
Completed --> [*]
|
||||
Cancelled --> [*]
|
||||
note right of Active
|
||||
数据一致性通过
|
||||
外键约束和事务保证
|
||||
end note
|
||||
```
|
||||
|
||||
## 故障排除指南
|
||||
|
||||
### 常见问题及解决方案
|
||||
|
||||
1. **关联关系创建失败**
|
||||
- 检查计划ID是否存在
|
||||
- 验证指标ID的有效性
|
||||
- 确认唯一性约束未被违反
|
||||
|
||||
2. **更新操作异常**
|
||||
- 确认关联关系ID正确
|
||||
- 检查字段范围限制（权重0-100）
|
||||
- 验证JSON参数格式
|
||||
|
||||
3. **删除操作失败**
|
||||
- 确认关联关系存在
|
||||
- 检查是否有依赖关系
|
||||
|
||||
**章节来源**
|
||||
- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L215-L249)
|
||||
|
||||
## 结论
|
||||
|
||||
计划指标关联表作为医院绩效管理系统的核心组件，通过精心设计的数据模型和完善的业务逻辑，实现了灵活的指标配置功能。系统采用分层架构设计，确保了良好的可维护性和扩展性。
|
||||
|
||||
关键优势包括：
|
||||
- 完整的多对多关联支持
|
||||
- 灵活的权重和评分配置
|
||||
- 强大的数据一致性保证
|
||||
- 清晰的权限控制机制
|
||||
|
||||
## 附录
|
||||
|
||||
### 数据库迁移历史
|
||||
|
||||
系统通过Alembic进行数据库版本管理，支持指标模板相关字段的添加和维护。
|
||||
|
||||
**章节来源**
|
||||
- [002_template.py](file://backend/alembic/versions/002_template.py#L1-L96)
|
||||
- [create_plan_tables.py](file://backend/create_plan_tables.py#L1-L20)
|
||||
|
||||
### 最佳实践建议
|
||||
|
||||
1. **配置管理**
|
||||
- 建立标准化的指标配置流程
|
||||
- 定期审查和优化权重分配
|
||||
- 维护评分方法的一致性
|
||||
|
||||
2. **数据维护**
|
||||
- 定期清理无效的关联关系
|
||||
- 监控数据完整性
|
||||
- 建立备份和恢复机制
|
||||
|
||||
3. **性能优化**
|
||||
- 合理使用索引
|
||||
- 优化查询语句
|
||||
- 监控数据库性能指标
|
||||
700
.qoder/repowiki/zh/content/数据库设计/表结构设计/配置管理表/配置管理表.md
Normal file
700
.qoder/repowiki/zh/content/数据库设计/表结构设计/配置管理表/配置管理表.md
Normal file
@@ -0,0 +1,700 @@
|
||||
# 配置管理表
|
||||
|
||||
<cite>
|
||||
**本文档引用的文件**
|
||||
- [models.py](file://backend/app/models/models.py)
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py)
|
||||
- [002_template.py](file://backend/alembic/versions/002_template.py)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py)
|
||||
- [security.py](file://backend/app/core/security.py)
|
||||
- [indicators.py](file://backend/app/api/v1/indicators.py)
|
||||
- [performance_plans.py](file://backend/app/api/v1/performance_plans.py)
|
||||
- [menus.py](file://backend/app/api/v1/menus.py)
|
||||
- [templates.py](file://backend/app/api/v1/templates.py)
|
||||
- [indicator_service.py](file://backend/app/services/indicator_service.py)
|
||||
- [template_service.py](file://backend/app/services/template_service.py)
|
||||
- [database.py](file://backend/app/core/database.py)
|
||||
- [config.py](file://backend/app/core/config.py)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构概览](#架构概览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考虑](#性能考虑)
|
||||
8. [故障排除指南](#故障排除指南)
|
||||
9. [结论](#结论)
|
||||
|
||||
## 简介
|
||||
|
||||
本文档详细介绍了医院绩效考核管理系统的配置管理表结构，重点关注以下核心配置表：
|
||||
|
||||
- 考核指标表（indicators）
|
||||
- 系统用户表（users）
|
||||
- 绩效计划表（performance_plans）
|
||||
- 计划指标关联表（plan_kpi_relations）
|
||||
- 系统菜单表（menus）
|
||||
- 考核指标模板表（indicator_templates）
|
||||
|
||||
该系统采用现代化的后端架构，使用FastAPI框架、SQLAlchemy ORM、PostgreSQL数据库，并实现了完整的权限控制和模板化管理机制。
|
||||
|
||||
## 项目结构
|
||||
|
||||
系统采用分层架构设计，主要分为以下几个层次：
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "表现层"
|
||||
API[API路由层]
|
||||
Frontend[前端界面]
|
||||
end
|
||||
subgraph "业务逻辑层"
|
||||
Services[服务层]
|
||||
Schemas[数据模式层]
|
||||
end
|
||||
subgraph "数据访问层"
|
||||
Models[ORM模型层]
|
||||
Database[数据库层]
|
||||
end
|
||||
subgraph "基础设施层"
|
||||
Security[安全认证]
|
||||
Config[配置管理]
|
||||
end
|
||||
Frontend --> API
|
||||
API --> Services
|
||||
Services --> Models
|
||||
Models --> Database
|
||||
API --> Schemas
|
||||
Services --> Schemas
|
||||
Security --> API
|
||||
Config --> Database
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [models.py](file://backend/app/models/models.py#L1-L438)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L1-L743)
|
||||
- [security.py](file://backend/app/core/security.py#L1-L110)
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L1-L438)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L1-L743)
|
||||
- [database.py](file://backend/app/core/database.py#L1-L39)
|
||||
|
||||
## 核心组件
|
||||
|
||||
### 枚举类型系统
|
||||
|
||||
系统实现了完整的枚举类型体系，确保数据的一致性和完整性：
|
||||
|
||||
#### 指标类型枚举
|
||||
- 质量指标（quality）
|
||||
- 数量指标（quantity）
|
||||
- 效率指标（efficiency）
|
||||
- 服务指标（service）
|
||||
- 成本指标（cost）
|
||||
|
||||
#### 平衡计分卡维度
|
||||
- 财务维度（financial）
|
||||
- 客户维度（customer）
|
||||
- 内部流程维度（internal_process）
|
||||
- 学习与成长维度（learning_growth）
|
||||
|
||||
#### 用户权限级别
|
||||
- 普通员工（staff）
|
||||
- 部门经理（manager）
|
||||
- 系统管理员（admin）
|
||||
|
||||
#### 计划状态管理
|
||||
- 草稿（draft）
|
||||
- 待审批（pending）
|
||||
- 已批准（approved）
|
||||
- 已驳回（rejected）
|
||||
- 执行中（active）
|
||||
- 已完成（completed）
|
||||
- 已取消（cancelled）
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L16-L61)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L39-L44)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L24-L28)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L470-L479)
|
||||
|
||||
### 数据模型架构
|
||||
|
||||
系统采用SQLAlchemy ORM进行数据库建模，所有配置表都遵循统一的设计规范：
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class Indicator {
|
||||
+int id
|
||||
+string name
|
||||
+string code
|
||||
+IndicatorType 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
|
||||
+string applicable_dept_types
|
||||
+bool is_veto
|
||||
+bool is_active
|
||||
+datetime created_at
|
||||
+datetime updated_at
|
||||
}
|
||||
class User {
|
||||
+int id
|
||||
+string username
|
||||
+string password_hash
|
||||
+int staff_id
|
||||
+string role
|
||||
+bool is_active
|
||||
+datetime last_login
|
||||
+datetime created_at
|
||||
+datetime updated_at
|
||||
}
|
||||
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
|
||||
+datetime created_at
|
||||
+datetime updated_at
|
||||
}
|
||||
class PlanKpiRelation {
|
||||
+int id
|
||||
+int plan_id
|
||||
+int indicator_id
|
||||
+float target_value
|
||||
+string target_unit
|
||||
+float weight
|
||||
+string scoring_method
|
||||
+string scoring_params
|
||||
+string remark
|
||||
+datetime created_at
|
||||
+datetime updated_at
|
||||
}
|
||||
class Menu {
|
||||
+int id
|
||||
+int parent_id
|
||||
+MenuType menu_type
|
||||
+string menu_name
|
||||
+string menu_icon
|
||||
+string path
|
||||
+string component
|
||||
+string permission
|
||||
+int sort_order
|
||||
+bool is_visible
|
||||
+bool is_active
|
||||
+datetime created_at
|
||||
+datetime updated_at
|
||||
}
|
||||
class IndicatorTemplate {
|
||||
+int id
|
||||
+string template_name
|
||||
+string template_code
|
||||
+TemplateType template_type
|
||||
+string description
|
||||
+string dimension_weights
|
||||
+string assessment_cycle
|
||||
+bool is_active
|
||||
+datetime created_at
|
||||
+datetime updated_at
|
||||
}
|
||||
class TemplateIndicator {
|
||||
+int id
|
||||
+int template_id
|
||||
+int indicator_id
|
||||
+string category
|
||||
+float target_value
|
||||
+string target_unit
|
||||
+float weight
|
||||
+string scoring_method
|
||||
+string scoring_params
|
||||
+int sort_order
|
||||
+string remark
|
||||
+datetime created_at
|
||||
+datetime updated_at
|
||||
}
|
||||
IndicatorTemplate "1" -- "many" TemplateIndicator : "has"
|
||||
PerformancePlan "1" -- "many" PlanKpiRelation : "contains"
|
||||
Indicator "many" -- "many" PlanKpiRelation : "related_to"
|
||||
User "1" -- "many" PerformancePlan : "submits"
|
||||
Menu "1" -- "many" Menu : "parent_child"
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [models.py](file://backend/app/models/models.py#L117-L147)
|
||||
- [models.py](file://backend/app/models/models.py#L244-L261)
|
||||
- [models.py](file://backend/app/models/models.py#L270-L312)
|
||||
- [models.py](file://backend/app/models/models.py#L314-L339)
|
||||
- [models.py](file://backend/app/models/models.py#L347-L373)
|
||||
- [models.py](file://backend/app/models/models.py#L387-L409)
|
||||
- [models.py](file://backend/app/models/models.py#L411-L438)
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L117-L438)
|
||||
|
||||
## 架构概览
|
||||
|
||||
系统采用RESTful API架构，所有配置管理操作都通过标准化的HTTP接口进行：
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as "客户端"
|
||||
participant API as "API路由层"
|
||||
participant Service as "服务层"
|
||||
participant Model as "ORM模型层"
|
||||
participant DB as "数据库"
|
||||
Client->>API : HTTP请求
|
||||
API->>Service : 调用业务逻辑
|
||||
Service->>Model : 数据模型操作
|
||||
Model->>DB : SQL查询/更新
|
||||
DB-->>Model : 查询结果
|
||||
Model-->>Service : 处理后的数据
|
||||
Service-->>API : 业务结果
|
||||
API-->>Client : JSON响应
|
||||
Note over Client,DB : 完整的CRUD操作流程
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [indicators.py](file://backend/app/api/v1/indicators.py#L1-L142)
|
||||
- [performance_plans.py](file://backend/app/api/v1/performance_plans.py#L1-L310)
|
||||
- [templates.py](file://backend/app/api/v1/templates.py#L1-L272)
|
||||
|
||||
**章节来源**
|
||||
- [indicators.py](file://backend/app/api/v1/indicators.py#L1-L142)
|
||||
- [performance_plans.py](file://backend/app/api/v1/performance_plans.py#L1-L310)
|
||||
- [templates.py](file://backend/app/api/v1/templates.py#L1-L272)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 考核指标表（indicators）
|
||||
|
||||
#### 字段定义
|
||||
|
||||
| 字段名 | 类型 | 约束 | 描述 |
|
||||
|--------|------|------|------|
|
||||
| id | Integer | 主键, 自增 | 指标唯一标识符 |
|
||||
| name | String(100) | 非空 | 指标名称 |
|
||||
| code | String(20) | 唯一, 非空 | 指标编码 |
|
||||
| indicator_type | Enum | 非空 | 指标类型（质量/数量/效率/服务/成本） |
|
||||
| bs_dimension | Enum | 非空 | 平衡计分卡维度 |
|
||||
| weight | Numeric(5,2) | 默认1.0, >0 | 权重 |
|
||||
| max_score | Numeric(5,2) | 默认100.0 | 最高分值 |
|
||||
| target_value | Numeric(10,2) | 可选 | 目标值 |
|
||||
| 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 | 是否启用 |
|
||||
| created_at | DateTime | 默认当前时间 | 创建时间 |
|
||||
| updated_at | DateTime | 更新时自动更新 | 更新时间 |
|
||||
|
||||
#### 业务规则
|
||||
|
||||
1. **权重约束**：权重必须大于0，通过数据库检查约束保证
|
||||
2. **适用科室**：支持JSON格式存储适用科室类型数组
|
||||
3. **模板集成**：与指标模板系统无缝集成
|
||||
4. **状态管理**：支持启用/停用控制
|
||||
|
||||
#### 数据一致性保证
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([创建指标]) --> Validate["验证输入参数"]
|
||||
Validate --> CheckCode{"检查编码唯一性"}
|
||||
CheckCode --> |重复| Error["返回错误"]
|
||||
CheckCode --> |唯一| Create["创建指标记录"]
|
||||
Create --> SetDefaults["设置默认值"]
|
||||
SetDefaults --> Save["保存到数据库"]
|
||||
Save --> Success["创建成功"]
|
||||
Error --> End([结束])
|
||||
Success --> End
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [models.py](file://backend/app/models/models.py#L117-L147)
|
||||
- [indicators.py](file://backend/app/api/v1/indicators.py#L71-L85)
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L117-L147)
|
||||
- [indicators.py](file://backend/app/api/v1/indicators.py#L1-L142)
|
||||
|
||||
### 系统用户表（users）
|
||||
|
||||
#### 字段定义
|
||||
|
||||
| 字段名 | 类型 | 约束 | 描述 |
|
||||
|--------|------|------|------|
|
||||
| id | Integer | 主键, 自增 | 用户唯一标识符 |
|
||||
| username | String(50) | 唯一, 非空 | 用户名 |
|
||||
| password_hash | String(255) | 非空 | 密码哈希值 |
|
||||
| staff_id | Integer | 外键, 可选 | 关联员工ID |
|
||||
| role | String(20) | 默认"staff" | 角色权限 |
|
||||
| is_active | Boolean | 默认True | 是否启用 |
|
||||
| last_login | DateTime | 可选 | 最后登录时间 |
|
||||
| created_at | DateTime | 默认当前时间 | 创建时间 |
|
||||
| updated_at | DateTime | 更新时自动更新 | 更新时间 |
|
||||
|
||||
#### 权限控制机制
|
||||
|
||||
系统实现了多层级权限控制：
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
subgraph "权限层级"
|
||||
Admin[系统管理员<br/>拥有所有权限]
|
||||
Manager[部门经理<br/>管理权限]
|
||||
Staff[普通员工<br/>查看权限]
|
||||
end
|
||||
subgraph "受保护操作"
|
||||
Create[创建操作]
|
||||
Update[更新操作]
|
||||
Delete[删除操作]
|
||||
Approve[审批操作]
|
||||
end
|
||||
Admin --> Create
|
||||
Admin --> Update
|
||||
Admin --> Delete
|
||||
Admin --> Approve
|
||||
Manager --> Create
|
||||
Manager --> Update
|
||||
Manager --> Approve
|
||||
Staff -.-> Create
|
||||
Staff -.-> Update
|
||||
Staff -.-> Delete
|
||||
Staff -.-> Approve
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [security.py](file://backend/app/core/security.py#L94-L110)
|
||||
- [models.py](file://backend/app/models/models.py#L244-L261)
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L244-L261)
|
||||
- [security.py](file://backend/app/core/security.py#L1-L110)
|
||||
|
||||
### 绩效计划表（performance_plans）
|
||||
|
||||
#### 字段定义
|
||||
|
||||
| 字段名 | 类型 | 约束 | 描述 |
|
||||
|--------|------|------|------|
|
||||
| id | Integer | 主键, 自增 | 计划唯一标识符 |
|
||||
| plan_name | String(200) | 非空 | 计划名称 |
|
||||
| plan_code | String(50) | 唯一, 非空 | 计划编码 |
|
||||
| plan_level | Enum | 非空 | 计划层级（医院/科室/个人） |
|
||||
| plan_year | Integer | 非空 | 计划年度 |
|
||||
| plan_month | Integer | 可选 | 计划月份（月度计划） |
|
||||
| plan_type | String(20) | 默认"annual" | 计划类型（annual/monthly） |
|
||||
| department_id | Integer | 外键, 可选 | 所属科室ID |
|
||||
| staff_id | Integer | 外键, 可选 | 责任人ID |
|
||||
| parent_plan_id | Integer | 外键, 可选 | 上级计划ID |
|
||||
| description | Text | 可选 | 计划描述 |
|
||||
| strategic_goals | Text | 可选 | 战略目标 |
|
||||
| key_initiatives | Text | 可选 | 关键举措 |
|
||||
| status | Enum | 默认"DRAFT" | 状态（草稿/待审批/已批准/执行中/完成/取消） |
|
||||
| submitter_id | Integer | 外键, 可选 | 提交人ID |
|
||||
| submit_time | DateTime | 可选 | 提交时间 |
|
||||
| approver_id | Integer | 外键, 可选 | 审批人ID |
|
||||
| approve_time | DateTime | 可选 | 审批时间 |
|
||||
| approve_remark | Text | 可选 | 审批意见 |
|
||||
| version | Integer | 默认1 | 版本号 |
|
||||
| is_active | Boolean | 默认True | 是否启用 |
|
||||
| created_at | DateTime | 默认当前时间 | 创建时间 |
|
||||
| updated_at | DateTime | 更新时自动更新 | 更新时间 |
|
||||
|
||||
#### 计划状态流转
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> 草稿
|
||||
草稿 --> 待审批 : "提交申请"
|
||||
待审批 --> 已批准 : "审批通过"
|
||||
待审批 --> 已驳回 : "审批驳回"
|
||||
已批准 --> 执行中 : "激活计划"
|
||||
执行中 --> 已完成 : "计划完成"
|
||||
执行中 --> 已取消 : "取消计划"
|
||||
已完成 --> [*]
|
||||
已取消 --> [*]
|
||||
已驳回 --> 草稿 : "修改后重新提交"
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [models.py](file://backend/app/models/models.py#L270-L312)
|
||||
- [schemas.py](file://backend/app/schemas/schemas.py#L470-L479)
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L270-L312)
|
||||
- [performance_plans.py](file://backend/app/api/v1/performance_plans.py#L1-L310)
|
||||
|
||||
### 计划指标关联表（plan_kpi_relations）
|
||||
|
||||
#### 字段定义
|
||||
|
||||
| 字段名 | 类型 | 约束 | 描述 |
|
||||
|--------|------|------|------|
|
||||
| id | Integer | 主键, 自增 | 关联唯一标识符 |
|
||||
| plan_id | Integer | 外键, 非空 | 计划ID |
|
||||
| indicator_id | Integer | 外键, 非空 | 指标ID |
|
||||
| target_value | Numeric(10,2) | 可选 | 目标值 |
|
||||
| target_unit | String(50) | 可选 | 目标值单位 |
|
||||
| weight | Numeric(5,2) | 默认1.0 | 权重 |
|
||||
| scoring_method | String(50) | 可选 | 评分方法 |
|
||||
| scoring_params | Text | 可选 | 评分参数（JSON） |
|
||||
| remark | Text | 可选 | 备注 |
|
||||
| created_at | DateTime | 默认当前时间 | 创建时间 |
|
||||
| updated_at | DateTime | 更新时自动更新 | 更新时间 |
|
||||
|
||||
#### 关联关系特性
|
||||
|
||||
1. **唯一性约束**：同一计划下的指标只能关联一次
|
||||
2. **权重管理**：支持为每个关联设置独立权重
|
||||
3. **评分定制**：支持为特定关联配置评分方法和参数
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L314-L339)
|
||||
|
||||
### 系统菜单表（menus）
|
||||
|
||||
#### 字段定义
|
||||
|
||||
| 字段名 | 类型 | 约束 | 描述 |
|
||||
|--------|------|------|------|
|
||||
| id | Integer | 主键, 自增 | 菜单唯一标识符 |
|
||||
| parent_id | Integer | 外键, 可选 | 父菜单ID |
|
||||
| menu_type | Enum | 默认"menu" | 菜单类型（菜单/按钮） |
|
||||
| menu_name | String(100) | 非空 | 菜单名称 |
|
||||
| menu_icon | String(50) | 可选 | 菜单图标 |
|
||||
| path | String(200) | 非空 | 路由路径 |
|
||||
| component | String(200) | 可选 | 组件路径 |
|
||||
| permission | String(100) | 可选 | 权限标识 |
|
||||
| sort_order | Integer | 默认0 | 排序 |
|
||||
| is_visible | Boolean | 默认True | 是否可见 |
|
||||
| is_active | Boolean | 默认True | 是否启用 |
|
||||
| created_at | DateTime | 默认当前时间 | 创建时间 |
|
||||
| updated_at | DateTime | 更新时自动更新 | 更新时间 |
|
||||
|
||||
#### 菜单树形结构
|
||||
|
||||
系统支持无限级菜单嵌套，通过parent_id字段实现父子关系：
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
Root[根菜单] --> Parent1[一级菜单1]
|
||||
Root --> Parent2[一级菜单2]
|
||||
Parent1 --> Child11[二级菜单1-1]
|
||||
Parent1 --> Child12[二级菜单1-2]
|
||||
Parent2 --> Child21[二级菜单2-1]
|
||||
Child11 --> GrandChild111[三级菜单1-1-1]
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [models.py](file://backend/app/models/models.py#L347-L373)
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L347-L373)
|
||||
- [menus.py](file://backend/app/api/v1/menus.py#L1-L164)
|
||||
|
||||
### 考核指标模板表（indicator_templates）
|
||||
|
||||
#### 字段定义
|
||||
|
||||
| 字段名 | 类型 | 约束 | 描述 |
|
||||
|--------|------|------|------|
|
||||
| id | Integer | 主键, 自增 | 模板唯一标识符 |
|
||||
| template_name | String(200) | 非空 | 模板名称 |
|
||||
| template_code | String(50) | 唯一, 非空 | 模板编码 |
|
||||
| template_type | Enum | 非空 | 模板类型（通用/手术/非手术/医技/护理/行政/后勤） |
|
||||
| description | Text | 可选 | 模板描述 |
|
||||
| dimension_weights | Text | 可选 | 维度权重（JSON） |
|
||||
| assessment_cycle | String(20) | 默认"monthly" | 考核周期 |
|
||||
| is_active | Boolean | 默认True | 是否启用 |
|
||||
| created_at | DateTime | 默认当前时间 | 创建时间 |
|
||||
| updated_at | DateTime | 更新时自动更新 | 更新时间 |
|
||||
|
||||
#### 模板类型体系
|
||||
|
||||
| 模板类型 | 适用科室 | 描述 |
|
||||
|----------|----------|------|
|
||||
| general | 通用 | 适用于所有科室的基础模板 |
|
||||
| surgical | 手术临床科室 | 适用于外科系统各手术科室 |
|
||||
| nonsurgical_ward | 非手术有病房科室 | 适用于内科系统等有病房科室 |
|
||||
| nonsurgical_noward | 非手术无病房科室 | 适用于门诊科室 |
|
||||
| medical_tech | 医技科室 | 适用于检验科、放射科等医技科室 |
|
||||
| nursing | 护理单元 | 适用于各护理单元 |
|
||||
| admin | 行政科室 | 适用于党办、财务科、医保办等行政科室 |
|
||||
| logistics | 后勤保障科室 | 适用于总务科、采购科、基建科 |
|
||||
|
||||
#### 模板指标关联表（template_indicators）
|
||||
|
||||
| 字段名 | 类型 | 约束 | 描述 |
|
||||
|--------|------|------|------|
|
||||
| id | Integer | 主键, 自增 | 关联唯一标识符 |
|
||||
| template_id | Integer | 外键, 非空 | 模板ID |
|
||||
| indicator_id | Integer | 外键, 非空 | 指标ID |
|
||||
| category | String(100) | 可选 | 指标分类（二级指标） |
|
||||
| target_value | Numeric(10,2) | 可选 | 目标值 |
|
||||
| target_unit | String(50) | 可选 | 目标值单位 |
|
||||
| weight | Numeric(5,2) | 默认1.0 | 权重 |
|
||||
| scoring_method | String(50) | 可选 | 评分方法 |
|
||||
| scoring_params | Text | 可选 | 评分参数（JSON） |
|
||||
| sort_order | Integer | 默认0 | 排序 |
|
||||
| remark | Text | 可选 | 备注 |
|
||||
| created_at | DateTime | 默认当前时间 | 创建时间 |
|
||||
| updated_at | DateTime | 更新时自动更新 | 更新时间 |
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L387-L438)
|
||||
- [templates.py](file://backend/app/api/v1/templates.py#L1-L272)
|
||||
|
||||
## 依赖关系分析
|
||||
|
||||
### 数据库迁移历史
|
||||
|
||||
系统通过Alembic进行数据库版本管理，主要迁移包括：
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
Initial[初始版本] --> Template[模板版本]
|
||||
Initial["初始版本<br/>- 创建科室表<br/>- 创建员工表<br/>- 创建指标表<br/>- 创建考核记录表<br/>- 创建考核明细表<br/>- 创建工资记录表<br/>- 创建用户表"]
|
||||
Template["模板版本<br/>- 创建指标模板表<br/>- 创建模板指标关联表<br/>- 为指标表添加BSC维度字段"]
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L21-L183)
|
||||
- [002_template.py](file://backend/alembic/versions/002_template.py#L21-L96)
|
||||
|
||||
### 外部依赖关系
|
||||
|
||||
系统依赖的关键外部组件：
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "核心依赖"
|
||||
FastAPI[FastAPI Web框架]
|
||||
SQLAlchemy[SQLAlchemy ORM]
|
||||
Postgres[PostgreSQL数据库]
|
||||
Alembic[数据库迁移工具]
|
||||
end
|
||||
subgraph "安全依赖"
|
||||
JWT[JWT令牌]
|
||||
Bcrypt[密码加密]
|
||||
OAuth2[OAuth2密码模式]
|
||||
end
|
||||
subgraph "配置依赖"
|
||||
Pydantic[数据验证]
|
||||
Settings[环境配置]
|
||||
end
|
||||
FastAPI --> SQLAlchemy
|
||||
SQLAlchemy --> Postgres
|
||||
FastAPI --> JWT
|
||||
JWT --> Bcrypt
|
||||
FastAPI --> Pydantic
|
||||
Pydantic --> Settings
|
||||
Alembic --> SQLAlchemy
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [database.py](file://backend/app/core/database.py#L1-L39)
|
||||
- [security.py](file://backend/app/core/security.py#L1-L110)
|
||||
- [config.py](file://backend/app/core/config.py#L1-L47)
|
||||
|
||||
**章节来源**
|
||||
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L1-L183)
|
||||
- [002_template.py](file://backend/alembic/versions/002_template.py#L1-L96)
|
||||
- [database.py](file://backend/app/core/database.py#L1-L39)
|
||||
|
||||
## 性能考虑
|
||||
|
||||
### 数据库索引优化
|
||||
|
||||
系统为关键查询字段建立了适当的索引：
|
||||
|
||||
- **indicators表**：按指标类型建立索引，支持快速筛选
|
||||
- **users表**：按用户名建立唯一索引，确保用户唯一性
|
||||
- **performance_plans表**：按计划层级、年度、状态建立复合索引
|
||||
- **menus表**：按父节点、类型、可见性建立索引
|
||||
- **plan_kpi_relations表**：按计划ID、指标ID建立唯一索引
|
||||
|
||||
### 缓存策略
|
||||
|
||||
建议实现的缓存策略：
|
||||
|
||||
1. **枚举类型缓存**：缓存所有枚举定义，避免重复查询
|
||||
2. **模板数据缓存**：缓存常用模板数据，减少数据库访问
|
||||
3. **用户权限缓存**：缓存用户权限信息，提高权限检查效率
|
||||
|
||||
### 异步处理
|
||||
|
||||
系统采用异步数据库连接，支持高并发场景：
|
||||
|
||||
- 使用SQLAlchemy AsyncEngine进行异步数据库操作
|
||||
- 通过AsyncSession管理数据库会话
|
||||
- 支持异步API路由处理
|
||||
|
||||
## 故障排除指南
|
||||
|
||||
### 常见问题及解决方案
|
||||
|
||||
#### 数据库连接问题
|
||||
- **症状**：应用启动时报数据库连接错误
|
||||
- **原因**：DATABASE_URL配置不正确
|
||||
- **解决**：检查.env文件中的数据库连接字符串
|
||||
|
||||
#### 权限验证失败
|
||||
- **症状**：API调用返回401或403错误
|
||||
- **原因**：JWT令牌无效或用户权限不足
|
||||
- **解决**：重新登录获取有效令牌，检查用户角色配置
|
||||
|
||||
#### 数据唯一性冲突
|
||||
- **症状**：创建记录时报唯一约束冲突
|
||||
- **原因**：重复的编码或用户名
|
||||
- **解决**：检查输入数据的唯一性约束
|
||||
|
||||
#### 模板导入失败
|
||||
- **症状**：指标模板导入过程中断
|
||||
- **原因**：模板数据格式不正确或依赖关系缺失
|
||||
- **解决**：验证模板JSON格式，确保指标已存在
|
||||
|
||||
**章节来源**
|
||||
- [security.py](file://backend/app/core/security.py#L55-L83)
|
||||
- [indicators.py](file://backend/app/api/v1/indicators.py#L78-L84)
|
||||
|
||||
## 结论
|
||||
|
||||
本配置管理表系统通过精心设计的数据模型和完善的权限控制机制，为医院绩效考核管理提供了强大的基础支撑。系统的主要优势包括：
|
||||
|
||||
1. **完整的配置管理**：涵盖指标、计划、模板、菜单等核心配置
|
||||
2. **灵活的权限控制**：多层级权限体系满足不同角色需求
|
||||
3. **模板化管理**：支持指标模板的创建、管理和复用
|
||||
4. **数据一致性**：通过外键约束和检查约束保证数据完整性
|
||||
5. **扩展性强**：模块化设计便于功能扩展和维护
|
||||
|
||||
建议在实际部署中重点关注数据库性能优化、缓存策略实施和监控告警机制建设，以确保系统的稳定运行和高性能表现。
|
||||
Reference in New Issue
Block a user