@oj-module/cli 0.2.53 → 0.2.56

package/templates/src/{_platform/api → app/api/_platform}/_shared/service/domain/users.ts

@@ -1,5 +1,6 @@
 // 账号管理应用服务（管理域 /api/system/users，AC1-7~10 + B6 建号加固）。
 // 红线：admin 不碰 superadmin/admin 成员资格（AC1-8，service 按 actor 角色自查）；
+// 只有 superadmin 能改 superadmin 账号（口令/启停/资料/删除/角色，见 assertCanManageTarget）；
 // 禁止操作自己（AC1-10 注）；最后 superadmin 兜底（服务端二次防线）；
 // 角色唯一权威源 sys_user_role + 写时失效（AC1-7/D10）；禁用/重置口令级联删 refresh（§3.1）。
 // bcrypt 经注入（Node 侧全局不可 stub，同 session.ts 约定）。
@@ -59,6 +60,27 @@ function assertNotSelf(actorId: number, targetUid: number): void {
 		fail(400, "cannot operate on yourself");
 }
 
+/**
+ * 红线（RBAC 保护红线）：只有 superadmin 能改 superadmin。
+ *
+ * 与 `assertMembershipAllowed` 的分工：那条按**被授予的角色**管提权方向（谁能任命 admin /
+ * superadmin），这条按**目标账号当前的角色**管反向——谁能动一个已经是 superadmin 的号。
+ * 缺了它，同一租户的 admin 可以：重置 superadmin 口令（知道口令即接管账号，而 superadmin
+ * 是平台级、能跨租户）／把人禁用／把角色整集清空——后者连 `assertMembershipAllowed`
+ * 都拦不住（`next` 里没有 admin/superadmin 时它直接放行）。故口令/启停/资料/删除/角色
+ * 五条写路径统一走这里。
+ *
+ * 读角色走 `rolesOf()`，与写入同受请求租户注入约束：只能影响本租户的人。
+ */
+async function assertCanManageTarget(actorId: number, targetUid: number): Promise<void> {
+	const targetRoles = await rolesOf(Number(targetUid));
+	if (!targetRoles.includes("superadmin"))
+		return;
+	if ((await rolesOf(Number(actorId))).includes("superadmin"))
+		return;
+	fail(403, "modifying a superadmin requires superadmin");
+}
+
 /**
  * AC1-8（已修订）：成员资格提权守卫——按**被授予的角色**分层，不再一刀切。
  *
@@ -200,6 +222,7 @@ export async function updateUserRoles(actorId: number, targetUid: number, roles:
 	const target = await db.table("users").select(["id"]).where({ field: "id", op: "eq", value: targetUid }).all();
 	if (!target.length)
 		fail(404, "user not found");
+	await assertCanManageTarget(actorId, targetUid);
 	const next = [...new Set(roles.map(String))];
 	if (next.length) {
 		const known = await db.table("sys_role").select(["name"]).where({ field: "name", op: "in", value: next }).all();
@@ -258,6 +281,7 @@ export async function changePasswordByAdmin(actorId: number, targetUid: number,
 	const rows = await db.table("users").select(["id"]).where({ field: "id", op: "eq", value: targetUid }).all();
 	if (!rows.length)
 		fail(404, "user not found");
+	await assertCanManageTarget(actorId, targetUid);
 	const hash = await deps.bcryptHash(String(newPassword));
 	await db.tx(async (t) => {
 		await t.table("users").update({ password_hash: hash, must_change: 1 }).where({ field: "id", op: "eq", value: targetUid }).run();
@@ -273,6 +297,7 @@ export async function setForbidden(actorId: number, targetUid: number, forbidden
 	const rows = await db.table("users").select(["id"]).where({ field: "id", op: "eq", value: targetUid }).all();
 	if (!rows.length)
 		fail(404, "user not found");
+	await assertCanManageTarget(actorId, targetUid);
 	await db.tx(async (t) => {
 		await t.table("users").update({ is_forbidden: forbidden ? 1 : 0 }).where({ field: "id", op: "eq", value: targetUid }).run();
 		if (forbidden)
@@ -294,6 +319,7 @@ export async function updateUserProfile(actorId: number, targetUid: number, patc
 	const rows = await db.table("users").select(["id"]).where({ field: "id", op: "eq", value: targetUid }).all();
 	if (!rows.length)
 		fail(404, "user not found");
+	await assertCanManageTarget(actorId, targetUid);
 	const cols: Record<string, unknown> = {};
 	if (patch.displayName !== undefined)
 		cols.display_name = patch.displayName == null ? null : String(patch.displayName).trim() || null;
@@ -320,6 +346,7 @@ export async function deleteUser(actorId: number, targetUid: number): Promise<vo
 	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");
+	await assertCanManageTarget(actorId, targetUid);
 	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 }>;

package/templates/src/{_platform/api → app/api/_platform}/_shared/service/infra/oplog.ts

@@ -21,7 +21,7 @@ export interface OplogPage {
 	truncated: boolean
 }
 
-export async function searchOplog(filter: { action?: unknown, username?: unknown, module?: unknown, limit?: unknown }): Promise<OplogPage> {
+export async function searchOplog(filter: { action?: unknown, username?: unknown, module?: unknown, page?: unknown, limit?: unknown }): Promise<OplogPage> {
 	// 构造器（v0.1.82）：可选过滤走 whereIf，条件写一份（mk 工厂），count + list 复用；
 	// username 走语义 op contains（引擎转义 %/_/!，等价旧 LIKE ? ESCAPE '!' 的 %kw%）。
 	// 照抄口径：devkit scenarios 场景 42 ④。
@@ -35,6 +35,8 @@ export async function searchOplog(filter: { action?: unknown, username?: unknown
 		.whereIf(action, { field: "action", op: "eq", value: action })
 		.whereIf(module, { field: "module", op: "eq", value: module })
 		.whereIf(username, { field: "username", op: "contains", value: username });
-	const r = await pagedFactory<OplogRow>(mk, { size: filter.limit });
+	// page/limit 成对：limit 是每页条数（pageArgs 钳 200），缺省第 1 页 / 20 条。
+	// total 由 count 查询单独给出，页面按 total 算页数——不再靠 truncated 提示「结果被截断」。
+	const r = await pagedFactory<OplogRow>(mk, { page: filter.page, size: filter.limit });
 	return { list: r.list, total: r.total, truncated: r.truncated };
 }

package/templates/src/{_platform/api → app/api/_platform}/contacts/api.ts

@@ -6,7 +6,7 @@ import { searchContacts } from "../_shared/service/domain/contacts";
 import { assertTenantSelf } from "../_shared/service/infra/access";
 import { rateLimit } from "../_shared/service/infra/rate";
 
-export default {
+const handler = {
 	// GET /api/_platform/contacts?keyword=&limit= —— 人员目录（AC1-22~24）。
 	async get() {
 		await respond(async () => {
@@ -23,3 +23,31 @@ export default {
 		});
 	},
 };
+
+// 入参：keyword 必填（服务层红线 2~64 字符），limit 可选（钳 200）
+handler.get.schema = {
+	query: {
+		type: "object",
+		required: ["keyword"],
+		properties: {
+			keyword: { type: "string", minLength: 2 },
+			limit: { type: "number" },
+		},
+	},
+};
+
+// 出参：目录红线只出 id/username/display_name（不含 email/avatar/roles）
+handler.get.response = {
+	type: "array",
+	items: {
+		type: "object",
+		required: ["id", "username", "display_name"],
+		properties: {
+			id: { type: "number" },
+			username: { type: "string" },
+			display_name: { type: ["string", "null"] },
+		},
+	},
+};
+
+export default handler;

package/templates/src/{_platform/api → app/api/_platform}/contacts/detail/api.ts

@@ -4,7 +4,7 @@ import { contactDetail } from "../../_shared/service/domain/contacts";
 import { assertTenantSelf } from "../../_shared/service/infra/access";
 import { rateLimit } from "../../_shared/service/infra/rate";
 
-export default {
+const handler = {
 	async get() {
 		await respond(async () => {
 			const uid = http.user?.id;
@@ -19,3 +19,27 @@ export default {
 		});
 	},
 };
+
+// 入参：id 必填（详情按 id 取单条）
+handler.get.schema = {
+	query: {
+		type: "object",
+		required: ["id"],
+		properties: { id: { type: "number" } },
+	},
+};
+
+// 出参：详情比目录多 email/avatar（安全评审 P2：仅详情端点给）
+handler.get.response = {
+	type: "object",
+	required: ["id", "username", "display_name", "email", "avatar_base64"],
+	properties: {
+		id: { type: "number" },
+		username: { type: "string" },
+		display_name: { type: ["string", "null"] },
+		email: { type: ["string", "null"] },
+		avatar_base64: { type: ["string", "null"] },
+	},
+};
+
+export default handler;

package/templates/src/app/api/_platform/migrations/0017__users_employee_no.mysql.sql

@@ -0,0 +1,7 @@
+-- 0017__users_employee_no（mysql 方言）：工号列 + 租户内唯一。列语义同 0017__users_employee_no.sql 头注释。
+-- 差异（沿用 0015__tenant.mysql.sql 惯例）：
+--   · 键列不能用 TEXT 落唯一键 → 按业务长度收窄为 VARCHAR(64)；
+--   · 无部分索引 → 普通唯一键，NULL 在 MySQL 里可重复出现，效果等同「有值才唯一」；
+--   · (255 + 64) × 4B = 1276B < InnoDB 3072B 上限。
+ALTER TABLE users ADD COLUMN employee_no VARCHAR(64) NULL;
+ALTER TABLE users ADD UNIQUE KEY uk_users_employee_no (tenant_id, employee_no);

package/templates/src/app/api/_platform/migrations/0017__users_employee_no.pg.sql

@@ -0,0 +1,4 @@
+-- 0017__users_employee_no（postgres 方言）：工号列 + 租户内唯一。列语义同 0017__users_employee_no.sql 头注释。
+-- 差异（沿用 0016__org.pg.sql 惯例）：TEXT 在 pg 合法且可用于部分唯一索引，无需收窄类型。
+ALTER TABLE users ADD COLUMN employee_no TEXT;
+CREATE UNIQUE INDEX IF NOT EXISTS uk_users_employee_no ON users (tenant_id, employee_no) WHERE employee_no IS NOT NULL;

package/templates/src/app/api/_platform/migrations/0017__users_employee_no.sql

@@ -0,0 +1,8 @@
+-- 0017__users_employee_no（sqlite 方言）：工号列 + 租户内唯一
+--
+-- 为什么单开一列而不是复用 display_name / 外部 origin_id：用户 CSV 导入导出要与源系统
+-- 9 列表头完全互通，「工号」必须是独立可查字段。
+-- 可空是必需的：存量本地账号没有工号，外部同步号也可能不带；唯一性只在有值时有意义，
+-- 故用部分索引（sqlite/pg 都支持 WHERE），mysql 侧靠「NULL 可重复」的唯一键等效。
+ALTER TABLE users ADD COLUMN employee_no TEXT;
+CREATE UNIQUE INDEX IF NOT EXISTS uk_users_employee_no ON users (tenant_id, employee_no) WHERE employee_no IS NOT NULL;

package/templates/src/{_platform/api → app/api/_platform}/schema.yaml

@@ -37,6 +37,11 @@ tables:
       activated: {type: integer, null: false}
       # 职务（与来源无关的通用字段）
       position: {type: text}
+      # 工号（0017，可空）：与姓名/用户名分开的独立工号列，租户内有值时唯一。
+      # 必须在这里声明——列只落库而不进白名单时，任何模块 select 它都会被构造器拒为
+      # `unknown column 'employee_no'`（/system/departments 依赖 /system/users 的选人列表，
+      # 曾因此在打开部门页时整页报错）。
+      employee_no: {type: text}
       # 外部源侧的状态快照（企微 1/2/4/5）。**绝不**自动改写 is_forbidden——那会和
       # 本站管理员的手动启停互相覆盖（方案 §4.3）
       external_status: {type: integer}

package/templates/src/{_platform/api → app/api/_platform}/solutions/api.ts

@@ -167,7 +167,7 @@ async function listMigrationFiles(env: SolutionsEnv, name: string, version: stri
 }
 
 export function createSolutionsApi(env: SolutionsEnv) {
-	return {
+	const api = {
 		// GET /api/_platform/solutions/routes —— 前端归并数据源（登录即可）。
 		routes: {
 			async get() {
@@ -217,6 +217,65 @@ export function createSolutionsApi(env: SolutionsEnv) {
 			},
 		},
 	};
+
+	// ---- 契约（v0.1.72：入参 .schema / 出参平级 .response）----
+	// 路由行出参：SolutionRouteRow（前端归并与深检共用形状）
+	const routeRow = {
+		type: "object",
+		required: ["path", "module", "category", "order", "title_key", "required_permission", "enabled"],
+		properties: {
+			path: { type: "string" },
+			module: { type: "string" },
+			category: { type: "string", enum: ["main", "admin", "hidden"] },
+			order: { type: "number" },
+			title_key: { type: ["string", "null"] },
+			required_permission: { type: ["string", "null"] },
+			enabled: { type: "boolean" },
+		},
+	};
+	api.routes.get.response = { type: "array", items: routeRow };
+
+	// 深检报告出参：VerifyReport（ok/checks/advise）
+	const verifyReport = {
+		type: "object",
+		required: ["ok", "checks", "advise"],
+		properties: {
+			ok: { type: "boolean" },
+			checks: {
+				type: "array",
+				items: {
+					type: "object",
+					required: ["id", "severity", "subject", "advise_key"],
+					properties: {
+						id: { type: "string" },
+						severity: { type: "string", enum: ["error", "warn", "info"] },
+						subject: { type: "string" },
+						advise_key: { type: "string" },
+					},
+				},
+			},
+			advise: { type: "array", items: { type: "string" } },
+		},
+	};
+	// verify：name 必填（端点门，缺参 400）
+	api.verify.post.schema = {
+		query: {
+			type: "object",
+			required: ["name"],
+			properties: { name: { type: "string", minLength: 1 } },
+		},
+	};
+	api.verify.post.response = verifyReport;
+	api.verify.last.get.schema = {
+		query: {
+			type: "object",
+			required: ["name"],
+			properties: { name: { type: "string", minLength: 1 } },
+		},
+	};
+	api.verify.last.get.response = verifyReport;
+
+	return api;
 }
 
 export default createSolutionsApi(solutionsEnv());

package/templates/src/{auth/api → app/api/auth}/_shared/wecom/replay.ts

@@ -43,7 +43,13 @@ export function runtimeReplayGate(): ReplayGate {
 		incr: key => kv.incr(key),
 		expire: (key, ttlSecs) => kv.expire(key, ttlSecs),
 		get: key => kv.get(key),
-		set: async (key, ttlSecs) => { await kv.set(key, "1"); if (!(await kv.expire(key, ttlSecs))) { log.warn("wecom applied marker ttl not set", "key", key); await kv.del(key); } },
+		set: async (key, ttlSecs) => {
+			await kv.set(key, "1");
+			if (!(await kv.expire(key, ttlSecs))) {
+				log.warn("wecom applied marker ttl not set", "key", key);
+				await kv.del(key);
+			}
+		},
 		del: key => kv.del(key),
 		now: () => Math.floor(Date.now() / 1000),
 	};
@@ -61,7 +67,7 @@ export class ReplayAlreadyApplied extends Error {
 
 /** 处理成功后调用：标记该 nonce 已落库成功，供重推幂等回 success（避免首次偏慢被企微判超时、重推又被重放守卫挡成 400）。 */
 export async function markApplied(nonce: string, gate: ReplayGate): Promise<void> {
-	await gate.set("wecom:applied:" + nonce, NONCE_TTL_SECS);
+	await gate.set(`wecom:applied:${nonce}`, NONCE_TTL_SECS);
 }
 
 /**
@@ -85,7 +91,7 @@ export async function guardReplay(timestampRaw: string, nonce: string, gate: Rep
 	if (seen !== 1) {
 		// 重推场景：若首次处理已成功落库（标了 applied 标记），直接幂等回 success，
 		// 不让企微卡在「应用安装失败」。未标记者说明首推仍在进行或已失败（失败会 release 让重推重放），维持 400。
-		const applied = await gate.get("wecom:applied:" + nonce);
+		const applied = await gate.get(`wecom:applied:${nonce}`);
 		if (applied)
 			throw new ReplayAlreadyApplied();
 		fail(400, "回调 nonce 重复：同一条指令回调已被处理过（重放请求已拒绝）");

package/templates/src/{auth/api → app/api/auth}/_shared/wecom/tenant-admin.ts

@@ -61,15 +61,12 @@ function randomPassword(): string {
 
 /** 跨租户读：指定租户下的管理员行（asSystem 例外，见文件头） */
 async function adminRow(tenantId: string): Promise<{ id: number, must_change: number } | null> {
-	const rows = await db.asSystem().table("users")
-		.select(["id", "must_change"])
-		.where({
-			and: [
-				{ field: "tenant_id", op: "eq", value: tenantId },
-				{ field: "username", op: "eq", value: TENANT_ADMIN_USERNAME },
-			],
-		})
-		.all() as Array<{ id: number, must_change: number | null }>;
+	const rows = await db.asSystem().table("users").select(["id", "must_change"]).where({
+		and: [
+			{ field: "tenant_id", op: "eq", value: tenantId },
+			{ field: "username", op: "eq", value: TENANT_ADMIN_USERNAME },
+		],
+	}).all() as Array<{ id: number, must_change: number | null }>;
 	if (!rows.length)
 		return null;
 	return { id: Number(rows[0]!.id), must_change: Number(rows[0]!.must_change ?? 0) };
@@ -77,15 +74,12 @@ async function adminRow(tenantId: string): Promise<{ id: number, must_change: nu
 
 /** 跨租户读：该用户在本租户是否握着 admin 角色（账号存在 ≠ 有角色，可能被收回过） */
 async function hasAdminRole(tenantId: string, uid: number): Promise<boolean> {
-	const roles = await db.asSystem().table("sys_user_role")
-		.select(["role_name"])
-		.where({
-			and: [
-				{ field: "tenant_id", op: "eq", value: tenantId },
-				{ field: "user_id", op: "eq", value: uid },
-			],
-		})
-		.all() as Array<{ role_name: string }>;
+	const roles = await db.asSystem().table("sys_user_role").select(["role_name"]).where({
+		and: [
+			{ field: "tenant_id", op: "eq", value: tenantId },
+			{ field: "user_id", op: "eq", value: uid },
+		],
+	}).all() as Array<{ role_name: string }>;
 	return roles.some(r => String(r.role_name) === TENANT_ADMIN_ROLE);
 }
 
@@ -176,15 +170,12 @@ export async function setTenantAdminPassword(tenantId: string, password: string)
 	if (!row)
 		throw Object.assign(new Error("租户管理员建档失败"), { status: 500 });
 
-	await db.asSystem().table("users")
-		.update({ password_hash: await bcrypt.hash(password), must_change: 1 })
-		.where({
-			and: [
-				{ field: "tenant_id", op: "eq", value: tenantId },
-				{ field: "username", op: "eq", value: TENANT_ADMIN_USERNAME },
-			],
-		})
-		.run();
+	await db.asSystem().table("users").update({ password_hash: await bcrypt.hash(password), must_change: 1 }).where({
+		and: [
+			{ field: "tenant_id", op: "eq", value: tenantId },
+			{ field: "username", op: "eq", value: TENANT_ADMIN_USERNAME },
+		],
+	}).run();
 
 	// 改密后旧会话必须失效。跨租户删 refresh 走带 tenant_id 条件的裸 SQL
 	// （先例见 store.ts::revokeTenantSessions：守卫是 check-on-miss，带了租户条件即放行）

package/templates/src/{auth/api → app/api/auth}/api.ts

@@ -9,6 +9,30 @@ import { createSession } from "./_shared/session";
 // 模块级禁止 createSession()：oj build 的 introspect 在无 jwt 的空沙箱里评估模块（§9.4），
 // runtimeDeps() 读 g.jwt 会直接炸构建——session 在 handler 内按需构造（无状态，纯闭包）。
 
+/** 会话票据（TokenBundle）：登录 / 刷新 / 改密三处同形（D14 + AC1-27） */
+const tokenBundle = {
+	type: "object",
+	required: ["access_token", "refresh_token", "expires_in", "restricted", "user"],
+	properties: {
+		access_token: { type: "string" },
+		refresh_token: { type: "string" },
+		expires_in: { type: "number" },
+		restricted: { type: "boolean" },
+		user: {
+			type: "object",
+			required: ["id", "username", "display_name", "avatar_base64", "must_change", "roles"],
+			properties: {
+				id: { type: "number" },
+				username: { type: "string" },
+				display_name: { type: ["string", "null"] },
+				avatar_base64: { type: ["string", "null"] },
+				must_change: { type: "boolean" },
+				roles: { type: "array", items: { type: "string" } },
+			},
+		},
+	},
+};
+
 const login = {
 	// POST /api/auth/login —— 本地登录（D14：先验口令后查禁用，三种失败统一 401）。
 	// B5/AC1-26：(IP, username) 连败阈值 → 429 + 指数 backoff；粗粒度 per-IP 窗口防撞库扫描。
@@ -73,4 +97,39 @@ password.put.schema = {
 	},
 };
 
+// 入参：本地账号口令（两种失败统一 401，不泄露账号状态——D14）
+login.post.schema = {
+	body: {
+		type: "object",
+		required: ["username", "password"],
+		properties: {
+			username: { type: "string", minLength: 1 },
+			password: { type: "string", minLength: 1 },
+		},
+	},
+};
+login.post.response = tokenBundle;
+
+// 登出：吊销给定 refresh 串（无业务返回体）
+logout.post.schema = {
+	body: {
+		type: "object",
+		required: ["refresh_token"],
+		properties: { refresh_token: { type: "string", minLength: 1 } },
+	},
+};
+logout.post.response = { type: "null" };
+
+// 刷新：旧串轮换（reuse 检测在 service 内）
+refresh.post.schema = {
+	body: {
+		type: "object",
+		required: ["refresh_token"],
+		properties: { refresh_token: { type: "string", minLength: 1 } },
+	},
+};
+refresh.post.response = tokenBundle;
+
+password.put.response = tokenBundle;
+
 export default { login, logout, refresh, password };

package/templates/src/{auth/api → app/api/auth}/ldap-login/api.ts

@@ -7,7 +7,7 @@ import { createSession } from "../_shared/session";
 
 // 模块级禁止 createSession()/runtimeLdapGateway()：oj build introspect 的空沙箱无 jwt/axis（§9.4）。
 
-export default {
+const handler = {
 	async post() {
 		const body = http.body || {};
 		const username = String(body.username ?? "");
@@ -27,3 +27,39 @@ export default {
 		});
 	},
 };
+
+// 入参与本地登录同形（username/password）；出参同 TokenBundle
+handler.post.schema = {
+	body: {
+		type: "object",
+		required: ["username", "password"],
+		properties: {
+			username: { type: "string", minLength: 1 },
+			password: { type: "string", minLength: 1 },
+		},
+	},
+};
+handler.post.response = {
+	type: "object",
+	required: ["access_token", "refresh_token", "expires_in", "restricted", "user"],
+	properties: {
+		access_token: { type: "string" },
+		refresh_token: { type: "string" },
+		expires_in: { type: "number" },
+		restricted: { type: "boolean" },
+		user: {
+			type: "object",
+			required: ["id", "username", "display_name", "avatar_base64", "must_change", "roles"],
+			properties: {
+				id: { type: "number" },
+				username: { type: "string" },
+				display_name: { type: ["string", "null"] },
+				avatar_base64: { type: ["string", "null"] },
+				must_change: { type: "boolean" },
+				roles: { type: "array", items: { type: "string" } },
+			},
+		},
+	},
+};
+
+export default handler;

package/templates/src/{auth/api → app/api/auth}/wecom/api.ts

@@ -320,6 +320,29 @@ ticket.post.schema = {
 		},
 	},
 };
