Referência de API

Documentação das rotas e endpoints da plataforma Divino Cestas (commit 2b1881fafe).

📋 Visão Geral

A plataforma usa arquitetura MVC com Express.js. As rotas estão definidas em app/src/routes.js.

Base URL: http://localhost:13000 (desenvolvimento)

Autenticação: OpenID Connect (OAuth 2.0)

🏠 Rotas Principais

Dashboard

Método	Rota	Controller	Descrição
GET	/	IndexController.showIndex	Dashboard principal
GET	/callback	IndexController.showIndex	Callback OAuth

🔄 Ciclos (Cycles)

Listar e Gerenciar

Método	Rota	Controller	Descrição
GET	/ciclo-index	CicloIndexController.showIndex	Lista todos os ciclos
GET	/ciclo	CicloController.showIndex	Formulário novo ciclo
POST	/ciclo	CicloController.save	Salvar novo ciclo
GET	/ciclo/:id	CicloController.showIndex	Editar ciclo
POST	/ciclo/:id	CicloController.save	Atualizar ciclo
POST	/ciclo/delete/:id	CicloController.delete	Deletar ciclo

Estrutura de Dados - Ciclo

{
  nome: "Ciclo Primavera 2024",
  dataOfertaInicio: "2024-09-01",
  dataOfertaFim: "2024-09-15",
  dataPedidoInicio: "2024-09-16",
  dataPedidoFim: "2024-09-25",
  dataRetiradaInicio: "2024-10-01",
  dataRetiradaFim: "2024-10-05",
  ativo: true,
  // Relacionamentos
  cicloEntregas: [...],  // Datas de entrega
  cicloCestas: [...],    // Cestas do ciclo
  cicloProdutos: [...]   // Produtos extras
}

🧺 Cestas (Baskets)

Método	Rota	Controller	Descrição
GET	/cesta-index	CestaController.showIndex	Lista cestas
GET	/cesta	CestaController.showIndex	Formulário nova cesta
POST	/cesta	CestaController.save	Salvar nova cesta
GET	/cesta/:id	CestaController.showIndex	Editar cesta
POST	/cesta/:id	CestaController.save	Atualizar cesta
POST	/cesta/delete/:id	CestaController.delete	Deletar cesta

Estrutura de Dados - Cesta

{
  nome: "Cesta Básica de Hortaliças",
  descricao: "Cesta variada com hortaliças da estação",
  valorReferencia: 45.00,
  pesoAproximado: 5000, // gramas
  ativo: true
}

🥬 Produtos (Products)

Método	Rota	Controller	Descrição
GET	/produto-index	ProdutoController.showIndex	Lista produtos
GET	/produto	ProdutoController.showIndex	Formulário novo produto
POST	/produto	ProdutoController.save	Salvar novo produto
GET	/produto/:id	ProdutoController.showIndex	Editar produto
POST	/produto/:id	ProdutoController.save	Atualizar produto
POST	/produto/delete/:id	ProdutoController.delete	Deletar produto

Estrutura de Dados - Produto

{
  nome: "Alface Crespa",
  unidade: "maço", // kg, unidade, litro, dúzia
  pesoGramas: 200,
  valorReferencia: 3.50,
  descritivo: "Alface orgânica",
  categoriaid: 2,
  ativo: true
}

📦 Categorias

Método	Rota	Controller	Descrição
GET	/categoria-index	CategoriaController.showIndex	Lista categorias
GET	/categoria	CategoriaController.showIndex	Formulário nova categoria
POST	/categoria	CategoriaController.save	Salvar categoria
GET	/categoria/:id	CategoriaController.showIndex	Editar categoria
POST	/categoria/:id	CategoriaController.save	Atualizar categoria
POST	/categoria/delete/:id	CategoriaController.delete	Deletar categoria

📍 Pontos de Entrega (Delivery Points)

Método	Rota	Controller	Descrição
GET	/pontoentrega-index	PontoEntregaController.showIndex	Lista pontos
GET	/pontoentrega	PontoEntregaController.showIndex	Formulário novo ponto
POST	/pontoentrega	PontoEntregaController.save	Salvar ponto
GET	/pontoentrega/:id	PontoEntregaController.showIndex	Editar ponto
POST	/pontoentrega/:id	PontoEntregaController.save	Atualizar ponto
POST	/pontoentrega/delete/:id	PontoEntregaController.delete	Deletar ponto

