// 文件路径：src/main/java/com/fs/wxcid/service/FriendService.java

package com.fs.wxcid.service;

import com.fs.wxcid.dto.common.BaseResponse;
import com.fs.wxcid.dto.friend.*;
import com.fs.wxcid.vo.AddContactVo;

import java.util.List;

/**
 * 好友管理服务接口
 * <p>
 * 本接口封装了微信私有协议中 /friend 路径下的所有好友相关操作，
 * 包括：添加/同意好友、删除好友、查询联系人、搜索、上传通讯录等。
 * 所有方法均需传入账号唯一标识 authKey，并返回统一格式的 ApiResponse。
 * </p>
 */
public interface FriendService {

    /**
     * 批量获取联系人详细信息
     * <p>
     * 对应接口：POST /friend/GetContactDetailsList
     * 可同时查询多个用户或群聊的详细资料。
     * </p>
     * @return 统一响应结果
     */
    GetContactDetailsResponseData getContactDetailsList(GetContactDetailsListParam param);
    /**
     * 搜索联系人
     * <p>
     * 对应接口：POST /friend/SearchContact
     * 支持按昵称、微信号、手机号等模糊搜索。
     * </p>
     *
     * @return 统一响应结果
     */
    SearchContactResponse searchContact(SearchContactParam param);

    /**
     * 发起好友验证或添加请求
     * <p>
     * 对应接口：POST /friend/VerifyUser
     * 用于主动添加他人，需提供对方的 V3/V4（通常来自扫码或推荐）。
     * 若无 V3/V4，部分场景可能无法添加。
     * </p>
     *
     * @return 统一响应结果
     */
    BaseResponse verifyUser(VerifyUserParam param);
    ContactListResponse getContactListNotKey(GetContactListParam param);

    /**
     * 添加联系人
     */
    AddContactVo addContact(AddContactParam param);
}