@oj-module/cli 0.2.5 → 0.2.8

package/README.md

@@ -27,7 +27,7 @@ ojm dev [port]   # 启动开发服务器（默认 5174）：宿主代理 + 本
 ojm build        # 构建模块产物与 dist/modules.json
 ojm init [dir] [--yes]        # 脚手架：模板工程 + 证书签发 + 联网下载 oj 到 bin/
 ojm vendor [tag] [--force]    # 下载/重装 oj vendor（经 npm 包 @oj-bin/oj，tag 缺省取最新版本，形如 v0.1.13）
-ojm preview [port] [--oj-static]   # 生产形态预览：oj migrate + release + 静态兜底
+ojm preview [port]   # 生产形态预览：oj migrate → oj serve 单服务（API + 静态 SPA 同进程）
 ojm info        # 输出报障所需的版本矩阵与后端观测
 ojm api [dir]   # 契约产物生成（client/openapi/mock stub）
 ojm merge <out> <in...>  # 合并多份 modules.json

package/devkit/manual.md

@@ -1294,7 +1294,7 @@ pnpm dev             # 开发：devServer + oj 后端（api/src 保存即热更
 # Ctrl+C（SIGINT）/ kill（SIGTERM）终止 dev 时，前端与后端 oj 一起终止：
 # 先关 SSE 通道 → 停 oj 子进程 → 打印「后端 oj 已随前端一起终止」，不留 oj 孤儿占端口
 pnpm build           # = ojm build：oj build（生成 routes.js）+ 前端全站合并到 web/dist
-pnpm preview         # = ojm preview：oj migrate（verify 闸）→ 启动 serve + 静态后备
+pnpm preview         # = ojm preview：oj migrate（verify 闸）→ oj serve 单服务（API + 静态 SPA 同进程）
 pnpm typecheck       # = tsc --noEmit
 pnpm exec ojm info   # 版本矩阵 + 模块清单（报障用）
 pnpm exec ojm vendor # 下载/重装 oj 二进制
