Escopos e projetos

Objetivo

Na Radhr AI, o Escopo é o projeto. Foi uma decisão da F4: não existe tabela projetos; cada Contrato assinado gera um Escopo (escopos) com as etapas de execução (escopo_itens). Quando alguém fala em "projetos" na Radhr AI, no Copiloto ou no portal do cliente, está falando dos Escopos. Este documento cobre como o projeto nasce (Scope Builder), como é conferido (Scope Validator), como a saúde é calculada, como o Consultor executa etapa por etapa (com a sugestão diária do Delivery Advisor e a escalação de atrasos) e como uma Mudança de escopo é analisada, decidida e aplicada, com ou sem aditivo. Os agentes de IA deste fluxo falam como a organização: recebem a identidade e o bloco do perfil de IA dela no prompt. O contrato e o aditivo em si estão em funcional/contratos.

Fluxo

Todas as partes assinam o Contrato principal (na Radhr AI ou pela Clicksign). A cadeia assinado chama o Scope Builder, que gera o Escopo se o contrato ainda não tiver um — contrato só com itens recorrentes (ex.: renovação de sustentação) não tem projeto e não ganha escopo; o cartão do contrato diz isso no lugar do botão (contratoTemProjeto) —, e depois o Organization Auditor (auditoria), que relê o perfil da organização. Para planejar antes, o Consultor usa "Gerar escopo" no cartão Escopo e projeto do contrato (com a opção "só o modelo").
O Scope Builder pega os itens vendidos (sem os recorrentes), monta as etapas pelo escopo padrão de cada item no Catálogo e aplica as adaptações da IA, com justificativa. Prazos saem em sequência a partir do início do contrato (ou do kickoff, ou de hoje).
O Scope Validator roda logo em seguida: regras primeiro, depois a IA compara contrato × escopo. A saúde é calculada.
O Consultor executa em /radar/escopo/:id: muda status das etapas, define responsável, prazo e horas, conclui, transforma etapa em Tarefa, adiciona etapas e valida de novo. Cada movimento (etapa, concluir, adicionar, status, datas) dispara a cadeia escopo_movimento, e o Delivery Advisor relê o escopo.
Uma etapa aberta com prazo vencido vira ação "Destravar a entrega atrasada" na Home e risco de atraso no Cliente. No cron diário, a etapa atrasada além do limite da regra de escalação gera um aviso por e-mail (uma vez por etapa), e o Delivery Advisor sugere a próxima entrega de cada escopo ativo.
Quando os entregáveis da última fase são concluídos, a página sugere Encerrar o projeto. Encerrado, o cliente é avisado (se tiver portal) e a cadeia escopo_concluido relê a expansão do cliente.
Mudança de escopo: alguém solicita (página do escopo, aba Solicitações do Cliente 360, portal do cliente ou Copiloto com confirmação).
O Change Request Analyzer estima etapas novas e removidas, horas, dias, se já está no contrato e recomenda aprovar, negociar ou recusar; o código consolida valor e necessidade de aditivo.
O Consultor decide em /radar/mudanca/:id, podendo ajustar valor e dias. Rejeitada, fica registrada. Aprovada sem custo nem prazo (ou como cortesia do admin), é aplicada na hora. Com custo ou prazo, nasce um aditivo em rascunho.
O aditivo é enviado e assinado como qualquer contrato. A assinatura dispara a cadeia assinado, que aplica a mudança no escopo.

Regras de negócio

