openxiangda-cli 2.0.0-alpha.143 → 2.0.0-alpha.146

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openxiangda-cli",
-  "version": "2.0.0-alpha.143",
+  "version": "2.0.0-alpha.146",
   "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.72",
-    "openxiangda-devkit-core": "2.0.0-alpha.92",
-    "openxiangda-mcp": "2.0.0-alpha.92",
-    "openxiangda-skill-kit": "2.0.0-alpha.113"
+    "openxiangda-contracts": "2.0.0-alpha.73",
+    "openxiangda-devkit-core": "2.0.0-alpha.93",
+    "openxiangda-mcp": "2.0.0-alpha.93",
+    "openxiangda-skill-kit": "2.0.0-alpha.115"
   },
   "devDependencies": {
     "tsx": "4.23.12",

package/template/AGENTS.md

@@ -3,6 +3,25 @@
 - 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.
+- The platform `openxiangda/react` owns the only admin `ConfigProvider` and the
+  `light`/`dark`/`system` appearance preference. Admin pages use Ant Design's
+  `defaultAlgorithm`/`darkAlgorithm`, `theme.useToken()`, or generated
+  `--oxa-antd-*` CSS variables. Do not add a nested theme provider, theme
+  store, palette editor, `--oxa-color-*`/`--oxa-shell-*` aliases, or fixed
+  white/black/neutral structural colors. Future palettes are centralized
+  platform seed configurations; alpha contracts are replaced directly without
+  compatibility aliases. User-end pages are outside this admin visual contract
+  and may use Tailwind CSS and their own product design tokens/components, but
+  must not mutate the admin provider or Seed.
+- Use the complete Ant Design Seed/Map/Alias/Component model on admin pages:
+  platform-owned Seed values feed the selected algorithm; admin code consumes
+  generated Alias values for colors, spacing, typography, control dimensions,
+  motion, shadows, z-index and breakpoints. Never hand-write Map values or
+  introduce an admin token registry. Component tokens are only for
+  platform-approved non-color dimensions and typography.
+- The template includes Tailwind CSS v4 for user-end pages. Keep its `@theme`
+  and utility classes in the user-end layer, omit Tailwind preflight from the
+  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.
 - 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.
@@ -12,7 +31,7 @@
 - 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.
+- Use the current logged-in user and the union of that user's application roles. An app for every logged-in platform user may declare one existing package role through `authz.authenticatedUserRoleCode`; the platform materializes it on first access and unions it with manual and business-projected roles. Do not fabricate a browser fallback role or use a business membership resource for this universal audience. An optional declared Perspective projects only read visibility (pages, rows and fields); create/update/delete, workflows and custom actions continue to authorize against the complete union. Standard Data API calls inherit `X-OpenXiangda-Perspective` automatically. Use `@CurrentPerspective()` only when custom Nest code reads outside the standard Data API, and apply an equivalent read projection explicitly. Business code must not persist a platform Token or authorization result and must not implement a second identity path.
 - Fields inherit the resource read/create/update capabilities. Use field `access` only to tighten them; arrays are all-of and `false` is explicit deny. There is no `write` fallback.
 - Field `type` is semantic, never a hand-authored database type. The supported catalog is exactly `text.short`, `text.long`, `text.rich`, `number.integer`, `number.decimal`, `boolean`, `date`, `time`, `datetime`, `date-range`, `datetime-range`, `option.single`, `option.multiple`, `cascade.single`, `cascade.multiple`, `user.single`, `user.multiple`, `department.single`, `department.multiple`, `resource-ref.single`, `resource-ref.multiple`, `file`, `image`, `signature`, `address`, `location`, `json`, `serial-number`, `uuid` and `subtable`. The compiler alone derives PostgreSQL columns, constraints and indexes.
 - Every `date-range` and `datetime-range` field explicitly declares `rangeBoundary: 'closed' | 'half-open'`. Values remain `{ start, end }`; callers never send or override the boundary. Closed ranges allow `start <= end` and use PostgreSQL `[]`; half-open ranges require `start < end` and use `[)`.

package/template/README.md

@@ -27,11 +27,18 @@ BrowserRouter、RuntimeBoundary、Refine、generated routes 和后台 Shell
 `/admin/todos` 与 `/m/todos`，只读取当前用户的消息/待办投影并统一解析目标页面。
 
 自定义后台页使用 `OpenXiangdaAdminPage` 作为页面根；Ant Design 组件自动继承平台
-`ConfigProvider`，图表等 TypeScript 渲染值读取 `useOpenXiangdaTheme()`，自定义 CSS
-只使用公开的 `--oxa-color-*`、`--oxa-shadow-surface` 和
-`--oxa-radius-surface` 语义变量。不要为后台页新建主题 Provider，也不要把白色、黑色、
-浅灰色写死为页面、卡片、边框或文字颜色。品牌色只能用于品牌和有明确语义的数据分类，
-不能替代结构色。
+`ConfigProvider`，图表等 TypeScript 渲染值读取 `theme.useToken()`，自定义 CSS
+只使用平台生成的 `--oxa-antd-*` CSS 变量。不要为后台页新建主题 Provider、主题状态
+或颜色别名，也不要把白色、黑色、浅灰色写死为页面、卡片、边框或文字颜色。品牌色只能
+用于品牌和有明确语义的数据分类，不能替代结构色。主题只由平台的 Ant Design
+`defaultAlgorithm`/`darkAlgorithm` 生成；Seed 由平台集中维护，Map/Alias、间距、排版、
+动效、阴影、层级、断点和组件尺寸均从算法令牌读取。未来配色扩展只能修改平台集中维护
+的 seed，不得在应用内新建 token registry 或任意颜色输入。
+
+用户端页面不属于这份后台主题合同，可以使用 Tailwind CSS 和自己的产品组件/设计令牌；
+用户端不应依赖 `--oxa-antd-*`，也不能修改后台 Provider 或平台 Seed。
+模板已预装 Tailwind CSS v4 与 Vite 插件；在用户端页面直接使用 utility class，
+并在 `apps/web/src/user-end/tailwind.css` 的 `@theme` 中集中维护用户端产品令牌。
 
 登录声明位于 `frontend.authentication`，只允许现有平台用户并拒绝注册。桌面 `/login`
 与移动 `/m/login` 是独立生成的 `authenticationSurfaces`，不计入受保护的

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

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

@@ -5,7 +5,6 @@ import {
   defineApplicationContributions,
   OpenXiangdaAdminPage,
   OpenXiangdaApplication,
-  useOpenXiangdaTheme,
 } from 'openxiangda/react';
 import type { DataFieldSurface, DataResourceSurface } from 'openxiangda/core';
 import 'openxiangda/react/styles.css';
@@ -198,12 +197,9 @@ const resourceDefinitions = Object.fromEntries(
 );
 
 function ContentOperationsPage() {
-  const { effectiveAppearance, tokens } = useOpenXiangdaTheme();
   return (
     <OpenXiangdaAdminPage
       className="theme-contract-page"
-      data-primary={tokens.primary}
-      data-theme={effectiveAppearance}
       data-testid="custom-admin-page"
     >
       <Typography.Title level={2}>内容业务操作</Typography.Title>

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

@@ -197,7 +197,7 @@ async function mockPlatform(
         body: JSON.stringify({
           code: 200,
           data: {
-            schemaVersion: 'openxiangda.native-data-page/v2',
+            schemaVersion: 'openxiangda.data-page/v2',
             resourceCode,
             appVersionId: 'app-version-1',
             environmentHeadRevision: 1,
@@ -301,18 +301,44 @@ test('custom admin pages inherit tokens and follow live system appearance', asyn
   const customPage = page.getByTestId('custom-admin-page');
   const customPanel = customPage.locator('.theme-contract-panel');
   await expect(page.locator('html')).toHaveAttribute('data-oxa-theme', 'dark');
-  await expect(customPage).toHaveAttribute('data-theme', 'dark');
-  await expect(customPage).toHaveAttribute('data-primary', '#447bdc');
-  await expect(customPage).toHaveCSS('background-color', 'rgb(11, 21, 36)');
-  await expect(customPanel).toHaveCSS('background-color', 'rgb(17, 29, 46)');
-  await expect(customPanel).toHaveCSS('color', 'rgb(215, 224, 236)');
-  await expect(customPanel).toHaveCSS('border-color', 'rgb(38, 55, 79)');
+  const readThemeColors = () =>
+    page.evaluate(() => {
+      const root = document.documentElement;
+      const host = document.querySelector('[data-testid="custom-admin-page"]') ?? root;
+      const probe = document.createElement('div');
+      probe.style.cssText = [
+        'position:fixed',
+        'width:1px',
+        'height:1px',
+        'background:var(--oxa-antd-color-bg-layout)',
+        'color:var(--oxa-antd-color-bg-container)',
+        'border:1px solid var(--oxa-antd-color-border-secondary)',
+        'outline:1px solid var(--oxa-antd-color-text)',
+      ].join(';');
+      host.appendChild(probe);
+      const styles = getComputedStyle(probe);
+      const result = {
+        canvas: styles.backgroundColor,
+        surface: styles.color,
+        border: styles.borderTopColor,
+        text: styles.outlineColor,
+      };
+      probe.remove();
+      return result;
+    });
+  const darkColors = await readThemeColors();
+  await expect(customPage).toHaveCSS('background-color', darkColors.canvas);
+  await expect(customPanel).toHaveCSS('background-color', darkColors.surface);
+  await expect(customPanel).toHaveCSS('color', darkColors.text);
+  await expect(customPanel).toHaveCSS('border-color', darkColors.border);
 
   await page.emulateMedia({ colorScheme: 'light' });
   await expect(page.locator('html')).toHaveAttribute('data-oxa-theme', 'light');
-  await expect(customPage).toHaveAttribute('data-theme', 'light');
-  await expect(customPage).toHaveCSS('background-color', 'rgb(245, 245, 245)');
-  await expect(customPanel).toHaveCSS('background-color', 'rgb(255, 255, 255)');
+  const lightColors = await readThemeColors();
+  await expect(customPage).toHaveCSS('background-color', lightColors.canvas);
+  await expect(customPanel).toHaveCSS('background-color', lightColors.surface);
+  await expect(customPanel).toHaveCSS('color', lightColors.text);
+  await expect(customPanel).toHaveCSS('border-color', lightColors.border);
 });
 
 test('opens the stable admin entry under the preproduction gateway mount', async ({ page }) => {

package/template/apps/web/e2e/theme-contract-fixture.css

@@ -6,10 +6,10 @@
 }
 
 .theme-contract-panel {
-  border: 1px solid var(--oxa-color-border);
-  border-radius: var(--oxa-radius-surface);
-  background: var(--oxa-color-surface);
+  border: 1px solid var(--oxa-antd-color-border-secondary);
+  border-radius: var(--oxa-antd-border-radius);
+  background: var(--oxa-antd-color-bg-container);
   padding: 24px;
-  color: var(--oxa-color-text);
-  box-shadow: var(--oxa-shadow-surface);
+  color: var(--oxa-antd-color-text);
+  box-shadow: var(--oxa-antd-box-shadow-tertiary);
 }

package/template/apps/web/package.json

@@ -14,17 +14,19 @@
     "@ant-design/icons": "6.2.3",
     "@refinedev/core": "5.0.12",
     "antd": "6.4.3",
-    "openxiangda": "2.0.0-alpha.62",
+    "openxiangda": "2.0.0-alpha.65",
     "react": "19.2.8",
     "react-dom": "19.2.8",
     "react-router-dom": "7.8.2"
   },
   "devDependencies": {
     "@playwright/test": "1.62.1",
+    "@tailwindcss/vite": "4.3.3",
     "@types/node": "24.13.3",
     "@types/react": "19.2.14",
     "@types/react-dom": "19.2.3",
     "@vitejs/plugin-react": "4.7.0",
+    "tailwindcss": "4.3.3",
     "tsx": "4.23.12",
     "typescript": "5.9.3",
     "vite": "7.1.3"

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

@@ -20,6 +20,7 @@ import {
   resourceDefinitions,
   workflowDefinitions,
 } from '../../../packages/contracts/src/generated.js';
+import './user-end/tailwind.css';
 import 'openxiangda/react/styles.css';
 
 const ApplicationHome = () => <main>OpenXiangda 应用</main>;

package/template/apps/web/src/user-end/tailwind.css

@@ -0,0 +1,17 @@
+/* User-end Tailwind foundation. Keep its reset and tokens separate from admin. */
+@import "tailwindcss/theme.css";
+@import "tailwindcss/utilities.css";
+
+@source "../";
+
+@theme {
+  --font-sans: Inter, "PingFang SC", "Microsoft YaHei", sans-serif;
+  --font-display: Inter, "PingFang SC", "Microsoft YaHei", sans-serif;
+  --color-user-brand-500: oklch(58.5% 0.205 256);
+  --color-user-brand-600: oklch(51.5% 0.224 256);
+  --color-user-surface: oklch(99% 0.002 256);
+  --color-user-canvas: oklch(97.5% 0.006 256);
+  --color-user-ink: oklch(25% 0.025 256);
+  --color-user-muted: oklch(50% 0.025 256);
+  --radius-user-card: 1rem;
+}

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

@@ -1,4 +1,5 @@
 import react from '@vitejs/plugin-react';
+import tailwindcss from '@tailwindcss/vite';
 import { defineConfig } from 'vite';
 
 const connectedProxy =
@@ -6,7 +7,7 @@ const connectedProxy =
 const port = Number(process.env.OPENXIANGDA_WEB_PORT || 5173);
 
 export default defineConfig({
-  plugins: [react()],
+  plugins: [react(), tailwindcss()],
   base: './',
   optimizeDeps: {
     entries: [

package/template/package.json

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

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

@@ -1,5 +1,5 @@
 // Generated by OpenXiangda 2.0 Native compiler. Do not edit by hand.
-export const compilerContractVersion = "native-3" as const;
+export const compilerContractVersion = "native-4" as const;
 export const appCode = "openxiangda-application" as const;
 export const appName = "OpenXiangda 应用" as const;
 export const appPerspectives = [] as const;