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

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.activity.vo.*;
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.activity.WxCpActivityDO;
import cn.iocoder.yudao.module.wxcp.dal.dataobject.activity.WxCpActivitySignupDO;
import jakarta.validation.Valid;

import java.util.List;

/**
 * 企业微信活动 Service 接口
 *
 * @author 超级管理员
 */
public interface WxCpActivityService {

    // ==================== 活动管理 ====================

    /**
     * 创建活动（初始为草稿状态）
     *
     * @param createReqVO 创建信息
     * @return 活动编号
     */
    Long createActivity(@Valid WxCpActivitySaveReqVO createReqVO);

    /**
     * 修改活动
     *
     * @param updateReqVO 修改信息
     */
    void updateActivity(@Valid WxCpActivitySaveReqVO updateReqVO);

    /**
     * 删除活动
     *
     * @param id 活动编号
     */
    void deleteActivity(Long id);

    /**
     * 获得活动
     *
     * @param id 活动编号
     * @return 活动
     */
    WxCpActivityDO getActivity(Long id);

    /**
     * 获得活动分页
     *
     * @param pageReqVO 分页查询
     * @return 活动分页
     */
    PageResult<WxCpActivityDO> getActivityPage(@Valid WxCpActivityPageReqVO pageReqVO);

    /**
     * 获得活动封面附件列表（最多 1 张）
     *
     * @param activityId 活动编号
     * @return 附件（含访问地址）
     */
    List<SystemStorageBlobRespVO> getActivityAttachments(Long activityId);

    /**
     * 发布活动（草稿 -&gt; 已发布）
     *
     * @param id 活动编号
     */
    void publishActivity(Long id);

    /**
     * 结束活动
     *
     * @param id 活动编号
     */
    void finishActivity(Long id);

    /**
     * 取消活动
     *
     * @param id 活动编号
     */
    void cancelActivity(Long id);

    // ==================== 推送 ====================

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

    /**
     * 生成活动报名二维码（PNG 字节流）
     *
     * @param id   活动编号
     * @param size 边长像素，传 0 使用默认值
     * @return PNG 字节
     */
    byte[] generateSignupQrCode(Long id, int size);

    /**
     * 拼装活动报名页地址
     *
     * @param id 活动编号
     * @return 报名页完整 URL
     */
    String buildSignupUrl(Long id);

    // ==================== 报名 ====================

    /**
     * 提交报名（免登录接口使用）
     *
     * @param reqVO 报名信息
     * @return 报名记录编号
     */
    Long createSignup(@Valid WxCpSignupPublicReqVO reqVO);

    /**
     * 取消报名
     *
     * @param id 报名记录编号
     */
    void cancelSignup(Long id);

    /**
     * 报名签到
     *
     * @param id 报名记录编号
     */
    void checkInSignup(Long id);

    /**
     * 获得报名记录
     *
     * @param id 报名记录编号
     * @return 报名记录
     */
    WxCpActivitySignupDO getSignup(Long id);

    /**
     * 获得报名记录分页
     *
     * @param pageReqVO 分页查询
     * @return 报名记录分页
     */
    PageResult<WxCpActivitySignupDO> getSignupPage(@Valid WxCpSignupPageReqVO pageReqVO);

    /**
     * 获得某条报名记录的附件列表
     *
     * @param signupId 报名记录编号
     * @return 附件（含访问地址）
     */
    List<SystemStorageBlobRespVO> getSignupAttachments(Long signupId);

    /**
     * 获得活动报名统计
     *
     * @param activityId 活动编号
     * @return 统计数据
     */
    WxCpActivityStatsRespVO getActivityStats(Long activityId);

}