Mapeamento de Renomeação PT → EN - FornecedorController

Data: 2025-01-11 Objetivo: Renomear métodos de português para inglês mantendo compatibilidade com frontend

📋 MÉTODOS A RENOMEAR

⚠️ PROBLEMA IDENTIFICADO: MÉTODO DUPLICADO

favoritarLicitacao() aparece 2x:

Linha 980: Aceita int $id (legado, não usa UUID)

public function favoritarLicitacao(int $id): JsonResponse

Linha 1276: Aceita string $id (novo, usa UUID)

public function favoritarLicitacao(string $id): JsonResponse

Decisão:

• ✅ MANTER: Linha 1276 (usa UUID, é o método atual)
• ❌ REMOVER: Linha 980 (legado, usa int ID)

🗺️ ROTAS NO routes/api.php

Rotas /supplier/ (ATIVAS):

Route::prefix('supplier')->group(function () {
    Route::get('/dashboard', [FornecedorController::class, 'dashboard']);
    Route::get('/orders', [FornecedorController::class, 'licitacoes']);                    // → getOrders
    Route::get('/orders/favorites', [FornecedorController::class, 'licitacoesFavoritas']); // → getFavoriteOrders
    Route::get('/orders/{id}', [FornecedorController::class, 'licitacaoDetalhes']);        // → getOrderDetails
    Route::post('/orders/{id}/favorite', [FornecedorController::class, 'favoritarLicitacao']); // → toggleOrderFavorite
    Route::post('/orders/{id}/decline', [FornecedorController::class, 'declinarLicitacao']);   // → declineOrder

    Route::get('/proposals', [FornecedorController::class, 'propostas']);                 // → getProposals
    Route::post('/proposals', [FornecedorController::class, 'criarProposta']);            // → createProposal
    Route::get('/proposals/{id}', [FornecedorController::class, 'detalhesProposta']);     // → getProposalDetails
    Route::get('/proposals/{id}/pdf', [FornecedorController::class, 'gerarPdfProposta']); // → generateProposalPdf
    Route::put('/proposals/{id}', [FornecedorController::class, 'editarProposta']);       // → updateProposal
    Route::delete('/proposals/{id}', [FornecedorController::class, 'cancelarProposta']);  // → deleteProposal
});

Rotas /fornecedor/ (LEGADAS - MANTER POR COMPATIBILIDADE):

Route::prefix('fornecedor')->group(function () {
    Route::get('/dashboard', [FornecedorController::class, 'dashboard']);
    Route::get('/licitacoes', [FornecedorController::class, 'licitacoes']);                      // → getOrders
    Route::get('/licitacoes/favoritas', [FornecedorController::class, 'licitacoesFavoritas']);   // → getFavoriteOrders
    Route::get('/licitacoes/{id}', [FornecedorController::class, 'licitacaoDetalhes']);          // → getOrderDetails
    Route::post('/licitacoes/{id}/favoritar', [FornecedorController::class, 'favoritarLicitacao']); // → toggleOrderFavorite

    Route::get('/propostas', [FornecedorController::class, 'propostas']);                // → getProposals
    Route::post('/propostas', [FornecedorController::class, 'criarProposta']);           // → createProposal
    Route::get('/propostas/{id}', [FornecedorController::class, 'detalhesProposta']);    // → getProposalDetails
    Route::get('/propostas/{id}/pdf', [FornecedorController::class, 'gerarPdfProposta']); // → generateProposalPdf
    Route::put('/propostas/{id}', [FornecedorController::class, 'editarProposta']);      // → updateProposal
    Route::delete('/propostas/{id}', [FornecedorController::class, 'cancelarProposta']); // → deleteProposal
});

🎯 FRONTEND - USO DAS ROTAS

Arquivo: useDashboardMetrics.ts:66

