michangarrito/docs/_definitions/DATABASE-SCHEMA.md

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

Database Schema - MiChangarrito

Alias: @MCH_DEF_DB Version: 2.0.0 Ultima actualizacion: 2026-01-17 Estado: VALIDADO vs Codigo

---

1. RESUMEN

Metrica	Valor
ORM	TypeORM 0.3.19
DB Engine	PostgreSQL 16+
Schema	public (unico)
Total Tablas	38 (generadas por entities)
Multi-tenant	Si (tenant_id en todas las tablas)

Nota: Este proyecto utiliza TypeORM con migraciones automaticas. Las tablas se generan a partir de las entities definidas en backend/src/modules/*/entities/.

---

2. TABLAS POR MODULO

2.1 Auth (2 tablas)

Tabla	Entity	Descripcion
tenants	Tenant	Tiendas/Changarritos (multi-tenant root)
users	User	Usuarios del sistema

2.2 Categories (1 tabla)

Tabla	Entity	Descripcion
categories	Category	Categorias de productos

2.3 CoDi-SPEI (3 tablas)

Tabla	Entity	Descripcion
codi_transactions	CodiTransaction	Transacciones CoDi
spei_transactions	SpeiTransaction	Transacciones SPEI
virtual_accounts	VirtualAccount	Cuentas virtuales

2.4 Customers (3 tablas)

Tabla	Entity	Descripcion
customers	Customer	Clientes del changarrito
fiados	Fiado	Creditos/fiados
fiado_payments	FiadoPayment	Pagos de fiados

2.5 Integrations (2 tablas)

Tabla	Entity	Descripcion
tenant_integration_credentials	TenantIntegrationCredential	Credenciales por tenant
tenant_whatsapp_numbers	TenantWhatsappNumber	Numeros WhatsApp

2.6 Inventory (2 tablas)

Tabla	Entity	Descripcion
inventory_movements	InventoryMovement	Movimientos de stock
stock_alerts	StockAlert	Alertas de stock bajo

2.7 Invoices (3 tablas)

Tabla	Entity	Descripcion
invoices	Invoice	Facturas CFDI
invoice_items	InvoiceItem	Items de factura
tax_configs	TaxConfig	Configuracion fiscal

2.8 Marketplace (6 tablas)

Tabla	Entity	Descripcion
suppliers	Supplier	Proveedores B2B
supplier_products	SupplierProduct	Productos de proveedores
supplier_orders	SupplierOrder	Ordenes a proveedores
supplier_order_items	SupplierOrderItem	Items de orden
supplier_reviews	SupplierReview	Resenas
supplier_favorites	SupplierFavorites	Favoritos

2.9 Messaging (3 tablas)

Tabla	Entity	Descripcion
conversations	Conversation	Conversaciones
messages	Message	Mensajes
notifications	Notification	Notificaciones

2.10 Orders (2 tablas)

Tabla	Entity	Descripcion
orders	Order	Pedidos
order_items	OrderItem	Items del pedido

2.11 Payments (1 tabla)

Tabla	Entity	Descripcion
payment_methods	PaymentMethod	Metodos de pago

2.12 Products (1 tabla)

Tabla	Entity	Descripcion
products	Product	Productos del catalogo

2.13 Referrals (3 tablas)

Tabla	Entity	Descripcion
referrals	Referral	Referidos
referral_codes	ReferralCode	Codigos
referral_rewards	ReferralReward	Recompensas

2.14 Sales (2 tablas)

Tabla	Entity	Descripcion
sales	Sale	Ventas POS
sale_items	SaleItem	Items de venta

2.15 Subscriptions (4 tablas)

Tabla	Entity	Descripcion
plans	Plan	Planes de suscripcion
subscriptions	Subscription	Suscripciones
token_balances	TokenBalance	Balance de tokens IA
token_usages	TokenUsage	Uso de tokens

---

3. RELACIONES PRINCIPALES

                    ┌─────────────┐
                    │   tenants   │ (Multi-tenant root)
                    └──────┬──────┘
                           │ 1:N
         ┌─────────────────┼─────────────────┐
         │                 │                 │
    ┌────▼────┐      ┌─────▼─────┐    ┌──────▼──────┐
    │  users  │      │ products  │    │ customers   │
    └─────────┘      └─────┬─────┘    └──────┬──────┘
                           │ 1:N             │ 1:N
                    ┌──────┴──────┐          │
                    │             │          │
               ┌────▼────┐  ┌─────▼─────┐    │
               │  sales  │  │  orders   │◄───┘
               └────┬────┘  └─────┬─────┘
                    │             │
               ┌────▼────┐  ┌─────▼─────┐
               │sale_items│  │order_items│
               └─────────┘  └───────────┘

---

4. INDICES Y CONSTRAINTS

4.1 Indices Principales

-- Multi-tenant
CREATE INDEX idx_products_tenant ON products(tenant_id);
CREATE INDEX idx_sales_tenant ON sales(tenant_id);
CREATE INDEX idx_customers_tenant ON customers(tenant_id);

-- Busquedas frecuentes
CREATE INDEX idx_products_barcode ON products(barcode);
CREATE INDEX idx_sales_date ON sales(created_at);
CREATE UNIQUE INDEX idx_users_email ON users(email);

4.2 Foreign Keys

• Todas las tablas tienen tenant_id -> tenants.id
• products.category_id -> categories.id
• sales.customer_id -> customers.id
• sale_items.product_id -> products.id
• fiados.customer_id -> customers.id

---

5. CONFIGURACION TYPEORM

# backend/src/config/database.config.ts
typeorm:
  type: "postgres"
  synchronize: false  # Usar migrations
  logging: ["error", "warn"]
  entities: ["dist/**/*.entity.js"]
  migrations: ["dist/database/migrations/*.js"]

---

6. REFERENCIAS

• Entities: @MCH_DEF_ENTITIES
• Backend Inventory: orchestration/inventarios/BACKEND_INVENTORY.yml
• Database Inventory: orchestration/inventarios/DATABASE_INVENTORY.yml

---

Definicion canonica v2.0.0 - MiChangarrito - VALIDADO