openxiangda-skill-kit 2.0.0-alpha.13 → 2.0.0-alpha.130

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

@@ -0,0 +1,259 @@
+# OpenXiangda 2.0 Frontend
+
+Read [Data and authorization](data-authz.md) for every resource or permission
+change and keep the generated [workspace contract](workspace.md) authoritative.
+
+Use the official Vite + React Router + Refine Core + Ant Design template. Import the platform-owned runtime from `openxiangda/react`, field controls from `openxiangda/field-kit` and clients/types from `openxiangda/core`. Do not copy these implementations into application source and do not add per-resource function wrappers.
+
+Generated desktop lists already own row selection, atomic batch update/delete,
+CSV/XLS/XLSX preview import, export, filters, column settings and density. Keep
+imports at 100 rows per transaction, use exact declared labels or field codes,
+and leave attachment values to the platform managed-file component.
+
+Declare searchable and filterable fields on the resource and let the standard
+CRUD renderer compose the search area. Keyword search spans the declared
+searchable fields; the first two filters remain inline and additional filters
+open in the platform's large modal. The renderer also preserves declaration
+order for form fields and removes authorization/debug explanations from the
+business UI. Do not create application-owned search toolbars, field ordering
+maps, permission tips or per-resource CRUD pages for these standard behaviors.
+
+Read the current user, complete application-role union and capabilities from the platform runtime authorization endpoint. There is no application-selected active role or identity switch. The standard Shell owns the optional Perspective selector. Use `hasReadCapability` for navigation, list/detail visibility and readable fields; continue to use `hasCapability` for create/update/delete, workflows and custom actions. The standard client sends the selected Perspective automatically, and the server repeats the projection for rows, fields and RLS. Never implement resource-specific frontend filters for it. Strip unauthorized fields from create and update payloads and never treat a disabled input as server authorization. Verify with `pnpm openxiangda check`.
+
+Use the standard `Shell` unchanged. It owns the authenticated user's display
+name, account identifier, safe avatar upload, localized application-role names,
+theme controls, Perspective selection and navigation scroll restoration. It
+also owns directory field requests under the current logged-in user's role
+union. Never fetch identity for the header, display role codes, add a second
+identity selector, or copy Shell and
+directory-client implementations into application source.
+
+For a custom application role-management page, use only the typed functions in
+`openxiangda/core`: `loadRoleManagementCatalog`, `listRoleMemberships`,
+`searchRoleManagementUsers`, the membership mutations, and the
+role-management-grant mutations. The catalog's `roleManagement` projection
+drives button visibility, while the platform repeats the check for every
+request. The “Custom role-management pages” section in
+[Data and authorization](data-authz.md) defines the delegation and CAS
+contract. Do not use the developer control-plane client in browser code.
+
+The application owns the editable admin information architecture through the
+typed `defineAdminNavigation`, `adminNavigationGroup`, `adminResourcePage`,
+and `adminOperationPage` helpers in `openxiangda/config`. The compiler emits
+all reachable `adminPages`, but the Shell renders only pages explicitly
+referenced by generated `adminNavigation`, then applies current-user access as
+a final filter. Page existence, route reachability and menu visibility are
+separate: detail/new/edit/dynamic/handoff pages never become menu entries by
+discovery, and permission logic cannot create entries. Read
+`openxiangda://workspace/contracts` or call `contract_describe`, then copy
+`data.adminNavigationAuthoring.suggestion.expression` once into
+`frontend.admin.navigation` with the listed `openxiangda/config` imports. The
+proposal is deterministic and editable; the compiler/runtime never invokes it
+or appends newly added resources later.
+
+Generated desktop resource CRUD routes use the compiler-owned
+`/admin/resources/<resourceCode>...` namespace and always render inside the
+platform's one Shell. Their independent mobile admin surface is projected from
+the same generated route catalog under `/m/admin/resources/<resourceCode>...`.
+Generated pages consume that catalog for every list/create/detail/edit/back
+navigation; do not reconstruct root resource paths in application code. Root
+and ordinary `/m/...` paths remain available to explicit user routes. The
+compiler rejects an explicit route whose canonical path shape conflicts with
+any explicit or platform-generated route, including dynamic routes that differ
+only by parameter name. Do not add aliases, redirects or route-order branches
+for earlier alpha paths.
+
+Declare the application-wide admin boundary at `frontend.admin.access` with
+`allOf` and/or `anyOf` capability arrays. Import generated `adminAccess` and
+pass it to `OpenXiangdaApplication`; the runtime evaluates that same immutable
+expression before `/admin/**`, `/m/admin/**`, the Shell, generated resources or
+admin contribution pages mount. Portal shortcuts may use the exported pure
+`isAdminAccessAllowed` predicate, while Data/App/Workflow APIs remain the
+server-side authority.
+
+Declare custom routes in `openxiangda.config.ts`, import the generated
+`appRoutes`, and bind every route key to exactly one local React page with
+`defineApplicationContributions` from `openxiangda/react`. Pass the result to
+`OpenXiangdaApplication`. The runtime registers `surface: 'admin'` routes inside
+the one platform Shell; do not wrap them in another Shell. It renders
+`surface: 'user'` routes without the admin Shell so mobile/user experiences can
+own their page layout without creating another router, identity provider or
+permission store. Only static admin routes explicitly referenced by
+`frontend.admin.navigation` enter the menu. Hidden routes retain the same
+`capability` or `access.allOf/anyOf`, including ancestor constraints. Keep admin
+operation pages under `/admin/operations`; parameterized routes remain
+reachable but cannot be menu references. `defineAdminContributions` remains an
+admin-only helper and intentionally rejects `user` routes.
+
+The platform also owns admin appearance. Wrap bespoke admin content in
+`OpenXiangdaAdminPage`. Ant Design components inherit the existing
+`ConfigProvider`; do not create another theme provider. Use
+`useOpenXiangdaTheme()` for TypeScript-rendered values such as chart colors and
+the public `--oxa-color-*`, `--oxa-shadow-surface`, and
+`--oxa-radius-surface` variables for custom CSS. Never hard-code white, black,
+or neutral greys as admin canvas, card, border, or text colors. Application
+brand and categorical colors may remain explicit only when they are not used as
+structural theme colors. Verify every custom admin page in light, dark, and
+follow-system modes.
+
+Declare application-owned login visuals with optional
+`frontend.authentication`. The only supported account contract is
+`existing-platform-users-only` with `registration.mode: 'reject'`; use exact
+desktop `/login` and mobile `/m/login`, each pointing to a static protected user
+default route. Import generated `authenticationSurfaces` and bind an exact
+desktop/mobile renderer map alongside `appRoutes`:
+
+```tsx
+const contributions = defineApplicationContributions(
+  { routes: appRoutes, authenticationSurfaces },
+  {
+    pages,
+    authentication: {
+      applicationLogin: DesktopLogin,
+      applicationLoginMobile: MobileLogin,
+    },
+  },
+);
+```
+
+Renderers receive only `ApplicationLoginSurfaceProps`: safe method descriptors,
+state/error metadata, normalized `returnTo`, and platform callbacks. They never
+receive credentials, provider configuration, OAuth state, tokens, roles, or
+authorization facts. The platform owns the one Router and authentication
+boundary, tokenless v2 facade, Secure HttpOnly session/refresh family and
+logout. Do not put login in `appRoutes`, call v1 auth APIs, persist tokens, or
+translate network/5xx and authenticated 403 states into login. Generated
+`platformAuthManifest` is the independent login QA denominator and does not
+change protected user route counts.
+
+For a deliberately anonymous user page, first read
+[Anonymous public access](public-access.md), declare one static `surface: 'user'`
+route and bind it through `frontend.publicAccess`. The policy must name one
+resource, its writable/returnable fields and only the bounded operations needed
+by the page (`draft.read`, `draft.update`, `validate`, `create`, `own.list`,
+`own.read`). A public route must not also declare `capability` or `access`.
+Pass generated `anonymousPublicAccess` to
+`<OpenXiangdaApplication publicAccess={anonymousPublicAccess}>`, then use
+`createAnonymousPublicClient({ routeCode })` from `openxiangda/react` inside
+the page. This client owns bootstrap, current-draft CAS, named validation,
+managed upload, idempotent submission and owner-scoped list/detail calls. Do
+not call the general Native Data API, store an identity in local storage, or
+derive ownership from IP, user-agent or a browser fingerprint. The HttpOnly
+browser credential identifies only this browser profile; clearing it or using
+another browser loses access by design.
+
+This is also the whole-application composition contract: pass the resulting
+`contributions` to `OpenXiangdaApplication` and let that component remain the
+only owner of `BrowserRouter`, `RuntimeBoundary`, Refine, generated resource and
+Workflow routes, and the admin Shell. A user page may render an independent PC
+or mobile layout, but it must not add a nested router/Shell or copy generated
+routes. Route parameters continue to come from React Router, and generated
+capability plus ancestor access guards run before the component renders.
+
+To expose the standard application-level todo center, declare
+`frontend.user.applicationTodoCenter: true`. The compiler generates `/todos`;
+the same runtime exposes the independent mobile `/m/todos` page. The page reads only the authenticated user's
+Notification Hub recipient projection and deep-links to the platform-resolved
+target. Do not query Notification Hub management endpoints or recreate a local
+message state store.
+
+When an application needs branded user-end composition, keep those generated
+routes and contribute renderers from the application entry through the public
+`openxiangda/react` contract:
+
+```tsx
+import {
+  defineApplicationContributions,
+  type StandardApplicationTodoCenterProps,
+  type StandardUserPageFrameProps,
+  type StandardUserSurfaceContributions,
+} from 'openxiangda/react';
+
+const standardUserSurfaces = {
+  frame: {
+    desktop: DesktopUserFrame,
+    mobile: MobileUserFrame,
+  },
+  applicationTodoCenter: {
+    desktop: DesktopTodoCenter,
+    mobile: MobileTodoCenter,
+  },
+} satisfies StandardUserSurfaceContributions;
+
+export const applicationContributions = defineApplicationContributions(
+  { routes: appRoutes, authenticationSurfaces },
+  { pages, authentication, standardUserSurfaces },
+);
+```
+
+Both desktop/mobile members and both groups are mandatory once
+`standardUserSurfaces` is present; partial families fail at compile time and
+again at runtime. Omit the property to retain the platform defaults.
+
+`StandardUserPageFrameProps` contains `pageKind`, `device`, `mobile`, rendered
+`children`, safe `route` metadata, `canGoBack` and the platform-owned `back()`
+callback. The frame wraps Todo and standard Workflow work-center, launch, task
+and instance pages. It must not create a Router, resolve identity, redirect a
+standard path or reinterpret route metadata as authorization.
+
+`StandardApplicationTodoCenterProps` contains only the authenticated current
+user's `items`, aggregate `counts`, `total`, `loading`, `loadingMore`, `error`,
+immutable `query`, `hasMore`, and the bounded callbacks `setQuery`, `refresh`,
+`loadMore`, `recordInteraction` and `openItem`. `setQuery` owns view, keyword,
+unread and paged-offset changes; `loadMore` appends and de-duplicates the next
+platform page; `openItem` records a click best-effort and uses the
+platform-resolved desktop/mobile target. Render only these props. Never import
+the private platform client, call Notification Hub endpoints, persist a Todo
+copy, accept a user/token parameter, or navigate from an item object not
+supplied by the current render. A renderer exception is contained by the
+platform error boundary without replacing `RuntimeBoundary` or the Router.
+
+The compiler also emits the required generated `routeManifest`. This is the
+single desktop/mobile paired catalog for standard Workflow and Todo pages. Each
+entry carries stable route codes, path parameters, access metadata and a
+`requiresAuthentication: true` marker; the top-level digest binds the complete
+catalog. Pass it directly to `OpenXiangdaApplication`. The runtime validates
+user Surface pairs, parameter names and shared access metadata before registering
+the Router. Applications must not recreate standard `/todos`, `/m/todos`, or
+Workflow paths, add aliases/redirects, or maintain a second route state. The
+compiler/platform preflight is the digest authority; the browser validates the
+digest shape and fails closed on malformed or inconsistent entries.
+
+For standard process submission, consume the typed browser helpers
+`loadBusinessProcessReceipt(commandId)` and
+`pollBusinessProcessCommand(commandId, afterRevision)` (or the matching Nest
+`receipt`/`poll` methods). A first response may be `accepted`; follow
+`nextPoll` until `terminal` instead of treating it as failure or issuing a
+generic request to the platform endpoint.
+
+For a small business action on a generated resource page, use the typed
+`resources[resourceCode].toolbar`, `.row` or `.detail` slots accepted by
+`defineApplicationContributions`. Declare a stable action code, label and
+capability/access expression. The render context contains only the current
+resource, already-authorized record or selection, and a bounded `refresh()`;
+it does not own CRUD, revisions, fields or authorization. Invoke a guarded Nest
+App Operation for cross-resource transactions, invariants or side effects and
+leave ordinary CRUD on the Native Data API. Do not copy a generated page just
+to insert a button.
+
+Generated contracts intentionally emit each resource Surface once in
+`resourceSurfaces`; `resourceDefinitions[code].surface` references that shared
+object. Import the generated runtime definitions normally. Do not serialize,
+inline or duplicate Surface literals in application code.
+
+The standard Workflow detail renderers consume only the authoritative Surface:
+`presentation.businessDetail`, `presentation.summary`, the typed timeline and
+operation descriptors. Continue to use `SurfaceFieldValue` for complete field
+semantics and the Workflow-scoped file client for attachments, rich-text images
+and signatures. Keep desktop and mobile renderers structurally independent;
+place decision actions in the fixed primary group, all low-frequency actions in
+the single more-actions entry, and collect comments in the action confirmation
+layer. The canonical desktop paths are `/tasks/:taskId` and
+`/workflows/:instanceId`; they render as standalone full-screen pages outside
+the admin Shell, while the platform alone replace-redirects historical admin
+detail URLs. Filter `system: true` and internal fields, omit empty sections,
+merge operation actor/action/reason/time into its vertical node, and never show
+UUIDs or revision/event diagnostics. Treat `stale` as metadata and show the
+friendly refresh prompt only after a real command token/CAS conflict. Do not
+copy the standard page into an application merely to show full business fields
+or rearrange platform-owned operations.

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

