Memoria técnica del proyecto

Producto: Uber Truck — marketplace de capacidad logística ociosa (backhaul), Chile.
Documento: memoria técnica viva del repositorio y del despliegue Railway.
Versión documento: 4.4  |  Software: 0.0.129 (Cubik app móvil + API Railway)  |  Fecha: 25 may 2026  |  Backlog/Gantt: vivo — revisar semanalmente

← Documentación · Inicio app · Producción: uber-truck-production.up.railway.app · Probar (testers): /probar

Propósito y forma de mantenimiento

Este archivo es la referencia única de arquitectura, hitos, cronograma Gantt, próximos pasos y stack por capas. Actualizarlo cuando cambien migraciones Supabase, rutas API, reglas de cancelación/multas o el avance real frente al plan.

Formato Word: en la raíz del repo ejecutar npm run export:memoria-docx → docs/Memoria-tecnica-Uber-Truck.docx y copia en Downloads/Proyecto Uber Truck/. Pack completo: npm run export:all-docs.

Visión de producto

MVP final = una sola app web con funcionamiento lo más parecido posible a Uber (pedir → emparejar → viaje en curso → chat → cancelar → cuenta), adaptado a carga por camión. El usuario ya sabe usar Uber; la curva de aprendizaje debe ser mínima.

Objetivo comercial: ganar usuarios y viajes reales con esta app propia. Objetivo estratégico a futuro: demostrar tracción y ofrecer el producto como add-on / integración a plataformas grandes (ej. marketplace logístico o apps de movilidad), no reemplazarlas desde el día uno.

Descartado para el MVP: piloto paralelo con WhatsApp + Airtable fuera de la app. Todo el piloto y la operación van dentro de Uber Truck.

Resumen ejecutivo del stack

Embarcadores y transportistas usan la misma app (public/): publicar demanda u oferta, ver sugerencias de match, aceptar, seguir estados, chatear, cancelar y revisar multas/cuenta. Backend Node.js 20 + Express 4, datos en Supabase, auth JWT, deploy Railway, código en GitHub.

Principio de producto

Priorizar paridad de flujo Uber y usuarios activos en la app antes que integraciones B2B o Open Finance. Pagos in-app y mapa en vivo entran cuando el flujo base ya se usa sin fricción.

Paridad UX — Uber vs Uber Truck (MVP final)

Resumen may 2026: el MVP final de flujo está cerrado en producción (v0.0.129). Post-MVP ítems FCM y contraseña fuerte cerrados; recuperar clave con código listo pero bloqueado para multi-cuenta piloto hasta dominio Resend (ver DOMAIN-AND-EMAIL.md). Canvas plan: canvases/cubik-plan-native-escala.canvas.tsx.

MVP final — flujos core (cerrados)

Post-MVP — no bloquea demo ni piloto 25/50

Validar en orden: Checklist interactivo Post-MVP · Guía MD · API GET /api/post-mvp/status

Parte I — Hitos del proyecto

Fase 0 — Descubrimiento y legal

Objetivo

Entrevistas en nodo industrial (San Bernardo / RM), validación de precio/comisión y borrador legal + seguro piloto.

Estado (jun 2026)

En curso — paralelo al MVP digital ya desplegado y demo comercial.

Fase 1 — MVP final app tipo Uber (producto único)

Objetivo

Cerrar la paridad de flujo en la misma app: mis viajes por cuenta, copy y pasos al estilo Uber, piloto con 20 viajes reales hechos 100% en la plataforma (hito M2).

Estado jun 2026

MVP flujo cerrado (v0.0.129). Pendiente operacional: dominio/correo Resend → 20 viajes M2 + piloto 25 empresas / 50 transportistas — no más pantallas core.

• owner_user_id — mis cargas / mis ofertas: hecho.
• Refino UX publicar → match → activos → historial: hecho (v0.0.90–0.0.125).
• SQL 008+ en prod: hecho; capturas pitch en docs/img/ opcional.

Fase 2 — Núcleo digital (ya en producción)

Lo realizado (adelantado vs Gantt oct 2026)

