@oj-module/cli 0.2.42 → 0.2.45

package/templates/src/_platform/api/migrations/0015__tenant.sql

@@ -0,0 +1,44 @@
+-- 0015__tenant（sqlite 方言）：多租户地基（企微代开发 v3 Phase 0）
+-- 21 张表定性（判据：该表是否可能在无租户上下文时被访问）——
+--   A 组 租户化 11：users / sys_oplog / sys_user_role / sys_refresh_token
+--                   / notifications / notifications_broadcast
+--                   / notifications_broadcast_read / notifications_broadcast_hidden
+--                   / home_pie / home_line / todos
+--   B 组 共享   10：_oj_migrations / sys_setting / sys_solution_route / sys_role / sys_permission
+--                   / sys_role_permission / sys_rate_window / sys_login_throttle
+--                   / market_history / reg_source_seq
+-- B 组须 schema.yaml `tenant: false` + config `tenant.shared_allow` 双声明才豁免守卫。
+-- 存量数据一律落 'default' 租户，**不做**自动归户（升级后由管理端显式分配）。
+--
+-- users：唯一性从「username 全局唯一」收敛为「(tenant_id, username) 同租户唯一」。
+-- sqlite 无法 ALTER 掉内联 UNIQUE 约束（sqlite_autoindex 不可 DROP）→ 重建表，其余表只加列。
+CREATE TABLE users__tenant_new (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  tenant_id TEXT NOT NULL DEFAULT 'default',
+  corp_id TEXT,
+  username TEXT NOT NULL,
+  password_hash TEXT NOT NULL,
+  avatar_base64 TEXT NOT NULL DEFAULT '',
+  source TEXT NOT NULL DEFAULT 'local',
+  display_name TEXT,
+  must_change INTEGER NOT NULL DEFAULT 0,
+  is_forbidden INTEGER NOT NULL DEFAULT 0,
+  email TEXT,
+  phone_number TEXT,
+  description TEXT,
+  UNIQUE (tenant_id, username)
+);
+INSERT INTO users__tenant_new (
+  id, tenant_id, username, password_hash, avatar_base64, source, display_name,
+  must_change, is_forbidden, email, phone_number, description
+)
+SELECT id, 'default', username, password_hash, avatar_base64, source, display_name,
+       must_change, is_forbidden, email, phone_number, description
+FROM users;
+DROP TABLE users;
+ALTER TABLE users__tenant_new RENAME TO users;
+
+ALTER TABLE sys_oplog ADD COLUMN tenant_id TEXT NOT NULL DEFAULT 'default';
+-- user_id 是全局自增 users.id（跨租户不重复），故主键 (user_id, role_name) 无需扩容
+ALTER TABLE sys_user_role ADD COLUMN tenant_id TEXT NOT NULL DEFAULT 'default';
+ALTER TABLE sys_refresh_token ADD COLUMN tenant_id TEXT NOT NULL DEFAULT 'default';

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

@@ -5,6 +5,8 @@
 # 元数据校验放行（journalHeadOf：深检 ledger 复核 + P3-11 预锁 guard 的真源），列与 oj 真表逐列对齐。
 tables:
   _oj_migrations:
+    # 共享表（B 组）：oj 迁移 journal，跨租户唯一，不可能带租户上下文访问。
+    tenant: false
     pk: [module, version]
     columns:
       module: {type: text, null: false}
@@ -16,6 +18,10 @@ tables:
     pk: id
     columns:
       id: {type: integer, autoincrement: true}
+      # 租户维度（0015）：外部身份按租户隔离，用户名唯一性收敛到 (tenant_id, username)。
+      tenant_id: {type: text, null: false}
+      # 企微业务键（D3/D6）：tenant_id 是隔离判定列，corp_id 只做可读冗余，不参与判定。
+      corp_id: {type: text}
       username: {type: text, null: false}
       password_hash: {type: text, null: false}
       avatar_base64: {type: text, null: false}
@@ -27,6 +33,9 @@ tables:
       phone_number: {type: text}
       description: {type: text}
   sys_setting:
