openxiangda 1.0.159 → 1.0.161

package/packages/sdk/src/build-source/scripts/register.mjs

@@ -20,7 +20,10 @@ import {
   ensureSchemaFormUuid,
   getOpenApiAccessToken,
   getOpenApiForm,
+  getOpenXiangdaPublishContextHeaders,
   isOpenXiangdaMode,
+  markWorkspaceFormBundlePublished,
+  mutateOpenXiangdaFormConfig,
 } from "./utils/form-api.mjs";
 import { assertFormReadyForBundle } from "./utils/schema-transform.mjs";
 
@@ -88,6 +91,7 @@ async function registerForms() {
 
     let formUuid;
     let appType;
+    let releaseExpectation = null;
     try {
       const ensured = await ensureSchemaFormUuid({
         config,
@@ -99,6 +103,7 @@ async function registerForms() {
       });
       formUuid = ensured.formUuid;
       appType = ensured.appType || config.appType;
+      releaseExpectation = ensured.releaseExpectation;
       if (ensured.created || ensured.dryRunCreated) created += 1;
     } catch (error) {
       console.error(`  ✗ 表单 ${formName}: ${error.message}`);
@@ -152,34 +157,57 @@ async function registerForms() {
       continue;
     }
 
-    const response = await fetch(getFormPublishUrl(appType, formUuid), {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        ...(isOpenXiangdaMode(config)
-          ? { Authorization: `Bearer ${await getAccessToken()}` }
-          : { "x-acs-dingtalk-access-token": await getAccessToken() }),
-      },
-      body: JSON.stringify(
-        isOpenXiangdaMode(config)
-          ? {
+    let body;
+    if (isOpenXiangdaMode(config)) {
+      try {
+        const mutation = await mutateOpenXiangdaFormConfig(
+          config,
+          await getAccessToken(),
+          {
+            appType,
+            formUuid,
+            endpoint: "publish",
+            operation: "bundle",
+            expected: releaseExpectation,
+            payload: {
               bundleUrl: payload.bundleUrl,
               cssUrl: payload.cssUrl,
               cssIsolation: payload.cssIsolation,
               version: payload.version,
               runtimeMode: payload.runtimeMode,
               runtime: payload.runtime,
-            }
-          : payload,
-      ),
-    });
-    const body = await response.json().catch(() => null);
-    if (!response.ok || body?.code !== 200) {
-      console.error(
-        `  ✗ 表单 ${formName}: HTTP ${response.status} ${body?.message || response.statusText}`,
-      );
-      failed += 1;
-      continue;
+            },
+          },
+        );
+        body = mutation.response;
+        markWorkspaceFormBundlePublished(config, formName, formUuid, {
+          revision: mutation.data?.revision,
+          etag: mutation.data?.etag,
+          activeFormReleaseHead: mutation.data?.activeFormReleaseHead,
+          version: payload.version,
+        });
+      } catch (error) {
+        console.error(`  ✗ 表单 ${formName}: ${error.message}`);
+        failed += 1;
+        continue;
+      }
+    } else {
+      const response = await fetch(getFormPublishUrl(appType, formUuid), {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "x-acs-dingtalk-access-token": await getAccessToken(),
+        },
+        body: JSON.stringify(payload),
+      });
+      body = await response.json().catch(() => null);
+      if (!response.ok || body?.code !== 200) {
+        console.error(
+          `  ✗ 表单 ${formName}: HTTP ${response.status} ${body?.message || response.statusText}`,
+        );
+        failed += 1;
+        continue;
+      }
     }
     console.log(`  ✓ 表单 ${formName} (${formUuid})`);
     succeeded += 1;
@@ -242,7 +270,10 @@ async function registerPages() {
     headers: {
       "Content-Type": "application/json",
       ...(isOpenXiangdaMode(config)
-        ? { Authorization: `Bearer ${await getAccessToken()}` }
+        ? {
+            Authorization: `Bearer ${await getAccessToken()}`,
+            ...getOpenXiangdaPublishContextHeaders(),
+          }
         : { "x-acs-dingtalk-access-token": await getAccessToken() }),
     },
     body: JSON.stringify(payload),

package/packages/sdk/src/build-source/scripts/sync-schema.mjs

@@ -21,8 +21,10 @@ import { loadConfig, getApiBaseUrl, rootDir } from "./utils/load-config.mjs";
 import {
   ensureSchemaFormUuid,
   getOpenApiAccessToken,
+  getOpenApiForm,
   isOpenXiangdaMode,
   markWorkspaceFormSchemaSynced,
+  mutateOpenXiangdaFormConfig,
 } from "./utils/form-api.mjs";
 import {
   assertSchemaSyncResult,
@@ -169,7 +171,7 @@ async function loadSchema(schemaPath) {
 
 // ---------- API 发送 ----------
 
-async function sendToApi(apiPayload, config, accessToken) {
+async function sendToApi(apiPayload, config, accessToken, expected) {
   const apiBase = getApiBaseUrl(config);
   const targetAppType = apiPayload.appType || config.appType;
   const url = isOpenXiangdaMode(config)
@@ -178,29 +180,57 @@ async function sendToApi(apiPayload, config, accessToken) {
 
   console.log(`  发送请求到: ${url}`);
 
+  if (isOpenXiangdaMode(config)) {
+    const mutation = await mutateOpenXiangdaFormConfig(config, accessToken, {
+      appType: targetAppType,
+      formUuid: apiPayload.formUuid,
+      endpoint: "schema",
+      operation: "schema",
+      expected,
+      payload: {
+        schema: apiPayload.schema,
+        packages: apiPayload.packages,
+        formType: apiPayload.formType,
+      },
+    });
+    const formMeta = await getOpenApiForm(config, accessToken, {
+      appType: targetAppType,
+      formUuid: apiPayload.formUuid,
+    });
+    if (Number(formMeta?.revision) !== Number(mutation.data?.revision)) {
+      const error = new Error(
+        `FORM_REVISION_CONFLICT: schema 激活返回 r${mutation.data?.revision}，校验读取为 r${formMeta?.revision}；未继续发布`,
+      );
+      error.code = "FORM_REVISION_CONFLICT";
+      throw error;
+    }
+    const verified = {
+      ...mutation.response,
+      data: {
+        ...mutation.data,
+        tableName: formMeta?.tableName,
+        formFields: formMeta?.formFields,
+      },
+    };
+    assertSchemaSyncResult(verified, apiPayload.fieldCount);
+    return verified;
+  }
+
   const response = await fetch(url, {
     method: "POST",
     headers: {
       "Content-Type": "application/json",
-      ...(isOpenXiangdaMode(config)
-        ? { Authorization: `Bearer ${accessToken}` }
-        : { "x-acs-dingtalk-access-token": accessToken }),
+      "x-acs-dingtalk-access-token": accessToken,
     },
     body: JSON.stringify(
-      isOpenXiangdaMode(config)
-        ? {
-            schema: apiPayload.schema,
-            packages: apiPayload.packages,
-            formType: apiPayload.formType,
-          }
-        : {
-            userId: config.userId,
-            appType: targetAppType,
-            formUuid: apiPayload.formUuid,
-            schema: apiPayload.schema,
-            packages: apiPayload.packages,
-            formType: apiPayload.formType,
-          },
+      {
+        userId: config.userId,
+        appType: targetAppType,
+        formUuid: apiPayload.formUuid,
+        schema: apiPayload.schema,
+        packages: apiPayload.packages,
+        formType: apiPayload.formType,
+      },
     ),
   });
 
@@ -261,6 +291,7 @@ async function main() {
       continue;
     }
 
+    let releaseExpectation = null;
     try {
       if (!args.dryRun && !accessToken) {
         accessToken = await getOpenApiAccessToken(config);
@@ -275,6 +306,7 @@ async function main() {
       });
       schema.formMeta.formUuid = ensured.formUuid;
       schema.formMeta.appType = ensured.appType || schema.formMeta.appType;
+      releaseExpectation = ensured.releaseExpectation;
       if (ensured.created || ensured.dryRunCreated) {
         createdForms.add(form.name);
       }
@@ -305,12 +337,20 @@ async function main() {
       results.push({ name: form.name, success: true, dryRun: true });
     } else {
       try {
-        const response = await sendToApi(apiPayload, config, accessToken);
+        const response = await sendToApi(
+          apiPayload,
+          config,
+          accessToken,
+          releaseExpectation,
+        );
         markWorkspaceFormSchemaSynced(config, form.name, apiPayload.formUuid, {
           title: schema.formMeta?.title || form.name,
           formType: apiPayload.formType || schema.formMeta?.formType || "receipt",
           fieldCount: apiPayload.fieldCount,
           tableName: response?.data?.tableName,
+          revision: response?.data?.revision,
+          etag: response?.data?.etag,
+          activeFormReleaseHead: response?.data?.activeFormReleaseHead,
         });
         console.log(`  ✅ 同步成功，tableName=${response.data.tableName}`);
         results.push({ name: form.name, success: true, response });

package/packages/sdk/src/build-source/scripts/utils/form-api.mjs

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import crypto from "node:crypto";
 import { getApiBaseUrl, rootDir } from "./load-config.mjs";
 
 const PROJECT_STATE_FILE = ".openxiangda/state.json";
@@ -124,6 +125,44 @@ export function markWorkspaceFormSchemaSynced(config, formName, formUuid, extra
   });
 }
 
+export function markWorkspaceFormBundlePublished(
+  config,
+  formName,
+  formUuid,
+  extra = {},
+) {
+  return saveWorkspaceFormBinding(config, formName, formUuid, {
+    ...extra,
+    bundlePublishedAt: new Date().toISOString(),
+  });
+}
+
+export function normalizeFormReleaseExpectation(value) {
+  const revision = Number(value?.revision);
+  if (!Number.isSafeInteger(revision) || revision < 1) return null;
+  const head = value?.activeFormReleaseHead || value?.expectedParent || {};
+  return {
+    revision,
+    etag: String(value?.etag || "").trim() || undefined,
+    activeFormReleaseHead: {
+      releaseId: head?.releaseId || null,
+      releaseHash: head?.releaseHash || null,
+      revision: Number(head?.revision ?? revision),
+    },
+  };
+}
+
+function formReleaseStateFields(value) {
+  const expectation = normalizeFormReleaseExpectation(value);
+  return expectation
+    ? {
+        revision: expectation.revision,
+        ...(expectation.etag ? { etag: expectation.etag } : {}),
+        activeFormReleaseHead: expectation.activeFormReleaseHead,
+      }
+    : {};
+}
+
 function readExportedStringConstant(filePath, exportName) {
   if (!filePath || !fs.existsSync(filePath)) return "";
   const content = fs.readFileSync(filePath, "utf-8");
@@ -344,10 +383,25 @@ export function isOpenXiangdaMode(config) {
   return Boolean(config.openXiangdaAccessToken);
 }
 
+export function getOpenXiangdaPublishContextHeaders(env = process.env) {
+  const values = [
+    ["x-openxiangda-publish-lease-id", env.OPENXIANGDA_PUBLISH_LEASE_ID],
+    ["x-openxiangda-change-baseline-id", env.OPENXIANGDA_CHANGE_BASELINE_ID],
+    ["x-openxiangda-change-id", env.OPENXIANGDA_CHANGE_ID],
+    ["x-openxiangda-client-session-id", env.OPENXIANGDA_CLIENT_SESSION_ID],
+  ];
+  return Object.fromEntries(
+    values
+      .map(([name, value]) => [name, String(value || "").trim()])
+      .filter(([, value]) => Boolean(value)),
+  );
+}
+
 function getAuthHeaders(config, accessToken) {
   if (isOpenXiangdaMode(config)) {
     return {
       Authorization: `Bearer ${accessToken || config.openXiangdaAccessToken}`,
+      ...getOpenXiangdaPublishContextHeaders(),
     };
   }
   return {
@@ -355,6 +409,175 @@ function getAuthHeaders(config, accessToken) {
   };
 }
 
+function canonicalize(value) {
+  if (Array.isArray(value)) return value.map((item) => canonicalize(item));
+  if (!value || typeof value !== "object") return value;
+  return Object.fromEntries(
+    Object.keys(value)
+      .sort()
+      .filter((key) => value[key] !== undefined)
+      .map((key) => [key, canonicalize(value[key])]),
+  );
+}
+
+function canonicalJsonSha256(value) {
+  return crypto
+    .createHash("sha256")
+    .update(JSON.stringify(canonicalize(value)))
+    .digest("hex");
+}
+
+function normalizeFrozenFormSnapshot(value, label = "Form snapshot") {
+  const expectation = normalizeFormReleaseExpectation(value);
+  if (!expectation?.etag) {
+    const error = new Error(
+      `FORM_REVISION_CONFLICT: ${label} 未返回有效 revision/etag，拒绝配置写入`,
+    );
+    error.code = "FORM_REVISION_CONFLICT";
+    throw error;
+  }
+  if (expectation.activeFormReleaseHead.revision !== expectation.revision) {
+    const error = new Error(
+      `FORM_REVISION_CONFLICT: ${label} 的 head revision 与 Form revision 不一致`,
+    );
+    error.code = "FORM_REVISION_CONFLICT";
+    throw error;
+  }
+  return {
+    ...value,
+    ...expectation,
+    expectedParent: expectation.activeFormReleaseHead,
+  };
+}
+
+function assertExpectedFormSnapshot(frozen, expected) {
+  const normalizedExpected = normalizeFormReleaseExpectation(expected);
+  if (!normalizedExpected) return;
+  const headMatches =
+    canonicalJsonSha256(normalizedExpected.activeFormReleaseHead) ===
+    canonicalJsonSha256(frozen.expectedParent);
+  const etagMatches =
+    !normalizedExpected.etag || normalizedExpected.etag === frozen.etag;
+  if (
+    normalizedExpected.revision !== frozen.revision ||
+    !headMatches ||
+    !etagMatches
+  ) {
+    const error = new Error(
+      `FORM_REVISION_CONFLICT: 工作区冻结 revision=r${normalizedExpected.revision}，平台当前 revision=r${frozen.revision}；未执行写入，请先合并并重新规划`,
+    );
+    error.code = "FORM_REVISION_CONFLICT";
+    throw error;
+  }
+}
+
+async function readJsonResponse(response) {
+  return await response.json().catch(() => null);
+}
+
+export async function getOpenXiangdaFormSnapshot(
+  config,
+  accessToken,
+  { appType, formUuid },
+) {
+  if (!isOpenXiangdaMode(config)) return null;
+  const targetAppType = appType || config.appType;
+  const apiBase = getApiBaseUrl(config);
+  const response = await fetch(
+    `${apiBase}/openxiangda-api/v1/apps/${encodeURIComponent(targetAppType)}/forms/${encodeURIComponent(formUuid)}/snapshot`,
+    {
+      method: "GET",
+      headers: {
+        "Content-Type": "application/json",
+        ...getAuthHeaders(config, accessToken),
+      },
+    },
+  );
+  const body = await readJsonResponse(response);
+  if (!response.ok || body?.code !== 200) {
+    const message = body?.message || response.statusText || "unknown error";
+    const error = new Error(
+      `查询 Form snapshot 失败: HTTP ${response.status} ${message}`,
+    );
+    error.code = body?.errorCode || "FORM_REVISION_CONFLICT";
+    throw error;
+  }
+  return normalizeFrozenFormSnapshot(body.data);
+}
+
+export async function mutateOpenXiangdaFormConfig(
+  config,
+  accessToken,
+  {
+    appType,
+    formUuid,
+    endpoint,
+    operation,
+    payload,
+    expected,
+    artifactId,
+  },
+) {
+  if (!isOpenXiangdaMode(config)) {
+    throw new Error("mutateOpenXiangdaFormConfig 仅用于 OpenXiangda 模式");
+  }
+  const targetAppType = appType || config.appType;
+  const frozen = await getOpenXiangdaFormSnapshot(config, accessToken, {
+    appType: targetAppType,
+    formUuid,
+  });
+  assertExpectedFormSnapshot(frozen, expected);
+  const expectedParent = frozen.expectedParent;
+  const mutationPayload = payload || {};
+  const stableArtifactId =
+    artifactId ||
+    `form:${String(operation || endpoint || "config")
+      .replace(/[^A-Za-z0-9_.-]+/g, "-")
+      .slice(0, 48)}:${canonicalJsonSha256({
+      appType: targetAppType,
+      formUuid,
+      operation: operation || endpoint,
+      expectedParent,
+      payload: mutationPayload,
+    }).slice(0, 32)}`;
+  const apiBase = getApiBaseUrl(config);
+  const url = `${apiBase}/openxiangda-api/v1/apps/${encodeURIComponent(targetAppType)}/forms/${encodeURIComponent(formUuid)}/${String(endpoint || "").replace(/^\/+/, "")}`;
+  const response = await fetch(url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      ...getAuthHeaders(config, accessToken),
+      "If-Match": frozen.etag,
+    },
+    body: JSON.stringify({
+      ...mutationPayload,
+      artifactId: stableArtifactId,
+      expectedRevision: frozen.revision,
+      expectedParent,
+    }),
+  });
+  const body = await readJsonResponse(response);
+  if (!response.ok || body?.code !== 200) {
+    const message = body?.message || response.statusText || "unknown error";
+    const error = new Error(
+      `${body?.errorCode || "FORM_CONFIG_WRITE_FAILED"}: HTTP ${response.status} ${message}`,
+    );
+    error.code = body?.errorCode || "FORM_CONFIG_WRITE_FAILED";
+    error.status = response.status;
+    error.data = body?.data;
+    throw error;
+  }
+  const resultExpectation = normalizeFormReleaseExpectation(body.data);
+  if (!resultExpectation) {
+    const error = new Error(
+      "FORM_REVISION_CONFLICT: Form 配置写响应未返回 revision/head",
+    );
+    error.code = "FORM_REVISION_CONFLICT";
+    throw error;
+  }
+  return { response: body, data: body.data, frozen, url };
+}
+
 export async function getOpenApiAccessToken(config) {
   assertRequiredOpenApiConfig(config);
   if (isOpenXiangdaMode(config)) {
@@ -414,6 +637,7 @@ export async function createOpenApiForm(config, accessToken, formOptions) {
     payload.createMenu = formOptions.createMenu !== false;
     payload.menuParentId = config.menu?.parentId || "";
     payload.menuIcon = config.menu?.icon || "";
+    payload.expectedRevision = 0;
   } else {
     payload.userId = config.userId;
     payload.appType = targetAppType;
@@ -428,6 +652,7 @@ export async function createOpenApiForm(config, accessToken, formOptions) {
     headers: {
       "Content-Type": "application/json",
       ...getAuthHeaders(config, accessToken),
+      ...(isOpenXiangdaMode(config) ? { "If-Match": "0" } : {}),
     },
     body: JSON.stringify(payload),
   });
@@ -444,7 +669,8 @@ export async function createOpenApiForm(config, accessToken, formOptions) {
     throw new Error(`创建表单失败: HTTP ${res.status} ${message}`);
   }
 
-  const data = body?.data?.form || body?.data || body;
+  const responseData = body?.data || body;
+  const data = responseData?.form || responseData;
   const formUuid = data?.formUuid;
   if (!formUuid) {
     throw new Error("创建表单成功但响应中没有 formUuid");
@@ -453,6 +679,10 @@ export async function createOpenApiForm(config, accessToken, formOptions) {
   return {
     ...data,
     formUuid,
+    revision: data?.revision ?? responseData?.revision,
+    etag: data?.etag ?? responseData?.etag,
+    activeFormReleaseHead:
+      responseData?.activeFormReleaseHead || data?.activeFormReleaseHead,
   };
 }
 
@@ -643,6 +873,9 @@ export async function ensureSchemaFormUuid({
   const meta = readSchemaMeta(schemaPath);
   const targetAppType = resolveTargetAppType(config, meta);
   const workspaceBinding = readWorkspaceFormBinding(config, formName);
+  const workspaceReleaseExpectation = normalizeFormReleaseExpectation(
+    workspaceBinding?.form,
+  );
   const effectiveMeta = workspaceBinding?.form?.formUuid
     ? {
         ...meta,
@@ -658,6 +891,7 @@ export async function ensureSchemaFormUuid({
 
   if (effectiveMeta.formUuid && !staleOpenXiangdaBinding) {
     let created = false;
+    let createdForm = null;
     if (!dryRun) {
       const token = accessToken || (await getOpenApiAccessToken(config));
       const existingForm = await getOpenApiForm(config, token, {
@@ -666,7 +900,7 @@ export async function ensureSchemaFormUuid({
       });
 
       if (!existingForm) {
-        await createOpenApiForm(config, token, {
+        createdForm = await createOpenApiForm(config, token, {
           name: effectiveMeta.title || formName,
           appType: targetAppType,
           formType: effectiveMeta.formType || "receipt",
@@ -699,6 +933,7 @@ export async function ensureSchemaFormUuid({
 
       saveWorkspaceFormBinding(config, formName, effectiveMeta.formUuid, {
         title: effectiveMeta.title || formName,
+        ...formReleaseStateFields(createdForm),
       });
     }
 
@@ -707,6 +942,9 @@ export async function ensureSchemaFormUuid({
       appType: targetAppType,
       created,
       dryRunCreated: false,
+      releaseExpectation:
+        normalizeFormReleaseExpectation(createdForm) ||
+        workspaceReleaseExpectation,
     };
   }
 
@@ -745,6 +983,7 @@ export async function ensureSchemaFormUuid({
   if (isOpenXiangdaMode(config)) {
     saveWorkspaceFormBinding(config, formName, createdForm.formUuid, {
       title: createOptions.name,
+      ...formReleaseStateFields(createdForm),
     });
   } else {
     syncCreatedFormMeta(schemaPath, meta, targetAppType, createdForm.formUuid);
@@ -775,5 +1014,6 @@ export async function ensureSchemaFormUuid({
     created: true,
     menuCreated: menuResult.created,
     dryRunCreated: false,
+    releaseExpectation: normalizeFormReleaseExpectation(createdForm),
   };
 }

package/templates/openxiangda-react-spa/.cursor/rules/openxiangda-resources.mdc

@@ -11,9 +11,10 @@ You are editing engineering-managed resource manifests under `src/resources/`. L
 ## Commands
 
 ```bash
-openxiangda resource validate --profile <name>
-openxiangda resource plan --profile <name>
-openxiangda resource publish --profile <name>
+openxiangda resource validate <type> --only <codes> --profile <name>
+openxiangda resource plan <type> --only <codes> --profile <name>
+openxiangda resource publish <type> --only <codes> --profile <name>
+# one target: replace --only <codes> with --code <code>
 openxiangda resource typegen --profile <name>
 ```
 
@@ -23,3 +24,6 @@ openxiangda resource typegen --profile <name>
 - Guest access to forms, dataViews, functions, and connectors requires explicit policy `grants`.
 - Connector secrets and third-party credentials belong in the platform backend, never in manifests or page source.
 - Formal changes should keep Git as the source of truth: edit manifests, validate, plan, then publish.
+- `resource plan` and publish dry-runs are GET/HEAD-only. On `READ_ONLY_AUTH_REQUIRED`, run `openxiangda auth refresh --profile <name>` or log in again before retrying; never refresh inside the plan.
+- Source-triggered Function/Automation publishing patches only source fields on the server and preserves online bindings/contracts/metadata/state. Whole-manifest replacement requires `--replace-manifest --reason "..."`.
+- Formal promotion runs `release begin --change` (freeze Git + remote baseline, preflight the complete set) through `release end`. Reconcile `SOURCE_BASE_DIVERGED` / `RESOURCE_FIELD_CONFLICT`; never retry an old full payload with a fresh revision.

package/templates/openxiangda-react-spa/.cursor/rules/openxiangda.mdc

@@ -11,10 +11,10 @@ This is an OpenXiangda React SPA workspace. See [AGENTS.md](mdc:AGENTS.md) for f
 
 | User says | Command |
 |---|---|
-| publish resources | `openxiangda resource publish --profile <name>` |
-| deploy frontend | `openxiangda runtime deploy --profile <name>` |
+| publish resources | `openxiangda resource publish <type> --only <codes> --profile <name> --change <change>` |
+| deploy frontend | `openxiangda runtime deploy --profile <name> --no-activate` |
 | full deploy | `pnpm deploy -- --profile <name>` |
-| diff / plan | `openxiangda resource plan --profile <name>` |
+| diff / plan | `openxiangda resource plan <type> --only <codes> --profile <name>` |
 | diagnose | `openxiangda doctor --profile <name> --json` |
 | external backend Open API | `openxiangda-open-api` + `openxiangda open-api spec describe ...` |
 
@@ -22,10 +22,16 @@ This is an OpenXiangda React SPA workspace. See [AGENTS.md](mdc:AGENTS.md) for f
 
 - Writes and deploys must pass `--profile <name>` explicitly.
 - Architecture-class work is plan-gated: run `openxiangda design gates --topic <code> --json` and wait for confirmation.
-- High-risk changes must start with `openxiangda sdd context --json`, use an approved change, complete `coverage.json`, `release.json`, `evidence.md`, and `tasks.md`, then run `openxiangda sdd verify <change> --changed` before release.
+- Give every task an isolated worktree/branch and one explicit change. `sdd context` claims the current worktree for `CODEX_THREAD_ID`; on `WORKTREE_OWNED_BY_ANOTHER_TASK`, switch worktrees. Keep the same change for plan/check/verify/publish/archive.
+- L0 read-only/docs/tests need no SDD; L1 narrow reversible fixes record exact scope without a redundant second confirmation; schema, business Functions, Automation/Workflow, permissions, auth/public access, data writes, and runtime/config are L2/L3 full-SDD work. Live evidence/archive are post-release stages.
+- Very small copy/style/binding changes may use `openxiangda sdd quick <change> ...`; quick mode records exact low-risk scope without a redundant proposal/approval loop when the user already requested it.
+- Use staged verification: `--stage implementation` while developing, `--stage prepublish` before promotion, and `--stage postpublish` after activation.
+- Before platform writes, run `openxiangda release begin --change <change> --profile <name>` to freeze Git + remote field heads and preflight the complete target set; finish or abandon with `openxiangda release end --profile <name>`.
 - Account/role/permission/RBAC/organization-account/query-param authorization work must run `openxiangda design gates --topic permissions --json`, choose `managed-platform-account`, `existing-platform-user-assignment`, `static-role-permission`, or `query-param-context`, and write the permission matrix.
 - Roles that create roles, assign members, grant API permissions, maintain permission groups, or manage organization accounts must declare `apiPermissionCodes`, such as `app:role:manage`, `app:page-permission-group:manage`, `app:form-permission-group:manage`, and `app:organization:manage`.
 - `src/resources/**` is the resource source of truth; use `validate -> plan -> publish`.
+- Select logical resource codes with `--only`, or one code with `--code`; type-wide/app-wide release requires an approved dependency closure.
+- Source-triggered Function/Automation publishing uses server-side source-field PATCH and preserves online bindings, contracts, metadata, trigger/view configuration, and enabled/published state. Whole-manifest replacement requires `--replace-manifest --reason "..."`. On `SOURCE_BASE_DIVERGED` or `RESOURCE_FIELD_CONFLICT`, reconcile, rebuild, and re-plan.
 - React routes live in `src/app/router.tsx`; frontend artifacts are deployed with `openxiangda runtime deploy`.
 - Use `AttachmentField` / `ImageField` for form-context previews, and `AttachmentPreviewList` / `ImagePreviewGrid` / `useFilePreview` for standalone custom pages. Do not fake form context, import internal preview implementations, or maintain local previewable-extension lists.
 - Backend permissions, public-access grants, and App Function role/scope checks are authoritative.
@@ -36,6 +42,7 @@ This is an OpenXiangda React SPA workspace. See [AGENTS.md](mdc:AGENTS.md) for f
 
 - Do not run `lowcode-workspace publish-all`, `pnpm publish:all`, or `pnpm openxiangda:publish` directly.
 - Do not deploy without `--profile`.
+- Do not hot-patch a temporary release copy or activate a Runtime built from an unmerged task branch.
 - Do not use legacy `?publicAccess=guest`, `isRenderNav`, or workbench page parameters for new React SPA routes.
 - Do not rely on frontend-only button hiding, query-param checks, hardcoded roles, mock permissions, fake account IDs, or `PermissionBoundary` alone for real authorization.
 - Do not assign a business admin role without the role-setting API permissions needed for role/member management.

package/templates/openxiangda-react-spa/.qoder/rules/openxiangda-resources.md

@@ -11,9 +11,10 @@ You are editing engineering-managed resource manifests under `src/resources/`. L
 ## Commands
 
 ```bash
-openxiangda resource validate --profile <name>
-openxiangda resource plan --profile <name>
-openxiangda resource publish --profile <name>
+openxiangda resource validate <type> --only <codes> --profile <name>
+openxiangda resource plan <type> --only <codes> --profile <name>
+openxiangda resource publish <type> --only <codes> --profile <name>
+# one target: replace --only <codes> with --code <code>
 openxiangda resource typegen --profile <name>
 ```
 
@@ -23,3 +24,6 @@ openxiangda resource typegen --profile <name>
 - Guest access to forms, dataViews, functions, and connectors requires explicit policy `grants`.
 - Connector secrets and third-party credentials belong in the platform backend, never in manifests or page source.
 - Formal changes should keep Git as the source of truth: edit manifests, validate, plan, then publish.
+- `resource plan` and publish dry-runs are GET/HEAD-only. On `READ_ONLY_AUTH_REQUIRED`, run `openxiangda auth refresh --profile <name>` or log in again before retrying; never refresh inside the plan.
+- Source-triggered Function/Automation publishing patches only source fields on the server and preserves online bindings/contracts/metadata/state. Whole-manifest replacement requires `--replace-manifest --reason "..."`.
+- Formal promotion runs `release begin --change` (freeze Git + remote baseline, preflight the complete set) through `release end`. Reconcile `SOURCE_BASE_DIVERGED` / `RESOURCE_FIELD_CONFLICT`; never retry an old full payload with a fresh revision.