# PROJECT_GOAL.md 路线图更新提案（2026-04-28）

> 这是一份**提案**，不是已生效的路线图。
> 当前 `docs/PROJECT_GOAL.md` 中"阶段路线"段（line 67–86）较粗，本提案展开为完整可执行计划。
> 用户审完后，可让 Codex（或人工）把本提案 merge 进 `docs/PROJECT_GOAL.md`。

---

## 改动动机

用户在 2026-04-28 审计中指出原路线图存在的 gap：

1. **6.3 描述太窄**："删除自创内容（Notification.success / type）" 听起来像只清 Notification，但其它组件是否有同类问题没系统验证
2. **6.2c 是新增项**：原路线图没列 6.2c，组件级 theme prop scoped class 这个架构改动从未明确归位
3. **npm 包化是黑盒**：原路线图只写"npm 包化"4 个字，子步骤不清
4. **Phase 7 文档站缺细化**：多角色视图（设计 / 产品 / QA）每个 tab 形态没定
5. **遗漏 Popup Box / Chart 决策点**：Figma published 但代码缺，是 v0.1 阻塞还是 v0.2 backlog 没拍
6. **遗漏反向 audit**：之前我（Claude）审了 src/components/ 不是 src/canonical/，canonical 有没有"自创未登记"项没验过

---

## 提案：完整阶段路线（替换 PROJECT_GOAL line 69–86）

```
✅ 0-3：架构（边界翻译层 / 工作原则 / 翻译层登记）
✅ 4：模式聚类（134 项决策压缩到 10 项）
✅ 5：决策（B1-B10 全部按推荐方案）
✅ 6.1：翻译层批量登记
✅ 6.2a：Token 映射计划（38 hex → token 决策表）
✅ 6.2b：Token 替换执行（5 组件 hex → token + 10 新 token）
[当前位置 ↓]
🔴 6.3：删除自创内容（Notification.success / type → resolved；仅清 dead CSS + 状态更新）
🔴 6.3.5：canonical 层反向 audit（验证 src/canonical/ 无其它"自创未登记"项，~30 min）
🔴 6.4：新增运行时能力（Input.showCount / Select.multiple / Select.editable）
🔴 6.5：微结构修复（warning glyph / Notification 按钮色 / side pop close icon / PromptMessage L 内容驱动宽度）

🟡 决策点 1：Popup Box / Chart 命运
   → v0.1 内补？还是 v0.2 backlog？

🆕 NP-1：核对 package.json exports / types / files
🆕 NP-2：写 CHANGELOG.md（v0.1.0 entry）
🆕 NP-3：验证 README 安装段（GitHub install 路径已有，干净仓库实测）
🆕 NP-4：标 v0.1.0 git tag
🆕 NP-5：在干净环境 npm install git+... smoke test

🟡 7-prep：多角色视图原型设计（每个 tab 具体形态）
🟡 决策点 2：多角色视图是 v0.1 必备还是 v0.1.x 增强？
🟡 7-A：当前 17 个 docs page 从 in-review → approved（人工逐页核 Figma 像素一致）
🟡 7-B：5 个新加 page（breadcrumb / form-item / prompt-message / steps / tabs）同样审
🟡 7-C：加多角色 tab（Design Spec / Status Matrix / Use Cases）
🟡 7-D：补 Popup Box / Chart 文档页（如决策点 1 选 v0.1 内补）
🟡 7-E：站点壳层最后一轮审（导航 / 主题 / code copy）

🟢 v0.1 上线（公司其他项目可装）

📦 Post-launch（v0.1.x / v0.2 迭代）：
🔵 6.2c：组件级 theme prop scoped CSS class + 内 token alias（架构 refactor，audit 桥接 var cosmetic warning 修复）
🔵 6.6：FormItem.label / Tooltip.content 改双形态（破坏性，单独发版）
🔵 6.7：Badge.type 拆 color + shape（破坏性）
🔵 6.8：Button canonical 完成迁移（最大变更）
🔵 8-A：视觉层确定性脚本 scripts/visual-audit.ts
🔵 8-B：Code Connect 文件 *.figma.ts 锁死 Figma node ↔ code 映射
🔵 8-C：sync:figma-library --apply-cleanup 加进 CI 自动化
```

