# ENG-2777 - Contrato AOP verificado em homologação

## Estado

O usuário confirmou a instância de homologação e autorizou consultar outras OPs de exemplo. A leitura completa de `buscar`, `ler` e `lerComponente` funcionou para a OP `272246`, empresa `1`, origem `10`. A operação retornada foi `499`, com descrição `ENCAMINHA PRODUTO AO PROCESSO`, estágio `200`, sequência da operação `5` e sequência do componente `1`.

A consulta AOP já tem implementação nos commits `f35c9117` e `d0edd533`, conforme o handoff registrado na issue e na spec. A investigação não determina a fórmula de saldo pendente nem comprova uma relação entre a OP lida no QR e a OP que originou o estoque. Nas decisões posteriores, o usuário aprovou criar apenas o saldo restante, exibir essa composição na conferência, dispensar embalagem nesta rotina e reutilizar a execução padrão. Também autorizou como premissa manter a seleção padrão do estoque, sem restrição ou sugestão nova pela OP de origem. As amostras não comprovam que todas as OPs da operação real terão os mesmos dados.

## Fontes e limites

- WSDL e XSD reais de `sapiens_Synccom_lmi_aop`, no endereço-base de homologação confirmado pelo usuário. O endereço pertence à configuração da instância e não está registrado neste documento.
- Respostas reais das três operações, desserializadas pelo `SoapClient` nativo do PHP a partir do WSDL. Não foi necessário interpretar manualmente o XML da resposta.
- `config/integration.php:15-24` do checkout da ENG-2777 define as chaves `SENIOR_URL`, `SENIOR_USER`, `SENIOR_USER_PASSWORD` e os timeouts. As credenciais vieram da configuração local da cópia principal e ficaram apenas em memória.
- O destino SOAP ficou restrito ao mesmo serviço no endereço-base confirmado. Não houve consulta a outra instância ou serviço ERP, SQL, acesso ao banco, inicialização do Laravel, apontamento ou baixa.
- As capturas usadas nas verificações locais ficam fora do repositório, em diretório privado, sem envelopes de autenticação. Os exemplos abaixo omitem credenciais e substituem códigos de produto por rótulos. OPs, estágios, sequências, quantidades e unidades permanecem como observados.

## Operações e autenticação

O WSDL publica estas assinaturas:

```text
buscar(user: string, password: string, encryption: int,
       parameters: aopbuscarIn) -> aopbuscarOut
ler(user: string, password: string, encryption: int,
    parameters: aoplerIn) -> aoplerOut
lerComponente(user: string, password: string, encryption: int,
              parameters: aoplerComponenteIn) -> aoplerComponenteOut
```

As chamadas reais usaram usuário e senha locais e `encryption=0`. As consultas válidas retornaram dados coerentes com os identificadores solicitados. Não registrar esses argumentos de autenticação em logs ou fixtures.

No teste, o cliente usou `SOAP_SINGLE_ELEMENT_ARRAYS`. A normalização observada de um único registro como lista depende dessa opção; não presumir que outro cliente ou a configuração atual do WMS terá o mesmo comportamento.

## Entradas publicadas no XSD

Os campos de entrada são opcionais/nillable no esquema. Isso não comprova que toda combinação de campos seja suficiente para localizar uma OP ou componente.

| Tipo | Campos |
| --- | --- |
| `aopbuscarIn` | `codEmp:int`, `codEtg:int`, `codOpr:string`, `codOri:string`, `numOrp:int`, `seqRot:int`, `flowInstanceID:string`, `flowName:string` |
| `aoplerIn` | `codEmp:int`, `codEtg:int`, `codOri:string`, `numOrp:int`, `seqRot:int`, `flowInstanceID:string`, `flowName:string` |
| `aoplerComponenteIn` | `codDer:string`, `codEmp:int`, `codEtg:int`, `codOri:string`, `codPro:string`, `numOrp:int`, `seqCmp:int`, `flowInstanceID:string`, `flowName:string` |

