ERP Server Actions: Leads, Quotes, Requirements & Dashboard

getLeads(tenantCode?: string | null): Promise<LeadRow[]>

interface LeadRow {
  id: string;
  lead_code: string;
  risk_level: "CALIENTE" | "TIBIO" | "FRIO" | "SPAM";
  score: number;
  status: string;
  lead_source: string | null;
  notes: string | null;
  created_at: string;
  assigned_user_id: string | null;
  client: {
    legal_name: string;
    city: string | null;
  } | null;
  contact: {
    first_name: string;
    last_name: string;
    email: string | null;
    phone: string | null;
  } | null;
  diagnostic: {
    id: string;
    diagnostic_code: string;
    service_type: string;
    calculated_cfm: number | null;
    cfm_category: string;
    estimated_price_min_cop: number;
    estimated_price_max_cop: number;
    materials_recommendation: string | null;
    dimensions: { length: number; width: number; height: number } | null;
    calculated_volume: number | null;
  } | null;
}

updateLeadStatus(
  leadId: string,
  newStatus: "NUEVO" | "EN_SEGUIMIENTO" | "CALIFICADO" | "RECHAZADO" | "CONVERTIDO"
): Promise<void>

getQuotes(tenantCode?: string | null): Promise<QuoteRow[]>

interface QuoteRow {
  id: string;
  quote_code: string;
  client_id: string;
  requirement_id: string | null;
  assigned_user_id: string | null;
  valid_until: string;
  subtotal: number;
  total_amount: number;
  status: "BORRADOR" | "EN_REVISION" | "ENVIADA" | "APROBADA" | "RECHAZADA" | "VENCIDA";
  created_at: string;
  client: { legal_name: string } | null;
}

createQuote(
  tenantCode: string | null,
  quoteData: {
    clientId: string;
    requirementId?: string;
    validUntil: string;
  }
): Promise<Quote>

getQuoteItems(quoteId: string): Promise<QuoteItem[]>

addQuoteItem(
  tenantCode: string | null,
  itemData: {
    quoteId: string;
    description: string;
    itemType: string;
    quantity: number;
    unitPrice: number;
    discountAmount: number;
    taxPercent: number;
    itemOrder: number;
  }
): Promise<QuoteItem>

updateQuoteStatus(quoteId: string, status: string): Promise<Quote>

getRequirements(tenantCode?: string | null): Promise<RequirementRow[]>

interface RequirementRow {
  id: string;
  requirement_code: string;
  title: string;
  category: string;
  priority: "LOW" | "MEDIUM" | "HIGH";
  status:
    | "BORRADOR"
    | "NUEVO"
    | "EN_REVISION"
    | "DIAGNOSTICO"
    | "COTIZACION"
    | "COMPLETADO"
    | "CANCELADO";
  client_id: string;
  engineering_user_id: string | null;
  sales_user_id: string | null;
  created_at: string;
  client: { legal_name: string; city: string | null } | null;
  engineering_user: { first_name: string; last_name: string } | null;
}

createRequirement(
  tenantCode: string | null,
  reqData: {
    title: string;
    clientId: string;
    category: string;
    priority: string;
  }
): Promise<Requirement>

updateRequirementStatus(
  reqId: string,
  newStatus: string,
  extra?: Record<string, any>
): Promise<Requirement>

getDashboardCommandCenter(tenantCode: string | null): Promise<DashboardCommandCenterData>

interface DashboardCommandCenterData {
  tenantName: string;
  outstanding: number;           // Total unpaid balance (COP)
  invoiceCount: number;          // Count of pending invoices
  hasOverdue: boolean;           // Any invoices with status VENCIDA
  hasDueSoon: boolean;           // Fallback: true when invoiceCount > 0 and no overdue
  delta: number;                 // MoM change ratio (e.g. 0.124 = +12.4%)
  sparkline: number[];           // 30-point sparkline array derived from outstanding
  kpis: {
    totalInvoiced: number;       // Total invoiced for current month period
    totalPayments: number;       // Total payments received for current month
    leadSlaBreachRate: number;   // Lead SLA breach rate (0–100)
  };
  recentEvents: Array<{
    id: string;
    eventCode: string;
    entityType: string;
    entityId: string;
    payload: any;
    createdAt: string;
  }>;
  auditLog: Array<{
    id: string;
    eventCode: string;
    entityType: string;
    entityId: string | null;
    action: string;
    userId: string | null;
    userName: string | null;    // Resolved from users table
    createdAt: string;
  }>;
  operationsHealth: {
    inventory:  { score: number; alerts: number };  // score = max(0, 100 - lowStockItems × 10)
    purchases:  { score: number; alerts: number };  // score = max(0, 100 - pendingReqs × 8)
    billing:    { score: number; alerts: number };  // score = collection rate %
    crm:        { score: number; alerts: number };  // score = (converted / total leads) × 100
  };
  queueTasks: Array<{
    id: string;
    description: string;
    value: string | null;
    deadline: string;
    isOverdue: boolean;
    link: string;
  }>;
  userName: string;               // Currently hardcoded to "Administrador"
}

getKpisForRole(tenantCode: string | null): Promise<RoleDashboardData>

interface RoleDashboardData {
  kpis: KpiValue[];
  pending: PendingItem[];
  queueTitle: string;
  queueSubtitle: string;
  notificationsTitle: string;
  notificationsCount: number;
  notifications?: NotificationItem[];
}

interface KpiValue {
  id: string;
  label: string;
  value: string;
  sub?: string;
  trend?: "up" | "down" | "neutral";
  variant?: "success" | "info" | "warning" | "danger" | "neutral";
  link?: string;
}

interface PendingItem {
  id: string;
  description: string;
  value?: string | null;
  deadline: string;
  isOverdue: boolean;
  link: string;
}

interface NotificationItem {
  id: string;
  title: string;
  description: string;
  link: string;
  isDanger: boolean;
}

listUsers(tenantCode: string | null): Promise<UserListItem[]>

listRoles(tenantCode: string | null): Promise<RoleListItem[]>

createUser(
  tenantCode: string | null,
  data: {
    email: string;
    firstName: string;
    lastName: string;
    phone?: string;
    roleId: string | null;
  }
): Promise<{ success: boolean; error?: string; userId?: string }>

updateUser(
  tenantCode: string | null,
  userId: string,
  data: { firstName?: string; lastName?: string; phone?: string }
): Promise<{ success: boolean; error?: string }>

assignRole(
  tenantCode: string | null,
  userId: string,
  roleId: string
): Promise<{ success: boolean; error?: string }>

removeRole(
  tenantCode: string | null,
  userId: string,
  roleId: string
): Promise<{ success: boolean; error?: string }>