@oj-module/cli 0.1.17 → 0.1.20

package/src/init.ts

@@ -209,6 +209,10 @@ function copyTemplates(
 		const src = path.join(srcDir, entry.name);
 		const dest = path.join(destDir, entry.name);
 		if (entry.isDirectory()) {
+			// 空目录不进工程：git 不跟踪空目录，模板里残留的空目录（如误建的
+			// api/src/_shared）会被 oj build 当作缺 manifest.yaml 的模块 fail-fast
+			if (!dirHasFiles(src))
+				continue;
 			fs.mkdirSync(dest, { recursive: true });
 			copyTemplates(src, dest, placeholders, report);
 			continue;
@@ -227,6 +231,17 @@ function copyTemplates(
 	}
 }
 
+/** 目录（递归）是否含至少一个文件——空目录判定供 copyTemplates 跳过用 */
+function dirHasFiles(dir: string): boolean {
+	for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+		if (entry.isFile())
+			return true;
+		if (entry.isDirectory() && dirHasFiles(path.join(dir, entry.name)))
+			return true;
+	}
+	return false;
+}
+
 function copyIfAbsent(src: string, dest: string, report: InitReport): void {
 	if (fs.existsSync(dest)) {
 		report.skipped.push(path.basename(dest));
@@ -306,9 +321,9 @@ function generatePackageJson(cliRoot: string, projectName: string) {
 
 	const devDeps: Record<string, string> = {
 		"@oj-module/cli": cliPkg.version,
-		// runtime 必须显式声明：uni-dev 工程的 contract.ts 与生成 client 直接 import
-		// `@oj-module/runtime/contract[/errors]`，`ojm api` 在 Node 侧求值契约时
-		// 需从工程 node_modules 解析真实现（evaluateContract 把裸说明符 external）。
+		// runtime 必须显式声明：生成的 __client 与 web 模块直接 import
+		// `@oj-module/runtime`（契约层在 oj handler 的 .schema/.response 上，
+		// 经 openapi.json 进 client，不再经过 runtime/contract 的 Node 侧求值）。
 		"@oj-module/runtime": pin("@oj-module/runtime"),
 		"@ant-design/icons": pin("@ant-design/icons"),
 		// personal-center 的 ProForm 用到——仅取**类型**（运行时由宿主 importmap 提供单例）

package/src/oj.ts

@@ -27,8 +27,12 @@ export interface OjProcess {
 	ready: Promise<void>
 	/** SIGTERM 回收，3s 不退升级 SIGKILL；已退出则立即返回 */
 	stop: () => Promise<void>
-	/** 同步强杀（SIGKILL）：仅作进程退出兜底，防 oj 孤儿化 */
-	kill: () => void
+	/**
+	 * 同步强杀（SIGKILL）：仅作进程退出兜底，防 oj 孤儿化。
+	 * 可选：唯一消费点（dev 的 process exit 兜底）按 `kill?.()` 宽容调用；
+	 * 未 spawn 真实进程的实现（测试桩）可不提供。
+	 */
+	kill?: () => void
 }
 
 export interface StartOjPoll {

package/src/vendor.ts

@@ -27,12 +27,16 @@ export const NPM_PKG = "@oj-bin/oj";
  *   0.1.13 / 0.1.16 / 0.1.19 / 0.1.24 / 0.1.26 / 0.1.28 → 启动子命令 `server`
  *   0.1.32 起 → `serve`
  * 即 `server` → `serve` 的改名落在 (0.1.28, 0.1.32]。改名刚发生时 npm 通道只到
- * 0.1.32，门禁曾暂定 0.1.32（否则 vendor/init 没有可用来源）；现 npm 已发布
- * 0.1.50，门禁即抬到当前最新。
+ * 0.1.32，门禁曾暂定 0.1.32（否则 vendor/init 没有可用来源）；后随发布进度抬到
+ * 0.1.69（含嵌套 handler 组 v0.1.64 等，迁移指引见
+ * docs/superpowers/specs/2026-10-14-ojm-0.1.18-design.md）；**0.1.20 抬到 0.1.73**：
+ * 平级 `.response` 出参声明位自 oj v0.1.72 起、`oj openapi` 的 `del`→`delete`
+ * 操作键归一自 v0.1.73 起，`ojm api` 的 openapi 流水线以这两者为前提
+ * （见 CHANGELOG 0.1.20 / docs/guides/api-codegen-openapi.md）。
  */
-export const MIN_OJ_VERSION = "0.1.50";
+export const MIN_OJ_VERSION = "0.1.73";
 
-/** 按段数值比较（字符串比较会把 0.1.9 判成大于 0.1.50）；非数字段按 0 处理 */
+/** 按段数值比较（字符串比较会把 0.1.9 判成大于 0.1.69）；非数字段按 0 处理 */
 export function isSupportedOjVersion(version: string): boolean {
 	const parse = (v: string) => v.replace(/^v/, "").split(".").map(n => Number.parseInt(n, 10) || 0);
 	const [major = 0, minor = 0, patch = 0] = parse(version);

package/templates/api/config.yaml

@@ -12,6 +12,7 @@ mounts:
   # - prefix: "/"
   #   web: "../web/dist"   # 相对 api/config.yaml → 项目根/web/dist
   #   spa: true
+  # 嵌套 handler 组（oj v0.1.64）无需配置开关，组织方式见 api.ts 顶部注释。
 
 server:
   host: 127.0.0.1 # 显式钉死：oj 默认绑 [::1]，localhost 解析序在反代下有坑

package/templates/api/src/auth/api.ts

@@ -0,0 +1,66 @@
+// oj v0.1.64 嵌套 handler 组：组名 = 路径段（login → POST /auth/login，路由不变）。
+// DDD 判据：同聚合（会话生命周期）多动词收进单文件；
+// 未来 register/reset/oauth 属新聚合、各自开目录。共享签发逻辑仍在 _shared/session.ts。
+import { issueTokens, nowSecs, sessionKey } from "./_shared/session";
+
+const login = {
+	// POST /api/auth/login —— 登录（devkit 手册 §8：auth 端点是业务路由）。
+	// 用户不存在与密码错同报 invalid credentials（不泄露用户存在性）。
+	async post() {
+		const body = http.body || {};
+		const rows = await db.query(
+			"select id, password_hash, roles from users where username = ?",
+			[String(body.username ?? "")],
+		);
+		const row = rows[0];
+		if (!row || !(await bcrypt.verify(String(body.password ?? ""), row.password_hash || ""))) {
+			json.fail(401, "invalid credentials");
+			return;
+		}
+		// roles 列按 JSON 数组串解析，失败回落空。
+		let roles: string[] = [];
+		try {
+			roles = JSON.parse(row.roles || "[]");
+		}
+		catch {
+			roles = [];
+		}
+		json.ok(await issueTokens(String(row.id), roles));
+	},
+};
+
+const logout = {
+	// POST /api/auth/logout —— 注销（删 refresh session；access 到期前仍有效）。
+	async post() {
+		const token = String((http.body || {}).refresh_token ?? "");
+		await kv.del(sessionKey(token));
+		json.ok(null);
+	},
+};
+
+const refresh = {
+	// POST /api/auth/refresh —— 刷新（轮换：旧 refresh 立即失效，一次一用）。
+	async post() {
+		const token = String((http.body || {}).refresh_token ?? "");
+		const key = sessionKey(token);
+		const raw = await kv.get(key);
+		const sess = raw ? JSON.parse(raw) : null;
+		if (!sess || !(sess.exp > nowSecs())) {
+			json.fail(401, "invalid or expired refresh token");
+			return;
+		}
+		// session 只存 uid——roles 重查库取最新。
+		const rows = await db.query("select roles from users where id = ?", [sess.uid]);
+		let roles: string[] = [];
+		try {
+			roles = JSON.parse((rows[0] || {}).roles || "[]");
+		}
+		catch {
+			roles = [];
+		}
+		await kv.del(key);
+		json.ok(await issueTokens(String(sess.uid), roles));
+	},
+};
+
+export default { login, logout, refresh };

package/templates/api/src/notification/_shared/notify.ts

@@ -0,0 +1,199 @@
+// 跨模块通知发射原语（sample 后端实现，本地模块）。
+//
+// 设计文档 §4.3：「Sample 后端（实现）：api/src/_shared/notify.ts 用 db 直写两表，
+// 是后端模块真正 import 的原语」。oj 只把 api/src 的【顶层】目录当作模块（须有 manifest.yaml），
+// 故共享原语不能放 api/src/_shared（会被当成缺 manifest 的模块），须嵌进所属模块目录
+// （此处嵌套在 notification/ 下）。后端解析裸 specifier 以 api/ 为项目根并钳制模块不越界
+// （api-manual 第 5 章），原语用相对导入、不能 import 来自 @oj-module/runtime 的包
+// （符号链接指向 packages/runtime，越出项目根）。
+//
+// 语义：原语不做任何业务判断（不判空间/角色/可见性），收件人过滤是发送方责任。
+// 按人通知落 notifications（user_id 必填）；广播落 notifications_broadcast（一行），
+// 已读状态走 notifications_broadcast_read 回执表，避免广播按人 fan-out 的信息爆炸。
+//
+// 类型与 runtime 的 @oj-module/runtime/notify 保持同形（前端契约面复用 runtime 类型）；
+// 此处本地定义以避免后端 import 越界。两处形状变更需同步。
+
+export type NoticeCategory = "notice" | "pm" | "mention";
+
+export interface NoticeItem {
+	id: string
+	scope: "user" | "broadcast"
+	avatar: string
+	date: string
+	isRead?: boolean
+	message: string
+	title: string
+	link?: string
+	category?: NoticeCategory
+}
+
+export interface PushInput {
+	userId: string | number
+	title: string
+	message: string
+	link?: string
+	avatar?: string
+	category?: NoticeCategory
+}
+
+export interface PushBroadcastInput {
+	title: string
+	message: string
+	link?: string
+	avatar?: string
+	category?: NoticeCategory
+}
+
+interface Row {
+	[k: string]: unknown
+}
+interface NotifyDb {
+	query: (sql: string, params?: unknown[]) => Promise<Row[]>
+	exec: (sql: string, params?: unknown[]) => Promise<number>
+}
+declare const db: NotifyDb;
+
+function nowStr(): string {
+	return new Date().toISOString().slice(0, 16).replace("T", " ");
+}
+
+function splitId(id: string): [scope: "u" | "b", raw: string] {
+	const i = id.indexOf(":");
+	if (i < 0)
+		return ["u", id];
+	return [id.slice(0, i) === "b" ? "b" : "u", id.slice(i + 1)];
+}
+
+function mapItem(r: Row): NoticeItem {
+	const scope = String(r.scope);
+	const isBroadcast = scope === "broadcast";
+	return {
+		id: (isBroadcast ? "b:" : "u:") + String(r.id),
+		scope: isBroadcast ? "broadcast" : "user",
+		avatar: String(r.avatar ?? ""),
+		date: String(r.date ?? ""),
+		isRead: Number(r.is_read) === 1,
+		message: String(r.message ?? ""),
+		title: String(r.title ?? ""),
+		link: r.link == null ? undefined : String(r.link),
+		category: (r.category as NoticeCategory) ?? "notice",
+	};
+}
+
+/** 给指定用户推一条按人通知，返回命名空间 id "u:<id>" */
+export async function pushNotice(input: PushInput): Promise<string> {
+	const ins = await db.query(
+		`INSERT INTO notifications (user_id, avatar, date, is_read, message, title, link, category)
+		 VALUES (?, ?, ?, 0, ?, ?, ?, ?) RETURNING id`,
+		[
+			Number(input.userId),
+			input.avatar ?? "",
+			nowStr(),
+			input.message,
+			input.title,
+			input.link ?? null,
+			input.category ?? "notice",
+		],
+	);
+	return `u:${Number(ins[0]!.id)}`;
+}
+
+/** 广播一条通知（全员可见，一行存储），返回命名空间 id "b:<id>" */
+export async function pushBroadcastNotice(input: PushBroadcastInput): Promise<string> {
+	const ins = await db.query(
+		`INSERT INTO notifications_broadcast (avatar, date, message, title, link, category, create_time)
+		 VALUES (?, ?, ?, ?, ?, ?, ?) RETURNING id`,
+		[
+			input.avatar ?? "",
+			nowStr(),
+			input.message,
+			input.title,
+			input.link ?? null,
+			input.category ?? "notice",
+			nowStr(),
+		],
+	);
+	return `b:${Number(ins[0]!.id)}`;
+}
+
+/**
+ * 删除通知。按人项校验归属：非本人返回 false；广播项仅删本人回执（幂等，返回 true）。
+ * 返回是否成功操作到目标（调用方据 false 判 403）。
+ */
+export async function delNotice(id: string, userId: string | number): Promise<boolean> {
+	const [scope, raw] = splitId(id);
+	const uid = Number(userId);
+	if (scope === "b") {
+		await db.exec(
+			"DELETE FROM notifications_broadcast_read WHERE broadcast_id = ? AND user_id = ?",
+			[Number(raw), uid],
+		);
+		return true;
+	}
+	const n = await db.exec(
+		"DELETE FROM notifications WHERE id = ? AND user_id = ?",
+		[Number(raw), uid],
+	);
+	return n > 0;
+}
+
+/** 取某用户的合并通知列表（广播 LEFT JOIN 回执算 is_read UNION 按人），按时间倒序 */
+export async function noticesFor(
+	userId: string | number,
+	opts: { offset?: number, limit?: number } = {},
+): Promise<NoticeItem[]> {
+	const limit = opts.limit ?? 50;
+	const offset = opts.offset ?? 0;
+	const uid = Number(userId);
+	const rows = await db.query(
+		`SELECT id, avatar, date, is_read, message, title, link, category, 'user' as scope
+		   FROM notifications WHERE user_id = ?
+		 UNION ALL
+		 SELECT b.id, b.avatar, b.date, (r.read_time IS NOT NULL AND r.read_time <> '') as is_read,
+		        b.message, b.title, b.link, b.category, 'broadcast' as scope
+		   FROM notifications_broadcast b
+		   LEFT JOIN notifications_broadcast_read r ON r.broadcast_id = b.id AND r.user_id = ?
+		 ORDER BY date DESC
+		 LIMIT ? OFFSET ?`,
+		[uid, uid, limit, offset],
+	);
+	return rows.map(mapItem);
+}
+
+/**
+ * 标记已读：按人项校验归属（非本人返回 false）；广播项 upsert 回执（始终 true）。
+ * 返回是否命中目标（调用方据 false 判 403，与 delNotice 对称）。
+ */
+export async function markRead(id: string, userId: string | number): Promise<boolean> {
+	const [scope, raw] = splitId(id);
+	const uid = Number(userId);
+	const now = nowStr();
+	if (scope === "b") {
+		await db.exec(
+			"INSERT OR IGNORE INTO notifications_broadcast_read (broadcast_id, user_id, read_time) VALUES (?, ?, ?)",
+			[Number(raw), uid, now],
+		);
+		return true;
+	}
+	const n = await db.exec("UPDATE notifications SET is_read = 1 WHERE id = ? AND user_id = ?", [Number(raw), uid]);
+	return n > 0;
+}
+
+/** 全部已读：按人项全置位 + 广播回执全 upsert */
+export async function markAllRead(userId: string | number): Promise<void> {
+	const uid = Number(userId);
+	const now = nowStr();
+	await db.exec("UPDATE notifications SET is_read = 1 WHERE user_id = ?", [uid]);
+	await db.exec(
+		"INSERT OR IGNORE INTO notifications_broadcast_read (broadcast_id, user_id, read_time) SELECT id, ?, ? FROM notifications_broadcast",
+		[uid, now],
+	);
+}
+
+/** 清空：删按人项 + 删本人广播回执（列表消失） */
+export async function clearNotices(userId: string | number): Promise<void> {
+	const uid = Number(userId);
+	await db.exec("DELETE FROM notifications WHERE user_id = ?", [uid]);
+	await db.exec("DELETE FROM notifications_broadcast_read WHERE user_id = ?", [uid]);
+}

package/templates/api/src/notification/api.ts

@@ -0,0 +1,231 @@
+// oj v0.1.64 嵌套 handler 组：组名 = 路径段（路由不变）。del 是 oj 保留动词键
+// （动词键下不允许挂子组），del/ 保留独立目录——唯一例外。
+// DDD 判据：notifications 表 = 一致性边界 = 一个聚合，读/已读/清空/推送/删除都是
+// 该聚合上的操作；发射三端点是薄 HTTP 壳，真逻辑在 ./_shared/notify。
+//
+// 契约（oj v0.1.72「最新方式」）：入参挂 `.schema`（params/query/body 三通道），
+// 出参挂平级 `.response`（动词级优先于组级，组级沿嵌套继承）——oj 运行期据此校验入参、
+// 并供 `oj openapi` 生成 openapi.json → 前端 `ojm api` 生成 __client。
+// `.schema` 是 JSON Schema 严格子集（关键字白名单），union 用类型数组表达（见 userId）。
+import { clearNotices, markAllRead, markRead, noticesFor, pushBroadcastNotice, pushNotice } from "./_shared/notify";
+
+const notifications = {
+	// GET /api/notification/notifications —— 通知列表（按人真实通知）。
+	// 合并：广播(LEFT JOIN 回执算 is_read) UNION 按人(WHERE user_id = ?)，命名空间 id。
+	// Bearer 守卫保护。直接复用 _shared/notify 原语 noticesFor 保证与发射端单一数据路径。
+	async get() {
+		const uid = http.user?.id;
+		if (!uid) {
+			json.fail(401, "unauthorized");
+			return;
+		}
+		try {
+			json.ok(await noticesFor(uid));
+		}
+		catch (e) {
+			json.fail(500, String(e));
+		}
+	},
+	// POST /api/notification/notifications/read —— 单条通知已读。
+	// body.id 为命名空间串 "u:<id>"（按人）/"b:<id>"（广播）；按人项校验归属，非本人 403。
+	"read": {
+		async post() {
+			const uid = http.user?.id;
+			if (!uid) {
+				json.fail(401, "unauthorized");
+				return;
+			}
+			const body = (http.body ?? {}) as { id?: unknown };
+			const id = String(body.id ?? "");
+			if (!id) {
+				json.fail(400, "id is required");
+				return;
+			}
+			try {
+				const ok = await markRead(id, uid);
+				if (!ok) {
+					json.fail(403, "forbidden");
+					return;
+				}
+				json.ok(null);
+			}
+			catch (e) {
+				json.fail(500, String(e));
+			}
+		},
+	},
+	// POST /api/notification/notifications/read-all —— 全部通知已读（按当前用户）。
+	"read-all": {
+		async post() {
+			const uid = http.user?.id;
+			if (!uid) {
+				json.fail(401, "unauthorized");
+				return;
+			}
+			try {
+				await markAllRead(uid);
+				json.ok(null);
+			}
+			catch (e) {
+				json.fail(500, String(e));
+			}
+		},
+	},
+	// POST /api/notification/notifications/clear —— 清空通知（按当前用户）。
+	// 删按人项 + 删本人广播回执（列表消失）。
+	"clear": {
+		async post() {
+			const uid = http.user?.id;
+			if (!uid) {
+				json.fail(401, "unauthorized");
+				return;
+			}
+			try {
+				await clearNotices(uid);
+				json.ok(null);
+			}
+			catch (e) {
+				json.fail(500, String(e));
+			}
+		},
+	},
+};
+
+// 通知列表出参（data payload）：命名空间 id + 按人/广播 scope + 已读态 + 分类。
+// oj v0.1.72 起出参走平级 .response（.schema 只放 body 等入参）。
+notifications.get.response = {
+	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"] },
+		},
+	},
+};
+
+// POST /api/notification/notifications/read —— body 仅需 id。
+notifications.read.post.schema = {
+	body: {
+		type: "object",
+		required: ["id"],
+		properties: { id: { type: "string" } },
+	},
+};
+
+// POST /api/notification/push —— 给指定用户推一条按人通知（发射原语 HTTP 入口）。
+// 真正逻辑在 _shared/notify.pushNotice（任一后端模块也可直接 import 调用，无需走 HTTP）。
+// Bearer 守卫保护；收件人过滤是发送方责任（原语不做业务判断）。
+// userId 类型数组 ["string","number"] 表达 z.union（oj 白名单不支持 union 关键字，
+// 用类型数组表达；handler 内 String() 归一，缺省回落当前用户）。
+const push = {
+	async post() {
+		const uid = http.user?.id;
+		if (!uid) {
+			json.fail(401, "unauthorized");
+			return;
+		}
+		const b = (http.body ?? {}) as {
+			userId?: unknown
+			title?: unknown
+			message?: unknown
+			link?: unknown
+			avatar?: unknown
+			category?: unknown
+		};
+		const target = b.userId ?? uid;
+		if (!b.title || !b.message) {
+			json.fail(400, "title and message are required");
+			return;
+		}
+		try {
+			const id = await pushNotice({
+				userId: target as string | number,
+				title: String(b.title),
+				message: String(b.message),
+				link: b.link != null ? String(b.link) : undefined,
+				avatar: b.avatar != null ? String(b.avatar) : undefined,
+				category: b.category as never,
+			});
+			json.ok({ id });
+		}
+		catch (e) {
+			json.fail(500, String(e));
+		}
+	},
+};
+
+push.post.schema = {
+	body: {
+		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"] },
+		},
+	},
+};
+
+// POST /api/notification/push-broadcast —— 广播一条通知（全员可见，一行存储）。
+// 真正逻辑在 _shared/notify.pushBroadcastNotice。Bearer 守卫保护。
+const broadcast = {
+	async post() {
+		const uid = http.user?.id;
+		if (!uid) {
+			json.fail(401, "unauthorized");
+			return;
+		}
+		const b = (http.body ?? {}) as {
+			title?: unknown
+			message?: unknown
+			link?: unknown
+			avatar?: unknown
+			category?: unknown
+		};
+		if (!b.title || !b.message) {
+			json.fail(400, "title and message are required");
+			return;
+		}
+		try {
+			const id = await pushBroadcastNotice({
+				title: String(b.title),
+				message: String(b.message),
+				link: b.link != null ? String(b.link) : undefined,
+				avatar: b.avatar != null ? String(b.avatar) : undefined,
+				category: b.category as never,
+			});
+			json.ok({ id });
+		}
+		catch (e) {
+			json.fail(500, String(e));
+		}
+	},
+};
+
+broadcast.post.schema = {
+	body: {
+		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"] },
+		},
+	},
+};
+
+export default { notifications, push, "push-broadcast": broadcast };

package/templates/api/src/notification/del/api.ts

@@ -0,0 +1,47 @@
+// POST /api/notification/del —— 删除一条通知（发射原语 HTTP 入口）。
+// 按人项校验归属，非本人返回 403；广播项仅删本人回执。Bearer 守卫保护。
+import { delNotice } from "../_shared/notify";
+
+// POST /api/notification/del —— 删除一条通知（发射原语 HTTP 入口）。
+// 按人项校验归属，非本人返回 403；广播项仅删本人回执。Bearer 守卫保护。
+// userId 类型数组表达 z.union（同 push）；缺省回落当前用户。
+const handler = {
+	async post() {
+		const uid = http.user?.id;
+		if (!uid) {
+			json.fail(401, "unauthorized");
+			return;
+		}
+		const b = (http.body ?? {}) as { id?: unknown, userId?: unknown };
+		const id = String(b.id ?? "");
+		if (!id) {
+			json.fail(400, "id is required");
+			return;
+		}
+		const target = b.userId ?? uid;
+		try {
+			const ok = await delNotice(id, target as string | number);
+			if (!ok) {
+				json.fail(403, "forbidden");
+				return;
+			}
+			json.ok(null);
+		}
+		catch (e) {
+			json.fail(500, String(e));
+		}
+	},
+};
+
+handler.post.schema = {
+	body: {
+		type: "object",
+		required: ["id"],
+		properties: {
+			id: { type: "string" },
+			userId: { type: ["string", "number"] },
+		},
+	},
+};
+
+export default handler;

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

@@ -1,5 +1,7 @@
 name: notification
-desc: 通知模块（契约化通知读写：读 + 单条已读 + 全部已读 + 清空；表与种子归属本模块）
+desc: 通知模块（契约化通知读写：读 + 单条已读 + 全部已读 + 清空 + 广播；表与种子归属本模块）
 version: 0.1.0
 tables:
   - notifications
+  - notifications_broadcast
+  - notifications_broadcast_read

package/templates/api/src/notification/migrations/0001__create_notifications.sql

@@ -1,4 +1,4 @@
--- notifications 模块建表：DDL 只进 migrations（S006）。is_read 用 INTEGER(0/1)。
+-- notification 模块建表（P4-2）。notifications 通知表，is_read 用 INTEGER(0/1)。
 CREATE TABLE IF NOT EXISTS notifications (
   id INTEGER PRIMARY KEY AUTOINCREMENT,
   avatar TEXT NOT NULL DEFAULT '',

package/templates/api/src/notification/migrations/0002__notifications_user.sql

@@ -0,0 +1,9 @@
+-- notification 模块表演进（升级为按人真实通知）：可空 ADD COLUMN + 索引 + 既有行归主。
+-- 三方言可移植：sqlite/mysql/pg 均支持 ALTER TABLE ADD COLUMN（含 DEFAULT）。
+ALTER TABLE notifications ADD COLUMN user_id INTEGER;
+ALTER TABLE notifications ADD COLUMN link TEXT;
+-- 类别：notice=通知/广播，pm=私信，mention=@我（占位）。NOT NULL + DEFAULT 保证既有行与新增行合规。
+ALTER TABLE notifications ADD COLUMN category TEXT NOT NULL DEFAULT 'notice';
+CREATE INDEX IF NOT EXISTS idx_notifications_user ON notifications (user_id, is_read);
+-- 既有演示行（user_id 为 NULL）归主到用户 1：不丢数据、不再全员可见。
+UPDATE notifications SET user_id = 1, category = 'notice' WHERE user_id IS NULL;

package/templates/api/src/notification/migrations/0003__notifications_broadcast.sql

@@ -0,0 +1,22 @@
+-- 广播/公告表（全局一行，避免按人 fan-out 造成的信息爆炸）+ 已读回执表（按人记录读状态）。
+-- 铃列表 = 广播(LEFT JOIN 回执算 is_read) UNION 按人(WHERE user_id = ?)。
+-- 三方言可移植：建表 + 索引均为标准 DDL。
+CREATE TABLE IF NOT EXISTS notifications_broadcast (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  avatar TEXT NOT NULL DEFAULT '',
+  date TEXT NOT NULL DEFAULT '',
+  message TEXT NOT NULL DEFAULT '',
+  title TEXT NOT NULL DEFAULT '',
+  link TEXT,
+  category TEXT NOT NULL DEFAULT 'notice',
+  create_time TEXT NOT NULL DEFAULT ''
+);
+
+CREATE TABLE IF NOT EXISTS notifications_broadcast_read (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  broadcast_id INTEGER NOT NULL,
+  user_id INTEGER NOT NULL,
+  read_time TEXT NOT NULL DEFAULT ''
+);
+
+CREATE INDEX IF NOT EXISTS idx_broadcast_read ON notifications_broadcast_read (user_id, broadcast_id);