template-saas/docs/02-especificaciones/ET-SAAS-022-goals.md

id	title	type	status	priority	module	version	created_date	updated_date	story_points
ET-SAAS-022	Especificacion Tecnica Goals	TechnicalSpec	Implemented	P1	goals	1.0.0	2026-02-03	2026-02-03	8

ET-SAAS-022: Especificacion Tecnica - Sistema de Metas (Goals)

Metadata

• Codigo: ET-SAAS-022
• Modulo: Goals
• Version: 1.0.0
• Estado: Implementado (Backend)
• Fecha: 2026-02-03
• Basado en: SAAS-022

---

1. Resumen Ejecutivo

1.1 Estado Actual

Sistema de metas con backend implementado, UI pendiente.

Capacidad	Estado	Notas
Definitions	SI	Definiciones de metas
Assignments	SI	Asignaciones usuario/team
Progress	SI	Tracking de progreso
Milestones	SI	Hitos con notificaciones
Auto-tracking	SI	Fuentes automaticas
RLS	SI	Row Level Security
UI	NO	Frontend pendiente

1.2 Funcionalidades v1.0

Sistema completo con:

• 4 Entidades: Definitions, Assignments, ProgressLog, MilestoneNotifications
• 3 Tipos de meta: target, limit, maintain
• 5 Tipos de metrica: number, currency, percentage, boolean, count
• 6 Periodos: daily, weekly, monthly, quarterly, yearly, custom
• Auto-tracking: Integracion con sales, billing, commissions

---

2. Modelo de Datos

2.1 Schema: goals

Tabla: definitions

Campo	Tipo	Descripcion
id	UUID	PK
tenant_id	UUID	FK tenants
name	VARCHAR(200)	Nombre de la meta
description	TEXT	Descripcion
category	VARCHAR(100)	Categoria
type	ENUM	target, limit, maintain
metric	ENUM	number, currency, percentage, boolean, count
target_value	DECIMAL(15,2)	Valor objetivo
unit	VARCHAR(50)	USD, units, %, etc.
period	ENUM	daily, weekly, monthly, quarterly, yearly, custom
starts_at	DATE	Fecha inicio
ends_at	DATE	Fecha fin
source	ENUM	manual, sales, billing, commissions, custom
source_config	JSONB	Configuracion de fuente
milestones	JSONB	Hitos de progreso
status	ENUM	draft, active, paused, completed, cancelled
tags	JSONB	Array de tags

Source Config ejemplo:

{
  "module": "sales",
  "entity": "opportunities",
  "filter": {"stage": "closed_won"},
  "aggregation": "sum",
  "field": "amount"
}

Milestones ejemplo:

[
  {"percentage": 25, "notify": true},
  {"percentage": 50, "notify": true},
  {"percentage": 75, "notify": true},
  {"percentage": 100, "notify": true}
]

Tabla: assignments

Campo	Tipo	Descripcion
id	UUID	PK
tenant_id	UUID	FK tenants
definition_id	UUID	FK definitions
assignee_type	ENUM	user, team, tenant
user_id	UUID	FK users (si type=user)
team_id	UUID	Para futuro modulo de equipos
custom_target	DECIMAL(15,2)	Override del target
current_value	DECIMAL(15,2)	Valor actual
progress_percentage	DECIMAL(5,2)	0-100%
last_updated_at	TIMESTAMPTZ	Ultima actualizacion
status	ENUM	active, achieved, failed, cancelled
achieved_at	TIMESTAMPTZ	Fecha de logro
notes	TEXT	Notas

Tabla: progress_log

Campo	Tipo	Descripcion
id	UUID	PK
tenant_id	UUID	FK tenants
assignment_id	UUID	FK assignments
previous_value	DECIMAL(15,2)	Valor anterior
new_value	DECIMAL(15,2)	Nuevo valor
change_amount	DECIMAL(15,2)	Diferencia
source	ENUM	manual, automatic, import, api
source_reference	VARCHAR(200)	ID de transaccion origen
notes	TEXT	Notas
logged_at	TIMESTAMPTZ	Fecha del log
logged_by	UUID	FK users

Tabla: milestone_notifications

Campo	Tipo	Descripcion
id	UUID	PK
tenant_id	UUID	FK tenants
assignment_id	UUID	FK assignments
milestone_percentage	INT	% del hito alcanzado
achieved_value	DECIMAL(15,2)	Valor al alcanzar
notified_at	TIMESTAMPTZ	Fecha de notificacion

2.2 Enums

goals.goal_type: target, limit, maintain
goals.metric_type: number, currency, percentage, boolean, count
goals.period_type: daily, weekly, monthly, quarterly, yearly, custom
goals.data_source: manual, sales, billing, commissions, custom
goals.goal_status: draft, active, paused, completed, cancelled
goals.assignee_type: user, team, tenant
goals.assignment_status: active, achieved, failed, cancelled
goals.progress_source: manual, automatic, import, api

---

3. Tipos de Meta

3.1 Target (Alcanzar objetivo)

• Descripcion: Alcanzar un valor especifico
• Ejemplo: "Vender $50,000 este mes"
• Logro: current_value >= target_value

3.2 Limit (No exceder)

• Descripcion: No superar un limite
• Ejemplo: "Mantener gastos bajo $10,000"
• Logro: current_value <= target_value durante todo el periodo

3.3 Maintain (Mantener valor)

• Descripcion: Mantener un valor constante
• Ejemplo: "Mantener NPS >= 8.5"
• Logro: current_value dentro de rango durante todo el periodo

---

4. Arquitectura Backend

4.1 Estructura de Archivos

