@oj-module/cli 0.2.53 → 0.2.56

package/templates/src/{auth/web → app/web/auth}/__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 → app/web/auth/__client/index.ts}

@@ -17,6 +17,9 @@ export const API_PREFIX = "/auth";
 /** 认领身份前缀（契约 apiPrefix，字面等于模块目录名）：跨模块认领护栏对比基准 */
 export const MODULE_PREFIX = "/auth";
 
+/** 认领方模块（web.config clientOwners 指定）：跨模块认领护栏对比基准 */
+export const MODULE_OWNER = "/app";
+
 /**
  * 模块 entry 的 onInit 里一行创建（构造即 install）：完成 apiPrefix 登记 +
  * scoped request 绑定，返回绑好前缀的端点函数集合。一模块一 client；
@@ -28,12 +31,12 @@ export function createAuthClient(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 { 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 +67,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 +91,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 +115,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 +140,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 +163,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 +210,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 +280,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 +303,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 +382,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/app/web/entry.ts

@@ -0,0 +1,77 @@
+import type { ModuleContext, ModuleI18n } from "@oj-module/runtime";
+import { defineModule } from "@oj-module/runtime";
+
+import { routes as homeRoutes } from "./home/routes";
+import { onInit as loginOnInit, routes as loginRoutes } from "./login/routes";
+import { onInit as notificationOnInit, routes as notificationRoutes } from "./notification/routes";
+import { onInit as personalCenterOnInit, routes as personalCenterRoutes } from "./personal-center/routes";
+import { onInit as systemOnInit, routes as systemRoutes } from "./system/routes";
+
+/**
+ * 应用模块（多根聚合）：一个 entry 承载六个业务根，各根独立成一级菜单。
+ *
+ * 为什么聚合：这六个根（首页/登录/个人中心/通知/系统管理）是脚手架的框架内置页面，
+ * 同版本发布、同生命周期、缺一不可，拆成六个模块只会把工程目录、web.config 登记、
+ * modules.json 与首屏模块入口请求都放大六倍。聚合后仍是「一目录一模块」，但模块内
+ * 按根分目录（`<root>/routes.ts` + `pages/` + `__client/`），页面相对导入不变。
+ *
+ * 结构约定（多根模块）：
+ *   - 顶层路由首段去重 > 1 → runtime 判为多根（`isMultiRoot`），各根按 entry 里的
+ *     **绝对路径**原样注册，不被 `routePrefix` 改写——URL 与菜单 key 都不变；
+ *   - 菜单顺序仍由各根 `handle.order` 决定（≥0 主区升序、<0 底部固定区），与聚合前
+ *     逐项一致；改顺序只改 order，不要依赖 routes 数组下标（缺省 order 会按数组下标兜底）；
+ *   - 门禁挂根路由：`/system` 的 `handle.roles` 等价于原先的模块级 requiredRoles。
+ *
+ * i18n 用 `i18nNamespaces` 沿用各根**原命名空间**（home / login / personal-center /
+ * notification / system），因此 `t("system:menu.users")`、`useTranslation("system")`
+ * 与菜单标题 `<ns>:menu.<key>` 全部零改动。
+ */
+const i18nNamespaces: Record<string, ModuleI18n> = {
+	"home": {
+		"zh-CN": () => import("./home/locales/zh-CN.json"),
+		"en-US": () => import("./home/locales/en-US.json"),
+	},
+	"login": {
+		"zh-CN": () => import("./login/locales/zh-CN.json"),
+		"en-US": () => import("./login/locales/en-US.json"),
+	},
+	"personal-center": {
+		"zh-CN": () => import("./personal-center/locales/zh-CN.json"),
+		"en-US": () => import("./personal-center/locales/en-US.json"),
+	},
+	"notification": {
+		"zh-CN": () => import("./notification/locales/zh-CN.json"),
+		"en-US": () => import("./notification/locales/en-US.json"),
+	},
+	"system": {
+		"zh-CN": () => import("./system/locales/zh-CN.json"),
+		"en-US": () => import("./system/locales/en-US.json"),
+	},
+};
+
+export default defineModule({
+	name: "app",
+	description: "应用模块：框架内置页面（首页/登录/个人中心/通知/系统管理），多根聚合",
+	version: "0.1.0",
+	peerRuntime: ">=0.0.0",
+	routes: [
+		...homeRoutes,
+		...loginRoutes,
+		...personalCenterRoutes,
+		...notificationRoutes,
+		...systemRoutes,
+	],
+	i18nNamespaces,
+	lifecycle: {
+		/**
+		 * 各根的 onInit 按原模块加载顺序串行——login 必须最先（认证 provider 要在任何
+		 * 登录动作前就位），其余是前缀登记/API provider 注入，顺序无相互依赖。
+		 */
+		async onInit(ctx: ModuleContext) {
+			await loginOnInit(ctx);
+			await personalCenterOnInit(ctx);
+			await notificationOnInit(ctx);
+			await systemOnInit(ctx);
+		},
+	},
+});

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

@@ -17,6 +17,9 @@ export const API_PREFIX = "/home";
 /** 认领身份前缀（契约 apiPrefix，字面等于模块目录名）：跨模块认领护栏对比基准 */
 export const MODULE_PREFIX = "/home";
 
+/** 认领方模块（web.config clientOwners 指定）：跨模块认领护栏对比基准 */
+export const MODULE_OWNER = "/app";
+
 /**
  * 模块 entry 的 onInit 里一行创建（构造即 install）：完成 apiPrefix 登记 +
  * scoped request 绑定，返回绑好前缀的端点函数集合。一模块一 client；
@@ -28,8 +31,8 @@ export function createHomeClient(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);

package/templates/src/app/web/home/routes.ts

@@ -0,0 +1,41 @@
+import type { AppRouteRecordRaw } from "@oj-module/runtime";
+
+import { HomeOutlined } from "@ant-design/icons";
+
+import { createElement, lazy } from "react";
+
+const Home = lazy(() => import("./pages/index"));
+
+/**
+ * 首页根 `/home`。
+ *
+ * 为什么必须有：shell 预构建产物把 `VITE_BASE_HOME_PATH` 定为 `/home`
+ * （登录成功回跳、logo 点击、tabbar 首页、403/404 回首页都指向它）。
+ * 工程缺 `/home` 路由时这些跳转会落到错误边界。
+ *
+ * 结构对齐 playground-oj/web/src/home；页面用统计卡片 + 折线/柱/饼图
+ * 演示宿主共享依赖矩阵（echarts / echarts-for-react / react-countup / dayjs /
+ * antd / @ant-design/icons / react-i18next，均由宿主 importmap 提供单例）。
+ * 图表数据为静态演示值——真实业务走模块契约 + `ojm api` 生成的 client。
+ */
+export const routes: AppRouteRecordRaw[] = [
+	{
+		path: "/home",
+		handle: {
+			layout: "container",
+			order: 1,
+			title: "home:menu.home",
+			icon: createElement(HomeOutlined),
+		},
+		children: [
+			{
+				index: true,
+				Component: Home,
+				handle: {
+					title: "home:menu.home",
+					icon: createElement(HomeOutlined),
+				},
+			},
+		],
+	},
+];