# Claude 任务书：OKR 绩效系统“手术观测台”重构收尾

## 任务目标

在现有实现基础上，完成 OKR 绩效系统的前后端重构收尾，使所有页面遵循
“Surgical Observatory / 手术观测台”设计规范，且页面所需的数据、权限、状态和
跳转均由可验证的接口支持。

这不是从零开始的视觉重写。当前工作区已有未提交改动，包含新的双层壳层、18 个
路由页面、公共组件、部分视觉改造，以及部分工作流 API。必须先审计并保留这些
改动，禁止使用 `git reset`、`git checkout --`、清空目录或以旧版原型覆盖现有文件。

## 唯一事实来源

按以下优先级处理冲突：

1. 本任务书和 `docs/CLAUDE_REFACTOR_EXECUTION_PLAN.md`。
2. `docs/superpowers/specs/2026-07-06-surgical-observatory-fullstack-redesign.md`。
3. 当前代码、测试和数据库 schema。

附件中的旧提示词仅作需求线索，不能直接执行，原因如下：

- 它要求的 Cohere 白底、药丸按钮、16px 卡片圆角，与已确认的手术观测台规范冲突。
- 它假设页面和新壳层尚不存在；当前路由已包含登录页与 17 个登录后页面。
- 它要求复制外部 Open Design 文件；当前 `frontend/src/styles/` 已有 token 和覆盖文件，
  不应盲目替换。
- 它提出的 `aiInsights` 不得用虚构文案实现。若需要洞察，只能由可解释的规则数据生成；
  本次优先交付风险、待办和截止节点。

## 现状摘要（开始前必须复核）

### 技术栈与边界

- 前端：Vue 3、Vite、Pinia、Element Plus、Vitest。
- 后端：Spring Boot 3.2、MyBatis-Plus、SQLite、JUnit 5 / Mockito。
- 发布：构建后的 `frontend/dist/` 复制到
  `backend/src/main/resources/static/`，单 JAR 部署。
- 业务不可改变：周期状态机、OKR 60 + KPI 40、组织树权限、评分修正审计、归档快照。

### 已存在、需要保留并验证的能力

- 新壳层：`AppShell.vue`、`ModuleRail.vue`、`ContextNav.vue`、
  `SystemStatusBar.vue`。
- 路由：登录页，工作台，OKR（我的/团队/对齐/执行），绩效（我的/历史/评审/申诉），
  反馈，周期、模板、组织、维度、日志、通知；`/legacy` 兼容路由也仍存在。
- 页面支撑接口：`GET /api/workspace/overview`、
  `GET /api/okr/workbench?periodId=`、
  `GET /api/scores/review-queue?periodId=`、`GET /api/scores/history` 已在工作区中出现，
  但尚未完成接口契约测试和前端接线审计。
- 通用测试与守卫：`npm test`、`verify:theme`、`verify:scoring`，以及 Maven 测试。

### 已发现的预检问题（必须在对应阶段修复并测试）

- `WorkflowActionDto.fromPeriod()` 的“评审下属”目前指向 `/scores/list`，而真实路由为
  `/scores/review`；所有待办 URL 都应由路由测试或集成冒烟测试覆盖。
- 当前全局样式仍可见 `backdrop-filter`、普通面板阴影和渐变，且 shell token 尺寸与设计规格
  不一致；不要因为页面能编译就把它视为验收通过。
- 任务书列出的 7 类新增/增强接口尚未在 controller/service 中完整实现，不能把现有的
  `/okr/workbench`、`/scores/history` 当作它们的替代品而跳过契约测试。

## 设计与工程硬规则

- 视觉采用手术观测台：深色导航外壳 + 冷白数据工作区；正文 14px；控件圆角 4px，
  面板圆角 6px；普通内容无阴影、无玻璃模糊、无大面积渐变、无默认胶囊标签。
- 只使用 CSS token；新增颜色、间距、圆角和动效必须先定义 token。不得在 `.vue` 中
  加裸色值。
