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

任务目标

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

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

唯一事实来源

按以下优先级处理冲突：

本任务书和 docs/CLAUDE_REFACTOR_EXECUTION_PLAN.md。
docs/superpowers/specs/2026-07-06-surgical-observatory-fullstack-redesign.md。
当前代码、测试和数据库 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 或不返回该项，并在实现说明中记录；不能编造。

交付物

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

禁止事项

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

交叉评审交接

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

CLAUDE_REFACTOR_TASK.md 7.3 KB Історія Запис