@oj-module/cli 0.2.54 → 0.2.57

package/src/lifecycle/__tests__/bundle.test.ts

@@ -104,6 +104,12 @@ describe("buildBundle · 正路径", () => {
 		expect(tarList(r.tgz).some(n => n.endsWith("/modules.json"))).toBe(false);
 	});
 
+	it("r1 前提：模块源码 locales 双语随包（安装期角色 title 解析数据源，计划 20261103-0948）", async () => {
+		const names = tarList((await pack()).tgz);
+		expect(names).toContain("demo-solution-0.1.0/web/modules/demo-solution/locales/zh-CN.json");
+		expect(names).toContain("demo-solution-0.1.0/web/modules/demo-solution/locales/en-US.json");
+	});
+
 	it("solution.yaml 作为 bundle 契约（优先于 manifest.yaml，避开 oj 按 manifest.yaml 枚举 api 后端的冲突）", async () => {
 		// 根目录若用 manifest.yaml 当 bundle 契约，会被 oj 的 api 模块搜索枚举误判为 api 模块；
 		// 故解决方案改用 solution.yaml，bundle 工具优先认它（manifest.yaml 仅旧方案回退）。

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/src/vendor.ts

@@ -79,6 +79,30 @@ export function ojBinName(platform: string = process.platform): string {
 	return platform === "win32" ? "oj.exe" : "oj";
 }
 
+/**
+ * oj devkit 文档同步（计划 docs/plans/20261103-1020-vendor-devkit-sync）：bin/devkit
+ * （@oj-bin/oj postinstall 落盘，与 bin/oj 同版本）→ 工程 `.claude/skills/oj-api-dev/`，
+ * 全部 `.md` **覆盖**拷入——skill 文档始终与已装 oj 版本一致（vendor/init 共用出口）。
+ * bin/devkit 缺失（旧版 oj/异常安装）→ ok:false，调用方记跳过、不失败。
+ * global.d.ts 不在此同步：工程根那份是模板自有变体、用户可编辑（init 首装 copyIfAbsent）。
+ */
+export function syncOjDevkit(projectRoot: string, binDir: string, log: (msg: string) => void = () => {}): { ok: boolean, files: string[] } {
+	const devkitDir = path.join(binDir, "devkit");
+	if (!fs.existsSync(path.join(devkitDir, "SKILL.md")))
+		return { ok: false, files: [] };
+	const skillDir = path.join(projectRoot, ".claude", "skills", "oj-api-dev");
+	fs.mkdirSync(skillDir, { recursive: true });
+	const files: string[] = [];
+	for (const name of fs.readdirSync(devkitDir)) {
+		if (!name.endsWith(".md"))
+			continue;
+		fs.copyFileSync(path.join(devkitDir, name), path.join(skillDir, name));
+		files.push(name);
+	}
+	log(`[ojm] oj devkit 文档已同步 → .claude/skills/oj-api-dev/（${files.length} 个文件，与已装 oj 同版本）`);
+	return { ok: true, files };
+}
+
 /**
  * 工程内 oj 二进制路径的**唯一口径**（<projectRoot>/bin/oj）。
  *
@@ -222,6 +246,12 @@ function installFromNpm(version: string, binDir: string, run: NpmRun, log: (msg:
 	}
 }
 
+/** devkit 同步 + 缺失时的人话跳过行（vendorCommand 两个调用点共用） */
+function syncDevkitOrSkip(projectRoot: string, binDir: string, log: (msg: string) => void): void {
+	if (!syncOjDevkit(projectRoot, binDir, log).ok)
+		log("[ojm] bin/devkit 缺失，跳过 oj devkit 文档同步（旧版 oj 或异常安装；skill 文档不更新）");
+}
+
 /**
  * US-1..US-5 编排：解析目标版本（tag 缺省经 npm view 追 latest，显式 tag 去 v 前缀）
  * → 本地已是该版本则跳过（--force 除外）→ 临时目录安装 + 拷贝 → 报告版本 → 探针冒烟。
@@ -243,6 +273,9 @@ export async function vendorCommand(
 	const binDir = path.join(projectRoot, "bin");
 	const local = readLocalVersion(binDir);
 	if (!opts.force && local === `v${version}`) {
+		// 文档同步不随版本跳过：用户删过 skill 目录后重跑 vendor 即补齐（R4）。
+		// 先同步再打跳过行——「已是 vX」保持命令收尾行（既有门禁断言末行）。
+		syncDevkitOrSkip(projectRoot, binDir, log);
 		log(`[ojm] oj 已是 v${version}，跳过。`);
 		const result = probe(binDir);
 		if (!result.ok)
@@ -255,6 +288,7 @@ export async function vendorCommand(
 		log(`[ojm] 本地 ${local ?? "未安装"} → v${version}`);
 	installFromNpm(version, binDir, run, log);
 	log(`[ojm] oj ${local ? `${local} → ` : ""}v${version} 安装完成：${path.join(binDir, ojBinName(process.platform))}`);
+	syncDevkitOrSkip(projectRoot, binDir, log);
 	// 安装后冒烟：发布二进制可能因构建机路径被烤进而不可用（见 probeOjRuntime）
 	const result = probe(binDir);
 	if (!result.ok)

package/templates/README.md

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

package/templates/init.include.yaml

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