# KPI 模块设计原则

> 本文档定义 KPI 模块的核心设计原则，供后续后端/数据库开发参考。

## 1. KPI 字段定义

每个 KPI（绩效指标分配）应包含以下核心字段：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | string | 是 | 绩效名称，描述要达成的目标 |
| baseTarget | string | 否 | 基本目标 —— 预期最低应达成的成果描述 |
| stretchTarget | string | 否 | 挑战目标 —— 超出预期的优秀成果描述 |
| weight | number | 是 | 本周期内的权重（%），同一周期内所有 KPI 权重之和应为 100% |
| dependentUserId | string | 否 | 依赖人 —— KPI 达成需协作的关键人员 |
| dependentAssignmentId | string | 否 | 依赖绩效 —— 关联的他人 KPI |
| status | enum | 是 | 审批状态：DRAFT → SUBMITTED → APPROVED / REJECTED |

### 基本目标 vs 挑战目标

- **基本目标（baseTarget）**：合格线，达成此目标即视为"完成"
- **挑战目标（stretchTarget）**：拉伸线，达成此目标视为"超额完成"
- 评分时可基于两个目标的区间进行打分，基本目标对应及格分，挑战目标对应满分

## 2. 周期层级关系

### 核心原则：季度拆分在周期层面完成，而非 KPI 层面

```
PerformanceCycle (年度)
├── PerformanceCycle (Q1) ← parentCycleId 指向年度
├── PerformanceCycle (Q2)
├── PerformanceCycle (Q3)
└── PerformanceCycle (Q4)
```

- 年度周期可拆分为多个子周期（季度/半年度），通过 `parentCycleId` 建立层级
- 每个子周期是独立的绩效周期，有自己的状态、KPI 分配、评估流程
- KPI 不再通过 `parentId/children` 建立父子关系
- 每个 KPI 直接挂在对应的周期上，不跨周期

### PerformanceCycle 新增字段

| 字段 | 类型 | 说明 |
|------|------|------|
| parentCycleId | string? | 父周期 ID，null 表示顶层周期 |
| parentCycle | relation | 父周期引用 |
| childCycles | relation[] | 子周期列表 |

### 子周期规则

- 子周期的时间范围必须在父周期范围内
- 子周期继承父周期的等级配置（gradeConfig），除非显式覆盖
- 子周期可以有独立的状态流转，不强制与父周期同步
- 一个员工在子周期内的 KPI 与父周期内的 KPI 是独立的

## 3. 权重规则

- 同一绩效周期内，某员工的所有 KPI 权重之和必须等于 100%
- 子周期的权重独立于父周期（各自合计 100%）
- 权重精度支持到小数点后两位

## 4. 依赖机制

- KPI 可设置依赖人（`dependentUserId`），表示该 KPI 的达成需要该人协作
- 设置依赖人后，系统向被依赖人发送确认请求
- 被依赖人可选择绑定自己的某个 KPI 进行对齐（`dependentAssignmentId`）
- 依赖确认状态：`PENDING_DEPENDENCY` → `CONFIRMED`

## 5. 评分规则

- 自评（selfScore）+ 他评（managerScore）→ 最终分（finalScore）
- 评分区间 0-100
- 基于 baseTarget/stretchTarget 进行评判：
  - 未达基本目标 → 低分区间
  - 达成基本目标 → 及格分区间
  - 达成挑战目标 → 高分区间
- 最终分结合等级配置（GradeConfig）映射为等级（S/A/B/C/D）