AgrSis Docs
Operação

Sistema de Controle de Versão Automático

Sistema de Controle de Versão Automático

Visão Geral

Sistema automático de controle de versão baseado em Git que gera informações de versão durante o build e as exibe nos frontends.

Características

  • ✅ Automático: Gera versão automaticamente durante o build
  • ✅ Baseado em Git: Usa tags, commits e branches do git
  • ✅ Sem configuração manual: Não precisa alterar arquivos para atualizar versão
  • ✅ Monorepo-friendly: Funciona em monorepos com múltiplos frontends
  • ✅ Diferenciação Local/Produção: Identifica ambiente automaticamente

Como Funciona

1. Durante o Build

O script scripts/generate-version.js é executado automaticamente antes do build (via prebuild no package.json) e:

  1. Coleta informações do git:
    • Versão (última tag)
    • Hash do commit
    • Branch atual
    • Data e mensagem do último commit
  2. Gera arquivo public/version.json com todas as informações
  3. O arquivo é copiado para a pasta de build final

2. No Runtime

O composable useVersion() carrega o arquivo version.json e disponibiliza as informações para os componentes.

Componentes Disponíveis

1. useVersion() - Composable

const {
  version,          // v1.2.3
  displayVersion,   // v1.2.3 (a1b2c3d)
  fullInfo,         // v1.2.3 @ main (a1b2c3d)
  buildDate,        // 13/01/2025 às 16:30
  isProduction,     // true/false
  isDevelopment,    // true/false
  versionInfo,      // Objeto completo com todas as informações
} = useVersion()

2. <VersionDisplay> - Componente Visual

Três variantes disponíveis:

Minimal (padrão)

<VersionDisplay />
<!-- Exibe: v1.2.3 -->

Compact

<VersionDisplay variant="compact" />
<!-- Exibe: v1.2.3 (a1b2c3d) + branch -->

Detailed

<VersionDisplay variant="detailed" />
<!-- Exibe: Todas as informações em grid -->

3. <AboutModal> - Modal Completo

<template>
  <button @click="showAbout = true">Sobre</button>
  <AboutModal v-model="showAbout" />
</template>

<script setup>
const showAbout = ref(false)
</script>

Uso Prático

Na Página de Login

Adicione a versão no rodapé da página de login:

<template>
  <div class="login-page">
    <!-- ... form de login ... -->

    <footer class="login-footer">
      <VersionDisplay variant="minimal" />
    </footer>
  </div>
</template>

<style scoped>
.login-footer {
  @apply absolute bottom-4 left-1/2 -translate-x-1/2;
  @apply text-center;
}
</style>

No Menu do Usuário

Adicione um item "Sobre" no menu dropdown do usuário:

<template>
  <div class="user-menu">
    <!-- ... outros itens do menu ... -->

    <button @click="showAbout = true" class="menu-item">
      <svg class="menu-icon"><!-- ícone info --></svg>
      Sobre o Sistema
    </button>
  </div>

  <AboutModal v-model="showAbout" />
</template>

<script setup>
const showAbout = ref(false)
</script>

Exemplo Completo - Layout com Menu

<!-- apps/producer/layouts/default.vue -->
<template>
  <div class="layout">
    <header class="header">
      <nav class="nav">
        <!-- ... -->
      </nav>

      <!-- Menu do usuário -->
      <div class="user-menu-container">
        <button @click="toggleUserMenu" class="user-button">
          <!-- Avatar/Nome -->
        </button>

        <Transition name="dropdown">
          <div v-if="userMenuOpen" class="user-dropdown">
            <a href="/profile" class="dropdown-item">
              Meu Perfil
            </a>
            <a href="/settings" class="dropdown-item">
              Configurações
            </a>

            <hr class="dropdown-divider" />

            <button @click="openAboutModal" class="dropdown-item">
              <svg class="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
                <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" />
              </svg>
              Sobre o Sistema
            </button>

            <hr class="dropdown-divider" />

            <button @click="logout" class="dropdown-item text-red-600">
              Sair
            </button>
          </div>
        </Transition>
      </div>
    </header>

    <main class="main">
      <slot />
    </main>

    <footer class="footer">
      <VersionDisplay variant="minimal" />
    </footer>
  </div>

  <!-- Modal Sobre -->
  <AboutModal v-model="showAbout" />
</template>

<script setup>
const userMenuOpen = ref(false)
const showAbout = ref(false)

