feat: اصلاح سند payment corrections + audit-log & daily P&L views

Backend:
- POST /orders/{id}/payments/corrections (Manager/Owner): void wrong
  payments (marked Refunded, never deleted) and/or record replacements
  atomically; mandatory reason; requires an open register shift; full
  before/after written to the immutable audit trail.
- GET /orders/closed?date= — closed orders of one Iran-calendar day,
  paged, the browsing surface for corrections.
- CalculateExpectedCash now subtracts cash refunds so corrections keep
  the drawer expectation honest.

Dashboard (reports screen now has three tabs):
- عملکرد و سود: existing KPIs/charts + new day-by-day breakdown table
  (orders, revenue, expenses, net profit per Jalali day).
- اصلاح سند: closed-orders browser with payment chips + correction
  dialog (void checkboxes, replacement rows, live balance, reason).
- گزارش عملیات: filterable audit-log viewer (category, Jalali range,
  branch) with expandable structured details.

fa/en/ar translations included. 86 backend tests pass; dashboard tsc clean.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

src/Meezi.API/Controllers/OrdersController.cs

@@ -20,6 +20,7 @@ public class OrdersController : CafeApiControllerBase
     private readonly IValidator<RecordPaymentsRequest> _paymentsValidator;
     private readonly IValidator<AppendOrderItemsRequest> _appendValidator;
     private readonly IValidator<UpdateOrderSessionRequest> _sessionValidator;
+    private readonly IValidator<CorrectPaymentsRequest> _correctionValidator;
 
     public OrdersController(
         IOrderService orderService,
@@ -28,7 +29,8 @@ public class OrdersController : CafeApiControllerBase
         IValidator<UpdateOrderStatusRequest> statusValidator,
         IValidator<RecordPaymentsRequest> paymentsValidator,
         IValidator<AppendOrderItemsRequest> appendValidator,
-        IValidator<UpdateOrderSessionRequest> sessionValidator)
+        IValidator<UpdateOrderSessionRequest> sessionValidator,
+        IValidator<CorrectPaymentsRequest> correctionValidator)
     {
         _orderService = orderService;
         _audit = audit;
@@ -37,6 +39,7 @@ public class OrdersController : CafeApiControllerBase
         _paymentsValidator = paymentsValidator;
         _appendValidator = appendValidator;
         _sessionValidator = sessionValidator;
+        _correctionValidator = correctionValidator;
     }
 
     [HttpGet]
@@ -63,6 +66,35 @@ public class OrdersController : CafeApiControllerBase
         return Ok(new ApiResponse<IReadOnlyList<OrderDto>>(true, data));
     }
 
+    /// <summary>Closed orders (delivered/cancelled) of one Iran-calendar day — the
+    /// browsing surface for اصلاح سند payment corrections.</summary>
+    [HttpGet("closed")]
+    public async Task<IActionResult> GetClosedOrders(
+        string cafeId,
+        ITenantContext tenant,
+        CancellationToken cancellationToken,
+        [FromQuery] string? date = null,
+        [FromQuery] string? branchId = null,
+        [FromQuery] int page = 1,
+        [FromQuery] int pageSize = 30)
+    {
+        if (EnsureCafeAccess(cafeId, tenant) is { } denied) return denied;
+        if (EnsureBranchAccess(branchId, tenant) is { } branchDenied) return branchDenied;
+
+        DateOnly day;
+        if (string.IsNullOrWhiteSpace(date)) day = IranCalendar.TodayInIran;
+        else if (!DateOnly.TryParse(date, out day))
+            return BadRequest(new ApiResponse<object>(
+                false, null, new ApiError("VALIDATION_ERROR", "Invalid date (expected YYYY-MM-DD).", "date")));
+
+        if (page < 1) page = 1;
+        if (pageSize is < 1 or > 100) pageSize = 30;
+
+        var (items, total) = await _orderService.GetClosedOrdersAsync(
+            cafeId, day, branchId, page, pageSize, cancellationToken);
+        return Ok(new PagedApiResponse<OrderDto>(true, items, new PagedMeta(total, page, pageSize)));
+    }
+
     [HttpGet("live")]
     public async Task<IActionResult> GetLiveOrders(string cafeId, ITenantContext tenant, CancellationToken cancellationToken)
     {
@@ -273,6 +305,56 @@ public class OrdersController : CafeApiControllerBase
         return Ok(new ApiResponse<IReadOnlyList<PaymentDto>>(true, result.Data));
     }
 
