---
id: "ET-SAAS-018"
title: "Especificacion Tecnica Sales Pipeline"
type: "TechnicalSpec"
status: "Implemented"
priority: "P1"
module: "sales"
version: "1.0.0"
created_date: "2026-02-03"
updated_date: "2026-02-03"
story_points: 8
---

# ET-SAAS-018: Especificacion Tecnica - Sistema de Ventas (Sales Pipeline)

## Metadata
- **Codigo:** ET-SAAS-018
- **Modulo:** Sales
- **Version:** 1.0.0
- **Estado:** Implementado
- **Fecha:** 2026-02-03
- **Basado en:** SAAS-018

---

## 1. Resumen Ejecutivo

### 1.1 Estado Actual

Sistema de ventas completamente implementado con CRM basico.

| Capacidad | Estado | Notas |
|-----------|--------|-------|
| Pipeline Stages | SI | Etapas configurables por tenant |
| Leads Management | SI | Prospectos con scoring |
| Opportunities | SI | Oportunidades con probabilidad |
| Activities | SI | Llamadas, reuniones, tareas |
| RLS | SI | Row Level Security por tenant |

### 1.2 Funcionalidades v1.0

Sistema CRM con:

- **4 Entidades**: Pipeline Stages, Leads, Opportunities, Activities
- **Pipeline configurable**: Etapas personalizables por tenant
- **Lead Scoring**: Puntuacion 0-100 automatica
- **Activity Tracking**: Llamadas, reuniones, tareas, emails, notas
- **Conversion Flow**: Lead → Opportunity → Won/Lost

---

## 2. Modelo de Datos

### 2.1 Schema: sales

#### Tabla: pipeline_stages
| Campo | Tipo | Descripcion |
|-------|------|-------------|
| id | UUID | PK |
| tenant_id | UUID | FK tenants |
| name | VARCHAR(100) | Nombre de la etapa |
| position | INT | Orden en el pipeline |
| color | VARCHAR(7) | Color hex |
| is_won | BOOLEAN | Etapa de cierre ganado |
| is_lost | BOOLEAN | Etapa de cierre perdido |
| is_active | BOOLEAN | Estado activo |

#### Tabla: leads
| Campo | Tipo | Descripcion |
|-------|------|-------------|
| id | UUID | PK |
| tenant_id | UUID | FK tenants |
| first_name, last_name | VARCHAR(100) | Nombre completo |
| email, phone | VARCHAR | Contacto |
| company, job_title | VARCHAR | Empresa |
| source | ENUM | website, referral, cold_call, event, advertisement, social_media, other |
| status | ENUM | new, contacted, qualified, unqualified, converted |
| score | INT | 0-100 lead scoring |
| assigned_to | UUID | FK users |
| converted_at | TIMESTAMPTZ | Fecha conversion |
| custom_fields | JSONB | Campos personalizados |

#### Tabla: opportunities
| Campo | Tipo | Descripcion |
|-------|------|-------------|
| id | UUID | PK |
| tenant_id | UUID | FK tenants |
| name | VARCHAR(255) | Nombre de la oportunidad |
| lead_id | UUID | FK leads (opcional) |
| stage | ENUM | prospecting, qualification, proposal, negotiation, closed_won, closed_lost |
| stage_id | UUID | FK pipeline_stages |
| amount | DECIMAL(15,2) | Valor monetario |
| currency | VARCHAR(3) | Moneda (default USD) |
| probability | INT | 0-100 probabilidad de cierre |
| expected_close_date | DATE | Fecha esperada de cierre |
| assigned_to | UUID | FK users |
| won_at, lost_at | TIMESTAMPTZ | Fechas de cierre |
| lost_reason | VARCHAR(500) | Razon de perdida |

#### Tabla: activities
| Campo | Tipo | Descripcion |
|-------|------|-------------|
| id | UUID | PK |
| tenant_id | UUID | FK tenants |
| type | ENUM | call, meeting, task, email, note |
| status | ENUM | pending, completed, cancelled |
| subject | VARCHAR(255) | Titulo |
| lead_id / opportunity_id | UUID | Referencia |
| due_date | TIMESTAMPTZ | Fecha limite |
| completed_at | TIMESTAMPTZ | Fecha completado |
| assigned_to | UUID | FK users |
| reminder_at | TIMESTAMPTZ | Recordatorio |

### 2.2 Enums

```sql
sales.lead_status: new, contacted, qualified, unqualified, converted
sales.lead_source: website, referral, cold_call, event, advertisement, social_media, other
sales.opportunity_stage: prospecting, qualification, proposal, negotiation, closed_won, closed_lost
sales.activity_type: call, meeting, task, email, note
sales.activity_status: pending, completed, cancelled
```

