# Arquitectura inicial de LavanderOS

**Fecha:** 2 de septiembre de 2026

**Repositorio:** `https://github.com/luisangel/lavansys.git`

**Ruta local:** `/opt/lampp/htdocs/SASS-COMPRAVENTA/lavansys`

## 1. Objetivo

Construir una aplicación nueva para la operación de lavanderías, conservando las reglas funcionales documentadas en el proyecto `LAVANDERIA` y tomando de `saas-compraventa` únicamente su base administrativa madura: autenticación, RBAC, navegación configurable, patrones de catálogos y diseño Pick Admin adaptado a Bootstrap 5.

LavanderOS no será un fork funcional de ninguno de los dos sistemas. Tendrá código, migraciones, configuración, base de datos y evolución independientes.

## 2. Fuentes de referencia

### Dominio funcional

Proyecto: `/opt/lampp/htdocs/LAVANDERIA`

Se conservarán las reglas ya definidas para:

- plataforma SaaS multi-tenant;
- lavanderías, sucursales y membresías;
- usuarios y roles operativos;
- catálogo de servicios por kilogramo, pieza o paquete;
- órdenes, partidas y precios históricos;
- anticipos y pagos parciales;
- estados de recepción, proceso, lista, entrega y cancelación;
- caja, ingresos, egresos, retiros, cierres y ajustes;
- auditoría y reportes;
- tickets térmicos de 58 y 80 mm;
- recuperación de contraseña;
- respaldo, datos demo y verificación integral.

La documentación funcional será la fuente principal. El código existente podrá consultarse para entender reglas probadas, pero LavanderOS tendrá una implementación revisada y propia.

### Base administrativa y visual

Proyecto: `/opt/lampp/htdocs/SASS-COMPRAVENTA/saas-compraventa/app`

Se evaluaron como reutilizables:

- Yii2 Advanced con PHP 8 y Bootstrap 5;
- `yii\rbac\DbManager`;
- catálogo central de permisos;
- administración granular de roles;
- administración de usuarios y perfil propio;
- menú administrativo persistido y filtrado por permisos;
- layout Pick Admin, navegación lateral y personalizador de temas;
- `AppAsset`, CSS y JavaScript estrictamente necesarios;
- patrón de formularios administrativos;
- patrón de `SearchModel` + `ActiveDataProvider` + `GridView`;
- login, activación de cuenta y cambio de contraseña, tras revisión de seguridad;
- estructura de pruebas y comandos de consola.

El árbol de `saas-compraventa` contiene cambios locales en desarrollo. Se utilizará sólo como referencia de lectura y no se modificará ni copiará mediante operaciones Git masivas.

## 3. Elementos que no se copiarán

- Fuentes, comercios y conectores de precios.
- Productos, variantes, publicaciones y observaciones de precios.
- Rastreadores, alertas y ejecuciones de conectores.
- Migraciones del dominio de compraventa.
- Datos, credenciales, `.env`, runtimes, assets generados o archivos locales.
- Dependencias que no sean necesarias para LavanderOS.
- Textos, marcas, logotipos o rutas de EstáBara.
- Cambios sin confirmar presentes en el proyecto fuente.
- Código de lavandería sin revisión de estilo, seguridad y modelo de datos.

## 4. Decisiones técnicas iniciales

| Tema | Decisión |
|---|---|
| Framework | Yii2 Advanced limpio |
| PHP local | PHP 8.0.3 de XAMPP |
| Base local propuesta | `lavansys` |
| Motor | MariaDB/MySQL de XAMPP |
| Fechas de aplicación | `DATETIME` en UTC; conversión a zona del tenant en presentación |
| Interfaz | Pick Admin adaptado a Bootstrap 5 |
| Caché inicial | FileCache |
| Sesiones | PHP/Yii locales |
| RBAC | DbManager y permisos granulares |
| Multi-tenancy | `tenant_id` obligatorio más validación de sucursal |
| Redis | Fuera del MVP |
| Node.js | No requerido para operación inicial |
| VirtualHost local | No requerido inicialmente |
| Secretos | `.env` local ignorado; variables externas en servidor |
| Repositorio | Proyecto independiente `luisangel/lavansys` |