backend/src/modules/goals/
├── goals.module.ts
├── controllers/
│   ├── definitions.controller.ts
│   ├── assignments.controller.ts
│   ├── progress.controller.ts
│   └── dashboard.controller.ts
├── services/
│   ├── definitions.service.ts
│   ├── assignments.service.ts
│   ├── progress.service.ts
│   ├── tracking.service.ts
│   └── dashboard.service.ts
├── entities/
│   ├── definition.entity.ts
│   ├── assignment.entity.ts
│   ├── progress-log.entity.ts
│   └── milestone-notification.entity.ts
└── dto/

4.2 Endpoints API

Definitions

Metodo	Endpoint	Descripcion
GET	/goals/definitions	Listar
GET	/goals/definitions/:id	Obtener
POST	/goals/definitions	Crear
PUT	/goals/definitions/:id	Actualizar
PATCH	/goals/definitions/:id/status	Cambiar status
DELETE	/goals/definitions/:id	Eliminar
POST	/goals/definitions/:id/duplicate	Duplicar

Assignments

Metodo	Endpoint	Descripcion
GET	/goals/assignments	Listar
GET	/goals/assignments/:id	Obtener
GET	/goals/assignments/user/:userId	Por usuario
GET	/goals/assignments/definition/:defId	Por definicion
POST	/goals/assignments	Crear
PUT	/goals/assignments/:id	Actualizar
DELETE	/goals/assignments/:id	Eliminar

Progress

Metodo	Endpoint	Descripcion
GET	/goals/progress/:assignmentId	Historial
POST	/goals/progress	Registrar progreso
POST	/goals/progress/bulk	Registrar multiples

Dashboard

Metodo	Endpoint	Descripcion
GET	/goals/dashboard	Resumen general
GET	/goals/dashboard/my	Mis metas
GET	/goals/dashboard/team/:teamId	Metas del equipo
GET	/goals/dashboard/user/:userId	Metas de usuario
GET	/goals/dashboard/achieved	Metas logradas
GET	/goals/dashboard/at-risk	Metas en riesgo

---

5. Auto-Tracking

5.1 Configuracion de Fuentes

interface SourceConfig {
  module: 'sales' | 'billing' | 'commissions';
  entity: string;           // 'opportunities', 'invoices', etc.
  filter?: Record<string, any>;  // Filtros adicionales
  aggregation: 'sum' | 'count' | 'avg' | 'min' | 'max';
  field?: string;           // Campo para sum/avg
}

5.2 Ejemplo: Meta de Ventas

{
  "name": "Ventas Q1 2026",
  "type": "target",
  "metric": "currency",
  "target_value": 100000,
  "unit": "USD",
  "source": "sales",
  "source_config": {
    "module": "sales",
    "entity": "opportunities",
    "filter": {"stage": "closed_won"},
    "aggregation": "sum",
    "field": "amount"
  }
}

5.3 Flujo de Actualizacion

// Listener para eventos de ventas
@OnEvent('opportunity.won')
async handleOpportunityWon(event: OpportunityWonEvent) {
  // 1. Buscar metas con source_config que matchee
  const goals = await this.findMatchingGoals({
    module: 'sales',
    entity: 'opportunities',
    userId: event.opportunity.assignedTo
  });

  // 2. Para cada meta, actualizar progreso
  for (const assignment of goals) {
    await this.updateProgress(assignment.id, {
      changeAmount: event.opportunity.amount,
      source: 'automatic',
      sourceReference: event.opportunity.id
    });
  }
}

---

6. Frontend (Pendiente)

6.1 Paginas Propuestas

Ruta	Componente	Estado
/dashboard/goals	GoalsDashboard	Pendiente
/dashboard/goals/my	MyGoalsPage	Pendiente
/dashboard/goals/definitions	DefinitionsPage	Pendiente
/dashboard/goals/new	GoalFormPage	Pendiente
/dashboard/goals/:id	GoalDetailPage	Pendiente

6.2 Hooks Existentes

// frontend/src/hooks/useGoals.ts
useDefinitions, useDefinition, useCreateDefinition, useUpdateDefinition
useAssignments, useMyAssignments, useUserAssignments
useAssignmentProgress, useUpdateProgress
useGoalsDashboard, useAchievedGoals, useAtRiskGoals

---

7. Seguridad

7.1 RLS

CREATE POLICY definitions_tenant_isolation ON goals.definitions
    USING (tenant_id = current_setting('app.tenant_id')::uuid);

CREATE POLICY assignments_tenant_isolation ON goals.assignments
    USING (tenant_id = current_setting('app.tenant_id')::uuid);

7.2 Permisos RBAC

Permiso	Descripcion
goals:read	Ver metas
goals:write	Crear/editar metas
goals:assign	Asignar metas
goals:progress	Actualizar progreso
goals:manage	Administrar

---

8. Notificaciones

8.1 Eventos de Notificacion

Evento	Trigger	Destinatario
goal.milestone_reached	Alcanzar %	Usuario asignado
goal.achieved	100% completado	Usuario + Manager
goal.at_risk	<50% y queda poco tiempo	Manager
goal.failed	Periodo terminado sin lograr	Manager

8.2 Ejemplo de Notificacion

interface MilestoneNotification {
  type: 'goal.milestone_reached';
  userId: string;
  data: {
    goalName: string;
    milestone: 50;  // percentage
    currentValue: 25000;
    targetValue: 50000;
    remainingDays: 15;
  };
}

---

9. Integraciones

Modulo	Integracion
sales	Tracking automatico
billing	Tracking de ingresos
commissions	Metas de comision
notifications	Alertas de hitos
audit	Log de cambios

---

10. Referencias

• DDL: database/ddl/schemas/goals/
• Backend: backend/src/modules/goals/
• Frontend Services: frontend/src/services/goals/
• Frontend Hooks: frontend/src/hooks/useGoals.ts