@oj-module/cli 0.2.54 → 0.2.57

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/bundle.ts

@@ -308,6 +308,16 @@ async function assembleBundle(projectRoot: string, layout: ProjectLayout, plan:
 			}
 			fs.mkdirSync(path.join(root, "web", "modules"), { recursive: true });
 			fs.cpSync(ownWeb, path.join(root, "web", "modules", name), { recursive: true });
+			// R1 数据源随包（计划 docs/plans/20261103-0948）：安装期角色 title 解析读
+			// <包>/web/modules/<name>/locales/<lang>.json——构建产物不含 locales（源码 JSON
+			// 被 vite 内联进 JS chunk），故从源码树复制双语；目录不存在（纯后端段缺 locales）静默跳过。
+			for (const lang of ["zh-CN", "en-US"]) {
+				const src = path.join(webSrcOf(layout, name), "locales", `${lang}.json`);
+				if (fs.existsSync(src)) {
+					fs.mkdirSync(path.join(root, "web", "modules", name, "locales"), { recursive: true });
+					fs.copyFileSync(src, path.join(root, "web", "modules", name, "locales", `${lang}.json`));
+				}
+			}
 			const web = m.web as Record<string, unknown>;
 			for (const rel of [web.entry, ...(Array.isArray(web.css) ? web.css : [])]) {
 				if (typeof rel === "string" && !fs.existsSync(path.join(root, "web", rel))) {
@@ -365,6 +375,57 @@ export async function buildBundle(projectRoot: string, opts: { out?: string, nam
 	return results;
 }
 
+/**
+ * `ojm build` 末尾的用户方案摘要（2026-11-03，计划 docs/plans/20261103-0925）：
+ * 明确回答「我的方案构建进了吗、能不能打包」。判定口径与 resolveContractTargets 同源
+ * （模块级契约 ∪ 根契约，减内置名单）——摘要里列出的就是 --bundle 将要打包的那批。
+ * 只报告不裁决：不调 resolveLayout（构建末尾不因摘要崩溃），log 可注入供测试断言。
+ */
+export function summarizeBuiltSolutions(projectRoot: string, built: readonly { name: string, version: string }[], log: (line: string) => void = console.log): void {
+	const builtin = readBuiltinModules(projectRoot);
+	const rootSolution = path.join(projectRoot, "solution.yaml");
+	const rootManifest = path.join(projectRoot, "manifest.yaml");
+	const rootContract = fs.existsSync(rootSolution) ? rootSolution : fs.existsSync(rootManifest) ? rootManifest : undefined;
+	const rootName = rootContract ? peekContractName(rootContract) : undefined;
+
+	// 用户方案候选：模块级契约（非内置）∪ 根契约 name（按名去重——「根压 src」只是打包取哪份契约，摘要里是同一个方案）
+	const names = new Set<string>();
+	for (const c of collectModuleContracts(projectRoot)) {
+		if (!builtin.has(c.moduleDir!))
+			names.add(c.moduleDir!);
+	}
+	if (rootName !== undefined && !builtin.has(rootName))
+		names.add(rootName);
+
+	const builtByName = new Map(built.map(b => [b.name, b]));
+	if (names.size === 0) {
+		log("[ojm] 用户方案 0 份（ojm new <name> 创建后即可 ojm build --bundle 打包）");
+	}
+	else {
+		const all = [...names].sort();
+		const ok = all.filter(n => builtByName.has(n));
+		const missing = all.filter(n => !builtByName.has(n));
+		const builtList = ok.map(n => `${n}@${builtByName.get(n)!.version}`).join("、") || "无";
+		if (missing.length === 0)
+			log(`[ojm] 用户方案 ${all.length} 份已构建：${builtList}（ojm build --bundle 打包）`);
+		else
+			log(`[ojm] 用户方案 ${all.length} 份中 ${ok.length} 份已构建：${builtList}；未构建：${missing.join("、")}（查 web.config.ts 登记/enabled）`);
+	}
+
+	const builtinBuilt = built.filter(b => builtin.has(b.name));
+	if (builtinBuilt.length > 0)
+		log(`[ojm] 框架自带模块 ${builtinBuilt.length} 份已构建（不参与用户打包）`);
+
+	// module-root 口径（src/ 树在即适用；flat/new 工程模块不在 src/）：非内置且无契约的模块不会被打包——提前点名，别等 --bundle 才发现
+	if (fs.existsSync(path.join(projectRoot, "src"))) {
+		for (const b of built) {
+			if (builtin.has(b.name) || names.has(b.name))
+				continue;
+			log(`[ojm] ⚠️ 模块 ${b.name}@${b.version} 缺方案契约（src/${b.name}/solution.yaml），不会被打包`);
+		}
+	}
+}
+
 /**
  * C2-31 分层核对：模块级 manifest 仅 oj 原生键，且 name/version 与 bundle 级逐一相等
  * （oj 启动强校验同源）。

package/src/cli.ts

@@ -135,7 +135,10 @@ function makeAction(def: HelpEntry, projectRoot: string, lang: Lang, exit: (code
 				}
 				const { buildBackend, buildModules } = await import("./build");
 				await buildBackend(projectRoot);
-				await buildModules(projectRoot, { mergeSite: true });
+				const built = await buildModules(projectRoot, { mergeSite: true });
+				// 用户方案摘要（计划 20261103-0925）：构建末尾点名「我的方案」是否进构建、能否打包
+				const { summarizeBuiltSolutions } = await import("./bundle");
+				summarizeBuiltSolutions(projectRoot, built);
 			};
 		case "new":
 			return async (name: string | undefined, extra: string[] = [], opts: { layout?: string, api?: boolean } = {}) => {

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

@@ -21,7 +21,7 @@ import { BUILTIN_LIST_FILE, writeBuiltinList } from "./builtin";
 import { resolveCertDir, resolveConfigPath } from "./layout";
 import { probeOjCaps } from "./oj-caps";
 import { mintDevCert } from "./oj-cert";
-import { isSupportedOjVersion, MIN_OJ_VERSION, resolveOjBin, vendorCommand } from "./vendor";
+import { isSupportedOjVersion, MIN_OJ_VERSION, resolveOjBin, syncOjDevkit, vendorCommand } from "./vendor";
 import { readHostVersions } from "./versions";
 
 export interface InitOptions {
@@ -167,25 +167,16 @@ export async function initProject(destDir: string, opts: InitOptions = {}): Prom
 	//      oj 不可用/不支持 secret → 保留明文并告警（init 不因加密失败而失败）
 	await sealJwtSecret(destDir, report, opts.seal);
 
-	// 4) devkit 分发：agent skill + 全局类型
-	const devkit = path.join(binDir, "devkit");
-	if (fs.existsSync(path.join(devkit, "SKILL.md"))) {
-		const skillDir = path.join(destDir, ".claude/skills/oj-api-dev");
-		fs.mkdirSync(skillDir, { recursive: true });
-		for (const name of ["SKILL.md", "api-manual.md"])
-			copyIfAbsent(path.join(devkit, name), path.join(skillDir, name), report);
-		// v0.1.82 起 devkit 新增两份专题指南（api-manual/SKILL 均引用它们）：
-		// SQL 构造器能力矩阵/方言差异、oj test L1 测试指南。它们是**增量文档**、
-		// 不影响 ojm 运行，故「有则拷、无则记跳过」——bin/devkit 来自用户本地
-		// oj 版本（MIN_OJ_VERSION 只钉到 0.1.73），旧版 devkit 没有这两个文件，
-		// 为两份文档把整个 init 打挂不值当（用户升 oj 后重跑 init 即补上）。
-		for (const name of ["sql-builder-guide.md", "oj-test-guide.md"])
-			copyIfPresent(path.join(devkit, name), path.join(skillDir, name), report);
-		copyIfAbsent(path.join(devkit, "global.d.ts"), path.join(destDir, "global.d.ts"), report);
-	}
-	else {
+	// 4) devkit 分发：agent skill（与 vendor 同一同步出口 syncOjDevkit：bin/devkit 全量
+	//    .md **覆盖**进 .claude/skills/oj-api-dev——文档随 oj 版本同步，见计划 20261103-1020）
+	//    + 全局类型（模板已落则 copyIfAbsent 跳过，模板变体优先、用户可编辑）
+	const devkitStatus = syncOjDevkit(destDir, binDir);
+	if (devkitStatus.ok)
+		report.created.push(`.claude/skills/oj-api-dev（oj devkit 文档已同步 ${devkitStatus.files.length} 个文件）`);
+	else
 		report.skipped.push(".claude/skills/oj-api-dev（bin/devkit 缺失，跳过）");
-	}
+	if (fs.existsSync(path.join(binDir, "devkit", "global.d.ts")))
+		copyIfAbsent(path.join(binDir, "devkit", "global.d.ts"), path.join(destDir, "global.d.ts"), report);
 
 	// 4b) ojm 模块开发 skill 分发：从 cli 包内置 devkit（prepack 同步的
 	//     docs/devkit）拷到 .claude/skills/ojm-module-dev/；已存在则幂等跳过。
@@ -197,7 +188,8 @@ export async function initProject(destDir: string, opts: InitOptions = {}): Prom
 		// 业务工程拿到模板后自助完成对接要用，不能只留本仓：
 		//   · `wecom-daikaifa.md`  企业微信代开发（服务商模板）：凭据清单 + 用户/开发/部署三视角；
 		//   · `wecom-internal-app.md` 企业内部应用（自建）：五项 corp 凭据 + 验证并接入 + 共存。
-		for (const name of ["SKILL.md", "manual.md", "README.md", "wecom-daikaifa.md", "wecom-internal-app.md"])
+		//   · `publish-walkthrough.md` 方案包发布全流程（新手照做版）：打包/签名/CDN/安装一条链。
+		for (const name of ["SKILL.md", "manual.md", "README.md", "wecom-daikaifa.md", "wecom-internal-app.md", "publish-walkthrough.md"])
 			copyIfAbsent(path.join(cliDevkit, name), path.join(ojmSkillDir, name), report);
 	}
 	else {
@@ -240,15 +232,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 +410,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;
@@ -475,21 +475,6 @@ function copyIfAbsent(src: string, dest: string, report: InitReport): void {
 	report.created.push(path.relative(process.cwd(), dest) || path.basename(dest));
 }
 
-/**
- * 同 copyIfAbsent，但**源缺失**时记一条跳过而非抛错。
- *
- * 用于从 bin/devkit 拷第三方版本化内容（两份专题指南）：devkit 随用户本地 oj
- * 版本而变，旧版没有新文件属正常版本 skew，不是安装包损坏——缺了只少份文档，
- * 不该让 init 失败。源在而目标已存在仍走 copyIfAbsent 的幂等跳过。
- */
-function copyIfPresent(src: string, dest: string, report: InitReport): void {
-	if (!fs.existsSync(src)) {
-		report.skipped.push(`${path.basename(src)}（bin/devkit 无此文件，跳过）`);
-		return;
-	}
-	copyIfAbsent(src, dest, report);
-}
-
 /**
  * 新工程 .gitignore：不存在则生成；已存在则幂等跳过（用户规则永不覆盖）。
  *

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__/bundle-summary.test.ts

@@ -0,0 +1,106 @@
+// BDD：`ojm build` 末尾用户方案摘要（计划 docs/plans/20261103-0925-ojm-build-solution-summary.md）。
+// 摘要只报告不裁决：判定口径与 --bundle 打包对象同源（模块级契约 ∪ 根契约，减内置名单）；
+// log 注入断言，夹具只摆契约/名单/构建结果三样，不需要真实工程结构。
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { summarizeBuiltSolutions } from "../../bundle";
+
+let project: string;
+let lines: string[];
+
+beforeEach(() => {
+	project = mkdtempSync(join(tmpdir(), "ojm-build-summary-"));
+	lines = [];
+});
+
+afterEach(() => {
+	rmSync(project, { recursive: true, force: true });
+});
+
+/** 模块级契约：src/<name>/solution.yaml（+ web/entry.ts 保持真实模块目录形态） */
+function moduleContract(name: string): void {
+	const dir = join(project, "src", name);
+	mkdirSync(join(dir, "web"), { recursive: true });
+	writeFileSync(join(dir, "web", "entry.ts"), "export default {};\n");
+	writeFileSync(join(dir, "solution.yaml"), `name: ${name}\nversion: 1.0.0\nsummary: ${name}\n`);
+}
+
+function builtinList(names: string[]): void {
+	mkdirSync(join(project, "src"), { recursive: true });
+	writeFileSync(join(project, "src", ".ojm-builtin.json"), JSON.stringify({ modules: names }));
+}
+
+function summaryOf(built: { name: string, version: string }[]): string[] {
+	summarizeBuiltSolutions(project, built, l => lines.push(l));
+	return lines;
+}
+
+describe("summarizeBuiltSolutions", () => {
+	it("场景：全部构建成功 → 一行列出可打包方案 + 一行列出内置模块", () => {
+		moduleContract("crm");
+		moduleContract("erp");
+		builtinList(["home", "login"]);
+		const out = summaryOf([
+			{ name: "crm", version: "1.0.0" },
+			{ name: "erp", version: "0.2.0" },
+			{ name: "home", version: "9.9.9" },
+			{ name: "login", version: "9.9.9" },
+		]);
+		expect(out.some(l => l.includes("用户方案 2 份已构建") && l.includes("crm@1.0.0") && l.includes("erp@0.2.0"))).toBe(true);
+		expect(out.some(l => l.includes("框架自带模块 2 份已构建"))).toBe(true);
+	});
+
+	it("场景：方案没进构建 → 点名未构建方案与排查方向", () => {
+		moduleContract("crm");
+		moduleContract("erp");
+		builtinList(["home"]);
+		const out = summaryOf([
+			{ name: "crm", version: "1.0.0" },
+			{ name: "home", version: "9.9.9" },
+		]);
+		expect(out.some(l => l.includes("crm@1.0.0"))).toBe(true);
+		expect(out.filter(l => l.includes("erp")).join("\n")).toContain("未构建");
+	});
+
+	it("场景：零用户方案 → 提示 ojm new", () => {
+		moduleContract("home");
+		builtinList(["home"]);
+		const out = summaryOf([{ name: "home", version: "9.9.9" }]);
+		expect(out.some(l => l.includes("用户方案 0 份") && l.includes("ojm new"))).toBe(true);
+	});
+
+	it("场景：非内置模块缺契约 → 警告不会被打包", () => {
+		builtinList(["home"]);
+		const out = summaryOf([
+			{ name: "foo", version: "0.1.0" },
+			{ name: "home", version: "9.9.9" },
+		]);
+		expect(out.some(l => l.includes("缺方案契约") && l.includes("foo@0.1.0"))).toBe(true);
+	});
+
+	it("场景：旧单方案工程（根契约、无 src/ 树）→ 列出根契约方案，不误报缺契约", () => {
+		writeFileSync(join(project, "manifest.yaml"), "name: demo-solution\nversion: 0.1.0\nsummary: 旧写法\n");
+		const out = summaryOf([{ name: "demo-solution", version: "0.1.0" }]);
+		expect(out.some(l => l.includes("用户方案 1 份已构建") && l.includes("demo-solution@0.1.0"))).toBe(true);
+		expect(out.every(l => !l.includes("缺方案契约"))).toBe(true);
+	});
+
+	it("场景：新脚手架形态（内置集中 src/app，无用户方案）→ 0 份提示，src/app 不被误判", () => {
+		// 脚手架 init 后：src/ 下只有 app（平台聚合树，无契约）与 oj-market，均在内置名单
+		mkdirSync(join(project, "src", "app", "web"), { recursive: true });
+		writeFileSync(join(project, "src", "app", "web", "entry.ts"), "export default {};\n");
+		mkdirSync(join(project, "src", "oj-market", "web"), { recursive: true });
+		writeFileSync(join(project, "src", "oj-market", "web", "entry.ts"), "export default {};\n");
+		builtinList(["app", "oj-market", "_platform", "auth", "notification", "personal-center", "system", "web"]);
+		const out = summaryOf([
+			{ name: "app", version: "0.2.56" },
+			{ name: "oj-market", version: "0.2.56" },
+		]);
+		expect(out.some(l => l.includes("用户方案 0 份") && l.includes("ojm new"))).toBe(true);
+		expect(out.some(l => l.includes("框架自带模块 2 份已构建"))).toBe(true);
+		expect(out.every(l => !l.includes("缺方案契约"))).toBe(true);
+	});
+});