# Filtros executivos da carteira (Etapa 91)

## Visão geral

A **Etapa 91** cria a **base de filtros executivos da carteira** e **recortes por risco, prioridade, fechamento e operação**, para que a gestão navegue rapidamente entre subconjuntos relevantes sem abrir cada ciclo. A camada é **agregadora**: aplica filtros sobre **EventCyclePortfolioPriorityState** (que já consome closure, métricas, alertas, recuperação, simulação); não substitui priorização nem overview.

| Conceito | Descrição |
|----------|-----------|
| **Filtro** | **EventCyclePortfolioFilter**: FilterId, Name, RiskLevelFilter, PriorityLevelFilter, ClosureStatusFilter, ProducerStatusFilter, IncludeBlockedOnly, IncludeClosingSoonOnly, IncludeRecoveryOpportunitiesOnly, IncludeCompletedWithIssuesOnly, IncludeExecutionActiveOnly, Notes. |
| **Vista filtrada** | **EventCyclePortfolioFilteredViewState**: ActiveFilter, FilteredItems, FilteredCount, FilterSummary, HighestPriorityFilteredItem, LastFilteredAt. |
| **Controller** | **EventCyclePortfolioFilterController**: GetAvailableFilters(), ApplyFilter(priorityState, filter), ApplyActiveFilterOrNone(priorityState), SetActiveFilter(filterId), ClearActiveFilter(). |
| **Store** | **ActivePortfolioFilterStore**: SetActiveFilter(filterId), GetActiveFilterId(), ClearFilter(), HasActiveFilter (em memória). |

## Recortes disponíveis (presets)

- **Somente em risco** — RiskLevelLabel contém "Em risco", "Crítico" ou "Alertas bloqueantes".
- **Somente bloqueados** — RiskLevelLabel contém "Bloqueado".
- **Somente alta prioridade** — PriorityScore ≥ 70.
- **Somente perto de fechar** — PriorityReason "Perto de fechamento" ou ClosureStatus/CommercialStageLabel indicam aceite final.
- **Somente recuperação promissora** — TopRecoveryAction e SimulatedBestScenarioDelta preenchidos.
- **Somente concluídos com issues** — Concluídos (closure) e performance &lt; 70.
- **Somente execução ativa** — Não concluídos e não bloqueados (em andamento operacional).

## Como ajuda a gestão rápida

- **Aplicar filtro** — Um clique aplica o recorte; a lista e o dashboard passam a refletir apenas os itens que passam no filtro.
- **Ver total filtrado e item prioritário do recorte** — Sem abrir ciclos, a gestão vê quantos casos estão no recorte e qual é o mais crítico (HighestPriorityFilteredItem).
- **Trocar filtro** — Escolher outro preset; o store guarda o filtro ativo e a próxima actualização (dashboard, painel, strip) usa-o.
- **Limpar filtro** — Voltar à vista completa da carteira.

## UI

- **EventCyclePortfolioFilterStripView** — Se filtro ativo: nome do filtro, total filtrado, item prioritário, timestamp. Se não: "Nenhum ativo" e total na carteira.
- **EventCyclePortfolioFilterPanel** — Lista de filtros (botões); botão "Limpar filtro"; resumo do recorte; total filtrado; item mais crítico do recorte; última filtragem; lista de itens no recorte (com ★ no prioritário).
- **EventCycleDashboardPanel** — Quando há filtro ativo: linha "Filtro ativo: [nome] | N item(ns) | Crítico no recorte: [título] | timestamp".

## Ações

- **Aplicar filtro** — Clicar num filtro na lista; SetActiveFilter(filterId) e Refresh.
- **Trocar filtro** — Clicar noutro filtro; o anterior é substituído.
- **Limpar filtro** — ClearActiveFilter() e Refresh; vista volta a mostrar todos os itens.
- **Navegar para item filtrado** — Futuro: usar CycleId do item para abrir no CRM.
- **Destacar item prioritário do recorte** — No painel, o item com HighestPriorityFilteredItem recebe ★ e negrito.

## Limitações atuais

- **Sem persistência real** — O filtro ativo está apenas em memória (ActivePortfolioFilterStore).
- **Sem filtros salvos** — Não há perfis de filtro guardados nem preferências por utilizador.
- **Sem analytics externos** — Recortes são calculados apenas sobre os dados da priorização actual.

## 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 EventCyclePortfolioPriorityState e aplica predicados sobre itens; sem dependência circular.
