diff --git a/reports/NEX阶段8实施-2026-11-07.md b/reports/NEX阶段8实施-2026-11-07.md new file mode 100644 index 0000000..d308526 --- /dev/null +++ b/reports/NEX阶段8实施-2026-11-07.md @@ -0,0 +1,462 @@ +# NEX Design System · 阶段 8 实施报告(四项已批准决策) + +- 分支 / 提交链:`main`,`4411d22`(阶段 0–3)→ `24513a9`(4)→ `bc5d1bc`(5)→ `3e86b28`(6)→ `5753177`(7)→ 本轮**按批准顺序四项各一次提交 + 两笔收尾**: + `1227003`(D16)→ `0b9ea0a`(N16)→ `ae4dd7f`(D17/N7)→ `687bf5a`(N14)→ `7d844a9`(重拍 12 张手册插图)→ 本报告 +- NEX 子仓库 `nex_design_system/`(独立 git 仓库)两笔:`63e36ec`(`04` §8.1/§8.2 命名断点登记 + 窄屏降级范式,随 N16)、`c703f14`(`08` §2 可排序条目的键盘移动方式,随 N14) +- 授权来源:审计报告 `reports/NEX设计审计与改造计划-2026-11-07.md` 之后的四项逐条批准 + - **D16** 修复 kit `Tag` 吞 `className` + - **D17 / N7** 移动端导航采用抽屉式 Drawer + - **N14** 分镜拖拽排序增加键盘替代 + - **N16** NEX 增加命名断点登记机制 +- 上游文档:`nex_design_system/`(独立 git 仓库,NEX 0.1.1)、`docs/UI规范.md`(项目级权威)、`docs/NEX-对照与例外.md`(映射与例外登记) +- 时间:2026-11-07 开工,最终树复跑与两笔收尾提交落在 11-08 00:13–00:19(文件名的日期取开工日,与阶段 4–7 同一命名法) +- 环境:dev `http://127.0.0.1:5199` · 后端 `:8010` · preview `:4173` · 探针项目 PID=10 · 登录 `admin` +- 项目**没有** `lint` / `test` 脚本;可用命令只有 `npm run dev` / `build` / `typecheck` / `preview` 与 `scripts/ui/` 下的探针(见 §6)。 + +--- + +## 0. 结论摘要 + +| 项 | 目标 | 改动面 | 关键验证 | +|---|---|---|---| +| **D16** | `Tag` 的 `className` 被 `cn()` 吞掉 → 全站 10 处站点空转 | 5 源文件 +35/−14 + `classaudit` 新增第 8 闸 TAGSKIN | 932 颗标签逐站点 diff:**46 处差异,全部落在预期站点** · 11 道常驻探针 11/11 · `visualcheck` 120 状态 | +| **N16** | 命名断点没有机器闸;NEX 侧缺「主阶梯放不下时」的登记出口 | `classaudit` 新增第 9 闸 BP + NEX 04 §8 增补登记机制 | 裸 `max-[...]` = 0 · 5 把登记尺子各自只有 1 个使用者(10 档在册)· 闸反证(写坏→红→复绿 `BP_PROBE_OK 10/10`) | +| **D17 / N7** | <768 常驻 64px 图标轨与汉堡语义重叠,且吃掉正文 64px(D17 溢出 `sw203>cw170` 的来源) | 抽屉式导航(<768 不渲染 Sider)+ kit `Drawer` 加 `placement` + 探针抽屉内复核选中态 | 430 顶栏溢出归零 · 四档导航均可达 · 120 状态 | +| **N14** | 排序只有鼠标(HTML5 拖拽 + 表格两颗按钮),键盘/读屏用户做不到 | `⌥↑` / `⌥↓` 移动当前镜头,复用同一条 `move()`;快捷键登记在 `aria-keyshortcuts` + 一份 `sr-only` 说明 + 使用说明页(**没用 `title`**,见 §4.3 第 4 条) | 新写的 `sortcheck`:**改后 PASS 0(明暗各 6 组)/ HEAD 反证 FAIL 14** · 11 道常驻探针 11/11 · `visualcheck` 120 状态 · 卡脚零新增按钮(224 档实测会劈行) | + +**一句话结论**:四项里只有 D16 会动到视觉,而且动的是一枚此前**根本看不见**的角标;其余三项都是把已经存在但没人管的规则钉成闸、把只有鼠标的入口补上第二条路。 + +--- + +## 1. D16 · kit `Tag` 的 `className` 不再被吞 + +### 1.1 修改文件清单 + +| 文件 | 变化 | 属于 | +|---|---|---| +| `frontend/src/components/ui/Status.tsx` | `cn('nex-tag', …)` 末尾并入 `className`;prop 文档改成「能力边界表 + 200ms 读数坑」 | kit | +| `frontend/src/pages/ModelCenter.tsx` | 「默认」标签 `className="bg-primary border-primary text-on-primary font-bold"` → `className="font-bold"`(皮肤三族点不亮,且 §2.1 已废止语义铺底) | 页面 | +| `frontend/src/pages/project/Review.tsx` | `` → ``(弱化那一半本来就无效,等宽走登记过的色调) | 页面 | +| `frontend/src/pages/project/Storyboard.tsx` | 撤掉卡头 `` 包装,`flex-none` 直接写回 ``;注释同步 | 页面 | +| `frontend/src/app/layout/PipelineConsole.tsx` | wrapper **保留**,注释从「D16 修好后可撤」改成「为 display 族保留,`flex-none` 那半边已可进 Tag」 | 外壳 | +| `scripts/ui/classaudit.mjs` | 新增第 8 闸 **TAGSKIN**:给 kit 标签写皮肤类 = 判违规 | 探针 | +| `docs/UI规范.md` | 新增 **§1.1.1**(未层壳与 utility 的真实边界 + 实测能力矩阵 + 读数坑);§15.1 闸表 7→8 | 规范 | +| `docs/NEX-对照与例外.md` | §6 D16 行改判「已修」并写清机制与站点口径;§7 变更记录 | 规范 | + +### 1.2 修改前后差异 + +| 观测点 | 改前 | 改后 | +|---|---|---| +| `` / `` | 形参收了但没并进 `cn()` → **10 处站点全部空转**(同文件 `Badge`/`TagGroup` 都并了) | 落到 DOM;`className` 放最后,`tailwind-merge` 保留后写者 | +| 分镜卡缩略图角标「已生成 / 缺关键帧」 | `absolute bottom-2 left-[7px]` 没生效 → 角标参与文档流、落在 `overflow-hidden` 盒子外,探针 `visible=False`(**看不见**) | `position:absolute` 生效,角标贴回缩略图左下,`visible=True` ← 本轮**唯一**真实视觉新增 | +| 分镜卡头状态标签 | `flex-none` 靠外层 `` 才生效 | `flex-none` 直接写在 `` 上,wrapper 撤掉(卡宽/栅格/标题行数不动) | +| 总控台项目状态标签 | 外层 `` 两个类都要靠 wrapper | `flex-none` 可进 Tag,但 `max-md:hidden` 属 `display`、被未层壳独占 → **wrapper 必须留** | +| 模型中心「默认」 | `bg-primary border-primary text-on-primary font-bold`:三族皮肤写上去是空转,读者以为它是实心蓝块 | 只留 `font-bold`(400→700),显眼的是字重;语义色仍由 `tone="accent"` 那颗圆点承担 | +| 审核页视觉模型名 | `className={MUTED_MONO}`:等宽 + 弱化都读不到 | `tone="mono"` → 真的 SFMono;弱化那半废弃 | +| 时间线「配音」标签 ×13 | `ml-*` 空转(0px) | `ml-4px` 生效 | + +### 1.3 修改原因:机制真相比「漏并一个变量」更值钱 + +1. **确实是漏并**:`Status.tsx::Tag` 收了 `className` 却没进 `cn()`,页面写了不报错、探针也量不出差别(它本来就是空转),所以这个缺陷从 2026-11 一直活到本轮。 +2. **修好之后「utility 大面积失效」是假一半真一半**——上一轮的调查结论被本轮实测证伪: + - **假的一半**:antd `.ant-tag` 带 `transition: all .2s`。脚本 `el.className += ' ml-2'` 之后**立刻** `getComputedStyle`,读到的是**过渡起始值**:同一颗标签立即读 `margin-left = 0px`,等 700ms 再读 `= 8px`。margin / flex / font-weight 全部被这条误判成「输了」。 + - **真的一半**:`styles/index.css:55` 的 `@import "./app.css"` **不带 layer**(有意为之:自绘表面必须压得住 antd)。未层声明优先于任何 `@layer`,所以 `.nex-tag.ant-tag` 独占的 13 族属性页面 utility 压不动。 + - 正确的测法两条:同位置 `cloneNode` 插一个带同类名的**新节点**(首帧无过渡),或 CDP `CSS.getMatchedStylesForNode`(顺带能读层名)。 +3. **能力矩阵(明暗两档结论一致)**——它现在就是「页面能给标签写什么类」的口径,写进 §1.1.1: + - ✅ 生效:`ml-*` `mt-*` `mb-*` · `flex-none` `flex-1` · `font-mono` `font-bold` `italic` · `absolute`+`inset-*` · `truncate` + - ❌ 被壳吃掉:`mr-*`/`me-*` · `hidden` 与 `max-:hidden` · `bg-*` · `text-*`(色与字号) · `rounded-*` · `p-*`/`px-*`/`pe-*` · `leading-*` · `min-h-*` · `gap-*` · `max-w-*` · `whitespace-*` · `overflow-*` +4. **为什么不顺手把 `.nex-tag` 降进 `@layer`**:那等于重排「自绘皮肤 vs antd vs utility」三方的胜负关系,影响面是全站所有 `.nex-*` 表面,属「大规模 CSS 重写」(授权 §八 明确排除)。本轮只做:**让 `className` 说话,同时说清它能说到哪一句**。 + +### 1.4 规范符合性说明 + +| 条目 | 结论 | +|---|---| +| NEX 05 §3(组件属性契约) | 组件形参收下的 prop 必须真的生效——这是缺陷修复,不是新增规范 | +| `docs/UI规范.md` §1.1 层叠三条 | 补 §1.1.1 记第三方(未层 `app.css`),文档与实测对齐 | +| `docs/UI规范.md` §2.1(标签只有一档中性底,语义靠圆点) | 顺站点清理了两处「页面自造皮肤」残留(ModelCenter 实心蓝、Review 弱化等宽),方向与 §2.1 一致 | +| AGENTS.md 强制规则 9「不滥用局部覆盖」 | 本轮把三处**看起来像**局部覆盖的写法(`bg-primary`、`MUTED_MONO`、包 span)收敛回 `tone` / 说明原因,覆盖数量净减 | +| AGENTS.md 强制规则 3「禁止硬编码设计值」 | 未新增任何字面色值/尺寸;`left-[7px]` 是既有代码原样保留 | +| 例外登记 | `docs/NEX-对照与例外.md` §6 D16 改判「已修」,wrapper 保留的一处理由写进代码注释与 §7 | + +### 1.5 质量验证 + +**项目实际存在的命令,逐条执行**(没有 `lint` / `test`,不虚构): + +| 命令 | 结果 | +|---|---| +| `npm run typecheck` | ✅ 通过 | +| `npm run build`(= `tsc --noEmit && vite build`) | ✅ 通过;仅既有告警 `Some chunks are larger than 1200 kB`(与本项无关,见 §7) | +| `node scripts/ui/classaudit.mjs` | ✅ **8 道闸全 0**(含新增第 8 闸 TAGSKIN) | +| `npm run preview` + `:4173` | 服务在跑(4173 已 LISTEN),像素探针跑在 dev `:5199` 工作区上 | +| 常驻 11 道像素/源码探针(`tagcheck` `tableaudit` `gridcheck` `rhythmcheck` `btnrowcheck` `aligncheck` `symmetrycheck` `footercheck` `btnclustercheck` `feedbackcheck` `gateprobe`) | ✅ `EXIT[]=0` × 11,末行 `GATEPROBE_OK 11/11` | +| `scripts/ui/visualcheck.py`(15 路由 × 4 视口 1440/768/576/430 × 明暗 = **120 状态**) | **120 状态全绿**:15 路由 × 4 视口(1440 / 768 / 576 / 430)× 明暗 = 120 张截图,`=== 断言(0 条)===`、`=== HTTP 失败(0 条)===`、`=== console(0 条)===`;阈值与判据一字未改(原始基线 84 状态的超集) | +| `NEX_LABEL=before` 标签指纹(`git stash push` 取改前面貌)+ 逐站点 diff | 932 颗标签,**46 处差异**,站点分布:`/models` 2、`/projects/10/overview` 2、`/projects/10/timeline` 14、`/projects/10/storyboard` 28;变化字段只有 `own/pos/ml/fs/fw/vis/x/y`,**无一处皮肤字段(bg/color/radius/padding)改动** | +| 分镜卡键盘/浮层跨阶段复跑(阶段 1/2/3 探针) | 随 11 道常驻探针一起绿(`tagcheck` 覆盖状态标签兜底、`gateprobe` 覆盖 11 条判据反证) | + +**第 8 闸 TAGSKIN 的反向验证**(§15.1 口径:没反证过的闸等于装饰): + +| 写法 | 闸的判定 | +|---|---| +| `` | 红:点名 `bg-` → background 由 `.nex-tag` 独占 | +| `` | 红:响应式 display 同样点不亮(提示「要隐藏套 span」) | +| `` | 绿(✅ 生效族) | +| `` / `style={{…}}` | 绿(不写皮肤族) | +| 注释里写 `` | 绿(块注释先剥,防假阳性) | +| `Ctlbar.tsx` 里 antd 本尊 `Tag` | 不参与扫描(它不吃这条规矩) | + +### 1.6 有代表性的前后截图 + +证据目录:`reports/ui_evidence/nex-p8/d16/`(`shots/` = 16 张成对截图,`scripts/` = 本轮用到的探针,`*.log` / `*.json` = 原始读数)。 +`before` 的取法:`git stash push -- <改动的 5 个源文件>` → 同一 dev 服务、同一 PID=10 项目、同一视口重跑 → `git stash pop`。 +每对截图截的是**同一个祖先元素**(`locator.screenshot()`,盒子尺寸两档逐一相等),因此像素可直接对: + +| 成对文件(`{light,dark}_` 各一份) | 截图对象 | 差异区(2× 设备像素) | 看点 | +|---|---|---|---| +| `*_timeline_dub_{before,after}.png` | 音轨区一条片段行(含 `ml-1` 那颗「配音」) | `bbox=(334,34,567,86)` | 标签与左侧类型名之间多出 4px(`marginLeft` 0 → 4px) | +| `*_storyboard_badge_{before,after}.png` | 分镜卡缩略图 `[data-shot-preview]` | `bbox=(14,256,126,300)` | 「已生成」角标此前掉出缩略图盒子被 `overflow-hidden` 裁掉(探针 `vis` False)→ 现在贴在左下角 | +| `*_models_default_{before,after}.png` | 模型卡标题行(含「默认」标签) | `bbox=(167,12,222,39)` | `font-weight` 400 → 700;底色/描边/文字色两张逐像素相同(皮肤族本来就点不亮) | +| `*_review_qwen_{before,after}.png` | 审核页质检标签行(含 `qwen/…`) | `bbox=(472,2,776,52)` | 换成等宽(`tone="mono"`);标签宽度 145 → 161(等宽字更宽),字号与颜色不变 | + +> 上一版调查留下的 12 张截图里,`models_default_tag` 那对**逐字节相同**(截图框没罩住目标标签,等于没有证据),本轮改用元素级截图重取;`timeline_dub` 第一版也取错了实例(页面上有 22 颗文字含「配音」的标签,只有 7 颗带 `ml-1`,选择器已按 `nex-tag-tint` 钉准)。这两条教训写进 §7。 + +### 1.7 尚未解决(D16) + +1. **`.nex-*` 自绘表面仍整体在层外**:本轮只处理了标签一族。全站还有多少表面属于「写了 utility 但压不动」,要按 §1.1.1 的方法逐族量,属皮肤体系改造(授权 §八 排除大规模 CSS 重写)。 +2. **`PipelineConsole` 的 wrapper 仍在**:`display` 族压不动,撤它要先把 `.nex-tag` 皮肤降进 `@layer`。已在代码注释与 §6 写明条件。 +3. **`Dispatch.tsx:405,457` 的 `ml-2` / `ml-1` 未做前后对照**:PID=10 该项目没有 stale 心跳行,探针拿不到这两颗标签;同类 `ml-1` 已由 `/projects/10/timeline` 14 处实测覆盖,不外推为「已验证」。 +4. **build 的 chunk>1200kB 告警**:既有问题,与本轮无关,未处理。 + +--- + +## 2. N16 · 断点治理装上机器闸(NEX 侧补登记出口) + +> 提交:本项目 `0b9ea0a`;NEX 子仓库 `63e36ec`(`nex_design_system` 是独立 git 仓库,上游规范改动单独提交)。 + +### 2.1 修改文件清单 + +| 文件 | 变化 | 属于 | +|---|---|---| +| `scripts/ui/classaudit.mjs` | +135 / −1:新增第 9 闸 **BP**(以 `@theme` 的 `--breakpoint-*` 为唯一真相对账四处);同时修回被本轮写闸时顶掉的 `dead.length`(第 1 闸曾静默不影响退出码) | 探针 | +| `docs/UI规范.md` | §4「登记断点」的**复核口径**从「`grep -rn "max-\[" frontend/src` 必须为 0」改写为五条判据 + 指向第 9 闸;§15.1 闸表 8→9 并补第 9 行口径 | 规范 | +| `docs/NEX-对照与例外.md` | §2.4「§8 不允许私有断点」行改为「机制已被 NEX 采纳,且四条口径全部机器对账」;§5 **N16** 状态;§7 变更记录 | 规范 | +| `nex.config.yaml` | 新增 `breakpoints_registered`(1400/1240/1080/720/620 五档 + 各自唯一使用者);`custom_breakpoints: forbidden` → **`registered_only`**(原注释与阶段 7 的登记出口自相矛盾);`ui_gates` 注释 7→9 道子闸 | 配置 | +| `nex_design_system/docs/04-layout-system.md`(子仓库 `63e36ec`) | +32 行:**§8.1 命名断点登记出口**(有名字 / 有唯一使用者 / 有实测 / 有对账四条)+ **§8.2 专业工作区窄屏降级范式**(<768 导航只留一个入口)。§8.2 是本轮 D17/N7 抽屉化的上游依据 | 上游规范 | + +前端源码(`.tsx` / `.css`)**一字未改**:`git show --stat 0b9ea0a` 只有 4 个文件,`frontend/` 命中 0。 + +### 2.2 修改前后差异 + +| 观测点 | 改前 | 改后 | +|---|---|---| +| 「私档断点」的防守方式 | 一句人肉 `grep`;写 `max-[900px]:flex` 编译得过、像素也对,只有人眼能发现 | 第 9 闸判据①直接红并点名到文件行 | +| 断点变体名写错(如 `max-agnt:`) | Tailwind **不报错**,只是这一档压根不生成规则 → 静默失效 | 判据②红:用了 `@theme` 里不存在的名字 | +| 登记尺子的使用面 | 「一把尺子只有一个使用者」只写在 `UI规范.md` §4 表里,靠自觉 | 判据③红:0 使用者(死尺子)或 ≥2 个文件共用(口径漂移)都点名 | +| 探针 `BP` / `BPORDER` 与 `@theme` 同步 | 靠人记;漏一档时 `wantDisplay` **静默返回 `null`**,断言悄悄不跑,比报错更难查 | 判据④红:每档必须在两张表里同名同值,且 `BPORDER` 必须等于「按 px 从大到小」 | +| `.css` 里的 `@media` | 不在治理范围(阶段 7 只收了页面) | 判据⑤红:`(max\|min)-width: Npx` 的 N 必须是登记值 | +| 第 1 闸(死类名)退出码 | 被本轮初版的 `process.exit(...)` 表达式顶掉 → **红也不影响退出码** | 已还原,九项之和 = 退出码 | +| `nex.config.yaml` 自述 | `custom_breakpoints: forbidden` 与阶段 7 已开放的登记出口冲突 | `registered_only`,并把五档尺子连使用者一起登记 | + +### 2.3 修改原因 + +阶段 7 的收口把 5 把裸 `max-[…]` 改成了 `--breakpoint-*` 命名变体,但**归名之后「登记」这件事本身没有任何机器防守**:真相分散在 `styles/index.css` 的 `@theme`、`docs/UI规范.md` §4 的表、`scripts/ui/visualcheck.py` 的 `BP`/`BPORDER` 三处,全靠人同步。三处里最坏的一种失同步不是报错而是**静默**:往 `@theme` 加一档却忘了 `visualcheck.py`,`wantDisplay()` 对该档返回 `null`,那一条断言就不跑了——绿灯比红灯更容易骗人。N16 的批准内容就是「NEX 增加命名断点登记机制」,落地拆成两半:**上游**要有「主阶梯放不下时怎么办」的出口(NEX 04 §8.1),**本项目**要有能对账的闸(第 9 闸),两者缺一就退回「两份人写的表」。 + +### 2.4 规范符合性说明 + +| 规范条目 | 结论 | +|---|---| +| NEX `04-layout-system.md` §8(主阶梯 576/768/992/1200) | **COMPLIANT**:五档与 antd Grid 全等,第 9 闸判据②保证页面用的名字都来自 `@theme` | +| NEX 04 §8「不允许私有断点」 | **ADAPTED**(E9)+ 现在**可机器对账**:项目保留 5 把登记尺子(px 一字未改),代价是把「例外」升级成有判据的登记制;已回写上游 §8.1 | +| NEX 04 §8.1(本轮新增) | 四条口径本项目全部满足且有闸:名字(`--breakpoint-*`)/ 唯一使用者(判据③)/ 实测(§4 表「归到相邻档位会回退什么」列)/ 对账(第 9 闸) | +| `AGENTS.md` 强制规则 3「禁止硬编码设计值」 | 断点属布局尺寸,第 9 闸把它从「口头规矩」变成 CI 可跑的判据 | +| `AGENTS.md` 强制规则 9「不滥用局部覆盖」 | 本轮零局部覆盖:只加闸与文档 | +| 授权边界(§六「不批量替换 CSS」/§八「不大规模 CSS 重写」) | 遵守:无一个 `.tsx`/`.css` 改动,无像素变化 | + +### 2.5 质量验证 + +| 命令 | 结果 | +|---|---| +| `node scripts/ui/classaudit.mjs` | ✅ **九道闸全 0**,`EXIT=0`(末行:`0 处断点越界(第 9 闸:10 档在册 / 5 把登记尺子 / 裸 max-[…] 与未登记名与文档-探针失同步)`)。本轮 D17/N7 改完源码后**复跑仍九道全 0** | +| `reports/ui_evidence/nex-p8/n16/scripts/gate_bp_proof.py`(第 9 闸反证,§15.1 口径) | ✅ `BP_PROBE_OK 10/10`:9 种坏写法逐条红且点名 + 1 条「反向的反向」合法复用(`AgentConsole.tsx` 同文件 11 处复用必须放行) | +| `npm run typecheck` | ✅ 通过(零源码改动,作为回归哨兵跑) | +| 像素 / 路由回归 | 本项**不需要**:改动面不含 `frontend/`,渲染产物逐字节相同(`vite build` 产物只有 hash 与 chunk 名不受影响)。同分支的 120 状态全绿见 §3.5 | +| 反证残留检查 | `gate_bp_proof.py` 先对 5 个待改文件做快照,每条用例**进入前和结束后各还原一次**,最后再还原并复跑要求 `exit=0`;跑完 `git status` 与 `classaudit` 复跑均为绿 | + +### 2.6 有代表性的前后截图 + +**本项无截图,且这是准确的而不是缺失**:N16 的改动面是 `scripts/` + 文档 + `nex.config.yaml`,`frontend/` 零改动,浏览器渲染不出任何差别。它留下的可核对产物是源码级三件: + +| 产物 | 路径 | 作用 | +|---|---|---| +| 第 9 闸反证脚本 | `reports/ui_evidence/nex-p8/n16/scripts/gate_bp_proof.py` | 10 例(9 红 1 绿)逐条点名,证明闸不是装饰 | +| 闸的基线输出 | 上表 `classaudit` 九行 | 「10 档在册 / 5 把登记尺子 / 0 命中」= 治理后的稳态读数 | +| NEX 侧条文 | `nex_design_system/docs/04-layout-system.md` §8.1 / §8.2(子仓库 `63e36ec`) | 上游拿到登记出口与窄屏降级范式,下个项目不必再谈一次例外 | + +### 2.7 尚未解决(N16) + +1. **闸管不了语义**:判据只覆盖「名字存不存在、有没有登记、有没有人用、探针认不认」。「该不该在 1240 这一档换排布」仍是 R9 的人的判断——闸绿不等于断点选得对。 +2. **「唯一使用者」是当前的、不是永久的口径**:如果将来两处确实需要同一个 720 阈值,第 9 闸会红,届时要么改判据成显式多使用者登记(并解释为什么不合并成一把尺子),要么接受合并。这条边界已在 `UI规范.md` §4 写明,但没有自动裁决。 +3. **`MAIN_LADDER` 常量硬碰 antd 五档**:antd 升级若换档(例如 `xxl` 变体改名),判据②④会红——这是预期的失败方式(闸会响),但修哪一侧需要人判,闸不替人决定。 +4. **`@media` 判据⑤只看 `max|min-width` 的像素值**,不查 `orientation` / `prefers-reduced-motion` / `hover` 这类非宽度媒体特性,后者目前无治理需求。 + +--- + +## 3. D17 / N7 · <768 导航改抽屉,顶栏胶囊溢出归零 + +> 用户批准:**D17 / N7 移动端导航采用抽屉式 Drawer**。上游依据 = NEX `04-layout-system.md` §8.2「专业工作区的窄屏降级:导航在同一视口内只留一个入口」(§2.1 已记:条文随 N16 的 `63e36ec` 落到子仓库)。 + +### 3.1 修改文件清单 + +| 文件 | 变化 | 属于 | +|---|---|---| +| `frontend/src/components/ui/Overlay.tsx` | kit `Drawer` 新增 `placement`(默认 `right`:站内既有 **10 处** `` 调用点一个都不传,行为与像素逐字不变)与 `flushBody`;默认宽按左右分档(左 `min(288px, 100vw−48px)` / 右 `DRAWER_WIDE`);`styles.body` 只在 `flushBody` 时给 `padding:0` | kit | +| `frontend/src/app/layout/AppSider.tsx` | 一个文件拆三个导出:`AppNavMenu`(菜单本体)/ `AppSider`(≥768 常驻侧栏,**撤 `breakpoint="md"`**)/ `AppNavDrawer`(<768 左抽屉);`SIDER_WIDTH=224`(L47)、`SIDER_COLLAPSED_WIDTH=64`(L49) 提为具名导出供抽屉与探针引用 | 外壳 | +| `frontend/src/app/App.tsx` | `narrow = Grid.useBreakpoint().md === false`(`undefined` 当桌面,防首帧闪);`navOpen` state + 换页 `useEffect` 自动关;`{!narrow && }`(L187);`{narrow && }`;向 Header 传 `narrow/navOpen/onToggleNav` | 外壳 | +| `frontend/src/app/layout/AppHeader.tsx` | **同一颗汉堡换语义**:≥768 折叠侧栏(原文案)、<768 开合抽屉(打开/关闭导航菜单);`wide` 纳入 `narrow`(窄屏不许隐这颗);图标改按「导航现在露没露」选;`aria-expanded` 只在抽屉形态给 | 外壳 | +| `frontend/src/app/layout/PipelineConsole.tsx` | 项目名 `<768` 恢复收缩权:`max-md:min-w-0 max-md:flex-[0_1_auto]`(D17 那 33–38px 溢出的直接修复) | 外壳 | +| `scripts/ui/visualcheck.py` | 探针补 `sider` 字段;`NAV_DRAWER_WIDTH = 224`;窄屏菜单断言改「**真点一下汉堡** → 量 `.ant-drawer-content-wrapper` → 选中态底色必须等于桌面同一份 token → Esc 必须关」;新增 `in_nav()` 修掉 `NAV_ROUTES` 存模板 vs 已解析路径的失配(菜单断言覆盖 **3 → 10 条路由**) | 探针 | +| `docs/UI规范.md` | §6 外壳表:AppHeader 行补双形态语义、AppSider 行去 `breakpoint` 并写撤掉的理由、**新增 `AppNavMenu` / `AppNavDrawer` 两行**;§15 第 3 条改为「先问 `probe.sider` → 窄屏真点汉堡 → 量 content-wrapper」+ `NAV_ROUTES` 失配事故登记;§4 `insp-sm` 行同步阶段 8 复核结论 | 规范 | +| `docs/NEX-对照与例外.md` | §2.4 `<768 降级` **DEFERRED → ADOPTED**;§3 同步;§5 **N7 → ✅ 已采纳**;§6 **D17 → 已修**;§7 变更记录 | 规范 | +| `nex.config.yaml` | shell 段新增 `sidebar_narrow: drawer`(带实现行号);`sidebar_width/collapsed_width/content_padding/content_max_width` 的行号引用校正到 47/49/187/188/189 | 配置 | + +### 3.2 修改前后差异(全部为实测读数,来源见 §3.5) + +| 观测点 | 改前 | 改后 | +|---|---|---| +| <768 的导航入口 | **两个**:Sider 的 `breakpoint="md"` 自动收成 64px 图标轨,汉堡同时还在,且 label 写着「展开导航菜单」——点它只把图标轨撑回 224,一滚动/一换页又被 breakpoint 收回去 | **一个**:不渲染 Sider,汉堡是唯一入口,label 打开/关闭导航菜单,`aria-expanded` 跟随开合 | +| 430 正文盒宽 | 366(= 430 − 64 图标轨;扣 12×2 内距可用 342) | **430**(+64) | +| 576 正文盒宽 | 512 | **576** | +| 430 顶栏流水线台(D17) | 盒子 `x=100 w=172`,内容 `sw 203–205` → **溢出 33–38px**;项目名从 `x=63/68` 起画(比胶囊左沿还偏左 32–37px),尾部箭头画到 `x=305`(胶囊右沿 272)——名字读得完,但它不在自己那颗胶囊里 | `ovf=0`;名字 `x=113` 落在胶囊内,`w 183 → 84–86` 走省略号 + tooltip | +| 430 表格溢出(`tableaudit`) | **9 张**违规,容器 292 | **6 张**,容器 356;顺带修好「队列状态」行高 127→40 与两颗「人工审核」的横向溢出 | +| 576 表格溢出 | 6 张,容器 438 | 6 张(同一批老问题),容器 502,每条溢出量正好 −64 | +| 768 / 1024 / 1440 | — | **逐字相同**:`navprobe` 几何 5 行一致、`tableaudit` 768 输出两态一致、1440 的 `domdiff` DOM 几何全等(仅 `name.w 178↔183` 这类字体竞态) | +| 汉堡图标 | `collapsed ? Expand : Collapse` | `navShown ? Collapse : Expand`;≥768 时 `navShown === !collapsed`,与改前同值;<768 抽屉关着时画的正是改前那颗 `Expand` → **顶栏像素没动**(`document.fonts.ready` 后 before/after 强差 **0 px**,1440 与 768 都是) | +| 抽屉里的菜单 | 不存在 | 与侧栏**同一个组件**、同一个 224 宽、同一份选中态 token;最长那两条(「任务调度中心」「模型管理中心」6 字)不折行不裁字(`drawercheck` 的 `menu-fit` 判据逐条量 `scrollWidth ≤ clientWidth`) | + +### 3.3 修改原因 + +批准的是「采用抽屉式 Drawer」,但改前三条实测决定了它必须怎么改: + +1. **入口重复**:图标轨 + 汉堡同屏,汉堡点下去的效果还会被 `breakpoint` 收回——语义重叠且行为自相矛盾,这是 NEX 04 §8.2 明令消掉的状态。 +2. **64px 是真金白银的正文宽度**:430 档正文 366、576 档 512,抽屉化后各自拿回 64px。 +3. **D17 的溢出正是被这 64px 逼出来的**:`PipelineConsole` 那颗 Button 内容居中,装不下就两端一起往外溢;容器宽 +64 后 430 档溢出归零。剩下的 `flex-none` 副作用单独修(第 5 个文件)——手机档没有散文可吃(`cur ` 后同一支跑出 **FAIL 10 条**(430/576 各 5 条:没有「打开导航菜单」按钮、Enter 开不出抽屉、点不到、`aria-expanded` 两侧都不成立),`drawercheck-HEAD-反证.txt` 留存 | +| `scripts/ui/tableaudit.py` 逐视口前后对照(`NEX_WIDTH=` × 1440/768/576/430 × 两态 = 7 份日志) | 1440 两态 0 违规;768 两态**逐字相同**;576 违规 6→6、溢出量各 −64;430 违规 **9→6**(`tableaudit/ta-*.txt`) | +| 像素疑点定性(≥768 两档) | `scripts/domdiff.py`:1440 两态 DOM 几何**逐字相同**,768 仅项目名宽度 178↔183 抖动;`scripts/fontwait.py`:Google Fonts `Noto Sans SC` 异步 swap,落地 2s 后 `document.fonts.status` 仍 `loading` → 之前 24k/19k 强差是**字体竞态 + 活动角标数据漂移**;`scripts/pxnoise.py`:先 `await document.fonts.ready` 再拍 → before/after 顶栏强差 **0**(1440 与 768),同状态自差 1440=295(角标呼吸)/ 768=0 | +| 常驻 11 道像素/源码探针(`gridcheck` `rhythmcheck` `tagcheck` `btnrowcheck` `aligncheck` `symmetrycheck` `footercheck` `btnclustercheck` `feedbackcheck` `tableaudit` `gateprobe`) | ✅ `EXIT=0` × 11,末行 `GATEPROBE_OK 11/11` | +| 阶段 1/2/3 回归(状态标签兜底、三处热区、浮层层级) | 随常驻探针绿;`tagcheck` 覆盖 `title` 兜底,`gateprobe` 覆盖层级与 11 条判据反证 | + +### 3.6 有代表性的前后截图 + +证据目录:`reports/ui_evidence/nex-p8/d17/`。`before` 取法同 §1:`git stash push -- <5 个源文件>` → 同一 dev、同一 PID=10、同一视口重跑 → `pop`。 + +| 目录 | 内容 | 看点 | +|---|---|---| +| `shots-before/` vs `shots-after/` | 4 视口 × 明暗 × {整页, 顶栏} 成对,`shots-after/` 多两张 `*_drawer.png` | **768 / 1440 两档成对像素相同**(形态未变);**576 / 430 两档**页面向左扩 64px、顶栏胶囊从「名字溢到胶囊外」变成「胶囊内省略号」 | +| `shots-after/430-{light,dark}-drawer.png`、`576-{light,dark}-drawer.png` | 抽屉打开态(左贴边、宽 224、选中项高亮) | 明暗两主题的选中态底色/前景各一张,肉眼可对 `MENU_SELECTED` 两色 | +| `shots-b2/`、`shots-a2/`、`shots-after2/` | 字体竞态复核轮(`await document.fonts.ready` 之后重拍) | 顶栏成对像素在这几轮里对不上,正是 §3.5 那条定性的原始素材 | +| `scripts/px768/{1440,768}-{1,2}.png` | 同状态自差标定(两张同一时刻的顶栏) | 1440 自差 295 px(活动角标呼吸)、768 自差 0 → 说明「两态强差 = 0」的读数下限在哪 | +| `scripts/px768/dom-{before,after}.json`、`scripts/{before,after}.json` | 逐元素几何读数 | 1440 全等;576/430 差异只出现在 `content` 宽度与流水线台内部 | + +### 3.7 尚未解决(D17 / N7) + +1. **430 档顶栏读不出完整项目名**:现在是省略号 + hover/focus tooltip,全名要点汉堡开抽屉或点概况才见得到。要在手机档也读全名,得给流水线台排一次「名字 vs 百分比 vs 箭头」的优先级(改布局,本轮授权外)。 +2. **两套导航状态不共享**:≥768 的 `nex.sider.collapsed` 按人持久化,<768 的 `navOpen` 刻意不持久化(每次进来都是关着)。这是形态差异的必然结果还是遗漏,留给下轮判断。 +3. **768 档维持原样**:仍是 224 常驻侧栏 + 正文 544,汉堡只做折叠(成 64 图标轨)。平板横屏要不要也走抽屉是产品决策,本轮**没有**擅自扩到 768。 +4. **`tableaudit` 剩下的 6 条(768 / 576 / 430)是表格自身的窄屏排布问题**,抽屉化只是把容器放大 64px,根因(列宽、行内动作簇)没动,属 P2 批量整改范围(授权 §八 排除)。 +5. **汉堡的图标与文案在窄屏是两个动词**:抽屉开着时图标画 `Collapse`(读作「收起」),`aria-label` 说「关闭导航菜单」。方向一致、读屏念 label,接受现状,未新增图标族。 +6. ~~**`frontend/public/help/*.png` 12 张待重拍**~~ → **已做**:收尾用 `scripts/ui/helpshots.py` 重拍 12 张并**单独提交** `7d844a9`,不混进本项。看板插图里能看到 D16 之后才真的落进画面的那枚「已生成」角标——这是「文档插图与线上行为不许对不上」这条口径的例行动作,不是本项的新问题。 + +--- + +## 4. N14 · 分镜排序的键盘替代(`⌥↑` / `⌥↓`) + +### 4.1 修改文件清单 + +| 文件 | ±行 | 改了什么 | +|---|---|---| +| `frontend/src/pages/project/Storyboard.tsx` | +110 / −32 | `move()` 回传 `Promise`;新增 `moveByKey()`、模块级 `refocusShotCard()` 与两个常量;window keydown 加一条 Alt 让位判据;`ShotCard` 加 `onMove` prop 与 `Alt+↑/↓` 分支;看板分支外面包一层片段并落一条 `sr-only` 说明。**其中 26 行只是随片段包裹整体缩进两格(grid 容器 + 那段 258px 注释 + `` 调用块),非语义改动**(`git diff -w` 后本文件 +84 / −6) | +| `frontend/src/pages/Help.tsx` | +2 / −2 | 「分镜与脚本」的操作步骤补一句不用鼠标怎么走;页内快捷键清单 `Notice` 增 `⌥↑` / `⌥↓` 一行(并注明 Windows / Linux 是 `Alt`) | +| `docs/UI规范.md` | +16 / −2 | §13.3 ⑤ 反馈预算**两条 → 三条**(新增「结果播报跟着能不能看见落点判」);G3 补「热区不是按钮时快捷键挂在哪」 | +| `docs/NEX-对照与例外.md` | +5 / −4 | §2.8「§2 焦点与键盘」行状态与证据更新;**§5 N14 行 ⏸ 待议 → ✅ 已采纳**;§6「阶段 1–3 交付项」行的「N14 除外」改为指回阶段 8;§7 加一行变更记录(本文件 §5 第 2 条自己定的规矩:反向修订被采纳后必须改 §5 + 加 §7) | +| `nex_design_system/docs/08-accessibility-responsive.md`(子仓库 `c703f14`) | +10 | §2 新增五条(键盘移动方式 / 焦点留在被移条目 / 边界不许静默 / 反馈不对称 / `aria-keyshortcuts` 与集中登记)——**NEX 子仓库单独提交**,不在本项目提交里 | +| `nex.config.yaml` | **未改** | 本轮不动任何布局尺寸,配置里没有需要跟着改的数 | +| `reports/ui_evidence/nex-p8/n14/**` | 新增 | 专项探针、HEAD 反证、11 道常驻探针原始读数、两轮 `visualcheck` 日志、成对截图(该目录已 gitignore,本机留存) | + +### 4.2 修改前后差异 + +**① `move()` 从「什么都不返回」变成「回传成没成」**——这是让调用方能报结果的最小改动: + +```diff +- if (at < 0 || target < 0 || target >= rows.length) return +- await run('调整顺序', () => api.post(...)) ++ if (at < 0 || target < 0 || target >= rows.length) return false ++ return run('调整顺序', () => api.post(...)) // run() 本来就 return true/false +``` + +三个既有调用点(分镜表的「前移」「后移」、拖拽落点)全部写成 `void move(...)`,**一个字都没改**,行为也没变:`run()` 早就返回布尔了,只是以前没人接。 + +**② 新增键盘路径 `moveByKey()`**(`Storyboard.tsx:857`): + +| 情况 | 改前(键盘) | 改后 | +|---|---|---| +| 焦点在卡片上按 `⌥↓` | 什么都不发生(`Alt+↓` 落到 window 的「方向键切镜」上,选中镜头跳到下一张,镜序不动) | 这一镜真的下移一位;右下角吐司「镜头 2 已后移到第 3 位」;焦点跟着走到新位置 | +| 第一张卡按 `⌥↑` | 同上(选中态乱跳) | 顺序不动,吐司「镜头 1 已经在第 1 位,无法继续前移」 | +| 鼠标拖拽 | 能改镜序,无吐司 | **一字未改**,仍然无吐司(见 §4.3 第 3 条) | +| 分镜表的「前移 / 后移」两颗按钮 | 本来就键盘可达 | 未改 | + +**③ 焦点归还**:`refocusShotCard()` 用 rAF 最多找 8 帧。改前若不做这一步,实测按下第二下 `⌥↓` 时 `document.activeElement` 已经回到 ``——列表整体重排把卡片重挂了,键盘用户按第二下**没有任何落点**,等于「只能移一格」。 + +**④ 键位不再被 window 抢走**:卡片内 `preventDefault + stopPropagation`,window 侧再补一条 `if (ev.altKey && (ArrowUp|ArrowDown)) return` 兜底(焦点不在卡上时 `⌥↑↓` 什么都不做,而不是悄悄变成「切镜」)。改前这两条都没有:`Storyboard.tsx:1128-1129` 的 `j/k/↑/↓ → goShot(±1)` 会先吃掉方向键。 + +**⑤ 可达性属性**:卡片新增 `aria-keyshortcuts="Alt+ArrowUp Alt+ArrowDown"` 与 `aria-describedby="shot-move-hint"`,说明文字全站只写**一份** `sr-only` 节点(`UI规范.md` G3 的口径,见 §4.3 第 4 条)。`aria-label` 逐字未动(「打开分镜详情:镜头 N」),阶段 2 那条口径与 `visualcheck` 里对卡片的定位都不受影响。 + +**⑥ 视觉差异**:卡片、卡脚、列数、间距、顶栏、侧栏**零变化**——看板分支里新增的那个 `

