openxiangda-skill-kit 2.0.0-alpha.100

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

@@ -0,0 +1,67 @@
+# AppSpec
+
+AppSpec 是 OpenXiangda 2.0 应用仓库中的可选业务意图层。它帮助 AI 理解“为什么做、应当表现成
+什么、这次改变什么”，但不复制 `openxiangda.config.ts`、编译合同、代码、测试或部署状态，也
+不是发布门禁。
+
+AppSpec 只使用 2.0 的 `appspec/`、文档 schema v1 与 context v2。绝不读取、识别、导入或迁移
+1.x 的 `openspec/`、SDD、表单、页面、函数和发布材料。
+
+## 何时读取
+
+- 工作区存在 `appspec/` 时，在分析需求或修改行为前运行 `pnpm openxiangda spec context --json`，先读取
+  有界索引。
+- 从索引选择相关变更、能力、ADR 或历史变更 ID，再运行例如
+  `pnpm openxiangda spec context booking-window --json` 读取正文。
+- AI-native 客户端可读取 `openxiangda://workspace/appspec` 或调用 `appspec_context`。
+- 默认不加载全部正文；历史变更只在追查原因时用稳定 ID 按需读取。
+
+## 何时维护
+
+| 风险 | 典型变化 | 最小维护量 |
+| --- | --- | --- |
+| L0 | 重构、格式、无行为变化 | 不创建 ChangeSpec |
+| L1 | 文案、单字段、局部规则 | 一份短 ChangeSpec |
+| L2 | 跨资源、权限、状态变化 | 加正反验收、数据与回滚 |
+| L3 | 身份、迁移、并发、外部副作用 | 加失败/幂等、资源边界和 ADR |
+
+用户没有要求且变更是 L0 时，不要为了“流程完整”创建文档。小应用可以长期只维护 `app.md`。
+
+## 标准操作
+
+```bash
+pnpm openxiangda spec init
+pnpm openxiangda spec add-capability CAP-BOOKING --title "预约管理" --resources bookings
+pnpm openxiangda spec new booking-window --title "限制可预约时段" --risk L1 \
+  --capabilities CAP-BOOKING --resources bookings
+pnpm openxiangda spec context booking-window --json
+pnpm openxiangda spec check
+pnpm openxiangda spec close booking-window --current-spec merged \
+  --summary "已通过真实角色验收"
+```
+
+`spec check` 是用户主动选择的严格检查；普通 `check/dev/deploy` 只给 advisory，不因 AppSpec
+缺失或不完整而失败。
+
+新 ChangeSpec 的 `currentSpec` 固定从 `pending` 开始。关闭前先把长期有效结果合入 `app.md` 或相关
+CapabilitySpec，再由用户确认 `merged`；不改变长期规格时由用户确认 `not-applicable`。AI 可以列出
+未合入差异，但不能自行选择这两个值。稳定 REQ/AC 未进入当前规格、L2/L3 必需章节为空或保留默认
+占位内容时，`spec close` 不移动文件。
+
+## 写作边界
+
+- `app.md` 记录长期目标、角色、范围、术语和跨能力约束。
+- `capabilities/CAP-*.md` 记录当前有效需求，使用稳定 `REQ-*` 和可证伪 `AC-*`。
+- `changes/active/*.md` 只记录本次 delta、风险、影响范围与验收；关闭前把仍有效的结论合入能力规格，
+  并由用户确认 `currentSpec`。
+- `decisions/ADR-*.md` 只用于架构显著决定，不为普通小改创建。
+- 引用真实 2.0 resource/action code，不抄字段定义和权限矩阵的机器事实。
+- AI 可以创建 `draft`、指出未确认问题和建议更新，不能自行把需求标记为 `confirmed`。
+- 不因 AppSpec 与实现冲突就静默修改其中一方；明确指出冲突，由用户决定业务意图，技术事实以实时
+  编译合同为准。
+
+## 可迁移程度
+
+完整 AppSpec 能显著提高另一个新项目复现业务逻辑的概率，但最终文档本身不等于可执行应用。
+需要接近原应用时，应同时提供 AppSpec、`openxiangda.config.ts`、必要自定义动作、测试和外部接口
+合同；历史 ChangeSpec 不是必需输入。

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

@@ -0,0 +1,7 @@
+# OpenXiangda 2.0 Architecture
+
+Keep one React application, one optional NestJS service and one platform-owned data contract. Application code directly depends only on `openxiangda`; use `openxiangda/config`, `openxiangda/core`, `openxiangda/field-kit`, `openxiangda/react`, `openxiangda/nest` and `openxiangda/testing` as the public subpaths. Do not import the physical `openxiangda-*` implementation packages.
+
+Declare resources, routes, capabilities, row policies and operation-aware field policies once in `openxiangda.config.ts`. The compiler owns derived contracts; the root package owns Field Kit, CRUD Renderer, Shell, clients and Nest integration; the platform owns identity, authorization, data, environment Heads and deployment state.
+
+Ordinary list, detail, create, update and delete operations go directly through Data API. Add a NestJS endpoint only for a business action that cannot be represented as CRUD. Run `pnpm openxiangda check` after every contract change.

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

