@oj-module/cli 0.2.45 → 0.2.47

package/devkit/wecom-daikaifa.md

@@ -49,19 +49,44 @@
 
 ## 2. 凭据清单
 
-### 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 |
+### 2.1 八项部署常量（全部填在工程根 `config.yaml` 的 `vars:` 段）
+
+一个部署 = 一套代开发模板，所以这八项是**部署维度**的常量，不进数据库。
+
+八项分三层，**来源与必填时序不同**——这是破解「先有 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 C（服务商级凭证，只供「生成开通链接」用）**：`wecom_provider_id`（= 服务商后台
+  **服务商信息**页的 CorpID）/ `wecom_provider_secret`（= 服务商后台 **应用管理 → 通用开发参数** 点「编辑」
+  后的 `ProviderSecret` 字段，**不在**服务商信息页，也**不是** suite 的 secret）。代开发的开通入口走
+  `get_customized_auth_url`，该接口只认 `provider_access_token`，而它必须由服务商 corpid + provider_secret 换得。
+  缺它**不影响登录**（login 走 suite 流程），但 `/system/wecom` 点「生成开通链接」会 400 点名缺这两项。
+
+Tier A 任一为空 → 服务启动即 400 拒绝（宁可不登录，也不明文存 `permanent_code`）。
+Tier B 为空时服务仍可启动并响应 echostr，但 suite 流程会 400——先配 Tier A 把回调验证跑通、
+创建模版、拿到 suite 凭据，再补全 Tier B 即可，无需鸡生蛋。Tier C 可与 Tier B 同一阶段补全。
+
+> 📌 **官方术语对齐**：企微服务商后台「代开发应用 → 模板详情 → **基本信息**」页里，
+> 这两项就直接标作 **模板ID** 与 **模板Secret**（英文即 SuiteID / SuiteSecret）。
+> 也就是说：本仓的 `wecom_suite_id` ← 官方「模板ID」，`wecom_suite_secret` ← 官方「模板Secret」，
+> **不是**企业的 CorpID / CorpSecret，也**不是**某个自建应用的 Secret。照着「基本信息」页抄这两格即可。
+> 两者都是「创建模板成功后」才出现在该页，创建前只有 Tier A 的 Token / EncodingAESKey 可设。
+
+| # | 变量 | 层级 | 从哪取 | 格式 / 校验 | 配错或缺失的后果 |
+|---|---|---|---|---|---|
+| 1 | `wecom_suite_id` | Tier B | 企微服务商后台 → 应用管理 → 代开发应用 → 模板详情 → **基本信息**页（**创建成功后**才有），标作「**模板ID**」，即 **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 | 同页「基本信息」标作「**模板Secret**」，即 **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`（注意这是基址，**不是**企微后台要填的回调 URL） | **绝对地址、无尾斜杠、必须以 `/api/auth/wecom` 结尾** | 400 `wecom_base_url 必须是绝对地址` 或 `必须以 /api/auth/wecom 结尾`；配错还会让登录回跳落到别的应用或 404 |
+| 7 | `wecom_provider_id` | Tier C | 服务商后台 → **服务商信息**页显示的 CorpID（服务商自己的 corpid，不是企业 corpid，也不是 suite_id） | 非空字符串 | 只影响「生成开通链接」：`get_provider_token` 换不出 `provider_access_token` → 生成链接 502；此项为空 → 生成链接 400 `config vars 缺少 wecom_provider_id` |
+| 8 | `wecom_provider_secret` | Tier C | 服务商后台 → **应用管理 → 通用开发参数**（**点「编辑」按钮**那一栏的 `ProviderSecret` 字段）。**不在「服务商信息」页**（那里只显示 CorpID），也**不是** suite_secret | 非空字符串；重置后旧值立即失效 | 换不出 `provider_access_token` → 生成链接 502 `企微 get_provider_token 失败：errcode=40001 …`；此项为空 → 生成链接 400 `config vars 缺少 wecom_provider_secret` |
 
 `wecom_base_url` 是唯一「配一处、派生两处」的值——它同时决定：
 
@@ -70,6 +95,11 @@
 - 登录成功后的站点回跳 = 去掉 `/api/auth/wecom` 的那部分（子路径部署也正确，例如
   `https://example.com/oj/api/auth/wecom` → 回跳 `https://example.com/oj/login`）
 
+> ⚠️ **`wecom_base_url` 不是回调 URL 本身，别把它直接填进企微后台。** 企微后台要填的
+> 「指令回调 URL」是 `<wecom_base_url>/event`（**必须带 `/event`**）。裸的 `/api/auth/wecom`
+> 没有任何 handler，企微验签时会打到它 → **404 → 验证失败、模版保存不了**。
+> 派生关系如上：回调 URL = base + `/event`，网页授权回跳 = base + `/callback`。
+
 ### 2.2 两项备案（都在企微后台，不写在代码里）
 
 | 备案项 | 填什么 | 不做的症状 |
@@ -119,20 +149,43 @@ 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 | 配好 §2.1 的 **Tier C**（`wecom_provider_id` / `wecom_provider_secret`，服务商后台「通用开发参数」页取），重启服务；再用超级管理员登录，进 `/system/wecom` → 「生成开通链接」 | 代开发的开通入口走 `get_customized_auth_url`（返回 `qrcode_url`），它只认 `provider_access_token`，而 provider_access_token 必须由服务商 corpid + provider_secret 换得（= Tier C）。**不是**第三方应用的 `get_pre_auth_code`（代开发调它会 48002） | 400 `config vars 缺少 wecom_provider_id / wecom_provider_secret`；或 502 `get_provider_token 失败`（provider_secret 错/重置）；或链接生成失败 |
+| 6 | 把链接/二维码发给企业管理员，由其扫码/打开授权 | 只有企业管理员能授权；确认后企微推 `create_auth` | 企业侧没有应用；本站无该企业记录 |
+| 7 | 进 `/system/settings` 打开「启用企业微信登录」 | `wecom.enabled` 默认 **关**，只是「发现登录方式」的开关 | 登录页根本看不到「企业微信」页签 |
+| 8 | 企业员工从企微工作台/扫码/专属链接进入 | 首次登录自动建档 | 401 `登录凭据无效或不在应用可见范围内`（多半是可见范围没配） |
+
+> 🔐 **进 `/system/wecom` 必须用 `superadmin` 账号，不是 `admin`。** 该页是跨租户的服务商
+> 运营面（生成开通链接 = 调企微 `get_customized_auth_url` 换 `qrcode_url`、管理所有已授权企业），前端（`system/web/pages/wecom/index.tsx:61`
+> 的 `roles.includes("superadmin")`）与后端 `auth/wecom/admin/*`（每个端点 `assertSuperAdmin()`）
+> 都只放行 `superadmin`。模板 seed 已把 `admin` 从 `superadmin` 角色解绑（收敛为「账号名 = 角色名」，
+> 见 `_platform/api/seed.sql` 的 `DELETE … WHERE role_name='superadmin' AND username='admin'`），
+> 所以拿 `admin` 登录会直接显示「无权限」。请用 `superadmin` 登录（seed 口令 `123456`，
+> **登录后立即改密**）；若坚持让 `admin` 也能进，由 `superadmin` 在 `/system/roles` 把 `admin`
+> 绑到 `superadmin`，但不推荐——这会取消「日常管理员 vs 跨租户运营面」的隔离。
+
+> **为什么第 4 步容易漏**：`suite_ticket` 是被推送的，不是拉取的。第一次部署时如果回调
 > URL 保存得晚，就要等下一个 10 分钟周期。看到 503 不必怀疑代码——先确认回调真的通。
