# OKR 绩效考核系统 — 设计文档

## 概述

医梦AI 内部绩效考核系统。OKR(40%) + KPI(60%) 双轨模型，树形汇报权限，同屏联动展示。独立部署、本地 SQLite 存储、单 JAR 一键启动。

## 技术栈

| 层 | 选型 | 版本 |
|---|------|------|
| 运行时 | JDK | 17 LTS |
| 后端框架 | Spring Boot | 3.2.x |
| ORM | MyBatis-Plus | 3.5.x |
| 数据库 | SQLite (WAL 模式) | — |
| 认证 | Spring Security + JWT | 6.x |
| 前端框架 | Vue 3 + Composition API | 3.4+ |
| UI 库 | Element Plus | 2.6+ |
| 构建工具 | Vite + Maven | — |
| 状态管理 | Pinia | 2.x |

## 部署架构

**单 JAR 部署**：Vue 打包产物放入 Spring Boot `static` 目录，`java -jar` 同时服务前端和后端 API。

- 默认端口：18080（可通过 `application.yml` 中 `server.port` 修改）
- 部署物：1 个 jar + 1 个 `.db` 文件
- 迁移：拷贝上述两个文件
- 一键启动：`./start.sh`（内部执行 `npm build` → `mvn package` → `java -jar`）
- 开发模式：前端 `:5173` 代理到后端 `:8080`，热更新

## 项目结构

```
okr-performance/
├── backend/                         # Spring Boot 3.x
│   ├── pom.xml
│   └── src/main/java/com/yimeng/okr/
│       ├── OkrApplication.java
│       ├── config/                  # Security, CORS, MyBatis-Plus
│       ├── security/                # JWT Filter, TokenProvider
│       ├── controller/              # REST 控制器
│       ├── service/                 # 业务逻辑
│       ├── mapper/                  # MyBatis-Plus Mapper
│       ├── entity/                  # 数据库实体
│       ├── dto/                     # 请求/响应 DTO
│       ├── enums/                   # 枚举
│       ├── exception/               # 全局异常处理
│       └── schedule/                # 定时任务
├── frontend/                        # Vue 3 + Vite
│   └── src/
│       ├── router/                  # Vue Router
│       ├── stores/                  # Pinia
│       ├── api/                     # Axios + API 模块
│       ├── views/                   # 页面组件
│       ├── components/              # 通用组件
│       ├── composables/             # 组合函数
│       └── assets/                  # 静态资源（含 logo）
├── data/                            # SQLite 数据库文件目录
├── scripts/start.sh                 # 一键启动脚本
└── docs/
```

## 路由与菜单

**侧边栏三组菜单，基于角色动态显示：**

| 分组 | 菜单项 | 路由 | 可见角色 |
|------|--------|------|----------|
| 工作台 | 考核周期 | /periods | 全部 |
| | 我的 OKR | /okr/my | 全部 |
| | 我的绩效 | /scores/my | 全部 |
| 考评管理 | 绩效打分 | /scoring | 上级（有下属者） |
| | 绩效沟通 | /feedback | 上级 |
| 系统管理 | 组织架构 | /org | 超级管理员 |
| | KPI 模板库 | /kpi/templates | 上级 + 管理员 |
| | 操作日志 | /system/logs | 超级管理员 |
| | 数据备份 | /system/backup | 超级管理员 |

## 数据模型（12 张核心表）

