Proyectos

Proyectos

El módulo de Proyectos de Factux permite organizar y gestionar proyectos de forma integral, con control de presupuesto, asignación de recursos, hitos y facturación automática.

Acceso

Ruta: /owner/projects Componente principal: Projects.tsx Icono: FolderOpen

Descripción General

Este módulo ofrece una gestión completa de proyectos empresariales con:

• 3 vistas diferentes: Grid de tarjetas, Lista detallada y Vista Kanban
• Estados del proyecto: Planificación, Activo, En Espera, Completado, Cancelado, Archivado
• Gestión de hitos con facturación automática
• Control presupuestario en tiempo real
• Calendario integrado con tareas y eventos
• Sistema de recursos y asignación de equipo
• Tracking de tiempo y progreso automático

Estados del Proyecto

El sistema utiliza 6 estados para el ciclo de vida del proyecto:

Planificación

Fase inicial de definición de alcance y recursos

Activo

El proyecto está en ejecución activa

En Espera

Pausado temporalmente, a la espera

Completado

Finalizado exitosamente

Cancelado

Proyecto cancelado antes de completarse

Archivado

Guardado para referencia histórica

Niveles de Prioridad

Cada proyecto puede tener uno de 4 niveles de prioridad:

• 🟢 Baja (low): Proyectos sin urgencia
• 🟡 Media (medium): Prioridad estándar
• 🟠 Alta (high): Requiere atención prioritaria
• 🔴 Urgente (urgent): Máxima prioridad, atención inmediata

Vistas Principales

Vista Grid (Tarjetas)

Vista por defecto que muestra los proyectos en tarjetas con:

• Color identificativo del proyecto
• Estado y prioridad visual
• Información del cliente
• Progreso del proyecto
• Uso del presupuesto
• Fechas importantes
• Etiquetas del proyecto

Vista Kanban

Vista de tablero con columnas por estado, permitiendo:

• Drag & drop entre estados
• Cambio rápido de estado arrastrando tarjetas
• Vista consolidada del pipeline de proyectos
• Componente: KanbanView.tsx

Vista Calendario

Calendario interactivo que muestra:

• Fechas de inicio y fin de proyectos
• Hitos del proyecto
• Tareas con fechas de vencimiento
• Vista mensual navegable
• Componente: ProjectCalendarView.tsx

Funciones Principales

Este módulo incluye 8 funciones principales:

1. Crear Proyecto: Configuración completa con presupuesto, cliente y fechas
2. Gestionar Hitos: Definir objetivos intermedios con presupuesto asignado
3. Asignar Recursos: Gestión de personal, equipamiento y materiales
4. Configurar Presupuesto: Control de partidas presupuestarias y gastos
5. Vista Kanban: Gestión visual con drag & drop
6. Calendario: Timeline de tareas, hitos y eventos
7. Facturación por Hito: Auto-generación de facturas al completar hitos
8. Archivar Proyecto: Sistema de archivo con recuperación

Estadísticas

El dashboard de proyectos muestra:

• Total de Proyectos: Contador general
• Activos: Proyectos en ejecución
• Completados: Proyectos finalizados
• Presupuesto Total: Suma de todos los presupuestos
• Presupuesto Usado: Total gastado
• Promedio de Progreso: Media del avance de todos los proyectos

Filtros Avanzados

El sistema permite filtrar por:

• Estado: Filtrar por uno o múltiples estados
• Prioridad: Filtrar por nivel de urgencia
• Cliente: Ver proyectos de un cliente específico
• Rango de Fechas: Por fecha de inicio o fin
• Búsqueda: Por nombre o descripción del proyecto

Detalles Técnicos: Tipos TypeScript

Interfaces Principales

Project

interface Project {
  id: string;
  user_id: string;
  name: string;
  description?: string;
  status: ProjectStatus; // 'planning' | 'active' | 'on_hold' | 'completed' | 'cancelled' | 'archived'
  priority: ProjectPriority; // 'low' | 'medium' | 'high' | 'urgent'
  start_date?: string;
  end_date?: string;
  estimated_end_date?: string;
  budget_total: number;
  budget_used: number;
  progress: number;
  client_id?: string;
  manager_id?: string;
  tags?: string[];
  color: string; // Hex color
  is_template: boolean;
  template_source_id?: string;
  archived_at?: string;
  created_at: string;
  updated_at: string;

