# Contexto de desarrollo de mitienda para Codex

Última actualización: 17 de septiembre de 2026.

Este es el documento principal para continuar el desarrollo, con o sin el historial del chat. No es solo una guía de traslado. Describe el trabajo existente y separa lo implementado de lo pendiente. Verificar el código y el entorno al retomar: el estado de servicios y credenciales puede haber cambiado desde esta fecha.

## 1. Qué quiere el usuario

Una tienda de indumentaria llamada **mitienda**, tomando como referencia https://lluviadeoro.online/, con una presentación cuidada, administración del stock, alertas internas de stock y ventas e integración con Mercado Pago. Aceptó avanzar con la tecnología propuesta y pidió continuar el desarrollo. Quiere entender la operación con explicaciones sencillas y poder retomar el proyecto en otra PC con Codex.

Dirección de desarrollo original: http://mitienda.local/. Carpeta original: `C:\xampp\htdocs\mitienda`. Esto no es un sitio público publicado.

## 2. Decisiones que ya se tomaron

- Laravel 12 y PHP 8.2, por compatibilidad con el XAMPP instalado. No cambiar a Laravel 13 sin revisar primero el requisito de PHP y la compatibilidad de dependencias.
- Blade y Livewire 3 para páginas e interacción; Tailwind 4 y CSS propio con Vite 7. No hay una aplicación React/Next separada.
- MariaDB/InnoDB para el negocio. SQLite en memoria para pruebas automatizadas.
- Checkout Pro de Mercado Pago; sin capturar tarjetas en la tienda. Moneda ARS, importes persistidos en centavos.
- Compra como invitado. Seguimiento por enlace privado o número de pedido y correo. No se crearon cuentas de clientes.
- Inventario por variante/talle/color y reservas de 30 minutos. Las ventas manuales usan ese mismo inventario.
- Diseño propio en tonos crema y bordó, estilo editorial, adaptable a móvil. Tres fotos generadas ilustran el catálogo; no pertenecen a mercadería real del usuario.
- Configuración local demo; correos en logs. No presentar esta instalación como habilitada para cobrar al público.

## 3. Qué ya se construyó

| Área | Implementación existente |
| --- | --- |
| Tienda | Portada, catálogo, búsqueda, filtros de categoría/talle/ofertas, orden por precio, fichas con galería y variantes. |
| Compra | Carrito de sesión, cotización en servidor, cupón porcentual, retiro o envío de tarifa fija, umbral gratuito y checkout. |
| Pedidos | Reserva, pago pendiente/aprobado/rechazado, vencimiento/cancelación, preparación/entrega y consulta privada. |
| Productos | Alta/edición, fotografías, galería, categorías, variantes y activación/desactivación. |
| Inventario | Stock físico/reservado/disponible, mínimos por variante, ajustes con motivo, historial y devolución física controlada. |
| Alertas | Stock bajo/agotado, nuevo pedido, venta confirmada e incidencias de pagos. Campana cada 15 segundos, lectura y sonido opcional. |
| Operación | Ventas manuales de local/WhatsApp, clientes agrupados por correo, reportes y exportación CSV. WhatsApp es canal/enlace, no sincronización con su API. |
| Acceso | Inicio/cierre de sesión, administrador/operador, usuario activo, alta y desactivación de usuarios, cambio de contraseña. |
| Configuración | Nombre comercial, contacto, WhatsApp, retiro, costo/umbral de envío, correo de alertas, presentación y texto de cambios. |
| Pagos | Creación/reutilización de preferencia, webhook firmado, consulta autenticada, validación e idempotencia; incidencias por pago tardío/duplicado. |
| Tareas | Colas para consulta de pagos y correos; liberación de reservas cada minuto y conciliación de alertas de stock cada cinco minutos. |

Mercado Pago está **implementado y probado con respuestas simuladas**. No está conectado a una cuenta ni validado con pagos reales/sandbox del usuario. Los correos están **implementados en cola**, pero el transporte local es `log`, sin entrega a destinatarios.

## 4. Mapa del código