const response = await $api('/api/v1/fornecedor/dashboard', {

⚠️ USAR ROTA LEGADA: /fornecedor/dashboard✅ Ação: Trocar para /supplier/dashboard (padrão novo)

Arquivo: useFornecedorApi.ts

• Linha 23: /api/v1/supplier/dashboard ✅
• Linha 45: /api/v1/supplier/orders ✅
• Linha 86: /api/v1/supplier/orders/{id} ✅
• Linha 110: /api/v1/supplier/proposals ✅
• Linha 143: POST /api/v1/supplier/proposals ✅
• Linha 177: PUT /api/v1/supplier/proposals/{id} ✅
• Linha 200: DELETE /api/v1/supplier/proposals/{id} ✅

Arquivo: pages/orders/index.vue:187

const response = await $api(`/api/v1/supplier/orders/${uuid}/favorite`, {

✅ Já usando rota nova

Arquivo: pages/dashboard.vue:239

const response = await $api(`/api/v1/supplier/orders/${uuid}/favorite`, {

✅ Já usando rota nova

📝 PLANO DE EXECUÇÃO

Passo 1: Remover Método Duplicado (Legado)

• Identificar método duplicado na linha 980
• Remover método favoritarLicitacao(int $id) linha 980

Passo 2: Renomear Métodos no Controller

• licitacoes() → getOrders()
• licitacaoDetalhes() → getOrderDetails()
• propostas() → getProposals()
• criarProposta() → createProposal()
• editarProposta() → updateProposal()
• cancelarProposta() → deleteProposal()
• detalhesProposta() → getProposalDetails()
• favoritarLicitacao(string $id) → toggleOrderFavorite()
• licitacoesFavoritas() → getFavoriteOrders()
• gerarPdfProposta() → generateProposalPdf()
• declinarLicitacao() → declineOrder()

Passo 3: Atualizar Rotas

• Atualizar routes/api.php - rotas /supplier/
• Atualizar routes/api.php - rotas /fornecedor/ (legado)

Passo 4: Atualizar Frontend

• useDashboardMetrics.ts:66 → trocar /fornecedor/ para /supplier/

Passo 5: Testes

• Testar GET /supplier/dashboard
• Testar GET /supplier/orders
• Testar GET /supplier/orders/{id}
• Testar POST /supplier/orders/{id}/favorite
• Testar POST /supplier/orders/{id}/decline
• Testar GET /supplier/proposals
• Testar POST /supplier/proposals
• Testar GET /supplier/proposals/{id}
• Testar PUT /supplier/proposals/{id}
• Testar DELETE /supplier/proposals/{id}
• Testar GET /supplier/proposals/{id}/pdf

Passo 6: Atualizar Documentação

• Atualizar comentários PHPDoc no controller
• Atualizar RESUMO-IMPLEMENTACAO-FAVORITOS.md
• Atualizar CHECKLIST-TESTES-FAVORITOS.md

🔄 NOMENCLATURA ESCOLHIDA

Convenções REST:

• GET lista: get{Resource}s() - ex: getOrders(), getProposals()
• GET item: get{Resource}Details() - ex: getOrderDetails()
• POST criar: create{Resource}() - ex: createProposal()
• PUT atualizar: update{Resource}() - ex: updateProposal()
• DELETE remover: delete{Resource}() - ex: deleteProposal()
• POST ação: {verb}{Resource}() - ex: toggleOrderFavorite(), declineOrder()

Recursos:

• Licitação: Order (mantém consistência com model Order)
• Proposta: Proposal
• Favorito: Favorite

✅ BENEFÍCIOS DA RENOMEAÇÃO

1. Código mais limpo: Nomes em inglês seguindo padrões REST
2. Consistência: Alinhado com models e banco de dados
3. Manutenibilidade: Mais fácil para desenvolvedores internacionais
4. Boas práticas: Segue convenções Laravel e PSR
5. Documentação: Auto-documentável com nomes descritivos

🚨 RISCOS E MITIGAÇÃO

Riscos:

1. ❌ Quebrar frontend se rotas não forem atualizadas
2. ❌ Quebrar integrações externas (se houver)
3. ❌ Perder referências em logs/monitoramento

Mitigação:

1. ✅ Frontend já usa rotas /supplier/ (nova)
2. ✅ Manter rotas /fornecedor/ legadas por compatibilidade
3. ✅ Testar todos os endpoints após renomeação
4. ✅ Deploy gradual: staging → produção
5. ✅ Rollback fácil com Git

Responsável: Equipe de desenvolvimento Aprovação: Pendente Status: 🟡 Planejado