docs(规范): 阶段 9–45 口径入册(含 §13.14 执行过程那条)+ 台账 E11 与落地追记

三份规范与 `nex.config.yaml` 必须和这一批代码同时落地,否则「文档与实现冲突」
的账会留给下一轮。

- `docs/UI规范.md`:§2 表/§5.1.2.1(32 档只属于页头与工具条独立动作,卡片内动作
  归位)/§12 与 §12.2/§12.3/§13.14(新增:折叠行本身就是可点的语义元素,
  同动作的文字胶囊是第二入口,总控台「展开/收拢执行过程」那颗去掉)/§15.1 与
  §15.14(12 族族账、`projectswitchcheck` 默认落盘口径)同步。
- `docs/NEX-对照与例外.md`:登记 E11(环节资产页不渲染 `Pager`、命中数住 `<BarRight>`
  的理由与证据位置),§7 变更记录补阶段 37–44 各行,末了加一条 2026-11-12 的落地
  追记——把本轮之前所有报告里「HEAD 仍是 `418fb6b`」「未 commit」那类句子统一改口径,
  并写清两条待办:本地未 push、`nex_design_system` 子仓库指针未 push。
- `docs/工程规范.md`:脚本准入与探针清单跟着第 14 道更新。
- `AGENTS.md`:常驻探针 13 道 → 14 道两处。
- `nex.config.yaml`:`icons` 一栏改为两级表的真实形状(core 54 只/extra 24 只/
  index 是桶/`_kit.ts` 不含图形,边界由 `classaudit` 附三守);`board` 断点注释改为
  实测的「看板卡宽地板 320→288(auto-fill,minmax)」;`ui_gates` 与 `verification`
  两条改为 12 族族账的实际读数口径。**改了尺子就要同步它**,这一条是项目级硬要求。
- `README.md`:补第 14 道探针那一行、初始口令改 `admin@123`、`seed.py install
  --reset-password` 的保守口径说明。

表格自检:`/usr/bin/python3 reports/ui_evidence/nex-p37/mdtablecheck.py docs/*.md
reports/*.md` → 文件=50、不符行=0(顺手把阶段 45 报告里代码段内那个裸 `|` 转义掉,
`新建项目|111x32` → `新建项目\|111x32`,GFM 表格里的 code span 同样要转义)。
main
mula.liu 2026-11-12 10:21:58 +08:00
parent 83ed9622ec
commit 3e94a79b89
6 changed files with 1136 additions and 84 deletions

View File

@ -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. 强制规则

View File

@ -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 <token>`。模型配置与账号管理(`/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 就停住,

File diff suppressed because one or more lines are too long

File diff suppressed because it is too large Load Diff

View File

