# 🧱 PRD BACKEND – Floutic API (FastAPI + PostgreSQL + Stripe + GoHighLevel)
**Versión:** 2.0 – España
**Stack:** FastAPI · PostgreSQL · SQLAlchemy · Pydantic · Stripe · GoHighLevel · n8n · Redis
**Estado:** MVP Completado ✅ - Actualizado con Flujo de Contratación Avanzado

## 1. Objetivo
Construir la API central de Floutic con sistema de contratación curado: autenticación, usuarios, proyectos con validación administrativa, chat, pagos escrow y reputación con arquitectura escalable y segura.

## 1.1 Nuevo Flujo de Contratación Implementado ✅
- ✅ **Sistema de proyectos curados** con validación administrativa
- ✅ **Tres tipos de contratación:** privada, curada y desde perfil
- ✅ **Estados de proyecto avanzados** con flujo completo
- ✅ **Curación administrativa** para selección de expertos
- ✅ **Sistema de propuestas** con hitos definidos por expertos
- ✅ **Configuración Global de Tallaje** (XS-XL) gestionable desde admin
- ✅ **Validación de contenido** antes de publicación
- ✅ **Workflows administrativos** automatizados

## 1.1 Estado Actual del MVP ✅
- ✅ **Autenticación dual** (JWT estándar + cookies HttpOnly seguras)
- ✅ **Gestión completa de usuarios** y perfiles (empresa/experto/admin)
- ✅ **Sistema de proyectos** con 18 endpoints (públicos, privados, curados)
- ✅ **Chat interno** con archivos, edición y moderación
- ✅ **Pagos Escrow** con Stripe Connect (PaymentIntent inicial al contratar, sincronización `pending → held`, captura, deferred payout scheduler y reintentos automáticos)
- ✅ **Sistema de reseñas** y reputación con estadísticas
- ✅ **Sistema de hitos** para pagos parciales y entregas
- ✅ **Búsqueda de expertos** con filtros avanzados
- ✅ **Panel de administración** con 28 endpoints (métricas, exportación, gestión avanzada)
- ✅ **Integración completa con GoHighLevel** (contactos, oportunidades, etiquetas)
- ✅ **WebSocket** para notificaciones en tiempo real
- ✅ **Dashboard de experto** con estadísticas y aplicaciones
- ✅ **Tests exhaustivos** (843+ tests en 28+ archivos)
- ✅ **Tests de autenticación segura habilitados**: 7 tests previamente omitidos ahora funcionan correctamente

## 2. Arquitectura Real Implementada
```
/app
 ├── api/v1/endpoints/     # 11 módulos de endpoints
 │   ├── auth.py           # Autenticación JWT estándar
 │   ├── auth_secure.py    # Autenticación con cookies HttpOnly
 │   ├── users.py          # Gestión de usuarios
 │   ├── profiles.py       # Perfiles empresa/experto (11 endpoints)
 │   ├── projects.py       # Proyectos y matching (18 endpoints)
 │   ├── chat.py           # Sistema de mensajería (6 endpoints)
│   ├── payments.py       # Pagos y escrow (8 endpoints)
 │   ├── reviews.py        # Reseñas y reputación (7 endpoints)
 │   ├── milestones.py     # Hitos y entregas (8 endpoints)
 │   ├── admin.py          # Panel administrativo (28 endpoints)
 │   ├── ghl_integration.py # Integración GoHighLevel (6 endpoints)
 │   ├── webhooks.py       # Webhooks externos
 │   ├── notifications.py  # Sistema de notificaciones
 │   ├── websocket.py      # WebSocket para tiempo real
 │   ├── expert_dashboard.py # Dashboard de experto (3 endpoints)
 │   └── placeholder.py    # Endpoints de prueba
 ├── models/               # 8 modelos de base de datos
 │   ├── user.py          # Usuarios y roles
 │   ├── profile.py       # Perfiles empresa/experto
 │   ├── project.py       # Proyectos y aplicaciones
 │   ├── chat.py          # Mensajería
 │   ├── payment.py       # Pagos y escrow
 │   ├── review.py        # Reseñas y reputación
 │   ├── milestone.py     # Hitos y entregas
 │   ├── notification.py  # Notificaciones
 │   ├── ghl_sync_log.py  # Logs de sincronización GHL
 │   ├── project_invitation.py # Invitaciones a proyectos
 │   └── system_config.py # Configuración global del sistema
 ├── schemas/              # 8 esquemas Pydantic
 ├── services/             # 8 servicios especializados
 │   ├── ghl_service.py    # Integración GoHighLevel
 │   ├── stripe_service.py # Pagos con Stripe
 │   ├── notification_manager.py # Gestión de notificaciones
 │   ├── webhook_service.py # Procesamiento de webhooks
 │   ├── email_service.py  # Envío de emails
 │   ├── expert_curation_service.py # Curación de expertos
 │   ├── invitation_service.py # Gestión de invitaciones
 │   └── webhook_service.py # Servicios de webhook
 └── core/                 # Configuración y seguridad
     ├── security.py      # JWT, hash, validación
     ├── config.py        # Configuración de la aplicación
     └── database.py      # Conexión a PostgreSQL
```

## 3. Roles y Permisos Actualizados

### 3.1 Sistema de Roles Múltiples
- **Roles múltiples**: Los usuarios pueden tener múltiples roles simultáneamente (`roles` array en base de datos)
- **Rol activo**: Cada usuario tiene un `active_role` que determina qué dashboard y funcionalidades están disponibles
- **Cambio de rol**: Los usuarios pueden cambiar entre sus roles disponibles en cualquier momento
- **Gestión por admin**: Los administradores pueden añadir, eliminar o cambiar roles de usuarios

### 3.2 Roles Principales
- **Empresa (Cliente):** Crear proyectos, revisar propuestas, aprobar entregas, pagar
- **Experto:** Enviar propuestas, definir hitos, ejecutar proyectos, completar entregas
- **Administrador Floutic:** Validar proyectos, seleccionar expertos, publicar, mediar, supervisar, gestionar roles de usuarios

### 3.2 Nuevos Permisos por Rol

#### Empresa
- ✅ Crear borradores de proyecto (requiere perfil verificado)
- ✅ Solicitar presupuesto desde perfil de experto
- ✅ Revisar propuestas de expertos
- ✅ Aprobar/rechazar entregas
- ✅ Liberar pagos por hitos
- ✅ Valorar expertos tras completar proyecto
- ⚠️ **Restricción:** Solo empresas con perfil verificado (`is_verified=True`) pueden crear proyectos

#### Experto
- ✅ Enviar propuestas con hitos definidos
- ✅ Definir plan de trabajo y presupuesto
- ✅ Completar hitos y marcar como entregado
- ✅ Comunicarse con empresa vía chat
- ✅ Valorar empresa tras completar proyecto

#### Administrador Floutic
- ✅ **Validar proyectos** antes de publicación
- ✅ **Seleccionar expertos** para proyectos curados (3-5 expertos)
- ✅ **Publicar proyectos** (privados o curados)
- ✅ **Mediar disputas** entre empresa y experto
- ✅ **Supervisar** ejecución de proyectos
- ✅ **Gestionar** sistema de reputación
- ✅ **Gestionar roles de usuarios** - Añadir, eliminar o cambiar roles y rol activo de cualquier usuario

## 4. Tipos de Contratación Implementados

### 4.1 Proyecto Privado (Empresa conoce al experto)
- ✅ Empresa selecciona experto específico
- ✅ Admin valida y publica como **privado**
- ✅ Solo visible para el experto seleccionado
- ✅ Flujo: propuesta → aprobación → escrow
- **Uso:** Relaciones previas o clientes recurrentes

