Git + GitLab na prática: criar branch, enviar, abrir MR, dar merge e limpar branch

🚀 Git + GitLab na prática: branch, merge e limpeza sem dor de cabeça

Este guia é um passo a passo direto ao ponto para o fluxo mais comum no Git/GitLab:

• 🌱 Criar um novo branch
• 📤 Enviar para o GitLab e fazer merge com main
• 🧹 Voltar para o branch principal e apagar o branch local

---

✅ Pré-check (altamente recomendado)

Antes de qualquer coisa, confira em qual branch você está:

git branch

Atualize seu main local antes de criar novos branches:

git checkout main
git pull origin main

---

🌱 1) Como criar um novo branch

Opção A (recomendada)

Crie o branch sempre a partir do main atualizado:

git checkout main
git pull origin main
git checkout -b feature/nome-da-feature

📌 Exemplo real:

git checkout -b feature/projetos

Opção B (Git moderno)

git switch main
git pull origin main
git switch -c feature/projetos

---

📤 2) Já fiz commit. Como enviar para o GitLab e fazer merge?

2.1 Enviar o branch para o remoto

Primeiro push do branch:

git push -u origin feature/projetos

Pushs seguintes:

git push

2.2 Criar o Merge Request no GitLab

1. 🌐 Abra o repositório no GitLab
2. 🔀 Vá em Merge Requests → New merge request
3. Selecione:
   • Source: feature/projetos
   • Target: main
4. ✅ Crie o MR e clique em Merge quando estiver pronto

⚠️ Boa prática antes do merge

Traga o main mais recente para dentro do seu branch:

git fetch origin
git checkout feature/projetos
git merge origin/main
git add .
git commit
git push

💡 Algumas equipes preferem rebase. Se for o seu caso:

git fetch origin
git checkout feature/projetos
git rebase origin/main
git push --force-with-lease

---

🧹 3) Voltar para o main e apagar o branch local

3.1 Voltar para o branch principal

git checkout main
git pull origin main

3.2 Apagar o branch local após o merge

Forma segura (recomendada):

git branch -d feature/projetos

⚠️ Se o Git reclamar que não está mergeado:

git pull origin main
git branch -d feature/projetos

🔥 Forçar exclusão (use só se tiver certeza):

git branch -D feature/projetos

3.3 Limpar referências de branches remotos

git fetch --prune

---

📌 Checklist final (salva-vidas)

# criar branch
git checkout main
git pull origin main
git checkout -b feature/projetos

# trabalhar, commitar, enviar
git add .
git commit -m "feat: projetos"
git push -u origin feature/projetos

# (GitLab) abrir MR → merge

# voltar ao main e limpar branch
git checkout main
git pull origin main
git branch -d feature/projetos
git fetch --prune

✅ Pronto! Fluxo limpo, previsível e profissional.

PostgreSQL e IDENTITY: por que a sequência “desalinha” e como corrigir

Se você usa PostgreSQL, provavelmente já viu (ou vai ver) um erro como:

ERROR: duplicate key value violates unique constraint
DETAIL: Key (id)=(2) already exists.

Esse erro costuma aparecer quando uma coluna IDENTITY (ou SERIAL) está tentando gerar um ID que já existe na tabela. Na prática, isso significa que a sequência interna do PostgreSQL ficou desalinhada com os dados.

Neste artigo você vai entender:

• o que é a sequência interna (sequence) do IDENTITY
• por que ela pode “perder o valor correto”
• como diagnosticar o problema
• como ajustar a sequência com segurança

---

1) O que é IDENTITY no PostgreSQL?

Uma coluna definida como GENERATED ... AS IDENTITY gera valores automaticamente usando uma sequence (sequência) por trás.

Exemplo:

CREATE TABLE exemplo (
  id bigint GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
  nome text NOT NULL
);

O PostgreSQL cria uma sequence interna (com um nome próprio) e passa a usar algo como:

nextval('nome_da_sequence')

para gerar IDs automaticamente.

---

2) Por que a sequência pode “desalinhar”?

O ponto mais importante é este:

A sequence é independente da tabela. Ela não “olha” os dados para decidir o próximo número.

