SGF/docs/PURCHASING_COMMON_CORE_PLAN.md

Compras e núcleo financeiro comum — desenho e transição

Actualização de execução, 29/10/2026: primeiro incremento implementado e tecnicamente demonstrado em hosts sintéticos, conforme entrega e limites. A marcação de desenho/não executado abaixo conserva o estado da proposta original. Não há aceitação, implantação ou extracção integral de Compras presumidas; T2 e seguintes não foram iniciados.

29/10/2026. Estado: desenho técnico revisto e primeiro incremento delimitado; reestruturação e provas ainda não executadas. Referência principal para os dois projectos. Não substitui as matrizes de requisitos ou as aceitações existentes.

1. Decisão expressa e alcance

Decisão da Tempo: um módulo de Compras, um núcleo financeiro comum e duas composições comerciais. O ERP SGF inclui Compras. A composição Compras autónomo inclui as capacidades comuns necessárias, sem exigir a facturação de vendas SGF nem um SGF remoto. Os percursos entregues são preservados. Esta orientação substitui a proposta anterior de duas aplicações ligadas por conector remoto como arquitectura principal.

Desenvolvimento e validação usam organizações, unidades, contas e operações sintéticas; pessoas reais e concessões na Tempo pertencem à implantação. As configurações, dados, aprovações e alterações posteriores dos dois projectos mantêm-se. Nesta passagem alterou-se apenas documentação; não se leram credenciais, executaram bases/testes ou alteraram dependências.

Origem das restrições: composição comercial, núcleo único, preservação e uso sintético são decisões expressas da Tempo. Organização em pacotes, transacção local, contratos e sequência abaixo são propostas de implementação. Regras empresariais continuam a ser as aprovadas e versionadas, não políticas universais criadas pela modularização.

2. Duas composições, a mesma implementação

Componente	ERP SGF	Compras autónomo
Plataforma comum: identidade, empresa fiscal/unidade, autorizações, auditoria e comandos	Incluída	Incluída na extensão necessária ao produto
Núcleo financeiro comum e suas migrações	Uma implementação local	A mesma implementação local/versionada
Módulo de Compras e seus percursos	Incluído	Incluído
Facturação de vendas, oficinas, produção e outros módulos ERP	Conforme composição	Não obrigatórios para instalar, entrar, comprar ou pagar fornecedores
Comunicação entre Compras e financeiro	Interfaces de aplicação no mesmo processo	As mesmas interfaces no mesmo processo

Autonomia é autonomia de instalação e utilização, não outra cópia das regras. As duas instalações de clientes diferentes têm naturalmente os seus próprios dados; não se pretende sincronizar automaticamente essas instalações. Integração com facturação externa poderá ser opcional e contratada separadamente, nunca condição para usar Compras.

Proposta de estrutura lógica: Platform (contexto/acesso/auditoria), Finance (capacidades financeiras comuns), Inventory (movimentos físicos comuns), Purchasing (procurement), Sales e restantes módulos SGF. Stock físico não é contabilidade geral; ambos têm responsáveis definidos. As dependências apontam de Purchasing/Sales para contratos comuns, sem Finance depender dos controladores ou tabelas de vendas.

Os nomes e o formato físico dos pacotes são escolhas técnicas. A fonte de cada módulo deve ser única, com namespace próprio, versão e testes. Não copiar App/Services de Compras para outro App/Modules e continuar a manter ambos. Durante a transição, fachadas antigas delegam para o serviço extraído; não executam também a lógica antiga. Distribuir os mesmos artefactos em duas composições, sem exigir caminhos relativos entre repositórios no cliente.

No modo instalado, preferir uma ligação transaccional local para documento, efeito e auditoria quando pertencem à mesma operação. Separar propriedade das tabelas por módulo não exige bases separadas. Não unir agora as bases existentes, tabelas users/tenants, identificadores, históricos ou sessões. A estratégia exacta de schema será demonstrada em instalação sintética antes de qualquer migração de cliente.

3. Percursos de Compras a preservar

Referências relativas a C:/laragon/www/compras. As provas anteriores são reutilizadas; acrescentar verificações apenas do delta. Estado de implementação não equivale a autorização operacional real.

