# Plan maestro de desarrollo de LavanderOS

**Versión:** 1.0  
**Fecha base:** 2 de septiembre de 2026  
**Proyecto:** LavanderOS SaaS para lavanderías

## 1. Objetivo

Construir y llevar a piloto un SaaS multi-tenant para administrar lavanderías, sucursales, empleados, clientes, servicios, órdenes, pagos, caja y reportes. Después del periodo de prueba, cada tenant contratará un plan mensual acorde con sus límites de sucursales y usuarios.

Este documento define el orden de trabajo. `PROGRESO.md` indicará qué puntos están realmente terminados.

## 2. Principios no negociables

- Toda información operativa se filtra por `tenant_id` y, cuando corresponda, por `branch_id`.
- Importes, impuestos, descuentos y saldos se recalculan en el servidor.
- Precios y descripciones de partidas se conservan históricamente.
- Fechas propias se almacenan como `DATETIME` en UTC.
- Operaciones financieras usan transacciones y bloqueos de fila.
- No se eliminan físicamente movimientos financieros ni cierres.
- Acciones sensibles registran usuario, fecha y motivo.
- Contraseñas, tokens y credenciales nunca se versionan.
- Cada fase termina con pruebas, documentación y un commit identificable.

## 3. Estado de partida

Ya existe una primera versión de:

- Yii2 Advanced, interfaz administrativa y temas;
- autenticación local, activación de cuenta, RBAC y menús;
- tenants, sucursales, empleados y aislamiento;
- planes, periodo de prueba y límites contratados;
- clientes y servicios;
- perfil de lavandería, domicilio fiscal, logotipo y preferencias de ticket;
- estructura para identidades externas;
- creación inicial de órdenes, partidas históricas, folios y estados.

Estos módulos deberán pasar una revisión integral antes del piloto; “implementado” no equivale todavía a “listo para producción”.

## 4. Orden de desarrollo

### Fase 0 — Consolidación técnica y documental

Objetivo: estabilizar lo construido antes de ampliar el dominio.

- actualizar cantidades de migraciones y permisos documentadas;
- revisar índices, claves foráneas, nombres y tipos de columnas;
- normalizar formularios, listados, botones y mensajes;
- añadir pruebas automatizadas para aislamiento y autorización;
- revisar secretos, archivos subidos y permisos del filesystem;
- definir datos demo reproducibles.

**Aceptación:** una instalación vacía se levanta mediante comandos documentados; los verificadores terminan sin datos residuales; Git queda limpio.

**Decisión actual:** la prueba sobre base vacía queda aplazada hasta antes del piloto; la consolidación continúa sobre `lavansys` sin borrar información.

### Fase 1 — Completar órdenes

Objetivo: hacer eficiente y seguro el ciclo de recepción a entrega.

- búsqueda/autocompletado de clientes y llenado de contacto;
- partidas dinámicas, edición antes de cobrar y eliminación controlada;
- descuentos con permiso y motivo;
- folio configurable por sucursal;
- fechas prometida, lista, entregada y cancelada;
- máquina de estados con servicio de dominio y auditoría;
- filtros por folio, cliente, teléfono, sucursal, estado y fecha;
- validación de concurrencia y pruebas de redondeo;
- diseño móvil orientado a captura en mostrador.

**Aceptación:** una orden se captura en menos de tres minutos; no se aceptan totales del navegador; modificar un servicio no altera órdenes anteriores; otro tenant o sucursal no puede consultarla.

### Fase 2 — Pagos parciales

Objetivo: administrar anticipos y liquidaciones sin inconsistencias.

- tabla inmutable de pagos;
- métodos efectivo, tarjeta, transferencia y otros configurables;
- referencia, notas, usuario y fecha;
- actualización transaccional de pagado y saldo;
- bloqueo de fila para pagos simultáneos;
- rechazo de sobrepago y de pagos a órdenes canceladas/entregadas;
- cancelación o reverso con permiso y motivo;
- recibo de pago.

**Aceptación:** dos solicitudes concurrentes no generan sobrepago; el saldo siempre coincide con pagos vigentes; no se entrega con saldo pendiente.

### Fase 3 — Caja por sucursal

Objetivo: controlar el efectivo y los movimientos de cada turno.

- apertura con fondo inicial;
- una caja abierta por operador/sucursal según política definida;
- vínculo obligatorio entre pago presencial y sesión abierta;
- ingresos, egresos, retiros y depósitos;
- efectivo esperado frente a efectivo contado;
- cierre inmutable con diferencia;
- ajustes autorizados y auditados;
- manejo de concurrencia y recuperación ante errores.

**Aceptación:** sólo el efectivo afecta el efectivo esperado; ninguna operación de otro tenant entra en la caja; un cierre no puede editarse.

