ranking/README.md

Sistema de Ranking de Consultores CAPES

Sistema completo de ranking de consultores CAPES baseado na Minuta Técnica, desenvolvido com arquitetura DDD (Domain-Driven Design).

Arquitetura

Backend (Python + FastAPI + DDD)

• Domain Layer: Entities, Value Objects, Domain Services
• Application Layer: Use Cases, DTOs
• Infrastructure Layer: Repositories, Elasticsearch Client, Oracle Client
• Interface Layer: FastAPI Routes, Schemas, Dependencies

Frontend (React + Vite)

• Interface moderna baseada no layout do HTML de referência
• Componentes reutilizáveis
• Integração com API via Axios
• Design responsivo

Estrutura do Projeto

ranking/
├── backend/
│   ├── src/
│   │   ├── domain/
│   │   │   ├── entities/
│   │   │   │   └── consultor.py
│   │   │   ├── value_objects/
│   │   │   │   ├── periodo.py
│   │   │   │   └── pontuacao.py
│   │   │   ├── repositories/
│   │   │   │   └── consultor_repository.py
│   │   │   └── services/
│   │   │       └── calculador_pontuacao.py
│   │   ├── application/
│   │   │   ├── dtos/
│   │   │   │   └── consultor_dto.py
│   │   │   └── use_cases/
│   │   │       ├── obter_ranking.py
│   │   │       └── obter_consultor.py
│   │   ├── infrastructure/
│   │   │   ├── elasticsearch/
│   │   │   │   └── client.py
│   │   │   ├── oracle/
│   │   │   │   └── client.py
│   │   │   └── repositories/
│   │   │       └── consultor_repository_impl.py
│   │   └── interface/
│   │       ├── api/
│   │       │   ├── app.py
│   │       │   ├── routes.py
│   │       │   ├── config.py
│   │       │   └── dependencies.py
│   │       └── schemas/
│   │           └── consultor_schema.py
│   ├── pyproject.toml
│   ├── Dockerfile
│   └── .env.example
│
├── frontend/
│   ├── src/
│   │   ├── components/
│   │   │   ├── Header.jsx
│   │   │   ├── Header.css
│   │   │   ├── ConsultorCard.jsx
│   │   │   └── ConsultorCard.css
│   │   ├── services/
│   │   │   └── api.js
│   │   ├── App.jsx
│   │   ├── App.css
│   │   ├── main.jsx
│   │   └── index.css
│   ├── package.json
│   ├── vite.config.js
│   ├── Dockerfile
│   └── nginx.conf
│
├── docker-compose.yml
├── .env.example
├── .gitignore
└── README.md

Componentes de Pontuação

Componente A: Coordenação CAPES (máx 450 pts)

• CA: 200 base + 100 tempo + 100 áreas + 20 retorno + 30 bônus = 450
• CAJ: 150 base + 80 tempo + 100 áreas + 20 retorno + 20 bônus = 370
• CAJ-MP: 120 base + 60 tempo + 100 áreas + 20 retorno + 15 bônus = 315
• CAM: 100 base + 50 tempo + 100 áreas + 20 retorno + 10 bônus = 280

Componente B: Coordenação de Programa PPG (máx 180 pts)

• Base: 70 pts
• Tempo: 5 pts/ano (máx 50 pts)
• Programas extras: 20 pts/programa (máx 40 pts)
• Bônus ativo: 20 pts

Componente C: Consultoria (máx 230 pts)

• Ativo: 150 pts | Histórico: 100 pts
• Tempo: 5 pts/ano (máx 50 pts)
• Eventos: 2 pts/evento (máx 20 pts)
• Responsável: 5 pts/vez (máx 25 pts)
• Áreas extras: 10 pts/área (máx 30 pts)

Componente D: Premiações (máx 180 pts)

• Premiação: 60 pts
• Avaliação: 40 pts
• Inscrição: 20 pts

Requisitos

• Python 3.11+
• Node.js 18+
• Docker e Docker Compose (opcional)
• Acesso ao Elasticsearch (ATUACAPES)
• Acesso ao Oracle (SUCUPIRA_PAINEL)

Setup Local

Backend

1. Entre no diretório do backend:

cd backend

2. Crie ambiente virtual e instale dependências:

poetry install

3. Configure as variáveis de ambiente:

cp .env.example .env

4. Edite .env com suas credenciais:

ES_URL=http://seu-elasticsearch:9200
ES_INDEX=atuacapes
ES_USER=seu_usuario_elastic
ES_PASSWORD=sua_senha_elastic
ORACLE_USER=seu_usuario
ORACLE_PASSWORD=sua_senha
ORACLE_DSN=host:1521/service_name

5. Execute o backend:

poetry run python src/main.py

A API estará disponível em http://localhost:8000

Frontend

1. Entre no diretório do frontend:

cd frontend

2. Instale dependências:

npm install

3. Execute em modo desenvolvimento:

npm run dev

O frontend estará disponível em http://localhost:5173

Setup com Docker

1. Configure as variáveis de ambiente:

cp .env.example .env

2. Edite .env com suas credenciais

3. Execute com Docker Compose:

docker-compose up -d

• Backend: http://localhost:8000
• Frontend: http://localhost

Endpoints da API

GET /api/v1/ranking

Retorna o ranking resumido de consultores.

Query Parameters:

• limite (int, default=100): Limite de consultores
• offset (int, default=0): Offset para paginação
• componente (str, optional): Filtrar por componente (a, b, c, d)

GET /api/v1/ranking/detalhado

Retorna o ranking completo com todos os detalhes.

Query Parameters:

• limite (int, default=100): Limite de consultores
• componente (str, optional): Filtrar por componente (a, b, c, d)

GET /api/v1/consultor/{id_pessoa}

Retorna detalhes completos de um consultor específico.

GET /api/v1/health

Health check da API.

Fontes de Dados

Elasticsearch (ATUACAPES)

• Índice: atuacapes__1763197236
• Campos: id, dadosPessoais, atuacoes
• Tipos de atuação:
  • Coordenação de Área de Avaliação
  • Consultor
  • Premiação Prêmio
  • Avaliação Prêmio
  • Inscrição Prêmio

Oracle (SUCUPIRA_PAINEL)

• Tabela: VM_COORDENADOR
• JOIN com: VM_PROGRAMA_SUCUPIRA, VM_AREA_CONHECIMENTO, VM_AREA_AVALIACAO
• 29.546 registros (4.150 ativos, 25.396 históricos)

Documentação da API

Após iniciar o backend, acesse:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Desenvolvimento

Testes

cd backend
poetry run pytest

Linting

poetry run black src/
poetry run ruff check src/

Build para Produção

Backend:

docker build -t ranking-capes-backend ./backend

Frontend:

cd frontend
npm run build

Referências

• Documentação dos critérios: .claude/rules/ranking-consultores-capes.md
• Queries e mapeamentos: .claude/rules/ranking-queries-elasticsearch.md