文档与脚本同步 React+Tailwind:UI 规范增加词汇→原语对照,工程规范补 frontend/src 分层与扩展点,README 目录/构建口径更新

main
mula.liu 2026-11-01 19:01:03 +08:00
parent e677d891d4
commit e8e5a1cd2b
6 changed files with 166 additions and 57 deletions

View File

@ -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`)

View File

@ -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")

View File

@ -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"}

View File

@ -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>`**:单选 `FSelect`、多选 `FMultiSelect`;自动刷新类组件不放「立即刷新」按钮 | 全站历史问题 |
| R6 | **不用原生 `<select>`**:单选 `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`) | `<Ctlbar>` | `ui/Controls.tsx` |
| 右侧动作 `.bar-right`(不许 `margin-left:auto`) | `<BarRight>`;卡片动作行用 `<CardActions>` | `ui/Controls.tsx` |
| `.fld`(标签在左、控件在右) | `<Field label required width="default\|grow\|narrow\|wide\|full" hint>` | `ui/Controls.tsx` |
| 标签在上的字段(`.field` + `.lbl` + `.req`) | `<FieldBlock label required title>`,星号是 `<Req>` | `ui/Controls.tsx` |
| `.frow cols3 stack tight segfields` | `<FormRow cols={3} stack tight>` | `ui/Controls.tsx` |
| `.chipbar` / `.chipbar-label` / `.tag-chip` | `<ChipBar label>` + `<Chip>` / `<TagChip count on>` | `ui/Controls.tsx` |
| `.view-btn` 分段视图切换 | `<ViewBtn on>` | `ui/Tabs.tsx` |
| `.pager` | `<Pager sizes total pageSize onChange>`(`0` = 全部) | `ui/Controls.tsx` |
| `.check` | `<Check checked onChange disabled title>` | `ui/Controls.tsx` |
| `.upload` / 选文件 | `<FilePick label hint onChange>` | `ui/Controls.tsx` |
| 原生 `<select>`(R6 禁用) | `<Select options>` / `<MultiSelect>`,选项一律过 `toOptions` | `forms/Select.tsx` · `forms/MultiSelect.tsx` |
| `.primary` `.secondary` `.outline` `.ghost` `.tiny` `.danger` | `<Button variant size="sm\|md\|lg" danger on>` | `ui/Button.tsx` |
| `.btn-add` `.btn-del` `.btn-del.solid` `.sq` `.lg` | `<Button variant="add">` / `variant="del"` / `variant="del" danger` / `square` / `size="lg"` | `ui/Button.tsx` |
| `<a>` 要按钮皮肤(路由跳转) | `buttonCls({ variant })` 或 `<Button variant="link">` | `ui/Button.tsx` |
| `.tag` `.tag.ok/.warn/…` | `<Tag tone="default\|ok\|bad\|warn\|info\|accent\|mono">` | `ui/Status.tsx` |
| `.linehint` | `<LineHint>`(成行告警);空内容不渲染的用 `<Notice>` / `<ErrorText>` | `ui/Panel.tsx` · `ui/Page.tsx` |
| `.drawer` `.drawer-backdrop` `.drawer-x` `.drawer-actions` | `<Drawer title sub eyebrow actions width>`(`actions` 就是外壳直接子元素那一层) | `ui/Overlay.tsx` |
| 对话框 / `.modal` | `<Modal title eyebrow footer width>` | `ui/Overlay.tsx` |
| `.small-label` + `.sect-act` | `<SectionTitle action>` / `<PanelHead right eyebrow sub>` | `ui/Panel.tsx` |
| `v-if` / `v-show` | `{cond && <X />}` / `hidden`(条件挂载本身要保留,见 G2) | JSX |
| `v-model.number="filters.page_size"` | `value={…}` + `onChange={(next) => …}` | 受控组件 |
| `:deep(.aplay){min-width:110px}` | 传 `className`(`cn` 走 tailwind-merge,**后写的赢**)或容器上的任意变体 `[&>*]:min-w-[110px]` | `lib/cn.ts` |
| `@media (max-width:1180px)` | 断点变体写在类上:`max-huge:`1440 `max-mid:`1180 `max-mid2:`1100 `max-nav:`900 `max-short:`820 `max-tiny:`640 `max-narrow:`560 | `styles/tokens.css` |
| 栅格降列 | `<Grid cols min oneAt steps>`——变量驱动,页面不写 `@media` | `ui/Panel.tsx` |
## 1. 控件栏(工具条 / 筛选条 / 搜索条 / 卡片动作行)
规范类名 `.ctlbar`,它是**所有**含控件横条的唯一实现。页面里出现下列任意旧类名时,
语义一律等同 `.ctlbar`(`style.css` 已把它们合并到同一条规则,不再各自定义布局):
语义一律等同 `.ctlbar`,在 React 里它们全部塌缩成同一个 `<Ctlbar>`(不再各自定义布局):
```
.toolbar .filters .searchbar .lib-tools .sb-tools .sb-actions .card-actions
@ -35,16 +77,17 @@
另有一类**弹层 / 对话框内部条**(`.lb-head .head-right .verpick .vp-head .rec-head
.fmulti-bar .ai-box .generation-reference .pager .chipbar`):它们的外框布局
(grid、粘性头部、内部排版)保留各自的皮肤,`style.css` 只在这里统一
`--ctl-h:var(--ctl-h-md)`。**页面 CSS 里禁止再出现 `--ctl-h`**,需要紧凑高度时
把容器名登记到 `style.css` 的紧凑容器清单里。
(grid、粘性头部、内部排版)保留各自的皮肤,只在容器上统一声明
`[--ctl-h:var(--ctl-h-md)]`。**页面禁止给单个控件写死像素高度**,需要紧凑高度时
只在自己的**容器**类上写这一句,控件用 `h-(--ctl-h)` 跟随;`Ctlbar` / `ChipBar`
已经把这件事做掉了,页面里不要再出现 `--ctl-h-main` 之外的第三种尺子。
### 1.1 结构
```html
<div class="ctlbar">
<label class="fld grow"><span>搜索</span><input … /></label>
<label class="fld"><span>素材类型</span><FSelect>…</FSelect></label>
<label class="fld"><span>素材类型</span><Select>…</Select></label>
<label class="check"><input type="checkbox" />仅疑似重复</label>
<span class="bar-right">…右侧动作…</span> <!-- 需要右靠时用它,不用 margin-left:auto -->
<AutoRefresh … />
@ -77,7 +120,7 @@
#### 1.2.0 高度令牌:宽度变了只改令牌,不改控件
全站高度**两个档位 + 一个触屏档开关**,全部由 `style.css` 顶部三个自定义属性决定,
全站高度**两个档位 + 一个触屏档开关**,全部由 `styles/tokens.css` 三个自定义属性决定(`--ctl-h-main` 38 / `--ctl-h-md` 31 / `--ctl-h` 默认取主档,`@media (max-width:560px)` 把两档抬到 40 / 36),
**媒体查询也只许动令牌**(第二十二章起):
```css
@ -106,7 +149,7 @@
档位只有两档:`--ctl-h` = 38px、`--ctl-h-md` = 31px;≤560px 触屏档另给 40 / 36
(手机上要够得到,探针同时放行这两档)。下面这些**不是行内文字控件**,高度由内容或
所依附的画面决定,不参与档位 —— 探针(`audit16.js` CTL-H)按类名排除:
所依附的画面决定,不参与档位 —— 探针(`audit16.js` CTL-H)按类名排除(React DOM 上这些类名已不存在,见 §8 第 5 条):
| 例外 | 尺寸 | 为什么不参与档位 |
|---|---|---|
@ -119,7 +162,7 @@
是行内文字链接不是控件,靠 `< 26px` 兜底放行;**必须 `white-space:nowrap`**,否则被 flex 行挤成
两行行盒就是 30px「野高度」,CTL-H 判红 —— 这是真 bug,不要为了它往本表加例外 |
| `.type-button` 文案 | 折行 | 类型导航卡是热区:标题 + 说明 + 计数在窄导轨里**必须能折行**,
所以 `style.css` 全局 `button{white-space:nowrap}` 对它显式放开(`white-space:normal`) |
所以 `Button` 基础类的 `whitespace-nowrap` 要在那一处显式放开(`whitespace-normal`) |
| `.rec-big` | 48px | 录音面板唯一的**主操作钮**(开始 / 停止录制),要一眼看出可点、录音中要点准;比 `--ctl-h` 大一档。探针按「h > 44 视为触控主钮」放行 |
新增这类控件时**必须回来登记一行**,否则 CTL-H 判红;登记的前提是它确实不是行内文字控件。
@ -137,7 +180,7 @@
> 第二十二章 430px 音频行实测:`aplay=117,312,`**`27`**`,54` —— `flex:1 1 auto` + `min-width:0`
> 把播放条挤到 27px,内部那颗 22px 的 `⤢` 整个溢出到兄弟音色徽标上(`CROWD-V`)。
> `min-width:0` 允许控件缩到**比自己的最小内容宽度还小**,于是「同行等高做到了、宽度塌了」。
> 规范:这类行里的控件必须写**保底宽度**(`.audio-row :deep(.aplay){min-width:110px}`),
> 规范:这类行里的控件必须写**保底宽度**(容器上 `[&>*]:min-w-[110px]`,或给 `AudioPlay` 外层传 `className`),
> 徽标改成可截断(`.timbre-flag{flex:0 1 auto;min-width:0}` + `text-overflow:ellipsis` + `title`)。
> 自查判据:`rect.width` < 「该行内所有不可缩子项宽度 + gap」= 塌了,去看 CROWD-V。
@ -179,7 +222,7 @@
```
- 高度 31px(`.tag-chip`/`.chip` 已定高);**页面内不得再给 chip 写 `padding`/`min-height` 覆盖**,
尺寸只有一个来源(`style.css`)。
尺寸只有一个来源(`Chip` / `TagChip` 原语 + 容器 `--ctl-h` 档)。
- `margin:0 0 12px`(与下方网格/面板的呼吸),行首标签用 `.chipbar-label`(不要裸 `<span>`)。
- 上方是**媒体预览 / 音频条**这类自带高度的块时,加 `.chipbar top`(`margin-top:12px`),
不要在 markup 上写 `style="margin-top:…"`。
@ -216,12 +259,12 @@
只保留皮肤(边框/背景)。规则:
① 星号必须与标签文字同在 `.lbl` 里(或用全局 `:has` 兜底);
② 单独一个短字段不许脱离栅格自己占满一行;
③ 列数由容器决定,页面不写 `@media` 改列数(`style.css` 统一在 1180/900px 降列)。
③ 列数由容器决定,页面不写 `@media` 改列数(用 `<Grid cols oneAt steps>` 或断点变体 `max-mid:`/`max-nav:`)。
```html
<div class="frow">
<label class="fld"><span>模型</span><FSelect>…</FSelect></label>
<label class="fld"><span>画幅</span><FSelect>…</FSelect></label>
<label class="fld"><span>模型</span><Select>…</Select></label>
<label class="fld"><span>画幅</span><Select>…</Select></label>
</div>
<label class="field"><span class="lbl">试听文本 <b class="req">*</b></span>
<textarea rows="2"></textarea><small class="muted">说明文字</small></label>
@ -236,7 +279,7 @@
不得共用一行(图4「AI 试听」与「模型」挤在一起)。
- **抽屉只有三段式**:外壳 `display:flex;flex-direction:column` → `.drawer-head`(`flex:none`)
+ `.drawer-body`(`flex:1;overflow-y:auto`,唯一滚动区)+ `.drawer-actions`(`flex:none`,吸底动作条)。
长表单的保存/放弃**必须**是外壳的直接子元素 `.drawer-actions`,按当前页签 `v-if` 切换内容;
长表单的保存/放弃**必须**走 `<Drawer actions={…}>`(它是外壳的直接子元素),按当前页签条件切换内容;
不要在 `.drawer-body` 里塞 `position:sticky;bottom:0` 的假吸底 —— 它抵不掉 body 的 24px 下 padding
(滚到底留一条死区),中途还会停在半屏把后面的控件压在身下(第十八章 18.2)。
- **逐句行内 textarea 例外**:台词 / 字幕这类「一列多行」的行内文本框用 `min-height:56px`
@ -317,7 +360,7 @@
```html
<div class="pager">
<button class="outline tiny">← 上一页</button>
<label class="fld"><span>每页</span><FSelect v-model.number="filters.page_size">…</FSelect></label>
<label class="fld"><span>每页</span><Select value={filters.page_size} onChange={…}>…</Select></label>
<span>第 1 / 3 页 · 共 168 个</span>
<button class="outline tiny">下一页 →</button>
</div>
@ -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`,手写 `<button>` 时自己补
(第十六章之前只有 `.actions/.row/.card-actions` 等四个容器被覆盖,漏掉的按钮折行就长出「野高度」)。
卡片式按钮(`.type-button`)是唯一反向例外,见 §1.2.1。页面里别写 `width`。
@ -364,7 +407,7 @@
### G1 · 增加类按钮(`+ …`)贴在它作用的标题行右端,0 额外行
- 标题行 = `h1..h4` / `.sb-sect` / `.lbl` / `.small-label` / `.panel-head`;
把按钮放进全局类 **`.sect-act`**(`style.css`:`margin-left:auto` + 横向 flex +
把按钮放进 **`<SectionTitle action={…}>` / `<PanelHead right={…}>`**(原语内部就是 `ms-auto` + 横向 flex +
`flex-wrap:wrap`),标题行本身允许换行,窄列下整行折一次而不是横向溢出。
- **禁止**出现只装一个 `+` 按钮的 `.actions` / `.linedlg-foot` / 独立 `.row`。
同一标题行要放多个动作可以,但必须和该标题行同高(走 `--ctl-h-md`)。
@ -372,14 +415,14 @@
### G2 · 说明文字不上版面
**`.hintline` 类已彻底废弃**(全站 grep 必须为 0,`style.css` 与页面局部样式都不许留)。
**`.hintline` 已彻底废弃**(全站 grep 必须为 0,`styles/` 与页面里都不许留);成段解释文字唯一合法去处是 `<LineHint>` 或 `title`。
原来挂 `.hintline` 的东西按三类处置:
| 原内容性质 | 处置 |
|---|---|
| 静态操作说明(「勾选后会一直等到任务执行完」) | **删**,信息写进被描述控件的 `title` |
| 数据回显(当前值、摘要、出片参数、预设清单) | 改挂 **`.val`**(11px,`--c-text-2`,可断词),它是内容不是说明 |
| 条件出现的状态 / 告警(必须 `v-if`) | 短的用 `.tag`,一行的用全局 **`.linehint`** |
| 条件出现的状态 / 告警(必须条件挂载,不许常驻 DOM 藏起来) | 短的用 `<Tag>`,一行的用 `<LineHint>` |
标签上带括号补充(`画面描述(会进入提示词)`)一律砍成短标签,补充进该控件 `title`。
@ -415,10 +458,11 @@
台词行以前左边是 31px 的说话人下拉、右边是 `min-height:56px` 的输入窗,
一行里两种高度,看着就是没对齐。现在:**同一行里只要出现下拉 / 单行控件,
`textarea` 默认收成一行并与同行控件严格等高**;长文本靠 `resize:vertical` 手动往下拖,
默认高度不再破例。规则集中在 `style.css`(三条 `:has()` 选择器,覆盖
`.linedlg-row/.row/.tagrow/.libtogglebar/.form-compact/.ctlbar`,以及
`.frow/.grid2/.grid3/.gen-fields/.segfields/.form-grid` 里「同栅格行存在下拉」的字段),
页面 CSS 禁止再写 `.linedlg-row textarea{min-height:56px}` 这类局部覆盖。
默认高度不再破例。React 版把这条降级成了**一条元素基线**:
`styles/base.css` 里 `textarea{min-height:var(--ctl-h);resize:vertical}` ——
控件行容器(`Ctlbar` / `ChipBar` / 紧凑 `FormRow`)自己声明了紧凑档,
里面的 `textarea` 自动降到 31px,不再需要旧站那三条 `:has()` 探测选择器。
页面禁止再写 `min-h-[56px]` 这类局部覆盖。
整块编辑器(脚本导入 `rows=10`、提示词编辑器 `rows=7`、总控台指令框 `rows=5`)
不在任何控件行里,保持多行。
@ -445,7 +489,7 @@
探针把这些容器整体列为「数据区」,区内小字不计违规。
- **空态**:`.empty`、`Overview` 的 `.agent-empty`(含 `.agent-empty-hero` 的一句话引导)保留。
- **条件告警条**:`Library` 抽屉的 `.provider-warning`、`RecordAudio` 的 `.rec-note/.rec-warn/.rec-bad`、
顶栏用户胶囊里的 `.cap-note` = 只在条件成立时出现,保留(但必须带 `v-if`,不许常驻)。
顶栏用户胶囊里的提示位(`UserMenu`)= 只在条件成立时挂载,保留(不许常驻 DOM 再靠样式藏)。
- **页头 `header.hero` 右端的页面级主操作**(如资产库「+ 新建声线」)允许与标题同区,
它本身就是标题行右端;不再往 `.sect-act` 里塞。
- **G4 例外**:素材缩略图右上角的 `.media-remove`(20px 圆叉贴在图上,与 `MediaThumb` 的 `vN`
@ -459,17 +503,23 @@
## 8. 改动流程(每个页面必须走完)
1. `stat` 看 mtime:并行会话可能正在改同一个文件(本仓库不是 git,没有冲突提示)。
2. 改 markup 用 `.ctlbar/.fld/.chipbar/.frow/.field` 收敛,删掉页面里的布局补丁。
3. `npx vue-tsc --noEmit -p tsconfig.json` → EXIT=0。
4. `npx vite build` → 通过。
1. `git status --short` + `stat` 看 mtime:并行会话可能正在改同一个文件,动手前先确认没人在写。
2. 改 markup 用 `Ctlbar / Field / FieldBlock / ChipBar / FormRow` 收敛,删掉页面里的布局补丁;
缺原语就补进 `components/`,别在页面里手搓 `div + className`。
3. `cd frontend && npx tsc --noEmit` → EXIT=0(`npm run build` 里也带这一步,但单独跑更快)。
4. `npm run build`(= `tsc --noEmit` + `vite build`)→ 通过。
5. CDP(9333/9334/9335)打开该页真实状态(弹层、抽屉、筛选结果都要真打开),跑三段探针:
`audit16.js`(几何 / 溢出 / 野高度)、`audit19.js`(§7 G1~G3:`HINTLINE / SECT-DESC / LONG-PROSE /
ADD-ORPHAN / ICON-NOTITLE`)、`audit20.js`(§7 G4/G5:`ROW-TALL / ROW-SHORT / BTN-MISALIGN /
ADD-FLAT / DEL-FLAT / INLINE-COLOR`)。状态清单在 `mk16.py::STATES`,新增一类弹层 / 抽屉就在
那里加一条,`mkinv.py`(全量取证)与 `mkall.py`(双主题 + 浮层 + 用户位)自动带上;
**改过探针 JS 必须重新生成作业再跑**,否则跑的还是旧脚本。
6. 改了 `style.css` 的全站类(含 `--ctl-h*` 令牌、媒体查询)→ 必须双主题全量重跑
⚠️ React 迁移后这三段探针**只有几何部分可信**:`ROW-H / OFFX / CTL-H / OVERFLOW-X / CROWD-V /
LBL-CLIP / TINY-FONT / NATIVE-SELECT` 按标签和 `getComputedStyle` 判断,照常有效;
而 `BAR / CHIPBAR-GAP / BAR-GAP / STACK-WIDE` 靠 `.ctlbar/.chipbar/.fselect` 这些
**旧 DOM 类名**认容器,新代码里只剩 Tailwind 工具类,它们会**漏报而不是误报**。
别把「探针 0 项」当成合规证据——那几条要么改探针选择器,要么人工看一遍。
6. 改了 `styles/tokens.css` 的令牌或 `styles/base.css` 的元素基线(含 `--ctl-h*`、媒体查询)→ 必须双主题全量重跑
(深浅各 83 + 浮层 16 + 用户位 5 + 生成台 2 = 195 作业),不能只跑改动页。
**窄屏(430px)也在回归宽度里**:只在 ≤560px 生效的规则必须有证据,不能靠推理。
7. 结论进报告 `reports/UI审计与调整-2026-10-26.md` 对应章节:现象 → 根因 → 改法 → 逐项验收表。

View File

@ -72,7 +72,8 @@
与本会话结论:后端 227 passed / 1 skipped、前端 typecheck+build 干净、真机 API 27/27 + 11/11、浏览器验收 v20→v18→v20 往返后库已复原。
收尾清单:
1. ☐ **该仓库不是 git 仓库**(`list_projects` 里 `isGitRepository: false`),当前所有改动没有任何版本控制 —— 建议尽早 `git init` 并补 `.gitignore`(`nex_animation.db*`、`media/`、`.venv/`、`node_modules/`、`frontend/dist/`、`.local/`)
1. ☑ **该仓库不是 git 仓库**(`list_projects` 里 `isGitRepository: false`),当前所有改动没有任何版本控制 —— 建议尽早 `git init` 并补 `.gitignore`(`nex_animation.db*`、`media/`、`.venv/`、`node_modules/`、`frontend/dist/`、`.local/`)
(2026-11-01 前端迁移收尾时已 `git init` + 补 `.gitignore`,上面六项全部排除在外)
2. ☐ 后端跑在 screen `nexbackend`(8000,**无 --reload**),改后端代码必须重启;重启前查一遍 `tasks` 里有没有 queued/running
3. ☐ 遗留:后端 8000 只挂了 `/media`,没 SPA fallback,直接开 `http://127.0.0.1:8000/assets` 是 404(平时走 vite dev 5173)—— 要不要补,等用户点头

