@oj-module/cli 0.2.53 → 0.2.54

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 → app/web/home}/__client/api.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),
+				},
+			},
+		],
+	},
+];

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

@@ -0,0 +1,71 @@
+import type { AppRouteRecordRaw, ModuleContext } from "@oj-module/runtime";
+
+import { useAuthStore, useTenantStore } from "@oj-module/runtime";
+import { lazy } from "react";
+
+import { authProvider } from "./auth-provider";
+
+/**
+ * 登录根 `/login`（+ 强制改密 `/change-password`）。
+ *
+ * shell 宿主只消费模块路由（`getRoutes()`），**不挂 runtime 的内置 baseRoutes**，
+ * 因此缺少该根时 `/login` 无路由可跳（登出/回跳登录会落空）。本根补上路由：
+ * 登录链路仍回落到 runtime 默认链（`fetchLogin` → 后端内置 `auth/login` +
+ * 守卫 `getUserInfo` → `web/user-info`），本根只负责「内容区」。
+ *
+ * `handle.login: true` 让框架识别为登录页（`resolveLoginRoute` 校验路径必须是
+ * `/login`）；`handle.layout: "fullscreen"` 由框架注入全屏外壳。
+ */
+export const routes: AppRouteRecordRaw[] = [
+	{
+		path: "/login",
+		handle: {
+			layout: "fullscreen",
+			login: true,
+			hideInMenu: true,
+			title: "login:page.title",
+		},
+		children: [
+			{
+				index: true,
+				Component: lazy(() => import("./pages/login")),
+				handle: { title: "login:page.title" },
+			},
+		],
+	},
+	{
+		// 首登/重置后强制改密（must_change 悬挂期唯一可用写端）；
+		// 管理面 403 msg=password change required 时也引导至此
+		path: "/change-password",
+		handle: {
+			layout: "fullscreen",
+			hideInMenu: true,
+			title: "login:page.changePwd.title",
+		},
+		children: [
+			{
+				index: true,
+				Component: lazy(() => import("./pages/change-password")),
+				handle: { title: "login:page.changePwd.title", hideInMenu: true },
+			},
+		],
+	},
+];
+
+/**
+ * 认证 provider：仅接管「企微票据换会话」，其余方式原样委托内置链（见 auth-provider.ts）。
+ * 注册时机必须在任何登录动作之前——onInit 先于路由渲染。
+ */
+export async function onInit(ctx: ModuleContext) {
+	ctx.register.authProvider(authProvider);
+	// 登出必须清租户：否则下一个用户会带着上一个用户的租户头（跨租户请求 fail-closed 403，
+	// 但单租户部署会静默落到别人的 default 视图）。token 由非空转空即视为登出。
+	//
+	// 租户上下文的请求头由**运行时**注入（`runtime/store/tenant.ts`），本根不注册
+	// headerProvider——宿主 shell 的 hydrateUser / solution-routes 都在任何模块 onInit
+	// 之前就发请求，模块注册必然晚一步（2026-10-30 冷启动 e2e 实测两个 400）。
+	useAuthStore.subscribe((state, prev) => {
+		if (prev.token && !state.token)
+			useTenantStore.getState().clear();
+	});
+}

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

@@ -21,6 +21,13 @@ export const schemas = {
 		body: z.object({
 	"id": z.string()
 }),
+		data: z.null(),
+	},
+	"notificationNotificationsReadAllPost": {
+		data: z.null(),
+	},
+	"notificationNotificationsClearPost": {
+		data: z.null(),
 	},
 	"notificationPushPost": {
 		body: z.object({
@@ -30,6 +37,9 @@ export const schemas = {
 	"link": z.string().optional(),
 	"avatar": z.string().optional(),
 	"category": z.enum(["notice", "pm", "mention"]).optional()
+}),
+		data: z.object({
+	"id": z.string()
 }),
 	},
 	"notificationPushBroadcastPost": {
@@ -39,6 +49,9 @@ export const schemas = {
 	"link": z.string().optional(),
 	"avatar": z.string().optional(),
 	"category": z.enum(["notice", "pm", "mention"]).optional()
+}),
+		data: z.object({
+	"id": z.string()
 }),
 	},
 	"notificationDelPost": {
@@ -46,5 +59,6 @@ export const schemas = {
 	"id": z.string(),
 	"userId": z.union([z.string(), z.number()]).optional()
 }),
+		data: z.null(),
 	},
 };

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

