@oj-module/cli 0.2.47 → 0.2.48

package/templates/src/_platform/api/_shared/service/domain/users.ts

@@ -10,11 +10,22 @@ export interface UserDeps {
 	bcryptHash: (pw: string) => Promise<string>
 }
 
+/** 用户所属的一个部门。带 id 是为了前端能按部门（含子部门）筛选——部门名会重名。 */
+export interface UserDeptRef {
+	id: number
+	/** 部门名（软删/未命名部门为 null，展示口径交给调用方） */
+	name: string | null
+	isMain: boolean
+}
+
 export interface UserRow {
 	id: number
 	username: string
 	display_name: string | null
 	email: string | null
+	position: string | null
+	/** 所属部门（主部门在前） */
+	departments: UserDeptRef[]
 	is_forbidden: boolean
 	must_change: boolean
 	roles: string[]
@@ -58,22 +69,43 @@ async function assertMembershipAllowed(actorId: number, nextRoles: string[]): Pr
 }
 
 export async function listUsers(): Promise<UserRow[]> {
-	const rows = await db.table("users").select(["id", "username", "display_name", "email", "is_forbidden", "must_change"]).orderBy([{ field: "username" }]).all() as Array<Record<string, unknown>>;
+	const rows = await db.table("users").select(["id", "username", "display_name", "email", "position", "is_forbidden", "must_change"]).orderBy([{ field: "username" }]).all() as Array<Record<string, unknown>>;
 	const roleRows = await db.table("sys_user_role").select(["user_id", "role_name"]).all() as Array<{ user_id: number, role_name: string }>;
 	const roleMap = new Map<number, string[]>();
 	for (const r of roleRows)
 		(roleMap.get(Number(r.user_id)) ?? roleMap.set(Number(r.user_id), []).get(Number(r.user_id)))!.push(r.role_name);
+	const depts = await departmentsByUser();
 	return rows.map(r => ({
 		id: Number(r.id),
 		username: String(r.username),
 		display_name: r.display_name == null ? null : String(r.display_name),
 		email: r.email == null ? null : String(r.email),
+		position: r.position == null ? null : String(r.position),
+		departments: depts.get(Number(r.id)) ?? [],
 		is_forbidden: Number(r.is_forbidden) === 1,
 		must_change: Number(r.must_change) === 1,
 		roles: roleMap.get(Number(r.id)) ?? [],
 	}));
 }
 
