[MCH-DOC-VAL] docs: Completar definiciones técnicas con SIMCO 4.0.1

Actualiza catálogos de definiciones técnicas con nuevos módulos, servicios, entidades y esquemas de base de datos. Cambios por archivo: DATABASE-SCHEMA.md (+138 líneas): - Agregado simco_version: 4.0.1 - Schemas: 12 -> 15 (ai, onboarding, predictions) - Tablas: ~49 -> ~65 - Nuevas tablas documentadas: conversations, inventory_predictions - Diagrama de relaciones actualizado ENTITIES-CATALOG.md (+54 líneas): - Agregado simco_version: 4.0.1 - Entities: 25 -> 35+ - Nuevos módulos: AI/MCP, Predictions, Onboarding, Notifications - Relaciones actualizadas para nuevas entidades MODULES-CATALOG.md (+94 líneas): - Agregado simco_version: 4.0.1 - Módulos: 18 -> 24 - Agregados: MCH-M19 a MCH-M24 (Offline, Referrals, CoDi, Widgets, i18n, SAT) - Detalles completos de MCH-M10 (Predictions) y MCH-M11 (MCP Server) - Matriz de dependencias expandida SERVICES-CATALOG.md (+60 líneas): - Agregado simco_version: 4.0.1 - Services: 18+ -> 30+ - Nuevos módulos: MCP Server, Predictions, Onboarding, Notifications - Inyección de dependencias actualizada _INDEX.yml: - version: 1.0.0 -> 1.1.0 - Totales actualizados (entities: 35, services: 30, modules: 24) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-17 04:50:04 -06:00 · 2026-01-17 04:50:04 -06:00 · 343ff55271
commit 343ff55271
parent 15852f2d6a
5 changed files with 311 additions and 47 deletions
--- a/docs/_definitions/DATABASE-SCHEMA.md
+++ b/docs/_definitions/DATABASE-SCHEMA.md
@ -1,8 +1,16 @@
+---
+id: DEF-MCH-DB
+type: Definition
+title: "Database Schema"
+simco_version: "4.0.1"
+updated_at: 2026-01-17
+---
+
 # Database Schema - MiChangarrito

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

 ---

@ -10,11 +18,11 @@

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

 ---

@ -142,6 +150,36 @@ tablas:
  - predictions
 ```

+### 2.13 Schema: ai
+
+```yaml
+descripcion: "Asistente IA y MCP Server"
+tablas:
+  - conversations
+  - messages
+  - tool_calls
+```
+
+### 2.14 Schema: onboarding
+
+```yaml
+descripcion: "Flujo de configuracion inicial"
+tablas:
+  - sessions
+  - product_templates
+  - template_imports
+```
+
+### 2.15 Schema: predictions
+
+```yaml
+descripcion: "Predicciones de inventario"
+tablas:
+  - inventory_predictions
+  - reorder_suggestions
+  - demand_history
+```
+
 ---

 ## 3. TABLAS PRINCIPALES
@ -252,6 +290,55 @@ columnas:
    tipo: "TIMESTAMP"
 ```

+### 3.5 conversations (ai)
+
+```yaml
+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
+
+```yaml
+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
@ -261,23 +348,28 @@ columnas:
                    │   users     │
                    └──────┬──────┘
                           │ 1:N
