Dev frontend

前端实现

按契约实现前端。后端已先行，所以默认直连真实 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 进入联调与文档。

原则

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