Estrutura de Dados - Ponto de Entrega

{
  nome: "Centro Comunitário da Vila",
  endereco: "Rua das Flores, 123",
  cidade: "São Paulo",
  referencia: "Próximo ao mercado municipal",
  responsavel: "Maria Silva",
  telefone: "(11) 98765-4321",
  ativo: true
}

👥 Usuários (Users)

Método	Rota	Controller	Descrição
GET	/usuario-index	UsuarioController.showIndex	Lista usuários
GET	/usuario	UsuarioController.showIndex	Formulário novo usuário
POST	/usuario	UsuarioController.save	Salvar usuário
GET	/usuario/:id	UsuarioController.showIndex	Editar usuário
POST	/usuario/:id	UsuarioController.save	Atualizar usuário
POST	/usuario/delete/:id	UsuarioController.delete	Deletar usuário
GET	/usuarionovo	UsuarioController.novo	Auto-cadastro (primeiro login)
POST	/usuarionovo	UsuarioController.saveNovo	Salvar auto-cadastro
POST	/usuarionovo/:id	UsuarioController.saveNovo	Atualizar auto-cadastro

Estrutura de Dados - Usuário

{
  nome: "João Silva",
  email: "joao@exemplo.com",
  perfil: ['fornecedor', 'consumidor'], // Array com perfis
  nomeoficial: "João Silva - Sítio Boa Vista",
  celular: "(11) 91234-5678",
  descritivo: "Produtor de hortaliças orgânicas",
  cientepolitica: true,
  ativo: true
}

Perfis Disponíveis

perfil: DataTypes.ARRAY(DataTypes.ENUM(
  'info',        // Info-only
  'master',      // Super admin
  'admin',       // Administrator
  'fornecedor',  // Supplier
  'consumidor'   // Consumer
))

📊 Ofertas (Supplier Offers)

Método	Rota	Controller	Descrição
GET	/oferta-index	OfertaController.showIndex	Lista ofertas
GET	/oferta/:id	OfertaController.showIndex	Criar/editar oferta (id = cicloId)
POST	/oferta	OfertaController.save	Salvar parcial
POST	/ofertasave	OfertaController.save	Salvar final
POST	/ofertaapagarproduto	OfertaController.apagarProduto	Remover produto

Estrutura de Dados - Oferta

{
  oferta: {
    cicloid: 42,
    usuarioid: 5, // Fornecedor
    finalizada: true
  },
  produtos: [
    {
      produtoid: 15,
      quantidade: 50,
      valor: 3.50
    }
  ]
}

🎨 Composição (Basket Composition)

Método	Rota	Controller	Descrição
GET	/composicao/:id	ComposicaoController.showIndex	Ver/editar composição (id = cicloCestaId)
POST	/composicao/:id	ComposicaoController.save	Atualizar composição
POST	/composicaosave	ComposicaoController.save	Salvar composição

Estrutura de Dados - Composição

{
  cicloCestaId: 123,
  quantidadeCestas: 50,
  produtos: [
    {
      ofertaProdutoId: 456,
      quantidadePorCesta: 1.0, // 1 maço por cesta
      unidade: "maço"
    },
    {
      ofertaProdutoId: 457,
      quantidadePorCesta: 0.3, // 300g por cesta
      unidade: "kg"
    }
  ]
}

🛒 Pedidos de Consumidores (Consumer Orders)

Método	Rota	Controller	Descrição
GET	/pedidoconsumidores/:id	PedidoConsumidoresController.showIndex	Criar/editar pedido (id = cicloId)
POST	/pedidoconsumidores	PedidoConsumidoresController.save	Salvar pedido
GET	/pedidoconsumidoresconfirmacao/:id	PedidoConsumidoresController.confirmacao	Página confirmação
POST	/pedidoconsumidoresconfirmacao	PedidoConsumidoresController.finalizar	Finalizar pedido
GET	/pedidosconsumidorestodos/:id	PedidoConsumidoresController.todos	Ver todos os pedidos (id = cicloId)

