# v1.2.0 执行计划（B1 / 部署 / B3 / C3 / 场景页 + C1）

> 依据：《现状问题分析与改造清单》路线图 + 用户拍板的 5 个工作流。
> 原则：零运行时依赖不动摇；build 脚本产出全部可重跑；每步完成即验证。

---

## WS-0 · 顺手修两个硬伤（30 分钟）

| # | 问题 | 修法 | 验收 |
|---|---|---|---|
| 0.1 | data.js / data.json 带 UTF-8 BOM（PS5.1 `Set-Content -Encoding UTF8` 默认写 BOM），严格 JSON 解析器（node require、部分 Agent 工具链）直接解析失败 | build-site.ps1 写文件改用 `[System.IO.File]::WriteAllText($path, $content, [System.Text.UTF8Encoding]::new($false))` 无 BOM 写出 | `node -e "require('./site/data.json')"` 不报错 |
| 0.2 | dev-server 无缓存控制头，重建后浏览器可能拿旧 data.js | 遵守 PLAN §8 不改 dev-server.js；在 `CONTRIBUTING.md` 与 `TESTING.md` 各加一句「重建后浏览器需强制刷新（Ctrl+F5）」 | 文档含说明 |

## WS-1 · B1 契约第一批：15 个输入类组件（核心工作，约 1 天）

**选件**（B 端表单最高频，排除已有契约的 core 组件 input/select）：

| slug | 中文名 | 规格来源 |
|---|---|---|
| autocomplete | 自动完成 | 待查 index.json |
| cascader | 级联选择 | 同上 |
| transfer | 穿梭框 | 同上 |
| rate | 评分 | 同上 |
| slider | 滑块 | 同上 |
| segmented | 分段控制器 | 同上 |
| radiocard | 单选卡片 | 同上 |
| checkboxcard | 复选卡片 | 同上 |
| switchgroup | 开关组 | 同上 |
| numberrangeinput | 数字范围输入 | 同上 |
| codeinput | 验证码输入 | 同上 |
| passwordinput | 密码输入 | 同上 |
| phoneinput | 手机号输入 | 同上 |
| colorpicker | 颜色选择器 | 同上 |
| mention | 提及 | 同上 |

**每份契约的字段**（与现有 6 份 core 契约同 schema）：
- `variantDimensions`：维度名 + 取值数组（从规格原文提炼，不发明）
- `representativeVariants`：代表变体 label
- `usageHints`：使用要点（何时用/怎么用）
- `structurePatterns` + `anatomy`：结构描述
- `doNotInvent`：规格未定义、禁止擅自扩展的项
- `unknowns`：规格未明示、生成前需向用户澄清的项

**流程**：读规格原文（组件2-10.txt 对应章节）→ 逐份写 `.design_library/aurora-admin/components/<slug>.json` → 在 `components/index.json` 注册 `contract` 字段 → 重跑 build → 浏览器验证详情页出现「契约 JSON ✓」chip 与「设计契约」章节。

**验收**：15 个组件详情页 chip 变为契约化；`data.json` 中这 15 个组件 `contractRef` 非空、`contract` 对象完整。

## WS-2 · 部署上线（GitHub + Pages）

1. **C4-a 静态薄壳**：build 时生成 `site/components/<slug>.html`——含 title/description meta + canonical + `<meta http-equiv="refresh" content="0;url=../index.html#/component/<slug>">`，让每个组件有独立可爬 URL。
2. **C4-b sitemap.xml**：枚举首页/四页/Agents/Changelog/79 个组件薄壳。
3. **仓库准备**：`git init` + `.gitignore`（.playwright-mcp/ .tmp/ *.png 截图等）+ 顶层 `README.md`（项目简介/在线地址/目录结构/快速开始）+ 根 `index.html`（Pages 入口重定向到 ./site/）+ `.github/workflows/deploy-pages.yml`（upload-pages-artifact 部署整仓）。
4. **推送**：`gh auth status` 有凭证 → `gh repo create aurora-admin --public --source=. --push` 并启用 Pages；无凭证 → 本地 commit 完成，输出 3 条手工命令交给用户执行。

**验收**：site/data.json 无 BOM 可被 Pages 直链抓取；sitemap 列出全部 88 个 URL；（若推送成功）Pages URL 可访问。

## WS-3 · B3 Playground（在线试玩）

- `buildDemoCard` 加「试玩」按钮：代码区变为 `<textarea>`（等宽字体，零依赖），iframe 用 `srcdoc` 实时重渲染（输入 debounce 300ms）。
- 操作：试玩 / 复位（还原源码）/ 复制。
- 边界：仅 H5 tab 支持试玩（CSS/JSX/Vue 形态不可直接执行，按钮置灰并 title 说明）。
- **验收**：button 详情页改代码 → iframe 实时变化；复位还原；刷新页面不影响源文件。

## WS-4 · C3 headless 回归 + 首页通过率

- **跑法（本机零依赖）**：dev-server 起站后，用本地浏览器把 `tests/index.html` 里 79 个测试页逐个装入同源 iframe，等待其自动执行，收集 `data-assert`/`data-status` 汇总 → 写 `tests/report.json`（版本、时间、通过率、失败项列表）。
- **首页展示**：`renderHome` 尝试 fetch `tests/report.json`，Hero 统计区「测试页 79」旁显示「通过率 xx%」（无报告时显示 79 不变）。
- **留 CI 口子**：`tools/run-regression.mjs`（Playwright 版 runner，装了 playwright 的机器可直接 `node tools/run-regression.mjs` 跑出同一份 report.json + JUnit XML）。
- **验收**：report.json 存在且通过率真实；首页显示通过率。

## WS-5 · 场景示范页 + C1 交叉引用

- **场景页**：`site/scenario/user-management.html`——用户管理列表页（筛选表单 + 数据表格 + 分页 + 新增/编辑弹窗 + 消息反馈），只用 colors_and_type.css + components.css + 原生 JS；首页与快速开始加入口。
- **C1**：详情页底部「相关组件」卡——同分类高相关组件（规则：同分类 + 名称/slug 关键词映射表）+ 契约 usageHints 里提到的组件交叉链接。
- **验收**：场景页可视化正常（截图）；button 详情页底部出现相关组件链接。

## WS-6 · 收尾

- CHANGELOG.md 增 `[1.2.0]` 条目（changelog 页与顶栏版本随之自动同步）。
- 重跑 build + 全站浏览器回归（首页/搜索/详情/Agents/Changelog/Playground/场景页/暗色）。
- 更新《现状问题分析与改造清单》进度标注。

## 执行顺序与依赖

```
WS-0 (10min) → WS-1 (核心) → WS-2.1/2.2 (薄壳+sitemap) → WS-4 (回归+通过率)
→ WS-3 (Playground) → WS-5 (场景页+C1) → WS-2.3/2.4 (仓库+推送) → WS-6 (收尾)
```

依赖关系：WS-1 完成后重建才含新契约；WS-2 薄壳要在最终数据稳定后生成；WS-4 报告要在全部页面定型后跑；WS-2.4 推送放最后，一次推干净。