package com.aurora.service;

import org.springframework.data.domain.Sort;// 导入 Spring Data 的排序类（Sort），用于指定查询结果的排序方向（如升序、降序）
import org.springframework.data.geo.Distance;// 导入距离类（Distance），用于表示地理空间计算中的距离结果，通常包含数值和单位
import org.springframework.data.geo.GeoResults;// 导入地理空间查询结果类（GeoResults），用于封装地理空间查询的返回结果，如附近地点列表
import org.springframework.data.geo.Point;// 导入点类（Point），用于表示地理空间中的坐标点（经度、纬度）
import org.springframework.data.redis.connection.RedisGeoCommands;// 导入 Redis 地理空间命令相关类（RedisGeoCommands），提供地理空间操作的支持（如添加地点、计算距离）

import java.util.List;// 导入 Java 集合框架中的 List 接口，用于存储有序的元素序列，常用于方法参数或返回列表结果
import java.util.Map;// 导入 Map 接口，用于存储键值对映射关系，常用于哈希结构操作
import java.util.Set;// 导入 Set 接口，用于存储不重复的元素集合，常用于集合结构操作
// 抑制编译器所有类型的警告信息，避免编译时产生警告提示，使代码更简洁
@SuppressWarnings("all")
// 定义 Redis 服务接口（RedisService），声明一系列 Redis 数据操作的方法
// 该接口封装了 Redis 的常用功能，包括字符串、哈希、列表、集合、有序集合、位操作、地理空间等数据类型的操作
public interface RedisService {
    /**
     * 保存键值对并设置过期时间（单位：秒）,该方法将键值对存储到 Redis中，并在指定时间后自动过期，常用于临时数据或缓存场景
     * @param key   键名，用于唯一标识数据
     * @param value 值，可以是任意对象类型，通常通过序列化存储
     * @param time  过期时间（秒），指定数据在 Redis 中的存活时间
     */
    void set(String key, Object value, long time);

    void set(String key, Object value);//保存键值对（除非手动删除,否则永不过期）

    Object get(String key);//根据键名获取值(Object为值对象），该方法从Redis中查询指定键对应的值，如果键不存在则返回 null

    Boolean del(String key);//删除指定键的数据,该方法从Redis中移除指定键及其关联值，删除成功返回 true，否则返回 false

    Long del(List<String> keys);//批量删除多个键的数据,该方法一次性删除多个键值对，返回实际删除的键数量

    Boolean expire(String key, long time);//设置键的过期时间,该方法为已存在的键设置生存时间，超过指定时间后键自动失效

    Long getExpire(String key);//获取键的剩余生存时间（单位：秒),该方法查询键的剩余存活时间，返回秒数；如果键不存在或永不过期，返回特定值

