Saltar a contenido

Referencia

Los contratos técnicos se generarán desde el código siempre que sea posible. OpenAPI, esquema de base de datos, variables y rutas no se mantendrán manualmente como una segunda fuente de verdad.

Superficies actuales

Superficie Dirección local Estado
API http://localhost:8050 Desplegada; auth, organizaciones e integraciones
Frontend http://localhost:3050 Desplegado; registro, login, empresa activa e integraciones
OpenAPI runtime http://localhost:8050/openapi.json Generado por FastAPI
OpenAPI versionado openapi.json Regenerado y comprobado por CI

Commerce reserva Redis DB 8. infra/core contiene el provisioning declarativo de commerce_db, sus roles owner/runtime, y commerce_connect_db, con roles separados para el session store Shopify. Los scripts de init sólo se ejecutan al crear un volumen PostgreSQL nuevo. En el volumen persistente actual se ejecutó el provisioner no destructivo; Alembic está en 0005_tenant_hardening y la migración Prisma inicial del conector está aplicada.

La zona horaria comercial es America/Bogota. Persistencia, expiración de tokens, OAuth, webhooks y correlación usan UTC; frontend/reportes convierten a hora Colombia en el borde de presentación.

Enrutamiento público

  • Host predeterminado: commerce.timeliber.com.co.
  • Servicios Docker: commerce-web, commerce-api y commerce-shopify-connect; los nombres de contenedor llevan el prefijo timeliber-commerce- para no crear aliases ambiguos en las redes compartidas.
  • Frontend: /login, /register, /dashboard, /privacy, /terms y /support.
  • Shopify embedded app: /app; se reserva para el conector y no para el dashboard TimeLiber.
  • Backend: /api, /docs y /openapi.json.
  • Variable de despliegue: COMMERCE_DOMAIN, escrita sin https://.

Contratos propuestos

El frontend consume auth, organizaciones y conexiones con credentials: include. Los tipos se generan desde OpenAPI. En DEV puede crear un código de conexión de un solo uso para pegarlo en TimeLiber Connect; el código no viaja en la URL ni se persiste en el navegador. El conector aún no está desplegado ni validado con una Development Store.

La lectura de pedidos se expone en GET /api/v1/organizations/{organization_id}/integrations/shopify/orders. Sólo acepta una sesión TimeLiber con VIEW_DATA, establece el contexto RLS, recupera la instalación del mismo tenant y pide al conector interno una proyección sin PII de los últimos 60 días. TimeLiber Connect es el único dueño del token y usa GraphQL Admin API. Código y pruebas están completos; la llamada a Shopify real sigue pendiente de una instalación DEV vinculada.

Datos