openxiangda 2.55.1 → 2.59.1

package/documentation/getting-started.md

@@ -68,10 +68,10 @@ MCP 服务随项目根包一起安装，AI 客户端的 stdio 连接仍需配置
 以下命令的版本占位符由随包资料替换为该根包的精确版本。网站源码阅读者应先确认要使用的发行版本。
 
 ```bash
-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
+pnpm dlx openxiangda@2.59.1 skill install --force
+pnpm dlx openxiangda@2.59.1 auth status --base-url <平台地址> --json
+pnpm dlx openxiangda@2.59.1 login --cwd my-app --base-url https://platform.example.com
+pnpm dlx openxiangda@2.59.1 create my-app --base-url https://platform.example.com
 cd my-app
 pnpm openxiangda context --json
 pnpm openxiangda dev
@@ -121,6 +121,36 @@ AppSpec 随开发持续维护：测试发布前补齐总纲、关联变更与验
 
 前端启动使用根目录 `dev:web`。声明了后端的应用同时运行配置的 `backend.root` 包内的 `dev`，无需增加根目录 `dev:server`；纯前端应用只启动 Web 和代理。已有前端测试版本后，可以启用本地 Nest 联调，不必先构建或发布后端镜像。平台返回的活动应用版本和开发会话绑定本次联调，环境版本变化导致会话不一致时，停止后重新运行 `dev`。
 
+在已有测试环境的应用中，`dev` 先将当前完整资源、权限、具名操作和固定流程配置
+提交给平台。平台使用同源编译器校验配置与契约，保存真实配置版本和同步回执，
+选择该应用 test 的配置 Head，然后 CLI 重新读取环境并创建开发会话。这个过程
+不运行应用 `build`、打包或容器部署；代码继续在本机运行。相同配置与契约再次启动
+时复用当前版本；旧 Head 的开发会话失效，需要重新启动。新增模型和流程可以在
+同一批开发中联调，不需要每次冻结 SDK 和正式部署应用。
+
+完整开发配置要求平台提供 `application.development-configuration` 1.0.0，并且
+应用已有 test Native Head；当前尚不支持无测试基线的新应用直接同步。同步会改变
+test 的配置选择，历史正式版本、数据和原运行保留。开发配置不能用于生产晋级、
+正式部署或回滚候选。
+
+声明后端的应用还要求 `application.development-backend-events` 1.0.0。CLI自动连接
+当前test开发版本，把平台已签名的后台事件和流程业务步骤投递到本机Nest源码，
+并复用平台的持久执行回执与失败恢复。应用运行凭据只进入本地Nest环境，不传入Web、
+页面或终端状态。开发连接关闭或失联时，事件保留在平台队列，不回退到旧后端制品；
+同一测试环境同时只能连接一个开发会话，环境版本变化后重新运行dev。
+临时运输故障会在20秒内恢复原连接；已执行处理器的回复只重发原响应，不重复执行业务。
+授权、环境版本或连接归属变化会立即停止；超过恢复窗口则保留平台原执行记录，重新运行dev继续。
+
+开发连接会启用当前后台事件订阅，保留手工暂停；正常关闭时暂停本连接开启的订阅。
+Timer和DateTrigger继续暂停，日期提醒仍须确认测试副作用意图并完成专门验收。
+当前投递范围是标准后台事件与流程业务步骤；自定义审批人provider、managed-command
+planner等调用仍须正式后端或后续能力。不要把本地开发者联调视为普通角色验收。
+
+同步失败保留原配置运行 ID；相同输入重试复用原回执与版本，并由平台锁和 Head
+CAS 判断是否允许继续。并发请求返回进行中；服务重启释放锁后允许恢复原运行。
+不要修改环境 ID、直接写配置表或换随机键绕过错误。平台缺能力时更新配套平台，
+不通过重复打包应用规避开发能力缺口。
+
 纯 CRUD 修改优先使用标准模型、字段和页面；跨模型事务或外部副作用再选择后端。角色、行和字段权限在平台执行。详见[开发流程](./development.md)、[模型与标准 CRUD](./application-foundation.md)和[按需后端](./backend.md)。
 
 ## 应用源码
@@ -174,9 +204,9 @@ MCP 的 `docs_read` 可以读取本说明，当前没有独立的源码操作 MC
 无需本地工作区，使用本 Skill 随包精确版本或已安装的对应 CLI：
 
 ```bash
