PANEL_BASES_ANEXO24/INSTALACION_USUARIOS.md

# 🚀 Sistema Completo de Gestión de Usuarios y Permisos

## ✅ ¿Qué se ha implementado?

### 1. **Sistema de Autenticación**
- ✅ Login con usuario y contraseña
- ✅ Tokens JWT seguros
- ✅ Cookies HTTP-only
- ✅ Sesiones persistentes (7 días)
- ✅ Logout seguro
- ✅ Protección de rutas

### 2. **Gestión de Usuarios (Solo Admins)**
- ✅ Crear nuevos usuarios
- ✅ Editar usuarios existentes
- ✅ Activar/desactivar usuarios
- ✅ Eliminar usuarios
- ✅ Asignar rol de administrador

### 3. **Sistema de Permisos**
- ✅ Permisos granulares por base de datos
- ✅ Asignación/revocación de permisos
- ✅ Filtrado automático de bases de datos según permisos
- ✅ Administradores con acceso total

### 4. **Base de Datos PostgreSQL**
- ✅ Tabla de usuarios
- ✅ Tabla de permisos
- ✅ Tabla de sesiones
- ✅ Índices para rendimiento
- ✅ Constraints de integridad

### 5. **Seguridad**
- ✅ Contraseñas hasheadas con bcrypt
- ✅ Validación de contraseñas fuertes
- ✅ Tokens JWT con expiración
- ✅ Protección contra SQL injection
- ✅ Sanitización de entradas

## 📦 Archivos Creados

### Backend (Server)
```
src/lib/server/
├── auth.ts              # Utilidades de autenticación JWT y bcrypt
├── users.ts             # CRUD de usuarios y permisos
└── db.ts                # Conexión a PostgreSQL (actualizado)

src/routes/
├── login/
│   ├── +page.svelte         # Interfaz de login
│   └── +page.server.ts      # Lógica de autenticación
├── logout/
│   └── +server.ts           # Cerrar sesión
├── usuarios/
│   ├── +page.svelte         # Gestión de usuarios (UI)
│   ├── +page.server.ts      # CRUD y permisos
│   └── api/permissions/
│       └── +server.ts       # API de permisos
└── +page.server.ts          # Panel principal (actualizado con filtros)
```

### Base de Datos
```
database/
└── schema.sql           # Script de creación de tablas
```

### Documentación
```
docs/
└── USUARIOS.md          # Guía completa del sistema

scripts/
├── generate-password-hash.js    # Generar hash de contraseñas
└── init-users.sh                # Script de inicialización
```

### Configuración
```
.env.example             # Variables de entorno de ejemplo
```

## 🛠️ Instalación y Configuración

### Paso 1: Instalar Dependencias

```bash
npm install
```

Las dependencias ya están en package.json:
- `bcrypt` - Hash de contraseñas
- `jsonwebtoken` - Tokens JWT
- `pg` - Cliente PostgreSQL
- `@types/pg`, `@types/bcrypt`, `@types/jsonwebtoken` - Tipos TypeScript

### Paso 2: Configurar PostgreSQL

#### Opción A: Desde la línea de comandos
```bash
psql -h 10.0.20.152 -U postgres -d CONTROLDESK -f database/schema.sql
```

#### Opción B: Desde pgAdmin o DBeaver
1. Abre el archivo `database/schema.sql`
2. Copia todo el contenido
3. Pégalo en la consola SQL
4. Ejecuta el script

### Paso 3: Generar Contraseña del Admin

```bash
node scripts/generate-password-hash.js
```

Este script generará un hash para la contraseña `Admin123!`. 

**IMPORTANTE:** Copia el hash generado y actualiza el archivo `database/schema.sql` en la línea del INSERT del usuario admin, reemplazando el hash temporal.

Luego vuelve a ejecutar el INSERT en PostgreSQL:

```sql
INSERT INTO usuarios (username, email, password_hash, nombre_completo, es_admin, activo)
VALUES (
    'admin',
    'admin@aduanasoft.com',
    'EL_HASH_QUE_GENERASTE',  -- <-- Pega aquí el hash
    'Administrador del Sistema',
    true,
    true
)
ON CONFLICT (username) DO UPDATE SET
    password_hash = EXCLUDED.password_hash;
```

### Paso 4: Configurar Variables de Entorno

```bash
cp .env.example .env
```

Edita `.env` y actualiza los valores:

```env
# PostgreSQL
DB_POSTGRES_HOST=10.0.20.152
DB_POSTGRES_PORT=5432
DB_POSTGRES_USER=postgres
DB_POSTGRES_PASS=Control.
DB_POSTGRES_DB=CONTROLDESK

# JWT Secret (¡CÁMBIALO!)
JWT_SECRET=un-secreto-muy-largo-y-aleatorio-para-produccion
```

**⚠️ IMPORTANTE:** En producción, genera un JWT_SECRET aleatorio y seguro:
```bash
node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"
```

### Paso 5: Iniciar el Servidor

```bash
npm run dev
```

### Paso 6: Primer Login

1. Ve a `http://localhost:5173/login`
2. Usuario: `admin`
3. Contraseña: `Admin123!` (o la que configuraste)

## 📖 Uso del Sistema

### Para Administradores

