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

package com.fs.wxcid.service;

import com.fs.wxcid.dto.common.ApiResponse;
import com.fs.wxcid.dto.friend.*;

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

    /**
     * 同意好友请求
     * <p>
     * 对应接口：POST /friend/AgreeAdd
     * 通常用于处理来自他人的加好友申请，需提供 V3/V4 等加密参数。
     * </p>
     *
     * @param authKey    账号唯一标识（query 参数）
     * @param request 同意请求参数（包含 V3、V4、Scene 等）
     * @return 统一响应结果
     */
    ApiResponse agreeAdd(String authKey, AgreeAddRequest request);

    /**
     * 删除好友
     * <p>
     * 对应接口：POST /friend/DelContact
     * 从联系人列表中移除指定用户。
     * </p>
     *
     * @param authKey    账号唯一标识
     * @param request 删除请求参数（含 DelUserName）
     * @return 统一响应结果
     */
    ApiResponse delContact(String authKey, DelContactRequest request);

    /**
     * 批量获取联系人详细信息
     * <p>
     * 对应接口：POST /friend/GetContactDetailsList
     * 可同时查询多个用户或群聊的详细资料。
     * </p>
     *
     * @param authKey    账号唯一标识
     * @param request 查询参数（支持 UserNames 和 RoomWxIDList）
     * @return 统一响应结果
     */
    ApiResponse getContactDetailsList(String authKey, GetContactDetailsListRequest request);

    /**
     * 分页获取全部联系人（包括好友和群聊）
     * <p>
     * 对应接口：POST /friend/GetContactList
     * 通过序列号实现分页加载，避免一次性拉取过多数据。
     * </p>
     *
     * @param authKey    账号唯一标识
     * @param request 分页参数（CurrentWxcontactSeq / CurrentChatRoomContactSeq）
     * @return 统一响应结果
     */
    ApiResponse getContactList(String authKey, GetContactListRequest request);

    /**
     * 查询与指定用户的好友关系状态
     * <p>
     * 对应接口：POST /friend/GetFriendRelation
     * 可判断是否为单向/双向好友、是否被拉黑等。
     * </p>
     *
     * @param authKey    账号唯一标识
     * @param request 目标用户名（UserName）
     * @return 统一响应结果（含关系状态码）
     */
    ApiResponse getFriendRelation(String authKey, GetFriendRelationRequest request);

    /**
     * 获取已关注的公众号列表
     * <p>
     * 对应接口：GET /friend/GetGHList
     * 返回当前账号关注的所有公众号信息。
     * </p>
     *
     * @param authKey 账号唯一标识
     * @return 统一响应结果
     */
    ApiResponse getGHList(String authKey);

    /**
     * 获取手机通讯录中匹配的微信好友
     * <p>
     * 对应接口：GET /friend/GetMFriend
     * 需提前上传通讯录（UploadMContact），否则可能返回空。
     * </p>
     *
     * @param authKey 账号唯一标识
     * @return 统一响应结果
     */
    ApiResponse getMFriend(String authKey);

    /**
     * 获取已保存的群聊列表
     * <p>
     * 对应接口：GET /friend/GroupList
     * 返回当前账号参与并保存的所有群聊。
     * </p>
     *
     * @param authKey 账号唯一标识
     * @return 统一响应结果
     */
    ApiResponse getGroupList(String authKey);

    /**
     * 搜索联系人
     * <p>
     * 对应接口：POST /friend/SearchContact
     * 支持按昵称、微信号、手机号等模糊搜索。
     * </p>
     *
     * @param authKey    账号唯一标识
     * @param request 搜索参数（UserName + 场景配置）
     * @return 统一响应结果
     */
    ApiResponse searchContact(String authKey, SearchContactRequest request);

    /**
     * 上传手机通讯录用于匹配微信好友
     * <p>
     * 对应接口：POST /friend/UploadMContact
     * 上传后可调用 GetMFriend 获取匹配结果。
     * </p>
     *
     * @param authKey    账号唯一标识
     * @param request 通讯录号码列表（MobileList）
     * @return 统一响应结果
     */
    ApiResponse uploadMContact(String authKey, UploadMContactRequest request);

    /**
     * 发起好友验证或添加请求
     * <p>
     * 对应接口：POST /friend/VerifyUser
     * 用于主动添加他人，需提供对方的 V3/V4（通常来自扫码或推荐）。
     * 若无 V3/V4，部分场景可能无法添加。
     * </p>
     *
     * @param authKey    账号唯一标识
     * @param request 添加请求参数（含 V3、V4、Scene、验证语等）
     * @return 统一响应结果
     */
    ApiResponse verifyUser(String authKey, VerifyUserRequest request);
}