@oj-module/cli 0.1.21 → 0.2.1

package/devkit/README.md

@@ -15,7 +15,7 @@
 | 文件 | 用途 |
 |---|---|
 | `SKILL.md` | Claude Code 等 agent 的 skill 入口：工作流、红线、新模块 checklist、陷阱速查，按章节号引用手册 |
-| `manual.md` | 模块开发手册（10 章）：工程结构、写模块、契约与代码生成（含 §3.10 旧 contract.ts 工程迁移指南）、provider 接管（覆盖框架内置功能）、布局、i18n、构建发布、排查、CLI 子命令参考（ojm 原生命令 vs oj 透传命令） |
+| `manual.md` | 模块开发手册（10 章）：工程结构（含 §1.7 handler 四红线——oj 运行时实测钉出，后端必读）、写模块、契约与代码生成（含 §3.10 旧 contract.ts 工程迁移指南）、provider 接管（覆盖框架内置功能）、布局、i18n、构建发布、排查、CLI 子命令参考（ojm 原生命令 vs oj 透传命令） |
 | `framework-dev.md` | 框架贡献者路线（**仅框架仓库**）：改 `packages/runtime`、`packages/cli` 时的入口与红线 |
 
 ## 安装（业务工程）

package/devkit/SKILL.md

@@ -54,12 +54,20 @@ description: 用 ojm 开发前后端一体工程时使用——新增/修改前
   仅平级声明 `.response`。不要手写 `content-type`（运行时按 boundary 自动补）。
 - **前端模块的 import 只有三类**：`@oj-module/runtime`、宿主 importmap 提供的共享依赖、
   自身相对路径。共享依赖不进工程 `dependencies`（宿主提供单例，模块不得打包副本）。
+  **拿用户/角色等信息：读走 `useUserStore` / `useAuthStore` / `useAccess`（`AccessControl` 门禁），
+  写走契约 client（`ojm api` 生成模块自有 `__client`，或复用 runtime 导出的 `api/rbac` / `api/user`），
+  绝不 import 框架 `#src/*`**——设计动机与红线见手册 §2.8。
 - **后端方法名是 `del`，不是 `delete`**（写成 `delete` 返回 405）。
 - **加一张新表是三件套，不是只写 `schema.yaml`**：`migrations/{seq:04}__*.sql`（DDL 的真正定义（实际 SQL），
   DDL 只进 migrations）+ `schema.yaml`（声明，与 migration 逐字段一致）+ `manifest.yaml` 的 `tables:`
   （与 schema 双向一致）。少一个就建不出表或启动失败。见手册 §1.5。
 - **`seed.sql` 每次启动都重放**，必须幂等（`INSERT OR IGNORE`）；它按 `;` 朴素切分，
   注释里不许出现分号字面量。
+- **handler 四红线（manual §1.7，oj 运行时实测）**：① 未捕获异常恒 500 不读
+  `err.status`——业务错误必须经 `respond()` 收口 `json.fail`；② 相对 import 按
+  **目录**解析（多一层 `../` 就 route error）；③ 模块级 `let`/`Map` 不跨请求存活
+  （oj 每请求重建模块）——跨请求状态必须落库；④ 模块级禁止触碰运行时全局
+  （`jwt`/`axis`/`bcrypt`），`oj build` introspect 空沙箱会炸。
 
 ## 重启边界（最容易卡住新人）
 
@@ -78,6 +86,7 @@ description: 用 ojm 开发前后端一体工程时使用——新增/修改前
 - [ ] 菜单标题用命名空间语法 `"<模块名>:menu.<key>"`，且 `locales/<lang>.json` 里有这个 key
 - [ ] 有接口 → handler 动词挂了 `.schema`（入参）+ 平级 `.response`（出参，oj v0.1.72+）→ `oj openapi` + `ojm api` 跑过 → onInit 里 `create<Module>Client(ctx)`
 - [ ] 接管了某功能 → provider 方法数与类型定义**一个不差**
