@oj-module/cli 0.2.50 → 0.2.54

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} 条`);
 }

package/src/shared-deps.ts

@@ -20,6 +20,18 @@ export interface SharedDepEntry {
 	asset?: string
 	/** 硬共享：模块不得自带 */
 	hard: boolean
+	/**
+	 * 软共享但「不进宿主首屏」：宿主 shell 不预构建该资产、importmap 不列该键，
+	 * 模块若 import 它则自行打包进模块产物（设计文档 §4.3 的「软共享缺席→模块自带
+	 * 副本兜底」语义）。用于**仅模块使用、宿主与共享 chunk 永不 import**的重型依赖
+	 * （编辑器 / 图表 / Markdown / 拖拽 …），避免把它们 5~6MB 的体量无谓铺进
+	 * shell-dist 并要求公开链路多传一堆文件。宿主侧有真实 import 的共享依赖
+	 * （antd / pro-components / icons 内部依赖的 motion / react-jss / dayjs /
+	 * zustand 等）绝不能标 bundle —— 否则会被 antd 等共享 chunk 经 importmap 解析
+	 * 不到而 404。判定依据：宿主 host.tsx + runtime.js 的传递 import 图，以及
+	 * antd/pro-components/icons 的传递依赖图，都不含这些说明符。
+	 */
+	bundle?: boolean
 }
 
 export const SHARED_DEPS: SharedDepEntry[] = [
@@ -58,7 +70,7 @@ export const SHARED_DEPS: SharedDepEntry[] = [
 	 *     scopes 多版本共存兜底（C7）」——缺席时模块可自带副本而不硬失败。
 	 *     代价：多副本会重复约 5.4 MB 资产，故 scopes 只作兜底、默认仍走宿主。
 	 */
-	{ specifier: "@plane/editor", asset: "editor", hard: false },
+	{ specifier: "@plane/editor", asset: "editor", hard: false, bundle: true },
 	// 注：@rc-component/form（antd 6 Form 底层）曾尝试单例化以修 my-profile
 	// 崩溃（React #130），假说未证实——多副本并非充分根因，已回退；见
 	// docs/prd/202609010056-playground-full-modules-plan.md 差异项 D2。
@@ -108,10 +120,10 @@ export const SHARED_DEPS: SharedDepEntry[] = [
 	{ specifier: "dayjs/plugin/weekday", asset: "dayjs-plugin-weekday", hard: false },
 	{ specifier: "dayjs/plugin/weekOfYear", asset: "dayjs-plugin-weekOfYear", hard: false },
 	{ specifier: "dayjs/plugin/weekYear", asset: "dayjs-plugin-weekYear", hard: false },
-	{ specifier: "echarts", asset: "echarts", hard: false },
-	{ specifier: "echarts/charts", asset: "echarts-charts", hard: false },
-	{ specifier: "echarts/features.js", asset: "echarts-features", hard: false },
-	{ specifier: "echarts-for-react", asset: "echarts-for-react", hard: false },
+	{ specifier: "echarts", asset: "echarts", hard: false, bundle: true },
+	{ specifier: "echarts/charts", asset: "echarts-charts", hard: false, bundle: true },
+	{ specifier: "echarts/features.js", asset: "echarts-features", hard: false, bundle: true },
+	{ specifier: "echarts-for-react", asset: "echarts-for-react", hard: false, bundle: true },
 	{ specifier: "motion", asset: "motion", hard: false },
 	{ specifier: "motion/react", asset: "motion-react", hard: false },
 	{ specifier: "@dnd-kit/core", asset: "dnd-kit-core", hard: false },
@@ -127,6 +139,8 @@ export const SHARED_DEPS: SharedDepEntry[] = [
 	{ specifier: "react-error-boundary", asset: "react-error-boundary", hard: false },
 	{ specifier: "react-jss", asset: "react-jss", hard: false },
 	{ specifier: "clsx", asset: "clsx", hard: false },
+	// react-countup 只有 CJS 入口（main: build），其 require("react") 在模块自打包时会退化成
+	// 浏览器不可用的 require 桩 → 必须走宿主共享资产（shell 侧有 CJS→ESM 垫片）
 	{ specifier: "react-countup", asset: "react-countup", hard: false },
 	{ specifier: "simplebar-react", asset: "simplebar-react", hard: false },
 	{ specifier: "spin-delay", asset: "spin-delay", hard: false },
@@ -147,8 +161,8 @@ export const SHARED_DEPS: SharedDepEntry[] = [
 	 * 直接 import 它们，会命中前缀 external 但无 importmap 键 → 构建期深路径报错，
 	 * 属预期拦截（与 dayjs/plugin/* 同规则）。
 	 */
-	{ specifier: "vditor", asset: "vditor", hard: false },
-	{ specifier: "vditor/dist/index.css", asset: "vditor-index-css", hard: false },
+	{ specifier: "vditor", asset: "vditor", hard: false, bundle: true },
+	{ specifier: "vditor/dist/index.css", asset: "vditor-index-css", hard: false, bundle: true },
 ];
 
 /** 判断一个裸说明符是否命中共享表（命中主包前缀的深路径也按共享处理） */
@@ -161,7 +175,7 @@ export function isSharedDep(id: string): boolean {
  */
 export function generateShellEntries(): { name: string, pkg: string }[] {
 	return SHARED_DEPS
-		.filter(dep => dep.asset && dep.specifier !== "@oj-module/runtime")
+		.filter(dep => dep.asset && !dep.bundle && dep.specifier !== "@oj-module/runtime")
 		.map(dep => ({ name: dep.asset!, pkg: dep.specifier }));
 }
 
@@ -172,9 +186,13 @@ export function generateShellEntries(): { name: string, pkg: string }[] {
 export function generateImportmap(baseUrl = ""): Record<string, string> {
 	const map: Record<string, string> = {};
 	for (const dep of SHARED_DEPS) {
-		if (dep.asset) {
+		if (dep.asset && !dep.bundle) {
 			map[dep.specifier] = `${baseUrl}/assets/${dep.asset}.js`;
 		}
 	}
 	return map;
 }
+
+export function isPrebuiltDep(id: string): boolean {
+	return SHARED_DEPS.some(dep => !dep.bundle && (id === dep.specifier || id.startsWith(`${dep.specifier}/`)));
+}

package/src/site-base.ts

@@ -100,7 +100,7 @@ export function rewriteIndexHtml(html: string, siteBase: string | undefined, api
 		out = rewriteImportmap(out, base);
 		// 属性值：只要以单个 "/" 开头（排除 "//host"）。importmap 是脚本正文、非属性，
 		// 上一步已处理，二者不重叠。
-		out = out.replace(/(\b(?:href|src)=")(\/[^/"][^"]*|\/")/g, (_m, attr: string, url: string) =>
+		out = out.replace(/(\b(?:href|src|data-ojm-entry)=")(\/[^/"][^"]*|\/")/g, (_m, attr: string, url: string) =>
 			`${attr}${withSiteBase(url, base)}`);
 		globals.push(`window.__OJ_BASE__=${JSON.stringify(base)};`);
 	}

package/templates/README.md

@@ -6,82 +6,78 @@
 
 ```bash
 pnpm install