@ -55,8 +55,7 @@ api/ → app/ → pages/ → components/{ui,forms,media}/ → theme/ · lib/ ·
| `api/` | 唯一的 `fetch` 出口(信封拆包、`detail`→`Error`、401 跳登录) | 业务分支、组件状态 |
| `app/` | 外壳:`router.tsx` 路由表 · `App.tsx` 布局与守卫 · `ErrorBoundary.tsx` 分包失败兜底 · `layout/` 顶栏侧栏与 `nav.tsx` 导航表(两级菜单的唯一来源) | 任何业务接口调用 |
| `pages/` | 一屏一文件;页面私有小组件与类名常量在文件底部 | 页面之间的互相 import |
| `components/ui/` | 控件出口 + 版式原语:对 antd 的唯一封装层(`Button` `Input` `Checkbox` `Menu` `Status` `Overlay`…)与自绘版式件(`Field` `Ctlbar` `FormGrid` `Table` `Steps` `Pager` `Rows` `Tabs`);页面只从这里取组件。
文件按职责分(阶段 6):`Panel` 容器与栅格 · `State` 六态表面 · `Info` 只读回显 · `Ctlbar` 控件栏与胶囊 · `Fields` 字段 · `Overlay` 浮层 · `Table` `Tabs` `Steps` `Rows` 列表族 · `grid.tsx` 铺列换算 · `tone.tsx` 反馈语义表;**出口只有 `index.ts` 一个**,页面从不 import 具体文件 | 业务字段名、接口路径、绕过 `theme/antd.ts` 直接改 antd 皮肤 |
| `components/ui/` | 控件出口 + 版式原语:对 antd 的唯一封装层(`Button` `Input` `Checkbox` `Menu` `Status` `Overlay`…)与自绘版式件(`Field` `Ctlbar` `FormGrid` `Table` `Steps` `Pager` `Rows` `Tabs`);页面只从这里取组件。文件按职责分(阶段 6):`Panel` 容器与栅格 · `State` 六态表面 · `Info` 只读回显 · `Ctlbar` 控件栏与胶囊 · `Fields` 字段 · `Overlay` 浮层 · `Table` `Tabs` `Steps` `Rows` 列表族 · `grid.tsx` 铺列换算 · `tone.tsx` 反馈语义表;**出口只有 `index.ts` 一个**,页面从不 import 具体文件 | 业务字段名、接口路径、绕过 `theme/antd.ts` 直接改 antd 皮肤 |
| `theme/` | 只有 `antd.ts` 一个文件:`buildAntdTheme(mode)`(本站对 antd 的**唯一**改动清单——品牌色、表面色、少量结构性 ComponentToken)· `applyRootVars(mode)`(`createRoot` 之前把 antd 算出的 token 以 `--ant-*` 铺到 `:root`)· `HEADER_HEIGHT`(外壳顶栏高度,全站唯一自留尺寸) | 任何 JSX、任何页面语义;`metrics.ts` `palette.ts` `css-vars.ts` 那三把自造尺子别再建回来 |
| `components/forms/` | 选择器族(`Select` `MultiSelect` `SecretInput` + `toOptions`) | 页面专属选项 |
| `components/media/` | 带全局状态的媒体件(`MediaThumb` `AudioPlay` `MediaLightbox` `VersionPanel` `WorkflowBar`) | 纯展示(那些进 `ui/`) |
@ -271,9 +270,7 @@ sudo ./scripts/server.sh systemd > /etc/systemd/system/nex-animation.service #
| 规则 | 写法 | 为什么 |
|---|---|---|
| `models/` | **`/models/`** 锚根 | `backend/app/models/` 是 ORM 代码目录,裸写会一起忽略 |
| `media/` | **`media/`** 任意层级 | 产物目录会漂(根 `media/`、在 `backend/` 下启动漂出的 `backend/media/`、
以后某个模块自带的 `.../media/`),只锚根就会把漂出去的副本提交进仓库;
斜杠结尾只匹配**目录**,`api/media.py`、`src/media.ts` 这类代码文件不受影响 |
| `media/` | **`media/`** 任意层级 | 产物目录会漂(根 `media/`、在 `backend/` 下启动漂出的 `backend/media/`、以后某个模块自带的 `.../media/`),只锚根就会把漂出去的副本提交进仓库;斜杠结尾只匹配**目录**,`api/media.py`、`src/media.ts` 这类代码文件不受影响 |
| `dist/` `reports/` `.local/` `.trash/` | 锚根 | 都是单点目录,没必要放开 |
不变量 5 就是这条口诀的自动执行:`.gitignore` 改坏时 `deploy.sh` 当场 die 并把吃掉的

View File

