openxiangda 1.0.86 → 1.0.88

package/openxiangda-skills/references/openxiangda-api.md

@@ -166,11 +166,11 @@ Body:
 
 ### GET `/apps/:appType/forms/:formUuid/public-access`
 
-Requires Bearer token. Returns public/guest access config for the form.
+Requires Bearer token. Returns legacy public/guest access config for the form. This endpoint is only for old `sy-lowcode-view` compatibility.
 
 ### PUT `/apps/:appType/forms/:formUuid/public-access`
 
-Requires Bearer token. Creates or updates public/guest access config.
+Requires Bearer token. Creates or updates legacy public/guest access config.
 
 Body:
 
@@ -183,7 +183,113 @@ Body:
 
 ### DELETE `/apps/:appType/forms/:formUuid/public-access`
 
-Requires Bearer token. Deletes public/guest access config for the form.
+Requires Bearer token. Deletes legacy public/guest access config for the form.
+
+## React SPA Public Access
+
+New React SPA apps use `/view/:appType/public/*`, route resources, public access policies, and a scoped public session. Do not use `?publicAccess=guest` for new apps.
+
+### GET `/apps/:appType/routes`
+
+Requires Bearer token. Lists route resources.
+
+### POST `/apps/:appType/routes`
+
+Requires Bearer token. Creates a route resource.
+
+Body:
+
+```json
+{
+  "code": "public.register",
+  "title": "公开报名",
+  "kind": "page",
+  "pathPattern": "/view/:appType/public/register",
+  "publicAccess": "guest",
+  "publicPolicyCode": "public_register"
+}
+```
+
+### PUT `/apps/:appType/routes/:code`
+
+Requires Bearer token. Updates a route resource.
+
+### DELETE `/apps/:appType/routes/:code`
+
+Requires Bearer token. Deletes a route resource.
+
+### GET `/apps/:appType/public-access/policies`
+
+Requires Bearer token. Lists public access policies.
+
+### POST `/apps/:appType/public-access/policies`
+
+Requires Bearer token. Creates a public access policy.
+
+Body:
+
+```json
+{
+  "code": "public_register",
+  "name": "公开报名入口",
+  "enabled": true,
+  "mode": "guest",
+  "routeCode": "public.register",
+  "pathPattern": "/view/:appType/public/register",
+  "externalRoleCodes": ["external_visitor"],
+  "grants": {
+    "forms": ["FORM_UUID"],
+    "dataViews": ["public_registration_lookup"],
+    "functions": ["submit_public_registration"],
+    "connectors": ["sms.sendCode"]
+  }
+}
+```
+
+### PUT `/apps/:appType/public-access/policies/:code`
+
+Requires Bearer token. Updates a public access policy.
+
+### DELETE `/apps/:appType/public-access/policies/:code`
+
+Requires Bearer token. Deletes a public access policy.
+
+### POST `/apps/:appType/public-access/policies/:code/tickets`
+
+Requires Bearer token. Creates a ticket for a `mode: "ticket"` policy.
+
+Body:
+
+```json
+{
+  "expiresAt": "2026-06-18T12:00:00.000Z",
+  "subject": { "scenario": "score-link" }
+}
+```
+
+Tickets are single-use by default. Set policy `ticketConfig.singleUse: false` only when the link is intentionally reusable.
+
+### POST `/apps/:appType/public/session`
+
+Does not require an existing login. Creates a scoped public guest session.
+
+Body:
+
+```json
+{
+  "policyCode": "public_register",
+  "routeCode": "public.register",
+  "path": "/view/APP_XXX/public/register",
+  "ticket": "optional-ticket",
+  "guestIdentifier": "public:APP_XXX:browser-id",
+  "domain": "example.com",
+  "userAgent": "browser"
+}
+```
+
+The response returns a scoped bearer token. New React SPA apps must use `PublicAccessGate` or `createPublicAccessClient` so follow-up runtime/bootstrap, dataView, function, and connector calls include `Authorization: Bearer <token>`. Do not depend on auth cookies for public sessions.
+
+Returns the normal guest token payload plus `extra.publicAccess`.
 
 ### GET `/apps/:appType/menus`
 

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

