feat: 完成账单管理模块后端功能开发及API优化

核心功能:
- 账单CRUD操作(创建、查询、详情、更新状态、删除)
- 支付记录管理(创建支付、审核支付)
- 批量操作支持(批量更新账单状态)
- 统计分析功能(账单统计、逾期账单查询)
- 导出功能(Excel/PDF/CSV)

API端点 (16个):
- GET /api/admin/v1/billings - 账单列表(分页、筛选、排序)
- POST /api/admin/v1/billings - 创建账单
- GET /api/admin/v1/billings/{id} - 账单详情
- DELETE /api/admin/v1/billings/{id} - 删除账单
- PUT /api/admin/v1/billings/{id}/status - 更新状态
- POST /api/admin/v1/billings/batch/status - 批量更新
- GET /api/admin/v1/billings/{id}/payments - 支付记录
- POST /api/admin/v1/billings/{id}/payments - 创建支付
- PUT /api/admin/v1/billings/payments/{paymentId}/verify - 审核支付
- GET /api/admin/v1/billings/statistics - 统计数据
- GET /api/admin/v1/billings/overdue - 逾期账单
- POST /api/admin/v1/billings/export - 导出账单

架构优化:
- 采用CQRS模式分离读写(MediatR + Dapper + EF Core)
- 完整的领域模型设计(TenantBillingStatement, TenantPayment等)
- FluentValidation请求验证
- 状态机管理账单和支付状态流转

API设计优化 (三项改进):
1. 导出API响应Content-Type改为application/octet-stream
2. 支付审核API添加Approved和Notes可选参数,支持通过/拒绝
3. 移除TenantBillings API中重复的TenantId参数

数据库变更:
- 新增账单相关表及关系
- 支持Snowflake ID主键
- 完整的审计字段支持

🤖 Generated with Claude Code

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
2025-12-18 11:24:44 +08:00
parent 98f49ea7ad
commit 4b53862ded
73 changed files with 12688 additions and 305 deletions

View File

@@ -0,0 +1,88 @@
using MediatR;
using TakeoutSaaS.Application.App.Billings.Commands;
using TakeoutSaaS.Domain.Tenants.Repositories;
using TakeoutSaaS.Shared.Abstractions.Constants;
using TakeoutSaaS.Shared.Abstractions.Exceptions;
namespace TakeoutSaaS.Application.App.Billings.Handlers;
/// <summary>
/// 批量更新账单状态处理器。
/// </summary>
public sealed class BatchUpdateStatusCommandHandler(
ITenantBillingRepository billingRepository)
: IRequestHandler<BatchUpdateStatusCommand, int>
{
/// <summary>
/// 处理批量更新账单状态请求。
/// </summary>
/// <param name="request">批量更新状态命令。</param>
/// <param name="cancellationToken">取消标记。</param>
/// <returns>成功更新的账单数量。</returns>
public async Task<int> Handle(BatchUpdateStatusCommand request, CancellationToken cancellationToken)
{
// 1. 参数验证
if (request.BillingIds.Length == 0)
{
throw new BusinessException(ErrorCodes.BadRequest, "账单 ID 列表不能为空");
}
// 2. 查询所有账单
var billings = await billingRepository.GetByIdsAsync(request.BillingIds, cancellationToken);
if (billings.Count == 0)
{
throw new BusinessException(ErrorCodes.NotFound, "未找到任何匹配的账单");
}
// 3. 批量更新状态
var now = DateTime.UtcNow;
var updatedCount = 0;
foreach (var billing in billings)
{
// 业务规则检查:某些状态转换可能不允许
if (CanTransitionStatus(billing.Status, request.NewStatus))
{
billing.Status = request.NewStatus;
billing.UpdatedAt = now;
if (!string.IsNullOrWhiteSpace(request.Notes))
{
billing.Notes = string.IsNullOrWhiteSpace(billing.Notes)
? $"[批量操作] {request.Notes}"
: $"{billing.Notes}\n[批量操作] {request.Notes}";
}
await billingRepository.UpdateAsync(billing, cancellationToken);
updatedCount++;
}
}
// 4. 持久化变更
await billingRepository.SaveChangesAsync(cancellationToken);
return updatedCount;
}
/// <summary>
/// 检查状态转换是否允许。
/// </summary>
private static bool CanTransitionStatus(
TakeoutSaaS.Domain.Tenants.Enums.TenantBillingStatus currentStatus,
TakeoutSaaS.Domain.Tenants.Enums.TenantBillingStatus newStatus)
{
// 已支付的账单不能改为其他状态
if (currentStatus == TakeoutSaaS.Domain.Tenants.Enums.TenantBillingStatus.Paid
&& newStatus != TakeoutSaaS.Domain.Tenants.Enums.TenantBillingStatus.Paid)
{
return false;
}
// 已取消的账单不能改为其他状态
if (currentStatus == TakeoutSaaS.Domain.Tenants.Enums.TenantBillingStatus.Cancelled)
{
return false;
}
return true;
}
}