Manual de Parametrização do OIKVRA

1. O papel do parametrizador no OIKVRA

Parametrizar não é “preencher todas as opções”. É transformar a política real da organização em configurações explícitas, testáveis, versionáveis e compreensíveis para quem opera. O parametrizador deve reduzir complexidade para o usuário final sem esconder controles necessários.

Este manual pressupõe que a administração respeita quatro princípios: menor privilégio, segregação de funções, mudança controlada e rastreabilidade. Um parâmetro que altera disponibilidade, preço, fiscal, estoque ou autorização deve possuir dono, motivo e, quando aplicável, vigência.

Responsabilidades típicas

• Definir estrutura de empresa/estabelecimento e escopos.
• Configurar papéis e capacidades.
• Governar unidades, tipos de item, variantes e regras de catálogo.
• Definir depósitos, endereços, condições de estoque e políticas de reserva.
• Estabelecer tolerâncias, alçadas, motivos e fluxos de exceção.
• Homologar mudanças antes de liberar em produção.

2. Ambientes, versionamento e ciclo de mudança

Uma mudança de parâmetro deve ser tratada como mudança de produto operacional. O ciclo recomendado é propor → simular/testar → revisar → aprovar → vigorar → observar → corrigir/aposentar.

Parâmetros fiscais, financeiros e de autorização não devem receber valores fictícios apenas para permitir que o fluxo avance.

3. Estrutura organizacional e contexto operacional

Antes de Produtos e Estoque, defina a fronteira organizacional. Tenant isola a organização; empresa e estabelecimento modelam o contexto de operação. Depósitos e demais escopos dependem dessa estrutura.

Decisões mínimas

4. Papéis, capacidades, alçadas e segregação de funções

A autorização combina papel com atributos. Um papel genérico “estoque” não é suficiente para todas as empresas: o usuário pode ler um depósito, transferir entre dois, contar em um terceiro e não aprovar ajustes em nenhum.

Capacidades de referência em Produtos

• cat.item.read — consultar catálogo.
• cat.item.write — criar/editar itens no escopo.
• cat.cost.read — visualizar custo.
• cat.price.publish — publicar preço.
• cat.taxclass.approve — aprovar classificação fiscal.
• cat.barcode.resolve — resolver duplicidade de barras/aliases.
• cat.export — exportar catálogo conforme escopo.

Capacidades de referência em Estoque

• est.balance.read, est.receipt.record, est.transfer.execute, est.adjust.approve, est.lot.release, est.reserve.override, est.count.record.

5. Catálogo mestre, tipos de item e campos mínimos

Defina quais tipos de item a empresa usará e quais campos se tornam obrigatórios por finalidade. O cadastro inicial deve ser mínimo; campos adicionais aparecem quando necessários para comprar, vender, armazenar ou emitir documento.

Política de estado

Adote o ciclo rascunho → revisão → ativo → descontinuado. Defina quais mínimos impedem a ativação e quais áreas revisam comercial/fiscal.

6. Política de SKU, aliases e códigos de barras

Escolha uma política de SKU estável. Evite derivar significado demais do código, pois categorias e fornecedores mudam. O SKU identifica; atributos explicam.

Regras recomendadas

• SKU não reutilizável após descontinuação.
• Códigos de fornecedor e marketplace como aliases com escopo.
• Conflito de código de barras cria fila de gestão de dados, não sobrescrita automática.
• Importações usam chave externa idempotente.
• Busca pode indexar aliases, mas nunca revelar custo a perfil sem permissão.

7. Unidades, conversões, precisão e arredondamento

Mantenha um catálogo de unidades e defina conversões por item quando necessário. Cada fator relevante deve possuir vigência/versionamento suficiente para explicar documentos passados.

Parâmetros

• Unidade base.
• Unidades de compra e venda permitidas.
• Fator de conversão e precisão.
• Regra de arredondamento.
• Conversões proibidas sem fator específico, como massa ↔ volume.

8. Atributos, variantes e grades

Defina dicionários de atributos por família de produto. Atributos estruturados permitem variante, busca, integração e estoque por combinação. Evite criar campos livres diferentes para o mesmo conceito.

Exemplo de política

Cada variante que representa saldo distinto deve possuir identificação própria suficiente, sem duplicar o item pai inteiro.

9. Política de preços, canais, prioridade, vigência e margem

Modele tabelas de preço por canal/segmento/moeda somente quando existe regra de negócio que justifique a distinção. Defina prioridade para conflitos e não permita duas regras igualmente prioritárias e vigentes para o mesmo contexto sem critério de desempate.

Checklist de uma tabela

• Moeda.
• Canal/segmento.
• Início e fim de vigência.
• Prioridade.
• Política de desconto e alçada.
• Margem mínima/alerta quando aplicável.
• Quem pode publicar.