+> **阶段二衔接的新坑**：若第 3 步的 suite 凭据还没填、企微就推来了 `suite_ticket`，那几条会被
+> 400 拒掉（属预期），填好 Tier B 重启后下一个推送周期会自动补上，不必手动回放。
 
 ---
 
@@ -185,7 +238,7 @@ openssl rand -hex 32        # 输出 64 个 hex 字符，直接贴进 wecom_enc_
 企微只回调**公网 https**，所以本地必须内网穿透。最小闭环：
 
 ```sh
-# 1) 六个 vars 填进工程根 config.yaml 的 vars:（见 §2.1）
+# 1) 八项 vars 填进工程根 config.yaml 的 vars:（见 §2.1，含 Tier C 的 provider 凭证）
 #    其中 wecom_base_url 先写成穿透地址：https://<穿透域名>/api/auth/wecom
 # 2) 起前后端
 pnpm dev
@@ -239,10 +292,12 @@ pnpm dev
 |---|---|---|
 | 已开通企业清单 | `GET /auth/wecom/admin/apps` | **不返回** `permanent_code`，最多到 `corp_name` |
 | 启用 / 停用某企业某应用 | `POST /auth/wecom/admin/status` | 停用是安全动作：**只在该企业没有其它 active 应用时**才吊销该租户会话 |
-| 生成开通链接 | `GET /auth/wecom/admin/install` | 返回 `{installUrl, callbackUrl, expiresIn}`；`callbackUrl` 就是要逐字填进企微后台的那个值 |
+| 生成开通链接 | `GET /auth/wecom/admin/install` | 返回 `{installUrl, callbackUrl, expiresIn}`；`installUrl` 是代开发 `get_customized_auth_url` 返回的 `qrcode_url`（企业管理员扫/开即授权），`callbackUrl` 就是要逐字填进企微后台的那个值 |
 
-开通链接**10 分钟有效且一次性**：过期后界面上的二维码会置灰，重新点一次即可（每次点都重新换
-`pre_auth_code`，不做缓存）。
+开通链接由企微 `get_customized_auth_url` 生成，**有效期以企微返回为准**（文档口径可达 10 天，实测可能较短），
+过期后界面上的二维码会置灰，重新点一次即可（每次点都重新换 `provider_access_token` + 调
+`get_customized_auth_url`，不做缓存）。代开发**不支持**第三方应用的 `get_pre_auth_code`——本接口
+刻意走 `get_customized_auth_url`，踩过 48002 的坑。
 
 权限是**超级管理员**而不是站点 admin：这三件事跨租户（能看别家企业的 corp_id）。
 
@@ -295,7 +350,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 +363,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 启停与解绑
 
@@ -369,7 +427,10 @@ window.location.assign(`${resolveApiBase()}${wecomAuthorizePath(corp)}`);
 | 401 `登录票据无效或已使用` / `登录票据已过期，请重新登录` | 票据被重放，或 180 秒没换 | 重新从入口进 |
 | 400 `授权未完成：企业微信未返回 code` | 用户在授权页点了取消 | 重新授权 |
 | 400 `登录状态已失效，请从企业微信重新进入` | `state` 过期（10 分钟）/ 已用 / 换过部署 | 重新进；跨部署时正常现象 |
-| 502 `企微 … 失败：errcode=60020 …` | 服务器出口 IP 不在可信 IP | 补齐白名单 |
+| 502 `企微 … 失败：errcode=60020 … client ip 113.80.7.113` | 调用企微 API 的**服务器出口公网 IP**未在可信 IP 白名单（代开发套件级/服务商级；`get_suite_token` 与「生成开通链接」用的 `get_provider_token` / `get_customized_auth_url` **都必校**） | 企微服务商后台 → 应用管理 → 代开发应用 → 对应套件 → **IP 白名单/可信IP**，把报错里的 `client ip`（例 `113.80.7.113`，即你服务器访问公网的出口 IP，**不是内网 IP**）加进去；多出口/运营商 NAT 就加整段 CIDR。改完等几分钟再点「生成开通链接」。注：此码**不在自动重试验证集**（只有 40001/42001 重换一次），属配置阻断、重试无用 |
+| 502 `企微 … 失败：errcode=48002 api forbidden` | 代开发应用调了第三方应用的 `get_pre_auth_code`（代开发**明确不支持**该接口） | 本系统「生成开通链接」已改用代开发专属的 `get_customized_auth_url`（返回 `qrcode_url`）。若仍见此码：确认跑的是本版代码（`admin.ts` 的 `createInstall` 不再调 `get_pre_auth_code`），并检查是否别处/旧版本在调它 |
+| 502 `企微 … 失败：errcode=40058 state missing` | `get_customized_auth_url` 的 `state` 必填，本系统没传/传空（旧版） | 已改为始终发送 `state`（调用方不传则补默认常量）。若仍见此码：确认跑的是本版代码（`client.ts` 的 `customizedAuthUrl` 始终带 `state`） |
+| 502 `企微 … 失败：errcode=842002 代开发模板尚未上架/上线` | 传入的代开发模板（`templateid_list` 里的 suite_id）只是「创建成功」但**未上线**——`get_customized_auth_url` 只在模板正式上线后才生成 `qrcode_url` | **运营动作，非代码缺陷**：服务商后台 → 应用管理 → 代开发应用上线 → 提交模板上线审核 → 审核通过后手动点「提交上线」。模板状态变「已上线/上架」后再点「生成开通链接」。凭证/参数都对却卡这步，就是模板没上线（创建成功 ≠ 上线） |
 | 502 `企微 … 失败：errcode=40001/40014/42001` | 凭据错或 token 过期（会自动重换一次） | 若持续：核对 SuiteSecret / 是否重置过 |
 | 502 `企微接口不可达` / `HTTP 5xx` | 出网被墙、DNS、代理 | 查机器出网与 DNS |
 | 点登录页「企业微信」按钮页面只闪一下、无请求 | 跳转拼了站点 base 而不是 API base | 见 §6.6 |
@@ -382,7 +443,7 @@ window.location.assign(`${resolveApiBase()}${wecomAuthorizePath(corp)}`);
 ## 9. 一分钟自检
 
 ```text
-[ ] 六个 vars 非空，wecom_base_url 以 /api/auth/wecom 结尾
+[ ] 八个 vars 非空（Tier A/B/C），wecom_base_url 以 /api/auth/wecom 结尾
 [ ] 企微后台的指令回调 URL == <wecom_base_url>/event（逐字）
 [ ] 服务日志有 wecom suite_ticket updated（近期）
 [ ] /system/wecom 列表里有目标企业，status=active

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@oj-module/cli",
   "type": "module",
-  "version": "0.2.45",
+  "version": "0.2.47",
   "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.47",
     "@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.47",
 			"license": "MIT"
 		},
