Commit Graph

38 Commits (98ea70d74f571f7f66c656aee69c9fbfb22bbf49)

Author SHA1 Message Date
mula.liu 98ea70d74f docs(规范): 阶段 8.5 六处落点 + 常驻探针计数与代码对齐(12 → 13 道)
批准书 §1 的 DEFERRED 要求「先梳理组织关系、只在可复现缺陷处局部修」,§9 要求
「设计规范更新」,所以规范层落了六处,且**不新建第二份规范**(尺子仍只在 UI规范.md):

`docs/UI规范.md`(+316/−11)
· §1.1.2 全站样式组织现状 + CSS Layer 迁移的 DEFERRED 决策:分层/未分层清点口径、
  当前层叠优先级怎么成立(Tailwind layers → antd → 未分层 .nex-* 覆盖层)、
  `@layer` 声明 0 条 / `!important` 4 条全在 reduced-motion 内、唯一那条压过
  `max-md:hidden` 的未分层规则(=L-1)、以及为什么真要迁就要连 preflight 一起想清楚
· §6.2.1 导航的两个状态与「故意不同的生命周期」(折叠=偏好走 localStorage /
  抽屉=一次性动作走 useState)+ 当前页对辅助技术可见(aria-current)的暴露规则与折叠档边界
· §6.5 「窄屏不许把入口弄丢」后补三通道:Hover / Focus / Touch,只在真的截断时弹,
  触屏档按 `matchMedia('(hover: hover)')` 能力收口(不弹),并登记 N-3 待真机复测
· §13.2.1 窄屏表格两套列档位:`useNarrowTable()` 口径、九张表各自方案表、
  「换列定义不换 DOM」的辅助技术理由、数据完整性对账方法(token 级失踪计数)
· §15 标题与 §15.12/§15.13:十三道常驻探针 + 一道反向验证,新增 semanticcheck 那条判据说明
· §16 第 9 / 第 12 步:改尺子的回归清单补上 `gateprobe` 十四条判据与 semanticcheck

`docs/NEX-对照与例外.md`(+8/−3):§8 响应式那行补本项目走的第四条路(窄档换 columns,
建议 NEX 补进 04 §8.2 → N17);§2/§3/§5 新增一行「验收手段」判定 = COMPLIANT(阶段 8.5
起有机器证据),并记下 NEX 08 只列要求不给证明方式;HEAD↔工作树语义读数改成本轮实测口径。

`AGENTS.md`(+2/−2):两处「12 道常驻探针」→ 13 道。这是 semanticcheck 加进来之后
文档与代码对不上的最后一处,现已全站 grep 无残留旧计数。
2026-11-08 14:50:30 +08:00
mula.liu 687bf5a64d NEX 阶段 8·N14:分镜排序补上键盘替代 ⌥↑/⌥↓,改镜序不再是鼠标专属
阶段 2 把分镜卡做到「点得开」,但排序仍然只有两条鼠标路(HTML5 拖拽 + 分镜表两颗按钮):
键盘能走到卡片,却走不动卡片。用户批准 N14 后按「不加新控件」的口径补齐第二条路。

实现(frontend/src/pages/project/Storyboard.tsx):
- move() 回传 Promise<boolean>(越界 false,其余走 run() 的既有返回值)。三个
  void move(...) 调用点一字未改,行为不变——run() 本来就返回布尔,只是没人接。
- 新增 moveByKey():越界报「镜头 N 已经在第 M 位,无法继续前移/后移」,成功报
  「已后移到第 M 位」;随后 refocusShotCard()(rAF 最多 8 帧找回 [data-shot-card])
  把焦点还给同一张卡——列表整体重排会把卡片重挂、焦点掉回 <body>,
  不归还的话第二下按键根本没有落点,等于「只能移一格」。拿不到就不抢焦点。
- ShotCard.onKeyDown 先接 Alt+↑/↓(preventDefault + stopPropagation)再走 Enter/Space:
  卡片正处在 window 那条「方向键切镜」监听的冒泡路径上,不拦一次按键会既移镜又切镜;
  window 侧同步加 if (ev.altKey && Arrow) return 兜底,焦点不在卡上时宁可不响应。
- 可达性:aria-keyshortcuts="Alt+ArrowUp Alt+ArrowDown" + 全站一份 sr-only 说明
  (卡片用 aria-describedby 指过去)。不给整块热区加 title——原生 tooltip 会盖住
  卡内每一处;也不给每张卡的 aria-label 各念一遍——30 张卡念 30 遍同样的话。
  aria-label 逐字未改,阶段 2 的口径与探针定位都不受影响。
