@oj-module/runtime 0.1.17 → 0.1.21

package/dist/contract/index.d.ts

@@ -1,15 +1,15 @@
 /**
- * @oj-module/runtime/contract —— API 契约 DSL（AC-D11）。
+ * @oj-module/runtime/contract —— API 契约运行时。
  *
- * 零浏览器依赖（Node codegen 与浏览器运行时双安全）：
- * - defineApi：契约端点定义（含定义期校验）
- * - API_DEF：端点品牌标记（旧标记 `ram.api.def` 由 cli 侧自行识别，不在公共出口）
- * - z：zod re-export（契约 schema 书写；v4 钉版，pnpm catalog 单一来源）
- * - ContractApiError：契约制 client 统一错误类型
+ * 零浏览器依赖（Node codegen 与浏览器运行时双安全）。
+ *
+ * 历史：`defineApi` DSL 已在 oj v0.1.71 流水线中退役——单一事实源改为 oj
+ * `openapi.json`（`oj openapi` 产物）→ 前端 `ojm api` 生成 __client，不再消费
+ * 旧 `contract.ts`/`defineApi`。本子包现仅保留：
+ * - ContractApiError：契约制 client 统一错误类型（前端运行时用）
  * - ScopedRequestLike：生成 client 的 request 最小结构类型
+ * - z：zod re-export（契约 schema 书写；v4 钉版，pnpm catalog 单一来源）
  */
-export { API_DEF, defineApi } from "./define-api.ts";
-export type { ApiDefinitionInput, ApiFormFile, ApiFormInput, HttpMethod } from "./define-api.ts";
 export { ContractApiError } from "./errors.ts";
 export type { ScopedRequestLike } from "./scoped-request-like.ts";
 export { z } from "zod";

package/dist/contract/index.js

@@ -1,13 +1,14 @@
 /**
- * @oj-module/runtime/contract —— API 契约 DSL（AC-D11）。
+ * @oj-module/runtime/contract —— API 契约运行时。
  *
- * 零浏览器依赖（Node codegen 与浏览器运行时双安全）：
- * - defineApi：契约端点定义（含定义期校验）
- * - API_DEF：端点品牌标记（旧标记 `ram.api.def` 由 cli 侧自行识别，不在公共出口）
- * - z：zod re-export（契约 schema 书写；v4 钉版，pnpm catalog 单一来源）
- * - ContractApiError：契约制 client 统一错误类型
+ * 零浏览器依赖（Node codegen 与浏览器运行时双安全）。
+ *
+ * 历史：`defineApi` DSL 已在 oj v0.1.71 流水线中退役——单一事实源改为 oj
+ * `openapi.json`（`oj openapi` 产物）→ 前端 `ojm api` 生成 __client，不再消费
+ * 旧 `contract.ts`/`defineApi`。本子包现仅保留：
+ * - ContractApiError：契约制 client 统一错误类型（前端运行时用）
  * - ScopedRequestLike：生成 client 的 request 最小结构类型
+ * - z：zod re-export（契约 schema 书写；v4 钉版，pnpm catalog 单一来源）
  */
-export { API_DEF, defineApi } from "./define-api.js";
 export { ContractApiError } from "./errors.js";
 export { z } from "zod";

package/dist/hooks/use-tab-key/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 本页自己的页签 key（`removeTrailingSlash(pathname)`），供 `setTableTitle` /
+ * `resetTableTitle` / `addTab` 定位页签。
+ *
+ * keepAlive 陷阱：keepalive-for-react 把页面缓存在隐藏 portal 里，而 LocationContext
+ * 在 KeepAlive **之上**——切 tab 时缓存树随**激活页**位置重渲染，缓存页里的
+ * `useLocation()` 返回的是别家页签的路径。若拿它当页签 key，`setTableTitle` 会把
+ * 本页标题写到当前激活页签上（最后打开的文档页把之后切换到的每个页签都改成自己的标题）。
+ *
+ * 页签存活期内 key 不变（宿主 cacheKey = pathname+search，一页一路径），故首渲染
+ * （此时本页必是激活页）捕获一次即可；缓存树后续多少次重渲染都不会漂移。
+ * 需要跟随导航的位置信息请直接用 `useLocation`，不要用本 hook。
+ */
+export declare function useTabKey(): string;

package/dist/index.d.ts

@@ -26,6 +26,7 @@ export { PageError } from "./components/page-error";
 export * from "./constants/options";
 export * from "./hooks/use-access";
 export { usePreferences } from "./hooks/use-preferences";
