# Especificaciones de Módulos Futuros

Este documento contiene las especificaciones de diseño para módulos planificados del sistema.

---

## 1. Vendedores, Cobradores y Comisiones

### Descripción
Sistema para gestionar vendedores y cobradores con asignación a facturas, planificación de rutas de cobranza y liquidación de comisiones.

### Modelo de datos

```sql
-- Tabla principal de vendedores/cobradores
CREATE TABLE vendedores_cobradores (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    usuario_id UUID REFERENCES usuario(id),
    empresa_id UUID NOT NULL REFERENCES empresas(id),
    tipo VARCHAR(20) NOT NULL CHECK (tipo IN ('vendedor', 'cobrador', 'ambos')),
    zona_id UUID, -- Para rutas de cobranza
    comision_porcentaje DECIMAL(5,2) DEFAULT 0,
    comision_fija DECIMAL(15,2) DEFAULT 0,
    active BOOLEAN DEFAULT true,
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);

-- Asignación de facturas a vendedor/cobrador
CREATE TABLE asignacion_facturas (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    factura_id UUID NOT NULL REFERENCES facturas(id),
    cobrador_id UUID REFERENCES vendedores_cobradores(id),
    vendedor_id UUID REFERENCES vendedores_cobradores(id),
    fecha_asignacion TIMESTAMP DEFAULT NOW(),
    fecha_cobro_programada DATE,
    estado VARCHAR(20) DEFAULT 'pendiente' CHECK (estado IN ('pendiente', 'en_ruta', 'cobrado', 'reprogramado', 'cancelado')),
    notas TEXT,
    asignado_por UUID REFERENCES usuario(id),
    created_at TIMESTAMP DEFAULT NOW()
);

-- Rutas de cobranza diarias
CREATE TABLE rutas_cobranza (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    empresa_id UUID NOT NULL REFERENCES empresas(id),
    cobrador_id UUID NOT NULL REFERENCES vendedores_cobradores(id),
    fecha DATE NOT NULL,
    estado VARCHAR(20) DEFAULT 'planificada' CHECK (estado IN ('planificada', 'en_curso', 'completada', 'cancelada')),
    observaciones TEXT,
    created_at TIMESTAMP DEFAULT NOW()
);

-- Relación ruta-facturas
CREATE TABLE ruta_facturas (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    ruta_id UUID NOT NULL REFERENCES rutas_cobranza(id),
    asignacion_factura_id UUID NOT NULL REFERENCES asignacion_facturas(id),
    orden INTEGER,
    cobrado BOOLEAN DEFAULT false,
    monto_cobrado DECIMAL(15,2),
    fecha_cobro TIMESTAMP,
    notas TEXT
);

-- Comisiones generadas
CREATE TABLE comisiones (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    vendedor_cobrador_id UUID NOT NULL REFERENCES vendedores_cobradores(id),
    factura_id UUID REFERENCES facturas(id),
    tipo VARCHAR(20) NOT NULL CHECK (tipo IN ('venta', 'cobranza')),
    monto_base DECIMAL(15,2) NOT NULL,
    porcentaje_aplicado DECIMAL(5,2),
    monto_comision DECIMAL(15,2) NOT NULL,
    estado VARCHAR(20) DEFAULT 'pendiente' CHECK (estado IN ('pendiente', 'aprobada', 'liquidada', 'cancelada')),
    fecha_liquidacion DATE,
    liquidacion_id UUID, -- Para agrupar liquidaciones
    created_at TIMESTAMP DEFAULT NOW()
);

-- Zonas de cobranza
CREATE TABLE zonas_cobranza (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    empresa_id UUID NOT NULL REFERENCES empresas(id),
    nombre VARCHAR(100) NOT NULL,
    descripcion TEXT,
    active BOOLEAN DEFAULT true
);
```

