commit15

docs/SGF_MODULE_FLOW_PREPARATION.md

@@ -0,0 +1,121 @@
+# Preparação dos módulos e do fluxo integrado SGF
+
+Continuação financeira SGF: [recibo histórico de Compras para o núcleo comum](SGF_PAYABLE_HISTORY_RECEIPT_DELIVERY.md), implementado somente em bases novas de ensaio, com 10 cenários/56 asserções e 17 verificações HTTP. A fotografia histórica não constitui fonte viva, cutover operacional ou Financeiro completo; mantém paginação/carga financeira e implantação pendentes.
+
+Continuação SGF mais recente: [encerramento individual de propostas Oficina → Stock](WORKSHOP_STOCK_PROPOSAL_CLOSURE.md), com retirada/recusa sem efeito físico e protecção contra confirmação concorrente. Não encerra as etapas financeiras/contabilísticas ainda em falta ou as pendências de implantação/visuais.
+
+Continuações locais sintéticas posteriores: [recepção nativa no livro comum](STOCK_RECEIPT_LINK_DELIVERY.md), [saída por origem de Oficina](WORKSHOP_STOCK_DELIVERY.md), [ligação a entrega existente](WORKSHOP_DELIVERY_LINK.md), [repartição e devolução verificadas](WORKSHOP_MATERIAL_CYCLE.md) e [devolução nativa com observação SGF](NATIVE_WAREHOUSE_RETURN_DELIVERY.md). Estes incrementos superam partes da preparação inicial abaixo; não declaram todos os módulos completos nem uma composição operacional instalada. A última entrega consolida 36/544 provas próprias, preservando revisão visual e implantação como pendências separadas.
+
+Primeira execução posterior: [leitor comum de Stock, API e interface SGF](STOCK_READ_DELIVERY.md), funcional exclusivamente com bindings sintéticos de teste. Entrega parcial: sem movimentos, sem actualização de demos ou segunda composição HTTP de Compras. As restantes etapas deste plano permanecem por implementar/ligar.
+
+02/11/2026 — `SGF-MODULE-FLOW-PREPARATION-v1`. Pedido: começar a preparar as capacidades em falta para ligar etapas sem duplicar efeitos, criar gargalos evitáveis ou perder evidência. **Entrega desta passagem: inventário técnico verificável, mapa de ligações, contrato de evidência proposto e primeiro incremento delimitado. Não é a implementação dos motores operacionais em falta.**
+
+Reutiliza o [plano de núcleo comum](PURCHASING_COMMON_CORE_PLAN.md), a [demonstração integrada](PRODUCT_DEMO.md), os percursos financeiros sintéticos existentes e a [consolidação de carga/concorrência/HTTP](MODULE_ASSOCIATION_LOAD_CONSOLIDATION.md). Não reabre aceitações nem apresenta menus como módulos operacionais completos.
+
+## 1. Inventário actual e decisão de construção
+
+| Área | Base a preservar/reutilizar | Preparação para completar |
+| --- | --- | --- |
+| Compras | Requisições básicas em 8039; processos, recepção e conferência existentes em Compras | Transferir por incrementos completos, com contexto e direitos explícitos; não activar candidatas por arrasto |
+| Stock | `StockWorkflow`, `ReceiptWorkflow`, `InventoryLots`, `InventoryCounts`, `InventoryDispositions`, `InventoryReversals`, `WarehouseReservations` em Compras | Leitura comum paginada primeiro; depois escritor único/adaptadores e ligação a consumidores SGF |
+| Oficinas | Ordem/autorização, apontamentos verificados, custo e conversão comercial existentes | Ligar consumo físico por origem e versão, sem transformar observações anteriores em movimentos |
+| Comercial | Cadastro, rascunhos, B1, cálculos e emissão/PDF de teste | Preservar revisão comercial e origens; completar ligações e validação fiscal própria antes de uso real |
+| Financeiro | Núcleos comuns de orçamento e obrigações; recebimentos, pagamentos/afectações e reversões sintéticos | Compor os percursos, delimitar reconciliação e fontes históricas; não criar um segundo saldo |
+| Contabilidade | Classificação, perfis fiscais e menus | Motor de lançamentos, períodos, razão, fecho e relatórios com fontes rastreáveis; implementação ainda em falta |
+
+**Actualização importante face ao menu antigo de Stock:** a inspecção actual encontrou código de lotes, contagens, devoluções/abates, reservas e estornos em Compras. A ausência dessas ligações no SGF não significa ausência na origem. Os hashes e caminhos estão no [inventário de preparação](proofs/module-flow-preparation-20261102.json). São evidência de existência de fonte, **não prova de execução, cobertura integral ou activação dessas capacidades**. A extracção deverá seguir essas dependências, não copiar apenas `StockWorkflow` isoladamente ou reconstruir funcionalidades já existentes.
+
+O [manifesto do fluxo](integration/sgf-flow-plan.json) identifica seis módulos, treze etapas, um responsável por efeito, fontes, evidências de saída e lacunas. A verificação `scripts/inspect-module-flow-plan.mjs` confere caminhos/hashes, referências, responsáveis e ausência de ciclos nas dependências obrigatórias. Não carrega aplicações, não executa PHP nem consulta bases. Uma estrutura consistente não demonstra que a integração funcione.
+
+## 2. Fluxo com ramos independentes
+
+O desenho abaixo descreve o percurso sintético a construir, não ligações todas já activas. Os critérios específicos de cada documento permanecem nos serviços responsáveis.
+
+```mermaid
+flowchart LR
+    R[Requisição e ordem aprovadas] --> Q[Recepção e aceitação física]
+    Q --> S[Stock: movimento único]
+    R --> F[Factura de fornecedor conferida]
+    Q -. referências quando exigidas .-> F
+    F --> O[Financeiro: obrigação única]
+    O --> P[Pagamento confirmado e afectação]
+    W[Oficina autorizada e apontamentos verificados] --> C[Consumo de material da empresa]
+    S --> C
+    W --> D[Rascunho comercial revisto]
+    W --> K[Custo validado ou incompleto explícito]
+    C -. origem futura de quantidade/custo .-> K
+    D --> V[Factura de venda elegível]
+    V --> A[Conta a receber e recebimentos]
+    O -. efeito elegível .-> L[Contabilidade: lançamento e comprovativo]
+    P -. liquidação distinta .-> L
+    V -. efeito elegível .-> L
+    A -. recebimento distinto .-> L
+    S -. apenas com valorização definida .-> L
+```
+
+Regras para não criar dependências artificiais:
+
+- A recepção aceite gera quantidade física; a factura não repete a entrada. Factura/obrigação não esperam pelo pagamento. Compras de serviços não passam obrigatoriamente pelo stock.
+- Quantidade recebida e aceite são diferentes; as regras existentes de recepção parcial, rejeição, devolução e elegibilidade da factura são preservadas. A seta da recepção para a factura é condicional às regras existentes, não uma autorização para as omitir.
+- A oficina não exige que um novo processo de compra seja aberto para usar stock já elegível. Material do cliente não é saída do stock da empresa. Apontamento técnico, consumo físico, custo e cobrança são efeitos separados.
+- Custo incompleto fica incompleto; não bloqueia por decisão técnica toda a preparação comercial, nem é usado como preço de venda. A elegibilidade comercial continua explícita.
+- A contabilidade consome cada efeito elegível individualmente. Não espera que toda a cadeia esteja liquidada, nem trata documento, dívida e pagamento como três reconhecimentos do mesmo principal. As regras de reconhecimento e contas ainda terão de ser delimitadas.
+- Vencimento desconhecido é pendência documental visível; não é zero, data inventada ou bloqueio universal do reconhecimento. A fila de associações não atribui módulos automaticamente para desbloquear estas etapas.
+
+## 3. Comprovativo exigido em cada passagem
+
+| Passagem | Responsável único pelo efeito | Evidência necessária para o consumidor | Recusa/pendência que tem de ficar visível |
+| --- | --- | --- | --- |
+| Compra → recepção | Compras confere o documento físico | Origem/versão, linhas recebidas/aceites, qualidade, artigo/armazém explicitamente mapeados | Origem ou mapeamento ausente, quantidade incompatível, recepção parcial |
+| Recepção → stock | Inventory grava uma vez; a fachada de recepção delega na mesma transacção | ID do movimento, origem única, quantidades/unidade, versão do livro, fotografia | Repetição incompatível, lote/âmbito inválido; sem segunda entrada por factura |
+| Factura conferida → obrigação | Payables | Fotografia conferida, principal/moeda, origem e comprovativo de reconhecimento, responsabilidade histórica | Fonte incompleta/incompatível; ausência de vencimento sinalizada separadamente |
+| Pagamento → afectação | Financeiro | Evidência factual, confirmação distinta, saldo disponível, comprovativo de afectação | Sem dinheiro inventado; afectação não equivale a execução bancária |
+| Oficina → consumo | Inventory, a pedido da oficina | Ordem elegível, origem do material/versão, artigo/armazém, comprovativo de saída | Material do cliente, origem já consumida ou falta de stock/âmbito |
+| Oficina → custo/rascunho | Custos valida custo; Comercial cria rascunho | Apontamentos verificados, versões de taxa/preço próprias, revisão exacta | Taxa ausente ≠ zero; custo ≠ preço; sem duplicar material/tempo |
+| Documento/efeito → lançamento | GeneralLedger futuro | Origem elegível, regra de contas vigente, período aberto, débitos/créditos equilibrados | Classificação isolada não é lançamento; não usar menu/rascunho como prova de operação |
+| Livro → relatório | Serviço de leitura do domínio | Âmbito, filtros/data de corte, versão da fonte, ligação aos comprovativos | Fonte indisponível não é saldo zero; relatório definido não é relatório gerado |
+
+O contrato proposto no manifesto exige contexto/actor, origem por sistema/tipo/ID/versão/hash, tipo de efeito, decisão/data/fundamento, chave de repetição, correlação, âmbito de autorização e estado anterior/posterior. Quantidades usam a representação exacta do domínio (milésimos no stock); moeda e política de arredondamento acompanham efeitos monetários. Evidência original é identificada por referência protegida, sem copiar documentos privados para logs/relatórios técnicos.
+
+**Este contrato ainda não está implementado como motor transversal.** Os comprovativos e auditorias existentes continuam a ser autoridade nos seus percursos. O consumidor terá de conferir autenticidade/âmbito/origem/versão, não apenas confiar nos campos enviados pelo browser. Uma correlação facilita rastreio, mas não substitui unicidade: a chave de efeito deverá incluir empresa, origem factual estável e tipo de efeito. Uma alteração de versão não autoriza repetir a mesma entrada; correcção/compensação tem origem própria ligada ao original. Nenhum ID igual entre aplicações prova correspondência empresarial.
+
+## 4. Continuidade, falha e concorrência
+
+Cada comando deve terminar com comprovativo ou pendência explícita. Antes da execução mostra a origem/versão e o impacto; na confirmação revalida permissões, contexto, versões e dependências. Evidência insuficiente impede apenas a operação dependente, conservando o restante trabalho e permitindo consulta/correcção.
+
+Na mesma base, efeito, recibo de repetição e auditoria têm de ficar na mesma transacção. Uma fachada não deve chamar dois escritores concorrentes. Se houver envio posterior a outro domínio, a intenção e o resultado têm de ser duráveis, com estado consultável e repetição idempotente; não acrescentar broker remoto ou executor global antes de existir necessidade concreta. Os registos/outbox já existentes não passam a executar contabilidade por esta preparação.
+
+Perda de resposta: consulta por chave/origem recupera o resultado. Mesma chave com conteúdo diferente recusa. Versão antiga exige nova conferência. Falha entre efeitos não pode apresentar o próximo como concluído. Corrigir não apaga o original: acrescenta decisão/compensação e exige a revisão aplicável. Não prolongar transacção durante o tempo humano de leitura/confirmação; não chamar serviços externos mantendo locks.
+
+## 5. Evitar repetir os gargalos observados
+
+O `StockController` de origem pagina movimentos, mas também lê todos os artigos/armazéns/saldos e consulta resumo de lotes por par. Isso é **um risco encontrado no código, não uma medição nova de lentidão**. A futura consulta SGF não deve copiar esse padrão integral para cada página.
+
+- Paginar/filtar no servidor com ordenação estável; carregar metadados e referências necessárias, sem corpos documentais ou catálogos completos em cada resposta.
+- Agregar movimentos/saldos/lotes para os pares da página em conjunto, sem uma consulta por linha. Filtros por saldo têm de ser aplicados antes de paginar, sem alterar os totais.
+- Usar uma fotografia de leitura coerente e limitar o tempo de transacção. Revisão do livro e critérios de corte explícitos; versões por par não são substituídas por uma versão global arbitrária.
+- Conservar por enquanto a ordem de locks e a protecção de saldo vazio da origem. A experiência da fila mostrou serialização por empresa; não remover esse lock apenas para melhorar um benchmark. Medir depois por tipo de escrita e dependência real.
+- Medir tempo, consultas e memória por página; separar fonte, adaptador e renderização. Índices só na base sintética durante o ensaio e com ganho identificado separadamente. Não transportar automaticamente o índice da auditoria para o livro de stock.
+
+Não se garante ausência de gargalos antes das medições. Estes são critérios de construção/verificação para os encontrar cedo, sem confundir provas locais com capacidade de implantação.
+
+## 6. Ordem de entrega preparada
+
+| Incremento | Resultado a demonstrar | Condição de avanço |
+| --- | --- | --- |
+| I1 — `SGF-STOCK-READ-SIM-v1` | Fonte comum/adaptador de consulta de artigos, armazéns, existências e movimentos | Âmbito delimitado em [STOCK_READ_SCOPE.md](STOCK_READ_SCOPE.md); fonte ausente, recusas, totais e paginação comprovados |
+| I2 — recepção → stock | Mesmo escritor e origens de Compras nas duas composições | Paridade, atomicidade, idempotência e concorrência; sem migração de dados antigos por replay |
+| I3 — oficina → consumo | Ligação explícita por origem/versão, com comprovativo físico | Sem saída duplicada; cliente/empresa separados; falta de saldo e correcção comprovadas |
+| I4 — composição financeira | Reutilizar obrigação, liquidação e recebimentos existentes | Um responsável pelo saldo; histórico e evidências recuperáveis sem conciliação bancária presumida |
+| I5 — primeiro lançamento sintético | Uma classe de efeito, regra de contas e período delimitados | Motor com equilíbrio, versão, unicidade, compensação e histórico; sem declarar contabilidade geral completa |
+| I6 — relatórios e fecho | Leituras reconciliadas e depois fecho/reabertura delimitados | Relatórios rastreáveis ao livro; política de período/correcção antes de fechar |
+
+O desenvolvimento destas capacidades pode correr por etapas com fontes sintéticas explícitas; não precisa de esperar por pessoas/dados reais, revisão visual pendente ou publicação. Uma etapa seguinte não deve usar uma simulação oculta como se fosse efeito operacional da anterior. A implementação de I1 é o próximo trabalho delimitado; esta passagem não a declara executada.
+
+## 7. Prova e preservação desta preparação
+
+Executar com o Node fixado: `C:/laragon/tools/sgf-tempo/node-v24.22.1-win-arm64/node.exe scripts/inspect-module-flow-plan.mjs`. O resultado é um inventário estático de fontes e consistência do desenho, não teste funcional ou ensaio de carga. Nenhuma suite válida anterior precisa de repetição nesta passagem documental.
+
+Não se alteraram rotas, navegação, motores, configurações, dependências, schema ou direitos. Não se consultaram bases, manifestos privados ou credenciais. Os seis registos protegidos, a cache bloqueada, 8039 e outras demonstrações foram preservados. Compras foi lido apenas como fonte; sem alteração/activação de candidata. Sem publicação, push, checkpoint ou aceitação presumidos.
+
+**Pendências independentes:** implementação das ligações delimitadas; provas funcionais por incremento; revisão visual; validação de capacidade/implantação; decisões individuais das seis associações. O inventário de fontes não encerra nenhuma delas.