Manual de Uso do OIKVRA

1. O que é o OIKVRA e como este manual deve ser usado

O OIKVRA foi concebido como uma plataforma empresarial modular. Para o usuário, isso significa que produtos, estoque, vendas, compras, financeiro, fiscal, logística e demais domínios não devem funcionar como ilhas: cada informação relevante é criada uma vez, reutilizada pelas rotinas autorizadas e preservada com histórico.

Este manual tem três objetivos. Primeiro, ensinar a lógica comum do ERP, para que a pessoa entenda o que está fazendo mesmo quando muda de módulo. Segundo, orientar as rotinas operacionais de Produtos e Estoque. Terceiro, servir como base de treinamento, consulta e futura certificação.

Princípios que se repetem em todo o sistema

• Uma informação, uma origem. O mesmo item não deve ser recadastrado para cada canal.
• Estado explícito. Rascunho, revisão, ativo, bloqueado, reservado, quarentena e outros estados têm significado operacional.
• Automação com evidência. O sistema pode sugerir ou executar rotinas permitidas, mas deve informar o que fez, por quê e como corrigir exceções.
• Humano por exceção. Trabalho repetitivo pode ser automatizado; decisões sensíveis, ambiguidades e desvios sobem para revisão.
• Histórico preservado. Correções não devem apagar a operação original quando a rastreabilidade exigir estorno, compensação ou nova versão.

Para quem este volume foi escrito

Operadores, vendedores, compradores, estoquistas, responsáveis por cadastro, supervisores e gestores que utilizam o ERP no cotidiano. Pessoas responsáveis por implantar, configurar ou governar o ambiente devem ler também o Manual de Parametrização.

2. Conceitos fundamentais: empresa, estabelecimento, papel e escopo

O OIKVRA sempre interpreta uma ação dentro de um contexto. O usuário pode estar autorizado em uma empresa e não em outra; em uma filial específica; em determinados depósitos; ou apenas para certas ações. Por isso, não basta “estar logado”. O sistema combina identidade, papel e escopo para decidir o que pode ser consultado ou alterado.

Antes de confirmar qualquer operação

• Confira a empresa/estabelecimento exibidos no contexto.
• Confirme depósito, canal ou unidade quando a rotina depender deles.
• Se a opção esperada não aparece, não tente contornar o sistema: a causa pode ser permissão, estado do registro ou parâmetro.
• Em caso de acesso indevido aparente, interrompa a operação e comunique o responsável.

3. Acesso, identidade, sessão e segurança do usuário

O acesso deve usar identidade individual. Credenciais compartilhadas impedem atribuir corretamente autoria, enfraquecem a trilha de auditoria e tornam impossível aplicar o menor privilégio de forma confiável.

O que o usuário nunca deve fazer

• Compartilhar senha, código temporário ou token.
• Exportar dados porque outra pessoa “não tem acesso”. O acesso deve ser corrigido pela administração.
• Usar dados reais em planilhas ou sistemas externos não autorizados para “facilitar” uma tarefa.
• Persistir tentando uma operação negada. O bloqueio pode ser uma separação de funções intencional.

A plataforma registra autoria humana ou de serviço, empresa, origem, instante, correlação e, quando aplicável, justificativa e valores antes/depois. Essa rastreabilidade protege a empresa e também o operador.

4. A Tela Hoje, busca, tarefas e ajuda contextual

A experiência projetada do OIKVRA parte da tarefa, não da estrutura técnica do banco de dados. A “Tela Hoje” deve reunir o que a pessoa precisa fazer, revisar e acompanhar conforme seu papel e setor. O objetivo é que um usuário novo encontre tarefas críticas sem decorar caminhos extensos de menu.

Três áreas mentais

A busca deve aceitar, conforme o contexto, nome, apelido, código interno, código de barras e outros aliases autorizados. O sistema não deve exibir custo a quem só tem permissão de venda, mesmo que o registro seja encontrado pela mesma busca.

