feat(sale): implement modifications filtering and validation for admin sales

app/Domains/Forms/Services/SaleFormService.php

@@ -6,27 +6,18 @@ use App\Domains\Purchase\Models\Purchase;
 
 class SaleFormService
 {
-    /** @return array{statuses: list<array{code: string, name: string}>} */
+    /** @return array{statuses: list<array{value: string, label: string, real_statuses: list<string>}>} */
     public function get(): array
     {
-        $names = [
-            Purchase::STATUS_CREATED => 'Creada',
-            Purchase::STATUS_PENDING_PAYMENT => 'Esperando pago',
-            Purchase::STATUS_IN_REVIEW => 'En revisión',
-            Purchase::STATUS_PAID => 'Confirmada',
-            Purchase::STATUS_CANCELLED => 'Cancelada',
-            Purchase::STATUS_REJECTED => 'Rechazada',
-            Purchase::STATUS_EXPIRED => 'Vencida',
-            Purchase::STATUS_SUPERSEDED => 'Reemplazada',
-        ];
-
         return [
             'statuses' => array_map(
-                fn (string $status): array => [
+                fn (string $code, array $definition): array => [
-                    'code' => $status,
+                    'value' => $code,
-                    'name' => $names[$status],
+                    'label' => $definition['name'],
+                    'real_statuses' => $definition['statuses'],
                 ],
-                Purchase::statuses(),
+                array_keys(Purchase::adminStatuses()),
+                array_values(Purchase::adminStatuses()),
             ),
         ];
     }

app/Domains/Purchase/Models/Purchase.php

@@ -52,6 +52,14 @@ class Purchase extends Model
 
     public const STATUS_SUPERSEDED = 'superseded';
 
+    public const ADMIN_STATUS_INCOMPLETE = 'incomplete';
+
+    public const ADMIN_STATUS_AWAITING_PAYMENT = 'awaiting_payment';
+
+    public const ADMIN_STATUS_CONFIRMED = 'confirmed';
+
+    public const ADMIN_STATUS_CANCELLED = 'cancelled';
+
     /** @return list<string> */
     public static function statuses(): array
     {
@@ -67,6 +75,68 @@ class Purchase extends Model
         ];
     }
 
+    /**
+     * @return array<string, array{name: string, statuses: list<string>}>
+     */
+    public static function adminStatuses(): array
+    {
+        return [
+            self::ADMIN_STATUS_INCOMPLETE => [
+                'name' => 'Por completar datos',
+                'statuses' => [self::STATUS_CREATED],
+            ],
+            self::ADMIN_STATUS_AWAITING_PAYMENT => [
+                'name' => 'Esperando pago',
+                'statuses' => [self::STATUS_PENDING_PAYMENT, self::STATUS_IN_REVIEW],
+            ],
+            self::ADMIN_STATUS_CONFIRMED => [
+                'name' => 'Confirmado',
+                'statuses' => [self::STATUS_PAID],
+            ],
+            self::ADMIN_STATUS_CANCELLED => [
+                'name' => 'Anulado',
+                'statuses' => [
+                    self::STATUS_CANCELLED,
+                    self::STATUS_REJECTED,
+                    self::STATUS_EXPIRED,
+                    self::STATUS_SUPERSEDED,
+                ],
+            ],
+        ];
+    }
+
+    /** @return list<string> */
+    public static function adminStatusCodes(): array
+    {
+        return array_keys(self::adminStatuses());
+    }
+
+    /** @return list<string> */
+    public static function realStatusesForAdminStatus(string $adminStatus): array
+    {
+        return self::adminStatuses()[$adminStatus]['statuses'] ?? [];
+    }
+
+    public static function adminStatusFor(string $realStatus): ?string
+    {
+        foreach (self::adminStatuses() as $adminStatus => $definition) {
+            if (in_array($realStatus, $definition['statuses'], true)) {
+                return $adminStatus;
+            }
+        }
+
+        return null;
+    }
+
+    public static function adminStatusNameFor(string $realStatus): ?string
+    {
+        $adminStatus = self::adminStatusFor($realStatus);
+
+        return $adminStatus === null
+            ? null
+            : self::adminStatuses()[$adminStatus]['name'];
+    }
+
     protected $table = 'compras';
 
     /** @var array<int, string> */

app/Domains/Purchase/Services/Checkout/ReleaseCheckoutService.php

@@ -43,6 +43,11 @@ class ReleaseCheckoutService
         ): Purchase {
             $purchase = $this->lockPurchase($purchase);
 
+            if ($purchase->status === Purchase::STATUS_EXPIRED
+                && $targetStatus === Purchase::STATUS_CANCELLED) {
+                return $this->loadPurchase($purchase);
+            }
+
             if ($purchase->status === Purchase::STATUS_EXPIRED
                 && $targetStatus !== Purchase::STATUS_EXPIRED) {
                 throw new PurchaseExpiredException;
@@ -72,6 +77,14 @@ class ReleaseCheckoutService
 
             $cart = $purchase->cart()->withTrashed()->lockForUpdate()->first();
 
+            // Leaving checkout is allowed at the exact instant the reservation
+            // expires. Finish the expiration while holding the purchase lock so
+            // the request is idempotent with the scheduled expiration job.
+            if ($targetStatus === Purchase::STATUS_CANCELLED
+                && $this->hasOverdueActiveReservation($purchase)) {
+                $targetStatus = Purchase::STATUS_EXPIRED;
+            }
+
             if ($targetStatus === Purchase::STATUS_CANCELLED
                 && $cart?->status === 'active'
                 && in_array($purchase->status, [

app/Domains/Sale/Controllers/AdminApp/SaleController.php

@@ -3,6 +3,7 @@
 namespace App\Domains\Sale\Controllers\AdminApp;
 
 use App\Domains\Sale\Requests\AdminAppSaleIndexRequest;
+use App\Domains\Sale\Requests\AdminAppSaleModificationIndexRequest;
 use App\Domains\Sale\Requests\AdminAppSaleModificationPdfRequest;
 use App\Domains\Sale\Requests\AdminAppSalePdfRequest;
 use App\Domains\Sale\Resources\AdminApp\SaleDetailResource;
@@ -67,11 +68,13 @@ class SaleController extends Controller
         return new SaleResource($this->saleService->cancel($tenant, $sale));
     }
 
-    public function modifications(Request $request): AnonymousResourceCollection
+    public function modifications(
-    {
+        AdminAppSaleModificationIndexRequest $request,
+    ): AnonymousResourceCollection {
         return SaleModificationResource::collection(
             $this->saleService->modifications(
-                $request->user()->tenant()->firstOrFail()
+                $request->user()->tenant()->firstOrFail(),
+                $request->validated(),
             )
         );
     }
@@ -93,7 +96,7 @@ class SaleController extends Controller
 
         return $this->salePdfService->downloadModifications(
             $tenant,
-            $this->saleService->modificationsForExport($tenant),
+            $this->saleService->modificationsForExport($tenant, $request->validated()),
             $request->validated('timezone'),
         );
     }
@@ -116,7 +119,7 @@ class SaleController extends Controller
 
         return $this->saleExcelService->downloadModifications(
             $tenant,
-            $this->saleService->modificationsForExport($tenant),
+            $this->saleService->modificationsForExport($tenant, $request->validated()),
             $request->validated('timezone'),
         );
     }

app/Domains/Sale/Requests/AdminAppSaleIndexRequest.php

@@ -20,7 +20,7 @@ class AdminAppSaleIndexRequest extends FormRequest
             'q' => ['sometimes', 'nullable', 'string', 'max:255'],
             'id' => ['sometimes', 'nullable', 'integer', 'min:1'],
             'sale_date' => ['sometimes', 'nullable', 'date_format:Y-m-d'],
-            'status' => ['sometimes', 'nullable', 'string', Rule::in(Purchase::statuses())],
+            'status' => ['sometimes', 'nullable', 'string', Rule::in(Purchase::adminStatusCodes())],
             'sort_by' => ['sometimes', 'string', 'in:id,date,customer_name,quantity,status,total'],
             'sort_direction' => ['sometimes', 'string', 'in:asc,desc'],
             'page' => ['sometimes', 'integer', 'min:1'],

app/Domains/Sale/Requests/AdminAppSaleModificationIndexRequest.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace App\Domains\Sale\Requests;
+
+class AdminAppSaleModificationIndexRequest extends AdminAppSaleIndexRequest
+{
+    /** @return array<string, list<string>> */
+    public function rules(): array
+    {
+        $rules = parent::rules();
+
+        unset($rules['sort_by'], $rules['sort_direction']);
+
+        return $rules;
+    }
+}

app/Domains/Sale/Requests/AdminAppSaleModificationPdfRequest.php

@@ -3,19 +3,14 @@
 namespace App\Domains\Sale\Requests;
 
 use App\Domains\Shared\Rules\ValidTimezone;
-use Illuminate\Foundation\Http\FormRequest;
 
-class AdminAppSaleModificationPdfRequest extends FormRequest
+class AdminAppSaleModificationPdfRequest extends AdminAppSaleModificationIndexRequest
 {
-    public function authorize(): bool
-    {
-        return true;
-    }
-
     /** @return array<string, list<string>> */
     public function rules(): array
     {
         return [
+            ...parent::rules(),
             'timezone' => ['required', 'string', new ValidTimezone],
         ];
     }

app/Domains/Sale/Resources/AdminApp/SaleModificationResource.php

@@ -23,6 +23,12 @@ class SaleModificationResource extends JsonResource
             'attribute' => $this->attribute,
             'old_value' => $this->old_value,
             'new_value' => $this->new_value,
+            'admin_status' => is_string($this->new_value)
+                ? Purchase::adminStatusFor($this->new_value)
+                : null,
+            'status_label' => is_string($this->new_value)
+                ? Purchase::adminStatusNameFor($this->new_value)
+                : null,
             'changed_at' => $this->changed_at->utc()->toIso8601String(),
             'date' => $this->changed_at->format('Y-m-d'),
             'time' => $this->changed_at->format('H:i:s'),
@@ -31,6 +37,8 @@ class SaleModificationResource extends JsonResource
                 'id' => $sale->id,
                 'customer_name' => $sale->nombre_apellido,
                 'status' => $sale->status,
+                'admin_status' => Purchase::adminStatusFor($sale->status),
+                'status_label' => Purchase::adminStatusNameFor($sale->status),
             ] : null,
             'modified_by' => $user ? [
                 'id' => $user->id,

app/Domains/Sale/Resources/AdminApp/SaleResource.php

@@ -20,6 +20,8 @@ class SaleResource extends JsonResource
             'customer_name' => $this->nombre_apellido,
             'quantity' => (int) ($this->quantity ?? 0),
             'status' => $this->status,
+            'admin_status' => Purchase::adminStatusFor($this->status),
+            'status_label' => Purchase::adminStatusNameFor($this->status),
             'total' => number_format((float) $this->total, 2, '.', ''),
             'tickets_count' => $ticketsCount,
             'has_generated_tickets' => $ticketsCount > 0,

app/Domains/Sale/Services/AdminAppSaleExcelService.php

@@ -201,11 +201,6 @@ class AdminAppSaleExcelService
 
     private function saleStatus(string $status): string
     {
-        return match ($status) {
+        return Purchase::adminStatusNameFor($status) ?? $status;
-            Purchase::STATUS_PAID => 'Confirmado',
-            Purchase::STATUS_CREATED => 'Por completar datos',
-            Purchase::STATUS_PENDING_PAYMENT, Purchase::STATUS_IN_REVIEW => 'Esperando pago',
-            default => 'Anulado',
-        };
     }
 }

app/Domains/Sale/Services/AdminAppSaleService.php

@@ -92,18 +92,24 @@ class AdminAppSaleService
         return $this->salesQuery($tenant, $filters)->get();
     }
 
-    /** @return LengthAwarePaginator<ValueChange> */
+    /**
-    public function modifications(Tenant $tenant): LengthAwarePaginator
+     * @param  array<string, mixed>  $filters
+     * @return LengthAwarePaginator<ValueChange>
+     */
+    public function modifications(Tenant $tenant, array $filters = []): LengthAwarePaginator
     {
-        return $this->modificationsQuery($tenant)
+        return $this->modificationsQuery($tenant, $filters)
             ->paginateFromRequest()
             ->withQueryString();
     }
 
-    /** @return Collection<int, ValueChange> */
+    /**
-    public function modificationsForExport(Tenant $tenant): Collection
+     * @param  array<string, mixed>  $filters
+     * @return Collection<int, ValueChange>
+     */
+    public function modificationsForExport(Tenant $tenant, array $filters = []): Collection
     {
-        return $this->modificationsQuery($tenant)->get();
+        return $this->modificationsQuery($tenant, $filters)->get();
     }
 
     /** @param array<string, mixed> $filters */
@@ -126,7 +132,6 @@ class AdminAppSaleService
 
         return Purchase::query()
             ->where('tenant_codigo', $tenant->codigo)
-            ->where('status', '!=', Purchase::STATUS_SUPERSEDED)
             ->when($filters['q'] ?? null, function (Builder $query, string $search): void {
                 $term = trim($search);
 
@@ -144,12 +149,10 @@ class AdminAppSaleService
             )
             ->when(
                 $filters['status'] ?? null,
-                fn (Builder $query, string $status): Builder => $status === Purchase::STATUS_PENDING_PAYMENT
+                fn (Builder $query, string $status): Builder => $query->whereIn(
-                    ? $query->whereIn('status', [
+                    'status',
-                        Purchase::STATUS_PENDING_PAYMENT,
+                    Purchase::realStatusesForAdminStatus($status),
-                        Purchase::STATUS_IN_REVIEW,
+                )
-                    ])
-                    : $query->where('status', $status)
             )
             ->select('compras.*')
             ->selectRaw(
@@ -162,12 +165,50 @@ class AdminAppSaleService
             ->when($sortBy !== 'id', fn (Builder $query): Builder => $query->orderByDesc('id'));
     }
 
-    /** @return Builder<ValueChange> */
+    /**
-    protected function modificationsQuery(Tenant $tenant): Builder
+     * @param  array<string, mixed>  $filters
+     * @return Builder<ValueChange>
+     */
+    protected function modificationsQuery(Tenant $tenant, array $filters): Builder
     {
         return ValueChange::query()
             ->where('tenant_code', $tenant->codigo)
             ->where('trackable_type', (new Purchase)->getMorphClass())
+            ->when($filters['q'] ?? null, function (Builder $query, string $search): void {
+                $term = trim($search);
+
+                $query->where(function (Builder $query) use ($term): void {
+                    $query
+                        ->where('trackable_id', 'like', "%{$term}%")
+                        ->orWhereHasMorph(
+                            'trackable',
+                            [Purchase::class],
+                            function (Builder $sales) use ($term): void {
+                                $sales
+                                    ->where('nombre_apellido', 'like', "%{$term}%")
+                                    ->orWhere('created_at', 'like', "%{$term}%");
+                            },
+                        );
+                });
+            })
+            ->when(
+                $filters['id'] ?? null,
+                fn (Builder $query, int $id): Builder => $query->where('trackable_id', $id)
+            )
+            ->when(
+                $filters['sale_date'] ?? null,
+                fn (Builder $query, string $date): Builder => $query->whereHasMorph(
+                    'trackable',
+                    [Purchase::class],
+                    fn (Builder $sales): Builder => $sales->whereDate('created_at', $date),
+                )
+            )
+            ->when(
+                $filters['status'] ?? null,
+                fn (Builder $query, string $status): Builder => $query
+                    ->where('attribute', 'status')
+                    ->whereIn('new_value', Purchase::realStatusesForAdminStatus($status))
+            )
             ->with(['trackable', 'user'])
             ->orderByDesc('changed_at')
             ->orderByDesc('id');

app/Domains/Sale/documentacion/README.md

@@ -9,7 +9,8 @@ Provee consultas administrativas y exportaciones de ventas confirmadas, además
 - `AdminAppSaleService`: pagina ventas, calcula totales y obtiene colecciones para exportación; también consulta modificaciones.
 - `AdminAppSalePdfService`: genera descargas PDF de ventas y de cambios.
 - `AdminAppSaleExcelService`: genera descargas Excel de ventas y de cambios.
-- `AdminAppSaleIndexRequest`: valida filtros del listado y la exportación.
+- `AdminAppSaleIndexRequest`: valida filtros del listado y la exportación de ventas.
+- `AdminAppSaleModificationIndexRequest`: valida los filtros compartidos por el historial y sus exportaciones.
 - `SaleResource` y `SaleModificationResource`: representan ventas e historial para AdminApp.
 - `SaleController`: entrada HTTP del panel.
 
@@ -27,3 +28,5 @@ Consume compras de `Purchase`, datos del tenant y entradas de `Logging`. No es d
 ## Consideraciones
 
 La consulta paginada y la colección de exportación deben aplicar los mismos filtros para evitar diferencias entre pantalla, PDF y Excel.
+
+El historial comparte con ventas los filtros de búsqueda, ID, fecha de venta y estado. En el historial, el estado se evalúa sobre `ValueChange.new_value`: representa el resultado de esa modificación y no el estado actual de la venta.

resources/views/pdf/adminapp/sales.blade.php

@@ -47,11 +47,7 @@
                     <td>{{ $sale->created_at?->copy()->timezone($timeZone)->format('d/m/Y H:i') ?? '-' }}</td>
                     <td>{{ $sale->nombre_apellido ?: 'Sin nombre' }}</td>
                     <td class="center">{{ (int) ($sale->quantity ?? 0) }}</td>
-                    <td>{{ match ($sale->status) {
+                    <td>{{ \App\Domains\Purchase\Models\Purchase::adminStatusNameFor($sale->status) ?? $sale->status }}</td>
-                        'paid' => 'Confirmado',
-                        'created', 'pending_payment' => 'Esperando pago',
-                        default => 'Anulado',
-                    } }}</td>
                     <td class="number">${{ number_format((float) $sale->total, 2, ',', '.') }}</td>
                     <td class="center">{{ (int) ($sale->tickets_count ?? 0) }}</td>
                 </tr>

tests/Feature/Forms/AdminAppSaleFormControllerTest.php

@@ -2,6 +2,8 @@
 
 namespace Tests\Feature\Forms;
 
+use App\Domains\Attachable\Enums\AttachmentType;
+use App\Domains\Attachable\Models\Attachment;
 use App\Domains\Auth\Models\User;
 use App\Domains\Authorization\Enums\RoleCode;
 use App\Domains\Purchase\Models\Purchase;
@@ -34,12 +36,7 @@ class AdminAppSaleFormControllerTest extends TestCase
 
     public function test_an_adminapp_user_can_get_the_sale_form(): void
     {
-        $tenant = Tenant::query()->create([
+        $tenant = $this->createTenant('acme');
-            'codigo' => 'acme',
-            'nombre' => 'Acme',
-            'dominio' => 'acme.test',
-            'website_type_code' => 'onticket',
-        ]);
         Sanctum::actingAs(User::factory()->create([
             'rol_codigo' => RoleCode::AdminApp->value,
             'tenant_codigo' => $tenant->codigo,
@@ -47,13 +44,15 @@ class AdminAppSaleFormControllerTest extends TestCase
 
         $this->getJson('/api/v1/adminapp/forms/sale')
             ->assertOk()
-            ->assertJsonCount(count(Purchase::statuses()), 'data.statuses')
+            ->assertJsonCount(count(Purchase::adminStatusCodes()), 'data.statuses')
-            ->assertJsonPath('data.statuses.0.code', Purchase::STATUS_CREATED)
+            ->assertJsonPath('data.statuses.0.value', Purchase::ADMIN_STATUS_INCOMPLETE)
-            ->assertJsonPath('data.statuses.0.name', 'Creada')
+            ->assertJsonPath('data.statuses.0.label', 'Por completar datos')
-            ->assertJsonPath('data.statuses.1.code', Purchase::STATUS_PENDING_PAYMENT)
+            ->assertJsonPath('data.statuses.0.real_statuses.0', Purchase::STATUS_CREATED)
-            ->assertJsonPath('data.statuses.2.code', Purchase::STATUS_IN_REVIEW)
+            ->assertJsonPath('data.statuses.1.value', Purchase::ADMIN_STATUS_AWAITING_PAYMENT)
-            ->assertJsonPath('data.statuses.3.code', Purchase::STATUS_PAID)
+            ->assertJsonPath('data.statuses.1.real_statuses.0', Purchase::STATUS_PENDING_PAYMENT)
-            ->assertJsonPath('data.statuses.6.code', Purchase::STATUS_EXPIRED);
+            ->assertJsonPath('data.statuses.1.real_statuses.1', Purchase::STATUS_IN_REVIEW)
+            ->assertJsonPath('data.statuses.2.value', Purchase::ADMIN_STATUS_CONFIRMED)
+            ->assertJsonPath('data.statuses.3.value', Purchase::ADMIN_STATUS_CANCELLED);
     }
 
     public function test_a_customer_cannot_get_the_sale_form(): void
@@ -65,4 +64,34 @@ class AdminAppSaleFormControllerTest extends TestCase
 
         $this->getJson('/api/v1/adminapp/forms/sale')->assertForbidden();
     }
+
+    private function createTenant(string $code): Tenant
+    {
+        $headerLogo = $this->createAttachment("{$code}-header");
+        $footerLogo = $this->createAttachment("{$code}-footer");
+
+        return Tenant::query()->create([
+            'codigo' => $code,
+            'nombre' => ucfirst($code),
+            'dominio' => "{$code}.test",
+            'primary_color' => '#000000',
+            'secondary_color' => '#ffffff',
+            'danger_color' => '#dc3545',
+            'header_bg_color' => '#ffffff',
+            'footer_bg_color' => '#000000',
+            'header_logo_id' => $headerLogo->id,
+            'footer_logo_id' => $footerLogo->id,
+            'website_type_code' => 'onticket',
+        ]);
+    }
+
+    private function createAttachment(string $name): Attachment
+    {
+        return Attachment::query()->create([
+            'path' => "test/{$name}.png",
+            'filename' => "{$name}.png",
+            'type' => AttachmentType::Image,
+            'mime_type' => 'image/png',
+        ]);
+    }
 }

tests/Feature/Purchase/StorePurchaseTest.php

@@ -10,6 +10,7 @@ use App\Domains\Catalog\Enums\InventoryPolicy;
 use App\Domains\Catalog\Models\CatalogItem;
 use App\Domains\Catalog\Models\Category;
 use App\Domains\Catalog\Models\Inventory;
+use App\Domains\Catalog\Models\StockReservation;
 use App\Domains\Catalog\Models\Variant;
 use App\Domains\Purchase\Models\Purchase;
 use App\Domains\Purchase\Services\CheckoutService;
@@ -714,11 +715,11 @@ class StorePurchaseTest extends TestCase
 
         $this->actingAs($user, 'sanctum')
             ->postJson("/api/tenants/sonder/compras/{$purchase->id}/cancel")
-            ->assertUnprocessable()
+            ->assertOk()
-            ->assertJsonPath('code', 'purchase.expired');
+            ->assertJsonPath('data.status', Purchase::STATUS_EXPIRED);
     }
 
-    public function test_an_overdue_purchase_cannot_be_cancelled_before_the_expiration_job_runs(): void
+    public function test_leaving_an_overdue_purchase_expires_it_before_the_expiration_job_runs(): void
     {
         $this->createTenant('sonder', 'Sonder', 'sonder.com.ar');
         $user = User::factory()->create();
@@ -728,20 +729,17 @@ class StorePurchaseTest extends TestCase
 
         $this->actingAs($user, 'sanctum')
             ->postJson("/api/tenants/sonder/compras/{$purchase->id}/cancel")
-            ->assertUnprocessable()
+            ->assertOk()
-            ->assertExactJson([
+            ->assertJsonPath('data.status', Purchase::STATUS_EXPIRED);
-                'code' => 'stock_reservation.expired',
-                'message' => __('api.cart.reservation_expired'),
-            ]);
 
         $this->assertDatabaseHas('compras', [
             'id' => $purchase->id,
-            'status' => Purchase::STATUS_CREATED,
+            'status' => Purchase::STATUS_EXPIRED,
             'stock_reservation_id' => $purchase->stock_reservation_id,
         ]);
         $this->assertDatabaseHas('stock_reservations', [
             'id' => $purchase->stock_reservation_id,
-            'status' => 'active',
+            'status' => StockReservation::STATUS_EXPIRED,
         ]);
     }
 

tests/Feature/Sale/AdminAppSaleControllerTest.php

@@ -2,6 +2,8 @@
 
 namespace Tests\Feature\Sale;
 
+use App\Domains\Attachable\Enums\AttachmentType;
+use App\Domains\Attachable\Models\Attachment;
 use App\Domains\Auth\Models\User;
 use App\Domains\Authorization\Enums\RoleCode;
 use App\Domains\Cart\Models\Cart;
@@ -9,6 +11,8 @@ use App\Domains\Cart\Models\CartItem;
 use App\Domains\Catalog\Models\CatalogItem;
 use App\Domains\Catalog\Models\Inventory;
 use App\Domains\Catalog\Models\Variant;
+use App\Domains\Logging\Enums\ValueChangeActorType;
+use App\Domains\Logging\Models\ValueChange;
 use App\Domains\Purchase\Events\PurchasePaid;
 use App\Domains\Purchase\Models\Purchase;
 use App\Domains\Purchase\Models\PurchaseItem;
@@ -34,6 +38,96 @@ class AdminAppSaleControllerTest extends TestCase
         WebsiteType::query()->create(['codigo' => 'onticket', 'nombre' => 'OnTicket']);
     }
 
+    public function test_sale_modifications_use_sale_filters_and_resulting_status(): void
+    {
+        $tenant = $this->createTenant('acme');
+        $otherTenant = $this->createTenant('other');
+        $admin = $this->createAdminAppUser($tenant);
+        Sanctum::actingAs($admin);
+
+        $sale = Purchase::query()->create([
+            'tenant_codigo' => $tenant->codigo,
+            'nombre_apellido' => 'Ana Pérez',
+            'status' => Purchase::STATUS_CANCELLED,
+            'total' => '10000.00',
+        ]);
+        Purchase::query()->whereKey($sale->id)->update([
+            'created_at' => '2026-08-04 10:00:00',
+        ]);
+
+        $otherSale = Purchase::query()->create([
+            'tenant_codigo' => $tenant->codigo,
+            'nombre_apellido' => 'Otro cliente',
+            'status' => Purchase::STATUS_PAID,
+            'total' => '20000.00',
+        ]);
+        Purchase::query()->whereKey($otherSale->id)->update([
+            'created_at' => '2026-08-05 10:00:00',
+        ]);
+
+        $confirmedChange = ValueChange::query()->create([
+            'tenant_code' => $tenant->codigo,
+            'trackable_type' => $sale->getMorphClass(),
+            'trackable_id' => $sale->id,
+            'attribute' => 'status',
+            'old_value' => Purchase::STATUS_PENDING_PAYMENT,
+            'new_value' => Purchase::STATUS_PAID,
+            'changed_at' => '2026-08-06 10:00:00',
+            'actor_type' => ValueChangeActorType::User,
+            'user_id' => $admin->id,
+        ]);
+        ValueChange::query()->create([
+            'tenant_code' => $tenant->codigo,
+            'trackable_type' => $sale->getMorphClass(),
+            'trackable_id' => $sale->id,
+            'attribute' => 'status',
+            'old_value' => Purchase::STATUS_PAID,
+            'new_value' => Purchase::STATUS_CANCELLED,
+            'changed_at' => '2026-08-07 10:00:00',
+            'actor_type' => ValueChangeActorType::User,
+            'user_id' => $admin->id,
+        ]);
+        ValueChange::query()->create([
+            'tenant_code' => $tenant->codigo,
+            'trackable_type' => $otherSale->getMorphClass(),
+            'trackable_id' => $otherSale->id,
+            'attribute' => 'status',
+            'old_value' => Purchase::STATUS_PENDING_PAYMENT,
+            'new_value' => Purchase::STATUS_PAID,
+            'changed_at' => '2026-08-08 10:00:00',
+            'actor_type' => ValueChangeActorType::System,
+        ]);
+        ValueChange::query()->create([
+            'tenant_code' => $otherTenant->codigo,
+            'trackable_type' => $sale->getMorphClass(),
+            'trackable_id' => $sale->id,
+            'attribute' => 'status',
+            'old_value' => Purchase::STATUS_PENDING_PAYMENT,
+            'new_value' => Purchase::STATUS_PAID,
+            'changed_at' => '2026-08-09 10:00:00',
+            'actor_type' => ValueChangeActorType::System,
+        ]);
+
+        $this->getJson('/api/v1/adminapp/tenant/sales/modifications?'.http_build_query([
+            'q' => 'Ana',
+            'id' => $sale->id,
+            'sale_date' => '2026-08-04',
+            'status' => Purchase::ADMIN_STATUS_CONFIRMED,
+        ]))
+            ->assertOk()
+            ->assertJsonCount(1, 'data')
+            ->assertJsonPath('data.0.id', $confirmedChange->id)
+            ->assertJsonPath('data.0.new_value', Purchase::STATUS_PAID)
+            ->assertJsonPath('data.0.admin_status', Purchase::ADMIN_STATUS_CONFIRMED);
+
+        $this->getJson('/api/v1/adminapp/tenant/sales/modifications?status='.
+            Purchase::ADMIN_STATUS_CANCELLED)
+            ->assertOk()
+            ->assertJsonCount(1, 'data')
+            ->assertJsonPath('data.0.sale_id', $sale->id)
+            ->assertJsonPath('data.0.new_value', Purchase::STATUS_CANCELLED);
+    }
+
     public function test_sales_list_uses_purchase_item_snapshots_for_every_status(): void
     {
         $tenant = $this->createTenant('acme');
@@ -64,6 +158,7 @@ class AdminAppSaleControllerTest extends TestCase
         PurchaseItem::query()->create([
             'compra_id' => $createdPurchase->id,
             'source_catalog_item_id' => $catalogItem->id,
+            'nombre' => $catalogItem->nombre,
             'item_nombre' => $catalogItem->nombre,
             'cantidad' => 3,
             'precio_unitario' => '10000.00',
@@ -88,6 +183,7 @@ class AdminAppSaleControllerTest extends TestCase
         PurchaseItem::query()->create([
             'compra_id' => $pendingPurchase->id,
             'source_catalog_item_id' => $catalogItem->id,
+            'nombre' => $catalogItem->nombre,
             'item_nombre' => $catalogItem->nombre,
             'cantidad' => 4,
             'precio_unitario' => '10000.00',
@@ -102,6 +198,7 @@ class AdminAppSaleControllerTest extends TestCase
         PurchaseItem::query()->create([
             'compra_id' => $paidPurchase->id,
             'source_catalog_item_id' => $catalogItem->id,
+            'nombre' => $catalogItem->nombre,
             'item_nombre' => $catalogItem->nombre,
             'cantidad' => 2,
             'precio_unitario' => '10000.00',
@@ -116,6 +213,7 @@ class AdminAppSaleControllerTest extends TestCase
         PurchaseItem::query()->create([
             'compra_id' => $supersededPurchase->id,
             'source_catalog_item_id' => $catalogItem->id,
+            'nombre' => $catalogItem->nombre,
             'item_nombre' => $catalogItem->nombre,
             'cantidad' => 5,
             'precio_unitario' => '10000.00',
@@ -124,17 +222,25 @@ class AdminAppSaleControllerTest extends TestCase
 
         $this->getJson('/api/v1/adminapp/tenant/sales?sort_by=id&sort_direction=asc')
             ->assertOk()
-            ->assertJsonCount(3, 'data')
+            ->assertJsonCount(4, 'data')
             ->assertJsonPath('data.0.id', $createdPurchase->id)
             ->assertJsonPath('data.0.quantity', 3)
+            ->assertJsonPath('data.0.admin_status', Purchase::ADMIN_STATUS_INCOMPLETE)
+            ->assertJsonPath('data.0.status_label', 'Por completar datos')
             ->assertJsonPath('data.1.id', $pendingPurchase->id)
             ->assertJsonPath('data.1.quantity', 4)
+            ->assertJsonPath('data.1.admin_status', Purchase::ADMIN_STATUS_AWAITING_PAYMENT)
+            ->assertJsonPath('data.1.status_label', 'Esperando pago')
             ->assertJsonPath('data.2.id', $paidPurchase->id)
-            ->assertJsonPath('data.2.quantity', 2);
+            ->assertJsonPath('data.2.quantity', 2)
+            ->assertJsonPath('data.2.admin_status', Purchase::ADMIN_STATUS_CONFIRMED)
+            ->assertJsonPath('data.2.status_label', 'Confirmado')
+            ->assertJsonPath('data.3.id', $supersededPurchase->id)
+            ->assertJsonPath('data.3.admin_status', Purchase::ADMIN_STATUS_CANCELLED)
+            ->assertJsonPath('data.3.status_label', 'Anulado');
 
         $this->getJson('/api/v1/adminapp/tenant/sales?status='.Purchase::STATUS_SUPERSEDED)
-            ->assertOk()
+            ->assertUnprocessable();
-            ->assertJsonCount(0, 'data');
     }
 
     public function test_authentication_is_required_to_read_a_sale_detail(): void
@@ -142,7 +248,7 @@ class AdminAppSaleControllerTest extends TestCase
         $this->getJson('/api/v1/adminapp/tenant/sales/1')->assertUnauthorized();
     }
 
-    public function test_pending_payment_filter_also_returns_purchases_in_review(): void
+    public function test_awaiting_payment_filter_returns_every_mapped_real_status(): void
     {
         $tenant = $this->createTenant('acme');
         Sanctum::actingAs($this->createAdminAppUser($tenant));
@@ -160,13 +266,41 @@ class AdminAppSaleControllerTest extends TestCase
             'status' => Purchase::STATUS_PAID,
         ]);
 
-        $this->getJson('/api/v1/adminapp/tenant/sales?status=pending_payment&sort_by=id&sort_direction=asc')
+        $this->getJson('/api/v1/adminapp/tenant/sales?status=awaiting_payment&sort_by=id&sort_direction=asc')
             ->assertOk()
             ->assertJsonCount(2, 'data')
             ->assertJsonPath('data.0.id', $pendingPurchase->id)
             ->assertJsonPath('data.1.id', $reviewPurchase->id);
     }
 
+    public function test_cancelled_filter_returns_every_visible_mapped_real_status(): void
+    {
+        $tenant = $this->createTenant('acme');
+        Sanctum::actingAs($this->createAdminAppUser($tenant));
+
+        foreach ([
+            Purchase::STATUS_CANCELLED,
+            Purchase::STATUS_REJECTED,
+            Purchase::STATUS_EXPIRED,
+            Purchase::STATUS_SUPERSEDED,
+        ] as $status) {
+            Purchase::query()->create([
+                'tenant_codigo' => $tenant->codigo,
+                'status' => $status,
+            ]);
+        }
+        Purchase::query()->create([
+            'tenant_codigo' => $tenant->codigo,
+            'status' => Purchase::STATUS_PAID,
+        ]);
+
+        $this->getJson('/api/v1/adminapp/tenant/sales?status=cancelled')
+            ->assertOk()
+            ->assertJsonCount(4, 'data')
+            ->assertJsonPath('data.0.admin_status', Purchase::ADMIN_STATUS_CANCELLED)
+            ->assertJsonPath('data.0.status_label', 'Anulado');
+    }
+
     public function test_an_adminapp_user_can_read_a_sale_detail_from_its_tenant(): void
     {
         $tenant = $this->createTenant('acme');
@@ -233,6 +367,7 @@ class AdminAppSaleControllerTest extends TestCase
         $purchaseItem = PurchaseItem::query()->create([
             'compra_id' => $purchase->id,
             'source_catalog_item_id' => $catalogItem->id,
+            'nombre' => $catalogItem->nombre,
             'item_nombre' => $catalogItem->nombre,
             'cantidad' => 2,
             'precio_unitario' => '12500.00',
@@ -479,6 +614,7 @@ class AdminAppSaleControllerTest extends TestCase
         PurchaseItem::query()->create([
             'compra_id' => $purchase->id,
             'source_catalog_item_id' => $catalogItem->id,
+            'nombre' => $catalogItem->nombre,
             'item_nombre' => $catalogItem->nombre,
             'cantidad' => 2,
             'precio_unitario' => '10000.00',
@@ -574,14 +710,34 @@ class AdminAppSaleControllerTest extends TestCase
 
     private function createTenant(string $code): Tenant
     {
+        $headerLogo = $this->createAttachment("{$code}-header");
+        $footerLogo = $this->createAttachment("{$code}-footer");
+
         return Tenant::query()->create([
             'codigo' => $code,
             'nombre' => ucfirst($code),
             'dominio' => "{$code}.test",
+            'primary_color' => '#000000',
+            'secondary_color' => '#ffffff',
+            'danger_color' => '#dc3545',
+            'header_bg_color' => '#ffffff',
+            'footer_bg_color' => '#000000',
+            'header_logo_id' => $headerLogo->id,
+            'footer_logo_id' => $footerLogo->id,
             'website_type_code' => 'onticket',
         ]);
     }
 
+    private function createAttachment(string $name): Attachment
+    {
+        return Attachment::query()->create([
+            'path' => "test/{$name}.png",
+            'filename' => "{$name}.png",
+            'type' => AttachmentType::Image,
+            'mime_type' => 'image/png',
+        ]);
+    }
+
     private function createAdminAppUser(Tenant $tenant): User
     {
         return User::factory()->create([

tests/Unit/Forms/SaleFormServiceTest.php

@@ -8,20 +8,27 @@ use PHPUnit\Framework\TestCase;
 
 class SaleFormServiceTest extends TestCase
 {
-    public function test_it_returns_every_purchase_status_as_a_form_option(): void
+    public function test_it_returns_admin_statuses_with_their_real_statuses(): void
     {
         $form = (new SaleFormService)->get();
 
-        $this->assertSame(Purchase::statuses(), array_column($form['statuses'], 'code'));
+        $this->assertSame(Purchase::adminStatusCodes(), array_column($form['statuses'], 'value'));
         $this->assertSame([
-            'Creada',
+            'Por completar datos',
             'Esperando pago',
-            'En revisión',
+            'Confirmado',
-            'Confirmada',
+            'Anulado',
-            'Cancelada',
+        ], array_column($form['statuses'], 'label'));
-            'Rechazada',
+        $this->assertSame([
-            'Vencida',
+            [Purchase::STATUS_CREATED],
-            'Reemplazada',
+            [Purchase::STATUS_PENDING_PAYMENT, Purchase::STATUS_IN_REVIEW],
-        ], array_column($form['statuses'], 'name'));
+            [Purchase::STATUS_PAID],
+            [
+                Purchase::STATUS_CANCELLED,
+                Purchase::STATUS_REJECTED,
+                Purchase::STATUS_EXPIRED,
+                Purchase::STATUS_SUPERSEDED,
+            ],
+        ], array_column($form['statuses'], 'real_statuses'));
     }
 }

tests/Unit/Purchase/PurchaseAdminStatusTest.php

@@ -0,0 +1,69 @@
+<?php
+
+namespace Tests\Unit\Purchase;
+
+use App\Domains\Purchase\Models\Purchase;
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\TestCase;
+
+class PurchaseAdminStatusTest extends TestCase
+{
+    #[DataProvider('statusMappings')]
+    public function test_it_maps_real_statuses_to_admin_statuses(
+        string $realStatus,
+        string $adminStatus,
+        string $adminStatusName,
+    ): void {
+        $this->assertSame($adminStatus, Purchase::adminStatusFor($realStatus));
+        $this->assertSame($adminStatusName, Purchase::adminStatusNameFor($realStatus));
+        $this->assertContains(
+            $realStatus,
+            Purchase::realStatusesForAdminStatus($adminStatus),
+        );
+    }
+
+    /** @return iterable<string, array{string, string, string}> */
+    public static function statusMappings(): iterable
+    {
+        yield 'created' => [
+            Purchase::STATUS_CREATED,
+            Purchase::ADMIN_STATUS_INCOMPLETE,
+            'Por completar datos',
+        ];
+        yield 'pending payment' => [
+            Purchase::STATUS_PENDING_PAYMENT,
+            Purchase::ADMIN_STATUS_AWAITING_PAYMENT,
+            'Esperando pago',
+        ];
+        yield 'in review' => [
+            Purchase::STATUS_IN_REVIEW,
+            Purchase::ADMIN_STATUS_AWAITING_PAYMENT,
+            'Esperando pago',
+        ];
+        yield 'paid' => [
+            Purchase::STATUS_PAID,
+            Purchase::ADMIN_STATUS_CONFIRMED,
+            'Confirmado',
+        ];
+        yield 'cancelled' => [
+            Purchase::STATUS_CANCELLED,
+            Purchase::ADMIN_STATUS_CANCELLED,
+            'Anulado',
+        ];
+        yield 'rejected' => [
+            Purchase::STATUS_REJECTED,
+            Purchase::ADMIN_STATUS_CANCELLED,
+            'Anulado',
+        ];
+        yield 'expired' => [
+            Purchase::STATUS_EXPIRED,
+            Purchase::ADMIN_STATUS_CANCELLED,
+            'Anulado',
+        ];
+        yield 'superseded' => [
+            Purchase::STATUS_SUPERSEDED,
+            Purchase::ADMIN_STATUS_CANCELLED,
+            'Anulado',
+        ];
+    }
+}

tests/Unit/Sale/SaleModificationResourceTest.php

@@ -3,6 +3,7 @@
 namespace Tests\Unit\Sale;
 
 use App\Domains\Logging\Models\ValueChange;
+use App\Domains\Purchase\Models\Purchase;
 use App\Domains\Sale\Resources\AdminApp\SaleModificationResource;
 use Carbon\CarbonImmutable;
 use Illuminate\Http\Request;
@@ -29,5 +30,7 @@ class SaleModificationResourceTest extends TestCase
         $this->assertSame('2026-08-24T17:53:00+00:00', $data['changed_at']);
         $this->assertSame('2026-08-24', $data['date']);
         $this->assertSame('17:53:00', $data['time']);
+        $this->assertSame(Purchase::ADMIN_STATUS_CANCELLED, $data['admin_status']);
+        $this->assertSame('Anulado', $data['status_label']);
     }
 }