openxiangda 1.0.189 → 1.0.191

package/lib/cli.js

@@ -2142,14 +2142,120 @@ function buildEnvironmentStatusDiff(status) {
   };
 }
 
-function readStudioGit(args) {
+function readStudioGit(args, cwd = process.cwd()) {
   const result = spawnSync('git', args, {
-    cwd: process.cwd(),
+    cwd,
     encoding: 'utf8',
+    timeout: 5000,
   });
   return result.status === 0 ? String(result.stdout || '').trim() : '';
 }
 
+function studioGitSnapshot() {
+  const porcelain = readStudioGit([
+    'status',
+    '--porcelain',
+    '--untracked-files=all',
+  ]);
+  const branch = readStudioGit(['branch', '--show-current']);
+  const commit = readStudioGit(['rev-parse', 'HEAD']);
+  const upstream = readStudioGit([
+    'rev-parse',
+    '--abbrev-ref',
+    '--symbolic-full-name',
+    '@{upstream}',
+  ]);
+  const upstreamCommit = upstream
+    ? readStudioGit(['rev-parse', upstream])
+    : '';
+  const upstreamParts = upstream.split('/');
+  const remoteName = upstreamParts.length > 1 ? upstreamParts[0] : '';
+  const upstreamBranch = upstreamParts.slice(1).join('/');
+  const remoteHeadCommit =
+    remoteName && upstreamBranch
+      ? readStudioGit([
+          'ls-remote',
+          '--heads',
+          remoteName,
+          `refs/heads/${upstreamBranch}`,
+        ]).split(/\s+/)[0] || ''
+      : '';
+  const aheadBehind = upstream
+    ? readStudioGit([
+        'rev-list',
+        '--left-right',
+        '--count',
+        `${upstream}...HEAD`,
+      ])
+        .split(/\s+/)
+        .map(value => Number(value))
+    : [];
+  const worktreePaths = readStudioGit(['worktree', 'list', '--porcelain'])
+    .split(/\r?\n/)
+    .filter(line => line.startsWith('worktree '))
+    .map(line => line.slice('worktree '.length))
+    .filter(Boolean);
+  const dirtyWorktrees = worktreePaths
+    .filter(worktreePath => path.resolve(worktreePath) !== process.cwd())
+    .filter(worktreePath =>
+      Boolean(
+        readStudioGit(
+          ['status', '--porcelain', '--untracked-files=all'],
+          worktreePath
+        )
+      )
+    );
+  const ahead = Number.isFinite(aheadBehind[1]) ? aheadBehind[1] : null;
+  const behind = Number.isFinite(aheadBehind[0]) ? aheadBehind[0] : null;
+  const authoritativeBranch = ['main', 'master'].includes(branch);
+  const upstreamMainline = /\/(?:main|master)$/.test(upstream);
+  const clean = !porcelain;
+  const mainlineAligned =
+    clean &&
+    authoritativeBranch &&
+    upstreamMainline &&
+    commit === upstreamCommit &&
+    commit === remoteHeadCommit &&
+    ahead === 0 &&
+    behind === 0 &&
+    dirtyWorktrees.length === 0;
+  return {
+    branch,
+    commit,
+    upstream: upstream || null,
+    upstreamCommit: upstreamCommit || null,
+    remoteHeadCommit: remoteHeadCommit || null,
+    ahead,
+    behind,
+    clean,
+    mainlineAligned,
+    dirtyWorktrees,
+    worktreeCount: worktreePaths.length,
+    changes: porcelain ? porcelain.split(/\r?\n/).slice(0, 50) : [],
+  };
+}
+
+function isProductionCommissioning(environment) {
+  const policy = environment?.sideEffectPolicy || {};
+  return (
+    policy.payments === 'deny' &&
+    policy.notifications === 'tester_allowlist' &&
+    policy.externalWrites === 'deny' &&
+    policy.publicIndexing === 'deny' &&
+    policy.organizationWrites === 'deny' &&
+    policy.scheduledAutomations === 'disabled' &&
+    policy.environmentBanner === true
+  );
+}
+
+function isDeploymentEvidenceValid(deployment, now = Date.now()) {
+  if (!deployment?.evidenceHash) return false;
+  const evidence = deployment.evidenceSummary;
+  if (!evidence || evidence.outcome !== 'passed') return false;
+  const validUntil = Date.parse(evidence.validUntil || '');
+  return Number.isFinite(validUntil) && validUntil > now;
+}
+
 async function studio(args) {
   const { flags } = parseArgs(args);
   const config = loadConfig();
@@ -2165,26 +2271,69 @@ async function studio(args) {
       state,
       state.currentTarget || 'preproduction'
     );
-    const remote = await requestWithAuth(
+    const remoteStatus = await requestWithAuth(
       config,
       selected.binding.profile,
       environmentSetApiPath(state.logicalApp.code, '/status')
     );
-    const porcelain = readStudioGit([
-      'status',
-      '--porcelain',
-      '--untracked-files=all',
-    ]);
+    const environments = await Promise.all(
+      (remoteStatus?.environments || []).map(async environment => {
+        const deploymentId = environment?.latestDeployment?.id;
+        if (!deploymentId) return environment;
+        try {
+          const latestDeployment = await requestWithAuth(
+            config,
+            selected.binding.profile,
+            applicationDeploymentApiPath(
+              state.logicalApp.code,
+              deploymentId
+            )
+          );
+          return { ...environment, latestDeployment };
+        } catch {
+          return environment;
+        }
+      })
+    );
+    const remote = { ...remoteStatus, environments };
+    const git = studioGitSnapshot();
+    const preproduction = environments.find(
+      environment => environment.kind === 'preproduction'
+    );
+    const production = environments.find(
+      environment => environment.kind === 'production'
+    );
+    const drift = buildEnvironmentStatusDiff(remote).drift;
+    const evidenceValid = isDeploymentEvidenceValid(
+      preproduction?.latestDeployment
+    );
+    const productionCommissioning =
+      isProductionCommissioning(production);
+    const candidateReady = git.mainlineAligned;
+    const testRegistrationReady = Boolean(
+      preproduction?.latestDeployment?.id &&
+        preproduction.latestDeployment.status !== 'failed'
+    );
+    const promotionReady =
+      candidateReady &&
+      productionCommissioning &&
+      evidenceValid &&
+      preproduction?.latestDeployment?.status === 'succeeded' &&
+      Boolean(preproduction.latestDeployment.candidateId);
     return {
       workspace: process.cwd(),
       logicalApp: state.logicalApp,
       currentTarget: state.currentTarget,
       targets: state.targets,
-      git: {
-        branch: readStudioGit(['branch', '--show-current']),
-        commit: readStudioGit(['rev-parse', 'HEAD']),
-        clean: !porcelain,
-        changes: porcelain ? porcelain.split(/\r?\n/).slice(0, 50) : [],
+      git,
+      drift,
+      deliveryGates: {
+        candidateReady,
+        evidenceValid,
+        productionCommissioning,
+        promotionReady,
+        rollbackReady: Boolean(production?.heads?.appReleaseId),
+        testRegistrationReady,
       },
       openxiangdaVersion: CURRENT_VERSION,
       remote,

package/lib/developer-center.js

@@ -60,7 +60,7 @@ function studioHtml(sessionToken) {
     .pre{--accent:var(--pre)}.prod{--accent:var(--prod)}.card-head{display:flex;justify-content:space-between;align-items:center;margin-bottom:22px}
     h2{font-size:19px;margin:0}.badge{border:1px solid color-mix(in srgb,var(--accent) 45%,var(--line));color:var(--accent);padding:5px 9px;border-radius:999px;font-size:11px;letter-spacing:.08em}
     dl{display:grid;grid-template-columns:130px 1fr;gap:11px;margin:0;font-size:13px}dt{color:var(--muted)}dd{margin:0;font-family:ui-monospace,SFMono-Regular,monospace;overflow-wrap:anywhere}
-    .wide{grid-column:1/-1}.toolbar{display:flex;flex-wrap:wrap;gap:10px;margin-top:20px}button{appearance:none;border:1px solid #3a3d36;background:#22241f;color:#f4f4ef;padding:10px 14px;border-radius:10px;font-weight:600;cursor:pointer}
+    .wide{grid-column:1/-1}.toolbar{display:flex;flex-wrap:wrap;gap:10px;margin-top:20px}.gate-ok{color:var(--prod)}.gate-bad{color:var(--bad)}button{appearance:none;border:1px solid #3a3d36;background:#22241f;color:#f4f4ef;padding:10px 14px;border-radius:10px;font-weight:600;cursor:pointer}
     button:hover{border-color:#777c70}button.primary{background:#e9efe9;color:#111;border-color:#e9efe9}button.danger{color:#ffaaa3;border-color:#70423e}
     button:disabled{opacity:.4;cursor:not-allowed}.status{display:flex;gap:8px;align-items:center;color:var(--muted);font-size:13px}.dot{width:8px;height:8px;border-radius:50%;background:var(--prod);box-shadow:0 0 14px var(--prod)}
     pre{white-space:pre-wrap;word-break:break-word;background:#10110f;border:1px solid #252722;border-radius:12px;padding:16px;color:#c7cbc2;max-height:300px;overflow:auto;font:12px/1.55 ui-monospace,SFMono-Regular,monospace}
@@ -76,6 +76,7 @@ function studioHtml(sessionToken) {
   <section class="grid">
     <article class="card env pre"><div class="card-head"><h2>预发环境</h2><span class="badge">PREPRODUCTION</span></div><dl id="pre"></dl></article>
     <article class="card env prod"><div class="card-head"><h2>正式环境</h2><span class="badge">PRODUCTION</span></div><dl id="prod"></dl></article>
+    <article class="card wide"><div class="card-head"><h2>交付门禁与环境差异</h2><span class="badge" id="gate-badge">CHECKING</span></div><dl id="gates"></dl></article>
     <article class="card wide"><div class="card-head"><h2>交付状态</h2><div class="status"><span class="dot"></span><span id="health">连接中</span></div></div><div class="toolbar">
       <button data-action="candidate">生成候选</button><button data-action="deploy">部署预发</button><button data-action="test">登记测试证据</button><button class="primary" data-action="promote">晋级正式</button><button class="danger" data-action="rollback">准备回退</button><button data-action="refresh">刷新</button>
     </div><pre id="output">Developer Center 只监听 127.0.0.1；所有动作复用 OpenXiangda CLI 门禁。</pre></article>
@@ -87,9 +88,11 @@ const token=${token}; history.replaceState(null,"",location.pathname);
 const out=document.querySelector("#output"), dialog=document.querySelector("#dialog");
 let status=null, pending=null;
 const esc=v=>String(v??"-").replace(/[&<>"']/g,c=>({"&":"&amp;","<":"&lt;",">":"&gt;","\\"":"&quot;","'":"&#39;"}[c]));
-const rows=e=>[["appType",e?.appType],["公开地址",e?.publicOrigin],["AppRelease",e?.heads?.appReleaseId],["候选版本",e?.latestDeployment?.candidateId],["部署状态",e?.latestDeployment?.status],["副作用策略",JSON.stringify(e?.sideEffectPolicy||{})]].map(([k,v])=>\`<dt>\${esc(k)}</dt><dd>\${esc(v)}</dd>\`).join("");
+const rows=e=>[["appType",e?.appType],["环境修订",e?.revision],["公开地址",e?.publicOrigin],["AppRelease",e?.heads?.appReleaseId],["RuntimeRelease",e?.heads?.runtimeReleaseId],["BackendRelease",e?.heads?.backendReleaseId],["PageRelease",e?.heads?.pageReleaseId],["WorkflowRelease",e?.heads?.workflowReleaseId],["候选版本",e?.latestDeployment?.candidateId],["Deployment",e?.latestDeployment?.id],["部署状态",e?.latestDeployment?.status],["测试证据",e?.latestDeployment?.evidenceHash],["证据有效期",e?.latestDeployment?.evidenceSummary?.validUntil],["副作用策略",JSON.stringify(e?.sideEffectPolicy||{})]].map(([k,v])=>\`<dt>\${esc(k)}</dt><dd>\${esc(v)}</dd>\`).join("");
+const bool=v=>\`<span class="\${v?"gate-ok":"gate-bad"}">\${v?"通过":"阻断"}</span>\`;
+const gateRows=s=>[["权威主线",s?.git?.upstream||"-"],["远端主线提交",s?.git?.remoteHeadCommit],["ahead / behind",\`\${s?.git?.ahead??"-"} / \${s?.git?.behind??"-"}\`],["工作区干净",bool(Boolean(s?.git?.clean))],["其他脏 worktree",s?.git?.dirtyWorktrees?.length?s.git.dirtyWorktrees.join(", "):bool(true)],["Candidate 门禁",bool(Boolean(s?.deliveryGates?.candidateReady))],["预发测试证据",bool(Boolean(s?.deliveryGates?.evidenceValid))],["正式 commissioning",bool(Boolean(s?.deliveryGates?.productionCommissioning))],["同一 AppRelease",bool(Boolean(s?.drift?.sameAppRelease))],["资源差异",s?.drift?.sameAppRelease?"无":"存在（预发/正式 Release Head 不同）"],["OpenXiangda",s?.openxiangdaVersion]].map(([k,v])=>\`<dt>\${esc(k)}</dt><dd>\${typeof v==="string"&&v.startsWith("<span")?v:esc(v)}</dd>\`).join("");
 async function api(path,options={}){const r=await fetch(path,{...options,headers:{"content-type":"application/json","x-openxiangda-studio-token":token,...options.headers}});const j=await r.json();if(!r.ok)throw new Error(j.message||"request failed");return j}
-async function refresh(){try{status=await api("/api/status");document.querySelector("#repo").textContent=\`\${status.git?.branch||"-"} @ \${(status.git?.commit||"-").slice(0,12)} · \${status.git?.clean?"clean":"dirty"}\`;document.querySelector("#pre").innerHTML=rows(status.remote?.environments?.find(e=>e.kind==="preproduction"));document.querySelector("#prod").innerHTML=rows(status.remote?.environments?.find(e=>e.kind==="production"));document.querySelector("#health").textContent="状态已同步";}catch(e){document.querySelector("#health").textContent="读取失败";out.textContent=e.message}}
+async function refresh(){try{status=await api("/api/status");document.querySelector("#repo").textContent=\`\${status.git?.branch||"-"} @ \${(status.git?.commit||"-").slice(0,12)} · \${status.git?.mainlineAligned?"mainline ready":status.git?.clean?"clean / not aligned":"dirty"}\`;document.querySelector("#pre").innerHTML=rows(status.remote?.environments?.find(e=>e.kind==="preproduction"));document.querySelector("#prod").innerHTML=rows(status.remote?.environments?.find(e=>e.kind==="production"));document.querySelector("#gates").innerHTML=gateRows(status);const ready=Boolean(status.deliveryGates?.candidateReady);const badge=document.querySelector("#gate-badge");badge.textContent=ready?"READY":"BLOCKED";badge.className=\`badge \${ready?"gate-ok":"gate-bad"}\`;document.querySelector('[data-action="candidate"]').disabled=!ready;document.querySelector('[data-action="deploy"]').disabled=!ready;document.querySelector('[data-action="test"]').disabled=!status.deliveryGates?.testRegistrationReady;document.querySelector('[data-action="promote"]').disabled=!status.deliveryGates?.promotionReady;document.querySelector('[data-action="rollback"]').disabled=!status.deliveryGates?.rollbackReady;document.querySelector("#health").textContent="状态已同步";}catch(e){document.querySelector("#health").textContent="读取失败";out.textContent=e.message}}
 document.querySelectorAll("[data-action]").forEach(b=>b.onclick=()=>{pending=b.dataset.action;if(pending==="refresh")return refresh();document.querySelector("#dialog-title").textContent=b.textContent;document.querySelector("#value").value="";document.querySelector("#details").value=pending==="test"?JSON.stringify({outcome:"passed",requiredGates:["static","schema","appFunctions","roles","browser","lifecycle","cleanup"],results:{static:{status:"passed"},schema:{status:"passed"},appFunctions:{status:"passed"},roles:{status:"passed"},browser:{status:"passed"},lifecycle:{status:"passed"},cleanup:{status:"passed"}},cleanup:{passed:true,residueCount:0}},null,2):"";dialog.showModal()});
 document.querySelector("#confirm").onclick=async e=>{e.preventDefault();const action=pending;dialog.close();out.textContent="执行中…";try{const result=await api("/api/action",{method:"POST",body:JSON.stringify({action,value:document.querySelector("#value").value,details:document.querySelector("#details").value,confirmProduction:["promote","rollback"].includes(action)})});out.textContent=JSON.stringify(result,null,2);await refresh()}catch(error){out.textContent=error.message}};
 refresh();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openxiangda",
-  "version": "1.0.189",
+  "version": "1.0.191",
   "description": "OpenXiangda CLI, workspace build tools, runtime SDK, and form components.",
   "private": false,
   "bin": {
@@ -111,6 +111,7 @@
     "test:page-release-cli": "node scripts/page-release-cli-smoke.mjs",
     "test:app-release-cli": "node scripts/app-release-cli-smoke.mjs",
     "test:application-environments": "node scripts/application-environments-smoke.mjs",
+    "test:developer-center": "node scripts/developer-center-smoke.mjs",
     "test:form-release-cas": "node scripts/form-release-cas-smoke.mjs",
     "test:source-dependencies": "node scripts/source-dependencies-smoke.mjs",
     "test:form-field-contract": "node scripts/form-field-contract-smoke.mjs",

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

@@ -0,0 +1,24 @@
+---
+description: src/forms/** — Use openxiangda-form skill
+globs: src/forms/**/*
+alwaysApply: false
+---
+
+# OpenXiangda React SPA Form Files
+
+Editing `src/forms/<formCode>/`. Use the **`openxiangda-form`** skill.
+
+- Keep field/schema rules in `schema.ts` and presentation in `page.tsx`.
+- Prefer OpenXiangda platform fields, then `antd` / `antd-mobile`; do not use native inputs, hand-written uploaders, pickers, or user/department selectors.
+- Option fields require non-empty `options`; linked data uses `SelectField` with `optionSource.type: "linkedForm"`.
+- Top-level `schema.rules` is only for `FormEffect[]`; validation belongs to field `rules`.
+- Do not recreate platform system fields. Use `behavior: "HIDDEN"` + `valueSync` for derived or permission keys.
+
+Release with exact scope:
+
+```bash
+openxiangda resource plan form-setting --only <formCode> --profile <name>
+openxiangda resource publish form-setting --only <formCode> --change <change> --profile <name>
+```
+
+Managed production activation only occurs through candidate → preproduction deploy/test → promotion of the same candidate.

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

@@ -0,0 +1,25 @@
+---
+description: src/pages/** — Use openxiangda-page skill
+globs: src/pages/**/*
+alwaysApply: false
+---
+
+# OpenXiangda React SPA Page Files
+
+Editing `src/pages/`. Use the **`openxiangda-page`** skill.
+
+- Keep routes in `src/app/router.tsx` and navigation in `src/app/navigation.ts`.
+- Split complex pages into thin views, `domain/`, `shared/{services,hooks}/`, `components/`, and styles.
+- Use server pagination and structured `filterGroup`; never fetch an oversized page and filter in the browser.
+- Prefer OpenXiangda platform components for platform data fields and `antd` / `antd-mobile` for ordinary UI.
+- Do not use native form controls, hand-written pickers/uploaders, or frontend-only authorization.
+
+Build and stage:
+
+```bash
+pnpm typecheck
+pnpm build
+openxiangda runtime deploy --no-activate --change <change> --profile <name>
+```
+
+Managed production activation only occurs through candidate → preproduction deploy/test → promotion of the same candidate.

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

@@ -0,0 +1,26 @@
+---
+description: src/{workflows,automations,js-code-nodes,functions}/** — Use openxiangda-workflow-automation skill
+globs: src/{workflows,automations,js-code-nodes,functions}/**/*
+alwaysApply: false
+---
+
+# OpenXiangda React SPA Workflow / Automation / Function Files
+
+Use the **`openxiangda-workflow-automation`** skill for workflows, automations, JS_CODE, and App Functions.
+
+- Ordinary lifecycle state changes use a status field, domain state machine, and automation; create workflows only for real approval semantics.
+- Prefer App Functions for reusable backend logic. JS_CODE is for cross-form, batch, process, platform API, external HTTP, and complex orchestration.
+- Keep UI interactions, normal validation, and display logic in React.
+- Log important backend steps with `ctx.logger`; obtain third-party credentials only through declared `secretRefs`.
+- Never copy workflow, automation, or function IDs across profiles.
+
+Build and release with exact scope:
+
+```bash
+pnpm typecheck:js-code
+pnpm build-js-code --script <code>
+openxiangda resource plan <workflow|automation|function> --only <code> --profile <name>
+openxiangda resource publish <workflow|automation|function> --only <code> --change <change> --profile <name>
+```
+
+Managed production activation only occurs through candidate → preproduction deploy/test → promotion of the same candidate.

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

@@ -0,0 +1,37 @@
+---
+description: src/forms/** glob — 精准引导到 openxiangda-form skill
+glob: src/forms/**/*
+alwaysApply: false
+---
+
+# OpenXiangda React SPA Form Files
+
+You are editing files under `src/forms/<formCode>/`. Use the **`openxiangda-form`** skill.
+
+## Required structure
+
+```text
+src/forms/<formCode>/
+├── schema.ts   # defineFormSchema() default export
+└── page.tsx    # presentation only
+```
+
+## Common pitfalls
+
+- 平台字段组件优先于 `antd` / `antd-mobile` 包装和自定义业务组件。
+- `schema.ts` 定义字段、选项、规则与行为；`page.tsx` 只负责展示。
+- 禁止直接写原生 `<input>` / `<select>` / `<textarea>` / file input，禁止手写人员、部门、上传和 picker 组件。
+- 选项字段必须提供非空 `options`；跨表数据使用 `SelectField` + `optionSource.type: "linkedForm"`。
+- 顶层 `schema.rules` 只用于 `FormEffect[]`；字段校验放字段自己的 `rules`。
+- 平台系统字段由平台维护，不要重复创建。
+- 派生键和隐式权限键使用 `behavior: "HIDDEN"` + `valueSync`。
+
+## Release
+
+```bash
+openxiangda resource validate form-setting --only <formCode> --profile <name>
+openxiangda resource plan form-setting --only <formCode> --profile <name>
+openxiangda resource publish form-setting --only <formCode> --change <change> --profile <name>
+```
+
+正式环境托管发布仍必须走 candidate → preproduction deploy/test → 同 candidate promotion，禁止直接激活生产资源。

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

@@ -0,0 +1,29 @@
+---
+description: src/pages/** glob — 精准引导到 openxiangda-page skill
+glob: src/pages/**/*
+alwaysApply: false
+---
+
+# OpenXiangda React SPA Page Files
+
+You are editing files under `src/pages/`. Use the **`openxiangda-page`** skill.
+
+## Strong defaults
+
+- 路由集中维护在 `src/app/router.tsx`，应用导航维护在 `src/app/navigation.ts`。
+- 复杂页面拆分为薄视图、`domain/`、`shared/{services,hooks}/`、`components/` 和样式文件。
+- 默认使用原生 Tailwind utilities，不使用未配置的 shadcn token。
+- 列表必须服务端分页并使用结构化 `filterGroup`；禁止抓取超大页后在浏览器过滤。
+- 平台数据字段优先使用 OpenXiangda 平台组件；普通 UI 使用 `antd` / `antd-mobile`。
+- 禁止原生表单控件、手写 picker/uploader/人员部门选择器。
+- 后端权限、公开访问 grants 与 App Function 检查才是授权依据；前端只做展示保护。
+
+## Release
+
+```bash
+pnpm typecheck
+pnpm build
+openxiangda runtime deploy --no-activate --change <change> --profile <name>
+```
+
+Runtime 只暂存到候选发布；正式环境托管发布必须走 candidate → preproduction deploy/test → 同 candidate promotion。

package/templates/openxiangda-react-spa/.qoder/rules/openxiangda-workflow-automation.md

@@ -0,0 +1,34 @@
+---
+description: src/{workflows,automations,js-code-nodes,functions}/** glob — 精准引导到 openxiangda-workflow-automation skill
+glob: src/{workflows,automations,js-code-nodes,functions}/**/*
+alwaysApply: false
+---
+
+# OpenXiangda React SPA Workflow / Automation / Function Files
+
+Use the **`openxiangda-workflow-automation`** skill when editing:
+
+- `src/workflows/<code>/workflow.ts`
+- `src/automations/<code>/index.ts`
+- `src/js-code-nodes/<code>/index.ts`
+- `src/functions/<code>/index.ts`
+
+## Boundaries
+
+- 普通 `pending → processing → resolved → closed` 使用状态字段、领域状态机与 automation；只有真实审批语义才创建 workflow。
+- 复用后端业务逻辑优先 App Function；JS_CODE 用于跨表、批量、流程、平台 API、外部 HTTP 与复杂编排。
+- UI 交互、普通表单校验和展示逻辑留在 React 代码，不放进 JS_CODE。
+- 每个关键步骤使用 `ctx.logger.debug/info/warn/error`；第三方凭据只通过 `secretRefs` 与 `ctx.secrets.get()` 获取。
+- workflowId / automationId / functionId 不得跨 profile 复制。
+
+## Build and release
+
+```bash
+pnpm typecheck:js-code
+pnpm build-js-code --script <code>
+openxiangda resource validate <workflow|automation|function> --only <code> --profile <name>
+openxiangda resource plan <workflow|automation|function> --only <code> --profile <name>
+openxiangda resource publish <workflow|automation|function> --only <code> --change <change> --profile <name>
+```
+
+资源发布只生成候选子版本；正式环境托管发布必须走 candidate → preproduction deploy/test → 同 candidate promotion。

package/templates/openxiangda-react-spa/scripts/guard-publish.mjs

@@ -9,7 +9,7 @@ const lines = [
   '  openxiangda resource publish <type> --only <codes> --change <change> --profile <name>',
   '  openxiangda runtime deploy --no-activate --change <change> --profile <name>',
   '',
-  '正式激活后还必须 merge/push 冻结 SHA，再执行 release integration-status 与 release end。',
+  '发布前必须先把批准的提交合并并 push 到权威主线；激活后直接执行 release integration-status 与 release end。',
   '',
   'legacy lowcode-workspace publish-all 只用于旧 classic workspace 的兼容流程。',
   '',