---
paths:
  - "src/components/**"
  - "src/app/**"
  - "src/pages/**"
  - "src/stores/**"
---

# 前端开发规则（Clover · Next.js）

> 承接 前端交互设计.md（5屏金标准）+ API契约.md §3 DTO。

## 组件规范
- 单一职责：一个组件只做一件事
- Props 必须定义类型（TypeScript interface）
- 避免 prop drilling 超 3 层，用 Context 或状态管理

## DTO 对接（堵官网V1坑4）
- 所有 DTO 字段严格按 API契约§3，**不许自己假设嵌套结构**
- 后端响应与契约不符立即报 Lead，不私下适配
- workspace_id / product_id 不在前端传

## SSE（异步生图电影）
- 按 event_seq 去重，断线重连补发历史事件
- 11类事件按契约§2渲染：0/N进度 + 谁好谁先冒 + 单批失败重试 + 能离开
- flywheel_injected 事件 → 显"本次已注入：最近偏好/打回原因"

## 样式
- 用 CSS Modules 或 Tailwind，不用全局样式
- 响应断点统一：sm(640) md(768) lg(1024) xl(1280)
- 颜色/间距用 design token，不硬编码

## 可访问性
- 交互元素必须有 aria-label
- 图片必须有 alt 文本
- 键盘导航可用

## 红线（CLAUDE.md）
- ❌ 不展示 Token 余额、不做积分页（key 去中转站后台看）
- ❌ 飞轮隐形：无"训练AI"按钮，只在生成时显注入提示
- ❌ 不做"自动发布到小红书"——只到确认预览
- ❌ 不做移动端（一期）

## 状态管理
- 4 个 Store：任务 / 候选 / 审核 / 全局
- 异步态用骨架屏，错误态对接契约§0错误码