@oj-module/cli 0.2.46 → 0.2.48

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}`);
@@ -93,6 +118,88 @@ 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 的读法永远一致（同步闸门认的就是这个值）。
+ */
+function agentListOf(authInfo: unknown): Array<Record<string, unknown>> {
+	const list = (authInfo as Record<string, unknown> | undefined)?.agent;
+	return Array.isArray(list) ? list.map(a => a as Record<string, unknown>) : [];
+}
+
+/**
+ * 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;
 
@@ -131,15 +238,15 @@ 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)
-			: [];
+		const agents = agentListOf(res.auth_info);
+		const agentIds = agents.map(a => String(a.agentid)).filter(Boolean);
 		if (!res.permanent_code || !authCorp.corpid)
 			throw upstream("企微 get_permanent_code 返回缺少 permanent_code / corpid");
 		if (agentIds.length === 0)
@@ -149,20 +256,70 @@ export function createWecomClient(deps: WecomClientDeps) {
 			corpId: String(authCorp.corpid),
 			corpName: authCorp.corp_name == null ? null : String(authCorp.corp_name),
 			agentIds,
+			authModes: readAuthModes(res.auth_info),
 			state: res.state == null ? null : String(res.state),
 		};
 	}
 
 	/**
-	 * 预授权码（开通入口用）：套件级、10 分钟、一次有效，拼进 install URL 交给企业管理员点开。
-	 * 与 permanent_code 无关——它只换「安装向导里那一屏同意」，真正的永久码仍由 create_auth 回调给。
+	 * 复核授权模式（`get_auth_info`）：`change_auth` 事件只带 AuthCorpId、**不带 AuthCode**，
+	 * 所以刷新 auth_mode 只能拿已存的 permanent_code 反查。企业管理员在后台把「管理员授权」
+	 * 切成「成员授权」（或反向）就靠这条路径同步——切过去以后部门接口一律 60011，
+	 * 不刷新就会一直按「可同步」对待。
 	 */
-	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 authModesByPermanentCode(suiteAccessToken: string, corpId: string, permanentCode: string): Promise<Record<string, number>> {
+		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 readAuthModes(res.auth_info);
+	}
+
+	/**
+	 * 服务商级 token（provider_access_token）：代开发「生成授权链接」用，与套件 token 不同源。
+	 * 由服务商 corpid + provider_secret 换得，全部署共享一份（不限 suite）。
+	 * 注意：这是**服务商**凭证，不是 suite 凭证——代开发的 `get_customized_auth_url`
+	 * 只认 provider_access_token（用 suite_access_token 调会报 token 无效类错误）。
+	 */
+	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） */
@@ -180,6 +337,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` 从工号变成真名。
 	 *
@@ -189,32 +467,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） */
@@ -237,7 +492,23 @@ export function createWecomClient(deps: WecomClientDeps) {
 		throw upstream("企微 token 反复失效（40001/42001）");
 	}
 
-	return { suiteAccessToken, permanentCodeByAuthCode, preAuthCode, 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

@@ -41,6 +41,14 @@ 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 / 落库密钥 / 基址）。
@@ -57,6 +65,14 @@ const REQUIRED_SUITE: Array<[keyof WecomConfig, string]> = [
 	["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 {
@@ -66,6 +82,8 @@ function readWecomVars(): WecomConfig {
 		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") ?? "",
 	};
 }
 
@@ -90,6 +108,16 @@ export function assertEncKey(encKey: string): void {
 		throw Object.assign(new Error("企业微信配置错误：wecom_enc_key 必须是 16 或 32 字节的 hex（32/64 字符）或 base64"), { status: 400 });
 }
 
+/**
+ * 校验服务商凭证（生成授权链接必需）。缺任一即 400 并点名缺哪两项——
+ * 区分于 suite 凭证：那是「模版创建后下发」，provider 凭证是「服务商后台通用开发参数」里拿的。
+ */
+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 尚未下发）
@@ -125,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`;
 }
@@ -153,22 +192,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 }>;