openxiangda 2.29.2 → 2.31.0

package/documentation/managed-concurrency.md

@@ -0,0 +1,98 @@
+# 缓存、排队与整数配额
+
+`data.concurrency` 是可选的平台声明，用于限量申领、抢票和预约。平台负责缓存回源、等待资格、持久受理、受控 Native 事务及整数配额；应用通过 `openxiangda/react` 或 `openxiangda/mobile` 调用。平台必须声明能力 `data.managed-concurrency@1.0.0`。旧平台会在编译/发布能力检查阶段拒绝此声明。
+
+## 声明与权限
+
+完整且由双编译器测试验证的示例位于源码 `examples/managed-concurrency/declaration.ts`。调用 `defineOpenXiangdaApp(concurrencyExample())` 即可编译。把示例中的 `data.concurrency` 合入应用配置，并按实际业务配置模型和参与权限。
+
+| 声明 | 作用 |
+| --- | --- |
+| `reads` | 命名读取、有限参数、字段、条件、权限范围、新鲜期、旧值期限、失效字段和回源预算 |
+| `admission` | 本应用/环境所有命令共享的每秒速率、突发额度、在途上限 |
+| `commands` | 当前用户的能力、按资源分队列、最长等待、处理截止、Native 守卫和原子写入 |
+| `quotas` | 容量来源、业务记录上的分配 ID、可选的预占到期时间 |
+
+参数限于 UUID、有限字符串枚举和有限整数范围；绑定只接受 `input`、可信 `actor`、字面量和平台生成的 `allocation`。每个命令最多 8 个操作、8 个记录守卫。首版不执行应用任意 JS/SQL，也不在锁内调用外部系统。通知和外部副作用接已有事务后事件。
+
+配额来源模型的容量字段必须是整数；分配记录模型的引用字段必须是必填 UUID，模型设置 `mutationOwner: 'queued-command'`。角色仍须具备来源读取、分配模型创建和命令能力。普通 CRUD、导入、应用凭据均不能绕过命令所有权。用户身份由 `actor` 绑定，不能使用用户填写的人员编号决定名额归属。
+
+`database-now` 条件使用数据库时间，并按“字段 操作符 当前时间”解释。例如截止前允许报名：`{ kind: 'database-now', field: 'closesAt', operator: 'gt' }`。资格和业务截止在执行时重验，因此等待或已受理不等于一定成功。
+
+## 展示读取
+
+```ts
+const client = createManagedConcurrencyClient();
+const snapshot = await client.read('offer', { id: selectedOfferId });
+// snapshot.items、generatedAt、freshUntil、staleUntil、version、freshness
+```
+
+在平台身份初始化完成后创建并保持 `client` 实例稳定。它绑定应用、环境和当前用户；切换身份后旧客户端拒绝继续操作。组织内共享内容也要求登录与当前权限。`scope: 'application'` 不允许行策略或 actor 条件；个人/有行策略的数据使用 `scope: 'subject'`。
+
+每次访问仍通过平台现有身份、版本与字段权限链路。缓存减少内容查询；不能据此宣称整个请求零 SQL。活动内容和余量使用不同读取声明与依赖，避免每次报名使详情失效。`dependencies` 必须覆盖返回和过滤字段。Native 提交在同一事务写失效事实，恢复任务负责可靠推进；变更传播有延迟，要求即时资格或即时关闭的判断必须放在命令守卫中。
+
+冷缓存使用进程请求合并与跨副本刷新租约，短暂争用返回可重试响应。负缓存最长 5 秒，TTL 带随机抖动。可在应用版本激活后，用正常授权的 `read` 调用预热有限的热点 ID。首版提供认证后的 Redis/进程缓存，不提供公共 CDN 发布或自动扫描全量数据预热。
+
+## 提交与原结果恢复
+
+```tsx
+import { useMemo } from 'react';
+import { createManagedConcurrencyClient, useManagedCommand,
+  ManagedCommandStatus } from 'openxiangda/react';
+
+export function Claim({ offerId }: { offerId: string }) {
+  // 父级在平台身份就绪后挂载；身份变化时重新挂载此子树。
+  const client = useMemo(() => createManagedConcurrencyClient(), []);
+  const command = useManagedCommand({ client, command: 'claim',
+    input: { id: offerId }, storageKey: offerId });
+  return <>
+    <button disabled={command.state !== 'idle'}
+      onClick={() => void command.start().catch(() => {})}>申请</button>
+    <ManagedCommandStatus snapshot={command} />
+    {command.state === 'error' && <button
+      onClick={() => void command.resume().catch(() => {})}>恢复原操作</button>}
+  </>;
+}
+```
+
+挂载只恢复已有请求，用户调用 `start()` 才创建新意图。默认以 `sessionStorage` 保存原请求键及恢复资料，刷新后继续查原结果；浏览器禁止存储时明确失败，不自动改用易丢失的内存状态。可传入同接口的可靠存储。不要另写循环换请求键重试。
+
+等待阶段只轮询签名票据，不重复查业务数据。SDK 遵守建议间隔并加抖动，故障时逐步退避至约 30 秒。组件卸载或 `stop()` 只停止观察，不取消已受理命令。取消使用 `cancel()`，会核对原命令并处理与受理竞争的情况。只有已知终态才能 `clear()` 开始新意图。
+
+需要先排队再加载重型页面时，设置 `autoAccept: false`，用 `ManagedCommandGate` 的 `children={() => <HeavyContent />}` 延迟构建子树；用户确认后调用 `submit()`。命令输入在排队时固定。它不替代整站认证、应用启动元数据或未使用此能力的接口预算，也不能保护提前在父组件发起的请求。
+
+| 状态 | 含义 |
+| --- | --- |
+| `waiting` / `admitted` | 等待/获准受理，尚未占名额 |
+| `accepted` / `executing` / `retry_wait` | 已持久受理，平台继续处理 |
+| `succeeded` | 权威事务已提交，原结果可恢复 |
+| `rejected` / `expired` / `cancelled` | 明确终态 |
+| `recovering` / `error` | 正在核对/暂时无法确认，保留原请求键 |
+
+## 配额和发布边界
+
+立即分配用 `quota.action: 'allocate', mode: 'committed'`；需要预占时声明 `reservationSeconds` 并用 `mode: 'reserved'`。另声明 `confirm`、`release` 命令，绑定原 `allocation`，该命令的 `operations` 为空。只有原主体可确认/释放；到期与确认竞争使用数据库时间及固定锁顺序。
+
+原命令回执不可变。预占之后到期或释放，应调用 `client.allocation(allocationId)` 获取当前分配状态，不能用旧成功回执证明仍持有名额。首版同一池/主体保留永久去重事实，释放后不会自动重新报名；应用若需要新一轮，应使用新的权威资源/配额池，不能删除历史分配。
+
+容量减少不能低于已预占加已确认数量。存在配额历史时，禁止删除来源、改写分配引用或发布移除配额映射的版本。应用激活先排空所有非终态命令；不会让旧任务在新 Head 上执行。连接开发消费已激活测试版本的并发声明，未激活的本地模型覆盖层不能作为持久命令契约。
+
+## 资源上限与故障处理
+
+| 边界 | 首版硬上限 |
+| --- | --- |
+| 每应用/环境等待 | 128 个资源队列、合计 10000 人，同时受声明的更小上限约束 |
+| 缓存 | 单值 256 KiB；应用/环境累计 32 MiB、2048 个有效键；进程 L1 最多 256 个条目 |
+| 回源 | 每进程 2 个、每应用跨副本 2 个；应用合计 20 次/秒并受声明预算限制 |
+| HTTP | 并发能力普通入口每进程 8 个，查原结果独立 4 个 |
+| worker | 每进程最多 2 个，同一资源通过数据库事务锁协调 |
+
+Redis 不可用会停止新准入和缓存回源，绝不把所有请求直接放到数据库。已持久受理命令依赖 PostgreSQL 和现有 RabbitMQ 恢复；原结果在 Redis 故障时每进程最多 4 次/秒、4 个并发可回查。Redis 丢失会重建在途事实并换票据世代，临时等待位置可能变化。
+
+RabbitMQ 的消息只是唤醒提示；队列丢失或发布失败由数据库恢复，重复消息读取同一命令。锁等待或慢执行触发有界重试与应用短暂暂停放行。系统并不承诺跨队列严格公平，也不承诺一旦排队就必定获票。
+
+管理员可使用同源 POST `/openxiangda-api/v2/applications/:appCode/native/concurrency/status`，请求带 `environmentKey`，查看非终态数量/最早时间、最多 100 个配额池及当前进程缓存指标。`control` 接收 `{ environmentKey, paused: true }` 停止新受理；只允许应用超级管理员。停用或回滚前停止受理、排空命令、保留配额与原结果；不得通过删锁、删队列数据补偿业务。
+
+暂停/恢复按同一个环境锁串行传播；Redis 不可用时控制接口明确报错。控制值是绝对值，可以使用相同 `paused` 重试并核对状态。数据库提交确认丢失时不猜测控制结果；受理始终复查数据库的暂停状态。
+
+验证应包括内容 SQL 与授权 SQL 占比、每秒完成数、P95/P99、最老等待、连接数、锁等待和恢复时间。仓库故障测试证明协议边界，不代表任何客户环境的生产吞吐。部署者仍需使用目标硬件、真实权限和活动规模做容量验收。

