create-koa-boot 1.0.0

package/templates/example/backend/src/business/notification/notification.service.ts

@@ -0,0 +1,579 @@
+// 消息通知服务（V6.3）：事件触发写入 + 站内信查询/已读管理 + 库存预警实时检查
+// 三条独立链路：①站内信 sysMessage（始终写入）②外部渠道（EXTERNAL_NOTIFY_CHANNEL 单选旁路）
+// ③APP 推送（APP_PUSH_ENABLED 独立开关旁路，不受外部渠道影响）
+// emit 为旁路调用：内部捕获异常仅记日志，绝不回滚业务事务
+import 'reflect-metadata';
+import { Service } from 'typedi';
+import { Prisma } from '@prisma/client';
+import { prisma } from '../../config/database';
+import config from '../../config';
+import { MSG_TEMPLATES, MSG_TEMPLATE, JumpSpec } from './templates';
+import { usersByRole, dedupeReceivers, ReceiverSpec } from './receivers';
+import { ChannelAdapter, ChannelSendResult, WecomChannel, SmsChannel, EmailChannel, AppChannel } from './channel';
+import { PageResult, paginateQuery } from '../../common';
+
+/**
+ * 外部渠道适配器注册表（V6.2）：按 EXTERNAL_NOTIFY_CHANNEL 选择唯一渠道。
+ * - sms   = 阿里云短信
+ * - email = SMTP 邮件
+ * - wecom = 企业微信应用消息
+ * - 其他/空 = 不启用外部通知（仅站内信）
+ */
+function resolveExternalChannel(): ChannelAdapter | null {
+  switch (config.notify.externalChannel) {
+    case 'sms':
+      return new SmsChannel();
+    case 'email':
+      return new EmailChannel();
+    case 'wecom':
+      return config.wecom.enabled ? new WecomChannel() : null;
+    default:
+      return null;
+  }
+}
+
+/** 当前启用的外部渠道（测试发送与推送共用） */
+const EXTERNAL_ADAPTER: ChannelAdapter | null = resolveExternalChannel();
+
+/**
+ * APP 推送适配器（V6.3，独立链路）：仅由 APP_PUSH_ENABLED 开关控制，与外部渠道互不影响。
+ * 未开启开关时为 null（站内信与外部渠道照常）。
+ */
+const APP_ADAPTER: ChannelAdapter | null = config.appPush.enabled ? new AppChannel() : null;
+
+/** 测试推送结果（逐人明细，供测试界面展示） */
+export interface TestSendResult {
+  /** 有效接收人总数 */
+  total: number;
+  /** 成功发送人数 */
+  sentCount: number;
+  /** 无效的用户 ID（不存在/已停用） */
+  invalidIds: string[];
+  /** 成功发送的用户 */
+  sentUsers: {
+    id: string;
+    name: string | null;
+    phone: string | null;
+    email: string | null;
+    pushCid: string | null;
+  }[];
+  /** 发送失败的用户（未绑定企微 / 无手机号 / 无邮箱 / 未上报 cid / 发送报错） */
+  failedUsers: {
+    id: string;
+    name: string | null;
+    phone: string | null;
+    email: string | null;
+    pushCid: string | null;
+    reason: string;
+  }[];
+}
+
+@Service()
+export class NotificationService {
+  /**
+   * 事件触发入口：解析接收人 → 渲染模板 → 批量写入
+   * @param code 模板编码（唯一引用 MSG_TEMPLATE 枚举）
+   * @param vars 模板变量（含 bizId/bizId2 业务关联键；接收人解析所需字段）
+   * @param operatorId 触发操作人（系统自动触发时为空）
+   */
+  async emit(code: MSG_TEMPLATE, vars: Record<string, any>, operatorId?: string | null): Promise<void> {
+    try {
+      const def = MSG_TEMPLATES[code];
+      if (!def) {
+        console.error('[notify] 未知模板编码:', code);
+        return;
+      }
+      // 去重窗口（如库存预警 6 小时不重复发送）
+      if (def.dedupe) {
+        const since = new Date(Date.now() - def.dedupe.windowMs);
+        const existed = await prisma.sysMessage.findFirst({
+          where: {
+            templateCode: code,
+            createdAt: { gte: since },
+            ...def.dedupe.where(vars),
+          },
+          select: { id: true },
+        });
+        if (existed) return;
+      }
+
+      let receivers = await def.resolveReceivers(vars);
+      // 兜底：接收人集合为空时降级通知 admin，避免消息丢失（extraData 标记 fallback）
+      const fallback = receivers.length === 0;
+      if (fallback) {
+        receivers = await usersByRole('admin');
+        if (receivers.length === 0) return;
+      }
+
+      const content = def.render(vars);
+      const jump = def.jump(vars);
+      const effectiveReceivers = receivers.filter((r): r is ReceiverSpec & { userId: string } => Boolean(r.userId));
+      await prisma.sysMessage.createMany({
+        data: effectiveReceivers.map((r) => ({
+          msgType: def.msgType,
+          title: def.title,
+          content,
+          templateCode: code,
+          receiverUserId: r.userId,
+          receiverRoleCode: r.roleCode ?? null,
+          operatorId: operatorId ?? null,
+          bizType: def.bizType,
+          bizId: vars.bizId ?? null,
+          bizId2: vars.bizId2 ?? null,
+          extraData: { vars, jump, fallback: fallback || undefined } as any,
+        })),
+      });
+      // 外部渠道推送（旁路：短信/邮件/企微，按 EXTERNAL_NOTIFY_CHANNEL 单选）
+      await this.pushExternal(receivers, {
+        code,
+        title: def.title,
+        content,
+        jump,
+        bizType: def.bizType,
+        bizId: vars.bizId ?? null,
+      });
+      // APP 推送（独立链路旁路：APP_PUSH_ENABLED 开关，不受外部渠道影响）
+      await this.pushApp(receivers, {
+        code,
+        title: def.title,
+        content,
+        jump,
+        bizType: def.bizType,
+        bizId: vars.bizId ?? null,
+      });
+    } catch (e) {
+      // 通知为旁路：失败仅记日志，不影响业务主流程
+      console.error('[notify] emit 失败:', code, (e as Error).message);
+    }
+  }
+
+  /**
+   * 外部渠道推送（旁路）：发送并落发送日志
+   * 全部异常内部消化——推送失败绝不向上抛出，保证 emit 对业务零影响
+   */
+  private async pushExternal(
+    receivers: ReceiverSpec[],
+    payload: { code: string; title: string; content: string; jump: JumpSpec | null; bizType: string; bizId: string | null },
+  ): Promise<void> {
+    const adapter = EXTERNAL_ADAPTER;
+    if (!adapter) return;
+    const logBase: Prisma.NotificationSendLogUncheckedCreateInput = {
+      channel: adapter.channel,
+      templateCode: payload.code,
+      title: payload.title,
+      content: payload.content,
+      receiverUserIds: JSON.stringify(receivers.map((r) => r.userId)),
+      bizType: payload.bizType,
+      bizId: payload.bizId,
+    };
+    try {
+      const result: ChannelSendResult = await adapter.send({
+        templateCode: payload.code,
+        title: payload.title,
+        content: payload.content,
+        url: this.buildJumpUrl(payload.jump),
+        bizType: payload.bizType,
+        bizId: payload.bizId ?? undefined,
+        receivers,
+      });
+      await prisma.notificationSendLog.create({
+        data: {
+          ...logBase,
+          externalIds: result.externalIds.length ? JSON.stringify(result.externalIds) : null,
+          // 全部接收人未解析到外部标识时记为 skipped（短信=无手机号；企微=未绑定）
+          status: result.externalIds.length ? 'success' : 'skipped',
+        },
+      });
+    } catch (e) {
+      await prisma.notificationSendLog
+        .create({
+          data: {
+            ...logBase,
+            status: 'failed',
+            failReason: (e as Error).message.slice(0, 500),
+          },
+        })
+        .catch((logErr) => console.error('[notify] 发送日志落库失败:', (logErr as Error).message));
+      console.error(`[notify] ${adapter.channel} 推送失败:`, (e as Error).message);
+    }
+  }
+
+  /**
+   * APP 推送（独立链路旁路）：与 pushExternal 并列的旁路推送，按 APP_ADAPTER 发送并落发送日志。
+   * 配置不完整时静默跳过（不阻塞站内信与外部渠道）；全部异常内部消化。
+   */
+  private async pushApp(
+    receivers: ReceiverSpec[],
+    payload: { code: string; title: string; content: string; jump: JumpSpec | null; bizType: string; bizId: string | null },
+  ): Promise<void> {
+    const adapter = APP_ADAPTER;
+    if (!adapter || adapter.notConfiguredReason) return;
+    const logBase: Prisma.NotificationSendLogUncheckedCreateInput = {
+      channel: adapter.channel,
+      templateCode: payload.code,
+      title: payload.title,
+      content: payload.content,
+      receiverUserIds: JSON.stringify(receivers.map((r) => r.userId)),
+      bizType: payload.bizType,
+      bizId: payload.bizId,
+    };
+    try {
+      const result: ChannelSendResult = await adapter.send({
+        templateCode: payload.code,
+        title: payload.title,
+        content: payload.content,
+        url: this.buildJumpUrl(payload.jump),
+        bizType: payload.bizType,
+        bizId: payload.bizId ?? undefined,
+        receivers,
+      });
+      await prisma.notificationSendLog.create({
+        data: {
+          ...logBase,
+          externalIds: result.externalIds.length ? JSON.stringify(result.externalIds) : null,
+          // 全部接收人未上报 cid 时记为 skipped
+          status: result.externalIds.length ? 'success' : 'skipped',
+        },
+      });
+    } catch (e) {
+      await prisma.notificationSendLog
+        .create({
+          data: {
+            ...logBase,
+            status: 'failed',
+            failReason: (e as Error).message.slice(0, 500),
+          },
+        })
+        .catch((logErr) => console.error('[notify] 发送日志落库失败:', (logErr as Error).message));
+      console.error(`[notify] ${adapter.channel} 推送失败:`, (e as Error).message);
+    }
+  }
+
+  /**
+   * 外部通知测试推送接收人列表（仅管理员）：启用用户 + 角色名 + 送达状态（是否绑定企微/是否有手机号）
+   * 同时返回当前启用的外部渠道信息，供测试界面按渠道渲染
+   */
+  async listReceivers(keyword?: string): Promise<{
+    channel: {
+      type: string;
+      dependency: 'wechat_userid' | 'phone' | 'email' | 'push_cid';
+      configured: boolean;
+      reason?: string;
+    };
+    users: {
+      id: string;
+      username: string;
+      name: string | null;
+      phone: string | null;
+      email: string | null;
+      roleNames: string[];
+      deliverable: boolean;
+    }[];
+  }> {
+    const where: Prisma.UserWhereInput = { status: 'active' };
+    if (keyword?.trim()) {
+      const kw = keyword.trim();
+      where.OR = [
+        { name: { contains: kw } },
+        { username: { contains: kw } },
+        { phone: { contains: kw } },
+        { email: { contains: kw } },
+      ];
+    }
+    const users = await prisma.user.findMany({
+      where,
+      select: {
+        id: true,
+        username: true,
+        name: true,
+        phone: true,
+        email: true,
+        wechatUserid: true,
+        userRoles: { select: { role: { select: { name: true } } } },
+      },
+      orderBy: { createdAt: 'asc' },
+    });
+    const adapter = EXTERNAL_ADAPTER;
+    return {
+      channel: {
+        type: adapter?.channel ?? 'none',
+        dependency: adapter?.receiverDependency ?? 'phone',
+        configured: adapter ? !adapter.notConfiguredReason : false,
+        reason: adapter?.notConfiguredReason,
+      },
+      users: users.map((u) => ({
+        id: u.id,
+        username: u.username,
+        name: u.name,
+        phone: u.phone,
+        email: u.email,
+        roleNames: u.userRoles.map((ur) => ur.role.name),
+        // 企微渠道看是否绑定 userid；短信渠道看是否有手机号；邮件渠道看是否有邮箱
+        deliverable:
+          adapter?.receiverDependency === 'phone'
+            ? !!u.phone
+            : adapter?.receiverDependency === 'email'
+              ? !!u.email
+              : !!u.wechatUserid,
+      })),
+    };
+  }
+
+  /**
+   * 外部通知测试发送（仅管理员）：按当前渠道（EXTERNAL_NOTIFY_CHANNEL）发送，落发送日志，返回逐人结果
+   * 企微渠道：未绑定 userid 的用户自动按手机号解析；短信渠道：仅需手机号即可送达；邮件渠道：仅需邮箱即可送达
+   */
+  async testSend(payload: { receiverUserIds: string[]; title?: string; content: string }): Promise<TestSendResult> {
+    const adapter = EXTERNAL_ADAPTER;
+    if (!adapter) throw new Error('未启用外部通知：请配置 EXTERNAL_NOTIFY_CHANNEL（sms / email / wecom）');
+    if (adapter.notConfiguredReason) throw new Error(adapter.notConfiguredReason);
+
+    const userIds = [...new Set(payload.receiverUserIds ?? [])];
+    if (userIds.length === 0) throw new Error('请选择至少一位接收人');
+    const content = payload.content?.trim();
+    if (!content) throw new Error('请输入发送内容');
+    const title = payload.title?.trim() || '消息推送测试';
+
+    const users = await prisma.user.findMany({
+      where: { id: { in: userIds }, status: 'active' },
+      select: { id: true, name: true, phone: true, email: true, wechatUserid: true, pushCid: true },
+    });
+    const validIds = new Set(users.map((u) => u.id));
+    const invalidIds = userIds.filter((id) => !validIds.has(id));
+    if (users.length === 0) throw new Error('所选接收人不存在或已停用');
+
+    const receivers: ReceiverSpec[] = users.map((u) => ({ userId: u.id }));
+    const result = await adapter.send({
+      templateCode: 'TEST_SEND',
+      title,
+      content,
+      url: config.wecom.h5BaseUrl || '',
+      bizType: 'TEST',
+      receivers,
+    });
+    const failureMap = new Map(result.failures.map((f) => [f.userId, f.reason]));
+
+    const logBase: Prisma.NotificationSendLogUncheckedCreateInput = {
+      channel: adapter.channel,
+      templateCode: 'TEST_SEND',
+      title,
+      content,
+      receiverUserIds: JSON.stringify(users.map((u) => u.id)),
+      bizType: 'TEST',
+    };
+    await prisma.notificationSendLog.create({
+      data: {
+        ...logBase,
+        externalIds: result.externalIds.length ? JSON.stringify(result.externalIds) : null,
+        // 全部接收人未解析到外部标识时记为 skipped
+        status: result.externalIds.length ? 'success' : 'skipped',
+      },
+    });
+
+    return {
+      total: users.length,
+      sentCount: result.externalIds.length,
+      invalidIds,
+      sentUsers: users
+        .filter((u) => !failureMap.has(u.id))
+        .map((u) => ({ id: u.id, name: u.name, phone: u.phone, email: u.email, pushCid: u.pushCid })),
+      failedUsers: users
+        .filter((u) => failureMap.has(u.id))
+        .map((u) => ({
+          id: u.id,
+          name: u.name,
+          phone: u.phone,
+          email: u.email,
+          pushCid: u.pushCid,
+          reason: failureMap.get(u.id)!,
+        })),
+    };
+  }
+
+  /**
+   * APP 推送测试接收人列表（仅管理员，独立链路）：APP 推送启用状态 + 用户列表 + 是否已上报 cid
+   */
+  async appListReceivers(keyword?: string): Promise<{
+    channel: { type: string; dependency: 'push_cid'; configured: boolean; reason?: string };
+    users: {
+      id: string;
+      username: string;
+      name: string | null;
+      phone: string | null;
+      pushCid: string | null;
+      roleNames: string[];
+      deliverable: boolean;
+    }[];
+  }> {
+    const where: Prisma.UserWhereInput = { status: 'active' };
+    if (keyword?.trim()) {
+      const kw = keyword.trim();
+      where.OR = [
+        { name: { contains: kw } },
+        { username: { contains: kw } },
+        { phone: { contains: kw } },
+      ];
+    }
+    const users = await prisma.user.findMany({
+      where,
+      select: {
+        id: true,
+        username: true,
+        name: true,
+        phone: true,
+        pushCid: true,
+        userRoles: { select: { role: { select: { name: true } } } },
+      },
+      orderBy: { createdAt: 'asc' },
+    });
+    const adapter = APP_ADAPTER;
+    return {
+      channel: {
+        type: 'app',
+        dependency: 'push_cid',
+        configured: adapter ? !adapter.notConfiguredReason : false,
+        reason: adapter?.notConfiguredReason,
+      },
+      users: users.map((u) => ({
+        id: u.id,
+        username: u.username,
+        name: u.name,
+        phone: u.phone,
+        pushCid: u.pushCid,
+        roleNames: u.userRoles.map((ur) => ur.role.name),
+        // APP 渠道看是否已登录过 App 并上报 cid
+        deliverable: !!u.pushCid,
+      })),
+    };
+  }
+
+  /**
+   * APP 推送测试发送（仅管理员，独立链路）：按 APP_PUSH_ENABLED 开关推送，落发送日志，返回逐人结果
+   * 只有登录过 App 并上报过 cid 的用户可送达
+   */
+  async appTestSend(payload: { receiverUserIds: string[]; title?: string; content: string }): Promise<TestSendResult> {
+    const adapter = APP_ADAPTER;
+    if (!adapter) throw new Error('APP 推送未启用：请配置 APP_PUSH_ENABLED=true');
+    if (adapter.notConfiguredReason) throw new Error(adapter.notConfiguredReason);
+
+    const userIds = [...new Set(payload.receiverUserIds ?? [])];
+    if (userIds.length === 0) throw new Error('请选择至少一位接收人');
+    const content = payload.content?.trim();
+    if (!content) throw new Error('请输入发送内容');
+    const title = payload.title?.trim() || 'APP 推送测试';
+
+    const users = await prisma.user.findMany({
+      where: { id: { in: userIds }, status: 'active' },
+      select: { id: true, name: true, phone: true, email: true, pushCid: true },
+    });
+    const validIds = new Set(users.map((u) => u.id));
+    const invalidIds = userIds.filter((id) => !validIds.has(id));
+    if (users.length === 0) throw new Error('所选接收人不存在或已停用');
+
+    const receivers: ReceiverSpec[] = users.map((u) => ({ userId: u.id }));
+    const result = await adapter.send({
+      templateCode: 'TEST_SEND',
+      title,
+      content,
+      url: '',
+      bizType: 'TEST',
+      receivers,
+    });
+    const failureMap = new Map(result.failures.map((f) => [f.userId, f.reason]));
+
+    const logBase: Prisma.NotificationSendLogUncheckedCreateInput = {
+      channel: adapter.channel,
+      templateCode: 'TEST_SEND',
+      title,
+      content,
+      receiverUserIds: JSON.stringify(users.map((u) => u.id)),
+      bizType: 'TEST',
+    };
+    await prisma.notificationSendLog.create({
+      data: {
+        ...logBase,
+        externalIds: result.externalIds.length ? JSON.stringify(result.externalIds) : null,
+        status: result.externalIds.length ? 'success' : 'skipped',
+      },
+    });
+
+    return {
+      total: users.length,
+      sentCount: result.externalIds.length,
+      invalidIds,
+      sentUsers: users
+        .filter((u) => !failureMap.has(u.id))
+        .map((u) => ({ id: u.id, name: u.name, phone: u.phone, email: u.email, pushCid: u.pushCid })),
+      failedUsers: users
+        .filter((u) => failureMap.has(u.id))
+        .map((u) => ({
+          id: u.id,
+          name: u.name,
+          phone: u.phone,
+          email: u.email,
+          pushCid: u.pushCid,
+          reason: failureMap.get(u.id)!,
+        })),
+    };
+  }
+
+  /** 由模板 jump（path+query）拼接 admin H5 绝对地址，供 textcard 跳转 */
+  private buildJumpUrl(jump: JumpSpec | null): string {
+    const base = config.wecom.h5BaseUrl;
+    if (!jump || !base) return base || '';
+    const query = jump.query ? `?${new URLSearchParams(jump.query).toString()}` : '';
+    return `${base.replace(/\/+$/, '')}${jump.path}${query}`;
+  }
+
+  /** 分页查询当前用户消息（分类/已读筛选，按时间倒序） */
+  async getMessagesByPage(
+    userId: string,
+    params?: {
+      page?: number;
+      pageSize?: number;
+      msgType?: string;
+      isRead?: boolean;
+    },
+  ): Promise<PageResult<any>> {
+    const where: Record<string, any> = { receiverUserId: userId };
+    if (params?.msgType) where.msgType = params.msgType;
+    if (params?.isRead !== undefined) where.isRead = params.isRead;
+    const result = await paginateQuery<any>(
+      prisma.sysMessage,
+      { where, orderBy: { createdAt: 'desc' } },
+      params,
+    );
+    // 扁平化 extraData 中的跳转参数，供前端直接使用
+    const list = result.list.map((m: any) => {
+      const { extraData, ...rest } = m;
+      return { ...rest, jump: extraData?.jump ?? null };
+    });
+    return { list, pagination: result.pagination };
+  }
+
+  /** 未读消息数（顶栏红点） */
+  async getUnreadCount(userId: string): Promise<number> {
+    return prisma.sysMessage.count({ where: { receiverUserId: userId, isRead: false } });
+  }
+
+  /** 标记单条已读（仅限本人消息） */
+  async markRead(userId: string, id: string): Promise<boolean> {
+    const updated = await prisma.sysMessage.updateMany({
+      where: { id, receiverUserId: userId, isRead: false },
+      data: { isRead: true, readTime: new Date() },
+    });
+    return updated.count > 0;
+  }
+
+  /** 全部标记已读（仅限本人消息） */
+  async markAllRead(userId: string): Promise<number> {
+    const updated = await prisma.sysMessage.updateMany({
+      where: { receiverUserId: userId, isRead: false },
+      data: { isRead: true, readTime: new Date() },
+    });
+    return updated.count;
+  }
+
+  /** 接收人去重工具（供模板注册表内部使用的静态导出） */
+  static dedupeReceivers = dedupeReceivers;
+}

