openxiangda 1.0.22 → 1.0.24

package/README.md

@@ -7,21 +7,20 @@ It uses normal platform user login tokens through `/openxiangda-api/v1`; it does
 Private platform routing is fixed: backend APIs are under `/service`, platform management is under `/platform`, and app runtime access is under `/view`. Passing a root domain such as `https://yida.wisejob.cn/` to the CLI is supported; OpenXiangda stores the API base as `https://yida.wisejob.cn/service`.
 
 ```bash
-npm install -g .
-# or during local development:
+npm install -g openxiangda@latest --registry=https://registry.npmjs.org
+openxiangda update check
+openxiangda skill install
+
+# during local development:
 npm link
 
-openxiangda skill install
 openxiangda skill status
-openxiangda workspace init ./my-app-workspace
-cd ./my-app-workspace
-pnpm install
 openxiangda platform add dev https://dev-lowcode.example.com
 openxiangda login --profile dev
 openxiangda env
-openxiangda app list --profile dev
-openxiangda workspace bind --profile dev --app-type APP_XXXX
-cd /path/to/sy-lowcode-app-workspace
+openxiangda workspace init ./my-app-workspace --profile dev --app-name "示例应用"
+cd ./my-app-workspace
+pnpm install
 openxiangda workspace publish --profile dev
 openxiangda menu list --profile dev
 openxiangda workflow list --profile dev
@@ -37,6 +36,16 @@ openxiangda app snapshot APP_XXXX --profile dev --json
 
 User tokens are stored in `~/.openxiangda/profiles.json` with `0600` permissions. Project state is stored in `.openxiangda/state.json` and contains only profile-specific resource IDs.
 
+Use the official npm registry for OpenXiangda updates:
+
+```bash
+npm install -g openxiangda@latest --registry=https://registry.npmjs.org
+openxiangda update check --json
+openxiangda update install
+```
+
+Domestic npm mirrors may lag and return an older OpenXiangda version. `openxiangda update check --json` is designed for AI agents: it returns the installed version, latest official npm version, whether an update is available, and the compatibility commands to run after updating. `openxiangda update install` installs from the official registry and refreshes OpenXiangda skills by default.
+
 Codex skills are installed separately from login/profile state. Run `openxiangda skill install` after installing or linking the CLI. It installs the `openxiangda` root skill plus the 7 top-level subskills into `${CODEX_HOME:-~/.codex}/skills` by default:
 
 - `openxiangda`
@@ -50,10 +59,19 @@ Codex skills are installed separately from login/profile state. Run `openxiangda
 
 Use `openxiangda skill install --dest <skills-dir>` to target a different Codex skills directory. If a same-name skill exists but was not installed by OpenXiangda, the command refuses to overwrite it unless `--force` is provided. Restart Codex after installing skills.
 
-Create a new publishable app workspace with `openxiangda workspace init <dir>`. The command writes a minimal `sy-lowcode-app-workspace` template with React, Ant Design, the single `openxiangda` package, and the required `publish:all` / `openxiangda:publish` scripts. Use `--install` to run `pnpm install` immediately, or run it manually after creation. You can also bind during initialization:
+Create a new publishable app workspace with `openxiangda workspace init <dir>`. The command writes a minimal `sy-lowcode-app-workspace` template with React, Ant Design, the single `openxiangda` package, and the required `publish:all` / `openxiangda:publish` scripts. Use `--install` to run `pnpm install` immediately, or run it manually after creation.
+
+Local workspace state is authoritative. If the current folder has no `.openxiangda/state.json` app binding, create a new app instead of searching the platform for a similar app name:
+
+```bash
+openxiangda workspace init ./my-app-workspace --profile dev --app-name "示例应用"
+```
+
+Bind to an existing app only when the user explicitly provides an `appType` or asks to reuse an existing platform app:
 
 ```bash
 openxiangda workspace init ./my-app-workspace --profile dev --app-type APP_XXXX
+openxiangda workspace bind --profile dev --app-type APP_XXXX
 ```
 
 表单页、流程表单页和自定义代码页都应在 `sy-lowcode-app-workspace` 中实现，由 `openxiangda workspace publish --profile <name>` 统一构建、上传 OSS 并注册到平台。`openxiangda form create`、`form publish`、`page publish` 只作为底层修复/诊断命令，不作为 AI 生成页面的主入口。

