openxiangda-skill-kit 2.0.0-alpha.64 → 2.0.0-alpha.66

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openxiangda-skill-kit",
-  "version": "2.0.0-alpha.64",
+  "version": "2.0.0-alpha.66",
   "description": "Validation and deterministic packaging for OpenXiangda 2.0 AI skills.",
   "type": "module",
   "main": "./dist/index.js",
@@ -17,7 +17,7 @@
     "README.md"
   ],
   "dependencies": {
-    "openxiangda-devkit-core": "2.0.0-alpha.46"
+    "openxiangda-devkit-core": "2.0.0-alpha.48"
   },
   "devDependencies": {
     "tsx": "4.23.12",

package/skills/openxiangda-v2/SKILL.md

@@ -5,9 +5,9 @@ description: Use when building, inspecting, validating, or delivering a complete
 
 # OpenXiangda 2.0
 
-Use the generated React, NestJS and Data API workspace as one application. Before a workspace exists, invoke the exact 2.0 package published with this Skill: `pnpm dlx openxiangda-cli@2.0.0-alpha.79`. Inside an application use only its locked CLI through `pnpm openxiangda`; never invoke a bare global `openxiangda`, because that executable may belong to 1.x.
+Use the generated React, NestJS and Data API workspace as one application. Before a workspace exists, invoke the exact 2.0 package published with this Skill: `pnpm dlx openxiangda-cli@2.0.0-alpha.81`. Inside an application use only its locked CLI through `pnpm openxiangda`; never invoke a bare global `openxiangda`, because that executable may belong to 1.x.
 
-Start with `pnpm dlx openxiangda-cli@2.0.0-alpha.79 login`, then `pnpm dlx openxiangda-cli@2.0.0-alpha.79 create <directory>`. Run `pnpm openxiangda dev` for the local feedback loop and `pnpm openxiangda check` before delivery. Moving tags such as `latest` and `alpha` are forbidden for bootstrap because package-manager metadata and dlx caches can resolve an older toolchain.
+Start with `pnpm dlx openxiangda-cli@2.0.0-alpha.81 login`, then `pnpm dlx openxiangda-cli@2.0.0-alpha.81 create <directory>`. Run `pnpm openxiangda dev` for the local feedback loop and `pnpm openxiangda check` before delivery. Moving tags such as `latest` and `alpha` are forbidden for bootstrap because package-manager metadata and dlx caches can resolve an older toolchain.
 
 For an AI-native development client, start the workspace MCP through the same
 pinned executable with `pnpm exec openxiangda --mcp-stdio --cwd <workspace>`.
@@ -19,11 +19,19 @@ path.
 
 Keep ordinary CRUD on the platform Data API. Use NestJS only for real business actions. Page and field guards improve the interface; the platform remains authoritative for rows, fields and actions.
 
+For every CRUD application, read [Data and authorization](references/data-authz.md)
+before editing the manifest. Declare each resource through only `code`, `name`,
+`fields` and optional list/layout/data-policy settings. Each field declares its
+type, label, required state, Surface flags, reference/file metadata and access
+once. `schema`, `surface`, resource `capabilities`, resource `fieldPolicies` and
+`platform/data` modules are forbidden application source.
+
 Deploy test data first with `pnpm openxiangda deploy`. Inspect it with `pnpm openxiangda status` and `pnpm openxiangda logs`. Select production explicitly only after the same tested version succeeds. Use `pnpm openxiangda rollback --to <app-version-id>` when a verified prior version must be restored.
 
 OpenXiangda 2.0 has no compatibility surface. Do not add Umi, ProComponents, RoleSession, Function CRUD, underscore resource codes, `fieldPolicies.write`, legacy Skill routing, package aliases or migration branches. Replace a wrong alpha contract directly.
 
-Read only the reference needed for the current change:
+Read only the reference needed for the current change, except that CRUD work
+always reads Data and authorization as required above:
 
 - [Architecture](references/architecture.md)
 - [Workspace agent contract](references/workspace.md)

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

@@ -53,6 +53,12 @@ Backend routes are private to the application unless their operation declaration
 }
 ```
 
+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
@@ -62,6 +68,33 @@ 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

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

@@ -1,7 +1,93 @@
 # OpenXiangda 2.0 Data and Authorization
 
-Declare stable capabilities and application roles. Express row access with platform-enforced predicates such as unrestricted school access, college field matching and current-user membership in an instrument manager array.
+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.
 
-Declare restricted field access separately for read, create and update. There is no shared `write` field and no fallback. A resource create capability owns unrestricted fields; generated update access is denied until the field declares update capabilities. Capability arrays are all-of. Frontend filtering is presentation only. Run `pnpm openxiangda check` after every policy change.
+```ts
+import {
+  currentUserDataPolicy,
+  defineOpenXiangdaApp,
+  resourceCapabilityCodes,
+} from 'openxiangda-devkit-core';
 
-One resource field owns storage and selector semantics together. A single `directory-user` reference uses `type: 'string'`; a single `directory-department` or same-application `resource` reference uses `type: 'uuid'`; every reference with `multiple: true` uses `type: 'json'`. Resource references must target a declared resource and a `string` or `text` label field. File limits belong only on `type: 'file'`. Never save labels or copied directory objects. Any role that reads or edits directory-backed fields must explicitly include `app:<app-code>:directory:read`.
+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: 'string', 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: 'string', label: '接待人', required: true,
+      reference: { kind: 'directory-user' }, list: true, filter: true,
+    },
+    {
+      code: 'hostDepartmentId', type: 'uuid', label: '接待部门',
+      reference: { kind: 'directory-department' }, list: true, filter: true,
+    },
+    {
+      code: 'attachments', type: 'file', label: '附件',
+      file: { multiple: true, maxCount: 5, maxSizeMb: 20, accept: ['image/*', '.pdf'] },
+    },
+    {
+      code: 'internalNote', type: 'text', 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.
+
+The complete storage type set is `string`, `text`, `integer`, `decimal`,
+`boolean`, `date`, `datetime`, `uuid`, `json` and `file`. Use `integer` for
+whole numbers and `decimal` for other numeric values; `number` is not a field
+type. `openxiangda check` reports an invalid type at the authored field path.
+
+A single directory user reference uses `type: 'string'`; a single department
+or same-app resource reference uses `uuid`; any `reference.multiple: true` uses
+`json`. A resource reference also declares `resourceCode` and a string/text
+`labelField`. File limits exist only under `file` and use `maxSizeMb`.
+
+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 `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/workspace.md

@@ -2,14 +2,19 @@
 
 - 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`. Resource codes are lower kebab-case. The same declaration owns storage, Surface metadata, permissions and generated AI Schema.
+- 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 application roles. Do not select RoleSession, persist platform Token or implement a second authorization path.
-- Declare restricted field read, create and update permissions explicitly. There is no `write` fallback; generated update permission is denied unless explicitly granted.
+- 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 storage types are exactly `string`, `text`, `integer`, `decimal`, `boolean`, `date`, `datetime`, `uuid`, `json` and `file`; there is no `number` type.
+- 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. Members, departments, resources and attachments use platform-owned selectors and stable IDs.
 - A single directory user reference uses a `string` field; a single department or same-app resource reference uses `uuid`; every `multiple: true` reference uses `json`. 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.
 - 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.