@oj-module/cli 0.2.1 → 0.2.5

package/templates/web/src/system/__client/api.schemas.ts

@@ -0,0 +1,162 @@
+/* eslint-disable */
+// 生成物：ojm api 从契约生成，勿手改（改动请改契约文件后重跑 ojm api）
+// AC-D15：仅供 DEV 校验动态 import，生产构建不进产物
+import { z } from "@oj-module/runtime";
+
+export const schemas = {
+	"systemLoginMethodsGet": {
+		data: z.object({
+	"methods": z.array(z.string())
+}),
+	},
+	"systemOplogGet": {
+		query: z.object({
+	"action": z.string().optional(),
+	"username": z.string().optional(),
+	"module": z.string().optional(),
+	"limit": z.number().min(1).max(200).optional()
+}),
+		data: z.object({
+	"list": z.array(z.object({
+	"id": z.number(),
+	"create_time": z.number(),
+	"user_id": z.number(),
+	"username": z.string(),
+	"action": z.string(),
+	"module": z.string(),
+	"version": z.string().nullable(),
+	"target": z.string().nullable(),
+	"detail": z.string().nullable(),
+	"level": z.number()
+})),
+	"total": z.number(),
+	"truncated": z.boolean()
+}),
+	},
+	"systemOplogPost": {
+		body: z.object({
+	"action": z.string().min(1),
+	"module": z.string().min(1),
+	"version": z.string().optional(),
+	"target": z.string().optional(),
+	"level": z.number().optional()
+}),
+		data: z.object({
+	"ok": z.boolean()
+}),
+	},
+	"systemPermissionsGet": {
+		data: z.array(z.object({
+	"code": z.string(),
+	"module": z.string(),
+	"title_key": z.string().nullable(),
+	"deprecated": z.boolean()
+})),
+	},
+	"systemRolesGet": {
+		data: z.array(z.object({
+	"name": z.string(),
+	"module": z.string(),
+	"title": z.string().nullable(),
+	"description": z.string().nullable(),
+	"builtin": z.boolean(),
+	"deprecated": z.boolean(),
+	"holders": z.number(),
+	"permissions": z.array(z.string())
+})),
+	},
+	"systemRolesPost": {
+		body: z.object({
+	"name": // @oj-warn: pattern="^custom\\.[a-z0-9][a-z0-9-]*$" 为 Rust regex，未在前端执行（跨语言语义漂移/ReDoS 风险）
+	z.string(),
+	"title": z.string().min(1),
+	"permissions": z.array(z.string()).optional()
+}),
+		data: z.object({
+	"name": z.string(),
+	"module": z.string()
+}),
+	},
+	"systemRolesDelete": {
+		query: z.object({
+	"name": z.string().min(1)
+}),
+	},
+	"systemRolesBindingsPut": {
+		query: z.object({
+	"name": z.string().min(1)
+}),
+		body: z.object({
+	"permissions": z.array(z.string())
+}),
+	},
+	"systemSettingsGet": {
+		data: z.array(z.object({
+	"group": z.string(),
+	"items": z.array(z.object({
+	"key": z.string(),
+	"module": z.string(),
+	"group": z.string(),
+	"type": z.string(),
+	"value": z.string().nullable(),
+	"default_value": z.string().nullable(),
+	"label_key": z.string().nullable(),
+	"options": z.string().nullable(),
+	"secret": z.boolean(),
+	"update_time": z.number()
+}))
+})),
+	},
+	"systemSettingsPut": {
+		body: z.object({
+	"key": z.string().min(1),
+	"value": z.string()
+}),
+	},
+	"systemUsersGet": {
+		data: z.array(z.object({
+	"id": z.number(),
+	"username": z.string(),
+	"display_name": z.string().nullable(),
+	"email": z.string().nullable(),
+	"is_forbidden": z.boolean(),
+	"must_change": z.boolean(),
+	"roles": z.array(z.string())
+})),
+	},
+	"systemUsersPost": {
+		body: z.object({
+	"username": z.string().min(1),
+	"password": z.string().min(6),
+	"displayName": z.string().optional(),
+	"email": z.string().optional()
+}),
+		data: z.object({
+	"id": z.number()
+}),
+	},
+	"systemUsersForbiddenPut": {
+		query: z.object({
+	"uid": z.number()
+}),
+		body: z.object({
+	"forbidden": z.boolean()
+}),
+	},
+	"systemUsersPasswordPut": {
+		query: z.object({
+	"uid": z.number()
+}),
+		body: z.object({
+	"password": z.string().min(6)
+}),
+	},
+	"systemUsersRolesPut": {
+		query: z.object({
+	"uid": z.number()
+}),
+		body: z.object({
+	"roles": z.array(z.string())
+}),
+	},
+};

