saveinmed/docs/database-schema.md

# Database Schema - SaveInMed

Documentação do esquema de banco de dados PostgreSQL do SaveInMed.

---

## Diagrama ER

```mermaid
erDiagram
    COMPANIES ||--o{ USERS : "emprega"
    COMPANIES ||--o{ PRODUCTS : "vende"
    COMPANIES ||--o{ ORDERS : "compra (buyer)"
    COMPANIES ||--o{ ORDERS : "vende (seller)"
    COMPANIES ||--o{ CART_ITEMS : "possui"
    ORDERS ||--o{ ORDER_ITEMS : "contém"
    PRODUCTS ||--o{ ORDER_ITEMS : "inclui"
    PRODUCTS ||--o{ CART_ITEMS : "referencia"
    ORDERS ||--o| REVIEWS : "avalia"
    ORDERS ||--o| SHIPMENTS : "envia"

    COMPANIES {
        uuid id PK
        text cnpj UK
        text corporate_name
        text category
        text license_number
        boolean is_verified
        float latitude
        float longitude
        text city
        text state
        text phone
        text operating_hours
        boolean is_24_hours
        timestamptz created_at
        timestamptz updated_at
    }

    USERS {
        uuid id PK
        uuid company_id FK
        text role
        text name
        text username UK
        text email UK
        boolean email_verified
        text password_hash
        timestamptz created_at
        timestamptz updated_at
    }

    PRODUCTS {
        uuid id PK
        uuid seller_id FK
        text name
        text description
        text batch
        date expires_at
        bigint price_cents
        bigint stock
        timestamptz created_at
        timestamptz updated_at
    }

    ORDERS {
        uuid id PK
        uuid buyer_id FK
        uuid seller_id FK
        text status
        bigint total_cents
        text shipping_recipient_name
        text shipping_street
        text shipping_number
        text shipping_complement
        text shipping_district
        text shipping_city
        text shipping_state
        text shipping_zip_code
        text shipping_country
        timestamptz created_at
        timestamptz updated_at
    }

    ORDER_ITEMS {
        uuid id PK
        uuid order_id FK
        uuid product_id FK
        bigint quantity
        bigint unit_cents
        text batch
        date expires_at
    }

    CART_ITEMS {
        uuid id PK
        uuid buyer_id FK
        uuid product_id FK
        bigint quantity
        bigint unit_cents
        text batch
        date expires_at
        timestamptz created_at
        timestamptz updated_at
    }

    REVIEWS {
        uuid id PK
        uuid order_id FK UK
        uuid buyer_id FK
        uuid seller_id FK
        int rating
        text comment
        timestamptz created_at
    }

    SHIPMENTS {
        uuid id PK
        uuid order_id FK UK
        text carrier
        text tracking_code
        text external_tracking
        text status
        timestamptz created_at
        timestamptz updated_at
    }
```

---

## Tabelas

### `companies`
Empresas (farmácias/distribuidoras) cadastradas na plataforma.

| Coluna | Tipo | Descrição |
|--------|------|-----------|
| `id` | UUID | Chave primária |
| `cnpj` | TEXT | CNPJ (único) |
| `corporate_name` | TEXT | Razão social |
| `category` | TEXT | Categoria (farmacia, distribuidora) |
| `license_number` | TEXT | Número da licença sanitária |
| `is_verified` | BOOLEAN | Se a empresa foi verificada |
| `latitude` | FLOAT | Latitude da localização |
| `longitude` | FLOAT | Longitude da localização |
| `city` | TEXT | Cidade |
| `state` | TEXT | Estado (UF) |
| `phone` | TEXT | Telefone de contato |
| `operating_hours` | TEXT | Horário de funcionamento |
| `is_24_hours` | BOOLEAN | Funciona 24 horas |
| `created_at` | TIMESTAMPTZ | Data de criação |
| `updated_at` | TIMESTAMPTZ | Data de atualização |

---

### `users`
Usuários vinculados às empresas.

| Coluna | Tipo | Descrição |
|--------|------|-----------|
| `id` | UUID | Chave primária |
| `company_id` | UUID | FK para companies |
| `role` | TEXT | Perfil (Dono, Colaborador, Entregador, Admin) |
| `name` | TEXT | Nome completo |
| `username` | TEXT | Login único |
| `email` | TEXT | Email único |
| `email_verified` | BOOLEAN | Email verificado |
| `password_hash` | TEXT | Hash da senha (bcrypt) |
| `created_at` | TIMESTAMPTZ | Data de criação |
| `updated_at` | TIMESTAMPTZ | Data de atualização |

