# Culturando Theme - Documentação Técnica & Manual

**Versão:** 1.2.0  
**Autor:** Ana Nascimento - Culturando  
**Requisitos:** WordPress 6.2+, PHP 8.0+, MySQL 5.7+  
**Licença:** GPL v2 or later  

---

## Visão Geral
Tema WordPress customizado para o portal **Culturando**, focado em divulgação cultural, parceiros locais e agenda de eventos. Desenvolvido com arquitetura modular, performance otimizada e conformidade LGPD nativa.

---

## Estrutura de Arquivos

    culturando-theme/
    ├── assets/
    │ ├── css/ # Estilos do tema e módulos
    │ ├── js/ # Scripts (cookie consent, maps, interactions)
    │ └── images/ # Ícones e placeholders
    ├── includes/
    │ ├── theme-options.php # Painel de administração do tema
    │ ├── partners.php # CPT Parceiros + Taxonomias + Location Picker
    │ ├── banner-manager.php # Gerenciador de banners + rastreamento
    │ └── eventos.php # CPT Eventos + Template Tags + Rewrites
    ├── template-parts/
    │ ├── content-partner.php
    │ ├── content-event.php
    │ ├── content-page.php
    │ ├── content-single.php
    │ ├── content-none.php
    │ └── content.php
    ├── index.php
    ├── header.php / footer.php
    ├── front-page.php # home do site
    ├── archive.php # Listagem genérica
    ├── archive-event.php # Listagem geral de eventos
    ├── single-event.php # Página do evento
    ├── archive-partner.php # Listagem geral de parceiros
    ├── single-partner.php # Ficha do parceiro (com mapa e agenda)
    ├── page.php / single.php # Templates padrão
    ├── functions.php # Inicialização, hooks e autoload
    └── style.css # Folha de estilos principal

---

## Instalação & Ativação
1. Compacte a pasta do tema em `culturando.zip`.
2. No WP-Admin: **Aparência → Temas → Adicionar Novo → Enviar Tema**.
3. Ative o tema e acesse **Configurações → Cookie Consent** e **Opções do Tema** para configurar chaves de API e textos.
4. Acesse **Links Permanentes** e clique em **Salvar Alterações** para registrar as rewrite rules de eventos e parceiros.

---

## Módulos & Funcionalidades

### Administração do Tema
- Slider configurável na página inicial
- Campos para mídias sociais (URLs e ícones)
- Seletor de tipo de editor (Gutenberg/Clássico)
- Campo de texto para copyright no rodapé
- Tratamento limpo de `settings_errors()` (sem duplicatas)

### Sistema de Parceiros
- CPT `partner` com campos de: nome, logo, descrição, contato, horários, endereço
- **Taxonomia `categoria_parceiro`**: Áreas de atuação (ex: Gastronomia, Cultura, Passeios)
- **Taxonomia `local_parceiro`**: Bairros/Regiões (ex: Centro, Vila Nova, Distrito Histórico)
- Box de informações estruturadas (exibido no frontend)
- Fallback de avatar com iniciais automáticas (caso não haja logo)
- Cards 100% clicáveis (técnica *stretch link* para acessibilidade e SEO)

### Localização & Mapas
- **Location Picker** integrado à edição de Parceiros e Páginas (locais turísticos)
- Seleção visual de coordenadas via mapa interativo (Google Maps / Leaflet)
- Exibição automática de mapa estático ou interativo no frontend
- Campos de endereço formatados para schema.org e SEO local

### Gerenciador de Banners
- Múltiplas posições fixas no layout (header, sidebar, rodapé, entre conteúdos)
- Suporte a **Destaque da Semana**: formato rico com imagem, título, descrição e CTA
- Contador de cliques via `post_meta`
- URLs ofuscadas (`?cct=` + `?r=` em base64) para evitar bloqueios de WAF/ModSecurity
- Handler seguro com validação de status `publish` e redirect `302`

### Módulo de Eventos
- CPT `event` aninhado no menu de Parceiros
- Fluxo de criação travado via parceiro (`post-new.php?post_type=event&parceiro_pai=ID`)
- Meta box na edição do parceiro com lista dos 5 próximos + botão `+ Novo Evento`
- Campos: data, hora, duração, preço, link de ingresso
- Parceiro vinculado **imutável** no editor de eventos
- Filtro automático de eventos passados no frontend
- Rewrite dinâmico: `/parceiros/%partner_slug%/evento/%event_slug%/`
- `archive-event.php` espelhado na estrutura do tema
- Template tags: `the_event_data()` (box de detalhes) e `the_next_events()` (lista na ficha)
- Colunas customizadas no admin; botão "Adicionar Novo" removido da listagem solta

### Cookie Consent (LGPD)
- Modal único (sem banner duplicado)
- Abertura automática no primeiro acesso + acionamento manual via link
- Preferências granulares: essencial, analytics, marketing
- CSS com transições suaves (`opacity` + `pointer-events`)
- Shortcode `[lgpd_consent_manager]` para menu/rodapé
- API JS: `window.cccConsent.has('analytics')`
- API PHP: `ccc_has_consent('marketing')`

## Plugin associado

### Set Location
Permite adicionar um "location picker" a páginas e parceiros, para mostrar a localização no mapa

---

## UI/UX & Frontend
- Footer fixo no fundo em páginas de pouco conteúdo (`body { display: flex; min-height: 100vh }`)
- `blockquote` estilizado com aspas tipográficas Unicode (`\201C` / `\201D`)
- Botão **"Citação"** adicionado ao seletor de formatação do TinyMCE
- Suporte a embeds otimizados (YouTube/Facebook) com fallbacks responsivos
- Captura automática de thumbnail do YouTube para posts na categoria `culturando`
- Design system coeso com variáveis CSS (`--color-secondary`, espaçamentos consistentes)

---

## API para Desenvolvedores

### Funções Globais
| Função | Descrição |
|--------|-----------|
| `ccc_has_consent( $category )` | Verifica consentimento LGPD (PHP) |
| `ccc_get_consent_data()` | Retorna array bruto do cookie de consentimento |
| `culturando_get_upcoming_events( $partner_id, $limit )` | WP_Query filtrada de eventos futuros |
| `the_event_data( $args )` | Exibe box de detalhes do evento |
| `get_event_data( $args )` | Retorna HTML do box de detalhes |
| `the_next_events( $args )` | Lista próximos eventos do parceiro |

### Hooks Disponíveis
| Hook | Tipo | Uso |
|------|------|-----|
| `culturando_after_partner_content` | Action | Inserir conteúdo após a ficha do parceiro |
| `culturando_event_meta_fields` | Filter | Modificar/adicionar campos do meta box de eventos |
| `culturando_banner_positions` | Filter | Registrar novas posições de banner |
| `culturando_map_api_key` | Filter | Injetar chave de API do mapa dinamicamente |

---
*Desenvolvido com foco em simplicidade, performance e conformidade legal. 🌿*