Referência Histórica

Migração de Nomenclatura: Português → Inglês

Status: ✅ CONCLUÍDA Data Início: 2025-12-18 Data Conclusão: 2025-12-18 Tempo Total: ~1h30min Impacto: Alto - API + Frontend Producer migrados com sucesso

Migração de Nomenclatura: Português → Inglês

Status: ✅ CONCLUÍDA Data Início: 2025-12-18 Data Conclusão: 2025-12-18 Tempo Total: ~1h30min Impacto: Alto - API + Frontend Producer migrados com sucesso


🎯 Objetivo

Padronizar TODA a nomenclatura do projeto para inglês, eliminando inconsistências entre:

  • Banco de dados (já em inglês ✅)
  • API Resources (mistura PT/EN ❌)
  • Frontend Types (mistura PT/EN ❌)
  • Nomes de pastas (português ❌)

📊 Situação Atual

Banco de Dados ✅

-- CORRETO: Tudo em inglês
orders: number, description, deadline_date, supply_radius
order_items: quantity, measurement_unit_id
customers: name, email, phone

API Resources ❌

// OrderResource.php - INCONSISTENTE
[
    'numero' => $this->number,              // PT ← EN
    'descricao' => $this->description,       // PT ← EN
    'data_limite_cotacao' => $this->deadline_date, // PT ← EN
    'raio_fornecimento' => $this->supply_radius,   // PT ← EN
    'bidding_type' => $this->bidding_type,   // EN ← EN
    'delivery_deadline' => $this->delivery_deadline, // EN ← EN
]

Frontend Types ❌

// order.ts - INCONSISTENTE
export interface Order {
  numero: string              // PT
  descricao: string           // PT
  data_limite_cotacao: string // PT
  raio_fornecimento: number   // PT
  bidding_type: string        // EN
  delivery_deadline: number   // EN
  can_edit: boolean           // EN
  created_at: string          // EN
}

Estrutura de Pastas ❌

agrsis-v1/
├── api/                    ✅ EN
├── frontend-produtor/      ❌ PT
├── frontend-fornecedor/    ❌ PT

🗺️ Mapeamento Completo PT → EN

1. Orders (Licitações)

Português (Atual)Inglês (Novo)Contexto
numeronumberNúmero da licitação (LC-001)
descricaodescriptionDescrição da licitação
data_limite_cotacaodeadline_dateData limite para propostas
raio_fornecimentosupply_radiusRaio de fornecimento (km)
tipo_licitacaobidding_typeTipo: aberta/fechada
modo_prazodeadline_modeModo: geral/específico
prazo_entregadelivery_deadlinePrazo de entrega (dias)
condicoes_pagamentopayment_termsCondições de pagamento
tipo_fretefreight_typeTipo: CIF/FOB

2. Order Items (Itens da Licitação)

Português (Atual)Inglês (Novo)Contexto
quantidadequantityQuantidade do produto
quantidade_produtoproduct_quantityQuantidade (campo DB)
aceita_similaraccepts_similarAceita similar?
programacao_entregadelivery_scheduleProgramação de entrega

3. Products (Produtos)

Português (Atual)Inglês (Novo)Contexto
nome_comercialcommercial_nameNome comercial
descricaodescriptionDescrição do produto
principio_ativoactive_ingredientPrincípio ativo
marcabrandMarca

4. Customers (Produtores)

Português (Atual)Inglês (Novo)Contexto
nomenameNome do produtor
tipo_pessoaperson_typePF ou PJ
cpf_cnpjtax_idCPF ou CNPJ
telefonephoneTelefone
area_plantadaplanted_areaÁrea plantada (hectares)

5. Addresses (Endereços)

Português (Atual)Inglês (Novo)Contexto
logradourostreetRua/Avenida
numeronumberNúmero
complementocomplementComplemento
bairroneighborhoodBairro
cidadecityCidade
ufstateEstado (UF)
cepzip_codeCEP

6. Measurement Units (Unidades)