Ajuda contextual por tela e campo

O OIKVRA foi projetado para associar telas e campos relevantes a uma help_key estável. Com o foco em um campo documentado, pressione Shift + F1 para abrir a explicação daquele campo. Sem um campo específico em foco, o mesmo atalho poderá abrir a ajuda da tela atual. Em estados de exceção, a ajuda poderá direcionar ao tópico que explica o motivo do bloqueio e a forma correta de reparo.

Exemplo: o campo de unidade base usa a chave lógica CAT.PRODUCT.UNIT_BASE. Essa chave permanece estável mesmo que a aparência da tela ou a URL do manual mude. O objetivo é ligar a operação ao ponto exato da documentação sem exigir que o usuário pesquise o capítulo manualmente.

5. Estados, aprovações, automações, exceções e correções

Boa parte dos erros em ERP nasce quando o operador confunde “registrado” com “liberado”, “físico” com “disponível” ou “salvo” com “aprovado”. No OIKVRA, estados são parte da regra de negócio e devem ficar claros.

Como ler um estado

• Rascunho: existe, mas ainda não produz o efeito definitivo esperado.
• Em revisão: depende de validação por pessoa ou regra autorizada.
• Ativo/Vigente/Liberado: passou pelas guardas aplicáveis e pode ser usado dentro do escopo.
• Bloqueado/Quarentena: existe fisicamente ou cadastralmente, porém está inelegível para determinada operação.
• Descontinuado/Expirado: não deve entrar em novas operações, mas permanece no histórico.

Automação não significa ausência de controle

Uma automação pode conciliar, sugerir, encaminhar, pré-preencher ou executar ações permitidas. Ela não pode elevar a permissão do gatilho, atravessar empresas nem repetir efeitos em razão de uma mensagem duplicada. Quando falha, deve gerar exceção com causa, responsável e evidência suficiente.

Corrigir não é apagar

Movimentos confirmados de estoque, por exemplo, não devem ser editados como se nunca tivessem existido. A correção adequada é um movimento compensatório ou outro mecanismo auditável. Da mesma forma, documentos históricos preservam o contexto e a versão usada à época.

6. Primeiro acesso: roteiro de dez minutos

Este roteiro serve para qualquer usuário recém-habilitado. Ele não altera configurações administrativas.

7. Como pesquisar antes de criar

Pesquisar antes de cadastrar é uma regra operacional central. Duplicidades de item propagam problemas para preço, estoque, compra, venda e fiscal.

Ordem recomendada

1. Pesquise pelo código de barras quando disponível.
2. Pesquise pelo SKU ou código conhecido.
3. Pesquise pelo nome e por partes relevantes da descrição.
4. Considere aliases de fornecedor ou canal apresentados pelo sistema.
5. Se existirem candidatos semelhantes, compare unidade, variante, marca/modelo e estado antes de decidir criar.

8. Como interpretar mensagens, bloqueios e permissões

Uma mensagem deve ser tratada de acordo com a categoria do problema, não apenas pela cor visual. Use o quadro abaixo como referência.

9. O que é um item no catálogo

O catálogo unifica itens vendáveis e compráveis sem exigir cópias para cada canal. Um registro pode representar produto, serviço, kit, assinatura ou bem controlado. A distinção define o comportamento, especialmente se existe ou não movimento físico de estoque.

Produto e serviço compartilham a identidade de catálogo, mas apenas itens controlados fisicamente geram movimentos de estoque. Kit comercial, lista de materiais industrial e pacote de serviços são conceitos distintos.

10. Cadastrar um produto: fluxo funcional completo

O cadastro deve começar pela identificação, não pelo preenchimento de uma ficha extensa. A interface projetada pode apresentar campos progressivamente conforme o tipo de item e a finalidade.

11. SKU, códigos de barras e aliases externos

