# Decisão de instalação da integração de requisições no SGF

Data: **02/11/2026**. Estado: **proposta para decisão; instalação não autorizada nem executada**.

## Recomendação concreta

**Não confirmar ainda a instalação desta candidata como percurso operacional.** Os mecanismos e provas isoladas permanecem válidos, mas a conferência do destino revelou lacunas de implantação que esses ensaios com roles proprietárias e cadastros sintéticos não cobriam: ligação de migração/privilégios SQL da aplicação e preparação operacional de centros/dotações pela interface.

A operação futura proposta é **instalação técnica de schema e código, inicialmente desactivada**, no destino abaixo, sem outorga automática de direitos, sem dados de Compras e sem mudar o pacote activo 0.1.1. Antes de pedir a confirmação dessa operação, fechar o plano de privilégios e de recuperação do destino. A disponibilização aos utilizadores exige ainda resolver o cadastro/orçamento e a configuração nominativa. Não há autorização para executar `migrate`, `apply`, `cache`, concessões, manutenção ou paragem/reinício de serviços nesta decisão.

## Destino conferido, não uma instalação genérica

| Elemento | Valor |
| --- | --- |
| Projecto SGF local | `C:\laragon\www\sgf-tempo` |
| URL configurada | `http://127.0.0.1:8000` — não é publicação num domínio |
| Ambiente/PHP | `local`; PHP **8.4.27** pelo wrapper do SGF |
| Base efectiva | PostgreSQL **`sgf_tempo_dev`**, `127.0.0.1:55432` |
| Role da aplicação | `sgf_dev_app` — sem CREATE no schema public e sem autoridade para ALTER em permission_grants |
| Proprietário existente da tabela de permissões | `sgf_dev_owner` — LOGIN e CREATE em public confirmados; credenciais não consultadas nem registadas |
| Estado anterior | 87 tabelas public; fundação de identidade presente; nenhum `cb_*`, `ir_*` ou `sgc_installations` da candidata |
| Configuração de integração | Bundle/ficheiro operacional ausentes; manutenção inactiva; configuração Laravel não compilada no instante da leitura |
| Pacote instalado de Compras | **0.1.1**, ponteiro SHA-256 `81899e531e9eec449717e694d8bdc106a9e220a828f5491ce918c1d2dc612787` |
| Revisão Git SGF observada | `fcf0ada22701337acd4c84b404207b8400f490a2`; não substitui a conferência dos ficheiros locais em curso |

Inventário por **transacção PostgreSQL READ ONLY**, sem migrar: [prova da decisão](proofs/sgf-installation-decision-inventory.json). As contagens/impressões digitais preservadas incluem 89 concessões, duas pertenças e 162 eventos de auditoria. Há uma empresa, uma unidade e **uma concessão de administração da empresa**; não foram enumerados nomes, emails ou credenciais. A base `sgf_tempo_test`, a instância modular isolada em 8039/cluster 55439 e as demonstrações anteriores não são este destino e não podem ser reiniciadas/resetadas por arrasto.

O registo antigo de processo web não foi tomado como confirmação de processo actualmente activo. Na janela futura, conferir o PID/executável/instante de arranque e vinculação ao projecto antes de actuar. **Não usar `sgf.ps1 stop` indiscriminadamente**: esse comando também pára o cluster PostgreSQL 55432, partilhado com outras bases.

## Candidata exacta e planos de leitura

| Referência | Valor |
| --- | --- |
| Identidade da candidata | **`OPERATIONAL-CANDIDATE-5fae7cf7f99c42ba`** — versão identificada por conteúdo, não 0.1.2 |
| Directório | `C:\laragon\www\compras\storage\app\private\candidates\OPERATIONAL-CANDIDATE-5fae7cf7f99c42ba` |
| ZIP | `C:\laragon\www\compras\storage\app\private\candidate-archives\OPERATIONAL-CANDIDATE-5fae7cf7f99c42ba.zip` |
| SHA-256 ZIP, reconferido | `d14a3261d5aaab80f96250af781c700ab53376021f4638e3aee43c15ff37ceed` |
| SHA-256 manifesto | `b1ec47f7a9ad87e0b232bac41e402d4a00ee5f03f00a79b93effc692ce8b39a2` |
| Impressão de destino do plano de código | `bab719ee4e08555a8e1de694dd3a93df82680c7aba653613f0714dd76e4065d6` |
| Impressão de destino do plano de schema | `169e6e863f28b67740f07b6e7cbc664fbe585a7760a83dccebc8d482ad8ab792` |
| ID previsto de primeira aplicação | `b1ec47f7a9ad87e0b232bac4` — reconfirmar no retorno real da CLI |

Os dois comandos `plan` passaram no destino e só leram/conferiram estado. Isso **não executa nem valida a capacidade de escrever DDL com a role runtime**, e `schema_prepared=false`. Os hashes são uma fotografia: repetir os planos de leitura imediatamente antes de uma operação aprovada; divergência impede usar esta decisão antiga como autorização para sobrescrever o destino.

## Alterações previstas, sem efeitos já aplicados

