using CMSMicroservice.Domain.Enums;

namespace CMSMicroservice.Application.Common.Interfaces;

/// <summary>
/// سرویس محاسبه موقعیت در Binary Tree
/// این سرویس مشخص می‌کند که کاربر جدید باید در کدام Leg (Left/Right) قرار بگیرد
/// </summary>
public interface INetworkPlacementService
{
    /// <summary>
    /// محاسبه LegPosition برای کاربر جدید
    /// </summary>
    /// <param name="parentId">شناسه Parent در Network</param>
    /// <param name="cancellationToken"></param>
    /// <returns>
    /// - Left: اگر Parent فرزند چپ ندارد
    /// - Right: اگر Parent فرزند راست ندارد
    /// - null: اگر Parent هر دو Leg را دارد (Binary Tree پر است!)
    /// </returns>
    Task<NetworkLeg?> CalculateLegPositionAsync(long parentId, CancellationToken cancellationToken = default);
    
    /// <summary>
    /// بررسی اینکه آیا Parent می‌تواند فرزند جدید بپذیرد
    /// </summary>
    /// <param name="parentId"></param>
    /// <param name="cancellationToken"></param>
    /// <returns>true اگر Parent کمتر از 2 فرزند دارد</returns>
    Task<bool> CanAcceptChildAsync(long parentId, CancellationToken cancellationToken = default);
    
    /// <summary>
    /// پیدا کردن اولین Parent در شبکه که می‌تواند فرزند جدید بپذیرد
    /// (برای Auto-Placement در Binary Tree)
    /// </summary>
    /// <param name="rootParentId">شناسه Parent اصلی که از آن شروع می‌کنیم</param>
    /// <param name="cancellationToken"></param>
    /// <returns>شناسه Parent مناسب برای قرار گرفتن کاربر جدید</returns>
    Task<long?> FindAvailableParentAsync(long rootParentId, CancellationToken cancellationToken = default);
}
