@oj-module/cli 0.2.53 → 0.2.54

package/templates/src/auth/api/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/auth/web/__client/api.schemas.ts

@@ -4,10 +4,89 @@
 import { z } from "@oj-module/runtime";
 
 export const schemas = {
+	"authLoginPost": {
+		body: z.object({
+	"username": z.string().min(1),
+	"password": z.string().min(1)
+}),
+		data: z.object({
+	"access_token": z.string(),
+	"refresh_token": z.string(),
+	"expires_in": z.number(),
+	"restricted": z.boolean(),
+	"user": z.object({
+	"id": z.number(),
+	"username": z.string(),
+	"display_name": z.string().nullable(),
+	"avatar_base64": z.string().nullable(),
+	"must_change": z.boolean(),
+	"roles": z.array(z.string())
+})
+}),
+	},
+	"authLogoutPost": {
+		body: z.object({
+	"refresh_token": z.string().min(1)
+}),
+		data: z.null(),
+	},
+	"authRefreshPost": {
+		body: z.object({
+	"refresh_token": z.string().min(1)
+}),
+		data: z.object({
+	"access_token": z.string(),
+	"refresh_token": z.string(),
+	"expires_in": z.number(),
+	"restricted": z.boolean(),
+	"user": z.object({
+	"id": z.number(),
+	"username": z.string(),
+	"display_name": z.string().nullable(),
+	"avatar_base64": z.string().nullable(),
+	"must_change": z.boolean(),
+	"roles": z.array(z.string())
+})
+}),
+	},
 	"authPasswordPut": {
 		body: z.object({
 	"old_password": z.string().min(1),
 	"new_password": z.string().min(6)
+}),
+		data: z.object({
+	"access_token": z.string(),
+	"refresh_token": z.string(),
+	"expires_in": z.number(),
+	"restricted": z.boolean(),
+	"user": z.object({
+	"id": z.number(),
+	"username": z.string(),
+	"display_name": z.string().nullable(),
+	"avatar_base64": z.string().nullable(),
+	"must_change": z.boolean(),
+	"roles": z.array(z.string())
+})
+}),
+	},
+	"authLdapLoginPost": {
+		body: z.object({
+	"username": z.string().min(1),
+	"password": z.string().min(1)
+}),
+		data: z.object({
+	"access_token": z.string(),
+	"refresh_token": z.string(),
+	"expires_in": z.number(),
+	"restricted": z.boolean(),
+	"user": z.object({
+	"id": z.number(),
+	"username": z.string(),
+	"display_name": z.string().nullable(),
+	"avatar_base64": z.string().nullable(),
+	"must_change": z.boolean(),
+	"roles": z.array(z.string())
+})
 }),
 	},
 	"authWecomAdminAppsGet": {
@@ -24,6 +103,16 @@ export const schemas = {
 	"installed_at": z.number(),
 	"update_time": z.number()
 })),
