@oj-module/cli 0.2.17 → 0.2.20

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" } }
 ```
 
@@ -156,7 +156,6 @@ export default defineModule({
 - 必须**嵌套**在 `menu.main`，不能平铺成 `"<模块名>:menu.main": "..."`（i18next 点路径取值）。
 - 缺这条 key → 构建期契约校验直接 fail（构建期 fail-fast）。
 - 普通子项（space / status / collections 等）的 `title` 仍各自匹配 `<模块名>:menu.*`（如 `wiki:menu.space`）。
-- 旧设计的 `menu.group` key 已废弃：`menu.main` 取代它成为根标题与管理子组标题的统一真源。
 
 ---
 
@@ -191,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.17",
+  "version": "0.2.20",
   "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.17",
+    "@oj-module/runtime": "0.2.20",
     "@redocly/cli": "^2.51.0",
     "@tailwindcss/vite": "^4.3.0",
     "esbuild": "^0.28.2",

package/shell-dist/assets/runtime.js

@@ -303,10 +303,10 @@ function getAppInfo() {
 	return {
 		"pkg": {
 			"name": "@oj-module/runtime",
-			"version": "0.2.17",
+			"version": "0.2.20",
 			"license": "MIT"
 		},
-		"lastBuildTime": "2026-10-21 21:54:09"
+		"lastBuildTime": "2026-10-22 12:17:23"
 	};
 }
 var init_get_app_info = __esmMin((() => {}));

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-NKdPzzWoLWlLgH/F6SaXrg=='; 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-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" />
 
-		<script type="importmap" nonce="NKdPzzWoLWlLgH/F6SaXrg==">{
+		<script type="importmap" nonce="oCauQheXzDS2E/yd7smCtg==">{
   "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.17",
-  "@oj-module/runtime/contract": "0.2.17",
-  "@oj-module/runtime/contract/errors": "0.2.17",
+  "@oj-module/runtime": "0.2.20",
+  "@oj-module/runtime/contract": "0.2.20",
+  "@oj-module/runtime/contract/errors": "0.2.20",
   "@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);
+	});
+});

package/src/__tests__/layout.test.ts

@@ -0,0 +1,176 @@
+// layout spec：三种布局的探测、互斥、模块枚举与 config 落点。
+//
+// 这些取值是 dev/build/preview/bundle 的共同底座：探测错一次，`ojm build` 会构建 A
+// 而 `ojm dev` 预览 B，或产物写进空目录后表现为「health 200、模块 0 个」的假绿。
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+
+import {
+	apiSrcOf,
+	moduleDir,
+	resolveCertDir,
+	resolveConfigPath,
+	resolveLayout,
+	scanModules,
+	webSrcOf,
+} from "../layout";
+
+function newRoot(): string {
+	return mkdtempSync(join(tmpdir(), "ojm-layout-"));
+}
+
+function writeFile(root: string, rel: string, content = ""): void {
+	const abs = join(root, rel);
+	mkdirSync(join(abs, ".."), { recursive: true });
+	writeFileSync(abs, content, "utf-8");
+}
+
+/** 新布局的最小工程：src/wiki/{api/manifest.yaml, web/entry.ts} + 根 config.yaml */
+function newModuleRootProject(): string {
+	const root = newRoot();
+	writeFile(root, "src/wiki/api/manifest.yaml", "name: wiki\nversion: 0.1.0\n");
+	writeFile(root, "src/wiki/web/entry.ts", "export default {};\n");
+	writeFile(root, "config.yaml", "server:\n  port: 9778\n");
+	return root;
+}
+
+describe("resolveLayout / module-root", () => {
+	it("src/<name>/{api,web} 命中 module-root，产物根语义不变", () => {
+		const root = newModuleRootProject();
+		const layout = resolveLayout(root);
+
+		expect(layout.kind).toBe("module-root");
+		expect(layout.modulesSrc).toBe(join(root, "src"));
+		expect(layout.distDir).toBe(join(root, "web", "dist"));
+		expect(layout.apiDist).toBe(join(root, "api", "dist"));
+		expect(layout.watchTarget).toBe(join(root, "src"));
+		// --module-root 取「源码树根目录」（oj 在其子树内递归找 manifest.yaml）
+		expect(layout.moduleRoot).toBe(join(root, "src"));
+	});
+
+	it("web/dist 存在不会被误判成 flat 布局", () => {
+		const root = newModuleRootProject();
+		mkdirSync(join(root, "web", "dist", "modules", "wiki", "0.1.0"), { recursive: true });
+		expect(resolveLayout(root).kind).toBe("module-root");
+	});
+
+	it("枚举真源是标记文件：一侧可缺省，纯后端 / 纯前端各算一个模块", () => {
+		const root = newRoot();
+		writeFile(root, "src/_platform/api/manifest.yaml", "name: _platform\nversion: 0.1.0\n");
+		writeFile(root, "src/auth/api/manifest.yaml", "name: auth\nversion: 0.1.0\n");
+		writeFile(root, "src/about/web/entry.ts", "export default {};\n");
+
+		// 按名字排序（不依赖 readdir 顺序，产物才可复现）
+		const modules = scanModules(resolveLayout(root));
+		expect(modules.map(m => m.name)).toEqual(["_platform", "about", "auth"]);
+		expect(modules.map(m => !!m.apiSrc)).toEqual([true, false, true]);
+		expect(modules.map(m => !!m.webSrc)).toEqual([false, true, false]);
+		expect(modules[0].apiSrc).toBe(join(root, "src", "_platform", "api"));
+		expect(modules[1].webSrc).toBe(join(root, "src", "about", "web"));
+	});
+
+	it("非模块目录（既无 api/ 也无 web/，如共享库）静默跳过", () => {
+		const root = newRoot();
+		writeFile(root, "src/wiki/api/manifest.yaml", "name: wiki\nversion: 0.1.0\n");
+		writeFile(root, "src/shared/util.ts", "export const x = 1;\n");
+		expect(scanModules(resolveLayout(root)).map(m => m.name)).toEqual(["wiki"]);
+	});
+
+	it("有 api/ 却缺 manifest.yaml：报错并指名目录（不静默当成非模块）", () => {
+		const root = newRoot();
+		writeFile(root, "src/wiki/api/manifest.yaml", "name: wiki\nversion: 0.1.0\n");
+		writeFile(root, "src/broken/api/index.js", "export {};\n");
+		expect(() => resolveLayout(root)).toThrow(/src\/broken\//);
+	});
+
+	it("src/ 下没有任何模块标记时不算 module-root（避免把脚本 src/ 当模块树）", () => {
+		const root = newRoot();
+		mkdirSync(join(root, "src", "scripts"), { recursive: true });
+		expect(() => resolveLayout(root)).toThrow(/未发现模块源码/);
+	});
+});
+
+describe("resolveLayout / 历史布局", () => {
+	it("web/src 仍识别为 new，模块根不在 src/ 之下", () => {
+		const root = newRoot();
+		writeFile(root, "web/src/wiki/entry.ts", "export default {};\n");
+		writeFile(root, "api/src/wiki/manifest.yaml", "name: wiki\nversion: 0.1.0\n");
+
+		const layout = resolveLayout(root);
+		expect(layout.kind).toBe("new");
+		expect(layout.modulesSrc).toBe(join(root, "web", "src"));
+		expect(layout.moduleRoot).toBeUndefined();
+		expect(apiSrcOf(layout, "wiki")).toBe(join(root, "api", "src", "wiki"));
+		expect(webSrcOf(layout, "wiki")).toBe(join(root, "web", "src", "wiki"));
+	});
+
+	it("web/<name>/entry.ts 识别为 flat，产物落 build/", () => {
+		const root = newRoot();
+		writeFile(root, "web/home/entry.ts", "export default {};\n");
+		writeFile(root, "web/home/__client/api.ts", "export {};\n");
+
+		const layout = resolveLayout(root);
+		expect(layout.kind).toBe("flat");
+		expect(layout.modulesSrc).toBe(join(root, "web"));
+		expect(layout.distDir).toBe(join(root, "build"));
+		expect(webSrcOf(layout, "home")).toBe(join(root, "web", "home"));
+	});
+
+	it("历史布局不支持 scanModules（顺序由 web.config.ts 决定）", () => {
+		const root = newRoot();
+		writeFile(root, "web/src/wiki/entry.ts", "export default {};\n");
+		expect(() => scanModules(resolveLayout(root))).toThrow(/只适用于 module-root/);
+	});
+});
+
+describe("resolveLayout / 互斥与缺省", () => {
+	it("两套源码树同时存在时报错，而不是静默选一个", () => {
+		const root = newModuleRootProject();
+		writeFile(root, "web/src/legacy/entry.ts", "export default {};\n");
+		expect(() => resolveLayout(root)).toThrow(/同时存在两套模块源码树/);
+	});
+
+	it("什么布局都没有时报错并列出两种合法形状", () => {
+		const root = newRoot();
+		expect(() => resolveLayout(root)).toThrow(/未发现模块源码/);
+	});
+});
+
+describe("config 落点", () => {
+	it("module-root：config 与证书目录都在仓库根", () => {
+		const root = newModuleRootProject();
+		expect(resolveConfigPath(root)).toBe(join(root, "config.yaml"));
+		expect(resolveCertDir(root)).toBe(join(root, "config"));
+	});
+
+	it("module-root 仍把 config 留在 api/ 时报错（回退会让路由静默消失）", () => {
+		const root = newRoot();
+		writeFile(root, "src/wiki/api/manifest.yaml", "name: wiki\nversion: 0.1.0\n");
+		writeFile(root, "api/config.yaml", "server:\n  port: 9778\n");
+		expect(() => resolveConfigPath(root)).toThrow(/仍在 api\/ 下/);
+	});
+
+	it("历史布局：config 与证书目录仍在 api/ 下", () => {
+		const root = newRoot();
+		writeFile(root, "web/src/wiki/entry.ts", "export default {};\n");
+		writeFile(root, "api/config.yaml", "server:\n  port: 9778\n");
+		expect(resolveConfigPath(root)).toBe(join(root, "api", "config.yaml"));
+		expect(resolveCertDir(root)).toBe(join(root, "api", "config"));
+	});
+
+	it("空目录（init 目标）不报错：落默认位置供脚手架写入", () => {
+		const root = newRoot();
+		expect(resolveConfigPath(root)).toBe(join(root, "api", "config.yaml"));
+	});
+});
+
+describe("路径取值函数", () => {
+	it("module-root：moduleDir / apiSrcOf / webSrcOf 都在 src/<name>/ 之下", () => {
+		const layout = resolveLayout(newModuleRootProject());
+		expect(moduleDir(layout, "wiki")).toBe(join(layout.modulesSrc, "wiki"));
+		expect(apiSrcOf(layout, "wiki")).toBe(join(layout.modulesSrc, "wiki", "api"));
+		expect(webSrcOf(layout, "wiki")).toBe(join(layout.modulesSrc, "wiki", "web"));
+	});
+});

package/src/__tests__/module-list.test.ts

@@ -0,0 +1,66 @@
+// 前端模块清单 spec（设计 D3：扫描为准 + web.config.ts 可选覆盖）。
+//
+// 关键不变量是**并集而不是替换**：新增一个模块目录后忘了登记，也必须被构建；
+// 反过来登记了一个已经不存在的目录，必须报错而不是静默少一个模块。
+import { describe, expect, it } from "vitest";
+
+import { mergeModuleList } from "../config";
+
+const ROOT = "/proj";
+
+function scanned(...names: string[]) {
+	return names.map(name => ({ name, webSrc: `${ROOT}/src/${name}/web` }));
+}
+
+describe("mergeModuleList", () => {
+	it("无覆盖时按扫描顺序（layout 已按名字排序）", () => {
+		expect(mergeModuleList(scanned("about", "home", "wiki"), undefined, ROOT)).toEqual([
+			{ name: "about", entry: "src/about/web/entry.ts", enabled: true },
+			{ name: "home", entry: "src/home/web/entry.ts", enabled: true },
+			{ name: "wiki", entry: "src/wiki/web/entry.ts", enabled: true },
+		]);
+	});
+
+	it("覆盖项按声明顺序排前，未登记的按扫描顺序追加（并集）", () => {
+		const list = mergeModuleList(scanned("about", "home", "wiki"), [
+			{ name: "home", entry: "ignored" },
+			{ name: "wiki", entry: "ignored" },
+		], ROOT);
+		expect(list.map(m => m.name)).toEqual(["home", "wiki", "about"]);
+	});
+
+	it("enabled:false 仍生效（覆盖项与未登记项都按自己的声明走）", () => {
+		const list = mergeModuleList(scanned("about", "home"), [
+			{ name: "home", entry: "x", enabled: false },
+		], ROOT);
+		expect(list).toEqual([
+			{ name: "home", entry: "src/home/web/entry.ts", enabled: false },
+			{ name: "about", entry: "src/about/web/entry.ts", enabled: true },
+		]);
+	});
+
+	it("登记了不存在的模块 → 报错并提示以目录为准", () => {
+		expect(() => mergeModuleList(scanned("home"), [
+			{ name: "gone", entry: "src/gone/web/entry.ts" },
+		], ROOT)).toThrow(/src\/gone\/web\/entry\.ts 不存在/);
+	});
+
+	it("纯后端模块（无 web/entry.ts）不进前端清单", () => {
+		const list = mergeModuleList([
+			{ name: "auth" }, // 纯后端：只有 api/manifest.yaml，扫描结果没有 webSrc
+			{ name: "home", webSrc: `${ROOT}/src/home/web` },
+		], undefined, ROOT);
+		expect(list.map(m => m.name)).toEqual(["home"]);
+	});
+
+	it("登记一个纯后端模块也算错（该目录没有前端入口）", () => {
+		expect(() => mergeModuleList([
+			{ name: "auth" },
+		], [{ name: "auth", entry: "x" }], ROOT)).toThrow(/不存在/);
+	});
+
+	it("entry 用相对工程根的路径（与 web.config.ts 历史口径一致）", () => {
+		const [only] = mergeModuleList(scanned("wiki"), [{ name: "wiki", entry: "/abs/should-be-ignored" }], ROOT);
+		expect(only.entry).toBe("src/wiki/web/entry.ts");
+	});
+});