# Inventário do Banco de Dados — SGG

Inventário definitivo das **47 tabelas** do Sistema de Gestão de Gabinete.
Serve como referência de manutenção e entendimento da arquitetura.

**Convenções gerais (valem para quase todas as tabelas):**
- `id` — chave primária (BIGINT UNSIGNED AUTO_INCREMENT).
- `tenant_id` — suporte multi-inquilino (SaaS); padrão 1 no MVP.
- `created_at` / `updated_at` — carimbos de tempo.
- `deleted_at` — exclusão lógica (soft delete) onde aplicável.
- `mandate_id` — vínculo ao mandato (multi-mandato) onde aplicável.

**"Bloco"** indica em que etapa a tabela passou a ser *usada* pela aplicação.
Quase todas foram **modeladas no schema v4** (antes da implementação); a coluna
reflete o bloco que de fato a colocou em uso, para orientar manutenção.

---

## Núcleo, acesso e identidade

| Tabela | Finalidade | Bloco | Observações |
|--------|------------|-------|-------------|
| `tenants` | Inquilinos do SaaS (cada gabinete é um tenant). | 1 | Raiz do isolamento multi-inquilino. |
| `mandates` | Mandatos (legislaturas) de um tenant. | 1 | `is_active` indica o mandato corrente; usado em documentos e agenda. |
| `mandate_users` | Vínculo N:N entre usuários e mandatos. | 1 | Permite equipe atuar em mandatos distintos. |
| `roles` | Papéis de acesso (admin, chefe de gabinete, assessor, equipe de rua, marketing, etc.). | 1 | Base do RBAC. |
| `permissions` | Permissões granulares (ex.: `demands.create`, `media.upload`). | 1 | Catálogo de permissões. |
| `role_permissions` | Vínculo N:N papéis ↔ permissões. | 1 | Define o que cada papel pode fazer. |
| `users` | Usuários do sistema (equipe do gabinete). | 1 | Ganhou `phone`, `position`, `region_id` (Bloco 2). Senha em bcrypt. `must_change_password`/`password_changed_at` (Fase 10) forçam troca no 1º acesso. Já tinha `failed_attempts`/`locked_until` (rate limit). |
| `user_neighborhoods` | Bairros atendidos por cada membro da equipe (N:N). | 2 | Criada na migration 001. |
| `tenant_branding` | Identidade visual (logos, favicon, cores, slogan). | 1 | Uma linha por tenant. |
| `mandate_profile` | Dados institucionais (vereador, partido, número, legislatura, contatos, redes). | 1 | Usado no papel timbrado dos documentos. |
| `sessions` | Sessões persistidas (apoio ao controle de sessão). | 1 | Complementa a sessão PHP. |
| `settings` | Configurações chave/valor por tenant. | 1 | Guarda também credenciais Z-API (Bloco 5). |

## Território

| Tabela | Finalidade | Bloco | Observações |
|--------|------------|-------|-------------|
| `regions` | Regiões do município (Norte, Sul, Leste, Oeste, Central, etc.). | 2 | Seed de Uberlândia (migration 002). Unique (tenant, nome). |
| `neighborhoods` | Bairros, vinculados a uma região. | 2 | 23 bairros de Uberlândia no seed. Coordenadas para o mapa. Unicidade por (tenant,name) reforçada no Hotfix 10.1 (migration 009) após saneamento de duplicados/UTF8. |
| `departments` | Secretarias/órgãos de destino de ofícios e demandas. | 2 | Unique (tenant, sigla). |
| `request_sources` | Origem do contato/solicitação (telefone, WhatsApp, presencial, etc.). | 2 | Tabela (não-ENUM) para flexibilidade. |

## Cidadãos

| Tabela | Finalidade | Bloco | Observações |
|--------|------------|-------|-------------|
| `citizens` | Cadastro de cidadãos atendidos. | 1 | Ganhou `nickname`, `is_community_leader`, `source_id` (Bloco 2). Aniversário dia/mês sem ano; consentimento e opt-out de WhatsApp (LGPD). |
| `citizen_interactions` | Histórico de interações com o cidadão. | 1 | Alimentado por mensagens, demandas, etc. |

## Demandas, protocolos e SLA

| Tabela | Finalidade | Bloco | Observações |
|--------|------------|-------|-------------|
| `demand_categories` | Categorias de demanda (iluminação, asfalto, etc.). | 2 | Tem `sla_days` e `default_department_id` (secretaria padrão). |
| `protocol_counters` | Contador transacional de protocolo de demandas por ano. | 2 | Garante numeração `SGG-AAAA-NNNNNN` sem colisão. |
| `demand_groups` | Agrupamento de demandas recorrentes (mesma categoria+bairro+ref). | 2 | Conta ocorrências para identificar problemas crônicos. |
| `demands` | Demandas/solicitações dos cidadãos. | 2 | Protocolo, SLA, status, recorrência, coordenadas (`occur_latitude`/`occur_longitude`) para o mapa. |
| `demand_status_history` | Linha do tempo de cada demanda (status, comentários). | 2 | Trilha completa por demanda. |
| `demand_public_tokens` | Tokens para consulta pública de protocolo. | (schema) | Reservado ao portal de transparência (Bloco 8). |

## Documentos

| Tabela | Finalidade | Bloco | Observações |
|--------|------------|-------|-------------|
| `document_templates` | Modelos de documento com variáveis `{{...}}`. | 4 | Ofício, indicação, requerimento, etc. |
| `document_counters` | Contador transacional de documentos por tipo/ano. | 4 | Numeração `OF-AAAA-NNNN`, `IND-...` sem colisão (hotfix Bloco 4). |
| `documents` | Documentos emitidos (ofícios, indicações, respostas). | 4 | Vincula a demanda e secretaria; impressão/PDF via navegador. Ganhou `is_public`/`published_at` (Bloco 8) para publicação intencional no portal. |