- 反馈的不对称是刻意的,写进 UI规范.md §13.3 ⑤ 第 3 条:拖拽时卡片跟着手走、落点
  由卡片自己说,键盘时手没在版面上、必须由文字说出「成到哪」;判据从「输入方式一致」
  改成「用户能不能自己看见落点」。播报走 notify()(Toast 容器本身是常驻 aria-live),
  不另起第二条 live region(R19)。
- 不新增卡脚按钮:224 档实测那一行会劈成 2+1(正是 btnclustercheck 拦的形状),
  补按钮就得缩控件或加行,两者都属本轮排除的视觉改动。看板/表格像素零变化,
  新插入的 sr-only <p> 放 grid 外面,不参与列宽计算。

帮助页同步:pages/Help.tsx 的分镜步骤与快捷键清单加 ⌥↑ / ⌥↓(注明 Win/Linux 用 Alt)。
G3 补「热区不是按钮时快捷键挂在哪」;对照文档 §2.8 更新证据、§5 N14 ⏸→✅、§7 变更记录。

验证:npm run typecheck 通过(中途抓到一处真实 TS1005:普通注释搬进 JSX 子节点)·
npm run build 通过(仅既有 chunk>1200kB 告警)· classaudit 九道闸全 0 EXIT=0 ·
新写专项探针 sortcheck(明暗各 6 组:顺序变了 / 焦点没丢 / 有播报 / 边界会说话且顺序不动 /
不 Alt 的方向键行为不变 / Enter 仍打开检查器)PASS 0 条,对 HEAD 反证 FAIL 14 条 ·
常驻 11 道探针 EXIT=0 ×11(GATEPROBE_OK 11/11,含 feedbackcheck 与 gridcheck)·
visualcheck 120 状态(15 路由 × 4 视口 × 明暗)断言 0 / HTTP 0 / console 0,
另跑 1440 单档 30 状态同样全 0。证据 reports/ui_evidence/nex-p8/n14/。

上游:NEX 08 §2 新增「可排序条目的键盘移动方式」五条(子仓库单独提交)。
2026-11-08 00:16:30 +08:00
mula.liu ae4dd7f68e NEX 阶段 8·D17/N7:<768 导航改左抽屉,同一屏只剩一个导航入口,顶栏胶囊溢出归零
用户批准「移动端导航采用抽屉式 Drawer」。改前三条实测决定了必须怎么改:
① Sider 的 breakpoint="md" 把侧栏自动收成 64px 图标轨,而汉堡同时还在,
   label 写着「展开导航菜单」——点它只把图标轨撑回 224,随即又被 breakpoint 收回,
   同一屏两个导航入口且行为自相矛盾(NEX 04 §8.2 明令消掉的状态);
② 那 64px 是真金白银的正文宽度:430 实测正文盒 366(可用 342)、576 实测 512;
③ D17 那 33–38px 溢出正是被它逼出来的:流水线台那颗 Button 内容居中,
   装不下就两端一起往外溢——430 胶囊盒子 x=100 w=172、内容 sw 203,
   项目名从 x=63 起画(比胶囊左沿还偏左 37px),箭头画到 x=305(胶囊右沿 272)。

实现:
- kit Drawer 加 placement(默认 right,站内既有 10 处调用点一个都不传,行为逐字不变)
  与 flushBody。flushBody 只能是 prop:.ant-drawer-body 的 padding 是 antd CSS-in-JS 的
  未层声明,页面写 p-0 在 @layer utilities 里,层外压层内(同 §1.1.1 的 .nex-tag 实测)。
  左右默认宽分档(左 min(288px,100vw−48px) / 右 DRAWER_WIDE):抽屉宽度取决于它是
  「替换主内容的位置」还是「压在主内容上的一块面板」。
- AppSider 拆三导出:AppNavMenu(菜单本体)/ AppSider(≥768 常驻,撤 breakpoint)/
  AppNavDrawer(<768 左抽屉,宽 = SIDER_WIDTH 224 + flushBody)。抽屉宽不取 antd 默认 378:
  里面是同一份菜单,宽度一换折行、缩进、选中底色宽度全都换,等于凭空多出第二个导航形态。
- App 测一次 narrow(Grid.useBreakpoint().md === false,undefined 当桌面否则 1440 会闪一帧
  「没侧栏只有汉堡」)往下传:侧栏在不在、汉堡点哪儿,两处必须同一个答案。navOpen 换页自动关。
