photum/README.md

# 📸 Photum - Sistema de Gestão FOT (Formaturas e Eventos)

Sistema completo de gestão para eventos fotográficos, especializado em formaturas e eventos acadêmicos. Plataforma moderna e intuitiva para gerenciamento de FOTs (Formatura Operations Tracking), fotógrafos, instituições de ensino, empresas parceiras e entregas, com foco em excelência e atendimento humanizado.

---

## 🎯 Visão Geral

O **Photum** é uma aplicação web full-stack desenvolvida com React + TypeScript no frontend e Go no backend, que centraliza todo o fluxo de trabalho de uma empresa de fotografia especializada em formaturas, desde o cadastro inicial da turma até a entrega final do álbum.

### Principais Funcionalidades

- ✅ **Gestão FOT**: Sistema completo de gerenciamento de FOTs (Formatura Operations Tracking)
- ✅ **Gestão Multi-perfil**: Suporte para 4 tipos de usuários (Superadmin, Empresa, Fotógrafo, Cliente)
- ✅ **Gestão de Instituições**: Cadastro completo de universidades e faculdades
- ✅ **Controle de Eventos**: CRUD completo de eventos de formatura com status workflow
- ✅ **Dashboard Personalizado**: Interface Excel-style adaptada por perfil de usuário
- ✅ **Sistema de Aprovações**: Workflow de aprovação de eventos com atribuição de equipe
- ✅ **Gestão de Turmas**: Cadastro detalhado com FOT, empresa, instituição, ano formatura
- ✅ **Cadastro Profissional**: Sistema duplo de aprovação (usuários normais e profissionais)
- ✅ **Filtros Avançados**: Busca por FOT, data e tipo de evento
- ✅ **Mapas Interativos**: Integração com Mapbox para visualização de locais
- ✅ **Galeria de Inspirações**: Showcase de trabalhos anteriores
- ✅ **Backend Go**: API RESTful completa com PostgreSQL

---

## 🚀 Como Executar o Projeto

### Pré-requisitos

- **Node.js** (versão 18 ou superior)
- **npm** ou **yarn**

### Estrutura do Repositório

```
photum/
├── frontend/      # Aplicação React + TypeScript
├── backend/       # Backend (em desenvolvimento)
└── README.md      # Este arquivo
```

### Instalação e Execução

#### Frontend

1. **Clone o repositório**:

   ```bash
   git clone https://github.com/rede5/photum.git
   cd photum/frontend
   ```

2. **Instale as dependências**:

   ```bash
   npm install
   ```

3. **Configure as variáveis de ambiente**:

   - Crie um arquivo `.env.local` na pasta `frontend`
   - Adicione suas credenciais:
     ```env
     VITE_MAPBOX_TOKEN=seu_token_mapbox_aqui
     GEMINI_API_KEY=sua_chave_gemini_aqui
     ```

4. **Execute o projeto em modo desenvolvimento**:

   ```bash
   npm run dev
   ```

5. **Acesse no navegador**:
   ```
   http://localhost:3000
   ```

### Build para Produção

```bash
cd frontend
npm run build
npm run preview
```

---

## 🗺️ Rotas e Navegação

O sistema utiliza um **roteamento customizado baseado em estados** (sem React Router). As rotas disponíveis são:

| Rota                     | Descrição                                             | Acesso      |
| ------------------------ | ----------------------------------------------------- | ----------- |
| `/` (`home`)             | Landing page institucional com informações da empresa | Público     |
| `/login`                 | Tela de autenticação                                  | Público     |
| `/register`              | Cadastro de novos usuários                             | Público     |
| `/cadastro-profissional` | Cadastro de profissionais (fotógrafos)                | Público     |
| `/painel` (`dashboard`)  | Dashboard principal com filtros avançados (FOT, Data)  | Autenticado |
| `/cursos`                | Gestão FOT - Cadastro e edição de turmas             | Autenticado |
| `/aprovacao`             | Aprovação de cadastros (normais e profissionais)     | Admin       |
| `/request-event`         | Formulário de criação de evento de formatura          | Autenticado |
| `/inspiration`   | Galeria de inspirações e trabalhos anteriores         | Autenticado |
| `/calendar`      | Calendário de eventos de formatura                    | Autenticado |
| `/team`          | Gestão de equipe e fotógrafos                         | Autenticado |
| `/finance`       | Módulo financeiro e controle de pagamentos            | Autenticado |
| `/settings`      | Configurações do sistema e perfil                     | Autenticado |
| `/privacy`       | Política de privacidade                               | Público     |
| `/terms`         | Termos de uso                                         | Público     |
| `/lgpd`          | Informações sobre conformidade LGPD                   | Público     |

### Navegação no Sistema

A navegação acontece através do componente `<Navbar>` que chama a função `onNavigate(pageName)` passando o nome da rota desejada. Rotas protegidas redirecionam automaticamente para `/login` se o usuário não estiver autenticado.

---

## 🔐 Tela de Login e Usuários de Demonstração

### Como Acessar

1. Na página inicial, clique em **"Área do Cliente"**
2. Você será redirecionado para a **tela de login** (`/login`)

### Interface de Login

A tela de login apresenta:

- **Layout dividido**:
  - Lado esquerdo com imagem institucional
  - Lado direito com formulário de login
- **Campos**:
  - E-mail corporativo ou pessoal
  - Senha (desabilitada no modo demo)
- **Botão**: "Entrar no Sistema"

### Usuários de Demonstração

Não é necessário senha. Basta clicar em um dos cartões de usuário demo ou digitar o e-mail:

| Perfil         | Nome          | E-mail               | Descrição                      |
| -------------- | ------------- | -------------------- | ------------------------------ |
| **Superadmin** | Dev Admin     | `admin@photum.com`   | Acesso total ao sistema        |
| **Empresa**    | Carlos CEO    | `empresa@photum.com` | Dono da empresa de fotografia  |
| **Fotógrafo**  | Ana Lente     | `foto@photum.com`    | Profissional fotógrafo         |
| **Cliente**    | Juliana Noiva | `cliente@photum.com` | Cliente final (dono do evento) |

### Fluxo de Login

```
1. Usuário clica em "Área do Cliente" na Home
   ↓
2. Sistema redireciona para /login
   ↓
3. Usuário seleciona um perfil demo OU digita e-mail manualmente
   ↓
4. Sistema valida o e-mail com mock de usuários
   ↓
5. Se válido: redireciona para /dashboard
   Se inválido: exibe mensagem de erro
```

### Exemplo de Código (Login)

```tsx
// Login simplificado (sem senha)
const handleLogin = async (e: React.FormEvent) => {
  e.preventDefault();
  const success = await login(email); // Busca no mock de usuários
  if (!success) {
    setError("Usuário não encontrado");
  }
};
```

---

## 👥 Perfis de Usuário e Permissões

### 1. Superadmin (`SUPERADMIN`)

- **Acesso**: Total ao sistema
- **Funcionalidades**:
  - Visualiza todos os eventos
  - Gerencia todos os usuários
  - Acesso a configurações avançadas

### 2. Dono da Empresa (`BUSINESS_OWNER`)

- **Acesso**: Administrativo
- **Funcionalidades**:
  - Cria e edita eventos
  - Atribui fotógrafos
  - Aprova solicitações de clientes
  - Gerencia equipe

### 3. Fotógrafo (`PHOTOGRAPHER`)

- **Acesso**: Operacional
- **Funcionalidades**:
  - Visualiza eventos atribuídos
  - Atualiza status de eventos
  - Faz upload de fotos
  - Acessa detalhes de contatos

### 4. Cliente (`EVENT_OWNER`)