+/** uid → 所属部门（主部门排前）。两次查询而非 join：构造器 join 带值条件有已知缺口。 */
+async function departmentsByUser(): Promise<Map<number, UserDeptRef[]>> {
+	const memberRows = await db.table("sys_dept_member").select(["user_id", "dept_id", "is_main"]).all() as Array<{ user_id: number, dept_id: number, is_main: number }>;
+	if (!memberRows.length)
+		return new Map();
+	const deptRows = await db.table("sys_department").select(["id", "name"]).where({ field: "deleted", op: "eq", value: 0 }).all() as Array<{ id: number, name: string | null }>;
+	const nameOf = new Map(deptRows.map(d => [Number(d.id), d.name == null ? null : String(d.name)]));
+	const out = new Map<number, UserDeptRef[]>();
+	// 主部门先落：is_main=1 的行先排一遍，其余后追加
+	const ordered = [...memberRows].sort((a, b) => Number(b.is_main ?? 0) - Number(a.is_main ?? 0));
+	for (const m of ordered) {
+		const uid = Number(m.user_id);
+		const id = Number(m.dept_id);
+		(out.get(uid) ?? out.set(uid, []).get(uid)!).push({ id, name: nameOf.get(id) ?? null, isMain: Number(m.is_main ?? 0) === 1 });
+	}
+	return out;
+}
+
 /** B6：建号——拒外来号前缀、口令 ≥6、默认 must_change=1。返回新用户 id。 */
 export async function createUser(input: { username: string, password: string, displayName?: string, email?: string }, deps: UserDeps): Promise<number> {
 	const username = String(input.username ?? "").trim();
@@ -87,12 +119,64 @@ export async function createUser(input: { username: string, password: string, di
 	if (exists.length)
 		fail(400, "username exists");
 	const hash = await deps.bcryptHash(String(input.password));
-	const rows = await db.table("users").insert({ username, password_hash: hash, display_name: input.displayName ?? null, email: input.email ?? null, must_change: 1 }).returning(["id"]).run() as Array<{ id: number }>;
+	// activated=1：管理员建号是「明确要这个人」的动作，立刻进通讯录目录。
+	// 与同步建档相反——同步会把全企业名册灌进来，那批号必须等真人登录才算 activated（见 contacts.ts 门禁）。
+	const rows = await db.table("users").insert({ username, password_hash: hash, display_name: input.displayName ?? null, email: input.email ?? null, must_change: 1, activated: 1 }).returning(["id"]).run() as Array<{ id: number }>;
 	const uid = Number(rows[0].id);
 	await recordOp({ action: "user.create", module: "framework", target: username });
 	return uid;
 }
 
+/**
+ * 外部源（企微 / LDAP）同步建档：按用户名 find-or-create，返回 uid。
+ *
+ * 与 `createUser` 的三处刻意差异：
+ *   1. **activated=0**：同步灌进来的是「目录档」，要等真人登录过才算活人（§9.1，否则
+ *      contacts 会被一次同步放大成整份企业名册）；
+ *   2. 不写审计：按部门批量建号，逐条审计会把 sys_oplog 打爆（同步入口自己记一条总量）；
+ *   3. 归属权（D13）：已存在行的 `source` 与本次来源不同（管理员已「转为本地维护」）→
+ *      只回 id，**一个字段都不改**，改名/改职务都归本地管。
+ *
+ * 口令哈希仍用 `!<source>` 占位（与 `!wecom` / `!ldap` 同义：任何口令都验不过）。
+ */
+export async function upsertSourceUser(input: { username: string, displayName?: string | null, source: string, corpId?: string | null }): Promise<number> {
+	const username = String(input.username ?? "").trim();
+	if (!username)
+		fail(400, "username required");
+	const rows = await db.table("users").select(["id", "source"]).where({ field: "username", op: "eq", value: username }).all() as Array<{ id: number, source: string | null }>;
+	if (rows.length) {
+		const row = rows[0]!;
+		const name = input.displayName?.trim();
+		// 同步只改自己拥有的行：名字变了（改名/补上真名）就更新，其余字段（职务/状态）由调用方另写
+		if (name && String(row.source ?? "") === input.source)
+			await db.table("users").update({ display_name: name }).where({ field: "id", op: "eq", value: Number(row.id) }).run();
+		return Number(row.id);
+	}
+	try {
+		const inserted = await db.table("users").insert({
+			username,
+			display_name: input.displayName?.trim() || username,
+			password_hash: `!${input.source}`,
+			avatar_base64: "",
+			source: input.source,
+			corp_id: input.corpId ?? null,
+			must_change: 0,
+			is_forbidden: 0,
+			activated: 0,
+		}).returning(["id"]).run() as Array<{ id: number }>;
+		return Number(inserted[0]!.id);
+	}
+	catch (e) {
+		// 并发（两片撞同一人 / 两个部门同时处理）唯一约束兜底：回查复用，同 saveProfile 先例
+		if (!/unique|constraint/i.test(e instanceof Error ? e.message : String(e)))
+			throw e;
+		const again = await db.table("users").select(["id"]).where({ field: "username", op: "eq", value: username }).all() as Array<{ id: number }>;
+		if (!again.length)
+			throw e;
+		return Number(again[0]!.id);
+	}
+}
+
 /** AC1-7：整集替换角色（sys_user_role 权威源），写后失效持有者判权缓存。 */
 export async function updateUserRoles(actorId: number, targetUid: number, roles: string[]): Promise<void> {
 	assertNotSelf(actorId, targetUid);
@@ -161,3 +245,57 @@ export async function setForbidden(actorId: number, targetUid: number, forbidden
 	invalidateUser(Number(targetUid));
 	await recordOp({ action: "user.forbidden.update", module: "framework", target: await usernameOf(Number(targetUid)), detail: { forbidden } });
 }
+
+/**
+ * 改资料（基线 CRUD 的用户侧）。
+ *
+ * 只放行与来源无关的展示字段（displayName / email / position）——用户名即外部身份的主键
+ * （`wecom:<userid>` 这类），改名会让下一次登录认错人（B6 命名空间抢占，见
+ * RESERVED_USERNAME_PREFIX）。`is_forbidden` 走 setForbidden、口令走 changePasswordByAdmin，
+ * 都不在这里——它们是带副作用的动作（级联删 refresh），混进通用 PATCH 会让「改个邮箱」也强退。
+ */
+export async function updateUserProfile(actorId: number, targetUid: number, patch: { displayName?: string | null, email?: string | null, position?: string | null }): Promise<void> {
+	const rows = await db.table("users").select(["id"]).where({ field: "id", op: "eq", value: targetUid }).all();
+	if (!rows.length)
+		fail(404, "user not found");
+	const cols: Record<string, unknown> = {};
+	if (patch.displayName !== undefined)
+		cols.display_name = patch.displayName == null ? null : String(patch.displayName).trim() || null;
+	if (patch.email !== undefined)
+		cols.email = patch.email == null ? null : String(patch.email).trim() || null;
+	if (patch.position !== undefined)
+		cols.position = patch.position == null ? null : String(patch.position).trim() || null;
+	if (!Object.keys(cols).length)
+		return;
+	await db.table("users").update(cols).where({ field: "id", op: "eq", value: targetUid }).run();
+	await recordOp({ action: "user.profile.update", module: "framework", target: await usernameOf(Number(targetUid)), detail: { fields: Object.keys(cols), actor: Number(actorId) } });
+}
+
+/**
+ * 删用户（基线 CRUD）。
+ *
+ * 级联清单是手工维护的——这些表都是逻辑外键（无 FK 约束），漏清任何一张都会留下
+ * 指向已删用户的悬空行：`sys_dept_member`（部门成员）/ `sys_user_role`（角色）
+ * / `sys_refresh_token`（会话）。删完立即失效判权缓存，否则被删者手上的 token
+ * 还能用满一个 TTL。
+ */
+export async function deleteUser(actorId: number, targetUid: number): Promise<void> {
+	assertNotSelf(actorId, targetUid);
+	const rows = await db.table("users").select(["id", "username"]).where({ field: "id", op: "eq", value: targetUid }).all() as Array<{ id: number, username: string }>;
+	if (!rows.length)
+		fail(404, "user not found");
+	const roles = await rolesOf(Number(targetUid));
+	if (roles.includes("superadmin")) {
+		const supers = await db.table("sys_user_role").select([{ fn: "count", as: "c" }]).where({ field: "role_name", op: "eq", value: "superadmin" }).all() as Array<{ c: number }>;
+		if (Number(supers[0]?.c ?? 0) <= 1)
+			fail(400, "cannot delete the last superadmin");
+	}
+	await db.tx(async (t) => {
+		await t.table("sys_dept_member").where({ field: "user_id", op: "eq", value: targetUid }).delete().run();
+		await t.table("sys_user_role").where({ field: "user_id", op: "eq", value: targetUid }).delete().run();
+		await t.table("sys_refresh_token").where({ field: "user_id", op: "eq", value: targetUid }).delete().run();
+		await t.table("users").where({ field: "id", op: "eq", value: targetUid }).delete().run();
+	});
+	invalidateUser(Number(targetUid));
+	await recordOp({ action: "user.delete", module: "framework", target: String(rows[0]!.username) });
+}

package/templates/src/_platform/api/_shared/service/infra/query.ts

@@ -15,7 +15,8 @@ export interface PageResult<T> {
 const MAX_SIZE = 200;
 const DEFAULT_SIZE = 20;
 
-function pageArgs(input: { page?: unknown, size?: unknown }): { page: number, size: number, offset: number } {
+/** 分页参数归一（非法回落默认，size 静默钳 200）；导给「内存分页」的读面复用，避免钳制口径分叉 */
+export function pageArgs(input: { page?: unknown, size?: unknown }): { page: number, size: number, offset: number } {
 	const rawPage = Number.parseInt(String(input.page ?? ""), 10);
 	const rawSize = Number.parseInt(String(input.size ?? ""), 10);
 	const page = Number.isFinite(rawPage) && rawPage >= 1 ? rawPage : 1;

package/templates/src/_platform/api/fixtures/l1-test-user.sql

@@ -1,7 +1,7 @@
 -- L1 测试账号（仅 `oj test` 经 fixtures 灌入，不进 release 产物）。
 --
 -- 为什么不能用 seed 的开发账号（admin/superadmin 等）跑 L1 登录：
---   ① seed 账号初始口令 123456 只是开发便利——用户在 dev 库改过口令后，口令即漂移，
+--   ① seed 账号初始口令 aA123456 只是开发便利——用户在 dev 库改过口令后，口令即漂移，
 --      L1 若绑 seed 账号会随机 401（本地实测踩过：dev 库口令被改成 12345678）。
 --   ② 不用 must_change 解释：seed 账号现均为 0（2026-10-22 口径）；真正的原因是 ①。
 -- 故 additive 建一个专用账号：INSERT OR IGNORE 幂等，反复重放终态一致，

package/templates/src/_platform/api/manifest.yaml

@@ -16,3 +16,6 @@ tables:
   - sys_rate_window
   - sys_login_throttle
   - reg_source_seq
+  # 0016 组织架构领域（CRUD 基线 + 外部源适配器的落点；两张都是租户表）
+  - sys_department
+  - sys_dept_member

package/templates/src/_platform/api/migrations/0016__org.mysql.sql

@@ -0,0 +1,41 @@
+-- 0016__org（mysql 方言）：组织架构领域。表定性与列语义同 0016__org.sql 头注释。
+-- 差异（沿用 0001__create_users.mysql.sql / 0015__tenant.mysql.sql 的既有惯例）：
+--   · TEXT 不能带字面默认值、不能直接做唯一键 → 键列按业务长度收窄为 VARCHAR；
+--   · AUTOINCREMENT → BIGINT AUTO_INCREMENT；秒级 epoch 的 INTEGER → BIGINT；
+--   · 索引写在 CREATE TABLE 内（MySQL 无 CREATE INDEX IF NOT EXISTS）；
+--   · 复合唯一键 (tenant_id, origin, origin_id) = (255+32+128) × 4B = 1660B < InnoDB 3072B 上限。
+CREATE TABLE IF NOT EXISTS sys_department (
+  id BIGINT AUTO_INCREMENT PRIMARY KEY,
+  tenant_id VARCHAR(255) NOT NULL,
+  origin VARCHAR(32) NOT NULL DEFAULT 'local',
+  origin_id VARCHAR(128) NOT NULL,
+  parent_id BIGINT NULL,
+  name VARCHAR(255),
+  name_en VARCHAR(255),
+  order_no INTEGER NOT NULL DEFAULT 0,
+  sync_visible INTEGER NOT NULL DEFAULT 1,
+  deleted INTEGER NOT NULL DEFAULT 0,
+  seen_job_id BIGINT,
+  update_time BIGINT NOT NULL,
+  UNIQUE KEY uk_sys_department_origin (tenant_id, origin, origin_id),
+  KEY idx_sys_department_parent (tenant_id, parent_id, deleted, order_no)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+CREATE TABLE IF NOT EXISTS sys_dept_member (
+  id BIGINT AUTO_INCREMENT PRIMARY KEY,
+  tenant_id VARCHAR(255) NOT NULL,
+  user_id BIGINT NOT NULL,
+  dept_id BIGINT NOT NULL,
+  order_no INTEGER NOT NULL DEFAULT 0,
+  is_leader INTEGER NOT NULL DEFAULT 0,
+  is_main INTEGER NOT NULL DEFAULT 0,
+  update_time BIGINT NOT NULL,
+  UNIQUE KEY uk_sys_dept_member (tenant_id, user_id, dept_id),
+  KEY idx_sys_dept_member_dept (tenant_id, dept_id, order_no),
+  KEY idx_sys_dept_member_user (tenant_id, user_id, is_main)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+ALTER TABLE users ADD COLUMN activated INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE users ADD COLUMN position VARCHAR(255) NULL;
+ALTER TABLE users ADD COLUMN external_status INTEGER NULL;
+UPDATE users SET activated = 1;

package/templates/src/_platform/api/migrations/0016__org.pg.sql

@@ -0,0 +1,40 @@
+-- 0016__org（postgres 方言）：组织架构领域。表定性与列语义同 0016__org.sql 头注释。
+-- 差异（沿用 0001__create_users.pg.sql 的既有惯例）：
+--   · AUTOINCREMENT → BIGSERIAL（SERIAL 系允许 seed 显式 id，GENERATED ALWAYS 系不允许）；
+--   · TEXT 在 pg 合法，键列与文本列一律保留 TEXT，无需收窄；
+--   · 秒级 epoch 的 INTEGER → BIGINT。
+CREATE TABLE IF NOT EXISTS sys_department (
+  id BIGSERIAL PRIMARY KEY,
+  tenant_id TEXT NOT NULL,
+  origin TEXT NOT NULL DEFAULT 'local',
+  origin_id TEXT NOT NULL,
+  parent_id BIGINT,
+  name TEXT,
+  name_en TEXT,
+  order_no INTEGER NOT NULL DEFAULT 0,
+  sync_visible INTEGER NOT NULL DEFAULT 1,
+  deleted INTEGER NOT NULL DEFAULT 0,
+  seen_job_id BIGINT,
+  update_time BIGINT NOT NULL,
+  UNIQUE (tenant_id, origin, origin_id)
+);
+CREATE INDEX IF NOT EXISTS idx_sys_department_parent ON sys_department (tenant_id, parent_id, deleted, order_no);
+
+CREATE TABLE IF NOT EXISTS sys_dept_member (
+  id BIGSERIAL PRIMARY KEY,
+  tenant_id TEXT NOT NULL,
+  user_id BIGINT NOT NULL,
+  dept_id BIGINT NOT NULL,
+  order_no INTEGER NOT NULL DEFAULT 0,
+  is_leader INTEGER NOT NULL DEFAULT 0,
+  is_main INTEGER NOT NULL DEFAULT 0,
+  update_time BIGINT NOT NULL,
+  UNIQUE (tenant_id, user_id, dept_id)
+);
+CREATE INDEX IF NOT EXISTS idx_sys_dept_member_dept ON sys_dept_member (tenant_id, dept_id, order_no);
+CREATE INDEX IF NOT EXISTS idx_sys_dept_member_user ON sys_dept_member (tenant_id, user_id, is_main);
+
+ALTER TABLE users ADD COLUMN activated INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE users ADD COLUMN position TEXT;
+ALTER TABLE users ADD COLUMN external_status INTEGER;
+UPDATE users SET activated = 1;

package/templates/src/_platform/api/migrations/0016__org.sql

@@ -0,0 +1,62 @@
+-- 0016__org（sqlite 方言）：组织架构领域（CRUD 基线 + 外部源适配器的落点）
+--
+-- 两张表都是**租户表**（tenant: true）：组织架构天然按租户隔离（企微部署下 tenant_id = corp_id），
+-- 只在有租户上下文时被读写，与 users / sys_oplog 同组（0015 A 组口径）。
+-- 故**不**进 config.yaml 的 tenant.shared_allow——那里只放全局映射/凭证。
+--
+-- 定位（方案 §14：CRUD 是基线，企微 / LDAP 只是适配器）：
+--   · 表里不出现任何 wecom_* / ldap_* 字段，来源只由 origin 表达；
+--   · origin 是**归属权**标识（D13）：local = 本站管理员全权可 CRUD；
+--     wecom / ldap / sso = 该适配器管辖，同步与回收只作用于自己 origin 的行。
+--
+-- 列的来源语义：
+--   origin_id     外部源主键（企微部门 id / LDAP entryUUID）；origin='local' 时由应用层生成稳定串
+--   parent_id     本地父部门 id（不是外部 id）——本地部门与同步部门可混挂，且不随外部调整而变
+--   name          未获权限时为 NULL（企微代开发未授权「部门名」即如此），展示层用 origin_id 兜底
+--   sync_visible  同步可见性，**仅由同步轮次维护**（失去可见范围 → 0），本地部门恒 1
+--   deleted       软删除。**只由外部源的删除事件置 1**（D9）：本地删除走真删，见 §14.4-②
+--   seen_job_id   最近一次完整全量命中的 job，用于墓碑回收（回收前必先校验本轮完整且无 skip）
+CREATE TABLE IF NOT EXISTS sys_department (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  tenant_id TEXT NOT NULL,
+  origin TEXT NOT NULL DEFAULT 'local',
+  origin_id TEXT NOT NULL,
+  parent_id INTEGER,
+  name TEXT,
+  name_en TEXT,
+  order_no INTEGER NOT NULL DEFAULT 0,
+  sync_visible INTEGER NOT NULL DEFAULT 1,
+  deleted INTEGER NOT NULL DEFAULT 0,
+  seen_job_id INTEGER,
+  update_time INTEGER NOT NULL,
+  UNIQUE (tenant_id, origin, origin_id)
+);
+CREATE INDEX IF NOT EXISTS idx_sys_department_parent ON sys_department (tenant_id, parent_id, deleted, order_no);
+
+-- 成员 ↔ 部门（多对多）：企微一个人可在多个部门，order / is_leader 与 department[] 逐位对应。
+-- 全本地 id 关联（user_id + dept_id），**与来源完全无关**，接任何适配器都不用改这张表。
+CREATE TABLE IF NOT EXISTS sys_dept_member (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  tenant_id TEXT NOT NULL,
+  user_id INTEGER NOT NULL,
+  dept_id INTEGER NOT NULL,
+  order_no INTEGER NOT NULL DEFAULT 0,
+  is_leader INTEGER NOT NULL DEFAULT 0,
+  is_main INTEGER NOT NULL DEFAULT 0,
+  update_time INTEGER NOT NULL,
+  UNIQUE (tenant_id, user_id, dept_id)
+);
+CREATE INDEX IF NOT EXISTS idx_sys_dept_member_dept ON sys_dept_member (tenant_id, dept_id, order_no);
+CREATE INDEX IF NOT EXISTS idx_sys_dept_member_user ON sys_dept_member (tenant_id, user_id, is_main);
+
+-- users 扩列（三列都是与源无关的通用字段）
+--   activated        是否登录过本站。同步会为「从未登录」的全员建档，若不加这道闸门，
+--                    contacts 目录（60 次/分、keyword≥2）可被用来遍历拖走整份企业名册（§9.1）
+--   position         职务（本地 / LDAP / 企微都能填）
+--   external_status  外部源侧的状态快照（企微 1/2/4/5）。**绝不自动改写 is_forbidden**——
+--                    那会和本站管理员的手动启停互相覆盖（§4.3）
+ALTER TABLE users ADD COLUMN activated INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE users ADD COLUMN position TEXT;
+ALTER TABLE users ADD COLUMN external_status INTEGER;
+-- 存量账号一律视为已激活：保持 contacts 的既有行为不变（它此前本就返回全部 users）
+UPDATE users SET activated = 1;

package/templates/src/_platform/api/org/departments/api.ts

@@ -0,0 +1,51 @@
+import { respond } from "../../_shared/respond";
+// GET /api/_platform/org/departments —— 部门平铺分页（共享读面）。
+// 与 /org/tree 的差别在**分页与过滤**：大企业别一次拉全树，按 parent / keyword 分片取。
+// parent=0 表示只要根层；不给 parent 即跨层全查（仍受 scope 收窄）。
+import { pageDepartments, resolveReadFace } from "../../_shared/service/domain/org-read";
+
+const DEPT_ITEM = {
+	type: "object",
+	required: ["id", "parentId", "name", "orderNo", "memberCount"],
+	properties: {
+		id: { type: "number" },
+		parentId: { type: ["number", "null"] },
+		name: { type: ["string", "null"] },
+		nameEn: { type: ["string", "null"] },
+		orderNo: { type: "number" },
+		memberCount: { type: "number" },
+	},
+} as const;
+
+async function get() {
+	await respond(async () => {
+		const q = http.query as Record<string, unknown>;
+		const reader = await resolveReadFace(q.scope);
+		return pageDepartments(reader, { parent: q.parent, keyword: q.keyword, page: q.page, size: q.size });
+	});
+}
+get.schema = {
+	query: {
+		type: "object",
+		properties: {
+			scope: { type: "string", enum: ["self", "all"] },
+			parent: { type: "number" },
+			keyword: { type: "string" },
+			page: { type: "number", minimum: 1 },
+			size: { type: "number", minimum: 1, maximum: 200 },
+		},
+	},
+};
+get.response = {
+	type: "object",
+	required: ["list", "total", "page", "size", "truncated"],
+	properties: {
+		list: { type: "array", items: DEPT_ITEM },
+		total: { type: "number" },
+		page: { type: "number" },
+		size: { type: "number" },
+		truncated: { type: "boolean" },
+	},
+};
+
+export default { get };

package/templates/src/_platform/api/org/is-member/api.ts

@@ -0,0 +1,33 @@
+import { respond } from "../../_shared/respond";
+// GET /api/_platform/org/is-member?uid=&dept= —— 某人是否在某部门（**含子部门**）下。
+// 第二个「算」型端点：按部门做访问控制/路由时，调用方不该自己去拉树递归。
+// scope=self 下只能问自己（问别人 → 403）。
+import { isMemberOf, resolveReadFace } from "../../_shared/service/domain/org-read";
+
+async function get() {
+	await respond(async () => {
+		const q = http.query as Record<string, unknown>;
+		const reader = await resolveReadFace(q.scope);
+		const uid = q.uid == null || String(q.uid).trim() === "" ? reader.uid : Number(q.uid);
+		return { isMember: await isMemberOf(reader, uid, Number(q.dept)) };
+	});
+}
+get.schema = {
+	query: {
+		type: "object",
+		required: ["dept"],
+		properties: {
+			scope: { type: "string", enum: ["self", "all"] },
+			// 不给 uid 即问自己
+			uid: { type: "number" },
+			dept: { type: "number" },
+		},
+	},
+};
+get.response = {
+	type: "object",
+	required: ["isMember"],
+	properties: { isMember: { type: "boolean" } },
+};
+
+export default { get };

package/templates/src/_platform/api/org/members/api.ts

@@ -0,0 +1,55 @@
+import { respond } from "../../_shared/respond";
+// GET /api/_platform/org/members —— 部门成员 + 部门路径（共享读面）。
+// 不给 dept 即查可见范围内的全部成员（配 keyword 用）。
+// ⚡ includeSub 在 scope=self 下只对「我所在部门」生效：对上级部门一展开就是整棵子树，
+// 那等于绕过自身路径的限制，所以宁可 400 也不静默截断（见 org-read.ts 头注）。
+import { pageMembers, resolveReadFace } from "../../_shared/service/domain/org-read";
+
+const MEMBER_ITEM = {
+	type: "object",
+	required: ["userId", "username", "deptId", "deptPath", "isMain"],
+	properties: {
+		userId: { type: "number" },
+		username: { type: "string" },
+		displayName: { type: ["string", "null"] },
+		deptId: { type: "number" },
+		// 根在前的部门名路径（部门名缺失时退 `#id`）
+		deptPath: { type: "array", items: { type: "string" } },
+		isMain: { type: "boolean" },
+	},
+} as const;
+
+async function get() {
+	await respond(async () => {
+		const q = http.query as Record<string, unknown>;
+		const reader = await resolveReadFace(q.scope);
+		return pageMembers(reader, { dept: q.dept, includeSub: q.includeSub, keyword: q.keyword, page: q.page, size: q.size });
+	});
+}
+get.schema = {
+	query: {
+		type: "object",
+		properties: {
+			scope: { type: "string", enum: ["self", "all"] },
+			dept: { type: "number" },
+			// 查询串是字符串：`true` / `1` 视为展开子部门
+			includeSub: { type: "string" },
+			keyword: { type: "string" },
+			page: { type: "number", minimum: 1 },
+			size: { type: "number", minimum: 1, maximum: 200 },
+		},
+	},
+};
+get.response = {
+	type: "object",
+	required: ["list", "total", "page", "size", "truncated"],
+	properties: {
+		list: { type: "array", items: MEMBER_ITEM },
+		total: { type: "number" },
+		page: { type: "number" },
+		size: { type: "number" },
+		truncated: { type: "boolean" },
+	},
+};
+
+export default { get };

package/templates/src/_platform/api/org/picker/api.ts

@@ -0,0 +1,59 @@
+import { respond } from "../../_shared/respond";
+// GET /api/_platform/org/picker?keyword= —— 人 + 部门混合（选人组件一次拿全）。
+// ⚡ keyword 必填且 ≥2：选人组件是**枚举面**（拿单字能把整份名册拖走），与通讯录同一条红线。
+import { readPicker, resolveReadFace } from "../../_shared/service/domain/org-read";
+
+const DEPT_ITEM = {
+	type: "object",
+	required: ["id", "parentId", "name", "orderNo", "memberCount"],
+	properties: {
+		id: { type: "number" },
+		parentId: { type: ["number", "null"] },
+		name: { type: ["string", "null"] },
+		nameEn: { type: ["string", "null"] },
+		orderNo: { type: "number" },
+		memberCount: { type: "number" },
+	},
+} as const;
+
+const USER_ITEM = {
+	type: "object",
+	required: ["userId", "username", "deptId", "deptPath", "isMain"],
+	properties: {
+		userId: { type: "number" },
+		username: { type: "string" },
+		displayName: { type: ["string", "null"] },
+		deptId: { type: "number" },
+		deptPath: { type: "array", items: { type: "string" } },
+		isMain: { type: "boolean" },
+	},
+} as const;
+
+async function get() {
+	await respond(async () => {
+		const q = http.query as Record<string, unknown>;
+		const reader = await resolveReadFace(q.scope);
+		return readPicker(reader, { keyword: q.keyword, limit: q.limit });
+	});
+}
+get.schema = {
+	query: {
+		type: "object",
+		required: ["keyword"],
+		properties: {
+			scope: { type: "string", enum: ["self", "all"] },
+			keyword: { type: "string", minLength: 2 },
+			limit: { type: "number", minimum: 1, maximum: 50 },
+		},
+	},
+};
+get.response = {
+	type: "object",
+	required: ["departments", "users"],
+	properties: {
+		departments: { type: "array", items: DEPT_ITEM },
+		users: { type: "array", items: USER_ITEM },
+	},
+};
+
+export default { get };

package/templates/src/_platform/api/org/resolve/api.ts

@@ -0,0 +1,38 @@
+import { respond } from "../../_shared/respond";
+// POST /api/_platform/org/resolve —— 把「部门（含子部门）」展开成 user_id 列表。
+//
+// ⚡ 这是共享读面**真正的价值**：需求方要的是「算」不是「看」。缺了它，每个消费模块都会自己
+// 把树拉下来递归，共享名存实亡（方案 §5.2）。典型用法：通知/审批按「某部门及其下级」定收件人。
+//
+// 结果去重升序，可直接当收件人集合用；显式传的 userIds 原样并入（再去重）。
+import { resolveReadFace, resolveUserIds } from "../../_shared/service/domain/org-read";
+
+async function post() {
+	await respond(async () => {
+		const q = http.query as Record<string, unknown>;
+		const reader = await resolveReadFace(q.scope);
+		const b = (http.body || {}) as { deptIds?: unknown, userIds?: unknown, includeSub?: boolean };
+		return { userIds: await resolveUserIds(reader, { deptIds: b.deptIds, userIds: b.userIds, includeSub: b.includeSub }) };
+	});
+}
+post.schema = {
+	query: {
+		type: "object",
+		properties: { scope: { type: "string", enum: ["self", "all"] } },
+	},
+	body: {
+		type: "object",
+		properties: {
+			deptIds: { type: "array", items: { type: "number" } },
+			userIds: { type: "array", items: { type: "number" } },
+			includeSub: { type: "boolean" },
+		},
+	},
+};
+post.response = {
+	type: "object",
+	required: ["userIds"],
+	properties: { userIds: { type: "array", items: { type: "number" } } },
+};
+
+export default { post };

package/templates/src/_platform/api/org/tree/api.ts

@@ -0,0 +1,37 @@
+import { respond } from "../../_shared/respond";
+// GET /api/_platform/org/tree —— 部门树（共享读面，方案 A3 / §5.2）。
+//
+// **返回平表而不是嵌套树**：oj 的契约 IR 不支持递归 schema（无 $ref），嵌套深度写不进契约；
+// 树由前端按 parentId 组装（与管理端 /api/system/departments 同口径）。
+//
+// 本端点只出「活着且同步可见」的部门（软删与失去可见范围的行不出）——那是管理端的事。
+import { readTree, resolveReadFace } from "../../_shared/service/domain/org-read";
+
+const DEPT_ITEM = {
+	type: "object",
+	required: ["id", "parentId", "name", "orderNo", "memberCount"],
+	properties: {
+		id: { type: "number" },
+		parentId: { type: ["number", "null"] },
+		name: { type: ["string", "null"] },
+		nameEn: { type: ["string", "null"] },
+		orderNo: { type: "number" },
+		memberCount: { type: "number" },
+	},
+} as const;
+
+async function get() {
+	await respond(async () => {
+		const reader = await resolveReadFace((http.query as Record<string, unknown>).scope);
+		return readTree(reader);
+	});
+}
+get.schema = {
+	query: {
+		type: "object",
+		properties: { scope: { type: "string", enum: ["self", "all"] } },
+	},
+};
+get.response = { type: "array", items: DEPT_ITEM };
+
+export default { get };