Ou seja: a tabela pode ter ID 1000, mas se a sequence ainda estiver em 10, o próximo insert automático pode tentar gerar 11, 12... e em algum momento pode gerar um valor que já existe, causando erro.

Motivos comuns (na prática)

• Importação/carga de dados inserindo IDs manualmente (ex.: INSERT com id=1000)
• Restore de backup onde os dados voltam, mas a sequence não é ajustada
• Scripts de migração ou manutenção que inserem IDs explicitamente
• TRUNCATE/DELETE (a tabela muda, mas a sequence mantém o valor antigo)
• Testes/seed com dados fixos e IDs definidos “na mão”

---

3) Como diagnosticar se a sequence está errada

O diagnóstico clássico compara:

• maior ID da tabela vs
• valor atual da sequence

3.1 Descobrir o nome da sequence associada ao IDENTITY

SELECT pg_get_serial_sequence('schema.tabela', 'coluna_id');

Exemplo:

SELECT pg_get_serial_sequence('public.exemplo', 'id');

O retorno será o nome da sequence (por exemplo public.exemplo_id_seq).

3.2 Ver o maior ID existente na tabela

SELECT MAX(id) FROM public.exemplo;

3.3 Ver o valor atual da sequence

SELECT last_value FROM public.exemplo_id_seq;

Se last_value for menor que o MAX(id), você tem um desalinhamento.

---

4) Como ajustar a sequência do IDENTITY (forma segura)

A correção consiste em configurar a sequence para continuar a partir do maior ID existente.

4.1 Ajuste automático usando o máximo da tabela

SELECT setval(
  pg_get_serial_sequence('schema.tabela', 'coluna_id'),
  (SELECT COALESCE(MAX(coluna_id), 1) FROM schema.tabela)
);

Exemplo completo:

SELECT setval(
  pg_get_serial_sequence('public.exemplo', 'id'),
  (SELECT COALESCE(MAX(id), 1) FROM public.exemplo)
);

Após isso, o próximo INSERT automático usará MAX(id) + 1.

---

5) Caso especial: tabela vazia

Se a tabela estiver vazia e você quiser reiniciar a contagem, use o terceiro parâmetro do setval:

SELECT setval(
  pg_get_serial_sequence('public.exemplo', 'id'),
  1,
  false
);

O false indica que o próximo valor gerado será exatamente 1.

---

6) Por que “buracos” em IDs são normais

Um detalhe que muita gente estranha:

Sequences não fazem rollback. Elas avançam mesmo se a transação falhar.

Exemplo:

BEGIN;
INSERT INTO public.exemplo (nome) VALUES ('Teste');
ROLLBACK;

Mesmo com rollback, a sequence pode ter incrementado. Isso gera “buracos” nos IDs, e isso é esperado. IDs não devem ser usados como números contábeis ou sequenciais perfeitos.

---

7) Boas práticas para evitar o problema

• Evite inserir IDs manualmente. Se precisar, ajuste a sequence depois.
• Após restore/importações, sempre valide MAX(id) vs sequence.
• Crie um checklist pós-deploy para checar sequences.
• Em migrações, prefira inserir sem ID e deixar o banco gerar.

---

Conclusão

Quando o PostgreSQL “tenta repetir um ID”, quase sempre o problema é a sequence interna do IDENTITY que ficou atrás do maior valor real da tabela.

A correção é simples e segura usando setval alinhado ao MAX(id). Com isso, você evita erros de chave duplicada e mantém o banco saudável mesmo após importações ou restores.

Se você quiser, eu posso publicar uma versão complementar mostrando:

• como resetar sequences em lote para um schema inteiro
• como fazer isso no contexto do Django (sqlsequencereset)
• como automatizar validação pós-deploy

Tabelas Padrão do Django: Autenticação, Permissões e Infraestrutura

 

Entendendo as Tabelas Padrão do Django: Autenticação, Permissões e Infraestrutura

Quando iniciamos um projeto com Django, várias tabelas são criadas automaticamente no banco de dados. Para quem olha pela primeira vez, nomes como auth_group, django_content_type ou django_migrations podem parecer confusos.

Este artigo explica para que serve cada uma dessas tabelas, como elas se relacionam e quando você deve (ou não) interagir com elas.