` 是 `sr-only`(绝对定位,不进网格、不参与 `gridcheck` 的列宽计算)。唯一的版面新增是操作后右下角那颗吐司,那是本项要的东西本身。 + +### 4.3 修改原因 + +1. **阶段 2 只把卡片做到「点得开」,没做到「移得动」**。审计里 N14 的原文是「08 §1/§2 未覆盖 HTML5 拖拽的键盘替代」——当时判定 ⏸ 待议的理由是「改排序交互属产品决策」,用户批准后这条就不再有借口。 +2. **为什么不新增卡脚按钮**:最省事的方案是在卡脚「文案 / 重生成 / ⧉ / 🗑」那一行后头再加两颗 ↑↓,但那行在 224 档实测会劈成 2+1(正是 `btnclustercheck` 拦的形状),要它不劈就得缩按钮或加行——两者都是本轮明确排除的视觉改动。快捷键把新控件数量压到 0。 +3. **为什么拖拽不报吐司、键盘要报**(这是本轮唯一一处故意留下的不对称):拖的时候卡片跟着指针走,落点由卡片自己说;再补一句「已移到第 3 位」是 §13.3 ⑤ 那条预算里的第 ③ 句废话。键盘正相反——手没在版面上,读屏用户看到的只是列表闪了一下,「它刚从第 4 位来到第 3 位」这句话没有任何别的载体。判据因此从「输入方式要一致」改成**「用户能不能自己看见落点」**,已写进 `UI规范.md` §13.3 ⑤ 第 3 条。 +4. **为什么用一份 `sr-only` 而不是每张卡一句 `aria-label`**:G3 说快捷键「写在相关按钮的 `title` 里」,但整块热区不是按钮,挂 `title` 会让原生 tooltip 盖住卡片每一处(鼠标划过一片浮字);每张卡都在 `aria-label` 里念一遍快捷键,30 张卡就是 30 遍同样的话,那正是这套规范一直在清的那种冗余。所以:`aria-keyshortcuts` 负责机器查询、一份 `sr-only` + `aria-describedby` 负责聚焦时真念出来、使用说明页负责给人看。 +5. **播报走 `notify()` 而不是新起 live region**:`components/ui/Toast.tsx:32` 的容器本身就是常驻 `aria-live="polite"`。再造一条就是全站第二个播报通道,违反 R19 四级表面,也让两条通道互相打断。 + +### 4.4 规范符合性说明 + +| 条款 | 判定 | 依据 | +|---|---|---| +| NEX 08 §2「所有可交互元素必须能通过键盘到达」 | **COMPLIANT(本轮补齐)** | 排序这件事改前只能靠鼠标;现在键盘与鼠标是同一条 `move()` | +| NEX 08 §1「不用只有 `onClick` 的 `div`」 | COMPLIANT,未回退 | 卡片仍是阶段 2 定的 `

`,**没有**改成 `