Add 4 AI bookkeeping features

Feature 7: Bank Rec Auto-Match — AiSuggestMatches endpoint scores uncleared transactions vs statement ending balance; AI Auto-Match panel in Reconcile.cshtml with confidence highlights and Apply All button. Feature 8: Late Payment Prediction — PredictLatePayments endpoint scores open AR customers by risk (high/medium/low) using historical avg-days-to-pay + late rate; rendered as badge table in AR Aging view via ar-aging-ai.js. Feature 9: Natural Language Financial Queries — FinancialQuery GET page + RunFinancialQuery POST; 12-month context snapshot pre-loaded; answers grounded in real data with supporting facts, follow-up suggestions, session history, and example chips. Feature 10: Recurring Bill Detection — RunRecurringDetection scans 12 months of bills for vendor payment patterns (monthly/quarterly/annual); card grid view in Bills/RecurringDetection.cshtml with confidence badges, next-expected-date, and suggested actions. Supporting: 4 new DTO groups in AccountingAiDtos.cs, 4 method signatures in IAccountingAiService.cs, 4 implementations in AccountingAiService.cs, 4 new AiFeatures constants, 2 new Landing page AI report cards. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-10 19:22:49 -04:00
parent e2f9e9ae4f
commit 959e323f3a
16 changed files with 1679 additions and 4 deletions
@@ -322,3 +322,214 @@ public class ClaudeAnomalyFlag
    public string? RecommendedAction { get; set; }
    public string? BillNumber { get; set; }
 }
+
+// ── Feature 7: Bank Rec Auto-Match ───────────────────────────────────────────
+
+public class BankRecMatchItem
+{
+    public string EntityType { get; set; } = string.Empty;   // "Payment", "BillPayment", "Expense"
+    public int EntityId { get; set; }
+    public string Date { get; set; } = string.Empty;          // ISO 8601
+    public string Reference { get; set; } = string.Empty;
+    public string Description { get; set; } = string.Empty;
+    public decimal Amount { get; set; }
+    public string Direction { get; set; } = string.Empty;     // "deposit" or "payment"
+}
+
+public class AutoMatchRequest
+{
+    public List<BankRecMatchItem> UnclearedItems { get; set; } = new();
+    public decimal BeginningBalance { get; set; }
+    public decimal StatementEndingBalance { get; set; }
+}
+
+public class AutoMatchSuggestion
+{
+    public string EntityType { get; set; } = string.Empty;
+    public int EntityId { get; set; }
+    public double Confidence { get; set; }   // 0.0–1.0
+    public string Reason { get; set; } = string.Empty;
+}
+
+public class AutoMatchResult
+{
+    public bool Success { get; set; }
+    public string? ErrorMessage { get; set; }
+    public List<AutoMatchSuggestion> SuggestedCleared { get; set; } = new();
+    public List<string> Insights { get; set; } = new();
+}
+
+/// <summary>Internal JSON schema that Claude returns for bank rec auto-match.</summary>
+public class ClaudeAutoMatchResponse
+{
+    public List<ClaudeAutoMatchSuggestion> SuggestedCleared { get; set; } = new();
+    public List<string> Insights { get; set; } = new();
+}
+
+public class ClaudeAutoMatchSuggestion
+{
+    public string EntityType { get; set; } = string.Empty;
+    public int EntityId { get; set; }
+    public double Confidence { get; set; }
+    public string Reason { get; set; } = string.Empty;
+}
+
+// ── Feature 8: Late Payment Prediction ───────────────────────────────────────
+
+public class OpenInvoiceSummary
+{
+    public string InvoiceNumber { get; set; } = string.Empty;
+    public decimal BalanceDue { get; set; }
+    public string? DueDateIso { get; set; }
+    public int DaysOverdue { get; set; }
+}
+
+public class LatePaymentCustomerData
+{
+    public string CustomerName { get; set; } = string.Empty;
+    public decimal TotalOwed { get; set; }
+    public double AvgDaysToPay { get; set; }      // historical average
+    public int TotalInvoicesAllTime { get; set; }
+    public int LateInvoicesAllTime { get; set; }
+    public List<OpenInvoiceSummary> OpenInvoices { get; set; } = new();
+}
+
+public class LatePaymentPredictionRequest
+{
+    public string CompanyName { get; set; } = string.Empty;
+    public List<LatePaymentCustomerData> Customers { get; set; } = new();
+}
+
+public class LatePaymentPrediction
+{
+    public string CustomerName { get; set; } = string.Empty;
+    /// <summary>"high", "medium", or "low"</summary>
+    public string RiskLevel { get; set; } = "medium";
+    public int EstimatedDaysToPayment { get; set; }
+    public string Reasoning { get; set; } = string.Empty;
+}
+
+public class LatePaymentPredictionResult
+{
+    public bool Success { get; set; }
+    public string? ErrorMessage { get; set; }
+    public List<LatePaymentPrediction> Predictions { get; set; } = new();
+    public List<string> Insights { get; set; } = new();
+}
+
+/// <summary>Internal JSON schema that Claude returns for late payment predictions.</summary>
+public class ClaudeLatePaymentResponse
+{
+    public List<ClaudeLatePaymentPrediction> Predictions { get; set; } = new();
+    public List<string> Insights { get; set; } = new();
+}
+
+public class ClaudeLatePaymentPrediction
+{
+    public string CustomerName { get; set; } = string.Empty;
+    public string RiskLevel { get; set; } = "medium";
+    public int EstimatedDaysToPayment { get; set; }
+    public string Reasoning { get; set; } = string.Empty;
+}
+
+// ── Feature 9: Natural Language Financial Queries ─────────────────────────────
+
+public class MonthlyFinancialSummary
+{
+    public string Month { get; set; } = string.Empty;   // "YYYY-MM"
+    public decimal Revenue { get; set; }
+    public decimal Expenses { get; set; }
+    public decimal NetIncome { get; set; }
+}
+
+public class FinancialQueryContext
+{
+    public string CompanyName { get; set; } = string.Empty;
+    public string AsOfDate { get; set; } = string.Empty;
+    public decimal TotalRevenueYtd { get; set; }
+    public decimal TotalExpensesYtd { get; set; }
+    public decimal NetIncomeYtd { get; set; }
+    public decimal ArOutstanding { get; set; }
+    public decimal ApOutstanding { get; set; }
+    public List<MonthlyFinancialSummary> Last12Months { get; set; } = new();
+    public List<ExpenseByCategory> ExpensesByCategory { get; set; } = new();
+}
+
+public class FinancialQueryRequest
+{
+    public string Question { get; set; } = string.Empty;
+    public FinancialQueryContext Context { get; set; } = new();
+}
+
+public class FinancialQueryResult
+{
+    public bool Success { get; set; }
+    public string? ErrorMessage { get; set; }
+    public string Answer { get; set; } = string.Empty;
+    public string? FollowUpSuggestion { get; set; }
+    public List<string> RelevantFacts { get; set; } = new();
+}
+
+/// <summary>Internal JSON schema that Claude returns for financial queries.</summary>
+public class ClaudeFinancialQueryResponse
+{
+    public string Answer { get; set; } = string.Empty;
+    public string? FollowUpSuggestion { get; set; }
+    public List<string> RelevantFacts { get; set; } = new();
+}
+
+// ── Feature 10: Recurring Bill Detection ─────────────────────────────────────
+
+public class RecurringBillHistoryItem
+{
+    public string VendorName { get; set; } = string.Empty;
+    public string BillNumber { get; set; } = string.Empty;
+    public decimal Amount { get; set; }
+    public string DateIso { get; set; } = string.Empty;
+    public string? Memo { get; set; }
+}
+
+public class RecurringBillDetectionRequest
+{
+    public string CompanyName { get; set; } = string.Empty;
+    public List<RecurringBillHistoryItem> Bills { get; set; } = new();
+}
+
+public class RecurringBillPattern
+{
+    public string VendorName { get; set; } = string.Empty;
+    /// <summary>"monthly", "quarterly", "biannual", "annual"</summary>
+    public string Frequency { get; set; } = string.Empty;
+    public decimal TypicalAmount { get; set; }
+    public string? NextExpectedDateIso { get; set; }
+    /// <summary>"high", "medium", or "low"</summary>
+    public string Confidence { get; set; } = "medium";
+    public string Description { get; set; } = string.Empty;
+    public string? SuggestedAction { get; set; }
+}
+
+public class RecurringBillDetectionResult
+{
+    public bool Success { get; set; }
+    public string? ErrorMessage { get; set; }
+    public List<RecurringBillPattern> Patterns { get; set; } = new();
+    public List<string> Insights { get; set; } = new();
+}
+
+/// <summary>Internal JSON schema that Claude returns for recurring bill detection.</summary>
+public class ClaudeRecurringBillResponse
+{
+    public List<ClaudeRecurringPattern> Patterns { get; set; } = new();
+    public List<string> Insights { get; set; } = new();
+}
+
+public class ClaudeRecurringPattern
+{
+    public string VendorName { get; set; } = string.Empty;
+    public string Frequency { get; set; } = string.Empty;
+    public decimal TypicalAmount { get; set; }
+    public string? NextExpectedDateIso { get; set; }
+    public string Confidence { get; set; } = "medium";
+    public string Description { get; set; } = string.Empty;
+    public string? SuggestedAction { get; set; }
+}
@@ -43,4 +43,33 @@ public interface IAccountingAiService
    /// Returns a ranked list of flagged items with recommended actions.
    /// </summary>
    Task<AnomalyDetectionResult> DetectAnomaliesAsync(AnomalyDetectionRequest request);
