photum/frontend/README.md

# Frontend - Photum Formaturas

Sistema de gerenciamento FOT (Formatura Operations Tracking) e eventos desenvolvido com React, TypeScript e Vite.

## 📋 Índice

- [Tecnologias](#tecnologias)
- [Estrutura do Projeto](#estrutura-do-projeto)
- [Instalação](#instalação)
- [Scripts Disponíveis](#scripts-disponíveis)
- [Arquitetura](#arquitetura)
- [Componentes](#componentes)
- [Páginas](#páginas)
- [Novidades e Features](#novidades-e-features)
- [Contextos](#contextos)
- [Serviços](#serviços)
- [Tipos](#tipos)
- [Configuração](#configuração)

## 🚀 Tecnologias

- **React 19.2.0** - Biblioteca para construção de interfaces
- **TypeScript 5.8.2** - Superset JavaScript com tipagem estática
- **Vite 6.2.0** - Build tool e dev server de alta performance
- **React Router DOM 7.9.6** - Navegação entre páginas
- **Mapbox GL 3.16.0** - Mapas interativos
- **Google GenAI 1.30.0** - Integração com IA generativa do Google
- **Lucide React 0.554.0** - Ícones modernos
- **TailwindCSS** - Framework CSS utility-first (via classes inline)

## 📁 Estrutura do Projeto

```
frontend/
├── components/          # Componentes reutilizáveis
│   ├── Button.tsx      # Botão customizável
│   ├── CourseForm.tsx  # Formulário de cadastro FOT
│   ├── EventCard.tsx   # Card de exibição de eventos
│   ├── EventForm.tsx   # Formulário de criação/edição de eventos
│   ├── EventTable.tsx  # Tabela Excel-style (8 colunas)
│   ├── EventFiltersBar.tsx  # Filtros avançados (FOT, Data, Tipo)
│   ├── Input.tsx       # Input customizável
│   ├── InstitutionForm.tsx  # Formulário de instituições
│   ├── MapboxMap.tsx   # Componente de mapa interativo
│   ├── Navbar.tsx      # Barra de navegação
│   └── ProfessionalForm.tsx  # Formulário cadastro profissional
│
├── contexts/           # Context API para gerenciamento de estado
│   ├── AuthContext.tsx # Autenticação e usuários
│   └── DataContext.tsx # Eventos e instituições
│
├── pages/             # Páginas da aplicação
│   ├── Calendar.tsx   # Calendário de eventos
│   ├── CourseManagement.tsx  # Gestão FOT (Turmas)
│   ├── Dashboard.tsx  # Painel principal (Tabela de eventos)
│   ├── Finance.tsx    # Gestão financeira
│   ├── Home.tsx       # Página inicial/landing
│   ├── Inspiration.tsx # Galeria de inspirações
│   ├── LGPD.tsx       # Página de conformidade LGPD
│   ├── Login.tsx      # Página de login
│   ├── PrivacyPolicy.tsx  # Política de privacidade
│   ├── ProfessionalRegister.tsx  # Cadastro profissional
│   ├── Register.tsx   # Cadastro de novos usuários
│   ├── Settings.tsx   # Configurações do sistema
│   ├── Team.tsx       # Gestão de equipe
│   ├── TermsOfUse.tsx # Termos de uso
│   └── UserApproval.tsx  # Aprovação de cadastros (2 tabelas)
│
├── services/          # Serviços externos e APIs
│   ├── apiService.ts      # API REST do backend Go
│   ├── genaiService.ts    # Integração com Google GenAI
│   ├── mapboxService.ts   # Serviços do Mapbox
│   └── mockGeoService.ts  # Mock para testes de geolocalização
│
├── public/            # Arquivos estáticos
├── App.tsx           # Componente raiz da aplicação
├── index.tsx         # Ponto de entrada da aplicação
├── types.ts          # Definições de tipos TypeScript
├── constants.ts      # Constantes da aplicação
├── vite.config.ts    # Configuração do Vite
├── tsconfig.json     # Configuração do TypeScript
└── package.json      # Dependências e scripts
```

## 🔧 Instalação

```bash
# Instalar dependências
npm install

# Configurar variáveis de ambiente
cp .env.example .env.local

# Editar .env.local com suas credenciais
# VITE_MAPBOX_TOKEN=seu_token_aqui
# GEMINI_API_KEY=sua_chave_aqui
```

## 📜 Scripts Disponíveis

```bash
# Iniciar servidor de desenvolvimento (porta 3000)
npm run dev

# Build para produção
npm run build

# Preview da build de produção
npm run preview
```

## 🏗️ Arquitetura

### Gerenciamento de Estado

O projeto utiliza **Context API** do React para gerenciar estado global:

- **AuthContext**: Gerencia autenticação, usuários e permissões
- **DataContext**: Gerencia eventos, instituições e dados relacionados

### Roteamento

Navegação baseada em estados internos controlada pelo componente `App.tsx`, sem uso de React Router para simplicidade.

### Estilização

Utiliza **Tailwind CSS** (via classes inline) com tema customizado:

- Cores principais: roxo (`brand-purple`) e preto (`brand-black`)
- Design responsivo mobile-first
- Componentes reutilizáveis estilizados

## 🧩 Componentes

### Button.tsx

Botão reutilizável com variantes de estilo e estados de carregamento.

### CourseForm.tsx

Modal completo para cadastro e edição de FOTs (turmas) com 10 campos:
- FOT ID (5 dígitos, validação numérica)
- Empresa (dropdown da API)
- Nível Educacional (dropdown da API)
- Observações
- Instituição (dropdown de universidades da API)
- Ano Formatura (dropdown da API)
- Cidade e Estado
- Gastos Captação e Pré Venda

**Features:**
- Validação de FOT (apenas números, máximo 5 dígitos)
- Carregamento automático de dados ao editar
- Integração completa com backend

### EventTable.tsx

Tabela Excel-style para exibição de eventos com **8 colunas**:
1. FOT
2. Data
3. Curso
4. Instituição
5. Ano Formatura
6. Empresa
7. Tipo Evento
8. Status
9. Ações (condicional para empresa)

**Features:**
- Ordenação por todas as colunas
- Click na linha abre detalhes
- Botão "Aprovar" abre modal de equipe
- Design responsivo

### EventFiltersBar.tsx

Barra de filtros avançados com **3 filtros**:
- **FOT**: Campo de busca numérico (5 dígitos)
- **Data**: Seletor de data
- **Tipo de Evento**: Dropdown

**Features:**
- Busca em tempo real
- Exibição de filtros ativos
- Botão limpar filtros
- Grid responsivo (3 colunas)

### EventCard.tsx

Card para exibição visual de eventos com informações principais (data, tipo, status).

### EventForm.tsx

Formulário completo para criar e editar eventos com validação de campos.

**Nova ordem de campos:**
1. Tipo de Evento* (primeiro)
2. Nome do Evento (Opcional)
3. Data e horários
4. Demais campos...

### Input.tsx

Input customizado com suporte a diferentes tipos e validação.

### InstitutionForm.tsx

Formulário para cadastro e edição de instituições de ensino.

### MapboxMap.tsx

Componente de mapa interativo usando Mapbox GL para visualização de localizações.

### Navbar.tsx

Barra de navegação responsiva com menu e controle de autenticação.

### ProfessionalForm.tsx

Formulário específico para cadastro de profissionais (fotógrafos).

**Features:**
- Campo "Função Profissional" com dropdown da API
- Tratamento de erro quando backend não está rodando
- Mensagem: "❌ Erro ao carregar funções. Verifique se o backend está rodando"

## 📄 Páginas

### Home.tsx

Landing page com apresentação da empresa, serviços e informações de contato.

### Login.tsx / Register.tsx / ProfessionalRegister.tsx

Páginas de autenticação para acesso ao sistema:
- **Login**: Autenticação de usuários
- **Register**: Cadastro de usuários normais
- **ProfessionalRegister**: Cadastro específico para fotógrafos

### Dashboard.tsx (`/painel`)

Painel principal com visualização e gerenciamento de eventos.

**Features:**
- Tabela Excel-style com 8 colunas
- Filtros avançados (FOT, Data, Tipo)
- Busca por nome
- Filtros rápidos (Todos, Ativos, Pendentes)
- Click na linha → Detalhes do evento
- Página de detalhes com tabela vertical (12 informações)

### CourseManagement.tsx (`/cursos`)

Gestão FOT - Cadastro e edição de turmas.

**Features:**
- Tabela Excel-style com todas as turmas
- Botão "Cadastrar Turma" no header
- Click na linha para editar
- Modal CourseForm integrado
- 11 colunas de informações

### UserApproval.tsx (`/aprovacao`)

Aprovação de cadastros com **2 tabelas separadas**:

**Aba "Usuários Normais":**
- Filtra `role !== 'PHOTOGRAPHER'`
- Colunas: Nome, Email, Telefone, Data, Status, Ações

**Aba "Profissionais":**
- Filtra profissionais fotógrafos
- Colunas: Nome, Email, Telefone, **Função**, Data, Status, Ações

### Calendar.tsx

Visualização de eventos em formato de calendário mensal.

### Team.tsx

Gestão da equipe de fotógrafos e colaboradores.

### Finance.tsx

Controle financeiro e relatórios de eventos.

### Settings.tsx

Configurações do sistema e preferências do usuário.

### Inspiration.tsx

Galeria de fotos e inspirações para clientes.

### PrivacyPolicy.tsx / TermsOfUse.tsx / LGPD.tsx

Páginas legais e de conformidade.

## 🎯 Novidades e Features

### ✨ Sistema FOT Completo
- Cadastro de turmas com 10 campos
- Validação de FOT (5 dígitos numéricos)
- Integração com API para dropdowns
- Edição em modal

### ✨ Dashboard Renovado
- Tabela de 8 colunas (FOT, Data, Curso, Instituição, Ano, Empresa, Tipo, Status)
- Filtro de busca por FOT
- Detalhes do evento em tabela vertical

### ✨ Sistema de Aprovação Dupla
- 2 tabelas separadas (Normais e Profissionais)
- Aprovação de eventos abre modal de equipe
- Workflow completo de aprovação

### ✨ Cadastro Profissional
- Formulário específico para fotógrafos
- Dropdown de funções da API
- Tratamento de erro quando backend offline

### ✨ Filtros Avançados
- Busca por FOT (numérico, 5 dígitos)
- Filtro por Data
- Filtro por Tipo de Evento
- Removidos filtros de Estado e Cidade

### ✨ Modal de Evento Reorganizado
- "Tipo de Evento" como primeiro campo
- "Nome do Evento" como opcional em segundo

## 🔄 Contextos

### AuthContext

```typescript
interface AuthContextType {
  user: User | null;
  login: (email: string) => Promise<boolean>;
  logout: () => void;
  availableUsers: User[]; // Para demo
}
```

**Usuários Mock Disponíveis:**

- SuperAdmin: `admin@photum.com`
- Business Owner: `empresa@photum.com`
- Fotógrafo: `foto@photum.com`
- Cliente: `cliente@photum.com`

### DataContext

```typescript
interface DataContextType {
  events: EventData[];
  institutions: Institution[];
  addEvent: (event: EventData) => void;
  updateEventStatus: (id: string, status: EventStatus) => void;
  assignPhotographer: (eventId: string, photographerId: string) => void;
  getEventsByRole: (userId: string, role: string) => EventData[];
  addInstitution: (institution: Institution) => void;
  updateInstitution: (id: string, institution: Partial<Institution>) => void;
  getInstitutionsByUserId: (userId: string) => Institution[];
  getInstitutionById: (id: string) => Institution | undefined;
}
```

## 🛠️ Serviços

### genaiService.ts

Integração com Google Gemini AI para funcionalidades de IA generativa.

### mapboxService.ts

Serviços de mapeamento e geolocalização usando Mapbox API.

### mockGeoService.ts

Serviço mock para testes de geolocalização sem consumir API externa.

## 📝 Tipos

### UserRole (Enum)

- `SUPERADMIN`: Acesso total ao sistema
- `BUSINESS_OWNER`: Proprietário do negócio
- `EVENT_OWNER`: Cliente/dono do evento
- `PHOTOGRAPHER`: Fotógrafo

### EventStatus (Enum)

- `PENDING_APPROVAL`: Aguardando aprovação
- `PLANNING`: Em planejamento
- `CONFIRMED`: Confirmado
- `IN_PROGRESS`: Em execução
- `DELIVERED`: Entregue
- `ARCHIVED`: Arquivado

### EventType (Enum)

- `WEDDING`: Casamento
- `CORPORATE`: Corporativo
- `BIRTHDAY`: Aniversário
- `DEBUTANTE`: Debutante
- `OTHER`: Outro

### Interfaces Principais

```typescript
interface User {
  id: string;
  name: string;
  email: string;
  role: UserRole;
  avatar?: string;
  institutionId?: string;
}

interface Institution {
  id: string;
  name: string;
  type: string;
  cnpj?: string;
  phone: string;
  email: string;
  address?: Address;
  description?: string;
  ownerId: string;
}

interface EventData {
  id: string;
  name: string;
  date: string;
  time: string;
  type: EventType;
  status: EventStatus;
  address: Address;
  contacts: Contact[];
  checklist: ChecklistItem[];
  briefing: string;
  coverImage: string;
  ownerId: string;
  photographerIds: string[];
  institutionId?: string;
}
```

## ⚙️ Configuração

### vite.config.ts

```typescript
- Porta padrão: 3000
- Host: 0.0.0.0 (acesso externo)
- Variáveis de ambiente: GEMINI_API_KEY
- Alias: '@' aponta para a raiz do frontend
```

### Variáveis de Ambiente

Crie um arquivo `.env.local`:

```env
VITE_MAPBOX_TOKEN=seu_token_mapbox
GEMINI_API_KEY=sua_chave_gemini
```

## 🎨 Design System

### Cores Principais

- **brand-purple**: Cor primária da marca
- **brand-black**: Cor secundária/texto
- Tons de cinza para backgrounds e bordas

### Breakpoints Responsivos

- Mobile: < 640px
- Tablet: 640px - 1024px
- Desktop: > 1024px

## 📱 Funcionalidades

- ✅ Autenticação multi-perfil (SuperAdmin, Owner, Photographer, Client)
- ✅ CRUD completo de eventos
- ✅ Gestão de instituições de ensino
- ✅ Calendário visual de eventos
- ✅ Mapas interativos com Mapbox
- ✅ Sistema de checklists para eventos
- ✅ Galeria de inspirações
- ✅ Gestão de equipe
- ✅ Controle financeiro
- ✅ Páginas de conformidade legal (LGPD, Termos, Privacidade)

## 🔒 Segurança

- Autenticação baseada em contexto
- Validação de permissões por role
- Proteção de rotas baseada em autenticação
- Conformidade com LGPD

## 🚧 Desenvolvimento

O projeto está configurado com:

- Hot Module Replacement (HMR)
- TypeScript strict mode
- Linting automático
- Path aliases

## 📞 Suporte

Para dúvidas ou problemas:

- Email: contato@photum.com.br
- Tel: (19) 3405 5024 | (19) 3621 4621

---

**Desenvolvido por Photum Formaturas** © 2025