openxiangda 2.0.0-alpha.99 → 2.0.0

package/skills/openxiangda-v2/references/workflow-events.md

@@ -1,151 +1,81 @@
-# Workflow, Events and Notification Hub
-
-Read [Architecture](architecture.md), [Data and authorization](data-authz.md)
-and [Testing](testing.md) before enabling this optional layer.
-
-Use these optional modules only when the application has a real standard approval or cross-channel notification requirement. Ordinary CRUD and application-specific state machines stay on Data API/App API and must not pull Workflow or Notification code into the default template.
-
-## Boundaries
-
-- The application owns business records and domain invariants.
-- Workflow Kernel v2 owns definitions, instances, tasks, participants, commands, transitions and audit facts.
-- Application Events v2 owns durable facts and delivery.
-- Notification Hub v2 owns templates, rules, logical messages, channel delivery, callbacks and message operations.
-- Named Action business notifications use `OpenXiangdaBusinessNotificationService` and the platform-owned `application.informational.standard` template. App Gateway authorizes the current user once; Notification Hub revalidates the action proof, sends as the application principal, and retains initiating user/action audit. Ordinary users never need `app:notification2:send`.
-- Native Identity/AuthZ v2 owns the current user and the union of that user's current application roles. Perspective is read-only and never changes workflow participation or action authorization.
-- Never import, query, migrate or call 1.x workflow/message code, tables, APIs, queues, templates or callbacks.
-
-## Workflow declaration
-
-Declare workflow topology and bindings once in `openxiangda.config.ts`. Use only approval, condition and end nodes for the standard module. Every definition `inputSchema` is a closed root object (`type: 'object'`, `additionalProperties: false`). Keep business data in Data API/App API and pass the exact `{ resourceCode, id }` `dataRef`, a separate positive `dataRevision`, and bounded schema-valid facts into prepare/start. Undeclared facts and answers fail closed.
-
-`workflows.activations` is the complete desired set for the deployed version,
-not a patch list. Removing a declaration deactivates that workflow for new
-starts. Every assignee provider binding uses candidate `min`/`max` defaults of
-1/200 and may not exceed 200. Application Provider callbacks accept only the
-signed `openxiangda.workflow-assignee-request/v2.1` envelope, including the
-business/data/version tuple and `factDigest`.
-
-Every definition declares a launch mode: `standalone` for a self-contained
-generated durable-process page, `custom-page` for an application operation page,
-`hidden-handoff` for a non-menu handoff route, or `work-center-only` when users
-only act on existing tasks. `standalone` exposes the standard user launch
-route, while `hidden-handoff` keeps the same route out of portal navigation;
-the generated browser runtime uses the workflow's localized definition title,
-so applications do not maintain code-to-title maps. `standalone` and
-`hidden-handoff` default to a compiler-owned
-`processOperationCode` and standard process commit. When the subject mutation is
-owned by an App Operation, declare `launch.submission.kind: 'named-operation'`
-instead. The compiler seals its POST path, capability, schemas, input sources,
-result paths and optional context prefill; the standard page invokes that exact
-operation and persists only a returned `commandId`. Missing/null
-`processCommand` is an explicit successful no-approval result. The browser never
-owns a save callback, facts/dataRef, preparation token, or direct start. Custom
-pages launch only inside a verified Named Action through
-`OpenXiangdaBusinessProcessService`.
+# Workflow 与 Notification Hub 2.0 边界
 
-```ts
-launch: {
-  mode: 'hidden-handoff',
-  submission: {
-    kind: 'named-operation',
-    create: {
-      operationCode: 'reservation.submit',
-      inputs: {
-        idempotencyKey: { source: 'idempotency-key' },
-        applicant: { source: 'current-user-reference' },
-        venue: { source: 'field', fieldCode: 'venue' },
-        startAt: { source: 'field', fieldCode: 'startAt' },
-        purpose: { source: 'field', fieldCode: 'purpose' },
-      },
-      output: {
-        subjectId: 'id',
-        subjectRevision: 'revision',
-        processCommand: 'processCommand',
-      },
-    },
-    context: [{ queryParameter: 'venueId', fieldCode: 'venue' }],
-  },
-}
-```
+标准 Workflow 与 Notification Hub 已作为 OpenXiangda 2.0 可选平台模块重新开放。它们不属于默认 CRUD 模板，也不兼容或复用 1.x 工作流、消息中心、模板、卡片、回调、表和 API。
 
-Every required operation request property must have one input binding. Use
-`field`, `idempotency-key`, `current-user-reference`, `requested-at`, and—for an
-`existing` intent—both `subject-id` and `subject-revision`. Context parameters
-only prefill declared fields; the Named Action still derives identity, validates
-authorization/business invariants and owns idempotency. Its
-`platformAccess.workflow.codes` must include this workflow.
+## 标准详情与当前用户入口
 
-Use an assignee Provider only when resolution depends on application data. The Provider returns stable Native user/role subjects and never makes the final task authorization decision.
+普通记录、流程记录、任务和实例复用同一详情框架。流程详情提供申请内容、审批历史和变更记录三个标签页；管理员在当前抽屉或页面中切换到普通表单编辑，直接保存并自动留下变更记录，审批结果保持不变。PC 子表在表格内编辑，父表提交时统一校验。
 
-The standard operations are approve, reject, return, resubmit, transfer, delegate, add-sign, withdraw, admin reassign, admin terminate and reminder. Render only operations returned by the task/instance Surface. A template or application action cannot add a Workflow command that is absent from the Surface.
+待办中心通过 Workflow 查询 `pending`、`handled`、`created`、`cc` 四种视图；消息中心默认向 Notification Hub 查询 `view=all`，沿用应用声明的渲染扩展。各入口按服务端 `detailNavigation` 打开详情，页面不自行拼接人员范围。
 
-## Submission and concurrency
+抄送由动态 Surface 提供 `cc` 操作，使用 `user_select` 多选组件收集 1 至 20 位人员。任务 Surface 可以正式包含实例抄送命令；前端按 `operation.execute.href` 和该 Surface 的 token 提交，不另造任务命令或 token。公共事件为 `openxiangda.workflow.instance.cc_added.v2`。
 
