提交文件
This commit is contained in:
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