========================================================================
 SISTEMA DE GESTÃO DE GABINETE (SGG)
 README_INSTALACAO.txt  —  Blocos 1 a 11 + Hotfix Geo 1.1 + Storage Refactor
========================================================================

Sistema web de gestão de mandato (vereador), em PHP 8 + MySQL, para
hospedagem cPanel. Sem Node, sem Composer, sem serviços pagos.

Módulos disponíveis nesta versão:

  - Bloco 1 — Núcleo: login, papéis e permissões (RBAC), equipe do
    gabinete, identidade visual, cadastro de cidadãos e aniversariantes
    (com trava de consentimento — LGPD).
  - Bloco 2 — Demandas: protocolo SGG-AAAA-NNNNNN, SLA, recorrência,
    histórico e anexos; territórios (regiões e bairros de Uberlândia) e
    secretarias; dashboard de demandas.
  - Bloco 3 — Biblioteca de Mídia: fotos, vídeos, áudios e documentos de
    campo; coleções/galerias; download seguro com log; tags.
  - Bloco 4 — Documentos: ofícios, indicações, requerimentos e respostas,
    com numeração própria por tipo/ano, modelos com variáveis {{...}} e
    impressão/PDF via navegador (papel timbrado).
  - Bloco 5 — WhatsApp (Z-API): caixa de saída (rascunho → fila → enviada),
    modelos de mensagem, trava de consentimento (LGPD), logs de envio e
    teste de conexão. Envio real via Z-API (cliente cURL nativo).
  - Bloco 6 — Agenda e Compromissos: reuniões, visitas, audiências e
    eventos; calendário em mês, semana, dia e lista (sem bibliotecas);
    status, resultado e encaminhamentos; dashboard da agenda; integração
    com demandas e cidadãos.
  - Bloco 7 — Mapa Territorial e Regiões: mapa Leaflet + OpenStreetMap,
    camadas com filtros, heatmap, dashboard territorial, inteligência
    territorial (rankings) e painel executivo. Foco em inteligência
    territorial para apoio à decisão do mandato.
  - Bloco 8 — Portal de Transparência: site público (sem login),
    responsivo, com página inicial, linha do tempo, ações do mandato,
    indicadores, mapa público, galeria, documentos, pesquisa,
    transparência territorial e prestação de contas. Publicação
    intencional (só aparece o que for explicitamente publicado) e gestão
    administrativa com auditoria. Acesse em /transparencia.
  - Bloco 9 — Visitas Técnicas e Tarefas: registro de visitas a campo
    (agendamento, execução, constatações, vínculo a demandas e mapa) e
    tarefas internas com prioridade, prazo, responsável, status e
    comentários.
  - Hotfix 9.1 — Relatórios e Auditoria: tela de Relatórios (/reports) com
    indicadores agregados e filtros, e tela de Auditoria (/audit) com o
    histórico de ações do sistema. Protegidas por permissão (reports.view
    e audit.view); a auditoria não é pública.
  - Fase 10 — Inteligência e Hardening: Sala de Situação do mandato
    (/situation) com indicadores e alertas executivos; relatórios
    estratégicos (bairros/regiões/categorias críticas, secretarias,
    produtividade da equipe); auditoria gerencial em linguagem amigável;
    e segurança reforçada — TROCA DE SENHA OBRIGATÓRIA no primeiro acesso
    (o admin não usa mais admin123), senha forte, headers de segurança e
    proteção contra força bruta no login.

  Importante (Bloco 7): as coordenadas dos bairros são APROXIMADAS (centro
  do bairro). Servem para inteligência territorial (agregações, heatmap,
  concentração por bairro/região) e NÃO representam a localização exata de
  imóveis ou cidadãos. No mapa, dados pessoais (nome de cidadão) só são
  exibidos a quem tem a permissão de ver cidadãos; com permissão apenas de
  relatórios territoriais, os cidadãos aparecem de forma anônima.

------------------------------------------------------------------------
 JÁ TENHO UMA VERSÃO INSTALADA — COMO ATUALIZAR?
