@oj-module/cli 0.2.45 → 0.2.46

package/devkit/wecom-daikaifa.md

@@ -52,16 +52,28 @@
 ### 2.1 六项部署常量（全部填在工程根 `config.yaml` 的 `vars:` 段）
 
 一个部署 = 一套代开发模板，所以这六项是**部署维度**的常量，不进数据库。
-**六项任一为空 → 企微登录整体 400 拒绝服务**（宁可不登录，也不明文存 `permanent_code`）。
 
-| # | 变量 | 从哪取 | 格式 / 校验 | 配错或缺失的后果 |
-|---|---|---|---|---|
-| 1 | `wecom_suite_id` | 企微服务商后台 → 应用管理 → 代开发应用 → 模板详情，即 **SuiteID**（形如 `ww…` / `wwb…`） | 非空字符串 | 400 `企业微信未配置：config vars 缺少 wecom_suite_id`；回调事件还会被判 `SuiteId 与本部署配置不一致` |
-| 2 | `wecom_suite_secret` | 同页 **SuiteSecret**（可重置） | 非空字符串；重置后旧值立即失效 | 换不出 `suite_access_token` → 502 `企微 get_suite_token 失败：errcode=40001 …`；开通链接生成也失败 |
-| 3 | `wecom_callback_token` | 同页 **Token**（字母数字，3–32 位） | 与企微后台**逐字一致** | 保存回调 URL 时 `echostr` 解不解得开；事件被判验签失败，企微持续重推 |
-| 4 | `wecom_encoding_aes_key` | 同页 **EncodingAESKey** | **43 字符** | 同上：回调报文解不开，`suite_ticket` 永远收不到 |
-| 5 | `wecom_enc_key` | **自己生成**，见 §2.4 | hex 32 字符（16 字节）或 64 字符（32 字节），或 base64 解码后 16 / 32 字节。**AES-192（24 字节）不支持** | 400 `企业微信配置错误：wecom_enc_key 必须是 16 或 32 字节的 hex（32/64 字符）或 base64` |
-| 6 | `wecom_base_url` | 你站点的对外地址 + `/api/auth/wecom` | **绝对地址、无尾斜杠、必须以 `/api/auth/wecom` 结尾** | 400 `wecom_base_url 必须是绝对地址` 或 `必须以 /api/auth/wecom 结尾`；配错还会让登录回跳落到别的应用或 404 |
+六项分两层，**来源与必填时序不同**——这是破解「先有 suite 还是先有回调」死锁的关键
+（详见 plan §18）：
+
+- **Tier A（部署方本地生成，创建模版前即可配齐）**：`wecom_callback_token` /
+  `wecom_encoding_aes_key` / `wecom_enc_key` / `wecom_base_url`。这四项决定服务能否启动并响应
+  回调验证，**不依赖企业微信下发**；即使 `suite_id` / `suite_secret` 还空着，服务也能跑通 echostr。
+- **Tier B（企业微信在「代开发模版创建成功」后下发）**：`wecom_suite_id` / `wecom_suite_secret`。
+  只影响登录 / 授权等 suite 流程（login / callback / create_auth）；**回调 URL 验证（echostr）不依赖它们**。
+
+Tier A 任一为空 → 服务启动即 400 拒绝（宁可不登录，也不明文存 `permanent_code`）。
+Tier B 为空时服务仍可启动并响应 echostr，但 suite 流程会 400——先配 Tier A 把回调验证跑通、
+创建模版、拿到 suite 凭据，再补全 Tier B 即可，无需鸡生蛋。
+
+| # | 变量 | 层级 | 从哪取 | 格式 / 校验 | 配错或缺失的后果 |
+|---|---|---|---|---|---|
+| 1 | `wecom_suite_id` | Tier B | 企微服务商后台 → 应用管理 → 代开发应用 → 模板详情（**创建成功后**才有），即 **SuiteID**（形如 `ww…` / `wwb…`） | 非空字符串 | Tier A 配齐时服务可启动并验证回调；此项空 → login/callback/create_auth 等 suite 流程 400 `config vars 缺少 wecom_suite_id`；`event.post` 还会判 `SuiteId 与本部署配置不一致` |
+| 2 | `wecom_suite_secret` | Tier B | 同页 **SuiteSecret**（可重置） | 非空字符串；重置后旧值立即失效 | 换不出 `suite_access_token` → 502 `企微 get_suite_token 失败：errcode=40001 …`；开通链接生成也失败 |
+| 3 | `wecom_callback_token` | Tier A | 同页 **Token**（自设，字母数字 3–32 位） | 与企微后台**逐字一致** | 保存回调 URL 时 `echostr` 解不解得开；事件被判验签失败，企微持续重推 |
+| 4 | `wecom_encoding_aes_key` | Tier A | 同页 **EncodingAESKey**（自设） | **43 字符** | 同上：回调报文解不开，`suite_ticket` 永远收不到 |
+| 5 | `wecom_enc_key` | Tier A | **自己生成**，见 §2.4 | hex 32 字符（16 字节）或 64 字符（32 字节），或 base64 解码后 16 / 32 字节。**AES-192（24 字节）不支持** | 400 `企业微信配置错误：wecom_enc_key 必须是 16 或 32 字节的 hex（32/64 字符）或 base64` |
+| 6 | `wecom_base_url` | Tier A | 你站点的对外地址 + `/api/auth/wecom` | **绝对地址、无尾斜杠、必须以 `/api/auth/wecom` 结尾** | 400 `wecom_base_url 必须是绝对地址` 或 `必须以 /api/auth/wecom 结尾`；配错还会让登录回跳落到别的应用或 404 |
 
 `wecom_base_url` 是唯一「配一处、派生两处」的值——它同时决定：
 