+- [ ] 有后端 → handler 四红线过一遍（manual §1.7：respond 收口 / import 深度 / 无模块级状态 / 无模块级运行时全局）
 - [ ] `pnpm dev` 起来后按 §8 五步排查全过
 
 ## 旧工程迁移（contract.ts / defineApi → 新流水线）
@@ -126,10 +135,15 @@ description: 用 ojm 开发前后端一体工程时使用——新增/修改前
 | 后端 `import '@oj-module/runtime/...'` 报 `escapes project root` | oj 解析裸 specifier 以 `api/` 为项目根并钳制不越界，`@oj-module/runtime` 符号链接在 `packages/runtime`（项目根外） | 后端原语/类型放 `api/src` 内相对导入；跨模块共享类型仍以 runtime 为单一真源，两端形状手动同步 |
 | 跨用户删/读他人通知不报错却像没生效 | 原语对不存在/非本人的行 `UPDATE 0` 行返回 `ok`，没区分归属 | 原语（`delNotice`/`markRead`）返回 `boolean`/`count`，端点据 `false`/`0` 映射 `json.fail(403, "forbidden")` |
 | handler 写了动词子目录（`read/api.ts` 这类） | 旧形态（oj v0.1.64 前） | 按 manual §3.9「DDD 判据速查」reshape：同聚合多动词收模块根嵌套组，`del` 保留键例外 |
+| 业务错误恒 `{"code":500}`（401/403/409 全变 500） | handler 抛异常被 oj 一律抹 500，不读 `err.status` | service 抛 `Error & {status}`，handler 经 `respond()` 收口（manual §1.7-1） |
+| dev 日志 route error（Cannot find module）/ 端点 404 | handler 相对 import 多一层——按**目录**解析 | 按 manual §1.7 深度表改 |
+| 限速/节流/计数真实请求下永不累积（测试全绿） | 模块级 `Map`/`let` 不跨请求存活（每请求重建模块） | 状态落库（模板迁移 0009 先例）或 oj 持久面 |
+| `ojm build` 报 `introspect api.ts: jwt not configured` | 模块级语句碰运行时全局，introspect 空沙箱炸 | 移进 handler 函数体内（manual §1.7-4） |
 | 页签怎么点都关不掉、无报错提示 | `beforeClose` 守卫 fail-safe 否决（守卫抛错按取消处理） | 先查控制台 `[tabs] beforeClose` 报错；确认弹窗逻辑与 `resolve(true/false)` 收口（manual §6.4） |
 
 ## 手册
 
-`manual.md`（同目录）共 10 章：1 工程结构 / 2 写前端模块 / 3 契约与代码生成 /
-4 接管框架内置功能（provider）/ 5 布局与插槽 / 6 i18n 与样式 / 7 构建与发布 / 8 排查 /
-9 参考 / 10 CLI 子命令参考（ojm 原生命令 vs oj 透传命令的差异区分）。
+`manual.md`（同目录）共 10 章：1 工程结构（含 **§1.7 handler 四红线**——oj 运行时实测钉出，
+后端 handler 必读）/ 2 写前端模块 / 3 契约与代码生成 / 4 接管框架内置功能（provider）/
+5 布局与插槽 / 6 i18n 与样式 / 7 构建与发布 / 8 排查 / 9 参考 / 10 CLI 子命令参考
+（ojm 原生命令 vs oj 透传命令的差异区分）。

package/devkit/manual.md

@@ -92,6 +92,43 @@ api/src/<模块>/<路径...>/api.ts   →   /api/<模块>/<路径...>
 
 > `seed.sql` 按 `;` 朴素切分，**注释里不许出现分号字面量**，否则语法错。
 
