@oj-module/cli 0.2.47 → 0.2.49

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

@@ -0,0 +1,346 @@
+import type { SystemDepartmentsGetData, SystemDepartmentsMembersGetData } from "../../__client/api";
+
+import { PlusOutlined } from "@ant-design/icons";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import {
+	App,
+	Button,
+	Form,
+	Input,
+	Modal,
+	Popconfirm,
+	Select,
+	Space,
+	Table,
+	Tag,
+	Tree,
+	TreeSelect,
+	Typography,
+} from "antd";
+import { useMemo, useState } from "react";
+import { useTranslation } from "react-i18next";
+
+import {
+	systemDepartmentsDelete,
+	systemDepartmentsDetachPost,
+	systemDepartmentsGet,
+	systemDepartmentsMembersDelete,
+	systemDepartmentsMembersGet,
+	systemDepartmentsMembersPost,
+	systemDepartmentsMembersPut,
+	systemDepartmentsMovePut,
+	systemDepartmentsPost,
+	systemDepartmentsPut,
+	systemUsersGet,
+} from "../../__client/api";
+import { explainError, isForbidden } from "../errors";
+import { ForbiddenPanel } from "../forbidden";
+import { WecomSyncBar } from "./sync-bar";
+import { buildTreeData, subtreeIds } from "./tree";
+
+type DeptRow = SystemDepartmentsGetData[number];
+type MemberRow = SystemDepartmentsMembersGetData[number];
+
+/** 归属权 → 人话标签（local = 本站可改；其余 = 适配器管辖，改前须「转为本地维护」） */
+function originTag(origin: string, t: (k: string, opts?: { defaultValue?: string }) => string): React.ReactNode {
+	if (origin === "local")
+		return <Tag>{t("system:departments.origin.local")}</Tag>;
+	return <Tag color="blue">{t(`system:departments.origin.${origin}`, { defaultValue: origin })}</Tag>;
+}
+
+/** 部门管理页：树形增删改 + 成员维护 + 转为本地维护（D14 保底出口）。 */
+export default function DepartmentsPage() {
+	const { t } = useTranslation();
+	const { message } = App.useApp();
+	const queryClient = useQueryClient();
+
+	const [editOpen, setEditOpen] = useState(false);
+	const [editing, setEditing] = useState<DeptRow | null>(null);
+	const [form] = Form.useForm<{ name: string, nameEn?: string, parentId?: number | null, orderNo?: number }>();
+	const [memberDept, setMemberDept] = useState<DeptRow | null>(null);
+	const [addUid, setAddUid] = useState<number | null>(null);
+
+	const deptsQuery = useQuery({ queryKey: ["system", "departments"], queryFn: systemDepartmentsGet });
+	const usersQuery = useQuery({ queryKey: ["system", "users"], queryFn: systemUsersGet });
+	const membersQuery = useQuery({
+		queryKey: ["system", "departments", "members", memberDept?.id],
+		queryFn: () => systemDepartmentsMembersGet({ id: memberDept!.id }),
+		enabled: memberDept !== null,
+	});
+
+	const rows = useMemo(() => deptsQuery.data ?? [], [deptsQuery.data]);
+	const invalidateAll = () => {
+		queryClient.invalidateQueries({ queryKey: ["system", "departments"] });
+		queryClient.invalidateQueries({ queryKey: ["system", "departments", "members"] });
+	};
+	const onError = (e: unknown) => message.error(explainError(e, t));
+
+	const createMut = useMutation({
+		mutationFn: (input: { name: string, nameEn?: string | null, parentId?: number | null, orderNo?: number }) => systemDepartmentsPost(input),
+		onSuccess: () => {
+			message.success(t("system:common.saved"));
+			setEditOpen(false);
+			form.resetFields();
+			invalidateAll();
+		},
+		onError,
+	});
+
+	const updateMut = useMutation({
+		mutationFn: (input: { id: number, body: { name?: string, nameEn?: string | null, orderNo?: number } }) => systemDepartmentsPut({ query: { id: input.id }, body: input.body }),
+		onSuccess: () => {
+			message.success(t("system:common.saved"));
+			setEditOpen(false);
+			invalidateAll();
+		},
+		onError,
+	});
+
+	const moveMut = useMutation({
+		mutationFn: (input: { id: number, parentId: number | null }) => systemDepartmentsMovePut({ query: { id: input.id }, body: { parentId: input.parentId } }),
+		onSuccess: invalidateAll,
+		onError,
+	});
+
+	const deleteMut = useMutation({
+		mutationFn: (id: number) => systemDepartmentsDelete({ id }),
+		onSuccess: invalidateAll,
+		onError,
+	});
+
+	const detachMut = useMutation({
+		mutationFn: (id: number) => systemDepartmentsDetachPost({ id }),
+		onSuccess: () => {
+			message.success(t("system:common.saved"));
+			invalidateAll();
+		},
+		onError,
+	});
+
+	const addMemberMut = useMutation({
+		mutationFn: (input: { id: number, userId: number }) => systemDepartmentsMembersPost({ query: { id: input.id }, body: { userId: input.userId } }),
+		onSuccess: () => {
+			setAddUid(null);
+			invalidateAll();
+		},
+		onError,
+	});
+
+	const updateMemberMut = useMutation({
+		mutationFn: (input: { id: number, userId: number, body: { isLeader?: boolean, isMain?: boolean } }) => systemDepartmentsMembersPut({ query: { id: input.id, userId: input.userId }, body: input.body }),
+		onSuccess: invalidateAll,
+		onError,
+	});
+
+	const removeMemberMut = useMutation({
+		mutationFn: (input: { id: number, userId: number }) => systemDepartmentsMembersDelete({ id: input.id, userId: input.userId }),
+		onSuccess: invalidateAll,
+		onError,
+	});
+
+	// 父级选择器：排除自己及其子孙（选了会被后端判环 400，不如不给）
+	const parentOptions = useMemo(() => {
+		if (!editing)
+			return rows.map(d => ({ title: d.name ?? `#${d.id}`, value: d.id }));
+		const banned = subtreeIds(rows, [editing.id]);
+		return rows.filter(d => !banned.has(d.id)).map(d => ({ title: d.name ?? `#${d.id}`, value: d.id }));
+	}, [rows, editing]);
+
+	const treeData = useMemo(() => buildTreeData(rows, (d) => {
+		const editable = d.origin === "local";
+		return (
+			<Space size={4} wrap>
+				<Typography.Text strong>{d.name ?? t("system:departments.unnamed")}</Typography.Text>
+				{originTag(d.origin, t)}
+				<Typography.Text type="secondary">{`${t("system:departments.memberCount")} ${d.memberCount}`}</Typography.Text>
+				{!d.syncVisible ? <Tag color="orange">{t("system:departments.hidden")}</Tag> : null}
+				{!d.deleted ? null : <Tag color="red">{t("system:departments.removed")}</Tag>}
+				<Button
+					size="small"
+					type="link"
+					onClick={() => {
+						setEditing(d);
+						form.setFieldsValue({ name: d.name ?? "", nameEn: d.nameEn ?? undefined, parentId: d.parentId, orderNo: d.orderNo });
+						setEditOpen(true);
+					}}
+				>
+					{editable ? t("system:common.edit") : t("system:departments.view")}
+				</Button>
+				<Button
+					size="small"
+					type="link"
+					onClick={() => {
+						setMemberDept(d);
+						setAddUid(null);
+					}}
+				>
+					{t("system:departments.members")}
+				</Button>
+				{editable
+					? (
+						<Popconfirm title={t("system:departments.confirmDelete")} onConfirm={() => deleteMut.mutate(d.id)}>
+							<Button size="small" type="link" danger>{t("system:common.delete")}</Button>
+						</Popconfirm>
+					)
+					: (
+						<Popconfirm
+							title={t("system:departments.detach")}
+							description={t("system:departments.detachHint")}
+							onConfirm={() => detachMut.mutate(d.id)}
+						>
+							<Button size="small" type="link">{t("system:departments.detach")}</Button>
+						</Popconfirm>
+					)}
+			</Space>
+		);
+	}), [rows, t, form, deleteMut, detachMut]);
+
+	if (deptsQuery.error && isForbidden(deptsQuery.error))
+		return <ForbiddenPanel t={t} error={deptsQuery.error} />;
+
+	const memberColumns = [
+		{
+			title: t("system:departments.memberColumns.user"),
+			dataIndex: "username",
+			render: (_: unknown, row: MemberRow) => (row.displayName ? `${row.displayName}（${row.username}）` : row.username),
+		},
+		{
+			title: t("system:departments.memberColumns.main"),
+			dataIndex: "isMain",
+			render: (isMain: boolean, row: MemberRow) => (
+				<Popconfirm
+					title={t("system:departments.memberColumns.main")}
+					onConfirm={() => updateMemberMut.mutate({ id: row.deptId, userId: row.userId, body: { isMain: !isMain } })}
+				>
+					<Tag color={isMain ? "green" : undefined}>{isMain ? t("system:departments.yes") : t("system:departments.no")}</Tag>
+				</Popconfirm>
+			),
+		},
+		{
+			title: t("system:departments.memberColumns.leader"),
+			dataIndex: "isLeader",
+			render: (isLeader: boolean, row: MemberRow) => (
+				<Popconfirm
+					title={t("system:departments.memberColumns.leader")}
+					onConfirm={() => updateMemberMut.mutate({ id: row.deptId, userId: row.userId, body: { isLeader: !isLeader } })}
+				>
+					<Tag color={isLeader ? "blue" : undefined}>{isLeader ? t("system:departments.yes") : t("system:departments.no")}</Tag>
+				</Popconfirm>
+			),
+		},
+		{
+			title: t("system:departments.memberColumns.actions"),
+			key: "actions",
+			render: (_: unknown, row: MemberRow) => (
+				<Popconfirm
+					title={t("system:departments.confirmRemoveMember")}
+					onConfirm={() => removeMemberMut.mutate({ id: row.deptId, userId: row.userId })}
+				>
+					<Button size="small" type="link" danger>{t("system:departments.removeMember")}</Button>
+				</Popconfirm>
+			),
+		},
+	];
+
+	return (
+		<Space direction="vertical" style={{ width: "100%", paddingTop: 16 }}>
+			{/* 企微来源的组织架构：顶部常驻状态条 + 立即同步（没装企微的站点这里什么都不渲染） */}
+			<WecomSyncBar onFinished={() => queryClient.invalidateQueries({ queryKey: ["system"] })} />
+			<Space>
+				<Button
+					type="primary"
+					icon={<PlusOutlined />}
+					onClick={() => {
+						setEditing(null);
+						form.resetFields();
+						setEditOpen(true);
+					}}
+				>
+					{t("system:departments.create")}
+				</Button>
+				<Typography.Text type="secondary">{t("system:departments.createHint")}</Typography.Text>
+			</Space>
+
+			<Tree blockNode defaultExpandAll treeData={treeData} />
+
+			<Modal
+				title={editing ? t("system:departments.edit") : t("system:departments.create")}
+				open={editOpen}
+				onCancel={() => setEditOpen(false)}
+				confirmLoading={createMut.isPending || updateMut.isPending}
+				onOk={() => form.submit()}
+			>
+				<Form
+					form={form}
+					layout="vertical"
+					onFinish={(values) => {
+						const parentId = values.parentId ?? null;
+						if (!editing) {
+							createMut.mutate({ name: values.name, nameEn: values.nameEn ?? null, parentId, orderNo: values.orderNo });
+							return;
+						}
+						if (editing.origin === "local")
+							updateMut.mutate({ id: editing.id, body: { name: values.name, nameEn: values.nameEn ?? null, orderNo: values.orderNo } });
+						if (parentId !== editing.parentId)
+							moveMut.mutate({ id: editing.id, parentId });
+					}}
+				>
+					<Form.Item name="name" label={t("system:departments.columns.name")} rules={[{ required: true }]}>
+						<Input disabled={editing !== null && editing.origin !== "local"} />
+					</Form.Item>
+					<Form.Item name="nameEn" label={t("system:departments.columns.nameEn")}>
+						<Input disabled={editing !== null && editing.origin !== "local"} />
+					</Form.Item>
+					<Form.Item name="parentId" label={t("system:departments.columns.parent")}>
+						<TreeSelect allowClear treeData={parentOptions} placeholder={t("system:departments.root")} />
+					</Form.Item>
+				</Form>
+				{editing && editing.origin !== "local"
+					? (
+						<Space>
+							<Typography.Text type="secondary">{t("system:departments.readonlyHint")}</Typography.Text>
+							<Button size="small" type="link" onClick={() => detachMut.mutate(editing.id)}>
+								{t("system:departments.detach")}
+							</Button>
+						</Space>
+					)
+					: null}
+			</Modal>
+
+			<Modal
+				width={720}
+				title={`${t("system:departments.members")}：${memberDept?.name ?? ""}`}
+				open={memberDept !== null}
+				onCancel={() => setMemberDept(null)}
+				footer={null}
+			>
+				<Space style={{ marginBottom: 12 }}>
+					<Select
+						style={{ minWidth: 240 }}
+						placeholder={t("system:departments.selectUser")}
+						value={addUid ?? undefined}
+						onChange={v => setAddUid(v)}
+						options={(usersQuery.data ?? []).map(u => ({ label: u.display_name ? `${u.display_name}（${u.username}）` : u.username, value: u.id }))}
+					/>
+					<Button
+						type="primary"
+						disabled={addUid === null || !memberDept}
+						loading={addMemberMut.isPending}
+						onClick={() => memberDept && addUid !== null && addMemberMut.mutate({ id: memberDept.id, userId: addUid })}
+					>
+						{t("system:departments.addMember")}
+					</Button>
+				</Space>
+				<Table
+					rowKey="userId"
+					size="small"
+					loading={membersQuery.isLoading}
+					dataSource={membersQuery.data ?? []}
+					columns={memberColumns}
+					pagination={{ hideOnSinglePage: true }}
+					locale={{ emptyText: t("system:departments.noMembers") }}
+				/>
+			</Modal>
+		</Space>
+	);
+}

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;