ProfitClaw AI — API

1. Concepto

MVP B2B SaaS para tiendas e-commerce pequeñas/medianas (Shopify, WooCommerce, BigCommerce). Tres agentes de IA actúan sobre eventos en tiempo real del frontend de la tienda para recuperar ventas perdidas (carritos abandonados), aumentar el ticket promedio (upsell/cross-sell) y elevar la conversión en checkout (descuento dinámico). Un dashboard atribuye ingreso recuperado, AOV y aumento de conversión a cada agente — la métrica que justifica el precio del SaaS.

2. Arquitectura

Frontend tienda (snippet JS) ──HTTP──> /api/v1/track/**  (público, autenticado por API key de tienda)
                                              │
                                     AgentDecisionService ──Feign──> LlmClient (texto persuasivo)
                                              │
                                     ProductCatalogRepository / PerformanceMetricsRepository (JPA/PostgreSQL)

Panel dueño de tienda ──JWT──> /api/v1/stores/**, /api/v1/agents/**, /api/v1/dashboard/**

Shopify ──webhook──> /api/v1/webhooks/shopify/orders
Shopify Admin API <──Feign── ProductCatalogService (sync catálogo)

Capas: %%INLINE0%% → %%INLINE1%% → %%INLINE2%% → %%INLINE3%% (entidades JPA), dto (Records inmutables), %%INLINE5%% (Feign: Shopify Admin API + LLM), %%INLINE6%% (JWT), config (Feign, Security, Jackson pre-escrito).

Nota de diseño: las entidades JPA (%%INLINE8%%, %%INLINE9%%, AgentConfiguration, PerformanceMetrics) se implementaron como clases mutables, no Records, porque Hibernate requiere constructor sin argumentos y setters para el ciclo de vida de la entidad/dirty-checking. Los DTOs sí son Records inmutables, conforme a la guía de estilo.

3. Endpoints

Públicos

• POST /api/v1/auth/register — alta de tienda + dueño, devuelve JWT + API key de tracking.
• POST /api/v1/auth/login — login, devuelve JWT.
• %%INLINE14%% — Agente de Upsell/Cross-sell (body: %%INLINE15%%, carrito) → mensaje + productos sugeridos.
• POST /api/v1/track/cart-abandoned — Agente de Recuperación de Carrito Abandonado → email/SMS + código de descuento.
• POST /api/v1/track/checkout-hesitation — Agente de Descuento Dinámico → aprueba/niega descuento en tiempo real.
• %%INLINE18%% — webhook %%INLINE19%% de Shopify.

Protegidos (JWT Authorization: Bearer <token>)

• GET /api/v1/stores/me — datos de la tienda autenticada.
• %%INLINE22%% / %%INLINE23%% — listar/activar-configurar agentes.
• GET /api/v1/dashboard — Dashboard de Rendimiento (ingreso recuperado, ΔconversiÓn, AOV, ingreso por upsell).

4. Referencias técnicas

• Spring Boot 4.0.4 / Spring Framework 7 / Java 25.
• Jackson 3 (%%INLINE25%%) vía %%INLINE26%% pre-escrito.
• Spring Security con %%INLINE27%% (stateless) + %%INLINE28%% 0.12.6 (API fluida Jwts.builder()...signWith(key)).
• Spring Cloud OpenFeign 4.2.1: %%INLINE30%% (Admin API) y %%INLINE31%% (chat completions), habilitados vía %%INLINE32%% en %%INLINE33%% (no se tocó la clase *Application).
• PostgreSQL vía %%INLINE35%% (configurar %%INLINE36%% en despliegue; application.yml base ya provisto).
• Snippet cliente: %%INLINE38%%, referenciado en %%INLINE39%% punto 7.

5. Análisis de negocio

• Problema: hasta 70% de carritos abandonados en e-commerce PyME sin recursos para IA personalizada.
• Propuesta de valor: ROI medible y directo (ingreso recuperado, AOV, conversión) — vendible a dueños no técnicos.
• Monetización: suscripción por niveles según volumen de pedidos mensuales, o % del ingreso adicional generado — el Dashboard de Rendimiento es la pieza que sostiene ese pricing (evidencia de valor entregado).
• Diferenciador vs. infraestructura pura (Ollama, CrewAI): producto final con impacto directo en ingresos del cliente, reduce churn.

6. Cómo ejecutar

# Requiere PostgreSQL corriendo y configurado en application.yml (spring.datasource.*)
mvn clean spring-boot:run

Variables de entorno relevantes (todas con default de desarrollo, sobreescribir en producción):

• %%INLINE40%%, %%INLINE41%%
• %%INLINE42%%, %%INLINE43%%, llm.model
• shopify.api.url

Flujo de prueba rápido:

1. %%INLINE46%% → obtener %%INLINE47%% y token.
2. %%INLINE49%% con el %%INLINE50%% → mensaje de recuperación generado.
3. %%INLINE51%% con %%INLINE52%% → ver métrica acumulada.