Skip to main content

Módulo 03: Hierarquia de Times

Status: Rascunho Inicial

1. Contratos de API (RESTful)​

1.1 Times​

GET  /api/times/meu-time
  Return: { time: { id, gestor, nivel }, membros: [{ id, nome, nivel, producao_mes }] }

GET  /api/times/{id}
  Return: { ...dados do time + membros diretos }

GET  /api/times/{id}/arvore
  Return: { ...time + subárvore completa (recursiva, até N níveis) }

POST /api/convites
  Body: { email?, expira_em?, time_id }
  Return: { token, link_completo, expira_em }

GET  /api/convites/{token}/validar
  Return: { valido: bool, gestor_nome, time_nome, nivel_resultante }

1.2 Hierarquia & Movimentação​

GET  /api/hierarquia/arvore
  Query: ?nivel_max=5&status=ATIVO
  Return: { arvore completa do tenant (apenas Admin/Gerente) }

GET  /api/hierarquia/meu-ramo
  Return: { caminho do usuário logado até o N1 }

PATCH /api/usuarios/{id}/transferir
  Body: { novo_time_id, motivo }
  Return: { usuario_id, novo_time_id, historico_id }
  Auth: Admin

1.3 Consultas de Produção em Cascata​

GET  /api/producao/minha
  Query: ?periodo=2026-06
  Return: { vendas_proprias: N, vendas_time: N, total_cascata: N }

GET  /api/producao/time/{time_id}
  Query: ?nivel_max=3&periodo=2026-06
  Return: { producao_por_nivel: [{ nivel: 1, total: N }, ...] }

2. Schemas de Banco de Dados​

2.1 Campos Hierárquicos na tabela Usuário​

{
  "id": "uuid",
  "parent_id": "uuid | null",
  "time_id": "uuid | null",
  "nivel": "integer (calculado, não fixo)",
  "e_gestor": "boolean"
}

2.2 Entidade Time​

{
  "id": "uuid",
  "tenant_id": "uuid",
  "nome": "string",
  "gestor_id": "uuid",
  "nivel_gestor": "integer",
  "total_membros_diretos": "integer",
  "total_subarvore": "integer"
}

2.3 Log de Auditoria Hierárquica​

{
  "id": "uuid",
  "usuario_id": "uuid",
  "time_origem_id": "uuid",
  "time_destino_id": "uuid",
  "motivo": "string",
  "executado_por": "uuid"
}

3. Segurança e Boas Práticas (Performance DB)​

  • Nível Calculado: A coluna Nível (N1, N2...) é dinamicamente calculada com base na profundidade (Closure Table ou CTEs Recursivas no PostgreSQL).
  • Para evitar sobrecarga de consultas (traversing the tree), o sistema usará estratégias de Materialized Paths para as consultas em cascata da diretoria.