openxiangda 1.0.148 → 1.0.149

package/openxiangda-skills/references/pages/page-sdk.md

@@ -16,6 +16,7 @@ Guidelines:
 - Use `sdk.function.invoke(code, { input })` for reusable backend business logic declared under `src/resources/functions/` and `src/functions/`. Do not implement multi-form orchestration, connector fan-out, notification orchestration, or permission-sensitive backend rules directly in a page component.
 - Use `sdk.connector.invoke`, `sdk.connector.call("connector.api")`, or `sdk.connector.download` for external services. The SDK calls the platform runtime connector endpoint; it must not call third-party domains directly.
 - Use `sdk.notification.sendByType` and `batchSendByType` for reusable business messages. Custom notification types must be declared in `src/resources/notifications/` and published with `openxiangda resource publish`.
+- Use `sdk.createFileAccessTicket(bucketName, objectName, fileName, "preview")` when a custom React SPA page needs a user-openable attachment preview link. Open `response.result.previewPageUrl`; do not use `previewUrl` or `/service/file/preview-by-ticket/:ticket` as the page entry.
 - Use `sdk.organization.departments.*` and `sdk.organization.accounts.*` only for admin-style app pages that intentionally manage platform departments/accounts. The current user needs `app:organization:manage` on the app. Do not call legacy `/user` or `/department` write endpoints from pages.
 - Use `sdk.workCenter.listItems({ boxType })` and `sdk.workCenter.getStats()` for current-user work center lists and counts. `boxType` is one of `todo`, `done`, `cc`, or `initiated`. This is the end-user task/handled/cc/initiated surface; do not build todo pages by reading workflow operation logs, automation logs, or raw process-task tables.
 - `sdk.form.create` returns identifiers and generated serial number values only. Treat `formInstId` / `formInstanceId` as the required success contract; `serialNumber` / `serialNumbers` are present only when the form has `SerialNumberField`. Do not expect the save response to contain the full row, formula results, or other server-generated field values. Call `sdk.form.getDetail` explicitly after create when those values are needed.
