openxiangda 1.0.85 → 1.0.87

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

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,109 @@ 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": { "usage": "single-use" }
+}
+```
+
+### 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"
+}
+```
+
+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,
+});
+```
+
+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,72 @@ 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 },
+  "grants": {
+    "dataViews": ["public_score_lookup"]
+  }
+}
+```
+
+`grants.forms` 可以写本地 `formCode`，CLI 发布时会解析为真实 `formUuid`。
+
+## 3. Connector — `src/resources/connectors/<code>.json`
 
 ```json
 {
@@ -140,7 +205,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 +553,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.85",
+  "version": "1.0.87",
   "description": "OpenXiangda CLI, workspace build tools, runtime SDK, and form components.",
   "private": false,
   "bin": {
@@ -65,6 +65,7 @@
     "prepack": "npm run build:sdk",
     "test:profile-isolation": "bash scripts/profile-isolation-smoke.sh",
     "test:resource-plan": "node scripts/resource-plan-smoke.mjs",
+    "test:app-function-fallback": "node scripts/app-function-source-fallback-smoke.mjs",
     "test:runtime-deploy": "node scripts/runtime-deploy-smoke.mjs",
     "test:skill-install": "bash scripts/skill-install-smoke.sh",
     "test:workspace-init": "bash scripts/workspace-init-smoke.sh"