-1. Commit the bounded Native mutation and Workflow intent as one durable command.
-2. Persist `commandId` in the route and reload `ProcessCommandSurface` after refresh.
-3. Answer only requirements emitted for that command revision.
-4. Let the platform worker start the pinned Workflow exactly once.
-5. Use the Surface revision/concurrency token for every command.
+## 能力 owner
 
-Duplicate commands return the stored command receipt. Stale revisions fail with a structured conflict. A task/participant state transition, operation log, Workflow fact and event outbox commit atomically.
+- Workflow Kernel v2 唯一拥有定义、实例、任务、参与人、命令、流转、委托、加签和流程审计。
+- Application Events v2 唯一拥有已提交事实的 journal/outbox、顺序、投递和回执。
+- Notification Hub v2 唯一拥有逻辑消息、模板、规则、渠道路由、渲染、发送、更新、关闭、外部绑定、动作收据和消息运维。
+- Data API/App API 唯一拥有业务记录；Workflow 只保存 `dataRef` 和 revision-bound facts，消息只保存允许展示的安全投影。
+- Native Identity/AuthZ v2 唯一拥有当前用户、当前应用角色并集和数据范围；Perspective 只影响读取展示，不改变 Workflow 的发起、任务与操作授权。
 
-## Notification profile
+Workflow 发起只接受 `{ resourceCode, id }` 形式的 `dataRef`，并要求独立的
+正整数 `dataRevision`。definition 的 `inputSchema` 根对象必须显式
+`additionalProperties: false`，未声明的 facts/answers 直接拒绝。Provider
+回调只接受带完整业务/数据/definition/binding/fact digest 的
+`openxiangda.workflow-assignee-request/v2.1`。
 
-A node may reference a notification profile that selects:
+## 标准工作流范围
 
-- source facts that create, update or close a message;
-- audiences such as current participant, initiator, historical participant or CC;
-- a versioned template reference;
-- an allowlisted variable projection;
-- channel priority/fallback;
-- default detail target;
-- whether to show Workflow Surface actions;
-- whether a separate result message is required.
+首期只支持 `approval`、`condition`、`end`，以及 `single`、`any`、`all`、`sequence` 审批模式。标准操作为提交、同意、拒绝、退回、重新提交、转交、委托、前/后加签、撤回、管理员改派、管理员终止和不改变流程状态的催办。
 
-Template variables must be declared by JSON Schema and stay within the field policy visible to the recipient. The Notification Hub does not query arbitrary application tables to complete a template.
+复杂业务状态机继续放在应用领域服务。不要把任意 JavaScript、Service Task、BPMN、通用长事务或业务记录复制进 Workflow。
 
-For a non-Workflow informational message, the public business contract accepts
-only `title`, optional `summary`, recipients and a canonical navigation target.
-Supply stable `eventId`, `idempotencyKey`, `messageKey` and monotonic
-`sourceSequence`: duplicate events and idempotency keys replay the stored
-message, while a later source sequence converges the same logical message.
-Never forward a user token, application credential or global Notification Hub
-permission from application code.
+所有页面和消息动作必须来自后端 Workflow Surface 的 `operations[]`。前端、模板和渠道 Adapter 不自行推断操作权限。
+Surface 同时签发短期、一次性的 `commandToken`，绑定当前用户/会话、应用环境
+Head、实例/任务版本、允许的命令集合与 CSRF。命令请求只提交
+`commandToken + idempotencyKey + input`；旧的 caller-authored
+`expectedTaskVersion`/`expectedInstanceVersion` 不再是合同。冲突必须刷新 Surface，
+不得自动重放旧意图。
 
-A signed event/date-trigger consumer uses
-`OpenXiangdaBusinessNotificationService.sendFromEvent()`. The application
-declares safe paths under event `data` for recipients, title and summary;
-Notification Hub verifies the active durable delivery and resolves those paths
-itself. The audit actor remains the application event consumer with eventId,
-deliveryId and subscription code as initiating source. Missing or forged event
-proof, arbitrary recipient values and user impersonation are rejected.
+## 事实和消息投影
 
-The owning subscription must also declare the dependency explicitly so the
-immutable package capability closure cannot omit Notification Hub:
+Workflow 在同一 PostgreSQL 事务中提交状态、fact 和 outbox。每个实例使用严格单调的 `instanceSequence`，每位审批人拥有独立 participant 生命周期。
 
-```ts
-{
-  code: 'proposal-reminder-notification',
-  eventTypes: ['proposal.reminder.requested.v1'],
-  platformAccess: {
-    notification: { mode: 'business-standard' },
-  },
-}
-```
+Native Data 事件的 capture plan 由当前 Head 的 Event、Data、AuthZ revision
+与 resource 四元组共同确定。新增快照字段或扩展 RLS 会形成新的不可变 plan，
+不会与旧 plan 冲突；历史 replay/re-emission 复制原 fact 的数据与 plan digest，
+不会用当前 Head 重新投影历史事实。
 
-Do not add this declaration to subscriptions that do not call
-`sendFromEvent()`. Unknown access kinds and notification modes fail closed.
+每条 Workflow fact v2 都必须携带不可变实例身份信封：`workflowCode`、
+`definitionVersion`、`bindingVersion`、`instanceId`、`generation`、
+`businessKey`、`instanceSequence`、`revision`、`dataRef`、`dataRevision`、
+`actor` 与 `cause`。消费者不得从当前 Workflow Head 反推历史事实版本。
 
-## Detail navigation
+配置中的 `workflows.activations` 是完整 desired set；删除声明即停用新发起，
+不是增量 patch。definition 和 activation 必须一致声明
+`acceptedCommandDeactivationPolicy`：`finish-pinned` 让已接受的 durable process
+command 按固定版本完成，`cancel-on-deactivate` 在声明删除后取消尚未启动的命令；
+既有 Workflow instance 始终按固定版本继续。所有审批人 Provider 的 `min/max`
+默认 1/200，最大 200。
+需要按流程实例串行投递时只声明 `ordering: 'workflow-instance'`，不接受下划线别名。
 