## Mídia

| Tabela | Finalidade | Bloco | Observações |
|--------|------------|-------|-------------|
| `media_files` | Biblioteca de fotos, vídeos, áudios e documentos de campo. | 3 | Servida só por controller. Ganhou `region_id` (migration 003). |
| `media_collections` | Coleções/galerias (por bairro, evento, campanha, institucional). | 3 | — |
| `media_collection_items` | Itens de cada coleção (N:N ordenável). | 3 | — |
| `media_download_logs` | Log de downloads (usuário, IP, agente). | 3 | Governança e auditoria. |
| `media_usage_logs` | Registro de uso pelo marketing (marcar como utilizado). | 3 | — |
| `media_tags` | Tags de mídia. | 3 | Criada na migration 003. |
| `media_file_tags` | Vínculo N:N mídia ↔ tag. | 3 | Criada na migration 003. |
| `media_share_queue` | Fila de seleção para compartilhamento via WhatsApp. | 3 | Estrutura; envio real ocorre pelo Bloco 5. |

## Mensagens / WhatsApp

| Tabela | Finalidade | Bloco | Observações |
|--------|------------|-------|-------------|
| `message_templates` | Modelos de mensagem (WhatsApp) com variáveis. | 5 | Categorias: aniversário, demanda, protocolo, etc. |
| `message_outbox` | Caixa de saída (rascunho → fila → enviada). | 5 | Trava de consentimento (LGPD); provider zapi/manual. |
| `message_logs` | Log de envio com resposta do provedor (JSON). | 5 | Trilha de ações e erros. |

## Agenda e tarefas

| Tabela | Finalidade | Bloco | Observações |
|--------|------------|-------|-------------|
| `agenda_events` | Compromissos (reuniões, visitas, audiências, eventos). | 6 | Ampliada nas migrations 004 (`status`, `region_id`, ENUM type) e 005 (`resultado`, `encaminhamentos`). |
| `technical_visits` | Visitas técnicas (agendamento, execução, achados). | 9 | CRUD no Bloco 9; aparece na camada de visitas do mapa. |
| `tasks` | Tarefas internas. | 9 | CRUD no Bloco 9 (prioridade, prazo, status, responsável). |
| `task_comments` | Comentários de tarefas. | 9 | Usada na tela de detalhe da tarefa. |

## Transparência, linha do tempo e auditoria

| Tabela | Finalidade | Bloco | Observações |
|--------|------------|-------|-------------|
| `mandate_timeline` | Linha do tempo pública do mandato. | 8 | Exibida no portal quando `is_public=1`. |
| `public_reports` | Ações do mandato divulgadas no portal. | 8 | Exibidas quando `is_published=1`. |
| `audit_logs` | Auditoria de ações (criar, editar, excluir, enviar, etc.). | 1 | Usada por todos os módulos. |
| `consent_logs` | Registro de consentimentos (LGPD). | (schema) | Apoia a trilha de consentimento. |
| `attachments` | Anexos administrativos polimórficos (ex.: de demandas). | 2 | Separado de `media_files` (mídia rica). Servido por controller. |

---

## Débitos técnicos / pendências de schema

- **Coordenadas dos bairros são APROXIMADAS.** As coordenadas seedadas
  (`database.sql` / `006_bloco7_coords_seed.sql`) representam o centro
  aproximado de cada 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. Feições sem coordenada própria
  herdam a do bairro (COALESCE). Para precisão de endereço, preencha as
  coordenadas próprias da demanda/visita.
- **Dados territoriais ≠ dados pessoais.** As camadas e a busca do mapa só
  expõem nome de cidadão a quem tem `citizens.view`; com apenas `reports.view`,
  os cidadãos aparecem de forma anônima ("Cidadão") e não são pesquisáveis.

- **`agenda_events.participants`** hoje é um campo de texto livre. Há um débito
  técnico registrado para, no futuro, modelar participantes de forma
  estruturada (vínculo a `users`/`citizens`). Anotado no CHANGELOG e no
  IMPLEMENTATION_STATUS.
- **`mandate_timeline`, `public_reports`** são alimentadas pelo Bloco 8
  (transparência). **`demand_public_tokens`, `consent_logs`** seguem modeladas
  no schema v4 sem interface dedicada — apoio a recursos futuros.

## Migrations que alteraram o schema base

| Migration | Bloco | Efeito |
|-----------|-------|--------|
| `001_bloco2_ajustes.sql` | 2 | Colunas em `citizens`/`users`; tabela `user_neighborhoods`; uniques em `regions`/`departments`. |
| `002_bloco2_seeds.sql` | 2 | Seeds de Uberlândia (regiões, bairros, secretarias). |
| `003_bloco3_midia.sql` | 3 | `region_id` em `media_files`; tabelas `media_tags`, `media_file_tags`, `media_share_queue`. |
| `004_bloco6_agenda.sql` | 6 | `status`, `region_id` e ENUM `type` ampliado em `agenda_events`. |
| `005_bloco7_agenda_resultado.sql` | 7 | `resultado` e `encaminhamentos` em `agenda_events`. |

> Para instalações novas, basta importar o `database.sql` (já consolidado).
> As migrations são para quem já tem uma versão anterior instalada. Todas são
> idempotentes. Ver `MIGRATIONS.md`.