**Código:** criar o bundle local `packages/internal-requisitions`; aplicar sobreposições conferidas apenas a `Permissions.php`, `IdentityWorkflow.php`, `BudgetAdapter.php`, `AppServiceProvider.php` e `ModuleNavigation.php`. Guardar backups/journal em `storage/app/private/module-deployments`; tratar os caches padrão. Preservar restantes ficheiros/trabalho local. Não alterar `packages/purchasing/current.json`, activar 0.1.2, publicar ou copiar a base de Compras.

**Schema, revisão 1:** acrescentar **14 tabelas**: sete `cb_*` (`centres`, `origins`, `budgets`, `budget_entries`, `budget_consumptions`, `budget_reinforcements`, `audit`), seis `ir_*` (`requests`, `steps`, `events`, `commands`, `policies`, `policy_versions`) e `sgc_installations`. Sem dados sintéticos iniciais. Alargar `permission_grants.permission` de 40 para 100 e estender o CHECK unitário com os novos valores, preservando a expressão e os registos anteriores. Acrescentar FKs, unicidade e triggers de origem/versão/aprovação independente/histórico imutável. Os dados e decisões existentes não são classificados nem reescritos. **A migração 46 de Compras não é aplicada no SGF.**

**Permissões funcionais:** o catálogo candidato acrescenta seis direitos de requisição (`view`, `prepare`, `configure`, `approve.department_head`, `approve.procurement`, `approve.finance`) e os sete direitos do orçamento comum já desenvolvido. A criação de unidades continua a conceder apenas `unit.view`/`unit.edit`. Instalar o catálogo **não concede** nenhum novo direito a administradores, perfis de desenvolvimento ou outros utilizadores. A atribuição inicial nominativa e auditada exige âmbito habilitado explicitamente; as seguintes usam a administração nativa. Requerente e decisores continuam a exigir identidades distintas. A concessão de `purchasing_budget.record` é necessária para reserva/libertação, sem substituir a autorização de requisição.

**Privilégios PostgreSQL:** são outra camada. `sgf_dev_app` não deve receber CREATE, ownership ou a palavra-passe do proprietário. A execução de DDL exige a ligação de migração autorizada (`sgf_dev_owner` ou principal autorizado equivalente), só nessa execução e sem reescrever `.env` com credenciais privilegiadas. Depois, a aplicação precisa dos privilégios mínimos nas novas tabelas/sequências. **O instalador desta candidata não entrega esses GRANTs à role runtime**; as provas anteriores usaram role proprietária nas bases descartáveis. Falta fechar/ensaiar esse mapa com as duas roles separadas. O plano deve permitir leitura do registo de instalação, operações de requisição/política, append-only do histórico, reserva/auditoria e locks orçamentais necessários, sem UPDATE/DELETE sobre históricos ou grants genéricos sobre todo o schema. Nenhum GRANT é executado nesta análise.

## Bloqueantes e elementos fora do âmbito

| Questão | Classificação e impacto |
| --- | --- |
| Ligação de migração e privilégios SQL runtime | **Bloqueante para executar a instalação tal como está com a ligação normal.** A ligação actual não pode executar o DDL. Definir execução migradora e mapa mínimo de acesso a tabelas/sequências, preservar o runtime restrito e ensaiar a separação antes de aplicação. |
| Centros e dotações de orçamento em instalação vazia | **Bloqueante para disponibilizar o percurso básico neste destino.** Não existem `cb_*`; o formulário candidato só selecciona centros existentes e a configuração exige pelo menos um. Não há no percurso entregue cadastro/associação inicial de centros pela interface. Os ensaios prepararam essas fontes e a dotação aprovada por fixtures; não importar fixtures nem criar SQL manual como configuração comercial. |
| Interface orçamental SGF existente | **Bloqueante para a preparação operacional pela interface sem correcção.** `BudgetWorkspace` consulta `cb_ui_commands` e `cb_consumption_sources`, ausentes no destino e no schema de 14 tabelas. A reserva pelo motor comum foi ensaiada; isso não declara entregue o bootstrap administrativo/orçamental completo. Não ampliar consumo/facturas por arrasto: integrar o recorte necessário ou manter esse percurso fechado até completar a sua composição. |
| Catálogo administrativo de permissões | **Implementado e testado na candidata; ainda não instalado.** No destino, `Permissions::UNIT` continua só com dois direitos. Aplicar a sobreposição resolve a presença/gestão dos novos nomes; não resolve sozinho DCL PostgreSQL, centros/dotações ou atribuições nominativas. Não classificar como falta de implementação do catálogo nem como acessos já configurados. |
| Duas administrações nominativas | **Pendente para entrega/activação**, não condição para copiar código desactivado. O destino tem uma concessão `access.manage`; a regra da entrega exige duas administrações permanentes da empresa. Não criar conta/perfil ou outorgar direitos automaticamente para satisfazer a contagem. |
| Âmbito/configuração e dotação reais | **Pendente para activação:** seleccionar empresa/unidade, centros/fontes, intervenientes, política/limites, responsáveis e dotação aprovada pelas regras usuais. Não retirar a exigência de orçamento para contornar a falta de preparação. |
| Equipamentos/peças | **Fora do âmbito deste percurso básico.** Não impedem consumíveis, serviços e outros de completar requisição/submissão/aprovação/consulta quando as dependências acima estiverem preparadas. Equipamentos/peças não têm o seu percurso técnico SGF entregue; não os registar como `other` para contornar isso. |
| Navegação modular | **Tecnicamente aceite em 02/11/2026** na entrega própria. Não é bloqueante técnico da candidata. Revisão visual/recargas, associações antigas e volume/paginação mantêm o âmbito separado dessa aceitação. Não repetir as suites para resolver a instalação. |