+
+    /// <summary>
+    /// Suggests which uncleared bank rec items should be marked as cleared to reconcile
+    /// a statement. Returns a ranked list of suggestions with confidence scores based on
+    /// amount/date patterns and the gap between the current cleared balance and the
+    /// statement ending balance.
+    /// </summary>
+    Task<AutoMatchResult> AutoMatchReconciliationAsync(AutoMatchRequest request);
+
+    /// <summary>
+    /// Predicts likelihood of late payment for each open AR customer using their historical
+    /// payment behavior (avg days to pay, late rate) combined with current overdue status.
+    /// Returns risk levels (high/medium/low) and estimated days to collection.
+    /// </summary>
+    Task<LatePaymentPredictionResult> PredictLatePaymentsAsync(LatePaymentPredictionRequest request);
+
+    /// <summary>
+    /// Answers a plain-English financial question (e.g. "What did we spend on powder last quarter?")
+    /// using pre-loaded company financial context. Returns a direct answer, supporting facts,
+    /// and an optional follow-up question suggestion.
+    /// </summary>
+    Task<FinancialQueryResult> AnswerFinancialQueryAsync(FinancialQueryRequest request);
+
+    /// <summary>
+    /// Analyzes 6–12 months of bill history to detect recurring payment patterns per vendor.
+    /// Returns detected patterns with frequency, typical amount, next expected date, and
+    /// suggested actions (e.g. set a reminder, create a template).
+    /// </summary>
+    Task<RecurringBillDetectionResult> DetectRecurringBillsAsync(RecurringBillDetectionRequest request);
 }