+    /// <summary>
+    /// اصلاح سند — void wrongly-recorded payments and/or record replacements on a
+    /// closed order, atomically, with a mandatory reason. Manager/Owner only;
+    /// the full before/after is written to the immutable audit trail.
+    /// </summary>
+    [HttpPost("{id}/payments/corrections")]
+    public async Task<IActionResult> CorrectPayments(
+        string cafeId,
+        string id,
+        [FromBody] CorrectPaymentsRequest request,
+        ITenantContext tenant,
+        CancellationToken cancellationToken)
+    {
+        if (EnsureCafeAccess(cafeId, tenant) is { } denied) return denied;
+        if (EnsureManager(tenant) is { } forbidden) return forbidden;
+        var validation = await _correctionValidator.ValidateAsync(request, cancellationToken);
+        if (!validation.IsValid) return BadRequest(ValidationError(validation));
+
+        // Snapshot the payments before the change so the audit row carries a
+        // complete before/after picture even after later corrections.
+        var before = await _orderService.GetOrderAsync(cafeId, id, cancellationToken);
+
+        var result = await _orderService.CorrectPaymentsAsync(
+            cafeId, id, request, tenant.UserId, cancellationToken);
+        if (!result.Success) return OrderError(result.ErrorCode!, result.Field);
+
+        await _audit.LogAsync(new AuditEntry
+        {
+            Category = "Payment",
+            Action = "PaymentCorrected",
+            EntityType = "Order",
+            EntityId = id,
+            Summary = $"اصلاح سند: voided {request.VoidPaymentIds.Count} payment(s), " +
+                      $"recorded {request.Replacements.Count} replacement(s) — {request.Reason}",
+            Details = new
+            {
+                orderId = id,
+                displayNumber = result.Data!.DisplayNumber,
+                reason = request.Reason,
+                voidedPaymentIds = request.VoidPaymentIds,
+                paymentsBefore = before?.Payments.Select(p => new { p.Id, p.Method, p.Amount, p.Status }),
+                paymentsAfter = result.Data.Payments.Select(p => new { p.Id, p.Method, p.Amount, p.Status }),
+                paidAmountAfter = result.Data.PaidAmount,
+                orderTotal = result.Data.Total
+            }
+        }, cancellationToken);
+
+        return Ok(new ApiResponse<OrderDto>(true, result.Data));
+    }
+
     private IActionResult OrderError(string code, string? field = null) =>
         code switch
         {
@@ -300,6 +382,10 @@ public class OrdersController : CafeApiControllerBase
                 false, null, new ApiError(code, "Table is being cleaned.", field))),
             "NO_OPEN_SHIFT" => BadRequest(new ApiResponse<object>(
                 false, null, new ApiError(code, "Open the cash register shift before taking payment.", field))),
+            "PAYMENT_NOT_FOUND" => NotFound(new ApiResponse<object>(
+                false, null, new ApiError(code, "Payment not found on this order.", field))),
+            "PAYMENT_ALREADY_REFUNDED" => BadRequest(new ApiResponse<object>(
+                false, null, new ApiError(code, "Payment is already refunded.", field))),
             _ => BadRequest(new ApiResponse<object>(
                 false, null, new ApiError(code, "Invalid order request.", field)))
         };

src/Meezi.API/Models/Orders/OrderDtos.cs

@@ -70,6 +70,17 @@ public record RecordPaymentsRequest(
     IReadOnlyList<CreatePaymentRequest> Payments,
     int? LoyaltyPointsToRedeem = null);
 
