@oj-module/cli 0.2.18 → 0.2.23

package/src/contract/__tests__/market-client.integration.test.ts

@@ -9,8 +9,8 @@ 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/web/src/_platform/__client/api";
-import { httpMarketClient } from "../../../templates/web/src/oj-market/api/defaultClient";
+import { bindRequest } from "../../../templates/src/_platform/web/__client/api";
+import { httpMarketClient } from "../../../templates/src/oj-market/web/api/defaultClient";
 
 // index() 直连 request（不走生成 client），故把桩 request 做成可变实现，测试内统一指向同一 mock。
 const { requestImpl } = vi.hoisted(() => ({
@@ -63,7 +63,7 @@ function mockRequest(responder: (c: Call) => { status?: number, data?: unknown }
 
 // 让 index() 直连的 request 与生成 client 的 bindRequest 指向同一 mock，行为一致。
 // 桥接：占位方法零参签名 ↔ ScopedRequestLike 真实签名，经 any 双向打通（测试桩，无运行时差异）。
-function useMock(m: ReturnType<typeof mockRequest>) {
+function bindMock(m: ReturnType<typeof mockRequest>) {
 	bindRequest(m.req);
 	const req = m.req as unknown as Record<keyof typeof requestImpl, () => never>;
 	for (const k of Object.keys(requestImpl) as Array<keyof typeof requestImpl>)
@@ -75,12 +75,12 @@ describe("httpMarketClient · 统一委托生成 client 集成回归", () => {
 
 	beforeEach(() => {
 		mock = mockRequest(() => ({ data: {} }));
-		useMock(mock);
+		bindMock(mock);
 	});
 
 	it("meta() → GET _platform/market/meta，返回 { apiVersion }", async () => {
 		mock = mockRequest(() => ({ data: { apiVersion: "1.2.3" } }));
-		useMock(mock);
+		bindMock(mock);
 		const r = await httpMarketClient.meta();
 		expect(mock.calls).toEqual([{ method: "get", url: "_platform/market/meta", opts: undefined }]);
 		expect(r).toEqual({ apiVersion: "1.2.3" });
@@ -89,7 +89,7 @@ describe("httpMarketClient · 统一委托生成 client 集成回归", () => {
 	it("index() → GET _platform/market/index，返回 IndexRow[]", async () => {
 		const rows = [{ name: "a", latest: "1.0", installed: "1.0", enabled: true, upgradable: false }];
 		mock = mockRequest(() => ({ data: rows }));
-		useMock(mock);
+		bindMock(mock);
 		const r = await httpMarketClient.index();
 		expect(mock.calls[0]).toMatchObject({ method: "get", url: "_platform/market/index" });
 		expect(r).toEqual(rows);
@@ -97,7 +97,7 @@ describe("httpMarketClient · 统一委托生成 client 集成回归", () => {
 
 	it("index() 遇 503（未配置市场地址）→ [] 空态，不抛（PRD §5.3）", async () => {
 		mock = mockRequest(c => (c.url === "_platform/market/index" ? { status: 503 } : { data: {} }));
-		useMock(mock);
+		bindMock(mock);
 		const r = await httpMarketClient.index();
 		expect(r).toEqual([]);
 		// 503 是配置态而非故障：silentError 抑制全局 toast + retry:0 不重试（原
@@ -108,7 +108,7 @@ describe("httpMarketClient · 统一委托生成 client 集成回归", () => {
 
 	it("install(input) → POST _platform/market/install，body 含 name/version/source", async () => {
 		mock = mockRequest(() => ({ data: { task_id: "t-1" } }));
-		useMock(mock);
+		bindMock(mock);
 		const r = await httpMarketClient.install({ name: "alpha", version: "2.0", source: "file" });
 		expect(mock.calls[0]).toMatchObject({ method: "post", url: "_platform/market/install" });
 		expect(mock.calls[0].opts?.json).toEqual({ name: "alpha", version: "2.0", source: "file" });
@@ -117,7 +117,7 @@ describe("httpMarketClient · 统一委托生成 client 集成回归", () => {
 
 	it("install(input) 缺省 version/source → null / cdn 兜底", async () => {
 		mock = mockRequest(() => ({ data: { task_id: "t-2" } }));
-		useMock(mock);
+		bindMock(mock);
 		await httpMarketClient.install({ name: "beta" });
 		expect(mock.calls[0].opts?.json).toEqual({ name: "beta", version: null, source: "cdn" });
 	});
@@ -125,7 +125,7 @@ describe("httpMarketClient · 统一委托生成 client 集成回归", () => {
 	it("task(id) → GET _platform/market/task? 带 id", async () => {
 		const rec = { id: "t-1", name: "a", version: "1.0", status: "done", stage: "done", progress: 100, message: "ok", stages: [], startedAt: 1 };
 		mock = mockRequest(() => ({ data: rec }));
-		useMock(mock);
+		bindMock(mock);
 		const r = await httpMarketClient.task("t-1");
 		expect(mock.calls[0]).toMatchObject({ method: "get", url: "_platform/market/task" });
 		expect(mock.calls[0].opts?.searchParams).toEqual({ id: "t-1" });
@@ -134,7 +134,7 @@ describe("httpMarketClient · 统一委托生成 client 集成回归", () => {
 
 	it("enable(input) → POST _platform/market/enable，body {name,enabled}", async () => {
 		mock = mockRequest(() => ({ data: { ok: true, message: "done" } }));
-		useMock(mock);
+		bindMock(mock);
 		const r = await httpMarketClient.enable({ name: "a", enabled: false });
 		expect(mock.calls[0]).toMatchObject({ method: "post", url: "_platform/market/enable" });
 		expect(mock.calls[0].opts?.json).toEqual({ name: "a", enabled: false });
@@ -144,7 +144,7 @@ describe("httpMarketClient · 统一委托生成 client 集成回归", () => {
 	it("history() → GET _platform/market/history，返回 MarketHistory[]", async () => {
 		const hist = [{ id: 1, solution: "a", version: "1.0", action: "install", status: "ok", operator: null, message: null, created_at: 1 }];
 		mock = mockRequest(() => ({ data: hist }));
-		useMock(mock);
+		bindMock(mock);
 		const r = await httpMarketClient.history();
 		expect(mock.calls[0]).toMatchObject({ method: "get", url: "_platform/market/history" });
 		expect(r).toEqual(hist);
@@ -152,7 +152,7 @@ describe("httpMarketClient · 统一委托生成 client 集成回归", () => {
 
 	it("uninstallImpact(name) → GET _platform/market/uninstall-impact? 带 name", async () => {
 		mock = mockRequest(() => ({ data: { name: "a", affectedRoles: 2, affectedUsers: 5 } }));
-		useMock(mock);
+		bindMock(mock);
 		const r = await httpMarketClient.uninstallImpact("a");
 		expect(mock.calls[0]).toMatchObject({ method: "get", url: "_platform/market/uninstall-impact" });
 		expect(mock.calls[0].opts?.searchParams).toEqual({ name: "a" });
@@ -161,7 +161,7 @@ describe("httpMarketClient · 统一委托生成 client 集成回归", () => {
 
 	it("uninstall(name) → POST _platform/market/uninstall，body {name}", async () => {
 		mock = mockRequest(() => ({ data: { ok: true, message: "removed" } }));
-		useMock(mock);
+		bindMock(mock);
 		const r = await httpMarketClient.uninstall("a");
 		expect(mock.calls[0]).toMatchObject({ method: "post", url: "_platform/market/uninstall" });
 		expect(mock.calls[0].opts?.json).toEqual({ name: "a" });

package/src/contract/check.ts

@@ -1,9 +1,10 @@
+import type { ApiModuleRoot } from "../layout";
 import type { HandlerRow } from "./handler-scan";
 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 { resolveConfigPath } from "../layout";
+import { apiModuleRoots, apiModulesSrc, apiSrcOf, legacyApiModuleRoots, resolveConfigPath, tryResolveLayout, webSrcOf } from "../layout";
 import { readOjAnonymousPaths } from "../oj-config";
 import { emitClient } from "./emit-client";
 import { planStubWrites } from "./emit-stub";
@@ -47,9 +48,12 @@ export interface ApiExemption {
 }
 
 /**
- * 加载豁免清单：默认 `<cwd>/api/.ojm-api-exempt.json`（新名），缺失时回退旧名
- * `api/.ram-api-exempt.json`（R4：存量工程豁免不因改名失效）；`opts.exempt` 为
- * 绝对/相对路径时覆盖默认。文件缺失或 JSON 损坏 → 空豁免 `{}`（绝不抛错）。
+ * 加载豁免清单：按布局找位置，`opts.exempt` 为绝对/相对路径时覆盖默认。
+ * 候选顺序（第一个存在的胜出）：
+ *   1. `<cwd>/.ojm-api-exempt.json`        —— module-root 布局（config.yaml 在工程根）
+ *   2. `<cwd>/api/.ojm-api-exempt.json`    —— 历史布局（api/ 即工程根）
+ *   3. `<cwd>/api/.ram-api-exempt.json`    —— R4：存量工程旧名不因改名失效
+ * 文件缺失或 JSON 损坏 → 空豁免 `{}`（绝不抛错）。
  * 反常识坑：清单是严格 JSON.parse——写 `//` 注释会解析失败、静默回退空豁免
  * （豁免全失效且无报错）；说明文字请放 `_comment` 字段（本加载器只读
  * modules/paths，多余字段天然忽略）。
@@ -70,18 +74,29 @@ export function loadExemption(opts: { cwd: string, exempt?: string }): ApiExempt
 	}
 }
 
-/** 豁免清单文件名（新名优先；旧名只读回退）。`init` 只产新名。 */
-const EXEMPT_FILE = "api/.ojm-api-exempt.json";
-const EXEMPT_FILE_LEGACY = "api/.ram-api-exempt.json";
+/**
+ * 豁免清单候选路径（按优先级；`init` 只产第一条）。
+ *
+ * 位置由布局决定而不是常量钉死：module-root 布局 config.yaml 在工程根、随行的
+ * `.ojm-api-exempt.json` 也在根；历史布局两者都在 `api/` 下。写死 `api/` 会让新
+ * 布局工程的豁免**静默失效**——`loadExemption` 缺文件即回退空豁免，`ojm api --check`
+ * 会突然对 auth/web 报一堆「有 handler 无契约」。
+ */
+const EXEMPT_FILES = [
+	".ojm-api-exempt.json",
+	"api/.ojm-api-exempt.json",
+	"api/.ram-api-exempt.json", // R4：旧名只读回退
+] as const;
 
 function resolveExemptPath(cwd: string, exempt?: string): string {
 	if (exempt)
 		return exempt;
-	const next = join(cwd, EXEMPT_FILE);
-	if (existsSync(next))
-		return next;
-	const legacy = join(cwd, EXEMPT_FILE_LEGACY);
-	return existsSync(legacy) ? legacy : next;
+	for (const rel of EXEMPT_FILES) {
+		const candidate = join(cwd, rel);
+		if (existsSync(candidate))
+			return candidate;
+	}
+	return join(cwd, EXEMPT_FILES[0]);
 }
 
 /** 路由身份串（如 "order/list"、"auth/login"）的模块段 = 首段 */
@@ -130,15 +145,18 @@ function walkWsFiles(dir: string, out: string[] = []): string[] {
  * 只 warn 不 error：带 Bearer/cookie 的受保护 WS 是正当用法。
  * 读不到 config 直接不判——缺配置时做不出有依据的断言。
  */
-function checkWsAnonymous(wsFiles: string[], apiSrcDir: string, configPath: string): CheckViolation[] {
+function checkWsAnonymous(roots: readonly ApiModuleRoot[], configPath: string): CheckViolation[] {
+	const wsFiles = roots.flatMap(root => walkWsFiles(root.dir).map(file => ({ file, root })));
 	if (!existsSync(configPath) || wsFiles.length === 0)
 		return [];
 	const anonymous = readOjAnonymousPaths(configPath);
 	if (anonymous.length === 0)
 		return [];
 	return wsFiles
-		.map((file) => {
-			const relDir = relative(apiSrcDir, dirname(file)).split(sep).join("/");
+		.map(({ file, root }) => {
+			const relDir = [root.name, relative(root.dir, dirname(file)).split(sep).filter(Boolean).join("/")]
+				.filter(Boolean)
+				.join("/");
 			return { file, path: `/${relDir}/ws` };
 		})
 		.filter(({ path }) => !anonymous.includes(path))
@@ -146,7 +164,7 @@ function checkWsAnonymous(wsFiles: string[], apiSrcDir: string, configPath: stri
 			level: "warn" as const,
 			kind: "ws-anonymous-missing" as const,
 			filePath: file,
-			message: `[ojm-api] WS 路由 ${path} 不在 auth.anonymous_paths——oj 0.1.30 起 WS 握手过鉴权守卫，未带凭据的客户端会握手 401（表现为「文件在却连不上」）。若该 WS 本就要求鉴权（客户端带 Bearer/Cookie）可忽略本提示；否则请在 api/config.yaml 的 auth.anonymous_paths 补上 ${path}。`,
+			message: `[ojm-api] WS 路由 ${path} 不在 auth.anonymous_paths——oj 0.1.30 起 WS 握手过鉴权守卫，未带凭据的客户端会握手 401（表现为「文件在却连不上」）。若该 WS 本就要求鉴权（客户端带 Bearer/Cookie）可忽略本提示；否则请在 config.yaml 的 auth.anonymous_paths 补上 ${path}。`,
 		}));
 }
 
@@ -279,18 +297,29 @@ async function checkFromOpenapi(openapiPath: string, cwd: string, _exemption: Ap
 	const doc = JSON.parse(readFileSync(openapiPath, "utf8")) as OpenApiDoc;
 	const ir = irFromOpenapi(doc);
 	const violations: CheckViolation[] = [];
+	const layout = tryResolveLayout(cwd);
+	// 契约工具的扫描单元是「模块 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");
 	for (const [module, eps] of groupIrByModule(ir)) {
 		const client = emitClient(eps, { target: "module", module });
-		const clientDir = join(cwd, "web/src", module, "__client");
+		const clientDir = clientDirOf(module);
 		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)
 				violations.push({ level: "error", kind: "artifact-stale", message: `[ojm-api] 生成物过期或缺失：${relative(cwd, p)}——请重跑 ojm api 使其与 openapi.json 同步。`, filePath: p });
 		}
 	}
-	const apiSrcDir = join(cwd, "api/src");
+	const apiSrcDir = layout ? apiModulesSrc(layout) : join(cwd, "api/src");
 	if (existsSync(apiSrcDir)) {
-		const stubWrites = await planStubWrites(ir, { apiSrcDir, implemented: implementedRouteKeys(apiSrcDir) });
+		const stubWrites = await planStubWrites(ir, {
+			apiSrcDir,
+			// stub 落模块的 api 侧：module-root 布局是 `<src>/<m>/api`，不是 `<src>/<m>`
+			apiRootOf: layout ? (m: string) => apiSrcOf(layout, m) : undefined,
+			implemented: implementedRouteKeys(roots),
+		});
 		for (const w of stubWrites) {
 			if (w.action === "create")
 				violations.push({ level: "error", kind: "artifact-stale", message: `[ojm-api] stub 缺失：${relative(cwd, w.filePath)}——请重跑 ojm api 生成。`, filePath: w.filePath });
@@ -318,19 +347,18 @@ export async function checkApi(opts: { cwd: string, exempt?: string }): Promise<
 		throw new Error(`[ojm-api] ${opts.cwd} 下未发现 openapi.json——请先运行 oj v0.1.73 的 \`oj openapi -c config -d api/src -b /api -o openapi.json\` 生成（OpenAPI 3.1，含全部模块）。\`ojm api --check\` 的单一事实源即 openapi.json，不再消费旧 contract.ts。`);
 	}
 
-	// ② route 双向对账（仅 uni-dev——oj 树存在才有意义）
-	if (existsSync(join(opts.cwd, "api/src"))) {
-		const apiSrcDir = join(opts.cwd, "api/src");
-		const handlers = walkApiFiles(apiSrcDir).flatMap(f => scanHandlerFile(f, apiSrcDir));
+	// ② route 双向对账（仅后端树存在才有意义）
+	const layout = tryResolveLayout(opts.cwd);
+	const apiSrcDir = layout ? apiModulesSrc(layout) : join(opts.cwd, "api/src");
+	const roots = layout ? apiModuleRoots(layout) : legacyApiModuleRoots(opts.cwd);
+	if (existsSync(apiSrcDir)) {
+		const handlers = roots.flatMap(root =>
+			walkApiFiles(root.dir).flatMap(f => scanHandlerFile(f, root.dir, root.name)));
 		violations.push(...reconcileRoutes(uniDevIr, handlers, exemption));
 	}
 
 	// ④ WS 路由鉴权对账（oj 0.1.30 起握手过鉴权守卫）
-	violations.push(...checkWsAnonymous(
-		walkWsFiles(join(opts.cwd, "api/src")),
-		join(opts.cwd, "api/src"),
-		resolveConfigPath(opts.cwd),
-	));
+	violations.push(...checkWsAnonymous(roots, resolveConfigPath(opts.cwd)));
 
 	// ③ routes.js diff
 	const distDir = join(opts.cwd, "api/dist");

package/src/contract/emit-stub.ts

@@ -2,7 +2,7 @@ import type { OjSchemaDiag } from "./emit-oj-schema";
 import type { IrEndpoint } from "./ir";
 import { createHash } from "node:crypto";
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname } from "node:path";
+import { dirname, join } from "node:path";
 import { emitOjSchemaLine } from "./emit-oj-schema";
 import { splitRoute, wirePrefixOf } from "./ir";
 import { jsonSchemaToSample } from "./json-schema-sample";
@@ -32,8 +32,14 @@ export interface StubWrite {
 }
 
 export interface PlanStubOptions {
-	/** oj api 源码根（如 "api/src"） */
+	/** oj api 源码根（如 "api/src"）；仅用于未提供 `apiRootOf` 时的路径拼接 */
 	apiSrcDir: string
+	/**
+	 * 模块名 → 该模块 api 侧目录。module-root 布局传 `(m) => apiSrcOf(layout, m)`
+	 * （`<src>/<m>/api`）——stub 必须落进模块的 api 侧，串到 `<src>/<m>/` 会被 oj 当成
+	 * 模块根下的普通文件；历史布局缺省即 `<apiSrcDir>/<m>`。
+	 */
+	apiRootOf?: (module: string) => string
 	/** 读已有文件（不存在返回 undefined）；缺省真实 fs */
 	readFile?: (path: string) => string | undefined
 	/** 格式化注入缝（测试/特殊工程）；缺省恒等——模板本身天然 lint-clean（F6） */
@@ -119,7 +125,9 @@ export async function planStubWrites(ir: IrEndpoint[], opts: PlanStubOptions): P
 
 	// 按（模块段 + 目录镜像）分组 → 一个 api.ts
 	// 已在别处（模块根嵌套组 / 其他文件）实现的端点不进 stub 计划。
-	const groups = new Map<string, IrEndpoint[]>();
+	// 键保留模块与目录两段：落盘路径要经 `apiRootOf` 定位模块 api 根（module-root 布局
+	// 多一层 `api`），不能只拼成一条相对串。
+	const groups = new Map<string, { module: string, dir: string, endpoints: IrEndpoint[] }>();
 	for (const ep of ir) {
 		if (opts.implemented) {
 			const ojFullAbs = (ep.apiPrefix + ep.route).replace(/\/{2,}/g, "/");
@@ -127,16 +135,20 @@ export async function planStubWrites(ir: IrEndpoint[], opts: PlanStubOptions): P
 			if ([ojFullAbs, contractAbs].some(a => opts.implemented!.has(`${ep.method} ${a}`)))
 				continue;
 		}
+		const module = ep.apiPrefix.replace(/^\//, "");
 		const { dir } = splitRoute(ep.route);
-		const rel = [ep.apiPrefix.replace(/^\//, ""), dir, "api.ts"].filter(Boolean).join("/");
-		const list = groups.get(rel) ?? [];
-		list.push(ep);
-		groups.set(rel, list);
+		const key = `${module}\u0000${dir}`;
+		const group = groups.get(key);
+		if (group)
+			group.endpoints.push(ep);
+		else
+			groups.set(key, { module, dir, endpoints: [ep] });
 	}
 
 	const writes: StubWrite[] = [];
-	for (const [rel, endpoints] of [...groups.entries()].sort()) {
-		const filePath = `${opts.apiSrcDir}/${rel}`;
+	for (const [, { module, dir, endpoints }] of [...groups.entries()].sort()) {
+		const apiRoot = opts.apiRootOf ? opts.apiRootOf(module) : join(opts.apiSrcDir, module);
+		const filePath = join(apiRoot, dir, "api.ts");
 		// 模板天然 lint-clean（F6）→ 直接哈希发射内容；注入缝仅供测试/特殊工程对齐
 		const body = await fix(emitStubBody(endpoints, opts.diag), filePath);
 		const fingerprint = `// ojm-api:stub ${endpoints.map(e => e.name).sort().join(",")} sha256:${hashContent(body)}\n`;

package/src/contract/handler-scan.ts

@@ -1,3 +1,4 @@
+import type { ApiModuleRoot } from "../layout";
 import type { IrEndpoint } from "./ir";
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { dirname, join, relative, sep } from "node:path";
@@ -205,13 +206,19 @@ export function handlerAbs(h: HandlerRow): string {
 	return h.tail?.startsWith("/") ? h.tail : `/${h.full}`;
 }
 
-export function scanHandlerFile(filePath: string, apiSrcDir: string): HandlerRow[] {
+/**
+ * `apiDir` 是**模块的 api 侧目录**（module-root → `src/<name>/api`，历史 → `api/src/<name>`），
+ * `moduleName` 补进路由镜像的首段。两个参数而不是「扫描根 + 相对路径」，是因为 module-root
+ * 布局在扫描根与 handler 目录之间多一层 `api`，而它不属于路由（见 layout.apiModuleRoots）。
+ */
+export function scanHandlerFile(filePath: string, apiDir: string, moduleName = ""): HandlerRow[] {
 	const text = readFileSync(filePath, "utf8");
 	const sf = ts.createSourceFile(filePath, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
 	const routes = collectRouteDecls(sf);
 	const decls = collectObjectDecls(sf);
 	const callDecls = collectCallDecls(sf);
-	const relDir = relative(apiSrcDir, dirname(filePath)).split(sep).join("/");
+	const inner = relative(apiDir, dirname(filePath)).split(sep).filter(Boolean).join("/");
+	const relDir = [moduleName, inner].filter(Boolean).join("/");
 	const rows: HandlerRow[] = [];
 	const seen = new Set<ts.Node>();
 
@@ -312,15 +319,17 @@ export function walkApiFiles(dir: string, out: string[] = []): string[] {
  * emit-stub 据此跳过「已在别处（模块根嵌套组 / 其他文件）实现」的端点——否则 DDD
  * reshape 后镜像 stub 与真实 handler 双写同路由，oj 路由表出现重复注册。
  */
-export function implementedRouteKeys(apiSrcDir: string): Set<string> {
+export function implementedRouteKeys(roots: readonly ApiModuleRoot[]): Set<string> {
 	const keys = new Set<string>();
-	for (const f of walkApiFiles(apiSrcDir)) {
-		const text = readFileSync(f, "utf8");
-		// stub 镜像文件不算实现——它们覆盖的路由需照常报「stub 缺失/待更新」
-		if (/^\/\/ (?:ojm|ram)-api:stub /.test(text))
-			continue;
-		for (const row of scanHandlerFile(f, apiSrcDir))
-			keys.add(pathKey(row.method, handlerAbs(row)));
+	for (const root of roots) {
+		for (const f of walkApiFiles(root.dir)) {
+			const text = readFileSync(f, "utf8");
+			// stub 镜像文件不算实现——它们覆盖的路由需照常报「stub 缺失/待更新」
+			if (/^\/\/ (?:ojm|ram)-api:stub /.test(text))
+				continue;
+			for (const row of scanHandlerFile(f, root.dir, root.name))
+				keys.add(pathKey(row.method, handlerAbs(row)));
+		}
 	}
 	return keys;
 }

package/src/contract/run.ts

@@ -8,6 +8,7 @@ import { 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, tryResolveLayout, webSrcOf } from "../layout";
 import { emitClient } from "./emit-client";
 import { applyStubWrites, planStubWrites } from "./emit-stub";
 import { implementedRouteKeys } from "./handler-scan";
@@ -81,19 +82,27 @@ async function runFromOpenapi(openapiPath: string, cwd: string, result: RunResul
 	const doc = JSON.parse(readFileSync(openapiPath, "utf8")) as OpenApiDoc;
 	const ir = irFromOpenapi(doc, { rawPaths });
 	const byModule = groupIrByModule(ir);
+	const layout = tryResolveLayout(cwd);
 	result.contracts += byModule.size;
 	for (const [module, eps] of byModule) {
 		const client = emitClient(eps, { target: "module", module });
-		const clientDir = join(cwd, "web/src", module, "__client");
+		const clientDir = join(layout ? webSrcOf(layout, module) : join(cwd, "web/src", module), "__client");
 		writeIfChanged(join(clientDir, "api.ts"), client["api.ts"], result);
 		writeIfChanged(join(clientDir, "api.schemas.ts"), client["api.schemas.ts"], result);
 	}
 	// stub：oj 目录镜像树（人碰过的文件永不写——plan 阶段已按指纹判好）。
 	// 已实现键全量扫一遍传入：嵌套组（模块根单文件）实现的端点不再生成镜像 stub。
-	const apiSrcDir = join(cwd, "api/src");
+	const apiSrcDir = layout ? apiModulesSrc(layout) : join(cwd, "api/src");
+	const roots = layout ? apiModuleRoots(layout) : legacyApiModuleRoots(cwd);
 	if (existsSync(apiSrcDir)) {
 		const diag: OjSchemaDiag = { warnings: [] };
-		const writes = await planStubWrites(ir, { apiSrcDir, diag, implemented: implementedRouteKeys(apiSrcDir) });
+		const writes = await planStubWrites(ir, {
+			apiSrcDir,
+			// stub 落模块的 api 侧：module-root 布局是 `<src>/<m>/api`，不是 `<src>/<m>`
+			apiRootOf: layout ? (m: string) => apiSrcOf(layout, m) : undefined,
+			diag,
+			implemented: implementedRouteKeys(roots),
+		});
 		const counts = applyStubWrites(writes);
 		result.stubs.created += counts.created;
 		result.stubs.updated += counts.updated;
@@ -126,7 +135,8 @@ export async function runApiDocs(cwd: string, opts: { redocBin?: string, fetchJs
 	}
 	const doc = JSON.parse(readFileSync(openapiPath, "utf8")) as { paths?: Record<string, Record<string, unknown>> };
 	const paths = doc.paths ?? {};
-	const isUniDev = existsSync(join(cwd, "api/src"));
+	const layout = tryResolveLayout(cwd);
+	const isUniDev = existsSync(layout ? apiModulesSrc(layout) : join(cwd, "api/src"));
 
 	const outDir = isUniDev ? join(cwd, "api/docs") : join(cwd, "docs/api");
 	mkdirSync(outDir, { recursive: true });

package/src/dev.ts

@@ -10,7 +10,7 @@
  *   - 布局探测          → layout.ts
  *   - 工程 mock 约定    → dev-mock.ts
  *
- * 两种形态（按 api/config.yaml 是否存在自动判定）：
+ * 两种形态（按 config.yaml 是否存在自动判定）：
  *   全栈   /api/* 反代 oj（oj 自带热更，ojm 不重启它），模块源码变更 → 重建 → SSE 刷新
  *   纯前端 /api/* 走工程 mock（mock/*.mock.mjs 约定，未命中 404），行为与历史版本一致
  *
@@ -28,6 +28,7 @@ import http from "node:http";
 import { join, resolve } from "node:path";
 import process from "node:process";
 import readline from "node:readline";
+import { syncAliasPaths } from "./alias-paths";
 import { buildModules } from "./build";
 import { loadContractMocks, resolveMock } from "./contract/mock";
 import { loadProjectMocks, mockStatusCode } from "./dev-mock";
@@ -35,6 +36,7 @@ import { createReloadHub, proxyApi, proxyWsUpgrade, sseScript } from "./dev-prox
 import { loadHtmlTransform } from "./html-transform";
 import { resolveConfigPath, resolveLayout } from "./layout";
 import { startOj } from "./oj";
+import { requireModuleRootCapability } from "./oj-caps";
 import { ensureDevCert } from "./oj-cert";
 import { readOjApiPrefix } from "./oj-config";
 import { createStaticHandler, decodeReqPath, listenOnFreePort } from "./static-handler";
@@ -48,8 +50,8 @@ export interface DevOptions {
 	shellDist?: string
 	/** 注入重建函数（测试）；默认 buildModules（不合并全站，产物只写模块） */
 	buildModulesFn?: (projectRoot: string) => Promise<unknown>
-	/** 注入桩 oj（测试）；默认 startOj；纯前端工程不调用 */
-	ojStarter?: (configPath: string, base: string, apiSrc: string) => OjProcess
+	/** 注入桩 oj（测试）；默认 startOj；纯前端工程不调用。第三参为目录（→ --api-path）或已拼好的旗标数组（→ --module-root） */
+	ojStarter?: (configPath: string, base: string, apiSource: string | string[]) => OjProcess
 	/** 强制纯前端形态（不起 oj，/api 走 mock） */
 	frontendOnly?: boolean
 	/** 启用 Vite 风格快捷键（默认仅 TTY 启用；测试可强制开） */
@@ -70,6 +72,10 @@ export async function devServer(projectRoot: string, opts: DevOptions = {}): Pro
 	console.log("[ojm] 构建本地模块…");
 	await build(projectRoot);
 
+	// 别名投影跟着模块清单走：dev 是「新增模块 → 立刻写 #/<新模块>/…」的主循环，
+	// 不刷新 paths 的话编辑器要把这条 import 报成 any/TS2307，直到下次 build。内容未变不写盘。
+	syncAliasPaths(projectRoot);
+
 	// 工程 mock（可选约定 mock/*.mock.mjs）：纯前端形态的 /api 边界
 	const mocks: MockRoute[] = await loadProjectMocks(projectRoot);
 	// 契约 mock（AC-D14）：手写精确匹配优先，契约 pattern 兜底示例值；装载失败不崩 dev
@@ -84,17 +90,26 @@ export async function devServer(projectRoot: string, opts: DevOptions = {}): Pro
 	// htmlTransform（web.config.ts，可选）先于起进程校验：配置坏了不该留下 oj 孤儿
 	const transform = await loadHtmlTransform(projectRoot);
 
-	// 2) oj 后端（工程有 api/config.yaml 时全栈形态；桩可注入）
+	// 2) oj 后端（工程有 config.yaml 时全栈形态；桩可注入）
 	const configPath = resolveConfigPath(projectRoot);
 	let oj: OjProcess | undefined;
 	let ojTarget: string | undefined;
 	// 反代前缀跟随 config 的 mounts:（api 挂载 prefix；F2：改前缀后硬编码 /api 会静默失效）
 	let apiBase = "/api";
 	if (!opts.frontendOnly && existsSync(configPath)) {
+		// dev 读源码树（保存即热更，不经产物）：module-root 布局给 `--module-root <root>/src`
+		// （oj 递归发现 manifest.yaml），历史布局给 `--api-path <root>/api/src`——两者互斥。
+		const moduleRoot = layout.kind === "module-root";
+		if (moduleRoot)
+			requireModuleRootCapability(projectRoot);
+		const apiSource: string | string[] = moduleRoot && layout.moduleRoot
+			? ["--module-root", layout.moduleRoot]
+			: resolve(projectRoot, "api/src");
 		apiBase = readOjApiPrefix(configPath);
 		await ensureDevCert(configPath);
-		const starter = opts.ojStarter ?? ((cfg: string, b: string, apiSrc: string) => startOj(cfg, b, apiSrc));
-		oj = starter(configPath, apiBase, resolve(projectRoot, "api/src"));
+		const fallbackStarter = (cfg: string, b: string, apiSrc: string | string[]) => startOj(cfg, b, apiSrc);
+		const starter: NonNullable<DevOptions["ojStarter"]> = opts.ojStarter ?? fallbackStarter;
+		oj = starter(configPath, apiBase, apiSource);
 		try {
 			await oj.ready; // 失败人话报错（stderr 尾部），fail-fast
 		}
@@ -210,7 +225,7 @@ export async function devServer(projectRoot: string, opts: DevOptions = {}): Pro
 	if (ojTarget)
 		console.log(`[ojm] oj 后端已就绪：${apiBase} → ${ojTarget}（api.ts 保存即热更）`);
 	else
-		console.log("[ojm] 纯前端形态（无 api/config.yaml）：/api 由 mock/ 提供");
+		console.log("[ojm] 纯前端形态（无 config.yaml）：/api 由 mock/ 提供");
 
 	console.log("[ojm] 宿主来自 @oj-module/cli 内置 shell-dist（importmap 单例），模块来自本地 dist/");
 
@@ -279,6 +294,8 @@ export async function devServer(projectRoot: string, opts: DevOptions = {}): Pro
 	// 仅 TTY 默认启用（管道/CI 下不抢 stdin）；测试可经 keymap + inputStream 强制。
 	const keymapEnabled = opts.keymap ?? (process.stdin.isTTY ?? false);
 	if (keymapEnabled) {
+		const footerText = "快捷键：r 热更新 · h 帮助 · c 清屏 · o 打开浏览器 · q 退出";
+		const footer = pinFooter(`[ojm] ${footerText}`);
 		setupDevKeymap({
 			server,
 			oj,
@@ -286,12 +303,15 @@ export async function devServer(projectRoot: string, opts: DevOptions = {}): Pro
 			port: actualPort,
 			input: opts.inputStream,
 			openBrowser: opts.openBrowser,
+			clearScreen: footer ? () => footer.clear() : undefined,
 			onReload: () => {
 				void trigger();
 			},
 			onQuit: shutdown,
 		});
-		console.log("[ojm] 快捷键：r 热更新 · h 帮助 · c 清屏 · o 打开浏览器 · q 退出");
+		// 非 TTY（pinFooter 拒绝）回退一次性打印，行为与历史一致
+		if (!footer)
+			console.log(`[ojm] ${footerText}`);
 	}
 
 	return server;
@@ -320,6 +340,52 @@ export async function shutdownDev(
 	setTimeout(exit, 1500, 0).unref();
 }
 
+/**
+ * 快捷键提示常驻底栏：DECSTBM 把滚动区设为 1..rows-1，末行留给提示。
+ * 之后本进程 console.log 与 oj 透传（均经 process.stdout.write）只在滚动区内滚动，
+ * 末行由终端保持，无需逐条重绘。非 TTY / 行数不足返回 undefined（调用方回退一次性打印）。
+ */
+export interface PinnedFooter {
+	/** 清屏：ED（\x1b[2J）保留滚动区（RIS \x1bc 会复位滚动区，禁用），随后重绘提示 */
+	clear: () => void
+	/** 恢复全屏滚动区并落光标到底行（进程退出/shell 接管前调用）；幂等 */
+	stop: () => void
+}
+
+export function pinFooter(text: string, stream: NodeJS.WriteStream = process.stdout): PinnedFooter | undefined {
+	if (!stream.isTTY || (stream.rows ?? 0) < 3)
+		return undefined;
+	const write = (s: string) => {
+		stream.write(s);
+	};
+	const render = () => {
+		const rows = stream.rows || 24;
+		write(`\x1B[1;${rows - 1}r`); // 滚动区：首行 ~ 倒数第二行（DECSTBM 会把光标送回 1;1）
+		write(`\x1B[${rows};1H\x1B[2K${text}`); // 末行清行后画常驻提示
+		write(`\x1B[${rows - 1};1H`); // 光标回滚动区底行，后续输出照常滚动
+	};
+	render();
+	const onResize = () => render();
+	let stopped = false;
+	const stop = () => {
+		if (stopped)
+			return;
+		stopped = true;
+		process.removeListener("SIGWINCH", onResize);
+		process.removeListener("exit", stop);
+		write("\x1B[r\x1B[999;1H\n"); // 恢复全屏滚动区，光标夹到底行避免 shell 提示符悬空
+	};
+	process.on("SIGWINCH", onResize);
+	process.on("exit", stop);
+	return {
+		clear: () => {
+			write("\x1B[2J");
+			render();
+		},
+		stop,
+	};
+}
+
 /**
  * Vite 风格 dev 快捷键（默认仅在 TTY 启用，见 devServer 内的 keymapEnabled 判定）。
  *   r  强制重建并热更新（复用 trigger）
@@ -341,6 +407,8 @@ export interface DevKeymapDeps {
 	 */
 	input?: NodeJS.ReadableStream & { setRawMode?: (mode: boolean) => unknown }
 	openBrowser?: (url: string) => void
+	/** 清屏实现（默认 \x1Bc）；devServer 注入底栏版以保住滚动区 */
+	clearScreen?: () => void
 	onReload: () => void
 	onQuit: () => void
 	log?: (msg: string) => void
@@ -389,7 +457,10 @@ export function setupDevKeymap(deps: DevKeymapDeps): void {
 			help();
 		}
 		else if (k === "c") {
-			process.stdout.write("\x1Bc");
+			if (deps.clearScreen)
+				deps.clearScreen();
+			else
+				process.stdout.write("\x1Bc");
 		}
 		else if (k === "o") {
 			open(url);