openxiangda 1.0.264 → 2.0.0-alpha.2

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

@@ -0,0 +1,116 @@
+# OpenXiangda 2.0 Backend
+
+Keep normal record CRUD in the platform Data API. Use `apps/server` only for typed business actions that need server-side logic. For an interactive request, the platform gateway supplies the verified current user, complete application-role union and capabilities from the same platform authorization snapshot used by Data API. Controllers bind operations and capabilities through `openxiangda/nest`; workers continue to use their explicit application identity.
+
+Do not duplicate resource persistence in controllers. Keep actions bounded and side-effect behavior explicit. Run `pnpm openxiangda dev` for the connected loop and `pnpm openxiangda check` before delivery.
+
+Keep the generated `apps/server/src/main.ts` on
+`bootstrapOpenXiangdaApplication(AppModule)`. Do not replace it with an
+application-owned `NestFactory` or `FastifyAdapter`: the SDK bootstrap owns the
+exact raw request bytes required by gateway signatures, proxy trust, shutdown
+hooks, and the runtime listen contract.
+
+Connected development and release builds deliberately use different compilers,
+so application Nest classes must never depend on emitted constructor metadata.
+Every constructor dependency in a `@Controller` or `@Injectable` class uses an
+explicit token:
+
+```ts
+import { Controller, Inject } from '@nestjs/common';
+import { OpenXiangdaStandardOperations } from 'openxiangda/nest';
+
+@Controller('/api/visitor-reservations')
+export class VisitorReservationsController {
+  constructor(
+    @Inject(OpenXiangdaStandardOperations)
+    private readonly operations: OpenXiangdaStandardOperations,
+  ) {}
+}
+```
+
+`openxiangda check` and `openxiangda dev` reject implicit constructor injection.
+Do not silence that diagnostic or replace the connected-development compiler.
+
+Backend routes are private to the application unless their operation declaration contains an explicit `ai` block. Never infer AI exposure or risk from the HTTP method. A write action declares its touched resources and non-empty side effects, for example:
+
+```ts
+{
+  code: 'reservation.enroll',
+  method: 'POST',
+  path: '/api/reservations/enroll',
+  capability: 'app:visitor-app:reservation:enroll',
+  requestSchema: { type: 'object', properties: { visitorName: { type: 'string' } } },
+  responseSchema: { type: 'object' },
+  ai: {
+    name: '预约访客',
+    description: '校验预约规则并创建访客预约',
+    risk: 'write',
+    resources: ['reservations'],
+    sideEffects: ['reservations:create'],
+    concurrency: 'none',
+    timeoutMs: 10000,
+  },
+}
+```
+
+Every custom operation capability is declared once in
+`authz.capabilities` with `kind: 'backend'`, then referenced by the operation
+and granted to every role allowed to call it. A capability string written only
+on an operation or role is invalid. Resource CRUD capabilities remain generated
+and must not be copied into this catalog.
+
+Generated CRUD and custom actions use the same platform Catalog, current-user authorization, Preview/Confirm boundary and idempotent execution path. Do not create an application-owned MCP server, preview store, AI role or database client.
+
+For visitor duplicates, meeting-time conflicts, and course capacity, use
+`OpenXiangdaStandardOperations`. These helpers submit the whole rule as one
+platform transaction. Do not query mutable rows before calling them and do not
+calculate replacement counters in application code. Course selection is a
+locked `record-assert` plus a bounded `increment`; replay must reach the
+platform idempotency receipt even after the course becomes full.
+
+The visitor helper has one exact command shape. `duplicateMatch` is the actual
+field-to-submitted-value object used for equality matching; it is never a list
+of field names:
+
+```ts
+return this.operations.createVisitorReservation({
+  reservationResourceCode: 'visitor-reservations',
+  duplicateMatch: {
+    visitorIdentityNumber: body.visitorIdentityNumber,
+    visitDate: body.visitDate,
+    startTime: body.startTime,
+  },
+  data: {
+    visitorIdentityNumber: body.visitorIdentityNumber,
+    visitDate: body.visitDate,
+    startTime: body.startTime,
+    status: body.status,
+  },
+  idempotencyKey: body.idempotencyKey,
+  activeStatusField: 'status',
+  activeStatusValues: ['pending', 'approved'],
+});
+```
+
+Use only declared field codes in `duplicateMatch`. Its values and `data` come
+from the same immutable request body.
+
+An idempotency key and the complete command payload are one immutable pair.
+Never put `new Date()`, `Date.now()`, `randomUUID()` or another changing value
+inside a controller while constructing the transaction. If a business time is
+part of the record, declare it as a required operation request field; the
+caller creates it once together with the idempotency key and reuses both on
+every retry. Platform-created record timestamps remain the source of truth
+when no separate business time is required.
+
+When declaring a lower-level transaction directly, use only the current
+contract:
+
+- every guard has a stable `OPENXIANGDA_*` `errorCode`;
+- `query-empty` protects a business-key uniqueness rule;
+- `record-assert` locks one exact record and checks declared field values or
+  declared field-to-field comparisons;
+- `increment` targets one declared integer field and must have a matching
+  same-resource, same-record `record-assert` guard;
+- never send SQL, table names, expressions, old guards without `errorCode`, or
+  a pre-read/absolute-update fallback.

