# 1. Clone com submodules
git clone --recurse-submodules <repo-url>
cd mapas

# 2. Variáveis de ambiente (copie e edite)
cp .env.example .env          # se existir, senão crie baseado no compose.yaml

# 3. Suba o stack
docker compose up -d

# app em  http://localhost:8080
# HTTPS   https://mapas.localhost:8443  (requer confiar no CA do Caddy — veja abaixo)
# Mailpit http://localhost:8025

# 4. Dependências JS (dentro do container)
docker compose exec mapas bash -c "cd src && pnpm install && pnpm run build"

# Instalar o CA do Caddy no sistema (CachyOS/Arch)
docker compose exec caddy cat /data/caddy/pki/authorities/local/root.crt > /tmp/caddy-root.crt
sudo trust anchor --store /tmp/caddy-root.crt && sudo update-ca-trust

# Instalar no Chrome/Chromium
mkdir -p $HOME/.pki/nssdb
certutil -d sql:$HOME/.pki/nssdb -N --empty-password 2>/dev/null || true
certutil -d sql:$HOME/.pki/nssdb -A -t "CT,," -n "Caddy Local CA" -i /tmp/caddy-root.crt
# Reinicie o Chrome

mapas/
├── config/             # Config PHP por feature (db, mailer, maps, etc.)
├── dev/                # Scripts de desenvolvimento (bash.sh, shell.sh, psql.sh)
├── scripts/            # Scripts utilitários (execute-job, db-update, run-tests)
├── src/
│   ├── core/           # Framework base (App, Entity, Controller, Hooks, Theme…)
│   ├── modules/        # Features modulares (Opportunities, Home, GeoDivisions…)
│   ├── plugins/        # Plugins opcionais (SpamDetector, Metabase, MapasBlame…)
│   ├── themes/
│   │   ├── BaseV1/     # Tema legado
│   │   ├── BaseV2/     # Tema moderno (base)
│   │   └── RedeMapas/  # ← tema ativo (submodule git separado)
│   └── db-updates.php  # Migrações (auto-aplicadas no start do container)
├── tests/              # PHPUnit (necessita DB — roda dentro do container)
├── compose.yaml        # Stack principal
└── compose.override.yml# Caddy HTTPS local

cd src/themes/RedeMapas
git add <arquivo> && git commit -m "fix: ..."

# Depois, no repo pai:
cd ../../..
git add src/themes/RedeMapas && git commit -m "chore: bump RedeMapas submodule"

RedeMapas/
├── Theme.php           # _init(): hooks, controllers, assets, metadata
├── assets-src/
│   ├── js/             # Fontes JS (esbuild)
│   └── sass/           # Fontes CSS (dart-sass)
├── assets/             # Build output (.gitignored no submodule)
├── layouts/            # Templates PHP de layout
├── views/              # Templates PHP de views
├── Controllers/        # Controllers HTTP do tema (ex: Push)
├── Jobs/               # JobTypes assíncronos (ex: SendWebPushNotification)
├── Push/               # Infraestrutura Web Push (SubscriptionStore, PushConfigBuilder)
└── Pwa/                # PWA (WebmanifestBuilder, HeadTagsBuilder)

$app = \MapasCulturais\App::i();
$app->em;          // Doctrine EntityManager
$app->user;        // usuário logado (GuestUser se anônimo)
$app->config[...]; // configurações
$app->log;         // Monolog logger

$app->hook('entity(Agent).save:before', function() {
    // $this = instância da entidade
});

$app->hook('view.render(site/index):before', function() {
    // roda antes de renderizar a view site/index
});

$app->hook('mapas.printJsObject:before', function() {
    $this->jsObject['minhaConfig'] = [...]; // injeta no objeto JS global `Mapas`
});

// Registrar
$app->registerController('meu', MeuController::class);

// Métodos = verbos HTTP + ação
// GET  /meu/listar/    → GET_listar()
// POST /meu/salvar/    → POST_salvar()
class MeuController extends Controller {
    public function GET_listar(): void {
        $this->json(['items' => [...]]);
    }
}

# Processar jobs pendentes
docker compose exec mapas ./scripts/execute-job.sh