Atenção: a maioria dessas tabelas faz parte da infraestrutura do framework. Elas não são tabelas de negócio.

---

Visão geral

As tabelas padrão do Django podem ser agrupadas em quatro grandes áreas:

1. Autenticação (quem é o usuário)
2. Autorização (o que o usuário pode fazer)
3. Infraestrutura interna do framework
4. Sessão e estado

---

1. Tabelas de Autenticação

auth_user

É a tabela central de usuários autenticáveis do Django.

Ela armazena informações como:

• nome de usuário
• senha (sempre em hash)
• e-mail
• flags de acesso (is_active, is_staff, is_superuser)
• datas de login e criação

Essa tabela é usada pelo sistema de login, logout e controle de acesso.

Boa prática: use auth_user para autenticação, não como entidade de negócio (ex.: funcionário, cliente, aluno).

---

2. Tabelas de Autorização (Permissões)

auth_permission

Armazena permissões individuais do sistema.

Para cada model Django, o framework cria automaticamente permissões padrão, como:

• adicionar
• alterar
• excluir
• visualizar

Essas permissões são usadas para controlar o acesso a funcionalidades específicas.

auth_group

Representa grupos de usuários.

Um grupo é basicamente um conjunto de permissões que pode ser atribuído a vários usuários.

Exemplos de grupos comuns:

• Administradores
• Editores
• Leitores

auth_group_permissions

Tabela associativa entre:

• grupos
• permissões

Define quais permissões cada grupo possui.

É aqui que o Django resolve a pergunta:

“O que usuários deste grupo podem fazer?”

auth_user_groups

Tabela associativa entre:

• usuários
• grupos

Define a quais grupos cada usuário pertence.

Um usuário pode estar em vários grupos ao mesmo tempo.

auth_user_user_permissions

Tabela associativa entre:

• usuários
• permissões individuais

Permite conceder permissões diretamente a um usuário, sem passar por grupos.

Boa prática: usar grupos sempre que possível e evitar permissões diretas, pois elas dificultam a manutenção.

---

3. Tabelas de Infraestrutura do Django

django_content_type

Registra todos os models instalados no projeto.

Cada registro identifica:

• o app
• o nome do model

Essa tabela é usada internamente pelo Django para:

• sistema de permissões
• Django Admin
• relacionamentos genéricos
• logs

Ela é fundamental para o funcionamento interno do framework.

django_admin_log

Armazena logs de ações realizadas no Django Admin.

Registra informações como:

• qual usuário realizou a ação
• qual objeto foi afetado
• qual operação foi executada (criação, alteração, exclusão)

É muito útil para auditoria administrativa.

django_migrations

Controla quais migrações já foram aplicadas no banco de dados.

Cada vez que você executa python manage.py migrate, o Django consulta essa tabela para saber:

• quais migrações já rodaram
• quais ainda precisam ser aplicadas

Importante: nunca edite ou apague registros dessa tabela manualmente.

---

4. Tabela de Sessão

django_session

Armazena as sessões ativas dos usuários.

É usada para:

• manter usuários logados
• armazenar dados temporários
• mensagens flash
• estados intermediários de formulários

As sessões têm prazo de validade e podem ser limpas automaticamente.

---

Resumo rápido

Tabela	Finalidade
auth_user	Usuários do sistema
auth_group	Grupos / perfis
auth_permission	Permissões
auth_group_permissions	Grupo ↔ Permissão
auth_user_groups	Usuário ↔ Grupo
auth_user_user_permissions	Permissões diretas
django_content_type	Registro de models
django_admin_log	Log do admin
django_migrations	Controle de migrations
django_session	Sessões

---

Boas práticas gerais

• Não manipule essas tabelas diretamente via SQL.
• Use sempre a API do Django (models, admin, permissions).
• Centralize permissões em grupos.
• Use auth_user apenas para autenticação.
• Separe entidades de negócio em tabelas próprias.

---

Conclusão

As tabelas padrão do Django formam a base de segurança e funcionamento do framework. Entendê-las ajuda a:

• modelar sistemas mais seguros
• evitar erros em produção
• criar arquiteturas mais limpas e escaláveis

Mesmo que você nunca precise mexer nelas diretamente, saber para que cada uma existe faz toda a diferença.

