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

## Setup Local

### Backend

1. Entre no diretório do backend:
```bash
cd backend
```

2. Crie ambiente virtual e instale dependências:
```bash
poetry install
```

3. Configure as variáveis de ambiente:
```bash
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:
```bash
poetry run python src/main.py
```

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

### Frontend

1. Entre no diretório do frontend:
```bash
cd frontend
```

2. Instale dependências:
```bash
npm install
```

3. Execute em modo desenvolvimento:
```bash
npm run dev
```

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

## Setup com Docker

1. Configure as variáveis de ambiente:
```bash
cp .env.example .env
```

2. Edite `.env` com suas credenciais

3. Execute com Docker Compose:
```bash
docker-compose up -d
```

- Backend: `http://localhost:8010`
- 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:8010/docs`
- ReDoc: `http://localhost:8010/redoc`

## Desenvolvimento

### Testes
```bash
cd backend
poetry run pytest
```

### Linting
```bash
poetry run black src/
poetry run ruff check src/
```

### Build para Produção

**Backend:**
```bash
docker build -t ranking-capes-backend ./backend
```

**Frontend:**
```bash
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`