compras/docs/desenvolvimento.md

Desenvolvimento do ProcuraFlow

Incremento actual de adjudicação e ordens de compra

Implementado em 28 de Outubro de 2026 no projecto Laravel existente, segundo a secção «Próximo incremento após RF-AF-01» das orientações. O RF-AF-01, os fornecedores e os documentos privados foram reutilizados e preservados. Não foram recriadas contas, executados seeds ou alterados o SGF Tempo, o Investmoz ou a configuração local.

Selecção e revalidação

• Procurement regista a adjudicação a partir da página de comparação de cotações. Exige justificação escrita e data/local de entrega. O solicitante não selecciona a sua própria compra; Administração consulta, sem substituir os perfis operacionais.
• ProposalComparison unifica a matriz da interface e a decisão no servidor. Recalcula preços, prazos e notas com aritmética racional; arredonda a pontuação final a duas casas decimais. Quantidades, preços e IVA são verificados em precisão decimal e centavos. Linhas devem corresponder à requisição, e os totais têm de conferir com as linhas. A entrega suporta apenas MZN.
• Requer três fornecedores distintos com propostas elegíveis, válidas e comparáveis; cada proposta elegível precisa de duas avaliações elegíveis. Os avaliadores têm de continuar na mesma empresa e num perfil operacional permitido, respeitar o departamento quando são chefes, ser distintos e não ser o solicitante. Uma declaração de ausência não substitui a verificação de conflitos.
• Escolha limitada ao topo da pontuação. Empates permitem seleccionar uma das propostas empatadas, sempre com fundamento escrito. Dispensa de cotações, escolha abaixo do topo e outros caminhos de excepção permanecem bloqueados sem política aprovada; parâmetros enviados pelo navegador não dispensam estas regras.
• Cada operação decisiva revalida o ConflictGuard, incluindo solicitante, aprovadores, autores de cotações, avaliadores e agora autor/aprovadores da adjudicação. Novas declarações continuam a bloquear operações sem apagar o histórico.
• A selecção fecha o registo de novas propostas e avaliações desse processo. A matriz de decisão e a sua impressão digital são guardadas. Alterações aos valores, avaliações, ponderações ou elegibilidade da matriz impedem a utilização das aprovações para emitir sobre uma base diferente.

Escalões e ciclo de aprovação do valor final

• Os limites e a base com/sem IVA vêm do snapshot guardado na requisição; não se substituem pela configuração actual da empresa. Processos sem snapshot válido ou histórico completo de aprovação da estimativa são bloqueados.
• A adjudicação abre explicitamente um novo ciclo de aprovações para o valor final, mesmo quando fica no mesmo escalão. As decisões da estimativa são preservadas e não são reaproveitadas. O topo do primeiro escalão é inclusivo, tal como o segundo; ultrapassagens acrescentam Procurement e Finanças, conforme as regras guardadas.
• As etapas são sequenciais. Solicitante e autor da adjudicação não aprovam o ciclo; cada etapa é decidida por uma pessoa distinta. A rejeição exige fundamento. Antes de emitir, verifica-se novamente se os aprovadores finais continuam elegíveis e sem conflito.
• Equipamento e peças com tipos ainda não suportados são bloqueados, sem presumir aprovação técnica ou limites próprios. Não existem excepções automáticas para urgência, fornecedor único ou valores acima de limites sem política definida.

Ordem emitida e consulta

