@oj-module/runtime 0.2.15 → 0.2.17

package/dist/index.d.ts

@@ -50,6 +50,18 @@ export { getAllExpandedKeys } from "./utils/get-all-expanded-keys";
 export { getAppInfo } from "./utils/get-app-info";
 export { getRedirectPath } from "./utils/get-redirect-path";
 export { request } from "./utils/request";
+/**
+ * 站点部署 base（子路径部署，2026-10-21）。
+ *
+ * 宿主把站点挂在非根前缀（oj `mounts: [{ prefix: /oj }]`）时，站内绝对 URL 必须
+ * 带该前缀。runtime 产物里的 `import.meta.env.BASE_URL` 是**包构建期**内联的 `/`，
+ * 只有部署期注入的 `window.__OJ_BASE__` 才是真值，故一律经 `resolveSiteBase()` 取值。
+ *
+ * - 模块侧拼「非路由」的站内绝对 URL（下载直链、`window.open`）用 `withSiteBase()`；
+ * - **路由跳转不要用它们**：`navigate` / `<Link>` 走路由空间，basename 已由
+ *   react-router 剥离，再拼一次会得到 `/oj/oj/wiki`。
+ */
+export { resolveSiteBase, withSiteBase } from "./utils/site-base";
 export * from "./utils/tree";
 export type { NoticeCategory, NoticeItem, PushBroadcastInput, PushInput, } from "@oj-module/runtime/notify";
 export { ErrorBoundary } from "react-error-boundary";

package/dist/layout/layout-menu/types.d.ts

@@ -23,4 +23,18 @@ export interface MenuItemType {
      * @default false
      */
     disabled?: boolean;
+    /**
+     * 所属模块名（0.2.16 R1，module-loader 注入）；归组据此甄别方案路由。
+     * 框架/后端路由无此字段。
+     */
+    module?: string;
+    /**
+     * 方案路由分类（0.2.16 R2，作者声明于 handle）：main=常规组、admin=管理组、
+     * hidden=不进菜单。归组与隐藏判定读此字段。
+     */
+    category?: "main" | "admin" | "hidden";
+    /**
+     * 菜单排序（0.2.16 R2，作者声明于 handle）；归组内子项按此升序。
+     */
+    order?: number;
 }

package/dist/router/extra-info/route-path.d.ts

@@ -14,9 +14,11 @@ export declare const exceptionUnknownComponentPath = "/exception/not-found-compo
  * 判断 pathname 是否为登录页（basename 感知，P0）。
  *
  * 供 ky hooks 等 React 之外的场景使用：原始 `location.pathname` 含 BASE_URL，
- * 子路径部署（/app/）下直接与 loginPath 比较恒为 false，401 时会重复 goLogin。
+ * 子路径部署（/oj/wiki/...）下直接与 loginPath 比较恒为 false，401 时会重复 goLogin。
  * React 组件内请用 `useLocation()`（react-router 已剥离 basename），无需本函数。
  *
- * @param base 部署 basename，Vite 保证以 `/` 结尾
+ * @param base 部署 base，恒以 `/` 结尾；缺省取 `resolveSiteBase()`（部署期注入优先，
+ * 见 utils/site-base.ts —— runtime 产物里的 `import.meta.env.BASE_URL` 是构建期
+ * 内联的 `/`，子路径部署下直接用它恒错）
  */
 export declare function isLoginPathname(pathname: string, base?: string): boolean;

package/dist/router/routes/index.d.ts

