@oj-module/cli 0.2.20 → 0.2.23

package/devkit/manual.md

@@ -39,6 +39,7 @@
 ├── tests/                 # 后端 BDD 测试（node:sqlite 内存库 + 真实迁移建表）
 ├── src/
 │   ├── tsconfig.json      # 后端 typecheck 工程（extends 上两者，exclude */web）
+│   ├── .ojm-builtin.json  # 框架自带方案名单（init 派生，可手改/删除；打包排除 + info 折叠，见 §11）
 │   ├── styles.css
 │   ├── _platform/         # 框架级：users 表 / rbac / 市场编排 / 生命周期
 │   │   ├── api/           #   + _shared/（respond、service/、site-facade）
@@ -74,7 +75,19 @@
 > **历史布局仍被识别**：`web/src/<name>`（uni-dev）与 `web/<name>`（框架根仓）照旧可用，
 > 只是 `ojm init` 不再产出。两套源码树**互斥**——同时存在时 `ojm` 直接报错，而不是静默选一个。
 
-登录账号 `admin / 123456`。端口：前端 devServer **5174**，oj 后端 **9778**
+登录账号：**账号名=内置角色名**一一对应，口令均 `123456`，且全部**免首登改密**（must_change=0，纯开发便利，勿用于生产）：
+
+| 账号 | 角色 | 能干什么 |
+|---|---|---|
+| `superadmin` | superadmin | 全部能力（含安全组设置、成员资格管理） |
+| `admin` | admin | 日常管理（不含 superadmin 专属项） |
+| `editor` | editor | 页面门编辑级 |
+| `viewer` | viewer | 页面门访客级 |
+
+> 旧脚手架库（admin 绑 superadmin / must_change=1）**无需手工迁移**：seed 每次启动幂等重放，
+> 自动收敛为账号名=角色名并清零 must_change（`DELETE` 旧绑定 + `UPDATE`，见 `_platform/api/seed.sql`）。
+
+端口：前端 devServer **5174**，oj 后端 **9778**
 （以工程根 `config.yaml` 的 `server.port` 为准）。
 
 ### 1.2 两个模块体系，同名不同物
@@ -93,6 +106,33 @@
 历史布局下两侧分居 `web/src/<模块>/` 与 `api/src/<模块>/`——**同一个名字、两个目录**，
 是布局迁移时最容易对不上的地方。
 
