# OKR 绩效系统全链路重构设计

**日期**：2026-07-06
**状态**：已确认
**视觉方向**：Surgical Observatory / 手术观测台
**适用范围**：全部 Web 页面、必要的后端接口与 SQLite 数据迁移

![手术观测台视觉方向](./assets/2026-07-06-surgical-observatory.png)

## 1. 目标

本轮重构不只统一视觉，而是以前端体验为出发点，重新梳理 OKR 制定、审核、执行、绩效评审、面谈、确认与申诉的完整闭环。

完成后系统应具备以下特征：

- 呈现高端科技公司、AI 智慧医疗、优雅克制的产品气质。
- 使用深色科技外壳和冷白临床数据工作区。
- 保持高信息密度，同时通过网格、留白、字重和分隔线建立秩序。
- 用户始终知道当前周期、当前阶段、待办事项和下一步操作。
- 前端不再重复拼装周期、权限和流程状态。
- 后端接口直接支持页面工作流，必要时允许新增接口、字段和表。
- 现有 SQLite 数据必须无损保留。
- 保持单 JAR 部署方式。

## 2. 硬性约束

### 2.1 业务约束

- 周期主状态机保持：

  `DRAFT → OKR_ALIGN → EXECUTING → ASSESSING → ARCHIVED`

- OKR 评分满分 60。
- 绩效维度评分满分 40。
- 加分、扣分和等级规则保持当前实现。
- 权限继续以组织上下级关系为主，`SUPER_ADMIN` 保留绕过能力。
- 历史归档数据不可因模板、组织或目标后续变更而失真。
- 评分修正必须进入 `audit_correction`，不得覆盖审计历史。

### 2.2 技术约束

- 前端继续使用 Vue 3、Vite、Pinia、Element Plus。
- 后端继续使用 Spring Boot、MyBatis-Plus、SQLite。
- 不使用外部 CDN。
- 字体、图标和静态资源必须打包进单 JAR。
- 新接口优先以增量方式加入；旧接口在前端迁移完成前继续可用。
- 数据库变化必须通过 `schema_migration` 前向迁移。

## 3. 视觉系统

### 3.1 核心气质

设计关键词：

- 临床仪器般精确
- 科研工作台
- 冷静、可信、可追溯
- AI 辅助而非 AI 炫技
- 数据优先

禁止以下表现：

- 紫蓝大渐变铺满内容区
- 营销式大标题和口号
- 卡片套卡片
- 大量胶囊标签
- 霓虹发光和模糊光斑
- 无业务含义的装饰图形
- Unicode 几何字符和 emoji 充当图标
- 无数据支持的“AI 诊断”文案

### 3.2 色彩

| 用途 | 建议值 | 规则 |
|---|---:|---|
| 外壳最深色 | `#120d4a` | 主导航轨、底部账户区 |
| 外壳基础色 | `#1d166b` | 上下文导航 |
| 品牌主色 | `#2b1f99` | 主要操作、关键选中态 |
| 医疗青 | `#3ad4d8` | 流程连线、实时状态、聚焦 |
| 页面背景 | `#f5f8fa` | 冷白微蓝灰 |
| 主表面 | `#ffffff` | 表格和主要工作区 |
| 次级表面 | `#f8fafc` | 表头、分组、只读区 |
| 主文字 | `#18212f` | 标题、主要数据 |
| 次级文字 | `#5f6b7a` | 说明和次要数据 |
| 边界 | `#dfe7ee` | 控件、区段和表格边界 |

品牌主色只承担关键动作和选中态；医疗青只承担流程、实时状态和交互焦点。警告、危险、成功继续使用语义色，不使用品牌色替代业务状态。

### 3.3 字体与图标

- 中文：本地子集化的思源黑体。
- 英文和数字：IBM Plex Sans。
- UI 最多使用两套字体。
- 正文基准 14px。
- 表头、状态和字段标签为 10–11px。
- 页面标题控制在 18–22px，不使用营销式超大标题。
- 图标优先复用 `@element-plus/icons-vue`。
- 若现有图标缺失，只补充一个风格统一、可本地打包的成熟图标库。

### 3.4 间距、圆角和层级

- 间距阶梯：4、8、12、16、24、32px。
- 控件圆角：4px。
- 普通面板圆角：6px。
- 抽屉、弹窗圆角上限：8px。
- 状态默认使用色点加文字，不默认使用胶囊。
- 普通内容区不使用阴影。
- 阴影只用于弹窗、抽屉、下拉和确实发生遮挡关系的浮层。

### 3.5 动效

- 时长控制在 140–180ms。
- 只使用淡入、轻微位移、尺寸和透明度变化。
- 禁止弹跳、弹性和持续循环动画。
- 支持 `prefers-reduced-motion`。
- 页面加载采用骨架屏，不使用通用旋转加载图标占据主视觉。

