Merge pull request 'feat(finance): 财务概览模块 1:1 还原' (#10) from feature/finance-overview-1to1 into dev

Feature/finance invoice 1to1

src/Api/TakeoutSaaS.TenantApi/Contracts/Finance/FinanceBusinessReportContracts.cs

@@ -0,0 +1,285 @@
+namespace TakeoutSaaS.TenantApi.Contracts.Finance;
+
+/// <summary>
+/// 经营报表列表请求。
+/// </summary>
+public sealed class FinanceBusinessReportListRequest
+{
+    /// <summary>
+    /// 门店 ID。
+    /// </summary>
+    public string StoreId { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 周期类型（daily/weekly/monthly）。
+    /// </summary>
+    public string? PeriodType { get; set; } = "daily";
+
+    /// <summary>
+    /// 页码。
+    /// </summary>
+    public int Page { get; set; } = 1;
+
+    /// <summary>
+    /// 每页条数。
+    /// </summary>
+    public int PageSize { get; set; } = 20;
+}
+
+/// <summary>
+/// 经营报表详情请求。
+/// </summary>
+public sealed class FinanceBusinessReportDetailRequest
+{
+    /// <summary>
+    /// 门店 ID。
+    /// </summary>
+    public string StoreId { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 报表 ID。
+    /// </summary>
+    public string ReportId { get; set; } = string.Empty;
+}
+
+/// <summary>
+/// 经营报表批量导出请求。
+/// </summary>
+public sealed class FinanceBusinessReportBatchExportRequest
+{
+    /// <summary>
+    /// 门店 ID。
+    /// </summary>
+    public string StoreId { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 周期类型（daily/weekly/monthly）。
+    /// </summary>
+    public string? PeriodType { get; set; } = "daily";
+
+    /// <summary>
+    /// 页码。
+    /// </summary>
+    public int Page { get; set; } = 1;
+
+    /// <summary>
+    /// 每页条数。
+    /// </summary>
+    public int PageSize { get; set; } = 20;
+}
+
+/// <summary>
+/// 经营报表列表行响应。
+/// </summary>
+public sealed class FinanceBusinessReportListItemResponse
+{
+    /// <summary>
+    /// 报表 ID。
+    /// </summary>
+    public string ReportId { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 日期文案。
+    /// </summary>
+    public string DateText { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 营业额。
+    /// </summary>
+    public decimal RevenueAmount { get; set; }
+
+    /// <summary>
+    /// 订单数。
+    /// </summary>
+    public int OrderCount { get; set; }
+
+    /// <summary>
+    /// 客单价。
+    /// </summary>
+    public decimal AverageOrderValue { get; set; }
+
+    /// <summary>
+    /// 退款率（百分数）。
+    /// </summary>
+    public decimal RefundRatePercent { get; set; }
+
+    /// <summary>
+    /// 成本总额。
+    /// </summary>
+    public decimal CostTotalAmount { get; set; }
+
+    /// <summary>
+    /// 净利润。
+    /// </summary>
+    public decimal NetProfitAmount { get; set; }
+
+    /// <summary>
+    /// 利润率（百分数）。
+    /// </summary>
+    public decimal ProfitRatePercent { get; set; }
+
+    /// <summary>
+    /// 状态编码。
+    /// </summary>
+    public string Status { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 状态文案。
+    /// </summary>
+    public string StatusText { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 是否可下载。
+    /// </summary>
+    public bool CanDownload { get; set; }
+}
+
+/// <summary>
+/// 经营报表列表响应。
+/// </summary>
+public sealed class FinanceBusinessReportListResultResponse
+{
+    /// <summary>
+    /// 列表。
+    /// </summary>
+    public List<FinanceBusinessReportListItemResponse> Items { get; set; } = [];
+
+    /// <summary>
+    /// 总数。
+    /// </summary>
+    public int Total { get; set; }
+
+    /// <summary>
+    /// 页码。
+    /// </summary>
+    public int Page { get; set; }
+
+    /// <summary>
+    /// 每页条数。
+    /// </summary>
+    public int PageSize { get; set; }
+}
+
+/// <summary>
+/// KPI 响应项。
+/// </summary>
+public sealed class FinanceBusinessReportKpiResponse
+{
+    /// <summary>
+    /// 指标键。
+    /// </summary>
+    public string Key { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 指标名称。
+    /// </summary>
+    public string Label { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 指标值文案。
+    /// </summary>
+    public string ValueText { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 同比变化率（百分数）。
+    /// </summary>
+    public decimal YoyChangeRate { get; set; }
+
+    /// <summary>
+    /// 环比变化率（百分数）。
+    /// </summary>
+    public decimal MomChangeRate { get; set; }
+}
+
+/// <summary>
+/// 明细行响应项。
+/// </summary>
+public sealed class FinanceBusinessReportBreakdownItemResponse
+{
+    /// <summary>
+    /// 明细键。
+    /// </summary>
+    public string Key { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 明细名称。
+    /// </summary>
+    public string Label { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 金额。
+    /// </summary>
+    public decimal Amount { get; set; }
+
+    /// <summary>
+    /// 占比（百分数）。
+    /// </summary>
+    public decimal RatioPercent { get; set; }
+}
+
+/// <summary>
+/// 经营报表详情响应。
+/// </summary>
+public sealed class FinanceBusinessReportDetailResponse
+{
+    /// <summary>
+    /// 报表 ID。
+    /// </summary>
+    public string ReportId { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 标题。
+    /// </summary>
+    public string Title { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 周期类型编码。
+    /// </summary>
+    public string PeriodType { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 状态编码。
+    /// </summary>
+    public string Status { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 状态文案。
+    /// </summary>
+    public string StatusText { get; set; } = string.Empty;
+
+    /// <summary>
+    /// KPI 列表。
+    /// </summary>
+    public List<FinanceBusinessReportKpiResponse> Kpis { get; set; } = [];
+
+    /// <summary>
+    /// 收入明细（按渠道）。
+    /// </summary>
+    public List<FinanceBusinessReportBreakdownItemResponse> IncomeBreakdowns { get; set; } = [];
+
+    /// <summary>
+    /// 成本明细（按类别）。
+    /// </summary>
+    public List<FinanceBusinessReportBreakdownItemResponse> CostBreakdowns { get; set; } = [];
+}
+
+/// <summary>
+/// 经营报表导出响应。
+/// </summary>
+public sealed class FinanceBusinessReportExportResponse
+{
+    /// <summary>
+    /// 文件名。
+    /// </summary>
+    public string FileName { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Base64 文件内容。
+    /// </summary>
+    public string FileContentBase64 { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 导出总记录数。
+    /// </summary>
+    public int TotalCount { get; set; }
+}

src/Api/TakeoutSaaS.TenantApi/Contracts/Finance/FinanceCostContracts.cs

@@ -0,0 +1,384 @@
+namespace TakeoutSaaS.TenantApi.Contracts.Finance;
+
+/// <summary>
+/// 成本模块通用作用域请求。
+/// </summary>
+public class FinanceCostScopeRequest
+{
+    /// <summary>
+    /// 维度（tenant/store）。
+    /// </summary>
+    public string? Dimension { get; set; }
+
+    /// <summary>
+    /// 门店标识（门店维度必填）。
+    /// </summary>
+    public string? StoreId { get; set; }
+
+    /// <summary>
+    /// 月份（yyyy-MM）。
+    /// </summary>
+    public string? Month { get; set; }
+}
+
+/// <summary>
+/// 成本录入查询请求。
+/// </summary>
+public sealed class FinanceCostEntryRequest : FinanceCostScopeRequest;
+
+/// <summary>
+/// 成本分析查询请求。
+/// </summary>
+public sealed class FinanceCostAnalysisRequest : FinanceCostScopeRequest
+{
+    /// <summary>
+    /// 趋势月份数量。
+    /// </summary>
+    public int TrendMonthCount { get; set; } = 6;
+}
+
+/// <summary>
+/// 成本录入保存请求。
+/// </summary>
+public sealed class SaveFinanceCostEntryRequest : FinanceCostScopeRequest
+{
+    /// <summary>
+    /// 分类列表。
+    /// </summary>
+    public List<SaveFinanceCostCategoryRequest> Categories { get; set; } = [];
+}
+
+/// <summary>
+/// 成本分类保存项请求。
+/// </summary>
+public sealed class SaveFinanceCostCategoryRequest
+{
+    /// <summary>
+    /// 分类编码（food/labor/fixed/packaging）。
+    /// </summary>
+    public string Category { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 分类总金额。
+    /// </summary>
+    public decimal TotalAmount { get; set; }
+
+    /// <summary>
+    /// 分类明细。
+    /// </summary>
+    public List<SaveFinanceCostDetailRequest> Items { get; set; } = [];
+}
+
+/// <summary>
+/// 成本明细保存项请求。
+/// </summary>
+public sealed class SaveFinanceCostDetailRequest
+{
+    /// <summary>
+    /// 明细标识（可空）。
+    /// </summary>
+    public string? ItemId { get; set; }
+
+    /// <summary>
+    /// 明细名称。
+    /// </summary>
+    public string ItemName { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 明细金额。
+    /// </summary>
+    public decimal Amount { get; set; }
+
+    /// <summary>
+    /// 数量（人工类可用）。
+    /// </summary>
+    public decimal? Quantity { get; set; }
+
+    /// <summary>
+    /// 单价（人工类可用）。
+    /// </summary>
+    public decimal? UnitPrice { get; set; }
+
+    /// <summary>
+    /// 排序值。
+    /// </summary>
+    public int SortOrder { get; set; }
+}
+
+/// <summary>
+/// 成本录入响应。
+/// </summary>
+public sealed class FinanceCostEntryResponse
+{
+    /// <summary>
+    /// 维度编码。
+    /// </summary>
+    public string Dimension { get; set; } = "tenant";
+
+    /// <summary>
+    /// 门店标识（门店维度时有值）。
+    /// </summary>
+    public string? StoreId { get; set; }
+
+    /// <summary>
+    /// 月份（yyyy-MM）。
+    /// </summary>
+    public string Month { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 本月营业额。
+    /// </summary>
+    public decimal MonthRevenue { get; set; }
+
+    /// <summary>
+    /// 本月总成本。
+    /// </summary>
+    public decimal TotalCost { get; set; }
+
+    /// <summary>
+    /// 本月成本率（%）。
+    /// </summary>
+    public decimal CostRate { get; set; }
+
+    /// <summary>
+    /// 分类数据。
+    /// </summary>
+    public List<FinanceCostEntryCategoryResponse> Categories { get; set; } = [];
+}
+
+/// <summary>
+/// 成本分类响应。
+/// </summary>
+public sealed class FinanceCostEntryCategoryResponse
+{
+    /// <summary>
+    /// 分类编码。
+    /// </summary>
+    public string Category { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 分类文案。
+    /// </summary>
+    public string CategoryText { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 分类总金额。
+    /// </summary>
+    public decimal TotalAmount { get; set; }
+
+    /// <summary>
+    /// 分类占比（%）。
+    /// </summary>
+    public decimal Percentage { get; set; }
+
+    /// <summary>
+    /// 明细数据。
+    /// </summary>
+    public List<FinanceCostEntryDetailResponse> Items { get; set; } = [];
+}
+
+/// <summary>
+/// 成本明细响应。
+/// </summary>
+public sealed class FinanceCostEntryDetailResponse
+{
+    /// <summary>
+    /// 明细标识。
+    /// </summary>
+    public string? ItemId { get; set; }
+
+    /// <summary>
+    /// 明细名称。
+    /// </summary>
+    public string ItemName { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 明细金额。
+    /// </summary>
+    public decimal Amount { get; set; }
+
+    /// <summary>
+    /// 数量（人工类可用）。
+    /// </summary>
+    public decimal? Quantity { get; set; }
+
+    /// <summary>
+    /// 单价（人工类可用）。
+    /// </summary>
+    public decimal? UnitPrice { get; set; }
+
+    /// <summary>
+    /// 排序值。
+    /// </summary>
+    public int SortOrder { get; set; }
+}
+
+/// <summary>
+/// 成本分析响应。
+/// </summary>
+public sealed class FinanceCostAnalysisResponse
+{
+    /// <summary>
+    /// 维度编码。
+    /// </summary>
+    public string Dimension { get; set; } = "tenant";
+
+    /// <summary>
+    /// 门店标识（门店维度时有值）。
+    /// </summary>
+    public string? StoreId { get; set; }
+
+    /// <summary>
+    /// 月份（yyyy-MM）。
+    /// </summary>
+    public string Month { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 统计卡。
+    /// </summary>
+    public FinanceCostAnalysisStatsResponse Stats { get; set; } = new();
+
+    /// <summary>
+    /// 趋势数据。
+    /// </summary>
+    public List<FinanceCostTrendPointResponse> Trend { get; set; } = [];
+
+    /// <summary>
+    /// 构成数据。
+    /// </summary>
+    public List<FinanceCostCompositionResponse> Composition { get; set; } = [];
+
+    /// <summary>
+    /// 明细表数据。
+    /// </summary>
+    public List<FinanceCostMonthlyDetailResponse> DetailRows { get; set; } = [];
+}
+
+/// <summary>
+/// 成本分析统计卡响应。
+/// </summary>
+public sealed class FinanceCostAnalysisStatsResponse
+{
+    /// <summary>
+    /// 本月总成本。
+    /// </summary>
+    public decimal TotalCost { get; set; }
+
+    /// <summary>
+    /// 食材成本率（%）。
+    /// </summary>
+    public decimal FoodCostRate { get; set; }
+
+    /// <summary>
+    /// 单均成本。
+    /// </summary>
+    public decimal AverageCostPerPaidOrder { get; set; }
+
+    /// <summary>
+    /// 环比变化（%）。
+    /// </summary>
+    public decimal MonthOnMonthChangeRate { get; set; }
+
+    /// <summary>
+    /// 本月营业额。
+    /// </summary>
+    public decimal Revenue { get; set; }
+
+    /// <summary>
+    /// 本月支付成功订单数。
+    /// </summary>
+    public int PaidOrderCount { get; set; }
+}
+
+/// <summary>
+/// 成本趋势点响应。
+/// </summary>
+public sealed class FinanceCostTrendPointResponse
+{
+    /// <summary>
+    /// 月份（yyyy-MM）。
+    /// </summary>
+    public string Month { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 月度总成本。
+    /// </summary>
+    public decimal TotalCost { get; set; }
+
+    /// <summary>
+    /// 月度营业额。
+    /// </summary>
+    public decimal Revenue { get; set; }
+
+    /// <summary>
+    /// 月度成本率（%）。
+    /// </summary>
+    public decimal CostRate { get; set; }
+}
+
+/// <summary>
+/// 成本构成响应。
+/// </summary>
+public sealed class FinanceCostCompositionResponse
+{
+    /// <summary>
+    /// 分类编码。
+    /// </summary>
+    public string Category { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 分类文案。
+    /// </summary>
+    public string CategoryText { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 金额。
+    /// </summary>
+    public decimal Amount { get; set; }
+
+    /// <summary>
+    /// 占比（%）。
+    /// </summary>
+    public decimal Percentage { get; set; }
+}
+
+/// <summary>
+/// 成本分析明细表行响应。
+/// </summary>
+public sealed class FinanceCostMonthlyDetailResponse
+{
+    /// <summary>
+    /// 月份（yyyy-MM）。
+    /// </summary>
+    public string Month { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 食材成本。
+    /// </summary>
+    public decimal FoodAmount { get; set; }
+
+    /// <summary>
+    /// 人工成本。
+    /// </summary>
+    public decimal LaborAmount { get; set; }
+
+    /// <summary>
+    /// 固定费用。
+    /// </summary>
+    public decimal FixedAmount { get; set; }
+
+    /// <summary>
+    /// 包装耗材。
+    /// </summary>
+    public decimal PackagingAmount { get; set; }
+
+    /// <summary>
+    /// 总成本。
+    /// </summary>
+    public decimal TotalCost { get; set; }
+
+    /// <summary>
+    /// 成本率（%）。
+    /// </summary>
+    public decimal CostRate { get; set; }
+}

src/Api/TakeoutSaaS.TenantApi/Contracts/Finance/FinanceInvoiceContracts.cs

@@ -0,0 +1,533 @@
+namespace TakeoutSaaS.TenantApi.Contracts.Finance;
+
+/// <summary>
+/// 保存发票设置请求。
+/// </summary>
+public sealed class FinanceInvoiceSettingSaveRequest
+{
+    /// <summary>
+    /// 企业名称。
+    /// </summary>
+    public string CompanyName { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 纳税人识别号。
+    /// </summary>
+    public string TaxpayerNumber { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 注册地址。
+    /// </summary>
+    public string? RegisteredAddress { get; set; }
+
+    /// <summary>
+    /// 注册电话。
+    /// </summary>
+    public string? RegisteredPhone { get; set; }
+
+    /// <summary>
+    /// 开户银行。
+    /// </summary>
+    public string? BankName { get; set; }
+
+    /// <summary>
+    /// 银行账号。
+    /// </summary>
+    public string? BankAccount { get; set; }
+
+    /// <summary>
+    /// 是否启用电子普通发票。
+    /// </summary>
+    public bool EnableElectronicNormalInvoice { get; set; } = true;
+
+    /// <summary>
+    /// 是否启用电子专用发票。
+    /// </summary>
+    public bool EnableElectronicSpecialInvoice { get; set; }
+
+    /// <summary>
+    /// 是否启用自动开票。
+    /// </summary>
+    public bool EnableAutoIssue { get; set; }
+
+    /// <summary>
+    /// 自动开票单张最大金额。
+    /// </summary>
+    public decimal AutoIssueMaxAmount { get; set; } = 10_000m;
+}
+
+/// <summary>
+/// 发票记录列表请求。
+/// </summary>
+public sealed class FinanceInvoiceRecordListRequest
+{
+    /// <summary>
+    /// 开始日期（yyyy-MM-dd）。
+    /// </summary>
+    public string? StartDate { get; set; }
+
+    /// <summary>
+    /// 结束日期（yyyy-MM-dd）。
+    /// </summary>
+    public string? EndDate { get; set; }
+
+    /// <summary>
+    /// 状态（pending/issued/voided）。
+    /// </summary>
+    public string? Status { get; set; }
+
+    /// <summary>
+    /// 类型（normal/special）。
+    /// </summary>
+    public string? InvoiceType { get; set; }
+
+    /// <summary>
+    /// 关键词（发票号/公司名/申请人）。
+    /// </summary>
+    public string? Keyword { get; set; }
+
+    /// <summary>
+    /// 页码。
+    /// </summary>
+    public int Page { get; set; } = 1;
+
+    /// <summary>
+    /// 每页条数。
+    /// </summary>
+    public int PageSize { get; set; } = 10;
+}
+
+/// <summary>
+/// 发票记录详情请求。
+/// </summary>
+public sealed class FinanceInvoiceRecordDetailRequest
+{
+    /// <summary>
+    /// 发票记录 ID。
+    /// </summary>
+    public string RecordId { get; set; } = string.Empty;
+}
+
+/// <summary>
+/// 发票开票请求。
+/// </summary>
+public sealed class FinanceInvoiceRecordIssueRequest
+{
+    /// <summary>
+    /// 发票记录 ID。
+    /// </summary>
+    public string RecordId { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 接收邮箱（可选）。
+    /// </summary>
+    public string? ContactEmail { get; set; }
+
+    /// <summary>
+    /// 开票备注。
+    /// </summary>
+    public string? IssueRemark { get; set; }
+}
+
+/// <summary>
+/// 发票作废请求。
+/// </summary>
+public sealed class FinanceInvoiceRecordVoidRequest
+{
+    /// <summary>
+    /// 发票记录 ID。
+    /// </summary>
+    public string RecordId { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 作废原因。
+    /// </summary>
+    public string VoidReason { get; set; } = string.Empty;
+}
+
+/// <summary>
+/// 发票申请请求。
+/// </summary>
+public sealed class FinanceInvoiceRecordApplyRequest
+{
+    /// <summary>
+    /// 申请人。
+    /// </summary>
+    public string ApplicantName { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 开票抬头（公司名）。
+    /// </summary>
+    public string CompanyName { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 纳税人识别号。
+    /// </summary>
+    public string? TaxpayerNumber { get; set; }
+
+    /// <summary>
+    /// 发票类型（normal/special）。
+    /// </summary>
+    public string InvoiceType { get; set; } = "normal";
+
+    /// <summary>
+    /// 开票金额。
+    /// </summary>
+    public decimal Amount { get; set; }
+
+    /// <summary>
+    /// 关联订单号。
+    /// </summary>
+    public string OrderNo { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 接收邮箱。
+    /// </summary>
+    public string? ContactEmail { get; set; }
+
+    /// <summary>
+    /// 联系电话。
+    /// </summary>
+    public string? ContactPhone { get; set; }
+
+    /// <summary>
+    /// 申请备注。
+    /// </summary>
+    public string? ApplyRemark { get; set; }
+
+    /// <summary>
+    /// 申请时间（可空）。
+    /// </summary>
+    public DateTime? AppliedAt { get; set; }
+}
+
+/// <summary>
+/// 发票设置响应。
+/// </summary>
+public sealed class FinanceInvoiceSettingResponse
+{
+    /// <summary>
+    /// 企业名称。
+    /// </summary>
+    public string CompanyName { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 纳税人识别号。
+    /// </summary>
+    public string TaxpayerNumber { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 注册地址。
+    /// </summary>
+    public string? RegisteredAddress { get; set; }
+
+    /// <summary>
+    /// 注册电话。
+    /// </summary>
+    public string? RegisteredPhone { get; set; }
+
+    /// <summary>
+    /// 开户银行。
+    /// </summary>
+    public string? BankName { get; set; }
+
+    /// <summary>
+    /// 银行账号。
+    /// </summary>
+    public string? BankAccount { get; set; }
+
+    /// <summary>
+    /// 是否启用电子普通发票。
+    /// </summary>
+    public bool EnableElectronicNormalInvoice { get; set; }
+
+    /// <summary>
+    /// 是否启用电子专用发票。
+    /// </summary>
+    public bool EnableElectronicSpecialInvoice { get; set; }
+
+    /// <summary>
+    /// 是否启用自动开票。
+    /// </summary>
+    public bool EnableAutoIssue { get; set; }
+
+    /// <summary>
+    /// 自动开票单张最大金额。
+    /// </summary>
+    public decimal AutoIssueMaxAmount { get; set; }
+}
+
+/// <summary>
+/// 发票统计响应。
+/// </summary>
+public sealed class FinanceInvoiceStatsResponse
+{
+    /// <summary>
+    /// 本月已开票金额。
+    /// </summary>
+    public decimal CurrentMonthIssuedAmount { get; set; }
+
+    /// <summary>
+    /// 本月已开票张数。
+    /// </summary>
+    public int CurrentMonthIssuedCount { get; set; }
+
+    /// <summary>
+    /// 待开票数量。
+    /// </summary>
+    public int PendingCount { get; set; }
+
+    /// <summary>
+    /// 已作废数量。
+    /// </summary>
+    public int VoidedCount { get; set; }
+}
+
+/// <summary>
+/// 发票记录列表项响应。
+/// </summary>
+public sealed class FinanceInvoiceRecordResponse
+{
+    /// <summary>
+    /// 记录 ID。
+    /// </summary>
+    public string RecordId { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 发票号码。
+    /// </summary>
+    public string InvoiceNo { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 申请人。
+    /// </summary>
+    public string ApplicantName { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 开票抬头（公司名）。
+    /// </summary>
+    public string CompanyName { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 发票类型编码。
+    /// </summary>
+    public string InvoiceType { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 发票类型文案。
+    /// </summary>
+    public string InvoiceTypeText { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 金额。
+    /// </summary>
+    public decimal Amount { get; set; }
+
+    /// <summary>
+    /// 关联订单号。
+    /// </summary>
+    public string OrderNo { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 状态编码。
+    /// </summary>
+    public string Status { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 状态文案。
+    /// </summary>
+    public string StatusText { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 申请时间（本地显示字符串）。
+    /// </summary>
+    public string AppliedAt { get; set; } = string.Empty;
+}
+
+/// <summary>
+/// 发票记录详情响应。
+/// </summary>
+public sealed class FinanceInvoiceRecordDetailResponse
+{
+    /// <summary>
+    /// 记录 ID。
+    /// </summary>
+    public string RecordId { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 发票号码。
+    /// </summary>
+    public string InvoiceNo { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 申请人。
+    /// </summary>
+    public string ApplicantName { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 开票抬头（公司名）。
+    /// </summary>
+    public string CompanyName { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 纳税人识别号。
+    /// </summary>
+    public string? TaxpayerNumber { get; set; }
+
+    /// <summary>
+    /// 发票类型编码。
+    /// </summary>
+    public string InvoiceType { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 发票类型文案。
+    /// </summary>
+    public string InvoiceTypeText { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 金额。
+    /// </summary>
+    public decimal Amount { get; set; }
+
+    /// <summary>
+    /// 关联订单号。
+    /// </summary>
+    public string OrderNo { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 接收邮箱。
+    /// </summary>
+    public string? ContactEmail { get; set; }
+
+    /// <summary>
+    /// 联系电话。
+    /// </summary>
+    public string? ContactPhone { get; set; }
+
+    /// <summary>
+    /// 申请备注。
+    /// </summary>
+    public string? ApplyRemark { get; set; }
+
+    /// <summary>
+    /// 状态编码。
+    /// </summary>
+    public string Status { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 状态文案。
+    /// </summary>
+    public string StatusText { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 申请时间（本地显示字符串）。
+    /// </summary>
+    public string AppliedAt { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 开票时间（本地显示字符串）。
+    /// </summary>
+    public string? IssuedAt { get; set; }
+
+    /// <summary>
+    /// 开票人 ID。
+    /// </summary>
+    public string? IssuedByUserId { get; set; }
+
+    /// <summary>
+    /// 开票备注。
+    /// </summary>
+    public string? IssueRemark { get; set; }
+
+    /// <summary>
+    /// 作废时间（本地显示字符串）。
+    /// </summary>
+    public string? VoidedAt { get; set; }
+
+    /// <summary>
+    /// 作废人 ID。
+    /// </summary>
+    public string? VoidedByUserId { get; set; }
+
+    /// <summary>
+    /// 作废原因。
+    /// </summary>
+    public string? VoidReason { get; set; }
+}
+
+/// <summary>
+/// 发票开票结果响应。
+/// </summary>
+public sealed class FinanceInvoiceIssueResultResponse
+{
+    /// <summary>
+    /// 记录 ID。
+    /// </summary>
+    public string RecordId { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 发票号码。
+    /// </summary>
+    public string InvoiceNo { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 开票抬头。
+    /// </summary>
+    public string CompanyName { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 金额。
+    /// </summary>
+    public decimal Amount { get; set; }
+
+    /// <summary>
+    /// 接收邮箱。
+    /// </summary>
+    public string? ContactEmail { get; set; }
+
+    /// <summary>
+    /// 开票时间（本地显示字符串）。
+    /// </summary>
+    public string IssuedAt { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 状态编码。
+    /// </summary>
+    public string Status { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 状态文案。
+    /// </summary>
+    public string StatusText { get; set; } = string.Empty;
+}
+
+/// <summary>
+/// 发票记录分页响应。
+/// </summary>
+public sealed class FinanceInvoiceRecordListResultResponse
+{
+    /// <summary>
+    /// 列表项。
+    /// </summary>
+    public List<FinanceInvoiceRecordResponse> Items { get; set; } = [];
+
+    /// <summary>
+    /// 页码。
+    /// </summary>
+    public int Page { get; set; }
+
+    /// <summary>
+    /// 每页条数。
+    /// </summary>
+    public int PageSize { get; set; }
+
+    /// <summary>
+    /// 总条数。
+    /// </summary>
+    public int TotalCount { get; set; }
+
+    /// <summary>
+    /// 统计。
+    /// </summary>
+    public FinanceInvoiceStatsResponse Stats { get; set; } = new();
+}

src/Api/TakeoutSaaS.TenantApi/Contracts/Finance/FinanceOverviewContracts.cs

@@ -0,0 +1,329 @@
+namespace TakeoutSaaS.TenantApi.Contracts.Finance;
+
+/// <summary>
+/// 财务概览查询请求。
+/// </summary>
+public sealed class FinanceOverviewDashboardRequest
+{
+    /// <summary>
+    /// 维度（tenant/store）。
+    /// </summary>
+    public string? Dimension { get; set; }
+
+    /// <summary>
+    /// 门店 ID（门店维度必填）。
+    /// </summary>
+    public string? StoreId { get; set; }
+}
+
+/// <summary>
+/// 财务概览指标卡响应。
+/// </summary>
+public sealed class FinanceOverviewKpiCardResponse
+{
+    /// <summary>
+    /// 指标值。
+    /// </summary>
+    public decimal Amount { get; set; }
+
+    /// <summary>
+    /// 对比值。
+    /// </summary>
+    public decimal CompareAmount { get; set; }
+
+    /// <summary>
+    /// 变化率（%）。
+    /// </summary>
+    public decimal ChangeRate { get; set; }
+
+    /// <summary>
+    /// 趋势（up/down/flat）。
+    /// </summary>
+    public string Trend { get; set; } = "flat";
+
+    /// <summary>
+    /// 对比文案。
+    /// </summary>
+    public string CompareLabel { get; set; } = "较昨日";
+}
+
+/// <summary>
+/// 收入趋势点响应。
+/// </summary>
+public sealed class FinanceOverviewIncomeTrendPointResponse
+{
+    /// <summary>
+    /// 日期（yyyy-MM-dd）。
+    /// </summary>
+    public string Date { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 轴标签（MM/dd）。
+    /// </summary>
+    public string DateLabel { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 实收金额。
+    /// </summary>
+    public decimal Amount { get; set; }
+}
+
+/// <summary>
+/// 收入趋势响应。
+/// </summary>
+public sealed class FinanceOverviewIncomeTrendResponse
+{
+    /// <summary>
+    /// 近 7 天。
+    /// </summary>
+    public List<FinanceOverviewIncomeTrendPointResponse> Last7Days { get; set; } = [];
+
+    /// <summary>
+    /// 近 30 天。
+    /// </summary>
+    public List<FinanceOverviewIncomeTrendPointResponse> Last30Days { get; set; } = [];
+}
+
+/// <summary>
+/// 利润趋势点响应。
+/// </summary>
+public sealed class FinanceOverviewProfitTrendPointResponse
+{
+    /// <summary>
+    /// 日期（yyyy-MM-dd）。
+    /// </summary>
+    public string Date { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 轴标签（MM/dd）。
+    /// </summary>
+    public string DateLabel { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 营收。
+    /// </summary>
+    public decimal RevenueAmount { get; set; }
+
+    /// <summary>
+    /// 成本。
+    /// </summary>
+    public decimal CostAmount { get; set; }
+
+    /// <summary>
+    /// 净利润。
+    /// </summary>
+    public decimal NetProfitAmount { get; set; }
+}
+
+/// <summary>
+/// 利润趋势响应。
+/// </summary>
+public sealed class FinanceOverviewProfitTrendResponse
+{
+    /// <summary>
+    /// 近 7 天。
+    /// </summary>
+    public List<FinanceOverviewProfitTrendPointResponse> Last7Days { get; set; } = [];
+
+    /// <summary>
+    /// 近 30 天。
+    /// </summary>
+    public List<FinanceOverviewProfitTrendPointResponse> Last30Days { get; set; } = [];
+}
+
+/// <summary>
+/// 收入构成项响应。
+/// </summary>
+public sealed class FinanceOverviewIncomeCompositionItemResponse
+{
+    /// <summary>
+    /// 渠道编码。
+    /// </summary>
+    public string Channel { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 渠道文案。
+    /// </summary>
+    public string ChannelText { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 金额。
+    /// </summary>
+    public decimal Amount { get; set; }
+
+    /// <summary>
+    /// 占比（%）。
+    /// </summary>
+    public decimal Percentage { get; set; }
+}
+
+/// <summary>
+/// 收入构成响应。
+/// </summary>
+public sealed class FinanceOverviewIncomeCompositionResponse
+{
+    /// <summary>
+    /// 总实收。
+    /// </summary>
+    public decimal TotalAmount { get; set; }
+
+    /// <summary>
+    /// 构成项。
+    /// </summary>
+    public List<FinanceOverviewIncomeCompositionItemResponse> Items { get; set; } = [];
+}
+
+/// <summary>
+/// 成本构成项响应。
+/// </summary>
+public sealed class FinanceOverviewCostCompositionItemResponse
+{
+    /// <summary>
+    /// 分类编码。
+    /// </summary>
+    public string Category { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 分类文案。
+    /// </summary>
+    public string CategoryText { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 金额。
+    /// </summary>
+    public decimal Amount { get; set; }
+
+    /// <summary>
+    /// 占比（%）。
+    /// </summary>
+    public decimal Percentage { get; set; }
+}
+
+/// <summary>
+/// 成本构成响应。
+/// </summary>
+public sealed class FinanceOverviewCostCompositionResponse
+{
+    /// <summary>
+    /// 总成本。
+    /// </summary>
+    public decimal TotalAmount { get; set; }
+
+    /// <summary>
+    /// 构成项。
+    /// </summary>
+    public List<FinanceOverviewCostCompositionItemResponse> Items { get; set; } = [];
+}
+
+/// <summary>
+/// TOP 商品项响应。
+/// </summary>
+public sealed class FinanceOverviewTopProductItemResponse
+{
+    /// <summary>
+    /// 排名。
+    /// </summary>
+    public int Rank { get; set; }
+
+    /// <summary>
+    /// 商品名称。
+    /// </summary>
+    public string ProductName { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 销量。
+    /// </summary>
+    public int SalesQuantity { get; set; }
+
+    /// <summary>
+    /// 营收金额。
+    /// </summary>
+    public decimal RevenueAmount { get; set; }
+
+    /// <summary>
+    /// 占比（%）。
+    /// </summary>
+    public decimal Percentage { get; set; }
+}
+
+/// <summary>
+/// TOP 商品响应。
+/// </summary>
+public sealed class FinanceOverviewTopProductResponse
+{
+    /// <summary>
+    /// 周期天数。
+    /// </summary>
+    public int PeriodDays { get; set; } = 30;
+
+    /// <summary>
+    /// 排行项。
+    /// </summary>
+    public List<FinanceOverviewTopProductItemResponse> Items { get; set; } = [];
+}
+
+/// <summary>
+/// 财务概览响应。
+/// </summary>
+public sealed class FinanceOverviewDashboardResponse
+{
+    /// <summary>
+    /// 维度编码。
+    /// </summary>
+    public string Dimension { get; set; } = "tenant";
+
+    /// <summary>
+    /// 门店标识。
+    /// </summary>
+    public string? StoreId { get; set; }
+
+    /// <summary>
+    /// 今日营业额卡片。
+    /// </summary>
+    public FinanceOverviewKpiCardResponse TodayRevenue { get; set; } = new();
+
+    /// <summary>
+    /// 实收卡片。
+    /// </summary>
+    public FinanceOverviewKpiCardResponse ActualReceived { get; set; } = new();
+
+    /// <summary>
+    /// 退款卡片。
+    /// </summary>
+    public FinanceOverviewKpiCardResponse RefundAmount { get; set; } = new();
+
+    /// <summary>
+    /// 净收入卡片。
+    /// </summary>
+    public FinanceOverviewKpiCardResponse NetIncome { get; set; } = new();
+
+    /// <summary>
+    /// 可提现余额卡片。
+    /// </summary>
+    public FinanceOverviewKpiCardResponse WithdrawableBalance { get; set; } = new();
+
+    /// <summary>
+    /// 收入趋势。
+    /// </summary>
+    public FinanceOverviewIncomeTrendResponse IncomeTrend { get; set; } = new();
+
+    /// <summary>
+    /// 利润趋势。
+    /// </summary>
+    public FinanceOverviewProfitTrendResponse ProfitTrend { get; set; } = new();
+
+    /// <summary>
+    /// 收入构成。
+    /// </summary>
+    public FinanceOverviewIncomeCompositionResponse IncomeComposition { get; set; } = new();
+
+    /// <summary>
+    /// 成本构成。
+    /// </summary>
+    public FinanceOverviewCostCompositionResponse CostComposition { get; set; } = new();
+
+    /// <summary>
+    /// TOP 商品排行。
+    /// </summary>
+    public FinanceOverviewTopProductResponse TopProducts { get; set; } = new();
+}

src/Api/TakeoutSaaS.TenantApi/Contracts/Finance/FinanceSettlementContracts.cs

@@ -0,0 +1,247 @@
+namespace TakeoutSaaS.TenantApi.Contracts.Finance;
+
+/// <summary>
+/// 到账统计请求。
+/// </summary>
+public sealed class FinanceSettlementStatsRequest
+{
+    /// <summary>
+    /// 门店 ID。
+    /// </summary>
+    public string StoreId { get; set; } = string.Empty;
+}
+
+/// <summary>
+/// 到账筛选请求。
+/// </summary>
+public class FinanceSettlementFilterRequest
+{
+    /// <summary>
+    /// 门店 ID。
+    /// </summary>
+    public string StoreId { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 开始日期（yyyy-MM-dd）。
+    /// </summary>
+    public string? StartDate { get; set; }
+
+    /// <summary>
+    /// 结束日期（yyyy-MM-dd）。
+    /// </summary>
+    public string? EndDate { get; set; }
+
+    /// <summary>
+    /// 渠道（wechat/alipay）。
+    /// </summary>
+    public string? Channel { get; set; }
+}
+
+/// <summary>
+/// 到账列表请求。
+/// </summary>
+public sealed class FinanceSettlementListRequest : FinanceSettlementFilterRequest
+{
+    /// <summary>
+    /// 页码。
+    /// </summary>
+    public int Page { get; set; } = 1;
+
+    /// <summary>
+    /// 每页条数。
+    /// </summary>
+    public int PageSize { get; set; } = 20;
+}
+
+/// <summary>
+/// 到账明细请求。
+/// </summary>
+public sealed class FinanceSettlementDetailRequest
+{
+    /// <summary>
+    /// 门店 ID。
+    /// </summary>
+    public string StoreId { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 到账日期（yyyy-MM-dd）。
+    /// </summary>
+    public string ArrivedDate { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 渠道（wechat/alipay）。
+    /// </summary>
+    public string Channel { get; set; } = string.Empty;
+}
+
+/// <summary>
+/// 到账统计响应。
+/// </summary>
+public sealed class FinanceSettlementStatsResponse
+{
+    /// <summary>
+    /// 今日到账。
+    /// </summary>
+    public decimal TodayArrivedAmount { get; set; }
+
+    /// <summary>
+    /// 昨日到账。
+    /// </summary>
+    public decimal YesterdayArrivedAmount { get; set; }
+
+    /// <summary>
+    /// 本月到账。
+    /// </summary>
+    public decimal CurrentMonthArrivedAmount { get; set; }
+
+    /// <summary>
+    /// 本月交易笔数。
+    /// </summary>
+    public int CurrentMonthTransactionCount { get; set; }
+}
+
+/// <summary>
+/// 到账账户信息响应。
+/// </summary>
+public sealed class FinanceSettlementAccountResponse
+{
+    /// <summary>
+    /// 银行名称。
+    /// </summary>
+    public string BankName { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 开户名。
+    /// </summary>
+    public string BankAccountName { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 脱敏银行账号。
+    /// </summary>
+    public string BankAccountNoMasked { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 脱敏微信商户号。
+    /// </summary>
+    public string WechatMerchantNoMasked { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 脱敏支付宝 PID。
+    /// </summary>
+    public string AlipayPidMasked { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 结算周期文案。
+    /// </summary>
+    public string SettlementPeriodText { get; set; } = string.Empty;
+}
+
+/// <summary>
+/// 到账列表行响应。
+/// </summary>
+public sealed class FinanceSettlementListItemResponse
+{
+    /// <summary>
+    /// 到账日期。
+    /// </summary>
+    public string ArrivedDate { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 渠道编码。
+    /// </summary>
+    public string Channel { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 渠道文案。
+    /// </summary>
+    public string ChannelText { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 交易笔数。
+    /// </summary>
+    public int TransactionCount { get; set; }
+
+    /// <summary>
+    /// 到账金额。
+    /// </summary>
+    public decimal ArrivedAmount { get; set; }
+}
+
+/// <summary>
+/// 到账列表响应。
+/// </summary>
+public sealed class FinanceSettlementListResultResponse
+{
+    /// <summary>
+    /// 列表项。
+    /// </summary>
+    public List<FinanceSettlementListItemResponse> Items { get; set; } = [];
+
+    /// <summary>
+    /// 总数。
+    /// </summary>
+    public int Total { get; set; }
+
+    /// <summary>
+    /// 页码。
+    /// </summary>
+    public int Page { get; set; }
+
+    /// <summary>
+    /// 每页条数。
+    /// </summary>
+    public int PageSize { get; set; }
+}
+
+/// <summary>
+/// 到账明细行响应。
+/// </summary>
+public sealed class FinanceSettlementDetailItemResponse
+{
+    /// <summary>
+    /// 订单号。
+    /// </summary>
+    public string OrderNo { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 金额。
+    /// </summary>
+    public decimal Amount { get; set; }
+
+    /// <summary>
+    /// 支付时间。
+    /// </summary>
+    public string PaidAt { get; set; } = string.Empty;
+}
+
+/// <summary>
+/// 到账明细响应。
+/// </summary>
+public sealed class FinanceSettlementDetailResultResponse
+{
+    /// <summary>
+    /// 明细列表。
+    /// </summary>
+    public List<FinanceSettlementDetailItemResponse> Items { get; set; } = [];
+}
+
+/// <summary>
+/// 到账导出响应。
+/// </summary>
+public sealed class FinanceSettlementExportResponse
+{
+    /// <summary>
+    /// 文件名。
+    /// </summary>
+    public string FileName { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 文件内容（Base64）。
+    /// </summary>
+    public string FileContentBase64 { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 导出总数。
+    /// </summary>
+    public int TotalCount { get; set; }
+}

src/Api/TakeoutSaaS.TenantApi/Contracts/Finance/FinanceTransactionContracts.cs

@@ -0,0 +1,329 @@
+namespace TakeoutSaaS.TenantApi.Contracts.Finance;
+
+/// <summary>
+/// 交易流水筛选请求。
+/// </summary>
+public class FinanceTransactionFilterRequest
+{
+    /// <summary>
+    /// 门店 ID。
+    /// </summary>
+    public string StoreId { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 开始日期（yyyy-MM-dd）。
+    /// </summary>
+    public string? StartDate { get; set; }
+
+    /// <summary>
+    /// 结束日期（yyyy-MM-dd）。
+    /// </summary>
+    public string? EndDate { get; set; }
+
+    /// <summary>
+    /// 交易类型（income/refund/stored_card_recharge/point_redeem）。
+    /// </summary>
+    public string? Type { get; set; }
+
+    /// <summary>
+    /// 渠道（delivery/pickup/dine_in）。
+    /// </summary>
+    public string? Channel { get; set; }
+
+    /// <summary>
+    /// 支付方式（wechat/alipay/cash/card/balance）。
+    /// </summary>
+    public string? PaymentMethod { get; set; }
+
+    /// <summary>
+    /// 关键词（流水号/订单号）。
+    /// </summary>
+    public string? Keyword { get; set; }
+}
+
+/// <summary>
+/// 交易流水列表请求。
+/// </summary>
+public sealed class FinanceTransactionListRequest : FinanceTransactionFilterRequest
+{
+    /// <summary>
+    /// 页码。
+    /// </summary>
+    public int Page { get; set; } = 1;
+
+    /// <summary>
+    /// 每页条数。
+    /// </summary>
+    public int PageSize { get; set; } = 20;
+}
+
+/// <summary>
+/// 交易流水详情请求。
+/// </summary>
+public sealed class FinanceTransactionDetailRequest
+{
+    /// <summary>
+    /// 门店 ID。
+    /// </summary>
+    public string StoreId { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 交易标识（sourceType:sourceId）。
+    /// </summary>
+    public string TransactionId { get; set; } = string.Empty;
+}
+
+/// <summary>
+/// 交易流水列表结果。
+/// </summary>
+public sealed class FinanceTransactionListResultResponse
+{
+    /// <summary>
+    /// 列表。
+    /// </summary>
+    public List<FinanceTransactionListItemResponse> Items { get; set; } = [];
+
+    /// <summary>
+    /// 总数。
+    /// </summary>
+    public int Total { get; set; }
+
+    /// <summary>
+    /// 页码。
+    /// </summary>
+    public int Page { get; set; }
+
+    /// <summary>
+    /// 每页条数。
+    /// </summary>
+    public int PageSize { get; set; }
+
+    /// <summary>
+    /// 本页收入。
+    /// </summary>
+    public decimal PageIncomeAmount { get; set; }
+
+    /// <summary>
+    /// 本页退款。
+    /// </summary>
+    public decimal PageRefundAmount { get; set; }
+}
+
+/// <summary>
+/// 交易流水行。
+/// </summary>
+public sealed class FinanceTransactionListItemResponse
+{
+    /// <summary>
+    /// 交易标识。
+    /// </summary>
+    public string TransactionId { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 流水号。
+    /// </summary>
+    public string TransactionNo { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 关联订单号。
+    /// </summary>
+    public string? OrderNo { get; set; }
+
+    /// <summary>
+    /// 类型编码。
+    /// </summary>
+    public string Type { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 类型文案。
+    /// </summary>
+    public string TypeText { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 渠道文案。
+    /// </summary>
+    public string Channel { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 支付方式文案。
+    /// </summary>
+    public string PaymentMethod { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 交易金额。
+    /// </summary>
+    public decimal Amount { get; set; }
+
+    /// <summary>
+    /// 交易时间。
+    /// </summary>
+    public string OccurredAt { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 备注。
+    /// </summary>
+    public string Remark { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 是否收入。
+    /// </summary>
+    public bool IsIncome { get; set; }
+}
+
+/// <summary>
+/// 交易流水统计结果。
+/// </summary>
+public sealed class FinanceTransactionStatsResponse
+{
+    /// <summary>
+    /// 总收入。
+    /// </summary>
+    public decimal TotalIncome { get; set; }
+
+    /// <summary>
+    /// 总退款。
+    /// </summary>
+    public decimal TotalRefund { get; set; }
+
+    /// <summary>
+    /// 总笔数。
+    /// </summary>
+    public int TotalCount { get; set; }
+}
+
+/// <summary>
+/// 交易流水详情。
+/// </summary>
+public sealed class FinanceTransactionDetailResponse
+{
+    /// <summary>
+    /// 交易标识。
+    /// </summary>
+    public string TransactionId { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 流水号。
+    /// </summary>
+    public string TransactionNo { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 类型编码。
+    /// </summary>
+    public string Type { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 类型文案。
+    /// </summary>
+    public string TypeText { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 门店 ID。
+    /// </summary>
+    public string StoreId { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 关联订单号。
+    /// </summary>
+    public string? OrderNo { get; set; }
+
+    /// <summary>
+    /// 渠道文案。
+    /// </summary>
+    public string Channel { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 支付方式文案。
+    /// </summary>
+    public string PaymentMethod { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 交易金额。
+    /// </summary>
+    public decimal Amount { get; set; }
+
+    /// <summary>
+    /// 交易时间。
+    /// </summary>
+    public string OccurredAt { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 备注。
+    /// </summary>
+    public string Remark { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 顾客姓名。
+    /// </summary>
+    public string CustomerName { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 顾客手机号。
+    /// </summary>
+    public string CustomerPhone { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 退款单号。
+    /// </summary>
+    public string? RefundNo { get; set; }
+
+    /// <summary>
+    /// 退款原因。
+    /// </summary>
+    public string? RefundReason { get; set; }
+
+    /// <summary>
+    /// 会员名称。
+    /// </summary>
+    public string? MemberName { get; set; }
+
+    /// <summary>
+    /// 会员手机号。
+    /// </summary>
+    public string? MemberMobileMasked { get; set; }
+
+    /// <summary>
+    /// 充值金额。
+    /// </summary>
+    public decimal? RechargeAmount { get; set; }
+
+    /// <summary>
+    /// 赠送金额。
+    /// </summary>
+    public decimal? GiftAmount { get; set; }
+
+    /// <summary>
+    /// 到账金额。
+    /// </summary>
+    public decimal? ArrivedAmount { get; set; }
+
+    /// <summary>
+    /// 积分变动值。
+    /// </summary>
+    public int? PointChangeAmount { get; set; }
+
+    /// <summary>
+    /// 积分变动后余额。
+    /// </summary>
+    public int? PointBalanceAfterChange { get; set; }
+}
+
+/// <summary>
+/// 交易流水导出结果。
+/// </summary>
+public sealed class FinanceTransactionExportResponse
+{
+    /// <summary>
+    /// 文件名。
+    /// </summary>
+    public string FileName { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 文件内容（Base64）。
+    /// </summary>
+    public string FileContentBase64 { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 导出总数。
+    /// </summary>
+    public int TotalCount { get; set; }
+}

src/Api/TakeoutSaaS.TenantApi/Contracts/Member/MemberMessageReachContracts.cs

@@ -0,0 +1,585 @@
+namespace TakeoutSaaS.TenantApi.Contracts.Member;
+
+/// <summary>
+/// 消息触达统计请求。
+/// </summary>
+public sealed class MemberMessageReachStatsRequest
+{
+    /// <summary>
+    /// 门店 ID（可选）。
+    /// </summary>
+    public string? StoreId { get; set; }
+}
+
+/// <summary>
+/// 消息列表请求。
+/// </summary>
+public sealed class MemberMessageReachListRequest
+{
+    /// <summary>
+    /// 状态过滤（draft/pending/sending/sent/failed）。
+    /// </summary>
+    public string? Status { get; set; }
+
+    /// <summary>
+    /// 渠道过滤（inapp/sms/wechat-mini）。
+    /// </summary>
+    public string? Channel { get; set; }
+
+    /// <summary>
+    /// 关键词（标题）。
+    /// </summary>
+    public string? Keyword { get; set; }
+
+    /// <summary>
+    /// 页码。
+    /// </summary>
+    public int Page { get; set; } = 1;
+
+    /// <summary>
+    /// 每页条数。
+    /// </summary>
+    public int PageSize { get; set; } = 10;
+}
+
+/// <summary>
+/// 消息详情请求。
+/// </summary>
+public sealed class MemberMessageReachDetailRequest
+{
+    /// <summary>
+    /// 消息 ID。
+    /// </summary>
+    public string MessageId { get; set; } = string.Empty;
+}
+
+/// <summary>
+/// 保存消息请求。
+/// </summary>
+public sealed class SaveMemberMessageReachRequest
+{
+    /// <summary>
+    /// 消息 ID（编辑时传）。
+    /// </summary>
+    public string? MessageId { get; set; }
+
+    /// <summary>
+    /// 门店 ID（可选）。
+    /// </summary>
+    public string? StoreId { get; set; }
+
+    /// <summary>
+    /// 模板 ID（可选）。
+    /// </summary>
+    public string? TemplateId { get; set; }
+
+    /// <summary>
+    /// 标题。
+    /// </summary>
+    public string Title { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 内容。
+    /// </summary>
+    public string Content { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 发送渠道。
+    /// </summary>
+    public List<string> Channels { get; set; } = [];
+
+    /// <summary>
+    /// 目标类型（all/tag）。
+    /// </summary>
+    public string AudienceType { get; set; } = "all";
+
+    /// <summary>
+    /// 目标标签。
+    /// </summary>
+    public List<string> AudienceTags { get; set; } = [];
+
+    /// <summary>
+    /// 发送时间类型（immediate/scheduled）。
+    /// </summary>
+    public string ScheduleType { get; set; } = "immediate";
+
+    /// <summary>
+    /// 定时发送时间（UTC 或本地时间，后端统一转 UTC）。
+    /// </summary>
+    public DateTime? ScheduledAt { get; set; }
+
+    /// <summary>
+    /// 提交动作（draft/send）。
+    /// </summary>
+    public string SubmitAction { get; set; } = "draft";
+}
+
+/// <summary>
+/// 删除消息请求。
+/// </summary>
+public sealed class DeleteMemberMessageReachRequest
+{
+    /// <summary>
+    /// 消息 ID。
+    /// </summary>
+    public string MessageId { get; set; } = string.Empty;
+}
+
+/// <summary>
+/// 估算人群请求。
+/// </summary>
+public sealed class MemberMessageAudienceEstimateRequest
+{
+    /// <summary>
+    /// 目标类型（all/tag）。
+    /// </summary>
+    public string AudienceType { get; set; } = "all";
+
+    /// <summary>
+    /// 标签。
+    /// </summary>
+    public List<string> Tags { get; set; } = [];
+}
+
+/// <summary>
+/// 模板列表请求。
+/// </summary>
+public sealed class MemberMessageTemplateListRequest
+{
+    /// <summary>
+    /// 模板分类（marketing/notice/recall）。
+    /// </summary>
+    public string? Category { get; set; }
+
+    /// <summary>
+    /// 关键词（模板名称）。
+    /// </summary>
+    public string? Keyword { get; set; }
+
+    /// <summary>
+    /// 页码。
+    /// </summary>
+    public int Page { get; set; } = 1;
+
+    /// <summary>
+    /// 每页条数。
+    /// </summary>
+    public int PageSize { get; set; } = 10;
+}
+
+/// <summary>
+/// 模板详情请求。
+/// </summary>
+public sealed class MemberMessageTemplateDetailRequest
+{
+    /// <summary>
+    /// 模板 ID。
+    /// </summary>
+    public string TemplateId { get; set; } = string.Empty;
+}
+
+/// <summary>
+/// 保存模板请求。
+/// </summary>
+public sealed class SaveMemberMessageTemplateRequest
+{
+    /// <summary>
+    /// 模板 ID（编辑时传）。
+    /// </summary>
+    public string? TemplateId { get; set; }
+
+    /// <summary>
+    /// 模板名称。
+    /// </summary>
+    public string Name { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 模板分类（marketing/notice/recall）。
+    /// </summary>
+    public string Category { get; set; } = "notice";
+
+    /// <summary>
+    /// 模板内容。
+    /// </summary>
+    public string Content { get; set; } = string.Empty;
+}
+
+/// <summary>
+/// 删除模板请求。
+/// </summary>
+public sealed class DeleteMemberMessageTemplateRequest
+{
+    /// <summary>
+    /// 模板 ID。
+    /// </summary>
+    public string TemplateId { get; set; } = string.Empty;
+}
+
+/// <summary>
+/// 消息触达统计响应。
+/// </summary>
+public sealed class MemberMessageReachStatsResponse
+{
+    /// <summary>
+    /// 本月发送条数。
+    /// </summary>
+    public int MonthlySentCount { get; set; }
+
+    /// <summary>
+    /// 触达人数。
+    /// </summary>
+    public int ReachMemberCount { get; set; }
+
+    /// <summary>
+    /// 打开率（百分比）。
+    /// </summary>
+    public decimal OpenRate { get; set; }
+
+    /// <summary>
+    /// 转化率（百分比）。
+    /// </summary>
+    public decimal ConversionRate { get; set; }
+}
+
+/// <summary>
+/// 消息列表项响应。
+/// </summary>
+public sealed class MemberMessageReachListItemResponse
+{
+    /// <summary>
+    /// 消息 ID。
+    /// </summary>
+    public string MessageId { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 标题。
+    /// </summary>
+    public string Title { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 渠道。
+    /// </summary>
+    public List<string> Channels { get; set; } = [];
+
+    /// <summary>
+    /// 目标文案。
+    /// </summary>
+    public string AudienceText { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 预计触达人数。
+    /// </summary>
+    public int EstimatedReachCount { get; set; }
+
+    /// <summary>
+    /// 状态。
+    /// </summary>
+    public string Status { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 发送时间（yyyy-MM-dd HH:mm:ss）。
+    /// </summary>
+    public string? SentAt { get; set; }
+
+    /// <summary>
+    /// 定时发送时间（yyyy-MM-dd HH:mm:ss）。
+    /// </summary>
+    public string? ScheduledAt { get; set; }
+
+    /// <summary>
+    /// 打开率（百分比）。
+    /// </summary>
+    public decimal OpenRate { get; set; }
+
+    /// <summary>
+    /// 转化率（百分比）。
+    /// </summary>
+    public decimal ConversionRate { get; set; }
+}
+
+/// <summary>
+/// 消息列表响应。
+/// </summary>
+public sealed class MemberMessageReachListResultResponse
+{
+    /// <summary>
+    /// 列表。
+    /// </summary>
+    public List<MemberMessageReachListItemResponse> Items { get; set; } = [];
+
+    /// <summary>
+    /// 页码。
+    /// </summary>
+    public int Page { get; set; }
+
+    /// <summary>
+    /// 每页条数。
+    /// </summary>
+    public int PageSize { get; set; }
+
+    /// <summary>
+    /// 总数。
+    /// </summary>
+    public int TotalCount { get; set; }
+}
+
+/// <summary>
+/// 收件明细响应。
+/// </summary>
+public sealed class MemberMessageReachRecipientResponse
+{
+    /// <summary>
+    /// 会员 ID。
+    /// </summary>
+    public string MemberId { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 渠道。
+    /// </summary>
+    public string Channel { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 状态。
+    /// </summary>
+    public string Status { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 手机号。
+    /// </summary>
+    public string? Mobile { get; set; }
+
+    /// <summary>
+    /// OpenId。
+    /// </summary>
+    public string? OpenId { get; set; }
+
+    /// <summary>
+    /// 发送时间（yyyy-MM-dd HH:mm:ss）。
+    /// </summary>
+    public string? SentAt { get; set; }
+
+    /// <summary>
+    /// 已读时间（yyyy-MM-dd HH:mm:ss）。
+    /// </summary>
+    public string? ReadAt { get; set; }
+
+    /// <summary>
+    /// 转化时间（yyyy-MM-dd HH:mm:ss）。
+    /// </summary>
+    public string? ConvertedAt { get; set; }
+
+    /// <summary>
+    /// 错误信息。
+    /// </summary>
+    public string? ErrorMessage { get; set; }
+}
+
+/// <summary>
+/// 消息详情响应。
+/// </summary>
+public sealed class MemberMessageReachDetailResponse
+{
+    /// <summary>
+    /// 消息 ID。
+    /// </summary>
+    public string MessageId { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 模板 ID。
+    /// </summary>
+    public string? TemplateId { get; set; }
+
+    /// <summary>
+    /// 标题。
+    /// </summary>
+    public string Title { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 内容。
+    /// </summary>
+    public string Content { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 渠道。
+    /// </summary>
+    public List<string> Channels { get; set; } = [];
+
+    /// <summary>
+    /// 目标类型。
+    /// </summary>
+    public string AudienceType { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 目标标签。
+    /// </summary>
+    public List<string> AudienceTags { get; set; } = [];
+
+    /// <summary>
+    /// 目标文案。
+    /// </summary>
+    public string AudienceText { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 预计触达人数。
+    /// </summary>
+    public int EstimatedReachCount { get; set; }
+
+    /// <summary>
+    /// 发送时间类型。
+    /// </summary>
+    public string ScheduleType { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 定时发送时间（yyyy-MM-dd HH:mm:ss）。
+    /// </summary>
+    public string? ScheduledAt { get; set; }
+
+    /// <summary>
+    /// 发送状态。
+    /// </summary>
+    public string Status { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 实际发送时间（yyyy-MM-dd HH:mm:ss）。
+    /// </summary>
+    public string? SentAt { get; set; }
+
+    /// <summary>
+    /// 成功发送数。
+    /// </summary>
+    public int SentCount { get; set; }
+
+    /// <summary>
+    /// 已读数。
+    /// </summary>
+    public int ReadCount { get; set; }
+
+    /// <summary>
+    /// 转化数。
+    /// </summary>
+    public int ConvertedCount { get; set; }
+
+    /// <summary>
+    /// 打开率（百分比）。
+    /// </summary>
+    public decimal OpenRate { get; set; }
+
+    /// <summary>
+    /// 转化率（百分比）。
+    /// </summary>
+    public decimal ConversionRate { get; set; }
+
+    /// <summary>
+    /// 错误信息。
+    /// </summary>
+    public string? LastError { get; set; }
+
+    /// <summary>
+    /// 收件明细。
+    /// </summary>
+    public List<MemberMessageReachRecipientResponse> Recipients { get; set; } = [];
+}
+
+/// <summary>
+/// 消息调度元信息响应。
+/// </summary>
+public sealed class MemberMessageDispatchMetaResponse
+{
+    /// <summary>
+    /// 消息 ID。
+    /// </summary>
+    public string MessageId { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 状态。
+    /// </summary>
+    public string Status { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 时间类型。
+    /// </summary>
+    public string ScheduleType { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 定时发送时间（yyyy-MM-dd HH:mm:ss）。
+    /// </summary>
+    public string? ScheduledAt { get; set; }
+
+    /// <summary>
+    /// Hangfire 任务 ID。
+    /// </summary>
+    public string? HangfireJobId { get; set; }
+}
+
+/// <summary>
+/// 模板响应。
+/// </summary>
+public sealed class MemberMessageTemplateResponse
+{
+    /// <summary>
+    /// 模板 ID。
+    /// </summary>
+    public string TemplateId { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 名称。
+    /// </summary>
+    public string Name { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 分类。
+    /// </summary>
+    public string Category { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 内容。
+    /// </summary>
+    public string Content { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 使用次数。
+    /// </summary>
+    public int UsageCount { get; set; }
+
+    /// <summary>
+    /// 最近使用时间（yyyy-MM-dd HH:mm:ss）。
+    /// </summary>
+    public string? LastUsedAt { get; set; }
+}
+
+/// <summary>
+/// 模板列表响应。
+/// </summary>
+public sealed class MemberMessageTemplateListResultResponse
+{
+    /// <summary>
+    /// 列表。
+    /// </summary>
+    public List<MemberMessageTemplateResponse> Items { get; set; } = [];
+
+    /// <summary>
+    /// 页码。
+    /// </summary>
+    public int Page { get; set; }
+
+    /// <summary>
+    /// 每页条数。
+    /// </summary>
+    public int PageSize { get; set; }
+
+    /// <summary>
+    /// 总数。
+    /// </summary>
+    public int TotalCount { get; set; }
+}
+
+/// <summary>
+/// 目标人群估算响应。
+/// </summary>
+public sealed class MemberMessageAudienceEstimateResponse
+{
+    /// <summary>
+    /// 预计触达人数。
+    /// </summary>
+    public int ReachCount { get; set; }
+}

src/Api/TakeoutSaaS.TenantApi/Contracts/Store/StoreFeesContracts.cs

@@ -79,6 +79,10 @@ public sealed class StoreFeesSettingsDto
     /// </summary>
     public decimal BaseDeliveryFee { get; set; }
     /// <summary>
+    /// PlatformServiceRate。
+    /// </summary>
+    public decimal PlatformServiceRate { get; set; }
+    /// <summary>
     /// FreeDeliveryThreshold。
     /// </summary>
     public decimal? FreeDeliveryThreshold { get; set; }

src/Api/TakeoutSaaS.TenantApi/Controllers/FinanceCostController.cs

@@ -0,0 +1,270 @@
+using System.Globalization;
+using MediatR;
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Mvc;
+using TakeoutSaaS.Application.App.Finance.Cost.Commands;
+using TakeoutSaaS.Application.App.Finance.Cost.Dto;
+using TakeoutSaaS.Application.App.Finance.Cost.Queries;
+using TakeoutSaaS.Application.App.Stores.Services;
+using TakeoutSaaS.Domain.Finance.Enums;
+using TakeoutSaaS.Infrastructure.App.Persistence;
+using TakeoutSaaS.Module.Authorization.Attributes;
+using TakeoutSaaS.Shared.Abstractions.Constants;
+using TakeoutSaaS.Shared.Abstractions.Exceptions;
+using TakeoutSaaS.Shared.Abstractions.Results;
+using TakeoutSaaS.Shared.Web.Api;
+using TakeoutSaaS.TenantApi.Contracts.Finance;
+
+namespace TakeoutSaaS.TenantApi.Controllers;
+
+/// <summary>
+/// 财务中心成本管理。
+/// </summary>
+[ApiVersion("1.0")]
+[Authorize]
+[Route("api/tenant/v{version:apiVersion}/finance/cost")]
+public sealed class FinanceCostController(
+    IMediator mediator,
+    TakeoutAppDbContext dbContext,
+    StoreContextService storeContextService)
+    : BaseApiController
+{
+    private const string ViewPermission = "tenant:finance:cost:view";
+    private const string ManagePermission = "tenant:finance:cost:manage";
+
+    /// <summary>
+    /// 查询成本录入数据。
+    /// </summary>
+    [HttpGet("entry")]
+    [PermissionAuthorize(ViewPermission, ManagePermission)]
+    [ProducesResponseType(typeof(ApiResponse<FinanceCostEntryResponse>), StatusCodes.Status200OK)]
+    public async Task<ApiResponse<FinanceCostEntryResponse>> Entry(
+        [FromQuery] FinanceCostEntryRequest request,
+        CancellationToken cancellationToken)
+    {
+        // 1. 解析维度与作用域。
+        var scope = await ParseScopeAsync(request, cancellationToken);
+
+        // 2. 查询录入数据并映射响应。
+        var result = await mediator.Send(new GetFinanceCostEntryQuery
+        {
+            Dimension = scope.Dimension,
+            StoreId = scope.StoreId,
+            CostMonth = scope.CostMonth
+        }, cancellationToken);
+
+        return ApiResponse<FinanceCostEntryResponse>.Ok(MapEntry(result));
+    }
+
+    /// <summary>
+    /// 保存成本录入数据。
+    /// </summary>
+    [HttpPost("entry/save")]
+    [PermissionAuthorize(ManagePermission)]
+    [ProducesResponseType(typeof(ApiResponse<FinanceCostEntryResponse>), StatusCodes.Status200OK)]
+    public async Task<ApiResponse<FinanceCostEntryResponse>> SaveEntry(
+        [FromBody] SaveFinanceCostEntryRequest request,
+        CancellationToken cancellationToken)
+    {
+        // 1. 解析维度与作用域。
+        var scope = await ParseScopeAsync(request, cancellationToken);
+
+        // 2. 发起保存命令并映射响应。
+        var result = await mediator.Send(new SaveFinanceCostEntryCommand
+        {
+            Dimension = scope.Dimension,
+            StoreId = scope.StoreId,
+            CostMonth = scope.CostMonth,
+            Categories = (request.Categories ?? [])
+                .Select(MapSaveCategory)
+                .ToList()
+        }, cancellationToken);
+
+        return ApiResponse<FinanceCostEntryResponse>.Ok(MapEntry(result));
+    }
+
+    /// <summary>
+    /// 查询成本分析数据。
+    /// </summary>
+    [HttpGet("analysis")]
+    [PermissionAuthorize(ViewPermission, ManagePermission)]
+    [ProducesResponseType(typeof(ApiResponse<FinanceCostAnalysisResponse>), StatusCodes.Status200OK)]
+    public async Task<ApiResponse<FinanceCostAnalysisResponse>> Analysis(
+        [FromQuery] FinanceCostAnalysisRequest request,
+        CancellationToken cancellationToken)
+    {
+        // 1. 解析维度与作用域。
+        var scope = await ParseScopeAsync(request, cancellationToken);
+
+        // 2. 查询分析数据并映射响应。
+        var result = await mediator.Send(new GetFinanceCostAnalysisQuery
+        {
+            Dimension = scope.Dimension,
+            StoreId = scope.StoreId,
+            CostMonth = scope.CostMonth,
+            TrendMonthCount = Math.Clamp(request.TrendMonthCount, 3, 12)
+        }, cancellationToken);
+
+        return ApiResponse<FinanceCostAnalysisResponse>.Ok(MapAnalysis(result));
+    }
+
+    private async Task<(FinanceCostDimension Dimension, long? StoreId, DateTime CostMonth)> ParseScopeAsync(
+        FinanceCostScopeRequest request,
+        CancellationToken cancellationToken)
+    {
+        var dimension = ParseDimension(request.Dimension);
+        var costMonth = ParseMonthOrDefault(request.Month);
+
+        if (dimension == FinanceCostDimension.Tenant)
+        {
+            return (dimension, null, costMonth);
+        }
+
+        var storeId = StoreApiHelpers.ParseRequiredSnowflake(request.StoreId, nameof(request.StoreId));
+        await EnsureStoreAccessibleAsync(storeId, cancellationToken);
+        return (dimension, storeId, costMonth);
+    }
+
+    private async Task EnsureStoreAccessibleAsync(long storeId, CancellationToken cancellationToken)
+    {
+        var (tenantId, merchantId) = StoreApiHelpers.GetTenantMerchantContext(storeContextService);
+        await StoreApiHelpers.EnsureStoreAccessibleAsync(dbContext, tenantId, merchantId, storeId, cancellationToken);
+    }
+
+    private static FinanceCostDimension ParseDimension(string? value)
+    {
+        var normalized = (value ?? string.Empty).Trim().ToLowerInvariant();
+        return normalized switch
+        {
+            "" or "tenant" => FinanceCostDimension.Tenant,
+            "store" => FinanceCostDimension.Store,
+            _ => throw new BusinessException(ErrorCodes.BadRequest, "dimension 非法")
+        };
+    }
+
+    private static DateTime ParseMonthOrDefault(string? value)
+    {
+        if (string.IsNullOrWhiteSpace(value))
+        {
+            var utcNow = DateTime.UtcNow;
+            return new DateTime(utcNow.Year, utcNow.Month, 1, 0, 0, 0, DateTimeKind.Utc);
+        }
+
+        if (DateTime.TryParseExact(
+                value.Trim(),
+                "yyyy-MM",
+                CultureInfo.InvariantCulture,
+                DateTimeStyles.None,
+                out var parsed))
+        {
+            return new DateTime(parsed.Year, parsed.Month, 1, 0, 0, 0, DateTimeKind.Utc);
+        }
+
+        throw new BusinessException(ErrorCodes.BadRequest, "month 格式必须为 yyyy-MM");
+    }
+
+    private static FinanceCostCategory ParseCategory(string? value)
+    {
+        var normalized = (value ?? string.Empty).Trim().ToLowerInvariant();
+        return normalized switch
+        {
+            "food" => FinanceCostCategory.FoodMaterial,
+            "labor" => FinanceCostCategory.Labor,
+            "fixed" => FinanceCostCategory.FixedExpense,
+            "packaging" => FinanceCostCategory.PackagingConsumable,
+            _ => throw new BusinessException(ErrorCodes.BadRequest, "category 非法")
+        };
+    }
+
+    private static SaveFinanceCostCategoryCommandItem MapSaveCategory(SaveFinanceCostCategoryRequest source)
+    {
+        return new SaveFinanceCostCategoryCommandItem
+        {
+            Category = ParseCategory(source.Category),
+            TotalAmount = source.TotalAmount,
+            Items = (source.Items ?? [])
+                .Select(item => new SaveFinanceCostDetailCommandItem
+                {
+                    ItemId = StoreApiHelpers.ParseSnowflakeOrNull(item.ItemId),
+                    ItemName = item.ItemName,
+                    Amount = item.Amount,
+                    Quantity = item.Quantity,
+                    UnitPrice = item.UnitPrice,
+                    SortOrder = item.SortOrder
+                })
+                .ToList()
+        };
+    }
+
+    private static FinanceCostEntryResponse MapEntry(FinanceCostEntryDto source)
+    {
+        return new FinanceCostEntryResponse
+        {
+            Dimension = source.Dimension,
+            StoreId = source.StoreId,
+            Month = source.Month,
+            MonthRevenue = source.MonthRevenue,
+            TotalCost = source.TotalCost,
+            CostRate = source.CostRate,
+            Categories = source.Categories.Select(category => new FinanceCostEntryCategoryResponse
+            {
+                Category = category.Category,
+                CategoryText = category.CategoryText,
+                TotalAmount = category.TotalAmount,
+                Percentage = category.Percentage,
+                Items = category.Items.Select(item => new FinanceCostEntryDetailResponse
+                {
+                    ItemId = item.ItemId,
+                    ItemName = item.ItemName,
+                    Amount = item.Amount,
+                    Quantity = item.Quantity,
+                    UnitPrice = item.UnitPrice,
+                    SortOrder = item.SortOrder
+                }).ToList()
+            }).ToList()
+        };
+    }
+
+    private static FinanceCostAnalysisResponse MapAnalysis(FinanceCostAnalysisDto source)
+    {
+        return new FinanceCostAnalysisResponse
+        {
+            Dimension = source.Dimension,
+            StoreId = source.StoreId,
+            Month = source.Month,
+            Stats = new FinanceCostAnalysisStatsResponse
+            {
+                TotalCost = source.Stats.TotalCost,
+                FoodCostRate = source.Stats.FoodCostRate,
+                AverageCostPerPaidOrder = source.Stats.AverageCostPerPaidOrder,
+                MonthOnMonthChangeRate = source.Stats.MonthOnMonthChangeRate,
+                Revenue = source.Stats.Revenue,
+                PaidOrderCount = source.Stats.PaidOrderCount
+            },
+            Trend = source.Trend.Select(item => new FinanceCostTrendPointResponse
+            {
+                Month = item.Month,
+                TotalCost = item.TotalCost,
+                Revenue = item.Revenue,
+                CostRate = item.CostRate
+            }).ToList(),
+            Composition = source.Composition.Select(item => new FinanceCostCompositionResponse
+            {
+                Category = item.Category,
+                CategoryText = item.CategoryText,
+                Amount = item.Amount,
+                Percentage = item.Percentage
+            }).ToList(),
+            DetailRows = source.DetailRows.Select(item => new FinanceCostMonthlyDetailResponse
+            {
+                Month = item.Month,
+                FoodAmount = item.FoodAmount,
+                LaborAmount = item.LaborAmount,
+                FixedAmount = item.FixedAmount,
+                PackagingAmount = item.PackagingAmount,
+                TotalCost = item.TotalCost,
+                CostRate = item.CostRate
+            }).ToList()
+        };
+    }
+}

src/Api/TakeoutSaaS.TenantApi/Controllers/FinanceInvoiceController.cs

@@ -0,0 +1,308 @@
+using System.Globalization;
+using MediatR;
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Mvc;
+using TakeoutSaaS.Application.App.Finance.Invoice.Commands;
+using TakeoutSaaS.Application.App.Finance.Invoice.Dto;
+using TakeoutSaaS.Application.App.Finance.Invoice.Queries;
+using TakeoutSaaS.Domain.Tenants.Enums;
+using TakeoutSaaS.Module.Authorization.Attributes;
+using TakeoutSaaS.Shared.Abstractions.Constants;
+using TakeoutSaaS.Shared.Abstractions.Exceptions;
+using TakeoutSaaS.Shared.Abstractions.Results;
+using TakeoutSaaS.Shared.Web.Api;
+using TakeoutSaaS.TenantApi.Contracts.Finance;
+
+namespace TakeoutSaaS.TenantApi.Controllers;
+
+/// <summary>
+/// 财务中心发票管理。
+/// </summary>
+[ApiVersion("1.0")]
+[Authorize]
+[Route("api/tenant/v{version:apiVersion}/finance/invoice")]
+public sealed class FinanceInvoiceController(IMediator mediator) : BaseApiController
+{
+    private const string ViewPermission = "tenant:finance:invoice:view";
+    private const string IssuePermission = "tenant:finance:invoice:issue";
+    private const string VoidPermission = "tenant:finance:invoice:void";
+    private const string SettingsPermission = "tenant:finance:invoice:settings";
+
+    /// <summary>
+    /// 查询发票设置详情。
+    /// </summary>
+    [HttpGet("settings/detail")]
+    [PermissionAuthorize(ViewPermission, SettingsPermission)]
+    [ProducesResponseType(typeof(ApiResponse<FinanceInvoiceSettingResponse>), StatusCodes.Status200OK)]
+    public async Task<ApiResponse<FinanceInvoiceSettingResponse>> SettingsDetail(CancellationToken cancellationToken)
+    {
+        var result = await mediator.Send(new GetFinanceInvoiceSettingDetailQuery(), cancellationToken);
+        return ApiResponse<FinanceInvoiceSettingResponse>.Ok(MapSetting(result));
+    }
+
+    /// <summary>
+    /// 保存发票设置。
+    /// </summary>
+    [HttpPost("settings/save")]
+    [PermissionAuthorize(SettingsPermission)]
+    [ProducesResponseType(typeof(ApiResponse<FinanceInvoiceSettingResponse>), StatusCodes.Status200OK)]
+    public async Task<ApiResponse<FinanceInvoiceSettingResponse>> SettingsSave(
+        [FromBody] FinanceInvoiceSettingSaveRequest request,
+        CancellationToken cancellationToken)
+    {
+        var result = await mediator.Send(new SaveFinanceInvoiceSettingCommand
+        {
+            CompanyName = request.CompanyName,
+            TaxpayerNumber = request.TaxpayerNumber,
+            RegisteredAddress = request.RegisteredAddress,
+            RegisteredPhone = request.RegisteredPhone,
+            BankName = request.BankName,
+            BankAccount = request.BankAccount,
+            EnableElectronicNormalInvoice = request.EnableElectronicNormalInvoice,
+            EnableElectronicSpecialInvoice = request.EnableElectronicSpecialInvoice,
+            EnableAutoIssue = request.EnableAutoIssue,
+            AutoIssueMaxAmount = request.AutoIssueMaxAmount
+        }, cancellationToken);
+
+        return ApiResponse<FinanceInvoiceSettingResponse>.Ok(MapSetting(result));
+    }
+
+    /// <summary>
+    /// 查询发票记录分页。
+    /// </summary>
+    [HttpGet("record/list")]
+    [PermissionAuthorize(ViewPermission, IssuePermission, VoidPermission)]
+    [ProducesResponseType(typeof(ApiResponse<FinanceInvoiceRecordListResultResponse>), StatusCodes.Status200OK)]
+    public async Task<ApiResponse<FinanceInvoiceRecordListResultResponse>> RecordList(
+        [FromQuery] FinanceInvoiceRecordListRequest request,
+        CancellationToken cancellationToken)
+    {
+        var result = await mediator.Send(new GetFinanceInvoiceRecordListQuery
+        {
+            StartDateUtc = ParseDateOrNull(request.StartDate, nameof(request.StartDate)),
+            EndDateUtc = ParseDateOrNull(request.EndDate, nameof(request.EndDate)),
+            Status = ParseStatusOrNull(request.Status),
+            InvoiceType = ParseInvoiceTypeOrNull(request.InvoiceType),
+            Keyword = request.Keyword,
+            Page = request.Page,
+            PageSize = request.PageSize
+        }, cancellationToken);
+
+        return ApiResponse<FinanceInvoiceRecordListResultResponse>.Ok(new FinanceInvoiceRecordListResultResponse
+        {
+            Items = result.Items.Select(MapRecord).ToList(),
+            Page = result.Page,
+            PageSize = result.PageSize,
+            TotalCount = result.TotalCount,
+            Stats = new FinanceInvoiceStatsResponse
+            {
+                CurrentMonthIssuedAmount = result.Stats.CurrentMonthIssuedAmount,
+                CurrentMonthIssuedCount = result.Stats.CurrentMonthIssuedCount,
+                PendingCount = result.Stats.PendingCount,
+                VoidedCount = result.Stats.VoidedCount
+            }
+        });
+    }
+
+    /// <summary>
+    /// 查询发票记录详情。
+    /// </summary>
+    [HttpGet("record/detail")]
+    [PermissionAuthorize(ViewPermission, IssuePermission, VoidPermission)]
+    [ProducesResponseType(typeof(ApiResponse<FinanceInvoiceRecordDetailResponse>), StatusCodes.Status200OK)]
+    public async Task<ApiResponse<FinanceInvoiceRecordDetailResponse>> RecordDetail(
+        [FromQuery] FinanceInvoiceRecordDetailRequest request,
+        CancellationToken cancellationToken)
+    {
+        var result = await mediator.Send(new GetFinanceInvoiceRecordDetailQuery
+        {
+            RecordId = StoreApiHelpers.ParseRequiredSnowflake(request.RecordId, nameof(request.RecordId))
+        }, cancellationToken);
+
+        return ApiResponse<FinanceInvoiceRecordDetailResponse>.Ok(MapRecordDetail(result));
+    }
+
+    /// <summary>
+    /// 发票开票。
+    /// </summary>
+    [HttpPost("record/issue")]
+    [PermissionAuthorize(IssuePermission)]
+    [ProducesResponseType(typeof(ApiResponse<FinanceInvoiceIssueResultResponse>), StatusCodes.Status200OK)]
+    public async Task<ApiResponse<FinanceInvoiceIssueResultResponse>> RecordIssue(
+        [FromBody] FinanceInvoiceRecordIssueRequest request,
+        CancellationToken cancellationToken)
+    {
+        var result = await mediator.Send(new IssueFinanceInvoiceRecordCommand
+        {
+            RecordId = StoreApiHelpers.ParseRequiredSnowflake(request.RecordId, nameof(request.RecordId)),
+            ContactEmail = request.ContactEmail,
+            IssueRemark = request.IssueRemark
+        }, cancellationToken);
+
+        return ApiResponse<FinanceInvoiceIssueResultResponse>.Ok(MapIssueResult(result));
+    }
+
+    /// <summary>
+    /// 作废发票。
+    /// </summary>
+    [HttpPost("record/void")]
+    [PermissionAuthorize(VoidPermission)]
+    [ProducesResponseType(typeof(ApiResponse<FinanceInvoiceRecordDetailResponse>), StatusCodes.Status200OK)]
+    public async Task<ApiResponse<FinanceInvoiceRecordDetailResponse>> RecordVoid(
+        [FromBody] FinanceInvoiceRecordVoidRequest request,
+        CancellationToken cancellationToken)
+    {
+        var result = await mediator.Send(new VoidFinanceInvoiceRecordCommand
+        {
+            RecordId = StoreApiHelpers.ParseRequiredSnowflake(request.RecordId, nameof(request.RecordId)),
+            VoidReason = request.VoidReason
+        }, cancellationToken);
+
+        return ApiResponse<FinanceInvoiceRecordDetailResponse>.Ok(MapRecordDetail(result));
+    }
+
+    /// <summary>
+    /// 申请发票。
+    /// </summary>
+    [HttpPost("record/apply")]
+    [PermissionAuthorize(ViewPermission, IssuePermission)]
+    [ProducesResponseType(typeof(ApiResponse<FinanceInvoiceRecordDetailResponse>), StatusCodes.Status200OK)]
+    public async Task<ApiResponse<FinanceInvoiceRecordDetailResponse>> RecordApply(
+        [FromBody] FinanceInvoiceRecordApplyRequest request,
+        CancellationToken cancellationToken)
+    {
+        var result = await mediator.Send(new ApplyFinanceInvoiceRecordCommand
+        {
+            ApplicantName = request.ApplicantName,
+            CompanyName = request.CompanyName,
+            TaxpayerNumber = request.TaxpayerNumber,
+            InvoiceType = request.InvoiceType,
+            Amount = request.Amount,
+            OrderNo = request.OrderNo,
+            ContactEmail = request.ContactEmail,
+            ContactPhone = request.ContactPhone,
+            ApplyRemark = request.ApplyRemark,
+            AppliedAt = request.AppliedAt
+        }, cancellationToken);
+
+        return ApiResponse<FinanceInvoiceRecordDetailResponse>.Ok(MapRecordDetail(result));
+    }
+
+    private static DateTime? ParseDateOrNull(string? value, string fieldName)
+    {
+        return string.IsNullOrWhiteSpace(value)
+            ? null
+            : StoreApiHelpers.ParseDateOnly(value, fieldName);
+    }
+
+    private static TenantInvoiceStatus? ParseStatusOrNull(string? value)
+    {
+        var normalized = (value ?? string.Empty).Trim().ToLowerInvariant();
+        if (string.IsNullOrWhiteSpace(normalized))
+        {
+            return null;
+        }
+
+        return normalized switch
+        {
+            "pending" => TenantInvoiceStatus.Pending,
+            "issued" => TenantInvoiceStatus.Issued,
+            "voided" => TenantInvoiceStatus.Voided,
+            _ => throw new BusinessException(ErrorCodes.BadRequest, "status 参数不合法")
+        };
+    }
+
+    private static TenantInvoiceType? ParseInvoiceTypeOrNull(string? value)
+    {
+        var normalized = (value ?? string.Empty).Trim().ToLowerInvariant();
+        if (string.IsNullOrWhiteSpace(normalized))
+        {
+            return null;
+        }
+
+        return normalized switch
+        {
+            "normal" => TenantInvoiceType.Normal,
+            "special" => TenantInvoiceType.Special,
+            _ => throw new BusinessException(ErrorCodes.BadRequest, "invoiceType 参数不合法")
+        };
+    }
+
+    private static FinanceInvoiceSettingResponse MapSetting(FinanceInvoiceSettingDto source)
+    {
+        return new FinanceInvoiceSettingResponse
+        {
+            CompanyName = source.CompanyName,
+            TaxpayerNumber = source.TaxpayerNumber,
+            RegisteredAddress = source.RegisteredAddress,
+            RegisteredPhone = source.RegisteredPhone,
+            BankName = source.BankName,
+            BankAccount = source.BankAccount,
+            EnableElectronicNormalInvoice = source.EnableElectronicNormalInvoice,
+            EnableElectronicSpecialInvoice = source.EnableElectronicSpecialInvoice,
+            EnableAutoIssue = source.EnableAutoIssue,
+            AutoIssueMaxAmount = source.AutoIssueMaxAmount
+        };
+    }
+
+    private static FinanceInvoiceRecordResponse MapRecord(FinanceInvoiceRecordDto source)
+    {
+        return new FinanceInvoiceRecordResponse
+        {
+            RecordId = source.RecordId.ToString(),
+            InvoiceNo = source.InvoiceNo,
+            ApplicantName = source.ApplicantName,
+            CompanyName = source.CompanyName,
+            InvoiceType = source.InvoiceType,
+            InvoiceTypeText = source.InvoiceTypeText,
+            Amount = source.Amount,
+            OrderNo = source.OrderNo,
+            Status = source.Status,
+            StatusText = source.StatusText,
+            AppliedAt = source.AppliedAt.ToString("yyyy-MM-dd HH:mm:ss", CultureInfo.InvariantCulture)
+        };
+    }
+
+    private static FinanceInvoiceRecordDetailResponse MapRecordDetail(FinanceInvoiceRecordDetailDto source)
+    {
+        return new FinanceInvoiceRecordDetailResponse
+        {
+            RecordId = source.RecordId.ToString(),
+            InvoiceNo = source.InvoiceNo,
+            ApplicantName = source.ApplicantName,
+            CompanyName = source.CompanyName,
+            TaxpayerNumber = source.TaxpayerNumber,
+            InvoiceType = source.InvoiceType,
+            InvoiceTypeText = source.InvoiceTypeText,
+            Amount = source.Amount,
+            OrderNo = source.OrderNo,
+            ContactEmail = source.ContactEmail,
+            ContactPhone = source.ContactPhone,
+            ApplyRemark = source.ApplyRemark,
+            Status = source.Status,
+            StatusText = source.StatusText,
+            AppliedAt = source.AppliedAt.ToString("yyyy-MM-dd HH:mm:ss", CultureInfo.InvariantCulture),
+            IssuedAt = source.IssuedAt?.ToString("yyyy-MM-dd HH:mm:ss", CultureInfo.InvariantCulture),
+            IssuedByUserId = source.IssuedByUserId?.ToString(),
+            IssueRemark = source.IssueRemark,
+            VoidedAt = source.VoidedAt?.ToString("yyyy-MM-dd HH:mm:ss", CultureInfo.InvariantCulture),
+            VoidedByUserId = source.VoidedByUserId?.ToString(),
+            VoidReason = source.VoidReason
+        };
+    }
+
+    private static FinanceInvoiceIssueResultResponse MapIssueResult(FinanceInvoiceIssueResultDto source)
+    {
+        return new FinanceInvoiceIssueResultResponse
+        {
+            RecordId = source.RecordId.ToString(),
+            InvoiceNo = source.InvoiceNo,
+            CompanyName = source.CompanyName,
+            Amount = source.Amount,
+            ContactEmail = source.ContactEmail,
+            IssuedAt = source.IssuedAt.ToString("yyyy-MM-dd HH:mm:ss", CultureInfo.InvariantCulture),
+            Status = source.Status,
+            StatusText = source.StatusText
+        };
+    }
+}

src/Api/TakeoutSaaS.TenantApi/Controllers/FinanceOverviewController.cs

@@ -0,0 +1,171 @@
+using MediatR;
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Mvc;
+using TakeoutSaaS.Application.App.Finance.Overview.Dto;
+using TakeoutSaaS.Application.App.Finance.Overview.Queries;
+using TakeoutSaaS.Application.App.Stores.Services;
+using TakeoutSaaS.Domain.Finance.Enums;
+using TakeoutSaaS.Infrastructure.App.Persistence;
+using TakeoutSaaS.Module.Authorization.Attributes;
+using TakeoutSaaS.Shared.Abstractions.Constants;
+using TakeoutSaaS.Shared.Abstractions.Exceptions;
+using TakeoutSaaS.Shared.Abstractions.Results;
+using TakeoutSaaS.Shared.Web.Api;
+using TakeoutSaaS.TenantApi.Contracts.Finance;
+
+namespace TakeoutSaaS.TenantApi.Controllers;
+
+/// <summary>
+/// 财务中心概览驾驶舱。
+/// </summary>
+[ApiVersion("1.0")]
+[Authorize]
+[Route("api/tenant/v{version:apiVersion}/finance/overview")]
+public sealed class FinanceOverviewController(
+    IMediator mediator,
+    TakeoutAppDbContext dbContext,
+    StoreContextService storeContextService) : BaseApiController
+{
+    private const string ViewPermission = "tenant:finance:overview:view";
+
+    /// <summary>
+    /// 查询财务概览驾驶舱数据。
+    /// </summary>
+    [HttpGet("dashboard")]
+    [PermissionAuthorize(ViewPermission)]
+    [ProducesResponseType(typeof(ApiResponse<FinanceOverviewDashboardResponse>), StatusCodes.Status200OK)]
+    public async Task<ApiResponse<FinanceOverviewDashboardResponse>> Dashboard(
+        [FromQuery] FinanceOverviewDashboardRequest request,
+        CancellationToken cancellationToken)
+    {
+        // 1. 解析维度与作用域。
+        var dimension = ParseDimension(request.Dimension);
+        long? storeId = null;
+        if (dimension == FinanceCostDimension.Store)
+        {
+            storeId = StoreApiHelpers.ParseRequiredSnowflake(request.StoreId, nameof(request.StoreId));
+            await EnsureStoreAccessibleAsync(storeId.Value, cancellationToken);
+        }
+
+        // 2. 查询概览数据。
+        var dashboard = await mediator.Send(new GetFinanceOverviewDashboardQuery
+        {
+            Dimension = dimension,
+            StoreId = storeId,
+            CurrentUtc = DateTime.UtcNow
+        }, cancellationToken);
+
+        // 3. 映射响应并返回。
+        return ApiResponse<FinanceOverviewDashboardResponse>.Ok(MapDashboard(dashboard));
+    }
+
+    private async Task EnsureStoreAccessibleAsync(long storeId, CancellationToken cancellationToken)
+    {
+        var (tenantId, merchantId) = StoreApiHelpers.GetTenantMerchantContext(storeContextService);
+        await StoreApiHelpers.EnsureStoreAccessibleAsync(dbContext, tenantId, merchantId, storeId, cancellationToken);
+    }
+
+    private static FinanceCostDimension ParseDimension(string? value)
+    {
+        return (value ?? string.Empty).Trim().ToLowerInvariant() switch
+        {
+            "" or "tenant" => FinanceCostDimension.Tenant,
+            "store" => FinanceCostDimension.Store,
+            _ => throw new BusinessException(ErrorCodes.BadRequest, "dimension 非法")
+        };
+    }
+
+    private static FinanceOverviewDashboardResponse MapDashboard(FinanceOverviewDashboardDto source)
+    {
+        return new FinanceOverviewDashboardResponse
+        {
+            Dimension = source.Dimension,
+            StoreId = source.StoreId,
+            TodayRevenue = MapKpi(source.TodayRevenue),
+            ActualReceived = MapKpi(source.ActualReceived),
+            RefundAmount = MapKpi(source.RefundAmount),
+            NetIncome = MapKpi(source.NetIncome),
+            WithdrawableBalance = MapKpi(source.WithdrawableBalance),
+            IncomeTrend = new FinanceOverviewIncomeTrendResponse
+            {
+                Last7Days = source.IncomeTrend.Last7Days.Select(item => new FinanceOverviewIncomeTrendPointResponse
+                {
+                    Date = item.Date,
+                    DateLabel = item.DateLabel,
+                    Amount = item.Amount
+                }).ToList(),
+                Last30Days = source.IncomeTrend.Last30Days.Select(item => new FinanceOverviewIncomeTrendPointResponse
+                {
+                    Date = item.Date,
+                    DateLabel = item.DateLabel,
+                    Amount = item.Amount
+                }).ToList()
+            },
+            ProfitTrend = new FinanceOverviewProfitTrendResponse
+            {
+                Last7Days = source.ProfitTrend.Last7Days.Select(item => new FinanceOverviewProfitTrendPointResponse
+                {
+                    Date = item.Date,
+                    DateLabel = item.DateLabel,
+                    RevenueAmount = item.RevenueAmount,
+                    CostAmount = item.CostAmount,
+                    NetProfitAmount = item.NetProfitAmount
+                }).ToList(),
+                Last30Days = source.ProfitTrend.Last30Days.Select(item => new FinanceOverviewProfitTrendPointResponse
+                {
+                    Date = item.Date,
+                    DateLabel = item.DateLabel,
+                    RevenueAmount = item.RevenueAmount,
+                    CostAmount = item.CostAmount,
+                    NetProfitAmount = item.NetProfitAmount
+                }).ToList()
+            },
+            IncomeComposition = new FinanceOverviewIncomeCompositionResponse
+            {
+                TotalAmount = source.IncomeComposition.TotalAmount,
+                Items = source.IncomeComposition.Items.Select(item => new FinanceOverviewIncomeCompositionItemResponse
+                {
+                    Channel = item.Channel,
+                    ChannelText = item.ChannelText,
+                    Amount = item.Amount,
+                    Percentage = item.Percentage
+                }).ToList()
+            },
+            CostComposition = new FinanceOverviewCostCompositionResponse
+            {
+                TotalAmount = source.CostComposition.TotalAmount,
+                Items = source.CostComposition.Items.Select(item => new FinanceOverviewCostCompositionItemResponse
+                {
+                    Category = item.Category,
+                    CategoryText = item.CategoryText,
+                    Amount = item.Amount,
+                    Percentage = item.Percentage
+                }).ToList()
+            },
+            TopProducts = new FinanceOverviewTopProductResponse
+            {
+                PeriodDays = source.TopProducts.PeriodDays,
+                Items = source.TopProducts.Items.Select(item => new FinanceOverviewTopProductItemResponse
+                {
+                    Rank = item.Rank,
+                    ProductName = item.ProductName,
+                    SalesQuantity = item.SalesQuantity,
+                    RevenueAmount = item.RevenueAmount,
+                    Percentage = item.Percentage
+                }).ToList()
+            }
+        };
+    }
+
+    private static FinanceOverviewKpiCardResponse MapKpi(FinanceOverviewKpiCardDto source)
+    {
+        return new FinanceOverviewKpiCardResponse
+        {
+            Amount = source.Amount,
+            CompareAmount = source.CompareAmount,
+            ChangeRate = source.ChangeRate,
+            Trend = source.Trend,
+            CompareLabel = source.CompareLabel
+        };
+    }
+}

src/Api/TakeoutSaaS.TenantApi/Controllers/FinanceReportController.cs

@@ -0,0 +1,250 @@
+using MediatR;
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Mvc;
+using TakeoutSaaS.Application.App.Finance.Reports.Dto;
+using TakeoutSaaS.Application.App.Finance.Reports.Queries;
+using TakeoutSaaS.Application.App.Stores.Services;
+using TakeoutSaaS.Domain.Finance.Enums;
+using TakeoutSaaS.Infrastructure.App.Persistence;
+using TakeoutSaaS.Module.Authorization.Attributes;
+using TakeoutSaaS.Shared.Abstractions.Constants;
+using TakeoutSaaS.Shared.Abstractions.Exceptions;
+using TakeoutSaaS.Shared.Abstractions.Results;
+using TakeoutSaaS.Shared.Web.Api;
+using TakeoutSaaS.TenantApi.Contracts.Finance;
+
+namespace TakeoutSaaS.TenantApi.Controllers;
+
+/// <summary>
+/// 财务中心经营报表。
+/// </summary>
+[ApiVersion("1.0")]
+[Authorize]
+[Route("api/tenant/v{version:apiVersion}/finance/report")]
+public sealed class FinanceReportController(
+    IMediator mediator,
+    TakeoutAppDbContext dbContext,
+    StoreContextService storeContextService) : BaseApiController
+{
+    private const string ViewPermission = "tenant:statistics:report:view";
+    private const string ExportPermission = "tenant:statistics:report:export";
+
+    /// <summary>
+    /// 查询经营报表列表。
+    /// </summary>
+    [HttpGet("list")]
+    [PermissionAuthorize(ViewPermission)]
+    [ProducesResponseType(typeof(ApiResponse<FinanceBusinessReportListResultResponse>), StatusCodes.Status200OK)]
+    public async Task<ApiResponse<FinanceBusinessReportListResultResponse>> List(
+        [FromQuery] FinanceBusinessReportListRequest request,
+        CancellationToken cancellationToken)
+    {
+        // 1. 校验门店访问权限并解析查询参数。
+        var storeId = StoreApiHelpers.ParseRequiredSnowflake(request.StoreId, nameof(request.StoreId));
+        await EnsureStoreAccessibleAsync(storeId, cancellationToken);
+        var periodType = ParsePeriodType(request.PeriodType);
+
+        // 2. 发起查询并返回结果。
+        var result = await mediator.Send(new SearchFinanceBusinessReportListQuery
+        {
+            StoreId = storeId,
+            PeriodType = periodType,
+            Page = Math.Max(1, request.Page),
+            PageSize = Math.Clamp(request.PageSize, 1, 200)
+        }, cancellationToken);
+
+        return ApiResponse<FinanceBusinessReportListResultResponse>.Ok(new FinanceBusinessReportListResultResponse
+        {
+            Items = result.Items.Select(MapListItem).ToList(),
+            Total = result.Total,
+            Page = result.Page,
+            PageSize = result.PageSize
+        });
+    }
+
+    /// <summary>
+    /// 查询经营报表详情。
+    /// </summary>
+    [HttpGet("detail")]
+    [PermissionAuthorize(ViewPermission)]
+    [ProducesResponseType(typeof(ApiResponse<FinanceBusinessReportDetailResponse>), StatusCodes.Status200OK)]
+    public async Task<ApiResponse<FinanceBusinessReportDetailResponse>> Detail(
+        [FromQuery] FinanceBusinessReportDetailRequest request,
+        CancellationToken cancellationToken)
+    {
+        // 1. 校验门店访问权限并解析参数。
+        var storeId = StoreApiHelpers.ParseRequiredSnowflake(request.StoreId, nameof(request.StoreId));
+        await EnsureStoreAccessibleAsync(storeId, cancellationToken);
+        var reportId = StoreApiHelpers.ParseRequiredSnowflake(request.ReportId, nameof(request.ReportId));
+
+        // 2. 发起详情查询。
+        var detail = await mediator.Send(new GetFinanceBusinessReportDetailQuery
+        {
+            StoreId = storeId,
+            ReportId = reportId
+        }, cancellationToken);
+
+        if (detail is null)
+        {
+            return ApiResponse<FinanceBusinessReportDetailResponse>.Error(ErrorCodes.NotFound, "经营报表不存在");
+        }
+
+        return ApiResponse<FinanceBusinessReportDetailResponse>.Ok(MapDetail(detail));
+    }
+
+    /// <summary>
+    /// 导出单条报表 PDF。
+    /// </summary>
+    [HttpGet("export/pdf")]
+    [PermissionAuthorize(ExportPermission)]
+    [ProducesResponseType(typeof(ApiResponse<FinanceBusinessReportExportResponse>), StatusCodes.Status200OK)]
+    public async Task<ApiResponse<FinanceBusinessReportExportResponse>> ExportPdf(
+        [FromQuery] FinanceBusinessReportDetailRequest request,
+        CancellationToken cancellationToken)
+    {
+        // 1. 校验门店访问权限并解析参数。
+        var storeId = StoreApiHelpers.ParseRequiredSnowflake(request.StoreId, nameof(request.StoreId));
+        await EnsureStoreAccessibleAsync(storeId, cancellationToken);
+        var reportId = StoreApiHelpers.ParseRequiredSnowflake(request.ReportId, nameof(request.ReportId));
+
+        // 2. 执行导出。
+        var export = await mediator.Send(new ExportFinanceBusinessReportPdfQuery
+        {
+            StoreId = storeId,
+            ReportId = reportId
+        }, cancellationToken);
+
+        return ApiResponse<FinanceBusinessReportExportResponse>.Ok(MapExport(export));
+    }
+
+    /// <summary>
+    /// 导出单条报表 Excel。
+    /// </summary>
+    [HttpGet("export/excel")]
+    [PermissionAuthorize(ExportPermission)]
+    [ProducesResponseType(typeof(ApiResponse<FinanceBusinessReportExportResponse>), StatusCodes.Status200OK)]
+    public async Task<ApiResponse<FinanceBusinessReportExportResponse>> ExportExcel(
+        [FromQuery] FinanceBusinessReportDetailRequest request,
+        CancellationToken cancellationToken)
+    {
+        // 1. 校验门店访问权限并解析参数。
+        var storeId = StoreApiHelpers.ParseRequiredSnowflake(request.StoreId, nameof(request.StoreId));
+        await EnsureStoreAccessibleAsync(storeId, cancellationToken);
+        var reportId = StoreApiHelpers.ParseRequiredSnowflake(request.ReportId, nameof(request.ReportId));
+
+        // 2. 执行导出。
+        var export = await mediator.Send(new ExportFinanceBusinessReportExcelQuery
+        {
+            StoreId = storeId,
+            ReportId = reportId
+        }, cancellationToken);
+
+        return ApiResponse<FinanceBusinessReportExportResponse>.Ok(MapExport(export));
+    }
+
+    /// <summary>
+    /// 批量导出报表 ZIP（PDF + Excel）。
+    /// </summary>
+    [HttpGet("export/batch")]
+    [PermissionAuthorize(ExportPermission)]
+    [ProducesResponseType(typeof(ApiResponse<FinanceBusinessReportExportResponse>), StatusCodes.Status200OK)]
+    public async Task<ApiResponse<FinanceBusinessReportExportResponse>> ExportBatch(
+        [FromQuery] FinanceBusinessReportBatchExportRequest request,
+        CancellationToken cancellationToken)
+    {
+        // 1. 校验门店访问权限并解析参数。
+        var storeId = StoreApiHelpers.ParseRequiredSnowflake(request.StoreId, nameof(request.StoreId));
+        await EnsureStoreAccessibleAsync(storeId, cancellationToken);
+        var periodType = ParsePeriodType(request.PeriodType);
+
+        // 2. 执行批量导出。
+        var export = await mediator.Send(new ExportFinanceBusinessReportBatchQuery
+        {
+            StoreId = storeId,
+            PeriodType = periodType,
+            Page = Math.Max(1, request.Page),
+            PageSize = Math.Clamp(request.PageSize, 1, 200)
+        }, cancellationToken);
+
+        return ApiResponse<FinanceBusinessReportExportResponse>.Ok(MapExport(export));
+    }
+
+    private async Task EnsureStoreAccessibleAsync(long storeId, CancellationToken cancellationToken)
+    {
+        var (tenantId, merchantId) = StoreApiHelpers.GetTenantMerchantContext(storeContextService);
+        await StoreApiHelpers.EnsureStoreAccessibleAsync(dbContext, tenantId, merchantId, storeId, cancellationToken);
+    }
+
+    private static FinanceBusinessReportPeriodType ParsePeriodType(string? value)
+    {
+        return (value ?? string.Empty).Trim().ToLowerInvariant() switch
+        {
+            "" or "daily" => FinanceBusinessReportPeriodType.Daily,
+            "weekly" => FinanceBusinessReportPeriodType.Weekly,
+            "monthly" => FinanceBusinessReportPeriodType.Monthly,
+            _ => throw new BusinessException(ErrorCodes.BadRequest, "periodType 参数不合法")
+        };
+    }
+
+    private static FinanceBusinessReportListItemResponse MapListItem(FinanceBusinessReportListItemDto source)
+    {
+        return new FinanceBusinessReportListItemResponse
+        {
+            ReportId = source.ReportId,
+            DateText = source.DateText,
+            RevenueAmount = source.RevenueAmount,
+            OrderCount = source.OrderCount,
+            AverageOrderValue = source.AverageOrderValue,
+            RefundRatePercent = source.RefundRatePercent,
+            CostTotalAmount = source.CostTotalAmount,
+            NetProfitAmount = source.NetProfitAmount,
+            ProfitRatePercent = source.ProfitRatePercent,
+            Status = source.Status,
+            StatusText = source.StatusText,
+            CanDownload = source.CanDownload
+        };
+    }
+
+    private static FinanceBusinessReportDetailResponse MapDetail(FinanceBusinessReportDetailDto source)
+    {
+        return new FinanceBusinessReportDetailResponse
+        {
+            ReportId = source.ReportId,
+            Title = source.Title,
+            PeriodType = source.PeriodType,
+            Status = source.Status,
+            StatusText = source.StatusText,
+            Kpis = source.Kpis.Select(item => new FinanceBusinessReportKpiResponse
+            {
+                Key = item.Key,
+                Label = item.Label,
+                ValueText = item.ValueText,
+                YoyChangeRate = item.YoyChangeRate,
+                MomChangeRate = item.MomChangeRate
+            }).ToList(),
+            IncomeBreakdowns = source.IncomeBreakdowns.Select(MapBreakdown).ToList(),
+            CostBreakdowns = source.CostBreakdowns.Select(MapBreakdown).ToList()
+        };
+    }
+
+    private static FinanceBusinessReportBreakdownItemResponse MapBreakdown(FinanceBusinessReportBreakdownItemDto source)
+    {
+        return new FinanceBusinessReportBreakdownItemResponse
+        {
+            Key = source.Key,
+            Label = source.Label,
+            Amount = source.Amount,
+            RatioPercent = source.RatioPercent
+        };
+    }
+
+    private static FinanceBusinessReportExportResponse MapExport(FinanceBusinessReportExportDto source)
+    {
+        return new FinanceBusinessReportExportResponse
+        {
+            FileName = source.FileName,
+            FileContentBase64 = source.FileContentBase64,
+            TotalCount = source.TotalCount
+        };
+    }
+}

src/Api/TakeoutSaaS.TenantApi/Controllers/FinanceSettlementController.cs

@@ -0,0 +1,262 @@
+using System.Globalization;
+using MediatR;
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Mvc;
+using TakeoutSaaS.Application.App.Finance.Settlement.Dto;
+using TakeoutSaaS.Application.App.Finance.Settlement.Queries;
+using TakeoutSaaS.Application.App.Stores.Services;
+using TakeoutSaaS.Domain.Payments.Enums;
+using TakeoutSaaS.Infrastructure.App.Persistence;
+using TakeoutSaaS.Module.Authorization.Attributes;
+using TakeoutSaaS.Shared.Abstractions.Constants;
+using TakeoutSaaS.Shared.Abstractions.Exceptions;
+using TakeoutSaaS.Shared.Abstractions.Results;
+using TakeoutSaaS.Shared.Web.Api;
+using TakeoutSaaS.TenantApi.Contracts.Finance;
+
+namespace TakeoutSaaS.TenantApi.Controllers;
+
+/// <summary>
+/// 财务中心到账查询。
+/// </summary>
+[ApiVersion("1.0")]
+[Authorize]
+[Route("api/tenant/v{version:apiVersion}/finance/settlement")]
+public sealed class FinanceSettlementController(
+    IMediator mediator,
+    TakeoutAppDbContext dbContext,
+    StoreContextService storeContextService) : BaseApiController
+{
+    private const string ViewPermission = "tenant:finance:settlement:view";
+    private const string ExportPermission = "tenant:finance:settlement:export";
+
+    /// <summary>
+    /// 查询到账统计。
+    /// </summary>
+    [HttpGet("stats")]
+    [PermissionAuthorize(ViewPermission)]
+    [ProducesResponseType(typeof(ApiResponse<FinanceSettlementStatsResponse>), StatusCodes.Status200OK)]
+    public async Task<ApiResponse<FinanceSettlementStatsResponse>> Stats(
+        [FromQuery] FinanceSettlementStatsRequest request,
+        CancellationToken cancellationToken)
+    {
+        var storeId = StoreApiHelpers.ParseRequiredSnowflake(request.StoreId, nameof(request.StoreId));
+        await EnsureStoreAccessibleAsync(storeId, cancellationToken);
+
+        var stats = await mediator.Send(new GetFinanceSettlementStatsQuery
+        {
+            StoreId = storeId
+        }, cancellationToken);
+
+        return ApiResponse<FinanceSettlementStatsResponse>.Ok(new FinanceSettlementStatsResponse
+        {
+            TodayArrivedAmount = stats.TodayArrivedAmount,
+            YesterdayArrivedAmount = stats.YesterdayArrivedAmount,
+            CurrentMonthArrivedAmount = stats.CurrentMonthArrivedAmount,
+            CurrentMonthTransactionCount = stats.CurrentMonthTransactionCount
+        });
+    }
+
+    /// <summary>
+    /// 查询到账账户信息。
+    /// </summary>
+    [HttpGet("account")]
+    [PermissionAuthorize(ViewPermission)]
+    [ProducesResponseType(typeof(ApiResponse<FinanceSettlementAccountResponse>), StatusCodes.Status200OK)]
+    public async Task<ApiResponse<FinanceSettlementAccountResponse>> Account(
+        CancellationToken cancellationToken)
+    {
+        var account = await mediator.Send(new GetFinanceSettlementAccountQuery(), cancellationToken);
+        if (account is null)
+        {
+            return ApiResponse<FinanceSettlementAccountResponse>.Error(ErrorCodes.NotFound, "结算账户信息不存在");
+        }
+
+        return ApiResponse<FinanceSettlementAccountResponse>.Ok(new FinanceSettlementAccountResponse
+        {
+            BankName = account.BankName,
+            BankAccountName = account.BankAccountName,
+            BankAccountNoMasked = account.BankAccountNoMasked,
+            WechatMerchantNoMasked = account.WechatMerchantNoMasked,
+            AlipayPidMasked = account.AlipayPidMasked,
+            SettlementPeriodText = account.SettlementPeriodText
+        });
+    }
+
+    /// <summary>
+    /// 查询到账汇总列表。
+    /// </summary>
+    [HttpGet("list")]
+    [PermissionAuthorize(ViewPermission)]
+    [ProducesResponseType(typeof(ApiResponse<FinanceSettlementListResultResponse>), StatusCodes.Status200OK)]
+    public async Task<ApiResponse<FinanceSettlementListResultResponse>> List(
+        [FromQuery] FinanceSettlementListRequest request,
+        CancellationToken cancellationToken)
+    {
+        var parsed = await ParseFilterAsync(request, cancellationToken);
+
+        var result = await mediator.Send(new SearchFinanceSettlementListQuery
+        {
+            StoreId = parsed.StoreId,
+            StartAt = parsed.StartAt,
+            EndAt = parsed.EndAt,
+            PaymentMethod = parsed.PaymentMethod,
+            Page = Math.Max(1, request.Page),
+            PageSize = Math.Clamp(request.PageSize, 1, 200)
+        }, cancellationToken);
+
+        return ApiResponse<FinanceSettlementListResultResponse>.Ok(new FinanceSettlementListResultResponse
+        {
+            Items = result.Items.Select(MapListItem).ToList(),
+            Total = result.Total,
+            Page = result.Page,
+            PageSize = result.PageSize
+        });
+    }
+
+    /// <summary>
+    /// 查询到账明细（展开行）。
+    /// </summary>
+    [HttpGet("detail")]
+    [PermissionAuthorize(ViewPermission)]
+    [ProducesResponseType(typeof(ApiResponse<FinanceSettlementDetailResultResponse>), StatusCodes.Status200OK)]
+    public async Task<ApiResponse<FinanceSettlementDetailResultResponse>> Detail(
+        [FromQuery] FinanceSettlementDetailRequest request,
+        CancellationToken cancellationToken)
+    {
+        var storeId = StoreApiHelpers.ParseRequiredSnowflake(request.StoreId, nameof(request.StoreId));
+        await EnsureStoreAccessibleAsync(storeId, cancellationToken);
+
+        var arrivedDate = ParseRequiredDate(request.ArrivedDate, nameof(request.ArrivedDate));
+        var paymentMethod = ParseRequiredSettlementChannel(request.Channel);
+
+        var result = await mediator.Send(new GetFinanceSettlementDetailQuery
+        {
+            StoreId = storeId,
+            ArrivedDate = arrivedDate,
+            PaymentMethod = paymentMethod,
+            Take = 50
+        }, cancellationToken);
+
+        return ApiResponse<FinanceSettlementDetailResultResponse>.Ok(new FinanceSettlementDetailResultResponse
+        {
+            Items = result.Items.Select(MapDetailItem).ToList()
+        });
+    }
+
+    /// <summary>
+    /// 导出到账汇总 CSV。
+    /// </summary>
+    [HttpGet("export")]
+    [PermissionAuthorize(ExportPermission)]
+    [ProducesResponseType(typeof(ApiResponse<FinanceSettlementExportResponse>), StatusCodes.Status200OK)]
+    public async Task<ApiResponse<FinanceSettlementExportResponse>> Export(
+        [FromQuery] FinanceSettlementFilterRequest request,
+        CancellationToken cancellationToken)
+    {
+        var parsed = await ParseFilterAsync(request, cancellationToken);
+
+        var result = await mediator.Send(new ExportFinanceSettlementCsvQuery
+        {
+            StoreId = parsed.StoreId,
+            StartAt = parsed.StartAt,
+            EndAt = parsed.EndAt,
+            PaymentMethod = parsed.PaymentMethod
+        }, cancellationToken);
+
+        return ApiResponse<FinanceSettlementExportResponse>.Ok(new FinanceSettlementExportResponse
+        {
+            FileName = result.FileName,
+            FileContentBase64 = result.FileContentBase64,
+            TotalCount = result.TotalCount
+        });
+    }
+
+    private async Task<(long StoreId, DateTime? StartAt, DateTime? EndAt, PaymentMethod? PaymentMethod)> ParseFilterAsync(
+        FinanceSettlementFilterRequest request,
+        CancellationToken cancellationToken)
+    {
+        var storeId = StoreApiHelpers.ParseRequiredSnowflake(request.StoreId, nameof(request.StoreId));
+        await EnsureStoreAccessibleAsync(storeId, cancellationToken);
+
+        var startAt = ParseDateOrNull(request.StartDate);
+        var endAt = ParseDateOrNull(request.EndDate)?.AddDays(1);
+        if (startAt.HasValue && endAt.HasValue && startAt >= endAt)
+        {
+            throw new BusinessException(ErrorCodes.BadRequest, "开始日期不能晚于结束日期");
+        }
+
+        return (storeId, startAt, endAt, ParseOptionalSettlementChannel(request.Channel));
+    }
+
+    private async Task EnsureStoreAccessibleAsync(long storeId, CancellationToken cancellationToken)
+    {
+        var (tenantId, merchantId) = StoreApiHelpers.GetTenantMerchantContext(storeContextService);
+        await StoreApiHelpers.EnsureStoreAccessibleAsync(dbContext, tenantId, merchantId, storeId, cancellationToken);
+    }
+
+    private static DateTime ParseRequiredDate(string? value, string parameterName)
+    {
+        return ParseDateOrNull(value)
+            ?? throw new BusinessException(ErrorCodes.BadRequest, $"{parameterName} 必填，格式为 yyyy-MM-dd");
+    }
+
+    private static DateTime? ParseDateOrNull(string? value)
+    {
+        if (string.IsNullOrWhiteSpace(value))
+        {
+            return null;
+        }
+
+        if (DateTime.TryParseExact(
+                value,
+                "yyyy-MM-dd",
+                CultureInfo.InvariantCulture,
+                DateTimeStyles.None,
+                out var parsed))
+        {
+            return DateTime.SpecifyKind(parsed.Date, DateTimeKind.Utc);
+        }
+
+        throw new BusinessException(ErrorCodes.BadRequest, "日期格式必须为 yyyy-MM-dd");
+    }
+
+    private static PaymentMethod ParseRequiredSettlementChannel(string? channel)
+    {
+        return ParseOptionalSettlementChannel(channel)
+            ?? throw new BusinessException(ErrorCodes.BadRequest, "channel 必填，仅支持 wechat 或 alipay");
+    }
+
+    private static PaymentMethod? ParseOptionalSettlementChannel(string? channel)
+    {
+        return (channel ?? string.Empty).Trim().ToLowerInvariant() switch
+        {
+            "wechat" => PaymentMethod.WeChatPay,
+            "alipay" => PaymentMethod.Alipay,
+            "" => null,
+            _ => throw new BusinessException(ErrorCodes.BadRequest, "channel 仅支持 wechat 或 alipay")
+        };
+    }
+
+    private static FinanceSettlementListItemResponse MapListItem(FinanceSettlementListItemDto source)
+    {
+        return new FinanceSettlementListItemResponse
+        {
+            ArrivedDate = source.ArrivedDate.ToString("yyyy-MM-dd", CultureInfo.InvariantCulture),
+            Channel = source.Channel,
+            ChannelText = source.ChannelText,
+            TransactionCount = source.TransactionCount,
+            ArrivedAmount = source.ArrivedAmount
+        };
+    }
+
+    private static FinanceSettlementDetailItemResponse MapDetailItem(FinanceSettlementDetailItemDto source)
+    {
+        return new FinanceSettlementDetailItemResponse
+        {
+            OrderNo = source.OrderNo,
+            Amount = source.Amount,
+            PaidAt = source.PaidAt.ToString("yyyy-MM-dd HH:mm:ss", CultureInfo.InvariantCulture)
+        };
+    }
+}

src/Api/TakeoutSaaS.TenantApi/Controllers/FinanceTransactionController.cs

@@ -0,0 +1,343 @@
+using System.Globalization;
+using MediatR;
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Mvc;
+using TakeoutSaaS.Application.App.Finance.Transactions.Dto;
+using TakeoutSaaS.Application.App.Finance.Transactions.Queries;
+using TakeoutSaaS.Application.App.Stores.Services;
+using TakeoutSaaS.Domain.Finance.Enums;
+using TakeoutSaaS.Domain.Orders.Enums;
+using TakeoutSaaS.Domain.Payments.Enums;
+using TakeoutSaaS.Infrastructure.App.Persistence;
+using TakeoutSaaS.Module.Authorization.Attributes;
+using TakeoutSaaS.Shared.Abstractions.Constants;
+using TakeoutSaaS.Shared.Abstractions.Exceptions;
+using TakeoutSaaS.Shared.Abstractions.Results;
+using TakeoutSaaS.Shared.Web.Api;
+using TakeoutSaaS.TenantApi.Contracts.Finance;
+
+namespace TakeoutSaaS.TenantApi.Controllers;
+
+/// <summary>
+/// 财务中心交易流水。
+/// </summary>
+[ApiVersion("1.0")]
+[Authorize]
+[Route("api/tenant/v{version:apiVersion}/finance/transaction")]
+public sealed class FinanceTransactionController(
+    IMediator mediator,
+    TakeoutAppDbContext dbContext,
+    StoreContextService storeContextService) : BaseApiController
+{
+    private const string ViewPermission = "tenant:finance:transaction:view";
+    private const string DetailPermission = "tenant:finance:transaction:detail";
+    private const string ExportPermission = "tenant:finance:transaction:export";
+
+    /// <summary>
+    /// 查询交易流水列表。
+    /// </summary>
+    [HttpGet("list")]
+    [PermissionAuthorize(ViewPermission)]
+    [ProducesResponseType(typeof(ApiResponse<FinanceTransactionListResultResponse>), StatusCodes.Status200OK)]
+    public async Task<ApiResponse<FinanceTransactionListResultResponse>> List(
+        [FromQuery] FinanceTransactionListRequest request,
+        CancellationToken cancellationToken)
+    {
+        // 1. 解析并校验筛选参数。
+        var parsed = await ParseFilterAsync(request, cancellationToken);
+
+        // 2. 发起查询并映射响应。
+        var result = await mediator.Send(new SearchFinanceTransactionListQuery
+        {
+            StoreId = parsed.StoreId,
+            StartAt = parsed.StartAt,
+            EndAt = parsed.EndAt,
+            TransactionType = parsed.TransactionType,
+            DeliveryType = parsed.DeliveryType,
+            PaymentMethod = parsed.PaymentMethod,
+            Keyword = request.Keyword,
+            Page = Math.Max(1, request.Page),
+            PageSize = Math.Clamp(request.PageSize, 1, 200)
+        }, cancellationToken);
+
+        return ApiResponse<FinanceTransactionListResultResponse>.Ok(new FinanceTransactionListResultResponse
+        {
+            Items = result.Items.Select(MapListItem).ToList(),
+            Total = result.Total,
+            Page = result.Page,
+            PageSize = result.PageSize,
+            PageIncomeAmount = result.PageIncomeAmount,
+            PageRefundAmount = result.PageRefundAmount
+        });
+    }
+
+    /// <summary>
+    /// 查询交易流水统计。
+    /// </summary>
+    [HttpGet("stats")]
+    [PermissionAuthorize(ViewPermission)]
+    [ProducesResponseType(typeof(ApiResponse<FinanceTransactionStatsResponse>), StatusCodes.Status200OK)]
+    public async Task<ApiResponse<FinanceTransactionStatsResponse>> Stats(
+        [FromQuery] FinanceTransactionFilterRequest request,
+        CancellationToken cancellationToken)
+    {
+        // 1. 解析并校验筛选参数。
+        var parsed = await ParseFilterAsync(request, cancellationToken);
+
+        // 2. 发起查询并映射响应。
+        var result = await mediator.Send(new GetFinanceTransactionStatsQuery
+        {
+            StoreId = parsed.StoreId,
+            StartAt = parsed.StartAt,
+            EndAt = parsed.EndAt,
+            TransactionType = parsed.TransactionType,
+            DeliveryType = parsed.DeliveryType,
+            PaymentMethod = parsed.PaymentMethod,
+            Keyword = request.Keyword
+        }, cancellationToken);
+
+        return ApiResponse<FinanceTransactionStatsResponse>.Ok(new FinanceTransactionStatsResponse
+        {
+            TotalIncome = result.TotalIncome,
+            TotalRefund = result.TotalRefund,
+            TotalCount = result.TotalCount
+        });
+    }
+
+    /// <summary>
+    /// 查询交易流水详情。
+    /// </summary>
+    [HttpGet("detail")]
+    [PermissionAuthorize(ViewPermission, DetailPermission)]
+    [ProducesResponseType(typeof(ApiResponse<FinanceTransactionDetailResponse>), StatusCodes.Status200OK)]
+    public async Task<ApiResponse<FinanceTransactionDetailResponse>> Detail(
+        [FromQuery] FinanceTransactionDetailRequest request,
+        CancellationToken cancellationToken)
+    {
+        // 1. 校验门店参数与门店访问权限。
+        var storeId = StoreApiHelpers.ParseRequiredSnowflake(request.StoreId, nameof(request.StoreId));
+        await EnsureStoreAccessibleAsync(storeId, cancellationToken);
+
+        // 2. 解析交易复合标识。
+        if (!TryParseTransactionId(request.TransactionId, out var sourceType, out var sourceId))
+        {
+            return ApiResponse<FinanceTransactionDetailResponse>.Error(ErrorCodes.BadRequest, "transactionId 非法");
+        }
+
+        // 3. 查询详情并返回。
+        var detail = await mediator.Send(new GetFinanceTransactionDetailQuery
+        {
+            StoreId = storeId,
+            SourceType = sourceType,
+            SourceId = sourceId
+        }, cancellationToken);
+
+        if (detail is null)
+        {
+            return ApiResponse<FinanceTransactionDetailResponse>.Error(ErrorCodes.NotFound, "交易流水不存在");
+        }
+
+        return ApiResponse<FinanceTransactionDetailResponse>.Ok(MapDetail(detail));
+    }
+
+    /// <summary>
+    /// 导出交易流水 CSV。
+    /// </summary>
+    [HttpGet("export")]
+    [PermissionAuthorize(ExportPermission)]
+    [ProducesResponseType(typeof(ApiResponse<FinanceTransactionExportResponse>), StatusCodes.Status200OK)]
+    public async Task<ApiResponse<FinanceTransactionExportResponse>> Export(
+        [FromQuery] FinanceTransactionFilterRequest request,
+        CancellationToken cancellationToken)
+    {
+        // 1. 解析并校验筛选参数。
+        var parsed = await ParseFilterAsync(request, cancellationToken);
+
+        // 2. 发起导出并返回结果。
+        var result = await mediator.Send(new ExportFinanceTransactionCsvQuery
+        {
+            StoreId = parsed.StoreId,
+            StartAt = parsed.StartAt,
+            EndAt = parsed.EndAt,
+            TransactionType = parsed.TransactionType,
+            DeliveryType = parsed.DeliveryType,
+            PaymentMethod = parsed.PaymentMethod,
+            Keyword = request.Keyword
+        }, cancellationToken);
+
+        return ApiResponse<FinanceTransactionExportResponse>.Ok(new FinanceTransactionExportResponse
+        {
+            FileName = result.FileName,
+            FileContentBase64 = result.FileContentBase64,
+            TotalCount = result.TotalCount
+        });
+    }
+
+    private async Task<(long StoreId, DateTime? StartAt, DateTime? EndAt, FinanceTransactionType? TransactionType, DeliveryType? DeliveryType, PaymentMethod? PaymentMethod)> ParseFilterAsync(
+        FinanceTransactionFilterRequest request,
+        CancellationToken cancellationToken)
+    {
+        var storeId = StoreApiHelpers.ParseRequiredSnowflake(request.StoreId, nameof(request.StoreId));
+        await EnsureStoreAccessibleAsync(storeId, cancellationToken);
+
+        var startAt = ParseDateOrNull(request.StartDate);
+        var endAt = ParseDateOrNull(request.EndDate)?.AddDays(1);
+        if (startAt.HasValue && endAt.HasValue && startAt >= endAt)
+        {
+            throw new BusinessException(ErrorCodes.BadRequest, "开始日期不能晚于结束日期");
+        }
+
+        var transactionType = ParseTransactionType(request.Type);
+        var deliveryType = ParseDeliveryType(request.Channel);
+        var paymentMethod = ParsePaymentMethod(request.PaymentMethod);
+
+        return (storeId, startAt, endAt, transactionType, deliveryType, paymentMethod);
+    }
+
+    private async Task EnsureStoreAccessibleAsync(long storeId, CancellationToken cancellationToken)
+    {
+        var (tenantId, merchantId) = StoreApiHelpers.GetTenantMerchantContext(storeContextService);
+        await StoreApiHelpers.EnsureStoreAccessibleAsync(dbContext, tenantId, merchantId, storeId, cancellationToken);
+    }
+
+    private static DateTime? ParseDateOrNull(string? value)
+    {
+        if (string.IsNullOrWhiteSpace(value))
+        {
+            return null;
+        }
+
+        if (DateTime.TryParseExact(
+                value,
+                "yyyy-MM-dd",
+                CultureInfo.InvariantCulture,
+                DateTimeStyles.None,
+                out var parsed))
+        {
+            return DateTime.SpecifyKind(parsed.Date, DateTimeKind.Utc);
+        }
+
+        throw new BusinessException(ErrorCodes.BadRequest, "日期格式必须为 yyyy-MM-dd");
+    }
+
+    private static FinanceTransactionType? ParseTransactionType(string? value)
+    {
+        var normalized = (value ?? string.Empty).Trim().ToLowerInvariant();
+        return normalized switch
+        {
+            "income" => FinanceTransactionType.Income,
+            "refund" => FinanceTransactionType.Refund,
+            "stored_card_recharge" => FinanceTransactionType.StoredCardRecharge,
+            "point_redeem" => FinanceTransactionType.PointRedeem,
+            _ => null
+        };
+    }
+
+    private static DeliveryType? ParseDeliveryType(string? value)
+    {
+        var normalized = (value ?? string.Empty).Trim().ToLowerInvariant();
+        return normalized switch
+        {
+            "delivery" => DeliveryType.Delivery,
+            "pickup" => DeliveryType.Pickup,
+            "dine_in" => DeliveryType.DineIn,
+            _ => null
+        };
+    }
+
+    private static PaymentMethod? ParsePaymentMethod(string? value)
+    {
+        var normalized = (value ?? string.Empty).Trim().ToLowerInvariant();
+        return normalized switch
+        {
+            "wechat" => PaymentMethod.WeChatPay,
+            "alipay" => PaymentMethod.Alipay,
+            "cash" => PaymentMethod.Cash,
+            "card" => PaymentMethod.Card,
+            "balance" => PaymentMethod.Balance,
+            _ => null
+        };
+    }
+
+    private static bool TryParseTransactionId(string? value, out FinanceTransactionSourceType sourceType, out long sourceId)
+    {
+        sourceType = default;
+        sourceId = 0;
+
+        var normalized = (value ?? string.Empty).Trim();
+        if (string.IsNullOrWhiteSpace(normalized))
+        {
+            return false;
+        }
+
+        var parts = normalized.Split(':', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);
+        if (parts.Length != 2)
+        {
+            return false;
+        }
+
+        if (!long.TryParse(parts[1], out sourceId) || sourceId <= 0)
+        {
+            return false;
+        }
+
+        sourceType = parts[0].ToLowerInvariant() switch
+        {
+            "payment" => FinanceTransactionSourceType.PaymentRecord,
+            "payment_refund" => FinanceTransactionSourceType.PaymentRefundRecord,
+            "refund_request" => FinanceTransactionSourceType.RefundRequest,
+            "stored_card_recharge" => FinanceTransactionSourceType.StoredCardRechargeRecord,
+            "member_point" => FinanceTransactionSourceType.MemberPointLedger,
+            _ => default
+        };
+
+        return sourceType != default;
+    }
+
+    private static FinanceTransactionListItemResponse MapListItem(FinanceTransactionListItemDto source)
+    {
+        return new FinanceTransactionListItemResponse
+        {
+            TransactionId = source.TransactionId,
+            TransactionNo = source.TransactionNo,
+            OrderNo = source.OrderNo,
+            Type = source.TransactionType,
+            TypeText = source.TransactionTypeText,
+            Channel = source.ChannelText,
+            PaymentMethod = source.PaymentMethodText,
+            Amount = source.AmountSigned,
+            OccurredAt = source.OccurredAt.ToString("yyyy-MM-dd HH:mm:ss", CultureInfo.InvariantCulture),
+            Remark = source.Remark,
+            IsIncome = source.IsIncome
+        };
+    }
+
+    private static FinanceTransactionDetailResponse MapDetail(FinanceTransactionDetailDto source)
+    {
+        return new FinanceTransactionDetailResponse
+        {
+            TransactionId = source.TransactionId,
+            TransactionNo = source.TransactionNo,
+            Type = source.TransactionType,
+            TypeText = source.TransactionTypeText,
+            StoreId = source.StoreId.ToString(),
+            OrderNo = source.OrderNo,
+            Channel = source.ChannelText,
+            PaymentMethod = source.PaymentMethodText,
+            Amount = source.AmountSigned,
+            OccurredAt = source.OccurredAt.ToString("yyyy-MM-dd HH:mm:ss", CultureInfo.InvariantCulture),
+            Remark = source.Remark,
+            CustomerName = source.CustomerName,
+            CustomerPhone = source.CustomerPhone,
+            RefundNo = source.RefundNo,
+            RefundReason = source.RefundReason,
+            MemberName = source.MemberName,
+            MemberMobileMasked = source.MemberMobileMasked,
+            RechargeAmount = source.RechargeAmount,
+            GiftAmount = source.GiftAmount,
+            ArrivedAmount = source.ArrivedAmount,
+            PointChangeAmount = source.PointChangeAmount,
+            PointBalanceAfterChange = source.PointBalanceAfterChange
+        };
+    }
+}

src/Api/TakeoutSaaS.TenantApi/Controllers/MemberMessageReachController.cs

@@ -0,0 +1,428 @@
+using System.Globalization;
+using Asp.Versioning;
+using Hangfire;
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Mvc;
+using TakeoutSaaS.Application.App.Members.MessageReach.Dto;
+using TakeoutSaaS.Application.App.Members.MessageReach.Services;
+using TakeoutSaaS.Application.App.Stores.Services;
+using TakeoutSaaS.Infrastructure.App.Persistence;
+using TakeoutSaaS.Module.Authorization.Attributes;
+using TakeoutSaaS.Shared.Abstractions.Constants;
+using TakeoutSaaS.Shared.Abstractions.Results;
+using TakeoutSaaS.Shared.Web.Api;
+using TakeoutSaaS.TenantApi.Contracts.Member;
+using TakeoutSaaS.TenantApi.Services;
+
+namespace TakeoutSaaS.TenantApi.Controllers;
+
+/// <summary>
+/// 会员消息触达管理。
+/// </summary>
+[ApiVersion("1.0")]
+[Authorize]
+[Route("api/tenant/v{version:apiVersion}/member/message-reach")]
+public sealed class MemberMessageReachController(
+    IMemberMessageReachAppService memberMessageReachAppService,
+    TakeoutAppDbContext dbContext,
+    StoreContextService storeContextService)
+    : BaseApiController
+{
+    private const string ViewPermission = "tenant:member:message-reach:view";
+    private const string ManagePermission = "tenant:member:message-reach:manage";
+
+    /// <summary>
+    /// 获取页面统计。
+    /// </summary>
+    [HttpGet("stats")]
+    [PermissionAuthorize(ViewPermission, ManagePermission)]
+    [ProducesResponseType(typeof(ApiResponse<MemberMessageReachStatsResponse>), StatusCodes.Status200OK)]
+    public async Task<ApiResponse<MemberMessageReachStatsResponse>> Stats(
+        [FromQuery] MemberMessageReachStatsRequest request,
+        CancellationToken cancellationToken)
+    {
+        var tenantId = await ResolveTenantIdAsync(request.StoreId, cancellationToken);
+        var result = await memberMessageReachAppService.GetStatsAsync(tenantId, cancellationToken);
+        return ApiResponse<MemberMessageReachStatsResponse>.Ok(new MemberMessageReachStatsResponse
+        {
+            MonthlySentCount = result.MonthlySentCount,
+            ReachMemberCount = result.ReachMemberCount,
+            OpenRate = result.OpenRate,
+            ConversionRate = result.ConversionRate
+        });
+    }
+
+    /// <summary>
+    /// 分页查询消息列表。
+    /// </summary>
+    [HttpGet("list")]
+    [PermissionAuthorize(ViewPermission, ManagePermission)]
+    [ProducesResponseType(typeof(ApiResponse<MemberMessageReachListResultResponse>), StatusCodes.Status200OK)]
+    public async Task<ApiResponse<MemberMessageReachListResultResponse>> List(
+        [FromQuery] MemberMessageReachListRequest request,
+        CancellationToken cancellationToken)
+    {
+        var tenantId = ResolveTenantId();
+        var result = await memberMessageReachAppService.SearchMessagesAsync(
+            tenantId,
+            new SearchMemberMessageInput
+            {
+                Status = request.Status,
+                Channel = request.Channel,
+                Keyword = request.Keyword,
+                Page = request.Page,
+                PageSize = request.PageSize
+            },
+            cancellationToken);
+
+        return ApiResponse<MemberMessageReachListResultResponse>.Ok(new MemberMessageReachListResultResponse
+        {
+            Items = result.Items.Select(MapMessageListItem).ToList(),
+            Page = result.Page,
+            PageSize = result.PageSize,
+            TotalCount = result.TotalCount
+        });
+    }
+
+    /// <summary>
+    /// 获取消息详情。
+    /// </summary>
+    [HttpGet("detail")]
+    [PermissionAuthorize(ViewPermission, ManagePermission)]
+    [ProducesResponseType(typeof(ApiResponse<MemberMessageReachDetailResponse>), StatusCodes.Status200OK)]
+    public async Task<ApiResponse<MemberMessageReachDetailResponse>> Detail(
+        [FromQuery] MemberMessageReachDetailRequest request,
+        CancellationToken cancellationToken)
+    {
+        var tenantId = ResolveTenantId();
+        var messageId = StoreApiHelpers.ParseRequiredSnowflake(request.MessageId, nameof(request.MessageId));
+        var result = await memberMessageReachAppService.GetMessageDetailAsync(tenantId, messageId, cancellationToken);
+        if (result is null)
+        {
+            return ApiResponse<MemberMessageReachDetailResponse>.Error(ErrorCodes.NotFound, "消息不存在");
+        }
+
+        return ApiResponse<MemberMessageReachDetailResponse>.Ok(MapMessageDetail(result));
+    }
+
+    /// <summary>
+    /// 保存消息（草稿/发送）。
+    /// </summary>
+    [HttpPost("save")]
+    [PermissionAuthorize(ManagePermission)]
+    [ProducesResponseType(typeof(ApiResponse<MemberMessageDispatchMetaResponse>), StatusCodes.Status200OK)]
+    public async Task<ApiResponse<MemberMessageDispatchMetaResponse>> Save(
+        [FromBody] SaveMemberMessageReachRequest request,
+        CancellationToken cancellationToken)
+    {
+        var tenantId = await ResolveTenantIdAsync(request.StoreId, cancellationToken);
+        var messageId = StoreApiHelpers.ParseSnowflakeOrNull(request.MessageId);
+        var previousMeta = messageId.HasValue
+            ? await memberMessageReachAppService.GetDispatchMetaAsync(tenantId, messageId.Value, cancellationToken)
+            : null;
+
+        var saved = await memberMessageReachAppService.SaveMessageAsync(
+            tenantId,
+            new SaveMemberMessageInput
+            {
+                MessageId = messageId,
+                StoreId = StoreApiHelpers.ParseSnowflakeOrNull(request.StoreId),
+                TemplateId = StoreApiHelpers.ParseSnowflakeOrNull(request.TemplateId),
+                Title = request.Title,
+                Content = request.Content,
+                Channels = request.Channels,
+                AudienceType = request.AudienceType,
+                AudienceTags = request.AudienceTags,
+                ScheduleType = request.ScheduleType,
+                ScheduledAt = request.ScheduledAt,
+                SubmitAction = request.SubmitAction
+            },
+            cancellationToken);
+
+        // 1. 清理旧任务（若存在）。
+        if (!string.IsNullOrWhiteSpace(previousMeta?.HangfireJobId))
+        {
+            BackgroundJob.Delete(previousMeta.HangfireJobId);
+        }
+
+        // 2. 发送动作创建新任务并回写任务 ID。
+        if (string.Equals(request.SubmitAction, "send", StringComparison.OrdinalIgnoreCase))
+        {
+            var newJobId = ScheduleDispatchJob(saved.MessageId, saved.ScheduleType, saved.ScheduledAt);
+            await memberMessageReachAppService.BindDispatchJobAsync(tenantId, saved.MessageId, newJobId, cancellationToken);
+        }
+
+        // 3. 返回最新调度状态。
+        var latest = await memberMessageReachAppService.GetDispatchMetaAsync(tenantId, saved.MessageId, cancellationToken);
+        return ApiResponse<MemberMessageDispatchMetaResponse>.Ok(MapDispatchMeta(latest ?? saved));
+    }
+
+    /// <summary>
+    /// 删除消息。
+    /// </summary>
+    [HttpPost("delete")]
+    [PermissionAuthorize(ManagePermission)]
+    [ProducesResponseType(typeof(ApiResponse<object>), StatusCodes.Status200OK)]
+    public async Task<ApiResponse<object>> Delete(
+        [FromBody] DeleteMemberMessageReachRequest request,
+        CancellationToken cancellationToken)
+    {
+        var tenantId = ResolveTenantId();
+        var messageId = StoreApiHelpers.ParseRequiredSnowflake(request.MessageId, nameof(request.MessageId));
+        var oldJobId = await memberMessageReachAppService.DeleteMessageAsync(tenantId, messageId, cancellationToken);
+        if (!string.IsNullOrWhiteSpace(oldJobId))
+        {
+            BackgroundJob.Delete(oldJobId);
+        }
+
+        return ApiResponse<object>.Ok(null);
+    }
+
+    /// <summary>
+    /// 估算目标人群。
+    /// </summary>
+    [HttpPost("audience/estimate")]
+    [PermissionAuthorize(ViewPermission, ManagePermission)]
+    [ProducesResponseType(typeof(ApiResponse<MemberMessageAudienceEstimateResponse>), StatusCodes.Status200OK)]
+    public async Task<ApiResponse<MemberMessageAudienceEstimateResponse>> EstimateAudience(
+        [FromBody] MemberMessageAudienceEstimateRequest request,
+        CancellationToken cancellationToken)
+    {
+        var tenantId = ResolveTenantId();
+        var result = await memberMessageReachAppService.EstimateAudienceAsync(
+            tenantId,
+            new MemberMessageAudienceEstimateInput
+            {
+                AudienceType = request.AudienceType,
+                Tags = request.Tags
+            },
+            cancellationToken);
+
+        return ApiResponse<MemberMessageAudienceEstimateResponse>.Ok(new MemberMessageAudienceEstimateResponse
+        {
+            ReachCount = result.ReachCount
+        });
+    }
+
+    /// <summary>
+    /// 分页查询模板。
+    /// </summary>
+    [HttpGet("template/list")]
+    [PermissionAuthorize(ViewPermission, ManagePermission)]
+    [ProducesResponseType(typeof(ApiResponse<MemberMessageTemplateListResultResponse>), StatusCodes.Status200OK)]
+    public async Task<ApiResponse<MemberMessageTemplateListResultResponse>> TemplateList(
+        [FromQuery] MemberMessageTemplateListRequest request,
+        CancellationToken cancellationToken)
+    {
+        var tenantId = ResolveTenantId();
+        var result = await memberMessageReachAppService.SearchTemplatesAsync(
+            tenantId,
+            new SearchMemberMessageTemplateInput
+            {
+                Category = request.Category,
+                Keyword = request.Keyword,
+                Page = request.Page,
+                PageSize = request.PageSize
+            },
+            cancellationToken);
+
+        return ApiResponse<MemberMessageTemplateListResultResponse>.Ok(new MemberMessageTemplateListResultResponse
+        {
+            Items = result.Items.Select(MapTemplate).ToList(),
+            Page = result.Page,
+            PageSize = result.PageSize,
+            TotalCount = result.TotalCount
+        });
+    }
+
+    /// <summary>
+    /// 获取模板详情。
+    /// </summary>
+    [HttpGet("template/detail")]
+    [PermissionAuthorize(ViewPermission, ManagePermission)]
+    [ProducesResponseType(typeof(ApiResponse<MemberMessageTemplateResponse>), StatusCodes.Status200OK)]
+    public async Task<ApiResponse<MemberMessageTemplateResponse>> TemplateDetail(
+        [FromQuery] MemberMessageTemplateDetailRequest request,
+        CancellationToken cancellationToken)
+    {
+        var tenantId = ResolveTenantId();
+        var templateId = StoreApiHelpers.ParseRequiredSnowflake(request.TemplateId, nameof(request.TemplateId));
+        var result = await memberMessageReachAppService.GetTemplateAsync(tenantId, templateId, cancellationToken);
+        if (result is null)
+        {
+            return ApiResponse<MemberMessageTemplateResponse>.Error(ErrorCodes.NotFound, "模板不存在");
+        }
+
+        return ApiResponse<MemberMessageTemplateResponse>.Ok(MapTemplate(result));
+    }
+
+    /// <summary>
+    /// 保存模板。
+    /// </summary>
+    [HttpPost("template/save")]
+    [PermissionAuthorize(ManagePermission)]
+    [ProducesResponseType(typeof(ApiResponse<MemberMessageTemplateResponse>), StatusCodes.Status200OK)]
+    public async Task<ApiResponse<MemberMessageTemplateResponse>> SaveTemplate(
+        [FromBody] SaveMemberMessageTemplateRequest request,
+        CancellationToken cancellationToken)
+    {
+        var tenantId = ResolveTenantId();
+        var result = await memberMessageReachAppService.SaveTemplateAsync(
+            tenantId,
+            new SaveMemberMessageTemplateInput
+            {
+                TemplateId = StoreApiHelpers.ParseSnowflakeOrNull(request.TemplateId),
+                Name = request.Name,
+                Category = request.Category,
+                Content = request.Content
+            },
+            cancellationToken);
+
+        return ApiResponse<MemberMessageTemplateResponse>.Ok(MapTemplate(result));
+    }
+
+    /// <summary>
+    /// 删除模板。
+    /// </summary>
+    [HttpPost("template/delete")]
+    [PermissionAuthorize(ManagePermission)]
+    [ProducesResponseType(typeof(ApiResponse<object>), StatusCodes.Status200OK)]
+    public async Task<ApiResponse<object>> DeleteTemplate(
+        [FromBody] DeleteMemberMessageTemplateRequest request,
+        CancellationToken cancellationToken)
+    {
+        var tenantId = ResolveTenantId();
+        var templateId = StoreApiHelpers.ParseRequiredSnowflake(request.TemplateId, nameof(request.TemplateId));
+        await memberMessageReachAppService.DeleteTemplateAsync(tenantId, templateId, cancellationToken);
+        return ApiResponse<object>.Ok(null);
+    }
+
+    private long ResolveTenantId()
+    {
+        var (tenantId, _) = StoreApiHelpers.GetTenantMerchantContext(storeContextService);
+        return tenantId;
+    }
+
+    private async Task<long> ResolveTenantIdAsync(string? storeId, CancellationToken cancellationToken)
+    {
+        var (tenantId, merchantId) = StoreApiHelpers.GetTenantMerchantContext(storeContextService);
+        if (string.IsNullOrWhiteSpace(storeId))
+        {
+            return tenantId;
+        }
+
+        var parsedStoreId = StoreApiHelpers.ParseRequiredSnowflake(storeId, nameof(storeId));
+        await StoreApiHelpers.EnsureStoreAccessibleAsync(
+            dbContext,
+            tenantId,
+            merchantId,
+            parsedStoreId,
+            cancellationToken);
+        return tenantId;
+    }
+
+    private static string ScheduleDispatchJob(long messageId, string scheduleType, DateTime? scheduledAtUtc)
+    {
+        if (string.Equals(scheduleType, "scheduled", StringComparison.OrdinalIgnoreCase) && scheduledAtUtc.HasValue)
+        {
+            var delay = scheduledAtUtc.Value.ToUniversalTime() - DateTime.UtcNow;
+            if (delay < TimeSpan.Zero)
+            {
+                delay = TimeSpan.Zero;
+            }
+
+            return BackgroundJob.Schedule<MemberMessageReachDispatchJobRunner>(
+                runner => runner.ExecuteAsync(messageId),
+                delay);
+        }
+
+        return BackgroundJob.Enqueue<MemberMessageReachDispatchJobRunner>(runner => runner.ExecuteAsync(messageId));
+    }
+
+    private static MemberMessageReachListItemResponse MapMessageListItem(MemberMessageReachListItemDto source)
+    {
+        return new MemberMessageReachListItemResponse
+        {
+            MessageId = source.MessageId.ToString(),
+            Title = source.Title,
+            Channels = source.Channels.ToList(),
+            AudienceText = source.AudienceText,
+            EstimatedReachCount = source.EstimatedReachCount,
+            Status = source.Status,
+            SentAt = FormatDateTime(source.SentAt),
+            ScheduledAt = FormatDateTime(source.ScheduledAt),
+            OpenRate = source.OpenRate,
+            ConversionRate = source.ConversionRate
+        };
+    }
+
+    private static MemberMessageReachDetailResponse MapMessageDetail(MemberMessageReachDetailDto source)
+    {
+        return new MemberMessageReachDetailResponse
+        {
+            MessageId = source.MessageId.ToString(),
+            TemplateId = source.TemplateId?.ToString(),
+            Title = source.Title,
+            Content = source.Content,
+            Channels = source.Channels.ToList(),
+            AudienceType = source.AudienceType,
+            AudienceTags = source.AudienceTags.ToList(),
+            AudienceText = source.AudienceText,
+            EstimatedReachCount = source.EstimatedReachCount,
+            ScheduleType = source.ScheduleType,
+            ScheduledAt = FormatDateTime(source.ScheduledAt),
+            Status = source.Status,
+            SentAt = FormatDateTime(source.SentAt),
+            SentCount = source.SentCount,
+            ReadCount = source.ReadCount,
+            ConvertedCount = source.ConvertedCount,
+            OpenRate = source.OpenRate,
+            ConversionRate = source.ConversionRate,
+            LastError = source.LastError,
+            Recipients = source.Recipients.Select(item => new MemberMessageReachRecipientResponse
+            {
+                MemberId = item.MemberId.ToString(),
+                Channel = item.Channel,
+                Status = item.Status,
+                Mobile = item.Mobile,
+                OpenId = item.OpenId,
+                SentAt = FormatDateTime(item.SentAt),
+                ReadAt = FormatDateTime(item.ReadAt),
+                ConvertedAt = FormatDateTime(item.ConvertedAt),
+                ErrorMessage = item.ErrorMessage
+            }).ToList()
+        };
+    }
+
+    private static MemberMessageDispatchMetaResponse MapDispatchMeta(MemberMessageDispatchMetaDto source)
+    {
+        return new MemberMessageDispatchMetaResponse
+        {
+            MessageId = source.MessageId.ToString(),
+            Status = source.Status,
+            ScheduleType = source.ScheduleType,
+            ScheduledAt = FormatDateTime(source.ScheduledAt),
+            HangfireJobId = source.HangfireJobId
+        };
+    }
+
+    private static MemberMessageTemplateResponse MapTemplate(MemberMessageTemplateDto source)
+    {
+        return new MemberMessageTemplateResponse
+        {
+            TemplateId = source.TemplateId.ToString(),
+            Name = source.Name,
+            Category = source.Category,
+            Content = source.Content,
+            UsageCount = source.UsageCount,
+            LastUsedAt = FormatDateTime(source.LastUsedAt)
+        };
+    }
+
+    private static string? FormatDateTime(DateTime? value)
+    {
+        return value.HasValue
+            ? value.Value.ToLocalTime().ToString("yyyy-MM-dd HH:mm:ss", CultureInfo.InvariantCulture)
+            : null;
+    }
+}

src/Api/TakeoutSaaS.TenantApi/Controllers/StoreFeesController.cs

@@ -64,6 +64,7 @@ public sealed class StoreFeesController(
             StoreId = parsedStoreId,
             MinimumOrderAmount = request.MinimumOrderAmount,
             DeliveryFee = request.BaseDeliveryFee,
+            PlatformServiceRate = request.PlatformServiceRate,
             FreeDeliveryThreshold = request.FreeDeliveryThreshold,
             PackagingFeeMode = ParsePackagingFeeMode(request.PackagingFeeMode),
             OrderPackagingFeeMode = ParseOrderPackagingFeeMode(request.OrderPackagingFeeMode),
@@ -175,6 +176,7 @@ public sealed class StoreFeesController(
 
             targetFee.MinimumOrderAmount = sourceFee.MinimumOrderAmount;
             targetFee.BaseDeliveryFee = sourceFee.BaseDeliveryFee;
+            targetFee.PlatformServiceRate = sourceFee.PlatformServiceRate;
             targetFee.FreeDeliveryThreshold = sourceFee.FreeDeliveryThreshold;
             targetFee.PackagingFeeMode = sourceFee.PackagingFeeMode;
             targetFee.OrderPackagingFeeMode = sourceFee.OrderPackagingFeeMode;
@@ -214,6 +216,7 @@ public sealed class StoreFeesController(
             IsConfigured = source is not null,
             MinimumOrderAmount = source?.MinimumOrderAmount ?? 0m,
             BaseDeliveryFee = source?.DeliveryFee ?? 0m,
+            PlatformServiceRate = source?.PlatformServiceRate ?? 0m,
             FreeDeliveryThreshold = source?.FreeDeliveryThreshold,
             PackagingFeeMode = ToPackagingFeeModeText(source?.PackagingFeeMode ?? PackagingFeeMode.Fixed),
             OrderPackagingFeeMode = ToOrderPackagingFeeModeText(source?.OrderPackagingFeeMode ?? OrderPackagingFeeMode.Fixed),

src/Api/TakeoutSaaS.TenantApi/Program.cs

@@ -10,9 +10,12 @@ using Serilog;
 using StackExchange.Redis;
 using TakeoutSaaS.Application.App.Common.Geo;
 using TakeoutSaaS.Application.App.Extensions;
+using TakeoutSaaS.Application.App.Members.MessageReach.Options;
+using TakeoutSaaS.Application.App.Members.MessageReach.Services;
 using TakeoutSaaS.Application.Dictionary.Extensions;
 using TakeoutSaaS.Application.Identity.Extensions;
 using TakeoutSaaS.Application.Messaging.Extensions;
+using TakeoutSaaS.Application.Sms.Extensions;
 using TakeoutSaaS.Application.Storage.Extensions;
 using TakeoutSaaS.Infrastructure.App.Extensions;
 using TakeoutSaaS.Infrastructure.Dictionary.Extensions;
@@ -22,6 +25,7 @@ using TakeoutSaaS.Module.Authorization.Extensions;
 using TakeoutSaaS.Module.Messaging.Extensions;
 using TakeoutSaaS.Module.Messaging.Options;
 using TakeoutSaaS.Module.Scheduler.Extensions;
+using TakeoutSaaS.Module.Sms.Extensions;
 using TakeoutSaaS.Module.Storage.Extensions;
 using TakeoutSaaS.Module.Tenancy.Extensions;
 using TakeoutSaaS.Shared.Abstractions.Security;
@@ -118,6 +122,7 @@ if (!string.IsNullOrWhiteSpace(redisConn))
 
 // 6. 注册应用层与基础设施（仅租户侧所需）
 builder.Services.AddAppApplication();
+builder.Services.AddSmsApplication(builder.Configuration);
 builder.Services.AddIdentityApplication(enableMiniSupport: false);
 builder.Services.AddAppInfrastructure(builder.Configuration);
 builder.Services.AddIdentityInfrastructure(builder.Configuration, enableMiniFeatures: false, enableAdminSeed: false);
@@ -132,6 +137,7 @@ builder.Services.AddDictionaryInfrastructure(builder.Configuration);
 // 9. 注册消息发布能力（未配置 RabbitMQ 时自动降级为 NoOp 实现）
 builder.Services.AddMessagingApplication();
 builder.Services.AddMessagingModule(builder.Configuration);
+builder.Services.AddSmsModule(builder.Configuration);
 builder.Services.AddMassTransit(configurator =>
 {
     // 注册 SignalR 推送消费者
@@ -167,6 +173,16 @@ builder.Services.AddMassTransit(configurator =>
 builder.Services.AddStorageModule(builder.Configuration);
 builder.Services.AddStorageApplication();
 builder.Services.AddSchedulerModule(builder.Configuration);
+builder.Services.AddOptions<MemberMessagingOptions>()
+    .Bind(builder.Configuration.GetSection("MemberMessaging"))
+    .ValidateDataAnnotations()
+    .ValidateOnStart();
+builder.Services.AddHttpClient<IMemberMessageWeChatSender, MemberMessageWeChatSender>(client =>
+{
+    client.BaseAddress = new Uri("https://api.weixin.qq.com/");
+    client.Timeout = TimeSpan.FromSeconds(10);
+});
+builder.Services.AddScoped<MemberMessageReachDispatchJobRunner>();
 
 // 9.1 注册腾讯地图地理编码服务（服务端签名）
 builder.Services.Configure<TencentMapOptions>(builder.Configuration.GetSection(TencentMapOptions.SectionName));

src/Api/TakeoutSaaS.TenantApi/Services/MemberMessageReachDispatchJobRunner.cs

@@ -0,0 +1,50 @@
+using Hangfire;
+using Microsoft.EntityFrameworkCore;
+using TakeoutSaaS.Application.App.Members.MessageReach.Services;
+using TakeoutSaaS.Infrastructure.App.Persistence;
+using TakeoutSaaS.Shared.Abstractions.Tenancy;
+
+namespace TakeoutSaaS.TenantApi.Services;
+
+/// <summary>
+/// 会员消息触达发送任务执行器。
+/// </summary>
+public sealed class MemberMessageReachDispatchJobRunner(
+    TakeoutAppDbContext dbContext,
+    ITenantContextAccessor tenantContextAccessor,
+    IMemberMessageReachAppService memberMessageReachAppService,
+    ILogger<MemberMessageReachDispatchJobRunner> logger)
+{
+    /// <summary>
+    /// 执行消息发送任务。
+    /// </summary>
+    [AutomaticRetry(Attempts = 0)]
+    public async Task ExecuteAsync(long messageId)
+    {
+        // 1. 查询任务所属租户，避免跨租户执行。
+        var jobMeta = await dbContext.MemberReachMessages
+            .IgnoreQueryFilters()
+            .AsNoTracking()
+            .Where(item => item.Id == messageId)
+            .Select(item => new JobMeta(item.Id, item.TenantId))
+            .SingleOrDefaultAsync();
+        if (jobMeta is null || jobMeta.TenantId <= 0)
+        {
+            logger.LogWarning("会员消息任务不存在或租户无效，MessageId={MessageId}", messageId);
+            return;
+        }
+
+        // 2. 切换租户作用域并执行发送逻辑。
+        using var _ = tenantContextAccessor.EnterTenantScope(jobMeta.TenantId, "scheduler", $"tenant-{jobMeta.TenantId}");
+        try
+        {
+            await memberMessageReachAppService.ExecuteDispatchAsync(jobMeta.TenantId, jobMeta.Id, CancellationToken.None);
+        }
+        catch (Exception ex)
+        {
+            logger.LogError(ex, "会员消息任务执行失败，TenantId={TenantId} MessageId={MessageId}", jobMeta.TenantId, jobMeta.Id);
+        }
+    }
+
+    private sealed record JobMeta(long Id, long TenantId);
+}

src/Api/TakeoutSaaS.TenantApi/appsettings.Development.json

@@ -125,6 +125,49 @@
       "AntiLeechTokenSecret": "ReplaceWithARandomToken"
     }
   },
+  "Sms": {
+    "Provider": "Tencent",
+    "DefaultSignName": "外卖SaaS",
+    "UseMock": true,
+    "Tencent": {
+      "SecretId": "TENCENT_SMS_SECRET_ID",
+      "SecretKey": "TENCENT_SMS_SECRET_KEY",
+      "SdkAppId": "1400000000",
+      "SignName": "外卖SaaS",
+      "Region": "ap-beijing",
+      "Endpoint": "https://sms.tencentcloudapi.com"
+    },
+    "Aliyun": {
+      "AccessKeyId": "ALIYUN_SMS_AK",
+      "AccessKeySecret": "ALIYUN_SMS_SK",
+      "Endpoint": "dysmsapi.aliyuncs.com",
+      "SignName": "外卖SaaS",
+      "Region": "cn-hangzhou"
+    },
+    "SceneTemplates": {
+      "login": "LOGIN_TEMPLATE_ID",
+      "register": "REGISTER_TEMPLATE_ID",
+      "reset": "RESET_TEMPLATE_ID",
+      "member_message": "MEMBER_MESSAGE_TEMPLATE_ID"
+    },
+    "VerificationCode": {
+      "CodeLength": 6,
+      "ExpireMinutes": 5,
+      "CooldownSeconds": 60,
+      "CachePrefix": "sms:code"
+    }
+  },
+  "MemberMessaging": {
+    "SmsScene": "member_message",
+    "WeChatMini": {
+      "AppId": "WECHAT_MINI_APP_ID",
+      "AppSecret": "WECHAT_MINI_APP_SECRET",
+      "SubscribeTemplateId": "WECHAT_SUBSCRIBE_TEMPLATE_ID",
+      "PagePath": "pages/member/message-center/index",
+      "TitleDataKey": "thing1",
+      "ContentDataKey": "thing2"
+    }
+  },
   "Scheduler": {
     "ConnectionString": "Host=120.53.222.17;Port=5432;Database=takeout_app_db;Username=app_user;Password=AppUser112233;Pooling=true;Minimum Pool Size=5;Maximum Pool Size=50",
     "WorkerCount": 10,

src/Api/TakeoutSaaS.TenantApi/appsettings.Production.json

@@ -123,6 +123,49 @@
       "AntiLeechTokenSecret": "ReplaceWithARandomToken"
     }
   },
+  "Sms": {
+    "Provider": "Tencent",
+    "DefaultSignName": "外卖SaaS",
+    "UseMock": false,
+    "Tencent": {
+      "SecretId": "TENCENT_SMS_SECRET_ID",
+      "SecretKey": "TENCENT_SMS_SECRET_KEY",
+      "SdkAppId": "1400000000",
+      "SignName": "外卖SaaS",
+      "Region": "ap-beijing",
+      "Endpoint": "https://sms.tencentcloudapi.com"
+    },
+    "Aliyun": {
+      "AccessKeyId": "ALIYUN_SMS_AK",
+      "AccessKeySecret": "ALIYUN_SMS_SK",
+      "Endpoint": "dysmsapi.aliyuncs.com",
+      "SignName": "外卖SaaS",
+      "Region": "cn-hangzhou"
+    },
+    "SceneTemplates": {
+      "login": "LOGIN_TEMPLATE_ID",
+      "register": "REGISTER_TEMPLATE_ID",
+      "reset": "RESET_TEMPLATE_ID",
+      "member_message": "MEMBER_MESSAGE_TEMPLATE_ID"
+    },
+    "VerificationCode": {
+      "CodeLength": 6,
+      "ExpireMinutes": 5,
+      "CooldownSeconds": 60,
+      "CachePrefix": "sms:code"
+    }
+  },
+  "MemberMessaging": {
+    "SmsScene": "member_message",
+    "WeChatMini": {
+      "AppId": "WECHAT_MINI_APP_ID",
+      "AppSecret": "WECHAT_MINI_APP_SECRET",
+      "SubscribeTemplateId": "WECHAT_SUBSCRIBE_TEMPLATE_ID",
+      "PagePath": "pages/member/message-center/index",
+      "TitleDataKey": "thing1",
+      "ContentDataKey": "thing2"
+    }
+  },
   "Scheduler": {
     "ConnectionString": "Host=120.53.222.17;Port=5432;Database=takeout_app_db;Username=app_user;Password=AppUser112233;Pooling=true;Minimum Pool Size=5;Maximum Pool Size=50",
     "WorkerCount": 10,

src/Application/TakeoutSaaS.Application/App/Extensions/AppApplicationServiceCollectionExtensions.cs

@@ -3,6 +3,7 @@ using MediatR;
 using Microsoft.Extensions.DependencyInjection;
 using System.Reflection;
 using TakeoutSaaS.Application.App.Common.Behaviors;
+using TakeoutSaaS.Application.App.Members.MessageReach.Services;
 using TakeoutSaaS.Application.App.Personal.Services;
 using TakeoutSaaS.Application.App.Personal.Validators;
 using TakeoutSaaS.Application.App.Stores.Services;
@@ -35,6 +36,9 @@ public static class AppApplicationServiceCollectionExtensions
         // 2. 注册门店模块上下文服务
         services.AddScoped<StoreContextService>();
 
+        // 3. (空行后) 注册会员消息触达服务
+        services.AddScoped<IMemberMessageReachAppService, MemberMessageReachAppService>();
+
         return services;
     }
 }

src/Application/TakeoutSaaS.Application/App/Finance/Cost/Commands/SaveFinanceCostEntryCommand.cs

@@ -0,0 +1,88 @@
+using MediatR;
+using TakeoutSaaS.Application.App.Finance.Cost.Dto;
+using TakeoutSaaS.Domain.Finance.Enums;
+
+namespace TakeoutSaaS.Application.App.Finance.Cost.Commands;
+
+/// <summary>
+/// 保存成本录入数据。
+/// </summary>
+public sealed class SaveFinanceCostEntryCommand : IRequest<FinanceCostEntryDto>
+{
+    /// <summary>
+    /// 统计维度。
+    /// </summary>
+    public FinanceCostDimension Dimension { get; init; } = FinanceCostDimension.Tenant;
+
+    /// <summary>
+    /// 门店标识（门店维度必填）。
+    /// </summary>
+    public long? StoreId { get; init; }
+
+    /// <summary>
+    /// 目标月份（UTC 每月第一天）。
+    /// </summary>
+    public DateTime CostMonth { get; init; } = DateTime.UtcNow;
+
+    /// <summary>
+    /// 成本分类列表。
+    /// </summary>
+    public IReadOnlyList<SaveFinanceCostCategoryCommandItem> Categories { get; init; } = [];
+}
+
+/// <summary>
+/// 成本分类保存项。
+/// </summary>
+public sealed class SaveFinanceCostCategoryCommandItem
+{
+    /// <summary>
+    /// 成本分类。
+    /// </summary>
+    public FinanceCostCategory Category { get; init; }
+
+    /// <summary>
+    /// 分类总金额。
+    /// </summary>
+    public decimal TotalAmount { get; init; }
+
+    /// <summary>
+    /// 分类明细项。
+    /// </summary>
+    public IReadOnlyList<SaveFinanceCostDetailCommandItem> Items { get; init; } = [];
+}
+
+/// <summary>
+/// 成本明细保存项。
+/// </summary>
+public sealed class SaveFinanceCostDetailCommandItem
+{
+    /// <summary>
+    /// 明细标识（编辑时透传，可为空）。
+    /// </summary>
+    public long? ItemId { get; init; }
+
+    /// <summary>
+    /// 明细名称。
+    /// </summary>
+    public string ItemName { get; init; } = string.Empty;
+
+    /// <summary>
+    /// 金额。
+    /// </summary>
+    public decimal Amount { get; init; }
+
+    /// <summary>
+    /// 数量（人工类可用）。
+    /// </summary>
+    public decimal? Quantity { get; init; }
+
+    /// <summary>
+    /// 单价（人工类可用）。
+    /// </summary>
+    public decimal? UnitPrice { get; init; }
+
+    /// <summary>
+    /// 排序值。
+    /// </summary>
+    public int SortOrder { get; init; }
+}

src/Application/TakeoutSaaS.Application/App/Finance/Cost/Dto/FinanceCostDtos.cs

@@ -0,0 +1,279 @@
+namespace TakeoutSaaS.Application.App.Finance.Cost.Dto;
+
+/// <summary>
+/// 成本录入明细项 DTO。
+/// </summary>
+public sealed class FinanceCostEntryDetailDto
+{
+    /// <summary>
+    /// 明细标识。
+    /// </summary>
+    public string? ItemId { get; set; }
+
+    /// <summary>
+    /// 明细名称。
+    /// </summary>
+    public string ItemName { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 金额。
+    /// </summary>
+    public decimal Amount { get; set; }
+
+    /// <summary>
+    /// 数量（人工类可用）。
+    /// </summary>
+    public decimal? Quantity { get; set; }
+
+    /// <summary>
+    /// 单价（人工类可用）。
+    /// </summary>
+    public decimal? UnitPrice { get; set; }
+
+    /// <summary>
+    /// 排序值。
+    /// </summary>
+    public int SortOrder { get; set; }
+}
+
+/// <summary>
+/// 成本录入分类 DTO。
+/// </summary>
+public sealed class FinanceCostEntryCategoryDto
+{
+    /// <summary>
+    /// 分类编码。
+    /// </summary>
+    public string Category { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 分类文案。
+    /// </summary>
+    public string CategoryText { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 分类总金额。
+    /// </summary>
+    public decimal TotalAmount { get; set; }
+
+    /// <summary>
+    /// 分类占比（%）。
+    /// </summary>
+    public decimal Percentage { get; set; }
+
+    /// <summary>
+    /// 分类明细项。
+    /// </summary>
+    public List<FinanceCostEntryDetailDto> Items { get; set; } = [];
+}
+
+/// <summary>
+/// 成本录入页 DTO。
+/// </summary>
+public sealed class FinanceCostEntryDto
+{
+    /// <summary>
+    /// 维度编码。
+    /// </summary>
+    public string Dimension { get; set; } = "tenant";
+
+    /// <summary>
+    /// 门店标识（门店维度时有值）。
+    /// </summary>
+    public string? StoreId { get; set; }
+
+    /// <summary>
+    /// 月份（yyyy-MM）。
+    /// </summary>
+    public string Month { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 本月营业额。
+    /// </summary>
+    public decimal MonthRevenue { get; set; }
+
+    /// <summary>
+    /// 本月总成本。
+    /// </summary>
+    public decimal TotalCost { get; set; }
+
+    /// <summary>
+    /// 本月成本率（%）。
+    /// </summary>
+    public decimal CostRate { get; set; }
+
+    /// <summary>
+    /// 分类集合。
+    /// </summary>
+    public List<FinanceCostEntryCategoryDto> Categories { get; set; } = [];
+}
+
+/// <summary>
+/// 成本分析统计卡 DTO。
+/// </summary>
+public sealed class FinanceCostAnalysisStatsDto
+{
+    /// <summary>
+    /// 本月总成本。
+    /// </summary>
+    public decimal TotalCost { get; set; }
+
+    /// <summary>
+    /// 食材成本率（%）。
+    /// </summary>
+    public decimal FoodCostRate { get; set; }
+
+    /// <summary>
+    /// 单均成本。
+    /// </summary>
+    public decimal AverageCostPerPaidOrder { get; set; }
+
+    /// <summary>
+    /// 环比变化（%）。
+    /// </summary>
+    public decimal MonthOnMonthChangeRate { get; set; }
+
+    /// <summary>
+    /// 本月营业额。
+    /// </summary>
+    public decimal Revenue { get; set; }
+
+    /// <summary>
+    /// 本月支付成功订单数。
+    /// </summary>
+    public int PaidOrderCount { get; set; }
+}
+
+/// <summary>
+/// 成本趋势点 DTO。
+/// </summary>
+public sealed class FinanceCostTrendPointDto
+{
+    /// <summary>
+    /// 月份（yyyy-MM）。
+    /// </summary>
+    public string Month { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 月度总成本。
+    /// </summary>
+    public decimal TotalCost { get; set; }
+
+    /// <summary>
+    /// 月度营业额。
+    /// </summary>
+    public decimal Revenue { get; set; }
+
+    /// <summary>
+    /// 月度成本率（%）。
+    /// </summary>
+    public decimal CostRate { get; set; }
+}
+
+/// <summary>
+/// 成本构成项 DTO。
+/// </summary>
+public sealed class FinanceCostCompositionItemDto
+{
+    /// <summary>
+    /// 分类编码。
+    /// </summary>
+    public string Category { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 分类文案。
+    /// </summary>
+    public string CategoryText { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 金额。
+    /// </summary>
+    public decimal Amount { get; set; }
+
+    /// <summary>
+    /// 占比（%）。
+    /// </summary>
+    public decimal Percentage { get; set; }
+}
+
+/// <summary>
+/// 成本分析明细表行 DTO。
+/// </summary>
+public sealed class FinanceCostMonthlyDetailRowDto
+{
+    /// <summary>
+    /// 月份（yyyy-MM）。
+    /// </summary>
+    public string Month { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 食材成本。
+    /// </summary>
+    public decimal FoodAmount { get; set; }
+
+    /// <summary>
+    /// 人工成本。
+    /// </summary>
+    public decimal LaborAmount { get; set; }
+
+    /// <summary>
+    /// 固定费用。
+    /// </summary>
+    public decimal FixedAmount { get; set; }
+
+    /// <summary>
+    /// 包装耗材。
+    /// </summary>
+    public decimal PackagingAmount { get; set; }
+
+    /// <summary>
+    /// 总成本。
+    /// </summary>
+    public decimal TotalCost { get; set; }
+
+    /// <summary>
+    /// 成本率（%）。
+    /// </summary>
+    public decimal CostRate { get; set; }
+}
+
+/// <summary>
+/// 成本分析页 DTO。
+/// </summary>
+public sealed class FinanceCostAnalysisDto
+{
+    /// <summary>
+    /// 维度编码。
+    /// </summary>
+    public string Dimension { get; set; } = "tenant";
+
+    /// <summary>
+    /// 门店标识（门店维度时有值）。
+    /// </summary>
+    public string? StoreId { get; set; }
+
+    /// <summary>
+    /// 月份（yyyy-MM）。
+    /// </summary>
+    public string Month { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 统计卡。
+    /// </summary>
+    public FinanceCostAnalysisStatsDto Stats { get; set; } = new();
+
+    /// <summary>
+    /// 趋势数据。
+    /// </summary>
+    public List<FinanceCostTrendPointDto> Trend { get; set; } = [];
+
+    /// <summary>
+    /// 构成数据。
+    /// </summary>
+    public List<FinanceCostCompositionItemDto> Composition { get; set; } = [];
+
+    /// <summary>
+    /// 明细表数据。
+    /// </summary>
+    public List<FinanceCostMonthlyDetailRowDto> DetailRows { get; set; } = [];
+}

src/Application/TakeoutSaaS.Application/App/Finance/Cost/Handlers/FinanceCostMapping.cs

@@ -0,0 +1,248 @@
+using System.Globalization;
+using TakeoutSaaS.Application.App.Finance.Cost.Dto;
+using TakeoutSaaS.Domain.Finance.Enums;
+using TakeoutSaaS.Domain.Finance.Models;
+
+namespace TakeoutSaaS.Application.App.Finance.Cost.Handlers;
+
+/// <summary>
+/// 成本模块映射与文案转换。
+/// </summary>
+internal static class FinanceCostMapping
+{
+    /// <summary>
+    /// 维度编码转枚举。
+    /// </summary>
+    public static FinanceCostDimension ParseDimensionCode(string? value)
+    {
+        return (value ?? string.Empty).Trim().ToLowerInvariant() switch
+        {
+            "store" => FinanceCostDimension.Store,
+            _ => FinanceCostDimension.Tenant
+        };
+    }
+
+    /// <summary>
+    /// 维度枚举转编码。
+    /// </summary>
+    public static string ToDimensionCode(FinanceCostDimension value)
+    {
+        return value == FinanceCostDimension.Store ? "store" : "tenant";
+    }
+
+    /// <summary>
+    /// 分类编码转枚举。
+    /// </summary>
+    public static FinanceCostCategory ParseCategoryCode(string? value)
+    {
+        return (value ?? string.Empty).Trim().ToLowerInvariant() switch
+        {
+            "food" => FinanceCostCategory.FoodMaterial,
+            "labor" => FinanceCostCategory.Labor,
+            "fixed" => FinanceCostCategory.FixedExpense,
+            "packaging" => FinanceCostCategory.PackagingConsumable,
+            _ => FinanceCostCategory.FoodMaterial
+        };
+    }
+
+    /// <summary>
+    /// 分类枚举转编码。
+    /// </summary>
+    public static string ToCategoryCode(FinanceCostCategory value)
+    {
+        return value switch
+        {
+            FinanceCostCategory.FoodMaterial => "food",
+            FinanceCostCategory.Labor => "labor",
+            FinanceCostCategory.FixedExpense => "fixed",
+            FinanceCostCategory.PackagingConsumable => "packaging",
+            _ => "food"
+        };
+    }
+
+    /// <summary>
+    /// 分类文案。
+    /// </summary>
+    public static string ToCategoryText(FinanceCostCategory value)
+    {
+        return value switch
+        {
+            FinanceCostCategory.FoodMaterial => "食材原料",
+            FinanceCostCategory.Labor => "人工成本",
+            FinanceCostCategory.FixedExpense => "固定费用",
+            FinanceCostCategory.PackagingConsumable => "包装耗材",
+            _ => "食材原料"
+        };
+    }
+
+    /// <summary>
+    /// 格式化月份字符串（yyyy-MM）。
+    /// </summary>
+    public static string ToMonthText(DateTime month)
+    {
+        return month.ToString("yyyy-MM", CultureInfo.InvariantCulture);
+    }
+
+    /// <summary>
+    /// 归一化金额精度。
+    /// </summary>
+    public static decimal RoundAmount(decimal value)
+    {
+        return decimal.Round(value, 2, MidpointRounding.AwayFromZero);
+    }
+
+    /// <summary>
+    /// 构建录入页 DTO。
+    /// </summary>
+    public static FinanceCostEntryDto ToEntryDto(FinanceCostMonthSnapshot snapshot)
+    {
+        // 1. 计算总成本与成本率。
+        var totalCost = RoundAmount(snapshot.Categories.Sum(item => item.TotalAmount));
+        var costRate = snapshot.MonthRevenue > 0
+            ? RoundAmount(totalCost / snapshot.MonthRevenue * 100m)
+            : 0m;
+
+        // 2. 映射分类与明细。
+        var categories = snapshot.Categories.Select(category =>
+        {
+            var percentage = totalCost > 0
+                ? RoundAmount(category.TotalAmount / totalCost * 100m)
+                : 0m;
+
+            return new FinanceCostEntryCategoryDto
+            {
+                Category = ToCategoryCode(category.Category),
+                CategoryText = ToCategoryText(category.Category),
+                TotalAmount = RoundAmount(category.TotalAmount),
+                Percentage = percentage,
+                Items = category.Items
+                    .OrderBy(item => item.SortOrder)
+                    .ThenBy(item => item.ItemName)
+                    .Select(item => new FinanceCostEntryDetailDto
+                    {
+                        ItemId = item.ItemId?.ToString(CultureInfo.InvariantCulture),
+                        ItemName = item.ItemName,
+                        Amount = RoundAmount(item.Amount),
+                        Quantity = item.Quantity.HasValue ? RoundAmount(item.Quantity.Value) : null,
+                        UnitPrice = item.UnitPrice.HasValue ? RoundAmount(item.UnitPrice.Value) : null,
+                        SortOrder = item.SortOrder
+                    })
+                    .ToList()
+            };
+        }).ToList();
+
+        return new FinanceCostEntryDto
+        {
+            Dimension = ToDimensionCode(snapshot.Dimension),
+            StoreId = snapshot.StoreId?.ToString(CultureInfo.InvariantCulture),
+            Month = ToMonthText(snapshot.CostMonth),
+            MonthRevenue = RoundAmount(snapshot.MonthRevenue),
+            TotalCost = totalCost,
+            CostRate = costRate,
+            Categories = categories
+        };
+    }
+
+    /// <summary>
+    /// 构建分析页 DTO。
+    /// </summary>
+    public static FinanceCostAnalysisDto ToAnalysisDto(FinanceCostAnalysisSnapshot snapshot)
+    {
+        // 1. 计算统计指标。
+        var averageCostPerPaidOrder = snapshot.CurrentPaidOrderCount > 0
+            ? RoundAmount(snapshot.CurrentTotalCost / snapshot.CurrentPaidOrderCount)
+            : 0m;
+        var foodCostRate = snapshot.CurrentRevenue > 0
+            ? RoundAmount(snapshot.CurrentFoodAmount / snapshot.CurrentRevenue * 100m)
+            : 0m;
+
+        // 2. 映射趋势与明细表。
+        var trend = snapshot.Trends
+            .OrderBy(item => item.MonthStartUtc)
+            .Select(item =>
+            {
+                var costRate = item.Revenue > 0
+                    ? RoundAmount(item.TotalCost / item.Revenue * 100m)
+                    : 0m;
+
+                return new FinanceCostTrendPointDto
+                {
+                    Month = ToMonthText(item.MonthStartUtc),
+                    TotalCost = RoundAmount(item.TotalCost),
+                    Revenue = RoundAmount(item.Revenue),
+                    CostRate = costRate
+                };
+            })
+            .ToList();
+
+        var detailRows = snapshot.DetailRows
+            .OrderByDescending(item => item.MonthStartUtc)
+            .Select(item =>
+            {
+                var costRate = item.Revenue > 0
+                    ? RoundAmount(item.TotalCost / item.Revenue * 100m)
+                    : 0m;
+
+                return new FinanceCostMonthlyDetailRowDto
+                {
+                    Month = ToMonthText(item.MonthStartUtc),
+                    FoodAmount = RoundAmount(item.FoodAmount),
+                    LaborAmount = RoundAmount(item.LaborAmount),
+                    FixedAmount = RoundAmount(item.FixedAmount),
+                    PackagingAmount = RoundAmount(item.PackagingAmount),
+                    TotalCost = RoundAmount(item.TotalCost),
+                    CostRate = costRate
+                };
+            })
+            .ToList();
+
+        // 3. 构建成本构成。
+        var totalCost = RoundAmount(snapshot.CurrentTotalCost);
+        var composition = snapshot.CurrentCategories
+            .OrderBy(item => item.Category)
+            .Select(item => new FinanceCostCompositionItemDto
+            {
+                Category = ToCategoryCode(item.Category),
+                CategoryText = ToCategoryText(item.Category),
+                Amount = RoundAmount(item.TotalAmount),
+                Percentage = totalCost > 0
+                    ? RoundAmount(item.TotalAmount / totalCost * 100m)
+                    : 0m
+            })
+            .ToList();
+
+        return new FinanceCostAnalysisDto
+        {
+            Dimension = ToDimensionCode(snapshot.Dimension),
+            StoreId = snapshot.StoreId?.ToString(CultureInfo.InvariantCulture),
+            Month = ToMonthText(snapshot.CostMonth),
+            Stats = new FinanceCostAnalysisStatsDto
+            {
+                TotalCost = totalCost,
+                FoodCostRate = foodCostRate,
+                AverageCostPerPaidOrder = averageCostPerPaidOrder,
+                MonthOnMonthChangeRate = RoundAmount(snapshot.MonthOnMonthChangeRate),
+                Revenue = RoundAmount(snapshot.CurrentRevenue),
+                PaidOrderCount = snapshot.CurrentPaidOrderCount
+            },
+            Trend = trend,
+            Composition = composition,
+            DetailRows = detailRows
+        };
+    }
+
+    /// <summary>
+    /// 归一化为月份起始 UTC 时间。
+    /// </summary>
+    public static DateTime NormalizeMonthStart(DateTime value)
+    {
+        var utcValue = value.Kind switch
+        {
+            DateTimeKind.Utc => value,
+            DateTimeKind.Local => value.ToUniversalTime(),
+            _ => DateTime.SpecifyKind(value, DateTimeKind.Utc)
+        };
+
+        return new DateTime(utcValue.Year, utcValue.Month, 1, 0, 0, 0, DateTimeKind.Utc);
+    }
+}

src/Application/TakeoutSaaS.Application/App/Finance/Cost/Handlers/GetFinanceCostAnalysisQueryHandler.cs

@@ -0,0 +1,36 @@
+using MediatR;
+using TakeoutSaaS.Application.App.Finance.Cost.Dto;
+using TakeoutSaaS.Application.App.Finance.Cost.Queries;
+using TakeoutSaaS.Domain.Finance.Repositories;
+using TakeoutSaaS.Shared.Abstractions.Tenancy;
+
+namespace TakeoutSaaS.Application.App.Finance.Cost.Handlers;
+
+/// <summary>
+/// 成本分析查询处理器。
+/// </summary>
+public sealed class GetFinanceCostAnalysisQueryHandler(
+    IFinanceCostRepository financeCostRepository,
+    ITenantProvider tenantProvider)
+    : IRequestHandler<GetFinanceCostAnalysisQuery, FinanceCostAnalysisDto>
+{
+    /// <inheritdoc />
+    public async Task<FinanceCostAnalysisDto> Handle(
+        GetFinanceCostAnalysisQuery request,
+        CancellationToken cancellationToken)
+    {
+        // 1. 读取租户上下文并查询分析快照。
+        var tenantId = tenantProvider.GetCurrentTenantId();
+        var normalizedMonth = FinanceCostMapping.NormalizeMonthStart(request.CostMonth);
+        var snapshot = await financeCostRepository.GetAnalysisSnapshotAsync(
+            tenantId,
+            request.Dimension,
+            request.StoreId,
+            normalizedMonth,
+            request.TrendMonthCount,
+            cancellationToken);
+
+        // 2. 映射 DTO 返回。
+        return FinanceCostMapping.ToAnalysisDto(snapshot);
+    }
+}

src/Application/TakeoutSaaS.Application/App/Finance/Cost/Handlers/GetFinanceCostEntryQueryHandler.cs

@@ -0,0 +1,35 @@
+using MediatR;
+using TakeoutSaaS.Application.App.Finance.Cost.Dto;
+using TakeoutSaaS.Application.App.Finance.Cost.Queries;
+using TakeoutSaaS.Domain.Finance.Repositories;
+using TakeoutSaaS.Shared.Abstractions.Tenancy;
+
+namespace TakeoutSaaS.Application.App.Finance.Cost.Handlers;
+
+/// <summary>
+/// 成本录入查询处理器。
+/// </summary>
+public sealed class GetFinanceCostEntryQueryHandler(
+    IFinanceCostRepository financeCostRepository,
+    ITenantProvider tenantProvider)
+    : IRequestHandler<GetFinanceCostEntryQuery, FinanceCostEntryDto>
+{
+    /// <inheritdoc />
+    public async Task<FinanceCostEntryDto> Handle(
+        GetFinanceCostEntryQuery request,
+        CancellationToken cancellationToken)
+    {
+        // 1. 读取租户上下文并查询月度快照。
+        var tenantId = tenantProvider.GetCurrentTenantId();
+        var normalizedMonth = FinanceCostMapping.NormalizeMonthStart(request.CostMonth);
+        var snapshot = await financeCostRepository.GetMonthSnapshotAsync(
+            tenantId,
+            request.Dimension,
+            request.StoreId,
+            normalizedMonth,
+            cancellationToken);
+
+        // 2. 映射 DTO 返回。
+        return FinanceCostMapping.ToEntryDto(snapshot);
+    }
+}

src/Application/TakeoutSaaS.Application/App/Finance/Cost/Handlers/SaveFinanceCostEntryCommandHandler.cs

@@ -0,0 +1,66 @@
+using MediatR;
+using TakeoutSaaS.Application.App.Finance.Cost.Commands;
+using TakeoutSaaS.Application.App.Finance.Cost.Dto;
+using TakeoutSaaS.Domain.Finance.Models;
+using TakeoutSaaS.Domain.Finance.Repositories;
+using TakeoutSaaS.Shared.Abstractions.Tenancy;
+
+namespace TakeoutSaaS.Application.App.Finance.Cost.Handlers;
+
+/// <summary>
+/// 成本录入保存处理器。
+/// </summary>
+public sealed class SaveFinanceCostEntryCommandHandler(
+    IFinanceCostRepository financeCostRepository,
+    ITenantProvider tenantProvider)
+    : IRequestHandler<SaveFinanceCostEntryCommand, FinanceCostEntryDto>
+{
+    /// <inheritdoc />
+    public async Task<FinanceCostEntryDto> Handle(
+        SaveFinanceCostEntryCommand request,
+        CancellationToken cancellationToken)
+    {
+        // 1. 归一化入参并组装仓储快照模型。
+        var tenantId = tenantProvider.GetCurrentTenantId();
+        var normalizedMonth = FinanceCostMapping.NormalizeMonthStart(request.CostMonth);
+        var categories = request.Categories.Select(category => new FinanceCostCategorySnapshot
+        {
+            Category = category.Category,
+            TotalAmount = FinanceCostMapping.RoundAmount(category.TotalAmount),
+            Items = (category.Items ?? [])
+                .Select(item => new FinanceCostDetailItemSnapshot
+                {
+                    ItemId = item.ItemId,
+                    ItemName = item.ItemName,
+                    Amount = FinanceCostMapping.RoundAmount(item.Amount),
+                    Quantity = item.Quantity.HasValue
+                        ? FinanceCostMapping.RoundAmount(item.Quantity.Value)
+                        : null,
+                    UnitPrice = item.UnitPrice.HasValue
+                        ? FinanceCostMapping.RoundAmount(item.UnitPrice.Value)
+                        : null,
+                    SortOrder = item.SortOrder
+                })
+                .ToList()
+        }).ToList();
+
+        // 2. 持久化保存并重新查询最新快照。
+        await financeCostRepository.SaveMonthSnapshotAsync(
+            tenantId,
+            request.Dimension,
+            request.StoreId,
+            normalizedMonth,
+            categories,
+            cancellationToken);
+
+        var snapshot = await financeCostRepository.GetMonthSnapshotAsync(
+            tenantId,
+            request.Dimension,
+            request.StoreId,
+            normalizedMonth,
+            cancellationToken);
+
+        // 3. 映射为页面 DTO 返回。
+        return FinanceCostMapping.ToEntryDto(snapshot);
+    }
+}

src/Application/TakeoutSaaS.Application/App/Finance/Cost/Queries/GetFinanceCostAnalysisQuery.cs

@@ -0,0 +1,31 @@
+using MediatR;
+using TakeoutSaaS.Application.App.Finance.Cost.Dto;
+using TakeoutSaaS.Domain.Finance.Enums;
+
+namespace TakeoutSaaS.Application.App.Finance.Cost.Queries;
+
+/// <summary>
+/// 查询成本分析页数据。
+/// </summary>
+public sealed class GetFinanceCostAnalysisQuery : IRequest<FinanceCostAnalysisDto>
+{
+    /// <summary>
+    /// 统计维度。
+    /// </summary>
+    public FinanceCostDimension Dimension { get; init; } = FinanceCostDimension.Tenant;
+
+    /// <summary>
+    /// 门店标识（门店维度必填）。
+    /// </summary>
+    public long? StoreId { get; init; }
+
+    /// <summary>
+    /// 目标月份（UTC 每月第一天）。
+    /// </summary>
+    public DateTime CostMonth { get; init; } = DateTime.UtcNow;
+
+    /// <summary>
+    /// 趋势月份数量。
+    /// </summary>
+    public int TrendMonthCount { get; init; } = 6;
+}

src/Application/TakeoutSaaS.Application/App/Finance/Cost/Queries/GetFinanceCostEntryQuery.cs

@@ -0,0 +1,26 @@
+using MediatR;
+using TakeoutSaaS.Application.App.Finance.Cost.Dto;
+using TakeoutSaaS.Domain.Finance.Enums;
+
+namespace TakeoutSaaS.Application.App.Finance.Cost.Queries;
+
+/// <summary>
+/// 查询成本录入页数据。
+/// </summary>
+public sealed class GetFinanceCostEntryQuery : IRequest<FinanceCostEntryDto>
+{
+    /// <summary>
+    /// 统计维度。
+    /// </summary>
+    public FinanceCostDimension Dimension { get; init; } = FinanceCostDimension.Tenant;
+
+    /// <summary>
+    /// 门店标识（门店维度必填）。
+    /// </summary>
+    public long? StoreId { get; init; }
+
+    /// <summary>
+    /// 目标月份（UTC 每月第一天）。
+    /// </summary>
+    public DateTime CostMonth { get; init; } = DateTime.UtcNow;
+}

src/Application/TakeoutSaaS.Application/App/Finance/Cost/Validators/GetFinanceCostAnalysisQueryValidator.cs

@@ -0,0 +1,46 @@
+using FluentValidation;
+using TakeoutSaaS.Application.App.Finance.Cost.Queries;
+using TakeoutSaaS.Domain.Finance.Enums;
+
+namespace TakeoutSaaS.Application.App.Finance.Cost.Validators;
+
+/// <summary>
+/// 成本分析查询验证器。
+/// </summary>
+public sealed class GetFinanceCostAnalysisQueryValidator : AbstractValidator<GetFinanceCostAnalysisQuery>
+{
+    /// <summary>
+    /// 初始化验证规则。
+    /// </summary>
+    public GetFinanceCostAnalysisQueryValidator()
+    {
+        RuleFor(x => x.Dimension)
+            .Must(value => value is FinanceCostDimension.Tenant or FinanceCostDimension.Store)
+            .WithMessage("dimension 非法");
+
+        RuleFor(x => x)
+            .Must(query =>
+                query.Dimension != FinanceCostDimension.Store ||
+                (query.StoreId.HasValue && query.StoreId.Value > 0))
+            .WithMessage("storeId 非法");
+
+        RuleFor(x => x.CostMonth)
+            .Must(IsMonthInExpectedRange)
+            .WithMessage("month 非法");
+
+        RuleFor(x => x.TrendMonthCount)
+            .InclusiveBetween(3, 12);
+    }
+
+    private static bool IsMonthInExpectedRange(DateTime value)
+    {
+        var month = value.Kind switch
+        {
+            DateTimeKind.Utc => value,
+            DateTimeKind.Local => value.ToUniversalTime(),
+            _ => DateTime.SpecifyKind(value, DateTimeKind.Utc)
+        };
+
+        return month.Year is >= 2000 and <= 2100;
+    }
+}

src/Application/TakeoutSaaS.Application/App/Finance/Cost/Validators/GetFinanceCostEntryQueryValidator.cs

@@ -0,0 +1,43 @@
+using FluentValidation;
+using TakeoutSaaS.Application.App.Finance.Cost.Queries;
+using TakeoutSaaS.Domain.Finance.Enums;
+
+namespace TakeoutSaaS.Application.App.Finance.Cost.Validators;
+
+/// <summary>
+/// 成本录入查询验证器。
+/// </summary>
+public sealed class GetFinanceCostEntryQueryValidator : AbstractValidator<GetFinanceCostEntryQuery>
+{
+    /// <summary>
+    /// 初始化验证规则。
+    /// </summary>
+    public GetFinanceCostEntryQueryValidator()
+    {
+        RuleFor(x => x.Dimension)
+            .Must(value => value is FinanceCostDimension.Tenant or FinanceCostDimension.Store)
+            .WithMessage("dimension 非法");
+
+        RuleFor(x => x)
+            .Must(query =>
+                query.Dimension != FinanceCostDimension.Store ||
+                (query.StoreId.HasValue && query.StoreId.Value > 0))
+            .WithMessage("storeId 非法");
+
+        RuleFor(x => x.CostMonth)
+            .Must(IsMonthInExpectedRange)
+            .WithMessage("month 非法");
+    }
+
+    private static bool IsMonthInExpectedRange(DateTime value)
+    {
+        var month = value.Kind switch
+        {
+            DateTimeKind.Utc => value,
+            DateTimeKind.Local => value.ToUniversalTime(),
+            _ => DateTime.SpecifyKind(value, DateTimeKind.Utc)
+        };
+
+        return month.Year is >= 2000 and <= 2100;
+    }
+}

src/Application/TakeoutSaaS.Application/App/Finance/Cost/Validators/SaveFinanceCostEntryCommandValidator.cs

@@ -0,0 +1,120 @@
+using FluentValidation;
+using TakeoutSaaS.Application.App.Finance.Cost.Commands;
+using TakeoutSaaS.Domain.Finance.Enums;
+
+namespace TakeoutSaaS.Application.App.Finance.Cost.Validators;
+
+/// <summary>
+/// 成本录入保存验证器。
+/// </summary>
+public sealed class SaveFinanceCostEntryCommandValidator : AbstractValidator<SaveFinanceCostEntryCommand>
+{
+    /// <summary>
+    /// 初始化验证规则。
+    /// </summary>
+    public SaveFinanceCostEntryCommandValidator()
+    {
+        RuleFor(x => x.Dimension)
+            .Must(value => value is FinanceCostDimension.Tenant or FinanceCostDimension.Store)
+            .WithMessage("dimension 非法");
+
+        RuleFor(x => x)
+            .Must(command =>
+                command.Dimension != FinanceCostDimension.Store ||
+                (command.StoreId.HasValue && command.StoreId.Value > 0))
+            .WithMessage("storeId 非法");
+
+        RuleFor(x => x.CostMonth)
+            .Must(IsMonthInExpectedRange)
+            .WithMessage("month 非法");
+
+        RuleFor(x => x.Categories)
+            .NotNull()
+            .Must(categories => categories.Count > 0)
+            .WithMessage("categories 不能为空");
+
+        RuleFor(x => x.Categories)
+            .Must(HaveDistinctCategories)
+            .WithMessage("分类重复");
+
+        RuleForEach(x => x.Categories)
+            .SetValidator(new SaveFinanceCostCategoryCommandItemValidator());
+    }
+
+    private static bool HaveDistinctCategories(IReadOnlyList<SaveFinanceCostCategoryCommandItem> categories)
+    {
+        var normalized = (categories ?? [])
+            .Select(item => item.Category)
+            .Where(value => value != default)
+            .ToList();
+
+        return normalized.Count == normalized.Distinct().Count();
+    }
+
+    private static bool IsMonthInExpectedRange(DateTime value)
+    {
+        var month = value.Kind switch
+        {
+            DateTimeKind.Utc => value,
+            DateTimeKind.Local => value.ToUniversalTime(),
+            _ => DateTime.SpecifyKind(value, DateTimeKind.Utc)
+        };
+
+        return month.Year is >= 2000 and <= 2100;
+    }
+}
+
+/// <summary>
+/// 成本分类保存项验证器。
+/// </summary>
+public sealed class SaveFinanceCostCategoryCommandItemValidator : AbstractValidator<SaveFinanceCostCategoryCommandItem>
+{
+    /// <summary>
+    /// 初始化验证规则。
+    /// </summary>
+    public SaveFinanceCostCategoryCommandItemValidator()
+    {
+        RuleFor(x => x.Category)
+            .Must(value => value is FinanceCostCategory.FoodMaterial
+                or FinanceCostCategory.Labor
+                or FinanceCostCategory.FixedExpense
+                or FinanceCostCategory.PackagingConsumable)
+            .WithMessage("category 非法");
+
+        RuleFor(x => x.TotalAmount)
+            .GreaterThanOrEqualTo(0);
+
+        RuleForEach(x => x.Items)
+            .SetValidator(new SaveFinanceCostDetailCommandItemValidator());
+    }
+}
+
+/// <summary>
+/// 成本明细保存项验证器。
+/// </summary>
+public sealed class SaveFinanceCostDetailCommandItemValidator : AbstractValidator<SaveFinanceCostDetailCommandItem>
+{
+    /// <summary>
+    /// 初始化验证规则。
+    /// </summary>
+    public SaveFinanceCostDetailCommandItemValidator()
+    {
+        RuleFor(x => x.ItemName)
+            .NotEmpty()
+            .MaximumLength(64);
+
+        RuleFor(x => x.Amount)
+            .GreaterThanOrEqualTo(0);
+
+        RuleFor(x => x.Quantity)
+            .GreaterThanOrEqualTo(0)
+            .When(x => x.Quantity.HasValue);
+
+        RuleFor(x => x.UnitPrice)
+            .GreaterThanOrEqualTo(0)
+            .When(x => x.UnitPrice.HasValue);
+
+        RuleFor(x => x.SortOrder)
+            .GreaterThanOrEqualTo(0);
+    }
+}

src/Application/TakeoutSaaS.Application/App/Finance/Invoice/Commands/ApplyFinanceInvoiceRecordCommand.cs

@@ -0,0 +1,60 @@
+using MediatR;
+using TakeoutSaaS.Application.App.Finance.Invoice.Dto;
+
+namespace TakeoutSaaS.Application.App.Finance.Invoice.Commands;
+
+/// <summary>
+/// 申请发票记录命令。
+/// </summary>
+public sealed class ApplyFinanceInvoiceRecordCommand : IRequest<FinanceInvoiceRecordDetailDto>
+{
+    /// <summary>
+    /// 申请人。
+    /// </summary>
+    public string ApplicantName { get; init; } = string.Empty;
+
+    /// <summary>
+    /// 开票抬头（公司名）。
+    /// </summary>
+    public string CompanyName { get; init; } = string.Empty;
+
+    /// <summary>
+    /// 纳税人识别号。
+    /// </summary>
+    public string? TaxpayerNumber { get; init; }
+
+    /// <summary>
+    /// 发票类型（normal/special）。
+    /// </summary>
+    public string InvoiceType { get; init; } = "normal";
+
+    /// <summary>
+    /// 开票金额。
+    /// </summary>
+    public decimal Amount { get; init; }
+
+    /// <summary>
+    /// 关联订单号。
+    /// </summary>
+    public string OrderNo { get; init; } = string.Empty;
+
+    /// <summary>
+    /// 接收邮箱。
+    /// </summary>
+    public string? ContactEmail { get; init; }
+
+    /// <summary>
+    /// 联系电话。
+    /// </summary>
+    public string? ContactPhone { get; init; }
+
+    /// <summary>
+    /// 申请备注。
+    /// </summary>
+    public string? ApplyRemark { get; init; }
+
+    /// <summary>
+    /// 申请时间（可空，默认当前 UTC）。
+    /// </summary>
+    public DateTime? AppliedAt { get; init; }
+}

src/Application/TakeoutSaaS.Application/App/Finance/Invoice/Commands/IssueFinanceInvoiceRecordCommand.cs

@@ -0,0 +1,25 @@
+using MediatR;
+using TakeoutSaaS.Application.App.Finance.Invoice.Dto;
+
+namespace TakeoutSaaS.Application.App.Finance.Invoice.Commands;
+
+/// <summary>
+/// 开票命令。
+/// </summary>
+public sealed class IssueFinanceInvoiceRecordCommand : IRequest<FinanceInvoiceIssueResultDto>
+{
+    /// <summary>
+    /// 发票记录 ID。
+    /// </summary>
+    public long RecordId { get; init; }
+
+    /// <summary>
+    /// 接收邮箱（可选，传入会覆盖原值）。
+    /// </summary>
+    public string? ContactEmail { get; init; }
+
+    /// <summary>
+    /// 开票备注。
+    /// </summary>
+    public string? IssueRemark { get; init; }
+}

src/Application/TakeoutSaaS.Application/App/Finance/Invoice/Commands/SaveFinanceInvoiceSettingCommand.cs

@@ -0,0 +1,60 @@
+using MediatR;
+using TakeoutSaaS.Application.App.Finance.Invoice.Dto;
+
+namespace TakeoutSaaS.Application.App.Finance.Invoice.Commands;
+
+/// <summary>
+/// 保存发票设置命令。
+/// </summary>
+public sealed class SaveFinanceInvoiceSettingCommand : IRequest<FinanceInvoiceSettingDto>
+{
+    /// <summary>
+    /// 企业名称。
+    /// </summary>
+    public string CompanyName { get; init; } = string.Empty;
+
+    /// <summary>
+    /// 纳税人识别号。
+    /// </summary>
+    public string TaxpayerNumber { get; init; } = string.Empty;
+
+    /// <summary>
+    /// 注册地址。
+    /// </summary>
+    public string? RegisteredAddress { get; init; }
+
+    /// <summary>
+    /// 注册电话。
+    /// </summary>
+    public string? RegisteredPhone { get; init; }
+
+    /// <summary>
+    /// 开户银行。
+    /// </summary>
+    public string? BankName { get; init; }
+
+    /// <summary>
+    /// 银行账号。
+    /// </summary>
+    public string? BankAccount { get; init; }
+
+    /// <summary>
+    /// 是否启用电子普通发票。
+    /// </summary>
+    public bool EnableElectronicNormalInvoice { get; init; }
+
+    /// <summary>
+    /// 是否启用电子专用发票。
+    /// </summary>
+    public bool EnableElectronicSpecialInvoice { get; init; }
+
+    /// <summary>
+    /// 是否启用自动开票。
+    /// </summary>
+    public bool EnableAutoIssue { get; init; }
+
+    /// <summary>
+    /// 自动开票单张最大金额。
+    /// </summary>
+    public decimal AutoIssueMaxAmount { get; init; }
+}

src/Application/TakeoutSaaS.Application/App/Finance/Invoice/Commands/VoidFinanceInvoiceRecordCommand.cs

@@ -0,0 +1,20 @@
+using MediatR;
+using TakeoutSaaS.Application.App.Finance.Invoice.Dto;
+
+namespace TakeoutSaaS.Application.App.Finance.Invoice.Commands;
+
+/// <summary>
+/// 作废发票命令。
+/// </summary>
+public sealed class VoidFinanceInvoiceRecordCommand : IRequest<FinanceInvoiceRecordDetailDto>
+{
+    /// <summary>
+    /// 发票记录 ID。
+    /// </summary>
+    public long RecordId { get; init; }
+
+    /// <summary>
+    /// 作废原因。
+    /// </summary>
+    public string VoidReason { get; init; } = string.Empty;
+}

src/Application/TakeoutSaaS.Application/App/Finance/Invoice/Dto/FinanceInvoiceIssueResultDto.cs

@@ -0,0 +1,47 @@
+namespace TakeoutSaaS.Application.App.Finance.Invoice.Dto;
+
+/// <summary>
+/// 发票开票结果 DTO。
+/// </summary>
+public sealed class FinanceInvoiceIssueResultDto
+{
+    /// <summary>
+    /// 记录 ID。
+    /// </summary>
+    public long RecordId { get; set; }
+
+    /// <summary>
+    /// 发票号码。
+    /// </summary>
+    public string InvoiceNo { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 开票抬头。
+    /// </summary>
+    public string CompanyName { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 金额。
+    /// </summary>
+    public decimal Amount { get; set; }
+
+    /// <summary>
+    /// 接收邮箱。
+    /// </summary>
+    public string? ContactEmail { get; set; }
+
+    /// <summary>
+    /// 开票时间（UTC）。
+    /// </summary>
+    public DateTime IssuedAt { get; set; }
+
+    /// <summary>
+    /// 状态编码。
+    /// </summary>
+    public string Status { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 状态文案。
+    /// </summary>
+    public string StatusText { get; set; } = string.Empty;
+}

src/Application/TakeoutSaaS.Application/App/Finance/Invoice/Dto/FinanceInvoiceRecordDetailDto.cs

@@ -0,0 +1,112 @@
+namespace TakeoutSaaS.Application.App.Finance.Invoice.Dto;
+
+/// <summary>
+/// 发票记录详情 DTO。
+/// </summary>
+public sealed class FinanceInvoiceRecordDetailDto
+{
+    /// <summary>
+    /// 记录 ID。
+    /// </summary>
+    public long RecordId { get; set; }
+
+    /// <summary>
+    /// 发票号码。
+    /// </summary>
+    public string InvoiceNo { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 申请人。
+    /// </summary>
+    public string ApplicantName { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 开票抬头（公司名）。
+    /// </summary>
+    public string CompanyName { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 纳税人识别号。
+    /// </summary>
+    public string? TaxpayerNumber { get; set; }
+
+    /// <summary>
+    /// 发票类型编码。
+    /// </summary>
+    public string InvoiceType { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 发票类型文案。
+    /// </summary>
+    public string InvoiceTypeText { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 金额。
+    /// </summary>
+    public decimal Amount { get; set; }
+
+    /// <summary>
+    /// 关联订单号。
+    /// </summary>
+    public string OrderNo { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 接收邮箱。
+    /// </summary>
+    public string? ContactEmail { get; set; }
+
+    /// <summary>
+    /// 联系电话。
+    /// </summary>
+    public string? ContactPhone { get; set; }
+
+    /// <summary>
+    /// 申请备注。
+    /// </summary>
+    public string? ApplyRemark { get; set; }
+
+    /// <summary>
+    /// 状态编码。
+    /// </summary>
+    public string Status { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 状态文案。
+    /// </summary>
+    public string StatusText { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 申请时间（UTC）。
+    /// </summary>
+    public DateTime AppliedAt { get; set; }
+
+    /// <summary>
+    /// 开票时间（UTC）。
+    /// </summary>
+    public DateTime? IssuedAt { get; set; }
+
+    /// <summary>
+    /// 开票人 ID。
+    /// </summary>
+    public long? IssuedByUserId { get; set; }
+
+    /// <summary>
+    /// 开票备注。
+    /// </summary>
+    public string? IssueRemark { get; set; }
+
+    /// <summary>
+    /// 作废时间（UTC）。
+    /// </summary>
+    public DateTime? VoidedAt { get; set; }
+
+    /// <summary>
+    /// 作废人 ID。
+    /// </summary>
+    public long? VoidedByUserId { get; set; }
+
+    /// <summary>
+    /// 作废原因。
+    /// </summary>
+    public string? VoidReason { get; set; }
+}

src/Application/TakeoutSaaS.Application/App/Finance/Invoice/Dto/FinanceInvoiceRecordDto.cs

@@ -0,0 +1,62 @@
+namespace TakeoutSaaS.Application.App.Finance.Invoice.Dto;
+
+/// <summary>
+/// 发票记录列表项 DTO。
+/// </summary>
+public sealed class FinanceInvoiceRecordDto
+{
+    /// <summary>
+    /// 记录 ID。
+    /// </summary>
+    public long RecordId { get; set; }
+
+    /// <summary>
+    /// 发票号码。
+    /// </summary>
+    public string InvoiceNo { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 申请人。
+    /// </summary>
+    public string ApplicantName { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 开票抬头（公司名）。
+    /// </summary>
+    public string CompanyName { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 发票类型编码。
+    /// </summary>
+    public string InvoiceType { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 发票类型文案。
+    /// </summary>
+    public string InvoiceTypeText { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 金额。
+    /// </summary>
+    public decimal Amount { get; set; }
+
+    /// <summary>
+    /// 关联订单号。
+    /// </summary>
+    public string OrderNo { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 状态编码。
+    /// </summary>
+    public string Status { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 状态文案。
+    /// </summary>
+    public string StatusText { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 申请时间（UTC）。
+    /// </summary>
+    public DateTime AppliedAt { get; set; }
+}

src/Application/TakeoutSaaS.Application/App/Finance/Invoice/Dto/FinanceInvoiceRecordListResultDto.cs

@@ -0,0 +1,32 @@
+namespace TakeoutSaaS.Application.App.Finance.Invoice.Dto;
+
+/// <summary>
+/// 发票记录分页结果 DTO。
+/// </summary>
+public sealed class FinanceInvoiceRecordListResultDto
+{
+    /// <summary>
+    /// 列表项。
+    /// </summary>
+    public List<FinanceInvoiceRecordDto> Items { get; set; } = [];
+
+    /// <summary>
+    /// 页码。
+    /// </summary>
+    public int Page { get; set; }
+
+    /// <summary>
+    /// 每页条数。
+    /// </summary>
+    public int PageSize { get; set; }
+
+    /// <summary>
+    /// 总条数。
+    /// </summary>
+    public int TotalCount { get; set; }
+
+    /// <summary>
+    /// 统计。
+    /// </summary>
+    public FinanceInvoiceStatsDto Stats { get; set; } = new();
+}

src/Application/TakeoutSaaS.Application/App/Finance/Invoice/Dto/FinanceInvoiceSettingDto.cs

@@ -0,0 +1,57 @@
+namespace TakeoutSaaS.Application.App.Finance.Invoice.Dto;
+
+/// <summary>
+/// 发票设置 DTO。
+/// </summary>
+public sealed class FinanceInvoiceSettingDto
+{
+    /// <summary>
+    /// 企业名称。
+    /// </summary>
+    public string CompanyName { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 纳税人识别号。
+    /// </summary>
+    public string TaxpayerNumber { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 注册地址。
+    /// </summary>
+    public string? RegisteredAddress { get; set; }
+
+    /// <summary>
+    /// 注册电话。
+    /// </summary>
+    public string? RegisteredPhone { get; set; }
+
+    /// <summary>
+    /// 开户银行。
+    /// </summary>
+    public string? BankName { get; set; }
+
+    /// <summary>
+    /// 银行账号。
+    /// </summary>
+    public string? BankAccount { get; set; }
+
+    /// <summary>
+    /// 是否启用电子普通发票。
+    /// </summary>
+    public bool EnableElectronicNormalInvoice { get; set; }
+
+    /// <summary>
+    /// 是否启用电子专用发票。
+    /// </summary>
+    public bool EnableElectronicSpecialInvoice { get; set; }
+
+    /// <summary>
+    /// 是否启用自动开票。
+    /// </summary>
+    public bool EnableAutoIssue { get; set; }
+
+    /// <summary>
+    /// 自动开票单张最大金额。
+    /// </summary>
+    public decimal AutoIssueMaxAmount { get; set; }
+}

src/Application/TakeoutSaaS.Application/App/Finance/Invoice/Dto/FinanceInvoiceStatsDto.cs

@@ -0,0 +1,27 @@
+namespace TakeoutSaaS.Application.App.Finance.Invoice.Dto;
+
+/// <summary>
+/// 发票统计 DTO。
+/// </summary>
+public sealed class FinanceInvoiceStatsDto
+{
+    /// <summary>
+    /// 本月已开票金额。
+    /// </summary>
+    public decimal CurrentMonthIssuedAmount { get; set; }
+
+    /// <summary>
+    /// 本月已开票张数。
+    /// </summary>
+    public int CurrentMonthIssuedCount { get; set; }
+
+    /// <summary>
+    /// 待开票数量。
+    /// </summary>
+    public int PendingCount { get; set; }
+
+    /// <summary>
+    /// 已作废数量。
+    /// </summary>
+    public int VoidedCount { get; set; }
+}

src/Application/TakeoutSaaS.Application/App/Finance/Invoice/FinanceInvoiceDtoFactory.cs

@@ -0,0 +1,199 @@
+using TakeoutSaaS.Application.App.Finance.Invoice.Commands;
+using TakeoutSaaS.Application.App.Finance.Invoice.Dto;
+using TakeoutSaaS.Domain.Tenants.Entities;
+using TakeoutSaaS.Domain.Tenants.Enums;
+using TakeoutSaaS.Domain.Tenants.Repositories;
+
+namespace TakeoutSaaS.Application.App.Finance.Invoice;
+
+/// <summary>
+/// 发票模块 DTO 构造器。
+/// </summary>
+internal static class FinanceInvoiceDtoFactory
+{
+    public static FinanceInvoiceSettingDto CreateDefaultSettingDto()
+    {
+        return new FinanceInvoiceSettingDto
+        {
+            CompanyName = string.Empty,
+            TaxpayerNumber = string.Empty,
+            RegisteredAddress = null,
+            RegisteredPhone = null,
+            BankName = null,
+            BankAccount = null,
+            EnableElectronicNormalInvoice = true,
+            EnableElectronicSpecialInvoice = false,
+            EnableAutoIssue = false,
+            AutoIssueMaxAmount = 10_000m
+        };
+    }
+
+    public static FinanceInvoiceSettingDto ToSettingDto(TenantInvoiceSetting source)
+    {
+        return new FinanceInvoiceSettingDto
+        {
+            CompanyName = source.CompanyName,
+            TaxpayerNumber = source.TaxpayerNumber,
+            RegisteredAddress = source.RegisteredAddress,
+            RegisteredPhone = source.RegisteredPhone,
+            BankName = source.BankName,
+            BankAccount = source.BankAccount,
+            EnableElectronicNormalInvoice = source.EnableElectronicNormalInvoice,
+            EnableElectronicSpecialInvoice = source.EnableElectronicSpecialInvoice,
+            EnableAutoIssue = source.EnableAutoIssue,
+            AutoIssueMaxAmount = decimal.Round(source.AutoIssueMaxAmount, 2, MidpointRounding.AwayFromZero)
+        };
+    }
+
+    public static TenantInvoiceSetting CreateSettingEntity(
+        SaveFinanceInvoiceSettingCommand request,
+        string companyName,
+        string taxpayerNumber,
+        string? registeredAddress,
+        string? registeredPhone,
+        string? bankName,
+        string? bankAccount,
+        decimal autoIssueMaxAmount)
+    {
+        return new TenantInvoiceSetting
+        {
+            CompanyName = companyName,
+            TaxpayerNumber = taxpayerNumber,
+            RegisteredAddress = registeredAddress,
+            RegisteredPhone = registeredPhone,
+            BankName = bankName,
+            BankAccount = bankAccount,
+            EnableElectronicNormalInvoice = request.EnableElectronicNormalInvoice,
+            EnableElectronicSpecialInvoice = request.EnableElectronicSpecialInvoice,
+            EnableAutoIssue = request.EnableAutoIssue,
+            AutoIssueMaxAmount = autoIssueMaxAmount
+        };
+    }
+
+    public static void ApplySettingChanges(
+        TenantInvoiceSetting entity,
+        SaveFinanceInvoiceSettingCommand request,
+        string companyName,
+        string taxpayerNumber,
+        string? registeredAddress,
+        string? registeredPhone,
+        string? bankName,
+        string? bankAccount,
+        decimal autoIssueMaxAmount)
+    {
+        entity.CompanyName = companyName;
+        entity.TaxpayerNumber = taxpayerNumber;
+        entity.RegisteredAddress = registeredAddress;
+        entity.RegisteredPhone = registeredPhone;
+        entity.BankName = bankName;
+        entity.BankAccount = bankAccount;
+        entity.EnableElectronicNormalInvoice = request.EnableElectronicNormalInvoice;
+        entity.EnableElectronicSpecialInvoice = request.EnableElectronicSpecialInvoice;
+        entity.EnableAutoIssue = request.EnableAutoIssue;
+        entity.AutoIssueMaxAmount = autoIssueMaxAmount;
+    }
+
+    public static FinanceInvoiceStatsDto ToStatsDto(TenantInvoiceRecordStatsSnapshot source)
+    {
+        return new FinanceInvoiceStatsDto
+        {
+            CurrentMonthIssuedAmount = decimal.Round(source.CurrentMonthIssuedAmount, 2, MidpointRounding.AwayFromZero),
+            CurrentMonthIssuedCount = source.CurrentMonthIssuedCount,
+            PendingCount = source.PendingCount,
+            VoidedCount = source.VoidedCount
+        };
+    }
+
+    public static FinanceInvoiceRecordDto ToRecordDto(TenantInvoiceRecord source)
+    {
+        return new FinanceInvoiceRecordDto
+        {
+            RecordId = source.Id,
+            InvoiceNo = source.InvoiceNo,
+            ApplicantName = source.ApplicantName,
+            CompanyName = source.CompanyName,
+            InvoiceType = FinanceInvoiceMapping.ToInvoiceTypeText(source.InvoiceType),
+            InvoiceTypeText = FinanceInvoiceMapping.ToInvoiceTypeDisplayText(source.InvoiceType),
+            Amount = decimal.Round(source.Amount, 2, MidpointRounding.AwayFromZero),
+            OrderNo = source.OrderNo,
+            Status = FinanceInvoiceMapping.ToStatusText(source.Status),
+            StatusText = FinanceInvoiceMapping.ToStatusDisplayText(source.Status),
+            AppliedAt = source.AppliedAt
+        };
+    }
+
+    public static FinanceInvoiceRecordDetailDto ToRecordDetailDto(TenantInvoiceRecord source)
+    {
+        return new FinanceInvoiceRecordDetailDto
+        {
+            RecordId = source.Id,
+            InvoiceNo = source.InvoiceNo,
+            ApplicantName = source.ApplicantName,
+            CompanyName = source.CompanyName,
+            TaxpayerNumber = source.TaxpayerNumber,
+            InvoiceType = FinanceInvoiceMapping.ToInvoiceTypeText(source.InvoiceType),
+            InvoiceTypeText = FinanceInvoiceMapping.ToInvoiceTypeDisplayText(source.InvoiceType),
+            Amount = decimal.Round(source.Amount, 2, MidpointRounding.AwayFromZero),
+            OrderNo = source.OrderNo,
+            ContactEmail = source.ContactEmail,
+            ContactPhone = source.ContactPhone,
+            ApplyRemark = source.ApplyRemark,
+            Status = FinanceInvoiceMapping.ToStatusText(source.Status),
+            StatusText = FinanceInvoiceMapping.ToStatusDisplayText(source.Status),
+            AppliedAt = source.AppliedAt,
+            IssuedAt = source.IssuedAt,
+            IssuedByUserId = source.IssuedByUserId,
+            IssueRemark = source.IssueRemark,
+            VoidedAt = source.VoidedAt,
+            VoidedByUserId = source.VoidedByUserId,
+            VoidReason = source.VoidReason
+        };
+    }
+
+    public static FinanceInvoiceIssueResultDto ToIssueResultDto(TenantInvoiceRecord source)
+    {
+        return new FinanceInvoiceIssueResultDto
+        {
+            RecordId = source.Id,
+            InvoiceNo = source.InvoiceNo,
+            CompanyName = source.CompanyName,
+            Amount = decimal.Round(source.Amount, 2, MidpointRounding.AwayFromZero),
+            ContactEmail = source.ContactEmail,
+            IssuedAt = source.IssuedAt ?? DateTime.UtcNow,
+            Status = FinanceInvoiceMapping.ToStatusText(source.Status),
+            StatusText = FinanceInvoiceMapping.ToStatusDisplayText(source.Status)
+        };
+    }
+
+    public static TenantInvoiceRecord CreateRecordEntity(
+        long tenantId,
+        string invoiceNo,
+        string applicantName,
+        string companyName,
+        string? taxpayerNumber,
+        TenantInvoiceType invoiceType,
+        decimal amount,
+        string orderNo,
+        string? contactEmail,
+        string? contactPhone,
+        string? applyRemark,
+        DateTime appliedAt)
+    {
+        return new TenantInvoiceRecord
+        {
+            TenantId = tenantId,
+            InvoiceNo = invoiceNo,
+            ApplicantName = applicantName,
+            CompanyName = companyName,
+            TaxpayerNumber = taxpayerNumber,
+            InvoiceType = invoiceType,
+            Amount = amount,
+            OrderNo = orderNo,
+            ContactEmail = contactEmail,
+            ContactPhone = contactPhone,
+            ApplyRemark = applyRemark,
+            Status = TenantInvoiceStatus.Pending,
+            AppliedAt = appliedAt
+        };
+    }
+}

src/Application/TakeoutSaaS.Application/App/Finance/Invoice/FinanceInvoiceMapping.cs

@@ -0,0 +1,252 @@
+using System.Net.Mail;
+using TakeoutSaaS.Domain.Tenants.Enums;
+using TakeoutSaaS.Shared.Abstractions.Constants;
+using TakeoutSaaS.Shared.Abstractions.Exceptions;
+
+namespace TakeoutSaaS.Application.App.Finance.Invoice;
+
+/// <summary>
+/// 发票模块映射与参数标准化。
+/// </summary>
+internal static class FinanceInvoiceMapping
+{
+    public static TenantInvoiceType ParseInvoiceTypeRequired(string? value)
+    {
+        return ParseInvoiceTypeOptional(value)
+               ?? throw new BusinessException(ErrorCodes.BadRequest, "invoiceType 参数不合法");
+    }
+
+    public static TenantInvoiceType? ParseInvoiceTypeOptional(string? value)
+    {
+        var normalized = (value ?? string.Empty).Trim().ToLowerInvariant();
+        if (string.IsNullOrWhiteSpace(normalized))
+        {
+            return null;
+        }
+
+        return normalized switch
+        {
+            "normal" => TenantInvoiceType.Normal,
+            "special" => TenantInvoiceType.Special,
+            _ => throw new BusinessException(ErrorCodes.BadRequest, "invoiceType 参数不合法")
+        };
+    }
+
+    public static TenantInvoiceStatus? ParseStatusOptional(string? value)
+    {
+        var normalized = (value ?? string.Empty).Trim().ToLowerInvariant();
+        if (string.IsNullOrWhiteSpace(normalized))
+        {
+            return null;
+        }
+
+        return normalized switch
+        {
+            "pending" => TenantInvoiceStatus.Pending,
+            "issued" => TenantInvoiceStatus.Issued,
+            "voided" => TenantInvoiceStatus.Voided,
+            _ => throw new BusinessException(ErrorCodes.BadRequest, "status 参数不合法")
+        };
+    }
+
+    public static string ToInvoiceTypeText(TenantInvoiceType value)
+    {
+        return value switch
+        {
+            TenantInvoiceType.Normal => "normal",
+            TenantInvoiceType.Special => "special",
+            _ => "normal"
+        };
+    }
+
+    public static string ToInvoiceTypeDisplayText(TenantInvoiceType value)
+    {
+        return value switch
+        {
+            TenantInvoiceType.Normal => "普票",
+            TenantInvoiceType.Special => "专票",
+            _ => "普票"
+        };
+    }
+
+    public static string ToStatusText(TenantInvoiceStatus value)
+    {
+        return value switch
+        {
+            TenantInvoiceStatus.Pending => "pending",
+            TenantInvoiceStatus.Issued => "issued",
+            TenantInvoiceStatus.Voided => "voided",
+            _ => "pending"
+        };
+    }
+
+    public static string ToStatusDisplayText(TenantInvoiceStatus value)
+    {
+        return value switch
+        {
+            TenantInvoiceStatus.Pending => "待开票",
+            TenantInvoiceStatus.Issued => "已开票",
+            TenantInvoiceStatus.Voided => "已作废",
+            _ => "待开票"
+        };
+    }
+
+    public static string NormalizeCompanyName(string? value)
+    {
+        return NormalizeRequiredText(value, "companyName", 128);
+    }
+
+    public static string NormalizeApplicantName(string? value)
+    {
+        return NormalizeRequiredText(value, "applicantName", 64);
+    }
+
+    public static string NormalizeOrderNo(string? value)
+    {
+        return NormalizeRequiredText(value, "orderNo", 32);
+    }
+
+    public static string NormalizeTaxpayerNumber(string? value)
+    {
+        return NormalizeRequiredText(value, "taxpayerNumber", 64);
+    }
+
+    public static string? NormalizeOptionalTaxpayerNumber(string? value)
+    {
+        return NormalizeOptionalText(value, "taxpayerNumber", 64);
+    }
+
+    public static string? NormalizeOptionalKeyword(string? value)
+    {
+        return NormalizeOptionalText(value, "keyword", 64);
+    }
+
+    public static string? NormalizeOptionalEmail(string? value)
+    {
+        var normalized = NormalizeOptionalText(value, "contactEmail", 128);
+        if (normalized is null)
+        {
+            return null;
+        }
+
+        try
+        {
+            _ = new MailAddress(normalized);
+            return normalized;
+        }
+        catch (FormatException)
+        {
+            throw new BusinessException(ErrorCodes.BadRequest, "contactEmail 参数不合法");
+        }
+    }
+
+    public static string? NormalizeOptionalPhone(string? value)
+    {
+        return NormalizeOptionalText(value, "contactPhone", 32);
+    }
+
+    public static string? NormalizeOptionalRemark(string? value, string fieldName, int maxLength = 256)
+    {
+        return NormalizeOptionalText(value, fieldName, maxLength);
+    }
+
+    public static string NormalizeVoidReason(string? value)
+    {
+        return NormalizeRequiredText(value, "voidReason", 256);
+    }
+
+    public static decimal NormalizeAmount(decimal value)
+    {
+        if (value <= 0)
+        {
+            throw new BusinessException(ErrorCodes.BadRequest, "amount 参数不合法");
+        }
+
+        return decimal.Round(value, 2, MidpointRounding.AwayFromZero);
+    }
+
+    public static decimal NormalizeAutoIssueMaxAmount(decimal value)
+    {
+        if (value <= 0)
+        {
+            throw new BusinessException(ErrorCodes.BadRequest, "autoIssueMaxAmount 参数不合法");
+        }
+
+        return decimal.Round(value, 2, MidpointRounding.AwayFromZero);
+    }
+
+    public static (DateTime? StartUtc, DateTime? EndUtc) NormalizeDateRange(DateTime? startUtc, DateTime? endUtc)
+    {
+        DateTime? normalizedStart = null;
+        DateTime? normalizedEnd = null;
+
+        if (startUtc.HasValue)
+        {
+            var utcValue = NormalizeUtc(startUtc.Value);
+            normalizedStart = new DateTime(utcValue.Year, utcValue.Month, utcValue.Day, 0, 0, 0, DateTimeKind.Utc);
+        }
+
+        if (endUtc.HasValue)
+        {
+            var utcValue = NormalizeUtc(endUtc.Value);
+            normalizedEnd = new DateTime(utcValue.Year, utcValue.Month, utcValue.Day, 0, 0, 0, DateTimeKind.Utc)
+                .AddDays(1)
+                .AddTicks(-1);
+        }
+
+        if (normalizedStart.HasValue && normalizedEnd.HasValue && normalizedStart > normalizedEnd)
+        {
+            throw new BusinessException(ErrorCodes.BadRequest, "开始日期不能晚于结束日期");
+        }
+
+        return (normalizedStart, normalizedEnd);
+    }
+
+    public static DateTime NormalizeUtc(DateTime value)
+    {
+        return value.Kind switch
+        {
+            DateTimeKind.Utc => value,
+            DateTimeKind.Local => value.ToUniversalTime(),
+            _ => DateTime.SpecifyKind(value, DateTimeKind.Utc)
+        };
+    }
+
+    public static string BuildInvoiceNo(DateTime nowUtc)
+    {
+        var utcNow = NormalizeUtc(nowUtc);
+        return $"INV{utcNow:yyyyMMddHHmmssfff}{Random.Shared.Next(100, 999)}";
+    }
+
+    private static string NormalizeRequiredText(string? value, string fieldName, int maxLength)
+    {
+        var normalized = (value ?? string.Empty).Trim();
+        if (string.IsNullOrWhiteSpace(normalized))
+        {
+            throw new BusinessException(ErrorCodes.BadRequest, $"{fieldName} 参数不合法");
+        }
+
+        if (normalized.Length > maxLength)
+        {
+            throw new BusinessException(ErrorCodes.BadRequest, $"{fieldName} 长度不能超过 {maxLength}");
+        }
+
+        return normalized;
+    }
+
+    private static string? NormalizeOptionalText(string? value, string fieldName, int maxLength)
+    {
+        var normalized = (value ?? string.Empty).Trim();
+        if (normalized.Length == 0)
+        {
+            return null;
+        }
+
+        if (normalized.Length > maxLength)
+        {
+            throw new BusinessException(ErrorCodes.BadRequest, $"{fieldName} 长度不能超过 {maxLength}");
+        }
+
+        return normalized;
+    }
+}

src/Application/TakeoutSaaS.Application/App/Finance/Invoice/Handlers/ApplyFinanceInvoiceRecordCommandHandler.cs

@@ -0,0 +1,107 @@
+using MediatR;
+using TakeoutSaaS.Application.App.Finance.Invoice.Commands;
+using TakeoutSaaS.Application.App.Finance.Invoice.Dto;
+using TakeoutSaaS.Domain.Tenants.Entities;
+using TakeoutSaaS.Domain.Tenants.Enums;
+using TakeoutSaaS.Domain.Tenants.Repositories;
+using TakeoutSaaS.Shared.Abstractions.Constants;
+using TakeoutSaaS.Shared.Abstractions.Exceptions;
+using TakeoutSaaS.Shared.Abstractions.Security;
+using TakeoutSaaS.Shared.Abstractions.Tenancy;
+
+namespace TakeoutSaaS.Application.App.Finance.Invoice.Handlers;
+
+/// <summary>
+/// 申请发票处理器。
+/// </summary>
+public sealed class ApplyFinanceInvoiceRecordCommandHandler(
+    ITenantInvoiceRepository repository,
+    ITenantProvider tenantProvider,
+    ICurrentUserAccessor currentUserAccessor)
+    : IRequestHandler<ApplyFinanceInvoiceRecordCommand, FinanceInvoiceRecordDetailDto>
+{
+    /// <inheritdoc />
+    public async Task<FinanceInvoiceRecordDetailDto> Handle(
+        ApplyFinanceInvoiceRecordCommand request,
+        CancellationToken cancellationToken)
+    {
+        var tenantId = tenantProvider.GetCurrentTenantId();
+        var invoiceType = FinanceInvoiceMapping.ParseInvoiceTypeRequired(request.InvoiceType);
+        var applicantName = FinanceInvoiceMapping.NormalizeApplicantName(request.ApplicantName);
+        var companyName = FinanceInvoiceMapping.NormalizeCompanyName(request.CompanyName);
+        var taxpayerNumber = FinanceInvoiceMapping.NormalizeOptionalTaxpayerNumber(request.TaxpayerNumber);
+        var amount = FinanceInvoiceMapping.NormalizeAmount(request.Amount);
+        var orderNo = FinanceInvoiceMapping.NormalizeOrderNo(request.OrderNo);
+        var contactEmail = FinanceInvoiceMapping.NormalizeOptionalEmail(request.ContactEmail);
+        var contactPhone = FinanceInvoiceMapping.NormalizeOptionalPhone(request.ContactPhone);
+        var applyRemark = FinanceInvoiceMapping.NormalizeOptionalRemark(request.ApplyRemark, "applyRemark");
+        var appliedAt = request.AppliedAt.HasValue
+            ? FinanceInvoiceMapping.NormalizeUtc(request.AppliedAt.Value)
+            : DateTime.UtcNow;
+
+        if (invoiceType == TenantInvoiceType.Special && string.IsNullOrWhiteSpace(taxpayerNumber))
+        {
+            throw new BusinessException(ErrorCodes.BadRequest, "专票必须填写纳税人识别号");
+        }
+
+        var setting = await repository.GetSettingAsync(tenantId, cancellationToken)
+                      ?? throw new BusinessException(ErrorCodes.BadRequest, "请先完成发票设置");
+        EnsureTypeEnabled(setting, invoiceType);
+
+        var invoiceNo = await GenerateInvoiceNoAsync(tenantId, cancellationToken);
+        var entity = FinanceInvoiceDtoFactory.CreateRecordEntity(
+            tenantId,
+            invoiceNo,
+            applicantName,
+            companyName,
+            taxpayerNumber,
+            invoiceType,
+            amount,
+            orderNo,
+            contactEmail,
+            contactPhone,
+            applyRemark,
+            appliedAt);
+
+        if (setting.EnableAutoIssue && amount <= setting.AutoIssueMaxAmount)
+        {
+            entity.Status = TenantInvoiceStatus.Issued;
+            entity.IssuedAt = DateTime.UtcNow;
+            entity.IssuedByUserId = currentUserAccessor.IsAuthenticated ? currentUserAccessor.UserId : null;
+            entity.IssueRemark = "系统自动开票";
+        }
+
+        await repository.AddRecordAsync(entity, cancellationToken);
+        await repository.SaveChangesAsync(cancellationToken);
+
+        return FinanceInvoiceDtoFactory.ToRecordDetailDto(entity);
+    }
+
+    private static void EnsureTypeEnabled(TenantInvoiceSetting setting, TenantInvoiceType type)
+    {
+        if (type == TenantInvoiceType.Normal && !setting.EnableElectronicNormalInvoice)
+        {
+            throw new BusinessException(ErrorCodes.BadRequest, "电子普通发票未启用");
+        }
+
+        if (type == TenantInvoiceType.Special && !setting.EnableElectronicSpecialInvoice)
+        {
+            throw new BusinessException(ErrorCodes.BadRequest, "电子专用发票未启用");
+        }
+    }
+
+    private async Task<string> GenerateInvoiceNoAsync(long tenantId, CancellationToken cancellationToken)
+    {
+        for (var index = 0; index < 10; index += 1)
+        {
+            var invoiceNo = FinanceInvoiceMapping.BuildInvoiceNo(DateTime.UtcNow);
+            var exists = await repository.ExistsInvoiceNoAsync(tenantId, invoiceNo, cancellationToken);
+            if (!exists)
+            {
+                return invoiceNo;
+            }
+        }
+
+        throw new BusinessException(ErrorCodes.BadRequest, "生成发票号码失败，请稍后重试");
+    }
+}

src/Application/TakeoutSaaS.Application/App/Finance/Invoice/Handlers/GetFinanceInvoiceRecordDetailQueryHandler.cs

@@ -0,0 +1,30 @@
+using MediatR;
+using TakeoutSaaS.Application.App.Finance.Invoice.Dto;
+using TakeoutSaaS.Application.App.Finance.Invoice.Queries;
+using TakeoutSaaS.Domain.Tenants.Repositories;
+using TakeoutSaaS.Shared.Abstractions.Constants;
+using TakeoutSaaS.Shared.Abstractions.Exceptions;
+using TakeoutSaaS.Shared.Abstractions.Tenancy;
+
+namespace TakeoutSaaS.Application.App.Finance.Invoice.Handlers;
+
+/// <summary>
+/// 发票记录详情查询处理器。
+/// </summary>
+public sealed class GetFinanceInvoiceRecordDetailQueryHandler(
+    ITenantInvoiceRepository repository,
+    ITenantProvider tenantProvider)
+    : IRequestHandler<GetFinanceInvoiceRecordDetailQuery, FinanceInvoiceRecordDetailDto>
+{
+    /// <inheritdoc />
+    public async Task<FinanceInvoiceRecordDetailDto> Handle(
+        GetFinanceInvoiceRecordDetailQuery request,
+        CancellationToken cancellationToken)
+    {
+        var tenantId = tenantProvider.GetCurrentTenantId();
+        var record = await repository.FindRecordByIdAsync(tenantId, request.RecordId, cancellationToken)
+                     ?? throw new BusinessException(ErrorCodes.NotFound, "发票记录不存在");
+
+        return FinanceInvoiceDtoFactory.ToRecordDetailDto(record);
+    }
+}

src/Application/TakeoutSaaS.Application/App/Finance/Invoice/Handlers/GetFinanceInvoiceRecordListQueryHandler.cs

@@ -0,0 +1,50 @@
+using MediatR;
+using TakeoutSaaS.Application.App.Finance.Invoice.Dto;
+using TakeoutSaaS.Application.App.Finance.Invoice.Queries;
+using TakeoutSaaS.Domain.Tenants.Repositories;
+using TakeoutSaaS.Shared.Abstractions.Tenancy;
+
+namespace TakeoutSaaS.Application.App.Finance.Invoice.Handlers;
+
+/// <summary>
+/// 发票记录分页查询处理器。
+/// </summary>
+public sealed class GetFinanceInvoiceRecordListQueryHandler(
+    ITenantInvoiceRepository repository,
+    ITenantProvider tenantProvider)
+    : IRequestHandler<GetFinanceInvoiceRecordListQuery, FinanceInvoiceRecordListResultDto>
+{
+    /// <inheritdoc />
+    public async Task<FinanceInvoiceRecordListResultDto> Handle(
+        GetFinanceInvoiceRecordListQuery request,
+        CancellationToken cancellationToken)
+    {
+        var tenantId = tenantProvider.GetCurrentTenantId();
+        var keyword = FinanceInvoiceMapping.NormalizeOptionalKeyword(request.Keyword);
+        var (startUtc, endUtc) = FinanceInvoiceMapping.NormalizeDateRange(request.StartDateUtc, request.EndDateUtc);
+        var page = Math.Max(1, request.Page);
+        var pageSize = Math.Clamp(request.PageSize, 1, 200);
+
+        var (items, totalCount) = await repository.SearchRecordsAsync(
+            tenantId,
+            startUtc,
+            endUtc,
+            request.Status,
+            request.InvoiceType,
+            keyword,
+            page,
+            pageSize,
+            cancellationToken);
+
+        var statsSnapshot = await repository.GetStatsAsync(tenantId, DateTime.UtcNow, cancellationToken);
+
+        return new FinanceInvoiceRecordListResultDto
+        {
+            Items = items.Select(FinanceInvoiceDtoFactory.ToRecordDto).ToList(),
+            Page = page,
+            PageSize = pageSize,
+            TotalCount = totalCount,
+            Stats = FinanceInvoiceDtoFactory.ToStatsDto(statsSnapshot)
+        };
+    }
+}

src/Application/TakeoutSaaS.Application/App/Finance/Invoice/Handlers/GetFinanceInvoiceSettingDetailQueryHandler.cs

@@ -0,0 +1,29 @@
+using MediatR;
+using TakeoutSaaS.Application.App.Finance.Invoice.Dto;
+using TakeoutSaaS.Application.App.Finance.Invoice.Queries;
+using TakeoutSaaS.Domain.Tenants.Repositories;
+using TakeoutSaaS.Shared.Abstractions.Tenancy;
+
+namespace TakeoutSaaS.Application.App.Finance.Invoice.Handlers;
+
+/// <summary>
+/// 发票设置详情查询处理器。
+/// </summary>
+public sealed class GetFinanceInvoiceSettingDetailQueryHandler(
+    ITenantInvoiceRepository repository,
+    ITenantProvider tenantProvider)
+    : IRequestHandler<GetFinanceInvoiceSettingDetailQuery, FinanceInvoiceSettingDto>
+{
+    /// <inheritdoc />
+    public async Task<FinanceInvoiceSettingDto> Handle(
+        GetFinanceInvoiceSettingDetailQuery request,
+        CancellationToken cancellationToken)
+    {
+        var tenantId = tenantProvider.GetCurrentTenantId();
+        var setting = await repository.GetSettingAsync(tenantId, cancellationToken);
+
+        return setting is null
+            ? FinanceInvoiceDtoFactory.CreateDefaultSettingDto()
+            : FinanceInvoiceDtoFactory.ToSettingDto(setting);
+    }
+}

src/Application/TakeoutSaaS.Application/App/Finance/Invoice/Handlers/IssueFinanceInvoiceRecordCommandHandler.cs

@@ -0,0 +1,65 @@
+using MediatR;
+using TakeoutSaaS.Application.App.Finance.Invoice.Commands;
+using TakeoutSaaS.Application.App.Finance.Invoice.Dto;
+using TakeoutSaaS.Domain.Tenants.Entities;
+using TakeoutSaaS.Domain.Tenants.Enums;
+using TakeoutSaaS.Domain.Tenants.Repositories;
+using TakeoutSaaS.Shared.Abstractions.Constants;
+using TakeoutSaaS.Shared.Abstractions.Exceptions;
+using TakeoutSaaS.Shared.Abstractions.Security;
+using TakeoutSaaS.Shared.Abstractions.Tenancy;
+
+namespace TakeoutSaaS.Application.App.Finance.Invoice.Handlers;
+
+/// <summary>
+/// 发票开票处理器。
+/// </summary>
+public sealed class IssueFinanceInvoiceRecordCommandHandler(
+    ITenantInvoiceRepository repository,
+    ITenantProvider tenantProvider,
+    ICurrentUserAccessor currentUserAccessor)
+    : IRequestHandler<IssueFinanceInvoiceRecordCommand, FinanceInvoiceIssueResultDto>
+{
+    /// <inheritdoc />
+    public async Task<FinanceInvoiceIssueResultDto> Handle(
+        IssueFinanceInvoiceRecordCommand request,
+        CancellationToken cancellationToken)
+    {
+        var tenantId = tenantProvider.GetCurrentTenantId();
+        var record = await repository.FindRecordByIdAsync(tenantId, request.RecordId, cancellationToken)
+                     ?? throw new BusinessException(ErrorCodes.NotFound, "发票记录不存在");
+
+        if (record.Status != TenantInvoiceStatus.Pending)
+        {
+            throw new BusinessException(ErrorCodes.BadRequest, "仅待开票记录允许开票");
+        }
+
+        var setting = await repository.GetSettingAsync(tenantId, cancellationToken)
+                      ?? throw new BusinessException(ErrorCodes.BadRequest, "请先完成发票设置");
+        EnsureTypeEnabled(setting, record.InvoiceType);
+
+        record.ContactEmail = FinanceInvoiceMapping.NormalizeOptionalEmail(request.ContactEmail) ?? record.ContactEmail;
+        record.IssueRemark = FinanceInvoiceMapping.NormalizeOptionalRemark(request.IssueRemark, "issueRemark");
+        record.Status = TenantInvoiceStatus.Issued;
+        record.IssuedAt = DateTime.UtcNow;
+        record.IssuedByUserId = currentUserAccessor.IsAuthenticated ? currentUserAccessor.UserId : null;
+
+        await repository.UpdateRecordAsync(record, cancellationToken);
+        await repository.SaveChangesAsync(cancellationToken);
+
+        return FinanceInvoiceDtoFactory.ToIssueResultDto(record);
+    }
+
+    private static void EnsureTypeEnabled(TenantInvoiceSetting setting, TenantInvoiceType type)
+    {
+        if (type == TenantInvoiceType.Normal && !setting.EnableElectronicNormalInvoice)
+        {
+            throw new BusinessException(ErrorCodes.BadRequest, "电子普通发票未启用");
+        }
+
+        if (type == TenantInvoiceType.Special && !setting.EnableElectronicSpecialInvoice)
+        {
+            throw new BusinessException(ErrorCodes.BadRequest, "电子专用发票未启用");
+        }
+    }
+}

src/Application/TakeoutSaaS.Application/App/Finance/Invoice/Handlers/SaveFinanceInvoiceSettingCommandHandler.cs

@@ -0,0 +1,72 @@
+using MediatR;
+using TakeoutSaaS.Application.App.Finance.Invoice.Commands;
+using TakeoutSaaS.Application.App.Finance.Invoice.Dto;
+using TakeoutSaaS.Domain.Tenants.Repositories;
+using TakeoutSaaS.Shared.Abstractions.Constants;
+using TakeoutSaaS.Shared.Abstractions.Exceptions;
+using TakeoutSaaS.Shared.Abstractions.Tenancy;
+
+namespace TakeoutSaaS.Application.App.Finance.Invoice.Handlers;
+
+/// <summary>
+/// 保存发票设置处理器。
+/// </summary>
+public sealed class SaveFinanceInvoiceSettingCommandHandler(
+    ITenantInvoiceRepository repository,
+    ITenantProvider tenantProvider)
+    : IRequestHandler<SaveFinanceInvoiceSettingCommand, FinanceInvoiceSettingDto>
+{
+    /// <inheritdoc />
+    public async Task<FinanceInvoiceSettingDto> Handle(
+        SaveFinanceInvoiceSettingCommand request,
+        CancellationToken cancellationToken)
+    {
+        if (!request.EnableElectronicNormalInvoice && !request.EnableElectronicSpecialInvoice)
+        {
+            throw new BusinessException(ErrorCodes.BadRequest, "至少启用一种发票类型");
+        }
+
+        var tenantId = tenantProvider.GetCurrentTenantId();
+        var companyName = FinanceInvoiceMapping.NormalizeCompanyName(request.CompanyName);
+        var taxpayerNumber = FinanceInvoiceMapping.NormalizeTaxpayerNumber(request.TaxpayerNumber);
+        var registeredAddress = FinanceInvoiceMapping.NormalizeOptionalRemark(request.RegisteredAddress, "registeredAddress", 256);
+        var registeredPhone = FinanceInvoiceMapping.NormalizeOptionalPhone(request.RegisteredPhone);
+        var bankName = FinanceInvoiceMapping.NormalizeOptionalRemark(request.BankName, "bankName", 128);
+        var bankAccount = FinanceInvoiceMapping.NormalizeOptionalRemark(request.BankAccount, "bankAccount", 64);
+        var autoIssueMaxAmount = FinanceInvoiceMapping.NormalizeAutoIssueMaxAmount(request.AutoIssueMaxAmount);
+
+        var setting = await repository.GetSettingAsync(tenantId, cancellationToken);
+        if (setting is null)
+        {
+            setting = FinanceInvoiceDtoFactory.CreateSettingEntity(
+                request,
+                companyName,
+                taxpayerNumber,
+                registeredAddress,
+                registeredPhone,
+                bankName,
+                bankAccount,
+                autoIssueMaxAmount);
+
+            await repository.AddSettingAsync(setting, cancellationToken);
+        }
+        else
+        {
+            FinanceInvoiceDtoFactory.ApplySettingChanges(
+                setting,
+                request,
+                companyName,
+                taxpayerNumber,
+                registeredAddress,
+                registeredPhone,
+                bankName,
+                bankAccount,
+                autoIssueMaxAmount);
+
+            await repository.UpdateSettingAsync(setting, cancellationToken);
+        }
+
+        await repository.SaveChangesAsync(cancellationToken);
+        return FinanceInvoiceDtoFactory.ToSettingDto(setting);
+    }
+}

src/Application/TakeoutSaaS.Application/App/Finance/Invoice/Handlers/VoidFinanceInvoiceRecordCommandHandler.cs

@@ -0,0 +1,46 @@
+using MediatR;
+using TakeoutSaaS.Application.App.Finance.Invoice.Commands;
+using TakeoutSaaS.Application.App.Finance.Invoice.Dto;
+using TakeoutSaaS.Domain.Tenants.Enums;
+using TakeoutSaaS.Domain.Tenants.Repositories;
+using TakeoutSaaS.Shared.Abstractions.Constants;
+using TakeoutSaaS.Shared.Abstractions.Exceptions;
+using TakeoutSaaS.Shared.Abstractions.Security;
+using TakeoutSaaS.Shared.Abstractions.Tenancy;
+
+namespace TakeoutSaaS.Application.App.Finance.Invoice.Handlers;
+
+/// <summary>
+/// 发票作废处理器。
+/// </summary>
+public sealed class VoidFinanceInvoiceRecordCommandHandler(
+    ITenantInvoiceRepository repository,
+    ITenantProvider tenantProvider,
+    ICurrentUserAccessor currentUserAccessor)
+    : IRequestHandler<VoidFinanceInvoiceRecordCommand, FinanceInvoiceRecordDetailDto>
+{
+    /// <inheritdoc />
+    public async Task<FinanceInvoiceRecordDetailDto> Handle(
+        VoidFinanceInvoiceRecordCommand request,
+        CancellationToken cancellationToken)
+    {
+        var tenantId = tenantProvider.GetCurrentTenantId();
+        var record = await repository.FindRecordByIdAsync(tenantId, request.RecordId, cancellationToken)
+                     ?? throw new BusinessException(ErrorCodes.NotFound, "发票记录不存在");
+
+        if (record.Status != TenantInvoiceStatus.Issued)
+        {
+            throw new BusinessException(ErrorCodes.BadRequest, "仅已开票记录允许作废");
+        }
+
+        record.Status = TenantInvoiceStatus.Voided;
+        record.VoidReason = FinanceInvoiceMapping.NormalizeVoidReason(request.VoidReason);
+        record.VoidedAt = DateTime.UtcNow;
+        record.VoidedByUserId = currentUserAccessor.IsAuthenticated ? currentUserAccessor.UserId : null;
+
+        await repository.UpdateRecordAsync(record, cancellationToken);
+        await repository.SaveChangesAsync(cancellationToken);
+
+        return FinanceInvoiceDtoFactory.ToRecordDetailDto(record);
+    }
+}

src/Application/TakeoutSaaS.Application/App/Finance/Invoice/Queries/GetFinanceInvoiceRecordDetailQuery.cs

@@ -0,0 +1,15 @@
+using MediatR;
+using TakeoutSaaS.Application.App.Finance.Invoice.Dto;
+
+namespace TakeoutSaaS.Application.App.Finance.Invoice.Queries;
+
+/// <summary>
+/// 查询发票记录详情。
+/// </summary>
+public sealed class GetFinanceInvoiceRecordDetailQuery : IRequest<FinanceInvoiceRecordDetailDto>
+{
+    /// <summary>
+    /// 发票记录 ID。
+    /// </summary>
+    public long RecordId { get; init; }
+}

src/Application/TakeoutSaaS.Application/App/Finance/Invoice/Queries/GetFinanceInvoiceRecordListQuery.cs

@@ -0,0 +1,46 @@
+using MediatR;
+using TakeoutSaaS.Application.App.Finance.Invoice.Dto;
+using TakeoutSaaS.Domain.Tenants.Enums;
+
+namespace TakeoutSaaS.Application.App.Finance.Invoice.Queries;
+
+/// <summary>
+/// 查询发票记录分页。
+/// </summary>
+public sealed class GetFinanceInvoiceRecordListQuery : IRequest<FinanceInvoiceRecordListResultDto>
+{
+    /// <summary>
+    /// 开始日期（UTC）。
+    /// </summary>
+    public DateTime? StartDateUtc { get; init; }
+
+    /// <summary>
+    /// 结束日期（UTC）。
+    /// </summary>
+    public DateTime? EndDateUtc { get; init; }
+
+    /// <summary>
+    /// 状态筛选。
+    /// </summary>
+    public TenantInvoiceStatus? Status { get; init; }
+
+    /// <summary>
+    /// 类型筛选。
+    /// </summary>
+    public TenantInvoiceType? InvoiceType { get; init; }
+
+    /// <summary>
+    /// 关键词。
+    /// </summary>
+    public string? Keyword { get; init; }
+
+    /// <summary>
+    /// 页码。
+    /// </summary>
+    public int Page { get; init; } = 1;
+
+    /// <summary>
+    /// 每页条数。
+    /// </summary>
+    public int PageSize { get; init; } = 20;
+}

src/Application/TakeoutSaaS.Application/App/Finance/Invoice/Queries/GetFinanceInvoiceSettingDetailQuery.cs

@@ -0,0 +1,11 @@
+using MediatR;
+using TakeoutSaaS.Application.App.Finance.Invoice.Dto;
+
+namespace TakeoutSaaS.Application.App.Finance.Invoice.Queries;
+
+/// <summary>
+/// 查询发票设置详情。
+/// </summary>
+public sealed class GetFinanceInvoiceSettingDetailQuery : IRequest<FinanceInvoiceSettingDto>
+{
+}

src/Application/TakeoutSaaS.Application/App/Finance/Overview/Dto/FinanceOverviewDtos.cs

@@ -0,0 +1,313 @@
+namespace TakeoutSaaS.Application.App.Finance.Overview.Dto;
+
+/// <summary>
+/// 财务概览指标卡 DTO。
+/// </summary>
+public sealed class FinanceOverviewKpiCardDto
+{
+    /// <summary>
+    /// 指标值。
+    /// </summary>
+    public decimal Amount { get; set; }
+
+    /// <summary>
+    /// 对比基准值。
+    /// </summary>
+    public decimal CompareAmount { get; set; }
+
+    /// <summary>
+    /// 变化率（%）。
+    /// </summary>
+    public decimal ChangeRate { get; set; }
+
+    /// <summary>
+    /// 趋势（up/down/flat）。
+    /// </summary>
+    public string Trend { get; set; } = "flat";
+
+    /// <summary>
+    /// 对比文案（较昨日/较上周）。
+    /// </summary>
+    public string CompareLabel { get; set; } = "较昨日";
+}
+
+/// <summary>
+/// 收入趋势点 DTO。
+/// </summary>
+public sealed class FinanceOverviewIncomeTrendPointDto
+{
+    /// <summary>
+    /// 日期（yyyy-MM-dd）。
+    /// </summary>
+    public string Date { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 轴标签（MM/dd）。
+    /// </summary>
+    public string DateLabel { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 实收金额。
+    /// </summary>
+    public decimal Amount { get; set; }
+}
+
+/// <summary>
+/// 收入趋势 DTO。
+/// </summary>
+public sealed class FinanceOverviewIncomeTrendDto
+{
+    /// <summary>
+    /// 近 7 天。
+    /// </summary>
+    public List<FinanceOverviewIncomeTrendPointDto> Last7Days { get; set; } = [];
+
+    /// <summary>
+    /// 近 30 天。
+    /// </summary>
+    public List<FinanceOverviewIncomeTrendPointDto> Last30Days { get; set; } = [];
+}
+
+/// <summary>
+/// 利润趋势点 DTO。
+/// </summary>
+public sealed class FinanceOverviewProfitTrendPointDto
+{
+    /// <summary>
+    /// 日期（yyyy-MM-dd）。
+    /// </summary>
+    public string Date { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 轴标签（MM/dd）。
+    /// </summary>
+    public string DateLabel { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 营收。
+    /// </summary>
+    public decimal RevenueAmount { get; set; }
+
+    /// <summary>
+    /// 成本。
+    /// </summary>
+    public decimal CostAmount { get; set; }
+
+    /// <summary>
+    /// 净利润。
+    /// </summary>
+    public decimal NetProfitAmount { get; set; }
+}
+
+/// <summary>
+/// 利润趋势 DTO。
+/// </summary>
+public sealed class FinanceOverviewProfitTrendDto
+{
+    /// <summary>
+    /// 近 7 天。
+    /// </summary>
+    public List<FinanceOverviewProfitTrendPointDto> Last7Days { get; set; } = [];
+
+    /// <summary>
+    /// 近 30 天。
+    /// </summary>
+    public List<FinanceOverviewProfitTrendPointDto> Last30Days { get; set; } = [];
+}
+
+/// <summary>
+/// 收入构成项 DTO。
+/// </summary>
+public sealed class FinanceOverviewIncomeCompositionItemDto
+{
+    /// <summary>
+    /// 渠道编码（delivery/pickup/dine_in）。
+    /// </summary>
+    public string Channel { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 渠道文案。
+    /// </summary>
+    public string ChannelText { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 金额。
+    /// </summary>
+    public decimal Amount { get; set; }
+
+    /// <summary>
+    /// 占比（%）。
+    /// </summary>
+    public decimal Percentage { get; set; }
+}
+
+/// <summary>
+/// 收入构成 DTO。
+/// </summary>
+public sealed class FinanceOverviewIncomeCompositionDto
+{
+    /// <summary>
+    /// 总实收。
+    /// </summary>
+    public decimal TotalAmount { get; set; }
+
+    /// <summary>
+    /// 构成项。
+    /// </summary>
+    public List<FinanceOverviewIncomeCompositionItemDto> Items { get; set; } = [];
+}
+
+/// <summary>
+/// 成本构成项 DTO。
+/// </summary>
+public sealed class FinanceOverviewCostCompositionItemDto
+{
+    /// <summary>
+    /// 分类编码（food/labor/fixed/packaging/platform）。
+    /// </summary>
+    public string Category { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 分类文案。
+    /// </summary>
+    public string CategoryText { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 金额。
+    /// </summary>
+    public decimal Amount { get; set; }
+
+    /// <summary>
+    /// 占比（%）。
+    /// </summary>
+    public decimal Percentage { get; set; }
+}
+
+/// <summary>
+/// 成本构成 DTO。
+/// </summary>
+public sealed class FinanceOverviewCostCompositionDto
+{
+    /// <summary>
+    /// 总成本。
+    /// </summary>
+    public decimal TotalAmount { get; set; }
+
+    /// <summary>
+    /// 构成项。
+    /// </summary>
+    public List<FinanceOverviewCostCompositionItemDto> Items { get; set; } = [];
+}
+
+/// <summary>
+/// TOP 商品 DTO。
+/// </summary>
+public sealed class FinanceOverviewTopProductItemDto
+{
+    /// <summary>
+    /// 排名。
+    /// </summary>
+    public int Rank { get; set; }
+
+    /// <summary>
+    /// 商品名称。
+    /// </summary>
+    public string ProductName { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 销量。
+    /// </summary>
+    public int SalesQuantity { get; set; }
+
+    /// <summary>
+    /// 营收金额。
+    /// </summary>
+    public decimal RevenueAmount { get; set; }
+
+    /// <summary>
+    /// 营收占比（%）。
+    /// </summary>
+    public decimal Percentage { get; set; }
+}
+
+/// <summary>
+/// TOP 商品区块 DTO。
+/// </summary>
+public sealed class FinanceOverviewTopProductDto
+{
+    /// <summary>
+    /// 统计周期（天）。
+    /// </summary>
+    public int PeriodDays { get; set; } = 30;
+
+    /// <summary>
+    /// 排行数据。
+    /// </summary>
+    public List<FinanceOverviewTopProductItemDto> Items { get; set; } = [];
+}
+
+/// <summary>
+/// 财务概览页面 DTO。
+/// </summary>
+public sealed class FinanceOverviewDashboardDto
+{
+    /// <summary>
+    /// 维度编码（tenant/store）。
+    /// </summary>
+    public string Dimension { get; set; } = "tenant";
+
+    /// <summary>
+    /// 门店标识（门店维度时有值）。
+    /// </summary>
+    public string? StoreId { get; set; }
+
+    /// <summary>
+    /// 今日营业额卡片。
+    /// </summary>
+    public FinanceOverviewKpiCardDto TodayRevenue { get; set; } = new();
+
+    /// <summary>
+    /// 实收卡片。
+    /// </summary>
+    public FinanceOverviewKpiCardDto ActualReceived { get; set; } = new();
+
+    /// <summary>
+    /// 退款卡片。
+    /// </summary>
+    public FinanceOverviewKpiCardDto RefundAmount { get; set; } = new();
+
+    /// <summary>
+    /// 净收入卡片。
+    /// </summary>
+    public FinanceOverviewKpiCardDto NetIncome { get; set; } = new();
+
+    /// <summary>
+    /// 可提现余额卡片。
+    /// </summary>
+    public FinanceOverviewKpiCardDto WithdrawableBalance { get; set; } = new();
+
+    /// <summary>
+    /// 收入趋势。
+    /// </summary>
+    public FinanceOverviewIncomeTrendDto IncomeTrend { get; set; } = new();
+
+    /// <summary>
+    /// 利润趋势。
+    /// </summary>
+    public FinanceOverviewProfitTrendDto ProfitTrend { get; set; } = new();
+
+    /// <summary>
+    /// 收入构成。
+    /// </summary>
+    public FinanceOverviewIncomeCompositionDto IncomeComposition { get; set; } = new();
+
+    /// <summary>
+    /// 成本构成。
+    /// </summary>
+    public FinanceOverviewCostCompositionDto CostComposition { get; set; } = new();
+
+    /// <summary>
+    /// TOP 商品排行。
+    /// </summary>
+    public FinanceOverviewTopProductDto TopProducts { get; set; } = new();
+}

src/Application/TakeoutSaaS.Application/App/Finance/Overview/Handlers/FinanceOverviewMapping.cs

@@ -0,0 +1,245 @@
+using System.Globalization;
+using TakeoutSaaS.Application.App.Finance.Overview.Dto;
+using TakeoutSaaS.Domain.Finance.Enums;
+using TakeoutSaaS.Domain.Finance.Models;
+using TakeoutSaaS.Domain.Orders.Enums;
+
+namespace TakeoutSaaS.Application.App.Finance.Overview.Handlers;
+
+/// <summary>
+/// 财务概览映射与格式化。
+/// </summary>
+internal static class FinanceOverviewMapping
+{
+    /// <summary>
+    /// 构建财务概览页面 DTO。
+    /// </summary>
+    public static FinanceOverviewDashboardDto ToDashboardDto(FinanceOverviewDashboardSnapshot snapshot)
+    {
+        // 1. 指标卡映射。
+        var todayNetIncome = snapshot.Summary.TodayNetReceived - snapshot.Summary.TodayTotalCost;
+        var yesterdayNetIncome = snapshot.Summary.YesterdayNetReceived - snapshot.Summary.YesterdayTotalCost;
+
+        // 2. 近 30/7 天趋势映射。
+        var incomeLast30 = snapshot.IncomeTrend
+            .OrderBy(item => item.BusinessDate)
+            .Select(item => new FinanceOverviewIncomeTrendPointDto
+            {
+                Date = item.BusinessDate.ToString("yyyy-MM-dd", CultureInfo.InvariantCulture),
+                DateLabel = item.BusinessDate.ToString("MM/dd", CultureInfo.InvariantCulture),
+                Amount = RoundAmount(item.NetReceivedAmount)
+            })
+            .ToList();
+        var incomeLast7 = incomeLast30.Skip(Math.Max(0, incomeLast30.Count - 7)).ToList();
+
+        var profitLast30 = snapshot.ProfitTrend
+            .OrderBy(item => item.BusinessDate)
+            .Select(item => new FinanceOverviewProfitTrendPointDto
+            {
+                Date = item.BusinessDate.ToString("yyyy-MM-dd", CultureInfo.InvariantCulture),
+                DateLabel = item.BusinessDate.ToString("MM/dd", CultureInfo.InvariantCulture),
+                RevenueAmount = RoundAmount(item.RevenueAmount),
+                CostAmount = RoundAmount(item.CostAmount),
+                NetProfitAmount = RoundAmount(item.NetProfitAmount)
+            })
+            .ToList();
+        var profitLast7 = profitLast30.Skip(Math.Max(0, profitLast30.Count - 7)).ToList();
+
+        // 3. 收入构成映射。
+        var incomeTotal = RoundAmount(snapshot.IncomeComposition.Sum(item => item.Amount));
+        var incomeItems = snapshot.IncomeComposition
+            .OrderBy(item => GetChannelSort(item.Channel))
+            .Select(item => new FinanceOverviewIncomeCompositionItemDto
+            {
+                Channel = ToChannelCode(item.Channel),
+                ChannelText = ToChannelText(item.Channel),
+                Amount = RoundAmount(item.Amount),
+                Percentage = incomeTotal > 0
+                    ? RoundAmount(item.Amount / incomeTotal * 100m)
+                    : 0m
+            })
+            .ToList();
+
+        // 4. 成本构成映射。
+        var costTotal = RoundAmount(snapshot.CostComposition.Sum(item => item.Amount));
+        var costItems = snapshot.CostComposition
+            .OrderBy(item => GetCostCategorySort(item.CategoryCode))
+            .Select(item => new FinanceOverviewCostCompositionItemDto
+            {
+                Category = item.CategoryCode,
+                CategoryText = ToCostCategoryText(item.CategoryCode),
+                Amount = RoundAmount(item.Amount),
+                Percentage = costTotal > 0
+                    ? RoundAmount(item.Amount / costTotal * 100m)
+                    : 0m
+            })
+            .ToList();
+
+        // 5. TOP10 映射。
+        var topTotalRevenue = snapshot.TopProductTotalRevenue > 0
+            ? snapshot.TopProductTotalRevenue
+            : snapshot.TopProducts.Sum(item => item.RevenueAmount);
+        var topItems = snapshot.TopProducts
+            .OrderByDescending(item => item.RevenueAmount)
+            .ThenByDescending(item => item.SalesQuantity)
+            .Select((item, index) => new FinanceOverviewTopProductItemDto
+            {
+                Rank = index + 1,
+                ProductName = item.ProductName,
+                SalesQuantity = item.SalesQuantity,
+                RevenueAmount = RoundAmount(item.RevenueAmount),
+                Percentage = topTotalRevenue > 0
+                    ? RoundAmount(item.RevenueAmount / topTotalRevenue * 100m)
+                    : 0m
+            })
+            .ToList();
+
+        return new FinanceOverviewDashboardDto
+        {
+            Dimension = ToDimensionCode(snapshot.Dimension),
+            StoreId = snapshot.StoreId?.ToString(CultureInfo.InvariantCulture),
+            TodayRevenue = BuildKpi(snapshot.Summary.TodayGrossRevenue, snapshot.Summary.YesterdayGrossRevenue, "较昨日"),
+            ActualReceived = BuildKpi(snapshot.Summary.TodayNetReceived, snapshot.Summary.YesterdayNetReceived, "较昨日"),
+            RefundAmount = BuildKpi(snapshot.Summary.TodayRefundAmount, snapshot.Summary.YesterdayRefundAmount, "较昨日"),
+            NetIncome = BuildKpi(todayNetIncome, yesterdayNetIncome, "较昨日"),
+            WithdrawableBalance = BuildKpi(
+                snapshot.Summary.WithdrawableBalance,
+                snapshot.Summary.WithdrawableBalanceLastWeek,
+                "较上周"),
+            IncomeTrend = new FinanceOverviewIncomeTrendDto
+            {
+                Last7Days = incomeLast7,
+                Last30Days = incomeLast30
+            },
+            ProfitTrend = new FinanceOverviewProfitTrendDto
+            {
+                Last7Days = profitLast7,
+                Last30Days = profitLast30
+            },
+            IncomeComposition = new FinanceOverviewIncomeCompositionDto
+            {
+                TotalAmount = incomeTotal,
+                Items = incomeItems
+            },
+            CostComposition = new FinanceOverviewCostCompositionDto
+            {
+                TotalAmount = costTotal,
+                Items = costItems
+            },
+            TopProducts = new FinanceOverviewTopProductDto
+            {
+                PeriodDays = 30,
+                Items = topItems
+            }
+        };
+    }
+
+    private static FinanceOverviewKpiCardDto BuildKpi(decimal current, decimal previous, string compareLabel)
+    {
+        var normalizedCurrent = RoundAmount(current);
+        var normalizedPrevious = RoundAmount(previous);
+        return new FinanceOverviewKpiCardDto
+        {
+            Amount = normalizedCurrent,
+            CompareAmount = normalizedPrevious,
+            ChangeRate = CalculateChangeRate(normalizedCurrent, normalizedPrevious),
+            Trend = ResolveTrend(normalizedCurrent, normalizedPrevious),
+            CompareLabel = compareLabel
+        };
+    }
+
+    private static decimal CalculateChangeRate(decimal current, decimal previous)
+    {
+        if (previous == 0m)
+        {
+            return current == 0m ? 0m : 100m;
+        }
+
+        var rate = (current - previous) / previous * 100m;
+        return RoundAmount(rate);
+    }
+
+    private static string ResolveTrend(decimal current, decimal previous)
+    {
+        if (current > previous)
+        {
+            return "up";
+        }
+
+        if (current < previous)
+        {
+            return "down";
+        }
+
+        return "flat";
+    }
+
+    private static string ToDimensionCode(FinanceCostDimension value)
+    {
+        return value == FinanceCostDimension.Store ? "store" : "tenant";
+    }
+
+    private static string ToChannelCode(DeliveryType value)
+    {
+        return value switch
+        {
+            DeliveryType.Delivery => "delivery",
+            DeliveryType.Pickup => "pickup",
+            DeliveryType.DineIn => "dine_in",
+            _ => "delivery"
+        };
+    }
+
+    private static string ToChannelText(DeliveryType value)
+    {
+        return value switch
+        {
+            DeliveryType.Delivery => "外卖",
+            DeliveryType.Pickup => "自提",
+            DeliveryType.DineIn => "堂食",
+            _ => "外卖"
+        };
+    }
+
+    private static int GetChannelSort(DeliveryType value)
+    {
+        return value switch
+        {
+            DeliveryType.Delivery => 0,
+            DeliveryType.Pickup => 1,
+            DeliveryType.DineIn => 2,
+            _ => 9
+        };
+    }
+
+    private static int GetCostCategorySort(string? value)
+    {
+        return (value ?? string.Empty).Trim().ToLowerInvariant() switch
+        {
+            "food" => 0,
+            "labor" => 1,
+            "fixed" => 2,
+            "packaging" => 3,
+            "platform" => 4,
+            _ => 9
+        };
+    }
+
+    private static string ToCostCategoryText(string? value)
+    {
+        return (value ?? string.Empty).Trim().ToLowerInvariant() switch
+        {
+            "food" => "食材",
+            "labor" => "人工",
+            "fixed" => "固定",
+            "packaging" => "包装",
+            "platform" => "平台",
+            _ => "其他"
+        };
+    }
+
+    private static decimal RoundAmount(decimal value)
+    {
+        return decimal.Round(value, 2, MidpointRounding.AwayFromZero);
+    }
+}

src/Application/TakeoutSaaS.Application/App/Finance/Overview/Handlers/GetFinanceOverviewDashboardQueryHandler.cs

@@ -0,0 +1,34 @@
+using MediatR;
+using TakeoutSaaS.Application.App.Finance.Overview.Dto;
+using TakeoutSaaS.Application.App.Finance.Overview.Queries;
+using TakeoutSaaS.Domain.Finance.Repositories;
+using TakeoutSaaS.Shared.Abstractions.Tenancy;
+
+namespace TakeoutSaaS.Application.App.Finance.Overview.Handlers;
+
+/// <summary>
+/// 财务概览查询处理器。
+/// </summary>
+public sealed class GetFinanceOverviewDashboardQueryHandler(
+    IFinanceOverviewRepository financeOverviewRepository,
+    ITenantProvider tenantProvider)
+    : IRequestHandler<GetFinanceOverviewDashboardQuery, FinanceOverviewDashboardDto>
+{
+    /// <inheritdoc />
+    public async Task<FinanceOverviewDashboardDto> Handle(
+        GetFinanceOverviewDashboardQuery request,
+        CancellationToken cancellationToken)
+    {
+        // 1. 拉取租户上下文并读取快照。
+        var tenantId = tenantProvider.GetCurrentTenantId();
+        var snapshot = await financeOverviewRepository.GetDashboardSnapshotAsync(
+            tenantId,
+            request.Dimension,
+            request.StoreId,
+            request.CurrentUtc,
+            cancellationToken);
+
+        // 2. 映射页面 DTO。
+        return FinanceOverviewMapping.ToDashboardDto(snapshot);
+    }
+}

src/Application/TakeoutSaaS.Application/App/Finance/Overview/Queries/GetFinanceOverviewDashboardQuery.cs

@@ -0,0 +1,26 @@
+using MediatR;
+using TakeoutSaaS.Application.App.Finance.Overview.Dto;
+using TakeoutSaaS.Domain.Finance.Enums;
+
+namespace TakeoutSaaS.Application.App.Finance.Overview.Queries;
+
+/// <summary>
+/// 查询财务概览驾驶舱数据。
+/// </summary>
+public sealed class GetFinanceOverviewDashboardQuery : IRequest<FinanceOverviewDashboardDto>
+{
+    /// <summary>
+    /// 统计维度。
+    /// </summary>
+    public FinanceCostDimension Dimension { get; init; } = FinanceCostDimension.Tenant;
+
+    /// <summary>
+    /// 门店标识（门店维度必填）。
+    /// </summary>
+    public long? StoreId { get; init; }
+
+    /// <summary>
+    /// 当前 UTC 时间。
+    /// </summary>
+    public DateTime CurrentUtc { get; init; } = DateTime.UtcNow;
+}

src/Application/TakeoutSaaS.Application/App/Finance/Overview/Validators/GetFinanceOverviewDashboardQueryValidator.cs

@@ -0,0 +1,31 @@
+using FluentValidation;
+using TakeoutSaaS.Application.App.Finance.Overview.Queries;
+using TakeoutSaaS.Domain.Finance.Enums;
+
+namespace TakeoutSaaS.Application.App.Finance.Overview.Validators;
+
+/// <summary>
+/// 财务概览查询验证器。
+/// </summary>
+public sealed class GetFinanceOverviewDashboardQueryValidator : AbstractValidator<GetFinanceOverviewDashboardQuery>
+{
+    /// <summary>
+    /// 初始化验证规则。
+    /// </summary>
+    public GetFinanceOverviewDashboardQueryValidator()
+    {
+        RuleFor(x => x.Dimension)
+            .Must(value => value is FinanceCostDimension.Tenant or FinanceCostDimension.Store)
+            .WithMessage("dimension 非法");
+
+        RuleFor(x => x)
+            .Must(query =>
+                query.Dimension != FinanceCostDimension.Store ||
+                (query.StoreId.HasValue && query.StoreId.Value > 0))
+            .WithMessage("storeId 非法");
+
+        RuleFor(x => x.CurrentUtc)
+            .Must(value => value.Year is >= 2000 and <= 2100)
+            .WithMessage("currentUtc 非法");
+    }
+}

src/Application/TakeoutSaaS.Application/App/Finance/Reports/Dto/FinanceBusinessReportDtos.cs

@@ -0,0 +1,218 @@
+namespace TakeoutSaaS.Application.App.Finance.Reports.Dto;
+
+/// <summary>
+/// 经营报表列表行 DTO。
+/// </summary>
+public sealed class FinanceBusinessReportListItemDto
+{
+    /// <summary>
+    /// 报表 ID。
+    /// </summary>
+    public string ReportId { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 日期文案。
+    /// </summary>
+    public string DateText { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 营业额。
+    /// </summary>
+    public decimal RevenueAmount { get; set; }
+
+    /// <summary>
+    /// 订单数。
+    /// </summary>
+    public int OrderCount { get; set; }
+
+    /// <summary>
+    /// 客单价。
+    /// </summary>
+    public decimal AverageOrderValue { get; set; }
+
+    /// <summary>
+    /// 退款率（百分数）。
+    /// </summary>
+    public decimal RefundRatePercent { get; set; }
+
+    /// <summary>
+    /// 成本总额。
+    /// </summary>
+    public decimal CostTotalAmount { get; set; }
+
+    /// <summary>
+    /// 净利润。
+    /// </summary>
+    public decimal NetProfitAmount { get; set; }
+
+    /// <summary>
+    /// 利润率（百分数）。
+    /// </summary>
+    public decimal ProfitRatePercent { get; set; }
+
+    /// <summary>
+    /// 状态编码。
+    /// </summary>
+    public string Status { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 状态文案。
+    /// </summary>
+    public string StatusText { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 是否可下载。
+    /// </summary>
+    public bool CanDownload { get; set; }
+}
+
+/// <summary>
+/// 经营报表列表结果 DTO。
+/// </summary>
+public sealed class FinanceBusinessReportListResultDto
+{
+    /// <summary>
+    /// 列表项。
+    /// </summary>
+    public List<FinanceBusinessReportListItemDto> Items { get; set; } = [];
+
+    /// <summary>
+    /// 总数。
+    /// </summary>
+    public int Total { get; set; }
+
+    /// <summary>
+    /// 页码。
+    /// </summary>
+    public int Page { get; set; }
+
+    /// <summary>
+    /// 每页条数。
+    /// </summary>
+    public int PageSize { get; set; }
+}
+
+/// <summary>
+/// 经营报表 KPI DTO。
+/// </summary>
+public sealed class FinanceBusinessReportKpiDto
+{
+    /// <summary>
+    /// 指标键。
+    /// </summary>
+    public string Key { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 指标名称。
+    /// </summary>
+    public string Label { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 指标值文本。
+    /// </summary>
+    public string ValueText { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 同比变化率（百分数）。
+    /// </summary>
+    public decimal YoyChangeRate { get; set; }
+
+    /// <summary>
+    /// 环比变化率（百分数）。
+    /// </summary>
+    public decimal MomChangeRate { get; set; }
+}
+
+/// <summary>
+/// 经营报表明细行 DTO。
+/// </summary>
+public sealed class FinanceBusinessReportBreakdownItemDto
+{
+    /// <summary>
+    /// 明细键。
+    /// </summary>
+    public string Key { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 明细名称。
+    /// </summary>
+    public string Label { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 金额。
+    /// </summary>
+    public decimal Amount { get; set; }
+
+    /// <summary>
+    /// 占比（百分数）。
+    /// </summary>
+    public decimal RatioPercent { get; set; }
+}
+
+/// <summary>
+/// 经营报表详情 DTO。
+/// </summary>
+public sealed class FinanceBusinessReportDetailDto
+{
+    /// <summary>
+    /// 报表 ID。
+    /// </summary>
+    public string ReportId { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 标题。
+    /// </summary>
+    public string Title { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 周期类型编码。
+    /// </summary>
+    public string PeriodType { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 状态编码。
+    /// </summary>
+    public string Status { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 状态文案。
+    /// </summary>
+    public string StatusText { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 关键指标。
+    /// </summary>
+    public List<FinanceBusinessReportKpiDto> Kpis { get; set; } = [];
+
+    /// <summary>
+    /// 收入明细（按渠道）。
+    /// </summary>
+    public List<FinanceBusinessReportBreakdownItemDto> IncomeBreakdowns { get; set; } = [];
+
+    /// <summary>
+    /// 成本明细（按类别）。
+    /// </summary>
+    public List<FinanceBusinessReportBreakdownItemDto> CostBreakdowns { get; set; } = [];
+}
+
+/// <summary>
+/// 经营报表导出 DTO。
+/// </summary>
+public sealed class FinanceBusinessReportExportDto
+{
+    /// <summary>
+    /// 文件名。
+    /// </summary>
+    public string FileName { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Base64 文件内容。
+    /// </summary>
+    public string FileContentBase64 { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 总记录数。
+    /// </summary>
+    public int TotalCount { get; set; }
+}
+

src/Application/TakeoutSaaS.Application/App/Finance/Reports/Handlers/ExportFinanceBusinessReportBatchQueryHandler.cs

@@ -0,0 +1,112 @@
+using System.Globalization;
+using System.IO.Compression;
+using MediatR;
+using TakeoutSaaS.Application.App.Finance.Reports.Dto;
+using TakeoutSaaS.Application.App.Finance.Reports.Queries;
+using TakeoutSaaS.Domain.Finance.Repositories;
+using TakeoutSaaS.Domain.Finance.Services;
+using TakeoutSaaS.Shared.Abstractions.Tenancy;
+
+namespace TakeoutSaaS.Application.App.Finance.Reports.Handlers;
+
+/// <summary>
+/// 经营报表批量导出处理器（ZIP：PDF + Excel）。
+/// </summary>
+public sealed class ExportFinanceBusinessReportBatchQueryHandler(
+    IFinanceBusinessReportRepository financeBusinessReportRepository,
+    IFinanceBusinessReportExportService financeBusinessReportExportService,
+    ITenantProvider tenantProvider)
+    : IRequestHandler<ExportFinanceBusinessReportBatchQuery, FinanceBusinessReportExportDto>
+{
+    /// <inheritdoc />
+    public async Task<FinanceBusinessReportExportDto> Handle(
+        ExportFinanceBusinessReportBatchQuery request,
+        CancellationToken cancellationToken)
+    {
+        // 1. 读取租户上下文并归一化分页参数。
+        var tenantId = tenantProvider.GetCurrentTenantId();
+        var normalizedPage = Math.Max(1, request.Page);
+        var normalizedPageSize = Math.Clamp(request.PageSize, 1, 200);
+
+        // 2. 确保成本配置并补齐快照。
+        await financeBusinessReportRepository.EnsureDefaultCostProfilesAsync(
+            tenantId,
+            request.StoreId,
+            cancellationToken);
+        await financeBusinessReportRepository.QueueSnapshotsForPageAsync(
+            tenantId,
+            request.StoreId,
+            request.PeriodType,
+            normalizedPage,
+            normalizedPageSize,
+            cancellationToken);
+
+        // 3. 查询导出明细集合（允许实时补算）。
+        var details = await financeBusinessReportRepository.ListBatchDetailsAsync(
+            tenantId,
+            request.StoreId,
+            request.PeriodType,
+            normalizedPage,
+            normalizedPageSize,
+            allowRealtimeBuild: true,
+            cancellationToken);
+
+        // 4. 生成批量 PDF/Excel 并打包 ZIP。
+        var periodCode = FinanceBusinessReportMapping.ToPeriodTypeCode(request.PeriodType);
+        var zipBytes = await CreateZipAsync(
+            details,
+            periodCode,
+            financeBusinessReportExportService,
+            cancellationToken);
+
+        return new FinanceBusinessReportExportDto
+        {
+            FileName = string.Create(
+                CultureInfo.InvariantCulture,
+                $"business-report-batch-{request.StoreId}-{periodCode}-{DateTime.UtcNow:yyyyMMddHHmmss}.zip"),
+            FileContentBase64 = Convert.ToBase64String(zipBytes),
+            TotalCount = details.Count
+        };
+    }
+
+    private static async Task<byte[]> CreateZipAsync(
+        IReadOnlyList<Domain.Finance.Models.FinanceBusinessReportDetailSnapshot> details,
+        string periodCode,
+        IFinanceBusinessReportExportService exportService,
+        CancellationToken cancellationToken)
+    {
+        if (details.Count == 0)
+        {
+            using var emptyStream = new MemoryStream();
+            using (var emptyArchive = new ZipArchive(emptyStream, ZipArchiveMode.Create, true))
+            {
+                var entry = emptyArchive.CreateEntry("README.txt");
+                await using var writer = new StreamWriter(entry.Open());
+                await writer.WriteAsync("No business report data in current selection.");
+            }
+
+            return emptyStream.ToArray();
+        }
+
+        var pdfBytes = await exportService.ExportBatchPdfAsync(details, cancellationToken);
+        var excelBytes = await exportService.ExportBatchExcelAsync(details, cancellationToken);
+
+        using var stream = new MemoryStream();
+        using (var archive = new ZipArchive(stream, ZipArchiveMode.Create, true))
+        {
+            var pdfEntry = archive.CreateEntry($"business-report-{periodCode}.pdf");
+            await using (var pdfEntryStream = pdfEntry.Open())
+            {
+                await pdfEntryStream.WriteAsync(pdfBytes, cancellationToken);
+            }
+
+            var excelEntry = archive.CreateEntry($"business-report-{periodCode}.xlsx");
+            await using (var excelEntryStream = excelEntry.Open())
+            {
+                await excelEntryStream.WriteAsync(excelBytes, cancellationToken);
+            }
+        }
+
+        return stream.ToArray();
+    }
+}

src/Application/TakeoutSaaS.Application/App/Finance/Reports/Handlers/ExportFinanceBusinessReportExcelQueryHandler.cs

@@ -0,0 +1,59 @@
+using System.Globalization;
+using MediatR;
+using TakeoutSaaS.Application.App.Finance.Reports.Dto;
+using TakeoutSaaS.Application.App.Finance.Reports.Queries;
+using TakeoutSaaS.Domain.Finance.Repositories;
+using TakeoutSaaS.Domain.Finance.Services;
+using TakeoutSaaS.Shared.Abstractions.Constants;
+using TakeoutSaaS.Shared.Abstractions.Exceptions;
+using TakeoutSaaS.Shared.Abstractions.Tenancy;
+
+namespace TakeoutSaaS.Application.App.Finance.Reports.Handlers;
+
+/// <summary>
+/// 经营报表 Excel 导出处理器。
+/// </summary>
+public sealed class ExportFinanceBusinessReportExcelQueryHandler(
+    IFinanceBusinessReportRepository financeBusinessReportRepository,
+    IFinanceBusinessReportExportService financeBusinessReportExportService,
+    ITenantProvider tenantProvider)
+    : IRequestHandler<ExportFinanceBusinessReportExcelQuery, FinanceBusinessReportExportDto>
+{
+    /// <inheritdoc />
+    public async Task<FinanceBusinessReportExportDto> Handle(
+        ExportFinanceBusinessReportExcelQuery request,
+        CancellationToken cancellationToken)
+    {
+        // 1. 读取租户上下文并确保成本配置存在。
+        var tenantId = tenantProvider.GetCurrentTenantId();
+        await financeBusinessReportRepository.EnsureDefaultCostProfilesAsync(
+            tenantId,
+            request.StoreId,
+            cancellationToken);
+
+        // 2. 查询报表详情（允许实时补算）。
+        var detail = await financeBusinessReportRepository.GetDetailAsync(
+            tenantId,
+            request.StoreId,
+            request.ReportId,
+            allowRealtimeBuild: true,
+            cancellationToken);
+
+        if (detail is null)
+        {
+            throw new BusinessException(ErrorCodes.NotFound, "经营报表不存在");
+        }
+
+        // 3. 导出 Excel 并返回 Base64。
+        var fileBytes = await financeBusinessReportExportService.ExportSingleExcelAsync(detail, cancellationToken);
+        var periodCode = FinanceBusinessReportMapping.ToPeriodTypeCode(detail.PeriodType);
+        return new FinanceBusinessReportExportDto
+        {
+            FileName = string.Create(
+                CultureInfo.InvariantCulture,
+                $"business-report-{request.StoreId}-{periodCode}-{request.ReportId}.xlsx"),
+            FileContentBase64 = Convert.ToBase64String(fileBytes),
+            TotalCount = 1
+        };
+    }
+}

src/Application/TakeoutSaaS.Application/App/Finance/Reports/Handlers/ExportFinanceBusinessReportPdfQueryHandler.cs

@@ -0,0 +1,59 @@
+using System.Globalization;
+using MediatR;
+using TakeoutSaaS.Application.App.Finance.Reports.Dto;
+using TakeoutSaaS.Application.App.Finance.Reports.Queries;
+using TakeoutSaaS.Domain.Finance.Repositories;
+using TakeoutSaaS.Domain.Finance.Services;
+using TakeoutSaaS.Shared.Abstractions.Constants;
+using TakeoutSaaS.Shared.Abstractions.Exceptions;
+using TakeoutSaaS.Shared.Abstractions.Tenancy;
+
+namespace TakeoutSaaS.Application.App.Finance.Reports.Handlers;
+
+/// <summary>
+/// 经营报表 PDF 导出处理器。
+/// </summary>
+public sealed class ExportFinanceBusinessReportPdfQueryHandler(
+    IFinanceBusinessReportRepository financeBusinessReportRepository,
+    IFinanceBusinessReportExportService financeBusinessReportExportService,
+    ITenantProvider tenantProvider)
+    : IRequestHandler<ExportFinanceBusinessReportPdfQuery, FinanceBusinessReportExportDto>
+{
+    /// <inheritdoc />
+    public async Task<FinanceBusinessReportExportDto> Handle(
+        ExportFinanceBusinessReportPdfQuery request,
+        CancellationToken cancellationToken)
+    {
+        // 1. 读取租户上下文并确保成本配置存在。
+        var tenantId = tenantProvider.GetCurrentTenantId();
+        await financeBusinessReportRepository.EnsureDefaultCostProfilesAsync(
+            tenantId,
+            request.StoreId,
+            cancellationToken);
+
+        // 2. 查询报表详情（允许实时补算）。
+        var detail = await financeBusinessReportRepository.GetDetailAsync(
+            tenantId,
+            request.StoreId,
+            request.ReportId,
+            allowRealtimeBuild: true,
+            cancellationToken);
+
+        if (detail is null)
+        {
+            throw new BusinessException(ErrorCodes.NotFound, "经营报表不存在");
+        }
+
+        // 3. 导出 PDF 并返回 Base64。
+        var fileBytes = await financeBusinessReportExportService.ExportSinglePdfAsync(detail, cancellationToken);
+        var periodCode = FinanceBusinessReportMapping.ToPeriodTypeCode(detail.PeriodType);
+        return new FinanceBusinessReportExportDto
+        {
+            FileName = string.Create(
+                CultureInfo.InvariantCulture,
+                $"business-report-{request.StoreId}-{periodCode}-{request.ReportId}.pdf"),
+            FileContentBase64 = Convert.ToBase64String(fileBytes),
+            TotalCount = 1
+        };
+    }
+}

src/Application/TakeoutSaaS.Application/App/Finance/Reports/Handlers/FinanceBusinessReportMapping.cs

@@ -0,0 +1,178 @@
+using System.Globalization;
+using TakeoutSaaS.Application.App.Finance.Reports.Dto;
+using TakeoutSaaS.Domain.Finance.Enums;
+using TakeoutSaaS.Domain.Finance.Models;
+
+namespace TakeoutSaaS.Application.App.Finance.Reports.Handlers;
+
+/// <summary>
+/// 经营报表映射工具。
+/// </summary>
+internal static class FinanceBusinessReportMapping
+{
+    /// <summary>
+    /// 映射列表行 DTO。
+    /// </summary>
+    public static FinanceBusinessReportListItemDto ToListItem(FinanceBusinessReportListItemSnapshot source)
+    {
+        return new FinanceBusinessReportListItemDto
+        {
+            ReportId = source.ReportId.ToString(CultureInfo.InvariantCulture),
+            DateText = FormatPeriodText(source.PeriodType, source.PeriodStartAt, source.PeriodEndAt),
+            RevenueAmount = RoundMoney(source.RevenueAmount),
+            OrderCount = Math.Max(0, source.OrderCount),
+            AverageOrderValue = RoundMoney(source.AverageOrderValue),
+            RefundRatePercent = RoundPercent(source.RefundRate),
+            CostTotalAmount = RoundMoney(source.CostTotalAmount),
+            NetProfitAmount = RoundMoney(source.NetProfitAmount),
+            ProfitRatePercent = RoundPercent(source.ProfitRate),
+            Status = ToStatusCode(source.Status),
+            StatusText = ToStatusText(source.Status),
+            CanDownload = source.Status == FinanceBusinessReportStatus.Succeeded
+        };
+    }
+
+    /// <summary>
+    /// 映射详情 DTO。
+    /// </summary>
+    public static FinanceBusinessReportDetailDto ToDetail(FinanceBusinessReportDetailSnapshot source)
+    {
+        return new FinanceBusinessReportDetailDto
+        {
+            ReportId = source.ReportId.ToString(CultureInfo.InvariantCulture),
+            Title = BuildTitle(source.PeriodType, source.PeriodStartAt, source.PeriodEndAt),
+            PeriodType = ToPeriodTypeCode(source.PeriodType),
+            Status = ToStatusCode(source.Status),
+            StatusText = ToStatusText(source.Status),
+            Kpis = source.Kpis.Select(ToKpi).ToList(),
+            IncomeBreakdowns = source.IncomeBreakdowns.Select(ToBreakdown).ToList(),
+            CostBreakdowns = source.CostBreakdowns.Select(ToBreakdown).ToList()
+        };
+    }
+
+    /// <summary>
+    /// 周期类型编码。
+    /// </summary>
+    public static string ToPeriodTypeCode(FinanceBusinessReportPeriodType value)
+    {
+        return value switch
+        {
+            FinanceBusinessReportPeriodType.Daily => "daily",
+            FinanceBusinessReportPeriodType.Weekly => "weekly",
+            FinanceBusinessReportPeriodType.Monthly => "monthly",
+            _ => "daily"
+        };
+    }
+
+    private static FinanceBusinessReportKpiDto ToKpi(FinanceBusinessReportKpiSnapshot source)
+    {
+        return new FinanceBusinessReportKpiDto
+        {
+            Key = source.Key,
+            Label = source.Label,
+            ValueText = FormatKpiValue(source.Key, source.Value),
+            YoyChangeRate = RoundRate(source.YoyChangeRate),
+            MomChangeRate = RoundRate(source.MomChangeRate)
+        };
+    }
+
+    private static FinanceBusinessReportBreakdownItemDto ToBreakdown(FinanceBusinessReportBreakdownSnapshot source)
+    {
+        return new FinanceBusinessReportBreakdownItemDto
+        {
+            Key = source.Key,
+            Label = source.Label,
+            Amount = RoundMoney(source.Amount),
+            RatioPercent = RoundPercent(source.Ratio)
+        };
+    }
+
+    private static string FormatPeriodText(
+        FinanceBusinessReportPeriodType periodType,
+        DateTime startAt,
+        DateTime endAt)
+    {
+        return periodType switch
+        {
+            FinanceBusinessReportPeriodType.Daily => startAt.ToString("yyyy-MM-dd", CultureInfo.InvariantCulture),
+            FinanceBusinessReportPeriodType.Weekly =>
+                $"{startAt:MM-dd} ~ {endAt.AddDays(-1):MM-dd}",
+            FinanceBusinessReportPeriodType.Monthly => startAt.ToString("yyyy年M月", CultureInfo.InvariantCulture),
+            _ => startAt.ToString("yyyy-MM-dd", CultureInfo.InvariantCulture)
+        };
+    }
+
+    private static string BuildTitle(
+        FinanceBusinessReportPeriodType periodType,
+        DateTime startAt,
+        DateTime endAt)
+    {
+        return periodType switch
+        {
+            FinanceBusinessReportPeriodType.Daily => $"{startAt:yyyy年M月d日} 经营日报",
+            FinanceBusinessReportPeriodType.Weekly => $"{startAt:yyyy年M月d日}~{endAt.AddDays(-1):M月d日} 经营周报",
+            FinanceBusinessReportPeriodType.Monthly => $"{startAt:yyyy年M月} 经营月报",
+            _ => "经营报表"
+        };
+    }
+
+    private static string ToStatusCode(FinanceBusinessReportStatus status)
+    {
+        return status switch
+        {
+            FinanceBusinessReportStatus.Queued => "queued",
+            FinanceBusinessReportStatus.Running => "running",
+            FinanceBusinessReportStatus.Succeeded => "succeeded",
+            FinanceBusinessReportStatus.Failed => "failed",
+            _ => "queued"
+        };
+    }
+
+    private static string ToStatusText(FinanceBusinessReportStatus status)
+    {
+        return status switch
+        {
+            FinanceBusinessReportStatus.Queued => "排队中",
+            FinanceBusinessReportStatus.Running => "生成中",
+            FinanceBusinessReportStatus.Succeeded => "已生成",
+            FinanceBusinessReportStatus.Failed => "生成失败",
+            _ => "排队中"
+        };
+    }
+
+    private static string FormatKpiValue(string key, decimal value)
+    {
+        if (key is "order_count")
+        {
+            return Math.Round(value, 0, MidpointRounding.AwayFromZero).ToString("0", CultureInfo.InvariantCulture);
+        }
+
+        if (key is "refund_rate" or "profit_rate")
+        {
+            return $"{RoundPercent(value):0.##}%";
+        }
+
+        if (key is "average_order_value")
+        {
+            return $"¥{RoundMoney(value):0.##}";
+        }
+
+        return $"¥{RoundMoney(value):0.##}";
+    }
+
+    private static decimal RoundMoney(decimal value)
+    {
+        return decimal.Round(value, 2, MidpointRounding.AwayFromZero);
+    }
+
+    private static decimal RoundPercent(decimal value)
+    {
+        return decimal.Round(value * 100m, 2, MidpointRounding.AwayFromZero);
+    }
+
+    private static decimal RoundRate(decimal value)
+    {
+        return decimal.Round(value, 2, MidpointRounding.AwayFromZero);
+    }
+}
+

src/Application/TakeoutSaaS.Application/App/Finance/Reports/Handlers/GetFinanceBusinessReportDetailQueryHandler.cs

@@ -0,0 +1,39 @@
+using MediatR;
+using TakeoutSaaS.Application.App.Finance.Reports.Dto;
+using TakeoutSaaS.Application.App.Finance.Reports.Queries;
+using TakeoutSaaS.Domain.Finance.Repositories;
+using TakeoutSaaS.Shared.Abstractions.Tenancy;
+
+namespace TakeoutSaaS.Application.App.Finance.Reports.Handlers;
+
+/// <summary>
+/// 经营报表详情查询处理器。
+/// </summary>
+public sealed class GetFinanceBusinessReportDetailQueryHandler(
+    IFinanceBusinessReportRepository financeBusinessReportRepository,
+    ITenantProvider tenantProvider)
+    : IRequestHandler<GetFinanceBusinessReportDetailQuery, FinanceBusinessReportDetailDto?>
+{
+    /// <inheritdoc />
+    public async Task<FinanceBusinessReportDetailDto?> Handle(
+        GetFinanceBusinessReportDetailQuery request,
+        CancellationToken cancellationToken)
+    {
+        // 1. 读取租户上下文并确保成本配置存在。
+        var tenantId = tenantProvider.GetCurrentTenantId();
+        await financeBusinessReportRepository.EnsureDefaultCostProfilesAsync(
+            tenantId,
+            request.StoreId,
+            cancellationToken);
+
+        // 2. 查询详情（允许实时补算）并映射输出。
+        var detail = await financeBusinessReportRepository.GetDetailAsync(
+            tenantId,
+            request.StoreId,
+            request.ReportId,
+            allowRealtimeBuild: true,
+            cancellationToken);
+
+        return detail is null ? null : FinanceBusinessReportMapping.ToDetail(detail);
+    }
+}

src/Application/TakeoutSaaS.Application/App/Finance/Reports/Handlers/SearchFinanceBusinessReportListQueryHandler.cs

@@ -0,0 +1,57 @@
+using MediatR;
+using TakeoutSaaS.Application.App.Finance.Reports.Dto;
+using TakeoutSaaS.Application.App.Finance.Reports.Queries;
+using TakeoutSaaS.Domain.Finance.Repositories;
+using TakeoutSaaS.Shared.Abstractions.Tenancy;
+
+namespace TakeoutSaaS.Application.App.Finance.Reports.Handlers;
+
+/// <summary>
+/// 经营报表分页查询处理器。
+/// </summary>
+public sealed class SearchFinanceBusinessReportListQueryHandler(
+    IFinanceBusinessReportRepository financeBusinessReportRepository,
+    ITenantProvider tenantProvider)
+    : IRequestHandler<SearchFinanceBusinessReportListQuery, FinanceBusinessReportListResultDto>
+{
+    /// <inheritdoc />
+    public async Task<FinanceBusinessReportListResultDto> Handle(
+        SearchFinanceBusinessReportListQuery request,
+        CancellationToken cancellationToken)
+    {
+        // 1. 读取租户上下文并归一化分页参数。
+        var tenantId = tenantProvider.GetCurrentTenantId();
+        var normalizedPage = Math.Max(1, request.Page);
+        var normalizedPageSize = Math.Clamp(request.PageSize, 1, 200);
+
+        // 2. 确保成本配置并补齐分页周期快照。
+        await financeBusinessReportRepository.EnsureDefaultCostProfilesAsync(
+            tenantId,
+            request.StoreId,
+            cancellationToken);
+        await financeBusinessReportRepository.QueueSnapshotsForPageAsync(
+            tenantId,
+            request.StoreId,
+            request.PeriodType,
+            normalizedPage,
+            normalizedPageSize,
+            cancellationToken);
+
+        // 3. 查询分页快照并映射输出。
+        var pageSnapshot = await financeBusinessReportRepository.SearchPageAsync(
+            tenantId,
+            request.StoreId,
+            request.PeriodType,
+            normalizedPage,
+            normalizedPageSize,
+            cancellationToken);
+
+        return new FinanceBusinessReportListResultDto
+        {
+            Items = pageSnapshot.Items.Select(FinanceBusinessReportMapping.ToListItem).ToList(),
+            Total = pageSnapshot.TotalCount,
+            Page = normalizedPage,
+            PageSize = normalizedPageSize
+        };
+    }
+}

src/Application/TakeoutSaaS.Application/App/Finance/Reports/Queries/ExportFinanceBusinessReportBatchQuery.cs

@@ -0,0 +1,31 @@
+using MediatR;
+using TakeoutSaaS.Application.App.Finance.Reports.Dto;
+using TakeoutSaaS.Domain.Finance.Enums;
+
+namespace TakeoutSaaS.Application.App.Finance.Reports.Queries;
+
+/// <summary>
+/// 批量导出经营报表（ZIP：PDF + Excel）。
+/// </summary>
+public sealed class ExportFinanceBusinessReportBatchQuery : IRequest<FinanceBusinessReportExportDto>
+{
+    /// <summary>
+    /// 门店 ID。
+    /// </summary>
+    public long StoreId { get; init; }
+
+    /// <summary>
+    /// 周期类型。
+    /// </summary>
+    public FinanceBusinessReportPeriodType PeriodType { get; init; } = FinanceBusinessReportPeriodType.Daily;
+
+    /// <summary>
+    /// 页码。
+    /// </summary>
+    public int Page { get; init; } = 1;
+
+    /// <summary>
+    /// 每页条数。
+    /// </summary>
+    public int PageSize { get; init; } = 20;
+}

src/Application/TakeoutSaaS.Application/App/Finance/Reports/Queries/ExportFinanceBusinessReportExcelQuery.cs

@@ -0,0 +1,20 @@
+using MediatR;
+using TakeoutSaaS.Application.App.Finance.Reports.Dto;
+
+namespace TakeoutSaaS.Application.App.Finance.Reports.Queries;
+
+/// <summary>
+/// 导出经营报表 Excel。
+/// </summary>
+public sealed class ExportFinanceBusinessReportExcelQuery : IRequest<FinanceBusinessReportExportDto>
+{
+    /// <summary>
+    /// 门店 ID。
+    /// </summary>
+    public long StoreId { get; init; }
+
+    /// <summary>
+    /// 报表 ID。
+    /// </summary>
+    public long ReportId { get; init; }
+}

src/Application/TakeoutSaaS.Application/App/Finance/Reports/Queries/ExportFinanceBusinessReportPdfQuery.cs

@@ -0,0 +1,20 @@
+using MediatR;
+using TakeoutSaaS.Application.App.Finance.Reports.Dto;
+
+namespace TakeoutSaaS.Application.App.Finance.Reports.Queries;
+
+/// <summary>
+/// 导出经营报表 PDF。
+/// </summary>
+public sealed class ExportFinanceBusinessReportPdfQuery : IRequest<FinanceBusinessReportExportDto>
+{
+    /// <summary>
+    /// 门店 ID。
+    /// </summary>
+    public long StoreId { get; init; }
+
+    /// <summary>
+    /// 报表 ID。
+    /// </summary>
+    public long ReportId { get; init; }
+}

src/Application/TakeoutSaaS.Application/App/Finance/Reports/Queries/GetFinanceBusinessReportDetailQuery.cs

@@ -0,0 +1,20 @@
+using MediatR;
+using TakeoutSaaS.Application.App.Finance.Reports.Dto;
+
+namespace TakeoutSaaS.Application.App.Finance.Reports.Queries;
+
+/// <summary>
+/// 查询经营报表详情。
+/// </summary>
+public sealed class GetFinanceBusinessReportDetailQuery : IRequest<FinanceBusinessReportDetailDto?>
+{
+    /// <summary>
+    /// 门店 ID。
+    /// </summary>
+    public long StoreId { get; init; }
+
+    /// <summary>
+    /// 报表 ID。
+    /// </summary>
+    public long ReportId { get; init; }
+}

src/Application/TakeoutSaaS.Application/App/Finance/Reports/Queries/SearchFinanceBusinessReportListQuery.cs

@@ -0,0 +1,31 @@
+using MediatR;
+using TakeoutSaaS.Application.App.Finance.Reports.Dto;
+using TakeoutSaaS.Domain.Finance.Enums;
+
+namespace TakeoutSaaS.Application.App.Finance.Reports.Queries;
+
+/// <summary>
+/// 查询经营报表分页列表。
+/// </summary>
+public sealed class SearchFinanceBusinessReportListQuery : IRequest<FinanceBusinessReportListResultDto>
+{
+    /// <summary>
+    /// 门店 ID。
+    /// </summary>
+    public long StoreId { get; init; }
+
+    /// <summary>
+    /// 周期类型。
+    /// </summary>
+    public FinanceBusinessReportPeriodType PeriodType { get; init; } = FinanceBusinessReportPeriodType.Daily;
+
+    /// <summary>
+    /// 页码。
+    /// </summary>
+    public int Page { get; init; } = 1;
+
+    /// <summary>
+    /// 每页条数。
+    /// </summary>
+    public int PageSize { get; init; } = 20;
+}

src/Application/TakeoutSaaS.Application/App/Finance/Reports/Validators/ExportFinanceBusinessReportBatchQueryValidator.cs

@@ -0,0 +1,20 @@
+using FluentValidation;
+using TakeoutSaaS.Application.App.Finance.Reports.Queries;
+
+namespace TakeoutSaaS.Application.App.Finance.Reports.Validators;
+
+/// <summary>
+/// 经营报表批量导出查询验证器。
+/// </summary>
+public sealed class ExportFinanceBusinessReportBatchQueryValidator : AbstractValidator<ExportFinanceBusinessReportBatchQuery>
+{
+    /// <summary>
+    /// 初始化验证规则。
+    /// </summary>
+    public ExportFinanceBusinessReportBatchQueryValidator()
+    {
+        RuleFor(x => x.StoreId).GreaterThan(0);
+        RuleFor(x => x.Page).GreaterThan(0);
+        RuleFor(x => x.PageSize).InclusiveBetween(1, 200);
+    }
+}

src/Application/TakeoutSaaS.Application/App/Finance/Reports/Validators/ExportFinanceBusinessReportExcelQueryValidator.cs

@@ -0,0 +1,19 @@
+using FluentValidation;
+using TakeoutSaaS.Application.App.Finance.Reports.Queries;
+
+namespace TakeoutSaaS.Application.App.Finance.Reports.Validators;
+
+/// <summary>
+/// 经营报表 Excel 导出查询验证器。
+/// </summary>
+public sealed class ExportFinanceBusinessReportExcelQueryValidator : AbstractValidator<ExportFinanceBusinessReportExcelQuery>
+{
+    /// <summary>
+    /// 初始化验证规则。
+    /// </summary>
+    public ExportFinanceBusinessReportExcelQueryValidator()
+    {
+        RuleFor(x => x.StoreId).GreaterThan(0);
+        RuleFor(x => x.ReportId).GreaterThan(0);
+    }
+}

src/Application/TakeoutSaaS.Application/App/Finance/Reports/Validators/ExportFinanceBusinessReportPdfQueryValidator.cs

@@ -0,0 +1,19 @@
+using FluentValidation;
+using TakeoutSaaS.Application.App.Finance.Reports.Queries;
+
+namespace TakeoutSaaS.Application.App.Finance.Reports.Validators;
+
+/// <summary>
+/// 经营报表 PDF 导出查询验证器。
+/// </summary>
+public sealed class ExportFinanceBusinessReportPdfQueryValidator : AbstractValidator<ExportFinanceBusinessReportPdfQuery>
+{
+    /// <summary>
+    /// 初始化验证规则。
+    /// </summary>
+    public ExportFinanceBusinessReportPdfQueryValidator()
+    {
+        RuleFor(x => x.StoreId).GreaterThan(0);
+        RuleFor(x => x.ReportId).GreaterThan(0);
+    }
+}

src/Application/TakeoutSaaS.Application/App/Finance/Reports/Validators/GetFinanceBusinessReportDetailQueryValidator.cs

@@ -0,0 +1,19 @@
+using FluentValidation;
+using TakeoutSaaS.Application.App.Finance.Reports.Queries;
+
+namespace TakeoutSaaS.Application.App.Finance.Reports.Validators;
+
+/// <summary>
+/// 经营报表详情查询验证器。
+/// </summary>
+public sealed class GetFinanceBusinessReportDetailQueryValidator : AbstractValidator<GetFinanceBusinessReportDetailQuery>
+{
+    /// <summary>
+    /// 初始化验证规则。
+    /// </summary>
+    public GetFinanceBusinessReportDetailQueryValidator()
+    {
+        RuleFor(x => x.StoreId).GreaterThan(0);
+        RuleFor(x => x.ReportId).GreaterThan(0);
+    }
+}

src/Application/TakeoutSaaS.Application/App/Finance/Reports/Validators/SearchFinanceBusinessReportListQueryValidator.cs

@@ -0,0 +1,20 @@
+using FluentValidation;
+using TakeoutSaaS.Application.App.Finance.Reports.Queries;
+
+namespace TakeoutSaaS.Application.App.Finance.Reports.Validators;
+
+/// <summary>
+/// 经营报表分页查询验证器。
+/// </summary>
+public sealed class SearchFinanceBusinessReportListQueryValidator : AbstractValidator<SearchFinanceBusinessReportListQuery>
+{
+    /// <summary>
+    /// 初始化验证规则。
+    /// </summary>
+    public SearchFinanceBusinessReportListQueryValidator()
+    {
+        RuleFor(x => x.StoreId).GreaterThan(0);
+        RuleFor(x => x.Page).GreaterThan(0);
+        RuleFor(x => x.PageSize).InclusiveBetween(1, 200);
+    }
+}

src/Application/TakeoutSaaS.Application/App/Finance/Settlement/Dto/FinanceSettlementDtos.cs

@@ -0,0 +1,173 @@
+namespace TakeoutSaaS.Application.App.Finance.Settlement.Dto;
+
+/// <summary>
+/// 到账查询汇总行 DTO。
+/// </summary>
+public sealed class FinanceSettlementListItemDto
+{
+    /// <summary>
+    /// 到账日期（UTC 日期）。
+    /// </summary>
+    public DateTime ArrivedDate { get; set; }
+
+    /// <summary>
+    /// 渠道编码（wechat/alipay）。
+    /// </summary>
+    public string Channel { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 渠道文案。
+    /// </summary>
+    public string ChannelText { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 交易笔数。
+    /// </summary>
+    public int TransactionCount { get; set; }
+
+    /// <summary>
+    /// 到账金额。
+    /// </summary>
+    public decimal ArrivedAmount { get; set; }
+}
+
+/// <summary>
+/// 到账查询分页结果 DTO。
+/// </summary>
+public sealed class FinanceSettlementListResultDto
+{
+    /// <summary>
+    /// 列表项。
+    /// </summary>
+    public List<FinanceSettlementListItemDto> Items { get; set; } = [];
+
+    /// <summary>
+    /// 总数。
+    /// </summary>
+    public int Total { get; set; }
+
+    /// <summary>
+    /// 当前页码。
+    /// </summary>
+    public int Page { get; set; }
+
+    /// <summary>
+    /// 每页条数。
+    /// </summary>
+    public int PageSize { get; set; }
+}
+
+/// <summary>
+/// 到账明细行 DTO。
+/// </summary>
+public sealed class FinanceSettlementDetailItemDto
+{
+    /// <summary>
+    /// 订单号。
+    /// </summary>
+    public string OrderNo { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 金额。
+    /// </summary>
+    public decimal Amount { get; set; }
+
+    /// <summary>
+    /// 支付时间（UTC）。
+    /// </summary>
+    public DateTime PaidAt { get; set; }
+}
+
+/// <summary>
+/// 到账明细结果 DTO。
+/// </summary>
+public sealed class FinanceSettlementDetailResultDto
+{
+    /// <summary>
+    /// 明细列表。
+    /// </summary>
+    public List<FinanceSettlementDetailItemDto> Items { get; set; } = [];
+}
+
+/// <summary>
+/// 到账统计 DTO。
+/// </summary>
+public sealed class FinanceSettlementStatsDto
+{
+    /// <summary>
+    /// 今日到账金额。
+    /// </summary>
+    public decimal TodayArrivedAmount { get; set; }
+
+    /// <summary>
+    /// 昨日到账金额。
+    /// </summary>
+    public decimal YesterdayArrivedAmount { get; set; }
+
+    /// <summary>
+    /// 本月到账金额。
+    /// </summary>
+    public decimal CurrentMonthArrivedAmount { get; set; }
+
+    /// <summary>
+    /// 本月交易笔数。
+    /// </summary>
+    public int CurrentMonthTransactionCount { get; set; }
+}
+
+/// <summary>
+/// 到账账户信息 DTO。
+/// </summary>
+public sealed class FinanceSettlementAccountDto
+{
+    /// <summary>
+    /// 银行名称。
+    /// </summary>
+    public string BankName { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 开户名。
+    /// </summary>
+    public string BankAccountName { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 脱敏银行账号。
+    /// </summary>
+    public string BankAccountNoMasked { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 脱敏微信商户号。
+    /// </summary>
+    public string WechatMerchantNoMasked { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 脱敏支付宝 PID。
+    /// </summary>
+    public string AlipayPidMasked { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 结算周期文案。
+    /// </summary>
+    public string SettlementPeriodText { get; set; } = string.Empty;
+}
+
+/// <summary>
+/// 到账导出 DTO。
+/// </summary>
+public sealed class FinanceSettlementExportDto
+{
+    /// <summary>
+    /// 文件名。
+    /// </summary>
+    public string FileName { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 文件内容 Base64。
+    /// </summary>
+    public string FileContentBase64 { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 导出总数。
+    /// </summary>
+    public int TotalCount { get; set; }
+}

src/Application/TakeoutSaaS.Application/App/Finance/Settlement/Handlers/ExportFinanceSettlementCsvQueryHandler.cs

@@ -0,0 +1,71 @@
+using System.Globalization;
+using System.Text;
+using MediatR;
+using TakeoutSaaS.Application.App.Finance.Settlement.Dto;
+using TakeoutSaaS.Application.App.Finance.Settlement.Queries;
+using TakeoutSaaS.Domain.Finance.Repositories;
+using TakeoutSaaS.Shared.Abstractions.Tenancy;
+
+namespace TakeoutSaaS.Application.App.Finance.Settlement.Handlers;
+
+/// <summary>
+/// 到账汇总导出处理器。
+/// </summary>
+public sealed class ExportFinanceSettlementCsvQueryHandler(
+    IFinanceTransactionRepository financeTransactionRepository,
+    ITenantProvider tenantProvider)
+    : IRequestHandler<ExportFinanceSettlementCsvQuery, FinanceSettlementExportDto>
+{
+    /// <inheritdoc />
+    public async Task<FinanceSettlementExportDto> Handle(
+        ExportFinanceSettlementCsvQuery request,
+        CancellationToken cancellationToken)
+    {
+        var tenantId = tenantProvider.GetCurrentTenantId();
+        var rows = await financeTransactionRepository.ListSettlementForExportAsync(
+            tenantId,
+            request.StoreId,
+            request.StartAt,
+            request.EndAt,
+            request.PaymentMethod,
+            cancellationToken);
+
+        var list = rows.Select(FinanceSettlementMapping.ToListItem).ToList();
+        var csv = BuildCsv(list);
+        return new FinanceSettlementExportDto
+        {
+            FileName = $"settlement-{request.StoreId}-{DateTime.UtcNow:yyyyMMddHHmmss}.csv",
+            FileContentBase64 = Convert.ToBase64String(Encoding.UTF8.GetBytes(csv)),
+            TotalCount = list.Count
+        };
+    }
+
+    private static string BuildCsv(IReadOnlyList<FinanceSettlementListItemDto> rows)
+    {
+        var sb = new StringBuilder();
+        sb.Append('\uFEFF');
+        sb.AppendLine("到账日期,支付渠道,交易笔数,到账金额");
+
+        foreach (var row in rows)
+        {
+            sb.AppendLine(string.Join(',',
+                Escape(row.ArrivedDate.ToString("yyyy-MM-dd", CultureInfo.InvariantCulture)),
+                Escape(row.ChannelText),
+                Escape(row.TransactionCount.ToString(CultureInfo.InvariantCulture)),
+                Escape(FinanceSettlementMapping.FormatAmount(row.ArrivedAmount))));
+        }
+
+        return sb.ToString();
+    }
+
+    private static string Escape(string? value)
+    {
+        var normalized = value ?? string.Empty;
+        if (normalized.Contains(',') || normalized.Contains('"') || normalized.Contains('\n'))
+        {
+            return $"\"{normalized.Replace("\"", "\"\"", StringComparison.Ordinal)}\"";
+        }
+
+        return normalized;
+    }
+}

src/Application/TakeoutSaaS.Application/App/Finance/Settlement/Handlers/FinanceSettlementMapping.cs

@@ -0,0 +1,75 @@
+using System.Globalization;
+using TakeoutSaaS.Application.App.Finance.Settlement.Dto;
+using TakeoutSaaS.Domain.Finance.Models;
+using TakeoutSaaS.Domain.Payments.Enums;
+
+namespace TakeoutSaaS.Application.App.Finance.Settlement.Handlers;
+
+/// <summary>
+/// 到账查询映射辅助。
+/// </summary>
+internal static class FinanceSettlementMapping
+{
+    /// <summary>
+    /// 支付方式转渠道编码。
+    /// </summary>
+    public static string ToChannelCode(PaymentMethod paymentMethod)
+    {
+        return paymentMethod switch
+        {
+            PaymentMethod.WeChatPay => "wechat",
+            PaymentMethod.Alipay => "alipay",
+            _ => "unknown"
+        };
+    }
+
+    /// <summary>
+    /// 支付方式转渠道文案。
+    /// </summary>
+    public static string ToChannelText(PaymentMethod paymentMethod)
+    {
+        return paymentMethod switch
+        {
+            PaymentMethod.WeChatPay => "微信支付",
+            PaymentMethod.Alipay => "支付宝",
+            _ => "未知渠道"
+        };
+    }
+
+    /// <summary>
+    /// 映射到账汇总行。
+    /// </summary>
+    public static FinanceSettlementListItemDto ToListItem(FinanceSettlementListItemSnapshot source)
+    {
+        return new FinanceSettlementListItemDto
+        {
+            ArrivedDate = source.ArrivedDate,
+            Channel = ToChannelCode(source.PaymentMethod),
+            ChannelText = ToChannelText(source.PaymentMethod),
+            TransactionCount = source.TransactionCount,
+            ArrivedAmount = decimal.Round(source.ArrivedAmount, 2, MidpointRounding.AwayFromZero)
+        };
+    }
+
+    /// <summary>
+    /// 映射到账明细行。
+    /// </summary>
+    public static FinanceSettlementDetailItemDto ToDetailItem(FinanceSettlementDetailItemSnapshot source)
+    {
+        return new FinanceSettlementDetailItemDto
+        {
+            OrderNo = source.OrderNo,
+            Amount = decimal.Round(source.Amount, 2, MidpointRounding.AwayFromZero),
+            PaidAt = source.PaidAt
+        };
+    }
+
+    /// <summary>
+    /// 格式化金额（导出场景）。
+    /// </summary>
+    public static string FormatAmount(decimal value)
+    {
+        return decimal.Round(value, 2, MidpointRounding.AwayFromZero)
+            .ToString("0.00", CultureInfo.InvariantCulture);
+    }
+}

src/Application/TakeoutSaaS.Application/App/Finance/Settlement/Handlers/GetFinanceSettlementAccountQueryHandler.cs

@@ -0,0 +1,42 @@
+using MediatR;
+using TakeoutSaaS.Application.App.Finance.Settlement.Dto;
+using TakeoutSaaS.Application.App.Finance.Settlement.Queries;
+using TakeoutSaaS.Domain.Finance.Repositories;
+using TakeoutSaaS.Shared.Abstractions.Tenancy;
+
+namespace TakeoutSaaS.Application.App.Finance.Settlement.Handlers;
+
+/// <summary>
+/// 到账账户信息查询处理器。
+/// </summary>
+public sealed class GetFinanceSettlementAccountQueryHandler(
+    IFinanceTransactionRepository financeTransactionRepository,
+    ITenantProvider tenantProvider)
+    : IRequestHandler<GetFinanceSettlementAccountQuery, FinanceSettlementAccountDto?>
+{
+    /// <inheritdoc />
+    public async Task<FinanceSettlementAccountDto?> Handle(
+        GetFinanceSettlementAccountQuery request,
+        CancellationToken cancellationToken)
+    {
+        var tenantId = tenantProvider.GetCurrentTenantId();
+        var snapshot = await financeTransactionRepository.GetSettlementAccountAsync(
+            tenantId,
+            cancellationToken);
+
+        if (snapshot is null)
+        {
+            return null;
+        }
+
+        return new FinanceSettlementAccountDto
+        {
+            BankName = snapshot.BankName,
+            BankAccountName = snapshot.BankAccountName,
+            BankAccountNoMasked = snapshot.BankAccountNoMasked,
+            WechatMerchantNoMasked = snapshot.WechatMerchantNoMasked,
+            AlipayPidMasked = snapshot.AlipayPidMasked,
+            SettlementPeriodText = snapshot.SettlementPeriodText
+        };
+    }
+}

src/Application/TakeoutSaaS.Application/App/Finance/Settlement/Handlers/GetFinanceSettlementDetailQueryHandler.cs

@@ -0,0 +1,36 @@
+using MediatR;
+using TakeoutSaaS.Application.App.Finance.Settlement.Dto;
+using TakeoutSaaS.Application.App.Finance.Settlement.Queries;
+using TakeoutSaaS.Domain.Finance.Repositories;
+using TakeoutSaaS.Shared.Abstractions.Tenancy;
+
+namespace TakeoutSaaS.Application.App.Finance.Settlement.Handlers;
+
+/// <summary>
+/// 到账明细查询处理器。
+/// </summary>
+public sealed class GetFinanceSettlementDetailQueryHandler(
+    IFinanceTransactionRepository financeTransactionRepository,
+    ITenantProvider tenantProvider)
+    : IRequestHandler<GetFinanceSettlementDetailQuery, FinanceSettlementDetailResultDto>
+{
+    /// <inheritdoc />
+    public async Task<FinanceSettlementDetailResultDto> Handle(
+        GetFinanceSettlementDetailQuery request,
+        CancellationToken cancellationToken)
+    {
+        var tenantId = tenantProvider.GetCurrentTenantId();
+        var rows = await financeTransactionRepository.GetSettlementDetailsAsync(
+            tenantId,
+            request.StoreId,
+            request.ArrivedDate,
+            request.PaymentMethod,
+            request.Take,
+            cancellationToken);
+
+        return new FinanceSettlementDetailResultDto
+        {
+            Items = rows.Select(FinanceSettlementMapping.ToDetailItem).ToList()
+        };
+    }
+}

src/Application/TakeoutSaaS.Application/App/Finance/Settlement/Handlers/GetFinanceSettlementStatsQueryHandler.cs

@@ -0,0 +1,37 @@
+using MediatR;
+using TakeoutSaaS.Application.App.Finance.Settlement.Dto;
+using TakeoutSaaS.Application.App.Finance.Settlement.Queries;
+using TakeoutSaaS.Domain.Finance.Repositories;
+using TakeoutSaaS.Shared.Abstractions.Tenancy;
+
+namespace TakeoutSaaS.Application.App.Finance.Settlement.Handlers;
+
+/// <summary>
+/// 到账统计查询处理器。
+/// </summary>
+public sealed class GetFinanceSettlementStatsQueryHandler(
+    IFinanceTransactionRepository financeTransactionRepository,
+    ITenantProvider tenantProvider)
+    : IRequestHandler<GetFinanceSettlementStatsQuery, FinanceSettlementStatsDto>
+{
+    /// <inheritdoc />
+    public async Task<FinanceSettlementStatsDto> Handle(
+        GetFinanceSettlementStatsQuery request,
+        CancellationToken cancellationToken)
+    {
+        var tenantId = tenantProvider.GetCurrentTenantId();
+        var snapshot = await financeTransactionRepository.GetSettlementStatsAsync(
+            tenantId,
+            request.StoreId,
+            DateTime.UtcNow,
+            cancellationToken);
+
+        return new FinanceSettlementStatsDto
+        {
+            TodayArrivedAmount = snapshot.TodayArrivedAmount,
+            YesterdayArrivedAmount = snapshot.YesterdayArrivedAmount,
+            CurrentMonthArrivedAmount = snapshot.CurrentMonthArrivedAmount,
+            CurrentMonthTransactionCount = snapshot.CurrentMonthTransactionCount
+        };
+    }
+}

src/Application/TakeoutSaaS.Application/App/Finance/Settlement/Handlers/SearchFinanceSettlementListQueryHandler.cs

@@ -0,0 +1,44 @@
+using MediatR;
+using TakeoutSaaS.Application.App.Finance.Settlement.Dto;
+using TakeoutSaaS.Application.App.Finance.Settlement.Queries;
+using TakeoutSaaS.Domain.Finance.Repositories;
+using TakeoutSaaS.Shared.Abstractions.Tenancy;
+
+namespace TakeoutSaaS.Application.App.Finance.Settlement.Handlers;
+
+/// <summary>
+/// 到账汇总分页查询处理器。
+/// </summary>
+public sealed class SearchFinanceSettlementListQueryHandler(
+    IFinanceTransactionRepository financeTransactionRepository,
+    ITenantProvider tenantProvider)
+    : IRequestHandler<SearchFinanceSettlementListQuery, FinanceSettlementListResultDto>
+{
+    /// <inheritdoc />
+    public async Task<FinanceSettlementListResultDto> Handle(
+        SearchFinanceSettlementListQuery request,
+        CancellationToken cancellationToken)
+    {
+        var tenantId = tenantProvider.GetCurrentTenantId();
+        var normalizedPage = Math.Max(1, request.Page);
+        var normalizedPageSize = Math.Clamp(request.PageSize, 1, 200);
+
+        var snapshot = await financeTransactionRepository.SearchSettlementPageAsync(
+            tenantId,
+            request.StoreId,
+            request.StartAt,
+            request.EndAt,
+            request.PaymentMethod,
+            normalizedPage,
+            normalizedPageSize,
+            cancellationToken);
+
+        return new FinanceSettlementListResultDto
+        {
+            Items = snapshot.Items.Select(FinanceSettlementMapping.ToListItem).ToList(),
+            Total = snapshot.TotalCount,
+            Page = normalizedPage,
+            PageSize = normalizedPageSize
+        };
+    }
+}

src/Application/TakeoutSaaS.Application/App/Finance/Settlement/Queries/ExportFinanceSettlementCsvQuery.cs

@@ -0,0 +1,31 @@
+using MediatR;
+using TakeoutSaaS.Application.App.Finance.Settlement.Dto;
+using TakeoutSaaS.Domain.Payments.Enums;
+
+namespace TakeoutSaaS.Application.App.Finance.Settlement.Queries;
+
+/// <summary>
+/// 导出到账汇总 CSV。
+/// </summary>
+public sealed class ExportFinanceSettlementCsvQuery : IRequest<FinanceSettlementExportDto>
+{
+    /// <summary>
+    /// 门店标识。
+    /// </summary>
+    public long StoreId { get; init; }
+
+    /// <summary>
+    /// 开始时间（UTC，闭区间）。
+    /// </summary>
+    public DateTime? StartAt { get; init; }
+
+    /// <summary>
+    /// 结束时间（UTC，开区间）。
+    /// </summary>
+    public DateTime? EndAt { get; init; }
+
+    /// <summary>
+    /// 支付方式筛选。
+    /// </summary>
+    public PaymentMethod? PaymentMethod { get; init; }
+}

src/Application/TakeoutSaaS.Application/App/Finance/Settlement/Queries/GetFinanceSettlementAccountQuery.cs

@@ -0,0 +1,11 @@
+using MediatR;
+using TakeoutSaaS.Application.App.Finance.Settlement.Dto;
+
+namespace TakeoutSaaS.Application.App.Finance.Settlement.Queries;
+
+/// <summary>
+/// 查询到账账户信息。
+/// </summary>
+public sealed class GetFinanceSettlementAccountQuery : IRequest<FinanceSettlementAccountDto?>
+{
+}

src/Application/TakeoutSaaS.Application/App/Finance/Settlement/Queries/GetFinanceSettlementDetailQuery.cs

@@ -0,0 +1,31 @@
+using MediatR;
+using TakeoutSaaS.Application.App.Finance.Settlement.Dto;
+using TakeoutSaaS.Domain.Payments.Enums;
+
+namespace TakeoutSaaS.Application.App.Finance.Settlement.Queries;
+
+/// <summary>
+/// 查询到账明细。
+/// </summary>
+public sealed class GetFinanceSettlementDetailQuery : IRequest<FinanceSettlementDetailResultDto>
+{
+    /// <summary>
+    /// 门店标识。
+    /// </summary>
+    public long StoreId { get; init; }
+
+    /// <summary>
+    /// 到账日期（UTC 日期）。
+    /// </summary>
+    public DateTime ArrivedDate { get; init; }
+
+    /// <summary>
+    /// 渠道（微信/支付宝）。
+    /// </summary>
+    public PaymentMethod PaymentMethod { get; init; }
+
+    /// <summary>
+    /// 限制条数。
+    /// </summary>
+    public int Take { get; init; } = 20;
+}

src/Application/TakeoutSaaS.Application/App/Finance/Settlement/Queries/GetFinanceSettlementStatsQuery.cs

@@ -0,0 +1,15 @@
+using MediatR;
+using TakeoutSaaS.Application.App.Finance.Settlement.Dto;
+
+namespace TakeoutSaaS.Application.App.Finance.Settlement.Queries;
+
+/// <summary>
+/// 查询到账统计。
+/// </summary>
+public sealed class GetFinanceSettlementStatsQuery : IRequest<FinanceSettlementStatsDto>
+{
+    /// <summary>
+    /// 门店标识。
+    /// </summary>
+    public long StoreId { get; init; }
+}

src/Application/TakeoutSaaS.Application/App/Finance/Settlement/Queries/SearchFinanceSettlementListQuery.cs

@@ -0,0 +1,41 @@
+using MediatR;
+using TakeoutSaaS.Application.App.Finance.Settlement.Dto;
+using TakeoutSaaS.Domain.Payments.Enums;
+
+namespace TakeoutSaaS.Application.App.Finance.Settlement.Queries;
+
+/// <summary>
+/// 查询到账汇总分页。
+/// </summary>
+public sealed class SearchFinanceSettlementListQuery : IRequest<FinanceSettlementListResultDto>
+{
+    /// <summary>
+    /// 门店标识。
+    /// </summary>
+    public long StoreId { get; init; }
+
+    /// <summary>
+    /// 开始时间（UTC，闭区间）。
+    /// </summary>
+    public DateTime? StartAt { get; init; }
+
+    /// <summary>
+    /// 结束时间（UTC，开区间）。
+    /// </summary>
+    public DateTime? EndAt { get; init; }
+
+    /// <summary>
+    /// 支付方式筛选。
+    /// </summary>
+    public PaymentMethod? PaymentMethod { get; init; }
+
+    /// <summary>
+    /// 页码。
+    /// </summary>
+    public int Page { get; init; } = 1;
+
+    /// <summary>
+    /// 每页条数。
+    /// </summary>
+    public int PageSize { get; init; } = 20;
+}

src/Application/TakeoutSaaS.Application/App/Finance/Transactions/Dto/FinanceTransactionDtos.cs

@@ -0,0 +1,256 @@
+namespace TakeoutSaaS.Application.App.Finance.Transactions.Dto;
+
+/// <summary>
+/// 交易流水列表行。
+/// </summary>
+public sealed class FinanceTransactionListItemDto
+{
+    /// <summary>
+    /// 交易标识。
+    /// </summary>
+    public string TransactionId { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 流水号。
+    /// </summary>
+    public string TransactionNo { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 关联订单号。
+    /// </summary>
+    public string? OrderNo { get; set; }
+
+    /// <summary>
+    /// 交易类型编码。
+    /// </summary>
+    public string TransactionType { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 交易类型文案。
+    /// </summary>
+    public string TransactionTypeText { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 渠道文案。
+    /// </summary>
+    public string ChannelText { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 支付方式文案。
+    /// </summary>
+    public string PaymentMethodText { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 交易金额（带符号）。
+    /// </summary>
+    public decimal AmountSigned { get; set; }
+
+    /// <summary>
+    /// 交易时间。
+    /// </summary>
+    public DateTime OccurredAt { get; set; }
+
+    /// <summary>
+    /// 备注。
+    /// </summary>
+    public string Remark { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 是否收入。
+    /// </summary>
+    public bool IsIncome { get; set; }
+}
+
+/// <summary>
+/// 交易流水列表结果。
+/// </summary>
+public sealed class FinanceTransactionListResultDto
+{
+    /// <summary>
+    /// 分页数据。
+    /// </summary>
+    public List<FinanceTransactionListItemDto> Items { get; set; } = [];
+
+    /// <summary>
+    /// 总数。
+    /// </summary>
+    public int Total { get; set; }
+
+    /// <summary>
+    /// 当前页码。
+    /// </summary>
+    public int Page { get; set; }
+
+    /// <summary>
+    /// 每页条数。
+    /// </summary>
+    public int PageSize { get; set; }
+
+    /// <summary>
+    /// 本页收入合计。
+    /// </summary>
+    public decimal PageIncomeAmount { get; set; }
+
+    /// <summary>
+    /// 本页退款合计。
+    /// </summary>
+    public decimal PageRefundAmount { get; set; }
+}
+
+/// <summary>
+/// 交易流水统计。
+/// </summary>
+public sealed class FinanceTransactionStatsDto
+{
+    /// <summary>
+    /// 总收入。
+    /// </summary>
+    public decimal TotalIncome { get; set; }
+
+    /// <summary>
+    /// 总退款。
+    /// </summary>
+    public decimal TotalRefund { get; set; }
+
+    /// <summary>
+    /// 交易笔数。
+    /// </summary>
+    public int TotalCount { get; set; }
+}
+
+/// <summary>
+/// 交易流水详情。
+/// </summary>
+public sealed class FinanceTransactionDetailDto
+{
+    /// <summary>
+    /// 交易标识。
+    /// </summary>
+    public string TransactionId { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 流水号。
+    /// </summary>
+    public string TransactionNo { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 交易类型编码。
+    /// </summary>
+    public string TransactionType { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 交易类型文案。
+    /// </summary>
+    public string TransactionTypeText { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 门店标识。
+    /// </summary>
+    public long StoreId { get; set; }
+
+    /// <summary>
+    /// 关联订单号。
+    /// </summary>
+    public string? OrderNo { get; set; }
+
+    /// <summary>
+    /// 渠道文案。
+    /// </summary>
+    public string ChannelText { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 支付方式文案。
+    /// </summary>
+    public string PaymentMethodText { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 交易金额（带符号）。
+    /// </summary>
+    public decimal AmountSigned { get; set; }
+
+    /// <summary>
+    /// 交易时间。
+    /// </summary>
+    public DateTime OccurredAt { get; set; }
+
+    /// <summary>
+    /// 备注。
+    /// </summary>
+    public string Remark { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 顾客姓名。
+    /// </summary>
+    public string CustomerName { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 顾客手机号。
+    /// </summary>
+    public string CustomerPhone { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 退款单号。
+    /// </summary>
+    public string? RefundNo { get; set; }
+
+    /// <summary>
+    /// 退款原因。
+    /// </summary>
+    public string? RefundReason { get; set; }
+
+    /// <summary>
+    /// 会员名称。
+    /// </summary>
+    public string? MemberName { get; set; }
+
+    /// <summary>
+    /// 会员手机号脱敏值。
+    /// </summary>
+    public string? MemberMobileMasked { get; set; }
+
+    /// <summary>
+    /// 充值金额。
+    /// </summary>
+    public decimal? RechargeAmount { get; set; }
+
+    /// <summary>
+    /// 赠送金额。
+    /// </summary>
+    public decimal? GiftAmount { get; set; }
+
+    /// <summary>
+    /// 到账金额。
+    /// </summary>
+    public decimal? ArrivedAmount { get; set; }
+
+    /// <summary>
+    /// 积分变动值。
+    /// </summary>
+    public int? PointChangeAmount { get; set; }
+
+    /// <summary>
+    /// 积分变动后余额。
+    /// </summary>
+    public int? PointBalanceAfterChange { get; set; }
+}
+
+/// <summary>
+/// 交易流水导出结果。
+/// </summary>
+public sealed class FinanceTransactionExportDto
+{
+    /// <summary>
+    /// 文件名。
+    /// </summary>
+    public string FileName { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 文件内容（Base64）。
+    /// </summary>
+    public string FileContentBase64 { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 导出总数。
+    /// </summary>
+    public int TotalCount { get; set; }
+}

src/Application/TakeoutSaaS.Application/App/Finance/Transactions/Handlers/ExportFinanceTransactionCsvQueryHandler.cs

@@ -0,0 +1,81 @@
+using System.Globalization;
+using System.Text;
+using MediatR;
+using TakeoutSaaS.Application.App.Finance.Transactions.Dto;
+using TakeoutSaaS.Application.App.Finance.Transactions.Queries;
+using TakeoutSaaS.Domain.Finance.Repositories;
+using TakeoutSaaS.Shared.Abstractions.Tenancy;
+
+namespace TakeoutSaaS.Application.App.Finance.Transactions.Handlers;
+
+/// <summary>
+/// 交易流水 CSV 导出查询处理器。
+/// </summary>
+public sealed class ExportFinanceTransactionCsvQueryHandler(
+    IFinanceTransactionRepository financeTransactionRepository,
+    ITenantProvider tenantProvider)
+    : IRequestHandler<ExportFinanceTransactionCsvQuery, FinanceTransactionExportDto>
+{
+    /// <inheritdoc />
+    public async Task<FinanceTransactionExportDto> Handle(ExportFinanceTransactionCsvQuery request, CancellationToken cancellationToken)
+    {
+        // 1. 按筛选读取导出数据。
+        var tenantId = tenantProvider.GetCurrentTenantId();
+        var records = await financeTransactionRepository.ListForExportAsync(
+            tenantId,
+            request.StoreId,
+            request.StartAt,
+            request.EndAt,
+            request.TransactionType,
+            request.DeliveryType,
+            request.PaymentMethod,
+            request.Keyword,
+            cancellationToken);
+
+        // 2. 组装 CSV 并输出 Base64。
+        var csv = BuildCsv(records.Select(FinanceTransactionMapping.ToListItem).ToList());
+        var bytes = Encoding.UTF8.GetPreamble().Concat(Encoding.UTF8.GetBytes(csv)).ToArray();
+
+        return new FinanceTransactionExportDto
+        {
+            FileName = $"交易流水_{DateTime.UtcNow:yyyyMMddHHmmss}.csv",
+            FileContentBase64 = Convert.ToBase64String(bytes),
+            TotalCount = records.Count
+        };
+    }
+
+    private static string BuildCsv(IReadOnlyList<FinanceTransactionListItemDto> rows)
+    {
+        var builder = new StringBuilder();
+        builder.AppendLine("流水号,关联订单,类型,渠道,支付方式,金额,交易时间,备注");
+
+        foreach (var row in rows)
+        {
+            var cells = new[]
+            {
+                Escape(row.TransactionNo),
+                Escape(string.IsNullOrWhiteSpace(row.OrderNo) ? "—" : row.OrderNo!),
+                Escape(row.TransactionTypeText),
+                Escape(row.ChannelText),
+                Escape(row.PaymentMethodText),
+                Escape(FinanceTransactionMapping.FormatAmount(row.AmountSigned)),
+                Escape(row.OccurredAt.ToString("yyyy-MM-dd HH:mm:ss", CultureInfo.InvariantCulture)),
+                Escape(string.IsNullOrWhiteSpace(row.Remark) ? "—" : row.Remark)
+            };
+
+            builder.AppendLine(string.Join(',', cells));
+        }
+
+        return builder.ToString();
+    }
+
+    private static string Escape(string value)
+    {
+        if (!value.Contains('"') && !value.Contains(',') && !value.Contains('\n') && !value.Contains('\r'))
+        {
+            return value;
+        }
+
+        return $"\"{value.Replace("\"", "\"\"")}\"";
+    }
+}

src/Application/TakeoutSaaS.Application/App/Finance/Transactions/Handlers/FinanceTransactionMapping.cs

@@ -0,0 +1,155 @@
+using System.Globalization;
+using TakeoutSaaS.Application.App.Finance.Transactions.Dto;
+using TakeoutSaaS.Domain.Finance.Enums;
+using TakeoutSaaS.Domain.Finance.Models;
+using TakeoutSaaS.Domain.Orders.Enums;
+using TakeoutSaaS.Domain.Payments.Enums;
+
+namespace TakeoutSaaS.Application.App.Finance.Transactions.Handlers;
+
+/// <summary>
+/// 交易流水映射与文案转换。
+/// </summary>
+internal static class FinanceTransactionMapping
+{
+    /// <summary>
+    /// 生成交易复合标识。
+    /// </summary>
+    public static string BuildTransactionId(FinanceTransactionSourceType sourceType, long sourceId)
+    {
+        var sourceCode = sourceType switch
+        {
+            FinanceTransactionSourceType.PaymentRecord => "payment",
+            FinanceTransactionSourceType.PaymentRefundRecord => "payment_refund",
+            FinanceTransactionSourceType.RefundRequest => "refund_request",
+            FinanceTransactionSourceType.StoredCardRechargeRecord => "stored_card_recharge",
+            FinanceTransactionSourceType.MemberPointLedger => "member_point",
+            _ => "unknown"
+        };
+
+        return $"{sourceCode}:{sourceId}";
+    }
+
+    /// <summary>
+    /// 解析交易类型编码。
+    /// </summary>
+    public static string ToTransactionTypeCode(FinanceTransactionType transactionType)
+    {
+        return transactionType switch
+        {
+            FinanceTransactionType.Income => "income",
+            FinanceTransactionType.Refund => "refund",
+            FinanceTransactionType.StoredCardRecharge => "stored_card_recharge",
+            FinanceTransactionType.PointRedeem => "point_redeem",
+            _ => "unknown"
+        };
+    }
+
+    /// <summary>
+    /// 解析交易类型文案。
+    /// </summary>
+    public static string ToTransactionTypeText(FinanceTransactionType transactionType)
+    {
+        return transactionType switch
+        {
+            FinanceTransactionType.Income => "收入",
+            FinanceTransactionType.Refund => "退款",
+            FinanceTransactionType.StoredCardRecharge => "储值充值",
+            FinanceTransactionType.PointRedeem => "积分抵扣",
+            _ => "未知"
+        };
+    }
+
+    /// <summary>
+    /// 解析渠道文案。
+    /// </summary>
+    public static string ToChannelText(DeliveryType? deliveryType)
+    {
+        return deliveryType switch
+        {
+            DeliveryType.Delivery => "外卖",
+            DeliveryType.Pickup => "自提",
+            DeliveryType.DineIn => "堂食",
+            _ => "—"
+        };
+    }
+
+    /// <summary>
+    /// 解析支付方式文案。
+    /// </summary>
+    public static string ToPaymentMethodText(PaymentMethod? paymentMethod)
+    {
+        return paymentMethod switch
+        {
+            PaymentMethod.WeChatPay => "微信",
+            PaymentMethod.Alipay => "支付宝",
+            PaymentMethod.Cash => "现金",
+            PaymentMethod.Card => "刷卡",
+            PaymentMethod.Balance => "储值余额",
+            _ => "—"
+        };
+    }
+
+    /// <summary>
+    /// 映射列表行。
+    /// </summary>
+    public static FinanceTransactionListItemDto ToListItem(FinanceTransactionRecord source)
+    {
+        return new FinanceTransactionListItemDto
+        {
+            TransactionId = BuildTransactionId(source.SourceType, source.SourceId),
+            TransactionNo = source.TransactionNo ?? string.Empty,
+            OrderNo = source.OrderNo,
+            TransactionType = ToTransactionTypeCode(source.TransactionType),
+            TransactionTypeText = ToTransactionTypeText(source.TransactionType),
+            ChannelText = ToChannelText(source.DeliveryType),
+            PaymentMethodText = ToPaymentMethodText(source.PaymentMethod),
+            AmountSigned = decimal.Round(source.AmountSigned, 2, MidpointRounding.AwayFromZero),
+            OccurredAt = source.OccurredAt,
+            Remark = string.IsNullOrWhiteSpace(source.Remark) ? "—" : source.Remark.Trim(),
+            IsIncome = source.AmountSigned > 0
+        };
+    }
+
+    /// <summary>
+    /// 映射详情。
+    /// </summary>
+    public static FinanceTransactionDetailDto ToDetail(FinanceTransactionRecord source)
+    {
+        return new FinanceTransactionDetailDto
+        {
+            TransactionId = BuildTransactionId(source.SourceType, source.SourceId),
+            TransactionNo = source.TransactionNo ?? string.Empty,
+            TransactionType = ToTransactionTypeCode(source.TransactionType),
+            TransactionTypeText = ToTransactionTypeText(source.TransactionType),
+            StoreId = source.StoreId,
+            OrderNo = source.OrderNo,
+            ChannelText = ToChannelText(source.DeliveryType),
+            PaymentMethodText = ToPaymentMethodText(source.PaymentMethod),
+            AmountSigned = decimal.Round(source.AmountSigned, 2, MidpointRounding.AwayFromZero),
+            OccurredAt = source.OccurredAt,
+            Remark = string.IsNullOrWhiteSpace(source.Remark) ? "—" : source.Remark.Trim(),
+            CustomerName = string.IsNullOrWhiteSpace(source.CustomerName) ? "—" : source.CustomerName.Trim(),
+            CustomerPhone = string.IsNullOrWhiteSpace(source.CustomerPhone) ? "—" : source.CustomerPhone.Trim(),
+            RefundNo = source.RefundNo,
+            RefundReason = source.RefundReason,
+            MemberName = source.MemberName,
+            MemberMobileMasked = source.MemberMobileMasked,
+            RechargeAmount = source.RechargeAmount,
+            GiftAmount = source.GiftAmount,
+            ArrivedAmount = source.ArrivedAmount,
+            PointChangeAmount = source.PointChangeAmount,
+            PointBalanceAfterChange = source.PointBalanceAfterChange
+        };
+    }
+
+    /// <summary>
+    /// 导出金额文本。
+    /// </summary>
+    public static string FormatAmount(decimal amountSigned)
+    {
+        var rounded = decimal.Round(amountSigned, 2, MidpointRounding.AwayFromZero);
+        var sign = rounded >= 0 ? "+" : string.Empty;
+        return $"{sign}{rounded.ToString("0.00", CultureInfo.InvariantCulture)}";
+    }
+}

src/Application/TakeoutSaaS.Application/App/Finance/Transactions/Handlers/GetFinanceTransactionDetailQueryHandler.cs

@@ -0,0 +1,32 @@
+using MediatR;
+using TakeoutSaaS.Application.App.Finance.Transactions.Dto;
+using TakeoutSaaS.Application.App.Finance.Transactions.Queries;
+using TakeoutSaaS.Domain.Finance.Repositories;
+using TakeoutSaaS.Shared.Abstractions.Tenancy;
+
+namespace TakeoutSaaS.Application.App.Finance.Transactions.Handlers;
+
+/// <summary>
+/// 交易流水详情查询处理器。
+/// </summary>
+public sealed class GetFinanceTransactionDetailQueryHandler(
+    IFinanceTransactionRepository financeTransactionRepository,
+    ITenantProvider tenantProvider)
+    : IRequestHandler<GetFinanceTransactionDetailQuery, FinanceTransactionDetailDto?>
+{
+    /// <inheritdoc />
+    public async Task<FinanceTransactionDetailDto?> Handle(GetFinanceTransactionDetailQuery request, CancellationToken cancellationToken)
+    {
+        // 1. 读取租户上下文并查询详情。
+        var tenantId = tenantProvider.GetCurrentTenantId();
+        var record = await financeTransactionRepository.GetDetailAsync(
+            tenantId,
+            request.StoreId,
+            request.SourceType,
+            request.SourceId,
+            cancellationToken);
+
+        // 2. 映射详情输出。
+        return record is null ? null : FinanceTransactionMapping.ToDetail(record);
+    }
+}

src/Application/TakeoutSaaS.Application/App/Finance/Transactions/Handlers/GetFinanceTransactionStatsQueryHandler.cs

@@ -0,0 +1,41 @@
+using MediatR;
+using TakeoutSaaS.Application.App.Finance.Transactions.Dto;
+using TakeoutSaaS.Application.App.Finance.Transactions.Queries;
+using TakeoutSaaS.Domain.Finance.Repositories;
+using TakeoutSaaS.Shared.Abstractions.Tenancy;
+
+namespace TakeoutSaaS.Application.App.Finance.Transactions.Handlers;
+
+/// <summary>
+/// 交易流水统计查询处理器。
+/// </summary>
+public sealed class GetFinanceTransactionStatsQueryHandler(
+    IFinanceTransactionRepository financeTransactionRepository,
+    ITenantProvider tenantProvider)
+    : IRequestHandler<GetFinanceTransactionStatsQuery, FinanceTransactionStatsDto>
+{
+    /// <inheritdoc />
+    public async Task<FinanceTransactionStatsDto> Handle(GetFinanceTransactionStatsQuery request, CancellationToken cancellationToken)
+    {
+        // 1. 读取租户上下文并执行统计查询。
+        var tenantId = tenantProvider.GetCurrentTenantId();
+        var snapshot = await financeTransactionRepository.GetStatsAsync(
+            tenantId,
+            request.StoreId,
+            request.StartAt,
+            request.EndAt,
+            request.TransactionType,
+            request.DeliveryType,
+            request.PaymentMethod,
+            request.Keyword,
+            cancellationToken);
+
+        // 2. 映射统计结果。
+        return new FinanceTransactionStatsDto
+        {
+            TotalIncome = snapshot.TotalIncome,
+            TotalRefund = snapshot.TotalRefund,
+            TotalCount = snapshot.TotalCount
+        };
+    }
+}

src/Application/TakeoutSaaS.Application/App/Finance/Transactions/Handlers/SearchFinanceTransactionListQueryHandler.cs

@@ -0,0 +1,49 @@
+using MediatR;
+using TakeoutSaaS.Application.App.Finance.Transactions.Dto;
+using TakeoutSaaS.Application.App.Finance.Transactions.Queries;
+using TakeoutSaaS.Domain.Finance.Repositories;
+using TakeoutSaaS.Shared.Abstractions.Tenancy;
+
+namespace TakeoutSaaS.Application.App.Finance.Transactions.Handlers;
+
+/// <summary>
+/// 交易流水列表查询处理器。
+/// </summary>
+public sealed class SearchFinanceTransactionListQueryHandler(
+    IFinanceTransactionRepository financeTransactionRepository,
+    ITenantProvider tenantProvider)
+    : IRequestHandler<SearchFinanceTransactionListQuery, FinanceTransactionListResultDto>
+{
+    /// <inheritdoc />
+    public async Task<FinanceTransactionListResultDto> Handle(SearchFinanceTransactionListQuery request, CancellationToken cancellationToken)
+    {
+        // 1. 读取租户上下文并执行分页查询。
+        var tenantId = tenantProvider.GetCurrentTenantId();
+        var page = Math.Max(1, request.Page);
+        var pageSize = Math.Clamp(request.PageSize, 1, 200);
+
+        var snapshot = await financeTransactionRepository.SearchPageAsync(
+            tenantId,
+            request.StoreId,
+            request.StartAt,
+            request.EndAt,
+            request.TransactionType,
+            request.DeliveryType,
+            request.PaymentMethod,
+            request.Keyword,
+            page,
+            pageSize,
+            cancellationToken);
+
+        // 2. 映射结果并返回。
+        return new FinanceTransactionListResultDto
+        {
+            Items = snapshot.Items.Select(FinanceTransactionMapping.ToListItem).ToList(),
+            Total = snapshot.TotalCount,
+            Page = page,
+            PageSize = pageSize,
+            PageIncomeAmount = snapshot.PageIncomeAmount,
+            PageRefundAmount = snapshot.PageRefundAmount
+        };
+    }
+}

src/Application/TakeoutSaaS.Application/App/Finance/Transactions/Queries/ExportFinanceTransactionCsvQuery.cs

@@ -0,0 +1,11 @@
+using MediatR;
+using TakeoutSaaS.Application.App.Finance.Transactions.Dto;
+
+namespace TakeoutSaaS.Application.App.Finance.Transactions.Queries;
+
+/// <summary>
+/// 交易流水 CSV 导出查询。
+/// </summary>
+public sealed class ExportFinanceTransactionCsvQuery : FinanceTransactionFilterQueryBase, IRequest<FinanceTransactionExportDto>
+{
+}

src/Application/TakeoutSaaS.Application/App/Finance/Transactions/Queries/FinanceTransactionFilterQueryBase.cs

@@ -0,0 +1,46 @@
+using TakeoutSaaS.Domain.Finance.Enums;
+using TakeoutSaaS.Domain.Orders.Enums;
+using TakeoutSaaS.Domain.Payments.Enums;
+
+namespace TakeoutSaaS.Application.App.Finance.Transactions.Queries;
+
+/// <summary>
+/// 交易流水筛选查询基类。
+/// </summary>
+public abstract class FinanceTransactionFilterQueryBase
+{
+    /// <summary>
+    /// 门店 ID。
+    /// </summary>
+    public long StoreId { get; init; }
+
+    /// <summary>
+    /// 开始时间（含）。
+    /// </summary>
+    public DateTime? StartAt { get; init; }
+
+    /// <summary>
+    /// 结束时间（不含）。
+    /// </summary>
+    public DateTime? EndAt { get; init; }
+
+    /// <summary>
+    /// 交易类型。
+    /// </summary>
+    public FinanceTransactionType? TransactionType { get; init; }
+
+    /// <summary>
+    /// 渠道。
+    /// </summary>
+    public DeliveryType? DeliveryType { get; init; }
+
+    /// <summary>
+    /// 支付方式。
+    /// </summary>
+    public PaymentMethod? PaymentMethod { get; init; }
+
+    /// <summary>
+    /// 关键词。
+    /// </summary>
+    public string? Keyword { get; init; }
+}

src/Application/TakeoutSaaS.Application/App/Finance/Transactions/Queries/GetFinanceTransactionDetailQuery.cs

@@ -0,0 +1,26 @@
+using MediatR;
+using TakeoutSaaS.Application.App.Finance.Transactions.Dto;
+using TakeoutSaaS.Domain.Finance.Enums;
+
+namespace TakeoutSaaS.Application.App.Finance.Transactions.Queries;
+
+/// <summary>
+/// 交易流水详情查询。
+/// </summary>
+public sealed class GetFinanceTransactionDetailQuery : IRequest<FinanceTransactionDetailDto?>
+{
+    /// <summary>
+    /// 门店 ID。
+    /// </summary>
+    public long StoreId { get; init; }
+
+    /// <summary>
+    /// 来源类型。
+    /// </summary>
+    public FinanceTransactionSourceType SourceType { get; init; }
+
+    /// <summary>
+    /// 来源标识。
+    /// </summary>
+    public long SourceId { get; init; }
+}

src/Application/TakeoutSaaS.Application/App/Finance/Transactions/Queries/GetFinanceTransactionStatsQuery.cs

@@ -0,0 +1,11 @@
+using MediatR;
+using TakeoutSaaS.Application.App.Finance.Transactions.Dto;
+
+namespace TakeoutSaaS.Application.App.Finance.Transactions.Queries;
+
+/// <summary>
+/// 交易流水统计查询。
+/// </summary>
+public sealed class GetFinanceTransactionStatsQuery : FinanceTransactionFilterQueryBase, IRequest<FinanceTransactionStatsDto>
+{
+}

src/Application/TakeoutSaaS.Application/App/Finance/Transactions/Queries/SearchFinanceTransactionListQuery.cs

@@ -0,0 +1,20 @@
+using MediatR;
+using TakeoutSaaS.Application.App.Finance.Transactions.Dto;
+
+namespace TakeoutSaaS.Application.App.Finance.Transactions.Queries;
+
+/// <summary>
+/// 交易流水列表查询。
+/// </summary>
+public sealed class SearchFinanceTransactionListQuery : FinanceTransactionFilterQueryBase, IRequest<FinanceTransactionListResultDto>
+{
+    /// <summary>
+    /// 页码。
+    /// </summary>
+    public int Page { get; init; } = 1;
+
+    /// <summary>
+    /// 每页条数。
+    /// </summary>
+    public int PageSize { get; init; } = 20;
+}