-              ┌────────────┴────────────┐
-              │                         │
-       ┌──────▼──────┐          ┌───────▼──────┐
-       │   stores    │          │ subscriptions│
-       └──────┬──────┘          └──────────────┘
-              │ 1:N
-    ┌─────────┼─────────┬─────────────┐
-    │         │         │             │
-┌───▼───┐ ┌───▼───┐ ┌───▼───┐   ┌─────▼─────┐
-│products│ │ sales │ │orders │   │ customers │
-└───┬───┘ └───┬───┘ └───┬───┘   └─────┬─────┘
-    │         │         │             │
-    └─────────┴─────────┴─────────────┘
-                      │
-              ┌───────▼───────┐
-              │    fiados     │
-              └───────────────┘
+              ┌────────────┼────────────┐
+              │            │            │
+       ┌──────▼──────┐  ┌──▼──┐  ┌──────▼───────┐
+       │   stores    │  │ ai. │  │ subscriptions│
+       └──────┬──────┘  │conv.│  └──────────────┘
+              │ 1:N     └──┬──┘
+    ┌─────────┼─────────┬──┴────────┐
+    │         │         │           │
+┌───▼───┐ ┌───▼───┐ ┌───▼───┐ ┌─────▼─────┐
+│products│ │ sales │ │orders │ │ customers │
+└───┬───┘ └───┬───┘ └───┬───┘ └─────┬─────┘
+    │         │         │           │
+    │    └────┴─────────┴───────────┘
+    │                  │
+    │          ┌───────▼───────┐
+    │          │    fiados     │
+    │          └───────────────┘
+    │
+┌───▼────────────┐
+│ predictions.   │
+│ inventory_pred.│
+└────────────────┘
 ```

 ---
--- a/docs/_definitions/ENTITIES-CATALOG.md
+++ b/docs/_definitions/ENTITIES-CATALOG.md
@ -1,8 +1,16 @@
+---
+id: DEF-MCH-ENTITIES
+type: Definition
+title: "Entities Catalog"
+simco_version: "4.0.1"
+updated_at: 2026-01-17
+---
+
 # Entities Catalog - MiChangarrito

 **Alias:** @MCH_DEF_ENTITIES
 **Version:** 1.0.0
-**Ultima actualizacion:** 2026-01-16
+**Ultima actualizacion:** 2026-01-17

 ---

@ -10,7 +18,7 @@

 | Metrica | Valor |
 |---------|-------|
-| **Total Entities** | 25 |
+| **Total Entities** | 35+ |
 | **Por Modulo** | Ver seccion 2 |

 ---
@ -93,6 +101,36 @@
 | TokenPackage | `token-package.entity.ts` | token_packages | Paquetes de tokens |
 | TokenUsage | `token-usage.entity.ts` | token_usage | Uso de tokens IA |

+### 2.11 Modulo: AI/MCP
+
+| Entity | Archivo | Tabla BD | Descripcion |
+|--------|---------|----------|-------------|
+| Conversation | `conversation.entity.ts` | ai.conversations | Conversaciones con LLM |
+| Message | `message.entity.ts` | ai.messages | Mensajes de conversacion |
+| ToolCall | `tool-call.entity.ts` | ai.tool_calls | Llamadas a tools MCP |
+
+### 2.12 Modulo: Predictions
+
+| Entity | Archivo | Tabla BD | Descripcion |
+|--------|---------|----------|-------------|
+| InventoryPrediction | `inventory-prediction.entity.ts` | predictions.inventory_predictions | Cache de predicciones |
+| ReorderSuggestion | `reorder-suggestion.entity.ts` | predictions.reorder_suggestions | Sugerencias de compra |
+
+### 2.13 Modulo: Onboarding
+
+| Entity | Archivo | Tabla BD | Descripcion |
+|--------|---------|----------|-------------|
+| OnboardingSession | `onboarding-session.entity.ts` | onboarding.sessions | Sesiones de onboarding |
+| ProductTemplate | `product-template.entity.ts` | templates.product_templates | Templates de productos |
+
+### 2.14 Modulo: Notifications
+
+| Entity | Archivo | Tabla BD | Descripcion |
+|--------|---------|----------|-------------|
+| Notification | `notification.entity.ts` | notifications.notifications | Notificaciones del sistema |
+| NotificationTemplate | `notification-template.entity.ts` | notifications.templates | Templates de notificacion |
+| PushToken | `push-token.entity.ts` | notifications.push_tokens | Tokens FCM de dispositivos |
+
 ---

 ## 3. RELACIONES ENTRE ENTITIES
@ -126,6 +164,18 @@ relaciones:
  Fiado:
    has_many: [FiadoPayment]
    belongs_to: [Store, Customer]
+
+  Conversation:
+    has_many: [Message, ToolCall]
+    belongs_to: [Store, User]
+
+  OnboardingSession:
+    has_many: []
+    belongs_to: [Store]
+
+  Notification:
+    has_many: []
+    belongs_to: [Store, User]
 ```

 ---
--- a/docs/_definitions/MODULES-CATALOG.md
+++ b/docs/_definitions/MODULES-CATALOG.md
@ -1,8 +1,16 @@
+---
+id: DEF-MCH-MODULES
+type: Definition
+title: "Modules Catalog"
+simco_version: "4.0.1"
+updated_at: 2026-01-17
+---
+
 # Modules Catalog - MiChangarrito

 **Alias:** @MCH_DEF_MODULES
 **Version:** 1.0.0
-**Ultima actualizacion:** 2026-01-16
+**Ultima actualizacion:** 2026-01-17

 ---

@ -10,8 +18,8 @@

 | Metrica | Valor |
 |---------|-------|
-| **Total Modulos** | 18 |
-| **En Produccion** | 18 |
+| **Total Modulos** | 24 |
+| **En Produccion** | 24 |
 | **En Desarrollo** | 0 |

 ---
@ -40,6 +48,7 @@
 | MCH-M11 | MCP Server | Produccion | MCH-010 |
 | MCH-M12 | WhatsApp | Produccion | MCH-011 |
 | MCH-M13 | LLM Chat | Produccion | MCH-012/013 |
+| MCH-M13a | Analytics | Produccion | MCH-016 |

 ### 2.3 Modulos Negocio (Fase 4-5)