+### 1.7 handler 四红线（oj 运行时实测钉出，2026-10-16 RBAC 阶段）
+
+以下四条都是真机冒烟（`ojm init` + `ojm dev`/`build`）实测钉出的 oj 运行时行为，
+**dev 模式体感正常、一到构建/并发就炸**——vitest 直引 service 的测试结构性覆盖不到，
+评审 checklist 必查。逐条展开：
+
+1. **未捕获异常恒 500，不读 `err.status`。** handler 抛出任何异常，oj 运行时一律回
+   `{"code":500,"msg":"Error: ..."}`——你在 service 层精心设计的 401/403/409 全被抹平。
+   **红线**：handler 业务体必须收口成 `json.fail(status, msg, extra?)`；模板统一约定
+   `_platform/_shared/respond.ts` 的 `respond(fn)`——service 抛 `Error & {status?, ...extra}`，
+   handler 写 `await respond(async () => { ...; return data; })` 即自动映射
+   （extra = error 的 own 可枚举属性除去 `status`/`message`，进信封 `data`）。
+2. **相对 import 按「目录」解析，不是按文件层级。** 路由加载器以**含 `api.ts` 的目录**
+   为基准解析相对路径——多写一层 `../` 在 dev 日志里是 route error（模块像没注册），
+   vitest 直引 service 永远发现不了。正确深度：
+
+   | 文件位置 | 到 `_platform/_shared` 的写法 |
+   |---|---|
+   | `api/src/system/<x>/api.ts` | `../../_platform/_shared/...` |
+   | `api/src/system/<x>/<y>/api.ts` | `../../../_platform/_shared/...` |
+   | `api/src/auth/api.ts` | `../_platform/_shared/...` |
+   | `api/src/auth/<z>/api.ts` | `../../_platform/_shared/...` |
+   | `api/src/_platform/<x>/api.ts` | `../_shared/...` |
+   | `api/src/_platform/<x>/<y>/api.ts` | `../../_shared/...` |
+3. **模块级可变状态不跨请求存活。** oj **每请求重建 handler 模块实例**（实测：模块级
+   计数器连打三次恒为初值）——`let` / `Map` / `Set` 级状态一律视为**单请求作用域**。
+   需要跨请求的状态（限速、节流、去重窗口、判权缓存）**必须落库**或走 oj 持久面。
+   模板先例：迁移 `0009__sys_throttle`（`sys_login_throttle` 连败节流 +
+   `sys_rate_window` 滑动窗口，三方言）。别想着「先内存后 Redis」——内存方案在 oj 下
+   连单实例都跑不对。
+4. **`oj build` 的 introspect 在无运行时配置的空沙箱里评估模块。** 构建期会加载
+   handler 模块提取 `.schema`，此时 `jwt` / `axis` 等运行时全局**不存在**——模块级
+   任何触碰运行时全局的语句（`createSession()`、`axis("ldap")`、`bcrypt.xxx`）
+   直接炸构建：`introspect api.ts: Error: jwt not configured`。**红线**：handler 模块
+   顶部只许 import 与纯常量声明；一切运行时全局的取用移进 handler 函数体内按需执行
+   （无状态构造是纯闭包，每请求新建零成本）。
+
 ---
 
 ## §2 写前端模块
@@ -283,6 +320,41 @@ importmap 键，构建期报错——需要新深路径请联系框架方在共
 
 ---
 
