UI Carga de Evidencia + Validación FARO Connect

export type EvidenceStatus =
  | "submitted"
  | "approved"
  | "rejected"
  | "needs_more_info"
  | "archived";

export type EvidenceTrustLevel = "low" | "medium" | "high" | "critical";

export type EvidenceDefinitionForUpload = {
  evidence_code: string;
  name: string;
  description: string;
  evidence_type: string;
  trust_level: EvidenceTrustLevel;
  allowed_submission_modes: string[];
  allowed_file_types: string[];
  required_metadata_keys: string[];
  requires_review: boolean;
  can_close_action: boolean;
  validation_rules: Record<string, unknown>;
};

export type EvidenceUploadRequest = {
  action_id: string;
  evidence_code: string;
  title: string;
  description?: string;
  metadata: Record<string, unknown>;
  submit_for_review: boolean;
};

export type EvidenceReviewAction = {
  review_comment: string;
};

POST /api/v1/actions/23000000-0000-0000-0000-000000000001/evidence
Content-Type: multipart/form-data; boundary=----faro

------faro
Content-Disposition: form-data; name="evidence_code"

EVD-007
------faro
Content-Disposition: form-data; name="title"

Política de descuentos comerciales mayo 2026
------faro
Content-Disposition: form-data; name="description"

Se adjunta política revisada y aprobada por dirección.
------faro
Content-Disposition: form-data; name="metadata"

{"policy_name":"Política de descuentos comerciales",
 "approved_by":"12000000-0000-0000-0000-000000000001",
 "effective_from":"2026-06-01",
 "scope":"Comercial · todas las sucursales"}
------faro
Content-Disposition: form-data; name="submit_for_review"

true
------faro
Content-Disposition: form-data; name="file"; filename="politica-descuentos-2026.pdf"
Content-Type: application/pdf

<binary PDF data>
------faro--

// EVD-007 · Cambio de política
{
  "policy_name": "Política de descuentos comerciales",
  "approved_by": "12000000-0000-0000-0000-000000000001",
  "effective_from": "2026-06-01",
  "scope": "Comercial · todas las sucursales"
}

// EVD-003 · Registro de aprobación
{
  "approved_by": "12000000-0000-0000-0000-000000000003",
  "approved_at": "2026-05-30T15:30:00-03:00",
  "approval_scope": "Comercial · descuentos mayores a 12%"
}

// EVD-012 · Validación de dirección
{
  "validated_by": "12000000-0000-0000-0000-000000000099",
  "validated_at": "2026-05-30T16:00:00-03:00",
  "validation_scope": "Cambio de política comercial Q3 2026"
}

// EVD-006 · Comprobante externo
{
  "provider": "Distribuidora Cuyo S.A.",
  "document_id": "FAC-2026-04582",
  "amount": "482350.00"
}

// EVD-011 · Cliente / proveedor contactado
{
  "contact_name": "Cliente Demo Norte",
  "contact_date": "2026-05-29",
  "channel": "email",
  "outcome": "Aceptó nueva política · firma pendiente"
}

import type {
  EvidenceReviewAction,
  EvidenceUploadResponse
} from "./evidence.types";

export async function uploadActionEvidence(params: {
  actionId: string;
  evidenceCode: string;
  title: string;
  description?: string;
  metadata: Record<string, unknown>;
  file?: File | null;
  submitForReview: boolean;
}): Promise<EvidenceUploadResponse> {
  const formData = new FormData();

  formData.set("evidence_code", params.evidenceCode);
  formData.set("title", params.title);
  formData.set("description", params.description ?? "");
  formData.set("metadata", JSON.stringify(params.metadata));
  formData.set("submit_for_review", String(params.submitForReview));

  if (params.file) {
    formData.set("file", params.file);
  }

  const response = await fetch(`/api/v1/actions/${params.actionId}/evidence`, {
    method: "POST",
    body: formData
  });

  if (!response.ok) {
    const error = await response.json().catch(() => null);
    throw new Error(error?.message ?? "No se pudo cargar la evidencia");
  }

  return response.json();
}

import type { EvidenceDefinitionForUpload } from "./evidence.types";

export function validateEvidenceClientSide(params: {
  definition: EvidenceDefinitionForUpload;
  title: string;
  metadata: Record<string, unknown>;
  file: File | null;
}): string[] {
  const errors: string[] = [];

  if (!params.title.trim()) {
    errors.push("El título es obligatorio.");
  }

  for (const key of params.definition.required_metadata_keys ?? []) {
    const value = params.metadata[key];

    if (value === undefined || value === null || String(value).trim() === "") {
      errors.push(`Falta completar: ${humanizeKey(key)}.`);
    }
  }

  const requiresFile = evidenceUsuallyRequiresFile(params.definition.evidence_code);

  if (requiresFile && !params.file) {
    errors.push("Este tipo de evidencia requiere archivo.");
  }

  if (params.file && params.definition.allowed_file_types.length > 0) {
    const ext = params.file.name.split(".").pop()?.toLowerCase();
    if (!ext || !params.definition.allowed_file_types.includes(ext)) {
      errors.push(`Formato no permitido. Permitidos: ${params.definition.allowed_file_types.join(", ")}.`);
    }
  }

  if (params.file && params.file.size > 25 * 1024 * 1024) {
    errors.push("El archivo supera el máximo permitido de 25 MB.");
  }

  return errors;
}

{
  "ok": true,
  "evidence": {
    "evidence_id": "24000000-0000-0000-0000-000000000099",
    "evidence_code": "EVD-007",
    "title": "Política de descuentos comerciales mayo 2026",
    "status": "submitted",
    "submitted_at": "2026-05-30T15:30:00-03:00"
  },
  "action": {
    "action_id": "23000000-0000-0000-0000-000000000001",
    "status": "in_review",
    "can_close": false
  }
}

{
  "ok": true,
  "evidence": {
    "evidence_id": "24000000-0000-0000-0000-000000000099",
    "status": "approved"
  },
  "action": {
    "action_id": "23000000-0000-0000-0000-000000000001",
    "can_close": true,
    "blocking_reasons": []
  }
}

{
  "ok": true,
  "evidence": {
    "evidence_id": "24000000-0000-0000-0000-000000000099",
    "status": "rejected"
  },
  "action": {
    "action_id": "23000000-0000-0000-0000-000000000001",
    "status": "waiting_evidence"
  }
}