openxiangda-cli 2.0.0-alpha.49 → 2.0.0-alpha.56

package/package.json

@@ -1,24 +1,31 @@
 {
   "name": "openxiangda-cli",
-  "version": "2.0.0-alpha.49",
+  "version": "2.0.0-alpha.56",
   "description": "Thin application-level CLI for OpenXiangda 2.0.",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
   "bin": {
     "openxiangda": "./bin/run.js"
   },
   "files": [
     "bin/",
     "dist/",
+    "template/",
     "README.md"
   ],
   "dependencies": {
     "@oclif/core": "4.13.3",
-    "openxiangda-contracts": "2.0.0-alpha.23",
-    "create-openxiangda": "2.0.0-alpha.42",
-    "openxiangda-devkit-core": "2.0.0-alpha.28",
-    "openxiangda-skill-kit": "2.0.0-alpha.39"
+    "openxiangda-contracts": "2.0.0-alpha.26",
+    "openxiangda-devkit-core": "2.0.0-alpha.33",
+    "openxiangda-mcp": "2.0.0-alpha.33"
   },
   "devDependencies": {
     "tsx": "4.23.12",
@@ -35,9 +42,9 @@
   },
   "license": "MIT",
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "node ../../scripts/prune-package-dist.mjs && tsc -p tsconfig.json",
     "build:release": "node ../../scripts/prune-package-dist.mjs && pnpm build",
     "check": "tsc -p tsconfig.json --noEmit",
-    "test": "tsx --test test/*.test.ts"
+    "test": "node scripts/prepare-template.mjs && tsx --test test/*.test.ts && node ../../scripts/verify-cli-blackbox.mjs"
   }
 }

package/template/.dockerignore

@@ -0,0 +1,12 @@
+node_modules
+dist
+coverage
+playwright-report
+test-results
+.openxiangda
+.turbo
+.turbopack
+.umi
+.umi-production
+.git
+*.log

package/template/.env.example

@@ -0,0 +1,3 @@
+# openxiangda dev injects these values. Do not put platform tokens in this file.
+OPENXIANGDA_APP_CODE=instrument-center
+OPENXIANGDA_DEV_HOST=127.0.0.1

package/template/AGENTS.md

@@ -0,0 +1,8 @@
+# Application development rules
+
+- Build normal application code directly; generated Skills and historical templates are not design authority.
+- Keep CRUD in the replaceable browser Data API adapter under `/service`.
+- Put only real transactional or integration actions in Nest under `/api`.
+- Read current-user role/capability unions from the platform. UI guards are presentation only; server authorization is authoritative.
+- Do not add shadow scope fields. Use `collegeId` and `instrumentAdminIds` directly.
+- Run `openxiangda check` before delivery.

package/template/README.md

@@ -0,0 +1,23 @@
+# OpenXiangda 2.0 仪器应用
+
+这是最小黄金模板：Vite + React Router + Refine Core + Ant Design 前端、NestJS 后端，以及平台 Data/AuthZ 声明。
+
+```bash
+openxiangda login --base-url https://platform.example.com
+openxiangda create instrument-center
+cd instrument-center
+openxiangda dev
+```
+
+`instruments` 覆盖 30 字段、列表筛选、服务端分页排序、新增、编辑、详情、删除和文件上传。所有 CRUD 位于 `apps/web/src/platform-client.ts` 的 Data API adapter；Nest 只保留一个无副作用 current-user 摘要动作。
+
+前端读取平台 current-user 的角色/能力并集进行展示保护，服务端始终权威。字段策略区分 create/update；无权字段在提交前从 payload 删除。
+
+```bash
+openxiangda check
+openxiangda deploy
+openxiangda status
+openxiangda logs
+```
+
+`deploy` 使用本模板的 `apps/server/Dockerfile` 自动构建并推送 `linux/amd64` 镜像，再把不可变 digest 写入 AppPackage。请在本机安装并启动 Docker Buildx，并提前通过 Docker credential store 登录平台声明的镜像仓库；不要把 registry 密钥写进工作区。

