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

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

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

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

  ```bash
  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：最终验收与部署产物

- [ ] 运行：

  ```bash
  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 清单、迁移说明。