Percurso preservado	Implementação de referência	Preservação na composição SGF/autónoma
Empresa/equipa, departamentos e centros	app/Http/Controllers/CompanyController.php; app/Enums/PurchasingRole.php	Adaptar contexto e acesso sem alargar poderes; manter utilizadores e direitos históricos
Planeamento e marcos ligados à requisição	app/Services/PurchasePlanningWorkflow.php	Manter versões, responsáveis e ausência de reserva pelo simples planeamento
Requisição, linhas e aprovações sequenciais	app/Services/RequisitionWorkflow.php	Manter autoria, limites/base congelados, decisões distintas, exactidão e histórico
Fornecedor, documentos e dados bancários	SupplierBankWorkflow.php; controladores SupplierController.php/SupplierDocumentController.php	Preservar revisões, dupla validação bancária, cifragem e documentos privados
Cotações, matriz e conflitos	ProposalComparison.php; ConflictGuard.php; QuotationController.php	Mesmos critérios e elegibilidade; não reutilizar direitos de vendas
Abertura, qualificação, admissão e recomendação	ProposalOpeningWorkflow.php; DocumentaryQualificationWorkflow.php; FormalAdmission.php; FormalRecommendation.php	Preservar adopções opcionais, políticas por versão, bases, quóruns e decisões
Adjudicação, aprovação final e ordem	PurchaseWorkflow.php; InvestmentWorkflow.php	Manter nova aprovação do valor final, ordem única, snapshots e requisitos de investimento
Revisão/cancelamento antes de ordem	PurchaseControlPolicyWorkflow.php; PurchaseRevisionWorkflow.php	Preservar limites, libertação única e novo rascunho sem herdar decisões; não alargar a ordens emitidas
Recepção, qualidade e aceitação parcial	ReceiptWorkflow.php	Mesmas quantidades aceites, segregação, guia e origem única do movimento físico
Stock, equipamentos e peças	StockWorkflow.php; EquipmentWorkflow.php	Manter armazéns, saldos, saídas, transferências, contagens, ajustes e rastreabilidade
Dotação, reforço, reserva e compromisso	BudgetWorkflow.php; BudgetReinforcementWorkflow.php	Extrair a capacidade financeira existente; não criar orçamento paralelo no SGF
Factura recebida e conferência	InvoiceWorkflow.php	Preservar preço/unidade/IVA da ordem, aceitação física e facturação parcial cumulativa
Pagamento externo e conferência	ExternalPaymentWorkflow.php	Manter saldo, versão bancária e confirmação independente; não executar transferências
Processo único, auditoria e impressão	PurchaseProcessController.php; ProcurementReviewReport.php; routes/web.php	Conservar documentos e leitura histórica, com navegação adaptável às duas composições

Os serviços sem caminho completo nesta tabela ficam em app/Services; os controladores ficam em app/Http/Controllers. docs/validacao-tecnica.md já descreve recomendação/migração 000020; resumos ainda referidos a 000017 são anteriores, não indício de perda. Não reabrir a aceitação dos incrementos conservados nem declarar executadas novas provas a partir desses relatórios.

4. Capacidades comuns e um responsável por efeito

Responsável significa o módulo/serviço que valida e grava o efeito, não uma pessoa real. Um documento pode originar efeitos diferentes, cada um com identidade e responsável próprios; não deve provocar duas gravações do mesmo efeito.