@@ -17,6 +17,9 @@ export const API_PREFIX = "/notification";
 /** 认领身份前缀（契约 apiPrefix，字面等于模块目录名）：跨模块认领护栏对比基准 */
 export const MODULE_PREFIX = "/notification";
 
+/** 认领方模块（web.config clientOwners 指定）：跨模块认领护栏对比基准 */
+export const MODULE_OWNER = "/app";
+
 /**
  * 模块 entry 的 onInit 里一行创建（构造即 install）：完成 apiPrefix 登记 +
  * scoped request 绑定，返回绑好前缀的端点函数集合。一模块一 client；
@@ -28,8 +31,8 @@ export function createNotificationClient(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);
@@ -88,15 +91,22 @@ export async function notificationNotificationsGet(): Promise<NotificationNotifi
 }
 
 export type NotificationNotificationsReadPostBody = z.input<(typeof schemas)["notificationNotificationsReadPost"]["body"]>;
+export type NotificationNotificationsReadPostData = z.infer<(typeof schemas)["notificationNotificationsReadPost"]["data"]>;
 
-export async function notificationNotificationsReadPost(body: NotificationNotificationsReadPostBody): Promise<unknown> {
+export async function notificationNotificationsReadPost(body: NotificationNotificationsReadPostBody): Promise<NotificationNotificationsReadPostData> {
 	const client = ensureReq();
 	try {
-		const env = await client.post(`notification/notifications/read`, { json: body }).json<OjEnvelope<unknown>>();
+		const env = await client.post(`notification/notifications/read`, { json: body }).json<OjEnvelope<NotificationNotificationsReadPostData>>();
 		// 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 NotificationNotificationsReadPostData;
+		if (import.meta.env.DEV) {
+			const { schemas } = await import("./api.schemas");
+			const r = schemas["notificationNotificationsReadPost"].data.safeParse(data);
+			if (!r.success)
+				throw new ContractApiError(-1, `[契约违例] notificationNotificationsReadPost 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+		}
 		return data;
 	}
 	catch (e) {
@@ -104,14 +114,22 @@ export async function notificationNotificationsReadPost(body: NotificationNotifi
 	}
 }
 
-export async function notificationNotificationsReadAllPost(): Promise<unknown> {
+export type NotificationNotificationsReadAllPostData = z.infer<(typeof schemas)["notificationNotificationsReadAllPost"]["data"]>;
+
+export async function notificationNotificationsReadAllPost(): Promise<NotificationNotificationsReadAllPostData> {
 	const client = ensureReq();
 	try {
-		const env = await client.post(`notification/notifications/read-all`).json<OjEnvelope<unknown>>();
+		const env = await client.post(`notification/notifications/read-all`).json<OjEnvelope<NotificationNotificationsReadAllPostData>>();
 		// 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 NotificationNotificationsReadAllPostData;
+		if (import.meta.env.DEV) {
+			const { schemas } = await import("./api.schemas");
+			const r = schemas["notificationNotificationsReadAllPost"].data.safeParse(data);
+			if (!r.success)
+				throw new ContractApiError(-1, `[契约违例] notificationNotificationsReadAllPost 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+		}
 		return data;
 	}
 	catch (e) {
@@ -119,14 +137,22 @@ export async function notificationNotificationsReadAllPost(): Promise<unknown> {
 	}
 }
 
-export async function notificationNotificationsClearPost(): Promise<unknown> {
+export type NotificationNotificationsClearPostData = z.infer<(typeof schemas)["notificationNotificationsClearPost"]["data"]>;
+
+export async function notificationNotificationsClearPost(): Promise<NotificationNotificationsClearPostData> {
 	const client = ensureReq();
 	try {
-		const env = await client.post(`notification/notifications/clear`).json<OjEnvelope<unknown>>();
+		const env = await client.post(`notification/notifications/clear`).json<OjEnvelope<NotificationNotificationsClearPostData>>();
 		// 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 NotificationNotificationsClearPostData;
+		if (import.meta.env.DEV) {
+			const { schemas } = await import("./api.schemas");
+			const r = schemas["notificationNotificationsClearPost"].data.safeParse(data);
+			if (!r.success)
+				throw new ContractApiError(-1, `[契约违例] notificationNotificationsClearPost 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+		}
 		return data;
 	}
 	catch (e) {
@@ -135,15 +161,22 @@ export async function notificationNotificationsClearPost(): Promise<unknown> {
 }
 
 export type NotificationPushPostBody = z.input<(typeof schemas)["notificationPushPost"]["body"]>;
+export type NotificationPushPostData = z.infer<(typeof schemas)["notificationPushPost"]["data"]>;
 
-export async function notificationPushPost(body: NotificationPushPostBody): Promise<unknown> {
+export async function notificationPushPost(body: NotificationPushPostBody): Promise<NotificationPushPostData> {
 	const client = ensureReq();
 	try {
-		const env = await client.post(`notification/push`, { json: body }).json<OjEnvelope<unknown>>();
+		const env = await client.post(`notification/push`, { json: body }).json<OjEnvelope<NotificationPushPostData>>();
 		// 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 NotificationPushPostData;
+		if (import.meta.env.DEV) {
+			const { schemas } = await import("./api.schemas");
+			const r = schemas["notificationPushPost"].data.safeParse(data);
+			if (!r.success)
+				throw new ContractApiError(-1, `[契约违例] notificationPushPost 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+		}
 		return data;
 	}
 	catch (e) {
@@ -152,15 +185,22 @@ export async function notificationPushPost(body: NotificationPushPostBody): Prom
 }
 
 export type NotificationPushBroadcastPostBody = z.input<(typeof schemas)["notificationPushBroadcastPost"]["body"]>;
+export type NotificationPushBroadcastPostData = z.infer<(typeof schemas)["notificationPushBroadcastPost"]["data"]>;
 
-export async function notificationPushBroadcastPost(body: NotificationPushBroadcastPostBody): Promise<unknown> {
+export async function notificationPushBroadcastPost(body: NotificationPushBroadcastPostBody): Promise<NotificationPushBroadcastPostData> {
 	const client = ensureReq();
 	try {
-		const env = await client.post(`notification/push-broadcast`, { json: body }).json<OjEnvelope<unknown>>();
+		const env = await client.post(`notification/push-broadcast`, { json: body }).json<OjEnvelope<NotificationPushBroadcastPostData>>();
 		// 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 NotificationPushBroadcastPostData;
+		if (import.meta.env.DEV) {
+			const { schemas } = await import("./api.schemas");
+			const r = schemas["notificationPushBroadcastPost"].data.safeParse(data);
+			if (!r.success)
+				throw new ContractApiError(-1, `[契约违例] notificationPushBroadcastPost 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+		}
 		return data;
 	}
 	catch (e) {
@@ -169,15 +209,22 @@ export async function notificationPushBroadcastPost(body: NotificationPushBroadc
 }
 
 export type NotificationDelPostBody = z.input<(typeof schemas)["notificationDelPost"]["body"]>;
+export type NotificationDelPostData = z.infer<(typeof schemas)["notificationDelPost"]["data"]>;
 
-export async function notificationDelPost(body: NotificationDelPostBody): Promise<unknown> {
+export async function notificationDelPost(body: NotificationDelPostBody): Promise<NotificationDelPostData> {
 	const client = ensureReq();
 	try {
-		const env = await client.post(`notification/del`, { json: body }).json<OjEnvelope<unknown>>();
+		const env = await client.post(`notification/del`, { json: body }).json<OjEnvelope<NotificationDelPostData>>();
 		// 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 NotificationDelPostData;
+		if (import.meta.env.DEV) {
+			const { schemas } = await import("./api.schemas");
+			const r = schemas["notificationDelPost"].data.safeParse(data);
+			if (!r.success)
+				throw new ContractApiError(-1, `[契约违例] notificationDelPost 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+		}
 		return data;
 	}
 	catch (e) {

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

@@ -0,0 +1,70 @@
+import type { AppRouteRecordRaw, ModuleContext, NotificationsApiProvider } from "@oj-module/runtime";
+
+import { BellOutlined } from "@ant-design/icons";
+
+import { createElement, lazy } from "react";
+
+import { createNotificationClient } from "./__client/api";
+
+const NotificationCenter = lazy(() => import("./pages/center"));
+
+/**
+ * 通知中心页（N3）：全量消息 + 类型 Tab，铃铛弹层「查看全部」跳转至此。
+ * hideInMenu——入口在铃铛，不占侧边导航。
+ * 布局挂父路由 handle（resolveRouteLayouts 只给「无 Component 有 children」的
+ * 父路由注入 layout，页面组件写父级上布局会被忽略、裸渲染无 chrome）。
+ */
+export const routes: AppRouteRecordRaw[] = [
+	{
+		path: "/notification-center",
+		handle: {
+			layout: "container",
+			title: "notification:menu.notificationCenter",
+			icon: createElement(BellOutlined),
+			hideInMenu: true,
+		},
+		children: [
+			{
+				index: true,
+				Component: NotificationCenter,
+				handle: {
+					title: "notification:menu.notificationCenter",
+					icon: createElement(BellOutlined),
+				},
+			},
+		],
+	},
+];
+
+/**
+ * 通知聚合的唯一前端消费面（G5 模板形态）。
+ *
+ * onInit 全量接管通知 API（D9 + G4）：把通知读/写收敛到本模块 `/notification`
+ * 前缀下的 oj 后端，通知铃的互动（单条已读/全部已读/清空）由此生效；发射端
+ * 三方法（push/pushBroadcast/del）使本模块同时作为跨模块通知原语的接收端
+ * （前端 facade 委托至此）。
+ */
+export async function onInit(ctx: ModuleContext) {
+	// 构造即接线：createNotificationClient 登记契约前缀 /notification
+	// （唯一真源在 __client/api.ts 的 API_PREFIX）+ 绑定圈好前缀的 scoped
+	// request（越界/穿越发请求前即拒绝，前缀收敛 D11），返回的 client
+	// 方法都自动带 /api/notification/ 前缀。
+	const notificationClient = createNotificationClient(ctx);
+	const provider: NotificationsApiProvider = {
+		// 端点函数名由 oj operationId 派生（camelCase 子路径 + 方法），
+		// 见 __client/api.ts；provider 方法名（fetchNotifications/markRead…）不变。
+		fetchNotifications: () => notificationClient.notificationNotificationsGet(),
+		// id 为命名空间串（"u:<id>" / "b:<id>"），原样透传
+		markRead: id => notificationClient.notificationNotificationsReadPost({ id: String(id) }).then(() => {}),
+		markAllRead: () => notificationClient.notificationNotificationsReadAllPost().then(() => {}),
+		clearAll: () => notificationClient.notificationNotificationsClearPost().then(() => {}),
+		push: input => notificationClient
+			.notificationPushPost({ userId: input.userId, title: input.title, message: input.message, link: input.link, avatar: input.avatar, category: input.category })
+			.then(r => String((r as { id: string }).id)),
+		pushBroadcast: input => notificationClient
+			.notificationPushBroadcastPost({ title: input.title, message: input.message, link: input.link, avatar: input.avatar, category: input.category })
+			.then(r => String((r as { id: string }).id)),
+		del: (id, userId) => notificationClient.notificationDelPost({ id: String(id), userId }).then(() => {}),
+	};
+	ctx.register.notificationsApi(provider);
+}