package/lib/cli.js

@@ -14,7 +14,7 @@ const {
 } = require('./config');
 const { requestJson } = require('./http');
 const { getSkillStatusReport, installSkills } = require('./skills');
-const { initWorkspace } = require('./workspace-init');
+const { assertCanInitializeWorkspace, initWorkspace } = require('./workspace-init');
 const {
   fail,
   openBrowser,
@@ -24,6 +24,10 @@ const {
   warn,
   writeJson,
 } = require('./utils');
+const { version: CURRENT_VERSION } = require('../package.json');
+
+const NPM_PACKAGE_NAME = 'openxiangda';
+const OFFICIAL_NPM_REGISTRY = 'https://registry.npmjs.org';
 
 async function main(argv) {
   const [command, ...rest] = argv;
@@ -33,6 +37,7 @@ async function main(argv) {
   }
 
   if (command === 'login') return login(rest);
+  if (command === 'update') return update(rest);
   if (command === 'env') return env(rest);
   if (command === 'auth') return auth(rest);
   if (command === 'platform') return platform(rest);
@@ -58,12 +63,14 @@ function printHelp() {
 
 Usage:
   openxiangda login <platform-url> [--profile name]
+  openxiangda update check|install [--json] [--registry https://registry.npmjs.org]
   openxiangda platform add <name> <platform-url>
   openxiangda platform list
   openxiangda platform use <name>
   openxiangda auth status|refresh|logout [--profile name]
   openxiangda env [--profile name]
   openxiangda workspace init [dir] [--name package-name] [--install] [--profile name --app-type APP_XXX]
+  openxiangda workspace init [dir] --profile <name> --app-name <app-name> [--install]
   openxiangda workspace bind --profile <name> --app-type <APP_XXX>
   openxiangda workspace publish --profile <name> [--prune]
   openxiangda app list [--profile name] [--json]
@@ -102,6 +109,199 @@ OpenXiangda 使用普通用户登录 token，不需要 AK/SK。
 JS_CODE V2 使用 trusted_node；AI 源码必须写在 src/js-code-nodes/<scriptCode>/index.ts，definition-json 中的 sourceFile.localPath 会在 validate/create 时先 TS 校验、再构建并上传为快照。`);
 }
 
+async function update(args) {
+  const requestedSubcommand = args[0] && !args[0].startsWith('--') ? args[0] : 'check';
+  const parsedArgs = requestedSubcommand === args[0] ? args.slice(1) : args;
+  const { flags } = parseArgs(parsedArgs);
+  const registry = normalizeNpmRegistry(flags.registry || OFFICIAL_NPM_REGISTRY);
+
+  if (requestedSubcommand === 'check') {
+    const result = checkOpenXiangdaUpdate(registry);
+    if (flags.json) return writeJson(result);
+    printUpdateCheck(result);
+    return;
+  }
+
+  if (requestedSubcommand === 'install') {
+    const result = installOpenXiangdaUpdate(registry, {
+      json: Boolean(flags.json),
+      skipSkills: Boolean(flags['no-skills']),
+    });
+    if (flags.json) return writeJson(result);
+    print('OpenXiangda 已更新。');
+    if (result.skillInstall?.attempted && result.skillInstall.status !== 0) {
+      warn(`skill install 未完成: ${result.skillInstall.error}`);
+    }
+    return;
+  }
+
+  fail('用法: openxiangda update check|install [--json] [--registry https://registry.npmjs.org] [--no-skills]');
+}
+
+function normalizeNpmRegistry(value) {
+  const registry = String(value || OFFICIAL_NPM_REGISTRY).trim();
+  return registry.replace(/\/+$/, '') || OFFICIAL_NPM_REGISTRY;
+}
+
+function checkOpenXiangdaUpdate(registry) {
+  const latestVersion = fetchLatestOpenXiangdaVersion(registry);
+  const versionComparison = compareVersions(latestVersion, CURRENT_VERSION);
+  const updateAvailable = versionComparison > 0;
+  return {
+    packageName: NPM_PACKAGE_NAME,
+    currentVersion: CURRENT_VERSION,
+    latestVersion,
+    registry,
+    updateAvailable,
+    status: updateAvailable
+      ? 'update_available'
+      : versionComparison < 0
+        ? 'local_newer_than_registry'
+        : 'latest',
+    installCommand: `npm install -g ${NPM_PACKAGE_NAME}@latest --registry=${registry}`,
+    skillInstallCommand: 'openxiangda skill install --force',
+    compatibilityCheckCommand: 'openxiangda commands --json',
+    checkedAt: new Date().toISOString(),
+    notes: [
+      'Use the official npm registry for OpenXiangda updates; domestic mirrors may lag.',
+      'After updating the package, refresh OpenXiangda skills so AI guidance matches the CLI version.',
+    ],
+  };
+}
+
+function fetchLatestOpenXiangdaVersion(registry) {
+  const result = spawnSync(
+    'npm',
+    ['view', `${NPM_PACKAGE_NAME}@latest`, 'version', `--registry=${registry}`, '--json'],
+    {
+      encoding: 'utf8',
+      env: { ...process.env, npm_config_registry: registry },
+    }
+  );
+  if (result.error) {
+    fail(`无法执行 npm: ${result.error.message}`);
+  }
+  if (result.status !== 0) {
+    fail(`检查 OpenXiangda 更新失败: ${formatSpawnOutput(result)}`);
+  }
+  const raw = String(result.stdout || '').trim();
+  if (!raw) fail('检查 OpenXiangda 更新失败: npm 未返回版本号');
+  try {
+    const parsed = JSON.parse(raw);
+    return String(parsed).trim();
+  } catch (_error) {
+    return raw.replace(/^"|"$/g, '').trim();
+  }
+}
+
+function installOpenXiangdaUpdate(registry, options = {}) {
+  const npmArgs = [
+    'install',
+    '-g',
+    `${NPM_PACKAGE_NAME}@latest`,
+    `--registry=${registry}`,
+  ];
+  const quiet = Boolean(options.json);
+  if (!quiet) {
+    print(`执行: npm ${npmArgs.join(' ')}`);
+  }
+  const installResult = spawnSync('npm', npmArgs, {
+    encoding: 'utf8',
+    stdio: quiet ? 'pipe' : 'inherit',
+    env: { ...process.env, npm_config_registry: registry },
+  });
+  if (installResult.error) {
+    fail(`无法执行 npm: ${installResult.error.message}`);
+  }
+  if (installResult.status !== 0) {
+    fail(`OpenXiangda 更新失败: ${formatSpawnOutput(installResult)}`);
+  }
+
+  const result = {
+    packageName: NPM_PACKAGE_NAME,
+    registry,
+    installCommand: `npm ${npmArgs.join(' ')}`,
+    installed: true,
+    skillInstall: {
+      attempted: false,
+      status: null,
+      error: null,
+    },
+  };
+
+  if (!options.skipSkills) {
+    if (!quiet) {
+      print('刷新 OpenXiangda skills: openxiangda skill install --force');
+    }
+    const skillResult = spawnSync('openxiangda', ['skill', 'install', '--force'], {
+      encoding: 'utf8',
+      stdio: quiet ? 'pipe' : 'inherit',
+      env: process.env,
+    });
+    result.skillInstall.attempted = true;
+    result.skillInstall.status = skillResult.status;
+    if (skillResult.error || skillResult.status !== 0) {
+      result.skillInstall.error = skillResult.error?.message || formatSpawnOutput(skillResult);
+    }
+  }
+
+  return result;
+}
+
+function printUpdateCheck(result) {
+  const lines = [
+    'OpenXiangda update check',
+    `current: ${result.currentVersion}`,
+    `latest: ${result.latestVersion}`,
+    `registry: ${result.registry}`,
+  ];
+  if (result.updateAvailable) {
+    lines.push('status: update available');
+    lines.push('recommended:');
+    lines.push(`  ${result.installCommand}`);
+    lines.push(`  ${result.skillInstallCommand}`);
+  } else if (result.status === 'local_newer_than_registry') {
+    lines.push('status: local version is newer than registry');
+  } else {
+    lines.push('status: already latest');
+  }
+  lines.push(`compatibility: ${result.compatibilityCheckCommand}`);
+  print(lines.join('\n'));
+}
+
+function formatSpawnOutput(result) {
+  return (
+    String(result.stderr || '').trim() ||
+    String(result.stdout || '').trim() ||
+    `exit status ${result.status}`
+  );
+}
+
+function compareVersions(a, b) {
+  const left = parseSemver(a);
+  const right = parseSemver(b);
+  for (let index = 0; index < 3; index += 1) {
+    if (left.numbers[index] !== right.numbers[index]) {
+      return left.numbers[index] > right.numbers[index] ? 1 : -1;
+    }
+  }
+  if (left.prerelease === right.prerelease) return 0;
+  if (!left.prerelease) return 1;
+  if (!right.prerelease) return -1;
+  return left.prerelease > right.prerelease ? 1 : -1;
+}
+
+function parseSemver(value) {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/.exec(String(value || ''));
+  if (!match) {
+    return { numbers: [0, 0, 0], prerelease: String(value || '') };
+  }
+  return {
+    numbers: [Number(match[1]), Number(match[2]), Number(match[3])],
+    prerelease: match[4] || '',
+  };
+}
+
 async function platform(args) {
   const [subcommand, ...rest] = args;
   const { flags, positional } = parseArgs(rest);
@@ -378,14 +578,49 @@ async function workspace(args) {
   const config = loadConfig();
 
   if (subcommand === 'init') {
+    let appType = flags['app-type'];
+    let profileName = flags.profile || null;
+    let createdApp = null;
+
+    if (flags['app-name']) {
+      if (appType) {
+        fail('workspace init 不能同时使用 --app-name 和 --app-type');
+      }
+      profileName = profileName || config.currentProfile;
+      if (!profileName) {
+        fail('workspace init --app-name 需要先选择 profile，或显式传 --profile <name>');
+      }
+      assertCanInitializeWorkspace({
+        dir: positional[0],
+        force: flags.force,
+      });
+      const data = await createPlatformApp(config, profileName, {
+        name: flags['app-name'],
+        description: flags.description || '',
+        iconfontCss: flags['iconfont-css'] || '',
+      });
+      appType = extractCreatedAppType(data);
+      if (!appType) {
+        fail('应用已创建，但平台响应缺少 appType，无法写入 workspace 绑定');
+      }
+      createdApp = {
+        name: flags['app-name'],
+        appType,
+        data,
+      };
+    }
+
     const result = initWorkspace({
       dir: positional[0],
       name: flags.name,
       install: flags.install,
       force: flags.force,
-      profile: flags.profile,
-      appType: flags['app-type'],
+      profile: profileName,
+      appType,
     });
+    if (createdApp) {
+      result.createdApp = createdApp;
+    }
     if (flags.json) return writeJson(result);
     printWorkspaceInitReport(result);
     return;
@@ -418,6 +653,7 @@ async function workspace(args) {
       },
       updatedAt: new Date().toISOString(),
     };
+    ensureResourceBuckets(state.profiles[profileName]);
     saveProjectState(state);
     print(`当前工作区已绑定 ${profileName}: ${appType}`);
     return;
@@ -463,13 +699,10 @@ async function app(args) {
   if (subcommand === 'create') {
     const name = flags.name || positional.join(' ');
     if (!name) fail('用法: openxiangda app create <name> [--profile name]');
-    const data = await requestWithAuth(config, profileName, '/openxiangda-api/v1/apps/', {
-      method: 'POST',
-      body: {
-        name,
-        description: flags.description || '',
-        iconfontCss: flags['iconfont-css'] || '',
-      },
+    const data = await createPlatformApp(config, profileName, {
+      name,
+      description: flags.description || '',
+      iconfontCss: flags['iconfont-css'] || '',
     });
     if (flags.json) return writeJson(data);
     print(JSON.stringify(data, null, 2));
@@ -490,6 +723,29 @@ async function app(args) {
   print(JSON.stringify(data, null, 2));
 }
 
+async function createPlatformApp(config, profileName, payload) {
+  return requestWithAuth(config, profileName, '/openxiangda-api/v1/apps/', {
+    method: 'POST',
+    body: {
+      name: payload.name,
+      description: payload.description || '',
+      iconfontCss: payload.iconfontCss || '',
+    },
+  });
+}
+
+function extractCreatedAppType(data) {
+  const candidates = [
+    data?.appType,
+    data?.app?.appType,
+    data?.result?.appType,
+    data?.application?.appType,
+    data?.type,
+  ];
+  const value = candidates.find(item => typeof item === 'string' && item.trim());
+  return value ? value.trim() : null;
+}
+
 async function form(args) {
   const [subcommand, ...rest] = args;
   const { flags, positional } = parseArgs(rest);
@@ -1800,10 +2056,11 @@ async function commands(args) {
     name: 'openxiangda',
     commands: [
       'login <platform-url> [--profile name]',
+      'update check|install',
       'platform add|list|use|remove',
       'auth status|refresh|logout',
       'env',
-      'workspace init|bind|publish [--prune]',
+      'workspace init|bind|publish [--app-name] [--prune]',
       'app list|create|snapshot',
       'form list|create|bind|pull|publish',
       'page list|publish|bind|releases|activate',
@@ -1828,6 +2085,9 @@ function printWorkspaceInitReport(result) {
     `已创建 OpenXiangda workspace: ${result.targetDir}`,
     `package: ${result.packageName}`,
   ];
+  if (result.createdApp) {
+    lines.push(`已创建平台应用: ${result.createdApp.name} (${result.createdApp.appType})`);
+  }
   if (result.bound) {
     lines.push(`已绑定 ${result.bound.profile}: ${result.bound.appType}`);
   }

package/lib/workspace-init.js

@@ -41,8 +41,14 @@ function initWorkspace(options = {}) {
             automations: {},
             menus: {},
             roles: {},
+            connectors: {},
+            notifications: {
+              templates: {},
+              typeConfigs: {},
+            },
             pagePermissionGroups: {},
             formPermissionGroups: {},
+            formSettings: {},
           },
           updatedAt: new Date().toISOString(),
         },
@@ -69,6 +75,12 @@ function initWorkspace(options = {}) {
   };
 }
 
+function assertCanInitializeWorkspace(options = {}) {
+  const targetDir = path.resolve(options.dir || process.cwd());
+  ensureCanInitialize(targetDir, Boolean(options.force));
+  return targetDir;
+}
+
 function ensureCanInitialize(targetDir, force) {
   if (!fs.existsSync(TEMPLATE_DIR)) {
     throw new Error(`workspace 模板不存在: ${TEMPLATE_DIR}`);
@@ -135,5 +147,6 @@ function buildNextSteps(targetDir, installedDependencies, bound) {
 }
 
 module.exports = {
+  assertCanInitializeWorkspace,
   initWorkspace,
 };

package/openxiangda-skills/SKILL.md

@@ -35,27 +35,36 @@ When the user provides a root domain such as `https://yida.wisejob.cn/`, use it
    ```bash
    openxiangda login https://dev-lowcode.example.com --profile dev
    ```
-4. Check current context before any write:
+4. Check the CLI version and current context before any write:
    ```bash
+   openxiangda update check --json
    openxiangda env --profile dev
    openxiangda auth status --profile dev
    ```
-5. Ensure there is a local app workspace. If the current directory is not a `sy-lowcode-app-workspace` and no app workspace exists yet, initialize one:
+   If `updateAvailable` is true, update from the official npm registry before continuing:
    ```bash
-   openxiangda workspace init ./my-app-workspace --profile dev --app-type APP_XXXX
+   openxiangda update install
+   ```
+5. Ensure there is a local app workspace. Local workspace state is authoritative:
+   - If the current workspace already has `.openxiangda/state.json` with an app binding for the target profile, use that app.
+   - If the user explicitly provides an `appType` or asks to reuse an existing app, bind to that exact app.
+   - If the current folder is empty or has no local app binding, create a new app and workspace; do not search the platform for similar app names.
+   ```bash
+   openxiangda workspace init ./my-app-workspace --profile dev --app-name "示例应用"
    cd ./my-app-workspace
    pnpm install
    ```
-6. Bind the local workspace to the app for the selected platform:
+6. To bind an existing app only when explicitly requested:
    ```bash
-   openxiangda app list --profile dev
-   # or create one when needed:
-   openxiangda app create "示例应用" --profile dev
+   openxiangda workspace init ./my-app-workspace --profile dev --app-type APP_XXXX
+   # or, inside an existing workspace:
    openxiangda workspace bind --profile dev --app-type APP_XXXX
-   cd /path/to/sy-lowcode-app-workspace
+   ```
+7. Publish from the local workspace:
+   ```bash
    openxiangda workspace publish --profile dev
    ```
-7. For multi-platform publishing, always pass `--profile` explicitly:
+8. For multi-platform publishing, always pass `--profile` explicitly:
    ```bash
    openxiangda workspace publish --profile prod
    ```
@@ -63,7 +72,10 @@ When the user provides a root domain such as `https://yida.wisejob.cn/`, use it
 ## Rules
 
 - Never ask the user for `appKey`, `appSecret`, `AK`, or `SK`.
-- If `openxiangda` is not available in PATH, the CLI package is not installed or linked. In this repo, use `npm link`; in a packaged install, use `npm install -g .` or the published package.
+- If `openxiangda` is not available in PATH, the CLI package is not installed or linked. In this repo, use `npm link`; in a packaged install, use `npm install -g openxiangda@latest --registry=https://registry.npmjs.org`.
+- Always prefer the official npm registry for OpenXiangda updates. Domestic mirrors may lag and return an older package.
+- Run `openxiangda update check --json` when starting substantial work or diagnosing version/skill mismatches. If it reports an update, run `openxiangda update install` so the CLI and installed skills match. If the installed CLI does not support `update`, run `npm install -g openxiangda@latest --registry=https://registry.npmjs.org` and then `openxiangda skill install --force`.
+- Local `.openxiangda/state.json` is the source of truth for app binding. In an empty folder or unbound workspace, create a new app with `workspace init --app-name`; do not infer reuse from similar platform app names.
 - If there is no `sy-lowcode-app-workspace`, create one with `openxiangda workspace init <dir>` before writing forms, pages, or JS_CODE nodes.
 - Never treat `openxiangda form create` as page generation. It only creates a low-level platform form shell for diagnostics or for workspace publish internals. The source of user-facing pages is `sy-lowcode-app-workspace`.
 - Publish normal form pages, workflow form pages, and custom code pages through `openxiangda workspace publish --profile <name>` from the app workspace.
@@ -71,6 +83,7 @@ When the user provides a root domain such as `https://yida.wisejob.cn/`, use it
 - Use logical resource codes in local files. Platform-specific IDs such as `formUuid`, `pageId`, `workflowId`, and `automationId` must be isolated by profile.
 - Put engineering-managed resources in `src/resources/` and use `openxiangda resource validate|plan|publish|pull`. `workspace publish` publishes workspace forms/pages first, then runs non-destructive resource upsert. Only pass `--prune` when the user explicitly wants local manifests to delete platform-side extras.
 - For external APIs, create a connector manifest in `src/resources/connectors/` and call it from pages through `sdk.connector`; never put third-party API keys in page source.
+- Before scaffolding a real app, complex page, data management page, portal shell, status lifecycle, role governance, or automation, read `references/best-practices.md` and pick the architecture first. Prefer copying the relevant pattern from `examples/best-practices/` into `src/` instead of generating a single large page file.
 - Before publishing to another platform, verify the workspace is bound for that profile. Resource IDs from one profile must not be reused for another profile.
 - Use `openxiangda app snapshot <APP_XXX> --profile <name> --json` for diagnosis before changing an existing app.
 - Run write commands that update `.openxiangda/state.json` sequentially within the same workspace. Read-only commands can run in parallel.
@@ -106,6 +119,7 @@ Core CLI / state:
 - `references/workspace-state.md` — `.openxiangda/state.json` shape and profile isolation rules.
 - `references/connector-resources.md` — `src/resources` manifests, connector schema, and SDK connector calls.
 - `references/notifications.md` — `src/resources/notifications`, notification templates/type bindings, and `sdk.notification` / `ctx.notification`.
+- `references/best-practices.md` — initialized examples for modular pages, state lifecycles, role governance, permission isolation, high-performance queries, portal shells, workflow boundaries, and automation patterns.
 
 Form authoring:
 
@@ -130,5 +144,6 @@ Platform domain knowledge (read these first when generating forms or pages so th
 - `references/platform-data-model.md` — how the platform persists field values (JSONB, `{label, value}` for option fields, attachment shape, etc.). Use this whenever you write, render, or diagnose form data.
 - `references/style-system.md` — three-layer style architecture, CSS namespace, and the no-hardcoded-color rule. Use this before writing any page or form CSS.
 - `references/architecture-patterns.md` — CRUD data flow, `DataManagementList` pattern, recommended directory layout for `src/pages` and `src/forms`. Use this before scaffolding a new page or list view.
+- `references/best-practices.md` — read this before implementing app-level business patterns; it points to `examples/best-practices/` and explains when to use status fields instead of workflow.
 - `references/component-guide.md` — when to pick platform components vs. raw Ant Design vs. custom components, with the rules for option fields. Use this before introducing a new component.
 - `references/troubleshooting.md` — known failure modes (missing styles, `options` runtime errors, broken option rendering, etc.) and how to fix them. Use this when something does not behave as expected.

package/openxiangda-skills/references/architecture-patterns.md

@@ -29,9 +29,10 @@
 | 编写 REST API | 平台自动生成数据 API |
 | 维护权限中间件 | 表单字段级权限 + 部门/角色 |
 | 自建文件存储 | `AttachmentField` 直接接入平台存储 |
-| 自研流程引擎 | 表单 + workflow + js-code-nodes |
-
-AI Agent 在该平台上写代码时，**不应该考虑数据库、表结构、后端接口**——这些由表单 schema 自动派生。
+| 业务状态流转 | 表单 + `status` 字段 + 操作日志 + domain/service |
+| 真审批流程 | 表单 + workflow + js-code-nodes |
+
+AI Agent 在该平台上写代码时，**不应该考虑数据库、表结构、后端接口**——这些由表单 schema 自动派生。
 
 ---
 
@@ -144,12 +145,20 @@ export default function InstrumentListPage() {
 | 页面类型 | 实现方式 | 适用场景 |
 | --- | --- | --- |
 | 表单录入 / 编辑页 | `src/forms/xxx/` (`schema.ts` + `page.tsx`) | 新增数据、修改数据 |
-| 数据管理页 | `src/pages/xxx/` 使用 `DataManagementList` | 列表、查询、批量操作、导出 |
-| 流程表单页 | `src/forms/xxx/` 关联 workflow | 审批流程发起、节点处理 |
-| 自定义业务页 | `src/pages/xxx/` 自由编码 | 仪表盘、看板、复杂交互、对外门户 |
-| 详情页 | `src/pages/xxx/[id].tsx` 使用 `FormSummaryCard` 等 | 查看单条数据、关联记录 |
-
-> AI Agent 在创建新页面前，先按上表判断「应该走表单还是代码页」，避免把列表场景误塞进表单页。
+| 数据管理页 | `src/pages/xxx/` 使用 `DataManagementList` | 列表、查询、批量操作、导出 |
+| 状态流转页 | 普通表单 + 状态字段 + 操作日志 + 代码页 service | 工单、订单、任务等业务状态变化 |
+| 流程表单页 | `src/forms/xxx/` 关联 workflow | 真实审批流程发起、节点处理、审批意见 |
+| 自定义业务页 | `src/pages/xxx/` 自由编码 | 仪表盘、看板、复杂交互、对外门户 |
+| 详情页 | `src/pages/xxx/[id].tsx` 使用 `FormSummaryCard` 等 | 查看单条数据、关联记录 |
+
+> AI Agent 在创建新页面前，先按上表判断「应该走表单还是代码页」，避免把列表场景误塞进表单页。
+
+### 4.1 状态流转不是审批流
+
+- 普通业务流转默认使用普通表单：`status` 字段、责任人/归属冗余字段、操作日志表、domain 状态机、service 统一提交。
+- 每次状态变更都由 service 完成，统一写操作日志并更新责任人、归属、更新时间等冗余字段。
+- workflow 只用于真实审批：审批人、审批任务、同意/驳回、审批意见、节点权限、流程记录明确存在的场景。
+- 不要把「待处理 / 处理中 / 已完成 / 已关闭」这类状态流转建成流程表单。
 
 ---
 
@@ -175,7 +184,7 @@ export default function InstrumentListPage() {
 - **UI 库分端**：
   - PC → `antd`
   - Mobile → `antd-mobile`
-- **逻辑层共享**：`src/domain/` 与 `src/shared/services/` 在两端复用，确保业务规则一处实现。
+- **逻辑层共享**：`src/domain/` 与 `src/shared/services/` 在两端复用，确保业务规则一处实现。
 
 ### 5.2 共享 / 分离原则
 
@@ -228,15 +237,28 @@ forms ──▶ shared ──▶ domain
 ```
 
 - `domain/` 不依赖 `shared/` 或 UI。
-- `shared/` 不依赖 `pages/` 或 `forms/`。
-- 反向依赖（如 domain 导入 pages）= 立刻拒绝。
-
----
-
-## 速查 Checklist（AI Agent 自检）
-
-- [ ] 新增数据场景：是否已经定义表单 schema？
-- [ ] 列表/查询场景：是否使用 `DataManagementList` 而非平台 view？
-- [ ] 菜单绑定：是否指向代码页 `--type=page`？
-- [ ] PC/Mobile：是否分离页面、共享 domain？
-- [ ] 目录：业务逻辑是否落在 `domain/`，未污染 UI 层？
+- `shared/` 不依赖 `pages/` 或 `forms/`。
+- 反向依赖（如 domain 导入 pages）= 立刻拒绝。
+
+---
+
+## 7. 查询与交互性能
+
+- 列表必须走分页接口，传 `currentPage`、`pageSize`、排序和结构化条件。
+- 禁止一次取大 `pageSize` 再在页面内筛选。
+- 默认不要使用 `searchKeyWord`；多字段模糊查询用 `filterGroup` + `OR`，并显式指定字段。
+- 查询条件构造放在 `domain/` 或 `shared/services/`，不要散落在 TSX 事件处理里。
+- 列表刷新时保留当前数据，使用局部刷新态，避免整页闪烁。
+- 操作需要统一的确认、pending、成功反馈、失败刷新或回滚。
+
+---
+
+## 速查 Checklist（AI Agent 自检）
+
+- [ ] 新增数据场景：是否已经定义表单 schema？
+- [ ] 列表/查询场景：是否使用 `DataManagementList` 而非平台 view？
+- [ ] 查询：是否使用分页和结构化条件，而不是大 pageSize、页面内过滤或 `searchKeyWord`？
+- [ ] 流程判断：是否确认这是「真审批」，而不是普通状态流转？
+- [ ] 菜单绑定：是否指向代码页 `--type=page`？
+- [ ] PC/Mobile：是否分离页面、共享 domain？
+- [ ] 目录：业务逻辑是否落在 `domain/`，未污染 UI 层？