@oj-module/cli 0.2.46 → 0.2.48

package/templates/src/system/web/pages/departments/sync-bar.tsx

@@ -0,0 +1,257 @@
+// 组织架构页顶部的企微同步状态条（方案 §5.4 / §6.4 / §7）。
+//
+// 一条纪律：**状态条只在「本租户装了企微」时才出现**。没装企微的站点（纯 CRUD 用户）看到的
+// 就是一页干净的组织架构——所以 `connected=false`、无权限（403）、没有授权记录（400）都不画红条。
+//
+// 交互形态由后端的分片设计决定：一次 start 只推一片，调用方轮询。这里把它包成「一次点击 =
+// 一直推到 done/failed」，中间按限速配额留最小间隔；暂停/失败后按钮变「继续同步」，进度不丢。
+import { request } from "@oj-module/runtime";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+import { Alert, App, Button, Progress, Space, Typography } from "antd";
+import { useEffect, useRef, useState } from "react";
+import { useTranslation } from "react-i18next";
+
+import { errMsg, statusOf } from "../errors";
+
+/** 与后端 `auth/wecom/sync/api.ts` 的 VIEW 契约同形（跨模块调用，走全局 request 而非生成本模块 client） */
+interface SyncView {
+	connected: boolean
+	authMode: number
+	profileStatus: "active" | "disabled" | null
+	status: "idle" | "running" | "done" | "failed" | "cancelled"
+	phase: "departments" | "members" | "reconcile"
+	stats: { departments: number, members: number, skipped: number, reconciled: boolean }
+	progress: { done: number, total: number }
+	errCode: string | null
+	errDetail: { errcode?: number, phase: string, deptId?: string, at: number } | null
+	startedAt: number
+	finishedAt: number
+	updateTime: number
+}
+
+const KEY = ["system", "wecom-sync"] as const;
+
+/** 单片推完到下一次 start 的最小间隔：后端限速 10 次/分，串行驱动别自己撞 429 */
+const MIN_GAP_MS = 6000;
+/** 一轮点击最多推多少片（12 秒/片 ≈ 12 分钟）：兜底防呆，正常企业两三次就到底 */
+const MAX_SLICES = 60;
+
+async function fetchStatus(): Promise<SyncView> {
+	const env = await request.get("auth/wecom/sync/status").json<{ code: number, data?: SyncView }>();
+	if (!env.data)
+		throw new Error("企业微信同步状态读取失败");
+	return env.data;
+}
+
+async function pushSlice(): Promise<SyncView> {
+	const env = await request.post("auth/wecom/sync/start", { json: {} }).json<{ code: number, data?: SyncView }>();
+	if (!env.data)
+		throw new Error("企业微信同步未能启动");
+	return env.data;
+}
+
+async function cancelSync(): Promise<SyncView> {
+	const env = await request.post("auth/wecom/sync/cancel", { json: {} }).json<{ code: number, data?: SyncView }>();
+	if (!env.data)
+		throw new Error("取消同步失败");
+	return env.data;
+}
+
+function sleep(ms: number): Promise<void> {
+	return new Promise((resolve) => {
+		setTimeout(resolve, ms);
+	});
+}
+
+/**
+ * 「X 分钟前」：用**服务端时间戳之差**（updateTime - finishedAt）而不是浏览器 Date.now()，
+ * 一来渲染期不调时钟（纯函数），二来服务器与浏览器时区/时钟偏差不会把「刚刚」算成「8 小时前」。
+ */
+function agoLabel(secs: number, t: (k: string, o?: Record<string, unknown>) => string): string {
+	if (secs < 60)
+		return t("system:wecom.sync.ago.justNow");
+	if (secs < 3600)
+		return t("system:wecom.sync.ago.minutes", { count: Math.floor(secs / 60) });
+	if (secs < 86400)
+		return t("system:wecom.sync.ago.hours", { count: Math.floor(secs / 3600) });
+	return t("system:wecom.sync.ago.days", { count: Math.floor(secs / 86400) });
+}
+
+/** 错码 → 卡片文案（§7 表：谁处理、怎么办，别让企业管理员对着错误码发呆） */
+function errorCard(code: string, t: (k: string, o?: Record<string, unknown>) => string): { title: string, hint: string } {
+	const pick = (kind: string) => ({
+		title: t(`system:wecom.sync.err.${kind}.title`, { code }),
+		hint: t(`system:wecom.sync.err.${kind}.hint`, { code }),
+	});
+	if (code === "60011" || code === "48002")
+		return pick("permission");
+	if (code === "45009" || code === "45033")
+		return pick("rateLimited");
+	if (code === "60020")
+		return pick("ipWhitelist");
+	if (code === "timeout" || code === "network")
+		return pick("network");
+	return pick("unknown");
+}
+
+/** 状态条：只画「能不能同步 / 同步到哪了 / 失败了怎么办」，不暴露「三轨」这类内部名词 */
+export function WecomSyncBar({ onFinished }: { onFinished: () => void }) {
+	const { t } = useTranslation();
+	const { message } = App.useApp();
+	const queryClient = useQueryClient();
+	const [driving, setDriving] = useState(false);
+	const [cancelling, setCancelling] = useState(false);
+	// 组件卸载后停止继续推片：否则离开页面的人在后台被反复打上游
+	const aliveRef = useRef(true);
+	useEffect(() => {
+		return () => {
+			aliveRef.current = false;
+		};
+	}, []);
+
+	const query = useQuery({
+		queryKey: KEY,
+		queryFn: fetchStatus,
+		retry: false,
+		// 只有「别人在推」（另一标签页 / 上次未收尾）时才轮询；自己在推时每一片都带最新状态
+		refetchInterval: q => (!driving && q.state.data?.status === "running" ? 2000 : false),
+	});
+
+	const setView = (v: SyncView) => queryClient.setQueryData(KEY, v);
+
+	const drive = async () => {
+		setDriving(true);
+		let last: SyncView | null = null;
+		try {
+			for (let i = 0; i < MAX_SLICES; i++) {
+				const startedAt = Date.now();
+				const view = await pushSlice();
+				if (!aliveRef.current)
+					return;
+				last = view;
+				setView(view);
+				if (view.status !== "running") {
+					if (view.status === "done")
+						message.success(t("system:wecom.sync.done", { depts: view.stats.departments, members: view.stats.members }));
+					onFinished();
+					return;
+				}
+				// 短片（限流退避 / 空转）会连着打：补足间隔，别自己撞后端 10 次/分的限速
+				const spent = Date.now() - startedAt;
+				if (spent < MIN_GAP_MS) {
+					await sleep(MIN_GAP_MS - spent);
+					if (!aliveRef.current)
+						return;
+				}
+			}
+			message.warning(t("system:wecom.sync.paused", { depts: last?.stats.departments ?? 0 }));
+		}
+		catch (e) {
+			message.error(errMsg(e));
+		}
+		finally {
+			if (aliveRef.current)
+				setDriving(false);
+			queryClient.invalidateQueries({ queryKey: KEY });
+		}
+	};
+
+	const stop = async () => {
+		setCancelling(true);
+		try {
+			setView(await cancelSync());
+			message.success(t("system:wecom.sync.cancelled"));
+		}
+		catch (e) {
+			message.error(errMsg(e));
+		}
+		finally {
+			if (aliveRef.current)
+				setCancelling(false);
+		}
+	};
+
+	// 未连接 / 无权限 / 站点没接企微：整条不出现。403 与 400 都是「正常情况下就该没有」，
+	// 别的错误（500、网络）才值得占版面，让人知道「是有同步功能但它坏了」。
+	if (query.error && statusOf(query.error) !== 403 && statusOf(query.error) !== 400)
+		return <Alert type="warning" showIcon message={errMsg(query.error)} />;
+
+	const view = query.data;
+	if (!view || !view.connected)
+		return null;
+
+	if (view.authMode !== 0) {
+		return (
+			<Alert
+				type="warning"
+				showIcon
+				message={t("system:wecom.sync.memberAuth.title")}
+				description={t("system:wecom.sync.memberAuth.hint")}
+			/>
+		);
+	}
+
+	if (view.profileStatus === "disabled") {
+		return (
+			<Alert
+				type="warning"
+				showIcon
+				message={t("system:wecom.sync.frozen.title")}
+				description={t("system:wecom.sync.frozen.hint")}
+			/>
+		);
+	}
+
+	const running = view.status === "running";
+	const lastAt = view.finishedAt || view.updateTime;
+	const percent = view.progress.total > 0 ? Math.round((view.progress.done / view.progress.total) * 100) : 0;
+
+	const headline = running
+		? (view.progress.total > 0
+			? t("system:wecom.sync.syncingProgress", { done: view.progress.done, total: view.progress.total })
+			: t("system:wecom.sync.syncing"))
+		: lastAt > 0
+			? `${t("system:wecom.sync.updatedAt", { time: agoLabel(Math.max(0, view.updateTime - lastAt), t) })} · ${t("system:wecom.sync.auto")}`
+			: t("system:wecom.sync.neverSynced");
+
+	return (
+		<Alert
+			type={view.status === "failed" ? "error" : "info"}
+			showIcon
+			message={(
+				<Space size="middle" wrap>
+					<Typography.Text>{headline}</Typography.Text>
+					{!running && view.stats.skipped > 0 && (
+						<Typography.Text type="warning">
+							{t("system:wecom.sync.skipped", { count: view.stats.skipped })}
+						</Typography.Text>
+					)}
+				</Space>
+			)}
+			description={view.status === "failed" && view.errCode
+				? (
+					<Space direction="vertical" size={0}>
+						<Typography.Text strong>{errorCard(view.errCode, t).title}</Typography.Text>
+						<Typography.Text type="secondary">{errorCard(view.errCode, t).hint}</Typography.Text>
+					</Space>
+				)
+				: running && view.progress.total > 0
+					? <Progress percent={percent} size="small" style={{ maxWidth: 320 }} />
+					: undefined}
+			action={(
+				<Space direction="vertical" size={4}>
+					<Button type="primary" size="small" loading={driving} onClick={drive}>
+						{running
+							? t("system:wecom.sync.resume")
+							: view.status === "failed" ? t("system:wecom.sync.retry") : t("system:wecom.sync.syncNow")}
+					</Button>
+					{running && (
+						<Button size="small" type="text" danger loading={cancelling} onClick={stop}>
+							{t("system:wecom.sync.cancel")}
+						</Button>
+					)}
+				</Space>
+			)}
+		/>
+	);
+}

