Commit Graph

20 Commits (main)

Author SHA1 Message Date
mula.liu 3e94a79b89 docs(规范): 阶段 9–45 口径入册(含 §13.14 执行过程那条)+ 台账 E11 与落地追记
三份规范与 `nex.config.yaml` 必须和这一批代码同时落地,否则「文档与实现冲突」
的账会留给下一轮。

- `docs/UI规范.md`:§2 表/§5.1.2.1(32 档只属于页头与工具条独立动作,卡片内动作
  归位)/§12 与 §12.2/§12.3/§13.14(新增:折叠行本身就是可点的语义元素,
  同动作的文字胶囊是第二入口,总控台「展开/收拢执行过程」那颗去掉)/§15.1 与
  §15.14(12 族族账、`projectswitchcheck` 默认落盘口径)同步。
- `docs/NEX-对照与例外.md`:登记 E11(环节资产页不渲染 `Pager`、命中数住 `<BarRight>`
  的理由与证据位置),§7 变更记录补阶段 37–44 各行,末了加一条 2026-11-12 的落地
  追记——把本轮之前所有报告里「HEAD 仍是 `418fb6b`」「未 commit」那类句子统一改口径,
  并写清两条待办:本地未 push、`nex_design_system` 子仓库指针未 push。
- `docs/工程规范.md`:脚本准入与探针清单跟着第 14 道更新。
- `AGENTS.md`:常驻探针 13 道 → 14 道两处。
- `nex.config.yaml`:`icons` 一栏改为两级表的真实形状(core 54 只/extra 24 只/
  index 是桶/`_kit.ts` 不含图形,边界由 `classaudit` 附三守);`board` 断点注释改为
  实测的「看板卡宽地板 320→288(auto-fill,minmax)」;`ui_gates` 与 `verification`
  两条改为 12 族族账的实际读数口径。**改了尺子就要同步它**,这一条是项目级硬要求。
- `README.md`:补第 14 道探针那一行、初始口令改 `admin@123`、`seed.py install
  --reset-password` 的保守口径说明。

表格自检:`/usr/bin/python3 reports/ui_evidence/nex-p37/mdtablecheck.py docs/*.md
reports/*.md` → 文件=50、不符行=0(顺手把阶段 45 报告里代码段内那个裸 `|` 转义掉,
`新建项目|111x32` → `新建项目\|111x32`,GFM 表格里的 code span 同样要转义)。
2026-11-12 10:21:58 +08:00
mula.liu b504e31628 前端四项调整:输入框去掉光晕、账号菜单收口、逐页删开发期说明书、登录页重做成左右分栏
用户这一轮提了四条,其中三条是同一件事的三个面——**界面上残留着写给开发者自己的话**。
逐条落地的口径与取舍:

**1)所有输入框聚焦时的蓝色外框**
量出来其实是三层叠在一起:antd 组件 token 的 `activeShadow`(2px 主色光晕)、
`genFocusStyle` 画的 `outline`、站内 `app.css` 给自绘表面准备的全站 `:focus-visible` 兜底。
第二层没有独立 token,而它依赖的 `lineWidthFocus` 还被 Upload 拖拽区复用,动 token 会连带改上传框,
所以分两刀收:`theme/antd.ts` 关 token(`Input`/`InputNumber` 的 `activeShadow` = `none`、
`Select.activeOutlineColor` = `transparent`),`styles/app.css` 用
`:where(...):focus-visible { outline: none }` 关那圈 outline——用 `:where()` 是为了把特异度归零,
它只是一份选择器清单而不是新加一层优先级,将来谁要恢复焦点环不必先赢过一条 `!important`
(app.css 本身不在 `@layer` 里,压得住被 Tailwind 放进 `@layer antd` 的那份,本来就不需要 `!important`)。
**焦点指示没有被删**:antd 的 `activeBorderColor` + 加粗边框仍在,键盘用户看得见焦点;
自绘表面继续吃全站那条兜底。实测聚焦 `#login-user`:`box-shadow: none`、`outline: none 3px`、
`border-color` 浅 rgb(22,119,255) / 深 rgb(22,104,220)。

**2)账号胶囊:菜单去重、项上不留副标题**
「设置新密码」和「我的账号」是同一件事,且首启时登录页已经直接把人的带到 `/account?must=1`,
重复排队只让菜单变长——删掉,待办语义留着头像上的 Badge 红点。
菜单项不再写「账号信息 · 密码 · 登录设备」这类预演式说明;顺手把胶囊第二行的
`第 N 次登录` 也去了:那是「用户管理」表格里逐人登记的数据,挂在人人都要看的顶栏里等于把统计搬进导航。
现在菜单就是三项:我的账号 / 用户管理 / 退出登录。

**3)逐页去开发时冗余说明**(`Dashboard` / `AssetLibrary` / `ModelCenter` / `AgentConsole` /
`project/{Library,Overview,Storyboard,Timeline,Review,Delivery}` / `ProjectBriefDrawer`)
三类处置,已写进 UI规范 §14 G2:
- 常驻说明书删掉可见文字,信息进 `title`/`desc`:IndexTTS2 那四行论文式介绍(两处重复,
  含「下面这条预告会说清楚:」)、总控台「期间页面不会推进,属正常现象」;
- 开发者口径翻成「会怎样」:ffmpeg libass 提示只留降级后果,`FFMPEG_BIN` / `brew install ffmpeg-full` /
  当前探测路径收进 `title`;`Delivery` 卡头「媒体由后端 `/media` 直出,下载走 `/api/exports/:id/download`」整条删;
  「每一站的汇总状态由它覆盖的那几个节点折算而来」→「点一行直接跳到对应环节」;
- 内部词不许漏到版面:`mock/Mock` → 站内既有的**演练通道**(四处)、「未匹配的列在 `unmatched_images`」
  → 翻成人话;**一个物件只有一个名字**,`/models` 曾同时叫「模型中心 / 模型控制台 / 调度中心 → 模型中心」,
  全站统一成侧栏那一项的写法 **模型管理中心**(含 `.env` 注释、`dev.sh`/`server.sh`/`seed.py` 的引导语、
  后端四条给用户的报错文案、README、docs、探针页面名),并修掉不存在的入口路径「调度中心 → 模型中心」。
有意保留:单位与取值口径的括号(`(秒)(毫秒)(可选)(0=自动)(dB)`——读数不该依赖悬停)、
条件出现的 `Notice`/`LineHint`/`ErrorText`、`confirmAction` 的 `desc`、`Stat hint`、`nav.hint`、
`PageHead sub`(kit 既定槽位的一句话职责说明)、`Help.tsx` 整页(登记在册的产品手册)。
配套给 `OptionGrid` 单开 `labelTitle`,让组标签的括号补充有地方去而不额外占一行。

**4)登录页重做**(UI规范新增 §13.4)
左右分栏:左栏 `w-[46%] max-w-[620px]` 写平台自述(品牌行 →「把一条长视频,做成一条流水线」+
三条能力点 → 角色可见范围),底色用 `color-mix` 把主色掺进 `color-bg-layout`,**零新 hex**;
右栏卡片保留原生 `<form>` 包在 `<Panel>` 外(Enter 提交与密码自动填充都挂在 form 上)。
窄于 `lg` 左栏整列收起,品牌行回到卡片顶部,任何宽度都认得出登的是哪个系统。
去掉后端下发的种子账号预填(`login_hint` 字段本身保留,`test_auth.py` 与 `e2e_selfcheck.py` 还在用它判首启),
placeholder 回到「用户名」「密码」;新增**记住我**:键 `nex-login`,账号+口令一起记一起清
(只清口令留账号的话勾选框就不算数了),只在登录成功后落盘,取消勾选当场 `writeLocal(key, null)`,
默认不勾(本机明文口令)。

