Restaurante Resplandor POS
Software Design Document · v2.0 — Implementado
Punto de venta táctil para gestión de mesas, facturación y cierre diario, con sincronización multi-dispositivo en tiempo real y acceso restringido por login de Google.
Stack: HTML + Tailwind Play + Alpine.js + Lucide Icons + Supabase (Postgres + Realtime + Auth). Tailwind, Alpine, Lucide, supabase-js y el generador del QR del ticket son archivos locales de versión fija en assets/vendor/ (origen, versión y sha256 en assets/vendor/README.md), no CDNs: desde 2026-10-01 el POS no depende de ningún host de terceros para sus scripts.
| Versión | Estado | Stack | Actualizado |
|---|---|---|---|
| 1.0 — Open Spec | Definición inicial (solo localStorage, sin backend) | HTML · Tailwind · Alpine.js | Junio 2026 |
| 2.0 — Implementado | En producción, uso diario del restaurante | + Supabase (Postgres · Realtime · Auth) | Julio 2026 |
Dónde vive cada página (desde el 2026-09-29): la raíz
https://resplandor.ynt.codes/es la landing pública (index.html); el POS que describe este documento vive en/pos.html(uso interno:noindexyDisallowenrobots.txt);landing.htmlsolo redirige a la raíz para no romper enlaces ya publicados; la carta NFC y el menú siguen en/carta.htmly/menu.html. Detalle endocs/landing-y-agentes.md.
Estado de los roles, las alertas y la ola C (2026-10-01): en producción hay hoy la compuerta de personal (
personaly la restrictivasolo_personal), aplicada la noche del 2026-09-30 con Yonatan como único admin (mi_rol()devolvióadmin); Camila y los meseros todavía no están dados de alta. Todo lo demás está diseñado y probado en local, en ramas, y NO está al aire: los permisos por rol, las alertas de «pedir la cuenta» y el cobro por monto y por unidades (ola B), y el modelo de aprobación del personal, el panel de Mesas y pegatinas, el ticket configurable y deshacer un cobro (ola C). Aplicarlos es de Yonatan, en el orden de §07. Hasta entonces, lo que las secciones de abajo describen como «hoy» sigue siendo cierto en producción; lo nuevo va marcado con «ola B» u «ola C». El diseño completo está endocs/sdd-cuenta-en-mesa.md; cómo escribir, proteger, revisar y rotar las pegatinas, endocs/pegatinas.md.
La diferencia entre v1.0 y v2.0 no es cosmética: el plan original dejaba explícitamente fuera de alcance un backend real y la autenticación (ver v1.0, sección 02). La operación real con varios dispositivos en simultáneo hizo necesario sumar ambas cosas. Este documento describe lo que realmente existe hoy en pos.html, no el plan original.
Contenidos
- Introducción
- Alcance
- Stack tecnológico
- Arquitectura
- Sistema de diseño
- Entidades del dominio
- Seguridad y autenticación
- Contrato de datos
- Flujos principales
- Sincronización multi-dispositivo
- Incidentes resueltos
- Fases de desarrollo
- Decisiones fijas
- Estructura del HTML
- Componentes
- Checklist de producción
01 — Introducción
¿Qué es hoy Resplandor POS?
Una aplicación web táctil, single-file (pos.html, sin build step), que gestiona el flujo completo de un turno de restaurante: login del personal, mapa de mesas, toma de pedidos, facturación y cierre diario — sincronizado en tiempo real entre todos los dispositivos del local (tablets de meseros, caja, administración).
A diferencia del plan original, la persistencia no es solo localStorage: es un modelo híbrido donde localStorage actúa como caché de lectura instantánea y cola de escritura, y Supabase (Postgres) es la fuente de verdad remota, sincronizada por Realtime.
Principio rector actualizado: el cliente sigue siendo la capa de interacción (Alpine.js, sin framework pesado), pero la verdad de los datos vive en Supabase. El single-file HTML no significa "sin backend" — significa "sin build step ni servidor propio que mantener".
02 — Alcance
Qué entra y qué no (actualizado a v2.0)
✅ En producción
- Login obligatorio con Google (Supabase Auth) — toda la app está detrás de este gate
- Mapa de mesas con estado libre/ocupada, sincronizado en tiempo real
- Apertura y asignación de orden por mesa, protegida contra duplicados por condición de carrera
- Catálogo de productos (CRUD) con categorías
- Agregar ítems de menú e ítems manuales a una orden abierta
- Facturación: cálculo de total + ticket imprimible
- Cierre diario: total ventas + historial de cierres, con reintentos automáticos si falla la subida
- Realtime Presence: saber qué otro dispositivo/persona tiene abierta la misma mesa ahora mismo
- Persistencia híbrida:
localStorage(caché + cola offline) + Supabase (verdad remota) - Seguridad a nivel de base de datos (RLS): sin login, cero acceso a ningún dato
- Responsive: tablet ≥ 768px + desktop
❌ Todavía fuera de alcance
- Roles diferenciados (admin vs. mesero) — la compuerta de personal ya está al aire (solo entra quien esté en
personal; hoy, un admin); los permisos por rol y el modelo de aprobación (quien entra pide acceso y un admin lo aprueba) están listos en ramas y probados en local, sin aplicar (ver §07) - Alertas de «pedir la cuenta» en el POS, y el cobro por monto y por unidades de una línea (ola B, en ramas)
- Panel de Mesas y pegatinas (crear y editar mesas, escribir y revisar la pegatina NFC), ajustes del ticket (QR y pie) y deshacer un cobro (parcial, abono o la mesa completa; sin ventana de tiempo; ola C, en ramas)
- Imprimir en la térmica de la caja desde cualquier celular (cola de impresión en Supabase + un agente en el PC de la caja) — listo en ramas y probado de punta a punta en local, sin aplicar en producción (ver §07, «Imprimir en la caja»)
- Fotos de producto (Supabase Storage) — próxima fase
- Resumen de cierre generado con IA — próxima fase
- Inventario con control de stock
- Comandas en cocina (Kitchen Display)
- Facturación electrónica (DIAN)
- Multi-restaurante / multi-sucursal
03 — Stack tecnológico
| Tecnología | Rol |
|---|---|
| HTML5 + Alpine.js v3 | Estructura y reactividad declarativa, sin build step |
| Tailwind CSS (Play, 3.4.17, local) | Utilidades + design tokens; compila en el navegador desde assets/vendor/ |
| Lucide Icons (1.49.0, local) | SVG íconos desde assets/vendor/ |
| Fraunces + DM Sans | Tipografía display / body (Google Fonts) |
| Supabase Postgres | Fuente de verdad remota (productos, mesas, ordenes, cierres) |
| Supabase Realtime — Postgres Changes | Sincroniza cambios de fila entre dispositivos |
| Supabase Realtime — Presence | Quién tiene abierta cada mesa, en vivo, sin tocar Postgres |
| Supabase Auth (Google OAuth) | Login obligatorio, única puerta de entrada a la app |
| Row Level Security (RLS) | Control de acceso real — reemplaza la confianza en el secreto de la anon key |
| localStorage | Caché de lectura + cola de sincronización offline |
| window.print() | Ticket imprimible |
Librería de QR chica (ola C; qrcode-generator 1.4.4, MIT, 56 KB sin minificar, archivo local en assets/vendor/: el qrcode.js del paquete de npm, verificado contra npm y contra lo que publica cdnjs) | Dibuja en el navegador el QR del ticket a partir de ajustes.ticket_qr_url. Si no carga, el ticket sale sin QR, nunca roto |
Web NFC (NDEFReader) (ola C, solo Chrome para Android, HTTPS y con un toque del usuario) | Escribir y revisar la pegatina de cada mesa desde el POS (docs/pegatinas.md) |
¿Por qué se sumó Supabase si el plan decía "sin backend"?
El plan v1.0 asumía un solo dispositivo por turno. En la práctica, un restaurante tiene varios meseros con tablets simultáneas — sin una fuente de verdad remota y sincronización en tiempo real, dos meseros facturando la misma mesa es un riesgo real de negocio, no un detalle técnico. Supabase se eligió porque no rompe la regla de "cero build step": todo se consume por HTTP/WebSocket desde el mismo pos.html, sin bundler ni servidor propio.
04 — Arquitectura
Capas (actualizado)
| Capa | Responsabilidad | Implementación |
|---|---|---|
| Config | Design tokens, Tailwind config, credenciales de Supabase (anon key) | <script> al inicio del <head> |
| Store | Estado global reactivo + sesión de usuario + presencia | Alpine.store('pos', {...}) |
| Auth gate | Bloquea toda la UI hasta que exista sesión de Google | Contenedor x-show="$store.pos.usuario" que envuelve nav + vistas + modales |
| Components | Bloques HTML con x-data local | Secciones comentadas en <body> |
| Services | Mapeo camelCase ↔ snake_case, cálculo de totales, sync | Funciones dentro del store (parseX / formatX) |
| Persistence local | Caché de lectura + cola de reintentos | localStorage (pos_mesas, pos_ordenes, pos_productos, pos_cierres, pos_device_id) |
| Persistence remota | Verdad de negocio | Supabase Postgres, protegido por RLS |
| Realtime | Sincronización viva | Canal pos_sync (postgres_changes) + canal presencia_pos (Presence) |
Principios de diseño (vigentes)
- Separación Store / UI — el Alpine store sigue siendo la única fuente de verdad del cliente; los componentes solo leen y llaman métodos del store.
- Boundary camelCase ↔ snake_case — el store y los templates usan camelCase (
mesaId,abiertaEn); Supabase usa snake_case (mesa_id,abierta_en). La traducción pasa siempre porparseOrden()/formatOrden()(y equivalentes para producto/cierre). Este boundary se rompió en 5 lugares del template durante el desarrollo (ver sección 11) — si tocas templates que muestran datos de una orden, usa siempre los nombres camelCase del objeto ya parseado, nunca los de la columna de Postgres. - Fire-and-forget está prohibido — toda escritura a Supabase (
pushASupabase) tienetry/catch; todo handler de Realtime también. - La UI nunca confía en el estado local para decisiones de concurrencia — desde el incidente de mesas duplicadas, la base de datos (no el cliente) es quien arbitra condiciones de carrera (ver sección 10).
La versión del sitio
Qué es. Una sola versión para todo el sitio, AAAA.MM.DD-xxxxxxx, que sale del contenido (no de un contador que alguien tenga que subir): version.json en la raíz guarda { "version", "fecha", "huella" }. La huella es el sha256 de las cuatro páginas que llevan sello (pos.html, carta.html, index.html, menu.html) y de todo assets/** (ruta + contenido, en orden estable), con los sellos de versión normalizados (si no, escribir el sello cambiaría lo que se está hasheando). La fecha es la del día del cambio en America/Bogota (explícita: no depende de la zona de la máquina ni de CI) y xxxxxxx son los 7 primeros de la huella. Si la huella no cambió, el script no toca nada: la fecha no se mueve. Cambiar img/, docs/, el README o los archivos de descubrimiento (local.json, llms.txt…) no cambia la versión: no son del código que corre en el aparato.
Los sellos. Cada una de las cuatro páginas lleva la versión en dos sitios, cada uno en su propia línea: <meta name="resplandor-version" content="…"> en el <head> (lo que lee el POS) y <span data-version>…</span> en el pie, junto a la firma «Ynt-labs» (la marca de lusof, sin «Hecho por»: Yonatan, 2026-10-03), visible sin JavaScript. En el POS el pie va al final del área de trabajo y en el login; tocar la versión busca una nueva en el momento.
Por qué existe. GitHub Pages responde con Cache-Control: max-age=600 y el sitio no tiene service worker, así que un aparato con el POS abierto todo el día nunca se enteraba de que había versión nueva (2026-10-02: se vio en un aparato el POS «de antes», con «Facturar» e «Imprimir cuenta», horas después de publicar). Solo el POS lleva el aviso; carta, landing y menú son de clientes y de visitas cortas.
El aviso del POS (pos.html, «Versión del sitio» en el store):
-
Pide
version.json?t=<ms>concache: "no-store"al arrancar (también en la pantalla de login), cada 5 minutos, al volver a la pestaña y al volver la red. Sin red o con un error, en silencio; solo al tocar la versión del pie se le dice a la persona qué pasó. -
Si lo publicado es distinto del
<meta>de la página, sale una franja tranquila arriba de todo, en el flujo (no tapa el encabezado, ni la barra de cobro, ni la navegación de abajo): «Hay una versión nueva del POS» con «Recargar» y «Después». «Después» la esconde hasta que salga otra versión o pase 1 hora. -
«Recargar» refresca la caché HTTP del documento y de los
<script src>y<link rel="stylesheet">del mismo origen (fetch(url, { cache: "reload" })) y recién entonces llama alocation.reload(): sin eso, el reload podía volver a pintar la página vieja desde los 10 minutos de caché. Recargar es siempre un toque de la persona, nunca automático: si tras recargar la página sigue vieja (un CDN atrasado), el aviso vuelve a salir y se puede intentar otra vez; no hay bucles. Y solo recarga si recargar es seguro, en este orden (refutación de la integración con «para llevar», tres rondas):- Primero espera lo que solo vive en memoria (un «+1» cuyo delta sigue en vuelo, una marca «Para llevar» que la base aún no confirmó, una fila que se está subiendo, un papel que viaja a la caja —el ticket de un cobro: mientras el insert está en vuelo solo vive en memoria y recargar encima se lo llevaba, sin ticket en la caja ni en el teléfono—): no está en la cola ni en el almacenamiento y la recarga lo perdía. Espera hasta ~5 s y reintenta ya las marcas que esperaban su reloj de reintento; no adelanta la que todavía espera el «+1» de su línea (la nota llegaría antes que la línea y esta nacería sin la marca). Si no llega, no recarga. Un ticket sin resolver (su aviso dice «No hubo respuesta de la caja» o «error» y guarda la orden confirmada para imprimirla desde el teléfono, solo en memoria) cuenta como «algo empezado» (punto 4): la recarga no se hace sola.
- Después mira la red y baja el documento nuevo, y recarga enseguida solo si bajó entero. La descarga va después de la espera a propósito: con la descarga antes, si la red se caía mientras esperaba, la subida en vuelo fallaba y quedaba en la cola, la espera terminaba «bien» y recargar sin internet dejaba al POS en la página de error del navegador (
ERR_INTERNET_DISCONNECTED), sin pantalla, siendo un POS que sí trabaja sin red. Si la cuenta se movió mientras bajaba (con poca red son segundos), vuelve a esperar y a bajar (hasta 3 descargas). Y como los scripts y hojas se refrescan después del documento y pueden tardar, una mirada diminuta aversion.jsoncierra esa espera; entre la última prueba de red ylocation.reload()no queda más que la cola de microtareas. - Una red lenta no es una red caída, y la descarga se corta por inactividad, no por reloj. El documento baja solo (con todo el ancho de la conexión; pedido junto a los scripts, por debajo de ~90 KB/s no terminaba nunca) y se lee por partes, con un
reader: se abandona si ni las cabeceras llegan en 10 s (no hay red: «¿sin internet?») o si, ya contestado, pasan 15 s sin un solo byte del cuerpo («la descarga se detuvo»). Mientras lleguen bytes se sigue, tarde lo que tarde: un tope fijo de 30 s desde el pedido cortaba una descarga que avanzaba y, por debajo de ~7 KB/s reales, «Recargar» no recargaba nunca (y cada toque empezaba de cero, porquecache: "reload"no reusa lo ya bajado). Solo una red de seguridad de 5 minutos la corta aunque avance («la conexión está muy lenta»). Los scripts y hojas del mismo origen son de mejor esfuerzo (20 s): su tope no impide recargar si el documento ya bajó. - Mientras prepara, la persona decide (y nunca se recarga encima de lo que empezó). Con una red lenta preparar tarda decenas de segundos y el POS no se bloquea: la persona sigue trabajando. La franja dice «Descargando la versión nueva…» y ofrece «Cancelar» (en lugar de «Después», desde el toque en «Recargar», también mientras espera lo pendiente), que lo aborta todo —la espera y las descargas, con un
AbortController— y deja la franja como estaba: nada queda deshabilitado sin salida. Al terminar de bajar, recarga en el acto solo si la persona no hizo nada desde el toque: ni un toque ni una tecla fuera de la franja, ningún diálogo abierto, la misma vista. Si hizo algo, no recarga: la franja pasa a «La versión nueva está lista» con «Recargar ahora» y «Después», y espera su toque (con un diálogo abierto la franja queda debajo del velo: se ve al cerrarlo). «Recargar ahora» es inmediato —la caché ya está caliente, no baja nada otra vez—, pero sigue esperando lo pendiente (el punto 1) y mirando la red justo antes delocation.reload()(el punto 2). «Lista» vale solo para la versión que bajó: si sale otra, vuelve el aviso de siempre con su «Recargar», que baja de nuevo.
Sin red no recarga (también si el documento no se pudo descargar ahora mismo: wifi sin salida, un error del servidor). En todos los casos de «no» el POS sigue como estaba, el botón queda libre y la franja dice por qué («Sin conexión…», «No pude descargar la versión nueva…», «La descarga de la versión nueva se detuvo…», «Todavía se está guardando lo último de la cuenta…», «La cuenta siguió cambiando…», y —solo con «Recargar ahora»— «Hay un ticket sin imprimir: recargar borraría su aviso…» (un ticket «dudoso», en error o con la caja callada guarda en memoria la única copia de la orden cobrada: recargar se la llevaría; se imprime desde el teléfono o se cierra con la ✕ y se vuelve a tocar), 12 s; «Recargar ahora» sin red lo dice con sus palabras y la versión sigue «lista»).
-
Qué se pierde al recargar y por qué el aviso no interrumpe. Sobreviven la sesión de Supabase y la caché local (
pos_mesas,pos_ordenes, …) y, sobre todo, la cola de reintentos (pos_delta_queue,pos_pendientes), que se vacía sola al arrancar. Se pierde lo que solo vive en memoria y no es una subida en camino: la vista abierta (se vuelve a Mesas), un nombre a medio escribir, un diálogo de cobro abierto, el «Deshacer» del último cobro, y el interruptor «Agregar para llevar». (Las subidas en camino sí se esperan: ver arriba.) Por eso el aviso es una franja y no un diálogo, no recarga solo y no bloquea nada: la persona elige cuándo, entre una mesa y otra. Y por eso, si la persona hace algo mientras baja la versión nueva, «Recargar» no la recarga sola: la deja «lista» (punto 4).
Cómo se mantiene. node scripts/version.mjs se corre AL FINAL, después de scripts/css.mjs, scripts/iconos.mjs y scripts/descubrimiento.mjs (su huella incluye assets/css/resplandor.css y lo que ellos reescriben en las páginas), en cada cambio de páginas o de assets, y se commitea version.json junto con las cuatro páginas. node scripts/version.mjs --comprobar (paso del workflow comprobar.yml, y scripts/pruebas/version.test.mjs) sale con 1 si version.json o algún sello no corresponde, y dice qué correr.
descubrimiento.mjs no lee la versión (desde 2026-10-04): el <lastmod> del sitemap y del schemamap y el last-updated de los .md gemelos son una fecha por página —el día en que cambió el contenido de ESA página—, guardada junto con la huella de la página en scripts/fechas-paginas.json. Un cambio solo del POS (o solo del sello de versión) no mueve ninguna, así que no hay segunda corrida de descubrimiento.mjs después de version.mjs: el orden es css, iconos, descubrimiento, version, y listo. Si dos ramas tocan páginas distintas, sus fechas no chocan; si tocan la misma, hay marcas de conflicto en scripts/fechas-paginas.json: se resuelven (cualquier lado) y se regenera con node scripts/descubrimiento.mjs. Con marcas sin resolver (o con un archivo roto) el generador se niega (sale 1, no escribe nada, también con --comprobar): no lo toma por vacío, que llevaría a hoy las fechas de todas las páginas. Por qué no la fecha de version.json ni la de git: docs/landing-y-agentes.md, «Fechas de las páginas».
Si dos ramas chocan en version.json (las dos cambiaron páginas o assets, así que las dos reescribieron la versión y los sellos), no hay nada que decidir: resuelve el conflicto dejando cualquiera de los dos lados (los sellos son una línea cada uno) y vuelve a correr node scripts/version.mjs; la versión se recalcula del contenido ya mezclado. Con marcas de conflicto sin resolver en una página, el script se niega a sellar y lo dice.
05 — Sistema de diseño
El POS usa desde el 2026-09-30 la identidad v2 de la landing («El letrero abre el salón»): barra y login en telón, área de trabajo en arroz, tarjetas en papel; Cinzel para marca y títulos, Archivo para texto, botones, precios y totales. Esta sección ya no lista tokens, porque la paleta que había aquí (--ember #B5341C, Fraunces + DM Sans) quedó obsoleta.
- Tokens, tipografía y contratos de color:
docs/identidad-visual.md. La única fuente de los 15 tokens esassets/css/base.css. - Cómo se aplica al POS (mapa de lo viejo a lo nuevo, recetas de componentes, medidas táctiles, restricciones y verificación):
docs/pos-visual.md. - Dónde vive en
pos.html: un solo<style>con los 15 tokens copiados, alias temporales de la v1 y un bloque CSS por parte;pos.htmlconserva su Tailwind CDN y no cargaresplandor.css.scripts/pruebas/pos-visual.test.mjsvigila que los tokens sigan siendo los debase.css.
06 — Entidades del dominio
Mesa
| Campo (Postgres) | Campo (store, camelCase) | Tipo |
|---|---|---|
id | id | PK, integer |
capacidad | capacidad | number |
estado | estado | 'libre' | 'ocupada' |
updated_at | — | timestamptz |
token | token | text, 48 caracteres hexadecimales: la llave del enlace de la pegatina (§07). Solo un admin lo cambia (trg_mesas_token_solo_admin) |
activa (ola C) | activa | boolean, por defecto true. false = fuera de servicio: no sale en el mapa del salón, su enlace responde «inválido» y no se le puede avisar. Una mesa no se borra (tiene historial de cuentas): se desactiva, y no se puede desactivar con una cuenta abierta |
pegatina_escrita_en, pegatina_revisada_en (ola C) | escritaEn, revisadaEn | timestamptz | null: cuándo se escribió y cuándo se revisó por última vez la pegatina de la mesa (pegatina_marcar) |
Producto
| Campo (Postgres) | Campo (store) | Tipo |
|---|---|---|
id | id | PK, text |
categoria | cat | string |
nombre | nombre | string |
precio | precio | number |
descripcion | desc | string |
activo | activo | boolean |
etiqueta | — (el POS no la toca) | text | null, de 1 a 40 caracteres: nota corta que la carta pública muestra como pastilla («Incluye jugo», «Algunos fines de semana», «2 x 1», «20% OFF»). Migración 20261003130000. |
dia_semana | — (el POS no la toca) | smallint | null, 1 (lunes) a 7 (domingo): solo para las promociones. Migración 20261003130000. |
Orden
| Campo (Postgres) | Campo (store) | Tipo |
|---|---|---|
id | id | PK, text |
mesa_id | mesaId | number |
estado | estado | 'abierta' | 'cerrada' |
items | items | jsonb → OrdenItem[] |
total | total | numeric |
abierta_en | abiertaEn | timestamptz |
cerrada_en | cerradaEn | timestamptz | null |
parcial_de (ola C) | parcialDe | text | null: el id de la orden abierta de la que salió este cobro parcial o abono. Lo escribe la base al crear la orden cerrada (cobrar_parcial y cobrar_abono; el POS de antes lo mandaba en un upsert) y es lo que permite deshacer el cobro (§07, «Deshacer un cobro»). No cambia por UPDATE (lo conserva el disparador trg_ordenes_guardia, también para el admin: un mesero que cierra una cuenta suya con un parcial_de inventado no engaña a deshacer_cobro) y se pone en null al reabrir o editar esa venta |
version | version | integer: sube con cada cambio de los ítems (aplicar_delta_orden, cobrar_parcial, cobrar_abono, deshacer_cobro y, sin pedirlo, cualquier UPDATE que cambie items). El cobro por partes y el abono mandan la version que la tablet vio (p_version): si la base ya tiene otra, RS003. Cobrar la mesa manda la version que la tablet vio: si la base ya tiene otra, rechaza el cierre (RS003) y el POS avisa «La cuenta cambió, revísala» y la vuelve a leer (§07, «Cerrar con lo que se vio») |
servida_en (20261006160000, aún no al aire) | servidaEn | timestamptz | null: cuándo se sirvió la comida de la mesa (el cronómetro de espera del POS se detiene ahí; ver «Cronómetro de la mesa y «servida»»). No es un ítem: no sube la version. La escribe el POS con un update directo de esta columna a una cuenta abierta, nunca con el upsert de la fila; sin la columna (PGRST204 / 42703) el POS esconde el toque «servida». En el store solo existe la clave cuando hay marca |
Solo en la tablet (no es una columna): subida (boolean) marca la cuenta que viene de la base o que esta tablet ya subió una vez (parseOrden, _marcarSubida); una cuenta abierta sin red que jamás subió no la trae, y es la única cuya venta cerrada puede INSERTARSE sin que la lectura previa la dé por borrada («Una cuenta que la base ya no tiene no se cobra»).
Un OrdenItem puede llevar precio_manual: true y precio_por (correo de quien puso el precio a mano, atribución que pone la RPC y no un dato a prueba de falsificación): la base no refresca esa línea desde productos (ver «Precio a mano por línea del pedido»).
Un OrdenItem de precio negativo es un abono: un cobro por monto («Cobrar por partes → monto», ola B). La orden cerrada «Abono · Mesa N» lleva el cobro y la orden abierta recibe una línea «Abono recibido» con precio negativo (abono_recibido_<uid>, precio = −monto, qty 1; las dos las pone cobrar_abono en la misma transacción), así que su total es lo que queda por pagar. La carta pública (carta.html) la muestra como abono, con signo menos, y no como un producto (docs/sdd-cuenta-en-mesa.md §03.5 y §04.7).
«Para llevar» (2026-10-02; sin migración; diseño y tabla de decisiones en docs/para-llevar.md): opcional, por producto y para el pedido completo. Por producto: el token Para llevar al final de la base de la nota de la línea, separado por · («Sopa · Pollo · Para llevar — Persona 2 (Camila)»); se alterna con actualizar_nota_item, marca la línea entera y conserva persona y variante. Pedido completo: un OrdenItem de $0 con id fijo para_llevar (nombre «Para llevar», nota «Todo el pedido», cantidad 1), puesto y quitado con aplicar_delta_orden; no es un producto: no cuenta en «N ítem(s)», ni en dividir por persona, ni en cobros por unidades o abonos, y una cuenta que solo lo tiene no se cobra (sí se libera). Los tickets, la precuenta y el papel de la caja lo dicen («PARA LLEVAR — todo el pedido»), y la carta del cliente lo muestra como etiqueta.
Restricción a nivel de base de datos (nueva, ver sección 11): índice único parcial ux_ordenes_una_abierta_por_mesa (mesa_id) WHERE estado = 'abierta' — garantiza que nunca exista más de una orden abierta por mesa, sin importar cuántos dispositivos intenten abrirla a la vez.
CierreDiario
| Campo (Postgres) | Campo (store) | Tipo |
|---|---|---|
id | id | PK, text |
fecha | fecha | timestamptz |
total_ventas | total | numeric |
total_ordenes | — (se calcula de ordenes.length) | integer |
transacciones | ordenes | jsonb → Orden[] (guardadas ya en camelCase) |
Usuario / Sesión (nuevo en v2.0)
No es una tabla propia: la sesión vive en Supabase Auth, poblada por el proveedor Google OAuth. El store expone:
usuario // objeto de sesión de Supabase Auth, o null si no hay login
nombreUsuario // getter: user_metadata.full_name || email
avatarUsuario // getter: user_metadata.avatar_url
Con la ola B, tras el login el POS pregunta su rol a la base (mi_rol()) y el store suma esAdmin y tieneAcceso; una cuenta sin fila activa en personal ve «Tu cuenta no está habilitada» y no carga nada. Con la ola C, antes de eso el POS llama a solicitar_acceso(): quien entra con Google y no está en personal queda como pendiente y ve una pantalla de solo lectura (estadoAcceso, §07, «Modelo de aprobación»).
Personal (la tabla y la compuerta ya están al aire; los permisos por rol y la aprobación, no)
Quién entra al POS y con qué rol. Una fila por correo de Google, en minúsculas. La baja es lógica.
| Campo (Postgres) | Tipo |
|---|---|
email | PK, text, minúsculas y con forma de correo |
nombre | text, hasta 80 caracteres |
rol | 'admin' | 'mesero' (el de un pendiente es provisional: 'mesero' hasta que un admin lo apruebe) |
activo | boolean (la baja es false; la fila no se borra) |
estado (ola C) | 'pendiente' | 'aprobado', por defecto 'aprobado': las filas que ya existían quedan aprobadas |
solicitado_en (ola C) | timestamptz: cuándo pidió acceso, si lo pidió él mismo |
Se escribe con las RPC personal_alta, personal_baja y personal_cambiar_rol (solo admin) y, desde la ola C, personal_aprobar y personal_eliminar (solo admin); la única fila que alguien crea por su cuenta es la suya, pendiente, con solicitar_acceso(). El admin ve a todos (los pendientes también) y cada quien ve su propia fila. Los correos reales nunca van en el repo (es público): el alta inicial la pega Yonatan en el SQL Editor.
Alerta (ola B, aún no al aire)
El aviso «esta mesa pidió la cuenta»: el cliente elige QR, transferencia o efectivo y eso no cobra nada, solo avisa al personal.
| Campo (Postgres) | Tipo |
|---|---|
id | PK, uuid |
mesa_id, orden_id | la mesa y la orden abierta a la que se avisó |
tipo | 'pedir_cuenta' |
metodo | 'qr' | 'transferencia' | 'efectivo' |
estado | 'pendiente' | 'atendida' | 'descartada' |
creada_en, atendida_en | timestamptz |
atendida_por | correo de quien la atendió (o sistema si se cerró sola al facturar o liberar la mesa) |
Una sola alerta pendiente por mesa (índice único parcial): un segundo toque cambia el método y la hora. La crea solo service_role (la Edge Function alerta) y la atiende el personal con atender_alerta o descartar_alerta. Retención (ola C, D28): una alerta que ya no está pendiente (atendida o descartada) se borra un día después, porque guarda el correo de quien la atendió; las pendientes no se borran solas.
Ajustes (ola C, aún no al aire)
Cómo sale el ticket impreso. Una sola fila (id = 1).
| Campo (Postgres) | Campo (store) | Tipo |
|---|---|---|
ticket_qr_url | ticketQrUrl | text, por defecto https://resplandor.ynt.codes/; debe empezar por https:// y tener hasta 200 caracteres |
ticket_qr_visible | ticketQrVisible | boolean, por defecto true |
ticket_pie | ticketPie | text, por defecto «Gracias por su visita», hasta 120 caracteres |
actualizado_en, actualizado_por | — | quién y cuándo lo cambió |
La lee todo el personal aprobado y solo la escribe un admin (nadie inserta ni borra la fila). Sin la tabla, el POS usa esos mismos valores por defecto.
Impresora e impresión (cola de impresión, aún no al aire)
El PC de la caja es una impresora; cada ticket que un teléfono manda a la caja es una impresión en cola. El token del agente solo se guarda como hash.
| Campo (Postgres) | Tipo |
|---|---|
impresoras.id, nombre | uuid y el nombre que le pone el admin («Caja») |
impresoras.token_hash | sha256 en hex del token del agente; ningún rol de la API puede leerlo (permiso por columna) |
impresoras.activa, ultimo_latido, version_agente | el agente late cada 30 s; en línea = último latido de menos de 90 s |
impresiones.id | PK, uuid que pone el teléfono (un reintento sin red da 23505 y no sale otra copia) |
impresiones.impresora_id | la impresora destino (null = la toma cualquiera de las activas) |
impresiones.tipo | 'cuenta' | 'ticket' | 'abono' | 'cierre' | 'prueba' |
impresiones.contenido | jsonb: el documento ya armado por el POS ({v, titulo, lineas[], qr, cortar}, máximo 32 KB y 500 líneas); el agente no confía en él y filtra los bytes de control |
impresiones.estado, intentos, error | 'pendiente' | 'imprimiendo' | 'impresa' | 'error'; hasta 3 intentos; lo que lleva más de 15 min sin imprimirse (sin tomar, o tomado y trabado) pasa a error («caducó») |
impresiones.creada_por, creada_en, tomada_en, impresa_en, tomada_por | quién lo pidió (lo pone la base) y los tiempos |
Las impresiones impresas o fallidas de más de 7 días se borran solas. El personal las ve y las crea (tope de 30 por minuto y por persona, RS030); nadie las edita ni las borra por la API.
Presencia (nuevo en v2.0 — no persiste en Postgres)
Vive solo mientras dura la conexión Realtime de cada pestaña/dispositivo, en el canal presencia_pos:
{ mesaId: number | null, deviceId: string, nombre: string, ts: number }
deviceId es estable por navegador (localStorage.pos_device_id), no por persona — dos pestañas del mismo navegador comparten identidad de presencia.
07 — Seguridad y autenticación
Modelo de acceso
Toda la app está detrás de un gate: sin sesión de Google activa, no se renderiza absolutamente nada (ni el mapa de mesas, ni el catálogo). Esto se refuerza a dos niveles, porque uno solo no basta:
| Nivel | Qué protege | Cómo |
|---|---|---|
| Cliente (UX) | Qué ve el usuario | <div x-show="$store.pos.usuario"> envuelve nav + vistas + modales |
| Base de datos (real) | Qué puede leer/escribir cualquiera con la anon key, sin pasar por la UI | Row Level Security: las 4 tablas (productos, mesas, ordenes, cierres) solo tienen policies para el rol authenticated. Cero policies para anon. |
El nivel de cliente es cosmético — cualquiera puede leer la anon key desde "Ver código fuente" y llamar a la API REST de Supabase directamente. La única protección real es RLS. Este proyecto tuvo, por un tiempo, exactamente ese hueco (ver sección 11) — no vuelvas a dejar una tabla con policy para
anonsin una razón explícita y documentada aquí.
Flujo de login
init()resuelve la sesión existente (supabaseClient.auth.getSession()).- Si no hay sesión, se muestra la pantalla de login; la app real (caché, sync, Realtime, presencia) no arranca hasta que hay usuario.
- Al autenticarse,
onAuthStateChangedisparaarrancarApp()— con guarda propia (_appArrancada) para no duplicar suscripciones de Realtime si el evento de auth se dispara más de una vez. - El nombre y avatar de Google se usan también en Presence, así que "quién tiene la mesa abierta" muestra un nombre real, no un dispositivo anónimo.
- Ola C: antes de preguntar el rol, el POS llama a
solicitar_acceso(). Quien ya está enpersonaly aprobado sigue de largo; quien no está queda pendiente y ve una pantalla de solo lectura hasta que un admin lo apruebe (§07, «Modelo de aprobación del personal»).
Modelo de acceso por roles (ola B: listo en ramas, no está al aire)
El hueco de hoy. La policy restrictiva solo_google solo mira que la sesión venga de Google (supabase/migrations/20260905000000_resplandor_base.sql). Mientras el proyecto de Google Cloud esté en modo «Testing», eso se contiene con la lista de usuarios de prueba; pero cualquier cuenta de Google que pase el login lee las ventas y los tokens de las mesas, y si se publica la app, cualquier Gmail entra. Los roles cierran ese hueco y además reparten lo que puede hacer cada persona. Diseño completo, decisiones y pruebas de humo: docs/sdd-cuenta-en-mesa.md §02.
Las piezas (tres migraciones, de la rama tarea/roles-alertas-bd, cada una sale a su hora; nada de esto está aplicado en lccgehvyymladqvumcez):
| Pieza | Qué hace |
|---|---|
Tabla personal | Quién entra y con qué rol (admin o mesero). Una fila por correo de Google; la baja es lógica (activo = false). Se crea vacía: el alta inicial va en un SQL aparte, fuera del repo |
mi_correo() y mi_rol() | El rol de quien llama, o null. Se reconoce a la persona por su identidad de Google (auth.identities), no por el correo de auth.users, que el usuario puede cambiar; una cuenta con contraseña y el correo de un admin no hereda su rol. Se consulta en cada petición: una baja surte efecto en la siguiente consulta, no cuando vence la sesión |
La compuerta solo_personal | Policy restrictiva que reemplaza a solo_google: Google y fila activa en personal. Cubre productos, mesas, ordenes, cierres, sugerencias_plato y alertas; en menus solo las escrituras, porque la votación pública (menu.html) lee menus como anon. Sin fila activa no hay acceso, con o sin Google |
personal_alta, personal_baja, personal_cambiar_rol | Gestión del personal, solo admin, con ultimo_admin si la operación dejaría el sistema sin admins. El POS las llama desde la vista «Personal» |
| Permisos por rol | Policies por tabla y operación, con mi_rol() (tabla de abajo). El GRANT no cambia; cambia quién puede |
alertas, atender_alerta, descartar_alerta, alertar_cuenta | Las alertas de «pedir la cuenta». alertar_cuenta solo la ejecuta service_role (la Edge Function alerta); las otras dos, el personal |
Qué hace cada rol. Esconder en la interfaz es una comodidad; la regla real la pone la base: lo que un mesero no puede, la base lo rechaza aunque llame a la API a mano (con 42501 si es un insert, y en silencio, con 0 filas, si es editar o borrar; por eso el POS de la ola B tiene que esconderlo antes de aplicar los permisos). Una salvedad, en la nota ¹. Las filas marcadas «ola C» son de la ola C (secciones siguientes).
| Capacidad | Mesero | Admin |
|---|---|---|
| Entrar al POS | Con fila activa | Con fila activa |
| Ver mesas, órdenes, productos, menús, ventas del día y historial de cierres | Sí (los cierres, en solo lectura) | Sí |
| Abrir mesa, agregar y quitar ítems, «Ítem manual», editar la mesa, notas y «Persona N» | Sí | Sí |
| Cobrar y cerrar («Generar ticket y cobrar», el único botón de cobro), cobro por partes (por ítems, por unidades de una línea o por monto; una cuenta con promoción no se parte por ítems ni por persona: se cobra completa o con abonos, ver «Precio vivo y promociones como regla»), cuenta dividida por persona con nombre (con su «Precuenta» y su «Cobrar» en cada fila), «Imprimir precuenta» (no cobra; imprimir va siempre a la caja, con una confirmación: ver §07, «Imprimir en la caja»), liberar una mesa vacía (abierta y sin ítems) | Sí | Sí |
| Reabrir, editar o eliminar una orden cerrada (una venta del turno o de un cierre pasado) | No | Sí |
| Ver, atender y descartar alertas | Sí | Sí |
| Crear y editar productos (catálogo y precios) | Sí | Sí |
| Borrar productos | No | Sí |
| Programar el menú semanal y leer las sugerencias de platos | No | Sí |
Cierre del día (escribir en cierres) | No | Sí |
| Rotar el token de la pegatina de una mesa | No ¹ | Sí |
| Gestionar el personal: alta, baja, rol | No | Sí |
| Aprobar o eliminar personal y ver las solicitudes pendientes (ola C) | No | Sí |
| Mesas y pegatinas: crear y editar mesas, desactivarlas, escribir y revisar la pegatina (ola C) | No | Sí |
| Ajustes del ticket: dirección del QR, QR visible y pie (ola C) | No (el ticket impreso sí lo usa) | Sí |
| Tablero de Administración (ola C, ronda 5): la entrada del menú y sus tarjetas | No | Sí |
| Deshacer un cobro (ola C): un parcial, un abono o la mesa completa | Sí, en cualquier momento mientras el cobro siga en el turno (sin ventana de tiempo) | Sí, en cualquier momento |
| Ver «Cobros deshechos hoy» en el cierre del día (quién, mesa, monto y hora; ola C) | No | Sí |
¹ La rotación del token la impide la base, sin lanzar error. El POS guarda las mesas con upsert y un permiso por columna no sirve (mesero y admin son el mismo rol de Postgres), así que la policy deja que cualquier persona del personal edite mesas. Lo que lo frena es trg_mesas_token_solo_admin (en permisos_por_rol, desde la ronda 2 de la ola B): un BEFORE UPDATE que conserva el token viejo si quien lo cambia no es admin, sin romper el upsert de un mesero. Por eso el cambio de token de un mesero no falla: simplemente no cambia. También impide la base renumerar una mesa (solo admin).
- Caja = admin. No hay un tercer rol: el cierre del día y los cierres pasados son del admin (decisión de Yonatan, 2026-09-30). Si algún día hay un cajero que no deba tocar catálogo, menú ni personal, se agrega
'caja'alcheckdepersonal.rol. - El mesero sí crea y edita productos (decisión de Yonatan, 2026-09-30): INSERT y UPDATE en
productos, también elupsertdel POS. Borrar sigue siendo del admin. Lo que un mesero cambie en el catálogo sale en la carta pública (carta_publica), la landing y el MCP. - El mesero ve las ventas del día y el historial de cierres, en solo lectura (D29). Escribir en
cierreses solo del admin. - Sin propina: ni la carta, ni el POS, ni el ticket, ni el cierre la piden, la sugieren o la registran (decisión de Yonatan, 2026-09-30).
- Nunca cero admins: la baja o el cambio de rol que dejaría la tabla sin un admin activo se rechaza.
Arranque seguro: el orden en que sale al aire (todo con el GO de Yonatan y fuera del horario de servicio; el detalle y las reversas, en el SDD §02.5, §08 y §12.9):
- La compuerta (
20261002120000_personal_y_compuerta.sql) junto con el alta inicial. Ya está aplicada (2026-09-30, de noche), con Yonatan como único admin ymi_rol()verificado. La migración se niega a correr (y no toca una sola policy) si no queda al menos un admin con una cuenta de Google real; quien no esté dado de alta queda afuera al instante, y por eso Camila y los meseros esperan el paso 3. Reversa en menos de un minuto: la cabecera de la migración vuelve asolo_google. - Las alertas (
20261002130000_alertas.sql) y la Edge Functionalerta; y el POS de la ola B, que oye las alertas, ya le esconde al mesero lo del admin y trae el panel Personal con el alta por correo. - Dar de alta a Camila y a los meseros desde ese panel (o con el SQL de Yonatan), con la ola B al aire.
- Los permisos por rol (
20261002140000_permisos_por_rol.sql) después de publicar el POS de la ola B: al revés, el POS de hoy le mostraría al mesero botones que la base rechaza (y la base los rechaza en silencio, con 0 filas). - La ola C, en este orden: las cuatro migraciones (
20261002150000_aprobacion_personal.sql,20261002160000_mesas_y_pegatinas.sql,20261002170000_ajustes_ticket.sqly20261002180000_deshacer_cobro.sql, todas idempotentes y compatibles con el POS de la ola B: las filas depersonalque ya existen quedan aprobadas); luego la Edge Functioncuenta(una mesa desactivada es un enlace inválido: leemesas.activa, y por eso va después de la migración) yalertasi cambió; y por último el POS de la ola C. (El orden de aplicación no es el del directorio: la migración de la carta,20261003130000_carta_etiqueta_y_promos.sql, ya está aplicada en producción y en el directorio va después de estas cuatro; no comparten ningún objeto —carta_publica,productos.etiqueta,productos.dia_semana—, así que las cuatro se aplican encima de ella y dan el mismo catálogo que la cadena en el orden del directorio. Si algún día se usasupabase db push, pide--include-all.) - Google fuera de «Testing» (decisión D23, 2026-09-30), solo con la ola C al aire: antes, publicar la app deja a cualquier Gmail abrir el login. Con el modelo de aprobación, esa cuenta queda pendiente y solo ve el mapa y la carta.
Modelo de aprobación del personal (ola C: listo en ramas, no está al aire)
Pedido de Yonatan (2026-09-30): «haz mejor un panel de admin donde pueda añadir, aprobar o eliminar usuarios del restaurante; si no se aprueba solo podrá ver, no podrá hacer nada más». Es el camino normal desde la ola C, y reemplaza al alta solo por correo de la ola B: quien entra con Google pide acceso solo, y un admin lo aprueba o lo elimina. El alta por correo (personal_alta) sigue existiendo y crea a la persona ya aprobada. Diseño: docs/sdd-cuenta-en-mesa.md §12.2.
| Estado | Cómo se llega | Qué ve | Qué puede hacer |
|---|---|---|---|
| Pendiente | La primera vez que entra con Google sin estar en personal: el POS llama a solicitar_acceso(), que crea su fila (estado = 'pendiente', rol mesero provisional, nombre del perfil de Google) | «Tu cuenta espera aprobación», el mapa de mesas en solo lectura (número, capacidad y libre u ocupada, de vista_pendiente()) y la carta (carta_publica) | Mirar. Nada más: ni cuentas, ni totales, ni ventas, ni tokens, ni órdenes, ni alertas |
| Aprobado | Un admin lo aprueba como mesero o como admin (personal_aprobar(email, rol)), o lo dio de alta por correo | El POS de su rol (tabla de arriba) | Lo de su rol |
| Eliminado | Un admin lo elimina (personal_eliminar(email)): baja lógica, activo = false; la fila no se borra | La misma pantalla de espera, sin datos | Nada. Si vuelve a entrar, solicitar_acceso() responde eliminado y no la resucita: solo un admin puede volver a darla de alta |
- Lo impone la base, no la pantalla.
mi_rol()devuelve un rol solo si la fila está activa y aprobada: para un pendiente devuelvenull, y la compuertasolo_personalle niega todas las tablas, igual que a una cuenta sin fila. Lo único que ve es lo que le dan a propósitovista_pendiente()(número, capacidad y estado de las mesas activas; sin token, sin totales, sin órdenes) y la carta, que es pública.solicitar_acceso()no deja que nadie se apruebe a sí mismo: solo crea la fila pendiente. - Qué hace el POS en espera: no sincroniza datos, no abre Realtime de datos y no guarda caché; vuelve a preguntar cada 30 s y al volver a la pestaña, y cuando un admin lo aprueba arranca el flujo normal sin recargar. Si la base aún no tiene
solicitar_acceso(migración sin aplicar), el POS sigue el flujo de la ola B. - Quién aprueba: solo un admin. En Personal ve el contador de pendientes en vivo (le llegan los cambios de la tabla
personalpor Realtime; la RLS solo entrega las filas de los demás a un admin) y, por cada pendiente, «Aprobar como mesero», «Aprobar como admin» y «Eliminar»; por cada aprobado, cambiar el rol y eliminar. Eliminar se confirma dentro de la página, nunca con elconfirm()del navegador. - Nunca cero admins:
personal_eliminar,personal_bajay el cambio de rol rechazan lo que dejaría la tabla sin un admin aprobado y activo; un admin tampoco puede eliminarse si es el último. - Anti-abuso: hay un tope de solicitudes pendientes en total (lo fija la migración): llenado el tope se rechaza la solicitud nueva hasta que un admin limpie la lista. Una solicitud solo guarda el correo de Google y el nombre del perfil, y la hora.
- Privacidad: el correo y el nombre de un pendiente se guardan aunque nunca se aprueben, y solo los ve un admin.
privacy.htmllo dice. Para que se borre del todo un registro, la persona se lo pide al restaurante.
Google fuera de «Testing»: solo con la ola C al aire (decisión de Yonatan, 2026-09-30). Fuera de Testing, cualquier cuenta de Google puede abrir el login. Con la compuerta sola, esa cuenta ve «sin acceso»; con la aprobación, queda pendiente y solo ve el mapa y la carta. Antes de la ola C no se publica: mientras tanto, solo entra quien Yonatan agregó como usuario de prueba en Google Cloud (límite de 100) y esté en personal.
Mesas y pegatinas (ola C: listo en ramas, no está al aire)
Pedido de Yonatan: «en el panel administrativo debemos poder añadir y editar pegatinas». Vista Mesas y pegatinas del POS, solo para el admin. La guía para quien escribe las pegatinas, con los pasos de NFC Tools y de la contraseña, es docs/pegatinas.md.
- La lista trae todas las mesas, también las desactivadas: número, capacidad, estado (libre u ocupada), si está activa, su enlace (
carta.html?m=<mesa>&k=<token>, con «Copiar enlace») y cuándo se escribió y se revisó por última vez su pegatina. - Agregar mesa (
mesa_crear(id, capacidad)): el número y la capacidad; el token nace del default de la base. Respondeya_existesi el número ya está. Editar la capacidad (mesa_editar). El número no se cambia. - Desactivar o activar (
mesa_activar(id, activa)). Una mesa desactivada sale del mapa del salón (no del panel), su enlace responde «inválido» (la Edge Functioncuenta; la carta le dice a quien la toque que el enlace ya no sirve y que pida ayuda a un mesero) y no se le puede avisar (alertar_cuentala rechaza). No se puede desactivar una mesa con una cuenta abierta (con_cuenta_abierta). Las mesas no se borran: las órdenes apuntan a ellas y la clave foránea no tiene cascade. Reactivar una mesa devuelve su pegatina a la vida sin reescribirla. - Rotar el token sigue como hoy: solo admin (
rotarTokenMesa, frenado en la base portrg_mesas_token_solo_admin), e invalida la pegatina actual. - Escribir la pegatina desde el POS con Web NFC (
NDEFReader.writecon un registro de tipo URL): solo Chrome para Android, con HTTPS, NFC encendido y un toque del usuario. Al terminar marca la pegatina como «escrita» (pegatina_marcar). NuncamakeReadOnly: bloquearía la pegatina para siempre. Sin NFC (iPhone, otro navegador): «Copiar enlace» y NFC Tools. - Revisar la pegatina (
NDEFReader.scan): compara que la URL leída sea exactamente el enlace de esa mesa y del dominio del restaurante; solo si coincide la marca como «revisada» (pegatina_marcar). - La contraseña PWD/PACK de la pegatina (D16) no se pone desde Web NFC: va con NFC Tools. Por qué existe, cómo se pone y por qué nunca se bloquea para siempre:
docs/pegatinas.md. - Las cuatro funciones de la base (
mesa_crear,mesa_editar,mesa_activar,pegatina_marcar) son solo de admin y responden{ok, codigo?}.
Ajustes del ticket (ola C: listo en ramas, no está al aire)
Pedido de Yonatan: «código de barras parametrizable en el panel de admin porque puede cambiar el dominio». Vista Ajustes, sección «Ticket», solo para el admin: la dirección que lleva el QR del ticket (ticket_qr_url), si el QR sale (ticket_qr_visible) y el pie (ticket_pie, «Gracias por su visita» por defecto). Reemplaza el QR estático de la rama pos-pie: el POS dibuja el QR en el navegador con una librería chica fijada por versión exacta y servida desde assets/vendor/ (§03), y si esa librería no carga el ticket sale sin QR, nunca roto. La dirección debe empezar por https:// y tener hasta 200 caracteres: lo valida el POS y lo impone la base (un check). La lee todo el personal aprobado; la escribe solo un admin. El QR del ticket lleva a la landing: no muestra datos de pago.
Pedido de Yonatan (2026-10-02): «en la funcionalidad para pagar hazlo dinámico y si selecciona pagar, abrir QR de Bre-B» y «ese botón, al convertirse en QR, también debe tener la opción de enviar comprobante al WhatsApp de Resplandor». Pago con Bre-B. Vista Ajustes, sección «Pago con Bre-B», solo para el admin: el interruptor «Mostrar en la carta» (pago_breb_visible), la llave (pago_breb_llave) y el contenido del QR (pago_breb_qr: el texto que dice el QR, no una imagen; se pega o, si el navegador tiene BarcodeDetector, se lee de una foto), con la validación del formato EMV y del CRC antes de guardar y la vista previa del QR generado. La foto va primero (botón principal) y el texto es la otra manera; la llave sale sola del QR cuando está vacía; una etiqueta junto al título dice si la carta lo muestra («Visible para clientes» o «Apagado»), «Guardado» dice lo mismo, y un QR que trae un valor fijo (campo 54) o es de un solo uso (campo 01 en «12») avisa (todas las mesas pagarían ese valor). Los datos reales no están en el repo (es público): los carga el admin desde ahí. La base los valida con check (supabase/migrations/20261003150000_pago_breb.sql; la llave es «@alfanumérica», un número de 5 a 20 dígitos, un celular +57… o un correo; el QR, un contenido EMV de 20 a 700 caracteres cuyo último campo es el «6304» y su CRC es el correcto; y la llave que se muestra tiene que ser la que cobra el QR: el subcampo 04 del único campo 26 con el subcampo 00 CO.COM.RBM.LLA, leído campo por campo (privado.emv_llave y el check ajustes_pago_breb_qr_llave; sin eso un pegado equivocado dejaría «Llave: @a» bajo un QR que paga a «@b»). Lo mismo exigen la función, la carta y el tablero) y la Edge Function cuenta los entrega en pago: { breb: { llave, qr } } solo con la cuenta abierta y el interruptor encendido (nunca por carta_publica; service_role solo lee esas tres columnas de ajustes). Si la función no puede leer ajustes (un corte, la migración sin aplicar) no manda pago pero sí pago_desconocido: true, y la carta se queda con lo que ya mostraba: «no pude leer» no es «apagado». En la carta, «Pagar» → «QR (Bre-B)» convierte la hoja en el QR dibujado en el navegador (assets/vendor/qrcode-generator-1.4.4.js, corrección M), con «Llave: …» y «Copiar llave», el total y «Enviar comprobante por WhatsApp» (wa.me al número de assets/js/local.js, con la mesa y el total; sin datos personales); «Transferencia» muestra la llave con el mismo botón; «Efectivo» no cambia; todos avisan al mesero. En el celular «Transferencia» va primero (un QR en la pantalla del mismo celular que tendría que escanearlo no se puede leer: el QR dice «Para escanear con otro celular») y en escritorio, el QR. La vista del QR o la llave es compacta (sin la hora de apertura ni «Consumo en vivo»; la pastilla de conexión solo si dice algo malo), con una sola salida hacia atrás (la flecha «Cambiar método»), el subtítulo con el valor en vivo («escribe $ 99.000 en tu app del banco»: el QR del local es estático y no lo trae), «Copiar valor» (solo dígitos) y el botón del comprobante pegado sobre el total, a la vista sin desplazar desde 320×568 hasta 412×915; el mismo botón está en la tarjeta «Listo, le avisamos». Sin datos configurados el flujo es el de antes, sin QR ni llave. Se prueba de punta a punta (base real, cuenta real, carta y tablero en Chromium) en scripts/pruebas/integracion-pago-breb.test.mjs. Lo único en que la interfaz es más estricta que la base: el CRC en minúscula (EMV lo pide en mayúscula).
Tablero de Administración (ola C, ronda 5: listo en ramas, no está al aire)
Pedido de Yonatan (2026-10-01): «construir un panel o dashboard del admin donde pueda agregar meseros, editar menús semanales y demás administración». Una sola entrada Administración en la navegación (solo admin; el mesero no la ve) abre un tablero de tarjetas, móvil primero (una columna en el teléfono, rejilla de 2 y de 3 desde tablet). No duplica ninguna vista: cada tarjeta lleva a la que ya existía, con un dato vivo y su acción principal. Reemplaza al botón «Más» y a los links sueltos de Menú semanal y Personal.
- Hoy (franja de arriba): ventas del turno, mesas ocupadas y alertas pendientes.
- Tarjetas: Personal (solicitudes por aprobar y activos; «Agregar mesero»), Menú semanal (la semana en curso: cargada, incompleta o sin cargar; «Editar menú»), Mesas y pegatinas (activas y pegatinas sin revisar; «Revisar pegatinas»), Productos (en carta; «Agregar producto»), Ticket y ajustes (la dirección del QR actual), Cierres (el último cierre; «e historial» va solo para el lector de pantalla), Cobros deshechos hoy y Alertas. Las que piden algo del admin se destacan con un filete maíz y un chip («Por aprobar», «Por cargar» o «Por definir», «Por revisar», «Por decidir», «Por atender») y suben al principio (Alertas primero); con solicitudes esperando, el botón de Personal es «Revisar solicitudes (N)». La insignia de «Admin» cuenta las solicitudes por aprobar más una por cada tarjeta que pide algo (menú, pegatinas, ventas sin subir); las alertas tienen la suya.
- Ventas sin subir de esta tablet (un cierre «Sin respaldo» de la versión anterior): si una tablet trae uno sin decidir, la tarjeta de Cierres se destaca («Un cierre por decidir», chip «Por decidir») y su primer botón es «Revisar ventas sin subir», que abre la hoja de la ronda 5a, redactada de nuevo en la ronda 6 (subir las ventas que faltan o descartar la copia). Esa hoja también se abre sola al arrancar, una vez por sesión, y el aviso «Revisar» de la vista de Cierre la abre. Es solo del admin.
- Impresora de la caja: con la cola de impresión en la base la tarjeta sale sola: dato vivo «Caja en línea» (punto lleno) o «Caja sin conexión» (anillo hueco) con la última señal del agente («Última señal hace 12 s»), o «Sin configurar»; si la caja se cayó hace poco la tarjeta sube y dice «Por revisar»; su acción, «Configurar impresora», abre la vista de la impresora (crear la impresora, su token que se muestra una vez, rotarlo, imprimir una prueba), que cuelga de Administración con su «‹ Administración». Sin la cola en la base la tarjeta no existe (
impresora = null,tieneImpresora: el gancho dedocs/pos-visual.md§0.20, ya conectado). - Datos: solo reutiliza lo que el POS ya lee (personal, mesas, cobros deshechos, ajustes) más una lectura liviana nueva: el menú de la semana en curso (a lo más 18 filas). No hay migración ni función nueva en la base.
- En el teléfono la barra inferior del admin queda Mesas · Alertas · Productos · Cierre · Admin (Alertas se queda: la campana de arriba solo existe desde tablet).
Deshacer un cobro (ola C: listo en ramas, no está al aire)
Pedidos de Yonatan: «si pagué una parte de una cuenta y la quiero deshacer, si ese pago fue de esa mesa se debería poder editar y devolver a la mesa, por ende recalcular» (2026-09-30) y «el pedido se podrá deshacer cuando quiera el mesero o el admin» (2026-10-01). Se acabó el límite de tiempo que tenía el mesero. deshacer_cobro(orden_id) deshace tres clases de cobro del turno abierto:
- Un cobro parcial (por ítems o por unidades) y un abono crean una orden cerrada que apunta a la orden abierta de la que salieron (
ordenes.parcial_de). Deshacerlos los devuelve a la cuenta de la misma mesa: cada ítem vuelve con su mismo id, nombre, precio y nota (se le suma a la línea si sigue); un abono quita su línea «Abono recibido», y solo si la cuenta la trae exactamente así (una línea, cantidad 1, precio igual al opuesto del abono: si alguien la editó, no se devuelve y no se inventa un monto). - El cobro completo de una mesa (sin
parcial_de): si la mesa está libre, la misma orden se reabre en ella (la mesa vuelve a «ocupada»); si la mesa ya tiene otra cuenta abierta, sus ítems pasan a esa cuenta y la cerrada se borra (los abonos que habían salido de ella pasan a apuntar a la cuenta que los recibe, y siguen siendo devolvibles). - Cómo se ofrece: (1) justo después de cobrar (por partes o la mesa completa), un aviso «Cobrado $ X · Deshacer» de unos 15 segundos; (2) en el cierre, en «Transacciones del turno»: «Devolver a la cuenta de Mesa N» (parcial y abono), «Deshacer · reabrir la Mesa N» o «Deshacer · pasar a la cuenta de Mesa N» (la mesa completa), con una confirmación dentro de la página que dice qué vuelve y cómo queda la cuenta. Sin red no se ofrece: necesita la base.
- Qué hace, en una sola transacción con candado (sobre los cobros que salieron de la orden, la orden, la mesa y la cuenta abierta, siempre en ese orden: sin interbloqueo): vuelve los ítems, recalcula
totalyversion, y borra la orden cerrada (o la reabre). Como el cobro desaparece, las ventas de hoy y el cierre del día cuadran solos. El monto que devuelve es lo que de verdad volvió a la cuenta, no el total de la cerrada. La cuenta en vivo de la carta se actualiza con la señal de siempre (una sola). Un segundo toque respondeno_existe: no devuelve dos veces. - Quién y cuándo: el admin y el mesero, en cualquier momento, mientras el cobro siga en el turno abierto (todavía no esté archivado en un cierre del día: el cierre borra las órdenes que archiva, y si la purga está en camino responde
ya_en_cierre). Una cuenta sin rol, nunca (no_autorizado). Editar en el sitio y eliminar una venta cerrada siguen siendo solo del admin; deshacer es otra cosa, y por eso es una RPC con permisos propios y no undeletesuelto: el mesero no tiene permiso de editar ni borrar órdenes cerradas (SDD §02.3, nota 5). - Cuándo no se puede:
cuenta_ya_cerrada(el parcial o abono salió de una cuenta que ya se cobró completa: deshaz primero el cobro de la mesa),no_es_parcial(de otra mesa que la cuenta, un abono de antes sin cuenta —se corrige editándolo sin mesa, admin— o un abono que ya no cuadra),mesa_inactiva(la mesa se desactivó: se activa y se vuelve a intentar) yya_en_cierre. - Trazabilidad, no un freno (decisión de Yonatan): cada deshacer deja una fila en la tabla
deshechos(orden, mesa, tipo —parcial,abonoocompleto—, monto, los ítems, quién —el correo de la sesión de Google— y cuándo —la hora del servidor—). Solo la escribedeshacer_cobro(nadie tiene INSERT) y solo el admin la lee. El cierre del día le enseña al admin «Cobros deshechos hoy: N · $ X» con la lista (quién, mesa, monto, hora); «hoy» es el turno: lo que todavía no cuelga de ningún cierre (cierre_idnull; lo ponecerrar_diaal cerrar, así que no depende del reloj de ninguna tablet), y cada día del historial cuenta los suyos. Se guarda 90 días (al guardar un cierre del día se borra lo más viejo). Es un dato personal (el correo de quien lo hizo):privacy.htmllo dice.
El cierre del día lo decide la base, y los deltas llevan un id (ola C, ronda 5: listo en ramas, no está al aire)
Las dos rondas anteriores trajeron casi tantas regresiones propias como hallazgos nuevos, y todas nacían de lo mismo: el cierre del día comparaba una foto de la tablet y además se podía cerrar sin red y subir después. Esta ronda no parchó esa máquina: la simplificó.
- El cierre lo decide la base (
cerrar_dia(p_id, p_esperado), solo admin, una transacción con el candado de aviso común condeshacer_cobro). Ya no recibe la lista de la tablet: toma todas las ventas cerradas que ningún cierre se llevó (también las de ayer que nadie cerró), rechaza si queda una cuenta abierta (hay_abiertas), arma el cierre, lo guarda, borra lo que archiva, purga los ids de deltas que ya no tienen orden y le pone sucierre_ida los deshechos del turno. Nunca borra una cuenta abierta. Para que el admin firme lo que ve, el POS manda lo que espera (p_esperado: cuántas ventas, cuánto y cuáles); si la base tiene otra cosa respondecambiocon su resumen (sin guardar ni borrar nada) y el POS vuelve a mostrar la confirmación con los números de la base («Los números cambiaron mientras mirabas… Sí, cerrar así»). La hora del cierre es la del servidor. (El método de pago solo se guarda en las líneas de abono: una venta normal no lo lleva, así que el cierre no trae un total por método más queabonos_por_metodoen el resumen.) - No hay cierre sin red. «Cerrar día» solo se habilita con conexión y con la cola vacía (sin deltas, filas ni cierres editados sin subir); si no, el botón se apaga y dice «Sin conexión…» o «Hay N cambios sin subir: espera a que suban» (con «Reintentar subir»). Se fue el camino del cierre «Sin respaldo» para los cierres nuevos y todo lo que existía solo por él (
sinSubir,_cierreRechazado, el archivo local antes de que la base conteste). Un cierre «Sin respaldo» viejo que haya quedado en ellocalStorage(del POS de la ola B, el de producción) ya no se resuelve solo (ronda 5a): lo decide el admin, ver «Sin descartes silenciosos, reabrir con red y cierres viejos a decisión del admin» más abajo; nunca se purga nada a partir de él. - Una venta nunca entra en dos cierres: la tabla interna
cierre_ordenes(orden_ides la clave primaria) la mantiene un disparador decierres; un segundo cierre con una venta ya archivada se rechaza (RS004) y el cobro de una venta cerrada ya archivada se rechaza conRS005(ronda 5a: antes se descartaba en silencio). Ronda 6: editar un cierre que la base ya tiene tampoco puede meter una venta que está viva enordenes(RS004: una copia atrasada del historial no resucita una venta que otro admin reabrió y se volvió a cobrar; el POS vuelve a leer el historial y avisa). - Deltas idempotentes:
aplicar_delta_ordenganap_delta_id(opcional). El POS le pone un id a cada delta al encolarlo y lo reenvía igual en cada reintento; la base lo anota endeltas_aplicadosdentro de la misma transacción y, si ya estaba, no aplica nada. Una cuenta cobrada sin red sube con los ítems de los deltas que nunca se mandaron: la fila lleva sus ids enordenes.deltas_idsy el guardia los anota en la misma transacción que la fila. Con eso, reenviar un delta cuya respuesta se perdió ya no lo duplica (era el límite admitido de la ronda anterior). - El POS sabe qué trae la base (
_sondearBase): pregunta porordenes.parcial_de(el guardia deversion) yordenes.deltas_idscon una lectura de cero filas, así que no depende de que haya órdenes cargadas. Sin un sí confirmado no mandaversion; sin los ids, cae al camino de antes. - Un POS viejo sin recargar no corrompe nada con la base nueva: además, un guardia de DELETE (
trg_ordenes_guardia_borrar) no deja que la API borre una cuenta abierta con ítems, así que el cierre del día de una tablet con el POS viejo (guardar el cierre con su foto y borrar por id) ya no se lleva la cuenta que otro dispositivo reabrió con «Deshacer». Ronda 6: tampoco deja borrar por la API una venta cerrada que ningún cierre archivó: una purga que se quedó pendiente en una tablet (K1.purgar) no puede llevarse el segundo cobro de una venta que un admin reabrió con el mismo id; el cierre que guarda esa tablet queda anotado encierre_ordenes, así que esas ventas no se cuentan dos veces.
Sin descartes silenciosos, reabrir con red y cierres viejos a decisión del admin (ola C, ronda 5a: listo en ramas, no está al aire)
La refutación de la ronda 4 encontró tres fallos que nacían del paso del POS viejo al nuevo. Yonatan eligió simplificar: en vez de más código de recuperación, menos máquina y decisiones a la vista.
- Nada se descarta en silencio. El guardia de
ordenes(trg_ordenes_guardia) ya no devuelvenull(0 filas y ningún aviso) al subir una ventacerradacuyo id está archivado en un cierre: la rechaza conRS005(«la cuenta … ya estaba en un cierre del día: revísala con el admin»). Antes ese camino también se comía el cobro de una cuenta que existe abierta con un id archivado (un POS viejo cerró con una foto vieja y la cuenta la había reabierto un «Deshacer»): quedaba imposible de cobrar ycerrar_diadecíahay_abiertaspara siempre. El POS lo recibe (esErrorCuentaArchivada→_cuentaArchivada): lee qué hay en la base con ese id y avisa «Esta cuenta ya estaba en un cierre del día: no se cobró y sigue abierta. Revísala con el admin» (al admin le dice dónde: Historial → ese cierre → Editar → Reabrir), deja la cuenta abierta y la mesa ocupada y no deja nada pendiente; si la venta ya se archivó y se purgó, la suelta con aviso.cerrar_diarespondehay_abiertasconen_cierre(cuáles de esas mesas están en ese caso) y la ventana del cierre lo dice. También se rechaza conRS005el cobro por partes, por persona o el abono de una cuenta que existe abierta y archivada (la cuenta cobrada «por partes» se vaciaba, se liberaba la mesa y la venta quedaba contada dos veces): el POS lo recibe (esErrorCobroParcialArchivado→_cobroParcialRechazado), quita ese cobro, no toca la cuenta (lo que un cobro saca de ella —las unidades, o el crédito del abono— sale solo DESPUÉS de que la base acepta su fila: de una venta rechazada no salió nada), relee la cuenta de la base y la adopta tal cual y avisa «El cobro por partes de la Mesa N NO quedó registrado… Si ya recibiste el pago, no lo pierdas de vista». Si la cuenta ya no está abierta (el parcial llegó tarde de una tablet sin red) entra como siempre. Los únicos descartes callados que quedan son los del guardia de DELETE, a propósito (los provoca un POS viejo o una purga atrasada que borran por id y no tienen dónde mostrar un error). - Reabrir una venta de un cierre pasado exige conexión y es atómico (
reabrir_venta_de_cierre(p_cierre_id, p_orden_id, p_mesa_id), solo admin): en una sola transacción, con el mismo candado de aviso, saca la venta del cierre (recalcula su total y su cuenta de ventas; el disparador decierresla libera decierre_ordenes) y deja la cuenta abierta en la mesa pedida. Todo o nada. Antes el POS subía la cuenta abierta y después editaba el cierre: si la segunda subida no llegaba, la cuenta quedaba abierta y archivada a la vez. Sin red, «Reabrir en mesa» se apaga y dice «Sin conexión: reabrir una venta de un cierre pasado necesita la base…». Es también la salida limpia delRS005: si la cuenta ya existe abierta con ese id, se la deja tal cual y solo se la saca del cierre (adoptada); desde ese momento se cobra y se cierra el día con normalidad (una sola vez en los libros). Códigos:no_autorizado,invalido,no_existe,no_esta_en_cierre,es_abono,mesa_inexistente,mesa_inactiva,mesa_ocupada. Reabrir una venta del turno (no de un cierre) sigue como siempre. - Los cierres «Sin respaldo» viejos los decide el admin. Un cierre que el POS de antes dejó en
localStoragepor cerrar el día sin red (traepurgarysyncdistinto deok; los que arma esta versión por el camino de siempre llevanorigen) sale de la lista de cierres al cargar la caché y se guarda aparte (pos_cierres_viejos): nada lo sube con unupsert, ni esconde las ventas de hoy, ni purga la base a partir de él. Al arrancar, al admin se le abre una hoja: «Ventas sin subir de esta tablet»: «Esta tablet guardó N ventas ($ X) del sistema anterior (cierre del …). Faltan en el sistema: 1 ($ Y)», con la lista de solo las que faltan o el sistema tiene abiertas (mesa, día y hora, monto; las demás —ya están, ya estaban en un cierre, se deshicieron— se resumen en una línea) y dos acciones explícitas: «Subir N ventas ($ Y)» (solo las que el sistema no tiene en ninguna orden, cierre nideshechos; entran como cobros normales) o «Descartar copia» (pide un segundo toque, en el pie fijo y con «Sí, descartar» como botón de peligro y la cifra de lo que se perdería; no sube nada ni toca la base). Las marcas de subida de las ventas de ese cierre que ya no están enpos_ordenesse sueltan al cargar la caché (_soltarPendientesDeCierresViejos): si la base tiene esa cuenta abierta, la copia atrasada ya no pisa lo que se agregó sin red. La hoja compara con una lectura propia de la base y, si falla, no concluye nada (apaga «Subir»). El mesero no la ve (el cierre queda guardado para el próximo admin que entre en esa tablet). Mientras haya uno sin decidir, «Cerrar día» se apaga y lo dice. Se fue_recuperarCierresViejos(la recuperación automática de la ronda 4).
Cerrar con lo que se vio (ola C: listo en ramas, no está al aire)
Refutación de la ola C, hallazgo 4: una tablet que estuvo sin red cobraba la mesa con los ítems que veía y pisaba lo que otra tablet había devuelto con «Deshacer» (44.000 de 49.000 consumidos quedaban sin cobrar ni registrar). Ahora el UPDATE que pasa una orden de abierta a cerrada lleva la version que la tablet vio, y el disparador trg_ordenes_guardia lo rechaza con RS003 si la base tiene otra. El POS anota la version que la base le contesta tras cada delta y espera a los deltas en vuelo antes de cerrar (así no hay falsas alarmas propias); si de todas formas la cuenta cambió, deja la cuenta abierta y la mesa ocupada, la vuelve a leer y avisa «La cuenta cambió, revísala: … No se cobró nada». Quien no manda version (una caché vieja) no se frena.
Imprimir en la caja (cola de impresión: listo en ramas, no está al aire)
Qué resuelve. Sacar el ticket en la térmica del PC de la caja desde cualquier celular, con wifi o con datos, sin instalar nada en los teléfonos (se descartó Tailscale en cada celular: una VPN por teléfono, por mesero nuevo y por cuenta).
Cómo se pide: siempre a la caja, con una confirmación (pedido de Yonatan, 2026-10-03; docs/pos-visual.md §0.24, que reemplaza la elección de §0.22). Imprimir tiene un solo destino, la caja, y una sola pregunta. «Imprimir precuenta» (la de toda la cuenta), el «Precuenta» de cada persona («Dividir cuenta por persona») y el «Imprimir» del ticket de un cobro, un abono o una precuenta abren un modal corto («¿Imprimir la precuenta en la caja?», «¿Imprimir la precuenta de Camila en la caja?», «¿Imprimir el ticket en la caja?») con [Imprimir en la caja] y [Cancelar] y un resumen («Mesa 3 · 6 ítems · $ 97.000»). Nada sale hasta confirmar, y con la caja en línea no se abre la impresión del teléfono; el estado (En cola → Imprimiendo → Impreso) sale en el aviso flotante. Ya no hay «En la caja / En este teléfono» ni dos botones en el ticket. Mientras hay un trabajo igual en cola, su botón dice «En cola…» y está apagado (sin doble impresión; el de otra persona o el del ticket son otros papeles y siguen libres). Con otro papel viajando a la caja (por ejemplo el «Reintentar» del aviso, que va sobre los modales) el botón de la pregunta se apaga y dice «Enviando el anterior…»: la confirmación nunca se cierra sin mandar nada (si la tocan igual, avisa y se queda abierta). Y si ese mismo papel ya quedó en cola mientras la pregunta seguía abierta (el «Reintentar» era de él), el botón dice «En cola…» como el de su fila y «Cancelar» pasa a «Cerrar»: no manda una segunda copia (confirmaImpresionEnCola). Qué pasa según lo que el POS sabe de la caja:
| Estado de la caja | Qué hace «Imprimir» |
|---|---|
| En línea (último latido de menos de 90 s) | La pregunta de arriba; al confirmar, el trabajo va a la cola |
| Registrada pero sin latir | La salida de emergencia, con la misma confirmación: «La caja no está en línea (última señal hace 7 min). Se imprime desde este teléfono.» con [Imprimir aquí] y [Cancelar]; nada se encola |
La cola no está en la base (la migración sin aplicar: el POS de hoy), la cola está pero nadie registró la caja o todas las cajas están dadas de baja (activa = false, que la base solo le devuelve al admin: una caja de baja es como no tener ninguna y el admin imprime igual que el mesero) | Imprime desde el teléfono sin confirmación extra: el diálogo de impresión del propio teléfono ya es la confirmación y el POS no cambia en nada |
| No se sabe (la red falló al arrancar) | Primero vuelve a preguntar (hasta 2,5 s) y decide con la respuesta: un «no sé» no se toma por «no hay caja». Mientras espera, el botón dice «Un momento…» y ningún botón de imprimir responde (un segundo toque no se suma); si en la espera salió de la cuenta, no abre ninguna pregunta |
El teléfono imprime solo en esos casos de emergencia: (1) caja registrada que no late (la confirmación de arriba), (2) si el envío falla después de confirmar (la caja se cayó entre medias, sin red, la base lo rechaza, el documento no cabe: el teléfono imprime solo y lo dice, porque la persona ya pidió el papel). El papel es lo que se confirmó, no lo que muestre la pantalla cuando por fin falla el envío (un envío lento tarda hasta 10 s: en ese rato pudo abrir otra mesa, con otra «Persona 1»): si esa cuenta sigue a la vista imprime exactamente el documento confirmado; si ya salió de ella, depende de si el papel se puede volver a pedir (_caerAlTelefono): una precuenta sí (la cuenta sigue abierta), así que no imprime otra cosa y el aviso lo dice («No se imprimió: ya saliste de esa cuenta. Vuelve a la Mesa 3 y pídela de nuevo.»); el ticket de un cobro, de un abono o del «Cobrar» de una persona no (la cuenta se cerró y ninguna pantalla vuelve a mostrar su ticket: un mesero no tiene «editar_cerradas»): no se le trae la pantalla de vuelta ni se cancela nada (antes, a los 10 s, reaparecía sola mientras atendía otra mesa y se cancelaba el trabajo tardío, también el que sí había llegado a la cola con la respuesta lenta). El aviso del trabajo se queda en la lista con la orden CONFIRMADA (una copia, no la cuenta abierta de ahora) y dice la verdad: si el trabajo sí llegó (se mira en la base) sigue su camino —sale en la caja y el aviso lo sigue—; si no se sabe, queda «dudoso» («No hubo respuesta de la caja. Si el ticket llegó, sale allí en unos segundos; si no sale, imprímelo desde este teléfono.»), cuenta como «en cola» para su botón (no se pide otro igual) y se vigila su respuesta tardía; si la base lo rechazó, queda en «error». En esos dos últimos el botón «Imprimir desde este teléfono» del aviso pone otra vez en pantalla esa orden y la imprime (_imprimirTrabajoDesdeTelefono), y antes cierra la puerta de atrás: si el trabajo pudo quedar en la cola lo cancela y, si la caja ya lo tomó, NO imprime aquí (saldría doble). Si quien lo pidió cerró sesión o entró otra persona en la tablet, el aviso se va con la sesión. Y (3) «Imprimir aquí» del aviso «La caja no responde…» (o «se calló mientras imprimía…»), que cancela el trabajo de la caja para no salir doble. Lo que se cancela y lo que se ofrece distingue qué papel es (la precuenta entera y la de cada persona son de la misma orden; _alcanceDe): imprimir aquí la precuenta de Camila no cancela la de Andrés ni la entera.
La precuenta de una persona (botón «Precuenta» de su fila): un documento con solo las líneas de esa persona (su nombre o «Persona N»), su total, el encabezado «PRECUENTA — no es un cobro» y la línea «Cuenta de Camila · Mesa 3» (en lugar de las filas «Mesa» y «Cuenta de»), con el mismo formato del documento de la caja y del ticket de pantalla (_armarPreCuentaPersona, documentoTicket); respeta «Para llevar» (bajo el producto, y el encabezado si es todo el pedido) y no cobra ni saca nada de la cuenta (a diferencia de «Cobrar», que sigue igual). Si la mesa ya recibió abonos «por monto», las líneas de cada persona siguen asignadas y suman más de lo que la mesa debe: debajo del TOTAL de sus líneas lleva «Abonos de la mesa» y «Queda por pagar (mesa)» (la cifra que también hace valer «Cobrar»), para no entregarle al cliente un papel que le cobra otra vez lo ya pagado. La precuenta de toda la cuenta conserva su encabezado «CUENTA DE COBRO — NO ES FACTURA». El aviso dice «Cuenta de Camila · Mesa 3». Sin la caja sale del teléfono con el mismo texto.
Cómo funciona. El POS arma el ticket (el mismo contenido que el de papel, con el nombre de cada persona cuando la cuenta se dividió: «Cerdo - Camila», «Cuenta de Camila») y lo inserta en impresiones. Un agente en el PC de la caja (impresora/, Node 22 sin dependencias) solo hace conexiones salientes a Supabase: oye una señal por Realtime (tópico impresora: + sha256(token), sin datos, como la cuenta en vivo), toma el trabajo con impresora_tomar, lo convierte a ESC/POS y lo manda RAW al spooler de Windows; luego confirma con impresora_confirmar. Si la señal se pierde, sondea la cola cada 5 s. El POS muestra «En cola → Impreso» en vivo (el aviso conserva los tres últimos y, aunque sean más viejos, todo lo que no terminó —en cola, imprimiéndose o con error—, para que su botón «En cola…» siempre tenga salida a la vista: «Imprimir aquí» o la X; con varios se acota y se desliza; el POS recuerda hasta 10 trabajos y, pasado el tope, solo olvida lo ya impreso —_acotarTrabajosCaja—, nunca lo que no terminó) y, si el insert falla después de confirmar, cae a window.print() del teléfono si el mesero sigue en esa pantalla, o deja el aviso con «Imprimir desde este teléfono» si ya salió (el ticket de un cobro o un abono nunca se queda sin papel —el aviso guarda la orden cobrada desde que el trabajo entra a la lista, también si entró a la cola y la caja no responde—; una precuenta que ya no está a la vista se vuelve a pedir; sin caja en línea lo dice la confirmación, ver arriba). «Deshacer» un cobro retira el aviso de su ticket y cancela lo que quedó en la cola (el papel de un cobro que ya no existe no se ofrece ni sale); si la caja ya lo tomó, el aviso lo dice y sale allí. Con un diálogo abierto el aviso se compacta a una línea («y N más»), arriba y sin recibir toques, para no tapar los botones del diálogo (con tres papeles sin respuesta la pila medía 320 px y tapaba «Imprimir en la caja» y «Sí, cobrar»); al cerrarlo vuelve entero. Con la base de hoy (sin la migración) el POS es el de siempre.
Seguridad. El agente no lleva ninguna llave de servicio: usa la clave publicable y un token de impresora aleatorio (256 bits, se muestra una sola vez al crearlo o rotarlo en el POS → Administración → «Impresora de la caja» → «Configurar impresora», solo admin; la base guarda su hash). Las tres RPC del agente (impresora_tomar, impresora_confirmar, impresora_latido) las puede ejecutar anon, pero un token inválido, rotado o de una impresora desactivada es indistinguible (vacío / no_autorizado). Rotar deja sin servicio al agente viejo al instante. El agente filtra todo byte de control del documento: un nombre de producto con ESC o GS no le manda comandos a la impresora. Garantía de entrega: al menos una vez (si el PC se cae entre imprimir y confirmar, a los 2 min sale otra copia si el trabajo tiene menos de 15 min, como mucho 3; el agente toma un trabajo por vez y recuerda en disco lo que ya imprimió). Nada de más de 15 min sale al volver el PC, ni lo que nadie tomó ni lo que se colgó a media impresión, y el POS cancela en la base lo que deja sin respuesta cuando el teléfono imprime o se cierra el aviso. El agente se niega a sacar más de 600 renglones de papel, y el POS no recorta una cuenta enorme: la imprime el teléfono.
Al aire (todo con el GO de Yonatan; el orden y la reversa de menos de un minuto, en impresora/README-impresora.md y en la cabecera de la migración): (1) 20261003140000_cola_impresion.sql después de la compuerta (usa mi_rol()/mi_correo()), en el SQL Editor; el POS de hoy no la nota; (2) el POS con el botón; (3) en el POS, admin → Administración → tarjeta «Impresora de la caja» → «Configurar impresora» → crear → token; (4) en el PC de la caja: Node 22, la carpeta impresora/, config.json con el token, node agente.mjs --impresoras, --prueba y iniciar.cmd. Pruebas: scripts/pruebas/migracion-cola-impresion.test.mjs (la base), impresora-*.test.mjs (el agente), pos-impresion-caja*.test.mjs (el POS) y impresion-punta-a-punta.test.mjs (los tres juntos, con Docker y Chromium), integracion-personas-impresion.test.mjs (la jerarquía de los botones, la tarjeta del tablero y el documento con los nombres de las personas), pos-impresion-defecto.test.mjs y pos-impresion-defecto-navegador.test.mjs (la confirmación, la emergencia, el «En cola…», la precuenta por persona y la fila de dos líneas a 320, 360, 390 y 1280 px) e integracion-punta-a-punta.test.mjs (el POS real a 390, 920 y 1440 px contra la base real y el agente: tablero, dividir por persona con nombres, imprimir en la caja, «Cobrado $ X · Deshacer» y el cierre con sus colores). Sin probar todavía: la señal por el Realtime real de Supabase, el spooler de Windows y la térmica de verdad.
Verificación en modo prueba (Google Cloud)
Mientras el proyecto de Google Cloud esté en modo "Testing", solo pueden loguearse cuentas agregadas manualmente en Audience → Test users (límite de 100). Publicar la app a producción quita ese límite; como solo se usan scopes básicos (email/perfil), normalmente no exige la revisión larga de Google reservada a scopes sensibles.
Decisión (2026-09-30): sí se saca de Testing, pero solo con la ola C al aire (paso 6 de arriba). Sin la compuerta, «publicar» y «cualquier Gmail entra al POS» son lo mismo: la RLS de antes solo exigía el proveedor Google. La compuerta ya cierra el acceso a los datos, y el modelo de aprobación hace que quien llega sin permiso quede pendiente y solo vea el mapa y la carta, en vez de un callejón sin salida. Es una decisión de identidad y la ejecuta Yonatan.
Lo único que anon puede leer: la carta y su cuenta (2026-09-06)
La carta pública de las pegatinas NFC (carta.html) no toca las 4 tablas. Sus dos puertas, ambas en supabase/:
| Puerta | Qué expone | Por qué es segura |
|---|---|---|
Vista carta_publica (SECURITY DEFINER a propósito, como las policies de menus) | categoria, nombre, precio, descripcion de productos con activo and en_carta | anon solo tiene SELECT sobre la vista; productos sigue sin policies para anon. El advisor la lista como security_definer_view: es el diseño. |
Edge Function cuenta (GET ?m=<mesa>&k=<token>, --no-verify-jwt como votar) | Solo la orden abierta de esa mesa: ítems (nombre, precio, cantidad), total, hora | Valida el par (mesas.id, mesas.token) con service-role; token de 48 hex por mesa, rate-limit por IP. Ola C: además exige que la mesa esté activa; una mesa desactivada responde igual que un token malo («enlace inválido», 404), para no revelar cuál de las dos cosas es. Fuga aceptada: quien guardó el enlace ve la cuenta del siguiente ocupante mientras esté abierta; el mesero rota el token desde "Enlace NFC" en la vista de la orden (con roles, la rotación es solo del admin). |
Desayunos y promociones de la semana (2026-10-01, rama carta-promos). Desde la migración 20261003130000 la vista carta_publica expone además, al final, etiqueta y dia_semana (mismas filas, mismos permisos). La carta conoce dos categorías por datos: Desayunos (siempre se pinta, con «Todos los días · 7:00 a.m. – 11:00 a.m.»; sus platos y precios son los del letrero del local —Calentado Resplandor $17.000, Desayuno sencillo $9.000, Desayuno Resplandor $12.000— y se cargan con el sobre de datos; sin platos cargados dice «Pregunta por los desayunos del día» en vez de inventar) y Promociones (sección «Promociones de la semana», enlace estable carta.html#promociones, lunes a domingo según dia_semana, con la de HOY resaltada según la hora de Bogotá y no la del teléfono). Las promociones de precio fijo son productos normales; la del lunes (20% en el tercer almuerzo) y los 2 x 1 (miércoles y sábado) no tienen precio propio: van con precio 0 y una etiqueta, y la carta muestra la etiqueta, nunca «$ 0». No hay función de descuento en el POS y no se pidió (Yonatan, 2026-10-01: «no son descuento, son promociones todos los días»): cada día es una promoción tal como la dice su afiche. En el POS esas tres aparecen como productos normales (tocarlas suma una línea de $0; el ítem manual no admite 0 ni negativos: pos.html, agregarItemManual). La carta nueva pide las 6 columnas y, ante un 400 (la base todavía sin la migración), repite con las 4 de siempre. El orden para salir al aire está en PASOS-AL-AIRE.md de la coordinación (sobre 1 → publicar → sobre 2) y los datos se cargan con un sobre SQL, no con una migración. La landing no depende de la base para las promociones: muestra los afiches (assets/img/promos/), y la carta de la landing (#carta, landing.js) NO lleva la categoría «Promociones» (saldría sin día y con «$ 0»); sus platos sí traen la etiqueta. Las herramientas en vivo para agentes (vivo.js: WebMCP ver_carta, MCP resplandor_ver_carta) piden las 6 columnas con el mismo repliegue ante un 400 y entregan etiqueta y dia (las promociones valen un solo día). El domingo la carta no ofrece el Menú Resplandor (no hay): la tarjeta del día lo dice y la franja «Promoción de hoy» (Almuerzos) queda justo debajo; «hoy» se vuelve a calcular a la medianoche de Bogotá y al volver a la pestaña.
La pegatina de cada mesa lleva https://resplandor.ynt.codes/carta.html?m=<mesa>&k=<token>; el POS lo muestra, lo copia y lo rota. Sin k válido la carta no muestra el control "Mi cuenta".
Cuenta en vivo y «Pagar» (ramas, sin desplegar). Con la fase 1 de docs/sdd-cuenta-en-mesa.md la carta recibe los cambios por un canal de Realtime cuyo tópico sale de sha256(token) y cuyo mensaje va vacío (la carta vuelve a leer cuenta); con la ola A, el botón «Pagar» (detrás del interruptor pagarEnMesa de assets/js/local.js, apagado) hace POST a la Edge Function alerta (--no-verify-jwt, solo ejecuta alertar_cuenta), que crea una alerta para el personal. Desde 2026-10-02 la carta SÍ muestra la llave y el QR de Bre-B del restaurante, pero solo con una cuenta abierta y el interruptor del admin encendido (ver «Pago con Bre-B» arriba); el mesero cobra y cierra en el POS. Ninguna de las dos funciones se ofrece a agentes (WebMCP, MCP, llms.txt). Una línea de abono (precio negativo) se ve en la cuenta como abono, con signo menos, y el total es lo que queda.
menu.html crea su cliente de Supabase sin sesión (persistSession: false): comparte origen, y por lo tanto localStorage, con el POS, y con la compuerta una tablet con la sesión de alguien que no está en personal vería la votación sin menús.
Cierres por día y panel de cierres con rastro (2026-10-05: listo en rama, no está al aire)
Pedido de Yonatan (tareas/2026-10-05-cierres-de-hoy-y-panel-admin.md) tras ver «Cierre del día» con la Mesa 1 del domingo abierta. «Transacciones del turno» y los KPIs son solo de HOY en Bogotá (el día de cerrada_en, no el del aparato ni el de UTC): las ventas de un día anterior que nadie cerró siguen por cerrar, pero van a un aviso discreto de una línea («Ayer (dom 4) quedó sin cerrar: N ventas · $ X — Cerrar ayer · Ocultar»). Lo ven todos; «Cerrar ayer» solo el admin; «Ocultar» se guarda por día en localStorage y vuelve al día siguiente si sigue sin cerrar. La base lo hace con cerrar_dia_de(p_id, p_dia, p_esperado) (migración 20261006100000_cierres_de_hoy_y_cambios.sql): cierra solo las ventas de ese día, el admin firma lo que ve (cambio si otra tablet vendió algo), un día pasado lleva la fecha de ese día (su 23:59:59 en Bogotá) y una cuenta abierta no lo frena (una cuenta abierta todavía no es una venta); cerrar HOY sigue exigiendo las mesas cobradas. cerrar_dia(p_id, p_esperado), la firma vieja, no se toca (un POS sin recargar sigue cerrando todo junto) y un POS nuevo con una base sin la migración cae a ella. Con una base sin la migración, el admin no firma una cosa y cierra otra: el primer «Sí, cerrar día» descubre que cerrar_dia_de no existe, no cierra nada y vuelve a la ventana con las cifras nuevas (todas las ventas por cerrar, con el aviso «entran también las de días anteriores» y el botón «Sí, cerrar así», como ante cambio); solo el segundo clic llama a cerrar_dia. Si no hay ventas de días anteriores, lo firmado es lo mismo que se cerraría y un solo clic basta. Un día pasado, sin la migración, no se cierra por separado.
Una venta con cerrada_en de «mañana» cuenta como de HOY (decisión por defecto, a confirmar por Yonatan): el reloj de una tablet adelantado cobra una mesa al pasar la medianoche y la venta queda con la fecha de mañana; antes no salía en ninguna lista ni entraba en ningún cierre hasta el día siguiente. Ahora el POS la trata como de hoy (diaDeVenta topa el día en hoy: sale en «Transacciones del turno», suma en los KPIs y entra en «Cerrar día») y la base hace lo mismo (migración 20261006120000_cierres_ajustes.sql: cerrar_dia_de(HOY) toma también las ventas cuyo día en Bogotá es posterior a hoy, así lo que el admin firma es lo que la base cierra; un día pasado no se las lleva y un día futuro sigue siendo invalido). Con la base intermedia (20261006100000 aplicada y 20261006120000 todavía no) y el POS nuevo, la base no toma la venta de mañana mientras el POS sí la cuenta como de hoy: si es la única del turno, cerrar_dia_de responde sin_ventas (para la base no hay nada que cerrar) y el POS avisa «La base no ve esas ventas como de hoy: revisa la hora de la tablet»; si hay otras ventas de hoy, responde cambio con las de hoy sin la de mañana y, firmado eso, el cierre se hace y la de mañana queda sola, con el mismo sin_ventas. No se pierde ninguna venta (queda por cerrar hasta que se aplique la segunda migración o llegue mañana), pero es un estado a evitar: el orden de salida es obligatorio, 100000 → 120000 → push del POS, y el POS nuevo no sale antes de 20261006120000.
Relojes desfasados (la base cuenta los días con su reloj, cada tablet con el suyo; el POS lo dice en vez de afirmar lo que no sabe): (1) tablet adelantada y «Cerrar ayer»: el día que la tablet llama «ayer» es HOY para la base; si la base responde cambio con ventas que la tablet cuenta como de hoy, o hay_abiertas (que solo frena el cierre de hoy), la ventana dice «Para la base ese día es hoy: el reloj de esta tablet va adelantado. Revisa la hora de la tablet.» y pasa a ser la de hoy (con el bloqueo de mesas abiertas y la firma de lo que propone la base), no la de «solo las ventas del día pasado: las de hoy no se tocan»; (2) tablet atrasada, o la venta de mañana con la base intermedia: si la base responde sin_ventas y la tablet, ya releída la base, sigue teniendo esas ventas por cerrar, el aviso es «La base no ve esas ventas como de hoy: revisa la hora de la tablet» y no «otro dispositivo ya cerró» (ese texto queda para cuando de verdad las ventas ya no están). Lo que no se arregla en el POS (la base es quien cuenta los días, y no sabe qué reloj tiene la tablet): una tablet atrasada que cierra «hoy» le pide a la base cerrar un día pasado (sale con la fecha 23:59:59 de ese día y sin exigir las mesas cobradas), y una adelantada que cierra «hoy» pide un día futuro, que la base rechaza (invalido, el POS dice «recarga la página»); en los dos casos no se pierde ninguna venta.
Panel «Cierres» dentro de Administración (solo admin: puede('cierres_admin') en el POS; RPC y RLS en la base): los cierres de los últimos 30 días; al abrir uno se ven sus ventas (se saca o edita una con el editor de siempre, que recalcula el total), se corrige su nota (cierre_corregir_nota), se anula con un motivo (cierre_anular) y se lee su rastro. Los totales no se editan a mano (salen de las ventas: ninguna RPC recibe un monto) y nada se borra: un cierre anulado se queda, tachado, con quién, cuándo y por qué, y sus ventas vuelven a las ventas por cerrar (sale su aviso, se cierra el día otra vez); un cierre anulado también suelta sus cobros deshechos (deshechos.cierre_id vuelve a null y no quedan colgados del cierre anulado; ajuste de 20261006120000; los toma el PRÓXIMO cierre que se haga, sea del día que sea —cerrar_dia_de marca los deshechos con cierre_id is null y fecha_bogota(hecho_en) <= p_dia, así que solo se libra un cierre de un día anterior al que se deshicieron—: si se cierra HOY antes de rehacer AYER, los cobros deshechos de ayer quedan en el cierre de hoy y el de ayer rehecho sale sin ellos; decisión de Yonatan si prefiere deshechos por día), y queda congelado (RS006: la base rechaza cualquier UPDATE que nombre fecha, totales o ventas, aunque el contenido sea idéntico; si no, el upsert idéntico de una tablet con el historial atrasado volvería a archivar las ventas liberadas y el siguiente cierre las borraría sin contarlas; el POS, al recibir RS006, avisa y vuelve a leer el historial). Cada cambio deja una fila en cierres_cambios (quién, cuándo, qué cierre, qué cambió, antes y después, y la venta completa que salió o cambió): la escribe un solo disparador SECURITY DEFINER sobre cierres, así que también anota el cierre del día, «Reabrir» y la edición del historial; solo el admin la lee, solo se agrega (RS007) y no se purga. El UPDATE directo de cierres queda en las cinco columnas de siempre: la nota y la anulación solo van por las RPC. Orden de salida (obligatorio): 1) 20261006100000_cierres_de_hoy_y_cambios.sql, 2) 20261006120000_cierres_ajustes.sql (se niega a correr sin la primera), 3) el push del POS. Pruebas: migracion-cierres-de-hoy.test.mjs y migracion-cierres-ajustes.test.mjs (dinero y permisos por rol contra Postgres 17; la segunda, además, que las dos funciones son el mismo cuerpo que las de la primera más el cambio puntual) y cierres-de-hoy-navegador.test.mjs (la lógica del POS y el navegador a 390 y 1280 px).
Precio vivo y promociones como regla (2026-10-04)
Desde tareas/2026-10-04-hallazgos-domingo.md la base es quien mantiene al día los ítems de toda cuenta abierta (migración
20261005100000_precio_vivo_y_promos.sql): un trigger BEFORE en ordenes refresca el precio de cada línea de producto desde
productos y aplica las promociones del día como línea propia y positiva («Seco · 3er almuerzo · 20% OFF», 1 × 15.200, junto a
«Seco», 2 × 19.000), y un trigger AFTER en productos «toca» las cuentas abiertas cuando cambia un precio o una regla, así el cambio
llega solo a todas las tablets (Realtime, misma version), a la carta (señal cuenta:) y al ticket. Las cuentas cerradas no se tocan.
La regla vive en productos.promo_regla ({ cada, descuento, aplica: { categorias, productos } }: por cada N unidades elegibles, la
más barata de cada grupo lleva X %; 100 = gratis, el 2 x 1; o, desde 20261006170000, la forma de precio fijo { cada, precio, aplica }: el grupo de N unidades
cuesta $ X, ver «Promociones de precio fijo» más abajo) y se edita desde el modal de producto; el POS solo muestra las promos del
día (dia_semana) y anuncia las de regla, que no se agregan a mano. Pagar en la carta es una sola pantalla: al abrir «Pagar» se
avisa al mesero con el método cuenta («pide la cuenta», migración 20261005110000_alerta_pedir_cuenta.sql) y copiar la llave o
abrir el comprobante afinan esa alerta a transferencia. Ojo con los permisos: el CHECK de promo_regla corre con el rol de quien
escribe (authenticated, desde el POS), así que privado.promo_regla_ok es la única función de privado que esos roles ejecutan
(migración 20261005120000_promo_regla_ejecutable.sql, como emv_crc_ok en el pago con Bre-B); las otras cuatro las llaman los
triggers (SECURITY DEFINER) y la API no las corre. Sin ese permiso nadie podía crear ni cambiar un producto desde el POS.
Una cuenta con promoción no se parte (migración 20261005130000_promo_cobro_por_partes.sql). El descuento sale de contar las unidades que
hay en la cuenta entera y «Cobrar por partes» (por ítems, por unidades o por persona) saca unidades de una en una —una orden cerrada con
parcial_de y después un aplicar_delta_orden (−qty) por línea— y la base lo recalcula tras cada una: el mismo almuerzo del lunes salía a 53.200,
57.000 o 83.600 (5 Seco: el restaurante perdía 7.600), y cobrar las dos líneas de un grupo dejaba un Seco ya pagado en la cuenta. La regla, simple
y comprobable: la guardia trg_ordenes_guardia_promo rechaza (SQLSTATE RS005, mensaje con «promoción» y «por partes») un cobro por partes de una
cuenta que tiene una línea promo:… —el mismo código de la cuenta archivada, a propósito: el POS ya publicado lo reconoce como «el cobro no quedó»—, el POS no lo
ofrece (casillas apagadas, aviso, y «Cobrar» a una persona se vuelve un abono por su total) y se cobra la mesa completa o se reparte con abonos,
que no sacan unidades, así que la suma cobrada no depende de cómo se reparta. El POS lo juzga igual para no ofrecer el cobro por partes: la línea promo:… que trae la cuenta o la que la base le pondría HOY según sus unidades (cuentaTendriaPromo, con el día de
hoy: una cuenta escrita ayer se juzga con la regla de hoy; antes solo miraba las líneas guardadas y la base la rechazaba con RS005 una y otra vez), y si aun así la base contesta RS005
(el catálogo de la tablet era anterior) la tablet relee la cuenta y recuerda la promoción en esa versión. Una cuenta sin promoción se cobra por partes como siempre; lo cobrado
aparte antes de que hubiera promo no cuenta para un trío que se arme después (la promo se calcula sobre lo que hay en la cuenta abierta). Dos
promos del mismo día sobre los mismos productos: ninguna unidad recibe dos descuentos, pero puede contar para dos grupos (hoy no hay dos reglas
el mismo día). Recordar lo ya cobrado (en vez de bloquear) no cierra el cobro de varias líneas: entre la fila cerrada y el último delta hay escrituras
intermedias en las que la unidad está en las dos cuentas. Eso se cerró de raíz con el cobro atómico (párrafo siguiente).
El cobro por partes y los abonos son UNA llamada atómica en la base (tercera refutación del 2026-10-05; migración 20261005140000_cobrar_parcial.sql). Cobrar como
«fila cerrada + deltas −qty por la cola» no converge: el orden de llegada de varias escrituras decide el dinero (los deltas que ya esperaban en la cola, los que
se mandan después y adelantan, la venta que llega antes o después de ellos) y la base recalcula la promo tras cada una; con la red de verdad —supabase-js no lanza sin
red, devuelve {error}— se midieron 57.000 y 54.000 donde la mesa debía pagar 53.200 y 50.400. En vez de arreglar el orden caso por caso, la base hace el cobro entero:
cobrar_parcial(p_orden_id, p_version, p_venta, p_lineas, p_delta_id) y cobrar_abono(p_orden_id, p_version, p_venta, p_monto, p_metodo, p_delta_id), SECURITY INVOKER (la
RLS manda; mismos permisos que aplicar_delta_orden), con el candado de aviso resplandor.cobros y select … for update de la cuenta, juzgan en este orden:
idempotencia por p_delta_id —antes que la versión: repetir un cobro cuya respuesta se perdió devuelve lo mismo sin duplicarlo, mande la versión que mande; si esa venta ya
no existe, RS003—; la versión que la tablet vio (RS003: está atrasada, relee); la cuenta archivada (RS005); la promoción, en la cuenta o la que tendría al normalizarla con
las reglas de hoy (RS005: no se parte; el día de la promo es el de la escritura, privado.dia_promo(), igual que el trigger: una mesa abierta ayer se juzga con hoy); y las líneas pedidas, que
tienen que existir con esas unidades (RS006). Entonces inserta la venta cerrada con parcial_de (el precio de hoy de la cuenta y el total los pone la base), saca esas
unidades de la cuenta, sube la versión y devuelve las dos filas. El abono pone, en la misma transacción, la venta «Abono» y la línea abono_recibido_<uid>; sí entra en una
cuenta con promoción (no saca unidades). El POS (_cobrarEnBase) espera a que no haya cambios de esa cuenta en camino (deltas en vuelo o en la cola, con tope de 10 s; si no
puede vaciarla, es «sin red»), llama, y adopta las dos filas tal cual. Por eso el cobro por partes y los abonos necesitan red: sin ella (el RESULTADO de la llamada, no remoto: un
error de red, un 5xx sin código o 10 s sin respuesta) no se cobra ni se encola nada, la cuenta no cambia y el aviso dice «Sin red: el cobro por partes y los abonos necesitan red;
la mesa completa sí se puede cobrar».
El cobro «en duda» y la cuenta CONGELADA (cuarta y quinta refutación, 2026-10-06). Una llamada que falla por red no dice si el cobro llegó: la base pudo aplicarlo y perderse solo la
respuesta. El id del cobro nace UNA vez por intento (al confirmar el diálogo), se guarda en localStorage (pos_cobros_en_duda, uno por cuenta) y no depende de la versión de la cuenta.
Una cuenta con un cobro en duda queda CONGELADA en esa tablet hasta que la reconciliación con la base diga si el cobro entró o no (una sola regla; antes cada puerta tenía la suya y
se colaban los cambios: asignar una persona, marcar para llevar o un +1 subían la versión de la copia —_anotarVersion, hoy _anotarRespuesta— SIN los ítems que el cobro ya había sacado, la mesa completa cerraba con
la copia vieja y la guardia RS003 la dejaba pasar: 75.000 por una mesa de 62.000, u 82.000 con un abono que el cierre borraba; y el ticket PROVISIONAL de la mesa completa ignoraba lo ya
cobrado). Congelada = no se agrega, quita, reasigna ni marca para llevar nada, no se pone un precio, no se deshace un cobro de ella, y no se cobra (mesa completa, por partes, persona, abono ni
precuenta): la cuenta se muestra con un velo («Cobro pendiente de confirmar con la base: espera a que vuelva la red») y un botón «Reintentar ahora», y el mapa de mesas la marca con un
reloj. Las puertas son _cobroBloqueado (todo cobro; lo primero que mira _motivoSinCobro), _gestoBloqueado (cada gesto, antes de tocar nada), los escritores de fondo que esperan sin
subir (_intentarMarcaLlevar, _intentarPrecio) y _anotarRespuesta, que no sube la versión de una cuenta congelada; pos-cuenta-congelada.test.mjs recorre el store en busca de cualquier
método que escriba una cuenta sin su puerta. El aviso de un cobro que salió y no se sabe si entró NO ofrece la mesa completa. La reconciliación (_resolverCobroEnDuda: una lectura por id en
ordenes; sola al volver la red, cada 7 s mientras haya una cuenta congelada, al arrancar y a mano con «Reintentar ahora»): si la venta existe se adopta la venta y la cuenta de la base
(ticket real, aviso «SÍ quedó registrado… no lo repitas») y se descongela; si no existe, «no llegó» todavía no es definitivo (ver abajo, «La espera de 30 s»): pasada la espera y con dos
lecturas sin la venta, se suelta el intento, se relee la cuenta de la base y se descongela; si no se puede preguntar (o la venta está pero no se pudo leer la cuenta), sigue congelada. Un intento ya no se reenvía (no hay «huella»): a un cobro en duda solo se le pregunta; un cobro nuevo sale con ids propios. Pasadas
6 h sin poder preguntar el intento ya no cuenta (la única salida que no sabe, y el aviso lo dice). El candado es por cuenta (una llamada colgada de una mesa no frena a las demás) y se libera
siempre. Lo que queda dicho: una petición que la red entregue DESPUÉS de los 30 s y de las dos lecturas sin la venta registraría el cobro sin que la tablet lo sepa; ninguna petición tarda tanto
(PostgREST acota la ejecución a 8 s), pero si pasara, la guardia de versión la rechazaría (RS003) si algo cambió mientras tanto, y si nada cambió la tablet relee la cuenta con el próximo eco o lectura.
La espera de 30 s (sexta refutación, regresión de la rama): un «no llegó» de la reconciliación no es definitivo mientras la petición original pueda seguir en camino (una recarga con
«Registrando…» colgado, el tope de 10 s: PostgREST termina la petición aunque el cliente la aborte). El intento solo se suelta cuando (a) la petición se asentó (respuesta, error o aborto por el
tope: asentadoEn, que se guarda con el intento; la página nueva asienta al arrancar el intento que dejó la anterior), (b) pasaron al menos 30 s desde entonces (ESPERA_COBRO_TARDIO_MS) y
(c) una segunda lectura por id sigue sin la venta; mientras tanto la cuenta sigue congelada, con el velo, y «Reintentar ahora» dice que sigue en espera.
La versión local nunca sube sin los ítems que la acompañan (sexta refutación, 2026-10-06; ya estaba en producción). La respuesta de un cambio propio (asignar una persona, «para llevar», un +1,
un precio) solo subía la version de la copia; si otra tablet había cobrado algo de esa cuenta, la copia vieja quedaba con la versión buena, la guardia RS003 la dejaba pasar y la mesa completa
registraba lo ya cobrado (75.000 por una mesa de 62.000), también en la tablet que no tenía nada en duda. Ahora _anotarRespuesta decide por cada respuesta con una versión mayor: si la fila
trae los mismos ítems que la copia, solo sube la versión (el caso de siempre); si trae ítems distintos y la tablet no tiene otro cambio propio en camino (deltas en vuelo o en la cola, o la
fila sin subir), adopta la fila entera (ítems, total y versión, con encima las marcas y precios que aún no subió); si hay otros cambios en camino, la cuenta se está cerrando, la fila es más
vieja que otra ya vista, la cuenta está congelada o solo llegó una versión (sin ítems), la versión local no se toca y la copia queda «desactualizada» y se relee en cuanto se pueda. Lo mismo
vale para cada sitio que escribía version: el cobro adoptado con cambios propios en camino y «Deshacer» una mesa completa ya no copian la versión de una respuesta sin ítems (la sacan de la
lectura que sigue); pos-version-con-items.test.mjs recorre el store y falla si algún camino escribe version sin los ítems que la acompañan. Y el cobro de la mesa completa, con red, relee la
cuenta de la base justo antes de cerrar y cierra con eso (_facturarReleyendo): si lo leído —o lo que la respuesta de un cambio AJENO trajo mientras se esperaba— no es lo que la pantalla mostraba al tocar «Sí, cobrar», se adopta, se avisa («La cuenta cambió en la base… ahora son N
ítems por $X y la pantalla decía $Y») y NO se cierra: el diálogo sigue abierto con el total nuevo y se confirma de nuevo; si la base ya no la tiene abierta (la cobró otra tablet), o ya no la tiene
(la cobró por partes y liberó la mesa, o la anuló: la fila se borró), no se cobra nada («Esta cuenta ya no está en la base…», más abajo). Sin red no hay con qué
leer: se cierra con la versión que de verdad corresponde a los ítems locales, PROVISIONAL, y al volver la red la base manda: RS003 si la cuenta cambió, RS007 si ya no existe (la lápida, más abajo).
RS003/RS006 («La cuenta cambió: revísala y vuelve a cobrar»), RS005, cuenta ya cerrada y permisos: se avisa, nada
sale de la cuenta y se relee. «Deshacer» ya sabe devolver estas ventas (la unidad vuelve y la base recalcula la promo). La guardia de 20261005130000 se queda como red de
seguridad de una tablet que todavía tiene el POS de antes.
Una cuenta que la base ya no tiene no se cobra ni resucita: la lápida de las cuentas borradas (séptima refutación, 2026-10-06, corregida por la octava; el defecto ya estaba en producción; migración 20261006150000_lapida_de_cuentas_borradas.sql, aún sin pegar). Cuando OTRA
tablet cobra toda la cuenta por partes y libera la mesa, o la anula (quita todos los ítems) y la libera, la fila de la cuenta se borra. La tablet con la copia vieja tocaba «Sí, cobrar»; su relectura trataba «0 filas» como
«no se pudo leer», cerraba con la copia vieja y el upsert de la fila cerrada la INSERTABA como una venta nueva (la guardia RS003 solo juzga el UPDATE): 124.000 por una mesa de 62.000, o una venta fantasma de una cuenta
anulada; sin red pasaba igual al volver la red, y «Deshacer» el cobro completo de una mesa que ya tenía otra cuenta (la cerrada se borra) abría la misma puerta. Y una cuenta ABIERTA pendiente de subir (la tablet la atendió sin red, o la subida de su fila se cortó a medias) resucitaba igual cuando por fin subía, y se cobraba dos veces. Ahora, en dos capas. (a) El POS (_leerCuentaParaCobrar) distingue «la
base contestó que no existe» (200 con 0 filas, o PGRST116) de un fallo de lectura (red, 5xx, un error de la base): si no existe NO cobra, avisa «Esta cuenta ya no está en la base: otra tablet la cobró o la liberó», sale de la cuenta, relee las
mesas y muestra la mesa libre. Solo vale para una cuenta que ya estuvo en la base (la marca local subida, que ponen parseOrden y la primera subida que entra, o una version > 0): una cuenta abierta sin red y jamás subida sigue
pudiendo cerrarse (su venta se inserta; es la única cuyo cierre puede insertarse). (b) La base guarda privado.ordenes_borradas —la lápida: una tabla PRIVADA con id, borrada_en y tenia_items, RLS sin policies y sin permisos para la API— con los ids que
borró (trg_ordenes_anotar_borrada, AFTER DELETE: liberar una mesa vacía, deshacer_cobro —el cobro completo que pasa a otra cuenta y el parcial que vuelve a su cuenta borran la fila cerrada—, la purga del cierre del día), y trg_ordenes_guardia_lapida
(BEFORE INSERT, solo la API) rechaza con RS007 («esa cuenta ya no existe: la cobró o la liberó otra tablet») cualquier fila —cerrada o abierta, también el esqueleto ON CONFLICT DO NOTHING— con el id de una cuenta de la lápida que TENÍA ÍTEMS: es lo que atrapa el caso SIN red.
«Tenía ítems» (la frontera, octava refutación): ítems no vacíos, o version > 0 (cada cambio de los ítems la sube: un cobro por partes que la vació, una anulación y deshacer_cobro la dejan en ≥ 1 aunque queden 0 ítems), o una venta cerrada. Otra tablet decidió sobre esos ítems: nadie los vuelve a subir ni a cobrar. Si la cuenta se borró VACÍA y SIN HISTORIA (nació y se liberó vacía, version 0:
nadie pidió nada en la base) la venta real de una tablet que la atendió sin red ENTRA (cerrada, o abierta con lo que pidió), una sola vez y sin aviso: antes (séptima versión de la lápida) se rechazaba y esos 49.000 se perdían. Lo que la frontera NO distingue: una cuenta que tuvo ítems en la base, se vació y se liberó, y una tablet que la atendió sin red tiene OTROS
ítems que nunca llegaron; esa venta real también se rechaza (la base no sabe qué ítems nunca llegaron) y el POS enseña al mesero lo que esa tablet agregó y nunca llegó. Se prefiere perder una venta que se puede volver a tomar a cobrar dos veces.
El POS trata RS007 (esErrorCuentaBorrada, _cuentaBorrada) como una cuenta que no debe existir, cerrada o abierta: la descarta (con su ticket, lo pendiente, la marca pendiente de «mesa ocupada» que esa cuenta sostenía y los cambios que esperaban en la cola), vuelve al mapa, relee y avisa «El cobro de la Mesa N que hiciste sin conexión NO quedó registrado…» (cerrada) o «La cuenta de la Mesa N que esta tablet tenía pendiente de subir ya no existe en la base…» (abierta); si la tablet había agregado
cosas que nunca llegaron (_itemsSinSubir: los cambios de la cola, sumados por línea), el aviso las enseña («Lo que esta tablet agregó y NUNCA llegó a la base: 2 × Seco…») para que el mesero abra una cuenta nueva con ellas o las deje. El esqueleto de lo pendiente (_subirLoPendiente) también recibe RS007: sin eso los cambios de una cuenta que ya no existe quedaban primeros de la cola para siempre.
Lo que NO frena: una cuenta que nunca estuvo en la base, un UPDATE (la fila existe: lo juzga RS003), una cuenta borrada vacía y sin historia, el dueño y las funciones SECURITY DEFINER (deshacer_cobro, cobrar_parcial, reabrir_venta_de_cierre, cerrar_dia). Una cuenta que vuelve a existir POR UNA FUNCIÓN DE LA BASE o por el dueño
(trg_ordenes_olvidar_borrada, AFTER INSERT, SECURITY INVOKER: mira current_user como las guardias de antes y borra por privado.orden_olvidar: reabrir una venta de un cierre, «Deshacer») sale de la lápida: reabrir y volver a cobrar sigue funcionando. Subir por la API NUNCA la saca de ahí (antes sí, y de ahí salía el cobro doble de una cuenta abierta que resucitaba). Al guardar un cierre del día se borran las anotaciones de más de 7 días (trg_cierres_purga_lapida). El orden de los guardias es el del nombre: trg_ordenes_guardia (RS005: archivada) gana. Lo que queda dicho:
la guardia mira lo ya confirmado (un INSERT que empiece en el mismo instante en que otra transacción borra la cuenta no se frena); pasados 7 días la anotación se va; el cobro por partes del POS de antes inserta una venta cerrada NUEVA con parcial_de
que la lápida no mira (el POS nuevo cobra por la RPC, que no encuentra la cuenta); y la frontera de arriba. Pruebas: migracion-lapida-borradas.test.mjs (Postgres 17 con la RLS de un mesero y un admin), pos-cuenta-borrada.test.mjs (el store en un vm) y pos-cuenta-borrada-real.test.mjs (Chromium con supabase-js real y dos tablets:
X1 a X4, N1, N3 y, de la octava refutación, R1, R2, R2b y R3).
Lo propio en camino no es «otra tablet la tocó» (séptima refutación, regresión de la rama; la octava lo afina): al tocar «Sí, cobrar» la tablet espera sus cambios en camino (un +1, una persona, un precio), lee la base y compara con lo que la pantalla mostraba ítem por ítem, unidades Y precio de lista (_cuentaPlana; una línea de promoción cuenta como su plato a su precio de lista). En un día de promo
la respuesta de un +1 propio trae la línea de promo que la base puso: las unidades y los precios de lista son los mismos y solo cambió el reparto del descuento, así que, si la cuenta no cuesta MÁS de lo que se veía, cierra sin avisar con el total que registra la base; si cuesta más (quitar una
unidad deshizo la promo) pide confirmar de nuevo, y el aviso dice que fue por lo que acabas de cambiar; si las unidades difieren o algún precio (otra tablet puso un precio a mano: con las mismas unidades el total bajaba y se adoptaba SIN aviso, o subía y se atribuía a esta tablet), otra tablet también tocó la cuenta: se avisa «otra tablet la tocó» con el total nuevo, suba o baje, como siempre.
Lo cobrado por una mesa no depende de cómo se parta (invariante, con sus salvedades; segunda refutación del 2026-10-05, tareas/2026-10-04-hallazgos-domingo.md).
Vale para cobros hechos desde una lectura al día de la cuenta, y sin red no se cobra una cuenta con promoción. Tres reglas del POS lo sostienen, todas
comprobadas con el store en un vm, con la base real (mesero con RLS) y en el navegador:
- La base manda; el cobro es atómico. Un cobro por partes o un abono es UNA llamada (
cobrar_parcial/cobrar_abono): la base inserta la venta y saca las unidades (o pone el crédito) en la misma transacción, o no hace nada. Si la rechaza (RS005 por promoción o cierre del día, permisos, la cuenta cambió) de la cuenta no salió nada y el POS no la reconstruye: la relee y la adopta tal cual (_adoptarCuentaDeLaBase). Si no puede leerla, la copia queda «sin confirmar» y no se cobra hasta que una lectura la reemplace. (Antes la venta y los −qty salían a la vez y el rechazo «devolvía» con +qty una unidad que nunca salió: con la copia atrasada, 2 Menú + 1 Seco quedaba en 80.200 en vez de 61.200 —la línea «Seco» ya era «Seco · 3er almuerzo» en la base y el −qty no encontraba nada que sacar—; ya no hay −qty.) - Sin red no se cobra una cuenta con promoción (la línea
promo:…, o la que la base pondría:cuentaTendriaPromo, por la regla de HOY —el día de la escritura, como la base— y sus ítems): mesa completa, por partes, por persona, abono y precuenta muestran «Sin red: esta cuenta tiene promoción; espera a que vuelva la red para cobrar». Sin red la tablet no recibe la línea de promo y los deltas subían antes que la venta: la guardia ya no veía la promo y 3 Seco volvían a 57.000. Las cuentas sin promoción se cobran sin red completas, como siempre; por partes y los abonos, nunca sin red (necesitan red). «Sin red» se sabe por el RESULTADO de una llamada (supabase-js devuelve{error}sin lanzar):sincronizarSupabasemarca la tablet «sin red» con ese error, el cobro de la mesa completa de una cuenta con promoción pregunta primero si hay base (una lectura de una fila, 4 s) y el navegador avisa con «offline»/«online»; marcada así, la tablet vuelve a preguntar sola cada 8 s. - El total lo fija la base. El cobro de la mesa completa pide de vuelta la fila que la base REGISTRÓ (
upsert(...).select(...): ya pasó portrg_ordenes_a_precio_vivo, que recalcula promos y precios de hoy al cerrar) y el ticket se arma con ese total; si difiere del que la tablet mostraba, avisa «La base recalculó el total…». Con red «Imprimir» espera esa respuesta como mucho 10 s (pasado el tope se enciende, el papel dice «PROVISIONAL» y el POS lo dice); sin red (solo cuentas sin promoción) el ticket dice «PROVISIONAL» y, al confirmarse, si el total registrado difiere, lo avisa y el ticket ya dice el nuevo (ticket 34.200 y venta registrada 38.000 era una caja que no cuadra). El cierre del día (cerrar_dia) suma lo que la base registró, que ahora es lo mismo que dice el ticket.
Lo que no cubre, dicho: lo cobrado aparte antes de que hubiera promoción en la cuenta no cuenta para un trío que se arme después (la promo se calcula sobre lo que hay en la
cuenta abierta); y una tablet que todavía tiene el POS de antes sigue cobrando por partes con la fila cerrada y los −qty (la guardia de 20261005130000 frena lo de las cuentas con
promoción, pero ese protocolo no converge): por eso el POS nuevo va a todas las tablets antes de pegar las reglas (sobre 2).
Precio a mano por línea del pedido (2026-10-06)
Pedido de Yonatan del 2026-10-05 («se debe poder editar el valor a mano de cada producto»; tareas/2026-10-05-precio-a-mano-y-botones.md). En la
vista de la orden, tocar el precio unitario de una línea abre en esa misma línea un campo en pesos enteros (Enter o salir del campo guarda,
Escape cancela; vacío no cambia nada) y el precio nuevo vale para todas las unidades de la línea. Lo pueden hacer el mesero y el admin
(puede('precio_a_mano'), como crear y editar productos) y solo en una cuenta abierta: no en cobrar por partes, ni en un abono o el marcador «para
llevar». Una línea de promoción tampoco se cambia ELLA (se recalcula desde su base), salvo cuando la promo se llevó su base ENTERA (con «3er
almuerzo», tres ejecutivos distintos × 1 dejan al más barato entero en la línea promo:…:<base> y la línea base desaparece de la cuenta): entonces
esa línea de promo ofrece el precio del PLATO (el campo trae el precio sin el descuento, y el descuento se recalcula sobre el nuevo), la pastilla
«a mano» y «Volver al precio de carta», y todo viaja por el id de la base (promo.de). La línea queda con precio_manual: true y precio_por
(el correo de Google de quien lo puso, que escribe la RPC; la línea de promo sin base lo recuerda en promo.precio, promo.precio_manual y
promo.precio_por) dentro del jsonb de ordenes.items, sin columna nueva: la carta, el ticket y el cierre leen el mismo precio.
precio_por es la atribución que pone la RPC, no un dato a prueba de falsificación: ordenes_editar deja a un mesero escribir ordenes.items
por la API y una escritura directa puede traer precio_manual y un precio_por cualquiera, que el precio vivo respeta; no se usa para decidir
nada (permisos, cierre, carta pública). Cerrarlo con un guardia en ordenes_guardia no cupo limpio (la RPC es SECURITY INVOKER y el POS mismo escribe
marcas por escritura directa: la fila entera de una mesa abierta sin red, el cobro completo y por partes), así que queda como decisión pendiente de
Yonatan (rechazar la marca directa, o aceptar que precio_por es solo informativo). El precio vivo ya no la pisa:
privado.normalizar_items no refresca desde productos una línea con precio_manual, y las promociones la cuentan con ese precio (la línea de
promo recuerda la marca de su base; si la base vuelve —otra unidad del plato desde la carta, o un precio que la deja de ser la más barata—, la
adopta de la línea de promo). El cambio viaja por la RPC public.fijar_precio_item(p_orden_id, p_item_id, p_precio) (migraciones
20261006110000_precio_a_mano.sql y sus rondas 2 y 3 20261006130000_precio_a_mano_promo_entera.sql, la última de las de main (la última que redefine normalizar_items es 20261006140000, que las une; detrás van la lápida, 20261006150000, y «servida», 20261006160000, la última de la cadena); las aplica Yonatan, en ese orden y
antes del push del POS): los mismos guardias que aplicar_delta_orden (orden bloqueada y abierta, version que sube, SECURITY INVOKER) más mi_rol()
admin o mesero; COP enteros de 0 a 10.000.000 (0 vale: una cortesía y, como una línea gratis no entra a la promo, la base reaparece). «La línea no existe en la
orden» sale con SQLSTATE PT404 y «orden no existe» sigue P0001. Con PT404 PostgREST responde HTTP 404 (los PT<nnn> son los que devuelve con el estado
HTTP ; un P0002 salía como 500, porque PostgREST convierte todo P0xxx salvo P0001 en 500): el message es fijo y sin ids («linea inexistente en la
orden»; PostgREST lo pone en la línea de estado HTTP) y la frase con los ids va en details. El POS (esLineaInexistente) lo reconoce por el código y, por el
texto, la RPC de 20261006110000 (que la decía con P0001); esOrdenInexistente no toma un PT404 por «orden no existe». Ante cualquiera de los dos —o una cuenta
cerrada— deja la línea como estaba, avisa en una línea («La cuenta de la mesa N cambió: el precio de «X» no se guardó. Quedó como estaba.») y vuelve a leer la cuenta.
Si el campo del precio estaba abierto sobre la línea de una promo que se llevó el plato entero y, antes de Enter, la cuenta cambió (otra tablet sumó una unidad: la
base reaparece, o quitó un plato: la promo se desarma), el precio escrito va a la línea del plato de ahora (la base, por su id); si ya no hay ninguna línea de ese
plato, el POS avisa «La cuenta cambió, vuelve a tocar el precio.» en vez de perderlo en silencio. El POS la llama como
actualizar_nota_item llama a la marca de «Para llevar»: inmediato en pantalla, con reintentos y anotado como pendiente (preciosPendientes, solo en
memoria: se pierde si el navegador se reinicia antes de que vuelva la red, la misma arquitectura que las marcas «para llevar») hasta que la base confirme, sin
que el eco de Realtime lo borre, y «Recargar» espera a que llegue. El precio va a la cuenta del campo que se tocó, no a la activa de ahora.
«Volver al precio de carta» (un enlace en la línea, solo con precio a mano) manda p_precio = null, quita la marca y deja que el precio vivo
la refresque.
privado.normalizar_items la redefinen cuatro migraciones (20261005130000, que pliega una línea de promo sin su objeto, las dos del precio a mano, que respetan precio_manual, y —ya sobre la unión— 20261006170000, el precio fijo de las promos), las tres primeras escritas sobre la
de 20261005100000 sin saber de las otras: create or replace deja ganar a la última que se pega, así que el orden de pegado perdía en silencio el precio a mano (las cuentas volvían al precio de la
carta en su siguiente escritura) o el pliegue. 20261006140000_normalizar_items_pliegue_y_precio_a_mano.sql es la unión (el cuerpo de la última de main con el pliegue) y va última de las que la redefinen y, en el sobre final, detrás de las otras dos (la lápida, que no la toca, va después):
en cualquier orden, quien la pega por último deja la función completa (migracion-normalizar-items-union.test.mjs lo prueba con tres bases). La reversa del sobre final devuelve la
función a la que había antes: la de 20261006130000 si el precio a mano está puesto, la de 20261005100000 si no.
Al deshacer un cobro, la cuenta manda (deshacer_cobro_sumar, migración 20261006130000; la venta cerrada guarda la línea con la marca de cuando se cobró y
esa marca puede estar vieja): al devolver una venta a una cuenta abierta, si la cuenta ya tiene ese plato —su línea base con ese id, o una línea de promo de
esa base (cuando la promo se llevó el plato entero, su precio y su marca viven en ella)—, las unidades devueltas se suman al precio y la marca que la cuenta tiene
hoy, y la línea devuelta pierde la suya (precio_manual y precio_por en una base; promo.precio_manual y promo.precio_por en una línea de promo, cuyo
promo.precio se queda como el precio base al que se desplegará, que luego el precio vivo refresca si no hay marca). Si la cuenta no tiene nada de ese plato,
la línea vuelve tal como se vendió, con su marca y quien la puso. Sin esto, tras «Volver al precio de carta» (o con otro grupo en la misma mesa) deshacer un cobro por
partes o completo le pegaba a la cuenta un precio a mano que nadie le había puesto hoy, firmado con el correo de otra persona. «La cuenta» es la que había antes de
sumar; el cobro completo que se reabre en su mesa libre vuelve tal cual (no hay cuenta que mande). El paso a' de normalizar_items (la base que vuelve sin marca
adopta la que recuerda su línea de promo) sigue siendo necesario para el otro camino —tocar el plato en la carta mientras la promo se lo lleva entero a precio a mano—. Con el POS puesto y la migración sin aplicar, tocar un precio avisa «falta aplicar la actualización de la base» y deja el precio como estaba
(y, sin la ronda 2, el precio de un plato que está dentro de una promo avisa que la cuenta cambió y lo deja como estaba). Carreras que no se corrigieron
(decisión de Yonatan): dos tablets —la A fija el precio y la B, atrasada, cobra por partes esa línea al precio viejo: la venta cerrada queda al precio
viejo y la cuenta al nuevo, la misma carrera que un cambio de precio en Productos (el INSERT cerrado no se normaliza a propósito). En el mismo pedido, los
+ − de cada línea pasaron a ser discretos: siguen midiendo 44 px de toque, pero sin caja ni borde (solo el signo en apoyo, la cantidad en medio), y a
390 px la línea se lee en dos renglones (docs/pos-visual.md, §3.13). Pruebas: migracion-precio-a-mano.test.mjs y
migracion-precio-a-mano-promo-entera.test.mjs (estática y contra Postgres 17 en Docker: permisos por rol, dinero, promos, la base dentro de la promo,
cobro, reversa) y precio-a-mano-navegador.test.mjs (estática, vm y navegador a 390 y 1280 px). La primera incluye los escenarios D1 y D2 de la refutación de la ronda 2 y los bordes de
«la cuenta manda» (la cuenta con y sin el plato, a mano o no; el cobro completo que se reabre).
Promociones de precio fijo: «cada N por $X» (2026-10-06: listo en rama, no está al aire)
Pedido de Yonatan del 2026-10-06 (noche, un martes), mirando la mesa 1 con 2 Hamburguesa Resplandor a $ 30.000 = $ 60.000 y el «Combo hamburguesas» agregado aparte, a mano, como un
producto más de $ 50.000: «si agrego 2 hamburguesas resplandor no hace el descuento cuando se adiciona y queda el precio normal 60, del martes ni del día actual». Las promos de
descuento ya se aplicaban solas desde 20261005100000; las de precio fijo (Almuerzos, Combo hamburguesas, Dupleta de papas, Picada + jarra) se dejaron A PROPÓSITO sin regla porque la
regla pedía un descuento. Ahora hay una segunda forma de la misma columna (migración 20261006170000_promo_precio_fijo.sql y sobre docs/sobres/2026-10-06-promo-precio-fijo.sql, los
pega Yonatan: Línea Roja, aparca):
- La regla.
{ "cada": 2, "precio": 50000, "aplica": { "productos": ["<id>"] } }: cada N unidades elegibles de la cuenta cuestan $precio(COP enteros, de 1 a 10.000.000). La regla trae exactamente uno dedescuento/precio(privado.promo_regla_ok, que llama el CHECKproductos_promo_regla_valida, que no cambió; de paso una regla sin ninguno de los dos, que la versión de antes dejaba pasar por un NULL que nadie miró, ya no pasa). La promo sigue valiendo el día que digaproductos.dia_semanade su fila (el combo, el martes) y el día es el de la escritura en Bogotá. - Cómo se cuenta (
privado.normalizar_items). Las unidades elegibles se ordenan de mayor a menor precio (a igual precio, en el orden de la cuenta), como con el descuento; cada grupo completo de N cuesta X: la unidad más barata del grupo sale a la líneapromo:<promo>:<base>con el preciomax(0, X − Σ de las otras N−1 unidades del grupo), y esa línea llevapromo: { id, de, nombre, precio: <el de la base>, precio_fijo: X }(sindescuento; conprecio_manual/precio_porsi su base los tiene). Con la hamburguesa a 30.000 y X = 50.000: 1 → 30.000; 2 → 30.000 + 20.000 = 50.000; 3 → 80.000; 4 → 100.000 (dos grupos). El precio a mano entra en la suma como hoy (cada unidad cuenta con el precio de su línea; la base que la promo se lleva entera conserva su marca y sigue teniendo precio a mano y «Volver al precio de carta»). Es idempotente en la segunda pasada, el pliegue de la línea de promo sin objeto y la adopción del precio a mano del paso a' quedan intactos, y las promos de descuento no cambian ni una clave de su objetopromo. - Decisiones por defecto (a confirmar con Yonatan): (1) nunca más que sin promo: la unidad de promo no cuesta más que su precio de lista y un grupo que ya costaba X o menos NO genera línea
de promo (con la hamburguesa a 20.000 las dos cuestan 40.000 y se quedan en 40.000, no en 50.000); (2) X menor que lo que cuestan las otras (una regla mal puesta, no un caso): la unidad de
promo queda en 0, nunca negativa; (3) una línea que reparte unidades entre grupos de distinto costo (solo con una regla por categoría y precios mezclados y más de un grupo) recibe en su línea de
promo el promedio redondeado a peso de lo que costó cada unidad con promo: la cuenta puede salir distinta de la suma exacta de los grupos por hasta k/2 pesos (k = los grupos de ESA línea: una
unidad de promo por grupo, medio peso de redondeo cada una, por arriba o por abajo; un caso comprobado: 9.999 y 20.000 → 15.000 y 1 peso de más; con 6 grupos puede llegar a 3); con la regla de UN
producto todas las unidades valen lo mismo y es exacto; (4)
public.fijar_precio_itemno se tocó: lo que escribe en una línea de promo cuando la base está absorbida lo recalcula el trigger del precio vivo (trg_ordenes_a_precio_vivo), que pliega la línea de promo y la arma de nuevo connormalizar_items; (5) un solo precio: al guardar una promo de precio fijo desde el POS, el precio del producto —el que muestra la carta pública— pasa a ser el del grupo, siempre (el modal lo muestra en ese campo y no lo deja editar aparte); al pasar a «Descuento %» el producto vuelve a valer 0, como cualquier promo de descuento. - La línea del producto de la promo es una línea de producto más. Antes de la regla el «Combo hamburguesas» es un producto de 50.000 que el mesero agrega a mano —la única forma de venderlo—, y el POS de antes
(una tablet que todavía no recargó) lo sigue vendiendo así.
privado.normalizar_itemsno hace nada especial con esa línea: vale su precio de catálogo (50.000) SIEMPRE, haya o no hamburguesas al lado, ni más ni menos (el paso b es el de la unión, sin cambios; un precio a mano se respeta como en cualquier línea y «Volver al precio de carta» la devuelve a 50.000). Con el par de hamburguesas y esa línea en la misma cuenta se cobran las dos cosas, el grupo (50.000) y el producto (50.000): el combo solo, 50.000; combo + 1 hamburguesa, 80.000; el par + el combo, 100.000; 2 combos + 2 hamburguesas, 150.000; fuera de su día, 60.000 + 50.000. Una venta del combo que se deshace vuelve a la cuenta como lo que es, un combo vendido a su precio. La base no puede saber si esa línea repite el par (una tablet sin recargar, la captura) o es un combo servido de verdad antes de la regla; las primeras versiones intentaron decidirlo en la base (ponerla en 0 siempre, o solo cuando el par se formaba, o contando grupos completos) y cada una regaló combos vendidos de verdad o volvió a cobrar doble. Yonatan eligió simplificar: sin heurística, la línea del producto es una línea de producto. Lo mismo vale para el producto de una promo de descuento con precio propio (el modal lo conserva a propósito y su línea se cobra aparte de su descuento, como desde20261005100000: Entradas de la carta a 12.000 + 2 Patacones un sábado = 27.000) y para un producto con regla fuera de Promociones. Una cuenta sin precio fijo sale byte a byte igual que con la unión20261006140000(el diferencial de las pruebas lo comprueba, con un catálogo de solo descuento y con el catálogo completo en cuentas que ninguna regla de precio fijo alcanza). - El trigger de las cuentas abiertas (RS008). Para que el cobro doble no aparezca por sorpresa al encender la regla, un trigger de
productos(productos_promo_precio_fijo_en_cuentas,BEFORE UPDATE OF promo_regla, activo, funciónprivado.promo_precio_fijo_en_cuentas, SECURITY DEFINER, solo leeordenesyproductos) rechaza con SQLSTATERS008—y se deshace todo el UPDATE— que una promo de precio fijo PASE A APLICARSE SOLA (se le pone la regla de precio fijo donde había una de descuento o ninguna, o se activa una apagada) mientras su producto esté en una cuenta abierta. No mira la categoría:normalizar_itemsaplica toda regla activa, esté el producto en «Promociones» o en cualquier otra, y un trigger que la mirara se esquivaría moviendo el producto de categoría, poniéndole la regla y devolviéndolo. El mensaje separa las mesas en dos, porque la orden correcta no es la misma. Las que tienen además el grupo completo (N o más unidades de lo que la regla alcanza: las 2 hamburguesas) pueden tener la línea del producto repitiéndolo, la captura: esa línea se quita con la ✕ solo si repite el grupo; si es un combo servido de verdad además de las hamburguesas, se cobra la mesa. Las que no lo tienen son un combo vendido de verdad (el producto es la única forma de venderlo antes del sobre): quitarles la línea dejaría de cobrar 50.000 por unidad, así que se cobra la mesa o se cambia la línea por 2 Hamburguesa Resplandor, que con la regla valen 50.000 (combo + Seco = 69.000 antes y después; quitar la línea sin más lo deja en 19.000). La razón «cobraría el producto además del grupo» solo vale para las primeras. Lista hasta 8 mesas de cada clase y cuántas unidades tiene cada una; después se vuelve a intentar. Solo mira cuentas abiertas (una venta ya cobrada no estorba, ni siquiera la que todavía se puede deshacer) y solo la transición: editar la etiqueta, el precio o la descripción de un combo que ya tiene su regla de precio fijo activa no dispara nada, aunque haya cuentas con el producto, y tampoco el upsert del POS (que manda todas las columnas); apagarla o quitarle la regla tampoco. Qué cubre y qué no: cubre la edición de la fila que ya existe (un UPDATE depromo_reglao deactivo) venga de donde venga: el sobre del combo, el modal de producto (Almuerzos y la Dupleta de papas, que Yonatan convertirá desde Productos editando la fila que ya existe) y cualquier escritura del personal con la API que edite esa fila (la RLS deja editar productos a un mesero). No cubre crear el producto otra vez con el mismo id (un INSERT; tampoco el upsert de una tablet con la caché vieja después de un borrado), cambiarle el id a una promo, ni crear otra promo de precio fijo con la misma regla mientras el producto que vendía la anterior sigue en la carta (la base no sabe qué producto vendía cada promo): si Almuerzos o la Dupleta se crean con «Nuevo producto» en vez de editar la fila existente, el producto viejo hay que apagarlo o borrarlo antes, o se sigue vendiendo junto al grupo. Está dicho en la cabecera de la migración y fijado por una prueba (DECLARADO). El POS trata el RS008 como un rechazo definitivo: avisa con el mensaje de la base, suelta la subida pendiente (no la reintenta sola cuando se cobre la última mesa) y vuelve a leer los productos (pushASupabase,esErrorPromoEnCuentas,_promoEnCuentas). Riesgo que queda, dicho tal cual: una tablet que no se recargó, con el sobre ya puesto, todavía ofrece el combo como producto: si lo agrega y además pide las hamburguesas, la cuenta cobra el grupo y el producto (cobro doble, 100.000), y editar el combo desde ella —aunque sea solo la etiqueta— subepromo_regla: nully borra la regla (el par deja de formar el combo, 60.000, y con la línea del producto la cuenta sube a 110.000). Nada de eso tiene arreglo en la base: por eso el orden de salida recarga TODAS las tablets antes del sobre. - Reglas que ya existían, y reglas que no se pueden leer. El validador de antes miraba solo
cadaydescuento(y un NULL en suorlo dejaba seguir), así que producción puede tener filas que el nuevo no acepta (sincada, sindescuento, o con una clavepreciocualquiera junto aldescuento): no se podrían volver a editar ni cambiandoactivo. Por eso la migración es una sola transacción (begin…commit) y, justo después de poner el validador nuevo, revisaproductos.promo_regla: si alguna no pasa, aborta sin cambiar nada (tampoco queda el validador nuevo) con un mensaje que listaid («nombre», regla …)de cada una y dice cómo arreglarla (desde Productos, o conupdate public.productos set promo_regla = promo_regla - 'precio' where id = '<id>', onullpara quitársela). Vale pegada en el SQL Editor o con el arnés de las pruebas. Ademásnormalizar_itemsnunca lanza por una regla rara: una regla queprivado.promo_regla_okno acepta (unprecioque no es entero, los dos o ninguno) se salta, y las demás siguen aplicando (antes un::numericsobre un texto lanzaba y el trigger del precio vivo se tragaba el error, dejando las cuentas de ese día sin precio vivo ni promos). - Volver a pegar una migración anterior. Si alguna vez se vuelve a pegar
20261005100000,20261005130000,20261006110000,20261006130000o20261006140000con el combo ya con su regla, esanormalizar_itemsno sabe de precio fijo: lee eldescuento(null), la línea de promo sale conprecio: null, el total la ignora y cada par se regala sin aviso (2 hamburguesas 30.000, 4 → 60.000, en vez de 50.000 y 100.000). Hay que pegar20261006170000otra vez detrás. La reversa correcta es la de la cabecera de la migración: primero la regla del combo anull, después el validador de antes y por último volver a pegar la unión entera. - Por qué
20261006170000y no20261006140000. La versión VIGENTE denormalizar_itemses la unión20261006140000_normalizar_items_pliegue_y_precio_a_mano.sql(la que pliega y respeta el precio a mano a la vez): cortar de20261006130000con otrocreate or replacehabría borrado el pliegue en silencio, y el prefijo20261006140000ya es de la unión (las pruebas exigen prefijos únicos). Por eso la migración nueva va última de la cadena (después de la lápida y de «servida», que no tocan estas funciones), parte del cuerpo de la unión y se niega a correr, sin cambiar nada, si falta20261006130000o la unión. Si alguna vez se vuelve a pegar una de las que redefinennormalizar_itemsopromo_regla_ok, hay que pegar esta otra vez detrás. - El POS (
pos.html; sin rediseño visual). En el modal de producto, una promoción automática elige «Descuento %» o «Precio fijo del grupo $» (uno u otro; el mensaje de lo que falta cambia con el tipo) yguardarProductoescribe la forma que toca (una de precio fijo tiene UN solo precio, el del grupo —el que muestra la carta pública—, siempre: en el modal el campo de precio del producto muestra el del grupo, no se edita aparte y una línea lo explica; al pasar a «Descuento %» el producto vuelve a 0 si su precio venía del grupo, o recupera el precio propio que tenía antes de mirar «Precio fijo del grupo» ; y al desmarcar «Es una promoción automática» el producto toma el precio del grupo con el que ya se vendía, y si aun así no tiene precioguardarProductolo dice en un aviso en vez de quedarse mudo);reglaPromoValidaacepta las dos formas con las cotas de la base;reglaTxtdice «2 por $ 50.000 en Hamburguesa Resplandor» (el anuncio.promo-hoyde la carta del mesero lo muestra: «Se aplica sola en la cuenta»; las promos con regla no se agregan a mano: el combo deja de ofrecerse como producto, y la carta pública sigue mostrando «Combo hamburguesas $ 50.000»); la línea de promo lleva la pastilla «Combo · 2 por $ 50.000» (pastillaPromo; las de descuento dicen lo de siempre); y_ponerPrecioLocalreparte el grupo conrepartoPrecioFijo(una aproximación de la cuenta de la base: ordena las unidades, suma el grupo, descuenta lo que haga falta a la más barata, pero solo recalcula las promos de la línea que se edita y no mueve cantidades ni mira las unidades que se llevó una promo de nombre posterior) para pintar ya el precio nuevo mientras llega el eco, que es la verdad y lo corrige (el cobro vuelve a leer la base; sin red,_conPreciosPendientesmantiene el número hasta subir). Mientras llega el eco de «agregar la segunda hamburguesa» la pantalla dice 60.000 (la línea toca su precio de catálogo, como siempre); con el eco, 50.000 y la línea de promo.cuentaTendriaPromoya miraba solocadayaplica, así que la cuenta con 2 hamburguesas ya cuenta como «con promoción» para no ofrecer el cobro por partes (y se cobra la mesa completa o por abonos, como con las de descuento). - El sobre de datos (
docs/sobres/2026-10-06-promo-precio-fijo.sql, al final del orden de salida, ver abajo): le pone a «Combo hamburguesas» (categoría Promociones) la regla{ cada: 2, precio: 50000, aplica: { productos: [<id de «Hamburguesa Resplandor»>] } }yprecio = 50000(un solo precio, explícito e idempotente), buscando por nombre y categoría («Platos Fuertes»), en una transacción que aborta sin escribir si no encuentra exactamente una fila de cada nombre o si la migración no está puesta; idempotente, con su reversa. Al correrloproductos_tocan_cuentasre-normaliza las cuentas abiertas: una mesa con 2 hamburguesas un martes queda en 50.000 sola y llega a todas las tablets por Realtime. El sobre se niega (RS008, sin cambiar nada) mientras el «Combo hamburguesas» esté en una cuenta abierta como producto (lo hace el trigger de arriba, no el sobre): el mensaje dice en qué mesas y qué hacer en cada una: donde la mesa tiene además las 2 hamburguesas, la línea se quita con la ✕ solo si repite el par; donde no (un combo vendido de verdad), se cobra la mesa o se cambia la línea por 2 Hamburguesa Resplandor (con la regla valen 50.000: quitarla sin más dejaría de cobrar 50.000); y se vuelve a pegar. Sin ese producto en ninguna mesa abierta, ninguna línea del combo cambia de precio al pegarlo. Una venta ya cobrada con el combo no lo frena y no se toca. - Lo que queda fuera (anotado, no hecho): los combos de productos DISTINTOS («Picada + jarra de Cantarito»: 1 + 1) —la regla de grupo cuenta unidades de lo elegido y no distingue composición—,
y las otras de precio fijo (Almuerzos, Dupleta de papas), que pone Yonatan desde Productos cuando confirme qué incluyen. Con el POS de antes la base calcula bien el grupo (la línea de promo de precio
fijo es una línea de promo cualquiera: id
promo:…y objetopromo), pero ese POS no entiende la regla nueva: la ve como si no tuviera regla, sigue ofreciendo el combo como producto, la pastilla de la línea dice «−undefined % por promoción» y, sobre todo, editar el combo desde esa tablet —aunque sea solo la etiqueta— subepromo_regla: nully borra la regla; y sin red, sucuentaTendriaPromotampoco conoce la regla y deja cobrar: la venta sube ya cerrada, sin pasar pornormalizar_items, y queda al precio normal (60.000). Nada de eso tiene arreglo en la base. Orden de salida (en este orden, sin saltarse ninguno): 1) la migración (si avisa de reglas que el validador nuevo no acepta, las lista: arreglarlas y volver a pegar); 2) el push del POS; 3) recargar TODAS las tablets y comprobar, en el pie de cada una, que muestran la versión nueva (la misma queversion.jsonpublica al aire: el POS nunca se recarga solo); 4) recién entonces el sobre de datos, con el combo fuera de las cuentas abiertas (si no, se niega con RS008 y dice en qué mesas y qué hacer en cada una: se cobran, se cambia la línea por las 2 hamburguesas, o se quita SOLO si repite el par). Anotado y no tocado:cuentaTendriaPromoda por hecho el combo con N unidades aunque el grupo cueste X o menos (2 hamburguesas a mano a 20.000: la base no aplica combo, pero la tablet niega el cobro por partes); es un error del lado conservador. - Pruebas:
migracion-promo-precio-fijo.test.mjs(estática: orden y prefijo, cabecera, diff línea por línea denormalizar_itemscontra la unión (solo el precio fijo y el salto de la regla ilegible) y depromo_regla_okcontra la original, reversa; y contra Postgres 17 en Docker: la captura 1/2/3/4/5 hamburguesas, el día de la escritura, el precio a mano también con la base absorbida por la RPC, X menor que la suma y el grupo que no sube la cuenta, el promedio por categoría, idempotencia, el CHECK como un admin de verdad, las de descuento intactas, el cobro por partes rechazado (RS005), la migración dos veces, mutantes que el cuadro de escenarios tiene que matar (los que quitan el tope del precio de lista o el filtro del grupo que ya costaba X, ponen en 0 la línea del producto del combo —en el paso b o cuando el par se forma— o descomponen el trigger: sin mirar las cuentas abiertas, mirando también las ventas cobradas, disparando al editar una regla igual, sin la transición de activar, solo avisando, sin la variante con nota, mirando otra vez la categoría —al encender o en la fila vieja— o con el mensaje que no separa las mesas con el grupo completo de las que no), la reversa, la negativa sin20261006130000/ sin la unión, la línea del producto del combo (solo: 50.000; con 1 hamburguesa: 80.000; con el par: 100.000; 2 combos + 2 hamburguesas: 150.000; otro día: 110.000; el precio a mano; un abono; el cobro por partes y «Deshacer» completo y parcial, también con el par), el trigger de las cuentas (el sobre y el modal —como admin y como mesero— se niegan con RS008 con el combo o la Dupleta en una cuenta abierta, listando las mesas separadas —con el par, donde la línea se quita solo si repite; sin él, donde se cobra o se cambia la línea—; una venta cobrada no estorba; quitada la línea se aplican; la transición de descuento a precio fijo y la de apagada a activa se niegan, también con el producto FUERA de Promociones y esquivando la categoría (sacarlo, poner la regla); editar la etiqueta, el precio o la descripción de una promo que ya era de precio fijo (dentro o fuera de Promociones), el upsert con todas las columnas, mover su categoría, apagarla o quitarle la regla no disparan nada; seguir el mensaje no cambia lo cobrado —combo + Seco, 69.000 antes y después del sobre, cambiando la línea por las 2 hamburguesas— y lo que el trigger no cuida (un INSERT, otra promo nueva) queda fijado comoDECLARADO), el diferencial (cuentas sin precio fijo, byte a byte contra la unión20261006140000), las filas heredadas (la migración falla y la radiografía queda idéntica; una regla ilegible se salta) y el sobre contra un catálogo con los dos nombres, con su precio único y su negativa con el combo en una cuenta abierta) ypromo-precio-fijo-navegador.test.mjs(estática,vmconnormalizadorDeComboy navegador a 390 y 1280 px)._pos-vm.mjsy_pos-simulado.mjsaprenden el precio fijo.
Cronómetro de la mesa y «servida» (2026-10-06: listo en rama, no está al aire)
Pedidos de Yonatan del 2026-10-06: «al hacer un pedido, un cronómetro sutil para conocimiento de cuánto llevan esperando el pedido los de la mesa» y «también podrá decidir
si fue atendido para que el cronómetro no siga… se le llevó la comida y ahí ya no necesita contar, solo informativo». Solo informa: no bloquea, no avisa, no suena y no
cambia los cobros, la carta del cliente (la Edge Function cuenta lee ordenes por nombre de columna y su marca es la version) ni el cierre del día.
- Qué muestra. En cada mesa ocupada con algo que servir del mapa, un chip pequeño «12 min» (sin segundos; «1 h 05» pasada la hora; «+24 h» pasado un día); en la cabecera
de la cuenta, «Abierta 12:24 p. m. · esperando 12 min». Neutro hasta 20 min, tinte ámbar de 20 a 40 y coral desde 40 (
ESPERA_AMBAR_MIN/ESPERA_CORAL_MINenpos.html), sin parpadeos. Un solosetIntervalde 1 minuto en el store, que se detiene con la pestaña oculta y se pone al día al volver. Las horas, siempre enAmerica/Bogotacon el reloj del aparato; un reloj atrasado respecto de la hora del pedido dice «ahora». Cuenta cerrada o vacía: nada. - Desde cuándo cuenta. La base no guarda la hora de cada ítem; sin migración, el inicio es
abierta_en(la cuenta se abre al tomar el pedido), salvo que esa tablet haya visto llegar el pedido después (la cuenta se abrió vacía) o una tanda nueva a una mesa servida: lo anota enlocalStorage(pos_pedido_en) y el chip/título dicen «Pedido tomado a las 12:24 p. m.». Una lectura de la base nunca inventa la hora del primer pedido; la tanda nueva a una mesa servida sí la reconoce una tablet que tenía la cuenta servida (recargar, volver del bolsillo). Límite: una tablet sin copia previa de la cuenta cuenta desdeabierta_en. - «Servida». Un toque en el chip de la cabecera (o mantenerlo pulsado en la tarjeta del mapa, para no marcarla por error al abrir la mesa) marca la mesa servida: el
cronómetro se detiene y el chip dice «servida 12:41 · esperó 17 min» en neutro; otro toque la quita y vuelve a contar desde el mismo inicio. Si después se agregan ítems, la
tablet que los agrega pone
servida_enen null (después de subir los ítems) y empieza una espera nueva; quitar ítems o que vuelvan unidades por un cobro deshecho no la toca. La marca viaja a todas las tablets (Realtime) y sobrevive a recargar; sin red queda pendiente enlocalStoragey sube sola. - Migración
20261006160000_servida.sql(la aplica Yonatan, antes del push del POS; el POS la detecta y sin ella esconde el toque): UNA columna,ordenes.servida_en timestamptz null. No tocanormalizar_items,aplicar_delta_ordenniordenes_guardia; poner o quitar la marca no subeversion(updated_atsí avanza); la RLS deordenesya lo permite (admin todo; mesero solo cuentas abiertas) yordenesestá ensupabase_realtimesin lista de columnas, así que el eco la trae. El prefijo no es20261006100000(como pedía la tarea) porquecierres_de_hoy_y_cambiosya lo usa, ni20261006140000(con el que nació) porque la rama de la promo con regla ejecutable ya tomó…140000y…150000; las migraciones se ordenan por prefijo, así que esta va después de las dos (…160000). Idempotente, con REVERSA en la cabecera (borra la columna). - Pruebas:
pos-cronometro-mesa.test.mjs(lógica en unvmcon reloj falso),cronometro-mesa-navegador.test.mjs(390 y 1280 px, claro y oscuro, alturas sin cambio, contraste AA medido) ymigracion-servida.test.mjs(estática y contra Postgres 17: quién la escribe, laversionno sube, Realtime, dos veces, reversa). Diseño visual:docs/pos-visual.md§0.27.
08 — Contrato de datos
| Tipo | Operación | Descripción |
|---|---|---|
AUTH | store.iniciarSesionGoogle() | Redirige a Google OAuth vía Supabase Auth |
AUTH | store.cerrarSesion() | Cierra sesión y limpia usuario |
ACTION | store.abrirMesa(mesaId) | Crea orden vacía; si la BD rechaza por duplicado, adopta la orden real (resolverConflictoDeMesa) |
ACTION | store.agregarItem(...) / quitarItem(itemId) | Modifican la orden activa |
ACTION | store.facturar() | Cierra orden, libera mesa, genera ticket |
ACTION | store.cerrarDia() | Genera CierreDiario, purga órdenes archivadas de Supabase, reintenta si falla |
CRUD | store.productos | CRUD completo, restringido a authenticated por RLS |
REALTIME | Canal pos_sync | Escucha postgres_changes en mesas, ordenes, productos |
REALTIME | Canal presencia_pos | track() de {mesaId, deviceId, nombre}; no toca Postgres |
RPC (ola B) | mi_rol(), mi_correo() | El rol (admin | mesero | null) y el correo de Google de quien llama; el POS decide qué mostrar |
RPC (ola B) | personal_alta(p_email, p_nombre, p_rol), personal_baja(p_email), personal_cambiar_rol(p_email, p_rol) | Gestión del personal, solo admin; responden {ok, codigo?} (ultimo_admin, ya_existe, no_autorizado…) |
RPC (ola B) | atender_alerta(p_id), descartar_alerta(p_id) | El personal resuelve una alerta pendiente; si otra tablet llegó antes, {ok:false, codigo:'no_pendiente'} |
RPC (ola B, solo service_role) | alertar_cuenta(p_mesa, p_token, p_metodo) | La única puerta de escritura del cliente de la pegatina: la ejecuta la Edge Function alerta |
RPC (ola C) | solicitar_acceso() | Quien entra con Google pide acceso: crea su fila pendiente. Responde {estado: 'pendiente' | 'aprobado' | 'eliminado', rol}; una persona eliminada no se resucita |
RPC (ola C) | vista_pendiente() | Lo único que ve un pendiente: id, capacidad y estado de las mesas activas. Sin token, totales ni órdenes |
RPC (ola C) | personal_aprobar(p_email, p_rol), personal_eliminar(p_email) | Solo admin; responden {ok, codigo?} y nunca dejan la tabla sin un admin aprobado y activo |
RPC (ola C) | mesa_crear(p_id, p_capacidad), mesa_editar(p_id, p_capacidad), mesa_activar(p_id, p_activa), pegatina_marcar(p_id, p_tipo, p_token) | Panel de Mesas y pegatinas, solo admin; ya_existe, con_cuenta_abierta; p_tipo es 'escrita' o 'revisada'; p_token es el que de verdad se escribió o se leyó: si la mesa ya tiene otro (giraron el enlace mientras tanto) responde enlace_cambio y no marca nada. La capacidad va de 1 a 50 (mesas_capacidad_rango) |
RPC (ola C) | deshacer_cobro(p_orden_id) | Deshace un cobro del turno: un parcial o un abono vuelven a la cuenta de la misma mesa; el cobro completo reabre la mesa o pasa a la cuenta que ya tiene. Admin y mesero, sin ventana. {ok, tipo, total_abierta, orden_id, mesa_id, monto, version, reabierta, fusionada} o {ok:false, codigo}: cuenta_ya_cerrada, no_es_parcial, mesa_inactiva, ya_en_cierre, no_autorizado, no_existe, ya_reabierta, mesa_ocupada. Deja su fila en deshechos. Si la cuenta que recibe la línea ya tiene ese plato, manda su precio y su marca de precio a mano (§ «Precio a mano por línea del pedido») |
RPC (ola C) | cerrar_dia(p_id, p_esperado) | El cierre del día lo decide la base (solo admin, una transacción): toma todas las ventas cerradas que ningún cierre se llevó, rechaza si hay una cuenta abierta o si lo que el POS espera (p_esperado: {n, total, ids}) no es lo que hay, guarda el cierre, borra lo que archiva y marca los deshechos del turno con el id del cierre. Nunca borra una cuenta abierta. {ok, repetido, n, total, borradas, cierre, deshechos} o {ok:false, codigo}: no_autorizado, invalido, hay_abiertas, sin_ventas, cambio (con el resumen de la base) |
RPC (cobro atómico, 20261005140000) | cobrar_parcial(p_orden_id, p_version, p_venta, p_lineas, p_delta_id) | Cobra por partes (por ítems, por unidades o por persona) UNA cuenta abierta, en una transacción y bajo candado: p_version es la que la tablet vio (RS003 si cambió), p_venta = {id}, p_lineas = [{id, qty}], p_delta_id identifica el cobro (repetirlo devuelve lo mismo sin duplicar). Rechaza una cuenta con promoción (RS005, «por partes») o archivada en un cierre (RS005) y lo que la cuenta no tiene (RS006). Inserta la venta cerrada con parcial_de, saca esas unidades y devuelve {ok, repetido, venta, cuenta}. Admin y mesero; SECURITY INVOKER |
RPC (cobro atómico, 20261005140000) | cobrar_abono(p_orden_id, p_version, p_venta, p_monto, p_metodo, p_delta_id) | El abono, lo mismo: p_venta = {id, uid}, p_monto entero menor que lo que falta, p_metodo efectivo, qr o transferencia; pone la venta «Abono» y la línea abono_recibido_<uid> juntas. Sí entra en una cuenta con promoción |
RPC (2026-10-05) | cerrar_dia_de(p_id, p_dia, p_esperado) | El cierre de UN día en Bogotá (hoy o uno pasado sin cerrar), solo admin: solo las ventas de ese día (hoy, también las de «mañana» por un reloj adelantado: 20261006120000); hoy exige las mesas cobradas, un día pasado no; el cierre de un día pasado lleva la fecha de ese día. {ok, repetido, n, total, borradas, dia, cierre, deshechos} o {ok:false, codigo}: no_autorizado, invalido, hay_abiertas, sin_ventas, cambio |
RPC (2026-10-05) | cierre_corregir_nota(p_cierre_id, p_nota), cierre_anular(p_cierre_id, p_motivo) | Panel de cierres, solo admin; la nota (hasta 500) no toca ningún peso; anular (motivo de 3 a 300) no borra nada, devuelve las ventas a las ventas por cerrar y suelta los cobros deshechos del cierre (responde deshechos: cuántos). nota_larga, anulado, ya_anulado, motivo_requerido, mesa_inexistente, no_existe |
TABLE (2026-10-05) | cierres_cambios | El rastro de los cierres: quién, cuándo, acción (cierre, nota, anulado, venta_sacada, edicion), motivo, antes, después y detalle. La escribe solo trg_cierres_rastro; solo el admin la lee; solo se agrega |
TABLE (ola C) | deshechos | Cada cobro deshecho: orden, mesa, tipo, monto, ítems, quién (correo) y cuándo. Solo la escribe deshacer_cobro; solo el admin la lee; 90 días |
ACTION (ola C) | deshacerUltimoCobro(), devolverACuenta(ordenId), cargarDeshechos() | El aviso «Cobrado $ X · Deshacer» (15 s), «Devolver a la cuenta / Deshacer el cobro» en «Transacciones del turno» y «Cobros deshechos hoy» en el cierre |
ACTION (ola C) | guardarAjustes(cambios), cargarAjustes() | Ajustes del ticket (dirección del QR, QR visible, pie); solo admin escribe |
RPC (cola de impresión) | impresora_estado(), impresion_cancelar(p_id) | El personal: qué cajas hay y si están en línea; cancelar un trabajo que nadie tomó, o que la caja tomó y lleva más de 2 min sin confirmar (antes de caer a window.print() o al cerrar el aviso) |
RPC (cola de impresión, solo admin) | impresora_crear(p_nombre), impresora_rotar(p_id), impresora_activar(p_id, p_activa) | Alta, token nuevo (el viejo deja de servir) y baja de una impresora; {ok, id, token} con el token en claro una sola vez |
RPC (cola de impresión, con el token) | impresora_tomar(p_token, p_max), impresora_confirmar(p_token, p_id, p_ok, p_error), impresora_latido(p_token, p_version) | Las tres del agente del PC de la caja; ejecutables por anon, autenticadas por el token |
ACTION (cola de impresión) | pedirImpresion(que, persona?), aceptarImpresion(), cancelarImpresion() | Imprimir siempre a la caja con una confirmación: pedirImpresion('precuenta' | 'ticket', persona) abre el modal (confirmaImpresion) y NO manda nada; aceptarImpresion() manda UN trabajo (o, en la emergencia, imprime en el teléfono); cancelarImpresion() lo cierra |
ACTION (cola de impresión) | imprimirCuentaEnCaja(persona?), imprimirTicketEnCaja(), crearImpresora(), rotarImpresora() | Lo que hace el «Imprimir en la caja» del modal (no preguntan: a la pantalla se llega por pedirImpresion; con caída al teléfono) y gestionan la impresora desde la vista «Impresora de la caja» (tarjeta del tablero de Administración) |
REALTIME (cola de impresión) | Canal pos_impresiones | postgres_changes de impresiones filtrado por creada_por: el estado en vivo de lo que ese teléfono mandó |
ACTION (ola B; cobro atómico desde 20261005140000) | facturarParcial (ítems o unidades), cobrarGrupoPersona y cobrarMonto | Cobran una parte con UNA llamada a cobrar_parcial / cobrar_abono (_cobrarEnBase) y adoptan la venta y la cuenta que devuelve la base. Necesitan red: sin ella no se cobra ni se encola nada. La mesa sigue abierta |
09 — Flujos principales
Flujo 0 — Login (nuevo)
- El dispositivo abre la app → ve la pantalla "Continuar con Google" si no hay sesión.
- Tras loguearse, Supabase redirige de vuelta a la misma URL con la sesión activa.
- La app arranca: carga caché local, sincroniza con Supabase, abre los canales Realtime.
Flujo A — Pedido completo (sin cambios de fondo, con protección nueva)
- Seleccionar mesa — si dos meseros la abren casi al mismo tiempo, la base de datos garantiza que solo una orden gane; el segundo dispositivo adopta la orden real automáticamente, sin duplicar nada.
- Agregar ítems / ítem manual — igual que antes. Opcional: «Agregar para llevar» (junto al buscador), «Para llevar» en cada línea y «Todo para llevar» en la cabecera del pedido (
docs/para-llevar.md). - Ver aviso de presencia — si otro dispositivo también tiene la mesa abierta, aparece un banner con su nombre antes de facturar.
- Generar ticket y cobrar — genera ticket, libera la mesa, libera la presencia.
- Imprimir (opcional, sin cobrar) — «Imprimir precuenta» (toda la cuenta) o, con la cuenta dividida por persona, el «Precuenta» de cada fila (solo lo de esa persona): pregunta «¿Imprimir la precuenta en la caja?» y nada sale hasta confirmar (§07, «Imprimir en la caja»).
Flujo B — Cierre del día
Sin cambios de flujo para el usuario; internamente, si falla la subida del cierre, queda en cola (colaPendiente) con reintento automático cada 20s y al recuperar conexión.
10 — Sincronización multi-dispositivo
Mecanismos vigentes
| Mecanismo | Qué resuelve |
|---|---|
Postgres Changes (pos_sync) | Refleja cambios de fila entre dispositivos (abrir mesa, agregar ítem, facturar) |
Cola colaPendiente | Si falla la subida de un cierre, no se pierde — se reintenta automáticamente |
cerrarDia() purga ordenes | Evita que órdenes archivadas "reaparezcan" fantasma en otro dispositivo al recargar |
Índice único mesa_id + 'abierta' | Garantiza a nivel de base de datos que nunca haya dos órdenes abiertas para la misma mesa |
resolverConflictoDeMesa() | Cuando la base de datos rechaza una orden duplicada, el dispositivo perdedor adopta la orden ganadora sin intervención del mesero |
| Realtime Presence | Visibilidad humana de "quién más está aquí", complementaria (no sustituye) a la garantía de la base de datos |
Principio
Desde el incidente de mesas duplicadas, la regla es: cualquier invariante de negocio que dependa de "solo debería pasar una vez" se refuerza en Postgres, no solo en el cliente. El cliente puede tener bugs, race conditions o quedarse con caché vieja; la base de datos es la última línea de defensa.
11 — Incidentes resueltos
Esta sección documenta bugs reales encontrados en producción, para que no se repitan.
11.1 — Fuga de datos por policies anon legacy
Síntoma: un fetch sin login a la tabla cierres devolvía datos de ventas reales.
Causa: la tabla cierres existía desde antes de la migración completa a Supabase, con policies (cierres_select_publico, cierres_insert_publico) que la migración de seguridad no detectó por tener nombres distintos a los esperados.
Fix: se eliminaron esas policies; hoy las 4 tablas solo tienen acceso para authenticated.
Lección: al migrar políticas de seguridad, verificar el nombre real de las policies existentes (pg_policies), no asumirlo por el nombre usado en un script anterior.
11.2 — Órdenes duplicadas por condición de carrera
Síntoma: una misma mesa mostraba pedidos distintos en dos dispositivos (uno con ítems, otro vacío); coincide con reportes previos de "órdenes vacías duplicadas" en exportes de la tabla.
Causa: abrirMesa() confiaba en el estado local (mesa.estado === 'libre') para decidir si crear una orden nueva. Si dos dispositivos leían "libre" antes de que la primera escritura propagara, ambos creaban una orden nueva para la misma mesa.
Fix: índice único parcial en ordenes(mesa_id) WHERE estado = 'abierta' + manejo de conflicto en el cliente (resolverConflictoDeMesa) que adopta la orden ganadora.
Lección: ninguna invariante de "solo uno a la vez" puede depender solo de lógica de cliente en un sistema multi-dispositivo.
11.3 — Bindings snake_case filtrados al template
Síntoma: el total de una mesa ocupada nunca aparecía en el mapa de mesas; la hora de apertura de la orden siempre mostraba la hora actual; "Transacciones del turno" mostraba el número de mesa en blanco.
Causa: 5 lugares del HTML leían mesa_id / abierta_en / cerrada_en directo sobre objetos ya convertidos a camelCase por parseOrden().
Fix: corregidos a mesaId / abiertaEn / cerradaEn.
Lección: el boundary camelCase ↔ snake_case (sección 04) es fácil de romper por copiar-pegar de un objeto crudo de Supabase; revisar siempre contra qué objeto está apuntando un x-text antes de nombrar el campo.
12 — Fases de desarrollo
| Fase | Estado |
|---|---|
| 1 — UI Kit & Design System | ✅ Completa |
| 2 — Gestión de Menú (CRUD productos) | ✅ Completa |
| 3 — Motor de Pedidos | ✅ Completa |
| 4 — Facturación & Ticket | ✅ Completa |
| 5 — Cierre & Reportes | ✅ Completa |
| 6 — Migración a Supabase (Postgres + Realtime) | ✅ Completa |
| 7 — Confiabilidad de sincronización (colas, reintentos, purga) | ✅ Completa |
| 8 — Realtime Presence | ✅ Completa |
| 9 — Login con Google + RLS | ✅ Completa |
| 10 — Fix de condición de carrera (mesas duplicadas) | ✅ Completa |
| 11 — Fotos de producto (Supabase Storage) | ⏳ Pendiente |
| 12 — Resumen de cierre con IA | ⏳ Pendiente |
| 13 — Roles diferenciados (admin vs. mesero) | 🔧 La compuerta ya está al aire (2026-09-30, con Yonatan como único admin). Listos en ramas y probados en local: los permisos por rol, las alertas y el POS de la ola B; faltan por salir, con el GO de Yonatan y en el orden de §07 |
| 14 — Aprobación del personal, mesas y pegatinas, ticket configurable y deshacer cobros (ola C) | 🔧 Listo en ramas y probado en local; sale después de la ola B, con el GO de Yonatan y en el orden de §07. Google sale de Testing solo con esta ola al aire |
13 — Decisiones fijas
| Área | Decisión | Razón |
|---|---|---|
| Estructura | Single-file HTML | Sin build, sin servidor propio |
| Scripts de terceros | Archivos locales de versión fija en assets/vendor/, nunca un CDN ni una versión flotante (pos-sin-cdn.test.mjs lo vigila) | Si la red del teléfono no alcanzaba un CDN, el POS quedaba sin estilos y sin funciones (2026-10-01). Las fuentes de Google siguen siendo externas: si fallan, cae a la tipografía de respaldo |
| Persistencia | Híbrida: localStorage (caché/cola) + Supabase (verdad) | localStorage solo ya no basta con múltiples dispositivos |
| Login | Google OAuth obligatorio, para toda la app | Es la base para que RLS pueda cerrar el acceso anónimo |
| Seguridad | RLS restringido a authenticated, cero acceso anon | La anon key es pública por diseño; el control real vive en las policies |
| Concurrencia | Invariantes "solo uno a la vez" se refuerzan en Postgres (constraints/índices), nunca solo en el cliente | Ver incidente 11.2 |
| Reactividad | Alpine.js v3 | Sin cambios respecto a v1.0 |
| IDs | crypto.randomUUID() / equivalente propio (uid()) | Sin cambios |
| Precio | COP, sin decimales | Sin cambios |
| Acceso (ola B) | Cuenta de Google y fila activa en personal, con rol mesero o admin; la base hace cumplir los permisos | La compuerta cierra el hueco de «cualquier cuenta de Google» y permite sacar Google de Testing (§07) |
| Caja (ola B) | Caja = admin; el cierre del día es solo del admin | Yonatan, 2026-09-30. Un tercer rol solo si aparece un cajero que no deba tocar catálogo, menú ni personal |
| Catálogo (ola B) | El mesero crea y edita productos; borrar es del admin | Yonatan, 2026-09-30 |
| Propina | No se pide, no se sugiere ni se registra, en ningún lado | Yonatan, 2026-09-30: «eso no se hace acá» |
| Pagar (ola A y B) | El cliente elige el método y eso avisa al personal; el mesero cobra y cierra en el POS. Desde 2026-10-02 (Bre-B): con una cuenta abierta y el interruptor encendido, «QR (Bre-B)» convierte la hoja en el QR de pago del restaurante, con su llave y «Enviar comprobante por WhatsApp»; los datos los carga el admin en ajustes (nunca en el repo) | Yonatan, 2026-10-02: «hazlo dinámico y si selecciona pagar, abrir QR de Bre-B». Reemplaza «ninguna página muestra a dónde pagar»; el costo (un clon de la pegatina podría mostrar otra llave) lo frenan la contraseña de escritura y la revisión diaria (docs/sdd-cuenta-en-mesa.md, aviso del inicio) |
| Aprobación del personal (ola C) | Quien entra con Google pide acceso y queda pendiente; un admin lo aprueba (mesero o admin) o lo elimina. Un pendiente solo ve el mapa de mesas y la carta | Yonatan, 2026-09-30: «si no se aprueba solo podrá ver, no podrá hacer nada más». Reemplaza el alta solo por correo y deja sacar Google de Testing sin abrir el POS a cualquier Gmail |
| Google fuera de Testing | Solo con la ola C al aire | Yonatan, 2026-09-30. La compuerta sola deja un callejón sin salida; con la aprobación, el pendiente ve el mapa y la carta |
| Mesas y pegatinas (ola C) | El admin crea, edita, desactiva y rota mesas, y escribe y revisa la pegatina desde el POS con Web NFC. Las mesas no se borran: se desactivan. Nunca makeReadOnly. La contraseña PWD/PACK (D16) va con NFC Tools | Yonatan, 2026-09-30: «debemos poder añadir y editar pegatinas». Bloquear una pegatina para siempre impediría rotarla |
| Ticket configurable (ola C) | La dirección del QR, si sale y el pie se cambian desde Ajustes (solo admin); el QR se dibuja en el navegador | Yonatan, 2026-09-30: «puede cambiar el dominio» |
| Deshacer un cobro (ola C) | Se puede deshacer un cobro parcial, un abono o el cobro completo de una mesa: el admin y el mesero, en cualquier momento (sin ventana de tiempo), mientras el cobro siga en el turno | Yonatan, 2026-09-30: «tipo ctrl+z»; 2026-10-01: «el pedido se podrá deshacer cuando quiera el mesero o el admin». Editar en el sitio y eliminar una venta cerrada siguen siendo solo del admin |
| Trazabilidad de lo deshecho (ola C) | Cada deshacer queda en deshechos (quién, mesa, monto, hora) y el admin lo ve en el cierre del día: «Cobros deshechos hoy». No limita al mesero | Yonatan, 2026-10-01. Resuelve D37 (antes: «¿deja un registro?»). 90 días de retención (privacidad) |
| Alertas (ola C, D28) | Una alerta resuelta se borra un día después | Guarda el correo de quien la atendió: minimización (Ley 1581). privacy.html lo dice |
| Cobro por partes (ola B) | Por ítems, por unidades de una línea y por monto; el abono es una línea de precio negativo en la orden abierta | El total de la orden es lo que queda, y el cierre del día cuadra solo |
| Versión del sitio y aviso de versión nueva | Una versión (version.json, scripts/version.mjs) que sale del contenido; cada página la lleva sellada y firmada («Ynt-labs · versión X»). Solo el POS avisa, con una franja que no interrumpe, y recargar es siempre un toque de la persona (§04, «La versión del sitio») | Yonatan, 2026-10-02: «sí, agrega el aviso de versión nueva» y «en pie de página ynt-labs + versión». GitHub Pages cachea 10 minutos y el POS pasa el día abierto |
| Para llevar (2026-10-02) | Opcional y sin migración, en dos niveles: por producto (el token Para llevar al final de la base de la nota de la línea) y el pedido completo (una línea de $0 con id fijo para_llevar). El marcador no es un producto: fuera de «N ítem(s)», de dividir, de los cobros por unidades y de los abonos; una cuenta que solo lo tiene no se cobra. No cobra empaque (Yonatan, 2026-10-03): es solo una marca | Yonatan, 2026-10-02: «qué pasa si piden algo para llevar… un ítem no obligatorio para identificar si es para llevar el producto, no el pedido completo… pero también el pedido completo». Viaja por caminos que ya existen: nada que aplicar ni desplegar |
14 — Estructura del HTML
pos.html
│
├── <head>
│ ├── Fonts (Google) y scripts locales de assets/vendor/ (Tailwind, Alpine, Lucide, Supabase JS, qrcode-generator)
│ └── <style> — design tokens reales (sección 05), componentes, print
│
├── <body x-data x-init="$store.pos.init()">
│ ├── <script> — Alpine.store('pos', {...}) con:
│ │ Auth (usuario, iniciarSesionGoogle, cerrarSesion)
│ │ Presencia (deviceId, presenciaMesas, iniciarPresencia, actualizarPresencia)
│ │ Sync (parseX/formatX, pushASupabase, procesarCambioEnVivo)
│ │ Lógica de negocio (abrirMesa, facturar, cerrarDia, resolverConflictoDeMesa)
│ │
│ ├── [Gate] Pantalla de login — visible solo sin sesión
│ │
│ └── <div x-show="$store.pos.usuario"> — todo lo demás, solo con sesión:
│ ├── Nav (mesas/productos/cierre + badge de usuario + logout)
│ ├── Vista Mesas (con badge de presencia)
│ ├── Vista Orden (con banner de conflicto de presencia)
│ ├── Vista Ticket
│ ├── Vista Cierre
│ ├── Vista Productos
│ └── Modales (producto, ítem manual, confirmar cierre)
15 — Componentes
| Componente | Novedad en v2.0 |
|---|---|
LoginGate | Pantalla fija que reemplaza toda la app sin sesión |
MesaCard | Ahora incluye badge de presencia (punto ámbar pulsante) |
OrdenPanel | Ahora incluye banner de conflicto de presencia |
NavBar | Ahora incluye avatar, nombre y botón de logout |
Resto (CatalogoGrid, TicketView, ProductoCRUD, CierreView) | Sin cambios funcionales |
16 — Checklist de producción
- Login con Google funcionando de punta a punta
- RLS verificado: cero acceso sin autenticar (
fetchanónimo devuelve vacío/error) - Índice único de una orden abierta por mesa, verificado en la base real
- Presence mostrando nombres reales, no dispositivos anónimos
- Bindings camelCase corregidos en las 5 vistas afectadas
- Probar apertura simultánea de una mesa desde dos dispositivos reales (la garantía es de base de datos, pero vale confirmar la UX del lado perdedor)
- Definir roles admin/mesero: decididos por Yonatan (caja = admin; el mesero crea y edita productos; el mesero ve ventas y cierres en solo lectura) y probados en local
- Aplicar la compuerta de personal y verificar con
mi_rol()(2026-09-30, de noche; solo con Yonatan como admin: Camila y los meseros quedan para la ola B o la C) - Publicar el POS de la ola B y recién entonces aplicar
permisos_por_rol - Dar de alta a Camila y a los meseros (con el panel Personal de la ola B, o aprobándolos con la ola C)
- Ola C: aplicar las cuatro migraciones (
aprobacion_personal,mesas_y_pegatinas,ajustes_ticket,deshacer_cobro), despuéscuentay por último el POS (§07, «Arranque seguro») - Solo con la ola C al aire, sacar Google OAuth de Testing (D23)
- Revisar en una mesa real: escribir y revisar una pegatina desde Android, y deshacer un cobro parcial con la cuenta abierta (
docs/pegatinas.md; SDD §12.9) - Fotos de producto (Storage) — próxima fase
- Resumen de cierre con IA — próxima fase