@oj-module/cli 0.1.17 → 0.1.20

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

@@ -0,0 +1,50 @@
+/* eslint-disable */
+// 生成物：ojm api 从契约生成，勿手改（改动请改契约文件后重跑 ojm api）
+// AC-D15：仅供 DEV 校验动态 import，生产构建不进产物
+import { z } from "@oj-module/runtime";
+
+export const schemas = {
+	"notificationNotificationsGet": {
+		data: z.array(z.object({
+	"id": z.string(),
+	"scope": z.enum(["user", "broadcast"]),
+	"avatar": z.string(),
+	"date": z.string(),
+	"isRead": z.boolean().optional(),
+	"message": z.string(),
+	"title": z.string(),
+	"link": z.string().nullable().optional(),
+	"category": z.enum(["notice", "pm", "mention"]).optional()
+})),
+	},
+	"notificationNotificationsReadPost": {
+		body: z.object({
+	"id": z.string()
+}),
+	},
+	"notificationPushPost": {
+		body: z.object({
+	"userId": z.union([z.string(), z.number()]).optional(),
+	"title": z.string(),
+	"message": z.string(),
+	"link": z.string().optional(),
+	"avatar": z.string().optional(),
+	"category": z.enum(["notice", "pm", "mention"]).optional()
+}),
+	},
+	"notificationPushBroadcastPost": {
+		body: z.object({
+	"title": z.string(),
+	"message": z.string(),
+	"link": z.string().optional(),
+	"avatar": z.string().optional(),
+	"category": z.enum(["notice", "pm", "mention"]).optional()
+}),
+	},
+	"notificationDelPost": {
+		body: z.object({
+	"id": z.string(),
+	"userId": z.union([z.string(), z.number()]).optional()
+}),
+	},
+};

package/templates/web/src/notification/{client → __client}/api.ts

@@ -33,7 +33,7 @@ export function createNotificationClient(ctx: ModuleContext) {
 	}
 	ctx.register.apiPrefix(API_PREFIX);
 	bindRequest(ctx.utils.request);