+export { useTabKey } from "./hooks/use-tab-key";
 export * from "./icons";
 export { LayoutEffects } from "./layout/layout-effects";
 export { setupI18n } from "./locales";

package/dist/layout/widgets/notification/types.d.ts

@@ -13,8 +13,8 @@ export interface NotificationItem {
     isRead?: boolean;
     message: string;
     title: string;
-    /** 深链：前端点击跳转 */
-    link?: string;
+    /** 深链：前端点击跳转（无深链的通知为 null） */
+    link?: string | null;
     /** 消息类别：notice=通知/广播，pm=私信，mention=@我（占位） */
     category?: NoticeCategory;
 }

package/dist/runtime.js

@@ -255,10 +255,10 @@ function getAppInfo() {
 	return {
 		"pkg": {
 			"name": "@oj-module/runtime",
-			"version": "0.1.17",
+			"version": "0.1.21",
 			"license": "MIT"
 		},
-		"lastBuildTime": "2026-10-13 22:01:51"
+		"lastBuildTime": "2026-10-15 18:45:29"
 	};
 }
 var init_get_app_info = __esmMin((() => {}));
@@ -3580,7 +3580,7 @@ var init_use_layout_style = __esmMin((() => {
 }));
 //#endregion
 //#region src/store/tabs.ts