O SKU interno identifica o item de forma estável dentro da plataforma. Ele não deve ser substituído toda vez que um fornecedor, marketplace ou canal alterar seu próprio código. Esses identificadores externos entram como aliases com escopo.

Boas práticas para o operador

• Não reutilize um SKU de item antigo para um item novo.
• Não crie novo produto apenas porque o fornecedor usa outro código.
• Se um código de barras já estiver vinculado a outro item ativo, trate como conflito de dados.
• Ao resolver duplicidade, preserve o histórico e utilize o mecanismo de alias/mescla autorizado.

O sistema pode permitir busca por foto ou semântica como forma de localizar candidatos, mas uma correspondência ambígua deve exigir escolha humana.

12. Unidades e conversões: caixa, unidade, peso e outras medidas

A unidade base é a referência do item. Compra e venda podem ocorrer em unidades diferentes desde que exista conversão versionada e válida. O sistema deve preservar a quantidade, a unidade original e a conversão usada no documento.

Cuidados

• Conversões devem ser exatas o suficiente para o negócio e seguir arredondamento declarado.
• Massa não deve ser convertida automaticamente em volume sem um fator específico válido para o item/contexto.
• Alteração futura do fator não reescreve documentos históricos.
• Se o operador perceber que uma unidade cadastrada está errada, deve interromper o lançamento e solicitar correção, em vez de compensar mentalmente.

13. Variantes e grade

Variantes permitem compartilhar a identidade de família do produto sem perder o saldo e o código próprios de cada combinação. Moda, calçados, cores, tamanhos, voltagens e outras características são exemplos comuns.

Uma grade correta evita dois extremos: criar produtos totalmente desconectados para cada variação ou manter um único SKU incapaz de representar saldos diferentes.

Ao selecionar uma variante

• Confirme os atributos exibidos, não apenas o nome do item pai.
• Use o código/barra da variante quando disponível.
• Em recebimento e separação, valide a variante física antes de confirmar o movimento.

14. Classificação fiscal e revisão responsável

O catálogo pode armazenar NCM/NBS, CEST, origem e outros elementos fiscais com vigência e fundamento. A classificação fiscal não deve ser tratada como um campo comum que qualquer usuário preenche para “liberar” uma venda.

Quando uma classificação estiver ausente, vencida ou em conflito, o item deve ir para a fila de revisão apropriada antes de uma operação fiscal que dependa dela. Sugestões automáticas ou por IA devem apresentar evidências e permanecer sujeitas à aprovação do responsável.

15. Tabelas de preço, canal, vigência e proteção de margem

Preço é contextual. Uma tabela pode depender de canal, segmento, moeda, data de vigência e prioridade. O preço usado em uma operação deve guardar a tabela, regra, desconto, moeda e vigência que justificaram o cálculo.

O que o usuário deve conferir

• Canal e data da operação.
• Preço retornado e, quando permitido, explicação da regra aplicada.
• Desconto dentro da alçada.
• Alertas de margem mínima.

Custo e margem são informações sensíveis. Um vendedor sem permissão não deve obtê-las por busca, API, exportação ou relatório. Se o sistema bloquear a publicação ou desconto por margem, a conduta correta é acionar a alçada prevista.

16. Kits, substitutos e descontinuação

Um kit comercial reúne componentes para venda. Quando a política prevê reserva dos componentes, vender um kit deve reservar cada componente uma única vez e o estorno deve recompor corretamente essa reserva.

Quando um item deixa de ser comercializado, o estado “descontinuado” impede novas ofertas conforme a política, mas não apaga vendas, compras, movimentos ou documentos antigos. Pode existir um substituto sugerido; a troca não deve acontecer silenciosamente.

17. Importação e sincronização de catálogo

Importações e integrações devem ser idempotentes: repetir a mesma carga com a mesma chave externa não pode criar cópias do item. O sistema deve oferecer prévia, apontar conflitos e produzir relatório das rejeições.

Antes de confirmar uma carga

