@oj-module/cli 0.1.17 → 0.1.20

package/templates/api/src/notification/schema.yaml

@@ -1,11 +1,33 @@
-# 声明式表结构（§4.2 / D1-C）：notification 模块自有表 notifications。
+# 声明式表结构（§4.2 / D1-C）：notification 模块自有表。
+# 按人通知 notifications（user_id 归属 + link 深链 + category 类别）+ 广播两表。
 tables:
   notifications:
     pk: id
     columns:
       id: {type: integer, autoincrement: true}
+      user_id: {type: integer, null: true}
       avatar: {type: text, null: false}
       date: {type: text, null: false}
       is_read: {type: integer, null: false}
       message: {type: text, null: false}
       title: {type: text, null: false}
+      link: {type: text, null: true}
+      category: {type: text, null: false}
+  notifications_broadcast:
+    pk: id
+    columns:
+      id: {type: integer, autoincrement: true}
+      avatar: {type: text, null: false}
+      date: {type: text, null: false}
+      message: {type: text, null: false}
+      title: {type: text, null: false}
+      link: {type: text, null: true}
+      category: {type: text, null: false}
+      create_time: {type: text, null: false}
+  notifications_broadcast_read:
+    pk: id
+    columns:
+      id: {type: integer, autoincrement: true}
+      broadcast_id: {type: integer, null: false}
+      user_id: {type: integer, null: false}
+      read_time: {type: text, null: false}

package/templates/api/src/notification/seed.sql

@@ -1,4 +1,6 @@
--- notifications 模块种子：每次启动重放，必须幂等（INSERT OR IGNORE / 注释里别写分号）。
-INSERT OR IGNORE INTO notifications (id, avatar, date, is_read, message, title) VALUES (1, '', '2026-09-01 09:12', 0, '脚手架已就绪，用 admin / 123456 登录开始', '欢迎');
-INSERT OR IGNORE INTO notifications (id, avatar, date, is_read, message, title) VALUES (2, '', '2026-09-02 14:30', 0, '编辑 api/src 下的 api.ts 保存即热更，新增模块目录需重启 ojm dev', '开发提示');
-INSERT OR IGNORE INTO notifications (id, avatar, date, is_read, message, title) VALUES (3, '', '2026-09-03 18:45', 1, '契约改动后重跑 ojm api 生成前端 client 与文档', '契约');
+-- notification 模块种子（按人真实通知）。user_id=1（admin），link/category 幂等可空/默认。
+-- 按分号朴素切分（S006）：语句内不得含分号字面量。
+INSERT OR IGNORE INTO notifications (id, user_id, avatar, date, is_read, message, title, link, category) VALUES (1, 1, '', '2026-09-01 09:12', 0, '脚手架已就绪，用 admin / 123456 登录开始', '欢迎', NULL, 'notice');
+INSERT OR IGNORE INTO notifications (id, user_id, avatar, date, is_read, message, title, link, category) VALUES (2, 1, '', '2026-09-02 14:30', 0, '通知铃支持单条已读、全部已读与清空；广播经 push-broadcast 入 b: 命名空间', '通知铃', NULL, 'notice');
+INSERT OR IGNORE INTO notifications (id, user_id, avatar, date, is_read, message, title, link, category) VALUES (3, 1, '', '2026-09-03 18:45', 1, '契约改动后重跑 ojm api 生成前端 client 与文档', '契约', NULL, 'notice');
+INSERT OR IGNORE INTO notifications (id, user_id, avatar, date, is_read, message, title, link, category) VALUES (4, 1, '', '2026-09-04 08:00', 0, '编辑 api/src 下的 api.ts 保存即热更；handler 组支持四层嵌套（oj v0.1.64）', '开发提示', NULL, 'notice');

package/templates/api/src/personal-center/upload/api.ts

@@ -23,7 +23,8 @@ function toBase64(bytes: Uint8Array): string {
 	return out;
 }
 
