# Logs do Sistema — Arquitetura

> O módulo tem **duas metades** independentes: a **escrita** (dispersa por
> todo o CMS, via `activity()`) e a **leitura** (uma única tela).
> A duplicidade do slug `logs-do-sistema` na tabela `modulos` é o problema
> estrutural que domina o módulo.

---

## 1. Fluxo de escrita (spread operator)

```
Controller / Service (qualquer um do CMS)
   │  activity()
   │      ->performedOn($model)     // subject_type + subject_id
   │      ->causedBy(Sentinel::getUser())  // causer_type + causer_id
   │      ->withProperty('Detalhe', 'texto livre')
   │      ->log('Listou usuários')   // description
   ▼
Spatie\Activitylog\ActivityLogger
   │  monta o model Activity
   ▼
Spatie\Activitylog\Models\Activity  (AppServiceProvider registra o observer)
   │  -> creating(ActivityObserver)
   │      ip_address = Request::ip()
   │      browser    = higienização do User-Agent
   ▼
tabela activity_log
```

Exemplos reais de escrita:

| Local | Código | `log_name` |
|---|---|---|
| `v6/app/Http/Controllers/Admin/UserController.php:38-42` | `activity()->performedOn($this->userLog)->causedBy(Sentinel::getUser())->withProperty('Detalhe', 'Listado por: ' . ...)->log('Listou usuários')` | `default` |
| `v6/app/Http/Controllers/Admin/UserController.php:136-137` | `->log('Cadastro de usuário')` | `default` |
| `v6/app/Http/Controllers/Admin/RoleController.php:32-33` | `->log('Listou Roles')` | `default` |
| `v6/app/Http/Controllers/Admin/LoginController.php:34-35` | `->log('Login no sistema')` | `default` |
| `v6/app/Http/Controllers/Prefecture/SupportController.php:113-116` | `activity()->withProperty('Detalhe', ...)->log('Página de suporte')` — **sem `causedBy`** | `default` |

> Nenhuma gravação usa `->logName()`. Portanto **todas** as linhas têm
> `log_name = 'default'` (valor de `config/activitylog.php`:
> `'default_log_name' => 'default'`), o que torna o índice
> `activity_log_log_name_index` inútil para filtragem.

---

## 2. Fluxo de leitura

```
GET /cms/log  (rota 'log.index', middleware check.logged)
   ▼
Admin\ActivityLogController@index
   │  $title = "Logs";
   ▼
view('admin.activities-logs.index')
   │  <table id="tabela_logs">
   ▼
assets/js/custom/config/logs/datatable.js
   │  runDatatables('logs', collums)
   ▼
GET /cms/datatable/logs   (rota nomeada 'logs')
   ▼
Prefecture\DatatableController@get_logs
   │  ActivityLog::orderBy('created_at','desc')->limit(5000)->get()
   ▼
struct_logs($logs)
   │  json_decode($value->properties)  e concatena "chave: valor | "
   ▼
Yajra DataTables JSON  →  DataTable no navegador
```

---

## 3. Diagrama do efeito da duplicidade do slug

```
        modulos (58 linhas)
   ┌────────┬──────────────────────────┬──────────┐
   │ id     │ slug                     │ status   │
   ├────────┼──────────────────────────┼──────────┤
   │  7     │ logs-do-sistema          │  true    │  ← módulo "ativo"
   │ 32     │ logs-do-sistema          │  false   │  ← cópia "desativada"
   └────────┴──────────────────────────┴──────────┘
                       │
        pluck('status','slug')   ← chave duplicada
                       │
                       ▼
   $modulos['logs-do-sistema'] === false     (vence a ÚLTIMA linha)
                       │
   ┌───────────────────┼────────────────────────────┐
   ▼                   ▼                            ▼
menu do AdminLTE   role/form.blade.php        tela /cms/modulos
($modulos[...]     (filtra por                (mostra as DUAS
 é false →         $resource->modulo->status   linhas, com
 item oculto)       do recurso 36 →             id HTML duplicado
                    modulo 32 (false) →          "logs-do-sistema")
                    linha oculta)
```

---

## 4. Classes envolvidas