La base `lavansys` y la URL local definitiva se confirmarán antes de aplicar migraciones.

## 5. Roles base

- `super_admin`: administra la plataforma y los tenants; no opera automáticamente datos de una lavandería.
- `owner`: administra su lavandería, usuarios, servicios, caja, ajustes y reportes.
- `cashier`: crea órdenes, registra pagos y opera caja.
- `operator`: consulta órdenes y actualiza estados operativos.

Los nombres se conservarán del dominio de lavandería. La interfaz para administrar roles y el catálogo granular de permisos tomarán el patrón de `saas-compraventa`.

## 6. Catálogo inicial de permisos

### Plataforma

- `platform.access`
- `tenant.view`
- `tenant.create`
- `tenant.update`
- `tenant.toggle`

### Usuarios y seguridad

- `user.view`
- `user.create`
- `user.update`
- `user.toggle`
- `user.resetPassword`
- `role.view`
- `role.create`
- `role.update`
- `role.delete`
- `menu.view`
- `menu.create`
- `menu.update`
- `menu.toggle`
- `menu.delete`
- `profile.view`
- `profile.update`
- `profile.changePassword`

### Operación

- `service.view`
- `service.create`
- `service.update`
- `service.toggle`
- `order.view`
- `order.create`
- `order.updateStatus`
- `order.cancel`
- `order.printTicket`
- `payment.create`
- `cash.view`
- `cash.open`
- `cash.createMovement`
- `cash.close`
- `cash.authorizeAdjustment`
- `report.view`
- `report.export`

El permiso nunca sustituirá el filtro por tenant y sucursal.

## 7. Modelo de datos previsto

### Identidad y plataforma

- `user`
- tablas estándar RBAC de Yii2;
- `tenant`
- `branch`
- `tenant_user`
- `plan`
- `tenant_subscription`
- `user_external_identity` para vincular proveedores OAuth/OIDC sin duplicar cuentas;
- `admin_menu`

### Catálogos

- `service`
- `customer`
- catálogos controlados en PHP para tipo, unidad, método de pago y estados, salvo que el piloto demuestre necesidad de tablas configurables.

### Operación

- `tenant_sequence`
- `order`
- `order_item`
- `order_payment`
- `cash_register_session`
- `cash_movement`
- `cash_adjustment`
- `activity_log`

Se evitarán `ENUM`, borrado físico de datos financieros y SQL innecesariamente específico de MySQL.

## 8. Reglas que deben conservarse

1. Toda consulta operativa restringe el tenant de la sesión.
2. Un usuario ligado a una sucursal no puede operar otra.
3. Los importes se recalculan en el servidor.
4. La partida conserva nombre, unidad, precio e impuesto históricos.
5. Los pagos y cierres usan transacciones y bloqueos de fila.
6. No se permite sobrepago.
7. No se entrega una orden con saldo pendiente.
8. Todo pago manual requiere caja abierta.
9. Sólo el efectivo modifica el efectivo esperado.
10. Los cierres son inmutables; las correcciones son ajustes auditados.
11. Cancelaciones, ajustes y acciones sensibles registran usuario y motivo.
12. Las contraseñas utilizan exclusivamente la seguridad de Yii.
13. CSRF permanece habilitado y las acciones destructivas usan POST.
14. Los secretos nunca se versionan.
15. Los logotipos se validan como imagen, se renombran aleatoriamente y la base conserva sólo su ruta.

## 9. Estándar visual

LavanderOS adoptará los patrones ya probados en `saas-compraventa`:

