Imágenes en pasos de caso

Los pasos de un caso pueden incluir varias imágenes (PNG, JPEG o WebP). El servidor las procesa a WebP (tamaño completo, borde largo ≤ 2048px, conservando proporción) y genera una miniatura (borde largo ≤ 320px).

El acceso es el mismo que editar pasos del caso: cualquier miembro autenticado de la organización que pueda guardar pasos puede hacer stage, commit y borrar adjuntos. No está limitado a owner/admin del proyecto (a diferencia de los avatares de proyecto).

Flujo

1. Stage — POST /api/v1/test-cases/{caseUlid}/step-attachments:stage con multipart/form-data y una o más partes file. El servidor escribe en staging/<orgUlid>/ y devuelve referencias staged (sin fila en base de datos).
2. Commit — Incluye esas referencias en cada paso de POST /api/v1/projects/{projectUlid}/test-cases (crear) o PUT /api/v1/test-cases/{caseUlid}/steps (reemplazar). El servidor copia staging → claves permanentes, inserta filas y elimina los objetos staged.
3. Lectura — GET /api/v1/test-cases/{caseUlid}/steps (y el GET consolidado del caso) devuelve attachments[] por paso con claves permanentes. Las miniaturas se sirven en GET /__assets/{thumbKey} (misma ruta pública que avatares).

Los objetos staged abandonados expiran con una regla de lifecycle de R2 sobre el prefijo staging/ (~48 horas).

Stage (multipart)

curl -sS -X POST \
  -H "Authorization: Bearer $PROBARA_API_TOKEN" \
  -F "file=@captura-a.png" \
  -F "file=@captura-b.png" \
  "https://probara.net/api/v1/test-cases/01J...CASE/step-attachments:stage"

200 (ejemplo):

{
  "attachments": [
    {
      "ulid": "01J...ATT",
      "objectKey": "staging/01J...ORG/01J...UPLOAD.webp",
      "thumbKey": "staging/01J...ORG/01J...UPLOAD_thumb.webp",
      "mime": "image/webp",
      "byteSize": 8420,
      "width": 1200,
      "height": 800,
      "originalFilename": "captura-a.png"
    }
  ]
}

Límites:

• Hasta 10 partes file por petición
• 10 MiB por archivo antes del procesamiento
• MIME permitidos: image/png, image/jpeg, image/webp

422 si hay demasiados archivos, MIME no permitido o imagen inválida. 404 si el caso no pertenece a la organización activa.

Commit al guardar pasos

Cada paso del payload de reemplazo puede llevar attachments:

{
  "steps": [
    {
      "ulid": "01J...STEP",
      "position": 1,
      "action": "Abrir ajustes",
      "attachments": [
        {
          "ulid": "01J...ATT",
          "position": 0,
          "objectKey": "staging/01J...ORG/01J...UPLOAD.webp",
          "thumbKey": "staging/01J...ORG/01J...UPLOAD_thumb.webp",
          "mime": "image/webp",
          "byteSize": 8420,
          "width": 1200,
          "height": 800,
          "originalFilename": "captura-a.png"
        }
      ]
    }
  ]
}

Reconciliación por ulid del adjunto:

Payload	Acción del servidor
ULID nuevo + claves staging/<esta-org>/	Copia a attachments/<orgUlid>/<projectUlid>/steps/<stepUlid>/<attUlid>.webp, inserta fila, borra staged
ULID existente (ya guardado)	Conserva objetos; solo actualiza position
Fila existe pero ULID ausente	Borra fila, borra objetos permanentes, decrementa contador de almacenamiento

El servidor no confía en byteSize, width ni height del cliente en el commit — vuelve a medir los objetos en R2. Las claves staged deben coincidir con el prefijo de la organización solicitante; referencias cross-tenant se rechazan.

POST /api/v1/projects/{projectUlid}/test-cases acepta la misma forma de attachments por paso al crear.

Borrar un adjunto

curl -sS -X DELETE \
  -H "Authorization: Bearer $PROBARA_API_TOKEN" \
  "https://probara.net/api/v1/test-cases/01J...CASE/step-attachments/01J...ATT"

204 si ok. 404 si el adjunto o el caso no existen.

Contabilidad de almacenamiento

Los bytes confirmados (completo + miniatura) incrementan organization_storage_usage con categoría step_attachment. Los bytes en staging no cuentan. Aún no hay cuotas; el contador prepara tiers futuros.

Relacionado

• Referencia API — paginación, errores, PATCH consolidado
• Referencia interactiva v1 — esquemas completos