• Ordem única por requisição e adjudicação, com referências OC-ANO-ID, transacção e unicidade na base de dados. Repetir a emissão devolve a ordem existente sem novas linhas, novo número, nova auditoria ou alteração dos dados congelados. Podem existir intervalos na sequência de identificadores.
• A ordem congela na emissão linhas, quantidades/unidades, preços, IVA, totais, moeda, fornecedor/contactos, empresa, departamento, centro de custo, referência/condições da proposta, entrega, fundamento, emitente, matriz revalidada e aprovações. A matriz guardada na adjudicação continua separada como histórico da escolha. Alterações posteriores às fichas e propostas não reescrevem a ordem.
• Listagem, detalhe, emitente, histórico e versão HTML para impressão ou gravação em PDF pelo navegador. A impressão escapa o conteúdo fornecido pelos utilizadores. Não há geração de PDF no servidor ou envio por email.
• Administração, Procurement e Finanças consultam na própria empresa; chefes apenas processos do seu departamento. Solicitantes e armazém não recebem acesso aos documentos financeiros nesta etapa.
• Todas as ordens exibem Documento de desenvolvimento. Não autoriza compras reais. O snapshot guarda development_only=true e budget_checked=false. O orçamento ainda não é verificado, tanto na interface como na impressão. Não foram criadas ordens reais neste incremento.
• Falhar a auditoria reverte a adjudicação e as suas etapas, ou a emissão e as suas linhas. Os modelos das ordens e linhas impedem edição/eliminação; a protecção contra SQL administrativo continua dependente das permissões operacionais.

Verificação e preservação

• Suite completa Laravel: 165 passaram, 3 ignorados, 1.662 asserções. Os 46 testes específicos de adjudicação/ordens passaram; a suite inclui também os testes anteriores de RF-AF-01/fornecedores/anexos e os três testes de pré-visualização pública acrescentados em paralelo. Os testes usam SQLite em memória, não a base de negócio.
• Cobertura: acesso por perfil e departamento; isolamento de empresas; valores/IVA e quantidades fraccionárias; fronteiras de 25.000 e 150.000 MZN; base com/sem IVA guardada; novo ciclo de aprovação; empates; excepções bloqueadas; conflitos/suspensão/expiração após avaliação ou selecção; elegibilidade de avaliadores/aprovadores; integridade das linhas; prevenção de repetição com unicidade/idempotência; snapshots; impressão com escape de HTML; rollback se falhar a auditoria.
• PHPStan aprovado, sem erros; Pint aprovado em todos os ficheiros PHP; verificação frontend sem avisos ou erros; TypeScript aprovado; compilação aprovada; git diff --check sem erros.
• Migração aditiva 2026_10_28_000005_create_purchase_awards_and_orders aplicada no PostgreSQL local após os testes. Contagens antes/depois iguais: 1 utilizador, 1 empresa e 0 requisições, fornecedores, cotações, avaliações, documentos e declarações de conflito. Novas tabelas de adjudicações, aprovações finais, ordens e linhas vazias. Não foram criados registos sintéticos na base real.
• O SHA-256 do .env manteve-se igual antes e depois. Não houve seeds, alterações de credenciais ou configuração, nem reinicialização de dados.
• As rotas de ordens/adjudicação estão registadas. O acesso sem autenticação a /ordens redireccionou para a entrada ProcuraFlow em 8015, com HTTP 200. As páginas autenticadas e o conteúdo da impressão foram verificados em testes HTTP/Inertia, não visualmente.

Foram detectadas alterações paralelas na pré-visualização pública, na entrada e nas respectivas rotas/testes; foram preservadas e incluídas na verificação final, sem as apresentar como parte desta implementação. As alterações funcionais deste incremento permanecem limitadas à adjudicação/ordens e à integração necessária com os módulos anteriores.

Limitações e próximo passo

Revisão visual autenticada, revisão visual da impressão/PDF e concorrência real em PostgreSQL continuam pendentes. Não foram realizados testes de carga. O código usa bloqueio por empresa e bloqueios dos registos de comparação/fornecedores/utilizadores dentro da transacção; isso não constitui validação de concorrência real.

Ainda não existe cancelamento/reabertura de adjudicações, alteração da data de entrega depois da selecção ou substituição de uma ordem emitida. Se a base aprovada mudar, faltar elegibilidade ou a data de entrega passar, o sistema impede a emissão; não assume uma autorização de correcção. As políticas e o fluxo de revisão/cancelamento devem ser definidos antes de ampliar esses caminhos.