• Migraciones Supabase 001–011 (auth, matches, chat, notificaciones, banco, precios 010, confianza/carga 011); 012–014 (mis viajes, match_ratings, chips tags/tag_band).
• Calificaciones estilo Uber (may 2026): POST /api/matches/:id/rate, catálogo /rating-tags-catalog.json, UI trips-ui.js + rating-tags.js.
• API: capacity-offers, load-requests, matches, sugerencias automáticas, comms, cuenta.
• UI embarcador / transportista, emparejamientos activos, modal cancelar, acuerdo mutuo bilateral.
• Notificaciones in-app (JWT); panel Cuenta y multas siempre visible con sesión.
• Multas tipo Uber (v0.0.50–0.0.57): 7 días plazo → bloqueo operar; deudor declara pago externo + comprobante; acreedor (embarcador o transportista según caso) ve comprobante y confirma/rechaza en 24 h; sin respuesta → moderador; chat soporte con rol moderador (admin).
• Cuenta bancaria: bank-gate — en producción no publicar/ofertar/emparejar sin banco completo (BANK_ENFORCE).
• GPS transportista en sesión; visibilidad en tablero con toggle (multa no apaga GPS).
• KYC semi-curado (kyc_status=approved); owner_user_id en listados.
• Railway producción + /health + documentación en /docs/.

Pendiente en fase 2 (post-MVP prod)

• 2.10b: pasarela + wallet real + retención al «En ruta» (U7 prod).
• 2.10e–f (futuro): cobro integrado multas vía wallet (hoy transferencia + comprobante).

Fase 3 — Piloto confianza

KYC manual, ratings bidireccionales (adelantado — mayo 2026), microseguro POC, 100 viajes digitales (M4). Pendiente: reputación visible en tablero Emparejar (M3).

Fase 4 — Escala producto

Match semi-automático por corredor, dashboard embarcador frecuente, informe red de capacidad (M5).

Fase 5 — Estrategia add-on (visión, post-tracción)

Con métricas de uso (viajes, retención, NPS), empaquetar capacidad ociosa como módulo integrable (API + widgets) para socios tipo marketplace o apps de movilidad. Requiere MVP propio maduro y casos de éxito en Chile.

Cronograma del proyecto — vista Gantt

Las fechas son orientativas (jun 2026 – mar 2027). El Gantt detallado por mes está en este mismo documento (no hace falta abrir otro archivo).

Leyenda

Resumen por fases

Diagrama Gantt por fase (trimestres)

Hitos (milestones)

Métricas de control

Interpretación 25 may 2026: MVP flujo cerrado (v0.0.129); FCM y contraseña fuerte cerrados; SQL prod 23/23 OK; foco = dominio Resend (P0) → demo comercial → piloto 25/50 → 20 viajes M2. Wallet prod y Twilio en cola P0; OAuth/iOS fuera de alcance inmediato. cubik.cl y cubik.com ocupados — variante compuesta sin renombrar app.

Piloto M2 — corredor único (liquidez)

El cuello de botella del marketplace no es el código sino la oferta y demanda simultánea. El piloto M2 se concentra en un corredor para lograr densidad operacional.

Detalle operativo: Piloto M2 — corredor, KPIs y riesgos.

KPIs marketplace — piloto M2

Matriz de riesgos operacionales

Cobertura — quién responde (resumen)

La plataforma no transporta ni reembolsa el valor declarado de la mercadería por defecto. Transportista ejecuta el flete; embarcador declara con veracidad; Uber Truck facilita match, registro, chat, incidentes y reglas de cancelación.

Tabla completa: anexo piloto §4 · términos cargo-trust-v1.

Próximos pasos — backlog vivo (25 may 2026)

Prioridad: P0 bloquea piloto; P1 siguiente entrega; P2 planificado. Actualizar al cerrar cada release o semana de piloto. Detalle comercial: PLAN-COMERCIAL-PILOTO.md · canvas cubik-plan-native-escala.

No hacer aún: rewrite 100 % nativo, Open Finance, pricing dinámico completo, expansión multi-corredor sin liquidez. Priorizar operación piloto sobre más pantallas.

Gantt plan comercial — 16 semanas (9 jun – 29 sep 2026)

Alineado a canvases/cubik-plan-native-escala.canvas.tsx. Barras ████ = ventana activa por semana (S1 = 9–13 jun).

Gantt detallado por tarea (2026–2027)

Responsable: E=Equipo, O=Operaciones/piloto, L=Legal. Vista mensual complementaria al Gantt de 16 semanas.

Avance fase 2 — resumen (10 jun 2026)

• MVP digital núcleo + paridad UX: ~95% (cerrado para piloto)
• Multas / cuenta (2.10a): ~90% (falta wallet prod 2.10b)
• Cubik Saldo piloto + QA: ~85%
• Fase 3 ratings: ~70% (mutuo en app; KYC ampliado pendiente)
• Proyecto total (hasta M5): ~50% — foco operación piloto

Bitácora de avance — 27 mayo 2026

Bitácora de avance — 29 mayo 2026 (v0.0.50–0.0.57)