@@ -100,6 +101,24 @@ const response = await sdk.dataSource.run("tickets", {
 
 Data view filters, having, and fields use output aliases such as `customerName` or `ticketCount`, not source references such as `customer.name`. For option-like fields, prefer scalar aliases such as `statusValue` in the view definition and page filters. If the page only needs one form, prefer `sdk.form.advancedSearch`. If the page only needs a simple one-form dropdown, prefer linkedForm options.
 
+File preview ticket:
+
+```ts
+const ticketResponse = await sdk.createFileAccessTicket(
+  "lowcode",
+  "attachments/contracts/demo.docx",
+  "demo.docx",
+  "preview",
+)
+
+const previewPageUrl = ticketResponse.result?.previewPageUrl
+if (previewPageUrl) {
+  window.open(previewPageUrl, "_blank")
+}
+```
+
+`previewPageUrl` is the final browser page URL, normally `/view/:appType/file-preview?ticket=...`. `previewUrl` is the file content stream for the preview renderer and should not be used as the user-facing page entry.
+
 App Function invocation:
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openxiangda",
-  "version": "1.0.148",
+  "version": "1.0.149",
   "description": "OpenXiangda CLI, workspace build tools, runtime SDK, and form components.",
   "private": false,
   "bin": {

package/packages/sdk/dist/{ProcessPreview-BoblxCUt.d.mts → ProcessPreview-BOCARAvP.d.mts}

@@ -269,7 +269,15 @@ interface FormRuntimeApi {
         success: boolean;
     }>;
     createDownloadTicket: (bucketName: string, objectName: string, fileName?: string) => Promise<any>;
-    createFileAccessTicket: (bucketName: string, objectName: string, fileName?: string, purpose?: 'download' | 'preview' | 'onlyoffice') => Promise<any>;
+    /**
+     * Creates a protected file access ticket.
+     *
+     * previewPageUrl is the page URL that can be opened directly.
+     * previewUrl is the raw file content stream URL for iframe/img/PDF viewers.
+     */
+    createFileAccessTicket: (bucketName: string, objectName: string, fileName?: string, purpose?: 'download' | 'preview' | 'onlyoffice', options?: {
+        appType?: string;
+    }) => Promise<any>;
     getUserById: (id: string) => Promise<any>;
     getUserList: (params?: Record<string, any>) => Promise<any[]>;
     getDepartmentRoots: () => Promise<any[]>;

package/packages/sdk/dist/{ProcessPreview-BoblxCUt.d.ts → ProcessPreview-BOCARAvP.d.ts}

@@ -269,7 +269,15 @@ interface FormRuntimeApi {
         success: boolean;
     }>;
     createDownloadTicket: (bucketName: string, objectName: string, fileName?: string) => Promise<any>;
-    createFileAccessTicket: (bucketName: string, objectName: string, fileName?: string, purpose?: 'download' | 'preview' | 'onlyoffice') => Promise<any>;
+    /**
+     * Creates a protected file access ticket.
+     *
+     * previewPageUrl is the page URL that can be opened directly.
+     * previewUrl is the raw file content stream URL for iframe/img/PDF viewers.
+     */
+    createFileAccessTicket: (bucketName: string, objectName: string, fileName?: string, purpose?: 'download' | 'preview' | 'onlyoffice', options?: {
+        appType?: string;
+    }) => Promise<any>;
     getUserById: (id: string) => Promise<any>;
     getUserList: (params?: Record<string, any>) => Promise<any[]>;
     getDepartmentRoots: () => Promise<any[]>;

package/packages/sdk/dist/components/index.cjs

@@ -3317,6 +3317,11 @@ function canPreview(item) {
   const ext = getFileExtension(item.name);
   return isImageFile(item.name, item.contentType) || ["mp4", "webm", "ogg", "mov", "m4v"].includes(ext) || PREVIEW_PAGE_EXTENSIONS.includes(ext);
 }
+function appendTicketIfMissing(url, ticket) {
+  if (!url || !ticket || /[?&]ticket=/.test(url)) return url;
+  const separator = url.includes("?") ? "&" : "?";
+  return `${url}${separator}ticket=${encodeURIComponent(ticket)}`;
+}
 function AttachmentFieldPC({
   fieldId,
   behavior,
@@ -3432,16 +3437,15 @@ function AttachmentFieldPC({
         item.bucketName || bucketName,
         item.objectName,
         item.name,
-        "preview"
+        "preview",
+        { appType: item.appType || config.appType }
       );
       const ticketValue = typeof ticket === "string" ? { previewUrl: ticket } : ticket;
-      if (ticketValue?.previewPageUrl && ticketValue?.ticket) {
-        const separator = ticketValue.previewPageUrl.includes("?") ? "&" : "?";
-        return `${ticketValue.previewPageUrl}${separator}ticket=${encodeURIComponent(ticketValue.ticket)}`;
+      if (ticketValue?.previewPageUrl) {
+        return appendTicketIfMissing(ticketValue.previewPageUrl, ticketValue.ticket);
       }
       if (ticketValue?.ticket && PREVIEW_PAGE_EXTENSIONS.includes(getFileExtension(item.name))) {
-        const separator = previewPagePath.includes("?") ? "&" : "?";
-        return `${previewPagePath}${separator}ticket=${encodeURIComponent(ticketValue.ticket)}`;
+        return appendTicketIfMissing(previewPagePath, ticketValue.ticket);
       }
       return ticketValue?.previewUrl || ticketValue?.url || "";
     }
@@ -3683,6 +3687,11 @@ function canPreview2(item) {
   const ext = getFileExtension(item.name);
   return isImageFile(item.name, item.contentType) || ["mp4", "webm", "ogg", "mov", "m4v"].includes(ext) || PREVIEW_PAGE_EXTENSIONS2.includes(ext);
 }
+function appendTicketIfMissing2(url, ticket) {
+  if (!url || !ticket || /[?&]ticket=/.test(url)) return url;
+  const separator = url.includes("?") ? "&" : "?";
+  return `${url}${separator}ticket=${encodeURIComponent(ticket)}`;
+}
 function AttachmentFieldMobile({
   fieldId,
   behavior,
@@ -3831,16 +3840,15 @@ function AttachmentFieldMobile({
         item.bucketName || bucketName,
         item.objectName,
         item.name,
-        "preview"
+        "preview",
+        { appType: item.appType || config.appType }
       );
       const ticketValue = typeof ticket === "string" ? { previewUrl: ticket } : ticket;
-      if (ticketValue?.previewPageUrl && ticketValue?.ticket) {
-        const separator = ticketValue.previewPageUrl.includes("?") ? "&" : "?";
-        return `${ticketValue.previewPageUrl}${separator}ticket=${encodeURIComponent(ticketValue.ticket)}`;
+      if (ticketValue?.previewPageUrl) {
+        return appendTicketIfMissing2(ticketValue.previewPageUrl, ticketValue.ticket);
       }
       if (ticketValue?.ticket && PREVIEW_PAGE_EXTENSIONS2.includes(getFileExtension(item.name))) {
-        const separator = previewPagePath.includes("?") ? "&" : "?";
-        return `${previewPagePath}${separator}ticket=${encodeURIComponent(ticketValue.ticket)}`;
+        return appendTicketIfMissing2(previewPagePath, ticketValue.ticket);
       }
       return ticketValue?.previewUrl || ticketValue?.url || "";
     }
@@ -3971,6 +3979,11 @@ function canPreview3(item) {
   const ext = getFileExtension(item.name);
   return isImageFile(item.name, item.contentType) || ["mp4", "webm", "ogg", "mov", "m4v"].includes(ext) || PREVIEW_PAGE_EXTENSIONS3.includes(ext);
 }
+function appendTicketIfMissing3(url, ticket) {
+  if (!url || !ticket || /[?&]ticket=/.test(url)) return url;
+  const separator = url.includes("?") ? "&" : "?";
+  return `${url}${separator}ticket=${encodeURIComponent(ticket)}`;
+}
 function AttachmentFieldReadonly({
   fieldId,
   readonlyClassName,
@@ -3981,7 +3994,7 @@ function AttachmentFieldReadonly({
   showFileTypeBadge = false,
   previewPagePath = "/file-preview"
 }) {
-  const { formData, api } = useFormContext();
+  const { formData, api, config } = useFormContext();
   const { isMobile } = useDeviceDetect();
   const value = formData[fieldId] ?? [];
   if (value.length === 0) {
@@ -4006,15 +4019,14 @@ function AttachmentFieldReadonly({
         item.bucketName || bucketName,
         item.objectName,
         item.name,
-        "preview"
+        "preview",
+        { appType: item.appType || config.appType }
       );
       const ticketValue = typeof ticket === "string" ? { previewUrl: ticket } : ticket;
-      if (ticketValue?.previewPageUrl && ticketValue?.ticket) {
-        const separator = ticketValue.previewPageUrl.includes("?") ? "&" : "?";
-        url = `${ticketValue.previewPageUrl}${separator}ticket=${encodeURIComponent(ticketValue.ticket)}`;
+      if (ticketValue?.previewPageUrl) {
+        url = appendTicketIfMissing3(ticketValue.previewPageUrl, ticketValue.ticket);
       } else if (ticketValue?.ticket && PREVIEW_PAGE_EXTENSIONS3.includes(getFileExtension(item.name))) {
-        const separator = previewPagePath.includes("?") ? "&" : "?";
-        url = `${previewPagePath}${separator}ticket=${encodeURIComponent(ticketValue.ticket)}`;
+        url = appendTicketIfMissing3(previewPagePath, ticketValue.ticket);
       } else {
         url = getTicketUrl(ticketValue, url);
       }
@@ -10817,11 +10829,11 @@ function createFormRuntimeApi(config) {
       });
       return normalizeFileTicketResult(baseUrl, response.data || response.result);
     },
-    createFileAccessTicket: async (bucketName, objectName, fileName, purpose = "preview") => {
+    createFileAccessTicket: async (bucketName, objectName, fileName, purpose = "preview", options = {}) => {
       const response = await request({
         url: "/file/access-ticket",
         method: "post",
-        data: { bucketName, objectName, fileName, purpose }
+        data: { bucketName, objectName, fileName, purpose, appType: options.appType }
       });
       return normalizeFileTicketResult(baseUrl, response.data || response.result);
     },