@@ -15,6 +15,7 @@ Guidelines:
 - 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 `createAuthClient` from `openxiangda/runtime` or `LoginPage` / `useAuth` from `openxiangda/runtime/react` for application login pages. Auth provider App Functions return identity assertions only; platform auth owns create/bind/reject/token decisions.
+- Use `PublicAccessGate` from `openxiangda/runtime/react` or `createPublicAccessClient` from `openxiangda/runtime` for React SPA public pages under `/view/:appType/public/*`. Do not append old `?publicAccess=guest` links in new apps.
 - For the current user's department hierarchy, use `sdk.department.getCurrentUserParentDepartments()`; do not hardcode `GET /department/:id/parentDepartments` in page code.
 - Use `sdk.auth.logoutAndRedirect({ loginUrl })` for user logout when the page should return after login. It calls the platform logout endpoint, appends the current page URL as `callback`, and redirects to the login URL. Use `sdk.auth.logout()` only when the page wants to handle redirect itself.
 - Use `sdk.role.getMyRoles()`, `sdk.role.getCurrentRole()`, and `sdk.role.switchAppRole()` for current-user app role switching. Pass `roleId: ""` to switch back to all app roles.
@@ -141,6 +142,40 @@ const result = await auth.phoneCodeLogin({
 
 For phone-code auth, the App Function provider receives `event`, `appType`, `method`, `credential`, `requestId`, `request`, and `challenge`. It may return `{ ok, providerState }` for send and `{ ok, identity }` for verify. It must not return `token`, `accessToken`, `refreshToken`, cookies, or mutate platform account tables.
 
+Public access route:
+
+```tsx
+import { PublicAccessGate } from "openxiangda/runtime/react";
+
+export function PublicRegisterRoute() {
+  return (
+    <PublicAccessGate
+      policyCode="public_register"
+      routeCode="public.register"
+    >
+      <PublicRegisterPage />
+    </PublicAccessGate>
+  );
+}
+```
+
+Standalone public session client:
+
+```ts
+import { createPublicAccessClient } from "openxiangda/runtime";
+
+const publicAccess = createPublicAccessClient({ appType, servicePrefix: "/service" });
+
+await publicAccess.startSession({
+  policyCode: "public_register",
+  routeCode: "public.register",
+  path: window.location.pathname,
+  ticket: new URLSearchParams(window.location.search).get("ticket") || undefined,
+});
+```
+
+`PublicAccessGate` stores the returned bearer token in the runtime provider and injects it into follow-up SDK requests. 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.
+
 Logout and current-user role switching:
 
 ```ts

package/openxiangda-skills/references/permissions-settings.md

@@ -185,7 +185,44 @@ Data management config is stored as an opaque JSON object by the platform. Keep
 }
 ```
 
-Public access config:
+## Public Access
+
+新 React SPA 应用的公开访问使用应用路由和公开策略资源：
+
+```json
+{
+  "code": "public.register",
+  "pathPattern": "/view/:appType/public/register",
+  "publicAccess": "guest",
+  "publicPolicyCode": "public_register"
+}
+```
+
+```json
+{
+  "code": "public_register",
+  "mode": "guest",
+  "routeCode": "public.register",
+  "externalRoleCodes": ["external_visitor"],
+  "grants": {
+    "forms": ["registration_form"],
+    "dataViews": ["public_registration_lookup"],
+    "functions": ["submit_public_registration"],
+    "connectors": ["sms.sendCode"]
+  }
+}
+```
+
+Rules:
+
+- Public routes live under `/view/:appType/public/*`.
+- Public users get a scoped `publicAccess` claim, not a normal app role assignment.
+- Use virtual external role codes, such as `external_visitor`, in page/form/dataView permission groups.
+- Form/dataView/function/connector access is denied unless the policy explicitly grants it.
+- `mode: "ticket"` requires a valid ticket for sensitive links.
+- Do not use `?publicAccess=guest` for new React SPA apps.
+
+Legacy form public access config:
 
 ```json
 {
@@ -194,4 +231,4 @@ Public access config:
 }
 ```
 
-Public access is resolved by `appType + formUuid`; no local ID mapping is needed.
+This old form-level setting is resolved by `appType + formUuid` and exists only for old `sy-lowcode-view` compatibility.

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

@@ -101,7 +101,74 @@ await auth.phoneCodeLogin({ phone, code, challengeId: sent.challengeId });
 
 设计前必须确认启用方式、注册策略、身份匹配键、provider 边界、默认权限、安全参数、第三方配置归属。
 
-## 1. Connector — `src/resources/connectors/<code>.json`
+## 1. Public Route — `src/resources/routes/<code>.json`
+
+新 React SPA 公开页使用 `/view/:appType/public/*`，不要再使用旧 `?publicAccess=guest`。
+
+```json
+{
+  "code": "public.register",
+  "title": "公开报名",
+  "kind": "page",
+  "pathPattern": "/view/:appType/public/register",
+  "publicAccess": "guest",
+  "publicPolicyCode": "public_register"
+}
+```
+
+React Router 中用 `PublicAccessGate` 创建 scoped public session：
+
+```tsx
+import { PublicAccessGate } from "openxiangda/runtime/react";
+
+<PublicAccessGate policyCode="public_register" routeCode="public.register">
+  <PublicRegisterPage />
+</PublicAccessGate>
+```
+
+## 2. Public Access Policy — `src/resources/public-access/<code>.json`
+
+公开策略声明外部角色和可访问资源。未显式 grant 的 form/dataView/function/connector 默认拒绝；grant 后仍受对应后端权限组控制。
+
+```json
+{
+  "code": "public_register",
+  "name": "公开报名入口",
+  "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"]
+  }
+}
+```
+
+Ticket 模式：
+
+```json
+{
+  "code": "public_score_lookup",
+  "name": "公开成绩查询",
+  "mode": "ticket",
+  "routeCode": "public.scoreLookup",
+  "pathPattern": "/view/:appType/public/score",
+  "externalRoleCodes": ["external_ticket_holder"],
+  "ticketConfig": { "ttlSeconds": 1800, "singleUse": true },
+  "grants": {
+    "dataViews": ["public_score_lookup"]
+  }
+}
+```
+
+Ticket 默认单次使用，首次换取 public session 后立即失效；只有明确配置 `ticketConfig.singleUse: false` 的业务场景才允许复用。
+
+`grants.forms` 可以写本地 `formCode`，CLI 发布时会解析为真实 `formUuid`。
+
+## 3. Connector — `src/resources/connectors/<code>.json`
 
 ```json
 {
@@ -140,7 +207,7 @@ const data = await sdk.connector.call("crm.getCustomer", { body: { keyword } });
 
 不要把 `authConfig` 里的真实 secret 写进 manifest；用 placeholder，由平台管理员在后台覆盖。完整字段见 [`connector-resources.md`](connector-resources.md)。
 
-## 2. Data View — `src/resources/data-views/<code>.json`
+## 4. Data View — `src/resources/data-views/<code>.json`
 
 选择规则：
 
@@ -488,11 +555,12 @@ export default async function (ctx) {
     { "fields": ["customerCode"], "unique": true },
     { "fields": ["status", "ownerDept"] }
   ],
-  "dataManagement": { "enabled": true, "default": "list" },
-  "publicAccess": { "enabled": false }
+  "dataManagement": { "enabled": true, "default": "list" }
 }
 ```
 
+`publicAccess` 表单 setting 只用于旧 `sy-lowcode-view` 兼容。新 React SPA 公开页面必须使用 `src/resources/routes/` + `src/resources/public-access/` + `PublicAccessGate`。
+
 ## 12. Menu — `src/resources/menus/<code>.json`
 
 ```json

package/package.json

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