# Logs do Sistema — Resumo Executivo

> **Versão analisada:** `v6` (o módulo existia como "Registro de Atividades" na v5; a v6 o rebatizou como "Logs do Sistema" e o integrou ao registro de módulos)
> **Slug do módulo:** `logs-do-sistema` (tabela `modulos`) — **slug duplicado**: ids **7** (`status = true`) e **32** (`status = false`)
> **Natureza:** CMS (painel administrativo)
> **Estado:** migrado v5 -> v6, com **duplicidade de registro** introduzida na v6

---

## 1. Objetivo

Fornecer a trilha de auditoria do CMS: quem fez o quê, em que momento, de
qual IP e com qual navegador. A gravação é feita de forma **manual** por
cada controller, via o helper `activity()` do pacote
`spatie/laravel-activitylog`; a leitura é feita por uma única tela do CMS
(`/cms/log`) com DataTable, alimentada por um endpoint AJAX.

## 2. Efeito / Impacto

| Faixa | Efeito |
|---|---|
| Cidadão | Nenhum efeito direto. |
| Prefeitura (CMS) | Permite auditar quem cadastrou usuários, editou perfis, criou fornecedor, publicou notícia etc. |
| Transparência e legalidade | A trilha é a evidência técnica de quem operou o sistema; a ausência de proteção (o item de menu nunca aparece) reduz muito o valor dela. |
| Operação técnica | `activity_log` cresce sem rotação automática na aplicação (o pacote prevê `delete_records_older_than_days`, mas **não há cron configurado**). |

## 3. Comportamento

- Cada chamada `activity()->...->log('...')` grava uma linha em
  `activity_log` com: `log_name` (default `default`), `description` (a
  mensagem), `subject_type`/`subject_id` (o modelo afetado),
  `causer_type`/`causer_id` (quem executou), `properties` (JSON livre),
  `ip_address` e `browser`.
- `ip_address` e `browser` são preenchidos por um **observer** do Eloquent
  (`v6/app/Observers/ActivityObserver.php`), que captura `Request::ip()` e
  higieniza o `User-Agent`.
- A tela `/cms/log` mostra, no máximo, **5000 registros** (os mais
  recentes), sem paginação server-side, sem filtro por data, usuário ou
  tipo de ação.
- O rodapé do CMS mostra a **versão do sistema**, que vem de uma tabela
  **diferente** (`update_logs`), não de `activity_log`.
- **O item de menu "Logs do sistema" nunca é exibido** (ver seção 5).

## 4. Como o Usuário Interage

- Tela `/cms/log`: tabela com ID, Data, Descrição, Detalhes, IP, Navegador.
- A coluna "Detalhes" concatena todas as chaves do JSON `properties` no
  formato `chave: valor | chave: valor`.
- Não há exportação, não há detalhe expandível, não há busca.
- O acesso direto por URL funciona (`/cms/log`), desde que o usuário esteja
  autenticado (middleware `check.logged`).

## 5. Detalhes e Particularidades Técnicas

### 5.1 A duplicidade do slug `logs-do-sistema`

A migration `v6/database/migrations/2024_11_01_150206_create_modulos_table.php`
insere **duas** linhas com o mesmo slug:

```php
// ID 7
DB::table('modulos')->insert(['name' => 'Logs do Sistema', 'slug' => 'logs-do-sistema', 'status' => 1]);
// ID 32
DB::table('modulos')->insert(['name' => 'Logs do Sistema', 'slug' => 'logs-do-sistema', 'status' => 0]);
```

Consequências (todas verificadas no código e na base):

| Efeito | Mecanismo |
|---|---|
| `$modulos['logs-do-sistema']` vale sempre **false** | a própria view do AdminLTE calcula o array com `pluck('status','slug')` (`v6/resources/views/vendor/adminlte/page.blade.php:115-124`); com chave duplicada, **a última linha vence** (id 32, `status = false`). O mesmo acontece no `ModulosServiceProvider` (`v6/app/Providers/ModulosServiceProvider.php:22-24`) |
| O item de menu "Logs do sistema" **nunca aparece** | `v6/resources/views/vendor/adminlte/page.blade.php:284` exige `has_access(['registro-de-atividades.index']) && $modulos['logs-do-sistema']` |
| A permissão `registro-de-atividades.index` **não existe** | não há recurso com esse slug em `resources` |
| A linha "Logs do Sistema" da matriz de permissões **não aparece** | o recurso id 36 (`logs-do-sistema`) aponta para `modulo_id = 32`, cujo `status = false`, e `v6/resources/views/admin/role/form.blade.php:43` filtra por módulo ativo |
| A tela `/cms/modulos` mostra **duas linhas idênticas** | `Admin\ModulosController@index` lista todas as linhas de `modulos` |