-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
+pnpm dlx openxiangda@2.59.1 auth status --base-url <平台> --json
+pnpm dlx openxiangda@2.59.1 source resolve <仓库URL> --base-url <平台> --json
+pnpm dlx openxiangda@2.59.1 source clone <仓库URL> <新目录> --base-url <平台> --json
 ```
 
 登录缺失或站点不匹配时，先按该平台执行 login。resolve 根据平台已经登记的绑定返回
@@ -227,6 +257,29 @@ openxiangda link rebind --base-url https://platform-b.example.com   # 显式换
 幂等初始化处暴露，随时可以再次 rebind 修正。详细决策记录见仓库
 `docs/architecture-decisions/workspace-platform-rebind.md`。
 
+### 普通角色与应用登录联调
+
+`pnpm openxiangda dev --identity browser` 使用应用自身的登录入口验证普通用户；
+新模板已接入开发模式挂载插件。既有 Vite 应用在 `vite.config.ts` 中从
+`openxiangda/config` 导入 `createConnectedDevelopmentVitePlugin`，加入 `plugins`。
+插件只在 CLI 的普通身份连接开发模式下提供标准运行时挂载信息；正式构建及
+默认开发者模式不受影响，登录、Cookie、CSRF 与实时角色仍由平台管理。
+退出后仍保持应用登录模式。默认的 `developer` 模式方便开发者联调，但已携带应用
+浏览器 cookie 或不同显式 Bearer 的请求保留原身份。失效 cookie 由平台拒绝，不会
+回退开发者身份。登录、退出和 CSRF 均由平台处理。
+
+普通用户的 Data API 和业务操作经过平台授权。预发布开发配置已激活、平台支持
+`application.development-backend-invocations` 且当前 CLI 连接存活时，已声明的业务
+operation 通过平台网关进入本地 Nest 源码；浏览器身份、CSRF 和原幂等键保持不变。
+平台在派发和 Nest 验证时重查身份、角色与当前版本，浏览器不会取得开发者凭据。
+
+这条联调路径支持有限缓冲 HTTP：请求最多 256 KiB，响应最多 1 MiB，每环境事件与
+业务调用共用 8 个运输槽，普通调用最多等待 30 秒；SSE 明确拒绝，托管文件使用平台
+文件接口。关闭或撤销连接、停止环境、切换 Head 都使旧调用失效。回执丢失沿原
+意图查询或恢复，不生成第二次业务提交。正式部署仍走已激活的正式后端。
+旧平台与事件专用连接不支持此路径；启用后端的 `--identity browser` 会提示配套升级。
+源码测试与批次正式构建、激活、普通角色验收分别记录。
+
 ## 检查与交付 {#delivery}
 
 只检查时运行 `pnpm openxiangda check`。需要部署测试环境时直接运行 `pnpm openxiangda deploy`，它已包含检查、测试和构建；无需再连续重复运行全部脚本。

package/documentation/managed-concurrency-frontend.md

@@ -49,9 +49,9 @@ export async function readOffer(
 
 将读取接入应用已有的异步查询状态：初次加载显示局部骨架，空数组显示无可展示内容，失败提供局部重试。组件卸载或资源变化时中止旧请求，迟到响应不能覆盖新资源。同页多个观察者可复用应用已有查询层，查询键包含 `client.scope`、读取 code 和规范化参数，身份变化时清除旧主体视图；当前没有内置的 `useManagedRead` hook。
 
-### 只读预算繁忙恢复
+### 只读繁忙与断连恢复
 
-`read`、`mine`、`result`、`allocation` 共用有界恢复：单次调用默认含 HTTP 和等待的总预算 120 秒，最多 12 次总请求。应用可以通过 `budgetMs` 显式延长；超过 120 秒时最多 120 次总请求，预算上限为 30 分钟，超出上限按 30 分钟处理。只重试 HTTP 429 的 `CONCURRENCY_API_BUSY`、`CONCURRENCY_RESULT_BUSY`、`CONCURRENCY_RATE_LIMITED`、`CONCURRENCY_SOURCE_BUSY`；兼容旧平台的 HTTP 503 仅限前两个已知预算错误。明确 `retryable: false`、未知 429、权限拒绝、Redis/数据库/授权依赖失败和网络失败直接返回，不用繁忙重试掩盖。
+`read`、`mine`、`result`、`allocation` 共用有界恢复：单次调用默认含 HTTP 和等待的总预算 120 秒，最多 12 次总请求。应用可以通过 `budgetMs` 显式延长；超过 120 秒时最多 120 次总请求，预算上限为 30 分钟，超出上限按 30 分钟处理。可恢复的预算响应为 HTTP 429 的 `CONCURRENCY_API_BUSY`、`CONCURRENCY_RESULT_BUSY`、`CONCURRENCY_RATE_LIMITED`、`CONCURRENCY_SOURCE_BUSY`；兼容旧平台的 HTTP 503 仅限前两个已知预算错误。认证传输层标记为 HTTP 503、`PLATFORM_TRANSPORT_UNAVAILABLE` 的连接中断也按原预算恢复。明确 `retryable: false`、未标记的网络错误、未知 429、权限拒绝、Redis/数据库/授权依赖失败直接返回；连接中断不证明请求已受理或业务失败。
 
 第一次失败后的基础等待为 2 秒，之后指数增加到最多 30 秒；取其与有效服务端提示的较大值，再加 0% 至 25% 随机抖动。提示优先使用合法 `Retry-After`（秒或 HTTP 日期），缺失时使用 `data.retryAfterMs`。若等待达到剩余预算，不提前查询，直接返回最后一次繁忙错误；请求次数用完也保留最后繁忙响应。正在进行的请求超过总预算则中止并返回 `CONCURRENCY_READ_RECOVERY_EXHAUSTED`，不以之前的繁忙响应掩盖悬挂请求。
 
@@ -236,10 +236,16 @@ hook 从 `openxiangda/react` 和 `openxiangda/mobile` 导出。state、initializ
 
 已受理申请的自动观察最多持续到首次明确提交后的 30 分钟，默认受理恢复仍为 120 秒，两者分别计算。自动观察的每次结果读取同时受单次 120 秒和原提交剩余时间限制；刷新和 resume 不重新获得观察时间。跨设备没有本地首次时间时，用原回执 acceptedAt 计算观察窗口，不能以页面挂载时间重新计时。达到窗口后保留原意图，状态为 recovering、isObserving 为 false，提示稍后核对；明确 refresh 仍可用有界初查预算查询迟到终态，但不重新启动已经到期的自动观察，也不自动提交。
 
-正常待处理结果每次至少间隔 5 秒，遵守更长的服务端 retryAfterMs，再加随机抖动。单次只读恢复耗尽且仍是已知预算繁忙时，外层可在原观察窗口内指数退避继续。SDK 自身明确标记为 status=504、retryable=true 的 CONCURRENCY_READ_RECOVERY_EXHAUSTED 也只在已受理原结果观察中按退避恢复；它不代表服务端忙，不延长原三十分钟截止，也不触发再次提交。权限、依赖、普通网络错误、其他 504 或未标记可恢复的错误立即停止自动观察，显示 error 并保留原回执和请求键。终态停止。受理恢复中核对原结果同样只允许已知预算繁忙继续，读取依赖失败不能被外层重试隐藏。一个业务区域只挂载一个观察者。离开或关闭页面不撤销已受理请求，平台自动继续；新设备通过 mine 找到本人的原请求。position 为空时显示「已受理，稍后可查看」，不要显示虚假的精确人数或预计秒数。
+正常待处理结果每次至少间隔 5 秒，遵守更长的服务端 retryAfterMs，再加随机抖动。单次只读恢复耗尽且仍是已知预算繁忙或认证传输层标记的 `PLATFORM_TRANSPORT_UNAVAILABLE`/503 时，外层可在原观察窗口内指数退避继续。SDK 自身明确标记为 status=504、retryable=true 的 CONCURRENCY_READ_RECOVERY_EXHAUSTED 也只在已受理原结果观察中按退避恢复；它不代表服务端忙，不延长原三十分钟截止，也不触发再次提交。权限、依赖、未标记的网络错误、其他 504 或未标记可恢复的错误立即停止自动观察，显示 error 并保留原回执和请求键。终态停止。受理恢复中核对原结果的连接中断由同一有界只读层恢复，内层耗尽不触发 enqueue 重放，读取依赖失败不能被外层重试隐藏。一个业务区域只挂载一个观察者。离开或关闭页面不撤销已受理请求，平台自动继续；新设备通过 mine 找到本人的原请求。position 为空时显示「已受理，稍后可查看」，不要显示虚假的精确人数或预计秒数。
 
-refresh 有本地原键时先薄查询原 key；找到已受理非终态后不再 mine。没有本地意图或原申请已有终态时，mine 优先恢复新的进行中周期，避免本地历史 succeeded 遮蔽另一个设备的新申请。原键明确 404 后保留一次本人列表兜底；未确认的本地意图只能采用同原键回执。列表中只有别的活跃周期时显示 recovering / CONCURRENCY_ORIGINAL_REQUEST_REQUIRED，并保留原 key/input；没有匹配时显示 CONCURRENCY_ACCEPTANCE_UNCONFIRMED，提供「核对原申请」和「恢复原申请」动作。不能把无匹配解释为业务失败，也不丢弃可能迟到受理的原意图。已知读取繁忙耗尽显示 recovering，真实依赖、网络、权限或未知 400 显示 error；两种状态均保留原键、输入和已受理回执，读取失败不自动提交。
+refresh 有本地原键时先薄查询原 key；找到已受理非终态后不再 mine。没有本地意图或原申请已有终态时，mine 优先恢复新的进行中周期，避免本地历史 succeeded 遮蔽另一个设备的新申请。原键明确 404 后保留一次本人列表兜底；未确认的本地意图只能采用同原键回执。列表中只有别的活跃周期时显示 recovering / CONCURRENCY_ORIGINAL_REQUEST_REQUIRED，并保留原 key/input；没有匹配时显示 CONCURRENCY_ACCEPTANCE_UNCONFIRMED，提供「核对原申请」和「恢复原申请」动作。不能把无匹配解释为业务失败，也不丢弃可能迟到受理的原意图。已知读取繁忙耗尽显示 recovering，认证传输层标记的断连先在原预算内恢复；真实依赖、未标记的网络错误、权限或未知 400 显示 error。两种状态均保留原键、输入和已受理回执，读取失败不自动提交。
 
 不要在 mount 发现历史 succeeded 时自动跳成功页或永久禁用提交。它可能已经被管理员取消，需结合当前业务记录展示。只有用户明确再次点击 submit，且原请求已有终态，SDK 才创建新的 requestKey；活跃请求或未知应答始终恢复原 key。平台明确返回未受理的参数错误（400 + CONCURRENCY_INPUT_INVALID 等约定错误）时，SDK 才清除被拒输入，允许修正后再提交；未知 400、409、429、5xx 和网络错误仍保留原意图。成功提示以 receipt.state==='succeeded' 和 receipt.result 为准，accepted/executing 只显示「已登记，处理中」。
 
 permit 的 ManagedCommandGate 仍只用于 admitted 短确认，不用于 durable。durable 不能套任意前端 onSubmit 冒充后台事务，真正业务必须由已声明的 backend-plan handler 返回受管计划。
+
+### 入口等待与身份加载连续性
+
+平台启用入口排队时，SDK 的当前用户读取只对明确的入口繁忙响应接续等待：HTTP 429、`CONCURRENCY_BOOTSTRAP_BUSY`、可重试以及有效的等待状态与 `remainingMs`。第一次有效回执固定等待截止，后续回执只能缩短，最长不超过首次读取开始后的三十分钟。按平台排队提示每 2–15 秒查询，加最多 20% 抖动；不会因普通繁忙或网络错误无限延长。普通身份读取仍使用五分钟恢复预算；权限拒绝、版本变化、入口过期和满额终止恢复。单次读取、投影和网络失败的限制保持独立。
+
+该行为只读取平台身份，不替应用发起或重放报名，也不改变已经受理命令的原始请求键与结果截止。上线容量需在使用该 SDK 的实际应用制品上重新验证。

package/documentation/manifest.json

@@ -1,12 +1,12 @@
 {
   "schemaVersion": "openxiangda.documentation/v1",
-  "version": "2.55.1",
+  "version": "2.59.1",
   "topics": [
     {
       "id": "getting-started",
       "title": "安装与开始开发",
       "file": "getting-started.md",
-      "sha256": "592aa59bab9fcb430ee5caf042c872bf902a8ae5ac8e666b643ebf2e0c103b4a"
+      "sha256": "7d0388a492eb7b4c7caabbd332049d6461155d8c00cd838bde27c1d15ab66152"
     },
     {
       "id": "product-design",
@@ -30,13 +30,13 @@
       "id": "development",
       "title": "需求与开发流程",
       "file": "development.md",
-      "sha256": "3ff8114424828b6652c23b9e00826ebb87754742751589b65c034ec87eb1f54b"
+      "sha256": "4551c3bef9cb5b2828a38f4cbb1426091c1ac53be5e4fc93c1993ab9e103c483"
     },
     {
       "id": "declarations-cheatsheet",
       "title": "声明速查：一次写对 config",
       "file": "declarations-cheatsheet.md",
-      "sha256": "4fa1bc8920af2157bc67ba5819e85fbc271da93155be18650bfbe51c02eac782"
+      "sha256": "69ef6d6c02424f2db6bc050e9dd84b39cd8b61f358dbb7cb8eefaf7eabb5ab9e"
     },
     {
       "id": "application-foundation",
@@ -66,13 +66,13 @@
       "id": "field-components",
       "title": "字段、表单与移动控件",
       "file": "field-components.md",
-      "sha256": "e621fef870bdafa01bd41a294be6169094f1c8b5d6d31c89fa64df105d86a3d5"
+      "sha256": "a820d01b4fb69a1505c220e0cd2d55ded960b7598213695a48acd94bd8699618"
     },
     {
       "id": "data-authz",
       "title": "数据查询与权限",
       "file": "data-authz.md",
-      "sha256": "1f77cbaf778a0a01dfa877610e7d87451716fd60d4364fda43adb4f92c5010f1"
+      "sha256": "1068bd59a362bb990255d94e4db66fcd1f69b6f7895a4314c4e64afaf201006d"
     },
     {
       "id": "public-access",
@@ -84,13 +84,13 @@
       "id": "workflow-events",
       "title": "审批、事件与通知",
       "file": "workflow-events.md",
-      "sha256": "0c02e0253ee52804d22801bab215933c5240974c72e4951bafb0a27e35d0cbd4"
+      "sha256": "9fec3422c6b0532ead4353fc38e65c91bbf2f086c22536862978a45d6dbde19c"
     },
     {
       "id": "backend",
       "title": "按需后端与业务动作",
       "file": "backend.md",
-      "sha256": "5fcea9d1f9197d7f9ed1d65d0e181465092f34feeb0eec46552f20264bf02f85"
+      "sha256": "c43b7f407ba109ded4e5ee1080533cad472754a7a3f5aa090debb1d9b6e050c5"
     },
     {
       "id": "agent-cards",
@@ -114,13 +114,13 @@
       "id": "managed-concurrency-frontend",
       "title": "并发能力的前端接入",
       "file": "managed-concurrency-frontend.md",
-      "sha256": "c4b18991058fec5878f73355e63da063a677ced8413e7fc2b4f03edfb0c2341a"
+      "sha256": "0b7146815b5fa0f6ae93dcce27e4a4c6f1d43d42b230dbe479f997430088ba8c"
     },
     {
       "id": "administration",
       "title": "应用管理与有效配置",
       "file": "administration.md",
-      "sha256": "084b3bcb6ff371701045ec900149d90f8294323259ddd260f7e2c8bfedda2378"
+      "sha256": "31b9fdd249aaa5866482a82e425c62e7d680435b9a837a7558d864d5ea0c5561"
     },
     {
       "id": "testing",

package/documentation/workflow-events.md

@@ -94,6 +94,60 @@ events: {
 时长，十年内，如 `-PT1H` 表示提前一小时）到达时触发。适合到期提醒、超期升级等场景；
 同一条记录的字段更新后按新值重算。`code` 唯一，`eventType` 同样引用已声明应用事件。
 
+日期事件自动带上 `triggerCode`、`resourceCode`、`recordId`、`recordRevision`、`field`
+和 `dueAt`；`payload` 显式写普通对象（无自定义内容时写 `{}`），不能覆盖这些字段或
+`projection`。需要申请人、提醒正文等记录资料时，复用订阅的 `payload.fields`：平台
+取同一事件修订中、事件类型及资源匹配的字段并集，和日期、记录修订一起读取真实
+Native 值，写入事件 `projection`。每个消费者收到的投影再按自身字段声明裁剪。
+
+例如，应用代码为 `reference-app`、资源 `bookings` 包含 `owner`（user.single）、
+`reminderText`（text.long）、`expiresAt`（datetime）时，可以声明：
+
+```ts
+events: {
+  schemas: [{
+    eventType: 'reference-app.booking.expiry.v1', dataSchemaVersion: '1.0.0',
+    jsonSchema: {
+      type: 'object', additionalProperties: false,
+      required: ['triggerCode', 'resourceCode', 'recordId', 'recordRevision', 'field', 'dueAt', 'projection'],
+      properties: {
+        triggerCode: { const: 'booking-expiry' }, resourceCode: { const: 'bookings' },
+        recordId: { type: 'string', format: 'uuid' }, recordRevision: { type: 'integer', minimum: 1 },
+        field: { const: 'expiresAt' }, dueAt: { type: 'string', format: 'date-time' },
+        projection: {
+          type: 'object', additionalProperties: false, required: ['owner', 'reminderText'],
+          properties: {
+            owner: { type: 'object', additionalProperties: false, required: ['value', 'label'],
+              properties: { value: { type: 'string', format: 'uuid' }, label: { type: 'string' } } },
+            reminderText: { type: 'string', minLength: 1, maxLength: 2000 },
+          },
+        },
+      },
+    },
+  }],
+  dateTriggers: [{ code: 'booking-expiry', resourceCode: 'bookings', field: 'expiresAt',
+    offset: '-PT1H', eventType: 'reference-app.booking.expiry.v1', payload: {} }],
+  subscriptions: [{ code: 'booking-expiry-notice', eventTypes: ['reference-app.booking.expiry.v1'],
+    filter: { resourceCodes: ['bookings'] }, payload: { includeChanges: false, fields: ['owner', 'reminderText'] },
+    platformAccess: { notification: { mode: 'business-standard' } },
+  }],
+},
+```
+
+订阅处理器照常实现。通知的 `sendFromEvent` 使用 `recipientPaths: ['projection.owner.value']`
+等路径，由平台从已认证事件取得收件人；应用不在发送请求中复制人员 ID。
+
+投影只接受资源声明的顶层字段，禁止子表、路径/SQL表达式及 `mask: 'omit'` 的敏感字段。
+单订阅最多32字段，同事件投影并集最多64字段，扫描最多100订阅，完整事件不超过
+64 KiB。投影 JSON Schema 必须是关闭额外属性的 object、声明全部已选字段，不能
+要求未投影字段。编译阶段检查固定日期封套和结构，运行时才校验真实资料的类型、
+必填、长度等约束；不生成虚构人员让编译检查通过。资料不满足 schema、来源版本
+漂移或字段不合法时，该调度意图取消并保留错误，不发送不完整提醒。
+
+有资料投影的日期声明要求平台能力 `events.date-source-projection:1.0.0`；连接旧平台
+会在能力协商时拒绝。无字段投影的既有日期事件保持原形态及原能力要求。日期事件
+不自动筛选批准状态；要限定业务状态，应显式设计条件，不能从审批名称推断。
+
 两类触发器各最多 100 条。事件 Schema 用 `events.schemas` 声明
 （`{ eventType, dataSchemaVersion, jsonSchema, sensitiveFields? }`），`eventType` 遵循
 `xxx.yyy.v1` 版本后缀模式；触发器只发事件，不直接写数据或调用流程。
@@ -106,6 +160,13 @@ events: {
 
 标准任务和实例详情的“返回”由应用 Router 使用同一份 route manifest 中对应设备的流程中心路径；没有中心条目时返回已声明门户。普通用户无需管理后台权限。应用独立消费 `WorkflowTaskPage` 或 `WorkflowInstancePage` 时，可以传入本应用已声明的 `returnPath`，例如 `<WorkflowInstancePage variant="mobile" returnPath="/m/work-center" />`。抽屉的 `onDismiss` 仍负责关闭当前抽屉；返回导航不授予目标页面权限。
 
+会签第一票或转交成功后，节点可能继续等待其他人，但原用户的办理席位已经结束。
+标准页面确认旧任务不可读时重新核验实例访问，再显示当前进度；不重投原命令。
+嵌入任务面板的 `onCommandCompleted(result, context)` 保留原平台结果，第二参数
+`taskSurfaceUnavailable` 为 SDK 的成功后读取事实，供宿主关闭旧办理面并读取实例。
+通用网络错误或无关权限拒绝仍显示读取失败；已确认成功的读取失败允许返回，
+未知写入继续要求先查询原结果。`advanced` 仍只表示流程推进，不表示个人席位状态。
+
 抄送由动态 Surface 提供 `cc` 操作，使用 `user_select` 多选组件收集 1 至 20 位人员。任务 Surface 可以正式包含实例抄送命令；前端按 `operation.execute.href` 和该 Surface 的 token 提交，不另造任务命令或 token。公共事件为 `openxiangda.workflow.instance.cc_added.v2`。
 
 ## 钉钉卡片已读查询
@@ -396,8 +457,10 @@ Workflow instance-scoped preview/content 路由，平台在每次文件读取时
 `/m/workflows/:workflowCode/start`。definition 必须显式声明
 `launch: { mode: 'standalone' | 'hidden-handoff' | ... }`，缺失会被编译器拒绝；
 factProjection 把 option/user/department/resource-ref/cascade 字段投影为
-`{ label, value }` 对象，对应 inputSchema 属性必须声明为 `type: 'object'`
-（multiple 类字段为 array + object items），条件表达式用 `path: '<fact>.value'`
+`{ label, value }` 对象，对应 inputSchema 属性声明为 `type: 'object'`；
+允许尚未填写的单值引用显式使用 `type: ['object', 'null']`，数组顺序无关。
+Native必填校验仍执行；multiple类字段保持array + object items（cascade.multiple
+为array + array + object）。条件表达式用 `path: '<fact>.value'`
 比较；声明成标量会在运行时 INPUT_SCHEMA_MISMATCH 并无限重试，编译器现已拦截。`standalone`/`hidden-handoff` 缺省使用同一个
 compiler-owned `processOperationCode`、subject declaration 和标准 process commit；平台在一个
 事务中写业务数据和 durable command。action-owned 资源改为声明
@@ -440,6 +503,19 @@ return <WorkflowSubmissionPage workflowCode="reinstatement" variant="mobile" for
 及已接受命令的展示优先于该提示。应用应始终挂载标准页，避免当前资格变化遮蔽原结果恢复。
 这些规则属于应用代码，不能通过管理员节点配置修改；服务器仍独立校验实际业务资格与字段。
 
+`valueLinkage(changed, values)`在用户输入后同步返回canonical字段patch，例如
+`Object.hasOwn(changed, 'owner') ? { specialist: values.owner ?? null } : {}`。
+改负责人复制专员，手改专员保留；再次改负责人重新复制，清空用null。回调只能改当前
+可见、可编辑且匹配launch的字段，不能改系统/只读/隐藏字段或返回Promise。输入是副本，
+写回沿用codec并标记已触碰，迟到预填不会覆盖联动值。预填、草稿、恢复、程序写回不触发
+联动；PC/手机规则一致。异常保留输入并阻断新提交，下一次成功输入可恢复，原提交结果
+查询及已接受命令仍优先。异步资料读取放准备阶段，服务器仍校验资格和业务不变量。
+
+具名owned新建表单可传`subtableReadonlyFields: { lines: ['employeeNumber'] }`，
+把当前子行的派生值显示为只读，并从提交输入排除。表名与字段必须属于当前sealed
+owned闭包；配置错误会拒绝新表单。值仍可供应用联动展示，Server应重新计算可信值。
+此选项只收窄页面交互，不授予读写权限，也不改变普通CRUD或审批任务的字段规则。
+
 通用应用待办页通过 `frontend.user.applicationTodoCenter: true` 启用，平台同时提供
 `/todos` 和 `/m/todos`。它只投影当前登录用户的 Notification Hub 收件人数据，
 `查看详情` 使用上述统一导航解析；待办页不常驻业务详情，审批命令仍在目标 Workflow
@@ -557,6 +633,50 @@ outbox容量等事务故障会回滚，处理器按原键核对后重交，不
 系统、流水号和隐藏字段不可作为补填入口。根附件、图片复用平台托管文件；
 签名和富文本同样保留 Native 字段协议；普通 owned 子行以固定页面白名单和行 CAS 提交。
 
+### 任务内的资源引用选择
+
+任务页面中的 `resource-ref.single` / `resource-ref.multiple` 自动使用当前任务的选择接口。
+当前办理人不需要业务资料的普通 `update` 权限，但必须拥有目标字典的 `read` 权限；
+字段来源、读取投影、行权限和有界分页继续由 Native Data 执行。
+仅当前固定 taskPage 中可见且可填写的根字段能够查询，隐藏、只读、条件尚未生效的字段
+和子表字段拒绝查询。字段显隐与填写规则仍归页面声明。
+
+自定义任务表单使用公开 `searchResource` 时传入当前 Surface 的 task ID、业务资料修订及
+任务版本；不能把 task 与普通 create、launch 或管理员 record edit 上下文混用：
+
+```ts
+await searchResource(resourceCode, fieldCode, {
+  operation: 'update', keyword: '司机',
+  task: { taskId, expectedRevision: businessDetail.sourceRevision, expectedTaskVersion: task.version },
+});
+```
+
+底层请求使用 `workflow-task-field-source-query/v2`，返回已有的
+`data-field-source-page/v2`。依赖字段的过滤仅使用声明的 bindings：当前可填写的依赖
+可取表单值，显式清空会返回空选项；只读或不在当前页面的依赖取已保存资料。
+游标绑定当前任务、版本、页面、定义和资料修订。409 时刷新任务并保留用户输入，
+403 时展示实际拒绝，不扩大普通 CRUD 权限。标准 PC 和移动任务组件自动传递这些上下文。
+
+### 前后端共享的表达式计算
+
+PC、手机与 Nest 共用的业务模块从纯入口导入，应用仍只声明统一根包精确依赖：
+
+```ts
+import { evaluateWorkflowTaskPageExpression, type WorkflowExpression } from 'openxiangda/expressions';
+
+const when: WorkflowExpression = {
+  op: 'gt',
+  left: { op: 'path', path: 'values.amount' },
+  right: { op: 'literal', value: 1000 },
+};
+const needsReview = Boolean(evaluateWorkflowTaskPageExpression(when, { amount: 1500 }));
+```
+
+路径以 `values.` 开始，第二参数直接传字段值对象。此入口复用原任务页计算器，
+支持浏览器打包器和原生 Node ESM；共享模块不要导入浏览器传输入口
+`openxiangda/core`，也不直接依赖内部物理包。计算结果不授予审批或数据权限，
+真实流转和写入继续由平台固定定义与当前用户授权核验。
+
 ### 标准流程的主子表发起
 
 标准发起页复用 Field Kit 的 PC/手机子表，通过原 `standard-commands` 的
@@ -568,8 +688,35 @@ outbox容量等事务故障会回滚，处理器按原键核对后重交，不
 发起仍执行当前用户的父、子资源及字段授权。拥有主表权限不会自动得到通用子表权限。
 已有记录提交核对父 CAS 和完整已读子行集合，包括未修改行；删除显式保留原 id/revision，
 跨单、遗漏、重复或陈旧行均拒绝。原命令已提交时先返回同一回执，再也不重新展开当前行。
-每表100/累计400、完整意图双倍、整请求2MiB及展开后1000操作与 Native 预算一致。
-普通显式 Named Action 的16个业务操作预算不变；其自定义子表提交仍按自身合同实现。
+每表最多500/累计500、完整意图双倍、整请求2MiB及展开后1016操作与 Native 预算一致。
+超过原单表100或累计400的声明自动要求 `data.extended-owned-subtable-capacity@1.0.0`；
+较小声明及默认20行不自动扩容，新能力由支持的Server自动开启。
+普通显式 Named Action 的16个业务操作预算不变。
+
+具名发起操作需要标准页填写一层子表时，在该操作声明固定的创建闭包：
+
+```ts
+platformAccess: {
+  workflow: { codes: ['expense-approval'] },
+  ownedSubject: {
+    mode: 'create', resourceCode: 'expense-requests',
+    subtables: [{ fieldCode: 'items', fieldCodes: ['description', 'amount', 'evidence'] }],
+  },
+  managedFiles: [{ resourceCode: 'expense-items', fieldCodes: ['evidence'], intents: ['create'] }],
+}
+```
+
+`items` 必须是主体模型声明的一层 owned 关系。子字段清单不含外键、排序字段、嵌套子表或序号。
+含文件、图片、签名或富文本的字段同时声明该操作的 `managedFiles` 创建权限。平台自动核验
+`workflow.named-owned-create@1.0.0` 能力，无需手动开关。
+
+标准 PC/移动页从发起 Surface 读取此闭包，填写新的子行，上传通过原具名操作执行。
+申请人不需要子资源的普通 create/update/delete 权限。应用后端完成业务校验后，
+`BusinessProcess.commit` 只传一个主体 create，其 `data` 包含上述行结构，subject 指向此操作。
+平台在同一 Native 事务内展开子行、维护外键与顺序并接受流程命令；原回执恢复先于子行规划。
+这一契约只支持新建，拒绝 existing/update、混合显式操作以及 decimal reservation；
+原有不声明 `ownedSubject` 的具名操作继续使用显式事务。最多16张子表、合计500行，
+仍执行原事务字节、字段、文件与授权检查。
 
 ### 任务 owned 子表
 
@@ -585,11 +732,11 @@ outbox容量等事务故障会回滚，处理器按原键核对后重交，不
 
 关系沿用模型的 `resourceCode/foreignKey/orderField/maxRows`，不接受任务调用者自报。
 子字段可声明同样的只读、可见和条件必填规则；这些属于页面代码，管理员不能覆盖。
-`create/delete/reorder` 省略时关闭。仅一层，每表 maxRows 最多100，父资源及任务页
-声明总量最多400；默认仍20。完整意图最多为每表 maxRows 的两倍，可在一次提交中
+`create/delete/reorder` 省略时关闭。仅一层，每表 maxRows 最多500，父资源及任务页
+声明总量最多500；默认仍20。完整意图最多为每表 maxRows 的两倍，可在一次提交中
 删除满表旧行并新增同等数量，仍按有效行数校验上限。整个 form/任务私有草稿值限1MiB，
 页面定义仍64KiB/64根字段；系统、隐藏、关系键和顺序字段不进入子字段白名单。
-标准主子表提交复用同一个 Native 原子事务，最多1000操作/2MiB（400行全量替换加主表为801操作），
+标准主子表提交复用同一个 Native 原子事务，最多1016操作/2MiB（500行全量替换加主表为1001操作），
 任一行失败全单回滚，不静默截断或分批提交。普通表单草稿values最多2MiB，含原值与当前值；
 状态字段的独立配额不变。附件上传数量/字节与详情读取预算仍独立执行，行数容量不豁免文件配额。
 子行支持 file/image/signature/text.rich，使用同一个任务上传入口并绑定准确行；普通
@@ -645,8 +792,12 @@ approve/resubmit 携带 `form: { expectedRevision, values }` 时，Native 业务
 拒绝后的读取失败明确提示本次未提交，锁住旧操作，恢复读取后再核对；未知结果仍只能恢复原请求。
 操作确认表单使用同一 Surface 的必填、字符数与非空白规则校验意见和原因。
 拒绝意见默认必填。固定节点显式设置 `operationPolicy.reject.commentRequired: false` 时允许省略或空意见，目标须具备 `workflow.optional-rejection-comment@1.0.0`；已进入任务使用冻结规则，后续配置不追溯。选填仍限制为最多4000字符的字符串，不写入假意见。
-`commentRequired` 只配置同意/拒绝的 `comment`；转交、委托、加签、退回与管理员改派
-继续使用原合同的必填 `reason`，不用再填写第二份意见。
+`commentRequired` 只配置同意/拒绝的 `comment`。转交、委托、加签、退回使用 `reason`，
+默认必填；固定节点可显式声明如 `operationPolicy.transfer: { reasonRequired: false }`，
+目标须具备 `workflow.optional-operation-reason@1.0.0`，平台自动提供，无需初始化开关。
+选填允许省略、空字符串或空白，仍拒绝非字符串和超过4000字符的值，不生成代替原因。
+开放对应 `administration.operations` 后，管理员可以收紧选填规则，不能放宽代码必填规则；
+已进入的任务保留冻结规则。管理员改派始终必填，不用再填写第二份审批意见。
 明确拒绝后，实例、任务版本及操作签名仍一致且操作仍可用时，对话框保留输入供人工核对；
 任务、权限、字段规则或版本变化时不能沿用旧操作。刷新和保留输入都不会自动重发请求。
 补填刷新固定事实投影；
@@ -770,6 +921,42 @@ append 处理签名或 HTML。当前任务、实例、记录或字段改变时
 
 退回补正（return_review）必须有人实际处理，不能靠空人跳过；重提后的正常 replay/resume 流转继续采用原节点策略。使用此声明时，生成契约要求目标平台支持 `workflow.approval-empty-policy@1.0.0`，缺少该能力的旧服务端不能接收。
 
+## 审批通过后整批授权代理 {#approved-delegation}
+
+`subject.factProjection`可以引用主体已声明的owned子表。平台在Native创建事务中按真实
+父记录读取明细，输出带持久行`key`的扁平业务对象；外键、排序和系统字段不进入事实。
+日期、数字和人员引用采用Native规范值，按声明排序字段及id稳定排序。所有本次创建行
+必须经原RLS可见；权限不足、修订或集合变化、单表超限均回滚，不接受客户端自报数组。
+空的可选子表保留`[]`，单表最大500行，完整流程事实仍限256KiB；初期不支持嵌套子表。
+声明自动要求`workflow.owned-initial-facts@1.0.0`，平台初始化自动提供，无额外开关。
+这是初始冻结能力；任务修改owned明细后的事实更新应另行确认，不能用初始快照代替。
+
+代理申请使用固定定义的 `approvedDelegation`：
+
+```ts
+approvedDelegation: {
+  confirmationNodeId: 'confirm',
+  confirmer: 'delegate', // 或 initiator：由发起人本人确认
+  requestsField: 'requests',
+  maxRequests: 500,
+},
+```
+
+`requests` 必须是 Native 主体投影到实例的闭合、有界明细数组；只读取固定实例
+`fact_snapshot.data`，每行采用 `WorkflowApprovedDelegationRequest`，保存本人和代理人的
+职责键及修订、代理人引用、流程/可选节点范围、起止时间与原因。最多500行、整批256KiB。
+代理人确认的整批必须为同一代理人；同一流程不同节点的明细分别保留。
+
+所有批准路径必须经过声明的单人、人工、非空确认节点。自动处理、超时、管理员跳过、
+转交和代理确认不能产生确认证据；明细变化或再次退回后必须在当前周期重新确认。
+最终批准在同一事务核验真实人工任务和双方当前账号、职责、窗口、修订与冲突，
+然后调用已有平台代理所有者整批授权。任一行失败时，批准、全部授权和批次回执一起回滚。
+创建、审核中、拒绝、退回和撤回不授权；原命令恢复不重新创建或激活已撤销的授权。
+
+声明自动要求 `workflow.approved-delegation@1.0.0`，无需增加默认关闭的开关。
+不提供 HTTP/system 代建入口，不授予代理人额外资料权限。图通过 `readability.logic`
+说明确认、当前职责核验及授权处理；这些逻辑和连线由代码固定。
+
 ## 按业务资料权限查看办理历史 {#record-history-read}
 
 发起人、审批人、抄送人使用既有 Workflow 详情。业务查看人员需要根据当前资料范围读取办理记录时，模型可显式声明：
@@ -827,3 +1014,85 @@ 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，未声明的流程保持原提交行为。实际角色与事务回滚需在目标平台验收。
+
+## 审批自动完成期限
+
+可选评价等允许不填写内容的审批节点，可以声明固定期限：
+
+```ts
+completionDeadline: { afterSeconds: 600, action: 'approve' }
+```
+
+此声明需要 `workflow.completion-deadline@1.0.0`。平台在正常任务进入事务中保存
+期限，以数据库创建时间计时，默认每30秒扫描，到期可能有扫描及排队延迟。
+期限支持1秒至30天，由应用代码拥有，管理员不能改变期限、条件或连接。
+没有声明的节点继续人工办理；退回补正和恢复源任务仍须人工处理。
+
+到期是整个节点自动完成，剩余审批席位取消，保留已提交内容与真实人工意见，
+历史标记“超时自动同意”，不会给申请人或未处理人员伪造审批票。
+只允许可选任务输入；必填字段、条件必填、子表必填、`edit_required`、同意意见
+必填和自定义 approve handler 与期限冲突，编译及平台注册都会拒绝。
+节点配置不能把此类节点改成必须填写同意意见。
+
+人工处理与后台执行共用实例锁，先完成者生效。任务离开、退回、撤回、终止或
+删除时，在同一事务取消期限。下游失败回滚整次流转，保存脱敏错误码并有界退避；
+最多12次失败后停止自动重试，保留人工办理。PC/手机任务详情显示截止时间或
+失败提示，管理流程图显示固定规则，实例轨迹显示实际自动完成证据。
+本批没有管理员重试或改期限入口。
+
+平台重启后继续处理原持久期限，无需额外启用开关。已有期限的版本回滚时，
+必须保留兼容的平台后台，或先完成/明确取消在途任务；不能删除期限与历史。
+
+
+## 退回发起人补正 {#initiator-correction}
+
+数据更正使用独立的固定节点，不作为本人审批票：
+
+```ts
+startAt: 'calculate',
+taskPages: { correction: { title: '补正申请', fields: [{ code: 'amount', required: true }] } },
+nodes: {
+  // calculate 和 review 沿应用已声明的代码步骤及审批节点。
+  correct: { id: 'correct', kind: 'correction', title: '发起人补正',
+    taskPageCode: 'correction', next: 'calculate' },
+  // review.returnTargets 声明 ['correct']；其他正向边不能进入 correct。
+},
+```
+
+`next` 必须等于固定 `startAt`。该节点只能由声明的审批退回进入，包括第一个审批节点；
+退回到其他审批节点仍需真实人工办理历史。补正沿当前任务页、Native授权和资料修订，
+仅原发起人直接办理，只有保存补填和重新提交，不代理、转交、加签或管理员代填。
+原职责失效或修订改变时拒绝，不换身份继续。
+
+保存不推进。重新提交在同一事务更新标量资料与事实、关闭补正任务及退回会话，
+从固定起点重新执行条件与代码步骤。补正重提记录 `resubmitted`，不产生同意票或
+代理申请的人工批准确认。只支持 `replay`，请求 `resume_current` 明确拒绝。
+初期补正页不支持 owned 子表；创建时的 owned 事实快照不能代替补正后的事实刷新。
+
+图显示旁侧补正节点、直角虚线退回/重提路径，正向分支的层级保持；拓扑和代码仍固定。
+声明自动要求 `workflow.initiator-correction@1.0.0`，无需增加默认关闭的开关。
+结果未知使用当前任务原命令回执恢复，不重建申请；数据、任务或事件失败一起回滚。
+
+### 补正重提的业务校验 {#correction-business-command}
+
+补正涉及年限资格、培训日期、报销上限或当前主数据时，字段 Schema 之外还要重新执行
+业务规则。在固定定义声明 `commandHandlers.resubmit: { operationCode: 'requests.resubmit' }`，
+把该操作的 `platformAccess.workflow` 声明为
+`{ codes: ['request-approval'], businessCommands: ['resubmit'] }`。
+操作必须是受控、强制幂等的 POST，绑定同一父资源的 `recordId`；请求 Schema 使用
+`openxiangda/config` 导出的 `workflowBusinessCommandInvocationSchema`。
+响应使用完整、闭合的实际结果 Schema，不能以开放的顶层对象绕过受控操作检查。
+
+标准 PC/手机任务页根据当前 Surface 调用该具名操作；应用不复制审批流转或预测下游
+动态人员。处理器先调用 `businessProcess.resolveOriginalTaskCommand(invocation)` 查询原结果，
+再合并受限任务字段、重验当前业务规则和资料，最后调用 `commandWithData`，
+使用 `expectedTransition: { kind: 'correction-replay' }`。平台验证真实本人补正、原任务与
+资料修订，在同一事务保存字段、刷新事实、核验 Native guards、关闭退回会话并重新计算。
+业务 mutation 仅写非事实的可信快照或审计字段，不能直接改变 `factProjection` 字段。
+
+`save_form` 仍可保存未填完的资料；只有通过业务重校验才能重提。直接调用原 Workflow
+重提入口会被拒绝，管理员不能替原发起人绕过该处理器。仅声明 resubmit 的流程可保留
+普通审批的退回和自动策略；包含 approve/reject/withdraw 业务 handler 的既有限制不变。
+自动协商 `workflow.correction-business-command@1.0.0`，无需额外开启功能。
+本人标量补正支持 Native 写入，owned 子表补正仍不支持；原已成功结果先于当前资料重验
+恢复，不因日期推移或资料后来停用而被误报为失败。接入方法见[后端](backend.md#correction-business-command)。