[CONSEJO — Doc 07] Contrarian: La integración real-time entre SalesMind (POS) y StockMind (inventario) es el diferenciador técnico más importante — y también la fuente de bug más peligrosa. Una venta en el POS que descuenta del inventario StockMind incorrectamente (duplicado, no descuenta, descuenta el SKU equivocado) destruye la confianza del cliente en ambos módulos simultáneamente. First Principles: El POS en modo offline necesita garantizar que las transacciones no se pierdan aunque el dispositivo se apague. IndexedDB en el cliente + queue persistente en el servidor + reconciliación determinista al reconectar. Executor: La latencia del sync POS → StockMind debe ser <2 segundos. Si supera los 5 segundos, el cajero ve stock incorrecto en la próxima búsqueda. Usar Redis Streams para el event bus entre módulos.

1. Stack backend SalesMind

Hereda el stack de MindStack Suite (Python 3.12 + FastAPI + SQLAlchemy 2.0 + PostgreSQL 16 + Celery + Redis), con adiciones específicas para POS:

2. Arquitectura de integración con StockMind

2.1 Flujo de venta POS → StockMind

1. Cajero completa venta en POS
   │
2. SalesMind API registra la venta en sl_sales + sl_sale_items
   │
3. SalesMind publica evento en Redis Streams:
   "sale_completed" {sku_id, quantity, tenant_id, timestamp}
   │
4. StockMind consumer lee el evento y registra movimiento:
   INSERT INTO sm_stock_movements (movement_type='sale', ...)
   │
5. StockMind actualiza sm_skus.stock_current
   │
6. StockMind publica de vuelta si stock llega a punto de reorden:
   "reorder_alert" {sku_id, stock_current, reorder_point}
   │
7. SalesMind POS recibe la alerta vía WebSocket y muestra:
   "Stock de Tornillo 4" llegó al punto de reorden — OC sugerida en StockMind"

Garantías de la integración: - Exactly-once delivery: Redis Streams con ACK explícito. Si el consumer falla antes de ACK, el mensaje se reintenta. - Idempotencia: cada movimiento tiene un sale_id único que previene duplicados en caso de retry. - Timeout: si StockMind no confirma en 5s, SalesMind marca la venta como "pending_sync" y reintenta en background.

2.2 Flujo offline

POS sin internet:
1. Venta registrada en IndexedDB (browser) con status='offline'
2. Cuando hay internet: POST /sales/sync con array de ventas offline
3. Backend procesa en orden cronológico (timestamp del cliente)
4. Conflicto (mismo SKU vendido 2× offline): se acepta ambos (puede haber stock negativo temporal)
5. Stock negativo dispara alerta "Posible sobreconteo — revisar inventario físico"

3. API REST principales SalesMind

3.1 Prefijo y convenciones

Base URL: https://app.stockmind.io/api/v1/salesmind/
(Mismo dominio que StockMind, path diferente — monolito compartido)

Autenticación, paginación y manejo de errores: idéntico a StockMind (ver StockMind Doc 07 §3.1).

3.2 Endpoints principales

# POS
POST /salesmind/sales              — Registrar venta completa
POST /salesmind/sales/sync         — Sincronizar ventas offline (array)
GET  /salesmind/sales/{sale_id}    — Detalle de una venta
GET  /salesmind/sales              — Historial de ventas (paginado)

# Productos (vista POS — delegada a StockMind)
GET  /salesmind/catalog            — Catálogo SKUs con precio venta (de StockMind)
GET  /salesmind/catalog/search?q=  — Búsqueda rápida para POS (<200ms)

# CRM
GET  /salesmind/leads              — Lista de oportunidades
POST /salesmind/leads              — Crear oportunidad
PUT  /salesmind/leads/{id}         — Actualizar oportunidad (etapa, score, nota)
GET  /salesmind/leads/{id}/score   — Score del motor para esta oportunidad

# Pricing
GET  /salesmind/pricing/suggestions — Sugerencias de precio del motor (hoy)
POST /salesmind/pricing/approve/{sku_id} — Aprobar sugerencia de precio
POST /salesmind/pricing/reject/{sku_id}  — Rechazar sugerencia

# Dashboard
GET  /salesmind/dashboard/summary  — Resumen del día (ventas, pipeline, alertas)

# WebSocket
WS   /salesmind/ws/{tenant_id}     — Canal de eventos real-time al POS

3.3 Evento WebSocket al POS

// Enviado desde el servidor al POS cuando hay novedad relevante
{
  "event": "stock_alert",
  "data": {
    "sku_id": "uuid",
    "sku_name": "Tornillo 4\" zincado",
    "stock_current": 45,
    "reorder_point": 200,
    "message": "Stock llegó al punto de reorden — OC sugerida"
  }
}

{
  "event": "price_updated",
  "data": {
    "sku_id": "uuid",
    "new_price": 520,
    "currency": "CRC"
  }
}

4. Schema de base de datos SalesMind (prefix: sl_)

Tablas principales (estructura completa en Doc 08):

sl_sales                — Cabecera de ventas
sl_sale_items           — Líneas de venta (SKU, cantidad, precio)
sl_customers            — Clientes/cuentas del CRM
sl_leads                — Oportunidades del pipeline CRM
sl_lead_activities      — Actividades en cada oportunidad (llamada, demo, etc.)
sl_pricing_suggestions  — Sugerencias de precio del motor
sl_pricing_history      — Historial de precios aprobados
sl_reps                 — Representantes comerciales
sl_commissions          — Cálculo de comisiones (V1.1)

5. Workers Celery SalesMind

6. Consideraciones de seguridad específicas POS

• Las transacciones de venta son inmutables: no hay DELETE ni UPDATE en sl_sales. Si hay error, crear nota de crédito (movimiento inverso).
• El precio al momento de la venta se congela en sl_sale_items.price_at_sale — no puede cambiar retroactivamente.
• Logs de audit obligatorios para: cambio de precio, descuento manual aplicado en POS, cancelación de venta.
• El cajero no puede ver el historial de ventas de otros cajeros (RBAC a nivel de terminal POS).

Ver también: Doc 06 (SRD Frontend — interfaces que consumen estas APIs) · Doc 08 (Modelo de Datos — schema completo sl_) · Doc 09 (Motor Core — motores de pricing y scoring) · Doc 10 (Seguridad — audit trail de transacciones POS)*