Introdução
No Odoo, um modelo define a forma como a informação é organizada e guardada na base de dados. Tudo o que representa um registo de negócio — encomendas, faturas, movimentos de stock — vive num modelo que estabelece campos, tipos e relações.
Perceber os modelos do Odoo é obrigatório tanto para consultores funcionais como para programadores. Eles são a espinha dorsal da arquitetura de dados: definem campos, ligações e a lógica que automatiza processos.
Aqui vamos focar-nos num dos modelos essenciais do Odoo: stock.move. Quer esteja a construir módulos de armazém, a integrar sistemas externos ou a configurar fluxos de inventário, com toda a probabilidade irá interagir com este modelo.
O que é o modelo stock.move
O stock.move representa um único movimento de inventário: a transferência de um artigo de uma localização para outra. Cada vez que algo sai de uma prateleira, muda de armazém ou é expedido para um cliente, é gerado um registo stock.move.
O módulo de Inventário (Stock) usa intensamente este modelo. Vendas, Compras, Produção e lojas online criam registos stock.move sempre que disparam operações de stock. Confirmar uma entrega, receber mercadoria ou finalizar uma ordem de fabrico resulta em criação ou atualização destes registos.
O modelo base encontra-se no módulo stock e é habitualmente extendido por outros módulos via herança de modelos do Odoo. O módulo de Vendas liga a encomenda à movimentação; Compras liga a linha de compra; Produção associa a ordem de fabrico. Cada aplicação acrescenta apenas o necessário, mantendo o núcleo intacto.
Campos principais do modelo
Segue-se um resumo dos campos mais relevantes do stock.move. Conhecê-los permite gerir melhor reservas, rastreabilidade e integração com outros processos.
1. name
Tipo: Char. Identifica a movimentação com uma descrição legível (normalmente produto e quantidade). É o rótulo que aparece nas listas e documentos e ajuda o utilizador a reconhecer o movimento.
2. product_id
Tipo: Many2one (product.product). O produto que está a ser movido. Campo obrigatório — sem um produto não há movimento. Odoo usa-o para contabilizar quantidades e aplicar regras de inventário.
3. product_uom
Tipo: Many2one (uom.uom). A unidade de medida associada à quantidade. Obrigatório. Normalmente corresponde à UoM padrão do produto; o sistema valida as quantidades com base nesta unidade.
4. product_uom_qty
Tipo: Float. A quantidade planeada para movimentar, na unidade do produto. Representa a necessidade; o valor efetivamente processado fica em quantity_done.
5. quantity
Tipo: Float. Campo de exibição ou calculado que mostra a quantidade (por vezes convertido entre UoMs). Usado nas vistas para apresentação ao utilizador.
6. location_id
Tipo: Many2one (stock.location). Local de origem do movimento — de onde sai o produto. Campo obrigatório e crítico para assegurar níveis correctos de stock.
7. location_dest_id
Tipo: Many2one (stock.location). Local de destino — para onde vai o produto. Também obrigatório; define se é uma entrega ao cliente, recepção a armazém, ou outro.
8. picking_id
Tipo: Many2one (stock.picking). Documento de transferência que agrupa os movimentos (ordem de entrega, receção interna). Useful para operações de picking e interface de utilizador.
9. picking_type_id
Tipo: Many2one (stock.picking.type). Tipo de operação (saída, entrada, transferência interna). Define regras padrão, locais por defeito e o fluxo de trabalho associado.
10. state
Tipo: Selection. Estado actual do movimento: draft, waiting, confirmed, assigned, done, cancelled. Indica se o movimento está por confirmar, reservado, concluído, etc.
11. date
Tipo: Datetime. Data agendada para a execução do movimento. Usada para planeamento, priorização e coordenação das operações de armazém.
12. date_deadline
Tipo: Datetime. Prazo do movimento — por exemplo a data prometida de entrega ao cliente. Serve para cálculos de urgência e relatórios SLA.
13. origin
Tipo: Char. Referência ao documento originador (n.º da encomenda de venda, compra ou ordem de fabrico). Facilita a rastreabilidade entre documentos.
14. move_dest_id
Tipo: Many2one (stock.move). Ligação ao movimento que recebe o output deste movimento. Utilizado para encadear movimentos (ex.: saída de fabrico que alimenta uma entrega).
15. move_orig_ids
Tipo: One2many (stock.move). Movimentos de origem que alimentam este registo — a relação inversa de move_dest_id. Útil para traçar fluxos de materiais.
16. move_line_ids
Tipo: One2many (stock.move.line). Linhas detalhadas do movimento: lotes, números de série, localizações específicas. São criadas ao reservar ou processar estoque.
17. partner_id
Tipo: Many2one (res.partner). Parceiro associado (cliente para entregas, fornecedor para receções). Usado para moradas, comunicações e relatórios.
18. company_id
Tipo: Many2one (res.company). Indica a empresa em cenários multi-empresa. Afeta visibilidade, regras de contabilidade e políticas inter-company.
19. quantity_done
Tipo: Float. Quantidade efectivamente processada. É actualizada durante o picking/receção; o movimento só fica em done quando quantity_done alcança product_uom_qty.
20. reserved_availability
Tipo: Float. Quantidade reservada para este movimento. Reflete o stock comprometido quando o movimento é atribuído.
21. create_date
Tipo: Datetime. Data e hora de criação do registo, gerida automaticamente. Essencial para auditoria e históricos.
22. write_date
Tipo: Datetime. Data e hora da última alteração, também automática. Ajuda a saber quando um registo foi actualizado pela última vez.
23. sequence
Tipo: Integer. Ordem de exibição dentro de um picking. Movimentos com número menor aparecem primeiro no interface.
24. priority
Tipo: Selection. Nível de urgência (ex.: normal vs urgente). Influencia o planeamento e a priorização de operações.
25. description_picking
Tipo: Char. Nota ou instrução que aparece no documento de picking. Útil para instruções especiais de manuseio.
26. reference
Tipo: Char. Referência interna ou código para mapear com sistemas externos ou para rastreamento personalizado.
27. group_id
Tipo: Many2one (procurement.group). Grupo de procurement que liga movimentos associados a uma mesma necessidade (por exemplo, uma encomenda de venda).
28. procure_method
Tipo: Selection. Estratégia: make to stock ou make to order. Define se se retira stock existente ou se dispara produção/compra.
29. sale_line_id
Tipo: Many2one (sale.order.line). Campo adicionado pelo módulo de Vendas. Liga o movimento à linha de venda que o originou para fins de rastreabilidade.
30. purchase_line_id
Tipo: Many2one (purchase.order.line). Campo adicionado pelo módulo de Compras. Liga o movimento à linha de compra quando se recebem bens de fornecedores.
31. production_id
Tipo: Many2one (mrp.production). Campo adicionado pelo Manufacturing. Liga movimentos às ordens de fabrico para gerir consumo de matérias-primas e produção.
32. active
Tipo: Boolean. Indicador de arquivamento. Quando False o registo fica oculto nas vistas por defeito, sem ser eliminado da base de dados.
Como este modelo entra nos processos empresariais
1. Entrega ao cliente
Ao confirmar uma encomenda de venda, o Odoo gera movimentos para cada linha. O local de origem é o armazém e o destino é a localização do cliente; os movimentos aparecem agrupados num picking (ordem de entrega). Durante o picking actualiza-se quantity_done e o estado passa a done quando concluído.
2. Receção a fornecedores
Quando se confirma uma encomenda de compra, o sistema cria movimentos de entrada: o local de origem representa o fornecedor e o destino o armazém. As linhas ficam agrupadas numa receção; ao validar a chegada de mercadoria actualiza-se quantity_done.
3. Transferência interna
Movimentos entre armazéns ou entre localizações internas criam registos stock.move com origem e destino específicos. São usados para reabastecimentos, redistribuição de stock e operações multi-armazém.
4. Produção
Ordens de fabrico geram movimentos de dois tipos: saída de matérias-primas para a produção e entrada de produto acabado para o stock. O campo production_id relaciona movimentos com a ordem de fabrico e o encadeamento de movimentos liga produção a entregas posteriores.
5. Devoluções e sucata
Devoluções de clientes criam movimentos inversos; operações de sucata movem artigos para uma localização de sucata. O mesmo modelo stock.move suporta estes fluxos; é o tipo de picking que regula o comportamento.
Como os programadores alargam este modelo
Os programadores alargam o stock.move usando padrões próprios do Odoo, com a herança de modelos como principal ferramenta.
Herança de modelo
Utilize _inherit = 'stock.move' num módulo para estender o modelo: acrescente campos, sobreponha métodos ou valide regras. Essa abordagem mantém as alterações isoladas e facilita actualizações do Odoo.
Adicionar campos
Declare novos campos no modelo herdado com os tipos adequados: Char, Many2one, Boolean, Integer, Text, Selection. Em cenários multi-empresa pense em campos dependentes da company. Exemplos comuns para stock.move incluem números de tracking personalizados, referências de transportadora ou atributos de lote.
Extensões em Python
Sobreponha métodos como _action_done, _action_assign ou _action_cancel para injetar lógica adicional, chamando super() para preservar o comportamento base. Tenha cuidado com actualizações de inventário e encadeamentos de movimentos para não introduzir inconsistências.
Odoo Studio
O Odoo Studio permite adicionar campos sem escrever código — útil para personalizações rápidas no formulário de movimento. Para alterações de lógica ou fluxos complexos, módulos personalizados são mais sustentáveis.
Boas práticas
- Defina sempre correctamente location_id e location_dest_id. Localizações incorrectas levam a contagens de stock erradas e problemas de reconciliação.
- Agrupe movimentos relacionados usando picking_id. Evite criar movimentos isolados que pertençam a uma mesma transferência.
- Para integrações, use a API (XML-RPC/JSON-RPC). O modelo stock.move está exposto; faça um mapeamento cuidadoso de IDs e external_ids para evitar colisões.
- Ao adicionar campos personalizados, prefixe com x_ ou com o prefixo do módulo para reduzir a hipótese de conflito em atualizações futuras do Odoo.
- Use move_dest_id e move_orig_ids para garantir rastreabilidade. Quando gerar movimentos encadeados programaticamente, estabeleça correctamente estas referências.
- Preste atenção a quantity_done vs product_uom_qty ao validar movimentos. Odoo permite entregas parciais — trate esses casos na lógica de negócios.
Erros frequentes
- Criar movimentos com tipos de localização incompatíveis. Origem e destino têm de ser compatíveis (por exemplo, não faz sentido que ambos sejam localizações de cliente).
- Alterar product_uom_qty depois de existirem move lines. Isso pode criar discrepâncias no inventário; o procedimento seguro é anular e recriar o movimento.
- Esquecer de definir origin. Sem essa referência torna-se difícil ligar o movimento ao documento que o gerou para fins de auditoria.
- Sobrepor _action_done sem chamar super(). Tal prática pode quebrar actualizações de inventário e funcionalidades de outros módulos.
- Criar movimentos directamente, ignorando o fluxo (por exemplo sem passar por stock.picking). Contornar o picking pode inviabilizar reservas e atribuições automáticas.
- Ignorar move_dest_id ao dividir ou unir movimentos. Movimentos encadeados ficam órfãos se os relacionamentos não forem mantidos.
Conclusão
O modelo stock.move é o núcleo do inventário no Odoo: regista cada deslocação de mercadoria entre localizações. Conhecer os seus campos e as formas como os módulos o ampliam ajuda a configurar, personalizar e integrar o Odoo com segurança.
Seja a sua função mapear processos de armazém ou desenvolver módulos, dominar o stock.move evita retrabalho e falhas operacionais.
Precisa de ajuda na sua implementação Odoo?
A Dasolo acompanha empresas na implementação, personalização e optimização do Odoo. Especializamo-nos em integrações por API e desenvolvimento de módulos, com experiência profunda na arquitectura de dados e modelos como o stock.move.
Se precisa de apoio na sua implementação Odoo, desenvolvimento de módulos personalizados ou integrações, podemos ajudar. Agende uma demonstração para discutir o seu projecto.