@@ -0,0 +1,268 @@
+# OpenXiangda 2.0 Backend
+
+Read [Architecture](architecture.md) and [Data and authorization](data-authz.md)
+before adding a backend. Finish with [Testing](testing.md).
+
+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. Controllers bind operations and capabilities through `openxiangda/nest`; workers continue to use their explicit application identity.
+
+Every interactive business action uses `@OpenXiangdaOperation(operation)`. The
+guard checks `operation.requiredCapability` once at App API ingress. Inside that
+declared action, inject `OpenXiangdaBusinessDataApiService`,
+`OpenXiangdaBusinessNotificationService`, or use
+`OpenXiangdaStandardOperations`: Native Data and Notification Hub then run as the trusted backend
+for this exact application, environment, version and operation. Do not forward
+the caller's resource, row or field permissions into that internal Data call,
+and do not author an `authorizationJSON` permission mirror. The platform still
+records the initiating user and action code in records, files, events and audit.
+The platform models this internal hop as the request-bounded
+`native-business-action` principal. It is neither an OAuth client nor a Native
+runtime credential: PostgreSQL accepts it only after the platform has verified
+the signed Gateway invocation, exact target/Head, published
+`code + requiredCapability`, application data scope and initiating user. Never
+copy an invocation token into application data, construct the action headers
+yourself, or fall back to `OpenXiangdaApplicationDataApiService` when this
+channel is rejected; a rejection means the platform/package combination is not
+compatible or the invocation is stale.
+
+For an informational business notification, inject
+`OpenXiangdaBusinessNotificationService` in the same declared action. The SDK
+uses the short-lived gateway invocation, never the caller's original login
+token. The platform rechecks the operation and capability, promotes the call to
+the exact application/environment principal, and records the initiating user
+and action. Do not grant ordinary users `app:notification2:send` and do not use
+the privileged `OpenXiangdaNotificationService` as an application workaround.
+
+```ts
+import { Inject } from '@nestjs/common';
+import {
+  OPENXIANGDA_NOTIFICATION_BUSINESS_SEND_V2,
+  OPENXIANGDA_NOTIFICATION_EVENT_SEND_V2,
+  OpenXiangdaBusinessNotificationService,
+} from 'openxiangda/nest';
+
+constructor(
+  @Inject(OpenXiangdaBusinessNotificationService)
+  private readonly notifications: OpenXiangdaBusinessNotificationService,
+) {}
+
+await this.notifications.send({
+  schemaVersion: OPENXIANGDA_NOTIFICATION_BUSINESS_SEND_V2,
+  eventId: body.eventId,
+  correlationId: `proposal:${proposal.id}`,
+  messageKey: `proposal:${proposal.id}:invite:${member.id}`,
+  sourceSequence: proposal.revision,
+  recipients: [{ userId: member.userId }],
+  title: '待您附议',
+  summary: proposal.title,
+  navigationTarget: {
+    kind: 'APP_ROUTE',
+    appCode: 'proposal_app',
+    routeCodes: {
+      desktop: 'proposal.detail',
+      mobile: 'proposal.detail-mobile',
+    },
+    pathParams: { id: proposal.id },
+    access: 'AUTHENTICATED',
+  },
+  idempotencyKey: `proposal:${proposal.id}:invite:${member.id}:v${proposal.revision}`,
+});
+
+```
+
+The fixed template accepts only `title` and optional `summary`. Reuse the same
+`eventId` or `idempotencyKey` for retries. Reuse `messageKey` with increasing
+`sourceSequence` for state convergence; do not generate a new logical message
+for each retry.
+
+The generated
+`notificationTemplateCodes.applicationInformational` constant documents the
+selected platform template; `send()` chooses it automatically and does not
+accept a caller-supplied template code.
+
+Inside a signed Application Events/date-trigger handler, call
+`sendFromEvent()` on the same service. The SDK obtains the application
+credential and forwards the current eventId, deliveryId and subscription code.
+Declare only dot paths beneath the immutable event `data`; Notification Hub
+resolves the actual Native user IDs and presentation text. Do not copy values
+from the event into a caller-supplied `recipients` array and never manufacture a
+user token.
+
+```ts
+await this.notifications.sendFromEvent({
+  schemaVersion: OPENXIANGDA_NOTIFICATION_EVENT_SEND_V2,
+  correlationId: `proposal:${event.data.proposalId}`,
+  messageKey: `proposal:${event.data.proposalId}:reminder`,
+  sourceSequence: event.data.revision,
+  recipientPaths: ['assigneeUserIds'],
+  titlePath: 'notification.title',
+  summaryPath: 'notification.summary',
+  navigationTarget: {
+    kind: 'APP_ROUTE',
+    appCode: 'proposal_app',
+    routeCodes: {
+      desktop: 'proposal.detail',
+      mobile: 'proposal.detail-mobile',
+    },
+    pathParams: { id: event.data.proposalId },
+    access: 'AUTHENTICATED',
+  },
+  idempotencyKey: event.id,
+});
+```
+
+`OpenXiangdaDataApiService` deliberately retains ordinary current-user Data
+authorization and automatically inherits the request Perspective for reads.
+Its writes still authorize against the complete role union. Do not use it to
+implement a declared business action. The
+business facade also rejects routes without immutable `OpenXiangdaOperation`
+metadata, so a controller cannot silently gain trusted Data access.
+
+If a custom controller bypasses the standard Data API and reads Nest-owned SQL,
+an external service or another datastore, inject `@CurrentPerspective()` and
+apply the declared role-based read projection explicitly. Perspective is not a
+credential and must never change mutation authorization. Prefer moving ordinary
+reads back to `OpenXiangdaDataApiService`, where the platform owns the contract.
+
+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, Post } from '@nestjs/common';
+import { appOperations } from '@app/contracts';
+import {
+  OpenXiangdaBusinessDataApiService,
+  OpenXiangdaOperation,
+} from 'openxiangda/nest';
+
+@Controller()
+export class VisitorReservationsController {
+  constructor(
+    @Inject(OpenXiangdaBusinessDataApiService)
+    private readonly data: OpenXiangdaBusinessDataApiService,
+  ) {}
+
+  @Post('/api/reservations/enroll')
+  @OpenXiangdaOperation(appOperations.reservationEnroll)
+  async enroll() {
+    return await this.data.create('visitor-reservations', { status: 'pending' });
+  }
+}
+```
+
+`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:
+
+Build operation request and response schemas through
+`resourceRecordSchema`, `schemaRef` and `composeAppOperationSchemas` from
+`openxiangda/config`. These helpers project canonical field value protocols
+from the same Resource declaration and prevent repeated user, department,
+resource-reference or managed-file shapes. Do not import a physical toolchain
+package or copy the JSON protocol by hand.
+
+```ts
+{
+  code: 'reservation.enroll',
+  method: 'POST',
+  path: '/api/reservations/enroll',
+  capability: 'app:visitor-app:reservation:enroll',
+  ...composeAppOperationSchemas({
+    request: resourceRecordSchema(visitorReservations, {
+      fields: ['visitorName', 'visitDate', 'startTime'],
+    }),
+    response: schemaRef('ReservationRecord'),
+    definitions: {
+      ReservationRecord: resourceRecordSchema(visitorReservations),
+    },
+  }),
+  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-exists` requires one visible record without forcing a mutation of it;
+- `record-match` requires one visible record plus typed value/field assertions,
+  and may protect a mutation of another resource;
+- `record-assert` locks one exact record and checks declared field values or
+  declared field-to-field comparisons;
+- `databaseNowAssertion('publishAt', 'lte')` compares a declared `datetime`
+  field with the single PostgreSQL transaction time. Do not pass `Date.now()`,
+  an offset, a SQL function or a fallback timestamp; a successful idempotent
+  replay returns the original `evaluatedAt` without re-evaluating the guard;
+- `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/commands.md

@@ -0,0 +1,21 @@
+# OpenXiangda 2.0 Commands
+
+> Generated from `DEVKIT_COMMANDS`. Do not edit manually.
+
+| Command | Risk | Purpose |
+| --- | --- | --- |
+| `pnpm openxiangda create` | deploy | 创建、绑定并初始化应用 |
+| `pnpm openxiangda dev` | write-local | 连接平台测试数据启动本地 Web 与 Nest |
+| `pnpm openxiangda check` | write-local | 生成契约并在目标平台预检后执行检查、测试和构建 |
+| `pnpm openxiangda accept` | deploy | 按计划准备可选的真实预发验收身份 |
+| `pnpm openxiangda deploy` | deploy | 部署测试环境或显式复用测试版本部署生产 |
+| `pnpm openxiangda status` | read | 查询最近或指定部署状态 |
+| `pnpm openxiangda logs` | read | 查询最近或指定部署日志 |
+| `pnpm openxiangda cancel` | deploy | 幂等取消尚未提交激活的部署 |
+| `pnpm openxiangda retry` | deploy | 显式重试可恢复的失败部署 |
+| `pnpm openxiangda start` | deploy | 从当前不可变版本启动应用环境 |
+| `pnpm openxiangda stop` | deploy | 将应用环境缩容为零并保留数据 |
+| `pnpm openxiangda rollback` | deploy | 回滚测试或生产环境 |
+| `pnpm openxiangda login` | write-local | 通过平台浏览器授权登录 |
+| `pnpm openxiangda skill` | write-local | 安装当前版本的 AI Skill |
+| `pnpm openxiangda spec` | write-local | 维护可选的 AppSpec 需求与变更辅助 |

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

@@ -0,0 +1,270 @@
+# 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,
+  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`; 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. 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` 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.
+
+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 explicitly and cannot rely on an implicit
+database default.
+
+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' } },
+  ],
+}
+```
+
+`datetime-range` is always a non-empty half-open interval `[start, end)`.
+Adjacent 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:
+
+```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.
+
+Run `pnpm openxiangda check` after every declaration or permission change.