@oj-module/cli 0.2.48 → 0.2.50

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

@@ -1,11 +1,13 @@
-import type { WecomConfig } from "../_shared/wecom/config";
+import type { CallbackCreds, WecomKind } from "../_shared/wecom/config";
+import type { SelfApp } from "../_shared/wecom/login";
 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
 // POST /api/auth/wecom/ticket  {ticket}          —— 一次性票据换 TokenBundle（token 不进 URL）
 // GET  /api/auth/wecom/event                     —— 企微回调 URL 验证（echostr 解出后原样回）
-// POST /api/auth/wecom/event                     —— 企微指令回调（suite_ticket / 授权 / 解绑）
+// POST /api/auth/wecom/event                     —— 企微回调（代开发指令事件 / 自建应用通讯录变更）
 //
 // 三处纪律：
 //   1. 两个 302 端点**不能**用 respond（它末尾无脑 json.ok，会把 302 覆盖成 200 信封）——
@@ -18,7 +20,17 @@ 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, readCallbackConfig, readWecomConfig, siteRootOf } from "../_shared/wecom/config";
+import {
+
+	callbackCreds,
+	loginRedirectOf,
+	readBase,
+	readCorpConfig,
+	readSuiteConfig,
+	siteRootOf,
+	wecomKinds,
+} from "../_shared/wecom/config";
+import { handleContactChange } from "../_shared/wecom/contacts";
 import { sha1Hex, unwrapWecomMessage, wecomSignature } from "../_shared/wecom/crypt";
 import { handleSuiteEvent } from "../_shared/wecom/events";
 import {
@@ -28,14 +40,16 @@ import {
 	LOGIN_TICKET_TTL_SECS,
 	loginLandingUrl,
 	putLoginState,
+	resolveWecomProfile,
+
 	selfUpdate,
 	takeLoginState,
 } from "../_shared/wecom/login";
 import { callbackFields, field } from "../_shared/wecom/payload";
-import { guardReplay, runtimeReplayGate } from "../_shared/wecom/replay";
+import { guardReplay, markApplied, ReplayAlreadyApplied, runtimeReplayGate } from "../_shared/wecom/replay";
 import { claimLoginTicket, ensureTenant, findProfile, issueLoginTicket, runtimeStoreDeps, tenantOfCorp } from "../_shared/wecom/store";
 
-// 模块级禁止 readWecomConfig()/createSession()/runtimeHttp()：oj build 的 introspect 在空沙箱里
+// 模块级禁止 readBase()/createSession()/runtimeHttp()：oj build 的 introspect 在空沙箱里
 // 评估模块（无 vars/jwt/fetch），一律在 handler 内按需构造（§9.4）。
 
 /** 请求头的读取按大小写不敏感处理（http.headers 的键大小写随客户端） */
@@ -51,7 +65,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();
 }
@@ -60,6 +74,19 @@ function badRequest(message: string): Error {
 	return Object.assign(new Error(message), { status: 400 });
 }
 
+/**
+ * 本部署自己那家企业内部应用（配了 `wecom_corp_*` 才有）。
+ *
+ * 作用是给登录入口一个**确定的默认目标**，而不是去猜档案里哪一行是「本站自己」：共存部署里
+ * 档案表还有别家企业通过代开发装进来的行，猜的代价是本站 `/login` 反过来回 400。
+ */
+function corpSelf(): SelfApp | undefined {
+	if (!wecomKinds().includes("corp"))
+		return undefined;
+	const c = readCorpConfig();
+	return { corpId: c.corpId, agentId: c.agentId };
+}
+
 /**
  * 解不开时把「哪一侧配错」记进日志——只回一句 `pkcs7: bad padding` 等于没给线索。
  *
@@ -68,23 +95,26 @@ function badRequest(message: string): Error {
  *     一个字符），或这条推送其实来自另一个套件/模板（那把钥匙解不开这份密文）。
  *     `aesKeyFp` 是本进程**实际加载**那把钥匙的指纹：改完 config 对不上就说明没生效（没重启/改错文件）。
  *   · `receiver mismatch` → **钥匙对、身份不对**。`receiveid` 已按候选试过（见 unwrapAccepting：
- *     suite_id + 信封 `ToUserName`），两边都对不上只剩两种：信封里没有 `ToUserName`，或这条推送
- *     既不属本部署套件、receiveid 也不是它自己声称的身份（伪造/转发）。
+ *     凭据自己的 receiver + 信封 `ToUserName`），两边都对不上只剩两种：信封里没有 `ToUserName`，
+ *     或这条推送既不属本部署、receiveid 也不是它自己声称的身份（伪造/转发）。
  *
- * 注意 `envelopeToUser` **不等于** `configuredSuite` 是正常的：数据回调的 `ToUserName` 是 corpid。
+ * `kind` 必须记：共存部署里有两套钥匙，日志不写「这次用的是哪套」，排障就退化成猜。
+ * 注意 `envelopeToUser` **不等于** `configuredReceiver` 是正常的：数据回调的 `ToUserName` 是 corpid。
  */
