SGF/docs/MODULAR_NAVIGATION_DELIVERY.md

# Navegação modular SGF — implementação local, 01/11/2026

## Aceitação expressa e checkpoint exclusivamente local — 02/11/2026

O utilizador aceitou esta entrega técnica e autorizou o registo e um checkpoint Git local apenas deste incremento, sem credenciais, dados privados ou alterações alheias. A implementação já está preservada no histórico anterior; este checkpoint acrescenta a conferência, a precisão do âmbito e a aceitação, sem incorporar o trabalho paralelo de Compras.

O âmbito aceite compreende os seis módulos identificados abaixo, Início separado e configuração geral acessível em «Opções gerais», conforme as permissões. A aceitação considera a apresentação efectivamente entregue: não declara existente uma entrada única com o rótulo «Configuração», nem transforma as capacidades em preparação em operações concluídas.

Mantêm-se explicitamente pendentes: **revisão visual**, incluindo recarga das páginas autónomas e sem voltar à via de navegador bloqueada; **conferência humana das associações antigas**, que continuam sinalizadas e sem atribuição automática; **avaliação de volume e paginação** antes de implantação. A aceitação técnica não constitui aceitação visual, utilização real ou resolução dessas pendências.

O checkpoint é exclusivamente local. Não autoriza publicação, push, novas concessões públicas, novas operações reais ou activação de candidatas de Compras. O pacote instalado permanece **0.1.1**. As provas válidas anteriores são reutilizadas; não houve repetição de testes por este registo documental.

## Estado conferido em 02/11/2026

Identificação exacta confirmada no catálogo do servidor e na navegação: **Comercial (`commercial`), Compras (`purchasing`), Stock (`stock`), Oficinas (`workshop`), Financeiro (`finance`) e Contabilidade (`accounting`)**. Início e as opções gerais de configuração não são contados como módulos.

**Início** está nas opções gerais, separado da navegação do módulo, inclusive quando nenhum módulo foi seleccionado. A **configuração geral** também é independente do módulo activo: Empresa e Unidades são apresentadas com `company.view`; edição/criação e consulta de cada unidade mantêm os seus direitos próprios; Acessos e Associações de módulos exigem `access.manage`, além dos direitos específicos de cada operação. As rotas gerais mantêm autenticação/contexto de empresa e autorização no servidor, sem exigir selecção de módulo.

Precisão de apresentação: a interface actual chama a esta navegação **«Opções gerais»** e apresenta directamente Empresa, Unidades autorizadas, Associações de módulos e Acessos. **Não existe actualmente um botão ou submenu único com o rótulo «Configuração».** A Configuração documental permanece no módulo Comercial. Assim, está confirmada a separação funcional da configuração geral; uma entrada literalmente intitulada «Configuração» não pode ser declarada entregue sem ajuste de interface. Esta conferência não alterou o menu nem repetiu testes.

As duas frentes já estão concluídas: regressão integral da suite existente (**185 testes / 3 220 asserções**) e três perfis sintéticos de desenvolvimento configurados, com descoberta dos seis módulos e autoridade separada. A suite focada actualizada tinha sido aprovada com **8 testes / 90 asserções**. O isolamento por módulo, empresa e unidade e as recusas de acesso fazem parte das provas registadas na [conclusão técnica](MODULAR_NAVIGATION_COMPLETION.md).

A retoma comparou **184 ficheiros** de aplicação, configuração, rotas, recursos, testes e base com a cópia validada: não encontrou diferenças, além da normalização física de porta já documentada. Os hashes dos dois JUnit coincidem com os registados na entrega. Não foi necessário corrigir código, repetir testes, recriar a base ou provisionar perfis novamente.

As impressões digitais das concessões, pertenças e auditoria da instalação, a guarda original e o apontador instalado de Compras mantêm-se iguais às da conclusão. O pacote instalado permanece **0.1.1**, sem activação de candidata. A instância isolada `http://127.0.0.1:8039` respondeu à consulta HTTP de sessão com 200; não houve autenticação nova nem utilização de navegador nesta conferência.

Pendências que subsistem após a aceitação técnica expressa: [revisão visual separada](MODULAR_NAVIGATION_VISUAL_REVIEW.md), incluindo a recarga das páginas autónomas; conferência humana das associações antigas, que continuam sinalizadas e sem atribuição automática; avaliação de volume/paginação antes de implantação. Stock em preparação e guardas dos adaptadores de Compras continuam com os limites anteriores. Não há aceitação visual, publicação ou utilização real presumidas.

Evidência desta retoma: [conferência de 02/11/2026](proofs/modular-navigation-recheck-20261102.json). As secções seguintes preservam o relatório da implementação inicial e os seus estados históricos; a regressão e os perfis não são tarefas por concluir.

