@oj-module/cli 0.2.43 → 0.2.46

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

@@ -0,0 +1,246 @@
+import type { WecomConfig } from "../_shared/wecom/config";
+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 / 授权 / 解绑）
+//
+// 三处纪律：
+//   1. 两个 302 端点**不能**用 respond（它末尾无脑 json.ok，会把 302 覆盖成 200 信封）——
+//      异常统一交 failWith（respond.ts 同一个信封收口）。
+//   2. 企微事件端点必须回**纯文本** `success` / 解出的 `echostr`（信封会被企微判成失败并重推三次），
+//      故走 json.stream 的 text/plain 通道（json.raw 是 JSON 通道，会把 echostr 加引号）。
+//   3. 这四个端点都在 `auth.anonymous_paths`（无 Bearer）与 `tenant.anonymous_paths`（浏览器带不了
+//      `X-TENANT-ID`）里：租户只能由服务端从 profile / 票据推导（db.asTenant，见 store.ts::ensureTenant）。
+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 { unwrapWecomMessage, wecomSignature } from "../_shared/wecom/crypt";
+import { handleSuiteEvent } from "../_shared/wecom/events";
+import {
+	assertUserActive,
+	buildAuthorizeUrl,
+	ensureWecomUser,
+	LOGIN_TICKET_TTL_SECS,
+	loginLandingUrl,
+	putLoginState,
+	takeLoginState,
+} from "../_shared/wecom/login";
+import { guardReplay, runtimeReplayGate } from "../_shared/wecom/replay";
+import { claimLoginTicket, ensureTenant, findProfile, issueLoginTicket, runtimeStoreDeps, tenantOfCorp } from "../_shared/wecom/store";
+import { xmlField } from "../_shared/wecom/xml";
+
+// 模块级禁止 readWecomConfig()/createSession()/runtimeHttp()：oj build 的 introspect 在空沙箱里
+// 评估模块（无 vars/jwt/fetch），一律在 handler 内按需构造（§9.4）。
+
+/** 请求头的读取按大小写不敏感处理（http.headers 的键大小写随客户端） */
+function header(name: string): string {
+	const all = (http.headers ?? {}) as Record<string, string>;
+	const key = Object.keys(all).find(k => k.toLowerCase() === name);
+	return key ? String(all[key] ?? "") : "";
+}
+
+function query(name: string): string {
+	return String(((http.query ?? {}) as Record<string, unknown>)[name] ?? "").trim();
+}
+
+/** 纯文本 200（企微事件回执专用；信封会被判失败并触发重推） */
+function plainText(body: string): void {
+	const stream = json.stream({ contentType: "text/plain; charset=utf-8" });
+	stream.write(body);
+	stream.end();
+}
+
+function badRequest(message: string): Error {
+	return Object.assign(new Error(message), { status: 400 });
+}
+
+/**
+ * 校验企微回调签名并解出明文。签名不合法 → 400（不是 401：调用方是企微服务器，
+ * 401 会被当成「本站需要鉴权」误导排查）；信封里的原文不回显，避免给探测者提供比对材料。
+ *
+ * 三道顺序不可换：先验签（不给未鉴权请求写 kv）→ 再拦重放（省一次解密，也让
+ * cancel_auth 这种危险性最高的报文止步在落库之前）→ 最后解密。
+ */
+async function decryptVerified(encrypted: string): Promise<{ cfg: WecomConfig, plain: string }> {
+	const cfg = readWecomConfig();
+	const expected = wecomSignature(cfg.token, query("timestamp"), query("nonce"), encrypted);
+	if (expected !== query("msg_signature"))
+		throw badRequest("回调签名校验失败");
+	await guardReplay(query("timestamp"), query("nonce"), runtimeReplayGate());
+	try {
+		return { cfg, plain: unwrapWecomMessage(encrypted, cfg.encodingAesKey, cfg.suiteId) };
+	}
+	catch (e) {
+		// 解密失败只透出「失败」：错钥/错套件/被篡改三者不可区分，也不该让外部据此判断哪一环配错
+		log.warn("wecom callback decrypt failed", "reason", (e as Error).message);
+		throw badRequest("回调消息解密失败");
+	}
+}
+
+const login = {
+	// 企微内打开（UA 含 wxwork）→ oauth2 静默授权；普通浏览器 → qrConnect 扫码。
+	// corp 必填（D10：企业代码 = corp_id，服务商后台可生成带码的专属登录链接）。
+	async get() {
+		try {
+			const cfg = readWecomConfig();
+			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;
+			});
+
+			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),
+				state,
+				inWecom: /wxwork/i.test(header("user-agent")),
+			});
+			json.redirect.found(url);
+		}
+		catch (e) {
+			failWith(e); // 302 不在错误通道里：异常同样走统一信封，不能让浏览器看到裸 500
+		}
+	},
+};
+
+const callback = {
+	// 企微回跳：state 一次性（kv 取即删）→ profile → 绑租户 → code 换 userid → JIT 建档 → 发票 → 302。
+	async get() {
+		try {
+			const cfg = readWecomConfig();
+			const code = query("code");
+			const state = query("state");
+			// 用户在企业微信里点了「拒绝」时企微不回 code，只回 state
+			if (!code)
+				throw badRequest("授权未完成：企业微信未返回 code（可能已在授权页取消）");
+			if (!state)
+				throw badRequest("登录状态缺失：请从企业微信重新进入");
+
+			const deps = runtimeStoreDeps(cfg);
+			const pending = await takeLoginState(state, runtimeCache());
+			const profile = await findProfile(pending.corpId, pending.agentId, deps);
+			// 顺序刚性：先绑租户再碰 users（JIT 建号是租户表写入，守卫 deny 下缺上下文即拒）
+			ensureTenant(tenantOfCorp(profile.corpId));
+
+			const client = createWecomClient({ http: runtimeHttp(), cache: runtimeCache() });
+			const userid = await client.userIdByCode(profile.corpId, profile.agentId, profile.permanentCode, code);
+			// 名字是惰性取的：只有首次建档才多打一次 user/get（老用户零开销），拿不到就用工号兜底
+			const { uid, forbidden } = await ensureWecomUser(profile.corpId, userid, () =>
+				client.userNameById(profile.corpId, profile.agentId, profile.permanentCode, userid));
+			if (forbidden)
+				throw Object.assign(new Error("账号已被停用，请联系管理员"), { status: 403 });
+
+			// 票据而不是 token 进 URL：token 会留在浏览器历史/Referer/反代日志里
+			const ticket = crypto.randomHex(32);
+			const tenant = tenantOfCorp(profile.corpId);
+			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 }));
+		}
+		catch (e) {
+			failWith(e);
+		}
+	},
+};
+
+const ticket = {
+	// 一次性票据换会话。票据即凭证：先抢所有权（原子 used 0→1）再校验过期，重放与并发双花都只会成功一次。
+	async post() {
+		await respond(async () => {
+			const raw = String((http.body as { ticket?: string } | null)?.ticket ?? "");
+			if (!raw)
+				throw badRequest("缺少 ticket");
+			// 换票只碰 DB 与会话：**不读部署凭据**——加解密在这条路径上用不到，而套件凭据没配好
+			// 时把「已签发的票」判成登录失败，等于把配置事故伪装成票据失效（admin 的 status 同处理）。
+			const storeDeps: WecomStoreDeps = { encrypt: () => "", decrypt: () => "", now: () => Math.floor(Date.now() / 1000) };
+			const claimed = await claimLoginTicket(crypto.sha256Hex(raw), storeDeps);
+			// 票据里的租户是权威：前端落地页必须先 bootstrapTenant（`?tenant=` 由 callback 的 302 带上），
+			// 否则这里拿到的是默认租户头，ensureTenant 会以 403 明确拒绝（而不是悄悄落到 default）
+			ensureTenant(claimed.ownerTenant);
+			await assertUserActive(claimed.uid);
+			return createSession().issueExternal(claimed.uid);
+		});
+	},
+};
+ticket.post.schema = {
+	body: {
+		type: "object",
+		required: ["ticket"],
+		properties: {
+			ticket: { type: "string", minLength: 32, maxLength: 128 },
+		},
+	},
+};
+
+const event = {
+	// 企微后台「保存回调 URL」时会 GET 一次：解出 echostr 后**原样明文回**（不套信封、不加引号）。
+	//
+	// 只依赖 Tier A 凭据（readCallbackConfig）：token/aeskey/baseUrl/encKey 全部部署方本地生成，
+	// 不需要 suite_id——因此「配齐四项正确即可响应验证」，**不必等代开发模版创建、拿到 suite_id 之后**。
+	// 这正是打破鸡生蛋死锁（plan §18）的落点：先有可验证的回调，才能创建模版、拿到 suite 凭据。
+	//
+	// suite_id 在「模版创建成功」后才下发；URL 验证可能发生在拿到 suite_id 之前（创建表单内联校验），
+	// 此时 receiveid 无从比对 → 走 tolerant（签名已是最外层鉴权闸门，receiveid 仅为防御性兜底）。
+	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"))
+				throw badRequest("回调签名校验失败");
+			await guardReplay(query("timestamp"), query("nonce"), runtimeReplayGate());
+			const suiteId = (vars.get("wecom_suite_id") ?? "").trim();
+			try {
+				plainText(unwrapWecomMessage(encrypted, cfg.encodingAesKey, suiteId, !suiteId));
+			}
+			catch (e) {
+				// 解密失败只透出「失败」：错钥/未下发套件/被篡改三者不可区分，也不该让外部据此判断哪一环配错
+				log.warn("wecom callback decrypt failed", "reason", (e as Error).message);
+				throw badRequest("回调消息解密失败");
+			}
+		}
+		catch (e) {
+			failWith(e);
+		}
+	},
+
+	// 指令回调：验签 → 解密 → 分发（suite_ticket / create_auth / change_auth / cancel_auth /
+	// reset_permanent_code）。回 `success` 才算收下，否则企微 5 秒后重推三次。
+	async post() {
+		try {
+			const xml = typeof http.body === "string" ? http.body : "";
+			const encrypted = xmlField(xml, "Encrypt");
+			if (!encrypted)
+				throw badRequest("回调报文缺少 Encrypt");
+			const { cfg, plain } = await decryptVerified(encrypted);
+			const client = createWecomClient({ http: runtimeHttp(), cache: runtimeCache() });
+			await handleSuiteEvent(plain, { cfg, client, store: runtimeStoreDeps(cfg) });
+			plainText("success");
+		}
+		catch (e) {
+			// 失败必须让企微看到非 success：它重推三次，正好覆盖「suite_ticket 未到/上游抖」这类瞬态
+			failWith(e);
+		}
+	},
+};
+
+export default { login, callback, ticket, event };

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