------------------------------------------------------------------------

========================================================================
 ARMAZENAMENTO DE ARQUIVOS (sgg_storage)
========================================================================

A partir do Hotfix Geo 1.1 + Storage Refactor, os arquivos enviados ao
sistema ficam em sgg_storage/, FORA da pasta /sgg.

  ESTRUTURA RECOMENDADA:
    /raiz/
      sgg/           ← código (atualizável livremente)
      sgg_storage/   ← uploads (avatars, logos, mídias, anexos...)

  CONFIG (sgg/config/config.php):
    'storage_root' => dirname(__DIR__, 2) . '/sgg_storage',

  Cada subpasta de sgg_storage/ contém .htaccess bloqueando acesso direto.
  Arquivos são servidos via controllers seguros do sistema.

  Instalações anteriores: uploads antigos em /sgg/uploads continuam
  funcionando via fallback automático — não é necessário mover os arquivos.

  Veja MIGRACAO_STORAGE.md para instruções completas.

1. Faça BACKUP do banco e da pasta uploads (veja BACKUP.md).
2. Aplique as migrations que ainda faltam, em ordem (veja MIGRATIONS.md).
   Aplique apenas as posteriores à sua versão atual:
     migrations/001_bloco2_ajustes.sql   (para quem vinha do Bloco 1)
     migrations/002_bloco2_seeds.sql      (para quem vinha do Bloco 1)
     migrations/003_bloco3_midia.sql      (para quem vinha do Bloco 2)
     migrations/004_bloco6_agenda.sql     (para quem vinha do Bloco 5)
     migrations/005_bloco7_agenda_resultado.sql (para quem vinha do Bloco 6)
     migrations/006_bloco7_coords_seed.sql      (coordenadas dos bairros p/ o mapa)
     migrations/007_bloco8_documents_public.sql (para quem vinha do Bloco 7)
     migrations/008_fase10_hardening.sql        (para quem vinha do Bloco 9)
     migrations/009_hotfix101_neighborhoods.sql (saneia bairros duplicados/UTF8)
   (phpMyAdmin > Importar, um arquivo de cada vez. As migrations são
    idempotentes: reaplicar por engano não causa erro nem duplica dados.)
3. Substitua os arquivos de /app e /public pelos desta versão.
4. Pronto. NÃO reimporte o database.sql (isso apagaria seus dados).

IMPORTANTE — PRIMEIRO ACESSO (Fase 10):
No primeiro login o administrador (admin@admin.com / admin123) será OBRIGADO
a definir uma nova senha forte (mínimo 8 caracteres, com maiúscula, minúscula
e número). A senha admin123 deixa de valer após essa troca.

Se for uma INSTALAÇÃO NOVA, ignore o passo acima e siga normalmente
abaixo (o database.sql já vem com tudo do Bloco 2).

Requisitos:
  - PHP 8.0 ou superior
  - MySQL 8.0+ ou MariaDB 10.4+
  - Hospedagem cPanel (ou qualquer Apache com mod_rewrite)
  - Extensões PHP: pdo_mysql, fileinfo, mbstring (padrão na maioria dos cPanel)

NÃO é necessário: Node, npm, Composer, Laravel ou VPS.

------------------------------------------------------------------------
 INSTALAÇÃO EM cPANEL (leia antes de começar)
------------------------------------------------------------------------
Esta seção resume os pontos que mais geram dúvida em cPanel. Os passos
detalhados vêm logo abaixo.

1) ARQUIVO DE CONFIGURAÇÃO
   O pacote NÃO inclui o config.php (de propósito, para não sobrescrever
   a configuração do seu servidor nem expor credenciais). Você cria o seu:
     a) copie  config/config.example.php
     b) renomeie a cópia para  config/config.php
     c) preencha as credenciais do banco e o base_path
   Se o config.php não existir, o sistema mostra um aviso pedindo para
   criá-lo — isso é esperado.