- **Acesso**: Restrito aos próprios eventos
- **Funcionalidades**:
  - Solicita novos eventos
  - Acompanha status do seu evento
  - Visualiza fotos do evento
  - Eventos criados entram em status "Aguardando Aprovação"

---

## 📊 Status de Eventos

Os eventos seguem um workflow com os seguintes status:

| Status                 | Descrição                                   | Cor          |
| ---------------------- | ------------------------------------------- | ------------ |
| `Aguardando Aprovação` | Cliente criou, aguarda aprovação da empresa | Cinza        |
| `Em Planejamento`      | Aprovado, em fase de planejamento           | Azul         |
| `Confirmado`           | Evento confirmado e agendado                | Verde        |
| `Em Execução`          | Evento acontecendo                          | Roxo         |
| `Entregue`             | Fotos entregues ao cliente                  | Verde escuro |
| `Arquivado`            | Evento finalizado e arquivado               | Cinza escuro |

---

## 🛠️ Tecnologias Utilizadas

### Core

- **React 19.2.0** - Biblioteca JavaScript para UI
- **TypeScript 5.8.2** - Superset tipado do JavaScript
- **Vite 6.2.0** - Build tool e dev server ultra-rápido

### UI/UX

- **Lucide React 0.554.0** - Ícones modernos e customizáveis
- **TailwindCSS** - Framework CSS utility-first (configurado via classes inline)

### Mapas e Geolocalização

- **Mapbox GL 3.16.0** - Mapas interativos e geolocalização
- **@types/mapbox-gl 3.4.1** - Tipos TypeScript para Mapbox

### Navegação

- **React Router DOM 7.9.6** - Sistema de roteamento e navegação

### IA e APIs

- **@google/genai 1.30.0** - Integração com Google Gemini AI

### Build Tools

- **@vitejs/plugin-react 5.0.0** - Plugin oficial do Vite para React
- **@types/node 22.14.0** - Tipos TypeScript para Node.js

---

## 📁 Estrutura do Projeto

```
photum/
├── frontend/                # Aplicação Frontend
│   ├── components/          # Componentes reutilizáveis
│   │   ├── Button.tsx       # Botão customizado
│   │   ├── CourseForm.tsx   # Formulário de cadastro FOT
│   │   ├── EventCard.tsx    # Card de evento
│   │   ├── EventForm.tsx    # Formulário de evento
│   │   ├── EventTable.tsx   # Tabela de eventos (8 colunas)
│   │   ├── EventFiltersBar.tsx  # Filtros avançados (FOT, Data, Tipo)
│   │   ├── Input.tsx        # Input customizado
│   │   ├── 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
│   │   ├── AuthContext.tsx  # Autenticação e usuários
│   │   └── DataContext.tsx  # Gerenciamento de eventos e instituições
│   ├── pages/               # Páginas principais
│   │   ├── Calendar.tsx     # Calendário de eventos
│   │   ├── CourseManagement.tsx  # Gestão FOT (Turmas)
│   │   ├── Dashboard.tsx    # Dashboard principal (Painel)
│   │   ├── Finance.tsx      # Gestão financeira
│   │   ├── Home.tsx         # Landing page
│   │   ├── Inspiration.tsx  # Galeria de inspirações
│   │   ├── LGPD.tsx         # Conformidade LGPD
│   │   ├── Login.tsx        # Tela de login
│   │   ├── PrivacyPolicy.tsx  # Política de privacidade
│   │   ├── ProfessionalRegister.tsx  # Cadastro profissional
│   │   ├── Register.tsx     # Cadastro de usuários
│   │   ├── Settings.tsx     # Configurações
│   │   ├── Team.tsx         # Gestão de equipe
│   │   ├── TermsOfUse.tsx   # Termos de uso
│   │   └── UserApproval.tsx  # Aprovação de cadastros
│   ├── services/            # Serviços e APIs
│   │   ├── genaiService.ts  # Integração Google GenAI
│   │   ├── mapboxService.ts # Serviços Mapbox
│   │   └── mockGeoService.ts # Mock de geolocalização
│   ├── public/              # Arquivos estáticos
│   ├── App.tsx              # Componente raiz + roteamento
│   ├── constants.ts         # Constantes globais
│   ├── types.ts             # Tipos TypeScript
│   ├── index.tsx            # Entry point
│   ├── package.json         # Dependências
│   ├── tsconfig.json        # Config TypeScript
│   ├── vite.config.ts       # Config Vite
│   └── README.md            # Documentação do frontend
│   └── services/            # Serviços e APIs
│       ├── apiService.ts    # API REST do backend Go
│       ├── genaiService.ts  # Integração Google GenAI
│       ├── mapboxService.ts # Serviços Mapbox
│       └── mockGeoService.ts # Mock de geolocalização
│
├── backend/                 # Backend Go + PostgreSQL
│   ├── cmd/api/             # Entry point
│   ├── internal/            # Lógica de negócio
│   │   ├── auth/            # Autenticação e tokens
│   │   ├── cadastro_fot/    # Gestão FOT
│   │   ├── empresas/        # Empresas parceiras
│   │   ├── cursos/          # Cursos universitários
│   │   ├── profissionais/   # Profissionais cadastrados
│   │   └── db/              # Queries SQL (sqlc)
│   ├── docs/                # Documentação Swagger
│   ├── docker-compose.yml   # PostgreSQL container
│   └── Makefile             # Comandos build/test
│
└── README.md                # Este arquivo
```

