Skip to content
This repository was archived by the owner on Feb 5, 2026. It is now read-only.

Latest commit

 

History

History
255 lines (219 loc) · 12.9 KB

API_DOCUMENTATION.md

File metadata and controls

255 lines (219 loc) · 12.9 KB

Documentação de Integração API - Sistema SIGEP

Este documento mapeia a integração entre o frontend React e o backend Go API do Sistema de Gestão de Pessoas (SIGEP).

Configuração Base

  • Frontend: React + TypeScript (Vite)
  • Backend: Go + Gin Framework
  • Base URL: Configurável via VITE_API_BASE_URL
  • Autenticação: Bearer Token (desenvolvimento: mock-token-for-testing)
  • Banco de Dados: Cloud Firestore
  • Projeto GCP: gestao-de-pessoas-v2

Mapeamento Frontend → Backend

Funcionalidade Interface (Frontend) Método HTTP Endpoint (Backend) Status Descrição
MÓDULO CARGOS
Listar Cargos Cargos.tsx via CargosController GET /api/cargos/ ✅ ATIVO Lista paginada de cargos com filtros
Listar Cargos Ativos PessoaForm.tsx via useCargos GET /api/cargos/?ativo=true ✅ ATIVO Dropdown de cargos ativos para formulários
Buscar Cargo por ID CargoForm.tsx via CargosController GET /api/cargos/:id ✅ ATIVO Carregamento de dados para edição
Criar Cargo CargoForm.tsx via CargosController POST /api/cargos/ ✅ ATIVO Criação de novo cargo
Atualizar Cargo CargoForm.tsx via CargosController PUT /api/cargos/:id ✅ ATIVO Atualização completa de cargo
Excluir Cargo Cargos.tsx via CargosController DELETE /api/cargos/:id ✅ ATIVO Inativação lógica do cargo
MÓDULO SERVIDORES
Listar Servidores Pessoas.tsx via ServidoresController GET /api/servidores/ ✅ ATIVO Lista paginada com filtros
Buscar por CPF PessoaForm.tsx via ServidoresController GET /api/servidores/search?cpf={cpf} ✅ ATIVO Validação de CPF único
Buscar Servidor por ID PessoaForm.tsx via ServidoresController GET /api/servidores/:id ✅ ATIVO Carregamento para edição
Criar Servidor PessoaForm.tsx via ServidoresController POST /api/servidores/ ✅ ATIVO Criação de novo servidor
Atualizar Servidor PessoaForm.tsx via ServidoresController PUT /api/servidores/:id ✅ ATIVO Atualização completa
Atualizar Status Pessoas.tsx via ServidoresController PATCH /api/servidores/:id/status ✅ ATIVO Mudança de status apenas
Excluir Servidor Pessoas.tsx via ServidoresController DELETE /api/servidores/:id ✅ ATIVO Inativação lógica
Verificar Nepotismo PessoaForm.tsx via ServidoresController POST /api/servidores/verificar-nepotismo ✅ ATIVO Validação legal de parentesco
Upload de Documento FileUpload.tsx via ServidoresController POST /api/servidores/:id/documentos ✅ ATIVO Upload de arquivos do servidor
Listar Documentos Pessoas.tsx via ServidoresController GET /api/servidores/:id/documentos ✅ ATIVO Documentos do servidor
Excluir Documento Pessoas.tsx via ServidoresController DELETE /api/servidores/:id/documentos/:docId ✅ ATIVO Remoção de documento
MÓDULO ÓRGÃOS
Listar Órgãos Orgaos.tsx via OrgaosControllerNew GET /api/orgaos/ ✅ ATIVO Lista completa de órgãos
Buscar Órgão por ID OrgaoForm.tsx via OrgaosControllerNew GET /api/orgaos/:id ✅ ATIVO Dados para edição
Estrutura Hierárquica Orgaos.tsx via OrgaosControllerNew GET /api/orgaos/hierarchy ✅ ATIVO Árvore hierárquica completa
Estatísticas Órgãos Dashboard.tsx via OrgaosControllerNew GET /api/orgaos/stats ✅ ATIVO Métricas para dashboard
Órgãos Filhos OrgaoForm.tsx via OrgaosControllerNew GET /api/orgaos/filhos/:paiId ✅ ATIVO Hierarquia específica
Criar Órgão OrgaoForm.tsx via OrgaosControllerNew POST /api/orgaos/ ✅ ATIVO Criação com hierarquia automática
Atualizar Órgão OrgaoForm.tsx via OrgaosControllerNew PUT /api/orgaos/:id ✅ ATIVO Atualização com recálculo hierárquico
Excluir Órgão Orgaos.tsx via OrgaosControllerNew DELETE /api/orgaos/:id ✅ ATIVO Validação de órgãos filhos
MÓDULO GEOCODIFICAÇÃO
Buscar Coordenadas LatLngMapField.tsx via direto GET /api/geocoding/?address={address} ✅ ATIVO Conversão endereço → lat/lng
MÓDULO DOCUMENTOS
Gerar Termo de Posse GerarDocumento.tsx via direto POST /api/pdf/termo-posse/:id ✅ ATIVO PDF oficial do termo
MÓDULO SISTEMA
Health Check ApiHealthCheck.tsx via ApiClient GET /health ⚠️ PENDENTE Status da API