- 图标使用 `@element-plus/icons-vue` 或本地 SVG；不得使用 emoji 或 Unicode 图形当图标。
- 页面统一使用 `PageContextBar`、`AsyncState` 和 workspace store；URL 的 `periodId` 是
  周期选择的最终来源。待办链接必须携带业务对象和周期上下文。
- API 返回继续使用 `ApiResult<T>`；权限必须按当前用户和上下级树校验；不得因聚合查询
  泄露其他主管或下属的数据。
- 数据库仅允许向前、幂等迁移。先备份、单版本事务、失败回滚、`schema.sql` 同步；
  不修改或丢弃已有业务数据。
- 不改变现有 API 路径或既有响应字段。新增字段必须可选或新增端点。

## 本次必须补齐的接口契约

先写 controller/service/integration 测试，再实现。DTO 命名、Java 字段和 JSON 字段均须
在测试中固定。

| 能力 | 端点 / 变更 | 最小响应与规则 |
|---|---|---|
| 对齐矩阵 | `GET /api/okr/period/{periodId}/alignment-graph` | 节点（目标、负责人、进度、状态）、父子/承接边、孤立与风险标记；只返回调用者可见范围。现有 `tree` 可复用内部查询但不改旧契约。 |
| 执行矩阵 | `GET /api/okr/period/{periodId}/execution-timeline` | KR、负责人、目标/当前值、状态、起止日期、最近更新、进度历史；不可伪造没有存储的里程碑。 |
| 风险列表 | `GET /api/okr/period/{periodId}/risk-items` | 由阻塞 KR、逾期、未对齐和进度落后等明确规则生成，并提供规则类型、严重度、对象、负责人、详情。工作台可复用同一服务。 |
| 评分统计 | `GET /api/scores/statistics?periodId=` | 仅 HR 管理员以上；等级分布、有效终评总人数、平均值、中位数。无数据时返回零值/空分布，而非异常。 |
| 个人趋势 | `GET /api/scores/trend?limit=` | 当前用户的已归档终评按周期排序；保留现有 `/history` 兼容。 |
| 通知分组 | `GET /api/notifications/unread-by-type` | 只统计当前用户未读通知，按真实通知 type 返回；总数与 `/unread-count` 一致。 |
| 工作台 | 扩展 `WorkspaceOverviewDto` | 增加 `riskCount`、`overdueCount`；若新增 `insights`，必须是规则驱动的 `type/severity/title/description/relatedEntityId`，且不把它称为 AI。 |
| 日志筛选 | 扩展 `GET /api/system/logs` | 保留现有 `action`、`entityType`，新增 ISO 日期 `startDate`、`endDate`；HR 权限不变；非法日期与开始晚于结束须返回可读 400。 |

若现有表没有可靠数据支撑某字段，返回 `null` 或不返回该项，并在实现说明中记录；不能编造。

## 交付物

1. 完整、最小范围的前后端实现及测试。
2. 更新后的 `docs/CLAUDE_REFACTOR_EXECUTION_PLAN.md` 复选框和最终实施摘要。
3. 每个阶段一个原子 commit；不提交无关静态构建产物，除非阶段 6 的最终发布同步。
4. 最终报告：变更文件、接口示例、迁移版本、每条验证命令及实际输出摘要、已知限制。

## 禁止事项

- 不执行外部原型文件或复制外部设计 token。
- 不删改当前未提交改动来获得“干净”状态。
- 不新增路由来绕开既有页面；仅在原型有明确页面且当前路由缺失时，先说明并等待确认。
- 不将 mock 数据、假 AI 分析、前端硬编码业务结论作为正式功能。
- 不在未经测试的情况下宣称完成。

## 交叉评审交接

完成每一阶段后停在 commit 边界，向我提供：commit SHA、`git diff <base>...HEAD`、
通过/失败的测试输出以及待确认项。我将从接口契约、权限/数据隔离、迁移安全、
业务口径、视觉规范和回归风险六个维度独立评审。未获得评审结论前，不开始下一阶段。