@@ -1354,10 +1354,11 @@ export default async (path: string, html: string) => {
   顺序是 transform → dev 的 reload 脚本注入，`ojm dev` 照旧热更。
 - 返回 `string` 或 `{ html, cacheControl? }`；**未配置时输出与历史逐字节一致**，抛错/坏返回只
   打日志并回退原文（不会 500），非 HTML 资产完全不受影响。
-- 配置的模块缺失或 default 不是函数 → `ojm dev`/`ojm preview` **启动即报错**（不留半个 oj 进程）。
-- **`preview --oj-static` 例外**：该模式静态由 oj 二进制直出（`--app-path`），不经 ojm 静态层，
-  本钩子不生效；生产要在 oj 托管侧做同样的事，用 oj 的 `server.html_meta`（构建期 JSON）或
-  `server.html_meta_handler`（动态 handler）——见 oj devkit 手册「静态站点与 per-route meta」。
+- 配置的模块缺失或 default 不是函数 → `ojm dev` **启动即报错**（不留半个 oj 进程）。
+- **单服务 preview 例外**：preview 静态由 oj 二进制直出（web 挂载），不经 ojm 静态层，本钩子
+  不生效（启动检测到配置即 WARN，不加载模块）；逐路由 meta 用 oj 的 `server.html_meta`
+  （构建期 JSON）或 `server.html_meta_handler`（动态 handler）——见 oj devkit 手册
+  「静态站点与 per-route meta」。
 
 > release 的 `server.migrate_on_start` 默认 `verify`：迁移账本落后会**拒绝启动**，
 > 先跑 `ojm migrate -d api/dist`（透传自动补 `-c api/config.yaml`）。
@@ -1398,7 +1399,7 @@ export default async (path: string, html: string) => {
 | 豁免写了 `//` 注释后全部失效 | 严格 JSON 解析失败、静默回退 | 注释写进 `_comment` 字段 |
 | 新建后端模块目录后 API 404 | 目录镜像路由未热更 | **重启** `ojm dev` |
 | DELETE 返回 405 | 方法名写成了 `delete` | 改成 `del` |
-| IM 预览/爬虫只有默认标题（页面 JS 改了没用） | 服务端没做 HTML 注入 | 配 `htmlTransform`（见 §7；`preview --oj-static` 模式下要改到 oj 侧 `server.html_meta_handler`） |
+| IM 预览/爬虫只有默认标题（页面 JS 改了没用） | 服务端没做 HTML 注入 | 配 `htmlTransform`（见 §7；单服务 preview 要改到 oj 侧 `server.html_meta`/`server.html_meta_handler`） |
 | 配了 `htmlTransform` 但没生效 | 路径写错 / default 不是函数会**启动报错**；能起来却没效果 → 检查该请求是否命中静态层（`/api` 前缀与带扩展名的资源都不过钩子） | 见 §7 的生效范围 |
 | 上传报 401 | `headers` 写成固定对象，token 过期 | 写成方法，用时现取（§4.5） |
 | 后端菜单用了我的布局名，页面却没壳 | 注册该布局的模块没加载 | 看控制台 `[layout] 未知名布局` 提醒 |
@@ -1468,7 +1469,7 @@ export default async (path: string, html: string) => {
 
 > **为什么只有这 5 个走透传？** oj 还有 `serve` / `build` / `secret`（`keygen`/`seal` 等）
 > 子命令——但它们被 `ojm` **内部调用并附带额外逻辑**（如 `ojm build` 在 `oj build`
-> 之后还要做前端全站合并；`ojm preview` 在 `oj migrate` 之后起 `oj serve` + 静态后备），
+> 之后还要做前端全站合并；`ojm preview` 在 `oj migrate` 之后起 `oj serve` 单服务），
 > 所以不单独透传给用户，避免绕开 ojm 的工程化处理。需要原汁原味跑 oj 其它子命令时，
 > 直接 `./bin/oj <sub> ...`（记得手动 `-c api/config.yaml`）。
 
@@ -1516,21 +1517,22 @@ export default async (path: string, html: string) => {
 > release 下只有 `routes.js` 里的路由存在，目录镜像路由不生效——所以参数路由要先
 > `ojm build` 再测（见 §7）。
 
-#### `ojm preview [port] [--oj-static]`
+#### `ojm preview [port]`
 
-生产形态预览（设计 §6）：
+生产形态预览（设计 §6，2026-10-19 单服务化）：
 
 1. 启动前 **fail-fast 四查**（缺 oj 二进制 / `config.yaml` / `web/dist/index.html` /
    `api/dist/manifests.yaml` 任一即报错并给补救指引，绝不留下 oj 孤儿）；
 2. `oj migrate`（应用待执行迁移，非零退出即退、不起 server）；
-3. `oj serve`（release/js，仅 API）；
-4. ojm 静态层后备（SPA 回退，无 SSE 注入、不设 no-store）。
-
-- `port`：preview 端口（缺省 **4173**）。
-- `--oj-static`：静态改由 oj `--app-path` 直出（真 exercise oj 静态层；history 深链接 404 为已知限制，
-  ojm 本口仍提供 SPA 后备 + `/api` 反代）。
-- 支持 `web.config.ts` 的 `htmlTransform`（按路由注入 `<title>`/`og:*`，见 §7），模块缺失或
-  default 非函数会**启动即报错**。
+3. 生成派生 config `api/.ojm-preview.yaml`（原 config 副本 + upsert `/` web 挂载 +
+   `spa: true`；显式 `port` 时覆盖 `server.port`）；
+4. `oj serve`（release/js，**单进程同时出 API 与静态**，SPA 深链回落）。
+
+- `port`：preview 端口（缺省用 config 的 `server.port`，默认 9778）；显式传参经派生 config 覆盖。
+- ojm 不再自建 http server、不反代、不传 `--app-path`——与「oj serve + web 挂载」的生产公式同形。
+- 派生 config 为临时产物，退出三路清理（SIGINT / 进程退出兜底 / 编程式 stop），模板 .gitignore 已收录。
+- `web.config.ts` 的 `htmlTransform` 在单服务 preview **不生效**（启动 WARN 指向 oj
+  `server.html_meta` / `server.html_meta_handler`）。
 
 #### `ojm api [dir] [--check] [--docs] [--exempt <path>]`
 

package/devkit/sql-builder-missing-capabilities-pr.md

@@ -0,0 +1,234 @@
+# 上游 PR 提案：SQL 构造器缺失能力清单
+
+> 目的：把模板 `db.query` 全面迁移到 `db.table(...)` 构造器以获得多库（sqlite / mysql / postgres）可移植性时，
+> 识别出构造器**当前无法表达**、只能回退 `db.query` 的 7 类能力。本文档作为向上游 `oj` 运行时 SQL 构造器提 PR 的依据。
+>
+> 证据来源：`~/.local/share/oj/devkit/api-manual.md`（查询构造器章节，含 `like` 操作清单 §1142、子查询限制 §1343、
+> `union` §1346、CTE §1378 等）；框架 `README.md` v0.1.66（ESCAPE 纪律）；模板代码 `packages/cli/templates/api/src/**`。
+
+---
+
+## 1. 背景与现状
+
+模板已完成 `db.query` → `db.table()` 的主体迁移：约 96 处查询/写入迁移到构造器，但仍有 **17 处**因构造器能力缺口被迫保留
+`db.query`（含注释 `保留 db.query：…`）。这些缺口若不上游补齐，模板永远无法做到"零原生 SQL"。
+
+构造器已具备：`select/where/orderBy/limit/offset/all`、`insert/update/delete/returning/run`、
+`where` 树（`and/or/not`）、`in/like/isnull/eq…` 比较、`union`/`union all`、`case`/`window` 列、`with` CTE、嵌套子查询（深度≤4）。
+
+缺口集中在**表达能力**而非基础 CRUD。
+
+---
+
+## 2. 缺失能力总览（按出现频率与阻塞面排序）
+
+| # | 缺失能力 | 阻塞面 | 当前回退点（模板） | 优先级 |
+|---|----------|--------|--------------------|--------|
+| 1 | `like` 的 `ESCAPE` 转义子句 | 模糊搜索全场景（用户/方案/联系人/目录） | `contacts.ts:20`、`solution-perms.ts:100`、`uninstall.ts:76/82/116` | P0 |
+| 2 | `join ... ON` 带**值条件**（`AND user_id = ?`） | 通知合并查询（broadcast LEFT JOIN 回执） | `notify.ts:135-167` | P0 |
+| 3 | `select` 支持**字面量/计算列**（`'user' as scope`、`(x IS NOT NULL…) as y`） | 通知合并 + 角色作用域标记 | `notify.ts:144/148` | P1 |
+| 4 | `INSERT OR IGNORE` / `INSERT … SELECT` | 通知已读回执幂等写入 | `notify.ts:167-169/186-188` | P1 |
+| 5 | **全表 delete 的强制 where 豁免** | 登录限流重置等有意清空 | `rate.ts:78` | P2 |
+| 6 | **动态 WHERE** 组合（运行时按可选参数拼接） | 多过滤项搜索、动态 IN | `demo/todos/api.ts:12`、`uninstall.ts:166` | P2 |
+| 7 | `select *`（无列清单） | 刷新令牌等整行读取 | `session.ts:114-115` | P3 |
+
+---
+
+## 3. 逐项详述
+
+### 3.1 `like` 缺 `ESCAPE` 子句（P0）
+
+**为什么是硬约束**：框架对模糊搜索有强制纪律——`LIKE` 元字符必须用 `ESCAPE '!'` 转义，且**不能用 `ESCAPE '\'`**
+（mysql 默认 `sql_mode` 下 `ESCAPE '\'` 直接 1064）。`api-manual.md` 的 `like` 操作清单（§1142）及子查询限制（§1343）
+表明：`WhereCond` 的 `like` 不接受 `escape` 字段，也不接受子查询。
+
+**阻塞的真实代码**（`contacts.ts:20`）：
+
+```ts
+// 保留 db.query：模糊搜索需 ESCAPE '!'(构造器 like 无 escape 子句；mysql 默认 sql_mode 下 ESCAPE '\' 即 1064)
+const rows = await db.query(
+  `SELECT * FROM contacts WHERE name LIKE ? ESCAPE '!' OR phone LIKE ? ESCAPE '!'`,
+  [pat, pat],
+) as unknown as ContactRow[];
+```
+
+**提议 API**：
+
+```ts
+// 方案 A：WhereCond 增加 escape 字段
+db.table("contacts").where({ field: "name", op: "like", value: pat, escape: "!" }).all();
+// 方案 B：链式 like 三参
+db.table("contacts").where(c => c.like("name", pat, "!").or.like("phone", pat, "!")).all();
+```
+
+引擎侧：sqlite 原样 `ESCAPE '!'`；mysql/postgres 同语义转写。**务必锁定 `!` 为默认转义符**，杜绝 `'\'`。
+
+---
+
+### 3.2 `join ... ON` 仅支持列=列，不支持值条件（P0）
+
+**阻塞的真实代码**（`notify.ts:150`，广播通知合并读取）：
+
+```sql
+SELECT b.id, …, (r.read_time IS NOT NULL AND r.read_time <> '') as is_read, …, 'broadcast' as scope
+  FROM notifications_broadcast b
+  LEFT JOIN notifications_broadcast_read r ON r.broadcast_id = b.id AND r.user_id = ?
+```
+
+`api-manual.md` 的 join `on` 仅接受 `{ left, right }`（列=列）。`AND r.user_id = ?` 是**值条件**，构造器无法表达。
+
+**提议 API**：
+
+```ts
+db.table("notifications_broadcast as b")
+  .leftJoin("notifications_broadcast_read as r",
+    on => on.on("r.broadcast_id", "b.id").and("r.user_id", "=", uid))
+  .select([...])
+  .all();
+// on() 第二形参支持 op + value：.and("r.user_id", "=", uid)
+```
+
+---
+
+### 3.3 `select` 不支持字面量 / 计算列（P1）
+
+**阻塞的真实代码**（`notify.ts:144/148`）：
+
+```sql
+SELECT id, avatar, date, is_read, message, title, link, category, 'user' as scope
+  FROM notifications WHERE user_id = ?
+UNION ALL
+SELECT b.id, …, (r.read_time IS NOT NULL AND r.read_time <> '') as is_read, …, 'broadcast' as scope
+  FROM notifications_broadcast b LEFT JOIN …
+```
+
+`'user' as scope`（字面量列）与 `(r.read_time IS NOT NULL AND r.read_time <> '') as is_read`（计算列）均无法用构造器 `select([...])`
+表达（该 API 当前只收列名字符串或 `{ fn, field, as }` 聚合）。
+
+**提议 API**：
+
+```ts
+.select([
+  "id", "avatar", "date",
+  { expr: "'user'", as: "scope" },              // 字面量
+  { expr: "(r.read_time IS NOT NULL AND r.read_time <> '')", as: "is_read" }, // 计算列
+])
+```
+
+> 注：`case`/`window` 列（§1360）已支持，但**任意表达式 + as 别名**维度缺失，建议补齐 `expr` 入口。
+
+---
+
+### 3.4 缺 `INSERT OR IGNORE` / `INSERT … SELECT`（P1）
+
+**阻塞的真实代码**（`notify.ts:167-169` 与 `186-188`）：
+
+```ts
+// 保留 db.exec：INSERT OR IGNORE 构造器无等价（引擎按方言改写 IGNORE）
+await d.exec("INSERT OR IGNORE INTO notifications_broadcast_read (broadcast_id, user_id, read_time) VALUES (?, ?, ?)", [...]);
+// 保留 db.exec：INSERT OR IGNORE ... SELECT 构造器无法表达
+await d.exec("INSERT OR IGNORE INTO notifications_broadcast_read (broadcast_id, user_id, read_time) SELECT id, ?, ? FROM notifications_broadcast", [...]);
+```
+
+`INSERT OR IGNORE` 是 sqlite 方言；mysql 对应 `INSERT … ON DUPLICATE KEY IGNORE`/忽略，postgres 对应 `ON CONFLICT DO NOTHING`。
+构造器当前 `insert()` 无 `orIgnore()` 修饰，也无 `fromSelect()`。
+
+**提议 API**：
+
+```ts
+db.table("notifications_broadcast_read")
+  .insert({ broadcast_id, user_id, read_time })
+  .orIgnore()          // 引擎按方言转写：sqlite OR IGNORE / pg ON CONFLICT DO NOTHING / mysql 忽略重复
+  .run();
+
+db.table("notifications_broadcast_read")
+  .insert(["broadcast_id", "user_id", "read_time"])
+  .fromSelect(db.table("notifications_broadcast").select(["id", lit(uid), lit(now)]))
+  .orIgnore()
+  .run();
+```
+
+---
+
+### 3.5 全表 delete 强制 where 无豁免（P2）
+
+**阻塞的真实代码**（`rate.ts:78`，登录限流重置——有意清空整张表）：
+
+```ts
+await db.exec("delete from sys_login_throttle", []);
+```
+
+构造器在运行时抛 `"update requires where"`（delete 同理强制 where）。清空整表是合法运维动作，需显式豁免。
+
+**提议 API**：
+
+```ts
+db.table("sys_login_throttle").delete().where({ __all: true }).run();
+// 或显式逃逸：.delete().run({ force: true })
+```
+
+命名上建议用**显眼且不可误用**的写法规避"忘了加 where 误清表"，例如要求 `where({ __all: true })` 或 `deleteAll()`。
+
+---
+
+### 3.6 动态 WHERE 组合无安全出口（P2）
+
+**阻塞的真实代码**（`demo/todos/api.ts:12`、`uninstall.ts:166`）：
+
+```ts
+// 保留 db.query：WHERE 由 JS 字符串拼接动态生成（规则5）
+// 保留 db.query：IN 占位符经 JS 字符串拼接动态生成（动态 SQL），构造器 in 仅接受静态数组值
+```
+
+运行时按可选过滤参数拼接 WHERE（如"给了 status 才加 `status = ?`"、动态 IN 长度）超出了构造器静态 `where(...)` 树。
+
+**提议 API**（安全逃逸舱，而非放开字符串拼接）：
+
+```ts
+db.table("todos")
+  .where(sql`status = ? AND owner = ?`, [status, owner])   // 类型安全参数化片段
+  .all();
+// 或 builder 拼接：.whereIf(cond, c => c.eq("status", v))
+```
+
+> 反对直接暴露 `where(rawString, params)` 给业务层——保留给平台内部/高级场景，避免回到拼接 SQL 的老路。
+
+---
+
+### 3.7 `select *` 无整行读取（P3）
+
+**阻塞的真实代码**（`session.ts:114-115`）：
+
+```ts
+// 保留 db.query：select * 无已知列清单（规则6）
+const rows = await db.query("select * from sys_refresh_token where token_hash = ?", [hash]) …;
+```
+
+**提议 API**：
+
+```ts
+db.table("sys_refresh_token").select("*").where({ field: "token_hash", op: "eq", value: hash }).all();
+// 或省略 select，默认整行：.all()
+```
+
+---
+
+## 4. 不在本文范围
+
+- **方言无关的表达式求值**：计算列目前建议以 `expr` 字符串透传（由引擎保证参数化安全），不要求构造器解析表达式语义。
+- **存储过程 / 批处理 / 事务编排**：与可移植性目标无关。
+- **`db.query` 下架**：补齐上述能力后模板侧可全量迁移，下架是后续动作，不在本 PR 提案内。
+
+---
+
+## 5. 验收建议（上游实现后模板侧可关闭的回退点）
+
+1. `contacts.ts:20` 模糊搜索 → 改用 `like` + `escape`。
+2. `solution-perms.ts:100` / `uninstall.ts:76/82/116` 目录与权限 LIKE → 同上。
+3. `notify.ts:135-167` 通知合并 → `leftJoin` 值条件 + `expr` 列。
+4. `notify.ts:167-188` 已读回执 → `orIgnore()` / `fromSelect()`。
+5. `rate.ts:78` 限流重置 → `delete().where({ __all: true })`。
+6. `demo/todos/api.ts:12` / `uninstall.ts:166` → 动态 WHERE 安全出口。
+7. `session.ts:114-115` → `select("*")`。
+
+全部关闭后，模板 `api/src` 内 `保留 db.query` / `保留 d.exec` 注释应归零，达成"零原生 SQL 可移植"目标。

package/package.json

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

package/shell-dist/assets/runtime.js

@@ -256,10 +256,10 @@ function getAppInfo() {
 	return {
 		"pkg": {
 			"name": "@oj-module/runtime",
-			"version": "0.2.5",
+			"version": "0.2.8",
 			"license": "MIT"
 		},
-		"lastBuildTime": "2026-10-19 10:55:08"
+		"lastBuildTime": "2026-10-20 00:16:33"
 	};
 }
 var init_get_app_info = __esmMin((() => {}));

package/shell-dist/index.html

@@ -5,9 +5,9 @@
 		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
 		<link rel="icon" href="/favicon.ico" />
 		<title>React Antd Admin · Shell</title>
-		<meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'self' https://modules.cdn.example.com 'wasm-unsafe-eval' 'nonce-O1CJWdo1CXHlXEClzw+t4w=='; script-src-attr 'none'; connect-src 'self' data: https://modules.cdn.example.com; style-src 'self' https://modules.cdn.example.com 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' data:; frame-src https://ant.design https://react.dev https://condorheroblog.github.io; form-action 'none'; base-uri 'none'; object-src 'none'; upgrade-insecure-requests" />
+		<meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'self' https://modules.cdn.example.com 'wasm-unsafe-eval' 'nonce-GbU8577c6LFtg4pmT1NjGA=='; script-src-attr 'none'; connect-src 'self' data: https://modules.cdn.example.com; style-src 'self' https://modules.cdn.example.com 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' data:; frame-src https://ant.design https://react.dev https://condorheroblog.github.io; form-action 'none'; base-uri 'none'; object-src 'none'; upgrade-insecure-requests" />
 
-		<script type="importmap" nonce="O1CJWdo1CXHlXEClzw+t4w==">{
+		<script type="importmap" nonce="GbU8577c6LFtg4pmT1NjGA==">{
   "imports": {
     "react": "/assets/react.js",
     "react/jsx-runtime": "/assets/jsx-runtime.js",

package/shell-dist/versions.json

@@ -7,9 +7,9 @@
   "react-router": "7.18.2",
   "react-router/dom": "7.18.2",
   "@tanstack/react-query": "5.102.8",
-  "@oj-module/runtime": "0.2.5",
-  "@oj-module/runtime/contract": "0.2.5",
-  "@oj-module/runtime/contract/errors": "0.2.5",
+  "@oj-module/runtime": "0.2.8",
+  "@oj-module/runtime/contract": "0.2.8",
+  "@oj-module/runtime/contract/errors": "0.2.8",
   "@plane/kit": "0.1.20",
   "@plane/editor": "0.1.20",
   "antd": "6.6.1",

package/src/contract/__tests__/handler-scan.test.ts

@@ -51,6 +51,35 @@ export default createMarketApi({} as Env);
 		]);
 	});
 
+	it("标识符默认导出指回工厂调用：const x = createXxx(env); export default x（market/api.ts 真形态）", () => {
+		// 真实模板形态：工厂调用赋给 const，再 export default 该标识符。
+		// 此前 scanHandlerFile 只认「default 导出 = 调用表达式」，认不出
+		// 「default 导出 = 标识符 → 指向一次工厂调用」，导致 market 整族 route 漏登。
+		const rows = scan("api.ts", `
+import type { Env } from "./types";
+export function createMarketApi(env: Env) {
+	return {
+		"install": {
+			async post() { return {}; },
+		},
+		"verify": {
+			async post() { return {}; },
+			last: {
+				async get() { return {}; },
+			},
+		},
+	};
+}
+const marketApi = createMarketApi({} as Env);
+export default marketApi;
+`);
+		expect(rows.map(r => `${r.method} ${r.full}`).sort()).toEqual([
+			"GET _platform/market/verify/last",
+			"POST _platform/market/install",
+			"POST _platform/market/verify",
+		]);
+	});
+
 	it("无 return 对象 / 未知 callee / 点分 callee 不可解析 → 零行（不炸不猜）", () => {
 		expect(scan("a.ts", "export default createMissingApi({});")).toEqual([]);
 		expect(scan("b.ts", `

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

@@ -0,0 +1,167 @@
+import type { ScopedRequestLike } from "../../../templates/web/src/_platform/__client/api";
+
+// 集成回归：真实 httpMarketClient（统一后委托 ojm 生成 client）的委托行为。
+// 经 bindRequest 注入 mock request，验证每条 MarketClient 方法 → 正确 URL/body/query + 返回形状；
+// 并验证 index 的 503「未配置市场地址」→ [] 空态（PRD §5.3）。
+//
+// 不加载 @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";
+
+// index() 直连 request（不走生成 client），故把桩 request 做成可变实现，测试内统一指向同一 mock。
+const { requestImpl } = vi.hoisted(() => ({
+	requestImpl: {
+		get: () => { throw new Error("placeholder"); },
+		post: () => { throw new Error("placeholder"); },
+		put: () => { throw new Error("placeholder"); },
+		delete: () => { throw new Error("placeholder"); },
+		patch: () => { throw new Error("placeholder"); },
+		head: () => { throw new Error("placeholder"); },
+	},
+}));
+
+vi.mock("@oj-module/runtime", async () => {
+	const { z } = await import("zod");
+	return {
+		z,
+		// defaultClient 顶层 bindRequest(request) 用到；测试内立即被 mock 覆盖，不会真发请求。
+		request: requestImpl,
+	};
+});
+
+interface Call {
+	method: string
+	url: string
+	opts?: { searchParams?: Record<string, string | number | boolean>, json?: unknown }
+}
+
+function mockRequest(responder: (c: Call) => { status?: number, data?: unknown }) {
+	const calls: Call[] = [];
+	const make = (method: string) => (url: string, opts?: Call["opts"]) => {
+		calls.push({ method, url, opts });
+		const r = responder({ method, url, opts });
+		if (r.status && r.status >= 400) {
+			const err: { response?: { status?: number } } = new Error(`HTTP ${r.status}`);
+			err.response = { status: r.status };
+			throw err;
+		}
+		return { json: () => Promise.resolve({ code: 0, data: r.data ?? null }) };
+	};
+	const req = {
+		get: make("get"),
+		post: make("post"),
+		put: make("put"),
+		delete: make("delete"),
+		patch: make("patch"),
+		head: make("head"),
+	} as unknown as ScopedRequestLike;
+	return { calls, req };
+}
+
+// 让 index() 直连的 request 与生成 client 的 bindRequest 指向同一 mock，行为一致。
+function useMock(m: ReturnType<typeof mockRequest>) {
+	bindRequest(m.req);
+	requestImpl.get = m.req.get;
+	requestImpl.post = m.req.post;
+	requestImpl.put = m.req.put;
+	requestImpl.delete = m.req.delete;
+	requestImpl.patch = m.req.patch;
+	requestImpl.head = m.req.head;
+}
+
+describe("httpMarketClient · 统一委托生成 client 集成回归", () => {
+	let mock: ReturnType<typeof mockRequest>;
+
+	beforeEach(() => {
+		mock = mockRequest(() => ({ data: {} }));
+		useMock(mock);
+	});
+
+	it("meta() → GET _platform/market/meta，返回 { apiVersion }", async () => {
+		mock = mockRequest(() => ({ data: { apiVersion: "1.2.3" } }));
+		useMock(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" });
+	});
+
+	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);
+		const r = await httpMarketClient.index();
+		expect(mock.calls[0]).toMatchObject({ method: "get", url: "_platform/market/index" });
+		expect(r).toEqual(rows);
+	});
+
+	it("index() 遇 503（未配置市场地址）→ [] 空态，不抛（PRD §5.3）", async () => {
+		mock = mockRequest(c => (c.url === "_platform/market/index" ? { status: 503 } : { data: {} }));
+		useMock(mock);
+		const r = await httpMarketClient.index();
+		expect(r).toEqual([]);
+	});
+
+	it("install(input) → POST _platform/market/install，body 含 name/version/source", async () => {
+		mock = mockRequest(() => ({ data: { task_id: "t-1" } }));
+		useMock(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" });
+		expect(r).toEqual({ task_id: "t-1" });
+	});
+
+	it("install(input) 缺省 version/source → null / cdn 兜底", async () => {
+		mock = mockRequest(() => ({ data: { task_id: "t-2" } }));
+		useMock(mock);
+		await httpMarketClient.install({ name: "beta" });
+		expect(mock.calls[0].opts?.json).toEqual({ name: "beta", version: null, source: "cdn" });
+	});
+
+	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);
+		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" });
+		expect(r).toEqual(rec);
+	});
+
+	it("enable(input) → POST _platform/market/enable，body {name,enabled}", async () => {
+		mock = mockRequest(() => ({ data: { ok: true, message: "done" } }));
+		useMock(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 });
+		expect(r).toEqual({ ok: true, message: "done" });
+	});
+
+	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);
+		const r = await httpMarketClient.history();
+		expect(mock.calls[0]).toMatchObject({ method: "get", url: "_platform/market/history" });
+		expect(r).toEqual(hist);
+	});
+
+	it("uninstallImpact(name) → GET _platform/market/uninstall-impact? 带 name", async () => {
+		mock = mockRequest(() => ({ data: { name: "a", affectedRoles: 2, affectedUsers: 5 } }));
+		useMock(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" });
+		expect(r).toEqual({ name: "a", affectedRoles: 2, affectedUsers: 5 });
+	});
+
+	it("uninstall(name) → POST _platform/market/uninstall，body {name}", async () => {
+		mock = mockRequest(() => ({ data: { ok: true, message: "removed" } }));
+		useMock(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" });
+		expect(r).toEqual({ ok: true, message: "removed" });
+	});
+});

package/src/contract/handler-scan.ts

@@ -94,6 +94,20 @@ function collectObjectDecls(sf: ts.SourceFile): Map<string, ts.ObjectLiteralExpr
 	return decls;
 }
 
+/** 顶层 `const x = createXxx(env)` 调用声明表：工厂形态经标识符引用（`export default x`）时的解析依据 */
+function collectCallDecls(sf: ts.SourceFile): Map<string, ts.CallExpression> {
+	const decls = new Map<string, ts.CallExpression>();
+	for (const stmt of sf.statements) {
+		if (!ts.isVariableStatement(stmt))
+			continue;
+		for (const decl of stmt.declarationList.declarations) {
+			if (ts.isIdentifier(decl.name) && decl.initializer && ts.isCallExpression(decl.initializer))
+				decls.set(decl.name.text, decl.initializer);
+		}
+	}
+	return decls;
+}
+
 /** verb 键 → 实现函数名（供 `.route` 语句按函数名查找；内联写法回落键名） */
 function implNameOf(prop: ts.ObjectLiteralElementLike): string | undefined {
 	if (ts.isShorthandPropertyAssignment(prop))
@@ -141,9 +155,16 @@ function defaultExportObject(sf: ts.SourceFile, decls: Map<string, ts.ObjectLite
  * 是调用表达式，此前扫描器不认，route-unregistered 守卫对 market/solutions 全族失效）：
  * 解析同文件同名函数声明体内 return 的对象字面量（运行时 oj 内省执行工厂拿到该对象，静态
  * 扫描镜像此语义）。支持多个 return；对象内标识符引用仍解析文件级顶层 const。
+ * 补全（P2-14 形态遗漏）：`export default createXxxApi(marketEnv())` 中 `call.expression`
+ * 是**带实参的调用表达式**，函数名落在 `call.expression.expression`（createXxxApi）；
+ * 旧逻辑直接 dottedNameOf(call.expression) 对 CallExpression 返回 undefined → 扫成 0 路由，
+ * 致使 ojm api --check 把 market 全族端点判为「未实现 / stub 缺失」。此处穿透一层取被调函数名。
  */
 function factoryReturnObjects(sf: ts.SourceFile, call: ts.CallExpression): ts.ObjectLiteralExpression[] {
-	const callee = dottedNameOf(call.expression);
+	// `export default createXxxApi(marketEnv())`：`call.expression` 为带实参的调用表达式，
+	// 函数名在其 `.expression`；`export default obj.createXxxApi(marketEnv())` 同样穿透。
+	const target = ts.isCallExpression(call.expression) ? call.expression.expression : call.expression;
+	const callee = dottedNameOf(target);
 	if (callee === undefined)
 		return [];
 	for (const stmt of sf.statements) {
@@ -189,6 +210,7 @@ export function scanHandlerFile(filePath: string, apiSrcDir: string): HandlerRow
 	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 rows: HandlerRow[] = [];
 	const seen = new Set<ts.Node>();
@@ -251,10 +273,19 @@ export function scanHandlerFile(filePath: string, apiSrcDir: string): HandlerRow
 		walk(root, "", filePrefix, 1);
 	}
 	else {
-		// P2-14：工厂形态（CallExpression）——组前缀从目录镜像起算（同内联字面量形态）
+		// 工厂形态（P2-14 + 补全）：export default 后接
+		//  - CallExpression 直调：createXxx(env) / createXxx(marketEnv())
+		//  - Identifier 引用：const api = createXxx(env); export default api
+		// 组前缀从目录镜像起算（同内联字面量形态）。
 		for (const stmt of sf.statements) {
-			if (ts.isExportAssignment(stmt) && !stmt.isExportEquals && ts.isCallExpression(stmt.expression)) {
-				for (const obj of factoryReturnObjects(sf, stmt.expression))
+			if (!ts.isExportAssignment(stmt) || stmt.isExportEquals)
+				continue;
+			const expr = stmt.expression;
+			const callExpr = ts.isCallExpression(expr)
+				? expr
+				: (ts.isIdentifier(expr) ? callDecls.get(expr.text) : undefined);
+			if (callExpr) {
+				for (const obj of factoryReturnObjects(sf, callExpr))
 					walk(obj, "", "", 1);
 			}
 		}