# Favoritos gerenciais e watchlist (Etapa 92)

## Visão geral

A **Etapa 92** cria a **base de favoritos gerenciais, casos observados e fila pessoal de acompanhamento** (watchlist), para que a gestão destaque ciclos importantes além da priorização global. A camada é **agregadora**: usa a priorização para listar ciclos e actualizar títulos; não substitui priorização, filtros nem overview.

| Conceito | Descrição |
|----------|-----------|
| **Item observado** | **EventCycleWatchItem**: WatchItemId, CycleId, OpportunityId, Title, IsFavorite, IsPinned, WatchReason, AddedAt, LastTouchedAt, Notes. |
| **Estado da watchlist** | **EventCycleWatchlistState**: Items, FavoriteItems, PinnedItems, TotalWatched, WatchlistSummary, TopPinnedItem, LastUpdatedAt. |
| **Store** | **WatchlistStore**: Add, Remove, Get, GetAll, SetFavorite, SetPinned, UpdateNotes, UpdateWatchReason, UpdateTitle (em memória). |
| **Controller** | **EventCycleWatchlistController**: AddToWatchlist, RemoveFromWatchlist, SetFavorite, SetPinned, UpdateNotes, UpdateWatchReason, GetWatchlistState(priorityState), IsWatched. |

## Diferença entre prioridade automática e observação manual

- **Prioridade automática** — Calculada por regras (bloqueado, em risco, recuperação, perto de fechar, etc.). A fila e os filtros usam essa prioridade para ordenar e recortar.
- **Observação manual (watchlist)** — O gestor escolhe quais casos acompanhar, favoritar ou fixar. A watchlist é **complementar**: destaca casos que o gestor quer ter sempre à mão, independentemente do score automático.

## Acompanhamento manual gerencial

- **Adicionar à watchlist** — Incluir um ciclo na lista de observados (a partir da carteira prioritizada).
- **Favorito** — Marcar como favorito (★); aparece em FavoriteItems.
- **Fixar** — Fixar no topo da fila pessoal (📌); aparece em PinnedItems; TopPinnedItem é o primeiro fixado.
- **Motivo e notas** — WatchReason e Notes para contexto rápido (edição via controller; UI pode expor em fases posteriores).
- **Remover** — Tirar da watchlist.

## UI

- **EventCycleWatchlistStripView** — Total observados, favoritos, fixado principal, timestamp.
- **EventCycleWatchlistPanel** — Resumo; lista de observados (título, ★/📌, motivo, notas, botões Favorito/Desfavoritar, Fixar/Desfixar, Remover); secção "Adicionar à watchlist" com itens da carteira ainda não observados e botão "Adicionar".
- **EventCycleDashboardPanel** — Quando TotalWatched > 0: linha "Watchlist: N observado(s) | M favorito(s) | Fixado: [título] | timestamp".

## Ações

- **Adicionar à watchlist** — AddToWatchlist(cycleId, opportunityId, title, reason).
- **Remover** — RemoveFromWatchlist(cycleId).
- **Marcar/desmarcar favorito** — SetFavorite(cycleId, true/false).
- **Fixar/desfixar** — SetPinned(cycleId, true/false).
- **Editar nota/motivo** — UpdateNotes(cycleId, notes), UpdateWatchReason(cycleId, reason) (API disponível; edição completa na UI pode ser expandida depois).
- **Abrir caso observado** — Futuro: usar CycleId para navegar ao ciclo no CRM.

## Integração

- **EventCyclePortfolioPriorityState** — GetWatchlistState(priorityState) usa a priorização para actualizar títulos dos itens observados e para listar "Adicionar à watchlist" (itens não observados).
- Sem dependência circular: a priorização não depende da watchlist; a watchlist apenas lê e enriquece com a priorização.

## Limitações atuais

- **Sem persistência real** — Tudo em memória (WatchlistStore); ao recarregar perde-se.
- **Sem multiusuário real** — Uma única watchlist por sessão; não há utilizador nem partilha.

## Garantias

- **Quest intacto** — Nenhum fluxo Quest nem runtime XR alterado.
- **Web Hotel e Produtor intactas** — Apenas novas secções e uma linha no dashboard.
- **Camada agregadora** — Só consome priorização para listar e actualizar títulos; não altera priorização, filtros nem overview.
