@oj-module/cli 0.2.53 → 0.2.56

package/src/__tests__/templates-schema-columns.test.ts

@@ -0,0 +1,99 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { parse } from "yaml";
+
+/**
+ * BDD：模板后端「迁移落库的列」必须在所属模块 schema.yaml 的列白名单里声明。
+ *
+ * 为什么要这条：oj 的 SQL 构造器是二进制内的 Rust 实现，select/insert/update 的列会**先**按
+ * schema.yaml 校验，列在库里但不在白名单时，SQL 还没发就被拒成
+ * `unknown column 'x' in <site>`（site 随语句位置变：join on / insert values / update sets …）。
+ * 线上表现是端点 500、日志里没有 SQL，看起来像「列不存在」，实际是声明漏了。
+ *
+ * 真实事故（2026-11）：_platform 0017 加了 users.employee_no，schema.yaml 漏声明，
+ * /system/departments（选人列表依赖 /system/users）整页 500。
+ *
+ * 校验面取 `ALTER TABLE … ADD COLUMN`：已有表新增列的唯一入口，也是最容易「只写迁移、
+ * 忘了补声明」的一类。整表声明由 t-2（租户定性）与表数快照兜底。
+ */
+
+const templatesRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../../templates");
+const srcRoot = join(templatesRoot, "src");
+
+interface ColumnDecl {
+	type?: string
+	[key: string]: unknown
+}
+
+interface SchemaDoc {
+	tables?: Record<string, { columns?: Record<string, ColumnDecl> }>
+}
+
+/** `ALTER TABLE <表> ADD [COLUMN] <列>`（忽略方言专属文件，sqlite 基础件是唯一真相） */
+const ADD_COLUMN_RE = /ALTER\s+TABLE\s+[`"']?(\w+)[`"']?\s+ADD\s+(?:COLUMN\s+)?[`"']?(\w+)[`"']?/gi;
+
+function walk(dir: string, out: string[] = []): string[] {
+	for (const entry of readdirSync(dir)) {
+		const full = join(dir, entry);
+		if (statSync(full).isDirectory())
+			walk(full, out);
+		else
+			out.push(full);
+	}
+	return out;
+}
+
+/** 表名 → 声明的列集合（跨模块同名表由 templates-tenant-scope 的 S002 断言拦，这里取并集） */
+function loadDeclaredColumns(files: string[]): Map<string, Set<string>> {
+	const declared = new Map<string, Set<string>>();
+	for (const file of files.filter(f => f.endsWith("schema.yaml"))) {
+		const doc = parse(readFileSync(file, "utf-8")) as SchemaDoc | null;
+		for (const [table, decl] of Object.entries(doc?.tables ?? {}))
+			declared.set(table, new Set(Object.keys(decl.columns ?? {})));
+	}
+	return declared;
+}
+
+/** 基础迁移文件：`migrations/*.sql`，排除 `<名>.mysql.sql` / `<名>.pg.sql` */
+function isBaseMigration(file: string): boolean {
+	return /[/\\]migrations[/\\][^/\\]+\.sql$/.test(file) && !/\.(?:mysql|pg)\.sql$/.test(file);
+}
+
+describe("templates 后端 schema.yaml 列白名单", () => {
+	it("s-1 迁移里 ADD COLUMN 的列都在 schema.yaml 有声明（漏声明 = 构造器拒查）", () => {
+		const files = walk(srcRoot);
+		const declared = loadDeclaredColumns(files);
+		const violations: string[] = [];
+
+		for (const file of files.filter(isBaseMigration)) {
+			for (const m of readFileSync(file, "utf-8").matchAll(ADD_COLUMN_RE)) {
+				const [, table, column] = m;
+				const where = relative(templatesRoot, file);
+				const cols = declared.get(table);
+				if (!cols) {
+					violations.push(`${where}: 表 ${table} 未在任何 schema.yaml 声明`);
+					continue;
+				}
+				if (!cols.has(column)) {
+					violations.push(
+						`${where}: ${table}.${column} 未在 schema.yaml 声明`
+						+ `（构造器会拒为 unknown column '${column}' in on '${table}'；补到 owning 模块的 tables.${table}.columns）`,
+					);
+				}
+			}
+		}
+
+		expect(violations).toEqual([]);
+	});
+
+	it("s-2 回归锚点：0017 三方言迁移齐备，users.employee_no 已声明为 text", () => {
+		const migDir = join(srcRoot, "app", "api", "_platform", "migrations");
+		for (const file of ["0017__users_employee_no.sql", "0017__users_employee_no.mysql.sql", "0017__users_employee_no.pg.sql"])
+			expect(existsSync(join(migDir, file)), `缺迁移 ${file}`).toBe(true);
+
+		const schema = parse(readFileSync(join(srcRoot, "app", "api", "_platform", "schema.yaml"), "utf-8")) as SchemaDoc;
+		expect(schema.tables?.users?.columns?.employee_no).toMatchObject({ type: "text" });
+	});
+});

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/alias-paths.ts

@@ -20,18 +20,18 @@ import type { ProjectLayout } from "./layout";
 import fs from "node:fs";
 import path from "node:path";
 import { parse } from "yaml";
-import { tryResolveLayout } from "./layout";
+import { scanModules, tryResolveLayout } from "./layout";
 
 /** 生成物文件名（工程根）。`src/tsconfig.json` 以 `../tsconfig.paths.json` 引用 */
 export const ALIAS_PATHS_FILE = "tsconfig.paths.json";
 
 /** 生成物头注释：tsconfig 允许注释，且这是唯一会被 `ojm` 覆写的 tsconfig */
 const HEADER = [
-	"// 由 ojm 生成：ojm init / ojm build / ojm dev 会按 src/*/api/manifest.yaml 重写本文件，请勿手改。",
+	"// 由 ojm 生成：ojm init / ojm build / ojm dev 会按模块清单重写本文件，请勿手改。",
 	"//",
-	"// oj 别名 `#/<模块名>/…` 锚在目标模块根（本布局下即 src/<模块名>/api）。tsconfig 的",
-	"// paths 只能静态全局映射，且每条规则的替换值只允许一个 `*`（`./src/*/api/*` 会被 TS",
-	"// 以 TS5062 拒掉），故按模块逐条枚举。",
+	"// oj 别名 `#/<模块名>/…` 锚在目标模块根（src/<模块名>/api 或 src/app/api/<模块名>）。",
+	"// tsconfig 的 paths 只能静态全局映射，且每条规则的替换值只允许一个 `*`（`./src/*/api/*`",
+	"// 会被 TS 以 TS5062 拒掉），故按模块逐条枚举。",
 ].join("\n");
 
 /** 读模块根 manifest 的 `name`（oj 的模块身份）；读不到/格式坏时回落到目录名 */
@@ -58,14 +58,13 @@ export function aliasPathEntries(layout: ProjectLayout): Record<string, string[]
 	if (layout.kind !== "module-root")
 		return {};
 	const entries: Record<string, string[]> = {};
-	for (const mod of fs.readdirSync(layout.modulesSrc, { withFileTypes: true })) {
-		if (!mod.isDirectory() || mod.name.startsWith("."))
+	// 以扫描结果为准：既覆盖平铺 src/<name>/api，也覆盖聚合容器 src/app/api/<name>
+	for (const mod of scanModules(layout)) {
+		if (!mod.apiSrc)
 			continue;
-		const apiDir = path.join(layout.modulesSrc, mod.name, "api");
-		if (!fs.existsSync(path.join(apiDir, "manifest.yaml")))
-			continue;
-		const name = manifestName(apiDir, mod.name);
-		entries[`#/${name}/*`] = [`./${path.posix.join("src", mod.name, "api", "*")}`];
+		const name = manifestName(mod.apiSrc, mod.name);
+		const rel = path.relative(layout.projectRoot, mod.apiSrc).split(path.sep).join("/");
+		entries[`#/${name}/*`] = [`./${rel}/*`];
 	}
 	return entries;
 }

package/src/builtin.ts

@@ -64,9 +64,16 @@ export function readBuiltinModules(projectRoot: string): Set<string> {
 export function deriveBuiltinModules(include: Iterable<string>): Set<string> {
 	const mods = new Set<string>();
 	for (const p of include) {
-		const m = /^src\/([^/]+)\/(?:api|web)(?:\/|$)/.exec(p)?.[1];
-		if (m)
-			mods.add(m);
+		// 聚合容器下的后端模块：src/app/api/<name>（模块名取 api 的下一段，不是容器名）
+		const nested = /^src\/[^/]+\/api\/([^/]+)(?:\/|$)/.exec(p)?.[1];
+		if (nested) {
+			mods.add(nested);
+			continue;
+		}
+		// 平铺后端 src/<name>/api 与前端 src/<name>/web/...
+		const flat = /^src\/([^/]+)\/(?:api|web)(?:\/|$)/.exec(p)?.[1];
+		if (flat)
+			mods.add(flat);
 	}
 	return mods;
 }

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

@@ -72,7 +72,7 @@ function emit() {
 }
 
 describe("emitClient (module target)", () => {
-	const { "api.ts": apiTs, "api.schemas.ts": schemasTs } = emit();
+	const { "index.ts": apiTs, "api.schemas.ts": schemasTs } = emit();
 
 	it("aPI_PREFIX / MODULE_PREFIX 用 JSON 字符串字面量（注入安全）", () => {
 		expect(apiTs).toContain("export const API_PREFIX = \"/wiki\";");
@@ -114,7 +114,7 @@ describe("emitClient (module target)", () => {
 describe("emitClient 注入安全：模块名含特殊字符不破坏源码", () => {
 	it("module 名含 -/$ 时 MODULE_PREFIX/工厂名仍走字符串字面量（API_PREFIX 取 IR wirePrefix）", () => {
 		const ir = irFromOpenapi(DOC, { base: "/v1/api" });
-		const { "api.ts": apiTs } = emitClient(ir, { target: "module", module: "weird-name" });
+		const { "index.ts": apiTs } = emitClient(ir, { target: "module", module: "weird-name" });
 		// module 选项只影响 MODULE_PREFIX 与 create<Module>Client 名
 		expect(apiTs).toContain("export const MODULE_PREFIX = \"/weird-name\";");
 		expect(apiTs).toContain("export function createWeirdNameClient(");
@@ -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 { "index.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 { "index.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/__tests__/market-client.integration.test.ts

@@ -1,4 +1,4 @@
-// ScopedRequestLike 真源在 runtime contract（生成物 __client/api.ts 也从这里 import，
+// ScopedRequestLike 真源在 runtime contract（生成物 __client/index.ts 也从这里 import，
 // 自身不再 re-export——旧写法 type import 自 __client 会在再生后 TS2305）。
 import type { ScopedRequestLike } from "@oj-module/runtime/contract/errors";
 
@@ -9,7 +9,7 @@ import type { ScopedRequestLike } from "@oj-module/runtime/contract/errors";
 // 不加载 @oj-module/runtime 重依赖（antd / pro-components 在 node 环境无法 import），仅桩 request、
 // 透传真实 zod（供生成 client 的 DEV 响应校验走真实路径）。ContractApiError 由轻量子路径提供。
 import { beforeEach, describe, expect, it, vi } from "vitest";
-import { bindRequest } from "../../../templates/src/_platform/web/__client/api";
+import { bindRequest } from "../../../templates/src/app/web/_platform/__client";
 import { httpMarketClient } from "../../../templates/src/oj-market/web/api/defaultClient";
 
 // index() 直连 request（不走生成 client），故把桩 request 做成可变实现，测试内统一指向同一 mock。

package/src/contract/__tests__/run-api.test.ts

@@ -46,9 +46,9 @@ describe("runApi 消费 openapi.json（新口径 Task #4）", () => {
 		const result = await runApi({ cwd: dir, openapi: "openapi.json" });
 		expect(result.contracts).toBe(2);
 
-		const wikiApi = join(dir, "web/src/wiki/__client/api.ts");
+		const wikiApi = join(dir, "web/src/wiki/__client/index.ts");
 		const wikiSchemas = join(dir, "web/src/wiki/__client/api.schemas.ts");
-		const userApi = join(dir, "web/src/user/__client/api.ts");
+		const userApi = join(dir, "web/src/user/__client/index.ts");
 		expect(existsSync(wikiApi)).toBe(true);
 		expect(existsSync(wikiSchemas)).toBe(true);
 		expect(existsSync(userApi)).toBe(true);

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";
@@ -306,18 +307,21 @@ async function checkFromOpenapi(openapiPath: string, cwd: string, _exemption: Ap
 	const violations: CheckViolation[] = [];
 	const layout = tryResolveLayout(cwd);
 	// 契约工具的扫描单元是「模块 api 根」而不是整棵源码树：module-root 布局里
-	// `src/<name>/api` 的 `api` 段不属于路由，且 `web/__client/api.ts` 不能被当 handler。
+	// `src/<name>/api` 的 `api` 段不属于路由，且 `web/__client/index.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);
-		for (const [file, content] of [["api.ts", client["api.ts"]], ["api.schemas.ts", client["api.schemas.ts"]]] as const) {
+		const client = emitClient(eps, { target: "module", module, owner: owners[module] });
+		const clientDir = clientDirOf(layout, cwd, module, owners);
+		for (const [file, content] of [["index.ts", client["index.ts"]], ["api.schemas.ts", client["api.schemas.ts"]]] as const) {
 			const p = join(clientDir, file);
 			if (!existsSync(p) || readFileSync(p, "utf8") !== content)
 				violations.push({ level: "error", kind: "artifact-stale", message: `[ojm-api] 生成物过期或缺失：${relative(cwd, p)}——请重跑 ojm api 使其与 openapi.json 同步。`, filePath: p });
 		}
+		// 旧生成物（0.2.54 前叫 api.ts）：不删会被 oj dev 当路由扫描并因 import 逃逸报错
+		const legacy = join(clientDir, "api.ts");
+		if (existsSync(legacy))
+			violations.push({ level: "error", kind: "artifact-stale", message: `[ojm-api] 旧生成物仍在：${relative(cwd, legacy)}——入口已改为 index.ts，请重跑 ojm api（会删除旧文件）。`, filePath: legacy });
 	}
 	const apiSrcDir = layout ? apiModulesSrc(layout) : join(cwd, "api/src");
 	if (existsSync(apiSrcDir)) {

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"
 		: "";
@@ -343,8 +357,15 @@ ${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 } {
+/**
+ * 发射双产物：index.ts（类型 + 请求函数 + 工厂）与 api.schemas.ts（DEV 校验 schema）。
+ *
+ * 入口文件名是 `index.ts` 而非 `api.ts`：oj dev 的 `--module-root` 扫描会把模块目录下
+ * **任何 `api.ts`** 当路由文件导入，聚合模块（src/app 同时有 api/ 与 web/）里的
+ * `web/<root>/__client/index.ts` 会被误扫（import 逃逸 project root 直接报错）。
+ * `index.ts` 不在扫描名单内，且 `from "../__client"` 的导入更短。
+ */
+export function emitClient(ir: IrEndpoint[], opts: { target: "module" | "internal", module?: string, /** client 归属模块（多根聚合）；缺省 = module */ owner?: string }): { "index.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 +383,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)
@@ -372,7 +393,7 @@ export function emitClient(ir: IrEndpoint[], opts: { target: "module" | "interna
 		sections.push(emitEndpoint(ep));
 	}
 	return {
-		"api.ts": `${sections.join("\n\n")}\n`,
+		"index.ts": `${sections.join("\n\n")}\n`,
 		"api.schemas.ts": emitSchemas(ir, opts.target),
 	};
 }

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

@@ -2,13 +2,14 @@ import type { OjSchemaDiag } from "./emit-oj-schema";
 import type { IrEndpoint } from "./ir";
 import type { OpenApiDoc } from "./openapi-ir";
 import { execFile as execFileCb } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { createRequire } from "node:module";
 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,12 +84,21 @@ 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");
-		writeIfChanged(join(clientDir, "api.ts"), client["api.ts"], result);
+		const client = emitClient(eps, { target: "module", module, owner: owners[module] });
+		const clientDir = clientDirOf(layout, cwd, module, owners);
+		writeIfChanged(join(clientDir, "index.ts"), client["index.ts"], result);
 		writeIfChanged(join(clientDir, "api.schemas.ts"), client["api.schemas.ts"], result);
+		// 迁移：0.2.54 起入口文件从 api.ts 改为 index.ts。旧文件必须删——oj dev 的
+		// --module-root 扫描会把模块目录下任何 api.ts 当路由导入（聚合模块的
+		// web/<root>/__client/index.ts 会直接报 import 逃逸）。
+		const legacy = join(clientDir, "api.ts");
+		if (existsSync(legacy)) {
+			rmSync(legacy);
+			result.written.push(legacy);
+		}
 	}
 	// stub：oj 目录镜像树（人碰过的文件永不写——plan 阶段已按指纹判好）。
 	// 已实现键全量扫一遍传入：嵌套组（模块根单文件）实现的端点不再生成镜像 stub。