# PRD — Missoes/Cotacoes (MVP)

## Problema / dor

Hoje no Genesis não há ciclo formal de cotação de fornecedores. Quando o cliente precisa cotar um item (insumo, serviço, equipamento), o processo acontece fora do sistema — telefone, WhatsApp, planilha — sem rastro de quem foi convidado, quem respondeu, em quanto tempo, e por qual critério o vencedor foi escolhido.

Isso cria três dores: **(1)** o processo de Compras não tem como justificar objetivamente a escolha de um fornecedor (auditoria e compliance fraca), **(2)** preços/condições negociados se perdem (não viram base histórica pra futuras decisões) e **(3)** outros módulos do Genesis que precisariam cotar (não só Compras — também Logística, Manutenção etc.) acabam reimplementando o mesmo fluxo de forma improvisada.

A solução: um **módulo de Cotações genérico e reutilizável**, baseado em **Strategy + Adapters**, que qualquer outro módulo (Compras, Logística, etc.) pode acionar pra rodar um ciclo de cotação completo (solicitar → convidar fornecedores → receber propostas → comparar → selecionar vencedor → devolver resultado).

## Personas (alto nível)

- **Solicitante** (geralmente vindo de outro módulo, ex.: Comprador em Compras) — dispara um ciclo de cotação informando itens, fornecedores-alvo e critérios.
- **Cotador / Operador de cotações** — administra o ciclo: revisa convites, acompanha respostas, ajusta termos, seleciona vencedor.
- **Fornecedor externo** — recebe convite (com token público), abre o portal, vê os itens solicitados e envia proposta (preço, prazo, condições). Não tem login no Genesis.
- **Aprovador da seleção** — quem confirma o vencedor antes do resultado ser devolvido ao módulo solicitante (pode ou não coincidir com o aprovador de Compras; PO confirma).

> Mapeamento exato pra papéis Genesis fica com o PO.

## O que precisa fazer (alto nível) — MVP

1. **Solicitar Cotação**
   - Outro módulo (ou o próprio operador) cria uma solicitação com **itens + quantidades + fornecedores-alvo + estratégia** (Fornecedor Único / Comparativa) + **prazo de resposta**.
   - API/serviço programático pra módulos consumidores (não só UI).

2. **Strategies de cotação no MVP**
   - **Fornecedor Único** — convite a 1 fornecedor; registra preço/prazo/condições; sem ranking.
   - **Comparativa** — convite a N fornecedores; ranking automático por critério (preço, prazo, score composto).
   - Ambas implementam uma `CotacaoStrategyInterface`, plugadas via **Registry** (mesmo padrão de `OtpCanalRegistry` e `EdicaoRotaCallbackRegistry`).

3. **Convite ao fornecedor — canal pluggable + portal**
   - Envio do convite via **Mensageria/Otp** (canais email / WhatsApp / log já registrados).
   - O convite carrega **link com `token_publico`** pro portal externo (padrão Edicaorota — motorista acessa via token).
   - **Portal do fornecedor**: tela pública (sem login Genesis) onde fornecedor:
     - Vê os itens e termos da cotação.
     - Preenche preço unitário, prazo de entrega, validade da proposta, observações.
     - Envia. Pode reabrir até o prazo expirar (ou até o ciclo ser fechado).

4. **Avaliação e seleção**
   - Tela do operador mostra todas as propostas lado a lado, ranking por critério da estratégia.
   - Operador seleciona vencedor (com justificativa).
   - **Aprovação da seleção** (uma camada simples, igual binária do Edicaorota — gestor confirma).

5. **Devolução ao solicitante (Callback Registry)**
   - Quando a cotação é fechada (vencedor confirmado), Cotacoes dispara callback pro módulo solicitante via `CotacaoCallbackInterface` + `CotacaoCallbackRegistry`.
   - Compras (futuro consumidor) implementa o callback em `Adapters/Compras/Callbacks/CompraCotacaoCallback.php` — recebe o id da cotação + vencedor + preços e atualiza o Pedido de Compra com a referência.

6. **Histórico / auditoria**
   - Toda transição registrada (solicitada → enviada → resposta-recebida(N) → avaliada → vencedor-selecionado → aprovada → fechada / cancelada / expirada) com **quem + quando**.
   - Cada proposta de fornecedor tem trilho próprio (envio do convite, abertura do portal, submissão, edição, expiração).

7. **Tela de admin de fornecedores (mínima)**
   - **Não é** a Missao Fornecedores completa — é um cadastro mínimo dentro de Cotacoes (ou uma sub-Missao) com: razão social, CNPJ, contato (email/celular), categorias atendidas. Suficiente pra alimentar o convite.
   - Se a Missao `Fornecedores` for desenvolvida em paralelo, Cotacoes consome via Adapter.

## Fora do escopo (próximas fases)

