namespace SocialService.Domain.Services;

/// <summary>
/// EN: Service interface for graph-based queries (mutual friends, suggestions).
/// VI: Interface service cho các truy vấn dựa trên đồ thị (bạn chung, gợi ý).
/// </summary>
public interface IGraphQueryService
{
    /// <summary>
    /// EN: Get mutual friends between two users.
    /// VI: Lấy bạn chung giữa hai users.
    /// </summary>
    /// <param name="userId1">EN: First user ID / VI: ID user thứ nhất</param>
    /// <param name="userId2">EN: Second user ID / VI: ID user thứ hai</param>
    /// <returns>EN: List of mutual friend user IDs / VI: Danh sách ID bạn chung</returns>
    Task<IEnumerable<Guid>> GetMutualFriendsAsync(Guid userId1, Guid userId2);

    /// <summary>
    /// EN: Get friend suggestions for a user based on mutual connections.
    /// VI: Lấy gợi ý kết bạn cho user dựa trên kết nối chung.
    /// </summary>
    /// <param name="userId">EN: User ID / VI: ID user</param>
    /// <param name="limit">EN: Maximum suggestions / VI: Số lượng gợi ý tối đa</param>
    /// <returns>EN: List of suggested user IDs with mutual count / VI: Danh sách ID user gợi ý với số bạn chung</returns>
    Task<IEnumerable<FriendSuggestion>> GetFriendSuggestionsAsync(Guid userId, int limit = 10);

    /// <summary>
    /// EN: Get the degree of connection between two users.
    /// VI: Lấy bậc kết nối giữa hai users.
    /// </summary>
    /// <param name="userId1">EN: First user ID / VI: ID user thứ nhất</param>
    /// <param name="userId2">EN: Second user ID / VI: ID user thứ hai</param>
    /// <returns>EN: Connection degree (-1 if not connected) / VI: Bậc kết nối (-1 nếu không kết nối)</returns>
    Task<int> GetConnectionDegreeAsync(Guid userId1, Guid userId2);

    /// <summary>
    /// EN: Get mutual friends count between two users.
    /// VI: Lấy số lượng bạn chung giữa hai users.
    /// </summary>
    Task<int> GetMutualFriendsCountAsync(Guid userId1, Guid userId2);
}

/// <summary>
/// EN: DTO for friend suggestion with mutual friends count.
/// VI: DTO cho gợi ý kết bạn với số lượng bạn chung.
/// </summary>
public record FriendSuggestion(Guid UserId, int MutualFriendsCount);