-var initialState$3, useTabsStore;
+var initialState$3, closingKeys, useTabsStore;
 var init_tabs = __esmMin((() => {
 	init_preferences$3();
 	init_get_app_namespace();
@@ -3606,224 +3606,218 @@ var init_tabs = __esmMin((() => {
 		*/
 		isMaximize: false
 	};
-	useTabsStore = create()(persist((set) => ({
-		...initialState$3,
+	closingKeys = /* @__PURE__ */ new Set();
+	useTabsStore = create()(persist((set, get) => {
 		/**
-		* @zh 设置标签页是否处于刷新状态
-		* @en Set whether the tab is in a refresh state.
+		* 关闭前守卫：待关闭集合里任一标签页声明了 beforeClose 且返回 false / 抛错时，整体中止。
+		* fail-safe：守卫抛错按中止处理，防误关丢内容；console.error 留排查线索。
 		*/
-		setIsRefresh: (state) => {
-			set({ isRefresh: state });
-		},
-		/**
-		* @zh 设置标签页
-		* @en Set the tab.
-		*/
-		setActiveKey: (routePath) => {
-			set({ activeKey: routePath });
-		},
-		/**
-		* @zh 在最前面插入标签页
-		* @en Insert a tab at the front.
-		*/
-		insertBeforeTab: (routePath, tabProps) => {
-			set((state) => {
-				if (routePath?.length) {
-					const newMap = /* @__PURE__ */ new Map([[routePath, tabProps]]);
-					for (const [key, value] of state.openTabs) newMap.set(key, value);
-					return { openTabs: newMap };
-				}
-				return state;
-			});
-		},
-		/**
-		* @zh 添加标签页
-		* @en Add a tab.
-		*/
-		addTab: (routePath, tabProps) => {
-			set((state) => {
-				if (routePath?.length) {
-					const newTabs = new Map(state.openTabs);
-					/**
-					* 1. 如果 tab 已经存在，则更新 historyState 属性，所以不去重，且 ...newTabs.get(routePath) 是为了保证首页的 closable 属性不被覆盖
-					* 2. 如果 tab 不存在，则添加到 Map 中
-					*/
-					newTabs.set(routePath, {
-						...newTabs.get(routePath),
-						...tabProps
-					});
-					return { openTabs: newTabs };
+		const guardClose = async (keys) => {
+			for (const key of keys) {
+				const fn = get().openTabs.get(key)?.beforeClose;
+				if (fn == null) continue;
+				const fns = Array.isArray(fn) ? fn : [fn];
+				for (const f of fns) try {
+					if (!await f()) return false;
+				} catch (e) {
+					console.error("[tabs] beforeClose 守卫抛错，按中止关闭处理", e);
+					return false;
 				}
-				return state;
-			});
-		},
+			}
+			return true;
+		};
 		/**
-		* @zh 移除标签页
-		* @en Remove a tab.
+		* 共用关闭路径：in-flight 去重 → 守卫 → 精确删除获批集合（TOCTOU 防护：
+		* 不对 live state 重算，await 期间新开的 tab 不受影响）→ activeKey 修正。
 		*/
-		removeTab: (routePath) => {
-			set((state) => {
+		const guardAndClose = async (removed, fallbackActive) => {
+			if (removed.length === 0) return;
+			for (const k of removed) closingKeys.add(k);
+			try {
+				if (!await guardClose(removed)) return;
+				set((state) => {
+					const toClose = new Set(removed);
+					const newTabs = new Map([...state.openTabs].filter(([k]) => !toClose.has(k)));
+					if (newTabs.size === state.openTabs.size) return state;
+					const remaining = [...newTabs.keys()];
+					return {
+						openTabs: newTabs,
+						activeKey: toClose.has(state.activeKey) || !newTabs.has(state.activeKey) ? fallbackActive(remaining) : state.activeKey
+					};
+				});
+			} finally {
+				for (const k of removed) closingKeys.delete(k);
+			}
+		};
+		return {
+			...initialState$3,
+			/**
+			* @zh 设置标签页是否处于刷新状态
+			* @en Set whether the tab is in a refresh state.
+			*/
+			setIsRefresh: (state) => {
+				set({ isRefresh: state });
+			},
+			/**
+			* @zh 设置标签页
+			* @en Set the tab.
+			*/
+			setActiveKey: (routePath) => {
+				set({ activeKey: routePath });
+			},
+			/**
+			* @zh 在最前面插入标签页
+			* @en Insert a tab at the front.
+			*/
+			insertBeforeTab: (routePath, tabProps) => {
+				set((state) => {
+					if (routePath?.length) {
+						const newMap = /* @__PURE__ */ new Map([[routePath, tabProps]]);
+						for (const [key, value] of state.openTabs) newMap.set(key, value);
+						return { openTabs: newMap };
+					}
+					return state;
+				});
+			},
+			/**
+			* @zh 添加标签页
+			* @en Add a tab.
+			*/
+			addTab: (routePath, tabProps) => {
+				set((state) => {
+					if (routePath?.length) {
+						const newTabs = new Map(state.openTabs);
+						/**
+						* 1. 如果 tab 已经存在，则更新 historyState 属性，所以不去重，且 ...newTabs.get(routePath) 是为了保证首页的 closable 属性不被覆盖
+						* 2. 如果 tab 不存在，则添加到 Map 中
+						* 3. beforeClose 是注册语义而非覆盖语义：数组 concat + 按引用去重
+						*    （keep-alive 重挂载重复注册不叠加）；null 显式清除全部守卫
+						*/
+						const prev = newTabs.get(routePath);
+						const merged = {
+							...prev,
+							...tabProps
+						};
+						if (tabProps.beforeClose === null) merged.beforeClose = void 0;
+						else if (prev?.beforeClose != null && tabProps.beforeClose !== void 0) merged.beforeClose = [...Array.isArray(prev.beforeClose) ? prev.beforeClose : [prev.beforeClose], ...Array.isArray(tabProps.beforeClose) ? tabProps.beforeClose : [tabProps.beforeClose]].filter((f, i, a) => a.indexOf(f) === i);
+						newTabs.set(routePath, merged);
+						return { openTabs: newTabs };
+					}
+					return state;
+				});
+			},
+			/**
+			* @zh 移除标签页
+			* @en Remove a tab.
+			*/
+			removeTab: async (routePath) => {
 				const homePath = "/home";
-				if (routePath === homePath) return state;
-				const newTabs = new Map(state.openTabs);
-				newTabs.delete(routePath);
-				let newActiveKey = state.activeKey;
-				if (routePath === state.activeKey) newActiveKey = Array.from(newTabs.keys()).at(-1) || homePath;
-				if (newTabs.size === 0) {
-					newTabs.set(homePath, state.openTabs.get(homePath));
-					newActiveKey = homePath;
-				}
-				return {
-					openTabs: newTabs,
-					activeKey: newActiveKey
-				};
-			});
-		},
-		/**
-		* @zh 关闭右侧标签页
-		* @en Close tabs on the right.
-		*/
-		closeRightTabs: (routePath) => {
-			set((state) => {
-				const newTabs = /* @__PURE__ */ new Map();
-				let found = false;
-				let activeKeyFound = false;
-				let newActiveKey = state.activeKey;
-				for (const [key, value] of state.openTabs) {
-					if (found) break;
-					newTabs.set(key, value);
-					if (key === routePath) found = true;
-					if (key === state.activeKey) activeKeyFound = true;
-				}
-				if (!activeKeyFound) newActiveKey = routePath;
-				return {
-					openTabs: newTabs,
-					activeKey: newActiveKey
-				};
-			});
-		},
-		/**
-		* @zh 关闭左侧标签页
-		* @en Close tabs on the left.
-		*/
-		closeLeftTabs: (routePath) => {
-			set((state) => {
-				const newTabs = /* @__PURE__ */ new Map();
+				if (!routePath?.length || routePath === homePath || closingKeys.has(routePath)) return;
+				await guardAndClose([routePath], (keys) => keys.at(-1) ?? homePath);
+			},
+			/**
+			* @zh 关闭右侧标签页
+			* @en Close tabs on the right.
+			*/
+			closeRightTabs: async (routePath) => {
+				if (closingKeys.has(routePath)) return;
+				const keys = [...get().openTabs.keys()];
+				const idx = keys.indexOf(routePath);
+				if (idx < 0) return;
+				await guardAndClose(keys.slice(idx + 1), () => routePath);
+			},
+			/**
+			* @zh 关闭左侧标签页
+			* @en Close tabs on the left.
+			*/
+			closeLeftTabs: async (routePath) => {
+				if (closingKeys.has(routePath)) return;
 				const homePath = "/home";
-				let found = false;
-				let newActiveKey = state.activeKey;
-				let activeKeyOnRight = false;
-				newTabs.set(homePath, state.openTabs.get(homePath));
-				for (const [key, value] of state.openTabs) {
-					if (key === homePath) continue;
-					if (found || key === routePath) {
-						newTabs.set(key, value);
-						found = true;
-					}
-					if (key === state.activeKey && found) activeKeyOnRight = true;
-				}
-				if (!activeKeyOnRight) newActiveKey = routePath;
-				return {
-					openTabs: newTabs,
-					activeKey: newActiveKey
-				};
-			});
-		},
-		/**
-		* @zh 关闭其他标签页
-		* @en Close other tabs.
-		*/
-		closeOtherTabs: (routePath) => {
-			set((state) => {
-				const newTabs = /* @__PURE__ */ new Map();
+				const keys = [...get().openTabs.keys()];
+				const idx = keys.indexOf(routePath);
+				if (idx < 0) return;
+				await guardAndClose(keys.slice(0, idx).filter((k) => k !== homePath), () => routePath);
+			},
+			/**
+			* @zh 关闭其他标签页
+			* @en Close other tabs.
+			*/
+			closeOtherTabs: async (routePath) => {
+				if (closingKeys.has(routePath)) return;
 				const homePath = "/home";
-				newTabs.set(homePath, state.openTabs.get(homePath));
-				if (routePath !== homePath && state.openTabs.has(routePath)) newTabs.set(routePath, state.openTabs.get(routePath));
-				let newActiveKey = state.activeKey;
-				if (!newTabs.has(state.activeKey)) newActiveKey = routePath;
-				return {
-					openTabs: newTabs,
-					activeKey: newActiveKey
-				};
-			});
-		},
-		/**
-		* @zh 关闭所有标签页
-		* @en Close all tabs.
-		*/
-		closeAllTabs: () => {
-			set((state) => {
-				const newTabs = /* @__PURE__ */ new Map();
+				await guardAndClose([...get().openTabs.keys()].filter((k) => k !== homePath && k !== routePath), () => routePath);
+			},
+			/**
+			* @zh 关闭所有标签页
+			* @en Close all tabs.
+			*/
+			closeAllTabs: async () => {
 				const homePath = "/home";
-				newTabs.set(homePath, state.openTabs.get(homePath));
-				return {
-					openTabs: newTabs,
-					activeKey: homePath
-				};
-			});
-		},
-		/**
-		* @zh 更改标签页顺序
-		* @en Change tab order.
-		*/
-		changeTabOrder: (from, to) => {
-			set((state) => {
-				const newTabs = Array.from(state.openTabs.entries());
-				const [movedTab] = newTabs.splice(from, 1);
-				newTabs.splice(to, 0, movedTab);
-				return { openTabs: new Map(newTabs) };
-			});
-		},
-		/**
-		* @zh 切换标签页最大化状态
-		* @en Toggle tab maximization status
-		* @param {boolean} state - 最大化状态
-		*/
-		toggleMaximize: (state) => {
-			set({ isMaximize: state });
-		},
-		/**
-		* @zh 设置标签页标题
-		* @en Set the tab title
-		*/
-		setTableTitle: (routePath, title) => {
-			set((state) => {
-				const newTabs = new Map(state.openTabs);
-				const targetTab = newTabs.get(routePath);
-				if (targetTab) {
-					targetTab.newTabTitle = title;
-					newTabs.set(routePath, targetTab);
-					return { openTabs: newTabs };
-				}
-				return state;
-			});
-		},
-		/**
-		* @zh 重置标签页标题（删除自定义的标题）
-		* @en Reset the tab title (delete custom titles)
-		*/
-		resetTableTitle: (routePath) => {
-			set((state) => {
-				const newTabs = new Map(state.openTabs);
-				const targetTab = newTabs.get(routePath);
-				if (targetTab) {
-					delete targetTab.newTabTitle;
-					newTabs.set(routePath, targetTab);
-					return { openTabs: newTabs };
-				}
-				return state;
-			});
-		},
-		/**
-		* @zh 重置所有标签页的状态
-		* @en Reset all tab states
-		*/
-		resetTabs: () => {
-			set(() => {
-				return { ...initialState$3 };
-			});
-		}
-	}), {
+				await guardAndClose([...get().openTabs.keys()].filter((k) => k !== homePath), () => homePath);
+			},
+			/**
+			* @zh 更改标签页顺序
+			* @en Change tab order.
+			*/
+			changeTabOrder: (from, to) => {
+				set((state) => {
+					const newTabs = Array.from(state.openTabs.entries());
+					const [movedTab] = newTabs.splice(from, 1);
+					newTabs.splice(to, 0, movedTab);
+					return { openTabs: new Map(newTabs) };
+				});
+			},
+			/**
+			* @zh 切换标签页最大化状态
+			* @en Toggle tab maximization status
+			* @param {boolean} state - 最大化状态
+			*/
+			toggleMaximize: (state) => {
+				set({ isMaximize: state });
+			},
+			/**
+			* @zh 设置标签页标题
+			* @en Set the tab title
+			*/
+			setTableTitle: (routePath, title) => {
+				set((state) => {
+					const newTabs = new Map(state.openTabs);
+					const targetTab = newTabs.get(routePath);
+					if (targetTab) {
+						targetTab.newTabTitle = title;
+						newTabs.set(routePath, targetTab);
+						return { openTabs: newTabs };
+					}
+					return state;
+				});
+			},
+			/**
+			* @zh 重置标签页标题（删除自定义的标题）
+			* @en Reset the tab title (delete custom titles)
+			*/
+			resetTableTitle: (routePath) => {
+				set((state) => {
+					const newTabs = new Map(state.openTabs);
+					const targetTab = newTabs.get(routePath);
+					if (targetTab) {
+						delete targetTab.newTabTitle;
+						newTabs.set(routePath, targetTab);
+						return { openTabs: newTabs };
+					}
+					return state;
+				});
+			},
+			/**
+			* @zh 重置所有标签页的状态
+			* @en Reset all tab states
+			*/
+			resetTabs: () => {
+				set(() => {
+					return { ...initialState$3 };
+				});
+			}
+		};
+	}, {
 		name: getAppNamespace("tabbar"),
 		/**
 		* activeKey 不需要持久化存储
@@ -9378,6 +9372,28 @@ function getBooleanOptions(t) {
 	}];
 }
 //#endregion
+//#region src/hooks/use-tab-key/index.ts
+init_remove_trailing_slash();
+/**
+* 本页自己的页签 key（`removeTrailingSlash(pathname)`），供 `setTableTitle` /
+* `resetTableTitle` / `addTab` 定位页签。
+*
+* keepAlive 陷阱：keepalive-for-react 把页面缓存在隐藏 portal 里，而 LocationContext
+* 在 KeepAlive **之上**——切 tab 时缓存树随**激活页**位置重渲染，缓存页里的
+* `useLocation()` 返回的是别家页签的路径。若拿它当页签 key，`setTableTitle` 会把
+* 本页标题写到当前激活页签上（最后打开的文档页把之后切换到的每个页签都改成自己的标题）。
+*
+* 页签存活期内 key 不变（宿主 cacheKey = pathname+search，一页一路径），故首渲染
+* （此时本页必是激活页）捕获一次即可；缓存树后续多少次重渲染都不会漂移。
+* 需要跟随导航的位置信息请直接用 `useLocation`，不要用本 hook。
+*/
+function useTabKey() {
+	const { pathname } = useLocation();
+	const keyRef = useRef(void 0);
+	if (keyRef.current === void 0) keyRef.current = removeTrailingSlash(pathname);
+	return keyRef.current;
+}
+//#endregion
 //#region src/module-loader/define-module.ts
 /**
 * 声明一个模块。
@@ -27447,4 +27463,4 @@ 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, defineModule, fetchAddMenuItem, fetchAddRoleItem, fetchAsyncRoutes, fetchDeleteMenuItem, fetchDeleteRoleItem, fetchLogin, fetchLogout, fetchMenuByRoleId, fetchMenuList, fetchRefreshToken, fetchRoleList, fetchRoleMenu, fetchUpdateMenuItem, fetchUpdateRoleItem, fetchUserInfo, filterTree, getAllExpandedKeys, getAppInfo, getBooleanOptions, getModule, getModules, getRedirectPath, getRegisteredApiPrefix, getRegisteredStore, getRoutes, getYesNoOptions, handleTree, loadAll, mapTree, menuIcons, notify, permissionPrefix, setupI18n, traverseTreeValues, unloadModule, useAccess, useAuthStore, usePreferences, useSlotNodes, 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, defineModule, fetchAddMenuItem, fetchAddRoleItem, fetchAsyncRoutes, fetchDeleteMenuItem, fetchDeleteRoleItem, fetchLogin, fetchLogout, fetchMenuByRoleId, fetchMenuList, fetchRefreshToken, fetchRoleList, fetchRoleMenu, fetchUpdateMenuItem, fetchUpdateRoleItem, fetchUserInfo, filterTree, getAllExpandedKeys, getAppInfo, getBooleanOptions, getModule, getModules, getRedirectPath, getRegisteredApiPrefix, getRegisteredStore, getRoutes, getYesNoOptions, handleTree, loadAll, mapTree, menuIcons, notify, permissionPrefix, setupI18n, traverseTreeValues, unloadModule, useAccess, useAuthStore, usePreferences, useSlotNodes, useTabKey, useTabsStore, useUserStore, external_exports as z };

package/dist/store/tabs.d.ts

@@ -1,4 +1,9 @@
 import type { TabPaneProps } from "antd";
+/**
+ * @zh 关闭前守卫：返回 false（或 Promise<false>）取消关闭；抛错按取消处理（fail-safe）
+ * @en Close guard: return false (or Promise<false>) to cancel the close; a thrown error is treated as cancel (fail-safe).
+ */
+export type BeforeTabCloseGuard = () => boolean | Promise<boolean>;
 /**
  * @zh 标签页项目属性接口
  * @en Tab item properties interface.
@@ -17,6 +22,12 @@ export interface TabItemProps extends Omit<TabPaneProps, "tab"> {
      * @see {@link https://reactrouter.com/en/main/hooks/use-navigate#optionsstate | usenavigate - options state}
      */
     historyState?: Record<string, any>;
+    /**
+     * @zh 关闭前守卫：单个或数组（顺序执行，按函数引用去重，null 清除全部守卫）。
+     * 五个关闭动作（单个/右/左/其他/全部）关闭前 await 守卫，任一否决或抛错整批取消。
+     * @en Guard before close: a single guard or an array (executed in order, deduped by reference; null clears all guards). All five close actions await guards before closing — any veto or thrown error cancels the whole batch.
+     */
+    beforeClose?: BeforeTabCloseGuard | BeforeTabCloseGuard[] | null;
 }
 export interface TabStateType extends Omit<TabItemProps, "label"> {
     label: string;
@@ -32,13 +43,13 @@ export interface TabStateType extends Omit<TabItemProps, "label"> {
  */
 interface TabsAction {
     setIsRefresh: (state: boolean) => void;
-    addTab: (routePath: string, tabProps: TabStateType) => void;
+    addTab: (routePath: string, tabProps: Partial<TabStateType>) => void;
     insertBeforeTab: (routePath: string, tabProps: TabStateType) => void;
-    removeTab: (routePath: string) => void;
-    closeRightTabs: (routePath: string) => void;
-    closeLeftTabs: (routePath: string) => void;
-    closeOtherTabs: (routePath: string) => void;
-    closeAllTabs: () => void;
+    removeTab: (routePath: string) => Promise<void>;
+    closeRightTabs: (routePath: string) => Promise<void>;
+    closeLeftTabs: (routePath: string) => Promise<void>;
+    closeOtherTabs: (routePath: string) => Promise<void>;
+    closeAllTabs: () => Promise<void>;
     setActiveKey: (routePath: string) => void;
     resetTabs: () => void;
     changeTabOrder: (from: number, to: number) => void;

package/package.json

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

package/dist/contract/define-api.d.ts

@@ -1,76 +0,0 @@
-import type { z } from "zod";
-/**
- * AC-D11/AC-D4：契约端点定义。
- *
- * route 一律相对 apiPrefix（无 oj 根绝对写法——前端受模块手册 D11 前缀收敛，
- * 根绝对逃逸语义不放行）；参数段支持 oj matchit 同款 `{id}` 单段与
- * `{*path}` catch-all，参数段内不得混字面（`{id}.json` 非法）。
- */
-export type HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "HEAD" | "OPTIONS";
-/**
- * multipart/form-data 的文件部件：**只声明名字与形态**。
- *
- * 二进制刻意不进 zod（JSON Schema 无 binary 类型，且字节由运行时的 FormData
- * 组装）：oj 侧按 `http.files`（元数据 { field, filename, content_type, size }）
- * 与 `http.file(i)`（字节）读取。
- */
-export interface ApiFormFile {
-    /** 表单字段名（= FormData 的 append key = oj 侧 http.files[].field） */
-    name: string;
-    /** true = 必传；缺省可选（可选文件不 append 部件，oj 侧自然缺省） */
-    required?: boolean;
-    /** true = 同名多文件：生成 client 接受数组并逐个 append（oj 侧 http.files 多条） */
-    multiple?: boolean;
-}
-/** multipart/form-data 请求体：文本部件走 zod，文件部件只声明形态（与 body 互斥） */
-export interface ApiFormInput {
-    /** 文本部件 schema（z.object——字段名即部件名；进 OpenAPI 的 multipart JSON schema） */
-    fields?: z.ZodType;
-    /** 文件部件（与 fields 至少声明其一） */
-    files?: ApiFormFile[];
-}
-export interface ApiDefinitionInput {
-    /** 模块 API 前缀（"/" 开头）；uni-dev 形态字面等于 oj 模块段名（AC-D9） */
-    apiPrefix: string;
-    /**
-     * 线上 URL 前缀（"/" 开头，D-M8）：存量 oj 后端 URL 命名空间与目录名错位时
-     * 显式声明（如目录 workitems、URL /workspaces/{slug}/...）。缺省 = apiPrefix。
-     * 认领/护栏身份仍按 apiPrefix（目录名）；线上前缀不一致的同模块端点混用报错。
-     */
-    urlPrefix?: string;
-    /** 相对 apiPrefix 的路由（"/" 开头），支持 `{id}` / `{*path}` 参数段 */
-    route: string;
-    /** HTTP 方法，缺省 "GET"（IR 层归一） */
-    method?: HttpMethod;
-    /** 查询参数 schema（声明语义类型，URL 序列化由生成物负责） */
-    query?: z.ZodType;
-    /** 路径参数 schema（与 route 参数段一一对应） */
-    params?: z.ZodType;
-    /** 请求体 schema（JSON；与 form 互斥） */
-    body?: z.ZodType;
-    /**
-     * multipart/form-data 请求体（与 body 互斥）：文本部件写进 form.fields（zod），
-     * 文件部件只声明名字——二进制无法保真进 JSON Schema，FormData 由生成 client 组装。
-     */
-    form?: ApiFormInput;
-    /** 响应信封 data 部分的 schema；与 response:"raw" 互斥 */
-    data?: z.ZodType;
-    /** "raw" = 二进制/非信封逃生口：不解包、不校验、不进 mock 生成 */
-    response?: "raw";
-    /** true = 该端点不触发全局加载条（客户端表现层开关，非线协议，不进 OpenAPI） */
-    ignoreLoading?: boolean;
-    /** 接口描述（进 OpenAPI 文档） */
-    description?: string;
-}
-/**
- * defineApi 产物的品牌标记（Symbol.for 跨模块实例稳定）。
- * 非枚举属性——不影响 .route 等的可枚举性；codegen 据此可靠识别端点，
- * 不与契约文件里导出的普通 schema/常量混淆。
- *
- * 注：旧标记 `Symbol.for("ram.api.def")` 不在本包公开——只有 cli 的 IR 识别
- * 存量产物时才需要它，故由 `packages/cli/src/contract/ir.ts` 自行声明（避免把
- * 兼容专用符号扩进公共出口，设计 §7 R3）。
- */
-export declare const API_DEF: unique symbol;
-/** 定义一个契约端点：定义期校验后原样返回（描述符 .route 等可枚举，供 codegen/mock 遍历） */
-export declare function defineApi<D extends ApiDefinitionInput>(def: D): D;

package/dist/contract/define-api.js

@@ -1,61 +0,0 @@
-/** oj matchit 同款参数段：整段必须是 {name} 或 {*name}，不得混字面 */
-const PARAM_SEGMENT = /^\{\*?[a-z_]\w*\}$/i;
-function fail(route, reason) {
-    throw new Error(`[契约] 端点定义非法（route: ${route}）：${reason}`);
-}
-function validateDefinition(def) {
-    const { apiPrefix, route } = def;
-    if (!apiPrefix?.startsWith("/")) {
-        throw new Error(`[契约] apiPrefix 必须以 "/" 开头（收到: ${apiPrefix}）——如 "/order"；uni-dev 形态请与 oj 模块段名保持一致（AC-D9）。`);
-    }
-    if (def.urlPrefix !== undefined && !def.urlPrefix.startsWith("/"))
-        fail(route, `urlPrefix 必须以 "/" 开头（收到: ${def.urlPrefix}）。`);
-    if (!route?.startsWith("/"))
-        fail(route, `route 必须以 "/" 开头（收到: ${route}），且一律相对 apiPrefix——不支持 oj 的根绝对写法（模块手册 D11 前缀收敛）。`);
-    if (route.split("/").some(seg => seg === ".." || seg === "." || seg === "\\"))
-        fail(route, "route 含路径穿越段（.././\\），请改为正常静态段。");
-    for (const seg of route.split("/")) {
-        if (seg.includes("{") && !PARAM_SEGMENT.test(seg))
-            fail(route, `参数段 "${seg}" 混入字面量——matchit 约束：参数段必须整段为 {name} 或 {*name}，需要前缀/后缀字面时请拆成静态多段。`);
-    }
-    if (def.data && def.response === "raw")
-        fail(route, "data schema 与 response:\"raw\" 互斥——raw 端点不解包信封，不需要 data schema。");
-    if (def.form && def.body)
-        fail(route, "form 与 body 互斥——一个端点只有一种请求体形态：multipart/form-data（form）与 JSON（body）声明其一，文本字段请写进 form.fields。");
-    if (def.form) {
-        const files = def.form.files ?? [];
-        if (!def.form.fields && files.length === 0)
-            fail(route, "form 至少需要 fields 或一项 files——空 multipart 请求体无意义；无请求体请删掉 form（改用 query/params）。");
-        const seen = new Set();
-        for (const file of files) {
-            if (!file?.name)
-                fail(route, "form.files 每项必须有 name——它既是 FormData 的 append key，也是 oj 侧 http.files[].field 的字段名。");
-            if (seen.has(file.name))
-                fail(route, `form.files 字段名 "${file.name}" 重复——同名多文件请用 multiple: true。`);
-            seen.add(file.name);
-        }
-    }
-    if (def.response !== undefined && def.response !== "raw")
-        fail(route, `response 仅支持 "raw"（收到: ${String(def.response)}）。`);
-    // 评审 F9：方法面在定义期封顶，而不是延迟到 codegen 才炸
-    if (def.method === "OPTIONS")
-        fail(route, "OPTIONS 不在支持范围（ky/oj 均无对应方法）——预检请求由 fetch/CORS 层处理，契约不表达。");
-    if (def.method === "HEAD" && def.data)
-        fail(route, "HEAD 端点无响应体，不能声明 data schema——需要响应体请改用 GET。");
-}
-/**
- * defineApi 产物的品牌标记（Symbol.for 跨模块实例稳定）。
- * 非枚举属性——不影响 .route 等的可枚举性；codegen 据此可靠识别端点，
- * 不与契约文件里导出的普通 schema/常量混淆。
- *
- * 注：旧标记 `Symbol.for("ram.api.def")` 不在本包公开——只有 cli 的 IR 识别
- * 存量产物时才需要它，故由 `packages/cli/src/contract/ir.ts` 自行声明（避免把
- * 兼容专用符号扩进公共出口，设计 §7 R3）。
- */
-export const API_DEF = Symbol.for("ojm.api.def");
-/** 定义一个契约端点：定义期校验后原样返回（描述符 .route 等可枚举，供 codegen/mock 遍历） */
-export function defineApi(def) {
-    validateDefinition(def);
-    Object.defineProperty(def, API_DEF, { value: true, enumerable: false });
-    return def;
-}