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
- **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

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

### 2. Inicializar base de datos y usuario admin

```bash
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`):

```bash
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

```bash
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

```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

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

### 2. Instalar dependencias

```bash
pip install -r requirements.txt
```

### 3. Configurar variables para conexión remota

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

```bash
# 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

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

### 5. Systemd

```bash
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:

  ```bash
  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)