    Boolean hasKey(String key);//判断键是否存在,该方法检查Redis是否存在指定的键，常用于验证数据是否已缓存
    //返回自增后的新值
    Long incr(String key, long delta);//对键的值进行自增操作（整数）,该方法将键对应的整数值增加指定步长，常用于计数器、限流等场景
    //返回自增后的新值
    Long incrExpire(String key, long time);//自增并设置过期时间,该方法在自增操作的同时重置键的过期时间，确保计数器在指定时间内有效
    //返回自减后的新值
    Long decr(String key, long delta);//对键的值进行自减操作（整数）,该方法将键对应的整数值减少指定步长，常用于计数器、限流等场景
    /**
     * 获取哈希结构中指定字段的值，该方法从Redis哈希类型数据中获取特定字段的值，适用于对象属性存储
     * @param key     哈希键名    @param hashKey 哈希字段名  @return 字段值，如果字段不存在返回 null
     */
    Object hGet(String key, String hashKey);
    //向哈希结构中设置字段值并设置过期时间,该方法在哈希中设置字段值，并为整个哈希键设置统一的过期时间
    Boolean hSet(String key, String hashKey, Object value, long time);
    //向哈希结构中设置字段值（永不过期）,该方法仅设哈希字段值，不修改键的过期时间
    void hSet(String key, String hashKey, Object value);
    /**
     * 获取整个哈希结构的所有字段和值,该方法返回哈希键对应的全部字段-值映射，适用于获取完整对象数据
     * @param key 哈希键名  @return 字段-值映射表（Map 对象）
     */
    Map<String, Object> hGetAll(String key);
    //批量设置哈希结构的字段值并设置过期时间,该方法使用 Map 批量设置哈希字段，同时设置整个键的过期时间
    Boolean hSetAll(String key, Map<String, Object> map, long time);
    //批量设置哈希结构的字段值（永不过期）,该方法批量设置哈希字段，不修改键的过期时间
    void hSetAll(String key, Map<String, ?> map);
    /**
     * 删除哈希结构中的指定字段,该方法从哈希中移除一个或多个字段，不影响其他字段
     * @param key     哈希键名   @param hashKey 要删除的字段名（可变参数，可多个）
     */
    void hDel(String key, Object... hashKey);
    /**
     * 判断哈希结构中是否存在指定字段,该方法检查哈希中是否包含特定字段，用于验证字段存在性
     * @param key     哈希键名  @param hashKey 字段名  @return 是否存在（true：存在，false：不存在）
     */
    Boolean hHasKey(String key, String hashKey);
    //返回自增后的新值
    Long hIncr(String key, String hashKey, Long delta);//对哈希结构中指定字段的值进行自增操作（整数）,该方法增加哈希中某个字段的整数值，适用于对象属性的计数场景
    //返回自减后的新值
    Long hDecr(String key, String hashKey, Long delta);//对哈希结构中指定字段的值进行自减操作（整数）,该方法增加哈希中某个字段的整数值，适用于对象属性的计数场景
    //返回增加后的新分数
    Double zIncr(String key, Object value, Double score);//增加有序集合中成员的分数,该方法为有序集合中指定成员增加分数，适用于排行榜、优先级队列等场景
    //返回减少后的新分数
    Double zDecr(String key, Object value, Double score);//减少有序集合中成员的分数,该方法为有序集合中指定成员减少分数，适用于排行榜、优先级队列等场景
    //获取有序集合中指定排名范围的成员及分数（按分数从高到低）,该方法返回有序集合中从高到低排序的成员及其分数，适用于 TopN 查询
    Map<Object, Double> zReverseRangeWithScore(String key, long start, long end);
    //返回分数值，如果成员不存在返回 null
    Double zScore(String key, Object value);//获取有序集合中指定成员的分数,该方法查询特定成员在有序集合中的分数值

    Map<Object, Double> zAllScore(String key);//获取有序集合中所有成员的分数,该方法返回有序集合中全部成员的分数映射，适用于数据导出或分析

    Set<Object> sMembers(String key);//获取集合中的所有成员,该方法返回集合键对应的全部成员集合，适用于获取不重复的元素列表
    //返回实际被添加的新成员数量（重复成员不计数）
    Long sAdd(String key, Object... values);//向集合中添加一个或多个成员,该方法向集合中插入新成员，重复成员会被自动忽略
    //返回实际被添加的新成员数量
    Long sAddExpire(String key, long time, Object... values);//向集合中添加成员并设置过期时间,该方法添加成员的同时为整个集合键设置过期时间

    Boolean sIsMember(String key, Object value);//判断指定成员是否在集合中,该方法检查成员是否属于集合，用于验证元素存在性
    //返回成员数量  @param key 集合键名
    Long sSize(String key);//获取集合的成员数量,该方法返回集合中元素的总数，即集合的基数
    //返回实际被移除的成员数量
    Long sRemove(String key, Object... values);//从集合中移除一个或多个成员,该方法从集合中删除指定成员，不存在则忽略
    //返回元素列表
    List<Object> lRange(String key, long start, long end);//获取列表中指定范围的元素,该方法返回列表键中从start到end索引的元素子集（包含两端）

