@oj-module/cli 0.2.47 → 0.2.48

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

@@ -1,4 +1,5 @@
 import type { WecomConfig } from "../_shared/wecom/config";
+import type { CallbackFields } from "../_shared/wecom/payload";
 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
@@ -18,7 +19,7 @@ import { clientIp, guardLoginThrottle, noteLoginFailed, noteLoginSucceeded } fro
 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 { sha1Hex, unwrapWecomMessage, wecomSignature } from "../_shared/wecom/crypt";
 import { handleSuiteEvent } from "../_shared/wecom/events";
 import {
 	assertUserActive,
@@ -27,11 +28,12 @@ import {
 	LOGIN_TICKET_TTL_SECS,
 	loginLandingUrl,
 	putLoginState,
+	selfUpdate,
 	takeLoginState,
 } from "../_shared/wecom/login";
+import { callbackFields, field } from "../_shared/wecom/payload";
 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）。
@@ -58,6 +60,62 @@ function badRequest(message: string): Error {
 	return Object.assign(new Error(message), { status: 400 });
 }
 
+/**
+ * 解不开时把「哪一侧配错」记进日志——只回一句 `pkcs7: bad padding` 等于没给线索。
+ *
+ * 能先验签通过才走到解密，说明后台 Token 与本部署一致；于是解不开只剩两类：
+ *   · `bad padding` → **钥匙不对**：EncodingAESKey 与后台不一致（后台点过「随机生成」、或抄错/抄漏
+ *     一个字符），或这条推送其实来自另一个套件/模板（那把钥匙解不开这份密文）。
+ *     `aesKeyFp` 是本进程**实际加载**那把钥匙的指纹：改完 config 对不上就说明没生效（没重启/改错文件）。
+ *   · `receiver mismatch` → **钥匙对、身份不对**。`receiveid` 已按候选试过（见 unwrapAccepting：
+ *     suite_id + 信封 `ToUserName`），两边都对不上只剩两种：信封里没有 `ToUserName`，或这条推送
+ *     既不属本部署套件、receiveid 也不是它自己声称的身份（伪造/转发）。
+ *
+ * 注意 `envelopeToUser` **不等于** `configuredSuite` 是正常的：数据回调的 `ToUserName` 是 corpid。
+ */
+function noteDecryptFailure(e: unknown, envelope: CallbackFields | null, cfg: { encodingAesKey: string, suiteId: string }): void {
+	log.warn(
+		"wecom callback decrypt failed",
+		"reason",
+		(e as Error).message,
+		"envelopeToUser",
+		// URL 验证（GET）只有 query 里的 echostr，没有报文信封——那一侧记空串
+		envelope ? field(envelope, "ToUserName") : "",
+		"configuredSuite",
+		cfg.suiteId,
+		"aesKeyFp",
+		sha1Hex(cfg.encodingAesKey).slice(0, 8),
+	);
+}
+
+/**
+ * 按「可能合法的 receiveid」依次尝试解密。
+ *
+ * receiveid 的含义随场景变（90968 附注）：**第三方事件的回调是 suiteid**（suite_ticket / create_auth
+ * / cancel_auth），**企业应用（含代开发应用的数据回调）是 corpid**（通讯录变更就走这条）。
+ * 我们一个端点吃两种，只认 suiteid 会把所有数据回调判成「解密失败」——而真正的错是「比错了值」。
+ *
+ * 只对 `receiver mismatch` 换下一个候选：`bad padding` 说明密钥就不对，换谁都解不开，直接抛。
+ */
+function unwrapAccepting(encrypted: string, cfg: WecomConfig, candidates: string[]): string {
+	let lastErr: unknown;
+	const tried = new Set<string>();
+	for (const receiver of candidates) {
+		if (!receiver || tried.has(receiver))
+			continue;
+		tried.add(receiver);
+		try {
+			return unwrapWecomMessage(encrypted, cfg.encodingAesKey, receiver);
+		}
+		catch (e) {
+			if (!/receiver mismatch/.test((e as Error).message))
+				throw e;
+			lastErr = e;
+		}
+	}
+	throw lastErr ?? new Error("wecom: 没有可比对的 receiveid（suite_id 未配置？）");
+}
+
 /**
  * 校验企微回调签名并解出明文。签名不合法 → 400（不是 401：调用方是企微服务器，
  * 401 会被当成「本站需要鉴权」误导排查）；信封里的原文不回显，避免给探测者提供比对材料。
@@ -65,18 +123,20 @@ function badRequest(message: string): Error {
  * 三道顺序不可换：先验签（不给未鉴权请求写 kv）→ 再拦重放（省一次解密，也让
  * cancel_auth 这种危险性最高的报文止步在落库之前）→ 最后解密。
  */
-async function decryptVerified(encrypted: string): Promise<{ cfg: WecomConfig, plain: string }> {
+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"))
 		throw badRequest("回调签名校验失败");
 	await guardReplay(query("timestamp"), query("nonce"), runtimeReplayGate());
 	try {
-		return { cfg, plain: unwrapWecomMessage(encrypted, cfg.encodingAesKey, cfg.suiteId) };
+		// 信封的 ToUserName 就是这条报文的身份：套件事件里是 suiteid，应用数据回调里是 corpid，
+		// 与 receiveid 必然一致（两者在同一份密文/明文里，签名已经覆盖）。
+		return { cfg, plain: unwrapAccepting(encrypted, cfg, [cfg.suiteId, field(envelope, "ToUserName")]) };
 	}
 	catch (e) {
-		// 解密失败只透出「失败」：错钥/错套件/被篡改三者不可区分，也不该让外部据此判断哪一环配错
-		log.warn("wecom callback decrypt failed", "reason", (e as Error).message);
+		// 解密失败只对外透出「失败」：错钥/错套件/被篡改三者不可区分，也不该让外部据此判断哪一环配错
+		noteDecryptFailure(e, envelope, cfg);
 		throw badRequest("回调消息解密失败");
 	}
 }
@@ -135,12 +195,13 @@ const callback = {
 				throw badRequest("登录状态缺失：请从企业微信重新进入");
 
 			const deps = runtimeStoreDeps(cfg);
-			const pending = await takeLoginState(state, runtimeCache());
+			const cache = runtimeCache();
+			const pending = await takeLoginState(state, cache);
 			const profile = await findProfile(pending.corpId, pending.agentId, deps);
 			// 顺序刚性：先绑租户再碰 users（JIT 建号是租户表写入，守卫 deny 下缺上下文即拒）
 			ensureTenant(tenantOfCorp(profile.corpId));
 
-			const client = createWecomClient({ http: runtimeHttp(), cache: runtimeCache() });
+			const client = createWecomClient({ http: runtimeHttp(), cache });
 			const userid = await client.userIdByCode(profile.corpId, profile.agentId, profile.permanentCode, code);
 			// 名字是惰性取的：只有首次建档才多打一次 user/get（老用户零开销），拿不到就用工号兜底
 			const { uid, forbidden } = await ensureWecomUser(profile.corpId, userid, () =>
@@ -148,6 +209,15 @@ const callback = {
 			if (forbidden)
 				throw Object.assign(new Error("账号已被停用，请联系管理员"), { status: 403 });
 
+			// 轨一：登录自更新（方案 §6.1）。节流 24h、失败不影响登录；但企微侧已离职/禁用的
+			// 账号必须在这里拦下——本站的 is_forbidden 永远以管理员为准，不能被 IdP 反向覆盖。
+			const self = await selfUpdate(
+				{ uid, userid, corpId: profile.corpId, agentId: profile.agentId, permanentCode: profile.permanentCode },
+				{ client, cache, store: deps },
+			);
+			if (self.blocked)
+				throw Object.assign(new Error("账号在企业微信中已被停用或已退出企业，请联系企业管理员"), { status: 403 });
+
 			// 票据而不是 token 进 URL：token 会留在浏览器历史/Referer/反代日志里
 			const ticket = crypto.randomHex(32);
 			const tenant = tenantOfCorp(profile.corpId);
@@ -198,8 +268,9 @@ const event = {
 	// 不需要 suite_id——因此「配齐四项正确即可响应验证」，**不必等代开发模版创建、拿到 suite_id 之后**。
 	// 这正是打破鸡生蛋死锁（plan §18）的落点：先有可验证的回调，才能创建模版、拿到 suite 凭据。
 	//
-	// suite_id 在「模版创建成功」后才下发；URL 验证可能发生在拿到 suite_id 之前（创建表单内联校验），
-	// 此时 receiveid 无从比对 → 走 tolerant（签名已是最外层鉴权闸门，receiveid 仅为防御性兜底）。
+	// suite_id 在「模版创建成功」后才下发；URL 验证可能发生在拿到 suite_id 之前（创建表单内联校验）。
+	// 加上「应用回调 URL 验证时 receiveid 是 corpid」这一层，GET 根本无从挑一个值来比 → 一律 tolerant，
+	// 见下面 try 里的说明（签名是唯一闸门，本端点不落状态）。
 	async get() {
 		try {
 			const cfg = readCallbackConfig();
@@ -210,11 +281,15 @@ const event = {
 			await guardReplay(query("timestamp"), query("nonce"), runtimeReplayGate());
 			const suiteId = (vars.get("wecom_suite_id") ?? "").trim();
 			try {
-				plainText(unwrapWecomMessage(encrypted, cfg.encodingAesKey, suiteId, !suiteId));
+				// receiveid 一律不比对：GET 只有 echostr、没有报文信封，无从知道该比哪一个——
+				// 「模板/指令回调 URL」验证时 receiveid 是 suiteid，「应用回调 URL」验证时是 corpid。
+				// 放宽是安全的：签名已过（token 只有本部署与企微知道），回包只是把解出的 echostr 原样返回，
+				// 不写任何状态；真正的 receiveid 比对在 POST 那条路径上（见 unwrapAccepting）。
+				plainText(unwrapWecomMessage(encrypted, cfg.encodingAesKey, suiteId, true));
 			}
 			catch (e) {
 				// 解密失败只透出「失败」：错钥/未下发套件/被篡改三者不可区分，也不该让外部据此判断哪一环配错
-				log.warn("wecom callback decrypt failed", "reason", (e as Error).message);
+				noteDecryptFailure(e, null, { encodingAesKey: cfg.encodingAesKey, suiteId });
 				throw badRequest("回调消息解密失败");
 			}
 		}
@@ -223,20 +298,27 @@ const event = {
 		}
 	},
 
-	// 指令回调：验签 → 解密 → 分发（suite_ticket / create_auth / change_auth / cancel_auth /
-	// reset_permanent_code）。回 `success` 才算收下，否则企微 5 秒后重推三次。
+	// 回调（指令 + 应用数据）：验签 → 解密 → 分发（suite_ticket / create_auth / change_auth /
+	// cancel_auth / reset_permanent_code）。回 `success` 才算收下，否则企微 5 秒后重推三次。
+	//
+	// 包体形态按官方文档是 XML（见 payload.ts 的开头），但归一化那一层两种都认，
+	// 所以本函数只认字段名，不认格式。
 	async post() {
 		try {
-			const xml = typeof http.body === "string" ? http.body : "";
-			const encrypted = xmlField(xml, "Encrypt");
+			const envelope = callbackFields(http.body);
+			const encrypted = field(envelope, "Encrypt");
 			if (!encrypted)
-				throw badRequest("回调报文缺少 Encrypt");
-			const { cfg, plain } = await decryptVerified(encrypted);
+				throw badRequest("回调报文缺少 Encrypt（不是企微回调，或中间件改写了请求体）");
+			const { cfg, plain } = await decryptVerified(encrypted, envelope);
 			const client = createWecomClient({ http: runtimeHttp(), cache: runtimeCache() });
 			await handleSuiteEvent(plain, { cfg, client, store: runtimeStoreDeps(cfg) });
 			plainText("success");
 		}
 		catch (e) {
+			// 企微侧只会显示「应用安装失败，联系服务商」，原因一概不透露——这里是唯一能查到
+			// 「哪一环拒了这条事件」的地方（缺这一行，这场失败在运维视角是零信息）。
+			const err = e as Error & { status?: number };
+			log.error("wecom event failed", "status", err.status ?? 500, "reason", err.message);
 			// 失败必须让企微看到非 success：它重推三次，正好覆盖「suite_ticket 未到/上游抖」这类瞬态
 			failWith(e);
 		}

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

@@ -0,0 +1,199 @@
+// 企微组织架构同步面：POST /auth/wecom/sync/start · GET /auth/wecom/sync/status · POST /auth/wecom/sync/cancel
+//
+// 三条纪律（方案 §3 D7 / §5.3 / §9.5）：
+//   1. **不接受 corpId**：只同步调用方当前租户（企微部署下 tenant_id 就是 corp_id）。
+//      跨租户那套（superadmin 代触发）不在这里——它需要绕过 sql_guard，尚未落地，见计划文档。
+//   2. **必须带租户头**：这三个端点不进 tenant.anonymous_paths，`assertTenantSelf` 再兜一层
+//      ——伪造 X-TENANT-ID 时 token 的 sub 在目标租户里查无此人，一步拦掉。
+//   3. 门禁：`auth.wecom.sync`（admin/superadmin 天然通过；可绑给自定义角色）。
+//
+// 限速只加在 start/cancel 上（`orgsync:<uid>` 10 次/分）：status 是纯本地读取、不打上游，
+// 而进度条要 1~2 秒轮询一次——给它套限速等于把页面焊死。
+//
+// 10 次/分是跟单片预算（sync.ts DEFAULT_BUDGET_MS = 12 秒）配平的：一片打满 12 秒，
+// 串行驱动天然只有 5 次/分，10 次是「不挡住正常推进」的余量；再低（初版 5 次）会在
+// 第 6 片直接 429，大企业同步永远走不完。要动其中一个数，两个一起看。
+import { respond } from "#/_platform/_shared/respond";
+import { assertPermission, assertTenantSelf } from "#/_platform/_shared/service/infra/access";
+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 { findProfile, probeProfile, runtimeStoreDeps } from "../../_shared/wecom/store";
+import { attachProfile, cancelSync, emptyView, startSync, syncStatus } from "../../_shared/wecom/sync";
+
+function currentTenant(): string {
+	const t = (http as unknown as { tenantId?: unknown }).tenantId;
+	return typeof t === "string" ? t.trim() : "";
+}
+
+function currentUid(): number {
+	return Number(http.user?.id ?? 0);
+}
+
+const STATS = {
+	type: "object",
+	required: ["departments", "members", "skipped", "reconciled"],
+	properties: {
+		departments: { type: "number" },
+		members: { type: "number" },
+		skipped: { type: "number" },
+		reconciled: { type: "boolean" },
+	},
+} as const;
+
+const VIEW = {
+	type: "object",
+	required: ["connected", "authMode", "profileStatus", "status", "phase", "stats", "progress", "errCode", "errDetail", "startedAt", "finishedAt", "updateTime"],
+	properties: {
+		// 授权事实（页面据此决定「整条隐藏 / 成员授权卡片 / 冻结黄条 / 正常同步栏」）
+		connected: { type: "boolean" },
+		authMode: { type: "number" },
+		profileStatus: { type: ["string", "null"] },
+		status: { type: "string", enum: ["idle", "running", "done", "failed", "cancelled"] },
+		phase: { type: "string", enum: ["departments", "members", "reconcile"] },
+		stats: STATS,
+		progress: {
+			type: "object",
+			required: ["done", "total"],
+			properties: { done: { type: "number" }, total: { type: "number" } },
+		},
+		// 脱敏：只有错码与「哪一环、哪个部门、什么时候」，没有异常原文（原文可能夹带 token）
+		errCode: { type: ["string", "null"] },
+		errDetail: {
+			type: ["object", "null"],
+			properties: {
+				errcode: { type: "number" },
+				phase: { type: "string", enum: ["departments", "members", "reconcile"] },
+				deptId: { type: "string" },
+				at: { type: "number" },
+			},
+		},
+		startedAt: { type: "number" },
+		finishedAt: { type: "number" },
+		updateTime: { type: "number" },
+	},
+} as const;
+
+function agentOf(raw: unknown): string | null {
+	const s = String(raw ?? "").trim();
+	return s.length > 0 ? s : null;
+}
+
+/**
+ * 解析当前租户的授权档案（企业代码 = 租户；多应用时必须带 agent）。
+ *
+ * 先 probe 再 findProfile：探针负责把「没装 / 已取消授权」翻译成人话（`findProfile` 为防
+ * 枚举把两者统一成「企业代码无效或应用未开通」，那句文案摆在自家组织架构页上会让人以为
+ * 是自己填错了），findProfile 负责解密出 permanent_code。
+ */
+async function profileOf(tenantId: string, agent: unknown) {
+	const probe = await probeProfile(tenantId, agentOf(agent));
+	if (!probe) {
+		throw Object.assign(new Error("本站尚未开通企业微信：没有可同步的授权记录"), { status: 400 });
+	}
+	if (probe.status !== "active") {
+		throw Object.assign(new Error("该企业已取消授权或应用已停用：组织架构同步已冻结，请联系服务商重新开通"), { status: 400 });
+	}
+	const cfg = readWecomConfig();
+	const profile = await findProfile(tenantId, probe.agentId, runtimeStoreDeps(cfg));
+	return { profile, probe, cfg };
+}
+
+const start = {
+	/**
+	 * 开始 / 继续一次同步：**每调一次推一片**，直到 status 变成 done/failed。
+	 * 可续跑是这套分片设计的全部意义（isolate 无定时器、路由有超时），所以不是「必须从零开始」。
+	 */
+	async post() {
+		await respond(async () => {
+			await assertPermission("auth.wecom.sync");
+			await assertTenantSelf();
+			const tenantId = currentTenant();
+			if (!tenantId)
+				throw Object.assign(new Error("缺少租户上下文"), { status: 400 });
+			await rateLimit(`orgsync:${currentUid()}`, 10, 60_000);
+
+			const body = (http.body ?? {}) as { agent?: unknown };
+			const { profile, probe, cfg } = await profileOf(tenantId, body.agent);
+			const view = await startSync(
+				{ corpId: profile.corpId, agentId: profile.agentId, secret: profile.permanentCode, authMode: profile.authMode },
+				{ client: createWecomClient({ http: runtimeHttp(), cache: runtimeCache() }), now: () => Date.now() },
+			);
+			// 审计落在**本租户**（同步只动自己租户的数据）：企业管理员在自己的日志里就能看到是谁同步的
+			await recordOp({
+				action: "wecom.org.sync",
+				module: "auth",
+				target: profile.corpId,
+				detail: { agentId: profile.agentId, status: view.status, phase: view.phase, stats: view.stats, baseUrl: cfg.baseUrl },
+			});
+			return attachProfile(view, probe);
+		});
+	},
+};
+start.post.schema = {
+	body: {
+		type: "object",
+		properties: { agent: { type: "string" } },
+	},
+};
+start.post.response = VIEW;
+
+const status = {
+	// 进度轮询：只读 wecom_sync_job + 一次授权探针，不打上游、不占限速额度。
+	// 「本站没装企微」在这里是**正常返回**（connected:false），不是 400——页面整条状态栏据此隐藏。
+	async get() {
+		await respond(async () => {
+			await assertPermission("auth.wecom.sync");
+			await assertTenantSelf();
+			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));
+			if (!probe)
+				return attachProfile(emptyView("idle"), null);
+			return attachProfile(await syncStatus(tenantId, probe.agentId), probe);
+		});
+	},
+};
+status.get.schema = {
+	query: {
+		type: "object",
+		properties: { agent: { type: "string" } },
+	},
+};
+status.get.response = VIEW;
+
+const cancel = {
+	// 取消：清游标、置 cancelled。**不回滚**已写入的组织数据——同步幂等，重跑只是覆盖
+	async post() {
+		await respond(async () => {
+			await assertPermission("auth.wecom.sync");
+			await assertTenantSelf();
+			const tenantId = currentTenant();
+			if (!tenantId)
+				throw Object.assign(new Error("缺少租户上下文"), { status: 400 });
+			await rateLimit(`orgsync:${currentUid()}`, 10, 60_000);
+
+			const { profile, probe } = await profileOf(tenantId, (http.body as Record<string, unknown> | undefined)?.agent);
+			const view = await cancelSync(profile.corpId, profile.agentId, { now: () => Date.now() });
+			await recordOp({
+				action: "wecom.org.sync.cancel",
+				module: "auth",
+				target: profile.corpId,
+				detail: { agentId: profile.agentId, phase: view.phase, stats: view.stats },
+				level: 4,
+			});
+			return attachProfile(view, probe);
+		});
+	},
+};
+cancel.post.schema = {
+	body: {
+		type: "object",
+		properties: { agent: { type: "string" } },
+	},
+};
+cancel.post.response = VIEW;
+
+export default { start, status, cancel };

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"]),
+	"auth_mode": z.number(),
 	"installed_at": z.number(),
 	"update_time": z.number()
 })),
@@ -44,6 +45,102 @@ export const schemas = {
 	"authWecomTicketPost": {
 		body: z.object({
 	"ticket": z.string().min(32).max(128)
+}),
+	},
+	"authWecomSyncStartPost": {
+		body: z.object({
+	"agent": z.string().optional()
+}),
+		data: z.object({
+	"connected": z.boolean(),
+	"authMode": z.number(),
+	"profileStatus": z.string().nullable(),
+	"status": z.enum(["idle", "running", "done", "failed", "cancelled"]),
+	"phase": z.enum(["departments", "members", "reconcile"]),
+	"stats": z.object({
+	"departments": z.number(),
+	"members": z.number(),
+	"skipped": z.number(),
+	"reconciled": z.boolean()
+}),
+	"progress": z.object({
+	"done": z.number(),
+	"total": z.number()
+}),
+	"errCode": z.string().nullable(),
+	"errDetail": z.object({
+	"errcode": z.number().optional(),
+	"phase": z.enum(["departments", "members", "reconcile"]).optional(),
+	"deptId": z.string().optional(),
+	"at": z.number().optional()
+}).nullable(),
+	"startedAt": z.number(),
+	"finishedAt": z.number(),
+	"updateTime": z.number()
+}),
+	},
+	"authWecomSyncStatusGet": {
+		query: z.object({
+	"agent": z.string().optional()
+}),
+		data: z.object({
+	"connected": z.boolean(),
+	"authMode": z.number(),
+	"profileStatus": z.string().nullable(),
+	"status": z.enum(["idle", "running", "done", "failed", "cancelled"]),
+	"phase": z.enum(["departments", "members", "reconcile"]),
+	"stats": z.object({
+	"departments": z.number(),
+	"members": z.number(),
+	"skipped": z.number(),
+	"reconciled": z.boolean()
+}),
+	"progress": z.object({
+	"done": z.number(),
+	"total": z.number()
+}),
+	"errCode": z.string().nullable(),
+	"errDetail": z.object({
+	"errcode": z.number().optional(),
+	"phase": z.enum(["departments", "members", "reconcile"]).optional(),
+	"deptId": z.string().optional(),
+	"at": z.number().optional()
+}).nullable(),
+	"startedAt": z.number(),
+	"finishedAt": z.number(),
+	"updateTime": z.number()
+}),
+	},
+	"authWecomSyncCancelPost": {
+		body: z.object({
+	"agent": z.string().optional()
+}),
+		data: z.object({
+	"connected": z.boolean(),
+	"authMode": z.number(),
+	"profileStatus": z.string().nullable(),
+	"status": z.enum(["idle", "running", "done", "failed", "cancelled"]),
+	"phase": z.enum(["departments", "members", "reconcile"]),
+	"stats": z.object({
+	"departments": z.number(),
+	"members": z.number(),
+	"skipped": z.number(),
+	"reconciled": z.boolean()
+}),
+	"progress": z.object({
+	"done": z.number(),
+	"total": z.number()
+}),
+	"errCode": z.string().nullable(),
+	"errDetail": z.object({
+	"errcode": z.number().optional(),
+	"phase": z.enum(["departments", "members", "reconcile"]).optional(),
+	"deptId": z.string().optional(),
+	"at": z.number().optional()
+}).nullable(),
+	"startedAt": z.number(),
+	"finishedAt": z.number(),
+	"updateTime": z.number()
 }),
 	},
 };

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 };
+	return { authLoginPost, authLogoutPost, authRefreshPost, authPasswordPut, authLdapLoginPost, authWecomAdminAppsGet, authWecomAdminStatusPost, authWecomAdminInstallGet, authWecomLoginGet, authWecomCallbackGet, authWecomTicketPost, authWecomEventGet, authWecomEventPost, authWecomSyncStartPost, authWecomSyncStatusGet, authWecomSyncCancelPost };
 }
 
 /**
@@ -287,3 +287,75 @@ export async function authWecomEventPost(): Promise<unknown> {
 		throw await toApiError(e);
 	}
 }
+
+export type AuthWecomSyncStartPostBody = z.input<(typeof schemas)["authWecomSyncStartPost"]["body"]>;
+export type AuthWecomSyncStartPostData = z.infer<(typeof schemas)["authWecomSyncStartPost"]["data"]>;
+
+export async function authWecomSyncStartPost(body: AuthWecomSyncStartPostBody): Promise<AuthWecomSyncStartPostData> {
+	const client = ensureReq();
+	try {
+		const env = await client.post(`auth/wecom/sync/start`, { json: body }).json<OjEnvelope<AuthWecomSyncStartPostData>>();
+		// 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 AuthWecomSyncStartPostData;
+		if (import.meta.env.DEV) {
+			const { schemas } = await import("./api.schemas");
+			const r = schemas["authWecomSyncStartPost"].data.safeParse(data);
+			if (!r.success)
+				throw new ContractApiError(-1, `[契约违例] authWecomSyncStartPost 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+		}
+		return data;
+	}
+	catch (e) {
+		throw await toApiError(e);
+	}
+}
+
+export type AuthWecomSyncStatusGetQuery = z.input<(typeof schemas)["authWecomSyncStatusGet"]["query"]>;
+export type AuthWecomSyncStatusGetData = z.infer<(typeof schemas)["authWecomSyncStatusGet"]["data"]>;
+
+export async function authWecomSyncStatusGet(query: AuthWecomSyncStatusGetQuery): Promise<AuthWecomSyncStatusGetData> {
+	const client = ensureReq();
+	try {
+		const env = await client.get(`auth/wecom/sync/status`, { searchParams: query as Record<string, string | number | boolean> }).json<OjEnvelope<AuthWecomSyncStatusGetData>>();
+		// 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 AuthWecomSyncStatusGetData;
+		if (import.meta.env.DEV) {
+			const { schemas } = await import("./api.schemas");
+			const r = schemas["authWecomSyncStatusGet"].data.safeParse(data);
+			if (!r.success)
+				throw new ContractApiError(-1, `[契约违例] authWecomSyncStatusGet 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+		}
+		return data;
+	}
+	catch (e) {
+		throw await toApiError(e);
+	}
+}
+
+export type AuthWecomSyncCancelPostBody = z.input<(typeof schemas)["authWecomSyncCancelPost"]["body"]>;
+export type AuthWecomSyncCancelPostData = z.infer<(typeof schemas)["authWecomSyncCancelPost"]["data"]>;
+
+export async function authWecomSyncCancelPost(body: AuthWecomSyncCancelPostBody): Promise<AuthWecomSyncCancelPostData> {
+	const client = ensureReq();
+	try {
+		const env = await client.post(`auth/wecom/sync/cancel`, { json: body }).json<OjEnvelope<AuthWecomSyncCancelPostData>>();
+		// 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 AuthWecomSyncCancelPostData;
+		if (import.meta.env.DEV) {
+			const { schemas } = await import("./api.schemas");
+			const r = schemas["authWecomSyncCancelPost"].data.safeParse(data);
+			if (!r.success)
+				throw new ContractApiError(-1, `[契约违例] authWecomSyncCancelPost 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+		}
+		return data;
+	}
+	catch (e) {
+		throw await toApiError(e);
+	}
+}

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

@@ -1,7 +1,7 @@
 -- notification 模块种子（按人真实通知）。user_id=1（admin），link/category 幂等可空/默认。
 -- avatar 给真实 URL：铃铛按 avatar 渲染头像，空串会破图（空串仅作为运行时兜底，不作为种子值）。
 -- 按分号朴素切分（S006）：语句内不得含分号字面量。
-INSERT OR IGNORE INTO notifications (id, user_id, avatar, date, is_read, message, title, link, category) VALUES (1, 1, 'https://avatar.vercel.sh/seed-welcome.svg?text=W', '2026-09-01 09:12', 0, '脚手架已就绪，用 admin / 123456 登录开始', '欢迎', NULL, 'notice');
+INSERT OR IGNORE INTO notifications (id, user_id, avatar, date, is_read, message, title, link, category) VALUES (1, 1, 'https://avatar.vercel.sh/seed-welcome.svg?text=W', '2026-09-01 09:12', 0, '脚手架已就绪，用 admin / aA123456 登录开始', '欢迎', NULL, 'notice');
 INSERT OR IGNORE INTO notifications (id, user_id, avatar, date, is_read, message, title, link, category) VALUES (2, 1, 'https://avatar.vercel.sh/seed-bell.svg?text=B', '2026-09-02 14:30', 0, '通知铃支持单条已读、全部已读与清空；广播经 push-broadcast 入 b: 命名空间', '通知铃', NULL, 'notice');
 INSERT OR IGNORE INTO notifications (id, user_id, avatar, date, is_read, message, title, link, category) VALUES (3, 1, 'https://avatar.vercel.sh/seed-contract.svg?text=C', '2026-09-03 18:45', 1, '契约改动后重跑 ojm api 生成前端 client 与文档', '契约', NULL, 'notice');
 INSERT OR IGNORE INTO notifications (id, user_id, avatar, date, is_read, message, title, link, category) VALUES (4, 1, 'https://avatar.vercel.sh/seed-dev.svg?text=D', '2026-09-04 08:00', 0, '编辑 api/src 下的 api.ts 保存即热更；handler 组支持四层嵌套（oj v0.1.64）', '开发提示', NULL, 'notice');