### 4.2 Proyecto Curado (Sin experto asignado)
- ✅ Empresa crea borrador general
- ✅ Admin revisa y selecciona 3-5 expertos cualificados
- ✅ Publicación **curada** (solo visible para expertos invitados)
- ✅ Expertos envían propuestas y empresa elige
- **Uso:** Empresas nuevas o sin conocimiento técnico

### 4.3 Contratación desde Perfil
- ✅ Empresa navega perfiles y pulsa "Solicitar presupuesto"
- ✅ Se genera borrador con ese experto
- ✅ Admin valida antes de publicar
- **Uso:** Descubrimiento directo desde marketplace

## 5. Estados de Proyecto Actualizados

| Estado | Descripción | Actor Responsable | Siguiente Estado |
|--------|-------------|-------------------|------------------|
| `draft` | Borrador guardado por la empresa | Empresa | `pending_publication` |
| `pending_publication` | Enviado y en revisión administrativa | Admin | `published_private`/`published_curated` |
| `published_private` | Publicado (privado) | Admin | `bidding` |
| `published_curated` | Publicado (curado) | Admin | `bidding` |
| `bidding` | Recibiendo propuestas | Expertos | `assigned` |
| `assigned` | Propuesta aceptada | Empresa | `in_progress` |
| `in_progress` | En ejecución | Experto | `in_review` |
| `in_review` | En revisión | Empresa | `completed`/`in_progress` |
| `completed` | Finalizado | Ambos | - |
| `disputed` | Mediación | Admin | `in_progress`/`completed` |

## 6. Módulos principales
- **Autenticación JWT** con refresh tokens y rate limiting
- **Perfiles** de empresa y experto con validación
- **Gestión de proyectos** con curación administrativa
- **Chat interno** controlado y moderado
- **Pagos Escrow** con Stripe Connect (intentos automáticos por hito, endpoint de sincronización, liberación encadenada y deferred payout scheduler para transferencias diferidas)
- **Sistema de reseñas** y reputación
- **Integraciones** (GHL, n8n, Stripe) con retry policies

## 7. Endpoints Implementados ✅
| Módulo | Endpoint | Método | Descripción | Auth | Estado |
|---------|-----------|--------|--------------|------|--------|
| **Auth** | /api/auth/register | POST | Registro usuario con email (soporta múltiples roles) | No | ✅ |
| **Auth** | /api/auth/login | POST | Login y token JWT | No | ✅ |
| **Auth** | /api/auth/refresh | POST | Renovar token | Refresh | ✅ |
| **Auth** | /api/auth/logout | POST | Cerrar sesión | JWT | ✅ |
| **Auth** | /api/auth/verify | GET | Verificar token | JWT | ✅ |
| **Auth** | /api/auth/add-role | POST | Añadir nuevo rol al usuario autenticado | JWT | ✅ |
| **Auth** | /api/auth/switch-role | POST | Cambiar rol activo del usuario | JWT | ✅ |
| **Users** | /api/users/me | GET/PUT | Perfil propio | JWT | ✅ |
| **Users** | /api/users/{id} | GET | Ver perfil público | JWT | ✅ |
| **Profiles** | /api/profiles/{id} | GET/PUT | Ver/editar perfil | JWT | ✅ |
| **Profiles** | /api/profiles/upload | POST | Subir documentos | JWT | ✅ |
| **Profiles** | /api/profiles/experts | GET | Buscar expertos con filtros | JWT | ✅ |
| **Profiles** | /api/profiles/{id}/fiscal-data | PUT | Actualizar datos fiscales | JWT | ✅ |
| **Profiles** | /api/profiles/me/fiscal-status | GET | Verificar estado de datos fiscales | JWT | ✅ |
| **Projects** | /api/projects/ | GET/POST | Listar/crear proyectos. Soporta campo `status` (`draft` o `pending_publication`). Requiere perfil verificado y datos fiscales completos. Si el proyecto se crea para publicar, se activan automáticamente los metadatos de validación. | JWT | ✅ |
| **Projects** | /api/projects/{id} | GET/PUT/DELETE | Gestionar proyecto | JWT | ✅ |
| **Projects** | /api/projects/{id}/apply | POST | Aplicar a proyecto | JWT | ✅ |
| **Projects** | /api/projects/{id}/select/{expert_id} | POST | Seleccionar experto (requiere datos fiscales del experto si es primer proyecto) | JWT | ✅ |
| **Projects** | /api/projects/search/ | GET | Buscar proyectos (con trailing slash) | JWT | ✅ |
| **Chat** | /api/chat/{project_id} | GET/POST | Mensajería | JWT | ✅ |
| **Chat** | /api/chat/{project_id}/files | POST | Subir archivos | JWT | ✅ |
| **Payments** | /api/payments/initiate | POST | Crear PaymentIntent | JWT | ✅ |
| **Payments** | /api/payments/release | POST | Liberar pago | JWT | ✅ |
| **Payments** | /api/payments/release-and-charge-next | POST | Liberar pago y generar el siguiente PaymentIntent | JWT | ✅ |
| **Payments** | /api/payments/sync-status | POST | Sincronizar estado del PaymentIntent con Stripe | JWT | ✅ |
| **Payments** | /api/payments/dispute | POST | Crear disputa | JWT | ✅ |
| **Payments** | /api/payments/history | GET | Historial pagos | JWT | ✅ |
| **Stripe Connect** | /api/stripe-connect/status | GET | Verificar estado de cuenta Connect del experto | JWT (Experto) | ✅ |
| **Stripe Connect** | /api/stripe-connect/account-link | POST | Generar enlace de onboarding Express | JWT (Experto) | ✅ |
| **Stripe Connect** | /api/stripe-connect/account-update-link | POST | Generar enlace para actualizar cuenta Connect (con fallback automático) | JWT (Experto) | ✅ |
| **Payments** | /api/payments/project/{project_id} | GET | Pagos de un proyecto | JWT | ✅ |
| **Reviews** | /api/reviews | POST | Crear reseña | JWT | ✅ |
| **Reviews** | /api/reviews/user/{id} | GET | Reseñas de usuario | JWT | ✅ |
| **Reviews** | /api/reviews/stats/{id} | GET | Estadísticas reseñas | JWT | ✅ |
| **Reviews** | /api/reviews/{id} | GET/PUT/DELETE | Ver/editar/eliminar reseña | JWT | ✅ |
| **Reviews** | /api/reviews/{id}/respond | PUT | Responder reseña | JWT | ✅ |
| **Milestones** | /api/milestones | POST | Crear hito | Empresa | ✅ |
| **Milestones** | /api/milestones/project/{id} | GET | Listar hitos proyecto | JWT | ✅ |
| **Milestones** | /api/milestones/{id} | GET/PUT/DELETE | Ver/editar/eliminar hito | JWT | ✅ |
| **Milestones** | /api/milestones/{id}/complete | PUT | Completar hito | Experto | ✅ |
| **Milestones** | /api/milestones/{id}/approve | PUT | Aprobar hito | Empresa | ✅ |
| **Milestones** | /api/milestones/{id}/reject | PUT | Rechazar hito | Empresa | ✅ |
| **Admin** | /api/admin/users | GET | Listar usuarios con filtros (rol, estado, verificación, búsqueda) | Admin | ✅ |
| **Admin** | /api/admin/users/{id}/status | PUT | Activar/desactivar usuario | Admin | ✅ |
| **Admin** | /api/admin/users/{id}/verify | PUT | Verificar usuario/perfil | Admin | ✅ |
| **Admin** | /api/admin/users/{id}/unverify | PUT | Desverificar usuario/perfil | Admin | ✅ |
| **Admin** | /api/admin/users/{id}/roles | PUT | Gestionar roles de usuario (añadir, eliminar, cambiar rol activo) | Admin | ✅ |
| **Admin** | /api/admin/users/{id} | DELETE | Eliminar usuario | Admin | ✅ |
| **Admin** | /api/admin/projects | GET | Listar proyectos | Admin | ✅ |
| **Admin** | /api/admin/projects/{id}/status | PUT | Cambiar estado proyecto | Admin | ✅ |
| **Admin** | /api/admin/payments | GET | Listar pagos | Admin | ✅ |
| **Admin** | /api/admin/payments/{id}/refund | POST | Procesar reembolso | Admin | ✅ |
| **Webhooks** | /api/webhooks/stripe | POST | Webhook Stripe | Webhook | ✅ |
| **Webhooks** | /api/webhooks/ghl | POST | Webhook GHL | Webhook | ✅ |
| **Health** | /api/health | GET | Health check | No | ✅ |