Estrutura de Dados - Pedido

{
  pedido: {
    cicloid: 42,
    usuarioid: 78, // Consumidor
    pontoEntregaId: 3,
    finalizado: true,
    dataConfirmacao: "2024-09-20T10:30:00"
  },
  produtos: [
    {
      cicloCestaId: 1,
      quantidade: 2, // 2 cestas
      valor: 45.00
    }
  ]
}

📄 Relatórios (Reports)

Pedidos de Fornecedores

Método	Rota	Controller	Descrição
GET	/pedidosfornecedoressobra/:id	RelatorioController.sobra	Sobra de ofertas (id = cicloId)
GET	/pedidosfornecedorestodos/:id	RelatorioController.todos	Todos os pedidos (id = cicloId)
GET	/pedidosfornecedoresciclos	RelatorioController.ciclos	Selecionar ciclo
POST	/pedidosfornecedoresciclos	RelatorioController.ciclos	Exibir pedidos do ciclo

Pedidos de Consumidores

Método	Rota	Controller	Descrição
GET	/pedidosconsumidoresciclos	RelatorioController.consumidores	Selecionar ciclo
POST	/pedidosconsumidoresciclos	RelatorioController.consumidores	Exibir pedidos

Relatório de Produtos

Método	Rota	Controller	Descrição
GET	/relatorioprodutosciclos	RelatorioController.produtos	Selecionar ciclo
POST	/relatorioprodutosciclos	RelatorioController.produtos	Exibir relatório

Exportações

Método	Rota	Controller	Descrição
GET	/downloadpedidosfornecedoresciclos	RelatorioController.download	Baixar CSV
GET	/entregaCicloPDF/:id	RelatoriosController.entregaPDF	PDF de entrega (id = cicloId)

💰 Movimentações (Financial Movements)

Método	Rota	Controller	Descrição
GET	/movimentacaotodos	MovimentacaoController.showIndex	Ver todas movimentações

Estrutura de Dados - Movimentação

{
  usuarioid: 5, // Fornecedor/Consumidor
  tipoMovimentacaoId: 2,
  valor: 450.00,
  data: "2024-10-05",
  descricao: "Pagamento Ciclo Primavera 2024",
  arquivo: "comprovante.pdf", // Opcional
  cicloid: 42
}

👤 Perfil (Profile)

Método	Rota	Controller	Descrição
GET	/profile	ProfileController.index	Ver perfil
POST	/profile	ProfileController.update	Atualizar perfil

🌞 Limite Solar

Método	Rota	Controller	Descrição
GET	/limitesolar	LimiteSolarController.showIndex	Página limite solar

🔐 Autenticação

A autenticação é gerenciada pelo middleware express-openid-connect.

Fluxo OAuth

1. GET /
   └─ Se não autenticado → Redireciona para issuerBaseURL/authorize

2. Usuário faz login no provider OAuth

3. Callback → GET /callback
   └─ Valida token
   └─ Cria sessão (req.oidc.user)

4. Verifica se usuário existe no banco
   └─ Se não → Redireciona para /usuarionovo
   └─ Se sim → Continua para dashboard

Dados do Usuário Autenticado

req.oidc.user = {
  email: "joao@exemplo.com",
  name: "João Silva",
  picture: "https://...",
  email_verified: true,
  sub: "oauth2|..."
}

Verificar Autenticação

// Em qualquer rota
if (req.oidc.isAuthenticated()) {
  const userEmail = req.oidc.user.email;
  // Buscar usuário no banco pelo email
}

📊 Exemplos de Uso

Criar um Ciclo (cURL)

curl -X POST http://localhost:13000/ciclo \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "nome=Ciclo Primavera 2024" \
  -d "dataOfertaInicio=2024-09-01" \
  -d "dataOfertaFim=2024-09-15" \
  -d "dataPedidoInicio=2024-09-16" \
  -d "dataPedidoFim=2024-09-25" \
  -d "dataRetiradaInicio=2024-10-01" \
  -d "dataRetiradaFim=2024-10-05"

