446 lines
13 KiB
Markdown
446 lines
13 KiB
Markdown
# 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, Jobs, Mappers, Services
|
||
- **Infrastructure Layer**: Repositories, Elasticsearch Client, Oracle Client, Cache
|
||
- **Interface Layer**: FastAPI Routes, Schemas, Dependencies
|
||
|
||
### Frontend (React + Vite)
|
||
- Interface moderna com componentes reutilizáveis
|
||
- Comparação lado a lado de consultores
|
||
- Sugestão de consultores por tema
|
||
- Exportação de fichas em PDF
|
||
- Integração com API via Axios
|
||
- Design responsivo
|
||
|
||
## Estrutura do Projeto
|
||
|
||
```
|
||
ranking/
|
||
├── backend/
|
||
│ ├── src/
|
||
│ │ ├── domain/
|
||
│ │ │ ├── entities/
|
||
│ │ │ │ ├── consultor.py
|
||
│ │ │ │ └── consultor_ranking.py
|
||
│ │ │ ├── value_objects/
|
||
│ │ │ │ ├── criterios_pontuacao.py
|
||
│ │ │ │ ├── periodo.py
|
||
│ │ │ │ └── pontuacao.py
|
||
│ │ │ ├── repositories/
|
||
│ │ │ │ └── consultor_repository.py
|
||
│ │ │ └── services/
|
||
│ │ │ └── calculador_pontuacao.py
|
||
│ │ ├── application/
|
||
│ │ │ ├── dtos/
|
||
│ │ │ │ └── consultor_dto.py
|
||
│ │ │ ├── jobs/
|
||
│ │ │ │ ├── job_status.py
|
||
│ │ │ │ ├── processar_ranking.py
|
||
│ │ │ │ ├── popular_componente_b_job.py
|
||
│ │ │ │ └── scheduler.py
|
||
│ │ │ ├── mappers/
|
||
│ │ │ │ └── ranking_mapper.py
|
||
│ │ │ ├── services/
|
||
│ │ │ │ └── pdf_service.py
|
||
│ │ │ └── use_cases/
|
||
│ │ │ ├── obter_ranking.py
|
||
│ │ │ └── obter_consultor.py
|
||
│ │ ├── infrastructure/
|
||
│ │ │ ├── cache/
|
||
│ │ │ │ └── ranking_cache.py
|
||
│ │ │ ├── elasticsearch/
|
||
│ │ │ │ └── client.py
|
||
│ │ │ ├── oracle/
|
||
│ │ │ │ ├── client.py
|
||
│ │ │ │ └── ranking_repository.py
|
||
│ │ │ ├── repositories/
|
||
│ │ │ │ └── consultor_repository_impl.py
|
||
│ │ │ └── ranking_store.py
|
||
│ │ └── interface/
|
||
│ │ ├── api/
|
||
│ │ │ ├── app.py
|
||
│ │ │ ├── routes.py
|
||
│ │ │ ├── config.py
|
||
│ │ │ └── dependencies.py
|
||
│ │ └── schemas/
|
||
│ │ ├── consultor_schema.py
|
||
│ │ └── ranking_schema.py
|
||
│ ├── scripts/
|
||
│ ├── sql/
|
||
│ ├── static/
|
||
│ ├── tests/
|
||
│ ├── requirements.txt
|
||
│ ├── Dockerfile
|
||
│ └── .env.example
|
||
│
|
||
├── frontend/
|
||
│ ├── src/
|
||
│ │ ├── components/
|
||
│ │ │ ├── Header.jsx
|
||
│ │ │ ├── ConsultorCard.jsx
|
||
│ │ │ ├── CompararModal.jsx
|
||
│ │ │ ├── FiltroSelos.jsx
|
||
│ │ │ ├── BlocoCriteriosModal.jsx
|
||
│ │ │ ├── RawDataModal.jsx
|
||
│ │ │ └── SugerirConsultores.jsx
|
||
│ │ ├── services/
|
||
│ │ │ └── api.js
|
||
│ │ ├── App.jsx
|
||
│ │ ├── App.css
|
||
│ │ ├── main.jsx
|
||
│ │ └── index.css
|
||
│ ├── package.json
|
||
│ ├── vite.config.js
|
||
│ └── Dockerfile
|
||
│
|
||
├── scripts/
|
||
├── tools/
|
||
├── docker-compose.yml
|
||
├── .env.example
|
||
├── .gitignore
|
||
└── README.md
|
||
```
|
||
|
||
## Critérios de Pontuação V2
|
||
|
||
> Baseado na Minuta Técnica - Ranking AtuaCAPES v2.0
|
||
|
||
### Bloco A: Coordenação CAPES
|
||
|
||
| Código | Função | Base | Tempo | Teto Tempo | Bônus Atualidade | Bônus Retorno | Teto |
|
||
|--------|--------|------|-------|------------|------------------|---------------|------|
|
||
| **CA** | Coordenador de Área | 200 | 10 pts/ano | 100 | +30 | +20 | 450 |
|
||
| **CAJ** | Coordenador Adjunto | 150 | 8 pts/ano | 80 | +20 | +15 | 370 |
|
||
| **CAJ_MP** | Coord. Adjunto MP | 120 | 6 pts/ano | 60 | +15 | +10 | 315 |
|
||
| **CAM** | Câmara Temática | 100 | 5 pts/ano | 50 | +20 | +10 | 280 |
|
||
|
||
**Regras:**
|
||
- Tempo = anos completos × multiplicador (respeitando teto)
|
||
- Bônus Atualidade: apenas se mandato vigente
|
||
- Bônus Retorno: se houve retorno após período de inatividade
|
||
|
||
### Bloco B: Coordenação de Programa PPG (máx 180 pts)
|
||
|
||
| Critério | Pontuação |
|
||
|----------|-----------|
|
||
| Base | 70 pts |
|
||
| Tempo | 5 pts/ano (máx 50) |
|
||
| Programas extras | 20 pts/programa (máx 40) |
|
||
| Bônus por nota PPG | até 20 pts |
|
||
|
||
> **Nota**: Bloco B = 0 no V1 (dados incompletos no AtuaCAPES)
|
||
|
||
### Bloco C: Consultoria (máx 230 pts)
|
||
|
||
| Código | Situação | Base | Tempo | Teto Tempo | Continuidade 8a+ | Retorno | Teto |
|
||
|--------|----------|------|-------|------------|------------------|---------|------|
|
||
| **CONS_ATIVO** | Ativo | 150 | 5 pts/ano | 50 | +20 | +15 | 230 |
|
||
| **CONS_HIST** | Histórico | 100 | 5 pts/ano | 50 | +20 | - | 230 |
|
||
| **CONS_FALECIDO** | Falecido | 100 | - | - | +20 | - | 230 |
|
||
|
||
**Regras:**
|
||
- Bônus Continuidade: aplicado se >= 8 anos consecutivos
|
||
- Bônus Retorno: apenas para CONS_ATIVO com reativação
|
||
- CONS_FALECIDO não pontua por tempo
|
||
|
||
### Bloco D: Premiações, Avaliações e Participações
|
||
|
||
#### Inscrições
|
||
|
||
| Código | Descrição | Base | Teto |
|
||
|--------|-----------|------|------|
|
||
| **INSC_AUTOR** | Autoinscrição | 10 | 20 |
|
||
| **INSC_INST** | Inscrição Institucional | 30 | 60 |
|
||
|
||
#### Avaliação de Comissão
|
||
|
||
| Código | Descrição | Base | Teto |
|
||
|--------|-----------|------|------|
|
||
| **AVAL_COMIS_PREMIO** | Avaliador Prêmio | 30 | 60 |
|
||
| **AVAL_COMIS_GP** | Avaliador Grande Prêmio | 50 | 80 |
|
||
|
||
#### Coordenação de Comissão
|
||
|
||
| Código | Descrição | Base | Teto |
|
||
|--------|-----------|------|------|
|
||
| **COORD_COMIS_PREMIO** | Coord. Comissão Prêmio | 50 | 100 |
|
||
| **COORD_COMIS_GP** | Coord. Comissão GP | 60 | 120 |
|
||
|
||
#### Premiações Recebidas
|
||
|
||
| Código | Descrição | Base | Teto |
|
||
|--------|-----------|------|------|
|
||
| **PREMIACAO** | Grande Prêmio CAPES | 100 | 180 |
|
||
| **PREMIACAO_GP** | Prêmio CAPES de Tese | 50 | 60 |
|
||
| **MENCAO** | Menção Honrosa | 30 | 30 |
|
||
|
||
#### Bolsas CNPq
|
||
|
||
| Código | Descrição | Base | Teto |
|
||
|--------|-----------|------|------|
|
||
| **BOL_BPQ_SUPERIOR** | Bolsa PQ nível 1A/1B/1C | 30 | 60 |
|
||
| **BOL_BPQ_INTERMEDIARIO** | Bolsa PQ nível 1D/2 | 50 | 100 |
|
||
|
||
#### Participações
|
||
|
||
| Código | Descrição | Base | Teto |
|
||
|--------|-----------|------|------|
|
||
| **EVENTO** | Participação em Evento | 1 | 5 |
|
||
| **PROJ** | Participação em Projeto | 10 | 40 |
|
||
|
||
#### Orientações
|
||
|
||
| Código | Descrição | Base | Teto |
|
||
|--------|-----------|------|------|
|
||
| **ORIENT_POS_DOC** | Orientação Pós-Doc | 15 | 100 |
|
||
| **ORIENT_TESE** | Orientação Tese | 10 | 50 |
|
||
| **ORIENT_DISS** | Orientação Dissertação | 5 | 25 |
|
||
| **CO_ORIENT_POS_DOC** | Co-Orientação Pós-Doc | 7 | 35 |
|
||
| **CO_ORIENT_TESE** | Co-Orientação Tese | 5 | 25 |
|
||
| **CO_ORIENT_DISS** | Co-Orientação Dissertação | 3 | 15 |
|
||
|
||
#### Bancas
|
||
|
||
| Código | Descrição | Base | Teto |
|
||
|--------|-----------|------|------|
|
||
| **MB_BANCA_POS_DOC** | Banca Pós-Doc | 3 | 15 |
|
||
| **MB_BANCA_TESE** | Banca Tese | 3 | 15 |
|
||
| **MB_BANCA_DISS** | Banca Dissertação | 2 | 10 |
|
||
|
||
### Bloco E: Docência e Lattes
|
||
|
||
Pontuação baseada em atividades de docência e informações do currículo Lattes.
|
||
|
||
### Selos Visuais (sem pontuação)
|
||
|
||
Indicadores visuais que aparecem no card do consultor:
|
||
|
||
| Selo | Descrição | Ícone |
|
||
|------|-----------|-------|
|
||
| Coord. PPG | Coordenador de Programa | 🎓 |
|
||
| Presid. Câmara | Presidente de Câmara Temática | 🏛️ |
|
||
| Bolsista PQ | Bolsista de Produtividade CNPq | 🔬 |
|
||
| Grande Prêmio | Vencedor do Grande Prêmio | 🏆 |
|
||
| Prêmio | Vencedor de Prêmio | 🥇 |
|
||
| Menção Honrosa | Menção Honrosa | 🎖️ |
|
||
| Orientações | Orient. Pós-Doc/Tese/Diss | 📚📖📝 |
|
||
| Co-Orientações | Co-Orient. Pós-Doc/Tese/Diss | 📚📖📝 |
|
||
|
||
### Fórmula de Cálculo
|
||
|
||
```
|
||
Score_Atuação = min(Base + Tempo + Bônus, Teto)
|
||
Score_Total = Bloco_A + Bloco_B + Bloco_C + Bloco_D + Bloco_E
|
||
```
|
||
|
||
## 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
|
||
python -m venv venv
|
||
source venv/bin/activate
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
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_LOCAL_USER=seu_usuario
|
||
ORACLE_LOCAL_PASSWORD=sua_senha
|
||
ORACLE_LOCAL_DSN=host:1521/service_name
|
||
```
|
||
|
||
5. Execute o backend:
|
||
```bash
|
||
python -m uvicorn src.interface.api.app:app --host 0.0.0.0 --port 8000 --reload
|
||
```
|
||
|
||
A API estará disponível em `http://localhost:8000`
|
||
|
||
### 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. Crie a rede compartilhada (apenas uma vez):
|
||
```bash
|
||
docker network create shared_network
|
||
```
|
||
|
||
2. Configure as variáveis de ambiente:
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
3. Edite `.env` com suas credenciais
|
||
|
||
4. Execute com Docker Compose:
|
||
```bash
|
||
docker-compose up -d
|
||
```
|
||
|
||
- Backend: `http://localhost:8010`
|
||
- Frontend: `http://localhost:5173`
|
||
- Oracle local: `localhost:1521`
|
||
|
||
## Endpoints da API
|
||
|
||
### Ranking
|
||
|
||
| Método | Endpoint | Descrição |
|
||
|--------|----------|-----------|
|
||
| GET | `/api/v1/ranking` | Ranking resumido |
|
||
| GET | `/api/v1/ranking/paginado` | Ranking paginado com detalhes |
|
||
| GET | `/api/v1/ranking/detalhado` | Ranking completo |
|
||
| GET | `/api/v1/ranking/busca?nome=X` | Busca por nome |
|
||
| GET | `/api/v1/ranking/estatisticas` | Estatísticas do ranking |
|
||
| GET | `/api/v1/ranking/status` | Status do job de processamento |
|
||
| GET | `/api/v1/ranking/selos` | Lista de selos disponíveis |
|
||
| GET | `/api/v1/ranking/posicao/{id}` | Posição de um consultor |
|
||
| POST | `/api/v1/ranking/processar` | Dispara reprocessamento |
|
||
|
||
### Consultor
|
||
|
||
| Método | Endpoint | Descrição |
|
||
|--------|----------|-----------|
|
||
| GET | `/api/v1/consultor/{id}` | Detalhes do consultor |
|
||
| GET | `/api/v1/consultor/{id}/raw` | Documento ES completo |
|
||
| GET | `/api/v1/consultor/{id}/lattes` | Dados do Lattes |
|
||
| GET | `/api/v1/consultor/{id}/pdf` | Exportar ficha em PDF |
|
||
|
||
### Sugestões
|
||
|
||
| Método | Endpoint | Descrição |
|
||
|--------|----------|-----------|
|
||
| GET | `/api/v1/consultores/sugerir?tema=X` | Sugerir consultores por tema |
|
||
| GET | `/api/v1/consultores/areas-avaliacao` | Listar áreas de avaliação |
|
||
| POST | `/api/v1/equipe/pdf` | Gerar PDF de equipe |
|
||
|
||
### Utilitários
|
||
|
||
| Método | Endpoint | Descrição |
|
||
|--------|----------|-----------|
|
||
| GET | `/api/v1/health` | Health check |
|
||
| GET | `/` | Info da API |
|
||
|
||
## Fontes de Dados
|
||
|
||
### Elasticsearch (ATUACAPES)
|
||
- Índice: `atuacapes`
|
||
- Campos: `id`, `dadosPessoais`, `atuacoes`, `idiomas`, `formacoes`, `titulacoes`, `identificadorLattes`
|
||
- Tipos de atuação:
|
||
- Coordenação de Área de Avaliação
|
||
- Histórico de Coordenação de Área de Avaliação
|
||
- Consultor
|
||
- Histórico de Consultoria
|
||
- Premiação Prêmio
|
||
- Avaliação Prêmio
|
||
- Inscrição Prêmio
|
||
- Docência
|
||
- Orientação
|
||
- Bolsista CNPq
|
||
|
||
### Oracle Local (Ranking)
|
||
- Tabela: `TB_RANKING_CONSULTOR`
|
||
- Armazena ranking pré-calculado para performance
|
||
- ~350.000 consultores
|
||
|
||
### Oracle CAPES (SUCUPIRA_PAINEL)
|
||
- Tabela: `VM_COORDENADOR`
|
||
- JOIN com: `VM_PROGRAMA_SUCUPIRA`, `VM_AREA_CONHECIMENTO`, `VM_AREA_AVALIACAO`
|
||
|
||
## Documentação da API
|
||
|
||
Após iniciar o backend, acesse:
|
||
- Swagger UI: `http://localhost:8000/docs`
|
||
- ReDoc: `http://localhost:8000/redoc`
|
||
|
||
## Desenvolvimento
|
||
|
||
### Testes
|
||
```bash
|
||
cd backend
|
||
pytest
|
||
```
|
||
|
||
### Linting
|
||
```bash
|
||
black src/
|
||
ruff check src/
|
||
```
|
||
|
||
### Build para Produção
|
||
|
||
**Backend:**
|
||
```bash
|
||
docker build -t ranking-capes-backend ./backend
|
||
```
|
||
|
||
**Frontend:**
|
||
```bash
|
||
cd frontend
|
||
npm run build
|
||
```
|
||
|
||
## Funcionalidades do Frontend
|
||
|
||
- **Ranking Paginado**: Navegação por páginas com 10-500 registros por página
|
||
- **Busca por Nome**: Localiza consultor e navega para sua posição
|
||
- **Comparação**: Selecione 2 consultores para comparar lado a lado
|
||
- **Sugestão por Tema**: Busca consultores por área de conhecimento/pesquisa
|
||
- **Filtro por Selos**: Filtra por tipos de atuação
|
||
- **Exportação PDF**: Gera ficha individual ou de equipe
|
||
- **Detalhes Expandidos**: Card expansível com todas as atuações
|
||
- **Integração Lattes**: Exibe dados do currículo Lattes
|
||
|
||
## Referências
|
||
|
||
- Documentação dos critérios: `.claude/rules/ranking-consultores-capes.md`
|
||
- Queries e mapeamentos: `.claude/rules/ranking-queries-elasticsearch.md`
|
||
- Queries implementadas: `.claude/rules/ranking-queries-implementadas.md`
|