# 绩效管理模块 - API 文档

> **module**: performance
> **doc_type**: API
> **status**: Active
> **owner**: FFOA 开发团队
> **upstream_docs**: 01-prd.md, 04-state-machine.md, 06-data-model.md
> **last_verified**: 2026-03-20

---

### 统一约定

- Base URL: `/api/v1/performance`
- 认证: Bearer Token (JWT)
- 错误码: [08-error-codes.md](./08-error-codes.md)
- 统一拦截器: 成功响应由 `TransformInterceptor` 统一包装；错误响应由 `AllExceptionsFilter` 统一格式化
- 响应封装:
  - 成功: `{ "success": true, "data": {...}, "message": "success", "timestamp": "...", "path": "/api/v1/..." }`
  - 分页: `{ "success": true, "data": { items, total, page, limit, totalPages, hasNext, hasPrev }, "timestamp": "...", "path": "/api/v1/..." }`
  - 失败: `{ "success": false, "error": { "code": "PERF_xxx", "message": "...", "...": "..." }, "timestamp": "...", "path": "/api/v1/...", "method": "GET", "statusCode": 400 }`
- 示例说明: 示例响应默认展示完整封装；若仅展示 `data` 字段会显式标注

### 通用状态码

| 状态码 | 说明 |
|-------|------|
| 200 | 成功 |
| 201 | 创建成功 |
| 400 | 参数错误/业务校验失败 |
| 401 | 未认证 |
| 403 | 无权限 |
| 404 | 资源不存在 |
| 409 | 业务冲突（状态不允许/重复） |
| 422 | 数据校验失败 |

### API 说明

- 覆盖绩效周期、KPI、360、校准、结果等全链路接口
- 所有接口返回统一封装格式（见“统一约定”）
- 变更接口需同步更新错误码文档与测试场景

### 接口数量汇总

- 总计: 102 个接口（其中 In-scope: 92, Out-of-scope: 10）
- 统计口径: 下方”接口清单（按域）”中的全部路径
- Out-of-scope 说明: 标注为 Out-of-scope 的端点本轮前端无入口，后续版本规划
- 已废弃说明: KPI 指标库、持续反馈、绩效面谈、校准会议管理等已废弃接口已移除

### CycleStatus 枚举

| 值 | 说明 |
|------|------|
| DRAFT | 草稿 |
| GOAL_SETTING | 目标设定 |
| IN_PROGRESS | 执行中 |
| EVALUATING | 评估中 |
| CALIBRATING | 校准中 |
| CONFIRMING | 结果确认中（v4.0 新增） |
| COMPLETED | 已完成 |
| ARCHIVED | 已归档 |

### 周期状态转换 API 汇总

| 转换 | API | 方法 |
|------|------|------|
| DRAFT → GOAL_SETTING | /cycles/:id/publish | POST |
| GOAL_SETTING → IN_PROGRESS | /cycles/:id/start-execution | POST |
| IN_PROGRESS → EVALUATING | /cycles/:id/start-evaluation | POST |
| EVALUATING → CALIBRATING | /cycles/:id/start-calibration | POST |
| CALIBRATING → CONFIRMING | /cycles/:id/start-confirming | POST |
| CONFIRMING → COMPLETED | /cycles/:id/complete | POST |
| COMPLETED → ARCHIVED | /cycles/:id/archive | POST |

---

## 接口清单（按域）

### 1) 等级配置（9）

| 序号 | 方法 | 路径 | 权限 |
|------|------|------|------|
| 001 | GET | /grade-configs | HR |
| 002 | GET | /grade-configs/default | HR |
| 003 | GET | /grade-configs/select | HR |
| 004 | GET | /grade-configs/:id | HR |
| 005 | POST | /grade-configs | HR |
| 006 | PUT | /grade-configs/:id | HR |
| 007 | POST | /grade-configs/:id/set-default | HR |
| 008 | DELETE | /grade-configs/:id | HR |
| 009 | POST | /grade-configs/validate | HR |

### 2) 周期管理（20）

| 序号 | 方法 | 路径 | 权限 |
|------|------|------|------|
| 010 | GET | /cycles | All |
| 011 | GET | /cycles/select | All |
| 012 | GET | /cycles/active | All |
| 013 | GET | /cycles/:id | All |
| 014 | GET | /cycles/:id/statistics | All |
| 015 | POST | /cycles | HR |
| 016 | PUT | /cycles/:id | HR |
| 017 | POST | /cycles/:id/publish | HR |
| 018 | POST | /cycles/:id/start-execution | HR |
| 019 | POST | /cycles/:id/start-evaluation | HR |
| 020 | POST | /cycles/:id/start-calibration | HR |
| 020a | POST | /cycles/:id/start-confirming | HR |
| 021 | POST | /cycles/:id/complete | HR |
| 022 | POST | /cycles/:id/publish-results | HR |
| 023 | POST | /cycles/:id/archive | HR |
| 024 | DELETE | /cycles/:id | HR |
| 024a | GET | /cycles/:id/goal-setting-progress | HR |
| 024b | GET | /cycles/:id/evaluation-progress | HR |
| 024c | GET | /cycles/:id/calibration-progress | HR |
| 024d | GET | /cycles/:id/cycle-results-summary | HR |

### 3) KPI 分配与目标（17）

| 序号 | 方法 | 路径 | 权限 |
|------|------|------|------|
| 030 | GET | /kpi/assignments | All |
| 031 | GET | /kpi/assignments/my | All |
| 032 | GET | /kpi/assignments/team | Manager |
| 033 | GET | /kpi/assignments/:id | All |（Out-of-scope：本轮前端无入口，后续版本规划）|
| 034 | POST | /kpi/assignments | HR |
| 035 | POST | /kpi/assignments/batch | HR |（Out-of-scope：本轮前端无入口，后续版本规划）|
| 036 | PUT | /kpi/assignments/:id | HR/Owner |
| 037 | POST | /kpi/assignments/:id/quarter-targets | Owner/Manager | *(已废弃)* |
| 038 | GET | /kpi/weight-validation | All |（Out-of-scope：本轮前端无入口，后续版本规划）|
| 038a | POST | /kpi/assignments/submit-all | Owner |
| 038b | POST | /kpi/assignments/:id/approve | Manager |
| 038c | POST | /kpi/assignments/:id/reject | Manager |
| 038d | GET | /kpi/assignments/pending-dependency | All |
| 038e | POST | /kpi/assignments/:id/confirm-dependency | Owner |
| 038f | POST | /kpi/assignments/:id/reject-dependency | Owner |
| 038g | PATCH | /results/overall-comment | Manager/Owner |
| 038h | GET | /results/overall-comment | All |

### 4) KPI 评估（4）

| 序号 | 方法 | 路径 | 权限 |
|------|------|------|------|
| 039 | GET | /kpi/assessments/:id | All |
| 040 | POST | /kpi/assessments/:id/self-evaluate | Owner |
| 041 | POST | /kpi/assessments/:id/manager-evaluate | Manager |
| 042 | POST | /kpi/assessments/:id/confirm | HR |

### 5) 360 评估（21）

| 序号 | 方法 | 路径 | 权限 |
|------|------|------|------|
| 043 | GET | /360/evaluations | HR/Manager |
| 043a | GET | /360/evaluations/summary | HR/Manager |
| 043b | GET | /360/evaluations/by-employee | HR/Manager |
| 044 | GET | /360/evaluations/:id | HR/Manager |
| 045 | POST | /360/evaluations | HR/Manager |
| 046 | PUT | /360/evaluations/:id | HR/Manager |
| 047 | DELETE | /360/evaluations/:id | HR/Manager |
| 048 | POST | /360/evaluations/:id/start | HR/Manager |
| 049 | POST | /360/evaluations/:id/complete | HR/Manager |
| 051 | POST | /360/evaluations/:id/evaluators | HR/Manager |
| 052 | DELETE | /360/evaluations/:evaluationId/evaluators/:evaluatorId | HR/Manager |
| 053 | GET | /360/tasks | All |
| 054 | GET | /360/tasks/my | All |
| 054a | GET | /360/my-tasks | All |
| 055 | POST | /360/tasks/:id/submit | Evaluator |
| 056 | GET | /360/evaluations/:id/results | HR/Manager |
| 056a | GET | /360-templates | HR |
| 056b | POST | /360-templates | HR |
| 056c | PATCH | /360-templates/:id | HR |
| 056d | DELETE | /360-templates/:id | HR |
| 056e | PATCH | /360-templates/:id/set-default | HR |

### 6) 绩效校准（7）

| 序号 | 方法 | 路径 | 权限 |
|------|------|------|------|
| 067 | POST | /calibration/sessions/:id/adjust | HR/Manager |
| 068 | GET | /calibration/sessions/:id/distribution | HR/Manager |
| 069 | GET | /calibration/sessions/:id/logs | HR/Manager |
| 070 | GET | /calibration/sessions/:id/employees | HR/Manager |
| 071 | GET | /calibration/sessions/:id/validate-distribution | HR/Manager |
| 071a | GET | /calibration/overview | HR |
| 071b | POST | /calibration/adjust | HR |

### 7) 绩效结果（11）

| 序号 | 方法 | 路径 | 权限 |
|------|------|------|------|
| 093 | GET | /results/my | All |
| 094 | GET | /results/my/:cycleId | All |
| 095 | POST | /results/my/:id/viewed | All |
| 095a | POST | /results/my/:id/confirm | All |
| 095b | POST | /results/my/:id/appeal | All |
| 095c | POST | /results/:id/resolve-appeal | HR |
| 096 | GET | /results | HR/Manager |
| 097 | GET | /results/:id | HR/Manager/Owner |
| 098 | PUT | /results/:id | HR |
| 099 | POST | /results/calculate | HR |（Out-of-scope：本轮前端无入口，后续版本规划）|
| 100 | POST | /results/export | HR |

### 8) 统计分析（8）