• Confira a origem e a finalidade do arquivo.
• Verifique quantos registros foram reconhecidos como existentes, novos, conflitantes e rejeitados.
• Revise unidades, códigos e campos sensíveis sugeridos.
• Não aceite sobrescrita silenciosa de classificação fiscal ou outro dado previamente aprovado.
• Guarde o relatório de resultado quando a operação for relevante para auditoria.

18. Entender saldo físico, disponível, reservado e em conferência

“Ter no depósito” não significa necessariamente “poder vender”. O estoque é derivado dos movimentos e condições dos itens. A interface deve traduzir isso em conceitos operacionais claros.

19. Depósitos, endereços e condições de estoque

Uma empresa pode ter vários depósitos e, dentro deles, endereços ou posições. O mesmo item pode existir em condições diferentes: liberado, quarentena, bloqueado, consignado ou de terceiro.

O operador deve sempre confirmar onde está movimentando e em qual condição. A automação de endereçamento pode sugerir a próxima posição considerando capacidade, giro e restrições, mas a leitura física continua importante quando o fluxo exigir conferência.

Erros a evitar

• Receber no depósito errado e “corrigir” depois sem motivo.
• Usar endereço genérico para itens que exigem rastreabilidade.
• Confundir propriedade com localização: estoque de terceiro pode estar fisicamente dentro da empresa.

20. Recebimento de mercadoria

O recebimento conecta a origem comercial/fiscal ao movimento físico. A simples chegada do caminhão não significa que o item já está disponível.

21. Lote, série e validade

Lote e série permitem rastrear unidades ou grupos de unidades. Itens serializados não podem manter duas unidades ativas com a mesma série quando a regra exige unicidade. Validade influencia elegibilidade e pode orientar separação.

Durante o recebimento

• Leia ou informe o lote/série conforme o documento e o item físico.
• Confira validade antes de liberar.
• Não substitua lote ou série por texto livre em observação.
• Quando o dado físico não coincide com o documento, registre a divergência.

Lotes vencidos, bloqueados ou recolhidos não podem ser expedidos por uma rota alternativa para contornar a trava.

22. Quarentena, bloqueio e liberação de qualidade

Quarentena separa “recebido fisicamente” de “liberado para uso”. Enquanto o lote ou saldo estiver bloqueado, ele não deve participar da disponibilidade vendável nem ser reservado.

A liberação deve exigir a capacidade correspondente e, quando aplicável, evidência de inspeção. Se uma venda ou separação tentar usar saldo bloqueado, a operação deve ser impedida e indicar a causa.

23. Reservas e concorrência sobre o último saldo

Reserva compromete parte do saldo elegível com uma origem, como um pedido. A política deve impedir que duas operações simultâneas capturem a mesma última unidade, salvo uma política explícita e autorizada de venda sem estoque.

O operador não deve

• Repetir a confirmação várias vezes para “ver se entra”.
• Criar ajuste artificial para liberar uma venda sem investigar.
• Alterar a origem da reserva para mascarar o compromisso anterior.

24. Separação, onda, leitura e expedição

Separação transforma reservas em itens fisicamente preparados para expedição. Uma onda pode agrupar linhas segundo regras operacionais. A leitura deve reduzir trocas de SKU e impedir fechamento de volume com item incorreto.

25. Transferências entre depósitos

Transferência não é uma troca instantânea de saldo entre duas colunas. O modelo canônico reconhece saída, trânsito e entrada. Isso permite descobrir perda, atraso ou divergência durante o percurso.

Se o destino recebe quantidade diferente da enviada, a diferença precisa de investigação e tratamento próprio. Não ajuste a origem retroativamente para fazer os números “baterem”.

26. Inventário, contagem cega e recontagem

Inventário mede a aderência entre posição física e registro. Em contagem cega, o contador não vê o saldo esperado, reduzindo o risco de repetir mentalmente o número do sistema.

