# BRIEFING — Portal da Associada Eletros

> Documento de contexto para desenvolvimento com Claude Code.  
> Última atualização: 27/08/2026 — Etapa 1 concluída + UIs de cadastro/governança em homolog.  
> Fonte de escopo do cliente: `docs/escopo-cliente.xlsx` (15 abas).  
> Status funcional detalhado: `docs/requisitos de software/`.

---

## 1. Visão geral

### O que é

Portal de membros da **Eletros** (associação do setor de eletroeletrônicos), composto por **dois módulos**:

| Módulo | Público | Propósito |
|--------|---------|-----------|
| **Backoffice (Admin)** | Equipe interna da Eletros | Gestão de associadas, conteúdo, indicadores, censo e solicitações |
| **Portal da Associada** | Empresas associadas | Acesso a documentos, calendários, indicadores, financeiro e censo |

### Lógica central

A Eletros cadastra cada associada e define:

1. **Quais segmentos setoriais** ela participa (CSAC, CSLB, CSLM, CSLP, CSTIC)
2. **Quais órgãos** ela tem acesso (Conselhos, Comissões, Indicadores, Financeiro etc.)

**Todo o conteúdo do portal** — documentos, calendários, órgãos, indicadores — é **filtrado automaticamente** com base na participação da empresa em segmentos e órgãos.

```
Eletros cadastra empresa
  → define segmentos + órgãos (aba ACESSOS do escopo)
  → conteúdo vinculado a segmento/órgão
  → portal exibe só o que a empresa tem acesso
  → menu adaptado ao Tipo de Acesso de cada usuário
```

> **Importante:** A filtragem não é apenas por segmento. A aba **ACESSOS** do escopo do cliente define, órgão a órgão, quais empresas participam de cada linha (CADM, ASG, CSAC, CSLB, INDIC, FINANC etc.).

### Grupo econômico

Uma associada pode ter **múltiplas razões sociais** sob o mesmo acesso no portal (ex.: Britânia Eletrodomésticos S.A. + Philco Eletrônicos S.A.). O login representa o **grupo**, não necessariamente uma única CNPJ.

### Stack técnica

| Camada | Tecnologia |
|--------|------------|
| Backend | **Laravel 13** (PHP ≥ 8.3) |
| Painel Admin | **Filament 4** (PHP — backoffice Eletros) |
| Frontend Portal | **Livewire** + Blade (Vite + Tailwind) |
| Banco de dados | MySQL/MariaDB |
| Ambiente local / dev | **Docker** (Laravel Sail ou `docker-compose`) |
| Homologação | AWS Neotix (PHP — **sem Docker**) |
| Produção | Hostgator (PHP — **sem Docker**) |

```
┌─────────────────────────────────────────────────────────┐
│  Laravel 13 (monolito)                                  │
│  ├── /admin   → Filament 4 (PHP / Livewire)             │
│  └── /portal  → Portal Livewire + Blade                 │
└─────────────────────────────────────────────────────────┘
```

> **Admin** e **portal** compartilham a stack PHP/Livewire — alinhados ao Filament, com formulários complexos (censo, cadastros) via componentes Livewire.

---

## 2. Navegação do portal (mapa de páginas)

Estrutura definida no escopo do cliente (`docs/escopo-cliente.xlsx`):

| Seção | Subpáginas / Conteúdo |
|-------|------------------------|
| **Área Associada** | Boas-vindas ("Bem-vindo à Área da Associada") |
| **Governança** | Estatuto Social, Regulamento Associativo, Certificado de Filiação |
| **Cadastro** | Cadastro de Filiação, Cadastro de Representação |
| **Calendário** | Reuniões (AG, CADM, Conselhos Setoriais, Comissões Intersetoriais) + Eventos |
| **Conselhos Administrativos** | Assembleia Geral (ASG), Conselho de Administração (CADM) |
| **Conselhos Setoriais** | CSAC, CSLB, CSLM, CSLP, CSTIC |
| **Comissões Técnicas Setoriais** | CTS AC, CTS LB, CTS LM, CTS LP, CTS TIC |
| **Comissões Intersetoriais** | CACEX, CAL, CAT, CAS |
| **Indicadores** | Calendário de envio e status por segmento/grade |
| **Financeiro** | 2ª via de boleto, 2ª via de Boleto Rateio, Histórico de Rateios |
| **Censo** | Questionário com 40 perguntas |
| **Perfil da Associada** | Dados do grupo econômico (múltiplas razões sociais) |

---

## 3. Perfis e controle de acesso

### 3.1 Backoffice (Eletros)

| Perfil | Descrição |
|--------|-----------|
| **Admin Eletros** | Equipe interna com acesso total ao backoffice Filament |

### 3.2 Portal da Associada — modelo revisado

O escopo do cliente define um modelo **mais granular** que o binário representante/usuário comum. Para **cada órgão**, a empresa cadastra:

| Papel | Descrição |
|-------|-----------|
| **Representante Titular** | Representante principal do órgão |
| **Representante Suplente** | Substituto do titular |
| **Contato(s) Suporte** | Um ou mais contatos de apoio (`+ Adicionar Contato Suporte`) |

Cada pessoa cadastrada recebe um **Tipo de Acesso** que define o que vê/faz no portal:

| Tipo de Acesso | Contexto de uso |
|----------------|-----------------|
| **Sênior** | Órgãos administrativos (AG, CADM) |
| **Pleno** | Órgãos administrativos |
| **Júnior** | Órgãos institucionais e comissões |
| **Financeiro** | Módulo financeiro (boletos e rateios) |
| **Indicadores** | Módulo de indicadores |
| **Vazia** | Recebimento de grade vazia |
| **Vazia e Consolidada** | Grades vazia + consolidada |
| **Consolidada** | Grade consolidada |
| **Auditoria** | Grade de auditoria |

### 3.3 Regras de redirecionamento

