From 343ff5527197ee8507dddb664992c0dbe15dfa4d Mon Sep 17 00:00:00 2001 From: rckrdmrd Date: Sat, 17 Jan 2026 04:50:04 -0600 Subject: [PATCH] =?UTF-8?q?[MCH-DOC-VAL]=20docs:=20Completar=20definicione?= =?UTF-8?q?s=20t=C3=A9cnicas=20con=20SIMCO=204.0.1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- docs/_definitions/DATABASE-SCHEMA.md | 138 +++++++++++++++++++++----- docs/_definitions/ENTITIES-CATALOG.md | 54 +++++++++- docs/_definitions/MODULES-CATALOG.md | 94 +++++++++++++++--- docs/_definitions/SERVICES-CATALOG.md | 60 ++++++++++- docs/_definitions/_INDEX.yml | 12 ++- 5 files changed, 311 insertions(+), 47 deletions(-) diff --git a/docs/_definitions/DATABASE-SCHEMA.md b/docs/_definitions/DATABASE-SCHEMA.md index 182c97bd0..d45350cd3 100644 --- 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.│ +└────────────────┘ ``` --- diff --git a/docs/_definitions/ENTITIES-CATALOG.md b/docs/_definitions/ENTITIES-CATALOG.md index 78127c00c..136827ed6 100644 --- 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] ``` --- diff --git a/docs/_definitions/MODULES-CATALOG.md b/docs/_definitions/MODULES-CATALOG.md index 3fb1ca431..fbc2f3ea1 100644 --- 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 ``` diff --git a/docs/_definitions/SERVICES-CATALOG.md b/docs/_definitions/SERVICES-CATALOG.md index 369a34510..723196368 100644 --- 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 ``` --- diff --git a/docs/_definitions/_INDEX.yml b/docs/_definitions/_INDEX.yml index 6d54080b5..3fa4862df 100644 --- 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"