# Flujo de localización y entrega de órdenes ## Dirección utilizada por el QR El QR contiene una URL autenticada hacia la orden, no solamente el folio. La variable `APP_QR_ENTRY_URL` debe apuntar al `index.php` que sea accesible desde el dispositivo lector. En desarrollo local se usa la IP LAN de la PC y el celular debe estar conectado a la misma red. `localhost` no debe utilizarse en esta variable porque desde un celular se refiere al propio teléfono. Ejemplo local: ```dotenv APP_QR_ENTRY_URL="http://192.168.100.12/SASS-COMPRAVENTA/lavansys/backend/web/index.php" ``` En producción se sustituirá por la URL HTTPS del dominio. El empleado debe iniciar sesión; después de autenticarse podrá consultar y entregar la orden conforme a sus permisos. ## Identificación inmediata al abrir una orden La pantalla a la que conduce el QR muestra primero una señal visual con la situación y la acción recomendada: - **Ámbar, cobro pendiente:** presenta el saldo y lleva directamente al formulario de pago o abono. Si la ropa está lista, la entrega permanece bloqueada hasta liquidar el saldo. - **Turquesa, lista para entregar:** confirma que no existe saldo y permite marcar la entrega desde la señal principal. - **Verde, entregada:** muestra un icono de confirmación y señala que el proceso terminó. - **Azul, recibida sin saldo:** informa que el cobro está completo y que el siguiente paso es terminar el servicio. - **Rojo, cancelada:** distingue una orden cerrada que no debe continuar. Los botones sólo se muestran cuando el usuario cuenta con el permiso correspondiente. La validación del servidor sigue impidiendo entregar cualquier orden con saldo pendiente. ## Ticket de recepción y etiqueta de bolsa Después de crear una orden, el detalle muestra una guía breve para decidir cuándo imprimir, sin duplicar los botones de la pantalla: 1. Si el cliente paga al recibir, se usa la acción principal **Cobrar ahora** y después **Imprimir ticket** en la cabecera. 2. Si el cliente pagará después, se usa **Imprimir ticket** en la cabecera y el comprobante muestra claramente el saldo pendiente. 3. La etiqueta QR para la bolsa se imprime por separado; no sustituye el comprobante que recibe el cliente. El ticket puede reimprimirse desde el detalle de la orden y utiliza el ancho de 58 u 80 mm configurado en **Mi lavandería**. Incluye información comercial, sucursal, folio, recepción, entrega estimada, cliente, partidas, total, pagos vigentes, saldo, notas, mensaje personalizado y QR. La información se consulta al momento de imprimir, por lo que cualquier reimpresión refleja los pagos y el saldo actuales. La impresión requiere el permiso `order.printTicket`; las consultas permanecen limitadas a la lavandería y sucursal asignadas al usuario. ## Cobro en efectivo y cambio Al seleccionar el método con código `cash`, el formulario solicita dos importes distintos: - **Importe aplicado:** cantidad que reduce el saldo de la orden y que se registra como ingreso en caja. - **Efectivo recibido:** billetes y monedas entregados físicamente por el cliente. El sistema calcula `cambio = efectivo recibido - importe aplicado` en tiempo real. No permite confirmar si el efectivo recibido es menor que el importe. Para pagos que no sean en efectivo, estos campos no aparecen y sus valores se guardan como nulos. Ejemplo: para un saldo de `$340.00`, el importe aplicado es `$340.00`; si el cliente entrega `$500.00`, el cambio mostrado y guardado es `$160.00`. Caja recibe contablemente `$340.00`, no `$500.00`. El efectivo recibido y el cambio se conservan en `payments`, aparecen en el historial de pagos y se incluyen en las reimpresiones del ticket. Los registros anteriores permanecen válidos con ambos campos vacíos. ### Experiencia de punto de venta Cuando se selecciona efectivo, el panel de cobro presenta el monto aplicado, una captura amplia para el efectivo recibido, botones rápidos de importe exacto y denominaciones comunes, y un bloque destacado con el cambio para el cliente. Si falta efectivo, el bloque cambia a advertencia y el botón de cobro permanece deshabilitado. Al confirmar mediante **Cobrar e imprimir ticket**, el sistema registra el pago y redirige al comprobante actualizado con `print=1`; el navegador abre automáticamente su diálogo de impresión. Por seguridad, los navegadores normales no permiten imprimir silenciosamente. Una sucursal que requiera impresión directa deberá configurar posteriormente el navegador en modo kiosco y una impresora térmica predeterminada. Después del diálogo de impresión, la pantalla del ticket ofrece: - reimprimir el ticket; - imprimir la etiqueta para bolsa en formato térmico de 58/80 mm; - imprimir la etiqueta centrada en una hoja A4 con una impresora normal; - volver al detalle de la orden. En el detalle de la orden, **Etiqueta para bolsa** agrupa ambos formatos en un solo menú para evitar acciones duplicadas. ### Preferencia de impresión por equipo El formato de la etiqueta se guarda en `localStorage` con la clave `lavansys.labelPrintFormat`. La preferencia pertenece al navegador y equipo del puesto de trabajo, porque una misma lavandería puede usar una impresora térmica en caja y una impresora normal en otra computadora. El valor inicial es `thermal`. Al elegir `normal` o `thermal`, el botón principal de etiqueta conserva esa selección para las siguientes órdenes y también para la pantalla posterior al cobro. La preferencia no genera consultas a la base de datos, no se sincroniza entre equipos y puede cambiarse en cualquier momento desde el selector junto al botón. ## Objetivo Permitir que una lavandería con alto volumen localice y entregue una orden en pocos pasos desde una PC, teléfono o lector, sin obligar al personal a registrar etapas internas de lavado. ## Estados visibles El flujo operativo es: `Recibida → Lista → Entregada` `Cancelada` permanece como salida excepcional y requiere motivo. Los estados históricos `washing`, `drying` e `ironing` se conservan sólo para compatibilidad y pueden pasar directamente a `Lista`. Una orden con saldo pendiente nunca puede marcarse como entregada. ## Identificación física - Cada orden mantiene su folio legible. - Cada orden recibe un token aleatorio, único y no secuencial. - La etiqueta de bolsa muestra folio, cliente, entrega estimada y un QR que apunta al token. - La etiqueta no muestra importes ni datos sensibles. - El enlace del QR exige que el empleado inicie sesión y valida lavandería y sucursal. ## Localizar y entregar La pantalla está diseñada para PC y móvil y admite: - folio completo o parcial; - nombre del cliente; - teléfono; - enlace o QR con token seguro. La búsqueda se realiza por AJAX, devuelve un máximo acotado de coincidencias y prioriza órdenes listas. Las entregadas y canceladas se excluyen de forma predeterminada. Cada resultado presenta folio, cliente, teléfono, recepción, entrega estimada, estado y saldo, con una acción contextual: - `Marcar como lista` si está recibida; - `Cobrar saldo` si está lista y tiene adeudo; - `Entregar` si está lista y liquidada; - `Ver` para consulta. ## Flujo de mostrador 1. Se recibe la ropa y se crea la orden. 2. Se imprime una etiqueta para la bolsa y un comprobante para el cliente. 3. Al terminar el trabajo se localiza o escanea la orden y se marca como lista. 4. Al regresar el cliente se busca por folio, nombre, teléfono o QR. 5. Si existe saldo, se registra el pago con una caja abierta. 6. Una vez liquidada, se confirma la entrega. 7. El sistema conserva fecha, hora y usuario responsable en el historial. ## Reglas de seguridad y concurrencia - Todas las consultas se restringen por `tenant_id` y, para empleados asignados, por `branch_id`. - El token no contiene IDs ni información personal. - Los cambios de estado usan transacción y bloqueo de fila. - Una orden entregada no puede entregarse nuevamente. - Cobros manuales requieren una caja abierta. - Las acciones modificadoras usan POST y protección CSRF.