-Use a canonical navigation target with `PLATFORM_ROUTE`, `APP_ROUTE` or allowlisted `EXTERNAL_URL`, stable route code, path/query parameters and an authenticated access requirement. Do not place environment domains, bearer tokens, cookies, identity-switching credentials or secrets in template strings.
+Notification Hub 消费事实：
 
-The Notification Hub resolves desktop, mobile and channel deep links. The landing page always re-runs platform authentication and Data/AuthZ/Workflow authorization.
+- `participant.activated` 创建待处理消息；
+- participant 完成、转交、委托、加签、暂停或恢复时更新对应收件人的逻辑消息；
+- instance 完成、拒绝、撤回或终止时更新该实例全部历史消息；
+- 消息回调必须调用 Workflow 命令，等待 Workflow 新事实后再更新卡片。
 
-Business-record navigation and custom Workflow detail are separate contracts.
-To let the standard Workflow page offer “view business detail”, declare an
-explicit route pair on the subject resource:
+发送采用至少一次语义，以 `messageKey + recipient + channel` 幂等。RabbitMQ 只负责唤醒，PostgreSQL fact、message projection、outbox 和 receipt 才是恢复事实。
+
+## 详情跳转
+
+消息使用 canonical `navigationTarget`，而不是模板拼接环境 URL。它可以描述平台路由、应用路由或白名单外部地址，由平台按 tenant、environment 和 channel 解析 desktop/mobile/deep link。
+
+详情地址不能携带登录 Token、Cookie 或任何身份替换凭据。点击后必须重新认证，并由 Data/AuthZ/Workflow 执行真实权限校验；当前 Perspective 只能重新应用读取投影。
+
+“跳回业务记录”和“完全接管流程详情”是两个不同合同。标准 Workflow 页需要提供
+“查看业务详情”时，在 subject resource 上声明明确的 route code 对：
 
 ```ts
 const purchaseResource = {
@@ -159,165 +89,93 @@ const purchaseResource = {
 } satisfies AppDataResourceDeclaration;
 ```
 
-Both routes are authenticated `surface: 'user'` routes, require
-`app:<app-code>:data:<resource-code>:read`, and contain exactly one dynamic
-record parameter. Desktop stays outside `/m`; mobile starts with `/m/`. The
-parameter may be named for the domain (`:purchaseId`, `:applicationId`, and so
-on). The compiler seals the mapping and the platform renders it from the same
-active Contract revision used for Workflow navigation. With no mapping the
-Surface returns no business-record target. It never guesses a path from the
-resource code, and a malformed active mapping fails closed.
+两条 route 都必须是已认证的 `surface: 'user'` 页面并要求该资源的 read capability；
+桌面 path 不得进入 `/m`，移动 path 必须以 `/m/` 开头，且各自只能包含一个动态记录参数。
+参数名可以是业务语义名，例如 `:purchaseId` 或 `:applicationId`。编译器把映射写入
+不可变资源 Contract 和生成的 `resourceDefinitions`，平台从同一环境 active Contract
+读取并代入 Workflow Surface 已授权的 recordId。未声明时返回空业务记录目标；已发布
+映射畸形时严格失败。平台和浏览器都不得再按 `resourceCode` 猜路径，也不得用别名补洞。
 
-To replace the standard Workflow detail page everywhere, declare both route
-codes on the Workflow definition declaration. The desktop route must be an
-`admin` route, the mobile route must be a `user` route, and both paths contain
-exactly `:instanceId`:
+流程需要完全接管详情页时，在 definition declaration 上声明桌面端与移动端 route code：
 
 ```ts
-frontend: {
-  root: 'apps/web',
-  routes: [
-    {
-      code: 'purchase-detail',
-      path: '/admin/operations/purchases/:instanceId',
-      label: '采购审批详情',
-      surface: 'admin',
-    },
-    {
-      code: 'purchase-detail-mobile',
-      path: '/m/purchases/:instanceId',
-      label: '移动采购审批详情',
-      surface: 'user',
-    },
-  ],
-},
-workflows: {
-  definitions: [{
-    version: 1,
-    definition: purchaseApproval,
-    launch: { mode: 'work-center-only' },
-    detailRouteCode: {
-      desktop: 'purchase-detail',
-      mobile: 'purchase-detail-mobile',
-    },
-  }],
-  bindings: [],
-  activations: [],
-},
+{
+  version: 1,
+  definition: purchaseApproval,
+  launch: { mode: 'work-center-only' },
+  detailRouteCode: {
+    desktop: 'purchase-detail',
+    mobile: 'purchase-detail-mobile',
+  },
+}
 ```
 