### 7.1 Nuevos Endpoints para Flujo de Contratación ✅
| Módulo | Endpoint | Método | Descripción | Auth | Estado |
|---------|-----------|--------|--------------|------|--------|
| **Projects** | /api/projects/{id}/submit | POST | Enviar borrador para validación | Empresa | ✅ |
| **Projects** | /api/projects/{id}/validate | POST | Validar proyecto (admin) | Admin | ✅ |
| **Projects** | /api/projects/{id}/publish | POST | Publicar proyecto (admin) | Admin | ✅ |
| **Projects** | /api/projects/{id}/curate | POST | Seleccionar expertos para proyecto curado | Admin | ✅ |
| **Projects** | /api/projects/{id}/invite-experts | POST | Invitar expertos a proyecto curado | Admin | ✅ |
| **Projects** | /api/projects/{id}/request-budget | POST | Solicitar presupuesto desde perfil | Empresa | ✅ |
| **Projects** | /api/projects/{id}/propose | POST | Enviar propuesta con hitos | Experto | ✅ |
| **Projects** | /api/projects/{id}/deliver | POST | Marcar como entregado | Experto | ✅ |
| **Projects** | /api/projects/{id}/approve | POST | Aprobar entrega | Empresa | ✅ |
| **Projects** | /api/projects/{id}/request-revision | POST | Solicitar revisión | Empresa | ✅ |
| **Projects** | /api/projects/{id}/dispute | POST | Crear disputa | Ambos | ✅ |
| **Admin** | /api/admin/projects/pending | GET | Proyectos pendientes de validación | Admin | ✅ |
| **Admin** | /api/admin/projects/{id}/experts | GET | Expertos disponibles para proyecto | Admin | ✅ |
| **Admin** | /api/admin/projects/{id}/select-experts | POST | Seleccionar expertos para proyecto curado | Admin | ✅ |
| **Admin** | /api/admin/disputes | GET | Listar disputas | Admin | ✅ |
| **Admin** | /api/admin/disputes/{id}/resolve | POST | Resolver disputa | Admin | ✅ |

### 7.2 Nuevos Endpoints para Gestión Avanzada de Estados ✅
| Módulo | Endpoint | Método | Descripción | Auth | Estado |
|---------|-----------|--------|--------------|------|--------|
| **Admin** | /api/admin/users/{id}/reputation | GET | Obtener métricas de reputación | Admin | ✅ |
| **Admin** | /api/admin/users/{id}/internal-rating | PUT | Actualizar rating interno | Admin | ✅ |
| **Admin** | /api/admin/users/{id}/expert-level | PUT | Actualizar nivel de experto | Admin | ✅ |
| **Admin** | /api/admin/users/{id}/availability | PUT | Actualizar disponibilidad | Admin | ✅ |
| **Admin** | /api/admin/projects/{id}/validation-status | GET | Estado de validación | Admin | ✅ |
| **Admin** | /api/admin/projects/{id}/validation-status | PUT | Actualizar estado validación | Admin | ✅ |
| **Admin** | /api/admin/projects/{id}/project-type | PUT | Cambiar tipo de proyecto | Admin | ✅ |
| **Admin** | /api/admin/projects/{id}/invite-experts | POST | Invitar expertos a proyecto | Admin | ✅ |
| **Admin** | /api/admin/users/{id}/ghl-tags | GET | Obtener etiquetas GHL | Admin | ✅ |
| **Admin** | /api/admin/users/{id}/suspend-advanced | PUT | Suspensión avanzada | Admin | ✅ |
| **Admin** | /api/admin/metrics/advanced | GET | Métricas avanzadas | Admin | ✅ |

### 7.3 Nuevos Endpoints de Exportación y Gestión ✅
| Módulo | Endpoint | Método | Descripción | Auth | Estado |
|---------|-----------|--------|--------------|------|--------|
| **Admin** | /api/admin/export/users | GET | Exportar usuarios (CSV, JSON, XLSX) | Admin | ✅ |
| **Admin** | /api/admin/export/projects | GET | Exportar proyectos (CSV, JSON, XLSX) | Admin | ✅ |
| **Admin** | /api/admin/export/payments | GET | Exportar pagos (CSV, JSON, XLSX) | Admin | ✅ |
| **Admin** | /api/admin/payments/{id} | GET | Obtener pago específico | Admin | ✅ |
| **Admin** | /api/admin/health | GET | Estado de salud del sistema | Admin | ✅ |
| **Admin** | /api/admin/settings/sizing | GET/PUT | Configuración global de precios por talla | Admin | ✅ |

## 8. Integraciones detalladas
### Stripe
- **Escrow** con capture manual y disputas
- **Connect** para pagos a expertos
- **Webhooks** para eventos de pago
- **Retry policy** con backoff exponencial

### GoHighLevel
**URL de instalación:** https://app.suitesapiens.com/v2/location/fK4GiaVPEXaSURuTwtSj/dashboard

#### Pipelines Configurados:
1. **Empresas (Clientes)** - Etapas:
   - Registro nuevo → Cualificación/Brief → Proyecto publicado → Enviados expertos/Matching → En ejecución → Completado → Recurrente → Perdido/En pausa

2. **Expertos (Marketplace)** - Etapas:
   - Solicitud recibida → Pre-evaluación → Verificación documentos → Onboarding → Certificado (nivel asignado) → Activo → Rechazado/En pausa

#### Sistema de Etiquetas Actualizado:
- **Empresas:** emp-nuevo-registro, emp-borrador-creado, emp-proyecto-en-validación, emp-proyecto-publicado, emp-proyecto-en-ejecución, emp-proyecto-completado, emp-cliente-recurrente, emp-inactivo, emp-baja, emp-baja-confirmada, emp-recontacto
- **Expertos:** exp-solicitud, exp-pre-evaluación, exp-verificado, exp-nivel-global, exp-nivel-pro, exp-nivel-enterprise, exp-invitado-proyecto, exp-propuesta-enviada, exp-proyecto-asignado, exp-inactivo
- **Proyectos:** proj/borrador, proj/en-validación, proj/privado, proj/curado, proj/en-ejecución, proj/completado, proj/disputado
- **Fuente:** src/web, src/linkedin, src/ads, src/referral

#### Sistema Automático de Etiquetas GHL ✅
**Nuevo enfoque:** Las etiquetas se generan automáticamente basándose en los datos del usuario, eliminando la gestión manual.

**Reglas Automáticas Implementadas:**
- **Experto Verificado:** `role === "experto" && is_verified === true` → Etiqueta: "Experto Verificado"
- **Nivel Pro:** `expert_level === "Pro"` → Etiqueta: "Experto Pro"
- **Alto Rating:** `average_rating >= 4.5` → Etiqueta: "Alto Rating"
- **Empresa Activa:** `role === "empresa" && total_projects >= 5` → Etiqueta: "Empresa Activa"
- **Experto Activo:** `total_projects >= 10` → Etiqueta: "Experto Activo"
- **Activo Reciente:** `last_login > 7 días` → Etiqueta: "Activo Reciente"

