# Progreso de LavanderOS

> Desde el 4 de septiembre de 2026, el nombre comercial del producto es **LavanderOS** y su eslogan es **“El sistema operativo de tu lavandería.”** Los identificadores técnicos heredados `lavansys` se conservan temporalmente por compatibilidad.

**Actualizado:** 5 de septiembre de 2026

## Estado funcional

- Repositorio independiente en `luisangel/lavansys` y rama `main`.
- Yii2 Advanced sobre PHP 8.0 y MySQL/MariaDB.
- Diseño administrativo Pick Admin adaptado a LavanderOS.
- Experiencia visual unificada en plataforma, administración, catálogos, operación y pagos: encabezados, tarjetas, tablas, formularios, estados vacíos, acciones y adaptación responsive compatibles con los temas del personalizador.
- Login, cierre de sesión, activación de cuenta y perfil propio.
- Administración de usuarios, roles, permisos y menús.
- Política mínima de contraseña: 10 caracteres.
- La administración global de usuarios muestra la lavandería y sucursal asociadas; el superadministrador puede activar cuentas pendientes definiendo una contraseña inicial e invalidando el enlace de correo.
- Roles base protegidos: `super_admin`, `owner`, `cashier`, `operator`.
- 50 permisos granulares del catálogo actual.
- Menú inicial: Resumen, Usuarios, Roles y permisos, Menús.
- SMTP y CCO de monitoreo configurables por `.env`.
- Redis y Node.js fuera del MVP.
- Fechas propias almacenadas como `DATETIME` en UTC; RBAC conserva timestamps UNIX por compatibilidad con Yii2.
- Catálogos multi-tenant de clientes y servicios con cobro por kilogramo, pieza o paquete.
- Identidades externas preparadas en base de datos para el futuro acceso con Google y redes sociales.
- Perfil editable “Mi lavandería” con datos fiscales, identidad visual, logotipo validado y preferencias de ticket.
- Carga guiada de logotipo con vista previa y validación de formato, peso y dimensiones; se despliega proporcionalmente en tickets y etiquetas de bolsa.
- Centro de bienvenida para propietarios con progreso automático, próximos pasos, métricas y accesos directos a la configuración inicial.
- Las pantallas de clientes, servicios y pagos explican su propósito y muestran la siguiente acción recomendada para reducir la curva de aprendizaje.
- Órdenes con folio consecutivo por sucursal, partidas históricas, totales recalculados en servidor y flujo visible simplificado `Recibida → Lista → Entregada`.
- Integridad compuesta tenant/recurso en órdenes y bloqueo de fila para transiciones concurrentes.
- Captura de órdenes con partidas dinámicas, autollenado de clientes, total visual, filtros e historial de estados.
- Selector de clientes generado con IDs reales desde el servidor; admite también clientes ocasionales sin registro previo.
- Buscador autocompletable de clientes activos por nombre, teléfono o correo, con opción explícita “Público en general”; en este último caso `orders.customer_id` permanece `NULL` y no se crea un registro en `customers`.
- Los datos del autocompletado se inicializan antes del JavaScript y los recursos del backend usan versión por fecha para evitar código obsoleto en caché; los datos del cliente se presentan en una sola fila en escritorio.
- El autocompletado consulta por AJAX desde 2 caracteres, aplica debounce y cancelación, devuelve como máximo 20 resultados y usa índices multi-tenant por estado y nombre, teléfono o correo; ningún catálogo completo se incrusta en el HTML.
- Alta rápida de cliente desde la recepción: “Nuevo cliente” reutiliza nombre, teléfono y correo y guarda cliente más orden en una sola transacción; teléfono o correo coincidentes detienen ambos insertos y orientan a seleccionar el registro existente.
- Flujo verificado para pago total al recibir, anticipo parcial y pago contra entrega; una orden con saldo pendiente no puede entregarse.
- Pantalla “Localizar y entregar” para PC y móvil con búsqueda AJAX por folio, nombre o teléfono, resultados priorizados y acciones contextuales.
- Ticket térmico de recepción para 58/80 mm, independiente de la etiqueta de bolsa, con pagos, saldo, QR, reimpresión y guía posterior a crear o cobrar una orden.
- Cálculo de cambio para efectivo con captura de monto recibido, validación en servidor, auditoría en pagos y desglose en ticket e historial.
- Panel de cobro estilo punto de venta, impresión automática asistida del ticket después del pago y etiqueta para bolsa seleccionable entre impresora térmica y hoja A4.
- Preferencia de formato de etiqueta guardada localmente por navegador y puesto de trabajo, sin carga adicional para la base de datos.
- Listado de órdenes completamente en español, con teléfonos mexicanos legibles y accionables, y estados diferenciados por color.
- Token aleatorio único por orden y etiqueta imprimible con QR generado localmente; el QR exige autenticación y respeta lavandería y sucursal.
- Entrega estimada rápida mediante botones de 4, 24 y 48 horas, mañana a mediodía o fecha manual; al seleccionar partidas se propone automáticamente el mayor tiempo configurado en los servicios y se redondea a bloques de 15 minutos.
- El selector rápido de entrega utiliza una tarjeta visual propia, destaca la fecha calculada y el atajo elegido, mantiene la fecha manual como acción secundaria y se adapta a los temas y dispositivos móviles.
- Pagos y abonos parciales con métodos configurables, saldo transaccional, bloqueo contra sobrepago y cancelación auditada.
- Caja por sucursal con apertura, fondo inicial, ingresos, egresos, depósitos, retiros, efectivo esperado, conteo, diferencia y cierre inmutable.
- Bitácora central multi-tenant iniciada: registra transaccionalmente creación y cambios de estado de órdenes, altas y cancelaciones de pagos, y apertura, movimientos y cierre de caja.
- Cada evento de auditoría conserva lavandería, sucursal, actor, acción, recurso, fecha, IP cuando procede y contexto operativo mínimo; el modelo impide editar o eliminar registros existentes.
- Consulta administrativa de auditoría con filtros por fechas, acción, actor, sucursal y recurso. El owner sólo consulta su lavandería y sucursal asignada; el superadministrador puede consultar eventos de toda la plataforma. Cajeros y operadores no reciben este permiso.
- Centro de notificaciones en la campana superior, almacenado en MySQL y consultado mediante AJAX: contador de pendientes, últimos avisos, lectura individual, marcado global y listado completo.
- Avisos iniciales para órdenes listas, diferencias al cerrar caja y periodos de prueba próximos a vencer; destinatarios separados por lavandería, sucursal y rol, con claves de deduplicación.
- Reporte operativo de ventas, cobros y saldos con filtros por fecha y sucursal, indicadores de ventas, cobrado, saldo y ticket promedio, distribución por estado y método de pago, resultado por sucursal y evolución diaria.
- Conciliación de caja dentro del reporte operativo: turnos cerrados, efectivo esperado y contado, diferencia neta, faltantes, sobrantes y movimientos extraordinarios del periodo.
- Rankings operativos de los diez servicios con mayor venta y los diez clientes registrados más frecuentes, calculados con datos históricos de las órdenes y sin incluir “Público en general”.
- Módulo de reportes dividido en nueve páginas independientes: Resumen, Ventas, Cobranza y saldos, Caja, Órdenes y entregas, Servicios, Clientes, Sucursales y Empleados. Todas comparten filtros por fechas y sucursal.
- Resumen ejecutivo con comparación contra el periodo anterior; cartera pendiente y entregas atrasadas con acceso directo a la orden; actividad de empleados basada en órdenes, cobros y cierres de caja realmente registrados.
- Dashboard ejecutivo del propietario fortalecido con panorama del periodo, relación entre cobros y ventas, indicadores con tendencia, gráfica diaria ligera, prioridades accionables, estado operativo y vistas rápidas de sucursales, servicios y clientes. No requiere librerías gráficas ni procesamiento adicional de archivos.
- Segunda capa analítica del dashboard: promedios diarios, tasa de entrega, precisión de caja, tiempo promedio de entrega, composición visual de órdenes, barras comparativas por sucursal y método de pago, y bloque de salud con cartera, atrasos, diferencias y cancelaciones.
- Acceso granular a reportes: propietario y superadministrador consultan todas las secciones; cajero consulta Caja y Órdenes de su sucursal; operador consulta únicamente Órdenes y entregas. La navegación oculta reportes no autorizados y los importes de cobranza se retiran de la vista operativa sin permiso financiero.
- Exportaciones institucionales independientes en Excel para Ventas, Cobranza, Caja, Órdenes, Servicios, Clientes, Sucursales y Empleados. Incluyen nombre y logotipo de la lavandería, periodo, alcance, fecha de generación, color de marca, filtros, encabezados, formatos monetarios y totales.
- El botón verde “Exportar Excel” se presenta junto a los filtros de cada reporte autorizado. Ventas incluye además un detalle visible con fecha y hora, folio, cliente, teléfono, sucursal, usuario que atendió, estado, total, pagado, saldo y enlace a la orden; el Excel conserva también al usuario responsable.
- Los XLSX se generan como archivos temporales, se eliminan después de la descarga y admiten hasta 10,000 renglones por reporte; los textos se escriben de forma explícita para prevenir fórmulas inyectadas desde datos capturados por usuarios.
- Cada exportación utiliza un permiso independiente y actualmente queda reservada al propietario y superadministrador; los eventos de tenants se registran en la bitácora.
- El superadministrador trabaja exclusivamente en contexto global: no requiere membresía en una lavandería y el menú oculta el módulo Operación completo para evitar rutas que exigen tenant. Conserva Plataforma, Administración, Consulta y reportes consolidados.
- Las ventas se calculan por fecha de recepción de órdenes no canceladas; los cobros, por fecha efectiva de pagos vigentes. La interfaz explica esta separación para facilitar la conciliación.
- Exportación CSV detallada de órdenes del periodo, con límite de consulta de 366 días. Owner restringido a su lavandería/sucursal y superadministrador con vista consolidada de plataforma.
- Cada pago manual queda vinculado obligatoriamente al turno abierto del operador; únicamente el método efectivo modifica el efectivo esperado.
- Efectivo, tarjetas, transferencia y otros quedan disponibles para captura manual; Point, QR y enlace de Mercado Pago están modelados pero permanecen deshabilitados hasta conectar credenciales y webhooks.
- Cliente sandbox de Mercado Pago verificado e intentos idempotentes de enlace de pago disponibles desde órdenes con saldo.
- Acceso local sin VirtualHost.