+// 出参：TicketBundle（issueExternal 签发，同 TokenBundle）
+ticket.post.response = {
+	type: "object",
+	required: ["access_token", "refresh_token", "expires_in", "restricted", "user"],
+	properties: {
+		access_token: { type: "string" },
+		refresh_token: { type: "string" },
+		expires_in: { type: "number" },
+		restricted: { type: "boolean" },
+		user: {
+			type: "object",
+			required: ["id", "username", "display_name", "avatar_base64", "must_change", "roles"],
+			properties: {
+				id: { type: "number" },
+				username: { type: "string" },
+				display_name: { type: ["string", "null"] },
+				avatar_base64: { type: ["string", "null"] },
+				must_change: { type: "boolean" },
+				roles: { type: "array", items: { type: "string" } },
+			},
+		},
+	},
+};
 
 const event = {
 	// 企微后台「保存回调 URL」时会 GET 一次：解出 echostr 后**原样明文回**（不套信封、不加引号）。

package/templates/src/{notification/api → app/api/notification}/api.ts

@@ -137,6 +137,11 @@ notifications.read.post.schema = {
 		properties: { id: { type: "string" } },
 	},
 };
+notifications.read.post.response = { type: "null" };
+
+// read-all / clear：无入参、无返回体（json.ok(null)）——只声明出参，入参留空。
+notifications["read-all"].post.response = { type: "null" };
+notifications.clear.post.response = { type: "null" };
 
 // POST /api/notification/push —— 给指定用户推一条按人通知（发射原语 HTTP 入口）。
 // 真正逻辑在 _shared/notify.pushNotice（任一后端模块也可直接 import 调用，无需走 HTTP）。