- 同一颗汉堡换语义:≥768 折叠侧栏(原文案),<768 开合抽屉(打开/关闭导航菜单),
  aria-expanded 只在抽屉形态给(折叠侧栏是布局尺寸,不是被展开的面板);图标改按
  「导航现在露没露」选,≥768 时 navShown === !collapsed 与改前逐字同值,<768 抽屉关着时
  画的正是改前那颗 Expand → 顶栏像素没动。
- PipelineConsole 的项目名只在 <768 恢复收缩权(max-md:min-w-0 max-md:flex-[0_1_auto])。
  第十三轮给的 flex-none 是为了「名字不许被散文吃掉」,那条在 ≥768 依然成立;手机档没有
  散文可吃(cur <lg 隐、rail <xl 隐、status <md 隐),只剩「名字 vs 百分比+箭头」一道减法,
  折出来的是省略号 + tooltip(§15.2 第 7 条:省略号可以,残字不行)。

探针:visualcheck 补 probe.sider;菜单断言先问侧栏在不在,<768 真点一下汉堡,量
.ant-drawer-content-wrapper(外层 .ant-drawer 是 inset:0 的遮罩容器,宽恒等视口,拿它比 224
会全线误报)并断言左贴边 / 宽 224 / 选中态底色等于桌面同一份 token / Esc 必须关。
顺手修掉一处从阶段 0 就存在的失配:menu_required 用 `path in NAV_ROUTES` 比的是**模板**
(/projects/{id}/overview),主循环早已换成真实 id,七条项目路由从没进过菜单断言——
新增 in_nav() 后覆盖 3 → 10 条路由。

未做(授权 §六):卡片没扩大、栅格没改、56/224/64 与控件三档一字未动、430 的表格仍横向
滚动而没有顺手改堆叠单栏。

验证:typecheck 通过 · build 通过(仅既有 chunk>1200kB 告警)· classaudit 九道全 0 exit 0 ·
visualcheck 120 状态(15 路由 × 4 视口 × 明暗)0 断言 / 0 HTTP / 0 console ·
常驻 11 道探针 EXIT=0 ×11(GATEPROBE_OK 11/11)· 第 9 闸反证 BP_PROBE_OK 10/10 ·
navprobe 几何 FAIL 4/10 → PASS 0/10(430 溢出 33→0、正文 366→430)·
drawercheck 行为账 after PASS 0 条,对 HEAD 反证 FAIL 10 条 ·
tableaudit 逐视口前后:1440 两态 0 违规、768 两态逐字相同、576 溢出量各 −64、430 违规 9→6 ·
≥768 像素疑点定性为 Noto Sans SC 异步 swap 竞态 + 活动角标漂移:document.fonts.ready 后
before/after 顶栏强差 0(1440 与 768),1440 两态 DOM 几何逐字相同。
证据 reports/ui_evidence/nex-p8/d17/。

规范同步:UI规范 §6 外壳表补 AppNavMenu/AppNavDrawer 两行并写清撤 breakpoint 的理由、
§15 第 3 条改抽屉口径 + 登记 NAV_ROUTES 事故、§4 insp-sm 同步复核结论;
NEX-对照与例外 §2.4 <768 DEFERRED → ADOPTED、§5 N7 → 已采纳、§6 D17 → 已修、§7 变更记录;
nex.config.yaml shell 段加 sidebar_narrow: drawer 并校正四条尺寸的实现行号。
2026-11-07 23:36:48 +08:00
mula.liu 0b9ea0a430 NEX 阶段 8·N16:断点治理装上机器闸,登记从「两份人写的表」变成一条可对账的规矩
阶段 7 把页面里 5 把裸 max-[1240px] 之类的私档改名成 --breakpoint-* 命名变体,
归名之后留下的问题是:「登记」这件事只剩两份人写的表(styles/index.css 的 @theme
和 UI规范 §4 那张表)加一句 grep。下一轮谁再写一个 max-[900px]:flex,编译得过、
像素也对,只有人眼能发现;反过来说,往 @theme 加一档却忘了同步 visualcheck.py 的
BP 表更糟——wantDisplay 会对这一档静默返回 null,断言悄悄不跑了,比报错更难查。

