TimeLiber Commerce — Product Requirements Document

Estado: Activo — fundación y aprendizaje técnico
Versión: 0.1
Fecha: 2026-08-31
Owner: Por asignar

Este documento es la fuente canónica del alcance. Las decisiones técnicas viven en ADRs y el estado del sprint en .agent/context/tasks_active.md.

1. Propósito de esta etapa

TimeLiber Commerce comienza como una vertical de aprendizaje e infraestructura comercial. Su primera meta no es lanzar una suite omnicanal ni demostrar todavía product-market fit, sino dominar mediante una implementación real y segura:

• aplicaciones públicas de Shopify;
• instalación y autorización OAuth;
• scopes y acceso a datos protegidos;
• webhooks y lifecycle de una conexión;
• sincronización idempotente;
• separación multi-tenant;
• trabajos durables y observables;
• contratos que permitan añadir canales posteriores.

El resultado debe ser una base técnicamente correcta que conserve valor aunque el segmento o el producto comercial cambien.

2. Distinciones de estado

Estado	Significado
Aprendido	El comportamiento oficial fue investigado, recorrido y documentado.
Implementado	Existe código ejecutable para la capacidad.
Cubierto automáticamente	Existen pruebas; no demuestra conexión con el proveedor real.
Validado real	El journey se ejecutó contra Shopify real y quedó evidencia sin secretos.
Producto probado	Un comercio obtiene valor repetido y demuestra disposición de pago.

Ningún estado implica automáticamente el siguiente.

3. Problema estratégico

Los comercios operan conversaciones, catálogo, pedidos, pagos y entregas en sistemas desconectados. La hipótesis comercial es que una capa neutral y auditada puede reducir transcripción, demoras y pérdida de contexto, especialmente en operaciones que usan WhatsApp.

Esta hipótesis no se considera demostrada durante la fase fundacional.

4. Usuarios iniciales

Usuario técnico inmediato

El equipo que debe aprender a construir, asegurar y operar conexiones comerciales oficiales dentro de TimeLiber.

Usuario comercial hipotético

Comercios colombianos con Shopify, operación activa por WhatsApp y suficiente volumen para que las consultas de catálogo o pedidos consuman trabajo diario.

Hipótesis alternativa

Distribuidores B2B que reciben pedidos repetitivos por WhatsApp y los transcriben a ERP u hojas de cálculo.

5. Job inicial

Cuando una tienda instala la aplicación, necesita autorizarla sin compartir credenciales y verificar que los pedidos importados coinciden con Shopify, para confiar en la base antes de automatizar cualquier operación.

6. Objetivos de la fundación

• Crear la vertical conforme a los estándares TimeLiber.
• Evaluar y trasplantar selectivamente la ingeniería útil de PulseCommerce.
• Instalar una aplicación real en una Shopify Development Store.
• Solicitar inicialmente el mínimo scope necesario.
• Sincronizar pedidos de forma idempotente y conciliable.
• Procesar desinstalación, cambios de scopes y privacidad.
• Probar aislamiento tenant sobre PostgreSQL real.
• Documentar fallos, restricciones y decisiones aprendidas.

7. Fuera de alcance de la fundación

• Construir una tienda o reemplazar Shopify.
• Meta, Instagram, Mercado Libre o WooCommerce productivos.
• Agentes conversacionales productivos.
• Pagos, descuentos, devoluciones o cambios autónomos.
• Analítica predictiva y atribución avanzada.
• Billing y definición definitiva de precios.
• Prometer ahorros, conversiones o capacidades no medidas.

8. Requisitos funcionales iniciales

ID	Requisito	Gate
COM-AUTH-001	Crear sesión segura y organización activa.	Tests de auth y membresía.
COM-TENANT-001	Aislar datos por tenant_id con RLS.	Casos cross-tenant sobre PostgreSQL real.
COM-SHOP-001	Iniciar e instalar Shopify mediante el mecanismo oficial vigente.	Recorrido en Development Store.
COM-SHOP-002	Validar HMAC, antigüedad, estado de un uso y hostname.	Pruebas positivas y negativas.
COM-SHOP-003	Cifrar tokens y nunca serializarlos.	Revisión de schemas, logs y base.
COM-SHOP-004	Sincronizar pedidos sin duplicarlos.	Reintentos producen el mismo estado.
COM-SHOP-005	Mostrar datos conciliables por número, moneda, total y líneas.	Comparación campo por campo con Shopify real.
COM-WEBHOOK-001	Verificar, persistir y deduplicar webhooks antes de procesarlos.	Prueba de reintento y reinicio.
COM-LIFE-001	Desinstalar o cambiar scopes invalida el uso del token.	Delivery real o limitación documentada.

9. Requisitos no funcionales

• UUIDs nativos, SQLAlchemy 2.0 con select() y borrado lógico donde corresponda.
• Runtime PostgreSQL sin SUPERUSER ni BYPASSRLS; migraciones con rol separado.
• Scopes mínimos y secretos gestionados sólo mediante configuración segura.
• Logs estructurados sin tokens ni información personal innecesaria.
• Idempotency keys y receipts para efectos externos.
• Health checks, métricas y correlación de OAuth, webhooks y jobs.
• Toda acción futura de agente tendrá policy engine, auditoría y kill switch.

10. Gates de avance

Gate F1 — Base segura

• Auth, organizaciones y RLS pasan pruebas.
• La aplicación levanta sobre la infraestructura TimeLiber.
• No hay secretos ni dependencias directas entre verticales.

Gate F2 — Shopify real

• Instalación completa en una Development Store.
• Al menos un pedido se sincroniza y concilia.
• El recorrido se puede repetir desde cero.

Gate F3 — Aprendizaje suficiente

• Restricciones y fallos están documentados.
• Existe una matriz honesta de piezas reutilizadas y reescritas.
• El equipo puede explicar OAuth, tokens, scopes, webhooks e idempotencia sin depender del chat.

Gate F4 — Producto

Sólo después de F1–F3 se prueba un flujo con comercios. La construcción de WhatsApp o nuevos canales dependerá de esa evidencia, no de la posibilidad técnica.

11. Métricas de la etapa

• Cero accesos cross-tenant.
• Cero secretos expuestos.
• 100% de pedidos de la muestra conciliados por moneda, total y líneas.
• Reintentos sin duplicación.
• Instalación y desinstalación reproducibles.
• Tiempo y fallos del journey documentados.

Estas métricas validan ingeniería; no prueban product-market fit.