@oj-module/cli 0.1.16 → 0.1.20

package/devkit/manual.md

@@ -103,7 +103,7 @@ web/src/<模块名>/
 ├── entry.ts          # 元数据唯一来源（没有 package.json / meta.json）
 ├── pages/            # 页面组件（按需）
 ├── locales/          # zh-CN.json / en-US.json（按需）
-└── client/           # ojm api 生成物（勿手改）
+└── __client/         # ojm api 生成物（勿手改）
 ```
 
 ### 2.2 两步缺一不可
@@ -114,8 +114,8 @@ web/src/<模块名>/
 > 模板真出过这个 bug：模块文件都在，就是忘了登记，结果模块安静地没加载、
 > 按钮安静地灰着，**全程没有一个报错**。写完模块第一件事就是检查 `web.config.ts`。
 
-**建档顺序很重要**（有接口的模块）：先写 `contract.ts` → 跑 `ojm api` → 再写 `entry.ts`。
-生成前 `import { createXxxClient } from "./client/api"` 必然 ts 报红，
+**建档顺序很重要**（有接口的模块）：先写 handler 的 `.schema` → 跑 `oj openapi` + `ojm api` → 再写 `entry.ts`。
+生成前 `import { createXxxClient } from "./__client/api"` 必然 ts 报红，
 那不是你写错了，是产物还没生成。完整流水线见 §3.4。
 
 ```ts
@@ -143,7 +143,7 @@ import { BookOutlined } from "@ant-design/icons";
 import { defineModule } from "@oj-module/runtime";
 import { createElement, lazy } from "react";
 
-import { createBooksClient } from "./client/api";
+import { createBooksClient } from "./__client/api";
 
 const Books = lazy(() => import("./pages/index"));
 