+    # 共享表（B 组 D8）：登录方式发现 /system/login-methods 是未登录端点，此刻没有租户上下文；
+    # 且这些开关是部署级语义，不是每 corp 语义。
+    tenant: false
     pk: key
     columns:
       key: {type: text, null: false}
@@ -45,6 +54,7 @@ tables:
     pk: id
     columns:
       id: {type: integer, autoincrement: true}
+      tenant_id: {type: text, null: false}
       create_time: {type: integer, null: false}
       user_id: {type: integer, null: false}
       username: {type: text, null: false}
@@ -55,6 +65,9 @@ tables:
       detail: {type: text}
       level: {type: integer, null: false}
   sys_solution_route:
+    # 共享表（B 组）：站点级路由/启用注册表（PK=path，安装/卸载/启停为站点操作），
+    # 语义上不存在按 corp 分叉，也不保证在租户上下文里被访问。
+    tenant: false
     # 0010 重构后形状（站点级路由，path 主键；与 migrations/0010__sys_solution_route.sql 逐列一致）。
     pk: path
     columns:
@@ -67,6 +80,8 @@ tables:
       deprecated: {type: integer, null: false}
       enabled: {type: integer, null: false}
   sys_role:
+    # 共享表（B 组）：框架角色目录（内置角色 + 权限码由模块声明同步而来），分配关系在 A 组。
+    tenant: false
     pk: name
     columns:
       name: {type: text, null: false}
@@ -76,6 +91,7 @@ tables:
       builtin: {type: integer, null: false}
       deprecated: {type: integer, null: false}
   sys_permission:
+    tenant: false
     pk: code
     columns:
       code: {type: text, null: false}
@@ -83,6 +99,7 @@ tables:
       title_key: {type: text}
       deprecated: {type: integer, null: false}
   sys_role_permission:
+    tenant: false
     pk: [role_name, permission_code]
     columns:
       role_name: {type: text, null: false}
@@ -90,11 +107,13 @@ tables:
   sys_user_role:
     pk: [user_id, role_name]
     columns:
+      tenant_id: {type: text, null: false}
       user_id: {type: integer, null: false}
       role_name: {type: text, null: false}
   sys_refresh_token:
     pk: token_hash
     columns:
+      tenant_id: {type: text, null: false}
       token_hash: {type: text, null: false}
       user_id: {type: integer, null: false}
       expires_at: {type: integer, null: false}
@@ -103,12 +122,15 @@ tables:
   # 限速/登录节流状态表（V9__sys_throttle 经迁移创建；rate.ts 经 db.table() 访问，
   # 须在此声明 + 在 manifest.yaml tables 登记，否则 oj 表元数据校验报 unknown table）。
   sys_rate_window:
+    # 共享表（B 组）：限速窗口按调用面计数（IP/账号维度），登录前就要用，无租户上下文。
+    tenant: false
     pk: rate_key
     columns:
       rate_key: {type: text, null: false}
       window_start: {type: integer, null: false}
       count: {type: integer, null: false}
   sys_login_throttle:
+    tenant: false
     pk: pair_key
     columns:
       pair_key: {type: text, null: false}
@@ -117,6 +139,9 @@ tables:
   # 市场操作历史（P4 上收 _platform）：install/enable/disable/uninstall/upgrade/rollback 六类动作留痕。
   # 写入由平台编排面（_lifecycle/history.ts recordHistory）落到本表；市场页只读消费。
   market_history:
+    # 共享表（B 组）：解决方案安装/升级/回滚是**站点级**操作（装一次全站生效），
+    # 按租户隔离会把同一批站点事件割裂成互不可见的碎片。
+    tenant: false
     pk: id
     columns:
       id: {type: integer, autoincrement: true}
@@ -130,6 +155,9 @@ tables:
   # REG-CS2 索引新鲜度：站点按源记住见过的最大 seq（防回放/降级，回退即拒）。
   # 读写由 _lifecycle/source-seq.ts 落到本表；source_url 为业务主键（无自增 id）。
   reg_source_seq:
+    # 共享表（B 组）：索引新鲜度水位属于**站点**（受害者是站点，防回放/降级），
+    # 与租户无关；source-seq.ts 的设计注释即写明「记在站点 DB」。
+    tenant: false
     pk: source_url
     columns:
       source_url: {type: text, null: false}

package/templates/src/_platform/api/seed.sql

@@ -28,6 +28,9 @@ INSERT OR IGNORE INTO sys_setting (key, module, "group", type, value, default_va
 INSERT OR IGNORE INTO sys_setting (key, module, "group", type, value, default_value, label_key, secret, update_time) VALUES ('framework.market_cdn_url', 'framework', 'security', 'string', '/cdn', '/cdn', 'system:setting.market_cdn_url', 0, 0);
 INSERT OR IGNORE INTO sys_setting (key, module, "group", type, value, default_value, label_key, secret, update_time) VALUES ('ldap.enabled', 'ldap', 'login', 'bool', '0', '0', 'system:setting.ldap_enabled', 0, 0);
 INSERT OR IGNORE INTO sys_setting (key, module, "group", type, value, default_value, label_key, secret, update_time) VALUES ('sso.enabled', 'sso', 'login', 'bool', '0', '0', 'system:setting.sso_enabled', 0, 0);
+-- 企微代开发（登录方式 + 代开发后台总开关）：默认关。开启前须先在 config.yaml vars 填 6 项部署常量，
+-- 否则登录页会出现企微 tab 但点进去 400「企业微信未配置」（宁可报错也不静默隐藏，便于运维定位）。
+INSERT OR IGNORE INTO sys_setting (key, module, "group", type, value, default_value, label_key, secret, update_time) VALUES ('wecom.enabled', 'wecom', 'login', 'bool', '0', '0', 'system:setting.wecom_enabled', 0, 0);
 INSERT OR IGNORE INTO sys_setting (key, module, "group", type, value, default_value, label_key, secret, update_time) VALUES ('ldap_base_dn', 'ldap', 'ldap', 'string', '', '', 'system:setting.ldap_base_dn', 0, 0);
 INSERT OR IGNORE INTO sys_setting (key, module, "group", type, value, default_value, label_key, secret, update_time) VALUES ('ldap_uid_attr', 'ldap', 'ldap', 'string', 'uid', 'uid', 'system:setting.ldap_uid_attr', 0, 0);
 INSERT OR IGNORE INTO sys_setting (key, module, "group", type, value, default_value, label_key, secret, update_time) VALUES ('ldap_email_attr', 'ldap', 'ldap', 'string', 'mail', 'mail', 'system:setting.ldap_email_attr', 0, 0);

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

@@ -0,0 +1,112 @@
+// 代开发后台（服务商运营面）的领域逻辑：企业应用清单、启停、开通入口。
+//
+// 三个反常识点，都是踩过的坑：
+//   1. **不读部署常量也能停用**：`wecom_base_url` 配错时正是最需要「先把这个企业停掉」的时刻，
+//      所以清单与启停都不依赖 `readWecomConfig`，只有开通入口要（它得调企微换预授权码）。
+//   2. **不能用 `asTenant` 清会话**：管理员请求自带自己的租户头（多半是 `default`），
+//      而 `asTenant` 只能在「请求还没有租户」时调用，否则抛错。故吊销目标企业会话走带
+//      `tenant_id = ?` 的裸 SQL（守卫是 check-on-miss，带了租户条件即放行）。
+//   3. **停用单个应用 ≠ 停用企业**：会话是按租户（= 企业）发的，一个企业可能有测试/正式两个应用。
+//      只有该企业**再没有启用中的应用**时才吊销会话——否则停用测试应用会把正式环境的人踢下线。
+import type { WecomClient } from "./client";
+import type { WecomConfig } from "./config";
+import type { WecomStoreDeps } from "./store";
+import { invalidateAllUsers } from "#/_platform/_shared/service/infra/access";
+import { eventUrlOf, installUrlOf } from "./config";
+import { corpScope, getSuiteTicket, revokeTenantSessions, tenantOfCorp } from "./store";
+
+export interface WecomAdminDeps {
+	client: WecomClient
+	store: WecomStoreDeps
+}
+
+/** 清单行：不含 `permanent_code_enc`（secret 不出库，连超级管理员也不给看） */
+export interface AppRow {
+	suite_id: string
+	corp_id: string
+	agent_id: string
+	auth_corp_id: string
+	env: string
+	corp_name: string | null
+	status: string
+	installed_at: number
+	update_time: number
+}
+
+export async function listApps(): Promise<AppRow[]> {
+	const rows = await db.table("wecom_app_profile")
+		.select(["suite_id", "corp_id", "agent_id", "auth_corp_id", "env", "corp_name", "status", "installed_at", "update_time"])
+		.all() as unknown as AppRow[];
+	// 稳定序：先按企业、再按应用；同企业多环境并排，运维一眼能看出「哪两个是同一家」
+	return rows.sort((a, b) => a.corp_id.localeCompare(b.corp_id) || a.agent_id.localeCompare(b.agent_id));
+}
+
+export interface StatusResult {
+	/** 影响行数（0 = 该企业没开通这个应用） */
+	updated: number
+	/** 本次顺带吊销的 refresh token 数（0 = 还有别的应用在用，或本来就没有会话） */
+	revokedSessions: number
+}
+
+/**
+ * 启用/停用某个企业的某个应用。
+ * 停用语义包含「不再发放新 token 且旧 refresh 失效（当企业整体停用时）」——授权与会话必须同频。
+ */
+export async function setAppStatus(
+	corpId: string,
+	agentId: string,
+	status: "active" | "disabled",
+	deps: WecomAdminDeps,
+): Promise<StatusResult> {
+	const scope = {
+		and: [
+			corpScope(corpId),
+			{ field: "agent_id", op: "eq", value: agentId },
+		],
+	};
+	const updated = Number(await db.table("wecom_app_profile").update({ status, update_time: deps.store.now() }).where(scope).run());
+	if (!updated)
+		throw Object.assign(new Error("该企业未开通此应用（或企业代码/应用 id 不匹配）"), { status: 404 });
+
+	// secret 可能仍在另一状态被缓存：无论启停都先让企业 token 失效，下一次登录重新换
+	await deps.client.invalidateCorpToken(corpId, agentId);
+	if (status === "active")
+		return { updated, revokedSessions: 0 };
+
+	const others = await db.table("wecom_app_profile").select(["agent_id"]).where({
+		and: [
+			corpScope(corpId),
+			{ field: "status", op: "eq", value: "active" },
+		],
+	}).all();
+	if (others.length)
+		return { updated, revokedSessions: 0 };
+
+	const revoked = await revokeTenantSessions(tenantOfCorp(corpId));
+	invalidateAllUsers();
+	return { updated, revokedSessions: revoked };
+}
+
+export interface InstallResult {
+	installUrl: string
+	/** 企微后台「指令回调 URL」应填这个（逐字） */
+	callbackUrl: string
+	expiresIn: number
+}
+
+/** 生成开通入口：suite_access_token → 预授权码 → install URL（企业管理员点开即进入授权安装向导） */
+export async function createInstall(
+	cfg: WecomConfig,
+	client: WecomClient,
+	store: WecomStoreDeps,
+	state: string,
+): Promise<InstallResult> {
+	const ticket = await getSuiteTicket(cfg.suiteId, store);
+	const token = await client.suiteAccessToken(cfg.suiteId, cfg.suiteSecret, ticket.ticket);
+	const pre = await client.preAuthCode(token);
+	return {
+		installUrl: installUrlOf(cfg, pre.code, state),
+		callbackUrl: eventUrlOf(cfg),
+		expiresIn: pre.expiresIn,
+	};
+}

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

@@ -0,0 +1,243 @@
+// 企微 API 客户端（代开发三级凭证链 + 网页授权换 userid）。
+//
+// 凭证链（devkit 未覆盖，见 docs/plans/20261030-1845-wecom-daikaifa-login-plan.md §5.4）：
+//   suite_ticket(企微推) + suite_secret → suite_access_token（套件级，2h）
+//   suite_access_token + auth_code → permanent_code（= 代开发应用的 secret，属于 (suite, corp)）
+//   permanent_code + corpid  → corp access_token（**与自建应用同一个 gettoken 接口**，2h）
+//   corp access_token + code → userid（网页授权 snsapi_base，与自建应用同一个 auth/getuserinfo）
+// 代开发与第三方应用的分叉点只有两处：取永久授权码走 `/service/v2/get_permanent_code`；
+// 企业 token 走 `gettoken` 而不是 `service/get_corp_token`。
+//
+// 缓存：两段 token 都进 kv（oj 有 Redis 就跨进程，没有就进程内），TTL = expires_in-300。
+// 失效：40001/42001 视为 token 失效 → 删缓存重取一次（企微侧提前失效是常态，不重试会把登录打成 502）。
+// 错误两态红线（与 ldap-login 同）：上游网络/协议/企微错误码 → 502（可重试语义）；
+// 用户凭据层面（code 无效/不在可见范围）→ 401（不区分原因，防探测）。
+
+const API_BASE = "https://qyapi.weixin.qq.com";
+const TIMEOUT_MS = 5000;
+const TOKEN_SKEW_SECS = 300;
+
+export interface WecomHttp {
+	getJson: (url: string) => Promise<Record<string, unknown>>
+	postJson: (url: string, body: unknown) => Promise<Record<string, unknown>>
+}
+
+export interface WecomCache {
+	get: (key: string) => Promise<string | null>
+	set: (key: string, value: string, ttlSecs: number) => Promise<unknown>
+	del: (key: string) => Promise<unknown>
+}
+
+export interface WecomClientDeps {
+	http: WecomHttp
+	cache: WecomCache
+}
+
+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) });
+		}
+		catch (e) {
+			throw upstream(`企微接口不可达：${(e as Error).message}`);
+		}
+		if (!res.ok)
+			throw upstream(`企微接口 HTTP ${res.status}`);
+		try {
+			return await res.json() as Record<string, unknown>;
+		}
+		catch {
+			throw upstream("企微接口返回非 JSON");
+		}
+	}
+	return {
+		getJson: url => call(url, { method: "GET" }),
+		postJson: (url, body) => call(url, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body ?? {}) }),
+	};
+}
+
+export function runtimeCache(): WecomCache {
+	return {
+		get: key => kv.get(key),
+		// kv 没有「带 TTL 的写」，只能写值再设过期——两步之间进程退出、或 expire 失败，
+		// 这个键就变成「永不过期」：corp secret 轮换后旧 token 仍被当作新鲜的，
+		// 表现是长时间 502 而日志一片安静。故显式兜底：设不上过期就删键（宁可每请求回源）。
+		set: async (key, value, ttlSecs) => {
+			await kv.set(key, value);
+			if (!(await kv.expire(key, ttlSecs))) {
+				log.warn("wecom token cached without ttl", "key", key);
+				await kv.del(key);
+			}
+		},
+		del: key => kv.del(key),
+	};
+}
+
+function upstream(message: string): Error {
+	return Object.assign(new Error(message), { status: 502 });
+}
+
+/** code 无效 / 不在应用可见范围 / 非企业成员：统一 401（不泄露具体原因，§5.3 枚举风险） */
+function rejectCode(): never {
+	throw Object.assign(new Error("登录凭据无效或不在应用可见范围内"), { status: 401 });
+}
+
+/** 企微错误码 → 异常。`errcode` 缺失视为成功（get_permanent_code 的历史行为）。 */
+function assertOk(res: Record<string, unknown>, what: string): void {
+	const code = res.errcode;
+	if (code == null || Number(code) === 0)
+		return;
+	throw upstream(`企微 ${what} 失败：errcode=${String(code)} ${String(res.errmsg ?? "")}`.trimEnd());
+}
+
+const TOKEN_EXPIRED = new Set([40001, 40014, 42001]);
+
+export function createWecomClient(deps: WecomClientDeps) {
+	const { http, cache } = deps;
+
+	async function cachedToken(key: string, load: () => Promise<{ token: string, expiresIn: number }>): Promise<string> {
+		const hit = await cache.get(key);
+		if (hit)
+			return hit;
+		const { token, expiresIn } = await load();
+		const ttl = Math.max(60, Math.floor(expiresIn) - TOKEN_SKEW_SECS);
+		await cache.set(key, token, ttl);
+		return token;
+	}
+
+	/** 套件 access_token：需要 suite_ticket（过期/缺失由调用方先拦） */
+	async function suiteAccessToken(suiteId: string, suiteSecret: string, suiteTicket: string): Promise<string> {
+		return cachedToken(`wecom:suite_token:${suiteId}`, async () => {
+			const res = await http.postJson(`${API_BASE}/cgi-bin/service/get_suite_token`, {
+				suite_id: suiteId,
+				suite_secret: suiteSecret,
+				suite_ticket: suiteTicket,
+			});
+			assertOk(res, "get_suite_token");
+			if (!res.suite_access_token)
+				throw upstream("企微 get_suite_token 未返回 suite_access_token");
+			return { token: String(res.suite_access_token), expiresIn: Number(res.expires_in ?? 7200) };
+		});
+	}
+
+	/**
+	 * auth_code → permanent_code（+ 企业信息 + 应用列表）。
+	 * 代开发用 `/service/v2/get_permanent_code`：返回 is_customized_app=true，且**不返回 access_token**。
+	 * auth_code 一次有效（10 分钟内），重放只会拿到企微错误码 → 502，由调用方丢弃本条事件。
+	 */
+	async function permanentCodeByAuthCode(suiteAccessToken: string, authCode: string): Promise<{
+		permanentCode: string
+		corpId: string
+		corpName: string | null
+		agentIds: string[]
+		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");
+		if (agentIds.length === 0)
+			throw upstream("企微 get_permanent_code 未返回授权应用（auth_info.agent 为空）");
+		return {
+			permanentCode: String(res.permanent_code),
+			corpId: String(authCorp.corpid),
+			corpName: authCorp.corp_name == null ? null : String(authCorp.corp_name),
+			agentIds,
+			state: res.state == null ? null : String(res.state),
+		};
+	}
+
+	/**
+	 * 预授权码（开通入口用）：套件级、10 分钟、一次有效，拼进 install URL 交给企业管理员点开。
+	 * 与 permanent_code 无关——它只换「安装向导里那一屏同意」，真正的永久码仍由 create_auth 回调给。
+	 */
+	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) };
+	}
+
+	/** 企业 access_token（代开发 = 自建应用的 gettoken，corpsecret 就是 permanent_code） */
+	async function corpAccessToken(corpId: string, agentId: string, secret: string): Promise<string> {
+		return cachedToken(`wecom:corp_token:${corpId}:${agentId}`, async () => {
+			const res = await http.getJson(`${API_BASE}/cgi-bin/gettoken?corpid=${encodeURIComponent(corpId)}&corpsecret=${encodeURIComponent(secret)}`);
+			assertOk(res, "gettoken");
+			if (!res.access_token)
+				throw upstream("企微 gettoken 未返回 access_token");
+			return { token: String(res.access_token), expiresIn: Number(res.expires_in ?? 7200) };
+		});
+	}
+
+	async function invalidateCorpToken(corpId: string, agentId: string): Promise<void> {
+		await cache.del(`wecom:corp_token:${corpId}:${agentId}`);
+	}
+
+	/**
+	 * 成员姓名（best-effort）：只用于把 JIT 号的 `display_name` 从工号变成真名。
+	 *
+	 * 三类失败一律返回 null，绝不抛出：套件没有通讯录读权限（60011/48002）、成员不在可见范围、
+	 * 上游抖动。补名是体验优化，不能因为拿不到名字把登录打成 5xx——
+	 * 调用方拿到 null 就用工号兜底。
+	 * 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;
+	}
+
+	/** 网页授权 code → userid（snsapi_base；非企业成员/超出可见范围 → 401） */
+	async function userIdByCode(corpId: string, agentId: string, secret: string, code: string): Promise<string> {
+		for (let attempt = 0; attempt < 2; attempt++) {
+			const token = await corpAccessToken(corpId, agentId, secret);
+			const res = await http.getJson(`${API_BASE}/cgi-bin/auth/getuserinfo?access_token=${encodeURIComponent(token)}&code=${encodeURIComponent(code)}`);
+			const errcode = Number(res.errcode ?? 0);
+			if (TOKEN_EXPIRED.has(errcode) && attempt === 0) {
+				await invalidateCorpToken(corpId, agentId);
+				continue;
+			}
+			if (errcode !== 0)
+				rejectCode();
+			const userid = res.userid == null ? "" : String(res.userid);
+			if (!userid)
+				rejectCode(); // 非企业成员（外部联系人）时企微只给 openid，不认作本应用用户
+			return userid;
+		}
+		throw upstream("企微 token 反复失效（40001/42001）");
+	}
+
+	return { suiteAccessToken, permanentCodeByAuthCode, preAuthCode, corpAccessToken, invalidateCorpToken, userIdByCode, userNameById };
+}
+
+export type WecomClient = ReturnType<typeof createWecomClient>;

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