-	return { clearAll, del, fetchNotifications, markAllRead, markRead, push, pushBroadcast };
+	return { notificationNotificationsGet, notificationNotificationsReadPost, notificationNotificationsReadAllPost, notificationNotificationsClearPost, notificationPushPost, notificationPushBroadcastPost, notificationDelPost };
 }
 
 /**
@@ -64,14 +64,22 @@ async function toApiError(e: unknown): Promise<unknown> {
 	return e;
 }
 
-export async function clearAll(): Promise<unknown> {
+export type NotificationNotificationsGetData = z.infer<(typeof schemas)["notificationNotificationsGet"]["data"]>;
+
+export async function notificationNotificationsGet(): Promise<NotificationNotificationsGetData> {
 	const client = ensureReq();
 	try {
-		const env = await client.post(`notification/notifications/clear`).json<OjEnvelope<unknown>>();
+		const env = await client.get(`notification/notifications`).json<OjEnvelope<NotificationNotificationsGetData>>();
 		// 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;
+		const data = env.data as NotificationNotificationsGetData;
+		if (import.meta.env.DEV) {
+			const { schemas } = await import("./api.schemas");
+			const r = schemas["notificationNotificationsGet"].data.safeParse(data);
+			if (!r.success)
+				throw new ContractApiError(-1, `[契约违例] notificationNotificationsGet 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+		}
 		return data;
 	}
 	catch (e) {
@@ -79,12 +87,12 @@ export async function clearAll(): Promise<unknown> {
 	}
 }
 
-export type DelBody = z.input<(typeof schemas)["del"]["body"]>;
+export type NotificationNotificationsReadPostBody = z.input<(typeof schemas)["notificationNotificationsReadPost"]["body"]>;
 
-export async function del(body: DelBody): Promise<unknown> {
+export async function notificationNotificationsReadPost(body: NotificationNotificationsReadPostBody): Promise<unknown> {
 	const client = ensureReq();
 	try {
-		const env = await client.post(`notification/del`, { json: body }).json<OjEnvelope<unknown>>();
+		const env = await client.post(`notification/notifications/read`, { 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）");
@@ -96,22 +104,14 @@ export async function del(body: DelBody): Promise<unknown> {
 	}
 }
 
-export type FetchNotificationsData = z.infer<(typeof schemas)["fetchNotifications"]["data"]>;
-
-export async function fetchNotifications(): Promise<FetchNotificationsData> {
+export async function notificationNotificationsReadAllPost(): Promise<unknown> {
 	const client = ensureReq();
 	try {
-		const env = await client.get(`notification/notifications`).json<OjEnvelope<FetchNotificationsData>>();
+		const env = await client.post(`notification/notifications/read-all`).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 FetchNotificationsData;
-		if (import.meta.env.DEV) {
-			const { schemas } = await import("./api.schemas");
-			const r = schemas.fetchNotifications.data.safeParse(data);
-			if (!r.success)
-				throw new ContractApiError(-1, `[契约违例] fetchNotifications 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
-		}
+		const data = env.data as unknown;
 		return data;
 	}
 	catch (e) {
@@ -119,10 +119,10 @@ export async function fetchNotifications(): Promise<FetchNotificationsData> {
 	}
 }
 
-export async function markAllRead(): Promise<unknown> {
+export async function notificationNotificationsClearPost(): Promise<unknown> {
 	const client = ensureReq();
 	try {
-		const env = await client.post(`notification/notifications/read-all`).json<OjEnvelope<unknown>>();
+		const env = await client.post(`notification/notifications/clear`).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）");
@@ -134,12 +134,12 @@ export async function markAllRead(): Promise<unknown> {
 	}
 }
 
-export type MarkReadBody = z.input<(typeof schemas)["markRead"]["body"]>;
+export type NotificationPushPostBody = z.input<(typeof schemas)["notificationPushPost"]["body"]>;
 
-export async function markRead(body: MarkReadBody): Promise<unknown> {
+export async function notificationPushPost(body: NotificationPushPostBody): Promise<unknown> {
 	const client = ensureReq();
 	try {
-		const env = await client.post(`notification/notifications/read`, { json: body }).json<OjEnvelope<unknown>>();
+		const env = await client.post(`notification/push`, { 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）");
@@ -151,12 +151,12 @@ export async function markRead(body: MarkReadBody): Promise<unknown> {
 	}
 }
 
-export type PushBody = z.input<(typeof schemas)["push"]["body"]>;
+export type NotificationPushBroadcastPostBody = z.input<(typeof schemas)["notificationPushBroadcastPost"]["body"]>;
 
-export async function push(body: PushBody): Promise<unknown> {
+export async function notificationPushBroadcastPost(body: NotificationPushBroadcastPostBody): Promise<unknown> {
 	const client = ensureReq();
 	try {
-		const env = await client.post(`notification/push`, { json: body }).json<OjEnvelope<unknown>>();
+		const env = await client.post(`notification/push-broadcast`, { 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）");
@@ -168,12 +168,12 @@ export async function push(body: PushBody): Promise<unknown> {
 	}
 }
 
-export type PushBroadcastBody = z.input<(typeof schemas)["pushBroadcast"]["body"]>;
+export type NotificationDelPostBody = z.input<(typeof schemas)["notificationDelPost"]["body"]>;
 
-export async function pushBroadcast(body: PushBroadcastBody): Promise<unknown> {
+export async function notificationDelPost(body: NotificationDelPostBody): Promise<unknown> {
 	const client = ensureReq();
 	try {
-		const env = await client.post(`notification/push-broadcast`, { json: body }).json<OjEnvelope<unknown>>();
+		const env = await client.post(`notification/del`, { 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）");

package/templates/web/src/notification/entry.ts

@@ -2,7 +2,7 @@ import type { NotificationsApiProvider } from "@oj-module/runtime";
 
 import { defineModule } from "@oj-module/runtime";
 
-import { createNotificationClient } from "./client/api";
+import { createNotificationClient } from "./__client/api";
 
 /**
  * notification 模块（G5 模板形态，对齐 apps/playground-oj/web/src/notification）。
@@ -21,23 +21,25 @@ export default defineModule({
 	lifecycle: {
 		async onInit(ctx) {
 			// 构造即接线：createNotificationClient 登记契约前缀 /notification
-			// （唯一真源在 client/api.ts 的 API_PREFIX）+ 绑定圈好前缀的 scoped
+			// （唯一真源在 __client/api.ts 的 API_PREFIX）+ 绑定圈好前缀的 scoped
 			// request（越界/穿越发请求前即拒绝，前缀收敛 D11），返回的 client
 			// 方法都自动带 /api/notification/ 前缀。
 			const notificationClient = createNotificationClient(ctx);
 			const provider: NotificationsApiProvider = {
-				fetchNotifications: () => notificationClient.fetchNotifications(),
+				// 端点函数名由 oj operationId 派生（camelCase 子路径 + 方法），
+				// 见 __client/api.ts；provider 方法名（fetchNotifications/markRead…）不变。
+				fetchNotifications: () => notificationClient.notificationNotificationsGet(),
 				// id 为命名空间串（"u:<id>" / "b:<id>"），原样透传
-				markRead: id => notificationClient.markRead({ id: String(id) }).then(() => {}),
-				markAllRead: () => notificationClient.markAllRead().then(() => {}),
-				clearAll: () => notificationClient.clearAll().then(() => {}),
+				markRead: id => notificationClient.notificationNotificationsReadPost({ id: String(id) }).then(() => {}),
+				markAllRead: () => notificationClient.notificationNotificationsReadAllPost().then(() => {}),
+				clearAll: () => notificationClient.notificationNotificationsClearPost().then(() => {}),
 				push: input => notificationClient
-					.push({ userId: input.userId, title: input.title, message: input.message, link: input.link, avatar: input.avatar, category: input.category })
+					.notificationPushPost({ userId: input.userId, title: input.title, message: input.message, link: input.link, avatar: input.avatar, category: input.category })
 					.then(r => String((r as { id: string }).id)),
 				pushBroadcast: input => notificationClient
-					.pushBroadcast({ title: input.title, message: input.message, link: input.link, avatar: input.avatar, category: input.category })
+					.notificationPushBroadcastPost({ title: input.title, message: input.message, link: input.link, avatar: input.avatar, category: input.category })
 					.then(r => String((r as { id: string }).id)),
-				del: (id, userId) => notificationClient.del({ id: String(id), userId }).then(() => {}),
+				del: (id, userId) => notificationClient.notificationDelPost({ id: String(id), userId }).then(() => {}),
 			};
 			ctx.register.notificationsApi(provider);
 		},

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

@@ -0,0 +1,8 @@
+/* eslint-disable */
+// 生成物：ojm api 从契约生成，勿手改（改动请改契约文件后重跑 ojm api）
+// AC-D15：仅供 DEV 校验动态 import，生产构建不进产物
+import { z } from "@oj-module/runtime";
+
+export const schemas = {
+
+};

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