O esquema não oferece paginação ou limite de registros para `buscar`. A execução normal da rotina deve consultar uma OP por seus identificadores, com o filtro de operação, não repetir a busca de descoberta de exemplos.

## Fluxo comprovado para uma OP

### 1. Encontrar a operação e sua posição

Parâmetros reais de `buscar`:

```json
{"codEmp":1,"codOri":"10","numOrp":272246,"codOpr":"499"}
```

A resposta contém `lista`, de zero a muitos `aopbuscarOutlista`, além de `erroExecucao` e `msgErr`. A consulta acima retornou exatamente um registro:

```json
{
  "erroExecucao": null,
  "msgErr": null,
  "lista": [{
    "codEmp": 1,
    "codOri": "10",
    "numOrp": 272246,
    "codOpr": "499",
    "desOpr": "ENCAMINHA PRODUTO AO PROCESSO",
    "codEtg": "200",
    "seqRot": 5,
    "codPro": "PRODUTO_DA_OP",
    "codDer": "03",
    "desDer": "Zincado Branco"
  }]
}
```

`codEtg` é texto na linha de saída de `buscar`, mas inteiro na entrada de `ler`. Validar sua conversão. Preservar origens e derivações como texto, inclusive zeros à esquerda.

Uma busca de descoberta filtrada por `codEmp=1`, `codOri="10"` e `codOpr="499"`, sem `numOrp`, retornou 138 registros. Todos corresponderam à empresa, origem e operação solicitadas. As combinações de estágio/sequência foram `250/10`, `250/50`, `200/4` e `200/5`. Esses valores não são constantes da operação 499.

### 2. Ler a operação e enumerar seus componentes

Parâmetros reais de `ler`, com estágio e sequência recebidos de `buscar`:

```json
{"codEmp":1,"codOri":"10","numOrp":272246,"codEtg":200,"seqRot":5}
```

A resposta válida trouxe `erroExecucao=null`, `msgErr="OK"`, a identidade solicitada e:

```json
{
  "codOpr": "499",
  "codEtg": 200,
  "seqRot": 5,
  "codPro": "PRODUTO_DA_OP",
  "codDer": "02",
  "desDer": "Enegrecido de Tempera (Oxidado)",
  "uniMed": "CT",
  "qtdAbe": 4,
  "qtdApo": 0,
  "qtdRst": 4,
  "qtdTot": 4,
  "componentes": [{
    "codEmp": 1,
    "codCmp": "COMPONENTE_A",
    "codDer": "02",
    "seqCmp": 1,
    "qtdPrv": 4,
    "qtdUti": 0,
    "uniMed": "CT",
    "depositos": [{"codDep":"002","padrao":1,"qtdDis":4,"qtdTot":4}]
  }]
}
```

O código real de `COMPONENTE_A` é diferente de `PRODUTO_DA_OP`. A derivação `03` de `buscar` também difere da derivação `02` retornada por `ler` e pelo componente. Não substituir o material do componente pelo produto ou acabamento do cabeçalho da busca.

A leitura das OPs `234138`, estágio `250`, sequência `10`, e `272250`, estágio `250`, sequência `10`, retornou `msgErr="OK"`, mas não trouxe a coleção `componentes`. Assim, localizar a operação 499 não garante que ela tenha componentes disponíveis para esta rotina. Não fabricar um componente a partir do cabeçalho quando a coleção estiver ausente.

### 3. Consultar o componente pela sua sequência

A chamada comprovada de `lerComponente` usou a identidade da OP, o estágio e `seqCmp=1`. Para `codPro`, também foi testado o código do componente recebido em `ler.componentes[].codCmp`; para `codDer`, a derivação `02` da mesma linha:

```json
{
  "codEmp": 1,
  "codOri": "10",
  "numOrp": 272246,
  "codEtg": 200,
  "seqCmp": 1,
  "codPro": "COMPONENTE_A",
  "codDer": "02"
}
```

