diff --git a/AGENTS.md b/AGENTS.md index 3baf7d7..7f99fc9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -9,7 +9,7 @@ | 层 | 文件 | 负责什么 | |---|---|---| -| 1 | `docs/UI规范.md` | **项目级 UI/UX 权威**:20 条硬规则 R1–R20、§1–§16 全部尺子与口径、13 道常驻探针、十二步改动流程 | +| 1 | `docs/UI规范.md` | **项目级 UI/UX 权威**:20 条硬规则 R1–R20、§1–§16 全部尺子与口径、14 道常驻探针、十二步改动流程 | | 2 | `docs/工程规范.md` | 目录职责、脚本准入、代码风格、部署、删除策略、最低验收 | | 3 | `docs/NEX-对照与例外.md` | NEX 逐条判定(COMPLIANT / ADOPTED / ADAPTED / DEFERRED / NOT APPLICABLE)与**项目级例外登记**;NEX 与本项目冲突时按此文件执行 | | 4 | `nex.config.yaml` | 项目现状声明(真实尺寸、真实技术栈、真实检查命令)。改了布局尺寸必须同步它 | @@ -41,7 +41,7 @@ - **Empty 三分类**:没数据 / 没匹配 / 引导下一步,文案分开,且能清除筛选恢复默认。 - **反馈四级表面**(R19):`ErrorText`/`LineHint` → `Notice` → `notify*` 吐司 → `confirmAction`。长任务唯一进度源是顶栏「平台动态」(§13.7),页面内不得再放第二个进度条。 - **专业工作区交互**:分镜卡拖拽、时间线、录音、素材灯箱、版本面板的既有操作路径。 -- **质量闸门**:13 道常驻探针 + §16 十二步流程。这是 NEX 10「阶段 5 质量门禁」的现成实现,复用而非重造。 +- **质量闸门**:14 道常驻探针 + §16 十二步流程。这是 NEX 10「阶段 5 质量门禁」的现成实现,复用而非重造。 - 本项目**没有**文档阅读 / PDF 预览 / AI Chat 工作区,不要为对齐 NEX 引入相应模板、布局或图表依赖。 ## 3. 强制规则 diff --git a/README.md b/README.md index a081955..bdd9d50 100644 --- a/README.md +++ b/README.md @@ -125,6 +125,7 @@ NEX_WIDTHS=1440,992,768,430 NEX_THEMES=dark,light \ .venv/bin/python -u scripts/ui/aligncheck.py # 同一行同心 + 只读胶囊字重(R3 · R20) .venv/bin/python -u scripts/ui/symmetrycheck.py # 跨页同一把尺:门牌标题左缘 / 标题行中线 / 主操作右缘三个集合必须各是单值(R20) .venv/bin/python -u scripts/ui/feedbackcheck.py # 吐司 / 确认框运行时复验(R19,明暗各一遍) +.venv/bin/python -u scripts/ui/projectswitchcheck.py # 改了项目数据生命周期(详情 store / 切换与轮询)再跑这条:换项目不残留、404 认错、静置不闪 ``` 体检默认量 dev server(5173):**`console` 那一项只能在 dev 上量**——React 与 antd 的告警是 @@ -256,7 +257,7 @@ HTML5 拖拽改镜序、Shift 范围勾选、批量复制/移到最前/统一改 - mDNS 机器名(`http://<名>.local:5173`)已在 `frontend/vite.config.ts` 的 `server.allowedHosts: ['.local']` 里放行;换成自定义域名仍需显式加白名单, 否则 Vite 会返回 403 `Blocked request. This host (...) is not allowed.`。 -- 🔒 鉴权默认开启(`AUTH_ENABLED=true`):首次启动自动播种管理员 `admin` / 初始口令 `admin1234` +- 🔒 鉴权默认开启(`AUTH_ENABLED=true`):首次启动自动播种管理员 `admin` / 初始口令 `admin@123` (`app/services/auth.py:bootstrap`,登录后应立即改密),会话走 `nex_session` Cookie, 脚本也可以用 `Authorization: Bearer `。模型配置与账号管理(`/api/providers`、`/api/users`) 只有管理员能写,观摩/制作角色可看可拍但不能改全平台配置。 @@ -436,7 +437,7 @@ curl -s localhost:8000/health | jq '.executor,.ffmpeg_capabilities,.auth_enabled curl -s localhost:8000/api/auth/state | jq '.auth_enabled,.login_hint' # 未登录也返回 200 # 读业务接口前先登录拿 Cookie(账号口令就是首启播种的那一对): curl -s -c /tmp/nex.jar -H 'content-type: application/json' \ - -d '{"username":"admin","password":"admin1234"}' localhost:8000/api/auth/login > /dev/null + -d '{"username":"admin","password":"admin@123"}' localhost:8000/api/auth/login > /dev/null curl -s -b /tmp/nex.jar localhost:8000/api/meta | jq '.presets,.options.transition' ``` @@ -491,6 +492,16 @@ sudo ./scripts/server.sh systemd > /etc/systemd/system/nex-animation.service \ (`seed.py` 与 `server.sh` 都收这个开关)只补缺、不覆盖同名配置,`--dry-run` 先看将要发生什么, 主密钥冲突时区分「没有解密依赖 → 换」与「有依赖 → 中止等你决策」。 +管理员口令走同一套保守口径:`install` **默认不改已存在账号的口令**(这台机器可能早改过, +覆盖成开发机的口令是反直觉的倒退)。所以在开发机改了 `admin` 口令、重新 `export` 之后, +服务器上要多跑一次才会对齐: + +```bash +docker compose exec app python scripts/seed.py install --only-missing --reset-password +``` + +新库(`./data` 是空的)不需要这条:数据包里没有的账号会按包里的哈希直接建出来。 + **数据集与代码必须对得上**:`deploy.sh --check`、`deploy.sh` 打包、`seed.py install` 装库之前, 跑的都是同一个 `doctor`(列对得上表结构 / 适配器在代码里注册过 / `modes` 不比适配器声明的能力少 / 每类能力有且仅有一个默认 / 包里的密文能被包里的主密钥解开)。任何一条 error 就停住, diff --git a/docs/NEX-对照与例外.md b/docs/NEX-对照与例外.md index 707c1d1..2c9f584 100644 --- a/docs/NEX-对照与例外.md +++ b/docs/NEX-对照与例外.md @@ -15,7 +15,7 @@ - 反向清单:本轮实施中发现**需要 NEX 自己修订或补充**的地方(§5),以及尚未收敛的漂移(§6)。 **不是:** -- ❌ 不是第二份 UI 规范。尺子、口径、20 条硬规则、13 道探针仍然只在 `docs/UI规范.md`,本文件**不重复制定数值**,只做判定与引用。 +- ❌ 不是第二份 UI 规范。尺子、口径、20 条硬规则、14 道探针仍然只在 `docs/UI规范.md`,本文件**不重复制定数值**,只做判定与引用。 - ❌ 不是改造任务清单。改造计划见 `reports/NEX设计审计与改造计划-2026-11-07.md`。 - ❌ 不是 changelog 替代品。改了尺寸/机制,先改 `theme/antd.ts` 与 `UI规范.md`,再回来更新本表受影响的那一行。 @@ -143,9 +143,9 @@ NEX 与本项目差异用「项目适配」解决,**不得反向修改本项 | NEX 条款 | 状态 | 本项目出处 | 理由 | |---|---|---|---| | §1 语义化交互(不用 `div + onClick`) | **ADOPTED(原则)**;3 处热区 **本轮阶段 2 修** | `Storyboard.tsx:1915`(`
`)、`ui/Rows.tsx:11`(`
`)、`AppHeader.tsx:60,70`(`Avatar`/`Text` 当链接)——**行号为阶段 0 记录值**;阶段 2 之后三处已分别变为 `Storyboard.tsx:1915+`(带 `tabIndex`/`onKeyDown`)、`ui/Rows.tsx:27`(`clickable` 分支)、`AppHeader.tsx:70`(已是真 ``) | 原则完全接受;存量违规仅这 3 处(已核实:`MediaThumb.tsx:106`、`AudioPlay.tsx:68`、`MediaLightbox.tsx:186` 均已带 role/tabIndex/aria-modal,**不是**问题) | -| §1/§2 控件的可读名称必须是自然语言——装饰图形的**字形码不得混入**(`upload 导入脚本`) | **COMPLIANT(阶段 8.5.1 · S-2 修)**;antd 内部图形的英文宿主名称另记 §6 一条漂移 | `components/icons/index.ts`(全站唯一图标出口,79 条一律 `decorative(Glyph,'IconX')`,**三档口径**:默认 `aria-hidden` / 显式 `aria-label` 走具名 / 显式 `aria-hidden={false}` 尊重调用方)、`ui/Input.tsx`(搜索按钮「搜索」+ 清空键「清空搜索」)、`ui/Ctlbar.tsx::Pager`(`itemRender` → 上一页/下一页)、`ui/Tabs.tsx`(溢出「更多页签」)、`forms/SecretInput.tsx`(「显示/隐藏密码」两态);两道机器闸:`classaudit` 第 2 闸 `ICONA`(源码侧出口形状)+ `semanticcheck` 第 8 条 `GLYPH`(DOM 侧字形码),`gateprobe` 配静态反例 | NEX 08 说「名称要能读」但没说什么算泄漏。本项目的口径是**两头都不许一刀切**:既不许批量 `aria-hidden`(那会把 42 处「图标是宿主唯一语义」变成没有名字),也不许给图标补 `aria-label={字形名}`(那正是缺陷本身)。改前 1 072 条图标读数里 **900 只**把字形码念出去、**42 只**是宿主唯一名称来源 → 改后 **80 / 0**;4 处调用点原本就写着 `aria-hidden` 的照旧尊重(不是批量加的) | +| §1/§2 控件的可读名称必须是自然语言——装饰图形的**字形码不得混入**(`upload 导入脚本`) | **COMPLIANT(阶段 8.5.1 · S-2 修)**;antd 内部图形的英文宿主名称另记 §6 一条漂移 | `components/icons/index.ts`(全站唯一图标出口,78 条一律 `decorative(Glyph,'IconX')`——阶段 8.5.1 落地时是 79 条,阶段 24 删掉一条 0 引用的死出口 `IconArrowBack` 后为 78 条,口径一字未改),**三档口径**:默认 `aria-hidden` / 显式 `aria-label` 走具名 / 显式 `aria-hidden={false}` 尊重调用方)、`ui/Input.tsx`(搜索按钮「搜索」+ 清空键「清空搜索」)、`ui/Ctlbar.tsx::Pager`(`itemRender` → 上一页/下一页)、`ui/Tabs.tsx`(溢出「更多页签」)、`forms/SecretInput.tsx`(「显示/隐藏密码」两态);**六道**机器闸(阶段 23 时四道、阶段 32 加 `ICNN` 成五道、阶段 34 加 `GLYPH 5d` 成六道):`classaudit` 第 2 闸 `ICONA`(源码侧出口形状)+ `semanticcheck` 第 8 条 `GLYPH` 的 **DOM 支**(字形码挂在 `aria-label` 上,且等于自己的类名后缀 `anticon-<码>`)+ 同一条判据的 **整名支**(拿 CDP AX 树里辅助技术**真读到的**整条名称撞登记表——`ellipsis` 那种「只念出一个英文单词」= 等于没有名称,`NAME` 查不出;两支共用判据函数 `whole_glyph_name`,阶段 10 补)+ **阶段 23 补第五道** `semanticcheck.GLYPH` 的 **5c 支**(AT 树里**看得见**的 `anticon` 图形必须中文报名:宿主**已经**具名时,里面那颗 `role=img aria-label="up\|down\|left\|right"` 仍是独立的播报对象,念完宿主再补一句英文;①②③④ 一支都看不见它——`ax_names()` 只收 INTERACTIVE 角色,登记表名单是**语义别名**(`chevron-left`)撞不中 antd 用的**字形本名**(`left`))+ **阶段 17 复扫补第四道** `classaudit` 第 2 条·附二 `ICNN`(源码侧「图标型控件必须报名」:自关闭的 `} />` 既无 `aria-label` 又无 `title` ⇒ 立案;`` 的字面量无汉字或为空串 ⇒ 立案)——前三道量的是「名字写错了」,第四道量的是「名字根本没写」,第五道量的是「宿主报对了名字、图形却在旁边自己出声」、第六道量的是「图形消音之后宿主没报名」(阶段 34,见本格末段):`decorative()` 撤掉字形名之后宿主只剩`aria-label`/`title` 两条命名通道,而这一族控件约一半住在**要点开才进 DOM** 的浮层里,常驻浏览器探针跑的是 15 条路由的关闭态,结构上量不到(浮层实测:阶段 17 `s2overlay.py`);六道的反例分别钉在 `gateprobe` 判据 ⑰ / `GLYPH` / ⑲ / ㉓ / ㉔ / ㉙ | NEX 08 说「名称要能读」但没说什么算泄漏。本项目的口径是**两头都不许一刀切**:既不许批量 `aria-hidden`(那会把 42 处「图标是宿主唯一语义」变成没有名字),也不许给图标补 `aria-label={字形名}`(那正是缺陷本身)。改前 1 072 条图标读数里 **900 只**把字形码念出去、**42 只**是宿主唯一名称来源 → 改后 **80 / 0**;4 处调用点原本就写着 `aria-hidden` 的照旧尊重(不是批量加的)。**阶段 10 真机复验**(本机 `:5173` + 后端在线,非早先那份失效快照):交互元素的可访问名称里含字形码 只剩 `/help` 正文里那条链接 `/api/meta`(撞中的是 `api`,是内容不是图标名 → 归打印不立案),溢出「…」那颗的名称经 name-from-contents 解析成「更多页签」;DOM 里 0 个 PUA 私有区字符(图标全是 SVG)。读屏真机验收的边界**没有因为复验而缩小**:VoiceOver + Safari 18.3 实听过 8 处修复 / 10 组对照,分页两颗、「清空搜索」、「显示/隐藏密码」、窄视口「更多页签」这 4 处与 **NVDA + Chrome 全家仍未执行 → MANUAL QA REQUIRED**(见 §6 签字口径行) **阶段 10 把这条口径推回上游**:NEX 子仓库 `10ccdc1` 给 `08-accessibility-responsive.md` §1 补了两条——「控件**整条**可读名称就是图形内部标识(字形码 / 图标 key / 枚举值 / 状态码)→ 按无名处理,判定口径是整条不是包含」与「默认装饰、语义由宿主说、两头都不许一刀切」。上面那句「NEX 08 说了要能读但没说什么算泄漏」自此不再是规范缺口。**阶段 23 收口(口径补第四条:宿主具名 ⇒ 图形消音)**:`GLYPH` 5c 上线后全站量到 **1440 与 430 各 72 颗** AT 看得见、整条名称无汉字的 `anticon` 图形(34 `up` + 34 `down` + 2 `left` + 2 `right`;`DOM.getOuterHTML` 对不上号 0 颗 ⇒ 不是采集失败的假数),浮层里另有 20 颗(12 步进 + 8 分页,常驻探针量不到那一段)。三处 kit 收口、页面 0 改动、只写 aria 属性:`ui/Input.tsx::renameStepHandlers()` 给已具名宿主内部的 `[role=img]` 消音、`ui/Ctlbar.tsx::pagerLabel()` 连箭头图形一起 clone 成 `aria-hidden`、`ui/Ctlbar.tsx::TagChip()` 的 `closeIcon` 从「不写名让 antd 兜『关闭』」改成显式 `aria-label="移除"`(这一处不是无名,是**泛化名精确化 + 命名权从 antd 版本实现细节里拿回来**:5.29 `_util/hooks/useClosable.js` 才有那段 `?? locale.close` 兜底)。**没有批量 `aria-hidden`**:登记表第 ② 档那几只「图标就是全部语义」的出口照旧具名;`s2c` C 支复核后 190 条 `INVISIBLE_OP` 全部落在口径外(142 `ant-select-arrow` 本就 `aria-hidden` + 24 `.nex-stat-mark` 装饰 + 24 只有文字的宿主),维持不改。已知缺口登记:Tag ✕ 那颗 `tabindex="-1"` ⇒ 名称修好了、键盘仍够不到(修它要换 DOM);`NAMED_SUB` 168 条名字挂在 antd 裸 `` 的图标上,念得出内容听不出「可点击」。读屏真机仍未执行 ⇒ **MANUAL QA REQUIRED**。取证 `reports/ui_evidence/nex-p23/`、报告 `reports/NEX阶段23-S2收口与图标宿主具名-2026-11-09.md`。**阶段 32 复扫(2026-11-10 · 只补尺子与文档,`frontend/src/**` 一字未改)**:第四道 `ICNN` 补齐**第四子判据 ④**——图标写在 **children** 里的图标钮(``):附二① 的「自关闭 + icon 槽」两条前提一条都不成立,可结论一模一样——图标默认 `aria-hidden` ⇒ 宿主在 AT 树里没有名字,而 DOM 侧的 `NAME` 只在浮层**打开时**才量得到。判据保守到只咬「非自关闭 + 开标签无 `aria-label`/`aria-labelledby`/`title` + children 里每个开标签都是登记表图标 + 无裸文字 + 无可能出字的表达式」,表达式只放行四种形状(整段一只图标 / 成对圆括号 / `cond ? 图标 : 图标` / `cond && 图标`,分支递归判定),`{row.label}`、字符串字面量、函数调用、`` 包的字一律**跳过不判**(「看不出有没有名字」不是「没有名字」,误报的下场和漏报一样是这条闸被关掉)。这一支自带采到凭据 `ICNN-COVER childIcon=N named=M missing=K`:现网 **N=4 / named=4 / missing=0**(`media/AudioPlay.tsx:79` 播放·暂停、`media/MediaLightbox.tsx:266` 与 `:323` 上一张·下一张、`media/MediaThumb.tsx:163` 删除这个素材,四颗全部已具名 ⇒ 立案 0);另一把**独立**尺(`reports/ui_evidence/nex-p32/icononly.py` 源码普查)同批读数 `DEFECT=0`(`UNKNOWN=3` 全是 `pages/Help.tsx` 的文字链接,不属这一族;`VARNAMED=32` 是名字来自变量或跨行属性、静态读不出字面量的图标钮 ⇒ 交 DOM 侧 `NAME` 与 `ICNN-COVER` 合起来管,不在源码侧猜)。反例钉在 `gateprobe` ㉓:坏形状加 `N`(children 裸图标)/ `O`(children 是换图形三元)必须逐条点名,好形状加 `U`/`V`/`W`(名字写在宿主上)必须**被覆盖率行采到**、`X`/`Y`/`Z`/`AA`(会出字的四种)必须整片跳过,并断坏面 `childIcon=2 named=0 missing=2`、好面采到下限。**这一轮反例第一跑就抓到两条探针自身的接线缺陷**(`gateprobe.log` 11:46 `EXIT=1`):① 「真文件面必须静」那条把标记写成裸 `ICNN`,是新增覆盖率行 `ICNN-COVER` 的前缀,好面只要跑起来就必红;② 「好面采到下限」那条把标记写成了给人看的口径描述(`childIcon>=3 且 …`),而 `verdict()` 是 `marker in hay` 的字面子串匹配,输出里永远是具体数字 ⇒ **好面越健康这条腿越必红**。两条都按「不放宽判据」修(① 改钉点名行前缀 `ICNN ` 两颗空格;② 改钉覆盖率行原文、数值下限留在 hay 取值里),并各配一条突变测试自证没被改成恒绿(采集打成 `childIcon=0` ⇒ cover-good 红;好面塞一行 `ICNN Overlay.tsx…` ⇒ real 红)。修后 `gateprobe2.log` 11:49:32 **`GATEPROBE_OK 26/26`、`FAIL` 0、`grep -c '^OK'` = 184**(阶段 31 的 180 + 4,4 条全在 ㉓ 第四支)。**「批量给图标加 `aria-hidden`」这条路本轮仍然没走**:登记表第 ② 档那 5 只「图标就是全部语义」的出口照旧具名。取证 `reports/ui_evidence/nex-p32/`、报告 `reports/NEX阶段32-S2复扫与图标子节点命名闸-2026-11-10.md`。**阶段 34(2026-11-10)把 §7 里那条「672 条宿主没补名 · 待定性」结掉,结论是尺子错、不是页面错**:阶段 32 的活体尺把句柄打在图标 `` 上、读的是 span 自己的 AX 名,于是宿主已具名的 `ant-btn-icon` 内层也被记成缺名。换成**宿主级**活体尺 `reports/ui_evidence/nex-p34/s2host.py` 复量(1440 / 430 两宽 × 明暗 × 关闭态 + 浮层打开态 + `NEX_INTERACT=1` 交互态补量,八轮)⇒ **缺名图标控件 0 条、对账八轮全平 ⇒ 业务代码一字未改**(`frontend/src/**` 零改动,本轮没有视觉与交互变化)。常驻判据补 `semanticcheck.GLYPH` **第五支 5d** `nameless_icon_host`(AX 树里未被忽略、整条名称为空的可操作控件回查 DOM 有无图标;没图标交还 `NAME` 闸,不重复立案),反例 = `gateprobe` 判据 ㉙(七坏五好,`GATEPROBE_OK 28/28`、`grep -c '^OK'` = 198、`FAIL` 0);定点前后对照 = `s2names.py` 十条 × 明暗 × 两宽(阶段 8.5 真机念到的 `book 手册` / `upload 导入脚本` / `down 导出` 今天分别是「手册」role=link、「导入脚本 / 关键帧」role=button、「导出」role=button,图标一律 `aria-hidden`)。**没有新增第 15 道常驻探针**(普查尺留 evidence 侧,与 `s2surface` / `iconkbd` 同一先例)。新登记三条见 §6(`S-2-2` 抽屉 ✕ 的名字是面板名不含动作 / `S-2-3` `nex-file-input` 的 `Choose File` / `S-2-4` 交互态口径)。取证 `reports/ui_evidence/nex-p34/`、报告 `reports/NEX阶段34-S2宿主级复量与第五支闸门-2026-11-10.md`。 | | §2 焦点与键盘 | COMPLIANT(阶段 2 三处热区可键盘化 + **阶段 8 补排序键盘替代 N14**) | `app.css` 全站 `:focus-visible` 兜底;`ui/Table.tsx`、`MediaThumb.tsx`、`AgentConsole.tsx` 键盘处理;`lib/layers.ts::floatingLayerOpen` 分层 Esc;`Storyboard.tsx::moveByKey` + `ShotCard` 的 `aria-keyshortcuts` / `aria-describedby` | 拖拽排序的键盘替代 NEX 原本未覆盖 → **N14**,阶段 2 只做授权内的 3 处热区,**阶段 8 用户批准后落地**(`⌥↑` / `⌥↓`,实测见 `reports/ui_evidence/nex-p8/n14/`),并反向提交给 NEX `08` §2(子仓库提交) | -| §2/§3/§5 的**验收手段**(可访问名称 / 焦点可见 / 状态播报 / 空错载 是否真成立) | **COMPLIANT(阶段 8.5 起有机器证据 · 阶段 8.5.1 加第 8 条 GLYPH)**;软档 20 颗/主题待 P2 | `scripts/ui/semanticcheck.py`(第 13 道常驻探针,八条判据 NAME/HOTSPOT/TAB/FOCUS/ARIA/LIVE/STATES/**GLYPH**,全部走 CDP 的 AX 树与真按键,不读源码字符串)、`UI规范.md` **§15.13**、本轮两处真缺陷修复 `pages/AssetLibrary.tsx:1217/1274/1359`(三颗裸 `Checkbox` 补 `aria-label`)、`styles/app.css:519`(`:has()` 补回被全局复位吃掉的上传按钮焦点环)、`scripts/ui/census-icons.py`(立项前只读普查,恒返回 0,不进串行) | NEX 08 只列要求、没给「怎么证明」,此前本项目也只在源码里数 `aria-*` 字符串——实测这种数法**两个真缺陷一个都抓不到**(D-A 旁边有文字、D-B 病灶在 CSS)。HEAD `5a10bfb` 同尺对照:改前硬档 **58 条**(NAME 20 / HOTSPOT 16 / TAB 16 / FOCUS 6,1440 与 430 两档读数相同)→ 工作树改后硬档 0;那 40 条 NAME 软档(20 每主题)不计退出码;剩下的软档 19 类同一根因:`ui/Fields.tsx::Field` 孤立使用 antd `Form.Item`(外层无 `
`)⇒ `