+/// <summary>
+/// اصلاح سند — amend the payments of an order after the fact (wrong method,
+/// wrong amount, or payment recorded on the wrong order). Voids the listed
+/// payments (marked Refunded, never deleted) and records the replacements in
+/// one atomic operation. A reason is mandatory; the whole change is audit-logged.
+/// </summary>
+public record CorrectPaymentsRequest(
+    IReadOnlyList<string> VoidPaymentIds,
+    IReadOnlyList<CreatePaymentRequest> Replacements,
+    string Reason);
+
 public record PaymentDto(string Id, PaymentMethod Method, decimal Amount, PaymentStatus Status, string? Reference);
 
 public record LiveOrderDto(

src/Meezi.API/Services/OrderService.cs

@@ -67,6 +67,19 @@ public interface IOrderService
         RecordPaymentsRequest request,
         string? userId,
         CancellationToken cancellationToken = default);
+    Task<(IReadOnlyList<OrderDto> Items, int Total)> GetClosedOrdersAsync(
+        string cafeId,
+        DateOnly date,
+        string? branchId,
+        int page,
+        int pageSize,
+        CancellationToken cancellationToken = default);
+    Task<OrderServiceResult<OrderDto>> CorrectPaymentsAsync(
+        string cafeId,
+        string orderId,
+        CorrectPaymentsRequest request,
+        string? userId,
+        CancellationToken cancellationToken = default);
 }
 
 public class OrderService : IOrderService
@@ -1119,6 +1132,117 @@ public class OrderService : IOrderService
         return new OrderServiceResult<IReadOnlyList<PaymentDto>>(true, dtos);
     }
 
+    public async Task<(IReadOnlyList<OrderDto> Items, int Total)> GetClosedOrdersAsync(
+        string cafeId,
+        DateOnly date,
+        string? branchId,
+        int page,
+        int pageSize,
+        CancellationToken cancellationToken = default)
+    {
+        var (utcStart, utcEnd) = IranCalendar.GetUtcRangeForIranDay(date);
+
+        var query = _db.Orders
+            .Where(o => o.CafeId == cafeId
+                        && (o.Status == OrderStatus.Delivered || o.Status == OrderStatus.Cancelled)
+                        && o.CreatedAt >= utcStart
+                        && o.CreatedAt < utcEnd);
+
+        if (!string.IsNullOrEmpty(branchId))
+            query = query.Where(o => o.BranchId == branchId);
+
+        var total = await query.CountAsync(cancellationToken);
+
+        var orders = await ApplyOrderIncludes(query)
+            .OrderByDescending(o => o.CreatedAt)
+            .Skip((page - 1) * pageSize)
+            .Take(pageSize)
+            .AsNoTracking()
+            .ToListAsync(cancellationToken);
+
+        return (orders.Select(MapOrder).ToList(), total);
+    }
+
+    public async Task<OrderServiceResult<OrderDto>> CorrectPaymentsAsync(
+        string cafeId,
+        string orderId,
+        CorrectPaymentsRequest request,
+        string? userId,
+        CancellationToken cancellationToken = default)
+    {
+        var order = await LoadOrderAsync(cafeId, orderId, cancellationToken);
+        if (order is null)
+            return new OrderServiceResult<OrderDto>(false, null, "ORDER_NOT_FOUND");
+
+        // Resolve the payments being voided — they must belong to this order and
+        // still be live. Payments are never deleted; voiding marks them Refunded
+        // so the original سند stays visible in history and audit.
+        var toVoid = new List<Payment>();
+        foreach (var paymentId in request.VoidPaymentIds.Distinct())
+        {
+            var payment = order.Payments.FirstOrDefault(p => p.Id == paymentId);
+            if (payment is null)
+                return new OrderServiceResult<OrderDto>(false, null, "PAYMENT_NOT_FOUND", "voidPaymentIds");
+            if (payment.Status != PaymentStatus.Completed)
+                return new OrderServiceResult<OrderDto>(false, null, "PAYMENT_ALREADY_REFUNDED", "voidPaymentIds");
+            toVoid.Add(payment);
+        }
+
+        var branchId = await ResolveOrderBranchIdAsync(order, cafeId, cancellationToken);
+        if (string.IsNullOrEmpty(branchId))
+            return new OrderServiceResult<OrderDto>(false, null, "NO_OPEN_SHIFT", "branchId");
+
+        // Corrections move money through the drawer, so they need an open shift
+        // exactly like recording a payment does.
+        var shiftCheck = await _shiftService.RequireOpenShiftForBranchAsync(cafeId, branchId, cancellationToken);
+        if (!shiftCheck.Success)
+            return new OrderServiceResult<OrderDto>(false, null, shiftCheck.ErrorCode, shiftCheck.Field);
+        var openShift = shiftCheck.Data!;
+
+        foreach (var payment in toVoid)
+            payment.Status = PaymentStatus.Refunded;
+
+        var replacements = request.Replacements.Select(p => new Payment
+        {
+            OrderId = orderId,
+            Method = p.Method,
+            Amount = p.Amount,
+            Reference = p.Reference,
+            Status = PaymentStatus.Completed
+        }).ToList();
+        _db.Payments.AddRange(replacements);
+
+        // Fully paid again after the correction → ensure the order is closed;
+        // underpaid → leave the status alone (the remainder can be collected
+        // through the normal payment flow later). EF navigation fixup may have
+        // already appended the replacements to order.Payments, so exclude them
+        // by reference to avoid double-counting.
+        var paidTotal = order.Payments
+                            .Where(p => p.Status == PaymentStatus.Completed && !replacements.Contains(p))
+                            .Sum(p => p.Amount)
+                        + replacements.Sum(p => p.Amount);
+        if (paidTotal >= order.Total && OpenForPaymentStatuses.Contains(order.Status))
+            order.Status = OrderStatus.Delivered;
+
+        await _db.SaveChangesAsync(cancellationToken);
+
+        var createdBy = userId ?? openShift.OpenedByUserId;
+        foreach (var payment in toVoid)
+        {
+            await _shiftService.RecordTransactionAsync(
+                cafeId, openShift.Id, CashTransactionType.Refund, payment.Method,
+                payment.Amount, createdBy, orderId, request.Reason, cancellationToken);
+        }
+        foreach (var payment in replacements)
+        {
+            await _shiftService.RecordTransactionAsync(
+                cafeId, openShift.Id, CashTransactionType.OrderPayment, payment.Method,
+                payment.Amount, createdBy, orderId, request.Reason, cancellationToken);
+        }
+
+        return new OrderServiceResult<OrderDto>(true, MapOrder(order));
+    }
+
     private static IQueryable<Order> ApplyOrderIncludes(IQueryable<Order> query) =>
         query
             .Include(o => o.Items)

