michangarrito/docs/_definitions/DATABASE-SCHEMA.md

---
id: DEF-MCH-DB
type: Definition
title: "Database Schema"
simco_version: "4.0.1"
updated_at: 2026-01-17
---

# Database Schema - MiChangarrito

**Alias:** @MCH_DEF_DB
**Version:** 1.0.0
**Ultima actualizacion:** 2026-01-17

---

## 1. RESUMEN

| Metrica | Valor |
|---------|-------|
| **Total Schemas** | 15 |
| **Total Tablas** | ~65 |
| **Total Funciones** | 20 |
| **Total Triggers** | 25+ |
| **Extensiones** | 5 |

---

## 2. SCHEMAS

### 2.1 Schema: public

```yaml
descripcion: "Schema principal - Usuarios y configuracion base"
tablas:
  - users
  - roles
  - permissions
  - user_roles
```

### 2.2 Schema: stores

```yaml
descripcion: "Gestion de tiendas/changarritos"
tablas:
  - stores
  - store_settings
  - store_hours
```

### 2.3 Schema: products

```yaml
descripcion: "Catalogo de productos e inventario"
tablas:
  - products
  - categories
  - inventory
  - price_history
```

### 2.4 Schema: sales

```yaml
descripcion: "Punto de venta y transacciones"
tablas:
  - sales
  - sale_items
  - payments
  - cash_registers
```

### 2.5 Schema: orders

```yaml
descripcion: "Pedidos y entregas"
tablas:
  - orders
  - order_items
  - deliveries
```

### 2.6 Schema: customers

```yaml
descripcion: "Gestion de clientes"
tablas:
  - customers
  - customer_addresses
```

### 2.7 Schema: fiados

```yaml
descripcion: "Sistema de creditos/fiados"
tablas:
  - fiados
  - fiado_payments
  - credit_limits
```

### 2.8 Schema: subscriptions

```yaml
descripcion: "Planes y suscripciones SaaS"
tablas:
  - plans
  - subscriptions
  - subscription_history
```

### 2.9 Schema: tokens

```yaml
descripcion: "Tienda de tokens IA"
tablas:
  - token_packages
  - token_purchases
  - token_usage
```

### 2.10 Schema: notifications

```yaml
descripcion: "Sistema de notificaciones"
tablas:
  - notifications
  - notification_templates
  - notification_logs
```

### 2.11 Schema: integrations

```yaml
descripcion: "Integraciones externas"
tablas:
  - whatsapp_configs
  - llm_configs
  - payment_configs
```

### 2.12 Schema: analytics

```yaml
descripcion: "Metricas y reportes"
tablas:
  - daily_metrics
  - monthly_reports
  - predictions
```

### 2.13 Schema: ai

```yaml
descripcion: "Asistente IA y MCP Server"
tablas:
  - conversations
  - messages
  - tool_calls
```

### 2.14 Schema: onboarding

```yaml
descripcion: "Flujo de configuracion inicial"
tablas:
  - sessions
  - product_templates
  - template_imports
```

### 2.15 Schema: predictions

```yaml
descripcion: "Predicciones de inventario"
tablas:
  - inventory_predictions
  - reorder_suggestions
  - demand_history
```

---

## 3. TABLAS PRINCIPALES

### 3.1 users

```yaml
tabla: "users"
schema: "public"
descripcion: "Usuarios del sistema (duenos de changarritos)"
columnas:
  - nombre: "id"
    tipo: "UUID"
    pk: true
  - nombre: "email"
    tipo: "VARCHAR(255)"
    unique: true
  - nombre: "phone"
    tipo: "VARCHAR(20)"
  - nombre: "name"
    tipo: "VARCHAR(100)"
  - nombre: "created_at"
    tipo: "TIMESTAMP"
  - nombre: "updated_at"
    tipo: "TIMESTAMP"
relaciones:
  - tabla: "stores"
    tipo: "ONE_TO_MANY"
    columna: "owner_id"
indices:
  - nombre: "idx_users_email"
    columnas: ["email"]
    unique: true
```

### 3.2 stores

