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

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

@@ -0,0 +1,410 @@
+# 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.
+
+Anonymous external access is not an application role, current-user policy or
+unrestricted row grant. When a no-account visitor must submit, resume, upload or
+read their own submissions, read [Anonymous public access](public-access.md) and
+declare the exact `frontend.publicAccess` policy. Never widen the ordinary Native
+Data API or manufacture an internal user to serve a public page.
+
+```ts
+import {
+  currentUserDataPolicy,
+  dataPolicyExpression,
+  defineOpenXiangdaApp,
+  resourceCapabilityCodes,
+  resourceReadPolicy,
+} 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: { 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`. For a Native resource,
+grant `read` to each role that may enter its generated page; the compiler also
+grants that role every enabled generated create/update/delete operation. Remove
+an operation only when the role must be restricted, using the corresponding
+code in `deniedCapabilities`. The compiler validates the denial and seals only
+the resulting allow list, so runtime authorization has no second deny model.
+Non-Native mutation owners never receive this expansion. Directory-backed roles also require
+`app:<app-code>:directory:read`. Explicit field `access` capability codes are
+also granted only to the intended roles. They are owned and exported by the
+generated field policy, so do not repeat them in `authz.capabilities`.
+`authz.capabilities` contains only explicit `backend` or `ui` capabilities.
+
+Declare mutation ownership on the same resource with
+`mutationOwner: 'native' | 'action' | 'readonly' | 'workflow'`. Native defaults
+to generated list/detail/create/update/delete. Other owners default to readable
+list/detail only and must use their named action or Workflow boundary for
+mutation. Use `generated: { list, detail, create, update, delete }` to narrow
+the generated page/operation surface. The compiler rejects Native mutation
+pages, AI operations or role grants on a non-Native owner, and rejects
+create/update when no writable business field exists. Do not grant a resource
+create/update/delete capability to make an action-owned record editable.
+
+Declare optional work Perspectives once at the application root. A Perspective
+references existing role codes; the compiler derives its readable capability
+projection, so never hand-author `capabilityCodes` or duplicate row filters:
+
+```ts
+export default defineOpenXiangdaApp({
+  // ...identity, authz and data...
+  perspectives: [
+    {
+      code: 'reception-desk',
+      name: '接待人员视角',
+      roleCodes: ['reception_staff'],
+      default: true,
+    },
+    {
+      code: 'visitor-admin',
+      name: '访客管理员视角',
+      roleCodes: ['visitor_admin'],
+    },
+  ],
+});
+```
+
+The runtime offers only Perspectives whose `roleCodes` intersect the current
+user's actual application-role union. Selecting one sends
+`X-OpenXiangda-Perspective` on standard reads. Native Data intersects the
+normal authorized role union with that Perspective before capability, field,
+row-policy and RLS evaluation. Omit the header for the complete union. Never
+use Perspective to guard writes, workflows or custom actions.
+
+`required: true` is a logical application rule: generated forms show it as
+required, and the Native Data API rejects omission on create or explicit null
+on create/update. It does not create PostgreSQL `NOT NULL`; every authored
+business column remains physically nullable so fields can be added or made
+required without a historical-data backfill. Older rows may therefore contain
+null when they predate the rule. 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.
+
+For `uuid` fields, omission never generates a value. Only the resource system
+field `id` is platform-generated. An omitted optional UUID remains `null`; a
+required UUID must be supplied by a current create request and cannot rely on
+an implicit database default. This is Data API validation, not a physical
+`NOT NULL` constraint.
+
+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 JSON display values. For `resource-ref.*`, `resourceCode`, `value`, `label`, optional `description` and optional `snapshot` are convenient historical display data only: the target resource remains authoritative, the platform does not create a foreign key or refresh/check the stored JSON, and business actions that need current target state must query it by `resourceCode` plus `value`. A resource source `labelField` must point to `text.short` or `text.long`; a `serial-number` field can be listed in `searchFields`, `descriptionFields` or `snapshotFields`, but it is not a display label. File limits exist only under `file`; `maxCount` owns the single/multiple bound and `maxSizeMb` owns the per-file size bound. There is no `file.multiple` key.
+
+Generated list, detail, audit and preview surfaces render the stored canonical
+`label` snapshots for `option.*`, `user.*`, `department.*` and
+`resource-ref.*`, including multiple arrays and the first linked list column.
+Do not add application formatters, directory re-queries or browser-side joins
+for these standard fields.
+
+Numeric bounds belong on the field declaration and are enforced by the
+platform for every write path. They are inclusive, and only valid on
+`number.integer` or `number.decimal`:
+
+```ts
+{ code: 'capacity', type: 'number.integer', label: '容量', required: true, min: 0, max: 10000 }
+```
+
+Cross-field rules belong on the resource, not in a generated form callback.
+Only bounded same-record field comparisons are supported; declare multiple
+invariants when all must hold:
+
+```ts
+{
+  code: 'sessions',
+  name: '场次',
+  fields: [
+    { code: 'startAt', type: 'datetime', label: '开始时间', required: true },
+    { code: 'endAt', type: 'datetime', label: '结束时间', required: true },
+    { code: 'capacity', type: 'number.integer', label: '容量', required: true, min: 0 },
+    { code: 'occupied', type: 'number.integer', label: '已占用', required: true, min: 0 },
+  ],
+  invariants: [
+    { code: 'time-order', expression: { leftField: 'startAt', operator: 'lt', rightField: 'endAt' } },
+    { code: 'capacity-not-exceeded', expression: { leftField: 'capacity', operator: 'gte', rightField: 'occupied' } },
+  ],
+}
+```
+
+Every `date-range` and `datetime-range` field explicitly declares
+`rangeBoundary: 'closed' | 'half-open'`. Values remain `{ start, end }`; callers
+never send or override the boundary. Closed ranges allow `start <= end` and use
+PostgreSQL `[]`; half-open ranges require `start < end` and use `[)`. Adjacent
+half-open values such as `[10:00, 11:00)` and `[11:00, 12:00)` do not overlap.
+Use the ordinary `overlaps` query operator or a `query-empty` transaction guard;
+never add or subtract milliseconds at the boundary.
+
+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',
+  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 `current_user: true`,
+lowercase match modes, a dotted value path, or policy-level `roleCodes`. The
+compiler and platform know that `user.*` fields compare their stable `value`;
+`field` remains the declared field root code.
+
+For portal visibility windows, use the typed SDK expression and keep it a
+server-enforced read policy:
+
+```ts
+resourceReadPolicy({
+  code: 'published-articles',
+  name: '仅查看当前已发布内容',
+  resourceCode: 'articles',
+  matchMode: 'AND',
+  rules: [{ dimensionCode: 'organization', field: 'organizationId' }],
+  expression: dataPolicyExpression.allOf(
+    dataPolicyExpression.constant({
+      field: 'status', operator: 'eq', value: 'PUBLISHED',
+    }),
+    dataPolicyExpression.databaseNow({
+      field: 'publishAt', operator: 'lte',
+    }),
+    dataPolicyExpression.anyOf(
+      dataPolicyExpression.null({ field: 'expireAt', operator: 'is_null' }),
+      dataPolicyExpression.databaseNow({ field: 'expireAt', operator: 'gt' }),
+    ),
+  ),
+})
+```
+
+`db_now` is platform-owned PostgreSQL statement time and only accepts a
+`datetime` field. Missing/null values match only `is_null`; they do not match
+negative constants or time comparisons. The same bounded expression can
+combine `currentUser`, `dimension`, `relation`, `constant`, `null`, and
+`databaseNow` leaves under `allOf`/`anyOf`. Never duplicate this expression in
+a page `where` filter and call it authorization: UI filters are optional
+display state and cannot weaken or replace Native RLS.
+
+`readExpression` is always added on top of the base `matchMode`/`rules`; those
+base rules continue to restrict create/update/delete. If writes truly need no
+row scope beyond capability checks, say so explicitly with
+`writeBoundary: 'capability_only'` instead of `matchMode`/`rules`. Never use an
+empty base implicitly: `check` rejects it so an AI cannot accidentally remove
+write authorization while adding a portal read window.
+
+When a business membership resource is the durable source of a package role or
+RelationshipGrant, declare the projection instead of calling authorization
+management endpoints from application code:
+
+For an application intended for every logged-in platform user, declare one
+baseline package role directly on `authz`. The platform materializes a real
+membership for that role on first access, so routes, Data RLS, Workflow and
+business actions consume the same union. Omit the declaration for applications
+that require explicit role assignment:
+
+```ts
+authz: {
+  authenticatedUserRoleCode: 'applicant',
+  capabilities: [/* explicit UI and backend capabilities */],
+  roles: [
+    {
+      code: 'applicant',
+      name: '普通申请人',
+      capabilities: [/* bounded baseline capabilities */],
+    },
+  ],
+}
+```
+
+The referenced role must exist and cannot also be the target of a
+`roleMembershipSource`. Use projected roles such as `member` for approved
+business membership and let the current user receive the union, for example
+`applicant + member`.
+
+```ts
+authz: {
+  // ...capabilities, roles and policies...
+  roleMembershipSources: [{
+    code: 'venue-managers',
+    name: '场馆管理员角色成员',
+    resourceCode: 'venue-manager-relations',
+    userIdField: 'manager.value',
+    roleCode: 'venue_admin',
+    enabledField: 'enabled',
+    failureMode: 'strict',
+  }],
+  relationshipGrantSources: [{
+    code: 'venue-member-grants',
+    name: '场馆成员关系授权',
+    resourceCode: 'venue-manager-relations',
+    subject: { type: 'user', userIdField: 'manager.value' },
+    relationCode: 'member',
+    targetResourceCode: 'venues',
+    resourceIdField: 'venue.value',
+    operations: ['read', 'update'],
+    enabledField: 'enabled',
+    failureMode: 'strict',
+  }],
+}
+```
+
+The user path must be `user.single.value`; the target path is `id` only when the
+source resource is also the target resource, or a `resource-ref.single.value`
+that points at the declared target resource.
+Operations are a bounded constant list. Create/update/delete the relationship
+resource through the standard Data API; the platform converges and revokes only
+the facts owned by that source. Projection failure is always strict because a
+last-known-good grant could defeat revocation.
+
+Use the SDK projection health call after deployment. A platform operator with
+the existing authorization-management capability may run rebuild for historical
+rows or recover a dead-letter job. Rebuild/recovery are idempotent and accept an
+`operationId`; they never accept a user token, user id override or impersonation
+input. Do not write `sourceCode`, canonical membership rows or relationship
+grant rows yourself.
+
+## Custom role-management pages
+
+Use the current-user browser SDK when a custom desktop or mobile page must
+maintain this application's role members. Do not create an application role
+table, call the platform `role` controller, forward a developer token, or add a
+NestJS endpoint that accepts a user/tenant/role from the browser.
+
+An application or platform super administrator initializes delegation by
+attaching one role-management grant to a business role. `manageAllRoles: true`
+means every current application role and therefore requires
+`managedRoleCodes: []`; otherwise list the exact role codes. Every grant must
+include `membership.read` and may add `membership.assign`,
+`membership.update`, `membership.revoke`, and `management.delegate`:
+
+```ts
+import {
+  createRoleManagementGrant,
+  loadRoleManagementCatalog,
+} from 'openxiangda/core';
+
+const catalog = await loadRoleManagementCatalog();
+const managerAuthority = catalog.roleManagement.roles.find(
+  item => item.roleCode === 'business_manager',
+);
+
+await createRoleManagementGrant({
+  operationId: crypto.randomUUID(),
+  reason: '允许业务管理员维护场馆操作员',
+  subjectRoleCode: 'business_manager',
+  manageAllRoles: false,
+  managedRoleCodes: ['venue_operator'],
+  actions: [
+    'membership.read',
+    'membership.assign',
+    'membership.update',
+    'membership.revoke',
+    'management.delegate',
+  ],
+});
+```
+
+The platform always evaluates the current logged-in user's complete
+application-role union. A delegated manager can pass on only role/action pairs
+already present in that union and needs `management.delegate` for both the
+recipient role and every managed role. It cannot manufacture an all-role grant
+from several selected-role grants.
+
+Build the member page only from these SDK calls:
+
+```ts
+import {
+  createRoleMembership,
+  listRoleMemberships,
+  searchRoleManagementUsers,
+  updateRoleMembership,
+  revokeRoleMembership,
+} from 'openxiangda/core';
+
+const users = await searchRoleManagementUsers({ keyword: '张' });
+const page = await listRoleMemberships({
+  roleCode: 'venue_operator',
+  status: 'active',
+  limit: 20,
+  offset: 0,
+});
+
+await createRoleMembership({
+  operationId: crypto.randomUUID(),
+  reason: '张老师负责场馆日常运营',
+  userId: users.items[0]!.id,
+  roleCode: 'venue_operator',
+  scopeGrants: [],
+});
+
+const membership = page.items[0]!;
+if (membership.maintainable) {
+  await updateRoleMembership(membership.id, {
+    operationId: crypto.randomUUID(),
+    reason: '调整角色有效期',
+    expectedRevision: membership.revision,
+    scopeGrants: membership.scopeGrants,
+    validFrom: null,
+    validTo: '2027-01-01T00:00:00.000Z',
+  });
+}
+```
+
+Use `listRoleManagementGrants`, `updateRoleManagementGrant` and
+`revokeRoleManagementGrant` for the delegation page. All updates/revocations
+require the row's latest `revision`. On HTTP 409, reload catalog and rows; never
+retry with a guessed revision. Every successful mutation returns an immutable
+`receipt`; `loadAuthorizationMutationReceipt(operationId)` reads it again for
+the same actor. Show `immutableReason` for an authenticated-user or projection
+membership and never try to mutate it. A hidden button is only UX—the server
+returns 403 for every undelegated role/action.
+
+Run `pnpm openxiangda check` after every declaration or permission change.

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

@@ -0,0 +1,49 @@
+# 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.
+Treat DeploymentRun recovery as platform-authoritative. Inspect `rootFailure`,
+`latestFailure`, `candidate`, `recovery` and the append-only `attempts` ledger.
+Run only the published `recovery.nextCommand`; offer cancellation only when
+`recovery.cancelAllowed` is true. Never infer retryability or cancellation from
+status, the latest failure, or locally interpreted checkpoints.
+
+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.
+
+All AppPackage platform requirements are compiler-derived structured entries with `code`, exact `contractVersion` and a deterministic declaration-only `usageDigest`. The target platform feature must be `available` at exactly that contract version. Applications cannot declare `platform.requiredCapabilities`, pass additional requirements to the package compiler or use the deleted string `requiredCapabilities` shape.
+
+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.