template-saas/docs/01-modulos/SAAS-018-sales.md

id	title	type	status	priority	module	version	created_date	updated_date	estimated_sp
SAAS-018	Sales Foundation	Module	Specified	P2	sales	1.0.0	2026-01-24	2026-01-24	21

SAAS-018: Sales Foundation

Metadata

• Codigo: SAAS-018
• Modulo: Sales
• Prioridad: P2
• Estado: Especificado
• Fase: 6 - Advanced Features
• Story Points: 21

Descripcion

Modulo base de ventas para plataformas SaaS. Proporciona gestion de leads, oportunidades, pipeline de ventas, y seguimiento de actividades comerciales. Diseñado para ser extendido por verticales ERP.

Objetivos

1. Gestionar leads y contactos comerciales
2. Pipeline de oportunidades con etapas configurables
3. Seguimiento de actividades (llamadas, emails, reuniones)
4. Reportes de ventas y conversion
5. Integracion con billing para cerrar ventas

Alcance

Incluido

• CRUD de leads con scoring automatico
• Pipeline de oportunidades (kanban)
• Etapas configurables por tenant
• Actividades y seguimiento
• Conversion lead -> cliente
• Dashboard de ventas
• Reportes basicos (conversion, tiempo ciclo)
• Integracion con notifications

Excluido

• CRM completo (erp-core)
• Cotizaciones/Propuestas (erp-core)
• Productos y catalogo (portfolio module)
• Facturacion (billing module existente)

Modelo de Datos

Schema: sales

-- Leads
CREATE TABLE sales.leads (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    tenant_id UUID NOT NULL REFERENCES tenants.tenants(id),

    -- Contacto
    first_name VARCHAR(100) NOT NULL,
    last_name VARCHAR(100),
    email VARCHAR(255) NOT NULL,
    phone VARCHAR(50),
    company VARCHAR(200),
    job_title VARCHAR(100),

    -- Origen y scoring
    source sales.lead_source NOT NULL DEFAULT 'manual',
    score INTEGER DEFAULT 0,
    status sales.lead_status NOT NULL DEFAULT 'new',

    -- Asignacion
    assigned_to UUID REFERENCES users.users(id),

    -- Metadata
    tags JSONB DEFAULT '[]',
    custom_fields JSONB DEFAULT '{}',
    notes TEXT,

    -- Conversion
    converted_at TIMESTAMPTZ,
    converted_to_opportunity_id UUID,

    -- Audit
    created_at TIMESTAMPTZ DEFAULT NOW(),
    updated_at TIMESTAMPTZ DEFAULT NOW(),
    created_by UUID REFERENCES users.users(id)
);

-- Oportunidades
CREATE TABLE sales.opportunities (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    tenant_id UUID NOT NULL REFERENCES tenants.tenants(id),

    -- Info basica
    name VARCHAR(200) NOT NULL,
    description TEXT,

    -- Pipeline
    stage_id UUID NOT NULL REFERENCES sales.pipeline_stages(id),
    probability INTEGER DEFAULT 0 CHECK (probability >= 0 AND probability <= 100),

    -- Valores
    amount DECIMAL(15,2) DEFAULT 0,
    currency VARCHAR(3) DEFAULT 'USD',
    expected_close_date DATE,

    -- Relaciones
    lead_id UUID REFERENCES sales.leads(id),
    contact_email VARCHAR(255),
    company VARCHAR(200),

    -- Asignacion
    assigned_to UUID REFERENCES users.users(id),

    -- Estado
    status sales.opportunity_status NOT NULL DEFAULT 'open',
    won_at TIMESTAMPTZ,
    lost_at TIMESTAMPTZ,
    lost_reason VARCHAR(500),

    -- Metadata
    tags JSONB DEFAULT '[]',
    custom_fields JSONB DEFAULT '{}',

    -- Audit
    created_at TIMESTAMPTZ DEFAULT NOW(),
    updated_at TIMESTAMPTZ DEFAULT NOW()
);