| Archivo o carpeta | Responsabilidad |
| --- | --- |
| `routes/web.php` | Rutas de tienda, pedidos, autenticación, administración, medios y webhook. |
| `app/Http/Controllers/StoreController.php` | Carrito, cotización, checkout, seguimiento y recepción del webhook. |
| `app/Http/Controllers/AdminController.php` | Operación del panel, permisos específicos y formularios administrativos. |
| `app/Http/Controllers/AuthController.php` | Acceso y salida de sesión. |
| `app/Http/Middleware/StaffAccess.php` | Roles autorizados y usuario activo. |
| `app/Services/CartService.php` | Carrito, precios, descuentos y envío. |
| `app/Services/OrderService.php` | Crear/reservar pedidos, aplicar cambios de pago, cancelar y vencer. |
| `app/Services/InventoryService.php` | Ajustes, movimientos, liberación y reposición física. |
| `app/Services/AlertService.php` | Alertas, deduplicación y aviso al cliente. |
| `app/Services/MercadoPagoService.php` | Preferencias, verificación de firma y consulta al proveedor. |
| `app/Jobs/SyncMercadoPago.php`, `SendStoreEmail.php` | Trabajo asíncrono y reintentos. |
| `app/Models` | Productos, variantes, pedidos/ítems, eventos de pago, movimientos, alertas, cupones, configuración y usuarios. |
| `database/migrations` | Esquema de base de datos; modificar mediante nuevas migraciones cuando haya datos que conservar. |
| `database/seeders/DatabaseSeeder.php` | Datos locales de muestra y administrador inicial si no existe. No usar como carga productiva. |
| `app/Livewire`, `resources/views/livewire` | Catálogo con filtros y campana. |
| `resources/views/store`, `admin`, `layouts` | Pantallas públicas, administrativas y estructura visual. |
| `resources/css/store.css`, `resources/js/app.js` | Diseño y comportamiento del navegador. |
| `config/store.php`, `.env.example` | Opciones del comercio y nombres de variables, sin secretos reales. |
| `routes/console.php`, `scripts` | Comandos y arranque/parada local de trabajadores. |
| `tests/Feature/StoreTest.php`, `phpunit.xml` | Pruebas de negocio y entorno aislado. |

Imágenes de ejemplo: `public/images`. Fotografías cargadas desde el panel: `storage/app/public/catalog`, servidas por `/media/{archivo}` sin depender de un enlace simbólico. Nunca exponer la raíz completa del proyecto como DocumentRoot; usar `public`.

## 5. Reglas delicadas: leer antes de modificar

1. `Variant.stock` es stock físico; `reserved` son unidades comprometidas; disponibilidad es la diferencia. No modificar estos campos desde nuevos caminos que omitan los servicios y bloqueos transaccionales.
2. Al crear el pedido se reserva, no se cobra. Un intento rechazado no libera inmediatamente la reserva porque puede haber otro intento del mismo pedido.
3. Al aprobar un pago se descuenta el stock una sola vez. La clave de checkout evita duplicar pedidos y los eventos de pago evitan procesar dos veces una misma notificación.
4. Las reservas vencidas se liberan. Si llega un pago tardío se intenta asignar disponibilidad; si no alcanza o el pedido se canceló, pasa a revisión.
5. Una aprobación debe concordar con importe, ARS, referencia privada, vendedor y ambiente. No acreditar por parámetros del navegador ni por el cuerpo del webhook sin consultar la API.
6. Una devolución de dinero no prueba que volvió la prenda. El administrador confirma la recepción física para reponer una sola vez.
7. Operadores pueden atender pedidos y stock; productos, descuentos, configuración y gestión de usuarios tienen restricciones de administrador. Mantener las restricciones del servidor aunque cambie la interfaz.
8. Un pago demo solo se confirma en local desde administración y no suma ingresos reales.

## 6. Verificación que ya se hizo

Última ejecución registrada durante la construcción: **30 pruebas aprobadas, 122 aserciones**, mediante `php artisan test --no-ansi`. Esta cifra es histórica, no una ejecución nueva al leer este documento.

Cobertura relevante: renderizado, roles y usuario desactivado, stock insuficiente, checkout repetido, aprobación duplicada, importe manipulado, intentos pendientes/rechazados posteriores, segundo pago, vencimiento, pago tardío con/sin stock, ajustes sobre stock reservado, reposición tras reembolso, cupones, precios del servidor, firma y vendedor de Mercado Pago, filtros Livewire, alertas y exclusión de ingresos demo.

También se verificaron desde navegador: compra demo con cupón y retiro, confirmación administrativa, descuento en MariaDB, búsqueda dinámica, menú y presentación móvil sin desbordamiento horizontal, y panel de escritorio. Compilación Vite exitosa. Colas sin trabajos fallidos en esa revisión y programador ejecutando vencimientos. Los trabajadores deben comprobarse de nuevo después de reiniciar o trasladar la PC.

La protección de sobreventa tiene pruebas funcionales secuenciales. **No se ha registrado una prueba de concurrencia real con procesos simultáneos sobre MariaDB**, ni una prueba de carga. No afirmar que se hicieron.

## 7. Qué falta y cómo darlo por terminado

### Necesario para lanzar la tienda

| Prioridad | Pendiente | Qué se necesita / criterio de finalización |
| --- | --- | --- |
| 1 | Datos reales del comercio | Usuario aporta productos, precios, fotos, contacto, retiro y reglas de envío/cambios. Cargar y revisar cada ficha; separar o retirar datos demo sin eliminar información real. |
| 2 | Pruebas reales de integración con Mercado Pago | Cuenta/aplicación y credenciales privadas de prueba, vendedor y URL pública HTTPS. Verificar aprobación, rechazo, repetición de webhook, vencimiento, pago tardío y reembolso. Confirmar que estado y stock coinciden con el proveedor. |
| 3 | Correo SMTP | Servidor/remitente autorizado y destinatarios de prueba acordados. Comprobar recepción real de pedido/pago/alertas y manejo de fallos. Evitar enviar al cliente mensajes viejos de pruebas al cambiar el transporte. |
| 4 | Alojamiento y dominio | Hosting compatible con Laravel/PHP/MariaDB y procesos de cola/programador. Configurar HTTPS, DocumentRoot, archivos persistentes y variables por entorno. Comprobar navegación y webhook desde fuera de la PC. |
| 5 | Operación y salida de demo | Respaldar base y fotos, comprobar restauración, logs y recuperación de colas. Ejecutar aceptación final; activar configuración productiva y desactivar demo cuando las dependencias anteriores estén verificadas. |

