Pular para o conteúdo principal

Documento de Gerência de Configuração de Software

VersãoDataAutor(es)Descrição
1.018/02/2026João Pedro S. BritoDefinições iniciais sobre modelo de ramificações, estrutura de repositórios, issues, pull-requests e gerenciamento de migrações de banco de dados para o projeto STATS.
1.103/03/2026Antonio G. CastroAdição de templates de tarefas, template de pull request, específicações de metodologias ágeis.
1.217/06/2026Antonio G. CastroRemove templates desse documento, edita ferramenta de banco de dados.

Sumário​

  1. Introdução
  2. Tecnologias e Infraestrutura (Stack)
  3. Estrutura de Repositórios
  4. Modelo de Ramificação (Branching Model)
  5. Gerenciamento de Mudanças e Tarefas
  6. Gerenciamento de Pull Requests (PRs) — (seção não existe, ainda precisa ser escrita)
  7. Gerenciamento de Mensagens de Commit
  8. Gerenciamento de Banco de Dados (Migrações)

1. Introdução​

Este documento estabelece as diretrizes e padrões de Gerência de Configuração de Software (GCS) para o projeto Remo e Cruzeiro em Números.

O objetivo é garantir a rastreabilidade, padronização e qualidade do código desenvolvido, facilitando o trabalho assíncrono entre os membros da equipe e a entrega contínua do MVP.

2. Tecnologias e Infraestrutura (Stack)​

A arquitetura do projeto foi desenhada para suportar um modelo multitenant, separando responsabilidades e garantindo desempenho (detalhes no Diário de Decisão):

  • Frontend: React com Next.js
  • Backend: Node.js com NestJS
  • Banco de Dados: PostgreSQL
  • ORM: Prisma
  • Extração e Tratamento de Dados (ETL): Python (Pandas, BeautifulSoup)
  • Controle de Versão e Gestão Ágil: Git e GitHub Projects

3. Estrutura de Repositórios​

O projeto adota arquitetura multitenant e separa as responsabilidades de Frontend e Backend em repositórios distintos, todos sob a mesma organização no GitHub:

  • stats-backend: Contém a API REST em NestJS, o ORM Prisma e os scripts de ETL em Python.
  • stats-frontend-remo: Aplicação web em Next.js com a identidade visual do Clube do Remo.
  • stats-frontend-cruzeiro: Aplicação web em Next.js com a identidade visual do Cruzeiro.

3.1 Gestão de Acessos e Credenciais (RBAC)​

O projeto adota a prática de Role-Based Access Control (RBAC). Não utilizamos credenciais ou e-mails compartilhados genéricos.

  • Os repositórios pertencem a uma Organização no GitHub.
  • Os serviços de infraestrutura são acessados por convites individuais atrelados aos e-mails pessoais/institucionais de cada membro.
  • O acesso ao banco de dados para desenvolvimento é feito estritamente via compartilhamento seguro da variável DATABASE_URL no arquivo .env local.

4. Modelo de Ramificação (Branching Model)​

A equipe utiliza o GitHub Flow, um modelo simplificado, ágil e focado em entregas contínuas, ideal para equipes reduzidas.

4.1 Branches Principais​

  • main: É a ramificação de produção. O código nesta branch deve estar sempre estável, funcional e pronto para deploy automático nas plataformas de hospedagem. Nenhum commit direto é permitido na main., exceto correções no repositório de documentação.

4.2 Branches de Trabalho (Features e Fixes)​

Para qualquer nova funcionalidade ou correção, deve-se criar uma ramificação a partir da main.

  • Regra de Nomenclatura: <tipo>/<descricao-curta>
  • Tipos permitidos:
    • feat/: desenvolvimento de novas funcionalidades.
    • fix/: correções de bugs ou erros mapeados.
    • docs/: alterações exclusivas em documentação.
  • Exemplos: feat/filtro-partidas, fix/15-erro-calculo-renda.

5. Gerenciamento de Mudanças e Tarefas​

O ciclo de desenvolvimento baseia-se em Sprints adaptativas de 2 semanas, gerenciadas via GitHub Projects.

O volume de tarefas por Sprint varia conforme a Capacidade Declarada da equipe (reduzida em semanas de provas acadêmicas).

Dinâmica de Sprints e Capacidade​

Utilizamos um modelo de Scrum-ban Adaptativo com Sprints de 2 semanas.

  • Gestão de Capacidade: Em semanas de provas ou alta carga acadêmica, a equipe declara "Baixa Capacidade" durante a reunião de Planning, podendo reduzir o escopo para 1 tarefa ou declarar "Sprint de Pausa" para não comprometer a qualidade.

5.1 Critérios para Mesclagem (Merge)​

  • Revisão de Código: o PR deve ser aprovado por pelo menos 1 membro da equipe diferente do autor.
  • Rastreabilidade: o PR deve referenciar a issue correspondente usando palavras-chave (ex: Closes #12 ou Fixes #15). Isso fechará a tarefa automaticamente no Kanban.
  • Conflitos: não deve haver conflitos com a branch main. O autor é responsável por realizar o rebase ou merge da main em sua branch e resolver os conflitos localmente antes de solicitar aprovação.

7. Gerenciamento de Mensagens de Commit​

A equipe adota a convenção Conventional Commits para manter o histórico de versionamento semântico, legível e automatizável.

  • Estrutura do commit: <tipo>(<escopo opcional>): <descrição curta no imperativo>
  • Tipos permitidos:
    • feat: adição de nova funcionalidade.
    • fix: correção de bug.
    • chore: atualização de ferramentas, dependências ou configurações que não afetam o código em si (ex: .gitignore, mudanças de provedor de host).
    • refactor: refatoração de código que não adiciona recurso nem corrige bug.
    • style: formatação, ponto-e-vírgula, espaçamentos (não afeta o comportamento).
    • docs: alterações na documentação (README.md, PDFs, etc).

7.1 Exemplos​

  • feat(api): cria endpoint de busca de partidas por clube
  • fix(frontend): corrige sobreposição do header no mobile
  • chore: atualiza versão do Prisma ORM

8. Gerenciamento de Banco de Dados (Migrações)​

Devido à arquitetura da aplicação, as alterações de esquema de banco de dados (schema) devem seguir controle de versão estrito usando as ferramentas do Prisma.

  • Toda alteração no banco de dados deve ser feita primeiramente no arquivo schema.prisma.
  • O desenvolvedor deve gerar uma migração local utilizando o comando npx prisma migrate dev --name <descricao>.
  • A pasta gerada prisma/migrations/ deve obrigatoriamente ser versionada (commitada) e enviada no Pull Request, pois ela contém os scripts SQL que instruirão o banco de dados de produção (Neon) a se atualizar.