openxiangda 2.0.0-alpha.2 → 2.0.0-alpha.21

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

@@ -1,5 +1,8 @@
 # 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,
@@ -7,4 +10,47 @@ 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.
 
-Read the current user, complete application-role union and capabilities from the platform runtime authorization endpoint. There is no role switcher and the browser does not send a RoleSession header. Use capabilities and field access only to present or disable UI; strip unauthorized fields from create and update payloads and never treat a disabled input as server authorization. Verify with `pnpm openxiangda check`.
+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 admin operation page, declare the route in
+`openxiangda.config.ts`, import the generated `appRoutes`, and bind every route
+key to exactly one local React page with `defineAdminContributions` from
+`openxiangda/react`. Pass the result to `OpenXiangdaApplication`. Do not wrap the
+page in another `Shell`: the runtime registers it in the unified router and the
+same Shell owns its menu entry, title, history and direct-URL capability gate.
+Only `navigation: 'menu'` routes enter the menu; hidden routes retain the same
+`capability` or `access.allOf/anyOf`, including ancestor constraints. Never add
+an application-owned layout, router, menu, identity provider or permission
+store. Keep operation pages under `/admin/operations`; parameterized routes are
+hidden so they cannot become unresolved menu links.
+
+For a small business action on a generated resource page, use the typed
+`resources[resourceCode].toolbar`, `.row` or `.detail` slots accepted by
+`defineAdminContributions`. 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.

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

@@ -1,6 +1,14 @@
 # Testing and Acceptance
 
-Run `pnpm openxiangda check` after declaration or code changes. It owns generation, static validation, unit tests and production builds; preserve its stable diagnostic instead of bypassing a failing stage.
+Run `pnpm openxiangda check --json` after declaration or code changes. It owns
+generation, static validation, unit tests and production builds; preserve its
+stable diagnostic 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:
 
@@ -11,6 +19,42 @@ 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.
 
-Mock and unit tests are useful but do not close remote acceptance. Before production, deploy to preproduction and capture the exact AppVersion, environment Head, test identities, positive/negative results, browser behavior and request identifiers. Production promotion reuses that exact successful version; it is not another build.
+For platform generator changes, add a representative multi-resource fixture
+(currently nineteen standard resources), assert each Surface literal is emitted
+only once, 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.

package/skills/openxiangda-v2/references/{workflow-notification.md → workflow-events.md}

@@ -1,4 +1,7 @@
-# Workflow and Notification Hub
+# Workflow, Events and Notification Hub
+
+Read [Architecture](architecture.md), [Data and authorization](data-authz.md)
+and [Testing](testing.md) before enabling this optional layer.
 
 Use these optional modules only when the application has a real standard approval or cross-channel notification requirement. Ordinary CRUD and application-specific state machines stay on Data API/App API and must not pull Workflow or Notification code into the default template.
 
@@ -8,7 +11,7 @@ Use these optional modules only when the application has a real standard approva
 - Workflow Kernel v2 owns definitions, instances, tasks, participants, commands, transitions and audit facts.
 - Application Events v2 owns durable facts and delivery.
 - Notification Hub v2 owns templates, rules, logical messages, channel delivery, callbacks and message operations.
-- Native Identity/AuthZ v2 owns the current user and the union of that user's current application roles. Never select, transmit or persist a RoleSession.
+- Native Identity/AuthZ v2 owns the current user and the union of that user's current application roles. Perspective is read-only and never changes workflow participation or action authorization.
 - Never import, query, migrate or call 1.x workflow/message code, tables, APIs, queues, templates or callbacks.
 
 ## Workflow declaration
@@ -46,7 +49,7 @@ Template variables must be declared by JSON Schema and stay within the field pol
 
 ## Detail navigation
 
-Use a canonical navigation target with `PLATFORM_ROUTE`, `APP_ROUTE` or allowlisted `EXTERNAL_URL`, stable route code, path/query parameters and an authenticated access requirement. Do not place environment domains, bearer tokens, cookies, RoleSession identifiers or secrets in template strings.
+Use a canonical navigation target with `PLATFORM_ROUTE`, `APP_ROUTE` or allowlisted `EXTERNAL_URL`, stable route code, path/query parameters and an authenticated access requirement. Do not place environment domains, bearer tokens, cookies, identity-switching credentials or secrets in template strings.
 
 The Notification Hub resolves desktop, mobile and channel deep links. The landing page always re-runs platform authentication and Data/AuthZ/Workflow authorization.
 

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

