openxiangda 1.0.152 → 1.0.154

package/templates/openxiangda-react-spa/.cursor/rules/openxiangda.mdc

@@ -26,6 +26,7 @@ This is an OpenXiangda React SPA workspace. See [AGENTS.md](mdc:AGENTS.md) for f
 - Roles that create roles, assign members, grant API permissions, maintain permission groups, or manage organization accounts must declare `apiPermissionCodes`, such as `app:role:manage`, `app:page-permission-group:manage`, `app:form-permission-group:manage`, and `app:organization:manage`.
 - `src/resources/**` is the resource source of truth; use `validate -> plan -> publish`.
 - React routes live in `src/app/router.tsx`; frontend artifacts are deployed with `openxiangda runtime deploy`.
+- Use `AttachmentField` / `ImageField` for form-context previews, and `AttachmentPreviewList` / `ImagePreviewGrid` / `useFilePreview` for standalone custom pages. Do not fake form context, import internal preview implementations, or maintain local previewable-extension lists.
 - Backend permissions, public-access grants, and App Function role/scope checks are authoritative.
 - Query parameters are context, filters, or ticket input only; they are not sensitive authorization.
 

package/templates/openxiangda-react-spa/.qoder/rules/openxiangda.md

@@ -26,6 +26,7 @@ This is an OpenXiangda React SPA workspace. Read [AGENTS.md](AGENTS.md) for full
 - 角色能新增角色、分配成员、授接口权限、维护权限组或管理组织账号时，角色资源必须声明 `apiPermissionCodes`，例如 `app:role:manage`、`app:page-permission-group:manage`、`app:form-permission-group:manage`、`app:organization:manage`。
 - `src/resources/**` 是工程化资源来源，正式多资源变更走 `validate -> plan -> publish`。
 - React SPA 路由由 `src/app/router.tsx` 管理，前端包通过 `openxiangda runtime deploy` 发布。
+- 表单附件预览使用 `AttachmentField` / `ImageField`；普通自定义页面使用 `AttachmentPreviewList` / `ImagePreviewGrid` / `useFilePreview`，不要伪造表单上下文、直接引用内部预览实现或维护扩展名白名单。
 - 页面权限、表单权限、公开访问 grants、App Function 后端检查是授权依据；前端只做展示保护。
 - 查询参数只能做上下文、筛选或 ticket 输入，不能作为敏感数据授权依据。
 

package/templates/openxiangda-react-spa/AGENTS.md

@@ -126,9 +126,11 @@ import { PermissionBoundary, useAppMenus, useRuntimeBootstrap } from "openxiangd
 
 附件预览约定：
 
-- 应用代码优先使用 `AttachmentField`，或通过 React SPA PageSdk（`usePageSdk()` 返回的 `sdk`）调用 `sdk.createFileAccessTicket(bucketName, objectName, fileName, "preview", { appType })` 获取 `previewPageUrl` 后打开。
+- 表单上下文使用 `AttachmentField` / `ImageField`；不要为只读业务数据伪造 `FormProvider`。普通自定义页面从 `openxiangda/runtime/react` 导入 `AttachmentPreviewList` / `ImagePreviewGrid`；自定义卡片、表格和详情操作使用 `useFilePreview({ items })`，并渲染返回的 `host`。
+- 上述独立组件和 hook 必须位于 `OpenXiangdaProvider` + `OpenXiangdaPageProvider` 内。它们自动使用当前 PageSdk `appType`，复用平台 capability、ticket metadata 和受控二进制下载。
+- 只有需要复制、分享或新窗口打开时，才通过 PageSdk（`usePageSdk()` 返回的 `sdk`）调用 `sdk.createFileAccessTicket(bucketName, objectName, fileName, "preview", { appType })` 获取 `previewPageUrl` 后打开。
 - `previewPageUrl` 是给用户打开的页面入口；`previewUrl` / `/service/file/preview-by-ticket/:ticket` 是文件内容流，只供预览页内部 iframe、PDF、图片或视频组件加载。
-- 不要自行维护“可预览扩展名”列表。`AttachmentField` 会调用平台 capability API，只在服务端确认 `canPreview: true` 时展示预览；图片使用同组弹窗画廊，视频、音频和文档使用站内弹窗。
+- 不要自行维护“可预览扩展名”列表，也不要直接引用内部 `FilePreviewContent` / `useFilePreviewController`。公开组件会调用平台 capability API，只在服务端确认 `canPreview: true` 时展示预览；图片使用同组弹窗画廊，视频、音频和文档使用站内弹窗。
 - 默认支持 PDF、常见图片/视频/音频、文本、DOCX 和 XLSX；DOC/XLS/PPT、ODF 等格式需要部署侧配置 ONLYOFFICE。文件过大时平台会按 `FILE_PREVIEW_*_MAX_*` 上限降级为仅下载。
 - 全局兼容入口 `/view/file-preview?ticket=...` 只有在后端能从 URL、ticket payload 或 `FILE_PREVIEW_APP_TYPE` 推导 appType 时才会被 React SPA runtime 接管。若响应头仍是 `X-OpenXiangda-Runtime-Mode: legacy`，检查 ticket 是否含 appType、URL 是否带 `appType`、runtime release 是否已激活、以及服务端兜底配置。
 - 需要自定义文件预览 UI 时，在 `src/runtime/default-page-overrides.tsx` 覆盖 `file-preview`；自定义组件仍应读取 ticket metadata 和 `/service/file/*` 接口，不要直接拼旧 view/workbench 参数。