- **Leilão reverso** (rodadas com visibilidade entre fornecedores). Exige UX de tempo-real.
- **Anti-abuse avançado** no portal do fornecedor (CAPTCHA, fingerprinting, fraud detection). MVP usa só rate limit + expiração de token.
- **Login persistente do fornecedor** (criar conta, histórico próprio). MVP é portal stateless por token.
- **Integração com B3 / cotações de mercado** ou marketplaces (Mercado Livre, Bling Marketplace).
- **Renegociação automática** (rodadas adicionais, contraproposta).
- **Cadastro completo de fornecedores** (avaliação, blacklist, scoring histórico, documentos fiscais). Cobertura mínima no MVP.
- **Notificações in-app** pro operador (caixa de entrada Genesis) — usar Otp só na ida; volta é polling/refresh.

## Restrições / dependências conhecidas

- **Padrão arquitetural V2**: Sondas, Laboratorios, Validators, Enums com FSM, Callbacks Registry, Adapters/<Dominio>/. Referência: `Logistica/Edicaorota`.
- **Multi-tenant**: `customerControl=true, companyControl=true`.
- **Acesso externo via token público** segue o padrão `Edicaorota` (token gerado, expira, validado por Sonda) — reutilizar a engenharia de validação e expiração.
- **Mensageria/Otp** já existe e tem canais Email/WhatsApp/Log — Cotacoes registra evento próprio (`CotacaoConviteEvento`) seguindo o padrão `EdicaoRotaOtpEvento`.
- **Compras (`PRD/compras/`) é o primeiro consumidor** mas Cotacoes deve ficar agnóstico — interface/Adapter no centro, e Compras pluga via `Cotacao/Adapters/Compras/`.
- **Catálogo de produtos** (`Constelacoes/Produtos/Crud`): itens cotados podem ou não estar no catálogo (cotação avulsa de serviço/insumo não cadastrado também precisa funcionar — usar string-livre + product_id opcional).
- **LGPD / dados de fornecedor**: portal público expõe dados da cotação ao fornecedor convidado; PO valida o que pode ou não aparecer (ex.: não revelar preços de concorrentes).

## Métricas de sucesso (alto nível)

- **% de ciclos com >= 3 propostas em estratégias Comparativas** — sinal de que o convite chega e o portal funciona.
- **Tempo médio convite → primeira resposta** — sinal de UX do portal e do canal.
- **Taxa de expiração** (cotações que fecham sem qualquer resposta) — sinal inverso de saúde.
- **% de cotações fechadas com justificativa de seleção preenchida** — sinal de auditoria.
- **Reutilização do módulo**: número de módulos consumidores além de Compras (meta inicial: 0 no MVP, mas arquitetura permite).
- **Erros no portal externo / acessos negados** — saúde técnica.

## Inspirações / referências

- **Internamente**: `Logistica/Edicaorota` — padrão de portal externo via `token_publico`, FSM, Callbacks Registry e Adapters/<Dominio>/. `Mensageria/Otp` — Registry de canais. `Logistica/MissaoLogistica/Strategies` — Factory + Interface pra múltiplas Strategies.
- **Externamente**: portais de cotação RFQ (Bionexo, Mercado Eletrônico, Linkana, ME Compras), funcionalidade "Pedidos de Cotação" do Sankhya/Protheus.

## Dúvidas em aberto pro PO

1. **Granularidade do convite** — fornecedor recebe 1 link por cotação (vê todos itens) ou 1 link por item (cota cada item separado)?
2. **Visibilidade entre concorrentes** — fornecedor vê quem mais foi convidado? Vê preços de concorrentes após o fim? (impacta confiança e LGPD)
3. **Critério de ranking da Comparativa** — só preço, ou score composto (preço × prazo × histórico do fornecedor)? Configurável por cliente?
4. **Edição da proposta pelo fornecedor** — pode editar quantas vezes até o prazo? Ou só envio único?
5. **Itens fora do catálogo** — fornecedor pode adicionar item alternativo (substituto)? Ou tem que cotar exatamente o pedido?
6. **Aprovação da seleção** — sempre exigida ou só acima de certo valor? Quem aprova? (conexão com regras de Compras?)
7. **Cadastro de fornecedores** — desenvolver mínimo dentro de Cotacoes ou bloquear até `Missoes/Fornecedores` virar Sonda? Política do produto.
8. **Notificação de proposta recebida** — operador é notificado em tempo real (Otp/email) a cada resposta, ou só consulta a tela?
9. **Cancelar cotação em andamento** — operador pode cancelar a qualquer momento? Fornecedores que já responderam são notificados?
10. **Cotação sem solicitante automatizado** — operador pode criar cotação avulsa (sem vir de outro módulo) e usá-la como referência histórica? Ou Cotacoes só nasce a partir de solicitação?
11. **Token público — TTL** — quanto tempo o link fica válido após envio? Configurável por cotação ou por cliente?
12. **Anexos** (PDFs de proposta formal, fichas técnicas) — fornecedor pode anexar arquivo no portal? MVP ou v2?