package/skills/openxiangda-v2/references/data-authz.md

@@ -0,0 +1,93 @@
+# OpenXiangda 2.0 Data and Authorization
+
+Declare a resource and every field exactly once in `openxiangda.config.ts`.
+Do not write `schemaVersion`, `appCode`, `schema`, `capabilities`, `surface` or
+resource-level `fieldPolicies`; those are compiler projections, not application
+source. Do not create `platform/data` modules.
+
+```ts
+import {
+  currentUserDataPolicy,
+  defineOpenXiangdaApp,
+  resourceCapabilityCodes,
+} from 'openxiangda/config';
+
+const APP_CODE = 'visitor-center';
+const reservations = resourceCapabilityCodes(APP_CODE, 'visitor-reservations');
+
+const visitorReservations = {
+  code: 'visitor-reservations',
+  name: '访客预约',
+  dataPolicyCode: 'reservation-host',
+  fields: [
+    {
+      code: 'visitorName', type: 'text.short', label: '访客姓名', required: true,
+      indexed: true, list: true, filter: true, searchable: true, sortable: true,
+      section: '访客信息',
+    },
+    {
+      code: 'visitDate', type: 'date', label: '来访日期', required: true,
+      list: true, filter: true, sortable: true, section: '来访安排',
+    },
+    {
+      code: 'hostUserId', type: 'user.single', label: '接待人', required: true,
+      list: true, filter: true,
+    },
+    {
+      code: 'hostDepartmentId', type: 'department.single', label: '接待部门',
+      list: true, filter: true,
+    },
+    {
+      code: 'attachments', type: 'file', label: '附件',
+      file: { multiple: true, maxCount: 5, maxSizeMb: 20, accept: ['image/*', '.pdf'] },
+    },
+    {
+      code: 'internalNote', type: 'text.long', label: '内部备注',
+      access: { read: ['app:visitor-center:internal-note:read'], update: false },
+    },
+  ],
+  list: { defaultPageSize: 20, defaultSort: { field: 'visitDate', order: 'desc' } },
+  form: { layout: 'sections' }, detail: { layout: 'sections' },
+  mobile: { enabled: true },
+};
+```
+
+Put it in `data: { resources: [visitorReservations] }`. Resource CRUD
+capabilities are derived by `resourceCapabilityCodes`; grant the needed values
+to roles. Directory-backed roles also require
+`app:<app-code>:directory:read`. Explicit field `access` capability codes are
+also granted only to the intended roles.
+
+`required: true` owns both storage nullability and form validation. A field
+without `access` inherits the resource read/create/update capability. Each
+access array is all-of; `false` is explicit deny. The same arrays drive the
+generated UI and platform field policies.
+
+Field types are semantic, not PostgreSQL storage aliases. Use the catalog in the generated `AGENTS.md`: for example `text.short`, `number.integer`, `user.single`, `department.multiple`, `resource-ref.single`, `file`, `address` and `subtable`. The compiler alone chooses storage columns and constraints. Reference fields store complete labeled snapshots; resource references additionally declare their source and snapshot fields. File limits exist only under `file` and use `maxSizeMb`.
+
+Do not author raw schema or storage words as field types. `string`, `text`,
+`integer`, `decimal`, `boolean`, `date`, `datetime`, `uuid`, `json` and `file`
+describe value or storage families only when the platform protocol says so;
+their authored counterparts are the semantic catalog entries above (some names
+such as `date`, `datetime`, `uuid`, `json` and `file` intentionally coincide).
+In particular, `number` is not a field type: choose `number.integer` or
+`number.decimal`.
+
+Current-user row access has one spelling only:
+
+```ts
+currentUserDataPolicy({
+  code: 'reservation-host',
+  name: '接待人员仅查看本人预约',
+  resourceCode: 'visitor-reservations',
+  field: 'hostUserId.value',
+  roleCodes: ['reception_staff'],
+  unrestrictedRoleCodes: ['visitor_admin'],
+})
+```
+
+Put that value in `authz.dataPolicies`, declare both roles, and set the
+resource `dataPolicyCode` to the same code. Do not invent `operator`, `value`,
+`current_user: true`, lowercase match modes, or policy-level `roleCodes`.
+
+Run `pnpm openxiangda check` after every declaration or permission change.

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

