{"id":50388330,"url":"https://github.com/rckbrcls/world-cup-project","last_synced_at":"2026-05-30T16:30:42.033Z","repository":{"id":355492505,"uuid":"1216407414","full_name":"rckbrcls/world-cup-project","owner":"rckbrcls","description":"SQL-first FIFA World Cup database project with PostgreSQL rules, lifecycle tools, and an operational browsing client.","archived":false,"fork":false,"pushed_at":"2026-05-18T20:09:14.000Z","size":2514,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-05-18T21:55:09.532Z","etag":null,"topics":["database-course","fastapi","football","natural-language-query","nextjs","ollama","postgresql","react","sql","typescript","world-cup"],"latest_commit_sha":null,"homepage":null,"language":"PLpgSQL","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rckbrcls.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-20T21:52:41.000Z","updated_at":"2026-05-18T20:09:18.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/rckbrcls/world-cup-project","commit_stats":null,"previous_names":["rckbrcls/world-cup-project"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/rckbrcls/world-cup-project","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rckbrcls%2Fworld-cup-project","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rckbrcls%2Fworld-cup-project/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rckbrcls%2Fworld-cup-project/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rckbrcls%2Fworld-cup-project/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rckbrcls","download_url":"https://codeload.github.com/rckbrcls/world-cup-project/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rckbrcls%2Fworld-cup-project/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33700863,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-30T02:00:06.278Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["database-course","fastapi","football","natural-language-query","nextjs","ollama","postgresql","react","sql","typescript","world-cup"],"created_at":"2026-05-30T16:30:41.303Z","updated_at":"2026-05-30T16:30:42.025Z","avatar_url":"https://github.com/rckbrcls.png","language":"PLpgSQL","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Projeto de Banco de Dados da Copa do Mundo\n\nProjeto acadêmico de banco de dados para SCC0640, baseado em\n`docs/brief/BD-Projeto-2026.pdf`.\n\nO projeto modela um sistema de gerenciamento de Copas do Mundo FIFA em\nPostgreSQL e fornece um protótipo Python de linha de comando para as\ndemonstrações exigidas.\n\n## Escopo\n\n- Modelo relacional PostgreSQL para edições da Copa do Mundo, seleções, grupos,\n  partidas, elencos, árbitros, estádios, eventos e classificações.\n- Regras de negócio orientadas por SQL por meio de chaves, restrições, funções,\n  visões e gatilhos.\n- Script SQL direto para popular o conjunto de dados de demonstração.\n- Protótipo terminal em Python que lê parâmetros de login do banco, executa os\n  10 relatórios obrigatórios, solicita ao Ollama local a conversão de linguagem\n  natural para SQL, mostra feedback de planejamento por etapas, mostra o SQL\n  gerado antes da execução e trata erros do PostgreSQL.\n\n## Arquivos Principais\n\n- `docs/brief/BD-Projeto-2026.pdf`: enunciado original da disciplina.\n- `sql/ddl.sql`: esquema, restrições, índices, funções de validação, gatilhos e\n  funções de relatório obrigatórias.\n- `sql/dml.sql`: ponto de entrada do conjunto de dados de demonstração.\n- `src/terminal/presentation/`: comandos Typer e renderização terminal com\n  Rich.\n- `src/terminal/application/`: catálogo de consultas, planejamento da\n  Consulta Natural e orquestração dos casos de uso do terminal.\n- `src/terminal/domain/`: contratos de relatório usados pelo fluxo de consultas\n  obrigatórias.\n- `src/terminal/infrastructure/`: adaptadores de PostgreSQL, configurações,\n  repositório e Ollama.\n- `docker/Dockerfile`: imagem de contêiner para o protótipo.\n- `compose.yaml`: orquestração principal de PostgreSQL, Ollama e protótipo.\n- `submission/`: arquivos da entrega final da disciplina.\n\n## Requisitos Mínimos\n\nPara os caminhos com Docker Compose:\n\n- Docker Engine ou Docker Desktop com Docker Compose v2.\n- Conexão com a internet na primeira execução, porque a imagem do app e o\n  modelo do Ollama podem ser baixados.\n- Terminal interativo com suporte a stdin/TTY, pois o protótipo solicita dados\n  de conexão pelo teclado.\n- Pelo menos 15 GB livres em disco para imagens, volumes do PostgreSQL/Ollama e\n  modelo local.\n- 8 GB de memória RAM como mínimo prático; 16 GB são recomendados para o\n  Ollama rodar com mais folga.\n\nAntes de executar, escolha uma das duas opções abaixo. A opção 1 é a mais\nsimples para avaliadores que querem tudo isolado no Docker. A opção 2 é a\nrecomendada para macOS com Apple Silicon, porque o Ollama nativo pode usar a\naceleração Apple/Metal, enquanto o Ollama dentro do Docker Desktop para macOS\npode ficar limitado à CPU.\n\n## Opção 1 - Docker completo\n\nUse esta opção quando quiser PostgreSQL, Ollama e protótipo inteiramente no\nDocker Compose. Ela é indicada para Linux/Windows com aceleração de GPU\ndisponível para containers, ou para máquinas em que a execução CPU-only seja\naceitável. No Docker Desktop para macOS, o Ollama dentro do container pode rodar\nsem GPU/Metal e ficar bem mais lento.\n\n1. Instale e abra o Docker Desktop ou Docker Engine com Docker Compose v2.\n2. Confirme que o Docker responde:\n\n```bash\ndocker compose version\n```\n\n3. Execute o protótipo completo:\n\n```bash\ndocker compose run --rm app\n```\n\nEsse comando inicia PostgreSQL, aplica `sql/ddl.sql` e `sql/dml.sql` no primeiro\nvolume do banco, inicia o Ollama em container, baixa `gemma4:e2b` quando\nnecessário e abre o protótipo terminal. O download do modelo acontece apenas\nquando o volume `ollama-data` ainda não possui o modelo. O Compose já fixa\nbanco, usuário, senha, endereço interno do Ollama e modelo; não é necessário\ncriar arquivo de configuração nem exportar variáveis antes de rodar.\n\nQuando o terminal solicitar conexão com o banco, pressione Enter para aceitar os\nvalores padrão do Docker:\n\n```text\nservidor=db\nporta=5432\nbanco=copa_mundo\nusuario=copa_mundo\nsenha=copa_mundo\n```\n\n## Opção 2 - macOS com Ollama local\n\nUse esta opção em Macs com Apple Silicon. O PostgreSQL e o protótipo continuam\nno Docker Compose, mas o Ollama roda nativo no macOS para poder usar a\naceleração Apple/Metal.\n\n1. Instale o Ollama para macOS pelo site oficial: \u003chttps://ollama.com/download\u003e.\n2. Abra o aplicativo Ollama. Na primeira abertura, permita que ele instale o\n   comando `ollama` no terminal se o macOS solicitar essa confirmação.\n3. Abra um novo terminal e confirme que a CLI foi instalada:\n\n```bash\nollama --version\n```\n\nSe o comando não existir, feche e abra novamente o app Ollama e aceite a criação\ndo atalho da CLI. Pela instalação padrão, o app cria um link para o comando em\n`/usr/local/bin`.\n\n4. Baixe o modelo padrão:\n\n```bash\nollama pull gemma4:e2b\n```\n\n5. Confirme que o servidor local do Ollama responde:\n\n```bash\ncurl http://localhost:11434/api/tags\n```\n\nA resposta deve ser um JSON com a lista de modelos instalados. Verifique se\n`gemma4:e2b` aparece nessa lista.\n\n6. Faça um teste curto de geração antes de abrir o protótipo:\n\n```bash\ncurl http://localhost:11434/api/generate \\\n  -d '{\"model\":\"gemma4:e2b\",\"prompt\":\"Responda apenas OK.\",\"stream\":false}'\n```\n\nEsse teste também carrega o modelo na memória, então pode demorar na primeira\nexecução. Se quiser confirmar o processador usado pelo Ollama, rode:\n\n```bash\nollama ps\n```\n\nNa coluna `PROCESSOR`, o Ollama indica se o modelo está em CPU, GPU ou uma\nmistura de CPU/GPU.\n\n7. Execute o protótipo com o serviço que aponta para o Ollama do macOS:\n\n```bash\ndocker compose run --rm app-local-ollama\n```\n\nEsse serviço sobe o PostgreSQL e o app, mas não sobe o container `ollama`. O app\nusa `OLLAMA_BASE_URL=http://host.docker.internal:11434` para acessar o Ollama\nnativo do macOS. No prompt de conexão do banco, pressione Enter para aceitar os\nmesmos padrões do Docker: servidor `db`, porta `5432`, banco `copa_mundo`,\nusuário `copa_mundo` e senha `copa_mundo`.\n\nDepois da conexão, o protótipo oferece:\n\n- estado do banco;\n- os 10 relatórios SQL obrigatórios;\n- conversa da Consulta Natural por meio do Ollama local, com feedback de\n  planejamento por etapas;\n- execução SQL controlada, com SQL visível e tratamento de erros.\n\nDurante desenvolvimento, uma imagem Docker antiga pode continuar executando uma\nversão anterior do código. Depois de alterar arquivos em `src/`, reconstrua a\nimagem do serviço usado antes de testar novamente pelo Docker Compose.\n\nSe aparecer uma falha de autenticação por senha mesmo aceitando esses padrões,\no volume `postgres-data` provavelmente já foi inicializado antes com outra\nsenha. A imagem oficial do PostgreSQL só aplica a senha inicial na primeira\ncriação do volume; em um banco já existente, informe a senha original no prompt\nou recrie o volume apenas quando quiser descartar os dados locais.\n\nNa opção Docker completo, PostgreSQL e Ollama ficam internos ao Compose. Na\nopção macOS, somente o Ollama nativo precisa estar acessível na máquina local.\n\nReferências operacionais:\n\n- Ollama para macOS: \u003chttps://docs.ollama.com/macos\u003e\n- FAQ do Ollama sobre GPU no Docker: \u003chttps://docs.ollama.com/faq\u003e\n- GPU no Docker Desktop: \u003chttps://docs.docker.com/desktop/features/gpu/\u003e\n\n## Execução Manual de Desenvolvimento\n\nUse este caminho apenas se não quiser usar Docker Compose. Crie um banco\nPostgreSQL local com banco, usuário e senha `copa_mundo`, então aplique os\narquivos SQL nesta ordem:\n\n```bash\npsql \"postgresql://copa_mundo:copa_mundo@localhost:5432/copa_mundo\" -f sql/ddl.sql\npsql \"postgresql://copa_mundo:copa_mundo@localhost:5432/copa_mundo\" -f sql/dml.sql\n```\n\nInstale as dependências Python e garanta que o modelo esteja disponível no\nOllama local:\n\n```bash\nuv sync\nollama pull gemma4:e2b\n```\n\nExecute o protótipo terminal manualmente com:\n\n```bash\nuv run terminal\n```\n\nQuando o protótipo solicitar a conexão local, use:\n\n```text\nservidor=localhost\nporta=5432\nbanco=copa_mundo\nusuario=copa_mundo\nsenha=copa_mundo\n```\n\nA conversa da Consulta Natural também pode ser aberta diretamente:\n\n```bash\nuv run terminal consulta-natural conversa\n```\n\nDentro da conversa, `executar` executa apenas a proposta SQL validada mais\nrecente, e `sair` retorna ao menu.\n\n## Pacote Final\n\nO diretório de entrega da disciplina é `submission/` e deve manter estes oito\narquivos:\n\n- `01.ER.pdf`\n- `02.ER.xml`\n- `03.Relacional.pdf`\n- `04.Relacional.xml`\n- `05.DDL.sql`\n- `06.DML.sql`\n- `07.Prototipo.zip`\n- `08.Instrucoes.txt`\n\nSe os XMLs draw.io forem alterados, abra-os no diagrams.net/draw.io e exporte\nnovamente os PDFs correspondentes antes da entrega oficial.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frckbrcls%2Fworld-cup-project","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frckbrcls%2Fworld-cup-project","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frckbrcls%2Fworld-cup-project/lists"}