Escalonamento de Equipe

Visão Geral

O módulo de Escalonamento integra planejamento manual de turnos com sugestões de escala geradas por IA (Claude Sonnet 4.6), análise de demanda histórica e controle de disponibilidade da equipe.

Característica	Detalhe
Rota	/t/:slug/admin/scheduling
View	frontend-react/src/views/admin/SchedulingView.tsx
Backend	backend/src/scheduling/
Permissão	Admin, Superadmin
IA	Claude Sonnet 4.6 via Anthropic SDK

---

Abas

A view possui 4 abas:

Aba	Conteúdo
Escala	Grade semanal de turnos — calendário visual WeekCalendarGrid
Demanda	Heatmap de tráfego histórico por dia e hora
Disponibilidade	Cadastro e edição de disponibilidade da equipe
Custos	Resumo de custo de mão de obra por semana

---

Sugestões de Escala via IA

Como funciona

Todo Monday às 07:00 um cron job (@Cron('0 7 * * 1')) gera sugestões de escala para todas as filiais ativas de todos os tenants.

Dados analisados:

• Tráfego histórico de pedidos por hora (getHourlyTraffic — últimos 28 dias)
• Disponibilidade cadastrada da equipe (StaffAvailability)
• Sugestão anterior (feedback loop — evita repetir o mesmo erro)

Modelo: claude-sonnet-4-6 com prompt especializado em escalação de restaurantes.

Output: Array de ShiftSuggestion persistido em StaffingSuggestion.

Schemas

StaffingSuggestion

backend/src/scheduling/schemas/staffing-suggestion.schema.ts

Campo	Tipo	Descrição
tenant	ObjectId	Tenant
branch	ObjectId → Branch	Filial
weekStartDate	Date	Segunda-feira da semana sugerida
suggestions	ShiftSuggestion[]	Turnos sugeridos
status	enum	pending | applied | dismissed

ShiftSuggestion (sub-documento)

Campo	Tipo	Descrição
dayOfWeek	number (0–6)	Dia da semana (0 = Domingo)
startTime	string	Horário início (ex: "10:00")
endTime	string	Horário fim (ex: "18:00")
requiredStaff	number	Número de colaboradores recomendado
role	string?	Função/cargo recomendado
notes	string?	Observações adicionais do modelo

StaffAvailability

backend/src/scheduling/schemas/staff-availability.schema.ts

Campo	Tipo	Descrição
tenant	ObjectId	Tenant
user	ObjectId → User	Colaborador
dayOfWeek	number (0–6)	Dia da semana
startTime	string	Início da disponibilidade
endTime	string	Fim da disponibilidade
maxHoursPerWeek	number?	Limite semanal de horas

Feedback Loop

Ao gerar uma nova sugestão, o serviço recupera a sugestão anterior da mesma filial (getLastSuggestion) e inclui no prompt para que o modelo aprenda com aceitações e rejeições anteriores.

---

Heatmap de Demanda

Componente: frontend-react/src/components/scheduling/DemandHeatmap.tsx

Exibe um grid de dias × horas colorido por intensidade de pedidos. Útil para identificar horários de pico e calibrar a escala manualmente.

API: GET /t/:slug/scheduling/demand-heatmap?branchId=&weeks=4

Retorna DemandHeatmapCell[]:

interface DemandHeatmapCell {
  dayOfWeek: number;   // 0–6
  hour: number;        // 0–23
  orderCount: number;  // média de pedidos neste slot
}

---

Resumo de Custos

Componente: frontend-react/src/components/scheduling/LaborCostSummary.tsx

Agrega os turnos planejados para a semana selecionada e calcula:

• Total de horas por colaborador
• Custo estimado por colaborador (horas × taxa horária cadastrada)
• Total de custo de mão de obra da semana

---

API

Base: /t/:slug/scheduling

Guards: JwtAuthGuard, TenantGuard

Método	Endpoint	Descrição
GET	/shifts?branchId=&start=&end=	Listar turnos da semana
POST	/shifts	Criar turno manualmente
PUT	/shifts/:id	Atualizar turno
DELETE	/shifts/:id	Remover turno
GET	/suggestions?branchId=	Última sugestão IA da filial
POST	/suggestions/generate	Gerar nova sugestão IA
PUT	/suggestions/:id/apply	Aplicar sugestão (importa turnos)
PUT	/suggestions/:id/dismiss	Dispensar sugestão
GET	/availability	Listar disponibilidade da equipe
POST	/availability	Cadastrar disponibilidade
DELETE	/availability/:id	Remover disponibilidade
GET	/demand-heatmap	Heatmap de tráfego histórico
GET	/labor-cost	Resumo de custo de mão de obra

---

Backend

Arquivo	Descrição
backend/src/scheduling/scheduling.module.ts	Módulo NestJS
backend/src/scheduling/scheduling.controller.ts	Controller REST
backend/src/scheduling/staffing-suggestions.service.ts	Geração de sugestões via IA
backend/src/scheduling/schemas/staffing-suggestion.schema.ts	Schema de sugestões
backend/src/scheduling/schemas/staff-availability.schema.ts	Schema de disponibilidade
backend/src/scheduling/schemas/schedule-shift.schema.ts	Schema de turno

---

Relacionados

• Gestão de Filiais
• Assistente IA