SGF/docs/PURCHASING_UPDATES_DELIVERY.md

Transferência de Compras e actualizações do SGF

Objectivo e estado em 01/11/2026

O foco autorizado pelo proprietário é transferir as capacidades de Compras para o SGF e levar as melhorias seguintes por versões verificáveis. Não é sincronizar bases de desenvolvimento nem manter duas implementações. O SGC autónomo conserva todas as suas funcionalidades; no SGF, Pessoas e contratações destina-se apenas ao uso interno. Cada cliente recebe as capacidades adquiridas, com configuração e permissões próprias.

Implementado neste incremento: mecanismo de publicação/instalação/actualização/reversão e primeira capacidade realmente extraída e executada no SGF: projecção de reposição de stock. A transferência integral dos processos, ecrãs, identidade e dados de negócio ainda não está concluída.

Conferência antes de ampliar, 01/11/2026: a prioridade passa a ser esta matriz e a delimitação de instalação/reversão, conforme pedido posterior do proprietário. SGF local activo em 0.1.1. O núcleo económico começou a ser preparado antes desse pedido; a transferência em curso foi interrompida antes de nova activação. Existe candidata 0.1.2 no canal, sem instalação no SGF. Código preparado na origem não conta como capacidade transferida.

Actualização posterior autorizada: percurso de requisição interna implementado como candidata de revisão IR-CANDIDATE-bfa807e2b3c4fae7, testada sem activar o destino. A matriz abaixo distingue essa implementação candidata da capacidade instalada. Ver detalhes, recuperação e limites na secção do percurso escolhido.

Fonte única e fronteira dos dois hosts

packages/purchasing em Compras é a fonte canónica. App\Services\ReplenishmentProjection passou a fachada de compatibilidade; os consumidores actuais conservam a assinatura e usam o motor comum Tempo\Purchasing\Supply\ReplenishmentProjection. O SGF carrega os mesmos bytes de uma pasta de versão instalada. Não há chamada HTTP a Compras, procura da pasta vizinha, segundo algoritmo ou alteração das dependências instaladas.

As diferenças concretas que impedem uma cópia directa da aplicação permanecem: SGF usa tenant/empresa fiscal/unidade e concessões/contexto próprios, enquanto Compras usa tenant/departamento e perfis; ambos têm classes App e tabelas-base com significados diferentes. Os frontends e versões de PHP/Brick Math também diferem. Não copiar os controladores, tabelas users/tenants ou histórias de migração de um host para o outro. Extrair capacidades e adaptar contexto/acesso explicitamente.

Matriz de integração conferida

Estados: Transferido identifica a capacidade exacta instalada e executada no SGF; Parcialmente transferido identifica componentes comuns existentes, com lacunas no percurso; Pendente identifica capacidades ainda não incorporadas no SGF. A presença de um menu, cálculo ou classe não comprova transferência do processo completo. Capacidades excluídas do SGF são identificadas à parte.