### Funcionalidades
- Asignación automática o manual de cobrador al crear factura
- Planificación de rutas por día/zona
- Dashboard de cobranza con facturas pendientes por cobrador
- Liquidación de comisiones mensual/quincenal
- Rol "Supervisor de Cobranza" para gestionar asignaciones
- Reportes de rendimiento por vendedor/cobrador

---

## 2. Lista de Precios y Planes de Cuotas

### Descripción
Sistema para gestionar múltiples listas de precios y planes de financiamiento con cuotas.

### Modelo de datos

```sql
-- Listas de precios
CREATE TABLE listas_precios (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    empresa_id UUID NOT NULL REFERENCES empresas(id),
    nombre VARCHAR(100) NOT NULL,
    descripcion TEXT,
    tipo VARCHAR(20) DEFAULT 'general' CHECK (tipo IN ('general', 'mayorista', 'empleados', 'convenio')),
    prioridad INTEGER DEFAULT 0,
    fecha_vigencia_desde DATE,
    fecha_vigencia_hasta DATE,
    active BOOLEAN DEFAULT true,
    created_at TIMESTAMP DEFAULT NOW()
);

-- Items de lista de precios
CREATE TABLE lista_precio_items (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    lista_precio_id UUID NOT NULL REFERENCES listas_precios(id),
    producto_id UUID NOT NULL REFERENCES productos(id),
    precio_base DECIMAL(15,2) NOT NULL,
    precio_contado DECIMAL(15,2), -- Precio con descuento por pago contado
    active BOOLEAN DEFAULT true,
    UNIQUE(lista_precio_id, producto_id)
);

-- Planes de cuotas
CREATE TABLE planes_cuotas (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    empresa_id UUID NOT NULL REFERENCES empresas(id),
    nombre VARCHAR(100) NOT NULL,
    descripcion TEXT,
    cantidad_cuotas INTEGER NOT NULL,
    interes_porcentaje DECIMAL(5,2) DEFAULT 0,
    recargo_financiero DECIMAL(5,2) DEFAULT 0,
    aplica_a VARCHAR(20) DEFAULT 'todos' CHECK (aplica_a IN ('todos', 'categorias', 'productos')),
    fecha_vigencia_desde DATE,
    fecha_vigencia_hasta DATE,
    active BOOLEAN DEFAULT true,
    created_at TIMESTAMP DEFAULT NOW()
);

-- Categorías/productos a los que aplica el plan
CREATE TABLE plan_cuotas_aplicacion (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    plan_cuotas_id UUID NOT NULL REFERENCES planes_cuotas(id),
    tipo VARCHAR(20) NOT NULL CHECK (tipo IN ('categoria', 'producto')),
    referencia_id UUID NOT NULL,
    excluir BOOLEAN DEFAULT false
);

-- Precios específicos por plan de cuotas
CREATE TABLE producto_precios_cuotas (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    producto_id UUID NOT NULL REFERENCES productos(id),
    plan_cuotas_id UUID NOT NULL REFERENCES planes_cuotas(id),
    precio_cuota DECIMAL(15,2) NOT NULL,
    precio_total DECIMAL(15,2) NOT NULL,
    active BOOLEAN DEFAULT true,
    UNIQUE(producto_id, plan_cuotas_id)
);
```

### Casos de uso por rubro

| Rubro | Necesidad |
|-------|-----------|
| Electrodomésticos | Cuotas 3/6/12/18/24, interés variable |
| Supermercado | Precio contado, mayorista, empleados |
| Farmacia | Precio público, convenios, descuento jubilados |
| Distribuidora | Precio por volumen, escalonado |
| Servicios | Planes mensuales, anuales con descuento |

---

## 3. Sistema de Ofertas y Promociones

### Descripción
Motor de ofertas flexible que soporta múltiples tipos de promociones con condiciones combinables.

### Modelo de datos