Ou seja: o módulo existe, grava logs corretamente, mas é **invisível** na
UI e **inacessível por menu** — só por URL direta.

### 5.2 Outras particularidades

- A gravação é **manual** em cada controller: um controller novo que não
  chame `activity()` não é auditado. O model `App\Admin\User` tem o trait
  `LogsActivity` **comentado** (`v6/app/Http/Model/Admin/User.php:43`).
- `activity()->performedOn($this->userLog)` usa uma **instância nova** do
  model como "subject": o `subject_id` fica nulo e o `subject_type` é
  `App\Admin\User`.
- `SupportController` chama `activity()` **sem** `causedBy()`: o `causer_id`
  fica nulo mesmo sendo uma ação de usuário autenticado.

## 6. Estrutura de Dados

| Tabela | Papel |
|---|---|
| `activity_log` | Trilha de auditoria (spatie/laravel-activitylog v2.8) |
| `update_logs` | Versão do sistema exibida no rodapé do CMS (**outro** conceito) |
| `modulos` | Registro de módulos (com o slug duplicado) |
| `resources` | Recurso `logs-do-sistema` (id 36) apontando para o módulo duplicado |

Views SQL: **nenhuma** específica deste módulo.

## 7. Como Testar

- Autenticar e abrir `/cms/log` deve renderizar a tabela (HTTP 200).
- Executar qualquer ação auditada (ex.: criar usuário) e recarregar a
  página deve mostrar uma linha nova com IP e navegador preenchidos.
- Verificar que `GET /cms/log` sem sessão redireciona (middleware
  `check.logged`).
- Verificar que o item "Logs do sistema" **não** aparece no menu do CMS
  (comportamento atual, consequência da duplicidade).

## 8. Migração para Laravel Moderno

- Trocar `spatie/laravel-activitylog` por um pacote compatível com
  Laravel 11 (`spatie/laravel-activitylog` v4) ou por uma tabela própria
  `audit_logs` com colunas explícitas.
- **Resolver a duplicidade**: `UNIQUE` em `modulos.slug` + uma migration
  que consolide os ids 7 e 32 (o id 32 tem o recurso associado; o id 7 é
  o que está ativo) e apague o órfão.
- Criar uma tela de auditoria com **paginação real**, filtros (período,
  usuário, módulo, ação) e exportação CSV.
- Gravar a auditoria por **observer/evento de domínio** em vez de por
  chamada manual em cada controller.

## 9. Resumo Geral

"Logs do Sistema" é a trilha de auditoria do CMS, gravada com
`spatie/laravel-activitylog` na tabela `activity_log` e lida por uma única
tela (`/cms/log`) com DataTable limitado a 5000 linhas. O ponto crítico do
módulo é a **duplicidade do slug `logs-do-sistema` na tabela `modulos`**
(ids 7 e 32, inseridos pela própria migration v6): como o `pluck('status',
'slug')` do `ModulosServiceProvider` resolve a chave duplicada em favor da
última linha, o valor de status do módulo é sempre `false` e o item de menu
"Logs do sistema" nunca é exibido. Somado a isso, a permissão checada no
menu (`registro-de-atividades.index`) nem existe no catálogo `resources`, e
o recurso `logs-do-sistema` aponta para a cópia desativada do módulo — o
resultado é um módulo funcional porém **invisível e não administrável**.
Somam-se a isso a ausência de paginação/filtros/exportação, o
`subject_id` sempre nulo nas gravações manuais e a confusão entre
`activity_log` (auditoria) e `update_logs` (versão do sistema).

---

## Índice do dossiê

| Arquivo | Conteúdo |
|---|---|
| `00-RESUMO.md` | Este documento |
| `01-ARQUITETURA.md` | Camadas, classes e o diagrama de fluxo |
| `02-MODELAGEM.md` | Estrutura de dados detalhada |
| `03-ROTAS-E-CONTROLADORES.md` | Rotas, controllers, requests, resources |
| `04-VIEWS-E-UX.md` | Telas, componentes, JS, assets |
| `05-REGRAS-E-PORTABILIDADE.md` | Particularidades e armadilhas |
| `06-MIGRACAO-MODERNA.md` | Plano de reconstrução em Laravel moderno |
| `07-TESTES.md` | Estratégia e casos de teste |
| `08-GAPS-E-DIVIDAS.md` | Pendências, riscos, comparativo v5 vs v6 |