Permanecem pendentes orçamento, multimoeda, dados bancários com dupla validação, aprovações técnicas de equipamentos/peças e as políticas comerciais em aberto. Próximo incremento: recepção parcial e conferência de qualidade com segregação do emitente, seguido de equipamentos, peças e stock. Não avançar para compras ou pagamentos reais.

Ficheiros deste incremento

Migração 2026_10_28_000005; modelos PurchaseAward, PurchaseAwardApproval, PurchaseOrder, PurchaseOrderItem e trait de imutabilidade; serviços ProposalComparison e PurchaseWorkflow; controlador PurchaseController; integração em ConflictGuard e QuotationController; casts decimais de QuotationItem e ProposalEvaluation; rotas autenticadas e menu; tipos purchase.ts, páginas purchases/award, purchases/index, purchases/show, ligação da comparação e vista purchases/print.blade.php; testes PurchaseAwardOrderTest; documentação.

Entrega anterior RF-AF-01

Os registos abaixo conservam os resultados anteriores. A indicação de adjudicação e ordens como próximo passo nessas entregas fica substituída pelo incremento acima.

Incremento actual RF-AF-01 de 28 de Outubro de 2026

Implementado

Declarações pessoais de conflito de interesses na base Laravel e React existente, sem avançar para adjudicação ou ordens. Fornecedores, anexos privados, contas e configuração anteriores foram preservados. O SGF Tempo e o Investmoz não foram alterados.

• Interface em português em Conflitos de interesses, disponível para todos os perfis com empresa configurada. Cada utilizador declara exclusivamente em nome próprio. O servidor fixa autor, empresa e data/hora do registo.
• Âmbitos: fornecedor em todos os processos; processo independentemente do fornecedor; fornecedor num processo específico. São guardados fundamento, data de conhecimento da situação e data/hora de cada declaração ou correcção.
• Administração e Finanças consultam as declarações da sua empresa para controlo. Procurement, chefes, solicitantes e armazém consultam apenas as próprias. Nenhum perfil altera declarações alheias. As opções de fornecedores mostram só identificador e nome; as opções de processos respeitam a visibilidade do perfil e departamento.
• As correcções pessoais acrescentam um registo ligado ao anterior e à declaração inicial. Só corrigem fundamento e data de conhecimento; autor, empresa, âmbito e situação declarada não são alteráveis. Correcções de uma versão já corrigida são recusadas. O histórico completo é consultável e gera auditoria com antes/depois.
• Uma declaração de ausência não anula uma declaração de conflito, mesmo posterior ou noutro âmbito sobreposto. Não há caducidade, prazo anual ou autorização para retirada implementados. A data de conhecimento é descritiva e não adia o impedimento. Periodicidade, validade e levantamento dependem de decisão da empresa, sem valores presumidos.

Impedimentos no servidor

• A requisição sem fornecedor continua a poder ser criada, editada, submetida e aprovada quando há apenas conflito com um fornecedor ainda não associado. Um conflito pessoal específico do processo, já conhecido, impede a participação nesse processo.
• Ao associar um fornecedor através de uma cotação, o servidor verifica o operador actual, solicitante, aprovadores anteriores, autores de propostas, avaliadores anteriores e autores de acções de participação no histórico de auditoria. As verificações usam os utilizadores históricos, independentemente do perfil actual. O registo da própria declaração não é tratado como participação em compras.
• Reedição/submissão de requisições, decisões de aprovação, registo de cotações e avaliações verificam novamente os conflitos dos intervenientes e dos fornecedores já associados. O campo de ausência de conflito de uma operação não permite contornar os impedimentos.
• Conflitos registados depois de uma avaliação conservam as cotações, avaliações, aprovações e auditoria anteriores. A elegibilidade e a pontuação são recalculadas na comparação; propostas afectadas deixam de contar como elegíveis, e novas operações afectadas ficam impedidas. Não há alteração retroactiva dos estados ou eliminação de decisões históricas.
• Escritas de declarações, correcções e operações de participação começam por bloquear a empresa na transacção, antes dos bloqueios do processo/fornecedor. Esta protecção abrangente serializa estas escritas por empresa; o efeito real na concorrência e desempenho ainda não foi testado. Leituras da interface não constituem autorização para uma futura adjudicação: essa operação terá de verificar novamente os impedimentos dentro da sua transacção.
• Declarações e correcções falham integralmente se falhar a auditoria. O modelo impede edição destrutiva e eliminação; a protecção contra SQL directo ou administração da base de dados continua dependente de permissões operacionais adequadas.

