# ENG-3114 — Matriz dos caminhos de quantidade

## Critério e fronteira

A proteção é por produto/depósito e não depende da sessão/rua/OP informada no cliente. O guard roda antes das escritas nas entradas de serviço; os modelos quantitativos também encapsulam escritas diretas em transação e chamam a mesma regra.

Guardas de modelo resolvem identidades novamente após adquirir locks. Alteração de identidade de item, setor ou localização usa proteção exclusiva. Mudanças de labels sem efeito quantitativo continuam permitidas e não modificam a fotografia.

A auditoria é agendada pelo guard e persistida pelos eventos de transação somente no nível externo zero. HTTP e console usam o mesmo mecanismo. Não há captura por linha que transforme recusa em sucesso parcial.

| Grupo | Entrada/escritor | Proteção/fronteira | Evidência |
| --- | --- | --- | --- |
| API de transferência em lote | TransferableController → TransferableTransferItemService::transferMany | Conjunto inteiro antes da primeira transação de estoque; transação do serviço. | InventoryMovementTest (lote misto); smoke Playwright com API real, SKU bloqueado e SKU livre. |
| Transferência unitária, coleta e ajuste genérico | transferOne, transactionOne e chamada direta a transferItemToRecipient; subclasse TransferableTransferPickedItemService | Mesmo guard, origem e destino; chamadas aninhadas mantêm locks e auditoria até o rollback externo. | InventoryMovementTest; regressão Transferable comparada à base. |
| Escrita direta de item | ItemStoreService, ItemUpdateService, ItemDeleteService e Item::save/delete | Preflight de serviço; trait protege o próprio write, releitura de identidade e row lock. | InventoryOperationalPathsTest e InventoryMovementTest: aumento, redução, exclusão, endereço novo, item zero e reatribuições. |
| Geração/entrada | GenerateItemService e ItemTransferService | Transação externa antes da geração; valida o produto/contextos antes de criar item/progresso. | InventoryOperationalPathsTest; transferência genérica; nenhuma consulta ERP no guard. |
| Ajustes web/app | ItemAdjustmentService e StockAdjustmentService | Lote completo de produtos e criação de item; reduções/remoções continuam pelo serviço comum. | InventoryMovementTest; regras anteriores de OP 0 preservadas. |
| Aplicação de sincronização | SyncItemsService, ProductsItemsHandler e StorageItemsHandler | IDs existentes/informados e conteúdo de contêineres antes de alterar/remover. | InventoryOperationalPathsTest; InventoryStorageTest. |
| Job de entrada da Expedição | ProcessInputProductsJob → ItemStore/Update, PickedItemStore, TransactionStore | Cada StockIO é uma transação externa com preflight de todas as linhas; um System não contorna o bloqueio. | InventoryInputJobTest usa dispatchSync real, comprova origem job, ator System, rollback e ausência de ERP. |
| Importadores Senior de NF/pedido/requisição | SeniorSyncInvoiceJob, SeniorSyncPurchaseOrderJob e SeniorSyncRequestsJob | Escritas cadastrais/de demanda não são saldo físico; eventual aplicação física usa escritores protegidos. Não são liberados ajustes ERP por causa do bloqueio. | Inspeção dos chamadores; regressões cadastrais herdadas. |
| Entrada Senior do Almoxarifado | SeniorSyncInputWarehouseJob | Identificação/atualização local de Item e PickedItem passa pela defesa de modelo; setor Warehouse não vira depósito 004. | Cenários fora do contexto; regressões do Almoxarifado. |
| Separação | PickItemFromAddressService e RequestSeparationService | Guard antes dos locks decisivos de tarefa/item e da transferência; PickedItem também protegido. | InventoryOperationalPathsTest e regressões PickingOrder/Request; SourceStockIO e endereço determinam o contexto. |
| Trânsito de transferência | TransferTaskPullProductService, PushProductService, PickProductService e PickedTransferTaskProduct::save/delete | Reserva/coleta protegida, mesmo antes de mudar items.amount; sugestões e origem real entram na validação. | InventoryOperationalPathsTest; concorrência real início/pull e início/coleta. |
| Cancelamento de tarefa | TransferTaskCancelService | Mudar cabeçalho não prova coleta resolvida; início consulta a pendência real, não só a situação da tarefa. | InventoryOperationalPathsTest com tarefa cancelada e coleta TRANSFERRING. |
| Embalagens de expedição | ShippingPackagingQuantityService::add/removeAll/transfer/transferAll | Guard antes de manipular embalagens; protege quantidade mesmo sem alterar items.amount. | InventoryOperationalPathsTest, incluindo máquina do OperationalActor e movimentos parciais/totais. |
| Escritas/cascatas de embalagem e separação | ShippingPackagingProduct, PickedItem, StockIOProduct, ShippingPackaging e StockIO | Defesa de save/delete para quantidade, identidade e remoção de detentor com material; não bloqueia mera alteração de demanda/status. | InventoryOperationalPathsTest: remoção de linha, saída, embalagem e item separado. |
| Estorno/devolução/entrega | Serviços Request e cancelamento de separação/finalizações StockIO/PickingOrder | Deslocamento físico usa TransferableTransferItemService/Item/PickedItem. Quantidade de demanda/status sozinha não é movimentação física. | Matriz de escritores compartilhados; regressões adicionais comparadas à base, com limitações registradas nas evidências. |
| Caixas/paletes legados | Storage, Item.storage_id e Item cujo detentor é Storage | Conteúdo e posicionamento serializados pelo componente de contêineres; depósito vem de Address/StockIO persistidos, não do criador da caixa. | InventoryStorageTest com contêiner aninhado, transferência do invólucro e conteúdo Warehouse; corrida de contêiner inicialmente vazio. |
| Cadastros com efeito sobre localização | AddressUpdateService, Address/StockIO::save/delete e Product::delete | Inclui produtos de descendentes/contêineres, setor antigo e proposto; exclusão não remove material protegido. | InventoryMovementTest; concorrência Warehouse → Expedição com write já aguardando. |
| SQL em lote dentro da transferência | Detach/exclusão de picked_items após transferência/recalculo | A operação externa já protege o produto e detentores; não é entrada pública independente. | Lote atômico e defesa de exclusão/cascata; inspeção do serviço comum. |
| Consultas e metadados sem quantidade | Catálogo, hierarquia, labels, status de tarefas e demanda planejada | Não tratados como estoque; fotografia de iniciado é persistida. | Teste de labels alteradas sem mutar fotografia e leituras administrativas. |

## Eventos e limites

ServiceProcessed::dispatch já é no-op na base; não foi reativado nem refeito. ExpeditionReplenishmentTrigger já publica o job com afterCommit. Recusas não deixam item, progresso, transação ou quantidade parcial.

A consulta de concorrência usa PostgreSQL real: pg_blocking_pids comprova a espera em processos independentes. Testes sequenciais/mocks não são apresentados como prova de disputa.

Esta é a matriz dos escritores inspecionados, não uma promessa de interceptar SQL administrativo ou qualquer futuro QueryBuilder::update/delete. Novos caminhos quantitativos devem passar pelo guard antes de escrever e atualizar esta matriz com teste comportamental.
