# Inventário — organização do desenvolvimento backend e web

**Data:** 2026-11-06.
**Situação:** organização aprovada e preparada localmente; implementação das funcionalidades ainda não iniciada.
**Escopo:** issues principais ENG-3113 a ENG-3119 nos repositórios rex-back e rex-front.

## 1. Decisão e limites

Usar uma branch temporária de integração **feature/inventario** em cada repositório e uma branch **feature/eng-<número>** para cada issue. Os PRs das issues apontam para a integração, não diretamente para main/dev.

A integração concentra dependências já revisadas; não é a branch de trabalho diário. Criar ou atualizar a branch de cada issue somente quando seu desenvolvimento começar, após integrar seus pré-requisitos. Não antecipar todas as branches de execução a partir de uma base sem as dependências.

Alternativas consideradas: uma branch única dificultaria revisão/reversão por issue; PRs empilhados diretamente uns sobre os outros exigiriam manutenção de bases em cascata. A integração temporária permite PRs menores e uma base compartilhada.

Esta organização não substitui requisitos, desenhos ou planos aprovados. Sua finalidade é definir bases, sequência e divisão de execução. Documentos de planejamento não comprovam funcionalidades implementadas.

**Não inclui:** alterações no repositório Rex-Estoque nem execução das subissues mobile ENG-3268, ENG-3269 e ENG-3270, atribuídas a outra frente de desenvolvimento.

## 2. Bases e consolidação

| Repositório | Base efetivamente preparada | Integração |
| --- | --- | --- |
| rex-back | origin/main em a6b49a5f + planejamentos existentes | feature/inventario |
| rex-front | origin/main em 3d822115 + merge explícito do protótipo aprovado eng-2966 em 67305ddb | feature/inventario |

### Backend

Consolidar os planejamentos de feature/eng-3119 e feature/eng-3115 por merges que preservam sua história. O primeiro já contém os documentos das ENG-3113/3114/3116/3117/3118; o segundo acrescenta a consulta gerencial.

Os diffs desses ramos contra main foram conferidos: somente docs/plans/. Nenhum código funcional do inventário foi acrescentado por essa consolidação.

A integração agora contém os desenhos das sete issues e os seis planos detalhados existentes. A ENG-3117 possui desenho aprovado, mas ainda não possui implementation-plan; ver pendências.

### Frontend

O protótipo eng-2966 não estava na main. A integração preserva esse protótipo e incorpora deliberadamente a main atual por merge pré-validado sem conflitos, mantendo as correções já publicadas na aplicação. Isso não é uma troca inadvertida da base aprovada nem uma implementação da persistência.

O merge de preparação é 0bbce717. Não foi incorporada a dev inteira. A interface herdada ainda é o protótipo: fixture, storage e transições simuladas devem sair do runtime real nos recortes de cada plano, não ser tratados como entrega concluída.

O dashboard visual da ENG-3084, commit d1b2acaa, não está no snapshot eng-2966. Ao executar a ENG-3119, portar seletivamente sua interface dentro da branch da issue, adaptando-a aos contratos reais antes de integrar. Não mesclar a dev inteira nem levar o dashboard mockado de volta ao runtime persistido.

## 3. Worktrees locais

Caminhos relativos à pasta de trabalho Rex/:

| Diretório | Branch | Uso |
| --- | --- | --- |
| rex-back-inventario/ | feature/inventario | Integração e documentação comuns do backend |
| rex-front-inventario/ | feature/inventario | Integração da gestão web |
| rex-back-eng-3113/ | feature/eng-3113 | Desenvolvimento inicial do backend |
| rex-front-eng-3113/ | feature/eng-3113 | Desenvolvimento inicial da gestão web |

As branches feature/eng-3113 existentes foram reaproveitadas e atualizadas por fast-forward para a integração; não foram apagadas ou recriadas.

Os diretórios principais rex-back/ e rex-front/ continuam em main. As worktrees de planejamento das ENG-3114 a ENG-3119 e a worktree frontend da ENG-3110 foram preservadas.