- Após login, o usuário é redirecionado conforme seu **Tipo de Acesso** e **órgãos vinculados**.
- Menu e telas são **adaptados ao perfil** (ex.: Financeiro vê módulo financeiro; Indicadores vê calendário de envio).
- Usuários com Tipo de Acesso **Júnior** têm acesso restrito (documentos e calendário dos órgãos aos quais estão vinculados).
- Usuários **Sênior/Pleno/Financeiro/Indicadores** têm acesso ampliado aos respectivos módulos.

> **Pendente com cliente:** Mapear exatamente o que cada Tipo de Acesso pode ver e fazer no portal.

---

## 4. Segmentos setoriais

Lista confirmada no escopo do cliente:

| Sigla | Nome completo |
|-------|---------------|
| **CSAC** | Conselho Setorial de Ar-Condicionado |
| **CSLB** | Conselho Setorial de Linha Branca |
| **CSLM** | Conselho Setorial de Linha Marrom |
| **CSLP** | Conselho Setorial de Linha Portátil |
| **CSTIC** | Conselho Setorial de Tecnologia da Informação e Comunicação |

---

## 5. Órgãos (estrutura hierárquica)

### 5.1 Órgãos Administrativos

| Sigla | Nome |
|-------|------|
| **ASG** | Assembleia Geral |
| **CADM** | Conselho de Administração |

### 5.2 Órgãos Institucionais (Conselhos Setoriais)

| Sigla | Nome |
|-------|------|
| **CSAC** | Conselho Setorial de Ar-Condicionado |
| **CSLB** | Conselho Setorial de Linha Branca |
| **CSLM** | Conselho Setorial de Linha Marrom |
| **CSLP** | Conselho Setorial de Linha Portátil |
| **CSTIC** | Conselho Setorial de TIC |

### 5.3 Comissões Técnicas Setoriais

| Sigla | Nome |
|-------|------|
| **CTS AC** | Comissão Técnica de Ar-Condicionado |
| **CTS AC COM** | Comissão Técnica de Ar-Condicionado Comercial |
| **CTS KIG** | Comissão Técnica sobre Emenda de Kigali |
| **CTS BEBEDOURO** | Comissão Técnica de Bebedouro |
| **CTS FOGÃO** | Comissão Técnica de Fogão |
| **CTS LAVADORA** | Comissão Técnica de Lavadora de Roupas |
| **CTS REFRIGERADOR** | Comissão Técnica de Refrigerador |
| **CTS MICRO-ONDAS** | Comissão Técnica de Micro-ondas |
| **CTS LM** | Comissão Técnica de Linha Marrom |
| **CTS LP** | Comissão Técnica de Linha Portátil |

### 5.4 Comissões Técnicas Intersetoriais

| Sigla | Nome |
|-------|------|
| **CACEX** | Comissão de Assuntos de Comércio Exterior |
| **CAL** | Comissão de Assuntos Legislativos |
| **CAT** | Comissão de Assuntos Tributários |
| **CAS** | Comissão de Assuntos de Sustentabilidade |

### 5.5 Comissões Especiais

| Sigla | Nome |
|-------|------|
| **CESP TRABALHISTA** | Comissão Especial Trabalhista |
| **CESP CONSUMERISTA** | Comissão Especial Consumerista |
| **CESP TRIBUTÁRIA** | Comissão Especial Tributária |

### 5.6 Módulos funcionais (sem reunião)

| Sigla | Nome |
|-------|------|
| **FINANC** | Financeiro (boletos de mensalidades e rateios) |
| **INDIC** | Indicadores (envio e recebimento de dados) |

### 5.7 Regra de acesso por órgão

A aba **ACESSOS** do escopo lista, para cada sigla de órgão, quais empresas participam. Exemplos:

- **CADM** e **ASG**: praticamente todas as associadas
- **CSAC**: empresas do segmento de ar-condicionado (Daikin, Elgin, Gree, etc.)
- **CSLB**: empresas de linha branca (Electrolux, Britânia/Philco, etc.)
- **INDIC** e **FINANC**: todas as associadas listadas

Essa relação deve ser modelada em `empresa_orgao` e usada como filtro principal no portal.

---

## 6. Escopo funcional

### 6.1 Admin (Backoffice — Filament)

- [x] Autenticação da equipe Eletros
- [x] Gestão de associadas: dados, segmentos, órgãos, representantes e usuários
- [x] Gestão de grupo econômico (múltiplas razões sociais por associada)
- [ ] Visualização / revisão de Cadastro de Filiação e Representação *(status no domínio; UI Admin pendente)*
- [x] Upload e gestão de documentos de Governança
- [x] Gestão de órgãos (todos os tipos da seção 5) e calendário de reuniões *(CRUD Admin; Portal pendente)*
- [ ] Configuração do calendário de Indicadores por segmento e tipo de grade
- [ ] Visualização e exportação das respostas do Censo
- [x] Recebimento e gestão de solicitações financeiras (boleto e rateio) *(fila Admin; abertura Portal pendente)*
- [x] Gestão da matriz de acessos empresa × órgão *(vínculo no CRUD; importador ACESSOS pendente)*
- [x] Visibilidade módulo × segmento (`VisibilidadeDoPortal` / `modulo_segmento`)

### 6.2 Portal da Associada

- [x] Autenticação *(redirecionamento por Tipo de Acesso ainda pendente)*
- [x] Tela de boas-vindas e menu *(módulos futuros desabilitados; ACL TipoAcesso pendente)*
- [ ] Perfil da associada (grupo econômico com múltiplas razões sociais)
- [x] Cadastro de Filiação *(associada_admin)*
- [x] Cadastro de Representação por órgão *(associada_admin)*
- [x] Documentos de Governança (listagem, leituras, download autenticado)
- [ ] Calendário de reuniões filtrado pelos órgãos da empresa
- [ ] Páginas de Conselhos e Comissões (administrativos, setoriais, técnicos, intersetoriais)
- [ ] Indicadores: calendário de envio, recebimento de grades e status *(Tipo de Acesso Indicadores)*
- [ ] Financeiro: 2ª via boleto, 2ª via rateio, histórico *(Tipo de Acesso Financeiro)*
- [ ] Censo: questionário com salvamento parcial e envio final *(representante / titular)*

