openxiangda-skill-kit 2.0.0-alpha.100

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

@@ -0,0 +1,42 @@
+# OpenXiangda 2.0 Delivery
+
+Run `pnpm openxiangda check --json`; it defaults to the test target, compiles
+the complete configuration and contract bundles, and asks the target
+platform's advertised `configurationCompatibility` endpoint to run the same
+Native compiler validation used during deployment preparation. This read-only
+preflight happens before workspace checks, tests, builds, Buildx or uploads.
+Use `--environment production` only when explicitly checking that target. A
+failure preserves `pointer`, client contract/schema versions, platform
+version/capability and the required/supported application-contract tuples.
+The capability also publishes the existing 4 MiB configuration, 8 MiB
+contract and 10 MiB total request bounds so oversized input fails before the
+transport layer.
+Never remove generated fields, reduce versions, raise limits, add app-code
+exceptions or introduce 1.x compatibility to make it pass. The platform
+revalidates authoritatively during deployment preparation.
+
+After compatibility succeeds, check owns static checks, tests and production
+builds but deliberately does not seal an AppPackage. Its
+`data.sealedArtifact` object and `.openxiangda/build/seal-status.json` make that
+state explicit even when an older `app-package.json` remains on disk. Deploy to
+test with the returned `openxiangda deploy` next command. Deploy owns the
+official application Dockerfile and platform-provided repository target,
+builds and pushes the Nest image, then writes a `sealed` status tied to the new
+immutable package digest. Never ask the developer for an image tag, digest,
+registry password, Docker configuration, or another public build command. If
+Docker, Buildx, repository configuration, or registry login is missing,
+preserve the stable machine error and retry with the same
+`pnpm openxiangda deploy` command after fixing that prerequisite.
+
+`pnpm openxiangda accept --plan <file>` is an optional manual preproduction
+test helper. It prepares expiring real identities but does not deploy, seal,
+promote or satisfy any release gate. Use it only when the requested acceptance
+needs real role membership and browser login.
+
+Use `pnpm openxiangda status` and `pnpm openxiangda logs` without an ID for the most recent run, or pass an explicit run ID.
+
+For the AI-native MCP entrypoint, `build_app` and `deployment_plan` are explicitly unsealed previews. After the user authorizes deployment, call `deploy_app` without any image coordinate; it owns the same automatic Buildx, push, digest and sealing path as the CLI.
+
+Applications with Native Data Resources automatically require `data.native-golden-crud`. If deployment returns `OPENXIANGDA_REQUIRED_CAPABILITY_UNAVAILABLE`, preserve the remediation to upgrade the platform and retry the same deploy command. Never remove the requirement, edit the AppPackage, construct a second identity path, or create Function-based CRUD.
+
+After a successful test run, deploy the exact same version with `pnpm openxiangda deploy --environment production --from <test-deployment-id>`. Roll back with `pnpm openxiangda rollback --environment production --to <app-version-id>`. The platform owns durable deployment state.

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

@@ -0,0 +1,15 @@
+# Requirement Discovery
+
+Before editing, write a compact decision record covering:
+
+- business objective and measurable outcome;
+- actors and positive/negative scenarios;
+- resources, field meanings, required values and lifecycle states;
+- role memberships, operation capabilities, field restrictions and row scope;
+- external systems, side effects, concurrency and idempotency;
+- environment, security, volume and latency bounds;
+- acceptance evidence for UI, API, PostgreSQL/RLS and delivery.
+
+Separate known facts, assumptions and unresolved choices. Inspect the workspace protocol and existing declarations before inventing a contract. If a choice changes data meaning, authorization, external writes or release scope, resolve it before implementation. Ordinary naming or layout details may use a documented reasonable assumption.
+
+The output is complete only when every requirement maps to an owner and a falsifiable acceptance check. Do not begin with source patches and reconstruct intent afterward.

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

