@oj-module/cli 0.2.47 → 0.2.49

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/login/web/locales/en-US.json

@@ -31,6 +31,8 @@
 		"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.agent": "App ID (agentid)",
+		"wecom.agentHint": "Leave empty if the corp has a single app; otherwise use the agentid provided by your admin",
 		"wecom.exchanging": "Completing WeCom sign-in…"
 	}
 }

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

@@ -31,6 +31,8 @@
 		"wecom": "企业微信",
 		"wecom.action": "使用企业微信登录",
 		"wecom.hint": "填写企业代码（企微后台可见的 corp_id），或直接使用管理员收到的专属登录链接",
+		"wecom.agent": "应用 ID（agentid）",
+		"wecom.agentHint": "留空使用该企业下唯一应用；多应用部署请填管理员提供的 agentid",
 		"wecom.exchanging": "正在完成企业微信登录…"
 	}
 }

package/templates/src/login/web/pages/login.tsx

@@ -66,8 +66,13 @@ export default function LoginPage() {
 		const current = useTenantStore.getState().tenant;
 		return current === DEFAULT_TENANT ? "" : current;
 	});
-	// 企微 tab 的企业代码（优先用已持久化的值，单租户的 default 不预填）
-	const [corp, setCorp] = useState(() => tenant);
+	// 企微深链入口：应用「主页」配成 /login?corp=<corpId>&agent=<agentId>，
+	// 成员从企微内点开即带参到达——据此预填企业代码/应用，并由下方 effect 自动发起授权。
+	const urlCorp = new URLSearchParams(search).get("corp")?.trim() ?? "";
+	const urlAgent = new URLSearchParams(search).get("agent")?.trim() ?? "";
+	// 企微 tab 的企业代码（优先用 URL 深链带的，其次已持久化的值，单租户的 default 不预填）
+	const [corp, setCorp] = useState(() => urlCorp || tenant);
+	const [agent, setAgent] = useState(() => urlAgent);
 
 	// 企微 302 落地参数：只在首次渲染解析一次（ticket 一次性，解析结果必须稳定）
 	const [landing] = useState(() => parseWecomLanding(search));
@@ -110,6 +115,23 @@ export default function LoginPage() {
 		})();
 	}, [landing, login, navigate, search]);
 
