using TakeoutSaaS.Domain.Identity.Entities;

namespace TakeoutSaaS.Domain.Identity.Repositories;

/// <summary>
/// 小程序用户仓储契约。
/// </summary>
public interface IMiniUserRepository
{
    /// <summary>
    /// 根据微信 OpenId 查找小程序用户。
    /// </summary>
    /// <param name="openId">微信 OpenId</param>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>小程序用户，如果不存在则返回 null</returns>
    Task<MiniUser?> FindByOpenIdAsync(string openId, CancellationToken cancellationToken = default);

    /// <summary>
    /// 根据用户 ID 查找小程序用户。
    /// </summary>
    /// <param name="id">用户 ID</param>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>小程序用户，如果不存在则返回 null</returns>
    Task<MiniUser?> FindByIdAsync(long id, CancellationToken cancellationToken = default);

    /// <summary>
    /// 按用户标识集合批量查询小程序用户。
    /// </summary>
    Task<IReadOnlyList<MiniUser>> GetByIdsAsync(
        IReadOnlyCollection<long> ids,
        long tenantId,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// 创建或更新小程序用户（如果 OpenId 已存在则更新，否则创建）。
    /// </summary>
    /// <param name="openId">微信 OpenId</param>
    /// <param name="unionId">微信 UnionId（可选）</param>
    /// <param name="nickname">昵称</param>
    /// <param name="avatar">头像地址（可选）</param>
    /// <param name="tenantId">租户 ID</param>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>创建或更新后的小程序用户</returns>
    Task<MiniUser> CreateOrUpdateAsync(string openId, string? unionId, string? nickname, string? avatar, long tenantId, CancellationToken cancellationToken = default);
}