# Clover PRD-前端（界面名：龙石小红书内容生产平台）

> 前端技术框架。**承接层**：5屏画面金标准见 `../../前端交互设计.md`(经倩倩姐确认)，视觉见 `../../前端设计参考图.png`。本文①承接5屏②补工程细节③对接后端契约——**唯一冻结源 = `../启动包/API契约.md`**(端点§1 / SSE事件§2 / 错误码§0)，不看 PRD-后端。
> 技术栈：Next.js+React+TS+Tailwind+Zustand(范式扒banana/frontend,全新重建)。PC优先,最小宽度1280px,不做移动端。
> 🔴 红线(CLAUDE.md)：不展示Token余额/不做积分页/key只录不显余额。

## 0. 一句话定位
前端就是"挑挑挑"：挑文案(出N条选若干)→挑图(出N张选若干，N=用户设定，图最多8)→组长挑过不过。飞轮全程隐形记录。

## 1. 三角色 + 路由表
| 角色 | 默认首页 | 能进的页 |
|------|---------|---------|
| 熟手(运营) | /tasks/new | 开任务/挑文案/挑图/确认预览/历史 |
| 组长 | /review | 审核台/历史 |
| 管理员(北哥/老板) | /config | 配置台(产品/标杆/成员/违禁词)+全部 |

路由表：
- /login(登录+首登key引导) / /dashboard(工作台) / /tasks/new(开任务)
- /tasks/[id]/text(挑文案) / /images(挑图) / /confirm(确认预览·熟手提审前)
- /review(组长审核台) / /history(历史归档) / /config(配置台·管理员)
- 🔴 角色路由守卫：/review只组长+管理员;/config只管理员;越权重定向工作台

## 2. 全局布局（对齐设计图）
- 顶部：标题"龙石小红书内容生产平台"+右上角当前用户(运营-小李)
- 5步流程条(1开新任务/2选择文案/3选择图片/4确认文案/5成片发布)——熟手常驻;组长/管理员登录后不走此条(各进自己首页)
- 左侧8项导航(工作台/开新任务/选择文案/选择图片/建立任务/任务列表/历史归档/配置中心)
- 主区 + 右侧配置预览面板
- 🔴 底部原Token余额位置(设计图568320)→**移除**,替换为版本号/留白小草装饰
- 视觉：暖橙/奶油色+绿色小草

## 3. 五屏详述（承接前端交互设计.md）

### 屏1 配置台（管理员·/config）
- 产品库：素颜霜/面膜/精华卡片+[加产品](品类不写死,客户自助加)
- 每产品配：卖点/品牌词/违禁词(三级可调)/固定标签/风格调性/可调prompt/参考图
- **标杆笔记管理**(一期主通道=截图上传+手填亮点;列表展示;关联产品)
- 成员管理(workspace邀请/角色分配) ; key录入(各人自录,只录不显余额)
- → 飞轮的"出厂设置",配一次天天用

### 屏2 开新任务（熟手·/tasks/new·设计图主表单）
- 选产品[素颜霜▾] + **今天主题输入框**(如"黄皮提亮·早八伪素颜",驱动当次方向,关键字段勿漏)
- 单条数量/生成数量(可+/-,数量不写死) + 生成方向
- 双轨入口：轨A[开始批量生成文案] / 轨B[导入外部文案](粘贴豆包等)
- 右侧配置预览面板：产品名称/卖点/成分/质地/标签/参考图3张 + [编辑配置](点击→侧滑面板原地编辑,改完实时刷新预览)
- **生成前显示"本次已注入：最近偏好X/打回原因Y"**(调GET /preference/context,基石E④)
- 底部"最近任务"横向卡(4个,任务名+状态+进度条)

### 屏3 挑文案（熟手·/tasks/[id]/text·飞轮第1次学）
- 生成N条文案卡(可多选),每卡：标题+正文+标签+**五维分数**(标题/情绪/买点/关键词/合规,展示分数条+总分,数据来自后端scoreCopy)
- 轨B导入的文案标注来源区分(source=import角标)
- 选中触发飞轮+3(隐形,无"训练AI"按钮) ; [用这N条去生图→]

### 屏4 挑图+出成品（熟手·/tasks/[id]/images·飞轮第2次学）
- N批图缩略图(可多选) ; 选中触发飞轮+3
- 选中图+文案→自动套版预览(封面+内页拼成笔记长相)
- [满意,交组长审→]

