tbianchini/shopit-back
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(refund): implement backfill command for historical ticket refunds reconciliation

Browse Source
This commit is contained in:
ncoronel
2026-09-17 12:29:33 -03:00
parent 830f65c402
commit 5503559899
4 changed files with 159 additions and 135 deletions
Download Patch File Download Diff File Expand all files Collapse all files

121
app/Domains/Ticket/Services/BackfillRefundedUnitsService.php Normal file
View File

@@ -0,0 +1,121 @@
<?php
namespace App\Domains\Ticket\Services;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Log;
use RuntimeException;
class BackfillRefundedUnitsService
{
/** @return array<string, int> */
public function run(): array
{
$summary = DB::transaction(function (): array {
if (DB::table('inventories')->where('refunded_units', '>', 0)->exists()) {
throw new RuntimeException('El backfill requiere que refunded_units sea cero en todos los inventarios.');
}
$counts = [];
$variants = [];
$refundsSeen = 0;
$bundlesSkipped = 0;
DB::table('ticket_refunds as refunds')
->join('tickets', 'tickets.id', '=', 'refunds.ticket_id')
->join('compra_items as purchase_items', 'purchase_items.id', '=', 'refunds.purchase_item_id')
->leftJoin('catalog_items as purchase_catalog', 'purchase_catalog.id', '=', 'purchase_items.source_catalog_item_id')
->leftJoin('catalog_items as ticket_catalog', 'ticket_catalog.id', '=', 'tickets.source_catalog_item_id')
->select([
'refunds.id',
'refunds.ticket_id',
'tickets.source_variant_id',
'ticket_catalog.inventory_id',
'ticket_catalog.inventory_policy',
'ticket_catalog.type as ticket_catalog_type',
'purchase_catalog.type as purchase_catalog_type',
])
->chunkById(500, function ($refunds) use (&$counts, &$variants, &$refundsSeen, &$bundlesSkipped): void {
foreach ($refunds as $refund) {
$refundsSeen++;
if ($refund->ticket_catalog_type === 'bundle' || $refund->purchase_catalog_type === 'bundle') {
$bundlesSkipped++;
continue;
}
if ($refund->inventory_policy === null) {
throw new RuntimeException("El reembolso {$refund->id} no tiene un producto de catálogo asociado.");
}
$inventoryId = $refund->source_variant_id === null
? $refund->inventory_id
: $this->currentVariantInventoryId((int) $refund->source_variant_id, $variants);
if ($inventoryId === null) {
throw new RuntimeException("El reembolso {$refund->id} no tiene un inventario asociado.");
}
$counts[$inventoryId]['refunded'] = ($counts[$inventoryId]['refunded'] ?? 0) + 1;
if ($refund->inventory_policy === 'tracked') {
$counts[$inventoryId]['stock'] = ($counts[$inventoryId]['stock'] ?? 0) + 1;
}
}
}, 'refunds.id', 'id');
foreach ($counts as $inventoryId => $count) {
$updates = ['refunded_units' => DB::raw('refunded_units + '.$count['refunded'])];
if (($count['stock'] ?? 0) > 0) {
$updates['real_stock'] = DB::raw('real_stock + '.$count['stock']);
}
if (DB::table('inventories')->where('id', $inventoryId)->update($updates) !== 1) {
throw new RuntimeException("No se encontró el inventario {$inventoryId} para reponerlo.");
}
}
$refundedUnitsAdded = array_sum(array_column($counts, 'refunded'));
return [
'refunds_seen' => $refundsSeen,
'refunds_applied' => $refundedUnitsAdded,
'bundles_skipped' => $bundlesSkipped,
'inventories_updated' => count($counts),
'refunded_units_added' => $refundedUnitsAdded,
'real_stock_added' => array_sum(array_column($counts, 'stock')),
];
});
Log::info('inventory.refunded_units_backfill.completed', $summary);
return $summary;
}
/** @param array<int, object|null> $variants */
private function currentVariantInventoryId(int $variantId, array &$variants): ?int
{
$visited = [];
while (true) {
if (isset($visited[$variantId])) {
throw new RuntimeException("La cadena de reemplazos de la variante {$variantId} es circular.");
}
$visited[$variantId] = true;
if (! array_key_exists($variantId, $variants)) {
$variants[$variantId] = DB::table('variantes')
->where('id', $variantId)
->first(['inventory_id', 'replaced_by_variant_id']);
}
$variant = $variants[$variantId];
if ($variant === null) {
throw new RuntimeException("No se encontró la variante {$variantId} de un ticket reembolsado.");
}
if ($variant->replaced_by_variant_id === null) {
return $variant->inventory_id === null ? null : (int) $variant->inventory_id;
}
$variantId = (int) $variant->replaced_by_variant_id;
}
}
}

