feat: 新增财务交易流水后端模块

src/Domain/TakeoutSaaS.Domain/Finance/Enums/FinanceTransactionSourceType.cs

@@ -0,0 +1,32 @@
+namespace TakeoutSaaS.Domain.Finance.Enums;
+
+/// <summary>
+/// 交易来源类型。
+/// </summary>
+public enum FinanceTransactionSourceType
+{
+    /// <summary>
+    /// 支付流水。
+    /// </summary>
+    PaymentRecord = 1,
+
+    /// <summary>
+    /// 渠道退款流水。
+    /// </summary>
+    PaymentRefundRecord = 2,
+
+    /// <summary>
+    /// 退款申请（补充来源）。
+    /// </summary>
+    RefundRequest = 3,
+
+    /// <summary>
+    /// 储值充值记录。
+    /// </summary>
+    StoredCardRechargeRecord = 4,
+
+    /// <summary>
+    /// 会员积分流水。
+    /// </summary>
+    MemberPointLedger = 5
+}

src/Domain/TakeoutSaaS.Domain/Finance/Enums/FinanceTransactionType.cs

@@ -0,0 +1,27 @@
+namespace TakeoutSaaS.Domain.Finance.Enums;
+
+/// <summary>
+/// 交易类型。
+/// </summary>
+public enum FinanceTransactionType
+{
+    /// <summary>
+    /// 收入。
+    /// </summary>
+    Income = 1,
+
+    /// <summary>
+    /// 退款。
+    /// </summary>
+    Refund = 2,
+
+    /// <summary>
+    /// 储值充值。
+    /// </summary>
+    StoredCardRecharge = 3,
+
+    /// <summary>
+    /// 积分抵扣。
+    /// </summary>
+    PointRedeem = 4
+}

src/Domain/TakeoutSaaS.Domain/Finance/Models/FinanceTransactionRecord.cs

@@ -0,0 +1,173 @@
+using TakeoutSaaS.Domain.Finance.Enums;
+using TakeoutSaaS.Domain.Orders.Enums;
+using TakeoutSaaS.Domain.Payments.Enums;
+
+namespace TakeoutSaaS.Domain.Finance.Models;
+
+/// <summary>
+/// 交易流水统一记录。
+/// </summary>
+public sealed record FinanceTransactionRecord
+{
+    /// <summary>
+    /// 来源类型。
+    /// </summary>
+    public required FinanceTransactionSourceType SourceType { get; init; }
+
+    /// <summary>
+    /// 来源标识。
+    /// </summary>
+    public required long SourceId { get; init; }
+
+    /// <summary>
+    /// 所属门店。
+    /// </summary>
+    public required long StoreId { get; init; }
+
+    /// <summary>
+    /// 交易单号。
+    /// </summary>
+    public string? TransactionNo { get; init; }
+
+    /// <summary>
+    /// 交易类型。
+    /// </summary>
+    public required FinanceTransactionType TransactionType { get; init; }
+
+    /// <summary>
+    /// 关联订单标识。
+    /// </summary>
+    public long? OrderId { get; init; }
+
+    /// <summary>
+    /// 关联订单号。
+    /// </summary>
+    public string? OrderNo { get; init; }
+
+    /// <summary>
+    /// 渠道。
+    /// </summary>
+    public DeliveryType? DeliveryType { get; init; }
+
+    /// <summary>
+    /// 支付方式。
+    /// </summary>
+    public PaymentMethod? PaymentMethod { get; init; }
+
+    /// <summary>
+    /// 交易金额（收入为正，退款为负）。
+    /// </summary>
+    public required decimal AmountSigned { get; init; }
+
+    /// <summary>
+    /// 交易时间。
+    /// </summary>
+    public required DateTime OccurredAt { get; init; }
+
+    /// <summary>
+    /// 备注。
+    /// </summary>
+    public string? Remark { get; init; }
+
+    /// <summary>
+    /// 顾客姓名。
+    /// </summary>
+    public string? CustomerName { get; init; }
+
+    /// <summary>
+    /// 顾客手机号。
+    /// </summary>
+    public string? CustomerPhone { get; init; }
+
+    /// <summary>
+    /// 退款单号。
+    /// </summary>
+    public string? RefundNo { get; init; }
+
+    /// <summary>
+    /// 退款原因。
+    /// </summary>
+    public string? RefundReason { get; init; }
+
+    /// <summary>
+    /// 会员名称。
+    /// </summary>
+    public string? MemberName { get; init; }
+
+    /// <summary>
+    /// 会员手机号脱敏值。
+    /// </summary>
+    public string? MemberMobileMasked { get; init; }
+
+    /// <summary>
+    /// 充值金额。
+    /// </summary>
+    public decimal? RechargeAmount { get; init; }
+
+    /// <summary>
+    /// 赠送金额。
+    /// </summary>
+    public decimal? GiftAmount { get; init; }
+
+    /// <summary>
+    /// 到账金额。
+    /// </summary>
+    public decimal? ArrivedAmount { get; init; }
+
+    /// <summary>
+    /// 积分变动值。
+    /// </summary>
+    public int? PointChangeAmount { get; init; }
+
+    /// <summary>
+    /// 积分变动后余额。
+    /// </summary>
+    public int? PointBalanceAfterChange { get; init; }
+}
+
+/// <summary>
+/// 交易流水分页快照。
+/// </summary>
+public sealed record FinanceTransactionPageSnapshot
+{
+    /// <summary>
+    /// 分页记录。
+    /// </summary>
+    public required IReadOnlyList<FinanceTransactionRecord> Items { get; init; }
+
+    /// <summary>
+    /// 总记录数。
+    /// </summary>
+    public required int TotalCount { get; init; }
+
+    /// <summary>
+    /// 本页收入合计。
+    /// </summary>
+    public required decimal PageIncomeAmount { get; init; }
+
+    /// <summary>
+    /// 本页退款合计。
+    /// </summary>
+    public required decimal PageRefundAmount { get; init; }
+}
+
+/// <summary>
+/// 交易流水统计快照。
+/// </summary>
+public sealed record FinanceTransactionStatsSnapshot
+{
+    /// <summary>
+    /// 总收入。
+    /// </summary>
+    public required decimal TotalIncome { get; init; }
+
+    /// <summary>
+    /// 总退款。
+    /// </summary>
+    public required decimal TotalRefund { get; init; }
+
+    /// <summary>
+    /// 总交易笔数。
+    /// </summary>
+    public required int TotalCount { get; init; }
+}

