# Prompt — Phase A2 Audit auto-discovery + ε audit

> **角色**：executor
> **范围**：把 [`figma-sync/audit-page-t2-sample.mjs`](../../../figma-sync/audit-page-t2-sample.mjs) 的硬编码 `PAGE_CONFIG` 改自动派生（扫 `playground/docs/pages/*Page.vue`），加 **ε audit (`epsilon-handwritten-figma`)** 检测 page 上手写 figma 字面量——给 Phase A3 全库 sweep + Phase A4 page 批量改造提供工作清单。
>
> ⚠️ **不要 commit / 不要 git add**——dirty 累积到 Phase A2 通过后 commit。
> ⚠️ 完成后 **STOP**，按底部"完成报告"格式回报。
> ⚠️ **不扩范围**：只动 `figma-sync/audit-page-t2-sample.mjs` + 输出 `docs/internal/t2-sample-audit-report.<PageName>.md`。**不动** generator / canonical / page / prop-aliases.md / backlog.md / types.ts / grid 组件。

---

## §0 — Plan owner 已定裁定

### PAGE_CONFIG auto-discovery 规则

扫 `playground/docs/pages/*Page.vue`（共 28 个），按下面规则分类：

#### 跳过：Foundation pages（无 figma 真源，文档站基础设施）

| Page | 说明 |
|---|---|
| `BorderPage.vue` | 边框 token 文档 |
| `ColorPage.vue` | 颜色 token 文档 |
| `EffectPage.vue` | 阴影/特效 token 文档 |
| `IconPage.vue` | 图标库目录 |
| `OverviewPage.vue` | 项目总览 |
| `TypographyPage.vue` | 字体 token 文档 |

→ 6 page，audit 完全不跑（不进 PAGE_CONFIG）。

#### 跳过：Tier 2/3 + no-figma pages（Phase A 范围外）

| Page | 原因 | Backlog ID |
|---|---|---|
| `ButtonPage.vue` | Tier 3 (Button mega component) | BRIDGE-Tier3 |
| `InputPage.vue` | Tier 2 (input box filled+line 多 set) | BRIDGE-Tier2 |
| `SelectPage.vue` | Tier 2 (select box filled+line 多 set) | BRIDGE-Tier2 |
| `DateTimePage.vue` | 无 figma 真源对应 | （未登记，本轮 warn） |

→ 4 page，audit 跳过（warn 提示对应 backlog ID 或 figma 缺真源）。

#### 跑 audit：剩 18 page

= 28 - 6 foundation - 4 Tier 2/3 = **18 audit-able pages**

### Page → Component 派生规则（plan owner 锁）

每个 audit-able page 必须映射到 1 个 Tier 1 component（19 个 .ts 之一）：

1. **扫 SFC `<script setup>` import 语句**取 `@/src/canonical/<X>.vue` 引用
2. **过滤**：只保留有对应 Tier 1 `.ts` 文件的（`figma-data/normalized/docs-figma-members/<lowercase X>.ts` 存在）
3. **单 import 命中**：直接用
4. **多 import 命中**（如 StepsPage 同时 import Steps + StepItem）：按下面 tiebreaker map 取 primary：

| Page File | Primary Component | 理由 |
|---|---|---|
| `BreadcrumbPage` | `BreadcrumbItem` | Breadcrumb wrapper 无 figma 真源；item 是真实 figma `Breadcrumb/Item` |
| `StepsPage` | `StepItem` | Steps wrapper 无 figma 真源；item 是真实 figma `Step/Item` |
| `TabsPage` | `TabItem` | TabList / Tab 也存在但 item 是用户面对最多的 figma Tab/Item |

5. **0 import 命中** Tier 1：page 不可 audit（warn 跳过）

### audit-able pages 预期清单（18 个）

页名 → component 映射（auto-derive 后期望命中）：

| Page | Component |
|---|---|
| BadgePage | Badge |
| BreadcrumbPage | BreadcrumbItem (tiebreaker) |
| CheckboxPage | CheckBox |
| FormItemPage | FormItem |
| InputNumberPage | InputNumber |
| NotificationPage | Notification |
| PaginationPage | Pagination |
| ProgressPage | Progress |
| PromptMessagePage | PromptMessage |
| RadioPage | Radio |
| RatingPage | Rating |
| SliderPage | Slider |
| StepsPage | StepItem (tiebreaker) |
| SwitchPage | Switch |
| TablePage | Table |
| TabsPage | TabItem (tiebreaker) |
| TooltipPage | Tooltip |
| TopBarPage | TopBar |

