# SGF-STOCK-READ-SIM-v1 — primeiro incremento preparado

Actualização de implementação, 02/11/2026: [consulta funcional comum e adaptador SGF entregues parcialmente em ensaio sintético](STOCK_READ_DELIVERY.md). Fonte/rotas de Compras, duas composições HTTP e demonstração persistente própria continuam pendentes. O âmbito abaixo conserva o critério da entrega completa; não se declara todo executado.

02/11/2026. Estado: **âmbito técnico preparado, implementação não iniciada nesta entrega**. Parte da [preparação do fluxo integrado](SGF_MODULE_FLOW_PREPARATION.md). Não activar o menu operacional até existir fonte e prova; o estado informativo actual permanece verdadeiro.

## Resultado pretendido

Permitir que uma identidade sintética autorizada consulte artigos, armazéns, existências e movimentos no SGF a partir de uma capacidade comum reutilizada de Compras. Não copiar o motor de stock nem criar um segundo saldo. A composição autónoma conserva os seus percursos e dados. A consulta não depende da pasta de desenvolvimento Compras em runtime: essa pasta é fonte de extracção, não fornecedor remoto de dados.

A primeira implementação deverá separar contexto/autorização, repositório de leitura e apresentação. Reutilizar o schema/modelo de movimentos e quantidades existentes em ensaio isolado; não executar `StockController` da outra aplicação sobre a base SGF nem equiparar tenant Compras com tenant/empresa SGF. A extracção ficará num pacote comum com adaptadores locais; a fronteira final só pode ser fechada após inventariar modelos/scopes e dependências.

## Incluído e excluído

Inclui pesquisa paginada de artigos/armazéns, existências por artigo/armazém e histórico de movimentos; filtros no servidor, página/data de corte, origem e versão do livro. Valores nulos ou fonte indisponível são apresentados como tal, não como zero. A falta de autorização não devolve nomes, quantidades, existência de outra empresa ou custos.

Sem criação de artigos/armazéns pela interface, recepções, saídas, transferências, contagens, ajustes, devoluções ou estornos neste primeiro incremento. Sem replay de movimentos históricos, saldos iniciais reais, valorização inventada, ligação automática à oficina, emissão, pagamentos ou lançamentos. Lotes/reservas só aparecem quando a fonte já consegue demonstrar a sua semântica e autorização; não calcular disponível como físico menos zero por ausência de fonte de reservas. Funções fora do recorte permanecem explicitamente indisponíveis.

## Contexto e direitos propostos — não concedidos

Reutilizar sessão/contexto SGF, direitos administrativos existentes para a sua própria função e verificações no servidor. `company.view` e ver o menu de Stock não autorizam consultar armazéns. Antes de implementar/conceder, fechar a proposta:

| Direito candidato | Âmbito proposto | O que não concede |
| --- | --- | --- |
| `stock.view` | Empresa e unidades/armazéns explicitamente elegíveis | Cadastro, movimento, custo ou acesso implícito a todos os armazéns |
| Direito específico de custos, nome a delimitar | Separado, só se uma etapa futura incluir valorização | Não faz parte da consulta inicial nem é herdado de `stock.view` |

Se o mecanismo de grants SGF não representar armazéns, a primeira etapa limita os armazéns por relação explícita com empresa/unidade e nega qualquer correspondência ambígua; não inventar concessões de armazém em campos sem suporte. A decisão precisa de estar no adaptador e em testes, não em comparação de nomes/IDs. Contas QA próprias recebem apenas direitos sintéticos do ensaio; nenhuma concessão pública/real ou em demos existentes.

## Consulta e evidência

Página 25 por omissão, opção 100 e limite 100, ordenação por identificador estável com desempate quando necessário. Artigos/armazéns usam selecção pesquisável e paginada. Totais respeitam todos os filtros e o isolamento. Não retornar todo o livro para paginar em PHP/browser.

Para existências, agregar no SQL e seleccionar apenas os pares da página; totais de pares/filtros não podem ser calculados a partir de uma página de movimentos. Para o histórico, página ordenada, referência à origem elegível e versão/corte consultados. Quantidades em `quantity_milli` são inteiros exactos; unidade não é inferida de moeda ou descrição. A API devolve metadados mínimos; fotografias/documentos completos têm consulta protegida própria quando necessária.

Não adicionar cache entre pedidos que esconda revogações ou alterações. Paginação normal sobre livro que muda não garante percurso integral sem repetição/omissão: escolher corte/revisão e provar essa semântica. Uma página com novo contexto não pode reutilizar a resposta do contexto anterior. Não adquirir locks de escritor para simples leitura; usar coerência de snapshot/corte conforme o repositório.

## Cenário sintético e provas a executar na implementação

Preparar base e identidades próprias, fisicamente isoladas da demonstração e dos seis registos protegidos, sem `prepare/reset` em clusters existentes. Dois âmbitos empresariais, duas unidades, armazéns autorizados e reservados; artigo com movimentos e outro sem movimentos elegíveis. Preparação controlada da fixture não é endpoint operacional de entrada.

| Caso | Evidência de conclusão exigida |
| --- | --- |
| Fonte inexistente/incompatível | Estado explícito de indisponibilidade, sem saldo zero fabricado ou leitura cruzada |
| Consulta exacta | Soma de entradas/saídas e versão coincidem com o livro sintético; sem float |
| Filtros/páginas | 1 000/5 000/10 000 registos, páginas 25/100; totais, ordem, última página e cobertura exactos num corte fixo |
| Isolamento | Outra empresa/unidade/armazém recusados; sem dependências ou nomes expostos |
| Revogação/contexto | Pedido seguinte revalida o acesso; resposta antiga ignorada pelo cliente |
| Livro em alteração | Snapshot/corte demonstrado; nenhuma mistura silenciosa de saldo e revisão incompatíveis |
| Carga | Tempo, número de consultas, memória incremental/pico e tamanho da resposta; mesmos dados/condições; sem consulta por linha |
| Índices | Ganho separado de batching/projecção; só ensaio sintético, plano/catálogo preservados |
| Falha/retoma | Falha de leitura não grava movimento; reentrada recupera consulta sem alterar o livro |
| Duas composições | Mesma fonte comum e resultados equivalentes no recorte, sem exigir vendas SGF no Compras autónomo |

Não executar esta matriz antes de existir o adaptador. As provas válidas da fila não comprovam desempenho de Stock. A revisão visual terá o seu guião quando houver interface funcional, sem repetir a via de navegador bloqueada. Capacidade de implantação exige servidor/recursos/carga e política próprios; não se declara a partir da fixture.

## Critério de entrega

Código de leitura comum/adaptadores, interface honesta, provas de equivalência/isolamento/retoma, medições comparáveis e limitações documentadas. Sem migração ou concessão de destino por consequência do ensaio. Se a fonte só estiver disponível numa composição, declarar parcial; não apresentar dois motores ou fixtures desconexas como integração concluída.