Capacidade/efeito	Existente e origem	Falta desenvolver/adaptar	Único responsável de destino
Contexto empresarial e autorização	SGF: CompanyContext, Permissions, memberships/unidades. Compras: tenant=empresa, perfil/departamento e CurrentActor	Contrato comum e adaptação dos perfis; unidade não equivale a departamento/armazém	Platform; Purchasing conserva a elegibilidade e segregação do seu processo
Montantes e quantidades	Compras: centavos, milésimos e HalfUp; SGF: decimais exactos/racionais e política própria de IVA de serviços	Tipos/contratos com moeda, escala, unidade e política explícitas; sem uniformizar resultados históricos	Política de cálculo identificada por domínio/versão; Finance valida representação dos efeitos monetários
Dotação e reforço	Compras: Budget, BudgetReinforcement, aprovações e histórico	Extrair reutilizando regras existentes e generalizar origem sem perder controlos	Finance/BudgetControl
Reserva, ajuste na adjudicação, compromisso, libertação permitida e consumo	Compras: BudgetWorkflow, InvoiceWorkflow, budget_entries, budget_consumptions	Unificar todos os escritores desses efeitos, idempotência por origem e transacção local	Finance/BudgetControl; Purchasing pede o efeito e valida o processo
Orçamento industrial previsto/realizado	SGF: app/Modules/Industry/IndustrialBudgets.php, simulação aceite	Articular dimensões futuras; não substituir controlo de disponibilidade por comparação de custo	Industry/CostPlanning; não é outro escritor do ledger de dotações
Factura recebida e obrigação a fornecedor	Compras: registo e conferência em InvoiceWorkflow	Serviço comum de contas a pagar, vencimentos/condições e correcções; preservar documento de origem	Purchasing confere factura; Finance/Payables grava a obrigação uma vez
Pagamento e afectação à obrigação	Compras: registo/conferência externo em ExternalPaymentWorkflow	Extrair mecanismo para Finance/Treasury/Payables; execução bancária e conciliação completa não demonstradas	Finance; Purchasing recebe estado/consulta e não liquida de novo
Facturação de vendas e recebimentos	SGF: ServiceInvoicing, ServiceReceivables, emissão/recebimentos delimitados de teste	Interfaces financeiras comuns futuras; contas a receber não substituem contas a pagar	Sales conserva documento; Finance a receber/tesouraria quando extraído; nenhuma dependência comercial obrigatória em Compras
Quantidade física e saldo por armazém	Compras: ReceiptWorkflow, StockWorkflow, StockMovement	Extrair Inventory comum e delegar entradas/saídas de todos os consumidores; não presumir método de valorização	Inventory, invocado uma vez por origem; Purchasing aceita recepção e Workshop declara consumo
Custo directo/industrial	SGF: DirectCosts, IndustrialCosts e ExactCostMath, actualmente sintéticos	Ligar movimentos e taxas identificados, sem repetir consumo físico ou custo	Serviços de custos comuns/Industry conforme natureza; Inventory continua dono da quantidade
Classificação e conhecimento fiscal	SGF: CatalogueAccounting, ServiceFiscal; requisitos FIS-SGF-13 a 19	Completar consumidor de compras e vigência/dedutibilidade; reutilizar conhecimento aceite	Finance/TaxAccounting, com regra e período explícitos; taxa da cotação não confirma dedutibilidade
Lançamento, razão, fecho e modelos	SGF: âmbito descrito em SERVICE_INVOICE_CALCULATION_SPEC.md, não motor geral concluído	Construir capacidades e ligações em falta com origem/versão e correcções	Finance/GeneralLedger e Finance/TaxReporting; nenhum lançamento implícito na migração/importação
Auditoria e repetição de comandos	Ambos: histórico, transacções, chaves/hash em percursos específicos	Contrato de comando/origem e correlação comuns; preservar protecções existentes	Platform regista auditoria; cada serviço mantém unicidade do seu efeito na mesma transacção

Um núcleo financeiro comum não significa que todas as suas capacidades já existam no SGF. Parte será formada por extracção do código de Compras; parte pelas capacidades SGF já demonstradas; parte terá de ser desenvolvida. Receber factura não é emitir factura de vendas. Compromisso orçamental, obrigação, pagamento, movimento físico e lançamento são efeitos distintos.

5. Dependências e compatibilidade antes da extracção

1. Ambos usam Laravel 13, mas composer.lock difere: Compras Laravel 13.39.0/Brick Math 1.0.0; SGF Laravel 13.38.0/Brick Math 0.14.8. Escolher uma combinação suportada para o pacote no ensaio sintético; não actualizar manifests/lockfiles dos clientes automaticamente. Dependência incompatível é um problema concreto de implementação, não motivo para duplicar o motor.
2. Compras usa Inertia/TypeScript; SGF usa React/JSX e JSON de sessão. Primeiro separar aplicação/domínio da apresentação. Preservar ecrãs Compras, permitindo layouts diferentes; não reescrever todo o frontend para demonstrar o primeiro efeito partilhado.
3. BelongsToTenant e CurrentActor de Compras dependem de auth(); SGF usa selecção empresa/unidade e token de contexto. Definir actor/contexto explícitos e adaptadores locais revalidáveis. Não desactivar filtros ou conceder poderes globais para acomodar o pacote.
4. Um utilizador Compras tem actualmente um tenant/perfil/departamento; o SGF permite memberships e concessões. Definir correspondência sem usar email, nome ou igualdade de IDs como autoridade. Conta multiempresa e eventual evolução do modelo Compras exigem testes específicos; a extracção inicial pode limitar o cenário sintético a uma empresa/unidade, declarando a cobertura.
5. Não reaproveitar os nomes tenants/users para fundir tabelas automaticamente. Namespace próprio e uma migração proprietária de cada tabela; manter referências de origem e regras de acesso. Não juntar histórias de migrações ou copiar schemas de clientes para o novo ensaio.
6. As tabelas outbox SGF capturadas/sintéticas não são um serviço financeiro executável. Chamadas locais são suficientes para a primeira composição; não introduzir conector remoto, broker ou transacção distribuída como dependência.