audit script auto-discovery 应能复现这 18 项（不 hardcode 表格，按规则派生 + tiebreaker map）。

### tokenFiles 派生规则

每个 audit-able page 的 `tokenFiles` (用于 δ token purity audit)：

```
[
  `src/canonical/${componentName}.vue`,
  `playground/docs/pages/${pageFileName}`,
  `playground/docs/components/FigmaMembersGrid.vue`,
]
```

### ε audit (`epsilon-handwritten-figma`)：检测 page 是否已改造

#### 输入

每个 audit-able page SFC（用 `@vue/compiler-sfc` 同其它 audit）。

#### 检测 patterns（任一命中 → ε fail）

1. **`<script setup>` 含 `const figmaPage = ...`**（未改造的 figma 元数据残留）
2. **`<script setup>` 含 `const figmaNodeIds = ...`**（同上）
3. **`<template>` 含字面量 `'variant count=N'` 或 `"变体数=N"`**（旧手写 meta 行）
4. **`<template>` 含字面量 `'nodeId=<digits>:<digits>'`**（如 `nodeId=4821:1665`，旧手写 source meta 行）
5. **`<script setup>` 含 `import { <component>FigmaMembers } from '@/figma-data/normalized/docs-figma-members/<x>'`** **缺失** —— page 未消费 generator output（**反向条件**：该 import **不**出现 = ε fail）

#### Verdict schema

沿用现有 audit verdict shape（plan §3.1）：

```jsonc
{
  "auditId": "epsilon-handwritten-figma",
  "page": "BadgePage",
  "component": "Badge",
  "verdict": "pass" | "fail",
  "evidenceLevel": "direct",
  "evidenceSource": ["vue-sfc-static-scan"],
  "findings": [
    { "severity": "error", "location": "<file:line>", "message": "Detected handwritten 'figmaPage' const declaration" },
    ...
  ],
  "checkedAt": "ISO-8601"
}
```

任一 pattern 命中 → 加一条 finding。`findings.length === 0` → verdict=pass，否则 fail。

#### 期望验证

- BadgePage / TooltipPage（已改造）：ε=pass，findings=0
- 其他 16 audit-able page（未改造）：ε=fail，findings 至少含 #5（缺 generator import）和/或 #1-4 残留

### 4 现有 audit 在非改造 page 上的行为

audit 算法**不动**——但 4 audit 在非改造 page 上会出现什么 verdict 由实际数据决定：

- α theme isolation：如 component generator 输出有 theme axis 而 page 没用 grid → 通常 fail（无法确认 isolation）
- β figma axis coverage：page 静态 prop 值仍可能命中 axes（如 NotificationPage 用 status='success' 等）→ 可能 pass
- γ runtime fabrication：page 没 `<FigmaMembersGrid>` → fail（grid usage missing）
- δ token purity：与 page 改造状态无关，看 CSS 是否有 hex/rgb literal

⚠️ **不要**为非改造 page 调整 4 audit 算法以"修到 pass"——这是 Phase A4 改造时的事。本轮 audit 的角色是**报告事实**。

### Audit report 输出路径

每个 audit-able page → `docs/internal/t2-sample-audit-report.<PageName>.md`（覆写）

新增 ε audit section 加到现有 report markdown 模板（α / β / γ / δ 后追加）。

### CLI 行为

- `node figma-sync/audit-page-t2-sample.mjs`（无参）→ 跑全部 18 audit-able pages
- `node figma-sync/audit-page-t2-sample.mjs <PageName>`（如 `BadgePage`）→ 单 page 跑（向后兼容）
- 未知 page 名（如 `BorderPage`）→ throw with 引导 backlog ID 或 "foundation page, no audit applicable"
- Tier 2/3 page 名（如 `ButtonPage`）→ throw "Tier <N> page deferred per plan, see backlog BRIDGE-Tier<N>"

### Baseline regression check

跑完后：

- `t2-sample-audit-report.BadgePage.md`：α=N/A · β=pass · γ=pass · δ=pass · **ε=pass**（新加 ε 应 pass，因为已改造）· 与 commit 130fc13 时 4 verdict + findings=0 一致除 timestamps
- `t2-sample-audit-report.TooltipPage.md`：α=pass · β=pass · γ=pass · δ=pass · **ε=pass** · 与 commit 130fc13 时 4 verdict + findings=0 一致除 timestamps

