Bitácora de Actividad — Guía para RC

● Pedro (POS)       Canceló línea Ticket #4521          hace 3 min
● Marco (Dashboard) Envió OC a COTSCO por WhatsApp      hace 12 min
● Ana (POS)         Aplicó descuento 20% en Mesa 7       hace 18 min
● José (POS)        Editó precio ACEITE +5,455%          hace 2 hrs ⚠️

POST /api/v1/ingest/activity
X-API-Key: rpro_live_xxx
Content-Type: application/json
X-Idempotency-Key: {uuid-unico}

// Cancelación de línea en ticket abierto
'event' => 'ticket.line_cancelled'
'detail' => [
    'item'         => $line->item_name,
    'reason'       => $reason,        // motivo que el mesero captura
    'amount_cents' => $line->net_total_cents * 100,
    'ticket_id'    => (string) $ticket->id,
    'authorized_by'=> $manager?->name,  // si requirió autorización
]

// Void de ticket completo
'event' => 'ticket.voided'
'detail' => [
    'ticket_total_cents' => $ticket->total * 100,
    'items_count'        => $ticket->lines->count(),
    'reason'             => $reason,
    'authorized_by'      => $manager?->name,
]

// Descuento manual aplicado
'event' => 'ticket.discount_applied'
'detail' => [
    'discount_pct'    => $discount->percentage,
    'discount_cents'  => $discount->amount * 100,
    'ticket_id'       => (string) $ticket->id,
    'discount_type'   => $discount->type, // 'percentage' | 'fixed' | 'courtesy'
]

// Precio modificado manualmente en POS
'event' => 'ticket.price_overridden'
'detail' => [
    'item'            => $line->item_name,
    'original_cents'  => $line->unit_price * 100,
    'new_cents'       => $newPrice * 100,
    'ticket_id'       => (string) $ticket->id,
]

// Apertura de turno
'event' => 'cash_register.opened'
'detail' => [
    'opening_balance_cents' => $opening->initial_amount * 100,
    'shift'                 => $opening->shift, // 'morning' | 'afternoon' | 'night'
]

// Cierre con diferencia de caja
'event' => 'cash_register.closed'
'detail' => [
    'expected_cents'  => $corte->expected_cash * 100,
    'counted_cents'   => $corte->counted_cash * 100,
    'variance_cents'  => $corte->variance * 100,  // negativo = faltante
    'type'            => $corte->type, // 'xout' | 'zout'
]

// Login exitoso
'event' => 'user.login'
'detail' => [
    'ip'     => request()->ip(),
    'device' => request()->userAgent(),
]

// Login fallido
'event' => 'user.login_failed'
'detail' => [
    'ip'             => request()->ip(),
    'attempted_user' => $request->username,
]

// Cuando el gerente autoriza cualquier acción
'event' => 'manager.override'
'detail' => [
    'action'  => 'cancel_line',  // qué se autorizó
    'for_user'=> $waiter->name,
    'ref'     => "Ticket #{$ticket->id}",
]

<?php

namespace App\Services;

use Illuminate\Support\Facades\Http;
use Illuminate\Support\Str;

class RestauranteroActivityService
{
    private string $apiKey;
    private string $baseUrl = 'https://api.restauranteropro.com/api/v1';

    public function __construct()
    {
        $this->apiKey = config('restaurantero.api_key');
    }

    /**
     * Envía un evento a la Bitácora de Restaurantero Pro.
     *
     * @param string $branchIdentifier UUID del branch en RP
     * @param string $event            Tipo de evento (ticket.line_cancelled, etc.)
     * @param array  $detail           Datos específicos del evento
     * @param array  $options          actor_name, actor_role, ref_type, ref_id, device
     */
    public function log(
        string $branchIdentifier,
        string $event,
        array  $detail = [],
        array  $options = []
    ): void {
        // No bloquear el flujo del POS si RP no responde
        try {
            Http::timeout(3)
                ->withHeaders([
                    'X-API-Key'          => $this->apiKey,
                    'Content-Type'       => 'application/json',
                    'X-Idempotency-Key'  => Str::uuid()->toString(),
                ])
                ->post("{$this->baseUrl}/ingest/activity", [
                    'data' => [
                        'type'       => 'activity',
                        'attributes' => [
                            'branch_identifier' => $branchIdentifier,
                            'occurred_at'       => now()->toISOString(),
                            'actor_name'        => $options['actor_name'] ?? auth()->user()?->name ?? 'Sistema',
                            'actor_role'        => $options['actor_role'] ?? auth()->user()?->role ?? 'system',
                            'source'            => 'rc_pos',
                            'event'             => $event,
                            'ref_type'          => $options['ref_type'] ?? null,
                            'ref_id'            => $options['ref_id'] ?? null,
                            'detail'            => $detail,
                        ],
                        'meta'       => [
                            'pos_name'    => 'restaurant_controller',
                            'pos_version' => config('app.version', '2.1.0'),
                            'device'      => $options['device'] ?? request()->userAgent(),
                            'sent_at'     => now()->toISOString(),
                        ],
                    ],
                ]);
        } catch (\Throwable $e) {
            // Log local — nunca interrumpir el POS por falla de RP
            logger()->warning('RestauranteroActivity: fallo al enviar evento', [
                'event' => $event,
                'error' => $e->getMessage(),
            ]);
        }
    }
}

// En el observer de CancelledLine o donde manejes cancelaciones
app(RestauranteroActivityService::class)->log(
    branchIdentifier: $branch->rpro_identifier,
    event: 'ticket.line_cancelled',
    detail: [
        'item'         => $line->item_name,
        'reason'       => $reason,
        'amount_cents' => (int) round($line->net_total * 100),
    ],
    options: [
        'actor_name' => auth()->user()->name,
        'actor_role' => auth()->user()->role,
        'ref_type'   => 'ticket',
        'ref_id'     => (string) $ticket->id,
    ]
);

// En un comando Artisan temporal de RC
Http::withHeaders([
    'X-API-Key'         => env('RESTAURANTERO_API_KEY'),
    'X-Idempotency-Key' => Str::uuid(),
])->post('https://api.restauranteropro.com/api/v1/ingest/activity', [
    'data' => [
        'type'       => 'activity',
        'attributes' => [
            'branch_identifier' => '019e0c31-f390-7185-8bff-f5046c392930',
            'occurred_at'       => now()->toISOString(),
            'actor_name'        => 'Carlos Dev',
            'actor_role'        => 'developer',
            'source'            => 'rc_pos',
            'event'             => 'ticket.line_cancelled',
            'ref_type'          => 'ticket',
            'ref_id'            => '9999',
            'detail'            => [
                'item'         => 'TEST ITEM',
                'reason'       => 'Prueba de integración',
                'amount_cents' => 10000,
            ],
        ],
        'meta' => [
            'pos_name'   => 'restaurant_controller',
            'pos_version'=> '2.1.0',
            'sent_at'    => now()->toISOString(),
        ],
    ],
]);