-pnpm dev        # 开发：前端 devServer + oj 后端（api/src 保存即热更）
+pnpm dev        # 开发：前端 devServer + oj 后端（src/*/api 保存即热更）
 pnpm build      # 构建：oj build + 前端全站合并到 dist/web
 pnpm preview    # 预览：oj migrate + server（release 产物）
 ```
 
-登录账号：`admin` / `aA123456`（见 `api/src/_platform/seed.sql`）。
+登录账号：`admin` / `aA123456`（见 `src/_platform/api/seed.sql`）。
 
-## 系统管理模块
+## 目录（一目录 = 一个模块）
 
-`web/src/system/`（用户管理 / 成员资格 / 角色权限 / 操作日志 / 站点设置 / 登录方式）
-的前端 API 客户端 `__client/` **已随模板分发**（与 auth/notification 等一致），`pnpm dev`
-开箱即用、「系统管理」菜单直接可见。
-
-`__client` 是从 `openapi.json`（模板自带，由 `api/src/system` 契约产出）生成的产物；
-契约变更后刷新一次即可：
-
-```bash
-bin/oj openapi -c config.yaml -d api/src -b /api -o openapi.json   # 重产契约
-pnpm exec ojm api                     # 重新生成 web/src/*/__client（dev 检测到 openapi.json 变化也会自动重生成）
+```
+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 解压，不入库）
 ```
 
