Culturama
Plataforma web de descoberta de eventos culturais (TCC). Junta shows oficiais (Ticketmaster) com eventos de rua cadastrados por organizadores, com filtros, mapa, rotas e painel de moderação.
A fonte de verdade do produto está em culturama-especificacao-cursor.md.
Repositório privado: pode (e deve) ser compartilhado com sócios. Não suba senha, chave de API nem o arquivo .env.
Em que fase estamos
| Fase | Status |
|---|
| 1. Fundação (auth, 18+, LGPD, organizador CPF/CNPJ) | Feita |
| 2. Eventos (CRUD interno, listagem, Ticketmaster) | Feita |
| 3. Mapa, filtros, rotas, Uber/99 | Feita no código. Mapa e tempos de rota só ligam com chave Google. Filtros e deep links já funcionam sem ela. |
| 4. Painel admin | Feita |
| 5. Favoritos, comentários, denúncia, interesses | Feita |
| 6. Anúncios no site, Mercado Pago sandbox, polimento Skiper | Próxima |
Stack
- Next.js 14 (App Router) + TypeScript + Tailwind + shadcn
- Prisma + PostgreSQL (Supabase)
- Auth.js: e-mail/senha e Google
- Ticketmaster Discovery API (job diário)
- Google Maps JavaScript + Directions (opcional na Fase 3)
O que sobe no GitHub e o que não sobe
Sobe: código, Prisma (schema + migrations), .env.example, spec, skills do Cursor, vercel.json.
Não sobe (já está no .gitignore):
.env (senha do banco, AUTH_SECRET, chaves Ticketmaster/Google)node_modules/, .next/uploads/ (CPF/CNPJ e imagens enviadas)data/ (contador local de cota do Maps)
Cada sócio clona o repo, copia .env.example para .env e preenche as chaves no próprio computador. Quem já tem o banco do grupo pode reutilizar as URIs do Supabase, mas a senha se passa fora do Git (WhatsApp/1Password), nunca no commit.
Se uma chave já vazou em chat ou print, troque no painel (Supabase, Ticketmaster, Google, Auth).
Como rodar local
Requisitos: Node.js 20+, conta no Supabase (ou o projeto já usado pelo grupo).
git clone https://github.com/Wkarus/CULTURAMA.git
cd CULTURAMA
npm install
copy .env.example .env
No Linux/macOS use cp .env.example .env.
Preencha no .env pelo menos:
DATABASE_URL e DIRECT_URL (Supabase → Connect → Prisma; pooler na 6543, direto na 5432)AUTH_SECRET (npx auth secret)TICKETMASTER_API_KEY (Consumer Key da Discovery API) para importar showsADMIN_EMAIL com o e-mail da conta que vai moderar; depois saia e entre de novo, ou npm run db:admin
Opcional:
AUTH_GOOGLE_ID / AUTH_GOOGLE_SECRET (callback http://localhost:3000/api/auth/callback/google)NEXT_PUBLIC_GOOGLE_MAPS_API_KEY e GOOGLE_MAPS_API_KEY (Maps JavaScript + Directions). Sem isso, /mapa mostra aviso; lista, Uber e 99 seguem ok.
Banco e app:
npx prisma migrate deploy
npx prisma generate
npm run db:seed
npm run dev
Abra http://localhost:3000. Se a 3000 estiver ocupada, o Next usa 3001.
Scripts
npm run dev # desenvolvimento
npm test # testes de lib (CPF, filtros, categorias, Mapas Culturais…)
npm run mapas:importar # importa Mapas Culturais (ver abaixo)
npm run db:seed # categorias
npm run db:admin # promove ADMIN_EMAIL a admin
npx prisma studio # ver tabelas
Sincronizar Ticketmaster (dev, sem CRON_SECRET):
GET http://localhost:3000/api/cron/ticketmaster
Na Vercel, o cron diário está em vercel.json. Lá defina CRON_SECRET e chame com Authorization: Bearer ....
Mapas Culturais (SP Cultura, Mapa da Cultura, Paraíba…)
Importa eventos da API pública /api/ das instâncias em MAPAS_CULTURAIS_INSTANCIAS (formato Nome|URL|Fuso, separado por ;; |basico no fim liga o modo só dados básicos). Roda todo dia às 8h30 UTC pelo cron de vercel.json.
npx tsx scripts/importar-mapas-culturais.ts --simular --instancia=https://mapacultural.pb.gov.br # só busca e mostra, não grava
npm run mapas:importar # grava no banco
No PowerShell use npx tsx ... (o -- do npm run some). Em dev também dá para chamar GET /api/cron/mapas-culturais?instancia=URL; no painel admin há o botão "Sincronizar agora".
- Eventos entram como
importado (no ar sem revisão). Ocultar no admin vira cancelado, e a importação respeita.
- Evento que some da fonte ou já terminou vira
inativo (não é apagado) e volta a importado se reaparecer.
- Editar o texto no admin trava a sobrescrita daquele evento (
editado_pela_equipe).
- Linguagem → categoria:
src/lib/mapas-culturais-categorias.ts. O que não estiver mapeado vai para "Outros" e aparece no painel.
- Nunca importamos dados de agentes (nome pessoal, e-mail, telefone, documento): o
@select é uma lista fechada.
- Região: por padrão o Brasil todo; quem limita por distância é o usuário, no Perto de mim. Para restringir a importação:
MAPAS_CULTURAIS_UFS="SP,RJ" e/ou MAPAS_CULTURAIS_RAIO="lat,lng,km". Com filtro ligado, local sem estado conhecido fica de fora e evento que sai da região vira inativo.
- robots.txt: lido antes de cada instância. Se bloquear
/api/ (ou não responder), a instância é pulada sem nenhuma chamada à API e o aviso fica no histórico do admin. 404 = sem restrições (RFC 9309).
Autorização das fontes
O Mapa da Cultura (mapa.cultura.gov.br) e o SP Cultura (spcultura.prefeitura.sp.gov.br) só podem ser importados em produção depois de autorização formal dos respectivos gestores. Até lá, não os inclua em MAPAS_CULTURAIS_INSTANCIAS na Vercel. Teste local com --simular ou na página /teste/mapas-culturais não grava nada e é o limite do uso sem autorização. Ao receber a autorização, registre aqui quem autorizou, quando e por qual canal.
Modo só dados básicos (|basico), para fonte sem bloqueio a robôs e sem termos que proíbam o uso, enquanto a autorização não chega: a API nem é consultada sobre descrição e imagens. Entram só título, data, local, endereço, coordenadas, categoria, classificação etária, gratuidade e o link para a página original, com o crédito "Fonte: X". A descrição vira um texto padrão que manda para a página original. Dados factuais não têm proteção autoral (Lei 9.610, art. 8º); imagens e textos podem ter autor. Com a autorização, basta tirar o |basico.
| Instância | Autorização formal |
|---|
| Mapa da Cultura (federal) | pendente |
| SP Cultura | pendente |
| CulturAZ (Santo André) | autorizado em 28/10/2026, por e-mail, por Gabrielle Siqueira Tripiciano de Souza, responsável pelos Mapas Culturais na Prefeitura de Santo André. Combinado no pedido: crédito "Fonte: CulturAZ — Prefeitura de Santo André" com link para o evento original, no máximo uma consulta à API por dia (o cron), só dados de eventos e espaços, sem dados pessoais de agentes. O e-mail fica arquivado com a equipe. |
Regras de acesso (sem exceção)
- Nunca contornar Cloudflare, captcha ou desafio anti-robô: nada de User-Agent de navegador, navegador headless, proxy, troca de IP ou resolução automática de desafio.
- User-Agent sempre honesto e fixo:
CulturamaBot/1.0 (+contato), com o contato de MAPAS_CULTURAIS_CONTATO. Não existe opção para trocá-lo.
- Desafio da Cloudflare (403/429/503 com challenge, inclusive no robots.txt) ou robots.txt bloqueando ou sem resposta: a instância é pulada na hora, sem nova tentativa, e o aviso fica no histórico do admin. Nada é gravado nem inativado nessa rodada.
- Pausa entre chamadas, timeout e poucas retentativas com espera crescente, só para falhas de rede, 429 e 5xx comuns.
- As funções rodam em São Paulo (
"regions": ["gru1"] no vercel.json) por desempenho, perto do banco no Supabase (sa-east-1). Não é forma de passar por bloqueio.
Rotas úteis
| Rota | Quem usa |
|---|
/cadastro, /login, /privacidade | Conta 18+ com aceite LGPD |
/cadastro/organizador | CNPJ (BrasilAPI, auto-aprova se ativo) ou CPF (fila admin) |
/eventos, /eventos/[id] | Lista e detalhe (interno + Ticketmaster) |
/conta/eventos | CRUD do organizador aprovado |
/mapa | Mapa + mesmos filtros da lista |
/admin | Moderação, fila de organizadores, anúncios (cadastro; vitrine pública é Fase 6) |
Regras importantes:
- Organizador
pendente só salva rascunho.
- Cancelar/adiar não apaga o evento; muda
status.
- Evento
ticketmaster não é editável pelo organizador. Admin só oculta e anota nota_admin (campo interno, nunca no site público).
- Ads no admin ainda não aparecem na home. Quando aparecerem, a etiqueta "Patrocinado" é obrigatória.
Design
Tokens Shop/Refero em src/app/globals.css e .cursor/skills/culturama-design-system. Não instalar 21st Dev sem combinado do grupo. Skiper UI só na Fase 6.
Próximos passos (Fase 5)
- Favoritos (tabela
Favorite já existe no schema).
- Comentários/avaliações com denúncia (admin precisa poder remover).
- Tags de interesse no perfil e listagem simples por correspondência categoria/interesse. Sem LLM.
Depois, Fase 6: banners no front com "Patrocinado", checkout Mercado Pago sandbox (só evento interno; Ticketmaster usa o link dela), polimento visual.
Hospedagem prevista: Vercel + o mesmo Supabase. Variáveis da Vercel = as do .env, nunca commitadas.
Sócios: fluxo de trabalho
- Clone,
.env local, npm install, migrate + seed.
- Trabalhe em branch (
feat/favoritos), abra pull request no GitHub.
- Não force push em
master/main sem combinado.
- Não commite
.env, prints de chave, nem pasta uploads/.
