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

docs: atualizar README com estrutura e endpoints atuais

Browse Source
This commit is contained in:
Frederico Castro
2025-12-27 01:29:48 -03:00
parent 04f0c93a36
commit ef50aee945
1 changed files with 125 additions and 49 deletions
Download Patch File Download Diff File Expand all files Collapse all files

174
README.md
View File

@@ -6,13 +6,15 @@ Sistema completo de ranking de consultores CAPES baseado na Minuta Técnica, des
### Backend (Python + FastAPI + DDD)
- **Domain Layer**: Entities, Value Objects, Domain Services
- **Application Layer**: Use Cases, DTOs
- **Infrastructure Layer**: Repositories, Elasticsearch Client, Oracle Client
- **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 baseada no layout do HTML de referência
- Componentes reutilizáveis
- 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
@@ -24,8 +26,10 @@ ranking/
│ ├── src/
│ │ ├── domain/
│ │ │ ├── entities/
│ │ │ │ └── consultor.py
│ │ │ │ ├── consultor.py
│ │ │ │ └── consultor_ranking.py
│ │ │ ├── value_objects/
│ │ │ │ ├── criterios_pontuacao.py
│ │ │ │ ├── periodo.py
│ │ │ │ └── pontuacao.py
│ │ │ ├── repositories/
@@ -35,16 +39,29 @@ ranking/
│ │ ├── 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
│ │ │ └── repositories/
│ │ │ └── consultor_repository_impl.py
│ │ │ │ ├── client.py
│ │ │ │ └── ranking_repository.py
│ │ │ ├── repositories/
│ │ │ │ └── consultor_repository_impl.py
│ │ │ └── ranking_store.py
│ │ └── interface/
│ │ ├── api/
│ │ │ ├── app.py
@@ -52,8 +69,13 @@ ranking/
│ │ │ ├── config.py
│ │ │ └── dependencies.py
│ │ └── schemas/
│ │ └── consultor_schema.py
│ ├── pyproject.toml
│ │ ├── consultor_schema.py
│ │ └── ranking_schema.py
│ ├── scripts/
│ ├── sql/
│ ├── static/
│ ├── tests/
│ ├── requirements.txt
│ ├── Dockerfile
│ └── .env.example
│
@@ -61,9 +83,12 @@ ranking/
│ ├── src/
│ │ ├── components/
│ │ │ ├── Header.jsx
│ │ │ ├── Header.css
│ │ │ ├── ConsultorCard.jsx
│ │ │ └── ConsultorCard.css
│ │ │ ├── CompararModal.jsx
│ │ │ ├── FiltroSelos.jsx
│ │ │ ├── BlocoCriteriosModal.jsx
│ │ │ ├── RawDataModal.jsx
│ │ │ └── SugerirConsultores.jsx
│ │ ├── services/
│ │ │ └── api.js
│ │ ├── App.jsx
@@ -72,9 +97,10 @@ ranking/
│ │ └── index.css
│ ├── package.json
│ ├── vite.config.js
│ ├── Dockerfile
│ └── nginx.conf
│ └── Dockerfile
│
├── scripts/
├── tools/
├── docker-compose.yml
├── .env.example
├── .gitignore
@@ -187,6 +213,10 @@ ranking/
| **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:
@@ -206,7 +236,7 @@ Indicadores visuais que aparecem no card do consultor:
```
Score_Atuação = min(Base + Tempo + Bônus, Teto)
Score_Total = Bloco_A + Bloco_B + Bloco_C + Bloco_D
Score_Total = Bloco_A + Bloco_B + Bloco_C + Bloco_D + Bloco_E
```
## Requisitos
@@ -228,7 +258,9 @@ cd backend
2. Crie ambiente virtual e instale dependências:
```bash
poetry install
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```
3. Configure as variáveis de ambiente:
@@ -242,17 +274,17 @@ 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
ORACLE_LOCAL_USER=seu_usuario
ORACLE_LOCAL_PASSWORD=sua_senha
ORACLE_LOCAL_DSN=host:1521/service_name
```
5. Execute o backend:
```bash
poetry run python src/main.py
python -m uvicorn src.interface.api.app:app --host 0.0.0.0 --port 8000 --reload
```
A API estará disponível em `http://localhost:8010`
A API estará disponível em `http://localhost:8000`
### Frontend
@@ -275,79 +307,111 @@ O frontend estará disponível em `http://localhost:5173`
## Setup com Docker
1. Configure as variáveis de ambiente:
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
```
2. Edite `.env` com suas credenciais
3. Edite `.env` com suas credenciais
3. Execute com Docker Compose:
4. Execute com Docker Compose:
```bash
docker-compose up -d
```
- Backend: `http://localhost:8010`
- Frontend: `http://localhost`
- Frontend: `http://localhost:5173`
- Oracle local: `localhost:1521`
## Endpoints da API
### GET /api/v1/ranking
Retorna o ranking resumido de consultores.
### Ranking
**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)
| 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 |
### GET /api/v1/ranking/detalhado
Retorna o ranking completo com todos os detalhes.
### Consultor
**Query Parameters:**
- `limite` (int, default=100): Limite de consultores
- `componente` (str, optional): Filtrar por componente (a, b, c, d)
| 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 |
### GET /api/v1/consultor/{id_pessoa}
Retorna detalhes completos de um consultor específico.
### Sugestões
### GET /api/v1/health
Health check da API.
| 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__1763197236`
- Campos: `id`, `dadosPessoais`, `atuacoes`
- Í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 (SUCUPIRA_PAINEL)
### 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`
- 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`
- Swagger UI: `http://localhost:8000/docs`
- ReDoc: `http://localhost:8000/redoc`
## Desenvolvimento
### Testes
```bash
cd backend
poetry run pytest
pytest
```
### Linting
```bash
poetry run black src/
poetry run ruff check src/
black src/
ruff check src/
```
### Build para Produção
@@ -363,7 +427,19 @@ 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`