@oj-module/cli 0.2.53 → 0.2.54

package/devkit/SKILL.md

@@ -54,7 +54,7 @@ description: 用 ojm 开发前后端一体工程时使用——新增/修改前
 - **注册时机**：一切 `ctx.register.*` 必须在 `lifecycle.onInit` 内、且在 onInit 返回前完成。
   拖到 `onActivate` 或某个异步回调里注册不保证生效。`onInit` 签名是 **async**（返回
   `Promise<void>`）——漏写 `async` 会被 `tsc` 以 TS2322 拦下，范本见模板
-  `src/notification/web/entry.ts`。
+  `src/app/web/notification/entry.ts`。
 - **一模块一 client**：`create<Module>Client(ctx)` 只在 onInit 里创建一次。
   页面/组件/事件回调里**不要**再创建——会覆盖 request 单槽。页面里直接 import 裸函数调用。
 - **只创建自己模块的 client**：A 模块的 onInit 里创建 B 模块的 client 会 DEV 告警。要别家接口，
@@ -187,7 +187,7 @@ description: 用 ojm 开发前后端一体工程时使用——新增/修改前
 | 登录 401 且 msg 不是 `invalid credentials` | `/auth/*` 不在 `anonymous_paths` | 加进工程根 `config.yaml`，重启 |
 | WS 连接 401（「文件在却连不上」） | 模块写了 `ws.ts`，但其 `/ws` 路由不在 `anonymous_paths`（oj v0.1.30+ WS 握手也过鉴权） | 匿名 WS 加进 `anonymous_paths`；受保护 WS 带 Bearer/Cookie 是正当用法。`ojm api --check` 会对此 warn |
 | 登出/回登录页落空，或登录后落错误边界 | 工程缺 `login` / `home` 模块 | 在 `web.config.ts` 保留两者 |
-| 通知铃 404 `no route matched`（`/api/notifications`） | 前端 `notification` 模块没加载 / 没注册 `notificationsApi`，回落到内置只读兜底；脚手架不再提供 root 级 `/api/notifications` | 保留 `src/notification/web/entry.ts` 的登记 + onInit 注册四方法；后端由 `src/notification/api` 出 `/api/notification/*` |
+| 通知铃 404 `no route matched`（`/api/notifications`） | 前端 `notification` 模块没加载 / 没注册 `notificationsApi`，回落到内置只读兜底；脚手架不再提供 root 级 `/api/notifications` | 保留 `src/app/web/notification/entry.ts` 的登记 + onInit 注册四方法；后端由 `src/notification/api` 出 `/api/notification/*` |
 | `oj serve` 启动即退，报 `config uses removed server.* site keys (v0.1.58): api_prefix` | 用了 oj v0.1.58 起删除的旧站点键（`api_prefix`/`app_path`/`app_prefix`/`static_sites`/`app_spa_fallback`） | 改 `server.api_prefix: /api` 为顶层 `mounts:`（module-root 写 `{prefix: "/api", api: "api/dist"}`；历史布局写 `api: "src"`、源码交给 `-d`）；迁移完整 YAML 由报错给出 |
 | 改完 `mounts:` 仍全 404 | `api:` 指向目录不对（相对 config 所在目录） | module-root 指向产物目录 `"api/dist"`、历史布局指向源码树 `"src"`；`-c` 指向工程根 `config.yaml`（ojm dev/preview 已内置）。module-root 模板**故意不写 api 挂载**（源码交给 `--module-root src`、产物交给 `--api-path api/dist`，同时出现会报 module declared in multiple places） |
 | `oj serve` 启动即退，报 `module '_shared' missing manifest.yaml` | 把共享后端代码放到了扫描根顶层（`src/_shared/`）——oj 把扫描根下的顶层目录都当模块；历史布局是 `api/src/_shared/` | 嵌进所属模块：`src/<模块>/api/_shared/`（历史布局 `api/src/<模块>/_shared/`），用 `#<本模块>/...` 别名 |

package/devkit/manual.md

@@ -45,13 +45,21 @@
 │   ├── _platform/         # 框架级：users 表 / rbac / 市场编排 / 生命周期
 │   │   ├── api/           #   + _shared/（respond、service/、site-facade）
 │   │   └── web/           #   仅 __client 生成物（无页面）
+│   ├── app/web/           # 框架内置页面**多根模块**（一个 entry 多个根）：
+│   │   ├── entry.ts       #   routes 聚合 + i18nNamespaces + 生命周期
+│   │   ├── home/          #   /home               （routes.ts + pages + locales + __client）
+│   │   ├── login/         #   /login、/change-password
+│   │   ├── personal-center/  # /personal-center/my-profile
+│   │   ├── notification/  #   /notification-center
+│   │   └── system/        #   /system/*（根上 handle.roles = 系统管理员）
+│   ├── oj-market/web/     # 解决方案市场（独立模块，删目录即下线）
 │   ├── auth/api/          # login / refresh / logout / ldap-login
-│   ├── system/{api,web}/  # 用户 / 角色 / 权限 / 设置 / oplog / login-methods
-│   ├── notification/{api,web}/      # 通知互动（表 + push + del）
-│   ├── personal-center/{api,web}/   # 头像上传
+│   ├── system/api/        # 用户 / 角色 / 权限 / 设置 / oplog / login-methods（后端）
+│   ├── notification/api/  # 通知互动（表 + push + del）
+│   ├── personal-center/api/   # 头像上传
 │   └── web/{api,web}/     # root 级 /api/web（hello / user-info / get-async-routes 在 api 侧）