| Classe | Caminho | Papel |
|---|---|---|
| `Admin\ActivityLogController` | `v6/app/Http/Controllers/Admin/ActivityLogController.php` | Única action: `index()`; renderiza a view |
| `App\Admin\ActivityLog` | `v6/app/Http/Model/Admin/ActivityLog.php` | Model Eloquent da tabela `activity_log` |
| `Prefecture\DatatableController` | `v6/app/Http/Controllers/Prefecture/DatatableController.php` | `get_logs()` e `struct_logs()` |
| `App\Observers\ActivityObserver` | `v6/app/Observers/ActivityObserver.php` | Preenche `ip_address` e `browser` no evento `creating` |
| `AppServiceProvider` | `v6/app/Providers/AppServiceProvider.php:22` | Registra o observer: `Activity::observe(ActivityObserver::class)` |
| `App\Http\Model\Admin\Modulos` | `v6/app/Http/Model/Admin/Modulos.php` | Registro de módulos (com a duplicidade) |
| `App\Http\Model\Admin\Resource` | `v6/app/Http/Model/Admin/Resource.php` | Recurso `logs-do-sistema` → `modulo_id = 32` |
| `Admin\ModulosController` | `v6/app/Http/Controllers/Admin/ModulosController.php` | Tela `/cms/modulos` que expõe as duas linhas duplicadas |
| `ModulosServiceProvider` | `v6/app/Providers/ModulosServiceProvider.php` | Injeta `$modulos` nas views do portal e do dashboard |
| `App\Http\Model\Prefecture\UpdateLogs` | `v6/app/Http/Model/Prefecture/UpdateLogs.php` | **Outro** conceito: versão do sistema (`update_logs`) |
| `UpdateVersion` | `v6/app/Console/Commands/UpdateVersion.php` | Comando `update:logs` que insere a próxima versão |

---

## 5. Dependências externas

| Pacote | Versão | Uso |
|---|---|---|
| `spatie/laravel-activitylog` | `^2.8` | gravação e leitura da trilha (`activity()`, model `Activity`) |
| `yajra/laravel-datatables` | `^1.5` | JSON da listagem |
| `laravel/framework` | `5.5.*` | observers, `Request::ip()` |

Configuração: `v6/config/activitylog.php`
(`table_name = 'activity_log'`, `default_log_name = 'default'`,
`delete_records_older_than_days = 365`, `enabled = env('ACTIVITY_LOGGER_ENABLED', true)`).

---

## 6. O que NÃO pertence a este módulo

| Item | Motivo |
|---|---|
| `update_logs` / `UpdateVersion` / rodapé com a versão | É o **histórico de versões do software**, não a auditoria de ações. Vive no módulo `novidades` por afinidade, mas tem tabela, model e comando próprios. |
| `change_logs` / `Admin\ChangeLogController` | Módulo `novidades`. |
| `ombudsman_request_logs` | Auditoria da Ouvidoria, módulo `ouvidoria`. |
| `service_letter_access_logs` | Módulo `carta-de-servicos`. |

---

## 7. Mapa de arquivos

```
app/Http/Controllers/Admin/ActivityLogController.php
app/Http/Controllers/Prefecture/DatatableController.php   (get_logs, struct_logs)
app/Http/Model/Admin/ActivityLog.php
app/Http/Model/Admin/Modulos.php
app/Observers/ActivityObserver.php
app/Providers/AppServiceProvider.php
app/Providers/ModulosServiceProvider.php
app/Console/Commands/UpdateVersion.php
config/activitylog.php
database/migrations/2018_09_05_143852_create_activity_log_table.php
database/migrations/2025_01_16_210444_add_ip_address_to_activity_log.php
database/migrations/2023_03_22_095658_create_update_logs_table.php
database/migrations/2024_11_01_150206_create_modulos_table.php
resources/views/admin/activities-logs/index.blade.php
resources/views/admin/modulos/index.blade.php
resources/views/admin/modulos/form.blade.php
resources/views/vendor/adminlte/page.blade.php
public/assets/js/custom/config/logs/datatable.js
public/assets/js/custom/utilities/table.js
```