# 🚀 Quick Start — Perfumados Sistema v2.0 ## ⚡ En 5 minutos ### 1. Descargar y preparar ```bash cd perfumados_mejorado python -m venv venv source venv/bin/activate # Linux/Mac # o venv\Scripts\activate en Windows ``` ### 2. Instalar dependencias ```bash pip install -r requirements.txt ``` ### 3. Ejecutar la app ```bash python app.py ``` ### 4. Acceder ``` http://localhost:5000 Email: admin@perfumados.cl Contraseña: admin123 ``` --- ## 📋 Checklist de desarrollo ### Configuración básica ✅ - [x] Estructura modular (app.py, models.py, utils.py) - [x] Base de datos con SQLAlchemy - [x] Sistema de autenticación con contraseñas hasheadas - [x] Roles y permisos (admin, supervisor, empleado) ### Funcionalidades ✅ - [x] Dashboard consolidado - [x] Gestión de ventas (crear, importar Excel) - [x] Gestión de empleados - [x] Control de asistencia con GPS - [x] Reportes analíticos - [x] Cierre de cajas ### UI/UX ✅ - [x] Dark mode completo - [x] Responsive design - [x] Sidebar con navegación - [x] Alertas y notificaciones - [x] Formularios mejorados ### Seguridad ✅ - [x] Contraseñas hasheadas (werkzeug) - [x] Validaciones de entrada - [x] Decoradores para control de acceso - [x] Soft delete --- ## 🔧 Características principales ### Dashboard - **Stats en tiempo real** por local - **Resumen de ventas** del día - **Totales por forma de pago** ### Ventas - Registro manual de ventas - **Importación desde Excel** automática - Filtros por fecha, turno, forma de pago - Reportes del período ### Empleados - Base de datos completa - Validación de RUT - Seguimiento por local - Asignación de vendedores ### Asistencia - Marcaje entrada/salida - **Validación GPS** (Haversine) - Radio permitido: 300m - Reportes por período ### Reportes - Gráficos con Chart.js - Totales por forma de pago - Promedio de ventas/día - Exportación a PDF --- ## 📁 Estructura de archivos ``` perfumados_mejorado/ ├── app.py ← Aplicación principal (rutas) ├── models.py ← Modelos BD ├── utils.py ← Utilidades y decoradores ├── requirements.txt ← Dependencias ├── README.md ← Documentación completa ├── .env.example ← Variables de entorno ├── passenger_wsgi.py ← Para servidor ├── .htaccess ← Config Apache │ ├── templates/ ← Templates HTML │ ├── base.html │ ├── login.html │ ├── dashboard.html │ ├── ventas.html │ ├── empleados.html │ ├── asistencia.html │ └── ... │ ├── static/ │ ├── css/ │ │ └── style.css ← Estilos (dark mode) │ ├── js/ │ │ ├── app.js │ │ └── gps.js │ └── img/ │ └── instance/ └── perfumados.db ← BD (creada automáticamente) ``` --- ## 🔐 Seguridad ### Implementado ✅ Contraseñas hasheadas ✅ Validaciones de entrada ✅ Control de acceso por roles ✅ Soft delete ### Por implementar (producción) ⚠️ Implementar `Flask-WTF` para CSRF ⚠️ Rate limiting en login ⚠️ Usar `.env` para `SECRET_KEY` ⚠️ Auditoría de cambios ⚠️ Backup automático --- ## 🚨 Variables de entorno Crear archivo `.env`: ``` FLASK_ENV=production SECRET_KEY=tu-clave-super-secreta-de-min-32-caracteres DEBUG=False ``` --- ## 🛠️ Cambios importantes vs v1.0 ### ✨ Mejoras | Aspecto | v1.0 | v2.0 | |--------|------|------| | Estructura | Monolítica | Modular (models, utils, routes) | | Contraseñas | Texto plano | Hasheadas (werkzeug) | | Validaciones | Básicas | Completas | | Índices BD | Parciales | Optimizados | | Decimales GPS | Float | Float (mejorado) | | Documentación | Mínima | Completa | --- ## 📊 Endpoints principales ### Autenticación ``` POST /login GET /logout ``` ### Dashboard ``` GET /dashboard ``` ### Ventas ``` GET /ventas/ POST /ventas//nueva POST /ventas//importar ``` ### Empleados ``` GET /empleados POST /empleados/nuevo POST /empleados//editar ``` ### Asistencia ``` GET /asistencia POST /asistencia/registrar GET /asistencia/reporte ``` ### Reportes ``` GET /reportes ``` --- ## 🐛 Troubleshooting ### "No module named 'flask'" ```bash pip install -r requirements.txt ``` ### "Database locked" Eliminar `instance/perfumados.db` y ejecutar de nuevo ```bash rm instance/perfumados.db python app.py ``` ### "Port 5000 already in use" ```bash python app.py --port 5001 ``` ### GPS no valida 1. Verificar coordenadas en `models.py` → `LOCALES_CONFIG` 2. Verificar radio: `validar_ubicacion_gps()` en `utils.py` 3. Probar en `http://localhost:5000/asistencia` --- ## 📝 Próximos pasos 1. **Producción** - Cambiar `SECRET_KEY` - Implementar CSRF tokens - Agregar rate limiting - Configurar logs 2. **Funcionalidades** - Recuperación de contraseña - 2FA - Auditoría - Inventario 3. **Integración** - API REST - WebSockets - App móvil --- ## 💡 Tips ### Crear usuario supervisor ```bash python >>> from app import app, db >>> from models import Usuario >>> with app.app_context(): >>> user = Usuario(nombre='Juan', email='juan@perfumados.cl', rol='supervisor') >>> user.set_password('pass123') >>> db.session.add(user) >>> db.session.commit() ``` ### Importar datos de prueba ```bash # TODO: Crear script seed_data.py python scripts/seed_data.py ``` ### Hacer backup de la BD ```bash cp instance/perfumados.db instance/perfumados.db.bak ``` --- ## 📞 Soporte - Revisar logs en `logs/` - Consultar [README.md](README.md) para documentación completa - Reportar bugs con stack trace --- **Versión:** 2.0.0 (Modular & Secure) **Última actualización:** Mayo 2026