@@ -8,6 +8,42 @@ export const schemas = {
 		body: z.object({
 	"old_password": z.string().min(1),
 	"new_password": z.string().min(6)
+}),
+	},
+	"authWecomAdminAppsGet": {
+		data: z.array(z.object({
+	"suite_id": z.string(),
+	"corp_id": z.string(),
+	"agent_id": z.string(),
+	"auth_corp_id": z.string(),
+	"env": z.string(),
+	"corp_name": z.string().nullable().optional(),
+	"status": z.enum(["active", "disabled"]),
+	"installed_at": z.number(),
+	"update_time": z.number()
+})),
+	},
+	"authWecomAdminStatusPost": {
+		body: z.object({
+	"corpId": z.string().min(1),
+	"agentId": z.string().min(1),
+	"status": z.enum(["active", "disabled"])
+}),
+		data: z.object({
+	"updated": z.number(),
+	"revokedSessions": z.number()
+}),
+	},
+	"authWecomAdminInstallGet": {
+		data: z.object({
+	"installUrl": z.string(),
+	"callbackUrl": z.string(),
+	"expiresIn": z.number()
+}),
+	},
+	"authWecomTicketPost": {
+		body: z.object({
+	"ticket": z.string().min(32).max(128)
 }),
 	},
 };

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 };
+	return { authLoginPost, authLogoutPost, authRefreshPost, authPasswordPut, authLdapLoginPost, authWecomAdminAppsGet, authWecomAdminStatusPost, authWecomAdminInstallGet, authWecomLoginGet, authWecomCallbackGet, authWecomTicketPost, authWecomEventGet, authWecomEventPost };
 }
 
 /**
@@ -140,3 +140,150 @@ export async function authLdapLoginPost(): Promise<unknown> {
 		throw await toApiError(e);
 	}
 }
+
+export type AuthWecomAdminAppsGetData = z.infer<(typeof schemas)["authWecomAdminAppsGet"]["data"]>;
+
+export async function authWecomAdminAppsGet(): Promise<AuthWecomAdminAppsGetData> {
+	const client = ensureReq();
+	try {
+		const env = await client.get(`auth/wecom/admin/apps`).json<OjEnvelope<AuthWecomAdminAppsGetData>>();
+		// 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 AuthWecomAdminAppsGetData;
+		if (import.meta.env.DEV) {
+			const { schemas } = await import("./api.schemas");
+			const r = schemas["authWecomAdminAppsGet"].data.safeParse(data);
+			if (!r.success)
+				throw new ContractApiError(-1, `[契约违例] authWecomAdminAppsGet 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+		}
+		return data;
+	}
+	catch (e) {
+		throw await toApiError(e);
+	}
+}
+
+export type AuthWecomAdminStatusPostBody = z.input<(typeof schemas)["authWecomAdminStatusPost"]["body"]>;
+export type AuthWecomAdminStatusPostData = z.infer<(typeof schemas)["authWecomAdminStatusPost"]["data"]>;
+
+export async function authWecomAdminStatusPost(body: AuthWecomAdminStatusPostBody): Promise<AuthWecomAdminStatusPostData> {
+	const client = ensureReq();
+	try {
+		const env = await client.post(`auth/wecom/admin/status`, { json: body }).json<OjEnvelope<AuthWecomAdminStatusPostData>>();
+		// 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 AuthWecomAdminStatusPostData;
+		if (import.meta.env.DEV) {
+			const { schemas } = await import("./api.schemas");
+			const r = schemas["authWecomAdminStatusPost"].data.safeParse(data);
+			if (!r.success)
+				throw new ContractApiError(-1, `[契约违例] authWecomAdminStatusPost 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+		}
+		return data;
+	}
+	catch (e) {
+		throw await toApiError(e);
+	}
+}
+
+export type AuthWecomAdminInstallGetData = z.infer<(typeof schemas)["authWecomAdminInstallGet"]["data"]>;
+
+export async function authWecomAdminInstallGet(): Promise<AuthWecomAdminInstallGetData> {
+	const client = ensureReq();
+	try {
+		const env = await client.get(`auth/wecom/admin/install`).json<OjEnvelope<AuthWecomAdminInstallGetData>>();
+		// 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 AuthWecomAdminInstallGetData;
+		if (import.meta.env.DEV) {
+			const { schemas } = await import("./api.schemas");
+			const r = schemas["authWecomAdminInstallGet"].data.safeParse(data);
+			if (!r.success)
+				throw new ContractApiError(-1, `[契约违例] authWecomAdminInstallGet 响应与契约不符：${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 {
+		const env = await client.get(`auth/wecom/login`).json<OjEnvelope<unknown>>();
+		// 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 unknown;
+		return data;
+	}
+	catch (e) {
+		throw await toApiError(e);
+	}
+}
+
+export async function authWecomCallbackGet(): Promise<unknown> {
+	const client = ensureReq();
+	try {
+		const env = await client.get(`auth/wecom/callback`).json<OjEnvelope<unknown>>();
+		// 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 unknown;
+		return data;
+	}
+	catch (e) {
+		throw await toApiError(e);
+	}
+}
+
+export type AuthWecomTicketPostBody = z.input<(typeof schemas)["authWecomTicketPost"]["body"]>;
+
+export async function authWecomTicketPost(body: AuthWecomTicketPostBody): Promise<unknown> {
+	const client = ensureReq();
+	try {
+		const env = await client.post(`auth/wecom/ticket`, { json: body }).json<OjEnvelope<unknown>>();
+		// 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 unknown;
+		return data;
+	}
+	catch (e) {
+		throw await toApiError(e);
+	}
+}
+
+export async function authWecomEventGet(): Promise<unknown> {
+	const client = ensureReq();
+	try {
+		const env = await client.get(`auth/wecom/event`).json<OjEnvelope<unknown>>();
+		// 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 unknown;
+		return data;
+	}
+	catch (e) {
+		throw await toApiError(e);
+	}
+}
+
+export async function authWecomEventPost(): Promise<unknown> {
+	const client = ensureReq();
+	try {
+		const env = await client.post(`auth/wecom/event`).json<OjEnvelope<unknown>>();
+		// 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 unknown;
+		return data;
+	}
+	catch (e) {
+		throw await toApiError(e);
+	}
+}

package/templates/src/demo/api/migrations/0002__tenant.mysql.sql

@@ -0,0 +1,2 @@
+-- 0002__tenant（mysql 方言）：demo.todos 租户化。TEXT 不能带字面默认值 → VARCHAR(255)。
+ALTER TABLE todos ADD COLUMN tenant_id VARCHAR(255) NOT NULL DEFAULT 'default';

package/templates/src/demo/api/migrations/0002__tenant.sql

@@ -0,0 +1,2 @@
+-- 0002__tenant：demo.todos 租户化（企微代开发 v3 Phase 0 的 A 组）。
+ALTER TABLE todos ADD COLUMN tenant_id TEXT NOT NULL DEFAULT 'default';

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

@@ -5,6 +5,7 @@ tables:
     pk: id
     columns:
       id: {type: integer, autoincrement: true}
+      tenant_id: {type: text, null: false}
       title: {type: text, null: false}
       done: {type: integer, null: false}
       create_time: {type: integer, null: false}

package/templates/src/home/api/migrations/0002__tenant.mysql.sql

@@ -0,0 +1,3 @@
+-- 0002__tenant（mysql 方言）：首页图表两表租户化。TEXT 不能带字面默认值 → VARCHAR(255)。
+ALTER TABLE home_pie ADD COLUMN tenant_id VARCHAR(255) NOT NULL DEFAULT 'default';
+ALTER TABLE home_line ADD COLUMN tenant_id VARCHAR(255) NOT NULL DEFAULT 'default';

package/templates/src/home/api/migrations/0002__tenant.sql

@@ -0,0 +1,3 @@
+-- 0002__tenant：首页图表两表租户化（企微代开发 v3 Phase 0 的 A 组）。
+ALTER TABLE home_pie ADD COLUMN tenant_id TEXT NOT NULL DEFAULT 'default';
+ALTER TABLE home_line ADD COLUMN tenant_id TEXT NOT NULL DEFAULT 'default';

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

@@ -4,11 +4,13 @@ tables:
     pk: id
     columns:
       id: {type: integer, autoincrement: true}
+      tenant_id: {type: text, null: false}
       category: {type: text, null: false}
       value: {type: integer, null: false}
   home_line:
     pk: id
     columns:
       id: {type: integer, autoincrement: true}
+      tenant_id: {type: text, null: false}
       day: {type: integer, null: false}
       value: {type: integer, null: false}

package/templates/src/login/web/auth-provider.ts

@@ -0,0 +1,48 @@
+import type { AuthProvider, AuthType } from "@oj-module/runtime";
+
+import { fetchLogin, fetchLogout, fetchUserInfo, request, useAuthStore } from "@oj-module/runtime";
+
+/**
+ * 登录模块的认证 provider（P5 接缝）。
+ *
+ * 为什么必须注册：`useAuthStore.login()` 只认两条路——provider 或内置 `auth/login`。
+ * 企微登录拿到的是**票据**而不是口令，走不了内置路；而 store 的写入（token 持久化、
+ * 之后 guard 拉用户信息）必须只有一个入口，所以由本 provider 接管并把其余方式
+ * **原样委托**回内置实现（`fetchLogin/fetchLogout/fetchUserInfo`，行为零变化）。
+ *
+ * 契约（见 runtime `store/auth-provider.ts`）：provider 对返回值自负责，失败请直接
+ * reject——runtime 原样透传，错误提示归登录页。
+ */
+export const authProvider: AuthProvider = {
+	async login(payload): Promise<AuthType> {
+		if (payload.method !== "wecom")
+			return fetchLogin(payload);
+
+		const ticket = payload.ticket?.trim() ?? "";
+		if (!ticket)
+			throw new Error("缺少企业微信登录票据，请从企业微信重新进入");
+
+		// 服务端只认 `{ ticket }`（schema 校验 minLength 32）：它由 302 落地点带过来，
+		// 只在内存里存在一瞬间，不落 localStorage。
+		//
+		// throwHttpErrors:false —— ky 默认把非 2xx 抛成 HTTPError，message 是
+		// "Request failed with status code 401"，登录页只能原样贴给用户看。
+		// 这里自己读信封，把后端 `fail(401, "登录票据无效或已使用")` 的 msg 透上去。
+		const res = await request.post("auth/wecom/ticket", { json: { ticket }, throwHttpErrors: false });
+		const env = await res
+			.json<{ code: number, msg?: string, data?: { access_token?: string, refresh_token?: string } }>()
+			.catch(() => undefined);
+		if (!res.ok)
+			throw new Error(env?.msg || `企业微信登录失败（HTTP ${res.status}）`);
+		return {
+			token: env?.data?.access_token ?? "",
+			refreshToken: env?.data?.refresh_token ?? "",
+		};
+	},
+
+	async logout(): Promise<void> {
+		await fetchLogout({ refreshToken: useAuthStore.getState().refreshToken });
+	},
+
+	getUserInfo: () => fetchUserInfo(),
+};

