docs(reports): 阶段 8.5 实施报告——七项逐条结果、HEAD↔工作树对照、chunk 前后与未解决清单
- 七项逐条:CSS Layer DEFERRED(零迁移 + 组织盘点)· 430 顶栏名三通道 ·
六张窄屏表逐表方案(九套窄档列)· 第 9 闸语义化(semanticcheck + 咬出的 4 类 58 条)·
导航两状态入册(代码零改 + aria-current)· chunk 分析后实施 0 处 · N14 真实读屏。
- §8 自动化总账:本仓库真实存在的命令(**没有 lint / 没有单测**)、主跑 13:40→14:19 全表、
postfix 与最终代码两轮复跑(visualcheck-120-final / tableaudit-430·1440-final /
preview-smoke-final 全 0)、84 ⊂ 120 的口径关系与「30 行打印 vs 120 张断言」的说明、
preview 代理缺 NEX_BACKEND 导致第一次冒烟红的那段(含脚本自己的 preflight 修法)。
- §8.3 HEAD 5a10bfb ↔ 工作树同尺对照:tableaudit@430 违规 6→0、@1440 日志逐字节相同、
semanticcheck 两档 58→0;软档口径未动(NAME 硬0/软40、热区候选 138、24 次走位)。
- §7 VoiceOver 实跑 13 PASS / 3 部分 / 4 待人工,**NVDA + Chrome 本机无环境未执行**
⇒ N14 = MANUAL QA REQUIRED,**阶段 8 不标记完全验收通过**。
- §9 未解决清单 17 条带编号与严重度(L-1/L-2、N-1..N-3、T-1..T-3、S-1..S-4、C-1..C-3、
AT-2′、N14)+ NEX 侧未落地 N9/N10/N12/N17;§10 交付索引与停止线(未做批量 P2 整改、
未动 Header/Sider 尺寸、未换组件库、未升技术栈、未碰后端)。
- 证据树 `reports/ui_evidence/nex-p8f/`(01–11)按仓库既有 `.gitignore:50` 不进版本库,
报告里明写它是本机路径、换机器需重跑闸。
main
parent
98ea70d74f
commit
ed85caebe8
|
|
@ -0,0 +1,615 @@
|
|||
# NEX Design System · 阶段 8.5 实施报告(响应式 UX 与质量收口 · 七项)
|
||||
|
||||
- 分支 / 提交链:`main`,基线 `5a10bfb`(阶段 8 收尾)。本轮按批准项分次提交,逐项对应 §1–§7。
|
||||
- 授权来源:`reports/NEX阶段8实施-2026-11-07.md` 之后用户对**剩余七项问题**的逐条决策(阶段 8 授权书 §1–§7)。
|
||||
七项里 5 项 APPROVED、1 项 DEFERRED(CSS Layer)、1 项「保持现状 + 写清理由」(导航状态)。
|
||||
- 上游文档:`docs/UI规范.md`(项目级权威)、`docs/NEX-对照与例外.md`(映射与例外登记)、`nex_design_system/`(NEX 0.1.1 独立仓库)。
|
||||
- 环境:dev `http://127.0.0.1:5199` · 后端 `:8010` · preview `:4173` · HEAD 对照组 dev `:5299`(worktree `/private/tmp/nexd/head-p8g`)· 探针项目 PID=10 · 登录 `admin`
|
||||
- 项目**没有** `lint` / `test` 脚本;可用命令只有 `npm run dev` / `build` / `typecheck` / `preview` 与 `scripts/ui/` 下的探针(§8.1)。
|
||||
- 证据目录:`reports/ui_evidence/nex-p8f/`(01 css-layer · 02 topbar-name · 03 tables · 04 semantic · 05 nav · 06 chunk · 07 screen-reader · 09 gates · 10 preview-smoke · 11 visualcheck)。**注意:`.gitignore:50` 的 `reports/*evidence/` 让整棵证据树不进版本库**(仓库既有策略,本轮不改),所以它是**本机路径**——提交里能看到的是本报告与 §10.1 的代码/文档;换机器要重新跑闸。
|
||||
- 硬约束(全部遵守):不动后端与数据库 · 不升级技术栈 · 不引入第二套 UI 组件库 · 不改业务流程 · 不做无关视觉重设计 · 不删自动化检查 · 表格改造全部做数据完整性回归 · 每项给文件清单与理由。
|
||||
|
||||
---
|
||||
|
||||
## 0. 结论摘要
|
||||
|
||||
| # | 项 | 决策 | 改动面 | 关键验证 |
|
||||
|---|---|---|---|---|
|
||||
| 1 | CSS Layer 治理 | **DEFERRED** | **零迁移**:只做全站样式组织盘点(`docs/UI规范.md` §1.1.2 + `01-css-layer/census.txt`);唯一局部修复是第 4 项咬出的一个**可复现缺陷**(`app.css` +11 行焦点环) | `app.css` 828→839 行 / 140→141 规则 / 198→199 分支,`@layer` 声明仍为 0、`!important` 仍为 4 且全在 reduced-motion 内(同口径复跑脚本可复现) |
|
||||
| 2 | 430 顶栏项目名 | **APPROVED** | `PipelineConsole.tsx` 一处(+53/−5,其中 25 行是决策注释):受控 `Tooltip` 提供 Hover/Focus 提示,Touch 走概况抽屉;只在 `scrollWidth` 真的溢出时才弹;**触屏档按 `matchMedia('(hover: hover)')` 根本不弹**(§2.2.1——复跑证明「抽屉展开即收回」挡不住 `mouseEnterDelay` 的 100 ms 定时器) | 430 `truncated:true` 且 **accessible name 为完整名**(CDP `getFullAXTree`);Hover/Focus/Touch/Click **四通道分档实测**(§2.2.1 表):430 触屏 `tip_visible:false` 且抽屉标题=完整名,430 桌面窄窗 Hover 与 `:focus-visible` 各自 `tip_visible:true`,768/640/900/1440 `truncated:false` ⇒ **不弹**;`stray_tooltips` 1→**[]**;顶栏子元素 x 区间未变(操作区没被挤压) |
|
||||
| 3 | 六张窄屏违规表 | **APPROVED** | 新增共享开关 `useNarrowTable()`(`components/ui/Table.tsx`)+ 9 张表逐表两套 columns(`Dashboard` `Dispatch` `Review` `Timeline` `Delivery`);宽档列**一字未改** | `tableaudit` 430:**HEAD 违规 6 张 → 工作树 0 张**,576/768 同 0;1440 输出与 HEAD **逐字节相同**(仅时间戳差异);数据完整性按 token 对账:补丁后 ⑥失踪 **3→0**、③失踪 **9→2**(两次复跑读到的都是实时耗时计时器,值每次都在变大 ⇒ 漂移不是隐藏)、②④⑤⑦ 恒 0(`03-tables/DATA-INTEGRITY.txt`) |
|
||||
| 4 | 第 9 闸语义检查 | **APPROVED** | 新增 `scripts/ui/semanticcheck.py`(1062 行 · 7 条判据 · CDP AX + 真键盘);`gateprobe` +89/−8 行反向验证;`nex.config.yaml` 登记为常驻闸门;**咬到的 4 类真缺陷全部就地修复**(`AudioPlay` `MediaLightbox` `AssetLibrary` `app.css`) | HEAD `semanticcheck` 1440 **EXIT=58**(NAME 20 / HOTSPOT 16 / TAB 16 / FOCUS 6)→ 工作树 **EXIT=0**;`GATEPROBE_OK 14/14` |
|
||||
| 5 | 导航状态治理 | **保持分离设计** | 代码零改(折叠 `useLocalStorage` / 抽屉 `useState` 维持原样),理由写进 `docs/UI规范.md` §6.2.1;顺手关掉实测发现的 AT-2(`AppSider.tsx` 补 `aria-current="page"`,+18/−5 含注释) | 折叠:reload 后 `ls="true"`、侧栏 63px;抽屉:`localStorage` 键集为空、reload 后 `open:false`;`aria-current` 三条路由 + 抽屉内**有且只有当前项**带它,菜单宽度 207 未变;折叠成图标轨时二级项不渲染(弹层展开后恢复有名)——边界已写清并登记 **S-4**(`05-nav/ARIA-CURRENT.txt`) |
|
||||
| 6 | UI chunk | **先分析 → 实施 0 处** | 零代码改动。新增测量脚本 `scripts/ui/chunkinfo.mjs`(按映射区间计字节) | 首屏 before/after(HEAD 两次 / 工作树三次构建,抖动 ≤0.25 kB):1486.24~1487.46 kB raw(**+0.9~1.2**)/ 453.87~454.45 kB gzip(**+0.4**)/ 370.90~371.58 kB brotli,增量来自第 3 项的两套列定义;首屏文件数 7 → 7(没多一个请求);13 条路由**已经全部** `lazy()`;`ui-*.js` 1187.8 kB 是 rolldown 自动分组,不是本项目的手工分包决策 |
|
||||
| 7 | N14 真实读屏 | **MANUAL QA REQUIRED** | 零代码改动(键盘操作与「前移 / 后移」按钮原样保留)。产出真实 AT 会话记录:`07-screen-reader/`(149 条 VoiceOver 实播报 + 环境取证 + 24 行记录表 + 人工复测脚本) | VoiceOver + Safari 18.3 + macOS 15.3 **实跑**:13 步 PASS、3 步部分通过(新缺陷 AT-1 图标字形名外泄)、4 步待人工;**NVDA + Chrome 本机无 Windows 环境,未执行** ⇒ 见 §7 |
|
||||
|
||||
**一句话结论**:七项里没有一项需要动布局、动业务流程或动技术栈;真正改变屏幕的只有第 3 项(窄屏 <992 的表格重排,宽档逐字节不变)和第 2 项(顶栏多出一层只在截断时出现的提示)。收口阶段被自己的复跑闸揪出两处「改完还在」的缺陷——触屏 Tooltip 幽灵气泡(§2.2.1)与 ③⑥ 两张表漏并的数据(§3.4)——两处都在本轮内改成最终修法并用同一把探针复跑归零。第 4 项把「源码字符串齐全但辅助技术读不到」这一整类缺陷变成了会红的闸,并且在第一天就咬出 4 类 58 条真实缺陷——全部就地修好,退出码回到 0。
|
||||
|
||||
**验收状态:阶段 8 不能标记为完全验收通过。** N14 的真实读屏验收只完成了 VoiceOver 一档的一半(NVDA 未执行、⌥↑/⌥↓ 在 AT 下的播报未复听),本轮按授权书 §7 明记 **MANUAL QA REQUIRED**,不宣称通过。
|
||||
|
||||
---
|
||||
|
||||
## 1. CSS Layer 治理 — 决策 DEFERRED
|
||||
|
||||
### 1.1 现状:全站样式怎么组织
|
||||
|
||||
| 入口 | 行数 | 层归属 | 内容 |
|
||||
|---|---|---|---|
|
||||
| `styles/index.css` | 220 | 声明层序 `@layer theme, base, components, antd, utilities` | Tailwind `theme.css`→`theme` 层、`preflight.css`→`antd` 层、`utilities.css`→`utilities` 层;`@theme` 块 1 个(Token 出口)、`@utility` 2 条(`scrollbar-slim` / `scrollbar-none`)、`@custom-variant light` |
|
||||
| `styles/app.css` | **839** | **整文件未分层**(`@import "./app.css"` 不带 `layer`) | 141 条规则 / 199 条选择器分支:132 条含 `.nex-*`(其中 4 条是 `.ant-btn:has(> .nex-…)` 这类给 antd 收口的)、40 条纯 `.ant-*` 覆写、18 条元素级复位、9 条全局伪类。`@layer` 声明 **0** 条,`@media` 1 处,`@keyframes` 2 组,`!important` **4 处且全部落在 `@media (prefers-reduced-motion)` 内** |
|
||||
|
||||
口径与全量输出可复跑:`NEX_SRC=<文件> NEX_LABEL=<标签> .venv/bin/python /private/tmp/nexd/csscensus.py`(剥 `/* */` → 按花括号配对逐条取选择器 → 逗号拆分支;同时命中 `.nex-` 与 `.ant-` 只计 `.nex-` 一次),改前/改后同口径对照见 `reports/ui_evidence/nex-p8f/01-css-layer/census.txt`。
|
||||
|
||||
### 1.2 由此得出的层叠优先级(这是**现状设计**,不是意外)
|
||||
|
||||
未分层的 `app.css` 优先于**所有**分层声明——包括 Tailwind 的 `utilities` 层。实际后果有两条,一条是我们一直在用的,一条是坑:
|
||||
|
||||
1. **在用**:`.nex-*` 自绘表面因此稳定压过 utility 类,`theme/antd.ts → applyRootVars → @theme` 的 Token 才能被局部皮肤直接引用而不需要 `!important`。全站 `!important` 只有 4 处,全在减动效分支,说明这套「未分层皮肤」在实操里没有靠提权续命。
|
||||
2. **是坑**:反过来 **`max-md:hidden` 这类 display 工具类点不亮 `.nex-*`**(`.nex-tag.ant-tag{display:inline-flex}` 未分层 ⇒ 优先级更高)。这条已经被写成注释钉在 `PipelineConsole.tsx` 里,并被阶段 8 的 CDP 实测证实过一次。迁移到 `@layer components` 会让这 132 条规则的相对顺序整体反转——**影响面 = 全站**。
|
||||
|
||||
### 1.3 为什么 DEFERRED(三条依据,按批准书 §1「仅在存在可复现缺陷时局部修复」)
|
||||
|
||||
| 依据 | 读数 |
|
||||
|---|---|
|
||||
| 没有缺陷堆积 | 120 状态像素回归 + 13 道常驻闸门全绿;`!important` 只有 4 处且语义正当(减动效),没有「靠提权打补丁」的症状 |
|
||||
| 收益不可测量 | 迁移能换来的是「层叠可解释」,但本轮找到的唯一层叠类缺陷(§1.2 第 2 条)**已经用注释 + 一处 `:has()` 局部修复收口**;剩余收益要靠改 199 条分支去换,风险/收益倒挂 |
|
||||
| 会撞上别的批准项 | 第 3 项的两套 columns、第 2 项的 Tooltip 都依赖现有皮肤的优先级形态。同一轮里既重排表格又重排层叠,出问题时无法归因 |
|
||||
|
||||
**结论:DEFERRED 保持**。不迁 `app.css`、不引入新层、不批量重写 CSS。规范登记落点:`docs/UI规范.md` §1.1.2(含上表与「何时值得重启这项」的触发条件)。
|
||||
|
||||
### 1.4 本轮唯一动 CSS 的地方(可复现缺陷,属第 4 项咬出的 FOCUS)
|
||||
|
||||
`frontend/src/styles/app.css` +11 行:`.ant-btn:has(> .nex-file-input:focus-visible) { outline: 2px solid var(--ant-color-primary); outline-offset: 2px }`。
|
||||
症状:Tab 停在「上传素材 / 导入脚本」这类整块上传按钮上,**屏幕上焦点环完全看不见**(`semanticcheck` FOCUS 硬档,明暗各 3 处)。根因是热区靠一层 `opacity:0` 的 input 铺满按钮实现,而 46 行那条把描边交回 antd token 的 `:where(...):focus-visible{outline:none}` 与 41 行的兜底描边同特异性、位置在后,连这颗透明 input 唯一的一圈描边也一起吃掉了。做法是把环改画在**看得见的按钮**上,颜色/粗细/offset 与 41 行既有兜底一致;用 `:has(> :focus-visible)` 而不是 `:focus-within`,否则鼠标点一下也会描边。未新增层、未新增 `!important`、未新增 Token 之外的颜色字面量。
|
||||
|
||||
### 1.5 未解决(登记不隐藏)
|
||||
|
||||
- **L-1**:`.nex-*` 未分层导致 `max-*:hidden` 对自绘表面失效,目前靠「写注释 + 换写法」规避。彻底解法是把 `app.css` 归入 `components` 层并逐条复核 132 条规则的相对顺序,属独立一轮(估 1 个改动轮 + 全量 120 状态回归)。
|
||||
- **L-2**:`preflight.css` 被放进 `antd` 层是历史决定(让 antd 复位与自身组件同层),语义上更该在 `base`。同样属 L-1 那一轮一起判。
|
||||
|
||||
---
|
||||
|
||||
## 2. 430 顶栏项目名称 — 决策 APPROVED(单行省略号 + 完整名称提示)
|
||||
|
||||
### 2.1 先量清「缺的是哪一条」
|
||||
|
||||
批准书要求四条:Hover、Focus、Touch、完整名保留在辅助技术名称里,外加「不许挤压顶栏操作区」。
|
||||
把 HEAD 放到 430 视口逐条量(`02-topbar-name/before-430-dark.json`):
|
||||
|
||||
| 通道 | HEAD 实测 | 结论 |
|
||||
|---|---|---|
|
||||
| 单行省略号 | `name_w=86 / scrollW=178`、`lines=1`、`text-overflow:ellipsis`、`white-space:nowrap` | **本来就有**,不需要新增 |
|
||||
| AT 可读全名 | CDP `getFullAXTree`:`role=button name="跨界斗地主 · 大漠客栈二番局 83%"`,`accessible_name_includes_full=true` | **本来就有**(名字本身在 DOM 里,只是被 `overflow:hidden` 裁掉) |
|
||||
| Hover | `tip_on_hover={text:"跨界斗地主 · 大漠客栈二番局", opacity:"1"}` | **本来就有**(`Typography.Text ellipsis={{tooltip}}`) |
|
||||
| **Focus** | **`tip_on_focus=null`** | **缺这一条**——antd 的 `ellipsis.tooltip` 只认鼠标,键盘 Tab 到胶囊上时屏幕上没有任何地方能读完这个名字 |
|
||||
| 顶栏未被挤压 | `content_overflow=0`、`doc_scrollW=430=vw`、四颗子元素 x 区间 `[16,36] [52,84] [100,272] [288,414]` | **本来就没挤**,改后必须逐字节守住 |
|
||||
|
||||
**所以这一项真正的缺口是键盘那一格**,不是「没有省略号」也不是「没有 tooltip」。按批准书「不得为了形式统一改动已验证布局」,落点选在**已有的那颗胶囊组件**(`app/layout/PipelineConsole.tsx`,它就是 project switcher),而不是新建一层提示或改 `AppHeader`。
|
||||
|
||||
### 2.2 改法(`PipelineConsole.tsx` +53/−5 行,其中 25 行是决策注释)
|
||||
|
||||
- `Typography.Text` 的 `ellipsis={{tooltip}}` 换成**受控 `Tooltip`**:`trigger={['hover','focus']}`、`open={nameTip}`。
|
||||
- **只在真的截断时才弹**:`nameTruncated()` 在悬停/聚焦那一刻现量 `scrollWidth - clientWidth > 1`,不引 `ResizeObserver`、不给 Header 增加测量节点。名字读得完还飘一层同样的字是噪音。
|
||||
- **Focus 只认键盘**:`onFocus` 里 `matches(':focus-visible')` 为真才弹;鼠标点击胶囊(要开抽屉)不会在背后挂一层提示。`onBlur` 与 `Escape` 关闭。
|
||||
- **Touch 通道**:手机档点这一下本来就是「项目概况」的唯一入口,而抽屉标题 `ProjectBriefDrawer` 就是完整项目名——这条不改,只在注释里把它写成契约的第三条腿。
|
||||
- **本轮自己引入、复跑时才发现没修干净的缺陷**:触屏点胶囊会同时唤起 Tooltip 和概况抽屉,抽屉盖住提示、提示却留在背后。第一版修法(`useEffect(() => { if (briefOpen) setNameTip(false) }, [briefOpen])`)在 14:14 的数据完整性复跑里**没通过**,最终改法见 §2.2.1。
|
||||
|
||||
#### 2.2.1 复跑打脸:「抽屉一开就收提示」挡不住触屏气泡(14:20 最终修法)
|
||||
|
||||
复跑读数(`03-tables/DATA-INTEGRITY.txt` 上一版 B 段):`stray_tooltips: ["跨界斗地主 · 大漠客栈二番局"]`。
|
||||
按事件序列重测(`02-topbar-name/p85_tip.py`,430 + `has_touch` + `is_mobile`):
|
||||
|
||||
| 时刻 | 实测 |
|
||||
|---|---|
|
||||
| 事件顺序 | `pointerover:touch → pointerdown → pointerup → **mouseover** → focus → click` |
|
||||
| `+300ms` | `aria-expanded=true`(⇒ `briefOpen` 到得了组件、effect 确实执行了),但 `.ant-tooltip` **没有** `ant-tooltip-hidden` |
|
||||
| `+1600ms` | 同上;**Esc 关掉抽屉 +2.0s 之后气泡还在** |
|
||||
|
||||
根因不是 effect 没跑,是**顺序**:antd Tooltip 的 `mouseEnterDelay` 默认 0.1s,触屏点按产生的那条兼容 `mouseover` 排了个 100ms 的「打开」定时器,它落在 click(→ `briefOpen` → 收提示)**之后**,把提示又顶开;手指不会离开按钮 ⇒ 永远没有 `mouseleave` ⇒ 再也没有下一次收口。
|
||||
|
||||
**改法:按输入能力收口,不按事件顺序打补丁。** `showNameTip()` 先看 `matchMedia('(hover: hover)')`,没有悬停能力的设备根本不弹这层提示(`PipelineConsole.tsx:166-169`);用 `hover:hover` 而不是 `pointer:coarse`,混合设备插上鼠标就还有提示。键盘档那条 `briefOpen` effect 保留(Enter 开抽屉时身后的提示该收),鼠标与键盘代码路径一字未改。三条通道从此各管各的输入设备:**Hover 归 Tooltip、Focus 归 Tooltip(`:focus-visible`)、Touch 归概况抽屉标题**。
|
||||
|
||||
四通道复测(`02-topbar-name/TOUCH-FIX-VERIFY.txt` + `p85_tip3.py`/`p85_tip5.py`;`tip_visible` = 存在没有 `ant-tooltip-hidden` 的 `.ant-tooltip`):
|
||||
|
||||
| 通道 | 环境 | 动作 | `truncated` | `tip_visible` | 完整名称抵达处 |
|
||||
|---|---|---|---|---|---|
|
||||
| Touch | 430 触屏 | 点名字 | true | **false**(缺陷消失) | 抽屉标题「跨界斗地主 · 大漠客栈二番局」 |
|
||||
| Hover | 430 桌面窄窗 | 悬停名字 | true | **true** | Tooltip 正文 = 完整名称 |
|
||||
| Focus | 430 桌面窄窗 | Tab 到胶囊(`fv=true`) | true | **true**;Enter 开抽屉→false;Esc 关抽屉后焦点仍在胶囊,再按 Esc→false | 同上 |
|
||||
| Hover/Focus | 768 / 640 / 900 / 1440 | 悬停 / Tab | **false**(三档同测均 false) | false | 名字整条读得完,不飘同样的字=不是噪音 |
|
||||
| Mouse click | 1440 / 768 | 点胶囊 | false | false | 抽屉照常打开(业务交互未变) |
|
||||
|
||||
同一份 B 段探针在 14:22 的最终代码上复跑:`stray_tooltips: []`。截图 `02-topbar-name/AFTER-430-keyboard-closed.png` = 430 键盘档最后一步:既无气泡也无抽屉。
|
||||
|
||||
### 2.3 改后实测(`02-topbar-name/after-*.json` + 同名 PNG,明暗各拍 Hover/Focus)
|
||||
|
||||
| 视口 | `truncated` | Hover | Focus | blur 后残留 | 顶栏子元素 x 区间 | `content_overflow` |
|
||||
|---|---|---|---|---|---|---|
|
||||
| 430 dark | **true**(86/178) | ✅ 全名 | ✅ **全名(本轮新增)** | `tip_after_blur=null` ✅ | `[16,36] [52,84] [100,272] [288,414]` **与 HEAD 相同** | 0 |
|
||||
| 430 light | true | ✅ | ✅ | null ✅ | 同上 | 0 |
|
||||
| 768 dark | false(178/178) | 不弹 | 不弹 | null | 与 HEAD 相同 | 0 |
|
||||
| 1440 dark | false | 不弹 | 不弹 | null | 与 HEAD 相同 | 0 |
|
||||
|
||||
截图 10 张:`name-before-430-dark-{hover,focus}.png`、`name-after-{430-dark,430-light,768-dark,1440-dark}-{hover,focus}.png`。
|
||||
「不挤压操作区」的判据不是肉眼看的:顶栏四颗子元素的 x 区间逐条与 HEAD 对齐,`btn_scrollW==btn_clientW`(胶囊自身内部也无溢出)。
|
||||
|
||||
### 2.4 规范符合性
|
||||
|
||||
- 批准书 §2 四条全部满足(Touch 那条的最终载体是概况抽屉标题,不是 Tooltip——见 §2.2.1),且**没有新增视觉**:430 与 768/1440 的静态截图除提示层以外逐像素相同(第 8 项 120 状态回归中 1440/768 两档与基线同图)。
|
||||
- 未新增 `--nex-*` 变量、未新增 Token 之外的颜色、未新增组件库依赖(`Tooltip` 走 kit 已有的 antd 出口)。
|
||||
- `title` 上那句「流程进度 83% · 已完成 10/12 个节点 · 当前节点:…(点击展开项目概况)」保持不变——它是**进度**的抵达通道,与名字的省略号提示是两件事,不合并。
|
||||
|
||||
### 2.5 未解决
|
||||
|
||||
- **N-1**:430 顶栏在**项目名特别长**(>200px 额度)时省略比例更高,靠 `title` + Tooltip 兜住;如果后续产品要把「当前节点」也塞进 430 顶栏,得重新量一次额度,这一轮的结论不能外推。
|
||||
- **N-2**:Tooltip 的 `placement="bottomLeft"` 在最窄档会向左上折返(antd 自动翻转),本轮实测 430 不触发;换更窄(<380)视口需复测。
|
||||
- **N-3**:`canHover()` 之后,**纯触屏 + 外接键盘**(如 iPad + 蓝牙键盘)Tab 到胶囊时不再有 Tooltip,完整名称只剩「点按开抽屉」与辅助技术可访问名称两条通道。收窄是有意的,但本机没有该硬件,这条只按 `matchMedia` 分支推断、**未实机验证**,随 §7 人工脚本一起补。
|
||||
|
||||
---
|
||||
|
||||
## 3. 六张窄屏违规表格 — 决策 APPROVED(逐表方案,九张在册)
|
||||
|
||||
### 3.1 根因
|
||||
|
||||
§13.2 那套列宽预算是按 1440 那把尺子算的(全宽表容器 **1118**)。同一份 `columns` 搬到窄屏,容器只剩
|
||||
**430→356、576→502、768→462、992→670**,而定宽列合计 400–902 不变 ⇒ 两种坏法:长文列被挤成 **0 宽**(成本台账「取值」列实测只剩 **14px**),或整张表拖一条横向滚动条(430 上去回滑一条成本记录 = 没有这条记录)。
|
||||
HEAD@430 `tableaudit`:**违规 6 张表**(`03-tables/head-tableaudit-430.log`,`EXIT=6`),横向溢出最大一条 **546px**。
|
||||
|
||||
### 3.2 总开关:`useNarrowTable()`,换列定义不换 DOM
|
||||
|
||||
`frontend/src/components/ui/Table.tsx` 新增 `useNarrowTable()` = `Grid.useBreakpoint().lg === false`(<992)。页面写 `columns={narrow ? 精简列 : 宽档列}`。
|
||||
|
||||
- **为什么是 992**:侧栏 224 + 正文左右 48 之后,992 视口的表容器实测 **670**,是全站定宽预算放得下的最窄一档;992 以下只剩 502 / 462 / 356,而 **768 那一档比 576 还窄**(侧栏未折叠,正文被压到 462),所以三档窄屏共用一套精简列,不按 576/768 细分。
|
||||
- **为什么不用 CSS `max-lg:` 显隐**:要换的是**列定义**(少几列、格子合成几行),不是显示状态。两套 columns 只有一份在渲染,辅助技术才不会朗读到藏在 DOM 里的列(这条同时被第 4 项的 ARIA 判据支持)。
|
||||
|
||||
### 3.3 九张表逐表方案(宽档列一律未改)
|
||||
|
||||
| # | 表 | 文件 | 选的方案(不统一,按数据特点) | 窄档列宽 | 行高 |
|
||||
|---|---|---|---|---|---|
|
||||
| ① | 项目列表 | `Dashboard.tsx` | 复用**已验证的项目卡片**,卡/表边界从 `max-sm` 推到 `max-lg` | 走卡片 | — |
|
||||
| ② | 分镜任务清单 | `Dispatch.tsx` | 动作 Tag + 预估成本并入镜头行第 2 行,说明第 3 行 | 40/176/140 | 83 |
|
||||
| ③ | 任务执行明细 | `Dispatch.tsx` | 9 列 → 3 列;状态与 stage 码进元信息行 | 148/128/80 | 83 |
|
||||
| ④ | 审核留痕 | `Review.tsx` | 时间、类型·审核人、镜头合进首格三行 | 132/80/144 | 77 |
|
||||
| ⑤ | 时间线版本 | `Timeline.tsx` | 版本号并入名称行、元信息第 2 行;宽档 `minWidth` 保留 | 144/84/128 | 59 |
|
||||
| ⑥ | 成片记录 | `Delivery.tsx` | 规格/时长/大小第 3 行,耗时+校验和进 `title`;**缩略图保留**(唯一视觉凭证 + 预览入口) | 224/132 | 84 |
|
||||
| ⑦ | 生成记录 | `Delivery.tsx` | #/类型/镜头/供应商进首列(重试次数 >1 才追加),成本/时长/时间右列 | 124/144/88 | 81 |
|
||||
| ⑧ | 计费明细 | `Delivery.tsx` | 标识首列 / 数量·单价中列 / 金额·时间右列 | 124/136/96 | 59 |
|
||||
| ⑨ | 成本台账 | `Delivery.tsx` | 维度 + 取值合并 / 金额 + 记录数右列 | 244/112 | 59 |
|
||||
|
||||
方案分布对照批准书 §3 给的六个选项:**优先级列显示 + 次要列隐藏并格**(②③④⑤⑦⑧⑨)、**长文本完整内容提示**(全部长文列 `Clamp` + 原生 `title`)、**卡片式记录**(①——站内已有成熟卡片,不新造)、**行内操作合并**(⑥⑨ 右列收成一颗主操作 + `title` 兜住次要项)。
|
||||
**没有一张表用「横向滚动」当唯一答案**,也没有一张表只是把容器改宽。⑧⑨ 开发库无数据、探针看不见,用 `page.route` 伪造 `/api/projects/*/costs` 量出来的:改前 ⑨「取值」列 **14px**、⑧ 溢出 **456**。
|
||||
|
||||
窄档长文列下限 **≥120px**(宽档 ≥200):窄档容器只有 356,200 会挤死动作列;120 是实测「中文两行还能读出主干」的最窄值,低于它必须靠 `Clamp` + `title` 兜完整内容。行高预算仍 **≤84px**(3 行 × 22),⑥ 那条 `mt-0.5` 从 86 回到 84 就是这么来的。动作列宽度按 §13.2 第 3 条公式实测:成片「预览 66 + 下载 40 + gap 8 + 内边距 16 = **132**」,估的 120 会折两排。
|
||||
|
||||
### 3.4 「数据没失踪」是量出来的,不是保证的
|
||||
|
||||
探针 `/private/tmp/nexd/p85_verify.py` A 段(读数 `03-tables/DATA-INTEGRITY.txt`):同一张表在宽档与 430 各加载一次,把宽档每格正文切成 token 集,逐条问「这个 token 在窄档还在不在」。**在**的判据 = 仍出现在可见正文里 **或** 出现在某一格的 `[title]` 完整内容提示里(`Clamp` 折行与 `title` 是 §13.2 已批准的口径)。
|
||||
|
||||
| 表 | 宽档行数 | token 数 | 首轮仍在正文 | 首轮进 `title` | 首轮失踪 | 补丁后失踪(14:14 / 14:22 两次复跑一致) |
|
||||
|---|---|---|---|---|---|---|
|
||||
| ② 分镜任务清单 | 14 | 203 | 203 | 0 | **0** | **0** |
|
||||
| ③ 任务执行明细 | 61 | 1021 | 717 | 226 | **9** | **2**(仍是漂移,见下) |
|
||||
| ④ 审核留痕 | 33 | 995 | 995 | 0 | **0** | **0** |
|
||||
| ⑤ 时间线版本 | 1 | 11 | 11 | 0 | **0** | **0** |
|
||||
| ⑥ 成片记录 | 3 | 78 | 51 | 24 | **3** | **0** ✅ |
|
||||
| ⑦ 生成记录 | 43 | 7954 | 7954 | 0 | **0** | **0** |
|
||||
|
||||
补丁后 ③ 的 `still_visible` 从 717 涨到 **789**(+72 个 token 正是「追加状态中文 + stage 码」补回来的那批),`in_full_hint` 226 不变。剩下 2 条失踪在 14:14 与 14:22 两次复跑里分别是 `["955630.4s","959869.9s"]` 与 `["956252.9s","960492.3s"]`——**每次读数都在变大**,所以它们是实时耗时计时器,不是被隐藏的数据(陷阱 ①)。`03-tables/DATA-INTEGRITY.txt` 存的是最终代码那一次(14:22,含 `canHover()` 收口后的 B 段 `stray_tooltips: []`)。
|
||||
|
||||
两个真实缺口与修法(这是本轮后半段唯一新增的两处业务代码改动):
|
||||
|
||||
| 表 | 缺什么 | 怎么补 | 为什么这么放 |
|
||||
|---|---|---|---|
|
||||
| ③ | 宽档「任务」列第二行的**类型中文 + stage 码**(`配音 · voiceover`、`资产处理 · asset`、`时间线合成 · compose`、`质检 · quality_check`、`调度 · dispatch`,共 5 组)+ 2 条实时耗时读数 | 窄档元信息行**追加** ` · ${状态中文} · ${stage}` | 该格 `line-clamp:1`、实测 `scrollHeight 60 / clientHeight 20`:**只有开头约 12 个字符能露出来**。所以「前置」等于把「进度 100%」换成一个 stage 码,是拿已有数据换新失踪数据;**追加**则是零视觉增量的「补齐」。(2 条耗时读数是两次加载之间任务还在跑造成的漂移,不是隐藏。) |
|
||||
| ⑥ | 宽档首列的**导出编号** `65 / 78 / 79` | 名称行改成 `#编号 名称` 同行显示(`<span className={MONO}>#{id}</span> {name}`),`title` 同步为 `#id 名称` | 加一整行会把行高从 84 顶到预算外(这一档行高正好卡在 ≤84 上限);同行前缀与 ③⑦ 已有的「编号 + 名称」写法一致,实测行高仍是 84 |
|
||||
|
||||
**两个测量陷阱**(写进规范,避免下一轮误判):① 耗时/进度类**实时值**在两次加载之间会变,不能按字符串等值判失踪,否则「漂移」会被当成「隐藏」;② `line-clamp` 是按**高度**裁的,不是按宽度——所以不能靠「文本还在 DOM 里」宣称数据可见,必须量 `scrollHeight/clientHeight` 推算真正露出的字数。
|
||||
|
||||
### 3.5 红线自证(批准书 §3 六条禁令逐条)
|
||||
|
||||
| 禁令 | 自证 |
|
||||
|---|---|
|
||||
| 不得统一采用单一处理方案 | 九张表六种组合(§3.3),只有「长文 `Clamp` + `title`」是共用的兜底层 |
|
||||
| 不得隐藏重要业务数据 | ③④⑤⑥⑦② 六表 token 对账(§3.4);两处缺口已补 |
|
||||
| 不得仅扩大容器宽度 | 窄档容器与 HEAD 相同:430→**356**(`tableaudit-*-postfix` 与 HEAD 日志同值),未动侧栏/正文内边距 |
|
||||
| 不得放宽 tableaudit 规则 | `ROW_H_MAX` 默认 84 未改、`NEX_SCROLL_SLACK` 未调;本轮两次表格运行都吃**默认阈值** |
|
||||
| 保持键盘访问 | 第 4 项 `semanticcheck` 在 430 复跑:HEAD `timeline 热区 hard 7 / Tab 不可达 7` → 工作树 **hard 0**(并格后的操作是 antd `<Button>`) |
|
||||
| 操作反馈与数据完整 | 操作列仍在行内(未收进要点开的菜单),按钮文案与点击回调一字未改;`visualcheck` 430 档断言 0(§8.2) |
|
||||
|
||||
### 3.6 结果
|
||||
|
||||
| 视口 | HEAD | 工作树 |
|
||||
|---|---|---|
|
||||
| 1440 | `EXIT=0` | `EXIT=0`,**日志与 HEAD 逐字节相同**(仅时间戳差异,`diff` 去时间戳后为空) |
|
||||
| 768 | 违规(并入口径外) | **`EXIT=0` / 违规 0 张表** |
|
||||
| 576 | 违规 | **`EXIT=0` / 0** |
|
||||
| 430 | **`EXIT=6` / 违规 6 张表**(最大横向溢出 546) | **`EXIT=0` / 0** |
|
||||
|
||||
BEFORE/AFTER 截图 19 张在 `03-tables/`(`BEFORE-NN-*.png` / `AFTER-NN-*.png` 成对,①② 另带 1440/768 宽档对照,用来证明宽档没被顺手改掉)。
|
||||
|
||||
### 3.7 未解决
|
||||
|
||||
- **T-1**:窄档把次要列并进主列后,**列头朗读的行数变多**(一格三行)。VoiceOver 在 430 的逐格朗读节奏本轮没专门复核,随 §7 人工脚本一起补测。
|
||||
- **T-2**:⑥ 行高实测 84 = 预算上限,再加一条元信息(例如导出耗时中文)就会破线;届时要按 §13.2 走「砍行间距」或换方案,不能默认扩预算。
|
||||
- **T-3**:① 项目列表在 768/576 走卡片,卡片栅格在 430 是单列——这是既有已验证行为,本轮只把边界从 `max-sm` 推到 `max-lg`,**没有**重设计卡片。
|
||||
|
||||
---
|
||||
|
||||
## 4. 第 9 闸语义检查 — 决策 APPROVED(新增 `semanticcheck`,并已咬出 4 类真缺陷)
|
||||
|
||||
### 4.1 为什么原来的第 9 闸(源码级)不够
|
||||
|
||||
批准书 §4 要求「优先用实际浏览器行为和辅助技术语义信息验证,不要仅依靠脆弱的源代码字符串匹配」。
|
||||
此前所有源码级检查量的都是字符串——`aria-label` 写没写、`tabIndex` 写没写。字符串会骗人,四个真实例子:
|
||||
|
||||
| 骗人的写法 | 源码看着 | 实际 |
|
||||
|---|---|---|
|
||||
| `role="button"` 给了 `div`,没给 `tabIndex` | 两条都在 | Tab 到不了 |
|
||||
| `role="slider"` 写了三年 | ARIA 契约齐 | 没有任何按键路径,读屏报「滑块」却调不动(`AudioPlay`) |
|
||||
| 透明 `input` 铺满上传按钮 + 全局 `outline:none` | TSX 里根本没这行 | 焦点环看不见(在 CSS 里) |
|
||||
| `aria-describedby` 指向 antd Tooltip 的 id | 引用悬空 | 悬停/键盘展开后目标真的出现了,不算缺陷 |
|
||||
|
||||
### 4.2 七条判据(`scripts/ui/semanticcheck.py`,1062 行,退出码 = offender 条数)
|
||||
|
||||
数据源全部是浏览器里的真东西:CDP `Accessibility.getFullAXTree`(AT 实际读到的角色与名称)、`getComputedStyle`(算出来的焦点环)、真按 Tab / Space / Escape(键盘实际走到哪儿)。
|
||||
|
||||
| 判据 | 量什么 | 关键设计 |
|
||||
|---|---|---|
|
||||
| **NAME** | 交互元素必须有 AT 读得到的名字 | 无名节点打句柄回读 aria-label / title / placeholder / 解析后的 `aria-labelledby` / 所在 `<label>`(算 own),再看三类「写在页面上但 AT 读不到」的相邻标签(form-item 标签列、表头+行首、上溯四层的标签状前兄弟)。**勾选类控件不吃相邻文字**——旁边那句话根本不进它的名称 |
|
||||
| **HOTSPOT** | `cursor:pointer` 必须键盘可达 | 容器/外壳不算 antd 内部(整棵树都在 `.ant-app` 里,按「祖上有 ant-」豁免会恒为 0);已滤「自身或内部有可聚焦控件」与「热区套热区」 |
|
||||
| **TAB** | 每个可见的 button/link/switch/checkbox 必须被 Tab 访问到 | 靠**走位前重打的句柄**认元素(dataset 不是 React 托管属性,一次局部重渲染会整族抹掉标记);覆盖不完整记进「覆盖说明」,不把「没轮到」说成「到不了」 |
|
||||
| **FOCUS** | 每个焦点必须**看得见** | 不比字符串:走位前拍「没聚焦时长什么样」,到位再读;描边/外发光/边框/底色在**自身 + 上五层包裹 + 旁边两个兄弟**上全不动才立案。为什么看包裹层:本项目按 `theme/antd.ts` 的既定决策「只变边框不发蓝光」,变化实测落在第 3~4 层,复选框的焦点皮肤甚至画在兄弟 `.ant-checkbox-inner` 上——只看 `activeElement` 会把三类成熟的键盘可达实现全部误判。每站停 260ms(antd 有 0.2s 过渡) |
|
||||
| **ARIA** | 声明与行为一致 | `aria-expanded` 随抽屉真翻转、`aria-current` 唯一且对得上路径、`role=tab` 只有一颗 `aria-selected=true`;引用悬空时**先悬停、再键盘展开、再点**复查目标是否真出现(antd 的 Tooltip/下拉都是懒挂载) |
|
||||
| **LIVE** | 播报通道唯一 | 可见的 `aria-live`/`role=status`/`role=alert` 容器 ≤2 且必须带 polite/assertive(不许 `live="off"` 假装有) |
|
||||
| **STATES** | 空 / 载入 / 错误说得出口 | 空表有文案、骨架屏有名字与 `aria-busy`、错误块有可读文本 |
|
||||
|
||||
**两档严格度是这道闸能活下来的关键**:NAME 软档(控件本身没名字但紧邻有可见标签)当前 **20 颗/主题**、HOTSPOT 软档 **65 处/主题**(时间线轨道行的 NumberInput、筛选胶囊 `span.ant-tag.nex-chip` 那一族),它们坐在成熟业务代码里,属 P2 批量整改。第一天就把欠账写进退出码,第二天这道闸就会以「全是噪音」为由被关掉。`NEX_NAMESTRICT=1` / `NEX_HOTSPOTSTRICT=1` 用于 P2 收尾时翻默认。
|
||||
|
||||
### 4.3 它第一天咬到的东西——全部就地修好
|
||||
|
||||
HEAD(`5a10bfb`)在独立 worktree + 独立 dev `:5299` 上跑同一条闸:**1440 `EXIT=58`**(NAME 20 / HOTSPOT 16 / TAB 16 / FOCUS 6),430 同形;工作树 **`EXIT=0`**。
|
||||
|
||||
| 缺陷类 | 页面 | HEAD 读数 | 根因 | 修复落点 |
|
||||
|---|---|---|---|---|
|
||||
| NAME 硬档 ×20 | `/assets` | 明暗各 10 颗 `input.ant-checkbox-input` 无可读名称 | `MediaPick` 外套一层空 `<label>`,antd Checkbox 内还有一层无文字 `<label>`,缩略图下那行素材名不进名称 | `AssetLibrary.tsx` 三处 `aria-label="选择素材/母版 ${name}"`,沿用站内 `PickBox` 的「选择 + 对象 + 名字」既定写法 |
|
||||
| HOTSPOT + TAB ×32 | `timeline`(7) / `review`(1) 明暗各一遍 | `div.relative.flex-1[配音 0X 播放进度] role=slider tabindex=—` 可点不可达 | 进度条从第一天起就写着 `role="slider"`,却没 `tabIndex` 也没按键路径——**我们先把 ARIA 契约说出去又没兑现** | `AudioPlay.tsx`:补 `tabIndex=0` + `aria-valuemin/max/text` + `onScrubKey`(←→/↓↑ 挪 5%、Shift 20%、Home/End 首尾,与鼠标同一套 `seekAudio`);`preventDefault + stopPropagation`,因为分镜页把裸 ↑/↓ 绑成了切镜,焦点在进度条上时那两下必须只找位 |
|
||||
| (同族)空头 slider | `MediaLightbox.tsx` | 预览器里那条进度**只读**(无 onClick 无按键) | 只读进度写成 `role=slider` 是空头承诺 | 改 `role=progressbar` + `valuemin/max/now`:语义与行为一致,Tab 序列不欠债 |
|
||||
| FOCUS 硬档 ×6 | `assets` / `library` / `timeline` 明暗各一 | `input.nex-file-input` 焦点不可见(四项属性聚焦前后一模一样) | 见 §1.4——全局 `:where(...):focus-visible{outline:none}` 把透明 input 唯一那圈描边也吃了 | `app.css` +11 行把环画在**看得见的按钮**上(`.ant-btn:has(> .nex-file-input:focus-visible)`) |
|
||||
|
||||
四处修复都不改交互形状:进度条还是那条进度条,只是键盘也能用;复选框还是那颗复选框,只是有名有姓。
|
||||
|
||||
### 4.4 反向验证(证明这道闸真的会红)
|
||||
|
||||
`scripts/ui/gateprobe.py` +89/−8 行,新增三条语义判据的反证(人造坏控件 → 必须红 → 撤掉 → 复绿),常驻出口从 `11/11` 升到 **`GATEPROBE_OK 14/14`**。闸已登记进 `nex.config.yaml → verification.ui_gates`(14 条命令:13 道测量闸 + gateprobe)。
|
||||
|
||||
### 4.5 430 上的额外收获(表格改造的副收益)
|
||||
|
||||
HEAD 在 430 同一条闸也是 **`EXIT=58`**(`04-semantic/HEAD-SEM.txt`,判据分布与 1440 一致),其中 `timeline 热区 hard 7 / TAB 不可达 7`。
|
||||
第 3 项并格之后,同一位置的工作树读数是 **hard 0 / soft 20**——窄档操作列渲染成 antd `<Button>`,天然可聚焦。
|
||||
**7 个键盘死角是被表格改造顺手消掉的**,这是副收益,不是改造动机;记在这里是为了让下一轮看到「列合并」的真实代价与收益方向。
|
||||
|
||||
### 4.6 未解决
|
||||
|
||||
- **S-1**:NAME 软档 20 颗/主题、HOTSPOT 软档 65 处/主题在册(P2 批量整改,届时先翻 `NEX_NAMESTRICT` 再逐颗补 `aria-label`)。
|
||||
- **S-2**:AT-1 图标字形名外泄(`@ant-design/icons` 渲染 `role=img aria-label="upload"`,读屏念成「upload 导入脚本」)——`semanticcheck` 不立案(它确实有名),只有真机读屏能发现。已登记 `docs/UI规范.md` §5.1.1 在册待办,修法(`aria-hidden`)会影响 R15 的「一颗按钮一只语义图标」判据,必须单独一轮。
|
||||
- **S-3**:`models` 页在 430 有 2 颗页签被 rc-tabs 收进溢出「更多」菜单,闸的判据是「走菜单点着了才算走到」,只打印不立案——真机上这条菜单路径的可达性还没用读屏走过。
|
||||
|
||||
---
|
||||
|
||||
## 5. 导航状态治理 — 决策「保持现有分离设计」
|
||||
|
||||
### 5.1 两条状态确实不是同一条(实测)
|
||||
|
||||
| 状态 | 载体 | 生命周期 | 实测证据(`05-nav/probe-output.txt`) |
|
||||
|---|---|---|---|
|
||||
| 桌面侧栏折叠 `collapsed` | `App.tsx:98` `useLocalStorage('nex.sider.collapsed', false)` | **跨会话持久化** | C 段:真实点「收起导航菜单」→ reload 后 `ls="true"`、侧栏盒子 **63px**(展开 223px) |
|
||||
| 窄屏抽屉 `navOpen` | `App.tsx:100` `useState(false)` | **单次访问内存态** | C2 段:430 点开抽屉后 `localStorage` 键集 **为空**,reload 后 `open:false` |
|
||||
| 判定与清理 | `App.tsx:104` `Grid.useBreakpoint().md === false`;`App.tsx:116` 换路由即 `setNavOpen(false)`;`App.tsx:214` `{narrow && <AppNavDrawer/>}` | — | 全站「收起导航菜单」触发器只有 1 颗,汉堡只在 <768 出现,两者不同时存在 |
|
||||
|
||||
### 5.2 为什么不合并成一条 Boolean(写进规范的理由)
|
||||
|
||||
折叠改变的是**正文可用宽度**(223 ↔ 63)——它是布局偏好,需要跨页稳定,否则每次进来都要重排一次视线落点;
|
||||
抽屉改变的是**正文是否被遮住**——它是一次性遮挡层,「记住打开」等于每次进来先吃一层遮罩 + 一次焦点抢占,是移动端反模式(modal 可见性不进恢复栈)。
|
||||
两者一个是布局偏好、一个是模态可见性,共用一条状态反而要为每次换页写清理逻辑。**本项按批准书 §5 不要求重构**,代码零改动。
|
||||
|
||||
### 5.3 顺手关掉一个真实缺口(AT-2:当前页对辅助技术不可见)
|
||||
|
||||
写这一节的实测时发现:选中关系**只写在 class 上**。真机 VoiceOver 走位只报「菜单」,不报「当前页面」;CDP 读选中项属性只有 `aria-describedby`。
|
||||
antd Menu 在 `role=menu` 这条分支不写 `aria-selected`(`rc-menu/es/MenuItem.js:160` 那条只在 `role=option` 分支生效),所以**补不了就得登记 P2**。实测**能补**:
|
||||
|
||||
- 落点 `app/layout/AppSider.tsx`:`currentMark(key)` 给 `key === pathname` 的 item 加 `'aria-current': 'page'`,与 `selectedKeys={[pathname]}` 同一个钥匙(`useMemo` 依赖补 `pathname`)。
|
||||
- 为什么落得进 DOM(读源码确认,不是试出来的):`rc-menu/es/utils/nodeUtil.js` 的 `_excluded` 只剥 `label/children/key/type/extra`,`MenuItem.js:168` 把剩下的整包铺到 `<li>`。
|
||||
- 复测(D 段):`/projects/10/storyboard`、`/assets`、`/` 三条路由 + 430 抽屉里的第二份菜单,**有且只有当前项**带 `aria-current="page"`,且与 `.ant-menu-item-selected` 同一项;菜单项宽度 **207 未变**(加属性没改盒子)。
|
||||
- 顺带纠正了一条与实测不符的文件头注释(原写「`aria-current`…Menu 自带」,是错的)。
|
||||
- **折叠态的边界要说清楚**(14:21 补测,`05-nav/ARIA-CURRENT.txt`):`aria-current` 只可能出现在**已渲染的那一项**上。展开态 10 项里恰好 1 项有名;折叠成 64 图标轨后 `.ant-menu` 只剩 **3 项**(七个环节属于 `submenu`,rc-menu 懒渲染弹层),轨道上 `[aria-current]` 计数 = 0,此刻 AT 只能看到 antd 自己的 `.ant-menu-submenu-selected`——那是 `role=none` 的容器,往上写 ARIA 状态不会被播报;**悬停展开弹层**后当前项重新带上 `aria-current="page"`。所以这条改动的准确表述是「当前页一旦被渲染就必然有名」,不是「折叠态也能读出当前页」;后者要改 rc-menu 的弹层渲染时机,不在本轮范围(登记 **S-4**)。
|
||||
|
||||
### 5.4 规范落点 / 未闭环
|
||||
|
||||
补测还留了一条边界(**S-4**,见 §5.3 第三条):折叠图标轨不渲染二级菜单项,因此「折叠态读出当前页」要靠改 rc-menu 弹层渲染时机才能成立——不在本轮范围。
|
||||
|
||||
`docs/UI规范.md` §6.2.1 新增「导航有两个状态,且**故意**两种生命周期」,并把这条经验一般化:**凡选中只靠 class 表达的共享控件,都要给辅助技术一个状态属性**(已同时登记进 §6.2.1 的 AT 暴露段)。
|
||||
**未闭环**:补完之后 VoiceOver 是否真的播报「当前页面」还没在真机复听(AT-2 的 DOM 侧已关闭,AT 侧待人工),随 §7 的人工脚本一起交。
|
||||
|
||||
---
|
||||
|
||||
## 6. UI Chunk — 决策「先分析,再实施低风险优化」→ **实测后实施 0 处**
|
||||
|
||||
### 6.1 组成与归属(`scripts/ui/chunkinfo.mjs`,按 sourcemap 映射区间计字节)
|
||||
|
||||
| 归属 | 字节(工作树全站) | 归属 | 字节 |
|
||||
|---|---|---|---|
|
||||
| `npm:antd` | 542.7 kB | `npm:rc-table` | 37.5 kB |
|
||||
| `src:pages` | 331.8 kB | `npm:rc-tree` | 35.6 kB |
|
||||
| `npm:react-dom` | 126.3 kB | `npm:rc-select` | 31.2 kB |
|
||||
| `src:components` | 73.5 kB | `npm:rc-field-form` | 30.7 kB |
|
||||
| `npm:@ant-design/icons-svg` | 53.0 kB | `npm:tailwind-merge` | 27.8 kB |
|
||||
| `npm:@remix-run/router` | 45.8 kB | `src:lib` / `src:app` | 26.9 / 24.8 kB |
|
||||
|
||||
**三方合计 1258.5 kB / 本项目源码 479.5 kB**——首屏那 1.19 MB 的 `ui-*.js` 里近 **7 成是 antd + rc-* + react-dom**,不是我们的页面代码。
|
||||
|
||||
### 6.2 首屏 before/after
|
||||
|
||||
| 口径 | HEAD `5a10bfb` | 工作树 | 差 |
|
||||
|---|---|---|---|
|
||||
| 首屏合计 raw | 1486.24 / 1486.47 kB(两次构建) | 1487.23 / 1487.46 kB | **+0.9 ~ +1.2 kB** |
|
||||
| 首屏合计 gzip | 453.87 / 454.07 kB | 454.25 / 454.45 kB | **+0.4 kB** |
|
||||
| 首屏合计 brotli | 370.90 / 371.09 kB | 371.28 / 371.58 kB | **+0.4 kB** |
|
||||
| 首屏文件数 | 7 | **7**(未新增文件) | 0 |
|
||||
| 首屏占全部 | raw 78.5% / gzip 75.7% | raw 78.1% / gzip 75.6% | 占比略降 |
|
||||
| 全部产物 | 1892.67 / 1894.25 kB | 1904.38 / 1905.97 kB | +11 kB,全部落在**换页才拉的 lazy chunk** |
|
||||
|
||||
(每侧各跑两次构建、工作树在最终代码上另跑第三次 14:37 = 1487.42 / 454.33 / 371.37 kB,三次之间**抖动 ≤0.25 kB**,上表给区间,第三次原始输出在 `06-chunk/after-chunkinfo-final.txt` 并已并入 `firstscreen-diff.txt` 末段。首屏 7 个文件固定为 `ui-*.js` 1187.8 + `index-*.js` 219.5 + `index-*.css` 75.8 + 四个 <3 kB 的运行时小块。)
|
||||
|
||||
### 6.3 为什么实施 0 处(三条实测理由,对应批准书 §6 的三条禁令)
|
||||
|
||||
1. **「路由级动态加载」这件事**已经做完了:14 个页面组件**全部** `lazy()`(`frontend/src/app/router.tsx:37-50`),只有两颗是**写注释说明过的同步例外**——`<Dashboard>`(首屏那一页,拆了反而多一次往返)与 `<NotFound>`(「别的 chunk 没到位」时总要有人说话);`help.html` 只是重定向。本轮没有可补的漏网路由,而 `index-*.js`(219 kB)里装的正是路由表与外壳,拆它 = 改架构,属被禁止的「没有依据的全局分包重构」。
|
||||
2. **`ui-*.js` 1187.8 kB 不是我们造成的**:项目**没有** `manualChunks`,这一坨是 rolldown-vite 的自动分组结果。要动它得先动打包配置(等于引入新的分包决策),风险面 = 全站首屏。
|
||||
3. **没有盲目抬阈值**:`chunkSizeWarningLimit: 1200` 是 HEAD 就有的既有配置,本轮**未改**;那条 >1200 kB 的构建警告因此仍在(见 §6.5),我们没有用「调大数字」把它捂住。
|
||||
|
||||
本轮唯一算「低风险优化」的动作是**把测量做成脚本**(`chunkinfo.mjs`),下一轮再动分包时有基线可比。首屏加载行为的前后对比走的是第 8 项:`visualcheck` 120 状态的 `HTTP 0 / console 0` 与逐页断言,两档构建同绿。
|
||||
|
||||
### 6.4 一条测量口径的坑(写下来免得下一轮被误导)
|
||||
|
||||
`chunkinfo.mjs` 最初按「包名聚合」统计,把 react 报成了 306 kB——那是**过归属**(一个 chunk 里多个包的字节被整块记到第一个命中的包上)。改成按 sourcemap 映射区间逐段计字节后得到上表(react-dom 126.3 kB)。修正前后的对照存在 `06-chunk/perpkg-attribution.txt`,旧口径的读数已标注为 artifact。
|
||||
|
||||
### 6.5 未解决
|
||||
|
||||
- **C-1**:`ui-*.js` 1187.8 kB 触发构建期 `chunkSizeWarningLimit:1200` 警告。可选解法按风险从低到高:给 antd 做按需入口对账 → 试 `experimental.renderBuiltUrl`/分组微调 → 抬阈值(**须先有依据**)。本轮一条都没做。
|
||||
- **C-2**:`dist` 里没有 `.map`(`vite build` 默认不出),归属分析要额外跑一次 `--sourcemap` 构建;下一轮若常做这项分析,值得决定要不要固定出 map。
|
||||
- **C-3**:CSS 75.8 kB(gzip 13.8)与首屏同批下发,未按路由切;在真正做「低风险拆分」那一轮之前,它是第二优先级。
|
||||
|
||||
---
|
||||
|
||||
## 7. N14 真实读屏验证 — **MANUAL QA REQUIRED**(本轮不做「通过」宣称)
|
||||
|
||||
完整记录:`reports/ui_evidence/nex-p8f/07-screen-reader/`(README + 149 条真实播报 + 环境取证 + 3 张截图)。
|
||||
这一节按批准书 §7 的要求写:**真实环境、真实快捷键、真实焦点位置、真实播报内容**;做不到的一律标 MANUAL QA REQUIRED。
|
||||
|
||||
### 7.1 实际测试环境(全部实测取证,见 `environment-probe.txt`)
|
||||
|
||||
| 项目 | 实测值 |
|
||||
|---|---|
|
||||
| 操作系统 | macOS 15.3 (24D60),Mac16,10(Apple Silicon) |
|
||||
| 读屏软件 | **VoiceOver**(`/System/Library/CoreServices/VoiceOver.app`),语音 zh-CN「婷婷」 |
|
||||
| 浏览器 | **Safari 18.3** |
|
||||
| 对照组 | Google Chrome 156.0.8078.74(NVDA 用不上,仅记录版本) |
|
||||
| 被测站点 | `http://127.0.0.1:5199`(工作树 dev),项目 10 |
|
||||
| 播报抓取 | `/usr/bin/log stream --predicate 'process == "VoiceOver"' --style compact --info --debug` → 原始 8060 万字符日志压成 **149 条带时间戳播报** |
|
||||
| 抓取注意 | 本机 `log` 被 zsh function 遮蔽,**必须写 `/usr/bin/log`**,否则流为空 |
|
||||
|
||||
会话时间轴:13:51:19 进入网页内容 → 13:56:40 旁白自动退出 → 13:59:15 重开确认 → 13:59:35 进程退出。**全程未按 ⌥↓**,镜头顺序没被这次测试改动(清理时确认过没有截图顺序漂移)。
|
||||
|
||||
### 7.2 逐步记录(VoiceOver + Safari,播报栏为系统实际输出)
|
||||
|
||||
| # | 步骤 | 实际播报(时间戳) | 焦点 | 结论 |
|
||||
|---|---|---|---|---|
|
||||
| V1 | 进入页首 | `13:51:19 你当前在网页内容内部的横幅上。` / `13:52:07 补充` / `13:52:13 主要` | banner / complementary / main | **PASS**(三个 landmark 都能定位) |
|
||||
| V2 | 「收起导航菜单」 | `13:51:36 收起导航菜单 ⟨停顿⟩ 按钮` | Header 折叠按钮 | **PASS**(阶段 2 改的 `<button>` 在 AT 下有名有角色) |
|
||||
| V3 | 顶栏项目胶囊 | `13:51:41 跨界斗地主 · 大漠客栈二番局 审核中 83 百分之 当前 · 时间线合成 加号 配音 斜线 字幕 斜线 混音:…` | `.nex-console` | **PASS**(430 视觉省略号不影响 AT 读全称,与 §2 的 CDP accessible name 对得上) |
|
||||
| V4 | 平台状态开关 | `13:51:45 平台当前空闲 ⟨停顿⟩ , 对话框弹出 ⟨停顿⟩ 按钮` | 平台状态按钮 | **PASS** |
|
||||
| V5 | 主题切换 | `13:51:58 切换明暗主题,当前为浅色 ⟨停顿⟩ 按钮` | 主题按钮 | **PASS**(状态写进名字,不靠颜色) |
|
||||
| V6 | 进入侧栏菜单 | `13:52:09 菜单` → `13:52:11 你当前在"菜单"中。` → `13:52:11 的结尾 ⟨停顿⟩ 补充` | `<ul role=menu>` | **部分**:landmark 对,但**当前项没被播报为「当前页面」**=缺陷 AT-2;本轮已补 `aria-current="page"` 并 CDP 复测通过(§5.3),**VO 是否播报尚未真机复听** |
|
||||
| V7 | 「导入脚本」 | `13:52:17 upload 导入脚本` | 工具栏按钮 | **FAIL(AT-1)**:图标字形名混进可读名称 |
|
||||
| V8 | 视图切换单选组 | `13:52:45 切换分镜视图 ⟨停顿⟩ 单选按钮组`;`13:52:46 appstore 看板 appstore和其他1项`;`13:52:51 ordered-list 分镜表 ordered-list和其他1项` | Segmented | **部分**:组名/角色/「N 项中的第 M 项」都对;`appstore`/`ordered-list` 同 AT-1 |
|
||||
| V9 | 搜索框 | `13:53:06 搜索 :` → `13:53:10 搜索分镜 镜号 / 标题 / 画面 / 台词 / 角色 / 场景…` → `13:53:10 你当前在文本栏上。…` | 搜索 `<input>` | **PASS**(label 关联成功;`search` 前缀属 AT-1) |
|
||||
| V10 | 三个筛选器 | `13:53:18 按镜头状态筛选 , 列表框弹出 已收起 组合框`(另两颗同形) | 筛选控件 | **PASS**——`已收起` 是 ARIA 状态与实际一致的行为证据,正是第 4 项要的东西 |
|
||||
| V11 | 「导出」 | `13:53:51 down 导出 ⟨停顿⟩ 按钮` | 导出按钮 | **部分**:名称对但带 `down` 前缀(AT-1) |
|
||||
| V12 | 进入第一张分镜卡 | `13:53:55 打开分镜详情:镜头 1`;描述段 `13:53:53 聚焦卡片后按住 ` → `13:53:55 Alt(macOS ` | 分镜卡(grid) | **部分**:主名与 `aria-describedby`(`Storyboard.tsx:1361` 的 `.sr-only` 段)都被指向并起读,但整段只读到「Alt(macOS」就断。**原因未定性**:VO 播报是 `behavior: stop, isoBehavior: replace`,我两次 VO+→ 只隔 1.9–3 s,后一条会截断前一条;人工复测须在同一停留点等 ≥10 s 或按 VO+R 重读再判定 |
|
||||
| V13 | 卡内复选框与状态 | `13:54:03 选择镜头 1 ⟨停顿⟩ , 未勾选 ⟨停顿⟩ 复选框`;`13:54:04 已生成` | 复选框 | **PASS**(勾选态被播报;状态标签是纯文本可读) |
|
||||
| V14 | VO+Space 勾选 | **未执行**(只读走位,不改业务数据) | — | **待人工** |
|
||||
| V15 | 光标停在卡上按 ⌥↑ / ⌥↓ | **未执行**(VO 自动退出后重开 40 次 VO+→ 未命中卡片即停止) | — | **待人工**——⌥↓ 的**功能**正确性阶段 8 已验(`reports/NEX阶段8实施-2026-11-07.md:400` + `shots-before/*-3-按后.png`),**AT 下的播报与焦点跟随未验** |
|
||||
| V16 | 分镜表视图 Tab 到「前移 / 后移」 | **未执行** | 行操作 | **待人工**(`Storyboard.tsx:1475/1477` 是 `<button>` 且带 `aria-label`,播报需人工确认) |
|
||||
| N1–N4 | **NVDA 2024.x + Chrome**:Tab 到卡片 / Alt+↑↓ 排序 / 前移后移按钮 / 读被截断的项目名 | **未执行——本机无 Windows 环境**(`/Applications` 无 Parallels / UTM / VMware,无 Boot Camp) | — | **MANUAL QA REQUIRED** |
|
||||
|
||||
### 7.3 本轮新发现的两个 AT 缺陷
|
||||
|
||||
| 编号 | 症状 | 根因 | 处置 |
|
||||
|---|---|---|---|
|
||||
| **AT-1** | 图标字形名混进按钮名称:`upload 导入脚本`、`down 导出`、`appstore 看板`、`search 图像` | `@ant-design/icons` 把字形渲染成 `role=img` + `aria-label=<glyph 名>`(出口 `components/icons/index.ts` 原样再导出)。`semanticcheck` **不立案**——它确实「有名」,只有真机读屏能发现 | 修法明确(图标 `aria-hidden`),但它会影响 R15「一颗按钮一只语义图标」的判据与 `classaudit` 第 2 闸,**必须单独一轮**;已登记 `docs/UI规范.md` §5.1.1 在册待办 |
|
||||
| **AT-2** | 侧栏「当前页」对 AT 不可见(只有 `.ant-menu-item-selected`) | antd Menu 在 `role=menu` 分支不写 `aria-selected` | **本轮已关闭(DOM 侧)**:`aria-current="page"`,见 §5.3;AT 侧复听随 V 组人工脚本 |
|
||||
|
||||
### 7.4 为什么不能宣称 N14 通过
|
||||
|
||||
批准书 §7 要求「至少验证 NVDA + Chrome,以及项目支持范围内的 VoiceOver + Safari」并「必须记录实际读屏环境、快捷键行为、焦点位置和播报内容」。本轮:
|
||||
|
||||
- ✅ 环境、快捷键、焦点、播报四项**全部有实录**(V1–V13);
|
||||
- ✅ VoiceOver 一档的**大部分**读点通过,且发现两个源码检查看不见的缺陷;
|
||||
- ❌ NVDA + Chrome **一条都没跑**(客观上没有 Windows 环境);
|
||||
- ❌ N14 的**核心动作**——在 AT 下按 ⌥↑/⌥↓ 移动分镜卡并听到结果播报、焦点跟随——**没验**(V15 未执行);
|
||||
- ⚠ V12 的说明截断**未定性**(VO 播报节奏 vs 产品缺陷)。
|
||||
|
||||
**所以按授权书 §9:本轮不将整个 NEX Phase 8 标记为完全验收通过。** 人工复测脚本(照抄即可执行,含「每步只按一次 VO+→、等 ≥10 s」「VO+R 重读」「截屏留档到 `shot-vo-move-*.png`」)已经写进 `07-screen-reader/README.md` §3。
|
||||
|
||||
---
|
||||
|
||||
## 8. 自动化检查总账
|
||||
|
||||
### 8.1 这个仓库里**真实存在**的检查(没有 lint,也没有单测)
|
||||
|
||||
| 层 | 命令(逐字可执行) | 审什么 | 本轮 |
|
||||
|---|---|---|---|
|
||||
| 类型 | `cd frontend && npm run typecheck`(=`tsc --noEmit`) | 全量 TS | ✅ EXIT=0(14:21 与 14:48 各一次,两次都在 `canHover()` 与注释改指 §6.5 之后;提交序列 14:49:45–14:50:30 用的是同一份源码) |
|
||||
| 构建 | `cd frontend && npm run build`(=`tsc --noEmit && vite build`) | 产物能出 | ✅ EXIT=0(主跑 3 s;最终代码 14:37 再构建一次 4 s,`dist` 就是下面 preview 冒烟与 chunk 复测用的那一份。警告 `>1200 kB` 仍在=C-1,阈值一字未抬) |
|
||||
| 运行时 | `cd frontend && npm run dev` / `npm run preview` | 供所有 UI 闸门挂页面 | ✅ dev :5199 / preview :4173、:4189 |
|
||||
| 静态 UI | `node scripts/ui/classaudit.mjs` | 9 道子闸(死类名 / 图标出口 / 裸 `button` / 浮层底部动作 / `import 'antd'` 越界 / 反馈四级 / 标题前置图形 / Tag 皮肤类 / **断点对账**) | ✅ 9 项全 0(死类名 0 / 4137 候选;裸 button 命中 6 = 白名单 6;断点 0 / 10 档在册) |
|
||||
| 度量 UI | `.venv/bin/python -u scripts/ui/{visualcheck,tableaudit,gridcheck,rhythmcheck,tagcheck,btnrowcheck,aligncheck,symmetrycheck,footercheck,btnclustercheck,feedbackcheck}.py` | 像素、栅格、节奏、表格几何、按钮行/簇、页脚、反馈表面 | ✅ 全 EXIT=0 |
|
||||
| 语义 UI | `.venv/bin/python -u scripts/ui/semanticcheck.py`(**本轮新增**) | 辅助技术语义与行为七判据 | ✅ 1440 与 430 各 EXIT=0 |
|
||||
| 反向 | `.venv/bin/python -u scripts/ui/gateprobe.py` | 证明闸门坏了会响 | ✅ `GATEPROBE_OK 14/14`(本轮从 11/11 加到 14/14,新增 3 条都是 semanticcheck 的反例) |
|
||||
|
||||
`nex.config.yaml → verification.ui_gates` 从 13 行加到 **14 行**(新增 `semanticcheck.py`,并注明它是第 4 项的产物);`baseline` 那句仍是 **14 路由 × {1440,768,430} × {light,dark} = 84 个状态**,本轮没有偷偷改口径。所有 UI 闸门跑前都要 `export NEX_BASE=http://127.0.0.1:5199`(:5173 是陈旧实例)。**项目没有 `npm run lint`,也没有测试运行器**——任何「lint 通过 / 测试通过」的说法在本仓库都是虚构。
|
||||
|
||||
### 8.2 全量执行结果(主跑 13:40:15 → 14:19:29,`09-gates/SUMMARY.txt`)
|
||||
|
||||
| # | 闸门 | EXIT | 耗时 | # | 闸门 | EXIT | 耗时 |
|
||||
|---|---|---|---|---|---|---|---|
|
||||
| 1 | build | 0 | 3 s | 10 | footercheck | 0 | 148 s |
|
||||
| 2 | tableaudit-1440 | 0 | 49 s | 11 | btnclustercheck | 0 | 66 s |
|
||||
| 3 | tableaudit-768 | 0 | 42 s | 12 | feedbackcheck | 0 | 41 s |
|
||||
| 4 | tableaudit-576 | 0 | 43 s | 13 | **semanticcheck(1440)** | **0** | 706 s |
|
||||
| 5 | tableaudit-430 | 0 | 46 s | 14 | **semanticcheck-430** | **0** | 609 s ⚠ |
|
||||
| 6 | gridcheck | 0 | 58 s | 15 | gateprobe | 0 | 5 s |
|
||||
| 7 | rhythmcheck | 0 | 39 s | 16 | classaudit | 0 | 0 s |
|
||||
| 8 | tagcheck | 0 | 36 s | 17 | visualcheck-120 | 0 | 248 s |
|
||||
| 9 | btnrowcheck / aligncheck / symmetrycheck | 0 / 0 / 0 | 118 / 46 / 51 s | | | | |
|
||||
|
||||
⚠ 首跑 `semanticcheck-430` 与两处表格修复存在时间交叉(表格文件 14:07:42 / 14:08:25 落地,该闸 ~14:05 起跑),**视为污染**,14:25:53 起在最终代码上干净重跑,`EXIT=0 (612 s)`、`=== 语义与行为 0 条违规 ===`(`semanticcheck-430-rerun.log`,两份日志都在 `09-gates/` 与 `04-semantic/`)。**表格里那一行引用的是重跑版**;§8.3 的 HEAD ↔ 工作树对照同样以重跑版为准。
|
||||
|
||||
复跑(`09-gates/RERUN-SUMMARY.txt`,全部在最终代码上):
|
||||
|
||||
| 复跑项 | EXIT | 耗时 | 读数变化 |
|
||||
|---|---|---|---|
|
||||
| tableaudit-430-postfix | 0 | 43 s | 违规 0 张 |
|
||||
| tableaudit-576-postfix | 0 | 51 s | 违规 0 张 |
|
||||
| tableaudit-768-postfix | 0 | 45 s | 违规 0 张 |
|
||||
| dataintegrity(A/B/C/C2) | 0 | 98 s | ⑥ 失踪 3→**0**;③ 失踪 9→**2**(实时耗时漂移);B `stray_tooltips` 1→**[]** |
|
||||
| gateprobe-final | 0 | 3 s | 14/14 |
|
||||
| classaudit-final | 0 | 1 s | 9 子闸全 0 |
|
||||
| **semanticcheck-430-rerun** | **0** | **612 s** | **0 条违规**(清洁版:14:25:53 → 14:36,代码含 14:20 的 `canHover()` 触屏收口,与首跑读数一致) |
|
||||
| semanticcheck-account-routes | 0 | 171 s | 四条 chromeless/账号路由:硬档 **0**,软档只多两类 ×8(§8.4 → S-1) |
|
||||
|
||||
最终代码全量复跑(14:39:39 → 14:45:47,跑在 14:37 那次 `npm run build` 的产物与含 `canHover()` 的源码之上):
|
||||
|
||||
| 复跑项 | EXIT | 耗时 | 读数 |
|
||||
|---|---|---|---|
|
||||
| **visualcheck-120-final** | **0** | **246 s** | 120 张截图(15 路由 × 4 档 × 2 主题)已归档 `11-visualcheck-final/`;`=== HTTP 失败(0 条)===`、`=== 断言(0 条)===`;1440 档 30 行尺子逐张打印(脚本只在首个视口打印,见下) |
|
||||
| tableaudit-430-final | 0 | 45 s | `=== 违规 0 张表 ===`(窄档九张全在,最大行高 ≤ 84) |
|
||||
| tableaudit-1440-final | 0 | 41 s | `=== 违规 0 张表 ===`(宽档列与 HEAD 同形) |
|
||||
| **preview-smoke-final** | **0** | **84 s** | `dist` 产物 × preview :4173 × {1440,430} × {dark,light} × 6 代表页 = **24/24 OK**;顶栏均 56、导航入口均在、正文节点 373–1453、`data-theme` 与请求档一致、console error 0、4xx/5xx 0;截图 24 张在 `10-preview-smoke/shots/` |
|
||||
|
||||
**`preview-smoke` 第一次跑是红的(`EXIT=1`,36 s)**,红得有价值也有迷惑性:traceback 停在 `wait_for_url("/")`,看着像产物登录坏了,实际是**起 preview 的那个 shell 没带 `NEX_BACKEND`**,`vite.config.ts:9` 的代理默认指 `:8000` ⇒ 全站 `/api` 502、登录表单点下去没有回包。这条与产物无关,但它暴露了冒烟脚本自己的脆弱点:环境不对时它吐 traceback 而不是人话。已在脚本里补 `preflight()`(先打一发 `/api/v1/auth/login`,≥500 直接 `EXIT=3` 并说「起 preview 时忘了 NEX_BACKEND」),并把「登录成功」从「URL 必须等于 `/`」改成「离开 `/login`」——守卫落到哪条不在冒烟的职责里。**冒烟是证据不是闸门**,所以它没进 `nex.config.yaml` 的 14 条常驻名单。
|
||||
|
||||
### 8.3 HEAD ↔ 工作树同尺对照(这才是「有没有变好」的唯一凭据)
|
||||
|
||||
| 尺子 | HEAD `5a10bfb` | 工作树(本轮) |
|
||||
|---|---|---|
|
||||
| `tableaudit` @430 | **`EXIT=6` / 违规 6 张表**(最大横向溢出 546 px) | **`EXIT=0` / 0 张** |
|
||||
| `tableaudit` @576 / @768 | 违规 | **`EXIT=0` / 0 张**(两次) |
|
||||
| `tableaudit` @1440 | `EXIT=0` | `EXIT=0`,**日志去掉时间戳后与 HEAD 逐字节相同**(`diff <(sed …) <(sed …)` 空输出)⇒ 宽档真的没被顺手改 |
|
||||
| **`semanticcheck` @1440**(新增的闸) | **`EXIT=58`**(分布:NAME 20 / HOTSPOT 16 / TAB 16 / FOCUS 6;两条「只影响打印」的判据行已排除) | **`EXIT=0`** |
|
||||
| **`semanticcheck` @430** | **`EXIT=58`** | **`EXIT=0`** |
|
||||
| `typecheck` / `build` | 0 / 0 | 0 / 0 |
|
||||
|
||||
软档**没有为了让灯变绿而调严或调松**:1440 与 430 两档都仍是「无名 硬 0 / 软 40(=20 每主题)· 热区候选 138(=69 每主题)· 行走 12 路由 × 2 主题 = 24 次」,两档读数**逐条相同**。HEAD 对照日志留在 `04-semantic/HEAD-SEM.txt`。
|
||||
|
||||
### 8.4 84 状态基线 ↔ 本轮 120 张图的关系
|
||||
|
||||
- 基线 `84 = 14 路由 × {1440, 768, 430} × {light, dark}`(`visualcheck.py` 默认 14 条路由:`/ /assets /models` + 7 个项目环节页 + `/account /users /help /login`)。
|
||||
- 本轮 `visualcheck-120 = 15 条 × 4 档 × 2 主题`:路由多一条 `/not-a-page`,宽度多一档 `576` ⇒ **84 是 120 的真子集**,不是换了口径。
|
||||
- 结果:`=== HTTP 失败(0 条)===`、`=== 断言(0 条)===`。口径要说准:**断言覆盖 120 张**(`problems` 是按每页每档累积的,`visualcheck.py:514` 那行 `shot …` 只在首个视口打印,所以日志里只有 30 行尺子,另外 90 张的选中态与溢出走的是同一套断言、同样计入退出码)。打印出来的 30 行里侧栏选中项(bg/color/text/kind)与顶栏(h=56、bg)逐张可见——明暗两档分别是 `rgb(22,104,220)/rgb(255,255,255)` 与 `rgb(230,244,255)/rgb(22,119,255)`、Header `rgb(17,24,32)` / `rgb(255,255,255)`,120 张里 14 条路由的选中态**没有一条断线**。
|
||||
- `semanticcheck` 默认名单是 12 条:84 基线里的 10 条(`/`、`/assets`、`/models` + 7 个环节页)**加**两条合成态 `/403`、`/9e0f-not-a-page`,**不含** chromeless 的 `/login` 与三颗账号页。这四条本轮另跑 `NEX_ROUTES="/account,/users,/help,/login"` 补测(14:36:29 → 14:39:20,`EXIT=0`,171 s,日志 `04-semantic/semanticcheck-account-routes.log`):**硬档 0 条**,`/account` `/help` 热区 0,`/users` `/login` 各 4 条热区候选全部落在「内部已有可聚焦元素」的软档;软档只多出两类 ×8(1440/430 两档 × 明暗 = 4 组读数一致):`div.nex-stat`(可点击统计卡)与 `span.nex-chip`(可点击筛选片)pointer 可点但键盘到不了 ⇒ 登记为 §9 的 **S-1**,不在本轮扩大范围改。Tab 走位 24–61 站、`焦点掉出文档` 与主名单同形(地址栏/工具栏那一站,不是缺陷)。——「闸没报」和「闸没看」是两件事,得区分开。
|
||||
|
||||
### 8.5 跑不了的检查(照实说,不虚构)
|
||||
|
||||
| 项 | 状态 |
|
||||
|---|---|
|
||||
| `lint` / `test` / `e2e` | **本仓库不存在**,一次都没跑,也没宣称 |
|
||||
| NVDA + Chrome | **MANUAL QA REQUIRED**——本机没有 Windows(无 Parallels / UTM / VMware / Boot Camp) |
|
||||
| iPad 真机 + 蓝牙键盘(N-3) | 无设备,只按 `matchMedia` 分支推断 |
|
||||
| VoiceOver 复听(AT-1/AT-2、V14–V16) | 需人工,脚本已备(§7) |
|
||||
|
||||
---
|
||||
|
||||
## 9. 尚未完成的问题清单(编号与正文各节 §x.5 一一对应)
|
||||
|
||||
| 编号 | 位置 | 症状 | 影响面 | 严重 | 建议处理 |
|
||||
|---|---|---|---|---|---|
|
||||
| **L-1** | `frontend/src/styles/app.css`(839 行 / 141 规则 / 199 分支,其中 132 条 `.nex-*` **未入层**) | 未分层的 `.nex-tag.ant-tag{display:inline-flex}` 压过 `@layer utilities` 的 `max-md:hidden`,隐藏类点不亮 | 顶栏胶囊、任何想按断点隐藏 `.nex-*` 表面的地方 | 中(已知绕法:改结构/改类) | DEFERRED(§1.3 三条依据)。真要迁就要连 preflight 一起想清楚,属独立一轮 |
|
||||
| **L-2** | `app.css` 里 antd `@layer antd` 包住 preflight | 浏览器默认样式被排进具名层,`all: revert` 这类兜底行为不直观 | 全站基线 | 低 | 与 L-1 同轮处理 |
|
||||
| **N-1** | `PipelineConsole.tsx` 名字额度 | >200 px 额度的超长项目名在 430 省略比例更高,只剩 `title`+Tooltip+抽屉 | 430 顶栏 | 低 | 若产品要把「当前节点」也塞进 430,重新量额度,别外推本轮结论 |
|
||||
| **N-2** | 同上 `placement="bottomLeft"` | <380 视口未测,antd 会自动翻转 | 430 以下 | 低 | 下一轮加一档 360 视口 |
|
||||
| **N-3** | `PipelineConsole.tsx:166-169` `canHover()` | 纯触屏 + 外接键盘时键盘 Tooltip 不再出现 | iPad/触屏笔记本 | 低(有意收窄) | 有设备后按 §7 人工脚本补测 |
|
||||
| **T-1** | §3.3 并列的六张窄表 | 并列后一格三行,**行内逐格朗读节奏**没专门复核 | 430/576 读屏 | 中 | 与 §7 人工脚本同批:VO 逐格走一遍并录音 |
|
||||
| **T-2** | ⑥成片记录(`Delivery.tsx`) | 窄档行高实测 **84 = 预算上限**,再加一条元信息必破线 | ⑥ | 中 | 加信息前先按 §13.2 走「砍行间距」,不许默认扩预算 |
|
||||
| **T-3** | ①项目列表(`Dashboard.tsx`) | 卡片/表格边界从 `max-sm` 推到 `max-lg`,卡片栅格本身没重设计 | 576/768 项目列表 | 低 | 若要做移动端卡片形态,另开一轮 |
|
||||
| **S-1** | `semanticcheck` 软档 | NAME 软 40、HOTSPOT 候选 138(1440)仍只打印不立案;账号侧四条路由补测另得两类 ×8:`div.nex-stat`(可点统计卡)、`span.nex-chip`(可点筛选片)pointer 可点但键盘到不了(§8.4) | 全站的次级可达性 | 中(P2) | 按路由分批转硬:先 `/assets`(28) 与 `/projects/10/timeline`(20);`nex-stat` / `nex-chip` 一并处理(改 `button`/`a` 或补 `tabIndex`+`role`) |
|
||||
| **S-2** | `components/icons/index.ts` 出口(**AT-1**) | 图标字形名混进可读名称:`upload 导入脚本`、`down 导出`、`appstore 看板`、`search 图像` | 全站内带图标按钮的 AT 名称 | **高**(读屏天天听见) | 修法明确(图标 `aria-hidden`),但会牵动 R15 与 `classaudit` 第 2 闸,**必须单独一轮**;已登记 `docs/UI规范.md` §5.1.1 |
|
||||
| **S-3** | antd Tabs @430 | `rc-tabs` 溢出菜单(`…`)在小屏接管页签,键盘到不了被收起的页签需另验 | 430 带 Tabs 的页 | 中 | 下一轮:NEX_TABS 场景 + Tab 走位实测 |
|
||||
| **S-4** | `AppSider.tsx` + rc-menu 折叠弹层 | 折叠图标轨不渲染二级项 ⇒ 折叠态 AT 读不到「当前页」(弹层展开后正常) | ≥768 折叠档 | 低 | 需要改弹层渲染时机或给轨道项自绘状态;先观察 S-2 修完后的真实播报 |
|
||||
| **C-1** | `dist/assets/ui-*.js` 1187.8 kB | 构建期 `chunkSizeWarningLimit:1200` 警告仍在 | 首屏 | 中 | 按需入口对账 → 分组微调 → 抬阈值(须先有依据);本轮一条都没做(§6.3) |
|
||||
| **C-2** | `dist` 无 `.map` | chunk 归属分析每次要多跑一遍 `--sourcemap` 构建 | 分析效率 | 低 | 决定是否固定出 map |
|
||||
| **C-3** | CSS 75.8 kB(gzip 13.8)单块 | 与首屏同批下发,未按路由切 | 首屏 | 中 | 与 C-1 同轮,排第二优先级 |
|
||||
| **AT-2′** | VoiceOver 复听 | `aria-current` 已进 DOM(含折叠弹层),**VO 是否播报「当前页面」未复听** | 读屏导航 | 中 | 人工:V6 重跑 |
|
||||
| **N14** | 分镜卡 ⌥↑/⌥↓ 的 AT 播报与焦点跟随;NVDA + Chrome 全档 | **未验** | 键盘排序的主验收项 | **阻塞验收** | **MANUAL QA REQUIRED**——见 §7.4,Phase 8 因此不能标记完全通过 |
|
||||
|
||||
NEX 侧(不是本仓库)仍未落地的:N9 / N10 / N12 / N17。
|
||||
|
||||
---
|
||||
|
||||
## 10. 交付物索引
|
||||
|
||||
### 10.1 代码改动(16 项 = `frontend/src` 12 个文件 + `scripts/ui` 3 个(2 个新增)+ `nex.config.yaml`;全部在前端,后端 0 改动。净增按 `git diff --numstat` 的 +增/−删 记账)
|
||||
|
||||
| 项 | 文件 | 净增 | 干了什么 |
|
||||
|---|---|---|---|
|
||||
| 2 | `frontend/src/app/layout/PipelineConsole.tsx` | +53/−5(25 行决策注释) | 受控 Tooltip 三通道;`:focus-visible` 才弹;`canHover()` 触屏收口;`briefOpen` 收提示 |
|
||||
| 3 | `frontend/src/components/ui/Table.tsx` | +22/−1 | `useNarrowTable()`(`Grid.useBreakpoint().lg === false`,<992)总开关——**换列定义不换 DOM** |
|
||||
| 3 | `pages/project/Delivery.tsx` | +156/−5 | ⑥⑦⑧⑨ 窄档列方案 + ⑥ `#id 名称` 并列 |
|
||||
| 3 | `pages/project/Dispatch.tsx` | +124/−3 | ②③ 窄档列方案 + ③ 追加 ` · 状态 · stage` |
|
||||
| 3 | `pages/project/Review.tsx` / `Timeline.tsx` | +43/−2 / +42/−3 | ④ / ⑤ 窄档列方案 |
|
||||
| 3 | `pages/Dashboard.tsx` | +8/−2 | ① 卡片/表格边界 `max-sm → max-lg` |
|
||||
| 4 | `components/media/AudioPlay.tsx` | +28/−2 | `tabIndex` + `role=slider` 的 `valuemin/max/text` + `←→↑↓` 5% / `Shift` 20% / `Home` / `End`,`stopPropagation` |
|
||||
| 4 | `components/media/MediaLightbox.tsx` | +6/−1 | 只读进度从 `role=slider` 改 `role=progressbar`(假 slider 是 ARIA 谎报) |
|
||||
| 4 | `pages/AssetLibrary.tsx` | +11/0 | 三处 `aria-label`(选择素材 / 母版) |
|
||||
| 1+4 | `styles/app.css` | +11/0 | 唯一一处 CSS:`.ant-btn:has(> .nex-file-input:focus-visible)` 焦点环(FOCUS 判据咬出来的可复现缺陷) |
|
||||
| 5 | `app/layout/AppSider.tsx` | +18/−5 | `currentMark()` 给当前路由补 `aria-current="page"`;`useMemo` 依赖补 `pathname`;纠正文件头注释 |
|
||||
| 4 | `scripts/ui/semanticcheck.py` | **新增 1062 行** | 七条判据 NAME/HOTSPOT/TAB/FOCUS/ARIA/LIVE/STATES;旋钮 `NEX_WIDTH/NEX_THEME/NEX_ROUTES/NEX_TABS/NEX_NAMESTRICT/NEX_HOTSPOTSTRICT/NEX_FOCUS_DWELL` |
|
||||
| 4 | `scripts/ui/chunkinfo.mjs` | **新增 176 行** | 按 sourcemap 区间逐段计字节的 chunk 归属器 |
|
||||
| 4 | `scripts/ui/gateprobe.py` | +89/−8 | 加 3 条 semanticcheck 反例 → `GATEPROBE_OK 14/14` |
|
||||
| 4 | `nex.config.yaml` | +2/−1 | `ui_gates` 登记 semanticcheck(13→14 行) |
|
||||
|
||||
提交切分(`main`,基线 `5a10bfb`,逐项一个提交,14:49:45 → 14:50:30;均未 push):
|
||||
|
||||
| 提交 | 内容 | 文件面 |
|
||||
|---|---|---|
|
||||
| `a851eca` | 第 2 项:430 顶栏项目名三通道 | 1 |
|
||||
| `6334a4a` | 第 3 项:六张窄屏表逐表响应式 | 6 |
|
||||
| `357942b` | 第 4 项:semanticcheck + 咬出的 4 类真缺陷 + 闸登记 | 7 |
|
||||
| `2821475` | 第 5 项:`aria-current`(两状态本身零改) | 1 |
|
||||
| `4343702` | 第 6 项:chunk 归属测量脚本 | 1 |
|
||||
| `98ea70d` | 第 1 项 DEFERRED 的盘点 + 规范/映射/AGENTS 六处落点 | 3 |
|
||||
| `97513c6` | 本报告 | 1 |
|
||||
|
||||
合计(不含本报告)`19 files changed, +2177 / −54`:`frontend/src` 12 个文件 **+522/−29**(屏上真变的东西全在这 522 行里)、`scripts/ui` 3 个(2 新增)**+1327/−8**、三份文档 + `nex.config.yaml` **+328/−17**。本报告自己 615 行。
|
||||
|
||||
规范/映射/指令改动:`docs/UI规范.md` +316/−11(§1.1.2 CSS 组织与 DEFERRED、§5.1.1 AT-1 在册、§6.2.1 导航两状态 + AT 暴露规则、§6.5 完整名称三通道(Hover / Focus / Touch + `hover:hover` 能力门槛)、§13.2.1 窄屏表格九表方案 + 数据对账方法、§15.12/§15.13 探针、§16 十二步回归第 9/12 步对齐 13 道常驻探针)、`docs/NEX-对照与例外.md` +8/−3(阶段 8.5 决策落点 + HEAD↔工作树语义读数改成本轮实测口径)、`AGENTS.md` +2/−2(常驻探针计数与代码一致:13 道)。
|
||||
|
||||
### 10.2 证据目录 `reports/ui_evidence/nex-p8f/`
|
||||
|
||||
| 目录 | 内容 | 对应批准书 |
|
||||
|---|---|---|
|
||||
| `01-css-layer/` | 层叠清点(分层/未分层统计 + 优先级推断) | §1 DEFERRED 的依据 |
|
||||
| `02-topbar-name/` | 5 份 `after-*.json` + 11 张 PNG + `TOUCH-FIX-VERIFY.txt` + 4 个探针脚本 | §2 |
|
||||
| `03-tables/` | 9 对 BEFORE/AFTER(19 张)+ `DATA-INTEGRITY.txt` + `HEAD-COMPARE.txt` + HEAD 两档 tableaudit 日志 | §3 |
|
||||
| `04-semantic/` | 工作树与 HEAD 的 semanticcheck 日志、gateprobe、classaudit、补跑的 4 条账号页 | §4 |
|
||||
| `05-nav/` | README + `probe-output.txt` + `ARIA-CURRENT.txt` + 2 个探针 + 6 张截图 | §5 |
|
||||
| `06-chunk/` | 6 份读数(组成、前十大依赖、raw/gzip/brotli、before/after 首屏、口径修正对照) | §6 |
|
||||
| `07-screen-reader/` | README(含可照抄的人工脚本)+ 149 条真实播报 + 环境取证 + 3 张截图 | §7 |
|
||||
| `09-gates/` | 31 份闸门日志 + `SUMMARY.txt` + `RERUN-SUMMARY.txt` | §8 |
|
||||
| `10-preview-smoke/` | `preview_smoke.py`(含本轮补的 `preflight()`)+ 24 张 `dist` 预览截图(6 代表页 × {1440,430} × {dark,light}) | §8 最终产物烟测 |
|
||||
| `11-visualcheck-final/` · `11-visualcheck-main/` | 最终代码 / 主跑两轮各 120 张截图(`/private/tmp` 会被清,所以归档进证据目录) | §8.2 / §8.4 84⊂120 的图证 |
|
||||
|
||||
### 10.3 停止线
|
||||
|
||||
- 本轮到此为止:**未**做阶段 4–8 之外的批量 P2 整改、**未**动 Header/Sider/Content 尺寸、**未**换 UI 组件库、**未**升级技术栈、**未**碰后端/数据库/API。
|
||||
- **N14 真实读屏验证未完成 ⇒ 整个 NEX Phase 8 不标记为完全验收通过**(批准书 §9 末段)。
|
||||
- 下一步建议顺序(等确认,不自行开工):**S-2 图标 `aria-hidden` 一轮**(收益最大、面最窄)→ S-3 + T-1(读屏 × 表格/Tabs)→ C-1/C-3 分包 → L-1/L-2 层叠治理。
|
||||
Loading…
Reference in New Issue