openxiangda 2.35.3 → 2.48.2

package/documentation/workflow-events.md

@@ -153,13 +153,55 @@ Workflow 发起只接受 `{ resourceCode, id }` 形式的 `dataRef`，并要求
 
 ## 标准工作流范围
 
-首期只支持 `approval`、`condition`、`end`，以及 `single`、`any`、`all`、`sequence` 审批模式。标准操作为提交、同意、拒绝、退回、重新提交、转交、委托、前/后加签、撤回、管理员改派、管理员终止和不改变流程状态的催办。
+标准节点支持 `approval`、`condition`、`cc`、`end`，以及 `single`、`any`、`all`、`sequence` 审批模式。标准操作为提交、同意、拒绝、退回、重新提交、转交、委托、前/后加签、撤回、管理员改派、管理员终止和不改变流程状态的催办。
 
 除命令集之外，平台为实例管理员提供两个维护动作：`admin_jump`（把处于运行或退回状态的实例跳转到指定节点）与 `admin_delete`（删除实例，可选同时删除表单数据、是否触发自动化）。两者走平台管理端点的预览/执行两步流程并要求同源浏览器请求，不属于应用声明的工作流命令，也不占用 `commandToken` 命令合同。
 
 复杂业务状态机继续放在应用领域服务。不要把任意 JavaScript、Service Task、BPMN、通用长事务或业务记录复制进 Workflow。
 
 所有页面和消息动作必须来自后端 Workflow Surface 的 `operations[]`。前端、模板和渠道 Adapter 不自行推断操作权限。