package/templates/src/login/web/entry.ts

@@ -1,5 +1,6 @@
-import { defineModule } from "@oj-module/runtime";
+import { defineModule, useAuthStore, useTenantStore } from "@oj-module/runtime";
 import { lazy } from "react";
+import { authProvider } from "./auth-provider";
 
 /**
  * 登录模块：提供 `/login` 路由与内容区。
@@ -56,4 +57,23 @@ export default defineModule({
 		"zh-CN": () => import("./locales/zh-CN.json"),
 		"en-US": () => import("./locales/en-US.json"),
 	},
+	lifecycle: {
+		/**
+		 * 租户上下文（L2）：请求头由**运行时**注入（`runtime/store/tenant.ts`），模块不再注册
+		 * headerProvider——宿主 shell 的 hydrateUser / solution-routes 都在任何模块 onInit 之前
+		 * 就发请求，模块注册必然晚一步（2026-10-30 冷启动 e2e 实测两个 400 missing tenant header）。
+		 * 模块这里只保留「登出清租户」这一业务语义。
+		 */
+		async onInit(ctx) {
+			// 认证 provider：仅接管「企微票据换会话」，其余方式原样委托内置链（见 auth-provider.ts）。
+			// 注册时机必须在任何登录动作之前——onInit 先于路由渲染。
+			ctx.register.authProvider(authProvider);
+			// 登出必须清租户：否则下一个用户会带着上一个用户的租户头（跨租户请求 fail-closed 403，
+			// 但单租户部署会静默落到别人的 default 视图）。token 由非空转空即视为登出。
+			useAuthStore.subscribe((state, prev) => {
+				if (prev.token && !state.token)
+					useTenantStore.getState().clear();
+			});
+		},
+	},
 });

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