Processo/capacidade	Estado	Núcleo e persistência	Adaptadores de identidade/acesso e integração	Ecrãs e percurso no SGF	Evidência/lacuna determinante
Publicação, instalação e actualização de código do pacote	Transferido	Artefactos imutáveis, hashes, lock, histórico e ponteiro local; sem schema	CLI local e prova com PHP do host; sem alteração de direitos	CLI implementada; painel de updates não implementado	0.1.0/0.1.1, retry e rollback de código conferidos; migrações e canal remoto assinado pendentes
Cálculo de projecção de reposição	Transferido	Mesmo motor de consumo manual, média racional, reservas/entregas e lotes; sem persistência própria	Carregamento local independente do checkout de Compras; não concede acesso a dados	Sem novo ecrã; capacidade de cálculo instalada	Pacote activo 0.1.1, dois testes SGF e prova de cliente independente
Orçamento de Compras no núcleo comum	Parcialmente transferido	packages/budget-control comum anterior; mesmo motor de reserva	Composição operacional candidata com destino/schema/âmbito explícitos; adaptador instalado continua QA	Interface anterior e candidata de requisições; arranque/rotas operacionais ainda não integrados	20 controlos novos de preparação; restauro em production/base fora do prefixo QA verificado; sem instalação/activação no destino
Preparação de schema da integração	Parcialmente transferido — candidata não instalada	Migração transaccional, contrato do orçamento, registo imutável de revisão/hashes/operadores/backup	CLI plan/migrate local ao host, sem cópia de dados sintéticos ou concessões	Sem ecrã ou activação implícita; CLI de preparação não substitui instalação de código/rotas	Prova nova sgf-operational-delivery.json; destino 0.1.1 preservado
Factura conferida → obrigação a fornecedor	Parcialmente transferido	Núcleo comum de obrigações anterior, com origem única	Adaptador SGF e API no âmbito sintético; sem passagem automática de tabelas/IDs de Compras	Consulta/decisão do percurso anterior; sem workflow integral de recepção/conferência de facturas de Compras	SupplierPayables conserva guarda de ensaio; fornecedor de histórico SGF não concluído conforme entregas anteriores
Pagamentos e afectações a fornecedores	Parcialmente transferido	Núcleo comum e entregas anteriores preservados	Adaptadores/autorizações delimitados nas respectivas entregas; não representam migração de contas ou histórico de cliente	Percurso anterior existe no âmbito documentado; integração completa com novas origens de Compras pendente	SUPPLIER_SETTLEMENT_DELIVERY.md e limites de histórico/origens; não afirmar financeiro integral
Identidade, empresa/unidade, perfis e módulos adquiridos	Parcialmente transferido	Fundações próprias existentes nos dois hosts; não se fundiram tabelas-base	SGF mantém tenant/empresa fiscal/unidade/concessões; correspondência explícita com o contexto Purchasing por concluir	Sessão/contexto SGF existentes; selector SGC não foi incorporado automaticamente	Sem associação por igualdade de nome, email ou ID; parametrização comercial e permissões continuam distintas
Reorganização modular do SGF pedida posteriormente	Pendente — sem resultado apresentado	Entrega distinta da integração candidata de requisições	Não avaliada nem concluída por esta conferência	Não inferir reorganização entregue a partir dos ecrãs candidatos	Exige apresentação própria do âmbito, alterações e resultado; não executada por arrasto
Requisição interna: rascunho, submissão, aprovação independente e consulta	Parcialmente transferido — candidata; não activa	Motor único InternalRequisitions, adaptadores dos dois hosts; recibos, versões e histórico; reserva existente na mesma transacção	Contexto interno, empresa/unidade, autorização renovada, identidade independente e fontes explicitamente associadas; sem novas concessões no destino	Rascunho/edição, lista, submissão, decisão, histórico e parametrização na candidata; sem novo menu/rota activa no SGF	HTTP, concorrência, revogação, falha/recuperação e schema em bases isoladas; equipamentos/peças e instalação comercial pendentes; destino 0.1.1
Planeamento de compras	Pendente	Itens, marcos e associação a requisições permanecem em Compras	Adaptar unidades, centros, intervenientes e vínculos de origem no SGF	Planeamento e acompanhamento de marcos SGF do roteiro de Compras pendentes	Não gerar requisições duplicadas nem inferir reserva/decisão a partir de um plano
Fornecedores, documentos e dados bancários	Pendente	Cadastros/versionamento de Compras ainda não extraídos	Definir correspondências autorizadas de fontes e permissões, sem fundir entidades por nome	Cadastro, validações e consulta SGF de todo o percurso pendentes	Preservar fotografias utilizadas e validação bancária independente
Cotações, descontos e comparação económica	Pendente	Descontos e pontuação foram preparados na origem/candidata 0.1.2; SGF activo não contém estas classes	Elegibilidade, conflitos, avaliações autorizadas e decisão continuam no host; adaptador do processo SGF não implementado	Recepção de cotações, grelha, empates, recomendação e decisão SGF pendentes	Testes locais não equivalem a transferência. Candidata não instalada; nenhuma adjudicação automática
Abertura, admissibilidade, qualificação, recomendação e adjudicação	Pendente	Serviços/snapshots permanecem em Compras	Traduzir contexto, atribuições, impedimentos e versões sem alterar decisões concluídas	Actas, avaliações, decisões e ordens ainda não incorporadas	Necessita persistência e percurso completo por etapa, não simples ligação de menus
Ordens, recepções, inventário físico e lotes	Pendente	O cálculo de reposição está transferido; movimentos, ledger físico, decisões e reversões não	Adaptar origens únicas, armazéns/artigos, separação de funções e âmbito empresarial	Guias, recepções, saídas, transferências, contagens e lotes SGF de Compras pendentes	Não duplicar efeitos físicos ou confundir projecção com stock disponível
Fornecimento habitual, sugestões e importações	Parcialmente transferido	Apenas o motor de projecção incorporado; acordos, políticas versionadas, conversões e logística pendentes	Fontes, decisões, cadastros e vínculos aos processos SGF ainda por adaptar	Calendário, sugestão → requisição e importação operacional SGF pendentes	Um cálculo disponível não completa o workflow de abastecimento
Equipamentos, peças, manutenção e investimento	Pendente	Serviços/cadastros de Compras ainda não incorporados	Correspondência de activos/peças/unidades e regras aprovadas por definir tecnicamente	Ecrãs/percursos de Compras no SGF pendentes	Preservar origens e não repetir consumo físico/custo
Avaliação de fornecedores, melhoria e contraditório	Pendente	Versionamento, decisões e evidências permanecem em Compras	Adaptadores de intervenientes, conflitos e autorização independente pendentes	Preparação, revisão, acompanhamento e relatórios SGF pendentes	Não alterar avaliações antigas nem confundir qualificação com desempenho
Relatórios de Compras e sínteses factuais	Pendente	Projecções autorizadas de Compras ainda não extraídas	Reutilizar âmbito efectivo e versões do processo no SGF	Relatórios individuais/consolidados do roteiro de Compras pendentes	Não substituir por relatórios financeiros SGF de outro âmbito; núcleo factual independente de IA
Venda de mercadorias e ligação ao comercial SGF	Pendente	A opção de contexto não é um percurso completo de retalho/grosso demonstrado em Compras	Reutilizar responsabilidades de stock/facturação SGF, sem criar motores ou efeitos concorrentes	Percurso conjunto por módulos adquiridos ainda por demonstrar	Não confundir aquisição para revenda com venda efectuada nem declarar emissão fiscal transferida
Pessoas: recrutamento e prestadores internos	Pendente	Processos e versões ainda em Compras; fronteira técnica de RH apenas preparada	Adaptar perfis/atribuições e integração futura com RH; apenas contrato formalizado pode desencadear ligação	Candidaturas, avaliações, decisões e formalização/RH no SGF pendentes	RH ainda não implementado; selecção aprovada/rascunho não criam vínculo