package/template/_gitignore

@@ -0,0 +1,14 @@
+node_modules/
+dist/
+coverage/
+playwright-report/
+test-results/
+.openxiangda/
+.turbo/
+.turbopack/
+.umi/
+.umi-production/
+.codegraph/
+.env
+*.log
+.DS_Store

package/template/apps/server/Dockerfile

@@ -0,0 +1,19 @@
+FROM node:22-alpine AS build
+WORKDIR /workspace
+RUN corepack enable
+COPY package.json pnpm-lock.yaml pnpm-workspace.yaml tsconfig.base.json ./
+COPY apps/server/package.json apps/server/package.json
+COPY packages/contracts/package.json packages/contracts/package.json
+RUN pnpm --filter @app/server... install --frozen-lockfile --ignore-scripts
+COPY apps/server apps/server
+COPY packages/contracts packages/contracts
+RUN pnpm --filter @app/server... build
+RUN pnpm --filter @app/server deploy --prod --legacy --ignore-scripts /output
+
+FROM node:22-alpine AS runtime
+ENV NODE_ENV=production
+WORKDIR /app
+COPY --from=build --chown=1000:1000 /output /app
+USER 1000:1000
+EXPOSE 3000
+CMD ["node", "dist/main.js"]

package/template/apps/server/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@app/server",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "tsx watch src/main.ts",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "test": "tsx --test test/*.test.ts",
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/main.js"
+  },
+  "dependencies": {
+    "@app/contracts": "workspace:*",
+    "@nestjs/common": "11.1.29",
+    "@nestjs/core": "11.1.29",
+    "@nestjs/platform-fastify": "11.1.29",
+    "openxiangda-nest": "2.0.0-alpha.31",
+    "reflect-metadata": "0.2.2",
+    "rxjs": "7.8.2"
+  },
+  "devDependencies": {
+    "@types/node": "24.13.3",
+    "tsx": "4.23.12",
+    "typescript": "5.9.3"
+  }
+}

package/template/apps/server/src/app.module.ts

@@ -0,0 +1,32 @@
+import { Module } from '@nestjs/common';
+import { OpenXiangdaModule } from 'openxiangda-nest';
+import { InstrumentContextController } from './instrument-context.controller.js';
+
+@Module({
+  imports: [
+    OpenXiangdaModule.forRoot({
+      appCode: process.env.OPENXIANGDA_APP_CODE || 'instrument-center',
+      platformBaseUrl:
+        process.env.OPENXIANGDA_PLATFORM_BASE_URL ||
+        'http://127.0.0.1:7001/service',
+      environmentKey:
+        process.env.OPENXIANGDA_ENVIRONMENT_KEY || 'preproduction',
+      environmentId:
+        process.env.OPENXIANGDA_ENVIRONMENT_ID || 'connected-development',
+      appVersionId:
+        process.env.OPENXIANGDA_APP_VERSION_ID || 'connected-development',
+      deploymentRunId:
+        process.env.OPENXIANGDA_DEPLOYMENT_RUN_ID || 'connected-development',
+      environmentHeadRevision: Number(
+        process.env.OPENXIANGDA_ENVIRONMENT_HEAD_REVISION || 1
+      ),
+      backendRevisionId:
+        process.env.OPENXIANGDA_BACKEND_REVISION_ID || 'connected-development',
+      version: process.env.OPENXIANGDA_APP_VERSION || '0.1.0-dev',
+      connectedDevelopment:
+        process.env.OPENXIANGDA_CONNECTED_DEV === 'true',
+    }),
+  ],
+  controllers: [InstrumentContextController],
+})
+export class AppModule {}

package/template/apps/server/src/instrument-context.controller.ts

@@ -0,0 +1,25 @@
+import { Controller, Get, UseGuards } from '@nestjs/common';
+import { appOperations } from '@app/contracts';
+import {
+  CurrentUser,
+  OpenXiangdaAuthzGuard,
+  OpenXiangdaOperation,
+  type OpenXiangdaCurrentUser,
+} from 'openxiangda-nest';
+
+@Controller('api/instruments')
+@UseGuards(OpenXiangdaAuthzGuard)
+export class InstrumentContextController {
+  @Get('context')
+  @OpenXiangdaOperation(appOperations.instrumentContextInspect)
+  inspect(@CurrentUser() user: OpenXiangdaCurrentUser) {
+    // Intentionally read-only: this demonstrates local Nest business actions
+    // without wrapping Data API CRUD.
+    return {
+      userId: user.userId,
+      roleCodes: user.roleCodes,
+      capabilityCodes: user.capabilityCodes,
+      environmentKey: user.environmentKey,
+    };
+  }
+}

package/template/apps/server/src/main.ts

@@ -0,0 +1,18 @@
+import 'reflect-metadata';
+import { NestFactory } from '@nestjs/core';
+import {
+  FastifyAdapter,
+  type NestFastifyApplication,
+} from '@nestjs/platform-fastify';
+import { AppModule } from './app.module.js';
+
+const app = await NestFactory.create<NestFastifyApplication>(
+  AppModule,
+  new FastifyAdapter({ trustProxy: true })
+);
+app.enableShutdownHooks();
+const production = process.env.NODE_ENV === 'production';
+await app.listen(
+  Number(process.env.OPENXIANGDA_APP_PORT || process.env.PORT || 3000),
+  production ? '0.0.0.0' : '127.0.0.1'
+);

package/template/apps/server/test/smoke.test.ts

@@ -0,0 +1,28 @@
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import test from 'node:test';
+import { InstrumentContextController } from '../src/instrument-context.controller.js';
+
+test('the example action returns only the verified current-user summary', () => {
+  const result = new InstrumentContextController().inspect({
+    userId: 'user-1',
+    appCode: 'instrument-center',
+    environmentKey: 'preproduction',
+    roleCodes: ['college_admin', 'instrument_admin'],
+    isAppSuperAdmin: false,
+    capabilityCodes: ['app:instrument-center:data:instruments:read'],
+  });
+  assert.deepEqual(result.roleCodes, ['college_admin', 'instrument_admin']);
+  assert.equal(result.userId, 'user-1');
+});
+
+test('the server template owns no CRUD, event, OAuth, or secret implementation', () => {
+  const moduleSource = readFileSync(new URL('../src/app.module.ts', import.meta.url), 'utf8');
+  const controllerSource = readFileSync(
+    new URL('../src/instrument-context.controller.ts', import.meta.url),
+    'utf8'
+  );
+  assert.match(controllerSource, /@CurrentUser\(\)/);
+  assert.doesNotMatch(moduleSource + controllerSource, /oauthClient|eventSigning|RuntimeSecrets|Purchase|Workflow/);
+  assert.doesNotMatch(controllerSource, /createData|updateData|deleteData|queryData/);
+});

package/template/apps/server/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "sourceMap": true
+  },
+  "include": ["src/**/*.ts"]
+}

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

