Frontend Development · 前端实现知识包

M6.4 整改：v0.6.x 用 frontend-agent subagent 黑盒派发。v0.7.0 改 main thread + 6-phase 范式。 本 skill 是 main thread 实现 web/ 时的"必读知识包"。

Triggers

• /build-web 命令的 IMPLEMENT phase（仅 frontend.type === "spa"；server-side / none 由 build-web Phase 1 提前 noop 退出）
• /impl 命令串行执行前端阶段
• 任何 main thread 写 web/**/*.{tsx,ts,vue,html,css} 文件时
• /design-brief 编译 brief 与 /design-execute --channel <type> 派发/摄取外部设计稿时

PR-E（v0.7.2）：当 .ddt/tech-stack.json::frontend.type 是 server-side（Thymeleaf/JSP/FreeMarker/...）或 none 时，没有独立的 web/ 工程，本 skill 不应被触发。模板由 backend 项目（如 src/main/resources/templates/）承载，归 /build-api + skills/backend-development 处理。

Inputs（main thread 必读清单）

• docs/api-contract.yaml（唯一接口真相源）
• docs/prd.md（UX 语义参考）
• .ddt/tech-stack.json（前端栈 + ai_design 选项 SSoT，禁止偏离）
• skills/api-contract-first/SKILL.md（契约优先原则）
• skills/ai-native-design/SKILL.md（AI 设计稿工作流：claude-design / figma / v0）
• contexts/delivery.md（DDT 全局上下文）
• rules/delivery/agent-invariants.md（6 条全局不变量）

Hard Requirements（main thread 必须遵守）

1. 严格按契约：不得擅自发明字段、改字段名、改错误码（contract 不清写 blocker，不要猜）
2. build/lint/typecheck：完成后必须跑构建 + lint + type-check + 最小 happy-path UI 测试
3. 代码组织：web/ 目录；组件测试放 web/__tests__/
4. 统一 client：所有网络调用走统一 client（自动从 OpenAPI 生成 types，如 openapi-typescript）
5. 栈刚性约束：必须使用 .ddt/tech-stack.json::frontend 段定义的 framework / bundler / ui / state / data_fetching；禁止偏离
6. AI-native UI 工作流：按 tech-stack.json::ai_design.type 决定 UI 来源（claude-design / figma / v0）；接入流程统一为 /design-brief → /design-execute --channel <type> → main thread 按 ai-native-design SKILL §7 改写
7. SSoT 锁死：.ddt/tech-stack.json 仅可 Read，严禁 Write/Edit/MultiEdit（PreToolUse hook 硬拦截）
8. validation loop：每完成一个组件立即跑 build / lint / type-check / 组件测试，失败立即停下

6-Phase 实施流程（main thread）

Phase 1: EXPLORE

如果 web/ 已有代码：

• 用 Grep / Glob / Read 扫描组件树 + 已有 hooks / store / api client
• 找类似页面作参照
• 落 docs/build-web-exploration.md

如果空目录：

• 跑 tech-stack.json::frontend.scaffold_cmd
• 落基础配置

Phase 2: PLAN

落 docs/build-web-plan.md：组件树 / Files to Create / Build Sequence / Endpoint × 组件映射表（v0.9.13 D30 强制） / Validation Strategy。 组件树视图让用户能扫一眼判断结构。

Endpoint × 组件映射表（必填，v0.9.13 D30 实战驱动）：

## Endpoint × 组件映射

| 页面/组件 | 消费的 endpoint | 数据获取方式 | mock 替换状态 |
|---|---|---|---|
| MonitorPage | GET /vehicles + GET /alerts | useQuery + apiClient.GET | 替换 VEHICLES / ALERT_QUEUE const |
| TasksPage | GET /tasks | useQuery + apiClient.GET | 替换 TASKS const |
| AlertsPage | GET /alerts + POST /alerts/{id}/handle | useQuery + useMutation | 替换 ALERT_QUEUE const |

为什么强制：v0.9.13 D30 实战发现 tech-stack.json::type_generation 已声明 openapi-typescript，但 web 全部内联 mock const，零 API 调用。PLAN 阶段强制列映射表 → IMPLEMENT 阶段不能跳过 API client 直接抄 prototype mock。

