/*
 * Copyright (c) 2018-2999 广州市蓝海创新科技有限公司 All rights reserved.
 *
 * https://www.mall4j.com/
 *
 * 未经允许，不可做商业用途！
 *
 * 版权所有，侵权必究！
 */

package com.yami.shop.dao;

import com.baomidou.mybatisplus.core.mapper.BaseMapper;
import com.yami.shop.bean.app.dto.ShopCartItemDto;
import com.yami.shop.bean.app.param.ShopCartParam;
import com.yami.shop.bean.model.Basket;
import org.apache.ibatis.annotations.Param;

import java.util.List;
import java.util.Map;

/**
 * BasketMapper接口，继承自BaseMapper<Basket>，用于对购物车相关的数据持久化操作（与数据库交互）。
 * 例如查询、删除、更新购物车相关的记录等操作都在此接口中定义方法，由对应的实现类去具体实现这些方法与数据库的交互逻辑。
 *
 * @author lanhai
 */
public interface BasketMapper extends BaseMapper<Basket> {

    /**
     * 获取购物项的方法。
     * 通过传入的用户id，从数据库中查询出该用户对应的购物项列表信息。
     * 一般用于展示用户购物车中具体的商品项等情况。
     *
     * @param userId 用户id，用于唯一标识用户，通过该用户id来筛选出属于该用户的购物项
     * @return 返回包含购物项信息的列表，列表中的每个元素为ShopCartItemDto类型，封装了购物项的详细信息（如商品详情、数量等）
     */
    List<ShopCartItemDto> getShopCartItems(@Param("userId") String userId);

    /**
     * 根据购物车id列表和用户id删除购物车的方法。
     * 用于批量删除指定用户的购物车中对应的某些购物车记录，通过传入的购物车id列表来确定具体要删除哪些购物车记录。
     *
     * @param userId 用户id，明确是哪个用户的购物车记录要进行删除操作
     * @param basketIds 购物车id列表，是一个Long类型的列表，里面存放的每个id对应着要删除的购物车记录在数据库中的唯一标识
     */
    void deleteShopCartItemsByBasketIds(@Param("userId") String userId, @Param("basketIds") List<Long> basketIds);

    /**
     * 删除所有购物车的方法。
     * 此方法会将指定用户的所有购物车记录从数据库中全部删除，一般用于清空用户整个购物车的场景，比如用户手动选择清空购物车操作后调用此方法。
     *
     * @param userId 用户id，用于指定要清空购物车记录的用户
     */
    void deleteAllShopCartItems(@Param("userId") String userId);

    /**
     * 获取失效的购物项的方法。
     * 根据传入的用户id，从数据库中查询出该用户购物车中那些已经失效的购物项信息，比如商品下架、库存为0等原因导致的购物项失效情况。
     *
     * @param userId 用户id，用于筛选出属于该用户的失效购物项
     * @return 返回包含失效购物项信息的列表，列表中的每个元素为ShopCartItemDto类型，里面封装了失效购物项的相关详情（如商品信息等）
     */
    List<ShopCartItemDto> getShopCartExpiryItems(@Param("userId") String userId);

    /**
     * 删除失效的购物项的方法。
     * 用于将指定用户购物车中已失效的购物项从数据库中删除，以保证购物车数据的有效性和准确性，避免无效数据的堆积。
     *
     * @param userId 用户id，明确是哪个用户的失效购物项要进行删除操作
     */
    void cleanExpiryProdList(@Param("userId") String userId);

    /**
     * 更新购物车满减活动id的方法。
     * 通过传入的用户id以及购物项map，来更新购物车中各购物项对应的满减活动id，以反映最新的满减活动关联情况，确保购物车中商品价格等相关计算准确。
     *
     * @param userId 用户id，用于确定是哪个用户的购物车满减活动id要进行更新操作
     * @param basketIdShopCartParamMap 购物项map，是一个以购物车id（Long类型）为键，ShopCartParam类型为值的Map，ShopCartParam中封装了购物项的相关参数以及满减活动相关信息等，用于更新对应的购物车记录的满减活动id
     */
    void updateDiscountItemId(@Param("userId") String userId, @Param("basketIdShopCartParamMap") Map<Long, ShopCartParam> basketIdShopCartParamMap);

    /**
     * 根据商品id获取用户id列表的方法。
     * 基于传入的商品id，从数据库中查询出购买过该商品的所有用户的id信息，可用于统计商品的购买用户情况等相关业务场景。
     *
     * @param prodId 商品id，用于作为查询条件，筛选出购买过该商品的用户id
     * @return 返回一个包含用户id的列表，列表中的元素为String类型，每个元素代表一个购买过该商品的用户的唯一标识
     */
    List<String> listUserIdByProdId(@Param("prodId") Long prodId);

}