-├── api/dist/              # 后端产物（release 根：<name>-<ver>/ + manifests.yaml + versions.json）—构建后才有
-├── web/dist/              # 站点产物（shell + modules/ + modules.json）—构建后才有
+├── dist/api/              # 后端产物（release 根：<name>-<ver>/ + manifests.yaml + versions.json）—构建后才有
+├── dist/web/              # 站点产物（shell + modules/ + modules.json）—构建后才有
 ├── bin/                   # oj 二进制 + plugins/ + devkit/（不入库）
 └── .claude/skills/        # ojm-module-dev（本 devkit）+ oj-api-dev（随 oj 二进制）
 ```
@@ -62,13 +70,12 @@
   所在目录**，所有 `fs.*` 相对路径、`db.default`、`platform.root`、`mounts[].web`
   都相对它解析；证书与密钥落在同级的 `config/`（`ojm` 侧由 `resolveConfigPath()` /
   `resolveCertDir()` 单点派生，你不需要自己拼路径）。
-- **产物有两个根**：后端 `api/dist`（oj 扁平 release，`<name>-<ver>/` 与
-  `manifests.yaml` 同层），站点 `web/dist`（`modules/` + `modules.json`）。
-  `config.yaml` 上移到工程根后，两者不再同名 `dist`。
+- **产物有两个根**：后端 `dist/api`（oj 扁平 release，`<name>-<ver>/` 与
+  `manifests.yaml` 同层），站点 `dist/web`（`modules/` + `modules.json`）。
 - **`src/` 下每个目录都得是一个模块**：脚本 / 共享库请放在 `src/` 之外，否则
   `ojm dev/build` 会以「既无 `api/manifest.yaml` 也无 `web/entry.ts`」直接报错。
 
-> 模板里还有一批 demo-only 模块（`src/{demo,home}/api`、`src/{about,access,exception,
+> 模板里还有一批 demo-only 模块（`src/home/api`、`src/{about,access,exception,
 > outside,route-nest}/web`）仅供模板自演示，**不进脚手架**；其 `web.config.ts` 条目带
 > `// #region demo-only` 标记，init 拷贝时整段剥离。新布局的清单是「扫描 + 覆盖」并集，
 > 注释掉不会让模块消失——要「不构建」必须写 `enabled: false`。
@@ -289,14 +296,14 @@ export default {
 	baseUrl: "", // 模块产物 URL 前缀（可填 CDN 绝对域）；与站点部署位置无关
 	// siteBase: "/oj", // 站点挂在 https://host/oj/ 下时才需要（默认根路径），见 §13 的路径空间一节
 	modules: [
-		// home 必须保留且尽量靠前：shell 预构建把 "/" → VITE_BASE_HOME_PATH（=/home）
-		// 重定向，缺 /home 路由会让登录回跳 / 点 logo 落错误边界。
-		{ name: "home", entry: "src/home/web/entry.ts", enabled: true },
-		// login 必须保留：shell 宿主只消费模块路由、不挂 runtime 内置 baseRoutes，
-		// 缺它 `/login` 无路由可跳（登出会落空）。
-		{ name: "login", entry: "src/login/web/entry.ts", enabled: true },
+		// 框架内置页面聚合为一个**多根模块**（/home /login /personal-center
+		// /notification /system）：一个 entry 多个根，各根按 handle.order 排菜单。
+		// 缺 /home 会让登录回跳 / 点 logo 落错误边界；缺 /login 则登出无路由可跳。
+		{ name: "app", entry: "src/app/web/entry.ts", enabled: true },
 		{ name: "books", entry: "src/books/web/entry.ts", enabled: true },
 	],
+	// 多根聚合模块的 client 归属（生成物落 src/app/web/<api 前缀>/__client）：
+	// clientOwners: { home: "app", "personal-center": "app", notification: "app", system: "app" },
 };
 ```
 
@@ -351,7 +358,7 @@ export default defineModule({
 `defineModule` 字段：`name`（= 目录名）、`description`、`version`、
 `peerRuntime`、`routes`、`i18n?`、`lifecycle?`。
 
-> 页面组件用**静态 import 或 `lazy()` 都行**：模板自带模块（`src/home/web/entry.ts` 等）
+> 页面组件用**静态 import 或 `lazy()` 都行**：模板自带模块（`src/app/web/home/entry.ts` 等）
 > 用静态 import，多页面模块可对非首屏页面用 `lazy(() => import("./pages/x"))` 做代码分割。
 > 单个页面就用静态 import，少一层间接。
 
@@ -1349,7 +1356,7 @@ useEffect(() => {
    复用展示不同内容（列表页/`index` 路由），离开时必须 `resetTableTitle(tabKey)`，否则再进来看到
    上一个内容的标题。
 
-推荐形态（照 `src/home/web/pages/`、`src/personal-center/web/pages/my-profile/` 抄）：
+推荐形态（照 `src/app/web/home/pages/`、`src/app/web/personal-center/pages/my-profile/` 抄）：
 `BasicContent` 包一层 → 搜索区 + `BasicTable` → 新增/编辑用 antd `Modal` + `Form`
 → 提交后重新拉列表。数据来自 §3.4 的生成函数，**页面里直接 import 裸函数调用**。
 
@@ -1402,7 +1409,7 @@ useEffect(() => {
   `useEffect` 重新注册（上面的形态天然满足）。
 - 同一 key 关闭流程进行中再次触发被忽略（per-key in-flight 去重），双击不会弹两个框。
 
-可运行示例见 playground-oj `web/src/demo/pages/guard.tsx`（本仓 playground 仍是历史布局；
+可运行示例见模板工程 `src/app/web/*/pages/` 下的页面（layouts/权限门同源）；
 模板侧对应 `src/<模块>/web/pages/`，表单 dirty → 关页签弹确认）。
 
 ### 6.5 两份 tsconfig：`typecheck` 与 `typecheck:api`
@@ -1556,7 +1563,7 @@ export default async (path: string, html: string) => {
 | 登录 401 且 msg 不是 `invalid credentials` | `/auth/*` 不在 `anonymous_paths` | 加进工程根 `config.yaml`，重启 |
 | 登出/回登录页空白或 404 | 工程缺 `login` 模块（shell 无内置登录回落） | 在 `web.config.ts` 保留 `login` |
 | 登录后 / 点 logo 落 React Router 错误边界 | 工程缺 `home` 模块 | 在 `web.config.ts` 保留 `home`（尽量靠前） |
-| 通知铃 404 `no route matched`（`/api/notifications`） | 前端 `notification` 模块没加载 / 没注册 `notificationsApi`，回落到内置只读兜底——而脚手架不再提供 root 级 `/api/notifications` 模块 | 保留 `web.config.ts` 的 `notification` 登记，onInit 里注册四方法（模板 `src/notification/web/entry.ts`）；后端由 `src/notification/api` 提供 `/api/notification/*` |
+| 通知铃 404 `no route matched`（`/api/notifications`） | 前端 `notification` 模块没加载 / 没注册 `notificationsApi`，回落到内置只读兜底——而脚手架不再提供 root 级 `/api/notifications` 模块 | 保留 `web.config.ts` 的 `notification` 登记，onInit 里注册四方法（模板 `src/app/web/notification/entry.ts`）；后端由 `src/notification/api` 提供 `/api/notification/*` |
 | `@types/react` / `typescript` 装成 `*` | 宿主 versions.json 未列 | 安装后按实际版本钉死（`*` 不可复现） |
 | 迁移账本落后、服务拒绝启动 | release `verify` 闸 | 先 `ojm migrate -d api/dist`（透传自动补 `-c`） |
 | `seed.sql` 没生效 / 语法错 | 按 `;` 朴素切分，注释里有分号 | 去掉注释里的分号字面量 |
@@ -1579,14 +1586,14 @@ export default async (path: string, html: string) => {
 
 | 想抄什么 | 抄这里 |
 |---|---|
-| 带页面的模块（路由 / i18n / order） | `src/home/web/entry.ts`、`src/demo/web/entry.ts` |
-| 接管通知 provider（四方法全量） | `src/notification/web/entry.ts` |
-| 上传 provider（action + headers 方法） | `src/personal-center/web/entry.ts` |
-| 无页面模块（`routes: []`） | 同 `src/notification/web/entry.ts` |
+| 带页面的模块（路由 / i18n / order） | `src/app/web/home/entry.ts`、`src/app/web/entry.ts` |
+| 接管通知 provider（四方法全量） | `src/app/web/notification/entry.ts` |
+| 上传 provider（action + headers 方法） | `src/app/web/personal-center/entry.ts` |
+| 无页面模块（`routes: []`） | 同 `src/app/web/notification/entry.ts` |
 | handler `.schema` 入参 + 平级 `.response` 出参写法（GET + POST、参数段） | `src/notification/api/api.ts` |
 | handler 写法（嵌套组列表 / 写入 / 403 归属） | `src/notification/api/api.ts`（模块根单文件，`read`/`read-all`/`clear` 子组） |
 | 统一异常出口 `respond()`（service 抛 `Error & {status}` → 信封 `json.fail`） | 模板 `src/_platform/api/_shared/respond.ts` + 各 handler 用法（§1.7-1） |
-| 生成物长什么样（含工厂） | `src/notification/web/__client/api.ts` |
+| 生成物长什么样（含工厂） | `src/app/web/notification/__client/api.ts` |
 | 建表三件套 | `src/notification/api/{schema.yaml,manifest.yaml,migrations/}` |
 | 全局类型（`window.$message` 等） | 工程根 `env.d.ts` |
 
@@ -2229,7 +2236,7 @@ async function post() {
 3. 页面用本模块 client 调。
 
 多一层 handler 换来三件事：接口形状由**你自己的契约**决定（只出页面要的字段）、框架内部实现不进你的
-bundle、契约变更走你自己的版本号。仓库里 `src/system/web/pages/departments` 的组织架构页就是这条路的
+bundle、契约变更走你自己的版本号。仓库里 `src/app/web/system/pages/departments` 的组织架构页就是这条路的
 另一个方向（它消费的是管理端 `/api/system/departments`，见 §14.4）。
 
 ### 14.4 管理端 CRUD：只有「管组织架构」的模块才该碰

package/package.json

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

package/shell-dist/assets/runtime.js

@@ -304,10 +304,10 @@ function getAppInfo() {
 	return {
 		"pkg": {
 			"name": "@oj-module/runtime",
-			"version": "0.2.53",
+			"version": "0.2.54",
 			"license": "MIT"
 		},
-		"lastBuildTime": "2026-11-02 15:46:13"
+		"lastBuildTime": "2026-11-02 18:04:24"
 	};
 }
 var init_get_app_info = __esmMin((() => {}));
@@ -7500,11 +7500,14 @@ function topologicalSort(entries, definitions) {
 	return sorted;
 }
 async function mergeI18nResources(definition) {
-	if (!definition.i18n) return;
-	for (const [locale, loader] of Object.entries(definition.i18n)) {
+	if (definition.i18n) for (const [locale, loader] of Object.entries(definition.i18n)) {
 		const resources = await loader();
 		i18next.addResourceBundle(locale, definition.name, resources.default || resources);
 	}
+	for (const [namespace, bundle] of Object.entries(definition.i18nNamespaces ?? {})) for (const [locale, loader] of Object.entries(bundle)) {
+		const resources = await loader();
+		i18next.addResourceBundle(locale, namespace, resources.default || resources);
+	}
 }
 async function loadAll(manifest) {
 	const enabledEntries = manifest.modules.filter((m) => m.enabled !== false);

package/shell-dist/index.html

@@ -5,8 +5,8 @@
 		<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-vlbkVLVjOGWbsP3B+GCfRg=='; 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="vlbkVLVjOGWbsP3B+GCfRg==">{
+		<meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'self' https://modules.cdn.example.com 'wasm-unsafe-eval' 'nonce-Php0JD1/JaEf2vFUnNnXaQ=='; 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="Php0JD1/JaEf2vFUnNnXaQ==">{
   "imports": {
     "react": "/assets/react.js",
     "react/jsx-runtime": "/assets/jsx-runtime.js",
@@ -130,7 +130,7 @@
 			.boot-skeleton:after{content:"";width:18px;height:18px;margin-left:8px;border:2px solid #d9d9d9;border-top-color:#1677ff;border-radius:50%;animation:bs-spin .8s linear infinite}
 			@keyframes bs-spin{to{transform:rotate(360deg)}}
 		</style>
-		<script nonce="vlbkVLVjOGWbsP3B+GCfRg==" data-ojm-entry="/assets/index-e_Mp2mb5.js">(function(){try{var ua=(navigator.userAgent||"").toLowerCase(),p=location.pathname;while(p.length>1&&p.charAt(p.length-1)==="/")p=p.slice(0,-1);if(ua.indexOf("wxwork")>=0&&p.slice(-6)==="/login"&&!new URLSearchParams(location.search).get("wecom_ticket")){var a=(typeof window.__OJ_API_BASE__==="string"&&window.__OJ_API_BASE__.trim())||"/api";while(a.length>1&&a.charAt(a.length-1)==="/")a=a.slice(0,-1);location.replace(a+"/auth/wecom/login");return}}catch(e){}var s=document.createElement("script");s.type="module";s.src=document.currentScript.getAttribute("data-ojm-entry");document.head.appendChild(s);})();</script>
+		<script nonce="Php0JD1/JaEf2vFUnNnXaQ==" data-ojm-entry="/assets/index-e_Mp2mb5.js">(function(){try{var ua=(navigator.userAgent||"").toLowerCase(),p=location.pathname;while(p.length>1&&p.charAt(p.length-1)==="/")p=p.slice(0,-1);if(ua.indexOf("wxwork")>=0&&p.slice(-6)==="/login"&&!new URLSearchParams(location.search).get("wecom_ticket")){var a=(typeof window.__OJ_API_BASE__==="string"&&window.__OJ_API_BASE__.trim())||"/api";while(a.length>1&&a.charAt(a.length-1)==="/")a=a.slice(0,-1);location.replace(a+"/auth/wecom/login");return}}catch(e){}var s=document.createElement("script");s.type="module";s.src=document.currentScript.getAttribute("data-ojm-entry");document.head.appendChild(s);})();</script>
 	</head>
 	<body>
 		<div id="root"><div class="boot-skeleton">加载中…</div></div>

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.53",
-  "@oj-module/runtime/contract": "0.2.53",
-  "@oj-module/runtime/contract/errors": "0.2.53",
+  "@oj-module/runtime": "0.2.54",
+  "@oj-module/runtime/contract": "0.2.54",
+  "@oj-module/runtime/contract/errors": "0.2.54",
   "@plane/kit": "0.1.20",
   "@plane/editor": "0.1.20",
   "antd": "6.6.1",

package/src/__tests__/templates-tenant-scope.test.ts

@@ -115,7 +115,7 @@ describe("templates 租户定性（A 租户表 / B 共享表）", () => {
 		expect(unknown).toEqual([]);
 	});
 
-	it("t-4 28 张表的 A/B 分组与方案 v3 §5.2 一致（新增表须先定性）", () => {
+	it("t-4 27 张表的 A/B 分组与方案 v3 §5.2 一致（新增表须先定性）", () => {
 		const { tables } = loadSchemaTables();
 		const shared = [...tables].filter(([, d]) => d.tenant === false).map(([n]) => n).sort();
 		// Phase 0 落地 21 张（11 A + 10 B）；Phase 1 加企微三表，全部 B 组（D9：查它们时必然还没有租户上下文）
@@ -124,7 +124,8 @@ describe("templates 租户定性（A 租户表 / B 共享表）", () => {
 		// auth/0002 加 wecom_sync_job / wecom_sync_lock 两张，同属 A 组：同步只在调用方自己的租户内跑
 		// （D7 不接受 corpId 参数），故不进 shared_allow——跨租户读元数据那条另走显式 tenant_id 的裸 SQL。
 		// 改这张表清单 = 改租户隔离边界，必须同步 config.yaml 的 tenant.shared_allow（t-2/t-3 会把关）。
-		expect(tables.size).toBe(28);
+		// 2026-11-02 demo 模块下线（ecc7b35e）删掉 demo/api/schema.yaml 的 todos 表，28 → 27。
+		expect(tables.size).toBe(27);
 		expect(shared).toEqual([
 			"_oj_migrations",
 			"market_history",

package/src/config.ts

@@ -48,6 +48,15 @@ export interface ModulesConfig {
 	 * `(path, html) => string | { html, cacheControl? } | Promise<…>`）。
 	 */
 	htmlTransform?: string
+	/**
+	 * 生成 client 的归属模块：`api 前缀 → 承载其 __client 的 web 模块`。
+	 *
+	 * 缺省（不配）= 同名模块，即 `src/<api 前缀>/web/__client`（历史行为，零漂移）。
+	 * 多根聚合模块把多个业务域的页面/client 收进同一个 web 模块时配它：生成物落
+	 * `src/<归属模块>/web/<api 前缀>/__client`，页面相对导入 `../__client` 不变。
+	 * 只影响 `ojm api` 的落盘位置与生成物里的认领护栏，不影响路由与后端。
+	 */
+	clientOwners?: Record<string, string>
 }
 
 const DEFAULT_CONFIG: Required<Pick<ModulesConfig, "baseUrl" | "siteBase">> = {

package/src/contract/__tests__/client-path.test.ts

@@ -0,0 +1,30 @@
+import type { ProjectLayout } from "../../layout";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { clientDirOf } from "../client-path";
+
+const layout: ProjectLayout = {
+	kind: "module-root",
+	projectRoot: "/proj",
+	modulesSrc: "/proj/src",
+	distDir: "/proj/dist/web",
+	apiDist: "/proj/dist/api",
+	watchTarget: "/proj/src",
+	moduleRoot: "/proj/src",
+};
+
+describe("clientDirOf（client 落盘目录）", () => {
+	it("缺省 = 同名模块 src/<模块>/web/__client（历史口径零漂移）", () => {
+		expect(clientDirOf(layout, "/proj", "system")).toBe(join("/proj/src/system/web", "__client"));
+	});
+
+	it("clientOwners 指定归属 → src/<归属>/web/<api 前缀>/__client", () => {
+		expect(clientDirOf(layout, "/proj", "system", { system: "app" }))
+			.toBe(join("/proj/src/app/web/system", "__client"));
+	});
+
+	it("历史布局（layout=null）同样支持归属", () => {
+		expect(clientDirOf(null, "/proj", "system", { system: "app" }))
+			.toBe(join("/proj/web/src/app/system", "__client"));
+	});
+});

package/src/contract/__tests__/emit-client.test.ts

@@ -125,6 +125,24 @@ describe("emitClient 注入安全：模块名含特殊字符不破坏源码", ()
 	});
 });
 