Actualização posterior: a regressão completa e os perfis de desenvolvimento isolados foram concluídos em [MODULAR_NAVIGATION_COMPLETION.md](MODULAR_NAVIGATION_COMPLETION.md). A [revisão visual](MODULAR_NAVIGATION_VISUAL_REVIEW.md) permanece separada. As pendências dessas duas frentes descritas abaixo correspondem ao estado da entrega inicial.

Implementada a selecção explícita do módulo na sessão existente, navegação própria e opções gerais separadas. A página inicial mantém o conteúdo limpo anterior. Não há aceitação visual presumida, publicação, checkpoint Git ou activação de candidatas de Compras.

## Navegação e autorização

- Módulos: Comercial, Compras, Stock, Oficinas, Financeiro e Contabilidade, a partir do inventário de navegação existente. Custos/orçamentos e recebimentos conservam os percursos anteriores no Financeiro; não foi criado outro motor.
- O selector permanece visível, incluindo nas opções gerais. A navegação secundária apresenta apenas as funcionalidades permitidas do módulo activo e os cadastros/rascunhos partilhados permitidos.
- Empresa, unidades, acessos e administração das associações são opções gerais. A administração das associações exige `access.manage` e os direitos originais de consulta; cada decisão exige também edição do registo.
- A disponibilidade de módulos é recalculada no servidor com os direitos actuais, empresa e unidade seleccionadas. Revogar direitos ou desactivar um módulo impede pedidos seguintes. Seleccionar um contexto não insere concessões.
- `config/modules.php` contém a composição instalada e restrições opcionais por `tenant:company` (`contracted` e `enabled`). Não foi encontrado um cadastro anterior de subscrições/contratação: esta política não declara implementado um serviço de licenciamento. Permanecem as guardas dos serviços e dos pacotes instalados.
- Os perfis de descoberta de desenvolvimento são explicitamente delimitados por `user:tenant:company` em `development_profiles`, apenas em `local`, `testing` e `browser-testing`. Podem apresentar os seis módulos; operações continuam a exigir os direitos próprios. A lista entregue está vazia: nenhuma pessoa/conta de cliente recebeu um perfil de desenvolvimento. Não foi inventado um papel de desenvolvimento a partir de nomes, emails ou administração do cliente.
- A continuação acrescentou configuração privada por ambiente e verificação da guarda de base isolada também para a descoberta; o produto continua sem perfis de cliente atribuídos por defeito.
- Um acesso directo a uma função de outro módulo exige mudança explícita de contexto. Ligações internas entre percursos fazem essa mudança pelo servidor, sujeita à protecção de alterações pendentes e nova autorização.

## Associação dos dados e isolamento

O levantamento confirmou `tenant_id`, `company_id` e, quando aplicável, `unit_id`. Não existe uma coluna genérica anterior de módulo em clientes, serviços ou rascunhos. Não se inferiu a associação a partir do autor, do nome, de uma data ou da ausência de outra origem.

| Registos | Associação utilizada |
| --- | --- |
| `a_clients`, `a_services`, `a_service_drafts`, `a_billing_drafts` | Eventos explícitos de associação no registo de auditoria imutável existente. |
| Novas criações desses quatro tipos por HTTP | Evento na mesma transacção da criação, com módulo activo, autor, empresa, unidade e versão. |
| Registos anteriores desses quatro tipos | Sem atribuição automática. Consulta administrativa geral, com os direitos originais, apresenta os registos e a pendência. |
| Facturas de teste e respectivo PDF | Associação do rascunho identificado por `si_invoices.draft_id`, além dos âmbitos e direitos originais. |
| Oficina e correcções, custos, obrigações e liquidações | Percurso nativo e relações existentes de ordem, geração, lote, documento ou obrigação; mantidas as fotografias e identidades de origem. |
| Empresa, unidade, configuração do emitente e instruções gerais | Âmbito geral de empresa/unidade existente; não foram copiadas para módulos. |
| Relatórios ainda em preparação | Continuam sem geração de dados ou exportações; não foram inventadas fontes. |

`ModuleRecords` aplica `WHERE EXISTS` às consultas dos quatro cadastros/rascunhos e à leitura das facturas. A filtragem não é apenas visual: leitura por ID, origens seleccionáveis, preparação documental, pré-visualização, histórico e consultas dos serviços usam a associação verificada. A API partilhada mantém as exigências originais de cada área/acção/unidade.

Os avisos da interface e `scope_notice` explicam que dados anteriores sem associação estão preservados e pendentes. A vista administrativa geral não é uma listagem operacional do módulo e não está disponível a leitores sem `access.manage`. O responsável precisa de consulta e edição próprias para decidir uma associação com motivo e versão exacta; uma versão entretanto alterada é recusada com 409.

Associar o rascunho não associa automaticamente o cliente, o catálogo ou a prestação de origem. Cada vínculo necessário tem de ser conferido explicitamente. Uma associação pode ser retirada por novo evento e posteriormente reposta; os eventos anteriores permanecem. O registo de negócio, a sua versão, fotografia, história e responsabilidade financeira não são reescritos nem duplicados.