+#### manifest.yaml 与 solution.yaml：两种身份，别混淆
+
+工程里会出现两个名字里带 "manifest" 的文件，用途**完全不同**，混用会出构建/运行期怪问题：
+
+| 文件 | 层级 | 身份 | 谁读它 | 写什么 |
+|---|---|---|---|---|
+| `src/<模块>/api/manifest.yaml` | **模块级**（每个后端模块一份） | oj **原生七键**清单（`name`/`desc`/`version`/`tables`/…） | **oj 运行时**——按 `manifest.yaml` 枚举发现并校验 api 后端模块 | 模块名、版本、表清单（与 `schema.yaml` 双向一致，§1.5） |
+| `solution.yaml`（`src/<模块>/` 或工程根） | **方案级**（整个方案一份） | 方案包契约（身份 / 路由 / api 段 / web 段 / 权限 / …） | **`ojm build --bundle`**——打包入口与契约校验 | 方案名、版本、`api` 段（模块+前缀+tables+deps+anonymous）、`web` 段（entry/css/integrity）、`routes`、`health` |
+
+关键区别与红线：
+
+- **模块级 `manifest.yaml` 是 oj 发现 api 后端的唯一真源**：`ojm dev/build` 递归扫描
+  `src/<模块>/api/manifest.yaml` 认领后端模块；oj 启动也用它做强校验（`name ==` 目录名、版本同源）。
+  它**只能有 oj 原生七键**，写任何方案级字段（`routes` / `permissions` / …）都会被拒启。
+- **方案级契约以前也叫 `manifest.yaml`（工程根）**，但它会和上面的「oj 按 `manifest.yaml` 枚举 api 模块」
+  撞名：**工程根再放一份 `manifest.yaml` 当 bundle 契约，会被 oj 的搜索枚举误当成 api 模块**，污染后端发现。
+  所以解决方案统一改名为 **`solution.yaml`**，`ojm build --bundle` 优先认它（`manifest.yaml` 仅作旧方案回退）——
+  **后端按 `manifest.yaml` 枚举 api、打包按 `solution.yaml` 取契约**，两条枚举互不干扰。
+  **位置**：单模块方案推荐放 `src/<模块>/solution.yaml`（契约与所打包模块同位）；`ojm build --bundle`
+  也兼容工程根 `solution.yaml`，以及两处的 `manifest.yaml` 回退。**模块级契约只认 `src/<模块>/` 根下、
+  绝不进 `<模块>/api/`**——否则照样会和 oj 的 api 枚举撞车。
+- 进包后文件名固定回到 `manifest.yaml`（安装侧只认这个名字）：`ojm build --bundle` 把工程根或
+  `src/<模块>/` 下的 `solution.yaml`（或旧 `manifest.yaml`）拷贝进 tgz 内的 `<name>-<version>/manifest.yaml`，安装器/市场仍按老名字消费。
+
+> 一句话：**`manifest.yaml` 是给 oj 认模块用的（模块级、七键、oj 枚举）；`solution.yaml` 是给 `ojm build --bundle`
+> 打包用的（方案级、工程根）。两者文件名不同、层级不同、读者不同，别写错层。**
+
 ### 1.3 后端路由 = 目录镜像
 
 ```
@@ -1377,12 +1417,15 @@ useEffect(() => {
 pnpm dev               # 开发：devServer + oj 后端（src/<模块>/api 保存即热更）
 # 交互快捷键（仅 TTY 终端启用，类 Vite）：
 #   r  强制重建并热更新    h  显示帮助    c  清屏    o  浏览器打开    q  退出（oj 一并终止）
+# 提示行常驻终端最末行（滚动区），日志在其上方滚动不会被顶走（ojm ≥ 0.2.22）
 # Ctrl+C（SIGINT）/ kill（SIGTERM）终止 dev 时，前端与后端 oj 一起终止：
 # 先关 SSE 通道 → 停 oj 子进程 → 打印「后端 oj 已随前端一起终止」，不留 oj 孤儿占端口
 pnpm build             # = ojm build：oj build（生成 routes.js）+ 前端全站合并到 web/dist
 pnpm preview           # = ojm preview：oj migrate（verify 闸）→ oj serve 单服务（API + 静态 SPA 同进程）
 pnpm typecheck         # = tsc --noEmit（前端工程）
 pnpm typecheck:api     # = tsc --noEmit -p src/tsconfig.json（后端工程，见 §6.5）
+pnpm new               # = ojm new <name>：脚手架内生成用户方案骨架（见 §10.1）
+pnpm bundle            # = ojm build --bundle：打包全部用户方案（自带方案自动排除，见 §11）
 pnpm exec ojm info     # 版本矩阵 + 模块清单（报障用）
 pnpm exec ojm vendor   # 下载/重装 oj 二进制
 ```