+describe("emitClient 多根聚合归属（owner）", () => {
+	it("owner 与 module 不同 → 落 MODULE_OWNER，护栏对比归属模块；MODULE_PREFIX 仍是 api 前缀", () => {
+		const ir = irFromOpenapi(DOC, { base: "/v1/api" });
+		const { "api.ts": apiTs } = emitClient(ir, { target: "module", module: "system", owner: "app" });
+		expect(apiTs).toContain("export const MODULE_PREFIX = \"/system\";");
+		expect(apiTs).toContain("export const MODULE_OWNER = \"/app\";");
+		expect(apiTs).toContain("ctx.module.name !== MODULE_OWNER.slice(1)");
+		expect(apiTs).not.toContain("ctx.module.name !== MODULE_PREFIX.slice(1)");
+	});
+
+	it("owner 缺省 = module → 生成物与历史逐字一致（不出现 MODULE_OWNER）", () => {
+		const ir = irFromOpenapi(DOC, { base: "/v1/api" });
+		const { "api.ts": apiTs } = emitClient(ir, { target: "module", module: "system", owner: "system" });
+		expect(apiTs).not.toContain("MODULE_OWNER");
+		expect(apiTs).toContain("ctx.module.name !== MODULE_PREFIX.slice(1)");
+	});
+});
+
 describe("emitClient 空 IR 报错", () => {
 	it("iR 为空抛错（无端点无需生成）", () => {
 		expect(() => emitClient([], { target: "module", module: "x" })).toThrow();

package/src/contract/__tests__/handler-scan.test.ts

@@ -181,3 +181,26 @@ describe("handler-scan · 对账键与契约侧同形（参数路由精确命中
 		expect(pathKey(row.method, row.full)).toBe(pathKey("DELETE", "wiki/{id}"));
 	});
 });
+
+describe("handler-scan · 工厂返回本地对象（const api = { … }; return api）", () => {
+	it("回归：聚合工厂 return 标识符时仍展开动词与嵌套组（solutions/api.ts 形态）", () => {
+		const rows = scan("api.ts", `
+import type { Env } from "./types";
+export function createApi(env: Env) {
+\tconst routes = { async get() {} };
+\tconst verify = {
+\t\tasync post() {},
+\t\tlast: { async get() {} },
+\t};
+\tconst api = { routes, verify };
+\treturn api;
+}
+export default createApi({} as Env);
+`);
+		expect(rows.map(r => pathKey(r.method, handlerAbs(r))).sort()).toEqual([
+			"GET /_platform/market/routes",
+			"GET /_platform/market/verify/last",
+			"POST /_platform/market/verify",
+		]);
+	});
+});

package/src/contract/check.ts

@@ -4,8 +4,9 @@ import type { IrEndpoint } from "./ir";
 import type { OpenApiDoc } from "./openapi-ir";
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { dirname, join, relative, sep } from "node:path";
-import { apiModuleRoots, apiModulesSrc, apiSrcOf, legacyApiModuleRoots, resolveConfigPath, tryResolveLayout, webSrcOf } from "../layout";
+import { apiModuleRoots, apiModulesSrc, apiSrcOf, legacyApiModuleRoots, resolveConfigPath, tryResolveLayout } from "../layout";
 import { readOjAnonymousPaths } from "../oj-config";
+import { clientDirOf, loadClientOwners } from "./client-path";
 import { emitClient } from "./emit-client";
 import { planStubWrites } from "./emit-stub";
 import { handlerAbs, implementedRouteKeys, pathKey, scanHandlerFile, VERB_OF, walkApiFiles } from "./handler-scan";
@@ -308,11 +309,10 @@ async function checkFromOpenapi(openapiPath: string, cwd: string, _exemption: Ap
 	// 契约工具的扫描单元是「模块 api 根」而不是整棵源码树：module-root 布局里
 	// `src/<name>/api` 的 `api` 段不属于路由，且 `web/__client/api.ts` 不能被当 handler。
 	const roots = layout ? apiModuleRoots(layout) : legacyApiModuleRoots(cwd);
-	const clientDirOf = (module: string) =>
-		join(layout ? webSrcOf(layout, module) : join(cwd, "web/src", module), "__client");
+	const owners = await loadClientOwners(layout?.projectRoot ?? cwd);
 	for (const [module, eps] of groupIrByModule(ir)) {
-		const client = emitClient(eps, { target: "module", module });
-		const clientDir = clientDirOf(module);
+		const client = emitClient(eps, { target: "module", module, owner: owners[module] });
+		const clientDir = clientDirOf(layout, cwd, module, owners);
 		for (const [file, content] of [["api.ts", client["api.ts"]], ["api.schemas.ts", client["api.schemas.ts"]]] as const) {
 			const p = join(clientDir, file);
 			if (!existsSync(p) || readFileSync(p, "utf8") !== content)

package/src/contract/client-path.ts

@@ -0,0 +1,30 @@
+import type { ProjectLayout } from "../layout";
+
+import path from "node:path";
+import { loadSiteConfig } from "../config";
+import { webSrcOf } from "../layout";
+
+/**
+ * 生成 client 的落盘目录（`ojm api` 写、`ojm api --check` 核对，同一真源）。
+ *
+ * 缺省口径不变：`<project>/src/<api 前缀>/web/__client`（历史布局 `web/src/<模块>/__client`）。
+ * 多根聚合模块（web.config `clientOwners`）把多个业务域的 client 收进同一个 web 模块：
+ * 落 `<project>/src/<归属模块>/web/<api 前缀>/__client`——页面与该目录一起迁移，
+ * 页面里的相对导入 `../../__client` 不用改。
+ */
+export function clientDirOf(
+	layout: ProjectLayout | null,
+	cwd: string,
+	apiModule: string,
+	owners: Record<string, string> = {},
+): string {
+	const owner = owners[apiModule] ?? apiModule;
+	const base = layout ? webSrcOf(layout, owner) : path.join(cwd, "web/src", owner);
+	return owner === apiModule ? path.join(base, "__client") : path.join(base, apiModule, "__client");
+}
+
+/** 读 web.config.ts 的 `clientOwners`（缺文件 / 未配置 = 空表，口径回落同名模块） */
+export async function loadClientOwners(projectRoot: string): Promise<Record<string, string>> {
+	const config = await loadSiteConfig(projectRoot);
+	return config.clientOwners ?? {};
+}

package/src/contract/emit-client.ts

@@ -229,8 +229,8 @@ function emitEndpoint(ep: IrEndpoint): string {
 }`;
 }
 
-function emitPrelude(target: "module" | "internal", module?: string, endpointNames: string[] = [], wirePrefix?: string): string {
-	const binding = target === "module"
+function emitPrelude(target: "module" | "internal", module?: string, endpointNames: string[] = [], wirePrefix?: string, owner?: string): string {
+	let binding = target === "module"
 		? `let req: ScopedRequestLike | undefined;
 
 /** 线上 API 前缀（ojm api 从契约抽取，唯一真源，勿手改）：请求基址 + 前缀登记用 */
@@ -275,6 +275,20 @@ function ensureReq(): ScopedRequestLike {
 	return request;
 }`;
 
+	// 多根聚合模块：client 落在归属模块目录下，认领护栏的对比基准随之改为归属模块名。
+	// 缺省（未配 clientOwners）owner === module，生成物与历史逐字一致（快照不变）。
+	if (target === "module" && owner && owner !== module) {
+		binding = binding
+			.replace(
+				`export const MODULE_PREFIX = ${JSON.stringify(`/${module}`)};`,
+				`export const MODULE_PREFIX = ${JSON.stringify(`/${module}`)};
+
+/** 认领方模块（web.config clientOwners 指定）：跨模块认领护栏对比基准 */
+export const MODULE_OWNER = ${JSON.stringify(`/${owner}`)};`,
+			)
+			.replaceAll("MODULE_PREFIX.slice(1)", "MODULE_OWNER.slice(1)");
+	}
+
 	const ctxImport = target === "module"
 		? "import type { ModuleContext } from \"@oj-module/runtime\";\n"
 		: "";
@@ -344,7 +358,7 @@ ${entries.join("\n")}
 }
 
 /** 发射双产物：api.ts（类型 + 请求函数 + 工厂）与 api.schemas.ts（DEV 校验 schema） */
-export function emitClient(ir: IrEndpoint[], opts: { target: "module" | "internal", module?: string }): { "api.ts": string, "api.schemas.ts": string } {
+export function emitClient(ir: IrEndpoint[], opts: { target: "module" | "internal", module?: string, /** client 归属模块（多根聚合）；缺省 = module */ owner?: string }): { "api.ts": string, "api.schemas.ts": string } {
 	if (ir.length === 0)
 		throw new Error("[ojm-api] client 发射失败：IR 为空——openapi.json 里没有任何端点（operationId + tags），无需生成；请检查 \`oj openapi\` 产物。");
 	if (opts.target === "module" && !opts.module) {
@@ -362,7 +376,7 @@ export function emitClient(ir: IrEndpoint[], opts: { target: "module" | "interna
 			+ "——register.apiPrefix 一模块一值，urlPrefix 映射须整模块一致（不同前缀请拆模块）。",
 		);
 	}
-	const sections: string[] = [emitPrelude(opts.target, opts.module, ir.map(ep => ep.name), wirePrefixes.size === 1 ? wirePrefixes.values().next().value : undefined)];
+	const sections: string[] = [emitPrelude(opts.target, opts.module, ir.map(ep => ep.name), wirePrefixes.size === 1 ? wirePrefixes.values().next().value : undefined, opts.owner)];
 	for (const ep of ir) {
 		const types = emitTypes(ep);
 		if (types.length)

package/src/contract/handler-scan.ts

@@ -161,7 +161,23 @@ function defaultExportObject(sf: ts.SourceFile, decls: Map<string, ts.ObjectLite
  * 旧逻辑直接 dottedNameOf(call.expression) 对 CallExpression 返回 undefined → 扫成 0 路由，
  * 致使 ojm api --check 把 market 全族端点判为「未实现 / stub 缺失」。此处穿透一层取被调函数名。
  */
-function factoryReturnObjects(sf: ts.SourceFile, call: ts.CallExpression): ts.ObjectLiteralExpression[] {
+/**
+ * 取函数体内 `const <name> = { … }` 的对象字面量初始化器（工厂 return 标识符时用）。
+ * 只认直接声明，不追闭包/别名——够用即可，追深了会把无关对象当路由组。
+ */
+function objectLiteralOf(body: ts.Block, name: string): ts.ObjectLiteralExpression | undefined {
+	for (const st of body.statements) {
+		if (!ts.isVariableStatement(st))
+			continue;
+		for (const d of st.declarationList.declarations) {
+			if (ts.isIdentifier(d.name) && d.name.text === name && d.initializer && ts.isObjectLiteralExpression(d.initializer))
+				return d.initializer;
+		}
+	}
+	return undefined;
+}
+
+function factoryReturnObjects(sf: ts.SourceFile, call: ts.CallExpression, decls: Map<string, ts.ObjectLiteralExpression>): ts.ObjectLiteralExpression[] {
 	// `export default createXxxApi(marketEnv())`：`call.expression` 为带实参的调用表达式，
 	// 函数名在其 `.expression`；`export default obj.createXxxApi(marketEnv())` 同样穿透。
 	const target = ts.isCallExpression(call.expression) ? call.expression.expression : call.expression;
@@ -171,10 +187,31 @@ function factoryReturnObjects(sf: ts.SourceFile, call: ts.CallExpression): ts.Ob
 	for (const stmt of sf.statements) {
 		if (!ts.isFunctionDeclaration(stmt) || stmt.name?.text !== callee || stmt.body === undefined)
 			continue;
+		// 工厂体内的局部对象声明（`const routes = {…}`）合并进声明表：
+		// return 的对象里用简写属性引用它们时，walk 才能解析到组。
+		for (const st of stmt.body.statements) {
+			if (!ts.isVariableStatement(st))
+				continue;
+			for (const d of st.declarationList.declarations) {
+				if (ts.isIdentifier(d.name) && d.initializer && ts.isObjectLiteralExpression(d.initializer))
+					decls.set(d.name.text, d.initializer);
+			}
+		}
 		const out: ts.ObjectLiteralExpression[] = [];
 		for (const st of stmt.body.statements) {
-			if (ts.isReturnStatement(st) && st.expression !== undefined && ts.isObjectLiteralExpression(st.expression))
+			if (!ts.isReturnStatement(st) || st.expression === undefined)
+				continue;
+			if (ts.isObjectLiteralExpression(st.expression)) {
 				out.push(st.expression);
+				continue;
+			}
+			// `const api = { routes, verify }; … return api;` 形态（聚合工厂）：
+			// 返回标识符时回溯同函数体内的 object literal 初始化器。
+			if (ts.isIdentifier(st.expression)) {
+				const local = objectLiteralOf(stmt.body, st.expression.text);
+				if (local)
+					out.push(local);
+			}
 		}
 		return out;
 	}
@@ -317,7 +354,7 @@ export function scanHandlerFile(filePath: string, apiDir: string, moduleName = "
 				? expr
 				: (ts.isIdentifier(expr) ? callDecls.get(expr.text) : undefined);
 			if (callExpr) {
-				for (const obj of factoryReturnObjects(sf, callExpr))
+				for (const obj of factoryReturnObjects(sf, callExpr, decls))
 					walk(obj, "", "", 1);
 			}
 		}

package/src/contract/run.ts

@@ -8,7 +8,8 @@ import { basename, dirname, join } from "node:path";
 import process from "node:process";
 import { promisify } from "node:util";
 import { stringify as stringifyYaml } from "yaml";
-import { apiModuleRoots, apiModulesSrc, apiSrcOf, legacyApiModuleRoots, scanModules, tryResolveLayout, webSrcOf } from "../layout";
+import { apiModuleRoots, apiModulesSrc, apiSrcOf, legacyApiModuleRoots, scanModules, tryResolveLayout } from "../layout";
+import { clientDirOf, loadClientOwners } from "./client-path";
 import { emitClient } from "./emit-client";
 import { applyStubWrites, planStubWrites } from "./emit-stub";
 import { implementedRouteKeys } from "./handler-scan";
@@ -83,10 +84,11 @@ async function runFromOpenapi(openapiPath: string, cwd: string, result: RunResul
 	const ir = irFromOpenapi(doc, { rawPaths });
 	const byModule = groupIrByModule(ir);
 	const layout = tryResolveLayout(cwd);
+	const owners = await loadClientOwners(layout?.projectRoot ?? cwd);
 	result.contracts += byModule.size;
 	for (const [module, eps] of byModule) {
-		const client = emitClient(eps, { target: "module", module });
-		const clientDir = join(layout ? webSrcOf(layout, module) : join(cwd, "web/src", module), "__client");
+		const client = emitClient(eps, { target: "module", module, owner: owners[module] });
+		const clientDir = clientDirOf(layout, cwd, module, owners);
 		writeIfChanged(join(clientDir, "api.ts"), client["api.ts"], result);
 		writeIfChanged(join(clientDir, "api.schemas.ts"), client["api.schemas.ts"], result);
 	}

package/src/init.ts

@@ -240,6 +240,17 @@ export async function initProject(destDir: string, opts: InitOptions = {}): Prom
 	//     与 pnpm-workspace.yaml 同型，改由 init 现场生成
 	ensureGitignore(destDir, report);
 
+	// 5d) 旧布局冲突提示：0.2.54 起 home/login/personal-center/notification/system 的
+	//     web 侧聚合成 src/app/web 多根模块。init 只补缺不删除——老工程重跑 init 会
+	//     同时留下旧目录，扫描后同名路由注册两遍（菜单重复、行为不一致）。
+	const mergedEntry = path.join(destDir, "src", "app", "web", "entry.ts");
+	if (fs.existsSync(mergedEntry)) {
+		const leftovers = ["home", "login", "personal-center", "notification", "system"]
+			.filter(name => fs.existsSync(path.join(destDir, "src", name, "web", "entry.ts")));
+		if (leftovers.length > 0)
+			report.warnings.push(`检测到旧布局的前端模块目录（${leftovers.map(n => `src/${n}/web`).join("、")}）与新的聚合模块 src/app/web 并存——路由会重复注册。请手工删除这些旧 web 目录（其 api 侧保留）。`);
+	}
+
 	console.log(`[ojm] init 完成：${destDir}`);
 	console.log(`[ojm]   新增 ${report.created.length} 项，跳过（已存在）${report.skipped.length} 项`);
 	for (const item of report.skipped)
@@ -407,7 +418,10 @@ function pruneUnincludedApiPaths(destDir: string, include: Set<string>, report:
 	if (mods.size === 0)
 		return;
 	const openapiPath = path.join(destDir, "openapi.json");
-	const doc = JSON.parse(fs.readFileSync(openapiPath, "utf-8")) as { paths?: Record<string, unknown> };
+	const doc = JSON.parse(fs.readFileSync(openapiPath, "utf-8")) as {
+		paths?: Record<string, unknown>
+		tags?: { name?: string }[]
+	};
 	const paths = doc.paths ?? {};
 	const dropped = Object.keys(paths).filter((p) => {
 		const mod = /^\/api\/([^/]+)\//.exec(p)?.[1];
@@ -417,6 +431,10 @@ function pruneUnincludedApiPaths(destDir: string, include: Set<string>, report:
 		return;
 	for (const p of dropped)
 		delete paths[p];
+	// 顶层 tags 也要同步：只裁路径会留下指向不存在模块的 tag（契约自相矛盾，
+	// oj openapi 重产时又会消失，属 drift 噪声）。
+	if (Array.isArray(doc.tags))
+		doc.tags = doc.tags.filter(t => typeof t.name !== "string" || mods.has(t.name));
 	fs.writeFileSync(openapiPath, `${JSON.stringify(doc, null, "\t")}\n`);
 	report.created.push(`openapi.json 裁掉未收录 api 模块端点 ${dropped.length} 条`);
 }