  // Relaciones
  client?: { id: string; name: string; };
  milestones?: ProjectMilestone[];
  resources?: ProjectResource[];
  documents?: ProjectDocument[];
  activities?: ProjectActivity[];
  time_entries?: ProjectTimeEntry[];
  budget_items?: ProjectBudgetItem[];
  team_members?: ProjectTeamMember[];
  tasks?: Task[];
}

ProjectMilestone

interface ProjectMilestone {
  id: string;
  project_id: string;
  name: string;
  description?: string;
  due_date?: string;
  status: MilestoneStatus; // 'pending' | 'in_progress' | 'completed' | 'cancelled'
  progress: number;
  budget_allocated: number;
  budget_used: number;
  sort_order: number;
  invoice_id?: string;
  auto_invoice: boolean;
  invoice_amount: number;
  invoice_description?: string;
  invoiced_at?: string;
  created_at: string;
  updated_at: string;
}

ProjectResource

interface ProjectResource {
  id: string;
  project_id: string;
  name: string;
  description?: string;
  type: ResourceType; // 'person' | 'equipment' | 'material' | 'budget'
  quantity: number;
  unit: string;
  cost_per_unit: number;
  total_cost: number;
  allocated_hours?: number;
  used_hours: number;
  supplier?: string;
  is_active: boolean;
  created_at: string;
  updated_at: string;
}

ProjectBudgetItem

interface ProjectBudgetItem {
  id: string;
  project_id: string;
  milestone_id?: string;
  category: string;
  name: string;
  description?: string;
  estimated_cost: number;
  actual_cost: number;
  is_approved: boolean;
  approved_by?: string;
  approved_at?: string;
  created_at: string;
  updated_at: string;
}

ProjectTeamMember

interface ProjectTeamMember {
  id: string;
  project_id: string;
  user_id: string;
  role: string;
  hourly_rate?: number;
  allocated_hours?: number;
  permissions: {
    can_edit: boolean;
    can_delete: boolean;
    can_view_budget: boolean;
  };
  joined_at: string;
  left_at?: string;
}

ProjectStats

interface ProjectStats {
  total: number;
  planning: number;
  active: number;
  completed: number;
  overdue: number;
  on_budget: number;
  over_budget: number;
  total_budget: number;
  total_budget_used: number;
  total_hours_logged: number;
  average_progress: number;
}

Detalles Técnicos: Componentes React

Componentes Principales

ProjectFormSheet.tsx

Formulario principal para crear/editar proyectos con tabs:

• General: Nombre, descripción, estado, prioridad, cliente, color
• Fechas: Fecha inicio, fin estimado, fin real
• Presupuesto: Presupuesto total asignado
• Etiquetas: Tags para clasificación

KanbanView.tsx

Vista de tablero Kanban con drag & drop:

• Columnas por estado (5 estados)
• Arrastrar tareas entre estados
• Indicadores visuales de prioridad
• Contador de tareas por columna
• Integración con @dnd-kit/core

MilestoneForm.tsx

Formulario de gestión de hitos:

• Información básica del hito
• Presupuesto asignado al hito
• Fechas de vencimiento
• Estado del hito
• Configuración de facturación automática

MilestoneInvoiceConfig.tsx

Configuración de facturación por hito:

• Toggle para activar auto-facturación
• Monto a facturar
• Descripción para la factura
• Cálculo automático de IVA
• Vista previa del total

ProjectCalendarView.tsx

Calendario interactivo:

• Vista mensual de eventos
• Eventos de tareas (inicio, vencimiento)
• Eventos de proyectos (inicio, fin)
• Eventos de hitos
• Panel de detalles de fecha seleccionada

ProjectProgressCalculator.tsx

Calculadora de progreso automático:

• Cálculo basado en tareas completadas
• Ponderación por hitos
• Actualización en tiempo real
• Visualización de métricas

ProjectArchiveSystem.tsx

Sistema de archivado:

• Archivar proyecto y tareas activas
• Restaurar proyecto archivado
• Eliminación permanente con confirmación
• Advertencias de tareas activas

ActivityTracker.tsx

Registro de actividades:

• Log de cambios en el proyecto
• Historial de actualizaciones
• Timeline de eventos
• Filtrado por tipo de actividad

Detalles Técnicos: Base de Datos

Tablas de Supabase

projects

Tabla principal de proyectos:

- id (uuid, PK)
- user_id (uuid, FK a auth.users)
- name (text)
- description (text)
- status (project_status_enum)
- priority (project_priority_enum)
- start_date (date)
- end_date (date)
- estimated_end_date (date)
- budget_total (numeric)
- budget_used (numeric)
- progress (integer, 0-100)
- client_id (uuid, FK a customers)
- manager_id (uuid)
- tags (text[])
- color (text)
- is_template (boolean)
- template_source_id (uuid)
- archived_at (timestamptz)
- created_at (timestamptz)
- updated_at (timestamptz)

project_milestones

Hitos del proyecto:

- id (uuid, PK)
- project_id (uuid, FK a projects)
- name (text)
- description (text)
- due_date (date)
- status (milestone_status_enum)
- progress (integer)
- budget_allocated (numeric)
- budget_used (numeric)
- sort_order (integer)
- invoice_id (uuid, FK a invoices)
- auto_invoice (boolean)
- invoice_amount (numeric)
- invoice_description (text)
- invoiced_at (timestamptz)
- created_at (timestamptz)
- updated_at (timestamptz)

project_resources

Recursos asignados:

- id (uuid, PK)
- project_id (uuid, FK a projects)
- name (text)
- description (text)
- type (resource_type_enum)
- quantity (numeric)
- unit (text)
- cost_per_unit (numeric)
- total_cost (numeric)
- allocated_hours (integer)
- used_hours (integer)
- supplier (text)
- is_active (boolean)
- created_at (timestamptz)
- updated_at (timestamptz)

project_budget_items

Partidas presupuestarias:

- id (uuid, PK)
- project_id (uuid, FK a projects)
- milestone_id (uuid, FK a project_milestones)
- category (text)
- name (text)
- description (text)
- estimated_cost (numeric)
- actual_cost (numeric)
- is_approved (boolean)
- approved_by (uuid)
- approved_at (timestamptz)
- created_at (timestamptz)
- updated_at (timestamptz)

project_team_members

Miembros del equipo:

- id (uuid, PK)
- project_id (uuid, FK a projects)
- user_id (uuid, FK a auth.users)
- role (text)
- hourly_rate (numeric)
- allocated_hours (integer)
- permissions (jsonb)
- joined_at (timestamptz)
- left_at (timestamptz)

project_activities

Registro de actividades:

- id (uuid, PK)
- project_id (uuid, FK a projects)
- user_id (uuid, FK a auth.users)
- activity_type (text)
- title (text)
- description (text)
- metadata (jsonb)
- created_at (timestamptz)

project_time_entries

Registro de tiempo:

- id (uuid, PK)
- project_id (uuid, FK a projects)
- task_id (uuid, FK a tasks)
- user_id (uuid, FK a auth.users)
- description (text)
- hours (numeric)
- hourly_rate (numeric)
- total_cost (numeric)
- entry_date (date)
- billable (boolean)
- created_at (timestamptz)

project_documents

Documentos del proyecto:

- id (uuid, PK)
- project_id (uuid, FK a projects)
- name (text)
- description (text)
- document_type (document_type_enum)
- file_path (text)
- file_size (integer)
- mime_type (text)
- version (integer)
- is_latest_version (boolean)
- uploaded_by (uuid)
- tags (text[])
- created_at (timestamptz)
- updated_at (timestamptz)

Tipos Enum

-- Estado del proyecto
CREATE TYPE project_status_enum AS ENUM (
  'planning',
  'active',
  'on_hold',
  'completed',
  'cancelled',
  'archived'
);

-- Prioridad del proyecto
CREATE TYPE project_priority_enum AS ENUM (
  'low',
  'medium',
  'high',
  'urgent'
);