**Ventajas del Sistema Automático:**
- ✅ **Consistencia:** Siempre aplica las mismas reglas
- ✅ **Escalabilidad:** Funciona con miles de usuarios
- ✅ **Eficiencia:** Se actualiza en tiempo real
- ✅ **Transparencia:** Logs de todas las acciones
- ✅ **Mantenimiento:** Sin intervención manual requerida

#### Workflows Automatizados Actualizados:

**Empresas:**
1. **EMP - Registro nuevo** - Bienvenida y creación de oportunidad
2. **EMP - Borrador creado** - Notificación de borrador pendiente de validación
3. **EMP - Proyecto en validación** - Recordatorio a admin para revisar
4. **EMP - Proyecto publicado** - Actualización de estado a Activo
5. **EMP - Proyecto en ejecución** - Notificación de inicio de trabajo
6. **EMP - Proyecto completado** - Cierre automático y marca como Won
7. **EMP - Sin actividad** - Detección de inactividad (30 días)
8. **EMP - Baja o Eliminado** - Proceso de baja automático
9. **EMP - Recontacto** - Reactivación de empresas dormidas

**Expertos:**
1. **EXP - Invitado a proyecto** - Notificación de invitación a proyecto curado
2. **EXP - Propuesta enviada** - Confirmación de propuesta enviada
3. **EXP - Proyecto asignado** - Notificación de selección para proyecto
4. **EXP - Proyecto completado** - Solicitud de valoración

#### Campos Personalizados:
- **Empresas:** Tipo de empresa, Sector, Tamaño, País, Idioma preferido, Estado cliente, Persona de contacto
- **Expertos:** Área principal, Nivel de servicio, País/Región, Idioma de trabajo, Experiencia, Certificación, Disponibilidad, Valoración media
- **Proyectos:** Título, Presupuesto estimado, Nivel recomendado, Urgencia, Estado, Hitos definidos, Valor final

#### Funcionalidades:
- **Contactos** automáticos al registro
- **Pipelines** según tipo de usuario
- **Sincronización** de datos de perfil
- **Webhooks** para actualizaciones
- **Envío de emails** automatizados (bienvenida, notificaciones, recordatorios)
- **Templates de email** gestionados desde GHL
- **Campañas de email** marketing y transaccionales
- **Notificaciones internas** al equipo por eventos
- **Gestión de oportunidades** con estados automáticos

### n8n
- **Automatizaciones** de métricas diarias
- **Recordatorios** de proyectos pendientes
- **Notificaciones** push (emails delegados a GHL)
- **Reportes** semanales y mensuales
- **Triggers** para envío de emails vía GoHighLevel
- **Workflows** de sincronización entre sistemas

## 8. Flujo de Trabajo Administrativo

1. **Empresa crea proyecto**:
   - Opción **"Guardar Borrador"** → Estado: `draft`. El proyecto queda guardado para edición posterior.
   - Opción **"Publicar Proyecto"** → Estado: `pending_publication`.
2. **Activación de Validación**:
   - Al cambiar a `pending_publication` (ya sea al crear o enviar después), el sistema establece automáticamente `validation_status="pending"` y `submitted_at=now()`.
   - Se dispara una notificación interna a los administradores.
3. **Admin revisa contenido** → Validación de calidad y viabilidad
4. **Admin determina tipo de publicación:**
   - **Privado:** Si empresa especifica experto → `published_private`
   - **Curado:** Si necesita selección de expertos → `published_curated`

### 8.2 Curación de Expertos
**Para proyectos curados:**
1. **Admin analiza requisitos** del proyecto
2. **Admin busca expertos** con skills matching
3. **Admin selecciona 3-5 expertos** cualificados
4. **Admin invita expertos** al proyecto
5. **Expertos reciben notificación** y pueden aplicar

### 8.3 Gestión de Disputas
**Proceso de mediación:**
1. **Cualquier parte crea disputa** → Estado: `disputed`
2. **Admin recibe notificación** de disputa (alerta en tiempo real + email de respaldo)
3. **Admin revisa evidencia** (chat, entregas, hitos)
4. **Admin toma decisión** y comunica a ambas partes
5. **Proyecto continúa** según decisión del admin

### 8.4 Dashboard Administrativo
**Métricas clave:**
- Proyectos pendientes de validación
- Tiempo promedio de validación
- Tasa de aprobación de proyectos
- Disputas activas y resueltas
- Performance de expertos por categoría
- Satisfacción de empresas

### 8.5 Webhooks personalizados por usuario
- Cada usuario puede registrar una URL HTTPS y un secreto propio para recibir las mismas notificaciones que aparecen en el centro interno.
- El backend envía eventos mediante **POST** con autenticación **JWT** (compatible con n8n HTTP Trigger con JWT Auth) o sin autenticación.
- **Métodos de autenticación:**
  - `jwt`: Token JWT en header `Authorization: Bearer <token>` (recomendado para n8n)
  - `none`: Sin autenticación (solo para desarrollo/pruebas)
- **Endpoints:**
  - `GET /api/users/me/webhook` → Obtener configuración actual.
  - `PUT /api/users/me/webhook` → Configurar URL, habilitar/deshabilitar y método de autenticación.
  - `GET /api/users/me/webhook/secret` → Obtener el secreto actual (para configurar en n8n).
  - `POST /api/users/me/webhook/secret` → Regenerar secreto (se muestra solo una vez).
  - `POST /api/notifications/webhook/test` → Envía notificación de prueba para validar el flujo.
- **Tipos de webhooks disponibles (16 tipos):**
  - `project_created`, `project_approved`, `project_rejected`
  - `expert_applied`, `expert_selected`
  - `project_invitation`, `invitation_accepted`, `invitation_declined`
  - `milestone_completed`, `milestone_approved`, `milestone_rejected`
  - `payment_released`
  - `dispute_created`, `dispute_resolved`
  - `message_received`
  - `system_announcement`
- **Cabeceras enviadas:**
  - `Content-Type: application/json`
  - `X-Floutic-Event: <tipo_notificacion>`
  - `X-Floutic-Timestamp: <timestamp>`
  - `X-Floutic-Retry-Attempt: <intento>`
  - `Authorization: Bearer <token_jwt>` (solo si auth_method es "jwt")
- **Configuración para n8n:**
  - Método HTTP: POST
  - Key Type: Secret
  - Algorithm: HS256
  - Secret: (el secreto del usuario, obtenible desde `/api/users/me/webhook/secret`)
- El sistema almacena el último estado (éxito o error) y el timestamp para mostrarlo en el dashboard del usuario.
- 📖 **Documentación completa:** Ver [docs/WEBHOOKS.md](docs/WEBHOOKS.md) para ejemplos de payloads, configuración detallada y troubleshooting.

### 8.6 Perfiles de administradores
- Los usuarios con rol `admin` pueden crear un perfil tipo `admin` reutilizando el mismo modelo (`profiles`) que empresas y expertos.
- Campos clave: `bio`, `skills`, `location`, `linkedin_url`, `phone`. Se generan slugs `admin-{id}` para uso futuro en la página pública del equipo.
- El flujo se gestiona desde el dashboard (misma API `/api/profiles`), pero se omite el webhook a GoHighLevel porque solo es material interno.

## 9. Seguridad avanzada
### Autenticación
- **JWT** con expiración de 15 minutos
- **Refresh tokens** con expiración de 7 días
- **Rate limiting** 5 intentos/minuto para login
- **Hash Argon2/pbkdf2** con configuración optimizada
- **Sesiones concurrentes** limitadas a 3
- **Validación de fortaleza** de contraseñas
- **Logs de auditoría** para intentos de login