135
database/migrations/2026_09_16_000100_backfill_refunded_units.php
View File

@@ -1,147 +1,16 @@
<?php
use Illuminate\Database\Events\MigrationsEnded;
use Illuminate\Database\Migrations\Migration;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Event;
use Illuminate\Support\Facades\Log;
use Symfony\Component\Console\Output\ConsoleOutput;
return new class extends Migration
{
public function up(): void
{
$summary = DB::transaction(function (): array {
if (DB::table('inventories')->where('refunded_units', '>', 0)->exists()) {
throw new RuntimeException('El backfill requiere que refunded_units sea cero en todos los inventarios.');
}
$counts = [];
$variants = [];
$refundsSeen = 0;
$bundlesSkipped = 0;
DB::table('ticket_refunds as refunds')
->join('tickets', 'tickets.id', '=', 'refunds.ticket_id')
->join('compra_items as purchase_items', 'purchase_items.id', '=', 'refunds.purchase_item_id')
->leftJoin('catalog_items as purchase_catalog', 'purchase_catalog.id', '=', 'purchase_items.source_catalog_item_id')
->leftJoin('catalog_items as ticket_catalog', 'ticket_catalog.id', '=', 'tickets.source_catalog_item_id')
->select([
'refunds.id',
'refunds.ticket_id',
'tickets.source_variant_id',
'ticket_catalog.inventory_id',
'ticket_catalog.inventory_policy',
'ticket_catalog.type as ticket_catalog_type',
'purchase_catalog.type as purchase_catalog_type',
])
->chunkById(500, function ($refunds) use (&$counts, &$variants, &$refundsSeen, &$bundlesSkipped): void {
foreach ($refunds as $refund) {
$refundsSeen++;
// Bundle purchases need a component allocation that is outside this backfill.
if ($refund->ticket_catalog_type === 'bundle' || $refund->purchase_catalog_type === 'bundle') {
$bundlesSkipped++;
continue;
}
if ($refund->inventory_policy === null) {
throw new RuntimeException("El reembolso {$refund->id} no tiene un producto de catálogo asociado.");
}
$inventoryId = $refund->source_variant_id === null
? $refund->inventory_id
: $this->currentVariantInventoryId((int) $refund->source_variant_id, $variants);
if ($inventoryId === null) {
throw new RuntimeException("El reembolso {$refund->id} no tiene un inventario asociado.");
}
$counts[$inventoryId]['refunded'] = ($counts[$inventoryId]['refunded'] ?? 0) + 1;
if ($refund->inventory_policy === 'tracked') {
$counts[$inventoryId]['stock'] = ($counts[$inventoryId]['stock'] ?? 0) + 1;
}
}
}, 'refunds.id', 'id');
foreach ($counts as $inventoryId => $count) {
$updates = ['refunded_units' => DB::raw('refunded_units + '.$count['refunded'])];
if (($count['stock'] ?? 0) > 0) {
$updates['real_stock'] = DB::raw('real_stock + '.$count['stock']);
}
if (DB::table('inventories')->where('id', $inventoryId)->update($updates) !== 1) {
throw new RuntimeException("No se encontró el inventario {$inventoryId} para reponerlo.");
}
}
$refundedUnitsAdded = array_sum(array_column($counts, 'refunded'));
$realStockAdded = array_sum(array_column($counts, 'stock'));
return [
'refunds_seen' => $refundsSeen,
'refunds_applied' => $refundedUnitsAdded,
'bundles_skipped' => $bundlesSkipped,
'inventories_updated' => count($counts),
'refunded_units_added' => $refundedUnitsAdded,
'real_stock_added' => $realStockAdded,
];
});
Log::info('inventory.refunded_units_backfill.completed', $summary);
// The migrator prints DONE after up() returns. Emit the summary once the
// whole migration run ends so it appears below that line in the console.
if (app()->runningInConsole()) {
$printed = false;
Event::listen(MigrationsEnded::class, static function (MigrationsEnded $event) use ($summary, &$printed): void {
if ($printed || $event->method !== 'up') {
return;
}
$printed = true;
(new ConsoleOutput)->writeln(sprintf(
' <info>Refund backfill:</info> %d applied, %d bundles skipped, %d inventories updated, +%d refunded_units, +%d real_stock',
$summary['refunds_applied'],
$summary['bundles_skipped'],
$summary['inventories_updated'],
$summary['refunded_units_added'],
$summary['real_stock_added'],
));
});
}
}
/** @param array<int, object|null> $variants */
private function currentVariantInventoryId(int $variantId, array &$variants): ?int
{
$visited = [];
while (true) {
if (isset($visited[$variantId])) {
throw new RuntimeException("La cadena de reemplazos de la variante {$variantId} es circular.");
}
$visited[$variantId] = true;
if (! array_key_exists($variantId, $variants)) {
$variants[$variantId] = DB::table('variantes')
->where('id', $variantId)
->first(['inventory_id', 'replaced_by_variant_id']);
}
$variant = $variants[$variantId];
if ($variant === null) {
throw new RuntimeException("No se encontró la variante {$variantId} de un ticket reembolsado.");
}
if ($variant->replaced_by_variant_id === null) {
return $variant->inventory_id === null ? null : (int) $variant->inventory_id;
}
$variantId = (int) $variant->replaced_by_variant_id;
}
// Historical reconciliation runs explicitly via tickets:backfill-refunded-units.
}
public function down(): void
{
throw new RuntimeException('El backfill de reembolsos históricos no se puede revertir sin reconciliar el stock.');
// Reconciliation cannot be reversed without auditing stock.
}
};