-- Estado del hito
CREATE TYPE milestone_status_enum AS ENUM (
  'pending',
  'in_progress',
  'completed',
  'cancelled'
);

-- Tipo de recurso
CREATE TYPE resource_type_enum AS ENUM (
  'person',
  'equipment',
  'material',
  'budget'
);

-- Tipo de documento
CREATE TYPE document_type_enum AS ENUM (
  'contract',
  'proposal',
  'specification',
  'report',
  'invoice',
  'other'
);

Detalles Técnicos: Schema de Validación

Validación con Zod

projectSchema

import { z } from "zod";
import { isValid, parseISO, isBefore } from "date-fns";

export const projectSchema = z.object({
  name: z.string()
    .min(1, "El nombre del proyecto es obligatorio")
    .max(100, "El nombre no puede exceder 100 caracteres"),

  description: z.string().optional(),

  status: z.enum(['planning', 'active', 'on_hold', 'completed', 'cancelled', 'archived']),

  priority: z.enum(['low', 'medium', 'high', 'urgent']),

  start_date: z.string().optional().refine((date) => {
    if (!date) return true;
    return isValid(parseISO(date));
  }, {
    message: "Fecha de inicio inválida"
  }),

  end_date: z.string().optional(),

  estimated_end_date: z.string().optional(),

  budget_total: z.number()
    .min(0, "El presupuesto no puede ser negativo")
    .max(999999999, "El presupuesto es demasiado alto"),

  client_id: z.string().uuid("ID de cliente inválido").optional(),

  manager_id: z.string().uuid("ID de gerente inválido").optional(),

  tags: z.array(z.string()).optional(),

  color: z.string()
    .regex(/^#[0-9A-F]{6}$/i, "Color inválido (debe ser formato hexadecimal)")
    .optional(),
}).refine((data) => {
  // Validar que end_date sea posterior a start_date
  if (data.start_date && data.end_date) {
    const start = parseISO(data.start_date);
    const end = parseISO(data.end_date);
    return isBefore(start, end) || start.getTime() === end.getTime();
  }
  return true;
}, {
  message: "La fecha de fin debe ser posterior o igual a la fecha de inicio",
  path: ["end_date"]
});

Flujo de Trabajo Típico

1. Crear Proyecto: Definir nombre, cliente, presupuesto y fechas
2. Agregar Hitos: Dividir el proyecto en objetivos intermedios
3. Asignar Recursos: Añadir miembros del equipo y recursos necesarios
4. Crear Tareas: Desglosar el trabajo en tareas asignables
5. Seguimiento: Monitorear progreso, presupuesto y tiempos
6. Facturación: Generar facturas automáticas al completar hitos
7. Completar: Marcar como completado o archivar para referencia

Integraciones

El módulo de Proyectos se integra con:

• Clientes: Asociación de proyectos a clientes
• Facturas: Generación automática de facturas por hitos
• Tareas: Sistema completo de gestión de tareas del proyecto
• Calendario: Vista unificada de todos los eventos
• Actividades: Registro automático de cambios y actividades
• Documentos: Gestión de documentación del proyecto

Cómo trabajan juntas las funciones

Las 8 funciones del módulo están diseñadas para funcionar de forma integrada a lo largo del ciclo de vida del proyecto:

1. Crear Proyecto → Base para todo
2. Gestionar Hitos → División del proyecto en objetivos intermedios
3. Asignar Recursos → Ejecución del trabajo
4. Configurar Presupuesto → Control financiero
5. Vista Kanban → Gestión visual de tareas
6. Calendario → Timeline unificado
7. Facturación por Hito → Monetización automática
8. Archivar Proyecto → Cierre del ciclo de vida

Flujo completo:

Crear Proyecto → Definir Hitos → Asignar Recursos →
Crear Tareas (Kanban) → Seguimiento (Calendario) →
Completar Hitos → Facturar Automáticamente →
Completar Proyecto → Archivar

Nota

Todas las funciones respetan los permisos de empleados y asesores configurados en el sistema.

Permisos

El sistema respeta los permisos de empleados y asesores:

• Empleados: Según permisos configurados en projects module
• Asesores: Según permisos para el negocio del cliente
• Vista de solo lectura si no hay permisos de edición