openxiangda-skill-kit 2.0.0-alpha.98 → 2.0.0

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

@@ -1,167 +1,181 @@
-# Workflow, Events and Notification Hub
+# Workflow 与 Notification Hub 2.0 边界
 
-Read [Architecture](architecture.md), [Data and authorization](data-authz.md)
-and [Testing](testing.md) before enabling this optional layer.
+标准 Workflow 与 Notification Hub 已作为 OpenXiangda 2.0 可选平台模块重新开放。它们不属于默认 CRUD 模板，也不兼容或复用 1.x 工作流、消息中心、模板、卡片、回调、表和 API。
 
-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
+普通记录、流程记录、任务和实例复用同一详情框架。流程详情提供申请内容、审批历史和变更记录三个标签页；管理员在当前抽屉或页面中切换到普通表单编辑，直接保存并自动留下变更记录，审批结果保持不变。PC 子表在表格内编辑，父表提交时统一校验。
 
-- 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 查询 `pending`、`handled`、`created`、`cc` 四种视图；消息中心默认向 Notification Hub 查询 `view=all`，沿用应用声明的渲染扩展。各入口按服务端 `detailNavigation` 打开详情，页面不自行拼接人员范围。
 
-## Workflow declaration
+抄送由动态 Surface 提供 `cc` 操作，使用 `user_select` 多选组件收集 1 至 20 位人员。任务 Surface 可以正式包含实例抄送命令；前端按 `operation.execute.href` 和该 Surface 的 token 提交，不另造任务命令或 token。公共事件为 `openxiangda.workflow.instance.cc_added.v2`。
 
-Declare workflow topology and bindings once in `openxiangda.config.ts`. Use only approval, condition and end nodes for the standard module. Keep business data in Data API/App API and pass an immutable `dataRef`, business revision and bounded facts into prepare/start.
+## 能力 owner
 
-Every definition declares a launch mode: `standalone` for a self-contained
-generated save-and-start 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. Only `standalone` may be referenced by
-`adminWorkflowLaunchPage`; the generated browser runtime uses the workflow's
-localized definition title, so applications do not maintain code-to-title
-maps. A standalone page receives all durable business context through its
-typed save handler and URL/search contract; it must never depend on transient
-router location state. Work center, task and instance pages remain reachable
-without becoming launch menu entries. Bind the generated metadata with
-`defineWorkflowLaunchContributions(workflowDefinitions, handlers)`; handlers
-only persist the durable business revision, while generated code keeps title
-and launch mode authoritative.
+- 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 的发起、任务与操作授权。
 
-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.
+Workflow 发起只接受 `{ resourceCode, id }` 形式的 `dataRef`，并要求独立的
+正整数 `dataRevision`。definition 的 `inputSchema` 根对象必须显式
+`additionalProperties: false`，未声明的 facts/answers 直接拒绝。Provider
+回调只接受带完整业务/数据/definition/binding/fact digest 的
+`openxiangda.workflow-assignee-request/v2.1`。
 
-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.
+## 标准工作流范围
 
-## Submission and concurrency
+首期只支持 `approval`、`condition`、`end`，以及 `single`、`any`、`all`、`sequence` 审批模式。标准操作为提交、同意、拒绝、退回、重新提交、转交、委托、前/后加签、撤回、管理员改派、管理员终止和不改变流程状态的催办。
 
-1. Persist the business draft through Data API/App API.
-2. Bind prepare to the saved revision and all submission answers.
-3. Resolve required organization/approver choices.
-4. Start with a stable idempotency key distinct from the draft-save key.
-5. Use the Surface revision/concurrency token for every command.
+复杂业务状态机继续放在应用领域服务。不要把任意 JavaScript、Service Task、BPMN、通用长事务或业务记录复制进 Workflow。
 
-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 Surface 的 `operations[]`。前端、模板和渠道 Adapter 不自行推断操作权限。
+Surface 同时签发短期、一次性的 `commandToken`，绑定当前用户/会话、应用环境
+Head、实例/任务版本、允许的命令集合与 CSRF。命令请求只提交
+`commandToken + idempotencyKey + input`；旧的 caller-authored
+`expectedTaskVersion`/`expectedInstanceVersion` 不再是合同。冲突必须刷新 Surface，
+不得自动重放旧意图。
 
-## Notification profile
+## 事实和消息投影
 
-A node may reference a notification profile that selects:
+Workflow 在同一 PostgreSQL 事务中提交状态、fact 和 outbox。每个实例使用严格单调的 `instanceSequence`，每位审批人拥有独立 participant 生命周期。
 
-- 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.
+Native Data 事件的 capture plan 由当前 Head 的 Event、Data、AuthZ revision
+与 resource 四元组共同确定。新增快照字段或扩展 RLS 会形成新的不可变 plan，
+不会与旧 plan 冲突；历史 replay/re-emission 复制原 fact 的数据与 plan digest，
+不会用当前 Head 重新投影历史事实。
 
-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.
+每条 Workflow fact v2 都必须携带不可变实例身份信封：`workflowCode`、
+`definitionVersion`、`bindingVersion`、`instanceId`、`generation`、
+`businessKey`、`instanceSequence`、`revision`、`dataRef`、`dataRevision`、
+`actor` 与 `cause`。消费者不得从当前 Workflow Head 反推历史事实版本。
 
-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.
+配置中的 `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'`，不接受下划线别名。
 
-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.
+Notification Hub 消费事实：
 