@@ -1,21 +1,25 @@
 # OpenXiangda 2.0 Application Agent Contract
 
 - Use only the workspace-pinned CLI: `pnpm openxiangda <command>`. Never invoke a bare global `openxiangda` inside a 2.0 task.
+- `appspec/` is the optional OpenXiangda 2.0 business-intent layer. Before changing observable behavior, read the bounded index with `pnpm openxiangda spec context --json`, then select only the relevant stable ID; use no ChangeSpec for L0 work, one short ChangeSpec for L1, and add permission/rollback/concurrency detail only for L2/L3. Before close, the user—not AI—confirms `currentSpec=merged` or `not-applicable`. AppSpec is advisory and never a release gate. Never read, import or migrate 1.x `openspec/` or SDD.
 - Use Vite, React Router, Refine Core and Ant Design. Do not add Umi, ProComponents or another admin shell.
+- Keep generated admin routes and custom actions inside the platform Shell. Bind generated `appRoutes` to local operation pages with `defineAdminContributions`, and use only its typed `toolbar`, `row` and `detail` resource slots. Do not create another router, menu, layout, identity provider, permission store or copied CRUD page; route/action access uses capability or `allOf`/`anyOf`, while Data/App API authorization remains server-owned.
 - Declare each resource once in `openxiangda.config.ts` with only `code`, `name`, `fields` and optional 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.
 - 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.
 - Add NestJS only for a named business action that needs a cross-resource transaction, an invariant or an external side effect.
+- Every interactive business action binds `@OpenXiangdaOperation(operation)` and injects `OpenXiangdaBusinessDataApiService` or `OpenXiangdaStandardOperations`. The platform checks the action capability once at App API ingress; the trusted backend then has full Data access only to its exact application/environment while audit retains the initiating user. Do not author `authorizationJSON` or reapply the user's resource, row and field permissions inside the action.
 - A NestJS backend declares only `enabled`, `isolation: 'shared' | 'dedicated'` and `resourceProfile: 'light' | 'standard'`. Never put raw Kubernetes resources, replicas, ports or environment maps in application metadata; the platform owns capacity and scaling.
-- Use the current logged-in user and the union of that user's application roles. The generated client uses same-origin cookies and does not transmit a RoleSession header. Business code must not persist a platform Token or authorization result and must not implement a second identity path.
+- Use the current logged-in user and the union of that user's application roles. An optional declared Perspective projects only read visibility (pages, rows and fields); create/update/delete, workflows and custom actions continue to authorize against the complete union. Standard Data API calls inherit `X-OpenXiangda-Perspective` automatically. Use `@CurrentPerspective()` only when custom Nest code reads outside the standard Data API, and apply an equivalent read projection explicitly. Business code must not persist a platform Token or authorization result and must not implement a second identity path.
 - Fields inherit the resource read/create/update capabilities. Use field `access` only to tighten them; arrays are all-of and `false` is explicit deny. There is no `write` fallback.
 - Field `type` is semantic, never a hand-authored database type. The supported catalog is exactly `text.short`, `text.long`, `text.rich`, `number.integer`, `number.decimal`, `boolean`, `date`, `time`, `datetime`, `date-range`, `datetime-range`, `option.single`, `option.multiple`, `cascade.single`, `cascade.multiple`, `user.single`, `user.multiple`, `department.single`, `department.multiple`, `resource-ref.single`, `resource-ref.multiple`, `file`, `image`, `signature`, `address`, `location`, `json`, `serial-number`, `uuid` and `subtable`. The compiler alone derives PostgreSQL columns, constraints and indexes.
 - Declare every custom operation capability in `authz.capabilities` with `kind: 'backend'`, then reference that same code from the operation and its allowed roles. Generated resource CRUD capabilities do not go in this catalog.
