import type { NotificationChannel } from "../notifications/notifications.schema.js";

/**
 * 渠道策略接口（策略模式）。
 *
 * 每个渠道实现此接口，ChannelDispatcher 根据 NotificationPreference
 * 配置 fan-out 到启用的渠道。
 *
 * 仲裁依据 02-architecture-design.md §2.4：
 * - in_app 总是发送（保证站内信可见）
 * - 其他渠道按偏好配置启用/禁用
 * - 所有渠道软失败：投递失败不阻断主流程，记录 delivery 状态
 */

/** 渠道发送上下文（由 NotificationService 构造） */
export interface ChannelSendContext {
  /** 通知 ID（已写入 DB 的） */
  notificationId: string;
  /** 接收者用户 ID */
  userId: string;
  /** 通知标题 */
  title: string;
  /** 通知内容 */
  content: string;
  /** 通知类型 */
  type: string;
  /** 元数据 */
  metadata: Record<string, string> | null;
  /** 关联实体类型 */
  relatedEntityType?: string | null;
  /** 关联实体 ID */
  relatedEntityId?: string | null;
}

/** 渠道发送结果 */
export interface ChannelSendResult {
  /** 渠道名称 */
  channel: NotificationChannel;
  /** 是否发送成功 */
  sent: boolean;
  /** 外部网关返回的 ID（如有） */
  externalId?: string;
  /** 失败原因 */
  error?: string;
}

/** 渠道策略接口 */
export interface NotificationChannelStrategy {
  /** 渠道名称 */
  readonly name: NotificationChannel;
  /** 发送通知 */
  send(ctx: ChannelSendContext): Promise<ChannelSendResult>;
}
