# OKR 绩效系统 · 前端去 AI 味改造 v2 — 进展交接文档

**日期**：2026-06-27
**原执行者**：ZCode
**目标读者**：接手此工作的其他 AI Coding 工具

---

## 0. 一句话概括

正在把 OKR 绩效系统前端的 5 个样板页从「卡片堆叠式 AI 生成风格」重构为「AI 科研外壳 + 临床数据内核」的 D 风格。已完 4/10 任务，第 5 个任务（MyOkrView，最复杂的页面）template + script 已重写但尚未 commit，style 部分清理不彻底，需收尾后继续推进剩余 5 个任务。

---

## 1. 关键文档路径

所有文档均在 `/Users/destiny/dev/emoon/projects/okr-performance/` 下：

| 文档 | 路径 | 用途 |
|------|------|------|
| 设计规格 v2 | `docs/superpowers/specs/2026-06-20-medtech-ui-revamp-v2-design.md` | 5 页改造蓝图、token 增量、验收标准 |
| 实现计划 v2 | `docs/superpowers/plans/2026-06-20-medtech-ui-revamp-v2.md` | 10 任务详细分解，含代码片段 |
| v1 规格 | `docs/superpowers/specs/2026-06-18-flow-audit-and-medtech-ui-design.md` | v1 已完成（token 化、去 emoji），v2 是第二阶段 |

**设计语言方向（已确认）**：D 风格 = AI 科研外壳（留白克制、下划线输入、大写小字标签）+ 临床数据内核（表格化、高密度、三列对照式）。

---

## 2. 当前分支

```
feat/medtech-ui-v2
```

基于 `master` 创建。`master` 分支有大量未提交的工作区改动（v1 之前的遗留脏状态），**与本 v2 任务无关**。在 v2 分支上只 commit 了本任务的改动。

---

## 3. 已完成任务（4/10）

| 任务 | 内容 | Commit SHA | 文件 |
|------|------|-----------|------|
| 1 | theme.css 增量 token | `29c2d8b` | `frontend/src/styles/theme.css`（在 `:root` 块末尾追加 v2 token：表格/工具栏/状态点/区段带/侧边栏/登录渐变） |
| 2 | components.css 新增通用类 | `0e4546d` | `frontend/src/styles/components.css`（末尾追加 `.data-toolbar`/`.data-table`/`.compare-grid-3`/`.section-band`/`.metric-bar`/`.review-summary-bar`/`.underline-input`/`.history-trend` 等） |
| 3 | MainLayout 侧边栏改造 | `62ff5db` | `frontend/src/components/MainLayout.vue`（el-icon 改几何字符 ▦◎⬡⇄⊞▱◠⌧⬢⊟⌗≣、背景从渐变改纯色 `var(--color-sidebar-bg)`、选中态底色更淡、分组标题改大写小字、品牌副标题改 `OKR · 绩效`、角色 tag 去 round） |
| 4 | LoginView 全屏分栏 | `16d12b3` | `frontend/src/views/auth/LoginView.vue`（居中两栏 → 全屏左右分栏、左深色品牌区 + 右白表单、输入框从填充式改下划线式 `underline-input`、按钮 radius 收窄、文案改功能直述） |

---

## 4. 当前进行中：任务 5 — MyOkrView 表格化（⚠️ 未 commit）

**文件**：`frontend/src/views/okr/MyOkrView.vue`  
**文件行数**：约 790 行（原 820 行）  
**当前状态**：template 和 script 已重写，style 部分清理不彻底，**尚未 commit**

### 4.1 已完成的部分

**Template 重写**：
- ✅ `page-hero` / `hero-info` 已删除，改为 `.data-toolbar` 顶栏（标题 + 周期名 + 状态 + 操作按钮）
- ✅ `rules-card` (okr-standard-panel) 已删除
- ✅ `section-head` + `section-badge` 胶囊徽章全部删除
- ✅ `hint-card` 大图标引导卡全部删除（"等待上级" / "最高层级"），改为 `.state-banner` 简洁提示
- ✅ `okr-card` / `okr-grid` 卡片容器全部删除
- ✅ OKR 展示区改为 `.data-table` 表格视图（KR 列表，grid-template-columns 36px 1fr 56px 72px 120px 80px）
- ✅ 上级 OKR 对齐区改为 `.section-band` + `.data-table` 表格化
- ✅ 待审核 KR 区改为 `.section-band` + `.data-table` 表格化
- ✅ 侧边抽屉 `<el-drawer>` 已添加（KR 详情 + EXECUTING 阶段进度更新）
- ✅ Dialog（OKR 制定/编辑表单）保留原样未动

