jizhi/backend/MiaoJiZhang.Api/Contracts/BusinessContracts.cs

namespace MiaoJiZhang.Api.Contracts;

// ---- Ledger / Category ----
public record LedgerDto(long Id, string Name, string IconKey, bool IsDefault);
public record CategoryDto(
    long Id, string Name, string IconKey, string Type,
    int SortOrder, bool IsCustom, string ColorKey = "mint");
public record CreateCategoryRequest(
    string Name, string IconKey, string Type, string? ColorKey = null);
public record UpdateCategoryRequest(
    string Name, string IconKey, int SortOrder, string? ColorKey = null);

// ---- Transaction ----
public record CreateTransactionRequest(
    long? LedgerId,          // null = 默认账本
    long CategoryId,
    string Type,             // expense | income
    decimal Amount,
    string? Note,
    string? PaymentMethod,
    DateTime? OccurredAt,    // null = 现在
    string? Source,          // manual | voice | ocr
    string? SourceText,
    string? ClientRequestId = null,
    string? TransferDirection = null,
    string? Counterparty = null,
    string? Provider = null,
    string? ProviderTransactionId = null,
    string? RecognitionOccurrenceId = null,
    string? EvidenceFingerprint = null,
    string? RecognitionConfidence = null);

public record UpdateTransactionRequest(
    long LedgerId,
    long CategoryId,
    string Type,
    decimal Amount,
    string? Note,
    string? PaymentMethod,
    DateTime OccurredAt,
    DateTime? BaseUpdatedAt = null,
    string? TransferDirection = null,
    string? Counterparty = null);

public record TransactionDto(
    long Id, long LedgerId, long CategoryId, string CategoryName, string CategoryIcon,
    string Type, decimal Amount, string? Note, string? PaymentMethod,
    DateTime OccurredAt, string Source, string? SourceText,
    bool IsDeleted = false, string CategoryColor = "mint",
    DateTime? UpdatedAt = null,
    string? TransferDirection = null,
    string? Counterparty = null,
    string? Provider = null,
    string? ProviderTransactionId = null,
    string? RecognitionOccurrenceId = null,
    string? EvidenceFingerprint = null,
    string? RecognitionConfidence = null);

public record DailyGroupDto(DateOnly Date, decimal Expense, decimal Income, List<TransactionDto> Items);

public record MonthSummaryDto(
    int Year, int Month, decimal Income, decimal Expense, decimal Balance,
    int Count, List<DailyGroupDto> Days);

public record CategoryStatDto(
    long CategoryId, string Name, string IconKey,
    decimal Amount, double Percent, string ColorKey = "mint");
public record MonthStatsDto(int Year, int Month, decimal TotalExpense, decimal TotalIncome, List<CategoryStatDto> ByCategory, List<decimal> DailyExpenses)
{
    public string? AiAnalysis { get; set; }
}
public record PeriodTrendPointDto(
    string Label, DateTime Date, decimal Expense, decimal Income);
public record PeriodStatsDto(
    string PeriodType, string PeriodLabel, DateTime StartDate, DateTime EndDate,
    decimal TotalExpense, decimal TotalIncome, decimal Balance, int Count,
    List<CategoryStatDto> ByCategory, List<PeriodTrendPointDto> Trend,
    string? Analysis);

// ---- Budget ----
public record BudgetItemDto(
    long? CategoryId, string? CategoryName, string? CategoryIcon,
    decimal Amount, decimal Spent, bool IsRecurring,
    string? CategoryColor = null);
public record BudgetsResponse(int Year, int Month, BudgetItemDto? Total, List<BudgetItemDto> Categories);
public record UpsertBudgetRequest(long? CategoryId, decimal Amount, bool Recurring = false); // Amount<=0 表示删除该预算
public record BudgetAmountRequest(long? CategoryId, decimal Amount);
public record ApplyBudgetBatchRequest(bool Recurring, List<BudgetAmountRequest> Items);
public record BudgetRecommendationItemDto(
    long CategoryId,
    string CategoryName,
    string CategoryIcon,
    decimal SuggestedAmount,
    decimal CurrentSpent,
    decimal HistoricalAverage,
    string Confidence,
    string ColorKey = "mint");
public record BudgetRecommendationResponse(
    int Year,
    int Month,
    decimal SuggestedTotal,
    string Message,
    List<BudgetRecommendationItemDto> Items,
    string? AdjustmentSummary = null,
    List<string>? Warnings = null);
public record BudgetDraftItemRequest(long CategoryId, decimal Amount);
public record BudgetDraftRequest(
    decimal SuggestedTotal,
    List<BudgetDraftItemRequest> Items);