📦 Como mover uma tabela de um schema para outro no PostgreSQL

Organizar tabelas em schemas é uma prática essencial para manter bancos de dados grandes bem estruturados — especialmente em aplicações com múltiplos módulos, equipes ou microserviços.

Mas o que fazer quando você precisa mover uma tabela existente para outro schema? Felizmente, o PostgreSQL oferece um comando simples e poderoso para isso.

✅ Comando oficial: ALTER TABLE ... SET SCHEMA

Para mover uma tabela de um schema para outro, basta executar:

ALTER TABLE schema_atual.nome_da_tabela 
SET SCHEMA novo_schema;

📌 Exemplo prático

Mover a tabela usuarios de public para app_core:

ALTER TABLE public.usuarios
SET SCHEMA app_core;

---

📁 O que acontece quando você move uma tabela?

• As constraints (PK, FK, UNIQUE) vão junto automaticamente ✔️
• As foreign keys continuam funcionando ✔️
• Views e funções que referem o schema antigo podem parar de funcionar ⚠️
• Triggers, policies e permissões seguem anexadas à tabela ✔️

Ou seja: o PostgreSQL move toda a estrutura interna de forma segura, mas você precisa revisar apenas objetos que usam o nome qualificado do schema.

---

🔎 Verificando dependências antes de mover

Quer saber onde a tabela está sendo usada?

SELECT *
FROM pg_depend d
JOIN pg_class c ON d.refobjid = c.oid
WHERE c.relname = 'usuarios';

Isso ajuda a identificar views, funções ou objetos que referenciam a tabela.

---

🚚 Mover todas as tabelas de um schema automaticamente

Se você precisa mover várias tabelas de uma vez, use o bloco DO abaixo:

DO $$
DECLARE r RECORD;
BEGIN
  FOR r IN
    SELECT tablename
    FROM pg_tables
    WHERE schemaname = 'public'
  LOOP
    EXECUTE format('ALTER TABLE public.%I SET SCHEMA app_core;', r.tablename);
  END LOOP;
END$$;

Simples e eficiente para reorganizar um banco inteiro.

---

🏗️ Quando faz sentido mover tabelas para outro schema?

• Separar tabelas internas das tabelas da aplicação
• Organizar módulos diferentes (ex.: financeiro, usuarios, core)
• Melhorar segurança com permissões por schema
• Evitar poluição do schema public

Criar schemas bem definidos melhora a manutenção, a governança de dados e a colaboração entre equipes de desenvolvimento.

---

🎯 Conclusão

Mover tabelas entre schemas no PostgreSQL é simples com ALTER TABLE ... SET SCHEMA, e essa prática ajuda a manter sua estrutura de banco de dados limpa, organizada e modular.

Se você utiliza Django, Supabase ou microserviços, separar suas tabelas em schemas diferentes pode ser um grande avanço na arquitetura do projeto.

Gostou do conteúdo? Compartilhe com outros desenvolvedores! 🚀

📦 PostgreSQL: Movendo Tabelas Entre Schemas

1️⃣ Comando Principal

ALTER TABLE schema_atual.tabela
SET SCHEMA novo_schema;
  

✔ Simples, rápido e seguro.
✔ Move a tabela inteira, incluindo PK, FK, UNIQUE e índices.

---

2️⃣ O que Acontece ao Mover?

• 🔗 FKs, PKs e UNIQUE vão junto automaticamente.
• 🏷 Views e funções que referem o schema antigo podem precisar de ajuste.
• ⚙ Permissões e triggers permanecem funcionando.

---

3️⃣ Verificar Dependências Antes

SELECT *
FROM pg_depend d
JOIN pg_class c ON d.refobjid = c.oid
WHERE c.relname = 'nome_da_tabela';
  

🔍 Útil para localizar views, triggers e funções dependentes.

---

4️⃣ Mover Todas as Tabelas de um Schema

DO $$
DECLARE r RECORD;
BEGIN
  FOR r IN
    SELECT tablename
    FROM pg_tables
    WHERE schemaname = 'public'
  LOOP
    EXECUTE format('ALTER TABLE public.%I SET SCHEMA app_core;', r.tablename);
  END LOOP;
END$$;
  

🚚 Excelente para reorganizar o banco inteiro.

