# 绩效计划字段

<cite>
**本文档引用的文件**
- [models.py](file://backend/app/models/models.py)
- [performance_plans.py](file://backend/app/api/v1/performance_plans.py)
- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py)
- [schemas.py](file://backend/app/schemas/schemas.py)
- [create_plan_tables.py](file://backend/create_plan_tables.py)
- [001_initial.py](file://backend/alembic/versions/001_initial.py)
- [002_template.py](file://backend/alembic/versions/002_template.py)
- [database.md](file://docs/database.md)
</cite>

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

## 简介

本文件为医院绩效系统中绩效计划相关字段的详细数据字典，涵盖以下核心实体：
- 绩效计划表（PerformancePlan）
- 计划层级（PlanLevel）
- 计划状态（PlanStatus）
- 计划指标关联表（PlanKpiRelation）

文档详细说明了计划层级结构、计划审批流程、指标权重分配等相关字段，并包含计划执行跟踪和状态管理的字段约束。同时提供计划与指标关联关系的数据字典说明，以及计划版本管理和变更追踪的字段设计。

## 项目结构

该系统采用典型的三层架构设计：
- API层：处理HTTP请求和响应
- 服务层：实现业务逻辑和工作流控制
- 数据模型层：定义数据库表结构和关系

```mermaid
graph TB
subgraph "API层"
API[performance_plans.py]
end
subgraph "服务层"
Service[performance_plan_service.py]
end
subgraph "模型层"
Models[models.py]
Schemas[schemas.py]
end
subgraph "数据库"
DB[(SQLite/PostgreSQL)]
end
API --> Service
Service --> Models
Models --> DB
Schemas --> API
```

**图表来源**
- [performance_plans.py](file://backend/app/api/v1/performance_plans.py#L1-L310)
- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L1-L342)
- [models.py](file://backend/app/models/models.py#L270-L339)

## 核心组件

### 绩效计划表（PerformancePlan）

绩效计划表是整个绩效管理体系的核心实体，用于存储各级别（医院级、科室级、个人级）的绩效计划信息。

#### 基础字段定义

| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| id | Integer | 主键, 自增 | 计划唯一标识符 |
| plan_name | String(200) | 非空 | 计划名称 |
| plan_code | String(50) | 唯一, 非空 | 计划编码，全局唯一 |
| plan_level | Enum | 非空 | 计划层级：hospital/department/individual |
| plan_year | Integer | 非空 | 计划年度（2000-2100） |
| plan_month | Integer | 可空 | 计划月份（1-12），仅月度计划使用 |
| plan_type | String(20) | 默认 annual | 计划类型：annual/monthly |
| department_id | Integer | 外键 | 所属科室ID |
| staff_id | Integer | 外键 | 责任人ID |
| parent_plan_id | Integer | 外键 | 上级计划ID，支持层级结构 |
| description | Text | 可空 | 计划描述 |
| strategic_goals | Text | 可空 | 战略目标 |
| key_initiatives | Text | 可空 | 关键举措 |
| status | Enum | 默认 draft | 计划状态：draft/pending/approved/rejected/active/completed/cancelled |
| submitter_id | Integer | 外键 | 提交人ID |
| submit_time | DateTime | 可空 | 提交时间 |
| approver_id | Integer | 外键 | 审批人ID |
| approve_time | DateTime | 可空 | 审批时间 |
| approve_remark | Text | 可空 | 审批意见 |
| version | Integer | 默认 1 | 版本号，用于版本管理 |
| is_active | Boolean | 默认 TRUE | 是否启用 |
| created_at | DateTime | 默认当前时间 | 创建时间 |
| updated_at | DateTime | 默认当前时间 | 更新时间 |

#### 索引设计

- idx_plan_level：按计划层级查询优化
- idx_plan_year：按年度查询优化  
- idx_plan_department：按科室查询优化
- idx_plan_status：按状态查询优化

### 计划层级（PlanLevel）

计划层级枚举定义了绩效计划的组织层次结构：

```mermaid
classDiagram
class PlanLevel {
+hospital : "医院级"
+department : "科室级"
+individual : "个人级"
}
class PerformancePlan {
+plan_level : PlanLevel
+parent_plan_id : int
+child_plans : PerformancePlan[]
}
PerformancePlan --> PlanLevel : "使用"
```

**图表来源**
- [models.py](file://backend/app/models/models.py#L263-L268)
- [models.py](file://backend/app/models/models.py#L277-L304)

### 计划状态（PlanStatus）

计划状态枚举定义了完整的审批和执行生命周期：

```mermaid
stateDiagram-v2
[*] --> 草稿
草稿 --> 待审批 : "提交"
待审批 --> 已批准 : "审批通过"
待审批 --> 已驳回 : "审批驳回"
已批准 --> 执行中 : "激活"
已批准 --> 已取消 : "取消"
执行中 --> 已完成 : "完成"
执行中 --> 已取消 : "取消"
已完成 --> [*]
已取消 --> [*]
已驳回 --> [*]
```

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

### 计划指标关联表（PlanKpiRelation）

计划指标关联表建立了计划与具体考核指标之间的多对多关系，支持每个指标在不同计划中的差异化配置。

#### 关联字段定义

| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| id | Integer | 主键, 自增 | 关联关系唯一标识符 |
| plan_id | Integer | 外键, 非空 | 关联的计划ID |
| indicator_id | Integer | 外键, 非空 | 关联的指标ID |
| target_value | Decimal(10,2) | 可空 | 目标值 |
| target_unit | String(50) | 可空 | 目标值单位 |
| weight | Decimal(5,2) | 默认 1.0 | 权重（0-100） |
| scoring_method | String(50) | 可空 | 评分方法 |
| scoring_params | Text | 可空 | 评分参数（JSON格式） |
| remark | Text | 可空 | 备注 |
| created_at | DateTime | 默认当前时间 | 创建时间 |
| updated_at | DateTime | 默认当前时间 | 更新时间 |

#### 关联关系

- 一对多：一个计划可以关联多个指标
- 一对多：一个指标可以出现在多个计划中
- 唯一约束：同一计划下的指标必须唯一

**章节来源**
- [models.py](file://backend/app/models/models.py#L314-L339)
- [schemas.py](file://backend/app/schemas/schemas.py#L481-L517)

## 架构概览

系统采用RESTful API设计，支持完整的CRUD操作和业务流程控制：

```mermaid
sequenceDiagram
participant Client as "客户端"
participant API as "API层"
participant Service as "服务层"
participant Model as "模型层"
participant DB as "数据库"
Client->>API : GET /plans/{plan_id}
API->>Service : get_by_id(plan_id)
Service->>Model : 查询PerformancePlan
Model->>DB : SQL查询
DB-->>Model : 返回结果
Model-->>Service : PerformancePlan对象
Service-->>API : 格式化响应
API-->>Client : JSON数据
Note over Client,DB : 审批流程示例
Client->>API : POST /plans/{plan_id}/approve
API->>Service : approve(approver_id, approved, remark)
Service->>Model : 更新状态和审批信息
Model->>DB : 更新操作
DB-->>Model : 确认更新
Model-->>Service : 更新结果
Service-->>API : 审批结果
API-->>Client : 审批状态
```

**图表来源**
- [performance_plans.py](file://backend/app/api/v1/performance_plans.py#L194-L241)
- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L144-L182)

## 详细组件分析

### 计划层级结构

系统支持三级层级结构，通过parent_plan_id字段实现自关联：

```mermaid
graph TD
HospitalPlan["医院级计划<br/>parent_plan_id: NULL"]
DeptPlan1["科室级计划<br/>parent_plan_id: 医院级计划ID"]
DeptPlan2["科室级计划<br/>parent_plan_id: 医院级计划ID"]
IndividualPlan1["个人级计划<br/>parent_plan_id: 科室级计划ID"]
IndividualPlan2["个人级计划<br/>parent_plan_id: 科室级计划ID"]
HospitalPlan --> DeptPlan1
HospitalPlan --> DeptPlan2
DeptPlan1 --> IndividualPlan1
DeptPlan1 --> IndividualPlan2
```

**图表来源**
- [models.py](file://backend/app/models/models.py#L283-L301)
- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L319-L341)

### 计划审批流程

审批流程严格遵循状态机设计，确保业务合规性：

```mermaid
flowchart TD
Start([开始]) --> Draft["草稿状态<br/>DRAFT"]
Draft --> Submit["提交申请<br/>SUBMIT"]
Submit --> Pending["待审批<br/>PENDING"]
Pending --> Approve{"审批决定"}
Approve --> |通过| Approved["已批准<br/>APPROVED"]
Approve --> |驳回| Rejected["已驳回<br/>REJECTED"]
Approved --> Activate["激活计划<br/>ACTIVE"]
Activate --> Completed["完成<br/>COMPLETED"]
Rejected --> End([结束])
Completed --> End
Active --> End
```

**图表来源**
- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L131-L182)

### 指标权重分配

指标权重分配支持动态配置，每个计划可以为相同指标设置不同的权重：

#### 权重约束
- 权重范围：0-100
- 总权重：同一计划内所有指标权重之和通常为100%
- 动态调整：支持运行时修改权重分配

#### 评分参数
支持JSON格式的评分参数，如：
```json
{
  "threshold": 90,
  "bonus": 1.2,
  "penalty": 0.8
}
```

**章节来源**
- [schemas.py](file://backend/app/schemas/schemas.py#L486-L488)
- [models.py](file://backend/app/models/models.py#L323-L325)

### 计划执行跟踪

系统提供完整的过程跟踪机制：

#### 时间戳管理
- created_at：记录创建时间
- updated_at：自动更新时间戳
- submit_time：提交时间
- approve_time：审批时间

#### 版本管理
- version字段：支持版本追踪
- is_active：控制计划启用状态
- 支持历史版本对比

**章节来源**
- [models.py](file://backend/app/models/models.py#L288-L296)
- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L120-L128)

### 计划与指标关联关系

关联关系通过PlanKpiRelation表实现，支持灵活的配置：

```mermaid
erDiagram
PERFORMANCE_PLANS {
int id PK
string plan_name
int plan_year
enum plan_level
int department_id FK
int staff_id FK
}
PLAN_KPI_RELATIONS {
int id PK
int plan_id FK
int indicator_id FK
decimal weight
decimal target_value
string target_unit
}
INDICATORS {
int id PK
string name
string code
enum indicator_type
decimal weight
}
PERFORMANCE_PLANS ||--o{ PLAN_KPI_RELATIONS : "包含"
INDICATORS ||--o{ PLAN_KPI_RELATIONS : "被包含"
```

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

## 依赖关系分析

系统采用清晰的分层依赖关系：

```mermaid
graph LR
subgraph "外部依赖"
FastAPI[FastAPI框架]
SQLAlchemy[SQLAlchemy ORM]
Alembic[Alembic迁移]
end
subgraph "内部模块"
API[API层]
Service[服务层]
Models[模型层]
Schemas[模式层]
end
FastAPI --> API
SQLAlchemy --> Models
Alembic --> Models
API --> Service
Service --> Models
Service --> Schemas
Models --> Schemas
```

**图表来源**
- [performance_plans.py](file://backend/app/api/v1/performance_plans.py#L1-L18)
- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L1-L13)

### 数据库迁移

系统使用Alembic进行数据库版本管理，支持增量升级和降级：

#### 迁移版本
- 001_initial：初始版本，创建基础表结构
- 002_template：添加指标模板相关表

#### 迁移特性
- 自动检测模型变化
- 支持安全的数据库演进
- 提供回滚能力

**章节来源**
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L21-L183)
- [002_template.py](file://backend/alembic/versions/002_template.py#L21-L96)

## 性能考虑

### 查询优化

1. **索引策略**
   - 多列组合索引用于常用查询条件
   - 唯一索引确保数据完整性
   - 选择性索引提升查询性能

2. **查询优化**
   - 使用selectinload避免N+1查询问题
   - 分页查询支持大数据集
   - 条件查询减少数据传输

### 缓存策略

- 配置适当的缓存层
- 对静态配置数据进行缓存
- 利用数据库连接池

## 故障排除指南

### 常见问题

1. **计划状态异常**
   - 检查状态转换规则
   - 验证审批权限
   - 确认时间戳完整性

2. **指标关联问题**
   - 验证唯一性约束
   - 检查权重分配合理性
   - 确认评分参数格式

3. **数据库连接问题**
   - 检查连接池配置
   - 验证迁移版本一致性
   - 监控数据库性能

### 调试建议

1. **日志记录**
   - 启用详细的API日志
   - 记录关键业务操作
   - 监控错误堆栈

2. **测试策略**
   - 单元测试覆盖核心逻辑
   - 集成测试验证流程
   - 性能测试评估瓶颈

**章节来源**
- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L131-L182)
- [performance_plans.py](file://backend/app/api/v1/performance_plans.py#L194-L241)

## 结论

本数据字典详细描述了医院绩效系统中绩效计划相关的核心字段和业务逻辑。系统采用清晰的分层架构，支持完整的计划生命周期管理，包括：

- 多层级的组织结构支持
- 完整的审批流程控制
- 灵活的指标权重配置
- 详细的执行跟踪机制
- 强大的版本管理功能

通过合理的数据库设计和API接口，系统能够有效支撑医院的绩效管理体系，为不同层级的组织提供个性化的绩效管理解决方案。