# Codex Prompt: T3 — EP 风格分类 + 22 页 Figma 元数据

> **目标**：按 v2 plan T3 段把 [`playground/docs/navigation.ts`](../../playground/docs/navigation.ts) 重组为 EP 7 大类 + 给所有 docs 页加 `figmaPage` / `figmaNodeIds` 元数据。
>
> **估时 1-2h。不要 commit。**

---

## 背景

T4-spike 已端到端验证项目目标"AI 拿 Figma URL → 1:1 还原"（[复盘 2026-04-30](../retrospection/2026-04-30-t4-spike-validated.md)）。T4 batch（写 21 .figma.ts）DEFERRED 等用户 Figma plan 升 Org/Ent。

下一阶段按 v2 plan：**T3 先（nav 重组 + 22 页元数据，1-2h 小赢）→ T2 样板（generator + grid + 改 3 页 Badge/Tooltip/Select）**。

T3 是"机械重组"任务——schema (EP 7 大类) + 数据来源 (figma-data/raw/components/*.json) 都已定义。

---

## 必读前置

1. **`AGENTS.md`** — 跨工具入口（含硬规则 #6 + 项目约束 Pro plan + 工作流）
2. **`docs/meta-rules.md`** — 元规则（含触发器 G 分工：本任务是 executor 任务，按已定 schema 实现）
3. **[`docs/internal/long-term-plan-v2-2026-04-29.md`](../long-term-plan-v2-2026-04-29.md)** — T3 段（EP 7 大类清单 + 元数据要求）+ 当前进度拐点段（T3 先 → T2 后）
4. **[`playground/docs/navigation.ts`](../../playground/docs/navigation.ts)** — 当前 nav 结构（427 行，需重组）
5. **[`playground/docs/pages/`](../../playground/docs/pages/)** — 28 个 .vue 页面（22 组件页 + 6 foundation 页）+ 2 个数据 .ts
6. **`figma-data/raw/components/*.json`** —— 每个 component JSON 顶层有 `pageName` + `nodeId`，元数据来源

---

## 任务（5 步）

### 任务 1：核查 28 页面单 + 摸 figma-data 来源

跑：

```bash
ls playground/docs/pages/ | grep -E '\.vue$' | sort
ls figma-data/raw/components/ | head -50
```

按页面命名跟 figma-data 文件做手动对齐：

- `BadgePage` → `figma-data/raw/components/badge__4821_1665.json`（pageName = `— — Notifications & Pop box`，nodeId = `4821:1665`）
- `ButtonPage` → 多个 figma-data 文件（Button/dark L、Button/dark M、...、Button/url link 共 9 个 set）
- `BreadcrumbPage` → 同 figma 可能 1 或多 set
- 等等

**产出**：把对齐结果列在 plan 文档，提交给 plan owner 审。**不要硬猜**——能找到 figma-data 真源就用，找不到的标 `figmaNodeIds: []`（含 Foundation 类页面：Overview / Color / Typography / Border / Effect）。

### 任务 2：重组 [navigation.ts](../../playground/docs/navigation.ts) 为 EP 7 大类 + Foundation

按 v2 plan T3 段定义：

| 类 | 组件页 |
|---|---|
| **Foundation**（新增，不在 v2 plan 7 大类，但 28 页里有）| Overview / Color / Typography / Border / Effect |
| **Basic** | Button / Icon |
| **Form** | Input / InputNumber / Select / DateTime / Checkbox / Radio / Switch / Slider / Rating / FormItem |
| **Data** | Table / Pagination |
| **Navigation** | Breadcrumb / Steps / Tabs / TopBar |
| **Feedback** | Notification / Tooltip / Progress / PromptMessage |
| **Others** | Badge |
| **Configuration** | （v2 plan 留位"站点 theme switcher 等基础设施页"——当前无具体页面，留空 group） |

**关键约束**：
- 保留 [`navigation.ts`](../../playground/docs/navigation.ts) 现有的 `CanonicalPageId` union type，不动 type 名（避免破坏其它消费方）
- 重组的是**导航结构**（如 `navItems` array 或 group 数据），不是 type 定义
- Foundation 是 v2 plan 没明示的第 8 类——executor 不要发明 Configuration 之外的新名字，只能用 "Foundation"
- 现有 navigation.ts 看完之后，**先列出当前结构 + 重组后结构对比，给 plan owner 审**，再实改。这一步**不直接动代码**，先列 diff 草稿

### 任务 3：给 22 个组件页加 `figmaPage` + `figmaNodeIds` 元数据

每个 component page 的 `<script setup>` 顶部加：

```ts
// Figma source binding (T3 - 2026-04-30)
const figmaPage = '— — Notifications & Pop box'  // 来自 figma-data/raw/components/<X>__*.json `pageName`
const figmaNodeIds = ['4821:1665']  // 来自同文件 `nodeId`，array 形式以支持 Button 等多 set 组件
```

**关键约束**：
- 用 `const`，不用 `defineProps`——这是页面静态元数据，不是 prop
- `figmaNodeIds` 是 **array**（`string[]`），即使只有 1 个 ID 也用 array 形式（统一接口，避免 Button 9 set 时格式分叉）
- 6 个 Foundation 页面（Overview / Color / Typography / Border / Effect 等）：`figmaPage = ''`，`figmaNodeIds = []`，不强行映射 figma
- **不修改页面 template / 其它 logic**——只在 `<script setup>` 顶部加这 2 行
- Button 这种 9 set 组件：`figmaNodeIds` 列**全部 9 个 set 的 nodeId**

### 任务 4：跑 typecheck + dev server 兼容性快查

```bash
pnpm exec vue-tsc --noEmit
pnpm dev  # 开 dev 看导航是否渲染正常（30 秒内停）
```

任一失败 → STOP，列错误给 plan owner，不强行修。

### 任务 5：写一份产出报告 `docs/internal/_spikes/t3-execution-report.md`

含：
- 28 页 figmaPage / figmaNodeIds 对齐表（左 page 名 / 右 figma 来源）
- 找不到 figma 真源的页面列表 + 原因（如 Foundation 页本来就不该映射）
- nav 重组前后对比片段（2-3 行示例就够）
- typecheck / dev server 验证结果

---

## 不要做的事

- ❌ **不 commit / 不 push**
- ❌ 不修改页面 template / runtime logic / 任何页面 props（只在 `<script setup>` 顶部加 2 行 const 元数据）
- ❌ 不动 `CanonicalPageId` union type 定义（只重组 navigation 结构）
- ❌ 不删除任何已有页面 / nav 项
- ❌ 不发明新 EP 大类（除上面表里的 Foundation + 7 大类 + Configuration 共 9 个 group，不要再加）
- ❌ 不主动跑 `pnpm sync:figma-library`（不调 Figma API，只读已有 figma-data/raw/）
- ❌ 任务 2 nav 重组**不直接 fire 改代码**——先列 diff 草稿等 plan owner 审

允许的：
- ✅ 读项目内任何文件
- ✅ 跑 grep / `node -e` 查 figma-data raw JSON（按触发器 I 三层核对）
- ✅ 跑 `pnpm exec vue-tsc --noEmit` + `pnpm dev` 验证
- ✅ 改 [`playground/docs/navigation.ts`](../../playground/docs/navigation.ts)（结构重组）
- ✅ 改 22 个组件页 `<script setup>` 顶部（加 2 行 const）
- ✅ 新增 1 个文件：`docs/internal/_spikes/t3-execution-report.md`

---

## 自验

```bash
# typecheck
pnpm exec vue-tsc --noEmit; echo "EXIT: $?"  # 应 EXIT: 0

# 22 组件页全加了 figma 元数据（应 ≥ 22 个 page 文件含 figmaNodeIds）
grep -l 'figmaNodeIds' playground/docs/pages/*.vue | wc -l  # 应 ≥ 22

# Foundation 6 页应有 figmaNodeIds = []（用 grep 验证空 array）
grep -B1 'figmaNodeIds = \[\]' playground/docs/pages/*Page.vue | head -10

# 工作区只增 1 个新文件 + 改若干已有文件
git status --short | grep '^??' | wc -l   # 应 = 1（execution-report.md）
git status --short | grep -E '^.M' | wc -l  # 应 = 22+ 修改（22 组件页 + navigation.ts）

# HEAD 没动
git log --oneline -1   # 应仍是 2731196
```

---

## 完成后 STOP

报告格式：

```
=== Pre-flight ===
28 .vue page files found: yes
figma-data/raw/components/ accessible: yes

=== 任务 1 figma-data 对齐 ===
- 22 组件页 → figma 来源对齐表（见 t3-execution-report.md）
- 找不到 figma 真源页面：N（理由）

=== 任务 2 nav 重组 ===
diff 草稿已写入 t3-execution-report.md，**未直接 fire 改代码**——等 plan owner 审

=== 任务 3 22 页元数据 ===
22 / 22 组件页加了 figmaPage + figmaNodeIds
6 / 6 Foundation 页加了空 figmaNodeIds = []

=== 任务 4 验证 ===
typecheck: PASS / FAIL
pnpm dev (30s): PASS / FAIL

=== 阻碍 / 困惑 ===
（如有）

=== 工作区状态 ===
N untracked，M modified，0 commits，HEAD = 2731196
```

主 session 复审两件事：
1. nav 重组 diff 草稿（任务 2）— 决定是否同意结构再 fire 改代码
2. figma-data 对齐表（任务 1）— 验证 figmaNodeIds 没乱填

复审通过后**第二轮**让你 fire 改 navigation.ts 落地结构。

**STOP。不要进 T2 样板。**