@@ -0,0 +1,11 @@
+# OpenXiangda 2.0 Delivery
+
+Run `pnpm openxiangda check`; it owns generation, static checks, tests and production builds. Deploy to test with `pnpm openxiangda deploy`. The CLI uses the official application Dockerfile and the platform-provided repository target to build and push the Nest image, then seals only its immutable 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.
+
+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,10 @@
+# OpenXiangda 2.0 Frontend
+
+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.
+
+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`.

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

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

@@ -0,0 +1,69 @@
+# Workflow and Notification Hub
+
+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.
+- 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.
+- 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.
+
+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.
+
+## 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.
+
+The Notification Hub resolves desktop, mobile and channel deep links. The landing page always re-runs platform authentication and Data/AuthZ/Workflow authorization.
+
+## 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.
+
+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,21 @@
+# 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.
+- Use Vite, React Router, Refine Core and Ant Design. Do not add Umi, ProComponents or another admin shell.
+- 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.
+- 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.
+- 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.
+- 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`.
+- 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.

package/bin/openxiangda.js

@@ -1,26 +0,0 @@
-#!/usr/bin/env node
-
-const { main } = require('../lib/cli');
-const { maskText } = require('../lib/utils');
-
-const argv = process.argv.slice(2);
-
-main(argv).catch(error => {
-  const message =
-    error && error.message ? error.message : String(error || 'Unknown error');
-  if (argv.includes('--json')) {
-    const payload = {
-      success: false,
-      error: {
-        status: Number.isInteger(error?.status) ? error.status : null,
-        code: error?.code || error?.payload?.errorCode || null,
-        message,
-        data: error?.data ?? error?.payload?.data ?? null,
-      },
-    };
-    console.error(maskText(JSON.stringify(payload)));
-    process.exit(1);
-  }
-  console.error(maskText(message));
-  process.exit(1);
-});

package/lib/app-function-invoke.js

@@ -1,28 +0,0 @@
-function buildOpenXiangdaFunctionInvokeRequest(appType, functionCode, body) {
-  return {
-    method: 'POST',
-    path: `/openxiangda-api/v1/apps/${encodeURIComponent(appType)}/functions/${encodeURIComponent(functionCode)}/invoke`,
-    body,
-    strictEnvelope: true,
-  };
-}
-
-function buildLegacyFunctionInvokeRequest(appType, functionCode, body) {
-  return {
-    method: 'POST',
-    path: `/${encodeURIComponent(appType)}/v1/functions/${encodeURIComponent(functionCode)}/invoke.json`,
-    body,
-    strictEnvelope: true,
-  };
-}
-
-function isHttpNotFound(error) {
-  const status = Number(error?.status || error?.statusCode || error?.response?.status);
-  return status === 404 || String(error?.message || '').includes('HTTP 404');
-}
-
-module.exports = {
-  buildLegacyFunctionInvokeRequest,
-  buildOpenXiangdaFunctionInvokeRequest,
-  isHttpNotFound,
-};