> ## Documentation Index
> Fetch the complete documentation index at: https://docs.domsoftware.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Modelo de Dados (ERD)

> Diagrama de Entidade-Relacionamento e representação estrutural da arquitetura de Multi-Tenancy.

Para que a equipe de engenharia compreenda visualmente como o banco de dados relaciona as categorias críticas (Tenants, Produtos, Kits, e Integrações), desenvolvemos o modelo lógico abaixo.

## 1. Diagrama Entidade-Relacionamento Core

Por conta do padrão **Domain-Driven Design (DDD)**, as entidades se relacionam não pelo acoplamento forçado, mas pelas raízes de Agregação. Observação Crítica: A variável `tenant_id` atua como Chave Composita ou Foregin Key mandátoria em praticamente todas as tabelas.

```mermaid theme={null}
erDiagram
    TENANT {
        uuid id PK
        string name
        boolean isActive
        timestamp createdAt
    }

    COMPANY_PROFILE {
        uuid id PK
        uuid tenant_id FK
        string cnpj
        string legalName
        string stateRegistration
    }

    USER {
        uuid id PK
        uuid tenant_id FK
        string email
        string password_hash
        string role
    }

    PRODUCT {
        uuid id PK
        uuid tenant_id FK
        string sku
        string type "SIMPLE, KIT, MANUFACTURED"
        string commercialName
        decimal price
        decimal costPrice
    }

    PRODUCT_VARIATION {
        uuid id PK
        uuid product_id FK
        string sku
        decimal price_override
        jsonb attributes
    }

    KIT_COMPONENT {
        uuid id PK
        uuid kit_id FK "Produto Pai (Type=KIT)"
        uuid component_id FK "Produto Filho (Type=SIMPLE)"
        int quantity
        decimal lossPercentage
    }

    INVENTORY_BALANCE {
        uuid id PK
        uuid tenant_id FK
        uuid product_id FK
        uuid warehouse_id FK
        int physicalQty
        int reservedQty
    }

    MARKETPLACE_APP_TOKEN {
        uuid id PK
        uuid tenant_id FK
        string platform "MELI, SHOPEE"
        string acccessTokenEncrypted
        string refreshTokenEncrypted
        timestamp expiresAt
    }

    TENANT ||--o| COMPANY_PROFILE : "possui um"
    TENANT ||--o{ USER : "tem múltiplos"
    TENANT ||--o{ PRODUCT : "dono de"
    TENANT ||--o{ MARKETPLACE_APP_TOKEN : "conecta"
    
    PRODUCT ||--o{ PRODUCT_VARIATION : "pode ter"
    PRODUCT ||--o{ KIT_COMPONENT : "é composto por"
    PRODUCT ||--o{ INVENTORY_BALANCE : "possui saldo em"

```

***

## 2. Dicionário de Restrições Arquiteturais

### Multi-Tenancy (Isolamento de Dados)

1. **Gatilhos de Inserção:** Graças ao `TenantSubscriber` (TypeORM), a equipe de Dev **não** precisa passar o `tenantId` nos métodos de `create()` de `Product`, `InventoryBalance`, etc. É injetado por reflexão do CLS-Hooked.
2. **Índices Compostos de Proteção:** Todas as queries que buscam unicidade (Exemplo: "Existe SKUs duplicados?") obrigatoriamente possuem um `@Index(unique: true)` não no SKU sozinho, mas sim no bundle `(tenant_id, sku)`.

### Agregações do Catálogo (`Product` e `KitComponent`)

A API de leitura do produto lista os componentes, mas observe no ERD que `KIT_COMPONENT` faz referência reflexiva apontando sempre para um `Product`.

* `kit_id`: Referencia a linha do Produto com tipo = `KIT`.
* `component_id`: Referencia a linha do Produto com tipo = `SIMPLE`.
  Não é permitido que o `component_id` aponte para outro `KIT` (evita recursividade infinita cíclica que travaria os *workers* de custo médio e baixa de estoque).

### Segurança e Criptografia (Tokens OAuth)

`MARKETPLACE_APP_TOKEN` nunca armazena textos puros! Todo *access\_token* fornecido pela Shopee ou Mercado Livre é interceptado no `TokenService` e escrito no banco usando Criptografia AES de 256 bits, usando a chave Mestra `.env(TOKEN_ENCRYPTION_KEY)`. O ERD acusa a coluna como `acccessTokenEncrypted` para forçar este mindset em manutenções de DBA.