@oj-module/cli 0.2.49 → 0.2.53

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

@@ -21,6 +21,7 @@ import { invalidateAllUsers } from "#/_platform/_shared/service/infra/access";
 import { recordOp } from "#/_platform/_shared/service/infra/audit";
 import { handleContactChange } from "./contacts";
 import { callbackFields, field, requireField } from "./payload";
+import { provisionTenantAdmin } from "./tenant-admin";
 import { corpScope, ensureTenant, findCorpAuth, getSuiteTicket, putSuiteTicket, revokeTenantSessions, saveProfile, setAuthMode, setProfileStatus, tenantOfCorp } from "./store";
 
 /** suite_ticket 官方有效期 30 分钟（10 分钟推一次）；本地按 30 分钟作废，宁可拒一次也不拿过期票打企微 */
@@ -59,16 +60,32 @@ async function auditAuth(action: string, corpId: string, detail?: unknown, level
 	}
 }
 
-/** 该 corp 的所有应用都标记为停用，并吊销其租户下的全部会话 */
+/** 该 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 }>;
+	// 只取 suite 行：共存部署里同一家企业可能还有自建应用，cancel_auth 与它无关（C4）
+	const rows = await db.table("wecom_app_profile").select(["agent_id"]).where({
+		and: [corpScope(corpId), { field: "credential_kind", op: "eq", value: "suite" }],
+	}).all() as Array<{ agent_id: string }>;
 	for (const r of rows)
 		await deps.client.invalidateCorpToken(corpId, String(r.agent_id));
-	await setProfileStatus(corpId, "disabled", deps.store);
-	// 会话必须与授权同频：解绑后旧 refresh 串不得继续换新 access token。
+	await setProfileStatus(corpId, "disabled", deps.store, "suite");
+	await revokeOrKeep(corpId);
+}
+
+/**
+ * 会话与授权同频：解绑后旧 refresh 串不得继续换新 access token。
+ * 但「还有别的应用在用」时不吊销（同 `admin.ts::setAppStatus` 的语义）——否则取消代开发授权
+ * 会把同一家企业自建应用的在线用户一起踢下线。
+ */
+async function revokeOrKeep(corpId: string): Promise<void> {
+	const still = await db.table("wecom_app_profile").select(["agent_id"]).where({
+		and: [corpScope(corpId), { field: "status", op: "eq", value: "active" }],
+	}).all();
+	if (still.length)
+		return;
 	// tenant 条件写死在 SQL 里（不用 truncate：它的清理范围取决于本请求是否已绑过租户），
 	// 取消授权回调是匿名端点，不该依赖那种隐式前提。
 	await revokeTenantSessions(tenantOfCorp(corpId));
@@ -93,12 +110,16 @@ async function applyAuthCode(authCode: string, state: string | null, deps: Suite
 			agentId,
 			env,
 			corpName: granted.corpName,
+			// 来源由这一条路径决定：能走到 create_auth 的只可能是代开发
+			credentialKind: "suite",
 			permanentCode: granted.permanentCode,
 			authMode: granted.authModes[agentId] ?? 0,
 		}, store);
 		// secret 可能已轮换：旧 token 必须立刻作废，否则下一个登录会带着失效 token 打 userinfo
 		await client.invalidateCorpToken(granted.corpId, agentId);
 	}
+	// 租户具象化：代开发企业授权成功即配一个本租户管理员（尽力而为，绝不拖垮 1 秒回调窗口）
+	await provisionTenantAdmin(granted.corpId);
 	await auditAuth("wecom.auth.apply", granted.corpId, { agentIds: granted.agentIds, env });
 	return { corpId: granted.corpId, agentIds: granted.agentIds };
 }