| 序号 | 方法 | 路径 | 权限 |
|------|------|------|------|
| 101 | GET | /reports/personal | All |（Out-of-scope：本轮前端无入口，后续版本规划）|
| 102 | GET | /reports/personal/trend | All |（Out-of-scope：本轮前端无入口，后续版本规划）|
| 103 | GET | /reports/team | Manager |（Out-of-scope：本轮前端无入口，后续版本规划）|
| 104 | GET | /reports/department | HR |（Out-of-scope：本轮前端无入口，后续版本规划）|
| 105 | GET | /reports/company | HR/Executive |
| 106 | GET | /reports/grade-distribution | HR/Manager |（Out-of-scope：本轮前端无入口，后续版本规划）|
| 107 | GET | /reports/cycle-comparison | HR/Manager |（Out-of-scope：本轮前端无入口，后续版本规划）|
| 107a | GET | /reports/department/:deptId | HR |

### 9) 战略目标（6）

| 序号 | 方法 | 路径 | 权限 |
|------|------|------|------|
| 108 | GET | /strategic-objectives | HR |
| 108a | GET | /strategic-objectives/:id | HR |
| 109 | POST | /strategic-objectives | HR |
| 110 | PUT | /strategic-objectives/:id | HR |
| 111 | DELETE | /strategic-objectives/:id | HR |
| 112 | POST | /strategic-objectives/:id/assign | HR |

---

## 数据结构定义（字段级）

### 通用响应封装

#### SuccessResponse<T>

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| success | Boolean | ✅ | 成功标记，固定为 true |
| data | T | ✅ | 业务数据 |
| message | String | ✅ | 提示信息，默认 `success` |
| timestamp | DateTime | ✅ | 响应时间 |
| path | String | ✅ | 请求路径 |

#### ErrorResponse

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| success | Boolean | ✅ | 成功标记，固定为 false |
| error.code | String | ✅ | 错误码（见 08-error-codes） |
| error.message | String | ✅ | i18n key 或可读信息 |
| error.details | JSON | ❌ | 额外上下文 |
| timestamp | DateTime | ✅ | 响应时间 |
| path | String | ✅ | 请求路径 |
| method | String | ✅ | HTTP 方法 |
| statusCode | Int | ✅ | HTTP 状态码 |

### 通用列表与分页

#### PageResult<T>（扁平化分页格式）

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| items | T[] | ✅ | 列表数据 |
| total | Int | ✅ | 总数 |
| page | Int | ✅ | 页码（从 1 开始） |
| limit | Int | ✅ | 每页数量（等价于 pageSize） |
| totalPages | Int | ✅ | 总页数 |
| hasNext | Boolean | ✅ | 是否有下一页 |
| hasPrev | Boolean | ✅ | 是否有上一页 |

#### ListResult<T>

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| items | T[] | ✅ | 不分页列表 |

### 通用结果结构

#### IdResult

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | UUID | ✅ | 主键 ID |

#### IdName

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | UUID | ✅ | 主键 ID |
| name | String | ✅ | 名称 |

#### IdDefaultResult

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | UUID | ✅ | 主键 ID |
| isDefault | Boolean | ✅ | 是否默认 |

#### StatusResult

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| status | Enum | ✅ | 状态值 |

#### CycleStatusResult

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | UUID | ✅ | 周期 ID |
| status | Enum | ✅ | 周期状态 |

#### EvaluationStatusResult

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | UUID | ✅ | 评估 ID |
| status | Enum | ✅ | 评估状态 |

#### KpiAssessmentStatusResult

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | UUID | ✅ | 考核 ID |
| status | Enum | ✅ | 考核状态 |
| finalScore | Decimal | ❌ | 最终分数（如有） |

#### EvaluationTaskStatusResult

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | UUID | ✅ | 任务 ID |
| status | Enum | ✅ | 任务状态 |

#### PublishResultsResult

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| published | Int | ✅ | 已发布数量 |
| alreadyPublished | Int | ✅ | 已发布且跳过数量 |
| notified | Int | ✅ | 已通知数量 |

#### BatchResult

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| created | Int | ✅ | 成功创建数量 |
| failed | Int | ✅ | 失败数量 |

#### ValidationResult

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| valid | Boolean | ✅ | 校验结果 |
| message | String | ❌ | 校验提示 |

#### KpiWeightValidation

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| valid | Boolean | ✅ | 权重是否合规 |
| totalWeight | Decimal | ✅ | 权重总和 |

#### ResultsCalculateResult

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| calculated | Int | ✅ | 计算成功数量 |
| failed | Int | ✅ | 计算失败数量 |

#### ResultsExportResult

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| downloadUrl | String | ✅ | 下载地址 |
| expiresAt | DateTime | ✅ | 过期时间 |

#### ResultViewedResult

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | UUID | ✅ | 结果 ID |
| viewedByEmployee | Boolean | ✅ | 是否已查看 |

#### EvaluationEvaluatorResult

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| evaluationId | UUID | ✅ | 评估 ID |
| evaluatorId | UUID | ✅ | 评估人 ID |

#### CalibrationAdjustResult

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | UUID | ✅ | 记录 ID |
| finalGrade | String | ✅ | 最终等级代码 |

### 实体类型（与 06-data-model 一致）

#### PerformanceCycle

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | UUID | ✅ | 主键 |
| name | String | ✅ | 周期名称 |
| type | Enum | ✅ | 周期类型 |
| status | Enum | ✅ | 周期状态 |
| startDate | DateTime | ✅ | 开始日期 |
| endDate | DateTime | ✅ | 结束日期 |
| gradeConfigId | UUID | ❌ | 等级配置 ID |
| resultsPublishedAt | DateTime | ❌ | 结果发布时间 |
| resultsPublishedBy | UUID | ❌ | 结果发布人 |
| parentCycleId | UUID | ❌ | 父周期 ID（支持子周期结构） |
| organizationId | UUID | ✅ | 所属组织 ID |
| createdBy | UUID | ✅ | 创建人 |
| createdAt | DateTime | ✅ | 创建时间 |
| updatedAt | DateTime | ✅ | 更新时间 |
| deletedAt | DateTime | ❌ | 软删除时间 |

#### GradeConfig

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | UUID | ✅ | 主键 |
| name | String | ✅ | 配置名称 |
| description | String | ❌ | 配置描述 |
| grades | GradeItem[] | ✅ | 等级定义 |
| isDefault | Boolean | ✅ | 是否默认 |
| isActive | Boolean | ✅ | 是否启用 |
| organizationId | UUID | ❌ | 所属组织 ID（null = 平台级配置） |
| createdBy | UUID | ✅ | 创建人 |
| createdAt | DateTime | ✅ | 创建时间 |
| updatedAt | DateTime | ✅ | 更新时间 |
| deletedAt | DateTime | ❌ | 软删除时间 |

#### GradeItem

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| code | String | ✅ | 等级代码 |
| name | String | ✅ | 等级名称 |
| minScore | Decimal | ✅ | 最低分 |
| maxScore | Decimal | ✅ | 最高分 |
| color | String | ✅ | 颜色 |
| order | Int | ✅ | 顺序 |

#### PerformanceResult

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | UUID | ✅ | 主键 |
| cycleId | UUID | ✅ | 周期 ID |
| employeeId | UUID | ✅ | 员工 ID |
| kpiScore | Decimal | ❌ | KPI 得分 |
| kpiWeight | Decimal | ❌ | KPI 权重 |
| e360Score | Decimal | ❌ | 360 得分 |
| e360Weight | Decimal | ❌ | 360 权重 |
| totalScore | Decimal | ❌ | 总分（结果生成前可能为空） |
| gradeCode | String | ❌ | 等级代码（结果生成前可能为空） |
| gradeName | String | ❌ | 等级名称（结果生成前可能为空） |
| proposedGradeCode | String | ❌ | 汇总分数匹配的原始等级代码 |
| proposedGradeName | String | ❌ | 原始等级名称 |
| selfOverallComment | String | ❌ | 员工整体自评 |
| managerOverallComment | String | ❌ | 经理整体评语 |
| adjustmentLogs | GradeAdjustmentLog[] | ❌ | 等级调整日志 |
| isPublished | Boolean | ✅ | 是否发布 |
| publishedAt | DateTime | ❌ | 发布时间 |
| viewedByEmployee | Boolean | ✅ | 是否已查看 |
| viewedAt | DateTime | ❌ | 查看时间 |
| confirmStatus | Enum | ✅ | 确认状态（PENDING/CONFIRMED/APPEALED/APPEAL_RESOLVED） |
| appealReason | String | ❌ | 申诉原因 |
| appealResponse | String | ❌ | HR 申诉回复 |
| appealResolvedAt | DateTime | ❌ | 申诉处理时间 |
| remarks | String | ❌ | HR 备注 |
| organizationId | UUID | ✅ | 冗余组织 ID（简化分析查询） |
| createdAt | DateTime | ✅ | 创建时间 |
| updatedAt | DateTime | ✅ | 更新时间 |
| deletedAt | DateTime | ❌ | 软删除时间 |

#### KpiAssignment

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | UUID | ✅ | 主键 |
| cycleId | UUID | ✅ | 周期 ID |
| employeeId | UUID | ✅ | 员工 ID |
| name | String | ✅ | KPI 名称 |
| description | String | ❌ | KPI 描述 |
| weight | Decimal | ✅ | 权重 |
| unit | String | ❌ | 单位 |
| baseTarget | String | ❌ | 基本目标 |
| stretchTarget | String | ❌ | 挑战目标 |
| targetValue | Decimal | ❌ | 目标值（数值型） |
| parentId | UUID | ❌ | 父 KPI ID（支持层级结构） |
| seq | Int | ❌ | 排序序号 |
| status | Enum | ✅ | 审批状态（DRAFT/SUBMITTED/APPROVED/REJECTED） |
| maturityScore | Decimal | ❌ | 成熟度评分 |
| assessment | KpiAssessment | ❌ | 嵌套考核记录 |
| outgoingDependencies | KpiDependency[] | ❌ | 发起的跨部门依赖 |
| incomingDependencies | KpiDependency[] | ❌ | 收到的跨部门依赖 |
| createdAt | DateTime | ✅ | 创建时间 |
| updatedAt | DateTime | ✅ | 更新时间 |
| deletedAt | DateTime | ❌ | 软删除时间 |