package/templates/src/system/web/pages/departments/tree.ts

@@ -0,0 +1,66 @@
+import type { TreeDataNode } from "antd";
+
+/**
+ * 部门平表 → 树 / 子孙闭包。两处消费：部门管理页自己画树、用户页按部门（含子部门）筛选。
+ * 只依赖 `id`/`parentId` 两个字段，所以既能吃 `systemDepartmentsGet` 的行，也能吃别的部门投影。
+ */
+export interface DeptLike {
+	id: number
+	parentId: number | null
+}
+
+/**
+ * 组装 antd 树数据。后端下发平表（响应契约不支持递归 schema），树在这里拼。
+ *
+ * 两条脏数据防线（外部源可见范围裁剪的必然产物，不是 bug）：
+ *   · emitted：每个节点只挂一次——成环时不会无限递归，环上未挂到的节点补挂到根；
+ *   · depth：兜底，防御性上限，正常数据远达不到。
+ */
+export function buildTreeData<T extends DeptLike>(rows: T[], titleOf: (d: T) => React.ReactNode): TreeDataNode[] {
+	const byId = new Map(rows.map(d => [d.id, d]));
+	const childIds = new Map<number, number[]>();
+	for (const d of rows) {
+		if (d.parentId != null && byId.has(d.parentId))
+			(childIds.get(d.parentId) ?? childIds.set(d.parentId, []).get(d.parentId)!).push(d.id);
+	}
+	const emitted = new Set<number>();
+	const build = (d: T, depth: number): TreeDataNode | null => {
+		if (emitted.has(d.id) || depth > 32)
+			return null;
+		emitted.add(d.id);
+		return {
+			key: d.id,
+			title: titleOf(d),
+			children: (childIds.get(d.id) ?? [])
+				.map(id => build(byId.get(id)!, depth + 1))
+				.filter((n): n is TreeDataNode => n !== null),
+		};
+	};
+	const roots = rows.filter(d => d.parentId == null || !byId.has(d.parentId)).map(d => build(d, 0));
+	// 环上节点：父存在但永远轮不到挂（父在环里）→ 补挂到根，保证一个不丢
+	for (const d of rows) {
+		if (!emitted.has(d.id))
+			roots.push(build(d, 0));
+	}
+	return roots.filter((n): n is TreeDataNode => n !== null);
+}
+
+/**
+ * 从 `roots` 出发向下取「自己 + 全部子孙」的 id 闭包。
+ *
+ * 两处用途：部门管理页挡「把父部门挂到自己孙部门下」（后端判环 400）；用户页筛部门时
+ * 把子部门的人一并算进来。成环安全——每个节点最多进一次集合，循环必然终止。
+ */
+export function subtreeIds<T extends DeptLike>(rows: T[], roots: Iterable<number>): Set<number> {
+	const ids = new Set<number>(roots);
+	for (let grew = true; grew;) {
+		grew = false;
+		for (const d of rows) {
+			if (d.parentId != null && ids.has(d.parentId) && !ids.has(d.id)) {
+				ids.add(d.id);
+				grew = true;
+			}
+		}
+	}
+	return ids;
+}