classaudit.mjs 新增第 9 闸 BP:尺子的唯一真相是 @theme 里的 --breakpoint-*,其余
四处(页面用词 / UI规范 §4 表 / 探针的 BP·BPORDER / 尺子自己的使用面)全部由这条
闸向它对账,五条判据——① 裸 max-[…]/min-[…];② 用了没登记的变体名(写错名字
Tailwind 不报错,只是这一档压根不生成规则);③ 登记尺子必须有且仅有一个使用者、
不得 0 使用者、必须被 §4 表收录(§4 那三条口径的机器化);④ 每档都要出现在探针的
BP 与 BPORDER 里且同名同值同序(顺序错了会挑错赢家);⑤ .css 里 @media
(max|min)-width: Npx 的 N 必须是登记值,否则页面归了名、样式表里再开一批私档白干。
主阶梯「该不该在这一档换排布」是 R9 的语义判断,机器量不出来,这条闸不管。

闸按 §15.1 的口径反证过 10 例(写坏→红且点名→还原复绿),含一条反向的反向:agent
这把尺子的口径是「一个使用者」不是「一次使用」,同文件第 11 处复用必须放行,否则
闸就成了数次数的假判据。产物 reports/ui_evidence/nex-p8/n16/scripts/gate_bp_proof.py。

顺带修一处本轮写闸时踩到的自伤:新增第 9 闸时把 process.exit 表达式里的 dead.length
顶掉了(第一道闸从此不影响退出码),已还原——这类「闸门静默失效」正是这条闸自己要
防的毛病,写闸的人也一样会犯。

规范侧:NEX 04-layout-system.md 新增 §8.1 命名断点登记出口(有名字/有唯一使用者/
有实测/有对账四条)与 §8.2 专业工作区窄屏降级范式(<768 导航只留一个入口),已在
nex_design_system 子仓库单独提交 63e36ec;UI规范 §4 复核口径从「grep 必须为 0」
改为五条判据 + 指向第 9 闸,§15.1 闸表 8→9 并补基线输出;nex.config.yaml 补
breakpoints_registered 五档、ui_gates 注释改 9 道子闸、custom_breakpoints 从
forbidden 改 registered_only(原注释「禁止私档断点」已与阶段 7 的登记出口不一致)。

验证:classaudit 九道全绿(10 档在册 / 5 把登记尺子 / 0 命中,exit 0)·
反证 BP_PROBE_OK 10/10 · typecheck 通过。页面与样式文件零改动,像素不受影响。
2026-11-07 22:39:17 +08:00
Codex 1227003173 NEX 阶段 8·D16:kit 的 Tag 不再吞 className,顺带量清「页面到底能给它写什么」
Status.tsx::Tag 的形参收了 className 却没并进 cn(),全站 10 处站点从写下去那天起就是空转。
并进 cn() 末位(学同文件 Badge 的写法,tailwind-merge 保留后写者)之后逐站点实测,
结论与最初的推测不一样,两半都得记下来:
· 真的一半:styles/index.css:55 的 @import "./app.css" 不带 layer,未层声明高于任何
  @layer,所以 .nex-tag.ant-tag 独占的 13 族属性页面 utility 压不动(display/底/色/圆角/
  内距/字号/行高/min-height/gap/max-width/white-space/overflow/margin-inline-end);
· 假的一半:.ant-tag 带 transition:all .2s,改完类名立刻 getComputedStyle 读到的是过渡
  起始值,margin/flex/font-weight 曾被集体误判成「输了」(700ms 后再读就对了)。
明暗两档逐属性量出能力矩阵,写进 UI规范 §1.1.1,并给 classaudit 加第 8 闸 TAGSKIN:
给 kit 的 Tag/Status 写皮肤类 = 判违规(该走 tone,或把 display 留在 wrapper 上)。

站点回归:ModelCenter「默认」只留 font-bold(皮肤族点不亮,§2.1 也早已废止语义铺底);
Review 的视觉模型名改走 tone="mono";分镜卡撤掉 flex-none 那层 wrapper,
缩略图角标的 absolute 第一次真的生效(此前掉出 overflow-hidden 盒子,探针 visible=False);
PipelineConsole 的 wrapper 保留,注释改成实情:它只为 display 族存在,撤它得先降 .nex-tag 皮肤入层。