---

## 3. Arquitectura Backend

### 3.1 Estructura de Archivos

```
backend/src/modules/sales/
├── sales.module.ts
├── controllers/
│   ├── leads.controller.ts
│   ├── opportunities.controller.ts
│   ├── activities.controller.ts
│   └── pipeline-stages.controller.ts
├── services/
│   ├── leads.service.ts
│   ├── opportunities.service.ts
│   ├── activities.service.ts
│   └── pipeline-stages.service.ts
├── entities/
│   ├── lead.entity.ts
│   ├── opportunity.entity.ts
│   ├── activity.entity.ts
│   └── pipeline-stage.entity.ts
├── dto/
│   ├── create-lead.dto.ts
│   ├── update-lead.dto.ts
│   ├── create-opportunity.dto.ts
│   └── ...
└── __tests__/
```

### 3.2 Endpoints API

#### Leads
| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| GET | /sales/leads | Listar leads |
| GET | /sales/leads/:id | Obtener lead |
| POST | /sales/leads | Crear lead |
| PATCH | /sales/leads/:id | Actualizar lead |
| DELETE | /sales/leads/:id | Eliminar lead |
| POST | /sales/leads/:id/convert | Convertir a oportunidad |

#### Opportunities
| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| GET | /sales/opportunities | Listar oportunidades |
| GET | /sales/opportunities/:id | Obtener oportunidad |
| POST | /sales/opportunities | Crear oportunidad |
| PATCH | /sales/opportunities/:id | Actualizar |
| PATCH | /sales/opportunities/:id/stage | Cambiar etapa |
| POST | /sales/opportunities/:id/won | Marcar como ganada |
| POST | /sales/opportunities/:id/lost | Marcar como perdida |
| DELETE | /sales/opportunities/:id | Eliminar |

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

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

---

## 4. Seguridad

### 4.1 Row Level Security (RLS)

Todas las tablas tienen RLS habilitado con politicas por tenant_id.

```sql
-- Ejemplo para leads
CREATE POLICY leads_tenant_isolation ON sales.leads
    USING (tenant_id = current_setting('app.tenant_id')::uuid);
```

### 4.2 Permisos RBAC

| Permiso | Descripcion |
|---------|-------------|
| sales:read | Ver leads, oportunidades, actividades |
| sales:write | Crear/editar |
| sales:delete | Eliminar |
| sales:assign | Asignar a usuarios |
| sales:manage | Configurar pipeline |

---

## 5. Integraciones

### 5.1 Modulos Relacionados

| Modulo | Integracion |
|--------|-------------|
| users | Asignacion de leads/opportunities |
| notifications | Alertas de actividades |
| audit | Log de cambios |
| commissions | Calculo de comisiones en won |
| goals | Tracking de metas de ventas |

### 5.2 Eventos Emitidos

```typescript
// Eventos del modulo sales
LeadCreated, LeadUpdated, LeadConverted
OpportunityCreated, OpportunityStageChanged, OpportunityWon, OpportunityLost
ActivityCreated, ActivityCompleted
```

---

## 6. Frontend

### 6.1 Paginas

| Ruta | Componente | Estado |
|------|------------|--------|
| /dashboard/sales | SalesDashboard | Pendiente |
| /dashboard/sales/leads | LeadsPage | Pendiente |
| /dashboard/sales/opportunities | OpportunitiesPage | Pendiente |
| /dashboard/sales/pipeline | PipelinePage | Pendiente |
| /dashboard/sales/activities | ActivitiesPage | Pendiente |

### 6.2 Hooks

```typescript
// frontend/src/hooks/useSales.ts
useLeads, useLead, useCreateLead, useUpdateLead, useDeleteLead, useConvertLead
useOpportunities, useOpportunity, useCreateOpportunity, useUpdateOpportunityStage
useActivities, useCreateActivity, useCompleteActivity
usePipelineStages
```

---

## 7. Metricas y Dashboard

### 7.1 KPIs Propuestos

- Total Leads por periodo
- Conversion Rate (Lead → Opportunity)
- Win Rate (Opportunity → Won)
- Pipeline Value (suma de amounts)
- Average Deal Size
- Sales Velocity (tiempo promedio de cierre)

---

## 8. Referencias

- DDL: `database/ddl/schemas/sales/`
- Backend: `backend/src/modules/sales/`
- Frontend: `frontend/src/services/sales/`