openxiangda 1.0.86 → 1.0.88

package/README.md

@@ -174,6 +174,36 @@ const affiliatedDepartmentExternalId = user?.affiliatedDepartment?.externalId
 
 工程化资源放在工作区 `src/resources/` 下，由 `openxiangda resource validate|plan|publish|pull` 管理。`workspace publish` 会先构建并注册 workspace 表单/页面，再执行非破坏性资源 upsert，这样菜单、权限组、流程和表单设置可以解析最新的 profile-local ID。需要删除平台中 manifest 未声明的资源时，显式传 `--prune`。连接器页面运行时通过 `sdk.connector.invoke()` / `sdk.connector.call("connector.api")` 调用平台运行时接口，第三方密钥只保存在后端连接器配置中。
 
+React SPA 新应用的无需登录访问统一使用 `/view/:appType/public/*`。应用在 `src/resources/routes/*.json` 声明公开路由，在 `src/resources/public-access/*.json` 声明公开策略、外部角色和可访问资源 grant，页面用 `PublicAccessGate` 或 `createPublicAccessClient` 创建 scoped public session。公开 guest 的 form、dataView、function、connector 默认全部拒绝，只有 policy `grants` 明确列出的资源可访问，并且仍受对应表单权限组、dataView 权限组等后端权限控制。
+
+`mode: "ticket"` 的公开策略默认按单次 ticket 使用；只有明确配置 `ticketConfig.singleUse: false` 时才允许复用。新 public session 只返回 bearer token，SDK 会把 token 注入后续 runtime/bootstrap、dataView、function、connector 请求，不依赖认证 cookie。
+
+旧 `?publicAccess=guest` 和表单 `settings/forms/*.json` 里的 `publicAccess` 只用于旧 `sy-lowcode-view` 兼容。新 React SPA 应用不要再设计或生成这种链接。
+
+```json
+{
+  "code": "public_register",
+  "mode": "guest",
+  "routeCode": "public.register",
+  "pathPattern": "/view/:appType/public/register",
+  "externalRoleCodes": ["external_visitor"],
+  "grants": {
+    "forms": ["registration_form"],
+    "dataViews": ["public_registration_lookup"],
+    "functions": ["submit_public_registration"],
+    "connectors": ["sms.sendCode"]
+  }
+}
+```
+
+```tsx
+import { PublicAccessGate } from "openxiangda/runtime/react"
+
+<PublicAccessGate policyCode="public_register" routeCode="public.register">
+  <PublicRegisterPage />
+</PublicAccessGate>
+```
+
 多表只读查询和固定口径统计优先声明 `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`，不需要刷新。
 
 后端业务逻辑优先声明为 App Function：源码放在 `src/functions/<functionCode>/index.ts`，资源 manifest 放在 `src/resources/functions/<functionCode>.json`。函数运行在 trusted_node 中，通过 `ctx.form`、`ctx.dataView`、`ctx.connector`、`ctx.notification`、`ctx.platform.api` 等受控 API 访问平台能力；自动化、流程和运行时接口都可以调用同一个 function。JS_CODE V2 仍兼容，但新逻辑建议写成 function，再由 `function_call` 节点、`sdk.function.invoke(code, { input })` 或 `/:appType/v1/functions/:code/invoke.json` 调用。当前 MVP 中直接运行时接口要求调用者具备应用自动化管理权限，自动化/流程内部调用走服务端受控上下文。

package/lib/cli.js

@@ -3376,6 +3376,8 @@ function ensureResourceBuckets(bound) {
   bound.resources.connectors = bound.resources.connectors || {};
   bound.resources.dataViews = bound.resources.dataViews || {};
   bound.resources.authConfigs = bound.resources.authConfigs || {};
+  bound.resources.routes = bound.resources.routes || {};
+  bound.resources.publicAccessPolicies = bound.resources.publicAccessPolicies || {};
   bound.resources.notifications = bound.resources.notifications || {};
   bound.resources.notifications.templates = bound.resources.notifications.templates || {};
   bound.resources.notifications.typeConfigs = bound.resources.notifications.typeConfigs || {};
@@ -3586,6 +3588,22 @@ function saveDataViewResource(target, dataViewCode, dataViewId, extra = {}) {
   }, keys);
 }
 