Os bloqueios de duplicação, emissão já existente e dependências comerciais continuam a consultar as relações canónicas, mesmo quando uma dependência não é visível no módulo corrente. A filtragem de apresentação não liberta origens nem autoriza um segundo efeito.

## Mudança de contexto

- Empresa, unidade e módulo geram um token novo; os formulários e selecções anteriores são desmontados. Os pedidos API de leitura e escrita levam `X-SGF-Context`; pedidos de outra geração recebem 409. Respostas atrasadas são ignoradas na interface.
- Guardar, descartar ou cancelar é oferecido antes de sair de um editor alterado. Guardar usa a gravação já existente; falha, validação recusada ou novas alterações durante a gravação mantêm o contexto.
- Operações em curso impedem a mudança. Processos já submetidos conservam IDs, versões, origens e fotografias anteriores.
- Editores sem formulário submetível mantêm o contexto e pedem gravação explícita no próprio percurso. A detecção é conservadora e pode também sinalizar filtros/seleccionadores em secções sem formulário.
- As duas páginas autónomas de fornecedores recebem identificação do módulo e protecção de saída pelo invólucro SGF, sem editar o pacote partilhado. Com mais de um formulário autónomo alterado, pede-se gravação individual, porque os handlers originais recarregam a página após sucesso.
- Actualizar/fechar a página usa também a protecção nativa de saída do navegador. A navegação interna usa o diálogo de três opções, com teclado e foco delimitado.

## Provas efectuadas

- `php vendor/phpunit/phpunit/phpunit --filter ModuleNavigationTest`: **7 testes, 87 asserções**, aprovados.
- Casos: contexto explícito, acesso directo, token antigo, revogação, configuração da empresa, descoberta de desenvolvimento sem concessão operacional e sem efeito em produção, selecção recusada mantendo o contexto, auditoria sem token, isolamento entre empresas, associações/retirada/reposição, dados antigos não atribuídos automaticamente, versão desactualizada, gravação de prestação/rascunho e preservação do original/histórico/dependências.
- Base exclusiva de testes `sgf_tempo_test`, role `sgf_test_runner`, loopback 55432, com guarda existente. As novas provas usam transacções revertidas e identidades/empresas sintéticas com emails únicos; não usam `RefreshDatabase`, `migrate:fresh`, seeds ou reposição da demonstração. Sequências podem avançar com inserções revertidas; não são reiniciadas.
- `node scripts/module-navigation-check.mjs`: aprovado, incluindo separação dos módulos, módulo visível, gravação, falha, validação, descarte, editor sem submissão, remoção de formulários antigos e edição durante gravação.
- `npm.cmd run build`: inclui os testes de navegação anterior, os novos testes de módulos e a compilação Vite.
- Sintaxe PHP dos ficheiros alterados, sintaxe do invólucro JavaScript e `git diff --check`: aprovados.

A suite histórica completa não foi executada: vários testes antigos recriam a base e os clientes HTTP anteriores ainda não seleccionam módulo nem enviam token nas leituras. Não se declara essa regressão completa realizada. As provas acima cobrem o novo contrato e uma passagem real de cadastro → prestação → rascunho em transacção isolada.

## Migração, recuperação e limites

Não há migração SQL nova. As associações usam os eventos `module.record.associated` e `module.record.disassociated` em `identity_audit`, que já é append-only. Não foi alterada a estrutura, uma concessão, configuração nominativa, registo empresarial ou demo persistente por instalação deste incremento. O cluster PostgreSQL local existente foi iniciado para executar as provas.

Para corrigir uma associação, usar **Opções gerais → Associações de módulos**, seleccionar a operação de retirada ou associação, a versão apresentada e o fundamento. A recuperação acrescenta um evento e conserva o anterior; não apagar auditoria, origens ou documentos. Desactivar um módulo na política impede acesso futuro sem apagar dados. Não alterar a versão candidata/instalada de Compras para recuperar a navegação.

Para retirar esta implementação local, reverter apenas os ficheiros/hunks deste incremento e recompilar; não usar `git reset`/restauro global, pois já existiam alterações de Compras, pagamentos, reversões, rotas e provider antes deste trabalho. Conservar os eventos e dados existentes. Retirar as guardas modulares também retira esta camada de isolamento; não é um procedimento de publicação ou uma autorização de uso real.

Limites pendentes: revisão visual e interacção real no navegador, comportamento de recarga das páginas autónomas, regressão integral dos percursos anteriores, associação humana dos dados antigos e configuração explícita dos perfis de desenvolvimento. A consulta administrativa de associações ainda não tem paginação; a filtragem sobre auditoria deve ser avaliada com volumes de implantação antes de uso real. Não foi feito novo controlo de navegador nem atribuída aceitação à equipa.

Não houve publicação/push, alteração dos direitos da instalação pública, activação de Compras candidata, novas operações financeiras, remoção de guardas reais ou alteração de dependências.