openxiangda-skill-kit 2.0.0-alpha.92 → 2.0.0-alpha.94

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openxiangda-skill-kit",
-  "version": "2.0.0-alpha.92",
+  "version": "2.0.0-alpha.94",
   "description": "Validation and deterministic packaging for OpenXiangda 2.0 AI skills.",
   "type": "module",
   "main": "./dist/index.js",
@@ -17,7 +17,7 @@
     "README.md"
   ],
   "dependencies": {
-    "openxiangda-devkit-core": "2.0.0-alpha.73"
+    "openxiangda-devkit-core": "2.0.0-alpha.75"
   },
   "devDependencies": {
     "tsx": "4.23.12",

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

@@ -43,22 +43,39 @@ discovery, and permission logic cannot create entries. Read
 proposal is deterministic and editable; the compiler/runtime never invokes it
 or appends newly added resources later.
 
-For a custom admin operation page, declare the route in
-`openxiangda.config.ts`, import the generated `appRoutes`, and bind every route
-key to exactly one local React page with `defineAdminContributions` from
-`openxiangda/react`. Pass the result to `OpenXiangdaApplication`. Do not wrap the
-page in another `Shell`: the runtime registers it in the unified router and the
-same Shell owns its menu entry, title, history and direct-URL capability gate.
-Only static admin routes explicitly referenced by `frontend.admin.navigation`
-enter the menu. Hidden routes retain the same `capability` or
-`access.allOf/anyOf`, including ancestor constraints. Never add an
-application-owned layout, router, identity provider, permission store or a
-second menu store. Keep operation pages under `/admin/operations`;
-parameterized routes remain reachable but cannot be menu references.
+Declare custom routes in `openxiangda.config.ts`, import the generated
+`appRoutes`, and bind every route key to exactly one local React page with
+`defineApplicationContributions` from `openxiangda/react`. Pass the result to
+`OpenXiangdaApplication`. The runtime registers `surface: 'admin'` routes inside
+the one platform Shell; do not wrap them in another Shell. It renders
+`surface: 'user'` routes without the admin Shell so mobile/user experiences can
+own their page layout without creating another router, identity provider or
+permission store. Only static admin routes explicitly referenced by
+`frontend.admin.navigation` enter the menu. Hidden routes retain the same
+`capability` or `access.allOf/anyOf`, including ancestor constraints. Keep admin
+operation pages under `/admin/operations`; parameterized routes remain
+reachable but cannot be menu references. `defineAdminContributions` remains an
+admin-only helper and intentionally rejects `user` routes.
+
+This is also the whole-application composition contract: pass the resulting
+`contributions` to `OpenXiangdaApplication` and let that component remain the
+only owner of `BrowserRouter`, `RuntimeBoundary`, Refine, generated resource and
+Workflow routes, and the admin Shell. A user page may render an independent PC
+or mobile layout, but it must not add a nested router/Shell or copy generated
+routes. Route parameters continue to come from React Router, and generated
+capability plus ancestor access guards run before the component renders.
+
+To expose the standard application-level todo center, add
+`adminApplicationTodoCenterPage()` to an explicit admin navigation group. The
+compiler generates `/admin/todos`; the same runtime exposes the independent
+mobile `/m/todos` page. The page reads only the authenticated user's
+Notification Hub recipient projection and deep-links to the platform-resolved
+target. Do not query Notification Hub management endpoints or recreate a local
+message state store.
 
 For a small business action on a generated resource page, use the typed
 `resources[resourceCode].toolbar`, `.row` or `.detail` slots accepted by
-`defineAdminContributions`. Declare a stable action code, label and
+`defineApplicationContributions`. Declare a stable action code, label and
 capability/access expression. The render context contains only the current
 resource, already-authorized record or selection, and a bounded `refresh()`;
 it does not own CRUD, revisions, fields or authorization. Invoke a guarded Nest

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

@@ -84,6 +84,70 @@ Use a canonical navigation target with `PLATFORM_ROUTE`, `APP_ROUTE` or allowlis
 
 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`:
+
+```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
 
 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.

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

@@ -3,7 +3,7 @@
 - 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.
-- Keep generated admin routes and custom actions inside the platform Shell. Bind generated `appRoutes` to local operation pages with `defineAdminContributions`, and use only its typed `toolbar`, `row` and `detail` resource slots. Declare the complete editable 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 authorization remains server-owned.
+- 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. Use only its 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.
@@ -20,6 +20,6 @@
 - `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. 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.
+- 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.