zycandClaude Fable 5
216a711291
后端: - 新增 celery_health 生成前置闸——无 worker 在线时图片/视频生成入口 一律 503,防"提交到 ARK 后无人轮询、结果悬空+额度冻结"的数据丢失 - 拼接导出:帧率跟随源众数、字幕逐句重映射、原声/BGM 混音修复 - 资金核算审计脚本 + genesis 账目回填 + 滞留预留清理命令 - 接入 yunqi provider 与豆包 TTS 模型(catalog/migrations/bootstrap 命令) 前端:全站页面更新(pipeline/library/products/projects/team/account 等), 新增共享 pager 分页组件 QA:刷新 function-audit 全量输出,新增 full-qa 报告 文档:BP 产品介绍资料、design/CLAUDE.md Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
5.7 KiB
5.7 KiB
UI 设计稿开发规范（通用 CLAUDE.md）
把本文件放在 UI 设计稿工作区根目录。适用于任何 Web 项目：你（UI/设计 agent）产出的不是静态 HTML 画稿，而是可直接并入目标工程的 SPA 页面代码。
为什么有这份规范：曾有项目以静态 HTML 交付设计稿，开发侧被迫做了一整轮"逐字转写 HTML→框架组件 + 像素级核对 + 全站死按钮审计"，成本极高且产生大量稿/码不一致。本规范的唯一目标：设计稿即代码，交付物零转换并入主工程。
0. 项目参数表（每个新项目开工前先填，未填不得动工）
向开发侧确认以下信息并填入。本文件其余部分所有规则引用这张表，不要凭喜好自选：
| 参数 | 本项目取值 | 说明 |
|---|---|---|
| 前端框架 | （如 React 19 / Vue 3 / Svelte） | 必须与目标工程一致；全新项目默认 React + TypeScript |
| 构建工具 | （如 Vite） | 默认 Vite |
| 路由方案 | （目标工程现有方案） | 复用目标工程的路由机制，不自带新路由库 |
| 样式方案 | （如纯 CSS / Tailwind / CSS Modules） | 与目标工程一致；目标工程没有的方案不准引入 |
| 组件/图标库 | （目标工程已有的） | 只用已有的，不新增 UI 框架和图标库 |
| 设计 token 文件 | （如 src/styles.css / tokens.css） |
颜色、字号、间距的唯一来源 |
| 基准视口 | （如 1440×900） | 像素核对和验收用的视口 |
| 页面文件落位 | （如 src/routes/ + src/<page>.css） |
与目标工程目录同构 |
| Mock 数据落位 | （如 src/mock/） |
见 §4 |
| 类型定义文件 | （如 src/types.ts，可空） |
mock 字段形状的对齐目标 |
目标工程尚不存在（全新项目）时：默认 React + TypeScript + Vite + 纯 CSS，并把你定下的取值回填此表，作为后续开发工程的初始约定。
1. 交付物形态（最重要的一条）
每个页面的交付物固定为：
| 文件 | 说明 |
|---|---|
| 页面组件 | 一个独立的页面级组件文件，按参数表落位 |
| 页面样式 | 该页专属样式文件，全部选择器收敛在页面根 class 下 |
| Mock 数据 | 该页全部演示数据，集中一个文件 |
| 路由注册 | 在目标工程的路由配置中加一项，页面可直达 |
明确禁止：
- ❌ 交付静态
.html文件（任何形式，包括"先 HTML 后转组件"的中间产物） - ❌ iframe 嵌套原型、截图/图片代替可交互区域
- ❌ jQuery、CDN
<script>、内联<style>巨块 - ❌ 引入参数表之外的任何框架、UI 库、CSS 方案、图标库
2. 工作区与工程同构
- 设计稿工作区直接以目标工程的前端为模板搭骨架（入口、公共布局、token 文件、路由配置），在其上加页面；
npm run dev（或等价命令）必须能跑 - 公共骨架（侧栏/导航/页脚/Toast 等）只实现一份并各页复用，不要每页重画
- 全新项目则先搭最小可运行骨架，再出页面
3. 视觉规范
- 颜色、间距、字号一律引用参数表指定的 token 文件；新增 token 必须加进 token 文件并注释用途，不许在页面样式里写裸色值复制粘贴
- 页面样式顶层必须有唯一根 class（如
.products-page），所有规则在其作用域内，防止跨页泄漏；不要重复写 reset - 布局在基准视口下必须与设计意图逐像素一致，无横向滚动条；这是后续像素核对（pixelmatch 类工具）的验收视口
- 响应式要求由项目参数表注明；未注明时至少保证基准视口完整可用
4. 数据规范：mock 必须长得像真接口
这是历史返工的重灾区。规则：
- 每页 mock 集中放参数表指定的 mock 目录，禁止把数据硬编码散落在组件 JSX/模板里
- 目标工程已有类型定义的，mock 字段形状必须对齐；没有的，先写出 interface/类型再造数据，并在交接说明里标注"需后端提供的接口与字段"
- 组件一律通过 props 或一层
getXxx()取数函数拿数据——接真后端时只换数据源这一层 - 列表类数据至少 8 条以上真实感数据（真实语言文案、不同状态混排），并且必须设计并实现 loading / 空态 / 错误态 三种 UI
5. 交互规范：不许有死按钮
交付页面默认会被行为审计工具逐个控件真实点击验收：
- 每个按钮、tab、toggle、下拉、可点卡片，点击后必须有可观察的状态变化（切换内容、开弹窗、改样式、出提示——本地 state 实现即可）
- 弹窗/抽屉可开可关（含遮罩点击、Esc）；表单为受控输入并有提交反馈
- 暂时没想好行为的入口：宁可不画，也不要画一个没有 handler 的假按钮；确需占位的，统一
disabled+ 注明"规划中" - 控制台零 error/warning
6. 交付自查清单（每页提交前过一遍）
- dev server 启动后，该页可通过路由直达
- 类型检查/构建零错误
- 基准视口下与设计意图一致，无横向滚动条
- mock 数据集中存放、字段对齐类型定义、三态齐全
- 全部可点控件有真实 handler，控制台无报错
- 页面样式收敛在根 class 下，未污染其他页面
- 附《接口接入说明》：本页用到哪些数据、对应/期望哪个后端接口、哪些字段是新增
7. 与开发的交接标准
设计稿工作区与目标工程目录同构，开发合入一个页面的动作应该只有：拷贝页面组件 + 样式 + mock 三个文件、路由配置加一行、把 mock 取数层换成真实 API 调用。如果交接时开发需要做超出以上范围的改写，视为设计稿不合格，退回返工。