-Bind the generated routes with `defineApplicationContributions`. Inside the
-page, read `instanceId` from React Router and optional `taskId` from the query.
-Use `loadWorkflowInstanceSurface`, `loadWorkflowTaskSurface` and
-`loadWorkflowTimeline` from `openxiangda/core`; render only operations returned
-by the Surface. The platform resolves the same declaration for desktop/mobile
-work centers, Notification Hub logical messages, DingTalk cards and other
-channel snapshots. Omitting `detailRouteCode` keeps the standard pages. A
-declared but missing or incompatible route fails closed rather than falling
-back silently.
-
-When `detailRouteCode` is omitted, use the platform standard detail page. Its
-Surface carries `presentation.businessDetail`, pinned to the instance Data
-logical revision, declaration digest and physical resource while re-reading the
-current values of the same Native Data record on every request. The start-time
-`requestedRevision` remains CAS metadata; `sourceRevision` and visible values
-must advance after a business-record update and must never become start-time
-value snapshots. The projection applies the current user's field policy and
-removes every `system: true` or internal field plus any empty group. Parent and subtable
-resources stay on that same logical revision and each subtable is bounded to
-200 rows. Render the provided summary, full field Surface, typed timeline and
-server-owned operation descriptors; do not infer labels, operation hierarchy
-or field semantics from codes in application code. Desktop and mobile have
-independent renderers, low-frequency operations live under one more-actions
-entry, and comments are collected only after an operation is selected. A
-`stale` detail status is metadata, not a persistent banner or an action block;
-show the friendly refresh prompt only when a command returns a real
-`freshSurface` token/CAS conflict and never auto-replay it. Merge operation
-actor/action/reason/time into the corresponding vertical node instead of
-rendering a second audit block. Never render UUIDs, revision/event diagnostics
-or a technical information section. Resolve the applicant from a directory or
-stable snapshot and use a friendly placeholder instead of exposing userId.
-
-The standard desktop task and instance pages use `/tasks/:taskId` and
-`/workflows/:instanceId` as standalone full-screen routes outside the admin
-Shell. Historical `/admin/tasks/:taskId` and `/admin/workflows/:instanceId`
-routes have no alias or redirect. Mobile remains the
-independent `/m/tasks/:taskId` and `/m/workflows/:instanceId` surface.
-
-Ordinary records and Workflow task, instance and record entrances share the
-standard detail frame: gray background, grouped white cards, title/status/creator
-metadata and fixed actions. Workflow adds application content, approval history
-and change-history tabs. An authorized administrator edits the full ordinary
-form inside that same drawer or page and saves directly; do not introduce an
-edit-application dialog, correction reason or extra confirmation. Native change
-history records the edit while Workflow approval facts remain unchanged.
-Desktop child rows edit inline and parent submission validates every row.
-
-The standard work center reads the server's `pending`, `handled`, `created` and
-`cc` views and counts. The separate message center reads Notification Hub with
-`view=all` by default and preserves application renderer extensions. Follow each
-item's `detailNavigation`; do not rebuild user eligibility from client data.
-Dynamic `cc` operations use `user_select` with `mode: 'multiple'` and a bounded
-`userIds` array. Execute the exact Surface href with its issued command token:
-a task Surface may officially include an instance CC command. The public fact
-is `openxiangda.workflow.instance.cc_added.v2`.
-
-
-Files, rich-text images and signatures on this page use only the Workflow
-instance-scoped preview/content client. Every request is rebound to the current
-principal, authorized instance, projected resource/record/field and managed
-file id. Never substitute the ordinary Data API file route or put credentials
-in a file URL.
-
-Standard launch entry is also a platform user Surface. Desktop uses
-`/workflows/:workflowCode/start` and mobile uses
-`/m/workflows/:workflowCode/start`; both first load
-`loadWorkflowLaunchSurface(workflowCode)`, verify its compiler-owned subject and
-submission contract, then use the standard durable process commit or the exact
-sealed Named Action.
-`custom-page` and `work-center-only` declarations do not expose the standard
-launch Surface. After start, navigate through the device's standard instance
-entry so the current `detailRouteCode` contract can redirect consistently.
-
-An application-level inbox is enabled with
-`frontend.user.applicationTodoCenter: true`. It projects Notification Hub messages and
-per-recipient interaction for the current logged-in user only; it is not the
-Notification Hub management console. Use its `去处理` navigation to enter the
-authorized Workflow or application page, and keep approve/reject/transfer
-commands on the destination Surface.
-
-## Interactive channel actions
-
-Channel callbacks enter the Notification Action Gateway. The gateway verifies tenant, environment, recipient identity, task/participant, Surface revision, operation, nonce, signature and expiry before calling Workflow.
-
-The callback never writes Workflow or business state directly. It returns the Workflow command receipt, waits for the resulting fact and lets Notification Hub update the existing logical message. Duplicate or expired clicks return the current receipt/snapshot and refresh the card.
-
-Use direct card actions first for approve/reject. Return, transfer, delegate and add-sign normally deep-link to the standard task page because they require structured input.
-
-## Event handling
-
-Consume typed participant/task/instance facts with durable idempotency. Declare
-event delivery `ordering: 'workflow-instance'` when the handler requires the
-platform to serialize by instance; `workflow_instance` is not an alias. Still
-verify `instanceSequence` in the consumer and never assume global event order.
-Terminal instance facts dominate stale participant facts and update every
-historical message for that instance.
-
-For Native Data facts, the platform owns the capture plan under the exact Event
-revision, Data revision, AuthZ revision and resource tuple selected by the
-Native Head. Adding a snapshot field or extending RLS may create a new plan;
-applications do not version it and must not remove the field to satisfy an old
-plan. Historical replay uses the data and plan digest frozen in the original
-fact, so it never gains fields from the current Head.
-
-Every Workflow fact v2 carries the immutable instance identity envelope:
-`workflowCode`, `definitionVersion`, `bindingVersion`, `instanceId`,
-`generation`, `businessKey`, `instanceSequence`, `revision`, `dataRef`, and
-`dataRevision`, plus `actor` and `cause`. Treat missing identity as an invalid
-fact; never infer historical versions from the current Workflow Head.
-
-Use Fake Channel before a real Adapter. Verify create, update, close, reconcile, duplicate, out-of-order, restart, retryable failure, terminal failure and unknown delivery before DingTalk or campus canaries.
-
-## Verification
-
-Run the workspace generate/check/test/build gates plus real current-user positive and negative role-union cases. Acceptance must include full business-detail projection, bounded parent/subtable reads, Workflow-scoped files, independent desktop/mobile renderers, submit, approve, reject, return/resubmit, transfer, delegate, before/after add-sign, withdraw, terminate, duplicate commands, stale revisions, repeated callbacks, full terminal card updates, detail navigation and 1.x zero-touch evidence.
+`desktop` 必须引用 `surface: 'admin'` 的 route，`mobile` 必须引用
+`surface: 'user'` 的 route；两个 path 都必须且只能包含
+`:instanceId`。任务入口由平台追加有界 `taskId` query。应用使用
+`defineApplicationContributions(appRoutes, { pages })` 绑定桌面和移动组件，
+页面通过 `openxiangda/core` 的 `loadWorkflowInstanceDetail`、
+`loadWorkflowTaskDetail` 读取修订一致的聚合详情，只渲染 Surface 返回的操作。
+旧 Surface 与 timeline 读取继续供兼容客户端使用。
+
+平台在当前环境 Head 的不可变 Contract Bundle 上统一解析：桌面/移动工作台、
+Notification Hub 的 `workflow.detail` 逻辑目标、钉钉卡片以及其他渠道快照得到
+同一组自定义路径。未声明时保留标准详情；声明存在但 route 缺失、surface 错误或
+path 不合法时严格失败，不退回标准页掩盖合同错误。
+
+标准详情由平台统一渲染，不要求应用复制资源详情页。Workflow Surface 的
+`presentation.businessDetail` 按实例固定的 Data logical revision、资源声明 digest 和
+physical resource 定位结构，但每次读取同一 Native Data record 的当前字段值；发起时
+`requestedRevision` 只用于命令 token/CAS，当前 `sourceRevision` 和当前值始终随重新读取更新，
+禁止把业务字段值改成流程启动快照。字段投影同时应用当前用户策略并统一排除
+`system: true`、平台内部字段与过滤后为空的分组；
+父子表按同一 logical revision 和父记录外键读取，单表最多 200 行。页面同时消费
+`presentation.summary`、服务端 timeline `display.entries` 和 operation descriptors。
+桌面端与移动端拥有独立 DOM；同意/拒绝等决策操作固定在底部主操作区，转交、退回、
+加签等低频操作进入“更多操作”，意见只在点击动作后的确认弹窗或移动端底部抽屉中输入。
+`stale` 只是 revision 元数据，不显示常驻横幅也不预先阻断操作；只有服务端命令 token/CAS
+返回真实 `freshSurface` 冲突时才提示“内容已更新，请刷新后重试”，且绝不自动重放命令。
+同意、拒绝、退回、转交和加签记录并入对应纵向节点；实例撤回/终止是独立终态事件，
+展示操作者、动作、意见和唯一 `primaryDisplayTime`，
+不另设“操作记录”。标准业务页不渲染流程/任务/资源/记录 UUID、事件序列、revision 或失败指针。
+申请人、审批人和操作者显示目录/快照解析名称、可选部门以及真实头像；缺失或加载失败时
+统一使用平台默认头像，不生成姓名首字，也不回退 userId。
+
+PC 标准任务与实例详情的 canonical 路径分别为 `/tasks/:taskId` 和
+`/workflows/:instanceId`，使用独立全屏页面，不进入后台 Shell；不提供旧 admin 路径的
+别名或重定向。移动端继续使用独立的 `/m/tasks/:taskId` 和 `/m/workflows/:instanceId` 页面。
+
+流程详情中的附件、富文本图片和签名不直接复用普通 Data API 文件地址。浏览器调用
+Workflow instance-scoped preview/content 路由，平台在每次文件读取时重新校验当前身份、
+实例参与权限、固定业务记录、资源、字段和 file id；URL 不携带登录态或替代身份。
+
+标准发起页使用独立的 `WorkflowLaunchSurface` 读取当前激活合同：桌面路径为
+`/workflows/:workflowCode/start`，移动路径为
+`/m/workflows/:workflowCode/start`。`standalone`/`hidden-handoff` 缺省使用同一个
+compiler-owned `processOperationCode`、subject declaration 和标准 process commit；平台在一个
+事务中写业务数据和 durable command。action-owned 资源改为声明
+`launch.submission.kind: 'named-operation'`，显式绑定 create/existing 请求来源、响应 subject/
+processCommand 路径和 allowlisted context 预填。标准页调用原 Named Action，由应用服务端保留
+业务校验、幂等与原子提交；缺少/null processCommand 是成功的免审结果，不生成流程。页面只在
+确实返回 command 时把 `commandId` 写入 URL，刷新、跨设备和 worker 恢复都重新读取
+`ProcessCommandSurface`；`awaiting_input` 只回答已生成 requirement，`started` 再进入 pinned
+instance entry。浏览器不再导出 prepare/start 发起协议。
+
+通用应用待办页通过 `frontend.user.applicationTodoCenter: true` 启用，平台同时提供
+`/todos` 和 `/m/todos`。它只投影当前登录用户的 Notification Hub 收件人数据，
+`查看详情` 使用上述统一导航解析；待办页不常驻业务详情，审批命令仍在目标 Workflow
+Surface 上执行。
+
+## 应用声明
+
+应用只在明确启用可选模块时，在 `openxiangda.config.ts` 声明 workflow definition、binding、assignee provider、notification profile、template reference 和安全字段投影。Git 声明是拓扑事实源；平台管理页面只负责版本、激活、预览、诊断和有界运行参数，不建立第二份活动定义。
+
+事件处理器调用 `OpenXiangdaBusinessNotificationService.sendFromEvent()` 时，
+对应订阅还必须声明
+`platformAccess: { notification: { mode: 'business-standard' } }`。编译器将该声明写入
+不可变 Configuration/Contract Bundle，并据此生成精确的 `notification-hub-v2`
+能力闭包；不发送通知的订阅不得声明该依赖，未知 access 或 mode 直接失败。
+
+## 验证
+
+至少验证：完整标准详情投影、父子表边界、流程附件读取、桌面/移动独立渲染、全部标准操作、多人模式、重复/并发命令、stale revision、重启 replay、乱序事件、重复回调、消息终态全量更新、详情跳转、错用户/错租户/过期动作、渠道超时/unknown、死信重放和 1.x 零触碰。

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