    Long lSize(String key);//获取列表的长度,该方法返回列表中元素的总数  @param key 列表键名
    //@return 索引处的元素值
    Object lIndex(String key, long index);//根据索引获取列表中的元素,该方法返回列表中指定索引位置的元素，支持负数索引（-1 表示最后一个）
    //@return 插入后列表的长度
    Long lPush(String key, Object value);//向列表尾部插入一个元素,该方法在列表的右端（尾部）添加新元素，适用于队列或日志追加场景
    //@return 插入后列表的长度
    Long lPush(String key, Object value, long time);//向列表尾部插入一个元素并设置过期时间,该方法插入元素的同时重置列表键的过期时间
    //@return 插入后列表的长度
    Long lPushAll(String key, Object... values);//向列表尾部批量插入多个元素,该方法一次性在列表尾部插入多个元素，元素顺序与参数顺序一致
    //@return 插入后列表的长度
    Long lPushAll(String key, Long time, Object... values);//向列表尾部批量插入多个元素并设置过期时间,该方法批量插入元素的同时设置列表键的过期时间
    //返回实际移除数量   @param count 移除数量（正数：从头部开始搜索；负数：从尾部开始搜索；0：全部移除）
    Long lRemove(String key, long count, Object value);//从列表中移除指定数量的匹配元素,该方法删除列表中前count个与value相等的元素
    /**
     * 设置位图中指定偏移量的比特值,该方法操作位图（Bitmap）数据，将指定偏移量的比特设置为 1 或 0，适用于布隆过滤器、状态记录等场景
     * @param key    位图键名    @param offset 比特偏移量   @param b      比特值（true：1，false：0）
     * @return 设置是否成功
     */
    Boolean bitAdd(String key, int offset, boolean b);

    Boolean bitGet(String key, int offset);//获取位图中指定偏移量的比特值,该方法查询位图中特定偏移量的比特状态

    Long bitCount(String key);//统计位图中被设置为 1 的比特数量,该方法计算位图中所有值为 1 的比特总数，用于人口统计等
    @param key    位图键名
    //@param limit:要提取的比特数量  @param offset:起始偏移量  @param key:位图键名 @return 比特字段整数值列表
    List<Long> bitField(String key, int limit, int offset);//获取位图中指定范围的比特字段值,该方法提取位图中从指定偏移量开始的多个连续比特，返回其整数值列表
    //@return 位图的字节数组表示
    byte[] bitGetAll(String key);//获取整个位图的原始字节数据,该方法返回位图的完整字节数组，适用于底层数据处理或自定义解析

    Long hyperAdd(String key, Object... value);//向HyperLogLog中添加元素,该方法用于基数统计，向HyperLogLog结构中添加元素，用于估算不重复元素数量

    Long hyperGet(String... key);//合并多个HyperLogLog并返回估算的基数,该方法将多个HyperLogLog结构合并，并返回估算的唯一元素总数

    void hyperDel(String key);//删除HyperLogLog结构,该方法移除指定的HyperLogLog键
    /**
     * 向地理空间索引中添加一个地点,该方法将地点名称及其经纬度坐标添加到地理空间索引中，用于附近地点查询
     * @param key:地理空间键名  @param x:经度坐标  @param y:纬度坐标  @param name:地点名称标识
     * @return 添加成功的元素数量（1：成功，0：失败）
     */
    Long geoAdd(String key, Double x, Double y, String name);
    // @return 坐标点列表，每个元素是对应地点的 Point 对象
    List<Point> geoGetPointList(String key, Object... place);//获取指定地点的经纬度坐标列表,该方法查询一个或多个地点的坐标信息，返回Point对象列表
    /**
     * 计算两个地点之间的地理空间距离,该方法根据经纬度计算两个地点间的实际距离，返回包含数值和单位的 Distance 对象
     * @param key:地理空间键名  @param placeOne:第一个地点名称  @param placeTow:第二个地点名称
     * @return 距离对象（Distance），包含距离值和单位（如米、千米）
     */
    Distance geoCalculationDistance(String key, String placeOne, String placeTow);
    /**
     * 查询指定地点附近的其他地点,该方法以指定地点为中心，查找距离范围内的其他地点，支持排序和数量限制
     * @param key:地理空间键名  @param place:中心地点名称  @param distance:查询距离范围  @param limit:返回结果数量限制
     * @param sort:排序方向（ASC：由近到远，DESC：由远到近）
     * @return 地理空间查询结果（GeoResults），包含附近地点列表及其距离信息
     */
    GeoResults<RedisGeoCommands.GeoLocation<Object>> geoNearByPlace(String key, String place, Distance distance, long limit, Sort.Direction sort);

    List<String> geoGetHash(String key, String... place);//获取地点的Geohash字符串表示,该方法返回一个或多个地点的 Geohash 值，Geohash是一种用于表示地理位置的编码字符串

}