Um projeto por contrato gerado automaticamente. A cadeia só gera se o contrato não tiver escopo; o botão manual só aparece quando não há escopo. Contrato cancelado ou sem versão de proposta não gera. Vive em src/agentes.ts e src/escopo.ts (gerarEscopo).
Etapas vêm do Catálogo. Cada item vendido usa o escopo_padrao do item no Catálogo em banco; sem ele, os entregáveis do catálogo em código; sem nada, uma etapa "Execução e entrega". Horas padrão: 8 h por entregável, 4 h por etapa. Itens recorrentes não viram etapa. Vive em src/escopo.ts (planejar).
A IA só adapta, com justificativa: adicionar uma etapa, remover (nunca um entregável) ou renomear, sempre apontando um item vendido; até 12 adaptações e 5 riscos iniciais. Etapas da IA ficam com origem ia e a justificativa visível. Vive em src/escopo.ts (interpretarBuilder, planejar).
Prazos: o prazo_dias do item vendido (padrão 21) é dividido entre as etapas dele, em sequência. O fim previsto do projeto é o último prazo. Vive em src/escopo.ts.
Scope Validator, regras: item vendido sem etapa (alta), entregável sem prazo (média), etapa sem item vendido correspondente (média), dependência circular (alta), último prazo além do fim do contrato (alta), horas acima de 1,5 × 40 h por item vendido (média). Depois, a IA aponta inconsistências e riscos. Vive em src/escopo.ts (regrasDoEscopo, validarEscopo).
Saúde: vermelho com atraso de 7 dias ou mais, 3 etapas atrasadas ou apontamento alto fora do status planejado; amarelo com qualquer atraso, com ritmo abaixo do tempo decorrido (mais de metade do prazo passado e percentual concluído 25 pontos atrás) ou apontamento alto ainda no planejamento; senão verde. Projeto concluído é sempre verde. Vive em src/escopo.ts (saudeDoEscopo).
**Status do projeto pela máquina escopo:** planejado → em execução → em homologação → concluído, com pausado no meio. Entrar em execução grava o início (se vazio); concluir grava o fim real. Vive em src/estados.ts e src/escopo.ts (mudarStatusEscopo).
Status das etapas: a fazer, em andamento, em homologação, concluído, cancelado. Etapas canceladas saem das contas. Vive em src/escopo.ts.
Encerrar é sugestão, não trava. O aviso aparece quando todos os entregáveis da última fase estão concluídos e o projeto não está planejado; o código não impede encerrar antes pelo diálogo de status. Vive em src/radar/escopos.ts.
Etapa vira Tarefa com o prazo da etapa, dono = responsável da etapa (senão quem clicou, senão o dono do cliente). Exige lead de origem no cliente. Vive em src/escopo.ts (tarefaDoItem).
**Delivery Advisor (agente entrega): lê as etapas de um escopo ativo (planejado, em execução ou em homologação) com pelo menos uma etapa aberta, os responsáveis, o dono do cliente e as regras de entrega, escalação e risco do perfil, e devolve um resumo, a próxima entrega, o que está atrasando e quem acionar**. O código só aceita ids de etapas do próprio escopo e corta listas e textos. Uma sugestão por escopo por dia (hash com etapas, status, versão do perfil e o dia); "Reler hoje" força nova leitura. Sem o modelo, cai na regra: a primeira etapa atrasada (senão a próxima aberta na ordem das fases), os responsáveis das atrasadas, o dono do cliente e os admins quando a regra pede. Só sugere: nada muda no escopo sem o Consultor. Vive em src/entrega.ts.
Escalação de atrasos: no cron diário, etapa atrasada há N dias ou mais gera um e-mail ao Consultor dono do cliente (e aos admins, quando a regra pede) e o evento escalacao_enviada no cliente; a mesma etapa nunca é escalada de novo. N e o destino vêm da primeira regra de escalação do perfil que fala de atraso; sem regra, 5 dias, dono e admins. Vive em src/escalacao.ts.
Avisos ao cliente: entregável concluído e projeto concluído geram e-mail ao cliente com portal (ver funcional/clientes). Vive em src/escopo.ts e src/notificacoes-cliente.ts.
Change Request Analyzer: o prompt traz a identidade e o bloco do perfil da organização. A instrução de "recusar" ainda cita o que fica fora na Witbiz (conteúdo, operação de mídia, licenças), em qualquer organização. Vive em src/mudancas.ts (analisarMudanca).
Mudança, consolidação pelo código: só remove etapas existentes, abertas e com o título exato; impacto em horas = novas − removidas; valor = horas × valor-hora da organização (padrão R$ 250, em /radar/configuracoes), zero quando o saldo de horas não é positivo; "dentro do escopo" só vale com saldo de horas zero ou negativo; remoção nunca aumenta prazo; sem IA, dias = horas ÷ 4. Vive em src/mudancas.ts (consolidar).
Análise sem IA não aprova de graça. Sem a leitura do modelo nada é estimado, e a recomendação é negociar, salvo remoção. Para aprovar uma adição ou alteração, o Consultor informa o valor (0 = sem custo, por decisão explícita) e o prazo; o campo vem em branco e o servidor recusa sem ele. Vale também para a mudança ainda não analisada, e um valor negativo ou inválido é recusado.
Quando exige aditivo: valor maior que zero, mudança de prazo com dias diferentes de zero, ou aumento de prazo fora do escopo contratado. Vive em src/mudancas.ts.
Regra fixa: nada muda no escopo antes do aditivo assinado, exceto remoções sem custo e cortesias. "Aplicar no escopo" à mão é recusado enquanto o aditivo não estiver assinado. Vive em src/mudancas.ts (aplicarMudanca).
Decisão: só de mudança solicitada ou analisada; o Consultor pode ajustar valor e dias; a cortesia (sem cobrar, aplica na hora) só vale para admin e para mudança com valor. Vive em src/mudancas.ts (decidirMudanca).
Aplicação: etapas novas entram com origem mudanca e a justificativa "Mudança #n", removidas viram canceladas, o fim previsto anda os dias da mudança, o valor soma ao contratado do cliente (não na cortesia) e o escopo é revalidado pelas regras. Vive em src/mudancas.ts.
**Estados da mudança pela máquina mudanca:** solicitada → analisada → aprovada | rejeitada → aditivo → aplicada. Vive em src/estados.ts.
Home: mudança solicitada ou analisada vira "Decidir a mudança de escopo"; aditivo parado há 72 h vira "Cobrar a assinatura do aditivo". Vive em src/hoje.ts.