Estas tareas no requieren rehacer la aplicación. Las credenciales y servicios faltantes deben obtenerse/configurarse cuando el usuario decida conectarlos; nunca inventarlos ni pedir pegarlos en documentación.

### Trabajo técnico que puede continuarse sin servicios externos

- Añadir una prueba aislada de compras simultáneas sobre MariaDB, verificando que no se vende más stock del disponible y que se maneja la contención. Usar una base exclusiva de pruebas.
- Ampliar verificación de subida/galería de imágenes y recorridos administrativos completos de alta/edición, venta manual y entrega. No sustituir la suite existente por pruebas que solo reflejen el código.
- Revisar recuperación ante fallo de creación de preferencia, cola caída o notificación perdida. Hay reintentos de jobs; no hay un proceso periódico implementado de conciliación de todos los pagos contra Mercado Pago.
- Revisar zona horaria de negocio en cortes diarios/reportes antes del lanzamiento. La operación es Argentina; no asumir que la configuración temporal del servidor ya está adaptada.
- Si el panel crece, separar responsabilidades del controlador administrativo con pruebas que preserven el comportamiento. Es una mejora de mantenimiento, no un requisito para que la tienda funcione hoy.

Son próximos trabajos propuestos, no defectos reproducidos ni tareas ya realizadas. Priorizar según la próxima petición del usuario.

### Funciones que no están implementadas

Cotización/etiquetas automáticas de transportistas; facturación fiscal; sincronización de WhatsApp; cuentas de clientes; devoluciones parciales por prenda. El seguimiento del envío se carga manualmente. Los reembolsos se ejecutan en Mercado Pago; la tienda recibe estados de reembolso completo/contracargo y los parciales requieren conciliación manual. Definir alcance con el usuario antes de presentar cualquiera de estas integraciones como parte terminada.

## 8. Estado local y archivos privados

Hay cuatro productos de ejemplo y cupón `BIENVENIDA10`. El pedido demo `MT-FEKYGKVG` comprobó el circuito y consumió una Camisa Alba M; no representa ingreso real. Correo inicial administrativo: `admin@mitienda.local`. La contraseña se guarda en `storage/app/private/LOCAL-ACCESS.txt` y puede haber cambiado desde su generación. No copiarla a este documento.

Credenciales de DB y proveedores: `.env`, excluido del repositorio. No leer ni imprimir secretos como parte de una revisión general. `storage/app/private/local-workers.json` solo guarda identificadores de procesos de esa PC: no reutilizarlos al migrar. La carpeta no tenía repositorio `.git` en esta revisión; no asumir commits, rama o remoto existentes.

Instalación/operación detallada en `README.md`; traslado de archivos y base en `CONTINUAR-EN-OTRA-PC.md`. Conservar `APP_KEY` si se traslada la instalación. No ejecutar `migrate:fresh` para resolver errores de conexión.

## 9. Cómo retomar sin perder tiempo

1. Leer este archivo y `AGENTS.md`, revisar la petición actual del usuario y comprobar qué cambió en el código.
2. Identificar la carpeta, PHP y base disponibles. Si es otra PC, completar el traslado antes de desarrollar; la existencia del código no implica que la base esté importada.
3. Si se va a cambiar comportamiento, obtener una línea base de pruebas sobre el entorno aislado. Si falla, resolver la causa sin borrar la base del negocio.
4. Continuar la funcionalidad solicitada. Si el usuario solo pide seguir y el entorno ya funciona, proponer como siguiente bloque la validación de integración/operación de la sección 7; avanzar con las comprobaciones independientes de credenciales y pedir únicamente la información imprescindible.
5. Entregar qué se cambió, cómo se verificó y qué sigue pendiente; actualizar este documento para el próximo Codex.

## 10. Registro resumido de esta entrega

- 17/09/2026: aplicación local construida, integración de pagos simulada y recorrido demo verificados; 30 pruebas/122 aserciones; build de producción compilado.
- 17/09/2026: documentación de acceso, configuración y traslado en README y CONTINUAR-EN-OTRA-PC.
- 17/09/2026: añadido este contexto dedicado al desarrollo y `AGENTS.md`, a pedido del usuario. Este último trabajo solo modifica documentación; no activa pagos, publica el sitio ni constituye una nueva ejecución de la suite.

Para futuras entregas, añadir fecha, funcionalidad efectivamente terminada, archivos relevantes, verificación realizada, limitaciones y próximo paso. Actualizar las tablas de estado y pendientes para que el registro no contradiga la situación actual.