openxiangda 1.0.269 → 1.0.271

package/lib/design-gates.js

@@ -540,6 +540,23 @@ const RESOURCE_EXPLAINS = {
       'openxiangda function invoke summarize_customer --body-json \'{"input":{}}\'',
     ],
   },
+  webhook: {
+    dir: 'src/resources/webhooks/*.json',
+    minimalManifest: {
+      code: 'yuquan_access',
+      name: '玉泉门禁开门事件',
+      targetFunctionCode: 'qfyy_access_event',
+      idempotencyQueryParam: 'nonce',
+      maxBodyBytes: 262144,
+      status: 'active',
+    },
+    commands: [
+      'openxiangda resource validate webhook --profile <name>',
+      'openxiangda resource plan webhook --only yuquan_access --profile <name> --json',
+      'openxiangda resource publish webhook --only yuquan_access --change <id> --profile <name>',
+      'openxiangda webhook deliveries yuquan_access --profile <name> --json',
+    ],
+  },
   connector: {
     dir: 'src/resources/connectors/*.json',
     minimalManifest: {
@@ -633,6 +650,7 @@ function getResourceExplain(type) {
     auth: 'auth-config',
     authconfigs: 'auth-config',
     functions: 'function',
+    webhooks: 'webhook',
     connectors: 'connector',
   };
   const key = aliases[rawKey] || rawKey;

package/lib/release-plan.js

@@ -102,6 +102,7 @@ const DIRECT_RESOURCE_TYPE_BY_KEY = Object.freeze({
   menus: 'menu',
   dataViews: 'data-view',
   storageConfigs: 'storage',
+  webhooks: 'webhook',
   authConfigs: 'auth-config',
   routes: 'route',
   publicAccessPolicies: 'public-access',
@@ -116,6 +117,7 @@ const DIRECT_RESOURCE_RELEASE_ORDER = Object.freeze([
   'roles',
   'connectors',
   'storageConfigs',
+  'webhooks',
   'authConfigs',
   'routes',
   'publicAccessPolicies',
@@ -168,10 +170,14 @@ function commandFromArgs(args) {
 }
 
 function createStep(id, args, options = {}) {
+  const env = options.env && Object.keys(options.env).length > 0
+    ? { env: { ...options.env } }
+    : {};
   return {
     id,
     args,
     command: commandFromArgs(args),
+    ...env,
     writes: options.writes !== false,
     stagedKind: options.stagedKind || null,
     resumeMode: options.resumeMode || 'skip',
@@ -327,8 +333,7 @@ function buildWorkspaceReleaseSteps(
     targets.resourceSelectors?.formPermissionGroups || []
   );
   const stagesFormRelease =
-    runtimeMode === 'react-spa' &&
-    (targets.forms.length > 0 || formPermissionGroups.length > 0);
+    targets.forms.length > 0 || formPermissionGroups.length > 0;
   const deferredDataViewCodes = stagesFormRelease
     ? uniqueSorted(targets.resourceSelectors?.dataViews || [])
     : [];
@@ -345,58 +350,59 @@ function buildWorkspaceReleaseSteps(
         excludeTypes: stagesFormRelease ? ['formPermissionGroups'] : [],
       }
     );
-  if (runtimeMode === 'react-spa') {
-    const ensuredForms = uniqueSorted([
-      ...targets.forms,
-      ...targets.formDependencies,
-    ]);
-    if (ensuredForms.length > 0) {
-      steps.push(
-        createStep(
-          'form-ensure',
-          appendProfileAndChange(
-            ['form', 'ensure', '--only', ensuredForms.join(',')],
-            profileArg,
-            changeId
-          ),
-          { resumeMode: 'replay-local' }
-        )
-      );
-    }
-    if (stagesFormRelease) {
-      const resourceTypes = [
-        ...(targets.forms.length > 0 ? ['form-setting'] : []),
-        ...(formPermissionGroups.length > 0
-          ? ['form-permission-group']
-          : []),
-      ];
-      const qualify = resourceTypes.length > 1;
-      const selectors = [
-        ...targets.forms.map(code =>
-          qualify ? `form-setting:${code}` : code
+  const ensuredForms = uniqueSorted([
+    ...targets.forms,
+    ...targets.formDependencies,
+  ]);
+  if (ensuredForms.length > 0) {
+    steps.push(
+      createStep(
+        'form-ensure',
+        appendProfileAndChange(
+          ['form', 'ensure', '--only', ensuredForms.join(',')],
+          profileArg,
+          changeId
         ),
-        ...formPermissionGroups.map(code =>
-          qualify ? `form-permission-group:${code}` : code
+        { resumeMode: 'replay-local' }
+      )
+    );
+  }
+  if (stagesFormRelease) {
+    const resourceTypes = [
+      ...(targets.forms.length > 0 ? ['form-setting'] : []),
+      ...(formPermissionGroups.length > 0
+        ? ['form-permission-group']
+        : []),
+    ];
+    const qualify = resourceTypes.length > 1;
+    const selectors = [
+      ...targets.forms.map(code =>
+        qualify ? `form-setting:${code}` : code
+      ),
+      ...formPermissionGroups.map(code =>
+        qualify ? `form-permission-group:${code}` : code
+      ),
+    ];
+    steps.push(
+      createStep(
+        'form-stage',
+        appendProfileAndChange(
+          [
+            'resource',
+            'publish',
+            resourceTypes.join(','),
+            '--only',
+            selectors.join(','),
+          ],
+          profileArg,
+          changeId
         ),
-      ];
-      steps.push(
-        createStep(
-          'form-stage',
-          appendProfileAndChange(
-            [
-              'resource',
-              'publish',
-              resourceTypes.join(','),
-              '--only',
-              selectors.join(','),
-            ],
-            profileArg,
-            changeId
-          ),
-          { stagedKind: 'FormRelease' }
-        )
-      );
-    }
+        { stagedKind: 'FormRelease' }
+      )
+    );
+  }
+
+  if (runtimeMode === 'react-spa') {
     steps.push(...directConfigurationSteps);
     if (hasResourceTargets) {
       steps.push(
@@ -464,10 +470,13 @@ function buildWorkspaceReleaseSteps(
     return steps;
   }
 
-  const onlyTargets = [
-    ...targets.forms.map(code => `forms/${code}`),
-    ...targets.pages.map(code => `pages/${code}`),
-  ];
+  if (hasResourceTargets) {
+    steps.push(...directConfigurationSteps);
+    steps.push(
+      ...buildTargetedResourceReleaseSteps(targets, profileArg, changeId)
+    );
+  }
+  const onlyTargets = targets.pages.map(code => `pages/${code}`);
   if (onlyTargets.length > 0) {
     steps.push(
       createStep(
@@ -482,17 +491,17 @@ function buildWorkspaceReleaseSteps(
           ],
           profileArg,
           changeId
-        )
+        ),
+        {
+          stagedKind: 'PageRelease',
+          env: { OPENXIANGDA_PAGE_STAGE_ONLY: '1' },
+        }
       )
     );
   }
-  if (hasResourceTargets) {
-    steps.push(...directConfigurationSteps);
-    steps.push(
-      ...buildTargetedResourceReleaseSteps(targets, profileArg, changeId)
-    );
-  }
   if (
+    stagesFormRelease ||
+    targets.pages.length > 0 ||
     targets.functions.length > 0 ||
     targets.automations.length > 0 ||
     targets.workflows.length > 0
@@ -506,6 +515,12 @@ function buildWorkspaceReleaseSteps(
             'app-finalize',
             '--staged-resources-json',
             `.openxiangda/releases/${changeId || 'change'}/staged-resources.json`,
+            ...(deferredDataViewCodes.length > 0
+              ? [
+                  '--finalize-data-views',
+                  deferredDataViewCodes.join(','),
+                ]
+              : []),
             '--wait',
           ],
           profileArg,

package/openxiangda-skills/SKILL.md

@@ -167,7 +167,7 @@ When the sealed Runtime source intentionally does not descend from the active Ru
 
 `resource plan` and publish dry-runs are strictly GET/HEAD-only. `READ_ONLY_AUTH_REQUIRED` means the access token expired; run `openxiangda auth refresh --profile <name>` or log in again before retrying. Never add an automatic refresh POST inside a plan.
 
-`release publish` is the default promotion entrypoint only for legacy unmanaged workspaces. It verifies without rewriting reviewed `change.json`/`release.json`, waits for the app lease, freezes the App capture after ownership is acquired, executes deterministic exact staged steps, resumes from `.openxiangda/releases/<change>/execution.json`, atomically finalizes, verifies mainline integration, and releases the lease. When the same audited historical-lineage condition applies, legacy `release publish` accepts `--adopt-online-baseline --adoption-reason "..."` and forwards the pair only to exact `resource publish --only/--code` stages; missing reasons or plans without an exact resource stage fail before lease acquisition. Environment-managed applications use the two-phase `release ship`; candidate/deploy/test/fail/promote, `release begin`, and child commands remain recovery/diagnostic primitives.
+`release publish` is the default promotion entrypoint only for legacy unmanaged workspaces. It verifies without rewriting reviewed `change.json`/`release.json`, waits for the app lease, freezes the App capture after ownership is acquired, executes deterministic exact staged steps, resumes from `.openxiangda/releases/<change>/execution.json`, atomically finalizes, verifies mainline integration, and releases the lease. Legacy Page steps receive `OPENXIANGDA_PAGE_STAGE_ONLY=1`; the step environment and staged kind are hashed and journaled, and missing PageRelease evidence blocks Root finalize. Custom page publishers must honor that environment and call the current package CLI so `page publish` records the staged child. When the same audited historical-lineage condition applies, legacy `release publish` accepts `--adopt-online-baseline --adoption-reason "..."` and forwards the pair only to exact `resource publish --only/--code` stages. An intentional manifest replacement may add `--replace-manifest --reason "..."`; the inseparable pair reaches only the unique exact Backend stage. Missing reasons or compatible exact scopes fail before lease acquisition. Environment-managed applications use the two-phase `release ship`; candidate/deploy/test/fail/promote, `release begin`, and child commands remain recovery/diagnostic primitives.
 
 Reviewed bundle commands may retain `<profile>` as a template. The explicit real `release publish --profile <name>` value is bound to actual child argv without rewriting tracked SDD. React SPA page codes are logical coverage targets and activate through one Runtime child; they do not require PageRelease. `release app-head` and `runtime releases` are compact by default; use `--full` only when the complete manifest is required.
 
@@ -189,6 +189,8 @@ Treat resource declarations as environment mapping and release-observability met
 
 An App Function may declare metadata-only top-level `secretRefs: [{ name, required }]` only with `function_v2` + `trusted_node_v2`; source resolves values with `await ctx.secrets.get(name)` and uses `ctx.utils.http` for controlled public HTTPS. Create/rotate values through hidden TTY or `openxiangda secret ... --value-stdin --change <change> --profile <name>`. Never put values in arguments, files, manifests, state, plans, logs, errors, or chat. Secret bindings require `backend_release_v2` and whole-app `atomic_staged_children_v2`; a missing capability is fail-closed and never uses the legacy source PATCH. For whole-app activation use exact-scope `resource publish <type> --only <code> --stage-only`, then pass the returned verified `stagedResource` to `release app-finalize`; an active Backend Release is never labeled staged.
 
+Inbound third-party callbacks use `src/resources/webhooks/<code>.json` and the public path returned after publish. A Webhook binds one fixed same-app Function; it never stores Secret values or provider signature rules. The Function reads the exact `input.rawBody`, verifies before any data/helper/network call, and protects business writes with `input.idempotencyKey`. Use `openxiangda webhook deliveries|delivery` for receipts and read `references/webhooks.md` through the workflow-automation skill for the full contract.
+
 The lease is app-level promotion ownership, while worktree ownership prevents two Codex tasks from editing through the same source directory. Different worktrees may keep developing and validating; only the clean synchronized main checkout publishes. Use full resource/runtime publish only when the approved bundle intentionally covers the whole dependency closure.
 
 ## Always

package/openxiangda-skills/references/notifications.md

@@ -1,8 +1,8 @@
 # Notification Resources
 
-Use notification resources when a page, workflow, or automation needs reusable message templates.
+Use notification resources when an App Function, workflow, or automation needs reusable message templates.
 
-AI generation rule: declare notification resources first, then call `sdk.notification` in code pages or `ctx.notification` in JS_CODE. Do not hardcode `/api/notification-config/*` or store channel credentials in source.
+AI generation rule: declare notification resources first, then send only from trusted runtime code through `ctx.notification`. Code pages call a named App Function with a business identifier through `sdk.function.invoke`; they never choose effective recipients, rendered content, or channels. Do not hardcode `/api/notification-config/*` or store channel credentials in source.
 
 ## Resource Files
 
@@ -135,21 +135,35 @@ Standard card payload variables include `title`, `lastMessage`, `content`, `cont
 
 ## Runtime Calls
 
-Code pages:
+Code pages invoke a named business action. Pass business identifiers, not an
+effective recipient, rendered message, or channel list:
 
 ```ts
-await sdk.notification.sendByType({
-  notificationType: "reservation_reminder",
-  recipientId: userId,
-  payload: {
-    title: "预约提醒",
-    instrumentName,
-    startTime,
-  },
+await sdk.function.invoke("send_reservation_reminder", {
+  input: { reservationId },
 });
 ```
 
-DingTalk-specific helpers are available when the caller wants to inspect or force the DingTalk channel:
+The App Function checks the operator and current reservation state, resolves the
+recipient and template variables from authoritative data, then sends through the
+trusted runtime bridge:
+
+```ts
+export default async function sendReservationReminder(ctx) {
+  const reservation = await loadAuthorizedReservation(ctx.input.reservationId, ctx);
+  await ctx.notification.sendByType({
+    notificationType: "reservation_reminder",
+    recipientId: reservation.ownerUserId,
+    payload: {
+      title: "预约提醒",
+      instrumentName: reservation.instrumentName,
+      startTime: reservation.startTime,
+    },
+  });
+}
+```
+
+DingTalk-specific read and preview helpers remain available to pages:
 
 ```ts
 const capabilities = await sdk.notification.capabilities();
@@ -161,13 +175,6 @@ const preview = await sdk.notification.previewDingTalk({
   },
 });
 
-await sdk.notification.sendDingTalk({
-  notificationType: "reservation_reminder",
-  recipientId: userId,
-  payload: {
-    title: "预约提醒",
-  },
-});
 ```
 
 User-facing in-app message centers should read the platform inbox instead of
@@ -198,12 +205,10 @@ openxiangda notification preview reservation_reminder --body-json '{"payload":{"
 openxiangda notification capabilities --json
 openxiangda notification dingding-preview reservation_reminder --body-json '{"payload":{"title":"测试"}}'
 openxiangda notification dingding-preview --template-code reservation_reminder --body-json '{"payload":{"title":"测试"}}'
-openxiangda notification dingding-send reservation_reminder --body-json '{"recipientId":"USER_ID","payload":{"title":"测试"}}' --force
-openxiangda notification send reservation_reminder --body-json '{"recipientId":"USER_ID","payload":{"title":"测试"}}' --force
-openxiangda notification batch-send reservation_reminder --body-json '{"recipients":[{"recipientId":"USER_ID","payload":{"title":"测试"}}]}' --force
+openxiangda function invoke send_reservation_reminder --body-json '{"input":{"reservationId":"RESERVATION_ID"}}'
 ```
 
-Automation or workflow JS_CODE:
+App Function, Automation, or workflow JS_CODE:
 
 ```ts
 export default async function notify(ctx) {

package/openxiangda-skills/references/openxiangda-api.md

@@ -344,38 +344,16 @@ Requires Bearer token. Updates menu sorting and parent relationships in batch.
 
 ### POST `/apps/:appType/notifications/send-by-type`
 
-Requires Bearer token. Sends a notification in the current app scope.
-Each returned message can include `deliveryMeta` with provider message id, outTrackId, card template id, fallback usage, and provider error summary.
-
-```json
-{
-  "notificationType": "reservation_reminder",
-  "recipientId": "user-id",
-  "payload": {
-    "title": "预约提醒"
-  },
-  "channels": ["inapp"]
-}
-```
+Removed. Always returns HTTP/envelope `410` with
+`DIRECT_NOTIFICATION_SEND_REMOVED`. Pages must invoke a named App Function;
+trusted runtime code sends through `ctx.notification` after business
+authorization and recipient resolution.
 
 ### POST `/apps/:appType/notifications/batch-send-by-type`
 
-Requires Bearer token. Sends one notification type to multiple recipients.
-
-```json
-{
-  "notificationType": "reservation_reminder",
-  "recipients": [
-    {
-      "recipientId": "user-id",
-      "payload": {
-        "title": "预约提醒"
-      },
-      "channels": ["inapp"]
-    }
-  ]
-}
-```
+Removed. Always returns HTTP/envelope `410` with
+`DIRECT_NOTIFICATION_SEND_REMOVED`. Batch recipient selection belongs in a
+bounded, authorized App Function, Workflow, Automation, or trusted JS_CODE.
 
 ### GET `/apps/:appType/notifications/templates`
 
@@ -426,7 +404,9 @@ or a direct DingTalk config:
 
 ### POST `/apps/:appType/notifications/dingtalk/send`
 
-Requires Bearer token. Sends the resolved `notificationType` through the DingTalk channel only. The CLI command is `openxiangda notification dingding-send <notificationType> --body-json '{"recipientId":"USER_ID","payload":{"title":"测试"}}' --force`.
+Removed. Always returns HTTP/envelope `410` with
+`DIRECT_NOTIFICATION_SEND_REMOVED`. The CLI command is also removed; use
+`openxiangda function invoke <functionCode>` for an authorized business action.
 
 ### GET `/apps/:appType/notifications/type-configs`
 
@@ -969,3 +949,15 @@ Requires Bearer token. Creates a short-lived signed OSS upload URL for browser d
 ### POST `/apps/:appType/storage-configs/:code/objects/delete`
 
 Requires Bearer token. Deletes an OSS object under the configured `pathPrefix`.
+## Inbound Webhook
+
+- Management: `GET|POST /openxiangda-api/v1/apps/:appType/webhooks`
+- Detail/update/disable: `GET|POST|PUT|DELETE /openxiangda-api/v1/apps/:appType/webhooks/:code`
+- Delivery list/detail: `GET /openxiangda-api/v1/apps/:appType/webhooks/:code/deliveries[/:deliveryId]`
+- Public callback: `POST /openxiangda-webhooks/v1/:endpointId`
+
+The public `endpointId` resolves tenant/application ownership and is never
+replaced with `appType`. Management calls use normal profile authentication;
+the public callback is unauthenticated at the platform edge and the target
+Function must verify the provider signature from the exact raw body. See
+`webhooks.md` for the declaration and runtime envelope.

package/openxiangda-skills/references/pages/page-sdk.md

@@ -15,7 +15,7 @@ Guidelines:
 - Use `sdk.dataSource.run()` with a page data source descriptor when the page config should own the data view code, default fields, or default filters.
 - Use `sdk.function.invoke(code, { input })` for reusable backend business logic declared under `src/resources/functions/` and `src/functions/`. Do not implement multi-form orchestration, connector fan-out, notification orchestration, or permission-sensitive backend rules directly in a page component.
 - Use `sdk.connector.invoke`, `sdk.connector.call("connector.api")`, or `sdk.connector.download` for external services. The SDK calls the platform runtime connector endpoint; it must not call third-party domains directly.
-- Use `sdk.notification.sendByType` and `batchSendByType` for reusable business messages. Custom notification types must be declared in `src/resources/notifications/` and published with `openxiangda resource publish`.
+- Pages must not send notifications directly. Use `sdk.function.invoke(code, { input })` with business identifiers; the named App Function performs authorization, resolves recipients and variables from authoritative data, and sends with trusted `ctx.notification`. Custom notification types must still be declared in `src/resources/notifications/` and published with `openxiangda resource publish`.
 - Use `sdk.export.create` and `sdk.export.get` for asynchronous XLSX exports. Simple pages may send a declarative workbook definition. Complex or reusable exports should send only a published App Function `definitionCode`, the current query snapshot, export scope, and stable selected row IDs. The server executes `structured_export_provider_v1` with fresh user permissions; never upload executable rendering code from the browser. See `docs/structured-export-v1.md`.
 - Use `AttachmentPreviewList`, `ImagePreviewGrid`, or `useFilePreview` from `openxiangda/runtime/react` for in-page attachment previews in a custom React SPA page. They use the current PageSdk context and enforce the platform capability and ticket contracts. Use `sdk.createFileAccessTicket(bucketName, objectName, fileName, "preview", { appType })` only when the page needs a shareable or new-window preview link. `appType` defaults to the current page context. Open `response.result.previewPageUrl`; do not use `previewUrl` or `/service/file/preview-by-ticket/:ticket` as the page entry.
 - Use `sdk.organization.departments.*` and `sdk.organization.accounts.*` only for intentional organization pages. Read-only list/detail pages need `app:organization:read` or `app:organization:manage`; writes and password operations need `app:organization:manage`. Do not call legacy `/user` or `/department` endpoints from pages.

package/openxiangda-skills/references/resource-manifest-cheatsheet.md

@@ -552,19 +552,17 @@ const stats = await sdk.dataView.stats("ticket_stats_by_customer", {
 }
 ```
 
-页面调用：
+页面调用具名 App Function，只传业务标识：
 
 ```ts
-await sdk.notification.sendByType({
-  notificationType: "reservation_reminder",
-  recipientId: userId,
-  payload: { title: "预约提醒", instrumentName, startTime },
+await sdk.function.invoke("send_reservation_reminder", {
+  input: { reservationId },
 });
 ```
 
-JS_CODE 调用：`ctx.notification.sendByType({ ... })`。允许的 channels：`inapp` / `email` / `dingding` / `wechat` / `thirdparty_todo`。完整规则见 [`notifications.md`](notifications.md)。
+App Function / Workflow / Automation / JS_CODE 在完成业务鉴权并解析接收人后调用：`ctx.notification.sendByType({ ... })`。允许的 channels：`inapp` / `email` / `dingding` / `wechat` / `thirdparty_todo`。完整规则见 [`notifications.md`](notifications.md)。
 
-钉钉卡片预览/发送：`sdk.notification.previewDingTalk({ notificationType, payload })`、`sdk.notification.sendDingTalk({ notificationType, recipientId, payload })`；CLI 为 `openxiangda notification dingding-preview` 和 `openxiangda notification dingding-send --force`。
+页面可做钉钉卡片预览：`sdk.notification.previewDingTalk({ notificationType, payload })`；CLI 为 `openxiangda notification dingding-preview`。实际发送必须位于具名 App Function 等可信运行时中。
 
 ## 4. App Function — `src/resources/functions/<functionCode>.json` + `src/functions/<functionCode>/index.ts`
 
@@ -683,7 +681,37 @@ const result = await sdk.function.invoke("reservation_reminder_summary", {
 
 适用边界：可复用后端业务逻辑、跨页面/自动化/流程共享的查询编排、连接器调用、通知编排、受控平台 API 调用。App Function 支持 `ctx.form.queryOne/queryMany/getById/createOne/updateOne/updateById`、`ctx.dataView`、`ctx.connector`、`ctx.notification`、`ctx.platform.roles`、`ctx.platform.api` 等受控 helper，当前 MVP 不暴露原始 SQL/Redis。应用角色查询和成员维护优先使用 `ctx.platform.roles.list/findByCode/addUsers/removeUser`；底层 `ctx.platform.api` 返回 HTTP 包装与平台 envelope，需要自行解包。已发布可信代码可以访问当前租户、当前应用内的资源；function manifest 的 `resources` 是可选映射、审计和影响分析信息，不再是逐函数权限白名单。页面用户仍不能直接提交内部表单，跨应用和跨租户访问仍被拒绝。运行时接口默认需要应用自动化管理权限；普通用户页面要调用时，用 `definitionJson.runtimeInvoke.audience` 声明 `authenticated`、`page_permission_group`、`app_roles`、`platform_roles` 或 `scope_policy`，使用 `roleCodes` 匹配应用角色、使用 `platformRoleCodes` 匹配同步身份 `SCHOOL_GUARDIAN`、`SCHOOL_STUDENT`、`SCHOOL_TEACHER`，不要把 `"*"`、`"all-app-roles"` 写进角色编码。若表单只能由函数/流程写入，在 `src/resources/settings/forms/<formCode>.json` 设置 `runtimeWrite.mode="function_only"` 关闭原始写入接口。
 
-## 5. Workflow — `src/resources/workflows/<code>/workflow.json`（manifest）+ `src/workflows/<code>/workflow.ts`（代码优先）
+## 5. Inbound Webhook — `src/resources/webhooks/<code>.json`
+
+```json
+{
+  "code": "yuquan_access",
+  "name": "玉泉门禁开门事件",
+  "targetFunctionCode": "qfyy_access_event",
+  "idempotencyQueryParam": "nonce",
+  "maxBodyBytes": 262144,
+  "status": "active"
+}
+```
+
+Webhook 只声明公开入口到固定 App Function 的映射，不包含 Secret 或验签规则。
+供应商 Secret 在目标 Function 顶层 `secretRefs` 声明，源码通过
+`await ctx.secrets.get(name)` 读取，并且必须在任何表单查询、写入、连接器或通知
+调用之前使用 `input.rawBody` 验签。平台保存原始 UTF-8 Body、Base64 Body、原始
+Query 字符串、重复参数数组、解析 JSON 和安全请求头；投递为 at-least-once，应用
+还必须用 `input.idempotencyKey` 对业务写入做幂等保护。
+
+```bash
+openxiangda resource validate webhook --profile <name>
+openxiangda resource plan webhook --only yuquan_access --profile <name> --json
+openxiangda resource publish webhook --only yuquan_access --change <id> --profile <name>
+openxiangda webhook deliveries yuquan_access --profile <name> --json
+```
+
+完整 Function 输入、HMAC-SHA1 常量时间比较、返回状态和玉泉门禁示例见
+[`webhooks.md`](webhooks.md)。
+
+## 6. Workflow — `src/resources/workflows/<code>/workflow.json`（manifest）+ `src/workflows/<code>/workflow.ts`（代码优先）
 
 ```jsonc
 // src/resources/workflows/customer_approval/workflow.json
@@ -713,7 +741,7 @@ export default defineWorkflow({
 
 CLI 编译为 `definition.v3.json` + `preview.json`，平台运行时仍走标准工作流引擎。完整规则见 [`workflow-v3.md`](workflow-v3.md)。
 
-## 6. Automation — `src/resources/automations/<code>/{definition.code.json,preview.json}` + `src/automations/<code>/index.ts`
+## 7. Automation — `src/resources/automations/<code>/{definition.code.json,preview.json}` + `src/automations/<code>/index.ts`
 
 ```jsonc
 // src/resources/automations/notify_on_submit/definition.code.json