@@ -119,20 +131,34 @@ openssl rand -hex 32        # 输出 64 个 hex 字符，直接贴进 wecom_enc_
 
 ## 4. 首次开通：顺序错了一定卡在 503
 
-这七步有硬依赖，**不能跳序**：
+开通分两个阶段，两阶段之间由「代开发模版创建成功、拿到 suite 凭据」衔接——这正是
+破解鸡生蛋死锁的关键（详见 plan §18）：**回调验证只需 Tier A，不必等 suite**。
+
+### 阶段一：配 Tier A + 跑通回调验证（此时还没有 suite）
+
+| 步 | 动作 | 为什么 | 错序的症状 |
+|---|---|---|---|
+| 1 | 配好 §2.1 的 **Tier A 四项**（`callback_token` / `encoding_aes_key` / `enc_key` / `base_url`），重启服务 | 这四项本地生成，服务凭它们即可启动并响应 echostr | 400 `企业微信未配置：config vars 缺少 …` |
+| 2 | 站点对外 https 可达；把指令回调 URL `<base>/event` 填进企微后台并保存 | 保存动作本身就是第一次验签（GET `echostr`）——而 echostr 只依赖 Tier A | 保存失败：`Token` / `EncodingAESKey` 对不上 |
+
+> 阶段一**不需要** `suite_id` / `suite_secret`：企微在「模版创建成功」后才下发它们，而 echostr
+> 验证在创建期就能跑通（receiveid 校验在 suite 未下发时自动放宽，签名仍是唯一鉴权闸门）。
+
+### 阶段二：拿 suite 凭据，再走 suite 流程
 
-| 步 | 动作 | 为什么必须在这一步 | 跳过的症状 |
+| 步 | 动作 | 为什么必须在这一步 | 错序的症状 |
 |---|---|---|---|