+	// 企微深链自动入口：带 ?corp= 到达（且非回跳落地 / 非出错）且企微方式可用时，
+	// 直接整页发起授权——「点开即登录」，无需手动点「企业微信」tab。
+	const autoFiredRef = useRef(false);
+	useEffect(() => {
+		const c = new URLSearchParams(search).get("corp")?.trim() ?? "";
+		// 企微内（wxwork UA）从「应用主页」点开即自动发起授权；带 ?corp= 的深链同样自动发起。
+		const inWecom = typeof navigator !== "undefined" && /wxwork/i.test(navigator.userAgent);
+		if ((!c && !inWecom) || landing || autoFiredRef.current)
+			return;
+		if (new URLSearchParams(search).get("error"))
+			return;
+		if (!methods.includes("wecom"))
+			return;
+		autoFiredRef.current = true;
+		window.location.assign(`${resolveApiBase()}${wecomAuthorizePath(corp, agent)}`);
+	}, [landing, methods, search, corp, agent]);
+
 	async function onFinish(values: LoginFormValues, method: LoginMethod) {
 		setLoading(true);
 		setError(undefined);
@@ -144,7 +166,7 @@ export default function LoginPage() {
 		// 必须拼 API base（部署期可为 /api 或网关前缀）；拼站点 base 只会落到
 		// SPA 兜底页——点击后页面原地重载、一个 auth 请求都不发。
 		// 企业代码不在这里写 store——只有服务端回跳带的 tenant 才是权威值。
-		window.location.assign(`${resolveApiBase()}${wecomAuthorizePath(corp)}`);
+		window.location.assign(`${resolveApiBase()}${wecomAuthorizePath(corp, agent)}`);
 	}
 
 	const showTabs = methods.length > 1;
@@ -180,6 +202,7 @@ export default function LoginPage() {
 	// 受控值不走 antd 表单（Form.Item 无 name），故显式给 id/htmlFor：
 	// 少了这层关联，标签只是视觉文本，读屏与 getByLabel 都取不到输入框。
 	const wecomCorpId = "wecom-corp";
+	const wecomAgentId = "wecom-agent";
 	const wecomPanel = (
 		<Form layout="vertical" onFinish={wecomLogin}>
 			<Form.Item
@@ -195,6 +218,19 @@ export default function LoginPage() {
 					onChange={e => setCorp(e.target.value)}
 				/>
 			</Form.Item>
+			<Form.Item
+				label={t("login:method.wecom.agent")}
+				htmlFor={wecomAgentId}
+				extra={t("login:method.wecom.agentHint")}
+			>
+				<Input
+					id={wecomAgentId}
+					autoComplete="off"
+					placeholder="1000..."
+					value={agent}
+					onChange={e => setAgent(e.target.value)}
+				/>
+			</Form.Item>
 			<Button type="primary" htmlType="submit" block>
 				{t("login:method.wecom.action")}
 			</Button>

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');

package/templates/src/system/api/departments/api.ts

@@ -0,0 +1,142 @@
+import type { OrgDeps } from "#/_platform/_shared/service/domain/org";
+import { respond } from "#/_platform/_shared/respond";
+// 管理域端点组 /api/system/departments —— 组织架构 CRUD 基线（方案 A2）。
+// handler 只编排：assertSystemAdmin 守卫 → org 领域服务 → json 信封；归属权红线在 org.ts（D13）。
+//
+// 列表**返回平表而不是树**：oj 的响应契约不支持递归 schema（contract IR 无 $ref），
+// 树由前端按 parentId 组装。管理员要看全量（含 sync_visible=0 与软删壳），故两个开关全开。
+import {
+	createDepartment,
+	deleteDepartment,
+	listDepartments,
+	memberCounts,
+
+	updateDepartment,
+} from "#/_platform/_shared/service/domain/org";
+import { assertSystemAdmin } from "#/_platform/_shared/service/infra/access";
+
+/** 秒级 epoch（与 sys_oplog / wecom store 同一口径） */
+const orgDeps: OrgDeps = { now: () => Math.floor(Date.now() / 1000) };
+
+// GET /api/system/departments —— 部门平表（含成员计数），管理页树的数据源。
+async function get() {
+	await respond(async () => {
+		await assertSystemAdmin();
+		const [depts, counts] = await Promise.all([
+			listDepartments({ includeDeleted: true, includeHidden: true }),
+			memberCounts(),
+		]);
+		return depts.map(d => ({ ...d, memberCount: counts.get(d.id) ?? 0 }));
+	});
+}
+get.response = {
+	type: "array",
+	items: {
+		type: "object",
+		required: ["id", "origin", "originId", "parentId", "name", "orderNo", "syncVisible", "deleted", "memberCount"],
+		properties: {
+			id: { type: "number" },
+			// 归属权标识：local = 本站可 CRUD；其余 = 对应适配器管辖（D13）
+			origin: { type: "string" },
+			originId: { type: "string" },
+			parentId: { type: ["number", "null"] },
+			name: { type: ["string", "null"] },
+			nameEn: { type: ["string", "null"] },
+			orderNo: { type: "number" },
+			syncVisible: { type: "boolean" },
+			deleted: { type: "boolean" },
+			memberCount: { type: "number" },
+		},
+	},
+};
+
+// POST /api/system/departments —— 建部门（origin 恒 local）。
+async function post() {
+	await respond(async () => {
+		await assertSystemAdmin();
+		const b = (http.body || {}) as { name?: string, parentId?: number | null, nameEn?: string | null, orderNo?: number };
+		return { id: await createDepartment({
+			name: String(b.name ?? ""),
+			parentId: b.parentId ?? null,
+			nameEn: b.nameEn ?? null,
+			orderNo: b.orderNo,
+		}, orgDeps) };
+	});
+}
+post.schema = {
+	body: {
+		type: "object",
+		required: ["name"],
+		properties: {
+			name: { type: "string", minLength: 1 },
+			// 不给 parentId 即建在根下
+			parentId: { type: ["number", "null"] },
+			nameEn: { type: ["string", "null"] },
+			orderNo: { type: "number" },
+		},
+	},
+};
+post.response = {
+	type: "object",
+	required: ["id"],
+	properties: { id: { type: "number" } },
+};
+
+// PUT /api/system/departments?id= —— 改名/排序。部门归属 origin='local' 才放行（D13）。
+async function put() {
+	await respond(async () => {
+		await assertSystemAdmin();
+		const q = http.query as Record<string, unknown>;
+		const b = (http.body || {}) as { name?: string, nameEn?: string | null, orderNo?: number };
+		await updateDepartment(Number(q.id), {
+			name: b.name,
+			nameEn: b.nameEn,
+			orderNo: b.orderNo,
+		}, orgDeps);
+		return { ok: true };
+	});
+}
+put.schema = {
+	query: {
+		type: "object",
+		required: ["id"],
+		properties: { id: { type: "number" } },
+	},
+	body: {
+		type: "object",
+		properties: {
+			name: { type: "string", minLength: 1 },
+			nameEn: { type: ["string", "null"] },
+			orderNo: { type: "number" },
+		},
+	},
+};
+put.response = {
+	type: "object",
+	required: ["ok"],
+	properties: { ok: { type: "boolean" } },
+};
+
+// DELETE /api/system/departments?id= —— 删部门（有子部门即拒；关联成员行一并清）。
+async function del() {
+	await respond(async () => {
+		await assertSystemAdmin();
+		const q = http.query as Record<string, unknown>;
+		await deleteDepartment(Number(q.id));
+		return { ok: true };
+	});
+}
+del.schema = {
+	query: {
+		type: "object",
+		required: ["id"],
+		properties: { id: { type: "number" } },
+	},
+};
+del.response = {
+	type: "object",
+	required: ["ok"],
+	properties: { ok: { type: "boolean" } },
+};
+
+export default { get, post, put, del };

package/templates/src/system/api/departments/detach/api.ts

@@ -0,0 +1,34 @@
+import type { OrgDeps } from "#/_platform/_shared/service/domain/org";
+import { respond } from "#/_platform/_shared/respond";
+import { detachToLocal } from "#/_platform/_shared/service/domain/org";
+// POST /api/system/departments/detach?id= —— 「转为本地维护」（D14 保底出口）。
+//
+// 把一行脱离适配器管辖（origin → local）：此后改名/移动/删除全开，且后续同步轮次
+// 不再改写它。这是「外部源只给了残缺数据（如企微未授权部门名）」时唯一的出路。
+// 反向操作不提供：转回去后下一次同步立刻按源口径改写，语义不可控。
+import { assertSystemAdmin } from "#/_platform/_shared/service/infra/access";
+
+const orgDeps: OrgDeps = { now: () => Math.floor(Date.now() / 1000) };
+
+async function post() {
+	await respond(async () => {
+		await assertSystemAdmin();
+		const q = http.query as Record<string, unknown>;
+		await detachToLocal(Number(q.id), orgDeps);
+		return { ok: true };
+	});
+}
+post.schema = {
+	query: {
+		type: "object",
+		required: ["id"],
+		properties: { id: { type: "number" } },
+	},
+};
+post.response = {
+	type: "object",
+	required: ["ok"],
+	properties: { ok: { type: "boolean" } },
+};
+
+export default { post };