22
routes/console.php
View File

@@ -3,6 +3,7 @@
use App\Domains\Auth\Services\AdminCredentialVerifier;
use App\Domains\Catalog\Services\ExpireStockReservationsService;
use App\Domains\Purchase\Services\TenantTransactionResetService;
use App\Domains\Ticket\Services\BackfillRefundedUnitsService;
use App\Domains\Ticket\Services\LoadTestTicketDatasetService;
use Illuminate\Foundation\Inspiring;
use Illuminate\Support\Facades\Artisan;
@@ -13,6 +14,27 @@ Artisan::command('inspire', function () {
$this->comment(Inspiring::quote());
})->purpose('Display an inspiring quote');
Artisan::command('tickets:backfill-refunded-units', function (BackfillRefundedUnitsService $service): int {
try {
$summary = $service->run();
} catch (Throwable $exception) {
$this->error($exception->getMessage());
return self::FAILURE;
}
$this->info(sprintf(
'Refund backfill: %d applied, %d bundles skipped, %d inventories updated, +%d refunded_units, +%d real_stock',
$summary['refunds_applied'],
$summary['bundles_skipped'],
$summary['inventories_updated'],
$summary['refunded_units_added'],
$summary['real_stock_added'],
));
return self::SUCCESS;
})->purpose('Reconcile historical ticket refunds with inventory after reviewing existing refunded units');
Artisan::command('reservations:expire', function (): void {
$expired = app(ExpireStockReservationsService::class)->expireOverdue();

16
tests/Feature/Ticket/AdminAppTicketControllerTest.php
View File

@@ -289,8 +289,7 @@ class AdminAppTicketControllerTest extends TestCase
'refunded_units_added' => 1,
'real_stock_added' => 1,
]);
$backfill = require database_path('migrations/2026_09_16_000100_backfill_refunded_units.php');
$backfill->up();
$this->artisan('tickets:backfill-refunded-units')->assertSuccessful();
$this->assertSame(1, $inventory->fresh()->refunded_units);
$this->assertSame(1, $inventory->fresh()->real_stock);
@@ -308,6 +307,19 @@ class AdminAppTicketControllerTest extends TestCase
$this->assertSame(2, $inventory->fresh()->real_stock);
}
public function test_backfill_command_fails_without_changing_existing_refunded_units(): void
{
$inventory = Inventory::query()->create([
'real_stock' => 3,
'refunded_units' => 1,
]);
$this->artisan('tickets:backfill-refunded-units')->assertFailed();
$this->assertSame(1, $inventory->fresh()->refunded_units);
$this->assertSame(3, $inventory->fresh()->real_stock);
}
public function test_it_records_different_refund_types_for_tickets_from_the_same_purchase_item(): void
{
$tenant = $this->createTenant('ticket-mixed-refunds');