View File

@ -13,7 +13,7 @@
|---|---|---|
| `backend/app/` | 业务代码:`api/` 路由 · `services/` 领域逻辑 · `providers/` 模型适配 · `models/` 表定义 · `schemas/` 契约 | 一次性修数脚本、探针、临时数据 |
| `backend/tests/` | 全部自动化用例(契约、回归、真实模型 mock 演练) | 需要人手喂参数的调试脚本 |
| `frontend/src/` | Vue 3 源码 | 构建产物(`dist/` 是生成物,随时可删重出) |
| `frontend/src/` | React 19 + TypeScript 源码,分层见 §1.1 | 构建产物(`dist/` 是生成物,随时可删重出);页面私有的类名常量不该爬进 `components/` |
| `scripts/` | **只有四类**:启动、部署、运维、自检入口(见 §2) | 一次性脚本、验收残渣、临时 patch |
| `docs/` | 长期有效的设计/规范/方案文档 | 单次调试的日志粘贴 |
| `reports/` | 验收报告 `*.md`(结论 + 证据引用) | 报告本体之外的东西别混进来 |
@ -22,6 +22,37 @@
| `models/` | whisper.cpp 听写权重(可重新下载) | —— |
| `.trash/` | 待清理内容的唯一去处(见 §6) | —— |
### 1.1 `frontend/src` 分层与扩展点
前端从 Vue 换成 React + Tailwind 后,目录职责按「**依赖只允许自上而下**」执行:
```text
api/ → app/ → pages/ → components/{ui,forms,media}/ → hooks/ · lib/ → styles/
```
| 目录 | 放什么 | **不**放什么 |
|---|---|---|
| `api/` | 唯一的 `fetch` 出口(信封拆包、`detail`→`Error`、401 跳登录) | 业务分支、组件状态 |
| `app/` | 外壳:`router.tsx` 路由表 · `layout/` 顶栏侧栏鉴权闸门 · `nav.ts` 项目页签表 | 任何业务接口调用 |
| `pages/` | 一屏一文件;页面私有小组件与类名常量在文件底部 | 页面之间的互相 import |
| `components/ui/` | 版式与控件原语(`Button` `Field` `Ctlbar` `Table` `Modal` `Drawer` `Tag` `Pager`…) | 业务字段名、接口路径 |
| `components/forms/` | 选择器族(`Select` `MultiSelect` `SecretInput` + `toOptions`) | 页面专属选项 |
| `components/media/` | 带全局状态的媒体件(`MediaThumb` `AudioPlay` `MediaLightbox` `VersionPanel` `WorkflowBar`) | 纯展示(那些进 `ui/`) |
| `stores/` | zustand 切片(auth · theme · notice · project · models · system · audio · preview)+ 少量全站静态字典 | 组件本地 state |
| `hooks/` `lib/` | 可复用的 effect 与纯函数 | 带 JSX 的东西(那是 `components/`) |
| `styles/` | `tokens.css` 设计令牌(唯一尺子来源)· `base.css` 元素基线 | 页面级样式 |
**扩展点(改表不改逻辑,全部已落地验证)**:
| 想做的事 | 改哪儿 | 为什么不用改逻辑 |
|---|---|---|
| 加一类平台母版 | `pages/AssetLibrary.tsx:TYPE_META` 加一项 | 左栏、卡片、抽屉标题、生成台全部从这张表取标签/图标/提示 |
| 加一个项目页签 | `app/layout/nav.ts` 加一行 + `app/router.tsx` 加子路由(带 `handle` 标题) | 侧栏与文档标题分别由这两处派生,无需注册第三处 |
| 改某页每页条数档位 | `Pager` 的 `sizes`(页面里传 `PAGE_SIZES`,`0` = 全部) | 默认档位和「全部」语义在 `Controls.tsx` 一处实现 |
| 抽屉想要别的宽度 | `Drawer` 的 `width` 收一个 Tailwind 宽度类 | 默认值只在 `Overlay.tsx` 写一次,页面按屏宽传变体 |
| 新增弹窗/表单 | `Modal` `Drawer` `Field` `FormRow` 组合 | 高度、间距、页脚按钮排布由原语和容器 `--ctl-h` 档位兜住 |
| 控件档外的高度 | 容器上写 `[--ctl-h:var(--ctl-h-md)]` | 控件一律 `h-(--ctl-h)`,禁止单个控件写死像素 |
**根目录只允许**:`README.md`、`docker-compose.yml`、`.env`、`.env.example`、`.gitignore`
和上面这些目录。历史上漂在根上的 `.schema shots`、`backend/nex_animation.db`(0 字节空库)
之类的东西全部来自「在错误的目录里启动服务」,路径锚定修好之后不再产生。
@ -88,7 +119,13 @@
文案,而不是 `ValueError: bad input`。
- **相对路径必须锚定仓库根**(`app/config.py:get_settings`):media、SQLite、
`models/asr/*.bin` 都是相对路径,不锚定就会出现「换个目录启动,历史镜头全 404」。
- Python 3.11+(用了 `X | None` 语法);前端 Vue 3 + `<script setup>` + TS。
- Python 3.11+(用了 `X | None` 语法);前端 React 19 函数组件 + TS 严格模式
(`tsconfig` 开了 `noUnusedLocals`:留个没用过的变量就算脏,`npm run build` 直接失败)。
- **前端只有 Tailwind 一种样式语言**:尺寸/颜色一律走 `styles/tokens.css` 的令牌
(`text-ui` `rounded-control` `bg-sunken` `border-line-strong`…),页面里不写 `style=`、
不建 `.css`、不写 `@media`——窄屏行为用断点变体(`max-mid:` `max-narrow:` `max-short:`)写在类上。
- **一页一文件**,页面专属的类名常量与两行就够的小组件留在页面文件底部,
被第二个页面用到才提进 `components/`;反向也要提,别让两个页面各养一份皮肤。
## 5. 部署:数据边界与流程
@ -163,9 +200,9 @@ sudo ./scripts/server.sh systemd > /etc/systemd/system/nex-animation.service #
**回滚**:部署包不解覆盖式删除远端文件(不加 `--delete`),`.env` 与 `media/` 原地保留,
把 `.env` 指回旧目录即可回退。
## 6. 删除策略(无 git 历史时的保命约定)
## 6. 删除策略(git 捞不回来的那部分)
本目录当前**不是 git 仓库**,删掉就没有第二次机会,所以:
`.trash/` 与 `.local/` 都在 `.gitignore` 里,被删的内容**多半是未跟踪的运行时数据**(媒体、日志、验收证据),git 捞不回来,所以:
1. 一律 `mv` 到 `.trash/YYYY-MM-DD/<分类>/`,**禁止 `rm -rf`**。
2. 同名冲突时换目标名,不要图省事直接覆盖(本轮就有两个 `.DS_Store` 因 `mv -n` 撞名而漏清)。