**Script 新增**：
- ✅ `drawerVisible` / `drawerKr` 响应式状态
- ✅ `openKrDrawer(kr)` — 初始化 `_newValue`/`_newStatus` 后打开抽屉
- ✅ `submitDrawerProgress()` — 调用现有 `updateProgress()` 后关闭抽屉
- ✅ `periodStatusLabel` / `periodStatusDotClass` / `daysLeft` computed
- ✅ `krStatusDotClass(kr)` 函数

**保留的现有方法（未改动）**：
- ✅ `krPercent(kr)`、`krColor(status)`、`krStatusLabel(status)`、`updateProgress(kr)`、`doReview(id, approved)`、`handleSubmit()`、`startEdit()`、`openCreateForm()`、`load()` 等

### 4.2 ⚠️ 需要修复的遗留问题

**问题 1：Style 区废弃类删除不彻底（sed 误删了 `}` 闭合，已手动修复但可能有残留）**

删除范围 718-800 行时，sed 多删了 `kr-source-tag--mine` 的闭合 `}`，已手动补回。但可能有其他边界问题。建议接手后先跑 `npm run build` 确认 CSS 解析无错误。

**问题 2：Dialog 内仍有若干 `effect="dark" round` 和 `round` 属性**

位置：`frontend/src/views/okr/MyOkrView.vue` 约第 187、202、229、292、303 行。这些在 dialog（OKR 制定/编辑弹窗）内：
- 第 187 行：`<el-tag ... effect="plain" round>`（岗位指标参考标签）
- 第 202 行：`<el-tag ... effect="dark" round>`（"X 项指派给我"）
- 第 229 行：`<el-tag ... effect="dark" round>`（"指派给我"）
- 第 292 行：`<el-button ... round>`（"新增 KR"）
- 第 303 行：`<el-button ... round>`（"提交审核"/"保存修改"）

**处理建议**：Dialog 是填写态表单，可酌情保留（不与结果展示态同等严格）。但若要彻底去 AI 味，去掉 `effect="dark"` 和 `round`，tag 改 `effect="plain"`。

**问题 3：废弃 computed `stateIcon`/`stateBanner` 在 script 中残留**

约第 500-501 行。无害（computed 是惰性求值），但若 linter 报警可删除。

**问题 4：verify 脚本检查 `okr-standard-panel` 会失败**

当前 verify 脚本要求 MyOkrView 包含 `okr-standard-panel` 类（v1 遗留断言）。任务 5 删除了该类，verify 会报：
```
MyOkrView must use okr-standard-panel
```
这是**预期的**——任务 8 才会更新 verify 脚本移除此断言。不要在任务 5 中修改 verify 脚本。

**问题 5：注释中避免 `page-hero` 字符串**

第 3 行注释 `<!-- 工具栏顶栏（替代 page-hero）-->` 已改为 `<!-- v2 工具栏顶栏（替代旧版标题区）-->`，避免任务 8 的禁用模式 `/page-hero/` 正则误报。

### 4.3 提交建议

修复上述问题 1-3 后（问题 4 留给任务 8），建议 commit message：

```
feat(frontend): MyOkrView 表格化重构（工具栏 + O/KR 表格 + 侧边抽屉）

- page-hero/hero-info/section-badge/hint-card/okr-card 全部删除
- 改为 data-toolbar 顶栏 + data-table 表格视图
- KR 更新走侧边抽屉（复用现有 updateProgress 机制）
- 保留 dialog 编辑表单不变
```

---

## 5. 待完成任务（5/10 剩余）

