<?php

namespace Kylin\Sms\Contracts;

/**
 * 短信网关接口
 * 
 * 定义所有短信网关必须实现的方法
 * 所有短信服务商网关都必须实现此接口，确保统一的调用方式
 * 
 * @package Kylin\Sms\Contracts
 */
interface GatewayInterface
{
    /**
     * 获取网关名称
     * 
     * 返回网关的标识名称，用于日志记录和错误处理
     * 
     * @return string 网关名称，如 'aliyun'、'tencent' 等
     */
    public function getName(): string;

    /**
     * 发送短信
     * 
     * 发送普通短信内容到指定手机号
     * 
     * @param string $to 接收手机号
     * @param string $content 短信内容
     * @param array $data 附加数据，可包含签名、模板参数等
     * @return array 发送结果，包含 success、gateway、data 或 error 字段
     */
    public function send(string $to, string $content, array $data = []): array;

    /**
     * 发送模板短信
     * 
     * 使用预定义模板发送短信，模板参数将被填充到模板中
     * 
     * @param string $to 接收手机号
     * @param string $templateId 模板 ID 或模板代码
     * @param array $params 模板参数，键值对形式
     * @return array 发送结果，包含 success、gateway、data 或 error 字段
     */
    public function sendTemplate(string $to, string $templateId, array $params = []): array;

    /**
     * 批量发送短信
     * 
     * 向多个手机号发送相同内容的短信
     * 
     * @param array $recipients 接收手机号数组
     * @param string $content 短信内容
     * @param array $data 附加数据，可包含签名、模板参数等
     * @return array 发送结果，包含 success、gateway、data 或 error 字段
     */
    public function sendBatch(array $recipients, string $content, array $data = []): array;

    /**
     * 设置网关配置
     * 
     * 动态更新网关的配置信息
     * 
     * @param array $config 配置数组
     * @return self 支持链式调用
     */
    public function setConfig(array $config): self;

    /**
     * 获取当前网关配置
     * 
     * 返回网关当前的配置信息
     * 
     * @return array 配置数组
     */
    public function getConfig(): array;
}