package/templates/web/src/system/__client/api.ts

@@ -0,0 +1,382 @@
+/* eslint-disable */
+// 生成物：ojm api 从契约生成，勿手改（改动请改契约文件后重跑 ojm api）
+import { ContractApiError } from "@oj-module/runtime/contract/errors";
+import type { ScopedRequestLike } from "@oj-module/runtime/contract/errors";
+import type { ModuleContext } from "@oj-module/runtime";
+import type { z } from "@oj-module/runtime";
+import type { schemas } from "./api.schemas";
+
+/** oj 信封（AC-D16）：code=0 成功；非 0 时 HTTP status=code，由 toApiError 归一为 ContractApiError */
+interface OjEnvelope<T> { code: number, msg?: string, data?: T }
+
+let req: ScopedRequestLike | undefined;
+
+/** 线上 API 前缀（ojm api 从契约抽取，唯一真源，勿手改）：请求基址 + 前缀登记用 */
+export const API_PREFIX = "/system";
+
+/** 认领身份前缀（契约 apiPrefix，字面等于模块目录名）：跨模块认领护栏对比基准 */
+export const MODULE_PREFIX = "/system";
+
+/**
+ * 模块 entry 的 onInit 里一行创建（构造即 install）：完成 apiPrefix 登记 +
+ * scoped request 绑定，返回绑好前缀的端点函数集合。一模块一 client；
+ * 重复构造幂等安全（前缀重复登记同值、request 重绑同值）。
+ */
+export function createSystemClient(ctx: ModuleContext) {
+	// 跨模块认领护栏（DEV）：工厂知道自己该属于谁（MODULE_PREFIX = 契约 apiPrefix），
+	// ctx 又带 module.name——名实不符说明别的模块在替本模块创建 client，会共享 request
+	// 单槽、卸载互相耦合；跨模块需求应由本模块创建后经 provider 暴露。
+	// 注意对比基准是 MODULE_PREFIX（目录名）而非 API_PREFIX——D-M8 映射时线上前缀
+	// 属于别的命名空间，认领身份仍按目录名。
+	if (import.meta.env.DEV && ctx.module.name !== MODULE_PREFIX.slice(1)) {
+		console.warn(`[ojm-api] 模块 "${ctx.module.name}" 正在认领 ${MODULE_PREFIX} 的 client——跨模块认领会共享 request 单槽、卸载互相耦合；应由 "${MODULE_PREFIX.slice(1)}" 模块在自身 onInit 创建，跨模块需求经 provider 暴露。`);
+	}
+	ctx.register.apiPrefix(API_PREFIX);
+	bindRequest(ctx.utils.request);
+	return { systemLoginMethodsGet, systemOplogGet, systemOplogPost, systemPermissionsGet, systemRolesGet, systemRolesPost, systemRolesDelete, systemRolesBindingsPut, systemSettingsGet, systemSettingsPut, systemUsersGet, systemUsersPost, systemUsersForbiddenPut, systemUsersPasswordPut, systemUsersRolesPut };
+}
+
+/**
+ * @deprecated 请改用 createSystemClient(ctx)——工厂构造即完成
+ * 前缀登记 + request 绑定，不会出现「登记了前缀没绑 request」的半接线状态。
+ */
+export function bindRequest(r: ScopedRequestLike): void {
+	req = r;
+}
+
+function ensureReq(): ScopedRequestLike {
+	if (!req)
+		throw new ContractApiError(-1, "[ojm-api] 请求未绑定——请在模块 entry.ts 的 onInit 里调用 createSystemClient(ctx)（或 bindRequest(ctx.utils.request)）。");
+	return req;
+}
+
+/** ky HTTPError → ContractApiError（错误体为信封时取 code/msg）；契约违例与原错误原样透传 */
+async function toApiError(e: unknown): Promise<unknown> {
+	if (e instanceof ContractApiError)
+		return e;
+	// ky 2.x 构造 HTTPError 时已用 getReader() 消费掉原 response 体（res.clone().json() 按规范抛 TypeError，
+	// 体方法一律失效），解析好的错误体在公开字段 error.data——故读 error.data，勿改回 clone().json()。
+	const err = e as { data?: { code?: unknown, msg?: string }, response?: Response } | null;
+	const res = err?.response;
+	const d = err?.data;
+	if (res instanceof Response && d && typeof d.code === "number")
+		return new ContractApiError(d.code, d.msg ?? res.statusText);
+	return e;
+}
+
+export type SystemLoginMethodsGetData = z.infer<(typeof schemas)["systemLoginMethodsGet"]["data"]>;
+
+export async function systemLoginMethodsGet(): Promise<SystemLoginMethodsGetData> {
+	const client = ensureReq();
+	try {
+		const env = await client.get(`system/login-methods`).json<OjEnvelope<SystemLoginMethodsGetData>>();
+		// 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 SystemLoginMethodsGetData;
+		if (import.meta.env.DEV) {
+			const { schemas } = await import("./api.schemas");
+			const r = schemas["systemLoginMethodsGet"].data.safeParse(data);
+			if (!r.success)
+				throw new ContractApiError(-1, `[契约违例] systemLoginMethodsGet 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+		}
+		return data;
+	}
+	catch (e) {
+		throw await toApiError(e);
+	}
+}
+
+export type SystemOplogGetQuery = z.input<(typeof schemas)["systemOplogGet"]["query"]>;
+export type SystemOplogGetData = z.infer<(typeof schemas)["systemOplogGet"]["data"]>;
+
+export async function systemOplogGet(query: SystemOplogGetQuery): Promise<SystemOplogGetData> {
+	const client = ensureReq();
+	try {
+		const env = await client.get(`system/oplog`, { searchParams: query as Record<string, string | number | boolean> }).json<OjEnvelope<SystemOplogGetData>>();
+		// 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 SystemOplogGetData;
+		if (import.meta.env.DEV) {
+			const { schemas } = await import("./api.schemas");
+			const r = schemas["systemOplogGet"].data.safeParse(data);
+			if (!r.success)
+				throw new ContractApiError(-1, `[契约违例] systemOplogGet 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+		}
+		return data;
+	}
+	catch (e) {
+		throw await toApiError(e);
+	}
+}
+
+export type SystemOplogPostBody = z.input<(typeof schemas)["systemOplogPost"]["body"]>;
+export type SystemOplogPostData = z.infer<(typeof schemas)["systemOplogPost"]["data"]>;
+
+export async function systemOplogPost(body: SystemOplogPostBody): Promise<SystemOplogPostData> {
+	const client = ensureReq();
+	try {
+		const env = await client.post(`system/oplog`, { json: body }).json<OjEnvelope<SystemOplogPostData>>();
+		// 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 SystemOplogPostData;
+		if (import.meta.env.DEV) {
+			const { schemas } = await import("./api.schemas");
+			const r = schemas["systemOplogPost"].data.safeParse(data);
+			if (!r.success)
+				throw new ContractApiError(-1, `[契约违例] systemOplogPost 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+		}
+		return data;
+	}
+	catch (e) {
+		throw await toApiError(e);
+	}
+}
+
+export type SystemPermissionsGetData = z.infer<(typeof schemas)["systemPermissionsGet"]["data"]>;
+
+export async function systemPermissionsGet(): Promise<SystemPermissionsGetData> {
+	const client = ensureReq();
+	try {
+		const env = await client.get(`system/permissions`).json<OjEnvelope<SystemPermissionsGetData>>();
+		// 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 SystemPermissionsGetData;
+		if (import.meta.env.DEV) {
+			const { schemas } = await import("./api.schemas");
+			const r = schemas["systemPermissionsGet"].data.safeParse(data);
+			if (!r.success)
+				throw new ContractApiError(-1, `[契约违例] systemPermissionsGet 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+		}
+		return data;
+	}
+	catch (e) {
+		throw await toApiError(e);
+	}
+}
+
+export type SystemRolesGetData = z.infer<(typeof schemas)["systemRolesGet"]["data"]>;
+
+export async function systemRolesGet(): Promise<SystemRolesGetData> {
+	const client = ensureReq();
+	try {
+		const env = await client.get(`system/roles`).json<OjEnvelope<SystemRolesGetData>>();
+		// 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 SystemRolesGetData;
+		if (import.meta.env.DEV) {
+			const { schemas } = await import("./api.schemas");
+			const r = schemas["systemRolesGet"].data.safeParse(data);
+			if (!r.success)
+				throw new ContractApiError(-1, `[契约违例] systemRolesGet 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+		}
+		return data;
+	}
+	catch (e) {
+		throw await toApiError(e);
+	}
+}
+
+export type SystemRolesPostBody = z.input<(typeof schemas)["systemRolesPost"]["body"]>;
+export type SystemRolesPostData = z.infer<(typeof schemas)["systemRolesPost"]["data"]>;
+
+export async function systemRolesPost(body: SystemRolesPostBody): Promise<SystemRolesPostData> {
+	const client = ensureReq();
+	try {
+		const env = await client.post(`system/roles`, { json: body }).json<OjEnvelope<SystemRolesPostData>>();
+		// 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 SystemRolesPostData;
+		if (import.meta.env.DEV) {
+			const { schemas } = await import("./api.schemas");
+			const r = schemas["systemRolesPost"].data.safeParse(data);
+			if (!r.success)
+				throw new ContractApiError(-1, `[契约违例] systemRolesPost 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+		}
+		return data;
+	}
+	catch (e) {
+		throw await toApiError(e);
+	}
+}
+
+export type SystemRolesDeleteQuery = z.input<(typeof schemas)["systemRolesDelete"]["query"]>;
+
+export async function systemRolesDelete(query: SystemRolesDeleteQuery): Promise<unknown> {
+	const client = ensureReq();
+	try {
+		const env = await client.delete(`system/roles`, { searchParams: query as Record<string, string | number | boolean> }).json<OjEnvelope<unknown>>();
+		// 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 unknown;
+		return data;
+	}
+	catch (e) {
+		throw await toApiError(e);
+	}
+}
+
+export type SystemRolesBindingsPutQuery = z.input<(typeof schemas)["systemRolesBindingsPut"]["query"]>;
+export type SystemRolesBindingsPutBody = z.input<(typeof schemas)["systemRolesBindingsPut"]["body"]>;
+
+export async function systemRolesBindingsPut(input: { query: SystemRolesBindingsPutQuery, body: SystemRolesBindingsPutBody }): Promise<unknown> {
+	const client = ensureReq();
+	try {
+		const env = await client.put(`system/roles/bindings`, { searchParams: input.query as Record<string, string | number | boolean>, json: input.body }).json<OjEnvelope<unknown>>();
+		// 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 unknown;
+		return data;
+	}
+	catch (e) {
+		throw await toApiError(e);
+	}
+}
+
+export type SystemSettingsGetData = z.infer<(typeof schemas)["systemSettingsGet"]["data"]>;
+
+export async function systemSettingsGet(): Promise<SystemSettingsGetData> {
+	const client = ensureReq();
+	try {
+		const env = await client.get(`system/settings`).json<OjEnvelope<SystemSettingsGetData>>();
+		// 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 SystemSettingsGetData;
+		if (import.meta.env.DEV) {
+			const { schemas } = await import("./api.schemas");
+			const r = schemas["systemSettingsGet"].data.safeParse(data);
+			if (!r.success)
+				throw new ContractApiError(-1, `[契约违例] systemSettingsGet 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+		}
+		return data;
+	}
+	catch (e) {
+		throw await toApiError(e);
+	}
+}
+
+export type SystemSettingsPutBody = z.input<(typeof schemas)["systemSettingsPut"]["body"]>;
+
+export async function systemSettingsPut(body: SystemSettingsPutBody): Promise<unknown> {
+	const client = ensureReq();
+	try {
+		const env = await client.put(`system/settings`, { json: body }).json<OjEnvelope<unknown>>();
+		// 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 unknown;
+		return data;
+	}
+	catch (e) {
+		throw await toApiError(e);
+	}
+}
+
+export type SystemUsersGetData = z.infer<(typeof schemas)["systemUsersGet"]["data"]>;
+
+export async function systemUsersGet(): Promise<SystemUsersGetData> {
+	const client = ensureReq();
+	try {
+		const env = await client.get(`system/users`).json<OjEnvelope<SystemUsersGetData>>();
+		// 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 SystemUsersGetData;
+		if (import.meta.env.DEV) {
+			const { schemas } = await import("./api.schemas");
+			const r = schemas["systemUsersGet"].data.safeParse(data);
+			if (!r.success)
+				throw new ContractApiError(-1, `[契约违例] systemUsersGet 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+		}
+		return data;
+	}
+	catch (e) {
+		throw await toApiError(e);
+	}
+}
+
+export type SystemUsersPostBody = z.input<(typeof schemas)["systemUsersPost"]["body"]>;
+export type SystemUsersPostData = z.infer<(typeof schemas)["systemUsersPost"]["data"]>;
+
+export async function systemUsersPost(body: SystemUsersPostBody): Promise<SystemUsersPostData> {
+	const client = ensureReq();
+	try {
+		const env = await client.post(`system/users`, { json: body }).json<OjEnvelope<SystemUsersPostData>>();
+		// 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 SystemUsersPostData;
+		if (import.meta.env.DEV) {
+			const { schemas } = await import("./api.schemas");
+			const r = schemas["systemUsersPost"].data.safeParse(data);
+			if (!r.success)
+				throw new ContractApiError(-1, `[契约违例] systemUsersPost 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+		}
+		return data;
+	}
+	catch (e) {
+		throw await toApiError(e);
+	}
+}
+
+export type SystemUsersForbiddenPutQuery = z.input<(typeof schemas)["systemUsersForbiddenPut"]["query"]>;
+export type SystemUsersForbiddenPutBody = z.input<(typeof schemas)["systemUsersForbiddenPut"]["body"]>;
+
+export async function systemUsersForbiddenPut(input: { query: SystemUsersForbiddenPutQuery, body: SystemUsersForbiddenPutBody }): Promise<unknown> {
+	const client = ensureReq();
+	try {
+		const env = await client.put(`system/users/forbidden`, { searchParams: input.query as Record<string, string | number | boolean>, json: input.body }).json<OjEnvelope<unknown>>();
+		// 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 unknown;
+		return data;
+	}
+	catch (e) {
+		throw await toApiError(e);
+	}
+}
+
+export type SystemUsersPasswordPutQuery = z.input<(typeof schemas)["systemUsersPasswordPut"]["query"]>;
+export type SystemUsersPasswordPutBody = z.input<(typeof schemas)["systemUsersPasswordPut"]["body"]>;
+
+export async function systemUsersPasswordPut(input: { query: SystemUsersPasswordPutQuery, body: SystemUsersPasswordPutBody }): Promise<unknown> {
+	const client = ensureReq();
+	try {
+		const env = await client.put(`system/users/password`, { searchParams: input.query as Record<string, string | number | boolean>, json: input.body }).json<OjEnvelope<unknown>>();
+		// 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 unknown;
+		return data;
+	}
+	catch (e) {
+		throw await toApiError(e);
+	}
+}
+
+export type SystemUsersRolesPutQuery = z.input<(typeof schemas)["systemUsersRolesPut"]["query"]>;
+export type SystemUsersRolesPutBody = z.input<(typeof schemas)["systemUsersRolesPut"]["body"]>;
+
+export async function systemUsersRolesPut(input: { query: SystemUsersRolesPutQuery, body: SystemUsersRolesPutBody }): Promise<unknown> {
+	const client = ensureReq();
+	try {
+		const env = await client.put(`system/users/roles`, { searchParams: input.query as Record<string, string | number | boolean>, json: input.body }).json<OjEnvelope<unknown>>();
+		// 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 unknown;
+		return data;
+	}
+	catch (e) {
+		throw await toApiError(e);
+	}
+}

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

@@ -47,7 +47,7 @@ export default function OplogPage() {
 	];
 
 	return (
-		<Space direction="vertical" style={{ width: "100%" }}>
+		<Space direction="vertical" style={{ width: "100%", paddingTop: 16 }}>
 			<Form
 				layout="inline"
 				onFinish={values => setFilters({

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

@@ -67,6 +67,7 @@ export default function RolesPage() {
 
 	return (
 		<Tabs
+			style={{ paddingTop: 16 }}
 			items={[
 				{
 					key: "roles",

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

@@ -91,7 +91,7 @@ export default function SettingsPage() {
 		.filter(g => g.items.length > 0);
 
 	return (
-		<Space direction="vertical" style={{ width: "100%" }}>
+		<Space direction="vertical" style={{ width: "100%", paddingTop: 16 }}>
 			{groups.map(g => (
 				<Card key={g.group} title={g.group}>
 					<Space direction="vertical" style={{ width: "100%" }}>

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

@@ -115,7 +115,7 @@ export default function UsersPage() {
 	];
 
 	return (
-		<Space direction="vertical" style={{ width: "100%" }}>
+		<Space direction="vertical" style={{ width: "100%", paddingTop: 16 }}>
 			<Button type="primary" icon={<PlusOutlined />} onClick={() => setCreateOpen(true)}>
 				{t("system:users.create")}
 			</Button>

package/templates/web.config.ts

@@ -1,48 +1,40 @@
 /**
  * 模块工程配置：共享依赖一律不进 dependencies（宿主 importmap 提供），
  * 这里只登记模块清单（entry 相对本工程根）。
+ *
+ * 模块顺序即导航顺序：`home` 必须第一个（shell 的 "/" 重定向到它）。
  */
+const allModules = [
+	// /home 必须是首个模块：shell 的 "/" → VITE_BASE_HOME_PATH（=/home）重定向
+	{ name: "home", entry: "web/src/home/entry.ts" },
+	{ name: "demo", entry: "web/src/demo/entry.ts" },
+	// /login 路由由模块提供：shell 宿主不挂 runtime 内置 baseRoutes
+	{ name: "login", entry: "web/src/login/entry.ts" },
+	// 个人中心：runtime 用户菜单固定导航 /personal-center/my-profile，缺则点击落空
+	{ name: "personal-center", entry: "web/src/personal-center/entry.ts" },
+	// 通知：onInit 注册 notificationsApi provider（四方法全必填），
+	// 通知铃的互动（单条已读/全部已读/清空）由此生效；未登记则永远回落内置只读兜底
+	{ name: "notification", entry: "web/src/notification/entry.ts" },
+	// 系统管理：用户/成员资格/角色权限/操作日志/站点设置/登录方式（oj 后端 /api/system/*）
+	{ name: "system", entry: "web/src/system/entry.ts" },
+	// #region demo-only
+	// 以下为模板内置的演示模块（about/access/exception/outside/route-nest），
+	// 用于把 templates 当可运行 demo 直接跑；其文件不在 `ojm init` 的
+	// init.include.yaml 白名单里，不拷入新工程，故本区间连同这些条目会被
+	// init 一并剥离，脚手架产出的配置不会残留指向缺失文件的死条目。
+	{ name: "about", entry: "web/src/about/entry.ts" },
+	{ name: "access", entry: "web/src/access/entry.ts" },
+	{ name: "exception", entry: "web/src/exception/entry.ts" },
+	{ name: "outside", entry: "web/src/outside/entry.ts" },
+	{ name: "route-nest", entry: "web/src/route-nest/entry.ts" },
+	// 解决方案市场：第一方能力（消费 _platform 编排面 /api/_platform/market/*），
+	// 模板自带以便自演示；新工程默认不带，同上由 init 剥离。
+	{ name: "oj-market", entry: "web/src/oj-market/entry.ts" },
+	// #endregion demo-only
+];
+
 export default {
 	/** 产物 URL 前缀，留空表示同源相对路径 */
 	baseUrl: "",
-	modules: [
-		{
-			// /home 必须是首个模块：shell 的 "/" → VITE_BASE_HOME_PATH（=/home）重定向
-			name: "home",
-			entry: "web/src/home/entry.ts",
-			enabled: true,
-		},
-		{
-			name: "demo",
-			entry: "web/src/demo/entry.ts",
-			enabled: true,
-		},
-		{
-			// /login 路由由模块提供：shell 宿主不挂 runtime 内置 baseRoutes
-			name: "login",
-			entry: "web/src/login/entry.ts",
-			enabled: true,
-		},
-		{
-			// 个人中心：runtime 用户菜单固定导航 /personal-center/my-profile，缺则点击落空
-			name: "personal-center",
-			entry: "web/src/personal-center/entry.ts",
-			enabled: true,
-		},
-		{
-			// 通知：onInit 注册 notificationsApi provider（四方法全必填），
-			// 通知铃的互动（单条已读/全部已读/清空）由此生效；未登记则永远回落内置只读兜底
-			name: "notification",
-			entry: "web/src/notification/entry.ts",
-			enabled: true,
-		},
-		{
-			// 系统管理：用户/成员资格/角色权限/操作日志/站点设置/登录方式（oj 后端 /api/system/*）。
-			// __client 不随模板分发：init 后跑一次 `oj openapi -o openapi.json && ojm api` 生成；
-			// 生成前该模块加载失败（菜单缺失）属预期，README「系统管理模块」节有说明
-			name: "system",
-			entry: "web/src/system/entry.ts",
-			enabled: true,
-		},
-	],
+	modules: allModules,
 };

package/vendor/host-versions.json

@@ -8,9 +8,9 @@
 		"react-router": "7.18.2",
 		"react-router/dom": "7.18.2",
 		"@tanstack/react-query": "5.102.8",
-		"@oj-module/runtime": "0.2.1",
-		"@oj-module/runtime/contract": "0.2.1",
-		"@oj-module/runtime/contract/errors": "0.2.1",
+		"@oj-module/runtime": "0.2.5",
+		"@oj-module/runtime/contract": "0.2.5",
+		"@oj-module/runtime/contract/errors": "0.2.5",
 		"@plane/kit": "0.1.20",
 		"@plane/editor": "0.1.20",
 		"antd": "6.6.1",