| 任务 | 内容 | 预计复杂度 | 涉及文件 |
|------|------|-----------|---------|
| **5（收尾）** | MyOkrView 修复 + commit | 低 | `frontend/src/views/okr/MyOkrView.vue` |
| **6** | ScoringEditView 三列对照 + 底部总览栏 | 中 | `frontend/src/views/scoring/ScoringEditView.vue` |
| **7** | MyResultView 删圆环 + 数据条 + 历史趋势 | 中 | `frontend/src/views/scoring/MyResultView.vue` |
| **8** | 更新 verify-medtech-theme.mjs 断言 | 低 | `frontend/scripts/verify-medtech-theme.mjs` |
| **9** | 构建 + 部署同步 backend/static | 低 | 构建产物 |
| **10** | 验收对照清单（人工核对） | 低 | 无代码 |

> **任务 6-7 的详细代码级步骤见**：`docs/superpowers/plans/2026-06-20-medtech-ui-revamp-v2.md`（每个任务有完整的 template/html 代码块、字段名、注意事项）。

---

## 6. 关键技术细节（给接手工具）

### 6.1 数据结构（重要！避免 v1 错误）

| 页面 | 关键变量 | 数据结构 |
|------|---------|---------|
| MyOkrView | `myOkr.keyResults[]` | **扁平 KR 列表**，每条 `{id, title, currentValue, targetValue, weight, status, _newValue, _newStatus, sourceKrId, assignedToName}` |
| MyOkrView | 现有方法 | `krPercent(kr)`、`krColor(status)`、`krStatusLabel(status)`、`updateProgress(kr)`（内部用 `kr._newValue`/`kr._newStatus`，调用 `okrApi.updateProgress(kr.id, {newValue, status, remark})`） |
| ScoringEditView | `krScores` | `ref([])` — 元素 `{title, score}`，绑定 `krScores[i].score` |
| ScoringEditView | `dimScores` | `ref([])` — 元素 `{id, name, maxScore, score}`，绑定 `dimScores[i].score` |
| ScoringEditView | `computedTotal` | 预览总分（**不是** computedPreviewTotal） |
| ScoringEditView | `computedGrade` | 预览等级 S/A/B/C（已有） |
| ScoringEditView | 加减分 | `form.bonus` / `form.penalty`（reactive form，不是独立的 bonusScore ref） |
| MyResultView | `data.finalScore.total/grade/okrScore/kpiScore/bonus/penalty/confirmedAt` | 已确认的字段名 |
| MyResultView | 历史数据 | **无现成接口**，需前端轮询 `scoreApi.getMyResult(periodId)`，取最近 4 个归档周期 |

### 6.2 verify 脚本

- `frontend/scripts/verify-medtech-theme.mjs`：检查 vue/css 文件是否符合规范
- `frontend/scripts/verify-scoring-contract.mjs`：检查评分口径（OKR 60 + 绩效 40，**本次不改**）
- 当前验证命令：`cd frontend && node scripts/verify-medtech-theme.mjs`
- 任务 5 未 commit 状态下运行会报 `MyOkrView must use okr-standard-panel`——这会在任务 8 修复

### 6.3 新增的 CSS 全局类（components.css，任务 2 已添加）

| 类名 | 用途 |
|------|------|
| `.data-toolbar` | 顶栏（替代 page-hero） |
| `.data-table` / `.data-table__header` / `.data-table__row` | 表格化数据容器 |
| `.compare-grid-3` | 三列对照网格 |
| `.section-band` | 区段色带标题 |
| `.metric-bar` | 水平数据条 |
| `.review-summary-bar` | 底部固定总览栏 |
| `.underline-input` | 下划线式输入框 |
| `.history-trend` | 历史趋势小柱状图 |
| `.uppercase-label` | 大写小字标签 |
| `.status-label` | 色点 + 文字状态标签 |
| `.side-drawer__content` | 抽屉内容区 |

### 6.4 新增的 theme.css token（任务 1 已添加）

参见 `frontend/src/styles/theme.css` 末尾 `/* ===== v2 增量 token ===== */` 注释块。关键 token：
- `--color-sidebar-bg: #1d166b`
- `--color-login-brand-from: #1d166b` / `--color-login-brand-to: #120d4a`
- `--toolbar-height: 48px`
- `--table-row-height: 40px` / `--table-row-height-compact: 32px`
- `--dot-size: 6px`
- `--label-font-size: 10px` / `--label-letter-spacing: 0.5px`

