# 绩效管理模块 - 架构设计文档

> **module**: performance
> **doc_type**: Architecture
> **status**: Active
> **owner**: FFOA 开发团队
> **upstream_docs**: 01-prd.md, 02-user-journey.md
> **last_verified**: 2026-03-19

---

## 架构摘要


| 字段     | 内容                              |
| ------ | ------------------------------- |
| 模块定位   | 统一承载绩效周期、KPI、360、校准、结果、统计与配置管理  |
| 前端入口   | `/performance` 及其子路由            |
| 后端入口   | `/api/v1/performance/`*         |
| 当前实现重点 | 周期管理、KPI、360、校准、结果、统计、等级配置、战略目标 |
| 当前非重点  | 面谈、持续反馈、独立指标库页面、独立员工结果页         |
| 主聚合根   | Cycle（周期）；次级核心实体：KpiAssignment、KpiAssessment、Evaluation360、CalibrationAdjustment、PerformanceResult |
| 关键依赖   | IAM、Organization                |


---

## 分层边界

### 前端层

- 基于 Next.js App Router 的模块页面
- 页面负责展示、用户交互和调用 API 服务
- 公共组件集中在 `frontend/src/app/(modules)/performance/_components`

### 应用层

- 后端 Controller 负责 HTTP 路由、鉴权入口和 DTO 接收
- 不在 Controller 内堆积业务判断

### 领域层

- Service 负责状态流转、业务校验、聚合读写和跨实体编排
- 关键业务域包括：
  - 周期
  - KPI
  - 360
  - 校准
  - 结果
  - 报表
  - 模板/配置

### 基础设施层

- Prisma 负责持久化
- Organization 模块提供组织与成员关系

---

## 当前后端结构

### 模块入口

- `backend/src/modules/performance/performance.module.ts`

### 当前控制器


| 控制器                                    | 说明               |
| -------------------------------------- | ---------------- |
| `cycle.controller.ts`                  | 周期管理与状态推进        |
| `kpi.controller.ts`                    | KPI 分配、审批、评估等    |
| `evaluation360.controller.ts`          | 360 评估主流程        |
| `evaluation360-template.controller.ts` | 360 模板管理         |
| `calibration.controller.ts`            | 校准看板与等级调整        |
| `result.controller.ts`                 | 结果发布、导出、确认       |
| `grade-config.controller.ts`           | 等级配置管理           |
| `analytics.controller.ts`              | 统计分析报表           |
| `strategic-objective.controller.ts`    | 战略目标管理           |
| `overall-eval-comment.controller.ts`   | 整体评语             |


### 当前服务


| 服务                             | 责任                    |
| ------------------------------ | --------------------- |
| `CycleService`                 | 周期创建、发布、阶段流转、进度统计     |
| `KpiService`                   | KPI 新增、审批、依赖确认、自评/经理评 |
| `Evaluation360Service`         | 360 评估创建、任务分发、问卷提交、汇总 |
| `Evaluation360TemplateService` | 模板 CRUD 和默认模板管理       |
| `CalibrationService`           | 校准看板、等级调整、分布展示        |
| `ResultService`                | 结果计算、发布、确认、申诉、导出      |
| `GradeConfigService`           | 等级配置校验和默认配置维护         |
| `AnalyticsService`             | 部门/公司报表查询             |
| `StrategicObjectiveService`    | 战略目标与分配维护             |
| `OverallEvalCommentService`    | 员工/经理整体评语读写           |


---

## 当前前端结构

### 已使用页面


| 页面       | 路由                                    | 说明             |
| -------- | ------------------------------------- | -------------- |
| 绩效概览     | `/performance`                        | 个人概览、待办、结果入口   |
| 管理概览     | `/performance/admin`                  | 周期推进和管理看板      |
| 周期管理     | `/performance/cycles`                 | 周期列表与创建        |
| 我的 KPI   | `/performance/kpi`                    | KPI 维护、自评、依赖确认 |
| 团队 KPI   | `/performance/kpi/team`               | 审批与经理评分        |
| 360 评估   | `/performance/360`                    | 任务列表与个人结果      |
| 360 评估详情 | `/performance/360/[id]`               | 评估详情与管理        |
| 校准管理     | `/performance/calibration`            | 校准列表           |
| 校准看板     | `/performance/calibration/[id]`       | 校准看板（等级分布与调整）  |
| 结果管理     | `/performance/results/admin`          | 发布和导出结果        |
| 统计分析     | `/performance/analytics`              | 部门/公司报表        |
| 战略目标     | `/performance/strategic-objectives`   | 目标管理           |
| 等级设置     | `/performance/settings/grades`        | 等级配置           |
| 360 模板设置 | `/performance/settings/360-templates` | 模板配置           |


