@oj-module/cli 0.2.53 → 0.2.54

package/templates/src/web/api/user-info/api.ts

@@ -2,7 +2,7 @@
 // B4：roles 出自 sys_user_role 权威源（users.roles JSON 列已被 0003 移除，D10）——
 // 体验层角色走本资料接口，不进 JWT claims；avatar 读 avatar_base64，email 读 0007 迁移列。
 // 响应一律走 json.ok/json.fail 信封（oj 红线）。
-export default {
+const handler = {
 	async get() {
 		const uid = http.user?.id;
 		if (!uid) {
@@ -35,3 +35,23 @@ export default {
 		}
 	},
 };
+
+// 出参：登录链用户资料（roles 出自 sys_user_role，permissions 预留恒空）
+handler.get.response = {
+	type: "object",
+	required: ["id", "avatar", "username", "displayName", "email", "phoneNumber", "description", "roles", "mustChange", "permissions"],
+	properties: {
+		id: { type: "string" },
+		avatar: { type: "string" },
+		username: { type: "string" },
+		displayName: { type: "string" },
+		email: { type: "string" },
+		phoneNumber: { type: "string" },
+		description: { type: "string" },
+		roles: { type: "array", items: { type: "string" } },
+		mustChange: { type: "boolean" },
+		permissions: { type: "array", items: { type: "string" } },
+	},
+};
+
+export default handler;

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

@@ -4,5 +4,33 @@
 import { z } from "@oj-module/runtime";
 
 export const schemas = {
+	"webGetAsyncRoutesGet": {
+		data: z.array(z.object({
+	"path": z.string().optional(),
+	"component": z.string().optional(),
+	"children": z.array(z.object({
 
+})).optional()
+})),
+	},
+	"webHelloGet": {
+		data: z.object({
+	"message": z.string(),
+	"user": z.number().nullable()
+}),
+	},
+	"webUserInfoGet": {
+		data: z.object({
+	"id": z.string(),
+	"avatar": z.string(),
+	"username": z.string(),
+	"displayName": z.string(),
+	"email": z.string(),
+	"phoneNumber": z.string(),
+	"description": z.string(),
+	"roles": z.array(z.string()),
+	"mustChange": z.boolean(),
+	"permissions": z.array(z.string())
+}),
+	},
 };

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

@@ -64,14 +64,22 @@ async function toApiError(e: unknown): Promise<unknown> {
 	return e;
 }
 
-export async function webGetAsyncRoutesGet(): Promise<unknown> {
+export type WebGetAsyncRoutesGetData = z.infer<(typeof schemas)["webGetAsyncRoutesGet"]["data"]>;
+
+export async function webGetAsyncRoutesGet(): Promise<WebGetAsyncRoutesGetData> {
 	const client = ensureReq();
 	try {
-		const env = await client.get(`web/get-async-routes`).json<OjEnvelope<unknown>>();
+		const env = await client.get(`web/get-async-routes`).json<OjEnvelope<WebGetAsyncRoutesGetData>>();
 		// 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 WebGetAsyncRoutesGetData;
+		if (import.meta.env.DEV) {
+			const { schemas } = await import("./api.schemas");
+			const r = schemas["webGetAsyncRoutesGet"].data.safeParse(data);
+			if (!r.success)
+				throw new ContractApiError(-1, `[契约违例] webGetAsyncRoutesGet 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+		}
 		return data;
 	}
 	catch (e) {
@@ -79,14 +87,22 @@ export async function webGetAsyncRoutesGet(): Promise<unknown> {
 	}
 }
 
-export async function webHelloGet(): Promise<unknown> {
+export type WebHelloGetData = z.infer<(typeof schemas)["webHelloGet"]["data"]>;
+
+export async function webHelloGet(): Promise<WebHelloGetData> {
 	const client = ensureReq();
 	try {
-		const env = await client.get(`web/hello`).json<OjEnvelope<unknown>>();
+		const env = await client.get(`web/hello`).json<OjEnvelope<WebHelloGetData>>();
 		// 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 WebHelloGetData;
+		if (import.meta.env.DEV) {
+			const { schemas } = await import("./api.schemas");
+			const r = schemas["webHelloGet"].data.safeParse(data);
+			if (!r.success)
+				throw new ContractApiError(-1, `[契约违例] webHelloGet 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+		}
 		return data;
 	}
 	catch (e) {
@@ -94,14 +110,22 @@ export async function webHelloGet(): Promise<unknown> {
 	}
 }
 
-export async function webUserInfoGet(): Promise<unknown> {
+export type WebUserInfoGetData = z.infer<(typeof schemas)["webUserInfoGet"]["data"]>;
+
+export async function webUserInfoGet(): Promise<WebUserInfoGetData> {
 	const client = ensureReq();
 	try {
-		const env = await client.get(`web/user-info`).json<OjEnvelope<unknown>>();
+		const env = await client.get(`web/user-info`).json<OjEnvelope<WebUserInfoGetData>>();
 		// 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 WebUserInfoGetData;
+		if (import.meta.env.DEV) {
+			const { schemas } = await import("./api.schemas");
+			const r = schemas["webUserInfoGet"].data.safeParse(data);
+			if (!r.success)
+				throw new ContractApiError(-1, `[契约违例] webUserInfoGet 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+		}
 		return data;
 	}
 	catch (e) {

package/templates/web.config.ts

@@ -10,24 +10,17 @@
  * 登记了不存在的前端入口才报错。
  *
  * 注意：这里的登记顺序只影响模块加载顺序，**不决定侧边栏导航顺序**——
- * 菜单顺序由各模块 entry 路由的 handle.order 决定（≥0 主菜单区升序；
- * <0 底部固定区，pin 在侧边栏底部；同 order 按根 path 字母序）。
- * `home` 必须第一个登记（shell 的 "/" 重定向到它）。
+ * 菜单顺序由各根路由的 handle.order 决定（≥0 主菜单区升序；<0 底部固定区，
+ * pin 在侧边栏底部；同 order 按根 path 字母序）。
  */
 const allModules = [
-	// /home 必须是首个模块：shell 的 "/" → VITE_BASE_HOME_PATH（=/home）重定向
-	{ name: "home", entry: "src/home/web/entry.ts" },
-	// /login 路由由模块提供：shell 宿主不挂 runtime 内置 baseRoutes
-	{ name: "login", entry: "src/login/web/entry.ts" },
-	// 个人中心：runtime 用户菜单固定导航 /personal-center/my-profile，缺则点击落空
-	{ name: "personal-center", entry: "src/personal-center/web/entry.ts" },
-	// 通知：onInit 注册 notificationsApi provider（四方法全必填），
-	// 通知铃的互动（单条已读/全部已读/清空）由此生效；未登记则永远回落内置只读兜底
-	{ name: "notification", entry: "src/notification/web/entry.ts" },
-	// 系统管理：用户/成员资格/角色权限/操作日志/站点设置/登录方式（oj 后端 /api/system/*）
-	{ name: "system", entry: "src/system/web/entry.ts" },
+	// 框架内置页面：首页/登录/个人中心/通知/系统管理聚合成**一个多根模块**。
+	// 各根按 handle.order 排序（/home 1、/personal-center 110、/system -100 底部），
+	// 与拆分时的菜单逐项一致；/login、/change-password、/notification-center 走 hideInMenu。
+	{ name: "app", entry: "src/app/web/entry.ts" },
 	// 解决方案市场：第一方能力（消费 _platform 编排面 /api/_platform/market/*，
-	// R29：第三方方案不得仿照此调用面），默认随脚手架下发
+	// R29：第三方方案不得仿照此调用面），默认随脚手架下发。保持独立模块——
+	// 可选能力，删目录即可下线。
 	{ name: "oj-market", entry: "src/oj-market/web/entry.ts" },
 	// #region demo-only
 	// 以下为模板内置的演示模块（about/access/exception/outside/route-nest），
@@ -49,4 +42,17 @@ export default {
 	/** 产物 URL 前缀，留空表示同源相对路径 */
 	baseUrl: "",
 	modules: allModules,
+	/**
+	 * 生成 client 的归属模块：`api 前缀 → 承载其 __client 的 web 模块`。
+	 *
+	 * 多根聚合模块把多个业务域的页面/client 收进 `src/app/web`，故五个 api 前缀的
+	 * 生成物都落在 `src/app/web/<api 前缀>/__client`（与页面同级，页面相对导入不变）。
+	 * 不配则回落同名模块（`src/<api 前缀>/web/__client`，历史行为）。
+	 */
+	clientOwners: {
+		"home": "app",
+		"personal-center": "app",
+		"notification": "app",
+		"system": "app",
+	},
 };

package/vendor/host-versions.json

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

package/templates/src/home/web/entry.ts

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

package/templates/src/login/web/entry.ts

@@ -1,79 +0,0 @@
-import { defineModule, useAuthStore, useTenantStore } from "@oj-module/runtime";
-import { lazy } from "react";
-import { authProvider } from "./auth-provider";
-
-/**
- * 登录模块：提供 `/login` 路由与内容区。
- *
- * shell 宿主只消费模块路由（`getRoutes()`），**不挂 runtime 的内置 baseRoutes**，
- * 因此缺少本模块时 `/login` 无路由可跳（登出/回跳登录会落空）。本模块补上该路由：
- * 登录链路仍回落到 runtime 默认链（`fetchLogin` → 后端内置 `auth/login` +
- * 守卫 `getUserInfo` → `web/user-info`），模块只负责「内容区」。
- *
- * `handle.login: true` 让框架识别为登录页（`resolveLoginRoute` 校验路径必须是
- * `/login`）；`handle.layout: "fullscreen"` 由框架注入全屏外壳。
- */
-export default defineModule({
-	name: "login",
-	description: "登录模块（内容区由模块提供，外壳由框架提供）",
-	version: "0.1.0",
-	peerRuntime: ">=0.0.0",
-	routes: [
-		{
-			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 },
-				},
-			],
-		},
-	],
-	i18n: {
-		"zh-CN": () => import("./locales/zh-CN.json"),
-		"en-US": () => import("./locales/en-US.json"),
-	},
-	lifecycle: {
-		/**
-		 * 租户上下文（L2）：请求头由**运行时**注入（`runtime/store/tenant.ts`），模块不再注册
-		 * headerProvider——宿主 shell 的 hydrateUser / solution-routes 都在任何模块 onInit 之前
-		 * 就发请求，模块注册必然晚一步（2026-10-30 冷启动 e2e 实测两个 400 missing tenant header）。
-		 * 模块这里只保留「登出清租户」这一业务语义。
-		 */
-		async onInit(ctx) {
-			// 认证 provider：仅接管「企微票据换会话」，其余方式原样委托内置链（见 auth-provider.ts）。
-			// 注册时机必须在任何登录动作之前——onInit 先于路由渲染。
-			ctx.register.authProvider(authProvider);
-			// 登出必须清租户：否则下一个用户会带着上一个用户的租户头（跨租户请求 fail-closed 403，
-			// 但单租户部署会静默落到别人的 default 视图）。token 由非空转空即视为登出。
-			useAuthStore.subscribe((state, prev) => {
-				if (prev.token && !state.token)
-					useTenantStore.getState().clear();
-			});
-		},
-	},
-});

package/templates/src/notification/web/entry.ts

@@ -1,84 +0,0 @@
-import type { AppRouteRecordRaw, NotificationsApiProvider } from "@oj-module/runtime";
-
-import { BellOutlined } from "@ant-design/icons";
-import { defineModule } from "@oj-module/runtime";
-
-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）。
- */
-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),
-				},
-			},
-		],
-	},
-];
-
-/**
- * notification 模块（G5 模板形态）：通知聚合的唯一前端消费面。
- *
- * onInit 全量接管通知 API（D9 + G4）：把通知读/写收敛到本模块 `/notification`
- * 前缀下的 oj 后端，通知铃的互动（单条已读/全部已读/清空）由此生效；发射端
- * 三方法（push/pushBroadcast/del）使本模块同时作为跨模块通知原语的接收端
- * （前端 facade 委托至此）。
- */
-export default defineModule({
-	name: "notification",
-	description: "通知模块（D9/G4 注入通知读写 + 通知中心页）",
-	version: "0.1.0",
-	peerRuntime: ">=0.0.0",
-	routes,
-	i18n: {
-		"zh-CN": () => import("./locales/zh-CN.json"),
-		"en-US": () => import("./locales/en-US.json"),
-	},
-	lifecycle: {
-		async onInit(ctx) {
-			// 构造即接线：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/entry.ts

@@ -1,60 +0,0 @@
-import type { AppRouteRecordRaw, ModuleDefinition, 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"));
-
-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),
-				},
-			},
-		],
-	},
-];
-
-const mod: ModuleDefinition = {
-	name: "personal-center",
-	description: "个人中心模块",
-	version: "0.1.0",
-	routes,
-	i18n: {
-		"zh-CN": () => import("./locales/zh-CN.json"),
-		"en-US": () => import("./locales/en-US.json"),
-	},
-	lifecycle: {
-		// P4-3：接管头像上传端点（D9）。antd Upload 直连 action，headers 在上传瞬间
-		// 取当前 token 注入 Bearer（token 存 runtime auth store，跨渲染期读 getState）。
-		async onInit(ctx) {
-			// 构造即接线：登记契约前缀 /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);
-		},
-	},
-};
-
-export default mod;