Português (Atual)Inglês (Novo)Contexto
descricaodescriptionDescrição da unidade
siglaabbreviationSigla (kg, L, m³)

📝 Plano de Migração

Fase 1: API Resources (1-2 horas)

Arquivos a modificar:

  • app/Http/Resources/OrderResource.php
  • app/Http/Resources/OrderItemResource.php
  • app/Http/Resources/CustomerResource.php
  • app/Http/Resources/ProductResource.php
  • app/Http/Resources/AddressResource.php

Estratégia:

// ANTES
public function toArray(Request $request): array
{
    return [
        'numero' => $this->number,
        'descricao' => $this->description,
        'data_limite_cotacao' => $this->deadline_date,
    ];
}

// DEPOIS
public function toArray(Request $request): array
{
    return [
        'number' => $this->number,
        'description' => $this->description,
        'deadline_date' => $this->deadline_date?->format('Y-m-d H:i:s'),
        'supply_radius' => $this->supply_radius,
    ];
}

Checklist API:

  • OrderResource.php
  • OrderItemResource.php
  • CustomerResource.php
  • ProductResource.php
  • AddressResource.php
  • MeasurementUnitResource.php
  • QuotationItemResource.php

Fase 2: Frontend Producer (4-6 horas)

Arquivos a modificar:

Types:

  • types/order.ts
  • types/customer.ts
  • types/product.ts
  • types/address.ts

Componentes:

  • components/order/wizard/Step1BasicInfo.vue
  • components/order/wizard/Step2Products.vue
  • components/order/wizard/Step3Deadlines.vue
  • components/order/wizard/Step5Review.vue
  • components/ProductSearchSelect.vue
  • components/OrderTimeline.vue

Páginas:

  • pages/dashboard.vue
  • pages/profile.vue
  • pages/orders/index.vue
  • pages/orders/create.vue

Estratégia Types:

// ANTES
export interface Order {
  numero: string
  descricao: string
  data_limite_cotacao: string
  raio_fornecimento: number
}

// DEPOIS
export interface Order {
  number: string
  description: string
  deadline_date: string
  supply_radius: number
}

Checklist Frontend Producer:

  • types/order.ts
  • types/customer.ts
  • types/product.ts
  • types/address.ts
  • Atualizar TODOS os componentes
  • Atualizar TODAS as páginas
  • Testar wizard completo
  • Testar dashboard
  • Testar perfil

Fase 3: Frontend Supplier (4-6 horas)

Mesma estrutura do Producer:

  • types/
  • components/
  • pages/

Fase 4: Renomear Pastas (5 minutos)

Opção A: Monorepo Style

cd /Users/gustavocarneiro/EMPRESA/web/agrsis/agrsis-v1
mkdir apps
mv api apps/api
mv frontend-produtor apps/producer
mv frontend-fornecedor apps/supplier

Opção B: Web Style

cd /Users/gustavocarneiro/EMPRESA/web/agrsis/agrsis-v1
mv frontend-produtor producer-web
mv frontend-fornecedor supplier-web

Atualizar:

  • docker-compose.yml
  • Makefile
  • README.md
  • .github/ workflows (se houver)
  • package.json workspaces

🎯 Cronograma Proposto

Dia 1 (18/12) - Frontend Producer

  • 09:00-11:00 - API Resources (2h)
  • 11:00-13:00 - Frontend Types (2h)
  • 14:00-18:00 - Frontend Components/Pages (4h)
  • 18:00-19:00 - Testes completos (1h)

Dia 2-5 (19-22/12) - Frontend Supplier

  • Dia 2: Types + Componentes base
  • Dia 3: Páginas principais
  • Dia 4: Testes e ajustes
  • Dia 5: Buffer/contingência

🔍 Testes de Validação

API

# Testar endpoints
php artisan test --filter=OrderWizardTest
php artisan test --filter=OrderResourceTest

# Verificar JSON retornado
curl -X GET http://localhost:8000/api/v1/orders/1 \
  -H "Authorization: Bearer TOKEN"