1. **sys_user** — 用户账号：id, username, password_hash, real_name, position, department_id, superior_id, role(EMPLOYEE/SUPER_ADMIN), created_at
2. **sys_department** — 部门：id, name, parent_id, leader_id, sort_order
3. **assessment_period** — 考核周期：id, name, start_date, end_date, status(DRAFT→OKR_ALIGN→EXECUTING→ASSESSING→ARCHIVED), created_by
4. **okr_objective** — 目标 O：id, period_id, user_id, dept_id, type(DEPT/PERSONAL), title, status, version, snapshot_json, reviewed_by, reviewed_at
5. **kr_key_result** — 关键结果 KR：id, objective_id, title, target_value, current_value, status(NOT_STARTED/IN_PROGRESS/COMPLETED/BLOCKED), weight
6. **kr_progress_log** — KR 进度更新：id, kr_id, old_value, new_value, old_status, new_status, remark, updated_by, created_at
7. **kpi_template** — KPI 模板：id, name, category, items_json, created_by
8. **kpi_config** — 个人 KPI 配置：id, period_id, user_id, items_json, version, snapshot_json, locked_at
9. **performance_score** — 绩效打分：id, period_id, user_id, evaluator_id, okr_score(0-40), kpi_score(0-60), bonus, penalty, total, grade(S/A/B/C), type(SELF/SUPERIOR/FINAL), comments_json
10. **performance_feedback** — 面谈反馈：id, period_id, user_id, superior_id, interview_notes, highlights, issues, improvements, employee_feedback
11. **operation_log** — 操作日志：id, operator_id, action, entity_type, entity_id, old_data_json, new_data_json, ip, created_at
12. **audit_correction** — 修正记录：id, performance_id, correction_type, old_values_json, new_values_json, reason, operated_by, created_at

**关键设计决策：**
- OKR 目标和 KPI 配置在归档时写入 `snapshot_json` 字段，历史周期数据不受后续修改影响
- 数据"不可修改"语义通过 `audit_correction` 表实现——原记录逻辑删除，修正写入新表，全程留痕
- `performance_score.type` 区分自评(SELF)、上级初审(SUPERIOR)、最终结果(FINAL)

## 状态机

```
待发布 → OKR对齐 → 执行中 → 考评中 → 已归档
```

| 转换 | 触发方式 | 行为 |
|------|----------|------|
| 待发布→OKR对齐 | 管理员手动 | 为全员创建空白OKR记录，部门OKR可发布 |
| OKR对齐→执行中 | 管理员手动（或周期开始日自动） | 员工OKR锁定，不可修改 |
| 执行中→考评中 | 周期结束日自动（定时任务） | 员工可自评，上级可打分 |
| 考评中→已归档 | 管理员手动 | 数据快照，锁定不可修改 |

## 权限模型

不预设固定角色。权限完全基于 `sys_user.superior_id` 树形汇报关系动态生效：

- **普通员工**（无下属）：个人 OKR/绩效/反馈 增改查，无打分权限
- **直属上级**（有下属）：对 direct reports 拥有 OKR 审核、绩效打分、面谈记录、数据查看权限；权限代码 `WHERE evaluated_user.superior_id = current_user.id`
- **超级管理员**（role=SUPER_ADMIN）：全局最高权限，周期创建、组织架构维护、日志查看、备份恢复

## API 设计（约 45 个端点）

| 模块 | 前缀 | 核心端点 |
|------|------|----------|
| Auth | /api/auth | POST login, register; GET me; PUT password |
| 组织架构 | /api/org | CRUD departments; PUT members, superior |
| 考核周期 | /api/periods | CRUD periods; PUT status; GET progress |
| OKR | /api/okr | CRUD objectives & krs; POST submit; PUT review, progress |
| KPI | /api/kpi | CRUD templates, configs |
| 绩效打分 | /api/scores | POST self, superior; GET my (含 OKR 联动) |
| 绩效反馈 | /api/feedback | POST interview, reply; GET by id |
| 系统 | /api/system | GET logs; POST backup, restore |

所有打分相关 GET 端点返回当期 OKR 完整记录，实现同屏联动。

## UI 布局规则

- **主题色**：深 #2b1f99（侧边栏/强调），浅 #3ad4d8（高亮/操作唤醒）
- **侧边栏**：220px 宽，深色渐变，三组菜单分区
- **同屏页面（打分/反馈）**：宽屏(≥1440px)左右分栏（OKR记录 48% + 打分区 52%），窄屏(<1440px)上下分区（OKR可折叠面板 + 打分区）
- **Logo**：侧边栏顶部 + 登录页使用

## 一期范围（核心闭环）

纳入：账号与组织 → 考核周期 → OKR 管理 → KPI 配置 → 绩效打分（同屏） → 绩效反馈（同屏） → 操作日志
预留：数据统计与分析、自动备份、KPI 模板库完善、历史趋势曲线