## Estado local verificado

- Base: `lavansys`.
- Migraciones de aplicación: 31 aplicadas.
- Migraciones RBAC estándar: 4 aplicadas.
- Usuario inicial: `Administrador` (`super_admin`).
- Entorno local con lavandería, sucursal y propietario demo persistentes para pruebas operativas.
- Datos demo idempotentes para la Sucursal Principal: un cajero, un operador, tres clientes y cuatro servicios; disponibles únicamente con `APP_ENV=dev`.
- HTTP de login: respuesta 200.
- Verificación integral actualizada el 5 de septiembre de 2026: aislamiento multi-tenant, totales históricos, pagos parciales, rechazo de sobrepago, cancelación de pagos, cambio en efectivo, caja, máquina de estados, auditoría, notificaciones idempotentes y agregaciones de ventas, conciliación, servicios y clientes correctas. Los datos temporales se revierten al finalizar.
- Revisión estática del corte actual: archivos PHP sin errores de sintaxis, `git diff --check` limpio y sin credenciales reales detectadas en los cambios versionables.
- `composer.json` validado. La suite heredada de Codeception continúa aplazada porque requiere la base temporal vacía `yii2advanced_test`; no se ejecuta contra los datos locales de `lavansys`.
- Flujo integrado verificado con cajero demo: apertura, orden, abono en efectivo, pago con tarjeta y cálculo de caja; los pagos no efectivos no alteran el efectivo esperado.
- URL: `http://localhost/SASS-COMPRAVENTA/lavansys/backend/web/index.php?r=site%2Flogin`.

