michangarrito/docs/_definitions/DATABASE-SCHEMA.md

id	type	title	simco_version	updated_at
DEF-MCH-DB	Definition	Database Schema	4.0.1	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

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

2.2 Schema: stores

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

2.3 Schema: products

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

2.4 Schema: sales

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

2.5 Schema: orders

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

2.6 Schema: customers

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

2.7 Schema: fiados

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

2.8 Schema: subscriptions

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

2.9 Schema: tokens

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

2.10 Schema: notifications

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

2.11 Schema: integrations

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

2.12 Schema: analytics

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

2.13 Schema: ai

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

2.14 Schema: onboarding

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

2.15 Schema: predictions

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

---

3. TABLAS PRINCIPALES

3.1 users

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

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

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

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)

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

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