@@ -0,0 +1,150 @@
+import { expect, test } from '@playwright/test';
+
+test('renders the production warning and never requests a role session', async ({
+  page,
+}) => {
+  const requests: string[] = [];
+  page.on('request', request => requests.push(request.url()));
+  await page.route('**/view/instrument-center/instruments', async route => {
+    if (route.request().resourceType() !== 'document') {
+      await route.continue();
+      return;
+    }
+    const response = await route.fetch();
+    const body = (await response.text()).replace(
+      '<head>',
+      `<head>
+        <meta name="openxiangda-runtime-base" content="/view/instrument-center/" />
+        <meta name="openxiangda-app-code" content="instrument-center" />
+        <meta name="openxiangda-environment" content="production" />`
+    );
+    await route.fulfill({ response, body });
+  });
+  await page.route('**/service/**', async route => {
+    const url = new URL(route.request().url());
+    if (
+      url.pathname.endsWith('/native/current-user') &&
+      url.searchParams.get('environmentKey') === 'production'
+    ) {
+      await route.fulfill({
+        contentType: 'application/json',
+        body: JSON.stringify({
+          code: 200,
+          data: {
+            schemaVersion: 'openxiangda.current-user/v2',
+            appCode: 'instrument-center',
+            environment: {
+              id: 'production-id',
+              key: 'production',
+              activeAppVersionId: 'app-version-1',
+              headRevision: 7,
+              authzRevisionId: 'authz-revision-1',
+              authzVersion: 3,
+              scopeDataVersion: 'scope-data-version-1',
+            },
+            principal: {
+              type: 'user',
+              userId: 'user-e2e',
+              roleCodes: ['college_admin', 'instrument_admin'],
+              capabilityCodes: [
+                'app:instrument-center:data:instruments:read',
+                'app:instrument-center:data:instruments:update',
+                'app:instrument-center:instrument:context:read',
+              ],
+              isAppSuperAdmin: false,
+            },
+          },
+        }),
+      });
+      return;
+    }
+    if (url.pathname.endsWith('/native/data/instruments/query')) {
+      expect(route.request().postDataJSON()).toMatchObject({
+        schemaVersion: 'openxiangda.data-query/v2',
+        environmentKey: 'production',
+      });
+      await route.fulfill({
+        contentType: 'application/json',
+        body: JSON.stringify({
+          code: 200,
+          data: {
+            schemaVersion: 'openxiangda.data-page/v2',
+            resourceCode: 'instruments',
+            items: [
+              {
+                id: 'instrument-1',
+                revision: 2,
+                instrumentCode: 'INS-001',
+                chineseName: '场发射扫描电子显微镜',
+                specModel: 'SU8600',
+                categoryId: 'analysis_microscope',
+                assetCode: 'ASSET-001',
+                enabledDate: '2025-01-01',
+                usageStatus: 'active',
+                instrumentStatus: 'normal',
+                openToOutside: true,
+                collegeId: 'college-am',
+                manageDepartmentId: 'dept-am-test',
+                useDepartmentId: 'dept-am-test',
+                instrumentAdminIds: ['user-e2e'],
+                contactUserIds: ['user-e2e'],
+                contactPhone: '13800138000',
+                updatedAt: '2026-08-21T00:00:00.000Z',
+              },
+            ],
+            total: 1,
+            limit: 20,
+            offset: 0,
+          },
+        }),
+      });
+      return;
+    }
+    await route.fulfill({
+      status: 404,
+      contentType: 'application/json',
+      body: JSON.stringify({ code: 404, message: 'not mocked' }),
+    });
+  });
+  await page.goto('/view/instrument-center/instruments');
+  await expect(page.getByTestId('production-data-warning')).toBeVisible();
+  await expect(page.getByTestId('instrument-title')).toHaveText('仪器资源');
+  await expect(page.getByText('场发射扫描电子显微镜')).toBeVisible();
+  await expect(page.getByText('college_admin、instrument_admin')).toBeVisible();
+  expect(requests.filter(url => url.includes('role-session'))).toHaveLength(0);
+  expect(
+    requests.some(url =>
+      url.includes('/native/current-user?environmentKey=production')
+    )
+  ).toBe(true);
+});
+
+test('keeps the production warning visible when current-user fails closed', async ({
+  page,
+}) => {
+  await page.route('**/view/instrument-center/instruments', async route => {
+    if (route.request().resourceType() !== 'document') {
+      await route.continue();
+      return;
+    }
+    const response = await route.fetch();
+    const body = (await response.text()).replace(
+      '<head>',
+      `<head>
+        <meta name="openxiangda-runtime-base" content="/view/instrument-center/" />
+        <meta name="openxiangda-app-code" content="instrument-center" />
+        <meta name="openxiangda-environment" content="production" />`
+    );
+    await route.fulfill({ response, body });
+  });
+  await page.route('**/service/**', route =>
+    route.fulfill({
+      status: 503,
+      contentType: 'application/json',
+      body: JSON.stringify({ code: 503, message: 'current-user unavailable' }),
+    })
+  );
+  await page.goto('/view/instrument-center/instruments');
+  await expect(page.getByTestId('production-data-warning')).toBeVisible();
+  await expect(page.getByText('无法读取平台当前用户')).toBeVisible();
+});