A resposta trouxe `erroExecucao=null`, `msgErr="OK"`, `codCmp="COMPONENTE_A"`, `codDer="02"`, `seqCmp=1`, `qtdPrv=4`, `qtdUti=0`, `uniMed="CT"` e o depósito `002` com `qtdDis=4` e `qtdTot=4`.

Duas comparações controladas delimitaram o que o retorno prova:

- Alterar somente a entrada `codPro` do código do produto da OP para o código do componente alterou apenas `codPro` na resposta. `codCmp`, derivação, descrição, quantidades e depósitos permaneceram iguais. Portanto, a resposta de `codPro` não valida que esse seja o código do componente. Usar `codCmp` da linha retornada para essa identidade.
- Alterar somente a entrada `codDer` de `02` para `03` não mudou o retorno. O componente continuou com derivação `02`. Não usar a derivação enviada como substituta da derivação efetivamente retornada.

As descrições não são uma chave de cadastro. A resolução do material no WMS precisa usar a identidade do componente, com empresa e derivação, sem tentar localizar pelo texto descritivo ou pelo código do produto da OP.

## Quantidades e origem cadastral

O XSD publica `qtdPrv` e `qtdUti` no componente. A operação também retorna `qtdAbe`, `qtdApo`, `qtdRst` e `qtdTot`. As quantidades são `xs:double`. Na amostra com componente, `qtdPrv=4`, `qtdUti=0` e `uniMed="CT"` foram iguais em `ler` e `lerComponente`.

Essas observações não provam que `qtdPrv - qtdUti` seja o saldo permitido para uma nova retirada no WMS nem que uma retirada local atualize `qtdUti`, pois o fluxo não escreve no ERP. Para a implementação, o usuário decidiu assumir `qtdPrv` como necessidade total e não subtrair `qtdUti`; coletas e reservas vêm do WMS. Não converter `CT` em peças sem a regra de unidade do cadastro. A comparação do mapeamento customizado com o relatório da Rex é QA da premissa aprovada.

`qtdDis` e `qtdTot` de `depositos` descrevem campos de disponibilidade do depósito no contrato; não substituem a demanda do componente nem a quantidade efetivamente coletada no WMS.

Os tipos `aoplerOutcomponentes` e `aoplerComponenteOut` não publicam um campo de origem cadastral do componente. `codOri` identifica a OP e não pode receber o filtro cadastral `10/20/30/40/50/51/52/54`. Resolver essa origem pelo cadastro WMS, ou por outra fonte que venha a ser autorizada. Nenhuma consulta ao cadastro WMS ocorreu nesta investigação, portanto a elegibilidade cadastral do exemplo ainda não foi confirmada.

Não existe campo explicitamente chamado acabamento nos tipos consultados. Usar o cadastro do componente e sua derivação para identificar a apresentação correta, sem copiar automaticamente o acabamento do produto da OP mostrado por `buscar`.

## Erros e coleções

As operações publicam `erroExecucao` e `msgErr`, não `statusProcesso`. Nas respostas válidas observadas:

- `buscar` retornou dados com ambos os campos de mensagem nulos.
- `ler` e `lerComponente` retornaram `erroExecucao=null` e `msgErr="OK"`.
- `componentes` esteve ausente em duas OPs válidas e presente como lista de um registro na OP `272246`, com a opção `SOAP_SINGLE_ELEMENT_ARRAYS` ativa.

Na primeira investigação, `ler` para o QR `274240`, sem estágio nem sequência, retornou HTTP 200 e `msgErr="não foi encontrada a OP informada"`. Isso não comprova que toda chamada com esse número de OP falharia com qualquer combinação de parâmetros. Também não comprova que os campos opcionais do XSD possam ser omitidos no fluxo real.

Não usar HTTP 200 como confirmação de sucesso. Validar a mensagem funcional e a identidade retornada. Uma operação sem componentes não permite formar uma demanda apenas por possuir cabeçalho válido.

`Domain/Shared/Integrations/Senior/SeniorImportBase.php:35-44` verifica `statusProcesso != 1`; esse campo não faz parte das saídas AOP verificadas. Não reutilizar esse verificador sem adaptar a validação específica do AOP. Não transformar qualquer `msgErr` não vazio em erro, pois `"OK"` é uma mensagem de sucesso observada.

