Flujo: Creación de Proyecto

¿Quién lo usa?

¿Por qué importa?

La creación de proyecto es el punto de entrada de todo el ciclo de vida de Rial. Aquí el cliente define qué imágenes necesita: tipo de servicio, prendas, SKUs y configuración. Un proyecto mal configurado genera retrabajo costoso en etapas posteriores.

Entrada en la plataforma

URL: /projects/create

El cliente navega a esta ruta desde el botón “Nuevo proyecto” en la barra lateral. La plataforma muestra tres tipos de proyecto disponibles:

Ruta del componente: app/(private)/projects/create/page.tsx → ProjectTypeSelector

Nota: El paso de selección de modelo no existe en proyectos de tipo PRODUCT.

Capacidades según la compañía

La creación de proyectos y los catálogos opcionales dependen de los módulos habilitados en CompanySettings:

El frontend oculta pasos y rutas cuando el módulo no está habilitado, pero la autorización real se valida nuevamente en el backend.

Borradores BATCH

Los borradores permiten guardar por separado la configuración, el Excel, las imágenes, el matching y la selección de modelos antes de crear los proyectos finales. Requieren el módulo PROJECT_DRAFTS, el permiso PROJECT_CREATOR y rol COMPANY_ADMIN o BRAND_ADMIN.

Las rutas principales son:

POST   /project-drafts
GET    /project-drafts
GET    /project-drafts/:id
PUT    /project-drafts/:id/excel
PUT    /project-drafts/:id/images
PUT    /project-drafts/:id/models
PUT    /project-drafts/:id/matching
POST   /project-drafts/:id/projects
DELETE /project-drafts/:id

Cambiar el Excel invalida el matching y los modelos guardados. Cambiar las imágenes invalida el matching cuando cambia su fingerprint. La finalización requiere matching vigente y modelos válidos; al completarse mueve los archivos temporales y crea los proyectos BATCH de forma idempotente.

El upload temporal usa POST /uploads/request-signed-urls con uploadType=CREATE_PROJECT_DRAFT y draftId. Los datos canónicos del borrador se mantienen dentro de options.

Kits y combinación de prendas

Cuando GARMENT_COMBINATION está habilitado, el flujo BATCH puede consultar kits y ejecutar jobs de combinación. Los grupos que usan únicamente imágenes propias no crean un job; los grupos con kits esperan a que sus jobs terminen antes de permitir la creación final. PRODUCT no usa kits ni jobs de combinación.

El job se inicia mediante:

POST /jobs/garment-combination

Si el módulo no está habilitado, el frontend omite el paso COMBINE, no consulta kits y no solicita este endpoint.

Pasos del flujo

El flujo es manejado por ExcelProjectBase, un componente genérico que recibe la configuración específica de cada tipo de proyecto vía la prop config.

Paso 1 — Configuración (ExcelProjectStep.CONFIGURATION)

Componente: CreateExcelForm

El usuario completa los datos generales que se aplican a todos los proyectos creados desde este lote:

Endpoints en este paso: ninguno — los datos se guardan en el estado del formulario.

Validación para continuar: name, season y year deben estar completos.

Paso 2 — Subir Excel (ExcelProjectStep.EXCEL_UPLOAD)

Componente: UploadExcelForm

El usuario arrastra o selecciona un archivo .xlsx con la estructura de SKUs del proyecto. El archivo se valida automáticamente al cargarlo.

Columnas requeridas por tipo:

• Marca — debe existir en la plataforma (obligatorio)
• Genero — Hombre, Mujer o Unisex (opcional)
• Edad — en años (25) o meses ("6m") (opcional)
• SKU — identificador único con formato XXX.ext (obligatorio)
• Vista — solo Faceswap: formato XXX_YY.ext o XXX-YY.ext (obligatorio)

Endpoint utilizado:

POST /excel/projects/validate
  Body: FormData { file, projectType, projectName }
  Response: { isValid, error?, data: { excelData, duplicatedSkus } }

El backend procesa el Excel y retorna:

• excelData — estructura con proyectos agrupados por marca, lista de SKUs, modelos sugeridos
• duplicatedSkus — SKUs que ya existen en proyectos anteriores (se muestra una alerta de advertencia)

Validación para continuar: el Excel debe ser válido y contener al menos una fila por proyecto.

Paso 3 — Subir fotos (ExcelProjectStep.UPLOAD_IMAGES)

Componente: UploadImagesForm

El usuario carga las imágenes de las prendas. Todos los archivos se mantienen en memoria del navegador (File[]) y no se suben al servidor en este paso.

