openxiangda-skill-kit 2.3.127 → 2.3.129

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openxiangda-skill-kit",
-  "version": "2.3.127",
+  "version": "2.3.129",
   "description": "OpenXiangda 2.0 中文 AI 技能的校验、分发与安装。",
   "type": "module",
   "main": "./dist/index.js",
@@ -17,7 +17,7 @@
     "README.md"
   ],
   "dependencies": {
-    "openxiangda-devkit-core": "2.71.3"
+    "openxiangda-devkit-core": "2.71.4"
   },
   "devDependencies": {
     "tsx": "4.23.12",

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

@@ -165,15 +165,22 @@ Nest后端注入请求作用域的 `OpenXiangdaWorkflowService`，调用 `delega
 
 目录进入独立流程图地址，刷新及浏览器返回保留所查看流程/版本。共享组件按需加载 React Flow 与 ELK 正交布局：所有线段横平竖直、转角为直角；支持画布平移、滚轮缩放、适应全图、聚焦选中和缩略导航。分支标签可选中，详情保留完整条件、顺序和来源；窄屏采用同源节点列表，方向键/Home/End 定位节点。画布布局上限为 200 节点、1024 连线，不提供拖改、删除或连线编辑。
 
+`WorkflowDiagram`可传入可选`variableChoices`，格式与`WorkflowDesigner`一致：以真实事实路径为键，值为`{ label, value }`选项数组。
+从当前生成模型目录取得选项，再按实际`subject.factProjection`映射，不在页面维护第二套业务字典。
+它只提供显示名称，不能新增变量、改写条件或授予权限；每个变量最多64个选项、字典最多128项，并按原事实类型校验。
+画布分支、提示和可访问列表使用同一中文说明，自定义分支名保留；未知值或类型不兼容时保留原始值，不猜测含义。
+宿主传给设计器的同一元数据也用于AI建议预览，但预览显示正确不证明模型连接或实际调用可用。
+只读图保留显式业务条件通向拒绝结果的分支，普通审批拒绝操作的专用终点仍由办理设置/历史说明。
+
 应用自定义管理页面可复用当前用户客户端和共享图组件：
 
 ```tsx
 import { useEffect, useState } from 'react';
-import { WorkflowDiagram } from 'openxiangda/react';
+import { WorkflowDiagram, type WorkflowVariableChoices } from 'openxiangda/react';
 import { loadWorkflowDefinitionGraph, type WorkflowGraphReadResult } from 'openxiangda/core';
 
-export function ReadableWorkflow({ workflowCode, version }: {
-  workflowCode: string; version: number;
+export function ReadableWorkflow({ workflowCode, version, variableChoices }: {
+  workflowCode: string; version: number; variableChoices?: WorkflowVariableChoices;
 }) {
   const [result, setResult] = useState<WorkflowGraphReadResult>();
   const [selected, setSelected] = useState('');
@@ -188,7 +195,7 @@ export function ReadableWorkflow({ workflowCode, version }: {
   }, [workflowCode, version]);
   if (error) return <p role="alert">{error}</p>;
   if (!result) return <p>正在读取流程</p>;
-  return <WorkflowDiagram graph={result.graph} selectedNodeId={selected} onSelectNode={setSelected} />;
+  return <WorkflowDiagram graph={result.graph} variableChoices={variableChoices} selectedNodeId={selected} onSelectNode={setSelected} />;
 }
 ```
 

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

@@ -298,11 +298,31 @@ await businessData.transaction({
 ```
 
 引用约束：引用对象只含 `operationIndex`（0..99 的整数）与 `field: 'id'` 两个键；
-只能指向索引更小的 create 操作；引用不得嵌套在数组或对象里。违反形状报
+只能指向索引更小的 create 操作；普通字段引用不得嵌套在数组或对象里，关联资源字段的快照见下节。违反形状报
 `OPENXIANGDA_NATIVE_DATA_TRANSACTION_REFERENCE_INVALID`，嵌套报
 `..._NESTED`，目标不可解析报 `..._UNRESOLVED`。任一操作失败时整个事务回滚，
 不会留下无成员的 club。
 
+### 关联资源字段保留快照
+
+`resource-ref.single` 字段仍需要资源代码、显示标签和 `value`。用 Nest 的
+`resourceSnapshot` 将前序 create 引用放在唯一受支持的快照 `value` 位置；
+裸 UUID 引用不能代替资源字段快照：
+
+```ts
+import { resourceSnapshot } from 'openxiangda/nest';
+const operations = [
+  { operation: 'create' as const, resourceCode: 'orders', data: { name: '订单' } },
+  { operation: 'create' as const, resourceCode: 'order-lines', data: {
+    order: resourceSnapshot('orders', { operationIndex: 0, field: 'id' }, '订单'),
+  } },
+];
+```
+
+快照的 `resourceCode` 必须与前序 create 的资源一致。只允许既有快照元数据，
+`value` 之外的对象、数组和 `snapshot` 中仍不接受事务引用；平台继续验证目标字段、
+引用和实际授权。字符串 ID 的 `resourceSnapshot` 调用保持原行为，助手不提交或重试请求。
+
 ## 业务动作与普通查询 {#business-action}
 
 `OpenXiangdaDataApiService` 按当前用户的普通资源、行和字段权限执行。具名业务动作使用 `OpenXiangdaBusinessDataApiService`：入口先检查该动作 capability，平台在精确应用和环境内以受信任后端执行，并保留发起人与动作审计。业务动作不能接受任意模型/字段/用户 ID 后不做业务校验；应用负责该动作的输入约束和业务不变量。