# OKR no Maestro — Manual do utilizador

Este guia descreve como usar a **visão OKR** (`strategy-okr.html`) no MAESTRO: pré-requisitos, cadastro de objetivos, leitura dos painéis e limitações atuais.

---

## 1. Pré-requisitos

| Requisito | Detalhe |
|-----------|---------|
| **Acesso HTTP(S)** | Abra a aplicação via `http://` ou `https://`. Abrir ficheiros HTML em `file://` impede o carregamento correto do Supabase e da sessão. |
| **Sessão e organização** | Faça login e selecione a **organização (tenant)** no seletor no canto superior direito. Sem tenant válido, a página não carrega dados. |
| **Papel (role)** | **Ver** objetivos e KRs: qualquer utilizador com acesso ao tenant. **Criar objetivos**: `super_admin`, `tenant_admin` ou `manager` (políticas RLS na base de dados). Utilizadores só com papel `user` ou `viewer` veem o formulário em modo só leitura. |
| **Framework** | O tenant pode estar em X-Matrix, OKR ou Híbrido. Mesmo em modo só X-Matrix, a página OKR pode ser usada para pré-visualização; pode aparecer um aviso no topo. |

---

## 2. Cadastrar um objetivo estratégico

1. Na visão OKR, localize a secção **Novo objetivo**.
2. Preencha pelo menos o **nome** do objetivo.
3. Campos opcionais: **descrição**, **ciclo** (texto livre, ex.: `FY2026`, `2026-Q1`), **responsável**, e a caixa **Ativo**.
4. Clique em **Criar objetivo**.

O registo é gravado na tabela `strategy_objectives` no Supabase. Após o sucesso, a lista e os filtros atualizam-se automaticamente (ou use **Atualizar**).

### Resultados-chave (KRs)

1. Na secção **Novo resultado-chave (KR)**, escolha o **objetivo** pai.
2. **Modo manual:** defina unidade (opcional), valor inicial, **meta** (obrigatória para o cálculo de progresso) e valor atual opcional.
3. **Modo KPI de projeto:** escolha um KPI existente em `project_kpis`; a meta e a unidade são preenchidas a partir do KPI (pode editar o nome do KR antes de guardar).
4. Clique em **Criar KR**. Os dados vão para `strategy_key_results`.

### Ligar projetos ou programas a KRs

1. Na secção **Ligar KR a projeto ou programa**, selecione o **KR**, o tipo (**Projeto** ou **Programa**), a entidade correspondente, a **correlação** (dono / contribui / apoia) e notas opcionais.
2. **Adicionar vínculo** grava em `strategy_key_result_links` (um vínculo por par KR×projeto ou KR×programa).
3. A tabela **Vínculos existentes** lista os vínculos atuais; **Remover** apaga o registo (requer o mesmo papel que cria objetivos).

---

## 3. Painéis e separadores

| Separador | Função |
|-----------|--------|
| **Quadro principal** | Tabela hierárquica somente leitura: objetivo → projetos/programas → linhas de KR, com status, progresso, custo real agregado (quando existir) e linha do tempo. |
| **Lista de objetivos** | Cartões por objetivo com progresso e pré-visualização dos KRs. |
| **Resultados-chave** | Lista plana de KRs com filtros aplicados. |
| **Execução vinculada** | KRs que têm programas ou projetos associados. |

**Filtros:** ciclo do objetivo, estado do KR, origem do valor (manual vs KPI de projeto), e pesquisa textual.

**Cadência recomendada:** bloco colapsável no topo com orientação sobre ritos (anual / trimestral / check-ins). O campo **ciclo** do objetivo é texto livre; não é obrigatório um “tipo de ciclo” fixo na base.

---

## 4. Custos e projetos

Os **custos reais** mostrados por projeto vêm da soma de `project_budget_cost_entries` com `entry_type = 'actual'`. Se não houver lançamentos, aparece **—**.

---

## 5. Resolução de problemas

| Problema | O que verificar |
|----------|------------------|
| Traduções não atualizam | Altere o idioma no seletor; o texto estático com `data-i18n` e as etiquetas dos filtros devem atualizar. Recarregar a página após mudar organização. |
| Lista vazia | Confirme tenant no seletor; confirme que existem linhas em `strategy_objectives` para esse tenant; verifique filtros (ex.: ciclo) que possam esconder objetivos sem KRs quando combina filtros de KR. |
| Não consigo criar objetivo | Confirme papel `manager`, `tenant_admin` ou `super_admin`. Se o erro persistir, verifique políticas RLS e sessão no Supabase (Dashboard → Logs). |
| Erro ao carregar | Veja a consola do browser e a mensagem de notificação; cause comum: cliente Supabase não inicializado (`env.js` / rede). |

---

## 6. Documentação relacionada

- [OKR-PANEL-CADENCE-PLAN.md](./OKR-PANEL-CADENCE-PLAN.md) — plano de produto e cadência.
- [STRATEGY-OKR-COMPATIBILITY-NOTES.md](./STRATEGY-OKR-COMPATIBILITY-NOTES.md) — compatibilidade OKR vs X-Matrix (se existir no repositório).

---

*Última atualização: alinhada à implementação da visão OKR com seletor de tenant, i18n do módulo strategy e criação de objetivos via `StrategyService.createStrategyObjective`.*