openxiangda 2.44.0 → 2.55.1

package/documentation/field-components.md

@@ -68,6 +68,8 @@ import { AttachmentFileList } from 'openxiangda/field-kit';
 
 组件按文件引用选择缩略图，预览和下载经过平台接口。自定义活动封面同样先选择 `cover.thumbnailUrl`；只有平台引用没有缩略图时才回退 `cover.previewUrl`。不要写 `previewUrl || thumbnailUrl`，否则小卡片也会下载完整原图。保留真实宽高或稳定的封面比例，非首屏图片使用懒加载；不得在列表渲染时预取所有原图。
 
+视频或音频需要在原任务界面播放时，使用 `ManagedMediaPlayer`，例如 `<ManagedMediaPlayer file={record.media[0]} resourceCode="lessons" />`。组件先核对官方预览元信息，再鉴权读取内容；当前身份、文件或绑定变化以及卸载会释放播放器与 ObjectURL，不接受任意 `src`。默认单文件容量100MiB，可由应用按实际任务显式配置 `maxSizeMb`，超限明确失败并保留附件下载任务。提供加载、拒绝和重新读取状态，浏览器编码支持须实际播放验证。播放本身不提交业务进度或观看时长。
+
 受限文件的缓存必须保留权限核验。配套平台支持私有条件缓存时，浏览器可以保存文件响应，再次访问由平台先核对当前权限，内容未变化返回 304，从本地复用字节；`no-cache` 表示复用前校验，和 `no-store` 禁止保存不同。缺少可靠实体标识或请求失败时仍禁止缓存。不应由应用添加长期免校验缓存、公开 CDN 缓存或跨账号 Blob 缓存来绕过该规则。公开长期缓存需要独立、明确的公开发布契约，不能仅因字段名叫封面就视为公开。
 
 验收时同时记录原图/缩略图字节、列表实际请求的变体、重复访问传输量和权限撤销结果。仅看到 `blob:` 地址不能判断用了 Base64，HTTP 200 也不能证明命中了缓存。
@@ -140,6 +142,48 @@ import { AttachmentFileList } from 'openxiangda/field-kit';
 成员快照可包含头像、工号、职务、手机号、邮箱和所属部门；部门快照可包含完整路径、
 路径节点和父部门。凭证、Token 和认证秘密永远不能进入快照。
 
+### 限定职责候选（合同已定义，运行时接入中）
+
+`user.single` / `user.multiple` 可在代码中声明 `userCandidates`，引用本应用职责和可选范围。
+它与资源选择的显示 `source` 分开，编译产物中的字段和 Surface 必须一致。
+使用前确认平台已开放 `data.user-candidates@1.0.0`。SDK已接入候选读取和双端字段组件，
+平台运行时仍在本地集成验收；未广告能力时不能部署该声明。不能以普通通讯录过滤替代服务端约束。
+
+```ts
+{
+  code: 'unitLeaders', type: 'user.multiple', label: '单位负责人',
+  userCandidates: {
+    kind: 'app-role', roleCode: 'unit-leader', pageSize: 20,
+    scope: { dimensionCode: 'college', operation: 'approve', field: 'college' },
+  },
+}
+```
+
+职责和范围维度必须在同包声明。`pageSize` 为1–50，默认20；范围使用代码常量 `value`，
+或同资源的 `text.short`、`uuid`、`option.single` 字段 `field`，两者互斥。
+单选范围取稳定的 `.value`，不按显示标签决定身份。记录范围必须来自已授权、已保存的记录或当前任务，
+首版新建不接受非空的记录范围选人。修改范围须清空相依选择并保存，再按新范围重选。
+候选显示失败不能当作空名单；旧选择失效须保留显示快照并提示重选。
+
+流程使用 `{ provider: 'form_field_users', inputPath: 'leaders', candidateField: 'unitLeaders' }`，
+其中 `subject.factProjection.leaders` 必须精确指向 `unitLeaders`，范围字段也须有唯一事实投影。
+不能另写职责、范围或路由覆盖来源，不能用嵌套输入路径绕过候选字段。
+办理页不能同时修改范围字段与相依选人字段。首版任务候选只支持主体字段，任务中可写子表候选字段明确拒绝；
+普通子表记录的 Native 约束和历史只读显示仍按各自合同处理。
+流程进入节点时再次核验原职责成员，随后解释职责代理；历史已创建任务保留当时快照。
+
+标准表单、流程发起和任务补填自动传递候选上下文。自定义页使用Field Kit的
+`SurfaceFieldControl`/`MobileSurfaceFieldControl`，更新时提供`recordId`和`expectedRevision`；
+任务页额外提供`workflowCandidateBinding: { taskId, expectedTaskVersion }`。缺失任务版本会要求刷新，
+不会转用普通数据或通讯录接口。使用`ResourceFormContent`时也提供已加载记录的`expectedRevision`。
+
+自定义选人交互可从`openxiangda/react`调用`queryFieldUserCandidates(resourceCode, fieldCode, input)`
+或`queryWorkflowTaskUserCandidates(taskId, fieldCode, input)`。查询schema固定为
+`openxiangda.user-candidates-query/v2`，支持keyword/cursor/selectedIds；Native更新绑定recordId/expectedRevision，
+任务绑定expectedRevision/expectedTaskVersion。不要传入职责或学院覆盖参数。返回`UserCandidatePage`只包含
+稳定ID、名称、已选项valid/invalid及下一页游标；invalid不返回无权读取的名称，页面保留原显示快照。
+确认前复核选择只能改善交互，不能替代保存及节点进入时的服务器核验。
+
 仅选择时间时使用 `time`，并显式决定精度：
 
 ```ts
@@ -245,7 +289,7 @@ ISO instant）与 `minuteStep`（1 到 60 且整除 60）。设置步长后只
 - 单选、复选直接展示选项；下拉单选／复选使用可搜索的底部弹层，多选展示已选数量。
 - 日期使用月历，日期时间可切换时间滚轮；区间依次选择开始和结束，可返回上一步修改。
 - 地址采用地区路径逐层选择，详细地址单独输入。定位沿用当前可用的钉钉或浏览器能力。
-- 子表单直接展开行内字段，支持折叠、添加和删除；父表提交校验所有行，包括折叠的行。
+- 子表单使用每页十行的行内字段，手机支持折叠、添加和删除；父表提交校验所有行，包括折叠及未显示页的行。分页保留完整输入和草稿，任务完成校验会定位到错误行所在页；有待处理上传时先完成或移除文件，再翻页。
   权限、最大行数、原子事务和已存行的 revision 继续由原有资源契约约束。
 - 签名在底部画布手写并保存；图片、签名和附件仍通过托管文件接口上传与鉴权读取。
 - 手机富文本编辑降级为多行文本。未修改时保留已有 HTML；修改后将纯文本转为转义后的

package/documentation/frontend.md

@@ -1,5 +1,13 @@
 # 前端架构
 
+## 资料维护删除
+
+模型的 `recordDeletion.delete` 显式开启后，标准 `GeneratedResourcePage` 详情提供“删除资料”。普通资料编辑仍按原 `mutationOwner` 和生成页许可决定。删除面复用平台导航 guard，原因输入、显式影响预览、确认、到期、明确拒绝、未知结果和成功分别呈现，PC与手机使用同一响应式弹层。
+
+自定义详情可嵌入 `ResourceRecordDeletion`（`resourceCode`、`recordId`、`onClose`、`onDeleted`），服务端始终重验资料权限。独立接入使用 `createNativeResourceClient(resourceCode, surface)` 的 `previewDeletion(id)`、`deleteWithPreview(id, input)`、`deletionReceipt(id, input)`；也可从 `openxiangda/react` 导入 `previewNativeRecordDeletion`、`deleteNativeRecordWithPreview`、`recoverNativeRecordDeletion` 及对应 `DataRecordDeletion*` 类型。
+
+写入input包含 `schemaVersion: 'openxiangda.data-record-deletion-request/v1'`、原 `previewToken`、固定 `idempotencyKey` 与 `reason`。提交前固定完整请求，未知时先查原回执；专用回执不存在且预览未过期才可让用户明确重试原请求。预览有效五分钟，回执可在到期后恢复；SDK保留原CSRF的有界缓存不等于跨刷新保存。标准组件不跨刷新保存Token/原因/键，身份退出、Head变化或缓存淘汰后的旧请求恢复限制须向应用维护者说明。详情与历史不从删除成功回执回填已删除旧值。授权、级联预算和错误边界见[数据与权限](./data-authz.md)。
+
 状态：Vite/Refine 已成为 OpenXiangda 2.0 唯一默认前端栈。决策与实测见
 [核心架构](./concepts.md)。
 

package/documentation/getting-started.md

@@ -68,10 +68,10 @@ MCP 服务随项目根包一起安装，AI 客户端的 stdio 连接仍需配置
 以下命令的版本占位符由随包资料替换为该根包的精确版本。网站源码阅读者应先确认要使用的发行版本。
 
 ```bash