@@ -24,6 +24,7 @@ declare const baseRoutes: ({
         internal?: boolean;
         hideInMenu?: boolean;
         category?: "main" | "admin" | "hidden";
+        module?: string;
         iframeLink?: string;
         externalLink?: string;
         ignoreAccess?: boolean;
@@ -73,6 +74,7 @@ declare const baseRoutes: ({
         internal?: boolean;
         hideInMenu?: boolean;
         category?: "main" | "admin" | "hidden";
+        module?: string;
         iframeLink?: string;
         externalLink?: string;
         ignoreAccess?: boolean;

package/dist/router/types.d.ts

@@ -62,11 +62,16 @@ export interface RouteMeta {
      */
     hideInMenu?: boolean;
     /**
-     * 方案路由分类（P1-14/R21 三值归并，源自 sys_solution_route.category，经
-     * mergeSolutionCategories 注写）：main=常规组、admin=管理组、hidden=不进菜单。
-     * 框架/后端路由未归并时缺省。
+     * 方案路由分类（P1-14/R21 三值归并）：main=常规组、admin=管理组、hidden=不进菜单。
+     * 作者显式声明在 entry.ts handle（运行时单一真源）；框架/后端路由缺省。
      */
     category?: "main" | "admin" | "hidden";
+    /**
+     * 所属模块名（module-loader 在 `getRoutes()` 注册时按 `definition.name` 注入，
+     * 非作者手写）。归组逻辑据此甄别方案路由、生成 `solgroup:<category>:<module>` 父键，
+     * 不再依赖宿主 DB 行（0.2.16 起；此前由 sys_solution_route.module 提供）。
+     */
+    module?: string;
     /**
      * iframe链接，如果路由需要在iframe中加载外部页面时使用
      */

package/dist/router/utils/ascending.d.ts

@@ -21,6 +21,7 @@ export declare function ascending(arr: AppRouteRecordRaw[]): ({
         internal?: boolean;
         hideInMenu?: boolean;
         category?: "main" | "admin" | "hidden";
+        module?: string;
         iframeLink?: string;
         externalLink?: string;
         ignoreAccess?: boolean;
@@ -70,6 +71,7 @@ export declare function ascending(arr: AppRouteRecordRaw[]): ({
         internal?: boolean;
         hideInMenu?: boolean;
         category?: "main" | "admin" | "hidden";
+        module?: string;
         iframeLink?: string;
         externalLink?: string;
         ignoreAccess?: boolean;

package/dist/router/utils/group-solution-menus.d.ts

@@ -1,14 +1,20 @@
 import type { SolutionRouteRow } from "../../api/rbac/types";
 import type { MenuItemType } from "../../layout/layout-menu/types";
 /**
- * 方案路由注册菜单归组（2026-10-21，docs/plans/2026-10-21-1028-solution-menu-grouping.md）。
+ * 方案路由注册菜单归组（2026-10-21 设计；0.2.17 起）：
  *
- * 纯函数、单一职责（SRP）：只把已生成的菜单做"视觉层归组"，不动路由树、不触碰
- * i18n/翻译（组标题存裸 i18n key，交由渲染层 translateMenus 翻译）。跨列表操作
- * （admin 项在 wholeMenus、`/system` 在 bottomMenus），故一次调用吃两段菜单。
+ * - flat main 归组已取消：category==="main" 不再按模块建父菜单，模块根路由本身即
+ *   第一级菜单（entry.ts 单根约定），其子项直出（visible 由 category/hideInMenu 决定）。
+ * - admin 真重写：路由 PATH 已由 rewriteAdminPaths（access.ts）在注入前改写为
+ *   /system/<模块 root path>/*，故此处收到的 admin 菜单项 key 已是 /system/...；
+ *   本函数只做"视觉层归组"——递归收集 category==="admin" 项，按 module 建子组，
+ *   挂入 /system children 末尾，组标题存裸 i18n key `<module>:menu.main`（渲染层翻译）。
  *
- * 依赖倒置（DIP）：告警通道 onWarn 由调用方注入，缺省为模块级 warnOnce，便于单测
- * 断言与生产环境接管。无副作用、不 mutate 入参（未变动项复用原引用，返回新数组）。
+ * 纯函数、单一职责（SRP）：只把已生成的菜单做"视觉层归组"，不动路由树、不触碰翻译。
+ * 跨列表操作（admin 项可能在 wholeMenus、`/system` 在 bottomMenus），故一次调用吃两段菜单。
+ *
+ * 依赖倒置（DIP）：告警通道 onWarn 由调用方注入，缺省为模块级 warnOnce，便于单测断言。
+ * 无副作用、不 mutate 入参（未变动项复用原引用，返回新数组）。
  */
 export interface GroupSolutionMenusOptions {
     /** 宿主系统设置菜单 key，默认 "/system" */
@@ -19,10 +25,13 @@ export interface GroupSolutionMenusOptions {
 /**
  * 归组入口。
  *
- * - 空表（未安装/端点失败）或无命中行 → 返回新数组（内容相等），开发形态不变；
- * - 不 mutate 入参对象，未变动项复用原 menuItem 引用（仅重组数组与合成父项）。
+ * @param top 主区菜单项（order >= 0）
+ * @param bottom 底部固定区菜单项（order < 0，含 /system）
+ * @param rows 宿主方案路由行（可选）：缺省或空时归组完全依赖 handle 元数据（dev 形态）；
+ *   提供时仅作 category 的向后兼容回退（0.2.15 已装站点），不参与新 bundle 的归组真源。
+ * @param opts 选项（systemKey / onWarn）
  */
-export declare function groupSolutionMenus(top: MenuItemType[], bottom: MenuItemType[], rows: SolutionRouteRow[], opts?: GroupSolutionMenusOptions): {
+export declare function groupSolutionMenus(top: MenuItemType[], bottom: MenuItemType[], rows?: SolutionRouteRow[], opts?: GroupSolutionMenusOptions): {
     top: MenuItemType[];
     bottom: MenuItemType[];
 };

package/dist/router/utils/merge-solution-categories.d.ts

@@ -6,18 +6,15 @@ import type { AppRouteRecordRaw } from "../types";
  */
 export type AnnotatedRoute = AppRouteRecordRaw;
 /**
- * 方案路由归并（纯函数，R21）：按 path 把 sys_solution_route 行注记到已注册路由上。
+ * 方案路由归并（纯函数，R21 / 0.2.16 收窄）：DB 行仅作为「管理覆写层」。
  *
- * - 三值 category 原样落 handle.category（main=常规组、admin=管理组、hidden=不进菜单）；
- * - hidden 与 enabled=0（禁用）复用既有 hideInMenu 通路——只过滤菜单层，路由仍可达
- *   （禁用的路由摘除归装载层三处同写，D12）；
- * - order 覆写为声明序（2026-10-20 双段序轴）：框架常规项 ≥0 升序、管理面负数入
- *   底部固定区（pin 侧边栏底部，ascending 双段排序）、方案项从 200 起编，共用一条序轴；
- *   同 order 按根 path 字母序；
- * - 未匹配路由（框架/后端）原样保留（同一对象引用），入参不突变；
- * - solRoutes 为空（端点失败/未登录降级空表）时原样返回——降级不阻断，路由照常。
+ * 0.2.16 起 `category`/`order`/`module` 已是路由 handle 真源（作者声明 + module-loader 注入，
+ * 见 R1/R2），不再由本函数从行注写。本函数只保留一项管理语义：
  *
- * title 不在此覆写：entry.ts 是模块元数据唯一来源（module-loader 既有惯例），
- * title_key 随行下发仅供深检对比。
+ * - **禁用覆写**：行 `enabled === false`（或 deprecated）时追加 `hideInMenu: true`，
+ *   使该菜单项不可见（路由仍可达，D12 口径——禁用在装载层三处同写）；
+ * - 其余字段（category/order/module/title）一律不覆写，保持 handle 原值；
+ * - 入参不突变（未命中行或无需覆写时返回同一对象引用）；
+ * - solRoutes 为空（端点失败/未登录/dev 零行降级）时原样返回——降级不阻断，路由照常。
  */
 export declare function mergeSolutionCategories(routes: AppRouteRecordRaw[], solRoutes: SolutionRouteRow[]): AnnotatedRoute[];

package/dist/router/utils/rewrite-admin-paths.d.ts

@@ -0,0 +1,2 @@
+import type { AppRouteRecordRaw } from "../types";
+export declare function rewriteAdminPaths(routes: AppRouteRecordRaw[], systemKey?: string): AppRouteRecordRaw[];

package/dist/runtime.js

@@ -152,21 +152,68 @@ var notify = {
 	}
 };
 //#endregion
+//#region src/utils/site-base.ts
+/**
+* 归一化为「以 `/` 开头且以 `/` 结尾」的形式。
+*
+* 接受 `oj` / `/oj` / `/oj/` / `oj/` 四种写法（配置手写极易带或不带斜杠），
+* 空值与 `"/"` 一律归为根路径。
+*/
+function normalizeSiteBase(raw) {
+	if (!raw) return ROOT_BASE;
+	const trimmed = raw.trim();
+	if (!trimmed || trimmed === ROOT_BASE) return ROOT_BASE;
+	const withLeading = trimmed.startsWith(ROOT_BASE) ? trimmed : `${ROOT_BASE}${trimmed}`;
+	return withLeading.endsWith(ROOT_BASE) ? withLeading : `${withLeading}${ROOT_BASE}`;
+}
+/**
+* 当前站点的部署 base（恒以 `/` 结尾）。
+*
+* 优先级：`window.__OJ_BASE__`（部署期注入）> `import.meta.env.BASE_URL`（构建期值）。
+*
+* 每次调用都重新读取——不做模块级缓存。原因：测试需要在不重启模块的情况下模拟
+* 不同部署前缀（`vi.stubGlobal`），而字符串归一化的成本可忽略。
+*/
+function resolveSiteBase() {
+	const injected = globalThis.__OJ_BASE__;
+	if (typeof injected === "string") return normalizeSiteBase(injected);
+	return normalizeSiteBase("/");
+}
+/**
+* 把站内绝对路径（`/assets/x.js`）拼到站点 base 上（`/oj/assets/x.js`）。
+*
+* 已带 base 的路径幂等；`http(s)://`、`//cdn`、`data:` 等一切非站内绝对路径原样返回
+* （模块 entry 允许是 CDN 绝对域，见 `web.config.ts` 的 `baseUrl`）。
+*/
+function withSiteBase(url, base = resolveSiteBase()) {
+	if (!url.startsWith(ROOT_BASE) || url.startsWith("//")) return url;
+	const normalized = normalizeSiteBase(base);
+	if (normalized === ROOT_BASE || url.startsWith(normalized)) return url;
+	return `${normalized.slice(0, -1)}${url}`;
+}
+var ROOT_BASE;
+var init_site_base = __esmMin((() => {
+	ROOT_BASE = "/";
+}));
+//#endregion
 //#region src/router/extra-info/route-path.ts
 /**
 * 判断 pathname 是否为登录页（basename 感知，P0）。
 *
 * 供 ky hooks 等 React 之外的场景使用：原始 `location.pathname` 含 BASE_URL，
-* 子路径部署（/app/）下直接与 loginPath 比较恒为 false，401 时会重复 goLogin。
+* 子路径部署（/oj/wiki/...）下直接与 loginPath 比较恒为 false，401 时会重复 goLogin。
 * React 组件内请用 `useLocation()`（react-router 已剥离 basename），无需本函数。
 *
-* @param base 部署 basename，Vite 保证以 `/` 结尾
+* @param base 部署 base，恒以 `/` 结尾；缺省取 `resolveSiteBase()`（部署期注入优先，
+* 见 utils/site-base.ts —— runtime 产物里的 `import.meta.env.BASE_URL` 是构建期
+* 内联的 `/`，子路径部署下直接用它恒错）
 */
-function isLoginPathname(pathname, base = "/") {
+function isLoginPathname(pathname, base = resolveSiteBase()) {
 	return pathname === `${base}${loginPath.slice(1)}`;
 }
 var loginPath, exceptionPath, exception403Path, exception404Path, exception500Path;
 var init_route_path = __esmMin((() => {
+	init_site_base();
 	loginPath = "/login";
 	exceptionPath = "/exception";
 	exception403Path = `${exceptionPath}/403`;
@@ -256,10 +303,10 @@ function getAppInfo() {
 	return {
 		"pkg": {
 			"name": "@oj-module/runtime",
-			"version": "0.2.15",
+			"version": "0.2.17",
 			"license": "MIT"
 		},
-		"lastBuildTime": "2026-10-21 12:22:16"
+		"lastBuildTime": "2026-10-21 21:54:09"
 	};
 }
 var init_get_app_info = __esmMin((() => {}));
@@ -3300,7 +3347,7 @@ function openMustChangeModal() {
 		maskClosable: false,
 		cancelButtonProps: { style: { display: "none" } },
 		onOk: () => {
-			window.location.href = `/change-password`;
+			window.location.href = `${resolveSiteBase()}change-password`;
 		},
 		afterClose: () => {
 			mustChangeModalOpen = false;
@@ -3310,6 +3357,7 @@ function openMustChangeModal() {
 var mustChangeModalOpen;
 var init_must_change = __esmMin((() => {
 	init_is();
+	init_site_base();
 	init_static_antd();
 	mustChangeModalOpen = false;
 }));
@@ -7478,6 +7526,24 @@ function getModules() {
 function getModule(name) {
 	return modules.get(name);
 }
+/**
+* 给模块路由打 module 标（R1，0.2.16）：递归 children，非突变返回新对象。
+* module 来自 `definition.name`，作者无需手写——归组据此甄别方案路由、
+* 生成 `solgroup:<category>:<module>` 父键，不再依赖宿主 DB 行。
+*/
+function tagModuleRoutes(routes, name) {
+	return routes.map((route) => {
+		const tagged = {
+			...route,
+			handle: {
+				...route.handle,
+				module: name
+			}
+		};
+		if (Array.isArray(route.children) && route.children.length > 0) tagged.children = tagModuleRoutes(route.children, name);
+		return tagged;
+	});
+}
 function getRoutes() {
 	const { roles, permissions = [] } = useUserStore.getState();
 	const routes = [];
@@ -7487,7 +7553,7 @@ function getRoutes() {
 		if (requiredRoles?.length && !requiredRoles.some((role) => roles.includes(role))) continue;
 		const requiredPermissions = instance.definition.config?.requiredPermissions;
 		if (requiredPermissions?.length && !requiredPermissions.every((perm) => permissions.includes(perm))) continue;
-		if (instance.definition.routes.length > 0) routes.push(...resolveRouteLayouts(instance.definition.routes));
+		if (instance.definition.routes.length > 0) routes.push(...resolveRouteLayouts(tagModuleRoutes(instance.definition.routes, instance.definition.name)));
 	}
 	return addRouteIdByPath(routes);
 }
@@ -8294,13 +8360,23 @@ var init_constants = __esmMin((() => {
 //#endregion
 //#region src/router/index.ts
 function createRouter() {
-	return createBrowserRouter(rootRoute, { basename: "/" });
+	return createBrowserRouter(rootRoute, { 
+	/**
+	* @zh 子路径部署（oj `mounts: [{ prefix: /oj }]`）下 basename 必须是部署前缀，
+	* 否则 react-router 不剥前缀，深链 `/oj/wiki/...` 匹配不到任何路由（落到 404 兜底）。
+	* 取值走 `resolveSiteBase()`：优先宿主注入的 `window.__OJ_BASE__`，回退构建期
+	* `import.meta.env.BASE_URL`——后者在预构建产物里被内联成 `/`，单独用不可靠。
+	* @en Under sub-path deployment the basename must be the deploy prefix; read it
+	* through `resolveSiteBase()` instead of the build-time `import.meta.env.BASE_URL`.
+	*/
+basename: resolveSiteBase() });
 }
 var loadedPaths, rootRoute, router;
 var init_router = __esmMin((() => {
 	init_layout_root();
 	init_preferences$3();
 	init_progress();
+	init_site_base();
 	init_constants();
 	init_routes();
 	loadedPaths = /* @__PURE__ */ new Set();
@@ -8361,9 +8437,10 @@ function resolveMenuKey(path, parentPath) {
 */
 function generateMenuItemsFromRoutes(routeList, parentPath = "/") {
 	return routeList.reduce((acc, item) => {
-		const label = item.handle?.title;
-		const externalLink = item?.handle?.externalLink;
-		const icon = item?.handle?.icon;
+		const handle = item.handle;
+		const label = handle?.title;
+		const externalLink = handle?.externalLink;
+		const icon = handle?.icon;
 		const absolutePath = resolveMenuKey(item.path, parentPath);
 		const menuItem = {
 			key: absolutePath,
@@ -8377,11 +8454,14 @@ function generateMenuItemsFromRoutes(routeList, parentPath = "/") {
 			}, label) : label
 		};
 		if (icon) menuItem.icon = icon;
+		if (handle?.module) menuItem.module = handle.module;
+		if (handle?.category) menuItem.category = handle.category;
+		if (handle?.order !== void 0) menuItem.order = handle.order;
 		if (Array.isArray(item.children) && item.children.length > 0) {
-			const noIndexRoute = item.children.filter((route) => !route.index && !route?.handle?.hideInMenu);
+			const noIndexRoute = item.children.filter((route) => !route.index && !route?.handle?.hideInMenu && route?.handle?.category !== "hidden");
 			if (noIndexRoute.length > 0) menuItem.children = generateMenuItemsFromRoutes(noIndexRoute, absolutePath);
 		}
-		if (item?.handle?.hideInMenu) return acc;
+		if (handle?.hideInMenu || handle?.category === "hidden") return acc;
 		return [...acc, menuItem];
 	}, []);
 }
@@ -8393,158 +8473,132 @@ function defaultWarn(msg) {
 	warnedOnce.add(msg);
 	console.warn(msg);
 }
+/** 取某 item 的有效归组元数据（handle 优先，行回退） */
+function effective(item, row) {
+	return {
+		module: item.module ?? row?.module,
+		category: item.category ?? row?.category
+	};
+}
 /**
-* 处理单段菜单（顶层扫描，不递归 children）：
-* - main 路由：模块可见项 ≥2 则延迟建组（组插到该模块首个被摘项原序位）；否则原样直出；
-* - admin 路由：可挂载 `/system` 时摘除（交由调用方挂入 bottom 的 /system children），
-*   否则原样直出（回落顶层平铺，保持原序）；
-* - 无对应行项：原样直出。
+* 递归摘除 category==="admin" 的菜单项（handle 优先、行回退兜底），按 module 分桶收集；
+* 收集时压平 admin 项自身的层级——直接取 admin 项的 children，使"管理"中间级消失、
+* 子项直挂 `<module>:menu.main` 子组下，无 children 时退回 admin 项本身。
+* 其余项原样保留（children 递归同样处理），非突变；无变动的子树复用原引用。
+*
+* 返回新数组（有项被摘除/被重写父级时）或原数组引用（整段无 admin 时），便于调用方
+* 判断是否需重建 /system children（避免无 admin 项时给 /system 强加空 children）。
 */
-function processList(list, byPath, groupedModules, mountPossible) {
+function stripAdmin(list, byPath, buckets) {
+	let changed = false;
 	const out = [];
-	const groupsByModule = /* @__PURE__ */ new Map();
-	const adminItems = [];
-	list.forEach((it, idx) => {
-		const row = byPath.get(it.key);
-		if (!row) {
-			out.push(it);
-			return;
-		}
-		if (row.category === "admin") {
-			adminItems.push({
-				item: it,
-				row
-			});
-			if (mountPossible) return;
-			out.push(it);
-			return;
-		}
-		if (groupedModules.has(row.module)) {
-			let g = groupsByModule.get(row.module);
-			if (!g) {
-				g = {
-					items: [],
-					rows: [],
-					firstIdx: idx
-				};
-				groupsByModule.set(row.module, g);
-			}
-			g.items.push(it);
-			g.rows.push(row);
-			return;
+	for (const it of list) {
+		const { module, category } = effective(it, byPath.get(it.key));
+		if (category === "admin" && module) {
+			const subItems = it.children && it.children.length > 0 ? it.children : [it];
+			const bucket = buckets.get(module) ?? {
+				items: [],
+				module,
+				minOrder: Infinity
+			};
+			for (const s of subItems) bucket.items.push(s);
+			bucket.minOrder = Math.min(bucket.minOrder, it.order ?? 0);
+			buckets.set(module, bucket);
+			changed = true;
+			continue;
 		}
-		out.push(it);
-	});
-	const inserts = [...groupsByModule.values()].map((g) => ({
-		index: g.firstIdx,
-		group: makeGroup(MAIN_PREFIX, g.rows[0].module, g.items, g.rows)
-	})).sort((a, b) => b.index - a.index);
-	for (const ins of inserts) out.splice(ins.index, 0, ins.group);
-	return {
-		out,
-		adminItems
-	};
+		if (it.children && it.children.length > 0) {
+			const newChildren = stripAdmin(it.children, byPath, buckets);
+			if (newChildren !== it.children) {
+				changed = true;
+				out.push({
+					...it,
+					children: newChildren
+				});
+			} else out.push(it);
+		} else out.push(it);
+	}
+	return changed ? out : list;
 }
-function makeGroup(prefix, module, items, rows) {
-	const paired = items.map((item, i) => ({
+function makeAdminGroup(module, items) {
+	const paired = items.map((item) => ({
 		item,
-		order: rows[i].order
+		order: item.order ?? 0
 	})).sort((a, b) => a.order - b.order);
 	return {
-		key: `${prefix}${module}`,
-		label: `${module}:menu.group`,
+		key: `${ADMIN_PREFIX}${module}`,
+		label: `${module}:menu.main`,
 		children: paired.map((p) => p.item)
 	};
 }
 /**
 * 归组入口。
 *
-* - 空表（未安装/端点失败）或无命中行 → 返回新数组（内容相等），开发形态不变；
-* - 不 mutate 入参对象，未变动项复用原 menuItem 引用（仅重组数组与合成父项）。
+* @param top 主区菜单项（order >= 0）
+* @param bottom 底部固定区菜单项（order < 0，含 /system）
+* @param rows 宿主方案路由行（可选）：缺省或空时归组完全依赖 handle 元数据（dev 形态）；
+*   提供时仅作 category 的向后兼容回退（0.2.15 已装站点），不参与新 bundle 的归组真源。
+* @param opts 选项（systemKey / onWarn）
 */
 function groupSolutionMenus(top, bottom, rows, opts = {}) {
 	const systemKey = opts.systemKey ?? "/system";
 	const onWarn = opts.onWarn ?? defaultWarn;
-	if (rows.length === 0) return {
-		top: [...top],
-		bottom: [...bottom]
-	};
 	const byPath = /* @__PURE__ */ new Map();
-	for (const r of rows) if ((r.category === "main" || r.category === "admin") && r.enabled !== false) byPath.set(r.path, r);
-	if (byPath.size === 0) return {
-		top: [...top],
-		bottom: [...bottom]
-	};
-	const mainCount = /* @__PURE__ */ new Map();
-	for (const list of [top, bottom]) for (const it of list) {
-		const row = byPath.get(it.key);
-		if (row?.category === "main") mainCount.set(row.module, (mainCount.get(row.module) ?? 0) + 1);
-	}
-	const groupedModules = new Set([...mainCount].filter(([, n]) => n >= 2).map(([module]) => module));
-	const mountPossible = bottom.some((it) => it.key === systemKey);
-	const topRes = processList(top, byPath, groupedModules, mountPossible);
-	const bottomRes = processList(bottom, byPath, groupedModules, mountPossible);
-	const adminGroupsMap = /* @__PURE__ */ new Map();
-	for (const a of [...topRes.adminItems, ...bottomRes.adminItems]) {
-		const arr = adminGroupsMap.get(a.row.module) ?? [];
-		arr.push(a);
-		adminGroupsMap.set(a.row.module, arr);
-	}
-	const adminGroups = [...adminGroupsMap.entries()].map(([module, items]) => ({
-		minOrder: Math.min(...items.map((i) => i.row.order)),
-		group: makeGroup(ADMIN_PREFIX, module, items.map((i) => i.item), items.map((i) => i.row))
+	for (const r of rows ?? []) if (r.category === "admin" && r.enabled !== false) byPath.set(r.path, r);
+	const buckets = /* @__PURE__ */ new Map();
+	const newTop = stripAdmin(top, byPath, buckets);
+	const newBottom = stripAdmin(bottom, byPath, buckets);
+	const adminGroups = [...buckets.entries()].map(([module, b]) => ({
+		minOrder: b.minOrder,
+		group: makeAdminGroup(module, b.items)
 	})).sort((a, b) => a.minOrder - b.minOrder);
-	let newBottom = bottomRes.out;
+	let resultBottom = newBottom;
 	const sysIdx = newBottom.findIndex((it) => it.key === systemKey);
-	if (mountPossible && sysIdx !== -1) {
-		const system = newBottom[sysIdx];
-		newBottom = newBottom.slice();
-		newBottom[sysIdx] = {
-			...system,
-			children: [...system.children ?? [], ...adminGroups.map((g) => g.group)]
-		};
-	} else if (adminGroups.length > 0) onWarn(`[solution-menu-grouping] system menu "${systemKey}" not found; admin items keep top-level (grouping degraded).`);
+	if (adminGroups.length > 0) {
+		if (sysIdx !== -1) {
+			const system = newBottom[sysIdx];
+			resultBottom = newBottom.slice();
+			resultBottom[sysIdx] = {
+				...system,
+				children: [...system.children ?? [], ...adminGroups.map((g) => g.group)]
+			};
+		} else onWarn(`[solution-menu-grouping] system menu "${systemKey}" not found; admin items dropped from menu.`);
+	}
 	return {
-		top: topRes.out,
-		bottom: newBottom
+		top: newTop,
+		bottom: resultBottom
 	};
 }
-var MAIN_PREFIX, ADMIN_PREFIX, warnedOnce;
+var ADMIN_PREFIX, warnedOnce;
 var init_group_solution_menus = __esmMin((() => {
-	MAIN_PREFIX = "solgroup:main:";
 	ADMIN_PREFIX = "solgroup:admin:";
 	warnedOnce = /* @__PURE__ */ new Set();
 }));
 //#endregion
 //#region src/router/utils/merge-solution-categories.ts
 /**
-* 方案路由归并（纯函数，R21）：按 path 把 sys_solution_route 行注记到已注册路由上。
+* 方案路由归并（纯函数，R21 / 0.2.16 收窄）：DB 行仅作为「管理覆写层」。
 *
-* - 三值 category 原样落 handle.category（main=常规组、admin=管理组、hidden=不进菜单）；
-* - hidden 与 enabled=0（禁用）复用既有 hideInMenu 通路——只过滤菜单层，路由仍可达
-*   （禁用的路由摘除归装载层三处同写，D12）；
-* - order 覆写为声明序（2026-10-20 双段序轴）：框架常规项 ≥0 升序、管理面负数入
-*   底部固定区（pin 侧边栏底部，ascending 双段排序）、方案项从 200 起编，共用一条序轴；
-*   同 order 按根 path 字母序；
-* - 未匹配路由（框架/后端）原样保留（同一对象引用），入参不突变；
-* - solRoutes 为空（端点失败/未登录降级空表）时原样返回——降级不阻断，路由照常。
+* 0.2.16 起 `category`/`order`/`module` 已是路由 handle 真源（作者声明 + module-loader 注入，
+* 见 R1/R2），不再由本函数从行注写。本函数只保留一项管理语义：
 *
-* title 不在此覆写：entry.ts 是模块元数据唯一来源（module-loader 既有惯例），
-* title_key 随行下发仅供深检对比。
+* - **禁用覆写**：行 `enabled === false`（或 deprecated）时追加 `hideInMenu: true`，
+*   使该菜单项不可见（路由仍可达，D12 口径——禁用在装载层三处同写）；
+* - 其余字段（category/order/module/title）一律不覆写，保持 handle 原值；
+* - 入参不突变（未命中行或无需覆写时返回同一对象引用）；
+* - solRoutes 为空（端点失败/未登录/dev 零行降级）时原样返回——降级不阻断，路由照常。
 */
 function mergeSolutionCategories(routes, solRoutes) {
 	if (solRoutes.length === 0) return routes;
 	const byPath = new Map(solRoutes.map((r) => [r.path, r]));
 	return routes.map((route) => {
 		const row = route.path ? byPath.get(route.path) : void 0;
-		if (!row) return route;
+		if (!row || row.enabled !== false) return route;
 		return {
 			...route,
 			handle: {
 				...route.handle,
-				category: row.category,
-				order: row.order,
-				hideInMenu: row.category === "hidden" || !row.enabled || (route.handle.hideInMenu ?? false)
+				hideInMenu: true
 			}
 		};
 	});
@@ -8601,6 +8655,42 @@ var init_resolve_login_route = __esmMin((() => {
 	isInternalLoginRoute = (r) => r?.handle?.login === true && r?.handle?.internal === true;
 }));
 //#endregion
+//#region src/router/utils/rewrite-admin-paths.ts
+/** 解析路由绝对路径（与 generate-menu-items-from-routes 同语义） */
+function resolveAbs(path, parentAbs) {
+	if (!path) return parentAbs;
+	return path.startsWith("/") ? path : `${parentAbs.replace(/\/+$/, "")}/${path}`;
+}
+function rewriteAdminPaths(routes, systemKey = SYSTEM_KEY) {
+	const hoisted = [];
+	return [...routes.map((r) => processRoute(r, "/", systemKey, hoisted, void 0)).filter((r) => r !== null), ...hoisted];
+}
+function processRoute(route, parentAbs, systemKey, hoisted, moduleRootAbs) {
+	const abs = resolveAbs(route.path, parentAbs);
+	const rootAbs = moduleRootAbs ?? abs;
+	if (route.handle?.category === "admin") {
+		const newAbs = `${systemKey}${rootAbs}${abs.slice(rootAbs.length) || ""}`;
+		hoisted.push({
+			...route,
+			path: newAbs
+		});
+		return null;
+	}
+	if (!route.children || route.children.length === 0) return { ...route };
+	const newChildren = [];
+	for (const c of route.children) {
+		const processed = processRoute(c, abs, systemKey, hoisted, rootAbs);
+		if (processed !== null) newChildren.push(processed);
+	}
+	const result = { ...route };
+	result.children = newChildren;
+	return result;
+}
+var SYSTEM_KEY;
+var init_rewrite_admin_paths = __esmMin((() => {
+	SYSTEM_KEY = "/system";
+}));
+//#endregion
 //#region src/store/access.ts
 /**
 * 切分主区/底部固定区路由（ascending 已双段排序：负 order 段整体在后）。
@@ -8628,6 +8718,7 @@ var init_access = __esmMin((() => {
 	init_group_solution_menus();
 	init_merge_solution_categories();
 	init_resolve_login_route();
+	init_rewrite_admin_paths();
 	baseMenuRoutes = splitMenuRoutes(baseRoutes);
 	initialState$1 = {
 		wholeMenus: generateMenuItemsFromRoutes(baseMenuRoutes.top),
@@ -8641,8 +8732,9 @@ var init_access = __esmMin((() => {
 	useAccessStore = create((set, get) => ({
 		...initialState$1,
 		setAccessStore: (routes) => {
-			const newRoutes = ascending([...resolveLoginRoute(baseRoutes, routes, router, rootRoute), ...mergeSolutionCategories(routes, get().solutionRoutes)]);
-			router.patchRoutes(ROOT_ROUTE_ID, routes);
+			const rewrittenRoutes = rewriteAdminPaths(routes);
+			const newRoutes = ascending([...resolveLoginRoute(baseRoutes, rewrittenRoutes, router, rootRoute), ...mergeSolutionCategories(rewrittenRoutes, get().solutionRoutes)]);
+			router.patchRoutes(ROOT_ROUTE_ID, rewrittenRoutes);
 			const flatRouteList = flattenRoutes(newRoutes);
 			const { top, bottom } = splitMenuRoutes(newRoutes);
 			const grouped = groupSolutionMenus(generateMenuItemsFromRoutes(top), generateMenuItemsFromRoutes(bottom), get().solutionRoutes);
@@ -8823,15 +8915,20 @@ var init_remember_route = __esmMin((() => {
 /**
 * 跳转到登录页面
 *
+* 必须带上部署 base（`resolveSiteBase()`）：子路径部署下 `location.href = "/login"`
+* 会跳到宿主机根，而不是 `/oj/login`。不能用 `import.meta.env.BASE_URL`——预构建
+* 产物里它是构建期内联的 `/`。
+*
 * @returns 无返回值
 */
 function goLogin() {
 	useAuthStore.getState().reset();
-	window.location.href = `/login${rememberRoute()}`;
+	window.location.href = `${resolveSiteBase()}login${rememberRoute()}`;
 }
 var init_go_login = __esmMin((() => {
 	init_auth();
 	init_remember_route();
+	init_site_base();
 }));
 //#endregion
 //#region src/utils/request/header-safe.ts
@@ -27946,10 +28043,11 @@ init_user();
 init_get_app_info();
 init_get_redirect_path();
 init_request();
+init_site_base();
 init_user$1();
 init_local_icons();
 init_ri();
 init_menu_icons();
 init_tree();
 //#endregion
-export { AccessControl, AccessControlRoles, AntdApp, BasicButton, BasicContent, BasicTable, EmbeddedIcon, ErrorBoundary, ExternalIcon, FormAvatarItem, FormTreeItem, Iframe, LayoutCenterIcon, LayoutEffects, LayoutLeftIcon, LayoutRightIcon, MixedNavigationIcon, OutsidePageIcon, PageError, ProfileCardIcon, RiAccountCircleLine, RiContrastFill, RiFullscreenExitLine, RiFullscreenLine, RiMailCheckLine, RiMoonIcon, RiReactjsLine, RiSunIcon, RiUserSettingsLine, ServerErrorIcon, SideNavigationIcon, TopNavigationIcon, TwoColumnNavigationIcon, accessControlCodes, bindingDiff, canAssignRole, canDeleteRole, canEditRoleBindings, defineModule, fetchAddMenuItem, fetchAddRoleItem, fetchAsyncRoutes, fetchChangePassword, fetchDeleteMenuItem, fetchDeleteRoleItem, fetchLdapLogin, fetchLogin, fetchLoginMethods, fetchLogout, fetchMenuByRoleId, fetchMenuList, fetchRbacAdminResetPassword, fetchRbacContactDetail, fetchRbacContacts, fetchRbacCreateRole, fetchRbacCreateUser, fetchRbacDeleteRole, fetchRbacOplog, fetchRbacOplogPost, fetchRbacPermissionList, fetchRbacRoleList, fetchRbacSetForbidden, fetchRbacSettings, fetchRbacUpdateBindings, fetchRbacUpdateSetting, fetchRbacUpdateUserRoles, fetchRbacUserList, fetchRefreshToken, fetchRoleList, fetchRoleMenu, fetchSolutionRoutes, fetchUpdateMenuItem, fetchUpdateRoleItem, fetchUserInfo, filterTree, getAllExpandedKeys, getAppInfo, getBooleanOptions, getModule, getModules, getRedirectPath, getRegisteredApiPrefix, getRegisteredStore, getRoutes, getYesNoOptions, groupByModule, groupSettingsByModule, handleTree, loadAll, mapTree, menuIcons, notify, permissionPrefix, request, roleLabel, setupI18n, traverseTreeValues, unloadModule, useAccess, useAuthStore, usePreferences, useSlotNodes, useSolutionRoutes, useTabKey, useTabsStore, useUserStore, external_exports as z };
+export { AccessControl, AccessControlRoles, AntdApp, BasicButton, BasicContent, BasicTable, EmbeddedIcon, ErrorBoundary, ExternalIcon, FormAvatarItem, FormTreeItem, Iframe, LayoutCenterIcon, LayoutEffects, LayoutLeftIcon, LayoutRightIcon, MixedNavigationIcon, OutsidePageIcon, PageError, ProfileCardIcon, RiAccountCircleLine, RiContrastFill, RiFullscreenExitLine, RiFullscreenLine, RiMailCheckLine, RiMoonIcon, RiReactjsLine, RiSunIcon, RiUserSettingsLine, ServerErrorIcon, SideNavigationIcon, TopNavigationIcon, TwoColumnNavigationIcon, accessControlCodes, bindingDiff, canAssignRole, canDeleteRole, canEditRoleBindings, defineModule, fetchAddMenuItem, fetchAddRoleItem, fetchAsyncRoutes, fetchChangePassword, fetchDeleteMenuItem, fetchDeleteRoleItem, fetchLdapLogin, fetchLogin, fetchLoginMethods, fetchLogout, fetchMenuByRoleId, fetchMenuList, fetchRbacAdminResetPassword, fetchRbacContactDetail, fetchRbacContacts, fetchRbacCreateRole, fetchRbacCreateUser, fetchRbacDeleteRole, fetchRbacOplog, fetchRbacOplogPost, fetchRbacPermissionList, fetchRbacRoleList, fetchRbacSetForbidden, fetchRbacSettings, fetchRbacUpdateBindings, fetchRbacUpdateSetting, fetchRbacUpdateUserRoles, fetchRbacUserList, fetchRefreshToken, fetchRoleList, fetchRoleMenu, fetchSolutionRoutes, fetchUpdateMenuItem, fetchUpdateRoleItem, fetchUserInfo, filterTree, getAllExpandedKeys, getAppInfo, getBooleanOptions, getModule, getModules, getRedirectPath, getRegisteredApiPrefix, getRegisteredStore, getRoutes, getYesNoOptions, groupByModule, groupSettingsByModule, handleTree, loadAll, mapTree, menuIcons, notify, permissionPrefix, request, resolveSiteBase, roleLabel, setupI18n, traverseTreeValues, unloadModule, useAccess, useAuthStore, usePreferences, useSlotNodes, useSolutionRoutes, useTabKey, useTabsStore, useUserStore, withSiteBase, external_exports as z };

package/dist/utils/request/go-login.d.ts

@@ -1,6 +1,10 @@
 /**
  * 跳转到登录页面
  *
+ * 必须带上部署 base（`resolveSiteBase()`）：子路径部署下 `location.href = "/login"`
+ * 会跳到宿主机根，而不是 `/oj/login`。不能用 `import.meta.env.BASE_URL`——预构建
+ * 产物里它是构建期内联的 `/`。
+ *
  * @returns 无返回值
  */
 export declare function goLogin(): void;

package/dist/utils/site-base.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 站点部署 base 的唯一取值口（子路径部署支持，2026-10-21）。
+ *
+ * 背景：runtime 作为**预构建产物**分发（`dist/runtime.js`），`import.meta.env.BASE_URL`
+ * 在 `packages/runtime/vite.config.ts` 的构建期就被内联成 `"/"`。于是当站点被部署到
+ * 宿主机子路径（如 oj 的 `mounts: [{ prefix: /oj, web: dist, spa: true }]`）时：
+ *
+ * - `createBrowserRouter({ basename: "/" })` 剥不掉 `/oj`，深链刷新一律 404 兜底页；
+ * - `goLogin()` / `must-change` 拼出 `/login`，落在宿主机根而不是 `/oj/login`；
+ * - `isLoginPathname(location.pathname)` 恒为 false，401 会重复跳登录。
+ *
+ * 解法：真正的 base 只有**部署期**才知道（构建产物被挂到哪个前缀，由 oj 的 config
+ * 决定），所以由宿主在 index.html 里注入 `window.__OJ_BASE__`（`ojm build` 按
+ * `web.config.ts` 的 `siteBase` 写入），runtime 运行期优先读它，读不到再回退到
+ * 构建期值。这样：
+ *
+ * - 根路径部署（绝大多数工程，以及 `ojm dev` / `ojm preview` 默认）行为完全不变；
+ * - 子路径部署只需改一个配置项，无需重新构建 runtime。
+ *
+ * 契约：
+ * - 返回值**恒以 `/` 结尾**（`import.meta.env.BASE_URL` 的既有约定，`isLoginPathname`
+ *   的字符串拼接依赖它），根路径恒为 `"/"`；
+ * - 只处理「站点 base」，**不要**拿它拼 API 前缀——API 前缀是 `VITE_API_BASE_URL`
+ *   与模块 scoped request 的职责，两者互相独立；
+ * - React 组件内不要用它拼跳转，`navigate` / `<Link to>` 走的是**路由空间**
+ *   （basename 已被 react-router 剥离），拼上 base 反而会变成 `/oj/oj/wiki`。
+ */
+/**
+ * 归一化为「以 `/` 开头且以 `/` 结尾」的形式。
+ *
+ * 接受 `oj` / `/oj` / `/oj/` / `oj/` 四种写法（配置手写极易带或不带斜杠），
+ * 空值与 `"/"` 一律归为根路径。
+ */
+export declare function normalizeSiteBase(raw: string | null | undefined): string;
+/**
+ * 当前站点的部署 base（恒以 `/` 结尾）。
+ *
+ * 优先级：`window.__OJ_BASE__`（部署期注入）> `import.meta.env.BASE_URL`（构建期值）。
+ *
+ * 每次调用都重新读取——不做模块级缓存。原因：测试需要在不重启模块的情况下模拟
+ * 不同部署前缀（`vi.stubGlobal`），而字符串归一化的成本可忽略。
+ */
+export declare function resolveSiteBase(): string;
+/**
+ * 把站内绝对路径（`/assets/x.js`）拼到站点 base 上（`/oj/assets/x.js`）。
+ *
+ * 已带 base 的路径幂等；`http(s)://`、`//cdn`、`data:` 等一切非站内绝对路径原样返回
+ * （模块 entry 允许是 CDN 绝对域，见 `web.config.ts` 的 `baseUrl`）。
+ */
+export declare function withSiteBase(url: string, base?: string): string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@oj-module/runtime",
   "type": "module",
-  "version": "0.2.15",
+  "version": "0.2.17",
   "description": "React Antd Admin 框架运行时，供模块工程消费",
   "license": "MIT",
   "imports": {