## 4. 全局壳层与信息架构

### 4.1 双层导航

桌面端采用选中视觉稿中的双层导航：

- 64px 主导航轨：只展示产品一级模块和图标。
- 176px 上下文导航：展示当前一级模块内的页面。
- 上下文导航允许折叠。

一级模块：

1. 工作台
2. 目标与对齐
3. 绩效评审
4. 系统管理

二级页面映射：

| 一级模块 | 二级页面 |
|---|---|
| 工作台 | 当前周期、我的待办、团队风险 |
| 目标与对齐 | 我的 OKR、团队 OKR、OKR 对齐、执行进度 |
| 绩效评审 | 我的绩效、待我评审、绩效沟通、绩效申诉、历史绩效 |
| 系统管理 | 考核周期、组织架构、绩效模板、考核维度、操作日志 |

通知从独立主导航项调整为系统状态线入口，保留原有通知页面和深链接。

### 4.2 系统状态线

页面顶部使用 36px 状态线，展示：

- 当前周期和阶段
- 系统状态
- 未读通知
- 当前用户和账户菜单

### 4.3 页面上下文栏

每个页面使用统一的 `PageContextBar`：

- 页面标题
- 当前对象
- 当前周期
- 筛选条件
- 主要操作

标题、周期、状态和主要操作不再散落于独立 hero、横幅或卡片中。

### 4.4 响应式

- `≥1280px`：完整双层导航。
- `1024–1279px`：主导航轨常驻，上下文导航收起为弹出面板。
- `<1024px`：导航使用抽屉，工作台矩阵降级为纵向分组。
- 表格优先保留关键列，次要字段进入行详情，不直接压缩到不可读。

## 5. 统一工作台

登录后默认进入新增的工作台页面，不再直接进入周期列表。

工作台包含：

- 当前周期阶段轨道
- 周期剩余时间
- 我的待办
- 团队完成率
- 待审核事项
- 阻塞和风险项
- 近期截止节点

待办类型：

- 制定或修改 OKR
- 审核下属 OKR
- 更新 KR 进度
- 提交自评
- 完成终评
- 发布结果
- 记录或回复面谈
- 确认结果
- 处理申诉

点击待办必须直接进入具体周期、人员和业务对象，不允许只跳到泛列表页。

## 6. 全局周期上下文

新增 Pinia `workspace` store，统一维护：

- 当前周期
- 可选周期
- 当前阶段
- 当前用户在该阶段的待办
- 当前页面允许执行的动作

规则：

- URL 中的 `periodId` 是可分享、可刷新的最终来源。
- URL 未提供 `periodId` 时，使用 store 中最近选择的有效周期。
- store 也无有效值时，使用后端返回的推荐周期。
- 切换周期时同步更新 URL，并刷新当前页面业务数据。
- 页面不得自行重复实现“过滤非归档周期”“默认选择第一个周期”等逻辑。

## 7. OKR 全链路设计

统一流程：

`周期发布 → 上级目标 → 我的制定 → 上级审核 → 执行更新 → 进入考评`

### 7.1 我的 OKR

采用三段式工作台：

- 左侧：上级目标和必须承接的 KR。
- 中央：我的 O/KR 编辑与结果表格。
- 右侧检查器：权重、对齐关系、字段问题和提交条件。

能力：

- 保存草稿
- 继续编辑
- 正式提交
- 查看驳回原因
- 重新提交
- 执行阶段更新 KR

提交前检查：

- O 标题有效
- KR 数量符合规则
- KR 权重合计为 100
- 必须承接的 KR 已建立来源关系
- 所有 KR 具备目标值

### 7.2 团队 OKR

使用列表和详情分栏：

- 左侧按“待审核、未提交、已驳回、阻塞、正常”排序。
- 中央展示选中人员的 O/KR。
- 右侧展示对齐、权重、阻塞和审核上下文。

驳回必须填写原因。通过操作需要明确展示被审核的人员和目标数量。

### 7.3 OKR 对齐

使用树形矩阵：

- 层级编号
- 目标类型
- 对齐度
- KR 进度
- 负责人
- 状态

右侧检查器展示：

- 目标详情
- 负责人
- 关键结果
- 来源和下游承接关系
- 孤立状态
- 风险项
- 当前可执行操作

### 7.4 执行进度

个人和团队 KR 使用统一数据矩阵。

点击 KR 行打开详情抽屉：

- 当前值和目标值
- 状态
- 更新备注
- 完整进度历史
- 来源 KR
- 下游承接目标

## 8. 绩效评审闭环

统一流程：