Fora do âmbito SGF: recrutamento e contratação de prestadores por conta de terceiros. Mantêm-se no SGC autónomo; não são uma pendência a implementar no SGF. Não transferir candidaturas automaticamente para Compras, vendas ou RH.

Percurso escolhido e candidata de requisições internas

O proprietário autorizou requisição interna → submissão → aprovação independente → consulta do processo, usando a reserva orçamental existente. A implementação está preparada separadamente para revisão. O SGF continua em 0.1.1; nem a candidata económica 0.1.2 nem esta integração foram activadas. Não foram publicados pacotes nem alterados direitos públicos.

O motor packages/purchasing/src/InternalRequisitions.php é usado pelo adaptador autónomo app/Services/InternalRequisitionPort.php e pela candidata integrations/sgf/internal-requisitions. Conserva as regras de valores, limites, reserva antes da submissão e decisão por identidade diferente do requerente e dos decisores anteriores. O adaptador SGF reutiliza CompanyContext, Permissions e BudgetAdapter; não copia utilizadores, empresas ou o motor orçamental.

A candidata inclui rascunho/edição, listagem, submissão, decisão e consulta com histórico, além de parametrização versionada de centros/departamentos/intervenientes/limites. Apenas centros e pessoas autorizados do host podem ser associados. A configuração habilita a opção interna; não atribui permissões. O servidor volta a validar direitos e contexto em cada operação, incluindo repetições, e projecta as acções disponíveis para os ecrãs. Chave de operação, hash do conteúdo, versão esperada, locks e transacção única preservam origem e impedem duplicação de requisições/reservas em retry e concorrência. Uma falha mantém a transacção anterior; uma resposta perdida admite a repetição da mesma operação.

Os artefactos de revisão são produzidos por php scripts/build-internal-requisition-candidate.php. O manifesto, hashes e caminhos estão em proofs/internal-requisitions-candidate.json. runtime.zip contém código e schema explicitamente não instaláveis pelo updater actual; verification.zip contém as provas. Não levam bases, dados sintéticos, credenciais, dependências ou concessões. O caminho do SGF serve apenas para preparar/verificar; o runtime candidato utiliza ficheiros locais e serviços do próprio host. A futura instalação exige uma entrega compatível com schema, separada da activação do ponteiro de código.

Limitações da candidata: SGF suporta neste recorte consumíveis, serviços e outros; equipamentos/peças e respectivas validações técnicas continuam apenas no percurso autónomo. Fornecedores, cotações, ordens e recepções não foram incorporados por arrasto. As rotas/ecrãs só são carregados pelo bootstrap explícito das provas; não há novo menu activo no destino. A integração do catálogo privado de permissões na administração comercial, a instalação/migração operacional e a parametrização comercial integral permanecem pendentes. A guarda isolada do adaptador orçamental SGF foi preservada. Não há integração de contratações para terceiros nem activação de RH.

Classificação das pendências para decidir a instalação

Incremento posterior de preparação dos acessos: o catálogo e a autoridade inicial já têm implementação candidata em integrations/sgf/access, preparada separadamente em ACCESS-CANDIDATE-a69f06e21747228a. Prova proofs/sgf-access-delivery.json: 24 controlos novos, em PostgreSQL descartável, sem repetir as suites aprovadas da requisição. O SGF instalado continua com o catálogo anterior. As classificações abaixo mantêm-se bloqueantes até integrar e instalar esta preparação com o orçamento/schema/arranque operacionais; não significam ausência de implementação candidata.

Conferência de código posterior à entrega, sem repetir testes aprovados e sem alterar a candidata congelada ou a instalação SGF. A candidata comprova o percurso em ensaio isolado; ainda não é uma entrega operacional instalável.

Pendência	Classificação para este percurso	Impacto e condição de resolução
Equipamentos/peças e validações técnicas	Fora do âmbito do percurso básico entregue	O adaptador SGF aceita consumable, service e other. Estas requisições podem completar rascunho → submissão/reserva → aprovação → consulta sem equipamentos/peças. Uma necessidade de equipamento/peça continua sem percurso SGF suportado; não deve ser disfarçada como other. A classificação não declara suporte a todos os tipos de requisição.
Catálogo administrativo das novas permissões e sua gestão	Bloqueante para este percurso em utilização operacional	Permissions::UNIT contém apenas unit.view e unit.edit; IdentityWorkflow::accessList/changeAccess filtra/valida esse catálogo. Os direitos purchasing_requisitions.* não podem ser atribuídos/revogados pela administração normal. As concessões directas dos testes foram apenas sintéticas e não constituem configuração comercial entregue.
Autoridade inicial para gerir/outorgar os novos direitos	Bloqueante para este percurso em utilização operacional	changeAccess exige que quem concede já possua o direito concedido. Acrescentar nomes ao catálogo não resolve a atribuição inicial: é necessária entrega nominativa, explícita e auditada da autoridade aprovada pela empresa, sem outorga automática aos perfis actuais. A listagem e revogação de direitos derivados da unidade também devem abranger o catálogo integrado.
Adaptador orçamental operacional	Bloqueante para este percurso em utilização operacional	BudgetAdapter::guard() exige ambiente budget-testing, PostgreSQL local e base budget_core_sgf_<12hex>. O adaptador de requisições chama essa guarda inclusive na consulta/configuração. Não basta copiar ficheiros ou permitir requisições sem orçamento. Substituir a composição exclusiva de ensaio por composição operacional configurada, mantendo autorização, isolamento e motor comum; não renomear base real nem mudar o ambiente para contornar a guarda. Os direitos orçamentais necessários também não integram o catálogo administrativo actual.
Instalação/migração, arranque e encaminhamento das rotas	Bloqueante para este percurso em utilização operacional	Schema::install e bootstrap existem, mas só foram compostos no harness isolado. Falta instalador operacional com pré-condições, registo de migração e recuperação, composição local e registo controlado de rotas. O updater actual recusa esta candidata; não é possível instalar o percurso com o comando habitual de update de código.
Fornecedores, cotações, ordens, recepções e contratações para terceiros	Fora do âmbito desta entrega	Não são necessários para terminar a requisição no estado aprovado e consultá-la; contratação para terceiros permanece excluída do SGF.

