openyida 2026.9.21 → 2026.9.22-beta.2

package/yida-skills/skills/yida-nav-shell/references/nav-shell-patterns.md

@@ -1,6 +1,8 @@
-# 自定义导航壳形态目录
+# B 端导航壳形态目录
 
-根据 PRD、design.md 和用户参考选形态并设计，不用示例默认外观覆盖已有设计。应用/页面隐藏按 [导航技能](../SKILL.md#必做配置)，权限与跳转按下方契约。
+这里提供**选型方向 + 布局骨架 + 小段代码示例**。根据已确认的 PRD 和 `design.md` 选择一种主形态，再按业务设计外观；标签页可以叠加为二级导航。用户给过参考或已有满意实现时，沿用其设计，不用示例的默认样式覆盖。
+
+应用及页面导航配置按 [导航技能](../SKILL.md#必做配置) 执行。导航数据、权限和跳转遵守下方契约，UI 按设计手写；不以选择 CLI 组件或拼装整套模板作为实现起点。
 
 ## 选型速查
 
@@ -12,66 +14,130 @@
 | 悬浮胶囊 / Dock | 沉浸展示、轻量门户，减少常驻导航占位 | 3–6 项 | 底部胶囊或可收起菜单 |
 | 标签页 | 同一模块的同级视图，不替代应用主导航 | 2–8 项 | 横向滚动 |
 
-数量仅供布局参考，不增删业务模块。沿用用户指定形态，否则 AI 按场景决定，不另问样式选项。
+数量是布局参考，不是增删业务模块的依据。用户选择自定义导航后，由 Agent 按场景确定形态，用户已指定的形态优先；不把形态拆成导航提问选项，也不为这些样式再发起一轮提问。
 
 ## 通用设计要点
 
-导航表达应用身份、当前位置和有效任务。名称、顺序、分组来自 PRD，图标统一用 lucide-react 或 @ant-design/icons。选中态按设计采用胶囊、指示线或字重，不用 emoji、字母或 CSS 拼图标。导航与内容共同构图，避免重复菜单标题；外观变化不改变业务接口、权限、筛选及跳转参数。
+- 导航需要表达“应用是谁、当前在哪、还能去哪”。菜单名称与层级按业务组织；图标、文字、当前项和分组要有清晰主次。
+- 选中态可用胶囊底色、指示条、下划线或字重组合，按整体设计选择，不规定所有应用采用同一种外观。
+- 图标只作功能用途，使用同一套 `lucide-react` 或 `@ant-design/icons`；不用 emoji、字母占位和 CSS 拼图标。
+- 应用名、用户区、搜索和操作按实际需要安排；少量菜单不必填满整条屏幕，复杂菜单不宜硬塞进一条胶囊。
+- 页面内容与导航共同设计。浮导要留出间距，侧栏要给内容分配宽度；当前页已由菜单标明时，内容区不重复一个同名大标题。
+- 颜色与材质消费应用主题，详见 [主题 token](#主题-token)。导航外观调整不改变业务接口、筛选逻辑、权限与跳转参数。
 
 ## 形态 1：左侧边栏
 
-适合多模块、分组频繁切换的后台或门户。按使用频率安排应用名、常用入口、业务分组和底部操作；实体或浮动侧栏均需落实下方折叠、调宽交互。
+```text
+应用名    │ 面包屑 / 页面操作
+─────────┼──────────────────
+概览      │
+业务分组  │     业务内容
+  订单    │
+  客户    │
+折叠按钮  ↔ 可拖拽边缘
+```
+
+适合模块较多且经常跨模块工作的场景。分组可以用小标题、间距或分隔线区分；应用名、常用项、业务分组、底部操作按使用频率安排。可按设计采用实体侧栏或与页面背景留出间距的悬浮侧栏。必须落实下面的折叠和调宽交互。
 
 ## 形态 2：顶部导航
 
-默认贴顶通栏，无顶部/左右外侧留白或胶囊轮廓；内侧内容可居中限宽。悬浮栏仅按明确设计选用，仍记录 navigation.variant=top。业务工作区导航占位；有首屏背景图时叠加背景，默认透明，滚动后加遮罩底色，回顶恢复透明。
+```text
+        ╭─────────────────────────────────╮
+        │ 应用名   概览  订单  客户   操作 │
+        ╰─────────────────────────────────╯
 
-sticky 本身占位，共享网格建立叠加关系；先检查宿主滚动和祖先 overflow/transform，受限时按宿主边界用 fixed，不能覆盖平台侧栏。位置与首屏/滚动态写入 design.md；固定定位不等于悬浮外观，文字安全区不推下背景。
+                     业务内容
+```
 
-## 连续展示页共享首屏背景
+自定义顶部导航默认推荐**浮导**：与顶部和两侧留出间距，根据菜单数量和内容宽度设计成紧凑胶囊、居中悬浮栏或较宽的浮动容器。明确已选贴边通栏时沿用用户选择。仍记录 `navigation.variant=top`，浮导是呈现方式，不需要额外选择一种导航归属。
 
-`canvas-nav-content` 的 `layout="document"` 使导航与 main 共用网格区域，导航默认 sticky，宿主限制时显式用 `navigationPosition="fixed"`，按本页边界定位，main 随已有页面滚动；不固定高度、不裁切内容，也不额外创建滚动条。document 的根、main、content 均使用自然高度，不套 workspace 的 `flex:1 1 0/min-height:0`。导航包裹层保持透明；提取 canvas-nav-top 后传 `headerOnly`，让它只渲染菜单，避免重复 main 和 100vh 外壳。`ResizeObserver` 测量菜单真实高度，在根节点写入局部 `--openyida-navigation-height`；窄屏展开和换行后也能更新安全区。
+浮导顶部间距必须留在 Canvas 内：根容器用 `display: flow-root` 阻止首子元素 margin 折叠，或改由根 padding 承载，不能让整个 Canvas 产生顶部偏移。
 
-```jsx
-<div className="brand-page">
-  <style>{`
-    .brand-page .hero {
-      padding: calc(var(--openyida-navigation-height, 0px) + 48px) 24px 72px;
-      background-size: cover; background-position: center;
-    }
-    .brand-page .section {
-      scroll-margin-top: calc(var(--openyida-navigation-height, 0px) + 16px);
-    }
-    .brand-page .content { max-width: 1200px; margin: 0 auto; }
-  `}</style>
-  <CanvasNavigationContent layout="document" navigation={<CanvasNav headerOnly overlay title={brandName} items={items} activeKey={activeKey} onSelect={select} />}>
-    <section className="hero section" id="home" style={{ backgroundImage: heroBackground }}>
-      <div className="content">{renderHeroContent()}</div>
-    </section>
-    <section className="section" id="products">{renderProducts()}</section>
-  </CanvasNavigationContent>
-</div>
+位置、容器宽度、圆角、选中态和滚动行为写入 `design.md` 后实现；不把通栏套一个圆角就视为完成浮导设计。`sticky` 留在布局流中，`fixed` 叠在内容上，需要预留对应高度；移动端改为可展开的菜单，不能挤压文字。
+
+## 形态 3：顶部＋侧边
+
+```text
+应用名    业务域 A    业务域 B        用户
+───────────────────────────────────────
+域内模块  │
+域内模块  │           业务内容
+折叠按钮  ↔ 可拖拽边缘
 ```
 
-这是结构片段，`heroBackground` 来自已验证素材和设计遮罩；品牌、菜单、选择回调及内容函数由页面实现。导航的顶部/左右间距放在菜单内部 padding 中，让测量包含它；不要用折叠 margin 造间距。背景覆盖首屏，内容安全区只加一次。`maxWidth/gutter/radius/height` 是工作区参数，document 模式由页面区块设置内容宽度和间距。
+用于真实的两级信息架构。顶部承担业务域切换，侧栏仅显示当前域的模块；切换域时进入该域可见的默认模块或恢复上次入口。两层不要重复同一组菜单。侧栏同样必须支持折叠和拖拽调宽。
 
-锚点不改变 contentKey、不卸载整页。容器捕获宿主滚动事件并同步局部 data-scrolled；CanvasNav 的 overlay 随它切换透明/底色，展开时保持底色。锚点选中态仍由页面按实际滚动位置同步，并清理监听。滚动后加底色、回顶透明，文字随背景切换，移动端展开时保留底色。实际宿主验证 sticky，不能仅凭本地预览。document 不支持 iframeSrc，原生任务用 workspace 或表单抽屉。
+## 形态 4：悬浮胶囊 / Dock
 
-## 形态 3：顶部＋侧边
+```text
+                  业务内容
 
-用于真实两级信息架构：顶部切业务域，侧栏显示域内任务；切域进入该域默认或上次可见入口，两层不重复同一组菜单。侧栏支持折叠和拖拽。
+          ╭──────────────────────╮
+          │ 概览  活动  我的记录 │
+          ╰──────────────────────╯
+```
 
-## 形态 4：悬浮胶囊 / Dock
+适合少量高频入口的沉浸页或轻量门户。可以根据内容构图放在顶部、底部或侧边；已选择顶部导航时优先使用上面的顶部浮导方向。菜单保持紧凑，必要时收起，避开表单提交按钮、图表图例和移动端安全区。
+
+以下是**底部胶囊定位**的小段样式参考，尺寸和材质按设计调整，不是整页 UI 模板：
+
+```css
+.business-nav-dock {
+  position: fixed;
+  left: 50%;
+  bottom: calc(20px + env(safe-area-inset-bottom, 0px));
+  transform: translateX(-50%);
+  display: flex;
+  gap: 4px;
+  max-width: calc(100vw - 32px);
+  padding: 6px;
+  border-radius: 999px;
+  background: var(--pod-shell-theme-bg-color, #fff);
+  box-shadow: var(--pod-nav-popup-shadow, 0 6px 24px rgba(0, 0, 0, 0.12));
+}
+```
 
-适合少量高频入口的沉浸页或轻量门户。按构图放在顶部、底部或侧边，避开表单提交按钮、图例和移动端安全区。底部 Dock 可使用 fixed、left:50%、translateX(-50%)、bottom:calc(20px + env(safe-area-inset-bottom, 0px))，内容底部预留实际 Dock 高度及间距；尺寸材质依设计，不遮最后一行数据。
+同时为内容底部预留 Dock 实际高度与安全间距，并设置合适的层级和窄屏菜单策略；不能让导航遮住最后一行数据。
 
 ## 形态 5：标签页
 
-同模块视图使用 antd Tabs 或自绘标签，选中态与内容同步；窄屏横向滚动，键盘支持方向键、Home、End，跳过禁用项。页内标签不隐藏平台导航。
+在主导航下切换同模块视图，例如“待处理 / 已完成”。可用 antd `Tabs` 或按设计自绘，标签选中态与内容同步。长标签窄屏横向滚动；键盘支持方向键、Home、End 并跳过禁用项。只有页面内标签时保留平台导航，不因此关闭应用导航。
 
 ## 视图切换骨架
 
-只做本地切换时用 React 状态；分享、刷新、前进后退沿用路由或同步 hash。下方 AppShell 演示保留导航和 URL 的切换，纯本地视图可将 iframe 分支替换为业务组件映射；状态放在稳定父层，不把 PRD 的多个真实页面变成静态占位。快速切换、无权限回退和未保存内容遵循 [页面与导航连续性](../../yida-design/references/page-continuity.md)。
+同页视图与跨真实页面分别处理：同页只切内容可用 React 状态；要分享、刷新恢复、前进后退则同步 URL hash；跨页面仅在目标保留同一导航壳时使用现有路由与数据桥；原生页面嵌入主内容区。不要为了套用一个导航示例，把 PRD 的多个真实页面改造成一个静态页。
+
+下面只演示已过滤菜单的选中态与视图绑定。`views` 是当前页面自己的业务组件映射，布局与样式按选定形态补齐；需要 URL 同步的场景复用已有路由，不直接使用这个纯本地状态版本。
+
+```jsx
+import React from 'react';
+
+function LocalViews({ items, views }) {
+  const [selectedKey, setSelectedKey] = React.useState(null);
+  const activeItem = items.find(item => item.key === selectedKey && !item.disabled)
+    || items.find(item => !item.disabled);
+  if (!activeItem) return <p>无可用导航</p>;
+  const ActiveView = views[activeItem.key];
+  return (
+    <div className="business-shell">
+      <nav aria-label="业务导航">
+        {items.map(item => (
+          <button key={item.key} type="button" disabled={item.disabled}
+            aria-current={item.key === activeItem.key ? 'page' : undefined}
+            onClick={() => setSelectedKey(item.key)}>
+            {item.label}
+          </button>
+        ))}
+      </nav>
+      <main aria-label={activeItem.label}>
+        {ActiveView ? <ActiveView /> : <p>当前入口暂不可用</p>}
+      </main>
+    </div>
+  );
+}
+```
+
+页面变化时选中项必须仍在可见范围内；请求失败、加载中与空菜单按下方状态处理。`hashchange`、`matchMedia`、拖拽等监听在 effect 清理时移除。
 
 ## 侧栏交互
 
@@ -87,25 +153,7 @@ sticky 本身占位，共享网格建立叠加关系；先检查宿主滚动和
 
 ## 导航数据来源
 
-自定义导航的数量、名称、顺序、分组、默认任务和用途来自当前入口的 PRD。
-
-先区分页面内展示与真实资源导航。公开官网的首页、文化介绍等页内视图直接使用本地数组；需要统一过滤/选择 helper 时，显式用 local，不请求 getAccessableNavs：
-
-```jsx
-const items = [
-  { key: 'home', label: '首页', targetType: 'local', viewKey: 'home' },
-  { key: 'culture', label: '文化介绍', targetType: 'local', viewKey: 'culture' },
-];
-const menus = await loadCanvasNavigation({ items, mode: 'local' });
-const active = selectCanvasNavigation(menus, requestedKey, 'home');
-// 按 active.viewKey 渲染真实本页组件，URL 同步沿用下方切换骨架。
-```
-
-local 不接受 href/url 或真实页面跳转。含 access 时仍需 appType 和真实 resolveAccess；未授权项隐藏，查询失败不放行。业务数据读取、预约提交和管理操作另按平台权限执行；不得删除受保护菜单的 access。规划中的 sceneKey/resource/access 仍保留，不能把公开内容的菜单显示与受保护业务授权混为一谈。
-
-platform 只接绑定 formUuid/navUuid 的真实页面，local 或未绑定资源的叶子会在网络请求前报错。编译器也拦截静态可识别的误用；动态配置仍要验证。不要将“过滤后为空”或请求失败兜底为全量菜单。
-
-下面的数据树过滤用于 mode=platform；独立资源任务用 mode=independent 和真实 resolveAccess，按 [访问态入口契约](../../yida-app/references/entry-navigation.md#自定义菜单过滤) 执行，不能将平台树展示规则当作业务授权。使用当前访问者登录态请求 `/{appType}/query/formdesign/getAccessableNavs.json`，获取可见范围；`formUuid` 和 CSRF 值来自当前页面运行态。已有请求和正确的过滤逻辑时直接复用；首次接入可使用下面的数据片段，其中 `filterCanvasNavigation(plannedItems, navs, hiddenNav)` 负责可见性过滤，不包含导航 UI：
+自定义导航的数量、名称、顺序、分组和用途来自 PRD，通常工作台或首页在第一位。使用当前访问者登录态请求 `/{appType}/query/formdesign/getAccessableNavs.json`，获取可见范围；`formUuid` 和 CSRF 值来自当前页面运行态。已有请求和正确的过滤逻辑时直接复用；首次接入可使用下面的数据片段，其中 `filterCanvasNavigation(plannedItems, navs, hiddenNav)` 负责可见性过滤，不包含导航 UI：
 
 ```bash
 openyida sample openyida-page-template canvas-nav-data --output .cache/samples/canvas-nav-data.jsx
@@ -122,9 +170,9 @@ const items = await loadCanvasNavigation({
 });
 ```
 
-`plannedItems` 遵守菜单及访问态入口契约：任务 key 独立，绑定真实资源、用途与参数，本地视图绑定承载页。同一资源可有多个任务入口；分组仅需 label/children，有资源约束时另绑定。独立入口补齐 formUuid/viewUuid/access，不以平台展示范围代替授权。
+`plannedItems` 使用下方菜单契约：每个任务入口有独立 key，绑定真实 `navUuid/formUuid`，保存业务 label、图标、入口用途及跳转参数。工作台的本地视图绑定承载它的自定义页面 formUuid；同一资源可以对应多个任务入口。分组可只配置 label 和 children，具有独立资源约束时同时绑定该资源。
 
-片段递归排除 hidden 节点及 hiddenNav 命中 slug/navUuid 的子树，以可见 ID 过滤 PRD 菜单；保留规划顺序、分组和展示配置，不添加计划外资源，移除空组。侧边/顶部/Dock 用扁平入口，混合导航用两级结构。
+数据片段递归过滤接口中 `hidden` 的节点，以及 `g_config.navConfig.hiddenNav` 命中 `slug` 或 `navUuid` 的节点及子树，再以可见资源 ID 筛选 PRD 菜单。返回值保持 PRD 的顺序、分组和展示配置；未规划的接口资源不会自动增加到菜单，失去所有可见子项的分组会移除。侧边、顶部和 Dock 使用规划的扁平入口；混合导航使用规划的两级结构。
 
 页面首次加载或应用切换时清空旧菜单，取消旧请求，再加载当前应用菜单。按以下状态展示：
 
@@ -133,8 +181,8 @@ const items = await loadCanvasNavigation({
 | 加载中 | 显示加载提示，菜单和对应内容等待加载完成 |
 | 请求失败 | 显示重试入口 |
 | 没有可见入口 | 显示“无可用导航” |
-| 菜单加载完成 | 按当前地址选中可见入口；未指定入口时按 PRD 选择，先进入 defaultMenuKey 对应的可用任务，再回退首个可用任务 |
-| 地址中的 hash 指向不可见入口 | 先切至 defaultMenuKey 对应的可用任务，再回退首个可见入口；没有可见入口时显示“无可用导航” |
+| 菜单加载完成 | 按当前地址选中可见入口；未指定入口时按 PRD 选择，通常先进入工作台 |
+| 地址中的 hash 指向不可见入口 | 切至 PRD 顺序中的首个可见入口；没有可见入口时显示“无可用导航” |
 
 页面访问和数据权限继续由平台校验。
 
@@ -163,7 +211,7 @@ const registration = items.find(item => item.key === 'registration');
 
 **MUST**：自定义导航属于应用外壳，点击应用内导航后必须仍可见、可操作。原生提交页和数据管理页不包含这套自绘导航，不能直接用 `location.href` / `router.push` 替换顶层页面。`isRenderNav=false` 只隐藏原生导航，不会自动保留自绘导航。
 
-导航任务在主内容区打开；页内新增/详情使用标准 FormOpenContainer 抽屉，不混用。
+例如供应商应用：导航“工作台”显示本地工作台，“准入申请”嵌入原生 submission 页，“供应商档案”嵌入原生 workbench 页；工作台里的“提交申请”“详情”按钮仍用标准 `FormOpenContainer` 抽屉。导航项不打开抽屉。
 
 先提取并整体合并标准内容容器（合并重复 import）：
 
@@ -171,9 +219,9 @@ const registration = items.find(item => item.key === 'registration');
 openyida sample openyida-page-template canvas-nav-content --output .cache/samples/canvas-nav-content.jsx
 ```
 
-`CanvasNavigationContent` 默认 `layout="workspace"`。`navigation` 只接顶部菜单，`children` 接本地工作台，`iframeSrc` 接原生页面地址；不传地址时显示 children，可用于无权限或加载失败提示。`contentKey` 变化会卸载旧内容，导航保持挂载；默认重置滚动，显式 `preserveScroll` 按任务 key 恢复本地内容区位置。筛选、分页、已载数据和草稿需由稳定父层持有，并在恢复时已渲染足够内容；容器不缓存业务状态、iframe 或异步数据。`height` 默认 `100dvh`，已有宿主或侧栏分配高度时传入该区域的确定高度（只有父级高度确定时才能用 `100%`）。`maxWidth`、`gutter`、`radius`、`background` 按 design.md 设置并在视图间保持一致；默认透明背景承接页面画布，不跨 iframe 改色。容器不负责鉴权、路由、草稿保存或判断跨域加载失败。
+`CanvasNavigationContent` 的 `navigation` 接顶部导航，`children` 接本地工作台，`iframeSrc` 接原生页面地址；不传地址时显示 children，可用于无权限或加载失败提示。`contentKey` 变化会卸载旧内容并重置滚动。`height` 默认 `100dvh`，已有宿主或侧栏分配高度时传入该区域的确定高度（只有父级高度确定时才能用 `100%`）。`maxWidth`、`gutter`、`radius`、`background` 按 design.md 设置并在视图间保持一致；默认透明背景承接页面画布，不跨 iframe 改色。容器不负责鉴权、路由、草稿保存或判断跨域加载失败。
 
-先用 `openyida sample openyida-page-template canvas-nav-data` 合并 helper。下例 items 是权限已就绪的叶子菜单，资源、targetType、params 均真实；只含本地工作台与原生任务，外链及带壳跨页不进 iframe 分支。外观按 design.md。
+下面是交互骨架，导航外观按 `design.md` 实现。先执行 `openyida sample openyida-page-template canvas-nav-data` 获取并合并导航数据 helper（包含 `buildCanvasNavigationUrl`）。`items` 是已完成权限过滤的可见叶子菜单，仅包含当前壳内工作台与原生任务入口；资源 ID、`targetType` 和 `params` 来自真实配置。外链及带自身导航壳的跨页入口另走对应路由，不放入本例的 iframe 分支。
 
 ```jsx
 import React, { useEffect, useState } from 'react';
@@ -190,21 +238,20 @@ function AppShell({ items, homeKey, appType, renderWorkbench }) {
       window.removeEventListener('popstate', sync);
     };
   }, []);
-  const active = selectCanvasNavigation(items, requestedKey, homeKey);
+  const active = items.find(item => item.key === requestedKey) || items[0];
   function select(item) {
     if (item.disabled || item.key === active?.key) return;
     const url = new URL(window.location.href);
     const hash = new URLSearchParams(url.hash.slice(1));
     hash.set('view', item.key);
     url.hash = hash.toString();
-    window.history.pushState(window.history.state, '', url.toString());
+    window.history.pushState(null, '', url.toString());
     setRequestedKey(item.key);
   }
   return (
     <CanvasNavigationContent
       title={active?.label || '页面内容'}
       contentKey={active?.key}
-      preserveScroll
       iframeSrc={active && active.key !== homeKey
         ? buildCanvasNavigationUrl(active, appType, { embedded: true }) : undefined}
       navigation={<nav aria-label="应用导航">
@@ -221,13 +268,13 @@ function AppShell({ items, homeKey, appType, renderWorkbench }) {
 }
 ```
 
-hash 的 `view` 保存任务入口 key，刷新及前进后退恢复选中内容，其他 query/hash 参数和 history.state 保留。该例约定 hash 为参数形式；已有路由协议的页面沿用原协议，不强行覆盖。权限完成后，若请求入口不可用，按 active.key 用 replaceState 校正 view，不新增历史；没有可用入口则移除 view 并显示无权限内容。嵌入地址必须指向真实内容资源，不能再次嵌入当前壳页或带同一导航的壳页，避免递归和双导航。仅 iframe 内页滚动；不再给 iframe 外套滚动卡片。嵌入失败时保留导航并显示错误和明确的新窗口入口，不自动跳走。
+hash 的 `view` 保存任务入口 key，刷新及前进后退恢复选中内容，其他 query/hash 参数保留。该例约定 hash 为参数形式；已有路由协议的页面沿用原协议，不强行覆盖。嵌入地址必须指向真实内容资源，不能再次嵌入当前壳页或带同一导航的壳页，避免递归和双导航。仅 iframe 内页滚动；不再给 iframe 外套滚动卡片。嵌入失败时保留导航并显示错误和明确的新窗口入口，不自动跳走。
 
 切换会卸载当前内容；存在未提交表单时，应结合原生页面支持的通信能力处理离开提示，不能声称本例自动保存草稿或能读取所有 iframe 的脏状态。
 
 ## MUST：主内容撑满剩余空间
 
-本节仅用于业务工作区的 `layout="workspace"`，连续展示页使用上方 document 布局。工作区导航壳必须有确定的可用高度。独立全屏壳可用 `height: 100dvh`；已有宿主占用高度时使用宿主实际分配的确定高度，不能再叠加一个视口高度。仅 `min-height` 不能保证百分比高度链成立，也不要猜测 `calc(100vh - 80px)` 之类固定导航高度。
+自定义导航壳必须有确定的可用高度。独立全屏壳可用 `height: 100dvh`；已有宿主占用高度时使用宿主实际分配的确定高度，不能再叠加一个视口高度。仅 `min-height` 不能保证百分比高度链成立，也不要猜测 `calc(100vh - 80px)` 之类固定导航高度。
 
 布局链逐层成立：壳 `display:flex; flex-direction:column`，导航 `flex-shrink:0`，main 同时具有 `display:flex; flex-direction:column; flex:1 1 0; min-height:0; overflow:hidden`；iframe 视口为 `position:relative; flex:1 1 0; min-height:0; overflow:hidden`，iframe 绝对定位填满该视口。仅给子级写 `flex:1`、父级仍为 block 不合格。工作台分支使用独立 `overflow:auto` 的滚动容器；原生页面分支仅 iframe 内页滚动。
 
@@ -242,8 +289,7 @@ hash 的 `view` 保存任务入口 key，刷新及前进后退恢复选中内容
 | 菜单数据 | 用途 |
 | --- | --- |
 | `key` | 稳定且唯一的入口标识；分组和叶子项不重名 |
-| `navUuid / formUuid` | platform/independent 的真实资源标识；local 展示项使用 viewKey |
-| `viewKey` | local 的本页视图标识，不是平台资源 ID |
+| `navUuid / formUuid` | 真实平台资源标识，用于权限过滤；本地视图绑定承载页面 |
 | `label / icon` | PRD 业务名称、可选功能图标 |
 | `targetType` | 提交、页面或外链等入口用途，按上节确定 |
 | `params` | 预填、来源和其他业务参数，构造 URL 时保留 |
@@ -256,7 +302,13 @@ hash 的 `view` 保存任务入口 key，刷新及前进后退恢复选中内容
 
 ### 路由模式与数据桥兜底
 
-完整地址使用 `window.__OPENYIDA_UTILS__.router.push(href, params, false, true)`，避免平台重复添加应用前缀；第三参控制新标签，第四参控制 URL 模式。数据桥仅在第四参缺省时自动识别 /APP_、HTTP(S) 和协议相对地址，保留 query/hash；显式 false 不会纠正。页面 ID 仍用 `router.push('FORM-xxx', params, false)`，不要与 URL 混用或绕过数据桥。验收最终地址只有一层应用路径，选中态、参数和目标正确。
+曾出现的错误：将完整 `/APP_xxx/workbench/FORM_xxx` 地址当成页面 ID 或相对路由传入，平台再次添加当前应用前缀，产生重复的应用路径，无法正常切页。
+
+- 生成代码通过 `window.__OPENYIDA_UTILS__.router` 数据桥跳转，完整地址明确使用 `router.push(href, params, false, true)`：第三参控制新标签，第四参控制 URL 模式。
+- 数据桥已有兼容修复：仅在第四参 `isUrl` 未传或为 `undefined` 时，自动识别 `/APP_...`、HTTP(S) 和协议相对地址，并补为 `true`；路径中的 query/hash 保持原样。
+- 显式传入 `isUrl=false` 时保持调用方选择，不会自动纠正。因此不要对完整地址写 `router.push(href, params, false, false)`，也不要绕过数据桥直接调用底层平台工具。
+- 仅传页面 ID 时仍可用 `router.push('FORM-xxx', params, false)`；不要把页面 ID 与完整 URL 混用。
+- 验收：普通点击保持当前标签，最终 URL 仅含一层应用路径，目标页面、选中态和业务参数正确。新代码显式传 URL 模式，自动识别只作兼容兜底。
 
 ## 主题 token
 
@@ -265,8 +317,6 @@ hash 的 `view` 保存任务入口 key，刷新及前进后退恢复选中内容
 | 导航表面与标题 | `--pod-shell-theme-bg-color`、`--pod-nav-logo-text` |
 | 普通 / 悬停 / 选中 / 禁用文字 | `--pod-nav-item-text-*` |
 | 悬停 / 选中背景 | `--pod-nav-menu-bg-hover-color`、`--pod-nav-menu-bg-selected-color` |
-| 普通 / 悬停 / 选中边框 | `--pod-nav-menu-item-border`、`--pod-nav-menu-item-hover-border`、`--pod-nav-menu-item-selected-border`，填写完整边框值，各状态保持相同线宽 |
-| 菜单选中标记 | `--pod-nav-menu-item-selected-shadow`；`none` 关闭，其他值使用完整 `box-shadow`，可表达左、右或底部内阴影 |
 | 分隔线、选中指示、焦点 | `--pod-nav-sub-divider-color`、`--pod-nav-tab-line-selected-color` |
 | 菜单高度、圆角、文字、间距 | `--pod-nav-menu-*`、`--pod-nav-top-tab-*` |
 | 悬浮阴影 | `--pod-nav-popup-shadow` |
@@ -274,18 +324,25 @@ hash 的 `view` 保存任务入口 key，刷新及前进后退恢复选中内容
 | 自定义页整页画布 | `--pod-page-bg-color`（与原生页面统一）、`--pod-nav-page-padding` |
 | 业务卡片 | `--pod-card-bg-color`、`--pod-card-border` |
 
-`canvas-nav-side/top/mixed/dock` 共用上述菜单圆角、三种边框和选中阴影。已有自绘导航重新导出对应片段、合入页面源码并发布后生效；`canvas-nav-tabs` 继续使用页内标签样式。
-
-侧栏和 Dock 菜单项使用 `--pod-nav-menu-item-height` 与 `--pod-nav-menu-item-padding`；顶部菜单和混合导航的顶部分组使用 `--pod-nav-top-tab-height`、`--pod-nav-top-tab-item-padding` 与 `--pod-nav-top-tab-item-max-width`。侧栏、顶部和混合导航的菜单间距读取 `--pod-nav-menu-gap`；Dock 使用 `--pod-nav-slide-collapsed-menu-gap`。侧栏外部留白读取 `--pod-nav-slide-aside-padding`，混合导航侧栏读取 `--pod-nav-l-aside-padding`。顶部横向滚动区预留半个菜单间距供阴影展示；外阴影较大时增加间距，并检查长名称截断、折叠态和窄屏菜单。案例取值见 [导航形状与密度](../../yida-design/references/application-theme-consistency.md#导航形状与密度的案例经验)。
-
 主题由 `yida-design` 在应用级生成和配置；导航组件消费已有变量，必要的默认值放在 `var(...)` 回退中。颜色修改在主题文件完成，固定的布局结构留在组件中。导航深浅由导航主题决定，业务内容明暗由页面主题决定，分别验证。
 
 ## 验证
 
-按 [页面与导航连续性](../../yida-design/references/page-continuity.md) 验证首屏、往返及异常；补测不同权限的隐藏分组/不可见 hash，侧栏折叠、恢复宽度与拖拽，浅深色导航的文字/焦点。无递归 iframe、双导航和双滚动；局部背景不修改宿主主题，未做运行态检查须明确记录。
+- [ ] 点击每个应用内菜单后，自定义导航仍存在且可操作；选中项与主内容一致，并能通过导航返回工作台。
+- [ ] 原生提交/管理入口只切主内容 iframe；页面内新增/详情仍走标准抽屉，无双导航、递归 iframe 和双滚动条。
+- [ ] 深链刷新及前进后退恢复相应任务；嵌入失败也不丢导航。
+
+- 用权限不同的账号检查平台与自定义导航的可见入口，覆盖隐藏分组、空结果、请求失败及指向不可见入口的 hash。
+- 菜单选中项与当前业务视图一致；点击、深链、刷新和浏览器前进后退由页面现有路由正确处理。
+- 浅色及深色导航下，文字、背景、选中态、禁用态、焦点与分隔线可辨认。
+- 窄屏菜单可展开或滚动，悬浮导航按所在位置留出内容空间；需要覆盖式菜单时接入抽屉。
+- 自定义侧栏已验证折叠、展开后恢复宽度、拖拽上下限及内容区联动；这些功能不能因手写外观而省略。
+- 页面只保留一个应用导航组件，按 `design.md` 或用户参考检查悬浮位置、容器比例、留白和选中态；编译通过不等于视觉验收通过。
+- Canvas 宿主与自定义页根节点顶部对齐，浮导上边距留在根节点内（根节点使用 flow-root 或 flex/grid）；隐藏应用导航时透明画布透出 Shell，原生页面仍保留独立底色，不出现顶部异色条。
+- 本地编译通过后按发布技能更新目标页面；缺少运行态视觉检查时明确记录未验收，不得仅凭用了示例报告视觉完成。
 
 ## 可选代码参考
 
-按需用 `openyida sample openyida-page-template canvas-nav-side --output .cache/samples/canvas-nav.jsx` 查看折叠/调宽；top、mixed、dock、tabs 示例同理，外观仍按设计。
+需要具体交互实现时，可用 `openyida sample openyida-page-template canvas-nav-side --output .cache/samples/canvas-nav.jsx` 查看侧栏折叠、调宽逻辑；其他现有示例 `canvas-nav-top`、`canvas-nav-mixed`、`canvas-nav-dock`、`canvas-nav-tabs` 同样按需参考。它们保留供兼容和查阅，不是导航设计流程，也不是默认交付 UI。
 
-CodeCanvas 是单文件，合并片段时去重 import 和同名函数；只提取需要的逻辑。
+只提取需要的逻辑；CodeCanvas 使用单文件源码，合并片段时处理 import 和同名函数。菜单数据片段可独立复用，导航外观仍按上面的选型和业务设计实现。

package/yida-skills/skills/yida-page-config/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yida-page-config
-description: 为已有页面设置公开访问、组织内分享，或隐藏该页的平台导航时使用。隐藏导航不会改变访问权限。
+description: 配置已有页面的公开访问和组织内分享。
 ---
 
 # 页面访问配置
@@ -9,7 +9,7 @@ description: 为已有页面设置公开访问、组织内分享，或隐藏该
 
 用户要求查询或修改已有普通 OpenYida 页面的公开短链 `/o/`、组织内分享短链 `/s/`，或明确要求隐藏页面级导航时使用本技能。
 
-先通过创建结果、查询结果或项目配置确认目标页面的 `appType` 和 `formUuid`。页面归属不清、信息过期或结果冲突时，先查清再修改；不能只凭标题或猜测的链接确定页面。
+目标页面必须有可证明的 appType 和 formUuid。资源所有权不明、状态 stale、存在冲突或需要 reconciliation 时保持零写入；按标题或 URL 猜测页面身份不构成证明。
 
 ## 能力边界
 
@@ -20,15 +20,6 @@ description: 为已有页面设置公开访问、组织内分享，或隐藏该
 
 页面使用哪类数据、是否允许公开、openAuth 对当前页面和组织开放哪些资格，必须来自平台能力、用户确认或实际查询证据。本技能不根据页面类型或数据源猜测资格。
 
-## 匿名（免登）提交前置条件
-
-当用户要求"自定义页面在公开访问下提交数据到表单"或"走免登提交接口"时，作为前置门禁：
-
-1. **显示页和目标表单都需要 `isOpen`**：分别运行 `openyida get-page-config <appType> <显示页formUuid>` 和 `openyida get-page-config <appType> <目标formUuid>`，两者都返回 `isOpen === 'y'` 才承诺匿名提交。缺任一时先启用公开访问或改回登录态方案。
-2. **目标表单权限需包含 `FREE_LOGIN`**：运行 `openyida get-permission <appType> <目标formUuid>`，DEFAULT 权限组的 `dataPermit.rule` 须包含 `{"type":"FREE_LOGIN","value":"y"}`。缺少时按 `yida-form-permission` 锁定 DEFAULT 组 `packageUuid`，在完整现有 `dataPermit` 中只补该规则并保留其他规则，禁止用固定模板覆盖现网权限。
-3. 页面运行时分流是**匿名态**决定的，不是"表单公开"决定的：具体分流写法和 `RECEIPT_SAVE_FORM_DATA` 网关契约见 [`yida-canvas-custom-page/references/data-bridge-guide.md`](../yida-canvas-custom-page/references/data-bridge-guide.md) 的"公开访问（匿名态）提交"章节。
-4. 匿名提交的能力边界（不能发起流程、唯一性校验不生效、成员/部门/关联字段不支持、提交人恒为匿名、附件默认不跨组织）由平台限制决定；需要这些能力时改用登录态页面 + 关闭公开访问。
-
 ## 铁律
 
 1. **目标必须可证明**：appType 和 formUuid 从创建/查询命令或当前项目 config.json 获取；证据冲突时停止。
@@ -81,9 +72,9 @@ openyida save-share-config <appType> <formUuid> <url> <isOpen> [openAuth]
 openyida update-form-config <appType> <formUuid> false "<页面标题>"
 ```
 
-这条命令只设置页面级 `isRenderNav=false`。只有整个应用采用自定义导航时，才使用 `openyida update-app <appType> --hide-app-nav` 隐藏应用导航；独立访客端自定义菜单与管理端平台导航共存时，保留 `hideAppNav=n`。页面内是否显示导航、平台菜单是否包含该页、实际访问权限分别配置。详见 [访问态入口契约](../yida-app/references/entry-navigation.md)。
+这条命令只设置页面级 `isRenderNav=false`。自定义页要自绘应用侧边或顶部导航时，先使用 `openyida update-app <appType> --hide-app-nav` 隐藏应用导航；两者不是同一配置。
 
-完整应用的独立入口必须在写入后再执行 `openyida get-form-config <appType> <formUuid> --json`。只有回读确认 `renderNav=false` 后，才输出不带查询参数的 `/custom/{formUuid}`；仅缺少 `renderNav` 时兼容 `isRenderNav`，布尔值和字符串 `"false"` 均可，缺失或无效值不算成功。失败时保留 `/workbench`，不把 URL 参数当作持久配置成功证据。
+完整应用的独立入口必须在写入后再执行 `openyida get-form-config <appType> <formUuid> --json`。只有回读确认 `isRenderNav=false` 后，才输出不带查询参数的 `/custom/{formUuid}`；失败时保留 `/workbench`，不把 URL 参数当作持久配置成功证据。
 
 创建 dashboard 页面时，只有用户明确要求隐藏页面导航才使用：
 

package/yida-skills/skills/yida-prd/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yida-prd
-description: 基于整理好的需求事实编写或修改业务 PRD，负责业务、资源、页面、顺序和验收规则。
+description: 基于整理好的需求事实规划业务，生成 prd/<项目名>/prd.md，负责业务、资源、页面、顺序和验收规则。
 ---
 
 # yida-prd
@@ -11,7 +11,7 @@ description: 基于整理好的需求事实编写或修改业务 PRD，负责业
 
 读取 `.cache/openyida/<项目名>/requirement-brief.json`。发现影响规划的需求缺口时，将具体问题交回 `yida-requirement-analysis`，由 `yida-app` 组织澄清。
 
-开始规划前复用 brief 的 `navigation.type/source/reason`；导航未补齐时由应用编排按 [导航决策](../yida-design/references/navigation-decision.md) 作出 AI 判断，不交回首轮、不另设强制技术选择题；用户主动讨论或明确选择时保留其要求，按导航决策中的方案讨论与确认规则处理。Plan 将该类型写入 `execution.appConfig.navigationType`，Fast 在 PRD 应用配置中记录同一选择与依据。
+开始规划前确认 brief 的 `navigation.type/source/reason` 已明确；导航仍未决时交回需求分析与应用编排处理。Plan 将该类型写入 `execution.appConfig.navigationType`，Fast 在 PRD 应用配置中记录同一选择与依据。
 
 基于输入事实，按 [页面与导航规划](workflow/step-2-information-architecture.md) 形成业务资源蓝图，再按当前模式交付：
 
@@ -20,17 +20,15 @@ description: 基于整理好的需求事实编写或修改业务 PRD，负责业
 | Fast | 与 `yida-design` 并行，按 [11 章 PRD 契约](workflow/output-prd.md) 写入完整 `prd.md` |
 | Plan | 按 [计划业务规划](workflow/plan-business.md) 补齐 `build-plan.json` 的 `overview`、`dataModels`、`businessFlows`、`pages` 和业务 `execution`，交给 `yida-app` 调用 CLI 派生同一契约的 PRD |
 
-修改已有 PRD 时，只读并修改相关业务内容及其引用。Plan 按 [局部调整](../yida-app/workflow/plan/step-4-deliver.md#4-处理调整) 更新源字段，由 CLI 同步文档；Fast 直接修改 PRD 对应章节，保持其他章节原样。
+Plan 的业务调整通过字段级 patch 更新源事实，再由编排重新物化和确认。
 
 ## 业务要求
 
 - PRD 的业务说明和验收标准遵循 [用户可见表达契约](../yida-design/references/ask-human-interaction-contract.md)，用功能和使用效果描述方案；接口参数及配置键值写入 Agent 实施交接。Plan 的摘要、规则和验收文案会直接展示在 HTML 中，填写时使用同一业务表达。
-- 消费 brief 的 `userTasks` 和 `entryRecommendation`，将已选业务任务映射到页面、流程和访问路径；双入口不等于两个应用，不新增未选后台，业务管理入口不使用开发后台 `/admin` 代替。Plan 在现有页面/流程/执行字段表达这些要求，不新增未支持的 facts 字段。
 - 规划目标、角色、对象、字段语义、流程、资源、页面任务、数据来源和验收标准；写清资源创建、页面实现交付和导航三种顺序。
 - 用户存在 `explicitScope` 时，以该范围规划页面、表单、流程、报表和本轮交付。
 - 真实 `appType`、`formUuid`、`fieldId`、`processCode` 以资源证据为准；实现阶段产生的 ID 写入 `.cache/<项目名>-schema.json`。
 - 每个 display 页面提供 `pageSpecHandoff`，包含场景、区块、数据来源、主操作，以及指向对应 `design.md` 的 `designFile` / `designRefs`。视觉细则由 `yida-design` 维护。
-- 导航结构、菜单顺序和默认入口由业务任务确定；导航外观与应用框架、表单、记录详情和自定义页面交给 `yida-design` 统一设计。PRD 保留整体风格摘要与设计引用，完整 token 和消费规则只在 `design.md` 维护。
 
 ## 按需参考
 

package/yida-skills/skills/yida-prd/references/app/blueprint.md

@@ -1,6 +1,6 @@
 # 应用结构字段
 
-用于单个页面需要感知完整应用时，承接 `yida-prd` 的产品输出。应用字段与独立入口字段按 [前后台导航交接](../../../yida-requirement-analysis/references/handoff.md#前后台导航交接) 区分；下文应用隐藏字段用于全应用 custom，原生提交页/iframe 用于计划选定的原生页面。
+用于单个页面需要感知完整应用时，承接 `yida-prd` 的产品输出。
 
 ## 必填字段
 
@@ -17,7 +17,7 @@
 ## 使用规则
 
 - 页面 PRD 章节只引用与当前页有关的应用结构信息，不展开整个应用 PRD。
-- 首页按 [角色的主要任务](../../../yida-requirement-analysis/references/experience-groups.md#首页按任务选择) 确定：集中办事用 workbench，单项维护可直达原生列表，对外传播用 landing；已确认的经营分析用 dashboard，投屏监控用 screen。
+- 多页面应用的首页不一定是工作台：外部传播可用 landing，管理决策可用 dashboard，投屏可用 screen。
 
 导航字段按下表写，不能混用：
 
@@ -39,12 +39,12 @@
 {
   "pages": [
     {
-      "name": "采购工作台",
+      "name": "经营工作台",
       "resourceType": "display-page",
       "scene": "workbench",
       "entryMode": "platform-shell",
       "isMain": true,
-      "purpose": "处理待审批采购、跟进待收货订单、发起采购申请"
+      "purpose": "应用第一入口、今日概览、快捷入口"
     }
   ],
   "forms": [

package/yida-skills/skills/yida-prd/references/app/navigation-patterns.md

@@ -1,14 +1,11 @@
 # 导航模式
 
-沿用 PRD 的入口和导航方案，字段范围见 [应用结构字段](blueprint.md)。本节细化菜单与跳转方式。
-
 ## 快速判断
 
 | 需求 | 使用模式 | 要不要隐藏应用导航 | 备注 |
 | --- | --- | --- | --- |
-| 独立访客端自定义菜单＋管理端平台导航 | 两个访问态入口 | 不隐藏 | 仅前台页面设置 isRenderNav=false，详见 [访问态入口契约](../../../yida-app/references/entry-navigation.md) |
 | 常规业务系统、多页面后台 | 平台导航 | 不隐藏 | 用 `yida-nav-group` 管导航分组和顺序 |
-| 整个应用自绘应用级顶部/侧边/导航壳 | 页面内导航壳 | 隐藏 | 设置 `hideAppNav='y'`，再用 `yida-nav-shell` |
+| 自定义页自绘应用级顶部/侧边/导航壳 | 页面内导航壳 | 隐藏 | 设置 `hideAppNav='y'`，再用 `yida-nav-shell` |
 | 页面内 tab、分段、局部切换 | 混合导航 | 不隐藏 | 这是当前页面内部结构 |
 | 页面全屏、无导航、`isRenderNav=false` | 页面级隐藏 | 不一定 | 不等同于隐藏应用导航 |
 
@@ -18,7 +15,7 @@
 
 规则：
 
-- 默认进入高频管理任务；只有明确需要管理概览时才将概览靠前，不自动创建首页或把前台置顶。
+- 门面页靠前，配置/录入类页面靠后。
 - 同一角色的高频页面放同组。
 - 同应用内页面优先在平台应用导航内切换；不要把一组同应用页面复制成自定义页里的快捷入口卡。
 - 看板、工作台、列表、详情不要无序混排。
@@ -31,7 +28,7 @@
 
 - 默认不要在自定义页里自建同级导航。
 - 只有明确要顶部导航、侧边导航、导航壳、自绘应用级导航或隐藏应用导航时才使用。
-- 仅整个应用自绘应用级导航时开启 `hideAppNav`；不要用 `isRenderNav=false` 表达应用导航隐藏。
+- 自绘应用级导航前必须开启 `hideAppNav`；不要用 `isRenderNav=false` 表达应用导航隐藏。
 - 顶部导航适合官网/门户；侧边导航适合复杂后台；浮动胶囊适合沉浸展示。
 - 页面内导航只负责当前沉浸体验，不替代平台真实导航管理。
 

package/yida-skills/skills/yida-prd/references/app/role-journey.md

@@ -6,14 +6,12 @@
 
 ```markdown
 - 角色：经销商
-- 第一入口：订货工作台
-- 高频任务：处理待确认订单 / 查看待收货记录 / 发起补货
-- 需要页面：workbench + list + detail
+- 第一入口：经销商数据看板
+- 高频任务：查看 GMV / 补货风险 / 活动转化 / 巡店建议
+- 需要页面：dashboard + list + detail
 - 不需要页面：内部配置表单直接暴露在首屏
 ```
 
-只有角色确实需要经营分析时，另规划分析页；默认入口按 [首页按任务选择](../../../yida-requirement-analysis/references/experience-groups.md#首页按任务选择) 确定。
-
 ## 页面映射
 
 | 角色需求 | 页面类型 |

package/yida-skills/skills/yida-prd/references/plan-content.md

@@ -28,8 +28,6 @@
 - 视觉风格在 `prd.md` 中只写用户可理解摘要，并引用已同步生成的 `design.md` 作为完整设计契约来源。
 - `prd.md` 顶部记录 `buildPlanRevision`，必须等于 `build-plan.json.meta.revision`；用户确认后作为后续开发的产品执行基线。
 
-以下章节描述最终产物需要展示的内容。模型在紧凑输入中维护业务事实和项目差异；对象、流程、页面摘要与标准交接由 CLI 派生。
-
 ## 1. 需求总览
 
 目标：概述基于共享需求事实形成的业务方案。
@@ -148,8 +146,6 @@
 
 页面详情要让用户能想象最终页面能做什么、内容如何组织以及全局视觉主题如何在该页面落地，不要只写“展示数据、快捷操作”这类泛化描述。内容默认要求丰富但与任务相关；丰富度按任务覆盖衡量，不按区块数量衡量。
 
-紧凑输入中，按优先顺序填写 `blocks: [{name,purpose}]`，CLI 派生默认内容优先级与内容层次。独立的信息层次设计继续填写对应字段；首屏结构、关键交互和权限保留业务差异。
-
 字段归属：
 
 - 页面定位、核心用户、核心任务、内容优先级、功能区块、首屏结构、标志性交互、内容丰富度、页面模式、信息密度和权限属于 `pages.customPageDetails[]`。