openxiangda-cli 2.0.0-alpha.116 → 2.0.0-alpha.119

package/README.md

@@ -7,7 +7,10 @@ The CLI disables user, development and JIT plugin loading. A clean build removes
 AI-native development clients use the same pinned executable in pre-command
 stdio mode: `pnpm exec openxiangda --mcp-stdio --cwd <workspace>`. They can read
 `openxiangda://workspace/contracts` or call `contract_describe` to obtain the
-compiler-owned `aiCatalog` and `aiCatalogDigest`. This transport does not add a
-another executable and applications must not implement a second MCP server.
+compiler-owned `aiCatalog`, `aiCatalogDigest` and the typed copy-once
+`adminNavigationAuthoring.suggestion`. Copy its expression into
+`frontend.admin.navigation`; runtime never applies it automatically. This
+transport does not add another executable and applications must not implement
+a second MCP server.
 
 `dev` starts local Web/Nest hot reload and a loopback connected proxy. `deploy` defaults to test; production explicitly reuses a successful test AppVersion. Application binding, initialization, generation, tests and builds are internal stages rather than separate commands.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openxiangda-cli",
-  "version": "2.0.0-alpha.116",
+  "version": "2.0.0-alpha.119",
   "description": "Thin application-level CLI for OpenXiangda 2.0.",
   "type": "module",
   "main": "./dist/index.js",
@@ -21,10 +21,10 @@
   ],
   "dependencies": {
     "@oclif/core": "4.13.3",
-    "openxiangda-contracts": "2.0.0-alpha.55",
-    "openxiangda-devkit-core": "2.0.0-alpha.72",
-    "openxiangda-mcp": "2.0.0-alpha.72",
-    "openxiangda-skill-kit": "2.0.0-alpha.91"
+    "openxiangda-contracts": "2.0.0-alpha.58",
+    "openxiangda-devkit-core": "2.0.0-alpha.75",
+    "openxiangda-mcp": "2.0.0-alpha.75",
+    "openxiangda-skill-kit": "2.0.0-alpha.94"
   },
   "devDependencies": {
     "tsx": "4.23.12",

package/template/AGENTS.md

@@ -3,8 +3,8 @@
 - 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. Do not create another router, menu, 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.
-- Declare each resource once in `openxiangda.config.ts` with only `code`, `name`, `fields` and optional 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.
+- 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.
 - Add NestJS only for a named business action that needs a cross-resource transaction, an invariant or an external side effect.
@@ -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; never 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`; 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.
+- 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.

package/template/README.md

@@ -18,6 +18,14 @@ pnpm openxiangda dev
 
 字段组件、CRUD Renderer、Shell、Runtime 与 Data/Directory/File/App Client 都由 `openxiangda/react`、`openxiangda/field-kit` 和 `openxiangda/core` 统一提供，应用模板不复制这些实现。Nest 只在需要复杂事务或外部集成时增加 App API。标准客户端显式携带当前环境、使用同源 Cookie；业务代码不读取或持久化 Token、平台内部身份标识与授权结果。
 
+同一应用的自定义后台页、PC 用户页和移动用户页统一声明在
+`frontend.routes`，再用 `defineApplicationContributions(appRoutes, { pages })`
+逐项绑定本地组件并传给 `OpenXiangdaApplication`。后者是唯一的
+BrowserRouter、RuntimeBoundary、Refine、generated routes 和后台 Shell
+所有者；用户页可以拥有独立布局，但不要再建 router/Shell。要使用通用应用待办中心，
+在显式后台导航组中加入 `adminApplicationTodoCenterPage()`；平台生成
+`/admin/todos` 与 `/m/todos`，只读取当前用户的消息/待办投影并统一解析目标页面。
+
 前端一次读取当前登录用户在当前环境的完整应用角色并集和 capability。应用可在 `perspectives` 中声明工作视角；视角只投影页面、行和字段的读取范围，不改变真实身份，也不收窄新增、编辑、删除、流程与自定义动作权限。标准 Data API 自动识别视角；只有绕过标准 Data API 的自定义 Nest 查询才需要通过 `@CurrentPerspective()` 显式实现同等读取投影。字段默认继承资源 read/create/update；`access` 数组为 all-of，`false` 为明确拒绝，无权字段在提交前从 payload 删除。
 
 ```bash

package/template/apps/server/package.json

@@ -15,7 +15,7 @@
     "@nestjs/common": "11.1.29",
     "@nestjs/core": "11.1.29",
     "@nestjs/platform-fastify": "11.1.29",
-    "openxiangda": "2.0.0-alpha.30",
+    "openxiangda": "2.0.0-alpha.33",
     "reflect-metadata": "0.2.2",
     "rxjs": "7.8.2"
   },

package/template/apps/web/e2e/data-api-live-fixture.tsx

