openyida 2026.9.21 → 2026.9.22-beta.2

package/yida-skills/skills/yida-canvas-custom-page/references/data-bridge-guide.md

@@ -11,9 +11,8 @@
 | 宜搭开放 API（OpenAPI，`appKey`/`appSecret` 签名） | 服务端 / 平台连接器 | 需服务端签名；浏览器直连会泄露 secret。由后端或已鉴权的平台连接器调用。 |
 | 平台已配置连接器 `window.__OPENYIDA_CONNECTOR_API__` | **第三方 API 默认** | 页面只保存 `Http_*` `connectorName`、`operationId`、`connectionId` 和业务输入，由固定的同源运行时桥调用；鉴权与密钥留在平台侧。 |
 | 内部表单数据端点（同源、依赖登录 cookie + CSRF） | 降级可用 | 仅在 yida JS-API 桥不存在时使用；必须使用同源相对路径、`credentials: 'include'` 和运行态 CSRF token。 |
-| 公开访问网关 `window.pageConfig[...]`（同源、匿名态） | **匿名页仅此可用** | 仅当页面运行在 `/o/...` 公开链接（`FREELOGIN`、`loginUser.userId === 'FREEUSER'`）时使用；提交 URL 从 `window.pageConfig.RECEIPT_SAVE_FORM_DATA` 取值，为 origin 相对路径；CSRF 优先从 `window.g_config._csrf_token` 取，兼容 `pageConfig` 等运行态配置，**作为请求参数**（不是 header）传递；必须设置 `X-Requested-With: XMLHttpRequest` 头；`credentials: 'same-origin'`。仅当显示页和目标表单都已开启公开访问（`isOpen === 'y'`）且目标表单权限包含 `FREE_LOGIN` 数据规则时平台才会放行。 |
 
-选路原则：读本应用或本轮创建的宜搭表单，默认走 yida JS-API 桥；读第三方或复杂后端数据，走平台连接器桥；只有桥不存在且必须读表单时，才同源直连内部端点。页面运行在公开链接 `/o/...` 时即使能读到 `window.__OPENYIDA_YIDA_API__`，其登录态 `saveFormData` 也会失败；匿名提交必须优先走公开访问网关，且显示页和目标表单都已开启公开访问、目标表单权限包含 `FREE_LOGIN`。Cookie、CSRF、AK/SK 和签名由平台上下文、连接器或后端服务提供，页面不能接收或保存密钥。
+选路原则：读本应用或本轮创建的宜搭表单，默认走 yida JS-API 桥；读第三方或复杂后端数据，走平台连接器桥；只有桥不存在且必须读表单时，才同源直连内部端点。Cookie、CSRF、AK/SK 和签名由平台上下文、连接器或后端服务提供，页面不能接收或保存密钥。
 
 ## 推荐：先写 dataBinding，再实现数据桥
 