package/templates/example/backend/src/business/notification/receivers.ts

@@ -0,0 +1,44 @@
+// 接收人解析（通用化版）：供应链角色解析（门店/仓库负责人）已随框架裁剪移除，
+// 用户业务接收人解析规则（如按自定义角色/部门/自定义表）在此文件扩展。
+
+/** 接收人描述：指定用户或按角色（可选字段形式，便于各类渠道统一读取 userId） */
+export interface ReceiverSpec {
+  /** 直接指定用户 ID（优先） */
+  userId?: string;
+  /** 按角色编码（用户扩展业务接收人规则时可解析为 userId 后再下发） */
+  roleCode?: string;
+}
+
+/**
+ * 按角色编码解析用户列表（admin/manager/...）。
+ * 角色编码在 sys_roles.code 中定义。
+ */
+export async function usersByRole(roleCode: string): Promise<ReceiverSpec[]> {
+  const { prisma } = await import('../../config/database.js');
+  const users = await prisma.user.findMany({
+    where: { userRoles: { some: { role: { code: roleCode, status: 'active' } } }, status: 'active' },
+    select: { id: true },
+  });
+  return users.map((u) => ({ userId: u.id }));
+}
+
+/** 接收人去重（按 userId/roleCode 去重，保留第一个） */
+export function dedupeReceivers(specs: ReceiverSpec[]): ReceiverSpec[] {
+  const seenUser = new Set<string>();
+  const seenRole = new Set<string>();
+  const result: ReceiverSpec[] = [];
+  for (const s of specs) {
+    if (s.userId) {
+      if (!seenUser.has(s.userId)) {
+        seenUser.add(s.userId);
+        result.push(s);
+      }
+    } else if (s.roleCode) {
+      if (!seenRole.has(s.roleCode)) {
+        seenRole.add(s.roleCode);
+        result.push(s);
+      }
+    }
+  }
+  return result;
+}