@@ -35,7 +35,14 @@ export const liveDefinition: GeneratedResourceDefinition = {
   name: '字段协议记录',
   capabilities,
   surface: {
-    generated: true,
+    mutationOwner: 'native',
+    generated: {
+      list: true,
+      detail: true,
+      create: true,
+      update: true,
+      delete: true,
+    },
     fields: {
       text_short: {
         label: '标题',

package/template/apps/web/e2e/resource-experience-fixture.tsx

@@ -63,7 +63,14 @@ const fields: DataResourceSurface['fields'] = {
 };
 
 const surface: DataResourceSurface = {
-  generated: true,
+  mutationOwner: 'native',
+  generated: {
+    list: true,
+    detail: true,
+    create: true,
+    update: true,
+    delete: true,
+  },
   fields,
   list: {
     defaultPageSize: 20,
@@ -145,7 +152,6 @@ const adminContributions = defineAdminContributions(
       path: '/admin/operations/content',
       label: '内容业务操作',
       surface: 'admin',
-      navigation: 'menu',
       capability: 'app:openxiangda-application:operations:read',
       tabPersistence: 'session',
       keepAlive: 'none',
@@ -179,6 +185,179 @@ ReactDOM.createRoot(document.getElementById('root')!).render(
     <OpenXiangdaApplication
       appCode="openxiangda-application"
       appName="资源体验验收"
+      adminNavigation={[
+        {
+          code: 'resources',
+          label: '数据管理',
+          icon: 'database',
+          order: 0,
+          items: [
+            { pageCode: 'resource:resource-01:list', label: '内容栏目', order: 0 },
+            { pageCode: 'resource:resource-02:list', label: '内容文章', order: 1 },
+            { pageCode: 'resource:resource-03:list', label: '内容专题', order: 2 },
+            { pageCode: 'resource:resource-04:list', label: '会员档案', order: 3 },
+            { pageCode: 'resource:resource-05:list', label: '门户轮播', order: 4 },
+            { pageCode: 'resource:resource-06:list', label: '工会小组', order: 5 },
+            { pageCode: 'resource:resource-07:list', label: '场地预约', order: 6 },
+            {
+              pageCode: 'resource:resource-08:list',
+              label: '场地不可用时段',
+              order: 7,
+            },
+            { pageCode: 'resource:resource-09:list', label: '场地档案', order: 8 },
+            { pageCode: 'resource:resource-10:list', label: '通知公告', order: 9 },
+            { pageCode: 'resource:resource-11:list', label: '活动报名', order: 10 },
+            { pageCode: 'resource:resource-12:list', label: '资料下载', order: 11 },
+            { pageCode: 'operation:content-operations', order: 12 },
+          ],
+        },
+      ]}
+      adminPages={[
+        {
+          code: 'resource:resource-01:list',
+          kind: 'resource-list',
+          path: '/resource-01',
+          label: '资源 01',
+          navigationEligible: true,
+          capability: resourceDefinitions['resource-01'].capabilities.read,
+          resourceCode: 'resource-01',
+        },
+        {
+          code: 'resource:resource-01:detail',
+          kind: 'resource-detail',
+          path: '/resource-01/:id',
+          label: '资源 01 详情',
+          navigationEligible: false,
+          capability: resourceDefinitions['resource-01'].capabilities.read,
+          resourceCode: 'resource-01',
+        },
+        {
+          code: 'resource:resource-01:create',
+          kind: 'resource-create',
+          path: '/resource-01/new',
+          label: '新增资源 01',
+          navigationEligible: false,
+          capability: resourceDefinitions['resource-01'].capabilities.create,
+          resourceCode: 'resource-01',
+        },
+        {
+          code: 'resource:resource-01:update',
+          kind: 'resource-update',
+          path: '/resource-01/:id/edit',
+          label: '编辑资源 01',
+          navigationEligible: false,
+          capability: resourceDefinitions['resource-01'].capabilities.update,
+          resourceCode: 'resource-01',
+        },
+        {
+          code: 'resource:resource-02:list',
+          kind: 'resource-list',
+          path: '/resource-02',
+          label: '内容文章',
+          navigationEligible: true,
+          capability: resourceDefinitions['resource-02'].capabilities.read,
+          resourceCode: 'resource-02',
+        },
+        {
+          code: 'resource:resource-03:list',
+          kind: 'resource-list',
+          path: '/resource-03',
+          label: '内容专题',
+          navigationEligible: true,
+          capability: resourceDefinitions['resource-03'].capabilities.read,
+          resourceCode: 'resource-03',
+        },
+        {
+          code: 'resource:resource-04:list',
+          kind: 'resource-list',
+          path: '/resource-04',
+          label: '会员档案',
+          navigationEligible: true,
+          capability: resourceDefinitions['resource-04'].capabilities.read,
+          resourceCode: 'resource-04',
+        },
+        {
+          code: 'resource:resource-05:list',
+          kind: 'resource-list',
+          path: '/resource-05',
+          label: '门户轮播',
+          navigationEligible: true,
+          capability: resourceDefinitions['resource-05'].capabilities.read,
+          resourceCode: 'resource-05',
+        },
+        {
+          code: 'resource:resource-06:list',
+          kind: 'resource-list',
+          path: '/resource-06',
+          label: '工会小组',
+          navigationEligible: true,
+          capability: resourceDefinitions['resource-06'].capabilities.read,
+          resourceCode: 'resource-06',
+        },
+        {
+          code: 'resource:resource-07:list',
+          kind: 'resource-list',
+          path: '/resource-07',
+          label: '场地预约',
+          navigationEligible: true,
+          capability: resourceDefinitions['resource-07'].capabilities.read,
+          resourceCode: 'resource-07',
+        },
+        {
+          code: 'resource:resource-08:list',
+          kind: 'resource-list',
+          path: '/resource-08',
+          label: '场地不可用时段',
+          navigationEligible: true,
+          capability: resourceDefinitions['resource-08'].capabilities.read,
+          resourceCode: 'resource-08',
+        },
+        {
+          code: 'resource:resource-09:list',
+          kind: 'resource-list',
+          path: '/resource-09',
+          label: '场地档案',
+          navigationEligible: true,
+          capability: resourceDefinitions['resource-09'].capabilities.read,
+          resourceCode: 'resource-09',
+        },
+        {
+          code: 'resource:resource-10:list',
+          kind: 'resource-list',
+          path: '/resource-10',
+          label: '通知公告',
+          navigationEligible: true,
+          capability: resourceDefinitions['resource-10'].capabilities.read,
+          resourceCode: 'resource-10',
+        },
+        {
+          code: 'resource:resource-11:list',
+          kind: 'resource-list',
+          path: '/resource-11',
+          label: '活动报名',
+          navigationEligible: true,
+          capability: resourceDefinitions['resource-11'].capabilities.read,
+          resourceCode: 'resource-11',
+        },
+        {
+          code: 'resource:resource-12:list',
+          kind: 'resource-list',
+          path: '/resource-12',
+          label: '资料下载',
+          navigationEligible: true,
+          capability: resourceDefinitions['resource-12'].capabilities.read,
+          resourceCode: 'resource-12',
+        },
+        {
+          code: 'operation:content-operations',
+          kind: 'operation',
+          path: '/admin/operations/content',
+          label: '内容业务操作',
+          navigationEligible: true,
+          capability: 'app:openxiangda-application:operations:read',
+          routeCode: 'content-operations',
+        },
+      ]}
       contributions={adminContributions}
       resourceDefinitions={resourceDefinitions}
     />

package/template/apps/web/e2e/resources.spec.ts

@@ -327,16 +327,18 @@ test('updates the current user avatar through the platform-owned profile contrac
 
 test('preserves the left menu scroll position when switching resource pages', async ({ page }) => {
   await mockPlatform(page, true, runtimeBase, true);
+  await page.setViewportSize({ width: 1280, height: 400 });
   await page.goto('/resource-experience.e2e.html');
   const scroller = page.locator('.oxa-menu-scroll');
   await scroller.evaluate(node => {
-    const menu = node.querySelector('.oxa-menu') as HTMLElement | null;
-    if (menu) menu.style.minHeight = '1400px';
     node.scrollTop = 240;
     node.dispatchEvent(new Event('scroll'));
   });
   await expect.poll(() => scroller.evaluate(node => node.scrollTop)).toBe(240);
-  await page.locator('.oxa-sider').getByText('资料下载', { exact: true }).click();
+  await page
+    .locator('.oxa-sider')
+    .getByText('资料下载', { exact: true })
+    .evaluate(node => (node as HTMLElement).click());
   await expect(page).toHaveURL('/resource-12');
   await expect.poll(() => scroller.evaluate(node => node.scrollTop)).toBe(240);
 });

package/template/apps/web/e2e/workflow-experience-fixture.tsx

@@ -0,0 +1,144 @@
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import {
+  defineApplicationContributions,
+  defineWorkflowLaunchContributions,
+  OpenXiangdaApplication,
+  type AdminNavigationInput,
+  type AdminPagesInput,
+} from 'openxiangda/react';
+import { useParams, useSearchParams } from 'react-router-dom';
+import { appCode } from '../../../packages/contracts/src/generated.js';
+import 'openxiangda/react/styles.css';
+
+const workflowDefinitions = [
+  {
+    code: 'purchase-approval',
+    title: '采购审批',
+    launch: { mode: 'standalone' },
+  },
+] as const;
+
+const detailRoutes = {
+  desktop: {
+    code: 'purchase-detail',
+    path: '/admin/operations/purchases/:instanceId',
+    label: '采购审批详情',
+    surface: 'admin',
+    tabPersistence: 'none',
+    keepAlive: 'none',
+  },
+  mobile: {
+    code: 'purchase-detail-mobile',
+    path: '/m/purchases/:instanceId',
+    label: '移动采购审批详情',
+    surface: 'user',
+    tabPersistence: 'none',
+    keepAlive: 'none',
+  },
+} as const;
+
+function CustomWorkflowDetail() {
+  const { instanceId } = useParams();
+  const [search] = useSearchParams();
+  return (
+    <div data-testid="custom-workflow-detail">
+      自定义流程详情 {instanceId} / {search.get('taskId') || 'instance'}
+    </div>
+  );
+}
+
+const applicationContributions = defineApplicationContributions(detailRoutes, {
+  pages: {
+    desktop: CustomWorkflowDetail,
+    mobile: CustomWorkflowDetail,
+  },
+});
+
+const adminPages = [
+  {
+    code: 'application:todo-center',
+    kind: 'application-todo-center',
+    path: '/admin/todos',
+    label: '待办中心',
+    navigationEligible: true,
+  },
+  {
+    code: 'workflow:work-center',
+    kind: 'workflow-work-center',
+    path: '/admin/work-center',
+    label: '我的审批',
+    navigationEligible: true,
+  },
+  {
+    code: 'workflow:purchase-approval:launch',
+    kind: 'workflow-launch',
+    path: '/admin/workflows/purchase-approval/new',
+    label: '发起采购审批',
+    navigationEligible: true,
+    workflowCode: 'purchase-approval',
+  },
+  {
+    code: 'workflow:task',
+    kind: 'workflow-task',
+    path: '/admin/tasks/:taskId',
+    label: '审批任务',
+    navigationEligible: false,
+  },
+  {
+    code: 'workflow:instance',
+    kind: 'workflow-instance',
+    path: '/admin/workflows/:instanceId',
+    label: '流程详情',
+    navigationEligible: false,
+  },
+] as const satisfies AdminPagesInput;
+
+const adminNavigation = [
+  {
+    code: 'workflow-center',
+    label: '流程中心',
+    icon: 'workflow',
+    order: 0,
+    items: [
+      { pageCode: 'application:todo-center', label: '待办中心', order: 0 },
+      { pageCode: 'workflow:work-center', label: '我的审批', order: 1 },
+      {
+        pageCode: 'workflow:purchase-approval:launch',
+        label: '发起采购审批',
+        order: 2,
+      },
+    ],
+  },
+] as const satisfies AdminNavigationInput;
+
+const initialPath =
+  new URLSearchParams(window.location.search).get('initial') ||
+  '/admin/work-center';
+if (location.pathname.endsWith('/workflow-experience.e2e.html')) {
+  history.replaceState({}, '', initialPath);
+}
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <OpenXiangdaApplication
+      appCode={appCode}
+      appName="流程体验验收"
+      adminNavigation={adminNavigation}
+      adminPages={adminPages}
+      contributions={applicationContributions}
+      resourceDefinitions={{}}
+      workflows={defineWorkflowLaunchContributions(workflowDefinitions, {
+        'purchase-approval': async () => ({
+          businessKey: 'PO-2026-0825',
+          dataRef: {
+            resourceCode: 'purchase-orders',
+            recordId: 'purchase-1',
+            dataRevision: '8',
+          },
+          facts: { amount: 28600, applicant: '张三' },
+        }),
+      })}
+    />
+  </React.StrictMode>
+);

package/template/apps/web/e2e/workflow.spec.ts

@@ -1,14 +1,27 @@
 import { expect, test, type Page } from '@playwright/test';
 import { appCode } from '../../../packages/contracts/src/generated.js';
 
-const runtimeBase = `/view/${appCode}`;
 const taskId = '11111111-1111-4111-8111-111111111111';
 const instanceId = '22222222-2222-4222-8222-222222222222';
 function envelope(data: unknown, code = 200) {
   return { code, message: code === 200 ? 'success' : 'forbidden', data };
 }
 
-function task(completed = false) {
+function detailNavigation(custom = false) {
+  return custom
+    ? {
+        custom: true,
+        desktopPath: `/admin/operations/purchases/${instanceId}?taskId=${taskId}`,
+        mobilePath: `/m/purchases/${instanceId}?taskId=${taskId}`,
+      }
+    : {
+        custom: false,
+        desktopPath: `/admin/tasks/${taskId}`,
+        mobilePath: `/m/tasks/${taskId}`,
+      };
+}
+
+function task(completed = false, customDetail = false) {
   return {
     schemaVersion: 'openxiangda.workflow-task/v2',
     engineVersion: '2.0',
@@ -30,16 +43,18 @@ function task(completed = false) {
     dataRef: { resourceCode: 'purchase-orders', recordId: 'purchase-1' },
     createdAt: '2026-08-25T01:00:00.000Z',
     updatedAt: '2026-08-25T01:10:00.000Z',
+    detailNavigation: detailNavigation(customDetail),
   };
 }
 
-function surface(completed = false) {
+function surface(completed = false, customDetail = false) {
   return {
     schemaVersion: 'openxiangda.workflow-surface/v2',
     protocolVersion: 'workflow_surface_v2',
     surfaceRevision: completed ? 'revision-2' : 'revision-1',
     engineVersion: '2.0',
     instanceSequence: completed ? 4 : 3,
+    detailNavigation: detailNavigation(customDetail),
     navigationTarget: {
       kind: 'resource_record',
       appCode,
@@ -73,7 +88,7 @@ function surface(completed = false) {
       startedAt: '2026-08-25T01:00:00.000Z',
       completedAt: completed ? '2026-08-25T01:12:00.000Z' : null,
     },
-    task: completed ? null : task(false),
+    task: completed ? null : task(false, customDetail),
     presentation: {
       status: { label: completed ? '已同意' : '待审批', tone: 'warning' },
       layout: 'approval_detail',
@@ -118,7 +133,7 @@ function surface(completed = false) {
             },
             refresh: ['surface', 'timeline', 'work_center'],
           },
-          ...['reject', 'return', 'transfer', 'add_assignee'].map((key) => ({
+          ...['reject', 'return', 'transfer', 'add_assignee'].map(key => ({
             key,
             kind: 'workflow_command',
             label: {
@@ -185,20 +200,87 @@ function timeline(completed = false) {
   };
 }
 
-async function mockWorkflow(page: Page, options: { forbidden?: boolean } = {}) {
+function launchSurface() {
+  return {
+    schemaVersion: 'openxiangda.workflow-launch-surface/v2',
+    protocolVersion: 'workflow_launch_surface_v2',
+    surfaceRevision: 'launch-revision-1',
+    engineVersion: '2.0',
+    appCode,
+    environmentKey: 'preproduction',
+    environmentId: 'preproduction-id',
+    workflowCode: 'purchase-approval',
+    title: '采购审批',
+    launchMode: 'standalone',
+    inputSchema: { type: 'object', properties: {} },
+    head: {
+      workflowRevision: 4,
+      definitionVersion: 1,
+      bindingVersion: 1,
+      nativeRevision: 3,
+      contractRevisionId: 'contract-revision-1',
+    },
+    paths: {
+      desktop: '/admin/workflows/purchase-approval/new',
+      mobile: '/m/workflows/purchase-approval/start',
+    },
+    prepare: {
+      method: 'POST',
+      href: '/workflow/definitions/purchase-approval/prepare-start',
+    },
+    start: {
+      method: 'POST',
+      href: '/workflow/instances',
+      idempotencyRequired: true,
+    },
+  };
+}
+
+function todoPage() {
+  return {
+    schemaVersion: 'openxiangda.application-todo-center/v2',
+    appCode,
+    environmentKey: 'preproduction',
+    view: 'pending',
+    counts: { pending: 1, informational: 2, completed: 3, unread: 1 },
+    items: [
+      {
+        messageId: '33333333-3333-4333-8333-333333333333',
+        recipientId: '44444444-4444-4444-8444-444444444444',
+        state: 'action_required',
+        interactionState: 'unread',
+        title: '设备采购申请待审批',
+        summary: '张三提交了一笔办公设备采购申请',
+        fields: [
+          { code: 'amount', label: '申请金额', value: '¥28,600' },
+          { code: 'department', label: '申请部门', value: '理学院' },
+        ],
+        actions: [{ code: 'open', label: '去处理' }],
+        sourceKind: 'PLATFORM_EVENT',
+        sourceLabel: '流程中心',
+        occurredAt: '2026-08-28T01:00:00.000Z',
+        updatedAt: '2026-08-28T01:01:00.000Z',
+        navigation: {
+          desktopPath: `/admin/operations/purchases/${instanceId}?taskId=${taskId}`,
+          mobilePath: `/m/purchases/${instanceId}?taskId=${taskId}`,
+          external: false,
+          navigationUnavailable: false,
+        },
+      },
+    ],
+    total: 1,
+    limit: 12,
+    offset: 0,
+    nextOffset: null,
+  };
+}
+
+async function mockWorkflow(
+  page: Page,
+  options: { forbidden?: boolean; customDetail?: boolean } = {}
+) {
   let completed = false;
-  await page.route(`**${runtimeBase}/**`, async (route) => {
-    if (route.request().resourceType() !== 'document') return route.continue();
-    const response = await route.fetch();
-    const body = (await response.text()).replace(
-      '<head>',
-      `<head><meta name="openxiangda-runtime-base" content="${runtimeBase}/" />` +
-        `<meta name="openxiangda-app-code" content="${appCode}" />` +
-        '<meta name="openxiangda-environment" content="preproduction" />',
-    );
-    await route.fulfill({ response, body });
-  });
-  await page.route('**/service/**', async (route) => {
+  await page.route('**/service/**', async route => {
     const url = new URL(route.request().url());
     const path = url.pathname;
     if (path.endsWith('/native/authz/current')) {
@@ -241,7 +323,7 @@ async function mockWorkflow(page: Page, options: { forbidden?: boolean } = {}) {
               identityScope:
                 'user-union:preproduction-id:acceptance-user:authz-1',
             },
-          }),
+          })
         ),
       });
     }
@@ -258,6 +340,71 @@ async function mockWorkflow(page: Page, options: { forbidden?: boolean } = {}) {
         body: JSON.stringify(envelope(null, 403)),
       });
     }
+    if (path.endsWith('/todos') && route.request().method() === 'GET') {
+      return route.fulfill({
+        contentType: 'application/json',
+        body: JSON.stringify(envelope(todoPage())),
+      });
+    }
+    if (path.includes('/todos/') && path.endsWith('/interactions')) {
+      return route.fulfill({
+        contentType: 'application/json',
+        body: JSON.stringify(
+          envelope({
+            accepted: true,
+            duplicate: false,
+            interactionState: 'clicked',
+          })
+        ),
+      });
+    }
+    if (
+      path.endsWith(
+        '/workflow/definitions/purchase-approval/launch-surface'
+      )
+    ) {
+      return route.fulfill({
+        contentType: 'application/json',
+        body: JSON.stringify(envelope(launchSurface())),
+      });
+    }
+    if (
+      path.endsWith(
+        '/workflow/definitions/purchase-approval/prepare-start'
+      )
+    ) {
+      return route.fulfill({
+        contentType: 'application/json',
+        body: JSON.stringify(
+          envelope({
+            schemaVersion: 'openxiangda.workflow-preparation/v2',
+            preparationId: 'preparation-1',
+            status: 'ready',
+            requirements: [],
+            preparationToken: 'preparation-token-1',
+            preview: { nodes: [] },
+            expiresAt: '2026-08-28T02:00:00.000Z',
+            definitionVersion: 1,
+            bindingVersion: 1,
+            inputHash: 'input-hash-1',
+          })
+        ),
+      });
+    }
+    if (
+      path.endsWith('/workflow/instances') &&
+      route.request().method() === 'POST'
+    ) {
+      return route.fulfill({
+        contentType: 'application/json',
+        body: JSON.stringify(
+          envelope({
+            ...surface(false, options.customDetail).instance,
+            id: instanceId,
+          })
+        ),
+      });
+    }
     if (path.endsWith('/workflow/work-center/items')) {
       return route.fulfill({
         contentType: 'application/json',
@@ -270,15 +417,25 @@ async function mockWorkflow(page: Page, options: { forbidden?: boolean } = {}) {
             total: 1,
             limit: 20,
             offset: 0,
-            items: [task(completed)],
-          }),
+            items: [task(completed, options.customDetail)],
+          })
         ),
       });
     }
     if (path.endsWith(`/workflow/tasks/${taskId}/surface`)) {
       return route.fulfill({
         contentType: 'application/json',
-        body: JSON.stringify(envelope(surface(completed))),
+        body: JSON.stringify(
+          envelope(surface(completed, options.customDetail))
+        ),
+      });
+    }
+    if (path.endsWith(`/workflow/instances/${instanceId}/surface`)) {
+      return route.fulfill({
+        contentType: 'application/json',
+        body: JSON.stringify(
+          envelope(surface(completed, options.customDetail))
+        ),
       });
     }
     if (path.endsWith(`/workflow/instances/${instanceId}/timeline`)) {
@@ -306,18 +463,93 @@ test('renders a paged desktop work center from the current-user role union', asy
   page,
 }) => {
   await mockWorkflow(page);
-  await page.goto(`${runtimeBase}/admin/work-center`);
+  await page.goto('/workflow-experience.e2e.html?initial=/admin/work-center');
   await expect(page.getByRole('heading', { name: '审批工作台' })).toBeVisible();
   await expect(page.getByRole('link', { name: '采购申请审批' })).toBeVisible();
   await expect(page.getByText('PO-2026-0825')).toBeVisible();
 });
 
+test('renders the generic desktop and mobile application todo center without a second router', async ({
+  page,
+}) => {
+  await mockWorkflow(page);
+  await page.goto('/workflow-experience.e2e.html?initial=/admin/todos');
+  await expect(page.getByRole('heading', { name: '待办中心' })).toBeVisible();
+  await expect(page.getByText('设备采购申请待审批').first()).toBeVisible();
+  await expect(page.getByText('¥28,600').first()).toBeVisible();
+
+  await page.setViewportSize({ width: 390, height: 844 });
+  await page.goto('/workflow-experience.e2e.html?initial=/m/todos');
+  await expect(page.locator('.oxa-todo-center-mobile')).toBeVisible();
+  await page.getByRole('button', { name: '去处理' }).click();
+  await expect(page.getByTestId('custom-workflow-detail')).toContainText(
+    `${instanceId} / ${taskId}`
+  );
+});
+
+test('launches the same workflow from the canonical mobile Surface and follows custom detail routing', async ({
+  page,
+}) => {
+  await mockWorkflow(page, { customDetail: true });
+  await page.setViewportSize({ width: 390, height: 844 });
+  await page.goto(
+    '/workflow-experience.e2e.html?initial=/m/workflows/purchase-approval/start'
+  );
+  await expect(page.locator('.oxa-workflow-submission-mobile')).toBeVisible();
+  await expect(page.getByRole('heading', { name: '采购审批' })).toBeVisible();
+  await page.getByRole('button', { name: '保存业务数据并预检' }).click();
+  await expect(page.getByRole('button', { name: '提交审批' })).toBeVisible();
+  await page.getByRole('button', { name: '提交审批' }).click();
+  await expect(page.getByTestId('custom-workflow-detail')).toContainText(
+    `${instanceId} / ${taskId}`
+  );
+  await expect(page).toHaveURL(
+    new RegExp(`/m/purchases/${instanceId}\\?taskId=${taskId}$`)
+  );
+});
+
+test('routes desktop and mobile work-center entries to the declared custom detail pages', async ({
+  page,
+}) => {
+  await mockWorkflow(page, { customDetail: true });
+  await page.goto('/workflow-experience.e2e.html?initial=/admin/work-center');
+  await page.getByRole('link', { name: '采购申请审批' }).click();
+  await expect(page.getByTestId('custom-workflow-detail')).toContainText(
+    `${instanceId} / ${taskId}`
+  );
+  await expect(page).toHaveURL(
+    new RegExp(`/admin/operations/purchases/${instanceId}\\?taskId=${taskId}$`)
+  );
+
+  await page.setViewportSize({ width: 390, height: 844 });
+  await page.goto('/workflow-experience.e2e.html?initial=/m/work-center');
+  await page.getByText('采购申请审批').click();
+  await expect(page.getByTestId('custom-workflow-detail')).toContainText(
+    `${instanceId} / ${taskId}`
+  );
+  await expect(page).toHaveURL(
+    new RegExp(`/m/purchases/${instanceId}\\?taskId=${taskId}$`)
+  );
+});
+
+test('redirects a direct standard task URL to the declared custom detail page', async ({
+  page,
+}) => {
+  await mockWorkflow(page, { customDetail: true });
+  await page.goto(
+    `/workflow-experience.e2e.html?initial=/admin/tasks/${taskId}`
+  );
+  await expect(page.getByTestId('custom-workflow-detail')).toContainText(
+    `${instanceId} / ${taskId}`
+  );
+});
+
 test('renders the independent mobile task and executes only a Surface operation', async ({
   page,
 }) => {
   await mockWorkflow(page);
   await page.setViewportSize({ width: 390, height: 844 });
-  await page.goto(`${runtimeBase}/m/tasks/${taskId}`);
+  await page.goto(`/workflow-experience.e2e.html?initial=/m/tasks/${taskId}`);
   await expect(page.locator('.oxa-workflow-mobile-page')).toBeVisible();
   await expect(page.getByText('¥28,600')).toBeVisible();
   await expect(page.getByText('财务负责人').first()).toBeVisible();
@@ -334,7 +566,7 @@ test('shows an explicit authorization error instead of an empty work center', as
 }) => {
   test.setTimeout(45_000);
   await mockWorkflow(page, { forbidden: true });
-  await page.goto(`${runtimeBase}/admin/work-center`, {
+  await page.goto('/workflow-experience.e2e.html?initial=/admin/work-center', {
     waitUntil: 'domcontentloaded',
   });
   await expect(page.getByRole('alert')).toContainText('HTTP_403: forbidden', {

package/template/apps/web/package.json

@@ -14,7 +14,7 @@
     "@ant-design/icons": "6.2.3",
     "@refinedev/core": "5.0.12",
     "antd": "6.4.3",
-    "openxiangda": "2.0.0-alpha.30",
+    "openxiangda": "2.0.0-alpha.33",
     "react": "19.2.8",
     "react-dom": "19.2.8",
     "react-router-dom": "7.8.2"

package/template/apps/web/src/main.tsx

@@ -1,7 +1,8 @@
 import React from 'react';
 import ReactDOM from 'react-dom/client';
 import {
-  defineAdminContributions,
+  defineApplicationContributions,
+  defineWorkflowLaunchContributions,
   OpenXiangdaApplication,
 } from 'openxiangda/react';
 import {
@@ -9,24 +10,32 @@ import {
   appName,
   appPerspectives,
   appRoutes,
+  adminNavigation,
+  adminPages,
   resourceDefinitions,
-  workflowCodes,
+  workflowDefinitions,
 } from '../../../packages/contracts/src/generated.js';
 import 'openxiangda/react/styles.css';
 
-const adminContributions = defineAdminContributions(appRoutes, {
+const applicationContributions = defineApplicationContributions(appRoutes, {
   pages: {},
 });
+const workflowContributions = defineWorkflowLaunchContributions(
+  workflowDefinitions,
+  {},
+);
 
 ReactDOM.createRoot(document.getElementById('root')!).render(
   <React.StrictMode>
     <OpenXiangdaApplication
       appCode={appCode}
       appName={appName}
-      contributions={adminContributions}
+      adminNavigation={adminNavigation}
+      adminPages={adminPages}
+      contributions={applicationContributions}
       perspectives={appPerspectives}
       resourceDefinitions={resourceDefinitions}
-      workflows={workflowCodes}
+      workflows={workflowContributions}
     />
   </React.StrictMode>,
 );

package/template/apps/web/test/contracts.test.ts

@@ -28,8 +28,8 @@ test('clean template contains only application declarations and one React entry'
   );
   assert.match(config, /data:\s*\{\s*resources:/);
   assert.match(source, /OpenXiangdaApplication/);
-  assert.match(source, /defineAdminContributions\(appRoutes/);
-  assert.match(source, /contributions=\{adminContributions\}/);
+  assert.match(source, /defineApplicationContributions\(appRoutes/);
+  assert.match(source, /contributions=\{applicationContributions\}/);
   assert.match(source, /from 'openxiangda\/react'/);
   assert.match(source, /openxiangda\/react\/styles\.css/);
   const legacyMarkers = [
@@ -96,6 +96,28 @@ test('published E2E harnesses do not write evidence into the platform source rep
   assert.doesNotMatch(workflowSource, /docs\/architecture|evidenceDirectory/);
 });
 
+test('E2E experience fixtures explicitly own every tested admin route', () => {
+  const resourceFixture = readFileSync(
+    new URL('../e2e/resource-experience-fixture.tsx', import.meta.url),
+    'utf8'
+  );
+  for (let index = 1; index <= 12; index += 1) {
+    const code = `resource-${String(index).padStart(2, '0')}`;
+    const pageCode = `resource:${code}:list`;
+    assert.match(resourceFixture, new RegExp(`pageCode: '${pageCode}'`));
+    assert.match(resourceFixture, new RegExp(`code: '${pageCode}'`));
+  }
+
+  const workflowFixture = readFileSync(
+    new URL('../e2e/workflow-experience-fixture.tsx', import.meta.url),
+    'utf8'
+  );
+  assert.match(workflowFixture, /code: 'workflow:work-center'/);
+  assert.match(workflowFixture, /code: 'workflow:task'/);
+  assert.match(workflowFixture, /code: 'workflow:instance'/);
+  assert.match(workflowFixture, /pageCode: 'workflow:work-center'/);
+});
+
 test('browser acceptance serializes the prewarmed Vite HTML entrypoints', () => {
   const viteConfig = readFileSync(new URL('../vite.config.ts', import.meta.url), 'utf8');
   const playwrightConfig = readFileSync(
@@ -109,6 +131,7 @@ test('browser acceptance serializes the prewarmed Vite HTML entrypoints', () =>
     'data-api-live.e2e.html',
     'field-protocol.e2e.html',
     'resource-experience.e2e.html',
+    'workflow-experience.e2e.html',
   ]);
   for (const entry of htmlEntries) {
     assert.ok(viteConfig.includes(`'${entry}'`), `missing optimizeDeps entry ${entry}`);

package/template/apps/web/vite.config.ts

@@ -14,6 +14,7 @@ export default defineConfig({
       'data-api-live.e2e.html',
       'field-protocol.e2e.html',
       'resource-experience.e2e.html',
+      'workflow-experience.e2e.html',
     ],
   },
   server: {

package/template/apps/web/workflow-experience.e2e.html

@@ -0,0 +1,15 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="openxiangda-runtime-base" content="/" />
+    <meta name="openxiangda-app-code" content="openxiangda-application" />
+    <meta name="openxiangda-environment" content="preproduction" />
+    <title>Workflow experience acceptance</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/e2e/workflow-experience-fixture.tsx"></script>
+  </body>
+</html>

package/template/openxiangda.config.ts

@@ -1,10 +1,14 @@
-import { defineOpenXiangdaApp } from 'openxiangda/config';
+import { defineAdminNavigation, defineOpenXiangdaApp } from 'openxiangda/config';
 
 /** Clean application scaffold: declare resources and fields, then generate CRUD. */
 export default defineOpenXiangdaApp({
   schemaVersion: 3,
   app: { code: 'openxiangda-application', name: 'OpenXiangda 应用' },
-  frontend: { root: 'apps/web', routes: [] },
+  frontend: {
+    root: 'apps/web',
+    routes: [],
+    admin: { navigation: defineAdminNavigation([]) },
+  },
   backend: {
     root: 'apps/server',
     runtime: 'node',

package/template/package.json

@@ -22,7 +22,7 @@
     "build": "pnpm --recursive build"
   },
   "devDependencies": {
-    "openxiangda": "2.0.0-alpha.30",
+    "openxiangda": "2.0.0-alpha.33",
     "typescript": "5.9.3"
   }
 }

package/template/packages/contracts/src/generated.ts

@@ -17,6 +17,8 @@ export const capabilities = [
 ] as const;
 export const appOperations = {} as const;
 export const appRoutes = {} as const;
+export const adminPages = [] as const;
+export const adminNavigation = [] as const;
 export const eventTypes = [] as const;
 export const eventSubscriptionCodes = [] as const;
 export const eventHandlerManifest = {
@@ -27,6 +29,7 @@ export const eventHandlerManifest = {
 export const eventHandlers = {} as const;
 export const eventSchemas = [] as const;
 export const workflowCodes = [] as const;
+export const workflowDefinitions = [] as const;
 export const notificationTemplateCodes = {
   applicationInformational: "application.informational.standard",
 } as const;
@@ -35,6 +38,8 @@ export type ResourceCode = (typeof resourceCodes)[number];
 export type Capability = (typeof capabilities)[number];
 export type AppOperation = (typeof appOperations)[keyof typeof appOperations];
 export type AppRoute = (typeof appRoutes)[keyof typeof appRoutes];
+export type AdminPage = (typeof adminPages)[number];
+export type AdminNavigationGroup = (typeof adminNavigation)[number];
 export type AppPerspective = (typeof appPerspectives)[number];
 export type EventType = (typeof eventTypes)[number];
 export type EventSubscriptionCode = (typeof eventSubscriptionCodes)[number];