@@ -0,0 +1,74 @@
+# Testing and Acceptance
+
+Run `pnpm openxiangda check --json` after declaration or code changes. It owns
+generation plus a read-only Native compatibility preflight against the test
+platform before static validation, unit tests or production builds. Use
+`--environment production` only for an explicit production-target check.
+Preserve the stable diagnostic and JSON pointer instead of bypassing a failing
+stage. Read
+`data.sealedArtifact` in the machine result. A successful check always reports
+`state: "check-did-not-seal"`, `sealed: false` and
+`usableForDeploy: false`; it may also describe an older package as
+`previousArtifact`. Never treat an existing `.openxiangda/build/app-package.json`
+as output from the current check. Follow the exact `nextCommand`: rerun check
+when diagnostics fail, or run `openxiangda deploy` to build, seal and deploy.
+
+For each changed resource, verify the real chain:
+
+1. declaration compiles into one resource, Surface and capability set;
+2. desktop and mobile render the declared field semantics;
+3. create, read, update, delete, filtering, export and revision conflict use Native Data API;
+4. an allowed role succeeds and a denied role fails for operation, field and row paths;
+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
+the real toolchain generator output remains byte-identical, and pass the same
+fixture through the platform's exported Native validator. Then run the unchanged
+Web dist budget gate. A budget failure is a
+generator/runtime regression to fix; never raise the application budget or copy
+generated contracts into a smaller application-local format. Browser acceptance
+must also cover the large more-filters modal, declaration-order forms, hidden
+developer-only authorization copy, real account/role labels, avatar update and
+left-menu scroll preservation across route changes.
+
+Mock and unit tests are useful but do not close remote acceptance. When real
+identity acceptance is needed, create a short-lived local plan and run:
+
+```bash
+pnpm openxiangda accept --plan .openxiangda/acceptance-plan.json --json
+```
+
+The plan is explicit and preproduction-only:
+
+```json
+{
+  "schemaVersion": "openxiangda.preproduction-acceptance-plan/v2",
+  "environmentKey": "preproduction",
+  "expiresInMinutes": 240,
+  "actors": [
+    { "key": "allowed", "roleCodes": ["resource_admin"] },
+    { "key": "denied", "roleCodes": ["resource_viewer"] }
+  ]
+}
+```
+
+The result returns real temporary users and one-time login URLs. Treat those
+URLs as secrets, do not commit the plan/result, and let them expire. `accept`
+is an additional manual test facility: it is never called by `check` or
+`deploy`, never becomes a release gate, and a skipped run must not block a
+release. When it is used, capture the exact AppVersion, environment Head,
+positive/negative result, browser behavior and request identifiers. Production
+promotion reuses the exact successful version; it is not another build.
+
+For a new toolchain release, also create a completely fresh workspace using only the packed or published `openxiangda` package. Do not use repository-relative imports, unpublished workspace links or machine-installed legacy Skills.