Imported from ndrd79/guia (.opencode/skills/guia-comercio/SKILL.md). Install upstream with npx skills add ndrd79/guia --skill guia-comercio. Copyright stays with the author.

Portal Maria Helena — Skill de contexto completo

Identidade

• Nome: portal-maria-helena
• Domínio: portalmariahelena.com.br
• Propósito: Portal de cidade para Maria Helena/PR — guia comercial, notícias, classificados, eventos, serviços
• Versão: 0.1.0 (privado)

Stack

Scripts principais

• npm run dev — next dev
• npm run build — next build
• npm run lint — next lint
• npm run db:push — prisma db push
• npm run db:studio — prisma studio
• npm run db:generate — prisma generate

Variáveis de ambiente (.env.example)

NEXT_PUBLIC_SUPABASE_URL
NEXT_PUBLIC_SUPABASE_ANON_KEY
SUPABASE_SERVICE_ROLE_KEY
SUPABASE_POOLER_URL
SUPABASE_DIRECT_URL
DATABASE_URL
NEXT_PUBLIC_SITE_URL=https://portalmariahelena.com.br
EMAIL_FROM
NEXT_PUBLIC_ADMIN_DEV_BYPASS  # dev only

Estrutura de diretórios

F:\guia-comercio\
├── pages/          # Páginas (Pages Router)
├── components/     # Componentes React
├── lib/            # Utilitários, API helpers, banner catalog
├── hooks/          # Custom hooks
├── src/            # Código duplicado (hooks, types)
├── prisma/         # Schema do banco
├── supabase/       # Migrations
├── docs/           # Documentação
├── scripts/        # Scripts diversos
├── types/          # Definições TypeScript
├── public/         # Assets estáticos
└── styles/         # CSS global

Páginas públicas

Páginas do usuário (/area-usuario)

Páginas de admin (/admin)

Database (Prisma — modelos principais)

noticias

id UUID PK, titulo String(255), categoria String(100), data Date, imagem String?, descricao String?, conteudo String?, banner_id UUID? FK→banners, credito_foto String(255)?, fonte String(500)?, created_at, updated_at, destaque Boolean? default false, workflow_status String(50)? default "draft" (draft/review/approved/rejected/published/archived), meta_title String(500)?, meta_description String?, slug String(500)? UNIQUE, tags String[], created_by UUID? FK→users, updated_by UUID? FK→users

empresas

id UUID PK, name String(255), description String?, category String(100), rating Decimal(2,1)? default 0.0, reviews Int? default 0, location String(255)?, phone String(20)?, email String(255)?, website String(255)?, address String?, image String?, featured Boolean? default false, is_new Boolean? default false, ativo Boolean? default true, plan_type plan_type_enum (basic/premium), premium_expires_at Timestamptz?, exibir_em_empresas_locais Boolean? default false, plano String(20)? default "basico", status empresa_status_enum (pending/approved/rejected), whatsapp String(20)?, horario_funcionamento_dias String(100)?, horario_funcionamento_horario String(100)?, facebook String(255)?, instagram String(255)?, maps String?, cidade String(100)?, user_source String(50)?, import_batch_id UUID? FK→import_batches

banners

id UUID PK, nome String(255), posicao String(100), imagem String, link String?, largura Int? default 400, altura Int? default 200, ativo Boolean? default true, ordem Int default 0, local String(50)? default "geral" (geral/home/guia_comercial/noticias/eventos/classificados/contato), tempo_exibicao Int? default 5, data_inicio Timestamptz?, data_fim Timestamptz?, is_principal Boolean? default false, prioridade Int? default 0, categoria String(50)? default "regular" (regular/hybrid), tipo String(20)? default "estatico"

banner_analytics

id BigInt PK auto, banner_id UUID FK, tipo String(20) (view/click), created_at, ip_address Inet?, user_agent String?, session_id String(255)?

banner_positions

Catálogo de posições: id Int PK auto, nome String(100) UNIQUE, descricao String?, largura_rec Int?, altura_rec Int?, paginas String(100)?