---

## 7. Formulários detalhados

### 7.1 Cadastro de Filiação

**Dados gerais da empresa:**

| Campo | Tipo |
|-------|------|
| Nome da Empresa | texto |
| Data de Filiação | data |
| Marca(s) | texto / lista |

**Fábrica** *(bloco repetível — `+ Adicionar Fábrica`)*:

| Campo | Tipo |
|-------|------|
| Razão Social | texto |
| CNPJ | texto |
| Endereço | texto |
| CEP | texto |
| Estado / Município | texto |
| Produtos Fabricados | lista (`+ Adicionar Produto`) |
| Presidente | texto |
| Contato (Presidente) | texto |
| Aniversário (Presidente) | data |
| Diretor | texto |
| Contato (Diretor) | texto |
| Aniversário (Diretor) | data |
| Número de Empregos Diretos | número |
| Número de Empregos Indiretos | número |
| Segmentos Setoriais na Eletros | multiselect |

**Unidade Administrativa** *(bloco repetível — `+ Adicionar Unid. Administrativa`)*:

| Campo | Tipo |
|-------|------|
| Razão Social | texto |
| CNPJ | texto |
| Endereço | texto |
| CEP | texto |
| Presidente / Contato / Aniversário | texto / data |
| Diretor / Contato / Aniversário | texto / data |
| Número de Empregos Diretos | número |
| Número de Empregos Indiretos | número |

### 7.2 Cadastro de Representação

Para **cada órgão** ao qual a empresa tem acesso, preencher:

| Campo | Tipo |
|-------|------|
| Representante Titular — Nome | texto |
| Representante Titular — Cargo | texto |
| Representante Titular — E-mail | email |
| Representante Titular — Telefone | texto |
| Representante Titular — Tipo de Acesso | select |
| Representante Suplente — (mesmos campos) | |
| Contato(s) Suporte — (mesmos campos) | repetível (`+ Adicionar`) |

Órgãos cobertos: todos listados na seção 5 (administrativos, setoriais, comissões técnicas, intersetoriais, especiais, financeiro e indicadores).

### 7.3 Calendário de Reuniões

Visualização em **grade mensal** (dia × mês), agrupada por tipo:

| Aba do calendário | Órgãos exibidos |
|-------------------|-----------------|
| Assembleia Geral | ASG, AGO |
| Conselho de Administração | CADM |
| Conselhos Setoriais | CSAC, CSLB, CSLM, CSLP, CSTIC |
| Comissões Intersetoriais | CACEX, CAL, CAT, CAS |
| Eventos | Eventos gerais |

Cada célula exibe horário + sigla do órgão (ex.: `10h - CSLM`, `10h - CADM | 11h - AGO`).

### 7.4 Calendário de Indicadores

Visualização em **grade mensal**, com eventos por segmento:

| Tipo de evento | Segmentos | Exemplo |
|----------------|-----------|---------|
| Envio de Dados | LM (separado) | "Envio Dados LM de janeiro" |
| Envio de Dados | AC, LB, LP, TIC (agrupados) | "Envio Dados AC, LB, LP e TIC de janeiro" |
| Previsão Grade Consolidada | LM ou AC/LB/LP/TIC | "Previsão Grade Consolidada LM" |
| Recebimento da Grade Vazia | Todos | "Recebimento da Grade Vazia" |
| Previsão Grades Consolidadas | AC, LB, LP, TIC | "Previsão Grades Consolidadas AC, LB, LP e TIC" |

**Tipos de Grade** (para Cadastro de Representação — módulo Indicadores):

| Tipo | Descrição |
|------|-----------|
| Vazia | Grade em branco para preenchimento |
| Vazia e Consolidada | Ambas as grades |
| Consolidada | Grade consolidada |
| Auditoria | Grade de auditoria |

> LM (Linha Marrom) tem calendário de envio **diferente** dos demais segmentos (AC, LB, LP, TIC).

### 7.5 Financeiro

| Funcionalidade | Descrição |
|----------------|-----------|
| **2ª via de boleto** | Solicitação de segunda via de mensalidade |
| **2ª via de Boleto Rateio** | Solicitação de segunda via de rateio |
| **Histórico de Rateios** | Consulta de rateios anteriores |

> **Pendente:** Confirmar se histórico vem de integração com sistema financeiro ou upload manual.

### 7.6 Censo — 40 perguntas

Questionário estruturado em seções:

#### Identificação (Q1–3)

| # | Pergunta | Tipo |
|---|----------|------|
| 1 | Nome da empresa? | texto |
| 2 | Identificação do respondente (nome e sobrenome) | texto |
| 3 | E-mail do respondente | email |

#### Perfil Empresarial (Q4–7)

| # | Pergunta | Tipo |
|---|----------|------|
| 4 | Razões sociais e CNPJs da empresa e do Grupo Econômico | tabela repetível |
| 5 | Marcas nacionais e internacionais do Grupo Econômico | texto/lista |
| 6 | Localização das fábricas no Brasil (estado e município) | tabela repetível |
| 7 | Localização das unidades administrativas (estado e município) | tabela repetível |

#### Perfil Institucional (Q8–9)

| # | Pergunta | Tipo |
|---|----------|------|
| 8 | Segmentos setoriais da empresa na Eletros | multiselect |
| 9 | Participação em outras associações/entidades | texto condicional |

#### Perfil Empregatício (Q10–15)