+- Build App Operation request/response schemas with `resourceRecordSchema`, `schemaRef`, `composeJsonSchema` and `composeAppOperationSchemas` from `openxiangda/config`. They project the same Resource declaration and canonical field value protocols; never import a physical toolchain package or repeat user, department, resource-reference or managed-file schemas by hand.
 - Visitor duplicate protection uses `createVisitorReservation({ duplicateMatch: { fieldCode: submittedValue }, ... })`. `duplicateMatch` is a non-empty value map, never a field-name array, and no mutable pre-read is allowed.
-- Desktop and mobile pages share values, validation and authorization, but use separate renderers. Options, members, departments and resource references store their complete display snapshots; attachments, images and signatures use platform-managed file references.
-- `option.*`, `user.*`, `department.*` and `resource-ref.*` values never collapse to scalar IDs. Single values store one labeled snapshot and multiple values store snapshot arrays. `location` accepts only exact WGS84 coordinates captured by DingTalk or browser geolocation; it has no manual input or `manual` source. Roles that consume directory-backed fields explicitly include `app:<app-code>:directory:read`.
+- Desktop and mobile pages share values, validation and authorization, but use separate renderers. Options, members and departments store display snapshots; resource references store direct JSON display values; attachments, images and signatures use platform-managed file references.
+- `option.*`, `user.*`, `department.*` and `resource-ref.*` values never collapse to scalar IDs. Single values store one labeled object and multiple values store object arrays. `resource-ref.*` JSON is not a foreign key, trusted target snapshot or automatically refreshed copy; current target state is read by `resourceCode` plus `value`. A resource source `labelField` must be `text.short` or `text.long`; `serial-number` is allowed in source search, description and snapshot fields, but not as the label. `location` accepts only exact WGS84 coordinates captured by DingTalk or browser geolocation; it has no manual input or `manual` source. Roles that consume directory-backed fields explicitly include `app:<app-code>:directory:read`.
 - Derive role grants with `resourceCapabilityCodes(appCode, resourceCode)`. Declare current-user rows only with `currentUserDataPolicy(...)`; do not invent operators, values or alternate current-user spellings.
 - Do not add compatibility aliases, migration branches or silent fallbacks for an earlier 2.0 alpha contract. Replace an incorrect contract and regenerate the application.
 - Standard Workflow and Notification Hub are optional 2.0 modules. Enable them only through the canonical `openxiangda.config.ts` declarations and generated clients; never copy 1.x workflow/message code, tables, APIs, templates or callbacks into this workspace. Keep ordinary CRUD and application-specific state machines independent of them.
-- Run `pnpm openxiangda check` after contract changes. Deploy with `pnpm openxiangda deploy`, inspect with `pnpm openxiangda status` and `pnpm openxiangda logs`, and use the platform rollback command rather than mutating K3s directly.
-- AI-native clients start the workspace protocol through the same pinned binary: `pnpm exec openxiangda --mcp-stdio --cwd <workspace>`. Read `openxiangda://workspace/contracts` or call `contract_describe`, and require its `aiCatalog` and `aiCatalogDigest` to match the normal compiler output. This is a stdio transport mode, not a ninth CLI command. Never write an application MCP server, Catalog file, preview store or second authorization path.
+- Run `pnpm openxiangda check --json` after contract changes and read `data.sealedArtifact`; check never seals, and an older `.openxiangda/build/app-package.json` is not the current check result. Use `pnpm openxiangda accept --plan <file>` only for optional real preproduction identity acceptance; it never blocks delivery. Deploy with `pnpm openxiangda deploy`, inspect with `pnpm openxiangda status` and `pnpm openxiangda logs`, and use the platform rollback command rather than mutating K3s directly.
+- AI-native clients start the workspace protocol through the same pinned binary: `pnpm exec openxiangda --mcp-stdio --cwd <workspace>`. Read `openxiangda://workspace/contracts` or call `contract_describe`; when AppSpec is enabled, also read `openxiangda://workspace/appspec` or call `appspec_context`. Require `aiCatalog` and `aiCatalogDigest` to match the normal compiler output. This is a stdio transport mode, not another application-owned server. Never write an application MCP server, Catalog file, preview store or second authorization path.