# Próximos passos recomendados e ações sugeridas (Etapa 78)

## Visão geral

A **Etapa 78** cria a **base de próximos passos recomendados** do ciclo e um **painel de ações sugeridas** para comercial e operação: o sistema não só mostra o estado actual, como **orienta o que fazer a seguir**. A camada é **agregadora**: usa os mesmos dados do dashboard e dos alertas e gera acções recomendadas com prioridade e responsável; não substitui os módulos existentes.

| Conceito | Descrição |
|----------|-----------|
| **Ação recomendada** | **EventCycleRecommendedAction**: ActionId, CycleId, Title, Summary, ActionType, Priority, ResponsibleRole, RelatedSectionKey, SuggestedReason, IsBlockingResolution, IsCompleted, CreatedAt. |
| **Tipo de ação** | **EventCycleActionType**: ContactLead, SendProposal, RunQuestSession, FollowUpClient, GenerateHandoff, ClarifyScope, ApproveRevision, ConfirmPreparation, StartExecution, ResolveIssue, ReviewFinalReport, ApproveFinalAcceptance, CloseCycle. |
| **Prioridade** | **EventCycleActionPriority**: Low, Medium, High, Critical. |
| **Responsável** | **EventCycleResponsibleRole**: HotelSales, HotelAdmin, Producer, InternalAdmin. |
| **Estado do plano** | **EventCycleActionPlanState**: CycleId, Actions, TopPriorityAction, TotalActions, BlockingActions, LastGeneratedAt. |
| **Controller** | **EventCycleActionPlanController**: GenerateActionPlans, GenerateActionPlanForCycle, MarkActionCompleted, ClearCompletedForCycle, ClearAllCompleted, GetTotals. |
| **Store** | **CompletedCycleActionStore**: MarkCompleted, IsCompleted, ClearCompletedForCycle, ClearAllCompleted (em memória). |

## Regras de geração (heurísticas)

As acções são geradas por ciclo (pedido) com base no estado actual. A **primeira acção prioritária** (Critical, depois High, etc.) é exposta como **TopPriorityAction**. Ordem lógica das regras (as primeiras têm precedência quando várias se aplicam):

| Condição | Tipo | Título resumido | Prioridade | Responsável |
|----------|------|------------------|------------|-------------|
| Ciclo encerrado | CloseCycle | Ciclo encerrado | Low | HotelAdmin |
| Aceite/rejeição feita, ciclo não encerrado | CloseCycle | Encerrar ciclo | High | HotelAdmin |
| Relatório produtor concluído; aceite hotel pendente | ApproveFinalAcceptance | Aceite final do hotel | Critical | HotelAdmin |
| Execução concluída; relatório não concluído | ReviewFinalReport | Gerar e concluir relatório final | High | Producer |
| Execução bloqueada | ResolveIssue | Resolver bloqueio | Critical | Producer |
| Execução pausada | StartExecution | Retomar execução | High | Producer |
| Preparação confirmada; execução não iniciada | StartExecution | Iniciar execução | High | Producer |
| Checklist com obrigatórios pendentes | ConfirmPreparation | Concluir checklist e confirmar preparação | High | Producer |
| Escopo não confirmado | ClarifyScope | Confirmar escopo | High | HotelAdmin |
| Pedido sem aceite do produtor | FollowUpClient | Contactar produtor para aceite | Critical | HotelSales |
| Sessão Quest não realizada | RunQuestSession | Realizar sessão Quest | Medium | HotelSales |
| Follow-up prioritário pendente | FollowUpClient | Concluir follow-up prioritário | High | HotelSales |

Cada acção tem **RelatedSectionKey** (secção do dashboard) e **SuggestedReason** (motivo da recomendação). **IsBlockingResolution** = true quando a acção desbloqueia o avanço do ciclo.

## Concluídas (mock)

- **CompletedCycleActionStore** guarda ActionIds marcados como concluídos em memória.
- **MarkActionCompleted(actionId)** faz com que na próxima geração a acção seja filtrada.
- **ClearAllCompleted** limpa todas; **ClearCompletedForCycle(cycleId)** limpa só desse ciclo.
- "Concluída" é apenas gestão local: não altera o estado real (ex.: marcar "Aceite final" como concluída não executa o aceite no módulo).

## UI

- **EventCycleActionPlanStripView** — Faixa: "Ações: N | Bloqueantes: X | Próxima: [título da top] | Gerado: …". Cor verde quando há prioridade crítica.
- **EventCycleActionPlanPanel** — Lista de acções por ciclo; destaque da **próxima** (★); por acção: prioridade, responsável, título, motivo, secção; botão "Marcar concluída"; "Atualizar" e "Limpar concluídas". Cores por prioridade (Critical/High).
- **EventCycleDashboardPanel** — Por ciclo: linha **"Próxima ação: [TopPriorityAction.Title] (ResponsibleRole) — SuggestedReason"** quando existe TopPriorityAction.

## Ações do utilizador

- **Atualizar plano** — Refresh no painel ou strip (OnDataChanged ou botão).
- **Marcar ação como concluída** — Botão no painel; guarda no CompletedCycleActionStore; próxima geração não mostra a acção.
- **Limpar concluídas** — Botão no painel; limpa o store.
- **Navegar para a secção** — RelatedSectionKey indica a secção; o utilizador faz scroll no CRM até lá.

## Como as ações ajudam comercial e operação

- **Comercial (HotelSales)** — RunQuestSession, FollowUpClient (aceite do produtor, follow-up prioritário): próximos passos claros no pipeline e no handoff.
- **Operação (HotelAdmin, Producer)** — ConfirmPreparation, StartExecution, ReviewFinalReport, ApproveFinalAcceptance, CloseCycle, ClarifyScope, ResolveIssue: quem faz o quê e em que ordem, com prioridade e motivo.

## Limitações actuais

- Sem persistência real: CompletedCycleActionStore e planos são em memória.
- Sem automação real: não há tarefas agendadas nem notificações.
- Sem workflow persistido: "marcar concluída" não altera o estado dos módulos (handoff, escopo, execução, aceite final).