| # | Pergunta | Tipo |
|---|----------|------|
| 10 | Empregos diretos nas fábricas | número |
| 11 | Empregos diretos nas unidades administrativas | número |
| 12 | Empregos diretos nos centros de distribuição | número |
| 13 | Estimativa de empregos indiretos | número |
| 14 | Níveis de qualificação nas plantas industriais (%) | ranking: Fundamental, Médio, Técnico, Superior, Pós-Graduação |
| 15 | Níveis de qualificação nas unidades administrativas (%) | ranking |

#### Perfil Industrial (Q16–38)

| # | Pergunta | Tipo |
|---|----------|------|
| 16 | Produtos produzidos por outra Associada Eletros | tabela condicional |
| 17 | Produtos produzidos por empresa não associada | tabela condicional |
| 18 | Produtos fabricados em cada fábrica | tabela |
| 19 | Importação de bens finais de marca internacional | select (3 opções) |
| 20 | Produtos de marcas internacionais importados | tabela: País, Marca, Produto |
| 21 | Principais insumos (até 20) com NCM | tabela |
| 22 | A empresa produz os próprios insumos? | sim/não |
| 23 | Principais insumos produzidos (até 20) | lista condicional |
| 24 | A empresa compra insumos nacionais? | sim/não |
| 25 | Principais insumos comprados nacionalmente (até 20) | lista condicional |
| 26 | A empresa importa insumos globais? | sim/não |
| 27 | Principais insumos importados (até 20) | lista condicional |
| 28 | Modal de importação de insumos | select: Aéreo, Marítimo, Terrestre |
| 29 | Aeroportos, portos e pontos alfandegários (insumos) | tabela: 3 colunas |
| 30 | Modal de importação de bens finais | select |
| 31 | Aeroportos, portos e pontos alfandegários (bens finais) | tabela |
| 32 | Modal de deslocamento interno de insumos | select |
| 33 | Modal de transporte interno de bens finais | select |
| 34 | A empresa exporta produtos? | sim/não |
| 35 | Produtos e países de exportação | tabela condicional |
| 36 | Interesse em exportar? | sim/não |
| 37 | Produtos, países e desafios para exportação | tabela condicional |
| 38 | Certificação OEA | sim/não |

#### Perfil Econômico (Q39–40)

| # | Pergunta | Tipo |
|---|----------|------|
| 39 | Custo Brasil — ranking de impacto (1 a 6) | ranking: Capital Humano, Infraestrutura, Logística, Insumos Básicos, Contencioso Jurídico-Regulatório, Operações Tributárias |
| 40 | Variação cambial — impacto no custo do produto | select: Até 10%, 20%, 40%, 60%, 80%, Acima de 80% |

**Requisitos do censo:**
- Salvamento parcial (rascunho)
- Envio final (bloqueia edição)
- Apenas representante/titular pode responder

---

## 8. Modelagem do banco de dados

### 8.1 Diagrama de entidades (revisado)

```
grupos_economicos ── empresas ──┬── empresa_segmento ── segmentos
                                ├── empresa_orgao ── orgaos
                                ├── fabricas
                                ├── unidades_administrativas
                                ├── representacoes (titular/suplente/suporte × orgao)
                                ├── envios_indicadores
                                ├── solicitacoes_financeiras
                                └── censo_respostas ── censo_resposta_itens

segmentos ──┬── documentos
            ├── indicadores ── calendario_indicadores
            └── orgaos (setoriais) ── reunioes

orgaos ── reunioes
censos ── censo_perguntas
cadastros_filiacao
users ── representacoes
```

### 8.2 Tabelas e campos

#### `grupos_economicos`

Agrupa razões sociais sob um mesmo acesso no portal.

| Campo | Tipo | Observação |
|-------|------|------------|
| id | bigint PK | |
| nome | string | Ex.: "Britânia / Philco" |
| ativo | boolean | default true |
| created_at / updated_at | timestamps | |

---

#### `segmentos`

| Campo | Tipo | Observação |
|-------|------|------------|
| id | bigint PK | |
| sigla | string(10) unique | Ex.: `CSLB` |
| nome | string | Ex.: "Linha Branca" |
| slug | string unique | Ex.: `linha-branca` |
| ativo | boolean | default true |
| ordem | integer | |
| created_at / updated_at | timestamps | |

**Seed:** CSAC, CSLB, CSLM, CSLP, CSTIC.

---

#### `orgaos`

Todos os órgãos, comissões e módulos funcionais.

| Campo | Tipo | Observação |
|-------|------|------------|
| id | bigint PK | |
| sigla | string(20) unique | Ex.: `CADM`, `CTS AC` |
| nome | string | Nome completo |
| tipo | enum | `administrativo`, `institucional`, `comissao_setorial`, `comissao_intersetorial`, `comissao_especial`, `modulo` |
| segmento_id | FK nullable → segmentos | Null para intersetoriais e administrativos |
| orgao_pai_id | FK nullable → orgaos | Hierarquia (ex.: CTS AC → CSAC) |
| email_contato | string nullable | Ex.: `kathia.mendonca@eletros.org.br` para conselhos setoriais |
| ativo | boolean | default true |
| ordem | integer | |
| created_at / updated_at | timestamps | |

---

#### `empresas`

| Campo | Tipo | Observação |
|-------|------|------------|
| id | bigint PK | |
| grupo_economico_id | FK → grupos_economicos | |
| razao_social | string | |
| nome_fantasia | string nullable | |
| cnpj | string(14) unique | Somente dígitos |
| data_filiacao | date nullable | |
| marcas | json nullable | Lista de marcas |
| inscricao_estadual | string nullable | |
| telefone | string nullable | |
| email | string nullable | |
| site | string nullable | |
| ativo | boolean | default true |
| created_at / updated_at | timestamps | |
| deleted_at | timestamp nullable | Soft delete |

---

#### `empresa_segmento` (pivot)