@@ -240,7 +240,7 @@ export default defineModule({
 可服务的同源路径）。直接 `import "vditor/dist/..."` 其它深路径会命中前缀 external 但无
 importmap 键，构建期报错——需要新深路径请联系框架方在共享表登记。
 
-### 2.7 本版本共享依赖钉版（0.1.16 快照）
+### 2.7 本版本共享依赖钉版（0.1.20 快照）
 
 宿主经 importmap 提供以下单例（模块 `devDependencies` 须对齐，供 `tsc` 用）；完整 68 项矩阵以
 `pnpm exec ojm info` 或 `packages/cli/shell-dist/versions.json`（构建期生成）为准。
@@ -269,8 +269,10 @@ importmap 键，构建期报错——需要新深路径请联系框架方在共
 | `pinyin-pro` | 3.29.3 |
 | `vditor` | 4.0.0 |
 
-框架包版本：`@oj-module/runtime` / `@oj-module/cli` / `@plane/kit` / `@plane/editor` 均为 `0.1.16`
-（lockstep；本版实际改动仅 cli——vditor 入共享表）；`oj` 二进制最低版本门禁 `MIN_OJ_VERSION = 0.1.50`。
+框架包版本：`@oj-module/runtime` / `@oj-module/cli` / `@plane/kit` / `@plane/editor` 均为 `0.1.20`
+（lockstep）；`oj` 二进制最低版本门禁 `MIN_OJ_VERSION = 0.1.73`——契约流水线要求 oj ≥ 0.1.73：
+平级 `.response` 出参声明位自 v0.1.72 起、`oj openapi` 的 `del`→`delete` 操作键归一自 v0.1.73 起
+（低版本 oj 生成 `openapi.json` 会丢出参类型或产出非法 `"del"` 键，`ojm api --check` 必漂移）。
 
 > **`@oj-module/runtime` 到底导出哪些东西？** 权威清单随包发布在
 > `node_modules/@oj-module/runtime/dist/index.d.ts`——直接 Read 它，或在编辑器里
@@ -285,94 +287,128 @@ importmap 键，构建期报错——需要新深路径请联系框架方在共
 
 ### 3.1 一句话
 
-`ojm api` 读**契约文件**（`contract.ts`），一次性生成前端调用代码、接口元数据、
-后端 handler 骨架，让"前端调用的函数"与"后端暴露的路由"永远同源。
+新版「契约代码生成」的**唯一权威源是 `oj` handler 上的 `.schema`（入参）+ `.response`（出参）**，
+不再有 `contract.ts` / `defineApi`（旧 DSL + zod 翻译层已退役删除）。开发者在 handler 上手写
+`.schema`（JSON Schema 严格子集）与平级 `.response`（`json.ok(data)` 的 data 载荷），
+`oj v0.1.73+` 的 `oj openapi` 运行期内省并产出 `openapi.json`（OpenAPI 3.1，落工程根）；
+`ojm api` 消费它生成前端 `__client`。整条链路：
 
 ```
-contract.ts ──evaluate──► IR ──emit──► 四产物 + stub
+oj handler .schema（入参，手写）+ .response（出参，平级）——唯一权威源
+        │  oj 内省（含组级 .schema / .response 继承合并）
+        ▼
+oj openapi -c config -d api/src -b /api -o openapi.json   →  OpenAPI 3.1
+        │
+        ▼
+ojm api   →  irFromOpenapi  →  emitZodFromJsonSchema / emitClient
+        │
+        ▼
+web/<模块>/__client/{api.ts, api.schemas.ts}（+ stub / mock）
 ```
 
-### 3.2 契约 discovery 与产物落点
+`openapi.json` 即权威文档源，`ojm api --docs` 直接聚合它渲染文档站。`.schema` / `.response`
+写法、与 zod 表达力对照等后端侧细节见 `oj-api-dev` skill 的手册（`ojm init` 已装机在
+`.claude/skills/oj-api-dev/`，随 oj 二进制更新）的「入参与出参契约 `.schema`」章节；
+本文只讲它到前端这一侧的对接。
 
-| 工程形态 | 契约位置 | 产物流向 |
+> 版本要求：平级 `.response` 声明位自 **oj v0.1.72** 起支持；`oj openapi` 把 `del` 动词归一为
+> `delete` 操作键自 **v0.1.73** 起（含 `del` 端点的工程须 ≥ 0.1.73，否则 `--check` 必漂移）。
+> 旧 `.schema.response` 写法继续生效（存量零破坏），新工程一律用平级 `.response`。
+
+> 旧 `contract.ts` / `defineApi` 工程：翻译层已删除，`ojm api` **不再兼容读取** `contract.ts`
+> （找不到 `openapi.json` 即报错）。迁移方法见 **§3.10**（本手册自包含迁移指南）。
+
+### 3.2 产物落点（新口径）
+
+| 工程形态 | 权威源 | 产物流向 |
 |---|---|---|
-| **uni-dev**（前后端一体，推荐） | `api/src/<模块>/contract.ts` | `api.ts` / `api.schemas.ts` → `web/src/<模块>/client/`；`routes.json` / `openapi.yaml` → 契约旁；stub → `api/src/<模块>/<路径>/api.ts` |
-| 纯前端 | `web/src/<模块>/client/contract.ts` | 四产物全部落契约同目录，无 stub |
+| **uni-dev**（前后端一体，推荐） | 后端 `api/src/<模块>/**/api.ts` 上的 `.schema` | `web/src/<模块>/__client/{api.ts, api.schemas.ts}`（由 `ojm api` 消费 `openapi.json` 生成）；stub → `api/src/<模块>/<路径>/api.ts`（未实现 handler 时补骨架） |
+| 纯前端 | 仅消费他人 `openapi.json` | `__client/` 全部落前端侧，无 stub |
 
-**硬约束**：uni-dev 形态下每个端点的 `apiPrefix` 必须**字面等于**后端目录名
-（`api/src/order/contract.ts` → `/order`），不符即人话报错。
+`openapi.json` 是项目级单文件、含全部模块，由 `oj openapi` 产出，ojm 不再自产 `routes.json` /
+`openapi.yaml`。
+
+**硬约束**：模块目录名即 API 前缀来源——`api/src/order/**` → 线上前缀 `/order`（与旧 `apiPrefix`
+字面相等约束同源，只是现在由目录名推导，不再手写字段）。不符即人话报错。
 
 > 工程里有两个 "web"：前端 `web/`，与后端 `api/src/web/`（提供 user-info 等内置接口）。
 > 豁免清单里的 `"modules": ["web"]` 指的是**后者**。
 
-### 3.3 defineApi 字段
+### 3.3 handler `.schema`（入参）+ `.response`（出参）写法（JSON Schema 子集）
 
-```ts
-import { defineApi, z } from "@oj-module/runtime/contract";
-
-const book = z.object({ id: z.number(), title: z.string() });
-
-export const listBooks = defineApi({
-	apiPrefix: "/books",              // 必填，"/" 开头
-	route: "/list",                   // 必填，"/" 开头，相对 apiPrefix
-	method: "GET",                    // 缺省 "GET"
-	query: z.object({ keyword: z.string().optional() }),
-	data: z.object({ list: z.array(book), total: z.number() }),
-	ignoreLoading: true,              // 该端点不触发全局加载条
-	description: "图书列表",           // 进 OpenAPI
-});
-
-// 另两个按需字段：
-//   params: z.object({ id: z.number() })  —— 与 route 的 {id} 参数段一一对应
-//   body: z.object({ title: z.string() }) —— 请求体（JSON）
-//   response: "raw"                       —— 二进制/非信封的例外通道，与 data 互斥
-```
+> 旧 `defineApi` / `contract.ts` 已删除。现在契约直接写在 oj handler 的动词上——这是唯一权威源。
 
-**上传文件（multipart/form-data）** —— `form`，与 `body` 互斥：文本字段走
-`form.fields`（zod，字段名即表单部件名），文件部件只声明 `name` / `required` /
-`multiple`（二进制进不了 JSON Schema，也不进白名单）：
+每个动词（含嵌套组动词、子目录 handler）挂 `.schema` 放**入参**（三通道，对应旧
+`params/query/body`）；**出参**走与 `.schema` 平级的 `.response`（oj v0.1.72+，对应旧
+`defineApi` 的 `data`）：
 
 ```ts
-export const uploadAvatar = defineApi({
-	apiPrefix: "/personal-center",
-	route: "/upload",
-	method: "POST",
-	form: {
-		fields: z.object({ note: z.string().optional() }),
-		files: [{ name: "avatar", required: true }, { name: "gallery", multiple: true }],
+// api/src/order/list/api.ts（oj v0.1.72+ 写法，.schema / .response 手写，勿由工具生成）
+function get() {
+	// ...业务逻辑，json.ok(...) / json.fail(...)
+}
+get.schema = {
+	query: {                       // 入参 query（旧 defineApi 的 query）
+		type: "object",
+		required: ["page"],
+		properties: { page: { type: "number", minimum: 1 } },
 	},
-	data: z.string(),                 // 上传端点照例可以带响应 data
-});
+};
+get.response = {                  // 出参 data 载荷（旧 defineApi 的 data），与 .schema 平级
+	type: "object",
+	properties: { list: { type: "array", items: { type: "object" } }, total: { type: "number" } },
+};
 
-// 调用形态（生成 client 内部组装 FormData）：
-// await uploadAvatar({ fields: { note: "合同扫描件" },
-//                      files: { avatar: file, gallery: [f1, f2] } });
+export default { get };
 ```
 
-**不要手写 `content-type`**：运行时（ky）见到 `FormData` 会自己补
-`multipart/form-data; boundary=…`。后端 handler 侧用 `http.files`（元数据）/`http.file(i)`
-（字节）读文件，文本字段写入 `http.body.<name>`。
-
-文本字段的取值：标量按 `String()` 发；**对象/数组自动 `JSON.stringify`**（多部件文本只能是
-字符串，直接 `String({a:1})` 会静默变 `[object Object]`）。后端从 `http.body.<name>` 拿到的是
-JSON 文本，需要结构就自己 `JSON.parse`（或干脆用单独的 JSON 端点发结构化数据）。
-
-**定义期就会抛错**的写法（早炸好过晚炸）：
-
-- `apiPrefix` / `route` 不以 `/` 开头；`route` 含 `../`、`./`、`\`；
-- 参数段混字面：`{id}.json` 非法（matchit 约束——参数段必须**整段**为 `{name}` 或 `{*name}`，要前后缀就拆成静态多段）；
-- `data` 与 `response: "raw"` 同时出现；
-- `response` 取 `"raw"` 以外的值；
-- `method: "OPTIONS"`（不在支持范围）；
-- `method: "HEAD"` 且声明了 `data`（HEAD 无响应体）；
-- `form` 与 `body` 同时出现；`form` 既无 `fields` 也无 `files`；`form.files` 缺 `name` 或字段名重复（重名要用 `multiple: true`）；`form.fields` 不是 `z.object`。
+`.schema` 入参三通道：
 
-`data` 过**类型白名单**：不返回数据的接口**直接省略 `data`**，
-写 `z.null()` 或 transform / refine 会被拒。校验放后端做。
+| 通道 | 含义 | 对应旧字段 |
+|---|---|---|
+| `params` | 路径参数（与 route 的 `{id}` 段对应） | `params` |
+| `query` | URL query | `query` |
+| `body` | JSON 请求体 | `body` |
+
+`.response`（平级）语义与旧 `.schema.response` 完全相同：响应 `data` 载荷（信封
+`code/msg/data` 由 oj 自动包裹），对应旧 `data`。**优先级**（高 → 低）：动词 `.response` >
+组 `.response` > 动词 `.schema.response` > 组 `.schema.response`；组级沿嵌套层层继承。
+⚠️ 保留键：组对象上的 `response` 被当声明读走，不能用来命名嵌套子组（与 `schema`/`route` 相同）。
+
+**`.schema` 是 oj JSON Schema 白名单子集**，关键字仅限：
+`type / required / properties / items / additionalProperties / minimum / maximum /
+minLength / maxLength / pattern / enum / nullable / minItems / maxItems / default`。
+白名单外关键字（`$ref` / `oneOf` / `format` / `transform` 等）**fail-fast**，不静默降级。
+
+- **`pattern` 是 Rust regex**：oj 运行期用于校验；ojm 生成前端 zod 时**不进运行时**
+  （跨语言语义漂移 + ReDoS 风险），仅发 `// @oj-warn` 注释。需严格校验请下移到 handler。
+- **`default` 不射前端 zod `.default()`**：oj 运行期不为缺参补默认值；前端若补会让可选字段
+  变必填、掩盖契约漂移。仅发 `// @oj-note` 注释。
+- **`nullable` / 类型数组**：`{ type: ["string", "null"] }` → 前端 `z.string().nullable()`；
+  表达 union（如 `z.union([z.string(), z.number()])`）用类型数组 `["string", "number"]`
+  （oj 白名单不支持 `oneOf`/`anyOf`）。
+- **`additionalProperties: false`** → 前端 `.strict()`；`true` → `.catchall(z.unknown())`。
+- 所有动态键名 / 枚举值经 `JSON.stringify` 字面量注入，防注入。
+
+**端点方法名 / 类型名来自 `operationId`**（oj 由「去 base 子路径 + 方法」派生，非字母数字转 `_`）：
+`order/list` + `get` → `order_list_get` → 前端 `orderListGet`、`OrderListGetData`、
+`OrderListGetQuery` 等。这与旧 `defineApi` 的人类命名（`listBooks`）不同，迁移时用「逐字节比对」
+识别为丢失面（见 §3.10）。
+
+**上传文件（multipart/form-data）**：当前 `ojm api` 的 openapi 流水线**不生成** form 通道的
+前端 client（文件部件是二进制，不进 JSON Schema）。惯例走 antd `Upload` **直连**后端
+（不经 JSON client），handler 用 `http.files` / `http.file(i)` 读字节，仅平级声明
+`.response`（见 `api/src/personal-center/upload/api.ts` 范本）。
+
+**不要手写 `content-type`**：运行时（ky）见到 `FormData` 会自己补 `multipart/form-data;
+boundary=…`，手写反而丢 boundary。
+
+> 不返回数据的接口：**省略 `.response`** 声明（而非写空对象）。校验一律放后端（`.schema` 在 oj
+> 侧于 handler 调用前校验入参，违反即 `400`，handler 不被调用）。
 
 ### 3.4 生成物使用契约
 
-生成的 `web/src/<模块>/client/api.ts` 导出：
+生成的 `web/src/<模块>/__client/api.ts` 导出：
 
 - 裸请求函数（`fetchNotifications`、`markRead`…）——**直接 import 调用**；
 - `API_PREFIX` 常量——契约前缀的唯一真源；
@@ -393,12 +429,12 @@ const booksClient = createBooksClient(ctx);
 - 忘创建就调裸函数 → 人话报错「请求未绑定」，指路 `create<Module>Client(ctx)`。
 - 重复构造幂等安全；`onInit` 每模块只跑一次（HMR / StrictMode 不重复执行）。
 
-> **生成 ≠ 使用。** `ojm api` 为**每个** `api/src/<模块>/contract.ts` 生成
-> `web/src/<模块>/client/`，**不看有没有人 import**。所以「契约在、`client/`
-> 目录却不在」只有一种解释：那个模块的 `client/` 从没生成过（模板里的
-> personal-center 就是这样——它上传走 antd Upload 直连 `uploadApi.action`，
-> 生成出来也没人用，故模板没签回）。你在自己工程跑一次 `ojm api`，它就会出现。
-> 判断某模块**要不要用** client 的标准只有一个：代码里有没有人 import `./client/api`。
+> **生成 ≠ 使用。** `ojm api` 为 **openapi.json 里出现的每个模块**（`tags[0]`）生成
+> `web/src/<模块>/__client/`，**不看有没有人 import**。所以「handler 在、`__client/`
+> 目录却不在」只有一种解释：那个模块的 `__client/` 从没生成过（模板里的
+> personal-center 上传走 antd Upload 直连，不经过 JSON client，故没人 import 它的 `__client`）。
+> 你在自己工程跑一次 `ojm api`，它就会出现。
+> 判断某模块**要不要用** client 的标准只有一个：代码里有没有人 import `./__client/api`。
 > 有就在 onInit 里 `create<Module>Client(ctx)` 一次；没有就什么都不写，
 > 生成了但没人 import 也不报错。
 
@@ -409,68 +445,77 @@ const booksClient = createBooksClient(ctx);
 
 ### 3.5 生成物勿手改
 
-`client/api.ts`、`client/api.schemas.ts`、`routes.json`、`openapi.yaml`
-**重跑即覆盖**（eslint 已忽略这些路径）。改需求 = 改契约，重跑 `ojm api`。
+`__client/api.ts`、`__client/api.schemas.ts` **重跑即覆盖**（eslint 已忽略这些路径）。
+改需求 = 改 handler 的 `.schema`（或路由），重跑 `oj openapi` + `ojm api`。
 
 **唯一例外：stub。** `api/src/**/api.ts` 的 stub 文件头带指纹
 （`// ojm-api:stub <name> sha256:...`）。人碰过的 stub，工具**永不写永不删**——
-实现 handler 就是在 stub 里填业务逻辑。
+实现 handler 就是在 stub 里填业务逻辑（`.schema` 由开发者手写，工具不注入）。
 
 生成是**幂等**的：内容逐字节比对，无变化不写盘，重复跑 `ojm api` 的 git diff 为空。
 
-命名规则：生成的函数名 = 契约导出名（`listBooks`）；类型名 = 导出名 PascalCase +
-`Query` / `Body` / `Form` / `Data`（`ListBooksQuery`、`CreateBookBody`、`UploadAvatarForm`、`ListBooksData`）。
+命名规则：生成的函数名 = `camelCase(operationId)`（如 `orderListGet`）；类型名 =
+PascalCase(operationId) + `Query` / `Params` / `Body` / `Data`
+（`OrderListGetQuery`、`OrderListGetData` 等）。这与旧 `defineApi` 的人类导出名（`listBooks`）
+不同。
 
 ### 3.6 命令
 
 ```bash
-pnpm exec ojm api          # 生成
-pnpm exec ojm api --check  # 四重对账（只读，永不修文件）
-pnpm exec ojm api --docs   # 聚合 OpenAPI → redoc 静态站
+# 1) oj 产出 OpenAPI 规范（base 从 config 的 api 挂载前缀读；dev 用 -d api/src 内省）
+oj openapi -c api/config.yaml -d api/src -b /api -o openapi.json
+# 2) ojm 消费生成前端 __client（按 tags[0] 分组到各模块）
+pnpm exec ojm api
+# 3) 校验同步 / route 双向对账（只读）
+pnpm exec ojm api --check
+# 4) 聚合 openapi.json → redoc 静态文档站
+pnpm exec ojm api --docs
 ```
 
+> `oj openapi` 是 **oj 透传命令**（ojm 自动补 `-c api/config.yaml`），参数照 oj 原版语义。
+> 找不到 `openapi.json` 时 `ojm api` 直接报错指引先跑 `oj openapi`（旧 `contract.ts` 不兼容读取）。
+
 `--check` 对四件事（只读，绝不写盘、绝不修文件）：
 
-1. **生成物同步**：内存重生成 vs 磁盘逐字节 diff（含 stub 待更新检测）；
-2. **route 双向对账**：AST 扫后端 `api.ts`（default 导出方法名 + `.route = "..."`
-   赋值）vs 契约路由表——契约未实现 warn、handler 未登记 error、参数段不一致 error；
-3. **`routes.js` diff**：`oj build` 产物路由表 vs `routes.json`；无 dist 给提示不判违规；
+1. **生成物同步（artifact-stale）**：内存重跑 `ojm api` vs 磁盘逐字节 diff（`__client/{api.ts,api.schemas.ts}`）；
+2. **route 双向对账**：生成物端点 ⊄ handler 已实现表 → `route-not-implemented`；handler 表 ⊄ 生成物 → `route-unregistered`（参数段不一致 error）；
+3. **`routes.js` diff**：`oj build` 产物路由表 vs 生成物；无 dist 给提示不判违规；
 4. **WS 路由鉴权**：目录里的 `ws.ts` 会产生 `GET {base}/<模块>/<路径>/ws`——oj v0.1.30 起
    WS 握手也过鉴权守卫，不在 `auth.anonymous_paths` 里的 WS 会让未带凭据的客户端握手 401
    （表现为「文件在却连不上」）。只 warn（带 Bearer/Cookie 的受保护 WS 是正当用法）；
    读不到 config 就不判。
 
-`ojm dev` 内置契约 watch：契约文件变更 → 自动重跑生成 → 产物写入 `web/` 树
-触发模块重建 + 浏览器刷新。
+`ojm dev` 内置 `openapi.json` 变更 watch：规范变更 → 自动重跑 `ojm api` → 产物写入 `web/` 树
+触发模块重建 + 浏览器刷新。改完 handler `.schema` 需先重跑 `oj openapi` 更新规范。
 
-> ⚠️ **新模块目录的诞生不在 watch 范围**——新建模块的 `contract.ts` 要先重启
-> `ojm dev`（目录注册发生在启动期），之后该模块的契约改动才走热更。
+> ⚠️ **新模块目录的诞生不在 watch 范围**——新建后端模块目录要先重启
+> `ojm dev`（目录注册发生在启动期），之后该模块的 `.schema` 改动才走热更。
 
-### 3.7 后端入参契约（`.schema`，v0.1.44）
+### 3.7 后端入参契约（`.schema`，v0.1.44+ 手写）
 
-契约里声明的 `params` / `query` / `body` 不只生成前端类型与校验——`ojm api` 还会把
-它们落成后端 handler 上的 `.schema`，由 oj 在 **JS 之前**校验：违反即 `400` 信封，
-handler 根本不会被调用。于是**一份契约同时给出**：前端 client 与类型、前端 DEV 期 zod
-校验、后端入参校验、OpenAPI 文档。
+`.schema` 是**开发者手写**在 handler 动词上的（见 §3.3），oj 在 **JS 之前**校验入参：违反即
+`400` 信封，handler 根本不会被调用。于是**一份 `.schema` 同时给出**：oj 运行期入参校验、
+前端 DEV 期 zod 校验、OpenAPI 文档——前端 client 类型则来自 `oj openapi` 产出的 `openapi.json`。
 
 ```ts
-// api/src/order/list/api.ts（ojm api 生成，勿手改正文外的部分）
+// api/src/order/list/api.ts（.schema 由开发者手写，oj 运行期据此校验入参）
 function get(): void {
 	json.ok({ /* TODO */ });
 }
 get.schema = {
-	"query": {
-		"type": "object",
-		"properties": { "page": { "type": "number", "minimum": 1 } },
-		"required": ["page"]
-	}
+	query: {
+		type: "object",
+		properties: { page: { type: "number", minimum: 1 } },
+		required: ["page"],
+	},
 };
 export default { get };
 ```
 
 开关在 `api/config.yaml` 的 `server.schema_validation`（默认 `true`，置 `false` 为逃生门）。
-完整裁剪规则与降级表（白名单无 `format`/`oneOf`、Rust regex 不支持零宽断言、
-params/query 只允许扁平标量等）都在生成期拦下或告警，详情见 §3.3 的「定义期就会抛错」清单。
+白名单裁剪规则与降级（无 `format`/`oneOf`、Rust regex 不支持零宽断言、params/query 只允许扁平
+标量等）在 `oj openapi` 内省期或 ojm 生成期 fail-fast / 告警，详情见 §3.3 与 `oj-api-dev` skill
+手册（`.claude/skills/oj-api-dev/`）。
 
 ### 3.8 豁免清单 `api/.ojm-api-exempt.json`
 
@@ -486,6 +531,71 @@ params/query 只允许扁平标量等）都在生成期拦下或告警，详情
 
 文件缺失或损坏时静默按空豁免处理。cli ≥ 0.1.5 的 `ojm init` 已内置该文件。
 
+### 3.9 DDD 判据速查（oj v0.1.64 嵌套 handler 组）
+
+| 场景 | 形态 |
+|---|---|
+| 同聚合多动词 | 单文件嵌套组（组名 = 路径段，`const login = { async post() {...} }`） |
+| 不同聚合 | 各自目录/文件 |
+| ≤3 动词单一聚合 | 可平铺单文件 |
+
+规则与红线：组名即路径段（`login` → `POST /auth/login`，路由不变）；嵌套 ≤4 层；
+`route`/`schema` 是保留键；**`del` 是保留动词键，不能作组名**（删通知这类端点目录
+`del/` 是唯一例外形态）；组名可连字符（`"push-broadcast"`），checker 已支持字符串字面量键对账。
+
+反例信号：文件过胖 = 聚合过胖，**拆聚合而不是回退动词目录**；出现动词子目录
+（`read/api.ts` 这类）说明是旧形态，按上表 reshape。
+
+### 3.10 从旧 `contract.ts` / `defineApi` 工程迁移
+
+适用于 0.1.20 之前、用「`api/src/<模块>/contract.ts`（`defineApi` + zod）」声明契约的工程。
+翻译层已删除，`ojm api` 不再读取 `contract.ts`——不迁移则找不到 `openapi.json` 直接报错。
+
+**前置条件**
+
+- `oj` ≥ **0.1.73**（`oj openapi` 子命令 + 平级 `.response` + `del`→`delete` 归一；低版本会丢出参类型或产出非法方法键）
+- `@oj-module/cli` / `@oj-module/runtime` ≥ **0.1.20**（lockstep）
+- `api/config.yaml` 站点挂载已是顶层 `mounts:`（oj v0.1.58 起旧键 fail-fast）
+
+**字段映射（旧 `defineApi` → 新声明位）**
+
+| 旧 `defineApi` 字段 | 新声明位 | 说明 |
+|---|---|---|
+| `route` / `method` | handler 所在目录/文件名 + 动词函数名 | 路由由目录镜像推导，不再手写（AC-D9） |
+| `params` | `.schema.params` | 路径参数，与 route 的 `{id}` 段对应 |
+| `query` | `.schema.query` | URL query |
+| `body` | `.schema.body` | JSON 请求体 |
+| `data` | **平级 `.response`** | 出参 data 载荷（信封 `code/msg/data` 由 oj 自动包裹） |
+| `form` | —（丢失面） | 文件上传，当前流水线不生成前端 client，改 antd `Upload` 直连 |
+| `raw` | —（丢失面） | `openapi.json` 不携带 raw 标记，需人审 |
+| `ignoreLoading` | —（丢失面） | 透传标记，需人审 |
+
+**迁移步骤**
+
+1. **盘点**：列出每个 `contract.ts` 的全部端点（route / method / 入参 / data / form / raw / ignoreLoading）。
+2. **翻译**：对每个端点在对应 handler 动词上写 `.schema`（入参，JSON Schema 白名单子集）+
+   平级 `.response`（出参）。zod → JSON Schema 手工对照：`z.string()` → `{type:"string"}`、
+   `z.number()` → `{type:"number"}`、`z.enum([...])` → `{type:"string", enum:[...]}`、
+   `z.union([z.string(),z.number()])` → 类型数组 `["string","number"]`、`.nullable()` →
+   `["string","null"]`；`refine`/`transform` 必须下移到 handler 校验（丢失面）。
+3. **生成规范**：`oj openapi -c api/config.yaml -d api/src -b /api -o openapi.json`
+   （项目级单文件、含全部模块；组级 `.schema`/`.response` 已由 oj 内省期合并）。
+4. **生成 client**：`ojm api` → `web/src/<模块>/__client/{api.ts, api.schemas.ts}`。
+5. **改前端消费点**：函数名从旧人类命名（`fetchNotifications`）改为
+   `camelCase(operationId)`（`notificationNotificationsGet`）——用「逐字节比对」识别，
+   逐个改 import 与调用；`tsc --noEmit` 应收敛到 0 错误。
+6. **删旧文件**：删除各 `contract.ts`，以及旧流水线产物 `api/src/<模块>/routes.json`、
+   `api/src/<模块>/openapi.yaml`（ojm 不再自产；`api/docs/openapi.yaml` 仅 `--docs` 时生成，保留）。
+7. **对账**：`ojm api --check` 应 `0 error / 0 warn`；内置端点（`auth/*`、`web/*`、
+   `notifications`）经 `api/.ojm-api-exempt.json` 豁免（init 已内置）。
+
+**迁移后自检**
+
+- [ ] 工程根有 `openapi.json`，`--check` 零漂移
+- [ ] 每个 `__client` 的 `XxxData` 类型非 `unknown`（出参声明生效）
+- [ ] 无 `contract.ts` / per-module `routes.json` / `openapi.yaml` 残留
+- [ ] `ojm dev` 起服后接口联调通过（登录 / 列表 / 写操作 / 401）
+
 ---
 
 ## §4 接管框架内置功能（provider）
@@ -539,22 +649,34 @@ Provider 就是：「这块别用框架自带的了，换成我的实现。」
 
 ### 4.4 案例：接管通知功能（标准四文件）
 
-**① 契约**（`api/src/notification/contract.ts`）——见 §3.3 与 §3.4。
+**① handler `.schema`**（`api/src/notification/api.ts` 上各动词挂的 `.schema`）——见 §3.3 与 §3.4。
 
-**② handler**（`api/src/notification/notifications/read/api.ts`）：
+**② handler**（`api/src/notification/api.ts`，模块根嵌套组——组名 = 路径段，oj v0.1.64）：
 
 ```ts
-export default {
-	async post() {
-		const body = (http.body ?? {}) as { id?: unknown };
-		const id = Number(body.id);
-		if (!Number.isFinite(id)) { json.fail(400, "id is required"); return; }
-		await db.query("UPDATE notifications SET is_read = 1 WHERE id = ?", [id]);
-		json.ok(null);
+const notifications = {
+	// POST /api/notification/notifications/read —— 单条通知已读。
+	// body.id 为命名空间串 "u:<id>"（按人）/"b:<id>"（广播）；按人项校验归属，非本人 403。
+	read: {
+		async post() {
+			const uid = http.user?.id;
+			if (!uid) { json.fail(401, "unauthorized"); return; }
+			const body = (http.body ?? {}) as { id?: unknown };
+			const id = String(body.id ?? "");
+			if (!id) { json.fail(400, "id is required"); return; }
+			const ok = await markRead(id, uid);
+			if (!ok) { json.fail(403, "forbidden"); return; }
+			json.ok(null);
+		},
 	},
+	// read-all / clear 子组同理（全部已读 / 清空，按当前用户）
 };
+
+export default { notifications, /* push, "push-broadcast" 等同理 */ };
 ```
 
+> reshape 判据与嵌套组规则（保留键、层级上限）见 §3.9「DDD 判据速查」。
+
 **③ 生成**：`pnpm exec ojm api`
 
 **④ 对接**（`entry.ts`）：
@@ -562,7 +684,7 @@ export default {
 ```ts
 import type { NotificationsApiProvider } from "@oj-module/runtime";
 import { defineModule } from "@oj-module/runtime";
-import { createNotificationClient } from "./client/api";
+import { createNotificationClient } from "./__client/api";
 
 export default defineModule({
 	name: "notification",
@@ -584,13 +706,54 @@ export default defineModule({
 });
 ```
 
+**⑤ 跨模块发射原语（任何后端模块都能推通知）**
+
+通知不是「只有通知模块自己用」的功能——下单、审核、@我等其它模块也需要给某个人推一条提醒。
+把发射逻辑收敛成 `api/src/notification/_shared/notify.ts` 里的纯函数原语，其它模块**相对导入直接调用，
+无需走 HTTP**：
+
+```ts
+// 在其它模块的 handler 里
+import { pushNotice } from "../../notification/_shared/notify";
+
+export default {
+	async post() {
+		// ...业务逻辑...
+		const id = await pushNotice({ userId: 2, title: "你的订单已发货", message: "单号 SO123" });
+		json.ok({ id }); // 返回命名空间 id "u:<id>"
+	},
+};
+```
+
+原语清单（`_shared/notify.ts`，设计文档 §4.3 / §6）：
+
+| 原语 | 作用 | 返回 |
+|---|---|---|
+| `pushNotice({ userId, title, message, link?, avatar?, category? })` | 给指定用户推一条按人通知（一行 `notifications`） | 命名空间 id `"u:<id>"` |
+| `pushBroadcastNotice({ title, message, ... })` | 广播一条（一行 `notifications_broadcast`，全员可见、一行存储） | 命名空间 id `"b:<id>"` |
+| `delNotice(id, userId)` | 删按人项（校验归属，非本人返回 `false`）；广播项仅删本人回执 | `boolean`（是否命中） |
+| `noticesFor(userId)` | 合并列表：广播 LEFT JOIN 回执算 `is_read` UNION 按人 `WHERE user_id=?` | `NoticeItem[]` |
+| `markRead(id, userId)` | 按人项校验归属（非本人 `false` → 端点映射 403）；广播项 upsert 回执 | `boolean` |
+| `markAllRead(userId)` / `clearNotices(userId)` | 全部已读 / 清空（按当前用户） | `void` |
+
+约定：
+- **原语不做业务判断**（不判空间/角色/可见性），收件人过滤是发送方责任（`pushNotice` 的 `userId` 谁都能传，按人隔离靠存储 `user_id` 保证）。
+- **后端不能 `import '@oj-module/runtime'`**：oj 解析裸 specifier 以 `api/` 为项目根并钳制不越界（越界报
+  `escapes project root`）；`@oj-module/runtime` 符号链接在 `packages/runtime`，属项目根之外。原语必须落在
+  `api/src` 内（相对导入）；类型与 runtime 的 `@oj-module/runtime/notify` 保持同形即可，共享契约类型单一真源在 runtime。
+- **`_shared` 必须嵌进所属模块目录**（`api/src/notification/_shared/`），不能放 `api/src/_shared/`——oj 把
+  `api/src` 的**顶层**目录都当模块（须有 `manifest.yaml`），顶层 `_shared` 会被当成缺 manifest 的模块，
+  `oj serve` 直接退（`module '_shared' missing manifest.yaml`）。
+- **归属校验返回 403**：跨用户 `del` / `read` 他人按人项，原语返回 `false`，端点 `json.fail(403, "forbidden")`——
+  与「按人隔离」对称（A 推给 B 后 A 不可见、B 不可删/读 A 的）。
+
 **验证**：`pnpm dev` → `admin / 123456` 登录 → 右上角铃铛有蓝点 → 点开 →
 点任意一条蓝点消失 → 「全部已读」全清 → 「清空」列表变空。
 
 **加接口的通用流水线**：
 
 ```
-写契约 contract.ts → 写 handler api.ts → ojm api 生成 client → entry.ts 里 create client + 注册
+写 handler .schema → 写 handler 业务逻辑(api.ts) → oj openapi + ojm api 生成 client → entry.ts 里 create client + 注册
 ```
 
 ### 4.5 案例：接管头像上传（不写契约的最简入口）
@@ -932,7 +1095,56 @@ useEffect(() => {
 
 > `window.$message` 的类型声明在工程根 `env.d.ts`——那里也放着 `ImportMeta.env` 补丁。
 
-### 6.4 `pnpm typecheck` 看不到 `api/`
+### 6.4 页签与未保存守卫（`beforeClose`，runtime ≥ 0.1.18）
+
+页签有未保存内容时，关闭前弹确认框的完整链路：`addTab` 给页签挂 `beforeClose` 守卫，
+五个关闭动作（单个/右/左/其他/全部）关闭前**顺序 await** 守卫，任一返回 false 或
+抛错则**整批取消**（事务式）。守卫 await 期间页签保留、组件保持挂载，可安全弹 Modal。
+
+```tsx
+const TAB_KEY = "/demo/guard"; // 页签 key = 路由路径
+const [confirmResolver, setConfirmResolver] = useState<((ok: boolean) => void) | null>(null);
+const addTab = useTabsStore(s => s.addTab);
+const dirty = form.isFieldsTouched();
+
+useEffect(() => {
+	addTab(TAB_KEY, {
+		key: TAB_KEY,
+		label: t("demo:menu.guard"),
+		// 守卫应是稳定引用（useCallback 包裹）；去重按函数引用，
+		// keep-alive 重挂载重复注册同一函数不会叠加
+		beforeClose: dirty
+			? () => new Promise<boolean>((resolve) => {
+					setConfirmResolver(() => resolve);
+				})
+			: null, // null 清除该页签全部守卫（含他人注册的）；undefined 不动
+	});
+}, [dirty, addTab, t]);
+
+<Modal
+	open={confirmResolver !== null}
+	onOk={() => { confirmResolver?.(true); setConfirmResolver(null); }}   // 放行关闭
+	onCancel={() => { confirmResolver?.(false); setConfirmResolver(null); }} // 取消关闭
+>
+	有未保存的修改，确定关闭吗？
+</Modal>
+```
+
+约定与陷阱：
+
+- **守卫抛错 = 取消关闭 + console.error**（fail-safe：宁可不关门也不误关丢内容）；
+  页签「怎么点都关不掉」先查控制台 `[tabs] beforeClose` 报错。
+- **批量关闭串行弹 N 个确认框是语义正确结果**（每个有未保存内容的页签都须用户裁决）；
+  任一否决整批回滚。
+- home 页（`VITE_BASE_HOME_PATH`）永不可关、不在守卫范围；`resetTabs`（登出/401 下线）
+  **显式绕过守卫**直接清空——业务守卫不得阻塞下线。
+- **登出/刷新后守卫消失需重挂**：守卫只活在内存 store；重新打开页签时由页面
+  `useEffect` 重新注册（上面的形态天然满足）。
+- 同一 key 关闭流程进行中再次触发被忽略（per-key in-flight 去重），双击不会弹两个框。
+
+可运行示例见 playground-oj `web/src/demo/pages/guard.tsx`（表单 dirty → 关页签弹确认）。
+
+### 6.5 `pnpm typecheck` 看不到 `api/`
 
 工程 `tsconfig.json` 的 `include` 只有 `web`、`web.config.ts`、`global.d.ts`、`env.d.ts`，
 **不含 `api/`**。也就是说契约与 handler 的类型错误 `pnpm typecheck` 不报，
@@ -1029,9 +1241,9 @@ export default async (path: string, html: string) => {
 | 在页面/组件里又 create 了一个 client | 创建只该发生在 onInit 一次 | 页面里直接 import 裸函数，不要再创建 |
 | 控制台「模块 A 正在为 /b 路径创建 client（越界）」 | A 创建了 B 的 client | 由 B 创建并通过 provider 提供能力 |
 | 改了契约，前端类型没变 | 没重新生成 | 跑 `ojm api`；生成确定，diff 应只含你改的部分 |
-| `ojm api` 报「schema 超出白名单」 | 契约里写了 `z.null()` / transform / refine | 不返回数据就别写 `data`；校验放后端 |
+| `ojm api` 报「schema 超出白名单」 | 契约里写了白名单外关键字（`oneOf`/`$ref`/`format` 等） | 改用白名单子集（§3.3）；union 用类型数组、nullable 用 `["string","null"]`；校验放后端 |
 | `ojm api` 报「apiPrefix 与目录名不符」 | 契约要求 apiPrefix 字面等于后端目录名 | 改 `apiPrefix` 或移动契约目录 |
-| `ojm api` 报「没有发现契约文件」 | 目录不符发现规则 | 按 §3.2 核对；注意 `modules/`→`web/`、`api/`→`client/` 迁移 |
+| `ojm api` 报错「未发现 openapi.json」 | 没跑 `oj openapi` 生成规范 | 先 `oj openapi -c api/config.yaml -d api/src -b /api -o openapi.json`，再 `ojm api`；旧 `contract.ts` 工程须先迁移（见 §3.10） |
 | `--check` 报 artifact-stale | 改了契约没重跑 | 重跑 `ojm api` |
 | `--check` 报 handler 未登记 | 内置/手写 handler 无契约 | 补契约，或登记豁免清单 |
 | 豁免写了 `//` 注释后全部失效 | 严格 JSON 解析失败、静默回退 | 注释写进 `_comment` 字段 |
@@ -1067,17 +1279,16 @@ export default async (path: string, html: string) => {
 | 接管通知 provider（四方法全量） | `web/src/notification/entry.ts` |
 | 上传 provider（action + headers 方法） | `web/src/personal-center/entry.ts` |
 | 无页面模块（`routes: []`） | 同 `web/src/notification/entry.ts` |
-| 契约写法（GET + POST、参数段） | `api/src/notification/contract.ts`、`api/src/personal-center/contract.ts` |
-| handler 写法（列表 / 写入 / 上传） | `api/src/notification/notifications/api.ts`、`.../read/api.ts` |
-| 生成物长什么样（含工厂） | `web/src/notification/client/api.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` 子组） |
+| 生成物长什么样（含工厂） | `web/src/notification/__client/api.ts` |
 | 建表三件套 | `api/src/notification/{schema.yaml,manifest.yaml,migrations/}` |
 | 全局类型（`window.$message` 等） | 工程根 `env.d.ts` |
 
 另有：
 
-- **后端 handler 手册**：即 `oj-api-dev` skill 的手册——仓库内已同步到
-  [`docs/oj-api-dev/`](../oj-api-dev/README.md)（权威源随 oj 二进制分发在
-  `~/.local/share/oj/devkit`，随 oj 版本更新，同步时以之覆盖本目录）。
+- **后端 handler 手册**：即 `oj-api-dev` skill 的手册——`ojm init` 已装到工程的
+  `.claude/skills/oj-api-dev/`（权威源随 oj 二进制分发在 `bin/devkit/`，随 oj 版本更新）。
   写 handler 遇到 `json` / `db` / `kv` / `jwt` / 租户 / 测试的问题查它；
   站点挂载（`mounts`）、密钥信封（`secrets`）、配置变量（`vars`）、跨域（`cors`）、
   schema 校验（`schema_validation`）、`broker` / `tasks` / `oidc` / `ws` 等 oj 侧能力也都在这套手册里。
@@ -1088,7 +1299,7 @@ export default async (path: string, html: string) => {
 > `app_prefix` / `static_sites` / `app_spa_fallback`）迁到顶层 **`mounts:`** 扁平表
 > （一行=一个 URL 前缀+一个目录，`api`/`web` 恰好其一）。旧键出现即被 `oj serve` fail-fast 拒绝。
 > ojm 模板 `api/config.yaml` 已落到 `mounts:`，`ojm dev/preview` 的 SPA 深链回落由 ojm 自建静态层负责，
-> 不需要 oj 的 spa。详细迁移规则、vars/secrets/cors/schema 用法见 `docs/oj-api-dev/` 手册。
+> 不需要 oj 的 spa。详细迁移规则、vars/secrets/cors/schema 用法见 `oj-api-dev` skill 手册。
 
 ---
 
@@ -1134,8 +1345,8 @@ export default async (path: string, html: string) => {
 - **终止语义**：`Ctrl+C`（SIGINT）/ `kill`（SIGTERM）/ `q` 退出时，ojm 会先关 SSE 通道、
   再 `SIGTERM` 停 oj 子进程、打印「后端 oj 已随前端一起终止」，不留 oj 孤儿占端口；
   极端情况下（3s 未退）升级 `SIGKILL`，并在进程退出时以 `kill()` 强杀作为最后手段，防止 oj 孤儿化。
-- 内置契约 watch：契约文件变更 → 自动重跑 `ojm api` → 产物写入 `web/` 触发模块重建 + 刷新。
-  **新模块目录的诞生不在 watch 范围**——新建模块的 `contract.ts` 要先重启 `ojm dev`。
+- 内置 `openapi.json` watch：规范变更 → 自动重跑 `ojm api` → 产物写入 `web/` 触发模块重建 + 刷新。
+  **新模块目录的诞生不在 watch 范围**——新建后端模块目录要先重启 `ojm dev`（目录注册发生在启动期）。
 
 #### `ojm build`
 
@@ -1165,7 +1376,7 @@ export default async (path: string, html: string) => {
 
 #### `ojm api [dir] [--check] [--docs] [--exempt <path>]`
 
-契约代码生成（详见 §3）：读 `contract.ts` → 生成前端 client / 后端 stub / `routes.json` / `openapi.yaml`。
+契约代码生成（详见 §3）：消费 `openapi.json`（oj v0.1.73+ `oj openapi` 产物）生成前端 `__client` / 后端 stub。
 
 - `dir`：项目目录（缺省 `cwd`；显式目录必须先存在，否则报错）。
 - `--check`：**四重对账**（只读、绝不写盘）：① 生成物同步 ② route 双向对账
@@ -1220,3 +1431,20 @@ export default async (path: string, html: string) => {
 | `ojm exec "<sql>"` | 在数据库上执行 SQL |
 
 `secret`（`keygen` / `seal` 等）**不在透传集合内**——它不需要 config，需直接 `./bin/oj secret ...`。
+
+---
+
+## 附录：章节目录
+
+| 章 | 内容 | 什么时候读 |
+|---|---|---|
+| §1 工程结构 | 脚手架产物、两个模块体系、目录镜像路由、重启边界、建表三件套、迁移与 seed | 新人第一遍；改后端目录结构 |
+| §2 写前端模块 | 目录、两步注册、entry.ts 形状、路由 handle、import 红线、共享依赖钉版 | 加页面 / 加模块 |
+| §3 契约与代码生成 | `.schema` 入参 + 平级 `.response` 出参、生成物契约、命令、豁免清单、DDD 判据、**§3.10 旧 contract.ts 工程迁移** | 加接口；从旧工程迁移 |
+| §4 接管框架内置功能 | provider 机制、通知 / 上传 / 菜单三案例 | 接管通知铃、头像上传、动态菜单 |
+| §5 布局与插槽 | 内置布局、容器外壳、自定义布局、插槽、响应式、偏好 | 改页面外壳 / 适配 |
+| §6 i18n 与样式 | 命名空间 i18n、样式约定 | 加文案 / 改样式 |
+| §7 构建与发布 | build / preview、htmlTransform、verify 闸 | 发布前 |
+| §8 排查 | 五步排查法、症状速查表 | 任何「没生效」 |
+| §9 参考 | 可抄的工程内文件、oj-api-dev 手册指引 | 找范本 |
+| §10 CLI 子命令参考 | ojm 原生命令 vs oj 透传命令 | 查命令用法 |