compras/docs/desenvolvimento.md

Desenvolvimento do ProcuraFlow

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.