@@ -239,6 +244,12 @@ const broadcast = {
 	},
 };
 
+push.post.response = {
+	type: "object",
+	required: ["id"],
+	properties: { id: { type: "string" } },
+};
+
 broadcast.post.schema = {
 	body: {
 		type: "object",
@@ -253,4 +264,10 @@ broadcast.post.schema = {
 	},
 };
 
+broadcast.post.response = {
+	type: "object",
+	required: ["id"],
+	properties: { id: { type: "string" } },
+};
+
 export default { notifications, push, "push-broadcast": broadcast };

package/templates/src/{notification/api → app/api/notification}/del/api.ts

@@ -49,4 +49,6 @@ handler.post.schema = {
 	},
 };
 
+handler.post.response = { type: "null" };
+
 export default handler;

package/templates/src/{system/api → app/api/system}/oplog/api.ts

@@ -1,5 +1,5 @@
 import { respond } from "#/_platform/_shared/respond";
-// GET /api/system/oplog?action=&username=&module=&limit= —— 操作日志查询（AC1-29；D13 admin 可查）。
+// GET /api/system/oplog?action=&username=&module=&page=&limit= —— 操作日志查询（AC1-29；D13 admin 可查）。
 // POST /api/system/oplog —— 操作日志写入（C3；登录态即可，解决方案模块记录自身操作）。
 import { assertSystemAdmin, currentAccess } from "#/_platform/_shared/service/infra/access";
 import { recordOp } from "#/_platform/_shared/service/infra/audit";