@@ -0,0 +1,133 @@
+// 企微代开发「服务商侧」部署常量（config `vars:` 段，不进 DB、不进 sys_setting）。
+//
+// 多租户动态性边界：**套件（suite）是部署级的**——一个部署 = 一个服务商账号下的一套代开发模板
+// （suite_id/suite_secret/callback token/EncodingAESKey 全在这套模板的后台里）。
+// 「哪个企业装了哪个应用」不写配置：企微 create_auth 回调推 AuthCode → 换 permanent_code →
+// 落 wecom_app_profile，新增企业只需企业管理员扫码授权，**不改配置、不重启**。
+// 同一企业两个应用（测试/正式）也无需改配置：profile 主键含 agent_id（D5）。
+//
+// 与 ldap 同口径：启用开关走 sys_setting（`wecom.enabled`），凭据走部署常量。
+
+import { b64ToBytes } from "./crypt";
+
+export interface WecomConfig {
+	/** 代开发应用模版 id（企微侧即 suite_id），也是回调明文里的 receiveid */
+	suiteId: string
+	suiteSecret: string
+	/** 回调签名 token（企微后台「Token」） */
+	token: string
+	/** 回调加密密钥（43 字符 EncodingAESKey） */
+	encodingAesKey: string
+	/** AES-GCM 落库密钥（hex/base64，16 或 32 字节）：加密 permanent_code/secret */
+	encKey: string
+	/**
+	 * 连接器基址（绝对地址，无尾斜杠），如 `https://site.example.com/api/auth/wecom`。
+	 * 两个派生地址都由它拼出，避免「同一件事配两处、改一处漏一处」：
+	 *   · 指令回调 URL = `<base>/event` → **原样填进企微后台**（须逐字一致，含协议与路径）
+	 *   · 网页授权 redirect_uri = `<base>/callback`
+	 */
+	baseUrl: string
+}
+
+const REQUIRED: Array<[keyof WecomConfig, string]> = [
+	["suiteId", "wecom_suite_id"],
+	["suiteSecret", "wecom_suite_secret"],
+	["token", "wecom_callback_token"],
+	["encodingAesKey", "wecom_encoding_aes_key"],
+	["encKey", "wecom_enc_key"],
+	["baseUrl", "wecom_base_url"],
+];
+
+/**
+ * 落库密钥格式校验（fail-fast 在**读配置**处，而不是等 create_auth 时在 crypto 里炸）：
+ * oj 的 aesGcmEncrypt 只收「16 或 32 字节的 hex/base64」，AES-192（24 字节）明确不支持。
+ * 最常见的配置事故是把 32 个「随意字符」当密钥——它按 base64 解出 24 字节，加密时才报错，
+ * 而那时已经是企业授权回调，排查成本最高。
+ */
+export function assertEncKey(encKey: string): void {
+	const hex = /^[0-9a-f]+$/i.test(encKey) && [32, 64].includes(encKey.length);
+	let ok = hex;
+	if (!ok) {
+		try {
+			ok = [16, 32].includes(b64ToBytes(encKey).length);
+		}
+		catch {
+			ok = false;
+		}
+	}
+	if (!ok)
+		throw Object.assign(new Error("企业微信配置错误：wecom_enc_key 必须是 16 或 32 字节的 hex（32/64 字符）或 base64"), { status: 400 });
+}
+
+/**
+ * 读部署常量。缺任一必需项即 400（「未配置」是运维事实，不是服务端缺陷）：
+ * 前半段（suite 凭据）缺失 → 企微登录整体不可用；encKey 缺失则 permanent_code 无法安全落库，
+ * 宁可拒服务，也不退化成明文存储（§7.5 数据合规红线）。
+ */
+export function readWecomConfig(): WecomConfig {
+	const cfg: WecomConfig = {
+		suiteId: vars.get("wecom_suite_id") ?? "",
+		suiteSecret: vars.get("wecom_suite_secret") ?? "",
+		token: vars.get("wecom_callback_token") ?? "",
+		encodingAesKey: vars.get("wecom_encoding_aes_key") ?? "",
+		encKey: vars.get("wecom_enc_key") ?? "",
+		baseUrl: (vars.get("wecom_base_url") ?? "").replace(/\/+$/, ""),
+	};
+	const missing = REQUIRED.filter(([field]) => !cfg[field]).map(([, name]) => name);
+	if (missing.length)
+		throw Object.assign(new Error(`企业微信未配置：config vars 缺少 ${missing.join(" / ")}`), { status: 400 });
+	if (!/^https?:\/\//.test(cfg.baseUrl))
+		throw Object.assign(new Error("企业微信配置错误：wecom_base_url 必须是绝对地址（企微回调与 redirect_uri 都要求）"), { status: 400 });
+	assertEncKey(cfg.encKey);
+	return cfg;
+}
+
+/** 企微后台「指令回调 URL」：原样填这个（base + /event） */
+export function eventUrlOf(cfg: WecomConfig): string {
+	return `${cfg.baseUrl}/event`;
+}
+
+/** 网页授权 redirect_uri（base + /callback） */
+export function loginRedirectOf(cfg: WecomConfig): string {
+	return `${cfg.baseUrl}/callback`;
+}
+
+/** 连接器在站点里的固定挂载后缀（模块 apiPrefix `/auth` + 平台 API 前缀 `/api`）：`siteRootOf` 靠它剥离 */
+const CONNECTOR_SUFFIX = "/api/auth/wecom";
+
+/**
+ * 站点根（origin + 子路径前缀，无尾斜杠）：302 回跳落到 SPA 时用。
+ *
+ * 不能只取 origin：子路径部署（oj `mounts: [{ prefix: /oj }]`）时 SPA 的登录页在 `/oj/login`，
+ * 回跳到 `/login` 会打到宿主机根的别的应用（或 404）。前缀不另配一个变量——它就等于
+ * `wecom_base_url` 去掉本连接器的固定后缀，配一处即可，且不匹配时**报错**而不是猜。
+ */
+export function siteRootOf(cfg: WecomConfig): string {
+	const url = new URL(cfg.baseUrl);
+	const path = url.pathname.replace(/\/+$/, "");
+	if (!path.endsWith(CONNECTOR_SUFFIX))
+		throw Object.assign(new Error(`企业微信配置错误：wecom_base_url 必须以 ${CONNECTOR_SUFFIX} 结尾（如 https://site.example.com/oj${CONNECTOR_SUFFIX}）`), { status: 400 });
+	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 }>;
+	return rows[0]?.value === "1";
+}