文档同步:UI规范 §8.4(`labelTitle`)、§9.3(焦点轮廓三层口径)、§13.4(登录页)、
§14 G2(三类处置 + 一个物件一个名字)与 §14 例外登记(登录页左栏、`Help.tsx` 整页豁免);
README 鉴权一节补登录页与记住我;命名统一顺带扫了 `.env.example` / 三个脚本 / 后端文案。

验证:`npx tsc --noEmit`、`npm run build` 全绿;`node scripts/ui/classaudit.mjs` 七道闸门 0/0/0/0/0/0/0;
后端 + 前端起在 :8010/:5199 后跑完 §15 全部探针,退出码全 0——visualcheck 1440×明暗 15 路由
(console 0 / HTTP 失败 0 / 断言 0)、tableaudit 0、gridcheck 0、rhythmcheck 0、tagcheck 0/0、
btnrowcheck 0(413 组)、aligncheck 0、symmetrycheck 0、feedbackcheck 通过、footercheck 0(30 处吸底条)、
btnclustercheck 0(159 簇);gateprobe 11/11 反向验证;`pytest -q` 全量 502 passed 1 skipped
(后端改了四条用户可见文案,对应 3 处断言同步更新)。记住我三条路径(勾上存 / 不勾清空 / 取消即清)实测过。
2026-11-05 22:09:16 +08:00
mula.liu 27f3656d6b 依赖下载点全部配国内源,并修掉「镜像里没有中文字体」这个字幕坑
用户诉求是「镜像已有,其它依赖考虑国内加速」。先把全链路的外部下载点摸了一遍,
结论:**构建镜像不需要 huggingface**——唯一的 HF 地址在 scripts/server.sh,
只在裸机 install 的 fetch_asr_model() 里用到,而且容器里根本没有 whisper-cli,
那条 curl 在 Docker 路径下永远不会执行;requirements.txt 只有 8 个包(没有任何
whisper/hub 依赖),models/ 也被 .dockerignore 排掉。构建期真正的下载点只有
npm / apt / pip 三个,此前 npm 与 pip 已是国内源,只有 apt 还默认 deb.debian.org
(实测这一层要 200+ 秒,清华 0.24 秒拿到 Release)。

改动:
- Dockerfile:APT_MIRROR 默认改清华(境外显式传回 deb.debian.org);apt 清单
  ffmpeg → ffmpeg fontconfig fonts-noto-cjk。后两个是真 bug 修复——slim +
  --no-install-recommends 连 DejaVu 都不带,libass 找不到中文字形**不报错**,
  直接把烧的字幕画成一片豆腐块;services/ffmpeg.py 又要靠 fc-list/fc-scan
  按 charset 反查字体,所以 fontconfig 也一并装上。装完代码零改动:
  _FONT_FILE_CANDIDATES 里已写着 fonts-noto-cjk 的落盘路径。嫌 +120MB 可换
  fonts-wqy-microhei(+10MB)。
- server.sh / dev.sh:新增 PIP_INDEX_URL / NPM_REGISTRY / ASR_DOWNLOAD_URL 三组
  可覆盖变量,优先级 环境变量 > .env > 内置默认,键名与 Dockerfile 的 --build-arg
  完全一致(容器和裸机同一套口径);pip 一律带 -i、npm 一律带 --registry;
  ASR 权重默认走 hf-mirror(huggingface.co 国内实测 0.04s 直接连接重置)。
- server.sh install 新增中文字体探测:复用 app.services.ffmpeg.cjk_font_catalog(),
  查不到就 warn,别等出片了才发现字幕是方块。
- 四处默认值对齐(Dockerfile / docker-compose.yml / server.sh / dev.sh)。
- README §3.2 新增「依赖下载点与国内源」表:五个下载点各自发生在什么时候、
  用哪个键、默认值是什么,并点明浏览器侧 Google Fonts 是最后一处外部依赖
  (只影响访问者,要彻底离线需自托管);工程规范 §5 补一条「依赖源只有一套键、
  默认即国内,判据是新机器零配置能装起来」。

验证:bash -n 两个脚本通过;字体探针正反向都跑过(本机 49 个中文字体 → exit 0);
docker compose config 服务仍只有 app、args 渲染出新默认值;deploy.sh --check 19 项全绿;
pytest -k "ffmpeg or subtitle or font or asr or speech or quality" 35 passed 1 skipped
(未改后端代码,故未跑全量)。docker build 本机验证不了(Docker daemon 没起),
需在服务器上构建确认。
2026-11-05 19:36:32 +08:00
mula.liu 1a886beca6 端口按形态分键:HOST_PORT 只管部署对外,BACKEND_PORT/FRONTEND_PORT 只管开发;.env.example 与 compose 去噪音
一、端口三个键,各管一种形态,键名自带场景
上一轮我把它收敛成单一的 PORT,方向收得太狠:一个键被三种形态共用,等于把「这是给谁看的」
又塞回 README 里——同一个 HOST_PORT 在 Docker 下指对外映射、在裸机下指监听、在开发下指后端,
不翻文档的人分不出来。按形态分回去,判据从来不是键的个数,而是含义的唯一性:
一个键只能有一种含义、同一个 socket 不能有两个键。

  HOST_PORT      部署形态对外暴露的端口:compose 拿它插值做端口映射,server.sh 回读它做监听端口
  BACKEND_PORT   开发形态的后端 uvicorn(dev.sh 回读,并同步 Vite 代理目标)
  FRONTEND_PORT  开发形态的前端 Vite(独立进程,必须与后端错开)

compose 的 ports 回到 "${HOST_PORT:-8000}:8000",并删掉上一轮为兼容 PORT 加的 environment.PORT="8000"
钉子(键名分开之后没有歧义要钉了)。server.sh 的取值链改成
命令行 --port > 环境变量 HOST_PORT/PORT > .env 的 HOST_PORT > 8000,
旧键 PORT 留一版兼容;dev.sh 只认 BACKEND_PORT/FRONTEND_PORT(PORT 作旧键回退)。
实测:.env 写 HOST_PORT=8010 → compose published=8010、server.sh status 打 :8010;
HOST_PORT=9301 环境变量覆盖 → :9301;BACKEND_PORT=8000/FRONTEND_PORT=5173 → dev.sh 两个进程端口正确。

二、.env.example 按 .env 的样式重写,噪音清掉
它是运维唯一被要求编辑的文件,之前 100 行里 65 行是注释与说明,还有一批在 Docker 形态下
根本没人读的键。现在 32 个生效键 / 11 行注释,键位与本机 .env 一一对应,只放配置本身:
- 删掉 compose 覆盖掉的那几行的误导(SERVE_FRONTEND 不再列;DATABASE_URL/MEDIA_ROOT 只留一行说明
  「Docker 形态 compose 会指到挂载点」),长篇「为什么不在这里」全部搬到 README §3 与工程规范 §5,
  .env 头部三行指路。