-function noteDecryptFailure(e: unknown, envelope: CallbackFields | null, cfg: { encodingAesKey: string, suiteId: string }): void {
+function noteDecryptFailure(e: unknown, envelope: CallbackFields | null, creds: CallbackCreds): void {
 	log.warn(
 		"wecom callback decrypt failed",
 		"reason",
 		(e as Error).message,
+		"kind",
+		creds.kind,
 		"envelopeToUser",
 		// URL 验证（GET）只有 query 里的 echostr，没有报文信封——那一侧记空串
 		envelope ? field(envelope, "ToUserName") : "",
-		"configuredSuite",
-		cfg.suiteId,
+		"configuredReceiver",
+		creds.receiver,
 		"aesKeyFp",
-		sha1Hex(cfg.encodingAesKey).slice(0, 8),
+		sha1Hex(creds.encodingAesKey).slice(0, 8),
 	);
 }
 
@@ -92,12 +122,12 @@ function noteDecryptFailure(e: unknown, envelope: CallbackFields | null, cfg: {
  * 按「可能合法的 receiveid」依次尝试解密。
  *
  * receiveid 的含义随场景变（90968 附注）：**第三方事件的回调是 suiteid**（suite_ticket / create_auth
- * / cancel_auth），**企业应用（含代开发应用的数据回调）是 corpid**（通讯录变更就走这条）。
+ * / cancel_auth），**企业应用（含代开发应用的数据回调、自建应用的通讯录事件）是 corpid**。
  * 我们一个端点吃两种，只认 suiteid 会把所有数据回调判成「解密失败」——而真正的错是「比错了值」。
  *
  * 只对 `receiver mismatch` 换下一个候选：`bad padding` 说明密钥就不对，换谁都解不开，直接抛。
  */
-function unwrapAccepting(encrypted: string, cfg: WecomConfig, candidates: string[]): string {
+function unwrapAccepting(encrypted: string, creds: CallbackCreds, candidates: string[]): string {
 	let lastErr: unknown;
 	const tried = new Set<string>();
 	for (const receiver of candidates) {
@@ -105,7 +135,7 @@ function unwrapAccepting(encrypted: string, cfg: WecomConfig, candidates: string
 			continue;
 		tried.add(receiver);
 		try {
-			return unwrapWecomMessage(encrypted, cfg.encodingAesKey, receiver);
+			return unwrapWecomMessage(encrypted, creds.encodingAesKey, receiver);
 		}
 		catch (e) {
 			if (!/receiver mismatch/.test((e as Error).message))
@@ -116,6 +146,14 @@ function unwrapAccepting(encrypted: string, cfg: WecomConfig, candidates: string
 	throw lastErr ?? new Error("wecom: 没有可比对的 receiveid（suite_id 未配置？）");
 }
 
+/** 用哪一把钥匙能验过签名：**逐个试**（SHA1 一次，成本可忽略），命中即用它的钥匙解密 */
+function matchCreds(encrypted: string): CallbackCreds | null {
+	const sig = query("msg_signature");
+	const ts = query("timestamp");
+	const nonce = query("nonce");
+	return callbackCreds().find(c => wecomSignature(c.token, ts, nonce, encrypted) === sig) ?? null;
+}
+
 /**
  * 校验企微回调签名并解出明文。签名不合法 → 400（不是 401：调用方是企微服务器，
  * 401 会被当成「本站需要鉴权」误导排查）；信封里的原文不回显，避免给探测者提供比对材料。
@@ -123,53 +161,75 @@ function unwrapAccepting(encrypted: string, cfg: WecomConfig, candidates: string
  * 三道顺序不可换：先验签（不给未鉴权请求写 kv）→ 再拦重放（省一次解密，也让
  * cancel_auth 这种危险性最高的报文止步在落库之前）→ 最后解密。
  */
-async function decryptVerified(encrypted: string, envelope: CallbackFields): Promise<{ cfg: WecomConfig, plain: string }> {
-	const cfg = readWecomConfig();
-	const expected = wecomSignature(cfg.token, query("timestamp"), query("nonce"), encrypted);
-	if (expected !== query("msg_signature"))
+async function decryptVerified(encrypted: string, envelope: CallbackFields): Promise<{ kind: WecomKind, plain: string, claim: ReplayClaim }> {
+	const creds = matchCreds(encrypted);
+	if (!creds)
 		throw badRequest("回调签名校验失败");
-	await guardReplay(query("timestamp"), query("nonce"), runtimeReplayGate());
+	const claim = await guardReplay(query("timestamp"), query("nonce"), runtimeReplayGate());
 	try {
 		// 信封的 ToUserName 就是这条报文的身份：套件事件里是 suiteid，应用数据回调里是 corpid，
-		// 与 receiveid 必然一致（两者在同一份密文/明文里，签名已经覆盖）。
-		return { cfg, plain: unwrapAccepting(encrypted, cfg, [cfg.suiteId, field(envelope, "ToUserName")]) };
+		// 与 receiver 必然一致（两者在同一份密文/明文里，签名已经覆盖）。
+		return { kind: creds.kind, plain: unwrapAccepting(encrypted, creds, [creds.receiver, field(envelope, "ToUserName")]), claim };
 	}
 	catch (e) {
+		// 解不开的这一条不能占住 nonce：企微重推是它唯一的恢复路径，占住就把重推挡成 400
+		await claim.release();
 		// 解密失败只对外透出「失败」：错钥/错套件/被篡改三者不可区分，也不该让外部据此判断哪一环配错
-		noteDecryptFailure(e, envelope, cfg);
+		noteDecryptFailure(e, envelope, creds);
 		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();
+			// 登录只用「与来源无关」的两项（落库密钥 + 基址）：自建模式没有 suite 凭据，
+			// 在这里读整套 suite 配置会把一条正常的登录打成 400。
+			const base = readBase();
+			const deps = runtimeStoreDeps(base);
+
 			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, corpSelf());
+				await guardLoginThrottle(ip, profile.corpId);
+			}
 
 			const state = crypto.randomHex(16);
 			await putLoginState(state, { corpId: profile.corpId, agentId: profile.agentId, env: profile.env }, runtimeCache());
 			const url = buildAuthorizeUrl({
 				corpId: profile.corpId,
 				agentId: profile.agentId,
-				redirectUri: loginRedirectOf(cfg),
+				redirectUri: loginRedirectOf(base),
 				state,
 				inWecom: /wxwork/i.test(header("user-agent")),
 			});
@@ -185,7 +245,7 @@ const callback = {
 	// 企微回跳：state 一次性（kv 取即删）→ profile → 绑租户 → code 换 userid → JIT 建档 → 发票 → 302。
 	async get() {
 		try {
-			const cfg = readWecomConfig();
+			const base = readBase();
 			const code = query("code");
 			const state = query("state");
 			// 用户在企业微信里点了「拒绝」时企微不回 code，只回 state
@@ -194,7 +254,7 @@ const callback = {
 			if (!state)
 				throw badRequest("登录状态缺失：请从企业微信重新进入");
 
-			const deps = runtimeStoreDeps(cfg);
+			const deps = runtimeStoreDeps(base);
 			const cache = runtimeCache();
 			const pending = await takeLoginState(state, cache);
 			const profile = await findProfile(pending.corpId, pending.agentId, deps);
@@ -224,7 +284,7 @@ const callback = {
 			await issueLoginTicket(crypto.sha256Hex(ticket), uid, tenant, LOGIN_TICKET_TTL_SECS, deps);
 			await noteLoginSucceeded(await clientIp(), profile.corpId);
 			log.info("wecom login ok", "tenant", tenant, "agentId", profile.agentId);
-			json.redirect.found(loginLandingUrl({ origin: siteRootOf(cfg), ticket, tenant }));
+			json.redirect.found(loginLandingUrl({ origin: siteRootOf(base), ticket, tenant }));
 		}
 		catch (e) {
 			failWith(e);
@@ -264,32 +324,35 @@ ticket.post.schema = {
 const event = {
 	// 企微后台「保存回调 URL」时会 GET 一次：解出 echostr 后**原样明文回**（不套信封、不加引号）。
 	//
-	// 只依赖 Tier A 凭据（readCallbackConfig）：token/aeskey/baseUrl/encKey 全部部署方本地生成，
-	// 不需要 suite_id——因此「配齐四项正确即可响应验证」，**不必等代开发模版创建、拿到 suite_id 之后**。
-	// 这正是打破鸡生蛋死锁（plan §18）的落点：先有可验证的回调，才能创建模版、拿到 suite 凭据。
+	// 只依赖回调凭据（`callbackCreds()`）：token/aeskey 由部署方与企微后台成对填写，不需要 suite_id——
+	// 因此「配齐即可响应验证」，**不必等代开发模版创建、拿到 suite_id 之后**。这正是打破鸡生蛋死锁
+	// （plan §18）的落点：先有可验证的回调，才能创建模版、拿到 suite 凭据。
+	//
+	// 共存部署有**两套**回调凭据（代开发的指令回调 / 自建应用的通讯录同步回调），企微用哪一套签名
+	// 取决于管理员在哪个后台点「保存」→ 逐个试签，命中哪套就用哪套钥匙解密。两套都没配才报错。
 	//
-	// suite_id 在「模版创建成功」后才下发；URL 验证可能发生在拿到 suite_id 之前（创建表单内联校验）。
-	// 加上「应用回调 URL 验证时 receiveid 是 corpid」这一层，GET 根本无从挑一个值来比 → 一律 tolerant，
-	// 见下面 try 里的说明（签名是唯一闸门，本端点不落状态）。
+	// URL 验证可能发生在拿到 suite_id 之前（创建表单内联校验），加上「应用回调 URL 验证时 receiveid
+	// 是 corpid」这一层，GET 根本无从挑一个值来比 → 一律 tolerant，见下面 try 里的说明
+	// （签名是唯一闸门，本端点不落状态）。
 	async get() {
 		try {
-			const cfg = readCallbackConfig();
 			const encrypted = query("echostr");
-			const expected = wecomSignature(cfg.token, query("timestamp"), query("nonce"), encrypted);
-			if (expected !== query("msg_signature"))
+			const creds = matchCreds(encrypted);
+			if (!creds)
 				throw badRequest("回调签名校验失败");
-			await guardReplay(query("timestamp"), query("nonce"), runtimeReplayGate());
-			const suiteId = (vars.get("wecom_suite_id") ?? "").trim();
+			const claim = await guardReplay(query("timestamp"), query("nonce"), runtimeReplayGate());
 			try {
 				// receiveid 一律不比对：GET 只有 echostr、没有报文信封，无从知道该比哪一个——
-				// 「模板/指令回调 URL」验证时 receiveid 是 suiteid，「应用回调 URL」验证时是 corpid。
+				// 「模板/指令回调 URL」验证时 receiveid 是 suiteid，「应用回调 URL / 通讯录同步」验证时是 corpid。
 				// 放宽是安全的：签名已过（token 只有本部署与企微知道），回包只是把解出的 echostr 原样返回，
 				// 不写任何状态；真正的 receiveid 比对在 POST 那条路径上（见 unwrapAccepting）。
-				plainText(unwrapWecomMessage(encrypted, cfg.encodingAesKey, suiteId, true));
+				plainText(unwrapWecomMessage(encrypted, creds.encodingAesKey, creds.receiver, true));
 			}
 			catch (e) {
+				// 验证没通过就放回 nonce：企微后台点「保存」会连着验几次，占住会把后几次都挡成 400
+				await claim.release();
 				// 解密失败只透出「失败」：错钥/未下发套件/被篡改三者不可区分，也不该让外部据此判断哪一环配错
-				noteDecryptFailure(e, null, { encodingAesKey: cfg.encodingAesKey, suiteId });
+				noteDecryptFailure(e, null, creds);
 				throw badRequest("回调消息解密失败");
 			}
 		}
@@ -298,23 +361,52 @@ const event = {
 		}
 	},
 
-	// 回调（指令 + 应用数据）：验签 → 解密 → 分发（suite_ticket / create_auth / change_auth /
-	// cancel_auth / reset_permanent_code）。回 `success` 才算收下，否则企微 5 秒后重推三次。
+	// 回调（指令 + 应用数据 + 通讯录同步）：验签 → 解密 → 按**命中凭据的来源**分发。
+	// 回 `success` 才算收下，否则企微 5 秒后重推三次。
+	//
+	// 来源分派是共存的关键：suite 凭据只可能收到套件事件（suite_ticket / create_auth / change_auth /
+	// cancel_auth）；corp 凭据只可能收到通讯录变更（企业管理员在「通讯录同步 → 接收事件服务器」填的本 URL），
+	// **没有**套件事件这回事，所以直接进 change_contact 分支，不进 handleSuiteEvent 的 switch。
 	//
 	// 包体形态按官方文档是 XML（见 payload.ts 的开头），但归一化那一层两种都认，
 	// 所以本函数只认字段名，不认格式。
 	async post() {
+		let claim: ReplayClaim | undefined;
 		try {
 			const envelope = callbackFields(http.body);
 			const encrypted = field(envelope, "Encrypt");
 			if (!encrypted)
 				throw badRequest("回调报文缺少 Encrypt（不是企微回调，或中间件改写了请求体）");
-			const { cfg, plain } = await decryptVerified(encrypted, envelope);
+			const verified = await decryptVerified(encrypted, envelope);
+			claim = verified.claim;
+
 			const client = createWecomClient({ http: runtimeHttp(), cache: runtimeCache() });
-			await handleSuiteEvent(plain, { cfg, client, store: runtimeStoreDeps(cfg) });
+			if (verified.kind === "corp") {
+				// 自建应用没有套件流程：报文只可能是 change_contact（其余形态由 contacts.ts 记账后放过）
+				await handleContactChange(callbackFields(verified.plain), {
+					client,
+					store: runtimeStoreDeps(readBase()),
+					credentialKind: "corp",
+				});
+			}
+			else {
+				const cfg = readSuiteConfig();
+				await handleSuiteEvent(verified.plain, { cfg, client, store: runtimeStoreDeps(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 };

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

@@ -18,7 +18,7 @@ import { assertPermission, assertTenantSelf } from "#/_platform/_shared/service/
 import { recordOp } from "#/_platform/_shared/service/infra/audit";
 import { rateLimit } from "#/_platform/_shared/service/infra/rate";
 import { createWecomClient, runtimeCache, runtimeHttp } from "../../_shared/wecom/client";
-import { readWecomConfig } from "../../_shared/wecom/config";
+import { corpIdentity, readBase } from "../../_shared/wecom/config";
 import { findProfile, probeProfile, runtimeStoreDeps } from "../../_shared/wecom/store";
 import { attachProfile, cancelSync, emptyView, startSync, syncStatus } from "../../_shared/wecom/sync";
 
@@ -44,12 +44,15 @@ const STATS = {
 
 const VIEW = {
 	type: "object",
-	required: ["connected", "authMode", "profileStatus", "status", "phase", "stats", "progress", "errCode", "errDetail", "startedAt", "finishedAt", "updateTime"],
+	required: ["connected", "authMode", "profileStatus", "agentId", "credentialKind", "status", "phase", "stats", "progress", "errCode", "errDetail", "startedAt", "finishedAt", "updateTime"],
 	properties: {
 		// 授权事实（页面据此决定「整条隐藏 / 成员授权卡片 / 冻结黄条 / 正常同步栏」）
 		connected: { type: "boolean" },
 		authMode: { type: "number" },
 		profileStatus: { type: ["string", "null"] },
+		// 分辨锚点：多应用/共存企业下前端必须原样回传（C6）
+		agentId: { type: ["string", "null"] },
+		credentialKind: { type: ["string", "null"], enum: ["suite", "corp", null] },
 		status: { type: "string", enum: ["idle", "running", "done", "failed", "cancelled"] },
 		phase: { type: "string", enum: ["departments", "members", "reconcile"] },
 		stats: STATS,
@@ -80,6 +83,18 @@ function agentOf(raw: unknown): string | null {
 	return s.length > 0 ? s : null;
 }
 
+/**
+ * 未带 agent 时的兜底：**只有当本租户就是本部署自建的那家企业**才用配置里的 agent。
+ *
+ * 共存下的双应用租户（同一 corp 同时有代开发行与自建行）不带 agent 时探针只能 400，
+ * 而「点进自己组织架构页」不该要求管理员手填应用 id。别家企业没有这个兜底——
+ * 它们的 agent 只能来自登录链接/状态条回传，不由本站配置决定（那正是代开发的意义）。
+ */
+function selfAgentOf(tenantId: string): string | null {
+	const self = corpIdentity();
+	return self && self.corpId === tenantId ? self.agentId : null;
+}
+
 /**
  * 解析当前租户的授权档案（企业代码 = 租户；多应用时必须带 agent）。
  *
@@ -88,14 +103,15 @@ function agentOf(raw: unknown): string | null {
  * 是自己填错了），findProfile 负责解密出 permanent_code。
  */
 async function profileOf(tenantId: string, agent: unknown) {
-	const probe = await probeProfile(tenantId, agentOf(agent));
+	const probe = await probeProfile(tenantId, agentOf(agent) ?? selfAgentOf(tenantId));
 	if (!probe) {
 		throw Object.assign(new Error("本站尚未开通企业微信：没有可同步的授权记录"), { status: 400 });
 	}
 	if (probe.status !== "active") {
 		throw Object.assign(new Error("该企业已取消授权或应用已停用：组织架构同步已冻结，请联系服务商重新开通"), { status: 400 });
 	}
-	const cfg = readWecomConfig();
+	// 同步只用与来源无关的两项（落库密钥 + 基址）：读整套 suite 配置会把自建部署打成 400
+	const cfg = readBase();
 	const profile = await findProfile(tenantId, probe.agentId, runtimeStoreDeps(cfg));
 	return { profile, probe, cfg };
 }
@@ -149,7 +165,7 @@ const status = {
 			const tenantId = currentTenant();
 			if (!tenantId)
 				throw Object.assign(new Error("缺少租户上下文"), { status: 400 });
-			const probe = await probeProfile(tenantId, agentOf((http.query as Record<string, unknown>).agent));
+			const probe = await probeProfile(tenantId, agentOf((http.query as Record<string, unknown>).agent) ?? selfAgentOf(tenantId));
 			if (!probe)
 				return attachProfile(emptyView("idle"), null);
 			return attachProfile(await syncStatus(tenantId, probe.agentId), probe);

package/templates/src/auth/web/__client/api.schemas.ts

@@ -19,6 +19,7 @@ export const schemas = {
 	"env": z.string(),
 	"corp_name": z.string().nullable().optional(),
 	"status": z.enum(["active", "disabled"]),
+	"credential_kind": z.enum(["suite", "corp"]),
 	"auth_mode": z.number(),
 	"installed_at": z.number(),
 	"update_time": z.number()
@@ -40,6 +41,24 @@ export const schemas = {
 	"installUrl": z.string(),
 	"callbackUrl": z.string(),
 	"expiresIn": z.number()
+}),
+	},
+	"authWecomAdminOverviewGet": {
+		data: z.object({
+	"kinds": z.array(z.enum(["suite", "corp"])),
+	"configError": z.string().nullable(),
+	"callbackUrl": z.string().nullable(),
+	"corpId": z.string().nullable(),
+	"agentId": z.string().nullable(),
+	"corpCallbackConfigured": z.boolean()
+}),
+	},
+	"authWecomAdminConnectPost": {
+		data: z.object({
+	"corpId": z.string(),
+	"agentId": z.string(),
+	"departments": z.number(),
+	"members": z.number()
 }),
 	},
 	"authWecomTicketPost": {
@@ -108,7 +127,9 @@ export const schemas = {
 }).nullable(),
 	"startedAt": z.number(),
 	"finishedAt": z.number(),
-	"updateTime": z.number()
+	"updateTime": z.number(),
+	"agentId": z.string().nullable(),
+	"credentialKind": z.union([z.literal("suite"), z.literal("corp"), z.literal(null)]).nullable()
 }),
 	},
 	"authWecomSyncCancelPost": {

package/templates/src/auth/web/__client/api.ts

@@ -33,7 +33,7 @@ export function createAuthClient(ctx: ModuleContext) {
 	}
 	ctx.register.apiPrefix(API_PREFIX);
 	bindRequest(ctx.utils.request);
-	return { authLoginPost, authLogoutPost, authRefreshPost, authPasswordPut, authLdapLoginPost, authWecomAdminAppsGet, authWecomAdminStatusPost, authWecomAdminInstallGet, authWecomLoginGet, authWecomCallbackGet, authWecomTicketPost, authWecomEventGet, authWecomEventPost, authWecomSyncStartPost, authWecomSyncStatusGet, authWecomSyncCancelPost };
+	return { authLoginPost, authLogoutPost, authRefreshPost, authPasswordPut, authLdapLoginPost, authWecomAdminAppsGet, authWecomAdminStatusPost, authWecomAdminInstallGet, authWecomAdminOverviewGet, authWecomAdminConnectPost, authWecomLoginGet, authWecomCallbackGet, authWecomTicketPost, authWecomEventGet, authWecomEventPost, authWecomSyncStartPost, authWecomSyncStatusGet, authWecomSyncCancelPost };
 }
 
 /**
@@ -211,6 +211,52 @@ export async function authWecomAdminInstallGet(): Promise<AuthWecomAdminInstallG
 	}
 }
 
+export type AuthWecomAdminOverviewGetData = z.infer<(typeof schemas)["authWecomAdminOverviewGet"]["data"]>;
+
+export async function authWecomAdminOverviewGet(): Promise<AuthWecomAdminOverviewGetData> {
+	const client = ensureReq();
+	try {
+		const env = await client.get(`auth/wecom/admin/overview`).json<OjEnvelope<AuthWecomAdminOverviewGetData>>();
+		// 2xx + code!==0 也是业务错误（§6.2 通道 a）：oj 不会这么发，但契约机制的价值恰是防漂移
+		if (typeof env.code === "number" && env.code !== 0)
+			throw new ContractApiError(env.code, env.msg ?? "业务错误（信封 code 非 0）");
+		const data = env.data as AuthWecomAdminOverviewGetData;
+		if (import.meta.env.DEV) {
+			const { schemas } = await import("./api.schemas");
+			const r = schemas["authWecomAdminOverviewGet"].data.safeParse(data);
+			if (!r.success)
+				throw new ContractApiError(-1, `[契约违例] authWecomAdminOverviewGet 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+		}
+		return data;
+	}
+	catch (e) {
+		throw await toApiError(e);
+	}
+}
+
+export type AuthWecomAdminConnectPostData = z.infer<(typeof schemas)["authWecomAdminConnectPost"]["data"]>;
+
+export async function authWecomAdminConnectPost(): Promise<AuthWecomAdminConnectPostData> {
+	const client = ensureReq();
+	try {
+		const env = await client.post(`auth/wecom/admin/connect`).json<OjEnvelope<AuthWecomAdminConnectPostData>>();
+		// 2xx + code!==0 也是业务错误（§6.2 通道 a）：oj 不会这么发，但契约机制的价值恰是防漂移
+		if (typeof env.code === "number" && env.code !== 0)
+			throw new ContractApiError(env.code, env.msg ?? "业务错误（信封 code 非 0）");
+		const data = env.data as AuthWecomAdminConnectPostData;
+		if (import.meta.env.DEV) {
+			const { schemas } = await import("./api.schemas");
+			const r = schemas["authWecomAdminConnectPost"].data.safeParse(data);
+			if (!r.success)
+				throw new ContractApiError(-1, `[契约违例] authWecomAdminConnectPost 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+		}
+		return data;
+	}
+	catch (e) {
+		throw await toApiError(e);
+	}
+}
+
 export async function authWecomLoginGet(): Promise<unknown> {
 	const client = ensureReq();
 	try {

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

@@ -31,6 +31,8 @@
 		"wecom": "WeCom",
 		"wecom.action": "Sign in with WeCom",
 		"wecom.hint": "Enter the enterprise code (corp_id, visible in the WeCom console), or use the dedicated sign-in link from your admin",
+		"wecom.agent": "App ID (agentid)",
+		"wecom.agentHint": "Leave empty if the corp has a single app; otherwise use the agentid provided by your admin",
 		"wecom.exchanging": "Completing WeCom sign-in…"
 	}
 }

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

@@ -31,6 +31,8 @@
 		"wecom": "企业微信",
 		"wecom.action": "使用企业微信登录",
 		"wecom.hint": "填写企业代码（企微后台可见的 corp_id），或直接使用管理员收到的专属登录链接",
+		"wecom.agent": "应用 ID（agentid）",
+		"wecom.agentHint": "留空使用该企业下唯一应用；多应用部署请填管理员提供的 agentid",
 		"wecom.exchanging": "正在完成企业微信登录…"
 	}
 }