---

## 🎯 Gestão FOT (Formatura Operations Tracking)

O sistema FOT é o core do Photum, permitindo gestão completa de turmas de formatura:

### Campos do FOT

- **FOT** (5 dígitos, somente números) - Identificador único da turma
- **Empresa** - Empresa parceira responsável
- **EF I/EF II** - Nível educacional
- **Observações** - Notas e informações adicionais
- **Instituição** - Universidade/Faculdade (dropdown da API)
- **Ano Formatura** - Ano de conclusão do curso
- **Cidade** e **Estado** - Localização
- **Gastos Captação** - Investimento em marketing
- **Pré Venda** - Valores pré-negociados

### Funcionalidades da Tela FOT (`/cursos`)

- ✅ Tabela estilo Excel com todas as turmas
- ✅ Botão "Cadastrar Turma" abrindo modal
- ✅ Edição de turmas existentes (clique na linha)
- ✅ Integração com API backend para empresas, níveis educacionais e universidades
- ✅ Validação de FOT (5 dígitos numéricos)

---

## 📋 Dashboard e Filtros

### Tabela de Eventos (`/painel`)

Tabela Excel-style com 8 colunas principais:

1. **FOT** - Número identificador da turma
2. **Data** - Data do evento
3. **Curso** - Nome do curso
4. **Instituição** - Universidade/Faculdade
5. **Ano Formatura** - Ano de conclusão
6. **Empresa** - Empresa parceira
7. **Tipo Evento** - Categoria do evento
8. **Status** - Status atual do workflow
9. **Ações** (condicional) - Botão Aprovar (apenas para empresa)

### Filtros Avançados

- **FOT** - Campo de busca (somente números, 5 dígitos)
- **Data** - Seletor de data
- **Tipo de Evento** - Dropdown com tipos disponíveis

### Página de Detalhes

Ao clicar em um evento, exibe tabela vertical com 12 informações:

- FOT, Data, Curso, Instituição, Ano Formatura
- Empresa, Tipo Evento, Observações
- Local, Endereço, Horário, Qtd Formandos

---

## 👥 Sistema de Aprovação Dupla

### Tela de Aprovação (`/aprovacao`)

Sistema com **2 tabelas separadas por abas**:

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

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

### Cadastro Profissional (`/cadastro-profissional`)

- Formulário específico para fotógrafos
- 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"

### Workflow de Aprovação para Eventos

