barapp-orientation

name: barapp-orientation description: Mapa maestro y protocolo de seguridad de BarApp (Flutter/Firebase para bares). Usar SIEMPRE al empezar una tarea en este repo para ubicarse rápido, y OBLIGATORIO antes de tocar cualquier flujo operativo del panel de dueños — caja/POS, ventas, gastos, reservas, mesas, comandas/cocina, delivery, stock, impresión o firestore.rules. Define qué leer primero, las invariantes que no se pueden romper y cómo verificar antes de entregar.

BarApp — Orientación y Protocolo de Seguridad

BarApp es app Flutter/Firebase para bares: descubrimiento, carta digital, reservas, mesas, pedidos QR/app, delivery, caja/POS, ventas externas, comandas de cocina, impresión, eventos, staff, panel de dueños y BarPoints (fidelización).

Regla de oro del proyecto (Mariano): el "panel de dueños" es operatividad diaria real de bares. Nada de lo operativo puede romperse — una reserva, un pedido de mesa, una comanda que no llega o un cobro mal hecho es inaceptable. Ante la duda, NO cambiar un flujo: confirmar primero.

1. Orden de lectura al empezar cualquier tarea

1. AGENTS.md (raíz) — stack, comandos, convenciones, invariantes de negocio.
2. La skill-doc de dominio en skills/ según el área:
   • skills/barapp_firestore.md — colecciones, subcolecciones, queries, tx.
   • skills/barapp_owner_panel.md — pantallas, roles, navegación del panel.
   • skills/barapp_printing_pos.md — caja, POS, ventas, comandas, tickets, impresión, stock.
   • skills/barapp_security_rules.md — rules, roles, helpers, sincronía de copias.
   • skills/barapp_ui_flutter.md — tema, pantallas, navegación, responsive.
3. cambios cursor/ — changelog vivo por fases. Estado actual = FASE 3.
   • cambios cursor/FASE 3/00-revision-final-panel-dueno.md — auditoría ultra-fina (8 P0 + 22 P1 + 20 P2). Aplicados en Sprint P0/P1 (docs 01, 02).
   • Antes de tocar un módulo, leer su auditoría de fase (ej. reservas, gastos, cocina).
4. docs/ — BarPoints (ANALISIS_BARPOINTS.md, AUDITORIA_BARPOINTS_CUPONES.md), deploy web, secrets.

Al cerrar un módulo revisado, agregar un NN-nombre.md en la fase activa (convención del repo).

2. Invariantes operativas que NO se rompen

• Caja: no se registra NINGUNA venta/gasto efectivo/movimiento sin caja abierta. CajaSessionGuard.assertAbiertaEnTransaccion valida openCajaSessionId + sesión abierta dentro de la transacción. POS, delivery y ventas externas usan el mismo guard.
• Ventas: llevan cajaSessionId. Cobros de mesa leen cuenta_items DENTRO de la tx (anti doble-cobro). No cobrar mesa con órdenes de cocina activas.
• Stock: si controlaStock == true, POS/app/ventas externas validan y decrementan contra menu en la misma tx. La restauración de stock cubre los 4 estados terminales fallidos (rechazado, cancelado, cancelado_por_mozo, error).
• Reservas ↔ Mesas ↔ Cocina: sincronizar mesaId, mesaNombre, estado, reservaIdActiva, clienteActivo, agendaLockIds, agendaReservaIds. Escribir mesas desde el panel SIEMPRE vía los servicios (ReservationTableService, MesaOperationalService, PosOrderService/PosPaymentService), nunca con update directo, y marcar panelWriteAt.
• Impresión: flags impreso evitan duplicar tickets/comandas/reservas.
• Roles: superadmin (UIDs en rules) > owner (ownerId/userId) > staff (places/{id}/staff/{uid} con rol: admin/cajero/encargado/mozo/cocinero/repartidor).

3. Reglas de Firestore — doble copia

firestore.rules (raíz, fuente de verdad) y barapp_backend/firestore.rules deben quedar byte a byte idénticas. Igual para storage.rules y barapp_backend/storage.rules. Si tocás una, sincronizá la otra EN LA MISMA TAREA. Verificar:

diff -q firestore.rules barapp_backend/firestore.rules   # debe decir nada (idénticas)
diff -q storage.rules   barapp_backend/storage.rules

No renombrar colecciones, campos, rutas ni roles sin migración explícita y justificada.

4. Comandos clave

flutter analyze                         # debe quedar sin errores (warnings menores tolerados)
flutter test                            # ~387 unit + widget + integration
flutter test test/unit/security_hardening_test.dart   # guardas de rules/seguridad
flutter pub get
flutter run --dart-define-from-file=dart_defines.json
./deploy_web.sh                         # ÚNICO deploy web correcto (rota APP_BUILD_ID + cache)
# Functions: en barapp_backend/functions → npm run serve | npm run deploy | npm run logs
firebase deploy --only firestore:rules,firestore:indexes,storage

deploy_web.sh es el único flujo que actualiza APP_BUILD_ID y cache de hosting. flutter build web solo NO sirve para producción.

5. Checklist antes de entregar un cambio operativo

• Identificar rutas Firestore leídas/escritas y roles necesarios.
• Si tocó rules: sincronizar las dos copias + correr security_hardening_test.dart.
• Confirmar invariantes tocadas: caja abierta, stock, ventas, reservas, mesas, impresión.
• Estados loading/error/empty en UI; responsive mobile/desktop/web si la pantalla lo soporta.
• flutter analyze limpio (o justificar) + tests del área.
• Cambios chicos y reversibles; reutilizar servicios/mixins existentes antes de abstraer.
• Si hay riesgo operativo, decirlo explícito y proponer verificación manual.

6. Deuda / pendientes conocidos a tener presentes

• Trabajo de Fase 3 (hardening P0/P1) vive en el working tree: commitear y deployar rules + functions + web juntos para que producción quede consistente con el código.
• features se usa como lista (características) y como mapa (feature flags): no tocar sin decidir migración con compatibilidad.
• usuarios list/get sigue abierto a logueados por compatibilidad con búsqueda/staff (PII).
• Faltan tests de emulator para rules de flujos de dinero críticos.