-成员资格页仅 superadmin 可见。改了 `api/src` 的 handler `.schema`/`.response` 后重跑这两条保持同步
-（`ojm api --check` 可对账，零漂移为发布门禁）。
+`src/app/web` 是一个**多根模块**：一个 `entry.ts` 里挂五个顶层路由，各根按
+`handle.order` 排菜单（与拆分时逐项一致），页面按根分目录
+（`<root>/routes.ts` + `pages/` + `__client/`）。新增业务页面时建议单独建模块
+（`pnpm exec ojm new <name>`），不要往聚合模块里塞。
 
-## 目录
+## 契约与 `__client`
 
-```
-bin/           oj 二进制（init 解压，不入库）
-api/src/       后端模块源码（目录镜像路由：api/src/<模块>/<路径>/api.ts）
-dist/api/      oj build 产物
-web/src/   前端模块源码
-dist/web/  构建产物（完整站点）
+前端调后端一律走 `ojm api` 从 `openapi.json` 生成的 `__client/`（随模板分发，开箱即用）。
+改了 handler 的 `.schema`（入参）/ `.response`（出参）后刷新：
+
+```bash
+bin/oj openapi -c config.yaml --module-root src -b /api -o openapi.json   # 重产契约
+pnpm exec ojm api                                                         # 重生成 */web/*/__client
 ```
 
+多根聚合模块的 client 归属由 `web.config.ts` 的 `clientOwners` 决定（`system → app`），
+生成物落 `src/app/web/system/__client`，与页面同级——页面相对导入 `../../__client` 不用改。
+`ojm api --check` 可对账漂移（零漂移为发布门禁）。
+
 ## 注意
 
-- 改 `api/src` 下的 api.ts 保存即生效；**新增/删除后端模块目录、改
+- 改 `src/*/api` 下的 api.ts 保存即生效；**新增/删除模块目录、改
   schema/migrations/config.yaml 需重启 `ojm dev`**（oj 热更边界）。
-- 后端开发请用 `/oj-api-dev` skill（`.claude/skills/oj-api-dev/`），
-  手册按章节按需读。
-- `api/config.yaml` 的证书为 init 现场签发的本地 dev 证书，不构成信任边界；
+- 后端开发请用 `/oj-api-dev` skill（`.claude/skills/oj-api-dev/`），手册按章节按需读。
+- `config/` 下的证书为 init 现场签发的本地 dev 证书，不构成信任边界；
   生产环境用 oj 仓库 `oj-cert gen` 全新签发并替换公钥。
 
 ## 排障 / 常见问题
 
-- **`pnpm dev` / `pnpm build` 报 `Could not resolve "./__client/api"`**
-  某前端模块的 `entry.ts` 引用了 `web/src/<模块>/__client/api`，但该目录不存在——它是
-  `ojm api` 从 `openapi.json` 生成的产物。在工程根跑一次即可补齐：
+- **`pnpm dev` / `pnpm build` 报 `Could not resolve "../../__client/api"`**
+  对应根的 `__client` 缺失——它是 `ojm api` 的生成物。在工程根跑一次即可补齐：
 
   ```bash
-  pnpm exec ojm api      # 生成 web/src/*/__client（dev 检测到 openapi.json 变化也会自动重生成）
+  pnpm exec ojm api      # dev 检测到 openapi.json 变化也会自动重生成
   ```
 
-  改完后端 `api/src` 的契约后，重产契约再刷新：
+  改完后端契约后先重产契约再刷新：
 
   ```bash