### Autorización
- **RBAC** (Role-Based Access Control)
- **Middleware** de permisos por endpoint
- **Validación** de ownership de recursos
- **CORS** restringido a dominios específicos

### Protección de datos
- **Encriptación** de datos sensibles
- **Sanitización** de inputs con Pydantic
- **Validación** estricta de todos los campos
- **Logs** sin información sensible
- **Headers de seguridad** (HSTS, CSP, X-Frame-Options)

### Seguridad de red
- **HTTPS obligatorio** en producción
- **Rate limiting** por IP y endpoint
- **Trusted hosts** middleware
- **CORS** configurado por entorno

## 8. Testing y Calidad ✅ COMPLETADO
### Estrategia de testing implementada
- ✅ **486 tests unitarios** en 28 archivos de test
- ✅ **Tests de endpoints** para todos los módulos principales
- ✅ **Tests de integración** para flujos completos
- ✅ **Tests de servicios** para lógica de negocio
- ✅ **Tests de modelos** para validación de datos
- ✅ **Cobertura completa** de funcionalidades críticas

### Módulos con tests implementados
- ✅ **Autenticación** (auth.py, auth_secure.py)
- ✅ **Usuarios y perfiles** (users.py, profiles.py)
- ✅ **Proyectos** (projects.py, project_applications.py, project_validation.py)
- ✅ **Chat** (chat.py)
- ✅ **Pagos** (payments.py)
- ✅ **Reseñas** (reviews.py)
- ✅ **Hitos** (milestones.py)
- ✅ **Administración** (admin.py, admin_advanced.py, admin_verification.py)
- ✅ **Integraciones** (ghl_integration.py, webhooks.py)
- ✅ **Dashboard de experto** (expert_dashboard.py)
- ✅ **Servicios** (expert_curation_service.py, notification_manager.py)

### Validación implementada
- ✅ **Pydantic** para validación de datos en todos los endpoints
- ✅ **SQLAlchemy** para validación de base de datos
- ✅ **Custom validators** para reglas de negocio específicas
- ✅ **Error handling** estructurado con códigos HTTP apropiados
- ✅ **Validación de permisos** RBAC en todos los endpoints

## 9. Logs y Monitoreo
### Logging
- **Formato JSON** estructurado
- **Niveles:** DEBUG, INFO, WARNING, ERROR, CRITICAL
- **Correlation IDs** para tracing
- **Logs de auditoría** para acciones críticas

### Métricas
- **Prometheus** para métricas de sistema
- **Grafana** para dashboards
- **Alertas** para errores críticos
- **KPIs** de negocio (conversiones, retención)

## 10. Performance y Escalabilidad
### Cache
- **Redis** para cache de sesiones
- **Cache** de consultas frecuentes
- **TTL** configurable por tipo de dato
- **Invalidación** automática

### Optimización
- **Índices** optimizados en PostgreSQL
- **Connection pooling** con SQLAlchemy
- **Lazy loading** para relaciones
- **Paginación** en todos los listados

## 11. Despliegue y DevOps
### Docker Compose
```yaml
services:
  - backend (FastAPI)
  - postgres (PostgreSQL 15)
  - redis (Redis 7)
  - nginx (Reverse proxy)
```

### Variables de entorno
```bash
# Database
DATABASE_URL=postgresql://user:pass@localhost:5432/floutic
REDIS_URL=redis://localhost:6379/0

# Authentication
JWT_SECRET=your-super-secret-jwt-key
JWT_ALGORITHM=HS256
JWT_ACCESS_EXPIRE_MINUTES=15
JWT_REFRESH_EXPIRE_DAYS=7

# External APIs
STRIPE_SECRET_KEY=sk_live_xxx
STRIPE_WEBHOOK_SECRET=whsec_xxx
GHL_API_KEY=your-ghl-api-key
GHL_WEBHOOK_SECRET=your-ghl-webhook-secret

# n8n
N8N_WEBHOOK_URL=https://your-n8n-instance.com/webhook
N8N_API_KEY=your-n8n-api-key

# Security
CORS_ORIGINS=https://floutic.com,https://www.floutic.com
RATE_LIMIT_PER_MINUTE=60
MAX_CONCURRENT_SESSIONS=3

# Environment
ENVIRONMENT=production
LOG_LEVEL=INFO
DEBUG=false

# Monitoring
PROMETHEUS_PORT=8001
GRAFANA_URL=https://grafana.floutic.com
```

### CI/CD
- **GitHub Actions** para testing automático
- **Docker** para containerización
- **Deployment** automático a staging/prod
- **Rollback** automático en caso de errores

## 12. Compliance y Legal
### RGPD
- **Consentimiento** explícito para datos
- **Derecho al olvido** implementado
- **Portabilidad** de datos
- **Auditoría** de accesos

### Auditoría
- **Logs** de todas las transacciones
- **Trazabilidad** completa de pagos
- **Backup** diario de datos críticos
- **Recovery** plan documentado

## 13. Estado Actual y Funcionalidades Pendientes

### ✅ COMPLETADO (Diciembre 2025)
- ✅ **Sistema de autenticación dual** (JWT + cookies HttpOnly)
- ✅ **95+ endpoints** completamente implementados y testados
- ✅ **Integración completa con GoHighLevel** (contactos, oportunidades, etiquetas)
- ✅ **Sistema de notificaciones** con WebSocket en tiempo real
- ✅ **Dashboard de métricas avanzadas** con 28 endpoints administrativos
- ✅ **Sistema de disputas** con resolución administrativa
- ✅ **API de exportación** (usuarios, proyectos, pagos)
- ✅ **Sistema de backup** con migraciones automáticas
- ✅ **Rate limiting** implementado por endpoint
- ✅ **Caching con Redis** para sesiones y datos frecuentes
- ✅ **Optimización de consultas** con índices y relaciones optimizadas
- ✅ **Sistema de logs** estructurado con niveles apropiados
- ✅ **486 tests** con cobertura completa

### 🔄 PENDIENTE (Fase 3)
- 🔄 **Métricas de performance** con Prometheus y Grafana
- 🔄 **Sistema de alertas** automáticas para errores críticos
- 🔄 **API de reportes** avanzados para análisis de negocio
- 🔄 **Sistema de backup** distribuido y recovery automático
- 🔄 **Load balancing** automático basado en métricas
- 🔄 **Auto-scaling** de contenedores
- 🔄 **Sistema de monitoreo** 24/7 con alertas

### Fase 2.1 - Mejoras de Seguridad Críticas 🔒
- 🔄 **2FA (TOTP)** para usuarios con datos sensibles
- 🔄 **Rate limiting específico** para endpoints de autenticación
- 🔄 **Protección CSRF** con tokens
- 🔄 **Sistema de auditoría** completo con correlación de IDs
- 🔄 **Detección de anomalías** en intentos de login
- 🔄 **Bloqueo temporal** de cuentas tras múltiples intentos fallidos
- 🔄 **Rotación automática** de tokens y claves
- 🔄 **Monitoreo de seguridad** en tiempo real

### Fase 2.2 - Sistema de Gestión Avanzada de Estados ✅ COMPLETADA
- ✅ **Endpoints de reputación** - Gestión completa de métricas de reputación
- ✅ **Endpoints de niveles de experto** - Gestión de niveles Global/Pro/Enterprise
- ✅ **Endpoints de validación de proyectos** - Validación avanzada con estados
- ✅ **Endpoints de etiquetas GHL** - Sistema automático de etiquetas
- ✅ **Endpoints de métricas avanzadas** - KPIs detallados del sistema
- ✅ **Sistema de suspensión avanzada** - Suspensión con razón y duración
- ✅ **Gestión de disponibilidad** - Tiempo completo/Medio tiempo/Freelance
- ✅ **Rating interno** - Sistema de valoración interna de usuarios

