Contratos transacionais

SaaS de compras e controle de gastos para médias empresas brasileiras, com compras indiretas e insumos de produção desde a v1. O ciclo utilizável inclui demanda, aprovação, cotação, pedido oficial Nexio, recebimento/aceite, conferência de nota e integração com ERP. IA será consultiva: recomenda quando e de quem comprar, explica limitações e registra decisão humana.

Este documento fixa contratos mínimos entre módulos. Não especifica integralmente telas ou endpoints de Requisição, Cotação, Pedido, Contrato, Recebimento e Nota/Conferência. Esses seis módulos ainda precisam de suas especificações transacionais completas e implementação.

Começar com importação validada de cadastros, orçamento e demanda, configuração guiada por empresa e política simples de aprovação. Governança avançada é progressiva; controles explicitamente habilitados continuam obrigatórios. O piloto deve medir tempo até primeira compra, esforço de cadastro, taxa de devolução por configuração e fechamento do ciclo com ERP.

Raiz, linha e fatia têm IDs estáveis e independentes: documentId, lineId, allocationId. Reordenar não troca identidade. Remover preserva a linha histórica; reinserir outro item cria nova linha. Dividir/combinar cria novas identidades e relações de origem, sem reaproveitar ID de conteúdo incompatível.

Mapear referência externa uma vez; conflito de mapeamento é pendência humana, não upsert arbitrário. Atualização compara versão e rejeita mensagem atrasada ou fora de ordem. Integração sem versão fornece chave de evento estável e política de reconciliação por fonte. Todo join, chave de dedupe e consulta aplica tenant e empresa; supplierId restringe portal, sem depender do id informado pelo cliente.

O Nexio numera, aprova e emite o pedido oficial, incluindo destinatário fiscal, revisão e conteúdo enviado ao fornecedor. O ERP recebe a mesma revisão, com referência e identidade da operação. Falha do ERP deixa pendência de integração, sem apagar pedido já emitido. Se o cliente exigir aplicação prévia como pré-condição de emissão, isso precisa ser uma política explícita antes da primeira emissão e não uma suposição do adaptador.

Preservar histórico de tentativas e acknowledgements, sem regredir estado por resposta atrasada. Envio de revisão n+1 depende da aplicação ou resolução explícita da n quando o destino exige sequência. Dedupe no ERP usa chave de origem; sem suporte, o adaptador precisa consultar resultado e encaminhar ambiguidades, sem prometer exactly-once.

Alteração de pedido circula como revisão candidata. A efetiva continua exigível, recebe entregas e conserva obrigação. Na efetivação da alteração, reavaliar controles e aplicar apenas delta líquido de valor/quantidade/data por parcela, com reclassificações quando necessário. Rejeitar candidata mantém versão anterior. Retorno do ERP não edita conteúdo aprovado silenciosamente.

Compra centralizada pode ter uma negociação comum, mas gera pedidos separados por destinatário fiscal. Rateio é sempre dentro da Company do pedido. Transferência intercompany física/contábil exige processo ERP e referências próprias.

Regras canônicas em Orçamento, Fluxo de Aprovação, Moeda e Unidade de Medida. Novos compromissos sem verba em escopo controlado são impedidos; RequireApproval precisa da aprovação correspondente; autoridade ausente não cria alçada.

Necessidade planejada, entrega prometida, recebimento/aceite, período de prestação e contabilização são fatos distintos. Nota não substitui data de recebimento. Nota mais cara ajusta o Actual correspondente; não liquida de novo Obligation já recebida e não usa Adjustment para aumentar orçamento.

postingGroupId identifica a operação e entryOrdinal cada entrada. Liquidação e reversão apontam a entrada e a parcela; backfill, reorçamento e virada transferem por pares balanceados. A soma econômica consolidada é conservada nas reclassificações. Somente mudanças de valor econômico ou verba autorizada alteram os totais respectivos.

Último voto sem verba: guardar voto e Returned com motivo na mesma transação, sem Approved nem lançamento adicional. Falha técnica reverte tudo. Alteração de política ou cadastro não reescreve fatos; qualquer reclassificação registra origem, antes/depois e justificativa.

Fechamento impede novas intenções no período fechado, mas fatos tardios continuam registráveis: período aberto com competência original referenciada quando a janela de lançamento tardio encerrou. CancelOpen não extingue obrigação jurídica vigente. Reconciliação deve explicar diferenças entre razão gerencial, documento fiscal e contabilidade ERP.