package/templates/example/backend/src/business/notification/templates.ts

@@ -0,0 +1,72 @@
+// 消息模板注册表（通用化版）：枚举式集中管理，唯一维护入口
+// 模板机制与框架解耦：业务节点触发点只引用 MSG_TEMPLATE 枚举，禁止散落字符串。
+// 供应链模板（订货/出库/调拨/库存预警等）已在框架裁剪时移除，
+// 用户业务模板在此文件扩展：新增枚举值 + 在 MSG_TEMPLATES 注册即可。
+import {
+  ReceiverSpec,
+  usersByRole,
+  dedupeReceivers,
+} from './receivers';
+
+/** 消息模板编码（通用示例 3 个；用户业务模板在此扩展） */
+export enum MSG_TEMPLATE {
+  SYSTEM_ANNOUNCEMENT = 'SYSTEM_ANNOUNCEMENT', // 系统公告（发送给 admin）
+  WELCOME_NOTIFY = 'WELCOME_NOTIFY', // 欢迎/引导通知（发送给指定用户）
+  TEST_NOTIFY = 'TEST_NOTIFY', // 测试通知（测试发送入口）
+}
+
+/** 前端跳转参数（admin 端消息中心点击跳转） */
+export interface JumpSpec {
+  path: string;
+  query?: Record<string, string>;
+}
+
+/** 模板定义：类型 + 文案渲染 + 接收人解析 + 跳转 + 可选去重窗口 */
+export interface TemplateDef {
+  code: MSG_TEMPLATE;
+  msgType: 'TODO' | 'PROGRESS' | 'WARNING';
+  bizType: string;
+  title: string;
+  render: (vars: Record<string, any>) => string;
+  resolveReceivers: (vars: Record<string, any>) => Promise<ReceiverSpec[]>;
+  jump: (vars: Record<string, any>) => JumpSpec;
+  /** 可选去重窗口：窗口期内同模板不重复发送（如库存预警 6 小时） */
+  dedupe?: {
+    windowMs: number;
+    where: (vars: Record<string, any>) => any;
+  };
+}
+
+/** 模板注册表（唯一维护入口） */
+export const MSG_TEMPLATES: Record<MSG_TEMPLATE, TemplateDef> = {
+  [MSG_TEMPLATE.SYSTEM_ANNOUNCEMENT]: {
+    code: MSG_TEMPLATE.SYSTEM_ANNOUNCEMENT,
+    msgType: 'PROGRESS',
+    bizType: 'SYSTEM',
+    title: '📢 系统公告',
+    render: (v) => v.content ?? '',
+    resolveReceivers: async () => dedupeReceivers(await usersByRole('admin')),
+    jump: () => ({ path: '/notification' }),
+  },
+  [MSG_TEMPLATE.WELCOME_NOTIFY]: {
+    code: MSG_TEMPLATE.WELCOME_NOTIFY,
+    msgType: 'PROGRESS',
+    bizType: 'SYSTEM',
+    title: '👋 欢迎使用',
+    render: (v) => `欢迎 ${v.username ?? '用户'} 使用 Koa-Boot 示例项目。`,
+    resolveReceivers: async (v) => (v.userId ? [{ userId: v.userId }] : []),
+    jump: () => ({ path: '/notification' }),
+  },
+  [MSG_TEMPLATE.TEST_NOTIFY]: {
+    code: MSG_TEMPLATE.TEST_NOTIFY,
+    msgType: 'TODO',
+    bizType: 'SYSTEM',
+    title: '🔔 测试通知',
+    render: (v) => v.content ?? '',
+    resolveReceivers: async (v) => {
+      const ids = Array.isArray(v.receiverUserIds) ? v.receiverUserIds : [];
+      return dedupeReceivers(ids.map((id: string) => ({ userId: id })));
+    },
+    jump: () => ({ path: '/notification' }),
+  },
+};