闸门跟着 antd 布局层重新校准:三处检查不再说假话

症状:布局层搬进 antd(Flex / Drawer actions / Tag)之后,四道闸里冒出一批
      「查的是老口径」的误报,逼得人想给闸门加豁免——那是要把闸门关掉的前兆。
      ① visualcheck 侧栏探针只认 .ant-menu-item-selected,可菜单折叠时高亮的是
         父级 SubMenu 标题,antd 给它的是透明底 + colorPrimary(正确长相),
         拿选中项的 controlItemBgActive 去比就必然红:430 档
         projects/13/{delivery,dispatch,timeline} 三页连续报假故障。
      ② 同一支脚本把「行高为 0」当塌陷,而 antd 的图标复位本来就把 .anticon
         写成 line-height:0(盒子由 font-size 撑开),图标一旦带上 text-* 就中枪。
      ③ classaudit 第 4 条用 \b(actions|footer)=\{ 找浮层底部动作条,
         PageHead actions(页头视图开关)和 Toolbar actions(勾选后的批量条)
         名字撞车被一起吞进来,「最后一颗必须是主行动」判到了不该管的地方。
      ④ Tailwind 词表没有 Flex 的 wrap / space-between 与 cursor 的 not-allowed,
         这三个 props 值天天出现,逐行切词分不清引号内外,只能点名放行。
做法:①探针多输出一个 kind(item / submenu),Python 侧只在 kind=item 时比色板,
        submenu 交给原有的浮层复核分支;②行高断言排除 .anticon;
      ③先定位 prop 挂在哪个元素上,只有 Drawer / Modal(含 kit 转发的 AntDrawer /
        AntModal)才算底部动作条——实测全站 25 处里受管 12 处,另 12 处归 §7 控件栏;
      ④三个词进白名单,并在注释里写清「当类名写出来仍是笔误」;
      顺带删掉临时探针 nexprobe.cjs / nexprobe.tsx(能力已并进 visualcheck),
      新增 scripts/ui/helpshots.py:手册的 12 张插图是静态 PNG,不参与构建,
      UI 每换一次皮肤就整批过期,拍摄口径(视口/dpr/主题/主角项目/先收概况)写进脚本头。
为什么:闸门报一次假,人就多写一次豁免;豁免写满,真故障就混在里面没人看。
      所以这一轮修的是检查本身的口径,而不是给页面加特例。
main
mula.liu 2026-11-03 17:02:03 +08:00
parent 5ce8f4a207
commit be07d9d712
5 changed files with 218 additions and 113129 deletions

File diff suppressed because it is too large Load Diff

View File

@ -1,20 +0,0 @@
import React from 'react'
import { renderToString } from 'react-dom/server'
import { StyleProvider, createCache, extractStyle } from '@ant-design/cssinjs'
import { Form, Input, ConfigProvider } from 'antd'
// 只渲染【没有 Form 包裹】的 Form.Item,看 vertical 样式是否存在
const App = () => (
<ConfigProvider theme={{ cssVar: true, hashed: false }}>
<Form.Item label="孤立字段" layout="vertical" style={{ width: 128 }}>
<Input />
</Form.Item>
</ConfigProvider>
)
const cache = createCache()
renderToString(<StyleProvider cache={cache}><App /></StyleProvider>)
const css = String(extractStyle(cache, { plain: true } as never))
console.log('len', css.length)
const hits = css.replace(/\s+/g, ' ').split('}').filter(r => /-vertical/.test(r))
console.log('vertical rules:', hits.length)
console.log(hits.slice(0, 6).join('\n}\n'))

View File

@ -147,6 +147,12 @@ const PROSE = new Set([
'align', 'break', 'duration', 'flex-end', 'gap', 'items', 'left', 'list', 'max',
'max-height', 'min', 'min-width', 'not', 'object', 'order', 'pointer', 'right',
'row', 'text', 'top', 'group-global', 'group-project',
/* 2026-11 布局层改用 antd Flex 后多出来的三个 props 值 / CSS 取值:
`wrap` 是 <Flex wrap> 这个布尔属性本身、`space-between` 是 justify="space-between"、
`not-allowed` 是 style 里的 cursor。Tailwind 里对应的事各有正名
(flex-wrap / justify-between / cursor-not-allowed),这三个词当类名写出来必然是笔误,
但作为 props 值天天出现,逐行切词分不清引号内外,只能在这里点名。 */
'wrap', 'space-between', 'not-allowed',
])
const dead = []
@ -183,9 +189,10 @@ for (const hit of stray) console.log(`ICON ${hit}`)
console.log(`${stray.length} 处绕过登记表的图标 import(只许 ${path.relative(FRONTEND, REGISTRY)})`)
/* ── 第 3 条:裸 <button> 收口到自定义表面族 ──────────────────────────────
每条都要写清「为什么不是 antd Button」;新增文件先进这张表,别先写裸按钮。 */
每条都要写清「为什么不是 antd Button」;新增文件先进这张表,别先写裸按钮。
Controls.tsx 曾在表里:Chip / TagChip 后来全部改由 antd `Tag` /
`Tag.CheckableTag` / `Typography.Link` 承担,裸 <button> 命中数归零,条目已删。 */
const CUSTOM_SURFACES = {
'src/components/ui/Controls.tsx': 'Chip / TagChip 的叉:胶囊与标签,高度跟同排 antd 控件对齐(--ant-control-height*),antd 无此形态',
'src/components/ui/Overlay.tsx': 'Scrim:整屏遮罩,点空白关闭;不是按钮,是命中区',
'src/components/media/MediaThumb.tsx': '版本角标 + 删除叉:压在封面上的徽标,尺寸由封面决定',
'src/components/media/AudioPlay.tsx': '走带键:三档直径 28/22/20 由音频行高决定,antd 圆钮最矮 24',
@ -295,6 +302,29 @@ function openTag(src, start) {
每条都要写理由,别用它绕过口径。 */
const FOOTER_EXEMPT = new Set([])
/**
* 第 4 条量的是**浮层底部**(规范 §10),不是所有叫 actions / footer 的 prop。
*
* 症状:`\b(actions|footer)=\{` 这个名字碰撞把 `PageHead actions`(页头那排开关)
* 和 `Toolbar actions`(勾选后浮出的批量条)也吞了进来,报出
* 「最后一颗必须是主行动」——而页头最后一颗本来就该是「收起概况」这种
* 视图开关,主行动在 `PanelHead right`。批量条的「批量删除」是**未确认的
* 行内删除**(§10:那种才用 `type="text" danger`),也不该被判成权重反了。
* 做法:先定位 prop 属于哪个元素,只有 `<Drawer actions>` / `<Modal footer>`
* (含 kit 内部转发的 `<AntDrawer>` / `<AntModal>`)才是底部动作条。
* 实测全站 25 处:Drawer 6 + Modal 5 + AntModal 1 = 12 处受管,
* PageHead 5 + Toolbar 7 归 §7 的控件栏口径管,不在这里查。
*/
const FOOTER_HOSTS = new Set(['Drawer', 'Modal', 'AntDrawer', 'AntModal'])
/** 找 `at` 这个位置被哪个 JSX 元素包着(取起点最近的那个开标签)。 */
function hostOf(src, tags, at) {
let host = ''
let best = -1
for (const t of tags) if (t.start < at && t.end > at && t.start > best) { host = t.name; best = t.start }
return host
}
const footerViolations = []
const walkFooters = (dir) => {
for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
@ -303,7 +333,11 @@ const walkFooters = (dir) => {
if (!/\.tsx$/.test(ent.name)) continue
const rel = path.relative(FRONTEND, p)
const src = fs.readFileSync(p, 'utf8')
const openTags = [...src.matchAll(/<(Drawer|Modal|AntDrawer|AntModal)(?=[\s/>])/g)]
.map((t) => ({ name: t[1], start: t.index, end: t.index + openTag(src, t.index).length }))
.filter((t) => t.end > t.start)
for (const m of src.matchAll(/\b(actions|footer)=\{/g)) {
if (!FOOTER_HOSTS.has(hostOf(src, openTags, m.index))) continue
const open = m.index + m[0].length - 1
const close = braceEnd(src, open)
if (close < 0) continue
@ -336,7 +370,7 @@ const walkFooters = (dir) => {
}
walkFooters(SRC)
for (const hit of footerViolations) console.log(`FOOT ${hit}`)
console.log(`${footerViolations.length} 处不符合浮层底部动作口径(Drawer actions / Modal footer)`)
console.log(`${footerViolations.length} 处不符合浮层底部动作口径(只查 Drawer actions / Modal footer:PageHead · Toolbar 的 actions 属 §7 控件栏)`)
/* ── 第 5 条:`import 'antd'` 只许出现在尺子、外壳与 kit 里(R8)────────────
页面一旦直接 import 组件库,主题与档位就再也收不口:换 antd 大版本、调 token、

View File

@ -0,0 +1,138 @@
"""重拍《使用手册》的 12 张插图 → frontend/public/help/*.png。
为什么需要这支脚本:插图是 `Help.tsx` 里 `<img src="/help/x.png">` 直出的**静态截图**,
不参与构建。UI 每换一次皮肤,这 12 张就整批过期——上一轮换掉绿色配色后,手册里
仍然是 10-28 拍的旧绿色 UI,用户在正文里看到的和新配色对不上,
「浅绿色标签都要处理」这句话在插图上是字面成立的。改完 UI 必须跑一次这里。
口径(改之前先读,别随手换):
· 视口 1600×1000(16:10,和现有 12 张一致),`device_scale_factor=2` 拍到 3200×2000
再用 LANCZOS 缩回 1600 宽——比直接 1x 拍清晰,且产物尺寸与旧图逐项相等。
· 主题锁 **light**:12 张彼此要一致,且浅色才是这套「标准现代」皮肤的门面。
· 拍摄主角 = 项目 12《告诉你个小秘密第2期》:已交付、12 个节点全通、4 镜头 4 合格、
117 任务、5 条导出记录、有真实剧照。空草稿项目拍出来一片 0,半程项目缺内容。
· 五个项目子页(分镜 / 调度 / 质检 / 时间线 / 导出)**先收起「项目概况」再拍**:
那条折叠区(四张统计卡 + 流程进度 12 格)在所有子页顶部都一样,不收起的话每张
构图雷同、真正要教的看板被推到首屏之外。`/projects/12/overview` 反过来要展开。
· 资产管理三张拍的是 **平台资产库**(/assets 的人物 / 场景 / 声线三页签),沿用历史选题。
用法:`.venv/bin/python scripts/ui/helpshots.py [输出目录]`
默认直写 `frontend/public/help/`;给一个目录就落在那儿,先人工过一眼再覆盖。
前置:dev `vite :5173` + 后端 `:8000` 在跑,账号 admin/admin1234。
"""
import io
import os
import sys
from PIL import Image
from playwright.sync_api import sync_playwright
BASE = os.environ.get("NEX_BASE", "http://127.0.0.1:5173")
DEST = sys.argv[1] if len(sys.argv) > 1 else "frontend/public/help"
W, H = 1600, 1000
PROJECT = 12 # 拍摄主角,见模块 docstring
# name → (路由, 是否收起「项目概况」);顺序 = 手册正文里的出场顺序
SHOTS = [
("dashboard", "/"),
("overview", f"/projects/{PROJECT}/overview"),
("model-center", "/models"),
("asset-management", "/assets"), # 人物页签(默认)
("scene-assets", "/assets"), # 点「场景」页签
("voice-assets", "/assets"), # 点「声线」页签
("storyboard", f"/projects/{PROJECT}/storyboard"),
("storyboard-inspector", None), # 分镜 + ?shot= 打开检查器
("dispatch", f"/projects/{PROJECT}/dispatch"),
("review", f"/projects/{PROJECT}/review"),
("timeline", f"/projects/{PROJECT}/timeline"),
("delivery", f"/projects/{PROJECT}/delivery"),
]
COLLAPSED = {"storyboard", "storyboard-inspector", "dispatch", "review", "timeline", "delivery"}
ASSET_TABS = {"scene-assets": "场景", "voice-assets": "声线"}
def main() -> int:
os.makedirs(DEST, exist_ok=True)
with sync_playwright() as p:
b = p.chromium.launch()
pg = b.new_context(viewport={"width": W, "height": H}, device_scale_factor=2).new_page()
login(pg)
shot_id = first_shot(pg)
for name, route in SHOTS:
if route is None: # 检查器特写
pg.goto(f"{BASE}/projects/{PROJECT}/storyboard?shot={shot_id}", wait_until="networkidle")
pg.wait_for_timeout(1800)
else:
pg.goto(BASE + route, wait_until="networkidle")
pg.wait_for_timeout(1500)
tab = ASSET_TABS.get(name)
if tab:
click_tab(pg, tab)
if name in COLLAPSED:
collapse_summary(pg)
save(pg, name)
b.close()
return 0
def login(pg) -> None:
"""主题必须在 goto 之后写:首帧脚本读 localStorage 定底色,先写会被登录页重定向冲掉。"""
pg.goto(BASE + "/login", wait_until="networkidle")
pg.evaluate("() => localStorage.setItem('nex-the','light')")
pg.goto(BASE + "/login", wait_until="networkidle")
pg.fill("#login-user", "admin")
pg.fill("#login-pass", "admin1234")
pg.click("button[type=submit]")
pg.wait_for_url(BASE + "/")
pg.wait_for_timeout(800)
def first_shot(pg):
"""检查器要停在一镜真实数据上:镜头 id 从看板接口取,别硬编码。"""
return pg.evaluate(
"""() => fetch(`/api/projects/%d/shots/board`)
.then(r => r.json())
.then(d => (d.shots || d.items || d)[0]?.id)""" % PROJECT
)
def click_tab(pg, label: str) -> None:
"""平台资产库的大分类是页签(`Tabs`),没有 URL 参数,只能点。"""
ok = pg.evaluate(
"""(label) => {
const hit = [...document.querySelectorAll('[role=tab], .ant-tabs-tab, button')]
.find((n) => (n.innerText || '').trim().startsWith(label));
if (hit) hit.click();
return !!hit;
}""",
label,
)
print(f" 页签 {label} -> {ok}")
pg.wait_for_timeout(1200)
def collapse_summary(pg) -> None:
"""收起 ProjectDetail 的「项目概况」。ProjectDetail 在子路由间保持挂载,
所以第一张收起后其余几张进来就是收起态,这里点不到按钮是正常的。"""
btn = pg.query_selector('button:has-text("收起概况")')
if btn:
btn.click()
pg.wait_for_timeout(700)
def save(pg, name: str) -> None:
pg.wait_for_timeout(900)
pg.evaluate("() => window.scrollTo(0,0)")
pg.wait_for_timeout(250)
buf = pg.screenshot(type="png", clip={"x": 0, "y": 0, "width": W, "height": H})
im = Image.open(io.BytesIO(buf)).convert("RGB")
if im.width != W:
im = im.resize((W, int(im.height * W / im.width)), Image.LANCZOS)
path = f"{DEST}/{name}.png"
im.save(path, optimize=True)
print(f"shot {name:24s} {im.size} {os.path.getsize(path) // 1024} KB")
if __name__ == "__main__":
sys.exit(main())

View File

@ -9,7 +9,9 @@
2) 文字行高没塌成 px(无单位倍数被误写 px 时肉眼很容易漏);
3) 侧栏选中态跟着路由走(selectedKeys 没断);
4) 这一档宽度下没有元素横向捅出视口、没有被 overflow:hidden 切掉的字;
分段控件 / 页签 / 按钮 / 下拉当前值的文字必须整颗放得下(省略号也算截断)。
分段控件 / 页签 / 按钮 / 下拉当前值的文字必须整颗放得下(省略号也算截断);
桌面档(>=1024)里每颗 <ActionGroup> 必须待在同一行——同一概念的几颗按钮
被劈成两排就是没分组(`stack` 的竖排等宽除外)。
5) 请求没有 4xx/5xx——按 URL 分诊:素材文件在开发库里本来就没落盘是数据问题,
其余(接口 404、chunk 加载失败)一律算故障。
@ -104,7 +106,8 @@ PROBE = """() => {
// 窄屏侧栏是折叠的(Sider breakpoint=md),二级项不在 DOM 里而在 hover 浮层里,
// 此时 antd 把选中态打在父级 .ant-menu-submenu-selected 上 —— 这不是选中态断了。
// collapsed 一并报出去,让 Python 那边决定要不要再展开浮层复核。
const sel = document.querySelector('.ant-menu-item-selected')
const item = document.querySelector('.ant-menu-item-selected');
const sel = item
|| document.querySelector('.ant-menu-submenu-selected > .ant-menu-submenu-title');
const sc = sel ? getComputedStyle(sel) : null;
const bar = document.querySelector('.ant-layout-header') || document.querySelector('[class*=nex-header]');
@ -119,14 +122,22 @@ PROBE = """() => {
controlHeight: v('--ant-control-height'),
borderRadius: v('--ant-border-radius'),
},
menu: sel ? {bg: sc.backgroundColor, color: sc.color, text: sel.textContent.trim().slice(0, 12)} : null,
// kind=item 才是真正被选中的菜单项,能吃 antd 的 controlItemBgActive;
// kind=submenu 只是折叠态下高亮的父级标题,antd 给它的是透明底 + colorPrimary 文字,
// 这是折叠态的正确长相,拿选中项的色板去比必然误报。
menu: sel ? {bg: sc.backgroundColor, color: sc.color, text: sel.textContent.trim().slice(0, 12),
kind: item ? 'item' : 'submenu'} : null,
header: bar ? {h: Math.round(bar.getBoundingClientRect().height),
bg: getComputedStyle(bar).backgroundColor} : null,
theme: document.documentElement.dataset.theme,
collapsed: !!document.querySelector('.ant-layout-sider-collapsed'),
subSelected: !!document.querySelector('.ant-menu-submenu-selected'),
// 行高是无单位倍数:一旦 --ant-line-height-* 被写成 px,每一行文字都会塌成 1px 高
// .anticon 除外:antd 的图标复位把所有图标写成 line-height:0(实测菜单/头部/正文图标全是 0px),
// 图标的盒子由 font-size 撑开(12px 字图标实高 12px,没塌),这条断言管的是「文字行」。
// 图标一旦同时带 Tailwind 的 text-*,按 class 选元素就会把它误报成「行高塌了」。
text: [...document.querySelectorAll('.text-xs, .text-sm, .text-base')].slice(0, 12)
.filter((el) => !el.classList.contains('anticon'))
.map((el) => { const c = getComputedStyle(el);
const fs = parseFloat(c.fontSize), lh = parseFloat(c.lineHeight);
return Number.isFinite(lh) && lh < fs ? `${el.className.slice(0, 40)} fs=${fs} lh=${lh}` : null; })
@ -286,8 +297,31 @@ LAYOUT = r"""() => {
if (overflows(el)) return;
[...el.querySelectorAll('*')].some(overflows);
});
// 「同一概念的按钮组不许乱跨行」(docs/UI规范.md §7):ActionGroup 是一组按钮的**原子单位**,
// 要挪整组一起挪。这里量的是渲染结果而不是 class:同一容器里子项的垂直中心落在两条
// 水平线上 = 这组被折成两排。stack(antd 给 ant-flex-vertical)是刻意的竖排等宽,跳过;
// 只在主宽度及以上做(窄屏工具条折行是设计,桌面档折行是没分组)。
const wrap = [];
if (vw >= 1024) {
for (const el of document.querySelectorAll('.nex-action-group')) {
if ((typeof el.className === 'string' ? el.className : '').indexOf('ant-flex-vertical') >= 0) continue;
const kids = [...el.children].filter((k) => k.getBoundingClientRect().width > 0);
if (kids.length < 2) continue;
const rows = [];
for (const k of kids) {
const r = k.getBoundingClientRect();
const y = r.top + r.height / 2;
if (!rows.some((v) => Math.abs(v - y) < 8)) rows.push(y);
}
if (rows.length > 1) {
wrap.push(desc(el) + ' rows=' + rows.length + ' '
+ kids.map((k) => (k.innerText || k.tagName).trim().slice(0, 8)).join('|'));
}
}
}
return {vw, page: document.documentElement.scrollWidth, out: out.slice(0, 8),
clip: clip.slice(0, 8), disp: dispBad.slice(0, 8), trunc: trunc.slice(0, 8)};
clip: clip.slice(0, 8), disp: dispBad.slice(0, 8), trunc: trunc.slice(0, 8),
wrap: wrap.slice(0, 6)};
}"""
@ -308,6 +342,8 @@ def audit(page, route: str, width: int, theme: str, problems: list[str], *,
problems.append(f"{width}/{theme}{route}: display utility 被组件样式盖掉 {o}")
for o in lay["trunc"]:
problems.append(f"{width}/{theme}{route}: 控件标签被省略号截断 {o}")
for o in lay["wrap"]:
problems.append(f"{width}/{theme}{route}: 同一概念的按钮组被拆成两排 {o}")
if probe["theme"] != theme:
problems.append(f"{width}/{theme}{route}: data-theme={probe['theme']}")
for k, val in probe["root"].items():
@ -327,12 +363,14 @@ def audit(page, route: str, width: int, theme: str, problems: list[str], *,
if menu_required:
if not probe["menu"]:
problems.append(f"{width}/{theme}{route}: 菜单没有选中项")
elif probe["menu"].get("kind") != "item":
pass # 折叠态:父级标题只证明 selectedKeys 指对了分支,色板比不了,交给下面浮层复核
else:
want_bg, want_fg = MENU_SELECTED[theme]
if probe["menu"]["bg"] != want_bg or probe["menu"]["color"] != want_fg:
problems.append(f"{width}/{theme}{route}: 侧栏选中态 {probe['menu']['bg']}"
f"/{probe['menu']['color']},应为 {want_bg}/{want_fg}")
if probe.get("collapsed") and probe.get("subSelected"):
if probe["menu"] and probe["menu"].get("kind") == "submenu":
# 折叠态下只验到父级还不够:selectedKeys 传错时父级照样会亮。
# 展开浮层,确认这一条路由对应的二级项真的在里面被选中。
try: