@oj-module/cli 0.2.54 → 0.2.56

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/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(");
@@ -128,7 +128,7 @@ 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" });
+		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)");
@@ -137,7 +137,7 @@ describe("emitClient 多根聚合归属（owner）", () => {
 
 	it("owner 缺省 = module → 生成物与历史逐字一致（不出现 MODULE_OWNER）", () => {
 		const ir = irFromOpenapi(DOC, { base: "/v1/api" });
-		const { "api.ts": apiTs } = emitClient(ir, { target: "module", module: "system", owner: "system" });
+		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)");
 	});

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

@@ -307,17 +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 owners = await loadClientOwners(layout?.projectRoot ?? cwd);
 	for (const [module, eps] of groupIrByModule(ir)) {
 		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) {
+		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/emit-client.ts

@@ -357,8 +357,15 @@ ${entries.join("\n")}
 `;
 }
 
-/** 发射双产物：api.ts（类型 + 请求函数 + 工厂）与 api.schemas.ts（DEV 校验 schema） */
-export function emitClient(ir: IrEndpoint[], opts: { target: "module" | "internal", module?: string, /** client 归属模块（多根聚合）；缺省 = module */ owner?: 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) {
@@ -386,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/run.ts

@@ -2,7 +2,7 @@ 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";
@@ -89,8 +89,16 @@ async function runFromOpenapi(openapiPath: string, cwd: string, result: RunResul
 	for (const [module, eps] of byModule) {
 		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, "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。

package/src/init.ts

@@ -240,15 +240,22 @@ 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 侧保留）。`);
+	// 5d) 旧布局冲突提示：0.2.54 起因/app 同时承载前端聚合模块与后端模块。
+	//     init 只补缺不删除——老工程重跑 init 会同时留下旧目录：
+	//       · src/<name>/web 与 src/app/web 同名路由注册两遍（菜单重复）；
+	//       · src/<name>/api 与 src/app/api/<name> 模块名重复（ojm 扫描直接报错）。
+	const mergedWeb = path.join(destDir, "src", "app", "web", "entry.ts");
+	const mergedApi = path.join(destDir, "src", "app", "api");
+	if (fs.existsSync(mergedWeb) || fs.existsSync(mergedApi)) {
+		const appModules = ["home", "login", "personal-center", "notification", "system", "_platform", "auth", "web"];
+		const oldWeb = appModules.filter(name => fs.existsSync(path.join(destDir, "src", name, "web", "entry.ts")));
+		if (oldWeb.length > 0)
+			report.warnings.push(`检测到旧布局的前端模块目录（${oldWeb.map(n => `src/${n}/web`).join("、")}）与新聚合模块 src/app/web 并存——路由会重复注册。请手工删除这些旧 web 目录。`);
+		const oldApi = appModules.filter(name =>
+			fs.existsSync(path.join(destDir, "src", name, "api", "manifest.yaml"))
+			&& fs.existsSync(path.join(mergedApi, name, "manifest.yaml")));
+		if (oldApi.length > 0)
+			report.warnings.push(`检测到旧布局的后端模块目录（${oldApi.map(n => `src/${n}/api`).join("、")}）与新位置 src/app/api/<name> 同名——模块名重复会让 ojm 扫描报错。请手工删除这些旧 api 目录。`);
 	}
 
 	console.log(`[ojm] init 完成：${destDir}`);
@@ -411,9 +418,10 @@ function pruneUnincludedApiPaths(destDir: string, include: Set<string>, report:
 	// 只裁本次新建的 openapi.json：init 是幂等补缺，不改动既有工程文件
 	if (!report.created.includes("openapi.json"))
 		return;
-	// 白名单里 `src/<name>/api` 这条（整模块收录）决定「脚手架有哪些后端模块」
+	// 白名单里的 api 侧条目决定「脚手架有哪些后端模块」：
+	// 平铺 `src/<name>/api` 与聚合容器 `src/app/api/<name>` 都要认。
 	const mods = new Set([...include]
-		.map(p => /^src\/([^/]+)\/api$/.exec(p)?.[1])
+		.map(p => /^src\/([^/]+)\/api$/.exec(p)?.[1] ?? /^src\/[^/]+\/api\/([^/]+)$/.exec(p)?.[1])
 		.filter((m): m is string => !!m));
 	if (mods.size === 0)
 		return;

package/src/layout.ts

@@ -6,13 +6,16 @@
  *
  * 三种布局（互斥）：
  *   module-root  <project>/src/<name>/{api,web}   新布局：一目录一模块（设计 v2）
+ *                也支持聚合容器：src/app/{api/<模块>,web}——app 的 web 侧是多根前端模块，
+ *                api 侧每个子目录各自是独立后端模块（模块名 = 子目录名 = URL 前缀）
  *   new           <project>/web/src/<name>        历史 uni-dev 布局
  *   flat          <project>/web/<name>            框架根仓 dogfooding（产物落 build/）
  *
  * module-root 的判定只认「模块根标记文件」而不是单纯的 src/ 存在性：工程里
  * 常有不属于模块的 src/（脚本、共享库），凭目录名猜会误判。
  * `src/<x>/api/manifest.yaml` 与 `src/<x>/web/entry.ts` 是唯一真源（设计 C-6：
- * 一侧可缺省，两侧皆无则不是模块）。
+ * 一侧可缺省，两侧皆无则不是模块）。聚合容器下后端模块根是 `src/app/api/<x>/manifest.yaml`
+ * （见 collectApiRoots）。
  *
  * 产物根（2026-10-22 起收进工程根单一 dist/，原 {web,api}/dist 与源码混树）：
  *   dist/api   oj 扁平 release 根（<name>-<version>/ 同层兄弟 + manifests.yaml），三种布局一致
@@ -31,7 +34,7 @@ export type LayoutKind = "module-root" | "new" | "flat";
 /** 模块一侧的可缺省组合：两侧皆无不是模块（设计 C-6） */
 export interface ModuleSides {
 	name: string
-	/** 后端源码目录 `<project>/src/<name>/api`（无此侧为 undefined） */
+	/** 后端源码目录（`src/<name>/api` 或聚合容器 `src/app/api/<name>`；无此侧为 undefined） */
 	apiSrc?: string
 	/** 前端源码目录 `<project>/src/<name>/web`（无此侧为 undefined） */
 	webSrc?: string
@@ -82,13 +85,44 @@ function isFile(p: string): boolean {
  * 坏目录只在 module-root 被判定为当前布局后才报错（见 resolveLayout），
  * 否则一个恰好带 `src/utils/api/` 的历史工程会被误伤。
  */
+/** 递归扫描时跳过的目录名（产物 / 依赖 / 生成物，均不可能承载模块根） */
+const SCAN_SKIP_DIRS = new Set(["node_modules", "dist", "build", "__client", ".cache", ".git"]);
+
+/**
+ * 收集一个容器目录下的后端模块根。
+ *
+ * 两种形态并存（oj 的 `--module-root` 支持任意深度）：
+ *   · `<container>/api/manifest.yaml`          —— 模块根在 api 自身（src/<name>/api）
+ *   · `<container>/api/<name>/manifest.yaml`   —— 聚合容器下的子模块（src/app/api/system）
+ *
+ * 后者用于「一个应用目录承载多个业务域」：src/app 的 web 侧是多根聚合模块，
+ * api 侧按业务域分成 system / notification / … 各自仍是独立模块（模块名 = 目录名
+ * = URL 前缀，故不能并成一个 app 模块）。命中模块根即停，不再往 api 内部递归。
+ */
+function collectApiRoots(container: string, out: string[]): void {
+	const apiDir = path.join(container, "api");
+	if (isFile(path.join(apiDir, "manifest.yaml"))) {
+		out.push(apiDir);
+		return;
+	}
+	if (!isDir(apiDir))
+		return;
+	for (const ent of fs.readdirSync(apiDir, { withFileTypes: true })
+		.filter(e => e.isDirectory() && !e.name.startsWith(".") && !SCAN_SKIP_DIRS.has(e.name))
+		.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))) {
+		if (isFile(path.join(apiDir, ent.name, "manifest.yaml")))
+			out.push(path.join(apiDir, ent.name));
+	}
+}
+
 function scanModuleRoot(projectRoot: string): { modules: ModuleSides[], broken: string[] } | null {
 	const srcDir = path.join(projectRoot, "src");
 	if (!isDir(srcDir))
 		return null;
 
-	const modules: ModuleSides[] = [];
+	const byName = new Map<string, ModuleSides>();
 	const broken: string[] = [];
+	const apiOwners = new Map<string, string>();
 	// 按名字排序：readdir 的顺序取决于文件系统与创建历史（同一份源码在不同机器上可能不同），
 	// 而枚举顺序会进入构建顺序与产物内容——不排序则「同布局两次构建 sha256 相等」无法保证。
 	const entries = fs.readdirSync(srcDir, { withFileTypes: true })
@@ -96,22 +130,41 @@ function scanModuleRoot(projectRoot: string): { modules: ModuleSides[], broken:
 		.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
 	for (const ent of entries) {
 		const dir = path.join(srcDir, ent.name);
-		const apiDir = path.join(dir, "api");
 		const webDir = path.join(dir, "web");
-		const hasApi = isFile(path.join(apiDir, "manifest.yaml"));
 		const hasWeb = isFile(path.join(webDir, "entry.ts"));
-		if (!hasApi && !hasWeb) {
+		const apiRoots: string[] = [];
+		collectApiRoots(dir, apiRoots);
+		if (!hasWeb && apiRoots.length === 0) {
 			// 只把「有 api/ 或 web/ 子目录但缺标记」算坏目录；纯共享库目录（无两者）静默跳过
-			if (isDir(apiDir) || isDir(webDir))
+			if (isDir(path.join(dir, "api")) || isDir(webDir))
 				broken.push(ent.name);
 			continue;
 		}
-		modules.push({
-			name: ent.name,
-			apiSrc: hasApi ? apiDir : undefined,
-			webSrc: hasWeb ? webDir : undefined,
-		});
+		if (hasWeb)
+			byName.set(ent.name, { name: ent.name, webSrc: webDir });
+		for (const apiDir of apiRoots) {
+			// 模块名：平铺 src/system/api → system（api 的父目录）；
+			// 聚合 src/app/api/system → system（api 下方那层目录本身）。
+			const name = path.basename(apiDir) === "api"
+				? path.basename(path.dirname(apiDir))
+				: path.basename(apiDir);
+			const prev = apiOwners.get(name);
+			if (prev) {
+				throw new Error(
+					`[ojm] 后端模块名重复：${name} 同时出现在 ${path.relative(projectRoot, prev)} 与 `
+					+ `${path.relative(projectRoot, apiDir)}。模块名即 URL 前缀，必须唯一——`
+					+ "删掉旧布局目录（或改名）后重试。",
+				);
+			}
+			apiOwners.set(name, apiDir);
+			const hit = byName.get(name);
+			if (hit)
+				hit.apiSrc = apiDir;
+			else
+				byName.set(name, { name, apiSrc: apiDir });
+		}
 	}
+	const modules = [...byName.values()].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
 	return { modules, broken };
 }
 
@@ -244,7 +297,7 @@ export function legacyApiModuleRoots(projectRoot: string): ApiModuleRoot[] {
  * 为什么不直接 walk `apiModulesSrc(layout)`：module-root 布局的树根是 `src`，模块的
  * api 侧在 `<src>/<name>/api`，中间那层 `api` 是**布局分隔符、不是路由段**。拿 `src`
  * 当扫描根会双重出错——路由镜像多出 `api` 段（`system/api/users` ≠ 真实 `system/users`），
- * 且 `src/<name>/web/__client/api.ts` 这种前端生成物也会被当 handler 扫进来。
+ * 且 `src/<name>/web/__client/index.ts` 这种前端生成物也会被当 handler 扫进来。
  *
  * module-root → 按 `<name>/api/manifest.yaml` 判模块（与 build 同源，name 取 manifest）；
  * 历史布局    → `<project>/api/src` 的一级目录即模块。
@@ -267,9 +320,12 @@ export function moduleDir(layout: ProjectLayout, name: string): string {
  * 历史布局为 `<project>/api/src/<name>`——不在 modulesSrc 之下，必须走 projectRoot。
  */
 export function apiSrcOf(layout: ProjectLayout, name: string): string {
-	return layout.kind === "module-root"
-		? path.join(layout.modulesSrc, name, "api")
-		: path.join(layout.projectRoot, "api", "src", name);
+	if (layout.kind !== "module-root")
+		return path.join(layout.projectRoot, "api", "src", name);
+	// 聚合容器（src/app/api/<name>）与平铺（src/<name>/api）并存，以扫描结果为准；
+	// 找不到时回落旧口径，保证报错信息里的路径仍指向「本该在的位置」。
+	const hit = scanModules(layout).find(m => m.name === name)?.apiSrc;
+	return hit ?? path.join(layout.modulesSrc, name, "api");
 }
 
 /**

package/src/lifecycle/__tests__/manifest-contract.test.ts

@@ -1,4 +1,4 @@
-import type { InstallContext } from "../../../templates/src/_platform/api/_lifecycle/steps/preflight";
+import type { InstallContext } from "../../../templates/src/app/api/_platform/_lifecycle/steps/preflight";
 
 // BDD：bundle 级 manifest.yaml 契约校验（P1-11，C2 规则构建列）。
 // 规则真源：docs/prd/solution/202610171254-lifecycle-manifest-contract.md（C2-01~33 构建列，§4.1 矩阵）；
@@ -13,7 +13,7 @@ import { describe, expect, it } from "vitest";
 import { parse } from "yaml";
 // 跨端引用（双端一致钉）：被测实现同仓分居两运行时（计划 §1「两运行时取舍」），
 // 测试直接互调，比「两套件各读同一夹具」更强——漂移即本文件红。
-import { preflight } from "../../../templates/src/_platform/api/_lifecycle/steps/preflight";
+import { preflight } from "../../../templates/src/app/api/_platform/_lifecycle/steps/preflight";
 import { checkLocalesComplete, checkTablesAgainstSchema, parseManifest, RESERVED_NAMES, reservedNameSuggestions, validateContract } from "../../manifest-contract";
 
 const FIXTURES = join(dirname(fileURLToPath(import.meta.url)), "fixtures");

package/src/market/__tests__/bootstrap.test.ts

@@ -68,7 +68,7 @@ describe("given 一个装了 oj 二进制的源工程 When 自举隔离站点",
 
 		const site = await bootstrapIsolatedSite({ projectRoot: src, starter });
 
-		expect(existsSync(join(site.root, "src", "_platform", "api", "seed.sql"))).toBe(true);
+		expect(existsSync(join(site.root, "src", "app", "api", "_platform", "seed.sql"))).toBe(true);
 		expect(existsSync(join(site.root, "bin", "oj"))).toBe(true);
 		expect(existsSync(join(site.root, "bin", "plugins", "auth.wasm"))).toBe(true);
 		expect(site.root).not.toBe(src);

package/src/site.ts

@@ -21,7 +21,7 @@ export function tenantHeaders(): Record<string, string> {
 	return { [TENANT_HEADER]: DEFAULT_TENANT };
 }
 
-/** 任务记录（线形状镜像；真源 templates/src/_platform/api/_lifecycle/types.ts:65，客户端不 import 模板内部） */
+/** 任务记录（线形状镜像；真源 templates/src/app/api/_platform/_lifecycle/types.ts:65，客户端不 import 模板内部） */
 export interface TaskRecord {
 	/**
 	 * 记录 schema 版本（P2-10 线形状镜像）：缺省（undefined）=旧记录=v1 语义照常渲染；

package/templates/README.md

@@ -6,30 +6,32 @@
 
 ```bash
 pnpm install
-pnpm dev        # 开发：前端 devServer + oj 后端（src/*/api 保存即热更）
+pnpm dev        # 开发：前端 devServer + oj 后端（src 下 api.ts 保存即热更）
 pnpm build      # 构建：oj build + 前端全站合并到 dist/web
 pnpm preview    # 预览：oj migrate + server（release 产物）
 ```
 
-登录账号：`admin` / `aA123456`（见 `src/_platform/api/seed.sql`）。
+登录账号：`superadmin` / `aA123456`（四个内置角色账号见 `src/app/api/_platform/seed.sql`）。
 
-## 目录（一目录 = 一个模块）
+## 目录（一个 `src/app` 装下整个应用）
 
 ```
-config.yaml              站点/数据库/租户配置（init 现场签发证书到 config/）
-src/<name>/api/          后端模块（目录镜像路由：src/<name>/api/<路径>/api.ts）
-src/<name>/web/          前端模块（entry.ts 是入口；页面 / locales / __client 同目录）
-src/app/web/             框架内置页面聚合模块（多根：/home /login /personal-center /notification /system）
-src/oj-market/web/       解决方案市场（第一方能力，独立模块，删目录即下线）
-dist/api/                oj build 后端产物
-dist/web/                站点产物（shell + modules + modules.json）
-bin/                     oj 二进制（init 解压，不入库）
+config.yaml                  站点/数据库/租户配置（init 现场签发证书到 config/）
+src/app/api/<name>/          后端模块（模块名 = URL 前缀；目录镜像：<路径>/api.ts）
+src/app/web/                 前端聚合模块（多根，一个 entry.ts 挂 /home /login /…）
+  <root>/                    每个根：routes.ts + pages/ + locales/ + __client/
+src/oj-market/web/           解决方案市场（第一方能力，独立模块，删目录即下线）
+dist/api/                    oj build 后端产物
+dist/web/                    站点产物（shell + modules + modules.json）
+bin/                         oj 二进制（init 解压，不入库）
 ```
 
-`src/app/web` 是一个**多根模块**：一个 `entry.ts` 里挂五个顶层路由，各根按
-`handle.order` 排菜单（与拆分时逐项一致），页面按根分目录
-（`<root>/routes.ts` + `pages/` + `__client/`）。新增业务页面时建议单独建模块
-（`pnpm exec ojm new <name>`），不要往聚合模块里塞。
+- **后端**按业务域分模块：`_platform` / `auth` / `notification` / `personal-center` /
+  `system` / `web`，各自是独立 oj 模块（模块名即 `/api/<name>` 前缀），只是统一收在
+  `src/app/api` 下——顶层不再散落同名目录。
+- **前端** `src/app/web` 是一个**多根模块**：一个 `entry.ts` 里挂六个顶层路由，各根按
+  `handle.order` 排菜单，页面按根分目录。新增业务页面时建议单独建模块
+  （`pnpm exec ojm new <name>`），不要往聚合模块里塞。
 
 ## 契约与 `__client`
 
@@ -38,16 +40,19 @@ bin/                     oj 二进制（init 解压，不入库）
 
 ```bash
 bin/oj openapi -c config.yaml --module-root src -b /api -o openapi.json   # 重产契约
-pnpm exec ojm api                                                         # 重生成 */web/*/__client
+pnpm exec ojm api                                                         # 重生成 __client
 ```
 
+生成物入口是 `__client/index.ts`（**不是 `api.ts`**：oj dev 会把模块目录下的
+`api.ts` 当路由扫描）。页面里用 `from "../__client"` 导入。
+
 多根聚合模块的 client 归属由 `web.config.ts` 的 `clientOwners` 决定（`system → app`），
-生成物落 `src/app/web/system/__client`，与页面同级——页面相对导入 `../../__client` 不用改。
+生成物落 `src/app/web/system/__client`，与页面同级——页面相对导入不用改。
 `ojm api --check` 可对账漂移（零漂移为发布门禁）。
 
 ## 注意
 
-- 改 `src/*/api` 下的 api.ts 保存即生效；**新增/删除模块目录、改
+- 改 `src/app/api/**/api.ts` 保存即生效；**新增/删除模块目录、改
   schema/migrations/config.yaml 需重启 `ojm dev`**（oj 热更边界）。
 - 后端开发请用 `/oj-api-dev` skill（`.claude/skills/oj-api-dev/`），手册按章节按需读。
 - `config/` 下的证书为 init 现场签发的本地 dev 证书，不构成信任边界；
@@ -55,7 +60,7 @@ pnpm exec ojm api                                                         # 重
 
 ## 排障 / 常见问题
 
-- **`pnpm dev` / `pnpm build` 报 `Could not resolve "../../__client/api"`**
+- **`pnpm dev` / `pnpm build` 报 `Could not resolve "../../__client"`**
   对应根的 `__client` 缺失——它是 `ojm api` 的生成物。在工程根跑一次即可补齐：
 
   ```bash
@@ -73,8 +78,13 @@ pnpm exec ojm api                                                         # 重
   不能手改、也不入库——它是生成物，下次 `ojm api` 会覆盖。改接口就改 handler 的
   `.schema`/`.response`，再跑上面的命令刷新。
 
+- **从旧版本升级（`__client/api.ts`）**
+  0.2.54 起入口改名 `index.ts`（`api.ts` 会被 oj dev 当路由扫描）。重跑一次
+  `pnpm exec ojm api` 即可：新文件写入、旧 `api.ts` 自动删除；页面导入改为
+  `from "../__client"`。
+
 - **`pnpm dlx @oj-module/cli@latest init` 生成的脚手架缺模块 / 看起来很旧**
-  pnpm dlx 会按首次解析到的版本**缓存** CLI 可执行文件。排查：`ls src` 看是否缺预期模块。
+  pnpm dlx 会按首次解析到的版本**缓存** CLI 可执行文件。排查：`ls src/app/api` 看是否缺预期模块。
   解决：清掉 dlx 缓存后显式指定版本重跑——
 
   ```bash

package/templates/init.include.yaml

@@ -40,7 +40,7 @@ include:
   - src/styles.css
   # 后端 typecheck 工程（package.json 的 typecheck:api 指向它）；只收后端、排除 web
   - src/tsconfig.json
-  # —— 后端：配置 / 种子 / 测试 / 默认模块（模块源码在 src/<name>/api）——
+  # —— 后端：配置 / 种子 / 测试 / 默认模块（模块源码在 src/app/api/<模块>）——
   - config.yaml
   - .ojm-api-exempt.json
   - seed.mysql.sql
@@ -71,8 +71,12 @@ include:
   - tests/rbac-solution-perms.spec.ts
   - tests/rbac-tables.spec.ts
   - tests/rbac-users.spec.ts
+  # 角色页展示层过滤 superadmin（后端 listRoles 仍返回；页面源码随 src/app/web/system 下发）
+  - tests/roles-page.spec.ts
   - tests/seed-role-accounts.spec.ts
-  # 企微连接器与组织同步：源码本就分发（src/auth/api），对应回归也必须跟着走，
+  # 用户页行级门禁：只有 superadmin 能改 superadmin 账号（后端 assertCanManageTarget 的另一面）
+  - tests/users-page.spec.ts
+  # 企微连接器与组织同步：源码本就分发（src/app/api/auth），对应回归也必须跟着走，
   # 否则用户工程升级后改配置/换套件时没有任何本地自检手段。
   - tests/wecom-admin.spec.ts
   - tests/wecom-client-timeout.spec.ts
@@ -95,15 +99,19 @@ include:
   - tests/lifecycle/uninstall.spec.ts
   - tests/lifecycle/verify-checks.spec.ts
   - tests/lifecycle/verify-report.spec.ts
-  - src/_platform/api
-  - src/auth/api
-  - src/notification/api
-  - src/personal-center/api
-  - src/system/api
-  - src/web/api
+  # 框架内置后端全部收在 src/app/api/<模块>（模块名 = URL 前缀，故仍是独立模块）。
+  # home 的 api 是 demo-only 不进脚手架（见下），其余全部下发。
+  - src/app/api/_platform
+  - src/app/api/auth
+  - src/app/api/notification
+  - src/app/api/personal-center
+  - src/app/api/system
+  - src/app/api/web
   # —— web 前端模块 ——
-  - src/_platform/web
-  - src/auth/web
+  # 纯 client 归属目录（无页面模块）：_platform 的生成物被 oj-market 引用，
+  # auth / web 的是各自后端契约的配套产物，一并下发保证 ojm api --check 开箱即过。
+  - src/app/web/_platform
+  - src/app/web/auth
   # 框架内置页面聚合为一个多根模块（首页/登录/个人中心/通知/系统管理）。
   # home 只列 routes/locales/pages：其 api 模块是 demo-only 不进脚手架，__client
   # 留着会指向不存在的端点（见顶部说明），故逐子路径收录而不是整棵 src/app/web。
@@ -125,4 +133,4 @@ include:
   - src/oj-market/web/locales
   - src/oj-market/web/pages
   - src/oj-market/web/utils
-  - src/web/web
+  - src/app/web/web