Appearance
Backlog técnico (HU del PR/FAQ)
Las 10 historias de usuario del PR/FAQ §4.2 reagrupadas por quién las construye principalmente. Bajo la hipótesis de trabajo (06-pendientes.md #1): Nilo construye el agente conversacional, nosotros las APIs/integración.
EPIC 01 — Motor de Pedidos Conversacionales (WhatsApp + IA)
Owner principal: Nilo Commerce. Nosotros proveemos los endpoints y datos.
HU-01 — Registro de pedido vía texto/voz
Como Cliente Ferretero, quiero realizar un pedido enviando un mensaje de texto o voz a WhatsApp.
| Aspecto | Detalle |
|---|---|
| Quién lo hace | NLP/ASR: Nilo. Catálogo, precios, creación de orden: nosotros. |
| Nuestros endpoints | GET /v1/catalog, GET /v1/products/{sku}/price, POST /v1/orders |
| Criterio clave | El agente debe mantener memoria de corto plazo del carrito durante la sesión (responsabilidad Nilo). |
| Infra GCP/SAP | Cloud Run (servicios catálogo/pricing/orders) + BTP iFlow → SAP SD. |
HU-08 — Venta agéntica multimodal
Como ferretero, quiero enviar fotos de mi stock o notas de voz.
| Aspecto | Detalle |
|---|---|
| Quién lo hace | Vision (foto anaquel) y ASR (voz): Nilo. Resolución a SKUs: Nilo. Nosotros = recibir SKUs ya resueltos. |
| Nuestros endpoints | Reutiliza POST /v1/orders; opcional POST /v1/internal/evidence para almacenar foto/audio en bucket si Nilo nos los envía para auditoría. |
| Criterio clave (nuestro) | Auditoría anti SIM Swapping obligatoria antes del despliegue (HU-08 permite pagos y crédito). Ver 04-cumplimiento.md. |
| Infra | Cloud Functions (webhook con evidencia) + Bucket inmutable. |
HU-09 — Pedido sugerido & upsell
Como asesor-desarrollador, quiero que la IA sugiera productos estratégicos.
| Aspecto | Detalle |
|---|---|
| Quién lo hace | Presentación al cliente: Nilo. Motor de recomendación: a definir — puede vivir del lado Nilo o ser un servicio nuestro alimentado por historial SAP. |
| Nuestros endpoints | GET /v1/recommendations?customerCode=… (si lo alojamos nosotros). |
| Criterio clave | Algoritmos basados en historial de compra (SAP) y prioridades de portafolio (input del negocio). |
| Infra | Cloud Run + posible Vertex AI / BigQuery para el modelo de recomendación si lo construimos. |
HU-10 — Asistente experto (Expertise)
Como cliente, quiero preguntar sobre garantías o funcionamiento técnico.
| Aspecto | Detalle |
|---|---|
| Quién lo hace | RAG y respuesta: Nilo. Base de conocimiento de productos: nosotros. |
| Nuestros endpoints | GET /v1/knowledge/{sku} (fichas técnicas de Tuboplus, bombas, filtros). |
| Criterio clave | 0% alucinaciones. Esto exige que nuestra base sea curada, versionada y completa. Si Nilo cita mal, puede ser por defecto de nuestra fuente. |
| Infra | Cloud Run + repositorio de fichas (BigQuery? Firestore? por definir). |
EPIC 02 — Integración Core y Liquidación Financiera (SAP + ALCOA+)
Owner principal: nosotros.
HU-03 — Sincronización automática de pedidos (ALCOA+)
Como STO, quiero que cada pedido confirmado en WhatsApp se cree automáticamente como Orden de Venta en SAP.
| Aspecto | Detalle |
|---|---|
| Endpoint dueño | POST /v1/orders — el endpoint más crítico del proyecto. |
| Criterios de aceptación | Sincroniza en <60 s P95 vía iFlow BTP. Metadatos de autoría y GPS verificados. Excepción si excede límite de crédito → alerta al asesor. |
| Implementación | Cloud Run (SvcOrders) → Application Integration → BTP iPaaS → SAP SD. Idempotencia por Idempotency-Key. |
| Riesgo | Latencia BTP. Necesario observabilidad end-to-end con tracing distribuido. |
HU-04 — Gestión de venta a público en general (RFC genérico)
Como Asesor de Campo, quiero registrar ventas a clientes no fiscales.
| Aspecto | Detalle |
|---|---|
| Endpoint dueño | POST /v1/business-partners + bandera en POST /v1/orders. |
| Criterios de aceptación | Cuando el cliente no tiene RFC, el sistema asigna automáticamente RFC XAXX010101000, régimen 616, uso CFDI S01. Detalle en 04-cumplimiento.md. |
| Implementación | SvcFiscal orquesta creación de BP vía BAPI + job batch para factura global diaria/quincenal. |
| Volumen | 50% del canal — no es caso borde. |
EPIC 03 — Orquestación Logística y POD (3PL Integration)
Owner principal: nosotros. Pregunta abierta del propio PR/FAQ: "¿Existe una aplicación en Distribución, GTM/App?" — si ya hay algo, lo reutilizamos. Ver
06-pendientes.md#8.
HU-05 — Disparo de orden de despacho
Como Jefe de Almacén, quiero que la confirmación de pago en SAP active la solicitud de transporte al partner logístico.
| Aspecto | Detalle |
|---|---|
| Trigger | Evento desde SAP (status orden = "Listo para Entrega"). |
| Acción | Orquestador emite IDoc SHPORD o API REST a DispatchTrack con datos del cliente y materiales. |
| Implementación | Orchestrator (Application Integration) escucha el evento BTP/SAP → llama a DispatchTrack. |
| Riesgo | Errores 4xx/5xx de DispatchTrack → cola de reintento con backoff. |
HU-06 — Cierre de entrega con evidencia digital (POD)
Como Director de Supply Chain, quiero que la confirmación de entrega actualice automáticamente el estatus.
| Aspecto | Detalle |
|---|---|
| Trigger | Webhook entrante de DispatchTrack con foto + firma. |
| Endpoint nuestro | POST /v1/internal/webhooks/dispatchtrack/pod |
| Acción | Validar firma del webhook → almacenar evidencia en bucket inmutable → ejecutar PGI en SAP vía BAPI BAPI_GOODSMVT_CREATE. |
| Implementación | Cloud Function (webhook receiver) → SvcOrders → Application Integration → BTP. |
| Criterio | OTIF 98% medido sobre estos webhooks. |
HU "anchor" sin EPIC asignado en el PR/FAQ
HU-02 — Consulta de estatus de entrega (self-service)
Como Cliente, quiero preguntar por el estatus de mi pedido en WhatsApp.
| Aspecto | Detalle |
|---|---|
| Endpoint dueño | GET /v1/orders/{id}/status (proxy a DispatchTrack). |
| Criterio | Devuelve ETA + ubicación del vehículo + URL de mapa interactivo. |
| Implementación | SvcOrders cachea status con TTL corto; al hit del agente, refresca contra DispatchTrack si está obsoleto. |
| Infra | Cloud Run + Cloud Memorystore (Redis) para caché. |
HU-07 — Registro ágil SAP
Como cliente, quiero registrarme una sola vez con mi código SAP o SSO.
| Aspecto | Detalle |
|---|---|
| Endpoint dueño | GET /v1/customers?bsuid={bsuid} o ?phone={e164} + vínculo persistente. |
| Criterio | Un mismo cliente (identificado por BSUID estable, con teléfono opcional) puede gestionar múltiples códigos de cliente / sucursales. El vínculo se hace una sola vez y se mantiene aunque el usuario adopte username y oculte su número. |
| Implementación | Tabla customer_identifier_link (Cloud SQL): columnas bsuid (PK lógica para WhatsApp), phone_e164 (nullable), customer_code_sap, created_at. Validación contra SAP MDM al primer registro. Cosido oportunista: cuando llega BSUID nuevo con teléfono ya conocido, se actualiza el registro existente. |
| Riesgo | Cambio de número (SIM Swapping) + usuarios con username que ocultan teléfono — ver 04-cumplimiento.md § Privacidad de identificadores y § Anti SIM-swapping. |
Post-MVP (épicas 05–07)
| Épica | Idea | Implicación para nosotros |
|---|---|---|
| 05 — Empoderamiento de Campo | El asesor tiene insights SAP en la mano; tiempo de toma de pedido -40%. | Backend móvil del asesor: APIs de ruta, cobranza, cuotas. |
| 06 — Autogestión Agéntica | 20% de pedidos sin intervención humana. | Robustecer SLA y observabilidad de las APIs HU-01/03. |
| 07 — Inteligencia Logística | Visibilidad total + POD para el cliente. | Push notifications / webhooks salientes a Nilo. |
Roadmap visible
| Fase | Dueño técnico | Hitos |
|---|---|---|
| 1 — Fix the Basics | Equipo SAP + nosotros | Setup War Room. Data Sanity (limpieza maestros, geocercas Texcoco). Auditoría VB6. |
| 2 — MVP Texcoco | Nosotros + Nilo | Despliegue agente Nilo + nuestras APIs en producción para 3 asesores. Integración 3PL con POD. Latencia SAP <60 s. Adopción 10% al mes 3. |
| 3 — Escalamiento | Nosotros + Nilo + 3PL | Migración a Chalco. Activación motor de recomendación (HU-09). Comisiones híbridas. |
Definition of Done genérico (propuesta)
Para cualquier HU dueña nuestra, el "Done" mínimo:
- [ ] Endpoint con OpenAPI publicado y validado por Nilo.
- [ ] Pruebas unitarias + de contrato + de integración (con stub de SAP).
- [ ] Idempotencia probada en escenarios de retry.
- [ ] Audit log emitiendo con metadatos ALCOA+.
- [ ] Tracing distribuido visible en Cloud Logging.
- [ ] Dashboard de SLA configurado.
- [ ] Runbook para War Room en caso de incidente.
- [ ] (HU con dinero) Auditoría de ciberseguridad firmada.