任一非 timestamp 偏离 → STOP 报告，不修。

### 不动

- `figma-sync/generate-docs-figma-members.mjs`（A1 已 commit 130fc13）
- `figma-data/normalized/docs-figma-members/types.ts` / `*.ts`（schema + 输出不变）
- `playground/docs/pages/*.vue`（Phase A4 范围）
- `playground/docs/components/FigmaMembersGrid.vue`
- `src/canonical/*` / `src/components/*`
- `src/design-system/translation/prop-aliases.md`
- `docs/internal/backlog.md`

---

## §1 — 必读输入

按顺序：

1. [`AGENTS.md`](../../../AGENTS.md) — 硬规则 + 必读链路
2. [`docs/meta-rules.md`](../../meta-rules.md) — 反模式 + 触发器 G
3. [`docs/internal/backlog.md`](../../backlog.md) — 看新增 backlog 是否影响
4. [`figma-sync/audit-page-t2-sample.mjs`](../../../figma-sync/audit-page-t2-sample.mjs) — 现有 audit script（commit 130fc13），重写起点（PAGE_CONFIG / 4 audit functions / 报告 render）
5. [`figma-data/normalized/docs-figma-members/`](../../../figma-data/normalized/docs-figma-members/) — 19 Tier 1 .ts + types.ts（不动，audit 消费）
6. [`docs/internal/t2-sample-audit-report.BadgePage.md`](../../t2-sample-audit-report.BadgePage.md) — 现有 baseline 对照
7. [`docs/internal/t2-sample-audit-report.TooltipPage.md`](../../t2-sample-audit-report.TooltipPage.md) — 现有 baseline 对照
8. [`playground/docs/pages/`](../../../playground/docs/pages/) — 28 page 全集
9. [`playground/docs/pages/BadgePage.vue`](../../../playground/docs/pages/BadgePage.vue) — 已改造范式
10. [`playground/docs/pages/TooltipPage.vue`](../../../playground/docs/pages/TooltipPage.vue) — 已改造范式
11. 任意未改造 page（如 [`NotificationPage.vue`](../../../playground/docs/pages/NotificationPage.vue) / [`ProgressPage.vue`](../../../playground/docs/pages/ProgressPage.vue)）—— ε audit 检测 patterns 实证

---

## §2 — 任务清单

### 任务 2.1 — Audit script auto-discovery 重写

按 §0 规则重写 `figma-sync/audit-page-t2-sample.mjs`：

- 删硬编码 `PAGE_CONFIG = { BadgePage, TooltipPage }`
- 加 discovery 算法（scan + import 解析 + tiebreaker + tier filter）
- 4 audit 函数（α/β/γ/δ）**完全不改**——只配置数据来源换为派生
- 加 ε audit 函数（按 §0 检测 patterns 实施）
- main 函数：无参 → 全 page 跑；带 page 名 → 单跑（向后兼容）

### 任务 2.2 — 跑 audit 全量

```bash
node figma-sync/audit-page-t2-sample.mjs
```

预期控制台输出：
- `Discovered audit-able pages: 18`
- `Skipped foundation: 6 (BorderPage, ColorPage, ...)`
- `Skipped Tier 2/3: 4 (ButtonPage, InputPage, ...)`
- 18 reports 生成完毕

### 任务 2.3 — Baseline regression check

```bash
git diff docs/internal/t2-sample-audit-report.BadgePage.md
git diff docs/internal/t2-sample-audit-report.TooltipPage.md
```

预期：除 timestamps（`Generated at` / `checkedAt`）外，4 verdict + findings 应字面一致。新加 ε audit section 在末尾追加（baseline 文件不存在 ε section → 这次新加属正常变更，**不算 regression**）。

### 任务 2.4 — 单 page CLI 验证

```bash
node figma-sync/audit-page-t2-sample.mjs BadgePage    # 应正常跑
node figma-sync/audit-page-t2-sample.mjs ButtonPage   # 应 throw + 引导 BRIDGE-Tier3
node figma-sync/audit-page-t2-sample.mjs ColorPage    # 应 throw + 提示 foundation page
```

### 任务 2.5 — typecheck

