Saltar al contenido principal

Proyectos

Sistema de gestión de proyectos en Floutic.

Características​

  • Creación de proyectos (requiere email verificado, perfil completo, perfil verificado y datos fiscales)
  • Sistema de aplicaciones
  • Selección de expertos
  • Gestión de estados
  • Sistema de hitos

Requisitos para Crear Proyectos​

Para crear un proyecto, el usuario empresa debe cumplir con los siguientes requisitos (en orden de verificación):

  1. Email verificado: El email debe estar verificado (email_verified = true)
  2. Perfil completo: Debe existir un perfil de empresa completo
  3. Perfil verificado: El perfil debe estar verificado por un administrador (is_verified = true)
  4. Datos fiscales: Para el primer proyecto, se requieren datos fiscales completos (CIF, país, etc.). La validación se realiza tanto en frontend (Zod) como en backend (Pydantic).
  5. Formato de Fecha: El campo deadline debe enviarse como ISO datetime (YYYY-MM-DDTHH:MM:SS).
  6. Validación de Fecha Límite: La fecha límite no puede ser anterior a la fecha actual. Esta validación se aplica tanto en frontend (atributo min en input de fecha y validación en formulario) como en backend (validación en endpoints de creación/actualización).

Estructura Modular​

Los endpoints de proyectos están organizados en módulos especializados:

  • listing.py - Listado de proyectos (público y autenticado)
  • crud.py - Operaciones CRUD básicas (crear, leer, actualizar, eliminar)
  • applications.py - Gestión de aplicaciones de expertos
  • selection.py - Selección de expertos y pagos iniciales
  • workflow.py - Flujo de validación y curación (admin)
  • disputes.py - Gestión de disputas

Endpoints Principales​

Listado​

  • GET /api/projects/public - Listar proyectos públicos
  • GET /api/projects/ - Listar proyectos con filtros
  • GET /api/projects/my - Mis proyectos
  • GET /api/projects/all - Todos los proyectos (admin)

CRUD​

  • POST /api/projects/ - Crear proyecto. Soporta campo opcional status (draft o pending_publication). Si es pending_publication, el backend establece automáticamente validation_status="pending" y submitted_at=now().
  • GET /api/projects/{id} - Ver proyecto
  • PUT /api/projects/{id} - Actualizar proyecto
  • PATCH /api/projects/{id}/status - Cambiar estado
  • DELETE /api/projects/{id} - Eliminar proyecto

Aplicaciones y Selección​

  • POST /api/projects/{id}/apply - Aplicar a proyecto. Nota: La propuesta debe incluir una lista de proposed_milestones con al menos 3 hitos que sumen el total del proposed_budget.
  • GET /api/projects/{id}/my-application - Obtener mi propuesta para un proyecto (experto)
  • GET /api/projects/{id}/applications - Listar aplicaciones
  • POST /api/projects/{id}/applications/{application_id}/request-revision - Solicitar cambios a una propuesta (empresa). Cambia el estado a needs_revision y guarda feedback.
  • PUT /api/projects/{id}/applications/{application_id} - Re-enviar propuesta modificada (experto). Solo permitido si la propuesta está en needs_revision.
  • POST /api/projects/{id}/select/{expert_id} - Seleccionar experto
  • POST /api/projects/{id}/selection/cancel - Cancelar selección

Estados de propuesta (negociación)​

Las propuestas (ProjectApplication) soportan negociación antes de la selección:

  • pending: Propuesta enviada, pendiente de revisión por la empresa.
  • needs_revision: La empresa solicita cambios. Incluye feedback y revision_requested_at.
  • accepted: Propuesta aceptada (selección realizada).
  • rejected: Propuesta rechazada.

Campos relevantes:

  • attempt_number: Incrementa cada vez que el experto re-envía la propuesta.
  • feedback: Texto de la empresa con los cambios solicitados (se limpia al re-enviar).

Validación y Curación​

  • POST /api/projects/{id}/submit - Enviar para validación
  • POST /api/projects/{id}/validate - Validar proyecto (admin)
  • POST /api/projects/{id}/curate - Curar expertos (admin)
  • POST /api/projects/{id}/auto-curate - Auto-curación (admin)
  • GET /api/projects/{id}/curation-suggestions - Sugerencias de curación
  • POST /api/projects/{id}/request-budget - Solicitar presupuesto

Disputas​

  • POST /api/projects/{id}/dispute - Crear disputa
  • GET /api/projects/{id}/dispute - Obtener disputa activa/reciente

Máquina de estados y transiciones (Disputas)​

Estados de disputa (Dispute.status)​

  • open: disputa recién creada por empresa o experto.
  • in_review: disputa en mediación por admin.
  • resolved: disputa cerrada con decisión administrativa.
  • closed: estado de cierre final (reservado para flujos de cierre extendidos).

Transiciones válidas​

open -> in_review    (PUT /api/admin/disputes/{id}/mediate)
open -> resolved     (PUT /api/admin/disputes/{id}/resolve)
in_review -> resolved (PUT /api/admin/disputes/{id}/resolve)

Reglas:

  • Una disputa resolved o closed no puede volver a mediación.
  • Solo puede existir una disputa activa (open o in_review) por proyecto.

Side effects de estado (proyecto y pago)​

  • Al crear disputa:

    • Project.status cambia a disputed.
    • Si existe pago asociado en pending o held, pasa a disputed.

  • Al resolver disputa:

    • Dispute.status cambia a resolved.
    • Project.status vuelve a in_progress si estaba disputed.
    • Según resolution_action:
      • resolve_favor_expert / release_to_expert -> Payment.status = released y payout_status = transferred (si aplica).
      • resolve_favor_company / refund_company -> Payment.status = refunded y payout_status = pending.

  • Auditoría:

    • Se agregan entradas en project.admin_notes con prefijo [DISPUTE_EVENT].

Más Información​

Consulta la Documentación de la API para más detalles sobre cada endpoint.