openxiangda 2.0.0-alpha.48 → 2.0.0-alpha.49

package/skills/openxiangda-v2/references/public-access.md

@@ -0,0 +1,159 @@
+# OpenXiangda 2.0 Anonymous Public Access
+
+Read this reference whenever the requirement includes an external person without
+a platform account, anonymous or guest access, a public form/page, resumable
+submission, duplicate checks, public attachment upload, or reading the visitor's
+own submitted records.
+
+## Decide the boundary first
+
+Record these choices before editing:
+
+- the one static public route and one Native resource it serves;
+- the exact fields the visitor may write and receive;
+- whether drafts are needed and their bounded inactivity lifetime;
+- whether the page needs `own.list`, `own.read`, or both;
+- every named duplicate validation and its exact field tuple;
+- file fields and their normal resource-level type, count, size and MIME limits;
+- same-browser-only acceptance and the negative browser/device cases.
+
+This contract identifies possession of one browser profile, not a natural person.
+Clearing the platform HttpOnly cookie, private browsing, another browser or another
+device creates a new anonymous visitor. Do not promise recovery, merge or
+cross-device continuity. WeChat, DingTalk, SMS/email verification and automatic
+platform-account creation require later, separate identity contracts.
+
+## Declare the one public policy
+
+Declare the resource normally, then add one static `surface: 'user'` route and one
+`frontend.publicAccess` policy in `openxiangda.config.ts`:
+
+```ts
+export default defineOpenXiangdaApp({
+  // ...app, authz and data declarations...
+  frontend: {
+    root: 'apps/web',
+    routes: [
+      {
+        code: 'visitor-apply',
+        path: '/visitor/apply',
+        label: '访客预约',
+        surface: 'user',
+      },
+    ],
+    publicAccess: {
+      policies: [
+        {
+          code: 'visitor-apply-public',
+          routeCode: 'visitor-apply',
+          mode: 'anonymous',
+          resourceCode: 'visitor-requests',
+          operations: [
+            'draft.read',
+            'draft.update',
+            'validate',
+            'create',
+            'own.list',
+            'own.read',
+          ],
+          fields: ['visitorName', 'phone', 'visitDate', 'photo'],
+          requiredFields: ['visitorName', 'phone', 'visitDate'],
+          ownRecordFields: ['visitorName', 'phone', 'visitDate', 'photo'],
+          draft: {
+            enabled: true,
+            inactivityTtlSeconds: 2_592_000,
+            maxBytes: 262_144,
+          },
+          validations: [
+            {
+              code: 'phone-unused',
+              kind: 'duplicate',
+              fields: ['phone'],
+              result: 'availability',
+            },
+          ],
+        },
+      ],
+    },
+  },
+});
+```
+
+The route must be static and must not also declare `capability` or `access`.
+`fields`, `requiredFields`, `ownRecordFields` and validation fields must reference
+declared fields on the same resource. Public create must cover every writable
+required business field on that Native resource; `check` rejects an incomplete or
+widened declaration.
+
+Request only the operations the page uses:
+
+- `draft.read` and `draft.update` resume the current browser's active draft;
+- `validate` runs only named availability checks and never returns matching rows;
+- `create` performs the final idempotent submission;
+- `own.list` returns a bounded, server-ordered page of this browser's submitted
+  records;
+- `own.read` returns one submitted record only after the server repeats the owner
+  and submitted-draft receipt checks.
+
+## Use the generated browser client
+
+The template already passes generated `anonymousPublicAccess` to
+`OpenXiangdaApplication`. Bind the route through the normal generated `appRoutes`
+contribution, then use only the dedicated client in that page:
+
+```tsx
+import { createAnonymousPublicClient } from 'openxiangda/react';
+
+const publicClient = createAnonymousPublicClient({ routeCode: 'visitor-apply' });
+
+const session = await publicClient.bootstrap();
+const draft = session.draft ?? await publicClient.currentDraft();
+const saved = await publicClient.saveDraft(draft.revision, {
+  visitorName,
+  phone,
+  visitDate,
+});
+
+const availability = await publicClient.validate('phone-unused', { phone });
+const photo = await publicClient.upload('photo', file);
+const withPhoto = await publicClient.saveDraft(saved.revision, { photo });
+const receipt = await publicClient.submit(
+  withPhoto.revision,
+  crypto.randomUUID(),
+);
+
+const page = await publicClient.listOwn({ pageSize: 20 });
+const detail = await publicClient.getOwn(receipt.recordId);
+```
+
+Call `bootstrap()` before other methods and reuse the same idempotency key when
+retrying one uncertain submission. Draft writes use the returned revision as CAS;
+on conflict, reload the current draft instead of overwriting it. Treat duplicate
+preflight as UI feedback only: the platform repeats validation atomically during
+submission.
+
+Never call the general Native Data API from this page, construct `created_by`,
+accept a caller-selected draft id, query arbitrary filters/order/count, expose an
+object-store credential, or use a NestJS action as anonymous CRUD. Never store an
+identity in local storage or derive ownership from IP, user-agent or a browser
+fingerprint. IP may participate only in platform rate limiting.
+
+## Acceptance
+
+After `pnpm openxiangda check --json`, verify the exact preproduction route in real
+browsers:
+
+1. a fresh browser can bootstrap, save, reload and resume one draft;
+2. declared file upload/preview and final submission succeed;
+3. named validation returns only `available` or `duplicate`, and concurrent final
+   duplicate submissions cannot both succeed;
+4. the same browser can list and open its submitted records;
+5. another browser gets an empty list and the same record id returns 404;
+6. clearing the browser credential loses draft/history access as documented;
+7. undeclared routes, fields, operations, validations and ordinary Data API calls
+   remain denied;
+8. production uses HTTPS and no public object-storage bucket or anonymous upload
+   whitelist was introduced.
+
+Read [Data and authorization](data-authz.md), [Frontend](frontend.md) and
+[Testing](testing.md) for the surrounding resource, page and delivery checks.