Verificações realizadas

• Laravel/Pest: 116 passaram, 3 ignorados, 808 asserções. Inclui os testes anteriores de fornecedores e anexos e novos cenários de autoria, seis perfis, visibilidade, isolamento, correcções imutáveis, versões antigas, âmbitos, ausência sem poder de anulação, datas sem caducidade, fornecedor desconhecido, intervenientes anteriores, alterações após avaliação, bloqueios por pedidos directos, auditoria e rollback.
• PHPStan aprovado, sem erros; Pint aprovado; verificação frontend sem avisos ou erros; TypeScript aprovado; compilação aprovada; git diff --check sem erros. Os testes usam SQLite em memória, não a base de negócio.
• Migração aditiva 2026_10_28_000004_create_conflict_declarations aplicada no PostgreSQL local depois dos testes. Contagens antes/depois preservadas: 1 utilizador, 1 empresa e 0 requisições, fornecedores, cotações, avaliações e documentos. A nova tabela está vazia; não foram criadas declarações sintéticas na base real.
• O SHA-256 do .env permaneceu igual antes e depois. Não houve seeds, recriação de contas, alteração de credenciais, reinicialização de dados ou mudanças de configuração.
• As quatro rotas de conflitos estão registadas. O acesso HTTP sem sessão a /conflitos redireccionou para a entrada ProcuraFlow na porta 8015, que respondeu HTTP 200. Isto não constitui revisão visual autenticada.

Pendências e próximo passo

Continuam pendentes a revisão visual autenticada e os testes de concorrência real em PostgreSQL. Não foram realizados nem apresentados como aprovados. Também não foram testados carga ou desempenho dos bloqueios por empresa.

A política de periodicidade/validade das declarações e o procedimento autorizado para levantar ou tratar conflitos permanecem por decidir. Não há retirada de conflitos nem declarações em nome de terceiros. A entrega cobre os âmbitos e impedimentos nas operações actualmente existentes; não representa certificação integral do sistema.

Próximo incremento: adjudicação e ordens de compra, reutilizando ConflictGuard para verificar novamente todos os intervenientes e o fornecedor antes de seleccionar ou emitir, além das três cotações, avaliações independentes e escalões aplicáveis. Dados bancários com dupla validação continuam pendentes. Não avançar com políticas ou excepções comerciais ainda não definidas.

Ficheiros do RF-AF-01

Migração 2026_10_28_000004; modelo ConflictDeclaration; controlador ConflictDeclarationController; serviço ConflictGuard; integração em RequisitionWorkflow, Requisition, RequisitionController e QuotationController; rotas e menu; tipos conflict.ts, páginas conflicts/index e conflicts/show e avisos nas páginas de requisição/cotações; testes ConflictDeclarationTest; documentação de desenvolvimento e README.

Entrega anterior de fornecedores e anexos

O registo abaixo conserva o estado e os resultados da entrega anterior. As referências a declarações de conflito como próximo passo dizem respeito a essa entrega e são substituídas pelo incremento RF-AF-01 acima.

Incremento de 28 de Outubro de 2026

Edição e renovação de fornecedores e documentos privados, na base Laravel e React existente. As orientações de continuidade foram lidas nesta sessão. A inspecção inicial confirmou cadastro, validação e cotações já implementados; os novos recursos de edição e documentos ainda estavam ausentes. Não houve passagem para outro chat nem criação de outro projecto.

Implementação