---

### `products`
Produtos cadastrados para venda.

| Coluna | Tipo | Descrição |
|--------|------|-----------|
| `id` | UUID | Chave primária |
| `seller_id` | UUID | FK para companies (vendedor) |
| `ean_code` | TEXT | Código EAN/barras |
| `name` | TEXT | Nome do produto |
| `description` | TEXT | Descrição |
| `manufacturer` | TEXT | Laboratório/Fabricante |
| `category` | TEXT | Categoria (Analgésicos, Antibióticos, etc) |
| `subcategory` | TEXT | Subcategoria (opcional) |
| `batch` | TEXT | Lote |
| `expires_at` | DATE | Data de validade |
| `price_cents` | BIGINT | Preço em centavos |
| `stock` | BIGINT | Quantidade em estoque |
| `observations` | TEXT | Observações adicionais |
| `created_at` | TIMESTAMPTZ | Data de criação |
| `updated_at` | TIMESTAMPTZ | Data de atualização |

---

### `orders`
Pedidos de compra.

| Coluna | Tipo | Descrição |
|--------|------|-----------|
| `id` | UUID | Chave primária |
| `buyer_id` | UUID | FK para companies (comprador) |
| `seller_id` | UUID | FK para companies (vendedor) |
| `status` | TEXT | Status (Pendente, Pago, Faturado, Entregue) |
| `total_cents` | BIGINT | Total em centavos |
| `shipping_*` | TEXT | Campos de endereço de entrega |
| `created_at` | TIMESTAMPTZ | Data de criação |
| `updated_at` | TIMESTAMPTZ | Data de atualização |

---

### `order_items`
Itens de um pedido.

| Coluna | Tipo | Descrição |
|--------|------|-----------|
| `id` | UUID | Chave primária |
| `order_id` | UUID | FK para orders |
| `product_id` | UUID | FK para products |
| `quantity` | BIGINT | Quantidade |
| `unit_cents` | BIGINT | Preço unitário em centavos |
| `batch` | TEXT | Lote do produto |
| `expires_at` | DATE | Validade do produto |

---

### `cart_items`
Itens no carrinho de compras.

| Coluna | Tipo | Descrição |
|--------|------|-----------|
| `id` | UUID | Chave primária |
| `buyer_id` | UUID | FK para companies |
| `product_id` | UUID | FK para products |
| `quantity` | BIGINT | Quantidade |
| `unit_cents` | BIGINT | Preço unitário |
| `batch` | TEXT | Lote |
| `expires_at` | DATE | Validade |
| `created_at` | TIMESTAMPTZ | Data de criação |
| `updated_at` | TIMESTAMPTZ | Data de atualização |

> **UNIQUE**: (buyer_id, product_id)

---

### `reviews`
Avaliações de pedidos.

| Coluna | Tipo | Descrição |
|--------|------|-----------|
| `id` | UUID | Chave primária |
| `order_id` | UUID | FK para orders (único) |
| `buyer_id` | UUID | FK para companies |
| `seller_id` | UUID | FK para companies |
| `rating` | INT | Nota (1-5) |
| `comment` | TEXT | Comentário |
| `created_at` | TIMESTAMPTZ | Data de criação |

---

### `shipments`
Envios de pedidos.

| Coluna | Tipo | Descrição |
|--------|------|-----------|
| `id` | UUID | Chave primária |
| `order_id` | UUID | FK para orders (único) |
| `carrier` | TEXT | Transportadora |
| `tracking_code` | TEXT | Código de rastreio interno |
| `external_tracking` | TEXT | Código de rastreio externo |
| `status` | TEXT | Status (Enviado, Em Trânsito, Entregue) |
| `created_at` | TIMESTAMPTZ | Data de criação |
| `updated_at` | TIMESTAMPTZ | Data de atualização |

---

## Convenções

- **Valores monetários**: Sempre em centavos (BIGINT)
- **IDs**: UUID v4 ou v7
- **Timestamps**: TIMESTAMPTZ (UTC)
- **Soft delete**: Não implementado (delete real)