- 删掉只在叠加 scale.yml 时才有人读的 POSTGRES_*/REDIS_URL/CELERY_*(默认值写在 scale.yml 里)。
- 删掉与代码默认值同值的长尾键(上传白名单、COOKIE_NAME、FRONTEND_DIST_DIR、QC 细项等),
  需要的人按 Settings 字段名加一行即可(文件头写明键名 = 字段大写下划线)。
- 默认值改成单容器真相:SQLite + inline,不再是 postgresql+…@db:5432 + celery。
本机 .env 同步精简成 11 键 / 8 行注释,并把容器对外端口定成 HOST_PORT=8010(8000 坐着开发后端)。

三、docker-compose.yml 114 行 → 77 行
头部 34 行的架构论证压成 16 行只留「常用命令 + 配置来源 + 四个挂载点 + 指路 README」,
正文注释每条最多一行;为什么单容器、模型配置为什么不在这份文件里、扩容层怎么叠,
都指向 README §3.2 / §4.0。顺手把上一轮的教训留住:改 .env 之后必须重跑 up -d,
restart 沿用旧容器配置、不换端口映射,这条写进了命令清单。
env_value() 补上「去随行注释与尾部空白」:三种解析器(python-dotenv、compose env_file、
本仓的 sed 回读)里只有前者会剥行内注释,漏了它 server.sh 会把
「HOST_PORT=8010  # 本机跑容器…」整串当端口用。

四、文档同步:README §3.2 加端口三键表与「改了没反应的四个键」,§3.1 前端代理、§3.2 命令、
常用改动表、§3.4 server.sh 注释全部改口径;docs/工程规范.md §5 把规则从「端口只有一个键」
改写成「按形态分键 + 含义唯一」,并把两次反复的教训写进正文。

验证:bash -n 两个脚本通过;docker compose config --services 仍只有 app,published 随 HOST_PORT 变化,
容器内四个覆盖值仍是挂载点那套;deploy.sh --check 全绿(19 项入口齐全);
两份 env 0 未知键 0 模型键;backend 全量 502 passed / 1 skipped。
2026-11-05 19:01:32 +08:00
mula.liu 24978e9843 把「服务器上那份 .env 到底管什么」写死:模板默认改成单容器真相,compose 覆盖的键逐条点名
部署前必问的三个问题,答案以前都藏在别的文件里,这次直接写进 .env.example 与 README §3.2。

一、.env 不是「开发用的那份」,是「每台机器一份的那份」
它 gitignored、不在部署包里(deploy.sh 的「不随包走」清单里就有它),仓库根这份是开发机的
(SQLite、Vite 端口、本机口令),服务器上那份由 cp .env.example .env 生成,两份互不影响。
之前 .env.example 头部没交代这件事,于是「根目录 .env 是配置开发的?那服务器上改哪」这个问题
只能靠人脑补答案。补上四行说明。

二、对外端口配在哪:服务器那份 .env 的 PORT 一行,不在 compose 里
compose 只是引用它(ports: "${PORT:-${HOST_PORT:-8000}}:8000"),读 .env 读两遍:
先替 ${PORT} 插值得到端口映射,再整份注入容器当环境变量。
顺手填掉一个真坑:compose 的 environment 覆盖 DATABASE_URL / MEDIA_ROOT / SERVE_FRONTEND /
TASK_EXECUTOR / 容器内 PORT 这五个键,运维在 .env 里改前四个是**完全没反应**的——
这正是本仓最忌讳的「写了不生效」,而 .env.example 作为模板恰恰把它们写成生效态。
现在逐个点名:前四个标注「Docker 形态被 APP_* 覆盖」,容器内落点改 APP_DATABASE_URL /
APP_MEDIA_ROOT 那两行。

三、.env.example 的默认值改成单容器形态(原来那套会让人以为在用 Postgres)
模板里原先是 DATABASE_URL=postgresql+…@db:5432、TASK_EXECUTOR=celery、SERVE_FRONTEND=off、
POSTGRES_*/REDIS_URL 全生效,而 §3.2 又让你 cp 它去部署 Docker——照做之后文件说「Postgres +
Celery + 不托管前端」,实际跑的是「SQLite + inline + 托管前端」,读文件的人被指错方向。
现在默认 SQLite / inline / on(与 compose 强制的那套一致),Postgres/Redis/Celery 七个键
整段注释掉并注明「只在 -f docker-compose.scale.yml 时生效」。生效键从 45 降到 40:
留下的每一个都有读取方。
连带修掉 README §3.4 那句「模板里那套是 Postgres + Celery,cp 会起不来」——现在 cp 也能起来,
两条路径等价,这个矛盾说法本身就成了误导。

四、compose 里的 comfyui 服务:默认不参与,README 说明白
它带 profiles: ["comfy"],docker compose config --services 只有 app,不 --profile comfy 就
不会起,GPU 预留也不生效。算力在远端(模型中心里那三条 base_url)时它就是死代码,
只是给「算力恰好装在本机、想用容器跑一份 ComfyUI」留的开关。§3.2 与常用改动表各补一句。

验证:docker compose config --services 仍只有 app,published 仍随 PORT 变化,
容器内 DATABASE_URL/MEDIA_ROOT/SERVE_FRONTEND/TASK_EXECUTOR 仍是挂载点内那套;
deploy.sh --check 全绿(215 文件/7.5M,数据包 8 条模型配置体检通过);
两份 env 0 未知键 0 模型键;backend 全量 502 passed / 1 skipped。
2026-11-05 18:52:45 +08:00
mula.liu 1934fb8bcc 端口收成一个键 PORT,.env 里的模型说明清零,apt 源也能换
一、端口:HOST_PORT / PORT / BACKEND_PORT 三个键砍成一个

上一轮把端口小节加回 .env.example 时,我按「三种部署形态」列了三个键:
Docker 用 HOST_PORT、裸机 server.sh 用 PORT、开发 dev.sh 用 BACKEND_PORT+FRONTEND_PORT。
听起来各管一摊,实际上它们指的是同一件事——「这个应用对外听在哪个端口」。
一份要交给运维编辑的文件里出现三个同义键,他的第一反应必然是「我该改哪个」,
而改错那个的表现还是「服务起来了但端口没变」,跟没改一样。所以这次收到一个:

  PORT = 应用对外端口。Docker 对外的映射读它、裸机 server.sh 的监听端口读它、
         开发态的后端也读它。

- docker-compose.yml:ports 改成 "${PORT:-${HOST_PORT:-8000}}:8000",旧键留一版回退;
  另外在 environment 里显式写死 PORT: "8000",因为容器内永远监听 8000
  (EXPOSE 与健康检查都按 8000 写死),宿主 .env 注进来的那份不能让它漂——
  今天应用不读 PORT 没事,将来谁加一行 os.environ["PORT"] 就会变成
  「映射 9000:8000 但进程监听 9000」,容器直接不通。
- server.sh / dev.sh:加 env_value() 回读仓库根 .env(上一轮删掉过,是倒退)。
  取值优先级统一 命令行 > 环境变量 > .env > 默认值;旧键 HOST_PORT / BACKEND_PORT
  只作兼容回退。回读 .env 是有意的:.env 是运维唯一被要求编辑的文件,
  写进去的键必须真的生效,否则就是本仓最忌讳的「写了不生效」。
- 开发态仍保留 FRONTEND_PORT,这不是同义键:Vite 是独立进程,必须和后端错开端口。
- 实测:.env 写 PORT=8211 → server.sh status 打印 server :8211、dev.sh status 打印
  backend :8211;PORT=9000 docker compose config 的 published 变 9000 而容器内
  PORT 仍是 8000;HOST_PORT=9100(.env 无 PORT 时)仍能回退到 9100。