MRP, estoque e custeio industrial continuam externos. A v1 deve aceitar a demanda e programação desses sistemas e informar pedidos, confirmações e recebimentos com identidade consistente. O cliente precisa conhecer o atraso da sincronização; não apresentar saldo de estoque importado como disponibilidade em tempo real.

Cada Recommendation registra id, instante, empresas/escopo autorizados, tipo (quando/de quem), alternativas elegíveis, versão de regra/modelo/prompt, objetivo, restrições, estimativas, unidades/moedas e evidenceSnapshotId. O snapshot referencia cada fonte, versão, observedAt, período de validade, transformações e lacunas. Dados fornecidos por terceiros são conteúdo, nunca instrução para executar ação.

A explicação apresenta por que uma alternativa atende melhor ao objetivo e quais fatores mudariam o resultado. Fornecedor de R$ 1.050 pode superar o de R$ 1.000 se frete e atraso estimados forem menores; mostrar as parcelas, hipótese de atraso e incerteza, sem esconder o preço maior. Recomendação nunca dispensa alçada ou controle.

Compra antecipada exige demanda, posição de estoque, trânsito, prazo e custo de manter capital/estoque suficientemente atuais. Sem isso, devolver InsufficientData ou recomendação limitada ao que os dados sustentam, listando dados ausentes/vencidos; não inventar data ótima nem confiança numérica sem avaliação. Limiares de atualidade variam por fonte e caso de uso, definidos com o cliente.

Registrar HumanDecision com recomendação/revisão, autor autorizado, opção escolhida, aceitação/rejeição/alteração, motivo e data. Emitir pedido continua sendo ação humana autorizada nos controles normais. Resultados posteriores se ligam à decisão, sem mudar retroativamente a recomendação.

Avaliar contra baseline explícito (por exemplo, menor custo elegível e política atual), com separação temporal de treino/avaliação, prevenção de vazamento de resultados futuros e métricas de custo total observado, prazo, ruptura e adoção. Usar replay histórico e modo sombra antes de orientar operação; aceitar recomendação não prova benefício causal. Monitorar cobertura, erro e degradação por segmento, com opção de desligar recomendações sem interromper compras.

Preparar identidades, snapshots e resultados agora. Feature store, banco vetorial, treinamento próprio, agentes autônomos e infraestrutura dedicada podem esperar evidência de volume e ganho. Não há autorização para IA comprar ou aprovar sozinha.

Chamadas obrigatórias na transação; eventos em memória após o commit produtor; reações essenciais com outbox do produtor e inbox do consumidor. Tabela/migração pertence ao contexto, mecanismo à plataforma. Arquivos exigem versão imutável, veredito e download dos mesmos bytes; desfecho GrydFiles/Nexio atômico exige DbConnection e DbTransaction compartilhadas.

A implementação deve verificar a composição de API, Portal, Worker e Migrator por execução. Todo comando de worker deve declarar tenant/empresa e credencial de serviço; testes de revogação e limpeza de contexto são requisitos pendentes. Migração cobre todos os módulos usados, com trava exclusiva, versões compatíveis, retomada e restore ensaiado. Operadores têm fila de pendências, retry idempotente, reconciliação e trilha.

Definir RPO/RTO, retenção e responsáveis no onboarding operacional e medir restauração antes do piloto. Distinguir restauração técnica do banco de reconciliação de efeitos já enviados ao fornecedor/ERP. Não declarar prontidão com base somente em testes de estrutura.

Estes são requisitos para testes de domínio, integração e operação quando os módulos existirem. Verificação numérica dos exemplos e links nesta revisão documental não equivale à implementação desses cenários.

1. Antes das transações: identidades/revisões/parcelas, autoridade empresarial, arredondamento, razão e coordenação explícita. Publicar contratos e dependências da plataforma.
2. Primeiro ciclo utilizável: importação, demanda, aprovação, cotação, pedido, recebimento/aceite e nota/ERP, com pendências e reconciliação. Validar direto e indireto no mesmo piloto.
3. Antes do primeiro cliente: isolamento real, restore, migração, retries, revogação, arquivos e observabilidade demonstrados; configuração guiada com responsáveis.
4. Antes da IA: cobertura/qualidade de dados e resultados, baseline e avaliação temporal. Começar por recomendação explicável em modo sombra.

Hipóteses ainda sem validação: disposição a pagar, ganho de produtividade, esforço de implantação e manutenção de cadastros, cobertura de ERP e benefício da recomendação. Preservar monolito e quatro perfis; não adicionar infraestrutura física ou de ML para compensar ausência de evidência de produto.