验证:typecheck / build 通过;classaudit 8 道闸全 0;常驻 11 道探针 EXIT=0;
visualcheck 15 路由 × 4 视口 × 明暗 = 120 状态全绿(断言 0 / HTTP 0 / console 0);
932 颗标签 before/after 逐站点 diff,46 处差异全部落在预期站点,且无一处皮肤字段改动。
证据与元素级前后截图:reports/ui_evidence/nex-p8/d16/。
2026-11-07 22:35:11 +08:00
mula.liu 5753177616 NEX 阶段 7 断点归一:五把实测尺子登记成命名断点,页面里裸 max-[...] 归零
改的是尺子的名字,不是尺子的刻度。审计字面方案(620→576、720→768、
1080/1240/1400→992/1200)逐条实测后全部不采纳,走审计自己留的出口条款
R9:登记为项目断点。

- styles/index.css:--breakpoint-* 主阶梯后面补 5 条登记档位
  insp-lg=1400 / board=1240 / insp-md=1080 / insp-sm=720 / agent=620,
  每条注明唯一使用者;口径写进注释(一把尺子一个使用者、名字即表面、
  加档要带视口测量、删档要连带删掉唯一使用者)
- Storyboard.tsx / AgentConsole.tsx:15 处 max-[Npx] 换成 max-<name>:,
  并把「为什么不能并到邻居档位」的实测读数写进就地注释
  (agent 并到 576:指令列 415→150、行高 71→90;board 并到 xl:
  1204–1239 由 4 列 224 退回 3 列 301;insp-sm 并到 md:721–767 整屏盖住图标轨)
- scripts/ui/visualcheck.py:wantDisplay 的断点表同步这 5 个名字。
  归一之前凡含 [ 的类名被直接跳过,这轮起 max-board:flex /
  max-agent:order-5 才真的按档位算期望 display 与顺序
- docs/UI规范.md §4:断点登记表落地(档位 ↔ px ↔ 使用者 ↔ 采用理由)
- docs/NEX-对照与例外.md:新增缺口 N16 —— NEX 没有「主阶梯放不下时
  的命名登记出口」这一条

验证(最终代码态,全部 EXIT 0):typecheck / build 430ms / classaudit
0 死类名 4088 候选 / 11 道常驻探针 + GATEPROBE_OK 11/11 /
visualcheck 120 状态(15 路由 × 4 宽度 × 明暗,新增 576 档)+ 36 张边界档
断言 0 console 0 HTTP 0 / grep -rn "max-\[" frontend/src = 0 /
sbprobe 16 档与 agentprobe 10 档改前改后 JSON sha256 相同 /
dist CSS 五个断点块声明体逐字节相同 / 9 对前后帧 Header 以下 0 显著差异像素、
总控台两对 PNG 逐字节相同 / 阶段 1 tagw、阶段 2 kbd(1440 与 576)、
阶段 3 zorder5 跨阶段复跑全绿

报告 reports/NEX阶段4-7实施-2026-11-07.md(§4 与 §7 为本轮)
2026-11-07 18:54:24 +08:00
mula.liu 3e86b282e0 NEX 阶段 6 拆 kit 与清死代码:Panel/Controls 按职责分成五份、删 7 个 0 调用导出与 2 个死 hook、R8 承认 app 为外壳层 2026-11-07 18:21:47 +08:00
mula.liu bc5d1bcc90 NEX 阶段 5 定一次操作的反馈预算:Library 5 处原生对话框收口、录音链 3 颗吐司并成 1 颗、模型中心开关补结果反馈、430 统计卡改两列 2026-11-07 17:51:40 +08:00
mula.liu 24513a976e NEX 阶段 4 补齐状态表面:首屏骨架、抽屉骨架、权限不足与地址不存在兜底页 2026-11-07 17:14:37 +08:00
mula.liu 4411d222fa NEX 阶段 0–3 落地:规范对齐、状态标签截断兜底、三处热区键盘可达、浮层层级表
阶段 0(0 行业务代码):根 nex.config.yaml 把本项目实测值写死(Header 56 / Sider 224·64 /
Content 24·1680),AGENTS.md 的 NEX 路径统一加 nex_design_system/ 前缀并声明
docs/UI规范.md 为项目级权威;新增 docs/NEX-对照与例外.md 逐条判定 81 行
(COMPLIANT 49 / ADAPTED 17 / ADOPTED 13 / DEFERRED 7 / N-A 10)+ 例外 E1–E10
+ 别名表(不新增 --nex-* 命名空间)+ 反向清单 N1–N15。
阶段 1:ui/Status.tsx 的 Tag 自己兜 title(flatText 取正文),分镜卡标题 min-w-0、
状态标签 flex-none,顶栏流水线台 max-md:hidden 收口;visualcheck 新增 tagtitle 断言,
「截断却没兜底」从此进闸门。修掉分镜卡标签压到 35px、顶栏胶囊塌成 7px 两处实测病灶。
阶段 2:三处非语义热区可键盘化——顶栏品牌区改真实 <Link>(头像与平台名合成一个焦点站)、
分镜卡 <article> 加 tabIndex/aria-label/aria-current + Enter/Space(不套 role=button,
免抹掉卡内勾选框与三颗按钮)、Rows::LogRow 只在真有 onClick 时进 Tab 序列。
阶段 3:lib/layers.ts 建立 9 档层级表并被 7 处浮层引用;顺带修掉两条实测遮挡——
素材抽屉里点缩略图灯箱看不见(220 < 抽屉 1000)、声线抽屉里录音面板点不着(260),
确认框第一次拥有自己的数(1190)以免灯箱抬升后压不住。

验证:typecheck / classaudit / build 全部 EXIT 0;visualcheck 84 状态(14 路由 × 3 视口 ×
2 主题)console 0 · HTTP 0 · 断言 0;11 道常驻探针 GATEPROBE_OK 11/11。
详细取证见 reports/NEX阶段0-3实施-2026-11-07.md。
2026-11-07 16:49:14 +08:00
mula.liu 2d58807478 v 0.1.2 2026-11-07 02:55:35 +08:00
mula.liu ce91173a6c v 0.1.2 2026-11-07 00:48:17 +08:00
mula.liu a73ce504c9 用户管理按其它模块的口径重做,卡头不再复读页签与角标
用户这一轮两条,其实是同一句话:**同一个信息在一屏里只许说一次,同一类操作在任何模块里必须是同一个动作**。

**1)用户管理:从「左右两栏 + 常驻表单」改成「列表 + 抽屉 + 行内动作」(UI规范新增 §13.5)**
它是站内唯一一个没跟上口径的模块:左列表 + 右详情面板各占一半、页面顶部常驻一张新建表单(还自带一套
`formDirty` / `keepForms` / `syncEdit` 脏检查)、表格没有操作列、五张统计卡只有数字不能点、
抽屉里那颗「允许登录」`Check` 与列表上的「停用」是同一件事的两种写法。逐条对齐资产库 / 模型管理中心:
- 整行点开抽屉(`Table onPick`),**新建与编辑共用同一张 Drawer**(980px,与资产库编辑抽屉同宽)——
  关掉即放弃,于是压根不需要脏检查:Kit 没有的那层状态不再自己造;