## Chamadas realizadas

O levantamento inicial obteve WSDL/XSD e executou `buscar` e `ler` para o QR `274240`. Sua resposta grande de `buscar` não foi preservada nem interpretada de modo confiável; ela não é evidência de dados da OP.

A verificação seguinte usou o `SoapClient` nativo com o WSDL e fez somente estas chamadas SOAP:

| Operação | Filtro ou identidade | Resultado |
| --- | --- | --- |
| `buscar` | Empresa `1`, origem `10`, operação `499` | 138 registros, todos nos filtros solicitados; permitiu escolher outra OP. |
| `ler` | OP `234138`, estágio `250`, sequência `10` | `OK`, sem coleção de componentes. |
| `ler` | OP `272250`, estágio `250`, sequência `10` | `OK`, sem coleção de componentes. |
| `ler` | OP `272246`, estágio `200`, sequência `5` | `OK`, um componente com `seqCmp=1`. |
| `lerComponente` | OP `272246`, estágio `200`, componente `1`, código do produto da OP, derivação `02` | `OK`, identidade e quantidades do componente retornadas. |
| `buscar` | OP `272246`, empresa `1`, origem `10`, operação `499` | Exatamente um registro, confirmando o filtro por OP. |
| `lerComponente` | Mesma identidade, alterando apenas `codPro` para o código do componente | Apenas `codPro` mudou no retorno. |
| `lerComponente` | Mesma identidade anterior, alterando apenas a entrada `codDer` para `03` | Retorno permaneceu igual, com derivação real `02`. |

Asserções locais verificaram a identidade da OP, operação, estágio, sequências, código do componente, derivação e igualdade de quantidades entre as respostas. A resposta filtrada de `buscar` tinha 782 bytes; a resposta de `ler` com o componente tinha 1229 bytes. O tamanho da primeira resposta não bloqueia mais a interpretação do contrato.

Não houve busca adicional sem filtros, teste de carga, consulta a outro serviço, chamada a `genericConsult`, SQL, acesso ao banco, alteração de configuração ou implementação da aplicação.

## Efeito nas decisões da spec

- D3 tem evidência real da operação 499, de estágios e sequências diferentes e de um componente. Continua necessário validar a abrangência para as OPs da Rex, vários componentes e a seleção quando houver mais de uma ocorrência válida de 499.
- D5 tem WSDL, assinaturas e encadeamento das três leituras comprovados. Não está mais bloqueada por falta de ambiente ou de uma OP existente. Faltam casos de vários componentes, cadastro WMS elegível e respostas adicionais de falha para concluir a homologação funcional.
- D1 tem comportamento aprovado pelo usuário. Após retirar 40 de uma necessidade de 100, criar outra tarefa apenas com as 60 restantes e mostrar necessário, já separado e quantidade da nova tarefa. O usuário também autorizou a premissa técnica de usar `qtdPrv` como necessidade total; `qtdUti` não é subtraído, e as coletas/reservas são calculadas separadamente no WMS. Comparar com o relatório Rex em QA.
- D2 registra a premissa autorizada de manter a seleção padrão do estoque, sem filtro ou sugestão adicional pela OP de origem do material. A OP de reclassificação lida no QR não identifica automaticamente a OP que deu origem ao estoque. A investigação não comprova esse vínculo, mas ele não é requisito deste incremento ou das próximas etapas conforme a premissa adotada.
- D4 está aprovado pelo usuário. A rotina pertence à Expedição, dispensa embalagem de expedição para reclassificação e mantém as regras atuais de criação e a execução padrão, sem executor paralelo.

## Evidência adicional sobre quantidades em 21/10/2026

A documentação oficial Senior distingue previsão, utilização, transferência e reserva. As duas páginas abaixo foram consultadas sem acesso ao ERP ou às credenciais da instância.

