# Codex Prompt: T3 Round B — EP Nav 落地 + @/ alias 显式 + import 风格统一

> Round A 已产出 nav 重组草稿 + 22 页 figma 元数据（dirty 待 milestone commit）。Round B 是 T3 milestone 最后一步：
>
> 1. 加 explicit `@` alias 配置（vite.config.ts + tsconfig.json）
> 2. 28 docs page import 统一到 `@/src/canonical/...`
> 3. 按 Round A 草稿落 navigation.ts EP 8 group
>
> **估时 30-45min。不要 commit。**

---

## 背景

调研发现：当前 `@/src/canonical/X.vue` 在 dev 能 work 是因为 **Vite 5.4 隐式行为**——`vite.config.ts` 没显式配 `resolve.alias`，`tsconfig.json` 也没配 `paths`。是巧合 work，未来 Vite 升级 / typecheck / IDE / 其它工具可能炸。

修法：加 explicit 配置，**统一 28 docs page 用 `@/`**（21 干净 page 从相对路径迁过来，7 outlier 保持），消除两种风格混用。

---

## 必读前置

1. **`AGENTS.md`** — 含硬规则 #6（用 src/canonical 作 SoT）+ 工作流
2. **`docs/meta-rules.md`** — 反模式清单
3. **`docs/internal/long-term-plan-v2-2026-04-29.md`** — T3 段 + 当前进度
4. **`docs/internal/_spikes/t3-execution-report.md`** — Round A 产出，含 nav 重组**草稿**（任务 4 直接落它）
5. **`playground/docs/navigation.ts`** — 当前 nav 实现，427 行
6. **`vite.config.ts`** + **`tsconfig.json`** — 改这俩配置

---

## 任务

### 任务 1：`vite.config.ts` 加 `@` alias

在 `defineConfig` 返回的对象里加：

```ts
resolve: {
  alias: {
    '@': fileURLToPath(new URL('.', import.meta.url)),
  },
},
```

`fileURLToPath` / `URL` 已 import 在文件顶部，无需新加。位置建议放在 `plugins` 之后、`root` 之前。

### 任务 2：`tsconfig.json` 加 `paths`

`compilerOptions` 加：

```json
"baseUrl": ".",
"paths": {
  "@/*": ["./*"]
}
```

**注意 `include`**：当前是 `["src/**/*"]`——**不要**轻易扩到 playground，可能让 vue-tsc 发现新 typescript 错误（playground 之前没强制类型检查）。先**保持 include 不变**，跑 typecheck 看是否仍 PASS。

如果 typecheck 因为 paths 配置出问题 → STOP 报告，不 force-fix。

### 任务 3：21 干净 page import 统一到 `@/`

把 21 个用相对路径的 page 改：

```diff
- import Badge from '../../../src/canonical/Badge.vue'
+ import Badge from '@/src/canonical/Badge.vue'
```

执行前先 grep 确认全部位置：

```bash
grep -l "from ['\"]\.\.\/\.\.\/\.\.\/src/canonical/" playground/docs/pages/*.vue
```

预期 21 个 page 命中（28 - 7 outlier = 21）。

**严禁动**：

- 7 个已用 `@/` 的 page（CheckboxPage / RadioPage / BreadcrumbPage / FormItemPage / StepsPage / TabsPage / 其它）—— 它们已是目标风格
- `usageCode` 模板字符串里的 import 文本 —— 那是给用户看的代码片段，不是 runtime
- src/ 内部的 import —— src 树内部沿用相对路径（如 `src/canonical/Tooltip.vue` import `'../components/Tooltip/Tooltip.vue'`），**不全局重写**
- `src/components/Badge/Badge.figma.ts`（Code Connect 模板）—— 它在 src 内部，保持相对路径

### 任务 4：按 Round A 草稿落 `navigation.ts` EP 8 group

替换当前 `navigationGroups` 数组（line 67 之后）为 [t3-execution-report.md "Navigation Regroup Draft" 段](../_spikes/t3-execution-report.md) 的 8 group 结构：

```
Foundation / Basic / Form / Data / Navigation / Feedback / Others / Configuration
```

**约束**：

- 保留所有 type definitions（`CanonicalPageId` / `NavigationItemMeta` / `NavigationGroup` / 等）—— **不动 type 名**
- 保留辅助函数（`resolveText` / `orderedPages` / `isCanonicalPageId` / `defaultPageId`）
- 每个 nav item 仍需 localized text (en + zh)，**从原 navigationGroups 把已有的 zh-CN 文案复用过来**——**不要重新翻译**
- `Configuration` group 当前 items 为空 `[]`（v2 plan 留位）

### 任务 5：验证

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