@ -50,6 +59,12 @@
 | MCH-M16 | Deliveries | Produccion | MCH-016 |
 | MCH-M17 | Notifications | Produccion | MCH-017 |
 | MCH-M18 | Subscriptions | Produccion | MCH-018/019/020 |
+| MCH-M19 | Offline | Produccion | MCH-022 |
+| MCH-M20 | Referrals | Produccion | MCH-023 |
+| MCH-M21 | CoDi/SPEI | Produccion | MCH-024 |
+| MCH-M22 | Widgets | Produccion | MCH-025 |
+| MCH-M23 | i18n | Produccion | MCH-026 |
+| MCH-M24 | SAT/Facturacion | Produccion | MCH-027 |

 ---

@ -126,23 +141,72 @@ modulo:
    externos: []
 ```

+### MCH-M10: Predictions
+
+```yaml
+modulo:
+  id: "MCH-M10"
+  nombre: "Predictions"
+  estado: "produccion"
+  version: "1.0.0"
+
+  documentacion:
+    especificacion: "docs/01-epicas/MCH-009-prediccion-inventario.md"
+
+  objetos:
+    tablas: ["inventory_predictions", "reorder_suggestions"]
+    entities: ["InventoryPrediction", "ReorderSuggestion"]
+    services: ["PredictionsService", "ReorderService", "AlertsService"]
+    controllers: ["PredictionsController"]
+
+  dependencias:
+    modulos: ["MCH-M04", "MCH-M05"]
+    externos: []
+```
+
+### MCH-M11: MCP Server
+
+```yaml
+modulo:
+  id: "MCH-M11"
+  nombre: "MCP Server"
+  estado: "produccion"
+  version: "1.0.0"
+
+  documentacion:
+    especificacion: "docs/01-epicas/MCH-010-mcp-server.md"
+    requerimientos: ["RF-MCP-001", "RF-MCP-002"]
+
+  objetos:
+    tablas: ["conversations", "messages", "tool_calls"]
+    entities: ["Conversation", "Message", "ToolCall"]
+    services: ["MCPService", "ToolsService", "ConversationsService"]
+    controllers: ["MCPController"]
+
+  dependencias:
+    modulos: ["MCH-M04", "MCH-M05", "MCH-M09", "MCH-M14"]
+    externos: ["openrouter", "@anthropic-ai/sdk"]
+```
+
 ---

 ## 4. MATRIZ DE DEPENDENCIAS

 ```
