@hed-hog/operations 0.0.329 → 0.0.331

package/src/dashboard/README.md

@@ -0,0 +1,214 @@
+# Dashboard Widgets - Operations Module
+
+## Arquitetura
+
+O dashboard do módulo operations segue um padrão de composição modular com 3 camadas de widgets baseados em roles:
+
+### Roles e Widgets
+
+| Role | Widgets | Descrição |
+|------|---------|-----------|
+| `operations-collaborator` | 8 widgets | Visão pessoal: horas, timesheet, alocações, solicitações, prazos, ações rápidas |
+| `admin-operations-supervisor` | 8 widgets | Visão de time: headcount, aprovações, horas, capacidade, utilização, alertas, projetos, fila |
+| `admin-operations-director` | 7 widgets | Visão de portfólio: projetos, custos, esforço, risco, status, distribuição, prazos |
+
+### Estrutura de Pastas
+
+```
+src/dashboard/
+├── hooks/
+│   └── useDashboardData.ts          # Hook para buscar dados do backend
+├── types/
+│   └── widgets.types.ts             # Tipos TypeScript para dados de widgets
+├── components/
+│   └── DashboardLayout.tsx          # Layout principal que renderiza widgets
+└── widgets/
+    ├── MyHoursPeriodKpi.tsx         # Exemplo: Collaborator widget
+    ├── TeamHeadcountKpi.tsx         # Exemplo: Supervisor widget
+    ├── PortfolioProjectsKpi.tsx     # Exemplo: Director widget
+    └── [outros widgets...]          # A implementar
+```
+
+## Como Adicionar um Novo Widget
+
+### 1. Defina o tipo de dados em `types/widgets.types.ts`
+
+Adicione a interface de dados para seu widget:
+
+```typescript
+export interface MyNewWidgetData {
+  title: string;
+  value: number;
+  // ... outros campos
+}
+```
+
+### 2. Crie o componente widget
+
+Crie um arquivo em `widgets/MyNewWidget.tsx`:
+
+```typescript
+'use client';
+
+import React from 'react';
+
+interface MyNewWidgetProps {
+  slug: string;
+  title: string;
+  roleSlug: string;
+  width?: number;
+  height?: number;
+  data?: MyNewWidgetData;
+  style?: React.CSSProperties;
+}
+
+const MyNewWidget: React.FC<MyNewWidgetProps> = ({
+  title,
+  data,
+  style,
+}) => {
+  return (
+    <div className="bg-white rounded-lg shadow-sm p-4" style={style}>
+      <h3 className="text-sm font-medium">{title}</h3>
+      {/* Renderizar dados aqui */}
+    </div>
+  );
+};
+
+export default MyNewWidget;
+```
+
+### 3. Registre o widget em `DashboardLayout.tsx`
+
+Adicione ao `WIDGET_REGISTRY`:
+
+```typescript
+'my-new-widget': React.lazy(() => import('./widgets/MyNewWidget')),
+```
+
+### 4. Configure permissões no YAML
+
+Atualize `libraries/operations/hedhog/data/dashboard_component.yaml`:
+
+```yaml
+- slug: my-new-widget
+  library_slug: operations
+  width: 3
+  height: 1
+  name:
+    en: My New Widget
+    pt: Meu Novo Widget
+```
+
+Atualize `libraries/operations/hedhog/data/dashboard_component_role.yaml`:
+
+```yaml
+- component_id:
+    where:
+      slug: my-new-widget
+  role_id:
+    where:
+      slug: operations-collaborator  # ou a role apropriada
+```
+
+## Backend Integration
+
+### Endpoint: GET /operations/dashboard
+
+O backend retorna dados estruturados conforme a role do usuário:
+
+```typescript
+{
+  actor: {
+    roleScope: 'full' | 'team' | 'self',
+    collaboratorId: number,
+    collaboratorName: string,
+    teamSize: number,
+  },
+  cards: {
+    // ... dados agregados
+  },
+  recentTimesheets: [],
+  // ... dados específicos por role
+}
+```
+
+### Segurança
+
+⚠️ **IMPORTANTE:** O backend sanitiza automaticamente dados sensíveis por role:
+
+- **Directors**: Veem TODOS os dados (salários, custos, etc.)
+- **Supervisors**: Veem dados monetários da equipe apenas
+- **Collaborators**: Veem APENAS seus próprios dados, não de colegas
+
+Nenhuma sanitização adicional é necessária no frontend - confia no backend!
+
+## Padrões de Componente
+
+### KPI Card (Métrica simples)
+
+```typescript
+{
+  "métrica_principal": número grande em destaque,
+  "contexto": "de total",
+  "breakdown": [array de sub-métricas],
+  "status_indicator": visual de saúde (verde/amarelo/vermelho)
+}
+```
+
+### Chart/Graph (Visualização complexa)
+
+```typescript
+{
+  "título": string,
+  "dados": array de pontos com x,y,label,
+  "legenda": tipos de dados mostrados
+}
+```
+
+### Lista (Array de items)
+
+```typescript
+{
+  "cabeçalhos": ["coluna1", "coluna2", ...],
+  "linhas": [{ coluna1: valor, coluna2: valor }, ...],
+  "paginação": opcional
+}
+```
+
+## Testes
+
+Para testar um widget com dados mock:
+
+```typescript
+const mockData = {
+  plannedHours: 40,
+  approvedHours: 32,
+  pendingHours: 4,
+};
+
+<MyHoursPeriodKpi 
+  slug="my-hours-period-kpi"
+  title="Horas no Período"
+  roleSlug="operations-collaborator"
+  data={mockData}
+/>
+```
+
+## Loading States
+
+Cada widget implementa um fallback de loading usando `React.Suspense`:
+
+```typescript
+<React.Suspense fallback={<SkeletonLoader />}>
+  <MyWidget data={data} />
+</React.Suspense>
+```
+
+## Próximas Etapas
+
+- [ ] Implementar hook `useDashboardData` com react-query
+- [ ] Criar 20 widgets restantes (20/23 ainda faltam)
+- [ ] Integrar com Recharts/Chart.js para gráficos
+- [ ] Adicionar testes unitários para cada widget
+- [ ] Documentar parâmetros de cada widget