-		"lastBuildTime": "2026-10-31 01:51:27"
+		"lastBuildTime": "2026-10-31 16:11:28"
 	};
 }
 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-2NkaM2/61JPKHd1FH61mYw=='; 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="2NkaM2/61JPKHd1FH61mYw==">{
   "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.47",
+  "@oj-module/runtime/contract": "0.2.47",
+  "@oj-module/runtime/contract/errors": "0.2.47",
   "@plane/kit": "0.1.20",
   "@plane/editor": "0.1.20",
   "antd": "6.6.1",

package/templates/config.yaml

@@ -9,7 +9,9 @@
 # 站点挂载：一行 = 一个 URL 前缀 + 一个目录（api/web 二选一）。
 # 这里不放 api 挂载是有意的：本工程是 src/<name>/{api,web} 布局，源码由 ojm dev
 # 以 --module-root src 供给、产物由 ojm preview 以 --api-path dist/api 供给，都不走 mounts。
-# 手写部署（不用 ojm）时才需要加回一条 `- prefix: /api` + `api: dist`。
+# 手写部署（不用 ojm）时才需要加回一条 `- prefix: /api` + `api: dist/api`。
+# 注意：手写部署同时要把下面 platform.root 从 `src` 改成 `dist/api`（二者必须同源），
+# 否则 oj serve 报 `platform.root must be mounted as an api mount`。
 mounts:
   # 本地市场 CDN：直出工程根 cdn/。seed 里 framework.market_cdn_url 缺省就是 /cdn，本站点自供免 setup。
   # 生产删掉这条，并把该设置指向真 CDN（绝对地址）。不能设 spa：缺文件必须 404，
@@ -55,20 +57,33 @@ vars:
   # canonical_origin: "https://your-site.example.com"
 
   # ---- 企业微信代开发（服务商侧，部署级常量）----
-  # 一个部署 = 一个服务商账号下的一套代开发模板，所以这 6 个值是「部署」维度，不进 DB。
+  # 一个部署 = 一个服务商账号下的一套代开发模板，所以这 8 个值是「部署」维度，不进 DB。
   # 「哪个企业装了哪个应用」不写在这里：企微 create_auth 回调推 AuthCode → 换永久授权码 →
   # 落 wecom_app_profile（主键含 agent_id，同一企业测试/正式两个应用天然并存），
   # 新增企业只需企业管理员扫码授权，**不改配置、不重启**。
-  # 六项任一为空 → 企微登录整体 400 拒绝服务（宁可不登录，也不明文存 permanent_code）。
-  #   wecom_suite_id          代开发应用模版 id（企微后台「应用管理 → 代开发」里的 SuiteID）
-  #   wecom_suite_secret      套件密钥（SuiteSecret）
+  # 分三层（来源与必填时序不同，破解「先有 suite 还是先有回调」死锁）：
+  #   · Tier A 本地生成、创建模版前即可配齐：callback_token / encoding_aes_key / enc_key / base_url；
+  #     任一为空 → 启动即 400 拒绝服务（宁可不登录，也不明文存 permanent_code）。
+  #   · Tier B 企微创建模版后下发：suite_id / suite_secret；为空时仍可启动并响应 echostr 验证，
+  #     仅 login/callback/create_auth 等 suite 流程会 400——先配 Tier A 跑通回调、建模版、拿 suite 再补全。
+  #   · Tier C 服务商后台「通用开发参数」页拿（不是企业、也不是 suite）：provider_id / provider_secret；
+  #     只供「生成授权链接」用（get_customized_auth_url 要 provider_access_token）。缺它不影响登录，
+  #     但 /system/wecom 点「生成开通链接」会 400 点名缺这两项。
+  #   wecom_suite_id          代开发应用「模板详情 → 基本信息」页里的「模板ID」（即 SuiteID）；创建模板成功后才出现
+  #   wecom_suite_secret      同页「模板Secret」（即 SuiteSecret，可重置）；不是企业 CorpID/CorpSecret
+  #   wecom_provider_id       服务商的 corpid（服务商自己的，不是企业 corpid）；**位置：服务商后台「服务商信息」页显示的 CorpID**
+  #   wecom_provider_secret   服务商 provider_secret；**位置：服务商后台 → 应用管理 → 通用开发参数（点「编辑」）→ ProviderSecret 字段**，
+  #                           **不在「服务商信息」页**（那里只显示 CorpID），也**不是** suite_secret（suite 那个是另一套）。
   #   wecom_callback_token    「Token」（回调验签用）
   #   wecom_encoding_aes_key  「EncodingAESKey」（43 字符，回调解密用）
   #   wecom_enc_key           permanent_code 落库加密密钥（hex/base64，16 或 32 字节；建议 oj secret keygen）
-  #   wecom_base_url          连接器基址（绝对地址，无尾斜杠），如 https://site.example.com/api/auth/wecom
-  #                           → 企微后台「指令回调URL」填 <base>/event；网页授权 redirect_uri 用 <base>/callback
+  #   wecom_base_url          连接器基址（绝对地址，无尾斜杠，**这是基址、不是回调 URL**），如 https://site.example.com/api/auth/wecom
+  #                           → 企微后台「指令回调URL」填 <base>/event（必须带 /event，裸 <base> 无 handler 会 404）；
+  #                             网页授权 redirect_uri 用 <base>/callback
   wecom_suite_id: ''
   wecom_suite_secret: ''
+  wecom_provider_id: ''
+  wecom_provider_secret: ''
   wecom_callback_token: ''
   wecom_encoding_aes_key: ''
   wecom_enc_key: ''
@@ -77,6 +92,10 @@ vars:
 platform:
   modules: [_platform] # 安装器热更 config 需要 _platform 特权；删了会在装到最后一步报 NotCapable
   root: src # 后端模块源码根（src/<name>/api 的父目录）；preview 派生 config 时改写成 dist
+  # ⚠️ 手写部署（不用 ojm，靠 mounts 起站）时：root 必须等于 api 挂载目录，
+  # 否则 oj serve 直接拒启 `platform.root (…) must be mounted as an api mount`。
+  # 编译产物下把这里改成 `dist/api`（与下面 `- prefix: /api  api: dist/api` 同源）。
+  # ojm dev/preview 不受影响：dev 用 --module-root、preview 派生 config 会重写 root。
   # 信任库默认落在安装子树之外（.solutions/trusted-keys.yaml），第三方方案模块碰不到。
   # U6 加固：第三方模块的 fs 读写范围 = fs.root（= modules/ 安装子树），信任库必须在其外，
   # 否则方案包可写自己的信任锚（伪造签名来源）。部署侧还应补 platform.trusted_paths 授权

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

@@ -12,8 +12,8 @@ import type { WecomClient } from "./client";
 import type { WecomConfig } from "./config";
 import type { WecomStoreDeps } from "./store";
 import { invalidateAllUsers } from "#/_platform/_shared/service/infra/access";