6. Transição gradual

Passo	Resultado	Preservação / condição de passagem
T0 — este desenho	Percursos, efeitos, responsáveis e primeiro incremento delimitados	Documentação apenas; nenhuma aceitação funcional nova
T1 — controlo orçamental comum	Um serviço, contratos locais e dois hosts sintéticos exercitam o mesmo pacote	Paridade das regras/resultados existentes; todos os escritores do ledger delimitado passam pela mesma implementação
T2 — factura recebida e contas a pagar	Documento conferido origina uma obrigação comum; ecrãs/decisões Compras conservados	Sem emissão de venda obrigatória; consumo orçamental não repetido; correcções no âmbito implementado
T3 — pagamentos comuns	Extrair registo, conferência e afectação externa existentes; ligar obrigação	Um pagamento/afectação por origem; sem execução bancária presumida; preservar validação bancária
T4 — inventário e custos	Extrair movimentos físicos existentes e ligar consumidores SGF	Uma origem física, um movimento; valorizações e regras de custo explícitas
T5 — contabilidade/fiscalidade e composições completas	Completar consumidores, modelos e empacotamento das duas instalações	Conformidade/implantação por capacidade e cliente; sem obrigar a facturação de vendas

A ordem é incremental e pode ser ajustada por dependências demonstradas. Enquanto uma capacidade não foi extraída, mantém-se o seu escritor actual. Quando passar ao módulo comum, a fachada antiga apenas delega. Não manter dois fornecedores seleccionáveis para a mesma capacidade nas duas composições finais, nem comparar em paralelo gravando duas vezes. Comparações de paridade usam rollback ou leitura sem efeitos.

Dados históricos não são executados de novo como comandos. A transição de um cliente exige inventário de código/schema/dados/permissões equivalentes, backup/restauro e migração aditiva ensaiada. Preservar identificadores públicos/documentos/snapshots ou manter correspondência imutável, sem usar a extracção para recalcular IVA ou reaprovar processos concluídos. Reversão da versão de código não pode apagar efeitos ou deixar dois escritores activos; planear compatibilidade e recuperação antes de qualquer aplicação real.

7. Primeiro incremento delimitado — COMMON-BUDGET-SYNTHETIC-v1

Objectivo: demonstrar, em dois hosts de instalação sintéticos, a mesma implementação local de controlo orçamental proveniente de Compras, sem carregar vendas/facturação SGF como dependência.

Incluído: contrato de actor/contexto, origem do comando, moeda/base/exercício/centro, identidade idempotente e decisão elegível; operações existentes de dotação/reforço, reserva, ajuste de adjudicação, compromisso, libertação apenas no âmbito actualmente permitido e consumo por factura. Consolidar leitura de disponibilidade, ledger e auditoria, sem novo método de cálculo ou política empresarial. Pedidos sem dotação mantêm a distinção histórica de documento de desenvolvimento não controlado; não reinterpretar isso como controlo aprovado para utilização real.

Fronteira de código prevista: extrair de BudgetWorkflow.php, BudgetReinforcementWorkflow.php, operações orçamentais dos controladores de orçamento e de InvoiceWorkflow::validate, com Budget, BudgetEntry, BudgetConsumption e BudgetReinforcement. Manter as decisões de procurement e a conferência da factura nos seus serviços. Inventariar todos os pontos de escrita dessas tabelas antes da primeira alteração e incluir os testes/concorrência de orçamento e reforço existentes. Os ficheiros são pontos de origem, não autorização para copiar duas implementações.

Dois hosts de prova: composição Compras autónomo e composição ERP SGF reduzida com Purchasing, Platform e Finance. Ambos usam o mesmo artefacto/versionamento; cada um instala a sua base sintética isolada. Exercitar o circuito de aplicação real do módulo em cada host, não apenas um teste unitário com duas etiquetas. As entidades/actores de teste não são contas reais e não dependem de Osmane/Samira. A montagem visual completa do ERP não é condição para esta prova de extracção, mas o host deve carregar o módulo e os seus adaptadores de forma efectiva.