-## Detail navigation
+- `participant.activated` 创建待处理消息；
+- participant 完成、转交、委托、加签、暂停或恢复时更新对应收件人的逻辑消息；
+- instance 完成、拒绝、撤回或终止时更新该实例全部历史消息；
+- 消息回调必须调用 Workflow 命令，等待 Workflow 新事实后再更新卡片。
 
-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.
+发送采用至少一次语义，以 `messageKey + recipient + channel` 幂等。RabbitMQ 只负责唤醒，PostgreSQL fact、message projection、outbox 和 receipt 才是恢复事实。
 
-The Notification Hub resolves desktop, mobile and channel deep links. The landing page always re-runs platform authentication and Data/AuthZ/Workflow authorization.
+## 详情跳转
 
-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`:
+消息使用 canonical `navigationTarget`，而不是模板拼接环境 URL。它可以描述平台路由、应用路由或白名单外部地址，由平台按 tenant、environment 和 channel 解析 desktop/mobile/deep link。
 
-```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: [],
-},
-```
-
-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.
-
-Standard launch entry is also a platform Surface. Desktop uses
-`/admin/workflows/:workflowCode/new` and mobile uses
-`/m/workflows/:workflowCode/start`; both first load
-`loadWorkflowLaunchSurface(workflowCode)`, then use the same durable
-`saveBusinessRevision -> prepareWorkflowStart -> startWorkflow` protocol.
-`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 in explicit admin navigation with
-`adminApplicationTodoCenterPage()`. 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
+详情地址不能携带登录 Token、Cookie 或任何身份替换凭据。点击后必须重新认证，并由 Data/AuthZ/Workflow 执行真实权限校验；当前 Perspective 只能重新应用读取投影。
 
-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.
+“跳回业务记录”和“完全接管流程详情”是两个不同合同。标准 Workflow 页需要提供
+“查看业务详情”时，在 subject resource 上声明明确的 route code 对：
 
-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
+```ts
+const purchaseResource = {
+  code: 'purchases',
+  name: '采购申请',
+  detailRouteCode: {
+    desktop: 'purchase-record-detail',
+    mobile: 'purchase-record-detail-mobile',
+  },
+  fields: [/* ... */],
+} satisfies AppDataResourceDeclaration;
+```
 
-Consume typed participant/task/instance facts with durable idempotency. Order Workflow message projection by `instanceId + instanceSequence`; never assume global event order. Terminal instance facts dominate stale participant facts and update every historical message for that instance.
+两条 route 都必须是已认证的 `surface: 'user'` 页面并要求该资源的 read capability；
+桌面 path 不得进入 `/m`，移动 path 必须以 `/m/` 开头，且各自只能包含一个动态记录参数。
+参数名可以是业务语义名，例如 `:purchaseId` 或 `:applicationId`。编译器把映射写入
+不可变资源 Contract 和生成的 `resourceDefinitions`，平台从同一环境 active Contract
+读取并代入 Workflow Surface 已授权的 recordId。未声明时返回空业务记录目标；已发布
+映射畸形时严格失败。平台和浏览器都不得再按 `resourceCode` 猜路径，也不得用别名补洞。
 
-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.
+流程需要完全接管详情页时，在 definition declaration 上声明桌面端与移动端 route code：
 
-## Verification
+```ts
+{
+  version: 1,
+  definition: purchaseApproval,
+  launch: { mode: 'work-center-only' },
+  detailRouteCode: {
+    desktop: 'purchase-detail',
+    mobile: 'purchase-detail-mobile',
+  },
+}
+```
 
-Run the workspace generate/check/test/build gates plus real current-user positive and negative role-union cases. Acceptance must include 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,7 +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.
-
-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,25 +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.
-- `appspec/` is the optional 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 Ant Design. Do not add Umi, ProComponents or another admin shell.
-- 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.
-- Declare each resource once in `openxiangda.config.ts` with only `code`, `name`, `fields` and optional `mutationOwner`, generated/list/layout/data-policy settings. Each field owns type, label, required state, Surface flags, reference/file metadata and access. Resource codes are lower kebab-case. Use `native` for direct Data API mutations, `action`, `readonly` or `workflow` for non-Native ownership; never grant or generate Native mutation for a non-Native owner.
-- 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.
-- Add NestJS only for a named business action that needs a cross-resource transaction, an invariant or an external side effect.
-- 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 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.
-- 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`.
-- Derive role grants with `resourceCapabilityCodes(appCode, resourceCode)`. Declare current-user rows only with `currentUserDataPolicy(...)`; do not invent operators, values or alternate current-user spellings.
-- 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 the canonical `openxiangda.config.ts` declarations and generated clients; declare each Workflow launch as `standalone`, `custom-page`, `hidden-handoff` or `work-center-only`, put only self-contained standalone launch pages in navigation, and bind durable save handlers with `defineWorkflowLaunchContributions` without repeating generated titles. Desktop and mobile standard launch pages load the same canonical Workflow launch Surface. To replace Workflow detail, declare both desktop and mobile `detailRouteCode` values whose routes contain exactly `:instanceId`; Work Center, the application todo center and notification channels consume the platform-resolved paths, while every Surface and command remains server-authorized. Add the standard current-user todo page only with `adminApplicationTodoCenterPage()`; never query Notification Hub management APIs from a user page. Never depend on temporary router location state or copy 1.x workflow/message code, tables, APIs, templates or callbacks into this workspace. Keep ordinary CRUD and application-specific state machines independent of them.
-- 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.