### Fase 4 — Tickets y comprobantes

Objetivo: imprimir comprobantes claros en equipo real.

- tickets de orden y pago para 58/80 mm;
- logotipo, datos comerciales/fiscales, sucursal y pie personalizado;
- partidas, subtotal, impuesto, descuento, total, pagado y saldo;
- código QR o referencia de consulta si se aprueba;
- estilos exclusivos de impresión;
- reimpresión controlada y registro de actividad;
- prueba física en al menos una impresora de cada ancho utilizado.

**Aceptación:** el ticket no depende del layout administrativo, no corta importes y coincide con la orden almacenada.

### Línea paralela — Cobros digitales de los clientes de la lavandería

Objetivo: permitir que el cliente final liquide o abone una orden mediante enlace, QR o terminal, sin que LavanderOS concentre el dinero.

- cada propietario conectará su propia cuenta de Mercado Pago mediante OAuth;
- cada cobro se creará con las credenciales cifradas del tenant correspondiente;
- el dinero llegará directamente a la cuenta conectada de la lavandería, menos las comisiones del proveedor;
- LavanderOS conciliará la orden sólo después de confirmar el pago por API o webhook validado;
- enlace de pago para compartir por correo o mensajería y QR asociado a una orden;
- conexión, intentos, eventos y reembolsos aislados por tenant;
- diseño neutral respecto del proveedor para integrar otra pasarela en el futuro;
- Mercado Pago continuará en sandbox mientras no exista callback HTTPS público.

Este flujo es independiente de la mensualidad que el propietario pagará a LavanderOS por su suscripción SaaS.

**Aceptación:** una lavandería nunca puede utilizar la cuenta conectada de otra; un retorno del navegador no acredita por sí solo un pago; eventos repetidos no duplican abonos.

### Fase 5 — Auditoría y notificaciones

Objetivo: ofrecer trazabilidad operativa.

- bitácora de altas, cambios de estado, cancelaciones, pagos y caja;
- captura de actor, tenant, sucursal, IP y contexto mínimo;
- notificaciones internas de órdenes listas, pruebas por vencer y pagos vencidos;
- correos transaccionales configurables;
- políticas de retención y protección de datos personales.

**Aceptación:** las acciones sensibles pueden reconstruirse sin exponer secretos ni datos innecesarios.

### Fase 6 — Reportes

Objetivo: entregar información útil al owner y a la plataforma.

- ventas y pagos por periodo, sucursal, servicio y método;
- órdenes por estado, tiempos y saldo pendiente;
- caja, diferencias, movimientos y cierres;
- clientes frecuentes y servicios más vendidos;
- panel consolidado para owner multi-sucursal;
- métricas SaaS separadas para `super_admin`;
- exportación CSV con permisos y límites.

**Aceptación:** cifras conciliadas con órdenes, pagos y caja; filtros de otro tenant producen cero resultados.

### Fase 7 — Planes, suscripciones y cobro SaaS

Objetivo: convertir el piloto gratuito en servicio mensual.

- CRUD administrativo de planes, precios, límites y días de prueba;
- cambio de plan con reglas de aumento/reducción;
- estados trial, activa, vencida, suspendida y cancelada;
- avisos antes y después del vencimiento;
- periodo de gracia configurable;
- historial de suscripciones y precios contratados;
- selección e integración de pasarela de pago;
- webhooks idempotentes y registro de intentos;
- comprobantes/facturación sólo después de definir requisitos fiscales;
- suspensión gradual que preserve acceso a datos y evite operaciones nuevas.

**Decisiones pendientes:** precios finales, duración del trial, periodo de gracia, proveedor de pagos, impuestos, facturación y política de cancelación.

**Aceptación:** eventos duplicados de la pasarela no duplican cobros; los límites del plan se aplican en servidor; cambiar el catálogo no altera contratos históricos.

### Fase 8 — Portal público y autoservicio

Objetivo: permitir que prospectos conozcan el producto y se registren.

- página pública de producto, beneficios, precios y preguntas frecuentes;
- registro de owner y tenant con verificación de correo;
- selección de plan e inicio del periodo de prueba;
- captura del medio por el que el prospecto conoció LavanderOS, mediante catálogo administrable;
- onboarding para completar negocio, sucursal, logo y primer servicio;
- términos, privacidad, consentimiento y medidas antiabuso;
- recuperación de cuenta y soporte inicial.

**Aceptación:** el registro es transaccional, reanudable, no crea tenants duplicados y deja una suscripción de prueba consistente.

### Fase 9 — Google y redes sociales

Objetivo: permitir registro e inicio de sesión mediante OAuth 2.0/OIDC.

