@oj-module/cli 0.2.47 → 0.2.49

package/templates/src/auth/api/manifest.yaml

@@ -7,6 +7,9 @@ tables:
   - wecom_app_profile
   - wecom_suite_ticket
   - wecom_login_ticket
+  # 0002 组织架构同步：租户表（与上面三张共享表定性相反，见 schema.yaml）
+  - wecom_sync_job
+  - wecom_sync_lock
 deps: # 两处都用：login/refresh 读 _platform.users（ownership_guard: deny，§3/S003）；
   # 跨模块别名 `#/_platform/…` 的依赖门禁（oj build S008）
   _platform: ^0.1.0

package/templates/src/auth/api/migrations/0002__org_sync.mysql.sql

@@ -0,0 +1,28 @@
+-- 企微组织架构同步 mysql 方言覆盖（方言覆盖必胜，通用兜底；oj-bin docs/migration.md §3.1）。
+-- 差异：TEXT 主键须给长度（按业务长度收窄为 VARCHAR）；INTEGER → BIGINT（秒级 epoch / 毫秒标记）；
+-- 索引写在 CREATE TABLE 内（MySQL 无 CREATE INDEX IF NOT EXISTS）。
+ALTER TABLE wecom_app_profile ADD COLUMN auth_mode BIGINT NOT NULL DEFAULT 0;
+
+CREATE TABLE IF NOT EXISTS wecom_sync_job (
+  tenant_id VARCHAR(64) NOT NULL,
+  corp_id VARCHAR(64) NOT NULL,
+  agent_id VARCHAR(32) NOT NULL,
+  status VARCHAR(16) NOT NULL DEFAULT 'idle',
+  phase VARCHAR(16) NOT NULL DEFAULT 'departments',
+  cursor_text TEXT,
+  stats_text TEXT,
+  err_code VARCHAR(32),
+  err_detail VARCHAR(512),
+  started_at BIGINT NOT NULL DEFAULT 0,
+  finished_at BIGINT NOT NULL DEFAULT 0,
+  update_time BIGINT NOT NULL,
+  PRIMARY KEY (tenant_id, agent_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+CREATE TABLE IF NOT EXISTS wecom_sync_lock (
+  tenant_id VARCHAR(64) NOT NULL,
+  agent_id VARCHAR(32) NOT NULL,
+  owner VARCHAR(64) NOT NULL,
+  taken_at BIGINT NOT NULL,
+  PRIMARY KEY (tenant_id, agent_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

package/templates/src/auth/api/migrations/0002__org_sync.pg.sql

@@ -0,0 +1,27 @@
+-- 企微组织架构同步 pg 方言覆盖（方言覆盖必胜，通用兜底；oj-bin docs/migration.md §3.1）。
+-- 差异：INTEGER → BIGINT（秒级 epoch / 毫秒标记）；TEXT 在 pg 合法，键列保留 TEXT。
+ALTER TABLE wecom_app_profile ADD COLUMN auth_mode BIGINT NOT NULL DEFAULT 0;
+
+CREATE TABLE IF NOT EXISTS wecom_sync_job (
+  tenant_id TEXT NOT NULL,
+  corp_id TEXT NOT NULL,
+  agent_id TEXT NOT NULL,
+  status TEXT NOT NULL DEFAULT 'idle',
+  phase TEXT NOT NULL DEFAULT 'departments',
+  cursor_text TEXT,
+  stats_text TEXT,
+  err_code TEXT,
+  err_detail TEXT,
+  started_at BIGINT NOT NULL DEFAULT 0,
+  finished_at BIGINT NOT NULL DEFAULT 0,
+  update_time BIGINT NOT NULL,
+  PRIMARY KEY (tenant_id, agent_id)
+);
+
+CREATE TABLE IF NOT EXISTS wecom_sync_lock (
+  tenant_id TEXT NOT NULL,
+  agent_id TEXT NOT NULL,
+  owner TEXT NOT NULL,
+  taken_at BIGINT NOT NULL,
+  PRIMARY KEY (tenant_id, agent_id)
+);

package/templates/src/auth/api/migrations/0002__org_sync.sql

@@ -0,0 +1,41 @@
+-- 企微组织架构同步（B2）：授权模式快照 + 同步任务 / 抢锁。
+--
+-- auth_mode 存在 profile 上而不是部署常量：它由 get_permanent_code 在「企业授权」时刻返回，
+-- 是 (suite, corp, agent) 三元组的属性。**成员授权（1）下应用无任何部门权限**，通讯录类接口
+-- 一律 60011（方案 §2.3），所以它是同步入口的准入判据——400 拒绝，而不是跑成一片 60011。
+--
+-- 两张同步表都是**租户表**（不进 config.yaml 的 tenant.shared_allow）：同步只在调用方自己的
+-- 租户内跑（§3 D7），跨租户只由 superadmin 面读元数据，且那也走显式 tenant_id 的裸 SQL。
+--
+-- 抢锁用「复合主键插入」：INSERT 撞唯一约束是唯一可靠的原子判据。反过来用 status='running'
+-- 的读改写会留下竞态窗口，而 affected-rows 在三方言口径不一致、不能用来判成败（SKILL.md）。
+ALTER TABLE wecom_app_profile ADD COLUMN auth_mode INTEGER NOT NULL DEFAULT 0;
+
+CREATE TABLE IF NOT EXISTS wecom_sync_job (
+  tenant_id TEXT NOT NULL,
+  corp_id TEXT NOT NULL,
+  agent_id TEXT NOT NULL,
+  -- idle / running / done / failed / cancelled
+  status TEXT NOT NULL DEFAULT 'idle',
+  -- departments / members / reconcile
+  phase TEXT NOT NULL DEFAULT 'departments',
+  -- 续跑游标（JSON）：BFS 队列 + 已见部门 + 本轮进度标记。isolate 无定时器，进度只能靠调用方轮询推进
+  cursor_text TEXT,
+  -- 计数（JSON）：departments / members / deptSkipped / memberSkipped
+  stats_text TEXT,
+  -- 只存脱敏后的结构化错码，绝不存异常原文（异常里可能夹带 URL 上的 token，§7）
+  err_code TEXT,
+  err_detail TEXT,
+  started_at INTEGER NOT NULL DEFAULT 0,
+  finished_at INTEGER NOT NULL DEFAULT 0,
+  update_time INTEGER NOT NULL,
+  PRIMARY KEY (tenant_id, agent_id)
+);
+
+CREATE TABLE IF NOT EXISTS wecom_sync_lock (
+  tenant_id TEXT NOT NULL,
+  agent_id TEXT NOT NULL,
+  owner TEXT NOT NULL,
+  taken_at INTEGER NOT NULL,
+  PRIMARY KEY (tenant_id, agent_id)
+);

package/templates/src/auth/api/schema.yaml

@@ -23,6 +23,8 @@ tables:
       status: {type: text, null: false}
       # permanent_code（= 代开发应用的 secret）的 AES-GCM 密文，禁止明文落库
       permanent_code_enc: {type: text, null: false}
+      # 0=管理员授权 / 1=成员授权（0002）：成员授权下应用无任何部门权限，组织架构同步必然 60011
+      auth_mode: {type: integer, null: false}
       installed_at: {type: integer, null: false}
       update_time: {type: integer, null: false}
   wecom_suite_ticket:
@@ -46,3 +48,32 @@ tables:
       expires_at: {type: integer, null: false}
       used: {type: integer, null: false}
       created_at: {type: integer, null: false}
+  # 组织架构同步（0002）：**租户表**（不进 shared_allow）——同步只在调用方自己的租户内跑，
+  # 没有「查它时还不知道租户」的时刻；跨租户只由 superadmin 面读元数据。
+  wecom_sync_job:
+    pk: [tenant_id, agent_id]
+    columns:
+      tenant_id: {type: text, null: false}
+      corp_id: {type: text, null: false}
+      agent_id: {type: text, null: false}
+      # idle / running / done / failed / cancelled
+      status: {type: text, null: false}
+      # departments / members / reconcile
+      phase: {type: text, null: false}
+      # 续跑游标与计数都是 JSON 文本：字段演进不该每次都动三方言迁移
+      cursor_text: {type: text}
+      stats_text: {type: text}
+      # 只存脱敏后的结构化错码（异常原文可能夹带 URL 上的 token，§7）
+      err_code: {type: text}
+      err_detail: {type: text}
+      started_at: {type: integer, null: false}
+      finished_at: {type: integer, null: false}
+      update_time: {type: integer, null: false}
+  wecom_sync_lock:
+    pk: [tenant_id, agent_id]
+    columns:
+      tenant_id: {type: text, null: false}
+      agent_id: {type: text, null: false}
+      # 抢锁者标识（请求 id），只用于日志对账
+      owner: {type: text, null: false}
+      taken_at: {type: integer, null: false}

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

@@ -24,7 +24,7 @@ get.response = {
 	type: "array",
 	items: {
 		type: "object",
-		required: ["suite_id", "corp_id", "agent_id", "auth_corp_id", "env", "status", "installed_at", "update_time"],
+		required: ["suite_id", "corp_id", "agent_id", "auth_corp_id", "env", "status", "auth_mode", "installed_at", "update_time"],
 		properties: {
 			suite_id: { type: "string" },
 			corp_id: { type: "string" },
@@ -33,6 +33,8 @@ get.response = {
 			env: { type: "string" },
 			corp_name: { type: ["string", "null"] },
 			status: { type: "string", enum: ["active", "disabled"] },
+			// 权限三态（管理员授权 / 成员授权）——服务商一眼看出哪家企业「装了但同步不了」
+			auth_mode: { type: "number" },
 			installed_at: { type: "number" },
 			update_time: { type: "number" },
 		},

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

@@ -1,4 +1,6 @@
 import type { WecomConfig } from "../_shared/wecom/config";
+import type { CallbackFields } from "../_shared/wecom/payload";
+import type { ReplayClaim } from "../_shared/wecom/replay";
 import type { WecomStoreDeps } from "../_shared/wecom/store";
 // GET  /api/auth/wecom/login?corp=&agent=&env=  —— 发起企微授权（企微内静默 / 浏览器扫码）
 // GET  /api/auth/wecom/callback?code=&state=     —— 企微回跳：code→userid→JIT→一次性票据→302 SPA
@@ -18,20 +20,22 @@ import { clientIp, guardLoginThrottle, noteLoginFailed, noteLoginSucceeded } fro
 import { createSession } from "../_shared/session";
 import { createWecomClient, runtimeCache, runtimeHttp } from "../_shared/wecom/client";
 import { loginRedirectOf, readCallbackConfig, readWecomConfig, siteRootOf } from "../_shared/wecom/config";
-import { unwrapWecomMessage, wecomSignature } from "../_shared/wecom/crypt";
+import { sha1Hex, unwrapWecomMessage, wecomSignature } from "../_shared/wecom/crypt";
 import { handleSuiteEvent } from "../_shared/wecom/events";
 import {
 	assertUserActive,
 	buildAuthorizeUrl,
+	resolveWecomProfile,
 	ensureWecomUser,
 	LOGIN_TICKET_TTL_SECS,
 	loginLandingUrl,
 	putLoginState,
+	selfUpdate,
 	takeLoginState,
 } from "../_shared/wecom/login";
-import { guardReplay, runtimeReplayGate } from "../_shared/wecom/replay";
+import { callbackFields, field } from "../_shared/wecom/payload";
+import { guardReplay, runtimeReplayGate, ReplayAlreadyApplied, markApplied } from "../_shared/wecom/replay";
 import { claimLoginTicket, ensureTenant, findProfile, issueLoginTicket, runtimeStoreDeps, tenantOfCorp } from "../_shared/wecom/store";
-import { xmlField } from "../_shared/wecom/xml";
 
 // 模块级禁止 readWecomConfig()/createSession()/runtimeHttp()：oj build 的 introspect 在空沙箱里
 // 评估模块（无 vars/jwt/fetch），一律在 handler 内按需构造（§9.4）。
@@ -49,7 +53,7 @@ function query(name: string): string {
 
 /** 纯文本 200（企微事件回执专用；信封会被判失败并触发重推） */
 function plainText(body: string): void {
-	const stream = json.stream({ contentType: "text/plain; charset=utf-8" });
+	const stream = json.stream({ contentType: "text/plain; charset=utf-8", status: 200 });
 	stream.write(body);
 	stream.end();
 }
@@ -58,6 +62,62 @@ function badRequest(message: string): Error {
 	return Object.assign(new Error(message), { status: 400 });
 }
 
+/**
+ * 解不开时把「哪一侧配错」记进日志——只回一句 `pkcs7: bad padding` 等于没给线索。
+ *
+ * 能先验签通过才走到解密，说明后台 Token 与本部署一致；于是解不开只剩两类：
+ *   · `bad padding` → **钥匙不对**：EncodingAESKey 与后台不一致（后台点过「随机生成」、或抄错/抄漏
+ *     一个字符），或这条推送其实来自另一个套件/模板（那把钥匙解不开这份密文）。
+ *     `aesKeyFp` 是本进程**实际加载**那把钥匙的指纹：改完 config 对不上就说明没生效（没重启/改错文件）。
+ *   · `receiver mismatch` → **钥匙对、身份不对**。`receiveid` 已按候选试过（见 unwrapAccepting：
+ *     suite_id + 信封 `ToUserName`），两边都对不上只剩两种：信封里没有 `ToUserName`，或这条推送
+ *     既不属本部署套件、receiveid 也不是它自己声称的身份（伪造/转发）。
+ *
+ * 注意 `envelopeToUser` **不等于** `configuredSuite` 是正常的：数据回调的 `ToUserName` 是 corpid。
+ */
+function noteDecryptFailure(e: unknown, envelope: CallbackFields | null, cfg: { encodingAesKey: string, suiteId: string }): void {
+	log.warn(
+		"wecom callback decrypt failed",
+		"reason",
+		(e as Error).message,
+		"envelopeToUser",
+		// URL 验证（GET）只有 query 里的 echostr，没有报文信封——那一侧记空串
+		envelope ? field(envelope, "ToUserName") : "",
+		"configuredSuite",
+		cfg.suiteId,
+		"aesKeyFp",
+		sha1Hex(cfg.encodingAesKey).slice(0, 8),
+	);
+}
+
+/**
+ * 按「可能合法的 receiveid」依次尝试解密。
+ *
+ * receiveid 的含义随场景变（90968 附注）：**第三方事件的回调是 suiteid**（suite_ticket / create_auth
+ * / cancel_auth），**企业应用（含代开发应用的数据回调）是 corpid**（通讯录变更就走这条）。
+ * 我们一个端点吃两种，只认 suiteid 会把所有数据回调判成「解密失败」——而真正的错是「比错了值」。
+ *
+ * 只对 `receiver mismatch` 换下一个候选：`bad padding` 说明密钥就不对，换谁都解不开，直接抛。
+ */
+function unwrapAccepting(encrypted: string, cfg: WecomConfig, candidates: string[]): string {
+	let lastErr: unknown;
+	const tried = new Set<string>();
+	for (const receiver of candidates) {
+		if (!receiver || tried.has(receiver))
+			continue;
+		tried.add(receiver);
+		try {
+			return unwrapWecomMessage(encrypted, cfg.encodingAesKey, receiver);
+		}
+		catch (e) {
+			if (!/receiver mismatch/.test((e as Error).message))
+				throw e;
+			lastErr = e;
+		}
+	}
+	throw lastErr ?? new Error("wecom: 没有可比对的 receiveid（suite_id 未配置？）");
+}
+
 /**
  * 校验企微回调签名并解出明文。签名不合法 → 400（不是 401：调用方是企微服务器，
  * 401 会被当成「本站需要鉴权」误导排查）；信封里的原文不回显，避免给探测者提供比对材料。
@@ -65,44 +125,66 @@ function badRequest(message: string): Error {
  * 三道顺序不可换：先验签（不给未鉴权请求写 kv）→ 再拦重放（省一次解密，也让
  * cancel_auth 这种危险性最高的报文止步在落库之前）→ 最后解密。
  */
-async function decryptVerified(encrypted: string): Promise<{ cfg: WecomConfig, plain: string }> {
+async function decryptVerified(encrypted: string, envelope: CallbackFields): Promise<{ cfg: WecomConfig, plain: string, claim: ReplayClaim }> {
 	const cfg = readWecomConfig();
 	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 claim = await guardReplay(query("timestamp"), query("nonce"), runtimeReplayGate());
 	try {
-		return { cfg, plain: unwrapWecomMessage(encrypted, cfg.encodingAesKey, cfg.suiteId) };
+		// 信封的 ToUserName 就是这条报文的身份：套件事件里是 suiteid，应用数据回调里是 corpid，
+		// 与 receiveid 必然一致（两者在同一份密文/明文里，签名已经覆盖）。
+		return { cfg, plain: unwrapAccepting(encrypted, cfg, [cfg.suiteId, field(envelope, "ToUserName")]), claim };
 	}
 	catch (e) {
-		// 解密失败只透出「失败」：错钥/错套件/被篡改三者不可区分，也不该让外部据此判断哪一环配错
-		log.warn("wecom callback decrypt failed", "reason", (e as Error).message);
+		// 解不开的这一条不能占住 nonce：企微重推是它唯一的恢复路径，占住就把重推挡成 400
+		await claim.release();
+		// 解密失败只对外透出「失败」：错钥/错套件/被篡改三者不可区分，也不该让外部据此判断哪一环配错
+		noteDecryptFailure(e, envelope, cfg);
 		throw badRequest("回调消息解密失败");
 	}
 }
 
+/** 放回一次 nonce 占用；放回失败只告警——它不该盖住真正的失败原因 */
+async function releaseClaim(claim: ReplayClaim | undefined): Promise<void> {
+	if (!claim)
+		return;
+	try {
+		await claim.release();
+	}
+	catch (e) {
+		log.warn("wecom replay nonce release failed", "reason", (e as Error).message);
+	}
+}
+
 const login = {
 	// 企微内打开（UA 含 wxwork）→ oauth2 静默授权；普通浏览器 → qrConnect 扫码。
 	// corp 必填（D10：企业代码 = corp_id，服务商后台可生成带码的专属登录链接）。
 	async get() {
 		try {
 			const cfg = readWecomConfig();
+			const deps = runtimeStoreDeps(cfg);
+
 			const corp = query("corp");
 			const agent = query("agent");
-			if (!corp)
-				throw badRequest("缺少企业代码（corp）：请使用企业管理员收到的登录链接，或在登录页填写企业代码");
 
-			// 企业代码解析是**未登录可调的枚举面**（§5.3）：复用登录节流，维度 (IP, 企业代码)
 			const ip = await clientIp();
-			await guardLoginThrottle(ip, corp);
-
-			const deps = runtimeStoreDeps(cfg);
-			const profile = await findProfile(corp, agent || null, deps).catch(async (e: Error & { status?: number }) => {
-				// 只有「企业代码无效/多应用未指定」计失败；配置类错误（缺 vars）不该污染节流计数
-				if (e.status === 400)
-					await noteLoginFailed(ip, corp);
-				throw e;
-			});
+			// 企业代码解析是**未登录可调的枚举面**（§5.3）：复用登录节流，维度 (IP, 企业代码）。
+			// corp 缺省时（代开发模板常只服务一家企业）自动从已安装档案解析，省去手动填企业代码，
+			// 也让「应用主页」可直接填 https://<域名>/login（无需 ${corpid} 占位符，企微后台会因非法 URL 字符拒收）。
+			let profile: { corpId: string; agentId: string; env: string };
+			if (corp) {
+				await guardLoginThrottle(ip, corp);
+				profile = await findProfile(corp, agent || null, deps).catch(async (e: Error & { status?: number }) => {
+					// 只有「企业代码无效/多应用未指定」计失败；配置类错误（缺 vars）不该污染节流计数
+					if (e.status === 400)
+						await noteLoginFailed(ip, corp);
+					throw e;
+				});
+			} else {
+				profile = await resolveWecomProfile(agent || null);
+				await guardLoginThrottle(ip, profile.corpId);
+			}
 
 			const state = crypto.randomHex(16);
 			await putLoginState(state, { corpId: profile.corpId, agentId: profile.agentId, env: profile.env }, runtimeCache());
@@ -135,12 +217,13 @@ const callback = {
 				throw badRequest("登录状态缺失：请从企业微信重新进入");
 
 			const deps = runtimeStoreDeps(cfg);
-			const pending = await takeLoginState(state, runtimeCache());
+			const cache = runtimeCache();
+			const pending = await takeLoginState(state, cache);
 			const profile = await findProfile(pending.corpId, pending.agentId, deps);
 			// 顺序刚性：先绑租户再碰 users（JIT 建号是租户表写入，守卫 deny 下缺上下文即拒）
 			ensureTenant(tenantOfCorp(profile.corpId));
 
-			const client = createWecomClient({ http: runtimeHttp(), cache: runtimeCache() });
+			const client = createWecomClient({ http: runtimeHttp(), cache });
 			const userid = await client.userIdByCode(profile.corpId, profile.agentId, profile.permanentCode, code);
 			// 名字是惰性取的：只有首次建档才多打一次 user/get（老用户零开销），拿不到就用工号兜底
 			const { uid, forbidden } = await ensureWecomUser(profile.corpId, userid, () =>
@@ -148,6 +231,15 @@ const callback = {
 			if (forbidden)
 				throw Object.assign(new Error("账号已被停用，请联系管理员"), { status: 403 });
 
+			// 轨一：登录自更新（方案 §6.1）。节流 24h、失败不影响登录；但企微侧已离职/禁用的
+			// 账号必须在这里拦下——本站的 is_forbidden 永远以管理员为准，不能被 IdP 反向覆盖。
+			const self = await selfUpdate(
+				{ uid, userid, corpId: profile.corpId, agentId: profile.agentId, permanentCode: profile.permanentCode },
+				{ client, cache, store: deps },
+			);
+			if (self.blocked)
+				throw Object.assign(new Error("账号在企业微信中已被停用或已退出企业，请联系企业管理员"), { status: 403 });
+
 			// 票据而不是 token 进 URL：token 会留在浏览器历史/Referer/反代日志里
 			const ticket = crypto.randomHex(32);
 			const tenant = tenantOfCorp(profile.corpId);
@@ -198,8 +290,9 @@ const event = {
 	// 不需要 suite_id——因此「配齐四项正确即可响应验证」，**不必等代开发模版创建、拿到 suite_id 之后**。
 	// 这正是打破鸡生蛋死锁（plan §18）的落点：先有可验证的回调，才能创建模版、拿到 suite 凭据。
 	//
-	// suite_id 在「模版创建成功」后才下发；URL 验证可能发生在拿到 suite_id 之前（创建表单内联校验），
-	// 此时 receiveid 无从比对 → 走 tolerant（签名已是最外层鉴权闸门，receiveid 仅为防御性兜底）。
+	// suite_id 在「模版创建成功」后才下发；URL 验证可能发生在拿到 suite_id 之前（创建表单内联校验）。
+	// 加上「应用回调 URL 验证时 receiveid 是 corpid」这一层，GET 根本无从挑一个值来比 → 一律 tolerant，
+	// 见下面 try 里的说明（签名是唯一闸门，本端点不落状态）。
 	async get() {
 		try {
 			const cfg = readCallbackConfig();
@@ -207,14 +300,20 @@ const event = {
 			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 claim = await guardReplay(query("timestamp"), query("nonce"), runtimeReplayGate());
 			const suiteId = (vars.get("wecom_suite_id") ?? "").trim();
 			try {
-				plainText(unwrapWecomMessage(encrypted, cfg.encodingAesKey, suiteId, !suiteId));
+				// receiveid 一律不比对：GET 只有 echostr、没有报文信封，无从知道该比哪一个——
+				// 「模板/指令回调 URL」验证时 receiveid 是 suiteid，「应用回调 URL」验证时是 corpid。
+				// 放宽是安全的：签名已过（token 只有本部署与企微知道），回包只是把解出的 echostr 原样返回，
+				// 不写任何状态；真正的 receiveid 比对在 POST 那条路径上（见 unwrapAccepting）。
+				plainText(unwrapWecomMessage(encrypted, cfg.encodingAesKey, suiteId, true));
 			}
 			catch (e) {
+				// 验证没通过就放回 nonce：企微后台点「保存」会连着验几次，占住会把后几次都挡成 400
+				await claim.release();
 				// 解密失败只透出「失败」：错钥/未下发套件/被篡改三者不可区分，也不该让外部据此判断哪一环配错
-				log.warn("wecom callback decrypt failed", "reason", (e as Error).message);
+				noteDecryptFailure(e, null, { encodingAesKey: cfg.encodingAesKey, suiteId });
 				throw badRequest("回调消息解密失败");
 			}
 		}
@@ -223,20 +322,41 @@ const event = {
 		}
 	},
 
-	// 指令回调：验签 → 解密 → 分发（suite_ticket / create_auth / change_auth / cancel_auth /
-	// reset_permanent_code）。回 `success` 才算收下，否则企微 5 秒后重推三次。
+	// 回调（指令 + 应用数据）：验签 → 解密 → 分发（suite_ticket / create_auth / change_auth /
+	// cancel_auth / reset_permanent_code）。回 `success` 才算收下，否则企微 5 秒后重推三次。
+	//
+	// 包体形态按官方文档是 XML（见 payload.ts 的开头），但归一化那一层两种都认，
+	// 所以本函数只认字段名，不认格式。
 	async post() {
+		let claim: ReplayClaim | undefined;
 		try {
-			const xml = typeof http.body === "string" ? http.body : "";
-			const encrypted = xmlField(xml, "Encrypt");
+			const envelope = callbackFields(http.body);
+			const encrypted = field(envelope, "Encrypt");
 			if (!encrypted)
-				throw badRequest("回调报文缺少 Encrypt");
-			const { cfg, plain } = await decryptVerified(encrypted);
+				throw badRequest("回调报文缺少 Encrypt（不是企微回调，或中间件改写了请求体）");
+			const verified = await decryptVerified(encrypted, envelope);
+			claim = verified.claim;
+
 			const client = createWecomClient({ http: runtimeHttp(), cache: runtimeCache() });
-			await handleSuiteEvent(plain, { cfg, client, store: runtimeStoreDeps(cfg) });
+			await handleSuiteEvent(verified.plain, { cfg: verified.cfg, client, store: runtimeStoreDeps(verified.cfg) });
+			// 处理成功即标记 nonce 已落库：企微重推时命中即幂等回 success，解开「首推偏慢被企微判超时、
+			// 重推又被重放守卫挡 400」的死局——管理员端不再卡在「应用安装失败」。
+			await markApplied(query("nonce"), runtimeReplayGate()).catch(() => {});
 			plainText("success");
 		}
 		catch (e) {
+			// 重推且首推已成功落库：幂等回 success，管理员端不再卡在「应用安装失败」。
+			if (e instanceof ReplayAlreadyApplied) {
+				plainText("success");
+				return;
+			}
+			// 处理失败必须放回 nonce：企微只在「拿不到 success」时重推，而那正是需要重推的时刻；
+			// 占住不放，重推会被自己的重放守卫判成 400，瞬态故障的恢复路径当场断掉。
+			await releaseClaim(claim);
+			// 企微侧只会显示「应用安装失败，联系服务商」，原因一概不透露——这里是唯一能查到
+			// 「哪一环拒了这条事件」的地方（缺这一行，这场失败在运维视角是零信息）。
+			const err = e as Error & { status?: number };
+			log.error("wecom event failed", "status", err.status ?? 500, "reason", err.message);
 			// 失败必须让企微看到非 success：它重推三次，正好覆盖「suite_ticket 未到/上游抖」这类瞬态
 			failWith(e);
 		}