package cn.iocoder.yudao.module.wxcp.service.notice;

import cn.iocoder.yudao.framework.common.pojo.PageResult;
import cn.iocoder.yudao.module.system.controller.admin.storage.vo.SystemStorageBlobRespVO;
import cn.iocoder.yudao.module.wxcp.controller.admin.notice.vo.WxCpNoticePageReqVO;
import cn.iocoder.yudao.module.wxcp.controller.admin.notice.vo.WxCpNoticeSaveReqVO;
import cn.iocoder.yudao.module.wxcp.controller.admin.vo.WxCpPushReqVO;
import cn.iocoder.yudao.module.wxcp.controller.admin.vo.WxCpPushResultVO;
import cn.iocoder.yudao.module.wxcp.dal.dataobject.notice.WxCpNoticeArticleDO;
import cn.iocoder.yudao.module.wxcp.dal.dataobject.notice.WxCpNoticeDO;
import jakarta.validation.Valid;

import java.util.List;

/**
 * 企业微信通知 Service 接口
 *
 * @author 超级管理员
 */
public interface WxCpNoticeService {

    /**
     * 创建通知（初始为草稿状态）
     *
     * @param createReqVO 创建信息
     * @return 通知编号
     */
    Long createNotice(@Valid WxCpNoticeSaveReqVO createReqVO);

    /**
     * 修改通知
     *
     * @param updateReqVO 修改信息
     */
    void updateNotice(@Valid WxCpNoticeSaveReqVO updateReqVO);

    /**
     * 删除通知
     *
     * @param id 通知编号
     */
    void deleteNotice(Long id);

    /**
     * 获得通知
     *
     * @param id 通知编号
     * @return 通知
     */
    WxCpNoticeDO getNotice(Long id);

    /**
     * 获得通知分页
     *
     * @param pageReqVO 分页查询
     * @return 通知分页
     */
    PageResult<WxCpNoticeDO> getNoticePage(@Valid WxCpNoticePageReqVO pageReqVO);

    /**
     * 获得图片通知的图片列表
     *
     * @param noticeId 通知编号
     * @return 图片列表（含预览地址）
     */
    List<SystemStorageBlobRespVO> getNoticeImageAttachments(Long noticeId);

    /**
     * 获得附件通知的附件列表
     *
     * @param noticeId 通知编号
     * @return 附件列表（含预览/下载地址）
     */
    List<SystemStorageBlobRespVO> getNoticeFileAttachments(Long noticeId);

    /**
     * 获得视频通知的视频列表
     *
     * @param noticeId 通知编号
     * @return 视频列表（含预览地址）
     */
    List<SystemStorageBlobRespVO> getNoticeVideoAttachments(Long noticeId);

    /**
     * 获得多图文消息的图文列表
     *
     * @param noticeId 通知编号
     * @return 图文列表
     */
    List<WxCpNoticeArticleDO> getNoticeArticles(Long noticeId);

    /**
     * 获得多图文条目的封面附件
     *
     * @param articleId 图文条目编号
     * @return 封面附件列表（最多 1 张）
     */
    List<SystemStorageBlobRespVO> getNoticeArticleCoverAttachments(Long articleId);

    /**
     * 发布通知（草稿 -&gt; 已发布）
     *
     * @param id 通知编号
     */
    void publishNotice(Long id);

    /**
     * 撤回通知
     *
     * @param id 通知编号
     */
    void revokeNotice(Long id);

    /**
     * 推送通知给企业微信成员
     *
     * @param pushReqVO 推送信息
     * @return 推送结果
     */
    WxCpPushResultVO pushNotice(@Valid WxCpPushReqVO pushReqVO);

    /**
     * 拼装通知预览页地址，成员在企业微信内打开后可查看图片与附件
     *
     * @param id 通知编号
     * @return 预览页地址；未配置外网地址前缀时返回 null
     */
    String buildPreviewUrl(Long id);

}