-| 1 | 填好 §2.1 六项，重启服务 | 后面每一步都要读这些值 | 400 `企业微信未配置：config vars 缺少 …` |
-| 2 | 站点对外可访问（https），把指令回调 URL 填进企微后台并保存 | 保存动作本身就是第一次验签（GET `echostr`） | 保存失败，`Token`/`EncodingAESKey` 对不上 |
-| 3 | **等 `suite_ticket` 到手**（企微每 10 分钟推一次） | 换 `suite_access_token` 必须有票据，而票据只能由回调推来 | 503 `企微套件票据（suite_ticket）尚未收到：回调 URL 未打通或企微尚未推送` |
-| 4 | 用超级管理员登录，进 `/system/wecom` → 「生成开通链接」 | 开通链接要先换 `pre_auth_code`，而它依赖第 3 步 | 同上 503；或链接生成失败 |
-| 5 | 把链接/二维码发给企业管理员，由其确认授权 | 只有企业管理员能授权；确认后企微推 `create_auth` | 企业侧没有应用；本站无该企业记录 |
-| 6 | 进 `/system/settings` 打开「启用企业微信登录」 | `wecom.enabled` 默认 **关**，只是「发现登录方式」的开关 | 登录页根本看不到「企业微信」页签 |
-| 7 | 企业员工从企微工作台/扫码/专属链接进入 | 首次登录自动建档 | 401 `登录凭据无效或不在应用可见范围内`（多半是可见范围没配） |
-
-> **为什么第 3 步容易漏**：`suite_ticket` 是被推送的，不是拉取的。第一次部署时如果回调
+| 3 | 模版创建成功后，从模版详情拿 **SuiteID / SuiteSecret**，填入 §2.1 的 **Tier B**，重启服务 | 否则 `suite_ticket` 推来时 `event.post` 因缺 suite 凭据 400，票据永远收不到 | 日志看不到 `wecom suite_ticket updated`；`/system/wecom` 生成链接报 503 |
+| 4 | **等 `suite_ticket` 到手**（企微每 10 分钟推一次） | 换 `suite_access_token` 必须有票据，而票据只能由回调推来 | 503 `suite_ticket 尚未收到：回调 URL 未打通或企微尚未推送` |
+| 5 | 用超级管理员登录，进 `/system/wecom` → 「生成开通链接」 | 开通链接要先换 `pre_auth_code`，而它依赖第 4 步 | 同上 503；或链接生成失败 |
+| 6 | 把链接/二维码发给企业管理员，由其确认授权 | 只有企业管理员能授权；确认后企微推 `create_auth` | 企业侧没有应用；本站无该企业记录 |
+| 7 | 进 `/system/settings` 打开「启用企业微信登录」 | `wecom.enabled` 默认 **关**，只是「发现登录方式」的开关 | 登录页根本看不到「企业微信」页签 |
+| 8 | 企业员工从企微工作台/扫码/专属链接进入 | 首次登录自动建档 | 401 `登录凭据无效或不在应用可见范围内`（多半是可见范围没配） |
+
+> **为什么第 4 步容易漏**：`suite_ticket` 是被推送的，不是拉取的。第一次部署时如果回调
 > URL 保存得晚，就要等下一个 10 分钟周期。看到 503 不必怀疑代码——先确认回调真的通。
+> **阶段二衔接的新坑**：若第 3 步的 suite 凭据还没填、企微就推来了 `suite_ticket`，那几条会被
+> 400 拒掉（属预期），填好 Tier B 重启后下一个推送周期会自动补上，不必手动回放。
 
 ---
 
@@ -295,7 +321,9 @@ window.location.assign(`${resolveApiBase()}${wecomAuthorizePath(corp)}`);
 
 ### 7.1 上线前 checklist
 
-- [ ] 服务商账号已认证，代开发应用模板已创建（拿到 SuiteID / SuiteSecret / Token / EncodingAESKey）
+- [ ] 服务商账号已认证，代开发应用模板已创建
+- [ ] Tier A 四项已生成并填好（`wecom_callback_token` / `wecom_encoding_aes_key` 在企微后台同页自设；`wecom_enc_key` 见 §2.4 本地生成；`wecom_base_url` 为站点对外地址）
+- [ ] 模版创建成功后拿到 **SuiteID / SuiteSecret**（Tier B），已填入配置并重启（详见 §4 阶段二）
 - [ ] 站点已用 **https** 对外，反向代理放行 `POST /api/auth/wecom/event`（含原始 XML 请求体，不要改写）
 - [ ] 可信域名已备案（含校验文件）
 - [ ] 可信 IP 已列全所有出口 IP
@@ -306,16 +334,17 @@ window.location.assign(`${resolveApiBase()}${wecomAuthorizePath(corp)}`);
 
 ### 7.2 上线顺序
 
-照 §4 的七步走。每步的验收点：
+照 §4 的两阶段八步走。每步的验收点：
 
 | 步 | 验收 |
 |---|---|
