fred/ranking
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add utility scripts and documentation

Browse Source 
- Add TIPOS_ATUACAO_ELASTICSEARCH.md: mapping of ES activity types
- Add TOP_10_RANKING_CAPES.md: sample ranking output documentation
- Add backend/scripts/: utility scripts for analysis and debugging
  - analise_detalhada.py: detailed consultant analysis
  - auditar_ranking.py: ranking audit tool
  - bootstrap_ranking.sh: bootstrap script
  - buscar_consultores_especificos.py: search specific consultants
  - popular_componente_b.py: populate component B
  - top10_ranking.py: generate top 10 ranking
- Add scripts/reload_atuacapes.sh: reload ES index script
This commit is contained in:
Frederico Castro
2025-12-14 21:36:57 -03:00
parent 10d8efc96a
commit 4a98e8b38c
6 changed files with 1508 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

407
TIPOS_ATUACAO_ELASTICSEARCH.md Normal file
View File

@@ -0,0 +1,407 @@
# Tipos de Atuação Disponíveis no Elasticsearch (AtuaCAPES)
> Mapeamento completo dos tipos de atuação encontrados no índice `atuacapes` do Elasticsearch CAPES
## Visão Geral
Este documento lista todos os tipos de atuação (`atuacoes.tipo`) disponíveis no índice Elasticsearch do sistema AtuaCAPES, identificados através da análise do código implementado e da documentação do projeto.
---
## Tipos de Atuação Implementados
### Componente A - Coordenação CAPES
| Tipo | Descrição | Boost | Pontuação Base |
|------|-----------|-------|----------------|
| `Coordenação de Área de Avaliação` | Coordenadores ativos (CA, CAJ, CAJ-MP, CAM) | 10 | 200-100 pts |
| `Histórico de Coordenação de Área de Avaliação` | Coordenadores históricos (mandatos encerrados) | 5 | 200-100 pts |
**Subtipos identificados em `dadosCoordenacaoArea.tipo`:**
- `Coordenador de Área` (CA) - Base: 200 pts
- `Coordenador Adjunto` (CAJ) - Base: 150 pts
- `Coordenador Adjunto de Mestrado Profissionalizante` (CAJ-MP) - Base: 120 pts
- `Coordenador de Câmara Temática` (CAM) - Base: 100 pts
### Componente C - Consultoria
| Tipo | Descrição | Boost | Pontuação Base |
|------|-----------|-------|----------------|
| `Consultor` | Registro de consultoria ativa ou histórica | 2 | 150 pts (ativo) |
| `Histórico de Consultoria` | Consultorias encerradas | 1 | 100 pts (histórico) |
**Valores de `situacaoConsultoria`:**
- `Atividade Contínua` - Consultor Ativo
- `Ativo` - Consultor Ativo
- Outros valores ou com `inativacaoSituacao` preenchido = Histórico
### Componente D - Premiações
| Tipo | Descrição | Boost | Pontuação |
|------|-----------|-------|-----------|
| `Premiação Prêmio` | Prêmio recebido | 3 | 60-180 pts |
| `Avaliação Prêmio` | Participação em avaliação/comissão | 2 | 2-115 pts |
| `Inscrição Prêmio` | Inscrição em prêmio | 1 | 1-2 pts |
**Níveis de Premiação:**
#### Nível 1 - Grande Prêmio CAPES
- `dadosPremiacaoPremio.premiacao`: "Grande Prêmio"
- Pontuação: 150 + 50 = 200 pts (limitado a 180)
#### Nível 1 - Prêmio CAPES de Tese (PCT)
- `dadosPremiacaoPremio.premio`: "PCT"
- `dadosPremiacaoPremio.premiacao`: "Prêmio" (+25) ou "Menção Honrosa" (+15)
- Pontuação base: 100 pts (máx 150 pts)
#### Nível 2 - Institucionais
- Interfarma, Vale-CAPES, etc.
- Base: 30 pts
- Prêmio: +20 pts / Menção: +10 pts
- Máximo: 60 pts
#### Nível 3 - Autoinscrição
- CDTDN, Vínculos Familiares, etc.
- Base: 10 pts
- Prêmio: +5 pts / Menção: +3 pts
- Máximo: 20 pts
### Outros Tipos Identificados
| Tipo | Descrição | Uso no Ranking |
|------|-----------|----------------|
| `Evento` | Participação em eventos SAE | Sim - bônus consultoria |
**Campos relacionados a eventos:**
- `dadosEvento.consultorResponsavel`: "Sim" ou "Não"
- Eventos recentes (últimos 2 anos): bonus para consultoria ativa
- Responsável por evento: +5 pts por vez (máx 25)
---
## Estrutura de Dados por Componente
### Coordenação CAPES
```json
{
"tipo": "Coordenação de Área de Avaliação",
"inicio": "01/01/2020",
"fim": null,
"dadosCoordenacaoArea": {
"tipo": "Coordenador de Área",
"areaAvaliacao": {
"id": 123,
"nome": "CIÊNCIAS AMBIENTAIS"
},
"inicioVinculacao": "01/01/2020",
"fimVinculacao": null,
"colegio": [
{"nome": "Colégio de Ciências Exatas, Tecnológicas e Multidisciplinar"}
],
"portaria": "123/2020",
"ies": {
"nome": "Universidade Federal do Brasil",
"sigla": "UFB"
}
}
}
```
### Consultoria
```json
{
"tipo": "Consultor",
"inicio": "15/03/2018",
"fim": null,
"dadosConsultoria": {
"situacaoConsultoria": "Atividade Contínua",
"inicioSituacao": "15/03/2018",
"inativacaoSituacao": null,
"ies": {
"nome": "Universidade Federal do Brasil",
"sigla": "UFB"
},
"areaConhecimentoPos": [
{
"areaAvaliacao": {
"nome": "CIÊNCIAS AMBIENTAIS"
}
}
],
"areaPesquisa": [
{"descricao": "Mudanças Climáticas"}
]
}
}
```
### Premiações
```json
{
"tipo": "Premiação Prêmio",
"dadosPremiacaoPremio": {
"nomePremio": "Prêmio CAPES de Tese",
"premio": "PCT",
"premiacao": "Prêmio",
"ano": 2022,
"areaConhecimento": {
"areaAvaliacao": {
"nome": "CIÊNCIAS AMBIENTAIS"
}
},
"papelPessoa": "Autor"
}
}
```
### Participação em Prêmios
```json
{
"tipo": "Avaliação Prêmio",
"dadosParticipacaoPremio": {
"tipo": "Membro de Comissão",
"premio": "PCT",
"ano": 2023,
"comissao": {
"nome": "Comissão Julgadora",
"tipo": "Avaliação"
},
"areaAvaliacao": {
"nome": "CIÊNCIAS AMBIENTAIS"
}
}
}
```
### Eventos
```json
{
"tipo": "Evento",
"inicio": "10/05/2023",
"fim": "15/05/2023",
"dadosEvento": {
"consultorResponsavel": "Sim",
"nome": "Seminário de Avaliação",
"tipo": "Presencial"
}
}
```
---
## Query de Agregação - Descobrir Todos os Tipos
Para descobrir todos os tipos de atuação disponíveis no índice:
```json
{
"size": 0,
"aggs": {
"tipos": {
"nested": {"path": "atuacoes"},
"aggs": {
"tipos_unicos": {
"terms": {
"field": "atuacoes.tipo.keyword",
"size": 100
}
}
}
}
}
}
```
---
## Mapeamento de Tipos vs. Componentes de Pontuação
| Componente | Tipos Relacionados | Pontuação Máxima |
|------------|-------------------|------------------|
| **A - Coordenação CAPES** | `Coordenação de Área de Avaliação`<br>`Histórico de Coordenação de Área de Avaliação` | 450 pts (CA) |
| **B - Coordenação PPG** | *Não existe no ES - usar Oracle* | 180 pts |
| **C - Consultoria** | `Consultor`<br>`Histórico de Consultoria`<br>`Evento` (bônus) | 230 pts |
| **D - Premiações** | `Premiação Prêmio`<br>`Avaliação Prêmio`<br>`Inscrição Prêmio` | 180 pts |
---
## Campos Faltantes / Limitações
### Não Disponíveis no Elasticsearch
1. **Coordenação de Programa (PPG)**
- Não existe tipo `atuacoes.tipo` para coordenação de programa
- Fonte alternativa: Oracle `SUCUPIRA_PAINEL.VM_COORDENADOR`
2. **Nota do PPG**
- Não disponível em `dadosGestaoPrograma`
- Fonte alternativa: Oracle `VM_PROGRAMA_SUCUPIRA.DS_CONCEITO`
3. **Dados detalhados de Câmara Temática**
- Inferido pelo campo `dadosCoordenacaoArea.tipo` ou `nome`
- Pode haver imprecisão na classificação
4. **Situação "Falecido"**
- Existe `dadosPessoais.anoObito` mas não `situacaoConsultoria="Falecido"`
---
## Implementação no Código
### Arquivo: `backend/src/infrastructure/elasticsearch/client.py`
Query principal com boost por tipo:
```python
async def buscar_candidatos_ranking(self, size: int = 1000) -> List[Dict[str, Any]]:
query = {
"size": size,
"query": {
"bool": {
"should": [
# Coordenação CAPES
{
"nested": {
"path": "atuacoes",
"query": {
"bool": {
"should": [
{"term": {"atuacoes.tipo": {"value": "Coordenação de Área de Avaliação", "boost": 10}}},
{"term": {"atuacoes.tipo": {"value": "Histórico de Coordenação de Área de Avaliação", "boost": 5}}}
]
}
},
"score_mode": "sum"
}
},
# Consultoria
{
"nested": {
"path": "atuacoes",
"query": {
"bool": {
"should": [
{"term": {"atuacoes.tipo": {"value": "Consultor", "boost": 2}}},
{"term": {"atuacoes.tipo": {"value": "Histórico de Consultoria", "boost": 1}}}
]
}
},
"score_mode": "sum"
}
},
# Premiações
{
"nested": {
"path": "atuacoes",
"query": {
"bool": {
"should": [
{"term": {"atuacoes.tipo": {"value": "Premiação Prêmio", "boost": 3}}},
{"term": {"atuacoes.tipo": {"value": "Avaliação Prêmio", "boost": 2}}},
{"term": {"atuacoes.tipo": {"value": "Inscrição Prêmio", "boost": 1}}}
]
}
},
"score_mode": "sum"
}
}
],
"minimum_should_match": 1
}
},
"_source": ["id", "dadosPessoais", "atuacoes"],
"sort": [{"_score": "desc"}]
}
```
### Arquivo: `backend/src/infrastructure/repositories/consultor_repository_impl.py`
Extração de tipos:
```python
# Consultoria
consultorias = [
a for a in atuacoes
if a.get("tipo") in ["Consultor", "Histórico de Consultoria"]
]
# Coordenação CAPES
coordenacoes = [
a for a in atuacoes
if a.get("tipo") in [
"Coordenação de Área de Avaliação",
"Histórico de Coordenação de Área de Avaliação",
]
]
# Eventos (bônus consultoria)
eventos_sae = [
a for a in atuacoes
if a.get("tipo") == "Evento"
]
# Premiações (todos os tipos são processados genericamente)
premiacoes = [
a for a in atuacoes
if a.get("dadosPremiacaoPremio") or
a.get("dadosParticipacaoPremio") or
a.get("dadosParticipacaoInscricaoPremio")
]
```
---
## Estatísticas
### Estimativas de Volume (baseado em documentação)
| Tipo | Quantidade Estimada |
|------|---------------------|
| Coordenadores de área (ativos) | ~200 |
| Coordenadores históricos | ~322 |
| Consultores | ~52.551 |
| Premiações | ~63.799 |
| **Total de registros com atuações** | **~90.482** |
### Boost Aplicado
O boost é usado para priorizar candidatos no score inicial do Elasticsearch:
| Tipo | Boost | Justificativa |
|------|-------|---------------|
| Coordenação de Área (ativa) | 10 | Máxima prioridade (200-450 pts) |
| Coordenação de Área (histórica) | 5 | Alta prioridade histórica |
| Premiação Prêmio | 3 | Mérito significativo |
| Consultor | 2 | Base importante |
| Avaliação Prêmio | 2 | Participação ativa |
| Histórico de Consultoria | 1 | Relevância histórica |
| Inscrição Prêmio | 1 | Participação básica |
---
## Notas de Implementação
1. **Paginação**: Query principal retorna top 1000 candidatos ordenados por score ES
2. **Recálculo**: Python recalcula pontuação completa e reordena por pontuação real
3. **Cache**: Resultados cacheados por 5 minutos (TTL=300s)
4. **Performance**: Primeira requisição ~1m34s, cacheadas ~0.27s
5. **Timeout**: 120s para queries ES
---
## Referências
- **Documentação**: `/home/fred/projetos/ranking/.claude/rules/ranking-queries-elasticsearch.md`
- **Critérios**: `/home/fred/projetos/ranking/.claude/rules/ranking-consultores-capes.md`
- **Implementação ES**: `/home/fred/projetos/ranking/backend/src/infrastructure/elasticsearch/client.py`
- **Extração**: `/home/fred/projetos/ranking/backend/src/infrastructure/repositories/consultor_repository_impl.py`
---
**Última atualização**: 2025-12-13
**Índice Elasticsearch**: `atuacapes` (servidor: `elastic-atuacapes.hom.capes.gov.br:9200`)