| Campo | Tipo |
|-------|------|
| id | bigint PK |
| empresa_id | FK → empresas |
| segmento_id | FK → segmentos |
| created_at / updated_at | timestamps |

**Unique:** `(empresa_id, segmento_id)`

---

#### `empresa_orgao` (pivot)

Define quais órgãos cada empresa acessa (fonte: aba ACESSOS).

| Campo | Tipo |
|-------|------|
| id | bigint PK |
| empresa_id | FK → empresas |
| orgao_id | FK → orgaos |
| created_at / updated_at | timestamps |

**Unique:** `(empresa_id, orgao_id)`

---

#### `fabricas`

Fábricas do Cadastro de Filiação (repetível).

| Campo | Tipo |
|-------|------|
| id | bigint PK |
| empresa_id | FK → empresas |
| razao_social | string |
| cnpj | string(14) |
| endereco | string nullable |
| cep | string(8) nullable |
| estado | string nullable |
| municipio | string nullable |
| produtos_fabricados | json nullable |
| presidente_nome | string nullable |
| presidente_contato | string nullable |
| presidente_aniversario | date nullable |
| diretor_nome | string nullable |
| diretor_contato | string nullable |
| diretor_aniversario | date nullable |
| empregos_diretos | integer nullable |
| empregos_indiretos | integer nullable |
| created_at / updated_at | timestamps |

---

#### `unidades_administrativas`

Unidades administrativas do Cadastro de Filiação (repetível).

| Campo | Tipo |
|-------|------|
| id | bigint PK |
| empresa_id | FK → empresas |
| razao_social | string |
| cnpj | string(14) |
| endereco | string nullable |
| cep | string(8) nullable |
| presidente_nome / contato / aniversario | |
| diretor_nome / contato / aniversario | |
| empregos_diretos | integer nullable |
| empregos_indiretos | integer nullable |
| created_at / updated_at | timestamps |

---

#### `users`

| Campo | Tipo | Observação |
|-------|------|------------|
| id | bigint PK | |
| name | string | |
| email | string unique | |
| email_verified_at | timestamp nullable | |
| password | string | |
| perfil | enum | `eletros_admin`, `associada_admin`, `associada_usuario` |
| grupo_economico_id | FK nullable → grupos_economicos | Null para admins Eletros |
| cargo | string nullable | |
| telefone | string nullable | |
| ativo | boolean | default true |
| remember_token | string nullable | |
| created_at / updated_at | timestamps | |

> `associada_admin` administra a casa (cadastros); `associada_usuario` consulta. Permissões granulares de módulo ficam em `representacoes.tipo_acesso` (ACL ainda a aplicar).

---

#### `representacoes`

Vínculo de pessoa × órgão × empresa (Cadastro de Representação).

| Campo | Tipo | Observação |
|-------|------|------------|
| id | bigint PK | |
| empresa_id | FK → empresas | |
| orgao_id | FK → orgaos | |
| user_id | FK nullable → users | Null se ainda não convidado |
| papel | enum | `titular`, `suplente`, `contato_suporte` |
| nome | string | Preenchido no cadastro |
| cargo | string nullable | |
| email | string | |
| telefone | string nullable | |
| tipo_acesso | enum | `senior`, `pleno`, `junior`, `financeiro`, `indicadores`, `vazia`, `vazia_consolidada`, `consolidada`, `auditoria` |
| tipo_grade | enum nullable | `vazia`, `vazia_consolidada`, `consolidada`, `auditoria` — só para módulo Indicadores |
| ativo | boolean | default true |
| created_at / updated_at | timestamps | |

---

#### `cadastros_filiacao`

| Campo | Tipo | Observação |
|-------|------|------------|
| id | bigint PK | |
| empresa_id | FK → empresas | |
| preenchido_por | FK → users | |
| status | enum | `rascunho`, `enviado`, `aprovado`, `pendente_revisao` |
| enviado_em | timestamp nullable | |
| revisado_por | FK nullable → users | Admin Eletros |
| revisado_em | timestamp nullable | |
| created_at / updated_at | timestamps | |

> Dados detalhados ficam em `fabricas`, `unidades_administrativas` e campos de `empresas`.

---

#### `documentos`

| Campo | Tipo | Observação |
|-------|------|------------|
| id | bigint PK | |
| titulo | string | Ex.: "Estatuto Social" |
| tipo | enum | `estatuto_social`, `regulamento_associativo`, `certificado_filiacao`, `outro` |
| segmento_id | FK nullable → segmentos | Null = documento geral para todos |
| arquivo_path | string | Caminho relativo no disco `private` (ex.: `governanca/cslb/{uuid}.pdf`) |
| arquivo_nome_original | string | Nome exibido no download |
| arquivo_mime | string nullable | |
| arquivo_tamanho | integer nullable | bytes |
| publicado | boolean | default false |
| publicado_em | timestamp nullable | |
| criado_por | FK → users | |
| created_at / updated_at | timestamps | |
| deleted_at | timestamp nullable | |

---

#### `reunioes`

| Campo | Tipo | Observação |
|-------|------|------------|
| id | bigint PK | |
| orgao_id | FK → orgaos | |
| titulo | string nullable | |
| data | date | |
| hora_inicio | time | |
| hora_fim | time nullable | |
| descricao | text nullable | |
| tipo_calendario | enum | `assembleia_geral`, `conselho_administracao`, `conselho_setorial`, `comissao_intersetorial`, `evento` |
| created_at / updated_at | timestamps | |

---

#### `calendario_indicadores`

| Campo | Tipo | Observação |
|-------|------|------------|
| id | bigint PK | |
| segmento_id | FK nullable → segmentos | Null para eventos multi-segmento |
| segmentos_agrupados | json nullable | Ex.: `["CSAC","CSLB","CSLP","CSTIC"]` |
| tipo_evento | enum | `envio_dados`, `previsao_grade_consolidada`, `recebimento_grade_vazia`, `previsao_grades_consolidadas` |
| descricao | string | Ex.: "Envio Dados LM de janeiro" |
| data | date | |
| ano | integer | |
| tipo_grade | enum nullable | `vazia`, `vazia_consolidada`, `consolidada`, `auditoria` |
| created_at / updated_at | timestamps | |

