openxiangda 2.29.2 → 2.30.0

package/documentation/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/documentation/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.30.0 skill install --force
+pnpm dlx openxiangda@2.30.0 auth status --base-url <平台地址> --json
+pnpm dlx openxiangda@2.30.0 login --cwd my-app --base-url https://platform.example.com
+pnpm dlx openxiangda@2.30.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.30.0 auth status --base-url <平台> --json
+pnpm dlx openxiangda@2.30.0 source resolve <仓库URL> --base-url <平台> --json
+pnpm dlx openxiangda@2.30.0 source clone <仓库URL> <新目录> --base-url <平台> --json
 ```
 
 登录缺失或站点不匹配时，先按该平台执行 login。resolve 根据平台已经登记的绑定返回

package/documentation/manifest.json

@@ -1,12 +1,12 @@
 {
   "schemaVersion": "openxiangda.documentation/v1",
-  "version": "2.29.2",
+  "version": "2.30.0",
   "topics": [
     {
       "id": "getting-started",
       "title": "安装与开始开发",
       "file": "getting-started.md",
-      "sha256": "52478a53c36ad201febeed762cad6a15febf0243ca207cab7e3d62babe25aea5"
+      "sha256": "53c29676a178d4f9b0e656196cca8b6ac01461677ff9772e1c386fbaf67d2198"
     },
     {
       "id": "product-design",
@@ -72,7 +72,7 @@
       "id": "data-authz",
       "title": "数据查询与权限",
       "file": "data-authz.md",
-      "sha256": "f00c0dcd79c1ccf9ded0b3131ad304b671cebf475cf1ea20404da665dc2c0bb6"
+      "sha256": "b35904b721bcd837c3a26cdf91ef9514c82c87bd517c35572b84ee2a90c5a89f"
     },
     {
       "id": "public-access",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openxiangda",
-  "version": "2.29.2",
+  "version": "2.30.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.1",
+    "openxiangda-contracts": "2.27.0",
+    "openxiangda-devkit-core": "2.30.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.51",
+    "openxiangda-nest": "2.7.4",
+    "openxiangda-skill-kit": "2.3.25",
     "xlsx": "https://github.com/1377385356/openxiangda/releases/download/vendor-mirror/xlsx-0.20.3.tgz"
   },
   "peerDependencies": {
@@ -132,35 +132,37 @@
   },
   "openxiangdaRelease": {
     "schemaVersion": "openxiangda.release-notes/v1",
-    "version": "2.29.2",
+    "version": "2.30.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.30.0：平台条件唯一键",
+    "summary": "模型可声明条件唯一键，统一约束普通 CRUD、导入和业务事务；编译器在发布前检查规则并识别目标平台是否支持。",
+    "newFeatures": [
+      "模型与数据资源支持有界 uniqueKeys 声明，可选择精确比较、NFKC 空白折叠或 ASCII 大写，并按文本空值或单选集合限定参与记录。",
+      "两端编译器、JSON Schema、声明诊断和能力清单使用一致契约，自动要求 data.unique-keys@1.0.0。未声明的模型不增加能力要求。"
     ],
+    "fixes": [],
     "affectedUsers": [
-      "使用 OpenXiangda 2.0 工具链的开发者；仍调用 Studio 专属参数或导出的集成需要移除这些调用。"
+      "需要跨并发写入保障业务编号或复合字段唯一性的 OpenXiangda 2.0 应用开发者。"
     ],
     "upgradeSteps": [
-      "更新到 openxiangda@2.29.2 并更新项目锁文件；使用普通 create、dev 和发布流程。",
-      "移除 Studio 专属参数与导出。平台端退役部署须独立完成临时 Git 凭据撤权检查，不能仅凭 SDK 升级判定现场退役完成。"
+      "更新到 openxiangda@2.30.0 并更新锁文件；在需要唯一性的模型声明 uniqueKeys，使用当前版本的数据与权限文档。",
+      "先确认目标平台实际提供 data.unique-keys@1.0.0，再激活测试版本。历史重复或超长数据会明确拒绝激活并保留原环境。",
+      "重复写入处理 HTTP 409 和规则标识；长度超限处理 HTTP 422。避免盲目重试创建，事务失败后按原业务状态恢复。"
     ],
     "knownLimitations": [
-      "已退役的 Studio 专属导出和参数不再兼容。",
-      "本次发行不包含新的平台 Agent 运行时，不自动部署平台或应用。"
+      "每资源最多 8 条、每条 1–4 个键字段和最多 4 个 AND 条件；参与比较字段归一化后最多 256 个 UTF-8 字节。",
+      "已有规则的修改、删除和所用字段替换需要平台受管迁移；连接开发不能私自改变规则。",
+      "平台升级与 SDK 发行分别验收；npm 发行不代表客户节点已经上线。跨 PostgreSQL 大版本变更须先安排归一化索引的受管重建。"
     ],
     "issues": [],
     "compatibility": {
       "node": ">=24",
       "workspaceGenerations": "v2",
-      "platform": "普通应用开发和共享源码托管契约保持；平台退役按独立部署前置条件执行。",
+      "platform": "声明规则时要求 data.unique-keys@1.0.0；普通应用沿用现有能力。",
       "v1": "独立 V1 引擎和工作区不受影响。"
     },
-    "sha256": "5c26d50635ca43152e96c0017a9948f5c44cbfd8aff926cc4ff0da8971a3c49c",
-    "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.29.2"
+    "sha256": "cbe1a5766e0cc0d8948d54b6d2129320b5d2fbe1e8f7120874b9f56c774b1fcb",
+    "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.30.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/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": "43362f7f5e18dbfbaba0909a8c78d1ee83effa8ffbb1089131b150da408974ad"
     }
   ]
 }

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.30.0 auth status --cwd <应用目录> --base-url <平台地址> --json
+pnpm dlx openxiangda@2.30.0 login --cwd <应用目录> --base-url <平台地址>
+pnpm dlx openxiangda@2.30.0 create <应用目录> --base-url <同一平台地址>
+pnpm dlx openxiangda@2.30.0 skill install --force
 ```
 
 创建前把产品要求的目标平台明确带入命令，不从旧登录态推断站点。已有工作区从原绑定恢复，平台不一致时先解决登录与目标，不改 link 文件跨站创建。

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.30.0 skill install --force
+pnpm dlx openxiangda@2.30.0 auth status --base-url <平台地址> --json
+pnpm dlx openxiangda@2.30.0 login --cwd my-app --base-url https://platform.example.com
+pnpm dlx openxiangda@2.30.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.30.0 auth status --base-url <平台> --json
+pnpm dlx openxiangda@2.30.0 source resolve <仓库URL> --base-url <平台> --json
+pnpm dlx openxiangda@2.30.0 source clone <仓库URL> <新目录> --base-url <平台> --json
 ```
 
 登录缺失或站点不匹配时，先按该平台执行 login。resolve 根据平台已经登记的绑定返回