Proteja custo em todas as superfícies: interface, API, busca, exportação e relatório. Segurança não termina no front-end.

10. Classificação fiscal, vigência e fila de revisão

Configure a responsabilidade fiscal e o que acontece quando a classificação está pendente ou vencida. O catálogo deve permitir histórico/versionamento da classificação e fundamento suficiente.

Regras de governança

• Somente perfis fiscais aprovam campos definidos como sensíveis.
• Sugestões automáticas nunca substituem a aprovação quando ela é obrigatória.
• Dados vindos de fornecedor ou integração registram origem.
• Classificação vencida não deve ser usada silenciosamente em operação que exige validade.

11. Kits, substitutos e descontinuação

Defina como kits reservam componentes e como novas versões são publicadas. Ciclos de composição devem ser impedidos. Substituto é uma relação explícita; não deve alterar documentos existentes nem trocar item automaticamente sem política clara.

Para descontinuação, decida o tratamento de pedidos abertos, ofertas em canais, saldo remanescente e substitutos. Preserve consulta histórica.

12. Importação, chave externa e política de conflito

Antes de liberar cargas em massa, defina a chave externa por origem e o comportamento para quatro classes: novo, já existente, conflito e rejeitado.

Teste repetição da mesma carga. O resultado não pode criar duplicidade.

13. Desenho de depósitos e endereços

Modele depósitos conforme fronteiras operacionais reais: recebimento, armazenagem, picking, devolução, quarentena, terceiro etc. Nem toda diferença física precisa virar depósito separado; às vezes condição ou endereço resolve melhor.

Perguntas de desenho

• A transferência entre áreas precisa de estado “em trânsito” ou é movimentação interna?
• Quais endereços possuem capacidade/restrição?
• Quais itens podem ocupar cada zona?
• Há necessidade de leitura obrigatória?
• Quais perfis podem atuar em cada depósito?

Evite um depósito “GERAL” usado para tudo quando a operação precisa distinguir responsabilidade e condição.

14. Fórmula de disponibilidade e política de reserva

Disponibilidade deve derivar de movimentos, reservas e condições elegíveis. Defina a fórmula concreta de forma a não subtrair a mesma reserva duas vezes. A política também deve dizer se existe venda sem estoque e quem pode usar override.

Teste crítico de concorrência

Com uma unidade elegível, dispare duas solicitações simultâneas de reserva. O resultado esperado é uma reserva válida e um conflito informado, salvo política explícita diferente.

15. Lote, série, validade e regras de elegibilidade

Classifique quais famílias exigem lote, série e/ou validade. Defina unicidade de série, captura obrigatória no recebimento e expedição, e comportamento para vencidos.

Regras mínimas

• Série ativa não duplicada por item quando a rastreabilidade exigir.
• Lote/série preservados em cada movimento.
• Validade vencida torna o saldo inelegível.
• Bloqueio ou recall impede saída por todas as rotas.

16. Quarentena e integração com qualidade

Defina quais origens ou categorias entram em quarentena automaticamente, quem pode liberar e quais evidências são necessárias. O saldo em quarentena deve ficar excluído da disponibilidade.

Se qualidade não estiver habilitada como módulo completo, ainda assim a condição operacional precisa ser explícita e auditável; não use endereço físico como único substituto para o estado.

17. FIFO, FEFO e estratégia de separação

Escolha a política de seleção física por família quando necessário. FEFO prioriza validade; FIFO prioriza ordem de entrada. Regras de picking podem ainda considerar endereço, unidade logística e eficiência.

Documente exceções e não misture estratégia física com método contábil de custeio. Teste lotes com datas diferentes e um lote bloqueado para garantir que o motor nunca escolha o saldo inelegível.

18. Transferência, trânsito e divergência

Configure transferências com estados distintos para saída e entrada. A quantidade em trânsito deve permanecer rastreável. Defina quem pode expedir, receber e tratar divergência.

Cenários de homologação

• Transferir 5 unidades: origem reduz, trânsito recebe 5, destino aumenta somente após conferência.
• Destino recebe 4: uma unidade permanece divergente/em investigação conforme política.
• Solicitação repetida: não duplica a transferência.

19. Inventário cíclico, contagem cega, tolerância e recontagem

Defina periodicidade e critérios de seleção do inventário cíclico: valor, risco, giro, histórico de divergência ou combinação. A contagem cega deve ocultar o saldo esperado do contador.

Parâmetros

• Tolerância absoluta e/ou percentual por classe.
• Quando exigir recontagem.
• Quando exigir outro responsável.
• Quem aprova o ajuste.
• Motivos padronizados de diferença.

Evite tolerâncias tão largas que transformem inventário em mero ritual. Use relatórios de acurácia para revisar a política.

20. Ajustes, motivos e alçadas

