docs: 新增手术观测台全链路重构设计

docs/superpowers/specs/2026-07-06-surgical-observatory-fullstack-redesign.md

@@ -0,0 +1,663 @@
+# 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 聊天功能。
+- 不新增没有数据来源的预测和诊断。
+- 不修改评分口径。
+- 不切换数据库或部署架构。
+- 不在本轮引入深色内容主题。
+- 不重写与目标无关的后端模块。