package/template/apps/web/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>仪器资源管理</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/template/apps/web/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@app/web",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "check": "tsc -p tsconfig.json --noEmit && node scripts/check.mjs",
+    "test": "tsx --test test/*.test.ts",
+    "test:e2e": "playwright test",
+    "build": "tsc -p tsconfig.json --noEmit && vite build && node scripts/verify-build.mjs"
+  },
+  "dependencies": {
+    "@ant-design/icons": "6.2.3",
+    "@refinedev/core": "5.0.12",
+    "antd": "6.4.3",
+    "dayjs": "1.11.18",
+    "openxiangda-contracts": "2.0.0-alpha.26",
+    "react": "19.2.8",
+    "react-dom": "19.2.8",
+    "react-router-dom": "7.8.2"
+  },
+  "devDependencies": {
+    "@playwright/test": "1.62.1",
+    "@types/node": "24.13.3",
+    "@types/react": "19.2.14",
+    "@types/react-dom": "19.2.3",
+    "@vitejs/plugin-react": "4.7.0",
+    "tsx": "4.23.12",
+    "typescript": "5.9.3",
+    "vite": "7.1.3"
+  }
+}

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

@@ -0,0 +1,21 @@
+import { defineConfig } from '@playwright/test';
+
+const baseURL =
+  process.env.OPENXIANGDA_E2E_BASE_URL || 'http://127.0.0.1:4173';
+
+export default defineConfig({
+  testDir: './e2e',
+  use: { baseURL, trace: 'retain-on-failure' },
+  webServer: process.env.OPENXIANGDA_E2E_BASE_URL
+    ? undefined
+    : {
+        command: 'pnpm dev',
+        url: baseURL,
+        reuseExistingServer: false,
+        env: {
+          OPENXIANGDA_WEB_PORT: '4173',
+          OPENXIANGDA_ENVIRONMENT_KEY: 'production',
+          OPENXIANGDA_DEV_PROXY: 'http://127.0.0.1:7001',
+        },
+      },
+});

