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

import cn.iocoder.yudao.module.wxcp.controller.admin.vo.WxCpPushResultVO;

/**
 * 企业微信消息推送 Service 接口
 *
 * 抽出来供活动、通知等业务复用，避免各处重复拼装接收者与错误处理
 *
 * @author 超级管理员
 */
public interface WxCpMessagePushService {

    /**
     * 推送文本卡片消息
     *
     * @param title       卡片标题
     * @param description 卡片正文
     * @param url         点击按钮跳转地址，textcard 类型必填
     * @param btnTxt      按钮文案
     * @param scope       推送范围，见 {@link cn.iocoder.yudao.module.wxcp.enums.activity.WxCpPushScopeEnum}
     * @param target      推送目标；范围是全员时可传空
     * @return 推送结果（不抛异常，失败信息通过返回值给出）
     */
    WxCpPushResultVO pushCard(String title, String description, String url,
                             String btnTxt, Integer scope, String target);

    /**
     * 推送纯文本消息
     *
     * @param content 文本内容
     * @param scope   推送范围
     * @param target  推送目标
     * @return 推送结果
     */
    WxCpPushResultVO pushText(String content, Integer scope, String target);

    /**
     * 推送图文消息（news）
     *
     * @param title       标题
     * @param description 摘要
     * @param url         点击跳转地址
     * @param picUrl      封面图地址（选填）
     * @param scope       推送范围
     * @param target      推送目标
     * @return 推送结果
     */
    WxCpPushResultVO pushNews(String title, String description, String url, String picUrl,
                              Integer scope, String target);

    /**
     * 推送文件消息：先把文件上传到企业微信换取 mediaId，再发送文件
     *
     * @param file        文件
     * @param fileName    文件名（仅用于日志）
     * @param textContent 文件前的说明文本，可为空
     * @param scope       推送范围
     * @param target      推送目标
     * @return 推送结果
     */
    WxCpPushResultVO pushFile(java.io.File file, String fileName, String textContent,
                              Integer scope, String target);

    /**
     * 推送图片消息：先把图片上传到企业微信换取 mediaId，再发送图片
     *
     * @param file   图片文件
     * @param scope  推送范围
     * @param target 推送目标
     * @return 推送结果
     */
    WxCpPushResultVO pushImage(java.io.File file, Integer scope, String target);

}