# Módulo História — Linha do Tempo SUCESU

> **Namespace raiz:** `V2\Modules\Institucional\Historia`
> **Blade namespace:** `v2-historia::`
> **Tabela:** `v2_historia_milestones`

---

## Sumário

1. [Visão Geral](#visão-geral)
2. [Estrutura de Diretórios](#estrutura-de-diretórios)
3. [Model — Milestone](#model--milestone)
4. [Controllers](#controllers)
5. [Views CMS](#views-cms)
6. [Views Portal](#views-portal)
7. [Rotas](#rotas)
8. [Funcionalidades Implementadas](#funcionalidades-implementadas)
   - [Reordenação com setas](#reordenação-com-setas)
   - [Ativar/Desativar rápido](#ativardesativar-rápido)
   - [Split-screen editor com preview](#split-screen-editor-com-preview)
9. [Auditoria e Activity Log](#auditoria-e-activity-log)

---

## Visão Geral

O módulo **História** gerencia a linha do tempo da SUCESU no portal. Cada registro é um **marco histórico** (milestone) com período, título, imagem de destaque e descrição rica (ContentRichEditor).

### Fluxo de trabalho

```
CMS (CRUD) → v2_historia_milestones → Portal (/historia)
```

---

## Estrutura de Diretórios

```
V2/Modules/Institucional/Historia/
├── Controllers/
│   ├── HistoriaPortalController.php       # Página pública /historia
│   └── MilestoneCmsController.php         # CRUD + reorder + toggle + preview
├── Migrations/
│   └── 2025_03_28_000001_create_v2_historia_milestones_table.php
├── Models/
│   └── Milestone.php
├── ModuleProvider.php
├── Routes/
│   ├── cms.php                            # Rotas administrativas
│   └── web.php                            # Rota pública
└── Views/
    ├── cms/
    │   ├── _form.blade.php                # Período + Título
    │   ├── config.blade.php               # SEO do módulo
    │   ├── create.blade.php               # Criação com split-screen
    │   ├── edit.blade.php                 # Edição com split-screen + preview
    │   ├── index.blade.php                # Listagem com reordenação
    │   └── preview.blade.php              # Preview do milestone no iframe
    └── portal/
        └── index.blade.php                # Linha do tempo pública
```

---

## Model — Milestone

**Arquivo:** `Models/Milestone.php`

| Coluna | Tipo | Descrição |
|--------|------|-----------|
| `id` | string (UUID) | PK, não incrementável |
| `period` | string (100) | Ex: "1965 — 1967" |
| `title` | string (255) | Título do marco |
| `description` | text/null | JSON AST do ContentRichEditor |
| `image_id` | string (36)/null | FK para GalleryMedia |
| `sort_order` | integer | Ordenação (1-based) |
| `is_active` | boolean | Visível no portal? |
| `created_by` | string (36)/null | ID do usuário Sentinel |
| `created_at` / `updated_at` | timestamp | — |
| `deleted_at` | timestamp | Soft delete |

### Scopes

| Scope | Query |
|-------|-------|
| `active()` | `WHERE is_active = true` |
| `ordered()` | `ORDER BY sort_order ASC, created_at ASC` |

---

## Controllers

### MilestoneCmsController

| Método | Rota | Ação |
|--------|------|------|
| `index()` | `GET /cms/historia` | Lista paginada com busca |
| `create()` | `GET /cms/historia/novo` | Formulário de criação |
| `store()` | `POST /cms/historia/novo` | Persiste novo milestone |
| `edit($id)` | `GET /cms/historia/editar/{id}` | Formulário de edição |
| `update()` | `PUT|POST /cms/historia/editar/{id}` | Atualiza milestone |
| `destroy($id)` | `DELETE /cms/historia/{id}` | Soft delete |
| `reorder()` | `POST /cms/historia/reorder` | Reordena por array de IDs |
| `toggleActive($id)` | `POST /cms/historia/{id}/toggle` | Ativa/desativa + reindexa |
| `preview($id)` | `GET /cms/historia/preview/{id}` | Renderiza preview para iframe |
| `config()` | `GET /cms/historia/configuracoes` | SEO do módulo |
| `updateConfig()` | `POST /cms/historia/configuracoes` | Salva SEO |

### HistoriaPortalController

| Método | Rota | Ação |
|--------|------|------|
| `index()` | `GET /historia` | Lista milestones ativos ordenados |

---

## Views CMS

### `index.blade.php` — Listagem com ações rápidas

- Tabela com colunas: Imagem, Período, Título, **Ordem** (com setas up/down), **Ações** (toggle ativo + editar + arquivar)
- Reordenação via AJAX (swap de linhas no DOM → POST `/reorder`)
- Toggle ativo/desativo via AJAX com `bi-toggle-on`/`bi-toggle-off`
- Busca por período ou título
- Botão "Ver página" no header (abre `/historia` em nova aba)

### `_form.blade.php` — Período + Título

Apenas campos de texto lado a lado. Imagem e conteúdo narrativo são renderizados nas views `create`/`edit`.

### `create.blade.php` / `edit.blade.php` — Split-screen editor

Layout com CSS Grid:
- **Topo:** Período + Título (`_form`)
- **Split (3fr 2fr):**
  - **Esquerda:** ContentRichEditor (Tiptap)
  - **Direita:** Imagem de destaque + preview iframe
- **Rodapé:** Botões Salvar/Atualizar + Cancelar

O preview carrega a URL `GET /cms/historia/preview/{id}` que renderiza o milestone com o estilo do portal.

### `preview.blade.php` — Página de preview

HTML standalone (sem layout CMS) que renderiza:
- Banner "Modo Preview"
- Container com imagem + período + título + acento + descrição rica (`$htmlContent`)

---

## Views Portal

### `portal/index.blade.php` — Linha do tempo

- Hero com breadcrumb
- Seção de introdução
- Timeline de milestones com layout alternado (imagem/texto se invertem a cada item)
- CTA final

---

## Rotas

### CMS (`Routes/cms.php`)

| Método | Rota | Nome |
|--------|------|------|
| GET | `/cms/historia` | `v2.historia.cms.milestones.index` |
| GET | `/cms/historia/novo` | `v2.historia.cms.milestones.create` |
| POST | `/cms/historia/novo` | `v2.historia.cms.milestones.store` |
| GET | `/cms/historia/editar/{id}` | `v2.historia.cms.milestones.edit` |
| PUT/POST | `/cms/historia/editar/{id}` | `v2.historia.cms.milestones.update` |
| DELETE | `/cms/historia/{id}` | `v2.historia.cms.milestones.destroy` |
| POST | `/cms/historia/reorder` | `v2.historia.cms.milestones.reorder` |
| POST | `/cms/historia/{id}/toggle` | `v2.historia.cms.milestones.toggle` |
| GET | `/cms/historia/preview/{id}` | `v2.historia.cms.milestones.preview` |
| GET | `/cms/historia/configuracoes` | `v2.historia.cms.config` |
| POST | `/cms/historia/configuracoes` | `v2.historia.cms.config.update` |

### Portal (`Routes/web.php`)

| Método | Rota | Nome |
|--------|------|------|
| GET | `/historia` | `v2.historia.portal.index` |

---

## Funcionalidades Implementadas

### Reordenação com setas

Na listagem CMS, cada linha tem botões `bi-chevron-up` / `bi-chevron-down` na coluna "Ordem":

1. Click sobe/desce a linha no DOM (swap com `insertBefore`/`insertAfter`)
2. Coleta todos os IDs do `tbody` na nova ordem
3. Envia POST para `/cms/historia/reorder` com `{ ids: [...] }`
4. Servidor atualiza `sort_order` para 1, 2, 3... conforme posição no array
5. Página recarrega

### Ativar/Desativar rápido

Botão na coluna "Ações" que alterna entre:
- **Ativo:** `btn-outline-success` + `bi-toggle-on`
- **Inativo:** `btn-outline-secondary` + `bi-toggle-off`

Ao desativar:
- `is_active = false`, `sort_order = -1`
- Milestones ativos com `sort_order > oldOrder` decrementam em 1 (reindexação)

Ao reativar:
- `is_active = true`, `sort_order = max(sort_order dos ativos) + 1` (vai para o fim)

### Split-screen editor com preview

Na edição, o ContentRichEditor e o preview dividem a tela:
- Editor (esquerda, 3fr): Tiptap com toolbar completa
- Preview (direita, 2fr): Imagem de destaque + iframe com a view `preview.blade.php`

O preview é atualizado ao salvar o milestone (recarregando a página).

---

## Auditoria e Activity Log

| Operação | Tipo |
|----------|------|
| Criar milestone | `historia_milestone_create` |
| Atualizar milestone | `historia_milestone_update` |
| Arquivar (soft delete) | `historia_milestone_delete` |
| Ativar/Desativar | `historia_milestone_toggle` |
| Atualizar SEO | `historia_config_seo_update` |