---

## 关键 Phase 详细任务（建议加为 PROJECT_GOAL 附录或单独子文档）

### 6.2c 推迟说明

不进 v0.1 的理由：
- 下游 npm 消费者无可见 bug（颜色都是对的）
- 仅 `pnpm audit:design-system` 报"桥接变量未在全局 token 定义"——审计 cosmetic 警告
- 改动是 token 系统级 refactor（每个颜色 token 加 `-dark` / `-light` 显式变体），影响 30 个 canonical 组件的主题切换
- ROI 不对：改动大、风险中、用户感知 0

### 6.3.5 反向 audit 范围

- 跑 `pnpm audit:figma-conformance`（已存在）
- 跑 `pnpm audit:published-vs-code`（已存在）
- 加一次手动 grep `src/canonical/` 找未在 prop-aliases.md / divergences.md 登记的 prop / status / type / variant
- 输出 ~20 行报告：clean ✅ 或 N 处可疑（每处带组件名 + 位置 + 建议处理）

### NP-1 ~ NP-5 细节

| Step | 具体动作 |
|---|---|
| NP-1 | 检查 package.json：`main` / `module` / `exports` / `types` / `files` 字段；确认 `dist/` 输出完整 |
| NP-2 | `CHANGELOG.md` v0.1.0 entry：列出"首版"包含的全部 30 个 canonical 组件 + 642 图标 + tokens；列出 known issues（如 6.2c / 6.6/6.7/6.8 推迟）|
| NP-3 | 在另一台机器或 docker 干净环境，从 GitHub install 一次，写组件 import 测试，确认能跑 |
| NP-4 | `git tag v0.1.0` + push tag |
| NP-5 | 公司另一项目（建议小型 sandbox）实测 install + 用 5 个组件，记录任何问题 |

### 多角色视图（7-C）每个 tab 形态建议

| 角色 | Tab 名 | 形态建议 |
|---|---|---|
| 开发 | （主体）| 现有 Element Plus 风格 |
| 设计 | Design Spec | 嵌入 Figma frame 截图 + 全 variant 网格图 + 设计 token 引用清单 |
| QA | Status Matrix | 表格：状态轴（hover/disabled/error/empty）× 尺寸轴 × 主题 = 矩阵；每格一个截图或 live demo |
| 产品 | Use Cases | 1-3 个业务场景实例（如"提交表单成功提示" → PromptMessage success） |

> 7-prep 阶段需要先做这套设计的原型（可能动 playground/docs/DocsShell 结构）

---

## 决策点列表（用户需要拍板的事）

| # | 决策 | 影响 |
|---|---|---|
| **决策点 1** | Popup Box / Chart 进 v0.1 还是 v0.2？ | 影响 6.5 后到 7 之前是否插补全任务 |
| **决策点 2** | 多角色视图是 v0.1 必备还是 v0.1.x 增强？ | 影响 7-prep / 7-C 是否阻塞首版上线 |
| **决策点 3** | NP-1 ~ NP-5 串行还是和 7-A/B 并行？ | Path B 写"先 npm 化"，但若文档站不全 npm 装了用户也没文档 |

---

## 是否合并入 PROJECT_GOAL.md

**建议**：将本提案的"完整阶段路线"段（替换原 line 69–86）+ "关键 Phase 详细任务"段（新增附录）merge 进 PROJECT_GOAL.md。

**或者**：保留 PROJECT_GOAL.md 简洁版，本提案文件作为"详细执行视图"独立保留，PROJECT_GOAL 加一行指向本文件。

由用户决定。

---

## 不做的事

- 本提案不修改任何 src/ / figma-data/ / scripts
- 本提案不预设 PROJECT_GOAL.md 的最终样子，仅给候选方案
- 不替用户拍板 3 个决策点，仅列出供审