2) HOST DO BANCO: use 127.0.0.1 (e não "localhost")
   Em config.php, prefira:
       'host' => '127.0.0.1',
   Por quê: "localhost" faz o PHP tentar conectar por SOCKET UNIX (um
   arquivo local do MySQL). Em muitos cPanel esse socket não está no
   caminho que o PHP espera, e a conexão falha com erro tipo
   "Can't connect to local MySQL server through socket".
   Já "127.0.0.1" força a conexão por TCP/IP (rede), que é a forma padrão
   e estável de acesso ao MySQL em cPanel.
   Observação: se o seu provedor informar um host específico
   (ex.: "mysql.seuprovedor.com"), use o que ele indicar.

3) base_path: depende de ONDE o site fica
   O base_path informa ao sistema o "prefixo" da URL. Use conforme o caso:

     CASO A — site na RAIZ do domínio
       Ex.: https://seudominio.com.br/  (apontando para a pasta public)
         'base_path' => '',

     CASO B — em subpasta, apontando direto para /public
       Ex.: https://seudominio.com.br/sgg/  (a pasta /sgg É a public)
         'base_path' => '/sgg',

     CASO C — subpasta com a estrutura completa dentro
       Ex.: https://seudominio.com.br/sgg/public/
         'base_path' => '/sgg/public',

   Regra prática: o base_path é exatamente o trecho que aparece na URL
   ANTES das rotas do sistema (/login, /dashboard, ...). Se ao abrir o
   sistema os links/CSS aparecerem quebrados, quase sempre é o base_path.

------------------------------------------------------------------------
 PASSO 1 — Criar o banco de dados (cPanel > MySQL Databases)
------------------------------------------------------------------------
1. Crie um banco de dados, ex.: "seuusuario_sgg".
2. Crie um usuário de banco e uma senha.
3. Associe o usuário ao banco com TODOS os privilégios.
4. Anote: nome do banco, usuário e senha.

------------------------------------------------------------------------
 PASSO 2 — Importar a estrutura (cPanel > phpMyAdmin)
------------------------------------------------------------------------
1. Abra o phpMyAdmin e selecione o banco criado.
2. Aba "Importar" > escolha o arquivo "database.sql" deste pacote.
3. Clique em "Executar". Devem ser criadas 44 tabelas e os dados iniciais
   (incluindo bairros e secretarias de Uberlândia).

------------------------------------------------------------------------
 PASSO 3 — Enviar os arquivos
------------------------------------------------------------------------
Há duas formas. A OPÇÃO A é mais segura; use-a se possível.

  OPÇÃO A (recomendada — app fora do public_html)
  -----------------------------------------------
  1. Envie as pastas /app, /config, /uploads, /storage e o database.sql
     para uma pasta FORA do public_html (ex.: /home/seuusuario/sgg_app/).
  2. Envie o CONTEÚDO da pasta /public para dentro do public_html
     (ou para uma subpasta, ex.: public_html/gabinete/).
  3. Edite o public_html/index.php e ajuste o caminho do bootstrap:
       require __DIR__ . '/../sgg_app/app/bootstrap.php';
     (aponte para onde você colocou a pasta app).

  OPÇÃO B (mais simples — tudo dentro do public_html)
  ---------------------------------------------------
  1. Envie a pasta inteira do sistema para dentro do public_html, ex.:
       public_html/gabinete/
  2. Aponte o navegador para a subpasta /public, ex.:
       https://seudominio.com/gabinete/public/
     As pastas /app, /config, /uploads e /storage já vêm protegidas por
     arquivos .htaccess que bloqueiam acesso direto via navegador.

------------------------------------------------------------------------
 PASSO 4 — Configurar a conexão
------------------------------------------------------------------------
1. Na pasta /config, copie "config.example.php" para "config.php"
   (se ainda não existir).