@@ -1,9 +0,0 @@
-# OpenXiangda 2.0 Architecture
-
-Keep one React application, one optional NestJS service and one platform-owned data contract. Application code directly depends only on `openxiangda`; use `openxiangda/config`, `openxiangda/core`, `openxiangda/field-kit`, `openxiangda/react`, `openxiangda/nest` and `openxiangda/testing` as the public subpaths. Do not import the physical `openxiangda-*` implementation packages.
-
-Declare resources, routes, capabilities, row policies and operation-aware field policies once in `openxiangda.config.ts`. The compiler owns derived contracts; the root package owns Field Kit, CRUD Renderer, Shell, clients and Nest integration; the platform owns identity, authorization, data, environment Heads and deployment state.
-
-The compiler alone derives the AppPackage `requiredPlatformCapabilities` closure. Each entry binds a capability `code`, exact `contractVersion` and deterministic `usageDigest` of only that capability's normalized declarations. Never write `platform.requiredCapabilities`, append requirements through a build API, edit the AppPackage or accept a feature whose status is not `available` or whose contract version differs. The platform authoritatively recomputes the closure from the sealed config and contract artifacts.
-
-Ordinary list, detail, create, update and delete operations go directly through Data API. Add a NestJS endpoint only for a business action that cannot be represented as CRUD. Run `pnpm openxiangda check` after every contract change.

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

