From ef50aee94549f953a92c0b5dcc592d210b9579ac Mon Sep 17 00:00:00 2001 From: Frederico Castro Date: Sat, 27 Dec 2025 01:29:48 -0300 Subject: [PATCH] docs: atualizar README com estrutura e endpoints atuais --- README.md | 174 +++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 125 insertions(+), 49 deletions(-) diff --git a/README.md b/README.md index 073863b..f81f697 100644 --- a/README.md +++ b/README.md @@ -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`