Las contraseñas y credenciales SMTP sólo existen en `.env` o en la base mediante hash seguro; no se documentan ni versionan.
Yii no incluye variables de entorno, cookies, sesión ni servidor en los logs de error del backend (`logVars` deshabilitado).

## Fase multi-tenant

- Migración para `tenants`, `branches` y `tenant_users` preparada.
- Modelos y validación de pertenencia sucursal/tenant implementados.
- Contexto obligatorio `tenantContext` disponible para los módulos operativos.
- Aprovisionamiento transaccional de lavandería, sucursal principal, propietario y rol `owner`.
- Administración de lavanderías disponible sólo mediante permisos de plataforma.
- Alta ampliada con datos comerciales, domicilio estructurado de sucursal y perfil personal del owner.
- Razón social y RFC opcionales; contacto, zona horaria y dirección operativa obligatorios.
- Correo de bienvenida opcional sin exponer la contraseña.
- Verificación automatizada: `php yii tenant/verify-isolation`.
- Catálogo inicial de planes con precio mensual, días de prueba y límites de sucursales/usuarios.
- Suscripción por lavandería con fotografía del precio y límites contratados.
- Administración de sucursales y empleados restringida al tenant del owner.
- Alta de empleados por invitación segura y asignación exclusiva a una sucursal.