```sql
-- Ofertas principales
CREATE TABLE ofertas (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    empresa_id UUID NOT NULL REFERENCES empresas(id),
    nombre VARCHAR(200) NOT NULL,
    descripcion TEXT,
    tipo VARCHAR(30) NOT NULL CHECK (tipo IN (
        'descuento_porcentaje', 
        'descuento_monto', 
        'precio_especial', 
        'nxm', 
        'combo',
        'envio_gratis'
    )),
    valor DECIMAL(15,2), -- Porcentaje o monto según tipo
    valor_n INTEGER, -- Para NxM: lleva N
    valor_m INTEGER, -- Para NxM: paga M
    fecha_inicio TIMESTAMP NOT NULL,
    fecha_fin TIMESTAMP NOT NULL,
    dias_semana INTEGER[], -- Array de días (0=domingo, 6=sábado)
    hora_inicio TIME,
    hora_fin TIME,
    prioridad INTEGER DEFAULT 0,
    acumulable BOOLEAN DEFAULT false,
    limite_uso_total INTEGER,
    limite_uso_cliente INTEGER,
    usos_actuales INTEGER DEFAULT 0,
    active BOOLEAN DEFAULT true,
    created_at TIMESTAMP DEFAULT NOW()
);

-- Condiciones de la oferta
CREATE TABLE oferta_condiciones (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    oferta_id UUID NOT NULL REFERENCES ofertas(id),
    tipo_condicion VARCHAR(30) NOT NULL CHECK (tipo_condicion IN (
        'cantidad_minima',
        'monto_minimo',
        'tipo_pago',
        'tarjeta_marca',
        'tarjeta_banco',
        'cliente_tipo',
        'cliente_nuevo',
        'cuotas_minimas'
    )),
    operador VARCHAR(10) DEFAULT '=' CHECK (operador IN ('=', '>=', '<=', '>', '<', 'in', 'not_in')),
    valor VARCHAR(200) NOT NULL,
    orden INTEGER DEFAULT 0
);

-- A qué productos/categorías aplica
CREATE TABLE oferta_aplicacion (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    oferta_id UUID NOT NULL REFERENCES ofertas(id),
    aplica_a VARCHAR(20) NOT NULL CHECK (aplica_a IN ('producto', 'categoria', 'marca', 'todos')),
    referencia_id UUID, -- NULL si aplica a todos
    excluir BOOLEAN DEFAULT false
);

-- Medios de pago válidos para la oferta
CREATE TABLE oferta_medios_pago (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    oferta_id UUID NOT NULL REFERENCES ofertas(id),
    tipo_pago VARCHAR(30) NOT NULL CHECK (tipo_pago IN (
        'efectivo', 
        'tarjeta_credito', 
        'tarjeta_debito', 
        'transferencia',
        'cheque',
        'credito_interno'
    )),
    banco_codigo VARCHAR(20),
    tarjeta_marca VARCHAR(30), -- visa, mastercard, etc.
    cuotas_minimas INTEGER,
    cuotas_maximas INTEGER
);

-- Productos en combo (para tipo 'combo')
CREATE TABLE oferta_combo_items (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    oferta_id UUID NOT NULL REFERENCES ofertas(id),
    producto_id UUID NOT NULL REFERENCES productos(id),
    cantidad INTEGER DEFAULT 1,
    precio_combo DECIMAL(15,2)
);

-- Historial de uso de ofertas
CREATE TABLE oferta_usos (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    oferta_id UUID NOT NULL REFERENCES ofertas(id),
    factura_id UUID NOT NULL REFERENCES facturas(id),
    cliente_id UUID REFERENCES clientes(id),
    monto_descuento DECIMAL(15,2) NOT NULL,
    created_at TIMESTAMP DEFAULT NOW()
);
```

### Tipos de ofertas soportadas

| Tipo | Ejemplo |
|------|---------|
| Porcentaje | 20% OFF en lácteos |
| Monto fijo | $5.000 de descuento en compras +$50.000 |
| NxM | 3x2 en bebidas |
| Precio especial | Heladera a $500.000 (era $600.000) |
| Combo | Shampoo + Acondicionador = $15.000 |
| Por cantidad | Llevando 6+ unidades, 15% OFF |
| Por pago | 10% con Visa, 15% efectivo |
| Por día | Martes de farmacia 25% OFF |
| Por horario | Happy Hour 18-20hs 30% OFF |

