QYZH.InteractiveMagazine/QYZH.InteractiveMagazine.IService/IPetService.cs

using QYZH.InteractiveMagazine.Models.Common;
using QYZH.InteractiveMagazine.Models.Dto;
using QYZH.InteractiveMagazine.Models.Dto.Pet;
using QYZH.InteractiveMagazine.Models.Entity;

namespace QYZH.InteractiveMagazine.IService;

/// <summary>
/// 宠物服务接口
/// </summary>
public interface IPetService : IBaseService<UserPet>
{
    /// <summary>
    /// 获取用户宠物信息
    /// </summary>
    /// <param name="userId">用户Id</param>
    /// <returns>宠物信息</returns>
    Task<PetOutput?> GetPetByUserIdAsync(long userId);

    /// <summary>
    /// 为用户创建默认宠物（最低形态、成长值为0、未激活状态）
    /// </summary>
    /// <param name="userId">用户Id</param>
    Task CreateDefaultPetAsync(long userId);

    /// <summary>
    /// 激活宠物（将状态从 Inactive 改为 Active）
    /// </summary>
    /// <param name="userId">用户Id</param>
    Task ActivatePetAsync(long userId);

    /// <summary>
    /// 喂养宠物（增加成长值 + 记录喂养记录 + 触发进化检查）
    /// </summary>
    /// <param name="userId">用户Id</param>
    /// <param name="input">喂养输入</param>
    /// <returns>喂养结果</returns>
    Task<FeedPetOutput> FeedPetAsync(long userId, FeedPetInput input);

    /// <summary>
    /// 喂养宠物（无事务，需在外部事务中调用）
    /// </summary>
    /// <param name="userId">用户Id</param>
    /// <param name="input">喂养输入</param>
    /// <returns>喂养结果</returns>
    Task<FeedPetOutput> FeedPetInTranAsync(long userId, FeedPetInput input);

    /// <summary>
    /// 获取宠物喂养记录列表
    /// </summary>
    /// <param name="userId">用户Id</param>
    /// <param name="petId">宠物Id</param>
    /// <returns>喂养记录列表</returns>
    Task<PageListModel<FeedingRecordOutput>> GetFeedingRecordsAsync(long userId, long petId, PageQueryModel pageQuery);

    // ==================== 后台管理：宠物模板 ====================

    /// <summary>
    /// 创建宠物模板
    /// </summary>
    Task<PetTemplateOutput> CreateTemplateAsync(PetTemplateInput input);

    /// <summary>
    /// 更新宠物模板
    /// </summary>
    Task<PetTemplateOutput> UpdateTemplateAsync(long id, PetTemplateInput input);

    /// <summary>
    /// 删除宠物模板（软删除）
    /// </summary>
    Task DeleteTemplateAsync(long id);

    /// <summary>
    /// 获取单个宠物模板
    /// </summary>
    Task<PetTemplateOutput> GetTemplateByIdAsync(long id);

    /// <summary>
    /// 分页查询宠物模板列表
    /// </summary>
    Task<PageListModel<PetTemplateOutput>> GetTemplatesAsync(PetTemplateQueryInput input);

    /// <summary>
    /// 更新模板状态（启用/禁用）
    /// </summary>
    Task UpdateTemplateStatusAsync(long id);

    // ==================== 后台管理：进化链 ====================

    /// <summary>
    /// 创建进化阶段
    /// </summary>
    Task<PetEvolutionOutput> CreateEvolutionAsync(PetEvolutionInput input);

    /// <summary>
    /// 更新进化阶段
    /// </summary>
    Task<PetEvolutionOutput> UpdateEvolutionAsync(long id, PetEvolutionInput input);

    /// <summary>
    /// 删除进化阶段（软删除）
    /// </summary>
    Task DeleteEvolutionAsync(long id);

    /// <summary>
    /// 获取单个进化阶段
    /// </summary>
    Task<PetEvolutionOutput> GetEvolutionByIdAsync(long id);

    /// <summary>
    /// 分页查询进化阶段列表
    /// </summary>
    Task<PageListModel<PetEvolutionOutput>> GetEvolutionsAsync(PetEvolutionQueryInput input);

    // ==================== 后台管理：皮肤 ====================

    /// <summary>
    /// 创建皮肤
    /// </summary>
    Task<PetSkinOutput> CreateSkinAsync(PetSkinInput input);

    /// <summary>
    /// 更新皮肤
    /// </summary>
    Task<PetSkinOutput> UpdateSkinAsync(long id, PetSkinInput input);

    /// <summary>
    /// 删除皮肤（软删除）
    /// </summary>
    Task DeleteSkinAsync(long id);

    /// <summary>
    /// 获取单个皮肤（含图片列表）
    /// </summary>
    Task<PetSkinOutput> GetSkinByIdAsync(long id);

    /// <summary>
    /// 分页查询皮肤列表
    /// </summary>
    Task<PageListModel<PetSkinOutput>> GetSkinsAsync(PetSkinQueryInput input);

    // ==================== 后台管理：皮肤图片 ====================

    /// <summary>
    /// 创建皮肤图片
    /// </summary>
    Task<PetSkinImageOutput> CreateSkinImageAsync(PetSkinImageInput input);

    /// <summary>
    /// 更新皮肤图片
    /// </summary>
    Task<PetSkinImageOutput> UpdateSkinImageAsync(long id, PetSkinImageInput input);

    /// <summary>
    /// 删除皮肤图片（软删除）
    /// </summary>
    Task DeleteSkinImageAsync(long id);

    /// <summary>
    /// 获取指定皮肤的所有图片
    /// </summary>
    Task<List<PetSkinImageOutput>> GetSkinImagesBySkinIdAsync(long skinId);

    // ==================== 便捷查询接口 ====================

    /// <summary>
    /// 根据模板Id获取进化链列表（非分页，按StageLevel排序）
    /// </summary>
    Task<List<PetEvolutionOutput>> GetEvolutionsByTemplateIdAsync(long templateId);

    /// <summary>
    /// 根据模板Id获取皮肤列表（非分页，按SortOrder排序）
    /// </summary>
    Task<List<PetSkinOutput>> GetSkinsByTemplateIdAsync(long templateId);

    /// <summary>
    /// 根据皮肤Id获取各阶段图片列表（按进化阶段分组，含阶段基本信息）
    /// </summary>
    Task<List<SkinEvolutionStageOutput>> GetSkinImagesGroupedBySkinIdAsync(long skinId);

    /// <summary>
    /// 获取所有皮肤下拉列表（仅返回Id和Name，按SortOrder排序）
    /// </summary>
    /// <param name="types">皮肤类型列表（可选）</param>
    Task<List<SelectOptionDto>> GetAllSkinsForSelectAsync(List<string>? types = null);
}