# Comunicação operacional Hotel ↔ Produtor

## Visão geral

A **Etapa 69** introduz a base de **comunicação operacional** entre a web do hotel e a web do produtor, **ligada ao pedido/handoff** (ProducerOrder). Permite troca de mensagens mockadas por thread de pedido, indicadores de quem está a aguardar resposta e integração com pedidos de esclarecimento.

| Conceito | Descrição |
|----------|-----------|
| **Thread** | Uma **CommunicationThread** por ProducerOrder (OrderId como vínculo principal); pode referenciar OpportunityId, ProposalId, SessionId. |
| **Mensagens** | **CommunicationMessage**: remetente (HotelSales, Producer, etc.), tipo (GeneralNote, ClarificationRequest, ClarificationResponse, StatusUpdate, ScopeAdjustment, PriorityNote), conteúdo e data. |
| **Participantes** | **CommunicationParticipant** por thread (Hotel, Produtor); usado para identificar quem envia em cada mensagem. |

## Como a thread se relaciona ao handoff

- Ao **gerar** um ProducerOrder (Handoff para produtor), o **HotelToProducerHandoffService** chama **ProducerOrderCommunicationController.EnsureThreadForOrder** com OrderId, OpportunityId, ProposalId e SessionId. Assim, cada pedido tem uma thread criada automaticamente.
- A thread é o canal de comunicação para esse pedido: origem do pedido (oportunidade, proposta, sessão Quest), notas de handoff e status de aceite ficam visíveis nos cabeçalhos da UI de comunicação.
- **Sem dependência circular**: o módulo Communication referencia apenas IDs (OrderId, OpportunityId, etc.); o Hotel e o Produtor referenciam Communication para ler/escrever mensagens.

## Pedidos de esclarecimento e respostas

- **ClarificationRequest**: mensagem de tipo ClarificationRequest indica pedido de esclarecimento (ex.: do produtor ao hotel ou do hotel ao produtor). O remetente é identificado por **SenderRole** (Producer, HotelSales, etc.).
- **ClarificationResponse**: resposta a um pedido de esclarecimento. A UI do hotel pode mostrar o indicador **"Resposta recebida"** quando a última mensagem for ClarificationResponse (resposta do produtor).
- O **CommunicationIndicatorHelper** usa o estado do pedido (RequiresClarification, AcceptanceStatus) e a **última mensagem** (tipo e remetente) para definir rótulos:
  - **Aguardando resposta do produtor**: pedido em esclarecimento e última mensagem foi ClarificationRequest do hotel.
  - **Aguardando resposta do hotel**: pedido em esclarecimento e última mensagem foi ClarificationRequest do produtor.
  - **Escopo em esclarecimento**: pedido com RequiresClarification.
  - **Comunicação ativa**: há mensagens e não está em esclarecimento pendente.
  - **Pronto para seguir**: pedido aceite e sem esclarecimento pendente.

Na etapa actual, **registar** um pedido de esclarecimento ou resposta é feito ao **adicionar uma mensagem** com o tipo adequado (ClarificationRequest ou ClarificationResponse) via **ProducerOrderCommunicationController.AddClarificationRequest** / **AddClarificationResponse**. A UI envia mensagens como GeneralNote; botões específicos para “Pedir esclarecimento” ou “Responder esclarecimento” podem ser adicionados em etapas futuras.

## Limitações actuais

- **Sem persistência real**: threads e mensagens estão em **CommunicationStore** (em memória); ao reiniciar a aplicação perdem-se.
- **Sem comunicação em tempo real**: não há WebSockets, polling nem integração com email/WhatsApp/chat externo.
- **Sem autenticação real**: remetente é definido pelo lado que chama (Hotel = HotelSales, Produtor = Producer).
- A UI permite **nova mensagem** e **Enviar** como mock (GeneralNote); tipos ClarificationRequest/ClarificationResponse estão disponíveis na API para uso futuro.

## Estrutura (Assets/Web/Communication/)

- **Core**: CommunicationParticipantRole (HotelSales, HotelAdmin, Producer, InternalAdmin), CommunicationMessageType (GeneralNote, ClarificationRequest, ClarificationResponse, StatusUpdate, ScopeAdjustment, PriorityNote).
- **Domain**: CommunicationThread (Id, OrderId, OpportunityId, ProposalId, SessionId, CreatedAt, LastMessageAt), CommunicationMessage (Id, ThreadId, OrderId, SenderRole, MessageType, Content, CreatedAt), CommunicationParticipant (Id, ThreadId, Role, DisplayLabel).
- **Application**: CommunicationStore (GetOrCreateThread, GetThreadByOrderId, AddMessage, GetMessages, GetMessagesForOrder, GetParticipants), **ProducerOrderCommunicationController** (EnsureThreadForOrder, GetOrCreateThread, GetThreadForOrder, GetMessagesForOrder, AddMessage, AddClarificationRequest, AddClarificationResponse, AddStatusUpdate, AddGeneralNote), **CommunicationIndicatorHelper** (GetCommunicationLabel).

Integração:
- **Hotel**: secção **OrderCommunicationPanel** (thread por pedido, mensagens recentes, nova mensagem, indicadores: dúvida pendente, resposta recebida); **HotelToProducerHandoffService** chama EnsureThreadForOrder após gerar pedido.
- **Produtor**: secção **ProducerOrderCommunicationView** (thread por pedido, mensagens recentes, campo de resposta, indicadores: aguardando esclarecimento, pronto para continuar).
