# 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.*