openxiangda-skill-kit 2.3.57 → 2.3.89

package/skills/openxiangda-v2/references/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/skills/openxiangda-v2/references/getting-started.md

@@ -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)。
 
 ## 应用源码
@@ -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/skills/openxiangda-v2/references/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，再加随机抖动。单次只读恢复耗尽且仍是已知预算繁忙时，外层可在原观察窗口内指数退避继续；权限、依赖、网络故障或悬挂请求超过读取预算时立即停止自动观察，显示 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/skills/openxiangda-v2/references/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}