dev-frontend

---
name: dev-frontend
description: |
  开发流水线第 4 步：前端实现。按 API 契约开发页面、组件和状态管理，
  API 封装层对齐契约，所有页面覆盖加载/空/错误三态。
  触发词：前端实现、写前端、实现页面、开发界面、做 UI。
  输入 docs/dev/03-api-contract.md（后端已实现），产出可运行的前端，
  下一步交给 /dev-integration。
metadata:
  pipeline: dev-requirements → dev-architecture → dev-backend → dev-frontend → dev-integration
  stage: 4/5
---

# 前端实现

按契约实现前端。后端已先行，所以**默认直连真实 API 开发**；后端未就绪的接口才用 mock，且 mock 数据必须照抄契约里的响应示例。

## 前置检查

1. 读取 `docs/dev/03-api-contract.md` 和 `docs/dev/01-requirements.md`（页面按需求场景组织，不是按接口组织）。
2. 按契约"本地启动"一节把后端跑起来，用文档里的 curl 命令抽查 2-3 个接口确认可用。
3. 确认前端技术栈（架构文档已定）；如果涉及页面视觉设计且 `design-taste-frontend` skill 可用，样式部分参考它的原则，避免模板化审美。

## 开工前对齐（必须）

前置检查完成后，先向用户列出实现计划：页面清单、路由结构、实现顺序、视觉风格基调。**用户明确同意后才开始写代码**；对页面组织或风格有意见，先改计划再动手。

**商量必须自带默认推荐**：每个待定项（如风格基调、组件库）给出你建议的选项并标注「推荐」+一句理由，用户确认或改选即可，不许只抛开放式问题。

## 实现顺序

### 1. API 封装层（先于任何页面）
- 统一 HTTP client：base URL、认证 token 注入、统一响应结构解包（`code != 0` 抛业务错误）、401 跳登录。
- 按契约给每个接口写一个函数 + 类型定义（TS 类型直接从契约的 JSON 示例推导；字段名一个字母都不许改）。
- 这一层是前端唯一允许出现 URL 字符串的地方。

### 2. 路由与页面骨架
- 从需求文档的核心场景推导页面清单和路由结构，先搭全部页面的空壳 + 导航跑通。
- 登录/鉴权路由守卫先做——后面所有页面开发都在已登录态下进行。

### 3. 逐页面实现
按 P0 场景优先级逐个页面完成，每个页面做完即在浏览器里点一遍再做下一个：
- **三态必须齐**：加载中（骨架屏/spinner）、空数据（引导文案，不是白屏）、请求失败（可重试的错误提示）。
- 表单：校验规则与契约的参数校验一致（前端提示友好，但以后端校验为准）；提交中禁用按钮防重复提交。
- 列表：分页/搜索参数与契约的分页约定对齐。
- 时间、金额、枚举的展示格式统一封装成工具函数，不在组件里散写。

### 4. 状态管理
- 默认从简：能用组件局部状态就不上全局 store；全局只放登录态、用户信息这类真正跨页面的东西。
- 服务端数据用请求库的缓存机制（如 TanStack Query/SWR，若项目已有约定则从之），不手写 loading/error 样板。

## 完成标准

- [ ] 需求文档所有 P0 场景在浏览器里能完整走通
- [ ] 每个页面三态齐全（用 devtools 断网/改慢网速验证过错误态和加载态）
- [ ] 无 console 报错；构建（`npm run build` 等）通过
- [ ] 调用了哪些接口、发现哪些与契约不符（字段缺失/类型不对），记录成清单

## 交接

向用户汇报：完成的页面清单、启动方式、发现的契约不一致清单（这是联调阶段的输入）。
提示：**下一步运行 `/dev-integration` 进入联调与文档**。

## 原则

- 契约不一致时不要在前端"兼容一下"糊过去——记入清单，联调阶段以契约裁决，该改后端改后端。
- 视觉上宁可朴素一致，不要花哨混乱：统一间距、统一色板、统一圆角，禁止逐页面即兴发挥。
- 每个页面完成后在浏览器里真实点过才算完成，"编译通过"不等于"能用"。