@@ -381,146 +380,10 @@ function fetchFormData(appType, formUuid, signal) {
 function fieldOf(row, fieldId) { return (row.formData || row)[fieldId]; }
 ```
 
-## 公开访问（匿名态）提交
-
-页面运行在公开链接 `/o/...` 时，`this.utils.yida.saveFormData` 不可用于匿名提交；页面上即使存在 `window.__OPENYIDA_YIDA_API__` 桥对象，其登录态 `saveFormData` 也会返回 `LOGIN FAILED`。平台在 `window.pageConfig` 里注入的公开访问 API 网关映射，是匿名页写入表单数据的**唯一可行通道**。
-
-前置条件（缺一不可，缺任一都不承诺匿名提交）：
-
-- **显示页已开启公开访问**：`openyida get-page-config <appType> <显示页formUuid>` 返回 `isOpen === 'y'`。
-- **目标表单（receipt）也已开启公开访问**：`openyida get-page-config <appType> <目标formUuid>` 返回 `isOpen === 'y'`。显示页和目标表单的 `isOpen` 缺一不可。
-- **目标表单权限包含 FREE_LOGIN 规则**：`openyida get-permission <appType> <目标formUuid>` 的 DEFAULT 权限组 `dataPermit.rule` 包含 `{"type":"FREE_LOGIN","value":"y"}`。缺少此条会得到 `TIANSHU_160001 没有权限`。
-- 页面确实运行在匿名态：`String(window.pageConfig && window.pageConfig.FREELOGIN) === 'true'` 或 `(window.loginUser || {}).userId === 'FREEUSER'`。
-- `window.pageConfig.RECEIPT_SAVE_FORM_DATA` 非空（值形如 `/o/<hash>`）。
-
-网关请求契约：
-
-- **URL**：`window.location.origin + window.pageConfig.RECEIPT_SAVE_FORM_DATA`，与租户命名空间无关，不要硬编码 `/dingtalk/web` 或 `/alibaba/web`。
-- **方法与编码**：`POST` + `Content-Type: application/x-www-form-urlencoded`。
-- **必须的请求头**：`X-Requested-With: XMLHttpRequest`（缺少此头会导致 302 重定向而非 JSON 响应）。
-- **CSRF**：优先从 `window.g_config._csrf_token` 取，兼容 `pageConfig`、`YIDA_CONFIG`、`__YIDA__` 等运行态配置，**作为请求参数** `_csrf_token` 传递；`credentials: 'same-origin'`。
-- **body 参数**：`formUuid`、`appType`、`_csrf_token`、`value`（`JSON.stringify(字段数组)`）。`_schemaVersion` 不必填。
-- **`value` 字段数组格式**：每项固定为 `{componentName, fieldId, fieldData: {value}}`：
-  ```json
-  [
-    {
-      "componentName": "TextField",
-      "fieldId": "textField_xxx",
-      "fieldData": { "value": "文本值" }
-    }
-  ]
-  ```
-  `componentName` 必须取目标表单 `openyida get-schema <appType> <formUuid> --field-map-json` 返回的真实值，不得根据 `fieldId` 前缀猜测；标准组件名称见[字段定义 JSON 指南](../../yida-create-form-page/references/field-definition-guide.md#支持的字段类型)。`fieldData.value` 沿用表单保存值结构，文本、数字、单选、多选和日期等格式统一引用[数据格式指南](../../yida-data-management/references/data-format-guide.md#常见字段值格式)，不在本技能复制第二份映射表。该引用只说明值结构，不代表所有字段都支持公开匿名提交；仍需遵守下方匿名能力边界，并按返回实例 ID 回读目标字段。
-  把字段 ID 放进 `fieldData` 会得到 `success: true` 和 `formInstId`，但实际创建的是空记录，不能据此判定提交成功。
-- **响应**：`success: true` 时读 `content.formInstId`。
-
-自适应提交 helper（页面直接复制；登录态走既有桥，匿名态走公开网关；两态失败都返回可读原因）：
-
-```jsx
-function isFreeLoginPage() {
-  try {
-    var cfg = window.pageConfig || {};
-    if (String(cfg.FREELOGIN) === 'true') { return true; }
-  } catch (err) {}
-  try { return (window.loginUser || {}).userId === 'FREEUSER'; } catch (err) {}
-  return false;
-}
-
-function publicEndpoint(key) {
-  var cfg = (typeof window !== 'undefined' && window.pageConfig) || {};
-  var p = cfg[key];
-  if (!p) { return ''; }
-  return p.charAt(0) === '/' ? window.location.origin + p : p;
-}
-
-function getCsrfToken() {
-  var yida = window.__YIDA__ || {};
-  var sources = [
-    window.g_config,
-    window.pageConfig,
-    window.YIDA_CONFIG,
-    yida,
-    yida.config,
-    yida.pageConfig,
-    yida.runtimeConfig,
-  ];
-  var keys = ['_csrf_token', 'csrfToken', 'csrf_token', 'global_csrf_token'];
-  for (var i = 0; i < sources.length; i += 1) {
-    var source = sources[i] || {};
-    for (var j = 0; j < keys.length; j += 1) {
-      if (source[keys[j]]) { return source[keys[j]]; }
-    }
-  }
-  return '';
-}
-
-function submitViaPublicGateway(appType, formUuid, fieldArray) {
-  var url = publicEndpoint('RECEIPT_SAVE_FORM_DATA');
-  if (!url) {
-    return Promise.reject(new Error('当前页面未开启公开访问，无法匿名提交'));
-  }
-  var csrf = getCsrfToken();
-  if (!csrf) {
-    return Promise.reject(new Error('当前公开页面缺少提交凭证，请刷新后重试'));
-  }
-  var body = new URLSearchParams();
-  body.set('formUuid', formUuid);
-  body.set('appType', appType);
-  body.set('value', JSON.stringify(fieldArray));
-  body.set('_csrf_token', csrf);
-  return fetch(url, {
-    method: 'POST',
-    credentials: 'same-origin',
-    headers: {
-      'Content-Type': 'application/x-www-form-urlencoded',
-      'X-Requested-With': 'XMLHttpRequest',
-    },
-    body: body.toString(),
-  }).then(function (r) { return r.json(); }).then(function (json) {
-    if (!json || json.success === false) {
-      var msg = (json && (json.errorMsg || json.errorCode)) || '匿名提交失败';
-      throw new Error(msg);
-    }
-    return json.content || json;
-  });
-}
-
-function submitFormData(appType, formUuid, fields, fieldComponents) {
-  if (isFreeLoginPage()) {
-    var fieldArray = Object.keys(fields).map(function (fieldId) {
-      var componentName = fieldComponents && fieldComponents[fieldId];
-      if (!componentName) {
-        throw new Error('字段 ' + fieldId + ' 缺少真实 componentName，请先回读表单 Schema');
-      }
-      return {
-        componentName: componentName,
-        fieldId: fieldId,
-        fieldData: { value: fields[fieldId] },
-      };
-    });
-    return submitViaPublicGateway(appType, formUuid, fieldArray);
-  }
-  return window.__OPENYIDA_YIDA_API__.saveFormData({
-    appType: appType, formUuid: formUuid,
-    formDataJson: JSON.stringify(fields),
-  });
-}
-```
-
-匿名态能力边界（不要在这些场景里承诺免登能力）：
-
-- **不能发起流程**：`window.pageConfig.START_INSTANCE` 为空字符串，匿名态无法调用 `startProcessInstance`；流程页必须走登录态。
-- **不能读取跨组织附件**：匿名会话看不到组织内附件，附件字段默认不支持组织外访问。
-- **不支持成员/部门/关联表单/关联查询/行业组件/自定义组件**：这些字段在公开访问表单中被平台限制。
-- **唯一性校验不可用**：唯一约束不会在匿名提交时生效，业务侧要另外做去重。
-- **提交人恒为匿名**：审计需要真实身份时不要走匿名通道，改为登录页 + 表单公开访问关闭。
-- **匿名态开启后**：不再支持从该表单发送卡片消息给个人/群聊。
-
 ## 数据接入验收清单
 
 - 已确认 appType、formUuid 和字段 ID 来自真实表单 Schema。
 - 页面首屏接口返回后，统计总数与数据管理页 / `openyida data query form` 的总数一致。
-- 匿名提交不能只检查 `success` / `formInstId` 或总数增长；必须按返回的 `formInstId` 回读记录，确认代表性字段值真实落库。
 - 真实接口异常时显示错误原因和重试入口。
 - 提交、点赞等写操作成功后调用 silent reload，只更新统计和列表。
 - 轮询 `setInterval` 有 cleanup，页面隐藏时暂停请求。
@@ -531,5 +394,3 @@ function submitFormData(appType, formUuid, fields, fieldComponents) {
 - **幂等**：提交按钮加 loading 锁与去重键，拦截重复写入。
 - **权限**：写操作是否允许由平台权限决定；失败按后端返回的 `errorMsg` 提示。
 - **密钥位置**：任何 `appSecret` / 签名逻辑都留在服务端 / 连接器，页面源码里只出现同源相对路径与业务参数。
-- **匿名态分流**：页面运行在 `/o/...` 公开链接时，即使存在 `window.__OPENYIDA_YIDA_API__` 桥对象，其 `saveFormData` 仍会返回 `LOGIN FAILED`；必须先识别 `FREELOGIN` / `FREEUSER`，再按上文"公开访问（匿名态）提交"章节走 `window.pageConfig.RECEIPT_SAVE_FORM_DATA`，且 CSRF 走请求参数、`credentials: 'same-origin'`。
-- **匿名态限制**：匿名提交不能发起流程（`START_INSTANCE` 为空），唯一性校验不生效，成员/部门/关联表单/关联查询/行业组件/自定义组件不支持，提交人恒为匿名。审计需要真实身份、或需要唯一约束时不走匿名通道。

package/yida-skills/skills/yida-canvas-custom-page/references/navigation-and-entry-guide.md

@@ -1,101 +1,17 @@
 # YidaCodeCanvas 应用内导航与快捷入口
 
-作用范围先按 PRD 判断：独立前台的 pageSpecHandoff.navigation 只控制当前入口，配合 standalone 页面配置；后台应用导航继续保留。下文自绘应用级导航与全局隐藏规则，仅适用于整个应用采用 custom。页面内普通表单提交和详情入口必须接入下方标准 iframe 抽屉；全码前台也遵守，不自行实现另一套填写与提交逻辑。
-
 自定义页面里的快捷入口先判定目标类型，再选择跳转方式。目标是应用内页面时，用户应感觉是在宜搭应用导航内切换，而不是弹出一个脱离左侧导航的新页面，也不是在当前自定义页面中额外生成一套侧边导航或顶部应用导航。
 
 ## 运行态事实
 
-- `isRenderNav=false` 表示导航展示配置，不证明当前页面位于 iframe。不要仅凭该参数修改 `window.top.location`；嵌入方式、跨域和宿主能力需分别验证。
 - 宜搭应用壳根据 `navUuid/formUuid` 和 `workbench` 路径维护选中态；同应用页面应进入 `/{appType}/workbench/{formUuid}` 或对应壳层路由。
 - 发布层会把根级工具注册到 `window.__OPENYIDA_UTILS__`；可用时优先通过 `window.__OPENYIDA_UTILS__.router.push` 做应用内跳转，通过 `window.__OPENYIDA_UTILS__.openPage` 打开外部链接或新窗口场景。
 - `openPage` / `window.open` 更适合外部链接、新标签、钉钉链接、文件预览等场景；同应用页面默认在当前应用壳内切换。
 - 页面隐藏应用导航后，页面内自绘导航壳接管跨视图切换；导航可见时使用平台导航承载同级页面切换。
 - 自绘应用导航按 PRD 安排数量、顺序、分组和任务入口，通常工作台在首位；当前用户的 `getAccessableNavs.json` 结果只用于过滤不可见入口。数据片段和接入规则见 [导航数据来源](../../yida-nav-shell/references/nav-shell-patterns.md#导航数据来源)。
 
-## 平台导航下的管理页面
-
-业务管理端默认由平台菜单负责跨模块切换，自定义页面只实现业务内容。`entryRecommendation.entries[].menu` 是平台菜单与默认任务的规划，不是要求把整份菜单再渲染进工作台。选择自定义页面只改变内容实现方式，不改变导航归属。
-
-- `entryMode=platform-shell`：保留平台导航，直接实现概览、提醒、列表、筛选和业务操作，不添加品牌顶栏、应用侧栏或覆盖多个管理模块的 Tabs；不要为了容纳重复菜单而改成独立页或隐藏平台导航。
-- 合理的页内切换属于同一任务，例如预约页的“全部 / 待处理 / 已完成”、商品页的“在售 / 下架”。即便使用 React 状态切换，“商品管理 / 资讯管理 / 预约管理”仍是跨模块菜单，不能借页内 Tab 重复平台导航。
-- 概览里的“处理这条预约”“查看低库存商品”等上下文动作可以保留，使用真实资源和应用路由；不要把平台的全部模块再复制成固定菜单或快捷入口区。
-- standalone 只表示独立展示，不自动要求菜单；未规划页面菜单且应用保留平台导航时只实现业务内容，显式 none 同样不创建菜单。
-- 只有确认采用应用级自绘导航或独立前台菜单时才使用导航壳。保留筛选、分页、草稿状态本身不是自绘应用导航的理由；这些状态由业务组件管理。
-
-Plan 输出的 `pages[].navigationPolicy` 明确菜单归属、页面布局和本地切换范围，派发页面任务时与 `pageSpecHandoff` 一并传递，不将它塞进严格的 page-spec 输入。Fast 在 PRD/design.md 记录同样的边界。缺少该字段的旧计划，根据应用导航决策、当前页配置和实际管理链接判断；不能单凭 URL 或页面名称推断导航是否可见。
-
-验收要从真实管理端链接打开：平台菜单与页面内容区合起来只出现一套跨模块导航。若两层菜单重复，修改页面源码中的重复菜单，保留平台导航、业务组件、数据与权限；编译通过不能替代这项页面验收。
-
-## 先建立动作与目标清单
-
-跨页按钮、导航菜单、卡片链接、返回首页共用一份目标映射。编码前为每个动作记录：业务名称、targetType、真实 appType、目标 formUuid/navUuid、必要参数、打开方式；资源来源是创建/查询结果及回读，不从页面名称猜 ID。详情按钮另外记录真实 formInstId 的行数据来源。无目标或无权限时禁用并说明原因，不用空地址或占位链接。
-
-| 动作目标 | targetType | 接入方式 |
-| --- | --- | --- |
-| 本页房型 Tab、筛选、多个本地视图 | local | viewKey + selectView，更新状态或 hash |
-| 独立前台首页、客房、预订自定义页 | custom | `/{appType}/custom/{formUuid}`，utils 路由 URL 模式 |
-| 保留平台应用壳的管理页面 | page | `/{appType}/workbench/{navUuid或formUuid}` |
-| 应用工作台 | app | `/{appType}/workbench` |
-| 原生提交或详情入口 | submission / detail | 交给 useYidaFormOpen；详情必须带 formInstId |
-| 外部网站 | url | 已验证的完整 HTTP(S) 地址，按外链打开 |
-
-先提取可复用片段并整体合并到当前文件；保留现有页面业务实现：
-
-```bash
-openyida sample openyida-page-template canvas-navigation --output .cache/samples/canvas-navigation.jsx
-```
-
-`buildCanvasPageUrl(entry, context)` 生成链接，`navigateCanvasPage(entry, context)` 执行动作。context 的 appType 与必要时的 platformOrigin 来自实际资源；浏览器正常平台页面默认使用当前 origin，非平台或 opaque 嵌入时显式提供已核实的 origin，不猜域名，也不强行读取顶层窗口。表单动作接入已有 openForm；本页视图接入 selectView。跨应用目标在 entry.appType 中显式声明。
-
-```jsx
-// APP_TYPE 与 ROOM_PAGE_ID 必须来自本项目资源映射。
-const roomEntry = { targetType: 'custom', formUuid: ROOM_PAGE_ID };
-const navigationContext = { appType: APP_TYPE };
-// 放进业务组件；href 与普通左键点击共用同一目标，保留修饰键和新标签行为。
-<a href={buildCanvasPageUrl(roomEntry, navigationContext)} onClick={event => {
-  if (event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
-  event.preventDefault();
-  navigateCanvasPage(roomEntry, navigationContext);
-}}>查看客房</a>
-```
-
-应用内 HTTP 路径均保留 `/{appType}` 前缀。`/custom/...`、`/workbench/...`、`/submission/...`、`/formDetail/...` 是缺少应用身份的地址，换成绝对域名也不能修复缺失的 appType。纯页面 ID 的 `router.push('FORM-...', params)` 属于平台路由模式，与完整 URL 模式区分。桥不可用时片段在当前窗口打开完整地址；确需离开嵌入容器时先验证宿主约定，不将 `window.top` 作为默认 fallback。
-
-编译/发布会在可静态确定的 href、浏览器导航与 router/openPage 目标中检查缺失前缀，报 `OPENYIDA_CANVAS_PATH_MISSING_APP_TYPE`。字符串片段、注释和动态地址不等于完整目的地，不做全局字符串拦截。该检查不能证明页面 ID 属于正确应用或用户有权限；发布验收仍需逐个点击主动作、返回链接和菜单，核对真实地址、query/hash、目标用途及浏览器返回。
-
-## 管理员返回业务工作台
-
-当前访问者具有应用管理权限时，可在独立前台页头操作区展示次级按钮“业务工作台”。沿用当前主题，不作为普通访客菜单，不跳应用设计器、应用设置或开发后台。先从 PRD 的管理端入口及资源回读确定真实业务管理页，不把当前前台页或任意第一个菜单当作工作台。
-
-```bash
-openyida sample openyida-page-template canvas-admin-entry --output .cache/samples/canvas-admin-entry.jsx
-```
-
-片段包含统一跳转 helper、身份判断、hook 与按钮。整体合并，已有 `canvas-navigation` 或 React/Button import 时去重；按钮放在已接入的 CanvasThemeProvider 子树内：
-
-```jsx
-<CanvasAdminWorkbenchButton
-  appType={APP_TYPE}
-  workbenchFormUuid={MANAGEMENT_PAGE_ID}
-  params={{ corpid: CORP_ID }}
-/>
-```
-
-这些常量必须来自真实应用和资源映射；没有 corpid 需求时省略 params。指定管理视图可传 viewUuid。默认使用 `/{appType}/workbench/{workbenchFormUuid}`，不继承前台的 isRenderNav/iframe/hideLeftNav/navConfig.layout 参数。只有已验证应用默认工作台落点正确时才省略页面 ID 并显式传 `useDefaultWorkbench`；默认工作台可能回到前台首页。整个应用采用自绘管理壳时，应选择实际承载该业务壳的页面，并验证其入口，不能靠按钮擅自开启或隐藏应用导航。
-
-身份来自当前页面服务端注入的 `window.loginUser.isAppAdmin`，同时核对当前窗口的 `window.g_config.appType` / `window.pageConfig.appType` 与目标 appType 一致、userId 非空。访问态可能只提供 pageConfig；至少有一个非空应用标识，存在两个时必须全部一致，冲突仍按未知处理。只把 `"y"` 或布尔 true 视为允许；`"n"`/false 拒绝，其余未知。禁止 `Boolean(isAppAdmin)` 或 `if (isAppAdmin)`，因为 `"n"` 是真值。没有上下文、应用不匹配、匿名访问时隐藏，不读取父窗口另一应用的角色，不写死管理员名单，也不使用 CLI 操作者身份或 token 判断访问者。
-
-这个标识采用平台的 `isSuperOrAppManager` 口径，可能覆盖超级管理员、应用主管理员、数据管理员、开发成员及平台授权角色；它不等价于仅 MAIN，也不等价于某业务角色。若需求限定“仅主管理员”或“业务运营人员”，需另接已验证的当前访问者角色/权限服务，不通过姓名、菜单可见性或复制 CLI 管理员列表代替。
-
-按钮初始隐藏，读取上下文后显示；切换应用时旧状态不复用，回到页面时重读上下文，点击前再次读取。这里读取的是服务端页面上下文快照，刷新事件不会主动向权限服务查询最新授权；账号或权限已变化时需刷新页面，平台页面与数据接口始终承担真实授权。按钮显隐不授予任何业务权限。
-
-双入口应用保留 `hideAppNav=n`，只让独立前台按既定页面配置隐藏导航。验证管理员能进入指定业务工作台、普通访问者及匿名访问者不显示按钮、缺少上下文不会闪现、目标保留平台导航和业务参数。公开页与嵌入页缺少登录上下文时保持隐藏；不要为显示按钮而发起管理员名单查询或修改权限。
-
 ## 导航决策
 
-页内筛选、分页、详情往返与草稿按[状态恢复规则](view-state-recovery.md)设计。无现有路由且无未保存编辑拦截需求时可提取 `canvas-view-state`，不要在点击处理里零散保存状态。管理员入口只负责展示和跳转，业务写操作须加载 `yida-canvas-data-binding` 并核对其业务动作权限清单。
-
 | 用户说法 | 怎么理解 | 怎么做 |
 | --- | --- | --- |
 | “加侧边导航 / 顶部导航 / 导航壳 / 自绘应用导航” | 自定义页要承担应用级导航 | 进入 `yida-nav-shell`，并执行 `openyida update-app <appType> --hide-app-nav` |
@@ -171,17 +87,17 @@ openyida sample openyida-page-template canvas-admin-entry --output .cache/sample
 
 ## 按需接入自定义导航
 
-PRD 确定使用自定义导航时，按 `design.md` 编写导航 UI，先参考 [导航壳形态目录](../../yida-nav-shell/references/nav-shell-patterns.md) 的场景、布局骨架和小段代码，再按业务设计手写外观或迭代已有导航。顶部按连续展示页或业务工作区决定叠加/占位和背景范围，侧导必须支持折叠与拖拽调宽。菜单数据、可见性过滤、当前页和跳转按目录中的协议接入，样式消费应用导航 token；不以选择 CLI 导航模板作为起点。页内切换和跨任务往返均遵循 [页面与导航连续性](../../yida-design/references/page-continuity.md)。
+PRD 确定使用自定义导航时，按 `design.md` 编写导航 UI，先参考 [导航壳形态目录](../../yida-nav-shell/references/nav-shell-patterns.md) 的场景、布局骨架和小段代码，再按业务设计手写外观或迭代已有导航。自定义顶部默认浮导，侧导必须支持折叠与拖拽调宽。菜单数据、可见性过滤、当前页和跳转按目录中的协议接入，样式消费应用导航 token；不以选择 CLI 导航模板作为起点。
 
 ## 标准 FormOpenContainer
 
-页面内操作按钮去新增、提交或查看表单详情时，必须使用 CLI 提供的 `FormOpenContainer` 模板，不凭描述重写同名组件。按钮事件调用 `openForm(request)`，页面 JSX 渲染 hook 返回的 `formOpenContainer`；只有定义没有挂载，不算接入。新标签只用于外部 URL 或用户主动点击抽屉标题栏的新窗口操作。PC 端容器表现为右侧抽屉 + iframe，移动端由模板打开原生表单页，关闭抽屉后触发当前页刷新。已明确的应用级办理导航可在主内容区嵌入原生提交页，导航选中态与当前任务一致。
+页面内操作按钮去新增、提交或查看表单详情时，统一封装成同一个 `FormOpenContainer`。按钮事件只调用 `openForm(request)`；新标签只用于外部 URL 或用户主动点击抽屉标题栏的新窗口操作。PC 端容器表现为右侧抽屉 + iframe，移动端直接进入原生表单页，关闭抽屉后触发当前页刷新。应用级办理导航的提交页在主内容区嵌入，导航选中态与当前任务一致。
 
-YidaCodeCanvas 推荐使用 antd `Drawer`。`FormOpenContainer` 只负责打开原生提交页或详情页。通用 `CanvasDrawer` 提供标题栏、全屏/退出全屏、关闭和 `extra` 操作区，表单容器额外提供新窗口打开。普通业务内容容器保持透明，跟随抽屉外壳背景。
+YidaCodeCanvas 推荐使用 antd `Drawer`。`FormOpenContainer` 只负责打开原生提交页或详情页。通用 `CanvasDrawer` 提供标题栏、全屏/退出全屏、关闭和 `extra` 操作区，表单容器额外提供新窗口打开。只有普通业务内容模式使用内容卡片。
 
 抽屉 header 的工具操作统一使用图标按钮：新窗口打开用 `ExternalLink`，全屏/退出全屏用 `Maximize2` / `Minimize2`，关闭用 `X`。表单抽屉三个操作必须齐全，不得替换为“在新窗口打开”“关闭”等可见文字链接，也不得省略全屏。每个按钮提供对应的 `title`、`aria-label` 和可见键盘焦点；全屏按钮同时更新图标、提示和 `aria-pressed`。按钮默认使用中性色，hover、focus 跟随主题。发布前逐一验证三个按钮的实际行为，不以按钮已渲染代替验收。
 
-抽屉外壳默认使用 `var(--pod-shell-theme-bg-color, var(--color-white, #fff))`，标题栏与正文容器透明承接同一底色，不使用 `--pod-card-bg-color` 铺满抽屉。CanvasThemeProvider 同步设置 antd Drawer 的组件级背景；其他卡片、弹窗保留各自表面。只有明确的设计覆盖才传 CanvasDrawer.background 或 openForm 的 background，不主动生成卡片色覆盖。抽屉外壳的标题、正文和标题栏按钮默认使用 `--pod-page-header-text-color`，回退到 `--color-text1-4`，显式的 drawer 颜色变量仍可覆盖对应角色。外壳背景跟随应用框架，内部 iframe 独立呈现表单或详情页。传入 `background` 时同时检查标题、按钮和正文的可读性。iframe 内页面继续使用平台主题。
+模板已内置抽屉主题样式，背景默认使用 `--pod-shell-theme-bg-color`。自定义背景时传入 `CanvasDrawer.background`；表单入口通过 `openForm({ type: 'submission', formUuid, background: 'var(--pod-card-bg-color)' })` 设置。iframe 内页面使用平台主题。
 
 提交页和详情页统一由 `FormOpenContainer` 使用 `contentMode="iframe"`：iframe 直接填满标题栏下方的剩余空间，外层不加 `oy-drawer-card`、卡片底色、圆角或 padding，也不设置外层滚动。`oy-drawer-frame` 仅负责尺寸定位和裁切；滚动由 iframe 内页面负责。不要恢复 `calc(100vh - 56px)` 等猜测高度的兜底。
 
@@ -224,28 +140,83 @@ function ExampleToolbar({ appType, customerFormUuid, selectedCustomer, reload })
 }
 ```
 
-已有页面的表单入口也按标准片段接入，保留业务数据、刷新回调和权限校验；不另写缺少交互能力的抽屉外壳。
+如果项目没有使用 antd Drawer，可以用自绘 fixed 右侧面板，但组件名、状态结构和 URL 构造仍沿用 `FormOpenContainer / useYidaFormOpen / buildYidaFormUrl`。
 
 ## Canvas 点击骨架
 
 Canvas 自绘快捷入口时，表单提交和详情入口沿用 `useYidaFormOpen` 返回的 `openForm`。应用内页面用同页跳转，外部链接才新开；提交页在 PC 端进入抽屉，移动端才整页或新页打开，提交页 URL 默认追加 `isRenderNav=false`；详情页 URL 必须包含真实 `formInstId`，并默认追加 `navConfig.layout=1180` 和 `isRenderNav=false`：
 
-合并 `canvas-navigation` 片段后，只适配业务数据，不另写一套路径拼接：
-
 ```js
-function openEntry(entry, currentAppType, runtime) {
-  const target = entry.targetType === 'detail'
-    ? { ...entry, formInstId: getYidaFormInstId(entry.row) || entry.formInstId }
-    : entry;
-  return navigateCanvasPage(target, {
-    appType: currentAppType,
-    openForm: runtime.openForm,
-    selectView: runtime.selectView,
-    utils: window.__OPENYIDA_UTILS__,
+function getOpenYidaUtilsBridge() {
+  var candidates = [];
+  try { candidates.push(window.__OPENYIDA_UTILS__); } catch (err) {}
+  try { candidates.push(window.parent && window.parent.__OPENYIDA_UTILS__); } catch (err) {}
+  try {
+    if (typeof parentWindow !== 'undefined') {
+      candidates.push(parentWindow.__OPENYIDA_UTILS__);
+    }
+  } catch (err) {}
+  return candidates.find(function (item) { return item && item.ready; }) || null;
+}
+
+function buildYidaBasePath(entry, currentAppType) {
+  const appType = entry.appType || currentAppType;
+  if (entry.targetType === 'app') return `/${appType}/workbench`;
+  if (entry.targetType === 'page') return `/${appType}/workbench/${entry.navUuid || entry.formUuid}`;
+  if (entry.targetType === 'submission') {
+    return `/${appType}/submission/${entry.formUuid}?isRenderNav=false`;
+  }
+  if (entry.targetType === 'detail') {
+    if (!entry.formInstId) return '';
+    return `/${appType}/formDetail/${entry.formUuid}?formInstId=${encodeURIComponent(entry.formInstId)}&navConfig.layout=1180&isRenderNav=false`;
+  }
+  return entry.url || '';
+}
+
+function buildYidaPath(entry, currentAppType) {
+  const path = buildYidaBasePath(entry, currentAppType);
+  if (!path) return '';
+  const url = new URL(path, window.location.origin);
+  Object.entries(entry.params || {}).forEach(([key, value]) => {
+    if (value !== undefined && value !== null && value !== '') {
+      // 路径已带的必需参数（如真实实例 ID）优先，其他业务参数合并。
+      if (!url.searchParams.has(key)) url.searchParams.set(key, String(value));
+    }
   });
+  return url.href;
 }
-```
 
+function openEntry(entry, currentAppType, runtime) {
+  if (entry.targetType === 'submission' || entry.targetType === 'detail') {
+    runtime.openForm({
+      type: entry.targetType,
+      title: entry.title || '表单',
+      appType: entry.appType || currentAppType,
+      formUuid: entry.formUuid,
+      formInstId: getYidaFormInstId(entry.row) || entry.formInstId,
+      params: entry.params,
+    });
+    return;
+  }
+
+  const href = buildYidaPath(entry, currentAppType);
+  if (!href) return;
+  const utilsBridge = getOpenYidaUtilsBridge();
+  if (entry.targetType === 'url' || entry.openMode === 'new-tab') {
+    if (utilsBridge && typeof utilsBridge.openPage === 'function') {
+      utilsBridge.openPage({ url: href });
+      return;
+    }
+    window.open(href, '_blank');
+    return;
+  }
+  if (utilsBridge && utilsBridge.router && typeof utilsBridge.router.push === 'function') {
+    utilsBridge.router.push(href, {}, false, true);
+    return;
+  }
+  window.location.href = href;
+}
+```
 
 `getYidaFormInstId` 复用 CLI 抽屉片段中的同名 helper。复制或重命名 helper 时必须连同声明和全部调用点一起修改，不能只生成 `getInstId(...)` 等新调用名。
 

package/yida-skills/skills/yida-canvas-custom-page/references/page-generation-guide.md

@@ -10,22 +10,21 @@
 
 结构化实现工具提供可编译运行时结构、数据桥、主题变量和基础 primitives。真实业务页结合 `prd.md` 落地业务化区块顺序、数据和文案，结合 `design.md` 落地信息层级、局部构图和样式节奏。
 
-PRD 写有 `pageSpecHandoff` 时，可以把 `pageSpecHandoff` 转成 `page-spec.json`；其中 `entryMode`、`navigation`（只作用于当前入口）、`pageStructure`、`scene`、`contentBlocks`、`themeSummary`、`designFile`、`designRefs`、`dataBinding` 和 `primaryAction` 是页面实现的业务输入。随后读取 `designFile`：用 `designRefs` 查 frontmatter 的场景、组件和状态索引，再按显式 anchor 找到当前页八项设计与共享规则。格式见 [design.md 公共输出契约](../../yida-design/workflow/output-design.md)；索引不是规则正文，不能只读元数据就实现。
-
-平台导航管理页默认生成纯业务内容，跨模块菜单由平台负责；不要从 `entryRecommendation.menu` 再生成页面侧栏或模块 Tabs。Plan 的 `pages[].navigationPolicy` 与 `pageSpecHandoff` 一并作为实现上下文，Fast 同样记录导航归属；详见[管理页面边界](navigation-and-entry-guide.md#平台导航下的管理页面)。
+PRD 写有 `pageSpecHandoff` 时，可以把 `pageSpecHandoff` 转成 `page-spec.json`；其中 `pageStructure`、`scene`、`contentBlocks`、`themeSummary`、`designFile`、`designRefs`、`dataBinding` 和 `primaryAction` 是页面实现的业务输入。随后必须读取 `designFile` 指向的 `design.md`，用 `designRefs` 找到 `visualScaffold`、`backgroundLayer`、`surfaceMaterial`、`surfaceContrast`、`colorRoles`、`depthRule`、`roundedRule`、`densityRule`、`breathingRule`、组件和状态规则。
 
 ## Source Of Truth
 
-业务按 `prd.md` 实现，视觉按 `design.md` 实现。手写页面可直接使用这两份文件；使用生成器时，先整理 `page-spec.json`：
+`prd.md` 和 `design.md` 是唯一设计事实源。`page-spec.json` 只是页面实现阶段的派生文件，用于喂给生成器或保存一次稳定交接，不是第三份设计文件。
 
-- 业务字段来自当前 PRD。
-- 视觉部分保存 `designFile/designRefs` 和一致的 `themeSummary`，完整视觉规则从 design.md 读取。
-- `sourceOfTruth` 填写 `prdFile`、`designFile`、`designRefs` 和 `conflictPolicy = "prd-design-win"`。
-- spec 与 PRD/design.md 冲突时，按这两份文件重新生成 spec。
+- `page-spec.json` 必须由当前 `prd.md + design.md` 派生，不允许凭空新增视觉规则、页面结构或业务功能。
+- `page-spec.json` 不复制 `visualScaffold`、`surfaceMap`、`componentRecipe`、tokens、完整色盘或组件规则；只保存 `designFile/designRefs` 和与 design.md 一致的 `themeSummary`。
+- spec 必须包含 `sourceOfTruth.prdFile`、`sourceOfTruth.designFile`、`sourceOfTruth.designRefs` 和 `sourceOfTruth.conflictPolicy = "prd-design-win"`。
+- spec 与 PRD/design.md 冲突时，以 PRD/design.md 为准，重新生成 spec；不要修改 PRD/design.md 来迎合旧 spec。
+- 手写页面且结构清楚时可以跳过 `page-spec.json`，但源码实现备注必须能说明已读取 `prd.md` 和 `design.md`。
 
-按页面任务组织内容：工作台通常包含状态摘要、高频动作、待办、动态和上下文信息；列表页通常包含搜索筛选、列表或表格、详情预览，以及空态和错误时的下一步操作。工作台、首页、门户、看板和展示页推荐 8-10 个有业务目的的区块，窄场景或精简需求按实际任务减少。KPI 子项、快捷入口子项和列表行计入各自所属区块。
+实现阶段不再从 PRD 里反推视觉，也不直接读取 `references/style-designs/`。该目录只在 yida-design 阶段提供 `design.md` 结构模板；`YidaCodeCanvas` 组件实现只遵守当前项目的 `design.md`。工作台/业务首页通常需要圆润紧凑状态摘要、高频动作、待办/动态/最近记录和右侧上下文；实现阶段用这些结构替代“4 个等宽大 KPI 白卡 + 图标快捷卡 + 大空态白卡”。列表/管理页通常需要顶部视觉区、搜索筛选区、左侧列表或表格、右侧详情预览、错误/空态下一步动作；实现阶段用这些结构替代单个渐变标题、单个指标卡和大块空白提示。工作台、首页、门户、看板、展示页和业务入口页推荐落地 8-10 个有业务目的的区块以上；区块可以紧凑组合，不能用重复 KPI 卡、重复快捷入口或大空白卡凑数；KPI 子项、快捷入口子项和列表行不计入区块数量。窄场景或用户要求精简时可以更少，不应因此阻塞实现。
 
-如果当前页面正文没有具体布局、表面与组件、状态、响应式或验收安排，先补设计事实再实现。圆角、padding、gap 和密度采用选中主题与当前页决定，不能用固定大圆角或统一间距覆盖主题。状态、列表、动作与空态按真实内容组织，不用空白容器撑满首屏。
+如果当前 `design.md` 缺少 `roundedRule`、`densityRule` 或 `breathingRule`，先回写设计文件再实现。默认业务页应写清卡片 padding >20px、卡片 gap <20px、卡片圆角 0-32px；状态摘要、任务列表、动作条和空态保持紧凑，不得用额外 margin、超宽空状态框或空白高度制造“高级感”。
 
 页面实现路径二选一：结构化实现路径先从 `prd.md + design.md` 派生业务化 `page-spec.json` 并生成可编译骨架，之后读取 CLI 摘要或 `.openyida-page.json`。若发现业务或视觉事实源缺失，先回写 `prd.md` / `design.md` 并重生成 spec；只有实现偏差才对生成源码做小范围 Edit/patch。手写路径直接 Write 最终 `.canvas.jsx`。
 
@@ -43,22 +42,22 @@ PRD 写有 `pageSpecHandoff` 时，可以把 `pageSpecHandoff` 转成 `page-spec
 | 问题类型 | 必须修改哪里 | 不允许的做法 |
 | --- | --- | --- |
 | 页面目标、业务对象、指标口径、主操作、表单入口、数据来源、`contentBlocks`、空/载/错业务语义不足或错误 | 回写 `prd.md`，再重新派生 `page-spec.json` | 只在 `page-spec.json` 或源码里新增业务区块、指标和动作 |
-| 主题关系、token、页面布局、表面层次、色彩角色、形状、密度、组件状态或响应式不足或错误 | 回写 `design.md`，再重新派生 `page-spec.json` 或重读 design.md 实现 | 只在源码里临时写 CSS、主色、玻璃感、卡片材质、圆角、密度、呼吸感或状态样式 |
+| 主题关系、token、`visualScaffold`、`backgroundLayer`、`surfaceMaterial`、`surfaceContrast`、`colorRoles`、`depthRule`、`roundedRule`、`densityRule`、`breathingRule`、组件规则、状态规则、响应式规则不足或错误 | 回写 `design.md`，再重新派生 `page-spec.json` 或重读 design.md 实现 | 只在源码里临时写 CSS、主色、玻璃感、卡片材质、圆角、密度、呼吸感或状态样式 |
 | `page-spec.json` 缺少 `sourceOfTruth`、`designFile/designRefs`、`dataBinding` 字段，或与 `prd.md/design.md` 不一致 | 丢弃并从最新 `prd.md + design.md` 重新生成 `page-spec.json` | 修改 PRD/design.md 来迎合旧 spec，或把 design.md 的完整视觉规则复制进 spec |
 | 已创建或解析业务表单，但页面源码没有 `dataBinding.mode=form`、没有 `useYidaData` / `DataBridge`，或没有优先消费 `window.__OPENYIDA_YIDA_API__` | 补齐 `page-spec.json` 的真实 `dataBinding`，读取 `data-bridge-guide.md` 后重新生成或小范围修复源码 | 默认手写 `/query/form/searchFormDatas.json` 或 `/v1/form/searchFormDatas.json` fetch，缺字段映射，或用前端 seedRows 冒充真实表单数据 |
 | PRD、design.md 和 spec 都完整，但生成源码存在 className、布局比例、字段映射、响应式、loading/empty/error 渲染、编译错误等实现偏差 | 小范围 Edit/patch 源码 | 借源码 patch 新增 PRD 未定义的页面区块、业务动作或 design.md 未定义的视觉风格 |
 
 源码 patch 过程中一旦发现需要新增业务区块、改页面目标、改主题关系或补视觉规则，停止 patch，先回写 `prd.md` 或 `design.md`，再重新派生 spec 或重读两份事实源实现。
 
-设计内容直接映射到源码：外壳、首屏焦点、主要内容、动作、必要上下文、状态反馈与响应式都应有实现位置。`design.md` 的页面正文覆盖这些含义即可，不要求旧 `visualScaffold` 或同名 primitive 字段；没有真实内容的可选侧栏、指标或图形不渲染。
+`visualScaffold` 必须来自 `design.md`，并映射到源码 primitive：`rootShell`、`prioritySurface`、`statusPrimitive`、`actionPrimitive`、`contentPrimitive`、`contextPrimitive`、`statePrimitive`、`responsiveRule`、`roundedRule`、`densityRule` 和 `breathingRule`。如果只有区块名称，没有这些源码级槽位，先补 design.md，不要直接开始写 CSS。
 
-玻璃、光影、纹理、流光与不规则背景只在已确认设计需要时实现。玻璃明确半透明表面、边框、背景关系和 `backdrop-filter`；光洗不能干扰阅读，流光提供 `prefers-reduced-motion` 静态降级。背景可以自由，内容仍保持栅格、对齐、行高与操作位置稳定；平整画布主题不为“高级感”额外添加装饰。
+页面要求玻璃感、质感、背景感、光影、流光、不规则顶部或丰富色彩时，必须消费 `backgroundLayer`、`surfaceMaterial`、`colorRoles` 和 `depthRule`：页面根节点优先使用 `softTintCanvas`、带弱渐变的近白画布、细线装饰或素材焦点，再按 `design.md` 选择 `topIrregularWash`、`radialGlowWash`、`flowLight` 或 `organicNoise`。`topIrregularWash` 用顶部波浪、斜切、有机色块、轻装饰曲线或图形标记形成首屏背景；`radialGlowWash` 使用大面积柔和光洗，不使用离散装饰圆球或 bokeh；`flowLight` 必须低速低透明，并写 `prefers-reduced-motion` 静态降级。玻璃面板使用半透明 `rgba` 表面、`backdrop-filter`、细边框和柔和阴影；色彩角色至少区分应用主色、辅助色、语义色和图表色。纯白背景 + 普通纯白不透明卡片不满足玻璃感页面；但近白画布如果有渐变、装饰、素材焦点或足够内容密度，可以作为背景感方案。
 
-画布、内容面与边界按设计正文和 token 实现。同色画布与卡片可以通过细边界、共容器或留白建立层次；灰底不必统一无边框，渐变不强制搭配玻璃。验收看是否还原当前主题，不用另一套统一材质或尺寸规则覆盖它。
+实现页面背景和卡片时必须消费 `surfaceContrast`：页面背景与卡片背景不可相近或相同。白色/浅色背景配有边框卡片；浅灰背景（如 `#F3F4F6`）配白色无边框卡片；浅彩色背景配白色无边框卡片；渐变背景配玻璃感卡片。源码不得输出浅底白卡无边框、同色背景同色卡片，或只靠弱阴影区分层级。
 
-按 design.md 第 2 章已合并的项目配色和导航规则实现，不从模板重新推导另一套默认值；整体绿色风格不能只让按钮变绿。卡片背景使用 `var(--pod-card-bg-color, var(--color-white, #fff))`，边界消费 `--pod-card-border`；页面、卡片、导航、表头、文字与控件一并核对。antd 页面通过主题脚本统一映射主色、容器、文字、填充和边框；语义色暂用 antd 默认值，不能把所有状态改成品牌色。
+design.md 存在“项目配色适配”时先应用该节，它高于模板默认灰阶/品牌面积约束；整体绿色风格不能只让按钮变绿。卡片背景使用 `var(--pod-card-bg-color, var(--color-white, #fff))`，边界消费 `--pod-card-border`；页面、卡片、导航、表头、文字与控件一并核对。antd 页面通过主题脚本统一映射主色、容器、文字、填充和边框；语义色暂用 antd 默认值，不能把所有状态改成品牌色。
 
-设计需要背景装饰层时，先写根节点和伪元素，再写内容网格：`.oy-page-root` 承载基础底色、`::before` 承载不规则顶部色块或光洗、`::after` 承载低速流光或弱纹理，`.oy-page-content` 使用 `position: relative; z-index: 1;`。背景可以不规则，内容必须规则；标题、筛选、表格、图表、按钮和列表都保持稳定栅格、对齐和对比度。
+实现背景层时先写根节点和伪元素，再写内容网格：`.oy-page-root` 承载基础底色、`::before` 承载不规则顶部色块或光洗、`::after` 承载低速流光或弱纹理，`.oy-page-content` 使用 `position: relative; z-index: 1;`。背景可以不规则，内容必须规则；标题、筛选、表格、图表、按钮和列表都保持稳定栅格、对齐和对比度。
 
 数据真实性边界：
 
@@ -81,9 +80,7 @@ PRD 写有 `pageSpecHandoff` 时，可以把 `pageSpecHandoff` 转成 `page-spec
 
 ### 导航生成规则
 
-先读应用 navigationType 和当前页 pageSpecHandoff。前台 standalone + navigation.custom 只自绘当前入口菜单，不修改 appBlueprint.hideAppNav；后台继续使用平台导航。前后台页面内普通表单提交与详情均接入 CLI 的 `form-open-container` 模板；全码开发不豁免，不另写填写提交 UI。查询、筛选和展示继续按页面设计实现。
-
-自定义导航按 PRD 和 `design.md` 直接实现；参考 [导航壳形态目录](../../yida-nav-shell/references/nav-shell-patterns.md) 的场景与骨架，UI 示例按需查阅。连续展示页使用共同首屏画布与页面滚动，业务工作区保留导航占位和剩余高度；侧边及混合布局支持折叠、恢复宽度和拖拽调宽。菜单同时记录入口用途和打开方式：管理走 workbench，填写走 submission；本页视图切状态，保留导航的表单入口更新主内容 iframe，同标签跨页仅用于已确认承载同一导航壳的目标。页面内新增/详情按钮沿用 FormOpenContainer，切换与返回按 [页面与导航连续性](../../yida-design/references/page-continuity.md) 保留上下文。
+自定义导航按 PRD 和 `design.md` 直接实现；参考 [导航壳形态目录](../../yida-nav-shell/references/nav-shell-patterns.md) 的场景与骨架，UI 示例按需查阅。顶部默认浮导；侧边及混合布局支持折叠、恢复宽度和拖拽调宽。菜单同时记录入口用途和打开方式：管理走 workbench，填写走 submission；本页视图切状态，保留导航的表单入口更新主内容 iframe，跨页入口默认当前标签跳转。页面内新增/详情按钮沿用 FormOpenContainer。
 
 完整地址通过数据桥使用 `router.push(href, params, false, true)`；省略 URL 模式的自动识别只作兼容，详见 [路由模式与数据桥兜底](../../yida-nav-shell/references/nav-shell-patterns.md#路由模式与数据桥兜底)。导航显示参数不控制是否新开标签。
 
@@ -91,8 +88,8 @@ PRD 写有 `pageSpecHandoff` 时，可以把 `pageSpecHandoff` 转成 `page-spec
 | --- | --- | --- |
 | 普通自定义页、工作台、门户、看板、首页 | 不写 `hideAppNav` | 保留平台应用导航 |
 | 页面内 tab、分段筛选、内容区快捷入口 | 不写 `hideAppNav` | 保留平台应用导航 |
-| 整个应用的顶部导航、侧边导航、导航壳、自绘应用级导航 | 写 `appBlueprint.hideAppNav: 'y'` | 执行 `openyida update-app <appType> --hide-app-nav` |
-| 独立前台菜单、页面隐藏导航、无导航全屏、`isRenderNav=false` | 写 `appBlueprint.renderNav: false` | 执行 `openyida update-form-config <appType> <formUuid> false "<页面标题>"` |
+| 自定义页顶部导航、侧边导航、导航壳、自绘应用级导航 | 写 `appBlueprint.hideAppNav: 'y'` | 执行 `openyida update-app <appType> --hide-app-nav` |
+| 页面隐藏导航、无导航全屏、`isRenderNav=false` | 写 `appBlueprint.renderNav: false` | 执行 `openyida update-form-config <appType> <formUuid> false "<页面标题>"` |
 
 两条规则必须分开：`hideAppNav` 控制应用导航，`renderNav/isRenderNav=false` 控制页面导航。其他自定义页默认不调用 `update-app --hide-app-nav`。
 
@@ -109,13 +106,13 @@ PRD 写有 `pageSpecHandoff` 时，可以把 `pageSpecHandoff` 转成 `page-spec
 
 ## 官网与品牌页素材
 
-按 `design.md.assetStrategy` 调用 `yida-image-assets`。读取当前页的 `asset-manifests/<pageId>.json`（已有项目可用总清单 `asset-manifest.json`）中 `pages[].materialStatus`；当前页为 `final` 时，只读取该页 `assets[].materialStatus=final` 的图片 URL。总状态为 `draft` 不阻塞已就绪的页面；不手拼 URL，也不内嵌 data URI。
+按 `design.md.assetStrategy` 调用 `yida-image-assets`。读取 `asset-manifest.json` 中当前页面 `pages[].materialStatus`；当前页为 `final` 时，只读取该页 `assets[].materialStatus=final` 的图片 URL。总状态为 `draft` 不阻塞已就绪的页面；不手拼 URL，也不内嵌 data URI。
 
 联网搜图仅使用 Unsplash/Pexels。Unsplash 保留 API 热链和署名；Pexels 保留来源页和摄影师信息。
 
 ## 主题实现
 
-antd 页面按 [CanvasThemeProvider 指南](canvas-theme-provider.md) 统一接入主题。已有 Provider 或直接合并 Provider 的页面编译发布原文件；仅使用标记和主题脚本时，才编译发布生成的 `.themed.canvas.jsx`。纯 DOM 页面直接使用应用 CSS 变量。
+新 antd 页面按 [CanvasThemeProvider 指南](canvas-theme-provider.md) 装配主题；只编译和发布装配后的文件。纯 DOM 页面不需要 Provider；旧 hook 页面按该指南迁移，不能重复接入。
 
 主题色决策来自 `yida-design` 的 `design.md`。`app-theme.css` 只在应用级配置，由平台统一作用于整个应用。
 
@@ -150,13 +147,13 @@ antd 页面按 [CanvasThemeProvider 指南](canvas-theme-provider.md) 统一接
   "sourceOfTruth": {
     "prdFile": "prd/渠道增长应用/prd.md",
     "designFile": "prd/渠道增长应用/design.md",
-    "designRefs": ["themeProfile", "sceneRecipes.dashboard", "components.chart", "states.empty"],
+    "designRefs": ["themeProfile", "sceneRecipes.dashboard", "components.charts", "states.empty"],
     "conflictPolicy": "prd-design-win"
   },
   "pageStructure": "dashboard-overview",
   "scene": "dashboard",
   "designFile": "prd/渠道增长应用/design.md",
-  "designRefs": ["themeProfile", "sceneRecipes.dashboard", "components.chart", "states.empty"],
+  "designRefs": ["themeProfile", "sceneRecipes.dashboard", "components.charts", "states.empty"],
   "themeSummary": {
     "themeColor": "青绿色应用主题",
     "styleKeywords": ["运营洞察", "轻量玻璃感", "高密信息"]
@@ -201,18 +198,18 @@ antd 页面按 [CanvasThemeProvider 指南](canvas-theme-provider.md) 统一接
 | `official-homepage` | Real-scene hero、Product/service visual、Process/space story、Visit/service section、CTA |
 | `data-screen` | Command map、Metric grid、Rank panel、Screen insight header |
 
-工作台状态摘要按主题保持紧凑，未定义时可参考 64-88px；不使用横跨整页但内容稀疏的空矩形；快捷入口必须有分组和主次，不能平铺成图标卡阵列；待办、动态、最近记录、洞察、提醒和右侧上下文推荐组合成 8-10 个业务目的区块以上，但不作为硬门槛。空数据也用薄空态行 + 主操作入口，不渲染大块空白卡片。
+工作台的状态摘要必须是 64-88px 圆润紧凑状态条，不是 180px 高的大白卡，也不是横跨整页但内容稀疏的空矩形；快捷入口必须有分组和主次，不能平铺成图标卡阵列；待办、动态、最近记录、洞察、提醒和右侧上下文推荐组合成 8-10 个业务目的区块以上，但不作为硬门槛。空数据也用薄空态行 + 主操作入口，不渲染大块空白卡片。
 
 展示型自定义页面验收时检查 `contentBlocks` 或源码结构：工作台、首页、门户、看板、展示页和业务入口页应有足够多有业务目的的区块；每个区块承担不同任务，例如判断状态、发起动作、筛选、处理待办、查看动态、看洞察、看异常、进入详情、处理空态或补充上下文。区块数量不作为阻塞实现的硬门槛。若 PRD 只写“`KPI 卡片: 学生总数, 课程总数, 本月出勤率, 平均分`、`快捷入口: 录入学生/登记成绩/记录考勤/管理课程`、`最近成绩列表`、`最近考勤记录`”，实现前建议补充 `contentBlocks`；若业务确实是窄场景，可以继续实现并说明取舍。
 
-所有展示型页面都按当前项目 `design.md` 的页面八项要点与共享规则实现。若只有业务区块和视觉形容词，没有实际布局、表面、组件和响应式决定，先补设计源事实：
-
-1. 按当前页正文中的布局安排放置真实 `contentBlocks`，不从主题示例补造业务内容。
-2. 按表面与组件说明选择开放区、连续行、表格或必要容器，并引用对应共享组件 anchor。
-3. 用主题 token 与明确的局部数值实现间距、圆角和层次，保持首屏焦点与内容主次。
-4. 按主操作、状态与响应式说明实现动作、反馈、恢复入口及窄屏重排。
-5. 将实际页面八项验收逐条对应源码和截图；实现偏差局部修正，设计事实变化先更新源事实。
+所有展示型页面都按当前项目 `design.md` 的 `visualScaffold` 实现。若 PRD 只有业务区块、design.md 只有视觉形容词，没有明确 `layoutRecipe` / `surfaceMap` / `componentRecipe`，先回到 `prd/<项目名>/design.md` 补齐：
 
-整页刷新时，表格加载遮罩可能因 `transition: all` 遇到延迟加载的基础样式而闪出黑边。标准 Provider 已将遮罩边框固定为零，只保留透明度过渡；保留内置 style，旧页面按 [主题接入步骤](canvas-theme-provider.md) 更新 Provider 并重新发布，不通过修改主题色或全局清除边框处理。
+1. 先把 `contentBlocks` 映射到 `layoutRecipe` 的槽位。
+2. 按 `surfaceMap` 决定无框区、细线面板、浅底条、列表行、表格、右侧栏或抽屉，不能把所有区块都做成卡片。
+3. 按 `sectionRhythm` 排序和控制间距，保证首屏有主次和至少两层信息。
+4. 按 `roundedRule`、`densityRule` 和 `breathingRule` 写圆角、padding、gap、跨区块间距、列表行高、状态摘要高度、空态高度和贴边修正。
+5. 按 `componentRecipe` 统一按钮、入口、标签、图标、列表、图表和空态。
+6. 按源码 primitive 写组件：外层壳、首屏最大视觉锚点、状态摘要、动作条、主要内容、右侧上下文、状态处理和响应式规则都要落成真实 JSX/CSS。
+7. 写完源码后逐条核对 `acceptanceChecks`，不通过就继续 patch。
 
-其他控件默认保留组件库样式，仅在实际受到宿主样式干扰时修正：需要局部浮层样式时，通过 `CanvasThemeProvider.getPopupContainer` 选择不会裁剪弹层的容器，`OPENYIDA_CANVAS_CONTROL_CSS` 统一输入框、下拉、日期、运行态字段组件的 hover / focus / dropdown 样式。控件焦点边框或下拉浮层不符合设计时，先检查主题与挂载位置，再按样式指南局部调整，保留可见的键盘焦点。
+控件默认保留组件库样式，仅在实际受到宿主样式干扰时修正：需要局部浮层样式时，通过 `CanvasThemeProvider.getPopupContainer` 选择不会裁剪弹层的容器，`OPENYIDA_CANVAS_CONTROL_CSS` 统一输入框、下拉、日期、运行态字段组件的 hover / focus / dropdown 样式。出现黑色粗边、浏览器原生 outline、下拉浮层脱离页面风格时，先检查主题与挂载位置，再按样式指南增加局部 reset。