Excluído: alterações nas bases/clientes existentes, concessões reais, migração da Tempo, reestruturação integral do frontend, vendas, emissão fiscal, novo livro geral, criação de pagamentos, execução bancária, stock/valorização e novas regras de cancelamento. O consumo por factura é só o efeito orçamental existente, não a implementação antecipada de Payables. Não mover operações fora do incremento por arrasto.

Critério de saída: mesmas entradas produzem o mesmo ledger/saldos/recusas nos dois hosts, utilizando a mesma implementação, preservando base com/sem IVA, segregação, histórico e transacção. Uma origem gera um único efeito, replay idêntico recupera o resultado e conflito de conteúdo é recusado. Factura parcial consome apenas o montante devido, compromisso não é consumido duas vezes e falha da auditoria reverte o movimento. Os testes devem demonstrar revogação de direito e concorrência PostgreSQL. Artefacto Compras instala/arranca sem Sales ou SGF remoto.

Este incremento fica delimitado para orientar a próxima reestruturação. Não foi implementado ou aceite nesta passagem; as dependências acima deverão ser resolvidas no ensaio isolado, sem nova aprovação de cada pequeno passo técnico.

8. Plano de provas sintéticas, não executadas nesta passagem

Prova nos dois modos	Resultado exigido
Instalação autónoma sem Sales e sem rede para SGF	Arranque, contexto, procurement e controlo orçamental funcionam localmente
Instalação ERP com Purchasing	Mesmo pacote/migrações, serviços e resultados; sem segundo serviço de orçamento
Empresa A/B, unidade central/reservada, IDs coincidentes	Nenhum acesso ou movimento cruzado; contexto incompatível recusado
Proponente, aprovador, comprador e conferente sintéticos	Direitos explícitos; pessoa não valida a própria operação; revogação revalidada na transacção
Dotação 1000, reserva 300, ajuste para 350, compromisso 350, consumo parcial 100	Ledger conserva os deltas; 100 consumidos e 250 comprometidos; disponível 650, sem dupla subtracção
Reforço 200 proposto e depois aprovado distintamente	Disponível só aumenta após aprovação; replay não aumenta outra vez
Mesmo comando repetido; chave igual com conteúdo diferente	Mesmo resultado sem novo efeito; conflito explícito no segundo caso
Duas reservas simultâneas acima do saldo conjunto	Uma recusa ou espera conforme serialização; saldo nunca negativo
Falha entre documento, movimento e auditoria	Rollback local integral; repetição segura e sem reserva órfã
Cancelamento permitido antes de compromisso / ordem já emitida	Libertação única só no primeiro âmbito; manter recusa no segundo
Moeda/base/exercício ausentes ou incompatíveis	Pendência/recusa explicável, sem zero ou política inventada
Migração sintética e recuperação da versão	Contagens/origens/histórico conservados; nenhum replay de documentos históricos

Provas futuras T2–T5 acrescentam obrigação única, pagamento parcial, versões bancárias, movimento físico único, origem até lançamento e compatibilidade de regra/modelo fiscal. Não são critérios artificialmente antecipados para bloquear T1. Reutilizar provas aceites e registar apenas o delta nas matrizes/relatórios existentes. Demonstração persistente da equipa e bases destrutivas de regressão precisam de ambientes separados; não executar testes de extracção na demonstração SGF existente.

9. Referências SGF e cobertura documental

• AGENTS.md: decisões de produto e preservação; âmbito sintético.
• docs/PRODUCT_DEMO.md: capacidades existentes e demonstração, sem contabilidade geral presumida.
• docs/SERVICE_INVOICE_CALCULATION_SPEC.md, FIS-SGF-13 a 19: requisitos de compras/classificação, stock, contabilidade, custos e modelos; estados e critérios mantidos, sem nova matriz de requisitos.
• app/Shared/Context/CompanyContext.php, app/Modules/Identity/Services/Permissions.php: contexto/acessos existentes.
• app/Modules/Services/ServiceCalculation.php, DraftValues.php, ServiceReceivables.php, CatalogueAccounting.php: semântica financeira/fiscal existente e limites.
• app/Modules/Industry/IndustrialBudgets.php, IndustrialCosts.php: orçamento de custo e custeio industrial distintos de dotação de procurement.
• composer.json/composer.lock dos dois projectos: dependências reais a reconciliar na extracção.

Pendências específicas de desenho: forma física/versionamento/distribuição dos pacotes; schema sintético e estratégia futura de migração; correspondência multiempresa/unidade/departamento; combinação de dependências suportada. São decisões de implementação a demonstrar em QA, não requisitos para criar pessoas reais nem pretexto para um segundo motor financeiro.