package/templates/src/system/web/pages/errors.ts

@@ -5,7 +5,7 @@
  */
 
 /** HTTP 状态：ContractApiError.code 优先，HTTPError 回落 response.status */
-function statusOf(e: unknown): number | undefined {
+export function statusOf(e: unknown): number | undefined {
 	const err = e as { code?: number, response?: Response } | null;
 	if (typeof err?.code === "number")
 		return err.code;

package/templates/src/system/web/pages/users/index.tsx

@@ -3,13 +3,14 @@ import type { SystemUsersGetData } from "../../__client/api";
 import { PlusOutlined } from "@ant-design/icons";
 import { useUserStore } from "@oj-module/runtime";
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
-import { App, Button, Form, Input, Modal, Popconfirm, Space, Switch, Table, Tag } from "antd";
-import { useState } from "react";
+import { App, Button, Form, Input, Modal, Popconfirm, Space, Switch, Table, Tag, TreeSelect, Typography } from "antd";
+import { useMemo, useState } from "react";
 import { useTranslation } from "react-i18next";
 
 import { useNavigate } from "react-router";
 
-import { systemUsersForbiddenPut, systemUsersGet, systemUsersPasswordPut, systemUsersPost } from "../../__client/api";
+import { systemDepartmentsGet, systemUsersForbiddenPut, systemUsersGet, systemUsersPasswordPut, systemUsersPost } from "../../__client/api";
+import { buildTreeData, subtreeIds } from "../departments/tree";
 import { explainError, isForbidden } from "../errors";
 import { ForbiddenPanel } from "../forbidden";
 
@@ -19,6 +20,7 @@ type UserRow = SystemUsersGetData[number];
  * 用户管理（C1）：GET /system/users 列表 + 建号 / 禁用切换 / 重置口令。
  * 本人行禁用一切自操作（后端 assertNotSelf 400 兜底，前端不给会失败的按钮，R3）；
  * 成员资格入口仅 superadmin 可见（成员资格写是 superadmin-only，规格 §4）。
+ * 部门列标出主部门，顶部可按部门筛选（含子部门）——筛选在前端做，名单本来就是一页全量。
  */
 export default function UsersPage() {
 	const { t } = useTranslation();
@@ -33,8 +35,11 @@ export default function UsersPage() {
 	const [createForm] = Form.useForm<{ username: string, password: string, displayName?: string, email?: string }>();
 	const [pwdTarget, setPwdTarget] = useState<UserRow | null>(null);
 	const [pwdForm] = Form.useForm<{ password: string }>();
+	const [deptId, setDeptId] = useState<number | null>(null);
 
 	const usersQuery = useQuery({ queryKey: ["system", "users"], queryFn: systemUsersGet });
+	// 与部门页共用同一份缓存键：那边改完部门，这边的筛选树也跟着新
+	const deptQuery = useQuery({ queryKey: ["system", "departments"], queryFn: systemDepartmentsGet });
 
 	const invalidate = () => queryClient.invalidateQueries({ queryKey: ["system", "users"] });
 
@@ -66,12 +71,34 @@ export default function UsersPage() {
 		onError: e => message.error(explainError(e, t)),
 	});
 
+	const deptRows = useMemo(() => deptQuery.data ?? [], [deptQuery.data]);
+	const deptTree = useMemo(() => buildTreeData(deptRows, d => d.name ?? `#${d.id}`), [deptRows]);
+	// 选中部门 + 全部子部门：筛「研发部」要能带出「研发部/前端组」的人
+	const scope = useMemo(() => (deptId == null ? null : subtreeIds(deptRows, [deptId])), [deptRows, deptId]);
+	const visibleUsers = useMemo(() => {
+		const all = usersQuery.data ?? [];
+		return scope ? all.filter(u => u.departments.some(d => scope.has(d.id))) : all;
+	}, [usersQuery.data, scope]);
+
 	if (usersQuery.error && isForbidden(usersQuery.error))
 		return <ForbiddenPanel t={t} error={usersQuery.error} />;
 
 	const columns = [
 		{ title: t("system:users.columns.username"), dataIndex: "username" },
 		{ title: t("system:users.columns.displayName"), dataIndex: "display_name" },
+		{ title: t("system:users.columns.position"), dataIndex: "position" },
+		{
+			title: t("system:users.columns.departments"),
+			dataIndex: "departments",
+			render: (departments: UserRow["departments"]) => departments.length === 0
+				? <Typography.Text type="secondary">—</Typography.Text>
+				: departments.map(d => (
+					<Tag key={d.id} color={d.isMain ? "blue" : undefined}>
+						{d.name ?? `#${d.id}`}
+						{d.isMain ? ` · ${t("system:users.mainDept")}` : ""}
+					</Tag>
+				)),
+		},
 		{ title: t("system:users.columns.email"), dataIndex: "email" },
 		{
 			title: t("system:users.columns.roles"),
@@ -116,13 +143,28 @@ export default function UsersPage() {
 
 	return (
 		<Space direction="vertical" style={{ width: "100%", paddingTop: 16 }}>
-			<Button type="primary" icon={<PlusOutlined />} onClick={() => setCreateOpen(true)}>
-				{t("system:users.create")}
-			</Button>
+			<Space wrap>
+				<Button type="primary" icon={<PlusOutlined />} onClick={() => setCreateOpen(true)}>
+					{t("system:users.create")}
+				</Button>
+				<TreeSelect
+					allowClear
+					showSearch
+					treeNodeFilterProp="title"
+					loading={deptQuery.isLoading}
+					style={{ width: 240 }}
+					placeholder={t("system:users.filterDept")}
+					treeData={deptTree}
+					// 树是按 antd Tree 口径拼的（key/title），TreeSelect 认的是 value —— 这里换名映射
+					fieldNames={{ label: "title", value: "key", children: "children" }}
+					value={deptId ?? undefined}
+					onChange={(v?: number) => setDeptId(v ?? null)}
+				/>
+			</Space>
 			<Table
 				rowKey="id"
 				loading={usersQuery.isLoading}
-				dataSource={usersQuery.data ?? []}
+				dataSource={visibleUsers}
 				columns={columns}
 				pagination={{ hideOnSinglePage: true }}
 			/>

package/templates/src/system/web/pages/wecom/index.tsx

@@ -16,6 +16,8 @@ interface AppRow {
 	env: string
 	corp_name: string | null
 	status: "active" | "disabled"
+	/** 0=管理员授权 / 1=成员授权：成员授权下这家企业的应用做不了组织架构同步 */
+	auth_mode: number
 	installed_at: number
 	update_time: number
 }
@@ -51,7 +53,8 @@ async function createInstall(): Promise<InstallInfo> {
  * 企微代开发后台（服务商运营面，superadmin 独占）：
  *   · 已授权企业 × 应用清单（同一企业测试/正式两个应用各一行）；
  *   · 启停（停用企业最后一个应用时后端同时吊销该企业会话）；
- *   · 开通入口（预授权码 10 分钟有效，每次点都重新换）。
+ *   · 开通入口（点「生成开通链接」→ 后端调企微 get_customized_auth_url 换 qrcode_url，
+ *     企业管理员扫/开即授权，授权成功由 create_auth 回调落库）。
  */
 export default function WecomAdminPage() {
 	const { t } = useTranslation();
@@ -119,6 +122,15 @@ export default function WecomAdminPage() {
 		},
 		{ title: t("system:wecom.col.agent"), dataIndex: "agent_id" },
 		{ title: t("system:wecom.col.env"), dataIndex: "env", render: (v: string) => <Tag>{v}</Tag> },
+		{
+			// 权限三态：成员授权是「装了也同步不了」的硬约束（企微侧通讯录接口一律 60011），
+			// 摆在清单上，服务商不用点进去试一遍才知道
+			title: t("system:wecom.col.authMode"),
+			dataIndex: "auth_mode",
+			render: (v: number) => (v === 0
+				? <Tag color="green">{t("system:wecom.authModeAdmin")}</Tag>
+				: <Tag color="orange">{t("system:wecom.authModeMember")}</Tag>),
+		},
 		{
 			title: t("system:wecom.col.status"),
 			dataIndex: "status",
@@ -190,6 +202,9 @@ export default function WecomAdminPage() {
 				)}
 			</Card>
 			<Card title={t("system:wecom.appsTitle")}>
+				<Typography.Paragraph type="secondary" style={{ marginBottom: 12 }}>
+					{t("system:wecom.authModeHint")}
+				</Typography.Paragraph>
 				<Table<AppRow>
 					rowKey={row => `${row.suite_id}:${row.corp_id}:${row.agent_id}`}
 					size="small"

package/templates/tests/l1-builder.test.ts

@@ -11,7 +11,7 @@
 //   ③ notification：join ON 值条件 + UNION ALL + 字面量列 {lit,as} 的真渲染（场景 41 同款）。
 //
 // 登录账号：fixtures 的 l1tester（src/_platform/fixtures/l1-test-user.sql，仅 oj test 灌入）。
-// 不用 seed 的 admin 等开发账号：初始口令 123456 会随用户在 dev 库改密漂移——
+// 不用 seed 的 admin 等开发账号：初始口令 aA123456 会随用户在 dev 库改密漂移——
 // L1 绑 seed 账号曾实测 401。l1tester 为 additive 专用账号（must_change=0）。
 //
 // 运行：cd packages/cli/templates/api && ~/.local/share/oj/oj test -c config.yaml -d src -t tests