Casos de uso

Projeto com muitas etapas abertas. Abra o escopo e leia o cartão do Delivery Advisor: ele diz o que empurrar hoje e quem acionar. Se a sugestão não serve, "Dispensar hoje".
Contrato assinado numa sexta. O projeto aparece sozinho no 360 e no contrato; revise as etapas da IA (selo "IA" com a justificativa), defina responsáveis e passe para em execução.
Quer planejar antes da assinatura. Gere o escopo pelo cartão do contrato; quando o contrato for assinado, a Radhr AI não cria um segundo.
Etapa atrasou. A Home pede para destravar; conclua, ajuste o prazo ou transforme em Tarefa. O risco de atraso sobe no cliente e volta ao normal quando a etapa fecha.
Cliente pediu uma integração a mais. Solicite a mudança no escopo; a análise sugere etapas e valor; aprove ajustando o valor, e o aditivo abre para envio.
Cliente desistiu de uma etapa. Solicite uma remoção; sem custo e sem prazo, a aprovação cancela a etapa na hora, sem aditivo.
Cortesia comercial. Um admin aprova marcando "cortesia"; a mudança entra no projeto sem aditivo e sem somar ao contratado, com o evento cortesia_concedida.

Telas

/radar/escopo/:id: cabeçalho com status, saúde e barra de progresso; números (etapas, entregáveis, horas, atrasadas, início, fim previsto); etapas por fase, com edição na própria linha (Salvar, Concluir, Virar tarefa); "Adicionar" etapa; validação da IA no cartão lateral; status e datas em diálogo; aviso de encerramento; bloco de mudanças com "Solicitar mudança de escopo"; cartão ✦ IA · Delivery Advisor (com a flag delivery_advisor): resumo, próxima entrega com link para a etapa, atrasando, quem acionar, selo "por regra" quando veio do fallback, "Reler hoje" e "Dispensar hoje".
GET /radar/escopo/:id/entrega: a última sugestão do Delivery Advisor em JSON (com dispensada).
Home /radar/: até 3 sugestões de entrega do dia, não dispensadas (com a flag delivery_advisor).
/radar/mudanca/:id: pedido, números do impacto (valor, horas, dias), análise da IA com recomendação, etapas novas e removidas, cláusula aplicável; formulário de decisão com valor, dias, motivo e, para admin, cortesia; "Reanalisar"; cartão do aditivo com o status e "Aplicar no escopo".
/radar/contrato/:id: cartão Escopo e projeto com o link ou o botão "Gerar escopo".
/radar/cliente/:id: aba Solicitações com as mudanças do cliente e o formulário; Visão geral com entregas atrasadas.
/portal/<token>: andamento por fase para o cliente e formulário de pedido de mudança.