@@ -0,0 +1,131 @@
+# 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.
+
+The application owns the editable admin information architecture through the
+typed `defineAdminNavigation`, `adminNavigationGroup`, `adminResourcePage`,
+`adminOperationPage`, `adminWorkflowWorkCenterPage` and
+`adminWorkflowLaunchPage` 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 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.
+
+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.
+
+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, add
+`adminApplicationTodoCenterPage()` to an explicit admin navigation group. The
+compiler generates `/admin/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.
+
+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.

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

@@ -0,0 +1,66 @@
+# 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 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.

package/skills/openxiangda-v2/references/workflow-events.md

@@ -0,0 +1,180 @@
+# 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.
+
+## Boundaries
+
+- The application owns business records and domain invariants.
+- 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.
+- Named Action business notifications use `OpenXiangdaBusinessNotificationService` and the platform-owned `application.informational.standard` template. App Gateway authorizes the current user once; Notification Hub revalidates the action proof, sends as the application principal, and retains initiating user/action audit. Ordinary users never need `app:notification2:send`.
+- 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
+
+Declare workflow topology and bindings once in `openxiangda.config.ts`. Use only approval, condition and end nodes for the standard module. Keep business data in Data API/App API and pass an immutable `dataRef`, business revision and bounded facts into prepare/start.
+
+Every definition declares a launch mode: `standalone` for a self-contained
+generated save-and-start page, `custom-page` for an application operation page,
+`hidden-handoff` for a non-menu handoff route, or `work-center-only` when users
+only act on existing tasks. Only `standalone` may be referenced by
+`adminWorkflowLaunchPage`; the generated browser runtime uses the workflow's
+localized definition title, so applications do not maintain code-to-title
+maps. A standalone page receives all durable business context through its
+typed save handler and URL/search contract; it must never depend on transient
+router location state. Work center, task and instance pages remain reachable
+without becoming launch menu entries. Bind the generated metadata with
+`defineWorkflowLaunchContributions(workflowDefinitions, handlers)`; handlers
+only persist the durable business revision, while generated code keeps title
+and launch mode authoritative.
+
+Use an assignee Provider only when resolution depends on application data. The Provider returns stable Native user/role subjects and never makes the final task authorization decision.
+
+The standard operations are approve, reject, return, resubmit, transfer, delegate, add-sign, withdraw, admin reassign, admin terminate and reminder. Render only operations returned by the task/instance Surface. A template or application action cannot add a Workflow command that is absent from the Surface.
+
+## Submission and concurrency
+
+1. Persist the business draft through Data API/App API.
+2. Bind prepare to the saved revision and all submission answers.
+3. Resolve required organization/approver choices.
+4. Start with a stable idempotency key distinct from the draft-save key.
+5. Use the Surface revision/concurrency token for every command.
+
+Duplicate commands return the stored command receipt. Stale revisions fail with a structured conflict. A task/participant state transition, operation log, Workflow fact and event outbox commit atomically.
+
+## Notification profile
+
+A node may reference a notification profile that selects:
+
+- source facts that create, update or close a message;
+- audiences such as current participant, initiator, historical participant or CC;
+- a versioned template reference;
+- an allowlisted variable projection;
+- channel priority/fallback;
+- default detail target;
+- whether to show Workflow Surface actions;
+- whether a separate result message is required.
+
+Template variables must be declared by JSON Schema and stay within the field policy visible to the recipient. The Notification Hub does not query arbitrary application tables to complete a template.
+
+For a non-Workflow informational message, the public business contract accepts
+only `title`, optional `summary`, recipients and a canonical navigation target.
+Supply stable `eventId`, `idempotencyKey`, `messageKey` and monotonic
+`sourceSequence`: duplicate events and idempotency keys replay the stored
+message, while a later source sequence converges the same logical message.
+Never forward a user token, application credential or global Notification Hub
+permission from application code.
+
+A signed event/date-trigger consumer uses
+`OpenXiangdaBusinessNotificationService.sendFromEvent()`. The application
+declares safe paths under event `data` for recipients, title and summary;
+Notification Hub verifies the active durable delivery and resolves those paths
+itself. The audit actor remains the application event consumer with eventId,
+deliveryId and subscription code as initiating source. Missing or forged event
+proof, arbitrary recipient values and user impersonation are rejected.
+
+## 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, 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.
+
+To replace the standard Workflow detail page everywhere, declare both route
+codes on the Workflow definition declaration. The desktop route must be an
+`admin` route, the mobile route must be a `user` route, and both paths contain
+exactly `:instanceId`:
+
+```ts
+frontend: {
+  root: 'apps/web',
+  routes: [
+    {
+      code: 'purchase-detail',
+      path: '/admin/operations/purchases/:instanceId',
+      label: '采购审批详情',
+      surface: 'admin',
+    },
+    {
+      code: 'purchase-detail-mobile',
+      path: '/m/purchases/:instanceId',
+      label: '移动采购审批详情',
+      surface: 'user',
+    },
+  ],
+},
+workflows: {
+  definitions: [{
+    version: 1,
+    definition: purchaseApproval,
+    launch: { mode: 'work-center-only' },
+    detailRouteCode: {
+      desktop: 'purchase-detail',
+      mobile: 'purchase-detail-mobile',
+    },
+  }],
+  bindings: [],
+  activations: [],
+},
+```
+
+Bind the generated routes with `defineApplicationContributions`. Inside the
+page, read `instanceId` from React Router and optional `taskId` from the query.
+Use `loadWorkflowInstanceSurface`, `loadWorkflowTaskSurface` and
+`loadWorkflowTimeline` from `openxiangda/core`; render only operations returned
+by the Surface. The platform resolves the same declaration for desktop/mobile
+work centers, Notification Hub logical messages, DingTalk cards and other
+channel snapshots. Omitting `detailRouteCode` keeps the standard pages. A
+declared but missing or incompatible route fails closed rather than falling
+back silently.
+
+Standard launch entry is also a platform Surface. Desktop uses
+`/admin/workflows/:workflowCode/new` and mobile uses
+`/m/workflows/:workflowCode/start`; both first load
+`loadWorkflowLaunchSurface(workflowCode)`, then use the same durable
+`saveBusinessRevision -> prepareWorkflowStart -> startWorkflow` protocol.
+`custom-page` and `work-center-only` declarations do not expose the standard
+launch Surface. After start, navigate through the device's standard instance
+entry so the current `detailRouteCode` contract can redirect consistently.
+
+An application-level inbox is enabled in explicit admin navigation with
+`adminApplicationTodoCenterPage()`. It projects Notification Hub messages and
+per-recipient interaction for the current logged-in user only; it is not the
+Notification Hub management console. Use its `去处理` navigation to enter the
+authorized Workflow or application page, and keep approve/reject/transfer
+commands on the destination Surface.
+
+## Interactive channel actions
+
+Channel callbacks enter the Notification Action Gateway. The gateway verifies tenant, environment, recipient identity, task/participant, Surface revision, operation, nonce, signature and expiry before calling Workflow.
+
+The callback never writes Workflow or business state directly. It returns the Workflow command receipt, waits for the resulting fact and lets Notification Hub update the existing logical message. Duplicate or expired clicks return the current receipt/snapshot and refresh the card.
+
+Use direct card actions first for approve/reject. Return, transfer, delegate and add-sign normally deep-link to the standard task page because they require structured input.
+
+## Event handling
+
+Consume typed participant/task/instance facts with durable idempotency. Order Workflow message projection by `instanceId + instanceSequence`; never assume global event order. Terminal instance facts dominate stale participant facts and update every historical message for that instance.
+
+For Native Data facts, the platform owns the capture plan under the exact Event
+revision, Data revision, AuthZ revision and resource tuple selected by the
+Native Head. Adding a snapshot field or extending RLS may create a new plan;
+applications do not version it and must not remove the field to satisfy an old
+plan. Historical replay uses the data and plan digest frozen in the original
+fact, so it never gains fields from the current Head.
+
+Every Workflow fact v2 carries the immutable instance identity envelope:
+`workflowCode`, `definitionVersion`, `bindingVersion`, `instanceId`,
+`generation`, `businessKey`, `instanceSequence`, `revision`, `dataRef`, and
+`dataRevision`, plus `actor` and `cause`. Treat missing identity as an invalid
+fact; never infer historical versions from the current Workflow Head.
+
+Use Fake Channel before a real Adapter. Verify create, update, close, reconcile, duplicate, out-of-order, restart, retryable failure, terminal failure and unknown delivery before DingTalk or campus canaries.
+
+## Verification
+
+Run the workspace generate/check/test/build gates plus real current-user positive and negative role-union cases. Acceptance must include submit, approve, reject, return/resubmit, transfer, delegate, before/after add-sign, withdraw, terminate, duplicate commands, stale revisions, repeated callbacks, full terminal card updates, detail navigation and 1.x zero-touch evidence.

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

@@ -0,0 +1,26 @@
+# 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.
+- 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.
+- 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.
+- 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`, `OpenXiangdaBusinessNotificationService`, or `OpenXiangdaStandardOperations`. The platform checks the action capability once at App API ingress; the trusted backend then has full Data/managed business-notification access only to its exact application/environment while audit retains the initiating user and action. Do not author `authorizationJSON`, forward user tokens, grant ordinary users `app:notification2:send`, 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. 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 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; declare each Workflow launch as `standalone`, `custom-page`, `hidden-handoff` or `work-center-only`, put only self-contained standalone launch pages in navigation, and bind durable save handlers with `defineWorkflowLaunchContributions` without repeating generated titles. Desktop and mobile standard launch pages load the same canonical Workflow launch Surface. To replace Workflow detail, declare both desktop and mobile `detailRouteCode` values whose routes contain exactly `:instanceId`; Work Center, the application todo center and notification channels consume the platform-resolved paths, while every Surface and command remains server-authorized. Add the standard current-user todo page only with `adminApplicationTodoCenterPage()`; never query Notification Hub management APIs from a user page. Never depend on temporary router location state or 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 --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`; for first-time menu authoring, copy `data.adminNavigationAuthoring.suggestion.expression` once into `frontend.admin.navigation` with its listed `openxiangda/config` imports, then edit that application-owned declaration. Never treat the proposal as runtime discovery. 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.