@oj-module/cli 0.2.47 → 0.2.49

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

@@ -118,6 +118,96 @@ function assertOk(res: Record<string, unknown>, what: string): void {
 
 const TOKEN_EXPIRED = new Set([40001, 40014, 42001]);
 
+/**
+ * 错码三分类（方案 §5.1）。同步器按 kind 决定处置，**不再一律当 502**：
+ *   · permission：该部门不在应用权限/可见范围内 → 跳过并计数，本轮不判失败（否则一个部门无权限就整轮 failed）；
+ *   · ratelimit：指数退避重试（企微每企业 ≤1 万次/分、15 万次/小时，正常量级撞不到，撞到就是并发高了）；
+ *   · fatal：60020（出口 IP 未白名单）/ 46004（成员已删）/ 网络等——重试无用，计入熔断。
+ */
+export type WecomErrorKind = "permission" | "ratelimit" | "fatal";
+
+const PERMISSION_CODES = new Set([48002, 60011]);
+const RATELIMIT_CODES = new Set([45009, 45033]);
+
+export class WecomApiError extends Error {
+	readonly kind: WecomErrorKind;
+	readonly errcode: number;
+	constructor(what: string, errcode: number, errmsg: string) {
+		super(`企微 ${what} 失败：errcode=${errcode} ${errmsg}`.trimEnd());
+		this.name = "WecomApiError";
+		this.errcode = errcode;
+		this.kind = PERMISSION_CODES.has(errcode) ? "permission" : RATELIMIT_CODES.has(errcode) ? "ratelimit" : "fatal";
+		// 502：对上层仍是「上游出错」，路由信封口径不变；kind 只给同步器分流用
+		Object.assign(this, { status: 502 });
+	}
+}
+
+/** 退避用的软 sleep：isolate 无 timer 全局，拿不到 tasks 就退化成「不等待直接重试」 */
+function softSleep(ms: number): Promise<void> {
+	const g = globalThis as unknown as { tasks?: { sleep?: (ms: number) => Promise<void> } };
+	const sleep = g.tasks?.sleep;
+	if (typeof sleep !== "function")
+		return Promise.resolve();
+	return sleep(ms).catch(() => undefined);
+}
+
+/** 通讯录部门（simplelist/list 的公共形态）：企微部门 id 是数字，这里统一按字符串处理（§4.1 origin_id） */
+export interface WecomDept {
+	id: string
+	parentId: string
+	name: string | null
+	nameEn: string | null
+	order: number
+}
+
+/** 通讯录成员（user/list 的形态）：`department` / `order` / `is_leader_in_dept` 逐位对应 */
+export interface WecomMember {
+	userid: string
+	name: string | null
+	departments: string[]
+	orders: number[]
+	leaderInDept: number[]
+	mainDepartment: number | null
+	position: string | null
+	/** 1=已激活 2=已禁用 4=未激活 5=退出企业（§4.3，只存快照不改 is_forbidden） */
+	status: number | null
+}
+
+/**
+ * 授权信息里的应用列表（`auth_info.agent`）——`get_permanent_code` 与 `get_auth_info` 同形，
+ * 抽出来是为了两处对 auth_mode 的读法永远一致（同步闸门认的就是这个值）。
+ *
+ * **数组与单对象都认**：官方示例是数组，但 2026-11-01 的生产回包在代开发 v2 上给的是空列表
+ * （见 permanentCodeByAuthCode 的回源兜底）。单对象形态认下来没有代价，少一次「明明有应用却
+ * 判成没授权」的误杀。
+ */
+function agentListOf(authInfo: unknown): Array<Record<string, unknown>> {
+	const list = (authInfo as Record<string, unknown> | undefined)?.agent;
+	if (Array.isArray(list))
+		return list.map(a => a as Record<string, unknown>);
+	if (list && typeof list === "object")
+		return [list as Record<string, unknown>];
+	return [];
+}
+
+/**
+ * agent_id → auth_mode。auth_mode 在 agent 项上（每个应用各自一条）；老回包里偶尔只在
+ * auth_info 顶层给，故两级都读，缺省按 0（管理员授权）——成员授权会导致同步 100% 60011，
+ * 不能靠猜成 1。
+ */
+function readAuthModes(authInfo: unknown): Record<string, number> {
+	const top = (authInfo as Record<string, unknown> | undefined)?.auth_mode;
+	const modes: Record<string, number> = {};
+	for (const a of agentListOf(authInfo)) {
+		const agentId = String(a.agentid ?? "");
+		if (!agentId)
+			continue;
+		const mode = Number(a.auth_mode ?? top ?? 0);
+		modes[agentId] = Number.isFinite(mode) ? mode : 0;
+	}
+	return modes;
+}
+
 export function createWecomClient(deps: WecomClientDeps) {
 	const { http, cache } = deps;
 
@@ -156,28 +246,72 @@ export function createWecomClient(deps: WecomClientDeps) {
 		corpId: string
 		corpName: string | null
 		agentIds: string[]
+		/** agent_id → auth_mode（0=管理员授权 / 1=成员授权）；成员授权下应用无任何部门权限（§2.3） */
+		authModes: Record<string, number>
 		state: string | null
 	}> {
 		const res = await http.postJson(`${API_BASE}/cgi-bin/service/v2/get_permanent_code?suite_access_token=${encodeURIComponent(suiteAccessToken)}`, { auth_code: authCode });
 		assertOk(res, "get_permanent_code");
 		const authCorp = (res.auth_corp_info ?? {}) as Record<string, unknown>;
-		const agentList = ((res.auth_info ?? {}) as Record<string, unknown>).agent;
-		const agentIds = Array.isArray(agentList)
-			? agentList.map(a => String((a as Record<string, unknown>).agentid)).filter(Boolean)
-			: [];
 		if (!res.permanent_code || !authCorp.corpid)
 			throw upstream("企微 get_permanent_code 返回缺少 permanent_code / corpid");
+		let authInfo = res.auth_info;
+		let agents = agentListOf(authInfo);
+		if (agents.length === 0) {
+			// 代开发 v2 出现过「永久码拿到了、auth_info.agent 却是空的」（2026-11-01 生产日志）。
+			// 此时别急着判死：永久码已经在手，`get_auth_info` 是同形的复核接口，能补回应用列表。
+			// 只记字段名，不记值——回包里没有任何可公开的东西。
+			log.warn(
+				"wecom agent list missing in get_permanent_code",
+				"keys",
+				Object.keys(res).join(","),
+				"authInfoKeys",
+				authInfo && typeof authInfo === "object" ? Object.keys(authInfo as Record<string, unknown>).join(",") : typeof authInfo,
+			);
+			try {
+				authInfo = await authInfoByPermanentCode(suiteAccessToken, String(authCorp.corpid), String(res.permanent_code));
+				agents = agentListOf(authInfo);
+			}
+			catch (e) {
+				log.warn("wecom get_auth_info fallback failed", "reason", (e as Error).message);
+			}
+		}
+		const agentIds = agents.map(a => String(a.agentid)).filter(Boolean);
+		// 列表有元素却取不到 agentid：字段被改名的信号，记下键名（不记值）省下一次盲猜
+		if (agents.length > 0 && agentIds.length === 0)
+			log.warn("wecom agent item has no agentid", "keys", Object.keys(agents[0]!).join(","));
 		if (agentIds.length === 0)
-			throw upstream("企微 get_permanent_code 未返回授权应用（auth_info.agent 为空）");
+			throw upstream("企微 get_permanent_code 未返回授权应用（auth_info.agent 为空，get_auth_info 复核也没有）");
 		return {
 			permanentCode: String(res.permanent_code),
 			corpId: String(authCorp.corpid),
 			corpName: authCorp.corp_name == null ? null : String(authCorp.corp_name),
 			agentIds,
+			authModes: readAuthModes(authInfo),
 			state: res.state == null ? null : String(res.state),
 		};
 	}
 
+	/**
+	 * 复核授权模式（`get_auth_info`）：`change_auth` 事件只带 AuthCorpId、**不带 AuthCode**，
+	 * 所以刷新 auth_mode 只能拿已存的 permanent_code 反查。企业管理员在后台把「管理员授权」
+	 * 切成「成员授权」（或反向）就靠这条路径同步——切过去以后部门接口一律 60011，
+	 * 不刷新就会一直按「可同步」对待。
+	 */
+	async function authModesByPermanentCode(suiteAccessToken: string, corpId: string, permanentCode: string): Promise<Record<string, number>> {
+		return readAuthModes(await authInfoByPermanentCode(suiteAccessToken, corpId, permanentCode));
+	}
+
+	/** `get_auth_info` 的原始 `auth_info`：授权模式刷新与「永久码回包缺 agent」的回源兜底共用 */
+	async function authInfoByPermanentCode(suiteAccessToken: string, corpId: string, permanentCode: string): Promise<unknown> {
+		const res = await http.postJson(`${API_BASE}/cgi-bin/service/get_auth_info?suite_access_token=${encodeURIComponent(suiteAccessToken)}`, {
+			auth_corpid: corpId,
+			permanent_code: permanentCode,
+		});
+		assertOk(res, "get_auth_info");
+		return res.auth_info;
+	}
+
 	/**
 	 * 服务商级 token（provider_access_token）：代开发「生成授权链接」用，与套件 token 不同源。
 	 * 由服务商 corpid + provider_secret 换得，全部署共享一份（不限 suite）。
@@ -239,6 +373,127 @@ export function createWecomClient(deps: WecomClientDeps) {
 		await cache.del(`wecom:corp_token:${corpId}:${agentId}`);
 	}
 
+	/**
+	 * 通讯录类 GET 的公共通道：token 失效重取 + 三类错码分流。
+	 *
+	 * 重试上限是有意的：token 失效最多换两次（企微侧提前失效是常态），限流退避最多三次
+	 * （500ms/1s/2s），其余错码立即抛——同步器靠 kind 决定「跳过并计数」还是「计入熔断」，
+	 * 所以**必须把 errcode 带出去**，不能像 assertOk 那样拍平成一句中文。
+	 */
+	async function corpGet(
+		corpId: string,
+		agentId: string,
+		secret: string,
+		path: string,
+		params: Record<string, string | number | undefined>,
+		what: string,
+	): Promise<Record<string, unknown>> {
+		const qs = Object.entries(params)
+			.filter(([, v]) => v != null && v !== "")
+			.map(([k, v]) => `${k}=${encodeURIComponent(String(v))}`)
+			.join("&");
+		for (let attempt = 0; ; attempt++) {
+			const token = await corpAccessToken(corpId, agentId, secret);
+			const res = await http.getJson(`${API_BASE}${path}?access_token=${encodeURIComponent(token)}${qs ? `&${qs}` : ""}`);
+			const errcode = Number(res.errcode ?? 0);
+			if (!errcode)
+				return res;
+			if (TOKEN_EXPIRED.has(errcode) && attempt < 2) {
+				await invalidateCorpToken(corpId, agentId);
+				continue;
+			}
+			const err = new WecomApiError(what, errcode, String(res.errmsg ?? ""));
+			if (err.kind === "ratelimit" && attempt < 2) {
+				await softSleep(500 * 2 ** attempt);
+				continue;
+			}
+			throw err;
+		}
+	}
+
+	function toDept(raw: Record<string, unknown>): WecomDept {
+		return {
+			id: String(raw.id ?? ""),
+			parentId: raw.parentid == null ? "" : String(raw.parentid),
+			name: raw.name == null ? null : String(raw.name),
+			nameEn: raw.name_en == null ? null : String(raw.name_en),
+			order: Number(raw.order ?? 0),
+		};
+	}
+
+	/**
+	 * 子部门 id 列表（接口 1）：全量同步的**主路径**——官方 90208 明写 `department/list` 性能低。
+	 * `parentOriginId` 缺省时企微返回「应用可见范围内所有部门」，这既是 BFS 的起点，也是兜底路径。
+	 */
+	async function departmentChildren(corpId: string, agentId: string, secret: string, parentOriginId?: string): Promise<WecomDept[]> {
+		const res = await corpGet(corpId, agentId, secret, "/cgi-bin/department/simplelist", { id: parentOriginId }, "department/simplelist");
+		const list = Array.isArray(res.department_id) ? res.department_id as Array<Record<string, unknown>> : [];
+		return list.filter(d => d && d.id != null).map(toDept);
+	}
+
+	/** 单部门详情（接口 2）：simplelist 不带名字，名字只能从这里取（未授权时 name 为空） */
+	async function departmentDetail(corpId: string, agentId: string, secret: string, originId: string): Promise<WecomDept> {
+		const res = await corpGet(corpId, agentId, secret, "/cgi-bin/department/get", { id: originId }, "department/get");
+		const d = res.department as Record<string, unknown> | undefined;
+		if (!d || d.id == null)
+			throw upstream("企微 department/get 未返回部门详情");
+		return toDept(d);
+	}
+
+	/** 一次拿全量部门（接口 3）：降级兜底，1/2 因权限拿不到时用 */
+	async function departmentList(corpId: string, agentId: string, secret: string, parentOriginId?: string): Promise<WecomDept[]> {
+		const res = await corpGet(corpId, agentId, secret, "/cgi-bin/department/list", { id: parentOriginId }, "department/list");
+		const list = Array.isArray(res.department) ? res.department as Array<Record<string, unknown>> : [];
+		return list.filter(d => d && d.id != null).map(toDept);
+	}
+
+	function toMember(raw: Record<string, unknown>, detail: boolean): WecomMember {
+		const departments = Array.isArray(raw.department) ? raw.department.map(d => String(d)) : [];
+		const orders = detail && Array.isArray(raw.order) ? raw.order.map(o => Number(o)) : [];
+		const leader = detail && Array.isArray(raw.is_leader_in_dept) ? raw.is_leader_in_dept.map(o => Number(o)) : [];
+		return {
+			userid: String(raw.userid ?? ""),
+			name: raw.name == null ? null : String(raw.name),
+			departments,
+			orders,
+			leaderInDept: leader,
+			mainDepartment: detail && raw.main_department != null ? Number(raw.main_department) : null,
+			position: detail && raw.position != null ? String(raw.position) : null,
+			status: detail && raw.status != null ? Number(raw.status) : null,
+		};
+	}
+
+	/** 部门成员（接口 4，轻量）：`user/simplelist` 无 fetch_child，子部门要调用方自己递归 */
+	async function deptMembers(corpId: string, agentId: string, secret: string, deptOriginId: string): Promise<WecomMember[]> {
+		const res = await corpGet(corpId, agentId, secret, "/cgi-bin/user/simplelist", { department_id: deptOriginId }, "user/simplelist");
+		const list = Array.isArray(res.userlist) ? res.userlist as Array<Record<string, unknown>> : [];
+		return list.filter(u => u && u.userid != null).map(u => toMember(u, false));
+	}
+
+	/** 部门成员详情（接口 5，重量）：职务 / 排序 / 主部门 / 在职状态只有这里有；同一部门只该调一次 */
+	async function deptMembersDetail(corpId: string, agentId: string, secret: string, deptOriginId: string): Promise<WecomMember[]> {
+		const res = await corpGet(corpId, agentId, secret, "/cgi-bin/user/list", { department_id: deptOriginId }, "user/list");
+		const list = Array.isArray(res.userlist) ? res.userlist as Array<Record<string, unknown>> : [];
+		return list.filter(u => u && u.userid != null).map(u => toMember(u, true));
+	}
+
+	/**
+	 * 单成员详情（接口 6）：**登录自更新**用它，四次/次调用就够。
+	 *
+	 * best-effort：任何失败（无权限 / 不在可见范围 / 上游抖）返回 null，绝不抛出——
+	 * 补资料是体验优化，不能因为拿不到把登录打成 5xx。调用方拿到 null 就保留兜底值。
+	 */
+	async function userDetail(corpId: string, agentId: string, secret: string, userid: string): Promise<WecomMember | null> {
+		try {
+			const res = await corpGet(corpId, agentId, secret, "/cgi-bin/user/get", { userid }, "user/get");
+			// 回包偶尔不带 userid（老接口/精简回包）：入参就是权威，用入参补
+			return toMember({ ...res, userid: res.userid ?? userid }, true);
+		}
+		catch {
+			return null;
+		}
+	}
+
 	/**
 	 * 成员姓名（best-effort）：只用于把 JIT 号的 `display_name` 从工号变成真名。
 	 *
@@ -248,32 +503,9 @@ export function createWecomClient(deps: WecomClientDeps) {
 	 * token 复用 `userIdByCode` 刚取的那份缓存（同请求内通常 0 次额外换票）。
 	 */
 	async function userNameById(corpId: string, agentId: string, secret: string, userid: string): Promise<string | null> {
-		for (let attempt = 0; attempt < 2; attempt++) {
-			let token: string;
-			try {
-				token = await corpAccessToken(corpId, agentId, secret);
-			}
-			catch {
-				return null;
-			}
-			let res: Record<string, unknown>;
-			try {
-				res = await http.getJson(`${API_BASE}/cgi-bin/user/get?access_token=${encodeURIComponent(token)}&userid=${encodeURIComponent(userid)}`);
-			}
-			catch {
-				return null;
-			}
-			const errcode = Number(res.errcode ?? 0);
-			if (TOKEN_EXPIRED.has(errcode) && attempt === 0) {
-				await invalidateCorpToken(corpId, agentId);
-				continue;
-			}
-			if (errcode !== 0)
-				return null;
-			const name = res.name == null ? "" : String(res.name).trim();
-			return name || null;
-		}
-		return null;
+		const detail = await userDetail(corpId, agentId, secret, userid);
+		const name = detail?.name?.trim();
+		return name || null;
 	}
 
 	/** 网页授权 code → userid（snsapi_base；非企业成员/超出可见范围 → 401） */
@@ -296,7 +528,23 @@ export function createWecomClient(deps: WecomClientDeps) {
 		throw upstream("企微 token 反复失效（40001/42001）");
 	}
 
-	return { suiteAccessToken, permanentCodeByAuthCode, providerAccessToken, customizedAuthUrl, corpAccessToken, invalidateCorpToken, userIdByCode, userNameById };
+	return {
+		suiteAccessToken,
+		permanentCodeByAuthCode,
+		authModesByPermanentCode,
+		providerAccessToken,
+		customizedAuthUrl,
+		corpAccessToken,
+		invalidateCorpToken,
+		userIdByCode,
+		userNameById,
+		userDetail,
+		departmentChildren,
+		departmentDetail,
+		departmentList,
+		deptMembers,
+		deptMembersDetail,
+	};
 }
 
 export type WecomClient = ReturnType<typeof createWecomClient>;

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

@@ -153,7 +153,18 @@ export function readWecomConfig(): WecomConfig {
 	return v;
 }
 
-/** 企微后台「指令回调 URL」：原样填这个（base + /event） */
+/**
+ * 企微后台「指令回调 URL / 应用回调 URL」：原样填这个（base + `/event`）。
+ *
+ * **不带 `?callback_format=json`**——查过官方文档才这么定的：该参数只在「对外收款」的指令回调
+ * 文档（97478）里有说明，而代开发 / 第三方应用所属的**通用回调配置**（96238 §3.2）至今只写
+ * XML 外层信封（`<ToUserName><AgentID><Encrypt>`），全文没有这个参数；「部门通知事件」（92655）
+ * 虽给了 JSON 示例，但示例地址同样不带它，也没说怎么切过去。
+ *
+ * 也就是说：给我们这类回调加上它，是**文档未覆盖**的行为。省下的只是服务端一次正则，
+ * 代价却是把「企业管理员扫码能否装成功」押在上游实现上。服务端两种包体都认（payload.ts），
+ * 上游哪天默认改 JSON 也不用动这里。
+ */
 export function eventUrlOf(cfg: WecomConfig): string {
 	return `${cfg.baseUrl}/event`;
 }

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();
+}