@@ -6,6 +6,12 @@
 		"password": "Password",
 		"submit": "Sign in",
 		"success": "Signed in",
+		"tenant": {
+			"label": "Enterprise code",
+			"hint": "Only needed on multi-tenant deployments (e.g. WeCom corp_id); leave empty otherwise",
+			"toggle": "Sign in with enterprise code",
+			"hide": "Hide enterprise code"
+		},
 		"changePwd": {
 			"title": "Change Password",
 			"hint": "After first login or an admin reset, you must change your password before using the system.",
@@ -21,6 +27,10 @@
 		"local": "Password",
 		"ldap": "LDAP",
 		"sso": "SSO",
-		"sso.action": "Sign in with SSO"
+		"sso.action": "Sign in with SSO",
+		"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.exchanging": "Completing WeCom sign-in…"
 	}
 }

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

@@ -6,6 +6,12 @@
 		"password": "密码",
 		"submit": "登 录",
 		"success": "登录成功",
+		"tenant": {
+			"label": "企业代码",
+			"hint": "多租户部署才需要填（如企微 corp_id）；单租户部署留空即可",
+			"toggle": "使用企业代码登录",
+			"hide": "收起企业代码"
+		},
 		"changePwd": {
 			"title": "修改密码",
 			"hint": "首次登录或管理员重置口令后，需先修改密码才能使用系统。",
@@ -21,6 +27,10 @@
 		"local": "账号密码",
 		"ldap": "LDAP",
 		"sso": "SSO",
-		"sso.action": "使用 SSO 登录"
+		"sso.action": "使用 SSO 登录",
+		"wecom": "企业微信",
+		"wecom.action": "使用企业微信登录",
+		"wecom.hint": "填写企业代码（企微后台可见的 corp_id），或直接使用管理员收到的专属登录链接",
+		"wecom.exchanging": "正在完成企业微信登录…"
 	}
 }