1. [F900BAC, Baixa de Componentes do Estoque, versão 5.10.3](https://documentacao.senior.com.br/gestaoempresarialerp/5.10.3/menu_manufatura/f900bac.htm) apresenta um exemplo da tabela `E900CMO`. Antes da baixa, `QtdPrv=8,14`, `QtdRes=8,14`, `QtdUti=0` e `QtdCdr=0`. Depois da baixa, `QtdPrv` continua em `8,14`, `QtdRes=0,74`, `QtdUti=8,40` e `QtdCdr=1`. A página chama `QtdPrv` de "quantidade prevista do componente na OP". Também informa que, na opção "Apenas Transferência", "não será alimentado a quantidade utilizada na tabela de componentes da O.P. (campo E900CMO.QtdUti), apenas a nova coluna criada para este tratamento (E900Cmo.QtdTrf)". Isso não estabelece relação com uma coleta WMS.
2. [Identificador CHA-900CQCOP01, versão 5.10.4](https://documentacao.senior.com.br/gestaoempresarialerp/5.10.4/identificadores_regras/cha_900cqcop01.htm) define as variáveis da regra. `QtdPrv` é "Quantidade Prevista do Componente da OP"; `QtdUti` é "Quantidade que está se utilizando do Componente no atual movimento"; `QtdMvp` é "Quantidade já Movimentada do Componente (necessário quando houver movtos parciais). Usado apenas qdo for Baixa de Componentes". O contexto da variável importa; o nome isolado não prova se um retorno é total, saldo ou movimento atual.

Essas páginas não documentam a implementação de `sapiens_Synccom_lmi_aop`. O WSDL, o XSD e a amostra AOP `4/0` tampouco provam se o serviço copia `E900CMO.QtdPrv`, recalcula a previsão ou devolve um saldo. Esse continua sendo o limite da evidência técnica; não se deve apresentar a documentação padrão Senior como prova do mapeamento customizado.

**Premissa aprovada para implementar ENG-2777:** o usuário autorizou tratar `qtdPrv` como necessidade total do componente. O cálculo não subtrai `qtdUti`; coletas efetivas e reservas são apuradas separadamente no WMS. A premissa permite seguir com a implementação, embora o mapeamento do serviço customizado não tenha sido confirmado independentemente. Em QA, comparar `qtdPrv`, `uniMed` e o saldo resultante com o relatório da Rex para a mesma empresa, origem, OP, estágio, `seqRot` e `seqCmp`, inclusive após uma retirada parcial. Registrar divergências; essa comparação não bloqueia codificar a premissa aprovada.

A resolução WMS adicionada nesta continuação preserva essas quantidades originais, inclusive campo ausente ou nulo, sem transformá-las em zero. Ela verifica a igualdade da unidade do componente com `unit_measurements.acronym` e bloqueia divergências em vez de converter `CT` para peças.

A [DRM do projeto, atualizada em 20/10/2026](https://linear.app/soelx/document/28092026-eng-2507-drm-exp-rex-dash-separador-reprocessados-e-relatorio-3649327e3726), detalhada por Alex Oderdenge, relata comparação de código, acabamento e quantidade com o relatório em duas OPs. O documento mantém a regra de quantidade pendente sujeita à validação da Rex. Não fornece expressões de origem de `qtdPrv` e `qtdUti` nem um caso identificado de retirada parcial que estabeleça saldo bruto ou líquido. A consulta dessa fonte interna não resolve o mapeamento customizado.

O cálculo a partir do AOP pode ser implementado sob a premissa aprovada: `qtdPrv` é a necessidade total, sem descontar `qtdUti`; o WMS fornece as coletas efetivas e reservas. Os testes existentes de saldo e execução ainda usam necessidade WMS sintética, então QA integrado deve comparar quantidade, unidade e saldo com o relatório Rex. A autorização de `codEmp` também foi definida: o WMS verifica o contexto normal da Expedição e o ERP aceita ou recusa a consulta para as credenciais globais AOP; o leitor não envia a identidade individual do operador.
