feat: 套餐管理与配额校验能力

2025-12-03 20:17:55 +08:00
parent ea33e6fefe
commit 19137f3cf7
25 changed files with 996 additions and 4 deletions
--- a/src/Api/TakeoutSaaS.AdminApi/Controllers/TenantPackagesController.cs
+++ b/src/Api/TakeoutSaaS.AdminApi/Controllers/TenantPackagesController.cs
@@ -0,0 +1,90 @@
+using System.ComponentModel.DataAnnotations;
+using MediatR;
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Http;
+using Microsoft.AspNetCore.Mvc;
+using TakeoutSaaS.Application.App.Tenants.Commands;
+using TakeoutSaaS.Application.App.Tenants.Dto;
+using TakeoutSaaS.Application.App.Tenants.Queries;
+using TakeoutSaaS.Module.Authorization.Attributes;
+using TakeoutSaaS.Shared.Abstractions.Results;
+using TakeoutSaaS.Shared.Web.Api;
+
+namespace TakeoutSaaS.AdminApi.Controllers;
+
+/// <summary>
+/// 租户套餐管理。
+/// </summary>
+[ApiVersion("1.0")]
+[Authorize]
+[Route("api/admin/v{version:apiVersion}/tenant-packages")]
+public sealed class TenantPackagesController(IMediator mediator) : BaseApiController
+{
+    /// <summary>
+    /// 分页查询租户套餐。
+    /// </summary>
+    [HttpGet]
+    [PermissionAuthorize("tenant-package:read")]
+    [ProducesResponseType(typeof(ApiResponse<PagedResult<TenantPackageDto>>), StatusCodes.Status200OK)]
+    public async Task<ApiResponse<PagedResult<TenantPackageDto>>> Search([FromQuery] SearchTenantPackagesQuery query, CancellationToken cancellationToken)
+    {
+        var result = await mediator.Send(query, cancellationToken);
+        return ApiResponse<PagedResult<TenantPackageDto>>.Ok(result);
+    }
+
+    /// <summary>
+    /// 查看套餐详情。
+    /// </summary>
+    [HttpGet("{tenantPackageId:long}")]
+    [PermissionAuthorize("tenant-package:read")]
+    [ProducesResponseType(typeof(ApiResponse<TenantPackageDto>), StatusCodes.Status200OK)]
+    [ProducesResponseType(typeof(ApiResponse<TenantPackageDto>), StatusCodes.Status404NotFound)]
+    public async Task<ApiResponse<TenantPackageDto>> Detail(long tenantPackageId, CancellationToken cancellationToken)
+    {
+        var result = await mediator.Send(new GetTenantPackageByIdQuery { TenantPackageId = tenantPackageId }, cancellationToken);
+        return result is null
+            ? ApiResponse<TenantPackageDto>.Error(StatusCodes.Status404NotFound, "套餐不存在")
+            : ApiResponse<TenantPackageDto>.Ok(result);
+    }
+
+    /// <summary>
+    /// 创建套餐。
+    /// </summary>
+    [HttpPost]
+    [PermissionAuthorize("tenant-package:create")]
+    [ProducesResponseType(typeof(ApiResponse<TenantPackageDto>), StatusCodes.Status200OK)]
+    public async Task<ApiResponse<TenantPackageDto>> Create([FromBody, Required] CreateTenantPackageCommand command, CancellationToken cancellationToken)
+    {
+        var result = await mediator.Send(command, cancellationToken);
+        return ApiResponse<TenantPackageDto>.Ok(result);
+    }
+
+    /// <summary>
+    /// 更新套餐。
+    /// </summary>
+    [HttpPut("{tenantPackageId:long}")]
+    [PermissionAuthorize("tenant-package:update")]
+    [ProducesResponseType(typeof(ApiResponse<TenantPackageDto>), StatusCodes.Status200OK)]
+    [ProducesResponseType(typeof(ApiResponse<TenantPackageDto>), StatusCodes.Status404NotFound)]
+    public async Task<ApiResponse<TenantPackageDto>> Update(long tenantPackageId, [FromBody, Required] UpdateTenantPackageCommand command, CancellationToken cancellationToken)
+    {
+        command = command with { TenantPackageId = tenantPackageId };
+        var result = await mediator.Send(command, cancellationToken);
+        return result is null
+            ? ApiResponse<TenantPackageDto>.Error(StatusCodes.Status404NotFound, "套餐不存在")
+            : ApiResponse<TenantPackageDto>.Ok(result);
+    }
+
+    /// <summary>
+    /// 删除套餐。
+    /// </summary>
+    [HttpDelete("{tenantPackageId:long}")]
+    [PermissionAuthorize("tenant-package:delete")]
+    [ProducesResponseType(typeof(ApiResponse<bool>), StatusCodes.Status200OK)]
+    public async Task<ApiResponse<bool>> Delete(long tenantPackageId, CancellationToken cancellationToken)
+    {
+        var command = new DeleteTenantPackageCommand { TenantPackageId = tenantPackageId };
+        var result = await mediator.Send(command, cancellationToken);
+        return ApiResponse<bool>.Ok(result);
+    }
+}
--- a/src/Api/TakeoutSaaS.AdminApi/Controllers/TenantsController.cs
+++ b/src/Api/TakeoutSaaS.AdminApi/Controllers/TenantsController.cs
@@ -1,3 +1,4 @@
+using System.ComponentModel.DataAnnotations;
 using MediatR;
 using Microsoft.AspNetCore.Authorization;
 using Microsoft.AspNetCore.Http;