Direitos que a instalação deve permitir gerir, sem os conceder implicitamente: por empresa/unidade, purchasing_requisitions.view, .prepare, .configure, .approve.department_head, .approve.procurement e .approve.finance. Mantêm-se company.view, pertença à empresa e unit.view como condições do contexto. Submeter com reserva exige ainda purchasing_budget.record; rejeitar com libertação também usa esse direito existente. Preparação/aprovação da dotação usa os direitos do orçamento existente e deve ter responsáveis expressamente configurados. Só os escalões aplicáveis à política precisam de decisores, sempre com identidades distintas do requerente e dos decisores anteriores. Não é necessário conceder todos os direitos a todos os utilizadores.

Implementação candidata do catálogo e autoridade inicial

php scripts/prepare-sgf-access.php <raiz-SGF> lê os dois ficheiros de identidade do host e produz uma sobreposição de revisão em storage/app/private/candidates/ACCESS-CANDIDATE-<hash>, com manifesto e hashes antes/depois. Não escreve na pasta SGF, não aplica schema nem concede direitos. Recusa preparar uma alteração se os pontos esperados no host divergirem, exigindo reconciliação do trabalho em curso. A candidata original IR-CANDIDATE-bfa807e2b3c4fae7 não foi reescrita.

Na sobreposição, o catálogo unitário inclui os direitos de requisição e orçamento existentes; a criação de unidades continua a outorgar apenas unit.view/unit.edit. A administração nativa passa a listar/atribuir/revogar os novos direitos, conservando a exigência de o administrador possuir o direito que outorga. A atribuição unitária exige consulta da unidade pelo destinatário. Revogar a consulta da unidade confere autoridade sobre todos os direitos derivados afectados antes de os remover numa transacção; uma recusa não elimina parcialmente acessos.

InitialAuthority.php resolve a atribuição inicial como operação explícita. Exige administrador autenticado com access.manage, consulta/pertença ao contexto e uma lista de âmbitos habilitados pela futura composição de instalação (purchasing-access.initialisation_scopes, chaves tenant:company:unit; vazia por omissão). Só admite como destinatários administradores nominativos já autorizados nessa empresa/unidade. Escolhem-se os direitos e um fundamento, sem selecção automática de todos os direitos. Não atribui perfis de desenvolvimento. A concessão e a auditoria nativa purchasing.access_initialised são atómicas, serializadas pela empresa. Uma falha de auditoria desfaz as concessões. Uma repetição exacta não concede de novo nem recupera direitos entretanto revogados; outra inicialização é recusada, seguindo-se a gestão normal de acessos. Revogar a autoridade administrativa bloqueia também a consulta do ecrã e a repetição da operação.

As rotas candidatas em integrations/sgf/access/routes.php oferecem o ecrã /purchasing/internal-requisitions/access-initialisation e a operação /api/internal-requisitions/access-initialisation, com os middlewares nativos de autenticação, sessão e empresa. O ecrã mostra o contexto, permite escolher um destinatário nominativo e os direitos e envia CSRF/token de contexto/chave estável de operação. Estas rotas não estão registadas no destino. A prova nova verificou serviços nativos, persistência, autorização e renderização do ecrã; não declara ensaio HTTP completo ou revisão visual deste novo ecrã. A composição de instalação deverá ligar estas rotas ao módulo autorizado e retirar a habilitação de inicialização depois da entrega, preservando a auditoria.

Próxima dependência concreta: preparar a composição orçamental operacional e o instalador rastreável, incorporar esta sobreposição ao pacote SGF específico e conferir a sua integração HTTP. Não activar o módulo, a candidata de acessos ou 0.1.2 por consequência desta implementação.

Procedimento de instalação: estado exacto e sequência obrigatória

Incremento posterior — composição orçamental e preparação de schema: implementados em candidata separada integrations/sgf/operational e scripts/sgf-internal-install.php. Já existe executor de preparação de schema, com plan e migrate; continua sem existir comando completo de instalação/activação de código e rotas. Esta actualização sucede à ausência de executor registada na primeira conferência, preservando o âmbito das provas anteriores. Ver proofs/sgf-operational-delivery.json. Nenhum destes comandos foi executado na base da instalação SGF de destino.

php scripts/prepare-sgf-operational.php <raiz-SGF> lê o host e produz OPERATIONAL-CANDIDATE-<hash>, com manifesto, sobreposições de identidade/orçamento e ficheiros de suporte locais. Não escreve no SGF nem publica um pacote. A sobreposição orçamental conserva o motor e autorizações existentes; acrescenta composição operacional habilitada explicitamente, sem depender de APP_ENV=budget-testing ou de um nome de base QA. A guarda exige impressão do destino real (configuração e endereço/porta PostgreSQL efectivos), schema/versão de migração conferidos e âmbito tenant:company:unit autorizado em purchasing-operational.scopes. purchasing-operational.enabled é falso por omissão e purchasing-operational.target deve coincidir com o destino conferido. A guarda de ensaio anterior permanece para a composição QA, sem se tornar uma autorização operacional alternativa.