• Procurement pode editar a ficha e renovar a data da próxima revisão. Os campos são validados no servidor, incluindo NUIT único por empresa. Campos de propriedade, validação e estado enviados pelo navegador não são aceites.
• Alterações efectivas devolvem o fornecedor a pendente, limpam a validação actual e registam o antes e depois na auditoria. Gravações sem alterações preservam a validação. As cotações existentes permanecem guardadas; a elegibilidade depende do estado actual do fornecedor.
• Cada ficha tem versão. Edições e decisões de Finanças com uma versão antiga são recusadas. O criador e o último utilizador que alterou a ficha ou enviou documentos não podem validar o próprio trabalho, mesmo após mudança de perfil.
• PDF, JPEG e PNG, entre 1 KB e 2 MB por ficheiro. O limite respeita o upload_max_filesize=2M do PHP local, sem alterar configuração global ou .env. O servidor verifica MIME, extensão e tamanho.
• Documentos em disco dedicado supplier_documents, fora de public e fora do disco local com URLs assinadas. Caminhos internos não são enviados para a interface. Downloads autenticados e autorizados por empresa e perfil, com validação da ligação ao fornecedor, sem visualização inline e sem cache partilhada.
• Apenas Procurement envia documentos. Administração, Procurement e Finanças da mesma empresa podem descarregar. Chefes consultam a ficha sem metadados ou downloads dos documentos; solicitantes e armazém não acedem à ficha.
• Envios e downloads geram auditoria. Novos documentos invalidam a validação do fornecedor; os anteriores são preservados. Falhas da transacção removem o ficheiro recém-enviado e revertem os metadados e o estado.

Ficheiros deste incremento

Migração 2026_10_28_000003_add_supplier_maintenance_and_documents; SupplierController, SupplierDocumentController, SaveSupplierRequest, SupplierPolicy, modelos Supplier e SupplierDocument; disco em config/filesystems.php; rotas de fornecedores; tipos supplier.ts e páginas suppliers/index, suppliers/edit e suppliers/show; testes SupplierMaintenanceTest e adaptação da versão em SupplierQuotationTest.

Verificação concluída

• Testes Laravel: 74 passaram, 3 ignorados, 447 asserções. Cobrem edição, versões antigas, renovação, validação independente, MIME/extensão/tamanho, permissões, isolamento entre empresas, ligação documento/fornecedor, downloads auditados e reversão quando falha a auditoria.
• PHPStan sem erros; Pint aprovado; verificação frontend sem avisos ou erros; TypeScript e compilação aprovados; git diff --check sem erros.
• Migração aditiva 2026_10_28_000003 aplicada no PostgreSQL local depois dos testes. Contagens anteriores e posteriores iguais: 1 utilizador, 1 empresa, 0 requisições, 0 fornecedores, 0 cotações e 0 avaliações; nova tabela de documentos vazia. Não foram executados seeds, criadas contas ou alteradas credenciais/configuração.
• Entrada em http://127.0.0.1:8015/login confirmada com HTTP 200 e identificação ProcuraFlow; oito rotas de fornecedores registadas. As páginas autenticadas e as permissões foram verificadas nos testes Inertia; não foi feita inspecção visual autenticada no navegador.

As verificações funcionais usam SQLite em memória e armazenamento simulado, sem ficheiros ou registos de teste na base real. A migração é a única escrita realizada na base real neste incremento.

Limitações e próximo passo

Não há eliminação/substituição de documentos, antivírus, quotas acumuladas ou política de retenção nesta entrega. O hash SHA-256 é registado na recepção; não constitui assinatura digital ou análise antivírus. A revisão visual autenticada depende da sessão existente; não pedir nem redefinir a palavra-passe para testar. Concorrência real em PostgreSQL requer testes com ligações simultâneas, além dos testes de versões e transacções.

Continuam pendentes dados bancários com dupla validação e cadastro de declarações de conflito; não considerar a ficha ou a diligência devida como conformidade integral com RF-AF-01, RF-AF-05 ou RF-AF-06. Próximo passo: declarações de conflito e, depois, adjudicação e ordens, mantendo os controlos e decisões provisórias descritos na especificação. Conta, credenciais, configuração e dados existentes devem continuar preservados.