```yaml
tabla: "stores"
schema: "stores"
descripcion: "Changarritos/tiendas de los usuarios"
columnas:
  - nombre: "id"
    tipo: "UUID"
    pk: true
  - nombre: "owner_id"
    tipo: "UUID"
    fk: "users.id"
  - nombre: "name"
    tipo: "VARCHAR(100)"
  - nombre: "type"
    tipo: "VARCHAR(50)"
  - nombre: "status"
    tipo: "VARCHAR(20)"
relaciones:
  - tabla: "users"
    tipo: "MANY_TO_ONE"
    columna: "owner_id"
  - tabla: "products"
    tipo: "ONE_TO_MANY"
    columna: "store_id"
```

### 3.3 products

```yaml
tabla: "products"
schema: "products"
descripcion: "Productos del catalogo"
columnas:
  - nombre: "id"
    tipo: "UUID"
    pk: true
  - nombre: "store_id"
    tipo: "UUID"
    fk: "stores.id"
  - nombre: "name"
    tipo: "VARCHAR(200)"
  - nombre: "price"
    tipo: "DECIMAL(10,2)"
  - nombre: "stock"
    tipo: "INTEGER"
  - nombre: "category_id"
    tipo: "UUID"
    fk: "categories.id"
```

### 3.4 sales

```yaml
tabla: "sales"
schema: "sales"
descripcion: "Ventas realizadas en POS"
columnas:
  - nombre: "id"
    tipo: "UUID"
    pk: true
  - nombre: "store_id"
    tipo: "UUID"
    fk: "stores.id"
  - nombre: "total"
    tipo: "DECIMAL(10,2)"
  - nombre: "payment_method"
    tipo: "VARCHAR(20)"
  - nombre: "status"
    tipo: "VARCHAR(20)"
  - nombre: "created_at"
    tipo: "TIMESTAMP"
```

### 3.5 conversations (ai)

```yaml
tabla: "conversations"
schema: "ai"
descripcion: "Conversaciones con asistente LLM"
columnas:
  - nombre: "id"
    tipo: "UUID"
    pk: true
  - nombre: "store_id"
    tipo: "UUID"
    fk: "stores.id"
  - nombre: "user_id"
    tipo: "UUID"
    fk: "users.id"
  - nombre: "channel"
    tipo: "VARCHAR(20)"
  - nombre: "started_at"
    tipo: "TIMESTAMP"
  - nombre: "last_message_at"
    tipo: "TIMESTAMP"
```

### 3.6 inventory_predictions

```yaml
tabla: "inventory_predictions"
schema: "predictions"
descripcion: "Cache de predicciones de demanda"
columnas:
  - nombre: "id"
    tipo: "UUID"
    pk: true
  - nombre: "product_id"
    tipo: "UUID"
    fk: "products.id"
  - nombre: "period_start"
    tipo: "DATE"
  - nombre: "period_end"
    tipo: "DATE"
  - nombre: "predicted_demand"
    tipo: "DECIMAL(10,2)"
  - nombre: "confidence"
    tipo: "DECIMAL(3,2)"
  - nombre: "calculated_at"
    tipo: "TIMESTAMP"
```

---

## 4. RELACIONES PRINCIPALES

```
                    ┌─────────────┐
                    │   users     │
                    └──────┬──────┘
                           │ 1:N
              ┌────────────┼────────────┐
              │            │            │
       ┌──────▼──────┐  ┌──▼──┐  ┌──────▼───────┐
       │   stores    │  │ ai. │  │ subscriptions│
       └──────┬──────┘  │conv.│  └──────────────┘
              │ 1:N     └──┬──┘
    ┌─────────┼─────────┬──┴────────┐
    │         │         │           │
┌───▼───┐ ┌───▼───┐ ┌───▼───┐ ┌─────▼─────┐
│products│ │ sales │ │orders │ │ customers │
└───┬───┘ └───┬───┘ └───┬───┘ └─────┬─────┘
    │         │         │           │
    │    └────┴─────────┴───────────┘
    │                  │
    │          ┌───────▼───────┐
    │          │    fiados     │
    │          └───────────────┘
    │
┌───▼────────────┐
│ predictions.   │
│ inventory_pred.│
└────────────────┘
```

---

## 5. REFERENCIAS

- Especificaciones tecnicas: `docs/02-especificaciones/ARQUITECTURA-DATABASE.md`
- Migraciones: `apps/backend/src/database/migrations/`
- Entities: Ver @MCH_DEF_ENTITIES

---

*Definicion canonica v1.0.0 - MiChangarrito*