# ENG-2777 - Saída de itens para reclassificação por QR code de OP

## Estado e fontes

Especificação com decisões confirmadas, premissas e validações técnicas separadas. O usuário aprovou criar novas tarefas apenas com o saldo restante, mostrar esse saldo na conferência, dispensar embalagem de expedição nesta rotina e reutilizar a criação e a execução existentes. Para o estoque, a premissa autorizada é manter a seleção padrão, sem restringir ou acrescentar sugestão pela OP de origem do material.

### Implementação local do fluxo de consulta e criação

A integração da feature foi adicionada localmente aos dois repositórios: consulta AOP autenticada e somente leitura; revisão por OP com `qtdPrv` como necessidade total e coletas/reservas WMS separadas; confirmação com snapshot revalidado, idempotência e lock; uma tarefa pelos saldos disponíveis, iniciada pelo serviço padrão; tela para leitura contínua, revisão, equipe/responsável e recuperação da confirmação; navegação à execução padrão de Saídas. As rotas são `stock.expedition.output.reclassification.consult` e `stock.expedition.output.reclassification.store`.

Validações locais: as seis feature tests novas passaram com 62 assertions; 51 testes das suítes de início padrão/alocação e pré-faturas passaram com 221 assertions; testes mobile do serviço, scanner e executor passaram com 45 testes; Pint, lint PHP e verificação de rotas passaram. A seleção backend ampliada foi interrompida por timeout e não conta como completa. O Jest mobile completo teve 42 suítes aprovadas e duas falhas em trabalho local não relacionado de idempotência; o typecheck global segue falhando em idempotência e `AlmoxarifadoSaidas.tsx`. Nenhum arquivo novo da feature foi listado nos diagnósticos do typecheck.

QA manual do caminho feliz foi concluído em aparelho Android conectado por USB, contra o backend local e a cópia WMS `armazenagem`: as OPs 245649 e 245767 foram revisadas, incluídas em uma única tarefa (103443) e separadas integralmente, 5 CT e 8 CT. A tarefa preliminar 103442 foi encerrada sem coleta antes do teste combinado. As chamadas ao ERP foram somente de leitura; não houve apontamento ou baixa no Senior. Permanecem a comparação de quantidade/unidade com o relatório Rex, a verificação documental ENG-2784 e a autorização de implantação. A seção de continuidade de 21/10/2026 abaixo é o registro histórico da base anterior à integração; o status atual detalhado está em [eng-2777-continuidade-implementacao.md](eng-2777-continuidade-implementacao.md).