-pnpm dlx openxiangda@2.44.0 skill install --force
-pnpm dlx openxiangda@2.44.0 auth status --base-url <平台地址> --json
-pnpm dlx openxiangda@2.44.0 login --cwd my-app --base-url https://platform.example.com
-pnpm dlx openxiangda@2.44.0 create my-app --base-url https://platform.example.com
+pnpm dlx openxiangda@2.55.1 skill install --force
+pnpm dlx openxiangda@2.55.1 auth status --base-url <平台地址> --json
+pnpm dlx openxiangda@2.55.1 login --cwd my-app --base-url https://platform.example.com
+pnpm dlx openxiangda@2.55.1 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.44.0 auth status --base-url <平台> --json
-pnpm dlx openxiangda@2.44.0 source resolve <仓库URL> --base-url <平台> --json
-pnpm dlx openxiangda@2.44.0 source clone <仓库URL> <新目录> --base-url <平台> --json
+pnpm dlx openxiangda@2.55.1 auth status --base-url <平台> --json
+pnpm dlx openxiangda@2.55.1 source resolve <仓库URL> --base-url <平台> --json
+pnpm dlx openxiangda@2.55.1 source clone <仓库URL> <新目录> --base-url <平台> --json
 ```
 
 登录缺失或站点不匹配时，先按该平台执行 login。resolve 根据平台已经登记的绑定返回

package/documentation/managed-concurrency-frontend.md

@@ -236,7 +236,7 @@ hook 从 `openxiangda/react` 和 `openxiangda/mobile` 导出。state、initializ
 
 已受理申请的自动观察最多持续到首次明确提交后的 30 分钟，默认受理恢复仍为 120 秒，两者分别计算。自动观察的每次结果读取同时受单次 120 秒和原提交剩余时间限制；刷新和 resume 不重新获得观察时间。跨设备没有本地首次时间时，用原回执 acceptedAt 计算观察窗口，不能以页面挂载时间重新计时。达到窗口后保留原意图，状态为 recovering、isObserving 为 false，提示稍后核对；明确 refresh 仍可用有界初查预算查询迟到终态，但不重新启动已经到期的自动观察，也不自动提交。
 
-正常待处理结果每次至少间隔 5 秒，遵守更长的服务端 retryAfterMs，再加随机抖动。单次只读恢复耗尽且仍是已知预算繁忙时，外层可在原观察窗口内指数退避继续；权限、依赖、网络故障或悬挂请求超过读取预算时立即停止自动观察，显示 error 并保留原回执和请求键。终态停止。受理恢复中核对原结果同样只允许已知预算繁忙继续，读取依赖失败不能被外层重试隐藏。一个业务区域只挂载一个观察者。离开或关闭页面不撤销已受理请求，平台自动继续；新设备通过 mine 找到本人的原请求。position 为空时显示「已受理，稍后可查看」，不要显示虚假的精确人数或预计秒数。
+正常待处理结果每次至少间隔 5 秒，遵守更长的服务端 retryAfterMs，再加随机抖动。单次只读恢复耗尽且仍是已知预算繁忙时，外层可在原观察窗口内指数退避继续。SDK 自身明确标记为 status=504、retryable=true 的 CONCURRENCY_READ_RECOVERY_EXHAUSTED 也只在已受理原结果观察中按退避恢复；它不代表服务端忙，不延长原三十分钟截止，也不触发再次提交。权限、依赖、普通网络错误、其他 504 或未标记可恢复的错误立即停止自动观察，显示 error 并保留原回执和请求键。终态停止。受理恢复中核对原结果同样只允许已知预算繁忙继续，读取依赖失败不能被外层重试隐藏。一个业务区域只挂载一个观察者。离开或关闭页面不撤销已受理请求，平台自动继续；新设备通过 mine 找到本人的原请求。position 为空时显示「已受理，稍后可查看」，不要显示虚假的精确人数或预计秒数。
 
 refresh 有本地原键时先薄查询原 key；找到已受理非终态后不再 mine。没有本地意图或原申请已有终态时，mine 优先恢复新的进行中周期，避免本地历史 succeeded 遮蔽另一个设备的新申请。原键明确 404 后保留一次本人列表兜底；未确认的本地意图只能采用同原键回执。列表中只有别的活跃周期时显示 recovering / CONCURRENCY_ORIGINAL_REQUEST_REQUIRED，并保留原 key/input；没有匹配时显示 CONCURRENCY_ACCEPTANCE_UNCONFIRMED，提供「核对原申请」和「恢复原申请」动作。不能把无匹配解释为业务失败，也不丢弃可能迟到受理的原意图。已知读取繁忙耗尽显示 recovering，真实依赖、网络、权限或未知 400 显示 error；两种状态均保留原键、输入和已受理回执，读取失败不自动提交。
 

package/documentation/manifest.json

@@ -1,12 +1,12 @@
 {
   "schemaVersion": "openxiangda.documentation/v1",
-  "version": "2.44.0",
+  "version": "2.55.1",
   "topics": [
     {
       "id": "getting-started",
       "title": "安装与开始开发",
       "file": "getting-started.md",
-      "sha256": "5a0fd1357652426798651f3a947308abb2a47d391a4c523a4f9739c564ce4d0d"
+      "sha256": "592aa59bab9fcb430ee5caf042c872bf902a8ae5ac8e666b643ebf2e0c103b4a"
     },
     {
       "id": "product-design",
@@ -36,7 +36,7 @@
       "id": "declarations-cheatsheet",
       "title": "声明速查：一次写对 config",
       "file": "declarations-cheatsheet.md",
-      "sha256": "726d9e992c16531aef0ee2e8510729d3dd4f2b1320104e39bba9744181946330"
+      "sha256": "4fa1bc8920af2157bc67ba5819e85fbc271da93155be18650bfbe51c02eac782"
     },
     {
       "id": "application-foundation",
@@ -60,19 +60,19 @@
       "id": "frontend",
       "title": "页面与标准组件扩展",
       "file": "frontend.md",
-      "sha256": "9fdc5f950356843dca2dcfad3c0f5ff0d44b5158bd79cbd0f14ae99a48a543cf"
+      "sha256": "0d122e3f9096a549f355ba88a4800b6473180a19b926e3748c84d51bb44f02b6"
     },
     {
       "id": "field-components",
       "title": "字段、表单与移动控件",
       "file": "field-components.md",
-      "sha256": "4bb36d6b6162be84aaf95b86fabe2e44805d5f9441dc8cfa5f951c24ce6d6102"
+      "sha256": "e621fef870bdafa01bd41a294be6169094f1c8b5d6d31c89fa64df105d86a3d5"
     },
     {
       "id": "data-authz",
       "title": "数据查询与权限",
       "file": "data-authz.md",
-      "sha256": "5c8592f0b45e14c619b6146c6570c65161f0e0cb8ee86724050b3417f9e90e50"
+      "sha256": "1f77cbaf778a0a01dfa877610e7d87451716fd60d4364fda43adb4f92c5010f1"
     },
     {
       "id": "public-access",
@@ -84,13 +84,13 @@
       "id": "workflow-events",
       "title": "审批、事件与通知",
       "file": "workflow-events.md",
-      "sha256": "712024dc7f01a645c458aa98bc53b3ca817909356ca9255c2ab857698f4d66ef"
+      "sha256": "0c02e0253ee52804d22801bab215933c5240974c72e4951bafb0a27e35d0cbd4"
     },
     {
       "id": "backend",
       "title": "按需后端与业务动作",
       "file": "backend.md",
-      "sha256": "a8dc288d6c220f10638eddaf49edd7c55baa29f8e70880dd29ba1354efc4577d"
+      "sha256": "5fcea9d1f9197d7f9ed1d65d0e181465092f34feeb0eec46552f20264bf02f85"
     },
     {
       "id": "agent-cards",
@@ -114,19 +114,19 @@
       "id": "managed-concurrency-frontend",
       "title": "并发能力的前端接入",
       "file": "managed-concurrency-frontend.md",
-      "sha256": "0e6c4aa63ae82f7ce8c19c1dea061688c6507cebe93733be715b27fab71afa2e"
+      "sha256": "c4b18991058fec5878f73355e63da063a677ced8413e7fc2b4f03edfb0c2341a"
     },
     {
       "id": "administration",
       "title": "应用管理与有效配置",
       "file": "administration.md",
-      "sha256": "a5e17ced019746f314bf9a2005b023786308204233565b96ddf3db2150de2216"
+      "sha256": "084b3bcb6ff371701045ec900149d90f8294323259ddd260f7e2c8bfedda2378"
     },
     {
       "id": "testing",
       "title": "检查与真实业务验收",
       "file": "testing.md",
-      "sha256": "bc16ffa07fae9ddf17baf3ca99f7076aeee5976244864e46c701816c77ee9abd"
+      "sha256": "d70da0c44c8c949e916b62dbd05eb527a00b5b26c0c152de35ea84f5450958f2"
     },
     {
       "id": "delivery",

package/documentation/testing.md

@@ -36,6 +36,23 @@ Web 默认保留开发服务回环访问检查。按需 Nest 使用 `tsx --test`
 
 只改文案时验证受影响页面。复杂事务、并发和值转换使用聚焦测试。浏览器验收实际操作并检查错误，不能用模拟响应或空页面加载代替真实角色验收。
 
+应用后端生成 Native 事务或 BusinessProcess 数据守卫时，业务测试通过统一根包的公开测试入口校验真实生成的请求，不复制验证规则或额外依赖底层包：
+
+```ts
+import { SCHEMA_VERSIONS, validateDataTransactionRequest } from 'openxiangda/testing';
+
+const diagnostics = validateDataTransactionRequest({
+  schemaVersion: SCHEMA_VERSIONS.dataTransactionRequest,
+  idempotencyKey: submission.idempotencyKey,
+  guards: submission.data.guards,
+  operations: submission.data.operations.map(item => ({
+    operation: item.kind, resourceCode: item.resourceCode, data: item.data,
+  })),
+});
+```
+
+合法请求返回空诊断数组；守卫失败码必须使用 `OPENXIANGDA_*`。纯合同校验不证明数据库锁、权限、实际执行或失败恢复通过，这些仍需要对应角色和原操作的运行验收。
+
 匿名访问另验证续填、上传、校验、幂等提交、own.list/own.read；另一浏览器应无法获取前一浏览器的记录。工作流按已启用功能检查发起、处理、历史详情和消息跳转，不为未启用通道增加测试负担。
 
 ## 可选临时身份 {#temporary-identities}

package/documentation/workflow-events.md

@@ -254,14 +254,18 @@ fields: [{ code: 'startsAt', label: '开始时间', type: 'datetime', required:
 所声明精确 capability 的用户；capability 必须在同一应用显式声明，不支持
 通配符。该授权同时允许读取对应流程实例的详情及时间线，包括完成后查阅；
 不授予审批、抄送、改派、删除、普通数据读取或管理后台权限。撤销 capability
-后读取和终止权限都失效。撤回、终止均要求填写原因；超级管理员也遵守已声明时限。
+后读取和终止权限都失效。撤回默认要求填写原因；固定定义显式声明
+`instanceCommands: { withdraw: { reasonRequired: false } }` 时允许省略、空串或空白，
+仍拒绝已提供的非字符串及超过4000字符。该选项自动要求
+`workflow.optional-withdrawal-reason@1.0.0`，旧平台不能激活。`beforeFact` 可独立
+声明或与选填组合，空策略无效。终止仍必填原因；超级管理员也遵守已声明时限。
 
 不声明 `instanceCommands` 时沿用既有行为；只为终止授权时可以省略其
 `beforeFact`。声明策略的交付包自动要求平台能力
 `workflow.instance-cancellation-policy`，旧平台无法激活该应用版本。
 已经固定该策略的实例存在期间，平台回滚也必须保留策略执行能力。
 发布新 definition 不会改写旧实例固定的 definition 版本，因此不会给旧实例
-补上截止时间或业务管理员终止授权。升级前应盘点存量实例，按各自原定义完成
+补上截止时间、选填原因或业务管理员终止授权。升级前应盘点存量实例，按各自原定义完成
 或由原有授权主体处置；不要通过重发事件或改写事实迁移策略。已使用新策略的
 实例在截止后及终态仍允许当前被授权的业务管理员查阅，撤销其 capability
 也会撤销这些存量实例的详情读取权限。
@@ -404,6 +408,38 @@ processCommand 路径和 allowlisted context 预填。标准页调用原 Named A
 `ProcessCommandSurface`；`awaiting_input` 只回答已生成 requirement，`started` 再进入 pinned
 instance entry。浏览器不再导出 prepare/start 发起协议。
 
+### 标准提交页的业务表单扩展
+
+应用读取获授权的业务资料后，可将 canonical 预填值和同步字段规则传给公开
+`WorkflowSubmissionPage` 的 `formOptions`。PC和手机复用同一个组件及Field Kit；
+上传、具名动作、幂等操作和未知结果恢复继续由标准页处理，应用不要复制提交生命周期。
+
+```tsx
+import { WorkflowSubmissionPage, type WorkflowSubmissionFormOptions } from 'openxiangda/react';
+
+const formOptions: WorkflowSubmissionFormOptions = {
+  initialValues: { phone: profile.phone, className: profile.className },
+  fieldState: values => {
+    const medical = (values.reason as { value?: string } | undefined)?.value === 'illness';
+    return {
+      recoveryEvidence: { visible: medical, required: medical, hiddenValue: [] },
+      medicalReviewer: { visible: medical, required: medical, hiddenValue: null },
+    };
+  },
+  intro: <p>请核对预填资料；因病申请需要康复证明。</p>,
+};
+return <WorkflowSubmissionPage workflowCode="reinstatement" variant="mobile" formOptions={formOptions} />;
+```
+
+初值仅在当前匹配的发起合同内应用到未触碰字段，每字段一次；后到资料和父组件重新渲染
+不会覆盖已填写或手动清空的内容。日期和范围使用canonical值，标准页通过原codec转换。
+`fieldState`读取canonical值，`required`只能增加校验，不能撤销原必填或隐藏原必填字段；
+可选字段隐藏时清为`hiddenValue`或undefined，提交也使用同一投影，不发送旧材料/人员。
+初值或规则引用范围外字段会阻断表单。`intro`只提供页面说明，不拥有身份、授权或提交。
+资料加载/失败或业务资格提示可传`preparation`内容，它仅阻断尚未提交的表单；原请求查询
+及已接受命令的展示优先于该提示。应用应始终挂载标准页，避免当前资格变化遮蔽原结果恢复。
+这些规则属于应用代码，不能通过管理员节点配置修改；服务器仍独立校验实际业务资格与字段。
+
 通用应用待办页通过 `frontend.user.applicationTodoCenter: true` 启用，平台同时提供
 `/todos` 和 `/m/todos`。它只投影当前登录用户的 Notification Hub 收件人数据，
 `查看详情` 使用上述统一导航解析；待办页不常驻业务详情，审批命令仍在目标 Workflow
@@ -443,6 +479,10 @@ readability: {
 
 说明的执行位置只能是 submission、某节点的 node_input 或 completion。它是对已有逻辑的注释，不会自动执行计算或产生新流程节点。没有实际计算步骤时，不应写成“系统已计算总金额”。条件的变量必须存在于输入 Schema；对旧未标注定义，读取投影会明确给出未知来源诊断。
 
+流程图的条件卡直接摘要参与判断的变量与分支数，业务步骤卡摘要声明的产出。管理详情在条件旁显示申请字段、流程输入或固定步骤来源；业务步骤优先展示输出说明，缺少说明时明确提示。来源节点只有与当前图的 handler 代码和版本一致才可跳转，历史实例使用自己的固定定义。界面不根据节点标题推断公式，也不加载或执行源码引用。
+
+长图首次打开会保留可读比例；可用“适应全图”查看全貌，再通过搜索、来源链接、缩略导航或方向键定位。手机使用同一结构的节点列表和详情。图的连线、条件和代码始终只读，审批/抄送配置沿已声明的管理员能力修改，字段行为仍由页面代码定义。
+
 可选 `source: { path, symbol?, digest }` 只返回源码位置和 SHA256，不返回源码内容。path 指向工作区 apps/packages/platform 下的代码文件，digest 为 `sha256:<原始文件字节摘要>`。工作区加载时核对文件存在、无符号链接、大小和摘要；源码变化后以 WORKFLOW_LOGIC_DESCRIPTION_STALE 阻止封装，开发者应核实说明并更新引用。32 个文件、单文件 2MiB、总量 8MiB 为上限。元数据不能验证任意 TypeScript 的业务含义，业务说明及验收仍由开发者维护。
 
 ## 持久业务步骤
@@ -513,9 +553,74 @@ outbox容量等事务故障会回滚，处理器按原键核对后重交，不
 `examples/workflow-administration/task-page.ts`。
 
 页面表达式只读取本页 `values.*`，平台以合并后的业务值强制显隐和必填。
-最多16页、每页64字段、单次值64KiB，表达式8层/64节点。
+最多16页、每页64字段、单次值1MiB，表达式8层/64节点。
 系统、流水号和隐藏字段不可作为补填入口。根附件、图片复用平台托管文件；
-签名、子表和富文本仍需后续任务页面支持，不将它们降为任意 JSON。
+签名和富文本同样保留 Native 字段协议；普通 owned 子行以固定页面白名单和行 CAS 提交。
+
+### 标准流程的主子表发起
+
+标准发起页复用 Field Kit 的 PC/手机子表，通过原 `standard-commands` 的
+`mutation.data` 一次提交完整表单。子表字段值沿用表单行结构：
+`{ key, state, data, id?, revision? }`；日期等子字段按字段 codec 编码，
+界面快照与原值不作为授权或并发依据。声明关系、行序和父记录引用由 Native 生成。
+创建主表、所有子行和持久流程发起命令在同一个事务中完成；失败不留下部分申请。
+
+发起仍执行当前用户的父、子资源及字段授权。拥有主表权限不会自动得到通用子表权限。
+已有记录提交核对父 CAS 和完整已读子行集合，包括未修改行；删除显式保留原 id/revision，
+跨单、遗漏、重复或陈旧行均拒绝。原命令已提交时先返回同一回执，再也不重新展开当前行。
+每表100/累计400、完整意图双倍、整请求2MiB及展开后1000操作与 Native 预算一致。
+普通显式 Named Action 的16个业务操作预算不变；其自定义子表提交仍按自身合同实现。
+
+### 任务 owned 子表
+
+在主模型的 subtable 字段上声明 `subtable: { fields, create, delete, reorder }`，例如：
+
+```ts
+{ code: 'items', required: true, subtable: {
+  create: true, delete: true, reorder: true,
+  fields: [{ code: 'name', required: true }, { code: 'quantity', required: true },
+    { code: 'originalNote', readonly: true }],
+} }
+```
+
+关系沿用模型的 `resourceCode/foreignKey/orderField/maxRows`，不接受任务调用者自报。
+子字段可声明同样的只读、可见和条件必填规则；这些属于页面代码，管理员不能覆盖。
+`create/delete/reorder` 省略时关闭。仅一层，每表 maxRows 最多100，父资源及任务页
+声明总量最多400；默认仍20。完整意图最多为每表 maxRows 的两倍，可在一次提交中
+删除满表旧行并新增同等数量，仍按有效行数校验上限。整个 form/任务私有草稿值限1MiB，
+页面定义仍64KiB/64根字段；系统、隐藏、关系键和顺序字段不进入子字段白名单。
+标准主子表提交复用同一个 Native 原子事务，最多1000操作/2MiB（400行全量替换加主表为801操作），
+任一行失败全单回滚，不静默截断或分批提交。普通表单草稿values最多2MiB，含原值与当前值；
+状态字段的独立配额不变。附件上传数量/字节与详情读取预算仍独立执行，行数容量不豁免文件配额。
+子行支持 file/image/signature/text.rich，使用同一个任务上传入口并绑定准确行；普通
+子行字段和已授权只读展示不降为 JSON 编辑框。例子见 `examples/workflow-administration/task-owned-subtable.ts`。
+
+标准 PC/手机控件自动消费 `surface.taskForm.subtables`，不会调用普通 child CRUD。
+自定义客户端提交 `values.items` 的完整行意图数组：
+`{key,state,values,id?,revision?}`；state为created/persisted/deleted，key为小写UUID，
+持久行key等于id。删除显式列出原id/revision与空values，遗漏不代表删除。
+所有观察到的行版本都核对，包括未修改行；新行key作为其业务行ID。
+values只能写白名单的当前可编辑字段，关系键与顺序由服务器维护。
+
+原save_form/approve/resubmit同时提交主子数据、事实与决定，失败全部回滚。
+子表提交推进主版本；普通child操作仍各自拥有行版本，不能仅用主版本判断子表并发。
+私有草稿保存相同行意图，不改业务。CAS拒绝保留输入，核对后明确保留编辑或采用最新资料；
+正在编辑的行被别人删除时不会静默丢弃或复活。未知命令沿原请求/原回执恢复。
+能力 `workflow.task-owned-subtables@1.0.0` 从声明自动推导，正式 SQL
+`AuthorizeWorkflowTaskOwnedSubtablesV2` 随初始化迁移自动生效，无新增默认关闭开关。
+
+子行上传时在原 `WorkflowTaskFileUpload` 上增加
+`row: { subtableFieldCode: 'items', rowKey }`，`fieldCode` 是该行中的材料字段。
+rowKey 是新建或已持久化行的稳定小写 UUID；新行上传不会提前写入业务记录，排序也不会
+改变文件归属。不能自行指定子资源或父记录，也不能把任务私有文件交给普通 child CRUD。
+草稿递归保留有效行文件，删除意图不保留文件；原流程命令统一提交数据、引用和草稿消费。
+
+条件文件的上传资格依据已保存业务值。若本地编辑才使字段可见，标准页面提示先保存补填，
+再上传；私有草稿不会改变已经生效的业务事实。无条件材料可直接在尚未保存的新行上传。
+上传未知时保留原行地址、ID、规格和字节，核对 ready 回执只读恢复，不再 PUT；处理中
+禁用行修改、删除、排序和提交。标准 PC/手机控件自动处理四类值和准确行恢复。
+声明可写子行材料自动要求 `workflow.task-owned-files@1.0.0` 及适用的 managed/rich 能力；
+平台正式迁移 `AddWorkflowTaskOwnedFilesV2` 自动扩展绑定列，无需另开功能开关。
 
 标准 PC/手机任务页和 `WorkflowTaskOperationsPanel` 自动显示当前参与人的
 `surface.taskForm`。`save_form` 表示“提交补填，继续办理”，不是私有草稿。
@@ -538,6 +643,12 @@ approve/resubmit 携带 `form: { expectedRevision, values }` 时，Native 业务
 多人补填与管理纠错使用 Native 记录 CAS，冲突保留输入。首次请求的明确拒绝会只读刷新，
 修订变化时对照最新已保存值和本人输入，核对前锁住字段与操作；可选择保留输入或采用最新值。
 拒绝后的读取失败明确提示本次未提交，锁住旧操作，恢复读取后再核对；未知结果仍只能恢复原请求。
+操作确认表单使用同一 Surface 的必填、字符数与非空白规则校验意见和原因。
+拒绝意见默认必填。固定节点显式设置 `operationPolicy.reject.commentRequired: false` 时允许省略或空意见，目标须具备 `workflow.optional-rejection-comment@1.0.0`；已进入任务使用冻结规则，后续配置不追溯。选填仍限制为最多4000字符的字符串，不写入假意见。
+`commentRequired` 只配置同意/拒绝的 `comment`；转交、委托、加签、退回与管理员改派
+继续使用原合同的必填 `reason`，不用再填写第二份意见。
+明确拒绝后，实例、任务版本及操作签名仍一致且操作仍可用时，对话框保留输入供人工核对；
+任务、权限、字段规则或版本变化时不能沿用旧操作。刷新和保留输入都不会自动重发请求。
 补填刷新固定事实投影；
 修改已计算步骤的输入时清除当前失效输出及依赖输出。仅退回 replay 且所有前向
 审批路径确定重经生产者时允许；resume_current 或后置补填跳过重算会返回
@@ -558,8 +669,8 @@ approve/resubmit 携带 `form: { expectedRevision, values }` 时，Native 业务
 身份、环境、业务记录和固定页面由平台派生，不传actor/resource/page作为授权。
 可编译例子见 `examples/workflow-administration/task-draft.ts`。
 
-最多20份/90天与同用户、应用、环境、资源的其他表单草稿共享，单份最多64字段/64KiB。
-字段支持根附件、图片，暂不包含签名、富文本或子表。读到不兼容草稿时只返回安全标识与诊断，
+最多20份/90天与同用户、应用、环境、资源的其他表单草稿共享，单份最多64根字段/1MiB。
+字段支持根附件、图片、完整业务签名和富文本，暂不包含 owned 子表。读到不兼容草稿时只返回安全标识与诊断，
 不静默丢弃或泄露旧值。失去任务、角色或代理资格后不能继续读/用。
 
 读取不会自动覆盖输入；采用前确认，业务基线变化先核对并再次保存。相同输入暂存成功后
@@ -612,3 +723,107 @@ const readyFile = await completeWorkflowTaskFileUpload(taskId, input.id);
 复用既有 Native 文件引用 worker 和 GC；流式正式复制限时10秒。
 需要服务端正式 SQL `AddWorkflowTaskManagedFilesV2` 和自动能力
 `workflow.task-managed-files@1.0.0`，初始化无需新增开关。
+
+### 任务业务签名与富文本
+
+任务页面声明可编辑 `signature/text.rich` 时，标准 PC/手机字段控件自动使用同一任务
+文件、私有草稿和原流程提交入口。编译器同时要求 `workflow.task-rich-fields@1.0.0`；
+平台初始化自动提供，无新增配置开关。只有只读展示时不要求上传能力。
+
+业务签名保留完整 Native 值：`file: { id, name, size, contentType }`、可选 `signer`、
+`signedAt`、可选 `points` 和 `hash`，清空为 `null`。PNG、时间、笔迹与 SHA-256 在上传前
+固定，未知结果恢复只采用原文件，不重新签署。任务控件最多采样512个笔迹点并保留首尾；
+原 PNG 字节不改，仍受任务值1MiB限制。这些是业务采集信息，不代表平台认证的签署人、
+可信时间或法律电子签章。
+
+富文本保存清洗后的 HTML 和 Native 稳定托管图片地址，支持最多20图、单图10MiB、100MP。
+PC/手机保留格式、图片和前后文字；插图未知时锁住编辑，恢复采用原插入位置并只插入一次。
+`blob:` 仅用于授权预览，不进入保存值。新任务签名/富文本图片完成时核验实际图片解码与
+声明格式。完整值经 Native 校验后，草稿和正式审批共用排序文件锁、引用验证、保留期及事务。
+
+自定义 Field Kit 上传 renderer 的第四参数为可选 `onRecovered(file)`，仅在恢复原任务上传
+时采用完整字段值；正常上传仍返回 `DataFileRef`。非数组字段必须提供该回调；不能用文件数组
+append 处理签名或 HTML。当前任务、实例、记录或字段改变时清理旧图片预览，重新按范围读取。
+
+### 发起人同时参与审批
+
+审批节点可声明 `initiatorApprovalPolicy: 'auto_approve'`；省略或声明 `manual` 时由本人办理。
+该策略由流程代码固定，管理员可以调整已开放的审批方式与人员，不能修改此策略。
+仅当前已激活、由原人员解析或授权解析重试产生的发起人直接席位自动同意。
+单人/或签按正常同意规则完成；会签仍等待其他席位；依次审批只有轮到本人时才自动处理。
+发起人代理给他人、他人代理给发起人、转交、加签、管理员重分配及退回补正均需人工。
+
+带 `taskPageCode`、可写字段或强制同意意见的节点不能使用自动同意。需要补选负责人等
+业务输入的节点继续采用人工办理；配置也不能给自动节点增加强制同意意见。
+实际自动票使用原审批依赖与事务，历史显示“发起人自动同意”，事件包含 `automatic: true`
+及流程内核主体；没有伪造人工意见。后续解析失败会回滚本次自动票、任务与事件。
+每个事务最多进入 200 个节点、处理 200 个自动席位，业务步骤仍等待原业务结果。
+前一办理人来源保留原发起人；重启或原命令重放不重复自动票。
+
+此声明要求 `workflow.initiator-approval-policy@1.0.0`，缺少实现的目标平台会拒绝应用。
+
+### 审批人为空时的节点策略
+
+审批节点可声明 `emptyPolicy: 'skip'`，省略或声明 `block` 时保持阻塞。第一版 skip 支持 fixed_users、input_users、form_field_users、app_role、app_role_in_scope；编译器拒绝其他来源与 skip 组合。表单人员明确为 `[]`，或存在的角色在有效范围内没有成员，且解析成功、没有警告，才允许自动继续到 `onApprove`。缺失/null 字段、不存在的角色、无效账号、缺少范围、解析失败和非零人数不满足 min/max 都不能跳过。
+
+该策略由代码固定。每次实际跳过记录节点访问、当时配置、解析依据和 `openxiangda.workflow.node.skipped.v2` 事件；图和 PC/手机历史显示“已跳过”。连续节点推进受 200 节点上限约束，业务步骤仍等待其正式结果。后续失败与业务变更在原事务一起回滚，重试沿用原命令。
+
+退回补正（return_review）必须有人实际处理，不能靠空人跳过；重提后的正常 replay/resume 流转继续采用原节点策略。使用此声明时，生成契约要求目标平台支持 `workflow.approval-empty-policy@1.0.0`，缺少该能力的旧服务端不能接收。
+
+## 按业务资料权限查看办理历史 {#record-history-read}
+
+发起人、审批人、抄送人使用既有 Workflow 详情。业务查看人员需要根据当前资料范围读取办理记录时，模型可显式声明：
+
+```ts
+workflowHistory: { read: ['app:my-app:history:read'] },
+```
+
+`read: true` 绑定本资源的 read 能力，`false` 关闭入口；省略也关闭。能力数组引用已声明能力，最多20项，必须由同一角色成员全部持有，同时具备资源read。ALL资料读取角色与本人历史角色组合时，历史仍限本人行；Perspective和Native RLS继续收窄范围。此声明不授予审批、转交、后台或流程图管理能力，且独立于 `audit.read` 的资料变更记录。
+
+标准Native详情按声明提供折叠的“流程办理记录”。自定义用户端PC/手机页面可复用 `WorkflowRecordHistoryPanel`（`openxiangda/react`），传入 `resourceCode`、`recordId` 和 `variant`。通过 `loadWorkflowRecordHistory`（`openxiangda/core` 或 `openxiangda/react`）直接读取时，可传 `instanceId` 查看该记录的原固定实例，以及 `limit`（默认20、最多100）、`offset`（最多500）。环境来自当前平台runtime；接口不提供办理Surface或操作令牌。
+
+结果仅包含原流程版本、实际节点访问、人员、操作时间和意见，不返回条件事实、业务字段、代码、角色席位、原始log detail或授权摘要。每次请求重新授权；无权、没有可读实例、容量超限及读取中资料/实例变化分别保留明确失败。组件清除失败后的旧数据并提供手动重试，不自动重放写入。单实例最多500操作、200访问、1000审批/自动抄送席位，响应最多2MiB；历史较大时返回413，不静默截断。
+
+本能力要求平台 `workflow.record-history-read@1.0.0`。只读历史不提供评论发布、源系统打印或删除；这些行为需分别声明、授权和验收。
+
+## 拒绝通知的修改人 {#workflow-rejection-notification}
+
+当业务要求“申请被拒绝时通知最后修改人”，在固定流程定义中声明：
+
+```ts
+rejectionNotification: {
+  recipient: 'record_last_modifier',
+  title: '审批拒绝',
+  summary: '您有一个审批被拒绝，请查看',
+},
+```
+
+最后修改人是拒绝事务读取的 Native 主记录 `updated_by`，即最后一次成功业务写入所归属的用户。
+例如 A 发起、B 成功补填、C 拒绝时，专用拒绝通知发给 B。审批意见、拒绝操作和未成功的
+业务写入不会替换修改人。平台在原事务锁定主记录、冻结当前资料 revision 和收件人，
+通知队列恢复时使用原事实；之后的编辑不会改变这次通知的对象。
+
+标题最多160、摘要最多500字符，都是固定文本；不支持客户端收件人、任意字段路径、
+默认兜底人或节点管理员修改。缺失记录、空修改人或当前租户内无有效普通用户时，
+事实明确记录跳过原因；数据库或资源绑定失败沿原命令回滚，不产生部分拒绝事实。
+
+能力 `workflow.rejection-notification@1.0.0` 和 Notification Hub 由声明自动推导，平台
+初始化无需增加开关。省略声明或旧固定实例继续原行为。消息只读且没有审批按钮；
+点击仍认证并核验当前详情权限，收到消息不产生资料查看或流程办理权。
+实例原参与消息继续更新终态，专用消息另以实例为键去重。发送仍采用既有 outbox 的
+至少一次语义，沿原回执恢复；本地验证使用站内或 fake 渠道。
+
+应用无需后端或自建事件订阅。可编译例子见
+`examples/workflow-administration/rejection-notification.ts`。
+
+### 提交前检查必需审批人
+
+需要在保存业务资料前确认特定审批节点有人时，可在固定 definition 中声明：
+
+```ts
+launchPreflight: { requiredApprovalNodes: ['departmentReview', 'finalReview'] }
+```
+
+节点必须为实际 approval，最多20个且不能重复；本版只支持 fixed_users、initiator、app_role、app_role_in_scope，不能依赖未来任务补填、外部 provider 或候选字段。BusinessProcess.commit 在业务写入的同一事务内，按当前有效节点配置和真实成员/范围解析这些节点；空人、失效账号、超限或需要尚未提供的交互输入时整笔回滚。emptyPolicy:skip 不能绕过该准入。命中原提交回执时不会重新执行检查。
+
+这是提交准入，不预先冻结未来审批人；实际进入节点仍重新解析。声明要求目标具备 workflow.launch-preflight@1.0.0，未声明的流程保持原提交行为。实际角色与事务回滚需在目标平台验收。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openxiangda",
-  "version": "2.44.0",
+  "version": "2.55.1",
   "description": "OpenXiangda 2.0 的统一命令、应用 SDK、MCP 与中文 AI 技能资料。",
   "type": "module",
   "main": "./dist/index.js",
@@ -60,19 +60,20 @@
   ],
   "dependencies": {
     "@js-temporal/polyfill": "0.5.1",
+    "@rc-component/async-validator": "6.0.0",
     "@rc-component/picker": "1.10.0",
     "@xyflow/react": "12.12.0",
     "antd-mobile": "5.42.3",
     "dayjs": "1.11.18",
     "docx-preview": "0.3.7",
     "elkjs": "0.12.0",
-    "openxiangda-cli": "2.6.37",
-    "openxiangda-contracts": "2.43.0",
-    "openxiangda-devkit-core": "2.41.2",
+    "openxiangda-cli": "2.6.83",
+    "openxiangda-contracts": "2.63.0",
+    "openxiangda-devkit-core": "2.48.2",
     "openxiangda-legacy": "npm:openxiangda@1.0.269",
-    "openxiangda-mcp": "2.0.73",
-    "openxiangda-nest": "2.13.3",
-    "openxiangda-skill-kit": "2.3.52",
+    "openxiangda-mcp": "2.0.101",
+    "openxiangda-nest": "2.14.3",
+    "openxiangda-skill-kit": "2.3.81",
     "xlsx": "https://github.com/1377385356/openxiangda/releases/download/vendor-mirror/xlsx-0.20.3.tgz"
   },
   "peerDependencies": {
@@ -138,39 +139,35 @@
   },
   "openxiangdaRelease": {
     "schemaVersion": "openxiangda.release-notes/v1",
-    "version": "2.44.0",
+    "version": "2.55.1",
     "status": "reviewed",
-    "title": "OpenXiangda 2.44.0：当前任务的托管附件与图片",
-    "summary": "代码任务页面支持根附件与图片，普通审批人通过固定任务上传和预览，草稿保留和正式流程提交复用平台文件生命周期。",
+    "title": "持久原结果恢复与流程字段策略修复",
+    "summary": "已受理命令的短读取超时不会提前终止原三十分钟观察；同步主线的条件必填错误清理和冻结的选填撤回原因策略。",
     "newFeatures": [
-      "任务文件 SDK 支持固定 ID 的原计划与完成恢复，标准 PC/手机上传及预览自动接入。",
-      "编译器按可编辑任务文件申请 workflow.task-managed-files 自动能力，无额外默认关闭开关。"
+      "固定流程定义支持 instanceCommands.withdraw.reasonRequired:false；省略仍必填，新声明要求 workflow.optional-withdrawal-reason@1.0.0。"
     ],
     "fixes": [
-      "上传结果未知时保留原文件与请求并锁住新流程动作和草稿写入；ready 结果不再次 PUT。",
-      "任务表单和本人草稿比较使用任务文件范围，避免依赖通用 CRUD 预览资格。"
+      "已受理 durable 原结果查询收到 SDK 明确标记可恢复的短读取预算耗尽后，在原绝对截止前按退避继续只读查询；不重放提交。",
+      "另一字段解除条件必填后清除 SDK 自己生成的旧必填错误，保留其他客户端、子表和服务端错误。"
     ],
     "affectedUsers": [
-      "声明 file/image 任务补填页面的 V2 应用开发者、办理人和平台维护者。"
+      "使用 durable 持久命令的热点报名应用和包含条件必填或撤回策略的 V2 流程。"
     ],
     "upgradeSteps": [
-      "消费同批本地 SDK/contracts 与匹配平台 Server，应用迁移 AddWorkflowTaskManagedFilesV2，刷新资料并重启。",
-      "局部修改才显示附件字段时先保存补填，再上传；自定义页面固定上传 UUID，并保留原请求处理未知结果。"
+      "使用正式精确版本升级应用 SDK；原结果恢复无需更改服务端协议。",
+      "使用选填撤回原因时，平台必须具备对应能力；已有实例继续使用冻结版本。"
     ],
     "knownLimitations": [
-      "本轮交付根 file/image，签名、富文本和 owned 子表仍按后续任务页面切片验证。",
-      "上传资格依据已保存资料的页面状态；管理员不能配置字段权限。",
-      "本轮是本地迁移实验，npm 发布与学校生产迁移分别另行执行。"
+      "一次读取仍最多两分钟，总观察仍为原三十分钟；权限、依赖和普通网络错误不会被自动隐藏。",
+      "容量必须在目标硬件上独立测量；单元验证不能证明万人或浏览器洪峰已通过。"
     ],
     "issues": [],
     "compatibility": {
       "node": ">=24",
-      "workspaceGenerations": "v2",
-      "platform": "workflow.task-managed-files@1.0.0 与 AddWorkflowTaskManagedFilesV2",
-      "v1": "1.x 引擎独立，本轮不改变其上传入口。"
+      "platform": "durable 恢复沿用既有结果协议；显式选填撤回原因要求 workflow.optional-withdrawal-reason@1.0.0"
     },
-    "sha256": "b4d4027b81772f5c63ef0638b7ffa9c73374799a398bd17c8828ed126410e4da",
-    "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.44.0"
+    "sha256": "c6c0691f9fe9571dfe1c9078546a5db3f63645ba11a67a3f3d0d6324ba7713d1",
+    "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.55.1"
   },
   "scripts": {
     "build": "node ../../scripts/prune-package-dist.mjs && tsc -p tsconfig.json && node scripts/copy-assets.mjs",