package/src/dashboard/components/DashboardLayout.tsx

@@ -0,0 +1,131 @@
+'use client';
+
+/**
+ * Dashboard Principal - Renderiza widgets conforme role do usuário
+ * 
+ * Fluxo:
+ * 1. Detecta role do usuário (collaborator/supervisor/director)
+ * 2. Busca dados via GET /operations/dashboard
+ * 3. Renderiza widgets apropriados para a role
+ * 4. Cada widget é um componente reutilizável
+ */
+
+import React, { useMemo } from 'react';
+
+// Tipos de widgets por role
+interface WidgetDefinition {
+  slug: string;
+  title: string;
+  roleSlug: string;
+  width: number;
+  height: number;
+  xAxis: number;
+  yAxis: number;
+  componentPath: string;
+}
+
+// Mapear slugs aos componentes - importados dinamicamente do admin app
+// Os widgets estão em: apps/admin/src/app/(app)/(libraries)/operations/dashboard/widgets/
+const WIDGET_REGISTRY: Record<string, React.ComponentType<any>> = {};
+
+// Lazy loading de widgets - para evitar imports circulares
+const getWidget = (slug: string): React.ComponentType<any> | null => {
+  // Este mapa será populado em runtime via importação dinâmica
+  // Por enquanto, retorna null se widget não estiver pronto
+  return WIDGET_REGISTRY[slug] || null;
+};
+
+interface DashboardLayoutProps {
+  roleSlugs: string[];
+  dashboardSlug: string;
+  widgets: WidgetDefinition[];
+  data: any;
+  isLoading?: boolean;
+}
+
+export const DashboardLayout: React.FC<DashboardLayoutProps> = ({
+  roleSlugs,
+  dashboardSlug,
+  widgets,
+  data,
+  isLoading = false,
+}) => {
+  // Filtrar widgets para a role atual
+  const visibleWidgets = useMemo(() => {
+    return widgets.filter(widget => 
+      roleSlugs.includes(widget.roleSlug)
+    );
+  }, [widgets, roleSlugs]);
+
+  if (isLoading) {
+    return (
+      <div className="grid gap-4 w-full h-full">
+        {Array(4).fill(0).map((_, i) => (
+          <div 
+            key={i} 
+            className="bg-gray-200 rounded-lg animate-pulse"
+            style={{ minHeight: '200px' }}
+          />
+        ))}
+      </div>
+    );
+  }
+
+  return (
+    <div className="grid gap-4 w-full auto-rows-max" 
+         style={{
+           gridTemplateColumns: 'repeat(12, 1fr)',
+         }}>
+      {visibleWidgets.map(widget => {
+        const Component = WIDGET_REGISTRY[widget.slug];
+        
+        if (!Component) {
+          return (
+            <div 
+              key={widget.slug}
+              style={{
+                gridColumn: `span ${Math.min(widget.width, 12)}`,
+                gridRow: `auto / span ${widget.height}`,
+              }}
+              className="bg-red-50 border-2 border-red-200 rounded-lg p-4"
+            >
+              <p className="text-red-700 text-sm">
+                Component not found: {widget.slug}
+              </p>
+            </div>
+          );
+        }
+
+        return (
+          <React.Suspense 
+            key={widget.slug}
+            fallback={
+              <div 
+                style={{
+                  gridColumn: `span ${Math.min(widget.width, 12)}`,
+                  gridRow: `auto / span ${widget.height}`,
+                }}
+                className="bg-gray-200 rounded-lg animate-pulse"
+              />
+            }
+          >
+            <Component
+              slug={widget.slug}
+              title={widget.title}
+              roleSlug={roleSlugs[0]}
+              width={widget.width}
+              height={widget.height}
+              data={data?.[widget.slug]}
+              style={{
+                gridColumn: `span ${Math.min(widget.width, 12)}`,
+                gridRow: `auto / span ${widget.height}`,
+              }}
+            />
+          </React.Suspense>
+        );
+      })}
+    </div>
+  );
+};
+
+export default DashboardLayout;