@@ -1616,6 +1659,28 @@ export default async (path: string, html: string) => {
 > release 下只有 `routes.js` 里的路由存在，目录镜像路由不生效——所以参数路由要先
 > `ojm build` 再测（见 §7）。
 
+#### `ojm build --bundle [name]`
+
+打包**方案包**（solution bundle，可分发产物；语义细节见 §11）。只组装不构建，先 `ojm build` 再打包。
+
+- `--bundle` 无参：工程根有 `solution.yaml` 则只打根契约（旧单方案行为零变化）；
+  否则收集 `src/*/` 下全部**用户方案**契约逐个打包（框架自带方案自动排除，日志注明「框架自带，跳过」）。
+- `--bundle <name>` / `--bundle=<name>`：只打 `src/<name>/solution.yaml` 这一份（manifest.yaml 回退）。
+- 两段式：全部契约校验通过才开始写盘；零用户方案时报错指路 `ojm new`。
+
+#### `ojm new <name> [--layout container|none] [--api]`
+
+脚手架内生成一份用户方案骨架（module-root 布局）：`src/<name>/solution.yaml` +
+`web/{entry.ts,pages/,locales/}`（`--api` 再加 `api/{manifest.yaml,api.ts}`）。
+生成即被扫描收录，补产物后 `ojm build --bundle <name>` 直接可打（round-trip）。
+非 module-root 布局拒绝（会先要求迁移）；名字撞内置方案 / 保留名 / 已存在目录都会拒绝。
+```bash
+ojm new crm --layout container   # 建 src/crm/ 骨架
+pnpm dev                         # 看效果
+ojm build --bundle crm           # 打包
+```
+
+
 #### `ojm preview [port]`
 
 生产形态预览（设计 §6，2026-10-19 单服务化）：
@@ -1647,9 +1712,11 @@ export default async (path: string, html: string) => {
 
 生成物重跑即覆盖（eslint 已忽略）；唯一例外是带 `// ojm-api:stub` 指纹的 stub，人碰过则工具永不写删。
 
-#### `ojm info`
+#### `ojm info [--all]`
 
 输出版本矩阵（`@oj-module/cli` / `@oj-module/runtime` / 钉版 `@plane/*` / `oj` 二进制）与模块清单。
+module-root 下数据源是「扫描 + `web.config.ts` 登记」并集（未登记的用户模块也可见）。
+框架自带方案默认折叠为一行计数（`--all` 展开平铺）。
 **报障用**：拿不准「工程里到底装了什么版本、哪些模块被登记」时，先 `ojm info` 贴出来。
 
 #### `ojm vendor [tag] [--force]`
@@ -1722,25 +1789,44 @@ export default async (path: string, html: string) => {
 ## §11 方案包：打包与分发
 
 「站点级构建」见 §7；本节讲**方案包**（solution bundle）——单方案的可分发产物与到达站点的方式。
+一个脚手架可放多份用户方案（`ojm new` 逐个生成，各自一份 `src/<name>/solution.yaml`），
+`ojm build --bundle` 无参时全部打包、逐个校验独立出包；框架自带方案自动排除（名单见
+`src/.ojm-builtin.json`，`ojm info` 默认折叠自带模块）。
+**从开发到发布的完整过程视角（含签名与私钥保存纪律）见**
+[`docs/guides/solution-dev-build-publish.md`](../guides/solution-dev-build-publish.md)。
 
 ### 11.1 打包：`ojm build --bundle`
 
 ```bash
 ojm build --bundle            # --out <dir> 缺省工程根 dist/（方案包输出目录，与后端产物 api/dist 无关）
-# [ojm] 方案包已生成 → dist/<name>-<version>.tgz
+ojm build --bundle crm        # 只打 src/crm/ 这一份；--bundle=crm 等价
+# [ojm] 方案包已生成 → dist/<name>-<version>.tgz（多份用户方案时逐份输出，共打包 N 份）
 # [ojm] sha256：…（确定性打包：同源同字节）
+# 没有可打包的用户方案时：报错指向 ojm new（不静默产出空批次）
 ```
 
 > `--bundle` 只**组装**，不重跑构建：入包内容取自 `api/dist/<name>-<version>/` 与
 > `web/dist/modules/<name>/`——先 `ojm build` 再打包。
 
-- 打包即校验（fail-fast，坏清单出不了包）：方案 manifest 契约校验（字段齐全 / 类型白名单 /
-  保留名 / 键空间 → 可读违规清单）→ 文件面校验（`api.tables` ↔ `schema.yaml`、locales 双语齐备）。
+- **契约入口（按优先级）**：`src/<模块>/solution.yaml` ≻ 工程根 `solution.yaml` ≻
+  `src/<模块>/manifest.yaml` ≻ 工程根 `manifest.yaml`（方案级；`manifest.yaml` 为旧方案回退）。
+  **单模块方案推荐把契约放在 `src/<模块>/solution.yaml`**——契约与它所打包的模块同位，最直观。
+  文件名刻意避开 `manifest.yaml`：oj 按 `manifest.yaml` 枚举发现 api 后端模块（§1.2），工程根若放一份
+  bundle 契约会污染那条搜索枚举；故用 `solution.yaml` 隔开两条枚举——**后端按 `manifest.yaml` 枚举 api、
+  打包按 `solution.yaml` 取契约**，不再冲突。模块级契约同样**只认 `src/<模块>/` 根下、绝不进 `<模块>/api/`**，
+  否则会与 oj 的 api 枚举撞车。tgz 内固定写回 `manifest.yaml`（安装侧只认这个名字）。
+- **两段式**：先对全部目标契约跑完校验（纯读零写盘），全绿才开始逐个写 tgz——任一校验失败
+  dist/ 零增量，报错指名失败方案（发布者不会把半截批次扫进 CDN 索引）。校验项（fail-fast，
+  坏清单出不了包）：方案 solution 契约（字段齐全 / 类型白名单 / 保留名 / 键空间 → 可读违规清单）
+  → 文件面（`api.tables` ↔ `schema.yaml`、locales 双语齐备）→ 模块级契约 `name` 必须 === 目录名。
+- 框架自带方案不参与打包：`src/.ojm-builtin.json` 名单内的模块契约被跳过（逐条日志）；
+  该文件由 `ojm init` 从模板白名单派生，**可手改/删除**（删名 = 恢复参与打包），重跑 init 缺失才补写。
+  它只是打包排除 / info 折叠提示，**不是安全边界**：文件永不入包，安装侧信任链（签名 + 信任库 + TOFU）与它无关。
 - **只出包不签名**——签名见 §12（关注点分离：作者签名是显式动作，不是构建副产品）。
 - 产物内 `manifest.yaml` 的 `archive` 段是 **Form A**（仅 `file`）；`sha256`/`size` 由
   file 源上传时点补齐（宿主安装器）或发布通道 Form B 自带。
-- **入包红线**：`*.pem` / `*.key` / `.env` / `id_ed25519` / `id_rsa` 等私钥形态文件禁入包
-  （与 `modules.json` 禁入同款自检）——私钥入包即信任根基烧毁。
+- **入包红线**：`*.pem` / `*.key` / `*.p12` / `*.pfx` / `.env` 系 / `id_ed25519` / `id_rsa`
+  等私钥形态文件禁入包（与 `modules.json` 禁入同款自检，0.2.23 起扩面）——私钥入包即信任根基烧毁。
 
 ### 11.2 两种分发源
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@oj-module/cli",
   "type": "module",
-  "version": "0.2.20",
+  "version": "0.2.23",
   "description": "React Antd Admin 模块工程命令行工具（含预构建宿主 shell-dist）",
   "license": "MIT",
   "exports": {
@@ -49,7 +49,7 @@
   ],
   "dependencies": {
     "@faker-js/faker": "^10.4.0",
-    "@oj-module/runtime": "0.2.20",
+    "@oj-module/runtime": "0.2.23",
     "@redocly/cli": "^2.51.0",
     "@tailwindcss/vite": "^4.3.0",
     "esbuild": "^0.28.2",

package/shell-dist/assets/runtime.js

@@ -204,6 +204,7 @@ var init_site_base = __esmMin((() => {
 * 子路径部署（/oj/wiki/...）下直接与 loginPath 比较恒为 false，401 时会重复 goLogin。
 * React 组件内请用 `useLocation()`（react-router 已剥离 basename），无需本函数。
 *
+* @param pathname 原始路径（含部署 base，如 `location.pathname`）
 * @param base 部署 base，恒以 `/` 结尾；缺省取 `resolveSiteBase()`（部署期注入优先，
 * 见 utils/site-base.ts —— runtime 产物里的 `import.meta.env.BASE_URL` 是构建期
 * 内联的 `/`，子路径部署下直接用它恒错）
@@ -303,10 +304,10 @@ function getAppInfo() {
 	return {
 		"pkg": {
 			"name": "@oj-module/runtime",
-			"version": "0.2.20",
+			"version": "0.2.23",
 			"license": "MIT"
 		},
-		"lastBuildTime": "2026-10-22 12:17:23"
+		"lastBuildTime": "2026-10-22 18:50:31"
 	};
 }
 var init_get_app_info = __esmMin((() => {}));
@@ -429,7 +430,7 @@ function PageError({ error, resetErrorBoundary }) {
 	};
 	useEffect(() => {
 		if (enableDynamicTitle) document.title = t("exception.pageErrorTitle");
-	}, [enableDynamicTitle]);
+	}, [enableDynamicTitle, t]);
 	return /* @__PURE__ */ jsx(Result, {
 		status: "error",
 		icon: /* @__PURE__ */ jsx("div", {
@@ -3495,7 +3496,7 @@ function useCurrentRoute() {
 	const matches = useMatches();
 	return useMemo(() => {
 		return matches[matches.length - 1];
-	}, [matches, location]);
+	}, [matches]);
 }
 var init_use_current_route = __esmMin((() => {}));
 //#endregion
@@ -3595,7 +3596,7 @@ function useCssVar(name, root = defaultRoot, options = {}) {
 	}), [name, root]);
 	useEffect(() => {
 		if (options?.initialValue) controls.set(options.initialValue);
-	}, [options?.initialValue]);
+	}, [options?.initialValue, controls]);
 	useEffect(() => {
 		return () => controls.remove();
 	}, [controls]);
@@ -3656,7 +3657,7 @@ var init_dom = __esmMin((() => {}));
 * @en Get the style of the layout content area
 */
 function useLayoutContentStyle() {
-	const contentElement = useRef(null);
+	const contentElementRef = useRef(null);
 	const [visibleDomRect, setVisibleDomRect] = useState(null);
 	const resizeObserverRef = useRef(null);
 	const contentHeightControls = useCssVar(CSS_VARIABLE_LAYOUT_CONTENT_HEIGHT);
@@ -3673,7 +3674,7 @@ function useLayoutContentStyle() {
 		};
 	}, [visibleDomRect]);
 	const debouncedCalcHeight = useDebounceFn((_entries) => {
-		const rect = getElementVisibleRect(contentElement.current);
+		const rect = getElementVisibleRect(contentElementRef.current);
 		setVisibleDomRect(rect);
 		if (rect) {
 			contentHeightControls.set(`${rect.height}px`);
@@ -3681,10 +3682,10 @@ function useLayoutContentStyle() {
 		}
 	}, { wait: 16 });
 	useEffect(() => {
-		if (contentElement.current && !resizeObserverRef.current) {
+		if (contentElementRef.current && !resizeObserverRef.current) {
 			const resizeObserver = new ResizeObserver(debouncedCalcHeight.run);
 			resizeObserverRef.current = resizeObserver;
-			resizeObserver.observe(contentElement.current);
+			resizeObserver.observe(contentElementRef.current);
 		}
 		return () => {
 			resizeObserverRef.current?.disconnect();
@@ -3692,7 +3693,7 @@ function useLayoutContentStyle() {
 		};
 	}, [debouncedCalcHeight]);
 	return {
-		contentElement,
+		contentElementRef,
 		overlayStyle,
 		visibleDomRect
 	};
@@ -4173,7 +4174,7 @@ function KeepAliveLayer() {
 		(aliveRef.current?.getCacheNodes?.())?.forEach((node) => {
 			if (!openTabs.has(node.cacheKey)) aliveRef.current?.destroy(node.cacheKey);
 		});
-	}, [openTabs]);
+	}, [openTabs, aliveRef]);
 	/**
 	* 关闭多 tab 功能时，清空所有非当前页面缓存
 	*/
@@ -4181,10 +4182,18 @@ function KeepAliveLayer() {
 		if (!tabbarEnable) (aliveRef.current?.getCacheNodes?.())?.forEach((node) => {
 			if (node.cacheKey !== cacheKey) aliveRef.current?.destroy(node.cacheKey);
 		});
-	}, [tabbarEnable]);
+	}, [
+		tabbarEnable,
+		aliveRef,
+		cacheKey
+	]);
 	useEffect(() => {
 		if (tabbarEnable && isRefresh) aliveRef.current?.refresh();
-	}, [isRefresh]);
+	}, [
+		isRefresh,
+		aliveRef,
+		tabbarEnable
+	]);
 	const keepAliveExclude = useMemo(() => {
 		/**
 		* 不开启多 tab 时不需要 KeepAlive，把所有路由放进 exclude 仅保留切换动画
@@ -4212,7 +4221,7 @@ var init_keep_alive_layer = __esmMin((() => {
 //#region src/layout/layout-content/index.tsx
 function LayoutContent() {
 	const { token: { colorBgLayout } } = theme.useToken();
-	const { contentElement } = useLayoutContentStyle();
+	const { contentElementRef } = useLayoutContentStyle();
 	const enableFooter = usePreferencesStore((state) => state.enableFooter);
 	const fixedFooter = usePreferencesStore((state) => state.fixedFooter);
 	/**
@@ -4221,7 +4230,7 @@ function LayoutContent() {
 	*/
 	return /* @__PURE__ */ jsx("main", {
 		id: ELEMENT_ID_MAIN_CONTENT,
-		ref: contentElement,
+		ref: contentElementRef,
 		className: "relative overflow-y-auto overflow-x-hidden grow",
 		style: { backgroundColor: colorBgLayout },
 		children: /* @__PURE__ */ jsx(Scrollbar, { children: /* @__PURE__ */ jsx(GlobalSpin, { children: /* @__PURE__ */ jsxs("div", {
@@ -4447,7 +4456,11 @@ function GlobalSearch() {
 	useKeyPress("downarrow", handleDown);
 	useEffect(() => {
 		if (!keyword.length && Array.isArray(searchHistory)) setResultOptions(searchMenuList.filter((item) => searchHistory?.includes(item.key)));
-	}, [keyword, searchHistory]);
+	}, [
+		keyword,
+		searchHistory,
+		searchMenuList
+	]);
 	return /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsxs("div", {
 		onClick: () => setOpen((open) => !open),
 		className: "group flex justify-center items-center gap-2 md:bg-colorBgLayout px-3 py-1.5 rounded-full cursor-pointer text-colorTextSecondary hover:text-colorText md:mr-2.5",
@@ -5113,18 +5126,18 @@ function Sidebar() {
 				name: item.name,
 				checked: item.value,
 				onChange: handleChange,
-				children: item.label,
-				disabled: item.disabled
+				disabled: item.disabled,
+				children: item.label
 			}, item.name);
 		}),
 		/* @__PURE__ */ jsx(SwitchItem, {
 			name: "sidebarTheme",
 			checked: sidebarTheme === "light",
 			onChange: (name, value) => setPreferences(name, value ? "light" : "dark"),
-			children: t("preferences.sidebar.sidebarTheme"),
 			disabled: !sidebarEnable,
 			unCheckedChildren: /* @__PURE__ */ jsx(RiContrastFill, {}),
-			checkedChildren: /* @__PURE__ */ jsx(RiMoonIcon, {})
+			checkedChildren: /* @__PURE__ */ jsx(RiMoonIcon, {}),
+			children: t("preferences.sidebar.sidebarTheme")
 		}),
 		/* @__PURE__ */ jsx(NumberInputSpinner, {
 			min: 40,
@@ -5702,7 +5715,7 @@ function UserMenu({ ...restProps }) {
 		}
 		if (key === "personal-center") navigate("/personal-center/my-profile");
 	};
-	const altView = useMemo(() => isWindowsOs() ? "Alt" : "⌥", [isWindowsOs]);
+	const altView = useMemo(() => isWindowsOs() ? "Alt" : "⌥", []);
 	const items = [{
 		label: t("personal-center:menu.personalCenter"),
 		key: "personal-center",
@@ -5973,7 +5986,7 @@ function LayoutMenu({ mode = "inline", autoExpandCurrentMenu, handleMenuSelect,
 		isMobile,
 		sidebarCollapsed
 	]);
-	const handleOpenChange = (keys) => {
+	const handleOpenChange = useCallback((keys) => {
 		/**
 		* 1. 手风琴模式，点击菜单项，自动关闭其他菜单
 		* 2. 非手风琴模式且菜单是收起的，鼠标悬浮菜单自动关闭其他菜单
@@ -5992,7 +6005,12 @@ function LayoutMenu({ mode = "inline", autoExpandCurrentMenu, handleMenuSelect,
 				if (currentCloseKey) setOpenKeys(menuParentKeys[currentCloseKey]);
 			}
 		} else setOpenKeys(keys);
-	};
+	}, [
+		accordion,
+		sidebarCollapsed,
+		openKeys,
+		menuParentKeys
+	]);
 	const menuOpenProps = useMemo(() => {
 		if (autoExpandCurrentMenu) return {
 			openKeys,
@@ -6019,7 +6037,8 @@ function LayoutMenu({ mode = "inline", autoExpandCurrentMenu, handleMenuSelect,
 	}, [
 		matches,
 		sidebarCollapsed,
-		getSelectedKeys
+		getSelectedKeys,
+		accordion
 	]);
 	return /* @__PURE__ */ jsx(Menu, {
 		/**
@@ -6552,7 +6571,6 @@ function useDropdownMenu() {
 	}, [
 		t,
 		activeKey,
-		homePath,
 		openTabs
 	]);
 	/**
@@ -6569,6 +6587,8 @@ function useDropdownMenu() {
 		[TabActionKeys.CLOSE_OTHERS]: closeOtherTabs,
 		[TabActionKeys.CLOSE_ALL]: closeAllTabs
 	}), [
+		refresh,
+		setIsRefresh,
 		removeTab,
 		closeRightTabs,
 		closeLeftTabs,
@@ -6814,7 +6834,7 @@ function LayoutTabbar() {
 			hash: ""
 		};
 		navigate(key + historyState.search + historyState.hash);
-	}, [openTabs]);
+	}, [openTabs, navigate]);
 	/**
 	* 处理标签页编辑（关闭）
 	* @param {React.MouseEvent | React.KeyboardEvent | string} key - 被编辑的标签页的key
@@ -6941,7 +6961,8 @@ function LayoutTabbar() {
 		location,
 		currentRoute,
 		setActiveKey,
-		addTab
+		addTab,
+		activeKey
 	]);
 	return /* @__PURE__ */ jsx("div", {
 		className: classes.tabsContainer,
@@ -7023,7 +7044,7 @@ function ContainerLayout() {
 		if (screens.lg && !screens.xl) setPreferences("sidebarCollapsed", true);
 		else if (screens.xl) setPreferences("sidebarCollapsed", false);
 		else if (screens.xs || screens.sm && !screens.md) setPreferences("sidebarCollapsed", false);
-	}, [screens]);
+	}, [screens, setPreferences]);
 	const sidebarEnableState = useMemo(() => !isTopNav && sidebarEnable, [isTopNav, sidebarEnable]);
 	const computedSidebarWidth = useMemo(() => {
 		if (isMaximize || isMobile) return 0;
@@ -7049,7 +7070,7 @@ function ContainerLayout() {
 		let height = 48;
 		if (tabbarEnable) height += 35;
 		return height;
-	}, [tabbarEnable, 35]);
+	}, [tabbarEnable]);
 	useEffect(() => {
 		setLayoutHeaderHeight(isMaximize ? 35 : headerWrapperHeight);
 	}, [headerWrapperHeight, isMaximize]);
@@ -7934,7 +7955,7 @@ async function generateRoutesFromBackend(backendRoutes) {
 	/**
 	* 转换路由配置
 	* @param route 原始路由配置
-	* @param parentPath 父级路径（用于嵌套路由）
+	* @param parentComponentPath 父级组件路径（用于嵌套路由）
 	* @returns 转换后的路由配置
 	*/
 	const transformRoute = async (route, parentComponentPath) => {
@@ -8918,8 +8939,6 @@ var init_remember_route = __esmMin((() => {
 * 必须带上部署 base（`resolveSiteBase()`）：子路径部署下 `location.href = "/login"`
 * 会跳到宿主机根，而不是 `/oj/login`。不能用 `import.meta.env.BASE_URL`——预构建
 * 产物里它是构建期内联的 `/`。
-*
-* @returns 无返回值
 */
 function goLogin() {
 	useAuthStore.getState().reset();
@@ -9022,6 +9041,8 @@ function onRefreshFailed(error) {
 * 订阅者对象应包含 resolve 和 reject 方法。
 *
 * @param subscriber 订阅者对象，包含 resolve 和 reject 方法
+* @param subscriber.resolve 当 token 刷新成功时调用的函数，传入新的 token
+* @param subscriber.reject 当 token 刷新失败时调用的函数，传入错误信息
 */
 function addRefreshSubscriber(subscriber) {
 	refreshSubscribers.push(subscriber);
@@ -9447,6 +9468,10 @@ function useAccess() {
 * 权限验证组件
 *
 * @param AccessControlProps 权限验证组件的属性
+* @param AccessControlProps.type 权限类型，默认为 code
+* @param AccessControlProps.codes 权限值，可以是字符串或字符串数组
+* @param AccessControlProps.children 有权限时渲染的子组件
+* @param AccessControlProps.fallback 无权限时显示的内容
 * @returns 若子组件存在，并且传入的权限值有效，则返回子组件；否则返回 null
 */
 function AccessControl({ type = "code", codes, children, fallback }) {
@@ -9800,7 +9825,7 @@ function BasicTable(props) {
 		if (enableFooter && fixedFooter) return 40;
 		return 0;
 	}, [enableFooter, fixedFooter]);
-	const getPaginationProps = () => {
+	const getPaginationProps = useCallback(() => {
 		if (props.pagination === false) return false;
 		return {
 			placement: ["bottomStart"],
@@ -9810,7 +9835,7 @@ function BasicTable(props) {
 			showTotal: (total) => t("common.pagination", { total }),
 			...props.pagination
 		};
-	};
+	}, [props.pagination, t]);
 	/**
 	* @description 计算分页器的高度
 	* 如果分页器被禁用，则返回 0，否则根据分页器的大小返回相应的高度

package/shell-dist/index.html

@@ -5,9 +5,9 @@
 		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
 		<link rel="icon" href="/favicon.ico" />
 		<title>React Antd Admin · Shell</title>
-		<meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'self' https://modules.cdn.example.com 'wasm-unsafe-eval' 'nonce-oCauQheXzDS2E/yd7smCtg=='; script-src-attr 'none'; connect-src 'self' data: https://modules.cdn.example.com; style-src 'self' https://modules.cdn.example.com 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' data:; frame-src https://ant.design https://react.dev https://condorheroblog.github.io; form-action 'none'; base-uri 'none'; object-src 'none'; upgrade-insecure-requests" />
+		<meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'self' https://modules.cdn.example.com 'wasm-unsafe-eval' 'nonce-KUwgkL5p/qZWtW8VUNiLzg=='; script-src-attr 'none'; connect-src 'self' data: https://modules.cdn.example.com; style-src 'self' https://modules.cdn.example.com 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' data:; frame-src https://ant.design https://react.dev https://condorheroblog.github.io; form-action 'none'; base-uri 'none'; object-src 'none'; upgrade-insecure-requests" />
 
-		<script type="importmap" nonce="oCauQheXzDS2E/yd7smCtg==">{
+		<script type="importmap" nonce="KUwgkL5p/qZWtW8VUNiLzg==">{
   "imports": {
     "react": "/assets/react.js",
     "react/jsx-runtime": "/assets/jsx-runtime.js",

package/shell-dist/versions.json

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

package/src/__tests__/init-packagejson.test.ts

@@ -0,0 +1,29 @@
+// BDD：脚手架 package.json scripts 与模板的双写守卫（T3，发布工程师评审建议）。
+// 生成器（init.ts generatePackageJson）与模板（templates/package.json）各写一份 scripts，
+// 人肉同步必漂移（实证：typecheck:api 曾漏发生成器）——钉成测试：生成 scripts 的每个键
+// 都必须存在于模板 scripts（值一致），新增 script 先改模板再改生成器。
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { generatePackageJson } from "../init";
+
+const cliRoot = join(dirname(fileURLToPath(import.meta.url)), "../..");
+
+describe("脚手架 package.json scripts 双写守卫（T3）", () => {
+	it("生成 scripts 的每个键都存在于模板且值一致", () => {
+		const template = JSON.parse(readFileSync(join(cliRoot, "templates/package.json"), "utf-8"));
+		const generated = generatePackageJson(cliRoot, "guard-check");
+		for (const [key, value] of Object.entries(generated.scripts)) {
+			expect(template.scripts[key], `生成器有而模板无的 script：${key}（先改 templates/package.json）`)
+				.toBe(value);
+		}
+	});
+
+	it("多方案 scripts 齐备：new / bundle / typecheck:api", () => {
+		const generated = generatePackageJson(cliRoot, "guard-check");
+		expect(generated.scripts.new).toBe("ojm new");
+		expect(generated.scripts.bundle).toBe("ojm build --bundle");
+		expect(generated.scripts["typecheck:api"]).toBe("tsc --noEmit -p src/tsconfig.json");
+	});
+});

package/src/args.ts

@@ -40,13 +40,16 @@ export function parseApiArgs(argv: string[]): { dir: string, check: boolean, doc
 
 /**
  * `ojm build [--bundle] [--out <dir>]`。
- * `--bundle`：方案包构建（manifest.yaml 契约校验 → 确定性 tgz + sha256），
- * 与站点级 `ojm build`（后端 oj build + 模块产物合并）互斥分工（devkit 手册「打包与分发」）。
+ * `--bundle`：方案包构建（契约校验 → 确定性 tgz + sha256）。bundle 级契约位置：优先工程根
+ * `solution.yaml`、或 `src/<模块>/solution.yaml`（模块级方案，契约与所打包模块同位）；旧方案回退
+ * `manifest.yaml`（同两处位置）。与站点级 `ojm build`（后端 oj build + 模块产物合并）互斥分工
+ * （devkit 手册「打包与分发」）。
  * `--out` 的值不得以 `--` 开头（同 parseApiArgs 的消费式扫描，P6 同款坑）。
  */
-export function parseBuildArgs(argv: string[]): { bundle: boolean, out?: string } {
+export function parseBuildArgs(argv: string[]): { bundle: boolean, bundleName?: string, out?: string } {
 	const flags = new Set<string>();
 	let out: string | undefined;
+	let bundleName: string | undefined;
 	for (let i = 0; i < argv.length; i++) {
 		const a = argv[i];
 		if (a === "--out") {
@@ -54,11 +57,58 @@ export function parseBuildArgs(argv: string[]): { bundle: boolean, out?: string
 			i++; // 消费紧随的值，不被当 flag
 			continue;
 		}
+		// --bundle <name> / --bundle=<name>：只打这一份方案（无值 = 全部用户方案）
+		if (a === "--bundle") {
+			flags.add(a);
+			const next = argv[i + 1];
+			if (next !== undefined && !next.startsWith("--")) {
+				bundleName = next;
+				i++;
+			}
+			continue;
+		}
+		if (a.startsWith("--bundle=")) {
+			flags.add("--bundle");
+			bundleName = a.slice("--bundle=".length);
+			continue;
+		}
 		if (a.startsWith("--")) {
 			flags.add(a);
 		}
 	}
-	return { bundle: flags.has("--bundle"), out };
+	return { bundle: flags.has("--bundle"), bundleName, out };
+}
+
+/**
+ * `ojm new <name> [--layout container|none] [--api]`：新方案骨架生成参数。
+ * name 为首个非 flag 位置参数（必填，由调用方判空——非交互/CI 友好）。
+ */
+export function parseNewArgs(argv: string[]): { name?: string, layout?: "container" | "none", api?: boolean } {
+	let name: string | undefined;
+	let layout: "container" | "none" | undefined;
+	let api = false;
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i];
+		if (a === "--layout") {
+			const v = argv[i + 1];
+			if (v !== "container" && v !== "none")
+				throw new Error(`[ojm] --layout 只接受 container | none（实际：${v}）`);
+			layout = v;
+			i++;
+			continue;
+		}
+		if (a === "--api") {
+			api = true;
+			continue;
+		}
+		if (a !== undefined && !a.startsWith("--")) {
+			if (name !== undefined)
+				throw new Error(`[ojm] ojm new 只接受一个方案名（多余参数：${a}）`);
+			name = a;
+			continue;
+		}
+	}
+	return { name, layout, api };
 }
 
 /**