📸 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:

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

2. Instale as dependências:

   npm install
   

3. Configure as variáveis de ambiente:

   • Crie um arquivo .env.local na pasta frontend
   • Adicione suas credenciais:

     VITE_MAPBOX_TOKEN=seu_token_mapbox_aqui
     GEMINI_API_KEY=sua_chave_gemini_aqui
     

4. Execute o projeto em modo desenvolvimento:

   npm run dev
   

5. Acesse no navegador:

   http://localhost:3000
   

Build para Produção

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)

// 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

// 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

/* 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
• 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)

• Sistema básico de gestão de eventos
• Autenticação multi-perfil
• Dashboard responsivo
• 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 ✨📸