public record BudgetRefinementTurn(string Role, string Content);
public record RefineBudgetRecommendationRequest(
    long? LedgerId,
    int Year,
    int Month,
    string Instruction,
    BudgetDraftRequest CurrentDraft,
    List<BudgetRefinementTurn>? History = null);

// ---- Sticker ----
public record StickerDto(string Key, string Label, string GroupKey);

// ---- Monthly report ----
public record MonthlyReportDto(
    int Year, int Month, decimal Income, decimal Expense, decimal Balance, int Count,
    double AiRatio,
    string? TopDay, decimal TopDayAmount, string? TopDayNote,
    string? TopCategory, decimal TopCategoryAmount, double TopCategoryPercent,
    List<CategoryRankDto> CategoryRanking,
    string Roast);

public record CategoryRankDto(
    string Name, string IconKey, decimal Amount, double Percent,
    string ColorKey = "mint");

public record PeriodReportDto(
    string PeriodType, string PeriodLabel, DateTime StartDate, DateTime EndDate,
    decimal Income, decimal Expense, decimal Balance, int Count, double AiRatio,
    string? PeakLabel, decimal PeakAmount, string? PeakNote,
    string? TopCategory, decimal TopCategoryAmount, double TopCategoryPercent,
    List<CategoryRankDto> CategoryRanking,
    string Commentary);

// ---- OCR ----
public record OcrParseRequest(string Text, string? Source = null);
public record OcrParseResponse(
    bool Matched, long CategoryId, string CategoryName, string CategoryIcon,
    decimal Amount, string? PaymentMethod, string Note, string Type,
    string? TransferDirection = null, string? Counterparty = null);
public record ImageParseItemResponse(
    bool Matched, long CategoryId, string CategoryName, string CategoryIcon,
    string Type, decimal Amount, string? PaymentMethod, string Note,
    DateTime? OccurredAt,
    string? TransferDirection = null, string? Counterparty = null);
public record ImageParseResponse(
    bool Matched, long CategoryId, string CategoryName, string CategoryIcon,
    decimal Amount, string? PaymentMethod, string Note, string Type,
    List<ImageParseItemResponse> Items, DateTime? OccurredAt,
    string? TransferDirection = null, string? Counterparty = null);

public record RecognitionBatchCandidateRequest(
    string CandidateId,
    string ClientRequestId,
    string? FlowSessionId,
    string PackageName,
    string Type,
    decimal Amount,
    string? Merchant,
    string? OrderId,
    DateTime OccurredAt,
    string RecognitionKind,
    string? CategoryHint,
    string Confidence,
    string? SourceText,
    List<string>? EvidenceIds = null,
    string? TransferDirection = null,
    string? Counterparty = null,
    string? Provider = null,
    string? ProviderTransactionId = null,
    string? RecognitionOccurrenceId = null,
    string? IdentityConfidence = null);

public record RecognitionBatchEvidenceRequest(
    string EvidenceId,
    string? CandidateId,
    string? FlowSessionId,
    string PackageName,
    DateTime CapturedAt);

public record RecognitionBatchManifestRequest(
    string BatchId,
    DateTime OpenedAt,
    List<RecognitionBatchCandidateRequest> Candidates,
    List<RecognitionBatchEvidenceRequest> Evidence);

public record RecognitionBatchActionResponse(
    string Action,
    string ActionId,
    string? CandidateId,
    string? EvidenceId,
    long? CategoryId,
    string? CategoryName,
    string? Type,
    decimal? Amount,
    string? PaymentMethod,
    string? Note,
    DateTime? OccurredAt,
    double Confidence,
    string Reason,
    string? TransferDirection = null,
    string? Counterparty = null);

public record RecognitionBatchResponse(
    string BatchId,
    List<RecognitionBatchActionResponse> Actions);

public record RecognitionBatchTransactionItemRequest(
    string CandidateId,
    string ClientRequestId,
    long CategoryId,
    string Type,
    decimal Amount,
    string? Note,
    string? PaymentMethod,
    DateTime OccurredAt,
    string? Source,
    string? SourceText,
    string? TransferDirection = null,
    string? Counterparty = null,
    string? Provider = null,
    string? ProviderTransactionId = null,
    string? RecognitionOccurrenceId = null,
    string? EvidenceFingerprint = null,
    string? RecognitionConfidence = null);

public record CreateRecognitionBatchRequest(
    string BatchId,
    long? LedgerId,
    List<RecognitionBatchTransactionItemRequest> Items);

public record RecognitionBatchTransactionDto(
    string CandidateId,
    TransactionDto Transaction);

// ---- Chat ----
public record SendChatRequest(string Content, string Type = "text", long? LedgerId = null); // text | sticker
public record ChatMessageDto(
    long Id, string Role, string Type, string Content,
    TransactionDto? Transaction, DateTime CreatedAt);
public record SendChatResponse(List<ChatMessageDto> Messages);