---

5️⃣ Quando Usar Schemas Separados?

• 📁 Separar tabelas internas e tabelas de aplicação.
• 🧩 Organizar módulos (financeiro, usuários, core etc.).
• 🔐 Melhorar segurança com permissões por schema.
• 🧹 Evitar poluição do schema public.

---

🎯 Dica Final

Use schemas para modularidade, segurança e organização do banco.
Mover tabelas é seguro e simples com SET SCHEMA.

Git: Comandos para Desfazer e Deletar

 

Se você trabalha com programação, cedo ou tarde vai precisar dominar os comandos essenciais do Git. Neste guia prático, você vai aprender de forma simples como apagar branches, desfazer commits, criar novos branches e trabalhar corretamente com o GitLab.

---

✅ Como Apagar um Branch com Segurança

⚠️ Erro comum: não é possível apagar o branch que está em uso no momento. O Git protege você contra isso.

1️⃣ Volte para o branch principal

git checkout main

2️⃣ Apague o branch local

git branch -D nome_do_branch

3️⃣ (Opcional) Apague o branch remoto no GitLab

git push origin --delete nome_do_branch

---

✅ 4 Maneiras de Desfazer um Commit

🔹 1. Corrigir mensagem ou incluir arquivo (mantém alterações)

git reset --soft HEAD~1

Desfaz o commit, mas mantém os arquivos no estado de modificação.

🔹 2. Descartar completamente o último commit

git reset --hard HEAD~1

⚠️ Apaga tudo permanentemente.

🔹 3. Desfazer um commit que já foi enviado (push)

git revert HEAD

Cria um novo commit que desfaz o anterior (modo mais seguro).

🔹 4. Apagar commit até no repositório remoto (perigoso)

git reset --hard HEAD~1
git push origin main --force

---

✅ Ciclo de Vida de um Branch no GitLab

🚀 1. Enviar (push) seu novo branch

git push -u origin nome_do_branch

🗑️ 2. Apagar a cópia local após o merge

git branch -d nome_do_branch

🌐 3. Apagar o branch remoto

git push origin --delete nome_do_branch

💡 Dica Pro: ao criar um Merge Request (MR) no GitLab, marque a opção “Delete source branch after merge” para apagar automaticamente.

---

✅ Como Criar um Novo Branch para uma Nova Funcionalidade

1️⃣ Vá para a branch principal e atualize

git checkout main
git pull origin main

2️⃣ Crie e já entre no novo branch

git checkout -b feature/nova-funcionalidade

3️⃣ Envie para o GitLab

git push -u origin feature/nova-funcionalidade

---

✅ Como Renomear um Branch

Se estiver no próprio branch:

git branch -m novo_nome

Se for outro branch:

git branch -m nome_antigo novo_nome

Atualizar no GitLab:

git push -u origin novo_nome
git push origin --delete nome_antigo

---

✅ Resumo Rápido dos Comandos Essenciais

• Criar branch: git checkout -b feature/minha-feature
• Enviar branch: git push -u origin minha-feature
• Apagar branch local: git branch -d minha-feature
• Apagar branch remoto: git push origin --delete minha-feature
• Desfazer commit mantendo arquivos: git reset --soft HEAD~1
• Desfazer commit apagando tudo: git reset --hard HEAD~1
• Desfazer commit já enviado: git revert HEAD

---

🎯 Conclusão

Dominar esses comandos do Git e o fluxo com GitLab é essencial para trabalhar com qualidade, segurança e produtividade. Com esse guia, você evita erros comuns, mantém seu repositório limpo e trabalha alinhado com boas práticas profissionais.

🚀 Bons commits!

Como Resetar a Epson L3150 - Almofada de Tinta Cheia

🖨️ Como Resetar a Epson L3150 com WIC Reset Utility (Windows, macOS e Linux) – GRÁTIS!

Se sua impressora Epson parou de funcionar e exibe mensagens como “A almofada de tinta da impressora está no fim da vida útil”, saiba que o problema é reversível. Isso acontece quando a impressora atinge o limite programado de uso da waste ink pad (almofada de tinta). 😖

A boa notícia? Você pode resetar isso gratuitamente com a Trial Key usando o utilitário WIC Reset Utility – compatível com Windows, macOS (Intel) e Linux. Veja o passo a passo completo! ✅