#### KpiAssessment

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | UUID | ✅ | 主键 |
| assignmentId | UUID | ✅ | 关联分配 |
| status | Enum | ✅ | 状态（PENDING/SELF_EVALUATED/MANAGER_EVALUATED/CONFIRMED） |
| selfScore | Decimal | ❌ | 自评分数 |
| completionNote | String | ❌ | 完成情况说明 |
| selfComment | String | ❌ | 自评说明 |
| selfEvaluatedAt | DateTime | ❌ | 自评时间 |
| managerScore | Decimal | ❌ | 他评分数 |
| managerComment | String | ❌ | 他评说明 |
| managerId | UUID | ❌ | 评估经理 |
| managerEvaluatedAt | DateTime | ❌ | 他评时间 |
| finalScore | Decimal | ❌ | 最终分数 |
| deletedAt | DateTime | ❌ | 软删除时间 |

#### Evaluation360

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | UUID | ✅ | 主键 |
| cycleId | UUID | ✅ | 周期 ID |
| targetId | UUID | ✅ | 被评估者 ID |
| status | Enum | ✅ | 状态 |
| templateId | UUID | ❌ | 模板 ID |
| deadline | DateTime | ✅ | 截止日期 |
| minEvaluators | Int | ❌ | 最少评估人数 |
| createdBy | UUID | ✅ | 发起人 |
| createdAt | DateTime | ✅ | 创建时间 |
| updatedAt | DateTime | ✅ | 更新时间 |
| deletedAt | DateTime | ❌ | 软删除时间 |

#### EvaluationTask

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | UUID | ✅ | 主键 |
| evaluationId | UUID | ✅ | 评估 ID |
| evaluatorId | UUID | ✅ | 评估人 ID |
| relationType | Enum | ✅ | 关系类型 |
| status | Enum | ✅ | 任务状态 |
| isAnonymous | Boolean | ✅ | 是否匿名 |
| submittedAt | DateTime | ❌ | 提交时间 |
| createdAt | DateTime | ✅ | 创建时间 |
| deletedAt | DateTime | ❌ | 软删除时间 |

#### GradeAdjustmentLog

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | UUID | ✅ | 主键 |
| resultId | UUID | ✅ | 绩效结果 ID |
| previousGradeCode | String | ✅ | 调整前等级 |
| newGradeCode | String | ✅ | 调整后等级 |
| reason | String | ✅ | 调整原因 |
| adjustedBy | UUID | ✅ | 调整人 |
| adjustedAt | DateTime | ✅ | 调整时间 |
| deletedAt | DateTime | ❌ | 软删除时间 |

### 业务衍生与报表结构

#### CycleStatistics

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| kpi.totalAssignments | Int | ✅ | KPI 分配数 |
| e360.totalEvaluations | Int | ✅ | 360 评估数 |

#### GradeDistributionItem

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| gradeCode | String | ✅ | 等级代码 |
| count | Int | ✅ | 数量 |

#### CalibrationDistribution

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| totalEmployees | Int | ✅ | 总人数 |
| distribution | GradeDistributionItem[] | ✅ | 等级分布 |

#### CalibrationEmployeeItem

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| employeeId | UUID | ✅ | 员工 ID |
| currentGrade | String | ✅ | 当前等级代码 |

#### KpiAssignmentListItem

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | UUID | ✅ | 分配 ID |
| name | String | ✅ | KPI 名称 |
| employeeName | String | ❌ | 员工姓名 |
| weight | Decimal | ❌ | 权重 |
| targetValue | Decimal | ❌ | 目标值 |

#### KpiAssignmentTeamItem

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | UUID | ✅ | 分配 ID |
| employeeName | String | ✅ | 员工姓名 |
| name | String | ✅ | KPI 名称 |

#### EvaluationResult

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| overallScore | Decimal | ✅ | 总体得分 |

#### PerformanceResultListItem

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | UUID | ✅ | 结果 ID |
| gradeCode | String | ❌ | 等级代码 |
| totalScore | Decimal | ❌ | 总分 |

#### PerformanceResultAdminItem

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | UUID | ✅ | 结果 ID |
| employeeName | String | ✅ | 员工姓名 |

#### ReportPersonalSummary

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| avgScore | Decimal | ✅ | 平均分 |
| gradeCode | String | ✅ | 等级代码 |

#### ReportPersonalTrendItem

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| cycle | String | ✅ | 周期名称 |
| score | Decimal | ✅ | 得分 |

#### ReportTeamSummary

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| avgScore | Decimal | ✅ | 平均分 |
| distribution | GradeDistributionItem[] | ✅ | 等级分布 |

#### ReportDepartmentSummary

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| departmentId | UUID | ✅ | 部门 ID |
| avgScore | Decimal | ✅ | 平均分 |

#### ReportCompanySummary

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| avgScore | Decimal | ✅ | 平均分 |

#### ReportGradeDistribution

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| distribution | GradeDistributionItem[] | ✅ | 等级分布 |

#### ReportCycleComparisonItem

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| cycle | String | ✅ | 周期名称 |
| avgScore | Decimal | ✅ | 平均分 |

### 请求结构（字段级）

#### CreateGradeConfigRequest

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | String | ✅ | 配置名称 |
| description | String | ❌ | 配置描述 |
| grades | GradeItem[] | ✅ | 等级定义 |

#### UpdateGradeConfigRequest

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | String | ❌ | 配置名称 |
| description | String | ❌ | 配置描述 |
| grades | GradeItem[] | ❌ | 等级定义 |
| isActive | Boolean | ❌ | 是否启用 |

#### ValidateGradeConfigRequest

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| grades | GradeItem[] | ✅ | 等级定义 |

#### CreateCycleRequest

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | String | ✅ | 周期名称 |
| type | Enum | ✅ | 周期类型 |
| startDate | DateTime | ✅ | 开始日期 |
| endDate | DateTime | ✅ | 结束日期 |
| gradeConfigId | UUID | ❌ | 等级配置 ID |

#### UpdateCycleRequest

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | String | ❌ | 周期名称 |
| type | Enum | ❌ | 周期类型 |
| startDate | DateTime | ❌ | 开始日期 |
| endDate | DateTime | ❌ | 结束日期 |
| gradeConfigId | UUID | ❌ | 等级配置 ID |

#### PublishResultsRequest

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| employeeIds | UUID[] | ❌ | 员工 ID 列表 |
| notifyEmployees | Boolean | ❌ | 是否通知员工 |

#### CreateAssignmentRequest

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| cycleId | UUID | ✅ | 周期 ID |
| employeeId | UUID | ✅ | 员工 ID |
| name | String | ✅ | KPI 名称 |
| weight | Decimal | ✅ | 权重 |
| targetValue | Decimal | ❌ | 目标值 |

#### AssignmentInput

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | String | ✅ | KPI 名称 |
| weight | Decimal | ✅ | 权重 |
| targetValue | Decimal | ❌ | 目标值 |

#### BatchAssignRequest

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| cycleId | UUID | ✅ | 周期 ID |
| employeeIds | UUID[] | ✅ | 员工 ID 列表 |
| assignments | AssignmentInput[] | ✅ | 分配明细 |

#### UpdateAssignmentRequest

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | String | ❌ | KPI 名称 |
| weight | Decimal | ❌ | 权重 |
| targetValue | Decimal | ❌ | 目标值 |

#### UpdateQuarterTargetsRequest *(已废弃)*

> annualTargetValue 和 quarterTargets 字段已移除，此请求结构不再使用。

#### SelfEvaluateRequest

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| score | Decimal | ✅ | 自评分数 |
| comment | String | ❌ | 自评说明 |

#### ManagerEvaluateRequest

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| score | Decimal | ✅ | 他评分数 |
| comment | String | ❌ | 他评说明 |

#### CreateEvaluationRequest

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| cycleId | UUID | ✅ | 周期 ID |
| targetId | UUID | ✅ | 被评估者 ID |
| templateId | UUID | ❌ | 模板 ID |
| deadline | DateTime | ✅ | 截止日期 |
| minEvaluators | Int | ❌ | 最少评估人数 |
| evaluators | EvaluationEvaluatorInput[] | ❌ | 评估人列表 |

#### UpdateEvaluationRequest

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| deadline | DateTime | ❌ | 截止日期 |
| minEvaluators | Int | ❌ | 最少评估人数 |

#### EvaluationEvaluatorInput

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| evaluatorId | UUID | ✅ | 评估人 ID |
| relationType | Enum | ✅ | 关系类型 |
| isAnonymous | Boolean | ❌ | 是否匿名 |

#### SubmitEvaluationTaskRequest

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| responses | EvaluationResponseInput[] | ✅ | 评估明细 |

#### EvaluationResponseInput

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| dimension | String | ✅ | 评估维度 |
| score | Decimal | ✅ | 评分 |
| comment | String | ❌ | 评语 |

#### AdjustGradeRequest

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| resultId | UUID | ✅ | 绩效结果 ID |
| newGradeCode | String | ✅ | 新等级 |
| reason | String | ✅ | 调整原因 |

#### UpdateResultRemarksRequest

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| remarks | String | ✅ | 备注 |

#### CalculateResultsRequest

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| cycleId | UUID | ✅ | 周期 ID |
| weights | ResultWeights | ✅ | 权重 |
| employeeIds | UUID[] | ❌ | 员工 ID 列表 |

#### ResultWeights

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| kpi | Decimal | ✅ | KPI 权重 |
| e360 | Decimal | ✅ | 360 权重 |

#### ExportResultsRequest

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| cycleId | UUID | ✅ | 周期 ID |
| format | String | ✅ | 导出格式 |
| fields | String[] | ✅ | 导出字段 |

#### SubmitAllKpiRequest

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| employeeId | UUID | ✅ | 员工 ID |
| cycleId | UUID | ✅ | 周期 ID |

#### RejectKpiAssignmentRequest

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| reason | String | ✅ | 拒绝原因 |

#### RejectDependencyRequest

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| reason | String | ✅ | 拒绝原因 |