## Backup, restauro e recuperação — procedimento proposto, não executado

1. **Antes de qualquer escrita aprovada:** reconferir raiz, URL/base/roles, hashes e estado dos ficheiros/contas/auditoria. Guardar o código/configuração anterior e documentos/ficheiros externos. Reservar directório privado por execução em `C:\laragon\data\sgf-tempo\backups\purchasing\<data-id>`, fora da raiz pública e sem sobrescrever backups anteriores. O backup de configuração pode conter segredos; não o distribuir com o ZIP.
2. **Backup integral apenas de `sgf_tempo_dev`:** PostgreSQL 17 `pg_dump --format=custom` com host `127.0.0.1`, porta `55432`, ligação autorizada e ficheiro privado. Registar hash, instante de corte, código/manifesto/schema, inventário das 87 tabelas e ACLs/roles pertinentes. Credenciais por mecanismo privado como PGPASSFILE; nunca nos argumentos/logs. Não parar o cluster inteiro nem exportar/substituir outras bases.
3. **Restauro para base nova vazia:** criar `sgf_tempo_dev_restore_<id>` pelo procedimento DBA autorizado, restaurar o dump e conferir dados, documentos externos, tabelas, constraints/triggers, ACLs, contagens/digests de acessos/pertenças/auditoria e arranque com roles distintas. Os ensaios anteriores provaram restauro isolado, mas **não substituem o ensaio desta base e dos seus privilégios**. `pg_restore --list` só lê o índice. Se usar `--no-owner --no-privileges`, repor/validar explicitamente as ownerships/ACLs, incluindo CONNECT/USAGE, antes de ligar o runtime. Não converter o runtime em proprietário para fazer o ensaio passar.
4. **Janela de aplicação, só depois dos bloqueantes e da confirmação:** manutenção, parar apenas serviços de escrita desse projecto; preparar schema pela ligação migradora; aplicar o mapa SQL aprovado; conferir preservação. Aplicar código e compilar caches pelas CLIs aprovadas, com destino/manifesto reconferidos. Não outorgar direitos funcionais, habilitar âmbitos ou abrir o módulo por arrasto. Reiniciar/conferir serviços próprios mantendo o acesso fechado até decisão de activação.
5. **Falha de schema antes do commit:** rollback transaccional e conferência com o inventário anterior. Se a ligação se perder durante o commit, inspeccionar revisão/schema antes de repetir. Não executar migrações `down` ou apagar histórico para forçar retry.
6. **Falha de código/aplicação parcial:** manter serviços parados/manutenção; `sgf-code-deploy.php rollback` para o ID devolvido/registado; conferir backups/hashes. A rotina repõe ficheiros/bundle anterior, recusa alterações locais e não reverte dados/schema/concessões. Depois de cache nativo recompilado, invalida-o; executar `cache` para a versão reposta, quando houver bundle anterior, e reiniciar/conferir antes de reabrir. Na primeira instalação, voltar ao host sem bundle não cria uma versão anterior de requisições. O ponteiro 0.1.1 continua preservado.
7. **Corrupção ou incompatibilidade de dados/schema:** preservar também o estado que falhou; restaurar para outra base, nunca por cima da base activa. Reconciliar operações posteriores ao backup, configurações e revogações para não perder decisões ou reabrir direitos. Só trocar a ligação da aplicação após conferência e decisão registada; uma base restaurada com outro nome requer nova impressão de destino operacional e caches recompilados. Conservar a base anterior para diagnóstico. Rollback de código não é restauro de dados.

Os comandos parametrizados e contratos das CLIs estão em [transferencia-sgf.md](PURCHASING_UPDATES_DELIVERY.md). **Não pedir confirmação para executar um procedimento ainda incompleto:** primeiro resolver os bloqueantes identificados, actualizar/ensaiar a candidata e apresentar os novos hashes se houver alteração. O ZIP actual permanece imutável e disponível como evidência, não aprovado para implantação operacional.


Actualiza??o de 02/11/2026: a proposta desactivada anterior foi substitu?da pela candidata utiliz?vel 401ce31ae5f2dd20, ainda N?O instalada. Fonte vinculativa actual: C:/laragon/www/sgf-tempo/docs/PURCHASING_INSTALLATION_PROPOSAL.md. Mant?m-se 0.1.1, aus?ncia de concess?es e decis?o posterior de instala??o/configura??o.