@@ -112,7 +133,8 @@ async function applyAuthCode(authCode: string, state: string | null, deps: Suite
  */
 async function refreshAuthModes(corpId: string, deps: SuiteEventDeps): Promise<void> {
 	try {
-		const auth = await findCorpAuth(corpId, deps.store);
+		// 只对 suite 行成立：自建应用没有「授权模式」这个概念，给它刷 auth_mode 只会写脏数据（C5）
+		const auth = await findCorpAuth(corpId, deps.store, "suite");
 		if (!auth)
 			return;
 		const ticket = await getSuiteTicket(deps.cfg.suiteId, deps.store);
@@ -147,7 +169,7 @@ export async function handleSuiteEvent(payload: unknown, deps: SuiteEventDeps):
 	// 落进 default 只会被记成「不消费的事件」。
 	// 与下面几个分支的不同：通讯录事件失败**不抛**（事件是加速器，重推补不回来，见 contacts.ts）。
 	if (field(fields, "Event") === "change_contact" || infoType === "change_contact")
-		return await handleContactChange(fields, deps);
+		return await handleContactChange(fields, { client: deps.client, store: deps.store, credentialKind: "suite" });
 
 	switch (infoType) {
 		case "suite_ticket": {

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

@@ -62,32 +62,40 @@ export function buildAuthorizeUrl(opts: {
 /**
  * 代开发模板常只服务一家企业：登录入口不传 corp 时，从已安装档案自动解析，
  * 让「应用主页」直接填 https://<域名>/login 即可（无需 ${corpid} 占位符，避开企微后台对非法 URL 字符的校验）。
- * agent 未指定且该企业多应用时，取首个活跃应用以 corp 维度授权。
+ *
+ * `self` = 本部署自己那家企业内部应用（`wecom_corp_*` 配了什么）。
+ * 共存部署里必须传：否则别家企业通过代开发装进来的档案会把「本站默认登录哪家企业」淹掉，
+ * 本站自己的 `/login` 反倒回 400「已授权多家企业」。传了就按「自己的企业优先」解析，
+ * 且默认 agent 也来自配置，不再依赖写死的应用 id。
  */
-// 未指定 agent 且多应用时，优先作为默认登录应用的 agent（按部署需要调整）
-const DEFAULT_WECOM_AGENT = "1000059";
+export interface SelfApp {
+	corpId: string
+	agentId: string
+}
 
-export async function resolveWecomProfile(agentId: string | null): Promise<{ corpId: string, agentId: string, env: string }> {
+export async function resolveWecomProfile(agentId: string | null, self?: SelfApp): Promise<{ corpId: string, agentId: string, env: string }> {
 	const rows = await db.table("wecom_app_profile")
 		.select(["corp_id", "agent_id", "env", "status"])
 		.where({ field: "status", op: "eq", value: "active" })
 		.all() as Array<{ corp_id: string, agent_id: string, env: string | null, status: string }>;
 	const active = rows.filter(r => String(r.status) === "active");
 	if (!active.length)
-		throw Object.assign(new Error("尚未完成企业微信授权（无已安装应用档案），请先走「生成开通链接」完成授权"), { status: 400 });
-	const corps = [...new Set(active.map(r => r.corp_id))];
+		throw Object.assign(new Error("尚未完成企业微信接入（无可用应用档案）：代开发请先扫码开通；企业内部应用请在后台点「验证并接入」"), { status: 400 });
+	const pool = self ? active.filter(r => String(r.corp_id) === self.corpId) : active;
+	if (!pool.length)
+		throw Object.assign(new Error("本次部署配置的企业内部应用尚未接入：请在后台点「验证并接入」"), { status: 400 });
+	const corps = [...new Set(pool.map(r => String(r.corp_id)))];
 	if (corps.length > 1 && !agentId)
 		throw Object.assign(new Error("已授权多家企业，请在登录链接带 corp 参数以区分"), { status: 400 });
-	const corpId = corps[0]!;
-	const agents = active.filter(r => r.corp_id === corpId);
-	// 指定 agent 就必须命中，未指定则退到默认 agent / 首个活跃应用（agents 非空：active 已非空且
-	// 至少有一个属于 corpId——corps 就是按 active 的 corp_id 去重出来的）
+	const corpId = self ? self.corpId : corps[0]!;
+	const agents = pool.filter(r => String(r.corp_id) === corpId);
+	// 指定 agent 就必须命中；未指定时：自建应用优先取配置里的 agent，否则取首个活跃应用
 	const pick = agentId
-		? agents.find(a => a.agent_id === agentId)
-		: (agents.find(a => a.agent_id === DEFAULT_WECOM_AGENT) ?? agents[0]);
+		? agents.find(a => String(a.agent_id) === agentId)
+		: (self ? agents.find(a => String(a.agent_id) === self.agentId) : undefined) ?? agents[0];
 	if (!pick)
 		throw Object.assign(new Error("指定的 agent 在该企业中不存在"), { status: 400 });
-	return { corpId: pick.corp_id, agentId: pick.agent_id, env: pick.env == null ? "prod" : String(pick.env) };
+	return { corpId: String(pick.corp_id), agentId: String(pick.agent_id), env: pick.env == null ? "prod" : String(pick.env) };
 }
 
 export async function putLoginState(nonce: string, pending: PendingLogin, cache: WecomCache): Promise<void> {

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

@@ -7,7 +7,7 @@
 //
 // permanent_code（= 代开发应用的 secret，全 corp 数据权限）只以 AES-GCM 密文落库（§7.5），
 // 加解密经 deps 注入：Node 侧测试用假实现，运行时走 crypto.aesGcmEncrypt/Decrypt。
-import type { WecomConfig } from "./config";
+import type { WecomBase, WecomKind } from "./config";
 
 export interface WecomStoreDeps {
 	encrypt: (plain: string) => string
@@ -26,6 +26,13 @@ export interface AppProfile {
 	env: string
 	corpName: string | null
 	status: "active" | "disabled"
+	/**
+	 * 这一行的凭据来源（0003 列）。**不是标签，是语义**：
+	 *   · suite 行由 create_auth 写入，permanent_code 里是代开发换来的 secret；
+	 *   · corp 行由「验证并接入」写入，里面是应用详情页的 Secret（suite_id 为空串）。
+	 * 同一 corp_id 两行共存时，靠它决定「取消代开发授权该停哪一行」。
+	 */
+	credentialKind: WecomKind
 	permanentCode: string
 	/** 0=管理员授权 / 1=成员授权（成员授权下应用无任何部门权限，组织架构同步必然 60011，§2.3） */
 	authMode: number
@@ -92,6 +99,30 @@ export function corpAgentScope(corpId: string, agentId: string) {
 	};
 }
 
+/**
+ * 企业范围 + 可选的来源过滤。
+ *
+ * 共存部署里**同一家**企业可能同时有代开发行与自建行（迁移期最常见），而「取消代开发授权」
+ * 「复核授权模式」「找 secret」这三件事都只对 suite 行成立。不传 kind = 不过滤（保持
+ * 单来源部署的原行为，`suite_id` 主键天然只有一类行）。
+ */
+function corpKindScope(corpId: string, kind?: WecomKind) {
+	const base = corpScope(corpId);
+	if (!kind)
+		return base;
+	return {
+		and: [
+			base,
+			{ field: "credential_kind", op: "eq", value: kind },
+		],
+	};
+}
+
+/** 行 → 来源（库里的列是 text；只有明确写了 corp 才算自建，其余按代开发） */
+function kindOfRow(r: Record<string, unknown>): WecomKind {
+	return String(r.credential_kind) === "corp" ? "corp" : "suite";
+}
+
 /**
  * 吊销某租户的全部会话（refresh token）。
  *
@@ -121,6 +152,9 @@ export async function saveProfile(p: Omit<AppProfile, "status"> & { status?: App
 		env: p.env,
 		corp_name: p.corpName,
 		status: p.status ?? "active",
+		// 来源同时落在两处：主键里的 suite_id（corp 行为空串）与这一列（可读、可过滤）。
+		// 更新路径也写：存量 suite 行被 corp 接入覆盖时（人工导错）不该留着旧标注。
+		credential_kind: p.credentialKind,
 		permanent_code_enc: deps.encrypt(p.permanentCode),
 		// 授权模式是「该企业应用能不能做组织架构同步」的判据（§2.3）；重授权时必须跟着刷新
 		auth_mode: Number(p.authMode ?? 0),
@@ -146,9 +180,12 @@ export async function saveProfile(p: Omit<AppProfile, "status"> & { status?: App
 /**
  * 按企业代码找应用。`agentId` 为空时要求该企业只有一个启用中的应用。
  * 「企业不存在」与「已停用」返回**同一条文案**（§5.3 枚举风险：不让外部探测哪些企业装过）。
+ *
+ * `agentId` 已唯一确定一行（主键第三段），所以 `kind` 只是**加一层保险**：
+ * 事件路径知道自己验签过的是哪套凭据，带上它就不会在同名 agent 撞车时取错 secret。
  */
-export async function findProfile(corpId: string, agentId: string | null, deps: WecomStoreDeps): Promise<AppProfile> {
-	const rows = await db.table("wecom_app_profile").select(["*"]).where(corpScope(corpId)).all() as Array<Record<string, unknown>>;
+export async function findProfile(corpId: string, agentId: string | null, deps: WecomStoreDeps, kind?: WecomKind): Promise<AppProfile> {
+	const rows = await db.table("wecom_app_profile").select(["*"]).where(corpKindScope(corpId, kind)).all() as Array<Record<string, unknown>>;
 	const active = rows.filter(r => String(r.status) === "active");
 	const picked = agentId ? active.filter(r => String(r.agent_id) === agentId) : active;
 	if (picked.length === 0)
@@ -157,13 +194,14 @@ export async function findProfile(corpId: string, agentId: string | null, deps:
 		fail(400, "该企业开通了多个应用，登录链接必须带 agent 参数");
 	const r = picked[0]!;
 	return {
-		suiteId: String(r.suite_id),
+		suiteId: String(r.suite_id ?? ""),
 		corpId: String(r.corp_id),
 		authCorpId: r.auth_corp_id == null ? String(r.corp_id) : String(r.auth_corp_id),
 		agentId: String(r.agent_id),
 		env: r.env == null ? "prod" : String(r.env),
 		corpName: r.corp_name == null ? null : String(r.corp_name),
 		status: String(r.status) === "disabled" ? "disabled" : "active",
+		credentialKind: kindOfRow(r),
 		permanentCode: deps.decrypt(String(r.permanent_code_enc)),
 		authMode: Number(r.auth_mode ?? 0),
 	};
@@ -174,6 +212,8 @@ export interface ProfileProbe {
 	agentId: string
 	authMode: number
 	status: AppProfile["status"]
+	/** 来源：corp 行没有「授权模式」概念，页面不该给它画成员授权卡片 */
+	credentialKind: WecomKind
 }
 
 /**
@@ -186,8 +226,8 @@ export interface ProfileProbe {
  * 选中口径与 `findProfile` 对齐（优选启用中的应用；全停用时退回停用行，让页面能画
  * 「已取消授权」冻结态），只多一条：没有启用应用时也返回，而不是 400。
  */
-export async function probeProfile(corpId: string, agentId: string | null): Promise<ProfileProbe | null> {
-	const rows = await db.table("wecom_app_profile").select(["agent_id", "auth_mode", "status"]).where(corpScope(corpId)).all() as Array<Record<string, unknown>>;
+export async function probeProfile(corpId: string, agentId: string | null, kind?: WecomKind): Promise<ProfileProbe | null> {
+	const rows = await db.table("wecom_app_profile").select(["agent_id", "auth_mode", "status", "credential_kind"]).where(corpKindScope(corpId, kind)).all() as Array<Record<string, unknown>>;
 	if (rows.length === 0)
 		return null;
 	const active = rows.filter(r => String(r.status) === "active");
@@ -202,12 +242,17 @@ export async function probeProfile(corpId: string, agentId: string | null): Prom
 		agentId: String(r.agent_id),
 		authMode: Number(r.auth_mode ?? 0),
 		status: String(r.status) === "disabled" ? "disabled" : "active",
+		credentialKind: kindOfRow(r),
 	};
 }
 
-/** 停用/解绑：只改状态，不删行（取消授权也要留痕，§7.5 审计） */
-export async function setProfileStatus(corpId: string, status: AppProfile["status"], deps: WecomStoreDeps): Promise<number> {
-	return Number(await db.table("wecom_app_profile").update({ status, update_time: deps.now() }).where(corpScope(corpId)).run());
+/**
+ * 停用/解绑：只改状态，不删行（取消授权也要留痕，§7.5 审计）。
+ * `kind` 缺省 = 该企业的全部行（单来源部署的原行为）；传 `suite` 才是 cancel_auth 该做的——
+ * 代开发被取消授权时不能顺手把同一家企业的自建应用一起停掉。
+ */
+export async function setProfileStatus(corpId: string, status: AppProfile["status"], deps: WecomStoreDeps, kind?: WecomKind): Promise<number> {
+	return Number(await db.table("wecom_app_profile").update({ status, update_time: deps.now() }).where(corpKindScope(corpId, kind)).run());
 }
 
 /**
@@ -217,15 +262,19 @@ export async function setProfileStatus(corpId: string, status: AppProfile["statu
  *
  * 一并返回 `corpId`（真实企业 ID）：事件里给的可能是 `AuthCorpId`（第三方体系下是 open_corpid），
  * 而租户键只能用真实 corp_id（D10），故由这里统一把「事件身份 → 租户身份」的翻译交出来。
+ *
+ * `kind` 由**事件入口**传下来（本次验签命中的是哪套凭据）：同一家企业双应用时，
+ * 取错 kind 就会拿另一套 secret 去换 token，症状是 40001 而不是「配置错了」。
  */
-export async function findCorpAuth(corpId: string, deps: WecomStoreDeps): Promise<{ corpId: string, permanentCode: string, agentIds: string[] } | null> {
-	const rows = await db.table("wecom_app_profile").select(["corp_id", "agent_id", "permanent_code_enc"]).where(corpScope(corpId)).all() as Array<Record<string, unknown>>;
+export async function findCorpAuth(corpId: string, deps: WecomStoreDeps, kind?: WecomKind): Promise<{ corpId: string, permanentCode: string, agentIds: string[], credentialKind: WecomKind } | null> {
+	const rows = await db.table("wecom_app_profile").select(["corp_id", "agent_id", "permanent_code_enc", "credential_kind"]).where(corpKindScope(corpId, kind)).all() as Array<Record<string, unknown>>;
 	if (rows.length === 0)
 		return null;
 	return {
 		corpId: String(rows[0]!.corp_id),
 		permanentCode: deps.decrypt(String(rows[0]!.permanent_code_enc)),
 		agentIds: rows.map(r => String(r.agent_id)),
+		credentialKind: kindOfRow(rows[0]!),
 	};
 }
 
@@ -286,7 +335,7 @@ export async function claimLoginTicket(ticketHash: string, deps: WecomStoreDeps)
 }
 
 /** 运行时依赖：密钥取自部署常量，加密原语取自 oj 运行时全局 */
-export function runtimeStoreDeps(cfg: WecomConfig): WecomStoreDeps {
+export function runtimeStoreDeps(cfg: WecomBase): WecomStoreDeps {
 	return {
 		encrypt: (plain: string) => crypto.aesGcmEncrypt(plain, cfg.encKey),
 		decrypt: (blob: string) => crypto.aesGcmDecrypt(blob, cfg.encKey),

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

@@ -15,6 +15,7 @@
 //     致命类计入熔断（连续 FATAL_LIMIT 次 → job failed）；
 //   · 错误落库只存脱敏结构（`{errcode, phase, deptId, at}`）：异常原文里可能夹带 URL 上的 token。
 import type { WecomClient, WecomMember } from "./client";
+import type { WecomKind } from "./config";
 import type { ProfileProbe } from "./store";
 
 import { markSeen, reconcileHidden, upsertDepartment } from "#/_platform/_shared/service/domain/org";
@@ -75,10 +76,17 @@ export interface SyncJobView {
 export interface SyncView extends SyncJobView {
 	/** 本站是否装过企微（有授权记录，含已停用）——false 时页面整条不显示 */
 	connected: boolean
-	/** 0=管理员授权 / 1=成员授权（1 时任何通讯录调用都是 60011，同步入口直接拒绝） */
+	/** 0=管理员授权 / 1=成员授权（1 时任何通讯录调用都是 60011，同步入口直接拒绝）；自建行恒 0 */
 	authMode: number
 	/** 授权记录的应用状态；disabled = 已取消授权/被停用，同步冻结但数据保留（§7 黄条） */
 	profileStatus: "active" | "disabled" | null
+	/**
+	 * 本次解析到的应用 id：**多应用/共存企业的分辨锚点**。
+	 * 前端 start / cancel / status 必须原样回传，否则同一家企业两行档案时后端只能 400「必须带 agent」。
+	 */
+	agentId: string | null
+	/** 凭据来源：corp 行没有「授权模式」概念，页面不该给它画成员授权卡片 */
+	credentialKind: WecomKind | null
 }
 
 export interface SyncDeps {
@@ -191,6 +199,8 @@ export function attachProfile(view: SyncJobView, probe: ProfileProbe | null): Sy
 		connected: probe !== null,
 		authMode: probe?.authMode ?? 0,
 		profileStatus: probe?.status ?? null,
+		agentId: probe?.agentId ?? null,
+		credentialKind: probe?.credentialKind ?? null,
 	};
 }
 

package/templates/src/auth/api/_shared/wecom/tenant-admin.ts

@@ -0,0 +1,194 @@
+// 租户管理员：给每个企业租户（tenant_id = corp_id）配一个**本租户内**的管理员账号。
+//
+// 为什么必须有这一层：
+//   企业租户是企微登录时才由 `ensureTenant()` 隐式具象化的，里面只有 JIT 建出来的
+//   `wecom:<userid>` 员工号，**一个管理员都没有**——于是没人能进 /system/departments
+//   做组织架构同步、也没人能在该租户内授权。平台 superadmin 虽然在 /system/wecom
+//   上看得到所有企业，但管不了租户内的组织/成员/角色（详见下面「越权」一段）。
+//
+// 为什么是 `admin` 而不是 `superadmin`：
+//   `superadmin` 在本系统是**跨租户**的框架级角色——/system/wecom 每个端点都过
+//   `assertSuperAdmin()`，而它列出的 listApps() 是**所有企业**的档案。只要某租户里
+//   有人握着 superadmin，他带自己租户的头访问该页就能看到别家企业的档案，属跨租户
+//   越权。所以：superadmin = 平台级、只留在 default 租户（运维纪律）；
+//   admin = 租户级、每租户一个（本文件负责开的就是这个）。
+//
+// ─────────────────────────────────────────────────────────────────────────────
+// 【db.asSystem 例外说明 —— 全仓唯一，不得复制】
+//
+// 本文件是全代码库**唯一**使用 `db.asSystem()` 的地方。
+//
+// 为什么必须用它：superadmin 的请求自带 `default` 租户头，而 `db.asTenant` 是
+// 「请求级、只能设一次，且要求当时还没有租户」。也就是说平台侧**没有任何正常通道**
+// 能往企业租户里写 users / sys_user_role。而「给新租户配管理员」是平台开通动作，
+// 不是业务写——正是逃生通道的用途（global.d.ts 原文："use db.asSystem() for system tasks"）。
+//
+// 框架红线：同一段注释紧接着写「业务 handler 不得使用」。所以这里是**有意识且被审计
+// 的单一例外**，代价与边界必须写清楚：
+//   · 范围：只在本文件，只服务「开通 / 重设租户管理员」这一件事；
+//   · 写操作必须显式带上 tenant_id 条件（asSystem 绕过自动注入，漏了就是跨租户脏写）；
+//   · 每个入口都在 admin/api.ts 走 recordOp 留痕（开通 level 2、改密 level 4）；
+//   · **不得在本文件之外任何地方复制 db.asSystem()**。
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** 租户管理员的固定账号名（每租户各一个，互不冲突——users 唯一键含 tenant_id） */
+export const TENANT_ADMIN_USERNAME = "admin";
+/** 授予的角色：租户级日常管理（组织/成员/角色/同步），**不是**跨租户的 superadmin */
+const TENANT_ADMIN_ROLE = "admin";
+
+export interface TenantAdminState {
+	/** 租户（= 企业 ID） */
+	corpId: string
+	/** 管理员账号名 */
+	username: string
+	/** 该租户是否已有一个握着 admin 角色的账号 */
+	exists: boolean
+	/** 是否处于「须改密」状态（开通后恒为 true，直到本人改过一次） */
+	mustChange: boolean
+}
+
+/**
+ * 随机初始口令：**任何人都不知道**（bcrypt 单向，也不落库、不打日志）。
+ *
+ * 这不是缺陷而是设计：开通时不需要有人知道口令；平台侧要接管时走
+ * `setTenantAdminPassword()` **自己设一个已知的**——他输入的那个他本来就知道，
+ * 于是「口令需要被传递」这个问题被消掉了，全系统没有任何口令以可逆形式静态存储。
+ */
+function randomPassword(): string {
+	// randomHex 产出 [0-9a-f]，长度 20 > 口令最小长度 6，且数字字母混合
+	return crypto.randomHex(10);
+}
+
+/** 跨租户读：指定租户下的管理员行（asSystem 例外，见文件头） */
+async function adminRow(tenantId: string): Promise<{ id: number, must_change: number } | null> {
+	const rows = await db.asSystem().table("users")
+		.select(["id", "must_change"])
+		.where({
+			and: [
+				{ field: "tenant_id", op: "eq", value: tenantId },
+				{ field: "username", op: "eq", value: TENANT_ADMIN_USERNAME },
+			],
+		})
+		.all() as Array<{ id: number, must_change: number | null }>;
+	if (!rows.length)
+		return null;
+	return { id: Number(rows[0]!.id), must_change: Number(rows[0]!.must_change ?? 0) };
+}
+
+/** 跨租户读：该用户在本租户是否握着 admin 角色（账号存在 ≠ 有角色，可能被收回过） */
+async function hasAdminRole(tenantId: string, uid: number): Promise<boolean> {
+	const roles = await db.asSystem().table("sys_user_role")
+		.select(["role_name"])
+		.where({
+			and: [
+				{ field: "tenant_id", op: "eq", value: tenantId },
+				{ field: "user_id", op: "eq", value: uid },
+			],
+		})
+		.all() as Array<{ role_name: string }>;
+	return roles.some(r => String(r.role_name) === TENANT_ADMIN_ROLE);
+}
+
+/** 查看某租户的管理员状态（幂等、只读；不存在不建） */
+export async function tenantAdminState(tenantId: string): Promise<TenantAdminState> {
+	const row = await adminRow(tenantId);
+	if (!row)
+		return { corpId: tenantId, username: TENANT_ADMIN_USERNAME, exists: false, mustChange: false };
+	return {
+		corpId: tenantId,
+		username: TENANT_ADMIN_USERNAME,
+		exists: await hasAdminRole(tenantId, row.id),
+		mustChange: row.must_change === 1,
+	};
+}
+
+/**
+ * 开通租户管理员（幂等）：没有就建，有就只确认角色还在。
+ *
+ * 只做两件事：建 `admin` 账号（随机口令 + 强制改密）、授予本租户的 `admin` 角色。
+ * 重复调用安全——这正是「验证并接入可以反复点」的前提。
+ */
+export async function ensureTenantAdmin(tenantId: string): Promise<{ created: boolean }> {
+	let row = await adminRow(tenantId);
+
+	if (!row) {
+		// 与 ensureWecomUser 同形状：只填业务关心的列，其余走列默认值
+		await db.asSystem().table("users").insert({
+			tenant_id: tenantId,
+			username: TENANT_ADMIN_USERNAME,
+			display_name: "租户管理员",
+			password_hash: await bcrypt.hash(randomPassword()),
+			avatar_base64: "",
+			source: "local",
+			must_change: 1,
+			is_forbidden: 0,
+			activated: 1,
+		}).run();
+		// 回查拿 id：预查与插入之间有竞态（并发开通），回查是唯一可靠的取 id 方式
+		row = await adminRow(tenantId);
+	}
+	if (!row)
+		throw Object.assign(new Error("租户管理员建档失败"), { status: 500 });
+
+	if (!await hasAdminRole(tenantId, row.id)) {
+		await db.asSystem().table("sys_user_role").insert({
+			user_id: row.id,
+			role_name: TENANT_ADMIN_ROLE,
+			tenant_id: tenantId,
+		}).run();
+		return { created: true };
+	}
+	return { created: false };
+}
+
+/**
+ * 开通租户管理员（**尽力而为**）：开不通只告警，绝不打断调用方。
+ *
+ * 为什么调用方不能因为它失败：
+ *   · create_auth 有约 1 秒响应窗口（超时企业管理员看到「应用安装失败」），而 bcrypt
+ *     是 CPU 密集操作，不该让它有机会拖垮回调；
+ *   · connectCorp 走到这里时档案**已经落库**，抛错只会让界面显示「接入失败」而实际已接入。
+ *
+ * 补开通道：superadmin 随时可走「重设租户管理员口令」入口，该入口内部会先
+ * `ensureTenantAdmin()`，所以一次开通失败不会留下没有管理员的死租户。
+ */
+export async function provisionTenantAdmin(tenantId: string): Promise<void> {
+	try {
+		const r = await ensureTenantAdmin(tenantId);
+		log.info("wecom tenant admin provisioned", "corpId", tenantId, "created", r.created);
+	}
+	catch (e) {
+		log.warn("wecom tenant admin provision skipped", "corpId", tenantId, "reason", (e as Error).message);
+	}
+}
+
+/**
+ * 重设租户管理员口令（平台 superadmin 专用入口）。
+ *
+ * 口令**不存储**：superadmin 自己输入新口令 → 他知道 → 告知租户管理员。
+ * 落库的只有 bcrypt，且置 must_change=1（首次登录必须改），并级联吊销该用户的
+ * refresh token，避免旧会话继续有效。
+ */
+export async function setTenantAdminPassword(tenantId: string, password: string): Promise<TenantAdminState> {
+	// 先确保账号与角色都在：允许「还没人登录过」的租户被平台直接接管
+	await ensureTenantAdmin(tenantId);
+	const row = await adminRow(tenantId);
+	if (!row)
+		throw Object.assign(new Error("租户管理员建档失败"), { status: 500 });
+
+	await db.asSystem().table("users")
+		.update({ password_hash: await bcrypt.hash(password), must_change: 1 })
+		.where({
+			and: [
+				{ field: "tenant_id", op: "eq", value: tenantId },
+				{ field: "username", op: "eq", value: TENANT_ADMIN_USERNAME },
+			],
+		})
+		.run();
+
+	// 改密后旧会话必须失效。跨租户删 refresh 走带 tenant_id 条件的裸 SQL
+	// （先例见 store.ts::revokeTenantSessions：守卫是 check-on-miss，带了租户条件即放行）
+	await db.exec("DELETE FROM sys_refresh_token WHERE tenant_id = ? AND user_id = ?", [tenantId, row.id]);
+
+	return await tenantAdminState(tenantId);
+}

package/templates/src/auth/api/migrations/0003__credential_kind.mysql.sql

@@ -0,0 +1,3 @@
+-- 应用来源（0003）mysql 方言覆盖（方言覆盖必胜，通用兜底；oj-bin docs/migration.md §3.1）。
+-- 差异：MySQL 的 TEXT 不能带 DEFAULT，故收窄为 VARCHAR(16)。
+ALTER TABLE wecom_app_profile ADD COLUMN credential_kind VARCHAR(16) NOT NULL DEFAULT 'suite';

package/templates/src/auth/api/migrations/0003__credential_kind.pg.sql

@@ -0,0 +1,3 @@
+-- 应用来源（0003）pg 方言覆盖（方言覆盖必胜，通用兜底；oj-bin docs/migration.md §3.1）。
+-- 差异：TEXT 在 pg 合法且可带 DEFAULT，与通用文件同形。
+ALTER TABLE wecom_app_profile ADD COLUMN credential_kind TEXT NOT NULL DEFAULT 'suite';

package/templates/src/auth/api/migrations/0003__credential_kind.sql

@@ -0,0 +1,9 @@
+-- 应用来源（0003）：suite = 代开发（服务商模板授权） / corp = 企业内部应用（自建应用）。
+--
+-- 为什么必须有这一列，而不是靠 `suite_id = ''` 推断：
+--   · 查询要按来源筛（取消代开发授权不能顺手停掉同一家企业自建应用的档案）、后台要按来源展示；
+--   · 空串是「主键里塞了一个隐式语义」，任何一次手写 SQL 漏判都会把两类行混在一起；
+--   · 将来若做「同一企业双应用」，区分只能靠列，不能靠约定。
+--
+-- 现有行全部是代开发授权产生的，故 DEFAULT 'suite' 即正确的历史归属。
+ALTER TABLE wecom_app_profile ADD COLUMN credential_kind TEXT NOT NULL DEFAULT 'suite';

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

@@ -23,6 +23,8 @@ tables:
       status: {type: text, null: false}
       # permanent_code（= 代开发应用的 secret）的 AES-GCM 密文，禁止明文落库
       permanent_code_enc: {type: text, null: false}
+      # 应用来源（0003）：suite=代开发 / corp=企业内部应用（自建）。取消代开发授权只停 suite 行
+      credential_kind: {type: text, null: false}
       # 0=管理员授权 / 1=成员授权（0002）：成员授权下应用无任何部门权限，组织架构同步必然 60011
       auth_mode: {type: integer, null: false}
       installed_at: {type: integer, null: false}