-- Etapas del pipeline
CREATE TABLE sales.pipeline_stages (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    tenant_id UUID NOT NULL REFERENCES tenants.tenants(id),

    name VARCHAR(100) NOT NULL,
    description TEXT,
    position INTEGER NOT NULL DEFAULT 0,
    probability INTEGER DEFAULT 0,
    color VARCHAR(7) DEFAULT '#3B82F6',

    is_won BOOLEAN DEFAULT false,
    is_lost BOOLEAN DEFAULT false,
    is_active BOOLEAN DEFAULT true,

    created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Actividades
CREATE TABLE sales.activities (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    tenant_id UUID NOT NULL REFERENCES tenants.tenants(id),

    -- Tipo y descripcion
    type sales.activity_type NOT NULL,
    subject VARCHAR(200) NOT NULL,
    description TEXT,

    -- Relacion polimorfica
    related_type VARCHAR(50) NOT NULL, -- 'lead' | 'opportunity'
    related_id UUID NOT NULL,

    -- Programacion
    due_date TIMESTAMPTZ,
    completed_at TIMESTAMPTZ,

    -- Asignacion
    assigned_to UUID REFERENCES users.users(id),

    -- Metadata
    outcome TEXT,
    duration_minutes INTEGER,

    created_at TIMESTAMPTZ DEFAULT NOW(),
    created_by UUID REFERENCES users.users(id)
);

-- Enums
CREATE TYPE sales.lead_source AS ENUM (
    'manual', 'website', 'referral', 'campaign',
    'social', 'trade_show', 'cold_call', 'other'
);

CREATE TYPE sales.lead_status AS ENUM (
    'new', 'contacted', 'qualified', 'unqualified', 'converted'
);

CREATE TYPE sales.opportunity_status AS ENUM (
    'open', 'won', 'lost'
);

CREATE TYPE sales.activity_type AS ENUM (
    'call', 'email', 'meeting', 'task', 'note', 'demo'
);

RLS Policies

ALTER TABLE sales.leads ENABLE ROW LEVEL SECURITY;
ALTER TABLE sales.opportunities ENABLE ROW LEVEL SECURITY;
ALTER TABLE sales.pipeline_stages ENABLE ROW LEVEL SECURITY;
ALTER TABLE sales.activities ENABLE ROW LEVEL SECURITY;

CREATE POLICY tenant_isolation ON sales.leads
    USING (tenant_id = current_setting('app.current_tenant_id')::UUID);
-- (Similar for other tables)

Endpoints API

Leads

Metodo	Endpoint	Descripcion
GET	/sales/leads	Listar leads con filtros
POST	/sales/leads	Crear lead
GET	/sales/leads/:id	Obtener lead
PATCH	/sales/leads/:id	Actualizar lead
DELETE	/sales/leads/:id	Eliminar lead
POST	/sales/leads/:id/convert	Convertir a oportunidad
POST	/sales/leads/import	Importar leads (CSV)

Opportunities

Metodo	Endpoint	Descripcion
GET	/sales/opportunities	Listar oportunidades
POST	/sales/opportunities	Crear oportunidad
GET	/sales/opportunities/:id	Obtener oportunidad
PATCH	/sales/opportunities/:id	Actualizar oportunidad
DELETE	/sales/opportunities/:id	Eliminar oportunidad
PATCH	/sales/opportunities/:id/stage	Mover de etapa
POST	/sales/opportunities/:id/won	Marcar como ganada
POST	/sales/opportunities/:id/lost	Marcar como perdida

Pipeline

Metodo	Endpoint	Descripcion
GET	/sales/pipeline/stages	Listar etapas
POST	/sales/pipeline/stages	Crear etapa
PATCH	/sales/pipeline/stages/:id	Actualizar etapa
DELETE	/sales/pipeline/stages/:id	Eliminar etapa
POST	/sales/pipeline/stages/reorder	Reordenar etapas

Activities

Metodo	Endpoint	Descripcion
GET	/sales/activities	Listar actividades
POST	/sales/activities	Crear actividad
PATCH	/sales/activities/:id	Actualizar actividad
DELETE	/sales/activities/:id	Eliminar actividad
POST	/sales/activities/:id/complete	Marcar completada

Reports

Metodo	Endpoint	Descripcion
GET	/sales/reports/pipeline	Reporte pipeline
GET	/sales/reports/conversion	Tasa de conversion
GET	/sales/reports/forecast	Forecast de ventas

Frontend

Paginas

• /sales - Dashboard de ventas
• /sales/leads - Lista de leads
• /sales/leads/:id - Detalle de lead
• /sales/opportunities - Pipeline kanban
• /sales/opportunities/:id - Detalle de oportunidad
• /sales/activities - Calendario/lista de actividades
• /sales/reports - Reportes

Componentes

• LeadsList - Tabla de leads con filtros
• LeadForm - Formulario crear/editar lead
• LeadDetail - Vista detalle con timeline
• OpportunityKanban - Pipeline drag & drop
• OpportunityCard - Tarjeta en kanban
• OpportunityDetail - Vista detalle con actividades
• ActivityTimeline - Timeline de actividades
• ActivityForm - Formulario de actividad
• SalesDashboard - Metricas y graficos
• ConversionFunnel - Visualizacion embudo

Hooks

• useLeads - CRUD leads
• useOpportunities - CRUD oportunidades
• usePipeline - Gestion pipeline
• useActivities - CRUD actividades
• useSalesReports - Reportes

Dependencias

Modulos Requeridos

• SAAS-001 Auth (autenticacion)
• SAAS-002 Tenants (multi-tenancy)
• SAAS-003 Users (usuarios y asignacion)
• SAAS-007 Notifications (alertas de actividades)

Modulos Opcionales

• SAAS-019 Portfolio (productos en oportunidades)
• SAAS-020 Commissions (comisiones por venta)

Criterios de Aceptacion

1. CRUD completo de leads con validaciones
2. Pipeline kanban con drag & drop
3. Conversion lead -> oportunidad funcional
4. Sistema de actividades con recordatorios
5. Dashboard con metricas clave
6. Reportes de conversion y forecast
7. Tests unitarios (>70% coverage)
8. Documentacion API (Swagger)

Estimacion

Componente	SP
DDL + Entities	3
Backend Services	5
Controllers + DTOs	3
Frontend Pages	5
Frontend Components	3
Tests	2
Total	21

---

Ultima actualizacion: 2026-01-24 Autor: Claude Opus 4.5