$app->registerMetadata(
    new \MapasCulturais\Definitions\Metadata('minhaChave', ['label' => 'Minha chave', 'private' => true]),
    \MapasCulturais\Entities\User::class
);

// Leitura/escrita
$user->getMetadata('minhaChave');
$user->setMetadata('minhaChave', json_encode($valor)); // arrays: sempre json_encode
$user->save(true);

# Dentro do container
docker compose exec mapas bash
cd src
pnpm run build    # produção
pnpm run dev      # dev com source maps
pnpm run watch    # watch mode

# Todos os testes
docker compose exec mapas ./vendor/bin/phpunit tests/

# Arquivo específico
docker compose exec mapas ./vendor/bin/phpunit tests/src/EntitiesTest.php

# Método específico
docker compose exec mapas ./vendor/bin/phpunit tests/src/EntitiesTest.php --filter testAgentCreation

docker compose exec mapas ./scripts/shell.sh
# ou
docker compose exec mapas ./dev/shell.sh

// No prompt PsySH:
$app->disableAccessControl();
$user = $app->repo('User')->find(1);
// ... manipular entidades
$app->enableAccessControl();

# Aplicar migrações pendentes
docker compose exec mapas ./scripts/db-update.sh

# Conectar ao PostgreSQL
docker compose exec mapas ./dev/psql.sh
# ou direto
docker compose exec postgres psql -U mapas -d mapas

// Em Theme.php, hook mapas.printJsObject:before:
$app->hook('mapas.printJsObject:before', function() {
    $this->jsObject['minhaConfig'] = ['key' => 'value'];
});

// No JS:
var config = window.Mapas?.minhaConfig;

# PHP errors
docker compose exec mapas tail -f var/logs/error.log

# Logs do container
docker compose logs mapas --tail=50 -f

# Habilitar debug verbose
# Em dev/config.d/0.main.php:
'app.mode' => 'development',
# E definir APP_DEBUG=true no .env

# Conectar
docker compose exec mapas ./dev/psql.sh

# Ver metadata de um usuário
SELECT * FROM user_metadata WHERE object_id = 1;

# Jobs pendentes
SELECT * FROM job WHERE status = 0 ORDER BY create_timestamp DESC LIMIT 10;

# Notificações de um usuário
SELECT * FROM notification WHERE user_id = 1 ORDER BY create_timestamp DESC LIMIT 10;

Mapas = {
  baseURL: 'https://mapas.localhost:8443/',
  assetURL: '...',
  userId: 42,               // null se não logado
  user: { id, name, ... },
  config: {
    locale: 'pt-BR',
    timezone: 'America/Sao_Paulo',
    currency: 'BRL',
    iconset: { 'chevron-right': 'ph:chevron-right', ... },
  },
  request: { controller, action, urlData, id },
  routes: { ... },          // mapa de rotas registradas
  EntitiesDescription: { agent, space, event, project, ... },
  Taxonomies: { ... },
  // injetado pelo RedeMapas:
  redemapasPush: { enabled, publicKey, subscribeUrl, serviceWorkerUrl, strings },
}

// Em Theme.php ou Module.php — hook mapas.printJsObject:before
$app->hook('mapas.printJsObject:before', function() {
    $this->jsObject['minhaConfig'] = ['key' => 'value'];
});

// No JS:
const config = window.Mapas?.minhaConfig;

PHP importa componente → template renderizado → serializado em $TEMPLATES (JSON)
↓
Browser recebe window.$TEMPLATES = { 'mc-icon': '<svg>...</svg>', ... }
↓
vue-init.js registra globalmente: app.component('mc-icon', { template: $TEMPLATES['mc-icon'], ...script.js })
↓
Vue monta em #main-app

<?php $this->import('mc-icon'); ?>
<mc-icon name="ph:star" />

<?php $this->import('entity-card'); ?>
<entity-card :entity="<?= json_encode($entity->simplify('id,name,type')) ?>"></entity-card>

// Cria a app Vue 3
const app = createApp({ ... })

// Plugins registrados:
app.use(pinia)           // Pinia — gerenciamento de estado global
app.use(iconify)         // Iconify — ícones (via Mapas.config.iconset)
app.use(mediaQuery)      // $media() — breakpoints reativos