function toggleUserMenu() {
  userMenuOpen.value = !userMenuOpen.value
}

function openAboutModal() {
  showAbout.value = true
  userMenuOpen.value = false
}

function logout() {
  // lógica de logout
}
</script>

Gerando Novas Versões

1. Criar uma Tag de Versão

# Criar tag localmente
git tag -a v1.2.3 -m "Release v1.2.3: Descrição das mudanças"

# Enviar tag para o repositório
git push origin v1.2.3

2. Fazer o Build

# Local
cd apps/producer
npm run build

# Produção (via deploy)
bash scripts/deploy/deploy.sh

O script detectará automaticamente a nova tag e a incluirá nas informações de versão.

Estrutura de Arquivos

agrsis-v1/
├── scripts/
│   └── generate-version.js          # Script de geração de versão
│
├── apps/
│   ├── shared/
│   │   ├── composables/
│   │   │   └── useVersion.ts        # Composable
│   │   └── components/
│   │       ├── VersionDisplay.vue   # Componente visual
│   │       └── AboutModal.vue       # Modal completo
│   │
│   ├── producer/
│   │   ├── package.json             # prebuild script configurado
│   │   └── public/
│   │       └── version.json         # Gerado automaticamente no build
│   │
│   └── supplier/
│       ├── package.json             # prebuild script configurado
│       └── public/
│           └── version.json         # Gerado automaticamente no build
│
└── docs/
    └── VERSION_SYSTEM.md            # Esta documentação

Formato do version.json

{
  "version": "v1.2.3",
  "commitHash": "a1b2c3d",
  "branch": "main",
  "lastCommitDate": "2025-01-13T19:30:00-03:00",
  "lastCommitMessage": "feat: implementar sistema de versão automático",
  "buildDate": "2025-01-13T19:35:00.000Z",
  "environment": "production",
  "displayVersion": "v1.2.3 (a1b2c3d)",
  "fullInfo": "v1.2.3 @ main (a1b2c3d)"
}

Versionamento Semântico (SemVer)

Recomendamos seguir o padrão Semantic Versioning:

  • MAJOR (v1.0.0): Mudanças incompatíveis na API
  • MINOR (v1.1.0): Novas funcionalidades (compatível)
  • PATCH (v1.0.1): Correções de bugs

Exemplos:

# Correção de bug
git tag v1.0.1 -m "fix: corrigir validação de CPF"

# Nova funcionalidade
git tag v1.1.0 -m "feat: adicionar filtro de data nas cotações"

# Mudança breaking
git tag v2.0.0 -m "feat!: migrar para nova API de autenticação"

Comparando Versões (Local vs Produção)

No navegador

  1. Abra o DevTools (F12)
  2. Execute no console:
fetch('/version.json').then(r => r.json()).then(console.log)

Via curl

# Produção
curl https://producer.agrsis.com/version.json

# Local
curl http://localhost:3000/version.json

Troubleshooting

Versão não aparece

  1. Verifique se o script foi executado durante o build:
    npm run build
# Deve exibir: "✅ Arquivo de versão gerado com sucesso!"
  2. Verifique se o arquivo foi gerado:
    ls -la apps/producer/public/version.json
  3. Verifique se o arquivo está acessível:
    curl http://localhost:3000/version.json

"v0.0.0" ou "unknown"

Isso significa que não há tags no repositório. Crie uma:

git tag v0.1.0 -m "Initial version"
git push origin v0.1.0

Versão antiga mesmo após deploy

  1. Limpe o cache do navegador
  2. Verifique se o deploy executou o build: 
    ssh root@dev.agrsis.com "cd /opt/agrsis && docker compose logs api | grep version"

Próximos Passos

Melhorias Futuras

  • Adicionar changelog automático
  • Integrar com sistema de notificações (avisar usuários sobre nova versão)
  • Adicionar botão "Recarregar" se versão estiver desatualizada
  • Gerar release notes automaticamente
  • Integrar com CI/CD

Integração com CI/CD

Se você usar GitHub Actions, pode adicionar:

# .github/workflows/deploy.yml
- name: Create Release
  uses: actions/create-release@v1
  with:
    tag_name: ${{ github.ref }}
    release_name: Release ${{ github.ref }}
    body: |
      Automated release

Suporte

Dúvidas ou problemas? Entre em contato com o time de desenvolvimento.

Sistema de Modo de Manutenção

Exemplos Visuais de Uso da Versão

Copyright © 2026