/**
 * 渠道发送者接口定义
 *
 * 所有渠道（SMS/微信/邮件/站内）均实现 NotificationChannelSender 接口，
 * 由 dispatcher 统一调度。新增渠道只需实现此接口并注册到 dispatcher。
 */

import type { NotificationPayload, ChannelSendResult, NotificationChannel } from "../types"

/** 渠道接收人信息（由 data-access.getUserContactInfo 填充） */
export interface ChannelRecipient {
  userId: string
  /** 手机号（SMS 渠道必需） */
  phone?: string
  /** 邮箱（邮件渠道必需） */
  email?: string
  /** 微信 OpenID（微信公众号模板消息渠道必需） */
  wechatOpenId?: string
}

/**
 * 通知渠道发送者接口
 *
 * 实现方需保证：
 * - send 失败时抛出 Error 或返回 success:false（不抛出以避免阻塞其他渠道）
 * - sendBatch 内部并行发送，单条失败不影响其他条
 * - 所有实现需在文件首行 import "server-only"
 */
export interface NotificationChannelSender {
  /** 渠道标识 */
  readonly channel: NotificationChannel
  /** 发送单条通知 */
  send(payload: NotificationPayload, recipient: ChannelRecipient): Promise<ChannelSendResult>
  /** 批量发送（默认实现串行调用 send，可覆写为并行） */
  sendBatch(
    payloads: Array<{ payload: NotificationPayload; recipient: ChannelRecipient }>
  ): Promise<ChannelSendResult[]>
}