---

## 4. Sistema de Agendamiento de Citas

### Descripción
Sistema completo para gestionar citas con profesionales, incluyendo calendario, recordatorios y facturación integrada.

### Modelo de datos

```sql
-- Especialidades
CREATE TABLE especialidades (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    empresa_id UUID NOT NULL REFERENCES empresas(id),
    nombre VARCHAR(100) NOT NULL,
    descripcion TEXT,
    color VARCHAR(7), -- Hex color para UI
    duracion_default INTEGER DEFAULT 30, -- minutos
    active BOOLEAN DEFAULT true
);

-- Profesionales
CREATE TABLE profesionales (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    usuario_id UUID REFERENCES usuario(id),
    empresa_id UUID NOT NULL REFERENCES empresas(id),
    especialidad_id UUID REFERENCES especialidades(id),
    nombre VARCHAR(100) NOT NULL,
    apellido VARCHAR(100) NOT NULL,
    registro_profesional VARCHAR(50), -- Matrícula, etc.
    email VARCHAR(200),
    telefono VARCHAR(50),
    foto_url TEXT,
    biografia TEXT,
    duracion_cita_default INTEGER DEFAULT 30,
    precio_consulta DECIMAL(15,2),
    active BOOLEAN DEFAULT true,
    created_at TIMESTAMP DEFAULT NOW()
);

-- Horarios de atención por profesional
CREATE TABLE horarios_profesional (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    profesional_id UUID NOT NULL REFERENCES profesionales(id),
    dia_semana INTEGER NOT NULL CHECK (dia_semana BETWEEN 0 AND 6),
    hora_inicio TIME NOT NULL,
    hora_fin TIME NOT NULL,
    intervalo_minutos INTEGER DEFAULT 30,
    cupos_simultaneos INTEGER DEFAULT 1, -- Para clases grupales
    active BOOLEAN DEFAULT true,
    UNIQUE(profesional_id, dia_semana)
);

-- Bloqueos de horario (vacaciones, etc.)
CREATE TABLE bloqueos_horario (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    profesional_id UUID NOT NULL REFERENCES profesionales(id),
    fecha_inicio TIMESTAMP NOT NULL,
    fecha_fin TIMESTAMP NOT NULL,
    motivo VARCHAR(100),
    todo_el_dia BOOLEAN DEFAULT false,
    created_at TIMESTAMP DEFAULT NOW()
);

-- Servicios que ofrece cada profesional
CREATE TABLE servicios_profesional (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    profesional_id UUID NOT NULL REFERENCES profesionales(id),
    nombre VARCHAR(200) NOT NULL,
    descripcion TEXT,
    duracion_minutos INTEGER NOT NULL,
    precio DECIMAL(15,2) NOT NULL,
    requiere_preparacion BOOLEAN DEFAULT false,
    instrucciones_previas TEXT,
    active BOOLEAN DEFAULT true
);

-- Citas
CREATE TABLE citas (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    empresa_id UUID NOT NULL REFERENCES empresas(id),
    profesional_id UUID NOT NULL REFERENCES profesionales(id),
    cliente_id UUID REFERENCES clientes(id),
    servicio_id UUID REFERENCES servicios_profesional(id),
    fecha DATE NOT NULL,
    hora_inicio TIME NOT NULL,
    hora_fin TIME NOT NULL,
    estado VARCHAR(20) DEFAULT 'pendiente' CHECK (estado IN (
        'pendiente', 
        'confirmada', 
        'en_curso', 
        'completada', 
        'cancelada', 
        'no_asistio'
    )),
    notas_cliente TEXT,
    notas_internas TEXT,
    precio DECIMAL(15,2),
    factura_id UUID REFERENCES facturas(id),
    recordatorio_enviado BOOLEAN DEFAULT false,
    confirmacion_cliente BOOLEAN DEFAULT false,
    canal_reserva VARCHAR(20) DEFAULT 'presencial' CHECK (canal_reserva IN (
        'web', 'app', 'telefono', 'presencial', 'whatsapp'
    )),
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);

-- Recordatorios programados
CREATE TABLE recordatorios_cita (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    cita_id UUID NOT NULL REFERENCES citas(id),
    tipo VARCHAR(20) NOT NULL CHECK (tipo IN ('email', 'sms', 'whatsapp', 'push')),
    horas_antes INTEGER NOT NULL, -- 24, 2, etc.
    programado_para TIMESTAMP NOT NULL,
    enviado BOOLEAN DEFAULT false,
    fecha_envio TIMESTAMP,
    respuesta_cliente TEXT
);

-- Lista de espera
CREATE TABLE lista_espera (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    empresa_id UUID NOT NULL REFERENCES empresas(id),
    profesional_id UUID REFERENCES profesionales(id),
    cliente_id UUID NOT NULL REFERENCES clientes(id),
    servicio_id UUID REFERENCES servicios_profesional(id),
    fecha_preferida DATE,
    hora_preferida_desde TIME,
    hora_preferida_hasta TIME,
    notas TEXT,
    estado VARCHAR(20) DEFAULT 'activa' CHECK (estado IN ('activa', 'contactada', 'agendada', 'cancelada')),
    created_at TIMESTAMP DEFAULT NOW()
);
```