- Issue: [ENG-2777](https://linear.app/soelx/issue/ENG-2777/m05-saida-de-itens-reclassificados-por-qr-code-de-op), com o [handoff do primeiro incremento](https://linear.app/soelx/issue/ENG-2777/m05-saida-de-itens-reclassificados-por-qr-code-de-op#comment-9e8ae653).
- Backend analisado: `rex-back`, `main` em `db4676b782cea81bc9a172808d835a2a3a237103`.
- Mobile analisado: `Rex-Estoque`, `main` em `edb2ac0e62ea2dd14fbcb3441ae059a0c59e7382`.
- Branch de trabalho nos dois repositórios: `feature/eng-2777`.
- [Contrato AOP verificado em homologação](eng-2777-contrato-aop-homologacao.md), com WSDL/XSD e as três consultas encadeadas para outra OP autorizada como exemplo.

## Incremento já entregue

O primeiro incremento de backend está concluído nos commits locais `f35c9117` e `d0edd533`. Ele interpreta e valida o QR e consulta a operação 499 e seus componentes, sem escrever no ERP. A interface entregue é `ProductionOrderIdentity::fromQrCode()` e `SeniorProductionOrderRead::execute()`. A correção do segundo commit bloqueia estágio de componente divergente da operação validada.

O handoff registra 159 testes aprovados, com 479 asserções, em PHP 8.4 e sem rede, além de Pint aprovado nos arquivos do incremento. Essa evidência pertence ao incremento de leitura; não comprova cadastro WMS, saldo, endpoints, tarefa ou mobile, que ainda não foram implementados por ele.

## Continuação em 21/10/2026 — base anterior à consulta/criação por QR

Esta seção preserva a fotografia técnica da implementação-base anterior aos endpoints, confirmação transacional, tela de revisão e navegação descritos no status atual acima. O [registro de continuidade](eng-2777-continuidade-implementacao.md) mantém histórico dos serviços, testes e decisões; suas auditorias de pendências são datadas e foram supersedidas pelo incremento local mais recente.

- Backend, `1dec733d` e `3e21569d`: `ReclassificationOrderComponentsService::resolve()` consome o resultado do leitor AOP existente. Resolve o cadastro por empresa, `codCmp` e derivação exata, verifica a origem pelo cadastro `family.origin.integration` e exclui as origens não permitidas. Cadastro ausente ou ambíguo, origem sem empresa correspondente e unidade divergente impedem o resultado da OP inteira. O DTO preserva a identidade completa de cada ocorrência e os campos ERP originais, sem calcular saldo ou converter unidades.
- Backend, `25136b03`: registra a identidade completa em `reclassification_demands`, com vínculo único à linha de saída e unidade preservada. O motivo `RECLASSIFICATION=5` distingue essa saída de pré-faturas e requisições. O registro exige uma necessidade WMS já informada; não determina essa quantidade pelos campos AOP.
- Backend, `8c8f3ecc`: calcula saldo sobre necessidade já registrada no WMS, coletas efetivas da mesma linha e parcelas ainda reservadas em tarefas abertas. Os testes cobrem retirada parcial sintética, saldo zero, isolamento por OP, encerramento e exclusão padrão. O cálculo não interpreta `qtdPrv` ou `qtdUti` e ainda não está conectado à leitura de QR.
- Backend, `1112b21c`: requests e serviços de início legado/V2 dispensam embalagem somente para tarefas não vazias de reclassificação com todas as demandas registradas. Pré-faturas, requisições, tarefas mistas e linhas sem demanda não recebem a dispensa. Criação com início automático continua pendente.
- Backend, `700adade`, `c0223607` e `9dff52c3`: a coleta e ambas as finalizações padrão dispensam embalagem somente em reclassificação identificada. Coletas conservam demanda, tarefa e endereço de origem; encerramento total, parcial ou vazio usa quantidades efetivas. Passos mantêm a ordem SQL e oferecem somente a parcela aberta da tarefa. Resources separam necessidade e coleta globais da alocação e das coletas da tarefa atual. A necessidade desses testes é WMS conhecida, não calculada do AOP.
- Backend, `eb2d3a16` e `310bb1c1`: seis testes com processos PostgreSQL independentes verificam exclusividade do vínculo e coleta concorrente, inclusive estoque disputado e um item recebido compartilhado por demandas distintas. Isso não implementa idempotência ou concorrência na criação de tarefas.
- Backend, `26801e6d`: a pausa padrão e o retorno administrativo não reabrem tarefa de reclassificação encerrada. Pausa/retomada de tarefa aberta e retorno de pré-fatura conservam o comportamento.
- Backend, `e2a09337`: a revisão apontou uma disputa entre pré-fatura e reclassificação sobre o mesmo item de estoque. Dois testes reproduziram perda de saldo e retirada acima da disponibilidade. O serviço compartilhado agora bloqueia e relê o item em todas as coletas antes da validação, sem mudar a exigência de embalagem das pré-faturas.
- Backend, `59210601`: seis testes verificam coleta em disputa com fechamento da linha e com as finalizações legada/V2, em ambas as ordens. Comprovam rejeição após encerramento e preservação da coleta parcial com liberação do restante reservado. Não alteram produção nem comprovam exclusão concorrente ou devolução física.
- Backend, `abee6848`: o sincronizador padrão V2 valida a parcela solicitada contra o saldo WMS disponível, sem contar integralmente alocações encerradas ou transferir coletas antigas para a tarefa nova. Exige demanda e contexto válidos e rejeita quantidade inválida. Os 17 testes novos e a disputa real entre dois criadores usam demanda WMS conhecida; não implementam a confirmação por QR, o início automático ou sua idempotência.
- Mobile, `585d4fd` e `44751eb`: o hook `src/pages/Reclassificacao/useProductionOrderScanner.ts` mantém a lista em memória e controla consultas exclusivas, duplicidade e invalidação da sessão ao fechar a câmera. O hook ainda não tem tela, rota ou serviço HTTP associado. Os testes usam consultas simuladas; não comprovam uso da câmera física.
- Mobile, `5b74d6e`: adapta `Saidas/BottomDrawer` e seus helpers para tarefas locais de reclassificação. Mostra a identidade e quantidades globais/da tarefa, dispensa embalagem somente com flag verdadeira do backend e mantém a embalagem opcional e o fluxo de pré-faturas. Testes de componente verificam seleção da ocorrência e OP de origem do estoque. Não há criação por QR, nova navegação ou QA físico; a confirmação individual usa o componente anterior, simulado nesse teste.
- O [contrato AOP](eng-2777-contrato-aop-homologacao.md#evidência-adicional-sobre-quantidades-em-21102026) documenta que a implementação do serviço customizado não foi confirmada independentemente. Por decisão posterior do usuário, a implementação assumirá `qtdPrv` como necessidade total, sem subtrair `qtdUti`; comparar com o relatório Rex em QA.
- As permissões existentes de contexto/Expedição devem ser aplicadas antes da consulta. Não há vínculo WMS usuário/equipe-empresa, e não será criada allowlist por `codEmp`: a autorização da empresa é delegada ao ERP usando as credenciais globais do leitor AOP. `integration.request_company_code` continua específico de requisições.

O registro persistente, o saldo e a execução padrão adaptada têm testes em banco descartável. A seleção anterior passou com 424 testes e 1.500 asserções, sem filtro, mais 15 testes de concorrência executados separadamente. O fluxo por QR foi acrescentado depois, conforme o status atual no início desta spec e o registro de continuidade. O snapshot de testes da base anterior não é uma prova de regressão completa do incremento por QR. A comparação da quantidade/unidade com o relatório Rex permanece QA da premissa `qtdPrv`, não bloqueio para implementação. As decisões D1 a D6 permanecem válidas; QA integrado, verificação documental ENG-2784 e autorização de implantação ainda pendem.

## Objetivo

Adicionar uma forma de criar tarefas de separação a partir de QR codes de ordens de produção. O operador monta a lista de componentes destinados à reclassificação de acabamento e confirma uma única tarefa com o saldo restante de cada item e OP. Depois da criação, a tarefa segue a execução padrão já existente. Não criar outro fluxo de execução. O WMS deve preservar o vínculo com a OP e registrar as quantidades efetivas, inclusive em uma execução parcial.

## Limites obrigatórios

1. A integração com o ERP faz apenas consultas. As portas previstas são `buscar`, `lerComponente` e `ler` de `sapiens_Synccom_lmi_aop`.
2. Não chamar `ApontarOP`, apontar produção, baixar componentes ou executar qualquer outra escrita no ERP, inclusive por efeitos indiretos de serviços reutilizados.
3. A lista nasce das leituras realizadas pelo operador. Não criar sincronização periódica de OPs.
4. Preservar o vínculo de cada item com sua OP. Produtos iguais em OPs diferentes não se tornam uma única demanda sem identificação da OP.
5. Quantidade necessária e quantidade realizada são informações diferentes. Finalizar a tarefa não transforma o saldo não coletado em quantidade coletada.
6. Não alterar o comportamento das tarefas existentes de pré-faturas e requisições para atender a este novo fluxo.

## Contexto operacional confirmado

- A rotina pertence ao setor de Expedição.
- As permissões, a escolha de equipe e responsável e as demais regras de criação seguem os fluxos atuais. Não introduzir uma autorização ou atribuição automática diferente apenas para esta rotina.
- A tarefa de reclassificação inicia sem vínculo obrigatório com embalagem de expedição. A dispensa não altera a regra das tarefas normais de pré-faturas.
- Depois de criada, a tarefa usa a execução padrão, sem outra tela ou ciclo próprio de coleta e finalização.
- Uma nova leitura oferece apenas o que resta retirar. A conferência deve mostrar o necessário, o já separado e o que entrará na nova tarefa.
- A seleção de estoque permanece a padrão, sem filtro, prioridade ou sugestão nova pela OP de origem do estoque. Essa é uma premissa autorizada para a entrega, não uma exigência de rastreabilidade confirmada pela Rex.
- Premissa de quantidade confirmada pelo usuário: `qtdPrv` representa a necessidade total do componente. Não subtrair `qtdUti`; calcular retiradas realizadas pelo histórico WMS e reservas pela regra local existente. Conferir `qtdPrv` com o relatório da Rex em QA, sem bloquear a implementação por falta de código customizado do AOP.
- Autorização de empresa delegada ao ERP: o WMS aplica as permissões existentes para o operador acessar a rotina/contexto da Expedição, mas não manterá uma lista `usuário/equipe → codEmp`. O ERP deve aceitar ou recusar `codEmp` para as credenciais globais usadas pelo leitor AOP. Uma recusa não adiciona a OP à lista. O leitor atual usa credenciais de integração, não as credenciais individuais do operador.

## Fluxo funcional

### M05.1 - Leitura e conferência

1. O operador acessa a rotina de retirada para reclassificação e aciona a leitura de QR code.
2. O app abre a câmera e interpreta empresa, origem e número da OP. Exemplo fornecido na issue:

   ```json
   {"codEmp":1,"codOri":"10","numOrp":274240}
   ```

3. O backend valida os identificadores e o acesso do operador ao contexto operacional da Expedição conforme as permissões existentes. A autorização de `codEmp` é delegada ao ERP para as credenciais de integração do AOP; uma recusa do ERP impede a inclusão da OP. O QR code identifica a OP e não concede permissão WMS.
4. Para cada nova OP lida, o backend consulta o ERP e resolve os componentes elegíveis no WMS. A câmera não deve disparar várias inclusões simultâneas para a mesma leitura.
5. Após a consulta, o app adiciona a OP e seus itens à lista e retorna à câmera para a próxima leitura.
6. Ao sair da câmera, o operador confere a lista agrupada por OP. Cada item mostra produto, acabamento, unidade, quantidade necessária, quantidade já separada e quantidade a separar nesta nova tarefa. Aplicar a regra aprovada em D1, sem apresentar novamente o total como quantidade da tarefa quando já houve retirada.
7. O operador confirma a lista para gerar a tarefa.

Propostas para a primeira versão:

- Manter a lista em elaboração durante a sessão da tela, sem criar tarefa a cada leitura.
- Permitir retirar uma OP da lista antes da confirmação.
- Ao reler uma OP já presente, informar que ela já foi adicionada, sem somar novamente suas quantidades.
- Se uma leitura falhar, explicar o motivo e preservar as OPs já adicionadas. Não incluir apenas parte dos componentes elegíveis da OP com erro.
- Sem permissão de câmera, orientar o operador a habilitá-la. Leitura manual de identificadores e operação offline não fazem parte deste escopo.

### M05.2 - Consulta e identificação dos componentes

Para cada OP:

1. Chamar `buscar` com `codEmp`, `codOri` e `numOrp` do QR code e `codOpr="499"`. Não substituir a empresa ou a origem da OP pela origem cadastral do produto.
2. Validar que cada resultado corresponde à empresa, origem, OP e operação solicitadas. A seleção entre várias ocorrências válidas da operação depende de D3.
3. Obter `codEtg` e `seqRot` da operação retornada. Não fixar estágio ou sequência em código nem escolher outra operação como fallback. Validar a conversão de `codEtg`, que vem como texto na busca e é inteiro na entrada da leitura.
4. Chamar `ler` com a identidade da OP, `codEtg` e `seqRot` encontrados para enumerar `componentes` e suas sequências `seqCmp`. A ausência dessa coleção não autoriza fabricar componentes a partir do cabeçalho da OP.
5. Chamar `lerComponente` para cada ocorrência, com a identidade da OP, estágio e `seqCmp`. Usar o código `codCmp` e a derivação da linha de componente para preencher os argumentos `codPro` e `codDer`, conforme o encadeamento testado. Não confundir `seqRot`, da operação, com `seqCmp`, do componente.
6. Localizar o material no WMS por `codEmp`, `codCmp` e `codDer` efetivamente retornados para o componente. O campo `codPro` devolvido por `lerComponente` não é prova de sua identidade, pois variou com a entrada sem mudar o componente observado. Não procurar apenas pelo código nem substituir uma derivação por outra.
7. Aplicar ao cadastro dos componentes no WMS o filtro de origem `10`, `20`, `30`, `40`, `50`, `51`, `52` ou `54`. As respostas AOP verificadas não publicam essa origem cadastral. O filtro não se aplica a `codOri` da OP.
8. Preservar acabamento, unidade, quantidade necessária e a identificação de cada componente dentro da OP. A derivação do componente pode ser diferente da derivação do produto mostrada por `buscar`.
9. Usar `qtdPrv` como quantidade necessária total. Calcular no backend o saldo com as retiradas efetivas anteriores vinculadas à mesma demanda e as reservas de tarefas abertas, em campos separados. Não subtrair `qtdUti`. Conferir unidade e quantidade contra o relatório da Rex em QA; essa conferência não bloqueia a implementação sob a premissa confirmada.
10. Se os dados não permitirem montar uma lista válida, informar qual OP e qual informação impediram sua inclusão.

Proposta conservadora para dados inválidos: não adicionar a OP quando faltar a operação de encaminhamento, houver ambiguidade na seleção da operação, faltar um produto elegível no WMS ou não houver quantidade válida. Componentes fora das origens permitidas são excluídos pelo filtro, não tratados como falha de cadastro. Se nenhum componente restar, informar que a OP não possui componentes elegíveis.

### M05.3 - Geração e execução da tarefa

1. A confirmação gera uma única tarefa com os saldos restantes dos itens de todas as OPs da lista. Não incluir novamente quantidades que já foram efetivamente retiradas.
2. A tarefa pertence à Expedição, inicia automaticamente sem exigir embalagem de expedição e o app abre a execução padrão já existente. Manter as regras atuais de permissão, equipe e responsável, conforme D4.
3. A execução mantém a ordenação de coletas usada na separação de pré-faturas. Não criar outro algoritmo de roteamento ou fluxo de execução.
4. Cada coleta registra a quantidade efetiva, o item da demanda, a OP e o endereço de origem. A apresentação por endereço não pode apagar a identificação da OP. Fazer apenas as adaptações de identificação necessárias nos componentes existentes, sem duplicar a execução.
5. O operador usa a finalização total ou parcial da tarefa padrão. A releitura posterior da OP serve para criar outra tarefa apenas com o que ainda falta.
6. O WMS preserva as quantidades necessárias e realizadas por item e OP. O saldo não retirado continua identificável, mesmo após o encerramento da tarefa.
7. O encerramento não chama serviços de apontamento, baixa ou liberação no ERP.

Propostas de proteção:

- Revalidar no backend as permissões, os dados usados na confirmação e a disponibilidade para uma nova tarefa. O app não é autoridade para a quantidade.
- Criar e iniciar a tarefa como uma operação local atômica. Uma falha não pode deixar uma segunda tarefa criada por uma nova tentativa do mesmo pedido.
- Proteger no backend confirmações repetidas e concorrentes para a mesma demanda. Desabilitar o botão no app não é suficiente.
- Se a tarefa já existir após perda da resposta, recuperar seu identificador, em vez de gerar outra tarefa.
- Se houver mudança na demanda desde a conferência, apresentar a divergência e pedir nova confirmação, sem substituir quantidades silenciosamente.
- Uma execução sem nenhuma coleta não deve aparecer como retirada realizada. O estado de encerramento deve seguir a regra aprovada para este tipo de tarefa.

## Identidade e quantidades

### Identidade da demanda

A OP de reclassificação é a ordem lida no QR para obter a demanda. Sua identidade inclui `codEmp`, `codOri` e `numOrp`. O mesmo número de OP em empresas ou origens diferentes não identifica necessariamente a mesma ordem.

A OP de origem do estoque é a ordem que originou o material que entrou no estoque. Ela é um conceito diferente da OP de reclassificação e não pode ser deduzida apenas do QR desta rotina. Também não se confunde com a origem cadastral do componente usada no filtro de elegibilidade.

Cada linha precisa distinguir a ocorrência do componente na OP de reclassificação, com `codEtg`, `seqRot` da operação e `seqCmp` do componente retornados pelo ERP. Não usar apenas o ID do produto como chave da lista ou da coleta.

Exemplo de separação obrigatória:

| OP | Produto e derivação | Necessário | Realizado |
| --- | --- | ---: | ---: |
| A | P / acabamento X | 10 | 6 |
| B | P / acabamento X | 7 | 7 |

O sistema não pode gravar apenas uma linha de 17 necessários e 13 realizados. Deve ser possível consultar os 4 não retirados da OP A sem atribuí-los à OP B. Duas ocorrências do mesmo componente dentro de uma OP também não podem se sobrescrever.

### Quantidade necessária, realizada e pendente

- Necessária: `qtdPrv` retornada para a ocorrência do componente no AOP, assumida como necessidade total por decisão do usuário.
- Realizada: soma das coletas efetivas registradas no WMS para aquela linha. Não corresponde à quantidade planejada da tarefa nem a uma marca de status; não usar `qtdUti` como coleta WMS.
- Pendente para nova retirada: necessidade (`qtdPrv`) menos coletas efetivas WMS. As reservas ainda abertas são contabilizadas separadamente para determinar o que pode entrar em outra tarefa. Aplicar o tratamento existente para alocações e tarefas em andamento, sem criar um cálculo paralelo no mobile.

Respeitar a unidade `uniMed` e a precisão sem arredondamento silencioso. A comparação com o relatório Rex serve para QA da premissa e do mapeamento do serviço customizado; não bloqueia a implementação assumindo `qtdPrv` como total.

## Pontos técnicos já identificados

Estes pontos descrevem o código existente, não um contrato pronto para reclassificação:

- `rex-back/Domain/Shared/Integrations/Senior/SeniorSoapClientFactory.php` permite construir e substituir o cliente SOAP em testes. O serviço `rex-back/Domain/Shared/Integrations/Senior/SeniorProductionOrderRead.php` já foi entregue para executar as três leituras, com identidade validada e dados originais preservados. Reutilizá-lo nos próximos incrementos, sem reimplementar o adaptador.
- `rex-back/Domain/Shared/Integrations/Senior/SeniorImportBase.php` verifica `statusProcesso`, que não faz parte das saídas AOP verificadas. O adaptador AOP precisa tratar `erroExecucao`, mensagens funcionais e identidade dos dados. Nas amostras válidas, `buscar` retornou mensagens nulas, enquanto `ler` e `lerComponente` retornaram `msgErr="OK"`.
- `rex-back/app/Models/PickingOrder/PickingOrderProduct.php` relaciona a linha da tarefa a `stock_io_product_id` e aos `pickedItems`. Esse vínculo é uma referência para preservar demandas diferentes do mesmo produto.
- `rex-back/Domain/PickingOrder/Services/V2/ExpeditionPickingOrderStoreService.php` cria tarefas para várias pré-faturas, com validação e locks. Ele é específico de pré-faturas, equipe e saldo desse fluxo; não é uma entrada pronta para OPs.
- `rex-back/Domain/PickingOrder/Services/ExpeditionPickingOrderCandidateRouteService.php` ordena candidatos pela disponibilidade e pela ordem física dos endereços da equipe. `rex-back/Domain/PickingOrder/Services/PickingOrderRemainingStepsService.php` obtém os passos da função SQL `ordering_product_picking`. Reutilizar essas regras não significa calcular uma distância geométrica mínima.
- Requests e serviços `PickingOrderStartService` e `V2/PickingOrderStartService` usam `PickingOrder::requiresShippingPackaging()`. A dispensa aprovada em D4 vale somente para tarefas de reclassificação com vínculos persistentes, sem remover a proteção das tarefas normais de pré-faturas. A coleta também usa essa distinção e mantém os vínculos de demanda, tarefa e endereço.
- As duas versões de `PickingOrderFinishService` e `StockOutputFinishService` agora distinguem reclassificação. O caminho específico calcula status por coleta efetiva e mantém o saldo da necessidade global, sem aplicar cancelamento automático de produtos do caminho antigo.
- `rex-back/Domain/StockIO/Enums/StockOutputReasonEnum.php` tem o motivo `RECLASSIFICATION=5`. `ReclassificationDemandStoreService` exige esse motivo em saída de Expedição, o produto correto e a mesma unidade. Não cadastrar a demanda como pré-fatura ou requisição para contornar validações.
- `Rex-Estoque/src/components/CameraScanner/CameraScanner.tsx` já oferece câmera, tratamento de permissão e callback de leitura. A rotina precisa bloquear callbacks concorrentes durante a consulta e reabilitar a próxima leitura. O componente também tem leitores Honeywell e externo, mas o Honeywell substitui o callback por uma função vazia após uma leitura. Manter o componente aberto não garante leitura contínua nesses modos; se forem reutilizados, validar a continuidade sem alterar as rotinas existentes. A câmera é o modo exigido nesta entrega.
- `Rex-Estoque/src/pages/Requisicoes/CriarRequisicao/CriarRequisicao.tsx` já protege consultas de leitura com `scanInFlight`, cancelamento e identificação da sessão do scanner. Reaproveitar esse padrão para ignorar respostas que cheguem após fechar a câmera. Não copiar o fechamento automático após encontrar um produto, pois a leitura de OPs deve continuar.
- `Rex-Estoque/src/pages/Saidas/BottomDrawer/BottomDrawer.tsx` contém a execução de saídas. `Rex-Estoque/src/domain/erp/services/PickingOrderRemainingStepsService.ts` e `Rex-Estoque/src/domain/erp/services/PickingOrderFinishService.ts` usam rotas de Expedição. Essa execução deve ser reutilizada, com as adaptações pontuais necessárias para preservar a OP e a dispensa de embalagem.
- `Rex-Estoque/src/pages/AlmoxarifadoTarefaSaidas/ExecutarSaida/ExecutarSaida.tsx`, em `handleVerifyProduct`, seleciona a primeira linha encontrada pelo ID do produto. Esse critério não distingue OPs ou ocorrências diferentes do mesmo componente. Qualquer reaproveitamento dessa tela precisa selecionar a linha da demanda correta antes de registrar a coleta.
- `Rex-Estoque/src/pages/Saidas/pickingOrderExecution.helpers.ts` distingue falta de passos de fim da tarefa com produtos pendentes. Manter essa proteção; ausência de sugestão de endereço não comprova que toda a demanda foi coletada.

A reutilização da execução, da seleção de estoque e das regras atuais de criação está confirmada. A mudança é a entrada de demandas por QR de OP, com criação apenas do saldo restante e conferência explícita das quantidades. Adaptar os registros existentes para preservar a identidade de cada item e OP de reclassificação. Não implementar restrição adicional pela OP de origem do estoque nesta entrega. Não duplicar o módulo de separação nem modificar as integrações de faturamento.

## Decisões e validações

### D1 - Saldo restante e conferência aprovados

O usuário aprovou que uma nova tarefa contenha apenas o que ainda falta retirar. Se a demanda é de 100 peças e uma tarefa anterior retirou 40, a próxima tarefa deve conter 60, não 100. A tarefa anterior segue seu encerramento padrão; a nova entrada por QR não cria outro processo de execução.

Na conferência de cada item e OP, a tela deve deixar claro:

| Informação | Exemplo |
| --- | ---: |
| Quantidade necessária | 100 peças |
| Já separado | 40 peças |
| A separar nesta tarefa | 60 peças |

Mostrar as quantidades na unidade do material. O exemplo em peças não aprova converter automaticamente outra unidade retornada pelo ERP. Se não houver saldo disponível para criar, informar que não há quantidade restante e não gerar tarefa vazia.

O backend calcula e revalida o saldo na confirmação. O mobile apenas exibe o resultado. Reutilizar as regras existentes de alocação, reserva, cancelamento e devolução, sem contar como realizado o que apenas foi planejado em uma tarefa. A apresentação de eventual quantidade comprometida em tarefa aberta deve explicar a diferença entre o que falta retirar e o que está disponível para criar agora.

A premissa de implementação é `qtdPrv` como necessidade total. O cálculo subtrai somente as coletas efetivas do WMS; reservas abertas reduzem a disponibilidade para nova tarefa sem virar coleta. `qtdUti` não participa do saldo. Em QA, comparar a quantidade e `uniMed` com o relatório Rex para a mesma OP, operação e ocorrência do componente e registrar divergências, sem alterar a regra aprovada sem nova decisão.

### D2 - Premissa autorizada de seleção padrão do estoque

O usuário definiu como premissa desta entrega que a tarefa pode usar qualquer estoque que o fluxo padrão já considere elegível para o mesmo componente, empresa e derivação/acabamento. Manter as validações, restrições e a ordenação existentes. Não adicionar filtro pela OP que originou o material, nem confundir essa OP com a de reclassificação lida no QR.

Uma anotação manuscrita não fornece automaticamente um identificador consultável pelo sistema. A disponibilidade de um vínculo entre material e OP de origem do estoque ainda não foi comprovada nesta investigação. Essa ausência de evidência não bloqueia a implementação com seleção padrão.

Não criar uma sugestão, prioridade ou campo novo de OP de origem apenas para esta rotina. Se o fluxo padrão já exibir ou utilizar essa informação, preservá-lo sem mudanças. Uma restrição futura exigirá confirmação da Rex e uma relação verificável com o material em estoque; não será inferida do QR ou do papel.

Esta premissa não autoriza substituir produto, acabamento ou empresa. Ela remove somente a exigência adicional, não validada, de retirar de uma OP de origem específica.

### D3 - Operação 499 e componentes abrangidos

A operação 499 foi encontrada com a descrição prevista no ERP de homologação. A OP `272246` permitiu ler estágio `200`, `seqRot=5` e um componente com `seqCmp=1`. A busca também retornou outras combinações de estágio e sequência, portanto não podem ser constantes.

Homologar a abrangência para as OPs da Rex e a seleção dos componentes das origens permitidas contra o relatório, inclusive com vários componentes e acabamentos. A elegibilidade cadastral do componente usado no teste ainda não foi conferida no WMS.

Se a operação 499 tiver várias ocorrências distintas, manter o bloqueio de ambiguidade já entregue no primeiro incremento. Não escolher a primeira ocorrência nem somar demandas sem respaldo contratual. Esse tratamento permite seguir com as OPs de operação inequívoca; uma seleção diferente só será necessária se um caso real exigir e a Rex confirmar a regra.

### D4 - Criação padrão e dispensa de embalagem aprovadas

O usuário confirmou que esta entrega acrescenta uma forma de criar tarefas, não um fluxo novo de execução. Manter as regras e opções existentes para permissões, equipe, responsável e compatibilidade entre demandas agrupadas. Não impor por conta própria que o responsável seja o operador atual nem criar outra política de acesso.

O usuário também aprovou iniciar a tarefa de reclassificação sem vínculo obrigatório com o cadastro de embalagem de expedição. Essa dispensa é específica desta rotina. As tarefas normais de pré-faturas mantêm a exigência atual.

Reutilizar o início automático, as coletas, as pausas e a finalização padrão. As adaptações devem se limitar ao reconhecimento da demanda de reclassificação, à preservação do vínculo por OP e à dispensa aprovada de embalagem. Não criar um executor paralelo.

### D5 - Contrato e massa de homologação

O usuário confirmou o ambiente e autorizou consultar outras OPs de exemplo. O [levantamento AOP](eng-2777-contrato-aop-homologacao.md) registra WSDL, tipos, parâmetros e respostas reais das três portas para a OP `272246`. O bloqueio de ambiente e a necessidade de outra OP existente estão resolvidos. A investigação fez somente leituras, sem apontamento, baixa ou qualquer outra escrita no ERP.

O encadeamento comprovado é `buscar` para obter `codEtg` e `seqRot`, `ler` para obter os componentes e `seqCmp`, e `lerComponente` para detalhar cada ocorrência. As amostras incluem mensagens de sucesso, coleção ausente e coleção com um componente. A origem cadastral precisa vir do cadastro WMS; acabamento e derivação não podem ser copiados do cabeçalho da OP sem identificar o material correto.

Para concluir a homologação funcional, faltam casos com vários componentes e acabamentos, retirada parcial, origem cadastral elegível no WMS e respostas adicionais de falha. O relatório da Rex deve permitir conferir os resultados esperados. Os nomes e tipos de campos já observados constam do levantamento; sua semântica não será presumida quando ainda depender de uma decisão do negócio.

### D6 - Necessidade por `qtdPrv` e autorização da empresa pelo ERP

O usuário autorizou assumir `qtdPrv` como necessidade total de cada ocorrência de componente. O backend subtrai as coletas efetivas do WMS e trata reservas abertas separadamente; não subtrai `qtdUti`. Comparar quantidade e unidade com o relatório da Rex em QA, mas essa comparação não bloqueia a implementação sob essa premissa.

O WMS aplica as permissões atuais para o operador usar a rotina e o contexto da Expedição, sem manter uma lista de empresas permitidas por usuário ou equipe. A consulta AOP usa as credenciais globais da integração. O ERP é responsável por aceitar ou recusar `codEmp` para essas credenciais. Se recusar, a consulta falha e a OP não entra na lista. Essa decisão não transmite a identidade/permissão individual do operador ao ERP.

## Critérios de aceite

D1, D2, D4 e D6 registram decisões aprovadas. A comparação de `qtdPrv` e unidade com o relatório Rex é QA da premissa, não bloqueio de implementação. Não selecionar automaticamente uma operação 499 ambígua sem contrato que justifique essa escolha.

| Cenário | Resultado esperado |
| --- | --- |
| Ler várias OPs em sequência | Cada consulta adiciona seus itens e retorna à câmera; sair da câmera permite conferir toda a lista. |
| QR inválido, câmera negada ou consulta indisponível | Mensagem útil, sem inclusão incompleta da OP e sem apagar a lista já montada. |
| Fechar a câmera durante uma consulta | Ignorar o retorno tardio dessa sessão, sem adicionar uma OP após o fechamento ou alterar uma nova sessão de leitura. |
| Reler uma OP já adicionada | Não duplicar itens ou quantidades na lista. |
| Mesmo número de OP em empresas ou origens diferentes | Identificar cada OP pela combinação completa. O WMS aplica as permissões existentes para a rotina; o ERP aceita ou recusa `codEmp` para as credenciais de integração, e uma recusa não adiciona a OP à lista. |
| Componentes de origens permitidas e não permitidas | Aplicar o filtro ao cadastro dos componentes, sem filtrar pela origem da OP. |
| Operação 499 com estágio e sequência diferentes entre OPs | Usar os valores retornados para cada OP, sem constantes para estágio ou sequência. |
| OP sem dados, sem operação válida ou com produto não localizado | Informar por que a OP não pode ser incluída; não substituir produto ou derivação. |
| Mesmo produto em várias OPs ou ocorrências do componente | Preservar linhas, quantidades e coletas vinculadas à demanda correta. |
| Cabeçalho da OP com código ou derivação diferente do componente | Resolver o cadastro pelo material e derivação do componente, sem trocar pelo produto ou acabamento do cabeçalho. |
| Confirmar lista com várias OPs | Criar exatamente uma tarefa e iniciar sua execução automaticamente. |
| Endereços e estoques alternativos | Preservar a seleção, as restrições e a ordenação padrão, sem filtro ou sugestão adicional pela OP de origem do estoque, conforme a premissa D2. |
| Mesmo material elegível originado por OPs de estoque distintas | Não excluir um estoque somente por sua OP de origem; manter as regras padrão de produto, empresa e derivação/acabamento. |
| Retirada total | Registrar a quantidade efetiva de cada item e OP, sem saldo fictício. |
| Retirada parcial, inclusive item sem coleta | Preservar necessário e realizado; não marcar como coletada a quantidade que ficou no estoque. |
| Nova leitura após retirar 40 de uma demanda de 100 | Mostrar necessário 100, já separado 40 e quantidade da nova tarefa 60; criar apenas 60, sem desconto duplo. |
| Demanda sem saldo restante para criação | Informar a ausência de saldo e não gerar uma tarefa vazia ou repetir a quantidade já retirada. |
| Quantidade comprometida em outra tarefa aberta | Aplicar a disponibilidade do fluxo existente e explicar na conferência o que já está comprometido, sem tratar reserva como coleta realizada. |
| Duas confirmações concorrentes ou resposta perdida | Não duplicar tarefa nem alocar duas vezes a mesma quantidade disponível. |
| Quantidade alterada desde a conferência ou estoque insuficiente | Informar a divergência e manter quantidades efetivas corretas, sem completar uma coleta automaticamente. |
| Operador sem acesso ao contexto da Expedição | Rejeitar no backend antes da consulta ERP, mesmo com QR válido ou chamada direta à API. |
| ERP recusa a empresa da OP para as credenciais AOP | Mostrar erro seguro e não adicionar a OP nem seus componentes à lista. Não manter autorização WMS própria por `codEmp`. |
| Criar tarefa de reclassificação sem embalagem | Iniciar e abrir a execução padrão sem exigir embalagem; manter a exigência nas tarefas normais de pré-faturas. |
| Executar uma tarefa criada por QR de OP | Usar as coletas, pausas e finalização do fluxo padrão, sem outro executor e sem perder o vínculo por item e OP. |
| Executar o fluxo completo | Não chamar `ApontarOP`, baixa, apontamento de produção, faturamento ou qualquer outra escrita no ERP. |

## Verificação e entrega

- Backend: testar interpretação e validação de identificadores, autorização WMS ao contexto antes da consulta, recusa de empresa pelo ERP, contrato SOAP com respostas simuladas, seleção de operação/componentes, resolução de produto, `qtdPrv` como necessidade total, saldo/coletas/reservas, criação atômica e concorrência. Usar as amostras verificadas como referência para mensagens nulas ou `OK`, ausência de `statusProcesso`, coleções vazias ou com um registro e diferenças entre os dados do cabeçalho e do componente. Simular o cliente SOAP e verificar que somente as portas de consulta previstas são chamadas.
- Coleta e finalização: cobrir o mesmo produto em várias OPs, vários endereços para uma demanda, parcial e nenhuma coleta, sem inferir realizado a partir do status. Executar regressões dos fluxos atuais de pré-faturas e requisições.
- Mobile: testar leitura repetida, callbacks concorrentes, resposta após fechar a câmera, retorno à leitura, erros sem perda da lista, conferência por OP, confirmação repetida e abertura da tarefa na execução existente. Conferir na tela o necessário, o já separado e o saldo que entrará na tarefa. Na execução padrão, comprovar que ler um produto presente em duas OPs não atribui a coleta automaticamente à primeira linha.
- QA com a Rex: comparar operação, componentes, origens, acabamentos, unidades e quantidades com o relatório aprovado; executar retirada total e parcial e conferir o WMS por item e OP. Confirmar a ausência de escrita no ERP.
- Deploy: publicar backend compatível antes do mobile e validar a rotina em homologação. Incluir migrations apenas se o modelo aprovado exigir. Validar o cálculo do saldo e a preservação da seleção padrão do estoque. Registrar D2 como premissa, sem exigir uma decisão adicional de vínculo com OP manuscrita para concluir esta entrega.

Testes existentes que ajudam a preparar a regressão:

- `rex-back/tests/Feature/PickingOrder/PickingOrderMultiPreInvoiceExecutionTest.php` e `rex-back/tests/Feature/PickingOrder/ExpeditionPickingOrderConcurrencyTest.php` cobrem demandas de várias saídas e concorrência no fluxo de pré-faturas.
- `Rex-Estoque/src/pages/Saidas/pickingOrderStockIO.helpers.test.ts` e `Rex-Estoque/src/pages/Saidas/pickingOrderExecution.helpers.test.ts` cobrem associação de produtos às saídas e decisões de encerramento.

A consulta AOP, a interpretação do QR, a resolução cadastral WMS, o registro persistente e o saldo sobre necessidade WMS conhecida têm implementação interna. Início, coleta e ambas as finalizações padrão reconhecem a reclassificação sem embalagem obrigatória e preservam quantidades efetivas. Passos e respostas distinguem a parcela da tarefa do saldo global. O controle de leitura contínua tem testes no mobile, mas ainda não está ligado à câmera e à API. A tela padrão de execução já reconhece a demanda e a dispensa de embalagem em testes simulados, sem novo executor. As decisões agora assumidas para implementar são `qtdPrv` como necessidade total, sem subtrair `qtdUti`, e autorização de empresa pelo ERP usando as credenciais do AOP; o WMS ainda precisa aplicar as permissões normais de acesso à rotina antes da chamada. Faltam endpoints, criação atômica/idempotente com início automático, tela de leitura e conferência, integração, QA total/parcial e releitura com a Rex, além de deploy autorizado.

## Fora de escopo

- Apontamento de produção, baixa de componentes e qualquer escrita no ERP.
- Sincronização periódica ou importação em massa de OPs.
- Registro do produto já reclassificado ou entrada automática após o processo de acabamento.
- Novo algoritmo de caminho, novos relatórios e alterações no frontend web.
- Fluxo próprio de execução de tarefas ou novas regras de permissão, equipe e responsável que substituam as existentes.
- Novo filtro, prioridade ou sugestão de estoque pela OP de origem do material; interpretação automática de anotação manuscrita.
- Operação offline e persistência do rascunho entre reinícios do app.
