create-koa-boot 1.0.0

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

@@ -0,0 +1,273 @@
+// 消息渠道适配器（V6.3）：统一 ChannelAdapter 接口
+// 外部渠道（单选）：阿里云短信 / SMTP 邮件 / 企业微信应用消息，由 EXTERNAL_NOTIFY_CHANNEL 选择
+// APP 推送（独立链路）：UniPush 2.0，由 APP_PUSH_ENABLED 独立开关控制，不受外部渠道影响
+// 设计对齐 system-message-design.md：渠道开关 + 用户解析 + 发送日志由 service 层统一记录
+import { prisma } from '../../config/database';
+import { sendWecomTextCard, getWecomUseridByPhone } from '../../utils/wecom';
+import { sendSmsBatch, isSmsConfigured } from '../../utils/smsClient';
+import { sendEmailBatch, isEmailConfigured } from '../../utils/emailClient';
+import { pushToCids, isAppPushConfigured } from '../../utils/unipushClient';
+import { ReceiverSpec } from './receivers';
+
+/** 渠道发送载荷（由 NotificationService.emit 组装） */
+export interface ChannelSendPayload {
+  templateCode: string;
+  title: string;
+  content: string;
+  /** textcard 跳转地址（由模板 jump 拼接 admin H5 基础地址生成） */
+  url: string;
+  bizType?: string;
+  bizId?: string;
+  receivers: ReceiverSpec[];
+}
+
+/** 渠道发送结果：实际送达的外部接收标识（企微=userid，短信=手机号），供发送日志记录 */
+export interface ChannelSendResult {
+  /** 成功送达的外部标识列表（externalIds 字段落库） */
+  externalIds: string[];
+  /** 未送达明细（如未绑定企微 / 无手机号），供测试界面展示逐人原因 */
+  failures: { userId: string; reason: string }[];
+}
+
+/** 渠道适配器接口 */
+export interface ChannelAdapter {
+  readonly channel: string;
+  /** 描述该渠道接收人解析依赖（企微依赖 wechat_userid，短信依赖 phone，邮件依赖 email，APP 推送依赖 push_cid） */
+  readonly receiverDependency: 'wechat_userid' | 'phone' | 'email' | 'push_cid';
+  /** 未配置凭证时的提示（测试发送时展示给用户） */
+  readonly notConfiguredReason: string;
+  send(payload: ChannelSendPayload): Promise<ChannelSendResult>;
+  /**
+   * 解析接收人并返回可送达的外部标识 + 未送达明细。
+   * 短信渠道：仅需手机号即可送达；企微渠道：需要绑定 userid（可自动解析）；邮件渠道：仅需邮箱即可送达；
+   * APP 推送渠道：需要用户 App 登录上报过 cid（push_cid）
+   */
+  resolve(receivers: ReceiverSpec[]): Promise<{ externalIds: string[]; failures: { userId: string; reason: string }[] }>;
+}
+
+/**
+ * 企业微信应用消息适配器
+ * userid 解析策略（两条腿）：
+ * 1. 优先取 sys_users.wechat_userid（管理端维护/首次推送自动回写）
+ * 2. 为空且 WECOM_AUTO_BIND=true 时按手机号调企微 API 解析，成功后回写
+ */
+export class WecomChannel implements ChannelAdapter {
+  readonly channel = 'wechat_work';
+  readonly receiverDependency = 'wechat_userid' as const;
+  readonly notConfiguredReason =
+    '企业微信推送未启用：请检查 EXTERNAL_NOTIFY_CHANNEL=wecom 及企业微信凭证（WECOM_CORP_ID/AGENT_ID/SECRET）';
+
+  async send(payload: ChannelSendPayload): Promise<ChannelSendResult> {
+    const { externalIds, failures } = await this.resolve(payload.receivers);
+    if (externalIds.length === 0) return { externalIds, failures };
+    await sendWecomTextCard(externalIds, {
+      title: payload.title,
+      description: payload.content,
+      url: payload.url,
+    });
+    return { externalIds, failures };
+  }
+
+  /**
+   * 解析接收人的企微 userid（自动绑定：解析成功后回写 sys_users.wechat_userid）
+   * 返回成功解析的外部 userid 列表 + 未解析用户明细（供测试推送接口展示逐人结果）
+   */
+  async resolve(receivers: ReceiverSpec[]): Promise<{ externalIds: string[]; failures: { userId: string; reason: string }[] }> {
+    if (receivers.length === 0) return { externalIds: [], failures: [] };
+    const userIds = receivers.map((r) => r.userId).filter((id): id is string => !!id);
+    const users = await prisma.user.findMany({
+      where: { id: { in: userIds }, status: 'active' },
+      select: { id: true, wechatUserid: true, phone: true },
+    });
+    const externalIds: string[] = [];
+    const failures: { userId: string; reason: string }[] = [];
+    for (const u of users) {
+      if (u.wechatUserid) {
+        externalIds.push(u.wechatUserid);
+        continue;
+      }
+      const wid = await getWecomUseridByPhone(u.phone ?? '');
+      if (wid) {
+        externalIds.push(wid);
+        // 自动回写绑定，后续推送直接命中；失败不影响本次发送
+        await prisma.user
+          .update({ where: { id: u.id }, data: { wechatUserid: wid } })
+          .catch(() => {});
+      } else {
+        failures.push({ userId: u.id, reason: '未绑定企业微信账号（手机号解析失败）' });
+      }
+    }
+    return { externalIds, failures };
+  }
+}
+
+/**
+ * 阿里云短信适配器（V6.1）
+ * 直接以手机号为送达标识，无需 openid/userid 绑定；用户无手机号时计入失败。
+ * 短信为纯文本（无跳转链接），文案由模板自身决定。
+ */
+export class SmsChannel implements ChannelAdapter {
+  readonly channel = 'sms';
+  readonly receiverDependency = 'phone' as const;
+
+  get notConfiguredReason(): string {
+    const { reason } = isSmsConfigured();
+    return reason ?? '';
+  }
+
+  async send(payload: ChannelSendPayload): Promise<ChannelSendResult> {
+    const { externalIds, failures } = await this.resolve(payload.receivers);
+    if (externalIds.length === 0) return { externalIds, failures };
+    // 短信模板变量：content 为纯文本（短信不适合超长，截断 300 字）
+    const sentCount = await sendSmsBatch(externalIds, {
+      content: payload.content.slice(0, 300),
+      title: payload.title,
+    });
+    // 若全部失败（可能因阿里云单条限额/风控），上报 failures 供日志与测试界面展示
+    const failedPhones = sentCount < externalIds.length ? externalIds.slice(sentCount) : [];
+    const extendedFailures = [
+      ...failures,
+      ...failedPhones.map((phone) => ({ userId: phone, reason: '短信发送失败（详见日志）' })),
+    ];
+    return { externalIds: externalIds.slice(0, sentCount), failures: extendedFailures };
+  }
+
+  /**
+   * 解析接收人手机号：仅需手机号即可送达，无绑定概念
+   * 无手机号的用户计入 failures（短信无法触达）
+   */
+  async resolve(receivers: ReceiverSpec[]): Promise<{ externalIds: string[]; failures: { userId: string; reason: string }[] }> {
+    if (receivers.length === 0) return { externalIds: [], failures: [] };
+    const userIds = receivers.map((r) => r.userId).filter((id): id is string => !!id);
+    const users = await prisma.user.findMany({
+      where: { id: { in: userIds }, status: 'active' },
+      select: { id: true, phone: true },
+    });
+    const externalIds: string[] = [];
+    const failures: { userId: string; reason: string }[] = [];
+    for (const u of users) {
+      if (u.phone) {
+        externalIds.push(u.phone);
+      } else {
+        failures.push({ userId: u.id, reason: '用户未填写手机号，无法短信通知' });
+      }
+    }
+    return { externalIds, failures };
+  }
+}
+
+/** 简单 HTML 转义（邮件正文渲染时防 XSS 与格式丢失） */
+function escapeHtml(text: string): string {
+  return text
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+/**
+ * SMTP 邮件适配器（V6.2）
+ * 直接以邮箱为送达标识，无需绑定；用户未填写邮箱时计入失败。
+ * 邮件为 HTML 富文本：标题作为邮件主题，正文渲染为 HTML 段落（换行转 <br/>）。
+ */
+export class EmailChannel implements ChannelAdapter {
+  readonly channel = 'email';
+  readonly receiverDependency = 'email' as const;
+
+  get notConfiguredReason(): string {
+    const { reason } = isEmailConfigured();
+    return reason ?? '';
+  }
+
+  async send(payload: ChannelSendPayload): Promise<ChannelSendResult> {
+    const { externalIds, failures } = await this.resolve(payload.receivers);
+    if (externalIds.length === 0) return { externalIds, failures };
+    // 邮件主题 = 标题；正文 = HTML 段落（转义 + 换行转 <br/>）
+    const html = `<p style="margin:0;line-height:1.8;color:#333;font-size:14px;">${escapeHtml(
+      payload.content,
+    ).replace(/\n/g, '<br/>')}</p>`;
+    const sentCount = await sendEmailBatch(externalIds, payload.title, html);
+    // 部分发送失败时上报 failures 供日志与测试界面展示
+    const failedEmails = sentCount < externalIds.length ? externalIds.slice(sentCount) : [];
+    const extendedFailures = [
+      ...failures,
+      ...failedEmails.map((email) => ({ userId: email, reason: '邮件发送失败（详见日志）' })),
+    ];
+    return { externalIds: externalIds.slice(0, sentCount), failures: extendedFailures };
+  }
+
+  /**
+   * 解析接收人邮箱：仅需邮箱即可送达，无绑定概念
+   * 无邮箱的用户计入 failures（邮件无法触达）
+   */
+  async resolve(receivers: ReceiverSpec[]): Promise<{ externalIds: string[]; failures: { userId: string; reason: string }[] }> {
+    if (receivers.length === 0) return { externalIds: [], failures: [] };
+    const userIds = receivers.map((r) => r.userId).filter((id): id is string => !!id);
+    const users = await prisma.user.findMany({
+      where: { id: { in: userIds }, status: 'active' },
+      select: { id: true, email: true },
+    });
+    const externalIds: string[] = [];
+    const failures: { userId: string; reason: string }[] = [];
+    for (const u of users) {
+      if (u.email) {
+        externalIds.push(u.email);
+      } else {
+        failures.push({ userId: u.id, reason: '用户未填写邮箱，无法邮件通知' });
+      }
+    }
+    return { externalIds, failures };
+  }
+}
+
+/**
+ * APP 应用推送适配器（V6.3，独立链路）
+ * 以用户 App 端上报的 cid（push_cid）为送达标识；未上报（未登录过 App）的用户计入失败。
+ * 通知栏消息：点击启动 App；离线用户由厂商通道缓存补推。
+ */
+export class AppChannel implements ChannelAdapter {
+  readonly channel = 'app';
+  readonly receiverDependency = 'push_cid' as const;
+
+  get notConfiguredReason(): string {
+    const { reason } = isAppPushConfigured();
+    return reason ?? '';
+  }
+
+  async send(payload: ChannelSendPayload): Promise<ChannelSendResult> {
+    const { externalIds, failures } = await this.resolve(payload.receivers);
+    if (externalIds.length === 0) return { externalIds, failures };
+    const sentCount = await pushToCids(externalIds, payload.title, payload.content);
+    // 受理失败/离线未补推的 cid 计入 failures 供日志与测试界面展示
+    const failedCids = sentCount < externalIds.length ? externalIds.slice(sentCount) : [];
+    const extendedFailures = [
+      ...failures,
+      ...failedCids.map((cid) => ({ userId: cid, reason: '推送失败（详见日志）' })),
+    ];
+    return { externalIds: externalIds.slice(0, sentCount), failures: extendedFailures };
+  }
+
+  /**
+   * 解析接收人 cid：需 App 端登录后上报（push_cid），无绑定回退
+   * 未上报 cid 的用户计入 failures（App 推送无法触达）
+   */
+  async resolve(receivers: ReceiverSpec[]): Promise<{ externalIds: string[]; failures: { userId: string; reason: string }[] }> {
+    if (receivers.length === 0) return { externalIds: [], failures: [] };
+    const userIds = receivers.map((r) => r.userId).filter((id): id is string => !!id);
+    const users = await prisma.user.findMany({
+      where: { id: { in: userIds }, status: 'active' },
+      select: { id: true, pushCid: true },
+    });
+    const externalIds: string[] = [];
+    const failures: { userId: string; reason: string }[] = [];
+    for (const u of users) {
+      if (u.pushCid) {
+        externalIds.push(u.pushCid);
+      } else {
+        failures.push({ userId: u.id, reason: '用户未登录过 APP，无法推送（无设备标识）' });
+      }
+    }
+    return { externalIds, failures };
+  }
+}

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

@@ -0,0 +1,175 @@
+import { Controller, Get, Post, Patch, Route, Tags, Path, Query, Request, Body } from 'tsoa';
+import { NotificationService, TestSendResult } from './notification.service';
+import { SysMessageInfo } from './notification.model';
+import { success, fail, pageSuccess, ApiResponse, PageResult, BizCode } from '../../common';
+
+@Route('notification')
+@Tags('消息通知')
+export class NotificationController extends Controller {
+  private notificationService = new NotificationService();
+
+  /**
+   * 分页查询当前用户消息（分类/已读筛选，按时间倒序）
+   */
+  @Get('page')
+  public async getMessagesByPage(
+    @Request() req: any,
+    @Query() page?: number,
+    @Query() pageSize?: number,
+    @Query() msgType?: string,
+    @Query() isRead?: string,
+  ): Promise<ApiResponse<{ list: SysMessageInfo[]; pagination: PageResult<SysMessageInfo>['pagination'] } | null>> {
+    const user = req?.state?.user;
+    if (!user) return fail('未登录', BizCode.UNAUTHORIZED, null);
+    const result = await this.notificationService.getMessagesByPage(user.id, {
+      page,
+      pageSize,
+      msgType,
+      isRead: isRead === undefined ? undefined : isRead === 'true',
+    });
+    return pageSuccess(result.list, result.pagination);
+  }
+
+  /**
+   * 未读消息数（顶栏红点轮询）
+   */
+  @Get('unread-count')
+  public async getUnreadCount(@Request() req: any): Promise<ApiResponse<{ count: number } | null>> {
+    const user = req?.state?.user;
+    if (!user) return fail('未登录', BizCode.UNAUTHORIZED, null);
+    const count = await this.notificationService.getUnreadCount(user.id);
+    return success({ count });
+  }
+
+  /**
+   * 标记单条消息已读（仅限本人消息）
+   */
+  @Patch('{id}/read')
+  public async markRead(@Request() req: any, @Path() id: string): Promise<ApiResponse<boolean | null>> {
+    const user = req?.state?.user;
+    if (!user) return fail('未登录', BizCode.UNAUTHORIZED, null);
+    const updated = await this.notificationService.markRead(user.id, id);
+    return success(updated, updated ? '已标记已读' : '消息不存在或已读');
+  }
+
+  /**
+   * 全部标记已读（仅限本人消息）
+   */
+  @Patch('read-all')
+  public async markAllRead(@Request() req: any): Promise<ApiResponse<{ count: number } | null>> {
+    const user = req?.state?.user;
+    if (!user) return fail('未登录', BizCode.UNAUTHORIZED, null);
+    const count = await this.notificationService.markAllRead(user.id);
+    return success({ count }, '已全部标记已读');
+  }
+
+  /**
+   * 外部通知测试推送接收人列表（仅管理员）：当前渠道信息 + 启用用户 + 送达状态
+   */
+  @Get('receivers')
+  public async listReceivers(
+    @Request() req: any,
+    @Query() keyword?: string,
+  ): Promise<
+    | ApiResponse<
+        | {
+            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;
+            }[];
+          }
+        | null
+      >
+    | null
+  > {
+    const user = req?.state?.user;
+    if (!user) return fail('未登录', BizCode.UNAUTHORIZED, null);
+    if (!user.roles?.includes('admin')) return fail('仅管理员可操作', BizCode.FORBIDDEN, null);
+    const list = await this.notificationService.listReceivers(keyword);
+    return success(list, '查询成功');
+  }
+
+  /**
+   * 外部通知测试发送（仅管理员）：按当前 EXTERNAL_NOTIFY_CHANNEL 渠道发送，返回逐人发送结果
+   * @param body receiverUserIds 接收人用户 ID（必填）；title 标题（可选，默认"消息推送测试"）；content 发送内容（必填）
+   */
+  @Post('test-send')
+  public async testSend(
+    @Request() req: any,
+    @Body() body: { receiverUserIds: string[]; title?: string; content: string },
+  ): Promise<ApiResponse<TestSendResult | null>> {
+    const user = req?.state?.user;
+    if (!user) return fail('未登录', BizCode.UNAUTHORIZED, null);
+    if (!user.roles?.includes('admin')) return fail('仅管理员可操作', BizCode.FORBIDDEN, null);
+    try {
+      const result = await this.notificationService.testSend(body);
+      return success(result, '发送成功');
+    } catch (e) {
+      return fail((e as Error).message, BizCode.FAIL, null);
+    }
+  }
+
+  /**
+   * APP 推送测试接收人列表（仅管理员，独立链路）：APP 推送启用状态 + 用户列表 + 是否已上报设备 cid
+   */
+  @Get('app/receivers')
+  public async listAppReceivers(
+    @Request() req: any,
+    @Query() keyword?: string,
+  ): Promise<
+    | ApiResponse<
+        | {
+            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;
+            }[];
+          }
+        | null
+      >
+    | null
+  > {
+    const user = req?.state?.user;
+    if (!user) return fail('未登录', BizCode.UNAUTHORIZED, null);
+    if (!user.roles?.includes('admin')) return fail('仅管理员可操作', BizCode.FORBIDDEN, null);
+    const list = await this.notificationService.appListReceivers(keyword);
+    return success(list, '查询成功');
+  }
+
+  /**
+   * APP 推送测试发送（仅管理员，独立链路）：按 APP_PUSH_ENABLED 开关推送，返回逐人发送结果
+   * 只有登录过 App 并上报过 cid 的用户可送达
+   * @param body receiverUserIds 接收人用户 ID（必填）；title 标题（可选，默认"APP 推送测试"）；content 发送内容（必填）
+   */
+  @Post('app/test-send')
+  public async appTestSend(
+    @Request() req: any,
+    @Body() body: { receiverUserIds: string[]; title?: string; content: string },
+  ): Promise<ApiResponse<TestSendResult | null>> {
+    const user = req?.state?.user;
+    if (!user) return fail('未登录', BizCode.UNAUTHORIZED, null);
+    if (!user.roles?.includes('admin')) return fail('仅管理员可操作', BizCode.FORBIDDEN, null);
+    try {
+      const result = await this.notificationService.appTestSend(body);
+      return success(result, '发送成功');
+    } catch (e) {
+      return fail((e as Error).message, BizCode.FAIL, null);
+    }
+  }
+}

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

@@ -0,0 +1,22 @@
+// 消息通知类型定义（V5.4）
+import { JumpSpec } from './templates';
+
+/** 站内信消息（sys_messages） */
+export interface SysMessageInfo {
+  id: string;
+  msgType: 'TODO' | 'PROGRESS' | 'WARNING';
+  title: string;
+  content: string;
+  templateCode: string;
+  receiverUserId: string;
+  receiverRoleCode?: string | null;
+  operatorId?: string | null;
+  isRead: boolean;
+  readTime?: string | null;
+  bizType: string;
+  bizId?: string | null;
+  bizId2?: string | null;
+  createdAt: string;
+  /** 前端跳转参数（extraData.jump 扁平化） */
+  jump?: JumpSpec | null;
+}