-| 1–2 | 企微后台保存回调 URL 成功（说明验签与解密都对） |
-| 3 | 服务日志出现 `wecom suite_ticket updated` |
-| 4 | `/system/wecom` 能出链接，且显示的回调地址与企微后台一致 |
-| 5 | 列表出现该企业；日志出现 `wecom auth applied … agents=…` |
-| 6 | 登录页出现「企业微信」页签 |
-| 7 | 用一个**普通员工**账号登录成功（不要只用管理员自己的号） |
+| 1–2（阶段一） | 企微后台保存回调 URL 成功（说明 Tier A 的验签与解密都对——此时还没有 suite 凭据也照常通） |
+| 3（阶段二） | 填好 Tier B 并重启成功 |
+| 4 | 服务日志出现 `wecom suite_ticket updated` |
+| 5 | `/system/wecom` 能出链接，且显示的回调地址与企微后台一致 |
+| 6 | 列表出现该企业；日志出现 `wecom auth applied … agents=…` |
+| 7 | 登录页出现「企业微信」页签 |
+| 8 | 用一个**普通员工**账号登录成功（不要只用管理员自己的号） |
 
 ### 7.3 启停与解绑
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@oj-module/cli",
   "type": "module",
-  "version": "0.2.45",
+  "version": "0.2.46",
   "description": "React Antd 模块工程命令行工具（含预构建宿主 shell-dist）",
   "license": "MIT",
   "exports": {
@@ -49,7 +49,7 @@
   ],
   "dependencies": {
     "@faker-js/faker": "^10.4.0",
-    "@oj-module/runtime": "0.2.45",
+    "@oj-module/runtime": "0.2.46",
     "@redocly/cli": "^2.51.0",
     "@tailwindcss/vite": "^4.3.0",
     "cac": "^6.7.14",

package/shell-dist/assets/runtime.js

@@ -304,10 +304,10 @@ function getAppInfo() {
 	return {
 		"pkg": {
 			"name": "@oj-module/runtime",
-			"version": "0.2.45",
+			"version": "0.2.46",
 			"license": "MIT"
 		},
-		"lastBuildTime": "2026-10-31 01:51:27"
+		"lastBuildTime": "2026-10-31 09:51:01"
 	};
 }
 var init_get_app_info = __esmMin((() => {}));

package/shell-dist/index.html

@@ -5,9 +5,9 @@
 		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
 		<link rel="icon" href="/favicon.ico" />
 		<title>React Antd Admin · Shell</title>
-		<meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'self' https://modules.cdn.example.com 'wasm-unsafe-eval' 'nonce-IiFAOepBufxbhXdsYRrEMA=='; script-src-attr 'none'; connect-src 'self' data: https://modules.cdn.example.com; style-src 'self' https://modules.cdn.example.com 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' data:; frame-src https://ant.design https://react.dev https://condorheroblog.github.io; form-action 'none'; base-uri 'none'; object-src 'none'; upgrade-insecure-requests" />
+		<meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'self' https://modules.cdn.example.com 'wasm-unsafe-eval' 'nonce-OppgUj8nzdkICPflvWyj9w=='; script-src-attr 'none'; connect-src 'self' data: https://modules.cdn.example.com; style-src 'self' https://modules.cdn.example.com 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' data:; frame-src https://ant.design https://react.dev https://condorheroblog.github.io; form-action 'none'; base-uri 'none'; object-src 'none'; upgrade-insecure-requests" />
 
-		<script type="importmap" nonce="IiFAOepBufxbhXdsYRrEMA==">{
+		<script type="importmap" nonce="OppgUj8nzdkICPflvWyj9w==">{
   "imports": {
     "react": "/assets/react.js",
     "react/jsx-runtime": "/assets/jsx-runtime.js",

package/shell-dist/versions.json

@@ -7,9 +7,9 @@
   "react-router": "7.18.2",
   "react-router/dom": "7.18.2",
   "@tanstack/react-query": "5.102.8",
-  "@oj-module/runtime": "0.2.45",
-  "@oj-module/runtime/contract": "0.2.45",
-  "@oj-module/runtime/contract/errors": "0.2.45",
+  "@oj-module/runtime": "0.2.46",
+  "@oj-module/runtime/contract": "0.2.46",
+  "@oj-module/runtime/contract/errors": "0.2.46",
   "@plane/kit": "0.1.20",
   "@plane/editor": "0.1.20",
   "antd": "6.6.1",

package/templates/src/auth/api/_shared/wecom/config.ts

@@ -10,10 +10,13 @@
 
 import { b64ToBytes } from "./crypt";
 
-export interface WecomConfig {
-	/** 代开发应用模版 id（企微侧即 suite_id），也是回调明文里的 receiveid */
-	suiteId: string
-	suiteSecret: string
+/**
+ * 回调引导配置（Tier A）：echostr URL 验证 + 永久码落库加密所需的全部凭据。
+ * 这四项**全部由部署方在本地生成**，与企业微信无关——所以可以在「创建代开发模版 / 拿到
+ * suite_id」之前就配齐并启动服务、响应企微的 URL 验证。这是打破「先有 suite 还是先有回调」
+ * 死锁的关键（见 plan §18）：鸡生蛋问题里，这四项属于「蛋还没孵出来前就能自己备齐的料」。
+ */
+export interface WecomCallbackConfig {
 	/** 回调签名 token（企微后台「Token」） */
 	token: string
 	/** 回调加密密钥（43 字符 EncodingAESKey） */
@@ -29,15 +32,43 @@ export interface WecomConfig {
 	baseUrl: string
 }
 
-const REQUIRED: Array<[keyof WecomConfig, string]> = [
-	["suiteId", "wecom_suite_id"],
-	["suiteSecret", "wecom_suite_secret"],
+/**
+ * 完整配置（Tier A + Tier B）：login/callback/create_auth 等 suite 流程额外需要
+ * `suiteId` 与 `suiteSecret`——它们由企业微信在「代开发模版创建成功」后下发（模版详情页可见），
+ * 缺失只影响 suite 流程，不影响回调 URL 验证（后者只需 Tier A）。
+ */
+export interface WecomConfig extends WecomCallbackConfig {
+	/** 代开发应用模版 id（企微侧即 suite_id），也是回调明文里的 receiveid */
+	suiteId: string
+	suiteSecret: string
+}
+
+// Tier A：部署方本地生成，创建模版前即可配齐（token / EncodingAESKey / 落库密钥 / 基址）。
+const REQUIRED_CALLBACK: Array<[keyof WecomCallbackConfig, string]> = [
 	["token", "wecom_callback_token"],
 	["encodingAesKey", "wecom_encoding_aes_key"],
 	["encKey", "wecom_enc_key"],
 	["baseUrl", "wecom_base_url"],
 ];
 
+// Tier B：suite 凭据，企业微信在「代开发模版创建成功」后下发（模版详情页可查）。
+const REQUIRED_SUITE: Array<[keyof WecomConfig, string]> = [
+	["suiteId", "wecom_suite_id"],
+	["suiteSecret", "wecom_suite_secret"],
+];
+
+/** 一次性读出六处部署常量（未 trim 的尾斜杠在此归一） */
+function readWecomVars(): WecomConfig {
+	return {
+		token: vars.get("wecom_callback_token") ?? "",
+		encodingAesKey: vars.get("wecom_encoding_aes_key") ?? "",
+		encKey: vars.get("wecom_enc_key") ?? "",
+		baseUrl: (vars.get("wecom_base_url") ?? "").replace(/\/+$/, ""),
+		suiteId: vars.get("wecom_suite_id") ?? "",
+		suiteSecret: vars.get("wecom_suite_secret") ?? "",
+	};
+}
+
 /**
  * 落库密钥格式校验（fail-fast 在**读配置**处，而不是等 create_auth 时在 crypto 里炸）：
  * oj 的 aesGcmEncrypt 只收「16 或 32 字节的 hex/base64」，AES-192（24 字节）明确不支持。
@@ -60,26 +91,38 @@ export function assertEncKey(encKey: string): void {
 }
 
 /**
- * 读部署常量。缺任一必需项即 400（「未配置」是运维事实，不是服务端缺陷）：
- * 前半段（suite 凭据）缺失 → 企微登录整体不可用；encKey 缺失则 permanent_code 无法安全落库，
- * 宁可拒服务，也不退化成明文存储（§7.5 数据合规红线）。
+ * 读 Tier A 凭据（token / aeskey / encKey / baseUrl）。**不依赖 suite 凭据**：这是 echostr
+ * URL 验证与永久码落库加密所需的全部东西，部署方本地即可生成。引导期（suite_id 尚未下发）
+ * 服务也能靠它启动并响应企微的回调验证（plan §18）。
  */
-export function readWecomConfig(): WecomConfig {
-	const cfg: WecomConfig = {
-		suiteId: vars.get("wecom_suite_id") ?? "",
-		suiteSecret: vars.get("wecom_suite_secret") ?? "",
-		token: vars.get("wecom_callback_token") ?? "",
-		encodingAesKey: vars.get("wecom_encoding_aes_key") ?? "",
-		encKey: vars.get("wecom_enc_key") ?? "",
-		baseUrl: (vars.get("wecom_base_url") ?? "").replace(/\/+$/, ""),
-	};
-	const missing = REQUIRED.filter(([field]) => !cfg[field]).map(([, name]) => name);
+export function readCallbackConfig(): WecomCallbackConfig {
+	const v = readWecomVars();
+	const missing = REQUIRED_CALLBACK.filter(([field]) => !v[field]).map(([, name]) => name);
 	if (missing.length)
 		throw Object.assign(new Error(`企业微信未配置：config vars 缺少 ${missing.join(" / ")}`), { status: 400 });
-	if (!/^https?:\/\//.test(cfg.baseUrl))
+	if (!/^https?:\/\//.test(v.baseUrl))
+		throw Object.assign(new Error("企业微信配置错误：wecom_base_url 必须是绝对地址（企微回调与 redirect_uri 都要求）"), { status: 400 });
+	assertEncKey(v.encKey);
+	return { token: v.token, encodingAesKey: v.encodingAesKey, encKey: v.encKey, baseUrl: v.baseUrl };
+}
+
+/**
+ * 读完整部署常量。缺任一必需项即 400（「未配置」是运维事实，不是服务端缺陷）。
+ * 一次报全 Tier A + Tier B 所有缺失项，省掉逐轮补配置的往返；suite 凭据（Tier B）缺失时
+ * 文案点明「由代开发模版创建成功后下发」，避免运维误以为是本地漏配。
+ *
+ * 注：Tier B 缺失只影响 login/callback/create_auth 等 suite 流程；echostr 验证走
+ * `readCallbackConfig()`，不受此约束（见 api.ts::event.get）。
+ */
+export function readWecomConfig(): WecomConfig {
+	const v = readWecomVars();
+	const missing = [...REQUIRED_CALLBACK, ...REQUIRED_SUITE].filter(([field]) => !v[field]).map(([, name]) => name);
+	if (missing.length)
+		throw Object.assign(new Error(`企业微信未配置：config vars 缺少 ${missing.join(" / ")}（suite 凭据由代开发模版创建成功后下发）`), { status: 400 });
+	if (!/^https?:\/\//.test(v.baseUrl))
 		throw Object.assign(new Error("企业微信配置错误：wecom_base_url 必须是绝对地址（企微回调与 redirect_uri 都要求）"), { status: 400 });
-	assertEncKey(cfg.encKey);
-	return cfg;
+	assertEncKey(v.encKey);
+	return v;
 }
 
 /** 企微后台「指令回调 URL」：原样填这个（base + /event） */

package/templates/src/auth/api/_shared/wecom/crypt.ts

@@ -293,8 +293,12 @@ export function wecomSignature(...parts: string[]): string {
  * 明文结构（企微 §消息加解密）：`random(16B) | msg_len(4B, big-endian) | msg | receiveid`。
  * `receiveid` 对第三方平台/代开发模版是 **suite_id**；不一致即拒（错钥/错套件混用必须 fail-closed，
  * 否则不同套件的回调会互相污染）。43 字符 EncodingAESKey 末尾补 "=" 才是 44 字符 base64（32 字节）。
+ *
+ * `tolerant`（默认 false）：引导期 `suite_id` 尚未下发时，receiveid 无从比对——
+ * 此时放宽该检查。放宽是安全的：最外层签名（基于开发者持有的 `token`）已鉴权，
+ * receiveid 只是防御性兜底（防错配 aeskey）。`suite_id` 配齐后调用方应传 `false` 恢复严格。
  */
-export function unwrapWecomMessage(encryptedB64: string, encodingAesKey: string, expectedReceiver: string): string {
+export function unwrapWecomMessage(encryptedB64: string, encodingAesKey: string, expectedReceiver: string, tolerant = false): string {
 	const key = b64ToBytes(`${encodingAesKey}=`);
 	if (key.length !== 32)
 		throw new Error(`wecom: EncodingAESKey must decode to 32 bytes, got ${key.length}`);
@@ -306,7 +310,8 @@ export function unwrapWecomMessage(encryptedB64: string, encodingAesKey: string,
 		throw new Error("wecom: msg length out of range");
 	const msg = bytesToUtf8(plain.subarray(20, 20 + msgLen));
 	const receiver = bytesToUtf8(plain.subarray(20 + msgLen));
-	if (receiver !== expectedReceiver)
+	// 引导期（suite_id 未下发）且显式 tolerant → 跳过 receiveid 比对；其余情况严格比对。
+	if (!tolerant && receiver !== expectedReceiver)
 		throw new Error(`wecom: receiver mismatch (got ${receiver === "" ? "<empty>" : "other"}, expected suite)`);
 	return msg;
 }

package/templates/src/auth/api/wecom/api.ts

@@ -17,7 +17,7 @@ import { failWith, respond } from "#/_platform/_shared/respond";
 import { clientIp, guardLoginThrottle, noteLoginFailed, noteLoginSucceeded } from "../_shared/login-throttle";
 import { createSession } from "../_shared/session";
 import { createWecomClient, runtimeCache, runtimeHttp } from "../_shared/wecom/client";
-import { loginRedirectOf, readWecomConfig, siteRootOf } from "../_shared/wecom/config";
+import { loginRedirectOf, readCallbackConfig, readWecomConfig, siteRootOf } from "../_shared/wecom/config";
 import { unwrapWecomMessage, wecomSignature } from "../_shared/wecom/crypt";
 import { handleSuiteEvent } from "../_shared/wecom/events";
 import {
@@ -192,11 +192,31 @@ ticket.post.schema = {
 };
 
 const event = {
-	// 企微后台「保存回调 URL」时会 GET 一次：解出 echostr 后**原样明文回**（不套信封、不加引号）
+	// 企微后台「保存回调 URL」时会 GET 一次：解出 echostr 后**原样明文回**（不套信封、不加引号）。
+	//
+	// 只依赖 Tier A 凭据（readCallbackConfig）：token/aeskey/baseUrl/encKey 全部部署方本地生成，
+	// 不需要 suite_id——因此「配齐四项正确即可响应验证」，**不必等代开发模版创建、拿到 suite_id 之后**。
+	// 这正是打破鸡生蛋死锁（plan §18）的落点：先有可验证的回调，才能创建模版、拿到 suite 凭据。
+	//
+	// suite_id 在「模版创建成功」后才下发；URL 验证可能发生在拿到 suite_id 之前（创建表单内联校验），
+	// 此时 receiveid 无从比对 → 走 tolerant（签名已是最外层鉴权闸门，receiveid 仅为防御性兜底）。
 	async get() {
 		try {
-			const { plain } = await decryptVerified(query("echostr"));
-			plainText(plain);
+			const cfg = readCallbackConfig();
+			const encrypted = query("echostr");
+			const expected = wecomSignature(cfg.token, query("timestamp"), query("nonce"), encrypted);
+			if (expected !== query("msg_signature"))
+				throw badRequest("回调签名校验失败");
+			await guardReplay(query("timestamp"), query("nonce"), runtimeReplayGate());
+			const suiteId = (vars.get("wecom_suite_id") ?? "").trim();
+			try {
+				plainText(unwrapWecomMessage(encrypted, cfg.encodingAesKey, suiteId, !suiteId));
+			}
+			catch (e) {
+				// 解密失败只透出「失败」：错钥/未下发套件/被篡改三者不可区分，也不该让外部据此判断哪一环配错
+				log.warn("wecom callback decrypt failed", "reason", (e as Error).message);
+				throw badRequest("回调消息解密失败");
+			}
 		}
 		catch (e) {
 			failWith(e);

package/templates/tests/wecom-connector.spec.ts

@@ -21,6 +21,7 @@ import {
 	eventUrlOf,
 	installUrlOf,
 	loginRedirectOf,
+	readCallbackConfig,
 	readWecomConfig,
 	siteRootOf,
 } from "../src/auth/api/_shared/wecom/config";
@@ -620,7 +621,36 @@ describe("P1-J：部署常量读取（缺项一次报全 / 密钥格式 fail-fas
 
 	it("缺项一次报全（不是报第一个就返回，省掉逐轮补配置的往返）", () => {
 		installVars({ wecom_suite_id: "", wecom_callback_token: "", wecom_enc_key: "" });
-		expect(() => readWecomConfig()).toThrow(/wecom_suite_id.*wecom_callback_token.*wecom_enc_key/);
+		const msg = (() => {
+			try {
+				readWecomConfig();
+				return "";
+			}
+			catch (e) {
+				return (e as Error).message;
+			}
+		})();
+		for (const name of ["wecom_suite_id", "wecom_callback_token", "wecom_enc_key"])
+			expect(msg).toMatch(new RegExp(name));
+	});
+
+	it("readCallbackConfig 只校验 Tier A（token/aeskey/encKey/baseUrl），不依赖 suite 凭据——引导期可独立运行", () => {
+		// 即使 suite 两项全空，只要 Tier A 齐，readCallbackConfig 就不抛（供 echostr 验证用）
+		installVars({ wecom_suite_id: "", wecom_suite_secret: "" });
+		expect(() => readCallbackConfig()).not.toThrow();
+		// Tier A 缺项仍一次报全
+		installVars({ wecom_suite_id: "", wecom_suite_secret: "", wecom_callback_token: "", wecom_enc_key: "" });
+		const msg = (() => {
+			try {
+				readCallbackConfig();
+				return "";
+			}
+			catch (e) {
+				return (e as Error).message;
+			}
+		})();
+		for (const name of ["wecom_callback_token", "wecom_enc_key"])
+			expect(msg).toMatch(new RegExp(name));
 	});
 
 	it("baseUrl 去尾斜杠后拼出两个企微侧地址（回调 URL 要原样填进后台）", () => {

package/templates/tests/wecom-endpoints.spec.ts

@@ -384,6 +384,17 @@ describe("P1-L：GET/POST /auth/wecom/event（企微指令回调）", () => {
 		expect(out.body).toBeNull();
 	});
 
+	it("URL 验证（鸡生蛋解法）：suite_id 尚未下发时也能通过——receiveid 放宽，签名仍是唯一闸门", async () => {
+		// 引导期：模版还没建、suite_id 为空，但 Tier A 凭据（token/aeskey）已配齐，服务应能响应验证。
+		installVars({ wecom_suite_id: "" });
+		const echo = await seal("echo_bootstrap");
+		request({ query: { ...signedQuery(echo), echostr: echo } });
+		await (await api()).event.get();
+		expect(out.status).toBe(200);
+		expect(out.contentType).toContain("text/plain");
+		expect(out.text).toBe("echo_bootstrap");
+	});
+
 	it("签名不符 → 400（不给探测者任何比对材料）", async () => {
 		const echo = await seal("echo_12345");
 		request({ query: { timestamp: TS, nonce: NONCE, msg_signature: "bad", echostr: echo } });

package/vendor/host-versions.json

@@ -8,9 +8,9 @@
 		"react-router": "7.18.2",
 		"react-router/dom": "7.18.2",
 		"@tanstack/react-query": "5.102.8",
-		"@oj-module/runtime": "0.2.45",
-		"@oj-module/runtime/contract": "0.2.45",
-		"@oj-module/runtime/contract/errors": "0.2.45",
+		"@oj-module/runtime": "0.2.46",
+		"@oj-module/runtime/contract": "0.2.46",
+		"@oj-module/runtime/contract/errors": "0.2.46",
 		"@plane/kit": "0.1.20",
 		"@plane/editor": "0.1.20",
 		"antd": "6.6.1",