#### SaveOverallCommentRequest

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| cycleId | UUID | ✅ | 周期 ID |
| employeeId | UUID | ✅ | 员工 ID |
| selfOverallComment | String | ❌ | 员工整体自评（员工本人填写） |
| managerOverallComment | String | ❌ | 经理整体评语（经理填写） |

> 请求约束：selfOverallComment 和 managerOverallComment 必须二选一，至少提供一个。后端按当前用户角色校验：员工只能写 selfOverallComment，经理只能写 managerOverallComment。

#### CreateTemplateRequest

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | String | ✅ | 模板名称 |
| dimensions | JSON | ✅ | 评估维度定义 |
| description | String | ❌ | 模板描述 |

#### UpdateTemplateRequest

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | String | ❌ | 模板名称 |
| dimensions | JSON | ❌ | 评估维度定义 |
| description | String | ❌ | 模板描述 |

#### CreateStrategicObjectiveRequest

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| cycleId | UUID | ✅ | 周期 ID |
| name | String | ✅ | 目标名称 |
| description | String | ❌ | 目标描述 |
| departmentId | UUID | ❌ | 所属部门 |
| seq | Int | ❌ | 排序序号 |

#### UpdateStrategicObjectiveRequest

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | String | ❌ | 目标名称 |
| description | String | ❌ | 目标描述 |
| departmentId | UUID | ❌ | 所属部门 |
| seq | Int | ❌ | 排序序号 |

#### AssignStrategicObjectiveRequest

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| employeeIds | UUID[] | ✅ | 员工 ID 列表 |

#### CalibrationAdjustmentRequest

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| employeeId | UUID | ✅ | 员工 ID |
| cycleId | UUID | ✅ | 周期 ID |
| newGradeCode | String | ✅ | 调整后等级 |
| reason | String | ✅ | 调整原因 |

#### ConfirmResultRequest

（无请求体，使用路径参数 result ID）

#### AppealResultRequest

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| reason | String | ✅ | 申诉原因 |

### 新增响应结构

#### GoalSettingProgress

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| total | Int | ✅ | 总人数 |
| completed | Int | ✅ | 已完成数 |
| pending | Int | ✅ | 待完成数 |
| completionRate | Decimal | ✅ | 完成率 |

#### EvaluationProgress

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| total | Int | ✅ | 总人数 |
| selfEvaluated | Int | ✅ | 已自评数 |
| managerEvaluated | Int | ✅ | 已他评数 |
| completionRate | Decimal | ✅ | 完成率 |

#### CalibrationProgress

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| total | Int | ✅ | 总人数 |
| calibrated | Int | ✅ | 已校准数 |
| pending | Int | ✅ | 待校准数 |
| completionRate | Decimal | ✅ | 完成率 |

#### ResultsSummary

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| total | Int | ✅ | 总人数 |
| confirmed | Int | ✅ | 已确认数 |
| appealed | Int | ✅ | 申诉数 |
| distribution | GradeDistributionItem[] | ✅ | 等级分布 |

#### CalibrationOverview

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| totalEmployees | Int | ✅ | 总人数 |
| distribution | GradeDistributionItem[] | ✅ | 等级分布 |

#### ~~OverallComment~~（已废弃）

> 整体评语已合并到 PerformanceResult 实体（`selfOverallComment`、`managerOverallComment` 字段），不再是独立实体。保留此节仅用于说明旧接口命名的迁移去向，当前 API 不再返回该实体。参见 038g/038h 接口说明。

#### Template360

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | UUID | ✅ | 主键 |
| name | String | ✅ | 模板名称 |
| dimensions | JSON | ✅ | 评估维度定义 |
| description | String | ❌ | 模板描述 |
| relationshipTypes | JSON | ✅ | 可用关系类型数组 |
| isDefault | Boolean | ✅ | 是否默认 |
| isActive | Boolean | ✅ | 是否启用 |
| organizationId | UUID | ❌ | 所属组织 ID（null = 平台级模板） |
| createdBy | UUID | ✅ | 创建人 |
| createdAt | DateTime | ✅ | 创建时间 |
| updatedAt | DateTime | ✅ | 更新时间 |
| deletedAt | DateTime | ❌ | 软删除时间 |

#### StrategicObjective

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | UUID | ✅ | 主键 |
| cycleId | UUID | ✅ | 周期 ID |
| seq | Int | ✅ | 排序序号 |
| name | String | ✅ | 目标名称 |
| description | String | ❌ | 目标描述 |
| departmentId | UUID | ❌ | 所属部门 |
| createdBy | UUID | ✅ | 创建人 |
| createdAt | DateTime | ✅ | 创建时间 |
| updatedAt | DateTime | ✅ | 更新时间 |
| deletedAt | DateTime | ❌ | 软删除时间 |

#### KpiDependencyPending

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | UUID | ✅ | 依赖记录 ID（KpiDependency.id） |
| assignmentId | UUID | ✅ | 源 KPI 分配 ID（发起依赖的 KpiAssignment.id） |
| fromEmployee | IdName | ✅ | 发起人 |
| name | String | ✅ | KPI 名称 |
| status | String | ✅ | 状态 |

#### ConfirmResult

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | UUID | ✅ | 结果 ID |
| confirmStatus | String | ✅ | 确认状态（CONFIRMED） |
| confirmedAt | DateTime | ✅ | 确认时间 |

#### AppealResult

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | UUID | ✅ | 结果 ID |
| confirmStatus | String | ✅ | 确认状态（APPEALED） |
| appealReason | String | ✅ | 申诉原因 |
| appealedAt | DateTime | ✅ | 申诉时间 |

#### DepartmentReport

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| departmentId | UUID | ✅ | 部门 ID |
| departmentName | String | ✅ | 部门名称 |
| avgScore | Decimal | ✅ | 平均分 |
| distribution | GradeDistributionItem[] | ✅ | 等级分布 |
| employeeCount | Int | ✅ | 员工数量 |

---

## 统一格式 + 简短示例

### 1) 等级配置（9）