---

🔧 O que você vai precisar

• 🟢 Sua impressora Epson compatível (como a L3150) 🖨️
• 🟢 Um computador com Windows, macOS (Intel) ou Linux
• 🟢 Conexão USB com a impressora
• 🟢 Baixar o WIC Reset Utility ou iWIC aqui
• 🟢 Usar a chave de teste gratuita (TRIAL)
• 🟢 Almofada absorvente ( 🇧🇷 BR / 🇺🇲  US / 🇨🇳 CH )

🧭 Etapas do Reset Gratuito

1. 🔽 Baixe o WIC Reset Utility

Acesse o site oficial:

https://www.wic.support/download/

Escolha a versão certa para o seu sistema:

• 💻 Windows → WIC Reset Utility for Windows
• 🍎 Mac (Intel) → iWIC.dmg
• 🐧 Linux → Versão .sh para terminal

* lembre sempre de verificar se tem algum vírus nos arquivos.

2. 🖥️ Conecte sua impressora via USB

Ligue sua impressora Epson e conecte ao computador por cabo USB. Não use Wi-Fi neste processo.

Aparentemente a versão MAC permite o uso via Wi-Fi, se conseguir coloque nos comentários.

3. 🚀 Execute o utilitário

Abra o WIC (ou iWIC/iWIC Linux) e aguarde ele detectar a impressora. 

4. 🧪 Use a Trial Key Gratuita

Clique em “Read Waste Counters” para ver o estado das almofadas de tinta.

Depois, clique em “Reset Waste Ink Counters”

Na tela que pede a chave de ativação, digite:

TRIAL

🟢 A trial key irá resetar os contadores para 80% – o suficiente para a impressora voltar a funcionar!

5. ✅ Finalize

Aguarde a conclusão do processo. Quando solicitado, reinicie a impressora. Ela voltará a imprimir normalmente!

---

📝 Conclusão

🧼 Trocar as almofadas físicas de tinta não basta: é necessário informar à impressora que isso foi feito.

Com o WIC Reset Utility, você pode fazer isso em minutos – sem risco, sem pagar, sem complicação.

Use a versão grátis com a Trial Key e economize tempo e dinheiro!

Se gostou, compartilhe com quem tem uma Epson travada em casa! 💬

https://youtu.be/5DnHqAbWQhs

FastAPI + HTMX vs Django em times com IA, Cursor e GitLab 🚀

Quando falamos em construir um único sistema grande, com vários módulos (usuários, financeiro, relatórios, etc.), usando PostgreSQL e apoio pesado de IA no Cursor/Vibe Code, a escolha entre FastAPI + HTMX e Django vai muito além de performance. Entra na conta a experiência do time com trabalho colaborativo, Git, branches e merge requests no GitLab. 😅

1. Visão geral dos dois cenários

FastAPI + HTMX

• FastAPI: framework moderno, assíncrono, tipado e ótimo para APIs.
• HTMX: permite interações dinâmicas sem precisar de SPA pesada.
• Arquitetura mais aberta: você decide ORM, auth, estrutura de pastas, etc.

Django

• Framework "baterias incluídas": ORM, auth, templates, admin, etc.
• Estrutura de projeto bem definida (apps, urls, settings).
• Excelente para um monolito organizado em vários apps.

2. IA escrevendo código: quem se beneficia mais? 🤖

Com o Cursor e o Vibe Code gerando trechos de código, o framework que tiver padrões mais previsíveis sai na frente.

Django + IA

• Apps, models, views, urls, templates: tudo segue um padrão conhecido.
• A IA "sabe" preencher esse esqueleto com muita facilidade.
• Menos risco de virar um código todo fragmentado com vários estilos diferentes.

FastAPI + HTMX + IA

• A IA também lida muito bem com FastAPI.
• Mas, como a arquitetura é mais flexível, cada dev pode induzir a IA a criar estruturas diferentes (pastas, serviços, camadas).
• Isto exige um guia de arquitetura bem definido para humanos e IA seguirem o mesmo padrão.

3. Comparativo rápido 💡