src/Meezi.API/Services/ShiftService.cs

@@ -228,11 +228,16 @@ public class ShiftService : IShiftService
             .Where(t => t.Type == CashTransactionType.OrderPayment && t.Method == PaymentMethod.Cash)
             .Sum(t => t.Amount);
 
+        // Payment corrections (اصلاح سند) refund cash back out of the drawer.
+        var cashRefunds = transactions
+            .Where(t => t.Type == CashTransactionType.Refund && t.Method == PaymentMethod.Cash)
+            .Sum(t => t.Amount);
+
         var withdrawals = transactions
             .Where(t => t.Type == CashTransactionType.Withdrawal)
             .Sum(t => t.Amount);
 
-        return openingCash + cashPayments - withdrawals;
+        return openingCash + cashPayments - cashRefunds - withdrawals;
     }
 
     private static ShiftDto ToDto(Shift s) => new(

src/Meezi.API/Validators/PosValidators.cs

@@ -139,6 +139,22 @@ public class RecordPaymentsRequestValidator : AbstractValidator<RecordPaymentsRe
     }
 }
 
+public class CorrectPaymentsRequestValidator : AbstractValidator<CorrectPaymentsRequest>
+{
+    public CorrectPaymentsRequestValidator()
+    {
+        RuleFor(x => x.Reason).NotEmpty().MinimumLength(3).MaximumLength(500);
+        RuleFor(x => x)
+            .Must(x => (x.VoidPaymentIds?.Count ?? 0) > 0 || (x.Replacements?.Count ?? 0) > 0)
+            .WithMessage("At least one payment to void or one replacement is required.");
+        RuleForEach(x => x.Replacements).ChildRules(p =>
+        {
+            p.RuleFor(x => x.Method).IsInEnum();
+            p.RuleFor(x => x.Amount).GreaterThan(0);
+        });
+    }
+}
+
 public class AppendOrderItemsRequestValidator : AbstractValidator<AppendOrderItemsRequest>
 {
     public AppendOrderItemsRequestValidator()