## Próxima fase

La secuencia completa, sus dependencias y criterios de aceptación se mantienen en [`PLAN_DESARROLLO.md`](PLAN_DESARROLLO.md).

Cerrar formalmente las fases operativas 1 a 4 con pruebas de autorización, recorrido HTTP autenticado y pruebas físicas de impresión. La **Fase 5 — Auditoría y notificaciones** ya cuenta con bitácora y consulta administrativa; continúa el registro de otras acciones relevantes y las notificaciones internas.

La integración de Mercado Pago permanece como trabajo paralelo en sandbox. La conciliación y los webhooks se retomarán después de estabilizar la trazabilidad operativa. Antes del cobro SaaS en producción faltará integrar renovaciones, comprobantes de suscripción y cambios de plan.

## Comandos útiles

```bash
cd /opt/lampp/htdocs/SASS-COMPRAVENTA/lavansys
/opt/lampp/bin/php yii migrate --interactive=0
/opt/lampp/bin/php yii rbac/init
/opt/lampp/bin/php yii user/create-admin
/opt/lampp/bin/php yii tenant/create-demo-owner
/opt/lampp/bin/php yii tenant/seed-demo-data
/opt/lampp/bin/php yii notification/generate 3
/opt/lampp/bin/php yii report/verify
```

Los comandos demo sólo funcionan con `APP_ENV=dev` y no duplican ni reemplazan cuentas existentes. Las credenciales se muestran en consola, pero no se versionan en esta documentación. `notification/generate 3` genera, sin duplicar, los avisos de pruebas que vencen durante los siguientes tres días; posteriormente deberá ejecutarse mediante cron.
### Reportes operativos homologados

- Los reportes de ventas, cobranza, caja, órdenes, servicios, clientes, sucursales y empleados muestran indicadores ejecutivos y detalle operativo en pantalla.
- Cobranza incorpora antigüedad, responsable y último abono; caja muestra responsables, cobros y conciliación por turno; órdenes incluye el ciclo completo de recepción a entrega.
- Servicios, clientes, sucursales y empleados incluyen métricas de rendimiento, participación, recurrencia, recuperación y promedios útiles para la toma de decisiones.
- La exportación Excel conserva el mismo nivel de detalle, identidad de la lavandería, filtros aplicados y columnas monetarias formateadas.
- Los temas Oscuro y Pro Midnight utilizan superficies, cifras, textos secundarios y colores semánticos de alto contraste en todos los reportes.
- Verificador transaccional `php yii operation/verify` para probar caja, alta rápida de cliente, orden, anticipo, cambio, bloqueo de entrega con saldo, liquidación, entrega, cierre, reportes y permisos sin dejar datos temporales.
- Verificador `php yii operation/verify-access` para comprobar permisos positivos y negativos, así como la visibilidad real de menús para propietario, cajero, operador y superadministrador global.
- Pruebas HTTP locales aprobadas para las cuatro cuentas demo: autenticación, rutas autorizadas/prohibidas, ticket, etiqueta y redirección segura del QR. El ticket identifica discretamente a LavanderOS junto a la marca de la lavandería.

