michangarrito/docs/_definitions/DATABASE-SCHEMA.md

# Database Schema - MiChangarrito

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

---

## 1. RESUMEN

| Metrica | Valor |
|---------|-------|
| **Total Schemas** | 12 |
| **Total Tablas** | ~49 |
| **Total Funciones** | 15 |
| **Total Triggers** | 20+ |
| **Extensiones** | 4 |

---

## 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
```

---

## 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"
```

---

## 4. RELACIONES PRINCIPALES

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

---

## 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*