- encabezado `admin-page-heading`;
- formularios en `admin-form-card` y secciones numeradas;
- campos mediante `ActiveForm` y errores junto al campo;
- listados con `SearchModel`, `ActiveDataProvider` y `GridView`;
- acciones a la izquierda con icono, texto accesible o `aria-label`;
- filtros debajo del encabezado;
- navegación persistida y visible según permisos;
- temas Claro, Oscuro, Semioscuro y Pro Midnight;
- diseño móvil y navegación por teclado;
- sin plugins heredados cuando Bootstrap 5 o Yii2 cubran la necesidad.

La identidad visual se renombrará a **LavanderOS**. Antes de distribuir assets propietarios debe confirmarse la licencia aplicable de Pick Admin.

## 10. Estructura propuesta

```text
lavansys/
├── backend/
│   ├── assets/
│   ├── components/
│   ├── controllers/
│   ├── models/
│   ├── modules/
│   │   ├── platform/
│   │   ├── services/
│   │   ├── orders/
│   │   ├── cashier/
│   │   └── reports/
│   ├── views/
│   └── web/
├── common/
│   ├── components/
│   ├── models/
│   ├── services/
│   └── validators/
├── console/
│   ├── controllers/
│   └── migrations/
├── environments/
├── tests/
├── docs/
└── composer.json
```

## 11. Fases de implementación

### Fase A — Scaffold y diseño

- instalar Yii2 Advanced limpio;
- preparar `.gitignore`, `.env.example` y cargador de entorno;
- adaptar sólo los assets necesarios de Pick Admin;
- implementar layout, login, error, dashboard y temas;
- comprobar PHP, consola y HTTP.

### Fase B — Identidad, RBAC y navegación

- migración de usuarios y RBAC;
- catálogo granular de permisos;
- roles base protegidos;
- administración de usuarios, roles, perfil y menús;
- recuperación de contraseña;
- pruebas de acceso y seguridad.

### Fase C — Tenants y sucursales

- tenants, sucursales y membresías;
- contexto y scopes obligatorios;
- aprovisionamiento transaccional;
- panel `super_admin`;
- pruebas negativas con dos tenants.
- planes escalables por límites de sucursales y usuarios;
- periodo de prueba y suscripción mensual por tenant.

### Fase D — Catálogo y órdenes

- servicios;
- secuencias, órdenes y partidas históricas;
- estados, cancelación y tickets 58/80 mm;
- captura rápida y pruebas de totales.

### Fase E — Pagos y caja

- pagos parciales;
- sesiones y movimientos de caja;
- cierres, diferencias, ajustes y auditoría;
- concurrencia y reglas financieras.

### Fase F — Reportes y piloto

- reportes y CSV;
- datos demo;
- respaldo/restauración;
- verificador integral;
- revisión visual e impresión física;
- despliegue controlado.

## 12. Primer incremento ejecutable

El primer incremento se considerará terminado cuando:

- `lavansys` abra localmente con el layout nuevo;
- conecte a una base vacía propia;
- permita iniciar sesión;
- incluya RBAC granular, administración de roles y menús;
- tenga una cuenta `super_admin` creada mediante comando seguro;
- no contenga módulos ni datos de compraventa;
- las pruebas confirmen que las rutas no autorizadas están bloqueadas.

## 13. Controles durante la migración selectiva

- Comparar cada archivo antes de copiarlo.
- Sustituir textos, rutas y permisos del dominio anterior.
- No copiar `.git`, `vendor`, runtime, assets publicados ni configuraciones locales.
- No sobrescribir cambios en los proyectos fuente.
- Mantener commits pequeños por infraestructura, diseño, identidad y dominio.
- Documentar cualquier desviación respecto al sistema de lavandería previo.
- Ejecutar revisión de secretos antes de cada push.

## 14. Próximo paso

Crear el scaffold Yii2 Advanced dentro del repositorio `lavansys`, configurar la base local propuesta y portar primero el layout mínimo y la infraestructura de RBAC. No se implementarán catálogos de compraventa.