# **Especificaciones del Módulo de Clientes - ERP**

El **módulo de clientes** del ERP permite gestionar la información de clientes, asegurando compatibilidad con la gestión multiempresa, multiidioma y multi-moneda. A continuación, se detallan las especificaciones, incluyendo los campos clave y su función.

---

## **1. Funcionalidades del Módulo de Clientes**
El módulo de clientes debe permitir:
- **Crear, leer, actualizar y eliminar clientes** (CRUD).
- **Asociar clientes a una empresa** y, opcionalmente, a una o más sucursales.
- **Registrar clientes como personas físicas o empresas**.
- **Gestionar datos fiscales, comerciales y de contacto**.
- **Definir configuraciones de facturación y pago personalizadas**.
- **Aplicar descuentos en distintos niveles**.
- **Manejar aspectos financieros como retenciones y recargos**.
- **Identificar clientes con riesgo financiero**.
- **Asignar comerciales o delegados**.
- **Controlar el estado del cliente** (activo/inactivo).
- **Registrar auditoría de cambios**.

---

## **2. Estructura del Cliente y sus Campos**
Cada cliente tiene los siguientes atributos:

### **Datos Generales**
| Campo                 | Tipo de Dato     | Descripción |
|-----------------------|-----------------|-------------|
| `id`                 | `INT` (PK)       | Identificador único del cliente. |
| `company_id`         | `INT` (FK)       | Empresa a la que pertenece el cliente. |
| `is_company`         | `BOOLEAN`        | Indica si el cliente es una empresa (`true`) o una persona física (`false`). |
| `fiscal_name`        | `VARCHAR(255)`   | Nombre fiscal del cliente (solo si es empresa). |
| `commercial_name`    | `VARCHAR(255)`   | Nombre comercial del cliente (si aplica). |
| `name`               | `VARCHAR(255)`   | Nombre de la persona o empresa. |
| `email`              | `VARCHAR(100)`   | Correo electrónico único del cliente. |
| `phone`              | `VARCHAR(20)`    | Número de teléfono de contacto. |
| `address`            | `TEXT`           | Dirección del cliente. |
| `country_code`       | `CHAR(2)`        | Código del país del cliente (ISO 3166-1 alpha-2). |
| `origin`             | `VARCHAR(100)`   | Origen del cliente (ej. publicidad, redes sociales, feria, escaparate). |

### **Configuración de Moneda e Idioma**
| Campo               | Tipo de Dato     | Descripción |
|---------------------|-----------------|-------------|
| `currency_code`    | `CHAR(3)`        | Código de la divisa con la que trabaja el cliente (ISO 4217). |
| `language_code`    | `CHAR(5)`        | Idioma preferido del cliente para documentos y comunicación (ej. `es-ES`, `en-US`). |

### **Información Fiscal y Financiera**
| Campo                  | Tipo de Dato    | Descripción |
|------------------------|----------------|-------------|
| `vat_percentage`       | `DECIMAL(5,2)`  | Porcentaje de IVA aplicable al cliente. |
| `equivalence_charge`   | `BOOLEAN`       | Indica si el cliente aplica recargo de equivalencia. |
| `withholding_percentage` | `DECIMAL(5,2)` | Porcentaje de retención en facturas del cliente. |
| `payment_method`       | `VARCHAR(100)`  | Forma de pago habitual del cliente (ej. transferencia, tarjeta, efectivo). |
| `payment_day`          | `INT`           | Día del mes en que el cliente realiza pagos (1-31). |
| `risk`                | `BOOLEAN`       | Indica si el cliente tiene riesgo financiero o historial de morosidad. |

### **Descuentos y Tarifas Especiales**
| Campo               | Tipo de Dato    | Descripción |
|---------------------|----------------|-------------|
| `discount_line`     | `DECIMAL(5,2)`  | Descuento aplicado a nivel de línea en presupuestos. |
| `discount_chapter`  | `DECIMAL(5,2)`  | Descuento aplicado a nivel de capítulo en presupuestos. |
| `discount_global`   | `DECIMAL(5,2)`  | Descuento global aplicado al presupuesto. |
| `price_point`       | `DECIMAL(10,2)` | Valor de "precio punto" del cliente, usado para calcular costos personalizados en catálogo. |

### **Clasificación y Estado**
| Campo           | Tipo de Dato    | Descripción |
|---------------|----------------|-------------|
| `client_type` | `VARCHAR(100)`  | Tipo de cliente (ej. profesionales, constructoras, distribuidores, particulares). |
| `is_active`   | `BOOLEAN`       | Indica si el cliente está activo (`true`) o dado de baja (`false`). |

### **Delegados y Comerciales**
| Campo            | Tipo de Dato    | Descripción |
|-----------------|----------------|-------------|
| `Client_Sales_Rep` | `Tabla Relacional` | Relación con los comerciales asignados a este cliente. |

---

## **3. Auditoría y Seguridad**
Cada cambio en los datos de un cliente debe registrarse en una tabla de auditoría:
```sql
CREATE TABLE Client_Audit (
    id SERIAL PRIMARY KEY,
    client_id INT NOT NULL REFERENCES Clients(id) ON DELETE CASCADE,
    user_id INT NOT NULL REFERENCES Users(id),
    change_description TEXT,
    change_timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```
Esto permitirá rastrear modificaciones y garantizar transparencia en la gestión de clientes.

---

## **4. Endpoints Principales de la API**
### **4.1. Listar Clientes**
```http
GET /api/companies/{company_id}/clients
Authorization: Bearer <token>
```

### **4.2. Crear Cliente**
```http
POST /api/companies/{company_id}/clients
Authorization: Bearer <token>
```
**Solicitud:**
```json
{
  "is_company": true,
  "fiscal_name": "Empresa XYZ SL",
  "commercial_name": "XYZ Comercial",
  "name": "Empresa XYZ",
  "email": "contacto@xyz.com",
  "phone": "+34912345678",
  "country_code": "ES",
  "origin": "Publicidad",
  "currency_code": "EUR",
  "language_code": "es-ES",
  "vat_percentage": 21.00,
  "payment_method": "Transferencia bancaria",
  "discount_line": 5.00,
  "discount_chapter": 2.50,
  "discount_global": 10.00,
  "price_point": 1.20,
  "payment_day": 15,
  "risk": false,
  "equivalence_charge": false,
  "withholding_percentage": 10.00,
  "client_type": "Distribuidor",
  "is_active": true
}
```

### **4.3. Obtener Cliente por ID**
```http
GET /api/clients/{client_id}
Authorization: Bearer <token>
```

### **4.4. Actualizar Cliente**
```http
PUT /api/clients/{client_id}
Authorization: Bearer <token>
```

### **4.5. Baja Lógica de Cliente**
```http
PATCH /api/clients/{client_id}/deactivate
Authorization: Bearer <token>
```

### **4.6. Asignar Comercial a Cliente**
```http
POST /api/clients/{client_id}/sales-reps
Authorization: Bearer <token>
```

---

## **5. Seguridad y Control de Acceso**
- **Middleware de autenticación** para validar que solo usuarios autorizados gestionen clientes.
- **Permisos basados en roles**, como `Clientes: leer`, `Clientes: escribir`, `Clientes: eliminar`.
- **Reglas de validación** para evitar datos erróneos o incompletos.
- **Registro de auditoría** para cada modificación.

---