# Plan de Implementación: API Middleware Node.js para Flutter

## Resumen Ejecutivo
Se implementará un API REST en Node.js que actuará como middleware entre la aplicación Flutter y la base de datos SQL Server. Este middleware expondrá endpoints de autenticación seguros, evitando la exposición directa de credenciales de BD en la app móvil.

## Arquitectura General

### Componentes Principales
```
Flutter App (Móvil)
    ↓ HTTP Requests
Node.js API Middleware (Puerto 3000)
    ↓ SQL Queries via mssql package
SQL Server Database (Puerto 1433)
```

### Tecnologías Seleccionadas
- **Node.js** con **Express.js** para el servidor web
- **mssql** para conexión a SQL Server
- **JWT** para autenticación stateless
- **bcrypt** para hash de contraseñas
- **CORS** para permitir conexiones desde Flutter
- **Helmet** y **express-rate-limit** para seguridad básica

## Ubicación en el Proyecto

El API middleware se ubicará en la carpeta `api-middleware/` dentro de la raíz de tu proyecto Laravel (`c:/xampp/htdocs/sistema_piter/api-middleware/`). Esta ubicación es intuitiva porque:

- Está al mismo nivel que `app/`, `config/`, etc.
- El nombre `api-middleware` deja claro su propósito
- Fácil de encontrar y navegar
- No interfiere con la estructura Laravel existente

## Estructura del Proyecto

```
c:/xampp/htdocs/sistema_piter/
├── api-middleware/              # ← NUEVA CARPETA AQUÍ
│   ├── src/
│   │   ├── config/
│   │   │   └── database.js      # Configuración de conexión SQL Server
│   │   ├── controllers/
│   │   │   └── authController.js # Lógica de negocio para autenticación
│   │   ├── middleware/
│   │   │   ├── auth.js         # Middleware JWT
│   │   │   └── validation.js   # Validación de entrada
│   │   ├── routes/
│   │   │   └── auth.js         # Definición de rutas /api/auth/*
│   │   └── utils/
│   │       └── responses.js    # Utilidades para respuestas JSON
│   ├── .env                    # Variables de entorno
│   ├── package.json            # Dependencias y scripts
│   ├── server.js               # Punto de entrada del servidor
│   └── README.md               # Documentación
├── app/                        # Tu proyecto Laravel existente
├── config/
└── ... (otros archivos Laravel)
```

## Endpoints a Implementar

### 1. POST /api/auth/login
**Propósito:** Autenticar usuarios existentes
**Request Body:**
```json
{
  "email": "cliente@ejemplo.com",
  "password": "password123"
}
```
**Proceso:**
1. Validar formato de email y presencia de password
2. Ejecutar stored procedure `sp_Sistema_Login`
3. Si exitoso, generar JWT token
4. Retornar datos del usuario + token

### 2. POST /api/auth/register
**Propósito:** Registrar nuevos clientes
**Request Body:**
```json
{
  "email": "nuevo@ejemplo.com",
  "password": "passwordSeguro",
  "nombre": "Ana",
  "apellido": "Gomez",
  "dni": "72345678",
  "telefono": "+51999888777"
}
```
**Proceso:**
1. Validar todos los campos requeridos
2. Hash de password con bcrypt
3. Ejecutar stored procedure `sp_Sistema_RegistroCliente`
4. Retornar ID del usuario creado

### 3. POST /api/auth/google
**Propósito:** Login/registro con Google OAuth
**Request Body:**
```json
{
  "email": "gmail@gmail.com",
  "googleId": "1234567890...",
  "nombre": "Daniel",
  "apellido": "G.",
  "fotoUrl": "https://lh3.googleusercontent.com/..."
}
```
**Proceso:**
1. Buscar usuario por email
2. Si existe, actualizar google_id
3. Si no existe, crear nuevo usuario con google_id
4. Retornar datos del usuario

## Configuración de Base de Datos

### Conexión SQL Server
```javascript
const config = {
  server: process.env.DB_HOST || '127.0.0.1',
  port: parseInt(process.env.DB_PORT) || 1433,
  database: process.env.DB_DATABASE || 'sistema_piter',
  user: process.env.DB_USERNAME || 'sa',
  password: process.env.DB_PASSWORD || 'Gk@2025_Segura!',
  options: {
    encrypt: true,
    trustServerCertificate: true,
  }
};
```

### Stored Procedures Requeridos
- `sp_Sistema_Login`: Recibe email/password, retorna datos del usuario si válido
- `sp_Sistema_RegistroCliente`: Recibe datos del cliente, crea registro y retorna ID

## Seguridad Implementada

### Autenticación JWT
- Tokens con expiración de 24 horas
- Payload incluye: userId, email, rol
- Middleware para validar tokens en rutas protegidas

### Validación de Entrada
- Email: formato válido
- Password: mínimo 6 caracteres
- Campos requeridos: validación de presencia
- Sanitización de datos

### Rate Limiting
- Máximo 5 intentos de login por minuto por IP
- Máximo 3 registros por hora por IP

### CORS
- Permitir orígenes desde app Flutter (desarrollo y producción)
- Métodos: POST, OPTIONS
- Headers: Content-Type, Authorization

## Manejo de Errores

### Formato Consistente
```json
{
  "success": false,
  "message": "Descripción del error"
}
```

### Tipos de Error
- 400 Bad Request: Datos inválidos
- 401 Unauthorized: Credenciales incorrectas
- 409 Conflict: Email ya registrado
- 500 Internal Server Error: Errores del servidor

## Despliegue y Testing

### Configuración de Puerto
- Puerto 3000 para desarrollo
- Variable de entorno `PORT` para producción
- Accesible desde red local (192.168.x.x:3000)

### Testing
- Postman/Insomnia para probar endpoints
- Casos de prueba:
  - Login exitoso
  - Login fallido
  - Registro exitoso
  - Registro con email duplicado
  - Google login nuevo usuario
  - Google login usuario existente

### Variables de Entorno
```
PORT=3000
DB_HOST=127.0.0.1
DB_PORT=1433
DB_DATABASE=sistema_piter
DB_USERNAME=sa
DB_PASSWORD=Gk@2025_Segura!
JWT_SECRET=tu_jwt_secret_seguro_aqui
NODE_ENV=development
```

## Próximos Pasos
1. Aprobar este plan
2. Crear estructura del proyecto
3. Implementar componentes paso a paso
4. Testing exhaustivo
5. Despliegue en servidor accesible

## Consideraciones Adicionales
- El middleware debe estar ejecutándose para que Flutter pueda conectarse
- Para testing en dispositivo físico, usar IP local en lugar de localhost
- Monitorear logs para debugging
- Implementar logging estructurado para producción