@oj-module/cli 0.2.47 → 0.2.49

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

@@ -13,6 +13,11 @@
 //   2. nonce 幂等：kv.incr 原子计数，首次才写入 TTL。计数而不是读改写，是为了
 //      「两个并发同 nonce」也只有一个拿到 1（oj 的 kv 在配了 Redis 时是多实例共享的）。
 //
+// ⚡ 幂等是「处理成功」才算数：拿到的是一次**占用**（ReplayClaim），调用方处理失败必须
+// `release()` 放回。不放回的后果不是理论问题——企微只在「拿不到 success」时重推，而那正是
+// 需要重推的时刻；占用不放，重推会被自己的重放守卫判成 400，恢复路径当场死掉
+// （2026-11-01 生产日志：create_auth 因上游 502 失败 → 重推 400「nonce 重复」）。
+//
 // 两条都回调 400：它不是「本站要鉴权」的问题，401 会把排查带偏。
 const REPLAY_WINDOW_SECS = 5 * 60;
 /** 计数键存活时间：只要盖住重放窗口即可，避免 kv 无界增长 */
@@ -22,6 +27,8 @@ export interface ReplayGate {
 	/** 原子自增并返回新值（kv.incr 同语义） */
 	incr: (key: string) => Promise<number>
 	expire: (key: string, ttlSecs: number) => Promise<unknown>
+	get: (key: string) => Promise<string | null>
+	set: (key: string, ttlSecs: number) => Promise<unknown>
 	del: (key: string) => Promise<unknown>
 	now: () => number
 }
@@ -35,16 +42,36 @@ export function runtimeReplayGate(): ReplayGate {
 	return {
 		incr: key => kv.incr(key),
 		expire: (key, ttlSecs) => kv.expire(key, ttlSecs),
+		get: key => kv.get(key),
+		set: async (key, ttlSecs) => { await kv.set(key, "1"); if (!(await kv.expire(key, ttlSecs))) { log.warn("wecom applied marker ttl not set", "key", key); await kv.del(key); } },
 		del: key => kv.del(key),
 		now: () => Math.floor(Date.now() / 1000),
 	};
 }
 
+/** 一次 nonce 占用：处理成功就不必管（TTL 到期自然消失）；失败必须 `release()` */
+export interface ReplayClaim {
+	release: () => Promise<void>
+}
+
+/** 重推且首次已成功落库：抛出后由调用方直接回 success（幂等），不让企微卡在「应用安装失败」。 */
+export class ReplayAlreadyApplied extends Error {
+	constructor() { super("nonce 已成功处理（幂等成功）"); }
+}
+
+/** 处理成功后调用：标记该 nonce 已落库成功，供重推幂等回 success（避免首次偏慢被企微判超时、重推又被重放守卫挡成 400）。 */
+export async function markApplied(nonce: string, gate: ReplayGate): Promise<void> {
+	await gate.set("wecom:applied:" + nonce, NONCE_TTL_SECS);
+}
+
 /**
- * 校验一次回调的时效与唯一性。通过 => void；不通过 => 抛 400。
+ * 校验一次回调的时效与唯一性。通过 => 返回占用凭据；不通过 => 抛 400。
  * 调用时机：**签名校验之后、解密之前**（先验签避免给未鉴权的请求写 kv，再拦重放省一次解密）。
+ *
+ * 占用是「这次报文归我处理」，不是「这条报文已经处理成功」——所以失败路径必须放回：
+ * 企微的重推是瞬态故障唯一的恢复手段，被自己的重放守卫挡掉等于把恢复路径拆了。
  */