---

#### `envios_indicadores`

| Campo | Tipo | Observação |
|-------|------|------------|
| id | bigint PK | |
| empresa_id | FK → empresas | |
| calendario_indicador_id | FK → calendario_indicadores | |
| status | enum | `pendente`, `enviado`, `atrasado`, `aprovado`, `rejeitado` |
| tipo_grade | enum nullable | |
| arquivo_path | string nullable | Caminho relativo no disco `private` |
| enviado_por | FK nullable → users | |
| enviado_em | timestamp nullable | |
| created_at / updated_at | timestamps | |

**Unique:** `(empresa_id, calendario_indicador_id)`

---

#### `solicitacoes_financeiras`

| Campo | Tipo | Observação |
|-------|------|------------|
| id | bigint PK | |
| empresa_id | FK → empresas | |
| solicitado_por | FK → users | |
| tipo | enum | `segunda_via_boleto`, `segunda_via_boleto_rateio` |
| status | enum | `pendente`, `em_andamento`, `concluida`, `cancelada` |
| observacao_solicitante | text nullable | |
| resposta_eletros | text nullable | |
| respondido_por | FK nullable → users | |
| respondido_em | timestamp nullable | |
| created_at / updated_at | timestamps | |

---

---

#### `censos` / `censo_perguntas` / `censo_respostas` / `censo_resposta_itens`

Mantêm a estrutura original, com `censo_perguntas` seedada com as 40 perguntas da seção 7.6.

Tipos adicionais de pergunta: `ranking`, `tabela_repetivel`, `condicional`.

---

#### `historico_rateios`

| Campo | Tipo | Observação |
|-------|------|------------|
| id | bigint PK | |
| empresa_id | FK → empresas | |
| referencia | string | Período/referência do rateio |
| valor | decimal nullable | |
| arquivo_path | string nullable | Caminho relativo no disco `private` (boleto/comprovante) |
| data_vencimento | date nullable | |
| data_pagamento | date nullable | |
| created_at / updated_at | timestamps | |

> **Pendente:** Confirmar se histórico vem de integração com sistema financeiro ou upload manual pela Eletros.

---

### 8.3 Relacionamentos Eloquent (resumo)

```php
// GrupoEconomico
hasMany: empresas, users

// Empresa
belongsTo: grupoEconomico
belongsToMany: segmentos, orgaos
hasMany: fabricas, unidadesAdministrativas, representacoes, enviosIndicadores,
         solicitacoesFinanceiras, censoRespostas, historicoRateios
hasOne: cadastroFiliacao

// Orgao
belongsTo: segmento, orgaoPai
hasMany: reunioes, representacoes, filhos (orgaos filhos)
belongsToMany: empresas

// Representacao
belongsTo: empresa, orgao, user

// User
belongsTo: grupoEconomico (nullable)
hasMany: representacoes
```

### 8.4 Armazenamento de arquivos

Ver decisão completa na **seção 9.6**. Resumo: disco `private` (`storage/app/private/`), download via rota autenticada + `PortalVisibility` (documentos), sem URL pública.

---

## 9. Decisões de arquitetura

### 9.1 Separação Admin × Portal × Ambientes

| Aspecto | Decisão | Justificativa |
|---------|---------|---------------|
| Admin | **Filament 4** em `/admin` | CRUD rápido, autenticação e resources de domínio |
| Portal | **Livewire** + Blade em `/portal` | Alinhado ao Filament; formulários complexos (censo, cadastros) |
| Dev local | **Docker** (Sail / compose) | Ambiente padronizado (PHP, MySQL) |
| Homolog | AWS Neotix (PHP tradicional) | **Sem Docker** |
| Produção | Hostgator (PHP tradicional) | **Sem Docker** |

| Contexto | Rotas / UI |
|----------|------------|
| Admin Filament | Filament auto-registra `/admin` |
| Portal | `routes/web.php` + componentes Livewire em `app/Livewire/` |

### 9.2 Filtragem de conteúdo

Dupla camada de filtro no portal:

```php
// 1. Empresa participa do órgão?
$orgaoIds = $empresa->orgaos()->pluck('orgaos.id');

// 2. Reuniões visíveis
Reuniao::whereIn('orgao_id', $orgaoIds)->get();

// 3. Documentos (gerais ou do segmento da empresa)
Documento::where(function ($q) use ($empresa) {
    $q->whereNull('segmento_id')
      ->orWhereIn('segmento_id', $empresa->segmentos->pluck('id'));
})->where('publicado', true)->get();
```

**Implementar / implementado:**
- ~~Trait `FiltraPorOrgao` e `FiltraPorSegmento`~~ → centralizado em `App\Support\PortalVisibility`
- Visibilidade de módulos por segmento: pivot `modulo_segmento` + página Admin `VisibilidadeDoPortal`
- ACL por `representacoes.tipo_acesso` para cada módulo — **ainda pendente** (próximo incremento)

### 9.3 Autenticação

| Contexto | Guard | Provider |
|----------|-------|----------|
| Admin Filament | `web` | `users` where `perfil = eletros_admin` |
| Portal | `portal` | `users` where perfil é `associada_admin` ou `associada_usuario` |

Permissões de módulo previstas em `representacoes.tipo_acesso` (ainda não aplicadas ao menu/rotas). O perfil distingue admin da associada vs usuário comum.

### 9.4 Docker *(decisão registrada — apenas local)*

Docker **somente** para desenvolvimento local. Homolog (AWS) e produção (Hostgator) usam deploy PHP tradicional.

**Serviços típicos (`docker-compose.yml` ou Laravel Sail):**