As branches de integração foram deixadas sem upstream para não herdar origin/main como destino de pull/push. Nenhuma branch foi publicada e nenhum PR remoto foi aberto nesta preparação. Conferir o remoto de destino antes de publicar: o frontend possui origin e Soelx-App.

## 4. Sequência e marcos

Caminho principal:

    ENG-3113 → ENG-3114 → ENG-3116 → ENG-3117 → ENG-3118 → ENG-3119

A ENG-3115 pode começar após a base persistida da ENG-3113. Seu aceite da fotografia depende da ENG-3114, e o aceite de comparação/divergências depende de resultados reais das entregas de contagem/conferência. Não finalizar esse aceite com mocks ou adaptadores que sempre retornem vazio.

| Issue | Backend e web desta frente | Pré-requisitos / observações |
| --- | --- | --- |
| ENG-3113 | Cadastro/rascunho, contexto, autorização, catálogo, abrangência, listagem/detalhe básicos e cadastro web de três etapas | Primeiro desenvolvimento |
| ENG-3114 | Início, fotografia, bloqueio/auditoria WMS e interface de início | ENG-3113; não exigir distribuição para iniciar |
| ENG-3115 | Consultas, filtros, resultados/lançamentos/histórico gerenciais | ENG-3113; marcos integrados posteriores |
| ENG-3116 | Rodadas, participantes, tarefas, distribuição web e APIs operacionais de ingresso/assunção | ENG-3114 |
| ENG-3117 | Parametrização web, congelamento, interpretação/validação autoritativas, APIs de contagem/correção e auditoria | Backend da ENG-3116; detalhar plano antes da execução |
| ENG-3118 | Resultados, recontagens, encerramento de rodadas, decisões, consolidação, aprovação/reprovação web e desbloqueio | ENG-3117 |
| ENG-3119 | Agregações, API de resumos e dashboard web real | Resultados/aprovação da ENG-3118; recuperar interface ENG-3084 seletivamente |

A ordem representa contratos necessários, não obrigação de esperar a issue inteira ficar Done para compartilhar uma API estável. Backend/web podem avançar por marcos; a conclusão funcional da issue-pai deve refletir também o aceite mobile correspondente.

## 5. Separação do mobile

| Issue-pai | Subissue de outra frente | Parcela que não deve ser executada aqui |
| --- | --- | --- |
| ENG-3116 | ENG-3268 | Navegação nativa, listas, ingresso e assunção no app |
| ENG-3117 | ENG-3269 | Scanner, formulário de contagem, zero, correções e recuperação nativa |
| ENG-3118 | ENG-3270 | Recontagens elegíveis e tratamento de encerramento no app |

No plano da ENG-3116, as tarefas 11 e 12 e o recorte nativo da 13 pertencem à ENG-3268. No plano da ENG-3118, a tarefa 15 e o recorte nativo da integração 16 pertencem à ENG-3270. O desenho da ENG-3117 orienta a ENG-3269 quanto à execução nativa.

As **APIs usadas pelo mobile continuam no escopo do backend das issues principais**: não remover rotas operacionais, validação, cegueira, autorização, idempotência, auditoria ou testes backend por não desenvolver o cliente nativo.

Antes do handoff, documentar contratos efetivos, formatos, códigos de erro, versões e comandos idempotentes. Não enviar saldos/resultados de outras rodadas nos Resources operacionais. A disponibilidade de contratos pode destravar o outro desenvolvedor antes do encerramento da issue-pai; não criar dependência circular da subissue pela própria issue-pai.

Mocks de UI, testes por cliente HTTP e backend aprovado não equivalem a homologação do app. Registrar separadamente o aceite de cada frente.

## 6. Ponto de partida: ENG-3113

Trabalhar nas worktrees de execução, não na integração:

~~~bash
cd rex-back-eng-3113
git branch --show-current
git status --short
~~~

~~~bash
cd rex-front-eng-3113
git branch --show-current
git status --short
~~~

Consultar primeiro o desenho e o plano da ENG-3113 listados na seção 10. Sequência do plano:

1. Reconciliar o contrato efetivo e o prefixo das APIs, sem duplicar rotas/contexto.
2. Executar tarefas 1–5: persistência/contexto, autorização, catálogo, abrangência e comandos/concorrência no backend.
3. Executar tarefas 6–9: serviço/helpers sem simulação, seleção real, cadastro assíncrono e listagem/detalhe web.
4. Executar tarefas 10–11: E2E do recorte, integração entre dois usuários, regressão, revisão e evidências.

Não iniciar inventário, bloquear estoque, distribuir participantes ou implementar contagens na ENG-3113. O recorte entrega rascunho compartilhado em Dados → Abrangência → Revisão, sem fixture/storage de inventário no runtime e sem ERP.

## 7. Preparação de ambiente e segurança

### Backend

O composer.json exige **PHP ^8.4**; essa exigência prevalece sobre a referência antiga a 8.2 em AGENTS.md. O PHP padrão inspecionado é 8.2.33 e a imagem local rex-app:latest inspecionada também é 8.2.34. Não presumir a versão pelo nome/tag da imagem.

A worktree de execução ainda não possui vendor/ nem .env. Preparar runtime compatível e instalar as dependências do lockfile de forma independente; não criar symlink para o vendor de outra worktree, pois o autoload pode carregar o código da árvore errada. Não atualizar pacotes nesta organização.

Não copiar automaticamente o .env da aplicação principal: configurar explicitamente ambiente autorizado de desenvolvimento/testes, sem versionar credenciais ou apontar testes para o banco oficial.

Antes de qualquer suíte que modifique schema, seguir docs/testing-database.md e executar, no runtime/ambiente correto:

~~~bash
php artisan --env=testing test:database-safety
~~~

Somente depois do preflight, rodar as suítes previstas no plano. Não executar migrate:fresh manualmente, não usar a instância oficial e não rodar resets concorrentes no mesmo schema. Portas, bancos, URLs e demais valores de instância devem vir da configuração do ambiente; não gravar uma nova configuração de instância em código.

### Frontend

As dependências foram instaladas com npm ci --no-audit --no-fund em rex-front-eng-3113, sem alterar lockfile e sem copiar .env da árvore principal.

O CI existente usa Node 20. A verificação local usou Node 22.23.1 e recebeu aviso de engine de react-zxing, que declara suporte a Node 18/20; preferir Node 20 para o desenvolvimento e confirmar os gates nesse runtime antes da entrega.

Não adicionar fallback de API com fixture ou storage local para contornar ausência do backend. Não iniciar servidor contra a instância oficial para testar persistência.

## 8. PRs, integração e próximas branches

Para cada issue, separar alterações por repositório e manter o mesmo identificador nos nomes/commits. Pode haver um PR backend e outro frontend para a mesma issue; registrar referências cruzadas e mudanças de contrato.

Fluxo:

1. Conferir que os pré-requisitos foram integrados em feature/inventario.
2. Conferir branch, status e worktree antes de qualquer atualização.
3. Preparar a branch da issue a partir da integração atualizada.
4. Implementar, testar e revisar somente o recorte da issue.
5. Publicar quando autorizado e abrir PR com **base feature/inventario**.
6. Integrar após revisão/gates e atualizar o próximo desenvolvimento.

As branches backend das próximas issues já existem em worktrees de planejamento. Não recriá-las com -b nem trocar a branch em uso por outra sessão. Se continuarem limpas e apenas com a história consolidada dos planos, atualizá-las por fast-forward quando chegar sua vez. Por exemplo, **somente após integrar a implementação da ENG-3113**:

~~~bash
git -C rex-back-eng-3114 status --short
git -C rex-back-eng-3114 merge --ff-only feature/inventario
~~~

A contraparte frontend ainda inexistente pode ser criada nesse momento:

~~~bash
git -C rex-front worktree add -b feature/eng-3114 ../rex-front-eng-3114 feature/inventario
~~~