1. Empresa clica em "Aprovar" na tabela
2. Sistema redireciona para detalhes do evento
3. Modal de "Gerenciar Equipe" abre automaticamente
4. Empresa atribui profissionais ao evento
5. Confirma aprovação com equipe definida

---

## 🎭 Modal de Criar Evento

### Ordem dos Campos (Detalhes & Data)

1. **Tipo de Evento*** (primeiro campo)
2. **Nome do Evento (Opcional)**
3. Data Pretendida
4. Horário de Início* e Término*
5. Número de universitários
6. Demais campos...

---

## 🔗 Integração com Backend

### Endpoints da API

```typescript
// Empresas
GET /api/empresas

// Funções Profissionais
GET /api/funcoes

// Níveis Educacionais
GET /api/niveis-educacionais

// Universidades
GET /api/universidades

// Anos de Formatura
GET /api/graduation-years

// Tipos de Eventos
GET /api/tipos-eventos
```

### Tratamento de Erros

- Todos os componentes que consomem API têm tratamento de erro
- Exibição de mensagens amigáveis quando backend está offline
- Loading states durante requisições

---

## 🎨 Temas e Design System

### Cores da Marca

```css
/* Cores principais */
--brand-purple: #9333ea (roxo vibrante - cor primária)
--brand-black: #000000 (preto puro)
--brand-white: #ffffff (branco puro)

/* Status Colors (definidas em constants.ts) */
Aguardando Aprovação: #6b7280 (gray-500)
Em Planejamento: #3b82f6 (blue-500)
Confirmado: #10b981 (green-500)
Em Execução: #8b5cf6 (purple-500)
Entregue: #059669 (emerald-600)
Arquivado: #4b5563 (gray-600)
```

### Tipografia

- **Títulos e Headings**: System Font Stack
- **Corpo e Parágrafos**: System Font Stack
- **Tamanhos**: Sistema responsivo com classes Tailwind (text-sm, text-base, text-lg, etc.)

### Componentes Visuais

- **Cards**: Sombras suaves, bordas arredondadas
- **Botões**: Variantes primary (roxo), secondary (preto), danger (vermelho)
- **Inputs**: Bordas cinza, foco com anel roxo
- **Navbar**: Gradiente roxo com transparência

---

## 🔄 Workflows do Sistema

### Workflow de Criação de Evento (Cliente)

```
1. Cliente faz login
   ↓
2. Acessa "Solicitar Evento"
   ↓
3. Preenche formulário (nome, tipo, data, endereço, contatos)
   ↓
4. Evento criado com status "Aguardando Aprovação"
   ↓
5. Empresa visualiza solicitação
   ↓
6. Empresa aprova → Status muda para "Confirmado"
   ↓
7. Empresa atribui fotógrafo
   ↓
8. Fotógrafo acessa evento e realiza trabalho
   ↓
9. Status atualizado conforme workflow
   ↓
10. Cliente visualiza fotos e álbum final
```

### Workflow de Gestão (Empresa)

```
1. Empresa cria evento diretamente (status: "Em Planejamento")
   ↓
2. Adiciona informações detalhadas
   ↓
3. Atribui fotógrafos à equipe
   ↓
4. Confirma evento (status: "Confirmado")
   ↓
5. Acompanha execução
   ↓
6. Marca como entregue após conclusão
```

---

## 🧪 Dados de Teste (Mock)

O sistema utiliza dados mockados no frontend para demonstração:

### Usuários Mock (AuthContext.tsx)

- 4 usuários pré-cadastrados com diferentes perfis (ver seção de Login)

### Eventos Mock (DataContext.tsx)

- Eventos de exemplo de formaturas e casamentos
- Diferentes status para demonstrar o workflow completo
- Atribuições de fotógrafos e instituições

### Instituições Mock (DataContext.tsx)

- Universidade Federal do Rio Grande do Sul (UFRGS)
- Exemplos de outras instituições de ensino

---

