melhorias na ia

rules/fronteiras-monorepo.global.md

@@ -0,0 +1,120 @@
+---
+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: `.agent/rules/zod-validacao-padrao.global.md` (schemas no `*-comuns`)
+- Skill: `.agent/skills/mapear-codigo-fonte.global/SKILL.md`