Frontend

// Verificar tipos
npm run typecheck

// Testes
npm run test

// Build
npm run build

⚠️ Riscos e Mitigações

Risco 1: Breaking Changes no Frontend

Mitigação: Migrar API e Frontend simultaneamente

Risco 2: Cache de API

Mitigação: Limpar cache após deploy

php artisan config:clear
php artisan cache:clear

Risco 3: Tipos TypeScript incorretos

Mitigação: Executar npm run typecheck frequentemente


📋 Checklist Final

API

  • Todos Resources atualizados
  • Testes passando (18/18)
  • Sem campos PT no JSON

Frontend Producer

  • Todos types atualizados
  • Todos componentes atualizados
  • Todas páginas atualizadas
  • Build sem erros
  • Typecheck sem erros

Frontend Supplier

  • Todos types atualizados
  • Todos componentes atualizados
  • Todas páginas atualizadas
  • Build sem erros
  • Typecheck sem erros

Infraestrutura

  • Pastas renomeadas
  • docker-compose.yml atualizado
  • Makefile atualizado
  • README.md atualizado

🚀 Comandos de Migração Rápida

1. Buscar e Substituir (API)

cd api

# OrderResource
sed -i '' "s/'numero'/'number'/g" app/Http/Resources/OrderResource.php
sed -i '' "s/'descricao'/'description'/g" app/Http/Resources/OrderResource.php
sed -i '' "s/'data_limite_cotacao'/'deadline_date'/g" app/Http/Resources/OrderResource.php
sed -i '' "s/'raio_fornecimento'/'supply_radius'/g" app/Http/Resources/OrderResource.php

2. Buscar e Substituir (Frontend)

cd producer-web

# Types
sed -i '' 's/numero:/number:/g' types/order.ts
sed -i '' 's/descricao:/description:/g' types/order.ts
sed -i '' 's/data_limite_cotacao:/deadline_date:/g' types/order.ts
sed -i '' 's/raio_fornecimento:/supply_radius:/g' types/order.ts

🏗️ ESTRUTURA FINAL DO MONOREPO

Estrutura Anterior (ANTES):

agrsis-v1/
├── api/                    # Backend Laravel 11
├── frontend-produtor/      # Frontend Nuxt 3 - Produtor
├── frontend-fornecedor/    # Frontend Nuxt 3 - Fornecedor
├── shared/                 # Componentes compartilhados
├── docker-compose.yml
└── Makefile

Estrutura Atual (DEPOIS):

agrsis-v1/
├── apps/                   # 🆕 Pasta monorepo
│   ├── api/               # Backend Laravel 11 (renomeado)
│   │   ├── app/
│   │   │   ├── Http/
│   │   │   │   └── Resources/
│   │   │   │       ├── OrderResource.php          ✅ 100% inglês
│   │   │   │       ├── OrderItemResource.php      ✅ 100% inglês
│   │   │   │       ├── CustomerResource.php       ✅ 100% inglês
│   │   │   │       ├── ProductResource.php        ✅ 100% inglês
│   │   │   │       └── CustomerAddressResource.php ✅ 100% inglês
│   │   │   └── Enums/
│   │   │       └── OrderStatus.php                ✅ Lógica corrigida
│   │   ├── tests/
│   │   │   └── Feature/Order/
│   │   │       └── OrderWizardTest.php            ✅ 18/18 testes
│   │   └── database/migrations/                   ✅ Inglês desde início
│   │
│   ├── producer/          # Frontend Producer (era frontend-produtor)
│   │   ├── types/
│   │   │   └── order.ts                           ✅ 100% inglês
│   │   ├── components/
│   │   │   └── order/wizard/
│   │   │       ├── Step1BasicInfo.vue             ✅ Migrado
│   │   │       ├── Step2Products.vue              ✅ Migrado
│   │   │       ├── Step3Deadlines.vue             ✅ Migrado
│   │   │       ├── Step4Location.vue              ✅ Migrado
│   │   │       └── Step5Review.vue                ✅ Migrado
│   │   └── pages/
│   │       ├── dashboard.vue                      ✅ Migrado
│   │       ├── profile.vue                        ✅ Migrado
│   │       └── orders/
│   │           ├── index.vue                      ✅ Migrado
│   │           ├── new.vue                        ✅ Migrado
│   │           └── [id].vue                       ✅ Migrado
│   │
│   └── supplier/          # Frontend Supplier (era frontend-fornecedor)
│       └── ...                                    ⏳ Aguardando migração
│
├── shared/                # Componentes compartilhados
├── docs/                  # 📚 Documentação (não commitada)
│   └── MIGRATION-PT-TO-EN.md
├── docker-compose.yml     ✅ Atualizado para apps/
└── Makefile              ✅ Atualizado para apps/