src/Domain/TakeoutSaaS.Domain/Finance/Repositories/IFinanceTransactionRepository.cs

@@ -0,0 +1,66 @@
+using TakeoutSaaS.Domain.Finance.Enums;
+using TakeoutSaaS.Domain.Finance.Models;
+using TakeoutSaaS.Domain.Orders.Enums;
+using TakeoutSaaS.Domain.Payments.Enums;
+
+namespace TakeoutSaaS.Domain.Finance.Repositories;
+
+/// <summary>
+/// 财务交易流水仓储契约。
+/// </summary>
+public interface IFinanceTransactionRepository
+{
+    /// <summary>
+    /// 查询交易流水分页。
+    /// </summary>
+    Task<FinanceTransactionPageSnapshot> SearchPageAsync(
+        long tenantId,
+        long storeId,
+        DateTime? startAt,
+        DateTime? endAt,
+        FinanceTransactionType? transactionType,
+        DeliveryType? deliveryType,
+        PaymentMethod? paymentMethod,
+        string? keyword,
+        int page,
+        int pageSize,
+        CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// 查询交易流水统计。
+    /// </summary>
+    Task<FinanceTransactionStatsSnapshot> GetStatsAsync(
+        long tenantId,
+        long storeId,
+        DateTime? startAt,
+        DateTime? endAt,
+        FinanceTransactionType? transactionType,
+        DeliveryType? deliveryType,
+        PaymentMethod? paymentMethod,
+        string? keyword,
+        CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// 查询交易流水详情。
+    /// </summary>
+    Task<FinanceTransactionRecord?> GetDetailAsync(
+        long tenantId,
+        long storeId,
+        FinanceTransactionSourceType sourceType,
+        long sourceId,
+        CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// 查询导出数据。
+    /// </summary>
+    Task<IReadOnlyList<FinanceTransactionRecord>> ListForExportAsync(
+        long tenantId,
+        long storeId,
+        DateTime? startAt,
+        DateTime? endAt,
+        FinanceTransactionType? transactionType,
+        DeliveryType? deliveryType,
+        PaymentMethod? paymentMethod,
+        string? keyword,
+        CancellationToken cancellationToken = default);
+}