**[001] GET /grade-configs**
- 说明: 获取等级配置列表
- 请求 Query: { isActive? }
- 响应 Data: ListResult<GradeConfig>
- 示例请求: `GET /grade-configs?isActive=true`
- 示例响应: `{"success": true, "data": {"items": [{"id": "uuid", "name": "五级制"}]}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401, 403

**[002] GET /grade-configs/default**
- 说明: 获取默认等级配置
- 请求: 无
- 响应 Data: GradeConfig
- 示例请求: `GET /grade-configs/default`
- 示例响应: `{"success": true, "data": {"id": "uuid", "name": "五级制"}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401, 403, 404

**[003] GET /grade-configs/select**
- 说明: 获取等级下拉选项
- 请求: 无
- 响应 Data: IdName[]
- 示例请求: `GET /grade-configs/select`
- 示例响应: `{"success": true, "data": [{"id": "uuid", "name": "五级制"}], "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401, 403

**[004] GET /grade-configs/:id**
- 说明: 获取等级配置详情
- 请求 Path: { id }
- 响应 Data: GradeConfig
- 示例请求: `GET /grade-configs/uuid`
- 示例响应: `{"success": true, "data": {"id": "uuid", "name": "五级制"}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401, 403, 404

**[005] POST /grade-configs**
- 说明: 创建等级配置
- 请求 Body: CreateGradeConfigRequest
- 响应 Data: GradeConfig（完整资源对象）
- 示例请求: `{ "name": "四级制", "grades": [ { "code": "A", "minScore": 85, "maxScore": 100 } ] }`
- 示例响应: `{"success": true, "data": {"id": "uuid", "name": "四级制", "grades": [...]}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 201, 400, 401, 403, 422

**[006] PUT /grade-configs/:id**
- 说明: 更新等级配置
- 请求 Body: UpdateGradeConfigRequest
- 响应 Data: GradeConfig（完整资源对象）
- 示例请求: `{ "name": "四级制(更新)" }`
- 示例响应: `{"success": true, "data": {"id": "uuid", "name": "四级制(更新)", "grades": [...]}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 400, 401, 403, 404, 422

**[007] POST /grade-configs/:id/set-default**
- 说明: 设为默认配置
- 请求: 无
- 响应 Data: IdDefaultResult
- 示例请求: `POST /grade-configs/uuid/set-default`
- 示例响应: `{"success": true, "data": {"id": "uuid", "isDefault": true}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401, 403, 404, 409

**[008] DELETE /grade-configs/:id**
- 说明: 删除等级配置
- 请求: 无
- 响应 Data: IdResult
- 示例请求: `DELETE /grade-configs/uuid`
- 示例响应: `{"success": true, "data": {"id": "uuid"}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401, 403, 404, 409

**[009] POST /grade-configs/validate**
- 说明: 校验等级配置
- 请求 Body: ValidateGradeConfigRequest
- 响应 Data: ValidationResult
- 示例请求: `{ "grades": [ { "code": "A", "minScore": 90, "maxScore": 100 } ] }`
- 示例响应: `{"success": true, "data": {"valid": true}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 400, 401, 403

---

### 2) 周期管理（20）

**[010] GET /cycles**
- 说明: 获取周期列表
- 请求 Query: { status?, page?, pageSize? }
- 响应 Data: PageResult<PerformanceCycle>
- 示例请求: `GET /cycles?status=GOAL_SETTING&page=1&pageSize=20`
- 示例响应: `{"success": true, "data": {"items": [{"id": "uuid", "name": "2026 Q1"}], "total": 1, "page": 1, "limit": 20, "totalPages": 1, "hasNext": false, "hasPrev": false}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401

**[011] GET /cycles/select**
- 说明: 获取周期下拉列表
- 请求: 无
- 响应 Data: IdName[]
- 示例请求: `GET /cycles/select`
- 示例响应: `{"success": true, "data": [{"id": "uuid", "name": "2026 Q1"}], "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401

**[012] GET /cycles/active**
- 说明: 获取当前活跃周期
- 请求: 无
- 响应 Data: PerformanceCycle
- 示例请求: `GET /cycles/active`
- 示例响应: `{"success": true, "data": {"id": "uuid", "status": "IN_PROGRESS"}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401, 404

**[013] GET /cycles/:id**
- 说明: 获取周期详情
- 请求 Path: { id }
- 响应 Data: PerformanceCycle
- 示例请求: `GET /cycles/uuid`
- 示例响应: `{"success": true, "data": {"id": "uuid", "name": "2026 Q1"}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401, 404

**[014] GET /cycles/:id/statistics**
- 说明: 获取周期统计
- 请求 Path: { id }
- 响应 Data: CycleStatistics
- 示例请求: `GET /cycles/uuid/statistics`
- 示例响应: `{"success": true, "data": {"totalEmployees": 120, "kpiStats": {"total": 120, "selfEvaluated": 80, "managerEvaluated": 60, "confirmed": 40}, "evaluation360Stats": {"total": 10, "completed": 6, "pending": 4}}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401, 404

**[015] POST /cycles**
- 说明: 创建周期
- 请求 Body: CreateCycleRequest
- 响应 Data: PerformanceCycle（完整资源对象）
- 示例请求: `{ "name": "2026 Q1", "type": "QUARTERLY", "startDate": "2026-01-01", "endDate": "2026-03-31" }`
- 示例响应: `{"success": true, "data": {"id": "uuid", "name": "2026 Q1", "status": "DRAFT", "type": "QUARTERLY", "startDate": "2026-01-01", "endDate": "2026-03-31"}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 201, 400, 401, 403, 422

**[016] PUT /cycles/:id**
- 说明: 更新周期
- 请求 Body: UpdateCycleRequest
- 响应 Data: PerformanceCycle（完整资源对象）
- 示例请求: `{ "name": "2026 Q1（修订）" }`
- 示例响应: `{"success": true, "data": {"id": "uuid", "name": "2026 Q1（修订）", "status": "DRAFT"}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 400, 401, 403, 404, 409

**[017] POST /cycles/:id/publish**
- 说明: 发布周期
- 请求: 无
- 响应 Data: PerformanceCycle（完整资源对象）
- 示例请求: `POST /cycles/uuid/publish`
- 示例响应: `{"success": true, "data": {"id": "uuid", "name": "2026 Q1", "status": "GOAL_SETTING"}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401, 403, 404, 409

**[018] POST /cycles/:id/start-execution**
- 说明: 进入执行阶段
- 请求: 无
- 响应 Data: PerformanceCycle（完整资源对象）
- 示例请求: `POST /cycles/uuid/start-execution`
- 示例响应: `{"success": true, "data": {"id": "uuid", "name": "2026 Q1", "status": "IN_PROGRESS"}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401, 403, 404, 409

**[019] POST /cycles/:id/start-evaluation**
- 说明: 进入评估阶段
- 请求: 无
- 响应 Data: PerformanceCycle（完整资源对象）
- 示例请求: `POST /cycles/uuid/start-evaluation`
- 示例响应: `{"success": true, "data": {"id": "uuid", "name": "2026 Q1", "status": "EVALUATING"}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401, 403, 404, 409

**[020] POST /cycles/:id/start-calibration**
- 说明: 进入校准阶段
- 请求: 无
- 响应 Data: PerformanceCycle（完整资源对象）
- 示例请求: `POST /cycles/uuid/start-calibration`
- 示例响应: `{"success": true, "data": {"id": "uuid", "name": "2026 Q1", "status": "CALIBRATING"}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401, 403, 404, 409

**[020a] POST /cycles/:id/start-confirming**
- 说明: 发布结果，进入确认阶段（CALIBRATING → CONFIRMING）
- 请求: 无
- 响应 Data: PerformanceCycle（完整资源对象）
- 示例请求: `POST /cycles/uuid/start-confirming`
- 示例响应: `{"success": true, "data": {"id": "uuid", "name": "2026 Q1", "status": "CONFIRMING"}, "message": "success", "timestamp": "2026-03-14T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401, 403, 404, 409

**[021] POST /cycles/:id/complete**
- 说明: 完成周期
- 请求: 无
- 响应 Data: PerformanceCycle（完整资源对象）
- 示例请求: `POST /cycles/uuid/complete`
- 示例响应: `{"success": true, "data": {"id": "uuid", "name": "2026 Q1", "status": "COMPLETED"}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401, 403, 404, 409

**[022] POST /cycles/:id/publish-results**
- 说明: 发布绩效结果
- 请求 Body: PublishResultsRequest
- 响应 Data: PublishResultsResult
- 示例请求: `{ "employeeIds": ["u1"], "notifyEmployees": true }`
- 示例响应: `{"success": true, "data": {"published": 1, "alreadyPublished": 0, "notified": 1}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401, 403, 404, 409

**[023] POST /cycles/:id/archive**
- 说明: 归档周期
- 请求: 无
- 响应 Data: PerformanceCycle（完整资源对象）
- 示例请求: `POST /cycles/uuid/archive`
- 示例响应: `{"success": true, "data": {"id": "uuid", "name": "2026 Q1", "status": "ARCHIVED"}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401, 403, 404, 409

**[024] DELETE /cycles/:id**
- 说明: 删除周期
- 请求: 无
- 响应 Data: IdResult
- 示例请求: `DELETE /cycles/uuid`
- 示例响应: `{"success": true, "data": {"id": "uuid"}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401, 403, 404, 409

**[024a] GET /cycles/:id/goal-setting-progress**
- 说明: 获取目标设定进度
- 请求 Path: { id }
- 响应 Data: GoalSettingProgress
- 示例请求: `GET /cycles/uuid/goal-setting-progress`
- 示例响应: `{"success": true, "data": {"total": 50, "completed": 35, "pending": 15, "completionRate": 0.7}, "message": "success", "timestamp": "2026-03-14T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401, 403, 404

**[024b] GET /cycles/:id/evaluation-progress**
- 说明: 获取评估进度
- 请求 Path: { id }
- 响应 Data: EvaluationProgress
- 示例请求: `GET /cycles/uuid/evaluation-progress`
- 示例响应: `{"success": true, "data": {"total": 50, "selfEvaluated": 40, "managerEvaluated": 30, "completionRate": 0.6}, "message": "success", "timestamp": "2026-03-14T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401, 403, 404

**[024c] GET /cycles/:id/calibration-progress**
- 说明: 获取校准进度
- 请求 Path: { id }
- 响应 Data: CalibrationProgress
- 示例请求: `GET /cycles/uuid/calibration-progress`
- 示例响应: `{"success": true, "data": {"total": 50, "calibrated": 45, "pending": 5, "completionRate": 0.9}, "message": "success", "timestamp": "2026-03-14T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401, 403, 404

**[024d] GET /cycles/:id/cycle-results-summary**
- 说明: 获取周期结果汇总
- 请求 Path: { id }
- 响应 Data: ResultsSummary
- 示例请求: `GET /cycles/uuid/cycle-results-summary`
- 示例响应: `{"success": true, "data": {"total": 50, "confirmed": 40, "appealed": 2, "distribution": [{"gradeCode": "A", "count": 10}]}, "message": "success", "timestamp": "2026-03-14T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401, 403, 404

---

### 3) KPI 分配与目标（17）

**[030] GET /kpi/assignments**
- 说明: 获取分配列表
- 请求 Query: { cycleId?, employeeId?, page?, pageSize? }
- 响应 Data: PageResult<KpiAssignmentListItem>
- 示例请求: `GET /kpi/assignments?cycleId=uuid&page=1&pageSize=20`
- 示例响应: `{"success": true, "data": {"items": [{"id": "uuid", "name": "销售额完成率"}], "total": 1, "page": 1, "limit": 20, "totalPages": 1, "hasNext": false, "hasPrev": false}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401

**[031] GET /kpi/assignments/my**
- 说明: 获取我的分配
- 请求: 无
- 响应 Data: PageResult<KpiAssignmentListItem>
- 示例请求: `GET /kpi/assignments/my`
- 示例响应: `{"success": true, "data": {"items": [{"id": "uuid"}], "total": 1, "page": 1, "limit": 20, "totalPages": 1, "hasNext": false, "hasPrev": false}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401

**[032] GET /kpi/assignments/team**
- 说明: 获取团队分配
- 请求 Query: { cycleId? }
- 响应 Data: PageResult<KpiAssignmentTeamItem>
- 示例请求: `GET /kpi/assignments/team?cycleId=uuid`
- 示例响应: `{"success": true, "data": {"items": [{"id": "uuid", "employeeName": "张三"}], "total": 1, "page": 1, "limit": 20, "totalPages": 1, "hasNext": false, "hasPrev": false}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401, 403

**[033] GET /kpi/assignments/:id**（Out-of-scope：本轮前端无入口，后续版本规划）
- 说明: 获取分配详情
- 请求 Path: { id }
- 响应 Data: KpiAssignment
- 示例请求: `GET /kpi/assignments/uuid`
- 示例响应: `{"success": true, "data": {"id": "uuid", "name": "销售额完成率", "weight": 40}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401, 404

**[034] POST /kpi/assignments**
- 说明: 分配 KPI
- 请求 Body: CreateAssignmentRequest
- 响应 Data: KpiAssignment（完整资源对象，含 assessment）
- 示例请求: `{ "cycleId": "c1", "employeeId": "e1", "name": "销售额完成率", "weight": 40 }`
- 示例响应: `{"success": true, "data": {"id": "uuid", "cycleId": "c1", "employeeId": "e1", "name": "销售额完成率", "weight": 40, "assessment": {...}}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 201, 400, 401, 403, 409, 422

**[035] POST /kpi/assignments/batch**（Out-of-scope：本轮前端无入口，后续版本规划）
- 说明: 批量分配 KPI
- 请求 Body: BatchAssignRequest
- 响应 Data: BatchResult
- 示例请求: `{ "cycleId": "c1", "employeeIds": ["e1"], "assignments": [ { "name": "销售额完成率", "weight": 100 } ] }`
- 示例响应: `{"success": true, "data": {"created": 1, "failed": 0}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 201, 400, 401, 403, 409, 422

**[036] PUT /kpi/assignments/:id**
- 说明: 更新分配
- 请求 Body: UpdateAssignmentRequest
- 响应 Data: KpiAssignment（完整资源对象）
- 示例请求: `{ "weight": 50 }`
- 示例响应: `{"success": true, "data": {"id": "uuid", "name": "销售额完成率", "weight": 50, "assessment": {...}}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 400, 401, 403, 404, 409, 422

**[037] POST /kpi/assignments/:id/quarter-targets** *(已废弃)*
- 说明: ~~维护年度/季度目标~~ — annualTargetValue 和 quarterTargets 字段已移除。此接口保留但不再使用
- 请求 Body: UpdateQuarterTargetsRequest *(已废弃)*
- 响应 Data: KpiAssignment
- 示例请求: N/A
- 示例响应: N/A
- 状态码: 200, 400, 401, 403, 404, 422

**[038] GET /kpi/weight-validation**（Out-of-scope：本轮前端无入口，后续版本规划）
- 说明: 获取权重校验数据
- 请求 Query: { cycleId, employeeId }
- 响应 Data: KpiWeightValidation
- 示例请求: `GET /kpi/weight-validation?cycleId=c1&employeeId=e1`
- 示例响应: `{"success": true, "data": {"valid": true, "totalWeight": 100}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 400, 401

**[038a] POST /kpi/assignments/submit-all**
- 说明: 提交全部 KPI（员工完成目标设定后一次性提交）
- 请求 Body: SubmitAllKpiRequest
- 响应 Data: StatusResult
- 示例请求: `{ "employeeId": "e1", "cycleId": "c1" }`
- 示例响应: `{"success": true, "data": {"status": "SUBMITTED"}, "message": "success", "timestamp": "2026-03-14T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 400, 401, 403, 409

**[038b] POST /kpi/assignments/:id/approve**
- 说明: 批准 KPI 分配（经理审批）
- 请求: 无
- 响应 Data: StatusResult
- 示例请求: `POST /kpi/assignments/uuid/approve`
- 示例响应: `{"success": true, "data": {"status": "APPROVED"}, "message": "success", "timestamp": "2026-03-14T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401, 403, 404, 409

**[038c] POST /kpi/assignments/:id/reject**
- 说明: 拒绝 KPI 分配（经理驳回，需提供原因）
- 请求 Body: RejectKpiAssignmentRequest
- 响应 Data: StatusResult
- 示例请求: `{ "reason": "目标值设置不合理" }`
- 示例响应: `{"success": true, "data": {"status": "REJECTED"}, "message": "success", "timestamp": "2026-03-14T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 400, 401, 403, 404, 409

**[038d] GET /kpi/assignments/pending-dependency**
- 说明: 获取待确认的 KPI 依赖
- 请求 Query: { cycleId? }
- 响应 Data: ListResult<KpiDependencyPending>
- 示例请求: `GET /kpi/assignments/pending-dependency?cycleId=c1`
- 示例响应: `{"success": true, "data": {"items": [{"id": "uuid", "assignmentId": "a1", "fromEmployee": {"id": "e1", "name": "张三"}, "name": "销售额", "status": "PENDING"}]}, "message": "success", "timestamp": "2026-03-14T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401

**[038e] POST /kpi/assignments/:id/confirm-dependency**
- 说明: 确认 KPI 依赖
- 请求: 无
- 响应 Data: StatusResult
- 示例请求: `POST /kpi/assignments/uuid/confirm-dependency`
- 示例响应: `{"success": true, "data": {"status": "CONFIRMED"}, "message": "success", "timestamp": "2026-03-14T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401, 403, 404, 409

**[038f] POST /kpi/assignments/:id/reject-dependency**
- 说明: 拒绝 KPI 依赖（需提供原因）
- 请求 Body: RejectDependencyRequest
- 响应 Data: StatusResult
- 示例请求: `{ "reason": "该指标不属于我的职责范围" }`
- 示例响应: `{"success": true, "data": {"status": "REJECTED"}, "message": "success", "timestamp": "2026-03-14T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 400, 401, 403, 404, 409

**[038g] PATCH /results/overall-comment**
- 说明: 保存整体评语（upsert PerformanceResult 的评语字段，按 cycleId + employeeId 定位）
- 权限: selfOverallComment 仅本人可写，managerOverallComment 仅目标员工的经理可写
- 请求 Body: SaveOverallCommentRequest
- 响应 Data: PerformanceResult（完整资源对象）
- 示例请求: `{ "cycleId": "c1", "employeeId": "e1", "selfOverallComment": "整体表现优秀" }`
- 示例响应: `{"success": true, "data": {"id": "uuid", "cycleId": "c1", "employeeId": "e1", "selfOverallComment": "整体表现优秀", "managerOverallComment": null}, "message": "success", "timestamp": "2026-03-14T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 400, 401, 403

**[038h] GET /results/overall-comment**
- 说明: 获取整体评语（仅本人或其经理可查看）。实际返回 PerformanceResult 中的评语字段
- 请求 Query: { cycleId, employeeId }
- 响应 Data: `{ selfOverallComment: string | null, managerOverallComment: string | null }`
- 示例请求: `GET /results/overall-comment?cycleId=c1&employeeId=e1`
- 示例响应: `{"success": true, "data": {"selfOverallComment": "整体表现优秀", "managerOverallComment": null}, "message": "success", "timestamp": "2026-03-14T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401, 403

---

### 4) KPI 评估（4）

**[039] GET /kpi/assessments/:id**
- 说明: 获取考核详情
- 请求 Path: { id }
- 响应 Data: KpiAssessment
- 示例请求: `GET /kpi/assessments/uuid`
- 示例响应: `{"success": true, "data": {"id": "uuid", "status": "SELF_EVALUATED"}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401, 404

**[040] POST /kpi/assessments/:id/self-evaluate**
- 说明: 提交自评
- 请求 Body: SelfEvaluateRequest
- 响应 Data: KpiAssessment（完整资源对象）
- 示例请求: `{ "score": 85, "comment": "完成目标" }`
- 示例响应: `{"success": true, "data": {"id": "uuid", "status": "SELF_EVALUATED", "selfScore": 85, "selfComment": "完成目标"}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 400, 401, 403, 409

**[041] POST /kpi/assessments/:id/manager-evaluate**
- 说明: 提交他评
- 请求 Body: ManagerEvaluateRequest
- 响应 Data: KpiAssessment（完整资源对象）
- 示例请求: `{ "score": 80, "comment": "表现良好" }`
- 示例响应: `{"success": true, "data": {"id": "uuid", "status": "MANAGER_EVALUATED", "managerScore": 80, "managerComment": "表现良好", "finalScore": 81.5}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 400, 401, 403, 409

**[042] POST /kpi/assessments/:id/confirm**
- 说明: 确认评估结果
- 请求: 无
- 响应 Data: KpiAssessment（完整资源对象）
- 示例请求: `POST /kpi/assessments/uuid/confirm`
- 示例响应: `{"success": true, "data": {"id": "uuid", "status": "CONFIRMED", "finalScore": 81.5}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401, 403, 409

---

### 5) 360 评估（21）

**[043] GET /360/evaluations**
- 说明: 获取评估列表
- 请求 Query: { cycleId?, status?, page?, pageSize? }
- 响应 Data: PageResult<Evaluation360>
- 示例请求: `GET /360/evaluations?cycleId=c1&page=1&pageSize=20`
- 示例响应: `{"success": true, "data": {"items": [{"id": "uuid", "status": "IN_PROGRESS"}], "total": 1, "page": 1, "limit": 20, "totalPages": 1, "hasNext": false, "hasPrev": false}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401, 403

**[043a] GET /360/evaluations/summary**
- 说明: 获取 360 评估汇总
- 请求 Query: { cycleId? }
- 响应 Data: Evaluation360Summary
- 示例请求: `GET /360/evaluations/summary?cycleId=c1`
- 示例响应: `{"success": true, "data": {"total": 10, "completed": 6, "pending": 4}, "message": "success", "timestamp": "2026-03-14T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401, 403

**[043b] GET /360/evaluations/by-employee**
- 说明: 按员工获取 360 评估
- 请求 Query: { cycleId?, employeeId? }
- 响应 Data: ListResult<Evaluation360>
- 示例请求: `GET /360/evaluations/by-employee?cycleId=c1&employeeId=e1`
- 示例响应: `{"success": true, "data": {"items": [{"id": "uuid", "targetId": "e1", "status": "IN_PROGRESS"}]}, "message": "success", "timestamp": "2026-03-14T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401, 403

**[044] GET /360/evaluations/:id**
- 说明: 获取评估详情
- 请求 Path: { id }
- 响应 Data: Evaluation360
- 示例请求: `GET /360/evaluations/uuid`
- 示例响应: `{"success": true, "data": {"id": "uuid", "status": "IN_PROGRESS"}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401, 403, 404

**[045] POST /360/evaluations**
- 说明: 创建评估
- 请求 Body: CreateEvaluationRequest
- 响应 Data: Evaluation360（完整资源对象，含 tasks, template）
- 示例请求: `{ "cycleId": "c1", "targetId": "u1", "deadline": "2026-02-28" }`
- 示例响应: `{"success": true, "data": {"id": "uuid", "cycleId": "c1", "targetId": "u1", "status": "DRAFT", "tasks": [...], "template": {...}}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 201, 400, 401, 403, 422

**[046] PUT /360/evaluations/:id**
- 说明: 更新评估
- 请求 Body: UpdateEvaluationRequest
- 响应 Data: Evaluation360（完整资源对象）
- 示例请求: `{ "deadline": "2026-03-05" }`
- 示例响应: `{"success": true, "data": {"id": "uuid", "status": "DRAFT", "deadline": "2026-03-05"}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 400, 401, 403, 404, 409

**[047] DELETE /360/evaluations/:id**
- 说明: 删除评估
- 请求: 无
- 响应 Data: IdResult
- 示例请求: `DELETE /360/evaluations/uuid`
- 示例响应: `{"success": true, "data": {"id": "uuid"}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401, 403, 404, 409

**[048] POST /360/evaluations/:id/start**
- 说明: 开始评估
- 请求: 无
- 响应 Data: Evaluation360（完整资源对象）
- 示例请求: `POST /360/evaluations/uuid/start`
- 示例响应: `{"success": true, "data": {"id": "uuid", "status": "IN_PROGRESS", "tasks": [...]}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401, 403, 404, 409

**[049] POST /360/evaluations/:id/complete**
- 说明: 完成评估
- 请求: 无
- 响应 Data: Evaluation360（完整资源对象）
- 示例请求: `POST /360/evaluations/uuid/complete`
- 示例响应: `{"success": true, "data": {"id": "uuid", "status": "COMPLETED"}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401, 403, 404, 409

**[051] POST /360/evaluations/:id/evaluators**
- 说明: 添加评估人
- 请求 Body: EvaluationEvaluatorInput
- 响应 Data: EvaluationEvaluatorResult
- 示例请求: `{ "evaluatorId": "u2", "relationType": "PEER", "isAnonymous": true }`
- 示例响应: `{"success": true, "data": {"evaluationId": "uuid", "added": true}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 400, 401, 403, 404, 409

**[052] DELETE /360/evaluations/:evaluationId/evaluators/:evaluatorId**
- 说明: 移除评估人
- 请求: 无
- 响应 Data: EvaluationEvaluatorResult
- 示例请求: `DELETE /360/evaluations/uuid/evaluators/u2`
- 示例响应: `{"success": true, "data": {"evaluationId": "uuid", "evaluatorId": "u2"}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401, 403, 404, 409

**[053] GET /360/tasks**
- 说明: 获取评估任务列表
- 请求 Query: { evaluationId?, evaluatorId?, status? }
- 响应 Data: ListResult<EvaluationTask>
- 示例请求: `GET /360/tasks?status=PENDING`
- 示例响应: `{"success": true, "data": {"items": [{"id": "uuid", "status": "PENDING"}]}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401

**[054] GET /360/tasks/my**
- 说明: 获取我的评估任务
- 请求: 无
- 响应 Data: ListResult<EvaluationTask>
- 示例请求: `GET /360/tasks/my`
- 示例响应: `{"success": true, "data": {"items": [{"id": "uuid", "status": "PENDING"}]}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401

**[054a] GET /360/my-tasks**
- 说明: 获取我需要完成的反馈任务
- 请求 Query: { cycleId? }
- 响应 Data: ListResult<EvaluationTask>
- 示例请求: `GET /360/my-tasks?cycleId=c1`
- 示例响应: `{"success": true, "data": {"items": [{"id": "uuid", "status": "PENDING", "evaluationId": "eval1", "relationType": "PEER"}]}, "message": "success", "timestamp": "2026-03-14T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401

**[055] POST /360/tasks/:id/submit**
- 说明: 提交评估
- 请求 Body: SubmitEvaluationTaskRequest
- 响应 Data: EvaluationTaskStatusResult
- 示例请求: `{ "responses": [ { "dimension": "leadership", "score": 4 } ] }`
- 示例响应: `{"success": true, "data": {"id": "uuid", "status": "SUBMITTED"}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 400, 401, 403, 409, 422

**[056] GET /360/evaluations/:id/results**
- 说明: 获取评估结果
- 请求 Path: { id }
- 响应 Data: EvaluationResult
- 示例请求: `GET /360/evaluations/uuid/results`
- 示例响应: `{"success": true, "data": {"overallScore": 86.5}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401, 403, 404

**[056a] GET /360-templates**
- 说明: 获取 360 评估模板列表
- 请求: 无
- 响应 Data: ListResult<Template360>
- 示例请求: `GET /360-templates`
- 示例响应: `{"success": true, "data": {"items": [{"id": "uuid", "name": "标准360模板", "isDefault": true}]}, "message": "success", "timestamp": "2026-03-14T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401, 403

**[056b] POST /360-templates**
- 说明: 创建 360 评估模板
- 请求 Body: CreateTemplateRequest
- 响应 Data: IdResult
- 示例请求: `{ "name": "自定义模板", "dimensions": [{"name": "领导力", "weight": 30}] }`
- 示例响应: `{"success": true, "data": {"id": "uuid"}, "message": "success", "timestamp": "2026-03-14T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 201, 400, 401, 403, 422

**[056c] PATCH /360-templates/:id**
- 说明: 更新 360 评估模板
- 请求 Body: UpdateTemplateRequest
- 响应 Data: IdResult
- 示例请求: `{ "name": "更新后的模板" }`
- 示例响应: `{"success": true, "data": {"id": "uuid"}, "message": "success", "timestamp": "2026-03-14T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 400, 401, 403, 404

**[056d] DELETE /360-templates/:id**
- 说明: 删除 360 评估模板
- 请求: 无
- 响应 Data: IdResult
- 示例请求: `DELETE /360-templates/uuid`
- 示例响应: `{"success": true, "data": {"id": "uuid"}, "message": "success", "timestamp": "2026-03-14T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401, 403, 404, 409

**[056e] PATCH /360-templates/:id/set-default**
- 说明: 设为默认 360 评估模板
- 请求: 无
- 响应 Data: IdDefaultResult
- 示例请求: `PATCH /360-templates/uuid/set-default`
- 示例响应: `{"success": true, "data": {"id": "uuid", "isDefault": true}, "message": "success", "timestamp": "2026-03-14T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401, 403, 404, 409

---

### 6) 绩效校准（7）

**[067] POST /calibration/sessions/:id/adjust**
- 说明: 校准调整等级
- 请求 Body: AdjustGradeRequest
- 响应 Data: CalibrationAdjustResult
- 示例请求: `{ "resultId": "r1", "newGradeCode": "A", "reason": "校准调整" }`
- 示例响应: `{"success": true, "data": {"id": "uuid", "finalGrade": "A"}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 400, 401, 403, 404, 409

**[068] GET /calibration/sessions/:id/distribution**
- 说明: 获取等级分布
- 请求 Path: { id }
- 响应 Data: CalibrationDistribution
- 示例请求: `GET /calibration/sessions/uuid/distribution`
- 示例响应: `{"success": true, "data": {"totalEmployees": 50, "distribution": [{"gradeCode": "A", "count": 10}]}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401, 403, 404

**[069] GET /calibration/sessions/:id/logs**
- 说明: 获取调整日志
- 请求 Path: { id }
- 响应 Data: ListResult<GradeAdjustmentLog>
- 示例请求: `GET /calibration/sessions/uuid/logs`
- 示例响应: `{"success": true, "data": {"items": [{"id": "l1", "newGradeCode": "A"}]}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401, 403, 404

**[070] GET /calibration/sessions/:id/employees**
- 说明: 获取待校准员工
- 请求 Path: { id }
- 响应 Data: ListResult<CalibrationEmployeeItem>
- 示例请求: `GET /calibration/sessions/uuid/employees`
- 示例响应: `{"success": true, "data": {"items": [{"employeeId": "e1", "currentGrade": "B"}]}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401, 403, 404

**[071] GET /calibration/sessions/:id/validate-distribution**
- 说明: 校验分布
- 请求 Path: { id }
- 响应 Data: ValidationResult
- 示例请求: `GET /calibration/sessions/uuid/validate-distribution`
- 示例响应: `{"success": true, "data": {"valid": true, "message": "分布在可接受范围"}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401, 403, 404

**[071a] GET /calibration/overview**
- 说明: 获取校准概览（周期级别）
- 请求 Query: { cycleId }
- 响应 Data: CalibrationOverview
- 示例请求: `GET /calibration/overview?cycleId=c1`
- 示例响应: `{"success": true, "data": {"totalEmployees": 50, "distribution": [{"gradeCode": "A", "count": 10}, {"gradeCode": "B", "count": 25}]}, "message": "success", "timestamp": "2026-03-14T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 400, 401, 403

**[071b] POST /calibration/adjust**
- 说明: 保存校准调整
- 请求 Body: CalibrationAdjustmentRequest
- 响应 Data: CalibrationAdjustResult
- 示例请求: `{ "employeeId": "e1", "cycleId": "c1", "newGradeCode": "A", "reason": "绩效突出" }`
- 示例响应: `{"success": true, "data": {"id": "uuid", "finalGrade": "A"}, "message": "success", "timestamp": "2026-03-14T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 400, 401, 403, 404, 409

---

### 7) 绩效结果（11）

**[093] GET /results/my**
- 说明: 获取我的结果列表
- 请求 Query: { page?, pageSize? }
- 响应 Data: PageResult<PerformanceResultListItem>
- 示例请求: `GET /results/my?page=1&pageSize=20`
- 示例响应: `{"success": true, "data": {"items": [{"id": "r1", "gradeCode": "A"}], "total": 1, "page": 1, "limit": 20, "totalPages": 1, "hasNext": false, "hasPrev": false}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401

**[094] GET /results/my/:cycleId**
- 说明: 获取我的周期结果
- 请求 Path: { cycleId }
- 响应 Data: PerformanceResult
- 示例请求: `GET /results/my/c1`
- 示例响应: `{"success": true, "data": {"id": "r1", "totalScore": 85.5, "gradeCode": "A"}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401, 403, 404

**[095] POST /results/my/:id/viewed**
- 说明: 标记结果已查看
- 请求: 无
- 响应 Data: ResultViewedResult
- 示例请求: `POST /results/my/r1/viewed`
- 示例响应: `{"success": true, "data": {"id": "r1", "viewedByEmployee": true, "viewedAt": "2026-01-15T10:00:00Z"}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401, 403, 404

**[095a] POST /results/my/:id/confirm**
- 说明: 确认绩效结果
- 请求 Path: { id }（result ID）
- 响应 Data: ConfirmResult
- 示例请求: `POST /results/my/r1/confirm`
- 示例响应: `{"success": true, "data": {"id": "r1", "confirmStatus": "CONFIRMED", "confirmedAt": "2026-03-14T10:00:00Z"}, "message": "success", "timestamp": "2026-03-14T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401, 403, 404, 409

**[095b] POST /results/my/:id/appeal**
- 说明: 申诉绩效结果（需提供申诉原因）
- 请求 Path: { id }（result ID）
- 请求 Body: AppealResultRequest
- 响应 Data: AppealResult
- 示例请求: `{ "reason": "考核评分与实际工作成果不符" }`
- 示例响应: `{"success": true, "data": {"id": "r1", "confirmStatus": "APPEALED", "appealedAt": "2026-03-14T10:00:00Z"}, "message": "success", "timestamp": "2026-03-14T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 400, 401, 403, 404, 409

**[095c] POST /results/:id/resolve-appeal**
- 说明: HR 处理申诉（支持维持原判或调整等级/分数）
- 权限: result:publish
- 请求 Path: { id }（result ID）
- 请求 Body: { response: string, action: "MAINTAIN" | "ADJUST", adjustedGrade?: string, adjustedScore?: number }
- 响应 Data: PerformanceResult（完整资源对象，confirmStatus=APPEAL_RESOLVED）
- 示例请求: `{ "response": "经复核，维持原评定", "action": "MAINTAIN" }`
- 示例响应: `{"success": true, "data": {"id": "r1", "confirmStatus": "APPEAL_RESOLVED", "appealResponse": "经复核，维持原评定", "appealResolvedAt": "2026-03-14T10:00:00Z", "gradeCode": "B", "totalScore": 75.5}, "message": "success", "timestamp": "2026-03-14T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 400, 401, 403, 404, 409

**[096] GET /results**
- 说明: 获取结果列表
- 请求 Query: { cycleId, departmentId?, gradeCode?, isPublished?, page?, pageSize? }
- 响应 Data: PageResult<PerformanceResultAdminItem>
- 示例请求: `GET /results?cycleId=c1&page=1&pageSize=20`
- 示例响应: `{"success": true, "data": {"items": [{"id": "r1", "employeeName": "张三"}], "total": 1, "page": 1, "limit": 20, "totalPages": 1, "hasNext": false, "hasPrev": false}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401, 403

**[097] GET /results/:id**
- 说明: 获取结果详情
- 请求 Path: { id }
- 响应 Data: PerformanceResult
- 示例请求: `GET /results/r1`
- 示例响应: `{"success": true, "data": {"id": "r1", "totalScore": 85.5}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401, 403, 404

**[098] PUT /results/:id**
- 说明: 更新结果备注
- 请求 Body: UpdateResultRemarksRequest
- 响应 Data: PerformanceResult（完整资源对象）
- 示例请求: `{ "remarks": "表现稳定" }`
- 示例响应: `{"success": true, "data": {"id": "r1", "totalScore": 85.5, "gradeCode": "A", "remarks": "表现稳定"}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 400, 401, 403, 404

**[099] POST /results/calculate**（Out-of-scope：本轮前端无入口，后续版本规划）
- 说明: 计算绩效结果
- 请求 Body: CalculateResultsRequest
- 响应 Data: ResultsCalculateResult
- 示例请求: `{ "cycleId": "c1", "weights": { "kpi": 80, "e360": 20 } }`
- 示例响应: `{"success": true, "data": {"calculated": 10, "failed": 0}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 400, 401, 403, 409

**[100] POST /results/export**
- 说明: 导出绩效结果
- 请求 Body: ExportResultsRequest
- 响应 Data: ResultsExportResult
- 示例请求: `{ "cycleId": "c1", "format": "xlsx", "fields": ["employeeName", "totalScore"] }`
- 示例响应: `{"success": true, "data": {"downloadUrl": "https://...", "expiresAt": "2026-04-01T15:00:00Z"}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 400, 401, 403

---

### 8) 统计分析（8）

**[101] GET /reports/personal**（Out-of-scope：本轮前端无入口，后续版本规划）
- 说明: 获取个人绩效概览
- 请求 Query: { cycleId? }
- 响应 Data: ReportPersonalSummary
- 示例请求: `GET /reports/personal?cycleId=c1`
- 示例响应: `{"success": true, "data": {"avgScore": 82.5, "gradeCode": "B"}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401

**[102] GET /reports/personal/trend**（Out-of-scope：本轮前端无入口，后续版本规划）
- 说明: 获取个人绩效趋势
- 请求 Query: { limit? }
- 响应 Data: ListResult<ReportPersonalTrendItem>
- 示例请求: `GET /reports/personal/trend?limit=4`
- 示例响应: `{"success": true, "data": {"items": [{"cycle": "2026 Q1", "score": 85}]}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401

**[103] GET /reports/team**（Out-of-scope：本轮前端无入口，后续版本规划）
- 说明: 获取团队绩效报表
- 请求 Query: { cycleId? }
- 响应 Data: ReportTeamSummary
- 示例请求: `GET /reports/team?cycleId=c1`
- 示例响应: `{"success": true, "data": {"avgScore": 80.2, "distribution": [{"gradeCode": "A", "count": 3}]}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401, 403

**[104] GET /reports/department**（Out-of-scope：本轮前端无入口，后续版本规划）
- 说明: 获取部门绩效报表
- 请求 Query: { departmentId, cycleId }
- 响应 Data: ReportDepartmentSummary
- 示例请求: `GET /reports/department?departmentId=d1&cycleId=c1`
- 示例响应: `{"success": true, "data": {"departmentId": "d1", "avgScore": 78.0}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 400, 401, 403

**[105] GET /reports/company**
- 说明: 获取公司绩效报表
- 请求 Query: { cycleId }
- 响应 Data: ReportCompanySummary
- 示例请求: `GET /reports/company?cycleId=c1`
- 示例响应: `{"success": true, "data": {"avgScore": 81.0}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 400, 401, 403

**[106] GET /reports/grade-distribution**（Out-of-scope：本轮前端无入口，后续版本规划）
- 说明: 获取等级分布报表
- 请求 Query: { cycleId, departmentId? }
- 响应 Data: ReportGradeDistribution
- 示例请求: `GET /reports/grade-distribution?cycleId=c1`
- 示例响应: `{"success": true, "data": {"distribution": [{"gradeCode": "A", "count": 10}]}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 400, 401, 403

**[107] GET /reports/cycle-comparison**（Out-of-scope：本轮前端无入口，后续版本规划）
- 说明: 获取周期对比报表
- 请求 Query: { cycleIds }
- 响应 Data: ListResult<ReportCycleComparisonItem>
- 示例请求: `GET /reports/cycle-comparison?cycleIds=c1,c2`
- 示例响应: `{"success": true, "data": {"items": [{"cycle": "2026 Q1", "avgScore": 82}]}, "message": "success", "timestamp": "2026-01-15T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 400, 401, 403

**[107a] GET /reports/department/:deptId**
- 说明: 获取指定部门绩效报表
- 请求 Path: { deptId }
- 请求 Query: { cycleId }
- 响应 Data: DepartmentReport
- 示例请求: `GET /reports/department/d1?cycleId=c1`
- 示例响应: `{"success": true, "data": {"departmentId": "d1", "departmentName": "销售部", "avgScore": 82.5, "distribution": [{"gradeCode": "A", "count": 5}], "employeeCount": 20}, "message": "success", "timestamp": "2026-03-14T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 400, 401, 403, 404

---

### 9) 战略目标（6）

**[108] GET /strategic-objectives**
- 说明: 获取战略目标列表
- 请求 Query: { cycleId }
- 响应 Data: ListResult<StrategicObjective>
- 示例请求: `GET /strategic-objectives?cycleId=c1`
- 示例响应: `{"success": true, "data": {"items": [{"id": "uuid", "name": "提升市场份额", "cycleId": "c1"}]}, "message": "success", "timestamp": "2026-03-14T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401, 403

**[108a] GET /strategic-objectives/:id**
- 说明: 获取战略目标详情
- 请求 Path: { id }
- 响应 Data: StrategicObjective
- 示例请求: `GET /strategic-objectives/uuid`
- 示例响应: `{"success": true, "data": {"id": "uuid", "cycleId": "c1", "name": "提升市场份额", "description": "将市场份额提升至30%", "seq": 1}, "message": "success", "timestamp": "2026-03-14T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 401, 403, 404

**[109] POST /strategic-objectives**
- 说明: 创建战略目标
- 请求 Body: CreateStrategicObjectiveRequest
- 响应 Data: StrategicObjective（完整资源对象）
- 示例请求: `{ "cycleId": "c1", "name": "提升市场份额", "description": "将市场份额提升至30%" }`
- 示例响应: `{"success": true, "data": {"id": "uuid", "cycleId": "c1", "name": "提升市场份额", "description": "将市场份额提升至30%", "seq": 0}, "message": "success", "timestamp": "2026-03-14T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 201, 400, 401, 403, 422

**[110] PUT /strategic-objectives/:id**
- 说明: 更新战略目标
- 请求 Body: UpdateStrategicObjectiveRequest
- 响应 Data: StrategicObjective（完整资源对象）
- 示例请求: `{ "name": "提升市场份额（修订）" }`
- 示例响应: `{"success": true, "data": {"id": "uuid", "name": "提升市场份额（修订）"}, "message": "success", "timestamp": "2026-03-14T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 200, 400, 401, 403, 404

**[111] DELETE /strategic-objectives/:id**
- 说明: 删除战略目标
- 请求: 无
- 响应: 无（204 No Content）
- 示例请求: `DELETE /strategic-objectives/uuid`
- 状态码: 204, 401, 403, 404

**[112] POST /strategic-objectives/:id/assign**
- 说明: 分配战略目标给员工
- 请求 Body: `{ "assigneeIds": ["uuid1", "uuid2"] }`
- 响应 Data: StrategicObjective（完整资源对象，含 assignments）
- 示例请求: `{ "assigneeIds": ["e1", "e2"] }`
- 示例响应: `{"success": true, "data": {"id": "uuid", "name": "提升市场份额", "assignments": [...]}, "message": "success", "timestamp": "2026-03-14T10:00:00Z", "path": "/api/v1/performance/<path>"}`
- 状态码: 201, 400, 401, 403, 404

---

**创建时间**: 2025-12-25
**更新时间**: 2026-03-20
**状态**: Active
**版本**: v4.3