- 操作列四颗纯图标(编辑 / 重置密码 / 注销会话 / 停用⇄启用),逐个 `aria-label`,0 会话与停用自己分别
  disabled,整列 `stopPropagation`,免得点图标连带打开压在底下的抽屉;
- 四张统计卡**全部是筛选入口**(AS-7 同一口径),删掉第五张「活跃会话」:它不是入口,数字还被探针登录污染成四位数;
- 后端 `GET /api/users` 新增 `status`(`active` / `disabled` / `pending`,非法值 400),与既有 `q` `role`
  可叠加,`counts` 恒为全库数——统计卡点下去不会把自己的数字点没。「管理员」那张必须筛
  `role=admin&status=active` 才与卡上的数一致(`counts.admins` 只数启用中的),`pending` 同理写
  `must_change_password && is_active`:停用的账号本来就登不进去,不该再算「待改初始密码」;
- 搜索 320ms 防抖(与资产库同一个值);`useAutoRefresh` 第 4 参带上「任一浮层开着」,30 秒轮询不再冲掉敲了一半的表单;
- **停用与重置密码不能共用一张底部**:§10 那条动作条只许一颗 `type="primary"`,而停用确认是
  `primary danger`。于是停用留在行内走 `confirmAction`,重置密码独立一张 Modal(新密码 + 两颗 Check)。

**2)卡头去掉重复的二级标题(§13.6)**
资产库卡头写「人物母版 / 共 10 个母版」,头顶页签写「人物母版 10」,卡底 `Pager` 写「共 10 条」,
第一张统计卡的 `hint` 再写一遍「人物 10 · 场景 6 · 声线 3」——同一句话在一屏里出现四遍。
卡头的 `title` 与 `sub` 整块删掉,只留右端视图切换器;数量交还 `Pager` 与页签角标;`hint` 换成
「点下去清空筛选,回到这一类母版的网格视图」这种只在这里才有的信息。模型管理中心是同一形状
(左栏已经选中「大模型」,卡头再来一句「大模型」):删 `title`,能力说明挂到计数的原生 `title` 上(G2)。