| Serviço | Função |
|---------|--------|
| `app` | PHP 8.3 + Composer + Laravel |
| `mysql` | Banco de dados |

**Comandos de referência (local):**

```bash
docker compose up -d
docker compose exec app php artisan migrate
docker compose exec app php artisan serve   # ou via Sail
```

| Ambiente | Docker |
|----------|--------|
| Local | ✅ Sim |
| Homolog (AWS) | ❌ Não |
| Produção (Hostgator) | ❌ Não |

### 9.5 Matriz de permissões por Tipo de Acesso

| Módulo | Sênior/Pleno | Júnior | Financeiro | Indicadores |
|--------|:---:|:---:|:---:|:---:|
| Governança (docs) | ✅ | ✅ | ✅ | ✅ |
| Calendário/Reuniões | ✅ | ✅ | ✅ | ✅ |
| Cadastro Filiação | ✅ | ❌ | ❌ | ❌ |
| Cadastro Representação | ✅ | ❌ | ❌ | ❌ |
| Indicadores (envio) | ❌ | ❌ | ❌ | ✅ |
| Financeiro | ❌ | ❌ | ✅ | ❌ |
| Censo | ✅ | ❌ | ❌ | ❌ |

> Matriz preliminar — validar com cliente.

### 9.6 Armazenamento de arquivos *(decisão registrada)*

Todos os uploads sensíveis ficam em **disco privado** — fora do `public/` e sem URL direta. Governança, indicadores e financeiro são filtrados por segmento, empresa e perfil; URL pública quebraria essa regra.

| O que | Onde | Acesso |
|-------|------|--------|
| Arquivos sensíveis | `storage/app/private/` | Rota autenticada + `PortalVisibility` (documentos) |
| Assets públicos (se houver) | `storage/app/public/` | **Não usar** para documentos do portal |

**Disco:** disco nomeado `private` em `config/filesystems.php` → `storage/app/private` (Laravel 13).

**Pastas:**

```
storage/app/private/
├── governanca/{segmento_slug}/
├── indicadores/{empresa_id}/{ano}/
├── financeiro/{empresa_id}/
└── cadastros/{empresa_id}/
```

**Fluxo:** upload via `Storage::disk('private')` → `arquivo_path` relativo no banco (UUID no disco) → download via `DocumentoDownloadController` após checagem em `App\Support\PortalVisibility` (associada) ou sessão Admin.

| Módulo | Autorização (homolog) |
|--------|------------------------|
| Governança | `PortalVisibility::podeBaixar` + `DocumentoDownloadController` |
| Indicadores | Previsto no mesmo padrão (UI pendente) |
| Financeiro / rateios | Previsto no mesmo padrão (UI pendente) |

> Spec original citava Policies Laravel (`DocumentoPolicy` etc.). Homolog centraliza a ACL de conteúdo em `PortalVisibility` — divergência aceita; ver `docs/requisitos de software/`.

**Implementação:** Filament `FileUpload` com `->disk('private')`. **`storage:link` não necessário** para uploads do portal.

**Ambientes:** mesmo padrão em local, homolog (AWS) e produção (Hostgator em `/home1/eletr328/portal/storage/app/private/`). S3 **não previsto** na fase inicial.

### 9.7 Convenções de código

- **Idioma do código:** inglês (models, migrations, variáveis)
- **Idioma da interface:** português (BR)
- **Backend:** PHP 8.3+, Laravel 13, Filament 4, Livewire
- **Nomenclatura de tabelas:** plural, snake_case em português
- **Enums:** PHP backed enums
- **Form Requests** / validação Filament / Livewire conforme a camada
- **Autorização de conteúdo:** `App\Support\PortalVisibility` (Policies Laravel não usadas na pasta `app/Policies`)
- **Resources Filament** para entidades do admin

---

## 10. Etapa 1 — Base técnica *(concluída)*

> A Etapa 1 (fundação) está **feita**. Homolog já inclui também UIs de cadastro e governança. Status detalhado: `docs/requisitos de software/01-requisitos-de-software.md`.

### 10.1 Tarefas

- [x] Instalação e configuração do **Laravel 13**
- [x] Instalação e configuração do **Filament 4**
- [x] Instalação do **Livewire** (portal)
- [x] Setup **Docker** local (`docker-compose.yml` ou Laravel Sail)
- [x] Configuração do ambiente **homolog** (AWS Neotix) — branch `homolog` + workflow de deploy
- [ ] Configuração do ambiente **produção** (Hostgator) — no deploy
- [x] Configurar disco `private` em `config/filesystems.php`
- [x] Modelagem e criação das **migrations** e **models** (seção 8)
- [x] Seeders: segmentos, órgãos, perguntas do censo, admin Eletros
- [ ] Seeder da matriz de acessos (importar aba ACESSOS do escopo) — vínculo manual no CRUD de empresa
- [x] Verificação de compatibilidade com servidor **Hostgator** (seção 11 / `HOSTGATOR.md`)
- [x] Este arquivo `BRIEFING.md`

### 10.2 Além da Etapa 1 (já em homolog)

- Admin: Resources de grupos, empresas, segmentos, órgãos, produtos, documentos, reuniões, solicitações financeiras, usuários; página `VisibilidadeDoPortal`
- Portal: login, definir senha, home, filiação, representação, documentos (download/visualização)
- Autorização de documentos via `PortalVisibility`

### 10.3 Estrutura de diretórios (atual)

```
/
├── app/
│   ├── Enums/
│   ├── Filament/Resources/
│   ├── Filament/Pages/
│   ├── Livewire/Portal/
│   ├── Http/Controllers/
│   │   └── DocumentoDownloadController.php
│   ├── Models/
│   └── Support/
│       └── PortalVisibility.php
├── resources/views/
│   ├── livewire/portal/
│   └── components/layouts/
├── docker-compose.yml             # ou Laravel Sail
├── storage/app/private/
├── database/
├── docs/
│   └── requisitos de software/
├── BRIEFING.md
└── ...
```

