usite-sas-bic/moraworld
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
62e48bd372c17e9924caa716919e0307b49791dc
moraworld/ROADMAP.md
T

13 KiB
Raw Blame History

Moraworld Imports — Roadmap de Desarrollo

Versión: 1.0
Fecha inicio: Mayo 2026
Estado: En planificación → Fase 0

Visión del producto

Plataforma logística transfronteriza (EE.UU. → Ecuador) con:

  • Casillero B2C — automatizado (Amazon, eBay, etc.)
  • Carga pesada B2B — cotización manual
  • Bodega NJ — operaciones físicas sincronizadas por API
  • Aduanas — declaraciones SENAE
  • Multi-tenant — una instalación, datos aislados por empresa

Bodega: 150 N Day St, Suite EC-XXXXX, City of Orange, NJ 07050

Stack acordado (base del roadmap)

Capa Tecnología
Monorepo Turborepo + pnpm
Frontend Next.js 15 (App Router) + TypeScript + Tailwind CSS
API NestJS + TypeScript
ORM / migraciones Prisma
Base de datos PostgreSQL 16
Cache / colas Redis + BullMQ
Archivos AWS S3 (facturas, fotos)
Auth JWT + refresh tokens + MFA TOTP
Contenedores Docker Compose (local)
CI GitHub Actions
Docs API Swagger (OpenAPI)

El documento de requerimientos lista esto como sugerido; este roadmap lo adopta como decisión de implementación salvo cambio explícito.

Estructura del repositorio (objetivo final)

moraworld/
├── apps/
│   ├── web/              # Next.js — landing + portal cliente + tracking público
│   ├── admin/            # Next.js — portal admin + agente aduanero (Fase 3+)
│   ├── warehouse/        # Next.js — portal bodega NJ (Fase 2)
│   └── api/              # NestJS — REST API + workers
├── packages/
│   ├── database/         # Prisma schema + client
│   ├── shared/           # Tipos, constantes, validaciones Zod
│   └── ui/               # Componentes compartidos (opcional Fase 2)
├── docker/
│   └── docker-compose.yml
├── docs/
│   └── api/              # OpenAPI export
└── ROADMAP.md

Fases y cronograma estimado

Fase Nombre Duración est. Entregable principal
0 Fundación 1 semana Repo, Docker, BD, auth básico
1 MVP Casillero (cliente) 3–4 semanas Registro, suite, paquetes, pre-alerta
2 Bodega + API externa 3–4 semanas Portal operador NJ + sync software bodega
3 Admin + tarifas 2–3 semanas Dashboard, roles, configuración
4 Calculadora + pagos 2–3 semanas SENAE en calculadora + cobro en línea
5 Aduanas SENAE 4–6 semanas DSI, envío WebService, agente aduanero
6 Notificaciones + integraciones 2–3 semanas Email, SMS, WhatsApp, Amazon SP-API
7 B2B carga pesada 2 semanas Cotizaciones, expedientes INEN
8 Producción + hardening 2–3 semanas Deploy, backups, auditoría, ISO prep

Total estimado: 19–26 semanas (~5–6 meses) con 1–2 desarrolladores.

Fase 0 — Fundación (Semana 1)

Objetivo

Entorno de desarrollo reproducible y esqueleto del monorepo.

Tareas

  • Inicializar git + .gitignore + ramas (main, develop)
  • Crear monorepo Turborepo (pnpm workspaces)
  • docker-compose: PostgreSQL, Redis, (MinIO opcional para S3 local)
  • App api NestJS: health check, CORS, validación global
  • Package database: Prisma + primera migración
  • App web Next.js: layout base, tipografía Inter, colores marca
  • Variables de entorno (.env.example)
  • README con instrucciones pnpm install + docker compose up

Criterios de aceptación

  • pnpm dev levanta API + web en local
  • API responde GET /health → 200
  • Prisma conecta a PostgreSQL y aplica migraciones

Fase 1 — MVP Casillero cliente (Semanas 2–5)

Objetivo

Reemplazar el flujo mock de login.html, registro.html y portal-cliente.html con backend real.

Modelo de datos (Prisma — núcleo)

Tenant, User, Role, UserRole
Suite (código EC-XXXXX por usuario)
Package, PackageStatusHistory
PreAlert, Document (S3 keys)
TariffZone (básico)
AuditLog

