Bitácora de Actividad — Guía para RC

Qué es la Bitácora

La Bitácora de Actividad es el módulo de auditoría de Restaurantero Pro. Registra cada acción de cada usuario — tanto en el dashboard como en el POS — en un solo lugar. El dueño ve en tiempo real:

● 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 ⚠️

Restaurantero Pro detecta automáticamente anomalías de comportamiento y alerta al dueño:

3+ cancelaciones del mismo mesero en 2 horas
Precio modificado fuera del rango histórico (±20%)
Login desde dispositivo o IP nunca antes visto

El endpoint

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

Es el mismo patrón que ya usas para el Corte Z — mismo header, mismo formato JSON:API.

Qué eventos disparar desde RC

Estos son los eventos de alto valor para el dueño. Agrega los que correspondan según la versión de RC (Full Dining o Express):

Tickets y ventas

// 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,
]

Caja y turnos

// 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'
]

Usuarios y accesos

// 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,
]

Autorización de gerente

// 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}",
]

Snippet PHP completo — listo para copiar

<?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(),
            ]);
        }
    }
}

Uso en los observers de RC

// 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,
    ]
);

El try/catch con timeout(3) es importante — si Restaurantero Pro tiene algún problema, el POS no se debe quedar colgado. La Bitácora es best-effort: si un evento no llega, no afecta la operación del restaurante.

Cuándo disparar cada evento

A diferencia del Corte Z (que se envía una vez al día), los eventos de Bitácora se envían en tiempo real, al momento en que ocurre la acción.

Evento	Cuándo	Síncrono/Asíncrono
`ticket.line_cancelled`	Inmediatamente después de confirmar la cancelación	Async recomendado
`ticket.voided`	Inmediatamente después del void	Async recomendado
`ticket.discount_applied`	Al guardar el descuento	Async recomendado
`cash_register.opened`	Al crear el CashRegisterOpening	Async recomendado
`cash_register.closed`	Al cerrar el Corte Z (antes o después del ingest)	Async recomendado
`user.login`	En el AuthController, después de login exitoso	Async
`user.login_failed`	En el AuthController, después de fallo	Async
`manager.override`	Al registrar la autorización del gerente	Síncrono OK

No envíes eventos retroactivos — la Bitácora está diseñada para tiempo real. Si un evento falló, no lo reenvíes con occurred_at del pasado; simplemente déjalo pasar. El historial financiero lo cubre el Corte Z.

Checklist de integración para Bitácora

Prueba rápida desde Artisan (RC)

Agrega este comando en RC para probar sin abrir el POS:

// 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(),
        ],
    ],
]);

Verifica en el dashboard de Restaurantero Pro → Ajustes → Bitácora que el evento aparezca con source rc_pos.

​Qué es la Bitácora

​El endpoint

​Qué eventos disparar desde RC

​Tickets y ventas

​Caja y turnos

​Usuarios y accesos

​Autorización de gerente

​Snippet PHP completo — listo para copiar

​Uso en los observers de RC

​Cuándo disparar cada evento

​Checklist de integración para Bitácora

​Prueba rápida desde Artisan (RC)

Qué es la Bitácora

El endpoint

Qué eventos disparar desde RC

Tickets y ventas

Caja y turnos

Usuarios y accesos

Autorización de gerente

Snippet PHP completo — listo para copiar

Uso en los observers de RC

Cuándo disparar cada evento

Checklist de integración para Bitácora

Prueba rápida desde Artisan (RC)