// Stores Pinia globalmente:
useEntitiesCache()       // cache de entidades buscadas via API
useEntitiesLists()       // listas paginadas
useGlobalState()         // estado geral ($MAPAS, $global)

// Propriedades globais:
app.config.globalProperties.$MAPAS = Mapas
app.config.globalProperties.$DESCRIPTIONS = Mapas.EntitiesDescription
app.config.globalProperties.$TAXONOMIES = Mapas.Taxonomies

// Monta em:
app.mount('#main-app')

import { useEntitiesCache } from './components-base/global-state.js'
const cache = useEntitiesCache()
cache.fetchEntity('agent', 42)

// Buscar entidade
const agent = await API.getEntity('agent', 42)

// Buscar lista com filtros
const agents = await API.find('agent', {
  'name': 'LIKE%fulano%',
  '@select': 'id,name,type',
  '@limit': 10,
})

// Buscar contagem
const total = await API.find('agent', { '@count': 1 })

// Salvar / atualizar
await API.save('agent', { id: 42, name: 'Novo nome' })

src/themes/BaseV2/assets-src/sass/
├── 0.settings/
│   ├── _variables.scss    ← design tokens: cores, fontes, espaçamentos
│   ├── _mixins.scss       ← @mixin desktop/mobile, size(), sr-only
│   ├── _typography.scss   ← @font-face Open Sans
│   └── _global.scss       ← reset global, h1-h6, a, p
├── 1.objects/             ← padrões reutilizáveis sem estilo visual
├── 2.components/          ← 180+ componentes UI
├── layouts/               ← header, footer, entity layout, tabs
└── pages/                 ← estilos específicos por página/entidade

// Cores de entidades
$color-agents:       #EF7B45;
$color-events:       #9C4EC7;
$color-spaces:       #5EA73A;
$color-projects:     #00ADEB;
$color-opportunities:#003F7E;

// RedeMapas sobrescreve em theme-BaseV2.scss:
$color-primary:      #c46e14;  // dourado
$color-secondary:    #cc9933;  // laranja

// Responsividade
$desktop-breakpoint: 50rem;  // 800px
@mixin desktop { @media (min-width: $desktop-breakpoint) { @content; } }
@mixin mobile  { @media (max-width: $desktop-breakpoint) { @content; } }

src/
├── package.json              # root — scripts: dev/build/watch --parallel --recursive
├── node_scripts/             # @mapas/scripts — esbuild-build.mjs, sass-compile-options.mjs
├── modules/Components/       # workspace package — compila os componentes Vue
├── themes/BaseV2/            # workspace package — compila o CSS base
└── themes/RedeMapas/         # workspace package (submodule) — home.js, sw.js, home.scss

cd src/themes/RedeMapas
npm run build    # ou: pnpm run build (se não for submodule isolado)

// Em Theme.php — _init()
$this->enqueueScript('app-v2', 'meu-script', 'js/meu-script.js');
$this->enqueueStyle('app-v2', 'meu-style', 'css/meu-style.css');

// Com dependência
$this->enqueueScript('app-v2', 'meu-script', 'js/meu-script.js', ['outro-script']);

// Injeta no <head>
$app->hook('template(<<*>>.head):end', function() { echo '<meta ...>'; });

// Injeta no início do <body>
$app->hook('template(<<*>>.body):begin', function() { echo '<div ...>'; });

// Injeta no final do <body> (antes de </body>)
$app->hook('template(<<*>>.body):end', function() { echo '<script>...</script>'; });

// Somente na home
$app->hook('template(site/index.body):end', function() { /* ... */ });

docker compose exec mapas php -r "
\$keys = \Minishlink\WebPush\VAPID::createVapidKeys();
echo 'Public:  ' . \$keys['publicKey'] . PHP_EOL;
echo 'Private: ' . \$keys['privateKey'] . PHP_EOL;
"

develop        → base para PRs
  └── feat/descricao-curta
  └── fix/descricao-curta

feat(scope): descrição    # nova funcionalidade
fix(scope): descrição     # correção de bug
chore: descrição          # manutenção