Permissões

admin: tudo, incluindo conceder cortesia (ehAdmin em src/radar/mudancas.ts).
consultor: gera, edita e encerra projetos, solicita, reanalisa, aprova ou rejeita mudanças e aplica as que podem ser aplicadas. As telas não checam se o cliente é dele.
financeiro: decide mudanças em /radar/mudanca/:id (aprovar ou rejeitar, ajustando valor e prazo; o aditivo nasce como para o consultor). Cortesia continua só de admin; etapas, solicitações, reanálise e aplicação são recusadas com 403 (src/radar/permissoes.ts).
leitura: consulta escopos e mudanças e não altera nada (403).
Copiloto: solicitar_mudanca só vira ação depois da confirmação do consultor e só em cliente dele (ou sem dono); admin em todos.
cliente (por link): pelo portal, vê o andamento e pede mudanças; não decide nada.
**Papéis v2 (flag rbac_v2, ligada por organização):** em POST /radar/escopo/:id, concluir = escopos.concluir; validar, entrega e entrega_dispensar = escopos.validar; o resto = escopos.editar. Gerar pelo contrato = escopos.editar; solicitar mudança = mudancas.solicitar; decidir = mudancas.decidir (cortesia: mudancas.cortesia). owner, admin e master têm tudo; operation edita, conclui, valida e solicita; manager e financial decidem (manager também concede cortesia); sales só solicita (nos seus) e lê; viewer só lê. O consultor antigo vira sales (deixa de editar etapas e de decidir mudanças) e o admin do vínculo vira owner. Recusas vão para acessos (src/rbac/engine.ts).
Gating de plano: projetos e mudanças existem em todos os planos; o e-mail de aviso ao cliente depende do recurso avisos_cliente (Profissional ou superior) (src/planos.ts). O cartão e as sugestões do Delivery Advisor na Home dependem da flag delivery_advisor (planos pagos, desligada por padrão, src/flags.ts); a leitura no cron diário roda para todas as organizações.

Perguntas frequentes

Onde ficam os "projetos" do cliente? São os Escopos. Não existe outra entidade de projeto na Radhr AI: abra pelo Cliente 360 ou pelo contrato.

A IA pode tirar um entregável do projeto? Não. O Scope Builder ignora remoção de entregável, e toda etapa da IA mostra a justificativa. Você pode editar ou cancelar etapas depois.

Por que a saúde ficou amarela sem nada atrasado? Ou o ritmo está abaixo do tempo decorrido (mais da metade do prazo passou e o percentual concluído está 25 pontos atrás), ou a validação tem um apontamento alto enquanto o projeto ainda está planejado. Veja o cartão de validação.

Aprovei a mudança e o escopo não mudou. Está certo? Sim, se ela gerou aditivo: o escopo só muda quando o aditivo for assinado por todos. Remoções sem custo e cortesias aplicam na hora.

De onde vem o valor da mudança? Horas líquidas estimadas × valor-hora da organização, configurado por um admin em /radar/configuracoes. Você pode ajustar valor e dias antes de aprovar.

O Delivery Advisor mudou alguma etapa? Não. Ele só sugere a próxima entrega, o que atrasa e quem acionar; prazo, status e responsável continuam com você.

Recebi um e-mail "Etapa atrasada há N dias". Vou receber de novo amanhã? Não. A escalação manda um aviso por etapa. Conclua, replaneje o prazo ou registre a mudança de escopo.

Posso encerrar o projeto com etapas abertas? A Radhr AI sugere encerrar só quando os entregáveis da última fase fecham, mas não bloqueia o encerramento pelo diálogo de status. Encerrar avisa o cliente e dispara a leitura de expansão.

Webhooks de saída (ADR-0015)

Quando o Scope Builder cria um escopo, a Radhr AI emite escopo_criado (id, título, status, quantidade de itens, contrato e cliente) para os webhooks de saída da organização.