### Fase 2.2 - Mejoras de Dashboard y UX (Octubre 24, 2025) ✅
- ✅ **Endpoint `/projects/my`** - Obtener proyectos del usuario autenticado
- ✅ **Paginación de proyectos** con respuesta estructurada
- ✅ **Schemas optimizados** para respuestas paginadas
- ✅ **Estado vacío amigable** en frontend cuando no hay proyectos
- ✅ **Optimización de Redis** para caché de sesiones
- ✅ **Tests completos** para nuevo endpoint

#### Nuevo Endpoint: GET /projects/my
```
GET /api/projects/my?page=1&size=20
Authorization: Bearer {token}

Response 200 OK:
{
  "items": [
    {
      "id": 1,
      "title": "Proyecto ejemplo",
      "description": "Descripción del proyecto",
      "budget": 5000.0,
      "status": "open",
      "created_at": "2025-10-24T10:00:00",
      "applications_count": 3
    }
  ],
  "total": 10,
  "page": 1,
  "size": 20,
  "pages": 1
}
```

**Características:**
- ✅ Autenticación requerida
- ✅ Filtra automáticamente por `company_id` del usuario
- ✅ Soporte de paginación con query params
- ✅ Incluye contador de aplicaciones por proyecto
- ✅ Ordenado por fecha de creación (más recientes primero)
- ✅ Logging completo para debugging

**IMPORTANTE - Orden de Rutas FastAPI:**
El endpoint `/my` debe estar **antes** de `/{project_id}` en el router para evitar que FastAPI intente interpretar "my" como un `project_id` entero, causando errores 422 de validación.

### Fase 3 - Funcionalidades Avanzadas
- 🔄 **Sistema de recomendaciones** ML para matching
- 🔄 **Análisis de sentimientos** en chat y reseñas
- 🔄 **Sistema de badges** y gamificación
- 🔄 **API de integración** con herramientas externas
- 🔄 **Sistema de plantillas** para proyectos
- 🔄 **Marketplace de servicios** adicionales
- 🔄 **Sistema de afiliados** y referidos
- 🔄 **API de webhooks** para integraciones externas
- ✅ **Sistema de templates de email** gestionado desde GoHighLevel
- 🔄 **Dashboard de analytics** para empresas

### Fase 4 - Escalabilidad y Enterprise
- 🔄 **Multi-tenancy** para diferentes organizaciones
- 🔄 **Sistema de roles** granular por módulo
- 🔄 **API de white-label** para partners
- 🔄 **Sistema de auditoría** completo
- 🔄 **Compliance** con estándares internacionales
- 🔄 **Sistema de backup** distribuido
- 🔄 **Load balancing** automático
- 🔄 **Auto-scaling** basado en métricas
- 🔄 **Sistema de monitoreo** 24/7
- 🔄 **SLA** y soporte enterprise

### Funcionalidades Técnicas Pendientes
- 🔄 **Migración de base de datos** automática
- 🔄 **Sistema de versionado** de API
- 🔄 **Documentación automática** con OpenAPI
- 🔄 **Tests de carga** con Locust
- 🔄 **Sistema de CI/CD** completo
- 🔄 **Containerización** con Docker Compose
- 🔄 **Orquestación** con Kubernetes
- 🔄 **Sistema de secrets** management
- 🔄 **Monitoring** con Grafana
- 🔄 **Alerting** automático

---

## 14. Mejoras Recientes (Octubre 2025)

### 🎯 Correcciones de la Semana

1. **Trailing Slash en Endpoints** ✅
   - Corregido comportamiento de FastAPI con trailing slashes
   - Evita redirects 307 innecesarios
   - Mejora compatibilidad con clientes móviles
   - Endpoints afectados:
     - `/api/projects/` (GET con query params)
     - `/api/projects/search/` (GET con query params)
     - `/api/projects/my/` (GET con query params)
     - `/api/projects/applications/` (GET con query params)

2. **Respuestas API Consistentes** ✅
   - Endpoints de listado devuelven arrays directos
   - Eliminada inconsistencia entre respuestas paginadas y arrays
   - Simplifica manejo en frontend
   - Endpoints afectados:
     - `/api/projects/` → Array de proyectos
     - `/api/profiles/experts` → Array de expertos

3. **Compatibilidad con Desarrollo Móvil** ✅
   - Backend escucha en `0.0.0.0` para acceso desde red local
   - CORS configurado para IPs locales y dominios oficiales

### 🐛 Bugs Corregidos
- ✅ Redirect 307 en endpoints con query params sin trailing slash
- ✅ Inconsistencia en formato de respuestas (array vs objeto paginado)
- ✅ CORS bloqueando peticiones desde IP local en desarrollo

### 📝 Notas Técnicas
- **FastAPI Behavior**: Por defecto, FastAPI redirige URLs sin trailing slash a URLs con trailing slash cuando hay query parameters
- **Solución Frontend**: URLs del frontend actualizadas para incluir trailing slash en endpoints con query params
- **Compatibilidad**: Cambios retrocompatibles, no afectan a clientes existentes

### 🔍 Áreas de Mejora Identificadas
- ⚠️ Considerar implementar respuestas paginadas consistentes para todos los endpoints de listado
- ⚠️ Documentar comportamiento de trailing slash en OpenAPI/Swagger
- ⚠️ Agregar tests para verificar comportamiento con/sin trailing slash

### 📧 Arquitectura de Emails
**Decisión de Diseño:** Los emails transaccionales se envían desde el **backend de FastAPI** usando templates Jinja2 y SMTP. Los emails de marketing y campañas se gestionan desde **GoHighLevel**.

**Razones:**
- ✅ Control total sobre emails transaccionales críticos (bienvenida, match, hitos, pagos)
- ✅ Templates versionados en código (Jinja2) con revisión y tests
- ✅ Envío inmediato y confiable para eventos críticos
- ✅ Integración directa con la lógica de negocio
- ✅ GHL se usa para campañas de marketing y newsletters (no críticos)

**Flujo de Emails Transaccionales:**
1. Backend detecta evento (registro, proyecto completado, match, etc.)
2. `EmailService` renderiza template Jinja2 con contexto
3. Se envía email vía SMTP directamente desde el backend
4. Se genera versión texto plano automáticamente

**Tipos de Emails Gestionados por el Backend:**
- 📧 **Bienvenida:**
  - Email genérico (`welcome.html`)
  - Bienvenida empresas (`welcome_company.html`) - Incluye sesión Discovery
  - Bienvenida expertos (`welcome_expert.html`) - Incluye proceso de verificación
- 📧 **Match y selección:**
  - Match confirmado empresas (`match_confirmed_company.html`)
  - Match confirmado expertos (`match_confirmed_expert.html`)
  - Experto seleccionado (`expert_selected.html`)
  - Invitación a proyecto (`expert_invited.html`)
- 📧 **Proyectos:**
  - Nueva aplicación (`project_application.html`)
  - Proyecto aprobado/rechazado (`project_approved.html`, `project_rejected.html`)
- 📧 **Hitos:**
  - Hito completado (`milestone_completed.html`)
  - Hito aprobado (`milestone_approved.html`)
  - Hito rechazado (`milestone_rejected.html`)
- 📧 **Pagos:**
  - Pago liberado (`payment_released.html`)
  - Pago recibido (`payment_received.html`)
- 📧 **Reseñas:**
  - Solicitud de reseña post-proyecto (`request_review.html`) - Se envía automáticamente al completar proyecto
  - Reseña recibida (`review_received.html`)
- 📧 **Otros:**
  - Verificación de email (`verify_email.html`)
  - Recuperación de contraseña (`password_reset.html`)
  - Disputa (`dispute_notification.html`)
  - Mensaje recibido (`message_received.html`)