2. Edite config.php e preencha os dados do banco:
       'host' => '127.0.0.1',
       'name' => 'seuusuario_sgg',
       'user' => 'seuusuario_user',
       'pass' => 'sua_senha',

   IMPORTANTE sobre o 'host': em cPanel use '127.0.0.1', NÃO 'localhost'.
   Muitos servidores interpretam 'localhost' como conexão por socket Unix
   (um arquivo local do MySQL) que pode não estar no caminho esperado,
   resultando em erro de conexão. Usar '127.0.0.1' força a conexão por
   rede (TCP), que é a forma padrão de acesso ao MySQL em cPanel. Se o seu
   provedor indicar um host específico (ex.: 'mysql.seuprovedor.com'), use o
   que ele informar.
3. Ajuste 'base_path' conforme onde o sistema ficou:
       - Na raiz do domínio:        'base_path' => '',
       - Em subpasta /gabinete/public: 'base_path' => '/gabinete/public',
4. Deixe 'env' => 'production' em produção.

------------------------------------------------------------------------
 PASSO 5 — Permissões de pasta
------------------------------------------------------------------------
Garanta que estas pastas tenham permissão de escrita (geralmente 755):
   /uploads   (e subpastas branding, media)
   /storage   (e subpasta logs)

------------------------------------------------------------------------
 PASSO 6 — Acessar o sistema
------------------------------------------------------------------------
Abra o endereço no navegador e faça login:

   E-mail:  admin@admin.com
   Senha:   admin123

>>> IMPORTANTE: troque a senha do admin assim que possível.
    (A troca obrigatória no primeiro login será adicionada em bloco futuro.)

------------------------------------------------------------------------
 LIMITES DE UPLOAD (logo/favicon e futuras mídias)
------------------------------------------------------------------------
Os limites de tamanho por tipo são configuráveis no banco (tabela settings).
Se precisar enviar arquivos maiores, ajuste também no PHP do cPanel:
   upload_max_filesize e post_max_size (em "MultiPHP INI Editor").

------------------------------------------------------------------------
 ESTRUTURA DO PACOTE
------------------------------------------------------------------------
   /app                  código da aplicação (MVC)
   /config               configuração (config.php)
   /public               raiz web (index.php, assets)
   /uploads              arquivos enviados (fora do webroot na Opção A)
   /storage              logs da aplicação
   /migrations           scripts de atualização do banco (ver MIGRATIONS.md)
   /database.sql         estrutura + dados iniciais (instalação nova)
   /README_INSTALACAO.txt
   /MIGRATIONS.md        como atualizar o banco entre versões
   /BACKUP.md            como fazer backup e restaurar
   /IMPLEMENTATION_STATUS.md
   /CHANGELOG.md
   /VERSION.txt

------------------------------------------------------------------------
 SUPORTE / PRÓXIMOS BLOCOS
------------------------------------------------------------------------
Este pacote entrega os Blocos 1 e 2 de 9. Veja IMPLEMENTATION_STATUS.md
para o que já está pronto e o que vem a seguir (mídia, documentos, agenda,
mensagens, transparência). Módulos futuros aparecem como "Em breve" no menu.
========================================================================

== Bloco 15 — Central de Comunicação e Marketing ==
Novo módulo em /communication (fluxo de comunicação institucional integrado
às demandas, com estrutura/status/permissões/auditoria próprios). Migration
021_communication.sql cria 6 tabelas communication_* + 6 permissões próprias.
Em instalação nova, database.sql já inclui tudo. Permissões: admin e chefe de
gabinete (todas), marketing (todas menos create), equipe de rua (view+create),
vereador (view). Não altera o status da demanda; não duplica demandas.

== Bloco 16 — Consolidação / Auditoria Geral (v1.0) ==
Auditoria técnica completa (arquitetura, banco, segurança, performance, RBAC,
uploads, CSS/JS, mobile, UX, acessibilidade). Não cria módulos nem altera regras.
Melhorias: (1) defesa em profundidade contra path traversal no download/stream de
mídia (realpath + Storage::isSafe); (2) log de tentativa de login malsucedida; (3)
fim do N+1 na listagem da Central de Comunicação (miniaturas em lote). Sem novas
migrations; instalação inalterada (database.sql + migrations 001..021).