@@ -1,21 +0,0 @@
-# OpenXiangda 2.0 Commands
-
-> Generated from `DEVKIT_COMMANDS`. Do not edit manually.
-
-| Command | Risk | Purpose |
-| --- | --- | --- |
-| `pnpm openxiangda create` | deploy | 创建、绑定并初始化应用 |
-| `pnpm openxiangda dev` | write-local | 连接平台测试数据启动本地 Web，按需启动 Nest |
-| `pnpm openxiangda check` | write-local | 生成契约并在目标平台预检后执行检查、测试和构建 |
-| `pnpm openxiangda accept` | deploy | 按计划准备可选的真实预发验收身份 |
-| `pnpm openxiangda deploy` | deploy | 部署测试环境或显式复用测试版本部署生产 |
-| `pnpm openxiangda status` | read | 查询最近或指定部署状态 |
-| `pnpm openxiangda logs` | read | 查询最近或指定部署日志 |
-| `pnpm openxiangda cancel` | deploy | 幂等取消尚未提交激活的部署 |
-| `pnpm openxiangda retry` | deploy | 显式重试可恢复的失败部署 |
-| `pnpm openxiangda start` | deploy | 从当前不可变版本启动应用环境 |
-| `pnpm openxiangda stop` | deploy | 将应用环境缩容为零并保留数据 |
-| `pnpm openxiangda rollback` | deploy | 回滚测试或生产环境 |
-| `pnpm openxiangda login` | write-local | 通过平台浏览器授权登录 |
-| `pnpm openxiangda skill` | write-local | 安装当前版本的 AI Skill |
-| `pnpm openxiangda spec` | write-local | 维护可选的 AppSpec 需求与变更辅助 |

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

@@ -1,15 +0,0 @@
-# Requirement Discovery
-
-Before editing, write a compact decision record covering:
-
-- business objective and measurable outcome;
-- actors and positive/negative scenarios;
-- resources, field meanings, required values and lifecycle states;
-- role memberships, operation capabilities, field restrictions and row scope;
-- external systems, side effects, concurrency and idempotency;
-- environment, security, volume and latency bounds;
-- acceptance evidence for UI, API, PostgreSQL/RLS and delivery.
-
-Separate known facts, assumptions and unresolved choices. Inspect the workspace protocol and existing declarations before inventing a contract. If a choice changes data meaning, authorization, external writes or release scope, resolve it before implementation. Ordinary naming or layout details may use a documented reasonable assumption.
-
-The output is complete only when every requirement maps to an owner and a falsifiable acceptance check. Do not begin with source patches and reconstruct intent afterward.

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