```bash
pnpm exec vue-tsc --noEmit
```

预期 0 错误（audit script 不动 .ts schema）。

---

## §3 — 验收清单

- [ ] audit script 重写后**仍**支持单 page CLI（向后兼容 BadgePage / TooltipPage）
- [ ] 无参跑生成 **18** 份 audit reports（含 baselines）
- [ ] PAGE_CONFIG 是 auto-derive 不是 hardcode 字典
- [ ] Page → Component 派生命中预期 18 项（包括 tiebreaker 命中 BreadcrumbItem / StepItem / TabItem）
- [ ] Foundation pages skipped (6)
- [ ] Tier 2/3 pages skipped (4，warn with backlog ID)
- [ ] ε audit 实施 5 个检测 patterns（含反向条件）
- [ ] BadgePage / TooltipPage **ε=pass + 其他 4 verdict regress-pass**
- [ ] 16 未改造 page **ε=fail** + findings 列具体 patterns 命中
- [ ] 4 audit 函数代码 **0 改动**（只扩 discovery + ε function）
- [ ] `pnpm exec vue-tsc --noEmit` 0 错误
- [ ] generator / canonical / page / types.ts / prop-aliases / backlog **没动**
- [ ] 没 commit / 没 git add

---

## §4 — 完成报告（按下方格式回报）

```
## Phase A2 Audit Auto-Discovery + ε audit 完成报告

### 改动文件
- figma-sync/audit-page-t2-sample.mjs (重写, +XXX/-YYY 行)
- docs/internal/t2-sample-audit-report.<Page>.md × 18 (16 新, 2 baseline 重生)

### Discovery 统计
- Audit-able pages: <N> (期望 18)
- Skipped foundation: <list, 期望 6>
- Skipped Tier 2/3: <list, 期望 4 with backlog ID>
- Tiebreaker hits: <list, 期望 3: BreadcrumbPage, StepsPage, TabsPage>

### Audit 结果汇总
| Page | α | β | γ | δ | ε |
|---|---|---|---|---|---|
| BadgePage | N/A | pass | pass | pass | pass |
| TooltipPage | pass | pass | pass | pass | pass |
| <16 未改造 page> | <verdicts> |

### Baseline regression
- BadgePage 4 verdict + findings: <一致除 timestamps / 偏离描述>
- TooltipPage 4 verdict + findings: <一致除 timestamps / 偏离描述>
- ε audit baseline: BadgePage=pass, TooltipPage=pass

### CLI 向后兼容验证
- BadgePage 单跑: <OK / 错误>
- ButtonPage (Tier 3): <throw + backlog ID 引导>
- ColorPage (foundation): <throw / 行为>

### typecheck
- vue-tsc: 0 错误

### ε audit pattern 实施细节（plan owner 复审）
[贴 ε audit 实现 hunk + pattern 检测算法 + 任何 edge case 处理]

### 验收 self-check
- [ ] 18 reports 生成
- [ ] PAGE_CONFIG auto-derived
- [ ] tiebreaker 3 项命中
- [ ] ε audit 5 patterns 实施
- [ ] BadgePage / TooltipPage 5+1 verdict 全 pass
- [ ] 16 未改造 page ε=fail
- [ ] 4 audit 函数 0 改动
- [ ] 不动真源 .md / generator / canonical / page / types.ts
- [ ] vue-tsc 0 错
- [ ] 没 commit
- [ ] 没扩范围

### 未解决项 / blocker
[如 page → component 派生失败 / 多 import 无 tiebreaker / ε pattern 边界 case，列出；无则写"无"]

STOP — 等 plan owner 复审 + 决定 Phase A1+A2 整体 commit (或 A2 单独 commit 后启 A3 sweep)。
```

---

## §5 — 严守约束总览

- ⚠️ **不要 commit / 不要 git add**
- ⚠️ §0 裁定**最终**（discovery 规则 / tiebreaker 3 项 / ε 5 patterns / regression baselines）
- ⚠️ 4 audit 函数代码 **0 改动**
- ⚠️ 不动 generator / canonical / page / prop-aliases.md / backlog.md / types.ts
- ⚠️ 16 未改造 page 的 audit fail 是**期望事实**，不要"修到 pass"
- ⚠️ Baseline regression（Badge/Tooltip 4 verdict）必须 pass
- ⚠️ 完成 STOP，按 §4 格式回报