@oj-module/cli 0.2.53 → 0.2.54

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

@@ -101,14 +101,20 @@ include:
   - src/personal-center/api
   - src/system/api
   - src/web/api
-  # —— web 前端模块（home 只列页面源码，__client 见顶部说明）——
+  # —— web 前端模块 ——
   - 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
+  # 框架内置页面聚合为一个多根模块（首页/登录/个人中心/通知/系统管理）。
+  # 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 +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