La interfaz muestra las imágenes paginadas de 20 en 20 (ordenadas alfabéticamente por nombre) y permite previsualizarlas con hover. Si se detectan imágenes con el mismo nombre de archivo (SKU duplicado), se muestra una alerta de advertencia y las imágenes duplicadas son rechazadas.

Endpoints en este paso: ninguno.

Validación para continuar: debe haber al menos una imagen seleccionada.

Paso 4 — Modelo (ExcelProjectStep.MODEL)

Componente: SelectModelForm → ProjectModelSelection → ModelSelectionGrid

Solo disponible para FACESWAP y BATCH. El tipo PRODUCT omite este paso.

El usuario selecciona el modelo (o modelos) de IA que reemplazará a los modelos de las fotografías originales. La selección se hace por marca y género:

• Hombre → 1 slot de modelo
• Mujer → 1 slot de modelo
• Unisex → 1 slot femenino + 1 slot masculino

La validación comprueba que cada proyecto tenga al menos un modelo seleccionado acorde al género declarado en el Excel.

Endpoints en este paso: ninguno — la selección se guarda en el form state como modelIds[projectKey].

Paso 5 — Resumen (ExcelProjectStep.SUMMARY)

Componente: ProcessingResultsForm

Al avanzar al paso de Resumen, el sistema cruza automáticamente los nombres de las imágenes subidas con los SKUs del Excel. Este cruce determina qué imágenes corresponden a cada SKU y cuáles sobran o faltan.

Endpoint utilizado:

POST /excel/projects/match
  Body: { projects: SkusByProjectKey, fileNames: string[], projectType }
  Response: { result: { data: MatchedExcelResult, isValid, error? } }

Para lotes grandes de imágenes (> EXCEL_FILENAMES_CHUNK_SIZE), las llamadas se hacen en chunks y los resultados se combinan en el frontend con mergeMatchedExcelResults.

El resumen muestra:

Si hay imágenes con nombres que no corresponden a ningún SKU (extraImages) o SKUs sin imagen (unmatchedImages), el sistema bloquea la creación mostrando alertas de error.

El usuario puede descargar un reporte Excel del matching:

POST /excel/projects/report
  Body: { matchedImages, unmatchedImages, extraImages }
  Response: blob (.xlsx)

Validación para crear: no deben existir unmatchedImages ni extraImages.

Creación de proyectos (submit)

Al presionar “Crear proyectos”, el proceso corre en background (useBackgroundProcessing) y el usuario es redirigido a /projects?creating=true mientras se completa.

El flujo se ejecuta secuencialmente por cada marca encontrada en el Excel:

Para cada (projectKey, projectResult) en processingResult.projects:

  1. POST /uploads/request-signed-urls
       Body: { fileNames, uploadType: CREATE_PROJECT, brandId, projectType, skus }
       Response: { signedUrls: { [fileName]: string } }

  2. PUT [signed-url]   ← directo a Google Cloud Storage (concurrente, máx. 10 en paralelo)
       Body: archivo de imagen
       Headers: Content-Type: image/...

  3. POST /projects/faceswap   ← o /batch o /product según el tipo
       Body: { name, brandId, season, description, fileNames, modelIds, skus, gender, age, mediaType, ... }
       Response: { project: Project, projectFolder: ProjectFolder }

Una vez que todos los proyectos se crean exitosamente:

  4. PUT /status/mark-as-in-progress/{projectFolderId}
       — Cambia el estado del ProjectFolder a IN_PROGRESS

  5. PUT /generated-images/tag-faceswap/{projectFolderId}   ← solo FACESWAP
       — Etiqueta las imágenes de bypass (fotos originales que no se procesarán con AI)
       Response: { jobId: string }

Estado resultante

ProjectFolder.clientStatus  = CREATING  →  IN_PROGRESS
ProjectFolder.adminStatus   = CREATING  →  IN_PROGRESS
ProjectImage.adminStatus    = IN_PROGRESS  (listo para generar)

El admin recibe una notificación (ADMIN_PROJECT_CREATED) cuando el caso queda creado.

Secuencia técnica

Resumen de endpoints

Notas importantes

• El Excel es procesado y validado en el backend (/excel/projects/validate) antes de avanzar al siguiente paso. Los errores de formato o columnas faltantes se detectan en este punto.
• Si el cliente no tiene el permiso PROJECT_CREATOR, el botón “Nuevo proyecto” no aparece en la UI.
• Un ProjectFolder contiene múltiples Project (uno por marca) si el Excel incluye varias marcas.
• Las imágenes nunca pasan por el backend; se suben directamente a GCS usando signed URLs de corta duración.
• El proceso de creación corre en background: el usuario puede navegar a otra sección mientras los proyectos se crean. Al completarse exitosamente, se redirige a /projects?created=true.