**Tipos de Emails Gestionados por GHL (Marketing):**
- 📧 Campañas de marketing
- 📧 Newsletters y actualizaciones
- 📧 Seguimiento post-proyecto (opcional, complementa emails transaccionales)

### 🔗 Integración Backend ↔ GoHighLevel

**Eventos que el Backend debe enviar a GHL:**

| Evento en Floutic | Etiqueta GHL | Acción en GHL |
|-------------------|--------------|---------------|
| Usuario empresa se registra | `emp-nuevo-registro` | Workflow: EMP - Registro nuevo |
| Empresa publica proyecto | `emp-proyecto-publicado` | Workflow: EMP - Proyecto publicado |
| Proyecto en ejecución | `emp-proyecto-en-ejecución` | Actualiza pipeline a "En ejecución" |
| Proyecto completado | `emp-proyecto-completado` | Workflow: EMP - Proyecto cerrado |
| Empresa sin actividad 30 días | `emp-inactivo` | Workflow: EMP - Sin actividad |
| Empresa solicita baja | `emp-baja` | Workflow: EMP - Baja o Eliminado |
| Usuario experto se registra | `exp-solicitud` | Crea oportunidad en pipeline Expertos |
| Experto verificado | `exp-verificado` | Mueve a etapa "Certificado" |
| Experto asignado nivel | `exp-nivel-{global\|pro\|enterprise}` | Actualiza campo personalizado |

**Campos a sincronizar con GHL:**

**Empresas:**
- Tipo de empresa → Campo: "Tipo de empresa"
- Sector → Campo: "Sector"
- Tamaño → Campo: "Tamaño de empresa"
- País → Campo: "País"
- Email de contacto → Campo: "Email de empresa"

**Expertos:**
- Especialidad → Campo: "Área principal"
- Nivel Floutic → Campo: "Nivel de servicio Floutic"
- País → Campo: "País / Región"
- Idiomas → Campo: "Idioma de trabajo"
- Años experiencia → Campo: "Experiencia (años)"
- Verificado → Campo: "Certificación Floutic"
- Disponibilidad → Campo: "Disponibilidad semanal"

**Proyectos (como Oportunidades):**
- Título → Campo: "Título del proyecto"
- Presupuesto → Campo: "Presupuesto estimado (€)"
- Nivel requerido → Campo: "Nivel de servicio recomendado"
- Urgencia → Campo: "Urgencia"
- Estado → Campo: "Estado del proyecto"
- Valor final → Campo: "Valor final proyecto (€)"

**Endpoints del Backend para GHL:**
- `POST /api/webhooks/ghl` - Recibe webhooks de GHL
- `POST /api/integrations/ghl/contact` - Crea/actualiza contacto en GHL
- `POST /api/integrations/ghl/opportunity` - Crea/actualiza oportunidad en GHL
- `POST /api/integrations/ghl/tag` - Añade etiqueta a contacto
- `GET /api/integrations/ghl/status/{contact_id}` - Consulta estado en GHL

---

## 8. Sistema de Verificación de Perfiles ✅

### 8.1 Funcionalidades Implementadas

**Registro Automático Sin Verificar:**
- Todos los usuarios (empresas y expertos) se registran con `is_verified = false` por defecto
- Los administradores deben verificar manualmente cada perfil antes de permitir funcionalidades avanzadas
- Solo expertos verificados aparecen en búsquedas y curaciones de proyectos
- **Solo empresas con perfil verificado pueden crear proyectos** (validación en `get_current_company_user`)

**Endpoints de Verificación:**
- `PUT /api/admin/users/{id}/verify` - Verificar usuario/perfil
- `PUT /api/admin/users/{id}/unverify` - Desverificar usuario/perfil
- `GET /api/admin/users?is_verified=true/false` - Filtrar por estado de verificación

**Integración con GoHighLevel:**
- Webhook `exp-verificado` cuando se verifica un experto
- Etiqueta automática "Experto Verificado" en GHL
- Sincronización de estado de verificación

**Notificaciones:**
- Los administradores reciben notificaciones cuando un usuario completa su perfil (empresa o experto)
- La notificación se dispara en `POST /api/profiles/` (creación de perfil), no en el registro
- Esto permite que los admins verifiquen perfiles completos en lugar de usuarios sin perfil

### 8.2 Flujo de Verificación

1. **Usuario se registra** → `is_verified = false` (sin notificación a admin)
2. **Usuario crea perfil** → `POST /api/profiles/` → Notificación a administradores
3. **Admin revisa perfil** → `PUT /api/admin/users/{id}/verify` → `is_verified = true`
4. **Funcionalidades desbloqueadas:**
   - **Empresas:** Pueden crear proyectos (`POST /api/projects/`)
   - **Expertos:** Aparecen en búsquedas y pueden aplicar a proyectos curados

### 8.3 Restricción de Creación de Proyectos

**Backend (`get_current_company_user`):**
- Valida que el usuario tenga rol `empresa`
- Verifica que exista un perfil asociado
- Comprueba que `profile.is_verified = True`
- Devuelve `403 Forbidden` con mensaje específico si no cumple los requisitos

**Frontend:**
- Componente `PublicarProyectoForm` valida estado del perfil antes de mostrar formulario
- Script del formulario verifica perfil antes de permitir envío
- Dashboard de empresa muestra alertas cuando el perfil está pendiente o falta
- Botón "Crear Nuevo Proyecto" deshabilitado si el perfil no está verificado

### 8.4 Validaciones y Seguridad

- Solo administradores pueden verificar/desverificar
- Verificación requiere perfil existente
- Estados de verificación se sincronizan con GHL
- Logs de todas las acciones de verificación
- Restricción de creación de proyectos validada en múltiples capas (backend, frontend, UI)

### 8.5 Sistema de Datos Fiscales para Facturación Legal ✅

**Objetivo:** Solicitar datos fiscales completos necesarios para emitir facturas legales en España cuando empresas crean su primer proyecto o expertos son asignados a su primer proyecto.

#### 8.5.1 Campos Fiscales en Modelo Profile

**Para Empresas:**
- `cif` (CIF/NIF) - Obligatorio para primer proyecto
- `company_name` - Obligatorio junto con CIF

**Para Expertos:**
- `tax_id` (NIF) - Obligatorio para primer proyecto
- `fiscal_name` (Nombre fiscal/razón social) - Obligatorio
- `fiscal_address` (Dirección fiscal completa) - Obligatorio
- `fiscal_postal_code` (Código postal) - Obligatorio (5 dígitos)
- `fiscal_city` (Ciudad) - Obligatorio
- `fiscal_province` (Provincia) - Obligatorio
- `fiscal_country` (País) - Opcional (default: "España")
- `fiscal_data_complete` (Flag booleano) - Indica si tiene datos completos

#### 8.5.2 Validaciones Implementadas

**Función Helper:** `app.core.fiscal_validation.has_complete_fiscal_data(profile)`
- Para empresas: Verifica `cif` y `company_name`
- Para expertos: Verifica todos los campos fiscales requeridos
- Retorna `True` si tiene datos completos, `False` en caso contrario

**Validación en Creación de Proyecto:**
- Endpoint: `POST /api/projects/`
- Verifica si es el primer proyecto de la empresa
- Si es primer proyecto y no tiene datos fiscales completos, retorna error `400` con código `FISCAL_DATA_REQUIRED`
- Mensaje: "Para crear tu primer proyecto, necesitamos completar tus datos fiscales para la facturación"

**Validación en Selección de Experto:**
- Endpoint: `POST /api/projects/{project_id}/select/{expert_id}`
- Verifica si es el primer proyecto del experto
- Si es primer proyecto y no tiene datos fiscales completos, retorna error `400` con código `FISCAL_DATA_REQUIRED`
- Mensaje: "El experto debe completar sus datos fiscales antes de ser asignado a un proyecto"

