package cn.iocoder.yudao.module.im.service.rtc;

import cn.iocoder.yudao.framework.common.pojo.PageResult;
import cn.iocoder.yudao.module.im.controller.admin.manager.rtc.vo.ImRtcCallManagerPageReqVO;
import cn.iocoder.yudao.module.im.controller.admin.rtc.vo.ImRtcCallCreateReqVO;
import cn.iocoder.yudao.module.im.controller.admin.rtc.vo.ImRtcCallInviteReqVO;
import cn.iocoder.yudao.module.im.dal.dataobject.rtc.ImRtcCallDO;
import cn.iocoder.yudao.module.im.dal.dataobject.rtc.ImRtcParticipantDO;

import java.util.List;

/**
 * IM 实时通话 Service
 *
 * @author 芋道源码
 */
public interface ImRtcCallService {

    /**
     * 创建新通话；同好友对 / 同群已有进行中通话直接抛错（群场景应改走 {@link #inviteCall} 追加邀请，或 {@link #joinCall} 加入旁观）
     *
     * @param userId 发起人编号；通常是当前登录用户
     * @param reqVO  请求参数（scene / mediaType / peerUserId 或 groupId + inviteeIds）
     * @return 通话主表
     */
    ImRtcCallDO createCall(Long userId, ImRtcCallCreateReqVO reqVO);

    /**
     * 通话中追加邀请：仅群通话场景可用；本人必须是房内 JOINED 参与者；给新邀请人推 RTC_CALL(INVITE)
     *
     * @param userId 操作人编号；必须是当前会话参与者
     * @param reqVO  room + 新邀请的用户编号集合
     */
    void inviteCall(Long userId, ImRtcCallInviteReqVO reqVO);

    /**
     * 加入已有群通话：用于群胶囊条「加入」按钮；旁观者作为 JOINER 加入，邀请池内成员转 JOINED
     *
     * @param userId 加入者用户编号
     * @param room   业务通话编号；从胶囊条 activeCall 拿
     * @return 通话主表
     */
    ImRtcCallDO joinCall(Long userId, String room);

    /**
     * 接听通话：参与者 INVITING → JOINED；主表 CREATED → RUNNING（首次有非发起人接通时）
     *
     * @param userId 接听者用户编号
     * @param room   业务通话编号
     * @return 通话主表
     */
    ImRtcCallDO acceptCall(Long userId, String room);

    /**
     * 拒绝通话；仅 INVITING 状态可拒；群通话拒绝等同于不参与，房间仍存在
     *
     * @param userId 拒接者用户编号
     * @param room   业务通话编号
     */
    void rejectCall(Long userId, String room);

    /**
     * 取消邀请；主叫在 INVITING 状态主动取消
     *
     * @param userId 取消者用户编号（必须是主叫）
     * @param room   业务通话编号
     */
    void cancelCall(Long userId, String room);

    /**
     * 离开通话；RUNNING 状态下离开；私聊任一方离开 = 通话结束；群通话最后一人离开才结束
     *
     * @param userId 离开者用户编号
     * @param room   业务通话编号
     */
    void leaveCall(Long userId, String room);

    /**
     * 查询当前正在进行的通话；目前仅群聊场景（胶囊条），私聊未来扩展再补 peerUserId 参数
     * <p>
     * 鉴权：仅群活跃成员可查；防止任意用户探测群通话状态 / 拿到 inviter / inviteeIds 等敏感信息
     *
     * @param userId  操作人编号；通常是当前登录用户
     * @param groupId 群编号
     * @return 通话主表；不存在返回 null
     */
    ImRtcCallDO getActiveCall(Long userId, Long groupId);

    /**
     * 查询某通话的全部参与者明细；交给 Controller 拼装 inviteeIds / joinedUserIds
     *
     * @param room 业务通话编号
     * @return 参与者明细列表
     */
    List<ImRtcParticipantDO> getCallParticipantList(String room);

    /**
     * 签发指定用户进入该通话的 LiveKit Token；供 Controller 拼接到响应 VO
     *
     * @param userId 进房用户编号；token 内 displayName 取该用户昵称
     * @param room   业务通话编号
     * @return JWT 字符串
     */
    String signCallToken(Long userId, String room);

    /**
     * 处理 LiveKit Webhook 事件；用于关 tab / 强杀 / 网络断开等异常退出场景的兜底清理
     * <p>
     * 关键事件：participant_left（成员离开） / room_finished（房间结束）。
     * 前端正常 leave 时，也会触发同样的 LiveKit 事件；此处需做幂等处理，session 已被业务接口移除时直接忽略。
     *
     * @param event LiveKit Webhook 事件
     */
    void handleLiveKitEvent(cn.iocoder.yudao.module.im.framework.rtc.core.LiveKitWebhookEventDTO event);

    /**
     * 【定时任务调用】清理僵尸通话
     *
     * @param thresholdMinutes 通话创建超过此分钟数才纳入扫描；调用方保证 > 0
     * @return 清理数量
     */
    int cleanupZombieCalls(int thresholdMinutes);

    /**
     * 【定时任务调用】超时未接通的 INVITING 参与者：单人粒度标 NO_ANSWER + 推 RTC_CALL(NO_ANSWER) 让前端 banner 收敛；
     * 若导致通话只剩主叫，由 endSessionIfTerminal 级联关房
     *
     * @param thresholdMinutes 邀请时间超过此分钟数才纳入扫描；调用方保证 > 0
     * @return 超时处理数量
     */
    int timeoutInvitingParticipants(int thresholdMinutes);

    /**
     * 前端 RUNNING 端 timer 兜底；立即扫描指定 room 内超时的 INVITING 参与者，等同 Job 但限定单 room；
     * 实际超时阈值由后端 {@link cn.iocoder.yudao.module.im.framework.config.ImProperties.Rtc#getInviteTimeoutMinutes()} 决定，
     * 避免前后端配置不一致；接口静默，所有边界（room 不存在 / 鉴权失败 / 无超时候选）都返回 false 不抛异常
     *
     * @param userId 调用者用户编号；必须是该 room 的参与者
     * @param room   业务通话编号
     */
    void noAnswerCallCheck(Long userId, String room);

    // ==================== 管理后台 ====================

    /**
     * 【管理后台】获得通话记录分页
     *
     * @param reqVO 分页查询条件
     * @return 通话记录分页
     */
    PageResult<ImRtcCallDO> getCallPage(ImRtcCallManagerPageReqVO reqVO);

    /**
     * 【管理后台】获得通话记录
     *
     * @param id 通话编号
     * @return 通话记录
     */
    ImRtcCallDO getCall(Long id);

    /**
     * 【管理后台】按通话编号查询参与者明细
     *
     * @param id 通话编号
     * @return 参与者明细列表；通话不存在时返回空集合
     */
    List<ImRtcParticipantDO> getCallParticipantListByCallId(Long id);

}