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

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

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

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

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

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

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

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

```yaml
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*