A preparação exige fundação de identidade existente; cria o schema orçamental vazio se ausente, ou confere o schema completo existente contra o contrato estrutural aceite, conservando registos e dotação aprovada. Schema parcial ou incompatível é recusado. Estende os valores unitários aceites pelo constraint de permissões sem conceder direitos. Aplica o schema de requisições e grava sgc_installations imutável, revisão 1, assinatura estrutural, hash da migração, backup, operador nominativo de implantação e role PostgreSQL executante. Usa lock transaccional de instalação e DDL transaccional. Repetição com a mesma migração/schema reconhece a preparação anterior; alterações divergentes são recusadas sem sobrescrever. Não há down nem eliminação de dados no executor. A revisão actual não é mecanismo genérico para futuras migrações; estas exigem novo plano compatível e revisão própria.

Procedimento da CLI na candidata, pelo PHP fixado do host, apenas depois da decisão de instalação e preservação do destino:

powershell.exe -NoProfile -ExecutionPolicy Bypass -File "<raiz-SGF>/scripts/sgf.ps1" php "<candidata>/scripts/sgf-internal-install.php" plan "<raiz-SGF>"
powershell.exe -NoProfile -ExecutionPolicy Bypass -File "<raiz-SGF>/scripts/sgf.ps1" php "<candidata>/scripts/sgf-internal-install.php" migrate "<raiz-SGF>" <target-sha256> "<backup.dump>" <backup-sha256> "<operador-nominativo>" <manifest-sha256>

plan só lê/verifica: integridade dos ficheiros da candidata, compatibilidade dos ficheiros do host com hashes antes/depois, identidade do destino, hash do manifesto e existência do registo de preparação. O campo schema_prepared informa a existência da tabela de registo; não substitui a conferência integral feita por migrate/guarda operacional. Conferir o manifesto/hashes com a referência de entrega por canal de confiança. migrate exige correspondência do destino e do manifesto, ficheiro de backup existente e SHA-256 coincidente; lê o índice com pg_restore --list antes de escrever. O cliente PostgreSQL deve estar no PATH ou indicado por PG_RESTORE_BINARY. Conferir o índice não prova recuperação: manter o restauro/reconciliação já aceites e o ensaio adicional da preparação operacional registado na prova. Nenhuma credencial deve ser passada nos argumentos ou copiada para o manifesto; usa-se a ligação configurada do próprio host.

Prova deste incremento: OPERATIONAL-CANDIDATE-29687a1c9bc0e0b5, 20 controlos novos aprovados, incluindo CLI real, backup custom válido, recusa de backup não conferido, schema vazio/existente/parcial/incompatível, falha injectada, recuperação da transacção, repetição sem novo registo, ausência de concessões e preservação do orçamento aprovado. Após backup/restauro para outra base descartável fora de budget_core_sgf_*, a mesma composição passou em production, conferindo schema/registo de preparação, reserva existente e revogação preservada. Este ensaio verifica o novo registo/schema operacional; não repete nem substitui as suites já aprovadas da requisição. As duas bases e role restrita foram removidas; o backup sintético não integra a entrega. Os caminhos e resultados estão em proofs/sgf-operational-delivery.json. Os ficheiros de código/ponteiro e dados do SGF instalado não foram alterados.

Após migrate, o estado é preparado, não activado: não altera o ponteiro 0.1.1, providers/rotas, concessões, dados de demonstração ou configuração de activação. O código/sobreposições candidatos ainda precisam de aplicação controlada, composição de arranque e integração HTTP antes de propor a activação. A configuração comercial por empresa/unidade e a atribuição explícita de acessos continuam obrigatórias. Isto não entrega fornecedores, consumo de facturas, pagamentos, equipamentos/peças ou reorganização modular do SGF.