---

## 11. Servidor do cliente — Hostgator

> Detalhes completos de hospedagem, deploy e checklist técnico: **`HOSTGATOR.md`**

### Resumo

| Ambiente | Onde | URL |
|----------|------|-----|
| **Homologação** | Servidor **AWS Neotix** | A definir |
| **Produção** | **Hostgator** — Pacote G, servidor `br210` | `portal.eletros.org.br` |

MySQL 5.7, Apache 2.4, PHP, extensões, Composer e disco confirmados na Hostgator. Stack: **Laravel + Livewire**; **Docker só no dev local**. Homolog (AWS) e produção (Hostgator) sem Docker. Detalhes em `HOSTGATOR.md`.

---

## 12. Pendências e decisões a tomar

### 12.1 Próximo incremento de produto *(definido em 27/08/2026)*

Ordem de trabalho após alinhamento homolog × documentação:

1. **Fechar o ciclo de cadastro** — UI Admin para revisar/aprovar filiação e representação + aplicar **Tipo de Acesso** no menu e nas rotas do Portal (em paralelo/apoio à validação com o cliente no item #6 abaixo).
2. **Calendário de reuniões no Portal** — consumir reuniões já cadastradas no Admin.
3. Sequência natural do escopo: conselhos/comissões → indicadores → financeiro portal → censo → perfil da associada.

Detalhamento: `docs/requisitos de software/01-requisitos-de-software.md` §6.

### 12.2 Decisões abertas

| # | Item | Responsável | Status |
|---|------|-------------|--------|
| 1 | Criar banco MySQL do portal e subdomínio com PHP 8.3 — ver `HOSTGATOR.md` §12 | Cliente/Neotix | ⏳ Pendente (no deploy) |
| 1b | Definir URL e provisionamento da homolog na AWS Neotix — ver `HOSTGATOR.md` §5 | Neotix | ⏳ Conforme ambiente |
| 2 | ~~Stack do portal~~ | Neotix | ✅ Livewire; Admin Filament 4 |
| 3 | ~~Estrutura do Cadastro de Filiação~~ | Cliente | ✅ Definido no escopo |
| 4 | ~~Lista completa de segmentos~~ | Cliente | ✅ CSAC, CSLB, CSLM, CSLP, CSTIC |
| 5 | ~~Regra de representantes~~ | Cliente | ✅ Titular + Suplente + Suporte por órgão |
| 6 | Mapear permissões exatas de cada Tipo de Acesso | Cliente | ⏳ Pendente *(bloqueia ACL fina do próximo incremento)* |
| 7 | Contato Suporte cria usuário no sistema ou é só cadastral? | Cliente | ⏳ Pendente |
| 8 | Histórico de Rateios: integração ou cadastro manual? | Cliente | ⏳ Pendente |
| 9 | Integração com sistema financeiro (boletos) | Cliente | ⏳ Pendente |
| 10 | Documentos de Governança variam por segmento? | Cliente | ⏳ Pendente *(código já permite segmento/órgão)* |
| 11 | Conselhos Setoriais: fluxo de e-mail é interno ou externo? | Cliente | ⏳ Pendente |
| 12 | ~~Storage de arquivos~~ | Neotix | ✅ Disco `private` local — ver §9.6 |
| 13 | Envio de e-mails (convite, notificações) | Neotix | ⏳ Parcial (convite admin master existe) |
| 14 | ~~Perfis portal~~ | Neotix | ✅ `associada_admin` / `associada_usuario` (não mais `portal`) |
| 15 | ~~Autorização de downloads~~ | Neotix | ✅ `PortalVisibility` (em vez de Policies Laravel) |

---

## 13. Glossário

| Termo | Significado |
|-------|-------------|
| **Associada** | Empresa membro da Eletros |
| **Grupo Econômico** | Conjunto de razões sociais sob um mesmo acesso (ex.: Britânia + Philco) |
| **Segmento** | Área setorial: CSAC, CSLB, CSLM, CSLP, CSTIC |
| **Órgão** | Conselho, Comissão ou módulo funcional (CADM, CTS AC, FINANC etc.) |
| **Representante Titular** | Representante principal de um órgão |
| **Tipo de Acesso** | Nível de permissão no portal (Sênior, Júnior, Financeiro etc.) |
| **Tipo de Grade** | Classificação de planilha de indicadores (Vazia, Consolidada, Auditoria) |
| **Governança** | Estatuto Social, Regulamento Associativo, Certificado de Filiação |
| **Indicador** | Métrica/reporte periódico exigido das associadas |
| **Censo** | Questionário anual com 40 perguntas em 6 seções |
| **Filiação** | Cadastro institucional da empresa na associação |
| **Rateio** | Divisão de custos entre associadas |
| **Disco private** | Armazenamento de arquivos fora do `public/`, acessível só via Laravel + `PortalVisibility` / sessão autenticada |

---

## 14. Referências

- Escopo do cliente: `docs/escopo-cliente.xlsx`
- Requisitos de software: `docs/requisitos de software/`
- Hospedagem e deploy: `HOSTGATOR.md`
- [Laravel 13 — Documentação](https://laravel.com/docs/13.x)
- [Filament 4 — Documentação](https://filamentphp.com/docs/4.x)
- [Livewire — Documentação](https://livewire.laravel.com/)
- [Laravel Sail (Docker)](https://laravel.com/docs/13.x/sail)
- [Laravel — Deployment](https://laravel.com/docs/13.x/deployment)
- [Hostgator — PHP Version](https://www.hostgator.com/help/article/what-version-of-php-are-you-using)

---

*Este documento deve ser atualizado a cada etapa do projeto com novas decisões, alterações de escopo e lições aprendidas. Última sincronização com homolog: 27/08/2026.*