Criar uma Oferta (JavaScript)

// Frontend - Submeter formulário de oferta
const ofertaData = {
  cicloid: 42,
  produtos: [
    { produtoid: 15, quantidade: 50, valor: 3.50 },
    { produtoid: 23, quantidade: 30, valor: 8.00 }
  ]
};

fetch('/ofertasave', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(ofertaData)
})
.then(response => response.json())
.then(data => console.log('Oferta salva:', data));

Fazer um Pedido (JavaScript)

// Frontend - Submeter pedido de consumidor
const pedidoData = {
  cicloid: 42,
  pontoEntregaId: 3,
  produtos: [
    { cicloCestaId: 1, quantidade: 2 }, // 2 cestas básicas
    { cicloCestaId: 2, quantidade: 1 }  // 1 cesta premium
  ]
};

fetch('/pedidoconsumidores', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(pedidoData)
})
.then(response => response.json())
.then(data => {
  window.location.href = `/pedidoconsumidoresconfirmacao/${data.pedidoId}`;
});

🗃️ Banco de Dados

Configuração

// config/config.js
{
  development: {
    dialect: "postgres",
    host: "db.dev",
    database: "divinoalimento",
    username: process.env.DB_USER,
    password: process.env.DB_PASS
  },
  test: {
    dialect: "sqlite",
    storage: ":memory:"
  },
  production: {
    use_env_variable: "DATABASE_URL",
    dialect: "postgres",
    dialectOptions: { ssl: { require: true } }
  }
}

Principais Tabelas

Tabela	Descrição
usuario	Usuários do sistema
ciclo	Ciclos de entrega
cicloentregas	Datas de entrega por ciclo
ciclocestas	Cestas associadas a ciclos
cesta	Tipos de cestas
produto	Catálogo de produtos
categoriaprodutos	Categorias
pontoentrega	Pontos de entrega
oferta	Ofertas de fornecedores
ofertaprodutos	Produtos por oferta
composicoes	Composições de cestas
composicaoofertaprodutos	Produtos por composição
pedidoconsumidores	Pedidos de consumidores
pedidoconsumidoresprodutos	Produtos por pedido
movimentacao	Movimentações financeiras

🔧 Variáveis de Ambiente

# .env

# Aplicação
APP_PORT=13000
BASE_URL_APP=http://localhost:${APP_PORT}
NOT_USE_SSL=true

# Autenticação OAuth
BASE_URL_AUTH=localhost
AUTH_PORT=18080
issuerBaseURL=http://${BASE_URL_AUTH}:${AUTH_PORT}
clientID=your_client_id
secret=your_secret_key

# Banco de Dados (Desenvolvimento)
DB_HOST=db.dev
DB_NAME=divinoalimento
DB_USER=divino
DB_PASS=senha_segura

# Banco de Dados (Produção)
DATABASE_URL=postgresql://user:pass@host:5432/dbname

📝 Notas Importantes

Validações

• Datas: Devem estar em formato ISO YYYY-MM-DD
• Valores: Decimais com ponto (ex: 45.00)
• Perfis: Array de strings (ex: ['fornecedor', 'consumidor'])

Tratamento de Erros

A maioria dos endpoints retorna:

// Sucesso
{
  success: true,
  data: {...},
  message: "Operação realizada com sucesso"
}

// Erro
{
  success: false,
  error: "Mensagem do erro",
  details: {...} // Opcional
}

Headers Recomendados

Content-Type: application/json
Accept: application/json
Cookie: appSession=... (gerenciado automaticamente pelo OAuth)

🔗 Referências de Código

Componente	Arquivo
Definição de Rotas	app/src/routes.js:1
Controllers	app/src/controllers/
Models (Business Logic)	app/src/model/
Models (ORM)	app/models/
Database Queries	app/src/db/
Server	app/src/server.js:1

🔗 Próximos Passos

• Arquitetura - Entenda a estrutura do sistema
• Modelos de Dados - Estrutura detalhada do banco
• Guia do Desenvolvedor - Como contribuir

---

Dúvidas sobre a API? Consulte o código fonte ou abra uma issue no GitHub.