**3)顺着这次改动发现闸门自己有两个洞,一并补上**
- `aligncheck` 与 `symmetrycheck` 的 BASE 写死 `localhost:5173`,而那台端口上跑着**另一个项目**:
  十三页一个门牌都没量到,三个跨页集合全是空集、「最大跳动 0」,两把尺于是**空跑成绿**。
  现在两把都认 `NEX_BASE` 并且自报样本数(`ALIGN_PROBED` 底线 40、`SYM_HEADS n/13` 底线 10),
  掉到地板一律退出码 2——凡是「0 = 通过」的尺都必须报样本数,和 `FOOTER_PROBED` 同一条规矩。
- `feedbackcheck` 的 B 项靠 /users 页面上那颗常驻「保存」触发,保存搬进抽屉后它点不到东西直接抛异常
  (而 `| tail` 把非零吞了,看上去还是绿的)。改成整行点开抽屉再点抽屉底部「保存账号」;
  **点完必须把指针挪开**——那颗主按钮正对着吐司的落位带,手留在那儿就等于一直 hover,C 永远读到 `paused`。
- `footercheck` 加进 `/users` 三张浮层;行内图标按钮没有可见文案,触发器新增 `@无障碍名` 写法按 `aria-label` 找。

验证(dev 跑在 :5199 / :8010,8000 与 5173 被 nex_buddy 占着)
- 前端闸门:`classaudit.mjs` 六项全 0;`tsc --noEmit`、`npm run build` 通过。
- 探针全绿:aligncheck `ALIGN_PROBED 181` / 0 处(明暗两档)、symmetrycheck `SYM_HEADS 13/13`
  三集合单值 {273}/{109}/{1391}(明暗两档)、tableaudit 0、gridcheck 0、rhythmcheck 0、
  tagcheck 0(明暗)、btnrowcheck 413 组 0、btnclustercheck 154 簇 0、footercheck
  `FOOTER_PROBED 39 FOOTER_BAD_TOTAL 0`(加 /users 前 30)、feedbackcheck 明暗两套全过、
  gateprobe 11/11、visualcheck 0 断言 0 HTTP 失败。
- 后端 `pytest -q` 全量 **503 passed / 1 skipped**(新增 `test_user_list_filters_are_server_side`:
  三档状态筛选、`role`+`status`+`q` 叠加、counts 不随筛选变化、非法值 400)。
- 重启 dev 之后实测:点「管理员」卡 → 角色=管理员 状态=正常 → 表里 1 行 = 卡上 1、卡头「筛选出 1 / 3 个账号」;
  点「待改初始密码」(0)→ 空态「没有匹配的账号,换个关键词或清空筛选。」;`status=nope` → 400。
- 手册 12 张插图整批重拍(`helpshots.py`):上一轮删掉的开发期说明还留在插图里——
  插图是静态 PNG、不参与构建,UI 每换一次皮肤这 12 张就整批过期。
2026-11-06 01:12:21 +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 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 e5ccbe0651 内容页页头只剩一个实现:门牌卡改成「菜单同款图标 + 一级标题 + 主操作同排」,眉标删掉
症状:用户第 12 轮原话「内容页 Header 重写,只保留节点名(1 级标题)+ 描述说明。
标题前一个和左侧菜单一致的图标。右侧的主功能入口要对齐」。当时站内有两套页头
(`PageHead` 给全局页、`NodeHead` 给项目七站),七站门牌上还压着一行眉标
「项目环节 · 第 N / 7 站 · 名称」——这句话侧栏当前项、顶栏控制台、概况抽屉已经各说
一遍(R18);图标是环节名首字符自拼的色块,和侧栏那只图形只是「碰巧同类」;主操作
挂在**整块页头**的垂直中线上,而七站的职责说明有的两行有的一行,实测同一颗主按钮
在七页的 y 坐标各不相同,概览页没有动作时中线还空着一截。

