Pular para o conteúdo principal

Guia de Fork de Marca

:::info TODO Este guia será completado quando o primeiro fork real (front-web-vera-bet-br) for criado. Abaixo está o processo planejado. :::

Visão geral​

Um fork é uma cópia completa do front-web-base. O cliente tem liberdade total para personalizar: criar componentes, páginas, regras, redesenhar o tema inteiro.

O template vem com pontos de customização preparados (config files, tokens de tema), mas nada impede o cliente de modificar qualquer outro arquivo do projeto.

Única restrição: não alterar pacotes @cactus-agents/* diretamente — eles são dependências npm atualizáveis.

O que o cliente pode fazer​

  • Criar componentes próprios
  • Adicionar/remover/reescrever páginas
  • Customizar ou redesenhar o layout inteiro
  • Criar seus próprios hooks, stores, serviços
  • Adicionar bibliotecas e dependências
  • Configurar integrações próprias

Pontos rápidos de customização​

O template prepara 3 arquivos para facilitar customizações comuns:

ArquivoO que facilita
app/config/theme/colors.tsPaleta de cores (Tailwind tokens por seção)
app/config/routes.config.tsÁrvore de rotas (adicionar/remover páginas)
app/config/layout/composition.tsComponente de layout (trocar o DefaultLayout)

Esses são atalhos, não limites. O cliente pode ir além.

Processo planejado​

  1. Clonar front-web-base como novo repositório (front-web-{marca})
  2. Configurar .env / .dev.vars com as variáveis da marca
  3. Personalizar tema, rotas, layout — e qualquer outra coisa necessária
  4. Configurar .npmrc com token de acesso ao GitHub Packages
  5. pnpm install para resolver pacotes @cactus-agents/*
  6. Testar localmente com pnpm dev
  7. Configurar deploy no front-ops e GitHub:
    • Cadastrar o repo em front-ops/config/brands/<brand>/repos.yml com cf_account definido
    • Editar as org secrets no GitHub (Settings → Secrets → Actions) e adicionar o novo repo à lista de Repository access de cada secret relevante (GH_PACKAGES_TOKEN, FRONT_GH_ACTIONS_TOKEN, FRONT_{XX}_CF_*)
    • Se a brand usa um domínio novo, editar o API Token da conta CF correspondente para incluir a nova zona em Zone Resources (CF Dashboard → API Tokens → Edit)

Atualização de lógica de negócio​

pnpm update @cactus-agents/auth @cactus-agents/brand  # atualiza pacotes específicos
pnpm update @cactus-agents/*                    # atualiza todos

Sem merge conflicts — os pacotes são dependências npm, não código copiado.

Atualização de template​

Para mudanças na UI/estrutura do front-web-base, um PR script pode ser usado para propagar updates. A superfície de conflito depende de quanto o fork divergiu do base.