402 lines
13 KiB
Markdown
402 lines
13 KiB
Markdown
# 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.*
|