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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openxiangda-skill-kit",
-  "version": "2.0.0-alpha.64",
+  "version": "2.0.0-alpha.65",
   "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.47"
   },
   "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.80`. 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.80 login`, then `pnpm dlx openxiangda-cli@2.0.0-alpha.80 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/data-authz.md

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