@@ -134,4 +135,21 @@ public sealed class TenantsController(IMediator mediator) : BaseApiController
        var result = await mediator.Send(query, cancellationToken);
        return ApiResponse<PagedResult<TenantAuditLogDto>>.Ok(result);
    }
+
+    /// <summary>
+    /// 配额校验并占用额度（门店/账号/短信/配送）。
+    /// </summary>
+    /// <remarks>需在请求头携带 X-Tenant-Id 对应的租户。</remarks>
+    [HttpPost("{tenantId:long}/quotas/check")]
+    [PermissionAuthorize("tenant:quota:check")]
+    [ProducesResponseType(typeof(ApiResponse<QuotaCheckResultDto>), StatusCodes.Status200OK)]
+    public async Task<ApiResponse<QuotaCheckResultDto>> CheckQuota(
+        long tenantId,
+        [FromBody, Required] CheckTenantQuotaCommand body,
+        CancellationToken cancellationToken)
+    {
+        var command = body with { TenantId = tenantId };
+        var result = await mediator.Send(command, cancellationToken);
+        return ApiResponse<QuotaCheckResultDto>.Ok(result);
+    }
 }
--- a/src/Application/TakeoutSaaS.Application/App/Tenants/Commands/CheckTenantQuotaCommand.cs
+++ b/src/Application/TakeoutSaaS.Application/App/Tenants/Commands/CheckTenantQuotaCommand.cs
@@ -0,0 +1,26 @@
+using MediatR;
+using TakeoutSaaS.Application.App.Tenants.Dto;
+using TakeoutSaaS.Domain.Tenants.Enums;
+
+namespace TakeoutSaaS.Application.App.Tenants.Commands;
+
+/// <summary>
+/// 校验并消费租户配额命令。
+/// </summary>
+public sealed record CheckTenantQuotaCommand : IRequest<QuotaCheckResultDto>
+{
+    /// <summary>
+    /// 目标租户 ID。
+    /// </summary>
+    public long TenantId { get; init; }
+
+    /// <summary>
+    /// 配额类型。
+    /// </summary>
+    public TenantQuotaType QuotaType { get; init; }
+
+    /// <summary>
+    /// 本次申请使用量。
+    /// </summary>
+    public decimal Delta { get; init; } = 1;
+}
--- a/src/Application/TakeoutSaaS.Application/App/Tenants/Commands/CreateTenantPackageCommand.cs
+++ b/src/Application/TakeoutSaaS.Application/App/Tenants/Commands/CreateTenantPackageCommand.cs
@@ -0,0 +1,71 @@
+using MediatR;
+using TakeoutSaaS.Application.App.Tenants.Dto;
+using TakeoutSaaS.Domain.Tenants.Enums;
+
+namespace TakeoutSaaS.Application.App.Tenants.Commands;
+
+/// <summary>
+/// 创建租户套餐命令。
+/// </summary>
+public sealed record CreateTenantPackageCommand : IRequest<TenantPackageDto>
+{
+    /// <summary>
+    /// 套餐名称。
+    /// </summary>
+    public string Name { get; init; } = string.Empty;
+
+    /// <summary>
+    /// 套餐描述。
+    /// </summary>
+    public string? Description { get; init; }
+
+    /// <summary>
+    /// 套餐类型。
+    /// </summary>
+    public TenantPackageType PackageType { get; init; } = TenantPackageType.Standard;
+
+    /// <summary>
+    /// 月付价格。
+    /// </summary>
+    public decimal? MonthlyPrice { get; init; }
+
+    /// <summary>
+    /// 年付价格。
+    /// </summary>
+    public decimal? YearlyPrice { get; init; }
+
+    /// <summary>
+    /// 最大门店数。
+    /// </summary>
+    public int? MaxStoreCount { get; init; }
+
+    /// <summary>
+    /// 最大账号数。
+    /// </summary>
+    public int? MaxAccountCount { get; init; }
+
+    /// <summary>
+    /// 存储上限（GB）。
+    /// </summary>
+    public int? MaxStorageGb { get; init; }
+
+    /// <summary>
+    /// 短信额度。
+    /// </summary>
+    public int? MaxSmsCredits { get; init; }
+
+    /// <summary>
+    /// 配送单上限。
+    /// </summary>
+    public int? MaxDeliveryOrders { get; init; }
+
+    /// <summary>
+    /// 权益明细 JSON。
+    /// </summary>
+    public string? FeaturePoliciesJson { get; init; }
+
+    /// <summary>
+    /// 是否可售。
+    /// </summary>
+    public bool IsActive { get; init; } = true;
+}
--- a/src/Application/TakeoutSaaS.Application/App/Tenants/Commands/DeleteTenantPackageCommand.cs
+++ b/src/Application/TakeoutSaaS.Application/App/Tenants/Commands/DeleteTenantPackageCommand.cs
@@ -0,0 +1,14 @@
+using MediatR;
+
+namespace TakeoutSaaS.Application.App.Tenants.Commands;
+
+/// <summary>
+/// 删除租户套餐命令。
+/// </summary>
+public sealed record DeleteTenantPackageCommand : IRequest<bool>
+{
+    /// <summary>
+    /// 套餐 ID。
+    /// </summary>
+    public long TenantPackageId { get; init; }
+}
--- a/src/Application/TakeoutSaaS.Application/App/Tenants/Commands/UpdateTenantPackageCommand.cs
+++ b/src/Application/TakeoutSaaS.Application/App/Tenants/Commands/UpdateTenantPackageCommand.cs
@@ -0,0 +1,76 @@
+using MediatR;
+using TakeoutSaaS.Application.App.Tenants.Dto;
+using TakeoutSaaS.Domain.Tenants.Enums;
+
+namespace TakeoutSaaS.Application.App.Tenants.Commands;
+
+/// <summary>
+/// 更新租户套餐命令。
+/// </summary>
+public sealed record UpdateTenantPackageCommand : IRequest<TenantPackageDto?>
+{
+    /// <summary>
+    /// 套餐 ID。
+    /// </summary>
+    public long TenantPackageId { get; init; }
+
+    /// <summary>
+    /// 套餐名称。
+    /// </summary>
+    public string Name { get; init; } = string.Empty;
+
+    /// <summary>
+    /// 套餐描述。
+    /// </summary>
+    public string? Description { get; init; }
+
+    /// <summary>
+    /// 套餐类型。
+    /// </summary>
+    public TenantPackageType PackageType { get; init; } = TenantPackageType.Standard;
+
+    /// <summary>
+    /// 月付价格。
+    /// </summary>
+    public decimal? MonthlyPrice { get; init; }
+
+    /// <summary>
+    /// 年付价格。
+    /// </summary>
+    public decimal? YearlyPrice { get; init; }
+
+    /// <summary>
+    /// 最大门店数。
+    /// </summary>
+    public int? MaxStoreCount { get; init; }
+
+    /// <summary>
+    /// 最大账号数。
+    /// </summary>
+    public int? MaxAccountCount { get; init; }
+
+    /// <summary>
+    /// 存储上限（GB）。
+    /// </summary>
+    public int? MaxStorageGb { get; init; }
+
+    /// <summary>
+    /// 短信额度。
+    /// </summary>
+    public int? MaxSmsCredits { get; init; }
+
+    /// <summary>
+    /// 配送单上限。
+    /// </summary>
+    public int? MaxDeliveryOrders { get; init; }
+
+    /// <summary>
+    /// 权益明细 JSON。
+    /// </summary>
+    public string? FeaturePoliciesJson { get; init; }
+
+    /// <summary>
+    /// 是否可售。
+    /// </summary>
+    public bool IsActive { get; init; } = true;
+}
--- a/src/Application/TakeoutSaaS.Application/App/Tenants/Dto/QuotaCheckResultDto.cs
+++ b/src/Application/TakeoutSaaS.Application/App/Tenants/Dto/QuotaCheckResultDto.cs
@@ -0,0 +1,29 @@
+using TakeoutSaaS.Domain.Tenants.Enums;
+
+namespace TakeoutSaaS.Application.App.Tenants.Dto;
+
+/// <summary>
+/// 配额校验结果。
+/// </summary>
+public sealed class QuotaCheckResultDto
+{
+    /// <summary>
+    /// 配额类型。
+    /// </summary>
+    public TenantQuotaType QuotaType { get; init; }
+
+    /// <summary>
+    /// 当前配额上限，null 表示无限制。
+    /// </summary>
+    public decimal? Limit { get; init; }
+
+    /// <summary>
+    /// 已使用数量。
+    /// </summary>
+    public decimal Used { get; init; }
+
+    /// <summary>
+    /// 剩余额度，null 表示无限制。
+    /// </summary>
+    public decimal? Remaining { get; init; }
+}
--- a/src/Application/TakeoutSaaS.Application/App/Tenants/Dto/TenantPackageDto.cs
+++ b/src/Application/TakeoutSaaS.Application/App/Tenants/Dto/TenantPackageDto.cs
@@ -0,0 +1,77 @@
+using System.Text.Json.Serialization;
+using TakeoutSaaS.Domain.Tenants.Enums;
+using TakeoutSaaS.Shared.Abstractions.Serialization;
+
+namespace TakeoutSaaS.Application.App.Tenants.Dto;
+
+/// <summary>
+/// 租户套餐 DTO。
+/// </summary>
+public sealed class TenantPackageDto
+{
+    /// <summary>
+    /// 套餐 ID。
+    /// </summary>
+    [JsonConverter(typeof(SnowflakeIdJsonConverter))]
+    public long Id { get; init; }
+
+    /// <summary>
+    /// 套餐名称。
+    /// </summary>
+    public string Name { get; init; } = string.Empty;
+
+    /// <summary>
+    /// 描述。
+    /// </summary>
+    public string? Description { get; init; }
+
+    /// <summary>
+    /// 套餐类型。
+    /// </summary>
+    public TenantPackageType PackageType { get; init; }
+
+    /// <summary>
+    /// 月付价格。
+    /// </summary>
+    public decimal? MonthlyPrice { get; init; }
+
+    /// <summary>
+    /// 年付价格。
+    /// </summary>
+    public decimal? YearlyPrice { get; init; }
+
+    /// <summary>
+    /// 最大门店数。
+    /// </summary>
+    public int? MaxStoreCount { get; init; }
+
+    /// <summary>
+    /// 最大账号数。
+    /// </summary>
+    public int? MaxAccountCount { get; init; }
+
+    /// <summary>
+    /// 存储上限（GB）。
+    /// </summary>
+    public int? MaxStorageGb { get; init; }
+
+    /// <summary>
+    /// 短信额度。
+    /// </summary>
+    public int? MaxSmsCredits { get; init; }
+
+    /// <summary>
+    /// 配送单上限。
+    /// </summary>
+    public int? MaxDeliveryOrders { get; init; }
+
+    /// <summary>
+    /// 权益明细 JSON。
+    /// </summary>
+    public string? FeaturePoliciesJson { get; init; }
+
+    /// <summary>
+    /// 是否可售。
+    /// </summary>
+    public bool IsActive { get; init; }
+}
--- a/src/Application/TakeoutSaaS.Application/App/Tenants/Handlers/CheckTenantQuotaCommandHandler.cs
+++ b/src/Application/TakeoutSaaS.Application/App/Tenants/Handlers/CheckTenantQuotaCommandHandler.cs
@@ -0,0 +1,127 @@
+using System;
+using MediatR;
+using TakeoutSaaS.Application.App.Tenants.Commands;
+using TakeoutSaaS.Application.App.Tenants.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.Tenancy;
+
+namespace TakeoutSaaS.Application.App.Tenants.Handlers;
+
+/// <summary>
+/// 配额校验处理器。
+/// </summary>
+public sealed class CheckTenantQuotaCommandHandler(
+    ITenantRepository tenantRepository,
+    ITenantPackageRepository packageRepository,
+    ITenantQuotaUsageRepository quotaUsageRepository,
+    ITenantProvider tenantProvider)
+    : IRequestHandler<CheckTenantQuotaCommand, QuotaCheckResultDto>
+{
+    /// <inheritdoc />
+    public async Task<QuotaCheckResultDto> Handle(CheckTenantQuotaCommand request, CancellationToken cancellationToken)
+    {
+        if (request.Delta <= 0)
+        {
+            throw new BusinessException(ErrorCodes.BadRequest, "配额消耗量必须大于 0");
+        }
+
+        var currentTenantId = tenantProvider.GetCurrentTenantId();
+        if (currentTenantId == 0 || currentTenantId != request.TenantId)
+        {
+            throw new BusinessException(ErrorCodes.Forbidden, "租户上下文不匹配，请在请求头 X-Tenant-Id 指定目标租户");
+        }
+
+        // 1. 获取租户与当前订阅。
+        _ = await tenantRepository.FindByIdAsync(request.TenantId, cancellationToken)
+            ?? throw new BusinessException(ErrorCodes.NotFound, "租户不存在");
+
+        var subscription = await tenantRepository.GetActiveSubscriptionAsync(request.TenantId, cancellationToken);
+        if (subscription == null || subscription.EffectiveTo <= DateTime.UtcNow)
+        {
+            throw new BusinessException(ErrorCodes.Conflict, "订阅不存在或已到期");
+        }
+
+        var package = await packageRepository.FindByIdAsync(subscription.TenantPackageId, cancellationToken)
+            ?? throw new BusinessException(ErrorCodes.NotFound, "套餐不存在");
+
+        var limit = ResolveLimit(package, request.QuotaType);
+
+        // 2. 加载配额使用记录并计算。
+        var usage = await quotaUsageRepository.FindAsync(request.TenantId, request.QuotaType, cancellationToken)
+                    ?? new TenantQuotaUsage
+                    {
+                        TenantId = request.TenantId,
+                        QuotaType = request.QuotaType,
+                        LimitValue = limit ?? 0,
+                        UsedValue = 0,
+                        ResetCycle = ResolveResetCycle(request.QuotaType)
+                    };
+
+        var usedAfter = usage.UsedValue + request.Delta;
+        if (limit.HasValue && usedAfter > (decimal)limit.Value)
+        {
+            usage.LimitValue = limit.Value;
+            await PersistUsageAsync(usage, quotaUsageRepository, cancellationToken);
+            throw new BusinessException(ErrorCodes.Conflict, $"{request.QuotaType} 配额不足");
+        }
+
+        usage.LimitValue = limit ?? usage.LimitValue;
+        usage.UsedValue = usedAfter;
+        usage.ResetCycle ??= ResolveResetCycle(request.QuotaType);
+
+        await PersistUsageAsync(usage, quotaUsageRepository, cancellationToken);
+
+        return new QuotaCheckResultDto
+        {
+            QuotaType = request.QuotaType,
+            Limit = limit,
+            Used = usage.UsedValue,
+            Remaining = limit.HasValue ? limit.Value - usage.UsedValue : null
+        };
+    }
+
+    private static decimal? ResolveLimit(TenantPackage package, TenantQuotaType quotaType)
+    {
+        return quotaType switch
+        {
+            TenantQuotaType.StoreCount => package.MaxStoreCount,
+            TenantQuotaType.AccountCount => package.MaxAccountCount,
+            TenantQuotaType.Storage => package.MaxStorageGb,
+            TenantQuotaType.SmsCredits => package.MaxSmsCredits,
+            TenantQuotaType.DeliveryOrders => package.MaxDeliveryOrders,
+            _ => null
+        };
+    }
+
+    private static string ResolveResetCycle(TenantQuotaType quotaType)
+    {
+        return quotaType switch
+        {
+            TenantQuotaType.SmsCredits => "monthly",
+            TenantQuotaType.DeliveryOrders => "monthly",
+            _ => "lifetime"
+        };
+    }
+
+    private static async Task PersistUsageAsync(
+        TenantQuotaUsage usage,
+        ITenantQuotaUsageRepository quotaUsageRepository,
+        CancellationToken cancellationToken)
+    {
+        // 判断是否为新增。
+        if (usage.Id == 0)
+        {
+            await quotaUsageRepository.AddAsync(usage, cancellationToken);
+        }
+        else
+        {
+            await quotaUsageRepository.UpdateAsync(usage, cancellationToken);
+        }
+
+        await quotaUsageRepository.SaveChangesAsync(cancellationToken);
+    }
+}
--- a/src/Application/TakeoutSaaS.Application/App/Tenants/Handlers/CreateTenantPackageCommandHandler.cs
+++ b/src/Application/TakeoutSaaS.Application/App/Tenants/Handlers/CreateTenantPackageCommandHandler.cs
@@ -0,0 +1,46 @@
+using MediatR;
+using TakeoutSaaS.Application.App.Tenants.Commands;
+using TakeoutSaaS.Application.App.Tenants.Dto;
+using TakeoutSaaS.Domain.Tenants.Entities;
+using TakeoutSaaS.Domain.Tenants.Repositories;
+using TakeoutSaaS.Shared.Abstractions.Constants;
+using TakeoutSaaS.Shared.Abstractions.Exceptions;
+
+namespace TakeoutSaaS.Application.App.Tenants.Handlers;
+
+/// <summary>
+/// 创建租户套餐处理器。
+/// </summary>
+public sealed class CreateTenantPackageCommandHandler(ITenantPackageRepository packageRepository)
+    : IRequestHandler<CreateTenantPackageCommand, TenantPackageDto>
+{
+    /// <inheritdoc />
+    public async Task<TenantPackageDto> Handle(CreateTenantPackageCommand request, CancellationToken cancellationToken)
+    {
+        if (string.IsNullOrWhiteSpace(request.Name))
+        {
+            throw new BusinessException(ErrorCodes.BadRequest, "套餐名称不能为空");
+        }
+
+        var package = new TenantPackage
+        {
+            Name = request.Name.Trim(),
+            Description = request.Description,
+            PackageType = request.PackageType,
+            MonthlyPrice = request.MonthlyPrice,
+            YearlyPrice = request.YearlyPrice,
+            MaxStoreCount = request.MaxStoreCount,
+            MaxAccountCount = request.MaxAccountCount,
+            MaxStorageGb = request.MaxStorageGb,
+            MaxSmsCredits = request.MaxSmsCredits,
+            MaxDeliveryOrders = request.MaxDeliveryOrders,
+            FeaturePoliciesJson = request.FeaturePoliciesJson,
+            IsActive = request.IsActive
+        };
+
+        await packageRepository.AddAsync(package, cancellationToken);
+        await packageRepository.SaveChangesAsync(cancellationToken);
+
+        return package.ToDto();
+    }
+}
--- a/src/Application/TakeoutSaaS.Application/App/Tenants/Handlers/DeleteTenantPackageCommandHandler.cs
+++ b/src/Application/TakeoutSaaS.Application/App/Tenants/Handlers/DeleteTenantPackageCommandHandler.cs
@@ -0,0 +1,20 @@
+using MediatR;
+using TakeoutSaaS.Application.App.Tenants.Commands;
+using TakeoutSaaS.Domain.Tenants.Repositories;
+
+namespace TakeoutSaaS.Application.App.Tenants.Handlers;
+
+/// <summary>
+/// 删除租户套餐处理器。
+/// </summary>
+public sealed class DeleteTenantPackageCommandHandler(ITenantPackageRepository packageRepository)
+    : IRequestHandler<DeleteTenantPackageCommand, bool>
+{
+    /// <inheritdoc />
+    public async Task<bool> Handle(DeleteTenantPackageCommand request, CancellationToken cancellationToken)
+    {
+        await packageRepository.DeleteAsync(request.TenantPackageId, cancellationToken);
+        await packageRepository.SaveChangesAsync(cancellationToken);
+        return true;
+    }
+}
--- a/src/Application/TakeoutSaaS.Application/App/Tenants/Handlers/GetTenantPackageByIdQueryHandler.cs
+++ b/src/Application/TakeoutSaaS.Application/App/Tenants/Handlers/GetTenantPackageByIdQueryHandler.cs
@@ -0,0 +1,20 @@
+using MediatR;
+using TakeoutSaaS.Application.App.Tenants.Dto;
+using TakeoutSaaS.Application.App.Tenants.Queries;
+using TakeoutSaaS.Domain.Tenants.Repositories;
+
+namespace TakeoutSaaS.Application.App.Tenants.Handlers;
+
+/// <summary>
+/// 套餐详情查询处理器。
+/// </summary>
+public sealed class GetTenantPackageByIdQueryHandler(ITenantPackageRepository packageRepository)
+    : IRequestHandler<GetTenantPackageByIdQuery, TenantPackageDto?>
+{
+    /// <inheritdoc />
+    public async Task<TenantPackageDto?> Handle(GetTenantPackageByIdQuery request, CancellationToken cancellationToken)
+    {
+        var package = await packageRepository.FindByIdAsync(request.TenantPackageId, cancellationToken);
+        return package?.ToDto();
+    }
+}
--- a/src/Application/TakeoutSaaS.Application/App/Tenants/Handlers/SearchTenantPackagesQueryHandler.cs
+++ b/src/Application/TakeoutSaaS.Application/App/Tenants/Handlers/SearchTenantPackagesQueryHandler.cs
@@ -0,0 +1,33 @@
+using System.Linq;
+using MediatR;
+using TakeoutSaaS.Application.App.Tenants.Dto;
+using TakeoutSaaS.Application.App.Tenants.Queries;
+using TakeoutSaaS.Domain.Tenants.Repositories;
+using TakeoutSaaS.Shared.Abstractions.Results;
+
+namespace TakeoutSaaS.Application.App.Tenants.Handlers;
+
+/// <summary>
+/// 套餐分页查询处理器。
+/// </summary>
+public sealed class SearchTenantPackagesQueryHandler(ITenantPackageRepository packageRepository)
+    : IRequestHandler<SearchTenantPackagesQuery, PagedResult<TenantPackageDto>>
+{
+    /// <inheritdoc />
+    public async Task<PagedResult<TenantPackageDto>> Handle(SearchTenantPackagesQuery request, CancellationToken cancellationToken)
+    {
+        var packages = await packageRepository.SearchAsync(request.Keyword, request.IsActive, cancellationToken);
+
+        var ordered = packages.OrderByDescending(x => x.CreatedAt).ToList();
+        var pageIndex = request.Page <= 0 ? 1 : request.Page;
+        var size = request.PageSize <= 0 ? 20 : request.PageSize;
+
+        var pagedItems = ordered
+            .Skip((pageIndex - 1) * size)
+            .Take(size)
+            .Select(x => x.ToDto())
+            .ToList();
+
+        return new PagedResult<TenantPackageDto>(pagedItems, pageIndex, size, ordered.Count);
+    }
+}
--- a/src/Application/TakeoutSaaS.Application/App/Tenants/Handlers/UpdateTenantPackageCommandHandler.cs
+++ b/src/Application/TakeoutSaaS.Application/App/Tenants/Handlers/UpdateTenantPackageCommandHandler.cs
@@ -0,0 +1,48 @@
+using MediatR;
+using TakeoutSaaS.Application.App.Tenants.Commands;
+using TakeoutSaaS.Application.App.Tenants.Dto;
+using TakeoutSaaS.Domain.Tenants.Repositories;
+using TakeoutSaaS.Shared.Abstractions.Constants;
+using TakeoutSaaS.Shared.Abstractions.Exceptions;
+
+namespace TakeoutSaaS.Application.App.Tenants.Handlers;
+
+/// <summary>
+/// 更新租户套餐处理器。
+/// </summary>
+public sealed class UpdateTenantPackageCommandHandler(ITenantPackageRepository packageRepository)
+    : IRequestHandler<UpdateTenantPackageCommand, TenantPackageDto?>
+{
+    /// <inheritdoc />
+    public async Task<TenantPackageDto?> Handle(UpdateTenantPackageCommand request, CancellationToken cancellationToken)
+    {
+        if (string.IsNullOrWhiteSpace(request.Name))
+        {
+            throw new BusinessException(ErrorCodes.BadRequest, "套餐名称不能为空");
+        }
+
+        var package = await packageRepository.FindByIdAsync(request.TenantPackageId, cancellationToken);
+        if (package == null)
+        {
+            return null;
+        }
+
+        package.Name = request.Name.Trim();
+        package.Description = request.Description;
+        package.PackageType = request.PackageType;
+        package.MonthlyPrice = request.MonthlyPrice;
+        package.YearlyPrice = request.YearlyPrice;
+        package.MaxStoreCount = request.MaxStoreCount;
+        package.MaxAccountCount = request.MaxAccountCount;
+        package.MaxStorageGb = request.MaxStorageGb;
+        package.MaxSmsCredits = request.MaxSmsCredits;
+        package.MaxDeliveryOrders = request.MaxDeliveryOrders;
+        package.FeaturePoliciesJson = request.FeaturePoliciesJson;
+        package.IsActive = request.IsActive;
+
+        await packageRepository.UpdateAsync(package, cancellationToken);
+        await packageRepository.SaveChangesAsync(cancellationToken);
+
+        return package.ToDto();
+    }
+}
--- a/src/Application/TakeoutSaaS.Application/App/Tenants/Queries/GetTenantPackageByIdQuery.cs
+++ b/src/Application/TakeoutSaaS.Application/App/Tenants/Queries/GetTenantPackageByIdQuery.cs
@@ -0,0 +1,15 @@
+using MediatR;
+using TakeoutSaaS.Application.App.Tenants.Dto;
+
+namespace TakeoutSaaS.Application.App.Tenants.Queries;
+
+/// <summary>
+/// 获取套餐详情查询。
+/// </summary>
+public sealed record GetTenantPackageByIdQuery : IRequest<TenantPackageDto?>
+{
+    /// <summary>
+    /// 套餐 ID。
+    /// </summary>
+    public long TenantPackageId { get; init; }
+}
--- a/src/Application/TakeoutSaaS.Application/App/Tenants/Queries/SearchTenantPackagesQuery.cs
+++ b/src/Application/TakeoutSaaS.Application/App/Tenants/Queries/SearchTenantPackagesQuery.cs
@@ -0,0 +1,31 @@
+using MediatR;
+using TakeoutSaaS.Application.App.Tenants.Dto;
+using TakeoutSaaS.Shared.Abstractions.Results;
+
+namespace TakeoutSaaS.Application.App.Tenants.Queries;
+
+/// <summary>
+/// 分页查询租户套餐。
+/// </summary>
+public sealed record SearchTenantPackagesQuery : IRequest<PagedResult<TenantPackageDto>>
+{
+    /// <summary>
+    /// 搜索关键词（名称/描述）。
+    /// </summary>
+    public string? Keyword { get; init; }
+
+    /// <summary>
+    /// 是否筛选可售套餐。
+    /// </summary>
+    public bool? IsActive { get; init; }
+
+    /// <summary>
+    /// 页码。
+    /// </summary>
+    public int Page { get; init; } = 1;
+
+    /// <summary>
+    /// 每页条数。
+    /// </summary>
+    public int PageSize { get; init; } = 20;
+}
--- a/src/Application/TakeoutSaaS.Application/App/Tenants/TenantMapping.cs
+++ b/src/Application/TakeoutSaaS.Application/App/Tenants/TenantMapping.cs
@@ -73,4 +73,22 @@ internal static class TenantMapping
            CurrentStatus = log.CurrentStatus,
            CreatedAt = log.CreatedAt
        };