### 6.5 components.css 中已有的 status-dot 命名

`components.css` 中已有 `.status-dot` + `.is-active` / `.is-success` / `.is-warning` / `.is-danger` 修饰符（BEM 风格，用 `is-` 前缀）。MyOkrView style 中新增了 `.status-dot--active` / `.status-dot--warn` / `.status-dot--info`（BEM modifier 风格，用 `--` 前缀）。**两种风格共存但不会冲突**，因为修饰符写法不同（`.is-active` vs `--active`）。使用时注意选择一种风格。

---

## 7. 环境信息

| 项目 | 值 |
|------|-----|
| 项目根目录 | `/Users/destiny/dev/emoon/projects/okr-performance/` |
| 前端目录 | `frontend/` |
| 后端目录 | `backend/` |
| 前端技术栈 | Vue 3 + Vite + Element Plus + Pinia |
| 后端技术栈 | Spring Boot 3.2 + Maven + SQLite |
| 运行端口 | 前端 dev :5173，后端 :18080 |
| 前端构建 | `cd frontend && npm run build` |
| 后端启动 | `cd backend && mvn spring-boot:run` |
| 验证脚本 1 | `cd frontend && node scripts/verify-medtech-theme.mjs` |
| 验证脚本 2 | `cd frontend && node scripts/verify-scoring-contract.mjs` |
| 构建产物复制 | `rm -rf backend/src/main/resources/static/assets && cp -r frontend/dist/* backend/src/main/resources/static/` |

---

## 8. 任务 6 快速参考（ScoringEditView）

涉及文件：`frontend/src/views/scoring/ScoringEditView.vue`（约 450 行）

核心改动（详见计划文档）：
1. `page-hero` → `data-toolbar`
2. 左侧 `evidence-panel` + 右侧 `decision-panel` → `compare-grid-3` 三列对照
3. 区段用 `section-band`（"OKR 目标达成 · 满分 60" / "绩效维度 · 满分 40"）
4. KR 行绑定 `krScores[i].score`，维度行绑定 `dimScores[i].score`
5. 加减分绑定 `form.bonus` / `form.penalty`
6. 底部 `review-summary-bar`：`computedTotal` + `computedGrade` + 自评差异提示
7. 差异 |scoreDiff| ≥ 10 时变红 + tooltip "打分偏差较大，建议复核"
8. 响应式降级 <1280px 改为单列堆叠
9. 删除 `effect="dark" round`

## 9. 任务 7 快速参考（MyResultView）

涉及文件：`frontend/src/views/scoring/MyResultView.vue`（约 400 行）

核心改动（详见计划文档）：
1. `page-hero` → `data-toolbar`
2. `score-hero`（grade-ring conic-gradient + 渐变背景）→ `result-grid`（左大数字 + 右 metric-bar 构成条）
3. 新增「较上期 ▲+5.2」纵向对比（需前端轮询历史数据，无历史时显示"首次考评"）
4. 新增自评 vs 终评对照行
5. 操作按钮扁平化（去 emoji ✓ 💬）
6. 底部历史趋势小柱状图（最近 4 期，本期高亮）
7. 历史数据兜底：前端轮询 `scoreApi.getMyResult(periodId)` × 最近 4 个归档周期，失败则隐藏趋势区
8. **自评表单态（showSelfForm=true）保持现状不动**

---

## 10. 实施顺序建议

```
任务5收尾 → commit → 任务6(ScoringEditView) → commit → 任务7(MyResultView) → commit
→ 任务8(更新verify脚本，移除evidence-panel/decision-panel/okr-standard-panel断言，新增v2类断言+禁用模式)
→ verify两个脚本全部PASS → 任务9(build+复制static) → 任务10(验收)
```

**重要规则**：
- 每任务一 commit，便于回退
- 任务 8 之前不要动 verify 脚本（部分 legacy 断言会 FAIL 是预期的）
- 评分口径 OKR 60 + 绩效 40 绝对不能改
- `okr-workbench` / `review-workbench` / `result-workbench` / `clinical-shell` / `clinical-sidebar` / `internal-login` 这些 verify 依赖的类名必须保留