Critério	FastAPI + HTMX	Django
Arquitetura	Flexível; você define camadas e padrões.	Mais opinativo; estrutura de apps bem definida.
IA (Cursor / Vibe Code)	Funciona muito bem, mas exige guia de estilo forte.	IA se apoia em padrões consolidados do framework.
Curva de aprendizado em time colaborativo	Maior risco de divergência de estilos entre módulos.	Mais “trilhos” para o time seguir junto.
Admin interno	Depende de bibliotecas externas ou código próprio.	Django Admin pronto para uso.
Microservices no futuro	Naturalmente amigável a divisão em serviços.	Dá para fazer, mas o “modo padrão” é monolito.
Integração com PostgreSQL	Ótima (SQLAlchemy, etc.).	Ótima (Django ORM com suporte nativo).
Tamanho do time (2–4 devs)	Bom, se todos seguirem o mesmo padrão.	Muito bom, especialmente com menos experiência em Git.

4. Organização do repositório e módulos 🧩

Em ambos os casos, faz muita diferença ter um monorepo bem organizado no GitLab, com módulos claros e responsabilidades definidas.

Exemplo de organização com Django

project/
  manage.py
  project/
    settings.py
    urls.py
  apps/
    usuarios/
      models.py
      views.py
      urls.py
      templates/usuarios/
    financeiro/
    relatorios/
  

Cada app representa um módulo de negócio. Isso facilita o trabalho em paralelo: um dev cuida de usuarios, outro de financeiro, e assim por diante.

Exemplo de organização com FastAPI

app/
  main.py
  core/
  db/
  modules/
    usuarios/
      routers.py
      models.py
      schemas.py
      services.py
      templates/
    financeiro/
    relatorios/
  

Aqui, os routers e services de cada módulo ficam agrupados. Também é uma boa abordagem, mas depende mais de disciplina da equipe.

5. GitLab, branches e merges para iniciantes em trabalho conjunto 🧵

Mesmo com desenvolvedores experientes em outras tecnologias, a parte de trabalhar no mesmo app e fazer merge de código é um desafio à parte.

Fluxo simples recomendado

• Manter uma branch principal: main ou dev.
• Para cada funcionalidade: criar uma feature branch, por exemplo:
  • feature/usuarios-listagem
  • feature/financeiro-faturas
• Commits pequenos e frequentes.
• Abrir Merge Requests no GitLab para revisão, mesmo que rápida.
• Evitar codar diretamente na branch principal.

Cuidando do escopo da IA

Ao pedir ajuda para a IA no Cursor:

• Seja bem específico: "No arquivo X, crie apenas a função Y. Não altere outros módulos."
• Evite pedir refatorações gigantescas em muitos arquivos de uma vez.
• Use um README ou arquivo de regras explicando a arquitetura e peça para a IA seguir esse padrão.

6. Quando faz mais sentido usar cada stack? 🎯

Use FastAPI + HTMX se:

• Você quer muito foco em APIs modernas e assíncronas.
• Pensa em evoluir para microservices no médio prazo.
• Seu time tem boa disciplina de arquitetura e vai manter um padrão firme (apoiado por README/.rules).

Use Django se:

• O objetivo é um grande sistema único com vários módulos internos.
• O time ainda está aprendendo a trabalhar no mesmo código, fazendo merges e lidando com conflitos.
• Você quer usufruir do Django Admin e da estrutura de apps bem definida.
• Quer que a IA siga trilhos mais claros, com menos decisões arquiteturais no dia a dia.

7. Conclusão 💬

Em um cenário com 2 a 4 desenvolvedores, usando IA (Cursor/Vibe Code) para escrever boa parte do código e PostgreSQL como banco de dados, a escolha do framework não é só técnica: é também organizacional.

Se o time ainda está pegando o jeito de trabalhar junto, fazer branches, revisar e fazer merge sem conflitos enormes, Django tende a ser a escolha mais segura pela quantidade de padrões que ele já traz. Já o combo FastAPI + HTMX brilha quando há experiência maior em arquitetura e desejo de flexibilidade.

O mais importante é: definir padrões claros, registrar isso no repositório e ensinar esses padrões tanto ao time quanto à IA. Assim, o framework escolhido deixa de ser um problema e vira um aliado na entrega do produto. 💻✨