Se o fast-forward falhar ou houver trabalho novo de outra sessão, parar e revisar a divergência. Não resetar, forçar checkout ou reescrever commits para encaixar a branch. Em desenvolvimento paralelo já divergente, incorporar a integração por merge revisado e repetir os testes; não aplicar automaticamente a receita de início.

Não desenvolver tudo diretamente na integração nem abrir branches futuras hoje como se suas dependências já estivessem implementadas. Não misturar trabalho frontend da ENG-3110 ou alterações de outras sessões.

Antes do PR final da integração para a branch oficial, reconciliar novamente sua base com a branch de destino e executar validação integrada. A main existente aciona deploy — no backend, inclusive migrations — por isso nenhum push/merge para ela faz parte desta preparação.

## 9. Validação da preparação e pendências

### Executado em 2026-11-06

- Fetch dos remotos pertinentes e inspeção das bases/worktrees.
- Prévia de merge dos planejamentos e do frontend sem conflito; merges efetivos concluídos sem conflito.
- Conferência de que a consolidação backend altera somente documentação.
- Pint 1.19.0, em modo test/dirty, nos commits de preparação backend: PASS, **0 arquivos PHP**, sem carregar/testar a aplicação.
- Frontend na base de integração 0bbce717: **npm test — 448 testes aprovados, zero falhas**.
- Frontend na mesma base: **npm run build — aprovado**, com aviso de chunk maior que 500 kB.
- Estes testes incluem o código herdado/protótipo e não certificam persistência/aceite das funcionalidades ainda não implementadas.

### Não executado / pendente

- Preparar PHP 8.4 e o ambiente isolado de backend, instalar suas dependências e configurar o ambiente autorizado.
- Nenhuma chamada ao banco, migration, teste funcional backend, chamada ERP, servidor da aplicação ou homologação E2E integrada foi executada.
- Confirmar os gates frontend em Node 20; o aviso de engine não foi “corrigido” atualizando dependências.
- Elaborar o plano detalhado da ENG-3117 para backend/web antes de iniciar essa issue; o desenho já está preservado.
- Integração com dispositivo/mobile permanece com a outra frente.
- Publicação de branches, PRs remotos e deploy ficam para autorização posterior; nenhum status do Linear foi alterado para indicar implementação iniciada.

## 10. Índice dos planos comuns

Todos os links abaixo são relativos a este diretório docs/plans/ do repositório rex-back.

| Issue | Desenho | Plano de implementação |
| --- | --- | --- |
| ENG-3113 | [Inventário manual](2026-11-05-eng-3113-inventario-manual-design.md) | [Plano](2026-11-05-eng-3113-inventario-manual-implementation-plan.md) |
| ENG-3114 | [Início e bloqueio](2026-11-05-eng-3114-inicio-inventario-bloqueio-wms-design.md) | [Plano](2026-11-05-eng-3114-inicio-inventario-bloqueio-wms-implementation-plan.md) |
| ENG-3115 | [Consulta](2026-11-05-eng-3115-consulta-inventarios-design.md) | [Plano](2026-11-05-eng-3115-consulta-inventarios-implementation-plan.md) |
| ENG-3116 | [Distribuição e tarefas](2026-11-06-eng-3116-distribuicao-tarefas-contagem-design.md) | [Plano](2026-11-06-eng-3116-distribuicao-tarefas-contagem-implementation-plan.md) |
| ENG-3117 | [Modalidades e contagens](2026-11-06-eng-3117-modalidades-registro-contagens-design.md) | Pendente de detalhamento; preservar desenho aprovado |
| ENG-3118 | [Conferência e encerramento](2026-11-06-eng-3118-conferencia-encerramento-local-design.md) | [Plano](2026-11-06-eng-3118-conferencia-encerramento-local-implementation-plan.md) |
| ENG-3119 | [Dashboard](2026-11-06-eng-3119-dashboard-inventario-dados-reais-design.md) | [Plano](2026-11-06-eng-3119-dashboard-inventario-dados-reais-implementation-plan.md) |

O frontend tem um guia de entrada em docs/inventario-development.md. Os documentos históricos de mock no frontend são referência visual, não substitutos das decisões aprovadas nestes planos.