Deploy: Railway uber-truck-production.up.railway.app · rama main · versión app 0.0.57.

SQL pendiente usuario: ejecutar en Supabase RUN_022_023, RUN_024, RUN_025 (ver SQL-SUPABASE.md).

Archivos clave: src/lib/penalty-ledger.js, src/lib/penalty-payment.js, src/lib/bank-gate.js, src/routes/account.js, public/penalties-ui.js.

Bitácora de avance — 2 junio 2026 (Cubik v0.0.75–0.0.78)

Links operativos:

• App / API: https://uber-truck-production.up.railway.app
• Testers (un link): https://uber-truck-production.up.railway.app/probar
• Modo app web: /?app=1
• Health: /health
• APK Android: generar con npm run android:apk → %USERPROFILE%\Downloads\cubik-android.apk

Comandos: npm run cap:sync:bundle · npm run android:apk · npm run cap:open:android

Bitácora de avance — 3 junio 2026 (Cubik v0.0.90–0.0.94)

SQL usuario: ejecutar RUN_030_user_bank_accounts.sql en Supabase (migra cuenta legacy + multi-cuenta).

Deploy: commits 38dee51 (v0.0.93), f816bbe (v0.0.94) · Railway main.

Bitácora de avance — 10 junio 2026 (Cubik v0.0.127 — push FCM validado)

Bitácora de avance — 25 mayo 2026 (Cubik v0.0.97–0.0.98 + diseño pagos)

Deploy: Railway main · versión app 0.0.98 · APK cubik-android.apk.

Bitácora de avance — junio 2026 (Cubik Saldo piloto v0.0.99–0.0.104)

API: POST /api/matches/:id/pilot-pay (solo embarcador, viaje completed). SQL: RUN_026_pilot_payment.sql.

Deploy: commits 96947cf (v0.0.102) → 7f09d15 (v0.0.104) · Railway main · APK cubik-android.apk.

Limitación piloto: sin movimiento real de dinero; label «Simulación piloto»; completed ≠ pagado hasta que el embarcador pulsa Pagar.

Bitácora de avance — 25 mayo 2026 (v0.0.105 — calibración tarifas)

Deploy: commit a4336d7 (v0.0.105) · Railway main · comisiones piloto sin cambio.

Bitácora de avance — 25 mayo 2026 (v0.0.106 — UX urgencia y emparejar)

Bitácora de avance — junio 2026 (v0.0.107–0.0.125 — QA, Android y comercial)

Deploy: commits 71de185 → 70723d1 · Railway main · presentación comercial jun 2026.

Modelo de monetización, Cubik Saldo y checkout (diseño may 2026)

Estado jun 2026: piloto operativo (v0.0.100–0.0.104) con comisiones 10/5 y flujo pago post-completado simulado. Pendiente producción: wallet real, ledger, retención al «En ruta», recarga pasarela. GMV piloto no genera ingreso real (solo simulación en UI).

Comisiones (take rate dual)

Ejemplo flete $1.200.000: embarcador retiene/paga $1.320.000; transportista recibe $1.140.000; ingreso Cubik $180.000.

agreed_price_clp = monto negociado en oferta; comisiones se aplican después, no inflan el precio mostrado al aceptar.

Flujo de dinero (Cubik Saldo)

1. Publicar carga: wallet_balance ≥ 0,20 × budget_max_clp.
2. Aceptar match: aviso «El pago se retiene al marcar En ruta»; sin escrow aún.
3. Marcar en ruta: retiene agreed_price_clp × 1,10 del embarcador; si saldo insuficiente → bloqueo + notificación al embarcador.
4. Completar viaje: libera al transportista agreed_price_clp × 0,95; acredita comisiones a Cubik.
5. Cancelación / devolución: crédito en Cubik Saldo (no cash); multas según política existente.

Tiers de formalidad (sin efectivo)

Umbral $1M alinea checkout corto (tipo Uber Eats imagen 1) vs resumen tarifas obligatorio (imagen 2).

Pantallas UX (referencia Uber Eats)

Implementación técnica — piloto (hecho v0.0.100–0.0.104)

• SQL 026: matches.pilot_payment_status (in_settlement | released), pilot_payment_at.
• src/lib/payment-simulation.js — comisiones 10/5, enrich en GET matches y cuenta.
• POST /api/matches/:id/pilot-pay — embarcador marca pago; notifica transportista (pilot_payment).
• UI: pilot-pay-ui.js, trips-ui.js, penalties-ui.js, comms-ui.js.

Implementación técnica — producción (pendiente)