Não há neste momento um comando operacional completo para instalar esta candidata. Os passos abaixo distinguem o que existe do que falta implementar; não são autorização para os executar no destino. A decisão de instalação continua separada. Não usar purchasing:transfer, purchasing-release.php install, os scripts de prova ou as fixtures para instalar esta integração numa empresa. O pacote runtime.zip é um artefacto de revisão, não deve ser extraído sobre a raiz do SGF: inclui também adaptações app/* de Compras que não pertencem ao host SGF.

1. Identificar e conferir — disponível: fixar a candidata IR-CANDIDATE-bfa807e2b3c4fae7, o manifesto e os hashes em proofs/internal-requisitions-candidate.json; conferir o ZIP e cada ficheiro contra o manifesto. Registar raiz/destino, PHP do wrapper SGF, versão de aplicação/dependências, servidor/base/empresa/unidade e estado do ponteiro packages/purchasing/current.json (actualmente 0.1.1). Confirmar que os pré-requisitos de identidade e orçamento correspondem à composição pretendida. Nenhum comando desta etapa migra ou concede direitos.
2. Preparar a entrega operacional — bloqueado pelas implementações identificadas acima: produzir pacote SGF separado e versionado apenas com os ficheiros comuns necessários e adaptadores/ecrãs do host; incluir migração rastreável, composição operacional do orçamento, catálogo/gestão dos direitos e mecanismo de autoridade inicial. Conservar os hashes da candidata como referência; uma alteração de código origina outro artefacto, sem sobrescrever o congelado. A migração 46 de Compras não se aplica à base SGF. Não copiar tabelas base nem fixtures de Compras.
3. Preservar o destino — procedimento necessário antes de qualquer futura escrita: suspender tráfego de escrita e workers, aguardar transacções em curso, registar instante de corte, arquivar código/configuração de implantação e ponteiro/histórico; preservar documentos/ficheiros e contas. Fazer backup integral PostgreSQL da base conferida, não apenas das tabelas ir_*, pois o orçamento e as concessões também são afectados. Guardar o arquivo, hash e identidade do destino fora do pacote distribuído. Não incluir segredos no registo de implantação.
4. Aplicar schema e preparar código sem expor rotas — executor de schema agora em candidata: usar a CLI plan/migrate descrita acima, sem outorgar acessos. O wrapper transaccional regista revisão, confere repetições e recusa divergências; não executar Schema::install isoladamente. Preparar os ficheiros num directório local de versão, sem sobrepor os app/* de Compras nem trocar para 0.1.2. A aplicação das sobreposições e o arranque/activação do código continuam separados e pendentes.
5. Configurar acessos e política — bloqueado pelo catálogo/autoridade inicial: pelos mecanismos administrativos auditados, atribuir explicitamente os direitos aprovados a pessoas nominativas e ao âmbito correcto; garantir requerente e aprovadores distintos, e responsáveis da dotação. Depois configurar centros existentes, referências de departamento, intervenientes, limites, inclusão de imposto e exigência de orçamento. Nenhum nome ou ID de outra instalação é uma correspondência automática. Não inserir concessões por SQL como solução de entrega.
6. Activar — depende de decisão separada e das etapas anteriores concluídas: registar arranque/rotas locais do módulo e abrir o percurso apenas para contextos/módulos adquiridos e utilizadores autorizados; reiniciar serviços persistentes pelo procedimento do host. Conferir o estado aplicado, acessos efectivos e a consulta do processo no destino, sem repetir as suites já aprovadas. Registar versão, schema, configuração, autoria e instante da activação. Só então reabrir escritas/workers. Não existe nesta entrega comando que concretize esta etapa; nenhum destes passos foi executado na instalação SGF.

Procedimento de recuperação por tipo de falha

Os ensaios aceites sustentam DDL transaccional e backup/restauro isolado; não equivalem a um instalador de recuperação automática de cliente. Não repetir os testes para esta classificação.

Situação	Acção exacta
Falha de preparação, antes de escrever no destino	Abandonar a preparação; conservar o código/ponteiro 0.1.1 e a base intactos. Não há migração ou reversão de dados a executar.
Excepção durante a transacção de schema	Fazer rollback da transacção; conferir ausência de tabelas/alterações parciais e igualdade com o inventário prévio. Se a ligação se perder durante o commit, primeiro inspeccionar schema e registo de revisão; não pressupor rollback nem repetir Schema::install às cegas. Manter o módulo desactivado até esclarecer o estado.
Código não arranca após schema confirmado, antes de novas operações	Retirar o novo registo de rotas/arranque e regressar ao código/configuração anterior arquivados; reiniciar os serviços. Manter o schema aditivo e os dados, incluindo auditoria. O ponteiro 0.1.1 não reverte alterações do host. Não executar down, truncar ir_*, estreitar a coluna de permissões ou remover direitos/histórico por arrasto.
Falha numa submissão/decisão ou resposta perdida	Conservar a identidade/contexto e repetir exactamente a mesma chave, versão e conteúdo; o recibo devolve o efeito já confirmado ou a transacção recomeça sem reserva duplicada. Se houver conflito de versão/conteúdo ou revogação, consultar o processo com identidade autorizada; não gerar uma nova origem para contornar o erro.
Corrupção/dados ou schema incompatíveis após operações novas	Suspender escritas/workers; preservar também uma cópia do estado que falhou e operações posteriores ao corte. Restaurar o backup numa nova base vazia, nunca por cima da base em uso. Conferir tabelas/dados, schema/constraints/triggers e consulta de origens/versões/reservas. Reconciliar explicitamente as operações posteriores ao backup e a configuração/autorização actual, incluindo revogações; um backup antigo não deve reabrir acessos revogados. Só apontar a aplicação à base recuperada após conferência e decisão registada. Conservar a base anterior para diagnóstico.

Forma dos comandos PostgreSQL usados na prova aceite, a adaptar ao destino conferido e à autenticação administrativa local, não executados nesta conferência:

pg_dump --format=custom --file=<arquivo-backup.dump> --dbname=<base-origem-conferida>
pg_restore --list <arquivo-backup.dump>
createdb --owner=<proprietario-autorizado> <nova-base-vazia-de-recuperacao>
pg_restore --no-owner --no-privileges --exit-on-error --dbname=<nova-base-vazia-de-recuperacao> <arquivo-backup.dump>

O restauro da prova usou uma role restrita proprietária da nova base. --no-owner --no-privileges não restaura roles/grants PostgreSQL: estes devem ser preservados no inventário administrativo e repostos explicitamente no ambiente de recuperação. As permissões funcionais da aplicação são dados da base e também exigem reconciliação temporal. pg_restore --list só lê o índice; a prova de recuperação aceite é o restauro efectivo com reconciliação das 22 tabelas e consulta posterior já registados. Os comandos não restauram documentos externos, .env, dependências ou código; estes têm cópias/procedimentos próprios. Não há comando único entregue para fazer a troca operacional da base.

Entrega distinta da reorganização modular do SGF

Esta entrega é a integração candidata de requisições internas. Extrair um motor e preparar um adaptador não comprova a reorganização modular do SGF pedida posteriormente. Essa reorganização continua pendente, sem resultado apresentado nesta entrega, e deve ter inventário, alterações e resultado próprios. Não a contar como concluída na matriz nem usar esta classificação como autorização para a executar por arrasto.

Dados/schema: ensaio separado da reversão de código

• Compras: migração aditiva 2026_11_01_000046_add_requisition_command_versions.php, sobre a base que já contém a migração 45. Acrescenta versão do processo e recibos imutáveis de comando; não reclassifica nem apaga dados. O caminho autónomo anterior continua utilizável sem instalar os recibos; o ecrã só envia chaves/versões quando o schema está preparado. down recusa apagar recibos já existentes. Nenhuma migração foi aplicada à base persistente de desenvolvimento.
• SGF: Schema.php acrescenta as tabelas ir_*, alarga o comprimento de permission_grants.permission e estende a condição de âmbito com os direitos privados da candidata. Conserva a condição anterior e os seus registos, sem conceder direitos. Políticas e histórico são versionados e imutáveis; snapshots submetidos e origem não são reescritos. A instalação foi ensaiada em PostgreSQL descartável já com identidades, concessões e orçamento sintéticos.
• Falha/compatibilidade: DDL transaccional com falha injectada preserva schema/dados anteriores e permite nova tentativa. Foi ensaiada uma evolução aditiva compatível com a candidata anterior. Isto não comprova compatibilidade com futuras alterações destrutivas.
• Recuperação: backup/restauro para outra base isolada, reconciliação de dados, colunas, constraints e triggers e consulta do processo restaurado. O backup de ensaio é sintético e não faz parte do pacote cliente. Uma recuperação real exige parar escritas e reconciliar operações posteriores ao backup; não há restauro automático sobre operações novas.
• Código: o updater continua limitado a código sem migrações. Voltar ao código 0.1.1 não remove tabelas nem restaura dados, e essa versão não apresenta o novo percurso. Não executar down nem recuperar uma base antiga como efeito implícito de rollback do ponteiro.

As provas e os resultados efectivos deste incremento constam de proofs/internal-requisitions-sgf.json. As provas históricas abaixo conservam o respectivo âmbito. Ecrãs foram verificados por HTTP, modelo de acções, tipos/lint e compilação; não houve revisão visual por navegador.

Verificação da candidata congelada	Resultado
Integração SGF pelo PHP 8.4.27 do host, PostgreSQL descartável	43 controlos; 2 origens, 2 requisições e 2 reservas, incluindo save/submit/decide concorrentes em processos separados
Adaptador autónomo e regressão de compras/orçamento em PostgreSQL descartável	46 testes / 339 asserções
Regressão completa de Compras em SQLite isolado	883 testes: 881 aprovados, 2 ignorados; 8.950 asserções; resultado final em proofs/internal-requisitions-validation.json
Recuperação de dados/schema	22 tabelas reconciliadas; constraints/triggers/colunas conferidos; consulta restaurada preserva origem e versão 3
Modelo dos ecrãs congelados, limites monetários exactos, envelopes de retry e headers	23 controlos Node; sem navegador
PHPStan dirigido, TypeScript, lint/formatação e build frontend	Aprovados; sem erros PHPStan ou avisos lint nos ficheiros verificados
Activação e permissões no SGF de destino	Ponteiro 0.1.1 preservado; candidata recusada pelo updater normal; nenhuma concessão aplicada

Percurso de actualização

Separação entre preparação e instalação cliente

Etapa	Acesso necessário	Dependência de Compras na instalação cliente
Produzir ZIP validado (publish-purchasing.php)	Fonte Compras e canal de saída; não precisa de pasta SGF	Nenhuma depois de produzido o artefacto
Coordenar prova/instalação no SGF de desenvolvimento (transfer-purchasing.php)	Pastas locais de Compras/SGF, wrapper e canal	É uma ferramenta de desenvolvimento, não o instalador obrigatório do cliente
Conferir/instalar no cliente (purchasing-release.php)	SGF do próprio cliente com dependências e ferramentas de arranque, ZIP e SHA-256 aprovado	Não usa pasta, base, sessão ou serviço de Compras
Executar a capacidade instalada	Loader, versão seleccionada e dependências locais do SGF	Não consulta a origem nem sincroniza dados com ela

Conferido por dois meios: teste em pasta cliente sintética com a pasta de origem renomeada para indisponível; e execução no SGF 0.1.1 verificando que todos os ficheiros PHP carregados pertencem ao próprio host. A segunda prova não arranca a aplicação nem liga à base. Isto comprova a independência do pacote actual, não a preparação completa de todos os futuros módulos de cliente.

No desenvolvimento, a partir de Compras:

composer purchasing:transfer -- C:/laragon/www/sgf-tempo C:/laragon/data/sgc-releases/purchasing

O comando usa o wrapper e o PHP fixado pelo SGF, sem substituir versões. Executa regressões da capacidade e do mecanismo; verifica que a origem não mudou durante os testes; prova uma fotografia imutável; publica essa mesma fotografia; compara com a versão instalada; prova a candidata com o PHP/dependências do SGF; instala se for mais recente. Sem alterações no pacote, não gera versão nem reinstala código. O exemplo de caminho é do ambiente local, não dependência do runtime ou do formato distribuído.

Para apenas produzir uma versão validada, usar composer purchasing:publish -- <canal>. O comando scripts/purchasing-release.php publish é a primitiva técnica sem execução de testes; a publicação normal usa o percurso validado anterior.

O canal contém catalog.json e ZIPs imutáveis. Há numeração patch automática por alteração dos bytes; source_sha256 identifica o conjunto exacto de ficheiros. O manifesto individual contém SHA-256 por ficheiro e contrato/capacidades do módulo. A validação rejeita ficheiros extra, ausentes, alterados, caminhos inválidos, entradas duplicadas e arquivos excessivos.

Na instalação cliente, distribuir o ZIP, os artefactos de arranque e a referência SHA-256 por canal de confiança. Não é necessário o checkout de Compras:

php scripts/purchasing-release.php check <raiz-SGF> <versao.zip> <sha256-manifesto>
php scripts/purchasing-release.php install <raiz-SGF> <versao.zip> <sha256-manifesto>
php scripts/purchasing-release.php status <raiz-SGF>
php scripts/purchasing-release.php rollback <raiz-SGF>

O SHA-256 confere integridade contra a referência aprovada; não autentica sozinho um canal remoto. Não há download ou activação a partir de URLs arbitrários. Um catálogo remoto assinado e verificação de assinatura ainda não integram esta entrega.

Preservação e recuperação

Cada versão ocupa packages/purchasing/releases/<versão>; current.json é o ponteiro local. A instalação valida a versão actual antes de actualizar, prepara a candidata separadamente, regista histórico e troca o ponteiro atomicamente sob lock. Não apaga a versão anterior. Uma alteração local ao código instalado bloqueia a actualização em vez de a sobrescrever. Versão igual com conteúdo diferente e downgrade implícito são recusados. A reversão explícita confere os bytes anteriores e não recalcula nem apaga dados.

current.json, locks e histórico são estado da instalação e não credenciais/contas distribuídas. O SGF pode arrancar sem este módulo opcional instalado; depois da instalação, o provider carrega o pacote verificado. O histórico é local e não deve ser transplantado de uma empresa para outra.

O formato actual recusa pacotes com alterações de schema ou concessões. Os comandos de instalação/prova do primeiro incremento não abriram bases nem executaram migrações, seeds, alterações de contas, permissões, stock, finanças ou contratos. A nova candidata de requisições ensaiou persistência apenas em bases sintéticas descartáveis, conforme secção própria, sem alargar o contrato do updater. Serviços persistentes devem ser reiniciados pelo procedimento operacional depois de actualizar; o instalador não termina processos.

Alcance exacto da reversão

Elemento	Cobertura actual
Código do pacote e versão seleccionada	Reversão explícita para a versão anterior, depois de conferir integridade; histórico local e troca de ponteiro
Dependências PHP/Composer e frontend do host	Não são substituídas nem revertidas por este mecanismo
Dados empresariais, schema, configuração e permissões	Não são alterados nem revertidos pelo actual contrato
Migrações de dados/schema	Fora do updater; na candidata interna, DDL falhada, compatibilidade aditiva e backup/restauro em base isolada ensaiados separadamente; sem down/restauro automático

O manifesto exige database_changes=false e o formato não aceita pastas de migração/seed; isso delimita o contrato distribuído actual, não torna PHP futuro uma sandbox. Uma capacidade com persistência exige antes um contrato de migração com autoria/versão, schema compatível, aplicação idempotente, auditoria, destino conferido e backup/restauro ensaiados em isolamento. Deve distinguir reversão de código compatível, correcção por migração seguinte e eventual restauro de dados com plano de reconciliação. Não executar automaticamente down, apagar históricos ou restaurar um backup antigo sobre novas operações. A estratégia concreta terá de acompanhar o percurso escolhido.

Provas e limites

Conferência adicional antes de ampliar: seis testes do mecanismo/29 asserções, incluindo execução em cliente com origem indisponível; prova SGF em PHP 8.4.27, versão activa 0.1.1, todos os ficheiros carregados no próprio host e nenhuma ligação à base. Ver proofs/purchasing-client-independence.json. As provas do primeiro incremento abaixo mantêm o seu âmbito histórico. A candidata 0.1.2 contém preparação económica, mas não foi instalada; não contar os testes dessa preparação como prova do processo económico no SGF.

• Compras: 86 testes/566 asserções no percurso de publicação (reposição, histórico, lotes, coordenação, sugestões, estornos, contagens e cinco testes do mecanismo).
• SGF: dois testes/11 asserções, executados com o wrapper e PHP 8.4.27, sem base; execução real do pacote e resultados de consumo manual, média racional e lotes.
• Publicação 0.1.0 e actualização 0.1.1 instaladas localmente. A segunda versão acrescenta documentação do contrato de distribuição; o algoritmo transferido permaneceu igual.
• Reversão real 0.1.1 → 0.1.0 e reactivação 0.1.1 conferidas, sem dados/permissões alterados.
• Cinco testes do instalador cobrem publicação sem duplicação, nova versão, retry, rollback/reactivação, código local alterado, manifesto errado, conteúdo adulterado, path traversal, ficheiro ausente, segredo na origem e pedido de alteração de schema.
• Fachada e motor comum passaram análise PHP dirigida. Fonte do mecanismo e artefactos SGF conferidos em packages/module-updates/runtime-manifest.json.

Limitação central: este mecanismo actualiza as capacidades já extraídas para o pacote; não transfere automaticamente melhorias ainda confinadas aos controladores/serviços/ecrãs de Compras. Continuar a migração pela matriz acima, sem declarar todo o SGF actualizado só porque a versão do pacote mudou. Não há publicação no domínio ou conclusão de integração de RH nesta entrega.