okr-performance/docs/CLAUDE_REFACTOR_EXECUTION_PLAN.md

Claude 执行计划：手术观测台重构收尾

配套任务书：docs/CLAUDE_REFACTOR_TASK.md。

完成标准：所有既有业务行为保持兼容；新增页面数据契约可测试；设计规范一致； 前后端构建、测试与守卫均有实际通过证据。

阶段 0：保护现场与建立基线

• 记录 git status --short、当前分支、git diff --stat，将它们视为其他工作， 不丢弃、不格式化无关文件。
• 阅读任务书、设计规格、路由、API 客户端、相关 controller/service、schema 和迁移器。

• [ ] 运行并记录：

  cd frontend && npm test && npm run verify:theme && npm run verify:scoring && npm run build
  cd backend && mvn test
  

• [ ] 若基线失败，只定位与本任务相关的原因；先报告现状，不把已有失败伪装成本次修复。

• [ ] 列出“已有实现 / 真正缺口”矩阵，作为后续范围依据。

评审门：提交基线报告，不写产品代码。

阶段 1：统一视觉基础与壳层收尾

• 对照设计规格审计 theme.css、components.css 和 element-plus.css：移除新引入的 普通阴影、backdrop-filter、大面积渐变和过大圆角；保留必要弹窗/抽屉浮层阴影。
• 使实际壳层尺寸与规格一致：64px 主导航轨、176px 上下文导航、36px 状态线；补齐 1280px、1024px 两个响应式断点。
• 将当前页面散落的 hero/banner/自定义加载状态迁移到 PageContextBar 和 AsyncState， 但不重写已符合要求的页面。
• 审计图标和裸色值；只修复本次触及页面或公共组件中的违规项。
• 为 token 和壳层约束补充/更新 Vitest 守卫，避免用只检查类名的脆弱断言代替行为测试。

验证：前端单测、主题守卫、生产构建；桌面与窄屏手工截图各至少一张。

评审门：提供截图、变更范围和验证结果。

阶段 2：周期上下文和页面工作流接线

• 以 frontend/src/stores/workspace.js 为唯一周期状态入口：URL periodId 优先， 其次 store，最后后端推荐周期。
• 修正待办、工作台、OKR、评分和历史页面的链接，使其携带 periodId（必要时也携带 userId / objectId），刷新页面后上下文不丢失。
• 接线并验证已有 /workspace/overview、/okr/workbench、/scores/review-queue 和 /scores/history；删除为绕过这些接口而新增的同义前端数据拼装。
• 补充 store 的单元测试：推荐周期回退、URL 覆盖、周期切换刷新、失败状态不残留旧数据。

验证：Vitest + 浏览器手测“工作台待办 → 目标/评分页面 → 刷新”链路。

评审门：提供各页面的请求/响应样例与权限账户覆盖说明。

阶段 3：OKR 聚合接口和页面数据化

• 为 alignment graph、execution timeline、risk items 写集成测试，覆盖普通员工、直属主管、 无关主管和超级管理员四类访问者。
• 抽取可复用的 OKR 可见范围与风险判定服务，复用现有 /tree、进度历史和 workspace 查询；避免每个 endpoint 复制 SQL。
• 实现三个新增端点及对应 DTO；日期/进度为空时稳定降级，不推断事实。
• 接线 AlignmentView.vue、OkrExecutionView.vue 和 WorkspaceView.vue，支持 loading、 empty、error、无权限四种状态。
• 复核“我的/团队 OKR”提交、审核、进度更新不受影响；关键 KR 权重仍为 100。

验证：新增集成测试、现有 OkrServiceTest、前端构建与关键页面手测。

评审门：提供 DTO JSON 示例、可见范围断言与风险规则表。

阶段 4：绩效、通知和日志契约补齐

• 先为评分统计、个人趋势、通知分组和日志日期筛选写测试。
• 实现端点，保证：统计只允许 HR 管理员以上；趋势仅当前用户；通知仅当前用户； 日志权限保持 HR 管理员以上。
• 统计只能基于已发布/已归档的终评，明确过滤条件；中位数在偶数样本时取中间两项均值。
• 前端接线 HistoryView、NotificationView、LogView；无数据不显示伪图表或虚构趋势。
• 扩展工作台计数；若实现规则洞察，标记为“系统提示/规则提示”，并列出触发规则。

验证：后端集成测试、前端单测和带/不带筛选条件的手测。

评审门：提供权限矩阵、统计口径、日期边界行为和接口样例。

阶段 5：迁移安全与回归测试

• 只有阶段 3/4 确实需要持久化字段或索引时才新增迁移；纯聚合读取不新建表。
• 新迁移使用下一个未占用版本，在 DatabaseMigrationRunner 的备份和事务机制内运行； 同步更新 schema.sql。
• 测试首次运行、重复运行、失败回滚和现有数据可读；SQLite 列/索引存在性检查必须幂等。
• 回归 OKR 60 + KPI 40、评分修正审计、周期状态机和组织树权限。

验证：迁移专项测试、mvn test、使用副本数据库的启动验证。

评审门：提供版本号、向前/重复/失败三种迁移证据。

阶段 6：最终验收与部署产物

• [ ] 运行：

  cd frontend && npm test && npm run verify:theme && npm run verify:scoring && npm run build
  cd backend && mvn test && mvn clean package -DskipTests
  

• [ ] 在确认前端构建成功后，按项目脚本的方式同步 frontend/dist/ 到 backend/src/main/resources/static/；只提交与本次构建匹配的静态文件，清除失效 hash 引用。

• [ ] 启动 JAR（或等价集成环境），完成登录、工作台、OKR 更新、评分、通知、日志筛选的 冒烟测试。用非超级管理员验证至少一个越权请求返回 403。

• [ ] 更新本计划复选框，形成实施摘要和已知限制；提交最终 commit，不推送、不创建 PR。

最终交叉评审输入：完整 commit 列表、最终 diff、验证输出、截图、API 清单、迁移说明。