Endpoints Planejados para Novos Módulos

Funcionalidade Interface (Frontend) Método HTTP Endpoint (Backend) Prioridade Descrição
MÓDULO AFASTAMENTOS E DESLIGAMENTOS
Listar Afastamentos AfastamentosDesligamentos.tsx GET /api/afastamentos/ 🔥 ALTA Lista paginada de afastamentos
Buscar Afastamentos por Servidor AfastamentosDesligamentos.tsx GET /api/afastamentos/servidor/:id 🔥 ALTA Histórico do servidor
Criar Afastamento AfastamentoForm.tsx POST /api/afastamentos/ 🔥 ALTA Registro de novo afastamento
Atualizar Afastamento AfastamentoForm.tsx PUT /api/afastamentos/:id 🔥 ALTA Alteração de dados
Excluir Afastamento AfastamentosDesligamentos.tsx DELETE /api/afastamentos/:id 🔥 ALTA Cancelamento de afastamento
Upload Atestado AfastamentoForm.tsx POST /api/afastamentos/:id/documento 🔥 ALTA Anexar documento comprobatório
MÓDULO FÉRIAS
Listar Férias Ferias.tsx GET /api/ferias/ 🔥 ALTA Lista de programações
Buscar Férias por Servidor Ferias.tsx GET /api/ferias/servidor/:id 🔥 ALTA Histórico de férias
Programar Férias FeriasForm.tsx POST /api/ferias/ 🔥 ALTA Nova programação
Atualizar Férias FeriasForm.tsx PUT /api/ferias/:id 🔥 ALTA Alteração de período
Cancelar Férias Ferias.tsx DELETE /api/ferias/:id 🔥 ALTA Cancelamento
Calendário de Férias Ferias.tsx GET /api/ferias/calendario/:ano 🟡 MÉDIA Visão do ano
MÓDULO GESTÃO DE DOCUMENTOS
Listar Documentos GestaoDocumentos.tsx GET /api/documentos/ 🔥 ALTA Repositório completo
Buscar por Categoria GestaoDocumentos.tsx GET /api/documentos/categoria/:categoria 🔥 ALTA Filtro por tipo
Buscar por Tags GestaoDocumentos.tsx GET /api/documentos/tags/:tags 🟡 MÉDIA Busca por etiquetas
Criar Documento DocumentoGeralForm.tsx POST /api/documentos/ 🔥 ALTA Upload e cadastro
Atualizar Documento DocumentoGeralForm.tsx PUT /api/documentos/:id 🔥 ALTA Edição de metadados
Excluir Documento GestaoDocumentos.tsx DELETE /api/documentos/:id 🔥 ALTA Remoção segura
Download Documento GestaoDocumentos.tsx GET /api/documentos/:id/download 🔥 ALTA Acesso ao arquivo
MÓDULO AUTORIZAÇÕES
Listar Pendências Autorizacoes.tsx GET /api/autorizacoes/pendentes 🔥 ALTA Fila de aprovações
Aprovar Autorizacoes.tsx POST /api/autorizacoes/:id/aprovar 🔥 ALTA Aprovação
Rejeitar Autorizacoes.tsx POST /api/autorizacoes/:id/rejeitar 🔥 ALTA Rejeição com motivo
Histórico Autorizacoes.tsx GET /api/autorizacoes/historico 🟡 MÉDIA Log de decisões
MÓDULO GESTÃO DO CONHECIMENTO
Listar Treinamentos GestaoConhecimento.tsx GET /api/treinamentos/ 🟡 MÉDIA Catálogo de cursos
Inscrever Servidor GestaoConhecimento.tsx POST /api/treinamentos/:id/inscricao 🟡 MÉDIA Matrícula em curso
Certificados GestaoConhecimento.tsx GET /api/certificados/servidor/:id 🟡 MÉDIA Histórico de certificações
MÓDULO ANÁLISE E INDICADORES
Dashboard Executivo AnaliseIndicadores.tsx GET /api/dashboard/indicadores 🟡 MÉDIA Métricas consolidadas
Relatório Turnover AnaliseIndicadores.tsx GET /api/indicadores/turnover 🔵 BAIXA Taxa de rotatividade
Relatório Absenteísmo AnaliseIndicadores.tsx GET /api/indicadores/absenteismo 🔵 BAIXA Índices de ausência