-import { eventUrlOf, installUrlOf } from "./config";
-import { corpScope, getSuiteTicket, revokeTenantSessions, tenantOfCorp } from "./store";
+import { assertProviderConfig, eventUrlOf } from "./config";
+import { corpScope, revokeTenantSessions, tenantOfCorp } from "./store";
 
 export interface WecomAdminDeps {
 	client: WecomClient
@@ -88,25 +88,30 @@ export async function setAppStatus(
 }
 
 export interface InstallResult {
+	/** 开通链接（代开发 = `get_customized_auth_url` 返回的 qrcode_url，企业管理员扫/开即授权） */
 	installUrl: string
 	/** 企微后台「指令回调 URL」应填这个（逐字） */
 	callbackUrl: string
+	/** 链接有效期（秒，以企微返回为准，可达 10 天） */
 	expiresIn: number
 }
 
-/** 生成开通入口：suite_access_token → 预授权码 → install URL（企业管理员点开即进入授权安装向导） */
+/**
+ * 生成开通入口（代开发）：provider_access_token → get_customized_auth_url → qrcode_url。
+ * 与第三方应用的「预授权码拼安装链接」不是一个接口——代开发**不支持** get_pre_auth_code
+ * （errcode 48002），必须用这个。授权完成由企微回调 create_auth 落库，与这里无关。
+ */
 export async function createInstall(
 	cfg: WecomConfig,
 	client: WecomClient,
-	store: WecomStoreDeps,
 	state: string,
 ): Promise<InstallResult> {
-	const ticket = await getSuiteTicket(cfg.suiteId, store);
-	const token = await client.suiteAccessToken(cfg.suiteId, cfg.suiteSecret, ticket.ticket);
-	const pre = await client.preAuthCode(token);
+	assertProviderConfig(cfg);
+	const providerToken = await client.providerAccessToken(cfg.providerId, cfg.providerSecret);
+	const auth = await client.customizedAuthUrl(providerToken, [cfg.suiteId], state);
 	return {
-		installUrl: installUrlOf(cfg, pre.code, state),
+		installUrl: auth.url,
 		callbackUrl: eventUrlOf(cfg),
-		expiresIn: pre.expiresIn,
+		expiresIn: auth.expiresIn,
 	};
 }

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

@@ -33,11 +33,36 @@ export interface WecomClientDeps {
 	cache: WecomCache
 }
 
+/**
+ * 软超时：服务端 isolate 无 `setTimeout` / `AbortSignal` 全局，不能用 `AbortSignal.timeout`。
+ * 这里用运行时注入的 `tasks.sleep(ms)` 起一个「到点就 reject」的竞态；fetch 不被真正 abort，
+ * 只是不再等它（后台连接最终由 OS/池回收）。`tasks` 不可用时降级为原 promise（无超时）。
+ * 输家 promise 在 race 结束后仍可能 reject，挂 `.catch` 防 unhandled rejection。
+ */
+function withSoftTimeout<T>(p: Promise<T>, ms: number): Promise<T> {
+	const g = globalThis as unknown as { tasks?: { sleep?: (ms: number) => Promise<void> } };
+	const sleep = g.tasks?.sleep;
+	if (typeof sleep !== "function")
+		return p;
+	const timeout = sleep(ms).then(
+		() => { throw new Error(`超时 ${ms}ms`); },
+		() => undefined as never, // sleep 自身异常不中断主链路（返回 never 以免 race 结果退化为 void | T）
+	);
+	return Promise.race([p, timeout]).finally(() => {
+		// 输家 promise 在 race 结束后仍可能 reject，挂 catch 防 unhandled rejection
+		timeout.catch(() => {});
+	});
+}
+
 export function runtimeHttp(): WecomHttp {
 	async function call(url: string, init: RequestInit): Promise<Record<string, unknown>> {
 		let res: Response;
 		try {
-			res = await fetch(url, { ...init, signal: AbortSignal.timeout(TIMEOUT_MS) });
+			// 服务端 isolate 无 `AbortSignal` / `setTimeout` 全局（见 oj-api-dev global.d.ts：
+			// 「本运行时无 timer 全局」），`AbortSignal.timeout()` 直接 ReferenceError。
+			// 用运行时提供的 `tasks.sleep` 做软超时（到点 reject；fetch 仍在后台跑、不 abort），
+			// 拿不到 tasks 时降级为「不超时」——网络层失败仍会被下面 catch 转成 502。
+			res = await withSoftTimeout(fetch(url, init), TIMEOUT_MS);
 		}
 		catch (e) {
 			throw upstream(`企微接口不可达：${(e as Error).message}`);
@@ -154,15 +179,49 @@ export function createWecomClient(deps: WecomClientDeps) {
 	}
 
 	/**
-	 * 预授权码（开通入口用）：套件级、10 分钟、一次有效，拼进 install URL 交给企业管理员点开。
-	 * 与 permanent_code 无关——它只换「安装向导里那一屏同意」，真正的永久码仍由 create_auth 回调给。
+	 * 服务商级 token（provider_access_token）：代开发「生成授权链接」用，与套件 token 不同源。
+	 * 由服务商 corpid + provider_secret 换得，全部署共享一份（不限 suite）。
+	 * 注意：这是**服务商**凭证，不是 suite 凭证——代开发的 `get_customized_auth_url`
+	 * 只认 provider_access_token（用 suite_access_token 调会报 token 无效类错误）。
 	 */
-	async function preAuthCode(suiteAccessToken: string): Promise<{ code: string, expiresIn: number }> {
-		const res = await http.postJson(`${API_BASE}/cgi-bin/service/get_pre_auth_code?suite_access_token=${encodeURIComponent(suiteAccessToken)}`, {});
-		assertOk(res, "get_pre_auth_code");
-		if (!res.pre_auth_code)
-			throw upstream("企微 get_pre_auth_code 未返回 pre_auth_code");
-		return { code: String(res.pre_auth_code), expiresIn: Number(res.expires_in ?? 600) };
+	async function providerAccessToken(providerId: string, providerSecret: string): Promise<string> {
+		return cachedToken("wecom:provider_token", async () => {
+			const res = await http.postJson(`${API_BASE}/cgi-bin/service/get_provider_token`, {
+				corpid: providerId,
+				provider_secret: providerSecret,
+			});
+			assertOk(res, "get_provider_token");
+			if (!res.provider_access_token)
+				throw upstream("企微 get_provider_token 未返回 provider_access_token");
+			return { token: String(res.provider_access_token), expiresIn: Number(res.expires_in ?? 7200) };
+		});
+	}
+
+	/**
+	 * 代开发授权链接（get_customized_auth_url）：返回 `qrcode_url`（即企业管理员要扫/开的开通链接，
+	 * 运营侧常称 auth_url）。**代开发明确不支持**第三方应用那个 `get_pre_auth_code`（errcode 48002），
+	 * 必须用本接口。链接有效期以企微返回为准（可达 10 天），state 透传给授权成功回调原样回传。
+	 * `templateid_list` 填代开发模板 ID（本系统即 suite_id，代开发模板与 suite 同标识）。
+	 */
+	async function customizedAuthUrl(providerAccessToken: string, templateIds: string[], state: string): Promise<{ url: string, expiresIn: number }> {
+		// state 必填（errcode 40058 state missing），限 ≤32 字节；调用方没传（前端目前不传）就给默认常量。
+		// 注：本系统开通链接不靠 state 携带 env（env 走登录链接），故空时给固定默认值即可。
+		const st = state ? state.slice(0, 32) : "ojmdaikaifa";
+		const res = await http.postJson(`${API_BASE}/cgi-bin/service/get_customized_auth_url?provider_access_token=${encodeURIComponent(providerAccessToken)}`, {
+			state: st,
+			templateid_list: templateIds,
+		});
+		// 842002 = 代开发模板未上架/上线：模板创建成功 ≠ 上线，必须到服务商后台
+		// 「应用管理 → 代开发应用上线」提交审核、审核通过后再手动「提交上线」，
+		// 模板正式上线后 get_customized_auth_url 才会生成 qrcode_url。这是后台运营前置动作，
+		// 与代码/参数/凭证无关（否则会先报 40058/60020/40001 之类）。单独挑出给可操作提示。
+		if (Number(res.errcode ?? 0) === 842002)
+			throw upstream("企微 get_customized_auth_url 失败：errcode=842002 代开发模板尚未上架/上线——请到服务商后台「应用管理 → 代开发应用上线」提交模板上线审核，审核通过后手动点「提交上线」，模板正式上线后再生成开通链接");
+		assertOk(res, "get_customized_auth_url");
+		const url = res.qrcode_url ?? res.auth_url;
+		if (!url)
+			throw upstream("企微 get_customized_auth_url 未返回 qrcode_url");
+		return { url: String(url), expiresIn: Number(res.expires_in ?? 7200) };
 	}
 
 	/** 企业 access_token（代开发 = 自建应用的 gettoken，corpsecret 就是 permanent_code） */
@@ -237,7 +296,7 @@ export function createWecomClient(deps: WecomClientDeps) {
 		throw upstream("企微 token 反复失效（40001/42001）");
 	}
 
-	return { suiteAccessToken, permanentCodeByAuthCode, preAuthCode, corpAccessToken, invalidateCorpToken, userIdByCode, userNameById };
+	return { suiteAccessToken, permanentCodeByAuthCode, providerAccessToken, customizedAuthUrl, corpAccessToken, invalidateCorpToken, userIdByCode, userNameById };
 }
 
 export type WecomClient = ReturnType<typeof createWecomClient>;

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,61 @@ 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
+	/**
+	 * 服务商 corpid（不是企业 corpid，是「服务商」自己的 corpid）。
+	 * 代开发「生成授权链接」走 `get_customized_auth_url`，该接口只认 provider_access_token，
+	 * 而 provider_access_token 由服务商 corpid + provider_secret 换得——与 suite 凭证不同源。
+	 */
+	providerId: string
+	/** 服务商 provider_secret（在服务商后台「通用开发参数」页拿，别和 suite_secret 搞混） */
+	providerSecret: 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"],
+];
+
+// Tier C：服务商凭证（provider_access_token 源）。**仅「生成授权链接」需要**，不影响
+// login/callback/create_auth 等 suite 流程，故不进 readWecomConfig 的必填集合（readWecomConfig
+// 被登录链路复用，缺 provider 凭证不该让登录 400）。createInstall 单独校验。
+const REQUIRED_PROVIDER: Array<[keyof WecomConfig, string]> = [
+	["providerId", "wecom_provider_id"],
+	["providerSecret", "wecom_provider_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") ?? "",
+		providerId: vars.get("wecom_provider_id") ?? "",
+		providerSecret: vars.get("wecom_provider_secret") ?? "",
+	};
+}
+
 /**
  * 落库密钥格式校验（fail-fast 在**读配置**处，而不是等 create_auth 时在 crypto 里炸）：
  * oj 的 aesGcmEncrypt 只收「16 或 32 字节的 hex/base64」，AES-192（24 字节）明确不支持。
@@ -60,26 +109,48 @@ export function assertEncKey(encKey: string): void {
 }
 
 /**
- * 读部署常量。缺任一必需项即 400（「未配置」是运维事实，不是服务端缺陷）：
- * 前半段（suite 凭据）缺失 → 企微登录整体不可用；encKey 缺失则 permanent_code 无法安全落库，
- * 宁可拒服务，也不退化成明文存储（§7.5 数据合规红线）。
+ * 校验服务商凭证（生成授权链接必需）。缺任一即 400 并点名缺哪两项——
+ * 区分于 suite 凭证：那是「模版创建后下发」，provider 凭证是「服务商后台通用开发参数」里拿的。
  */
-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 assertProviderConfig(cfg: WecomConfig): void {
+	const missing = REQUIRED_PROVIDER.filter(([field]) => !cfg[field]).map(([, name]) => name);
+	if (missing.length)
+		throw Object.assign(new Error(`企业微信未配置：生成授权链接需要 ${missing.join(" / ")}（服务商后台「通用开发参数」页获取，与 suite 凭证不同源）`), { status: 400 });
+}
+
+/**
+ * 读 Tier A 凭据（token / aeskey / encKey / baseUrl）。**不依赖 suite 凭据**：这是 echostr
+ * URL 验证与永久码落库加密所需的全部东西，部署方本地即可生成。引导期（suite_id 尚未下发）
+ * 服务也能靠它启动并响应企微的回调验证（plan §18）。
+ */
+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） */
@@ -110,22 +181,6 @@ export function siteRootOf(cfg: WecomConfig): string {
 	return `${url.origin}${path.slice(0, -CONNECTOR_SUFFIX.length)}`;
 }
 
-/**
- * 代开发「开通入口」：企业管理员点开 → 企微授权安装页。
- * `redirect_uri` 落在站点根下的登录页（安装完回站点，指令回调已把 profile 落好）。
- */
-export function installUrlOf(cfg: WecomConfig, preAuthCode: string, state: string): string {
-	const redirect = `${siteRootOf(cfg)}/login?wecom_installed=1`;
-	const q = new URLSearchParams({
-		suite_id: cfg.suiteId,
-		pre_auth_code: preAuthCode,
-		redirect_uri: redirect,
-	});
-	if (state)
-		q.set("state", state);
-	return `https://open.work.weixin.qq.com/3rdapp/install?${q.toString()}`;
-}
-
 /** 登录方式发现用：只看开关，不读凭据（登录页要先知道「有没有这个方式」） */
 export async function wecomEnabled(): Promise<boolean> {
 	const rows = await db.table("sys_setting").select(["value"]).where({ field: "key", op: "eq", value: "wecom.enabled" }).all() as Array<{ value: string | null }>;

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/admin/api.ts

@@ -12,7 +12,6 @@ import { recordOp } from "#/_platform/_shared/service/infra/audit";
 import { createInstall, listApps, setAppStatus } from "../../_shared/wecom/admin";
 import { createWecomClient, runtimeCache, runtimeHttp } from "../../_shared/wecom/client";
 import { readWecomConfig } from "../../_shared/wecom/config";
-import { runtimeStoreDeps } from "../../_shared/wecom/store";
 
 /** 清单：已授权企业 × 应用（不含 permanent_code，secret 不出库） */
 async function get() {
@@ -92,8 +91,10 @@ status.post.response = {
 };
 
 const install = {
-	// 开通入口：生成 install URL（预授权码 10 分钟有效，故不缓存，每次点都重新换）。
-	// 顺带回「指令回调 URL」——服务商后台要把它逐字填进企微「代开发」配置页。
+	// 开通入口（代开发）：provider_access_token → get_customized_auth_url → qrcode_url。
+	// 该接口**只**对代开发开放（第三方应用那个 get_pre_auth_code 对代开发报 48002）；
+	// 链接有效期以企微返回为准，故不缓存，每次点都重新换。顺带回「指令回调 URL」——
+	// 服务商后台要把它逐字填进企微「代开发」配置页。
 	async get() {
 		await respond(async () => {
 			await assertSuperAdmin();
@@ -102,7 +103,6 @@ const install = {
 			return createInstall(
 				cfg,
 				createWecomClient({ http: runtimeHttp(), cache: runtimeCache() }),
-				runtimeStoreDeps(cfg),
 				state,
 			);
 		});

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/src/login/web/auth-provider.ts

@@ -41,7 +41,15 @@ export const authProvider: AuthProvider = {
 	},
 
 	async logout(): Promise<void> {
-		await fetchLogout({ refreshToken: useAuthStore.getState().refreshToken });
+		// 服务端吊销是「尽力而为」：本地登出（runtime 的 finally → reset）才是真相，
+		// 网络/服务端超时（如反代 `proxy_read_timeout` 短于上游）不应让退出卡死或抛
+		// 未捕获异常（点击退出 → Uncaught TimeoutError）。失败仅记日志，不向上抛。
+		try {
+			await fetchLogout({ refreshToken: useAuthStore.getState().refreshToken });
+		}
+		catch (e) {
+			console.warn("[auth-provider] logout 服务端吊销失败（本地会话已清空）：", e);
+		}
 	},
 
 	getUserInfo: () => fetchUserInfo(),

package/templates/src/system/web/locales/en-US.json

@@ -79,7 +79,7 @@
 	},
 	"wecom": {
 		"title": "Onboard a corporation",
-		"hint": "Click \"Generate install link\" and send the link or QR code to the corporation's admin for approval. The callback on the corporation side writes the row into this table after approval. The link expires in 10 minutes and works once; the QR code greys out when it does, so regenerate it.",
+		"hint": "Click \"Generate install link\" and send the link or QR code to the corporation's admin to scan/open for approval. On success this system auto-registers the corporation via the create_auth callback (writes wecom_app_profile). The link is generated by WeCom get_customized_auth_url; its validity follows WeCom's response (up to 10 days). The QR code greys out when it expires, so regenerate it.",
 		"appsTitle": "Onboarded corporations",
 		"genInstall": "Generate install link",
 		"installOk": "Generated. Send the link to the corporation's admin.",

package/templates/src/system/web/locales/zh-CN.json

@@ -7,7 +7,7 @@
 		"oplog": "操作日志",
 		"settings": "站点设置",
 		"loginMethods": "登录方式",
-		"wecom": "企业微信代开发"
+		"wecom": "企微集成"
 	},
 	"common": {
 		"confirm": "确认",
@@ -79,7 +79,7 @@
 	},
 	"wecom": {
 		"title": "开通企业",
-		"hint": "点「生成开通链接」后把链接或二维码发给企业管理员，由其确认授权；确认后企业侧的回调会写入本表。链接 10 分钟内有效且只能用一次，过期后二维码会置灰，需重新生成。",
+		"hint": "点「生成开通链接」把链接或二维码发给企业管理员，由其扫码/打开授权；授权成功后本系统经 create_auth 回调自动登记该企业（落库 wecom_app_profile）。链接由企微 get_customized_auth_url 生成，有效期以企微返回为准（可达 10 天），过期后二维码置灰，可重新生成。",
 		"appsTitle": "已开通企业",
 		"genInstall": "生成开通链接",
 		"installOk": "已生成，请把链接发给企业管理员",

package/templates/src/system/web/pages/wecom/index.tsx

@@ -51,7 +51,8 @@ async function createInstall(): Promise<InstallInfo> {
  * 企微代开发后台（服务商运营面，superadmin 独占）：
  *   · 已授权企业 × 应用清单（同一企业测试/正式两个应用各一行）；
  *   · 启停（停用企业最后一个应用时后端同时吊销该企业会话）；
- *   · 开通入口（预授权码 10 分钟有效，每次点都重新换）。
+ *   · 开通入口（点「生成开通链接」→ 后端调企微 get_customized_auth_url 换 qrcode_url，
+ *     企业管理员扫/开即授权，授权成功由 create_auth 回调落库）。
  */
 export default function WecomAdminPage() {
 	const { t } = useTranslation();

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

@@ -15,7 +15,7 @@ import { afterEach, beforeAll, beforeEach, describe, expect, it } from "vitest";
 import { assertSuperAdmin, invalidateAllUsers } from "../src/_platform/api/_shared/service/infra/access";
 import { listApps, setAppStatus } from "../src/auth/api/_shared/wecom/admin";
 import { createWecomClient, runtimeCache, runtimeHttp } from "../src/auth/api/_shared/wecom/client";
-import { installUrlOf, readWecomConfig, siteRootOf } from "../src/auth/api/_shared/wecom/config";
+import { readWecomConfig } from "../src/auth/api/_shared/wecom/config";
 import { installDb } from "./fixture";
 
 const g = globalThis as any;
@@ -51,6 +51,8 @@ function installVars(overrides: Record<string, string> = {}): void {
 	const base: Record<string, string> = {
 		wecom_suite_id: SUITE,
 		wecom_suite_secret: "suite_secret",
+		wecom_provider_id: "provider_1",
+		wecom_provider_secret: "provider_secret",
 		wecom_callback_token: "cb_token",
 		wecom_encoding_aes_key: AES_KEY_B64.replace(/=$/, ""),
 		wecom_enc_key: "0123456789abcdef0123456789abcdef",
@@ -97,10 +99,6 @@ function seedCorp(corpId = "ww_corp_a", agentId = "100001", env = "prod", status
 		.run(SUITE, corpId, agentId, authCorpId, env, `企业 ${corpId}`, status, `gcm(perm_${corpId}_${agentId})`, NOW, NOW);
 }
 
-function seedTicket(ticket = "tk_9", expiresAt = NOW + 1800): void {
-	dbo.prepare("INSERT INTO wecom_suite_ticket (suite_id, suite_ticket, expires_at, update_time) VALUES (?, ?, ?, ?)").run(SUITE, ticket, expiresAt, NOW);
-}
-
 function mkUser(username: string, roles: string[] = []): number {
 	dbo.prepare("INSERT INTO users (username, password_hash) VALUES (?, 'x')").run(username);
 	const id = (dbo.prepare("SELECT id FROM users WHERE username = ?").get(username) as { id: number }).id;
@@ -124,10 +122,10 @@ function fakeClient(): { client: any, invalidated: string[] } {
 
 const deps = { store: { encrypt: (p: string) => `gcm(${p})`, decrypt: (b: string) => b, now: () => NOW } };
 
-/** createInstall 的薄包装：store.now 固定，避免用例依赖真实时钟 */
+/** createInstall 的薄包装：省掉动态 import 的样板 */
 async function createInstallForTest(cfg: ReturnType<typeof readWecomConfig>, client: ReturnType<typeof createWecomClient>, state: string) {
 	const { createInstall } = await import("../src/auth/api/_shared/wecom/admin");
-	return createInstall(cfg, client, deps.store, state);
+	return createInstall(cfg, client, state);
 }
 
 const api = async () => (await import("../src/auth/api/wecom/admin/api")).default;
@@ -251,70 +249,93 @@ describe("P3-B：启停（setAppStatus）", () => {
 	});
 });
 
-describe("P3-C：开通入口（createInstall）", () => {
-	function stubUpstream(preAuth = "PRE_1", expiresIn = 600): string[] {
+describe("P3-C：开通入口（createInstall，代开发 get_customized_auth_url）", () => {
+	// 代开发**不支持** get_pre_auth_code（48002）：本段钉死调用链走 provider_access_token +
+	// get_customized_auth_url，绝不回退到第三方应用的预授权码接口。
+	function stubUpstream(qrcodeUrl = "https://open.work.weixin.qq.com/3rdservice/QR_1", expiresIn = 7200): { calls: string[], bodies: any[] } {
 		const calls: string[] = [];
-		g.fetch = async (url: string) => {
+		const bodies: any[] = [];
+		g.fetch = async (url: string, init?: any) => {
 			calls.push(url);
+			bodies.push(init?.body ? JSON.parse(init.body) : null);
 			return {
 				ok: true,
 				json: async () => {
-					if (url.includes("get_suite_token"))
-						return { suite_access_token: "suite_tk", expires_in: 7200 };
-					if (url.includes("get_pre_auth_code"))
-						return { pre_auth_code: preAuth, expires_in: expiresIn };
+					if (url.includes("get_provider_token"))
+						return { provider_access_token: "prov_tk", expires_in: 7200 };
+					if (url.includes("get_customized_auth_url"))
+						return { qrcode_url: qrcodeUrl, expires_in: expiresIn };
 					throw new Error(`stub fetch 未预期：${url}`);
 				},
 			};
 		};
-		return calls;
+		return { calls, bodies };
 	}
 
-	it("suite_ticket → suite_token → 预授权码 → install URL（redirect_uri 落站点根登录页）", async () => {
-		seedTicket();
-		const calls = stubUpstream();
+	it("provider_token → get_customized_auth_url → qrcode_url（即开通链接），且绝不调 get_pre_auth_code", async () => {
+		const { calls, bodies } = stubUpstream();
 		const cfg = readWecomConfig();
 		const client = createWecomClient({ http: runtimeHttp(), cache: runtimeCache() });
 
 		const r = await createInstallForTest(cfg, client, "st_1");
-		expect(calls.some(u => u.includes("get_suite_token"))).toBe(true);
-		expect(calls.some(u => u.includes("get_pre_auth_code"))).toBe(true);
+		expect(calls.some(u => u.includes("get_provider_token"))).toBe(true);
+		expect(calls.some(u => u.includes("get_customized_auth_url"))).toBe(true);
+		// 代开发 48002 的根因就是错用了 get_pre_auth_code——这条断言防止回归
+		expect(calls.some(u => u.includes("get_pre_auth_code"))).toBe(false);
+
+		const body = bodies.find(b => b && b.templateid_list) as any;
+		expect(body).toBeTruthy();
+		// get_customized_auth_url 要求 state 必填（errcode 40058 state missing）：本系统必传、非空
+		expect(body.state).toBe("st_1");
+		expect(body.templateid_list).toEqual([SUITE]);
+
+		expect(r.installUrl).toBe("https://open.work.weixin.qq.com/3rdservice/QR_1");
 		expect(r.callbackUrl).toBe("https://site.example.com/api/auth/wecom/event");
-		expect(r.expiresIn).toBe(600);
-
-		const url = new URL(r.installUrl);
-		expect(`${url.origin}${url.pathname}`).toBe("https://open.work.weixin.qq.com/3rdapp/install");
-		expect(url.searchParams.get("suite_id")).toBe(SUITE);
-		expect(url.searchParams.get("pre_auth_code")).toBe("PRE_1");
-		expect(url.searchParams.get("redirect_uri")).toBe("https://site.example.com/login?wecom_installed=1");
-		expect(url.searchParams.get("state")).toBe("st_1");
+		expect(r.expiresIn).toBe(7200);
 	});
 
-	it("子路径部署：redirect_uri 保留 /oj（回跳不落到宿主机根）", () => {
-		installVars({ wecom_base_url: "https://site.example.com/oj/api/auth/wecom" });
+	it("调用方没传 state 时仍发默认 state（避免 40058 state missing）", async () => {
+		const { bodies } = stubUpstream();
 		const cfg = readWecomConfig();
-		expect(siteRootOf(cfg)).toBe("https://site.example.com/oj");
-		const url = new URL(installUrlOf(cfg, "PRE_1", ""));
-		expect(url.searchParams.get("redirect_uri")).toBe("https://site.example.com/oj/login?wecom_installed=1");
-		// state 为空时不出现在 URL 里（不塞空串进去骗企微后台）
-		expect(url.searchParams.has("state")).toBe(false);
+		const client = createWecomClient({ http: runtimeHttp(), cache: runtimeCache() });
+		await createInstallForTest(cfg, client, "");
+		const body = bodies.find(b => b && b.templateid_list) as any;
+		expect(body.state).toBeTruthy();
+		expect(body.state.length).toBeLessThanOrEqual(32);
 	});
 
-	it("缺 suite_ticket（回调未打通/已过期）→ 503，不白跑一趟上游", async () => {
-		const calls = stubUpstream();
+	it("缺 provider 凭证（wecom_provider_id / wecom_provider_secret）→ 400 并点名缺哪两个 vars", async () => {
+		installVars({ wecom_provider_id: "", wecom_provider_secret: "" });
 		const cfg = readWecomConfig();
 		const client = createWecomClient({ http: runtimeHttp(), cache: runtimeCache() });
-		await expect(createInstallForTest(cfg, client, "")).rejects.toMatchObject({ status: 503 });
-		expect(calls).toEqual([]);
+		await expect(createInstallForTest(cfg, client, "")).rejects.toMatchObject({ status: 400 });
 	});
 
-	it("上游 errcode → 502（可重试语义，不是 500）", async () => {
-		seedTicket();
-		g.fetch = async () => ({ ok: true, json: async () => ({ errcode: 40001, errmsg: "invalid credential" }) });
+	it("上游 errcode（如 provider_secret 错）→ 502（可重试语义，不是 500）", async () => {
+		g.fetch = async () => ({ ok: true, json: async () => ({ errcode: 40001, errmsg: "invalid provider secret" }) });
 		const cfg = readWecomConfig();
 		const client = createWecomClient({ http: runtimeHttp(), cache: runtimeCache() });
 		await expect(createInstallForTest(cfg, client, "")).rejects.toMatchObject({ status: 502 });
 	});
+
+	it("get_customized_auth_url 返回 842002（模板未上架/上线）→ 502 且提示去后台提交上线（运营动作，非代码缺陷）", async () => {
+		g.fetch = async (url: string) => ({
+			ok: true,
+			json: async () => {
+				if (url.includes("get_provider_token"))
+					return { provider_access_token: "prov_tk", expires_in: 7200 };
+				if (url.includes("get_customized_auth_url"))
+					return { errcode: 842002, errmsg: "template not on shelves" };
+				throw new Error(`stub fetch 未预期：${url}`);
+			},
+		});
+		const cfg = readWecomConfig();
+		const client = createWecomClient({ http: runtimeHttp(), cache: runtimeCache() });
+		await expect(createInstallForTest(cfg, client, "st_1")).rejects.toMatchObject({
+			status: 502,
+			message: expect.stringContaining("代开发模板尚未上架/上线"),
+		});
+	});
 });
 
 describe("P3-D：端点接线（/auth/wecom/admin/*）", () => {

package/templates/tests/wecom-client-timeout.spec.ts

@@ -0,0 +1,99 @@
+// 回归：企微 API 客户端在「服务端 isolate」下的超时与崩溃防护。
+//
+// 真实 oj 服务端 isolate 没有 `AbortSignal` 全局，也没有 `setTimeout`
+// （oj-api-dev global.d.ts：「本运行时无 timer 全局，setTimeout 不可用」）。
+// 旧实现 `fetch(url, { signal: AbortSignal.timeout(ms) })` 会直接 ReferenceError
+// → 所有企微调用（换 token / 生成开通链接 / 登录）一律 502。
+// 这里在测试里**模拟**该 isolate（删掉 AbortSignal、tasks 视情况），断言：
+//   1. 无 AbortSignal 时调用照常工作（不抛 `AbortSignal is not defined`）；
+//   2. 不再把 `signal` 传给 fetch（旧 bug 的根）；
+//   3. tasks.sleep 存在 → 慢请求被软超时拦截并抛「超时」文案；
+//   4. tasks 缺失 → 安全降级为「不超时」，快速请求正常返回。
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { runtimeHttp } from "../src/auth/api/_shared/wecom/client";
+
+const g = globalThis as any;
+
+let savedAbortSignal: unknown;
+let savedTasks: unknown;
+let savedFetch: unknown;
+
+beforeEach(() => {
+	savedAbortSignal = (globalThis as { AbortSignal?: unknown }).AbortSignal;
+	savedTasks = g.tasks;
+	savedFetch = g.fetch;
+});
+
+afterEach(() => {
+	Object.defineProperty(globalThis, "AbortSignal", { value: savedAbortSignal, configurable: true, writable: true });
+	g.tasks = savedTasks;
+	g.fetch = savedFetch;
+});
+
+describe("wecom client：无 AbortSignal 的 isolate 不崩（回归）", () => {
+	it("abortSignal 被删掉时，getJson/postJson 仍能调用企微接口", async () => {
+		// 模拟服务端 isolate：把 AbortSignal 强制为 undefined（兼覆盖「整类不存在」与「.timeout 缺失」两种形态）
+		Object.defineProperty(globalThis, "AbortSignal", { value: undefined, configurable: true, writable: true });
+		g.tasks = undefined;
+
+		const fetchMock = vi.fn(async () => ({
+			ok: true,
+			json: async () => ({ errcode: 0, suite_access_token: "TOK", expires_in: 7200 }),
+		}));
+		g.fetch = fetchMock;
+
+		const http = runtimeHttp();
+		const data = await http.postJson("https://qyapi.weixin.qq.com/cgi-bin/service/get_suite_token", { a: 1 });
+		expect(data.errcode).toBe(0);
+		expect(fetchMock).toHaveBeenCalledTimes(1);
+	});
+
+	it("不再把 signal 传给 fetch（旧实现传 AbortSignal.timeout 的结果）", async () => {
+		Object.defineProperty(globalThis, "AbortSignal", { value: undefined, configurable: true, writable: true });
+		g.tasks = undefined;
+
+		const fetchMock = vi.fn(async () => ({ ok: true, json: async () => ({ errcode: 0 }) }));
+		g.fetch = fetchMock;
+
+		await runtimeHttp().getJson("https://qyapi.weixin.qq.com/x");
+		const [, init] = fetchMock.mock.calls[0];
+		expect(init.signal).toBeUndefined();
+	});
+
+	it("abortSignal.timeout 绝不被调用（防止旧 bug 回潮）", async () => {
+		const spy = vi.spyOn(globalThis.AbortSignal as { timeout: (ms: number) => unknown }, "timeout");
+		g.tasks = undefined;
+		g.fetch = vi.fn(async () => ({ ok: true, json: async () => ({ errcode: 0 }) }));
+
+		await runtimeHttp().getJson("https://qyapi.weixin.qq.com/x");
+		expect(spy).not.toHaveBeenCalled();
+		spy.mockRestore();
+	});
+});
+
+describe("wecom client：软超时（tasks.sleep）", () => {
+	it("tasks.sleep 存在时，慢请求被软超时拦截并抛出「超时」文案", async () => {
+		// 用立即 resolve 的 sleep 模拟（不真的等 TIMEOUT_MS，测试秒级完成）
+		g.tasks = { sleep: () => Promise.resolve() };
+		let resolveFetch: (v: unknown) => void = () => {};
+		const fetchMock = vi.fn(() => new Promise<unknown>((resolve) => {
+			resolveFetch = resolve;
+		}));
+		g.fetch = fetchMock;
+
+		const p = runtimeHttp().getJson("https://qyapi.weixin.qq.com/x");
+		await expect(p).rejects.toThrow(/超时/);
+		// 收尾挂起的 fetch，避免 open handle
+		resolveFetch({ ok: true, json: async () => ({ errcode: 0 }) });
+	});
+
+	it("tasks 缺失时降级为不超时：快速请求正常返回", async () => {
+		g.tasks = undefined;
+		const fetchMock = vi.fn(async () => ({ ok: true, json: async () => ({ errcode: 0 }) }));
+		g.fetch = fetchMock;
+
+		const data = await runtimeHttp().getJson("https://qyapi.weixin.qq.com/x");
+		expect(data.errcode).toBe(0);
+	});
+});

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

@@ -19,8 +19,8 @@ import { createWecomClient, runtimeCache } from "../src/auth/api/_shared/wecom/c
 import {
 	assertEncKey,
 	eventUrlOf,
-	installUrlOf,
 	loginRedirectOf,
+	readCallbackConfig,
 	readWecomConfig,
 	siteRootOf,
 } from "../src/auth/api/_shared/wecom/config";
@@ -620,7 +620,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 要原样填进后台）", () => {
@@ -638,8 +667,6 @@ describe("P1-J：部署常量读取（缺项一次报全 / 密钥格式 fail-fas
 		expect(siteRootOf(cfg)).toBe("https://site.example.com/oj");
 		expect(loginLandingUrl({ origin: siteRootOf(cfg), ticket: "tk", tenant: "ww_corp_a" }))
 			.toBe("https://site.example.com/oj/login?wecom_ticket=tk&tenant=ww_corp_a");
-		// 开通入口的 redirect_uri 同样要带子路径
-		expect(installUrlOf(cfg, "PAC1", "env=prod")).toContain(`redirect_uri=${encodeURIComponent("https://site.example.com/oj/login?wecom_installed=1")}`);
 	});
 
 	it("baseUrl 后缀不对 → 400（宁可拒，也不猜站点根拼出错误回跳）", () => {

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.47",
+		"@oj-module/runtime/contract": "0.2.47",
+		"@oj-module/runtime/contract/errors": "0.2.47",
 		"@plane/kit": "0.1.20",
 		"@plane/editor": "0.1.20",
 		"antd": "6.6.1",