2825b3d5fd
- ET-SAAS-018-sales.md: Sales pipeline/CRM module - ET-SAAS-019-portfolio.md: Product catalog module - ET-SAAS-020-commissions.md: Commissions system - ET-SAAS-021-mlm.md: Multi-Level Marketing module - ET-SAAS-022-goals.md: Goals and objectives system - Update _MAP.md with all 9 specifications All specs document: - Data model (DDL, enums, tables) - Backend architecture (endpoints, services) - Security (RLS, RBAC permissions) - Frontend status and hooks - Module integrations Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
290 lines
8.4 KiB
Markdown
290 lines
8.4 KiB
Markdown
---
|
|
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/`
|