SGF/docs/STOCK_READ_SCOPE.md

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. 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. 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.