package org.xyzh.api.workcase.service;

import org.xyzh.api.workcase.dto.TbVideoMeetingDTO;
import org.xyzh.api.workcase.vo.VideoMeetingVO;
import org.xyzh.common.core.domain.ResultDomain;

/**
 * @description    视频会议服务接口，管理Jitsi Meet视频会议
 * @filename    VideoMeetingService.java
 * @author    claude
 * @copyright xyzh
 * @since 2025-12-25
 */
public interface VideoMeetingService {

    /**
     * @description    创建视频会议
     * @param meetingDTO 会议信息
     * @param userId 创建者用户ID
     * @return ResultDomain<VideoMeetingVO>
     * @author    claude
     * @since 2025-12-25
     */
    ResultDomain<VideoMeetingVO> createMeeting(TbVideoMeetingDTO meetingDTO);

    /**
     * @description    获取会议信息
     * @param meetingId 会议ID
     * @param userId 请求用户ID（用于权限验证）
     * @return ResultDomain<VideoMeetingVO>
     * @author    claude
     * @since 2025-12-25
     */
    ResultDomain<VideoMeetingVO> getMeetingInfo(String meetingId, String userId);

    /**
     * @description    验证用户是否有权访问会议
     * @param meetingId 会议ID
     * @param userId 用户ID
     * @return ResultDomain<Boolean>
     * @author    claude
     * @since 2025-12-25
     */
    ResultDomain<Boolean> validateMeetingAccess(String meetingId, String userId);

    /**
     * @description    生成用户专属的会议访问URL（包含用户专属JWT Token）
     * @param meetingId 会议ID
     * @param userId 用户ID
     * @return ResultDomain<VideoMeetingVO>
     * @author    claude
     * @since 2025-12-25
     */
    ResultDomain<VideoMeetingVO> generateUserMeetingUrl(String meetingId, String userId);

    /**
     * @description    开始会议（更新状态为ongoing）
     * @param meetingId 会议ID
     * @return ResultDomain<Boolean>
     * @author    claude
     * @since 2025-12-25
     */
    ResultDomain<Boolean> startMeeting(String meetingId);

    /**
     * @description    结束会议（更新状态为ended）
     * @param meetingId 会议ID
     * @return ResultDomain<VideoMeetingVO>
     * @author    claude
     * @since 2025-12-25
     */
    ResultDomain<VideoMeetingVO> endMeeting(String meetingId);

    /**
     * @description    获取聊天室当前活跃的会议
     * @param roomId 聊天室ID
     * @return ResultDomain<VideoMeetingVO>
     * @author    claude
     * @since 2025-12-25
     */
    ResultDomain<VideoMeetingVO> getActiveMeetingByRoom(String roomId);

    /**
     * @description    检查用户是否为聊天室成员（内部方法）
     * @param roomId 聊天室ID
     * @param userId 用户ID
     * @return boolean
     * @author    claude
     * @since 2025-12-25
     */
    boolean isMemberOfRoom(String roomId, String userId);

    /**
     * @description    通过token获取会议入口信息（用于小程序和外部链接访问）
     *                 此接口在gateway白名单中，通过URL参数token进行认证
     * @param meetingId 会议ID
     * @param token 用户认证token
     * @return ResultDomain<VideoMeetingVO> 包含会议信息和用户专属的iframe URL
     * @author    yslg
     * @since 2025-12-27
     */
    ResultDomain<VideoMeetingVO> getMeetingEntryByToken(String meetingId, String token);

    /**
     * @description    生成会议入口URL（用于分享给小程序用户）
     * @param meetingId 会议ID
     * @param baseUrl 基础URL（如 https://example.com/workcase）
     * @return ResultDomain<String> 完整的会议入口URL（包含token参数）
     * @author    yslg
     * @since 2025-12-27
     */
    ResultDomain<String> generateMeetingEntryUrl(String meetingId, String baseUrl);
}
