rckrdmrd/template-saas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
2825b3d5fd
template-saas/docs/02-especificaciones/ET-SAAS-018-sales.md
Adrian Flores Cortes 2825b3d5fd
Some checks are pending
CI / Backend CI (push) Waiting to run
Details
CI / Frontend CI (push) Waiting to run
Details
CI / Security Scan (push) Waiting to run
Details
CI / CI Summary (push) Blocked by required conditions
Details
docs: Add ET-SAAS-018 to ET-SAAS-022 technical specifications 
- 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>
2026-02-03 13:14:48 -06:00

8.4 KiB
Raw Blame History

id title type status priority module version created_date updated_date story_points
ET-SAAS-018 Especificacion Tecnica Sales Pipeline TechnicalSpec Implemented P1 sales 1.0.0 2026-02-03 2026-02-03 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

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.

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

// 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

// 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/