#### 8.5.3 Endpoints de Datos Fiscales

**PUT /api/profiles/{id}/fiscal-data**
- Permite actualizar solo campos fiscales del perfil
- Valida que todos los campos requeridos estén presentes según el tipo de perfil
- Actualiza `fiscal_data_complete=True` cuando todos los datos están completos
- Solo el propio usuario puede actualizar sus datos fiscales
- Retorna el perfil actualizado con `ProfileResponse`

**GET /api/profiles/me/fiscal-status**
- Retorna estado de datos fiscales del usuario actual
- Respuesta incluye:
  - `is_complete`: boolean - Si tiene datos fiscales completos
  - `missing_fields`: array - Lista de campos que faltan (si aplica)
  - `profile_type`: string - Tipo de perfil (empresa/experto)

#### 8.5.4 Schemas y Validaciones

**Validaciones Pydantic:**
- `tax_id`: Pattern para NIF español (8 dígitos + letra opcional o solo 8 dígitos)
- `fiscal_name`: Min 2, max 200 caracteres
- `fiscal_address`: Min 5, max 500 caracteres
- `fiscal_postal_code`: Pattern español (5 dígitos)
- `fiscal_city`: Min 2, max 100 caracteres
- `fiscal_province`: Min 2, max 100 caracteres
- `cif`: Pattern para CIF español (Letra + 8 dígitos)

**Migración de Datos:**
- Todos los perfiles existentes se marcan con `fiscal_data_complete=False` por defecto
- Los usuarios pueden completar sus datos fiscales en cualquier momento desde su perfil

#### 8.5.5 Notificaciones de Datos Fiscales Requeridos ✅

**Sistema de Notificaciones Proactivas:**

El sistema envía notificaciones automáticas cuando se detecta que un usuario necesita completar sus datos fiscales:

**Para Empresas:**
- **Momento:** Cuando intentan crear su primer proyecto sin datos fiscales completos
- **Tipo de Notificación:** `FISCAL_DATA_REQUIRED`
- **Título:** "Datos Fiscales Requeridos"
- **Mensaje:** "Para crear tu primer proyecto, necesitas completar tus datos fiscales (CIF). Esto es necesario para la facturación legal."
- **Metadata:** Incluye `missing_fields` con los campos que faltan

**Para Expertos:**
- **Momento:** Cuando son seleccionados para su primer proyecto (se les acepta un presupuesto) sin datos fiscales completos
- **Tipo de Notificación:** `FISCAL_DATA_REQUIRED`
- **Título:** "Datos Fiscales Requeridos"
- **Mensaje:** "Para ser asignado a tu primer proyecto, necesitas completar tus datos fiscales (NIF, nombre fiscal, dirección, etc.). Esto es necesario para la facturación legal."
- **Metadata:** Incluye `missing_fields` con los campos que faltan

**Características:**
- Las notificaciones se envían **antes** de lanzar el error `FISCAL_DATA_REQUIRED`
- Se envían en tiempo real vía WebSocket si el usuario está conectado
- Se guardan en la base de datos para aparecer en el dashboard
- Incluyen metadata con los campos faltantes para facilitar la acción del usuario
- Se pueden enviar webhooks personalizados si el usuario los tiene configurados

**Flujo Completo:**
1. Usuario intenta crear proyecto o es seleccionado
2. Backend valida datos fiscales
3. Si faltan datos:
   - Se envía notificación al usuario (tipo `FISCAL_DATA_REQUIRED`)
   - Se retorna error `400` con código `FISCAL_DATA_REQUIRED`
   - El frontend muestra el modal de datos fiscales
4. El usuario ve la notificación en su dashboard incluso si no está en la página en ese momento

#### 8.5.6 Sincronización con GoHighLevel ✅

**Sincronización Automática de Datos Fiscales:**

Los datos fiscales se sincronizan automáticamente con GHL como campos personalizados (`customFields`) cuando:

1. **Creación de Contacto:** Al crear un nuevo contacto en GHL, todos los campos fiscales disponibles se incluyen automáticamente
2. **Actualización de Perfil:** Cuando se actualiza cualquier campo fiscal, se sincroniza con GHL en la próxima actualización del perfil

**Campos Fiscales Sincronizados con GHL:**

**Para Empresas:**
- `nif_fiscal` → `tax_id` (si existe)
- `nombre_fiscal` → `fiscal_name`
- `direccion_fiscal` → `fiscal_address`
- `codigo_postal_fiscal` → `fiscal_postal_code`
- `ciudad_fiscal` → `fiscal_city`
- `provincia_fiscal` → `fiscal_province`
- `pais_fiscal` → `fiscal_country`
- `datos_fiscales_completos` → `fiscal_data_complete` (como "Sí"/"No")

**Para Expertos:**
- `nif_fiscal` → `tax_id`
- `nombre_fiscal` → `fiscal_name`
- `direccion_fiscal` → `fiscal_address`
- `codigo_postal_fiscal` → `fiscal_postal_code`
- `ciudad_fiscal` → `fiscal_city`
- `provincia_fiscal` → `fiscal_province`
- `pais_fiscal` → `fiscal_country`
- `datos_fiscales_completos` → `fiscal_data_complete` (como "Sí"/"No")

**Lógica de Sincronización:**
- El campo `datos_fiscales_completos` se calcula automáticamente cuando se actualizan campos fiscales
- Se sincroniza automáticamente con GHL si se detectan cambios en cualquier campo fiscal
- Los valores booleanos se mapean a "Sí"/"No" para mejor legibilidad en GHL
- La sincronización ocurre en el endpoint `PUT /api/profiles/{id}` cuando se detectan cambios en campos fiscales

---

## 14. Resumen Ejecutivo del Estado Actual

### 📊 Métricas del Backend
- **Total de endpoints:** 95+ endpoints implementados
- **Módulos principales:** 11 módulos de endpoints
- **Modelos de datos:** 8 modelos SQLAlchemy
- **Servicios especializados:** 8 servicios
- **Tests implementados:** 486 tests en 28 archivos
- **Cobertura de testing:** 100% de funcionalidades críticas
- **Integraciones:** GoHighLevel, Stripe, Redis, WebSocket

### ✅ Fortalezas del Backend
1. **Arquitectura Robusta** 🏗️
   - FastAPI con async/await para alta performance
   - SQLAlchemy ORM con PostgreSQL para datos relacionales
   - Redis para caching y sesiones
   - WebSocket para notificaciones en tiempo real

2. **Seguridad Avanzada** 🔒
   - Autenticación dual (JWT + cookies HttpOnly)
   - RBAC completo con permisos granulares
   - Validación Pydantic en todos los endpoints
   - Rate limiting y protección CORS

3. **Integraciones Completas** 🔗
   - GoHighLevel para CRM y automatización
   - Stripe para pagos escrow
   - WebSocket para tiempo real
   - Sistema de webhooks robusto

4. **Testing Exhaustivo** ✅
   - 486 tests unitarios
   - Cobertura completa de endpoints
   - Tests de integración
   - Validación de servicios

### 🎯 Estado del Proyecto
**✅ MVP COMPLETADO (100%):**
- Sistema de contratación curado funcional
- Panel de administración completo
- Integraciones externas operativas
- Testing exhaustivo implementado
- Documentación actualizada

**🚀 PRÓXIMOS PASOS:**
1. **Monitoreo avanzado** con Prometheus/Grafana
2. **Alertas automáticas** para errores críticos
3. **Auto-scaling** basado en métricas
4. **Backup distribuido** y recovery automático

---

**Última actualización:** 15 de Diciembre de 2025
**Versión del PRD:** 2.0
**Estado:** MVP Completado al 100% - Sistema de contratación curado totalmente funcional