Outras tabelas

classificados, eventos, profiles, user_profiles, media_library, media_folders, media_usage, audit_logs, feira_produtor, produtores_feira, import_batches, import_results, seasonal_themes, news_analytics, news_versions, news_activity_log, workflow_comments, plan_history, backup_jobs/files/logs, storage_alerts/stats, video_ads/analytics/placements (legado)

API Routes

Públicas

Admin (protegidas por withAdminAuth)

Analytics

/api/analytics/banner-click, /api/analytics/banner-view, /api/analytics/ctr-roi, /api/analytics/dashboard, /api/analytics/summary, /api/analytics/track

Webhook

/api/webhook/empresa — Integração Google Forms (recebe submissões, cria empresa como pending)

Sistema de Autenticação

Admin

• Middleware (middleware.ts): verifica sessão Supabase + role admin no banco
• Cache cookie admin-role-ok com 5 min TTL
• APIs: wrapper withAdminAuth() em lib/api/withAdminAuth.ts
  • Usa getUser() (server-side), não getSession()
  • Cache in-memory de 1 minuto
  • Suporte Bearer token ou cookie
• Dev bypass: NEXT_PUBLIC_ADMIN_DEV_BYPASS=true

Usuário

• Supabase Auth (email/senha)
• Tabela profiles com role (user/admin)
• Tabela user_profiles com dados estendidos

Sistema de Banners

• 15+ posições centralizadas em lib/banners/catalog.ts
• Posições: home_hero, categorias, servicos, noticias_topo, noticias_meio, noticias_fim, guia_sidebar, eventos_topo, classificados_topo, contato_topo, guia_listagem_topo, noticia_individual_topo, noticia_individual_meio, noticia_individual_fim, layout_global
• Tipos: estatico (imagem) — vídeo removido
• Híbridos: banner com logo + CTA + texto patrocinado
• Agendamento: data_inicio / data_fim
• Analytics: view/click tracking, CTR
• Cache: 5 minutos in-memory para queries públicas
• Validação: Zod em lib/banners/validation.ts
• Workflow para adicionar posição: .agent/workflows/add-banner-position.md

Componentes principais

Layout

Header.tsx, Nav.tsx, Footer.tsx, UserLayout.tsx, SearchBar.tsx, WeatherSlider.tsx, CookieBanner.tsx, SeasonalDecorations.tsx, ErrorBoundary.tsx

Banners

BannerCarousel.tsx, BannerContainer.tsx, BannerAd.tsx, BannerDebug.tsx, OptimizedBanner.tsx, HeroBanner.tsx, SecondaryBanner.tsx, FooterBanner.tsx, PageBanner.tsx, BusinessCarousel.tsx, banners/BannerSlot.tsx, banners/index.ts, banners/templates/

Admin

AdminLayout.tsx, StatCard.tsx, MetricCard.tsx, StatsPanel.tsx, AnalyticsDashboard.tsx, ChartCard.tsx, TrendChart.tsx, ModernTable.tsx, Pagination.tsx, ImageUploader.tsx, ImageUploaderWithLibrary.tsx, MediaLibrary.tsx, MediaPicker.tsx, BannerPreview.tsx, PreviewModal.tsx, CategoryBadge.tsx, StatusIndicator.tsx, Breadcrumb.tsx, RelativeDate.tsx, ActionButtons.tsx, AINewsRewriter.tsx, EventoWizard.tsx, banners/BannerCard.tsx, banners/BannerList.tsx, banners/BannerFilters.tsx, banners/BannerForm.tsx (750+ linhas), banners/BannerWizard.tsx

Hooks principais

• /hooks/useBanners.ts — Carregar banners com cache
• /hooks/useBannersAdmin.ts — Admin de banners
• /hooks/useBannerFilters.ts — Filtros de banner
• /hooks/useBannerValidation.ts — Validação
• /hooks/useAnalytics.ts — Analytics
• /hooks/useAnalyticsDashboard.ts — Dashboard analytics
• /hooks/useImageOptimization.ts — Otimização de imagem
• /src/hooks/useBannerAnalytics.ts — Analytics de banners

