@oj-module/cli 0.2.53 → 0.2.54

package/templates/src/{system/web → app/web/system}/__client/api.schemas.ts

@@ -48,17 +48,6 @@ export const schemas = {
 }),
 		data: z.object({
 	"ok": z.boolean()
-}),
-	},
-	"systemDepartmentsMovePut": {
-		query: z.object({
-	"id": z.number()
-}),
-		body: z.object({
-	"parentId": z.number().nullable()
-}),
-		data: z.object({
-	"ok": z.boolean()
 }),
 	},
 	"systemDepartmentsDetachPost": {
@@ -118,6 +107,17 @@ export const schemas = {
 }),
 		data: z.object({
 	"ok": z.boolean()
+}),
+	},
+	"systemDepartmentsMovePut": {
+		query: z.object({
+	"id": z.number()
+}),
+		body: z.object({
+	"parentId": z.number().nullable()
+}),
+		data: z.object({
+	"ok": z.boolean()
 }),
 	},
 	"systemLoginMethodsGet": {
@@ -197,6 +197,7 @@ export const schemas = {
 		query: z.object({
 	"name": z.string().min(1)
 }),
+		data: z.null(),
 	},
 	"systemRolesBindingsPut": {
 		query: z.object({
@@ -205,6 +206,7 @@ export const schemas = {
 		body: z.object({
 	"permissions": z.array(z.string())
 }),
+		data: z.null(),
 	},
 	"systemSettingsGet": {
 		data: z.array(z.object({
@@ -228,6 +230,7 @@ export const schemas = {
 	"key": z.string().min(1),
 	"value": z.string()
 }),
+		data: z.null(),
 	},
 	"systemUsersGet": {
 		data: z.array(z.object({
@@ -265,33 +268,35 @@ export const schemas = {
 	"ok": z.boolean()
 }),
 	},
-	"systemUsersProfilePut": {
+	"systemUsersForbiddenPut": {
 		query: z.object({
 	"uid": z.number()
 }),
 		body: z.object({
-	"displayName": z.string().nullable().optional(),
-	"email": z.string().nullable().optional(),
-	"position": z.string().nullable().optional()
-}),
-		data: z.object({
-	"ok": z.boolean()
+	"forbidden": z.boolean()
 }),
+		data: z.null(),
 	},
-	"systemUsersForbiddenPut": {
+	"systemUsersPasswordPut": {
 		query: z.object({
 	"uid": z.number()
 }),
 		body: z.object({
-	"forbidden": z.boolean()
+	"password": z.string().min(6)
 }),
+		data: z.null(),
 	},
-	"systemUsersPasswordPut": {
+	"systemUsersProfilePut": {
 		query: z.object({
 	"uid": z.number()
 }),
 		body: z.object({
-	"password": z.string().min(6)
+	"displayName": z.string().nullable().optional(),
+	"email": z.string().nullable().optional(),
+	"position": z.string().nullable().optional()
+}),
+		data: z.object({
+	"ok": z.boolean()
 }),
 	},
 	"systemUsersRolesPut": {
@@ -301,5 +306,6 @@ export const schemas = {
 		body: z.object({
 	"roles": z.array(z.string())
 }),
+		data: z.null(),
 	},
 };

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

@@ -17,6 +17,9 @@ export const API_PREFIX = "/system";
 /** 认领身份前缀（契约 apiPrefix，字面等于模块目录名）：跨模块认领护栏对比基准 */
 export const MODULE_PREFIX = "/system";
 
+/** 认领方模块（web.config clientOwners 指定）：跨模块认领护栏对比基准 */
+export const MODULE_OWNER = "/app";
+
 /**
  * 模块 entry 的 onInit 里一行创建（构造即 install）：完成 apiPrefix 登记 +
  * scoped request 绑定，返回绑好前缀的端点函数集合。一模块一 client；
@@ -28,12 +31,12 @@ export function createSystemClient(ctx: ModuleContext) {
 	// 单槽、卸载互相耦合；跨模块需求应由本模块创建后经 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 暴露。`);
+	if (import.meta.env.DEV && ctx.module.name !== MODULE_OWNER.slice(1)) {
+		console.warn(`[ojm-api] 模块 "${ctx.module.name}" 正在认领 ${MODULE_PREFIX} 的 client——跨模块认领会共享 request 单槽、卸载互相耦合；应由 "${MODULE_OWNER.slice(1)}" 模块在自身 onInit 创建，跨模块需求经 provider 暴露。`);
 	}
 	ctx.register.apiPrefix(API_PREFIX);
 	bindRequest(ctx.utils.request);
-	return { systemDepartmentsGet, systemDepartmentsPost, systemDepartmentsPut, systemDepartmentsDelete, systemDepartmentsMovePut, systemDepartmentsDetachPost, systemDepartmentsMembersGet, systemDepartmentsMembersPost, systemDepartmentsMembersPut, systemDepartmentsMembersDelete, systemLoginMethodsGet, systemOplogGet, systemOplogPost, systemPermissionsGet, systemRolesGet, systemRolesPost, systemRolesDelete, systemRolesBindingsPut, systemSettingsGet, systemSettingsPut, systemUsersGet, systemUsersPost, systemUsersDelete, systemUsersProfilePut, systemUsersForbiddenPut, systemUsersPasswordPut, systemUsersRolesPut };
+	return { systemDepartmentsGet, systemDepartmentsPost, systemDepartmentsPut, systemDepartmentsDelete, systemDepartmentsDetachPost, systemDepartmentsMembersGet, systemDepartmentsMembersPost, systemDepartmentsMembersPut, systemDepartmentsMembersDelete, systemDepartmentsMovePut, systemLoginMethodsGet, systemOplogGet, systemOplogPost, systemPermissionsGet, systemRolesGet, systemRolesPost, systemRolesDelete, systemRolesBindingsPut, systemSettingsGet, systemSettingsPut, systemUsersGet, systemUsersPost, systemUsersDelete, systemUsersForbiddenPut, systemUsersPasswordPut, systemUsersProfilePut, systemUsersRolesPut };
 }
 
 /**
@@ -160,31 +163,6 @@ export async function systemDepartmentsDelete(query: SystemDepartmentsDeleteQuer
 	}
 }
 
-export type SystemDepartmentsMovePutQuery = z.input<(typeof schemas)["systemDepartmentsMovePut"]["query"]>;
-export type SystemDepartmentsMovePutBody = z.input<(typeof schemas)["systemDepartmentsMovePut"]["body"]>;
-export type SystemDepartmentsMovePutData = z.infer<(typeof schemas)["systemDepartmentsMovePut"]["data"]>;
-
-export async function systemDepartmentsMovePut(input: { query: SystemDepartmentsMovePutQuery, body: SystemDepartmentsMovePutBody }): Promise<SystemDepartmentsMovePutData> {
-	const client = ensureReq();
-	try {
-		const env = await client.put(`system/departments/move`, { searchParams: input.query as Record<string, string | number | boolean>, json: input.body }).json<OjEnvelope<SystemDepartmentsMovePutData>>();
-		// 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 SystemDepartmentsMovePutData;
-		if (import.meta.env.DEV) {
-			const { schemas } = await import("./api.schemas");
-			const r = schemas["systemDepartmentsMovePut"].data.safeParse(data);
-			if (!r.success)
-				throw new ContractApiError(-1, `[契约违例] systemDepartmentsMovePut 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
-		}
-		return data;
-	}
-	catch (e) {
-		throw await toApiError(e);
-	}
-}
-
 export type SystemDepartmentsDetachPostQuery = z.input<(typeof schemas)["systemDepartmentsDetachPost"]["query"]>;
 export type SystemDepartmentsDetachPostData = z.infer<(typeof schemas)["systemDepartmentsDetachPost"]["data"]>;
 
@@ -307,6 +285,31 @@ export async function systemDepartmentsMembersDelete(query: SystemDepartmentsMem
 	}
 }
 
+export type SystemDepartmentsMovePutQuery = z.input<(typeof schemas)["systemDepartmentsMovePut"]["query"]>;
+export type SystemDepartmentsMovePutBody = z.input<(typeof schemas)["systemDepartmentsMovePut"]["body"]>;
+export type SystemDepartmentsMovePutData = z.infer<(typeof schemas)["systemDepartmentsMovePut"]["data"]>;
+
+export async function systemDepartmentsMovePut(input: { query: SystemDepartmentsMovePutQuery, body: SystemDepartmentsMovePutBody }): Promise<SystemDepartmentsMovePutData> {
+	const client = ensureReq();
+	try {
+		const env = await client.put(`system/departments/move`, { searchParams: input.query as Record<string, string | number | boolean>, json: input.body }).json<OjEnvelope<SystemDepartmentsMovePutData>>();
+		// 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 SystemDepartmentsMovePutData;
+		if (import.meta.env.DEV) {
+			const { schemas } = await import("./api.schemas");
+			const r = schemas["systemDepartmentsMovePut"].data.safeParse(data);
+			if (!r.success)
+				throw new ContractApiError(-1, `[契约违例] systemDepartmentsMovePut 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+		}
+		return data;
+	}
+	catch (e) {
+		throw await toApiError(e);
+	}
+}
+
 export type SystemLoginMethodsGetData = z.infer<(typeof schemas)["systemLoginMethodsGet"]["data"]>;
 
 export async function systemLoginMethodsGet(): Promise<SystemLoginMethodsGetData> {
@@ -449,15 +452,22 @@ export async function systemRolesPost(body: SystemRolesPostBody): Promise<System
 }
 
 export type SystemRolesDeleteQuery = z.input<(typeof schemas)["systemRolesDelete"]["query"]>;
+export type SystemRolesDeleteData = z.infer<(typeof schemas)["systemRolesDelete"]["data"]>;
 
-export async function systemRolesDelete(query: SystemRolesDeleteQuery): Promise<unknown> {
+export async function systemRolesDelete(query: SystemRolesDeleteQuery): Promise<SystemRolesDeleteData> {
 	const client = ensureReq();
 	try {
-		const env = await client.delete(`system/roles`, { searchParams: query as Record<string, string | number | boolean> }).json<OjEnvelope<unknown>>();
+		const env = await client.delete(`system/roles`, { searchParams: query as Record<string, string | number | boolean> }).json<OjEnvelope<SystemRolesDeleteData>>();
 		// 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;
+		const data = env.data as SystemRolesDeleteData;
+		if (import.meta.env.DEV) {
+			const { schemas } = await import("./api.schemas");
+			const r = schemas["systemRolesDelete"].data.safeParse(data);
+			if (!r.success)
+				throw new ContractApiError(-1, `[契约违例] systemRolesDelete 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+		}
 		return data;
 	}
 	catch (e) {
@@ -467,15 +477,22 @@ export async function systemRolesDelete(query: SystemRolesDeleteQuery): Promise<
 
 export type SystemRolesBindingsPutQuery = z.input<(typeof schemas)["systemRolesBindingsPut"]["query"]>;
 export type SystemRolesBindingsPutBody = z.input<(typeof schemas)["systemRolesBindingsPut"]["body"]>;
+export type SystemRolesBindingsPutData = z.infer<(typeof schemas)["systemRolesBindingsPut"]["data"]>;
 
-export async function systemRolesBindingsPut(input: { query: SystemRolesBindingsPutQuery, body: SystemRolesBindingsPutBody }): Promise<unknown> {
+export async function systemRolesBindingsPut(input: { query: SystemRolesBindingsPutQuery, body: SystemRolesBindingsPutBody }): Promise<SystemRolesBindingsPutData> {
 	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>>();
+		const env = await client.put(`system/roles/bindings`, { searchParams: input.query as Record<string, string | number | boolean>, json: input.body }).json<OjEnvelope<SystemRolesBindingsPutData>>();
 		// 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;
+		const data = env.data as SystemRolesBindingsPutData;
+		if (import.meta.env.DEV) {
+			const { schemas } = await import("./api.schemas");
+			const r = schemas["systemRolesBindingsPut"].data.safeParse(data);
+			if (!r.success)
+				throw new ContractApiError(-1, `[契约违例] systemRolesBindingsPut 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+		}
 		return data;
 	}
 	catch (e) {
@@ -507,15 +524,22 @@ export async function systemSettingsGet(): Promise<SystemSettingsGetData> {
 }
 
 export type SystemSettingsPutBody = z.input<(typeof schemas)["systemSettingsPut"]["body"]>;
+export type SystemSettingsPutData = z.infer<(typeof schemas)["systemSettingsPut"]["data"]>;
 
-export async function systemSettingsPut(body: SystemSettingsPutBody): Promise<unknown> {
+export async function systemSettingsPut(body: SystemSettingsPutBody): Promise<SystemSettingsPutData> {
 	const client = ensureReq();
 	try {
-		const env = await client.put(`system/settings`, { json: body }).json<OjEnvelope<unknown>>();
+		const env = await client.put(`system/settings`, { json: body }).json<OjEnvelope<SystemSettingsPutData>>();
 		// 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;
+		const data = env.data as SystemSettingsPutData;
+		if (import.meta.env.DEV) {
+			const { schemas } = await import("./api.schemas");
+			const r = schemas["systemSettingsPut"].data.safeParse(data);
+			if (!r.success)
+				throw new ContractApiError(-1, `[契约违例] systemSettingsPut 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+		}
 		return data;
 	}
 	catch (e) {
@@ -594,23 +618,23 @@ export async function systemUsersDelete(query: SystemUsersDeleteQuery): Promise<
 	}
 }
 
-export type SystemUsersProfilePutQuery = z.input<(typeof schemas)["systemUsersProfilePut"]["query"]>;
-export type SystemUsersProfilePutBody = z.input<(typeof schemas)["systemUsersProfilePut"]["body"]>;
-export type SystemUsersProfilePutData = z.infer<(typeof schemas)["systemUsersProfilePut"]["data"]>;
+export type SystemUsersForbiddenPutQuery = z.input<(typeof schemas)["systemUsersForbiddenPut"]["query"]>;
+export type SystemUsersForbiddenPutBody = z.input<(typeof schemas)["systemUsersForbiddenPut"]["body"]>;
+export type SystemUsersForbiddenPutData = z.infer<(typeof schemas)["systemUsersForbiddenPut"]["data"]>;
 
-export async function systemUsersProfilePut(input: { query: SystemUsersProfilePutQuery, body: SystemUsersProfilePutBody }): Promise<SystemUsersProfilePutData> {
+export async function systemUsersForbiddenPut(input: { query: SystemUsersForbiddenPutQuery, body: SystemUsersForbiddenPutBody }): Promise<SystemUsersForbiddenPutData> {
 	const client = ensureReq();
 	try {
-		const env = await client.put(`system/users/profile`, { searchParams: input.query as Record<string, string | number | boolean>, json: input.body }).json<OjEnvelope<SystemUsersProfilePutData>>();
+		const env = await client.put(`system/users/forbidden`, { searchParams: input.query as Record<string, string | number | boolean>, json: input.body }).json<OjEnvelope<SystemUsersForbiddenPutData>>();
 		// 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 SystemUsersProfilePutData;
+		const data = env.data as SystemUsersForbiddenPutData;
 		if (import.meta.env.DEV) {
 			const { schemas } = await import("./api.schemas");
-			const r = schemas["systemUsersProfilePut"].data.safeParse(data);
+			const r = schemas["systemUsersForbiddenPut"].data.safeParse(data);
 			if (!r.success)
-				throw new ContractApiError(-1, `[契约违例] systemUsersProfilePut 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+				throw new ContractApiError(-1, `[契约违例] systemUsersForbiddenPut 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
 		}
 		return data;
 	}
@@ -619,17 +643,24 @@ export async function systemUsersProfilePut(input: { query: SystemUsersProfilePu
 	}
 }
 
-export type SystemUsersForbiddenPutQuery = z.input<(typeof schemas)["systemUsersForbiddenPut"]["query"]>;
-export type SystemUsersForbiddenPutBody = z.input<(typeof schemas)["systemUsersForbiddenPut"]["body"]>;
+export type SystemUsersPasswordPutQuery = z.input<(typeof schemas)["systemUsersPasswordPut"]["query"]>;
+export type SystemUsersPasswordPutBody = z.input<(typeof schemas)["systemUsersPasswordPut"]["body"]>;
+export type SystemUsersPasswordPutData = z.infer<(typeof schemas)["systemUsersPasswordPut"]["data"]>;
 
-export async function systemUsersForbiddenPut(input: { query: SystemUsersForbiddenPutQuery, body: SystemUsersForbiddenPutBody }): Promise<unknown> {
+export async function systemUsersPasswordPut(input: { query: SystemUsersPasswordPutQuery, body: SystemUsersPasswordPutBody }): Promise<SystemUsersPasswordPutData> {
 	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>>();
+		const env = await client.put(`system/users/password`, { searchParams: input.query as Record<string, string | number | boolean>, json: input.body }).json<OjEnvelope<SystemUsersPasswordPutData>>();
 		// 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;
+		const data = env.data as SystemUsersPasswordPutData;
+		if (import.meta.env.DEV) {
+			const { schemas } = await import("./api.schemas");
+			const r = schemas["systemUsersPasswordPut"].data.safeParse(data);
+			if (!r.success)
+				throw new ContractApiError(-1, `[契约违例] systemUsersPasswordPut 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+		}
 		return data;
 	}
 	catch (e) {
@@ -637,17 +668,24 @@ export async function systemUsersForbiddenPut(input: { query: SystemUsersForbidd
 	}
 }
 
-export type SystemUsersPasswordPutQuery = z.input<(typeof schemas)["systemUsersPasswordPut"]["query"]>;
-export type SystemUsersPasswordPutBody = z.input<(typeof schemas)["systemUsersPasswordPut"]["body"]>;
+export type SystemUsersProfilePutQuery = z.input<(typeof schemas)["systemUsersProfilePut"]["query"]>;
+export type SystemUsersProfilePutBody = z.input<(typeof schemas)["systemUsersProfilePut"]["body"]>;
+export type SystemUsersProfilePutData = z.infer<(typeof schemas)["systemUsersProfilePut"]["data"]>;
 
-export async function systemUsersPasswordPut(input: { query: SystemUsersPasswordPutQuery, body: SystemUsersPasswordPutBody }): Promise<unknown> {
+export async function systemUsersProfilePut(input: { query: SystemUsersProfilePutQuery, body: SystemUsersProfilePutBody }): Promise<SystemUsersProfilePutData> {
 	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>>();
+		const env = await client.put(`system/users/profile`, { searchParams: input.query as Record<string, string | number | boolean>, json: input.body }).json<OjEnvelope<SystemUsersProfilePutData>>();
 		// 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;
+		const data = env.data as SystemUsersProfilePutData;
+		if (import.meta.env.DEV) {
+			const { schemas } = await import("./api.schemas");
+			const r = schemas["systemUsersProfilePut"].data.safeParse(data);
+			if (!r.success)
+				throw new ContractApiError(-1, `[契约违例] systemUsersProfilePut 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+		}
 		return data;
 	}
 	catch (e) {
@@ -657,15 +695,22 @@ export async function systemUsersPasswordPut(input: { query: SystemUsersPassword
 
 export type SystemUsersRolesPutQuery = z.input<(typeof schemas)["systemUsersRolesPut"]["query"]>;
 export type SystemUsersRolesPutBody = z.input<(typeof schemas)["systemUsersRolesPut"]["body"]>;
+export type SystemUsersRolesPutData = z.infer<(typeof schemas)["systemUsersRolesPut"]["data"]>;
 
-export async function systemUsersRolesPut(input: { query: SystemUsersRolesPutQuery, body: SystemUsersRolesPutBody }): Promise<unknown> {
+export async function systemUsersRolesPut(input: { query: SystemUsersRolesPutQuery, body: SystemUsersRolesPutBody }): Promise<SystemUsersRolesPutData> {
 	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>>();
+		const env = await client.put(`system/users/roles`, { searchParams: input.query as Record<string, string | number | boolean>, json: input.body }).json<OjEnvelope<SystemUsersRolesPutData>>();
 		// 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;
+		const data = env.data as SystemUsersRolesPutData;
+		if (import.meta.env.DEV) {
+			const { schemas } = await import("./api.schemas");
+			const r = schemas["systemUsersRolesPut"].data.safeParse(data);
+			if (!r.success)
+				throw new ContractApiError(-1, `[契约违例] systemUsersRolesPut 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+		}
 		return data;
 	}
 	catch (e) {

package/templates/src/{system/web → app/web/system}/pages/users/index.tsx

@@ -132,9 +132,9 @@ export default function UsersPage() {
 					<Button size="small" disabled={String(row.id) === me} onClick={() => setPwdTarget(row)}>
 						{t("system:users.resetPwd")}
 					</Button>
-						{canManageMembership
-							? (
-								<Button size="small" type="link" onClick={() => navigate(`/system/users/${row.id}/roles`)}>
+					{canManageMembership
+						? (
+							<Button size="small" type="link" onClick={() => navigate(`/system/users/${row.id}/roles`)}>
 								{t("system:users.membership")}
 							</Button>
 						)

package/templates/src/{system/web → app/web/system}/pages/wecom/index.tsx

@@ -191,7 +191,7 @@ export default function WecomAdminPage() {
 		queryKey: ["system", "wecom-tenant-admin", corps.map(c => c.corpId).join(",")],
 		queryFn: async () => {
 			const out: Record<string, TenantAdminState> = {};
-			await Promise.all(corps.map(async c => {
+			await Promise.all(corps.map(async (c) => {
 				out[c.corpId] = await fetchTenantAdmin(c.corpId);
 			}));
 			return out;
@@ -244,7 +244,13 @@ export default function WecomAdminPage() {
 			title: t("system:wecom.tenantAdmin.action"),
 			key: "action",
 			render: (_: unknown, row: { corpId: string, name: string | null }) => (
-				<Button size="small" onClick={() => { setResetTarget(row); setResetPwd(""); }}>
+				<Button
+					size="small"
+					onClick={() => {
+						setResetTarget(row);
+						setResetPwd("");
+					}}
+				>
 					{t("system:wecom.tenantAdmin.reset")}
 				</Button>
 			),
@@ -433,7 +439,10 @@ export default function WecomAdminPage() {
 			<Modal
 				open={resetTarget != null}
 				title={t("system:wecom.tenantAdmin.resetTitle")}
-				onCancel={() => { setResetTarget(null); setResetPwd(""); }}
+				onCancel={() => {
+					setResetTarget(null);
+					setResetPwd("");
+				}}
 				onOk={() => resetMut.mutate({ corpId: resetTarget!.corpId, password: resetPwd })}
 				confirmLoading={resetMut.isPending}
 				okButtonProps={{ disabled: resetPwd.length < 6 }}

package/templates/src/{system/web/entry.ts → app/web/system/routes.ts}

@@ -1,7 +1,6 @@
-import type { AppRouteRecordRaw } from "@oj-module/runtime";
+import type { AppRouteRecordRaw, ModuleContext } from "@oj-module/runtime";
 
 import { SettingOutlined } from "@ant-design/icons";
-import { defineModule } from "@oj-module/runtime";
 
 import { createElement, lazy } from "react";
 
@@ -16,7 +15,24 @@ const Settings = lazy(() => import("./pages/settings"));
 const LoginMethods = lazy(() => import("./pages/login-methods"));
 const WecomAdmin = lazy(() => import("./pages/wecom"));
 
-const routes: AppRouteRecordRaw[] = [
+/**
+ * `/system` 根的角色门禁（对齐后端 assertSystemAdmin，access.ts:87）——
+ * superadmin **或** admin 均可，两者必须同时保留：D12（2026-10-22）起账号名=角色名，
+ * admin 与 superadmin 是两个独立账号（seed.sql），只留 ["admin"] 会把 superadmin
+ * 挡在门外（注册期过滤 → 路由消失 → 登录后 404 兜底）。改这两个值前先跑
+ * tests/system-guard.regression.spec.ts。
+ */
+const SYSTEM_ROLES = ["admin", "superadmin"];
+
+/**
+ * 系统管理根 `/system`：框架管理面（用户/成员资格/角色权限/操作日志/站点设置/登录方式），
+ * 数据源为 oj 后端 /api/system/*（模板 api 模块）。__client 由 `ojm api` 生成。
+ *
+ * 路由级门禁（B16）挂在根上：非系统管理员整棵子树不注入、菜单不可见（等价于原先的
+ * 模块级 requiredRoles——聚合后模块级会把 /home 一起挡掉，故必须下移到根路由）；
+ * API 级 403 由 assertSystemAdmin + service 层硬 enforcement 兜底。
+ */
+export const routes: AppRouteRecordRaw[] = [
 	{
 		path: "/system",
 		handle: {
@@ -25,6 +41,7 @@ const routes: AppRouteRecordRaw[] = [
 			// 负 order = 底部固定区：系统管理 pin 在侧边栏底部（2026-10-20 序轴约定）
 			order: -100,
 			layout: "container",
+			roles: SYSTEM_ROLES,
 		},
 		children: [
 			{
@@ -74,35 +91,7 @@ const routes: AppRouteRecordRaw[] = [
 	},
 ];
 
-/**
- * system 模块：框架管理面（用户/成员资格/角色权限/操作日志/站点设置/登录方式），
- * 数据源为 oj 后端 /api/system/*（模板 api 模块）。__client 不随模板分发——
- * init 后 `oj openapi -o openapi.json` + `ojm api` 生成（生成前本文件 ts 报红属预期，
- * devkit manual §2.2）。
- */
-export default defineModule({
-	name: "system",
-	description: "系统管理模块（框架管理面）",
-	version: "0.1.0",
-	peerRuntime: ">=0.0.0",
-	// 路由级门禁（B16）：非系统管理员不注入 /system 路由、菜单不可见；
-	// API 级 403 由 assertSystemAdmin + service 层硬 enforcement 兜底。
-	// 角色口径对齐后端 assertSystemAdmin（access.ts:87）——superadmin **或**
-	// admin 均可，两者必须同时保留：D12（2026-10-22）起账号名=角色名，admin 与
-	// superadmin 是两个独立账号（seed.sql），只留 ["admin"] 会把 superadmin 挡在
-	// 门外（注册期过滤 → 路由消失 → 登录后 404 兜底）。改这两个值前先跑
-	// tests/system-guard.regression.spec.ts（只留 ["admin"] 会立刻变红）。
-	config: { requiredRoles: ["admin", "superadmin"] },
-	routes,
-	i18n: {
-		"zh-CN": () => import("./locales/zh-CN.json"),
-		"en-US": () => import("./locales/en-US.json"),
-	},
-	lifecycle: {
-		async onInit(ctx) {
-			// 构造即接线：登记 /system 前缀 + 绑定 scoped request（D11 前缀收敛），
-			// 页面直接 import 生成的端点函数（模块级单槽 req 已由本调用绑定）。
-			createSystemClient(ctx);
-		},
-	},
-});
+/** 构造即接线：登记 /system 前缀 + 绑定 scoped request（D11 前缀收敛）。 */
+export async function onInit(ctx: ModuleContext) {
+	createSystemClient(ctx);
+}

package/templates/src/auth/api/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/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;