## 🚧 Funcionalidades em Desenvolvimento

### Backend

- API RESTful completa
- Banco de dados relacional
- Autenticação JWT
- Upload e armazenamento de fotos

### Frontend

As seguintes funcionalidades estão parcialmente implementadas:

- **Team** - Gestão completa de equipe e fotógrafos
- **Finance** - Módulo financeiro com relatórios
- **Calendar** - Calendário completo com múltiplas visualizações
- **Settings** - Painel de configurações avançadas

---

## 📝 Scripts Disponíveis

### Frontend

| Comando           | Descrição                                            |
| ----------------- | ---------------------------------------------------- |
| `npm run dev`     | Inicia servidor de desenvolvimento Vite (porta 3000) |
| `npm run build`   | Gera build de produção otimizado                     |
| `npm run preview` | Preview do build de produção                         |

### Backend

_Em desenvolvimento_

---

## 🤝 Contribuindo

Este é um projeto em desenvolvimento ativo. Contribuições são bem-vindas!

### Branch Strategy

- **main**: Branch de produção estável
- **dev**: Branch de desenvolvimento ativo (branch padrão para PRs)

### Como Contribuir

1. Fork o projeto
2. Crie uma branch para sua feature (`git checkout -b feature/AmazingFeature`)
3. Commit suas mudanças (`git commit -m 'Add some AmazingFeature'`)
4. Push para a branch (`git push origin feature/AmazingFeature`)
5. Abra um Pull Request para a branch `dev`

---

## 📄 Licença

Projeto privado - Todos os direitos reservados © 2025 Photum Formaturas

---

## 📞 Suporte e Contato

### Repositório e Issues

- **GitHub**: [github.com/rede5/photum](https://github.com/rede5/photum)
- **Issues**: Abra uma issue no GitHub para reportar bugs ou sugerir melhorias

### Contato Comercial

- **Email**: contato@photum.com.br
- **Telefone**: (19) 3405-5024 | (19) 3621-4621
- **Localização**: Americana, SP

### Redes Sociais

- Instagram: @photumformaturas
- Facebook: /photumformaturas
- YouTube: Photum Formaturas

---

## 🎯 Roadmap Futuro

### Curto Prazo (Q1 2025)

- [x] Sistema básico de gestão de eventos
- [x] Autenticação multi-perfil
- [x] Dashboard responsivo
- [x] Integração com Mapbox
- [ ] Sistema completo de upload de fotos
- [ ] Módulo de calendário funcional

### Médio Prazo (Q2-Q3 2025)

- [ ] Backend completo com API REST
- [ ] Banco de dados PostgreSQL
- [ ] Sistema de notificações em tempo real
- [ ] Módulo financeiro completo
- [ ] Gestão de equipe avançada
- [ ] Sistema de relatórios e analytics

### Longo Prazo (Q4 2025 e além)

- [ ] App Mobile (React Native)
- [ ] Integração com APIs de pagamento (Stripe, PagSeguro)
- [ ] Assinatura digital de contratos
- [ ] Exportação de relatórios PDF/Excel
- [ ] Sistema de galeria privada para clientes
- [ ] Integração com CRM
- [ ] Automação de email marketing
- [ ] Sistema de agendamento online

---

## 🏆 Diferenciais do Projeto

- ✨ **Interface Moderna**: Design clean e intuitivo com foco em UX
- 🎓 **Especialização**: Focado especificamente em formaturas e eventos acadêmicos
- 🗺️ **Geolocalização**: Mapas interativos para localização de eventos
- 🤖 **IA Integrada**: Google GenAI para funcionalidades inteligentes
- 📱 **Responsivo**: Funciona perfeitamente em dispositivos móveis
- 🔐 **Seguro**: Conformidade com LGPD e boas práticas de segurança
- 🎨 **Customizável**: Sistema de temas e personalização

---

**Desenvolvido com ❤️ para eternizar momentos únicos** ✨📸