• SQL: wallet_accounts, wallet_ledger, campos fee en matches.
• API role-scoped: checkout por rol sin filtrar fee del otro rol.
• Gate publicar: wallet-gate.js · retención: hook accepted → in_progress.
• Variables: SHIPPER_FEE_PERCENT=10, CARRIER_FEE_PERCENT=5, WALLET_PUBLISH_MIN_RATIO=0.20, CHECKOUT_SIMPLE_MAX_CLP=1000000.
• Pasarela: Mercado Pago / recarga saldo; multas migran a cargo wallet o tarjeta tokenizada.

Próxima etapa (jun 2026)

1. P0 — Presentación comercial (jun): demo prod + APK remoto; pitch piloto 25 embarcadores + 50 transportistas.
2. P0 — Piloto M2: 20 viajes completed corredor RM ↔ Valparaíso/San Antonio.
3. P0 — Nativo lite: GPS background (Capacitor/plugin) si el piloto lo exige — sin rewrite UI.
4. P1 — Wallet real + escrow en ruta (piloto 10/5 ya validado en simulación).
5. P1 — Twilio Proxy: llamadas enmascaradas (botón Llamar ya en v0.0.98).
6. P0 — Dominio + Resend: comprar variante Cubik; verificar DNS; EMAIL_FROM — bloqueante correo piloto.
7. P2 — Push FCM: Cerrado — segundo plano, notificaciones de acciones.
8. P2 — Contraseña fuerte + cambio en APK: Cerrado v0.0.128.
9. P2 — Escala 50+/200: presupuesto Maps + infra (~USD 2.1k/mes) antes de marketing masivo.

Detalle estratégico: PROXIMOS-PASOS-ESTRATEGIA.md · Plan comercial: PLAN-COMERCIAL-PILOTO.md · QA: QA-AUTOMATIZADO.md · UX app: CUBIK-APP-UX.md

Parte II — Stack tecnológico por capas

Numeración de abajo hacia arriba y hacia el exterior (referencia en incidentes y actas).

Capa 01 — Node.js

Rol: runtime del servidor (src/server.js). Engines: ≥ 20. Problemas: puerto ocupado, versión distinta a prod → alinear Railway y package.json.

Capa 02 — Express.js

