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,73 @@
using FluentValidation;
using TakeoutSaaS.Application.App.Billings.Commands;
namespace TakeoutSaaS.Application.App.Billings.Validators;
/// <summary>
/// 创建账单命令验证器。
/// </summary>
public sealed class CreateBillingCommandValidator : AbstractValidator<CreateBillingCommand>
{
public CreateBillingCommandValidator()
{
// 1. 租户 ID 必填
RuleFor(x => x.TenantId)
.GreaterThan(0)
.WithMessage("租户 ID 必须大于 0");
// 2. (空行后) 账单类型必填
RuleFor(x => x.BillingType)
.IsInEnum()
.WithMessage("账单类型无效");
// 3. (空行后) 应付金额必须大于 0
RuleFor(x => x.AmountDue)
.GreaterThan(0)
.WithMessage("应付金额必须大于 0");
// 4. (空行后) 到期日必须是未来时间
RuleFor(x => x.DueDate)
.GreaterThan(DateTime.UtcNow)
.WithMessage("到期日必须是未来时间");
// 5. (空行后) 账单明细至少包含一项
RuleFor(x => x.LineItems)
.NotEmpty()
.WithMessage("账单明细不能为空");
// 6. (空行后) 账单明细项验证
RuleForEach(x => x.LineItems)
.ChildRules(lineItem =>
{
lineItem.RuleFor(x => x.ItemType)
.NotEmpty()
.WithMessage("账单明细类型不能为空")
.MaximumLength(50)
.WithMessage("账单明细类型不能超过 50 个字符");
lineItem.RuleFor(x => x.Description)
.NotEmpty()
.WithMessage("账单明细描述不能为空")
.MaximumLength(200)
.WithMessage("账单明细描述不能超过 200 个字符");
lineItem.RuleFor(x => x.Quantity)
.GreaterThan(0)
.WithMessage("账单明细数量必须大于 0");
lineItem.RuleFor(x => x.UnitPrice)
.GreaterThanOrEqualTo(0)
.WithMessage("账单明细单价不能为负数");
lineItem.RuleFor(x => x.Amount)
.GreaterThanOrEqualTo(0)
.WithMessage("账单明细金额不能为负数");
});
// 7. (空行后) 备注长度限制(可选)
RuleFor(x => x.Notes)
.MaximumLength(500)
.WithMessage("备注不能超过 500 个字符")
.When(x => !string.IsNullOrWhiteSpace(x.Notes));
}
}