feat: initial commit - Moraworld Imports project

ROADMAP.md

@@ -0,0 +1,401 @@
+# 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.*