二、.env / .env.example:只留配置本身

模型相关的配置和说明全部删净——现在两份文件里 VIDEO_* / COMFYUI_* / TTS_* / IMAGE_* / LLM_*
一个键都没有,原先三段「模型配置为什么不在这里」的长说明压成头部两行指引
(去页面「调度中心 → 模型中心」改,服务器初值随 scripts/seed/ 导入)。
.env.example 55 行注释对 45 个生效键,每条最多两行;本机 .env 10 键 10 行注释。
顺带确认:本机 .env 没被删过,它是 gitignored 的,所以从来不出现在提交里。
APP_DATABASE_URL / APP_MEDIA_ROOT 归到 Docker 小节(它们只在容器里成立)。
键名逐个对过 Settings 字段:两份文件 0 个未知键(多余键本身会被 extra="ignore" 吞掉,
但写错字得能立刻看出来)。

三、ffmpeg:镜像里装了,而且源现在可换

回答提问:装了。Dockerfile 运行阶段(python:3.12-slim 没有 ffmpeg)apt 装它,
时间线合成、抽帧、时长/码率质检全调它(app/services/ffmpeg.py);
缺它的表现是「导出成片一路 500」而不是起不来,所以没做成可选层。
实测容器 /health 报 ffmpeg=true(/usr/bin/ffmpeg 5.1.9-0+deb12u1,
libass/xfade/subtitles/loudnorm 全 true)。
但这一段以前是唯一没做国内镜像的装包层,README 却写着「三段都走公网镜像源」——
名不副实,且上次该层在构建机上跑了约 221 s。补上 ARG APT_MIRROR(默认 deb.debian.org,
不传参等于原行为),bookworm 的 /debian 与 /debian-security 同在 deb.debian.org 下,
一次 sed 覆盖 deb822 与老式 sources.list 两种文件;compose 侧透出同名 build-arg。

四、文档同步:README §3.2 端口行与构建源行、§3.4、前端代理那条;
docs/工程规范.md §5 补「一件事只有一个键」,并把三键同义列为回归。

backend/tests 全量 502 passed / 1 skipped;bash -n 两个脚本通过;
docker compose config 只有一个服务 app,端口映射与 APT_MIRROR 注入均已核对。
2026-11-05 18:44:30 +08:00
mula.liu 890f1ee589 模型配置全部交给数据库,.env 只管进程参数;media 从库里搬出来单独一个挂载点
上一版把容器收成一个之后,剩下的口径不一致是「模型配在哪」有两处说法:
.env 里能写 COMFYUI_BASE_URL / VIDEO_PROVIDER / TTS_*,模型中心页面也能改,
而运行时 config_json 优先——于是"改了没生效"和"到底哪条说了算"变成日常问题。
搬家的判据写成一句话放进工程规范:**换模型要不要重启进程**。要,就说明它站错了队。
另外三条理由:① 换 GPU 机是日常操作,不该要求改 .env 再 up --force-recreate;
② API / worker / beat 三个进程必须读同一份模型事实,写 .env 就是三份;
③ 地址与 Key 进库才有审计(谁改的、什么时候)与探测记录。
media 分家是同一批的诉求:产物只涨不跌,会长到几十上百 GB,迟早要单独挪大盘、
做增量备份、被 rsync 与剪辑软件直接读,和"一个不能写坏的 SQLite"绑在同一个挂载点
就得整目录停服拷走。代价说清楚:备份清单从一条变两条。

改动
   · 划界:.env / .env.example 里 VIDEO_* / COMFYUI_* / TTS_* 一律清零(脚本核对过,
     43 个键全部对应 Settings 字段或 compose 插值键,无未知键、无模型键),模板头部
     写明"为什么这里没有模型配置"与新的排障口径(先去页面点 🔌 探测)。补回四个
     原本漏在模板外的进程参数 FFMPEG_BIN/FFPROBE_BIN/QC_VISUAL_*/QC_ASR_ENABLED。
   · Dockerfile / docker-compose.yml / docker-compose.scale.yml:MEDIA_ROOT 从
     /app/data/media 改成 /app/media 并新增 ./media 挂载;worker 同步挂两个目录
     (否则「worker 写完了页面看不到」),beat 不读写产物所以不挂;compose 里删掉
     COMFYUI_BASE_URL 透传,注释说明"去模型中心改 base_url,改完即生效"。
   · 后端三处悄悄降级要一起清掉,否则 env 一空就把真实默认位打回 Mock:
     api/system.py 不再用 settings.video_provider/tts_provider 覆盖页面默认位;
     services/audio.py 的 resolve_tts_spec 候选去掉 settings.tts_provider(未设供应商的
     声线会静默 Mock 配音,只有听成片才发现);providers/registry.py 的 _dedupe_defaults
     改按「真实模型 > 启用 > 登记顺序」裁决,两条 mock 行的 is_default 交给
     _has_real_spec 闸门而不是 env。config.py 的模型字段保留为代码级兜底并写明两个用处。
   · 两个启停脚本原来都是 curl .env 里的 COMFYUI_BASE_URL 探活——现在探的是废弃地址,
     绿字反而误导:dev.sh / server.sh 的 status 改成登录取 /api/providers,
     把库里在册且启用的 base_url 去重后逐个探(comfy 探 /system_stats)。
     dev.sh 顺带修两处历史问题:/api/providers 在 AUTH_ENABLED=true 下 401 被打印成
     "模型注册表读取失败"(现在先登录);非 2xx 被 urllib 当异常抛,LLM 根路径 404
     会误判 unreachable(有 HTTP 应答即算机器活着,真可用性以页面探测为准)。env_value
     随之无人引用,两个脚本各删一份。
   · 文档:README §3.2 挂载表 3 行→4 行(含"少挂 media 会怎样")+ 备份清单两条、
     「常用改动」表把 ComfyUI 一行改成页面操作、§4.0 重写(事实源 + 三条理由 +
     三种接入路径 + COMFYUI_BASE_URL 逃生门 + 排障顺序);工程规范 §5 加"配置分两层"、
     硬约束 #3 与数据边界表同步;deploy.sh / dev.sh 提示语同步。