-export async function guardReplay(timestampRaw: string, nonce: string, gate: ReplayGate): Promise<void> {
+export async function guardReplay(timestampRaw: string, nonce: string, gate: ReplayGate): Promise<ReplayClaim> {
 	const ts = Number(timestampRaw);
 	if (!Number.isInteger(ts) || ts <= 0)
 		fail(400, "回调 timestamp 非法");
@@ -55,12 +82,26 @@ export async function guardReplay(timestampRaw: string, nonce: string, gate: Rep
 
 	const key = `wecom:nonce:${nonce}`;
 	const seen = Number(await gate.incr(key));
-	if (seen !== 1)
+	if (seen !== 1) {
+		// 重推场景：若首次处理已成功落库（标了 applied 标记），直接幂等回 success，
+		// 不让企微卡在「应用安装失败」。未标记者说明首推仍在进行或已失败（失败会 release 让重推重放），维持 400。
+		const applied = await gate.get("wecom:applied:" + nonce);
+		if (applied)
+			throw new ReplayAlreadyApplied();
 		fail(400, "回调 nonce 重复：同一条指令回调已被处理过（重放请求已拒绝）");
+	}
 	// 首次访问才有资格设 TTL：设不上就删键——留一个没有过期的计数键既让它永久增长，
 	// 也会把未来的同一 nonce（虽概率极低）误判成重放。
 	if (!(await gate.expire(key, NONCE_TTL_SECS))) {
 		log.warn("wecom replay nonce ttl not set", "key", key);
 		await gate.del(key);
 	}
+	return {
+		// 直接 del，不做「是不是我占的那一次」的判断：oj 的 kv 没有 CAS，incr 的返回值
+		// 也已被消费在 seen 上。代价是并发同 nonce 时（同一秒内两次投递）可能多放过一次，
+		// 但放回的时机只在「处理失败」，而失败的这一条本来就该让企微重推。
+		release: async () => {
+			await gate.del(key);
+		},
+	};
 }

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

@@ -27,6 +27,8 @@ export interface AppProfile {
 	corpName: string | null
 	status: "active" | "disabled"
 	permanentCode: string
+	/** 0=管理员授权 / 1=成员授权（成员授权下应用无任何部门权限，组织架构同步必然 60011，§2.3） */
+	authMode: number
 }
 
 /** 套件票据：企微每 10 分钟推一次，有效期 30 分钟；过期不得发起任何套件级 API 调用 */
@@ -120,6 +122,8 @@ export async function saveProfile(p: Omit<AppProfile, "status"> & { status?: App
 		corp_name: p.corpName,
 		status: p.status ?? "active",
 		permanent_code_enc: deps.encrypt(p.permanentCode),
+		// 授权模式是「该企业应用能不能做组织架构同步」的判据（§2.3）；重授权时必须跟着刷新
+		auth_mode: Number(p.authMode ?? 0),
 		update_time: now,
 	};
 	if (rows.length) {
@@ -161,6 +165,43 @@ export async function findProfile(corpId: string, agentId: string | null, deps:
 		corpName: r.corp_name == null ? null : String(r.corp_name),
 		status: String(r.status) === "disabled" ? "disabled" : "active",
 		permanentCode: deps.decrypt(String(r.permanent_code_enc)),
+		authMode: Number(r.auth_mode ?? 0),
+	};
+}
+
+/** 「这家企业能不能同步」的三个事实：装没装 / 什么授权模式 / 是否还启用 */
+export interface ProfileProbe {
+	agentId: string
+	authMode: number
+	status: AppProfile["status"]
+}
+
+/**
+ * 授权探针（组织架构同步面的准入用）：与 `findProfile` 只差一件事——**查不到返回 null 而不是 400**。
+ *
+ * 为什么敢把「没有」当正常状态：调用方是本租户管理员在自己的组织架构页自省，`corp_id`
+ * 取自租户头而不是外部输入，不存在 `findProfile` 要防的枚举面（§5.3）。「本站没装企微」
+ * 是一个要能画成空态的事实，不是错误。
+ *
+ * 选中口径与 `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>>;
+	if (rows.length === 0)
+		return null;
+	const active = rows.filter(r => String(r.status) === "active");
+	const pool = active.length > 0 ? active : rows;
+	const picked = agentId ? pool.filter(r => String(r.agent_id) === agentId) : pool;
+	if (picked.length === 0)
+		return null;
+	if (picked.length > 1)
+		fail(400, "该企业开通了多个应用，同步入口必须带 agent 参数");
+	const r = picked[0]!;
+	return {
+		agentId: String(r.agent_id),
+		authMode: Number(r.auth_mode ?? 0),
+		status: String(r.status) === "disabled" ? "disabled" : "active",
 	};
 }
 
@@ -169,6 +210,30 @@ export async function setProfileStatus(corpId: string, status: AppProfile["statu
 	return Number(await db.table("wecom_app_profile").update({ status, update_time: deps.now() }).where(corpScope(corpId)).run());
 }
 
+/**
+ * 该企业已授权的应用 + 共享的永久授权码。
+ * 用于 `change_auth` 复核授权模式：事件只带 AuthCorpId（**没有 AuthCode**），
+ * 只能拿已落库的 permanent_code 去 `get_auth_info` 反查。未授权企业返回 null。
+ *
+ * 一并返回 `corpId`（真实企业 ID）：事件里给的可能是 `AuthCorpId`（第三方体系下是 open_corpid），
+ * 而租户键只能用真实 corp_id（D10），故由这里统一把「事件身份 → 租户身份」的翻译交出来。
+ */
+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>>;
+	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)),
+	};
+}
+
+/** 授权模式变更：只改 auth_mode，不动 secret / 状态（改状态是 cancel_auth 的事） */
+export async function setAuthMode(corpId: string, agentId: string, authMode: number, deps: WecomStoreDeps): Promise<void> {
+	await db.table("wecom_app_profile").update({ auth_mode: Number(authMode), update_time: deps.now() }).where(corpAgentScope(corpId, agentId)).run();
+}
+
 export async function putSuiteTicket(suiteId: string, ticket: string, expiresAt: number, deps: WecomStoreDeps): Promise<void> {
 	const rows = await db.table("wecom_suite_ticket").select(["suite_id"]).where({ field: "suite_id", op: "eq", value: suiteId }).all();
 	const cols = { suite_ticket: ticket, expires_at: expiresAt, update_time: deps.now() };

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

@@ -0,0 +1,501 @@
+// 企微组织架构**全量同步**（B2 / 方案 §6.2）：唯一权威来源。
+//
+// 形态是「分片推进」而不是「一个长任务」——服务端 isolate 没有定时器，路由也有超时，
+// 所以一次请求只推一片（默认 12 秒的预算），进度落在 wecom_sync_job 的游标里，
+// 由调用方轮询驱动。好处是：可续跑、可观测、不受路由超时限制、崩了也不丢进度。
+//
+// 三个阶段（相序固定，游标就是在这三个之间迁移）：
+//   departments → 一次 simplelist 拿可见范围内全部部门（兜底 department/list），按父子序落库；
+//   members     → 逐部门 user/list（要职务/排序/主部门，只有重量接口有），按片处理；
+//   reconcile   → **仅当本轮完整且零跳过**才把上一轮见过、这一轮没见的部门置隐（D9）。
+//
+// 三条纪律：
+//   · 归属权（D13）：所有写路径都带 `origin = 'wecom'`，本地建的部门一根毛都不碰；
+//   · 错码三分（§5.1）：权限类跳过并计数、限流类退避（client 内已重试，还错就停片等下轮）、
+//     致命类计入熔断（连续 FATAL_LIMIT 次 → job failed）；
+//   · 错误落库只存脱敏结构（`{errcode, phase, deptId, at}`）：异常原文里可能夹带 URL 上的 token。
+import type { WecomClient, WecomMember } from "./client";
+import type { ProfileProbe } from "./store";
+
+import { markSeen, reconcileHidden, upsertDepartment } from "#/_platform/_shared/service/domain/org";
+import { upsertSourceUser } from "#/_platform/_shared/service/domain/users";
+import { WecomApiError } from "./client";
+import { applyMemberDetail, externalUsername } from "./login";
+
+export type SyncStatus = "idle" | "running" | "done" | "failed" | "cancelled";
+export type SyncPhase = "departments" | "members" | "reconcile";
+
+export interface SyncStats {
+	/** 本轮落库的部门数 */
+	departments: number
+	/** 本轮结束时本企业的企微来源账号数（不是「人×部门」的调用次数） */
+	members: number
+	/** 因权限（60011/48002）跳过成员列表的部门数——页面要显示「N 个部门因权限跳过」 */
+	skipped: number
+	/** 是否执行了墓碑回收（有跳过就不敢回收，见 D9） */
+	reconciled: boolean
+}
+
+export interface SyncCursor {
+	phase: SyncPhase
+	/**
+	 * 轮次号（单调递增，落 `sys_department.seen_job_id`）。
+	 * 不用时间戳：同秒内重跑一轮会让「上一轮见过」和「本轮见过」撞成同一个值，
+	 * 墓碑回收（`seen_job_id < round`）就永远不生效。
+	 */
+	round: number
+	/** departments 阶段产出的部门清单；members 阶段按它逐部门拉人（游标只存本地 id + 企微 id） */
+	depts: Array<{ id: number, originId: string }>
+	/** 已处理到 depts 的下标（续跑锚点，避免同一部门重复拉） */
+	at: number
+	/** 连续致命错误计数（熔断） */
+	fatalRun: number
+}
+
+/** 同步任务本身的状态（只来自 `wecom_sync_job` 这一张表） */
+export interface SyncJobView {
+	status: SyncStatus
+	phase: SyncPhase
+	stats: SyncStats
+	/** 进度：done/total 均以「部门」计（成员阶段按已处理部门推进） */
+	progress: { done: number, total: number }
+	/** 脱敏后的错码与明细；非 failed 时为空 */
+	errCode: string | null
+	errDetail: { errcode?: number, phase: SyncPhase, deptId?: string, at: number } | null
+	startedAt: number
+	finishedAt: number
+	updateTime: number
+}
+
+/**
+ * 给页面看的完整状态 = 任务状态 + 授权事实。
+ * 两者刻意分开：`status` 是「同步跑到哪了」，`connected`/`authMode` 是「这家企业能不同步」，
+ * 后者来自授权面、前者来自执行面，混在一张表里就会在「取消授权后同步状态还写着 done」时自相矛盾。
+ */
+export interface SyncView extends SyncJobView {
+	/** 本站是否装过企微（有授权记录，含已停用）——false 时页面整条不显示 */
+	connected: boolean
+	/** 0=管理员授权 / 1=成员授权（1 时任何通讯录调用都是 60011，同步入口直接拒绝） */
+	authMode: number
+	/** 授权记录的应用状态；disabled = 已取消授权/被停用，同步冻结但数据保留（§7 黄条） */
+	profileStatus: "active" | "disabled" | null
+}
+
+export interface SyncDeps {
+	client: WecomClient
+	now: () => number
+	/** 单片时间预算（测试可调小；缺省见 DEFAULT_BUDGET_MS） */
+	budgetMs?: number
+}
+
+const ORIGIN = "wecom";
+/**
+ * 单片的墙钟预算。定 12 秒是两头夹出来的：
+ *   · 上界——路由全局超时 30 秒（`config.yaml server.timeout` 缺省 "30s"），而单次上游调用
+ *     自带 5 秒软超时（client.ts TIMEOUT_MS），预算到期后最多再等一次调用，12+5 < 30；
+ *   · 下界——4 秒（初版）配合 5 次/分的限速，前端串行驱动第 6 次就被 429 掐断，
+ *     500 人的企业要跑好几分钟；12 秒下一片能干完 100+ 次上游调用，正常规模两三次到底。
+ */
+const DEFAULT_BUDGET_MS = 12000;
+/** 连续致命错误上限（方案 §5.1「连续 10 次 → failed」） */
+const FATAL_LIMIT = 10;
+/** 抢锁租约：单片最长 12+5 秒，120 秒留给「请求被平台强杀、finally 都没跑到」的场景 */
+const LOCK_TTL_SECS = 120;
+
+function fail(status: number, message: string): never {
+	throw Object.assign(new Error(message), { status });
+}
+
+function emptyStats(): SyncStats {
+	return { departments: 0, members: 0, skipped: 0, reconciled: false };
+}
+
+function emptyCursor(): SyncCursor {
+	return { phase: "departments", round: 0, depts: [], at: 0, fatalRun: 0 };
+}
+
+function parseJson<T>(raw: unknown, fallback: T): T {
+	if (raw == null || raw === "")
+		return fallback;
+	try {
+		return JSON.parse(String(raw)) as T;
+	}
+	catch {
+		return fallback;
+	}
+}
+
+interface JobRow {
+	status: string
+	phase: string
+	cursor_text: string | null
+	stats_text: string | null
+	err_code: string | null
+	err_detail: string | null
+	started_at: number
+	finished_at: number
+	update_time: number
+}
+
+function jobScope(corpId: string, agentId: string) {
+	return {
+		and: [
+			{ field: "corp_id", op: "eq", value: corpId },
+			{ field: "agent_id", op: "eq", value: agentId },
+		],
+	};
+}
+
+async function readJob(corpId: string, agentId: string): Promise<JobRow | null> {
+	const rows = await db.table("wecom_sync_job").select(["*"]).where(jobScope(corpId, agentId)).all() as unknown as JobRow[];
+	return rows[0] ?? null;
+}
+
+function toView(job: JobRow | null): SyncJobView {
+	if (!job) {
+		return {
+			status: "idle",
+			phase: "departments",
+			stats: emptyStats(),
+			progress: { done: 0, total: 0 },
+			errCode: null,
+			errDetail: null,
+			startedAt: 0,
+			finishedAt: 0,
+			updateTime: 0,
+		};
+	}
+	const cursor = parseJson<SyncCursor>(job.cursor_text, emptyCursor());
+	return {
+		status: (job.status as SyncStatus) ?? "idle",
+		phase: (job.phase as SyncPhase) ?? cursor.phase,
+		stats: parseJson<SyncStats>(job.stats_text, emptyStats()),
+		progress: { done: cursor.at, total: cursor.depts.length },
+		errCode: job.err_code,
+		errDetail: parseJson<SyncJobView["errDetail"]>(job.err_detail, null),
+		startedAt: Number(job.started_at ?? 0),
+		finishedAt: Number(job.finished_at ?? 0),
+		updateTime: Number(job.update_time ?? 0),
+	};
+}
+
+/** 当前进度（只读本地行，不打上游）：轮询用它，不用 start */
+export async function syncStatus(corpId: string, agentId: string): Promise<SyncJobView> {
+	return toView(await readJob(corpId, agentId));
+}
+
+/** 拼上授权事实（见 SyncView 注释）。probe 为 null = 本站没装企微 */
+export function attachProfile(view: SyncJobView, probe: ProfileProbe | null): SyncView {
+	return {
+		...view,
+		connected: probe !== null,
+		authMode: probe?.authMode ?? 0,
+		profileStatus: probe?.status ?? null,
+	};
+}
+
+async function writeJob(corpId: string, agentId: string, patch: Record<string, unknown>, now: number): Promise<void> {
+	const cols = { ...patch, update_time: now };
+	const rows = await db.table("wecom_sync_job").select(["agent_id"]).where(jobScope(corpId, agentId)).all();
+	if (rows.length) {
+		await db.table("wecom_sync_job").update(cols).where(jobScope(corpId, agentId)).run();
+		return;
+	}
+	try {
+		await db.table("wecom_sync_job").insert({ corp_id: corpId, agent_id: agentId, started_at: now, finished_at: 0, ...cols }).run();
+	}
+	catch (e) {
+		// 唯一约束撞车（两片同时起）：转为更新，同 saveProfile 先例
+		if (!/unique|constraint/i.test(e instanceof Error ? e.message : String(e)))
+			throw e;
+		await db.table("wecom_sync_job").update(cols).where(jobScope(corpId, agentId)).run();
+	}
+}
+
+/**
+ * 抢锁：**靠复合主键插入**判原子，不靠读 status 再改。
+ * 过期租约（请求崩溃留下的行）允许抢占——否则一次 OOM 会让这个企业永远不能同步。
+ */
+async function acquireLock(agentId: string, owner: string, now: number): Promise<void> {
+	try {
+		await db.table("wecom_sync_lock").insert({ agent_id: agentId, owner, taken_at: now }).run();
+		return;
+	}
+	catch (e) {
+		if (!/unique|constraint/i.test(e instanceof Error ? e.message : String(e)))
+			throw e;
+	}
+	const rows = await db.table("wecom_sync_lock").select(["taken_at"]).where({ field: "agent_id", op: "eq", value: agentId }).all() as Array<{ taken_at: number }>;
+	const takenAt = Number(rows[0]?.taken_at ?? 0);
+	if (now - takenAt < LOCK_TTL_SECS)
+		fail(409, "同步正在进行，请稍后再试");
+	await db.table("wecom_sync_lock").update({ owner, taken_at: now }).where({ field: "agent_id", op: "eq", value: agentId }).run();
+}
+
+async function releaseLock(agentId: string): Promise<void> {
+	await db.table("wecom_sync_lock").where({ field: "agent_id", op: "eq", value: agentId }).delete().run();
+}
+
+/**
+ * 部门清单：主路径 `department/simplelist`（不带父 id = 应用可见范围内全部部门，一次拿完）。
+ * 上游明确写过 `department/list` 性能低（90208），故只当兜底——它多返回 `order`，
+ * 但大企业回包更容易撞 45029。
+ */
+async function fetchDepartments(client: WecomClient, corpId: string, agentId: string, secret: string) {
+	try {
+		return await client.departmentChildren(corpId, agentId, secret);
+	}
+	catch (e) {
+		if (e instanceof WecomApiError && e.kind === "permission")
+			throw e;
+		return await client.departmentList(corpId, agentId, secret);
+	}
+}
+
+/**
+ * 按父子序排好再落库：`upsertDepartment` 要的是**本地父 id**，所以父必须先存在。
+ * 孤儿（父不在结果集，通常是可见范围导致的）按方案挂到根，不报错；真成环的兜底也挂根
+ * （企微侧不会给出环，但这里绝不能死循环）。
+ */
+function orderTopDown<T extends { id: string, parentId: string }>(list: T[]): T[] {
+	const pending = new Map<string, T>(list.map(d => [d.id, d]));
+	const resolved = new Set<string>();
+	const out: T[] = [];
+	while (pending.size) {
+		let progressed = false;
+		for (const [id, d] of pending) {
+			const parent = d.parentId;
+			// 父为空、父不在本批（孤儿）、或父已排好 → 现在就能落
+			if (!parent || !pending.has(parent) || resolved.has(parent)) {
+				out.push(d);
+				resolved.add(id);
+				pending.delete(id);
+				progressed = true;
+			}
+		}
+		if (!progressed) {
+			for (const d of pending.values())
+				out.push(d);
+			break;
+		}
+	}
+	return out;
+}
+
+function scrubError(e: unknown, phase: SyncPhase, deptId: string | null, now: number): { errCode: string, errDetail: SyncJobView["errDetail"] } {
+	if (e instanceof WecomApiError)
+		return { errCode: String(e.errcode), errDetail: { errcode: e.errcode, phase, deptId: deptId ?? undefined, at: now } };
+	const message = e instanceof Error ? e.message : String(e);
+	// 非企微错码（网络/超时）：只留类别，不留原文（原文可能带 URL 上的 access_token）
+	return { errCode: /超时/.test(message) ? "timeout" : "network", errDetail: { phase, deptId: deptId ?? undefined, at: now } };
+}
+
+/** 没有 job 行时的空视图（导出给「本站没装企微」的空态用） */
+export function emptyView(status: SyncStatus): SyncJobView {
+	return { ...toView(null), status };
+}
+
+/**
+ * 开始 / 继续一次同步——**每调一次推一片**。
+ *
+ * 语义取「开始或继续」而不是「必须从零开始」：可续跑是这套分片设计的全部意义，
+ * 前端只要在 `status === "running"` 时继续调它（或由用户点「继续」），直到 done/failed。
+ */
+export async function startSync(ctx: { corpId: string, agentId: string, secret: string, authMode: number }, deps: SyncDeps): Promise<SyncJobView> {
+	// 准入判据：成员授权（auth_mode=1）下应用无任何部门权限，跑起来只会得到一片 60011
+	if (Number(ctx.authMode) !== 0)
+		fail(400, "该企业为「成员授权」模式，应用没有通讯录权限：请企业管理员在企微后台把授权模式改为「管理员授权」后再同步");
+
+	const now = Math.floor(deps.now() / 1000);
+	await acquireLock(ctx.agentId, `u${Number((globalThis as { http?: { user?: { id?: number } } }).http?.user?.id ?? 0)}`, now);
+	try {
+		const existing = await readJob(ctx.corpId, ctx.agentId);
+		const resumable = existing && existing.status === "running";
+		const prevCursor = existing ? parseJson<SyncCursor>(existing.cursor_text, emptyCursor()) : null;
+		let cursor = resumable && prevCursor
+			? prevCursor
+			: { ...emptyCursor(), round: (prevCursor?.round ?? 0) + 1 };
+		let stats = resumable ? parseJson<SyncStats>(existing.stats_text, emptyStats()) : emptyStats();
+		const startedAt = resumable ? Number(existing.started_at) : now;
+		const roundId = cursor.round;
+
+		await writeJob(ctx.corpId, ctx.agentId, {
+			status: "running",
+			phase: cursor.phase,
+			cursor_text: JSON.stringify(cursor),
+			stats_text: JSON.stringify(stats),
+			err_code: null,
+			err_detail: null,
+			started_at: startedAt,
+			finished_at: 0,
+		}, now);
+
+		const result = await runSlice(ctx.corpId, ctx.agentId, ctx.secret, cursor, stats, roundId, deps);
+		cursor = result.cursor;
+		stats = result.stats;
+		// 三态收敛：失败 / 片内收手（还在 running，等下一次 start）/ 全部跑完
+		const status: SyncStatus = result.failed ? "failed" : result.paused ? "running" : "done";
+		await writeJob(ctx.corpId, ctx.agentId, {
+			status,
+			phase: cursor.phase,
+			cursor_text: JSON.stringify(cursor),
+			stats_text: JSON.stringify(stats),
+			err_code: result.errCode,
+			err_detail: result.errDetail ? JSON.stringify(result.errDetail) : null,
+			finished_at: status === "running" ? 0 : now,
+		}, now);
+		return toView(await readJob(ctx.corpId, ctx.agentId));
+	}
+	finally {
+		await releaseLock(ctx.agentId);
+	}
+}
+
+interface SliceResult {
+	cursor: SyncCursor
+	stats: SyncStats
+	failed: boolean
+	/** 片内收手（预算用完 / 限流 / 可恢复的致命错）：进度已落库，下次接着推 */
+	paused: boolean
+	errCode: string | null
+	errDetail: SyncJobView["errDetail"]
+}
+
+async function runSlice(
+	corpId: string,
+	agentId: string,
+	secret: string,
+	cursor: SyncCursor,
+	stats: SyncStats,
+	roundId: number,
+	deps: SyncDeps,
+): Promise<SliceResult> {
+	const orgDeps = { now: deps.now };
+	const deadline = deps.now() + (deps.budgetMs ?? DEFAULT_BUDGET_MS);
+	const done = (extra: Partial<SliceResult> = {}): SliceResult => ({ cursor, stats, failed: false, paused: false, errCode: null, errDetail: null, ...extra });
+	const paused = (): SliceResult => done({ paused: true });
+
+	if (cursor.phase === "departments") {
+		let list: Array<{ id: string, parentId: string, name: string | null, order: number }>;
+		try {
+			list = await fetchDepartments(deps.client, corpId, agentId, secret);
+		}
+		catch (e) {
+			const scrubbed = scrubError(e, "departments", null, Math.floor(deps.now() / 1000));
+			return done({ failed: true, errCode: scrubbed.errCode, errDetail: scrubbed.errDetail });
+		}
+		const ordered = orderTopDown(list);
+		// 代开发 simplelist 不带部门名（见 client.ts departmentDetail 注释）：逐部门回源 department/get 补名字。
+		// 已有名字则跳过（普通企业 simplelist 可能带名字，不重复打上游）；单部门失败非致命，留空不影响骨架。
+		for (const d of ordered) {
+			if (d.name)
+				continue;
+			try {
+				const detail = await deps.client.departmentDetail(corpId, agentId, secret, d.id);
+				if (detail.name)
+					d.name = detail.name;
+			}
+			catch {
+				// 无权限 / 不在可见范围 / 上游抖动：名字留空，不因单部门失败中断整轮
+			}
+		}
+		const localByOrigin = new Map<string, number>();
+		const placedIds: number[] = [];
+		for (const d of ordered) {
+			const parentLocal = d.parentId && localByOrigin.has(d.parentId) ? localByOrigin.get(d.parentId)! : null;
+			const id = await upsertDepartment({ origin: ORIGIN, originId: d.id, parentId: parentLocal, name: d.name, orderNo: d.order }, orgDeps);
+			localByOrigin.set(d.id, id);
+			placedIds.push(id);
+		}
+		await markSeen(ORIGIN, placedIds, roundId, orgDeps);
+		cursor.depts = ordered.map(d => ({ id: localByOrigin.get(d.id)!, originId: d.id }));
+		cursor.at = 0;
+		cursor.phase = "members";
+		stats.departments = cursor.depts.length;
+	}
+
+	if (cursor.phase === "members") {
+		// 部门 id 映射：一次查询覆盖整片（500 部门以内一条 SQL；逐人查会把同步打成 N×M 次）
+		const rows = await db.table("sys_department").select(["id", "origin_id"]).where({ field: "origin", op: "eq", value: ORIGIN }).all() as Array<{ id: number, origin_id: string }>;
+		const deptByOrigin = new Map(rows.map(r => [String(r.origin_id), Number(r.id)]));
+		while (cursor.at < cursor.depts.length) {
+			if (deps.now() >= deadline)
+				return paused();
+			const dept = cursor.depts[cursor.at]!;
+			let members: WecomMember[];
+			try {
+				members = await deps.client.deptMembersDetail(corpId, agentId, secret, dept.originId);
+				cursor.fatalRun = 0;
+			}
+			catch (e) {
+				const kind = e instanceof WecomApiError ? e.kind : "fatal";
+				if (kind === "permission") {
+					// 单个部门无权限是常态（可见范围外的部门）：跳过并计数，不升级成失败
+					stats.skipped++;
+					cursor.at++;
+					continue;
+				}
+				if (kind === "ratelimit")
+					return paused(); // 限流已在 client 内退避三次，还错就停片，游标留在本部门
+				cursor.fatalRun++;
+				if (cursor.fatalRun >= FATAL_LIMIT) {
+					const scrubbed = scrubError(e, "members", dept.originId, Math.floor(deps.now() / 1000));
+					return done({ failed: true, errCode: scrubbed.errCode, errDetail: scrubbed.errDetail });
+				}
+				return paused();
+			}
+			for (const m of members)
+				await applyMember(m, corpId, deptByOrigin, orgDeps);
+			cursor.at++;
+		}
+		cursor.phase = "reconcile";
+	}
+
+	if (cursor.phase === "reconcile") {
+		// D9：只有「本轮完整且零跳过」才敢回收——否则一次上游抖动会被读成「这些部门被删了」
+		if (stats.skipped === 0) {
+			await reconcileHidden(ORIGIN, roundId, orgDeps);
+			stats.reconciled = true;
+		}
+		stats.members = await countMembers(corpId);
+	}
+
+	return done();
+}
+
+async function countMembers(corpId: string): Promise<number> {
+	const rows = await db.table("users").select(["id"]).where({ and: [
+		{ field: "source", op: "eq", value: ORIGIN },
+		{ field: "corp_id", op: "eq", value: corpId },
+	] }).all();
+	return rows.length;
+}
+
+/**
+ * 一个成员：建档（activated=0）→ 交给 `applyMemberDetail` 写资料与组织关系。
+ *
+ * 这里**只做「建档 + 传参」**：真正的字段口径（只写自己拥有的行、未知部门跳过、主部门兜底）
+ * 在 login.ts::applyMemberDetail 里，登录自更新与事件增量也调它。deptByOrigin 是本片预取的，
+ * 逐人去查会把这个 500 部门的同步打成 N×M 次查询。
+ */
+async function applyMember(m: WecomMember, corpId: string, deptByOrigin: Map<string, number>, orgDeps: { now: () => number }): Promise<void> {
+	const uid = await upsertSourceUser({ username: externalUsername(m.userid), displayName: m.name, source: ORIGIN, corpId });
+	await applyMemberDetail({ uid, userid: m.userid }, m, { ...orgDeps, deptByOrigin });
+}
+
+/** 取消：清游标、置 cancelled（不回滚已写入的组织数据——同步幂等，重跑即可） */
+export async function cancelSync(corpId: string, agentId: string, deps: { now: () => number }): Promise<SyncJobView> {
+	const now = Math.floor(deps.now() / 1000);
+	const job = await readJob(corpId, agentId);
+	if (!job)
+		return emptyView("idle");
+	await writeJob(corpId, agentId, {
+		status: "cancelled",
+		cursor_text: JSON.stringify(emptyCursor()),
+		err_code: null,
+		err_detail: null,
+		finished_at: now,
+	}, now);
+	await releaseLock(agentId);
+	return toView(await readJob(corpId, agentId));
+}