miinventario-v2/docs/_definitions/DATABASE-SCHEMA.md

Database Schema - MiInventario

Alias: @PROJ_DEF_DB Version: 1.0.0 Ultima actualizacion: 2026-01-16

---

1. RESUMEN

Metrica	Valor
Total Schemas	1 (public)
Total Tablas	21
Total ENUMs	14
Total Indices	17
Total Foreign Keys	13

---

2. SCHEMAS

2.1 Schema: public

tablas:
  # Core
  - users
  - stores
  - store_users

  # Videos e Inventario
  - videos
  - inventory_items

  # Creditos y Pagos
  - credit_balances
  - credit_packages
  - credit_transactions
  - payments

  # Sistema
  - referrals
  - notifications
  - otps
  - refresh_tokens

  # Admin
  - audit_logs
  - promotions
  - ia_providers

  # Feedback
  - corrections
  - ground_truth
  - product_submissions
  - validation_requests
  - validation_responses

---

3. TABLAS PRINCIPALES

3.1 users

tabla: "users"
schema: "public"
descripcion: "Usuarios del sistema"
columnas:
  - nombre: "id"
    tipo: "UUID"
    pk: true
  - nombre: "phone"
    tipo: "varchar(20)"
    unique: true
  - nombre: "email"
    tipo: "varchar(255)"
    unique: true
  - nombre: "passwordHash"
    tipo: "varchar(255)"
  - nombre: "name"
    tipo: "varchar(100)"
  - nombre: "businessName"
    tipo: "varchar(100)"
  - nombre: "role"
    tipo: "users_role_enum"
  - nombre: "isActive"
    tipo: "boolean"
  - nombre: "fcmToken"
    tipo: "varchar(255)"
  - nombre: "stripeCustomerId"
    tipo: "varchar(100)"
  - nombre: "createdAt"
    tipo: "timestamp"
  - nombre: "updatedAt"
    tipo: "timestamp"

3.2 stores

tabla: "stores"
schema: "public"
descripcion: "Tiendas de usuarios"
columnas:
  - nombre: "id"
    tipo: "UUID"
    pk: true
  - nombre: "ownerId"
    tipo: "UUID"
    fk: "users.id"
  - nombre: "name"
    tipo: "varchar(100)"
  - nombre: "giro"
    tipo: "varchar(50)"
  - nombre: "address"
    tipo: "varchar(255)"
  - nombre: "settings"
    tipo: "jsonb"
  - nombre: "isActive"
    tipo: "boolean"

3.3 videos

tabla: "videos"
schema: "public"
descripcion: "Videos subidos para procesamiento"
columnas:
  - nombre: "id"
    tipo: "UUID"
    pk: true
  - nombre: "storeId"
    tipo: "UUID"
    fk: "stores.id"
  - nombre: "uploadedById"
    tipo: "UUID"
    fk: "users.id"
  - nombre: "fileName"
    tipo: "varchar(255)"
  - nombre: "s3Key"
    tipo: "varchar(500)"
  - nombre: "status"
    tipo: "videos_status_enum"
  - nombre: "itemsDetected"
    tipo: "integer"
  - nombre: "creditsUsed"
    tipo: "integer"

3.4 inventory_items

tabla: "inventory_items"
schema: "public"
descripcion: "Items de inventario detectados"
columnas:
  - nombre: "id"
    tipo: "UUID"
    pk: true
  - nombre: "storeId"
    tipo: "UUID"
    fk: "stores.id"
  - nombre: "detectedByVideoId"
    tipo: "UUID"
    fk: "videos.id"
  - nombre: "name"
    tipo: "varchar(255)"
  - nombre: "category"
    tipo: "varchar(100)"
  - nombre: "quantity"
    tipo: "integer"
  - nombre: "detectionConfidence"
    tipo: "decimal(5,2)"
indices:
  - columnas: [storeId, name]
  - columnas: [storeId, category]
  - columnas: [storeId, barcode]

3.5 credit_balances

tabla: "credit_balances"
schema: "public"
descripcion: "Saldos de creditos por usuario"
columnas:
  - nombre: "id"
    tipo: "UUID"
    pk: true
  - nombre: "userId"
    tipo: "UUID"
    fk: "users.id"
    unique: true
  - nombre: "balance"
    tipo: "integer"
  - nombre: "totalPurchased"
    tipo: "integer"
  - nombre: "totalConsumed"
    tipo: "integer"
  - nombre: "totalFromReferrals"
    tipo: "integer"

3.6 payments

tabla: "payments"
schema: "public"
descripcion: "Pagos de usuarios"
columnas:
  - nombre: "id"
    tipo: "UUID"
    pk: true
  - nombre: "userId"
    tipo: "UUID"
    fk: "users.id"
  - nombre: "packageId"
    tipo: "UUID"
    fk: "credit_packages.id"
  - nombre: "amountMXN"
    tipo: "decimal(10,2)"
  - nombre: "creditsGranted"
    tipo: "integer"
  - nombre: "method"
    tipo: "payments_method_enum"
  - nombre: "status"
    tipo: "payments_status_enum"
  - nombre: "externalId"
    tipo: "varchar(255)"
indices:
  - columnas: [userId, createdAt]
  - columnas: [status, createdAt]
  - columnas: [externalId]

---

4. ENUMS

enums:
  users_role_enum:
    valores: [USER, VIEWER, MODERATOR, ADMIN, SUPER_ADMIN]

  videos_status_enum:
    valores: [PENDING, UPLOADING, UPLOADED, PROCESSING, COMPLETED, FAILED]

  store_users_role_enum:
    valores: [OWNER, OPERATOR]

  referrals_status_enum:
    valores: [PENDING, REGISTERED, QUALIFIED, REWARDED]

  payments_method_enum:
    valores: [CARD, OXXO, 7ELEVEN]

  payments_status_enum:
    valores: [PENDING, PROCESSING, COMPLETED, FAILED, REFUNDED, EXPIRED]

  notifications_type_enum:
    valores: [VIDEO_PROCESSING_COMPLETE, VIDEO_PROCESSING_FAILED, LOW_CREDITS, PAYMENT_COMPLETE, PAYMENT_FAILED, REFERRAL_BONUS, PROMO, SYSTEM]

  credit_transactions_type_enum:
    valores: [PURCHASE, CONSUMPTION, REFERRAL_BONUS, PROMO, REFUND]

  otps_purpose_enum:
    valores: [REGISTRATION, LOGIN, PASSWORD_RESET]

  corrections_type_enum:
    valores: [NAME, CATEGORY, QUANTITY, PRICE, BARCODE, IMAGE, OTHER]

  ground_truth_status_enum:
    valores: [PENDING, VERIFIED, REJECTED, NEEDS_REVIEW]

  product_submissions_status_enum:
    valores: [PENDING, APPROVED, REJECTED, NEEDS_INFO]

  promotions_type_enum:
    valores: [PERCENTAGE, FIXED_AMOUNT, CREDITS_BONUS, FREE_CREDITS]

---

5. DIAGRAMA DE RELACIONES

              users
             /  |  \
            /   |   \
       stores  credit_balances  referrals
          |         |
    store_users  credit_transactions
          |
       videos -----> inventory_items
          |              |
          +------> corrections
                       |
                  ground_truth

---

6. REFERENCIAS

• Inventario detallado: orchestration/inventarios/DATABASE_INVENTORY.yml
• Entities: Ver @PROJ_DEF_ENTITIES
• Migraciones: apps/backend/src/migrations/

---

Generado: 2026-01-16