+function saveRouteResource(target, routeCode, routeId, extra = {}) {
+  const keys = ['routeId', 'pathPattern', 'publicAccess', 'publicPolicyCode'];
+  saveStateResource(target, 'routes', routeCode, {
+    ...pickStateFields(extra, keys),
+    routeId,
+  }, keys);
+}
+
+function savePublicAccessPolicyResource(target, policyCode, policyId, extra = {}) {
+  const keys = ['policyId', 'mode', 'routeCode', 'pathPattern'];
+  saveStateResource(target, 'publicAccessPolicies', policyCode, {
+    ...pickStateFields(extra, keys),
+    policyId,
+  }, keys);
+}
+
 function saveAuthConfigResource(target, authConfigCode, configId, extra = {}) {
   const keys = ['configId', 'status'];
   saveStateResource(target, 'authConfigs', authConfigCode, {
@@ -3702,6 +3720,13 @@ const RESOURCE_SPECS = [
   { key: 'functions', dir: 'functions', topFiles: ['functions.json'], pluralKeys: ['functions'] },
   { key: 'dataViews', dir: 'data-views', topFiles: ['data-views.json'], pluralKeys: ['dataViews', 'data-views'] },
   { key: 'authConfigs', dir: 'auth', topFiles: ['auth.json'], pluralKeys: ['authConfigs', 'auth'] },
+  { key: 'routes', dir: 'routes', topFiles: ['routes.json'], pluralKeys: ['routes'] },
+  {
+    key: 'publicAccessPolicies',
+    dir: 'public-access',
+    topFiles: ['public-access.json'],
+    pluralKeys: ['publicAccessPolicies', 'publicAccess', 'policies'],
+  },
   {
     key: 'pagePermissionGroups',
     dir: path.join('permissions', 'page-groups'),
@@ -3883,6 +3908,12 @@ function generateResourceTypes(manifest, outputFile) {
     routeCode: item.routeCode || null,
     path: item.path || null,
   }));
+  const routes = (manifest.routes || []).map(item => ({
+    code: item.code,
+    pathPattern: item.pathPattern || item.path || null,
+    publicAccess: item.publicAccess || 'none',
+    publicPolicyCode: item.publicPolicyCode || item.policyCode || null,
+  }));
   const pagePermissionGroups = (manifest.pagePermissionGroups || []).map(item => ({
     code: item.code,
     menuCodes: normalizePermissionCodeArray(item.menuCodes),
@@ -3892,6 +3923,7 @@ function generateResourceTypes(manifest, outputFile) {
   const routeCodes = unique(
     [
       ...menus.map(item => item.routeCode),
+      ...routes.map(item => item.code),
       ...pagePermissionGroups.flatMap(item => item.routeCodes),
     ].filter(Boolean)
   );
@@ -3902,6 +3934,7 @@ function generateResourceTypes(manifest, outputFile) {
   const dataViewCodes = unique((manifest.dataViews || []).map(item => item.code).filter(Boolean));
   const functionCodes = unique((manifest.functions || []).map(item => item.code).filter(Boolean));
   const authConfigCodes = unique((manifest.authConfigs || []).map(item => item.code).filter(Boolean));
+  const publicAccessPolicyCodes = unique((manifest.publicAccessPolicies || []).map(item => item.code).filter(Boolean));
   const content = [
     '/* eslint-disable */',
     '// Generated by openxiangda resource typegen. Do not edit manually.',
@@ -3924,8 +3957,13 @@ function generateResourceTypes(manifest, outputFile) {
     `export const authConfigCodes = ${JSON.stringify(authConfigCodes, null, 2)} as const`,
     'export type AuthConfigCode = typeof authConfigCodes[number]',
     '',
+    `export const publicAccessPolicyCodes = ${JSON.stringify(publicAccessPolicyCodes, null, 2)} as const`,
+    'export type PublicAccessPolicyCode = typeof publicAccessPolicyCodes[number]',
+    '',
     `export const runtimeMenus = ${JSON.stringify(menus, null, 2)} as const`,
     '',
+    `export const runtimeRoutes = ${JSON.stringify(routes, null, 2)} as const`,
+    '',
     `export const pagePermissionGroups = ${JSON.stringify(pagePermissionGroups, null, 2)} as const`,
     '',
   ].join('\n');
@@ -3939,6 +3977,7 @@ function generateResourceTypes(manifest, outputFile) {
     dataViews: dataViewCodes.length,
     functions: functionCodes.length,
     authConfigs: authConfigCodes.length,
+    publicAccessPolicies: publicAccessPolicyCodes.length,
   };
 }
 
@@ -4043,6 +4082,29 @@ function validateResourceItem(kind, item, errors, warnings) {
       warnings.push(`${label}: 已开启非默认注册策略 ${registrationMode}，请确认身份匹配键、默认角色和审计字段`);
     }
   }
+  if (kind === 'routes') {
+    if (!item.pathPattern && !item.path) errors.push(`${label}: 缺少 pathPattern`);
+    const mode = item.publicAccess === undefined ? 'none' : String(item.publicAccess);
+    if (!['none', 'guest', 'ticket'].includes(mode)) {
+      errors.push(`${label}: publicAccess 只能是 none、guest 或 ticket`);
+    }
+  }
+  if (kind === 'publicAccessPolicies') {
+    if (!item.name) warnings.push(`${label}: 未声明 name，将使用 code`);
+    const mode = item.mode === undefined ? 'guest' : String(item.mode);
+    if (!['guest', 'ticket'].includes(mode)) {
+      errors.push(`${label}: mode 只能是 guest 或 ticket`);
+    }
+    if (!item.routeCode && !item.pathPattern && !item.path) {
+      warnings.push(`${label}: 未声明 routeCode/pathPattern，建议绑定到 /view/:appType/public/* 路由`);
+    }
+    if (!item.grants || typeof item.grants !== 'object' || Array.isArray(item.grants)) {
+      errors.push(`${label}: 缺少 grants object；未显式 grant 的 form/dataView/function/connector 默认拒绝`);
+    }
+    if (!Array.isArray(item.externalRoleCodes || item.externalRoles || item.roles || [])) {
+      errors.push(`${label}: externalRoleCodes 必须是数组`);
+    }
+  }
   if (kind === 'pagePermissionGroups' && !item.name) errors.push(`${label}: 缺少 name`);
   if (kind === 'formPermissionGroups') {
     if (!item.name) errors.push(`${label}: 缺少 name`);
@@ -4445,6 +4507,8 @@ async function buildResourcePlan(config, target, manifest) {
   await addWorkflowPlanActions(config, target, actions, manifest.workflows, existing.workflows);
   addPlanActions(actions, 'function', manifest.functions, existing.functions, (item, current) => functionEquals(target, item, current));
   addPlanActions(actions, 'authConfig', manifest.authConfigs, existing.authConfigs, (item, current) => authConfigEquals(item, current));
+  addPlanActions(actions, 'route', manifest.routes, existing.routes, (item, current) => routeEquals(item, current));
+  addPlanActions(actions, 'publicAccessPolicy', manifest.publicAccessPolicies, existing.publicAccessPolicies, (item, current) => publicAccessPolicyEquals(target.bound, item, current));
   await addAutomationPlanActions(config, target, actions, manifest.automations, existing.automations);
   addPlanActions(actions, 'dataView', manifest.dataViews, existing.dataViews, (item, current) => dataViewEquals(target.bound, item, current));
   addPlanActions(actions, 'pagePermissionGroup', manifest.pagePermissionGroups, existing.pagePermissionGroups, (item, current) => pagePermissionGroupEquals(target.bound, item, current));
@@ -4481,8 +4545,10 @@ async function publishResourceManifest(config, target, manifest, options = {}) {
   await publishWorkflowResources(config, target, manifest.workflows || [], result);
   await publishFunctionResources(config, target, manifest.functions || [], result);
   await publishAuthConfigResources(config, target, manifest.authConfigs || [], result);
+  await publishRouteResources(config, target, manifest.routes || [], result);
   await publishAutomationResources(config, target, manifest.automations || [], result);
   await publishDataViewResources(config, target, manifest.dataViews || [], result);
+  await publishPublicAccessPolicyResources(config, target, manifest.publicAccessPolicies || [], result);
   await publishPagePermissionGroupResources(config, target, manifest.pagePermissionGroups || [], result);
   await publishFormPermissionGroupResources(config, target, manifest.formPermissionGroups || [], result);
   if (options.prune) {
@@ -4505,6 +4571,8 @@ async function fetchExistingResourceMaps(config, target, manifest) {
     workflows: new Map(),
     functions: new Map(),
     authConfigs: new Map(),
+    routes: new Map(),
+    publicAccessPolicies: new Map(),
     automations: new Map(),
     dataViews: new Map(),
     pagePermissionGroups: new Map(),
@@ -4635,6 +4703,28 @@ async function fetchExistingResourceMaps(config, target, manifest) {
       });
     }
   }
+  if ((manifest.routes || []).length > 0) {
+    const data = await requestWithAuth(
+      config,
+      target.profileName,
+      apiPathWithQuery(`/openxiangda-api/v1/apps/${encodeURIComponent(target.appType)}/routes`, {
+        page: 1,
+        pageSize: 1000,
+      })
+    );
+    indexByCode(maps.routes, normalizeItems(data), item => item.code || item.resourceCode);
+  }
+  if ((manifest.publicAccessPolicies || []).length > 0) {
+    const data = await requestWithAuth(
+      config,
+      target.profileName,
+      apiPathWithQuery(`/openxiangda-api/v1/apps/${encodeURIComponent(target.appType)}/public-access/policies`, {
+        page: 1,
+        pageSize: 1000,
+      })
+    );
+    indexByCode(maps.publicAccessPolicies, normalizeItems(data), item => item.code || item.resourceCode);
+  }
   if ((manifest.dataViews || []).length > 0) {
     const data = await requestWithAuth(
       config,
@@ -5362,6 +5452,74 @@ async function publishDataViewResources(config, target, dataViews, result) {
   }
 }
 
+async function publishRouteResources(config, target, routes, result) {
+  for (const route of routes) {
+    const code = route.code || route.resourceCode;
+    const existing = await findExistingRoute(config, target, code);
+    const body = normalizeRouteManifest(route);
+    const data = existing
+      ? await requestWithAuth(
+          config,
+          target.profileName,
+          `/openxiangda-api/v1/apps/${encodeURIComponent(target.appType)}/routes/${encodeURIComponent(code)}`,
+          { method: 'PUT', body }
+        )
+      : await requestWithAuth(
+          config,
+          target.profileName,
+          `/openxiangda-api/v1/apps/${encodeURIComponent(target.appType)}/routes`,
+          { method: 'POST', body }
+        );
+    if (data?.id) {
+      saveRouteResource(target, code, data.id, {
+        pathPattern: data.pathPattern,
+        publicAccess: data.publicAccess,
+        publicPolicyCode: data.publicPolicyCode,
+      });
+    }
+    result.published.push({
+      kind: 'route',
+      code,
+      action: existing ? 'update' : 'create',
+      id: data?.id,
+    });
+  }
+}
+
+async function publishPublicAccessPolicyResources(config, target, policies, result) {
+  for (const policy of policies) {
+    const code = policy.code || policy.resourceCode;
+    const existing = await findExistingPublicAccessPolicy(config, target, code);
+    const body = normalizePublicAccessPolicyManifest(target.bound, policy);
+    const data = existing
+      ? await requestWithAuth(
+          config,
+          target.profileName,
+          `/openxiangda-api/v1/apps/${encodeURIComponent(target.appType)}/public-access/policies/${encodeURIComponent(code)}`,
+          { method: 'PUT', body }
+        )
+      : await requestWithAuth(
+          config,
+          target.profileName,
+          `/openxiangda-api/v1/apps/${encodeURIComponent(target.appType)}/public-access/policies`,
+          { method: 'POST', body }
+        );
+    if (data?.id) {
+      savePublicAccessPolicyResource(target, code, data.id, {
+        mode: data.mode,
+        routeCode: data.routeCode,
+        pathPattern: data.pathPattern,
+      });
+    }
+    result.published.push({
+      kind: 'publicAccessPolicy',
+      code,
+      action: existing ? 'update' : 'create',
+      id: data?.id,
+    });
+  }
+}
+
 async function findExistingFunction(config, target, code) {
   const stateId = target.bound.resources?.functions?.[code]?.functionId;
   const byCode = await requestOptionalWithAuth(
@@ -5374,6 +5532,30 @@ async function findExistingFunction(config, target, code) {
   return null;
 }
 
+async function findExistingRoute(config, target, code) {
+  const stateId = target.bound.resources?.routes?.[code]?.routeId;
+  const byCode = await requestOptionalWithAuth(
+    config,
+    target.profileName,
+    `/openxiangda-api/v1/apps/${encodeURIComponent(target.appType)}/routes/${encodeURIComponent(code)}`
+  );
+  if (byCode?.id) return byCode;
+  if (stateId) return { id: stateId, code };
+  return null;
+}
+
+async function findExistingPublicAccessPolicy(config, target, code) {
+  const stateId = target.bound.resources?.publicAccessPolicies?.[code]?.policyId;
+  const byCode = await requestOptionalWithAuth(
+    config,
+    target.profileName,
+    `/openxiangda-api/v1/apps/${encodeURIComponent(target.appType)}/public-access/policies/${encodeURIComponent(code)}`
+  );
+  if (byCode?.id) return byCode;
+  if (stateId) return { id: stateId, code };
+  return null;
+}
+
 async function findExistingAuthConfig(config, target, code) {
   const stateId = target.bound.resources?.authConfigs?.[code]?.configId;
   const byCode = await requestOptionalWithAuth(
@@ -5537,7 +5719,14 @@ async function pruneResourceManifest(config, target, manifest, result) {
   await pruneAutomations(config, target, desiredCodes(manifest.automations), result);
   await pruneFunctions(config, target, desiredCodes(manifest.functions), result);
   await pruneAuthConfigs(config, target, desiredCodes(manifest.authConfigs), result);
+  await pruneRoutes(config, target, desiredCodes(manifest.routes), result);
   await pruneDataViews(config, target, desiredCodes(manifest.dataViews), result);
+  await prunePublicAccessPolicies(
+    config,
+    target,
+    desiredCodes(manifest.publicAccessPolicies),
+    result
+  );
   await prunePagePermissionGroups(
     config,
     target,
@@ -5755,6 +5944,52 @@ async function pruneAuthConfigs(config, target, desired, result) {
   }
 }
 
+async function pruneRoutes(config, target, desired, result) {
+  const data = await requestWithAuth(
+    config,
+    target.profileName,
+    apiPathWithQuery(`/openxiangda-api/v1/apps/${encodeURIComponent(target.appType)}/routes`, {
+      page: 1,
+      pageSize: 1000,
+    })
+  );
+  for (const route of normalizeItems(data)) {
+    const code = route.code || route.resourceCode;
+    if (!code || desired.has(code)) continue;
+    await pruneOne(config, target, result, 'route', code, route.id, async () => {
+      await requestWithAuth(
+        config,
+        target.profileName,
+        `/openxiangda-api/v1/apps/${encodeURIComponent(target.appType)}/routes/${encodeURIComponent(code)}`,
+        { method: 'DELETE' }
+      );
+    });
+  }
+}
+
+async function prunePublicAccessPolicies(config, target, desired, result) {
+  const data = await requestWithAuth(
+    config,
+    target.profileName,
+    apiPathWithQuery(`/openxiangda-api/v1/apps/${encodeURIComponent(target.appType)}/public-access/policies`, {
+      page: 1,
+      pageSize: 1000,
+    })
+  );
+  for (const policy of normalizeItems(data)) {
+    const code = policy.code || policy.resourceCode;
+    if (!code || desired.has(code)) continue;
+    await pruneOne(config, target, result, 'publicAccessPolicy', code, policy.id, async () => {
+      await requestWithAuth(
+        config,
+        target.profileName,
+        `/openxiangda-api/v1/apps/${encodeURIComponent(target.appType)}/public-access/policies/${encodeURIComponent(code)}`,
+        { method: 'DELETE' }
+      );
+    });
+  }
+}
+
 async function prunePagePermissionGroups(config, target, desired, result) {
   const data = await requestWithAuth(
     config,
@@ -5831,6 +6066,8 @@ function removeStateResource(target, kind, code) {
     automation: 'automations',
     function: 'functions',
     authConfig: 'authConfigs',
+    route: 'routes',
+    publicAccessPolicy: 'publicAccessPolicies',
     dataView: 'dataViews',
     pagePermissionGroup: 'pagePermissionGroups',
     formPermissionGroup: 'formPermissionGroups',
@@ -6049,6 +6286,36 @@ async function pullResources(config, target) {
     written.push(path.relative(process.cwd(), filePath));
   }
 
+  const routes = await requestWithAuth(
+    config,
+    target.profileName,
+    apiPathWithQuery(`/openxiangda-api/v1/apps/${encodeURIComponent(target.appType)}/routes`, {
+      page: 1,
+      pageSize: 1000,
+    })
+  );
+  for (const route of normalizeItems(routes)) {
+    const code = route.code || route.resourceCode || route.id;
+    const filePath = path.join(baseDir, 'routes', `${code}.json`);
+    writeResourceJsonFile(filePath, toPulledRoute(route));
+    written.push(path.relative(process.cwd(), filePath));
+  }
+
+  const publicAccessPolicies = await requestWithAuth(
+    config,
+    target.profileName,
+    apiPathWithQuery(`/openxiangda-api/v1/apps/${encodeURIComponent(target.appType)}/public-access/policies`, {
+      page: 1,
+      pageSize: 1000,
+    })
+  );
+  for (const policy of normalizeItems(publicAccessPolicies)) {
+    const code = policy.code || policy.resourceCode || policy.id;
+    const filePath = path.join(baseDir, 'public-access', `${code}.json`);
+    writeResourceJsonFile(filePath, toPulledPublicAccessPolicy(policy, pullLookups));
+    written.push(path.relative(process.cwd(), filePath));
+  }
+
   const dataViews = await requestWithAuth(
     config,
     target.profileName,
@@ -6264,6 +6531,48 @@ function toPulledDataView(dataView, permissionGroups, lookups) {
   });
 }
 
+function toPulledRoute(route) {
+  return stripUndefinedValues({
+    code: route.code || route.resourceCode,
+    title: route.title || route.name,
+    kind: route.kind || 'page',
+    pathPattern: route.pathPattern || route.path,
+    menuCode: route.menuCode || undefined,
+    publicAccess: route.publicAccess || 'none',
+    publicPolicyCode: route.publicPolicyCode || route.policyCode || undefined,
+    meta: route.metaJson || route.meta || undefined,
+  });
+}
+
+function toPulledPublicAccessPolicy(policy, lookups) {
+  return stripUndefinedValues({
+    code: policy.code || policy.resourceCode,
+    name: policy.name,
+    description: policy.description || '',
+    enabled: policy.enabled !== false,
+    mode: policy.mode || 'guest',
+    routeCode: policy.routeCode || undefined,
+    pathPattern: policy.pathPattern || policy.path || undefined,
+    externalRoleCodes: policy.externalRoleCodes || policy.externalRoles || [],
+    grants: rewritePublicAccessGrantsForManifest(policy.grantsJson || policy.grants || {}, lookups),
+    ticketConfig: policy.ticketConfigJson || policy.ticketConfig || undefined,
+    rateLimit: policy.rateLimitJson || policy.rateLimit || undefined,
+    expiresAt: policy.expiresAt || undefined,
+  });
+}
+
+function rewritePublicAccessGrantsForManifest(grants, lookups) {
+  const formCodes = normalizePermissionCodeArray(grants.forms).map(formUuid =>
+    lookups.formCodeByUuid.get(formUuid) || formUuid
+  );
+  return stripUndefinedValues({
+    formCodes,
+    dataViews: normalizePermissionCodeArray(grants.dataViews),
+    functions: normalizePermissionCodeArray(grants.functions),
+    connectors: normalizePermissionCodeArray(grants.connectors),
+  });
+}
+
 function toPulledAuthConfig(authConfig) {
   return stripUndefinedValues({
     code: authConfig.code || authConfig.resourceCode,
@@ -6454,6 +6763,54 @@ function normalizeDataViewManifest(bound, dataView) {
   });
 }
 
+function normalizeRouteManifest(route) {
+  const code = route.code || route.resourceCode;
+  return stripUndefinedValues({
+    code,
+    title: route.title || route.name || code,
+    kind: route.kind || 'page',
+    pathPattern: route.pathPattern || route.path,
+    menuCode: route.menuCode,
+    publicAccess: route.publicAccess || 'none',
+    publicPolicyCode: route.publicPolicyCode || route.policyCode,
+    meta: route.meta || route.metaJson,
+  });
+}
+
+function normalizePublicAccessPolicyManifest(bound, policy) {
+  const code = policy.code || policy.resourceCode;
+  return stripUndefinedValues({
+    code,
+    name: policy.name || policy.title || code,
+    description: policy.description || '',
+    enabled: policy.enabled !== false,
+    mode: policy.mode || 'guest',
+    routeCode: policy.routeCode,
+    pathPattern: policy.pathPattern || policy.path,
+    externalRoleCodes: normalizePermissionCodeArray(
+      policy.externalRoleCodes || policy.externalRoles || policy.roles
+    ),
+    grants: normalizePublicAccessGrants(bound, policy.grants || {}),
+    ticketConfig: policy.ticketConfig,
+    rateLimit: policy.rateLimit,
+    expiresAt: policy.expiresAt,
+  });
+}
+
+function normalizePublicAccessGrants(bound, grants = {}) {
+  const formEntries = [
+    ...normalizePermissionCodeArray(grants.forms),
+    ...normalizePermissionCodeArray(grants.formCodes),
+    ...normalizePermissionCodeArray(grants.formUuids),
+  ];
+  return stripUndefinedValues({
+    forms: unique(formEntries.map(code => resolveOptionalFormUuid(bound, code)).filter(Boolean)),
+    dataViews: normalizePermissionCodeArray(grants.dataViews),
+    functions: normalizePermissionCodeArray(grants.functions),
+    connectors: normalizePermissionCodeArray(grants.connectors),
+  });
+}
+
 function normalizeAuthConfigManifest(authConfig) {
   const code = authConfig.code || authConfig.resourceCode || 'default';
   const configJson = clonePlainJson(
@@ -6969,6 +7326,40 @@ function authConfigEquals(desired, existing) {
   );
 }
 
+function routeEquals(desired, existing) {
+  if (!existing) return false;
+  const expected = normalizeRouteManifest(desired);
+  return (
+    String(existing.code || existing.resourceCode || '') === String(expected.code || '') &&
+    String(existing.title || existing.name || '') === String(expected.title || '') &&
+    String(existing.kind || 'page') === String(expected.kind || 'page') &&
+    String(existing.pathPattern || existing.path || '') === String(expected.pathPattern || '') &&
+    String(existing.menuCode || '') === String(expected.menuCode || '') &&
+    String(existing.publicAccess || 'none') === String(expected.publicAccess || 'none') &&
+    String(existing.publicPolicyCode || existing.policyCode || '') === String(expected.publicPolicyCode || '') &&
+    jsonEqualsForPlan(existing.metaJson || existing.meta || {}, expected.meta || {}, desired.__dir)
+  );
+}
+
+function publicAccessPolicyEquals(bound, desired, existing) {
+  if (!existing) return false;
+  const expected = normalizePublicAccessPolicyManifest(bound, desired);
+  return (
+    String(existing.code || existing.resourceCode || '') === String(expected.code || '') &&
+    String(existing.name || '') === String(expected.name || '') &&
+    String(existing.description || '') === String(expected.description || '') &&
+    Boolean(existing.enabled) === Boolean(expected.enabled) &&
+    String(existing.mode || 'guest') === String(expected.mode || 'guest') &&
+    String(existing.routeCode || '') === String(expected.routeCode || '') &&
+    String(existing.pathPattern || '') === String(expected.pathPattern || '') &&
+    stringSetEquals(existing.externalRoleCodes || [], expected.externalRoleCodes || []) &&
+    jsonEqualsForPlan(existing.grantsJson || existing.grants || {}, expected.grants || {}, desired.__dir) &&
+    jsonEqualsForPlan(existing.ticketConfigJson || existing.ticketConfig || {}, expected.ticketConfig || {}, desired.__dir) &&
+    jsonEqualsForPlan(existing.rateLimitJson || existing.rateLimit || {}, expected.rateLimit || {}, desired.__dir) &&
+    String(existing.expiresAt || '') === String(expected.expiresAt || '')
+  );
+}
+
 function dataViewEquals(bound, desired, existing) {
   if (!existing) return false;
   const expected = normalizeDataViewManifest(bound, desired);

package/openxiangda-skills/SKILL.md

@@ -29,7 +29,8 @@ OpenXiangda supports two workspace modes. Classic `sy-lowcode-app-workspace` pub
 | 自动化 / 定时任务 / 提交触发 / cron | `openxiangda-workflow-automation` | `openxiangda automation validate / create / publish / enable` |
 | App Function / function_call / 可复用后端逻辑 | `openxiangda-workflow-automation` | declare `src/resources/functions/<code>.json` + `src/functions/<code>/index.ts` |
 | 应用登录 / Auth SDK / 手机号验证码 / CAS / 钉钉免登 | `openxiangda-architecture-design` + `openxiangda-page` | design security gate first, then declare `src/resources/auth/<code>.json` and use `createAuthClient` / `LoginPage` |
-| 角色 / 权限组 / 字段权限 / 数据范围 / 公开访问 | `openxiangda-permission-settings` | `openxiangda permission ...` / `openxiangda settings ...` |
+| 角色 / 权限组 / 字段权限 / 数据范围 | `openxiangda-permission-settings` | `openxiangda permission ...` / `openxiangda settings ...` |
+| 外部人员无需登录访问 / 公开报名 / 公开查询 / public page | `openxiangda-architecture-design` + `openxiangda-permission-settings` + `openxiangda-page` | 先确认公开范围、外部角色、ticket、grants；再声明 `routes` + `public-access` 并用 `PublicAccessGate` |
 | 看应用结构 / 快照 / 对比 / 诊断 / 排查 / 报错 | `openxiangda-inspect` | `openxiangda app snapshot <APP_XXX> --profile <name> --json` |
 | 登录 / 切换平台 / profile / token / whoami | `openxiangda-core` | `openxiangda env --profile <name>` / `openxiangda auth status` |
 | 多表只读联表 / 固定口径统计 / 强实时复杂查询 / 看板指标 | `openxiangda-form` (data view) | declare `src/resources/data-views/<code>.json` with `storageMode` → `resource publish` |
@@ -44,6 +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`.
 - ✅ 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.
 - ✅ Treat workflow forms as an exception. Ordinary ticket/order/task/asset lifecycles use status fields, state machines, action logs, permissions, and automations; workflows are for real approval tasks.
@@ -58,6 +60,7 @@ OpenXiangda supports two workspace modes. Classic `sy-lowcode-app-workspace` pub
 - ❌ Running a full publish after editing one file. Default to `--changed --dry-run` → `--changed`, or targeted `--page` / `--form`.
 - ❌ Storing tokens, AK, SK, or third-party API secrets in project files. Shared env (`APP_OSS_*`, feedback robot) goes to `~/.openxiangda/.env`.
 - ❌ Raw native HTML form controls in AI-authored workspace code (`<input>`, `<select>`, `<textarea>`, file inputs, hand-written pickers, hand-written upload controls). They are allowed only inside OpenXiangda SDK/platform component internals.
+- ❌ Using `?publicAccess=guest` or form `publicAccess` settings for new React SPA apps. Those are legacy `sy-lowcode-view` compatibility only.
 
 ## Platform Routing
 
@@ -145,6 +148,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`. Public guest access to forms, dataViews, functions, and connectors is denied unless policy `grants` explicitly names the resource; backend permission groups still apply.
 - 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.
 - Use `openxiangda app snapshot <APP_XXX> --profile <name> --json` for diagnosis before changing an existing app.

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

@@ -25,6 +25,7 @@ This design flow is for applications built on OpenXiangda. The output is not a g
 - automations, JS_CODE V2 nodes, and App Functions
 - notifications and connectors
 - application login/auth methods, registration policy, identity matching, and provider boundaries
+- public access routes, external roles, ticket strategy, and explicit grants
 - publish and acceptance steps
 
 The design is complete only when another agent can implement it without deciding major architecture tradeoffs.
@@ -170,6 +171,25 @@ Ask these before generating any login/auth design:
 
 Default: registration is rejected; provider functions return identity assertions only; platform auth service owns account creation, binding, permission assignment, cookies, and tokens.
 
+### Public Access
+
+Ask these before designing any page or data that external people can access without normal login:
+
+- Which exact routes are public? Use `/view/:appType/public/*` for new React SPA apps.
+- What can anonymous/external users do: view a page only, submit a form, query a dataView, invoke a function, or call a connector-backed action?
+- Which virtual external role codes should represent these visitors, for example `external_visitor`, `external_applicant`, or `external_ticket_holder`?
+- Is ordinary guest mode enough, or does the link need `mode: "ticket"` with expiry/single-use behavior?
+- Which forms/dataViews/functions/connectors are explicitly granted? Everything not listed in `grants` is denied.
+- Which backend permission groups must also include the external role codes?
+- Is the page safe for search/share, or should the URL contain a generated ticket?
+
+Recommended default if the user is unsure:
+
+- Public marketing/info pages: `mode: "guest"`, no data grants.
+- Public form submission: `mode: "guest"` plus one form grant and a submit permission group for `external_visitor`.
+- Sensitive lookup or status query: `mode: "ticket"` plus one dataView/function grant, short TTL, and a read-only permission group.
+- Never use old `?publicAccess=guest` for new React SPA apps; it is legacy `sy-lowcode-view` compatibility only.
+
 ### UI Design
 
 Ask whether to use Product Design or another design skill for:
@@ -238,6 +258,15 @@ For simple CRUD/admin lists, design can proceed with the appropriate OpenXiangda
 - Phone-code providers are App Functions. They validate send/verify events and return identity assertions; they do not issue tokens or mutate platform users.
 - New-user registration must be explicit, with default roles and identity conflict behavior documented.
 
+### Public Access
+
+- Route resources live under `src/resources/routes/` and use `publicAccess: "guest"` or `"ticket"` only for `/view/:appType/public/*` paths.
+- 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.
+- Old `?publicAccess=guest` and form `publicAccess` settings are legacy compatibility and should not appear in new-app designs.
+
 ## Final Document Template
 
 ```markdown