package/skills/openxiangda-v2/references/testing.md

@@ -22,6 +22,14 @@ For each changed resource, verify the real chain:
 5. stored values and audit records match the declared shape;
 6. PostgreSQL/RLS remains authoritative, including current-user and multi-role-union cases.
 
+For `frontend.publicAccess`, add a separate anonymous-browser matrix. Verify draft
+resume, declared file upload, named availability validation, idempotent submission,
+and same-browser `own.list`/`own.read`. In a second browser verify an empty list and
+404 for the first browser's record id. Clear the first browser credential and
+confirm access is lost as documented. Also prove undeclared routes, fields,
+operations, validations and ordinary Data API calls remain denied. A logged-in
+admin path or a mocked client does not close anonymous public acceptance.
+
 For platform generator changes, add a representative multi-resource fixture
 (the compatibility corpus fixes 43 resources, complete list/form/detail/mobile
 surfaces, Perspective/AuthZ/Workflow/Event and exactly 161 producers), assert

package/skills/openxiangda-v2/references/workspace.md

@@ -5,6 +5,7 @@
 - Use Vite, React Router, Refine Core and Ant Design. Do not add Umi, ProComponents or another admin shell.
 - Bind every generated `appRoutes` entry to its local page with `defineApplicationContributions`; desktop `admin` routes stay inside the platform Shell, while `user` routes render without an admin Shell for independent mobile/user experiences. Generated resource CRUD routes are compiler-owned under `/admin/resources/<resourceCode>...` and `/m/admin/resources/<resourceCode>...`; never recreate root resource paths, aliases or redirects. Explicit routes that have the same canonical shape as another explicit or generated route fail compilation, even when dynamic parameter names differ. Use only the typed `toolbar`, `row` and `detail` resource slots for generated resource actions. Declare the complete editable admin menu with `defineAdminNavigation` and its page/group helpers; the Shell renders only generated `adminNavigation` references and permissions only filter them. Do not create another router, menu store, layout, identity provider, permission store or copied CRUD page; route/action access uses capability or `allOf`/`anyOf`, while Data/App API and Workflow authorization remain server-owned.
 - Application login is optional `frontend.authentication`: existing platform users only, registration rejected, exact desktop `/login` and mobile `/m/login`. Bind generated `authenticationSurfaces` to separate PC/mobile renderers through `defineApplicationContributions`; renderers own only brand visuals and call `ApplicationLoginSurfaceProps`. The platform alone owns passwords, providers, OAuth state/callbacks, secure cookies, current identity and authorization. Never put login in protected `appRoutes`, call a v1 auth route, store tokens, create users/roles, or add another Router/identity provider. Keep QA in generated `platformAuthManifest`, outside the protected route denominator.
+- External users without platform accounts use only an exact static `surface: 'user'` route declared through `frontend.publicAccess`. Declare the one resource, bounded field sets, required operations, draft limits and named duplicate validations; consume only generated `anonymousPublicAccess` and `createAnonymousPublicClient`. `own.list`/`own.read` mean records submitted by the same platform-issued HttpOnly browser credential, not a verified natural person, and another browser or cleared cookie intentionally loses access. Never create a guest role/user, call the general Native Data API, expose an anonymous upload path, store identity locally or derive ownership from IP, user-agent or fingerprint.
 - Declare each resource once in `openxiangda.config.ts` with only `code`, `name`, `fields` and optional `mutationOwner`, generated/list/layout/data-policy settings. Each field owns type, label, required state, Surface flags, reference/file metadata and access. Resource codes are lower kebab-case. Use `native` for direct Data API mutations, `action`, `readonly` or `workflow` for non-Native ownership; never grant or generate Native mutation for a non-Native owner.
 - Never write resource-level `schemaVersion`, `appCode`, `schema`, `surface`, `capabilities`, `fieldPolicies` or `platform/data` modules. The compiler derives the strict DataResource, CRUD capabilities, Surface and AI Schema. The application manifest still starts with its one top-level `schemaVersion: 3`.
 - Ordinary list/get/create/update/delete, filters, export and batch operations use the platform Native Data API. Do not create Function CRUD or NestJS wrappers.