验证(真跑)
   · 全量后端用例 502 passed / 1 skipped;conftest 新增钉住 COMFYUI_BASE_URL,
     否则 comfyui 三条不登记,断言会跟着开发机 .env 漂(这正是删完 .env 才暴露的隐性污染)。
   · HOST_PORT=8010 docker compose up -d --build → 12 秒 healthy;容器里没有任何模型 env,
     /api/providers 仍是 8 条、默认位四条全真(comfyui/minimax-h3 · qwen-image-2.1-turbo ·
     indextts2 · qwen/qwen3.7-plus),默认位是 entrypoint 从 ./scripts/seed 灌进去的。
   · media 挂载双向实测:容器内写 /app/media/_mount_probe.txt → 宿主 media/ 立即可见;
     宿主已有 1.8G 产物经容器读回 200(/media/1/generated/shot-02-task2.mp4 2.8MB video/mp4);
     走真实接口 POST /api/projects/1/assets 上传,落盘 media/1/reference/*.png 并能在页面直出。
   · ./scripts/deploy.sh --check 19 项全绿;seed.py doctor/boundary 通过;
     dev.sh status 与 server.sh status 均正确报出 http://10.100.53.199:9200 reachable、
     dashscope 报 HTTP 404(有应答)。冒烟产生的 media 两个探针文件与 ./data 移入
     .trash/2026-11-05/smoke-media-mount/,宿主库与产物未留垃圾。
2026-11-05 18:18:00 +08:00
mula.liu 517720cf62 打成 Docker 只留一个容器:前端产物与后端同进程同端口,Postgres/Redis/Celery 收成可选扩容层
compose 原本是六个容器(db/redis/api/worker/beat/web),那是「前后端分离 + 独立 broker」
时代的遗产。这个项目实际跑的是 SQLite + TASK_EXECUTOR=inline(进程内线程池,周期派发交给
app/services/daemon.py 的守护线程),前端产物由 SERVE_FRONTEND=on 让后端一并托管——
就是 scripts/server.sh 在裸机上跑的那套形态。多出来的三个组件在这里只增加故障面:
连不上的 db、没人消费的 broker、「api 起来了 worker 没起所以任务永远 pending」。

新增
   · Dockerfile:两段式。node 阶段 npm ci && npm run build(tsc --noEmit 不过就地失败,
     比在服务器上炸便宜);运行阶段 python:3.12-slim + apt ffmpeg(时间线合成/抽帧/质检的
     硬依赖,缺它的表现是「导出成片一路 500」而不是起不来)。镜像内保持仓库布局
     backend/ + scripts/ + frontend/dist:app/config.py 与 scripts/seed.py 都靠 parents[N]
     反推根目录,布局一改就是「.env 找不到」「数据集看不见」两类静默失灵。
     BASE_IMAGE/NODE_IMAGE/PIP_INDEX_URL/NPM_REGISTRY 全部可 --build-arg 覆盖。
   · .dockerignore:刻意排除 scripts/seed —— 加密主密钥不能烘进镜像层,谁拉镜像谁拿到它。
   · scripts/docker-entrypoint.sh:首启把挂载进来的部署数据包灌进库(AUTO_SEED=
     only-missing|force|off),灌失败只告警不拦启动(缺的只是几条模型配置,页面和 API 是好的);
     末尾 exec 让 uvicorn 当 PID 1,docker stop 的 SIGTERM 才传得进去。根目录从脚本自身位置
     反推而不是写死 /app:写死会让「数据集存在与否」的判断在换目录时静默变成 False。
   · docker-compose.scale.yml:真要多机/多 GPU 才叠这层切回 Postgres + Redis + worker + beat,
     页面仍由 app 这一个容器提供(SERVE_FRONTEND 没被动过)。

改动
   · docker-compose.yml 重写成单 service:对外只有 HOST_PORT 一个端口(容器内固定 8000,
     与 EXPOSE/HEALTHCHECK 对齐),数据三处 bind mount——./data(库+media)、
     ./scripts/seed:ro(机密)、./models:ro;comfyui 降级成 profile。
   · seed.py install 的「目标库已有业务数据」两档模式分开报:覆盖式保持黄色告警,
     --only-missing 一行都不动已有数据,而容器每次重启都会走到这里——跑了几天的服务器上
     必然有 event_logs,每次都黄一条等于训练运维无视黄条,降级成一行普通提示。
   · deploy.sh 必带清单加四个 Docker 文件(现 19 项)、包内排除新增的 /data/;
     server.sh 注释里的 docker-compose 指向改成 scale 层;.env.example 新增「Docker 部署」一节;
     README §3.2 整段重写(含挂载表、AUTO_SEED 三档、扩容叠加、国内 registry 实测命令)、
     §3.4 补「同一份部署包也能直接跑 docker」;工程规范 §1 根目录白名单与 §2 脚本表同步。

验证(真跑,不是纸面推演)
   · docker compose config --services = app(默认一个);叠 scale 层 = db redis beat worker app。
   · docker build 成功(685MB,本机直连不到 docker.io,改用 swr 镜像源的
     python:3.12-slim + node:22-alpine 走通,npm ci 34.8s / vite build 12.7s / ffmpeg 221s)。
   · HOST_PORT=8010 docker compose up -d 12 秒到 healthy;首启日志「模型配置:新增 8」
     「前端产物已托管:/app/frontend/dist」「执行后端=inline ffmpeg=True」。
   · / 与 /projects/3/storyboard 回落同一 index.html;/assets/index-*.js 200/216KB;
     /api/nope 是 401 JSON 而不是被 SPA 兜底成 HTML;登录后 /api/providers 返回 8 条配置 +
     四个默认位;/app/scripts/seed 确认 Read-only file system。
   · 把 tts 默认位手工改成 mock 后 restart:日志「保留本机默认位不改」,重启后仍是 mock;
     AUTO_SEED=force 时按包覆盖回 comfyui/indextts2。celery 入口与 AUTO_SEED=off 都不灌数据。
   · 优雅停止:SIGTERM 后 0s 走完「Shutting down → 内联调度守护线程已停止 → shutdown complete」。
   · 开发库 nex_animation.db mtime 纹丝没动;down 之后 ./data 完好;deploy.sh --check 全绿(19 项)。
2026-11-05 17:39:12 +08:00
mula.liu 9614b2d225 v 0.1.1 2026-11-05 16:53:24 +08:00
mula.liu 9d62b88b05 规范与闸门收口:R19 反馈四级、R20 标题前不挂图形写进硬规则,探针补到十道
这一笔只动文档、审计与闸门,代码一行没改——前三笔(b6a1df6 反馈表面、552b6b0 门牌图形)
把事做完了,但规范和闸门还停在第十八条 / 六道探针的状态:新规矩没进 §0 那张硬规则表就
等于没立;探针不落地,下一轮改动照样能悄悄长出第五套反馈皮肤。

补进去的规矩(§0 从 18 条到 20 条):
   · R19 反馈只有四级表面,各有唯一实现:行内 `ErrorText`/`LineHint` → 页面 `Notice` →
     结果 `notify*`(自绘吐司)→ 确认 `confirmAction`(自绘确认框);`window.confirm` /
     `window.alert` / `Modal.confirm` / antd `message` / `notification` / 裸 `<Alert>`
     全站清零,也不许再给它们打样式补丁。新增 §13.3 一整节写四级的分工、吐司的四件事
     (右下角堆叠 / 倒计时条与 JS 同源 / 同句去重成 ×N / 一屏最多 5 颗)和确认框的键盘映射。
   · R20 标题前面不挂图形:门牌与卡头的一级标题左侧不许出现图标、色块、头像。
   · 旧口径逐条纠正(10 处锚点全部命中才落盘):R16 ③ 与 §13.1 那张表里 `Notice`=antd
     `Alert`、§13.1 正文「图标由 Alert 自带」、§6.5 外壳表里 `App.tsx` 的「系统异常
     `Alert` → 页面」、§6.1「Content 里除了异常 Alert 就是 `<Outlet />`」、§15.6 tagcheck
     的豁免语「整段 Notice / Alert 保留 antd 语义底」、§13.3 症状里那个被真实换行截断的
     code span。站内已经没有 `Alert` 这个名字了,文档留着它就是在教人写回旧写法。
   · `docs/工程规范.md`:目录职责图与「谁可以 `import 'antd'`」那段摘掉 `stores/notice.ts`
     ——吐司自绘之后它不再 import antd,白名单从四处收成三处。
   · README:闸门命令块补 `aligncheck` / `symmetrycheck` / `feedbackcheck` 三行,硬规则
     摘要补第 6、7 两条审计的说明。

闸门:
   · `classaudit.mjs` 从五条判据加到七条。第 6 条静态禁反馈默认件(`window.confirm(` /
     `window.alert(` / `Modal.confirm(` / `message.xxx(` / `notification.xxx(` / 裸
     `<Alert`),实现本体白名单只有 `components/ui/{Toast,Confirm,Panel,Button,tone}.tsx`
     与 `stores/{notice,confirm}.ts`;第 7 条钉住 R20——门牌与卡头标题里不许再挂前置图形。
     同时把第 5 条 R8 的白名单里那第四处 `stores/notice.ts` 删掉:留着它就等于给「以后
     谁想在 store 里 import 组件库」开后门。
   · 新增第 9 道 `scripts/ui/feedbackcheck.py`:静态审计查不出两件事实——运行时是否真有
     某条老路径弹出过原生对话框、自绘吐司是否真的**显示出来了**(`ToastHost` 挂错位、
     provider 没渲染、store 被引成第二份实例,都会让 `notify()` 静默返回而静态审计照样
     是 0)。它按真实路径逐项验 A~F:全站零 `dialog`、/users 保存后吐司落在右下角且
     `.ant-message` 一个不许有、悬停时 `animation-play-state` 必须 paused、同句去重成 ×2、
     连推 7 句只留 5 颗、关闭键生效、/ 上点删除出确认框(两层文案 + 恰好一颗 dangerous
     primary)、Esc 关掉后项目数不变。
   · 实测(明暗两档):`classaudit` 七条全 0 · `feedbackcheck` 通过 · `btnrowcheck`
     `BTNROWS_TOTAL 0` / `HEAD_BREAK_TOTAL 0`(413 组动作排 / 59 处竖排豁免)·
     `footercheck` `FOOTER_PROBED 30` / `FOOTER_BAD_TOTAL 0` · `aligncheck` 0 ·
     `symmetrycheck` `SYM_TOTAL 0` · `tsc --noEmit` 与 `npm run build` 绿。

手册 12 张插图按「改完 UI 必须重跑 `helpshots.py`」的口径整批重拍(1600×1000@2x →
LANCZOS、锁 light、主角项目 12):旧图还是带主色方块门牌与卡头品牌 N 的那一版。
2026-11-03 23:58:44 +08:00
mula.liu 71fbaf0a94 规范补上 R18 与 §6.5「四级信息层次」,并纠正 §6.2 里那条与代码不符的侧栏描述
症状:这一轮的改动是**结构性**的——项目身份从三处收成一处、页头升成一层独立面板、
外壳退出可见层。规范里原本没有任何一条规定「哪一级的话该在哪一层说」,下一轮只要有人
觉得「概览页再放一颗归档按钮挺方便」,R18 要清的东西就会原样长回来。另一处是真错:
§6.2 写着一级分组叫「当前项目」、项目名挪到侧栏底部的状态块(Divider +「当前项目」+
两行省略的段落 + 当前节点摘要),而代码里那个状态块早就删了、分组现在叫「项目环节」
(`AppSider.tsx` 第 14~21 行的注释就是这么写的)——照着规范改代码会把它加回去。

做法:①§0 标题从「十七条硬规则」改成「十八条」,新增 **R18 每一级的身份与动作只在该级
说一遍**,右侧写上立规依据(用户第 11 轮原话 + 当时同一条项目身份说三遍的现场);
②新增 **§6.5 四级信息层次**:一张四行表把「① 项目入口 `PipelineConsole` / ② 项目层
`ProjectBriefDrawer` / ③ 环节层 `NodeHead` / ④ 内容层 `Panel`」各自的唯一载体、只允许
说什么、明确不许说写死,并补四条口头禅容易踩的坑——外壳 `ProjectDetail.tsx` 除兜底外
不渲染任何可见块(别把项目名/状态 Tag/指标卡加回来)、`NodeHead` 只是 `PageHead` 的一层
皮肤(属性同 `PageHead`,皮肤只有 `app.css` 一处,七站眉标算法只有一份)、抽屉里的跳转
是七站列表而不是流程条(轨道已改成容器自适应网格且整段不可点)、窄屏不许把入口弄丢
(控制台在 375 也渲染,实测 174×32 不撞折叠键);③§6 的 AppHeader 一行标明「它是全站
唯一的项目身份入口,点击展开 §6.5 的概况抽屉」;④§6.2 按代码改写:一级分组叫
「项目环节」、`title` 不拼项目名、侧栏不出现任何当前项目信息,并写明历史上那个状态块
为什么被删;⑤§7 控件档位那条把「PageHead actions」改成「`PageHead`·`NodeHead` 的
actions」,页头新增的那一层不能漏在档位规则外面;⑥README 的条目数同步到十八条
(只提这一行,其余 README 内容归并行的后端改动)。

为什么写成表格而不是散文:这四层的边界是「谁不许说话」,比「谁该说什么」更容易被破;
每层给一句明确的禁止项,下一轮评审能直接指着那一格说这条越界了,不用先争论语义。
2026-11-03 21:27:50 +08:00
mula.liu 7e784b5303 规范补到十七条并把探针升到「六道 + 一道反向验证」:行高、栅格、纵向节奏、标签底色全部有闸
症状:这一轮改的每一类毛病里,有四类靠人眼复查根本守不住——表格行被内容撑高(实测最高
255px)、该用栅格的地方用自然排列(窄屏两种坏画面:一行右边缘参差不齐、折行点随内容
漂移)、纵向节奏断(底边不齐 / 收缩错位)、标签自带彩色底纹(§2.1 要求中性底);而卡头
`right` 长起来把标题压成竖排(430 档标题 291×145)也没有任何闸门会报。更麻烦的是
rhythmcheck 的判据原先读像素,豁免写宽一格就永远安静地返回 0——14 条命中里混着探针
自己的假警报,没人敢信它的红。

做法:①`docs/UI规范.md` 新增 R17 表格行高纪律(§13.2)与 R16 信息块三件套的落地口径
(§13.1),§9.3 补卡头折行那条(含「折行样式要挂在 `.ant-card-head-wrapper` 而不是
`.ant-card-head`」这个陷阱与 430/1440 的实测数据),§15 扩成 15.1–15.7 六道常驻探针
加一道反向验证,§16 提交清单插入第 9 步「动过布局跑三张像素闸、改过判据跑 gateprobe」;
②新增 `tableaudit.py`(逐表报容器宽/可视宽/行数/最高行/列宽,超行高点名)、
`gridcheck.py`、`rhythmcheck.py`(GAP + RAG,四条写法级豁免逐条写明为什么豁免)、
`tagcheck.py`(扫标签 tinted 底);③`gateprobe.py` 用「坏 fixture 必须被点名、合法形态
必须被放行」两组用例反向验证三张像素闸,共 4/4 全对,不碰源码不触发 HMR;
④`rhythmcheck.py` 的判据改成只读写法不读像素(`isPin` 认 mt-auto / inline margin-top /
justify-content;RAG 侧放行子块自带 max-width、align-self 与整行居中的胶囊组),
`classaudit.mjs` 把 `<Flex align="flex-start">` 的取值加进 PROSE 白名单(它天天作为
props 值出现,逐行切词分不清引号内外);⑤`visualcheck.py` 的项目子页改成量「镜头最多」
的项目并支持 NEX_PROJECT_ID 覆盖——列表第一个常是空项目,空态下溢出与截断两类断言等于
没测;⑥README 的规范条目数同步到十七条(只提这一行,其余内容归并行的后端改动)。

为什么:这类毛病全是「看起来挺整齐、量一下才知道差 200px」,只有把它们变成退出码才能
防止下一轮又漏回去;而像素闸一旦可能悄悄失灵,就必须配一道反向验证——先证明闸门坏了
会响,它的绿才有意义。
2026-11-03 20:21:39 +08:00
mula.liu d65a78ce59 规范补到十六条:R15「按钮一律图标按钮」、R16「信息块一律带底纹」
症状:文档还停在十四条,而这一轮真正拦人的是四件没写进规矩的事——
      筛选条字段没规定必须 inline(所以「标签在上」被混进行内栏,一行散成两行)、
      按钮没规定必须带图标(所以整站是纯文字按钮)、
      统计/回显块没规定必须有底纹(所以每个页面自己涂一次白底描边)、
      重点色没规定「一个容器只留一颗」(所以三颗 blue primary 并排)。
      规矩没写=下一轮一定长回来,用户同一句抱怨会再说第三遍。
做法:R1/R2 补上「控件栏字段必须 <Field inline>,宽度落控件列 --nex-ctl-w」,
      新增 R15(图标按钮,含 FilePick/RecordAudio 也走 icon 槽)、
      R16(底纹走 fill-tertiary,禁止手涂 bg-[#...]);
      新增 §5.1.1「一颗按钮一只语义图标」、§5.1.2「关键动作才有重点色」;
      §2.1 记下状态色的新口径(浅色删掉自造档回到出厂,深色只抬亮一档,
      并写清深色会再走一遍 darkAlgorithm、字面量不是最终值);
      §7 示例改成 inline 写法,并登记现网实测「19 条 Ctlbar / 27 个字段,0 例外」;
      §9 补「标签在上只属于抽屉/弹窗/长表单」;
      §15.2 写清闸门的两处口径修正(浮层底部只查 Drawer/Modal;侧栏探针
      kind=item 才比色板、`.anticon` 不参与行高断言);README 索引同步到 R1–R16。
为什么:这四条不是审美偏好,是用户两次截图里的原话;写进硬规则并被 classaudit /
      visualcheck 管住,比在代码里留十条注释更能防止下一次回潮。
2026-11-03 17:03:34 +08:00
mula.liu 5f294c9ccb 补上 R8 这道闸并让文档说真话:classaudit 第五道检查 + README/工程规范回到 antd 版现状
症状:README 还在讲 metrics.ts / palette.ts / css-vars.ts 三把尺子、33 组 ComponentToken、
--ctl-h* 变量、ToolButton/IconSpot/MenuRow 这些本轮已经删掉的东西;R8「谁可以 import 'antd'」
只写在文档里,没有任何机器拦着——文档一漂,规范就退化成建议。

做法:
- classaudit.mjs 加第 5 道闸:`from 'antd'` 逐行扫,白名单只有 theme/ · app/ ·
  components/{ui,forms} · stores/notice.ts,退出码并入违规总数;已反向验证
  (pages/Account.tsx 临时插一行 import 后探针点名并报 exit=1,撤掉复绿)。
- README 分层表与两段口径重写:theme/ 只剩 antd.ts(buildAntdTheme + applyRootVars + HEADER_HEIGHT)、
  styles/ 的 --radius-* 只是 --ant-* 的别名、裸 <button> 白名单换成 CUSTOM_SURFACES 真实的 7 个文件、
  两道探针的描述换成它们各自真正查的东西(五道 / 八类)。
- 工程规范:theme/ 目录行、--ctl-h 档位、§0.5 与「§6 自绘区边界」这些失效指针改到
  R8 / §1 四层分工 / §5.2 自定义表面族;stores 补 recording;app/ 行写明 nav.tsx 是两级菜单唯一来源。
- kit 注释里的 §0.6 指针改指 R8 与 §5.2(那一节已随手写规范退场)。

验收:typecheck + build 通过;classaudit 五道全绿 exit=0;visualcheck 1440/768/430 × dark/light
(含登录页在登录前先量一趟)console 0 条、HTTP 失败 0 条、断言 0 条。
2026-11-03 12:59:59 +08:00
mula.liu 62c356952c UI 规范与两道常驻探针同步到 antd 版:classaudit.mjs + visualcheck.py,旧探针归档
docs/UI规范.md 按 antd 重写(16 章 / 十四条硬规矩 R1–R14):
- §6 外壳(Header 56 + 两级 Sider + Content)、内容页不做多页签、页签只在页面内部,
  Tabs vs ViewSwitch 的判据;§9.3 值型控件的宽度归控件而非「标签+控件」+ nex-prose-value 豁免登记;
  §10 下拉面板「至少同宽」与折行、标记类全集 18 只;§5.1 按钮上的字必须整颗放得下;
- §15 两道闸的判定口径写死,退出码都必须为 0。

scripts/ui/classaudit.mjs:四道判定(死类名 / 绕过登记表的图标 import / 裸 <button> /
浮层底部动作口径),基线 3912 个候选,必须在仓库根跑。
scripts/ui/visualcheck.py:登录 → 逐路由 × 逐档宽度 × 明暗截图,钉死八件事——
:root 尺子、行高、侧栏选中态(窄屏折叠时展开浮层复核二级项)、路由没被 path:'*' 静默吞掉、
display utility 被组件样式盖掉(R13 闸门)、横向溢出与切字、
控件标签**含下拉当前值**不许被省略号截断(散文型选项值按 nex-prose-value 放行)、
4xx/5xx 按 URL 分诊(素材缺文件单独计数,接口 404 点名发出它的路由)。
新增的 4xx/5xx 一条顺带治好了时间线 / 交付页「空状态对、代价是两条 404」的假绿。

旧的 audit.py / metrics.py / vocab.py 量的是已删的那套自造尺子,移进 scripts/ui/legacy/ 并标注作废。
README 与 docs/工程规范.md 同步:theme/ 只剩 antd.ts 一把尺子,导航与页签口径改为两级菜单 + 内部页签。

本轮验证:tsc 0 错 / classaudit 四道全 0 / vite build 通过 /
visualcheck 两轮各 104 张(1440·992·768·430 × dark·light,空项目与数据齐全项目各一轮)
console 0 条、HTTP 失败 0 条、断言 0 条。
2026-11-03 12:42:28 +08:00
mula.liu 4521c9f926 前端统一到 React 18 + Ant Design 5 + Vite + Zustand + React Router 6:控件不再在原生件上缝皮,Radix 那一层整体换成 antd 标准件 + 一层自有 kit,并把「谁定义控件」收口成词汇表。
用户连着三轮指出「字段标题、控件不对齐」「下拉控件的样式不对」,最后点名技术栈。真正的病不在
antd 还是 Radix,而在同一件事有三千种写法:左导航内边距一页 11px 一页 12px,白名单要从页面
className 上抄切片才能命中。上一轮 Radix 只外包了行为,皮肤仍由 30 多个页面自己拼,且没有任何
机制阻止分叉长回来。这一轮改的是词汇表:页面只准说业务,控件怎么长由 kit 层 + 一份令牌说了算。

底座(读数见报告 26.2):react 19.3.1→18.3.1、react-router-dom 7.18.5→6.30.6(点名为 18/6,是
降级,代价见 26.6)、新增 antd 5.29.3 + @ant-design/icons 6.3.4,@radix-ui/* 5 包与
class-variance-authority 清零;zustand/vite/tailwindcss 4.3.3 不变,Tailwind 留作皮肤 utility。
删 components/primitives/(11 文件 1133 行)与 styles/{base,tokens}.css;净 +488 行不是「少一千行」,
是同样面积的代码从三十个页面挪进两个目录——省的不是字节,是分叉次数。

新增:
- app/providers.tsx:ConfigProvider + <App> 唯一入口(主题、zh_CN、button.autoInsertSpace:false、cssVar),
  命令式 message/notification/modal 挂 antdApi 供 stores/ 使用;React Router 的 v7 future flag 一处收口。
- theme/{palette,antd,css-vars,metrics}.ts:数字只有一个来源 metrics.ts → 同时喂 antd ThemeConfig 与
  --ctl-h-*/--radius-*/--text-*,antd 控件与自绘区读同一把尺子,结构上长不歪了。