`员工自评 → 上级终评 → 发布结果 → 面谈反馈 → 员工确认或申诉 → 归档`

### 8.1 我的绩效

同一页面承载：

- 自评表单
- 自评已提交状态
- 终评结果
- 面谈反馈
- 结果确认
- 申诉入口

页面根据 `workflowState` 只突出当前主操作，其他历史阶段以只读方式折叠展示。

### 8.2 评审中心

采用选中视觉稿的核心布局：

- 左侧：员工评审队列。
- 中央：证据、自评、终评三列矩阵。
- 右侧：偏差和缺失证据检查器。
- 底部：固定总分、差异、评语和提交操作。

诊断规则必须基于真实数据，例如：

- 自评和终评差异超过阈值
- KR 完成率与评分明显不匹配
- 缺少绩效说明
- 存在阻塞 KR
- 加减分没有说明

### 8.3 绩效沟通

面谈记录必须绑定：

- 周期
- 员工
- 上级
- 对应终评分

上级记录亮点、问题、改进建议和面谈纪要；员工提交回复后，上级可以关闭面谈。

### 8.4 申诉与修正

申诉详情同时展示：

- 原始终评分
- 终评明细
- 面谈记录
- 申诉理由
- 处理回复
- 修正记录

任何修正都必须填写原因并写入 `audit_correction`。

### 8.5 历史绩效

提供正式历史接口，一次返回最近周期结果，不再由前端逐周期调用单期结果接口。

## 9. 页面组件体系

新增或重构以下通用组件：

| 组件 | 职责 |
|---|---|
| `AppShell` | 双层导航、状态线和响应式外壳 |
| `ModuleRail` | 一级模块图标导航 |
| `ContextNav` | 模块内二级页面导航 |
| `PageContextBar` | 标题、周期、筛选和主操作 |
| `WorkflowRail` | OKR—绩效阶段轨道 |
| `SplitWorkbench` | 列表、主区、详情检查器布局 |
| `DataMatrix` | 表格、树表、评分矩阵基础 |
| `InspectorPanel` | 右侧上下文详情 |
| `StickyActionBar` | 总分、差异、状态和提交 |
| `StatusLabel` | 色点与状态文字 |
| `MetricBar` | 进度和分数构成 |
| `EmptyState` | 无数据和下一步指引 |
| `ErrorState` | 可恢复错误 |
| `SkeletonState` | 页面加载状态 |

页面归入四类：

1. 数据浏览：周期、历史、日志、通知。
2. 分栏工作台：对齐、团队 OKR、评审、沟通、组织。
3. 编辑配置：个人 OKR、绩效模板、考核维度。
4. 结果详情：我的绩效、申诉、归档结果。

## 10. 接口设计

### 10.1 工作台概览

新增：

`GET /api/workspace/overview?periodId={id}`

响应包含：

- 推荐周期和可选周期
- 当前阶段
- 我的待办
- 团队汇总
- 风险汇总
- 近期节点
- `allowedActions`

### 10.2 OKR 工作台

新增：

`GET /api/okr/workbench?periodId={id}`

响应包含：

- 我的目标
- 上级目标
- 待审核目标
- 必须承接项
- 提交检查结果
- `workflowState`
- `allowedActions`
- `version`

新增或扩展写接口：

- 保存草稿
- 正式提交
- 审核通过
- 驳回并记录原因
- 更新 KR 进度

所有写接口使用明确 DTO，并校验版本号。

### 10.3 评审工作台

新增：

- `GET /api/scores/review-queue?periodId={id}`
- `GET /api/scores/history`

扩展现有评分详情响应，一次返回：

- OKR 证据
- 自评分
- 终评分
- 评分明细
- 面谈
- 申诉
- 诊断
- `workflowState`
- `allowedActions`
- `version`

### 10.4 错误协议

业务错误继续使用统一响应结构，并补充：

- `code`
- `message`
- `fieldErrors`
- `details`
- `conflictVersion`

版本冲突返回 HTTP 409。

## 11. 数据模型

### 11.1 评分明细表

新增 `performance_score_item`：

| 字段 | 说明 |
|---|---|
| `id` | 主键 |
| `score_id` | 对应 `performance_score` |
| `item_type` | `KR` 或 `DIMENSION` |
| `reference_id` | KR 或维度 ID |
| `name` | 提交时名称快照 |
| `max_score` | 满分或权重基准 |
| `score` | 实际评分 |
| `description` | 说明或评语 |
| `sort_order` | 展示顺序 |
| `snapshot_json` | 必要的证据快照 |
| `created_at` | 创建时间 |
| `updated_at` | 更新时间 |

`comments_json` 继续保留，作为兼容字段和历史快照。

### 11.2 状态

终评分状态明确为：

