Autoparts-DB/manager/README.md

Nexus Instance Manager

Panel de control central para gestionar instancias multi-tenant de Nexus POS.

Qué hace

• Crear demos en 1 clic con subdominio, PIN de acceso y fecha de expiración
• Monitorear salud de todos los servicios (POS, DB, Redis, Quart, Systemd)
• Gestionar tenants: activar/desactivar, resetear datos, eliminar
• Ejecutar migraciones de schema en todos los tenants desde una UI
• Dashboard con estadísticas globales y alertas de demos por expirar

Estructura

manager/
├── app.py                  # Flask app principal
├── config.py               # Variables de entorno
├── wsgi.py                 # Entry point para Gunicorn
├── requirements.txt        # Dependencias
├── services/               # Lógica de negocio
│   ├── health_service.py   # Health checks de infraestructura
│   ├── tenant_service.py   # CRUD tenants (usa tenant_manager del POS)
│   └── migration_service.py# Orquestación de migraciones
├── blueprints/             # API REST
│   ├── auth_bp.py          # Login/logout JWT
│   ├── tenants_bp.py       # Gestión de tenants
│   ├── demos_bp.py         # Creación de demos
│   ├── health_bp.py        # Health checks
│   └── admin_bp.py         # Dashboard stats y migraciones
├── static/                 # Frontend SPA
│   ├── css/manager.css
│   └── js/manager.js
├── templates/
│   └── index.html          # Single Page App
├── scripts/
│   └── init_manager.py     # Inicialización de DB + admin
└── systemd/
    └── nexus-manager.service

Instalación rápida

1. Dependencias

cd /home/Autopartes/manager
pip install -r requirements.txt

2. Inicializar base de datos y usuario admin

cd /home/Autopartes/manager
python scripts/init_manager.py --email admin@nexus.local --password nexus2026 --name "Super Admin"

Esto crea:

• Tabla manager_users (login del panel)
• Tabla manager_audit_log (registro de acciones)
• Usuario admin por defecto

3. Configurar variables de entorno

Asegúrate de que estas variables estén disponibles (en systemd o .env):

MASTER_DB_URL=postgresql://postgres@/nexus_autoparts
TENANT_DB_URL_TEMPLATE=postgresql://postgres@/{db_name}
MANAGER_JWT_SECRET=genera-un-segredo-largo-aqui
POS_DIR=/home/Autopartes/pos
REDIS_URL=redis://localhost:6379/0

4. Registrar servicio systemd

cp systemd/nexus-manager.service /etc/systemd/system/
systemctl daemon-reload
systemctl enable nexus-manager
systemctl start nexus-manager

Accede en: http://TU_IP:5003

5. (Opcional) Agregar a nginx

server {
    listen 80;
    server_name manager.nexusautoparts.com.mx;

    location / {
        proxy_pass http://127.0.0.1:5003;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_read_timeout 300s;
    }
}

Uso

Crear una demo

1. Ve a la sección Crear Demos
2. Llena nombre del negocio, email, días de vigencia
3. El subdominio se genera automáticamente (puedes personalizarlo)
4. Click en Crear Demo
5. El panel muestra la URL de acceso y el PIN del owner

Resetear una demo

• Presiona el ícono de 🔄 en la tabla de demos
• Limpia TODO el inventario, ventas, clientes, facturas
• Conserva empleados (incluyendo el owner) y configuración fiscal

Eliminar una demo

• Presiona 🗑️ y confirma
• Borra permanentemente la base de datos del tenant

Migraciones

• Ve a Migraciones para ver la versión de schema de cada tenant
• Ejecutar todas pendientes aplica migraciones en TODOS los tenants

Notas de seguridad

• Cambia MANAGER_JWT_SECRET en producción
• El panel expone acciones destructivas (delete/reset); protege el acceso con firewall o VPN
• Usa HTTPS en producción