package/template/apps/web/scripts/check.mjs

@@ -0,0 +1,32 @@
+import { readFileSync, readdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+const root = resolve(import.meta.dirname, '..');
+const files = [];
+function visit(directory) {
+  for (const entry of readdirSync(directory, { withFileTypes: true })) {
+    const path = join(directory, entry.name);
+    if (
+      entry.isDirectory() &&
+      !['.umi', '.umi-production', '.turbopack'].includes(entry.name)
+    )
+      visit(path);
+    else if (/\.(?:ts|tsx)$/.test(entry.name)) files.push(path);
+  }
+}
+visit(join(root, 'src'));
+const lines = files.reduce(
+  (total, file) => total + readFileSync(file, 'utf8').split(/\r?\n/).length,
+  0
+);
+if (files.length > 18) throw new Error(`WEB_SOURCE_FILE_BUDGET_EXCEEDED:${files.length}>18`);
+if (lines > 1_600) throw new Error(`WEB_BUSINESS_LOC_BUDGET_EXCEEDED:${lines}>1600`);
+const source = files.map(file => readFileSync(file, 'utf8')).join('\n');
+for (const marker of ['@umijs/', 'openxiangda-' + 'admin', 'openxiangda-' + 'user', 'instrument_query', 'instrument_save', 'function.invoke', 'role' + '-session']) {
+  if (source.includes(marker)) throw new Error(`WEB_FORBIDDEN_MARKER:${marker}`);
+}
+const playwright = readFileSync(join(root, 'playwright.config.ts'), 'utf8');
+if (!playwright.includes('reuseExistingServer: false')) {
+  throw new Error('WEB_E2E_MUST_NOT_REUSE_UNKNOWN_SERVER');
+}
+process.stdout.write(`Verified Vite/Refine web source: ${files.length} files, ${lines} LOC.\n`);

package/template/apps/web/scripts/verify-build.mjs

@@ -0,0 +1,20 @@
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { gzipSync } from 'node:zlib';
+import { join, resolve } from 'node:path';
+
+const dist = resolve(import.meta.dirname, '../dist');
+const assets = join(dist, 'assets');
+const names = readdirSync(assets);
+const files = names.map(name => join(assets, name));
+const total = files.reduce((bytes, file) => bytes + statSync(file).size, 0);
+if (total > 2_500_000) throw new Error(`WEB_DIST_BUDGET_EXCEEDED:${total}>2500000`);
+const javascript = files.filter(file => file.endsWith('.js'));
+const gzip = javascript.reduce(
+  (bytes, file) => bytes + gzipSync(readFileSync(file), { level: 9 }).byteLength,
+  0
+);
+if (gzip > 600_000) throw new Error(`WEB_JS_GZIP_BUDGET_EXCEEDED:${gzip}>600000`);
+if (names.some(name => name.endsWith('.map'))) throw new Error('WEB_SOURCE_MAP_FORBIDDEN');
+const html = readFileSync(join(dist, 'index.html'), 'utf8');
+if (!html.includes('<div id="root"></div>')) throw new Error('WEB_ROOT_MISSING');
+process.stdout.write(`Verified Vite build: ${total} bytes, ${gzip} gzip bytes.\n`);

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

@@ -0,0 +1,60 @@
+import { useOne } from '@refinedev/core';
+import { Button, Result, Space, Spin, Typography } from 'antd';
+import { useNavigate, useParams } from 'react-router-dom';
+import { InstrumentForm } from './InstrumentForm';
+import { Shell } from './Shell';
+import { INSTRUMENT_CAPABILITIES, type InstrumentRecord } from './instrument';
+import { useRuntime } from './runtime';
+
+export function InstrumentDetailPage() {
+  const { id = '' } = useParams();
+  const navigate = useNavigate();
+  const { hasCapability } = useRuntime();
+  const query = useOne<InstrumentRecord>({
+    resource: 'instruments',
+    id,
+    queryOptions: { retry: false },
+  });
+  const record = query.result;
+  if (query.query.isLoading)
+    return (
+      <Shell>
+        <Spin />
+      </Shell>
+    );
+  if (query.query.isError || !record)
+    return (
+      <Shell>
+        <Result
+          status="403"
+          title="无法访问"
+          subTitle={query.query.error?.message || '记录不存在'}
+        />
+      </Shell>
+    );
+  return (
+    <Shell>
+      <Space className="oxa-page-heading">
+        <Typography.Title level={3} style={{ margin: 0 }}>
+          仪器详情
+        </Typography.Title>
+        <Space>
+          <Button onClick={() => navigate('/instruments')}>返回列表</Button>
+          {hasCapability(INSTRUMENT_CAPABILITIES.update) && (
+            <Button
+              type="primary"
+              onClick={() => navigate(`/instruments/${id}/edit`)}
+            >
+              编辑
+            </Button>
+          )}
+        </Space>
+      </Space>
+      <InstrumentForm
+        mode="detail"
+        record={record}
+        onCancel={() => navigate('/instruments')}
+      />
+    </Shell>
+  );
+}