openxiangda 1.0.90 → 1.0.92

package/README.md

@@ -205,16 +205,26 @@ import {
   PublicAccessGate,
 } from "openxiangda/runtime/react"
 
+const PublicLoading = () => <div role="status">正在进入公开页面</div>
+const PublicAccessError = ({ error }: { error: { message?: string } }) => (
+  <div role="alert">{error.message || "公开链接不可用或已过期"}</div>
+)
+
 <OpenXiangdaProvider appType={appType} servicePrefix="/service">
   <OpenXiangdaPageProvider>
-    <PublicAccessGate policyCode="public_register" routeCode="public.register">
+    <PublicAccessGate
+      errorFallback={error => <PublicAccessError error={error} />}
+      fallback={<PublicLoading />}
+      policyCode="public_register"
+      routeCode="public.register"
+    >
       <PublicRegisterPage />
     </PublicAccessGate>
   </OpenXiangdaPageProvider>
 </OpenXiangdaProvider>
 ```
 
-不要把 `PublicAccessGate` 单独放在没有 `OpenXiangdaProvider` / `OpenXiangdaPageProvider` 的页面树下；否则 public session 不能注入后续 SDK 请求，`usePageSdk()` 也会抛出 `usePageSdkStore 必须在 PageProvider 内使用`。
+不要把 `PublicAccessGate` 单独放在没有 `OpenXiangdaProvider` / `OpenXiangdaPageProvider` 的页面树下；否则 public session 不能注入后续 SDK 请求，`usePageSdk()` 也会抛出 `usePageSdkStore 必须在 PageProvider 内使用`。公开页面必须给 `PublicAccessGate` 配 `fallback` 和 `errorFallback`，避免慢网、缺 ticket、ticket 过期时出现空白页。
 
 多表只读查询和固定口径统计优先声明 `src/resources/data-views/*.json` 数据视图，而不是在页面里手写多次单表查询再拼数据。默认 `storageMode: "materialized"` 会创建 PostgreSQL materialized view，适合读多写少和可接受刷新延迟的列表/报表；`storageMode: "live"` 每次查询实时编译逻辑视图，适合强实时但数据量可控的复杂查询。`viewType: "aggregate"` 是统计聚合视图，适合按客户、状态、月份等维度聚合 count/sum/avg/min/max。发布时 CLI 会把 `formCode` 解析为当前 profile 的 `formUuid`；页面通过 `sdk.dataView.query(code, params)` 查询行级视图，通过 `sdk.dataView.stats(code, params)` 查询聚合视图，也可以用 `sdk.dataSource.run()` 路由 `dataView.query` / `dataView.stats`。materialized 模式应为常用筛选、排序、统计维度和时间桶声明 `indexes`，并确认用户能接受的刷新延迟；live 模式忽略 `indexes`，不需要刷新。
 

package/lib/cli.js

@@ -24,6 +24,7 @@ const { assertCanInitializeWorkspace, initWorkspace } = require('./workspace-ini
 const { bootstrapWorkspace } = require('./workspace-bootstrap');
 const {
   fail,
+  formatFetchError,
   maskText,
   openBrowser,
   parseArgs,
@@ -7972,7 +7973,7 @@ async function requestForm(baseUrl, apiPath, formData, accessToken, options = {}
     if (isAbortError(error)) {
       throw new Error(maskText(`HTTP form request timed out after ${timeoutMs}ms: ${apiPath}`));
     }
-    throw error;
+    throw new Error(formatFetchError(error, apiPath));
   } finally {
     clearTimeout(timer);
   }

package/lib/http.js

@@ -1,4 +1,4 @@
-const { maskText } = require('./utils');
+const { formatFetchError, maskText } = require('./utils');
 
 const DEFAULT_REQUEST_TIMEOUT_MS = 60000;
 
@@ -35,7 +35,7 @@ async function requestJson(baseUrl, apiPath, options = {}) {
     if (isAbortError(error)) {
       throw new Error(maskText(`HTTP request timed out after ${timeoutMs}ms: ${apiPath}`));
     }
-    throw error;
+    throw new Error(formatFetchError(error, apiPath));
   } finally {
     clearTimeout(timer);
   }

package/lib/utils.js

@@ -11,6 +11,18 @@ function maskText(value) {
     .replace(/\b1[3-9]\d{9}\b/g, match => `${match.slice(0, 3)}****${match.slice(-4)}`);
 }
 
+function formatFetchError(error, context) {
+  const message = error && error.message ? String(error.message) : String(error || 'fetch failed');
+  const cause = error && error.cause;
+  const causeParts = [];
+  if (cause?.code) causeParts.push(String(cause.code));
+  if (cause?.name) causeParts.push(String(cause.name));
+  if (cause?.message) causeParts.push(String(cause.message));
+  const suffix = causeParts.length ? `; cause=${causeParts.join(': ')}` : '';
+  const contextSuffix = context ? `; request=${context}` : '';
+  return maskText(`${message}${suffix}${contextSuffix}`);
+}
+
 function print(value) {
   console.log(maskText(value));
 }
@@ -81,6 +93,7 @@ function writeJson(value) {
 
 module.exports = {
   fail,
+  formatFetchError,
   maskText,
   openBrowser,
   parseArgs,

package/openxiangda-skills/SKILL.md

@@ -45,7 +45,7 @@ OpenXiangda supports two workspace modes. Classic `sy-lowcode-app-workspace` pub
 - ✅ Run `openxiangda update check --json` at the start of substantial work; if `updateAvailable`, run `openxiangda update install` and `openxiangda skill install --force`.
 - ✅ For non-trivial app requirements, run the architecture design gate first: forms, fields, pages, permissions, data views, status/workflow, automation, notifications, and development tasks must be decided before coding.
 - ✅ For app login/auth requirements, run the auth security gate before coding: enabled methods, registration policy, identity matching keys, provider boundary, default roles, rate limits, audit fields, and third-party ownership must be confirmed.
-- ✅ For public/no-login access requirements, run the public access design gate before coding: public routes, external role codes, guest vs ticket, form/dataView/function/connector grants, and backend permission groups must be confirmed. New React SPA apps use `/view/:appType/public/*`, `src/resources/routes/`, `src/resources/public-access/`, and `PublicAccessGate`; route children that use Page SDK hooks must be inside `OpenXiangdaProvider` + `OpenXiangdaPageProvider`.
+- ✅ For public/no-login access requirements, run the public access design gate before coding: public routes, external role codes, guest vs ticket, form/dataView/function/connector grants, backend permission groups, and visible loading/error fallback states must be confirmed. New React SPA apps use `/view/:appType/public/*`, `src/resources/routes/`, `src/resources/public-access/`, and `PublicAccessGate`; route children that use Page SDK hooks must be inside `OpenXiangdaProvider` + `OpenXiangdaPageProvider`.
 - ✅ Public/no-login validation must inspect the JSON envelope, not only HTTP status. HTTP 200 with `code: "PUBLIC_GRANT_DENIED"` is a denied request; success requires `code` `200`, `"200"`, or compatible `0`, and no `success: false`.
 - ✅ For form-entry UX, pick components in this order: OpenXiangda platform form components → `antd` / `antd-mobile` wrappers → custom component only when neither exists.
 - ✅ List pages, linked options, remote selectors, and report drill-downs must use paginated server-side queries with explicit searchable fields. Do not fetch a large page and filter in local state.
@@ -149,7 +149,7 @@ When the user provides a root domain such as `https://yida.wisejob.cn/`, use it
 - For external APIs, create a connector manifest in `src/resources/connectors/` and call it from pages through `sdk.connector`; never put third-party API keys in page source.
 - For reusable backend logic shared by pages, automations, and workflows, create an App Function in `src/resources/functions/<functionCode>.json` plus `src/functions/<functionCode>/index.ts`. Call it from pages with `sdk.function.invoke`, from automation/workflow graphs with `function_call`, or from the runtime endpoint when the caller has app automation management permission. Current App Function MVP exposes controlled helpers such as `ctx.resources`, `ctx.form`, `ctx.dataView`, `ctx.connector`, `ctx.notification`, and `ctx.platform.api`; it does not expose raw SQL or Redis.
 - For application login, declare auth resources in `src/resources/auth/<code>.json` and publish them with `openxiangda resource publish`. App Function auth providers may validate external credentials and return only an identity assertion; they must never issue tokens, set cookies, or write platform user/binding tables directly. The platform auth service decides create/bind/reject and issues tokens.
-- For external/no-login pages in React SPA apps, declare `src/resources/routes/<code>.json` and `src/resources/public-access/<code>.json`, put the page under `/view/:appType/public/*`, and use `PublicAccessGate` or `createPublicAccessClient`. The route tree must also include `OpenXiangdaPageProvider` inside `OpenXiangdaProvider` before any `usePageSdk()` / `usePageContext()` / `useDataSource()` call; otherwise pages throw `usePageSdkStore 必须在 PageProvider 内使用`. Public guest access to forms, dataViews, functions, and connectors is denied unless policy `grants` explicitly names the resource; backend permission groups still apply.
+- For external/no-login pages in React SPA apps, declare `src/resources/routes/<code>.json` and `src/resources/public-access/<code>.json`, put the page under `/view/:appType/public/*`, and use `PublicAccessGate` or `createPublicAccessClient`. The route tree must also include `OpenXiangdaPageProvider` inside `OpenXiangdaProvider` before any `usePageSdk()` / `usePageContext()` / `useDataSource()` call; otherwise pages throw `usePageSdkStore 必须在 PageProvider 内使用`. Always provide `fallback` and `errorFallback` for public routes so slow networks, missing tickets, or expired tickets do not render blank pages. Public guest access to forms, dataViews, functions, and connectors is denied unless policy `grants` explicitly names the resource; backend permission groups still apply.
 - When verifying public access, parse the response body and reject string business errors such as `PUBLIC_GRANT_DENIED` even if the HTTP status is 200. Do not use `response.ok` alone as the success condition.
 - Before scaffolding a real app, complex page, data management page, portal shell, status lifecycle, role governance, or automation, read `references/best-practices.md` and pick the architecture first. Prefer copying the relevant pattern from `examples/best-practices/` into `src/` instead of generating a single large page file.
 - Before publishing to another platform, verify the workspace is bound for that profile. Resource IDs from one profile must not be reused for another profile.

package/openxiangda-skills/references/architecture-design.md

@@ -264,7 +264,7 @@ For simple CRUD/admin lists, design can proceed with the appropriate OpenXiangda
 - Public policies live under `src/resources/public-access/`.
 - Policy `externalRoleCodes` are virtual role codes carried by the scoped public token; use the same codes in page/form/dataView permission groups.
 - Policy `grants` must list every form/dataView/function/connector the public page can access. Do not rely on broad guest permissions.
-- Use `PublicAccessGate` in React routes or `createPublicAccessClient` for custom bootstrapping. If the page uses Page SDK hooks, the route tree must have `OpenXiangdaProvider` plus `OpenXiangdaPageProvider`; `PublicAccessGate` alone is not enough.
+- Use `PublicAccessGate` in React routes or `createPublicAccessClient` for custom bootstrapping. If the page uses Page SDK hooks, the route tree must have `OpenXiangdaProvider` plus `OpenXiangdaPageProvider`; `PublicAccessGate` alone is not enough. Public routes must define visible loading and error fallback states so slow networks, missing tickets, or expired tickets do not become blank pages.
 - In validation scripts, success requires the JSON envelope success code (`200`, `"200"`, or compatible `0`). HTTP 200 with `code: "PUBLIC_GRANT_DENIED"` is a denied request, not a success.
 - Validation must include at least one real browser render check for each public and private route, because API-only E2E can miss provider/runtime crashes such as `usePageSdkStore 必须在 PageProvider 内使用`.
 - Old `?publicAccess=guest` and form `publicAccess` settings are legacy compatibility and should not appear in new-app designs.

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

@@ -152,11 +152,18 @@ import {
   PublicAccessGate,
 } from "openxiangda/runtime/react";
 
+const PublicLoading = () => <div role="status">正在进入公开页面</div>;
+const PublicAccessError = ({ error }: { error: { message?: string } }) => (
+  <div role="alert">{error.message || "公开链接不可用或已过期"}</div>
+);
+
 export function PublicRegisterRoute() {
   return (
     <OpenXiangdaProvider appType={appType} servicePrefix="/service">
       <OpenXiangdaPageProvider>
         <PublicAccessGate
+          errorFallback={error => <PublicAccessError error={error} />}
+          fallback={<PublicLoading />}
           policyCode="public_register"
           routeCode="public.register"
         >
@@ -183,7 +190,7 @@ await publicAccess.startSession({
 });
 ```
 
-`PublicAccessGate` stores the returned bearer token in the runtime provider and injects it into follow-up SDK requests. It does not replace `OpenXiangdaPageProvider`. If you call `createPublicAccessClient` directly outside the provider, pass the returned `accessToken` as `Authorization: Bearer <token>` for follow-up APIs. The matching resources must exist under `src/resources/routes/` and `src/resources/public-access/`. Public guest access to forms, data views, functions, and connectors is denied unless the policy `grants` explicitly names that resource.
+`PublicAccessGate` stores the returned bearer token in the runtime provider and injects it into follow-up SDK requests. It does not replace `OpenXiangdaPageProvider`. Always provide `fallback` and `errorFallback` so slow networks, missing tickets, or expired tickets do not render a blank public page. If you call `createPublicAccessClient` directly outside the provider, pass the returned `accessToken` as `Authorization: Bearer <token>` for follow-up APIs. The matching resources must exist under `src/resources/routes/` and `src/resources/public-access/`. Public guest access to forms, data views, functions, and connectors is denied unless the policy `grants` explicitly names that resource.
 
 When testing public pages or writing direct fetch wrappers, check the JSON envelope, not only `response.ok`. Platform runtime APIs can return HTTP 200 with `code: "PUBLIC_GRANT_DENIED"`; this is a failed request. Treat only `code === 200`, `code === "200"`, or compatible success code `0` as success, and fail on `success: false`.
 

package/openxiangda-skills/references/resource-manifest-cheatsheet.md

@@ -125,16 +125,26 @@ import {
   PublicAccessGate,
 } from "openxiangda/runtime/react";
 
+const PublicLoading = () => <div role="status">正在进入公开页面</div>;
+const PublicAccessError = ({ error }: { error: { message?: string } }) => (
+  <div role="alert">{error.message || "公开链接不可用或已过期"}</div>
+);
+
 <OpenXiangdaProvider appType={appType} servicePrefix="/service">
   <OpenXiangdaPageProvider>
-    <PublicAccessGate policyCode="public_register" routeCode="public.register">
+    <PublicAccessGate
+      errorFallback={error => <PublicAccessError error={error} />}
+      fallback={<PublicLoading />}
+      policyCode="public_register"
+      routeCode="public.register"
+    >
       <PublicRegisterPage />
     </PublicAccessGate>
   </OpenXiangdaPageProvider>
 </OpenXiangdaProvider>
 ```
 
-React SPA 中 `OpenXiangdaProvider` 负责 runtime/bootstrap 和 public token 注入，`OpenXiangdaPageProvider` 负责 `usePageSdk()` / `usePageContext()` 的 Page SDK 上下文。缺少 `OpenXiangdaPageProvider` 会抛出 `usePageSdkStore 必须在 PageProvider 内使用`。
+React SPA 中 `OpenXiangdaProvider` 负责 runtime/bootstrap 和 public token 注入，`OpenXiangdaPageProvider` 负责 `usePageSdk()` / `usePageContext()` 的 Page SDK 上下文。缺少 `OpenXiangdaPageProvider` 会抛出 `usePageSdkStore 必须在 PageProvider 内使用`。公开页面必须给 `PublicAccessGate` 配 `fallback` 和 `errorFallback`，避免慢网、缺 ticket、ticket 过期时出现空白页。
 
 公开访问验证必须检查 JSON envelope。HTTP 200 但 `code: "PUBLIC_GRANT_DENIED"` 代表后端已拒绝；只有 `code` 为 `200`、`"200"` 或兼容成功码 `0`，且没有 `success: false` 时才算成功。
 

package/package.json

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

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

@@ -4519,9 +4519,12 @@ var OpenXiangdaProvider = ({
     [appType]
   );
   const [accessToken, setAccessTokenState] = (0, import_react8.useState)(null);
+  const accessTokenRef = (0, import_react8.useRef)(null);
   const setAccessToken = (0, import_react8.useCallback)(
     (nextAccessToken) => {
-      setAccessTokenState(nextAccessToken || null);
+      const normalizedAccessToken = nextAccessToken || null;
+      accessTokenRef.current = normalizedAccessToken;
+      setAccessTokenState(normalizedAccessToken);
     },
     []
   );
@@ -4547,7 +4550,7 @@ var OpenXiangdaProvider = ({
       return;
     }
     setState((prev) => ({ ...prev, loading: true, error: null }));
-    const requestFetch = options.accessToken !== void 0 ? createAuthorizedFetch(resolvedFetch, options.accessToken || null) : authorizedFetch;
+    const requestFetch = options.accessToken !== void 0 ? createAuthorizedFetch(resolvedFetch, options.accessToken || null) : createAuthorizedFetch(resolvedFetch, accessTokenRef.current);
     try {
       const response = await requestFetch(
         buildServiceUrl3(
@@ -4581,7 +4584,7 @@ var OpenXiangdaProvider = ({
         error: normalizeRuntimeError(error)
       });
     }
-  }, [authorizedFetch, resolvedAppType, resolvedFetch, servicePrefix]);
+  }, [resolvedAppType, resolvedFetch, servicePrefix]);
   (0, import_react8.useEffect)(() => {
     void reload();
   }, [reload]);
@@ -4591,10 +4594,11 @@ var OpenXiangdaProvider = ({
       appType: resolvedAppType,
       servicePrefix,
       fetchImpl: authorizedFetch,
+      baseFetchImpl: resolvedFetch,
       reload,
       setAccessToken
     }),
-    [authorizedFetch, reload, resolvedAppType, servicePrefix, state]
+    [authorizedFetch, reload, resolvedAppType, resolvedFetch, servicePrefix, state]
   );
   return /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(OpenXiangdaRuntimeContext.Provider, { value, children });
 };
@@ -5142,14 +5146,14 @@ var usePublicAccess = (options = {}) => {
   const {
     appType: runtimeAppType,
     servicePrefix: runtimeServicePrefix,
-    fetchImpl: runtimeFetchImpl,
+    baseFetchImpl: runtimeBaseFetchImpl,
     reload: reloadRuntime,
     setAccessToken
   } = runtime;
   const {
     appType = runtimeAppType,
     servicePrefix = runtimeServicePrefix,
-    fetchImpl = runtimeFetchImpl,
+    fetchImpl = runtimeBaseFetchImpl,
     autoStart = true,
     ...sessionInput
   } = options;