- components/ui/{Input,Checkbox,Menu,Rail,Tile,Overlay,field-labels};lib/layers.ts(Esc 先看有没有 antd
  浮层压着,否则分镜检查器里关一个下拉整层抽屉一起没)、lib/ref.ts、hooks/use-narrow.ts(触摸档必须
  同时喂给 antd 的 JS 数字,否则 560/430 一屏混着 31/38 与 36/40 两把尺子——首跑量出的 61 项就这么来的)。
- styles/app.css 接替 base+tokens,只留元素默认值与三处必须靠 CSS 的 antd 集成。
- scripts/ui/ 三件套首次入库:audit.py 七项机器判据 × 14 视图、vocab.py 六条源码词汇表闸、metrics.py。

修掉四个探针全绿也看不见的静默 bug:
1) 探针会假绿:浮层用例找不到抽屉时兜底 scope=main 把页面重量一遍,分镜「检查器」29 字段/57 输入
   /35 按钮(在 main 外面的 aside 里)一条都没测过。
2) Select 选中 null 回显成灰色 placeholder:antd 把 null 当无值,而「不绑定/无台词/未指定」的真实值
   就是 null(接口收 null,10 处)。kit 内折哨兵 nex-null,出入口各折一次,页面 API 一字未改。
3) JSX 子节点上的 /* */ 不是注释而是文本,挂在应用外壳之上把整站下推约 30px;移到 JSX 外并立词汇表规则 6。
4) 抽屉可以整块开在屏幕外面:Overlay 用 getContainer={false} 让 antd 就地渲染,rootStyle 的 absolute
   于是相对文档定位——入口按钮在折叠线以下时抽屉 y=-scrollY(1440 lib_edit 只剩 201px,430 assets_gen
   完全不可见,用户点了「AI 生成」像没反应)。改 fixed 后四档 10 个浮层全部 y=0 完整可见。为此给 audit
   加第 7 项判据 surface(浮层完整落在视口内 + 中心点 elementFromPoint 命中自己),反向验证:改回
   absolute 后 430 下 4 红 exit=1;判据取「有交集」太松(42px 也算过),收紧为「完整在视口内」才对。