-export default {
+// POST /api/personal-center/upload —— 头像上传（multipart→base64，P4-3，D7/F4）。
+const handler = {
 	async post() {
 		const uid = http.user?.id;
 		if (!uid) {
@@ -51,3 +52,13 @@ export default {
 		}
 	},
 };
+
+// 出参（data payload）= 上传后返回的资源 URL（data: URL）。body 是 multipipart，
+// 不在 .schema 白名单内（前端走 antd Upload 直连，不经 JSON client），故此处只声明出参。
+// oj v0.1.72 起出参走平级 .response（与 .schema 同级，动词级优先于组级），
+// .schema 只承载入参（params/query/body）。
+handler.post.response = {
+	type: "string",
+};
+
+export default handler;

package/templates/env.d.ts

@@ -1,6 +1,6 @@
 // 前端构建期全局类型（Vite 语义）。
 //
-// `ojm api` 生成的 client（web/src/<模块>/client/api.ts）会读
+// `ojm api` 生成的 client（web/src/<模块>/__client/api.ts）会读
 // `import.meta.env.DEV` 做开发期响应校验；脚手架不直接依赖 vite，
 // 故自带最小声明，避免 `pnpm typecheck` 对生成物报 TS2339
 // "Property 'env' does not exist on type 'ImportMeta'"。

package/templates/openapi.json

@@ -0,0 +1,471 @@
+{
+	"openapi": "3.1.0",
+	"info": {
+		"title": "oj API",
+		"version": "0.1.0"
+	},
+	"paths": {
+		"/api/auth/login": {
+			"post": {
+				"operationId": "auth_login_post",
+				"summary": "POST api/auth/login",
+				"x-oj-file": "auth/api.ts",
+				"tags": [
+					"auth"
+				],
+				"responses": {
+					"200": {
+						"description": "OK"
+					}
+				}
+			}
+		},
+		"/api/auth/logout": {
+			"post": {
+				"operationId": "auth_logout_post",
+				"summary": "POST api/auth/logout",
+				"x-oj-file": "auth/api.ts",
+				"tags": [
+					"auth"
+				],
+				"responses": {
+					"200": {
+						"description": "OK"
+					}
+				}
+			}
+		},
+		"/api/auth/refresh": {
+			"post": {
+				"operationId": "auth_refresh_post",
+				"summary": "POST api/auth/refresh",
+				"x-oj-file": "auth/api.ts",
+				"tags": [
+					"auth"
+				],
+				"responses": {
+					"200": {
+						"description": "OK"
+					}
+				}
+			}
+		},
+		"/api/notification/notifications": {
+			"get": {
+				"operationId": "notification_notifications_get",
+				"summary": "GET api/notification/notifications",
+				"x-oj-file": "notification/api.ts",
+				"tags": [
+					"notification"
+				],
+				"responses": {
+					"200": {
+						"description": "OK",
+						"x-oj-response-enforced": false,
+						"content": {
+							"application/json": {
+								"schema": {
+									"type": "object",
+									"required": [
+										"code",
+										"msg",
+										"data"
+									],
+									"properties": {
+										"code": {
+											"type": "integer"
+										},
+										"msg": {
+											"type": "string"
+										},
+										"data": {
+											"type": "array",
+											"items": {
+												"type": "object",
+												"required": [
+													"id",
+													"scope",
+													"avatar",
+													"date",
+													"message",
+													"title"
+												],
+												"properties": {
+													"id": {
+														"type": "string"
+													},
+													"scope": {
+														"type": "string",
+														"enum": [
+															"user",
+															"broadcast"
+														]
+													},
+													"avatar": {
+														"type": "string"
+													},
+													"date": {
+														"type": "string"
+													},
+													"isRead": {
+														"type": "boolean"
+													},
+													"message": {
+														"type": "string"
+													},
+													"title": {
+														"type": "string"
+													},
+													"link": {
+														"type": [
+															"string",
+															"null"
+														]
+													},
+													"category": {
+														"type": "string",
+														"enum": [
+															"notice",
+															"pm",
+															"mention"
+														]
+													}
+												}
+											}
+										}
+									}
+								}
+							}
+						}
+					}
+				}
+			}
+		},
+		"/api/notification/notifications/read": {
+			"post": {
+				"operationId": "notification_notifications_read_post",
+				"summary": "POST api/notification/notifications/read",
+				"x-oj-file": "notification/api.ts",
+				"tags": [
+					"notification"
+				],
+				"requestBody": {
+					"required": true,
+					"content": {
+						"application/json": {
+							"schema": {
+								"type": "object",
+								"required": [
+									"id"
+								],
+								"properties": {
+									"id": {
+										"type": "string"
+									}
+								}
+							}
+						}
+					}
+				},
+				"responses": {
+					"200": {
+						"description": "OK"
+					}
+				}
+			}
+		},
+		"/api/notification/notifications/read-all": {
+			"post": {
+				"operationId": "notification_notifications_read_all_post",
+				"summary": "POST api/notification/notifications/read-all",
+				"x-oj-file": "notification/api.ts",
+				"tags": [
+					"notification"
+				],
+				"responses": {
+					"200": {
+						"description": "OK"
+					}
+				}
+			}
+		},
+		"/api/notification/notifications/clear": {
+			"post": {
+				"operationId": "notification_notifications_clear_post",
+				"summary": "POST api/notification/notifications/clear",
+				"x-oj-file": "notification/api.ts",
+				"tags": [
+					"notification"
+				],
+				"responses": {
+					"200": {
+						"description": "OK"
+					}
+				}
+			}
+		},
+		"/api/notification/push": {
+			"post": {
+				"operationId": "notification_push_post",
+				"summary": "POST api/notification/push",
+				"x-oj-file": "notification/api.ts",
+				"tags": [
+					"notification"
+				],
+				"requestBody": {
+					"required": true,
+					"content": {
+						"application/json": {
+							"schema": {
+								"type": "object",
+								"required": [
+									"title",
+									"message"
+								],
+								"properties": {
+									"userId": {
+										"type": [
+											"string",
+											"number"
+										]
+									},
+									"title": {
+										"type": "string"
+									},
+									"message": {
+										"type": "string"
+									},
+									"link": {
+										"type": "string"
+									},
+									"avatar": {
+										"type": "string"
+									},
+									"category": {
+										"type": "string",
+										"enum": [
+											"notice",
+											"pm",
+											"mention"
+										]
+									}
+								}
+							}
+						}
+					}
+				},
+				"responses": {
+					"200": {
+						"description": "OK"
+					}
+				}
+			}
+		},
+		"/api/notification/push-broadcast": {
+			"post": {
+				"operationId": "notification_push_broadcast_post",
+				"summary": "POST api/notification/push-broadcast",
+				"x-oj-file": "notification/api.ts",
+				"tags": [
+					"notification"
+				],
+				"requestBody": {
+					"required": true,
+					"content": {
+						"application/json": {
+							"schema": {
+								"type": "object",
+								"required": [
+									"title",
+									"message"
+								],
+								"properties": {
+									"title": {
+										"type": "string"
+									},
+									"message": {
+										"type": "string"
+									},
+									"link": {
+										"type": "string"
+									},
+									"avatar": {
+										"type": "string"
+									},
+									"category": {
+										"type": "string",
+										"enum": [
+											"notice",
+											"pm",
+											"mention"
+										]
+									}
+								}
+							}
+						}
+					}
+				},
+				"responses": {
+					"200": {
+						"description": "OK"
+					}
+				}
+			}
+		},
+		"/api/notification/del": {
+			"post": {
+				"operationId": "notification_del_post",
+				"summary": "POST api/notification/del",
+				"x-oj-file": "notification/del/api.ts",
+				"tags": [
+					"notification"
+				],
+				"requestBody": {
+					"required": true,
+					"content": {
+						"application/json": {
+							"schema": {
+								"type": "object",
+								"required": [
+									"id"
+								],
+								"properties": {
+									"id": {
+										"type": "string"
+									},
+									"userId": {
+										"type": [
+											"string",
+											"number"
+										]
+									}
+								}
+							}
+						}
+					}
+				},
+				"responses": {
+					"200": {
+						"description": "OK"
+					}
+				}
+			}
+		},
+		"/api/notifications": {
+			"get": {
+				"operationId": "notifications_get",
+				"summary": "GET api/notifications",
+				"x-oj-file": "notifications/api.ts",
+				"tags": [
+					"notifications"
+				],
+				"responses": {
+					"200": {
+						"description": "OK"
+					}
+				}
+			}
+		},
+		"/api/personal-center/upload": {
+			"post": {
+				"operationId": "personal_center_upload_post",
+				"summary": "POST api/personal-center/upload",
+				"x-oj-file": "personal-center/upload/api.ts",
+				"tags": [
+					"personal-center"
+				],
+				"responses": {
+					"200": {
+						"description": "OK",
+						"x-oj-response-enforced": false,
+						"content": {
+							"application/json": {
+								"schema": {
+									"type": "object",
+									"required": [
+										"code",
+										"msg",
+										"data"
+									],
+									"properties": {
+										"code": {
+											"type": "integer"
+										},
+										"msg": {
+											"type": "string"
+										},
+										"data": {
+											"type": "string"
+										}
+									}
+								}
+							}
+						}
+					}
+				}
+			}
+		},
+		"/api/web/get-async-routes": {
+			"get": {
+				"operationId": "web_get_async_routes_get",
+				"summary": "GET api/web/get-async-routes",
+				"x-oj-file": "web/get-async-routes/api.ts",
+				"tags": [
+					"web"
+				],
+				"responses": {
+					"200": {
+						"description": "OK"
+					}
+				}
+			}
+		},
+		"/api/web/hello": {
+			"get": {
+				"operationId": "web_hello_get",
+				"summary": "GET api/web/hello",
+				"x-oj-file": "web/hello/api.ts",
+				"tags": [
+					"web"
+				],
+				"responses": {
+					"200": {
+						"description": "OK"
+					}
+				}
+			}
+		},
+		"/api/web/user-info": {
+			"get": {
+				"operationId": "web_user_info_get",
+				"summary": "GET api/web/user-info",
+				"x-oj-file": "web/user-info/api.ts",
+				"tags": [
+					"web"
+				],
+				"responses": {
+					"200": {
+						"description": "OK"
+					}
+				}
+			}
+		}
+	},
+	"tags": [
+		{
+			"name": "auth"
+		},
+		{
+			"name": "notification"
+		},
+		{
+			"name": "notifications"
+		},
+		{
+			"name": "personal-center"
+		},
+		{
+			"name": "web"
+		}
+	]
+}

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