<?php

namespace app\common\library\live\message;

/**
 * 直播消息服务商统一接口
 * 所有消息服务商（奥点云、阿里云等）均需实现该接口
 */
interface ProviderInterface
{
    /**
     * 发送消息到群组
     * @param string $groupId 群组ID（奥点云为 topic，阿里云为 GroupId）
     * @param string $body 消息体（JSON 字符串）
     * @param int $msgType 消息类型（阿里云自定义类型需 > 10000，text=10001,image=10002,gift=10003）
     * @param string $senderId 发送者ID（阿里云必填，奥点云忽略）
     * @param string $senderMeta 发送者扩展信息（阿里云可选）
     * @param string $msgTid 消息唯一标识（用于撤回，空则由服务商生成）
     * @return Result
     */
    public function send($groupId, $body, $msgType = 10001, $senderId = '', $senderMeta = '', $msgTid = '');

    /**
     * 撤回/删除消息
     * @param string $groupId 群组ID
     * @param string $msgTid 消息唯一标识（奥点云为 uuid，阿里云为 MsgTid）
     * @return Result
     */
    public function del($groupId, $msgTid);

    /**
     * 获取群组在线用户
     * @param string $groupId 群组ID
     * @param int $pageSize 每页数量
     * @param int $nextPageToken 下一页起始位置（奥点云作为 skip 偏移量使用）
     * @return Result data 包含 total、list、next_page_token、has_more
     */
    public function getOnlineUser($groupId, $pageSize = 50, $nextPageToken = 0);

    /**
     * 获取客户端登录鉴权信息（仅阿里云需要，奥点云返回空数据）
     * @param string $userId 用户ID
     * @param string $role 角色（admin 或空字符串）
     * @return Result data 包含 app_id、app_sign、auth、app_token
     */
    public function getLoginAuth($userId, $role = '');

    /**
     * 创建群组（仅阿里云需要，奥点云直接返回成功）
     * @param string $groupId 群组ID
     * @param string $groupName 群组名称
     * @param string $groupMeta 群组扩展信息
     * @return Result
     */
    public function createGroup($groupId, $groupName = '', $groupMeta = '');

    /**
     * 删除群组
     * 群组删除后不再可用，在线用户会被通知群已结束
     * @param string $groupId 群组ID
     * @param string $operatorId 操作者ID（可选）
     * @return Result
     */
    public function deleteGroup($groupId, $operatorId = '');
}