#### 1. Crear un Nuevo Usuario
1. Ve a "Gestión de Usuarios" en el sidebar
2. Haz clic en "Nuevo Usuario"
3. Completa el formulario:
   - **Usuario**: Nombre de usuario único
   - **Email**: Correo electrónico
   - **Nombre Completo**: Nombre real
   - **Contraseña**: Mínimo 8 caracteres con mayúsculas, minúsculas, números y símbolos
   - **Es Administrador**: Marca si quieres que sea admin
4. Haz clic en "Crear Usuario"

#### 2. Asignar Permisos de Bases de Datos
1. En la lista de usuarios, haz clic en el ícono 🔒 (candado)
2. Verás todas las bases de datos disponibles
3. Haz clic en "Sin Acceso" para otorgar acceso
4. Haz clic en "Con Acceso" para revocar acceso
5. Los cambios se guardan automáticamente

#### 3. Editar un Usuario
1. Haz clic en el ícono ✏️ (editar)
2. Modifica los campos que necesites
3. Para cambiar la contraseña, escribe una nueva (si dejas vacío, no se cambia)
4. Haz clic en "Guardar Cambios"

#### 4. Desactivar un Usuario
1. Haz clic en el ícono de toggle (activar/desactivar)
2. Confirma la acción
3. El usuario no podrá iniciar sesión, pero sus datos se conservan

#### 5. Eliminar un Usuario
1. Haz clic en el ícono 🗑️ (eliminar)
2. Confirma la acción
3. **¡CUIDADO!** Esta acción es permanente

### Para Usuarios Normales

Los usuarios normales solo verán:
- Las bases de datos que les han sido asignadas
- No tendrán acceso a "Gestión de Usuarios"
- El resto del panel funciona igual

## 🔒 Cómo Funciona la Seguridad

### Flujo de Autenticación

```
1. Usuario ingresa credenciales
   ↓
2. Servidor verifica con bcrypt
   ↓
3. Se genera token JWT
   ↓
4. Token se guarda en cookie HTTP-only
   ↓
5. Cada petición verifica el token
   ↓
6. Se aplican filtros de permisos
```

### Filtrado de Bases de Datos

```typescript
// En +page.server.ts (líneas 376-379)
if (!currentUser.es_admin) {
    // Filtra solo las bases de datos que el usuario puede ver
    databaseRows = await filterDatabasesByUserPermissions(currentUser.id, databaseRows);
    alertsData = await filterDatabasesByUserPermissions(currentUser.id, alertsData);
}
```

## 📊 Estructura de la Base de Datos

### Tabla `usuarios`
Almacena información de los usuarios del sistema.

| Campo | Tipo | Descripción |
|-------|------|-------------|
| id | SERIAL | ID único |
| username | VARCHAR(50) | Nombre de usuario único |
| email | VARCHAR(100) | Email único |
| password_hash | VARCHAR(255) | Contraseña hasheada |
| nombre_completo | VARCHAR(100) | Nombre completo |
| activo | BOOLEAN | Si el usuario está activo |
| es_admin | BOOLEAN | Si es administrador |
| fecha_creacion | TIMESTAMP | Fecha de creación |
| ultimo_acceso | TIMESTAMP | Último login |

### Tabla `usuario_base_datos`
Relaciona usuarios con bases de datos y sus permisos.

| Campo | Tipo | Descripción |
|-------|------|-------------|
| id | SERIAL | ID único |
| usuario_id | INTEGER | FK a usuarios |
| base_datos_nombre | VARCHAR(255) | Nombre de la BD |
| puede_ver | BOOLEAN | Permiso de visualización |
| puede_descargar_backup | BOOLEAN | Permiso de descarga (futuro) |
| puede_restaurar | BOOLEAN | Permiso de restauración (futuro) |
| fecha_asignacion | TIMESTAMP | Fecha de asignación |

## 🐛 Solución de Problemas

### "No puedo iniciar sesión"
1. Verifica que el hash de contraseña sea correcto en la BD
2. Revisa los logs del servidor (terminal donde corre `npm run dev`)
3. Asegúrate de que PostgreSQL esté corriendo
4. Verifica las credenciales en `.env`

### "No veo ninguna base de datos"
1. Si eres admin, deberías ver todas
2. Si eres usuario normal, verifica que tengas permisos asignados:
   ```sql
   SELECT * FROM usuario_base_datos WHERE usuario_id = TU_ID;
   ```

### "Error de conexión a PostgreSQL"
1. Verifica que PostgreSQL esté corriendo:
   ```bash
   psql -h 10.0.20.152 -U postgres -c "SELECT version();"
   ```
2. Revisa el firewall del servidor
3. Verifica las credenciales en `.env`

### "Invalid token" o "Session expired"
1. Cierra sesión y vuelve a iniciar
2. Limpia las cookies del navegador
3. Verifica que `JWT_SECRET` sea el mismo en `.env`

## 🎯 Próximos Pasos Recomendados

1. **Cambiar el JWT_SECRET** en `.env` a un valor aleatorio y seguro
2. **Actualizar la contraseña del admin** después del primer login
3. **Crear usuarios** para tu equipo
4. **Asignar permisos** según las responsabilidades de cada usuario
5. **Probar el sistema** con diferentes usuarios
6. **Configurar backups** de la base de datos PostgreSQL
7. **Documentar** los usuarios y sus permisos para tu organización

## 📞 Soporte

Para preguntas o problemas, contacta al equipo de desarrollo.

---

**Desarrollado para Aduanasoft** - Panel de Gestión de Bases de Datos SCAII