- comenzar con Google; agregar proveedores sólo si hay demanda;
- vincular la identidad externa a un `user` existente;
- evitar duplicados por correo no verificado;
- permitir vincular/desvincular proveedores desde seguridad;
- exigir un método de recuperación antes de quitar el último acceso;
- validar `state`, `nonce`, PKCE y URLs de retorno;
- cifrar tokens si algún proveedor exige conservarlos;
- registrar accesos y revocar sesiones ante eventos de seguridad.

**Aceptación:** una identidad externa sólo pertenece a un usuario; iniciar con Google no crea cuentas duplicadas; fallos OAuth no dejan altas parciales.

### Fase 10 — Piloto controlado

Objetivo: probar el producto con lavanderías reales antes de cobrar.

- datos demo y recorrido guiado;
- selección de un grupo pequeño de clientes piloto;
- métricas de uso, errores y tiempos de captura;
- respaldo/restauración probado;
- revisión visual móvil/escritorio;
- pruebas de impresión y operación diaria;
- canal de soporte e incidencias;
- corrección de bloqueadores y congelamiento de versión.

**Aceptación:** al menos un ciclo completo recepción–pago–caja–entrega funciona en operación real y existe restauración verificada.

### Fase 11 — Producción y operación

Objetivo: desplegar y mantener el SaaS con seguridad.

- servidor, dominio, HTTPS, correo definitivo y variables de entorno;
- base con usuario restringido, respaldos automáticos y monitoreo;
- jobs para vencimientos, correos y mantenimiento;
- despliegues reproducibles y rollback;
- logs sin secretos, alertas y revisión de capacidad;
- términos, privacidad y procedimientos de soporte;
- rotación de las credenciales usadas durante desarrollo.

**Aceptación:** checklist de producción aprobado, restauración ensayada, HTTPS obligatorio y monitoreo activo.

## 5. Dependencias principales

```text
Órdenes → Pagos → Caja → Tickets/Reportes
             └────────→ Auditoría

Planes + perfil de negocio → Portal público → Registro → OAuth/OIDC

MVP operativo + seguridad + respaldos → Piloto → Cobro SaaS → Producción
```

## 6. Método para ejecutar cada fase

1. Confirmar alcance y reglas pendientes.
2. Diseñar migración reversible e índices.
3. Implementar modelo y servicio de dominio.
4. Aplicar RBAC y aislamiento.
5. Construir interfaz consistente y accesible.
6. Ejecutar pruebas positivas, negativas y de concurrencia cuando aplique.
7. Verificar HTTP y ausencia de datos temporales.
8. Actualizar `PROGRESO.md` y documentación específica.
9. Revisar secretos y `git diff`.
10. Crear un commit pequeño y publicarlo.

## 7. Prioridad inmediata

La implementación funcional adelantó componentes de las fases 1 a 4. La prioridad inmediata es consolidarlos y cerrar sus criterios de aceptación: pruebas de autorización y aislamiento, recorrido HTTP autenticado, validación física de impresión y documentación del corte estable.

Una vez cerrado ese bloque se continuará con **Fase 5 — Auditoría y notificaciones**. Mercado Pago seguirá en sandbox y no condicionará el cierre del flujo operativo local.

En las mejoras operativas siguientes se contemplan el nombre del empleado que atendió en ticket y etiqueta, el buscador rápido AJAX por folio/cliente/teléfono y la lectura opcional de QR desde lector USB, cámara de computadora o celular. La cámara del navegador requerirá HTTPS en producción.

En paralelo quedó terminada la base persistente de cuentas de pago por lavandería. El siguiente incremento de pagos será habilitar OAuth de Mercado Pago sobre el dominio temporal HTTPS, intercambiar y cifrar tokens, renovar credenciales y utilizar la conexión del tenant al generar cobros. Después se incorporarán webhooks idempotentes, conciliación y QR de pago.

## 7.1 Backlog explícitamente aplazado

- preparar una base de conocimiento de ayuda;
- integrar posteriormente un asistente con IA para dudas de uso.

La IA no forma parte del alcance inmediato. Antes de retomarla deberán estabilizarse los flujos, redactarse contenido de ayuda verificable y definirse límites, privacidad, costos y mecanismo de escalamiento a soporte humano.

## 8. Temas que requieren decisión del propietario

- precios definitivos y nombres comerciales de planes;
- número final de días gratuitos y periodo de gracia;
- límites exactos por plan y tratamiento de excedentes;
- pasarela de pago y necesidad de facturación mexicana;
- estados operativos que realmente usa una lavandería piloto;
- descuentos permitidos y quién los autoriza;
- políticas de cancelación, devoluciones y conservación de datos;
- proveedores sociales adicionales a Google;
- impresoras y anchos usados en el piloto.