package/templates/src/{personal-center/web → app/web/personal-center}/__client/api.ts

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

@@ -0,0 +1,49 @@
+import type { AppRouteRecordRaw, ModuleContext, UploadApiProvider } from "@oj-module/runtime";
+import { ProfileCardIcon, RiAccountCircleLine, useAuthStore } from "@oj-module/runtime";
+
+import { createElement, lazy } from "react";
+
+import { createPersonalCenterClient } from "./__client/api";
+
+const MyProfile = lazy(() => import("./pages/my-profile"));
+
+/** 个人中心根 `/personal-center`：runtime 用户菜单固定导航 `/personal-center/my-profile`，缺则点击落空。 */
+export const routes: AppRouteRecordRaw[] = [
+	{
+		path: "/personal-center",
+		handle: {
+			layout: "container",
+			order: 110,
+			title: "personal-center:menu.personalCenter",
+			icon: createElement(RiAccountCircleLine),
+		},
+		children: [
+			{
+				path: "/personal-center/my-profile",
+				Component: MyProfile,
+				handle: {
+					title: "personal-center:menu.profile",
+					icon: createElement(ProfileCardIcon),
+				},
+			},
+		],
+	},
+];
+
+/**
+ * P4-3：接管头像上传端点（D9）。antd Upload 直连 action，headers 在上传瞬间
+ * 取当前 token 注入 Bearer（token 存 runtime auth store，跨渲染期读 getState）。
+ */
+export async function onInit(ctx: ModuleContext) {
+	// 构造即接线：登记契约前缀 /personal-center + 绑定 scoped request，
+	// 页面直接 import 的 personalCenterProfilePost 才有可用的请求通道
+	createPersonalCenterClient(ctx);
+	const provider: UploadApiProvider = {
+		action: "/api/personal-center/upload",
+		headers: (): Record<string, string> => {
+			const token = useAuthStore.getState().token;
+			return token ? { Authorization: `Bearer ${token}` } : {};
+		},
+	};
+	ctx.register.uploadApi(provider);
+}