@@ -0,0 +1,80 @@
+/* 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 = "/notifications";
+
+/** 认领身份前缀（契约 apiPrefix，字面等于模块目录名）：跨模块认领护栏对比基准 */
+export const MODULE_PREFIX = "/notifications";
+
+/**
+ * 模块 entry 的 onInit 里一行创建（构造即 install）：完成 apiPrefix 登记 +
+ * scoped request 绑定，返回绑好前缀的端点函数集合。一模块一 client；
+ * 重复构造幂等安全（前缀重复登记同值、request 重绑同值）。
+ */
+export function createNotificationsClient(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 { notificationsGet };
+}
+
+/**
+ * @deprecated 请改用 createNotificationsClient(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 里调用 createNotificationsClient(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 async function notificationsGet(): Promise<unknown> {
+	const client = ensureReq();
+	try {
+		const env = await client.get(`notifications`).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/src/personal-center/__client/api.schemas.ts

@@ -0,0 +1,10 @@
+/* eslint-disable */
+// 生成物：ojm api 从契约生成，勿手改（改动请改契约文件后重跑 ojm api）
+// AC-D15：仅供 DEV 校验动态 import，生产构建不进产物
+import { z } from "@oj-module/runtime";
+
+export const schemas = {
+	"personalCenterUploadPost": {
+		data: z.string(),
+	},
+};

