# Open Design Cohere 原型重构计划

## 目标与完成标准

以 `frontend/public/prototype.html` 为唯一视觉与交互参考，把现有 Vue 应用重构为
白色编辑画布、深靛蓝产品区、药丸操作、1px 中性边框和五色语义反馈的 Cohere 风格。
保留现有周期状态机、OKR 60 + KPI 40、组织树权限、审计修正与单 JAR 发布。

完成时，18 个原型页面均有对应路由、真实数据来源和 loading/empty/error 状态；不能用
样例文案或虚构 AI 结论替代业务数据。

## 差异盘点

| 原型交互 | 当前能力 | 实施结论 |
|---|---|---|
| 工作台：周期切换、四指标、风险、待办、团队概览 | `workspace/overview` 已提供周期、待办、风险、团队概览 | 前端聚合并补充指标映射；规则提示只由风险/截止/统计数据生成。 |
| 我的/团队 OKR：色条 KR、承接关系、进度与延迟 | 现有 OKR、团队、上级和进度接口 | 前端重构，无数据库变化。 |
| 对齐树与异常操作 | `alignment-graph`、`risk-items` 已存在 | 前端用 graph 的节点/边/风险渲染树与异常表；保留现有对齐操作。 |
| 甘特执行图、里程碑 | `execution-timeline` 有 KR、周期、进度历史；KR 无专属时间字段 | 先以周期范围 + 历史点实现；若产品确认需要独立里程碑，执行数据库阶段。 |
| 我的绩效/历史：大分数、分解、趋势 | `scores/my`、`scores/trend`、`scores/statistics` 已存在 | 前端重构；统计仅 HR 管理员可见。 |
| 打分、申诉、反馈 | 现有评分、申诉、反馈 API 完整 | 前端重构；不改变评分和申诉状态机。 |
| 通知：未读、类型筛选 | 通知分页、已读、`unread-by-type` 已存在 | 补类型筛选和未读徽章同步。 |
| 日志：日期/类型筛选、分页 | 已有 action、entityType、startDate、endDate 与分页 | 补全前端筛选控件和本地日期格式化。 |

## 阶段 0：固定基线与契约

1. 保留当前未提交改动，记录 `git status --short` 与 API 清单。
2. 运行 `npm test`、`npm run verify:theme`、`npm run verify:scoring`、`npm run build`、`mvn test`。
3. 为下列聚合端点保留或补齐集成测试：alignment graph、timeline、risk items、statistics、trend、
   unread-by-type、日志日期筛选。
4. 建立页面/API 映射测试或清单，确保原型中每个数据区都不是静态 mock。

## 阶段 1：设计系统与壳层

文件：`frontend/src/styles/{theme,components,element-plus}.css`、
`components/shell/{AppShell,ModuleRail,ContextNav,SystemStatusBar}.vue`。

1. 直接使用已复制的三份 Open Design token 文件；不再以旧“手术观测台”尺寸或 6px 圆角覆盖它。
2. 将左侧壳层改成原型的 220px 深靛蓝分组导航；保留路由结构，二级导航可折叠。
3. 顶部状态栏提供周期、阶段、通知和用户入口；通知入口跳转并携带未读数。
4. 统一页面标题、纯白卡片、表格 hover、药丸按钮、输入 focus 环及空/错/加载状态。
5. 清理迁移页面里的裸色值、emoji 图标、玻璃模糊与非浮层阴影。

验收：桌面 1440px、平板 1024px、手机 768px 三个断点；不新增路由。

## 阶段 2：工作台与 OKR

### 工作台

1. 基于 `GET /api/workspace/overview` 渲染周期切换、四个指标卡、风险预警、待办和团队概览。
2. 待办跳转必须包含 `periodId`；风险链接必须携带关联对象（后端未提供 objectId 时先补 DTO）。
3. “洞察”使用规则驱动文案：阻塞、逾期、进度滞后、待办截止、历史趋势；不得声称 AI 推理。

### OKR

1. `MyOkrView`：Objective/KR 色条、低进度红色、来源 KR/上级承接表。
2. `TeamOkrView`：成员网格、完成率、延迟/严重标签和详情跳转。
3. `AlignmentView`：以 `alignment-graph` 的 nodes/edges/riskIds 渲染 CSS 树和异常表；使用现有 align API。
4. `OkrExecutionView`：以 `execution-timeline` 渲染周期轨道、进度历史和风险标签；更新进度继续提交
   `newValue/status/remark`。

验收：员工、直属主管、HR 管理员、无关员工四类权限；无关员工不能看到他人目标或风险。

## 阶段 3：绩效闭环与沟通

1. `MyResultView`：巨型终评、OKR/KPI/加扣分分解、确认/申诉入口和 `scores/trend` 柱图。
2. `HistoryView`：按归档周期表格与趋势，当前周期用青色高亮；无历史时只显示空态。
3. `ScoringListView`：待评、已完成、申诉中状态，批量动作仅在后端有对应能力时显示。
4. `ScoringEditView`：自评/上级双栏、滑块、扣分红色反馈；不改变 60/40 计算。
5. `ScoreAppealView` 与 `FeedbackView`：状态流、紧急标记、会谈记录与规则提示。

验收：提交自评、主管终评、发布、确认/申诉全链路的现有集成测试继续通过。

## 阶段 4：管理与系统页

1. 周期页显示阶段轨道；模板页显示权重和规则摘要；维度页显示权重图。
2. 组织页采用部门树 + 成员列表；禁止 emoji 作为业务图标。
3. 通知页提供全部/未读/类型筛选，调用分页、已读和 unread-by-type；全部已读后同步总数与类型数。
4. 日志页提供日期、动作、实体类型筛选与分页；日期按本地 YYYY-MM-DD 传递。

## 阶段 5：可选数据库扩展（仅在确认独立里程碑时实施）

当前数据库可支持“周期级”甘特：`assessment_period.start_date/end_date` + `kr_progress_log`。
若需要原型中每个 KR 的独立开始/结束时间和多个里程碑，新增以下增量迁移：

```sql
ALTER TABLE kr_key_result ADD COLUMN start_date TEXT;
ALTER TABLE kr_key_result ADD COLUMN due_date TEXT;

CREATE TABLE IF NOT EXISTS kr_milestone (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  kr_id INTEGER NOT NULL,
  title TEXT NOT NULL,
  due_date TEXT,
  completed_at TEXT,
  status VARCHAR(20) NOT NULL DEFAULT 'PENDING',
  sort_order INTEGER NOT NULL DEFAULT 0,
  created_at TEXT NOT NULL,
  updated_at TEXT NOT NULL
);
CREATE INDEX IF NOT EXISTS idx_kr_milestone_kr ON kr_milestone(kr_id, sort_order);
```

迁移必须在 `DatabaseMigrationRunner` 中使用新版本、备份和事务；`schema.sql` 同步更新。
没有该产品确认时不执行此阶段，不凭空制造日期数据。

## 阶段 6：最终验证与发布

1. 前端：单测、主题/评分守卫、生产构建、18 页手动视觉对照。
2. 后端：完整 `mvn test`、权限/聚合接口集成测试、迁移首次/重复/失败回滚测试。
3. 运行 `./scripts/build.sh`，确认 `frontend/dist/index.html` 与
   `backend/src/main/resources/static/index.html` 一致，并检查 JAR 内引用的 hash 资源存在。
4. 用真实非管理员账户完成登录、待办跳转、OKR 更新、评分、通知筛选、日志筛选冒烟测试。