From e8e5a1cd2b70ae4064ba52b5baaa4b41030bd70b Mon Sep 17 00:00:00 2001 From: "mula.liu" Date: Sun, 1 Nov 2026 19:01:03 +0800 Subject: [PATCH] =?UTF-8?q?=E6=96=87=E6=A1=A3=E4=B8=8E=E8=84=9A=E6=9C=AC?= =?UTF-8?q?=E5=90=8C=E6=AD=A5=20React+Tailwind=EF=BC=9AUI=20=E8=A7=84?= =?UTF-8?q?=E8=8C=83=E5=A2=9E=E5=8A=A0=E8=AF=8D=E6=B1=87=E2=86=92=E5=8E=9F?= =?UTF-8?q?=E8=AF=AD=E5=AF=B9=E7=85=A7=EF=BC=8C=E5=B7=A5=E7=A8=8B=E8=A7=84?= =?UTF-8?q?=E8=8C=83=E8=A1=A5=20frontend/src=20=E5=88=86=E5=B1=82=E4=B8=8E?= =?UTF-8?q?=E6=89=A9=E5=B1=95=E7=82=B9=EF=BC=8CREADME=20=E7=9B=AE=E5=BD=95?= =?UTF-8?q?/=E6=9E=84=E5=BB=BA=E5=8F=A3=E5=BE=84=E6=9B=B4=E6=96=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 51 +++++++--- backend/app/main.py | 2 +- backend/tests/test_system_and_library.py | 2 +- docs/UI规范.md | 120 ++++++++++++++++------- docs/会话工作流整理.md | 3 +- docs/工程规范.md | 45 ++++++++- 6 files changed, 166 insertions(+), 57 deletions(-) diff --git a/README.md b/README.md index b67794e..da64143 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ > 目录职责、`scripts/` 准入规则、测试规范、改动后的最低验收三连,以及服务器上「什么该搬、什么不该搬」。 ``` -┌──────────────────────────────── Browser (Vue 3 + Vite) ────────────────────────────────┐ +┌──────────────────────── Browser (React + Vite + Tailwind CSS) ─────────────────────────┐ │ 项目总览 │ 资产库 │ 分镜与脚本 │ 调度中心 │ 质检与审核 │ 时间线合成 │ 导出与成本 │ └─────────────────────────────────────┬───────────────────────────────────────────────────┘ │ REST / JSON + multipart (vite proxy 或 nginx) @@ -35,14 +35,33 @@ ```text backend/ FastAPI 应用:app/api 路由 · app/services 编排 · app/providers 模型适配 · tests 回归用例 -frontend/ Vue 3 + Vite 工作台(public/help.html 就是上面那份图文手册) +frontend/ React 19 + Vite + Tailwind CSS v4 工作台(public/help.html 就是上面那份图文手册) scripts/ 只放启动 / 部署 / 运维脚本(下表);一次性验证探针不进这个目录 docs/ UI 规范、工程规范、H3 性能诊断记录 media/ 产物库(MEDIA_ROOT) models/ whisper 词级对齐权重 reports/ 阶段验收证据 -.local/ 开发态日志与 pid .trash/ 删除暂存(本目录不是 git 工作区,删掉就没了) +.local/ 开发态日志与 pid .trash/ 删除暂存(两者都不进 git,删掉就没了) .env 本机配置与密钥(不进部署包) nex_animation.db 开发库 ``` +**`frontend/src/` 分层**(依赖只允许自上而下,页面之间不互相 import): + +```text +api/ 唯一的 fetch 出口:信封自动拆包、detail 统一成 Error、401 跳登录 +app/ 应用外壳:router.tsx 路由表(唯一一份)· layout/ 顶栏侧栏鉴权闸门 +pages/ 页面与项目页签,一屏一文件;页面私有的类名常量/子组件留在文件底部 +components/ 无业务语义的原语,三个目录按职责分: + ui/ 版式与控件(Button/Field/Ctlbar/Table/Modal/Drawer/Tag…) + forms/ 选择器族(Select/MultiSelect/SecretInput + toOptions) + media/ 带全局状态的媒体件(MediaThumb/AudioPlay/MediaLightbox/WorkflowBar…) +stores/ zustand 切片:auth · theme · notice · project · models · system · audio · preview +hooks/ use-async / use-polling / use-auto-refresh / use-outside-click / use-local-storage +lib/ 纯函数与适配器:cn · format · media · pipeline · recorder · versions +styles/ tokens.css(设计令牌 = 唯一尺子来源)· base.css(元素级基线) +``` + +新增页面只做三件事:在 `pages/` 落文件 → 在 `app/router.tsx` 注册 → 复用 `components/*` 原语, +缺原语就补进 `components/`(不要复制粘贴样式)。加一类新母版/新页签同理:改表不改逻辑(见 `docs/工程规范.md` §1.1)。 + | 脚本 | 干什么 | 在哪儿跑 | | --- | --- | --- | | `scripts/dev.sh` | 开发态前后端两个进程(后端 8000 + Vite 5173),缺 `.env` / `.venv` / `node_modules` 自己补 | 开发机 | @@ -58,16 +77,16 @@ media/ 产物库(MEDIA_ROOT) models/ whisper 词级对齐权重 r | 模块 | 后端服务 / 接口 | 前端页面 | 关键能力 | | --- | --- | --- | --- | -| **① 人物与声音资产库** | `app/api/platform.py`、`app/api/library.py`、`services/storage.py`、`services/audio.py` | `views/AssetLibrary.vue`、`views/tabs/Library.vue` | 平台级人物 / 场景 / 声线母版创建时始终全局,不绑定项目;项目目标只在「引入项目」时选择。母版可上传、AI 生成、编辑,项目资产可反向「上架平台」。图片支持大图预览,每个媒体可单独删除,不必删除母版。声线在创建时只录入基础设定,生成试听时再选真实模型;项目内继续维护定妆图/三视图/服装/表情、场景图、声线与项目素材;每次上传生成**新版本**,删除留痕 | -| **② 分镜与脚本管理** | `app/api/storyboard.py`、`services/importer.py`、`services/prompt.py`、`services/preflight.py` | `views/tabs/Storyboard.vue`(分镜工作台) | Markdown/CSV/TSV/JSON/纯文本脚本导入 + 图片按镜号自动匹配关键帧(支持 zip);`shots/preview` 与 `dry_run` 先预览后落库;镜头增删改/排序、人物场景绑定、提示词组装与**版本留痕**、首尾帧/参考图上传;`shots/board` 轻量看板(逐镜预检)、`shots/bulk` 批量复制/移动/改参/删除、`shots/export` 反向导出 md/csv/json | -| **③ 视频模型调度中心** | `app/api/pipeline.py`、`services/dispatch.py`、`services/capacity.py`、`services/execution.py`、`services/daemon.py`、`app/providers/*` | `views/tabs/Dispatch.vue` | 任务清单(预检驱动,可解释「为什么跳过/阻塞」)→ 入队 → 按 provider/model 并发槽位与 RPM 限流派发(**一个模型一行**,视频与 TTS 各自的限额互不串台) → 指数退避重试 → 中断任务断点续跑;模型注册表在线启停/设默认/调并发/调限流/注入故障演练 | -| **④ 长视频合成引擎** | `app/api/delivery.py`、`services/timeline.py`、`services/compose.py`、`services/ffmpeg.py`、`services/quality.py` | `views/tabs/Review.vue`、`TimelineTab.vue`、`Delivery.vue` | 自动质检 7 项打分;人工审核合格/驳回重做;时间线(片段裁剪/转场/排序/字幕/配音/BGM/响度归一化);交付预检报告;4 档出片预设 + 校验和留档;成本台账与生成记录可复现 | -| **底层:任务编排 + 项目数据库** | `app/models/*`、`app/db.py`、`services/events.py`、`services/status.py`、`services/costing.py` | `views/Dashboard.vue`、`ProjectDetail.vue`、`tabs/Overview.vue` | 12 张表(项目/人物/场景/声线/素材/素材版本/镜头/任务/审核/时间线/片段/字幕/音轨/导出/成本/生成记录/事件);任务幂等键、心跳、错误历史、检查点;全流程事件流与流程进度视图 | +| **① 人物与声音资产库** | `app/api/platform.py`、`app/api/library.py`、`services/storage.py`、`services/audio.py` | `pages/AssetLibrary.tsx`、`pages/project/Library.tsx` | 平台级人物 / 场景 / 声线母版创建时始终全局,不绑定项目;项目目标只在「引入项目」时选择。母版可上传、AI 生成、编辑,项目资产可反向「上架平台」。图片支持大图预览,每个媒体可单独删除,不必删除母版。声线在创建时只录入基础设定,生成试听时再选真实模型;项目内继续维护定妆图/三视图/服装/表情、场景图、声线与项目素材;每次上传生成**新版本**,删除留痕 | +| **② 分镜与脚本管理** | `app/api/storyboard.py`、`services/importer.py`、`services/prompt.py`、`services/preflight.py` | `pages/project/Storyboard.tsx`(分镜工作台) | Markdown/CSV/TSV/JSON/纯文本脚本导入 + 图片按镜号自动匹配关键帧(支持 zip);`shots/preview` 与 `dry_run` 先预览后落库;镜头增删改/排序、人物场景绑定、提示词组装与**版本留痕**、首尾帧/参考图上传;`shots/board` 轻量看板(逐镜预检)、`shots/bulk` 批量复制/移动/改参/删除、`shots/export` 反向导出 md/csv/json | +| **③ 视频模型调度中心** | `app/api/pipeline.py`、`services/dispatch.py`、`services/capacity.py`、`services/execution.py`、`services/daemon.py`、`app/providers/*` | `pages/project/Dispatch.tsx` | 任务清单(预检驱动,可解释「为什么跳过/阻塞」)→ 入队 → 按 provider/model 并发槽位与 RPM 限流派发(**一个模型一行**,视频与 TTS 各自的限额互不串台) → 指数退避重试 → 中断任务断点续跑;模型注册表在线启停/设默认/调并发/调限流/注入故障演练 | +| **④ 长视频合成引擎** | `app/api/delivery.py`、`services/timeline.py`、`services/compose.py`、`services/ffmpeg.py`、`services/quality.py` | `pages/project/Review.tsx`、`Timeline.tsx`、`Delivery.tsx` | 自动质检 7 项打分;人工审核合格/驳回重做;时间线(片段裁剪/转场/排序/字幕/配音/BGM/响度归一化);交付预检报告;4 档出片预设 + 校验和留档;成本台账与生成记录可复现 | +| **底层:任务编排 + 项目数据库** | `app/models/*`、`app/db.py`、`services/events.py`、`services/status.py`、`services/costing.py` | `pages/Dashboard.tsx`、`pages/ProjectDetail.tsx`、`pages/project/Overview.tsx` | 12 张表(项目/人物/场景/声线/素材/素材版本/镜头/任务/审核/时间线/片段/字幕/音轨/导出/成本/生成记录/事件);任务幂等键、心跳、错误历史、检查点;全流程事件流与流程进度视图 | ## 2. 图2 业务流程 → 状态机与接口 流程节点定义在 `backend/app/services/status.py:PIPELINE_STAGES`,每个项目/镜头/任务的真实状态收敛成 -`GET /api/projects/{id}` 的 `workflow[]`(`pending/active/done/failed`),前端 `WorkflowBar.vue` 直接渲染。 +`GET /api/projects/{id}` 的 `workflow[]`(`pending/active/done/failed`),前端 `components/media/WorkflowBar.tsx` 直接渲染。 | # | 节点 | 主要接口 | 镜头状态流转 | | --- | --- | --- | --- | @@ -87,7 +106,7 @@ media/ 产物库(MEDIA_ROOT) models/ whisper 词级对齐权重 r 失败与恢复:`POST /api/tasks/{id}/retry|cancel`、`POST /projects/{id}/tasks/retry-failed`、`/tasks/cancel-active`、 `/projects/{id}/resume`(`running` 超过 `STALE_RUNNING_SECONDS` 视为中断并带上 checkpoint 续跑)。 -### 2.1 项目主页 LLM 总控台(`views/tabs/Overview.vue`) +### 2.1 项目主页 LLM 总控台(`pages/project/Overview.tsx`) 项目主页顶部提供自然语言总控台:使用系统注册并启用的默认真实 LLM 盘点镜头、关键帧、模型能力和 当前阻塞,先落库为可审阅的执行计划,再由用户确认执行。LLM 不直接操作媒体或数据库,后端只接受 @@ -109,7 +128,7 @@ build_timeline / compose` 八个白名单动作。主题或剧情变化时,`re 不会在真实模型缺失时静默回退。已完成且产物有效的步骤会跳过,失败步骤可从断点继续;实现见 `backend/app/services/agent.py`,契约测试见 `backend/tests/test_agent_orchestrator.py`。 -### 2.2 分镜工作台(`views/tabs/Storyboard.vue`) +### 2.2 分镜工作台(`pages/project/Storyboard.tsx`) 分镜是几十上百镜的大页面,所以列表**不**走返回全字段的 `GET /shots`,而是按用途拆成三层: @@ -199,7 +218,7 @@ cd frontend && npm install && npm run dev # http://localhost:5173 > **前端开发态代理**:`frontend/vite.config.ts` 必须把 `/api`、`/health`、`/media`、`/docs`、 > `/openapi.json` **五条路径一起**代理到后端。少代理任意一条,Vite 的 SPA 回退会用 > `index.html` 应答,前端拿到 `200` 却没有字段,对应面板就静默失效(侧边栏曾因此整块显示 -> 「任务执行 —/ffmpeg 缺失/字幕烧录 滤镜缺失/调度守护 未运行」)。`src/store.ts` 现在会 +> 「任务执行 —/ffmpeg 缺失/字幕烧录 滤镜缺失/调度守护 未运行」)。`src/stores/system.ts` 现在会 > 校验 `typeof health.status === 'string'`,一旦代理缺失直接抛出可读错误而不是假装健康。 > > **后端换地址/换端口**:`NEX_BACKEND=http://127.0.0.1:8010 npm run dev`,无需改代码。 @@ -236,7 +255,7 @@ curl -s -b /tmp/nex.jar localhost:8000/api/meta | jq '.presets,.options.transiti 开发态是「Vite 5173 + 后端 8000」两个进程;服务器上不需要 Vite—— `SERVE_FRONTEND=on` 让**同一个进程**既出 API 又发 `frontend/dist`, -vue-router 的 history 回落已经处理好(地址栏直接刷 `/projects/3` 不会 404), +React Router 的 history 回退已经处理好(地址栏直接刷 `/projects/3` 不会 404), 反向代理只需转发一处,`/api`、`/media`、`/docs` 与页面同源。 `SERVE_FRONTEND` 默认 `off`,所以开发与测试行为完全不变。 @@ -577,7 +596,9 @@ NEX_BASE=http://127.0.0.1:8000 ../.venv/bin/python scripts/e2e_selfcheck.py ### 6.3 前端构建 ```bash -cd frontend && npm run build # vite build(当前 51 modules / ~239 KB,gzip ~76 KB) +cd frontend && npm run build # tsc --noEmit && vite build +# 当前 100 modules;页面按路由分包,全部 chunk 合计 ~863 KB(gzip ~283 KB)+ CSS 85 KB(gzip 17 KB) +# 首屏只下载 index(~409 KB/130 KB gzip) + 共享原语 ui(~80 KB/26 KB gzip) + 当前页 chunk ``` ## 7. 边界与说明 @@ -586,7 +607,7 @@ cd frontend && npm run build # vite build(当前 51 modules / ~239 KB,gz - 登录鉴权(会话 Cookie + 角色闸门)与供应商密钥加密落库**已内置并默认开启**,页面只回显掩码; 公网部署仍建议放在 HTTPS 反代后面,并把 `MEDIA_ROOT` 放在受控存储上。关掉鉴权只适合可信内网。 - 媒体文件一律由后端 `/media/*` 直出,前端不拼本地路径;导出记录保留 `checksum`、`size_bytes`、`elapsed_ms` 便于对账。 -- 变更类接口统一返回 `{ok, result, summary}`(前端 `src/api.ts` 自动拆包),错误体统一读 `detail`;只读接口大多直接返回资源对象,**两个例外**是 `GET /api/projects/{id}` 与 `GET /api/projects/{id}/summary`——它们也带信封(前端已统一处理,写脚本时记得拆开或自动拆)。 +- 变更类接口统一返回 `{ok, result, summary}`(前端 `src/api/client.ts` 自动拆包),错误体统一读 `detail`;只读接口大多直接返回资源对象,**两个例外**是 `GET /api/projects/{id}` 与 `GET /api/projects/{id}/summary`——它们也带信封(前端已统一处理,写脚本时记得拆开或自动拆)。 ### 7.1 前后端契约(已用回归用例锁死,改动前请先跑 `tests/test_regression_fixes.py`) diff --git a/backend/app/main.py b/backend/app/main.py index 0b7ab42..180797d 100644 --- a/backend/app/main.py +++ b/backend/app/main.py @@ -93,7 +93,7 @@ if settings.serve_frontend_enabled() and FRONTEND_DIST is None: if FRONTEND_DIST is not None: # 不能把整个目录挂到 "/":那会遮住已经注册的 /api、/media、/docs。所以拆成两条: # 哈希资源走目录挂载,其余路径交给下面的 catch-all 做 history 回落。 - # vue-router 用的是 createWebHistory,/projects/3 这类深链在磁盘上没有对应文件, + # React Router 用的是 history 模式(browser history),/projects/3 这类深链在磁盘上没有对应文件, # 必须回 index.html 交给前端路由,否则用户刷新一次就 404。 if (FRONTEND_DIST / "assets").is_dir(): app.mount("/assets", StaticFiles(directory=FRONTEND_DIST / "assets"), name="spa-assets") diff --git a/backend/tests/test_system_and_library.py b/backend/tests/test_system_and_library.py index c8dc4be..12d6885 100644 --- a/backend/tests/test_system_and_library.py +++ b/backend/tests/test_system_and_library.py @@ -10,7 +10,7 @@ from tests.test_delivery import _make_wav def test_health_and_meta(api): health = api.get("/health") - # 侧边栏状态灯直接读这些字段名,改名必须同步 frontend/src/App.vue + # 侧边栏状态灯直接读这些字段名,改名必须同步 frontend/src/app/layout/SideNav.tsx assert health["status"] == "ok" assert health["executor"] == "inline" assert set(health) >= {"app", "executor", "ffmpeg", "ffmpeg_capabilities", "database", "daemon"} diff --git a/docs/UI规范.md b/docs/UI规范.md index 4f75b0a..adfe75a 100644 --- a/docs/UI规范.md +++ b/docs/UI规范.md @@ -2,11 +2,20 @@ > 适用范围:`frontend/src` 全部页面与组件。本文件是**唯一权威**:新页面照此写, > 老页面遇到不符的地方按此改。规范里每条都给出「对应类名」和「验收探针」, -> 探针脚本 `/tmp/nexshot/audit16.js` 会全站跑一遍,红项必须在报告里逐条解释或修掉。 +> 探针脚本 `/tmp/nexshot/audit16.js` 会全站跑一遍,红项必须在报告里逐条解释或修掉 +> (前端换成 React 后这些探针还能用,但容器类名那一半已经失效,见 §8 第 5 条的说明)。 > -> 先读 `style.css` 里的三块基础设施,再动手: -> ① 控件高度体系(`--ctl-h` / `--ctl-h-md`)② 本规范的控件栏体系(`.ctlbar` / `.fld`) -> ③ 抽屉体系(`.drawer*`)。三块都只允许在 `style.css` 里改,页面不要各自发明尺子。 +> **本文的类名是设计词汇,不是 DOM 契约。** 前端已经是 React 19 + Tailwind CSS v4: +> 规范尺子住在 `styles/tokens.css`(令牌)与 `styles/base.css`(元素基线), +> 布局皮肤住在 `components/{ui,forms,media}` 的原语里,DOM 上只有 Tailwind 工具类。 +> 所以下文写 `.ctlbar` / `.fld` / `.btn-add` 时,**照 §0.5 的对照表落成组件属性**, +> 不要去新代码里 grep 这些类名,也不要为了让探针好看把它们塞回 `className`。 +> +> 动手前先读三块基础设施,它们各自只有一份实现: +> ① 控件高度体系(`--ctl-h` / `--ctl-h-md` / `--ctl-h-main`,`styles/tokens.css`) +> ② 控件栏与字段体系(`Ctlbar` / `Field` / `FormRow`,`components/ui/Controls.tsx`) +> ③ 浮层体系(`Drawer` / `Modal`,`components/ui/Overlay.tsx`)。 +> 尺子只允许在这三处改,页面不要各自发明。 --- @@ -19,14 +28,47 @@ | R3 | **同一行控件必须等高、垂直居中**(`align-items:center` + 继承 `--ctl-h`);一行里出现两种高度 = 尺子坏了 | 图3 搜索框与右侧下拉中心线错开 | | R4 | **chip / 标签行与下方内容至少 10px 间隔**(`.chipbar`),且标签行本身不参与贴边 | 图2 「标签」chip 行压住下方面板 | | R5 | **筛选项准入**:每个筛选项必须 ① 对应后端真实参数 ② 在当前设计里有可达的非默认值 ③ 与页面顶部已选的大分类一致。三者缺一就删 | 图3 「每页」属于分页条,不属于筛选栏 | -| R6 | **不用原生 ``**:单选 `Select`、多选 `MultiSelect`(`components/forms`);自动刷新类组件不放「立即刷新」按钮 | 全站历史问题 | --- +## 0.5 规范词汇 → React 原语对照 + +新页面照这张表落地;表里没有的旧类名,先在 `frontend/src` 里 grep 它的中文注释, +找不到就是已经废弃。**原语都在 `components/` 的三个 barrel 里统一导出** +(`import { Ctlbar, Field, Button } from '../components/ui'`)。 + +| 本文的叫法 | React 里怎么写 | 实现位置 | +|---|---|---| +| `.ctlbar`(含 `.toolbar` `.filters` `.searchbar` `.lib-tools` `.sb-*` `.card-actions` `.cardfoot` `.usage-line` `.title-line` `.event-filter` `.ai-bar` `.agent-options`) | `` | `ui/Controls.tsx` | +| 右侧动作 `.bar-right`(不许 `margin-left:auto`) | ``;卡片动作行用 `` | `ui/Controls.tsx` | +| `.fld`(标签在左、控件在右) | `` | `ui/Controls.tsx` | +| 标签在上的字段(`.field` + `.lbl` + `.req`) | ``,星号是 `` | `ui/Controls.tsx` | +| `.frow cols3 stack tight segfields` | `` | `ui/Controls.tsx` | +| `.chipbar` / `.chipbar-label` / `.tag-chip` | `` + `` / `` | `ui/Controls.tsx` | +| `.view-btn` 分段视图切换 | `` | `ui/Tabs.tsx` | +| `.pager` | ``(`0` = 全部) | `ui/Controls.tsx` | +| `.check` | `` | `ui/Controls.tsx` | +| `.upload` / 选文件 | `` | `ui/Controls.tsx` | +| 原生 `` / ``,选项一律过 `toOptions` | `forms/Select.tsx` · `forms/MultiSelect.tsx` | +| `.primary` `.secondary` `.outline` `.ghost` `.tiny` `.danger` | ` - + 第 1 / 3 页 · 共 168 个 @@ -330,7 +373,7 @@ ## 6. 其它全站约定(历史决策,别改回去) - 分段页签组 `.inspector-tabs`(分镜表检查器「分镜 / 提示词 / 生成记录」)属**紧凑族**: - 高度已在 `style.css` 统一取 `--ctl-h-md`(`display:inline-flex + align-items:center + gap:4px`), + 高度已在 `Pager` 里统一取 `--ctl-h-md`(`inline-flex + items-center + gap-1`), 页面 CSS **不得**再写 `padding:8px 4px` 之类把它撑成第三种高度。 - 纵向堆叠的面板用 `.tabstack`:`> * + *` 自动 16px 呼吸,页面别再给单个面板写 `margin-top`。 - 一行状态只有两种骨架,选完别再手搓 flex/grid: @@ -350,7 +393,7 @@ - 服务监听 `0.0.0.0`,ComfyUI 只用 9200,后端不得继承系统代理。 - 字号下限 10px;正文 13px;表格 11.5px。 - 主题变量只用 `--c-*`,禁止硬编码颜色(`#hex`/`rgb()` 只允许出现在 `theme.css`)。 -- CJK 按钮文案必须 `white-space:nowrap`:`style.css` 里由全局 `button{white-space:nowrap}` 兜住 +- CJK 按钮文案必须 `white-space:nowrap`:`Button` 基础类自带 `whitespace-nowrap`,手写 `