### 已明确不存在或不作为当前入口的页面

- `/performance/cycles/create`
- `/performance/cycles/:id`
- `/performance/kpi/indicators`
- `/performance/results`（非 admin）

---

## 关键数据流

### 周期主流程

1. HR 创建并发布周期
2. 员工在目标设定阶段维护 KPI
3. 经理审批 KPI
4. 周期进入评估阶段，员工和经理完成评分
5. 360 数据补充结果视角
6. HR 校准等级
7. HR 发布结果，员工确认或申诉
8. HR 完成并归档周期

### 结果流

1. KPI 评分和 360 数据完成
2. 校准阶段修正等级
3. 结果管理页发布结果
4. 员工查看、确认或申诉

---

## 集成边界


| 依赖模块         | 当前用途              |
| ------------ | ----------------- |
| IAM          | 登录态、权限控制          |
| Organization | 组织切换、上下级关系、部门维度报表 |


---

## 当前版本的架构约束

- 当前事实源以 `04-state-machine.md`、`05-ui-interaction-spec.md`、`06-data-model.md`、`07-api.md` 为准
- 不允许根据历史文档恢复已移除的前端入口
- 所有写操作 API（状态推进、发布结果、确认申诉、调整等级等）必须返回完整资源对象，不能只回局部字段

---

## 实施阶段

> 新功能和大改动按 Phase 顺序实施，前一阶段验证通过后再进入下一阶段；小修复（bugfix、局部补丁）可直接跳到受影响阶段，但必须验证上游依赖未被破坏。

### Phase 1: 基础数据层

- **内容**: 等级配置（F8）+ 周期管理（F1）+ 战略目标（F9）
- **依赖**: 无（IAM 和组织架构为外部依赖，假设已就绪）
- **影响范围**: `grade-config.controller/service`、`cycle.controller/service`、`strategic-objective.controller/service`；前端 `/performance/cycles`、`/performance/settings/grades`、`/performance/strategic-objectives`
- **验证**: 等级配置 CRUD 可用，周期可创建并推进状态，战略目标可管理

### Phase 2: KPI 核心流程

- **内容**: KPI 目标设定（F2）+ 跨部门依赖 + KPI 审批
- **依赖**: Phase 1（需要周期处于 GOAL_SETTING 状态）
- **影响范围**: `kpi.controller/service`；前端 `/performance/kpi`、`/performance/kpi/team`
- **验证**: 员工可创建 KPI、提交审批、经理可审批/驳回，跨部门依赖可确认

### Phase 3: 评估与 360

- **内容**: 绩效评估（F3）+ 360 评估（F7）+ 360 模板管理
- **依赖**: Phase 2（需要 KPI 已审批通过，周期处于 EVALUATING）
- **影响范围**: `kpi.controller/service`（自评/经理评）、`evaluation360.controller/service`、`evaluation360-template.controller/service`、`overall-eval-comment.controller/service`；前端 `/performance/kpi`、`/performance/kpi/team`、`/performance/360`、`/performance/settings/360-templates`
- **验证**: 自评/经理评分可用，360 评估人可配置，评估可完成并汇总

### Phase 4: 校准与结果

- **内容**: 绩效校准（F4）+ 结果发布与确认（F6）
- **依赖**: Phase 3（需要评估完成，周期处于 CALIBRATING）
- **影响范围**: `calibration.controller/service`、`result.controller/service`；前端 `/performance/calibration`、`/performance/calibration/[id]`、`/performance/results/admin`
- **验证**: 校准看板可查看分布并调整等级，结果可发布，员工可确认/申诉

### Phase 5: 统计与报表

- **内容**: 统计分析（F5）
- **依赖**: Phase 4（需要有已完成的周期数据）
- **影响范围**: `analytics.controller/service`；前端 `/performance/analytics`
- **验证**: 部门/公司报表可查看，数据准确