package com.yunhai.userbase.service;

import com.yunhai.userbase.entity.ApplicationInfo;
import com.yunhai.userbase.model.application.ApplicationInfoQuery;
import com.yunhai.userbase.model.application.ApplicationInfoRequest;
import com.yunhai.userbase.model.application.ApplicationInfoSortVo;
import com.yunhai.userbase.model.application.ApplicationInfoVo;
import com.yunhai.userbase.model.application.PushSettingRequest;
import com.yunhai.userbase.model.application.PushSettingVo;

import org.springframework.data.domain.Page;
import org.springframework.data.domain.Pageable;

import java.util.List;

/**
 * 应用信息业务接口（缓存由 Spring Cache 注解统一管控）。
 */
public interface IApplicationInfoService {

    /**
     * 根据 id 查询应用信息（带缓存，防击穿）。
     */
    ApplicationInfo getById(Integer id);

    /**
     * 保存/更新应用信息（写后同步更新缓存）。
     */
    ApplicationInfo save(ApplicationInfo info);

    /**
     * 根据 id 删除应用信息（同步清除缓存）。
     */
    void deleteById(Integer id);

    /**
     * 新增应用信息。<br>
     * 由入参构造实体并落库；appKey 为整型，从 100000 起按数据库最大值自增，appSecret 为 32 位 UUID。<br>
     *
     * @param request 应用新增入参
     */
    void add(ApplicationInfoRequest request);

    /**
     * 编辑应用信息。<br>
     * 按 id 查找后拷贝入参字段并保存，appKey/appSecret 不随编辑变更。<br>
     *
     * @param id 应用ID
     * @param request 应用编辑入参
     */
    void edit(Integer id, ApplicationInfoRequest request);

    /**
     * 根据 id 删除应用信息。<br>
     *
     * @param id 应用ID
     */
    void delete(Integer id);

    /**
     * 重设应用密钥（appSecret）。<br>
     * 按 id 查找应用并生成新的 32 位 UUID 密钥后保存。<br>
     *
     * @param id 应用ID
     */
    void resetAppSecret(Integer id);

    /**
     * 根据条件分页查询应用列表。<br>
     *
     * @param query    查询条件（name 关键词按名称模糊或 appKey 精确匹配，categoryId 按类别精确匹配）
     * @param pageable 分页参数（page 从 0 起，size 每页条数）
     * @return 分页后的应用视图（含总条数 totalElements）
     */
    Page<ApplicationInfoVo> list(ApplicationInfoQuery query, Pageable pageable);

    List<ApplicationInfoSortVo> findListByCategoryId(Integer categoryId);

    /**
     * 同一应用类型内排序。<br>
     * 入参为该类型下应用的完整有序 id 列表，按列表顺序写入 sortNo（1 起）。<br>
     * 接口会额外校验：所有 id 必须存在且同属一个应用类型，避免跨类型串号导致排序错乱。<br>
     *
     * @param ids 同一应用类型下的应用ID有序列表
     */
    void sort(List<Integer> ids);

    /**
     * 保存应用推送设置（外部接口地址 / 总开关 / 启用的接口 / 学校范围 / 角色范围 / 推送密钥）。<br>
     * 仅更新推送相关字段，写后同步更新 appInfo 缓存。
     *
     * @param id 应用ID
     * @param request 推送设置（各字段可选，null 表示不修改）
     */
    ApplicationInfo savePushSetting(Integer id, PushSettingRequest request);

    /**
     * 获取应用推送设置回显 VO。
     *
     * @param id 应用ID
     * @return 推送设置 VO（仅含推送相关字段）
     */
    PushSettingVo getPushSetting(Integer id);
}