package/documentation/manifest.json

@@ -1,12 +1,12 @@
 {
   "schemaVersion": "openxiangda.documentation/v1",
-  "version": "2.29.2",
+  "version": "2.31.0",
   "topics": [
     {
       "id": "getting-started",
       "title": "安装与开始开发",
       "file": "getting-started.md",
-      "sha256": "52478a53c36ad201febeed762cad6a15febf0243ca207cab7e3d62babe25aea5"
+      "sha256": "c0361a31b8072107d1b3ad241dd69f4396d6900494368200236a41e05dbcdf96"
     },
     {
       "id": "product-design",
@@ -72,7 +72,7 @@
       "id": "data-authz",
       "title": "数据查询与权限",
       "file": "data-authz.md",
-      "sha256": "f00c0dcd79c1ccf9ded0b3131ad304b671cebf475cf1ea20404da665dc2c0bb6"
+      "sha256": "b35904b721bcd837c3a26cdf91ef9514c82c87bd517c35572b84ee2a90c5a89f"
     },
     {
       "id": "public-access",
@@ -98,6 +98,12 @@
       "file": "decimal-reservations.md",
       "sha256": "cdbc0bfff79c9bf71b88f5f50a5b76e4de77bae92e590ce08f32662621c1ff7d"
     },
+    {
+      "id": "managed-concurrency",
+      "title": "缓存、排队与整数配额",
+      "file": "managed-concurrency.md",
+      "sha256": "35de92be341f1bdac843725b59bd7794cd4defdcc044bfd9ce09706b4fcf2582"
+    },
     {
       "id": "administration",
       "title": "应用管理与有效配置",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openxiangda",
-  "version": "2.29.2",
+  "version": "2.31.0",
   "description": "OpenXiangda 2.0 的统一命令、应用 SDK、MCP 与中文 AI 技能资料。",
   "type": "module",
   "main": "./dist/index.js",
@@ -60,13 +60,13 @@
     "antd-mobile": "5.42.3",
     "dayjs": "1.11.18",
     "docx-preview": "0.3.7",
-    "openxiangda-cli": "2.6.0",
-    "openxiangda-contracts": "2.26.0",
-    "openxiangda-devkit-core": "2.29.0",
+    "openxiangda-cli": "2.6.2",
+    "openxiangda-contracts": "2.28.0",
+    "openxiangda-devkit-core": "2.31.0",
     "openxiangda-legacy": "npm:openxiangda@1.0.269",
-    "openxiangda-mcp": "2.0.50",
-    "openxiangda-nest": "2.7.3",
-    "openxiangda-skill-kit": "2.3.24",
+    "openxiangda-mcp": "2.0.52",
+    "openxiangda-nest": "2.7.5",
+    "openxiangda-skill-kit": "2.3.26",
     "xlsx": "https://github.com/1377385356/openxiangda/releases/download/vendor-mirror/xlsx-0.20.3.tgz"
   },
   "peerDependencies": {
@@ -132,35 +132,42 @@
   },
   "openxiangdaRelease": {
     "schemaVersion": "openxiangda.release-notes/v1",
-    "version": "2.29.2",
+    "version": "2.31.0",
     "status": "reviewed",
-    "title": "OpenXiangda 2.29.2：退役 Studio 专属工具链",
-    "summary": "移除已停止维护的 Studio 初始化、发现与绑定接口，保留普通应用创建、连接开发、源码托管和结构化命令输出。",
-    "newFeatures": [],
-    "fixes": [
-      "CLI 不再接受 Studio Project/ProvisioningRun 初始化参数，能力发现不再输出 toolchain.studio。",
-      "通用 JSON/JSONL 事件和模板摘要绑定使用独立 CLI 契约，不再依赖已退役产品。"
+    "title": "OpenXiangda 2.31.0：缓存、排队与原子配额",
+    "summary": "应用可声明热点内容缓存、全局准入、可恢复的 Native 命令和整数配额。平台承担回源保护、受理幂等与事务内分配，React 和移动端 SDK 提供等待、提交及原结果恢复。",
+    "newFeatures": [
+      "data.concurrency 由两端共享编译器验证，缓存读取声明包含权限范围、有限参数、失效依赖和回源预算。",
+      "等待准入按可信主体合并重复请求，持久命令返回原操作回执，响应丢失和页面刷新后可继续核对结果。",
+      "整数配额支持立即分配、预占、确认、释放与到期；配额、业务记录、事件和结果在同一 Native 事务提交，受管模型阻止普通 CRUD 绕过。",
+      "openxiangda/react 和 openxiangda/mobile 提供 createManagedConcurrencyClient、useManagedCommand、ManagedCommandStatus 与 ManagedCommandGate。"
     ],
+    "fixes": [],
     "affectedUsers": [
-      "使用 OpenXiangda 2.0 工具链的开发者；仍调用 Studio 专属参数或导出的集成需要移除这些调用。"
+      "需要缓存、排队、限量申领、预约或抢票的 OpenXiangda 2.0 应用开发者。"
     ],
     "upgradeSteps": [
-      "更新到 openxiangda@2.29.2 并更新项目锁文件；使用普通 create、dev 和发布流程。",
-      "移除 Studio 专属参数与导出。平台端退役部署须独立完成临时 Git 凭据撤权检查，不能仅凭 SDK 升级判定现场退役完成。"
+      "升级到 openxiangda@2.31.0 并更新锁文件，按 docs/managed-concurrency.md 及完整声明示例配置资源和权限。",
+      "先确认目标平台已部署 data.managed-concurrency@1.0.0 及对应 SQL migration，再激活测试版本。未启用此声明的应用沿用原路径。",
+      "上线前按目标硬件、真实权限和业务规模验证完成速率、P95/P99、回源 SQL、锁等待及恢复时间；部署和容量验收独立于 npm 发行。",
+      "停用或切换不兼容版本前停止新受理并排空非终态命令，保留历史命令、分配及回执。"
     ],
     "knownLimitations": [
-      "已退役的 Studio 专属导出和参数不再兼容。",
-      "本次发行不包含新的平台 Agent 运行时，不自动部署平台或应用。"
+      "首版执行编译后的 Native 原子动作，不把任意 JS、SQL 或第三方调用纳入原子事务。",
+      "Redis 故障时暂停新准入和缓存回源；临时等待位置不承诺持久，已持久受理命令可恢复。",
+      "缓存减少内容 SQL，当前身份和权限链路仍有数据库访问；不提供公共 CDN 发布或自动全量预热。",
+      "同一配额池和主体永久去重，释放后不会自动重新报名；新一轮业务使用新的权威资源或配额池。",
+      "资源保护上限不代表生产吞吐保证；公开包升级不会自动升级客户平台。"
     ],
     "issues": [],
     "compatibility": {
       "node": ">=24",
       "workspaceGenerations": "v2",
-      "platform": "普通应用开发和共享源码托管契约保持；平台退役按独立部署前置条件执行。",
+      "platform": "声明并发能力时要求 data.managed-concurrency@1.0.0；同时声明业务唯一键时还要求 data.unique-keys@1.0.0。",
       "v1": "独立 V1 引擎和工作区不受影响。"
     },
-    "sha256": "5c26d50635ca43152e96c0017a9948f5c44cbfd8aff926cc4ff0da8971a3c49c",
-    "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.29.2"
+    "sha256": "6258bae64bad0db43a319ecb6886a037952e0c77410edd6a790d18b8cd470645",
+    "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.31.0"
   },
   "scripts": {
     "build": "node ../../scripts/prune-package-dist.mjs && tsc -p tsconfig.json && node scripts/copy-assets.mjs",

package/releases/2.30.0.json

@@ -0,0 +1,34 @@
+{
+  "schemaVersion": "openxiangda.release-notes/v1",
+  "version": "2.30.0",
+  "status": "reviewed",
+  "title": "OpenXiangda 2.30.0：平台条件唯一键",
+  "summary": "模型可声明条件唯一键，统一约束普通 CRUD、导入和业务事务；编译器在发布前检查规则并识别目标平台是否支持。",
+  "newFeatures": [
+    "模型与数据资源支持有界 uniqueKeys 声明，可选择精确比较、NFKC 空白折叠或 ASCII 大写，并按文本空值或单选集合限定参与记录。",
+    "两端编译器、JSON Schema、声明诊断和能力清单使用一致契约，自动要求 data.unique-keys@1.0.0。未声明的模型不增加能力要求。"
+  ],
+  "fixes": [],
+  "affectedUsers": [
+    "需要跨并发写入保障业务编号或复合字段唯一性的 OpenXiangda 2.0 应用开发者。"
+  ],
+  "upgradeSteps": [
+    "更新到 openxiangda@2.30.0 并更新锁文件；在需要唯一性的模型声明 uniqueKeys，使用当前版本的数据与权限文档。",
+    "先确认目标平台实际提供 data.unique-keys@1.0.0，再激活测试版本。历史重复或超长数据会明确拒绝激活并保留原环境。",
+    "重复写入处理 HTTP 409 和规则标识；长度超限处理 HTTP 422。避免盲目重试创建，事务失败后按原业务状态恢复。"
+  ],
+  "knownLimitations": [
+    "每资源最多 8 条、每条 1–4 个键字段和最多 4 个 AND 条件；参与比较字段归一化后最多 256 个 UTF-8 字节。",
+    "已有规则的修改、删除和所用字段替换需要平台受管迁移；连接开发不能私自改变规则。",
+    "平台升级与 SDK 发行分别验收；npm 发行不代表客户节点已经上线。跨 PostgreSQL 大版本变更须先安排归一化索引的受管重建。"
+  ],
+  "issues": [],
+  "compatibility": {
+    "node": ">=24",
+    "workspaceGenerations": "v2",
+    "platform": "声明规则时要求 data.unique-keys@1.0.0；普通应用沿用现有能力。",
+    "v1": "独立 V1 引擎和工作区不受影响。"
+  },
+  "sha256": "cbe1a5766e0cc0d8948d54b6d2129320b5d2fbe1e8f7120874b9f56c774b1fcb",
+  "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.30.0"
+}

package/releases/2.31.0.json

@@ -0,0 +1,39 @@
+{
+  "schemaVersion": "openxiangda.release-notes/v1",
+  "version": "2.31.0",
+  "status": "reviewed",
+  "title": "OpenXiangda 2.31.0：缓存、排队与原子配额",
+  "summary": "应用可声明热点内容缓存、全局准入、可恢复的 Native 命令和整数配额。平台承担回源保护、受理幂等与事务内分配，React 和移动端 SDK 提供等待、提交及原结果恢复。",
+  "newFeatures": [
+    "data.concurrency 由两端共享编译器验证，缓存读取声明包含权限范围、有限参数、失效依赖和回源预算。",
+    "等待准入按可信主体合并重复请求，持久命令返回原操作回执，响应丢失和页面刷新后可继续核对结果。",
+    "整数配额支持立即分配、预占、确认、释放与到期；配额、业务记录、事件和结果在同一 Native 事务提交，受管模型阻止普通 CRUD 绕过。",
+    "openxiangda/react 和 openxiangda/mobile 提供 createManagedConcurrencyClient、useManagedCommand、ManagedCommandStatus 与 ManagedCommandGate。"
+  ],
+  "fixes": [],
+  "affectedUsers": [
+    "需要缓存、排队、限量申领、预约或抢票的 OpenXiangda 2.0 应用开发者。"
+  ],
+  "upgradeSteps": [
+    "升级到 openxiangda@2.31.0 并更新锁文件，按 docs/managed-concurrency.md 及完整声明示例配置资源和权限。",
+    "先确认目标平台已部署 data.managed-concurrency@1.0.0 及对应 SQL migration，再激活测试版本。未启用此声明的应用沿用原路径。",
+    "上线前按目标硬件、真实权限和业务规模验证完成速率、P95/P99、回源 SQL、锁等待及恢复时间；部署和容量验收独立于 npm 发行。",
+    "停用或切换不兼容版本前停止新受理并排空非终态命令，保留历史命令、分配及回执。"
+  ],
+  "knownLimitations": [
+    "首版执行编译后的 Native 原子动作，不把任意 JS、SQL 或第三方调用纳入原子事务。",
+    "Redis 故障时暂停新准入和缓存回源；临时等待位置不承诺持久，已持久受理命令可恢复。",
+    "缓存减少内容 SQL，当前身份和权限链路仍有数据库访问；不提供公共 CDN 发布或自动全量预热。",
+    "同一配额池和主体永久去重，释放后不会自动重新报名；新一轮业务使用新的权威资源或配额池。",
+    "资源保护上限不代表生产吞吐保证；公开包升级不会自动升级客户平台。"
+  ],
+  "issues": [],
+  "compatibility": {
+    "node": ">=24",
+    "workspaceGenerations": "v2",
+    "platform": "声明并发能力时要求 data.managed-concurrency@1.0.0；同时声明业务唯一键时还要求 data.unique-keys@1.0.0。",
+    "v1": "独立 V1 引擎和工作区不受影响。"
+  },
+  "sha256": "6258bae64bad0db43a319ecb6886a037952e0c77410edd6a790d18b8cd470645",
+  "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.31.0"
+}

package/skills/manifest.json

@@ -4,7 +4,7 @@
     {
       "name": "openxiangda-v2",
       "description": "使用 OpenXiangda 2.0 从模糊业务想法、已有资料或具体变更出发，通过对话发现模块、完成详细产品设计，由当前 AI Agent 按需用 Image 2.5 等图片能力形成视觉参考，直接实现真实页面并在浏览器修正，再检查和交付应用；维护 1.x 应用时使用对应的 1.x 技能。",
-      "sha256": "95e3963dae0247fd88878e22e4ed39f0bd37fd0462e9efaba39b1bd8410b3d99"
+      "sha256": "21818bd1f22b3be7ce899c8d4b2088d64e0ad4cd056506afbbc705ea4a0c9b72"
     }
   ]
 }

package/skills/openxiangda-v2/SKILL.md

@@ -40,10 +40,10 @@ AI 接到新应用、页面或改版任务时，在同一个 OpenXiangda 工作
 未创建工作区时使用本 Skill 随根包发布的精确版本：
 
 ```bash
-pnpm dlx openxiangda@2.29.2 auth status --cwd <应用目录> --base-url <平台地址> --json
-pnpm dlx openxiangda@2.29.2 login --cwd <应用目录> --base-url <平台地址>
-pnpm dlx openxiangda@2.29.2 create <应用目录> --base-url <同一平台地址>
-pnpm dlx openxiangda@2.29.2 skill install --force
+pnpm dlx openxiangda@2.31.0 auth status --cwd <应用目录> --base-url <平台地址> --json
+pnpm dlx openxiangda@2.31.0 login --cwd <应用目录> --base-url <平台地址>
+pnpm dlx openxiangda@2.31.0 create <应用目录> --base-url <同一平台地址>
+pnpm dlx openxiangda@2.31.0 skill install --force
 ```
 
 创建前把产品要求的目标平台明确带入命令，不从旧登录态推断站点。已有工作区从原绑定恢复，平台不一致时先解决登录与目标，不改 link 文件跨站创建。
@@ -72,6 +72,7 @@ pnpm dlx openxiangda@2.29.2 skill install --force
 | 审批、待办、消息或事件 | [工作流与通知](references/workflow-events.md) |
 | 自定义事务、校验或外部集成 | [按需后端](references/backend.md) |
 | 主子额度、审批占用释放、撤回修订重提 | [精确金额占用](references/decimal-reservations.md) |
+| 热点读取、抢票、排队、名额预占与原结果恢复 | [缓存、排队与配额](references/managed-concurrency.md) |
 | 管理成员或查看有效流程参数 | [应用管理](references/administration.md) |
 | 检查、部署、生产发布与故障恢复 | [验收](references/testing.md)、[交付](references/delivery.md) |
 | 需求记录与版本升级 | [全流程记录](references/appspec.md)、[升级](references/upgrading.md) |

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

@@ -29,6 +29,61 @@ pnpm openxiangda check
 
 角色成员、维度授权和平台管理员由平台管理面维护，不属于应用开发 CLI。
 
+### 条件唯一键
+
+需要“同一编号只能有一条有效主档”时，在模型声明 `uniqueKeys`。平台在环境
+激活时安装约束；普通 CRUD、导入和业务事务共用该约束。应用无需先查重再创建，
+也无需另建锁服务。声明会自动要求平台能力 `data.unique-keys@1.0.0`，旧平台在
+发布前明确报告缺少能力。未声明的模型不增加这一要求。
+
+```ts
+const partners = defineDataModel({
+  code: 'partners', name: '往来单位',
+  fields: [
+    { code: 'externalId', label: '外部编号', type: 'text.short' },
+    { code: 'name', label: '名称', type: 'text.short' },
+    { code: 'state', label: '状态', type: 'option.single', options: [
+      { value: 'active', label: '有效' }, { value: 'void', label: '作废' },
+    ] },
+  ],
+  uniqueKeys: [{
+    code: 'active-external-id',
+    fields: [{ fieldCode: 'externalId', normalizer: 'nfkc-upper-ascii-v1' }],
+    when: [{ fieldCode: 'state', operator: 'in', values: ['active'] }],
+  }],
+});
+```
+
+规则只比较同一租户、应用与环境内的记录。上例中 `ＡＢＣ` 和 `abc` 视为相同
+编号，只有 `active` 记录参与；切换状态进入比较集合时也执行约束。平台不会猜测
+业务中的有效、作废或软删除语义，条件由应用声明。
+
+- 每模型最多 8 条，稳定 `code` 使用最长 20 字符的 lower-kebab-case；每条包含
+  1–4 个不重复字段、最多 4 个 AND 条件。
+- 字段支持短文本、UUID、单选和单记录引用；单选/引用比较保存的 `value`，忽略标签。
+- `exact-v1` 原样比较（默认）；文本可用 `nfkc-space-v1` 做 NFKC 归一化、Unicode
+  空白折叠和首尾修剪，或 `nfkc-upper-ascii-v1` 再将 ASCII 小写转大写。非文本只
+  支持 exact；不按操作系统 locale 折叠其他文字大小写。
+- 文本条件是 `empty` / `nonempty`，按 NFKC 空白规则判断；单选条件是 `in` /
+  `notIn`，包含 1–16 个已声明选项值。缺失选项不满足 `notIn`。
+- 任一键字段为空或归一化后为空，该行不参加比较。需要每行填写时仍应声明字段
+  必填。参与比较的每个字段归一化后最多 256 个 UTF-8 字节。
+
+重复写入返回 HTTP 409 `OPENXIANGDA_NATIVE_DATA_RESOURCE_UNIQUE_CONFLICT`，并给出
+`resourceCode`、`ruleCode`；不会泄露其他记录 ID、值或原始 SQL。界面应让用户核实
+输入并复用自己有权访问的记录，不自动重试创建。超长返回 HTTP 422
+`OPENXIANGDA_NATIVE_DATA_RESOURCE_UNIQUE_VALUE_TOO_LONG`。事务中的任何操作失败，
+该事务的记录、事件及回执整体回滚。
+
+首次启用会检查历史数据。发现重复或超长时，激活失败且原环境 Head 保持；平台
+不会自动合并、改名或删除数据。已有规则可原样保留或新增规则，修改/移除规则、
+替换其字段类型或删除所用字段需要平台受管迁移。连接开发仍可添加普通字段，但
+规则变化会要求先正式激活测试版本。回滚到旧模型时也应保留已经安装的规则。
+
+平台为安装设置有界锁等待与扫描预算，超时不会留下部分约束。归一化依赖数据库
+版本；跨 PostgreSQL 大版本升级由平台安排受管重建，不能由应用绕过规则或重试
+写入来修复。
+
 ### 授权来源声明
 
 应用可以在 `authz` 中声明四类授权来源，让平台从业务数据投影出维度授权、应用角色成员和

package/skills/openxiangda-v2/references/getting-started.md

@@ -68,10 +68,10 @@ MCP 服务随项目根包一起安装，AI 客户端的 stdio 连接仍需配置
 以下命令的版本占位符由随包资料替换为该根包的精确版本。网站源码阅读者应先确认要使用的发行版本。
 
 ```bash
-pnpm dlx openxiangda@2.29.2 skill install --force
-pnpm dlx openxiangda@2.29.2 auth status --base-url <平台地址> --json
-pnpm dlx openxiangda@2.29.2 login --cwd my-app --base-url https://platform.example.com
-pnpm dlx openxiangda@2.29.2 create my-app --base-url https://platform.example.com
+pnpm dlx openxiangda@2.31.0 skill install --force
+pnpm dlx openxiangda@2.31.0 auth status --base-url <平台地址> --json
+pnpm dlx openxiangda@2.31.0 login --cwd my-app --base-url https://platform.example.com
+pnpm dlx openxiangda@2.31.0 create my-app --base-url https://platform.example.com
 cd my-app
 pnpm openxiangda context --json
 pnpm openxiangda dev
@@ -174,9 +174,9 @@ MCP 的 `docs_read` 可以读取本说明，当前没有独立的源码操作 MC
 无需本地工作区，使用本 Skill 随包精确版本或已安装的对应 CLI：
 
 ```bash
-pnpm dlx openxiangda@2.29.2 auth status --base-url <平台> --json
-pnpm dlx openxiangda@2.29.2 source resolve <仓库URL> --base-url <平台> --json
-pnpm dlx openxiangda@2.29.2 source clone <仓库URL> <新目录> --base-url <平台> --json
+pnpm dlx openxiangda@2.31.0 auth status --base-url <平台> --json
+pnpm dlx openxiangda@2.31.0 source resolve <仓库URL> --base-url <平台> --json
+pnpm dlx openxiangda@2.31.0 source clone <仓库URL> <新目录> --base-url <平台> --json
 ```
 
 登录缺失或站点不匹配时，先按该平台执行 login。resolve 根据平台已经登记的绑定返回

package/skills/openxiangda-v2/references/managed-concurrency.md

@@ -0,0 +1,98 @@
+# 缓存、排队与整数配额
+
+`data.concurrency` 是可选的平台声明，用于限量申领、抢票和预约。平台负责缓存回源、等待资格、持久受理、受控 Native 事务及整数配额；应用通过 `openxiangda/react` 或 `openxiangda/mobile` 调用。平台必须声明能力 `data.managed-concurrency@1.0.0`。旧平台会在编译/发布能力检查阶段拒绝此声明。
+
+## 声明与权限
+
+完整且由双编译器测试验证的示例位于源码 `examples/managed-concurrency/declaration.ts`。调用 `defineOpenXiangdaApp(concurrencyExample())` 即可编译。把示例中的 `data.concurrency` 合入应用配置，并按实际业务配置模型和参与权限。
+
+| 声明 | 作用 |
+| --- | --- |
+| `reads` | 命名读取、有限参数、字段、条件、权限范围、新鲜期、旧值期限、失效字段和回源预算 |
+| `admission` | 本应用/环境所有命令共享的每秒速率、突发额度、在途上限 |
+| `commands` | 当前用户的能力、按资源分队列、最长等待、处理截止、Native 守卫和原子写入 |
+| `quotas` | 容量来源、业务记录上的分配 ID、可选的预占到期时间 |
+
+参数限于 UUID、有限字符串枚举和有限整数范围；绑定只接受 `input`、可信 `actor`、字面量和平台生成的 `allocation`。每个命令最多 8 个操作、8 个记录守卫。首版不执行应用任意 JS/SQL，也不在锁内调用外部系统。通知和外部副作用接已有事务后事件。
+
+配额来源模型的容量字段必须是整数；分配记录模型的引用字段必须是必填 UUID，模型设置 `mutationOwner: 'queued-command'`。角色仍须具备来源读取、分配模型创建和命令能力。普通 CRUD、导入、应用凭据均不能绕过命令所有权。用户身份由 `actor` 绑定，不能使用用户填写的人员编号决定名额归属。
+
+`database-now` 条件使用数据库时间，并按“字段 操作符 当前时间”解释。例如截止前允许报名：`{ kind: 'database-now', field: 'closesAt', operator: 'gt' }`。资格和业务截止在执行时重验，因此等待或已受理不等于一定成功。
+
+## 展示读取
+
+```ts
+const client = createManagedConcurrencyClient();
+const snapshot = await client.read('offer', { id: selectedOfferId });
+// snapshot.items、generatedAt、freshUntil、staleUntil、version、freshness
+```
+
+在平台身份初始化完成后创建并保持 `client` 实例稳定。它绑定应用、环境和当前用户；切换身份后旧客户端拒绝继续操作。组织内共享内容也要求登录与当前权限。`scope: 'application'` 不允许行策略或 actor 条件；个人/有行策略的数据使用 `scope: 'subject'`。
+
+每次访问仍通过平台现有身份、版本与字段权限链路。缓存减少内容查询；不能据此宣称整个请求零 SQL。活动内容和余量使用不同读取声明与依赖，避免每次报名使详情失效。`dependencies` 必须覆盖返回和过滤字段。Native 提交在同一事务写失效事实，恢复任务负责可靠推进；变更传播有延迟，要求即时资格或即时关闭的判断必须放在命令守卫中。
+
+冷缓存使用进程请求合并与跨副本刷新租约，短暂争用返回可重试响应。负缓存最长 5 秒，TTL 带随机抖动。可在应用版本激活后，用正常授权的 `read` 调用预热有限的热点 ID。首版提供认证后的 Redis/进程缓存，不提供公共 CDN 发布或自动扫描全量数据预热。
+
+## 提交与原结果恢复
+
+```tsx
+import { useMemo } from 'react';
+import { createManagedConcurrencyClient, useManagedCommand,
+  ManagedCommandStatus } from 'openxiangda/react';
+
+export function Claim({ offerId }: { offerId: string }) {
+  // 父级在平台身份就绪后挂载；身份变化时重新挂载此子树。
+  const client = useMemo(() => createManagedConcurrencyClient(), []);
+  const command = useManagedCommand({ client, command: 'claim',
+    input: { id: offerId }, storageKey: offerId });
+  return <>
+    <button disabled={command.state !== 'idle'}
+      onClick={() => void command.start().catch(() => {})}>申请</button>
+    <ManagedCommandStatus snapshot={command} />
+    {command.state === 'error' && <button
+      onClick={() => void command.resume().catch(() => {})}>恢复原操作</button>}
+  </>;
+}
+```
+
+挂载只恢复已有请求，用户调用 `start()` 才创建新意图。默认以 `sessionStorage` 保存原请求键及恢复资料，刷新后继续查原结果；浏览器禁止存储时明确失败，不自动改用易丢失的内存状态。可传入同接口的可靠存储。不要另写循环换请求键重试。
+
+等待阶段只轮询签名票据，不重复查业务数据。SDK 遵守建议间隔并加抖动，故障时逐步退避至约 30 秒。组件卸载或 `stop()` 只停止观察，不取消已受理命令。取消使用 `cancel()`，会核对原命令并处理与受理竞争的情况。只有已知终态才能 `clear()` 开始新意图。
+
+需要先排队再加载重型页面时，设置 `autoAccept: false`，用 `ManagedCommandGate` 的 `children={() => <HeavyContent />}` 延迟构建子树；用户确认后调用 `submit()`。命令输入在排队时固定。它不替代整站认证、应用启动元数据或未使用此能力的接口预算，也不能保护提前在父组件发起的请求。
+
+| 状态 | 含义 |
+| --- | --- |
+| `waiting` / `admitted` | 等待/获准受理，尚未占名额 |
+| `accepted` / `executing` / `retry_wait` | 已持久受理，平台继续处理 |
+| `succeeded` | 权威事务已提交，原结果可恢复 |
+| `rejected` / `expired` / `cancelled` | 明确终态 |
+| `recovering` / `error` | 正在核对/暂时无法确认，保留原请求键 |
+
+## 配额和发布边界
+
+立即分配用 `quota.action: 'allocate', mode: 'committed'`；需要预占时声明 `reservationSeconds` 并用 `mode: 'reserved'`。另声明 `confirm`、`release` 命令，绑定原 `allocation`，该命令的 `operations` 为空。只有原主体可确认/释放；到期与确认竞争使用数据库时间及固定锁顺序。
+
+原命令回执不可变。预占之后到期或释放，应调用 `client.allocation(allocationId)` 获取当前分配状态，不能用旧成功回执证明仍持有名额。首版同一池/主体保留永久去重事实，释放后不会自动重新报名；应用若需要新一轮，应使用新的权威资源/配额池，不能删除历史分配。
+
+容量减少不能低于已预占加已确认数量。存在配额历史时，禁止删除来源、改写分配引用或发布移除配额映射的版本。应用激活先排空所有非终态命令；不会让旧任务在新 Head 上执行。连接开发消费已激活测试版本的并发声明，未激活的本地模型覆盖层不能作为持久命令契约。
+
+## 资源上限与故障处理
+
+| 边界 | 首版硬上限 |
+| --- | --- |
+| 每应用/环境等待 | 128 个资源队列、合计 10000 人，同时受声明的更小上限约束 |
+| 缓存 | 单值 256 KiB；应用/环境累计 32 MiB、2048 个有效键；进程 L1 最多 256 个条目 |
+| 回源 | 每进程 2 个、每应用跨副本 2 个；应用合计 20 次/秒并受声明预算限制 |
+| HTTP | 并发能力普通入口每进程 8 个，查原结果独立 4 个 |
+| worker | 每进程最多 2 个，同一资源通过数据库事务锁协调 |
+
+Redis 不可用会停止新准入和缓存回源，绝不把所有请求直接放到数据库。已持久受理命令依赖 PostgreSQL 和现有 RabbitMQ 恢复；原结果在 Redis 故障时每进程最多 4 次/秒、4 个并发可回查。Redis 丢失会重建在途事实并换票据世代，临时等待位置可能变化。
+
+RabbitMQ 的消息只是唤醒提示；队列丢失或发布失败由数据库恢复，重复消息读取同一命令。锁等待或慢执行触发有界重试与应用短暂暂停放行。系统并不承诺跨队列严格公平，也不承诺一旦排队就必定获票。
+
+管理员可使用同源 POST `/openxiangda-api/v2/applications/:appCode/native/concurrency/status`，请求带 `environmentKey`，查看非终态数量/最早时间、最多 100 个配额池及当前进程缓存指标。`control` 接收 `{ environmentKey, paused: true }` 停止新受理；只允许应用超级管理员。停用或回滚前停止受理、排空命令、保留配额与原结果；不得通过删锁、删队列数据补偿业务。
+
+暂停/恢复按同一个环境锁串行传播；Redis 不可用时控制接口明确报错。控制值是绝对值，可以使用相同 `paused` 重试并核对状态。数据库提交确认丢失时不猜测控制结果；受理始终复查数据库的暂停状态。
+
+验证应包括内容 SQL 与授权 SQL 占比、每秒完成数、P95/P99、最老等待、连接数、锁等待和恢复时间。仓库故障测试证明协议边界，不代表任何客户环境的生产吞吐。部署者仍需使用目标硬件、真实权限和活动规模做容量验收。