diff --git a/docs/NEX-对照与例外.md b/docs/NEX-对照与例外.md index c139f1f..7f9fdfb 100644 --- a/docs/NEX-对照与例外.md +++ b/docs/NEX-对照与例外.md @@ -104,7 +104,7 @@ NEX 与本项目差异用「项目适配」解决,**不得反向修改本项 | §3.3 NexDataTable | COMPLIANT | `ui/Table.tsx`(含键盘行导航)+ R17 行高预算 | 超出 NEX 要求:常驻 `tableaudit.py` | | §3.4 NexStatCard | COMPLIANT | `ui/Panel.tsx::Stat/StatGrid` + R16 纯色统计卡 | — | | §3.5 NexModal / NexDrawer | COMPLIANT | `ui/Overlay.tsx::{Modal,Drawer,Scrim,ConfirmHost}` + `DRAWER_HEAD/BODY/ACTIONS` | 三段式与底部动作条口径由 `classaudit` 第 4 闸验 | -| §3.6 NexPageState | 部分 COMPLIANT;余下 **DEFERRED → 阶段 4** | `ui/Panel.tsx::{Empty,Loading,Notice}`、`ui/Button.tsx::ErrorText` | Empty **三分类**(没数据/没匹配/引导)是本项目成熟设计,保留。缺 Forbidden / Not Found 专用态与 **Skeleton**(NEX 自身也未要求 → 反向缺口 **N9**) | +| §3.6 NexPageState | **COMPLIANT**(阶段 4) | `ui/Panel.tsx::{Empty,SkeletonBlock,Notice}`、`ui/Button.tsx::ErrorText`、`pages/{Forbidden,NotFound}.tsx`、`UI规范.md` §13.8 | Empty **三分类**(没数据/没匹配/引导)是本项目成熟设计,保留(ADAPTED)。阶段 4 补齐六态表面:首屏 `SkeletonBlock`(路由兜底 / 页面首屏 / 抽屉正文三类落点)、权限不足 `Forbidden`、地址不存在 `NotFound`(`path:'*'` 不再静默跳首页,`visualcheck` 名单 +1 条并断言文案)。旧 `` 随最后一处首屏调用一起删除 | | §4 NexDocus 现有组件迁移映射 | **NOT APPLICABLE** | — | 映射表左列是 NexDocus 的组件名 | | §5 组件代码约定 | COMPLIANT | `UI规范.md` §0 R10(ref 透传契约)、R8(`app.css` 是全站唯一 `.ant-*` 出口)、组件不内聚数据请求 | — | | (隐含)组件以 npm 包形式提供 | **ADAPTED**(E7) | `nex.config.yaml` `components.nex_react_package: forbidden` | 用本项目 kit,不引入第二套 NEX React 组件包 | @@ -119,7 +119,7 @@ NEX 与本项目差异用「项目适配」解决,**不得反向修改本项 | §4 搜索与筛选 | COMPLIANT | `UI规范.md` §12(筛选器准入清单)+ `ChipBar`/`Pager` | — | | §5 表格交互 | COMPLIANT | `UI规范.md` §0 R17 + `tableaudit.py` | — | | §6 Modal / Drawer / Page 选择 | COMPLIANT | `UI规范.md` §10(挂载点定死 + 三段式 + `floatingLayerOpen()`) | — | -| §7 反馈状态 | **ADAPTED**;余下 **DEFERRED** | `UI规范.md` §13.3(R19 四级表面:`ErrorText`/`LineHint`→`Notice`→`notify*`→`confirmAction`)、`§13.7` 唯一进度源 | 本项目把反馈表面分得比 NEX 更细并有 `feedbackcheck.py` 钉住。缺:Disabled 须说明原因、Skeleton(→ 阶段 4);Toast 量化门槛 NEX 自身未定义 → **N10** | +| §7 反馈状态 | **ADAPTED**(Skeleton 已补 · 阶段 4) | `UI规范.md` §13.3(R19 四级表面:`ErrorText`/`LineHint`→`Notice`→`notify*`→`confirmAction`)+ `§13.8` 六态表面、`§13.7` 唯一进度源 | 本项目把反馈表面分得比 NEX 更细并有 `feedbackcheck.py` 钉住。Skeleton 已按「首屏 / 局部」两类落地点补齐(§13.8);Disabled 须说明原因仍是软约定(无探针);Toast 量化门槛 NEX 自身未定义 → **N10**(→ 阶段 5) | | §8 主题切换 | COMPLIANT | `stores/theme.ts` + `index.html` 内联脚本 | 本项目机制**比 NEX 假设更完整**:跟随系统 + 手动 + `localStorage` + `` + `color-scheme` + `meta theme-color` + `⌘⇧L`,且自绘区与控件读同一批 `--ant-*`(`cssVar:true`),切主题不重算样式表 | | §9 动效 | COMPLIANT | `styles/index.css:173-179`、`app.css:50` | 见 §2.3 关于 `--animate-agent-*` 的说明 | @@ -264,8 +264,8 @@ cd frontend/src && grep -roh -- '--nex-[a-z0-9-]*' . | sort | uniq -c | sort -rn | N6 | 03 §10 要求层级表但**没给表** | 阶段 3 已产出 `lib/layers.ts::LAYER` + `UI规范.md` §10 十三行表;建议 NEX 同样只给「关系」而非固定数字 | ✅ 阶段 3 已解决 | | N7 | 04 §8 缺「专业工作区 <768 降级范式」 | 阶段 5(需产品决策)+建议 NEX 补 | 待议 | | N8 | 04 §5 对「画布型工作区」无规范 | 建议 NEX 增补 Canvas Workspace;本项目先在 `page_patterns.project_specific` 声明 | 已声明 | -| N9 | 05 §3.6 未要求 Skeleton / 未定字段级 busy 规则 | 阶段 4 +建议 NEX 补 | 待议 | -| N10 | 06 §7 未给「页内状态 vs Toast」量化门槛 | 阶段 4(`Library`/`UserAdmin` 吐司偏多)+建议 NEX 补 | 待议 | +| N9 | 05 §3.6 未要求 Skeleton / 未定字段级 busy 规则 | 本项目已在 `UI规范.md` §13.8 自定「首屏用骨架 / 局部用 Spinner / 一屏只播一句进度」三条判据(阶段 4);建议 NEX 补进 05 §3.6 | ✅ 本项目已解决;待 NEX 侧采纳 | +| N10 | 06 §7 未给「页内状态 vs Toast」量化门槛 | 阶段 5(`ModelCenter`/`Library`/`UserAdmin` 连续写操作改页内状态)+建议 NEX 补 | 待议(→ 阶段 5) | | N11 | 07 §1 把图表写成 Dashboard 固定组成 | 本表 **E6** + 配置 `chart_library_for_alignment_only: forbidden` | 已登记 | | N12 | 07 §2 缺卡片网格列表细则 | 阶段 6 +建议 NEX 补 | 待议 | | N13 | 07 无「审批/评审」模式 | `page_patterns.project_specific: [review-approval]` | 已声明 | @@ -281,6 +281,7 @@ cd frontend/src && grep -roh -- '--nex-[a-z0-9-]*' . | sort | uniq -c | sort -rn | **R8 文档白名单口径** | `UI规范.md` 写的允许 import antd 的范围是 `theme/`、`app/providers.tsx`、`components/{ui,forms}`、`app/layout/`;`classaudit.py` 第 5 闸实际放行整个 `app/` | 结果:`app/App.tsx:21` 裸用 `Button/Flex/Layout/Spin`、`app/ErrorBoundary.tsx:17` 裸用 `Result/Typography` 都能通过 | 二选一(下轮决策):① 文档承认「外壳层可直接用 antd」;② 收紧探针到 `app/layout/`。倾向 ① —— 外壳层与 kit 的差别是「只此一份、不扩散」 | | **D16 kit `Tag` 吞 className**(阶段 1 新发现) | `components/ui/Status.tsx::Tag` 形参收了 `className`,但下面的 `cn('nex-tag', …)` 没有把它并进去 → 页面写 `` / `` **全部空转**(同文件的 `Badge`、`TagGroup` 都并了;`Chip` 走 antd `Tag`,不受影响) | 受影响 10 处:`app/layout/ActivityCenter.tsx:70`、`pages/ModelCenter.tsx:959`、`pages/project/Dispatch.tsx:405,457`、`pages/project/Review.tsx:363`、`pages/project/Timeline.tsx:727`、`pages/project/Storyboard.tsx:1976,1978`、`pages/project/AgentConsole.tsx:551`(原 `app/layout/PipelineConsole.tsx:155` 已用外套 `` 绕过,现渲染于 `:165`,见下) | **本轮不修**:修好后会同时点亮两处真实视觉变化——ModelCenter 的实心蓝「默认」标签、分镜卡缩略图上的 `absolute` 角标——越出阶段 1 授权(「不得引入额外视觉改动」)。**修法(下轮)**:`className` 并进 `cn()`,然后逐站点回归那 10 处;`PipelineConsole:165` 与 `Storyboard:1995` 的两层 `` 包装届时可撤 (两处代码注释已写明「D16 修好后可撤」) | | **D17 窄屏顶栏项目名压到品牌块**(阶段 2 复测新发现) | 430 视口下 `.nex-console` 内容比自己的盒子还宽(改前 `scrollWidth` 214 / `clientWidth` 173 → 项目名 `` 从 x=57 起,压住品牌块 49..81;阶段 1 收口后 203/170,窄了 11px,**同一处问题改前就存在**) | 不是阶段 1/2 引入的回归;影响 430 一档的顶栏可读性,且让 `elementFromPoint` 类探针在品牌块处拿到错的节点 | **本轮不修**:修法要么缩顶栏内容、要么改窄屏品牌块形态,二者都属「Header 尺寸/移动端导航形态」(授权 §八 明确排除)。留待阶段 5 与 N7 一起决策 | +| 阶段 4 交付项 | 六态表面(首屏骨架 / 抽屉正文骨架 / Forbidden / NotFound)已落地,`visualcheck` 名单 14 → 15 | ✅ 已完成(见 §7) | 明细见 `reports/NEX阶段4-7实施-2026-11-07.md` | | 阶段 1–3 交付项 | 阶段 1(截断兜底 + 探针)、阶段 2(3 处热区可键盘化)、阶段 3(`LAYER` 层级表 + 两处真实遮挡修复)均已落地;N14 拖拽键盘替代除外 | ✅ 已完成(见 §7 三行记录) | 明细见 `reports/NEX阶段0-3实施-2026-11-07.md` | | 本地杂物目录 | `.trash/`(27M)、`.local/`(352M)仍在磁盘 | 已 gitignore;`AGENTS.md` §1 已声明「不作现状依据」 | 保持,不参与任何统计 | @@ -293,6 +294,7 @@ cd frontend/src && grep -roh -- '--nex-[a-z0-9-]*' . | sort | uniq -c | sort -rn | 2026-11-07 | 阶段 0 建档:逐条判定 NEX 0.1.1 全文、登记例外 E1–E10、建立别名表、收敛反向清单 N1–N15 | Codex(阶段 0) | | 2026-11-07 | 阶段 1 落地截断兜底:`visualcheck.py` 新增 `tagtitle` 探针、`ui/Status.tsx` 组件级 `title` 兜底、分镜卡状态标签与顶栏流水线台收口;`UI规范.md` §2.1/§15.2 补「信息标签可截断但必须有兜底」口径;登记缺陷 **D16**(见 §6) | Codex(阶段 1) | | 2026-11-07 | 阶段 2 三处非语义热区可键盘化:分镜卡 `
` 加 `tabIndex/aria-label/aria-current` + Enter/Space (守卫 `ev.target === ev.currentTarget`,不套 `role=button` 以免抹掉卡内控件);`ui/Rows.tsx::LogRow` 加 `clickable` 分支(role/tabIndex/onKeyDown,保留 `title` 语义与逐字颜色);`AppHeader.tsx` 品牌区由 `onClick + navigate` 改为真实 ``,头像与平台名合并为**一个**焦点站点(1440 下块宽 138px 与合并前一致)。登记缺陷 **D17**(见 §6) | Codex(阶段 2) | +| 2026-11-07 | 阶段 4 补齐六态表面:新增 `ui/Panel.tsx::SkeletonBlock`(antd `Skeleton` + `role=status` + `sr-only` + `.nex-skeleton` 闸门落点,不传 `label` 时整块 `aria-hidden` 以免一屏播两句进度)与两页兜底 `pages/Forbidden.tsx`(`AuthGate` 拦住非管理员时就地解释,权限规则未变)、`pages/NotFound.tsx`(`router.tsx` 的 `path:'*'` 不再静默 `Navigate` 回首页);`Drawer` 新增 `loading` 并接入 `ProjectBriefDrawer`;三处首屏 `` 换成骨架后旧导出连同其 antd `Spin` import 一并删除;`UI规范.md` 新增 §13.8 六态表面 + §10 抽屉骨架口径 + §15.2 名单 14→15;`visualcheck.py` 增加 `/not-a-page` 探针(不入 `NAV_ROUTES`)与「页面不存在」文案断言 | Codex(阶段 4) | | 2026-11-07 | 阶段 3 建立层级表:新增 `lib/layers.ts::LAYER`(header 20 / toolbar 40 / scrim 55 / sheet 60 / antd 1000 / preview 1020 / recorder 1030 / confirm 1190 / toast 1200),7 处浮层改为引用 `LAYER.*`(AppHeader 顶栏 / Page 粘性工具条 / Overlay 遮罩 / Storyboard 检查器 / MediaLightbox 灯箱 / RecordAudio 录音面板 / Confirm 确认框,`Overlay::Modal` 并新增可选 `zIndex` 形参),另有 2 条必须贴在 antd 节点上的 CSS 值(`app.css` 1100 / 1200)保持原数并加注释指回层级表;修掉两条**实测存在**的遮挡(抽屉里点开灯箱看不见、声线抽屉里录音面板点不着),并给确认框第一次显式层级以免灯箱抬升后压不住;`UI规范.md` §10 重写(层级表 + 修正过时的「挂载点」口径 + 两条「不进表」例外) | Codex(阶段 3) | **维护约定** diff --git a/docs/UI规范.md b/docs/UI规范.md index 861b13e..628fa06 100644 --- a/docs/UI规范.md +++ b/docs/UI规范.md @@ -520,7 +520,7 @@ items = [ | ④ 内容层 | `Panel` / `PanelHead` / `Ctlbar` / `Table` | 这批数据本身 | 不重复上面三层 | - **外壳 `pages/ProjectDetail.tsx` 只剩数据装载**:按路由 `loadProject` + `startPolling`、 - 三种兜底(`Loading` / `Empty` / `ErrorText`)、``。它**不渲染任何可见块**—— + 三种兜底(`SkeletonBlock` / `Empty` / `ErrorText`,口径见 §13.8)、``。它**不渲染任何可见块**—— 「展开概况」这颗按钮连同那条面包屑工具条一起删了,因为入口已经还给顶栏。 别把项目名、状态 Tag、指标卡加回来(那正是 R18 要清的东西)。 - **内容页页头只剩 `PageHead` 一个实现**(2026-11 第十二轮把 `NodeHead` 并了进来): @@ -1059,6 +1059,11 @@ antd 的 `Tag.CheckableTag` 未选中态是**完全透明**的。铺进等宽格 按层退靠的是 `floatingLayerOpen()`(见下)而不是挂载点。抽屉/弹窗内的下拉挂进 `.ant-drawer-body` / `.ant-modal-body`(`app/providers.tsx` 的 `getPopupContainer`), 这样父层是浮层自己,antd 会自动给它加档(实测抽屉内 1150 > 抽屉 1000)。 +- **抽屉正文没到之前给骨架,不给一片空白**:``(阶段 4 · §13.8)。 + 抽屉天生是「先开壳、后填内容」——壳一出现正文就是空的,读者分不清在加载还是这一项本来就没数据 + (空态另有 ``)。`app/layout/ProjectBriefDrawer.tsx` 传 `loading={!proj}`, + 原本包在正文外的 `` 分支删掉。**`Modal` 刻意没有这个参数**:站内没有 + 「先开弹窗再拉内容」的用法,等数据到位再开弹窗才是这里的惯例。 - **下拉面板「至少」和触发器同宽,而不是「等于」**:`forms/Select.tsx` 传 `popupMatchSelectWidth={false}`(rc-select 走 `minWidth` 分支)+ `classNames.popup.root='nex-select-popup'`。 传 `true` 会被钉死成触发器宽度:时间线页 186px 的面板里那条「跟随时间线设置(默认内嵌软字幕轨)」 @@ -1525,6 +1530,39 @@ URL 没变,effect 不再触发。 正好是这条尺子要保的东西。**别为了过闸把 `ActionGroup` 拆成裸按钮**—— 拆了以后中轨和右段成了同排兄弟,6 颗缝一条线,用户说的「读不出主谓」又回来了。 +### 13.8 六态表面:载入 / 空 / 错误 / 禁用 / 权限不足 / 地址不存在(2026-11-07 · NEX 阶段 4) + +症状(审计报告 D5 / D6 · V6 / V7):四种状态里站内只有两种有明确表面。 +① **载入**——全站 0 处骨架,首屏是「一块空白 + 一颗居中转圈」,读者分不清 +「还在拉」和「拉完什么都没有」,而后者恰好是 `` 该说话的时候; +② **权限不足**——非管理员访问 `/users`,`AuthGate` 一句 `` 把人静默弹回首页, +他点的是侧栏上明晃晃的「用户管理」,结果页面换了、什么也没发生; +③ **地址不存在**——路由表 `path: '*'` 也是 ``, +链接少复制一段就变成「打开的是首页」,而且 `replace` 把他原来那一页从历史里抹掉了。 + +| 状态 | 唯一表面 | 用在哪 | 不许用 | +|---|---|---|---| +| **载入(首屏)** | `SkeletonBlock`(`components/ui/Panel.tsx`,antd `Skeleton` + `role=status` + `sr-only` 文案 + `.nex-skeleton` 标记类) | **只有三类落点**:① 路由级 `Suspense` 兜底 `app/App.tsx::PageLoading`;② 页面内部自己拉的整块首屏(`Dashboard` 项目列表 / `Storyboard` 镜头墙 / `ProjectDetail` 工作台壳);③ 抽屉正文 `Drawer loading`(`ProjectBriefDrawer`) | 面板头、按钮里、字段刷新——那些是**局部**等待,用 `Spinner`,拿骨架去闪等于整屏抖动 | +| **载入(局部)** | `Spinner`(面板头 / 按钮内 12px 转圈) | 已有内容之上的刷新、按钮进行中 | 整块首屏退回收一颗转圈 | +| **空** | `Empty`,三分类口径见 §15.2 | 「这块本来该有数据」 | 拿空态冒充 404 / 权限不足 | +| **错误** | 行内 `ErrorText` → 页内 `Notice` → 整页 `ErrorBoundary`(R19) | 按 §13.3 分级 | 页面里裸 `` | +| **禁用** | antd `disabled` + 必要时 `title` 说原因 | 控件级 | 用 `opacity` 装禁用 | +| **权限不足** | `pages/Forbidden.tsx`(`PageHead` + `Notice` + `Info` + `Actions`) | `AuthGate` 判定为「admin 路由 + 角色不够」时就地渲染 | 静默 `Navigate` 回首页 | +| **地址不存在** | `pages/NotFound.tsx`(路由表 `path: '*'`) | 任何没匹配上的地址 | 静默跳回首页;也**不用** `Empty`(那是「这里该有数据」,不是「这个地址没有页面」) | + +三条判据,避免骨架被到处乱贴: +**① 等的是整块首屏 → `SkeletonBlock`;等的是已有内容的一次刷新 → `Spinner`; +② 一屏只播一句进度**(`SkeletonBlock` 不传 `label` 时整块 `aria-hidden`,纯装饰; +传了才是那句 `role=status` 的播报); +**③ 骨架的段数就是那块内容的形状**(页头一段 + 正文一摞), +想画第三种形状说明那一处不属于首屏。 + +旧导出 ``(一块居中的 `Spin` + 一行灰字)在阶段 4 删除:它全站只有三处调用, +三处都是首屏,而首屏的正确表面已经换成骨架;留着它等于给后来人留一把会退回 +「空白 + 转圈」的尺子。**探针侧**:`visualcheck.py` 的默认名单因此多了一条 +`/not-a-page`(14 → 15 条路由),并断言 404 页必须出现「页面不存在」—— +静默重定向回潮时这一条会立刻红。见 §15.2。 + --- ## 14. 说明文字与表单增删(G1/G2/G3/G4/G5) @@ -1680,10 +1718,14 @@ node scripts/ui/classaudit.mjs frontend/src/pages/Help.tsx **色板只与真正的 `.ant-menu-item-selected` 比**(探针把命中的元素标成 `kind:item`): 折叠态抓到的是父级标题(`kind:submenu`),antd 给它的是透明底 + `colorPrimary` 文字, 拿选中项的 `controlItemBgActive` 去比必然报假故障(430 档项目路由就是这么中招的); -4. **请求的路由没被 `path:'*'` 静默重定向**——`page.goto` 后比对 `page.url` +4. **请求的路由没被静默重定向**——`page.goto` 后比对 `page.url` (Python 里它是**属性不是方法**,写成 `page.url()` 会炸 `TypeError: 'str' object is not callable`)。 这条抓的是「截图看着正常,其实拍的是首页」:当年 `/projects/{id}/agent` 根本不是路由 - (`AgentConsole.tsx` 是 `Overview.tsx` 里的「项目总控台」区块),差点被当成独立页面验收; + (`AgentConsole.tsx` 是 `Overview.tsx` 里的「项目总控台」区块),差点被当成独立页面验收。 + 阶段 4 起 `path:'*'` 不再跳首页而是渲染 `pages/NotFound.tsx`,于是名单里多了一条 + **`/not-a-page`**(14 → 15 条路由)专门量这页兜底,并额外断言页面里必须出现「页面不存在」 + ——哪天有人把它改回 ``,URL 比对与这句文案断言会同时报。 + 它**不在 `NAV_ROUTES` 里**:错地址在侧栏没有对应项,「没有选中项」才是正确行为; 5. **display utility 没被组件样式盖掉**(LAYOUT 探针):扫 `hidden` / `block` / `flex` / `inline-flex` / `grid` / `inline-block` / `inline` 及其 `max-:` / `:` 变体, 拿计算值和期望值对,不一致就报。**这是 R13 层叠事故的自动化闸门**; diff --git a/frontend/src/app/App.tsx b/frontend/src/app/App.tsx index 1cd01d9..33002fb 100644 --- a/frontend/src/app/App.tsx +++ b/frontend/src/app/App.tsx @@ -18,8 +18,8 @@ */ import { Suspense, useEffect, useRef, useState, type ReactNode } from 'react' import { Navigate, Outlet, useLocation, useMatches } from 'react-router-dom' -import { Button, Flex, Layout, Spin } from 'antd' -import { Notice } from '../components/ui' +import { Button, Layout } from 'antd' +import { Notice, PageStack, SkeletonBlock } from '../components/ui' import { IconReload } from '../components/icons' import { startActivityFeed, stopActivityFeed } from '../stores/activity' import { authState, refreshState, useAuthStore, useIsAuthenticated } from '../stores/auth' @@ -30,6 +30,7 @@ import MediaLightbox from '../components/media/MediaLightbox' import AppHeader from './layout/AppHeader' import AppSider from './layout/AppSider' import ProjectBriefDrawer from './layout/ProjectBriefDrawer' +import Forbidden from '../pages/Forbidden' import ErrorBoundary from './ErrorBoundary' import type { RouteHandle } from './router' @@ -50,17 +51,33 @@ function AuthGate({ admin, children }: { admin?: boolean; children: ReactNode }) if (!user) { return } - if (admin && user.role !== 'admin') return + /* 权限不足要说清楚,不要静默弹回首页(阶段 4 · 审计报告 D5 / V6)。 + 判定规则一个字没动——还是「admin 路由 + 角色不是 admin」,改的只是拦住之后说什么。 */ + if (admin && user.role !== 'admin') return return <>{children} } -/** 路由级兜底:分包在加载时,Content 里给一个居中的 Spin(antd 的默认加载形态) */ -export function PageLoading({ text = '页面加载中' }: { text?: string }) { +/** + * 路由级兜底 = 首屏骨架(阶段 4 · 补 NEX 06 §7 的 loading 面,审计报告 D6 / V6)。 + * + * 症状:分包在拉的时候内容区是一块 240px 高的空盒子加一颗居中 Spin。 + * 读者不知道自己将看到页头还是表格,也分不清「还在拉」和「拉完是空的」—— + * 后者站内已经有明确表面( 三分类),两者长一个样就是误导。 + * 做法:先画页头那一行,再画正文那一摞,间距沿用 的 16, + * 和真正渲染出来的页面同一个竖向节奏(R10),换页时内容不会跳位。 + * 这是整站唯一的路由级骨架:页面自己不写首屏 loading 形状, + * 只有「页面内部自己在拉的整块数据」才由页面补一段骨架(见 Dashboard / 分镜)。 + * 为什么保留 text: 那两处要把话说清楚, + * 读屏靠它播报;正文骨架由第二段带 label,第一段是装饰,不重复播报。 + * 为什么不再用 :转圈留在按钮和面板头里(局部刷新的成熟形态), + * 整页级的等待一律给形状,见 `ui/Panel.tsx::SkeletonBlock` 的口径。 + */ +function PageLoading({ text = '页面加载中' }: { text?: string }) { return ( - - - {text} - + + + + ) } diff --git a/frontend/src/app/layout/ProjectBriefDrawer.tsx b/frontend/src/app/layout/ProjectBriefDrawer.tsx index be17451..2ba0e41 100644 --- a/frontend/src/app/layout/ProjectBriefDrawer.tsx +++ b/frontend/src/app/layout/ProjectBriefDrawer.tsx @@ -25,7 +25,7 @@ import * as api from '../../api/client' import { fmtMoney, fmtTime, pct, statusLabel } from '../../lib/format' import { moduleState } from '../../lib/pipeline' import { - Button, Drawer, ErrorText, Info, Loading, Notice, PageStack, Panel, + Button, Drawer, ErrorText, Info, Notice, PageStack, Panel, Stat, StatGrid, Status, Tag, Value, type TagTone } from '../../components/ui' import { WorkflowBar } from '../../components/media/WorkflowBar' @@ -99,6 +99,7 @@ export function ProjectBriefDrawer({ open, onClose, projectId }: { return ( }> - {!proj - ? 正在载入项目概况… - : ( + {/* 正文没到之前由 Drawer 的 loading 出骨架(阶段 4):这里只渲染有数据的那一支 */} + {proj && ( {error} @@ -192,7 +192,7 @@ export function ProjectBriefDrawer({ open, onClose, projectId }: { )} - )} + )} ) } diff --git a/frontend/src/app/router.tsx b/frontend/src/app/router.tsx index 845ccc9..8d6d8f7 100644 --- a/frontend/src/app/router.tsx +++ b/frontend/src/app/router.tsx @@ -6,6 +6,9 @@ * 其中 1.9MB 是这次根本用不到的页面)。现在只保留入口页(项目列表)同步加载, * 其余按路由切分:点进哪个页面才拉哪个页面的 chunk,构建产物也跟着按路由分包。 * + * 两个同步 import 的例外: 是首屏; 是「别的 chunk 没到位 / + * 地址根本不存在」时的兜底,它自己去拉一个 chunk 就成了笑话。两者都只有几百行。 + * * 鉴权守卫做在 App 的 里(会话状态在 zustand,组件订阅比 loader 更省事), * 这里只声明每条路由的元信息 handle。 */ @@ -13,6 +16,7 @@ import { lazy } from 'react' import { createBrowserRouter, Navigate } from 'react-router-dom' import App from './App' import Dashboard from '../pages/Dashboard' +import NotFound from '../pages/NotFound' /** 侧栏里一定点得到的相邻页:首屏渲染完在空闲时提前拉好 */ const loadAssetLibrary = () => import('../pages/AssetLibrary') @@ -79,7 +83,10 @@ export const router = createBrowserRouter([ // 图文手册是站内页面(旧 /help.html 独立静态页已删),新窗口打开不影响当前工作台 { path: 'help', element: , handle: withHandle('使用手册') }, { path: 'help.html', element: }, - { path: '*', element: } + /* 错地址要说「没有这一页」,不要静默跳回首页(阶段 4 · 审计报告 D5 / V7)。 + 以前是 :链接少复制一段就变成「打开的是首页」, + 用户以为系统在骗自己,而且 replace 把他原来那一页从历史里抹掉了。 */ + { path: '*', element: , handle: withHandle('页面不存在') } ] } ]) diff --git a/frontend/src/components/ui/Overlay.tsx b/frontend/src/components/ui/Overlay.tsx index 19e1863..2bbbae5 100644 --- a/frontend/src/components/ui/Overlay.tsx +++ b/frontend/src/components/ui/Overlay.tsx @@ -3,6 +3,7 @@ import { Drawer as AntDrawer, Modal as AntModal } from 'antd' import { cn } from '../../lib/cn' import { LAYER } from '../../lib/layers' import { Button } from './Button' +import { SkeletonBlock } from './Panel' import { ActionGroup } from './Controls' import { IconClose } from '../icons' /** @@ -71,7 +72,7 @@ function useNames() { /** 默认宽:表单抽屉吃满视野,只放一块面板的抽屉由页面传更窄的 CSS 宽度 */ const DRAWER_WIDE = 'min(1360px, calc(100vw - 20px))' -export function Drawer({ open, onClose, title, sub, children, actions, width, closeOnBackdrop = true, label }: { +export function Drawer({ open, onClose, title, sub, children, actions, width, closeOnBackdrop = true, label, loading }: { open: boolean onClose: () => void title: ReactNode @@ -84,6 +85,13 @@ export function Drawer({ open, onClose, title, sub, children, actions, width, cl closeOnBackdrop?: boolean /** 无障碍名:标题是节点(带 title 属性的 span)时用它补一个纯文本名字 */ label?: string + /** + * 正文还在拉:给骨架,不给「空白 + 转圈」(阶段 4 · NEX 06 §7)。 + * 只这一处浮层用得到骨架——抽屉正文是「先开壳、后填内容」的形态, + * 抽屉一出现就是一片空白,读者分不清在加载还是这一项本来就没数据(空态另有 )。 + * Modal 不加这个参数:站内没有「先开弹窗再拉内容」的用法。 + */ + loading?: boolean }) { const { titleId, subId } = useNames() return ( @@ -124,7 +132,12 @@ export function Drawer({ open, onClose, title, sub, children, actions, width, cl footer={actions ? {actions} : null} styles={{ footer: { background: 'var(--ant-color-bg-elevated)', borderColor: 'var(--ant-color-split)', padding: '12px 20px' } }} > -
{children}
+
+ {loading + ? + : children} +
) } diff --git a/frontend/src/components/ui/Page.tsx b/frontend/src/components/ui/Page.tsx index 113e40f..eda6edc 100644 --- a/frontend/src/components/ui/Page.tsx +++ b/frontend/src/components/ui/Page.tsx @@ -305,8 +305,10 @@ export function Sub({ children, className }: { children?: ReactNode; className?: * 叫 PageStack 不叫 TabStack:外壳没有多页签条(产品口径「内容页不做多 Tab」), * 页签只存在于页面内部(kit 的 ),这一层就是普通的正文纵排。 */ -export function PageStack({ children, className }: { children?: ReactNode; className?: string }) { - return {children} +export function PageStack({ children, className, style }: { + children?: ReactNode; className?: string; style?: CSSProperties +}) { + return {children} } /** diff --git a/frontend/src/components/ui/Panel.tsx b/frontend/src/components/ui/Panel.tsx index 46cd407..5e5ffc5 100644 --- a/frontend/src/components/ui/Panel.tsx +++ b/frontend/src/components/ui/Panel.tsx @@ -23,7 +23,7 @@ import { /* 本文件下方自己 export 了一个 (栅格封装)——antd 的 Grid 必须起别名: 同名声明会顶掉 import 绑定,AntGrid.useBreakpoint() 静默变成 undefined, 整页撞进 ErrorBoundary。(Divider / Empty 起别名是同一个原因)*/ - Grid as AntGrid, Progress, Row, Spin, Statistic, Typography + Grid as AntGrid, Progress, Row, Skeleton, Statistic, Typography } from 'antd' import { cn } from '../../lib/cn' import { IconClose, IconExternal, IconLoading } from '../icons' @@ -326,13 +326,45 @@ export function Empty({ children = '暂无数据', className }: { children?: Rea return } -/** 读取中:antd Spin */ -export function Loading({ children = '读取中…', className }: { children?: ReactNode; className?: string }) { +/* 「读取中:一块居中的 Spin」这个导出(旧 )在阶段 4 删掉了: + 它全站只有三处调用,三处都是**首屏**,而首屏的正确表面是下面的 。 + 留着它等于给后来人留一把会退回「空白 + 转圈」的尺子——局部刷新请用 , + 整块等待请用 ,两者都够用。(审计报告 D6 / V6 · UI规范 §15.3) */ + +/** + * 首屏骨架 = antd Skeleton(阶段 4 · 补 NEX 06 §7 的 loading 态)。 + * + * 症状:全站 0 处骨架。首屏是「一块空白 + 一颗转圈」——路由分包在拉、项目在拉, + * 内容区只有一枚居中 Spin(实测 240px 高的空盒子)。读者既不知道这里将出现 + * 什么形状的东西,也分不清「在加载」和「加载完什么都没有」。 + * 做法:骨架只用在**首屏**两处——① 路由级 Suspense 兜底(`app/App.tsx::PageLoading`), + * ② 抽屉正文(`ui/Overlay.tsx::Drawer` 的 `loading`)。 + * 面板头 / 字段级的刷新维持内联 `Spinner`,那是成熟设计,不要拿骨架去闪。 + * 为什么只有 rows / title 两个参数:站内首屏只有两种形状——「一摞段落」与 + * 「一行标题 + 一摞段落」,都在 antd Skeleton 自己的档位里;开更多参数 + * 等于给页面发第二把尺子(想要别的形状说明那一处不是首屏)。 + * `nex-skeleton` 是闸门落点:像素检查要能认出「这一屏此刻是骨架」, + * 才不会把骨架当成空白内容误判成 empty 态。 + * `label` 决定这摞骨架对读屏说不说话:一屏只该有一句进度播报, + * 所以纯装饰的那一段(页头形状)不传 label,它整块 `aria-hidden`。 + */ +export function SkeletonBlock({ rows = 3, title = true, label, className, style }: { + /** 段落行数(antd 默认 3 行,这里对齐成站内首屏的常见高度) */ + rows?: number + /** 要不要那一行标题占位:页头形状用 true,正文里续段用 false */ + title?: boolean + /** 读屏与低视力用户看到的进度说明;只挂 sr-only,不占版面。不传 = 这摞纯装饰 */ + label?: string + className?: string + style?: CSSProperties +}) { return ( - - - {children} - +
+ + {label ? {label} : null} +
) } diff --git a/frontend/src/pages/Dashboard.tsx b/frontend/src/pages/Dashboard.tsx index aa5ec3a..66a1227 100644 --- a/frontend/src/pages/Dashboard.tsx +++ b/frontend/src/pages/Dashboard.tsx @@ -19,7 +19,7 @@ import { useAutoRefresh } from '../hooks' import { Select } from '../components/forms' import { MediaThumb } from '../components/media/MediaThumb' import { WorkflowBar } from '../components/media/WorkflowBar' -import { Actions, Block, Button, Chip, ChipBar, Ctlbar, Empty, ErrorText, Field, FieldBlock, FormGrid, FormRow, Grid, Input, LINK_CLS, SearchInput, LinkButton, Loading, LogBox, LogRow, MONO, MUTED, NumberInput, PageHead, Panel, PanelHead, ProgressBar, Row, SectionTitle, Stat, StatGrid, Status, PageStack, Tile, Table, Tag, TagChip, TagGroup, TextArea, Value, Clamp } from '../components/ui' +import { Actions, Block, Button, Chip, ChipBar, Ctlbar, Empty, ErrorText, Field, FieldBlock, FormGrid, FormRow, Grid, Input, LINK_CLS, SearchInput, LinkButton, LogBox, LogRow, MONO, MUTED, NumberInput, PageHead, Panel, PanelHead, ProgressBar, Row, SectionTitle, Stat, StatGrid, Status, PageStack, SkeletonBlock, Tile, Table, Tag, TagChip, TagGroup, TextArea, Value, Clamp } from '../components/ui' import { capabilityHint, capsOf, defaultFor, deliveryResolutions, fpsChoices, isMock, loadModels, @@ -456,7 +456,8 @@ export default function Dashboard() { : null} - {loading ? 正在读取项目… + {/* 首屏(列表还没到过)给表格形状的骨架;筛选出来的「没有匹配」是空态,不是骨架 */} + {loading ? : !filtered.length ? 还没有项目。点击右上角「新建长视频项目」开始。 : ( <> diff --git a/frontend/src/pages/Forbidden.tsx b/frontend/src/pages/Forbidden.tsx new file mode 100644 index 0000000..67d92a7 --- /dev/null +++ b/frontend/src/pages/Forbidden.tsx @@ -0,0 +1,56 @@ +/** + * 权限不足(阶段 4 · 补 NEX 06 §7 六态里的「权限不足」,审计报告 D5 / V6)。 + * + * 症状:非管理员访问 /users,`AuthGate` 一句 `` 把人静默弹回首页。 + * 他点的是侧栏上明晃晃的「用户管理」,结果页面换了、什么也没发生—— + * 既不知道自己点错了、还是系统坏了、还是这功能压根没有。 + * 做法:就地解释三件事:**这一页要什么角色 / 你现在是什么角色 / 你能去哪儿**。 + * 权限规则一个字没改(判定仍在 `AuthGate`),这一页只负责把「被拦住」说出来。 + * 为什么不用 antd `Result`:Result 是整页兜底那种重型表面(ErrorBoundary 在用), + * 自带 antd 的排版尺;站内的同类表面是 `PageStack` + `PageHead` + `Notice`(R19), + * 用 kit 这几件就够了,改门牌尺子、换主题时这一页自动跟着走。 + * 为什么和 NotFound 分开两页:NEX 05 §3.6 明写两者不得混同—— + * 「这里没有页面」和「你有账号但进不来」是两句不同的话,动作也不一样。 + */ +import { useLocation } from 'react-router-dom' +import { useAuthStore, roleLabel } from '../stores/auth' +import { + Actions, Info, LinkButton, Mono, Notice, PageHead, PageStack, Panel +} from '../components/ui' +import { IconProjects, IconUser } from '../components/icons' + +export default function Forbidden() { + const user = useAuthStore((s) => s.user) + const location = useLocation() + const name = user?.display_name || user?.username || '未记名的会话' + const role = roleLabel(user?.role || '') + + return ( + + }>返回项目总览} + /> + + + + 这个地址只有「管理员」能进,你刚才是被权限闸门挡下的,不是页面坏了。 + + + {location.pathname} }, + { label: '需要的角色', value: '管理员' }, + { label: '当前账号', value: `${name}(${role})`, }, + { label: '还能去哪', value: '项目总览 · 平台资产库 · 模型管理中心 · 我的账号' } + ]} /> + + + 项目总览 + }>我的账号 + + + + ) +} diff --git a/frontend/src/pages/NotFound.tsx b/frontend/src/pages/NotFound.tsx new file mode 100644 index 0000000..5fa71fc --- /dev/null +++ b/frontend/src/pages/NotFound.tsx @@ -0,0 +1,47 @@ +/** + * 页面不存在(阶段 4 · 补 NEX 06 §7 与 05 §3.6,审计报告 D5 / V7)。 + * + * 症状:路由表把 `path: '*'` 写成 ``,任何错地址都被静默跳回首页。 + * 用户拿到的是「首页」,而不是「你要的那一页没有了」—— + * 分享出去的链接打错一个字符、项目被删之后旧地址还在收藏夹里, + * 这两种情况他都会以为系统在自己骗自己。 + * 做法:把地址原样念给他听(`Mono` 回显 pathname),解释三种常见原因, + * 再给三条一定走得通的出口。浏览器历史里那一页还在,后退照样能回去。 + * 为什么不用 :Empty 说的是「这个位置本来该有数据,现在还没有」, + * 和「这个地址没有对应页面」是两回事,混用会让读者以为项目里没东西(§15.2 Empty 三分类)。 + * 为什么同步 import(不 lazy):404 页必须在没有网络往返的前提下立刻画出来, + * 它本身就是「别的 chunk 没到位」时的兜底;它只有这一百来行,不进任何页面的分包。 + */ +import { useLocation } from 'react-router-dom' +import { + Actions, LinkButton, Mono, Notice, PageHead, PageStack, Panel +} from '../components/ui' +import { IconBook, IconLibrary, IconProjects } from '../components/icons' + +export default function NotFound() { + const location = useLocation() + + return ( + + 系统里没有地址 {location.pathname} 对应的页面。 + 这不影响已经保存的内容,账号也还是登录状态。} + actions={}>返回项目总览} + /> + + + + 链接是从别处复制来的,末尾多了一段或少了一段;或者这一页在别的账号 / 别的项目里。 + + + + }>项目总览 + }>平台资产库 + }>使用手册 + + + + ) +} diff --git a/frontend/src/pages/ProjectDetail.tsx b/frontend/src/pages/ProjectDetail.tsx index 7d3cdb7..6d0df6f 100644 --- a/frontend/src/pages/ProjectDetail.tsx +++ b/frontend/src/pages/ProjectDetail.tsx @@ -22,7 +22,7 @@ */ import { useEffect } from 'react' import { Link, Outlet, useParams } from 'react-router-dom' -import { Empty, ErrorText, LINK_CLS, Loading } from '../components/ui' +import { Empty, ErrorText, LINK_CLS, PageStack, SkeletonBlock } from '../components/ui' import { loadProject, startPolling, stopPolling, useProjectStore } from '../stores/project' export default function ProjectDetail() { @@ -39,7 +39,18 @@ export default function ProjectDetail() { return stopPolling }, [id]) - if (loading && !project) return 正在载入项目… + /* 项目在拉 = 这一屏还没形状(阶段 4 · 补 NEX 06 §7 的 loading 面)。 + 这里等的是整块工作台(页签 + 正文都挂在 里),属于首屏级等待, + 所以给骨架而不是转圈:读者先看到「上面一页头、下面一大块正文」的轮廓, + 数据到位后按同一个节奏替换,不会整屏跳位。 */ + if (loading && !project) { + return ( + + + + + ) + } if (!project) { return ( diff --git a/frontend/src/pages/project/Storyboard.tsx b/frontend/src/pages/project/Storyboard.tsx index 6655550..b5bf2af 100644 --- a/frontend/src/pages/project/Storyboard.tsx +++ b/frontend/src/pages/project/Storyboard.tsx @@ -29,7 +29,7 @@ import { options, useSystemStore } from '../../stores/system' import { notify } from '../../stores/notice' import { confirmAction } from '../../stores/confirm' import { openPreview, usePreviewOpen } from '../../stores/preview' -import { PageHead, ActionGroup, Actions, BarRight, Between, BLOCK_TONE, Button, CARD_ROW, Check, Checkbox, Chip, ChipBar, CloseButton, Ctlbar, DRAWER_ACTIONS, DRAWER_BODY, DRAWER_HEAD, DRAWER_TITLE, Divider, Empty, ErrorText, ExportMenu, ExtLink, Field, FieldBlock, FilePick, FormGrid, FormRow, IconText, Input, LINK_CLS, LinkButton, Loading, MUTED, MUTED_MONO, MaybeNumberInput, Mono, Notice, NumberInput, PageStack, Panel, PanelHead, Row, Scrim, SearchInput, SectionTitle, Spinner, Status, TAG_DENSE, Table, Tabs, Tag, TagGroup, TextArea, Toolbar, Value, ViewSwitch, cellWrap, type Columns } from '../../components/ui' +import { PageHead, ActionGroup, Actions, BarRight, Between, BLOCK_TONE, Button, CARD_ROW, Check, Checkbox, Chip, ChipBar, CloseButton, Ctlbar, DRAWER_ACTIONS, DRAWER_BODY, DRAWER_HEAD, DRAWER_TITLE, Divider, Empty, ErrorText, ExportMenu, ExtLink, Field, FieldBlock, FilePick, FormGrid, FormRow, IconText, Input, LINK_CLS, LinkButton, MUTED, MUTED_MONO, MaybeNumberInput, Mono, Notice, NumberInput, PageStack, Panel, PanelHead, Row, Scrim, SearchInput, SectionTitle, SkeletonBlock, Spinner, Status, TAG_DENSE, Table, Tabs, Tag, TagGroup, TextArea, Toolbar, Value, ViewSwitch, cellWrap, type Columns } from '../../components/ui' import { floatingLayerOpen, LAYER } from '../../lib/layers' import { IconAdd, IconArrowDown, IconArrowUp, IconAudit, IconCheck, IconChevronUp, IconClose, IconCompose, IconCopy, IconDelete, IconDownload, IconDragHandle, IconEdit, IconEye, IconGrid, IconImage, IconListOrdered, IconMic, IconParams, IconPlayCircle, IconReload, IconRetry, IconSearch, IconSound, IconToTop, IconUpload, IconVideo, IconWarn } from '../../components/icons' @@ -1306,7 +1306,10 @@ export default function Storyboard() { 做法:一页只准有一个 main,它在 app/App.tsx;页面内层是 div。 */}
{loading ? ( - 正在载入分镜… + /* 镜头列表还没到过 = 这一屏的首帧(阶段 4)。卡片墙的形状由骨架先占住, + 读者一眼看出「下面要长出一排卡」,而不是「这个项目一个镜头都没有」。 + 面板头那颗内联 Spinner 不动:那是局部刷新,不是首屏。 */ + ) : !shots.length ? ( 还没有镜头。点上方「导入脚本 / 关键帧」批量建镜,或「新增镜头」手工写第一镜。 ) : !filtered.length ? ( diff --git a/scripts/ui/visualcheck.py b/scripts/ui/visualcheck.py index 97a12a1..cb6511f 100644 --- a/scripts/ui/visualcheck.py +++ b/scripts/ui/visualcheck.py @@ -31,16 +31,21 @@ SHOTS = OUT / "shots" SHOTS.mkdir(parents=True, exist_ok=True) WIDTHS = [int(x) for x in os.environ.get("NEX_WIDTHS", "1440").split(",")] THEMES = os.environ.get("NEX_THEMES", "dark,light").split(",") +# 404 探针地址:路由表里不存在这一条,走的正是 `path: '*'` 那一支。 +# 阶段 4 之前它是「静默跳回首页」,量不到任何新表面;现在它是一页真的兜底页, +# 有页头、有说明、有三个出口,所以进了默认名单(名单 14 → 15 条)。 +NOT_FOUND_ROUTE = "/not-a-page" ROUTES = [r for r in os.environ.get( "NEX_ROUTES", "/,/assets,/models,/projects/{id}/overview,/projects/{id}/library," "/projects/{id}/storyboard,/projects/{id}/dispatch,/projects/{id}/review," "/projects/{id}/timeline,/projects/{id}/delivery," - "/account,/users,/help,/login").split(",") if r] + "/account,/users,/help,/login," + NOT_FOUND_ROUTE).split(",") if r] # 侧栏导航覆盖到的路由:这些必须有选中项,否则 selectedKeys 断了。 # 登录页不在导航里(chromeless),主循环也不跑它——见下面登录前的专用一趟。 +# 404 也不算:地址压根不在菜单里,侧栏没有选中项才是对的。 NAV_ROUTES = [r for r in ROUTES - if not any(x in r for x in ("/account", "/users", "/help", "/login"))] + if not any(x in r for x in ("/account", "/users", "/help", "/login", NOT_FOUND_ROUTE))] USER = os.environ.get("NEX_USER", "admin") FORCED_PID = os.environ.get("NEX_PROJECT_ID", "") PWD = os.environ.get("NEX_PASS", "admin1234") @@ -510,10 +515,13 @@ def main() -> int: r = r.replace("{id}", str(pid)) page.goto(BASE + r, wait_until="networkidle") page.wait_for_timeout(600) - # path:'*' 会把不存在的路线静默重定向回首页:不比对 URL 就会白测一页 + # 比对 URL:页面自己乱跳(含回潮成「静默重定向回首页」)时别白测一页 if not page.url.rstrip("/").endswith(r.rstrip("/")): problems.append(f"{width}/{theme}{r}: 路由不存在,实际落在 {page.url}") continue + if r == NOT_FOUND_ROUTE and not page.get_by_text("页面不存在").count(): + # 兜底页必须真的说话:只剩空壳或换回跳首页,都算这条兜底没了 + problems.append(f"{width}/{theme}{r}: 404 页没有给出「页面不存在」说明") audit(page, r, width, theme, problems, menu_required=r in NAV_ROUTES) browser.close()