@oj-module/cli 0.2.1 → 0.2.2

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@oj-module/cli",
   "type": "module",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "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.1",
+    "@oj-module/runtime": "0.2.2",
     "@redocly/cli": "^2.51.0",
     "@tailwindcss/vite": "^4.3.0",
     "esbuild": "^0.28.2",

package/shell-dist/assets/runtime.js

@@ -255,10 +255,10 @@ function getAppInfo() {
 	return {
 		"pkg": {
 			"name": "@oj-module/runtime",
-			"version": "0.2.1",
+			"version": "0.2.2",
 			"license": "MIT"
 		},
-		"lastBuildTime": "2026-10-16 20:19:27"
+		"lastBuildTime": "2026-10-16 22:08:56"
 	};
 }
 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-mWZBL1v96uMHEClxtdmRpA=='; 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-ELLiP0aL4p7v4pSj08o8IQ=='; 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="mWZBL1v96uMHEClxtdmRpA==">{
+		<script type="importmap" nonce="ELLiP0aL4p7v4pSj08o8IQ==">{
   "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.1",
-  "@oj-module/runtime/contract": "0.2.1",
-  "@oj-module/runtime/contract/errors": "0.2.1",
+  "@oj-module/runtime": "0.2.2",
+  "@oj-module/runtime/contract": "0.2.2",
+  "@oj-module/runtime/contract/errors": "0.2.2",
   "@plane/kit": "0.1.20",
   "@plane/editor": "0.1.20",
   "antd": "6.6.1",

package/templates/README.md

@@ -16,17 +16,19 @@ pnpm preview    # 预览：oj migrate + server（release 产物）
 ## 系统管理模块
 
 `web/src/system/`（用户管理 / 成员资格 / 角色权限 / 操作日志 / 站点设置 / 登录方式）
-的前端 API 客户端 `__client/` 是生成物、不随模板分发，**首次使用前生成一次**：
+的前端 API 客户端 `__client/` **已随模板分发**（与 auth/notification 等一致），`pnpm dev`
+开箱即用、「系统管理」菜单直接可见。
+
+`__client` 是从 `openapi.json`（模板自带，由 `api/src/system` 契约产出）生成的产物；
+契约变更后刷新一次即可：
 
 ```bash
-pnpm dev                              # 终端 A：起 oj 后端 + 前端
-bin/oj openapi -c config.yaml -d api/src -b /api -o openapi.json   # 终端 B：产出契约
-pnpm exec ojm api                     # 生成 web/src/*/__client（dev 检测到 openapi.json 变化也会自动重生成）
+bin/oj openapi -c config.yaml -d api/src -b /api -o openapi.json   # 重产契约
+pnpm exec ojm api                     # 重新生成 web/src/*/__client（dev 检测到 openapi.json 变化也会自动重生成）
 ```
 
-生成后重启 `pnpm dev`，「系统管理」菜单即可用（生成前该模块加载失败属预期）。
-改了 `api/src` 的 handler `.schema`/`.response` 后同样重跑这两条保持同步
-（`ojm api --check` 可对账，零漂移为发布门禁）。成员资格页仅 superadmin 可见。
+成员资格页仅 superadmin 可见。改了 `api/src` 的 handler `.schema`/`.response` 后重跑这两条保持同步
+（`ojm api --check` 可对账，零漂移为发布门禁）。
 
 ## 目录
 
@@ -46,3 +48,40 @@ web/dist/  构建产物（完整站点）
   手册按章节按需读。
 - `api/config.yaml` 的证书为 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` 生成的产物。在工程根跑一次即可补齐：
+
+  ```bash
+  pnpm exec ojm api      # 生成 web/src/*/__client（dev 检测到 openapi.json 变化也会自动重生成）
+  ```
+
+  改完后端 `api/src` 的契约后，重产契约再刷新：
+
+  ```bash
+  bin/oj openapi -c config.yaml -d api/src -b /api -o openapi.json
+  pnpm exec ojm api
+  ```
+
+- **`__client/` 下的文件能直接改吗？**
+  不能手改、也不入库——它是生成物，下次 `ojm api` 会覆盖你的手改。需要改接口就改
+  `api/src` 的 handler `.schema`/`.response`，再跑上面的命令刷新。
+  `ojm api --check` 可对账契约与产物的漂移（零漂移为发布门禁）。
+
+- **`pnpm dlx @oj-module/cli@latest init` 生成的脚手架缺模块 / 看起来很旧**
+  pnpm dlx 会按首次解析到的版本**缓存** CLI 可执行文件。若某次 `@latest` 指向的是旧版
+  （例如早于系统管理模块的 `0.1.x`），之后重跑仍可能命中旧缓存，生成的脚手架就会缺新模块、
+  模板偏旧（典型表现：`web/src` 下没有 `system` 目录）。
+  排查：`ls web/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   # 显式指定版本最稳
+  ```
+
+  养成显式带版本号（如 `@oj-module/cli@0.2.2`）的习惯，可避免 `@latest` 缓存歧义。

package/templates/web/src/system/__client/api.schemas.ts

@@ -0,0 +1,150 @@
+/* eslint-disable */
+// 生成物：ojm api 从契约生成，勿手改（改动请改契约文件后重跑 ojm api）
+// AC-D15：仅供 DEV 校验动态 import，生产构建不进产物
+import { z } from "@oj-module/runtime";
+
+export const schemas = {
+	"systemLoginMethodsGet": {
+		data: z.object({
+	"methods": z.array(z.string())
+}),
+	},
+	"systemOplogGet": {
+		query: z.object({
+	"action": z.string().optional(),
+	"username": z.string().optional(),
+	"module": z.string().optional(),
+	"limit": z.number().min(1).max(200).optional()
+}),
+		data: z.object({
+	"list": z.array(z.object({
+	"id": z.number(),
+	"create_time": z.number(),
+	"user_id": z.number(),
+	"username": z.string(),
+	"action": z.string(),
+	"module": z.string(),
+	"version": z.string().nullable(),
+	"target": z.string().nullable(),
+	"detail": z.string().nullable(),
+	"level": z.number()
+})),
+	"total": z.number(),
+	"truncated": z.boolean()
+}),
+	},
+	"systemPermissionsGet": {
+		data: z.array(z.object({
+	"code": z.string(),
+	"module": z.string(),
+	"title_key": z.string().nullable(),
+	"deprecated": z.boolean()
+})),
+	},
+	"systemRolesGet": {
+		data: z.array(z.object({
+	"name": z.string(),
+	"module": z.string(),
+	"title": z.string().nullable(),
+	"description": z.string().nullable(),
+	"builtin": z.boolean(),
+	"deprecated": z.boolean(),
+	"holders": z.number(),
+	"permissions": z.array(z.string())
+})),
+	},
+	"systemRolesPost": {
+		body: z.object({
+	"name": // @oj-warn: pattern="^custom\\.[a-z0-9][a-z0-9-]*$" 为 Rust regex，未在前端执行（跨语言语义漂移/ReDoS 风险）
+	z.string(),
+	"title": z.string().min(1),
+	"permissions": z.array(z.string()).optional()
+}),
+		data: z.object({
+	"name": z.string(),
+	"module": z.string()
+}),
+	},
+	"systemRolesDelete": {
+		query: z.object({
+	"name": z.string().min(1)
+}),
+	},
+	"systemRolesBindingsPut": {
+		query: z.object({
+	"name": z.string().min(1)
+}),
+		body: z.object({
+	"permissions": z.array(z.string())
+}),
+	},
+	"systemSettingsGet": {
+		data: z.array(z.object({
+	"group": z.string(),
+	"items": z.array(z.object({
+	"key": z.string(),
+	"module": z.string(),
+	"group": z.string(),
+	"type": z.string(),
+	"value": z.string().nullable(),
+	"default_value": z.string().nullable(),
+	"label_key": z.string().nullable(),
+	"options": z.string().nullable(),
+	"secret": z.boolean(),
+	"update_time": z.number()
+}))
+})),
+	},
+	"systemSettingsPut": {
+		body: z.object({
+	"key": z.string().min(1),
+	"value": z.string()
+}),
+	},
+	"systemUsersGet": {
+		data: z.array(z.object({
+	"id": z.number(),
+	"username": z.string(),
+	"display_name": z.string().nullable(),
+	"email": z.string().nullable(),
+	"is_forbidden": z.boolean(),
+	"must_change": z.boolean(),
+	"roles": z.array(z.string())
+})),
+	},
+	"systemUsersPost": {
+		body: z.object({
+	"username": z.string().min(1),
+	"password": z.string().min(6),
+	"displayName": z.string().optional(),
+	"email": z.string().optional()
+}),
+		data: z.object({
+	"id": z.number()
+}),
+	},
+	"systemUsersForbiddenPut": {
+		query: z.object({
+	"uid": z.number()
+}),
+		body: z.object({
+	"forbidden": z.boolean()
+}),
+	},
+	"systemUsersPasswordPut": {
+		query: z.object({
+	"uid": z.number()
+}),
+		body: z.object({
+	"password": z.string().min(6)
+}),
+	},
+	"systemUsersRolesPut": {
+		query: z.object({
+	"uid": z.number()
+}),
+		body: z.object({
+	"roles": z.array(z.string())
+}),
+	},
+};

package/templates/web/src/system/__client/api.ts

@@ -0,0 +1,358 @@
+/* eslint-disable */
+// 生成物：ojm api 从契约生成，勿手改（改动请改契约文件后重跑 ojm api）
+import { ContractApiError } from "@oj-module/runtime/contract/errors";
+import type { ScopedRequestLike } from "@oj-module/runtime/contract/errors";
+import type { ModuleContext } from "@oj-module/runtime";
+import type { z } from "@oj-module/runtime";
+import type { schemas } from "./api.schemas";
+
+/** oj 信封（AC-D16）：code=0 成功；非 0 时 HTTP status=code，由 toApiError 归一为 ContractApiError */
+interface OjEnvelope<T> { code: number, msg?: string, data?: T }
+
+let req: ScopedRequestLike | undefined;
+
+/** 线上 API 前缀（ojm api 从契约抽取，唯一真源，勿手改）：请求基址 + 前缀登记用 */
+export const API_PREFIX = "/system";
+
+/** 认领身份前缀（契约 apiPrefix，字面等于模块目录名）：跨模块认领护栏对比基准 */
+export const MODULE_PREFIX = "/system";
+
+/**
+ * 模块 entry 的 onInit 里一行创建（构造即 install）：完成 apiPrefix 登记 +
+ * scoped request 绑定，返回绑好前缀的端点函数集合。一模块一 client；
+ * 重复构造幂等安全（前缀重复登记同值、request 重绑同值）。
+ */
+export function createSystemClient(ctx: ModuleContext) {
+	// 跨模块认领护栏（DEV）：工厂知道自己该属于谁（MODULE_PREFIX = 契约 apiPrefix），
+	// ctx 又带 module.name——名实不符说明别的模块在替本模块创建 client，会共享 request
+	// 单槽、卸载互相耦合；跨模块需求应由本模块创建后经 provider 暴露。
+	// 注意对比基准是 MODULE_PREFIX（目录名）而非 API_PREFIX——D-M8 映射时线上前缀
+	// 属于别的命名空间，认领身份仍按目录名。
+	if (import.meta.env.DEV && ctx.module.name !== MODULE_PREFIX.slice(1)) {
+		console.warn(`[ojm-api] 模块 "${ctx.module.name}" 正在认领 ${MODULE_PREFIX} 的 client——跨模块认领会共享 request 单槽、卸载互相耦合；应由 "${MODULE_PREFIX.slice(1)}" 模块在自身 onInit 创建，跨模块需求经 provider 暴露。`);
+	}
+	ctx.register.apiPrefix(API_PREFIX);
+	bindRequest(ctx.utils.request);
+	return { systemLoginMethodsGet, systemOplogGet, systemPermissionsGet, systemRolesGet, systemRolesPost, systemRolesDelete, systemRolesBindingsPut, systemSettingsGet, systemSettingsPut, systemUsersGet, systemUsersPost, systemUsersForbiddenPut, systemUsersPasswordPut, systemUsersRolesPut };
+}
+
+/**
+ * @deprecated 请改用 createSystemClient(ctx)——工厂构造即完成
+ * 前缀登记 + request 绑定，不会出现「登记了前缀没绑 request」的半接线状态。
+ */
+export function bindRequest(r: ScopedRequestLike): void {
+	req = r;
+}
+
+function ensureReq(): ScopedRequestLike {
+	if (!req)
+		throw new ContractApiError(-1, "[ojm-api] 请求未绑定——请在模块 entry.ts 的 onInit 里调用 createSystemClient(ctx)（或 bindRequest(ctx.utils.request)）。");
+	return req;
+}
+
+/** ky HTTPError → ContractApiError（错误体为信封时取 code/msg）；契约违例与原错误原样透传 */
+async function toApiError(e: unknown): Promise<unknown> {
+	if (e instanceof ContractApiError)
+		return e;
+	// ky 2.x 构造 HTTPError 时已用 getReader() 消费掉原 response 体（res.clone().json() 按规范抛 TypeError，
+	// 体方法一律失效），解析好的错误体在公开字段 error.data——故读 error.data，勿改回 clone().json()。
+	const err = e as { data?: { code?: unknown, msg?: string }, response?: Response } | null;
+	const res = err?.response;
+	const d = err?.data;
+	if (res instanceof Response && d && typeof d.code === "number")
+		return new ContractApiError(d.code, d.msg ?? res.statusText);
+	return e;
+}
+
+export type SystemLoginMethodsGetData = z.infer<(typeof schemas)["systemLoginMethodsGet"]["data"]>;
+
+export async function systemLoginMethodsGet(): Promise<SystemLoginMethodsGetData> {
+	const client = ensureReq();
+	try {
+		const env = await client.get(`system/login-methods`).json<OjEnvelope<SystemLoginMethodsGetData>>();
+		// 2xx + code!==0 也是业务错误（§6.2 通道 a）：oj 不会这么发，但契约机制的价值恰是防漂移
+		if (typeof env.code === "number" && env.code !== 0)
+			throw new ContractApiError(env.code, env.msg ?? "业务错误（信封 code 非 0）");
+		const data = env.data as SystemLoginMethodsGetData;
+		if (import.meta.env.DEV) {
+			const { schemas } = await import("./api.schemas");
+			const r = schemas["systemLoginMethodsGet"].data.safeParse(data);
+			if (!r.success)
+				throw new ContractApiError(-1, `[契约违例] systemLoginMethodsGet 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+		}
+		return data;
+	}
+	catch (e) {
+		throw await toApiError(e);
+	}
+}
+
+export type SystemOplogGetQuery = z.input<(typeof schemas)["systemOplogGet"]["query"]>;
+export type SystemOplogGetData = z.infer<(typeof schemas)["systemOplogGet"]["data"]>;
+
+export async function systemOplogGet(query: SystemOplogGetQuery): Promise<SystemOplogGetData> {
+	const client = ensureReq();
+	try {
+		const env = await client.get(`system/oplog`, { searchParams: query as Record<string, string | number | boolean> }).json<OjEnvelope<SystemOplogGetData>>();
+		// 2xx + code!==0 也是业务错误（§6.2 通道 a）：oj 不会这么发，但契约机制的价值恰是防漂移
+		if (typeof env.code === "number" && env.code !== 0)
+			throw new ContractApiError(env.code, env.msg ?? "业务错误（信封 code 非 0）");
+		const data = env.data as SystemOplogGetData;
+		if (import.meta.env.DEV) {
+			const { schemas } = await import("./api.schemas");
+			const r = schemas["systemOplogGet"].data.safeParse(data);
+			if (!r.success)
+				throw new ContractApiError(-1, `[契约违例] systemOplogGet 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+		}
+		return data;
+	}
+	catch (e) {
+		throw await toApiError(e);
+	}
+}
+
+export type SystemPermissionsGetData = z.infer<(typeof schemas)["systemPermissionsGet"]["data"]>;
+
+export async function systemPermissionsGet(): Promise<SystemPermissionsGetData> {
+	const client = ensureReq();
+	try {
+		const env = await client.get(`system/permissions`).json<OjEnvelope<SystemPermissionsGetData>>();
+		// 2xx + code!==0 也是业务错误（§6.2 通道 a）：oj 不会这么发，但契约机制的价值恰是防漂移
+		if (typeof env.code === "number" && env.code !== 0)
+			throw new ContractApiError(env.code, env.msg ?? "业务错误（信封 code 非 0）");
+		const data = env.data as SystemPermissionsGetData;
+		if (import.meta.env.DEV) {
+			const { schemas } = await import("./api.schemas");
+			const r = schemas["systemPermissionsGet"].data.safeParse(data);
+			if (!r.success)
+				throw new ContractApiError(-1, `[契约违例] systemPermissionsGet 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+		}
+		return data;
+	}
+	catch (e) {
+		throw await toApiError(e);
+	}
+}
+
+export type SystemRolesGetData = z.infer<(typeof schemas)["systemRolesGet"]["data"]>;
+
+export async function systemRolesGet(): Promise<SystemRolesGetData> {
+	const client = ensureReq();
+	try {
+		const env = await client.get(`system/roles`).json<OjEnvelope<SystemRolesGetData>>();
+		// 2xx + code!==0 也是业务错误（§6.2 通道 a）：oj 不会这么发，但契约机制的价值恰是防漂移
+		if (typeof env.code === "number" && env.code !== 0)
+			throw new ContractApiError(env.code, env.msg ?? "业务错误（信封 code 非 0）");
+		const data = env.data as SystemRolesGetData;
+		if (import.meta.env.DEV) {
+			const { schemas } = await import("./api.schemas");
+			const r = schemas["systemRolesGet"].data.safeParse(data);
+			if (!r.success)
+				throw new ContractApiError(-1, `[契约违例] systemRolesGet 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+		}
+		return data;
+	}
+	catch (e) {
+		throw await toApiError(e);
+	}
+}
+
+export type SystemRolesPostBody = z.input<(typeof schemas)["systemRolesPost"]["body"]>;
+export type SystemRolesPostData = z.infer<(typeof schemas)["systemRolesPost"]["data"]>;
+
+export async function systemRolesPost(body: SystemRolesPostBody): Promise<SystemRolesPostData> {
+	const client = ensureReq();
+	try {
+		const env = await client.post(`system/roles`, { json: body }).json<OjEnvelope<SystemRolesPostData>>();
+		// 2xx + code!==0 也是业务错误（§6.2 通道 a）：oj 不会这么发，但契约机制的价值恰是防漂移
+		if (typeof env.code === "number" && env.code !== 0)
+			throw new ContractApiError(env.code, env.msg ?? "业务错误（信封 code 非 0）");
+		const data = env.data as SystemRolesPostData;
+		if (import.meta.env.DEV) {
+			const { schemas } = await import("./api.schemas");
+			const r = schemas["systemRolesPost"].data.safeParse(data);
+			if (!r.success)
+				throw new ContractApiError(-1, `[契约违例] systemRolesPost 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+		}
+		return data;
+	}
+	catch (e) {
+		throw await toApiError(e);
+	}
+}
+
+export type SystemRolesDeleteQuery = z.input<(typeof schemas)["systemRolesDelete"]["query"]>;
+
+export async function systemRolesDelete(query: SystemRolesDeleteQuery): Promise<unknown> {
+	const client = ensureReq();
+	try {
+		const env = await client.delete(`system/roles`, { searchParams: query as Record<string, string | number | boolean> }).json<OjEnvelope<unknown>>();
+		// 2xx + code!==0 也是业务错误（§6.2 通道 a）：oj 不会这么发，但契约机制的价值恰是防漂移
+		if (typeof env.code === "number" && env.code !== 0)
+			throw new ContractApiError(env.code, env.msg ?? "业务错误（信封 code 非 0）");
+		const data = env.data as unknown;
+		return data;
+	}
+	catch (e) {
+		throw await toApiError(e);
+	}
+}
+
+export type SystemRolesBindingsPutQuery = z.input<(typeof schemas)["systemRolesBindingsPut"]["query"]>;
+export type SystemRolesBindingsPutBody = z.input<(typeof schemas)["systemRolesBindingsPut"]["body"]>;
+
+export async function systemRolesBindingsPut(input: { query: SystemRolesBindingsPutQuery, body: SystemRolesBindingsPutBody }): Promise<unknown> {
+	const client = ensureReq();
+	try {
+		const env = await client.put(`system/roles/bindings`, { searchParams: input.query as Record<string, string | number | boolean>, json: input.body }).json<OjEnvelope<unknown>>();
+		// 2xx + code!==0 也是业务错误（§6.2 通道 a）：oj 不会这么发，但契约机制的价值恰是防漂移
+		if (typeof env.code === "number" && env.code !== 0)
+			throw new ContractApiError(env.code, env.msg ?? "业务错误（信封 code 非 0）");
+		const data = env.data as unknown;
+		return data;
+	}
+	catch (e) {
+		throw await toApiError(e);
+	}
+}
+
+export type SystemSettingsGetData = z.infer<(typeof schemas)["systemSettingsGet"]["data"]>;
+
+export async function systemSettingsGet(): Promise<SystemSettingsGetData> {
+	const client = ensureReq();
+	try {
+		const env = await client.get(`system/settings`).json<OjEnvelope<SystemSettingsGetData>>();
+		// 2xx + code!==0 也是业务错误（§6.2 通道 a）：oj 不会这么发，但契约机制的价值恰是防漂移
+		if (typeof env.code === "number" && env.code !== 0)
+			throw new ContractApiError(env.code, env.msg ?? "业务错误（信封 code 非 0）");
+		const data = env.data as SystemSettingsGetData;
+		if (import.meta.env.DEV) {
+			const { schemas } = await import("./api.schemas");
+			const r = schemas["systemSettingsGet"].data.safeParse(data);
+			if (!r.success)
+				throw new ContractApiError(-1, `[契约违例] systemSettingsGet 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+		}
+		return data;
+	}
+	catch (e) {
+		throw await toApiError(e);
+	}
+}
+
+export type SystemSettingsPutBody = z.input<(typeof schemas)["systemSettingsPut"]["body"]>;
+
+export async function systemSettingsPut(body: SystemSettingsPutBody): Promise<unknown> {
+	const client = ensureReq();
+	try {
+		const env = await client.put(`system/settings`, { json: body }).json<OjEnvelope<unknown>>();
+		// 2xx + code!==0 也是业务错误（§6.2 通道 a）：oj 不会这么发，但契约机制的价值恰是防漂移
+		if (typeof env.code === "number" && env.code !== 0)
+			throw new ContractApiError(env.code, env.msg ?? "业务错误（信封 code 非 0）");
+		const data = env.data as unknown;
+		return data;
+	}
+	catch (e) {
+		throw await toApiError(e);
+	}
+}
+
+export type SystemUsersGetData = z.infer<(typeof schemas)["systemUsersGet"]["data"]>;
+
+export async function systemUsersGet(): Promise<SystemUsersGetData> {
+	const client = ensureReq();
+	try {
+		const env = await client.get(`system/users`).json<OjEnvelope<SystemUsersGetData>>();
+		// 2xx + code!==0 也是业务错误（§6.2 通道 a）：oj 不会这么发，但契约机制的价值恰是防漂移
+		if (typeof env.code === "number" && env.code !== 0)
+			throw new ContractApiError(env.code, env.msg ?? "业务错误（信封 code 非 0）");
+		const data = env.data as SystemUsersGetData;
+		if (import.meta.env.DEV) {
+			const { schemas } = await import("./api.schemas");
+			const r = schemas["systemUsersGet"].data.safeParse(data);
+			if (!r.success)
+				throw new ContractApiError(-1, `[契约违例] systemUsersGet 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+		}
+		return data;
+	}
+	catch (e) {
+		throw await toApiError(e);
+	}
+}
+
+export type SystemUsersPostBody = z.input<(typeof schemas)["systemUsersPost"]["body"]>;
+export type SystemUsersPostData = z.infer<(typeof schemas)["systemUsersPost"]["data"]>;
+
+export async function systemUsersPost(body: SystemUsersPostBody): Promise<SystemUsersPostData> {
+	const client = ensureReq();
+	try {
+		const env = await client.post(`system/users`, { json: body }).json<OjEnvelope<SystemUsersPostData>>();
+		// 2xx + code!==0 也是业务错误（§6.2 通道 a）：oj 不会这么发，但契约机制的价值恰是防漂移
+		if (typeof env.code === "number" && env.code !== 0)
+			throw new ContractApiError(env.code, env.msg ?? "业务错误（信封 code 非 0）");
+		const data = env.data as SystemUsersPostData;
+		if (import.meta.env.DEV) {
+			const { schemas } = await import("./api.schemas");
+			const r = schemas["systemUsersPost"].data.safeParse(data);
+			if (!r.success)
+				throw new ContractApiError(-1, `[契约违例] systemUsersPost 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+		}
+		return data;
+	}
+	catch (e) {
+		throw await toApiError(e);
+	}
+}
+
+export type SystemUsersForbiddenPutQuery = z.input<(typeof schemas)["systemUsersForbiddenPut"]["query"]>;
+export type SystemUsersForbiddenPutBody = z.input<(typeof schemas)["systemUsersForbiddenPut"]["body"]>;
+
+export async function systemUsersForbiddenPut(input: { query: SystemUsersForbiddenPutQuery, body: SystemUsersForbiddenPutBody }): Promise<unknown> {
+	const client = ensureReq();
+	try {
+		const env = await client.put(`system/users/forbidden`, { searchParams: input.query as Record<string, string | number | boolean>, json: input.body }).json<OjEnvelope<unknown>>();
+		// 2xx + code!==0 也是业务错误（§6.2 通道 a）：oj 不会这么发，但契约机制的价值恰是防漂移
+		if (typeof env.code === "number" && env.code !== 0)
+			throw new ContractApiError(env.code, env.msg ?? "业务错误（信封 code 非 0）");
+		const data = env.data as unknown;
+		return data;
+	}
+	catch (e) {
+		throw await toApiError(e);
+	}
+}
+
+export type SystemUsersPasswordPutQuery = z.input<(typeof schemas)["systemUsersPasswordPut"]["query"]>;
+export type SystemUsersPasswordPutBody = z.input<(typeof schemas)["systemUsersPasswordPut"]["body"]>;
+
+export async function systemUsersPasswordPut(input: { query: SystemUsersPasswordPutQuery, body: SystemUsersPasswordPutBody }): Promise<unknown> {
+	const client = ensureReq();
+	try {
+		const env = await client.put(`system/users/password`, { searchParams: input.query as Record<string, string | number | boolean>, json: input.body }).json<OjEnvelope<unknown>>();
+		// 2xx + code!==0 也是业务错误（§6.2 通道 a）：oj 不会这么发，但契约机制的价值恰是防漂移
+		if (typeof env.code === "number" && env.code !== 0)
+			throw new ContractApiError(env.code, env.msg ?? "业务错误（信封 code 非 0）");
+		const data = env.data as unknown;
+		return data;
+	}
+	catch (e) {
+		throw await toApiError(e);
+	}
+}
+
+export type SystemUsersRolesPutQuery = z.input<(typeof schemas)["systemUsersRolesPut"]["query"]>;
+export type SystemUsersRolesPutBody = z.input<(typeof schemas)["systemUsersRolesPut"]["body"]>;
+
+export async function systemUsersRolesPut(input: { query: SystemUsersRolesPutQuery, body: SystemUsersRolesPutBody }): Promise<unknown> {
+	const client = ensureReq();
+	try {
+		const env = await client.put(`system/users/roles`, { searchParams: input.query as Record<string, string | number | boolean>, json: input.body }).json<OjEnvelope<unknown>>();
+		// 2xx + code!==0 也是业务错误（§6.2 通道 a）：oj 不会这么发，但契约机制的价值恰是防漂移
+		if (typeof env.code === "number" && env.code !== 0)
+			throw new ContractApiError(env.code, env.msg ?? "业务错误（信封 code 非 0）");
+		const data = env.data as unknown;
+		return data;
+	}
+	catch (e) {
+		throw await toApiError(e);
+	}
+}

package/templates/web.config.ts

@@ -38,8 +38,8 @@ export default {
 		},
 		{
 			// 系统管理：用户/成员资格/角色权限/操作日志/站点设置/登录方式（oj 后端 /api/system/*）。
-			// __client 不随模板分发：init 后跑一次 `oj openapi -o openapi.json && ojm api` 生成；
-			// 生成前该模块加载失败（菜单缺失）属预期，README「系统管理模块」节有说明
+			// __client 已随模板分发（与 auth/notification 等一致），开箱即用；契约变更后重跑
+			// `oj openapi -o openapi.json && ojm api` 可刷新，README「系统管理模块」节有说明
 			name: "system",
 			entry: "web/src/system/entry.ts",
 			enabled: true,

package/vendor/host-versions.json

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