@@ -16,10 +16,12 @@ get.schema = {
 		type: "object",
 		properties: {
 			action: { type: "string" },
-			// username 前缀匹配（service likePattern），非精确
+			// username 包含匹配（子串，service 走 contains），非精确
 			username: { type: "string" },
 			module: { type: "string" },
-			// 分页大小，service paged 钳 200
+			// 页码（1 起）；service 的 pageArgs 非法回落 1
+			page: { type: "number", minimum: 1 },
+			// 每页条数 1~200（schema 兜住；service 的 pageArgs 再钳一次）
 			limit: { type: "number", minimum: 1, maximum: 200 },
 		},
 	},

package/templates/src/{system/api → app/api/system}/roles/api.ts

@@ -72,4 +72,7 @@ del.schema = {
 	},
 };
 
+// 出参无业务载荷（service 返回 void → data 为 null）
+del.response = { type: "null" };
+
 export default { get, post, del };

package/templates/src/{system/api → app/api/system}/roles/bindings/api.ts

@@ -26,4 +26,7 @@ put.schema = {
 	},
 };
 
+// 出参无业务载荷（service 返回 void → data 为 null）
+put.response = { type: "null" };
+
 export default { put };

package/templates/src/{system/api → app/api/system}/settings/api.ts

@@ -57,4 +57,7 @@ put.schema = {
 	},
 };
 
+// 出参无业务载荷（service 返回 void → data 为 null）
+put.response = { type: "null" };
+
 export default { get, put };

package/templates/src/{system/api → app/api/system}/users/forbidden/api.ts

@@ -23,4 +23,7 @@ put.schema = {
 	},
 };
 
+// 出参无业务载荷（service 返回 void → data 为 null）
+put.response = { type: "null" };
+
 export default { put };

package/templates/src/{system/api → app/api/system}/users/password/api.ts

@@ -23,4 +23,7 @@ put.schema = {
 	},
 };
 
+// 出参无业务载荷（service 返回 void → data 为 null）
+put.response = { type: "null" };
+
 export default { put };

package/templates/src/{system/api → app/api/system}/users/roles/api.ts

@@ -24,4 +24,7 @@ put.schema = {
 	},
 };
 
+// 出参无业务载荷（service 返回 void → data 为 null）
+put.response = { type: "null" };
+
 export default { put };