### 屏4.5 确认预览（熟手提审前·/tasks/[id]/confirm）
- 熟手提审前最后预览整套笔记 ; [提交审核] ; [重新生成](飞轮-1)
- ⚠️ 注意:通过/打回是组长动作,不在此页(修正骨架视角错位)

### 屏5 组长审核台（组长·/review·飞轮最强信号）
- 待审笔记列表(N)：每条[预览]+[✓通过]+[✗打回+原因]
- 通过+5(权重最高,飞轮最强对信号) ; 打回必填原因(下次自动注入prompt提醒AI别再犯,-3)
- 打回原因输入：模态框,必填校验
- 通过→进成品库(熟手可去屏导出打包) ; 打回→任务回pending_selection
- 导出后人工去小红书/给达人发(工具到此为止,诚实边界:小红书无接口不自动发)

## 4. 异步生图电影 + 飞轮隐形 + 错误态

### 4.1 异步生图进度（承接交互设计.md §2·体验核心）
对接后端SSE事件(契约§2)：
- 点生图→不空白干等：显"正在生成N批…0/N [进度条] 预计30-60秒,可先去忙别的好了提醒"
- 并发跑,**谁好谁先冒**(好一批亮一批,对接 image_candidate 事件,每个带 event_seq) ; "3/N"实时计数
- 单批失败标红+[⟳重试](不拖垮其他批) ; "完成9/10,这9批够挑了[继续→]"(不强求全齐)
- 🔴 铁律:老demo"点完干等18分钟转圈到崩"绝不能再有

### 4.2 飞轮隐形运转（交互设计.md §3）
- 前端**无任何"训练AI/打分"按钮**(会吓到运营),只如实把动作记给后端(带谁+哪账号)
- 三动作埋点:屏3勾文案+3 / 屏4勾图+3 / 屏5通过+5打回-3 / 屏4.5重生成-1
- "变聪明"在后端,前端只管操作顺滑+显示"本次已注入"

### 4.3 错误态UI（对接契约§0 数字错误码，前端按 code 映射语义，**不硬编码字符串码**）
| code | 语义 | 前端响应(非统一toast) |
|------|------|----------------------|
| 42201 | 业务校验失败(未配key/违禁词硬拦截) | 未配key→引导配key页/banner按钮置灰(首登强制引导)；违禁词→显示触发词+级别,提交前后立即提示 |
| 50002 | AI/token站调用失败 | "生图通道繁忙"特殊提示(区别普通错误)+[重试] |
| 50001 | 服务端错误 | "生成失败"+[重试]按钮 |
| 40901 | 状态机非法流转 | 提示当前状态不可操作,刷新看最新态 |
| 40301 | 越权访问 workspace | "无权访问"提示,跳回工作区列表 |
| 40101 | 未认证/JWT失效 | 自动触发token刷新(扒banana已实现),失败则跳登录 |
| 40001 | 参数校验失败 | 表单字段级红字提示 |

> 前端维护一份 `errorCodeMap`(code→{文案,处理动作})常量，所有错误统一查表，违禁词/限速等细分信息从 `message` 字段读。
- 真实状况兜底(交互设计.md §4)：关页面回来任务还在(后端有状态不靠前端内存)/多人各看各的

## 5. 工程细节
- 状态管理4Store(参banana)：authStore(user/workspace_id/role/token) / taskStore(任务id/状态/已选文案图id) / generationStore(SSE进度/各图状态/已完成N) / preferenceStore(本次注入偏好摘要)
- SSE客户端(扒banana sse.ts,5次重连退避)+断线重连UI("连接断开重连中1/5…"+"重连失败任务后台仍在,可刷新")
- 组件库：流程条/文案卡(带五维分)/分镜图卡/配置预览面板/交付包预览/飞轮注入提示横幅/打回原因模态框/单图进度卡/审核操作栏。🔴 删除"Token余额组件"
- 骨架屏：文案卡/图卡/审核队列loading ; 表单校验：产品必选/主题字数限/数量范围
- API客户端(扒banana api.ts含token刷新) ; AuthGuard+角色守卫(扒banana)
- 可扒banana前端零件：authStore范式/api.ts/sse.ts/AuthGuard/NextUI组件;表单字段全重建(Clover字段不同)

## 6. ❌不做（CLAUDE.md红线）
- Token余额/用量展示(去中转站后台看) / 积分中心billing页 / 移动端适配