Mudanças nos Arquivos de Configuração:

docker-compose.yml

# ANTES
services:
  api:
    build:
      context: ./api
    volumes:
      - ./api:/var/www/html

  frontend-produtor:
    build:
      context: ./frontend-produtor
    volumes:
      - ./frontend-produtor:/app

# DEPOIS
services:
  api:
    build:
      context: ./apps/api
    volumes:
      - ./apps/api:/var/www/html

  frontend-producer:
    build:
      context: ./apps/producer
    volumes:
      - ./apps/producer:/app

Makefile

# ANTES
dev-api:
    cd api && php artisan serve

dev-produtor:
    cd frontend-produtor && npm run dev

# DEPOIS
dev-api:
    cd apps/api && php artisan serve

dev-producer:
    cd apps/producer && npm run dev

📊 RESULTADO DA MIGRAÇÃO

✅ Concluído:

AGR-181 - OrderResource PT→EN

  • 4 campos migrados
  • 18/18 testes passando
  • Commit: b6d4dfe

AGR-182 - OrderItemResource PT→EN

  • 2 campos migrados
  • 18/18 testes passando
  • Commit: 7849095

AGR-183 - Customer, Product, Address Resources PT→EN

  • 20 campos migrados em 4 Resources
  • 18/18 testes passando
  • Commit: c051bbd

AGR-184 - Types Frontend PT→EN

  • 5 interfaces atualizadas
  • 27 campos migrados
  • Commit: 3ad135a

AGR-185 - Componentes Wizard PT→EN

  • 6 componentes atualizados
  • Commit: 0c3fddf

AGR-186 - Páginas PT→EN

  • 6 páginas atualizadas
  • Commit: 11d3af7

AGR-187 - Estrutura Monorepo

  • 412 arquivos reorganizados
  • docker-compose.yml e Makefile atualizados
  • Commit: 435c818

AGR-188 - Testes API

  • OrderWizardTest: 18/18 ✅

AGR-189 - Validação Frontend

  • Build validado ✅

📈 Estatísticas:

  • Total de Commits: 7
  • Arquivos Alterados: ~480
  • Campos Migrados: 50+
  • Testes Passando: 18/18 (100%)
  • Tempo de Execução: ~1h30min
  • Tasks Linear Concluídas: 9/9

🎯 Status Final:

ComponenteStatusNomenclatura
Database✅ OK100% Inglês
API Resources✅ OK100% Inglês
API Tests✅ OK18/18 Passando
Frontend Types✅ OK100% Inglês
Frontend Components✅ OK100% Inglês
Frontend Pages✅ OK100% Inglês
Estrutura Pastas✅ OKMonorepo apps/
Docker Config✅ OKPaths Atualizados
Makefile✅ OKComandos Atualizados

📚 Referências


✅ MIGRAÇÃO COMPLETA

Projeto AgrSis v1 - Frontend Producer

  • ✅ Nomenclatura 100% padronizada em inglês
  • ✅ Estrutura monorepo moderna e escalável
  • ✅ Todos os testes passando
  • ✅ Pronto para desenvolvimento contínuo

Próximo passo: Migrar Frontend Supplier (AGR-190 a AGR-198)

Copyright © 2026