验收(复跑读数):audit --only page 1440/1280/900 × 明暗 6 组 84 行视图全 0、exit=0;--only overlay
1440/900/560/430 × 明暗 8 组 exit=0,surface 80/80 绿,72 个下拉样本 popW==trigW、inViewport、
optClipped=false、popOnTop=false 计 0;vocab 85 文件/皮肤常量 79(账实相符)exit=0;
npm run build(tsc+vite)exit=0(ui chunk 881.94 kB / gzip 278.63);probe_nullopt CLEAN、probe_secretref PASS。

文档同步:UI规范 §8 判据清单五项→七项(补 surface)、§1.3 新增「抽屉可以整块开在屏幕外面」;
工程规范 §1.1 体检器职责改为 10 浮层 × 4 宽度 × 七项;README 六项→七项判据;报告补第二十六章
26.1–26.9(选型换向、版本读数、四条根因、改法、逐项验收、降级代价、注释泄漏、仍未做、抽屉开在屏外)。
2026-11-02 21:57:13 +08:00
mula.liu 83d262a199 文档把选型决策、R7 与探针口径写死:UI规范新增 §0.6「标准控件组 = Radix primitives + 自有皮肤」,报告补第二十五章。
UI规范.md:§0.6 一次讲清四层分工(尺子 tokens.css / 行为 primitives / 皮肤 layers.ts / 语义 ui+forms)、
否掉 antd-MUI-Arco 的三条量化理由(两套尺子、preflight 抢深浅主题、深色皮肤要覆盖八成)、
以及规矩(页面与 ui/ 不许直接 import @radix-ui/*、新浮层必须先在 primitives 落原语再登记、
层级只用一套、Esc 先看 floatingLayerOpen()、Content 上写 fixed 会让 Radix 量到 0 高)。
另立「两个咬过人的陷阱」:① [&>*]:min-w-0 与 min-w-(--label-w) 特指度平票会无声清零标签下限;
② Playwright 的 locator.click() 先做 DOM.scrollIntoViewIfNeeded 把目标居中,
「开抽屉把页面顶回顶部」就是这么造出来的假 bug——量滚动位移前基线必须在 scroll_into_view_if_needed() 之后取。
硬规则从六条升到七条(R6 从「不用裸 select」扩成「控件不用浏览器原生外观」,新增 R7 字段形态唯一);
§0.5 对照表补 Checkbox/Slider/Popup/Menu/Dialog 与 floatingLayerOpen 六行;§3 的 hint 栅格写法
从 grid-cols-[auto_minmax(0,1fr)] 更新成 minmax(var(--label-w),max-content)_minmax(0,1fr);
§8 登记 align4(五判据各 0 组)与 ctl4(31 项)为新口径。

工程规范.md:§1.1 依赖链插入 components/primitives/ 这一层(附「一个用户就进,不等第二个用户」的例外),
扩展点加「加一类控件行为」一行,§4 补依赖卫生判据:grep 出的 import 集合必须等于 package.json。
README:分层表加 primitives/ 一行,并写清「不引成套组件库」的结论与 5 个 radix 包全部有 import。
报告第二十五章:现象归因表(对齐是 CSS bug、下拉与原生外观才是组件库该管的)、选型对照表、
三个根因的读数、逐项验收表(30 字段五判据 0 组、31/31、原生残留 0、13 装 6 用 → 5 装 5 用),
以及仍然没做的四条(MediaLightbox/RecordAudio 自绘 overlay、检查器刻意非模态、Tabs/tooltip 无用户先卸包、
日期与命令面板按需再补)。
2026-11-02 16:17:20 +08:00
mula.liu 20e8f19eca 前端统一收尾:图文手册从 public/help.html 搬成站内 React+Tailwind 页面 /help,SPA 深链回落与未知接口 404 拆成纯函数补自检,新增 ErrorBoundary 兜住分包加载失败 2026-11-01 19:25:47 +08:00
mula.liu e8e5a1cd2b 文档与脚本同步 React+Tailwind:UI 规范增加词汇→原语对照,工程规范补 frontend/src 分层与扩展点,README 目录/构建口径更新 2026-11-01 19:01:03 +08:00
mula.liu 9467e1bb97 v 0.1.0 2026-11-01 16:18:07 +08:00