-  bin/oj openapi -c config.yaml -d api/src -b /api -o openapi.json
+  bin/oj openapi -c config.yaml --module-root src -b /api -o openapi.json
   pnpm exec ojm api
   ```
 
 - **`__client/` 下的文件能直接改吗？**
-  不能手改、也不入库——它是生成物，下次 `ojm api` 会覆盖你的手改。需要改接口就改
-  `api/src` 的 handler `.schema`/`.response`，再跑上面的命令刷新。
-  `ojm api --check` 可对账契约与产物的漂移（零漂移为发布门禁）。
+  不能手改、也不入库——它是生成物，下次 `ojm api` 会覆盖。改接口就改 handler 的
+  `.schema`/`.response`，再跑上面的命令刷新。
 
 - **`pnpm dlx @oj-module/cli@latest init` 生成的脚手架缺模块 / 看起来很旧**
-  pnpm dlx 会按首次解析到的版本**缓存** CLI 可执行文件。若某次 `@latest` 指向的是旧版
-  （例如早于系统管理模块的 `0.1.x`），之后重跑仍可能命中旧缓存，生成的脚手架就会缺新模块、
-  模板偏旧（典型表现：`web/src` 下没有 `system` 目录）。
-  排查：`ls web/src` 看是否缺预期模块。
-  解决：清掉 dlx 缓存后重跑——
+  pnpm dlx 会按首次解析到的版本**缓存** CLI 可执行文件。排查：`ls src` 看是否缺预期模块。
+  解决：清掉 dlx 缓存后显式指定版本重跑——
 
   ```bash
   rm -rf ~/Library/Caches/pnpm/dlx        # macOS；其它平台见 pnpm 文档的 dlx-store 路径
-  # 或：pnpm dlx clear @oj-module/cli
-  pnpm dlx @oj-module/cli@<明确版本> init <工程名> --yes   # 显式指定版本最稳
+  pnpm dlx @oj-module/cli@<明确版本> init <工程名> --yes
   ```
-
-  养成显式带版本号（如 `@oj-module/cli@0.2.4`）的习惯，可避免 `@latest` 缓存歧义。

package/templates/init.include.yaml

@@ -20,9 +20,9 @@
 # `pnpm dev` 时忽略产物，不进发布包、也不进用户工程。守卫：
 # tests/cli/release-manifest.test.ts 逐条核对清单条目落在 tarball 内。
 #
-# 注意 web/src/{demo,home}/__client 不在清单：其 api 模块（api/src/demo、
-# api/src/home）是 demo-only 不进脚手架，client 生成物留着会指向不存在的端点，
-# 故 demo/home 只列页面源码（entry/locales/pages），不列整棵模块目录。
+# 注意 web/src/{home}/__client 不在清单：其 api 模块（api/src/home）是 demo-only
+# 不进脚手架，client 生成物留着会指向不存在的端点，故 home 只列页面源码
+# （entry/locales/pages），不列整棵模块目录。
 include:
   # —— 工程级文件 ——
   - README.md
@@ -101,17 +101,20 @@ include:
   - src/personal-center/api
   - src/system/api
   - src/web/api
-  # —— web 前端模块（demo/home 只列页面源码，__client 见顶部说明）——
+  # —— web 前端模块 ——
   - src/_platform/web
   - src/auth/web
-  - src/demo/web/entry.ts
-  - src/demo/web/locales
-  - src/demo/web/pages
-  - src/home/web/entry.ts
-  - src/home/web/locales
-  - src/home/web/pages
-  - src/login/web
-  - src/notification/web
+  # 框架内置页面聚合为一个多根模块（首页/登录/个人中心/通知/系统管理）。
+  # home 只列 routes/locales/pages：其 api 模块是 demo-only 不进脚手架，__client
+  # 留着会指向不存在的端点（见顶部说明），故逐子路径收录而不是整棵 src/app/web。
+  - src/app/web/entry.ts
+  - src/app/web/home/routes.ts
+  - src/app/web/home/locales
+  - src/app/web/home/pages
+  - src/app/web/login
+  - src/app/web/notification
+  - src/app/web/personal-center
+  - src/app/web/system
   # 解决方案市场：默认第一方能力。逐子路径收录——__tests__ 不进脚手架
   # （用户工程无 web 侧 vitest 基建，拷了是死文件）
   - src/oj-market/web/entry.ts
@@ -122,6 +125,4 @@ include:
   - src/oj-market/web/locales
   - src/oj-market/web/pages
   - src/oj-market/web/utils
-  - src/personal-center/web
-  - src/system/web
   - src/web/web