books/backend/Books.Api/AiBookkeeper/IAccountMappingService.cs

using Books.Api.EventFlow.ReadModels;

namespace Books.Api.AiBookkeeper;

/// <summary>
/// Maps standard account numbers (from Erhvervsstyrelsen) to company-specific accounts.
/// </summary>
public interface IAccountMappingService
{
    /// <summary>
    /// Find the company's account that matches a standard account number.
    /// </summary>
    /// <param name="companyId">Company ID</param>
    /// <param name="standardAccountNumber">Standard account number from Erhvervsstyrelsen</param>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>The matching account, or null if not found</returns>
    Task<AccountReadModelDto?> FindByStandardAccountNumberAsync(
        string companyId,
        string standardAccountNumber,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Map AI-suggested lines to company accounts.
    /// </summary>
    /// <param name="companyId">Company ID</param>
    /// <param name="suggestedLines">Lines from AI suggestion</param>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>Mapped lines with company account IDs</returns>
    Task<List<MappedSuggestedLine>> MapSuggestedLinesAsync(
        string companyId,
        List<SuggestedLine> suggestedLines,
        CancellationToken cancellationToken = default);
}

/// <summary>
/// A suggested line with the mapped company account.
/// </summary>
public class MappedSuggestedLine
{
    /// <summary>
    /// Original suggested line from AI.
    /// </summary>
    public required SuggestedLine Original { get; init; }

    /// <summary>
    /// Mapped company account (if found).
    /// </summary>
    public AccountReadModelDto? MappedAccount { get; init; }

    /// <summary>
    /// Whether the line was successfully mapped to a company account.
    /// </summary>
    public bool IsMapped => MappedAccount != null;
}