package/src/dashboard/components/widget-registry.ts

@@ -0,0 +1,255 @@
+/**
+ * Widget Registry - Mapa de widgets do dashboard
+ * 
+ * Este arquivo centraliza todas as informações de widgets para o dashboard da operations.
+ * Os widgets são importados dinamicamente em runtime.
+ */
+
+export interface WidgetInfo {
+  slug: string;
+  title: string;
+  component: string;
+  roleSlug: string;
+  width: number;
+  height: number;
+  category: 'collaborator' | 'supervisor' | 'director';
+}
+
+// Widgets para Colaboradores (7)
+export const COLLABORATOR_WIDGETS: WidgetInfo[] = [
+  {
+    slug: 'my-hours-period-kpi',
+    title: 'Minhas Horas (Período)',
+    component: 'MyHoursPeriodKpi',
+    roleSlug: 'collaborator',
+    width: 6,
+    height: 2,
+    category: 'collaborator',
+  },
+  {
+    slug: 'my-timesheet-status-kpi',
+    title: 'Status do Timesheet',
+    component: 'MyTimesheetStatusKpi',
+    roleSlug: 'collaborator',
+    width: 6,
+    height: 2,
+    category: 'collaborator',
+  },
+  {
+    slug: 'my-project-allocations-kpi',
+    title: 'Minhas Alocações',
+    component: 'MyProjectAllocationsKpi',
+    roleSlug: 'collaborator',
+    width: 6,
+    height: 2,
+    category: 'collaborator',
+  },
+  {
+    slug: 'my-open-requests-kpi',
+    title: 'Requisições Abertas',
+    component: 'MyOpenRequestsKpi',
+    roleSlug: 'collaborator',
+    width: 6,
+    height: 2,
+    category: 'collaborator',
+  },
+  {
+    slug: 'my-weekly-journey',
+    title: 'Jornada Semanal',
+    component: 'MyWeeklyJourney',
+    roleSlug: 'collaborator',
+    width: 12,
+    height: 3,
+    category: 'collaborator',
+  },
+  {
+    slug: 'my-relevant-deadlines',
+    title: 'Prazos Relevantes',
+    component: 'MyRelevantDeadlines',
+    roleSlug: 'collaborator',
+    width: 6,
+    height: 3,
+    category: 'collaborator',
+  },
+  {
+    slug: 'my-pending-requests-list',
+    title: 'Requisições Pendentes',
+    component: 'MyPendingRequestsList',
+    roleSlug: 'collaborator',
+    width: 6,
+    height: 3,
+    category: 'collaborator',
+  },
+  {
+    slug: 'my-quick-actions',
+    title: 'Ações Rápidas',
+    component: 'MyQuickActions',
+    roleSlug: 'collaborator',
+    width: 12,
+    height: 2,
+    category: 'collaborator',
+  },
+];
+
+// Widgets para Supervisores (7)
+export const SUPERVISOR_WIDGETS: WidgetInfo[] = [
+  {
+    slug: 'team-pending-approvals-kpi',
+    title: 'Aprovações Pendentes',
+    component: 'TeamPendingApprovalsKpi',
+    roleSlug: 'supervisor',
+    width: 6,
+    height: 2,
+    category: 'supervisor',
+  },
+  {
+    slug: 'team-hours-kpi',
+    title: 'Horas do Time',
+    component: 'TeamHoursKpi',
+    roleSlug: 'supervisor',
+    width: 6,
+    height: 2,
+    category: 'supervisor',
+  },
+  {
+    slug: 'team-capacity-kpi',
+    title: 'Capacidade do Time',
+    component: 'TeamCapacityKpi',
+    roleSlug: 'supervisor',
+    width: 6,
+    height: 2,
+    category: 'supervisor',
+  },
+  {
+    slug: 'team-utilization-overview',
+    title: 'Utilização do Time',
+    component: 'TeamUtilizationOverview',
+    roleSlug: 'supervisor',
+    width: 6,
+    height: 2,
+    category: 'supervisor',
+  },
+  {
+    slug: 'team-workload-alerts',
+    title: 'Alertas de Carga',
+    component: 'TeamWorkloadAlerts',
+    roleSlug: 'supervisor',
+    width: 12,
+    height: 3,
+    category: 'supervisor',
+  },
+  {
+    slug: 'managed-projects-status',
+    title: 'Status dos Projetos',
+    component: 'ManagedProjectsStatus',
+    roleSlug: 'supervisor',
+    width: 6,
+    height: 3,
+    category: 'supervisor',
+  },
+  {
+    slug: 'team-approval-queue',
+    title: 'Fila de Aprovações',
+    component: 'TeamApprovalQueue',
+    roleSlug: 'supervisor',
+    width: 6,
+    height: 3,
+    category: 'supervisor',
+  },
+];
+
+// Widgets para Diretores (8)
+export const DIRECTOR_WIDGETS: WidgetInfo[] = [
+  {
+    slug: 'portfolio-costs-kpi',
+    title: 'Custos do Portfólio',
+    component: 'PortfolioCostsKpi',
+    roleSlug: 'director',
+    width: 6,
+    height: 2,
+    category: 'director',
+  },
+  {
+    slug: 'portfolio-effort-kpi',
+    title: 'Esforço do Portfólio',
+    component: 'PortfolioEffortKpi',
+    roleSlug: 'director',
+    width: 6,
+    height: 2,
+    category: 'director',
+  },
+  {
+    slug: 'portfolio-risk-kpi',
+    title: 'Risco do Portfólio',
+    component: 'PortfolioRiskKpi',
+    roleSlug: 'director',
+    width: 6,
+    height: 2,
+    category: 'director',
+  },
+  {
+    slug: 'project-status-overview',
+    title: 'Status dos Projetos',
+    component: 'ProjectStatusOverview',
+    roleSlug: 'director',
+    width: 6,
+    height: 2,
+    category: 'director',
+  },
+  {
+    slug: 'effort-by-project',
+    title: 'Esforço por Projeto',
+    component: 'EffortByProject',
+    roleSlug: 'director',
+    width: 12,
+    height: 3,
+    category: 'director',
+  },
+  {
+    slug: 'capacity-distribution',
+    title: 'Distribuição de Capacidade',
+    component: 'CapacityDistribution',
+    roleSlug: 'director',
+    width: 6,
+    height: 3,
+    category: 'director',
+  },
+  {
+    slug: 'headcount-by-area',
+    title: 'Headcount por Área',
+    component: 'HeadcountByArea',
+    roleSlug: 'director',
+    width: 6,
+    height: 3,
+    category: 'director',
+  },
+  {
+    slug: 'strategic-deadlines',
+    title: 'Prazos Estratégicos',
+    component: 'StrategicDeadlines',
+    roleSlug: 'director',
+    width: 12,
+    height: 3,
+    category: 'director',
+  },
+];
+
+// Registro completo de todos os widgets
+export const ALL_WIDGETS = [
+  ...COLLABORATOR_WIDGETS,
+  ...SUPERVISOR_WIDGETS,
+  ...DIRECTOR_WIDGETS,
+];
+
+// Acessores úteis
+export const getWidgetsByRole = (roleSlug: string): WidgetInfo[] => {
+  return ALL_WIDGETS.filter(w => w.roleSlug === roleSlug);
+};
+
+export const getWidgetBySlug = (slug: string): WidgetInfo | undefined => {
+  return ALL_WIDGETS.find(w => w.slug === slug);
+};
+
+export const getWidgetsByCategory = (category: 'collaborator' | 'supervisor' | 'director'): WidgetInfo[] => {
+  return ALL_WIDGETS.filter(w => w.category === category);
+};

package/src/dashboard/hooks/useDashboardData.ts

@@ -0,0 +1,29 @@
+/**
+ * Hook para buscar dados do dashboard de operations
+ * Cacheia dados por 60s usando react-query
+ * Filtra automaticamente por role do usuário
+ */
+
+import type { OperationsDashboardData } from '../types/widgets.types';
+
+type DashboardRequestFn = <T extends object>(config: {
+  url: string;
+  method: 'GET';
+}) => Promise<{ data: T }>;
+
+/**
+ * Loader enxuto para o payload agregado do dashboard.
+ * A camada de UI pode embrulhar isso em react-query sem repetir o contrato.
+ */
+export async function fetchDashboardData(request: DashboardRequestFn) {
+  const response = await request<OperationsDashboardData>({
+    url: '/operations/dashboard',
+    method: 'GET',
+  });
+
+  return response.data;
+}
+
+export async function useDashboardData(request: DashboardRequestFn) {
+  return fetchDashboardData(request);
+}