### Decisiones y pendientes del 6 de septiembre de 2026

- Se confirmó el modelo de cuentas conectadas: cada propietario vinculará por OAuth su propia cuenta de Mercado Pago y recibirá directamente el dinero de sus clientes. LavanderOS no concentrará esos fondos.
- Las credenciales actuales del `.env` continúan limitadas al sandbox. OAuth y webhooks reales requieren una URL HTTPS pública.
- La integración se diseñará por proveedor para permitir otra pasarela en el futuro sin acoplar órdenes, pagos y saldos a Mercado Pago.
- Quedan planeados el nombre del empleado en ticket y etiqueta, búsqueda rápida AJAX de órdenes, lectura opcional de QR y registro del medio por el que un prospecto conoció LavanderOS.
- La validación física de impresoras y lectura QR queda pendiente durante las pruebas del propietario.
- La base de conocimiento y el asistente con IA quedan explícitamente aplazados; no forman parte de la siguiente entrega.
- El listado de órdenes muestra folios con contraste reforzado y la vista de detalle presenta Total, Pagado y Saldo como indicadores diferenciados, incluyendo variantes accesibles para temas oscuros.
- El ticket del cliente y la etiqueta de bolsa identifican al empleado que recibió la orden mediante su nombre de perfil, con el nombre de usuario como respaldo.
- El verificador transaccional completo continúa aprobado después de estos ajustes y revierte correctamente sus datos de prueba.
- La barra superior funciona como buscador AJAX de órdenes para usuarios operativos: consulta por folio, cliente o teléfono, muestra sucursal, estado y saldo, permite teclado y reconoce URLs producidas por el QR. Superadministradores sin tenant conservan la búsqueda de menú.
- Se agregó un catálogo administrable de fuentes de captación. El alta de lavanderías exige seleccionar cómo conocieron LavanderOS y permite registrar un detalle comercial opcional; la información aparece en el listado y expediente del tenant.
- El superadministrador puede editar la identidad, contacto, zona horaria, estado, notas internas y fuente de captación de una lavandería existente, sin intervenir en sus datos operativos, logo o configuración de impresión.
- El reporte de captación de plataforma consolida registros por fuente y plan, distingue pruebas vigentes/vencidas y suscripciones activas, muestra detalle comercial filtrable y permite exportar hasta 10,000 filas a Excel.
- Se documentó el despliegue seguro en un dominio temporal HTTPS: requisitos, configuración Production, entorno, cookies, permisos, MySQL, RBAC, correo, cron, actualizaciones, respaldos, pruebas de humo y preparación para OAuth/webhooks.
- Se implementó la base de cuentas de pago conectadas por lavandería: catálogo neutral de proveedores, conexión aislada por tenant/ambiente, estados de ciclo, índices y relaciones. Mercado Pago es el primer proveedor registrado.
- El propietario dispone de **Pagos digitales** con capacidades, estado y lista de requisitos. Preparar o desconectar una cuenta exige permisos propios y produce auditoría; desconectar elimina las credenciales locales.
- Se agregó cifrado autenticado para tokens con una clave Base64 de 32 bytes independiente (`PAYMENT_CREDENTIALS_KEY_BASE64`). La aplicación no presenta secretos en pantalla y rechaza claves mal formadas.
- OAuth real, renovación y webhooks permanecen pendientes hasta contar con `APP_URL` HTTPS pública. La interfaz no permite confundir una preparación con una conexión activa.