Libs utilitárias

• lib/prisma.ts — PrismaClient singleton
• lib/supabase.ts — Clientes Supabase (browser + server)
• lib/logger.ts — Logging estruturado (info, warn, error, debug, middleware, api, auth)
• lib/auth-helpers.ts — Refresh token
• lib/email.ts — Envio de email com Nodemailer
• lib/formatters.ts — Formatação de data/moeda
• lib/api/withAdminAuth.ts — Middleware de autenticação admin
• lib/api/rateLimit.ts — Rate limiting
• lib/banners/catalog.ts — Catálogo centralizado de posições
• lib/banners/utils.ts — Utilitários (status de agendamento, etc.)
• lib/banners/helpers.ts — Helpers
• lib/banners/validation.ts — Schemas Zod
• lib/banners/BannerTemplateRegistry.ts — Registry de templates
• lib/constants/categorias.ts — Categorias válidas
• lib/images/cropImage.ts — Crop de imagem

Categorias

Notícias (22)

Cidade, Policial, Política, Economia, Esportes, Cultura, Saúde, Educação, Tecnologia, Meio Ambiente, Trânsito, Infraestrutura, Agricultura, Turismo, Social, Justiça, Eventos, Negócios, Ciência, Lazer, Religião, Outras

Empresas

Restaurante, Automotivo, Saude, Alimentacao, Beleza, Tecnologia, Comercio, Servicos, Educacao, Imoveis

Problemas conhecidos

Segurança (críticos)

1. RLS desabilitado em audit_logs — CRÍTICO, requer correção manual
2. Function search path vulnerável — 3 alerts pendentes
3. Proteção vazada não habilitada no Supabase
4. MFA insuficiente — apenas básico
5. Postgres versão vulnerável — precisa upgrade
6. Dev bypass em produção — NEXT_PUBLIC_ADMIN_DEV_BYPASS pode ser perigoso
7. APIs sem withAdminAuth — algumas ainda usam auth manual

Qualidade de código

1. Arquivos grandes: noticias.tsx (858), banners.tsx (615), temas-sazonais.tsx (675), empresas/gerenciar.tsx (660)
2. Código morto: arquivos .disabled.tsx e .bak.tsx
3. Auth misto: Supabase Auth + NextAuth.js instalados
4. Type safety: src/types/supabase.ts usa type Database = any
5. Código duplicado: /hooks e /src/hooks têm arquivos similares
6. 99 migrations no Supabase — schema evoluiu iterativamente

Convenções de código

1. Pages Router (não App Router, apesar de /src/app existir)
2. Server-side: getServerSideProps com createServerSupabaseClient()
3. Client-side: hooks custom + supabase.from()
4. Form validation: Zod + React Hook Form com @hookform/resolvers/zod
5. API auth: withAdminAuth() wrapper para admin
6. Logger estruturado: lib/logger.ts (info, warn, error, debug, middleware, api, auth)
7. Notificações: react-hot-toast via ToastProvider
8. Ícones: Lucide React (admin), Font Awesome CDN (público)
9. Imagens: Supabase Storage, fallback placeholder em erro
10. Tailwind para estilos, sem CSS modules
11. Mobile-first responsivo

Documentação relevante

• docs/BANNERS-README.md — Sistema de banners (132 linhas)
• docs/IMPLEMENTACAO-BANNERS-GUIDE.md — Guia completo (846 linhas)
• docs/MAPA-BANNERS-SITE.md — Mapa de posições (328 linhas)
• docs/GOOGLE-FORMS-INTEGRATION.md — Webhook (311 linhas)
• docs/GUIA-MIGRACAO-SUPABASE.md — Migração (564 linhas)
• docs/VERCEL-DEPLOY.md — Deploy
• docs/SECURITY-AUTH-CONFIG.md — Segurança
• .agent/workflows/add-banner-position.md — Workflow para adicionar posição de banner