@oj-module/cli 0.2.18 → 0.2.23

package/devkit/menu-rules.md

@@ -144,10 +144,10 @@ export default defineModule({
 - 因此你只需在双语 locale 里声明**一条** `<模块名>:menu.main`：
 
 ```jsonc
-// web/src/<模块>/locales/zh-CN.json
+// src/<模块>/web/locales/zh-CN.json
 { "menu": { "main": "Wiki" } }   // 命中 <模块名>:menu.main（根菜单 + 系统设置里的管理子组都读它）
 
-// web/src/<模块>/locales/en-US.json
+// src/<模块>/web/locales/en-US.json
 { "menu": { "main": "Wiki" } }
 ```
 
@@ -190,7 +190,7 @@ handle: { currentActiveMenu: wikiPath("space") }   // → "/wiki/space"，随模
 推荐在模块内放一个 `paths.ts`：
 
 ```ts
-// web/src/<模块>/paths.ts
+// src/<模块>/web/paths.ts
 export const WIKI_ROOT = "wiki";                       // 模块挂载根（唯一定义处）
 export const wikiBase = `/${WIKI_ROOT}`;
 export const wikiPath = (...segments: Array<string | number>): string =>

package/devkit/module-dev-and-cdn-playground.md

@@ -3,6 +3,8 @@
 > 一篇写给「第一次在本工程开发模块」的人的教学文档。读完之后你应该能回答三个问题：
 > **① 开发中的模块要不要「安装」？② 要的话装到哪、会不会重复？③ 怎么在本地把市场链路完整跑一遍？**
 > 适用版本：`@oj-module/cli` 0.2.12+（`ojm market` 子命令），运行期 `oj` ≥ 0.1.73。
+> 本文按**当前模板的 module-root 布局**书写（`src/<模块>/{api,web}` + 工程根 `config.yaml`），
+> 建新工程另需 `oj` ≥ 0.1.85（`--module-root`）。历史布局（`api/src` + `web/src`）对照写在括注里。
 
 ## 1. 先建立心智模型：开发态 ≠ 分发态
 
@@ -10,12 +12,12 @@
 
 | | 开发态 | 分发态 |
 |---|---|---|
-| 模块在哪 | 工程内源码：`web/src/A` + `api/src/A` | 一个 `.tgz` 包（`ojm build --bundle` 产出） |
-| 谁登记它 | `web.config.ts` 的 `modules` 列表 → `ojm build` 生成 `modules.json` | 安装器往目标站点 upsert |
+| 模块在哪 | 工程内源码：`src/A/api` + `src/A/web`（历史布局：`api/src/A` + `web/src/A`） | 一个 `.tgz` 包（`ojm build --bundle` 产出） |
+| 谁登记它 | `ojm build` 扫描 `src/*/web/entry.ts`（`web.config.ts` 可选覆盖）→ 生成 `web/dist/modules.json` | 安装器往目标站点 upsert |
 | 跑起来靠 | `ojm dev` 直跑源码，改一行刷新即见 | 安装器十阶段（下载→验签→解压→迁移→注册→热更→冒烟） |
 | 典型场景 | 你在写它 | 别人（或另一个站点）装它 |
 
-一句话：**开发态没有「安装」这个动作**。`ojm dev` 起的站点直接扫描 `api/src` 产生路由、读 `modules.json` 装配菜单——你写的模块 A 此刻「已经在跑」，只是还没打过包。
+一句话：**开发态没有「安装」这个动作**。`ojm dev` 起的站点直接扫描 `src/` 产生路由（`oj build --module-root src`）、读 `modules.json` 装配菜单——你写的模块 A 此刻「已经在跑」，只是还没打过包。
 
 ## 2. 常见问题：我开发了模块 A，怎么「安装」我自己？
 
@@ -26,7 +28,7 @@
 真正想验证「A 这个包能不能装、安装流程对不对」时，有三个去处，按推荐顺序：
 
 1. **一次性隔离站点**：`ojm market trial --fixture <name>@<version>`（随机端口 + 一次性 DB + 一次性密钥 + 隔离信任库/CDN），跑完即毁，不碰你的工程、DB、信任库。这是唯一「装了也不心疼」的地方，也是最快的「这包能不能装」判据（实测 11 段全 ok 约 12 秒）。
-2. **另一个工程**：`ojm install dist/A-0.1.0.tgz`（file 源，multipart 直传）。
+2. **另一个工程**：`ojm install dist/A-0.1.0.tgz`（file 源，multipart 直传；`dist/` 是 `--bundle` 的默认输出目录，与后端产物 `api/dist` 无关）。
 3. **市场链路**：`ojm market publish` 落 CDN → 市场页点安装（§4 全套）。
 
 ### 2.2 偏要在本工程试怎么办
@@ -56,7 +58,7 @@
 
 注意 §3.1 的 upsert 是**按 name/path** 而不是按来源。于是存在这种状态：
 
-> 你源码里的 A（`api/src/A`，路由由 oj 扫描源码产生）和某次安装产物 `dist/A-0.1.0/` 同时存在。
+> 你源码里的 A（`src/A/api`，路由由 oj 扫描源码产生）和某次安装产物 `api/dist/A-0.1.0/` 同时存在。
 
 表现是：路由与模块条目各自只有一份（不重复），但**哪一份生效取决于挂载命中顺序**——症状为「我改了源码却不生效」或「行为怎么都不对」。这是本主题下最难查的一类问题：没有报错、没有重复，只是「被另一个自己顶替了」。
 
@@ -64,7 +66,7 @@
 
 ## 4. 本地 CDN 演练场：把市场链路完整跑一遍
 
-模板自带一个**本地模拟 CDN**（工程根 `cdn/` + `api/config.yaml` 的 `/cdn` 挂载），配上 `ojm market` 四条命令，就能在本地复刻「发包 → 上架 → 索引 → 安装」全链路。不需要外部服务。
+模板自带一个**本地模拟 CDN**（工程根 `cdn/` + 工程根 `config.yaml` 里的 `/cdn` 挂载），配上 `ojm market` 四条命令，就能在本地复刻「发包 → 上架 → 索引 → 安装」全链路。不需要外部服务。
 
 ### 4.1 全流程（五步）
 
@@ -91,7 +93,7 @@ ojm market verify --rebuild-index
 
 | 命令 | 做什么 | **不**做什么 |
 |---|---|---|
-| `market setup` | 写系统设置 `framework.market_cdn_url` | 不改写 `api/config.yaml`（挂载由模板自带） |
+| `market setup` | 写系统设置 `framework.market_cdn_url` | 不改写工程根 `config.yaml`（`/cdn` 挂载由模板自带） |
 | `market publish` | 落 `<name>-<version>.tgz` + 包级 `.tgz.sig` | **不碰索引**（索引是共享单文件，多人发布会互相覆盖） |
 | `market build-index` | 扫 `cdn/*.tgz` 提取包内 manifest，全量重建两份索引并签名 | 不落包 |
 | `market verify` | 完整性 / 包级签 / 索引签 / manifest 结构四类校验 + 漂移检出 | 不起站点、不装、不访问任何远端 |
@@ -129,19 +131,26 @@ ojm market verify --rebuild-index
 
 ```text
 solution-demo/
-├── manifest.yaml                      # 方案契约清单（Form A）
-├── api/src/<name>/
-│   ├── manifest.yaml                  # oj 原生清单（name/desc/version/tables）
-│   ├── schema.yaml                    # 表结构真源（必须与 manifest.tables 对齐）
-│   ├── routes.js
-│   ├── migrations/0001__init.sql
-│   └── ping/api.ts                    # handler 必须是 .ts
-└── web/src/<name>/locales/{zh-CN,en-US}.json   # 引用 i18n key 时必需
+├── manifest.yaml                       # 方案契约清单（Form A，恒在工程根）
+└── src/<name>/
+    ├── api/
+    │   ├── manifest.yaml               # oj 原生清单（name/desc/version/tables）
+    │   ├── schema.yaml                 # 表结构真源（必须与 manifest.tables 对齐）
+    │   ├── routes.js
+    │   ├── migrations/0001__init.sql
+    │   └── ping/api.ts                 # handler 必须是 .ts
+    └── web/
+        └── locales/{zh-CN,en-US}.json  # 引用 i18n key 时必需
 ```
 
+> 历史布局把这棵树换成 `api/src/<name>/…` + `web/src/<name>/locales/…`，构建命令里的
+> `--module-root src` 换成 `-d api/src`（两者互斥，都是「源码树根」）。布局判定看标记文件
+> 而不是目录名：`src/<name>/api/manifest.yaml` 或 `src/<name>/web/entry.ts` 存在即成模块。
+> 方案工程若由 `ojm init` 起（会带工程根 `config.yaml`），构建时加 `-c config.yaml`。
+
 ```bash
-<host>/bin/oj build -d api/src -o api/dist        # 后端构建（只用宿主已装的 oj）
-node "$CLI_PKG/bin/ojm.mjs" build --bundle        # 打包（构建即校验）
+<host>/bin/oj build --module-root src -o api/dist   # 后端构建（只用宿主已装的 oj）
+node "$CLI_PKG/bin/ojm.mjs" build --bundle          # 打包（构建即校验）
 node "$CLI_PKG/bin/ojm.mjs" keygen --id demo.publisher --out ./keys --yes
 node "$CLI_PKG/bin/ojm.mjs" sign dist/<name>-<version>.tgz --id demo.publisher --key ./keys/private.pem --check
 ```
@@ -154,8 +163,8 @@ node "$CLI_PKG/bin/ojm.mjs" market publish --real ../solution-demo --id demo.pub
 node "$CLI_PKG/bin/ojm.mjs" market verify --rebuild-index
 
 node "$CLI_PKG/bin/ojm.mjs" build                 # 生成 api/dist + web/dist（含 api/dist/versions.json）
-# config：platform.root 改成 dist（安装目标恒为 release 部署）
-(cd api && ../bin/oj serve -c config.yaml -b /api --api-path dist --console-log &)
+# config：platform.root 改成 api/dist（安装目标恒为 release 部署，root 必须与 --api-path 同源）
+(bin/oj serve -c config.yaml -b /api --api-path api/dist --console-log &)
 node "$CLI_PKG/bin/ojm.mjs" market setup --url http://127.0.0.1:9778 --user admin --pass 123456 --new-pass <新口令>
 # 市场页点安装 → 首次停在「待信任」→ 核对指纹 → ojm trust confirm --task <id> → 重试 → done
 ```
@@ -166,11 +175,11 @@ node "$CLI_PKG/bin/ojm.mjs" market setup --url http://127.0.0.1:9778 --user admi
 |---|---|---|
 | ① | `oj build` 报 `tables 声明 "x" 不在 schema.yaml` | oj 用 `schema.yaml` 做表结构真源，`manifest.tables` 只是引用面；补 `schema.yaml`（`tables: {<t>: {pk, columns}}`），与迁移语句对齐 |
 | ② | `oj build` 成功但 `routes.js` 是空表、dist 里没有 handler | **只编译 `.ts` handler**；写成 `ping/api.js` 会被静默丢弃 → 改 `api.ts` |
-| ③ | `build --bundle` 报 `缺少 web/src/<name>/locales/…` | manifest 一旦引用 `title_key`/`label_key` 就必须双语 locale（后端方案也要）；且 key 必须**嵌套** `{"menu":{"main":"…"}}`，平铺 `"menu.main"` 查不到 |
+| ③ | `build --bundle` 报 `缺少 src/<name>/web/locales/…`（历史布局是 `web/src/<name>/locales/…`） | manifest 一旦引用 `title_key`/`label_key` 就必须双语 locale（后端方案也要）；且 key 必须**嵌套** `{"menu":{"main":"…"}}`，平铺 `"menu.main"` 查不到 |
 | ④ | 安装 POST 返回 200，但 `market/task` 恒 404 | 宿主 config 缺 `fs:` 段 → 安装器落盘被 jail 拒、失败发生在任务文件写入前；0.2.13 起模板自带，旧工程手补 |
 | ⑤ | 安装卡 `preflight`：`无法读取宿主 runtime 版本` | 安装器读 `api/dist/versions.json`；0.2.13 起 `ojm build` 双落点（旧版手抄 `web/dist/versions.json`） |
 | ⑥ | 安装卡 `reloading`：`NotCapable: module '_platform' is not platform-privileged` | 宿主 config 的 `platform.modules` 未列 `_platform`（0.2.13 起模板自带） |
-| ⑦ | 安装卡 `reloading`：`reloadConfig 返回 unchanged` / 卡 `smoke`：探活 404 | 起站形态不对：`ojm preview` 服务派生 config（安装器热更写的是 `api/config.yaml`，被监视文件没变）；dev（`--api-path src`）装到 dist 的模块不被发现。**安装必须对真实 config 以 `--api-path dist` 起站** |
+| ⑦ | 安装卡 `reloading`：`reloadConfig 返回 unchanged` / 卡 `smoke`：探活 404 | 起站形态不对：`ojm preview` 服务派生 config（安装器热更写的是真实 config，派生文件没变）；dev 用 `--module-root src`（历史布局 `--api-path src`）读源码，装到 `api/dist` 的模块不被发现。**安装必须对真实 config 以 `--api-path api/dist`（历史布局 `--api-path dist`）起站** |
 
 ### 6.4 装成之后怎么确认
 
@@ -186,7 +195,7 @@ ls api/dist/<name>-<version>/                        # 安装产物目录
 写模块      → 源码直跑（ojm dev），不要装
 验证能装    → ojm market trial（隔离站点，12s），或 ojm install <tgz> 到另一个工程
 重复？      → 不会。注册面全 upsert；同名再装被前置校验直接拒
-市场链路    → setup → publish → build-index → verify → 市场页安装（release 形态：--api-path dist）
+市场链路    → setup → publish → build-index → verify → 市场页安装（release 形态：--api-path api/dist）
 绝对 URL    → 市场地址端口取自 config（9778），不是 dev server 的 5174
 信任        → 包级签=锚，索引签=完整性，TOFU 管陌生发布方，verify 不背书内容安全
 ```

package/devkit/sql-builder-missing-capabilities-pr.md

@@ -3,14 +3,15 @@
 > **闭环状态（2026-10-20）：7 项诉求全部闭环**——6 项随 oj 0.1.81/0.1.82 发布落地，第 4 项
 > （orIgnore + fromSelect）能力本身已发布但**组合在 sqlite 上被上游明文拒绝**，模板按上游
 > 文档指引保留一处 sanctioned 裸 SQL 绕行（`notify.ts:216`，api-manual §"orIgnore + fromSelect
-> 组合在 sqlite 不支持"原文即指向该绕行）。逐项映射见 §6；模板 `api/src` 内 `保留 db.query`
-> 注释已归零（仅剩上述 1 处 `保留 db.exec`）。
+> 组合在 sqlite 不支持"原文即指向该绕行）。逐项映射见 §6；模板 `src/*/api`（布局 v2 前为
+> `api/src`）内 `保留 db.query` 注释已归零（仅剩 `notify.ts` 里 `markAllRead` / `clearNotices`
+> 两处 `保留 db.exec`）。
 >
 > 目的：把模板 `db.query` 全面迁移到 `db.table(...)` 构造器以获得多库（sqlite / mysql / postgres）可移植性时，
 > 识别出构造器**当时无法表达**、只能回退 `db.query` 的 7 类能力。本文档作为向上游 `oj` 运行时 SQL 构造器提 PR 的依据。
 >
 > 证据来源：`~/.local/share/oj/devkit/api-manual.md`（查询构造器章节，含 `like` 操作清单 §1142、子查询限制 §1343、
-> `union` §1346、CTE §1378 等）；框架 `README.md` v0.1.66（ESCAPE 纪律）；模板代码 `packages/cli/templates/api/src/**`。
+> `union` §1346、CTE §1378 等）；框架 `README.md` v0.1.66（ESCAPE 纪律）；模板代码 `packages/cli/templates/src/*/api/**`。
 
 ---
 
@@ -243,12 +244,15 @@ db.table("sys_refresh_token").select("*").where({ field: "token_hash", op: "eq",
 6. `demo/todos/api.ts:12` / `uninstall.ts:166` → 动态 WHERE 安全出口。
 7. `session.ts:114-115` → `select("*")`。
 
-全部关闭后，模板 `api/src` 内 `保留 db.query` / `保留 d.exec` 注释应归零，达成"零原生 SQL 可移植"目标。
+全部关闭后，模板 `src/*/api` 内 `保留 db.query` / `保留 db.exec` 注释应归零，达成"零原生 SQL 可移植"目标。
 
 ---
 
 ## 6. 闭环状态（2026-10-20 实测）
 
+> 表中 `notify.ts:NN` 等行号是 **2026-10-20 的快照**，代码此后有增删（文件也已迁到
+> `src/notification/api/_shared/notify.ts`）——按函数名定位，别按行号跳。
+
 | # | 诉求 | 上游落地（版本） | 模板现状 |
 |---|------|------------------|----------|
 | 1 | `like` 的 `ESCAPE` 转义子句 | `contains` / `startswith` / `endswith` 语义化模糊匹配（**v0.1.81**），引擎自动转义 `%`/`_`/`!` | 已闭环：`contacts.ts` 等模糊搜索全部走 `contains`。**订正**：原判「`like` 无 escape 出口」系误报——escape 逃生舱本就存在（白名单 `! / | ~ # @`）；真正缺的是业务零转义语义 op，上游按此落地（L1 实测 `%` 元字符不泛化） |
@@ -259,9 +263,10 @@ db.table("sys_refresh_token").select("*").where({ field: "token_hash", op: "eq",
 | 6 | 动态 WHERE 组合 | `whereIf(test, cond)`（**v0.1.81**）：`undefined/null/false/[]` 整条跳过（注意 `""`/`0` 是合法值会保留——可选过滤的缺失值必须归一化为 `undefined`，模板 oplog 曾踩此坑并修复） | 已闭环：`demo/todos`、`uninstall.ts` 等全部改 `whereIf`；未采纳裸片段出口（whereIf 已覆盖诉求场景） |
 | 7 | `select *` | `select(["*"])`（**v0.1.81**，必须是唯一元素） | 已闭环：`session.ts` refresh 查询改 `select(["*"])` |
 
-**结论**：模板 `api/src` 内 `保留 db.query` 注释归零；`保留 d.exec` 仅剩 `notify.ts:216` 一处，
+**结论**：模板 `src/*/api` 内 `保留 db.query` 注释归零；`保留 db.exec` 仅剩 `notify.ts` 的
+`markAllRead` / `clearNotices` 两处（`src/notification/api/_shared/notify.ts`），
 且属上游文档明文记载的 sqlite 组合限制绕行（非能力缺口）。"零原生 SQL 可移植"目标以
-「一处上游 sanctioned 绕行」的形态达成。
+「上游 sanctioned 绕行」的形态达成。
 
 > 上游侧复核记录（oj 0.1.81 release notes，devkit `oj-api-dev/README.md`）：7 条诉求落地时
 > 判定「1 条误报、1 条部分误报」——误报即 §3.1 的 escape 出口（本就存在），部分误报即 §3.3

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@oj-module/cli",
   "type": "module",
-  "version": "0.2.18",
+  "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.18",
+    "@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.18",
+			"version": "0.2.23",
 			"license": "MIT"
 		},
-		"lastBuildTime": "2026-10-21 22:40:24"
+		"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-NpuwH1G8uW9SNQdyFsPFYQ=='; 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="NpuwH1G8uW9SNQdyFsPFYQ==">{
+		<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.18",
-  "@oj-module/runtime/contract": "0.2.18",
-  "@oj-module/runtime/contract/errors": "0.2.18",
+  "@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__/build-backend.test.ts

@@ -62,3 +62,57 @@ describe("given 纯前端工程（无 api/src）When ojm build 后端", () => {
 		expect(existsSync(join(root, "api", "dist"))).toBe(false);
 	});
 });
+
+/**
+ * 假 oj：把 argv 落盘供断言；`build --help` 的输出可切（模拟是否支持 --module-root）。
+ * 能力探针会先跑 `build --help`，所以脚本必须区分这两次调用。
+ */
+function fakeOjRecording(projectRoot: string, supportsModuleRoot: boolean): void {
+	mkdirSync(join(projectRoot, "bin"), { recursive: true });
+	const bin = join(projectRoot, "bin", "oj");
+	writeFileSync(bin, [
+		"#!/bin/sh",
+		"if [ \"$1\" = \"build\" ] && [ \"$2\" = \"--help\" ]; then",
+		`  ${supportsModuleRoot ? "echo '      --module-root <GLOB>  模块根 glob'" : "echo '  -d, --dir <DIR>'"}`,
+		"  exit 0",
+		"fi",
+		"if [ \"$1\" = \"-V\" ]; then echo 'oj 0.1.84'; exit 0; fi",
+		"printf '%s\\n' \"$*\" > \"$(dirname \"$0\")/invoked\"",
+		"exit 0",
+		"",
+	].join("\n"), { mode: 0o755 });
+}
+
+/** 新布局工程：src/<name>/{api,web} + 仓库根 config.yaml */
+function newModuleRootProject(): string {
+	const root = mkdtempSync(join(tmpdir(), "ojm-build-backend-mr-"));
+	mkdirSync(join(root, "src", "wiki", "api"), { recursive: true });
+	writeFileSync(join(root, "src", "wiki", "api", "manifest.yaml"), "name: wiki\nversion: 0.1.0\n", "utf-8");
+	writeFileSync(join(root, "config.yaml"), "server:\n  port: 9778\n", "utf-8");
+	return root;
+}
+
+describe("given module-root 布局 When ojm build 后端", () => {
+	it("then 一次调用、单一输出根：--module-root src + -o api/dist（与 -d 互斥）", async () => {
+		const root = newModuleRootProject();
+		fakeOjRecording(root, true);
+
+		expect(await buildBackend(root)).toBe(true);
+
+		// 逐模块 `-o <tmp>` 会让每个 tmp 各写一份 manifests.yaml，锁与兄弟目录关系全丢
+		const invoked = readFileSync(join(root, "bin", "invoked"), "utf-8").trim();
+		expect(invoked).toBe(
+			`build -c ${join(root, "config.yaml")} --module-root ${join(root, "src")} -o ${join(root, "api", "dist")} --no-minify`,
+		);
+		expect(existsSync(join(root, "api", "dist", "versions.json"))).toBe(true);
+	});
+
+	it("then oj 缺 --module-root 能力时 fail-fast，不落任何产物", async () => {
+		const root = newModuleRootProject();
+		fakeOjRecording(root, false);
+
+		await expect(buildBackend(root)).rejects.toThrow(/不支持 --module-root/);
+		expect(existsSync(join(root, "bin", "invoked"))).toBe(false); // 没跑 oj build
+		expect(existsSync(join(root, "api", "dist"))).toBe(false);
+	});
+});