@@ -1,62 +0,0 @@
-# OpenXiangda 2.0 Application Agent Contract
-
-- Use only the workspace-pinned CLI: `pnpm openxiangda <command>`. Never invoke a bare global `openxiangda` inside a 2.0 task.
-- Maintain business goals, task pages, permission decisions and acceptance examples in the existing `appspec/app.md`; complex modules may have focused capability records. `appspec/` is the OpenXiangda 2.0 business-intent layer. Before changing observable behavior, read the bounded index with `pnpm openxiangda spec context --json`, then select only the relevant stable ID; use no ChangeSpec for L0 work, one short ChangeSpec for L1, and add permission/rollback/concurrency detail only for L2/L3. Before close, the user—not AI—confirms `currentSpec=merged` or `not-applicable`. AppSpec is advisory and never a release gate. Never read, import or migrate 1.x `openspec/` or SDD.
-- Use Vite, React Router, Refine Core and platform Field Kit. Use Ant Design for PC and the scoped openxiangda/mobile adapter for touch controls; wrap custom mobile pages in MobileSurface and import openxiangda/mobile/styles.css. Do not import the antd-mobile root with its global reset. Do not author raw business input/select/textarea/contentEditable elements. Keep mobile entrypoints under src/mobile/ or name them Mobile*.tsx / *.mobile.tsx so openxiangda check can inspect their local dependency graph. Do not add Umi, ProComponents or another admin shell.
-- Use Ant Design's default component appearance on PC and the platform's scoped mobile adapter for touch controls. The UI provider supplies Chinese locale and contextual feedback only. Do not generate appearance preferences, color configuration, palette registries, visual state stores or document-wide color effects. Prefer platform components and keep CSS scoped to the component.
-- The template includes Tailwind CSS v4 utilities for user pages. The application owns its minimal document reset; omit preflight from the shared runtime and do not scaffold custom palettes.
-- Bind every generated `appRoutes` entry to its local page with `defineApplicationContributions`; desktop `admin` routes stay inside the platform Shell, while `user` routes render without an admin Shell for independent mobile/user experiences. Generated resource CRUD routes are compiler-owned under `/admin/resources/<resourceCode>...` and `/m/admin/resources/<resourceCode>...`; never recreate root resource paths, aliases or redirects. Explicit routes that have the same canonical shape as another explicit or generated route fail compilation, even when dynamic parameter names differ. Use only the typed `toolbar`, `row` and `detail` resource slots for generated resource actions. Declare the complete editable admin menu with `defineAdminNavigation` and its page/group helpers; the Shell renders only generated `adminNavigation` references and permissions only filter them. Do not create another router, menu store, layout, identity provider, permission store or copied CRUD page; route/action access uses capability or `allOf`/`anyOf`, while Data/App API and Workflow authorization remain server-owned.
-- Application login is optional `frontend.authentication`: existing platform users only, registration rejected, exact desktop `/login` and mobile `/m/login`. Bind generated `authenticationSurfaces` to separate PC/mobile renderers through `defineApplicationContributions`; renderers own only brand visuals and call `ApplicationLoginSurfaceProps`. The platform alone owns passwords, providers, OAuth state/callbacks, secure cookies, current identity and authorization. Never put login in protected `appRoutes`, call a v1 auth route, store tokens, create users/roles, or add another Router/identity provider. Keep QA in generated `platformAuthManifest`, outside the protected route denominator.
-- Branded standard user pages use the optional exact `standardUserSurfaces` contribution from `openxiangda/react`: provide separate desktop/mobile `frame` and `applicationTodoCenter` renderers or omit the property entirely. The platform still owns `/todos`, `/m/todos`, Workflow routes, `RuntimeBoundary`, current-user Notification Hub data, query/load/interaction callbacks and navigation. Never add a second Router, Todo API client, identity store or token prop.
-- External users without platform accounts use only an exact static `surface: 'user'` route declared through `frontend.publicAccess`. Declare the one resource, bounded field sets, required operations, draft limits and named duplicate validations; consume only generated `anonymousPublicAccess` and `createAnonymousPublicClient`. `own.list`/`own.read` mean records submitted by the same platform-issued HttpOnly browser credential, not a verified natural person, and another browser or cleared cookie intentionally loses access. Never create a guest role/user, call the general Native Data API, expose an anonymous upload path, store identity locally or derive ownership from IP, user-agent or fingerprint.
-- Define storage with `defineDataModel` in `modules/<business>/models.ts`; compose modules with `defineApplicationModule`. Select standard pages explicitly through `crud`, `defineResourceList` and `defineResourceForm`. Models without `crud` receive no pages or navigation. A business task page may consume several models. The root `openxiangda.config.ts` composes modules, routes and roles; it must not grow into one giant business definition. Existing `data.resources` remains a lower-level input to the same compiler. Keep internal fields `hidden: true`; this is presentation, never authorization. `system: true` marks server-owned values and hides them by default; `hidden: false` may show a business status or serial number. Form/detail/list field selections are exhaustive and ordered. A Workflow subject resource may declare explicit desktop/mobile `detailRouteCode` as documented in the workflow contract.
-- Never write resource-level `schemaVersion`, `appCode`, `schema`, `surface`, `capabilities`, `fieldPolicies` or `platform/data` modules. The compiler derives the strict DataResource, CRUD capabilities, Surface and AI Schema. The application manifest still starts with its one top-level `schemaVersion: 3`.
-- Ordinary list/get/create/update/delete, filters, export and batch operations use the platform Native Data API. Do not create Function CRUD or NestJS wrappers.
-- Standard PC lists use one toolbar, on-demand filters/column settings and drawer create/edit over the retained list. Full-page entry uses the same platform form. Declare shared form/detail groups with `crud[].sections: [{ title, fields }]`; each view's field selection remains exhaustive and ordered. Small forms may omit groups. Keep only business columns by default, use lightweight sections and let platform components handle pending, errors and dirty cancellation. Do not recreate list/form layouts in application code.
-- Add NestJS only for a named business action that needs a cross-resource transaction, an invariant or an external side effect. The blank app contains no apps/server source or Nest dependency importer. Declare backend.enabled or a server operation, then run pnpm openxiangda check or pnpm dev to initialize and install the optional backend once; existing source is never regenerated. Standard platform workflow definitions and activations do not require Nest.
-- One model can declare up to 20 named standard views with `crud[].code` and `name`. Each selects its own list/form/detail fields, sections, generated operations and mobile availability. Bind navigation with `adminResourcePage(modelCode, { viewCode })`; only an unnamed CRUD declaration generates the original default routes. Views share model values, access and Data API ownership. Include writable required fields in create forms or set `generated.create: false`. Keep platform display preferences and authenticated drafts scoped to the selected view; do not copy models or invent a second draft store.
-- Every interactive business action binds `@OpenXiangdaOperation(operation)` and injects `OpenXiangdaBusinessDataApiService`, `OpenXiangdaBusinessNotificationService`, or `OpenXiangdaStandardOperations`. The platform checks the action capability once at App API ingress; the trusted backend then has full Data/managed business-notification access only to its exact application/environment while audit retains the initiating user and action. Do not author `authorizationJSON`, forward user tokens, grant ordinary users `app:notification2:send`, or reapply the user's resource, row and field permissions inside the action.
-- A NestJS backend declares only `enabled`, `isolation: 'shared' | 'dedicated'` and `resourceProfile: 'light' | 'standard'`. Never put raw Kubernetes resources, replicas, ports or environment maps in application metadata; the platform owns capacity and scaling.
-- Use the current logged-in user and the union of that user's application roles. An app for every logged-in platform user may declare one existing package role through `authz.authenticatedUserRoleCode`; the platform materializes it on first access and unions it with manual and business-projected roles. Do not fabricate a browser fallback role or use a business membership resource for this universal audience. An optional declared Perspective projects only read visibility (pages, rows and fields); create/update/delete, workflows and custom actions continue to authorize against the complete union. Standard Data API calls inherit `X-OpenXiangda-Perspective` automatically. Use `@CurrentPerspective()` only when custom Nest code reads outside the standard Data API, and apply an equivalent read projection explicitly. Business code must not persist a platform Token or authorization result and must not implement a second identity path.
-- Fields inherit the resource read/create/update capabilities. Use field `access` only to tighten them; arrays are all-of and `false` is explicit deny. There is no `write` fallback.
-- Field `type` is semantic, never a hand-authored database type. The supported catalog is exactly `text.short`, `text.long`, `text.rich`, `number.integer`, `number.decimal`, `boolean`, `date`, `time`, `datetime`, `date-range`, `datetime-range`, `option.single`, `option.multiple`, `cascade.single`, `cascade.multiple`, `user.single`, `user.multiple`, `department.single`, `department.multiple`, `resource-ref.single`, `resource-ref.multiple`, `file`, `image`, `signature`, `address`, `location`, `json`, `serial-number`, `uuid` and `subtable`. The compiler alone derives PostgreSQL columns, constraints and indexes.
-- Every `date-range` and `datetime-range` field explicitly declares `rangeBoundary: 'closed' | 'half-open'`. Values remain `{ start, end }`; callers never send or override the boundary. Closed ranges allow `start <= end` and use PostgreSQL `[]`; half-open ranges require `start < end` and use `[)`.
-- Declare every custom operation capability in `authz.capabilities` with `kind: 'backend'`, then reference that same code from the operation and its allowed roles. Generated resource CRUD capabilities do not go in this catalog.
-- Build App Operation request/response schemas with `resourceRecordSchema`, `schemaRef`, `composeJsonSchema` and `composeAppOperationSchemas` from `openxiangda/config`. They project the same Resource declaration and canonical field value protocols; never import a physical toolchain package or repeat user, department, resource-reference or managed-file schemas by hand.
-- Visitor duplicate protection uses `createVisitorReservation({ duplicateMatch: { fieldCode: submittedValue }, ... })`. `duplicateMatch` is a non-empty value map, never a field-name array, and no mutable pre-read is allowed.
-- Desktop and mobile pages share values, validation and authorization, but use separate renderers. Options, members and departments store display snapshots; resource references store direct JSON display values; attachments, images and signatures use platform-managed file references.
-- `option.*`, `user.*`, `department.*` and `resource-ref.*` values never collapse to scalar IDs. Single values store one labeled object and multiple values store object arrays. `resource-ref.*` JSON is not a foreign key, trusted target snapshot or automatically refreshed copy; current target state is read by `resourceCode` plus `value`. A resource source `labelField` must be `text.short` or `text.long`; `serial-number` is allowed in source search, description and snapshot fields, but not as the label. `location` accepts only exact WGS84 coordinates captured by DingTalk or browser geolocation; it has no manual input or `manual` source. Roles that consume directory-backed fields explicitly include `app:<app-code>:directory:read`.
-- Use `resourceRoleCapabilities(appCode, resourceCode, "read" | "manage" | [operations])` for explicit role grants. A read grant never expands into create/update/delete when a page is added. Confirm the business permission matrix before implementing multi-role behavior; `manage` is only for roles explicitly allowed all CRUD operations. Use `currentUserDataPolicy(...)` for current-user row scope.
-- Do not add compatibility aliases, migration branches or silent fallbacks for an earlier 2.0 alpha contract. Replace an incorrect contract and regenerate the application.
-- Standard Workflow and Notification Hub are optional 2.0 modules. Enable them only through canonical `openxiangda.config.ts` declarations and generated clients. `standalone`/`hidden-handoff` default to the compiler-owned process operation; action-owned submission must instead declare `launch.submission.kind: 'named-operation'` with sealed create/existing input and output bindings so the standard PC/mobile page calls the original Named Action and accepts an explicit no-Workflow result. Never add a browser save callback or call Workflow prepare/start directly. Custom pages launch only through a verified Named Action using `OpenXiangdaBusinessProcessService`. PC and mobile render the same `ProcessCommandSurface` independently and recover only by `commandId`. To replace Workflow detail, declare both desktop and mobile `detailRouteCode` values whose routes contain exactly `:instanceId`. Add the current-user todo page only with `frontend.user.applicationTodoCenter: true`; never query Notification Hub management APIs from a user page.
-- Run `pnpm openxiangda check --json` after contract changes and read `data.sealedArtifact`; check never seals, and an older `.openxiangda/build/app-package.json` is not the current check result. Use `pnpm openxiangda accept --plan <file>` only for optional real preproduction identity acceptance; it never blocks delivery. Deploy with `pnpm openxiangda deploy`, inspect with `pnpm openxiangda status` and `pnpm openxiangda logs`, and use the platform rollback command rather than mutating K3s directly.
-- AI-native clients start the workspace protocol through the same pinned binary: `pnpm exec openxiangda --mcp-stdio --cwd <workspace>`. Read `openxiangda://workspace/contracts` or call `contract_describe`; for first-time menu authoring, copy `data.adminNavigationAuthoring.suggestion.expression` once into `frontend.admin.navigation` with its listed `openxiangda/config` imports, then edit that application-owned declaration. Never treat the proposal as runtime discovery. When AppSpec is enabled, also read `openxiangda://workspace/appspec` or call `appspec_context`. Require `aiCatalog` and `aiCatalogDigest` to match the normal compiler output. This is a stdio transport mode, not another application-owned server. Never write an application MCP server, Catalog file, preview store or second authorization path.
-
-- For an ordinary CRUD module, omit unused backend/platform blocks; the platform owns CRUD. `pnpm dev` uses connected development and starts Nest only when enabled or required by declared server capabilities. Run interface tests for changed business rules and browser tests for the actual PC/mobile create/edit/save/read journeys; passing HTTP tests alone is not acceptance.
-
-
-## Standard data entry and list controls
-
-Use the platform standard list for nested AND/OR conditions, display-column
-selection/order/freezing and multiple sorting. Set `requiresSelection: true` on
-selection-dependent toolbar contributions. Preserve hidden fields and query /
-export parity. Column changes preview immediately and save to current-user
-platform preferences explicitly.
-
-Standard forms use Save draft / Submit. Consume platform authenticated drafts;
-do not create application draft tables, localStorage or Nest draft endpoints.
-PC drawer controls are Full screen / New page / Close, with a platform draft
-handoff to the new page. Mobile entry uses grouped touch-field rows, a simple
-title and a fixed action footer, with bottom sheets for drafts and recovery.
-Do not add a mobile Back to list action or desktop form controls. Preserve edit
-revisions and draft CAS; successful submission consumes the draft atomically.
-
-## Optional application backend
-
-The default scaffold contains Web and shared contracts only. Declare
-`backend: { enabled: true }` or application server capabilities, then use the
-existing `pnpm openxiangda check` / `pnpm dev` loop. The tool initializes Nest
-source and its exact dependencies once, preserves authored source, and retries
-an interrupted dependency install. Standard platform workflow activation does
-not imply application Nest. See `docs/backend.md` and the runnable
-`examples/business-action-extension` for SDK ownership and transaction retries.