# dev smoke (30 秒 timeout)
pnpm dev &
DEV_PID=$!
sleep 8
# curl 抽样 3 个页面，确认 vite transform 输出含 /@fs/.../src/canonical/
curl -s "http://127.0.0.1:5173/docs/pages/CheckboxPage.vue" | grep -o '/@fs/[^"]*src/canonical/[^"?]*' | head -3
curl -s "http://127.0.0.1:5173/docs/pages/BadgePage.vue" | grep -o '/@fs/[^"]*src/canonical/[^"?]*' | head -3
curl -s "http://127.0.0.1:5173/docs/pages/TooltipPage.vue" | grep -o '/@fs/[^"]*src/canonical/[^"?]*' | head -3
kill $DEV_PID 2>/dev/null
```

预期 3 个 page 都输出 `/@fs/.../src/canonical/<X>.vue` ——证明 `@/` 解析正确。

如果 5173 端口已被占用（旧 dev server 在跑），换 5174 或停掉旧的。

### 任务 6：3 个隐性风险顺手清理（plan owner 扫描发现的低成本修复）

**6.1 `.gitignore` 加 `figma-data/raw-cache/`**

T1c PAUSED 状态留位——未来 T1c Round 2 实现 raw response cache 时，缓存文件 ~100MB，避免被误 commit。

```diff
# 在 .gitignore 末尾加
+ figma-data/raw-cache/
```

**6.2 删 `.claude/component-plan.md`**

文件内容是 "Deprecated, 重定向到 AGENTS.md"——但它在 `.claude/` Claude Code 工具特定目录里 tracked 进 repo。其它 AI 工具（Codex / Cursor / Gemini）看到这文件可能困惑"为什么 cross-tool repo 里有 Claude 工具目录"。AGENTS.md 已是单一入口，这个 deprecated pointer 不再需要。

```bash
git rm .claude/component-plan.md
```

**6.3 跑 `pnpm build` 刷新 dist/**

dist/ 当前是 Apr 28 旧 build，跟 src 最新代码不对齐。如果用户访问 :4173 preview 验证修复，看到的是 stale 产物。

```bash
pnpm build
```

预期：
- 全 build 流程通过（含 vue-tsc + vite build + icon dist 三步）
- dist/ 时间戳更新到当前
- 如果 build 失败 → STOP 报告，不 force fix（可能跟 alias / paths 改动有关）

### 任务 7：写补充段到 `t3-execution-report.md`

在文件末尾加 `## Round B 落地` 段，含：

- vite.config.ts diff（@ alias 加在哪几行）
- tsconfig.json diff（paths 加在哪）
- import 统一前后对照（21 page list + 7 outlier 保持）
- nav 重组结果（group 数 N → 8）
- typecheck + smoke 验证结果
- **3 个隐性风险清理结果**（.gitignore / .claude 文件 / dist build）

---

## 不要做的事

- ❌ **不 commit / 不 push**
- ❌ 不动 src/ 内部 import（src 树内部沿用相对路径）
- ❌ 不动 `usageCode` 模板字符串里的 import 文本
- ❌ 不动 `CanonicalPageId` 或其它 type definitions
- ❌ 不动辅助函数（resolveText / orderedPages / 等）
- ❌ 不重新翻译 zh-CN 文案——从原 navigationGroups 复用
- ❌ 不扩 tsconfig `include` 到 playground（避免触发 typescript 新错误）
- ❌ 不修 7 outlier 的现有 `@/` import（已是目标风格）
- ❌ 不主动跑 `pnpm sync:figma-library`（不调 Figma API）

允许的：

- ✅ 读项目内任何文件
- ✅ grep / curl / `node -e` 核查
- ✅ 改 `vite.config.ts` / `tsconfig.json`
- ✅ 改 21 个 page 的 import line
- ✅ 改 `playground/docs/navigation.ts` `navigationGroups` 数组（保留 type + 辅助函数）
- ✅ 改 `docs/internal/_spikes/t3-execution-report.md`（加 Round B 落地段）

---

## 自验

```bash
# 28 page 都用 @/src/canonical/
grep -l "from ['\"]@/src/canonical/" playground/docs/pages/*.vue | wc -l   # ≥ 22

# 没人再用 ../../../src/canonical/（除 src 内部）
grep -E "from ['\"]\.\.\/\.\.\/\.\.\/src/canonical/" playground/docs/pages/*.vue | wc -l   # = 0

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

# 工作区状态
git status --short | grep '^??' | wc -l    # 仅原有 untracked
git status --short | grep -E '^.M' | wc -l  # ~24（21 page + 2 config + 1 nav + 可能 t3-report）

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

---

## 完成后 STOP

报告格式：

```
=== 任务 1 vite.config.ts ===
@ alias added: yes / no
位置: line N

=== 任务 2 tsconfig.json ===
paths added: yes / no
include changed: no
typecheck side-effect: none / N new errors

=== 任务 3 import 统一 ===
21 page 改 @/ 形式: yes
7 outlier 保持: confirmed
src/ 内部 import 未动: confirmed

=== 任务 4 nav 重组 ===
group N → 8
zh-CN 文案: 全部从原数据复用

=== 任务 5 验证 ===
typecheck: PASS / FAIL
3 page curl smoke /@fs/.../src/canonical/: PASS / FAIL（贴 grep 输出）

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

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

主 session 复审 nav 重组（zh-CN 文案对不对）+ typecheck/smoke 验证结果，通过后 plan owner 一并 commit T3 milestone（含 Round A + B + 累积 dirty）。

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