+
+### 自动抄送 {#automatic-cc}
+
+在固定拓扑中声明 `cc` 节点，进入时解析接收人、保存抄送事实，然后继续 `next`。
+完整声明例子见 `examples/workflow-administration/automatic-cc.ts`：
+
+```ts
+copy: {
+  id: 'copy', kind: 'cc', title: '抄送办理负责人',
+  binding: 'readers', next: 'approved', emptyPolicy: 'block',
+  administration: { assigneeProviders: ['app_role', 'fixed_users'] },
+},
+```
+
+接收 binding 支持 `fixed_users`、`initiator`、`input_users`、`form_field_users`、
+`app_role`、`app_role_in_scope`、`previous_node_actor`。仅使用事务内原生来源，
+不支持 `application_provider` 或需要申请人交互的 `initiator_select`。名单按用户去重，
+每次进入最多 20 人；`min/max` 默认 1/20，非空名单仍必须符合声明的下限。
+角色查询超过 200 条有效成员行时明确拒绝，不能使用截断后的名单。
+范围角色要求对应范围的 `cc` 授权（或未限制操作、`*`），仅 `approve` 不满足。
+抄送不套用审批代理。
+
+`emptyPolicy: 'block'` 在真实空名单时回滚触发动作，补齐人员后可重试原申请或任务；
+`'skip'` 记录无人跳过并继续。未知角色、失效账号、非法输入和超限均属于错误，
+不会被 skip 吞掉。通知默认开启；`notify: false` 仍保存抄送审计、事件和实例阅读关系，
+Notification Hub 不生成该次抄送消息。渠道失败通过原 Hub 恢复，不回滚流程。
+
+进入记录、系统抄送日志及事件在同一事务提交。原命令重放不重复抄送；退回等导致实际
+再次进入时产生新轮次，可采用新的兼容节点配置，过去名单和配置保持冻结。时间线显示
+“流程自动抄送”，不会把系统动作记为发起人的人工操作。
+
+接收人可以使用既有抄送列表及实例详情，不获得审批权、后台权限或通用业务数据读取权。
+标准流程详情由服务器按页面代码声明的固定详情字段投影读取；需要排除敏感字段时，
+在 `crud.detail` 和 `subject.factProjection` 中明确选择允许字段，不能仅在浏览器隐藏。
+通用 Data API 继续核验当前数据授权，流程节点不提供字段权限配置。
+
+含 cc 的包自动声明 `workflow.automatic-cc@1.0.0`，平台正式迁移后自动提供该能力，
+没有额外开关。管理员仅可修改名称、说明及代码显式开放的接收来源，
+`next/emptyPolicy/notify` 保持代码所有；配置 SDK 见[应用管理](./administration.md#node-administration)。
+
+### 工作流命令
+
 Surface 同时签发短期、一次性的 `commandToken`，绑定当前用户/会话、应用环境
 Head、实例/任务版本、允许的命令集合与 CSRF。命令请求只提交
 `commandToken + idempotencyKey + input`；旧的 caller-authored
@@ -242,8 +284,8 @@ Native Data 事件的 capture plan 由当前 Head 的 Event、Data、AuthZ revis
 不是增量 patch。definition 和 activation 必须一致声明
 `acceptedCommandDeactivationPolicy`：`finish-pinned` 让已接受的 durable process
 command 按固定版本完成，`cancel-on-deactivate` 在声明删除后取消尚未启动的命令；
-既有 Workflow instance 始终按固定版本继续。所有审批人 Provider 的 `min/max`
-默认 1/200，最大 200。
+既有 Workflow instance 始终按固定版本继续。审批人 Provider 的 `min/max`
+默认 1/200，最大 200；自动抄送默认 1/20，最大 20。
 需要按流程实例串行投递时只声明 `ordering: 'workflow-instance'`，不接受下划线别名。
 
 平台按 desired set 直接覆盖环境 Head，不做版本比较。因此 `openxiangda deploy`
@@ -401,4 +443,262 @@ 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 的业务含义，业务说明及验收仍由开发者维护。
+
+## 持久业务步骤
+
+必须收到业务计算或外部操作结果后才继续的流程，用固定 `action` 节点。平台自动
+提供 `workflow.durable-business-step@1.0.0`；应用包含动作时自动声明能力需求并
+按需引导标准 Nest 后端，普通无动作应用保持原合同。字段显隐/编辑/必填继续由
+页面代码负责；动作版本、Schema、条件和连线只由开发者发布。
+
+```ts
+const amountSchema = { type: 'object', additionalProperties: false,
+  required: ['amountCents'], properties: { amountCents: { type: 'integer', minimum: 0 } } };
+// 放入已声明流程的 nodes；amount-route 必须是同一固定定义中的真实目标。
+const calculate = {
+  id: 'calculate', kind: 'action', title: '核算金额', next: 'amount-route',
+  handler: { code: 'calculate-v1', version: 1, mode: 'pure' },
+  inputSchema: amountSchema, outputSchema: amountSchema,
+  inputs: { amountCents: { source: 'fact', path: 'amountCents' } },
+};
+// 放入 events.subscriptions；应用 backend.enabled=true，消费 generated manifest。
+const subscription = {
+  code: 'calculate-v1', eventTypes: ['openxiangda.workflow.step.requested.v2'],
+  filter: { workflowStep: { handlerCode: 'calculate-v1' } },
+  payload: { includeChanges: false, fields: [] },
+};
+```
+
+成功输出写入 `steps.calculate.amountCents`。后续条件或动作只能读取每条路径上
+已经完成的生产者；前向/自引用、非法路径和输入类型不兼容会拒绝编译。步骤后
+需要 HTTP provider 或发起人选人的组合暂不支持，先在动作中产生有 Schema 的
+人员数据，再使用原生人员字段/角色分派。示例见
+`examples/workflow-administration/business-step.ts`。
+
+Nest 使用 `@OpenXiangdaEventHandler(generatedContract)` 注册实现，`handle` 返回
+`{ output, receipt? }`；上下文 `workflowStep` 包含验证过的固定请求，
+`idempotencyKey` 是稳定 executionId。不得通过返回值任意指定下一节点或调用
+Workflow 跳转。使用标准 `PlatformOpenXiangdaEventReceiptStore`；内存 receipt
+不能完成业务步骤。
+
+`pure` 用于无外部效果的计算；`reconciled-effect` 必须实现 `reconcile(event,
+context)`：成功返回 `{ status:'succeeded', result:{output,receipt?} }`，确定未执行
+返回 `{status:'not-executed'}`，无法确定返回 `{status:'unknown'}`。每次尝试先
+核对原执行键，未知结果需要人工核对后重放原事件。增加v2时保留v1合同及代码；
+旧具名版本合同不可变，缺失实现明确失败，不自动改用最新版本。
+
+输入输出各16KiB、回执2KiB，最多32映射、200节点；Schema闭合且有界，无远端
+引用或正则执行。平台先持久保存合法结果，再尝试流转；下游缺人等失败保留
+`result_ready`，恢复仅推进，不再次执行处理器。自动恢复最多5次，每批20；
+outbox容量等事务故障会回滚，处理器按原键核对后重交，不承诺跨服务绝对一次。
+撤回后的未领取步骤拒绝执行，已开始的外部操作仍需原键核对。
+
+管理员在标准实例管理页或 `WorkflowBusinessStepRecoveryPanel` 查看并继续受阻
+步骤；公开客户端为 `loadWorkflowBusinessStepRecovery`、
+`previewWorkflowBusinessStepRecovery`、`executeWorkflowBusinessStepRecovery`。
+复用原管理权限/token/CAS/CSRF/审计，提交失败保留相同token/input/idempotencyKey。
+组件通过 `onDraftStateChange` 报告 dirty/busy/unknown；宿主将其接入已有导航保护，
+提交中或结果未知时保留组件和实例。未知结果只允许显式重试原恢复请求；首次明确
+的4xx拒绝可保留原因并重新预览。宿主刷新失败不改变已经确认的提交结果。
+等待处理器的失败从原事件管理受控重放，保留原执行键。普通详情只显示安全状态
+摘要；原输入、输出和外部回执不放入普通时间线。
+
+## 代码任务页面与补填 {#task-page-submit}
+
+需要办理人补填时，在定义的 `taskPages` 声明命名页面，审批节点以
+`taskPageCode` 引用。页面字段顺序、`readonly`、`required`、`visibleWhen` 和
+`requiredWhen` 属于应用代码；流程管理员不能覆盖页面字段、条件或连线。
+字段类型和编码来自同一个 Native 模型。例子见
+`examples/workflow-administration/task-page.ts`。
+
+页面表达式只读取本页 `values.*`，平台以合并后的业务值强制显隐和必填。
+最多16页、每页64字段、单次值1MiB，表达式8层/64节点。
+系统、流水号和隐藏字段不可作为补填入口。根附件、图片复用平台托管文件；
+签名和富文本同样保留 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` 表示“提交补填，继续办理”，不是私有草稿。
+approve/resubmit 携带 `form: { expectedRevision, values }` 时，Native 业务更新、
+事实刷新、任务决定和下游流转同事务提交。reject/return/transfer 等操作不得
+夹带表单。审批人仅获得当前任务对应的单记录/页面字段入口，不获得通用 CRUD。
+
+相同幂等键不同输入拒绝；结果未知时保留原 token/input/key。共享组件锁定
+编辑，只重试原请求或调用 `loadWorkflowTaskCommandReceipt(taskId, key, tokenDigest)`
+查询本人原回执。重载只保存定位信息和 SHA256 token 摘要，不保存凭据或表单。
+`not_observed` 仍然未知；只有平台锁住确切凭证、确认数据库时间已过期且未使用
+的 `expired_unconsumed` 才能解除等待，供用户核对资料后重新确认。
+组件复用宿主的 `OpenXiangdaApplication` 导航保护；成功后刷新失败不变成提交失败。
+
+嵌入自定义详情时，可用 `renderLayout={({ content, actions, surface }) => ...}` 将补填表单和
+恢复提示放在可滚动正文，将操作按钮放在底栏。两部分始终使用同一个任务面板，
+不要分别创建两个面板或复制其表单、请求和回执状态。`surface` 是面板当前实际展示的
+资料，自定义详情用它显示刷新后的字段；加载或无可用资料时为空。标准详情已采用该布局。
+
+多人补填与管理纠错使用 Native 记录 CAS，冲突保留输入。首次请求的明确拒绝会只读刷新，
+修订变化时对照最新已保存值和本人输入，核对前锁住字段与操作；可选择保留输入或采用最新值。
+拒绝后的读取失败明确提示本次未提交，锁住旧操作，恢复读取后再核对；未知结果仍只能恢复原请求。
+补填刷新固定事实投影；
+修改已计算步骤的输入时清除当前失效输出及依赖输出。仅退回 replay 且所有前向
+审批路径确定重经生产者时允许；resume_current 或后置补填跳过重算会返回
+`WORKFLOW_TASK_FORM_RECOMPUTATION_REQUIRED` 并回滚，历史结果与签名保持。
+自动能力为 `workflow.task-page-submit@1.0.0`，平台初始化无需额外开关。
+
+### 任务私有草稿
+
+标准PC/手机任务页和嵌入面板提供“保存私有草稿”“我的草稿”。暂存仅本人可见，
+不会更新业务资料、事实、待办或推进任务；可以保存尚未完成必填的标量输入。
+页面的显隐/只读规则和Native类型仍强制，管理员没有字段覆盖或读取他人草稿的入口。
+
+自定义页面从 `openxiangda/core` 或 `openxiangda/react` 调用
+`loadWorkflowTaskDrafts(taskId)`、`saveWorkflowTaskDraft(taskId, input)` 和
+`removeWorkflowTaskDraft(taskId, { id, expectedRevision })`。
+保存输入为 `{ id, expectedRevision, recordRevision, values }`：首写前固定UUID及
+`expectedRevision: 0`；recordRevision来自当前taskForm.expectedRevision。
+身份、环境、业务记录和固定页面由平台派生，不传actor/resource/page作为授权。
+可编译例子见 `examples/workflow-administration/task-draft.ts`。
+
+最多20份/90天与同用户、应用、环境、资源的其他表单草稿共享，单份最多64根字段/1MiB。
+字段支持根附件、图片、完整业务签名和富文本，暂不包含 owned 子表。读到不兼容草稿时只返回安全标识与诊断，
+不静默丢弃或泄露旧值。失去任务、角色或代理资格后不能继续读/用。
+
+读取不会自动覆盖输入；采用前确认，业务基线变化先核对并再次保存。相同输入暂存成功后
+可安全离开，后续新编辑恢复导航保护；浏览器持久存储不保存字段值。
+结果未知保留原id/CAS/values，仅核对同id或重试原保存；同一次最后保存确认不新增修订，
+其他CAS冲突保留输入。新id必须是用户明确另存，不能用自动另存掩盖未知结果。
+
+正式 `form: { expectedRevision, values, draft: { id, expectedRevision } }` 可以包含暂存之后的新编辑。
+平台锁住本人草稿及业务基线，再沿原save_form/approve/resubmit命令同事务更新业务并消费，
+失败全部回滚。原成功命令重试先返回唯一Workflow回执，不因草稿已消费重复写入。
+任务真正关闭才过期未消费草稿，all/sequence任务仍可办理时保留其他人的有效草稿。
+能力 `workflow.task-private-drafts@1.0.0` 自动提供，无额外配置开关。
+
+### 任务附件与图片
+
+当前任务的可编辑 `file/image` 字段自动接入标准 PC/手机上传、缩略图、预览和下载。
+当前处理资格不授通用资源 CRUD；平台从固定任务派生记录、页面、身份和环境，
+上传时还核验**已保存业务资料对应的页面状态**。局部修改才显示附件字段时，
+先“保存补填”使字段生效，再上传；组件说明此边界，不自动提交业务值。
+
+自定义页面可从 `openxiangda/core` 或 `openxiangda/react` 调用：
+
+```ts
+const input = { id: crypto.randomUUID(), fieldCode: 'evidence',
+  fileName: file.name, fileSize: file.size, contentType: file.type };
+const plan = await initiateWorkflowTaskFileUpload(taskId, input);
+// pending 才按 plan.uploadMethod/uploadUrl/headers 上传原 File；ready 直接采用 plan.file。
+const readyFile = await completeWorkflowTaskFileUpload(taskId, input.id);
+// 结果未知时：loadWorkflowTaskFileUploadPlan(taskId, input.id)，或重试同 ID/规格。
+```
+
+上传 ID 必须在第一次请求前固定。标准组件一次处理一个文件；上传中或结果未知时
+保留原 File、ID、规格和当前输入，锁住新任务动作与草稿写入，提供“核对原上传”
+和“重试原上传”。ready 结果不再 PUT；完成响应丢失后只恢复原完成结果。
+文件字节、签名地址与表单值不进入浏览器持久存储。离开未完成上传时需先确认结果。
+
+预览字段组件传入 `workflowFileBinding: { taskId, resourceCode, recordId, fieldCode }`；
+正式实例详情使用原 `instanceId` binding。同一 binding 只提供一种范围。
+仅本人当前任务可读私有暂存文件，其他处理人和管理员没有私有读取特权。
+当前根业务记录已经引用的文件可按该任务页面规则读取；隐藏、资格失效或任务关闭后拒绝。
+通用 Native 完成、删除和未绑定文件读取不能绕过此范围。
+
+附件完成后仍只是当前输入；私有草稿延长文件保留至该草稿到期，业务绑定再移除引用
+仍尊重该保留期。原 save_form/approve/resubmit 验证真实文件状态、字段、范围与元数据，
+同事务提交业务引用、事实、任务决定和草稿消费；失败全回滚。完成上传时平台复制为
+独占正式对象，旧上传地址不能再修改正式字节。
+
+单文件不超过字段限制与100MiB；每账号/应用/环境最多100个尚未业务绑定的任务文件，
+声明大小合计200MiB。此大小是上传容量预算，staging/正式对象与缩略图另有存储开销。
+复用既有 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。当前任务、实例、记录或字段改变时清理旧图片预览，重新按范围读取。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openxiangda",
-  "version": "2.35.3",
+  "version": "2.48.2",
   "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.21",
-    "openxiangda-contracts": "2.35.0",
-    "openxiangda-devkit-core": "2.36.0",
+    "openxiangda-cli": "2.6.52",
+    "openxiangda-contracts": "2.47.0",
+    "openxiangda-devkit-core": "2.41.6",
     "openxiangda-legacy": "npm:openxiangda@1.0.269",
-    "openxiangda-mcp": "2.0.63",
-    "openxiangda-nest": "2.11.1",
-    "openxiangda-skill-kit": "2.3.41",
+    "openxiangda-mcp": "2.0.77",
+    "openxiangda-nest": "2.13.7",
+    "openxiangda-skill-kit": "2.3.57",
     "xlsx": "https://github.com/1377385356/openxiangda/releases/download/vendor-mirror/xlsx-0.20.3.tgz"
   },
   "peerDependencies": {
@@ -138,49 +139,32 @@
   },
   "openxiangdaRelease": {
     "schemaVersion": "openxiangda.release-notes/v1",
-    "version": "2.35.3",
+    "version": "2.48.2",
     "status": "reviewed",
-    "title": "OpenXiangda 2.35.3：运行时繁忙恢复与可读流程图",
-    "summary": "应用进入时可有界等待平台明确的繁忙响应，同身份刷新保留页面和原申请；流程图使用与不可变执行定义同源的投影展示说明、变量来源与实例路径。",
-    "newFeatures": [
-      "现有运行时 current 读取在明确的入口繁忙时按服务端提示和抖动退避，最长等待五分钟、最多一百二十次读取，并支持离页取消。",
-      "公开 WorkflowReadability、validateWorkflowReadability、projectWorkflowGraph 及共享 WorkflowDiagram，展示流程说明、条件优先级、变量来源和持久执行决定对应的路径，支持搜索、键盘及窄屏节点列表。",
-      "流程图使用懒加载 React Flow 与 ELK 正交布局，支持直角连线、平移缩放、节点定位、分支条件标签和缩略导航。",
-      "审批节点可显式声明管理员可调整的模式、人员来源和按钮上限；编译器复用有界校验，SDK 提供配置读取、CAS 更新和幂等回执，任务冻结有效配置。"
-    ],
+    "title": "子表输入与整表提交校验",
+    "summary": "保留子表分页的全部校验，在提交时定位离页错误，输入时稳定停留在当前页。",
+    "newFeatures": [],
     "fixes": [
-      "启动、焦点和可见性检查合并挂起身份读取；同身份刷新保留已验证页面和草稿，临时服务故障可重新检查，真实身份、环境、权限作用域变化或拒绝使旧受管客户端失效。",
-      "退出通知优先于仍在加载的身份请求，旧响应和取消回调不会恢复旧身份或覆盖登录入口。验证 current 成功后仅清除当前路径的入口等待截止。",
-      "安全只读传输故障最多三次总尝试；权限投影等待保留原十秒限制，普通应用请求和写入不会因本次修改自动重放。",
-      "管理员流程节点配置使用平台已有的 admin controller，修正上下文、配置读取和保存地址，保留环境、CAS、幂等操作标识与权限拒绝。",
-      "管理员流程节点配置保留平台返回的具体冲突错误码，页面可准确提示配置修订和幂等冲突。",
-      "StrictMode 同一提交的清理、重挂载接管原 current owner，避免重复初始化读取；观察取消立即生效，无人接管时释放共享请求，安装身份必须仍有活跃观察者，原读取预算与退出优先级保留。",
-      "标准任务和实例详情按应用声明返回对应设备的用户流程中心，避免普通申请人被带入管理后台；独立详情组件可显式指定返回路径，抽屉关闭和页面授权保持原行为。"
+      "父级子表完整校验只在显式校验或提交时执行，避免逐键扫描全部行并跳转至尚未填写的页；当前页字段仍即时反馈。"
     ],
     "affectedUsers": [
-      "使用 V2 运行时及持久排队能力的活动报名、预约、抢票应用开发者。",
-      "需要展示不可变流程定义、说明及实例执行路径，或启用有界审批节点配置的平台维护者和应用开发者。"
+      "使用V2标准主子表、流程发起或任务办理页面的用户。"
     ],
     "upgradeSteps": [
-      "将应用 openxiangda 精确升级到 2.35.3；平台流程图消费者将 openxiangda-contracts 精确升级到 2.35.0，同批工具链使用 openxiangda-devkit-core 2.36.0 和 openxiangda-cli 2.6.21，更新锁文件。",
-      "统一验证运行时繁忙恢复、同身份刷新、退出与真实身份切换，以及流程图说明与持久执行路径后发布同一冻结候选；启用管理员节点配置时确认平台支持 workflow.node-administration。",
-      "在目标服务器另外测量完整页面进入、提交、自然结果查询及最终处理时间；客户端恢复测试不作为硬件并发容量证据。"
+      "升级精确SDK/CLI并重新构建应用；本修正不引入服务端迁移或数据格式变更。",
+      "本任务仅本地包消费与合成验证，不执行npm发布。"
     ],
     "knownLimitations": [
-      "运行时繁忙恢复只用于现有 current 读取；未知 429、权限或版本拒绝和非繁忙依赖失败不扩展等待，初始化成功不表示业务请求已经受理。",
-      "本次发布保留持久申请的原请求键、观察截止和自然轮询策略；队列的受理、执行和最终结果仍由平台负责。",
-      "流程图说明不改变不可变执行定义及持久实例决定，不补造不存在的执行边，也不改变流程授权。",
-      "管理员节点配置只调整应用明确开放的边界，字段行为继续由应用页面与代码维护；未声明该能力的应用不启用新的配置入口。"
+      "分页是渲染边界，数据和事务仍遵守原先每表100行、声明合计400行等预算。",
+      "最大附件组合与学校完整源流程运行验收仍单独验证。"
     ],
     "issues": [],
     "compatibility": {
       "node": ">=24",
-      "workspaceGenerations": "v2",
-      "platform": "入口繁忙恢复需要平台提供 CONCURRENCY_BOOTSTRAP_BUSY 或 CONCURRENCY_API_BUSY 契约；可读流程图需要匹配的只读平台接口，管理员节点配置需要 workflow.node-administration 能力。持久排队沿用 data.managed-concurrency.durable@1.0.0。",
-      "v1": "V1 分发引擎及业务不变。"
+      "platform": "沿用2.48.0匹配平台；1.x不消费此组件"
     },
-    "sha256": "31ce7268d3e443bf8fd5d26f0be82be6b1a24ff22f25d0735c7abf4a83fe92dd",
-    "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.35.3"
+    "sha256": "bfc22a1f10ca53c3d5146d4e0b797363afa4f0ae78dda80b0a9724e74d0bc4f9",
+    "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.48.2"
   },
   "scripts": {
     "build": "node ../../scripts/prune-package-dist.mjs && tsc -p tsconfig.json && node scripts/copy-assets.mjs",

package/releases/2.48.1.json

@@ -0,0 +1,30 @@
+{
+  "schemaVersion": "openxiangda.release-notes/v1",
+  "version": "2.48.1",
+  "status": "reviewed",
+  "title": "大子表分页与整表校验",
+  "summary": "PC与手机主子表每页渲染十行，保留完整输入、草稿、排序和整单提交；校验覆盖全部行。",
+  "newFeatures": [],
+  "fixes": [
+    "减少大子表同时挂载的编辑控件；未显示行继续复用标准字段规则校验，任务完成的错误定位到对应页。",
+    "跨页移动使用绝对行序号，上传和待重试文件未处理时保留当前页。"
+  ],
+  "affectedUsers": [
+    "使用V2标准主子表、流程发起或任务办理页面的用户。"
+  ],
+  "upgradeSteps": [
+    "升级精确SDK/CLI并重新构建应用；本修正不引入服务端迁移或数据格式变更。",
+    "本任务仅本地包消费与合成验证，不执行npm发布。"
+  ],
+  "knownLimitations": [
+    "分页是渲染边界，数据和事务仍遵守原先每表100行、声明合计400行等预算。",
+    "最大附件组合与学校完整源流程运行验收仍单独验证。"
+  ],
+  "issues": [],
+  "compatibility": {
+    "node": ">=24",
+    "platform": "沿用2.48.0匹配平台；1.x不消费此组件"
+  },
+  "sha256": "ba545c3aadbbc7a8b4b31de91b2257dd1600df59c20e05e0ec452c0bf07362b0",
+  "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.48.1"
+}

package/releases/2.48.2.json

@@ -0,0 +1,29 @@
+{
+  "schemaVersion": "openxiangda.release-notes/v1",
+  "version": "2.48.2",
+  "status": "reviewed",
+  "title": "子表输入与整表提交校验",
+  "summary": "保留子表分页的全部校验，在提交时定位离页错误，输入时稳定停留在当前页。",
+  "newFeatures": [],
+  "fixes": [
+    "父级子表完整校验只在显式校验或提交时执行，避免逐键扫描全部行并跳转至尚未填写的页；当前页字段仍即时反馈。"
+  ],
+  "affectedUsers": [
+    "使用V2标准主子表、流程发起或任务办理页面的用户。"
+  ],
+  "upgradeSteps": [
+    "升级精确SDK/CLI并重新构建应用；本修正不引入服务端迁移或数据格式变更。",
+    "本任务仅本地包消费与合成验证，不执行npm发布。"
+  ],
+  "knownLimitations": [
+    "分页是渲染边界，数据和事务仍遵守原先每表100行、声明合计400行等预算。",
+    "最大附件组合与学校完整源流程运行验收仍单独验证。"
+  ],
+  "issues": [],
+  "compatibility": {
+    "node": ">=24",
+    "platform": "沿用2.48.0匹配平台；1.x不消费此组件"
+  },
+  "sha256": "bfc22a1f10ca53c3d5146d4e0b797363afa4f0ae78dda80b0a9724e74d0bc4f9",
+  "url": "https://github.com/1377385356/openxiangda/releases/tag/v2.48.2"
+}

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": "e70281f337585990895c4f75765c55b759167506656749d865fc749b6c2419ac"
+      "sha256": "b8d9f8625838d2c246b059fb8d14ac107fa1a8183f7bb3066e1fcad10087f1ed"
     }
   ]
 }

package/skills/openxiangda-v2/SKILL.md

@@ -40,10 +40,10 @@ AI 接到新应用、页面或改版任务时，在同一个 OpenXiangda 工作
 未创建工作区时使用本 Skill 随根包发布的精确版本：
 
 ```bash
-pnpm dlx openxiangda@2.35.3 auth status --cwd <应用目录> --base-url <平台地址> --json
-pnpm dlx openxiangda@2.35.3 login --cwd <应用目录> --base-url <平台地址>
-pnpm dlx openxiangda@2.35.3 create <应用目录> --base-url <同一平台地址>
-pnpm dlx openxiangda@2.35.3 skill install --force
+pnpm dlx openxiangda@2.48.2 auth status --cwd <应用目录> --base-url <平台地址> --json
+pnpm dlx openxiangda@2.48.2 login --cwd <应用目录> --base-url <平台地址>
+pnpm dlx openxiangda@2.48.2 create <应用目录> --base-url <同一平台地址>
+pnpm dlx openxiangda@2.48.2 skill install --force
 ```
 
 创建前把产品要求的目标平台明确带入命令，不从旧登录态推断站点。已有工作区从原绑定恢复，平台不一致时先解决登录与目标，不改 link 文件跨站创建。