-┌──────────┬──────┬──────┬──────┬──────┬──────┬──────┐
-│          │ Auth │ User │Store │ Prod │ Sale │ Cust │
-├──────────┼──────┼──────┼──────┼──────┼──────┼──────┤
-│ Auth     │  -   │  ->  │      │      │      │      │
-│ Users    │  <-  │  -   │  ->  │      │      │      │
-│ Stores   │      │  <-  │  -   │  ->  │  ->  │  ->  │
-│ Products │      │      │  <-  │  -   │      │      │
-│ Sales    │      │      │  <-  │  <-  │  -   │  <-  │
-│ Customers│      │      │  <-  │      │  ->  │  -   │
-│ Fiados   │      │      │      │      │  <-  │  <-  │
-│ Orders   │      │      │  <-  │  <-  │      │  <-  │
-└──────────┴──────┴──────┴──────┴──────┴──────┴──────┘
+┌────────────┬──────┬──────┬──────┬──────┬──────┬──────┬──────┬──────┐
+│            │ Auth │ User │Store │ Prod │ Sale │ Cust │ Pred │ MCP  │
+├────────────┼──────┼──────┼──────┼──────┼──────┼──────┼──────┼──────┤
+│ Auth       │  -   │  ->  │      │      │      │      │      │      │
+│ Users      │  <-  │  -   │  ->  │      │      │      │      │      │
+│ Stores     │      │  <-  │  -   │  ->  │  ->  │  ->  │      │      │
+│ Products   │      │      │  <-  │  -   │      │      │  ->  │  ->  │
+│ Sales      │      │      │  <-  │  <-  │  -   │  <-  │  ->  │  ->  │
+│ Customers  │      │      │  <-  │      │  ->  │  -   │      │  ->  │
+│ Fiados     │      │      │      │      │  <-  │  <-  │      │  ->  │
+│ Orders     │      │      │  <-  │  <-  │      │  <-  │      │      │
+│ Predictions│      │      │      │  <-  │  <-  │      │  -   │      │
+│ MCP        │      │      │      │  <-  │  <-  │  <-  │      │  -   │
+└────────────┴──────┴──────┴──────┴──────┴──────┴──────┴──────┴──────┘

 Leyenda: -> depende de, <- es dependido por
 ```
--- a/docs/_definitions/SERVICES-CATALOG.md
+++ b/docs/_definitions/SERVICES-CATALOG.md
@ -1,8 +1,16 @@
+---
+id: DEF-MCH-SERVICES
+type: Definition
+title: "Services Catalog"
+simco_version: "4.0.1"
+updated_at: 2026-01-17
+---
+
 # Services Catalog - MiChangarrito

 **Alias:** @MCH_DEF_SERVICES
 **Version:** 1.0.0
-**Ultima actualizacion:** 2026-01-16
+**Ultima actualizacion:** 2026-01-17

 ---

@ -10,7 +18,7 @@

 | Metrica | Valor |
 |---------|-------|
-| **Total Services** | 18+ |
+| **Total Services** | 30+ |
 | **Por Modulo** | Ver seccion 2 |

 ---
@ -90,6 +98,38 @@
 | LLMService | `llm.service.ts` | HttpService, ConfigService | Integracion OpenRouter |
 | StripeService | `stripe.service.ts` | Stripe SDK | Integracion Stripe |

+### 2.11 Modulo: MCP Server
+
+| Service | Archivo | Dependencias | Descripcion |
+|---------|---------|--------------|-------------|
+| MCPService | `mcp.service.ts` | LLMService, ToolsRegistry | Gateway LLM agnostico |
+| ToolsService | `tools.service.ts` | ProductsService, SalesService | Ejecutor de tools MCP |
+| ConversationsService | `conversations.service.ts` | Repository | Gestion de conversaciones IA |
+
+### 2.12 Modulo: Predictions
+
+| Service | Archivo | Dependencias | Descripcion |
+|---------|---------|--------------|-------------|
+| PredictionsService | `predictions.service.ts` | Repository, SalesService | Prediccion de demanda |
+| ReorderService | `reorder.service.ts` | Repository, InventoryService | Sugerencias de reorden |
+| AlertsService | `alerts.service.ts` | Repository, NotificationsService | Alertas de stock bajo |
+
+### 2.13 Modulo: Onboarding
+
+| Service | Archivo | Dependencias | Descripcion |
+|---------|---------|--------------|-------------|
+| OnboardingService | `onboarding.service.ts` | Repository, WhatsAppService | Flujo de onboarding |
+| OCRService | `ocr.service.ts` | GoogleVisionClient | Procesamiento de imagenes |
+| TranscriptionService | `transcription.service.ts` | WhisperClient | Transcripcion de audio |
+
+### 2.14 Modulo: Notifications
+
+| Service | Archivo | Dependencias | Descripcion |
+|---------|---------|--------------|-------------|
+| NotificationsService | `notifications.service.ts` | Repository, FCMService | Gestion de notificaciones |
+| FCMService | `fcm.service.ts` | Firebase Admin | Push notifications |
+| EmailService | `email.service.ts` | SendGridClient | Envio de emails |
+
 ---

 ## 3. INYECCION DE DEPENDENCIAS
@ -131,6 +171,22 @@ dependencias:
      - WhatsAppController
      - OrdersService
      - NotificationsService
+
+  MCPService:
+    inyecta:
+      - LLMService
+      - ToolsService
+    inyectado_en:
+      - WhatsAppService
+      - ChatController
+
+  PredictionsService:
+    inyecta:
+      - SalesService
+      - InventoryService
+    inyectado_en:
+      - MCPService
+      - ReportsController
 ```

 ---
--- a/docs/_definitions/_INDEX.yml
+++ b/docs/_definitions/_INDEX.yml
@ -2,9 +2,11 @@
 # Proyecto: michangarrito
 # Fecha: 2026-01-16

-version: "1.0.0"
+version: "1.1.0"
+simco_version: "4.0.1"
 proyecto: "michangarrito"
 fecha_creacion: "2026-01-16"
+fecha_actualizacion: "2026-01-17"
 descripcion: "Definiciones canonicas del proyecto MiChangarrito"

 # ============================================================================
@ -44,19 +46,19 @@ definiciones_locales:
    archivo: "ENTITIES-CATALOG.md"
    alias: "@MCH_DEF_ENTITIES"
    descripcion: "Catalogo de entidades del proyecto"
-    total_entities: 25
+    total_entities: 35

  services:
    archivo: "SERVICES-CATALOG.md"
    alias: "@MCH_DEF_SERVICES"
    descripcion: "Catalogo de servicios del proyecto"
-    total_services: 18
+    total_services: 30

  modules:
    archivo: "MODULES-CATALOG.md"
    alias: "@MCH_DEF_MODULES"
    descripcion: "Catalogo de modulos del proyecto"
-    total_modules: 18
+    total_modules: 24

 # ============================================================================
 # HERENCIA (Proyecto Independiente)
@ -72,4 +74,4 @@ herencia:
 estadisticas:
  total_definiciones: 4
  total_referencias_ws: 6
-  ultima_actualizacion: "2026-01-16"
+  ultima_actualizacion: "2026-01-17"