+### 2.8 模块如何获取用户/角色等信息（读与写的边界）
+
+模块常要读当前用户、角色、权限，甚至写改密/改角色。**正确姿势是走框架的「公共出口 + 契约客户端」，而不是 import 框架源码**——后者会把 runtime 内部实现打进模块 bundle，造成编译夹带、双份 store / 双 React、版本不一致。本节讲清楚边界与红线。
+
+**读（用户/角色/权限）→ 用 `@oj-module/runtime` 导出的公共 hook/store**
+
+这些是框架写入的同一份 zustand 单例，模块订阅即拿到实时状态，无需自己再拉一份：
+
+- `useUserStore`：当前用户画像（`username` / `roles` / `permissions` / `email` …）；
+- `useAuthStore`：`token`、登录/登出（`login` / `logout`）；
+- `useAccess` + `AccessControl` 组件：基于 `roles` / `permissions` 的按钮/菜单门禁，别自己拿 `roles` 数组手算；
+- 其它：`usePreferences`、`useTabsStore`、`useSlotNodes`（§5.5）等。
+
+```ts
+import { useUserStore, useAccess, AccessControl } from "@oj-module/runtime";
+
+const roles = useUserStore(s => s.roles);
+// 或按权限门禁：<AccessControl permission="system:users:read"><Button>用户管理</Button></AccessControl>
+```
+
+**写（改密/改角色/改设置）→ 走契约 API client，不碰框架内部**
+
+- 框架已把 `auth/*`、`system/*`、`web/*` 等端点经 OpenAPI 契约定义，并从 `@oj-module/runtime` 导出类型化 fetch（如 `api/rbac` 的 `fetchChangePassword`、`fetchRbacUpdateUserRoles`，`api/user` 的 `fetchUserInfo`）。要调框架内置写接口，直接复用这些导出。**但更推荐模块 own 自己的契约**：在 `api/src/<模块>/contract.ts` 声明，跑 `ojm api` 生成 `web/src/<模块>/__client/api.ts`，模块经自己的 client 调框架端点——接口由契约（versioned OpenAPI）对齐，而非把框架源文件打进来。
+- 底层都走同一个 `request` 单例 + 契约 URL；模块侧请求被 `defineModule` 的 `ctx` 收敛到登记过的 `apiPrefix`，越界 / `../` 穿越 / 逐请求 prefix 覆盖均被拒（请求边界见 §2.6 + `tests/runtime/scoped-request.test.ts`）。
+
+**为什么不会「版本不一致」**
+
+宿主（cli 内置 `shell-dist`）把 `react` / `antd` / `runtime` 等共享依赖预打包、经 importmap 提供**单例**——宿主与所有模块命中同一份实例。所以模块的 `useUserStore` 和框架的是**同一个 store**，antd `ConfigProvider` 也只有一个：不会出现两份 React / 两份 store 状态不同步。共享依赖版本以 `catalog:` 单一真相钉死（见 §2.7），模块只在 `devDependencies` 对齐版本供 `tsc` 用。
+
+**红线**
+
+- **绝不 `import … from "#src/*"`**：构建期直接拦（§2.6）。模块只 import 三类（§2.6）。
+- **`@oj-module/runtime` 的出口是冻结契约**：有 `tests/runtime/runtime-exports.test.ts` 守护，加/删导出即红，属破坏性变更。要用的东西若在出口里没有，**提需求让它进公共出口**，别改成 import 框架内部——否则一发版就碎。
+- 需要框架没暴露的能力（如接管某内置功能），走 §4 的 provider 接管，而非源码 import。
+
 ## §3 契约与代码生成
 
 ### 3.1 一句话