做法:①`app/layout/nav.tsx` 新增 `navItemAt(pathname)`——先查 `globalNav` 精确路径、
再查 `projectModules`,把菜单项那个 ReactNode 原样交给页头,菜单与门牌读同一份图形,
物理上不可能不一致;②`components/ui/Page.tsx` 删掉 `NodeHead` 与它自带的 `moduleAt`,
`PageHead` 成为全站唯一实现:第一行 `.nex-pagehead-title`(色块图标 + `Title level=3`)
与 `ActionGroup auto={false}` 同排两端对齐,第二行 `w-full` 的 `meta` + `sub`;新增
`icon` 属性(缺省反查菜单、`null` 明确不放),不在菜单里的三页(账号 / 用户管理 /
手册)显式补 `IconUser` / `IconTeam` / `IconBook`;③`app.css` 的 `.nex-nodehead` 改名
`.nex-pagehead`,新增 `.nex-pagehead-title { min-block-size: var(--ant-control-height) }`
——主按钮的 y 由这条几何保证,不靠页面垫 margin;色块从单类扩成一族
`.nex-stat-mark` / `.nex-pagehead-mark` / `.nex-brief-mark`(32 / 32 / 20 共用一套配色
与圆角,`--nex-stat-tint` 缺省落回主色),概况抽屉那七行同步降到 20 档;④七站与规范
(R18 行、§6.5 的四层表 ③ 与那条「`NodeHead` 是 `PageHead` 的一层皮肤」)一起改写。

为什么把「对齐」写成 CSS 而不是逐个页面调:只要中线还挂在整块页头上,任何一句说明
文案变长都会把七页的按钮重新错开;第一行定高之后,改文案只会长第二行。
1440 实测 13 个内容页:门牌唯一、标题行高恒为 32、图标 32×32、主操作右缘一律 1391、
中线一律 109.0(含无动作的概览与账号);430 档主操作折到下方、无 console error。
2026-11-03 22:40:16 +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 5ce8f4a207 检查点:布局层迁入 antd 原生(Panel/Controls/grid/Input + app.css 清理) 2026-11-03 14:37:22 +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 85a95a9ba3 登录页接入常驻探针并改用 kit 用词:「页签」一词收口到页面内部
产品口径落地复查(内容页不做多 Tab / 菜单只到两级 / 页签=页面内部页面)时发现两处该修的:

1) 常驻探针压根量不到登录页:登录之后再访问 /login 会被守卫回落首页,
   第 4 条的 URL 比对只能报「路由不存在」(实测退出码 1),而默认路由表里
   干脆没有 /login。改成**登录之前**先按 逐档宽度 × 明暗把 chromeless 的
   登录页量一遍并截图,尺子检查从主循环抽成 audit() 由两处共用(同一份断言,
   不给登录页开第二条口径);/login 进默认路由表,主循环跳过它。
   实测 430 / 768 / 1440 × 明暗:断言 0、console 0、HTTP 失败 0。
2) 登录页还留着手写用词:两个 <label><span> 字段换成 FieldBlock(标签在上,
   与全站同尺),三条自己拼「描边 + 底色」的提示条换成 Notice。截图逐像素对过,
   版面没动,只是不再各写一份。

顺带把词收口:ProjectDetail 注释里的「各业务页签」改成「各业务子页」——
「页签」从本轮起只指页面内部页签(§6.4),外壳没有页签条(§6.1);
§6 表格里 Header 那一行按真实三块(折叠开关+品牌簇 / PipelineConsole / 状态+手册+主题+UserMenu)重写,
§15.2 登记探针的登录前置一趟。
2026-11-03 12:52:42 +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 34f8862cfe UI 规范补上标签章节与 React 量法:§2 写清两族胶囊的分工、--tag-* 两档挂在容器上、TagGroup 的 6px/12px、min-height 与 font-size 两个 tailwind-merge 陷阱;§3 补 Field hint 的栅格写法与「一个容器只有一个 --ctl-h 档位」;§0.5 对照表按真实签名重写并登记已废弃的英文眉标;§1.3/§8 换成 React 时代的四条探针 2026-11-02 10:51:18 +08:00
mula.liu 889c6d113a UI 规范:删掉最后一处「全局 :has 兜底」的过时说法,与 §3 的 React 现状保持一致 2026-11-01 19:48:52 +08:00
mula.liu 5288f52b86 前端去重复:抽屉三段皮肤与浮层关闭钮收进 ui/Overlay(分镜检查器改为复用常量),长文本字段高度收进 TEXTAREA_TALL;UI 规范把星号/说明文字/抽屉三条改成 React 现状并删掉已随旧 CSS 删除的全局兜底,清掉空的 components/layout 2026-11-01 19:48:04 +08:00
mula.liu e4715cf967 修复 React 迁移遗留:分镜检查器改文案用 ref 取代失效的 .sb-insp 选择器、受控勾选框补 onChange 消除只读告警、seed 回落空串保持受控、登录用户名补回 #login-user;同步用例计数 2026-11-01 19:38:59 +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