@oj-module/cli 0.2.53 → 0.2.56

package/src/init.ts

@@ -240,6 +240,24 @@ export async function initProject(destDir: string, opts: InitOptions = {}): Prom
 	//     与 pnpm-workspace.yaml 同型，改由 init 现场生成
 	ensureGitignore(destDir, report);
 
+	// 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}`);
 	console.log(`[ojm]   新增 ${report.created.length} 项，跳过（已存在）${report.skipped.length} 项`);
 	for (const item of report.skipped)
@@ -400,14 +418,18 @@ 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;
 	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 +439,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/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,82 +6,88 @@
 
 ```bash
 pnpm install
-pnpm dev        # 开发：前端 devServer + oj 后端（api/src 保存即热更）
+pnpm dev        # 开发：前端 devServer + oj 后端（src 下 api.ts 保存即热更）
 pnpm build      # 构建：oj build + 前端全站合并到 dist/web
 pnpm preview    # 预览：oj migrate + server（release 产物）
 ```
 
-登录账号：`admin` / `aA123456`（见 `api/src/_platform/seed.sql`）。
+登录账号：`superadmin` / `aA123456`（四个内置角色账号见 `src/app/api/_platform/seed.sql`）。
 
-## 系统管理模块
+## 目录（一个 `src/app` 装下整个应用）
 
-`web/src/system/`（用户管理 / 成员资格 / 角色权限 / 操作日志 / 站点设置 / 登录方式）
-的前端 API 客户端 `__client/` **已随模板分发**（与 auth/notification 等一致），`pnpm dev`
-开箱即用、「系统管理」菜单直接可见。
+```
+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 解压，不入库）
+```
+
+- **后端**按业务域分模块：`_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` 是从 `openapi.json`（模板自带，由 `api/src/system` 契约产出）生成的产物；
-契约变更后刷新一次即可：
+## 契约与 `__client`
+
+前端调后端一律走 `ojm api` 从 `openapi.json` 生成的 `__client/`（随模板分发，开箱即用）。
+改了 handler 的 `.schema`（入参）/ `.response`（出参）后刷新：
 
 ```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 变化也会自动重生成）
+bin/oj openapi -c config.yaml --module-root src -b /api -o openapi.json   # 重产契约
+pnpm exec ojm api                                                         # 重生成 __client
 ```
 
-成员资格页仅 superadmin 可见。改了 `api/src` 的 handler `.schema`/`.response` 后重跑这两条保持同步
-（`ojm api --check` 可对账，零漂移为发布门禁）。
+生成物入口是 `__client/index.ts`（**不是 `api.ts`**：oj dev 会把模块目录下的
+`api.ts` 当路由扫描）。页面里用 `from "../__client"` 导入。
 
-## 目录
-
-```
-bin/           oj 二进制（init 解压，不入库）
-api/src/       后端模块源码（目录镜像路由：api/src/<模块>/<路径>/api.ts）
-dist/api/      oj build 产物
-web/src/   前端模块源码
-dist/web/  构建产物（完整站点）
-```
+多根聚合模块的 client 归属由 `web.config.ts` 的 `clientOwners` 决定（`system → app`），
+生成物落 `src/app/web/system/__client`，与页面同级——页面相对导入不用改。
+`ojm api --check` 可对账漂移（零漂移为发布门禁）。
 
 ## 注意
 
-- 改 `api/src` 下的 api.ts 保存即生效；**新增/删除后端模块目录、改
+- 改 `src/app/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"`**
+  对应根的 `__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`，再跑上面的命令刷新。
+
+- **从旧版本升级（`__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 可执行文件。若某次 `@latest` 指向的是旧版
-  （例如早于系统管理模块的 `0.1.x`），之后重跑仍可能命中旧缓存，生成的脚手架就会缺新模块、
-  模板偏旧（典型表现：`web/src` 下没有 `system` 目录）。
-  排查：`ls web/src` 看是否缺预期模块。
-  解决：清掉 dlx 缓存后重跑——
+  pnpm dlx 会按首次解析到的版本**缓存** CLI 可执行文件。排查：`ls src/app/api` 看是否缺预期模块。
+  解决：清掉 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

@@ -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,20 +99,30 @@ 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
-  # —— web 前端模块（home 只列页面源码，__client 见顶部说明）——
-  - src/_platform/web
-  - src/auth/web
-  - src/home/web/entry.ts
-  - src/home/web/locales
-  - src/home/web/pages
-  - src/login/web
-  - src/notification/web
+  # 框架内置后端全部收在 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 前端模块 ——
+  # 纯 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。
+  - 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
@@ -119,6 +133,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
+  - src/app/web/web