Tareas backend (NestJS)

  • Módulo auth: registro, login, refresh, logout
  • MFA TOTP: activar / verificar en login
  • Módulo users: perfil, actualizar teléfono/WhatsApp
  • Módulo suites: asignación automática al registrar (EC-{secuencia})
  • Módulo packages: CRUD, cambio de estado, historial inmutable
  • Módulo pre-alerts: crear, listar, adjuntar factura (upload S3)
  • Módulo documents: presigned URLs para subida
  • RBAC: guard Cliente vs roles internos (stub para fases posteriores)
  • Generador Tracking ID: EC-YYYYMMDD-XXXXXX
  • Seed: tenant Moraworld + usuario demo

Tareas frontend (Next.js web)

  • Migrar diseño de index.html → / (landing)
  • /login, /registro (multi-paso como HTML actual)
  • /portal — layout con sidebar (dashboard, paquetes, pre-alertas)
  • /portal/mi-casillero — dirección Suite copiable
  • /portal/paquetes — tabla con estados reales desde API
  • /portal/pre-alertas — formulario + upload factura
  • Modal registrar compra (manual; URL Amazon en Fase 6)
  • Cliente API (fetch/axios) + manejo de tokens

Criterios de aceptación

  • Usuario se registra y recibe Suite única en BD
  • Crea pre-alerta con PDF/imagen en S3
  • Registra paquete manual y ve estado REGISTRADO
  • Historial de estados visible y no editable

Fase 2 — Portal bodega + API software propio (Semanas 6–9)

Objetivo

Operadores en NJ gestionan paquetes físicos; tu software de bodega sincroniza por API.

Tareas

  • App warehouse (Next.js) o rutas /warehouse con rol Operador Bodega
  • Lista paquetes esperados (pre-alertas + registrados)
  • Acción: recibir paquete → RECIBIDO_BODEGA
  • Verificación: peso real, dimensiones, fotos (múltiples) → EN_VERIFICACION / VERIFICADO
  • Alerta discrepancia peso > 10%
  • Asignar paquete a Suite si llegó sin pre-alertar
  • API externa v1 (API Key por tenant):
    • POST /api/v1/webhooks/package-status
    • GET /api/v1/packages?status=...
    • PATCH /api/v1/packages/:id/verify
  • Documentación OpenAPI para integración bodega
  • Idempotencia en webhooks (X-Idempotency-Key)

Criterios de aceptación

  • Operador escanea/busca paquete y confirma recepción
  • Fotos visibles en portal cliente tras subirlas
  • Software externo puede actualizar estado vía API autenticada

Fase 3 — Portal administrativo (Semanas 10–12)

Objetivo

Admin Empresa y Super Admin gestionan operación.

Tareas

  • App admin o rutas /admin
  • Dashboard: paquetes por estado, ingresos, incidencias
  • Gestión usuarios y roles (matriz del doc §3.2)
  • Configurar tarifas: $/lb por zona Ecuador
  • Configurar categorías SENAE (4x4, B, C, D) editables
  • Logs de auditoría (solo lectura, filtros)
  • Reportes básicos CSV: envíos del mes

Criterios de aceptación

  • Admin cambia tarifa y afecta calculadora nueva
  • Toda acción sensible queda en audit_logs

Fase 4 — Calculadora + pagos (Semanas 13–15)

Objetivo

Calculadora pública y de portal con reglas reales; cobro anticipado del envío.

Tareas

  • Servicio calculator: peso volumétrico, flete, seguro, FODINFA, arancel, IVA
  • Endpoint público POST /api/v1/calculate-shipping (sin auth)
  • Migrar sección calculadora de index.html → datos desde API
  • Tracking público GET /api/v1/tracking/:id (sin auth, datos limitados)
  • Integración pasarela: PayPhone (prioridad Ecuador) + webhook confirmación
  • Vincular pago a Package antes de despacho
  • Estados post-pago en historial

Criterios de aceptación

  • Calculadora landing = misma lógica que portal (misma API)
  • Cliente paga envío y paquete queda marcado como pagado
  • Tracking público muestra timeline sin login

Fase 5 — Módulo aduanas SENAE (Semanas 16–21)

Objetivo

Declaración simplificada (DSI) y envío al WebService SENAE.

Tareas

  • Modelo CustomsDeclaration ligado a Package
  • Validación umbral $400 / régimen 4x4
  • Generación automática DSI (borrador)
  • Portal agente aduanero: revisar, aprobar, rechazar
  • Cola BullMQ: submit-to-senae con reintentos
  • Integración SENAE sandbox → producción
  • Guardar número autorización SENAE + PDF
  • Estado DECLARACION_ADUANERA → EN_TRANSITO_ECUADOR

Criterios de aceptación

  • Paquete VERIFICADO genera DSI revisable por agente
  • Envío exitoso a SENAE actualiza estado y notifica cliente
  • Paquetes sobre umbral generan alerta de importación formal