@@ -1274,6 +1346,10 @@ export default async (path: string, html: string) => {
 | curl 访问 SPA 路由返回 404 | SPA history 回落要求 `Accept: text/html` | 加 `-H 'Accept: text/html'`（浏览器自带，不是 bug） |
 | `oj serve` 启动即退，报 `config uses removed server.* site keys (v0.1.58): api_prefix`（或 `app_path` / `app_prefix` / `static_sites` / `app_spa_fallback`） | 用了 oj v0.1.58 起删除的旧站点键 | 改 `server.api_prefix: /api` 为顶层 `mounts: [{prefix: "/api", api: "src"}]`（一行=一个 URL 前缀+一个目录，`api`/`web` 恰好其一）；迁移完整 YAML 由报错信息给出；详见后端 devkit「mounts 迁移」 |
 | 改完 `mounts:` 仍报 `no route matched`（/api/* 全 404） | `api:` 指向的目录不是 oj 启动目录下的 `src`（相对 config 所在目录） | `mounts[].api` 写 `"src"`，且 `oj serve` 的 `-c` 指向 `api/config.yaml`（ojm dev/preview 已内置正确路径） |
+| 业务错误恒返回 `{"code":500}`（401/403/409 全变 500） | handler 抛异常被 oj 一律抹成 500，不读 `err.status` | service 抛 `Error & {status}`，handler 经 `respond()` 收口（§1.7-1） |
+| dev 起不来，日志一堆 route error（Cannot find module） | handler 相对 import 多写了一层——按**目录**解析不是按文件（§1.7-2） | 按 §1.7 深度表改 |
+| 限速/节流/去重窗口在真实请求下永不累积（测试却全绿） | 模块级 `Map`/`let` 不跨请求存活——oj 每请求重建模块（§1.7-3） | 状态落库（模板 0009 先例）或走 oj 持久面 |
+| `ojm build` 报 `introspect api.ts: Error: jwt not configured`（dev 模式正常） | 模块级语句触碰运行时全局，introspect 空沙箱里炸（§1.7-4） | 移进 handler 函数体内按需执行 |
 
 ---
 
@@ -1289,6 +1365,7 @@ export default async (path: string, html: string) => {
 | 无页面模块（`routes: []`） | 同 `web/src/notification/entry.ts` |
 | handler `.schema` 入参 + 平级 `.response` 出参写法（GET + POST、参数段） | `api/src/notification/api.ts`、模板 `packages/cli/templates/api/src/notification/api.ts` |
 | handler 写法（嵌套组列表 / 写入 / 403 归属） | `api/src/notification/api.ts`（模块根单文件，`read`/`read-all`/`clear` 子组） |
+| 统一异常出口 `respond()`（service 抛 `Error & {status}` → 信封 `json.fail`） | 模板 `api/src/_platform/_shared/respond.ts` + 各 handler 用法（§1.7-1） |
 | 生成物长什么样（含工厂） | `web/src/notification/__client/api.ts` |
 | 建表三件套 | `api/src/notification/{schema.yaml,manifest.yaml,migrations/}` |
 | 全局类型（`window.$message` 等） | 工程根 `env.d.ts` |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@oj-module/cli",
   "type": "module",
-  "version": "0.1.21",
+  "version": "0.2.1",
   "description": "React Antd Admin 模块工程命令行工具（含预构建宿主 shell-dist）",
   "license": "MIT",
   "exports": {
@@ -49,7 +49,7 @@
   ],
   "dependencies": {
     "@faker-js/faker": "^10.4.0",
-    "@oj-module/runtime": "0.1.21",
+    "@oj-module/runtime": "0.2.1",
     "@redocly/cli": "^2.51.0",
     "@tailwindcss/vite": "^4.3.0",
     "esbuild": "^0.28.2",

package/shell-dist/assets/{index-BUyoDvUl.js → index-CLdhl3Qd.js}

@@ -4,6 +4,7 @@ import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 import { ConfigProvider, theme } from "antd";
 import { useEffect, useState } from "react";
 import { createRoot } from "react-dom/client";
+import { useTranslation } from "react-i18next";
 import { Navigate, Outlet, RouterProvider, createBrowserRouter } from "react-router";
 import { jsx, jsxs } from "react/jsx-runtime";
 //#region \0vite/modulepreload-polyfill.js
@@ -141,15 +142,55 @@ var DEMO_USER = {
 	description: "manager",
 	roles: ["admin"]
 };
-useUserStore.setState(DEMO_USER);
 /**
-* 登录/登出都会经 auth store reset() 清空 user store；宿主链无 AuthGuard
-* 重新拉取 userInfo，播种丢失后头部用户名/角色恒为空。这里在 token 变化
-* 时重播种演示用户（模块路由的重登记由 access store reset() 快照机制负责）。
+* 定角色：宿主链**没有 AuthGuard**（免登录演示能力绕开 LayoutRoot），没有任何
+* 机制拉 `/web/user-info`，于是 user store 的 roles 恒为演示值或空——而模块路由
+* 的角色过滤（B16，`config.requiredRoles`）与 superadmin 类前端判断都读它。
+* 后果实测：seed 的 admin 账号（roles=["superadmin"]）被 `["admin"]` 挡在
+* /system 路由外（404），成员资格入口也判不出来。
+*
+* - 有 token = 真实登录链 → 拉真实角色（must_change 悬挂期该端点仍返回 200）；
+*   失败则清空，不让演示角色冒充真实权限（401 由请求层兜底跳登录）；
+* - 无 token = 演示态 → 播种 DEMO_USER（与 App 链 fake 数据一致，两链显示同构）。
+*/
+async function hydrateUser() {
+	if (!useAuthStore.getState().token) {
+		useUserStore.setState(DEMO_USER);
+		return;
+	}
+	try {
+		await useUserStore.getState().getUserInfo();
+	} catch (e) {
+		console.warn("[shell] /web/user-info 拉取失败，角色置空", e);
+		useUserStore.getState().reset();
+	}
+}
+/**
+* 登录/登出都会经 auth store reset() 清空 user store（宿主链无 AuthGuard 重新
+* 拉取），token 变化即重新定角色。
+*
+* 已知偏差：角色变化只影响渲染期判断，侧栏菜单是 Boot 期按当时角色登记的，
+* 不登录直接进站再登录的场景菜单需刷新一次才对（后端 403 硬兜底，不是权限泄漏）。
 */
 useAuthStore.subscribe((state, prev) => {
-	if (state.token !== prev.token) useUserStore.setState(DEMO_USER);
+	if (state.token !== prev.token) hydrateUser();
 });
+/**
+* 直链兜底页（catch-all 路由元素）。无匹配路由时渲染框架 `PageError`，
+* 把 title 设为框架 404 文案（`exception.notFoundTitle` = "404"），
+* 观感与无权限面板同构，替代 React Router 默认的「Unexpected Application Error!」。
+* 仅作观感兜底，权限判定仍由后端 403 硬执行。
+*/
+function CatchAll() {
+	const { t } = useTranslation();
+	return /* @__PURE__ */ jsx(PageError, {
+		error: {
+			status: 404,
+			message: t("exception.notFoundTitle")
+		},
+		resetErrorBoundary: () => {}
+	});
+}
 var i18nReady = false;
 function ensureI18n() {
 	if (!i18nReady) {
@@ -193,6 +234,7 @@ function Boot() {
 					document.head.appendChild(link);
 				}
 				const manifest = toLoaderManifest(list, runtimeVersion);
+				await hydrateUser();
 				await loadAll(manifest);
 				if (cancelled) return;
 				setRouter(createBrowserRouter([{
@@ -201,13 +243,20 @@ function Boot() {
 						FallbackComponent: PageError,
 						children: [/* @__PURE__ */ jsx(LayoutEffects, {}), /* @__PURE__ */ jsx(Outlet, {})]
 					}),
-					children: [{
-						index: true,
-						element: /* @__PURE__ */ jsx(Navigate, {
-							to: getRoutes()[0]?.path ?? "/",
-							replace: true
-						})
-					}, ...getRoutes()]
+					children: [
+						{
+							index: true,
+							element: /* @__PURE__ */ jsx(Navigate, {
+								to: getRoutes()[0]?.path ?? "/",
+								replace: true
+							})
+						},
+						...getRoutes(),
+						{
+							path: "*",
+							element: /* @__PURE__ */ jsx(CatchAll, {})
+						}
+					]
 				}]));
 			} catch (e) {
 				if (!cancelled) setError(e instanceof Error ? e.message : String(e));