package/templates/web/src/personal-center/__client/api.ts

@@ -0,0 +1,88 @@
+/* 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 = "/personal-center";
+
+/** 认领身份前缀（契约 apiPrefix，字面等于模块目录名）：跨模块认领护栏对比基准 */
+export const MODULE_PREFIX = "/personal-center";
+
+/**
+ * 模块 entry 的 onInit 里一行创建（构造即 install）：完成 apiPrefix 登记 +
+ * scoped request 绑定，返回绑好前缀的端点函数集合。一模块一 client；
+ * 重复构造幂等安全（前缀重复登记同值、request 重绑同值）。
+ */
+export function createPersonalCenterClient(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 { personalCenterUploadPost };
+}
+
+/**
+ * @deprecated 请改用 createPersonalCenterClient(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 里调用 createPersonalCenterClient(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 PersonalCenterUploadPostData = z.infer<(typeof schemas)["personalCenterUploadPost"]["data"]>;
+
+export async function personalCenterUploadPost(): Promise<PersonalCenterUploadPostData> {
+	const client = ensureReq();
+	try {
+		const env = await client.post(`personal-center/upload`).json<OjEnvelope<PersonalCenterUploadPostData>>();
+		// 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 PersonalCenterUploadPostData;
+		if (import.meta.env.DEV) {
+			const { schemas } = await import("./api.schemas");
+			const r = schemas["personalCenterUploadPost"].data.safeParse(data);
+			if (!r.success)
+				throw new ContractApiError(-1, `[契约违例] personalCenterUploadPost 响应与契约不符：${r.error.issues.map(i => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+		}
+		return data;
+	}
+	catch (e) {
+		throw await toApiError(e);
+	}
+}

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

@@ -0,0 +1,8 @@
+/* eslint-disable */
+// 生成物：ojm api 从契约生成，勿手改（改动请改契约文件后重跑 ojm api）
+// AC-D15：仅供 DEV 校验动态 import，生产构建不进产物
+import { z } from "@oj-module/runtime";
+
+export const schemas = {
+
+};

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

@@ -0,0 +1,110 @@
+/* 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 = "/web";
+
+/** 认领身份前缀（契约 apiPrefix，字面等于模块目录名）：跨模块认领护栏对比基准 */
+export const MODULE_PREFIX = "/web";
+
+/**
+ * 模块 entry 的 onInit 里一行创建（构造即 install）：完成 apiPrefix 登记 +
+ * scoped request 绑定，返回绑好前缀的端点函数集合。一模块一 client；
+ * 重复构造幂等安全（前缀重复登记同值、request 重绑同值）。
+ */
+export function createWebClient(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 { webGetAsyncRoutesGet, webHelloGet, webUserInfoGet };
+}
+
+/**
+ * @deprecated 请改用 createWebClient(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 里调用 createWebClient(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 async function webGetAsyncRoutesGet(): Promise<unknown> {
+	const client = ensureReq();
+	try {
+		const env = await client.get(`web/get-async-routes`).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 async function webHelloGet(): Promise<unknown> {
+	const client = ensureReq();
+	try {
+		const env = await client.get(`web/hello`).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 async function webUserInfoGet(): Promise<unknown> {
+	const client = ensureReq();
+	try {
+		const env = await client.get(`web/user-info`).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/vendor/host-versions.json

@@ -8,11 +8,11 @@
 		"react-router": "7.18.2",
 		"react-router/dom": "7.18.2",
 		"@tanstack/react-query": "5.102.8",
-		"@oj-module/runtime": "0.1.17",
-		"@oj-module/runtime/contract": "0.1.17",
-		"@oj-module/runtime/contract/errors": "0.1.17",
-		"@plane/kit": "0.1.17",
-		"@plane/editor": "0.1.17",
+		"@oj-module/runtime": "0.1.20",
+		"@oj-module/runtime/contract": "0.1.20",
+		"@oj-module/runtime/contract/errors": "0.1.20",
+		"@plane/kit": "0.1.20",
+		"@plane/editor": "0.1.20",
 		"antd": "6.6.1",
 		"antd/locale/en_US": "6.6.1",
 		"antd/locale/zh_CN": "6.6.1",