Autoparts-DB/manager

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
• Cartera: métricas de negocio por tenant (rollup diario), score de salud/riesgo de churn y anomalías entre tenants
• 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)
│   ├── portfolio_service.py# Rollup de métricas, lectura de cartera y anomalías
│   ├── business_metrics.py # Z-score robusto multi-tenant + score de salud
│   └── 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
│   ├── portfolio_bp.py     # /api/tenants/metrics y /api/portfolio/anomalies
│   └── 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 # Servicio systemd
└── README.md                 # Documentación completa

Instalación rápida (mismo servidor)

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@localhost/nexus_autoparts
TENANT_DB_URL_TEMPLATE=postgresql://postgres@localhost/{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;
    }
}

---

Instalación en Máquina Virtual separada (misma red local)

Si el manager corre en una VM diferente al servidor principal (donde está PostgreSQL + POS):

Requisitos de red

• PostgreSQL del servidor principal debe escuchar en 0.0.0.0:5432 (verificar listen_addresses = '*' en postgresql.conf)
• POS (5001), Dashboard (5000) y Quart (5002) ya escuchan en 0.0.0.0 por defecto
• Redis puede estar solo en 127.0.0.1; en ese caso el health check mostrará advertencia pero no afecta el funcionamiento

1. Clonar el repo en la VM

git clone https://git.consultoria-as.com/consultoria-as/Autoparts-DB.git /home/Autopartes
cd /home/Autopartes/manager

2. Instalar dependencias

pip install -r requirements.txt

3. Configurar variables para conexión remota

Crea /home/Autopartes/manager/.env o edita el servicio systemd:

# IP del servidor principal donde corre PostgreSQL y POS
NEXUS_SERVER_HOST=192.168.10.91

# PostgreSQL remoto (cambiar localhost por la IP del servidor)
MASTER_DB_URL=postgresql://nexus:PASSWORD@192.168.10.91/nexus_autoparts
TENANT_DB_URL_TEMPLATE=postgresql://nexus:PASSWORD@192.168.10.91/{db_name}

# Redis remoto (puede no funcionar si Redis solo escucha en localhost)
REDIS_URL=redis://192.168.10.91:6379/0

# Seguridad
MANAGER_JWT_SECRET=genera-un-segredo-largo-aqui
POS_DIR=/home/Autopartes/pos

Nota importante: La VM manager no necesita una instalación completa del POS. Solo necesita:

• Los archivos de manager/
• Los archivos de pos/ (para reutilizar tenant_manager.py y migraciones)
• Conectividad TCP al puerto 5432 del servidor principal

4. Inicializar DB y admin

cd /home/Autopartes/manager
python scripts/init_manager.py --email admin@nexus.local --password TU_PASSWORD

5. Systemd

cp systemd/nexus-manager.service /etc/systemd/system/
# Edita el archivo y cambia localhost por la IP del servidor en MASTER_DB_URL y NEXUS_SERVER_HOST
nano /etc/systemd/system/nexus-manager.service

systemctl daemon-reload
systemctl enable nexus-manager
systemctl start nexus-manager

---

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

Cartera (métricas, salud y anomalías)

• La sección Cartera muestra el score de salud/riesgo de churn por tenant y las anomalías detectadas entre tenants (z-score robusto con mediana + MAD).

• Los datos vienen de la tabla maestra tenant_metrics_daily, que se llena con el rollup diario:

  python3 scripts/rollup_tenant_metrics.py              # hoy, tenants activos
  python3 scripts/rollup_tenant_metrics.py --days 30    # backfill últimos 30 días
  python3 scripts/rollup_tenant_metrics.py --all        # incluir inactivos
  

  El script crea la tabla de forma idempotente (no usa el runner de migraciones de tenants) y es seguro re-ejecutarlo para la misma fecha.

• Endpoints (requieren Authorization: Bearer <token>):

  • GET /api/tenants/metrics?days=14 — rollup + {health_score, band, signals} por tenant
  • GET /api/portfolio/anomalies?date=YYYY-MM-DD&z=3.0&min_tenants=5 — anomalías entre tenants

  Con menos de min_tenants tenants en la cohorte el detector devuelve cold_start: true y no emite hallazgos. La "actividad" usa audit_log como proxy porque no se persisten logins individuales.

---

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
• Si despliegas en VM separada, asegúrate de que el firewall del servidor principal permite conexiones desde la IP de la VM manager al puerto 5432 (PostgreSQL)