120 lines
3.8 KiB
Markdown
120 lines
3.8 KiB
Markdown
---
|
|
type: rule
|
|
name: fronteiras-monorepo
|
|
description: Define a convenção de pacotes e regras de importação entre módulos do monorepo
|
|
scope: global
|
|
trigger: always_on
|
|
updatedAt: "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: `global/rules/zod-validacao-padrao.md` (schemas no `*-comuns`)
|
|
- Skill: `global/skills/mapear-codigo-fonte/SKILL.md`
|