@oj-module/cli 0.2.46 → 0.2.48

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

@@ -0,0 +1,263 @@
+import type { WecomClient, WecomDept } from "./client";
+import type { MemberDetail } from "./login";
+import type { CallbackFields } from "./payload";
+import type { WecomStoreDeps } from "./store";
+// 轨三：通讯录变更事件增量（`change_contact`）。
+//
+// 定位是**加速器，不是权威**（方案 §6.3）：权威永远是全量同步。事件只负责「管理员刚改完，
+// 页面上马上能看见」，所以这里的纪律与全量同步正好相反——
+//   · 任何失败都**不抛**（`handleContactChange` 全包在 try/catch 里），照旧回 success。
+//     企微拿不到 success 会重推三次，而重推补不回一次已经判死的失败，只会让企业管理员
+//     在后台看到「应用安装失败」；真正的兜底是下一轮全量同步。
+//   · 只记 `ChangeType` / 企业 ID / 失败原因，**不记姓名与工号**（明文里有）。
+//
+// 两种报文形态都认（归一化在 payload.ts）：
+//   · 应用侧数据回调（90970）：`ToUserName`(=corpid) / `FromUserName=sys` / `MsgType=event` /
+//     `Event=change_contact` / `ChangeType` / `UserID` / `Name` / `Department` / `MainDepartment` /
+//     `IsLeaderInDept` / `Position`；
+//   · 代开发指令回调（91134）：`SuiteId` / `AuthCorpId` / `InfoType=change_contact` /
+//     `ChangeType` / `UserID`（或部门 `Id`）。它**只给 id**，姓名与归属得回源 `user/get` /
+//     `department/get` 拿——这就是「事件里为什么还要出一次网」的全部原因。
+//
+// 写库一律复用轨一同一套函数（login.ts::applyMemberDetail）：三套写库逻辑必然长歪。
+import { markDeleted, upsertDepartment } from "#/_platform/_shared/service/domain/org";
+import { upsertSourceUser } from "#/_platform/_shared/service/domain/users";
+import { applyMemberDetail, externalUsername } from "./login";
+import { field, requireField } from "./payload";
+import { ensureTenant, findCorpAuth, tenantOfCorp } from "./store";
+
+/** 归属权标识（D13）：与 sync.ts 的 ORIGIN 同值，事件与同步必须写同一批行 */
+const ORIGIN = "wecom";
+
+export interface ContactEventDeps {
+	client: WecomClient
+	store: WecomStoreDeps
+}
+
+/** 一条事件的执行上下文：企业已授权 → 应用 与 永久码（= 企业应用 secret） */
+interface CorpCtx {
+	corpId: string
+	agentId: string
+	secret: string
+	now: () => number
+	client: WecomClient
+}
+
+/**
+ * 事件入口：**永不抛出**，返回值只用于日志（`handleSuiteEvent` 原样回给调用方记一行）。
+ *
+ * 企业身份两处取：应用侧数据回调放在 `ToUserName`（corpid），代开发指令回调放在 `AuthCorpId`。
+ * 两者都空时无从判断租户，直接记一笔放弃——猜一个默认企业比不处理更危险。
+ */
+export async function handleContactChange(fields: CallbackFields, deps: ContactEventDeps): Promise<string> {
+	const changeType = field(fields, "ChangeType");
+	const corpId = field(fields, "AuthCorpId") || field(fields, "ToUserName");
+	if (!changeType) {
+		log.info("wecom change_contact skipped", "reason", "报文里没有 ChangeType");
+		return "change_contact";
+	}
+	try {
+		const handled = await applyChange(changeType, corpId, fields, deps);
+		if (handled)
+			log.info("wecom change_contact applied", "changeType", changeType, "corpId", corpId);
+		else
+			log.info("wecom change_contact not consumed", "changeType", changeType, "corpId", corpId);
+	}
+	catch (e) {
+		log.warn("wecom change_contact ignored", "changeType", changeType, "corpId", corpId, "reason", (e as Error).message);
+	}
+	return changeType;
+}
+
+/** 返回 true = 本 ChangeType 被消费；false = 不认识（标签变更等），记账即可 */
+async function applyChange(changeType: string, corpId: string, fields: CallbackFields, deps: ContactEventDeps): Promise<boolean> {
+	if (!corpId)
+		throw new Error("报文里没有企业身份（ToUserName / AuthCorpId 皆空）");
+	const auth = await findCorpAuth(corpId, deps.store);
+	if (!auth)
+		throw new Error("该企业未授权本站（wecom_app_profile 无记录）");
+	const ctx: CorpCtx = {
+		corpId: auth.corpId,
+		// 永久码是 (suite, corp) 级的，应用只决定 token 缓存键，任取一个已授权应用即可
+		agentId: auth.agentIds[0] ?? "",
+		secret: auth.permanentCode,
+		now: deps.store.now,
+		client: deps.client,
+	};
+	// 顺序刚性：先绑租户再碰 users / sys_department / sys_dept_member——
+	// 本端点匿名（企微带不了 X-TENANT-ID），`sql_guard: deny` 下没有租户上下文的写会被直接拒。
+	ensureTenant(tenantOfCorp(auth.corpId));
+
+	switch (changeType) {
+		case "create_user":
+		case "update_user":
+			await applyUserEvent(fields, ctx);
+			return true;
+		case "delete_user":
+			await removeUserEvent(fields);
+			return true;
+		case "create_party":
+		case "update_party":
+			await applyDeptEvent(fields, ctx);
+			return true;
+		case "delete_party":
+			// `deleted=1` 的唯一写入口（子部门一并标记，见 org.ts::markDeleted）
+			await markDeleted(ORIGIN, requireField(fields, "Id", "change_contact"), { now: ctx.now });
+			return true;
+		default:
+			return false;
+	}
+}
+
+/**
+ * 成员新增/变更。事件自带姓名与部门，但**不带排序、不带在职状态**，代开发形态甚至只有一个
+ * `UserID`——所以统一回源 `user/get` 拿全量快照；拿不到（无通讯录权限/不在可见范围/上游抖）
+ * 才退回事件自带字段，缺的字段不写（`undefined` 与 `null` 在 applyMemberDetail 里语义不同）。
+ */
+async function applyUserEvent(fields: CallbackFields, ctx: CorpCtx): Promise<void> {
+	const userid = requireField(fields, "UserID", "change_contact");
+	// userid 变更与建档是两件事：先把旧行改名（同一行），再按新号补资料
+	const newUserid = field(fields, "NewUserID");
+	if (newUserid && newUserid !== userid)
+		await renameUser(userid, newUserid);
+	const target = newUserid || userid;
+
+	const detail = await ctx.client.userDetail(ctx.corpId, ctx.agentId, ctx.secret, target);
+	const eventName = field(fields, "Name").trim();
+	const uid = await upsertSourceUser({
+		username: externalUsername(target),
+		displayName: detail?.name?.trim() || eventName || null,
+		source: ORIGIN,
+		corpId: ctx.corpId,
+	});
+	// activated 不置位：建档 ≠ 用过本站（§9.1 的通讯录目录只收登录过的人）
+	await applyMemberDetail({ uid, userid: target }, detail ?? memberFromEvent(fields), { now: ctx.now });
+}
+
+/**
+ * userid 变更 = **同一行的改名**，不是新建（方案 §6.1）：否则旧号残留，而旧号还能登录。
+ *
+ * 新号已有本地行时**不合并**，抛给上层记一笔放弃：两行合并是「谁是真身」的判断题
+ * （角色、历史操作、文件归属都在旧行上），交给全量同步与人工，不在回调的 1 秒窗口里赌。
+ */
+async function renameUser(fromUserid: string, toUserid: string): Promise<void> {
+	const rows = await db.table("users").select(["id"]).where({ and: [
+		{ field: "username", op: "eq", value: externalUsername(fromUserid) },
+		{ field: "source", op: "eq", value: ORIGIN },
+	] }).all() as Array<{ id: number }>;
+	if (!rows.length)
+		return; // 旧号没建过档（全量同步还没跑到）：按新号走建档即可
+	const taken = await db.table("users").select(["id"]).where({ field: "username", op: "eq", value: externalUsername(toUserid) }).all();
+	if (taken.length)
+		throw new Error("新 userid 已有本地账号，跳过改名（交给全量同步/人工处理）");
+	const uid = Number(rows[0]!.id);
+	await db.table("users").update({ username: externalUsername(toUserid) }).where({ field: "id", op: "eq", value: uid }).run();
+	await revokeSessions(uid);
+}
+
+/**
+ * 退出企业：**不删账号**（审计、角色、历史引用都挂在 `users.id` 上），只把外部状态置 5 并摘掉
+ * 部门关联；`is_forbidden` 一律不动（那是本站管理员的手动启停，不能被 IdP 覆盖）。
+ *
+ * 保留期结束后的匿名化要靠定时清扫（方案 §9.3，D 阶段才有调度器）：现在写一个「删除」只会
+ * 得到一行立即过期的数据，所以这里刻意不做。
+ */
+async function removeUserEvent(fields: CallbackFields): Promise<void> {
+	const userid = requireField(fields, "UserID", "change_contact");
+	const rows = await db.table("users").select(["id"]).where({ and: [
+		{ field: "username", op: "eq", value: externalUsername(userid) },
+		{ field: "source", op: "eq", value: ORIGIN },
+	] }).all() as Array<{ id: number }>;
+	if (!rows.length)
+		return; // 没建过档就没什么可摘，等下一轮全量
+	const uid = Number(rows[0]!.id);
+	await db.tx(async (t) => {
+		await t.table("sys_dept_member").where({ field: "user_id", op: "eq", value: uid }).delete().run();
+		await t.table("users").update({ external_status: 5 }).where({ field: "id", op: "eq", value: uid }).run();
+	});
+	await revokeSessions(uid);
+}
+
+/**
+ * 部门新增/变更。
+ *
+ * 父级有**三态**，判断顺序不能换：上游详情 > 事件自带 `ParentId` > 保持本地现值。
+ * 最关键的是第三态——事件与上游都没给父级时**绝不能写成 null**，那会把整棵子树拍平到根，
+ * 而企微的 `ParentId` 为空串时既可能表示「根部门」也可能表示「这条报文没带」，光看值分不出来，
+ * 所以只在确认上游详情拿到时才敢按空处理（详情里的空就是根）。
+ */
+async function applyDeptEvent(fields: CallbackFields, ctx: CorpCtx): Promise<void> {
+	const originId = requireField(fields, "Id", "change_contact");
+	let detail: WecomDept | null = null;
+	try {
+		detail = await ctx.client.departmentDetail(ctx.corpId, ctx.agentId, ctx.secret, originId);
+	}
+	catch (e) {
+		// 无权限/不在可见范围是常态：退回事件自带字段，再不行就只改名字
+		log.warn("wecom dept detail skipped", "originId", originId, "reason", (e as Error).message);
+	}
+
+	const local = await localDept(originId);
+	let name: string | null = detail?.name ?? null;
+	if (!name)
+		name = field(fields, "Name").trim() || local?.name || null;
+	if (!name)
+		throw new Error("部门事件既没有名字、本地也没有这一行：不建无名部门");
+
+	let parentLocal: number | null = local?.parentId ?? null;
+	if (detail)
+		parentLocal = detail.parentId ? await localDeptId(detail.parentId) : null;
+	else if (fields.values.has("parentid"))
+		parentLocal = field(fields, "ParentId") ? await localDeptId(field(fields, "ParentId")) : null;
+
+	await upsertDepartment({
+		origin: ORIGIN,
+		originId,
+		parentId: parentLocal,
+		name,
+		orderNo: detail?.order ?? Number(field(fields, "Order") || 0),
+	}, { now: ctx.now });
+}
+
+/**
+ * 事件自带的成员字段。代开发形态只有 UserID，这里会退化成「只建档、不写组织关系」——
+ * 那没关系：下一次全量同步会把该有的都补上，而事件本来只是加速器。
+ */
+function memberFromEvent(fields: CallbackFields): MemberDetail {
+	const main = Number(field(fields, "MainDepartment"));
+	const position = field(fields, "Position").trim();
+	return {
+		name: field(fields, "Name").trim() || null,
+		// 空串 = 这条报文没给：不写（否则会把已知职务清成 null）
+		position: position || undefined,
+		status: undefined,
+		departments: splitIds(field(fields, "Department")),
+		orders: [],
+		leaderInDept: splitIds(field(fields, "IsLeaderInDept")).map(v => Number(v)),
+		mainDepartment: Number.isFinite(main) && main > 0 ? main : null,
+	};
+}
+
+/** 多值字段分隔符：企微用 `|`；逗号一并认，免得哪天换格式时静默只取到第一个 */
+function splitIds(raw: string): string[] {
+	return raw.split(/[|,]/).map(s => s.trim()).filter(Boolean);
+}
+
+async function localDept(originId: string): Promise<{ id: number, parentId: number | null, name: string | null } | null> {
+	const rows = await db.table("sys_department").select(["id", "parent_id", "name"]).where({ and: [
+		{ field: "origin", op: "eq", value: ORIGIN },
+		{ field: "origin_id", op: "eq", value: originId },
+	] }).all() as Array<{ id: number, parent_id: number | null, name: string | null }>;
+	const r = rows[0];
+	return r ? { id: Number(r.id), parentId: r.parent_id == null ? null : Number(r.parent_id), name: r.name } : null;
+}
+
+async function localDeptId(originId: string): Promise<number | null> {
+	const row = await localDept(originId);
+	return row ? row.id : null;
+}
+
+/** 删该用户全部 refresh 记录（与 session.ts::revokeAll 同语义，这里不构造 session 免得带进登录依赖） */
+async function revokeSessions(uid: number): Promise<void> {
+	await db.table("sys_refresh_token").where({ field: "user_id", op: "eq", value: uid }).delete().run();
+}

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