Rol: HTTP, JSON, estáticos public/, documentación /docs/, rutas /api/*, /health. Archivo: src/app.js.

Capa 03 — API REST

Rol: marketplace — ofertas, cargas, matches, auth, comms, cuenta. Auth: JWT en rutas protegidas. Rutas en src/routes/.

Capa 04 — Supabase (PostgreSQL)

Rol: persistencia; migraciones en supabase/migrations/. Proyecto prod: ljinhegtywixtbzjgjfn. Service role solo en servidor.

Capa 05 — Autenticación (JWT + bcrypt)

Rol: registro/login con email y contraseña; tabla users; roles shipper / carrier. Política contraseña: 8+ caracteres, letra, mayúscula, número (password-policy.js, v0.0.128).

Correo: forgot/reset con Resend en prod; piloto multi-cuenta bloqueado hasta dominio verificado (DOMAIN-AND-EMAIL.md). Pendiente: OAuth Google/Apple — AUTH-AND-EMAIL-ROADMAP.md.

Capa 06 — Lógica de dominio

Rol: src/lib/ — match, cancelación (match-cancel-reasons.js), precio (match-price.js), confianza/carga (cargo-trust.js), multas (penalty-ledger.js, penalty-payment.js, penalty-gate.js, bank-gate.js, payment-proof.js), repositorio.

Capa 07 — Servicios

Rol: src/services/ — Supabase client, comms, integraciones futuras (mapas, pagos).

Capa 08 — Frontend web + app móvil Cubik

Rol: public/ — SPA web + modo app (?app=1, PWA, Capacitor). Shell móvil: app-shell.js, app-shell.css. API remota vía api-base.js cuando UI va en bundle APK. Marca Cubik: brand-config.js, public/brand/.

Android: Capacitor 7, package cl.cubik.logistics, carpeta android/. Scripts: npm run android:apk, android:install:remote, android:verify. Distribución: /probar + APK bundle o remoto.

QA visual: /qa-lab — catálogo y gráficos de pruebas (npm run qa:lab).

Capa 09 — Experiencia producto (paridad Uber)

Rol: flujos, copy y pantallas en public/ alineados a «pedir → match → viaje activo → historial»; roles embarcador/transportista como pasajero/conductor. Piloto y validación solo dentro de esta app, no canales externos.

Capa 10 — Railway

Rol: hosting, variables de entorno, healthcheck /health, deploy desde GitHub main.

Capa 11 — Git y GitHub

Rol: versionado; nunca commitear .env. Workflow CI: .github/workflows/qa.yml (unit + Playwright local + smoke prod en main).

Capa 12 — Documentación HTML

Rol: memoria viva, Gantt y próximos pasos en un solo HTML; export Word vía html-to-docx. Hub: /docs/index.html.

Extensiones planificadas

Modelo de datos (resumen)

Entidades: users, vehicles, capacity_offers, load_requests, matches, match_messages, match_notifications, penalty_charges, match_incidents, match_ratings (012–014), trip_events (roadmap).

Calificaciones (012–014): tabla match_ratings — match_id, rater_role (shipper|carrier), stars, comment, tags (TEXT[]), tag_band (low|mid|high), rater_user_id (opcional, 014). UNIQUE (match_id, rater_role). En matches: delivery_note, completed_at.

Precio: load_requests.budget_min_clp, budget_max_clp; en matches: copia del rango, carrier_offer_clp, agreed_price_clp, price_status (migración 010).

Confianza / carga (011): en load_requests: cargo_description, declared_cargo_value_clp, has_dispatch_guide, dispatch_guide_folio, requires_cargo_insurance, legal_terms_version, terms_accepted_at. Tabla match_incidents (robo, daño, faltante, atraso, otro). Ver CARGO-TRUST.md y términos HTML.

Estados matches: proposed → (oferta transportista) → accepted (precio aceptado) → in_progress → completed | cancelled.

API REST — contrato MVP (mayo 2026)

Reglas de negocio MVP

• Match: corredor origen–destino, cubicación, peso; sugerencias automáticas en UI.
• Precio: embarcador publica rango orientativo; transportista oferta CLP (puede estar fuera del rango); embarcador acepta para confirmar. Puede ampliar rango salvo que ya exista precio acordado con otro transportista en la misma carga.
• Rango sugerido: POST /api/maps/budget-estimate — referencia por distancia, peso y urgencia (defaults calibrados jun 2026: base $80.000, $450/km, $22/kg; configurable vía BUDGET_* en Railway); no bloquea ofertas.
• Dirección: con Maps configurado, origen/destino deben elegirse de la lista Google.
• Cancelación: motivos; multas sugeridas; acuerdo mutuo bilateral.
• Roles: shipper ve sus cargas + mercado de ofertas; carrier ve mercado de cargas + sus ofertas; admin ve todo.
• Comisión: 10% fee embarcador + 5% comisión transportista sobre agreed_price_clp (15% efectivo); cada rol ve solo su línea en checkout.
• Cubik Saldo: publicar requiere 20% del presupuesto máximo en saldo; retención flete + 10% al Marcar en ruta; liberación al completar; sin efectivo.
• Tier formalidad: < $1.000.000 saldo Cubik; ≥ $1M factura + saldo/transferencia registrada.
• Confianza: plataforma como intermediario; embarcador declara mercadería y valor referencial; aceptación cargo-trust-v1; folio guía opcional (sin validación SII automática en MVP).
• Incidentes: registro en match_incidents; resolución entre partes y aseguradoras; la app no reembolsa valor declarado por defecto.
• Calificaciones: solo en completed; una nota por rol por viaje; reputación pública = promedio histórico de estrellas recibidas; chips según catálogo por rol y banda de estrellas.
• Multas: al cancelar se sugiere monto y reason_code; deudor según motivo (embarcador o transportista); 7 días para pagar antes de bloqueo; deudor declara transferencia + comprobante → acreedor 24 h para confirmar o disputar; sin confirmación → escalado moderador (sin auto-desbloqueo).
• Banco: en producción con Supabase, datos bancarios completos obligatorios para operar (BANK_ENFORCE); no sustituye pasarela futura.
• Pagos integrados: diseño Cubik Saldo cerrado (may 2026); implementación en curso; multas legacy siguen transferencia + comprobante hasta migración wallet — ver § monetización y PENALTY-AND-SUPPORT.md.

Seguridad y cumplimiento

• Secretos en .env; RLS Supabase por usuario cuando aplique.
• Ley 19.628 (Chile): minimizar PII en logs.
• Términos de confianza y carga en app + HTML (borrador operativo); revisión abogado Chile antes de escala comercial.
• Microseguro y KYC: fase 3; hoy flag requires_cargo_insurance + revisión manual de incidentes open.

Estructura del repositorio

Fin del documento — v4.4 (25 may 2026): paridad MVP cerrada; FCM + contraseña cerrados; dominio Resend P0; backlog vivo + Gantt 16 sem; foco dominio → demo → 25/50 → M2.