### Funcionalidades

| Funcionalidad | Descripción |
|---------------|-------------|
| Calendario visual | Vista día/semana/mes por profesional |
| Reserva online | Portal para clientes (opcional) |
| Recordatorios automáticos | Email/SMS/WhatsApp 24h y 2h antes |
| Confirmación | Cliente confirma asistencia |
| Lista de espera | Si no hay cupos disponibles |
| Historial de citas | Por cliente y por profesional |
| Facturación integrada | Generar factura al completar cita |
| Reportes | Ocupación, no-shows, ingresos por profesional |

### Casos de uso por rubro

| Rubro | Particularidades |
|-------|------------------|
| Clínica médica | Múltiples especialidades, derivaciones |
| Consultorio dental | Tratamientos multi-sesión |
| Salón de belleza | Servicios combinables, duración variable |
| Gimnasio/Yoga | Clases grupales con cupos |
| Abogados/Contadores | Citas por caso/expediente |
| Veterinaria | Paciente = mascota, dueño = cliente |
| Taller mecánico | Cita + vehículo + servicios |

---

## Priorización de implementación

| Fase | Módulo | Prioridad | Complejidad | Estimación |
|------|--------|-----------|-------------|------------|
| 1 | Lista de precios + Cuotas | Alta | Media | 2-3 semanas |
| 1 | Ofertas básicas | Alta | Media | 2 semanas |
| 2 | Vendedores/Cobradores | Media | Alta | 3-4 semanas |
| 2 | Agendamiento de citas | Media | Alta | 4-5 semanas |
| 3 | Ofertas avanzadas | Baja | Alta | 2-3 semanas |
| 3 | Rutas de cobranza | Baja | Alta | 2-3 semanas |
| 3 | Comisiones y liquidación | Baja | Media | 2 semanas |

---

## Notas de implementación

### Consideraciones generales
1. Todos los módulos deben respetar el multi-tenancy por `empresa_id`
2. Integración con el sistema de facturación existente
3. Permisos y roles específicos por módulo
4. API RESTful con documentación Swagger
5. Tests unitarios y de integración

### Integraciones requeridas
- Sistema de notificaciones (email, SMS, WhatsApp)
- Calendario (Google Calendar, Outlook)
- Pasarelas de pago para cuotas
- Reportería y dashboards

---

*Documento creado: Enero 2026*
*Última actualización: Enero 2026*