vue-componentes/.agent/rules/fronteiras-monorepo.global.md

type	name	description	scope	trigger	updatedAt
rule	fronteiras-monorepo	Define a convenção de pacotes e regras de importação entre módulos do monorepo	global	always_on	2026-06-01

Regra: Fronteiras de Pacote no Monorepo

Contexto

Cada módulo SaaS do ecossistema é organizado em até 4 pacotes dentro de um monorepo. O agente deve respeitar as fronteiras de importação entre pacotes para evitar acoplamento indevido.

Convenção de Pacotes

Cada módulo segue a estrutura:

<modulo>-back       ← Servidor: rotas, serviços, filas, CRON
<modulo>-front      ← Interface: páginas Vue, componentes, composables
<modulo>-comuns     ← Compartilhado: tipos, schemas Zod, enums, utils puros
<modulo>-migracao   ← Banco de dados: migrations, seeds, scripts de carga

Nem todo módulo terá os 4 pacotes. O mínimo funcional é back + front + comuns.

Regras de Importação

Permitido ✅

<modulo>-front  → pode importar de → <modulo>-comuns
<modulo>-back   → pode importar de → <modulo>-comuns
<modulo>-migracao → pode importar de → <modulo>-comuns

Proibido ❌

<modulo>-front  ✗ nunca importar de → <modulo>-back
<modulo>-back   ✗ nunca importar de → <modulo>-front
<modulo>-migracao ✗ nunca importar de → <modulo>-front
<modulo>-front  ✗ nunca importar de → <outro-modulo>-back
<outro-modulo>  ✗ nunca importar de → <modulo>-back (direto)

Comunicação entre módulos

Módulos diferentes nunca importam código um do outro diretamente. Comunicação entre módulos deve ocorrer via:

• API HTTP (chamada de serviço entre backs)
• Fila (BullMQ, Redis) para processamento assíncrono
• Banco compartilhado com schemas/tabelas separados por módulo
• Pacote *-comuns compartilhado apenas para tipos e schemas de contrato

O que vive em cada pacote

<modulo>-comuns

O pacote comuns é a única fonte de verdade para tipos e schemas compartilhados:

<modulo>-comuns/src/
├── tabelas/            ← schemas Zod por entidade (zEntidadeCriar, etc.)
├── enums/              ← enums de domínio do módulo
├── tipos/              ← tipos derivados dos schemas
└── utils/              ← funções puras sem side-effect

Proibido no comuns:

• Componentes Vue ou React
• Código com import de Node.js (fs, path, http)
• Código com import de bibliotecas de frontend (vue, vuetify)
• Lógica de negócio que depende de banco ou serviço externo

<modulo>-back

<modulo>-back/src/
├── rotas/              ← endpoints Express/Fastify
├── servicos/           ← lógica de negócio
├── banco/              ← queries (Knex, Prisma, etc.)
├── filas/              ← processadores de fila
├── cron/               ← tarefas agendadas
└── utils/              ← helpers exclusivos do back

<modulo>-front

<modulo>-front/src/
├── paginas/            ← páginas/views por rota
├── componentes/        ← componentes reutilizáveis do módulo
├── composables/        ← lógica reutilizável (use*.ts)
└── utils/              ← helpers exclusivos do front

<modulo>-migracao

<modulo>-migracao/src/
├── migrations/         ← criação/alteração de tabelas
├── seeds/              ← dados iniciais
└── scripts/            ← scripts de carga/transformação

Impacto

Sem esta regra:

• Front importa serviço de back (quebra em build de produção)
• Módulo A acessa tabelas do Módulo B diretamente (acoplamento oculto)
• Schemas ficam duplicados entre back e front
• Mudança em um módulo quebra outro sem aviso

Referências

• Rule: .agent/rules/zod-validacao-padrao.global.md (schemas no *-comuns)
• Skill: .agent/skills/mapear-codigo-fonte.global/SKILL.md