Crie motivos de ajuste que descrevam a causa, não o efeito. “Diferença de estoque” é pouco informativo; avaria, perda confirmada, erro de recebimento identificado, contagem confirmada e outras categorias permitem análise posterior.

Defina alçada por quantidade, valor e/ou categoria. O perfil que registra a contagem não deve automaticamente aprovar todo ajuste sensível. Preserve o movimento anterior e crie compensação auditável.

21. Propriedade, consignação e estoque de terceiros

Habilite dimensões de propriedade quando a operação precisar separar posse de ativo econômico. Defina valores permitidos, contratos/origens e como relatórios contábeis consomem essa dimensão.

Teste um item de terceiro fisicamente presente: ele deve aparecer para operação física sem compor indevidamente estoque próprio no processo contábil.

22. Onda de separação, conferência e reposição de picking

Defina quando pedidos entram em ondas, critérios de agrupamento e áreas de picking. Reposição pode ser acionada por demanda e mínimos, mas deve respeitar bloqueios e capacidade.

Homologação mínima

• Leitura de SKU errado impede fechamento.
• Quantidade separada não ultrapassa reserva elegível.
• Lote bloqueado não entra na tarefa.
• Reposição não cria movimento duplicado em reprocessamento.

23. Automações: gatilho, condição, ação, guardrails e exceção

Cada automação deve declarar gatilho, pré-condições, escopo, ação, versão e comportamento de falha. Antes de ativar, execute simulação ou teste em cenário representativo.

Exemplos: alertar preço abaixo de margem; sincronizar catálogo aprovado; sugerir endereçamento; repor picking; priorizar contagem cíclica. A automação nunca deve elevar permissões.

24. Auditoria, dados sensíveis e exportações

Defina quem consulta trilhas e com qual finalidade. Eventos confirmados devem ser preservados mesmo após estorno. Para Produtos e Estoque, audite publicação de preço, classificação fiscal, mudança de unidade/kit, acesso a custo, leituras/divergências, contagens, ajustes e bloqueios de lote.

Exportação é uma capacidade própria. Um usuário capaz de ler um registro na interface não precisa ter permissão para exportar todo o conjunto. Custo e outros dados sensíveis requerem proteção em todas as superfícies.

25. Indicadores que ajudam a validar a parametrização

26. Plano de homologação de Produtos e Estoque

Não libere parametrização apenas porque a tela “salvou”. Homologue efeitos de negócio.

27. Checklist de go-live para parametrização

• Estrutura de tenant, empresa e estabelecimento revisada.
• Papéis e escopos validados com usuários de teste.
• Menor privilégio confirmado para custo, preço, fiscal e ajustes.
• Tipos de item e unidades aprovados.
• SKUs/aliases sem conflitos conhecidos.
• Preços com vigências e prioridades consistentes.
• Fluxo fiscal de classificação definido.
• Depósitos, endereços e condições validados.
• Reserva concorrente testada.
• Lote/série/validade testados quando aplicáveis.
• Quarentena e liberação testadas.
• Transferência com trânsito testada.
• Inventário cego, tolerância e recontagem testados.
• Motivos e alçadas de ajuste aprovados.
• Automações testadas com repetição e falha.
• Trilhas de auditoria consultáveis.
• Plano de suporte e responsáveis definidos.
• Usuários receberam treinamento correspondente ao papel.

28. Controle posterior: revisão de acesso e parâmetros

Go-live não encerra a parametrização. Estabeleça revisões periódicas de acesso, regras de preço, unidades, estoque, automações e indicadores. Credenciais e integrações precisam de rotação/revogação conforme política.

Mudanças relevantes devem gerar nova versão, teste e comunicação. Evite “ajustes emergenciais” permanentes sem documentação; a exceção temporária precisa de dono e data para revisão.

29. Como este manual pode virar formação oficial

A arquitetura editorial já separa conhecimento por papel e por competência. Isso permite transformar capítulos em trilhas de aprendizagem sem duplicar conteúdo.

Certificação futura

Uma certificação pode combinar estudo do manual, exercícios em ambiente de treinamento, avaliação teórica e prova prática baseada em cenários. A certificação não deve existir apenas como “presença em curso”: precisa medir competência observável e possuir versão alinhada à edição do produto.

30. Rastreabilidade documental do Manual de Parametrização

As políticas descritas neste volume foram derivadas principalmente dos domínios CAT, EST, CAD, PLT, AUT e UX do blueprint funcional OIKVRA. Os códigos CX ao final de cada capítulo são o elo de manutenção editorial.

Quando um requisito canônico mudar, a revisão do manual deve localizar todos os capítulos associados, avaliar impacto, atualizar exemplos/testes e incrementar a edição. Isso cria uma disciplina editorial compatível com futura publicação impressa: uma edição do livro corresponde a uma baseline funcional identificável.