Status das Integrações

✅ Implementado e Funcional

  • Cargos: CRUD completo integrado
  • Servidores: CRUD + funcionalidades especiais (nepotismo, documentos)
  • Órgãos: CRUD + hierarquia automática
  • Geocodificação: Integração Google Maps
  • Documentos: Geração de PDFs

⚠️ Pendente de Implementação

  • Health Check: Endpoint não implementado no backend
  • Relatórios: Geração via BigQuery (planejado Fase 3)
  • Backup: Endpoints não implementados
  • Busca Inteligente: IA com Vertex AI (planejado Fase 4)

🔄 Usando Dados Locais (Não Integrado)

  • Seleções: SelecoesController usa models locais
  • Usuários: AuthController usa Firebase (comentado)
  • Templates: TemplatesController usa dados simulados

Tokens de Desenvolvimento

Para testes durante desenvolvimento, use um dos tokens válidos:

# Administrador
Authorization: Bearer admin-test-token

# Gestor  
Authorization: Bearer gestor-test-token

# Usuário comum
Authorization: Bearer user-test-token

# Mock genérico
Authorization: Bearer mock-token-for-testing

Configuração de Ambiente

Frontend (.env)

VITE_API_BASE_URL=http://localhost:8080/api

Backend

PORT=8080
GCP_PROJECT_ID=gestao-de-pessoas-v2
GOOGLE_APPLICATION_CREDENTIALS=path/to/credentials.json

Estruturas de Dados

Cargo

interface Cargo {
  id: string;
  nome: string;           // obrigatório
  nivel: string;          // obrigatório  
  salario: number;        // obrigatório, > 0
  carga_horaria: number;  // obrigatório, > 0
  tipo_vinculo: string;   // obrigatório
  descricao?: string;
  ativo?: boolean;        // padrão: true
  created_at?: string;
  updated_at?: string;
}

Servidor

interface Servidor {
  id: string;
  nome: string;              // obrigatório
  cpf: string;              // obrigatório, único
  email?: string;
  telefone?: string;
  endereco?: string;
  cargo_id: string;         // FK para Cargo
  orgao_id: string;         // FK para Orgao
  data_admissao: string;    // padrão: hoje
  tipo_vinculo: 'efetivo' | 'temporario' | 'comissionado' | 'terceirizado' | 'credenciado' | 'estagiario';
  status: 'ATIVO' | 'INATIVO' | 'AFASTADO' | 'APOSENTADO';
  data_demissao?: string;
  ativo?: boolean;          // padrão: true
  created_at?: string;
  updated_at?: string;
}

Órgão

interface Orgao {
  id: string;
  nome: string;             // obrigatório
  nome_gestor: string;      // obrigatório
  cpf_gestor: string;       // obrigatório
  sigla?: string;
  cnpj?: string;            // único se informado
  endereco?: string;
  telefone?: string;
  email?: string;
  pai_id?: string;          // FK para pai na hierarquia
  nivel?: number;           // calculado automaticamente
  caminho_completo?: string; // calculado automaticamente
  ativo?: boolean;          // padrão: true
  created_at?: string;
  updated_at?: string;
}

Funcionalidades Críticas

🔥 Verificação de Nepotismo

Endpoint: POST /api/servidores/verificar-nepotismo

Funcionalidade essencial para conformidade legal no setor público brasileiro.

Payload:

{
  "servidorNome": "João Silva",
  "servidorCPF": "123.456.789-00", 
  "conjugeCPF": "987.654.321-00",
  "cpfMae": "555.666.777-88",
  "cpfPai": "444.333.222-11"
}

🏢 Hierarquia de Órgãos

  • Níveis automáticos: Calculados pela API
  • Caminho completo: Gerado automaticamente
  • Integridade: Não permite exclusão de órgãos com filhos

📄 Geração de Documentos

  • Templates HTML: Conversion para PDF
  • Dados dinâmicos: Preenchimento automático
  • Conformidade legal: Documentos oficiais

Próximos Passos

Fase 2 (Em Andamento)

  1. Implementar endpoint /health no backend
  2. Migrar SelecoesController para usar API real
  3. Implementar upload de arquivos completo
  4. Conectar AuthController ao Firebase

Fase 3 (Planejado)

  1. Integração com BigQuery para relatórios
  2. Pipeline de dados Firestore → BigQuery
  3. Endpoints de relatórios complexos

Fase 4 (Planejado)

  1. Busca inteligente com Vertex AI
  2. Chatbot especialista
  3. Análise de documentos com IA

Última Atualização: Janeiro 2025
Versão: 1.0
Responsável: Equipe de Desenvolvimento SIGEP