Fase 6 — Notificaciones e integraciones (Semanas 22–24)

Objetivo

Comunicación automática en cada cambio de estado.

Tareas

  • Worker notificaciones: email (Resend/SES), SMS, WhatsApp Business API
  • Plantillas por estado (11 estados del doc)
  • Preferencias usuario: canal activo
  • Amazon SP-API: parsear URL → pre-llenar registro compra
  • Courier APIs (UPS/FedEx): tracking vendedor opcional
  • Botón WhatsApp landing (ya en HTML) — números desde config admin

Criterios de aceptación

  • Cambio de estado dispara al menos email + un canal configurado
  • Pegar URL Amazon pre-llena formulario de compra

Fase 7 — Carga pesada B2B (Semanas 25–26)

Objetivo

Flujo separado del casillero para importadores mayoristas.

Tareas

  • Modelo B2BQuote, B2BQuoteStatus
  • Formulario cotización en /carga-pesada/cotizacion
  • Panel admin: revisar solicitudes, responder cotización
  • Expediente con tracking B2B propio
  • Campos INEN / certificación en formulario
  • Notificación manual (email/WhatsApp) al equipo Moraworld

Criterios de aceptación

  • Cotización B2B no mezcla flujo con paquetes B2C
  • Admin puede cerrar cotización como aceptada/rechazada

Fase 8 — Producción y hardening (Semanas 27–29)

Objetivo

Sistema listo para usuarios reales con SLA y seguridad.

Tareas

  • Ambientes: development, staging, production
  • Deploy: API + web (Railway/Render o AWS ECS + RDS)
  • TLS, dominio, Cloudflare WAF
  • Backups PostgreSQL automáticos (retención 90 días)
  • Rate limiting, helmet, validación OWASP básica
  • Políticas: privacidad LOPDP, términos, cookies
  • Monitoreo: Sentry + logs estructurados
  • Pruebas E2E críticas (Playwright): registro → pre-alerta → bodega recibe
  • Runbook operativo para equipo Moraworld

Criterios de aceptación

  • Staging accesible con datos de prueba
  • Producción con backup restaurable probado
  • Checklist ISO 27001 controles implementados documentado

Roles del sistema (implementación por fase)

Rol Fase disponible
Cliente Final Fase 1
Operador Bodega Fase 2
Soporte Fase 3 (solo lectura)
Admin Empresa Fase 3
Agente Aduanero Fase 5
Super Admin Fase 3

Estados de paquete (referencia única)

REGISTRADO → EN_TRANSITO_BODEGA → RECIBIDO_BODEGA → EN_VERIFICACION
→ VERIFICADO → DECLARACION_ADUANERA → EN_TRANSITO_ECUADOR
→ EN_ADUANA_ECUADOR → LISTO_ENTREGA → ENTREGADO
(INCIDENCIA en cualquier punto)

Migración desde prototipos HTML actuales

Archivo actual Destino en producción
index.html apps/web — /, secciones anchor
login.html apps/web — /login
registro.html apps/web — /registro
portal-cliente.html apps/web — /portal/*
documentacion.html Mantener estático o mover a /docs interno
presentacion.html Mantener para ventas; no producción
requerimientos-sistema-casillero.md Fuente de verdad funcional

Los HTML actuales no se borran hasta completar migración de cada sección (Fase 1–4).

Riesgos y dependencias externas

Riesgo Mitigación
Acceso API SENAE (sandbox/prod) Iniciar trámite en Fase 0; mock en Fase 5
Software bodega sin API aún Definir contrato OpenAPI en Fase 2; mock
PayPhone / credenciales pagos Cuenta merchant en Fase 4
WhatsApp Business verificación Proceso Meta en Fase 6
Amazon SP-API aprobación Fallback scraping/manual Fase 6

Próximo paso inmediato (esta semana)

Iniciar Fase 0 en este orden:

  1. Crear monorepo + Docker + PostgreSQL + Redis
  2. Prisma schema v0 (Tenant, User, Suite, Package)
  3. NestJS auth mínimo (registro + login JWT)
  4. Next.js shell con página de health

Cuando confirmes, ejecutamos la Fase 0 en el repositorio.

Control de progreso

Fase Estado Fecha inicio Fecha fin
0 🟡 En curso May 2026
1 ⬜ Pendiente
2 ⬜ Pendiente
3 ⬜ Pendiente
4 ⬜ Pendiente
5 ⬜ Pendiente
6 ⬜ Pendiente
7 ⬜ Pendiente
8 ⬜ Pendiente

Documento vivo — actualizar al cerrar cada fase.

Reference in New Issue View Git Blame Copy Permalink