openxiangda-cli 2.0.0-alpha.163 → 2.0.0-alpha.165

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openxiangda-cli",
-  "version": "2.0.0-alpha.163",
+  "version": "2.0.0-alpha.165",
   "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.82",
-    "openxiangda-devkit-core": "2.0.0-alpha.105",
-    "openxiangda-mcp": "2.0.0-alpha.105",
-    "openxiangda-skill-kit": "2.0.0-alpha.129"
+    "openxiangda-contracts": "2.0.0-alpha.83",
+    "openxiangda-devkit-core": "2.0.0-alpha.106",
+    "openxiangda-mcp": "2.0.0-alpha.106",
+    "openxiangda-skill-kit": "2.0.0-alpha.131"
   },
   "devDependencies": {
     "tsx": "4.23.12",

package/template/AGENTS.md

@@ -24,6 +24,7 @@
   admin shell, and do not make user-end utilities depend on `--oxa-antd-*`.
 - 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.
 - 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`.

package/template/README.md

@@ -48,6 +48,14 @@ renderer 只使用 `ApplicationLoginSurfaceProps` 回调，不能验证密码、
 OAuth callback 或创建第二个 Router/身份状态。`platformAuthManifest` 单独记录登录面 QA，
 不会改变用户路由覆盖数。
 
+如需统一品牌化普通用户页面，在应用入口给
+`defineApplicationContributions` 增加完整的 `standardUserSurfaces`：必须同时提供
+`frame.desktop/mobile` 与 `applicationTodoCenter.desktop/mobile`。外框只使用
+`StandardUserPageFrameProps` 的页面类型、安全路由元数据、`children` 和平台返回回调；
+待办 renderer 只使用 `StandardApplicationTodoCenterProps` 的当前用户 items、加载/错误、
+查询、刷新、增量加载、交互和跳转回调。省略该属性继续使用平台默认页面。应用不得接管
+`/todos`、`/m/todos`、Workflow 路由、`RuntimeBoundary`、Token 或 Notification Hub API。
+
 生成式资源后台路径固定为 `/admin/resources/<resourceCode>...`，移动后台面为
 `/m/admin/resources/<resourceCode>...`；普通根路径和 `/m/...` 产品路径可由显式
 `user` route 使用。生成页内部跳转来自编译后的 `adminPages`，不要手写旧根路径、别名或

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.86",
+    "openxiangda": "2.0.0-alpha.89",
     "reflect-metadata": "0.2.2",
     "rxjs": "7.8.2"
   },

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

@@ -5,11 +5,17 @@ import {
   OpenXiangdaApplication,
   type AdminNavigationInput,
   type AdminPagesInput,
+  type StandardApplicationTodoCenterProps,
+  type StandardUserPageFrameProps,
+  type StandardUserSurfaceContributions,
 } from 'openxiangda/react';
 import { useParams, useSearchParams } from 'react-router-dom';
 import { appCode } from '../../../packages/contracts/src/generated.js';
 import 'openxiangda/react/styles.css';
 
+const fixtureParams = new URLSearchParams(window.location.search);
+const standardSurfaceMode = fixtureParams.get('surfaces');
+
 const workflowDefinitions = [
   {
     code: 'purchase-approval',
@@ -83,11 +89,97 @@ function CustomWorkflowDetail() {
   );
 }
 
+function StandardFrame({
+  back,
+  canGoBack,
+  children,
+  device,
+  pageKind,
+  route,
+}: StandardUserPageFrameProps) {
+  return (
+    <section
+      data-can-go-back={String(canGoBack)}
+      data-page-kind={pageKind}
+      data-route-code={route.routeCode}
+      data-route-params={JSON.stringify(route.params)}
+      data-testid={`standard-frame-${device}`}
+    >
+      <button onClick={back} type="button">返回</button>
+      {children}
+    </section>
+  );
+}
+
+function CustomTodo({
+  device,
+  error,
+  hasMore,
+  items,
+  loadMore,
+  loading,
+  loadingMore,
+  openItem,
+  query,
+  refresh,
+  setQuery,
+}: StandardApplicationTodoCenterProps) {
+  return (
+    <main data-testid={`custom-todo-${device}`}>
+      <h1>{device === 'mobile' ? '移动应用待办' : '桌面应用待办'}</h1>
+      <output data-testid="custom-todo-query">
+        {query.view}/{String(query.unread)}/{query.keyword || 'all'}
+      </output>
+      {error ? <div role="alert">{error}</div> : null}
+      <button onClick={() => void refresh()} type="button">刷新待办</button>
+      <button
+        onClick={() => setQuery({ unread: !query.unread })}
+        type="button"
+      >
+        切换未读
+      </button>
+      <ul aria-busy={loading || loadingMore}>
+        {items.map(item => (
+          <li key={item.messageId}>
+            <button onClick={() => void openItem(item)} type="button">
+              {item.title}
+            </button>
+          </li>
+        ))}
+      </ul>
+      <button
+        disabled={!hasMore || loadingMore}
+        onClick={() => void loadMore()}
+        type="button"
+      >
+        加载更多
+      </button>
+    </main>
+  );
+}
+
+function BrokenTodo(_props: StandardApplicationTodoCenterProps) {
+  throw new Error('fixture standard user renderer failure');
+}
+
+const standardUserSurfaces: StandardUserSurfaceContributions | undefined =
+  standardSurfaceMode
+    ? {
+        frame: { desktop: StandardFrame, mobile: StandardFrame },
+        applicationTodoCenter: {
+          desktop:
+            standardSurfaceMode === 'error' ? BrokenTodo : CustomTodo,
+          mobile: standardSurfaceMode === 'error' ? BrokenTodo : CustomTodo,
+        },
+      }
+    : undefined;
+
 const applicationContributions = defineApplicationContributions(detailRoutes, {
   pages: {
     desktop: CustomWorkflowDetail,
     mobile: CustomWorkflowDetail,
   },
+  ...(standardUserSurfaces ? { standardUserSurfaces } : {}),
 });
 
 const adminPages = [] as const satisfies AdminPagesInput;
@@ -203,7 +295,6 @@ const routeManifest = {
 
 const adminNavigation = [] as const satisfies AdminNavigationInput;
 
-const fixtureParams = new URLSearchParams(window.location.search);
 const initialPath = fixtureParams.get('initial') || '/work-center';
 const runtimeBase = fixtureParams.get('base')?.trim();
 if (runtimeBase) {

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

@@ -24,11 +24,12 @@ function detailNavigation(custom = false) {
 
 function workflowFixtureUrl(
   initialPath: string,
-  options: { base?: string; state?: string } = {},
+  options: { base?: string; state?: string; surfaces?: 'custom' | 'error' } = {},
 ) {
   const params = new URLSearchParams({ initial: initialPath });
   if (options.base) params.set('base', options.base);
   if (options.state) params.set('state', options.state);
+  if (options.surfaces) params.set('surfaces', options.surfaces);
   return `/workflow-experience.e2e.html?${params.toString()}`;
 }
 
@@ -525,42 +526,47 @@ function processCommandSurface() {
   };
 }
 
-function todoPage() {
+function todoPage(offset = 0) {
+  const first = {
+    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,
+    },
+  };
+  const second = {
+    ...first,
+    messageId: '77777777-7777-4777-8777-777777777777',
+    title: '采购结果通知',
+    interactionState: 'read',
+  };
   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,
+    items: [offset > 0 ? second : first],
+    total: 2,
     limit: 12,
-    offset: 0,
-    nextOffset: null,
+    offset,
+    nextOffset: offset > 0 ? null : 1,
   };
 }
 
@@ -642,7 +648,9 @@ async function mockWorkflow(
     if (path.endsWith('/todos') && route.request().method() === 'GET') {
       return route.fulfill({
         contentType: 'application/json',
-        body: JSON.stringify(envelope(todoPage())),
+        body: JSON.stringify(
+          envelope(todoPage(Number(url.searchParams.get('offset') || 0))),
+        ),
       });
     }
     if (path.includes('/todos/') && path.endsWith('/interactions')) {
@@ -806,6 +814,7 @@ test('renders the generic desktop and mobile application todo center without a s
   await mockWorkflow(page);
   await page.goto('/workflow-experience.e2e.html?initial=/todos');
   await expect(page.getByRole('heading', { name: '待办中心' })).toBeVisible();
+  await expect(page.getByTestId('standard-frame-desktop')).toHaveCount(0);
   await expect(page.locator('.oxa-todo-table')).toBeVisible();
   await expect(page.locator('.oxa-todo-preview-card')).toHaveCount(0);
   await expect(page.getByText('设备采购申请待审批').first()).toBeVisible();
@@ -838,6 +847,104 @@ test('renders the generic desktop and mobile application todo center without a s
   );
 });
 
+test('selects paired application todo renderers while the platform owns data, paging and navigation', async ({
+  page,
+}) => {
+  await mockWorkflow(page);
+  await page.goto(
+    workflowFixtureUrl('/todos', { surfaces: 'custom' }),
+  );
+  const desktopFrame = page.getByTestId('standard-frame-desktop');
+  await expect(desktopFrame).toHaveAttribute(
+    'data-page-kind',
+    'application-todo-center',
+  );
+  await expect(desktopFrame).toHaveAttribute(
+    'data-route-code',
+    'application.todo-center.desktop',
+  );
+  await expect(page.getByTestId('custom-todo-desktop')).toBeVisible();
+  await expect(page.getByText('设备采购申请待审批')).toBeVisible();
+
+  const nextPage = page.waitForRequest(request => {
+    const url = new URL(request.url());
+    return url.pathname.endsWith('/todos') && url.searchParams.get('offset') === '1';
+  });
+  await page.getByRole('button', { name: '加载更多' }).click();
+  await nextPage;
+  await expect(page.getByText('采购结果通知')).toBeVisible();
+
+  const unreadRequest = page.waitForRequest(request => {
+    const url = new URL(request.url());
+    return url.pathname.endsWith('/todos') && url.searchParams.get('unread') === 'true';
+  });
+  await page.getByRole('button', { name: '切换未读' }).click();
+  await unreadRequest;
+  await expect(page.getByTestId('custom-todo-query')).toContainText(
+    'pending/true/all',
+  );
+
+  await page.getByRole('button', { name: '设备采购申请待审批' }).click();
+  await expect(page).toHaveURL(
+    new RegExp(`/admin/operations/purchases/${instanceId}\\?taskId=${taskId}`),
+  );
+
+  await page.setViewportSize({ width: 390, height: 844 });
+  await page.goto(
+    workflowFixtureUrl('/m/todos', { surfaces: 'custom' }),
+  );
+  await expect(page.getByTestId('custom-todo-mobile')).toBeVisible();
+  await expect(page.getByTestId('standard-frame-mobile')).toHaveAttribute(
+    'data-route-code',
+    'application.todo-center.mobile',
+  );
+});
+
+test('frames platform-owned workflow launch, task and instance routes with safe metadata', async ({
+  page,
+}) => {
+  await mockWorkflow(page);
+  for (const [path, kind, routeCode, params] of [
+    [
+      '/workflows/purchase-approval/start',
+      'workflow-launch',
+      'workflow.purchase-approval.launch.desktop',
+      'purchase-approval',
+    ],
+    [
+      `/tasks/${taskId}`,
+      'workflow-task',
+      'workflow.task.desktop',
+      taskId,
+    ],
+    [
+      `/workflows/${instanceId}`,
+      'workflow-instance',
+      'workflow.instance.desktop',
+      instanceId,
+    ],
+  ] as const) {
+    await page.goto(workflowFixtureUrl(path, { surfaces: 'custom' }));
+    const frame = page.getByTestId('standard-frame-desktop');
+    await expect(frame).toHaveAttribute('data-page-kind', kind);
+    await expect(frame).toHaveAttribute('data-route-code', routeCode);
+    await expect(frame).toHaveAttribute(
+      'data-route-params',
+      new RegExp(params),
+    );
+  }
+});
+
+test('contains an application standard renderer failure inside the platform boundary', async ({
+  page,
+}) => {
+  await mockWorkflow(page);
+  await page.goto(workflowFixtureUrl('/todos', { surfaces: 'error' }));
+  await expect(page.getByText('页面显示失败')).toBeVisible();
+  await expect(page.getByText(/平台登录态和业务数据未受影响/)).toBeVisible();
+  await expect(page.getByRole('button', { name: '重新加载页面' })).toBeVisible();
+});
+
 test('launches the same workflow from the canonical mobile Surface and follows custom detail routing', async ({
   page,
 }) => {

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.86",
+    "openxiangda": "2.0.0-alpha.89",
     "react": "19.2.8",
     "react-dom": "19.2.8",
     "react-router-dom": "7.8.2"

package/template/apps/web/test/standard-user-surfaces.typecheck.tsx

@@ -0,0 +1,27 @@
+import {
+  defineApplicationContributions,
+  type StandardApplicationTodoCenterProps,
+  type StandardUserPageFrameProps,
+  type StandardUserSurfaceContributions,
+} from 'openxiangda/react';
+
+function Frame({ children }: StandardUserPageFrameProps) {
+  return <>{children}</>;
+}
+
+function Todo({ items }: StandardApplicationTodoCenterProps) {
+  return <>{items.length}</>;
+}
+
+const standardUserSurfaces = {
+  frame: { desktop: Frame, mobile: Frame },
+  applicationTodoCenter: { desktop: Todo, mobile: Todo },
+} satisfies StandardUserSurfaceContributions;
+
+const contributions = defineApplicationContributions({}, {
+  pages: {},
+  standardUserSurfaces,
+});
+
+const exportedFrame = contributions.standardUserSurfaces?.frame.desktop;
+void exportedFrame;

package/template/package.json

@@ -23,7 +23,7 @@
     "build": "pnpm --recursive build"
   },
   "devDependencies": {
-    "openxiangda": "2.0.0-alpha.86",
+    "openxiangda": "2.0.0-alpha.89",
     "typescript": "5.9.3"
   }
 }