+	},
+	"authWecomAdminOverviewGet": {
+		data: z.object({
+	"kinds": z.array(z.enum(["suite", "corp"])),
+	"configError": z.string().nullable(),
+	"callbackUrl": z.string().nullable(),
+	"corpId": z.string().nullable(),
+	"agentId": z.string().nullable(),
+	"corpCallbackConfigured": z.boolean()
+}),
 	},
 	"authWecomAdminStatusPost": {
 		body: z.object({
@@ -41,16 +130,6 @@ export const schemas = {
 	"installUrl": z.string(),
 	"callbackUrl": z.string(),
 	"expiresIn": z.number()
-}),
-	},
-	"authWecomAdminOverviewGet": {
-		data: z.object({
-	"kinds": z.array(z.enum(["suite", "corp"])),
-	"configError": z.string().nullable(),
-	"callbackUrl": z.string().nullable(),
-	"corpId": z.string().nullable(),
-	"agentId": z.string().nullable(),
-	"corpCallbackConfigured": z.boolean()
 }),
 	},
 	"authWecomAdminConnectPost": {
@@ -59,11 +138,48 @@ export const schemas = {
 	"agentId": z.string(),
 	"departments": z.number(),
 	"members": z.number()
+}),
+	},
+	"authWecomAdminTenantAdminGet": {
+		query: z.object({
+	"corpId": z.string().min(1)
+}),
+		data: z.object({
+	"corpId": z.string(),
+	"username": z.string(),
+	"exists": z.boolean(),
+	"mustChange": z.boolean()
+}),
+	},
+	"authWecomAdminTenantAdminPasswordPost": {
+		body: z.object({
+	"corpId": z.string().min(1),
+	"password": z.string().min(6)
+}),
+		data: z.object({
+	"corpId": z.string(),
+	"username": z.string(),
+	"exists": z.boolean(),
+	"mustChange": z.boolean()
 }),
 	},
 	"authWecomTicketPost": {
 		body: z.object({
 	"ticket": z.string().min(32).max(128)
+}),
+		data: z.object({
+	"access_token": z.string(),
+	"refresh_token": z.string(),
+	"expires_in": z.number(),
+	"restricted": z.boolean(),
+	"user": z.object({
+	"id": z.number(),
+	"username": z.string(),
+	"display_name": z.string().nullable(),
+	"avatar_base64": z.string().nullable(),
+	"must_change": z.boolean(),
+	"roles": z.array(z.string())
+})
 }),
 	},
 	"authWecomSyncStartPost": {
@@ -74,6 +190,8 @@ export const schemas = {
 	"connected": z.boolean(),
 	"authMode": z.number(),
 	"profileStatus": z.string().nullable(),
+	"agentId": z.string().nullable(),
+	"credentialKind": z.union([z.literal("suite"), z.literal("corp"), z.literal(null)]).nullable(),
 	"status": z.enum(["idle", "running", "done", "failed", "cancelled"]),
 	"phase": z.enum(["departments", "members", "reconcile"]),
 	"stats": z.object({
@@ -106,6 +224,8 @@ export const schemas = {
 	"connected": z.boolean(),
 	"authMode": z.number(),
 	"profileStatus": z.string().nullable(),
+	"agentId": z.string().nullable(),
+	"credentialKind": z.union([z.literal("suite"), z.literal("corp"), z.literal(null)]).nullable(),
 	"status": z.enum(["idle", "running", "done", "failed", "cancelled"]),
 	"phase": z.enum(["departments", "members", "reconcile"]),
 	"stats": z.object({
@@ -127,9 +247,7 @@ export const schemas = {
 }).nullable(),
 	"startedAt": z.number(),
 	"finishedAt": z.number(),
-	"updateTime": z.number(),
-	"agentId": z.string().nullable(),
-	"credentialKind": z.union([z.literal("suite"), z.literal("corp"), z.literal(null)]).nullable()
+	"updateTime": z.number()
 }),
 	},
 	"authWecomSyncCancelPost": {
@@ -140,6 +258,8 @@ export const schemas = {
 	"connected": z.boolean(),
 	"authMode": z.number(),
 	"profileStatus": z.string().nullable(),
+	"agentId": z.string().nullable(),
+	"credentialKind": z.union([z.literal("suite"), z.literal("corp"), z.literal(null)]).nullable(),
 	"status": z.enum(["idle", "running", "done", "failed", "cancelled"]),
 	"phase": z.enum(["departments", "members", "reconcile"]),
 	"stats": z.object({

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

@@ -33,7 +33,7 @@ export function createAuthClient(ctx: ModuleContext) {
 	}
 	ctx.register.apiPrefix(API_PREFIX);
 	bindRequest(ctx.utils.request);
-	return { authLoginPost, authLogoutPost, authRefreshPost, authPasswordPut, authLdapLoginPost, authWecomAdminAppsGet, authWecomAdminStatusPost, authWecomAdminInstallGet, authWecomAdminOverviewGet, authWecomAdminConnectPost, authWecomLoginGet, authWecomCallbackGet, authWecomTicketPost, authWecomEventGet, authWecomEventPost, authWecomSyncStartPost, authWecomSyncStatusGet, authWecomSyncCancelPost };
+	return { authLoginPost, authLogoutPost, authRefreshPost, authPasswordPut, authLdapLoginPost, authWecomAdminAppsGet, authWecomAdminOverviewGet, authWecomAdminStatusPost, authWecomAdminInstallGet, authWecomAdminConnectPost, authWecomAdminTenantAdminGet, authWecomAdminTenantAdminPasswordPost, authWecomLoginGet, authWecomCallbackGet, authWecomTicketPost, authWecomEventGet, authWecomEventPost, authWecomSyncStartPost, authWecomSyncStatusGet, authWecomSyncCancelPost };
 }
 
 /**
@@ -64,14 +64,23 @@ async function toApiError(e: unknown): Promise<unknown> {
 	return e;
 }
 
-export async function authLoginPost(): Promise<unknown> {
+export type AuthLoginPostBody = z.input<(typeof schemas)["authLoginPost"]["body"]>;
+export type AuthLoginPostData = z.infer<(typeof schemas)["authLoginPost"]["data"]>;
+
+export async function authLoginPost(body: AuthLoginPostBody): Promise<AuthLoginPostData> {
 	const client = ensureReq();
 	try {
-		const env = await client.post(`auth/login`).json<OjEnvelope<unknown>>();
+		const env = await client.post(`auth/login`, { json: body }).json<OjEnvelope<AuthLoginPostData>>();
 		// 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 AuthLoginPostData;
+		if (import.meta.env.DEV) {
+			const { schemas } = await import("./api.schemas");
+			const r = schemas["authLoginPost"].data.safeParse(data);
+			if (!r.success)
+				throw new ContractApiError(-1, `[契约违例] authLoginPost 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+		}
 		return data;
 	}
 	catch (e) {
@@ -79,14 +88,23 @@ export async function authLoginPost(): Promise<unknown> {
 	}
 }
 
-export async function authLogoutPost(): Promise<unknown> {
+export type AuthLogoutPostBody = z.input<(typeof schemas)["authLogoutPost"]["body"]>;
+export type AuthLogoutPostData = z.infer<(typeof schemas)["authLogoutPost"]["data"]>;
+
+export async function authLogoutPost(body: AuthLogoutPostBody): Promise<AuthLogoutPostData> {
 	const client = ensureReq();
 	try {
-		const env = await client.post(`auth/logout`).json<OjEnvelope<unknown>>();
+		const env = await client.post(`auth/logout`, { json: body }).json<OjEnvelope<AuthLogoutPostData>>();
 		// 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 AuthLogoutPostData;
+		if (import.meta.env.DEV) {
+			const { schemas } = await import("./api.schemas");
+			const r = schemas["authLogoutPost"].data.safeParse(data);
+			if (!r.success)
+				throw new ContractApiError(-1, `[契约违例] authLogoutPost 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+		}
 		return data;
 	}
 	catch (e) {
@@ -94,14 +112,23 @@ export async function authLogoutPost(): Promise<unknown> {
 	}
 }
 
-export async function authRefreshPost(): Promise<unknown> {
+export type AuthRefreshPostBody = z.input<(typeof schemas)["authRefreshPost"]["body"]>;
+export type AuthRefreshPostData = z.infer<(typeof schemas)["authRefreshPost"]["data"]>;
+
+export async function authRefreshPost(body: AuthRefreshPostBody): Promise<AuthRefreshPostData> {
 	const client = ensureReq();
 	try {
-		const env = await client.post(`auth/refresh`).json<OjEnvelope<unknown>>();
+		const env = await client.post(`auth/refresh`, { json: body }).json<OjEnvelope<AuthRefreshPostData>>();
 		// 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 AuthRefreshPostData;
+		if (import.meta.env.DEV) {
+			const { schemas } = await import("./api.schemas");
+			const r = schemas["authRefreshPost"].data.safeParse(data);
+			if (!r.success)
+				throw new ContractApiError(-1, `[契约违例] authRefreshPost 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+		}
 		return data;
 	}
 	catch (e) {
@@ -110,15 +137,22 @@ export async function authRefreshPost(): Promise<unknown> {
 }
 
 export type AuthPasswordPutBody = z.input<(typeof schemas)["authPasswordPut"]["body"]>;
+export type AuthPasswordPutData = z.infer<(typeof schemas)["authPasswordPut"]["data"]>;
 
-export async function authPasswordPut(body: AuthPasswordPutBody): Promise<unknown> {
+export async function authPasswordPut(body: AuthPasswordPutBody): Promise<AuthPasswordPutData> {
 	const client = ensureReq();
 	try {
-		const env = await client.put(`auth/password`, { json: body }).json<OjEnvelope<unknown>>();
+		const env = await client.put(`auth/password`, { json: body }).json<OjEnvelope<AuthPasswordPutData>>();
 		// 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 AuthPasswordPutData;
+		if (import.meta.env.DEV) {
+			const { schemas } = await import("./api.schemas");
+			const r = schemas["authPasswordPut"].data.safeParse(data);
+			if (!r.success)
+				throw new ContractApiError(-1, `[契约违例] authPasswordPut 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+		}
 		return data;
 	}
 	catch (e) {
@@ -126,14 +160,23 @@ export async function authPasswordPut(body: AuthPasswordPutBody): Promise<unknow
 	}
 }
 
-export async function authLdapLoginPost(): Promise<unknown> {
+export type AuthLdapLoginPostBody = z.input<(typeof schemas)["authLdapLoginPost"]["body"]>;
+export type AuthLdapLoginPostData = z.infer<(typeof schemas)["authLdapLoginPost"]["data"]>;
+
+export async function authLdapLoginPost(body: AuthLdapLoginPostBody): Promise<AuthLdapLoginPostData> {
 	const client = ensureReq();
 	try {
-		const env = await client.post(`auth/ldap-login`).json<OjEnvelope<unknown>>();
+		const env = await client.post(`auth/ldap-login`, { json: body }).json<OjEnvelope<AuthLdapLoginPostData>>();
 		// 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 AuthLdapLoginPostData;
+		if (import.meta.env.DEV) {
+			const { schemas } = await import("./api.schemas");
+			const r = schemas["authLdapLoginPost"].data.safeParse(data);
+			if (!r.success)
+				throw new ContractApiError(-1, `[契约违例] authLdapLoginPost 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+		}
 		return data;
 	}
 	catch (e) {
@@ -164,6 +207,29 @@ export async function authWecomAdminAppsGet(): Promise<AuthWecomAdminAppsGetData
 	}
 }
 
+export type AuthWecomAdminOverviewGetData = z.infer<(typeof schemas)["authWecomAdminOverviewGet"]["data"]>;
+
+export async function authWecomAdminOverviewGet(): Promise<AuthWecomAdminOverviewGetData> {
+	const client = ensureReq();
+	try {
+		const env = await client.get(`auth/wecom/admin/overview`).json<OjEnvelope<AuthWecomAdminOverviewGetData>>();
+		// 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 AuthWecomAdminOverviewGetData;
+		if (import.meta.env.DEV) {
+			const { schemas } = await import("./api.schemas");
+			const r = schemas["authWecomAdminOverviewGet"].data.safeParse(data);
+			if (!r.success)
+				throw new ContractApiError(-1, `[契约违例] authWecomAdminOverviewGet 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+		}
+		return data;
+	}
+	catch (e) {
+		throw await toApiError(e);
+	}
+}
+
 export type AuthWecomAdminStatusPostBody = z.input<(typeof schemas)["authWecomAdminStatusPost"]["body"]>;
 export type AuthWecomAdminStatusPostData = z.infer<(typeof schemas)["authWecomAdminStatusPost"]["data"]>;
 
@@ -211,21 +277,21 @@ export async function authWecomAdminInstallGet(): Promise<AuthWecomAdminInstallG
 	}
 }
 
-export type AuthWecomAdminOverviewGetData = z.infer<(typeof schemas)["authWecomAdminOverviewGet"]["data"]>;
+export type AuthWecomAdminConnectPostData = z.infer<(typeof schemas)["authWecomAdminConnectPost"]["data"]>;
 
-export async function authWecomAdminOverviewGet(): Promise<AuthWecomAdminOverviewGetData> {
+export async function authWecomAdminConnectPost(): Promise<AuthWecomAdminConnectPostData> {
 	const client = ensureReq();
 	try {
-		const env = await client.get(`auth/wecom/admin/overview`).json<OjEnvelope<AuthWecomAdminOverviewGetData>>();
+		const env = await client.post(`auth/wecom/admin/connect`).json<OjEnvelope<AuthWecomAdminConnectPostData>>();
 		// 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 AuthWecomAdminOverviewGetData;
+		const data = env.data as AuthWecomAdminConnectPostData;
 		if (import.meta.env.DEV) {
 			const { schemas } = await import("./api.schemas");
-			const r = schemas["authWecomAdminOverviewGet"].data.safeParse(data);
+			const r = schemas["authWecomAdminConnectPost"].data.safeParse(data);
 			if (!r.success)
-				throw new ContractApiError(-1, `[契约违例] authWecomAdminOverviewGet 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+				throw new ContractApiError(-1, `[契约违例] authWecomAdminConnectPost 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
 		}
 		return data;
 	}
@@ -234,21 +300,46 @@ export async function authWecomAdminOverviewGet(): Promise<AuthWecomAdminOvervie
 	}
 }
 
-export type AuthWecomAdminConnectPostData = z.infer<(typeof schemas)["authWecomAdminConnectPost"]["data"]>;
+export type AuthWecomAdminTenantAdminGetQuery = z.input<(typeof schemas)["authWecomAdminTenantAdminGet"]["query"]>;
+export type AuthWecomAdminTenantAdminGetData = z.infer<(typeof schemas)["authWecomAdminTenantAdminGet"]["data"]>;
 
-export async function authWecomAdminConnectPost(): Promise<AuthWecomAdminConnectPostData> {
+export async function authWecomAdminTenantAdminGet(query: AuthWecomAdminTenantAdminGetQuery): Promise<AuthWecomAdminTenantAdminGetData> {
 	const client = ensureReq();
 	try {
-		const env = await client.post(`auth/wecom/admin/connect`).json<OjEnvelope<AuthWecomAdminConnectPostData>>();
+		const env = await client.get(`auth/wecom/admin/tenant-admin`, { searchParams: query as Record<string, string | number | boolean> }).json<OjEnvelope<AuthWecomAdminTenantAdminGetData>>();
 		// 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 AuthWecomAdminConnectPostData;
+		const data = env.data as AuthWecomAdminTenantAdminGetData;
 		if (import.meta.env.DEV) {
 			const { schemas } = await import("./api.schemas");
-			const r = schemas["authWecomAdminConnectPost"].data.safeParse(data);
+			const r = schemas["authWecomAdminTenantAdminGet"].data.safeParse(data);
 			if (!r.success)
-				throw new ContractApiError(-1, `[契约违例] authWecomAdminConnectPost 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+				throw new ContractApiError(-1, `[契约违例] authWecomAdminTenantAdminGet 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+		}
+		return data;
+	}
+	catch (e) {
+		throw await toApiError(e);
+	}
+}
+
+export type AuthWecomAdminTenantAdminPasswordPostBody = z.input<(typeof schemas)["authWecomAdminTenantAdminPasswordPost"]["body"]>;
+export type AuthWecomAdminTenantAdminPasswordPostData = z.infer<(typeof schemas)["authWecomAdminTenantAdminPasswordPost"]["data"]>;
+
+export async function authWecomAdminTenantAdminPasswordPost(body: AuthWecomAdminTenantAdminPasswordPostBody): Promise<AuthWecomAdminTenantAdminPasswordPostData> {
+	const client = ensureReq();
+	try {
+		const env = await client.post(`auth/wecom/admin/tenant-admin/password`, { json: body }).json<OjEnvelope<AuthWecomAdminTenantAdminPasswordPostData>>();
+		// 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 AuthWecomAdminTenantAdminPasswordPostData;
+		if (import.meta.env.DEV) {
+			const { schemas } = await import("./api.schemas");
+			const r = schemas["authWecomAdminTenantAdminPasswordPost"].data.safeParse(data);
+			if (!r.success)
+				throw new ContractApiError(-1, `[契约违例] authWecomAdminTenantAdminPasswordPost 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
 		}
 		return data;
 	}
@@ -288,15 +379,22 @@ export async function authWecomCallbackGet(): Promise<unknown> {
 }
 
 export type AuthWecomTicketPostBody = z.input<(typeof schemas)["authWecomTicketPost"]["body"]>;
+export type AuthWecomTicketPostData = z.infer<(typeof schemas)["authWecomTicketPost"]["data"]>;
 
-export async function authWecomTicketPost(body: AuthWecomTicketPostBody): Promise<unknown> {
+export async function authWecomTicketPost(body: AuthWecomTicketPostBody): Promise<AuthWecomTicketPostData> {
 	const client = ensureReq();
 	try {
-		const env = await client.post(`auth/wecom/ticket`, { json: body }).json<OjEnvelope<unknown>>();
+		const env = await client.post(`auth/wecom/ticket`, { json: body }).json<OjEnvelope<AuthWecomTicketPostData>>();
 		// 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 AuthWecomTicketPostData;
+		if (import.meta.env.DEV) {
+			const { schemas } = await import("./api.schemas");
+			const r = schemas["authWecomTicketPost"].data.safeParse(data);
+			if (!r.success)
+				throw new ContractApiError(-1, `[契约违例] authWecomTicketPost 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+		}
 		return data;
 	}
 	catch (e) {

package/templates/src/notification/api/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/del/api.ts

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

package/templates/src/system/api/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/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/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/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/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/users/roles/api.ts

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

package/templates/src/web/api/get-async-routes/api.ts

@@ -1,8 +1,23 @@
 // GET /api/web/get-async-routes —— 后端动态路由（Bearer 守卫保护）。
 // demo 返回空数组：模块路由由 web/src 静态注入；需要后端路由时按
 // 宿主 RouteObject 形状返回。
-export default {
+const handler = {
 	get() {
 		json.ok([]);
 	},
 };
+
+// 出参：宿主 RouteObject 形状的数组（demo 恒空数组；页面路由由前端静态注入）
+handler.get.response = {
+	type: "array",
+	items: {
+		type: "object",
+		properties: {
+			path: { type: "string" },
+			component: { type: "string" },
+			children: { type: "array", items: { type: "object" } },
+		},
+	},
+};
+
+export default handler;

package/templates/src/web/api/hello/api.ts

@@ -1,6 +1,6 @@
 // GET /api/web/hello —— 演示业务端点（Bearer 守卫保护）。
 // 改完保存即生效（oj dev/ts 热更）；新增/删除模块目录需重启 ojm dev。
-export default {
+const handler = {
 	get() {
 		json.ok({
 			message: "hello from oj",
@@ -8,3 +8,15 @@ export default {
 		});
 	},
 };
+
+// 出参：演示端点（hello 文案 + 当前用户 id）
+handler.get.response = {
+	type: "object",
+	required: ["message", "user"],
+	properties: {
+		message: { type: "string" },
+		user: { type: ["number", "null"] },
+	},
+};
+
+export default handler;