@@ -12,6 +12,8 @@
 // 逆 S 盒由置换求逆（加载期一次性，<5ms）。
 
 const BLOCK = 16;
+/** 企微的 PKCS#7 补位块长（90968：填充至 32 字节的倍数），与 AES 的 16 字节块是两回事 */
+const PAD_BLOCK = 32;
 
 /** GF(2^8) 乘法，域多项式 x^8+x^4+x^3+x+1（0x11B），AES 唯一乘法 */
 function gmul(a: number, b: number): number {
@@ -153,12 +155,18 @@ export function aes256CbcDecrypt(cipher: Uint8Array, key: Uint8Array, iv: Uint8A
 	return out;
 }
 
-/** PKCS#7 去填充（1..16 字节，逐字节校验；非法抛错） */
+/**
+ * PKCS#7 去填充（逐字节校验；非法抛错）。
+ *
+ * 补位长度上限是 **32**，不是 AES 的块长 16：企微（90968「概述」）明确写「数据采用 PKCS#7 填充至
+ * **32 字节**的倍数」，官方各语言 demo 里 block_size 也等于 32。按 16 卡上限会让补位 17~32 的报文
+ * 一律判成 `bad padding`——而那恰好是真实回调里约一半的情况（补位值由报文长度决定）。
+ */
 export function pkcs7Unpad(data: Uint8Array): Uint8Array {
 	if (data.length === 0 || data.length % BLOCK !== 0)
 		throw new Error("pkcs7: bad length");
 	const pad = data[data.length - 1]!;
-	if (pad < 1 || pad > BLOCK || pad > data.length)
+	if (pad < 1 || pad > PAD_BLOCK || pad > data.length)
 		throw new Error("pkcs7: bad padding");
 	for (let i = data.length - pad; i < data.length; i++) {
 		if (data[i] !== pad)
@@ -291,12 +299,14 @@ export function wecomSignature(...parts: string[]): string {
  * 解出企微消息明文（`<xml>…</xml>` 或裸 `echostr`）。
  *
  * 明文结构（企微 §消息加解密）：`random(16B) | msg_len(4B, big-endian) | msg | receiveid`。
- * `receiveid` 对第三方平台/代开发模版是 **suite_id**；不一致即拒（错钥/错套件混用必须 fail-closed，
- * 否则不同套件的回调会互相污染）。43 字符 EncodingAESKey 末尾补 "=" 才是 44 字符 base64（32 字节）。
+ * `receiveid` 的含义**随场景变**（90968 附注）：第三方事件的回调是 **suite_id**（suite_ticket /
+ * create_auth），企业应用的回调（含代开发应用的数据回调，通讯录变更就走这条）是 **corpid**。
+ * 不一致即拒（错钥/错套件混用必须 fail-closed）——但调用方得按场景给出候选值，
+ * 见 `wecom/api.ts::unwrapAccepting`。43 字符 EncodingAESKey 末尾补 "=" 才是 44 字符 base64（32 字节）。
  *
- * `tolerant`（默认 false）：引导期 `suite_id` 尚未下发时，receiveid 无从比对——
- * 此时放宽该检查。放宽是安全的：最外层签名（基于开发者持有的 `token`）已鉴权，
- * receiveid 只是防御性兜底（防错配 aeskey）。`suite_id` 配齐后调用方应传 `false` 恢复严格。
+ * `tolerant`（默认 false）：拿不到可比对的 receiveid 时放宽（引导期没有 suite_id、或 GET 只有
+ * echostr 没有报文信封）。放宽是安全的：最外层签名（基于开发者持有的 `token`）已鉴权，
+ * receiveid 只是防御性兜底（防错配 aeskey）。
  */
 export function unwrapWecomMessage(encryptedB64: string, encodingAesKey: string, expectedReceiver: string, tolerant = false): string {
 	const key = b64ToBytes(`${encodingAesKey}=`);

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

@@ -2,7 +2,7 @@ import type { WecomClient } from "./client";
 import type { WecomConfig } from "./config";
 import type { WecomStoreDeps } from "./store";
 // 企微「指令回调」事件处理：suite_ticket / create_auth / change_auth / cancel_auth /
-// reset_permanent_code（代开发重置 secret 走后者）。
+// reset_permanent_code（代开发重置 secret 走后者），以及轨三的通讯录变更（contacts.ts）。
 //
 // 为什么这几件事必须由回调驱动（而不是管理端手工录）：
 //   · suite_ticket 每 10 分钟推一次、30 分钟过期，拿不到就换不出 suite_access_token，
@@ -12,13 +12,16 @@ import type { WecomStoreDeps } from "./store";
 //   · 企业解绑/取消授权只在 cancel_auth 出现。
 // 因此这里不是「可选的后台功能」，是代开发模式的下限能力。
 //
-// 响应纪律：处理完返回（路由回纯文本 success）。企微 5 秒内拿不到 success 会重推三次；
-// 重推对我们是幂等的（profile upsert / ticket 覆盖），但 AuthCode 一次有效，重推时已换取过 → 502，
+// 响应纪律：处理完返回（路由回纯文本 success）。企微对 `create_auth` 的窗口是 **约 1 秒**
+// （官方文档写 5 秒，实际按 1 秒卡；超时/非 success 一律在企业管理员浏览器上显示
+// 「应用安装失败，联系服务商」）。拿不到 success 会重推三次；重推对我们是幂等的
+// （profile upsert / ticket 覆盖），但 AuthCode 一次有效，重推时已换取过 → 502，
 // 属预期（日志留痕即可，不影响已落库的 profile）。
 import { invalidateAllUsers } from "#/_platform/_shared/service/infra/access";
 import { recordOp } from "#/_platform/_shared/service/infra/audit";
-import { corpScope, getSuiteTicket, putSuiteTicket, revokeTenantSessions, saveProfile, setProfileStatus, tenantOfCorp } from "./store";
-import { xmlField } from "./xml";
+import { handleContactChange } from "./contacts";
+import { callbackFields, field, requireField } from "./payload";
+import { corpScope, ensureTenant, findCorpAuth, getSuiteTicket, putSuiteTicket, revokeTenantSessions, saveProfile, setAuthMode, setProfileStatus, tenantOfCorp } from "./store";
 
 /** suite_ticket 官方有效期 30 分钟（10 分钟推一次）；本地按 30 分钟作废，宁可拒一次也不拿过期票打企微 */
 const SUITE_TICKET_TTL_SECS = 30 * 60;
@@ -40,15 +43,27 @@ export function envOfState(state: string | null): string {
 	return /^(?:prod|test|staging|dev)$/i.test(trimmed) ? trimmed.toLowerCase() : "prod";
 }
 
-function requireField(xml: string, name: string, infoType: string): string {
-	const value = xmlField(xml, name);
-	if (!value)
-		throw Object.assign(new Error(`企微事件 ${infoType} 缺少 ${name}`), { status: 400 });
-	return value;
+/**
+ * 事件路径的审计。两处纪律：
+ *   1. 调用前必须先 `ensureTenant(corp)`——`sys_oplog` 是租户表，本端点又是匿名路径（企微带不了
+ *      `X-TENANT-ID`），`sql_guard: deny` 下不带租户上下文的 insert 会被守卫直接拒；
+ *   2. 审计失败**只告警**：它发生在 profile 已落库之后，一次成功的授权不能因为写日志失败
+ *      变成企业管理员看到的「应用安装失败」。
+ */
+async function auditAuth(action: string, corpId: string, detail?: unknown, level?: number): Promise<void> {
+	try {
+		await recordOp({ action, module: "auth", target: corpId, detail, level });
+	}
+	catch (e) {
+		log.warn("wecom auth audit skipped", "action", action, "corpId", corpId, "reason", (e as Error).message);
+	}
 }
 
 /** 该 corp 的所有应用都标记为停用，并吊销其租户下的全部会话 */
 async function disableCorp(corpId: string, deps: SuiteEventDeps): Promise<void> {
+	// 取消授权同样是匿名回调：会话清理走裸 SQL，`sql_guard: deny` 下没有租户上下文会被拒——
+	// 而这里拒掉的后果是「旧 refresh 串仍能续命」，属安全红线，故必须绑成功再往下走。
+	ensureTenant(tenantOfCorp(corpId));
 	const rows = await db.table("wecom_app_profile").select(["agent_id"]).where(corpScope(corpId)).all() as Array<{ agent_id: string }>;
 	for (const r of rows)
 		await deps.client.invalidateCorpToken(corpId, String(r.agent_id));
@@ -67,6 +82,9 @@ async function applyAuthCode(authCode: string, state: string | null, deps: Suite
 	const suiteToken = await client.suiteAccessToken(cfg.suiteId, cfg.suiteSecret, suiteTicket.ticket);
 	const granted = await client.permanentCodeByAuthCode(suiteToken, authCode);
 	const env = envOfState(state ?? granted.state);
+	// 拿到企业身份就绑租户：profile 表虽共享，但其后的审计与后续写库都在这个租户下。
+	// 顺序不能挪到审计里——那样 saveProfile 之后才发现守卫拒，profile 已落库却回失败。
+	ensureTenant(tenantOfCorp(granted.corpId));
 	for (const agentId of granted.agentIds) {
 		await saveProfile({
 			suiteId: cfg.suiteId,
@@ -76,52 +94,119 @@ async function applyAuthCode(authCode: string, state: string | null, deps: Suite
 			env,
 			corpName: granted.corpName,
 			permanentCode: granted.permanentCode,
+			authMode: granted.authModes[agentId] ?? 0,
 		}, store);
 		// secret 可能已轮换：旧 token 必须立刻作废，否则下一个登录会带着失效 token 打 userinfo
 		await client.invalidateCorpToken(granted.corpId, agentId);
 	}
-	await recordOp({ action: "wecom.auth.apply", module: "auth", target: granted.corpId, detail: { agentIds: granted.agentIds, env } });
+	await auditAuth("wecom.auth.apply", granted.corpId, { agentIds: granted.agentIds, env });
 	return { corpId: granted.corpId, agentIds: granted.agentIds };
 }
 
+/**
+ * `change_auth` 后复核授权模式并落库。
+ *
+ * 失败**只告警**：回调窗口 1 秒，一次上游抖动不该把通知打成失败（重推也补不回被误判的
+ * 授权模式，反而让企业管理员看到「配置失败」）。代价是 auth_mode 短期仍是旧值，
+ * 同步闸门那侧还有 60011 兜底（见 sync 的 permission 分支）。
+ */
+async function refreshAuthModes(corpId: string, deps: SuiteEventDeps): Promise<void> {
+	try {
+		const auth = await findCorpAuth(corpId, deps.store);
+		if (!auth)
+			return;
+		const ticket = await getSuiteTicket(deps.cfg.suiteId, deps.store);
+		const suiteToken = await deps.client.suiteAccessToken(deps.cfg.suiteId, deps.cfg.suiteSecret, ticket.ticket);
+		const modes = await deps.client.authModesByPermanentCode(suiteToken, corpId, auth.permanentCode);
+		for (const agentId of auth.agentIds) {
+			const mode = modes[agentId];
+			if (mode == null)
+				continue;
+			await setAuthMode(corpId, agentId, mode, deps.store);
+			log.info("wecom auth_mode refreshed", "corpId", corpId, "agentId", agentId, "authMode", mode);
+		}
+	}
+	catch (e) {
+		log.warn("wecom auth_mode refresh skipped", "corpId", corpId, "reason", (e as Error).message);
+	}
+}
+
 /** 处理一条已验签并解密的回调明文；返回值仅用于日志（未知 InfoType 也回 success，不触发重推） */
-export async function handleSuiteEvent(plaintext: string, deps: SuiteEventDeps): Promise<string> {
-	const infoType = xmlField(plaintext, "InfoType") ?? "";
-	const suiteId = xmlField(plaintext, "SuiteId") ?? "";
+export async function handleSuiteEvent(payload: unknown, deps: SuiteEventDeps): Promise<string> {
+	// 入参是「原始报文」（对象 / JSON 串 / XML 串都行，见 payload.ts）；归一化只在这里做一次，
+	// 往下全是字段名，函数体里再也看不到格式。
+	const fields = callbackFields(payload);
+	const infoType = field(fields, "InfoType");
+	const suiteId = field(fields, "SuiteId");
 	if (suiteId && suiteId !== deps.cfg.suiteId)
 		throw Object.assign(new Error("企微事件 SuiteId 与本部署配置不一致"), { status: 400 });
 
+	// 通讯录变更（轨三）：**必须在 switch 之前分流**。两种形态都认——
+	// 应用侧数据回调是 `MsgType=event` + `Event=change_contact`（InfoType 为空），
+	// 代开发指令回调是 `InfoType=change_contact`；后者与 suite_ticket 同用 InfoType 这一列，
+	// 落进 default 只会被记成「不消费的事件」。
+	// 与下面几个分支的不同：通讯录事件失败**不抛**（事件是加速器，重推补不回来，见 contacts.ts）。
+	if (field(fields, "Event") === "change_contact" || infoType === "change_contact")
+		return await handleContactChange(fields, deps);
+
 	switch (infoType) {
 		case "suite_ticket": {
-			const ticket = requireField(plaintext, "SuiteTicket", infoType);
+			const ticket = requireField(fields, "SuiteTicket", infoType);
 			await putSuiteTicket(deps.cfg.suiteId, ticket, deps.store.now() + SUITE_TICKET_TTL_SECS, deps.store);
 			log.info("wecom suite_ticket updated", "suiteId", deps.cfg.suiteId);
+			// 顺势换一次 suite_access_token（命中缓存则 0 次往返）：create_auth 只有约 1 秒窗口，
+			// 这里先换掉，企业管理员扫码那条路径就只剩 get_permanent_code 一次出网。
+			// 副产品：suite_secret 配错会在票据推送时就进日志，而不是等某家企业扫码失败。
+			await deps.client.suiteAccessToken(deps.cfg.suiteId, deps.cfg.suiteSecret, ticket)
+				.catch((e: Error) => log.warn("wecom suite token warmup failed", "reason", e.message));
 			return infoType;
 		}
 		case "create_auth":
 		case "reset_permanent_code": {
-			const authCode = requireField(plaintext, "AuthCode", infoType);
-			const applied = await applyAuthCode(authCode, xmlField(plaintext, "State"), deps);
+			const authCode = requireField(fields, "AuthCode", infoType);
+			const applied = await applyAuthCode(authCode, field(fields, "State") || null, deps);
 			log.info("wecom auth applied", "event", infoType, "corpId", applied.corpId, "agents", applied.agentIds.join(","));
 			return infoType;
 		}
 		case "change_auth": {
-			// 可见范围/权限/启停变化：MVP 只做「数据可见性不加码」——不改状态、不动 secret，
-			// 靠下次登录重新走 userinfo（企微会拒掉已移出可见范围的成员）。停用/解绑走 cancel_auth。
-			const authCorpId = requireField(plaintext, "AuthCorpId", infoType);
+			// 可见范围/权限/启停变化。其中**「管理员授权 ⇄ 成员授权」切换**必须跟：切到成员授权后
+			// 部门接口一律 60011，同步闸门还按旧值放行就会一直 502。官方要求服务商自行调
+			// `get_auth_info` 复核——通知本身只带 AuthCorpId（没有 AuthCode），只能拿已存永久码反查。
+			// 其余变化（可见范围收窄等）仍是「下次登录重新走 userinfo」，不在回调里处理。
+			const authCorpId = requireField(fields, "AuthCorpId", infoType);
+			ensureTenant(tenantOfCorp(authCorpId));
+			await refreshAuthModes(authCorpId, deps);
 			log.info("wecom auth changed", "corpId", authCorpId);
 			return infoType;
 		}
 		case "cancel_auth": {
-			const authCorpId = requireField(plaintext, "AuthCorpId", infoType);
+			const authCorpId = requireField(fields, "AuthCorpId", infoType);
 			await disableCorp(authCorpId, deps);
-			await recordOp({ action: "wecom.auth.cancel", module: "auth", target: authCorpId, level: 4 });
+			await auditAuth("wecom.auth.cancel", authCorpId, undefined, 4);
 			log.warn("wecom auth cancelled", "corpId", authCorpId);
 			return infoType;
 		}
-		default:
-			// 通讯录变更等事件本模块不消费：记账即可，回 success 让企微别再推
-			log.info("wecom event ignored", "infoType", infoType);
-			return infoType;
+		default: {
+			// 余下的事件（标签变更、外部联系人等）本模块不消费：记账即可，回 success 让企微别再推。
+			//
+			// 记账要记够「这条报文能不能用」的量：指令回调（有 InfoType）与数据回调
+			// （`MsgType=event` + `Event=xxx`，没有 InfoType）走的是同一个 `/event`，
+			// 而两者的 Token/AESKey 未必是同一套。真机验形态时只凭 InfoType 为空无法区分
+			// 「收到了一条事件」与「收到了一条别的消息」，所以把 Event 与字段清单一起记下。
+			// **只记字段名不记值**：明文里有姓名与工号。
+			const eventName = field(fields, "Event");
+			log.info(
+				"wecom event ignored",
+				"infoType",
+				infoType,
+				"msgType",
+				field(fields, "MsgType"),
+				"event",
+				eventName,
+				"fields",
+				fields.names.join(","),
+			);
+			return eventName || infoType;
+		}
 	}
 }