@ -46,7 +46,7 @@ frontend:
router_version: "6"
state_management: zustand
charts: none # 无图表依赖、无图表组件;Dashboard 的「趋势层」不适用
icons: "@ant-design/icons,且只在 components/icons/index.ts 一处 import(R11)"
icons: "@ant-design/icons,且只在 components/icons/ 目录里的两张表 import:core.ts(首屏外壳可达 54 只)/ extra.ts(只有懒页面要 24 只);index.ts 是桶(只转发 core),_kit.ts 不含图形(R11 · 阶段 25 起,边界由 classaudit 附三守)"
# 应用外壳:以下是本项目**已验证**的尺寸,NEX 的 64/260/80/16/1280 不适用于本项目
shell:
@ -68,7 +68,7 @@ frontend:
# 这五档 + 主阶梯由 classaudit.mjs 第 9 闸 BP 与 styles/index.css 的 --breakpoint-* 逐档对账。
breakpoints_registered:
insp-lg: 1400 # Storyboard.tsx 检查器宽度第一档
board: 1240 # Storyboard.tsx 看板卡宽 258→224 地板
board: 1240 # Storyboard.tsx 看板卡宽地板 320→288(auto-fill,minmax(地板,1fr),上限不写在轨道上)
insp-md: 1080 # Storyboard.tsx 检查器宽度第二档
insp-sm: 720 # Storyboard.tsx 检查器整屏 + 素材列表单列
agent: 620 # AgentConsole.tsx 指令折叠头整行折行
@ -100,7 +100,7 @@ frontend:
verification:
npm_scripts: [dev, build, typecheck, preview]
ui_gates:
- node scripts/ui/classaudit.mjs # 静态:9 道子闸(死类名/图标 import + 出口形状 ICONA/裸 button/浮层底部/antd import/反馈表面/标题图形/标签皮肤/断点对账)
- node scripts/ui/classaudit.mjs # 静态:12 族(9 条 + 附/附二/附三 = 死类名/图标 import/出口形状 ICONA/图标型控件命名 ICNN 四点/两级表边界/裸 button/浮层底部/antd import/反馈表面/标题图形/标签皮肤/断点对账)· 末尾 FAMILY 行是族账与退出码的同源凭据
- .venv/bin/python scripts/ui/visualcheck.py
- .venv/bin/python scripts/ui/tableaudit.py
- .venv/bin/python scripts/ui/gridcheck.py
@ -112,13 +112,25 @@ frontend:
- .venv/bin/python scripts/ui/footercheck.py
- .venv/bin/python scripts/ui/btnclustercheck.py
- .venv/bin/python scripts/ui/feedbackcheck.py
- .venv/bin/python scripts/ui/semanticcheck.py # 阶段 8.5 第 4 项:辅助技术语义与行为(AX 名称/热区/Tab/焦点环/ARIA/live/六态/字形名外泄 GLYPH)
- .venv/bin/python scripts/ui/gateprobe.py # 反向验证:证明闸门真的会红(17 条判据 = 16 页面 + 1 静态)
- .venv/bin/python scripts/ui/semanticcheck.py # 阶段 8.5 第 4 项:辅助技术语义与行为(AX 名称/热区/Tab/焦点环/ARIA/live/六态/字形名外泄 GLYPH/浏览器原生文件控件文案外泄 FILE/窄屏溢出页签键盘通道 TABKBD/antd 内置文案语言包回落 LOCALE)· 十一条判据(FILE = 阶段 35 · S-3 新增,两条一头一尾:DOM 侧 input[type=file] 必须自带含汉字 aria-label;AX 侧任何未忽略节点名称里不许出现 Choose File / No file chosen)
- .venv/bin/python scripts/ui/projectswitchcheck.py # 阶段 33 第 14 道:换项目时的数据生命周期(① 不残留上一个项目的节点 / ② 详情 404 必须认错且切回能恢复 / ③ 静置跨一轮 6 s 轮询不许闪)· 退出码 = 缺陷条数,凑不出两个节点指纹不同的项目 ⇒ EXIT=2 说「无法判定」,不伪装成绿 · 口径 docs/UI规范.md §15.14、行为 §13.13
- .venv/bin/python scripts/ui/gateprobe.py # 反向验证:证明闸门真的会红 · 29 条判据(19 条页面判据(18 条 fixture + ⑱ 真组件溢出页签 TABKBD)+ 整名一条 ⑲(两腿算一条)+ 静态八条 ⑰ 图标出口形状 / ㉒ 产物预算 / ㉓ 图标命名 / ㉔ AT 图形中文名 / ㉖ 图标登记表两级表 / ㉗ 归属尺自证空转 / ㉙ S-2 宿主级缺名 / ㉚ 原生文件控件文案)+ 探测器自证一条 ㉘ `projectswitchcheck.matches`(与 docs/UI规范.md §15.12 同口径;条数以末行为准))· 阶段 35 实测 `GATEPROBE_OK 29/29`、`grep -c '^OK'` = 205(阶段 34 的 198 + 7 条 ㉚三坏四好)· ⚠ 末行分母是 `len(checks) + 11` 这个加出来的常数,加判据必须同时抬它(阶段 35 之前它停在 +10,末行连着谎报 28/28)· 阶段 34 实测 `GATEPROBE_OK 28/28`、`grep -c '^OK'` = 198(+ 12 条 ㉙七坏五好)(阶段 32 的 184 + 2 条 ㉘,阶段 31 的 180 + 4 条 ㉓ 第四支)、FAIL 0(阶段 31 是 180 = 阶段 25 165 + 15 条 ㉗) · 实数看末行 GATEPROBE_OK N/N 与 grep -c '^OK'
# 产物级闸(不吃页面、跑在 dist 上):改分包 / 动依赖 / 调预算时必须跑,见 docs/UI规范.md §13.11
artifact_gates:
- node scripts/ui/chunkbudget.mjs # 逐文件 raw 预算闸(kB=1000B,与 vite 控制台同尺)。上限三层来源:显式 --config > 构建器落盘 dist/.vite/rollup.config.json > 项目登记 frontend/chunk-budget.json;三层都没有才 DEGRADED + 兜底 1500 kB(退化≠放宽)。阶段 24 起真产物走第三层,不再长期挂 DEGRADED
- node scripts/ui/chunkinfo.mjs # 首屏闭包成分与三压缩口径读数(只读,恒退出 0)。⚠ 单位 n/1024 却标 kB,与上一条差 2.4 %,引用数字必须带工具名。归属段(只有带 .map 的产物才跑)自报三行机器可读读数 `ATTRIB_COVERAGE` / `ATTRIB_SUSPECT` / `ATTRIB_VERDICT=OK|SUSPECT|IDLE`(阶段 31:覆盖率 < 60 % ⇒ IDLE = 自证空转,那句「没有伪像」会被撤掉,别引用本轮归属读数);可选 `SOURCE_CHECK_STRICT=1` 把 IDLE/SUSPECT 升级成退出码 1,不设时本尺恒退出 0;`SOURCE_CHECK_MIN_COVERAGE` 可改门槛(默认 60)
- .venv/bin/python reports/ui_evidence/nex-p22/productsmoke.py # 真产物 :4173 上 14 路由 × 明暗冒烟(自带 /api 中继:vite preview 不代理 /api)
- .venv/bin/python reports/ui_evidence/nex-p22/lazyloadcheck.py # 真产物 :4173 上的懒加载结构判据 A/B/C1–C4/D + 录制全流程真点(判据以 DOMContentLoaded 为界,用 FCP 必假红)
# 只读普查,不进串行、无退出码:scripts/ui/census-icons.py(图标字形名现状量级,S-2 立项与收口对账用)
baseline: 14 路由 × {1440,768,430} × {light,dark} = 84 个状态
# 阶段 43 待授权(未升常驻,不进上面的串行清单):reports/ui_evidence/nex-p43/n14announce.py
# N14 播报保序尺——量同一次按键里「焦点回到卡片」与「live region 出现该文案」谁先发生;
# `--expect=after` 断言新顺序,`--expect=before` 是反向对照(新码上必须红,否则尺子不会红)。
# 升 scripts/ui/ 需单独授权(阶段 41 口径:新尺先在证据层跑住,再谈常驻)。本轮读数 rc=0 / rc=1(设计如此)。
baseline: 15 路由 × {1440,768,430} × {light,dark} = 90 个状态 # 阶段 4 起兜底页 /not-a-page 进 visualcheck 名单(14 → 15);更早的 84 状态基线逐条仍可对照
flow: docs/UI规范.md §16(十二步改动流程,改尺子必须全量回归含 430/576)
dev_base_url: http://127.0.0.1:5199 # :5173 是陈旧实例;:8000 被别的项目占用
dev_backend_port: 8010
dev_base_url: http://127.0.0.1:5173 # 2026-11-08 实测更正:`vite.config.ts:18` 的 `server.port` 就是 5173,闸门默认值(`semanticcheck.py` 与 `gateprobe.py` 里 `BASE` 的默认值)也是它。
# 旧口径写的 :5199 / :8010 是当时手工起的实例,不是配置里的端口——:5199 的代理上游此刻已 502,照旧口径起服务会让所有页面闸门拿不到数据。
dev_backend_port: 8000 # `vite.config.ts:10` 的 proxy target(默认 127.0.0.1:8000,可用环境变量 NEX_BACKEND 覆盖);:4173 是 preview,`vite.config.ts` 没有 preview.proxy,预览页无数据
# ── 项目必须达到的设计/体验结果(Agent 视为实施约束,不是参考建议)──────────
requirements: