package com.fs.qw.service;

import com.fs.common.exception.CustomException;
import com.fs.qw.domain.QwAcquisitionAssistant;
import com.fs.qw.dto.acquisition.AcquisitionListResponse;
import com.fs.qw.vo.AcquisitionAssistantDetailVO;

import java.util.List;

/**
 * 企微-获客链接管理Service接口
 * 
 * @author fs
 * @date 2026-03-16
 */
public interface IQwAcquisitionAssistantService 
{
    /**
     * 查询企微-获客链接管理列表
     *
     * @param qwAcquisitionAssistant 企微-获客链接管理
     * @return 企微-获客链接管理集合
     */
    public List<QwAcquisitionAssistant> selectQwAcquisitionAssistantList(QwAcquisitionAssistant qwAcquisitionAssistant);

    /**
     * 从企微同步获客链接列表（全量拉取所有详情）
     * @param corpid 企业ID
     * @param corpsecret 应用密钥
     * @return 同步结果统计
     */
    public String syncListFromQw(String corpid, String corpsecret);

    /**
     * 获取企微原始列表（分页）
     * @param corpid 企业ID
     * @param corpsecret 应用密钥
     * @param limit 每页数量（最大100）
     * @param cursor 分页游标
     * @return 企微返回的列表数据
     */
    public AcquisitionListResponse getQwList(String corpid, String corpsecret, Integer limit, String cursor);

    /**
     * 获取获客链接详情（从企微实时查询）
     * @param linkId 获客链接ID
     * @return 企微返回的详情数据
     * @throws CustomException 当调用企微API失败时抛出
     */
    public AcquisitionAssistantDetailVO getDetailWithQw(String linkId);

    /**
     * 根据linkId同步单个获客链接详情到本地
     * @param corpid 企业ID
     * @param corpsecret 应用密钥
     * @param linkId 获客链接ID
     */
    public void syncDetailToLocal(String corpid, String corpsecret, String linkId);

    /**
     * 创建获客链接
     *
     * @param corpid 企业ID
     * @param corpsecret 应用密钥
     * @param assistant 获客链接信息
     * @return 创建成功的完整对象（包含企微返回的link_id、url等）
     */
    public QwAcquisitionAssistant createWithQw(String corpid,String corpsecret,QwAcquisitionAssistant assistant);

    /**
     * 修改企微-获客链接管理
     *
     * @param qwAcquisitionAssistant 企微-获客链接管理
     * @return 结果
     */
    public QwAcquisitionAssistant updateWithQw(String corpId, String secret, QwAcquisitionAssistant qwAcquisitionAssistant);

    /**
     * 删除获客链接
     * @param corpid 企业ID
     * @param corpsecret 应用密钥
     * @param assistant 获客链接信息（必须包含linkId）
     * @throws CustomException 当调用企微API失败时抛出
     */
    public void deleteWithQw(String corpid, String corpsecret, QwAcquisitionAssistant assistant);

    /**
     * 查询企微-获客链接管理
     *
     * @param id 企微-获客链接管理主键
     * @return 企微-获客链接管理
     */
    public QwAcquisitionAssistant selectQwAcquisitionAssistantById(Long id);

    /**
     * 根据页面参数查询获客链接url
     * */
    public String selectQwAcquisitionUrlByPageParam(String pageParam);

}