+
+    public static TenantPackageDto ToDto(this TenantPackage package)
+        => new()
+        {
+            Id = package.Id,
+            Name = package.Name,
+            Description = package.Description,
+            PackageType = package.PackageType,
+            MonthlyPrice = package.MonthlyPrice,
+            YearlyPrice = package.YearlyPrice,
+            MaxStoreCount = package.MaxStoreCount,
+            MaxAccountCount = package.MaxAccountCount,
+            MaxStorageGb = package.MaxStorageGb,
+            MaxSmsCredits = package.MaxSmsCredits,
+            MaxDeliveryOrders = package.MaxDeliveryOrders,
+            FeaturePoliciesJson = package.FeaturePoliciesJson,
+            IsActive = package.IsActive
+        };
 }
--- a/src/Application/TakeoutSaaS.Application/Identity/Templates/RoleTemplateProvider.cs
+++ b/src/Application/TakeoutSaaS.Application/Identity/Templates/RoleTemplateProvider.cs
@@ -98,6 +98,36 @@ public sealed class RoleTemplateProvider : IRoleTemplateProvider
                Name = "租户订阅管理",
                Description = "创建、续费或调整租户套餐订阅。"
            },
+            ["tenant:quota:check"] = new()
+            {
+                Code = "tenant:quota:check",
+                Name = "租户配额校验",
+                Description = "校验并占用门店、账号、短信、配送等配额。"
+            },
+            ["tenant-package:read"] = new()
+            {
+                Code = "tenant-package:read",
+                Name = "套餐查询",
+                Description = "查看平台套餐定义列表与详情。"
+            },
+            ["tenant-package:create"] = new()
+            {
+                Code = "tenant-package:create",
+                Name = "套餐创建",
+                Description = "创建平台套餐定义。"
+            },
+            ["tenant-package:update"] = new()
+            {
+                Code = "tenant-package:update",
+                Name = "套餐更新",
+                Description = "更新平台套餐定义。"
+            },
+            ["tenant-package:delete"] = new()
+            {
+                Code = "tenant-package:delete",
+                Name = "套餐删除",
+                Description = "删除平台套餐定义。"
+            },
            ["merchant:create"] = new()
            {
                Code = "merchant:create",
@@ -369,6 +399,7 @@ public sealed class RoleTemplateProvider : IRoleTemplateProvider
                    "identity:permission:delete",
                    "tenant:read",
                    "tenant:subscription",
+                    "tenant:quota:check",
                    "merchant:read",
                    "merchant:update",
                    "merchant_category:read",
--- a/src/Domain/TakeoutSaaS.Domain/Tenants/Repositories/ITenantPackageRepository.cs
+++ b/src/Domain/TakeoutSaaS.Domain/Tenants/Repositories/ITenantPackageRepository.cs
@@ -0,0 +1,42 @@
+using System.Collections.Generic;
+using System.Threading;
+using System.Threading.Tasks;
+using TakeoutSaaS.Domain.Tenants.Entities;
+
+namespace TakeoutSaaS.Domain.Tenants.Repositories;
+
+/// <summary>
+/// 租户套餐仓储。
+/// </summary>
+public interface ITenantPackageRepository
+{
+    /// <summary>
+    /// 按 ID 查询套餐。
+    /// </summary>
+    Task<TenantPackage?> FindByIdAsync(long id, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// 按关键词与启用状态搜索套餐。
+    /// </summary>
+    Task<IReadOnlyList<TenantPackage>> SearchAsync(string? keyword, bool? isActive, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// 新增套餐。
+    /// </summary>
+    Task AddAsync(TenantPackage package, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// 更新套餐。
+    /// </summary>
+    Task UpdateAsync(TenantPackage package, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// 删除套餐。
+    /// </summary>
+    Task DeleteAsync(long id, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// 持久化。
+    /// </summary>
+    Task SaveChangesAsync(CancellationToken cancellationToken = default);
+}
--- a/src/Domain/TakeoutSaaS.Domain/Tenants/Repositories/ITenantQuotaUsageRepository.cs
+++ b/src/Domain/TakeoutSaaS.Domain/Tenants/Repositories/ITenantQuotaUsageRepository.cs
@@ -0,0 +1,38 @@
+using System.Collections.Generic;
+using System.Threading;
+using System.Threading.Tasks;
+using TakeoutSaaS.Domain.Tenants.Entities;
+using TakeoutSaaS.Domain.Tenants.Enums;
+
+namespace TakeoutSaaS.Domain.Tenants.Repositories;
+
+/// <summary>
+/// 租户配额使用仓储。
+/// </summary>
+public interface ITenantQuotaUsageRepository
+{
+    /// <summary>
+    /// 获取租户指定配额的使用情况。
+    /// </summary>
+    Task<TenantQuotaUsage?> FindAsync(long tenantId, TenantQuotaType quotaType, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// 按租户批量获取配额使用记录。
+    /// </summary>
+    Task<IReadOnlyList<TenantQuotaUsage>> GetByTenantAsync(long tenantId, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// 新增配额使用记录。
+    /// </summary>
+    Task AddAsync(TenantQuotaUsage usage, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// 更新配额使用记录。
+    /// </summary>
+    Task UpdateAsync(TenantQuotaUsage usage, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// 持久化。
+    /// </summary>
+    Task SaveChangesAsync(CancellationToken cancellationToken = default);
+}
--- a/src/Infrastructure/TakeoutSaaS.Infrastructure/App/Extensions/AppServiceCollectionExtensions.cs
+++ b/src/Infrastructure/TakeoutSaaS.Infrastructure/App/Extensions/AppServiceCollectionExtensions.cs
@@ -39,6 +39,8 @@ public static class AppServiceCollectionExtensions
        services.AddScoped<IPaymentRepository, EfPaymentRepository>();
        services.AddScoped<IDeliveryRepository, EfDeliveryRepository>();
        services.AddScoped<ITenantRepository, EfTenantRepository>();
+        services.AddScoped<ITenantPackageRepository, EfTenantPackageRepository>();
+        services.AddScoped<ITenantQuotaUsageRepository, EfTenantQuotaUsageRepository>();

        services.AddOptions<AppSeedOptions>()
            .Bind(configuration.GetSection(AppSeedOptions.SectionName))
--- a/src/Infrastructure/TakeoutSaaS.Infrastructure/App/Repositories/EfTenantPackageRepository.cs
+++ b/src/Infrastructure/TakeoutSaaS.Infrastructure/App/Repositories/EfTenantPackageRepository.cs
@@ -0,0 +1,69 @@
+using System.Linq;
+using Microsoft.EntityFrameworkCore;
+using TakeoutSaaS.Domain.Tenants.Entities;
+using TakeoutSaaS.Domain.Tenants.Repositories;
+using TakeoutSaaS.Infrastructure.App.Persistence;
+
+namespace TakeoutSaaS.Infrastructure.App.Repositories;
+
+/// <summary>
+/// 租户套餐仓储实现。
+/// </summary>
+public sealed class EfTenantPackageRepository(TakeoutAppDbContext context) : ITenantPackageRepository
+{
+    /// <inheritdoc />
+    public Task<TenantPackage?> FindByIdAsync(long id, CancellationToken cancellationToken = default)
+    {
+        return context.TenantPackages.AsNoTracking().FirstOrDefaultAsync(x => x.Id == id, cancellationToken);
+    }
+
+    /// <inheritdoc />
+    public async Task<IReadOnlyList<TenantPackage>> SearchAsync(string? keyword, bool? isActive, CancellationToken cancellationToken = default)
+    {
+        var query = context.TenantPackages.AsNoTracking();
+
+        if (!string.IsNullOrWhiteSpace(keyword))
+        {
+            var normalized = keyword.Trim();
+            query = query.Where(x => EF.Functions.ILike(x.Name, $"%{normalized}%") || EF.Functions.ILike(x.Description ?? string.Empty, $"%{normalized}%"));
+        }
+
+        if (isActive.HasValue)
+        {
+            query = query.Where(x => x.IsActive == isActive.Value);
+        }
+
+        return await query
+            .OrderByDescending(x => x.CreatedAt)
+            .ToListAsync(cancellationToken);
+    }
+
+    /// <inheritdoc />
+    public Task AddAsync(TenantPackage package, CancellationToken cancellationToken = default)
+    {
+        return context.TenantPackages.AddAsync(package, cancellationToken).AsTask();
+    }
+
+    /// <inheritdoc />
+    public Task UpdateAsync(TenantPackage package, CancellationToken cancellationToken = default)
+    {
+        context.TenantPackages.Update(package);
+        return Task.CompletedTask;
+    }
+
+    /// <inheritdoc />
+    public async Task DeleteAsync(long id, CancellationToken cancellationToken = default)
+    {
+        var entity = await context.TenantPackages.FirstOrDefaultAsync(x => x.Id == id, cancellationToken);
+        if (entity != null)
+        {
+            context.TenantPackages.Remove(entity);
+        }
+    }
+
+    /// <inheritdoc />
+    public Task SaveChangesAsync(CancellationToken cancellationToken = default)
+    {
+        return context.SaveChangesAsync(cancellationToken);
+    }
+}
--- a/src/Infrastructure/TakeoutSaaS.Infrastructure/App/Repositories/EfTenantQuotaUsageRepository.cs
+++ b/src/Infrastructure/TakeoutSaaS.Infrastructure/App/Repositories/EfTenantQuotaUsageRepository.cs
@@ -0,0 +1,51 @@
+using System.Linq;
+using Microsoft.EntityFrameworkCore;
+using TakeoutSaaS.Domain.Tenants.Entities;
+using TakeoutSaaS.Domain.Tenants.Enums;
+using TakeoutSaaS.Domain.Tenants.Repositories;
+using TakeoutSaaS.Infrastructure.App.Persistence;
+
+namespace TakeoutSaaS.Infrastructure.App.Repositories;
+
+/// <summary>
+/// 租户配额使用仓储实现。
+/// </summary>
+public sealed class EfTenantQuotaUsageRepository(TakeoutAppDbContext context) : ITenantQuotaUsageRepository
+{
+    /// <inheritdoc />
+    public Task<TenantQuotaUsage?> FindAsync(long tenantId, TenantQuotaType quotaType, CancellationToken cancellationToken = default)
+    {
+        return context.TenantQuotaUsages
+            .FirstOrDefaultAsync(x => x.TenantId == tenantId && x.QuotaType == quotaType, cancellationToken);
+    }
+
+    /// <inheritdoc />
+    public Task<IReadOnlyList<TenantQuotaUsage>> GetByTenantAsync(long tenantId, CancellationToken cancellationToken = default)
+    {
+        return context.TenantQuotaUsages
+            .AsNoTracking()
+            .Where(x => x.TenantId == tenantId)
+            .OrderBy(x => x.QuotaType)
+            .ToListAsync(cancellationToken)
+            .ContinueWith(t => (IReadOnlyList<TenantQuotaUsage>)t.Result, cancellationToken);
+    }
+
+    /// <inheritdoc />
+    public Task AddAsync(TenantQuotaUsage usage, CancellationToken cancellationToken = default)
+    {
+        return context.TenantQuotaUsages.AddAsync(usage, cancellationToken).AsTask();
+    }
+
+    /// <inheritdoc />
+    public Task UpdateAsync(TenantQuotaUsage usage, CancellationToken cancellationToken = default)
+    {
+        context.TenantQuotaUsages.Update(usage);
+        return Task.CompletedTask;
+    }
+
+    /// <inheritdoc />
+    public Task SaveChangesAsync(CancellationToken cancellationToken = default)
+    {
+        return context.SaveChangesAsync(cancellationToken);
+    }
+}