openxiangda-skill-kit 2.3.18 → 2.3.19

package/package.json

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

package/skills/manifest.json

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

package/skills/openxiangda-v2/SKILL.md

@@ -71,6 +71,7 @@ pnpm dlx openxiangda@__OPENXIANGDA_VERSION__ skill install --force
 | 外部无账号表单、续填、上传、本人记录 | [匿名公开访问](references/public-access.md) |
 | 审批、待办、消息或事件 | [工作流与通知](references/workflow-events.md) |
 | 自定义事务、校验或外部集成 | [按需后端](references/backend.md) |
+| 主子额度、审批占用释放、撤回修订重提 | [精确金额占用](references/decimal-reservations.md) |
 | 管理成员或查看有效流程参数 | [应用管理](references/administration.md) |
 | 检查、部署、生产发布与故障恢复 | [验收](references/testing.md)、[交付](references/delivery.md) |
 | 需求记录与版本升级 | [全流程记录](references/appspec.md)、[升级](references/upgrading.md) |

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

@@ -321,3 +321,5 @@ if (output.status === 'pending') {
 ```
 
 这些方法适用于当前用户、具名业务动作和应用服务身份，沿用各自权限；业务记录绑定仍需正式数据事务。输出目前支持 OSS/MinIO，受字段上限与100MiB硬上限约束，上传凭据五分钟后过期，完成须在额外十分钟内进行。过期错误应由调用者建立新的处理意图，不能无限重试相同过期计划。下载最长五分钟，签发后到期前为短期委托，不能即时撤回。不要在日志、持久草稿或业务数据中保存签名地址、POST policy 或签名字段。
+
+主子记录共享精确金额额度、撤回修订和审批释放，请使用[精确金额占用](decimal-reservations.md)的受管提交及终态事务。

package/skills/openxiangda-v2/references/decimal-reservations.md

@@ -0,0 +1,111 @@
+# 主子记录精确金额占用
+
+需要跨多条子记录共享主记录额度时，使用平台 `data.decimal-reservations` 1.1.0，
+金额字段声明 `number.decimal`、`precision: 18`、`scale: 2`、`exactDecimal: true`。
+JSON 金额使用字符串。平台在父记录锁内用 PostgreSQL NUMERIC 校验占用；应用不做
+浮点求和、不维护另一个余额字段。此能力需要匹配 SDK、平台镜像和迁移；包安装成功
+不表示目标环境已就绪，先检查平台能力和正式部署回执。
+
+## 声明与首次提交
+
+提交的 Named Action 在 `platformAccess.decimalReservation` 声明 `mode: 'reserve'`、
+资源、amount/currency/relation/parent/root/status 六个字段、主子关系取值和允许状态，
+并用 `platformAccess.workflow.codes` 声明实际审批。当前用户仍需资源与字段读写权限。
+首次使用会冻结环境内该资源的映射；已有未入账子记录时拒绝启用，不自动补账。
+
+在 `OpenXiangdaBusinessProcessService.commit` 顶层增加：
+
+```ts
+const decimalReservation = {
+  parentId,
+  expectedParentRevision: parent.revision,
+  childOperationKey: 'child',
+  reservationKey: submission.reservationKey,
+  amount: '123.45',
+  currencyCode: 'CNY',
+};
+```
+
+`childOperationKey` 同 `workflow.subject.fromOperation`，选中唯一一条该资源的
+create 或 update。平台原子完成子记录、占额、审批命令和可选本人草稿消费。
+审批通过将 reserved 改为 committed，继续占额；驳回或撤回释放一次。
+
+## 撤回后修订并重提
+
+released 子记录仍不能通过普通 CRUD 或 `BusinessData.transaction` 修改金额、
+状态、父/root/关系等保护字段。界面把修订保存到本人 FormDraft，重提时一次提交：
+
+```ts
+await businessProcess.commit({
+  idempotencyKey: submission.idempotencyKey,
+  data: {
+    operations: [{
+      key: 'child', kind: 'update', resourceCode: 'contracts',
+      id: child.id, expectedRevision: child.revision,
+      data: {
+        title: draft.title,
+        amount: '123.45',
+        status: { value: 'approving' },
+      },
+    }],
+  },
+  formDraft: {
+    resourceCode: 'contracts', id: draft.id,
+    expectedRevision: draft.revision, mode: 'update', recordId: child.id,
+  },
+  decimalReservation,
+  workflow: { workflowCode: 'contract-approval', subject: { fromOperation: 'child' } },
+});
+```
+
+每次新的提交意图使用新的 reservationKey 和提交键；网络结果未知时保留原键及原
+payload查询/重试，不能用新键重做旧请求。更新保留父/root/关系，失败会整体回滚，
+本人草稿仍可恢复，正式金额与审批命令不会半完成。普通主记录继续原来的无额度路径。
+
+## 真实审批事件终态
+
+在真实审批消费者的 `platformAccess` 增加以下声明；其中状态取值由应用自己的
+资源选项决定。审批必须声明同一 subject 资源，且存在该资源的 reserve 动作映射。
+
+```ts
+platformAccess: {
+  decimalReservation: {
+    resourceCode: 'contracts', workflowCode: 'contract-approval',
+    outcomes: [
+      { eventType: 'openxiangda.workflow.instance.completed.v2', mode: 'commit', eligibleChildStatuses: ['signing'] },
+      { eventType: 'openxiangda.workflow.instance.rejected.v2', mode: 'release', eligibleChildStatuses: ['rejected'] },
+      { eventType: 'openxiangda.workflow.instance.withdrawn.v2', mode: 'release', eligibleChildStatuses: ['draft'] },
+    ],
+  },
+}
+```
+
+每个 eventType 也必须列在订阅的 eventTypes 中。不得使用自造应用事件或
+native-data execution 订阅获得此权限。事件 handler 中用已有的
+`OpenXiangdaApplicationDataApiService`，将终态附加到原事务：
+
+```ts
+import { idempotentTransaction } from 'openxiangda/nest';
+
+await applicationData.transaction(idempotentTransaction(
+  context.idempotencyKey,
+  [childStatusUpdate, auditCreate],
+  [],
+  { decimalReservation: {
+    reservationKey: originalSubmission.reservationKey,
+    transitionKey: context.idempotencyKey,
+    childOperationIndex: 0,
+  } },
+));
+```
+
+选中的 childStatusUpdate 必须是该资源唯一 update，保留正常 expectedRevision。
+模式和金额不能放进终态请求；平台从真实 leased delivery、原始及当前不可变订阅、
+workflow command/instance/subject revision 和台账验证，SDK自动继承已验签事件上下文。
+普通应用凭据或自填事件头不构成授权。精确同键、同payload重放返回原完整事务结果；
+旧轮次不能释放重提后的新占用。重放仍受当前权限、有效事件租约和父记录可读性约束。
+
+首批只覆盖主子额度和三个真实审批结果。作废/终止释放 committed 必须另有受管
+真实业务动作；状态枚举不代表已实现该能力，签后金额变更仍拒绝。锁等待最多2秒、
+单条SQL最多5秒，较严格的已有约束优先；retryable 409
+`OPENXIANGDA_NATIVE_DECIMAL_CONTENTION` 不允许换键掩盖未知结果。