Uecko_ERP/docs/REQUISITOS CLIENTES.md

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:

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

GET /api/companies/{company_id}/clients
Authorization: Bearer <token>

4.2. Crear Cliente

POST /api/companies/{company_id}/clients
Authorization: Bearer <token>

Solicitud:

{
  "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

GET /api/clients/{client_id}
Authorization: Bearer <token>

4.4. Actualizar Cliente

PUT /api/clients/{client_id}
Authorization: Bearer <token>

4.5. Baja Lógica de Cliente

PATCH /api/clients/{client_id}/deactivate
Authorization: Bearer <token>

4.6. Asignar Comercial a Cliente

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.

---