`SUBMITTED → PUBLISHED → CONFIRMED`

面谈和申诉继续独立维护状态，但通过周期、用户和终评分建立可靠关联。

### 11.3 索引

补充高频查询索引：

- 周期 + 用户 + 类型
- 周期 + 评分状态
- 评分明细 + 评分 ID
- OKR 周期 + 用户
- KR 来源关系
- 通知用户 + 未读状态

## 12. 数据迁移

迁移延续现有 `schema_migration`。

要求：

1. 启动时检测待执行迁移。
2. 执行前将数据库备份到 `data/backups/`。
3. 每个迁移在独立事务内运行。
4. 失败时整体回滚并阻止应用继续启动。
5. 迁移只新增表、字段、索引或安全回填。
6. 不删除历史字段。
7. 将可解析的 `comments_json` 回填到 `performance_score_item`。
8. 无法解析的 JSON 原样保留并记录迁移日志。
9. 回填后校验记录数量和评分总分。

迁移必须使用包含旧结构和历史数据的数据库副本进行测试。

## 13. 前端状态与数据流

数据流分三层：

1. API 层负责请求和响应规范化。
2. Pinia store 负责全局周期、用户、待办和权限上下文。
3. 页面只负责局部筛选、编辑状态和展示。

页面不得：

- 自行推断跨模块权限。
- 重复实现周期默认选择。
- 直接解析多个版本的后端返回结构。
- 用多个接口拼装同一工作台首屏。

写操作完成后，优先局部更新当前对象；涉及阶段、待办或权限变化时刷新工作台上下文。

## 14. 错误和边界状态

- 字段错误在控件附近显示。
- 全局消息只用于跨页面结果或不可定位错误。
- 409 版本冲突展示新旧版本差异和刷新入口。
- 403 展示权限状态，不显示空白页面。
- 无数据状态明确说明原因和下一步。
- 接口失败提供重试。
- 危险操作展示受影响周期、人员和数据数量。
- 归档状态全部只读。

## 15. 验证策略

### 15.1 后端

- 服务单元测试
- 周期状态机测试
- 权限测试
- 接口契约测试
- 评分口径测试
- 历史数据库迁移测试
- 迁移失败回滚测试

### 15.2 前端

- Vitest 组件测试
- Pinia 状态测试
- API 响应规范化测试
- 主题 token 守卫
- 评分契约守卫
- 响应式布局检查

### 15.3 端到端

使用 Playwright 覆盖：

1. 周期发布
2. 上级制定和下级承接
3. OKR 提交、驳回、修改和通过
4. KR 进度更新
5. 员工自评
6. 上级终评和发布
7. 面谈和员工回复
8. 结果确认
9. 申诉和审计修正
10. 历史归档查看

### 15.4 交付验证

- 前端生产构建成功。
- 后端测试通过。
- 单 JAR 构建成功。
- 静态资源与前端构建产物一致。
- 新数据库可初始化。
- 历史数据库可无损迁移并启动。

## 16. 实施阶段

### 阶段 1：基础壳层

- 字体和设计 token
- 双层导航
- 页面上下文栏
- 全局周期 store
- 工作台概览接口和页面

### 阶段 2：OKR 链路

- 我的 OKR
- 团队 OKR
- OKR 对齐
- 执行进度
- OKR 聚合接口和版本控制

### 阶段 3：绩效链路

- 我的绩效
- 评审中心
- 绩效沟通
- 申诉
- 历史绩效
- 评分明细表和迁移

### 阶段 4：管理页面

- 周期管理
- 组织架构
- 绩效模板
- 考核维度
- 通知
- 操作日志

### 阶段 5：全链路验收

- 端到端测试
- 历史数据迁移
- 响应式检查
- 单 JAR 部署验证

每个阶段独立提交并保持可回退。

## 17. 完成标准

- 全部页面使用统一壳层、组件和视觉 token。
- 所有页面能明确展示当前周期和阶段。
- 所有关键操作可以从工作台待办直达。
- OKR 和绩效链路不存在依赖用户手动跨页面寻找下一步的断点。
- 前端不再通过多次串行请求拼装工作台首屏。
- 前后端评分口径一致。
- 历史绩效通过正式接口查询。
- 评分明细结构化存储并兼容旧 JSON。
- 历史 SQLite 数据迁移前有备份，迁移失败可回滚。
- 关键业务链路具备自动化测试。
- 最终产物可作为单 JAR 运行。

## 18. 非目标

- 不引入与当前业务无关的 AI 聊天功能。
- 不新增没有数据来源的预测和诊断。
- 不修改评分口径。
- 不切换数据库或部署架构。
- 不在本轮引入深色内容主题。
- 不重写与目标无关的后端模块。