O objetivo não é “zerar divergências” a qualquer custo, mas explicar e corrigir a posição com trilha.

27. Ajustes: quando usar e por que nunca editar o saldo diretamente

Ajuste é uma operação excepcional e auditável. Deve possuir motivo, responsável e autorização compatível com valor/quantidade. O movimento anterior continua consultável.

Exemplos legítimos

• Divergência confirmada após contagem e recontagem.
• Avaria identificada sem outro documento operacional apropriado.
• Correção compensatória de lançamento incorreto, seguindo o procedimento definido.

Exemplos inadequados

• Aumentar saldo para concluir uma venda.
• Apagar perda para melhorar indicador.
• Modificar manualmente o número exibido sem movimento de origem.

28. Consignação, propriedade e estoque de terceiros

Posse física e propriedade econômica são dimensões diferentes. Um item de terceiro pode estar no seu depósito e, ainda assim, não compor indevidamente o estoque próprio contábil. Da mesma forma, mercadoria própria pode estar sob guarda de terceiro.

Ao operar estoque consignado, confira sempre o campo/indicador de propriedade e a origem. Movimentar fisicamente não autoriza alterar a natureza da propriedade.

29. Custeio e o que o operador precisa saber

O método de separação física, como FIFO ou FEFO, não determina automaticamente o método de custeio contábil. O valor do estoque deve ser conciliável com o sublivro e a política declarada.

Na rotina operacional, o usuário deve garantir que movimentos tragam origem, quantidade, unidade e, quando exigido, custos ou documentos corretamente associados. A escolha e governança do método de custeio pertencem à parametrização e contabilidade.

30. Automações e IA em Produtos e Estoque

O OIKVRA projeta automações para reduzir trabalho repetitivo sem ocultar a decisão. Em Produtos, podem existir sincronização de catálogo, alerta de margem e enriquecimento de dados. Em Estoque, endereçamento, reposição de picking e inventário cíclico podem ser sugeridos ou automatizados dentro da política.

IA pode sugerir descrição/classificação, recuperar itens por imagem, prever risco de ruptura ou excesso e detectar movimentos atípicos. Essas funções devem explicar a base da sugestão e respeitar revisão humana quando houver impacto sensível.

31. Situações frequentes e como agir

32. Checklists rápidos de operação

33. Glossário essencial

Alias

Código externo ou alternativa de busca vinculada a uma identidade principal.

Disponível

Saldo elegível para nova operação segundo reservas, bloqueios e demais regras.

Endereço

Posição interna de armazenagem dentro de um depósito.

Idempotência

Propriedade que impede uma repetição técnica da mesma solicitação de produzir o efeito duas vezes.

Item

Identidade de catálogo para produto, serviço, kit, assinatura ou bem controlado.

Kit comercial

Oferta composta por componentes, distinta de uma lista de materiais industrial.

Lote

Grupo rastreável de unidades com atributos compartilhados.

Reserva

Compromisso de quantidade elegível com uma origem, como uma linha de pedido.

Série

Identificador individual de unidade quando a rastreabilidade exige unicidade.

SKU

Código interno estável do item ou variante.

Tenant

Fronteira organizacional de isolamento da plataforma.

Variante

Combinação específica de atributos de um item pai, com código/saldo próprios quando aplicável.

WMS

Conjunto de capacidades de gestão de armazém, endereçamento, separação, contagem e movimentação.

34. Rastreabilidade documental deste volume

Este volume foi derivado dos documentos funcionais canônicos do projeto OIKVRA, com foco nas áreas de Organização/Cadastros Mestres (CAD), Catálogo (CAT), Estoque/WMS (EST), Orquestração/Automação (AUT), Plataforma/Identidade/Segurança (PLT) e Experiência Guiada (UX).

A rastreabilidade por códigos CX exibida ao final dos capítulos permite relacionar o texto editorial aos requisitos de produto sem publicar documentos internos do projeto.