Phase 3: APPROVE（由 build-web.md 触发）

调用 AskUserQuestion 让用户批准 plan。

Phase 4: IMPLEMENT（main thread）

按 plan 逐步：写代码 → validation-loop → checkpoint commit。

若 tech-stack.json::ai_design.type 是 figma / v0，先跑 /design-brief 编译 brief，再 /design-execute --channel <type> 派发 + 摄取，最后 main thread 按 ai-native-design SKILL §7 改写为符合契约的 React 组件。

Phase 5: VERIFY

• vite build / eslint 0 errors / tsc --noEmit 0 errors / vitest run
• bin/check-contract-alignment.mjs（扫禁用模式 + 字段对齐）
• bin/audit-schema-alignment.mjs (v0.9.14 D31)：mock 字段 vs contract schema 三方差集，输出 docs/schema-audit.md（warning 不阻塞，但 LLM 必须看 hot-list 后决策修复优先级）

Phase 6: SUMMARY

落 docs/build-web-summary.md。

--module 分块实现

/build-web --module auth-pages
/build-web --module task-board

每轮独立 6-phase。

AI-native UI 工作流（按 tech-stack.json::ai_design.type 选）

详见 skills/ai-native-design/SKILL.md。

Self-Check

• 构建通过（vite build / next build 无报错）
• lint 0 error
• type-check 0 error
• 每个新页面有至少 1 个 happy-path 测试
• 未出现契约外字段（已全文搜索核查）
• 状态管理 / 数据获取与 tech-stack.json 一致
• tech-stack.json 未被 Edit（git diff 验证）

Don't

• ❌ 不要随便加 antd / mui 等 tech-stack.json 外的 UI 库
• ❌ 不要把 prototype（claude-design / figma / v0 bundle）的 mock 数组直接复制到生产代码（v0.9.13 D30 实战根因）：bundle 含 const MON_VEHICLES = [...] 这种演示用假数据，应在 IMPLEMENT 阶段删除并改用 apiClient.GET('/vehicles')。bundle 是视觉与结构来源，不是数据来源。
• ❌ 不要硬编码 mock 数据替代 API client（典型反模式：const TASKS = [...] 在 page 顶部 + 用 useState(TASKS)）
• ❌ 不要保留 supabase / v0-sdk 等"AI 设计源框架默认依赖"

API client 强制使用（v0.9.13 D30）

/build-web Phase 1 EXPLORE 自动跑 bin/generate-api-client.mjs，产出：

• web/src/api/types.ts（openapi-typescript 自动生成；contract 未变不重生）
• web/src/api/client.ts（openapi-fetch 模板；首次创建后用户可改）
• web/src/api/README.md（使用说明）

IMPLEMENT 阶段每个组件：

// ✅ 正确：用 generated client + react-query
import { apiClient, unwrap } from '@/api/client';
import { useQuery } from '@tanstack/react-query';

const vehiclesQuery = useQuery({
  queryKey: ['vehicles'],
  queryFn: () => unwrap(apiClient.GET('/vehicles')),
});
const vehicles = vehiclesQuery.data ?? [];

// ❌ 错误：硬编码 mock（被 bin/check-contract-alignment.mjs D30 检测到 → warning）
const VEHICLES = [
  { id: 'V001', status: 'transport' },
];

bin/check-contract-alignment.mjs 在 VERIFY 阶段扫 web/src 下的"contract 已定义 endpoint × 同名 mock 数组"反模式，输出清单到 docs/build-web-summary.md（warning 不阻塞）。

Do

• ✅ EXPLORE 阶段先看现有 web/，避免重写
• ✅ PLAN 阶段提供组件树视图
• ✅ IMPLEMENT 每个组件立即 vitest run
• ✅ 复杂 UI 用 --module 分块

Templates & References

• skills/api-contract-first/SKILL.md
• skills/ai-native-design/SKILL.md
• skills/validation-loop/SKILL.md
• skills/checkpoint-commit/SKILL.md