Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
d10ba06edc | ||
|
|
ea9dcb3314 | ||
|
|
7628645fb6 | ||
|
|
21a91f2aff | ||
|
|
4276aca5c2 | ||
|
|
9f480045fa | ||
|
|
bc2707bb65 | ||
|
|
f8d57b52aa | ||
|
|
8fcd52c31d | ||
|
|
ca13acb74e |
@@ -9,3 +9,4 @@
|
||||
/.github export-ignore
|
||||
CHANGELOG.md export-ignore
|
||||
.styleci.yml export-ignore
|
||||
*.pdf binary
|
||||
|
||||
@@ -1,5 +1,40 @@
|
||||
# SGF Tempo — instruções locais
|
||||
|
||||
- Encerramento por delegação de 27/10/2026: o utilizador autorizou aceitar a entrega isolada de custos directos após conferência técnica do percurso e preservar checkpoint local. Ver `docs/WORKSHOP_DIRECT_COST_ACCEPTANCE.md`. Não se atribui nova verificação pessoal no navegador ao utilizador. `090000` e quatro concessões continuam NÃO aplicados; custeio real, emissão e restantes operações reais bloqueados. Sem CIF/lote industrial ou publicação. Esta autorização substitui apenas a pendência de encerramento técnico deste ensaio.
|
||||
|
||||
- Autorização técnica de 27/10/2026: implementar apenas `WORKSHOP-DIRECT-COST-SIM-v1`, secção 14 de `docs/INDUSTRIAL_COST_ACCOUNTING_SCOPE.md`. Ver `docs/WORKSHOP_DIRECT_COST_DELIVERY.md`. Apenas sintético em `sgf_tempo_test`, origens de oficina verificadas por ID/versão, sem duplicar acontecimentos. 275 MZN conhecidos ou 175 incompletos sem taxa material; exactidão racional, nunca custo completo/margem. Preparação e validação de custos/taxas por identidades distintas, sem editar apontamentos. `090000` e quatro concessões reais apenas propostos, NÃO aplicados; confirmação específica antes de aplicação. Não activar custeio real ou publicar; preservar `7628645`, `ea9dcb3`, alterações posteriores, oficinas/recebimentos/fiscalidade e aprovações. Sem presumir aceitação, CIF ou lote industrial.
|
||||
|
||||
- Decisões de desenho confirmadas em 27/10/2026: primeiro ensaio de custo directo de uma ordem de oficina, reutilizando apontamentos verificados por ID/versão, sem duplicar origens. 2 UN × 50,00 + 105/60 H × 100,00 = 275,00 MZN de custo directo conhecido, nunca custo completo/margem; sem taxa material, 175,00 conhecidos e total incompleto. Osmane prepara; Samira valida versões de custos/taxas sem alterar apontamentos técnicos. Futuras provas sintéticas com identidades distintas, sem novas concessões reais. Ver secção 14 de `docs/INDUSTRIAL_COST_ACCOUNTING_SCOPE.md`. Apenas decisões registadas, sem ordem de implementação; lote industrial/CIF adiados. Preservar entregas aceites e bloqueios.
|
||||
|
||||
- Autorização específica posterior de 27/10/2026 executada: apenas `070000` aplicada em `sgf_tempo_dev`, por caminho explícito com `sgf_dev_owner`, e oito concessões auditadas no tenant #1 / Tempo Lda #1 / SEGI #1: conta #1 `service_receivables.view/prepare/allocate/correction_request`; conta #2 `service_receivables.view/confirm/reconcile/correction_approve`. Ver actualização de `docs/SERVICE_RECEIVABLES_DELIVERY.md`. Preservadas 54 tabelas anteriores, acessos e instalação de oficinas `080000`; seis tabelas novas vazias. Aplicação mantém `sgf_dev_app`; recebimentos, reconciliação, oficinas e emissão reais continuam bloqueados na aplicação/base. Nenhuma operação real ou concessão para técnico/verificador. As indicações anteriores de `070000`/oito concessões pendentes são históricas; esta instalação não activa uso real ou publicação.
|
||||
|
||||
- Encerramento de 27/10/2026: entrega isolada `SGF-RECEIVABLES-SIM-v1` aceite pelo utilizador, com registo e checkpoint exclusivamente local. Ver `docs/SERVICE_RECEIVABLES_ACCEPTANCE.md`. Esta aceitação substitui a pendência de aceitação funcional, mas NÃO aplica `070000` nem as oito concessões, não activa utilização real e mantém bloqueios operacionais/fiscais. Oficinas permanece aceite, com `080000` e os quatro direitos de abertura já aplicados tecnicamente; não repetir a sua aprovação. Sem custos industriais ou publicação.
|
||||
|
||||
- Autorização específica posterior de 27/10/2026 executada: apenas `080000` aplicada em `sgf_tempo_dev`, por caminho explícito e proprietário `sgf_dev_owner`; quatro concessões auditadas para conta #1, tenant #1 / Tempo Lda #1 / SEGI #1: `workshop.view/open/assign/authorize`. Ver actualização de `docs/WORKSHOP_RESOURCE_DELIVERY.md`. `070000` permanece pendente, sem aceitação de recebimentos implícita. Dados/acessos anteriores preservados; sete tabelas de oficina vazias. Aplicação mantém `sgf_dev_app`; guardas operacionais e de emissão real preservadas e verificadas. Técnico/verificador reais continuam por identificar, sem concessões. Esta instalação não activa utilização operacional; indicações anteriores de `080000`/quatro direitos pendentes são históricas.
|
||||
|
||||
- Aceitação específica de 27/10/2026: o utilizador aceitou a entrega isolada `WORKSHOP-RESOURCE-RECORD-v1` e autorizou o registo e checkpoint Git exclusivamente local, sem credenciais/dados reais. Ver `docs/WORKSHOP_RESOURCE_ACCEPTANCE.md`. Esta aceitação não aplica `080000`, não concede direitos, não activa uso operacional e não abrange a aceitação de recebimentos. `070000` permanece separada e pendente. Técnico/verificador reais continuam por identificar. Sem custos industriais, publicação ou novo incremento. Esta aceitação substitui apenas a anterior pendência de aceitação de oficinas.
|
||||
|
||||
- Autorização de 27/10/2026: `WORKSHOP-RESOURCE-RECORD-v1`, ordem/autorização/tarefas/tempos/materiais/verificação, exclusivamente sintético em `sgf_tempo_test`. Ver `docs/WORKSHOP_RESOURCE_DELIVERY.md`. Início de trabalho exige autorização; relato de ocorrência passada fora do âmbito é permitido para auditoria, permanentemente sinalizado, sem autorização retroactiva ou verificação automática. Verificador distinto do autor. Migração `080000` e concessões reais NÃO aplicadas; confirmação específica antes de qualquer aplicação. `070000` de recebimentos continua pendente e não deve ser aplicada por arrasto. Técnico/verificador reais não identificados; não criar contas reais ou atribuir supervisão à Samira. Preservar entregas, sem presumir aceitação de recebimentos/oficina. Sem stock/custos/facturação/recebimentos/lançamentos ou publicação; guardas operacionais/fiscais mantidas.
|
||||
|
||||
- Autorização de 27/10/2026: implementar `SGF-RECEIVABLES-SIM-v1`, conforme `docs/SERVICE_RECEIVABLES_SCOPE.md`, secção 12, exclusivamente sintético em `sgf_tempo_test`. Ver `docs/SERVICE_RECEIVABLES_DELIVERY.md`. Preservar `4276aca` e alterações posteriores. Migração `2026_10_27_070000` NÃO aplicada em desenvolvimento e oito concessões reais NÃO aplicadas: exigem confirmação específica antes da aplicação. Manter guardas de ambiente/base, original imutável, montantes exactos, identidade distinta na confirmação/aprovação e revisão exacta. Sem recebimentos reais, recibo fiscal, ligação bancária, dinheiro, lançamento, fecho ou publicação. Não retirar bloqueio de emissão/configuração real. Não declarar aceitação automática desta entrega.
|
||||
|
||||
- Autorização específica posterior de 27/10/2026 executada: migração `2026_10_26_060000_create_test_invoice_issuance.php` aplicada em `sgf_tempo_dev` e oito concessões exactamente propostas aplicadas/auditadas (conta #1: série view/propose na empresa #1, documento view/issue/correction_request só unidade #1; conta #2: série view/approve na empresa #1, documento view só unidade #1). Ver secção de aplicação em `docs/SERVICE_INVOICE_TEST_DELIVERY.md` e provas `invoice-dev-preservation*.json`. Preservadas 31 tabelas preexistentes e acessos anteriores; oito tabelas novas vazias. Nenhuma série real ou documento criado. `ServiceInvoicing::guard()` permanece inalterado e as entradas de emissão/configuração real recusam com 403 mesmo com concessões. A autorização não retira o bloqueio, não resolve conformidade e não autoriza emissão, recebimentos, lançamentos ou publicação. As indicações anteriores de migração/concessões pendentes são históricas.
|
||||
|
||||
- Em 27/10/2026, o utilizador confirmou **«Aceitar a entrega técnica e criar checkpoint local»** para navegador + PDF, após verificar a demonstração. Entrega técnica encerrada no âmbito de `docs/SERVICE_INVOICE_TEST_DELIVERY.md`, exclusivamente de teste. Registar/preservar checkpoint local sem credenciais/dados reais; não repetir validações aceites sem alteração/falha relevante. Esta aceitação não aplica a migração `060000`, oito concessões ou série real, não resolve conformidade/exigibilidade/apuramento e não autoriza retirar o bloqueio de emissão real, emitir, receber, contabilizar ou publicar.
|
||||
|
||||
- Autorização posterior de 26/10/2026: incremento técnico de emissão/reprodução no navegador e PDF, **exclusivamente demonstrável em sgf_tempo_test**, com bloqueio incondicional de emissão real. Ver `docs/SERVICE_INVOICE_TEST_DELIVERY.md` e `docs/SERVICE_INVOICE_ISSUANCE_SCOPE.md`. Série real será nova; proponente prepara/emite e pede correcções, validador fiscal aprova séries e regra temporal. Migração `2026_10_26_060000_create_test_invoice_issuance.php`, código/número inicial reais e oito concessões propostas permanecem sem aplicação e exigem confirmação específica. Não retirar `ServiceInvoicing::guard`, não criar documentos fictícios em desenvolvimento, não confundir pressupostos temporais sintéticos com pendências resolvidas do caso real. Preservar `9f48004`, B1 e aprovações existentes; sem recebimentos, lançamentos, comunicação externa ou publicação.
|
||||
|
||||
- Em 26/10/2026, o utilizador aceitou o cálculo condicionado e autorizou o registo e checkpoint Git exclusivamente local, sem credenciais/dados locais. Ver `docs/CONDITIONAL_CALCULATION_ACCEPTANCE.md`. Perfil, concessões e activação local foram objecto de confirmações específicas; os detalhes nominativos permanecem na ficha local não versionada. Exigibilidade e período de apuramento permanecem pendentes; aprovação temporal não os determina. Preservar versões/âmbito exactos, separação de proponente/validador, B1 e aprovações contabilísticas. Calcular não altera decisão temporal validada. Sem avançar para emissão documental, recebimentos, lançamentos ou publicação.
|
||||
|
||||
- Em 26/10/2026, o utilizador aceitou expressamente o cálculo de ensaio demonstrado (base 1000,03; IVA exacto 160,0048; IVA proposto 160,00; diferença preservada 0,0048; total proposto 1160,03) e autorizou registo e checkpoint Git apenas local. Ver `docs/SERVICE_CALCULATION_SEPARATE_REVIEW.md`. Esta confirmação substitui apenas a pendência de aceitação do ensaio: a aplicabilidade fiscal real permanece separada e pendente, sem autorização para activar perfil fiscal real, emitir, contabilizar ou publicar.
|
||||
|
||||
- Em 26/10/2026, após informar que entrou e verificou, o utilizador confirmou a aceitação funcional do primeiro incremento de classificação contabilística e autorizou o encerramento e checkpoint Git exclusivamente local, sem credenciais ou dados locais. Preservar a entrega e os limites de `docs/CATALOGUE_ACCOUNTING_DELIVERY.md`. Esta aceitação não abrange a validação do cálculo fiscal, que continua separada e pendente; não autoriza lançamentos, publicação ou outro incremento.
|
||||
|
||||
- Autorização posterior: primeiro incremento de classificação contabilística do catálogo, PGC-NIRF, sem lançamentos e sem alterar o cálculo fiscal. Categoria é regra-base; só excepção aprovada, vigente e compatível a substitui. Mudança de categoria que afecte classificação exige nova proposta, vigência e validação; não usar edição de serviços para contornar o circuito. Propostas/submissões/decisões/resoluções são imutáveis; correcção gera nova versão e a substituição de uma versão aprovada é explícita. Data de referência é explícita, não reconhecimento/IVA. Conta agregadora não é conta de movimento; subconjunto documental inicial apenas 7/7.2, sem inventar desdobramentos. Fonte e versão preservadas.
|
||||
- As quatro concessões contabilísticas iniciais foram especificamente confirmadas e aplicadas em 26/10/2026, após conferência: conta 1, empresa 1, `catalogue_accounting.view/propose`; conta 2, empresa 1, `catalogue_accounting.view/approve`. Osmane prepara; Samira valida/recusa, sem edição/administração implícita. Nenhuma concessão de unidade ou de gestão destes direitos foi acrescentada. Novas concessões exigem confirmação concreta; não associar privilégios a nomes/emails no código. Ver `docs/CATALOGUE_ACCOUNTING_DELIVERY.md`. A validação do cálculo continua separada e pendente.
|
||||
|
||||
- Autorização posterior: primeiro cálculo delimitado sobre preço sem imposto, uma linha, apenas ensaios sintéticos isolados em `sgf_tempo_test`. Política `SGF-SERVICE-NET-VAT-TRUNCATE2-v1`: base/IVA exactos, IVA documental proposto truncado a duas casas e diferença preservada; total proposto apenas se base for exactamente representável a duas casas. É decisão operacional do utilizador, não obrigação fiscal demonstrada. Nenhum perfil real activado, nenhum direito fiscal derivado de configuração visual, nenhuma fotografia B1 alterada. Ver `docs/SERVICE_CALCULATION_DELIVERY.md`; instruções históricas abaixo não revogam este âmbito posterior.
|
||||
|
||||
- Projecto exclusivo em `C:\laragon\www\sgf-tempo`; não alterar InvesteMoz, os seus dados, configurações, ferramentas ou serviços.
|
||||
- Base de requisitos: SGF_TEMPO_Roteiro_v0_9.docx. Distinguir decisões acordadas de propostas técnicas e autorização de execução.
|
||||
- Usar `scripts/sgf.ps1` para ferramentas e arranque. Não usar o PHP/Composer do PATH por omissão nem alterar o PATH global.
|
||||
@@ -16,3 +51,11 @@
|
||||
- As alterações usam o token do contexto revisto, validação de permissões no servidor e auditoria na mesma transacção. Não remover os triggers de imutabilidade ou de auditoria append-only.
|
||||
- Provas de navegador usam browser-testing na porta 8001 e apenas sgf_tempo_test, com sessões/cache isolados e CSRF activo. Parar a prova antes de executar testes que recriam a base de testes.
|
||||
- Em 25 de Outubro de 2026, o utilizador aceitou e deu por concluído o incremento local de entrada, contexto e permissões no âmbito demonstrado e com os limites de docs/IDENTITY_DELIVERY.md. Preservar essa entrega como base. Serviços permanece apenas em especificação; não há autorização para implementação financeira ou publicação.
|
||||
- Autorização posterior: implementar exclusivamente a entrega A de docs/SERVICES_WORKFLOW_SPEC.md. Clientes/serviços são da empresa; prestações e facturação permanecem rascunhos da unidade. A autorização não abrange B/C, emissão fiscal, confirmação de operações, lançamentos, recebimentos, reconciliação, fecho ou publicação.
|
||||
- As novas concessões de A foram especificamente confirmadas para as contas existentes ID 1 e ID 2, na empresa ID 1 / unidade ID 1, após conferência. Não inferir direitos dos emails, nomes ou concessões de identidade; qualquer nova aplicação inicial exige confirmação específica.
|
||||
- Em A, quantidades/preços são cadeias decimais exactas com até 16 algarismos inteiros e 8 decimais. Não usar float, moeda por omissão, imposto desconhecido como zero ou arredondamentos silenciosos. Histórico/eventos/outbox/pendências são transaccionais; não processar contabilidade nesta entrega.
|
||||
- Em 25 de Outubro de 2026, o utilizador aceitou a entrega A no âmbito demonstrado e com os limites de docs/SERVICES_A_DELIVERY.md e autorizou um checkpoint Git exclusivamente local, sem credenciais ou dados locais. Preservar esta base aceite. Não avançar para B/C nem publicar.
|
||||
- Autorização posterior delimitada: B1, apenas confirmação interna dos rascunhos de facturação, fotografia imutável e captura transaccional de eventos/pendências. Mostrar «Confirmado internamente — sem validade fiscal». Não emitir documentos comerciais/fiscais, reconhecer receita, produzir lançamentos, receber, reconciliar, fechar ou publicar. A nova concessão billing_drafts.confirm_internal foi especificamente confirmada para a conta existente ID 1, empresa 1/unidade 1; não implica gestão de novas concessões nem altera a consulta da conta ID 2. B1 não conclui B integralmente; ver docs/SERVICES_B1_DELIVERY.md.
|
||||
- Em 25 de Outubro de 2026, o utilizador aceitou B1 no âmbito demonstrado de confirmação interna, sem validade fiscal nem lançamentos contabilísticos, e autorizou um checkpoint Git local sem credenciais ou dados locais. Preservar B1 e os checkpoints anteriores. Não avançar para os restantes incrementos nem publicar.
|
||||
- Autorização posterior de 26 de Outubro de 2026: preparação documental de emitente/clientes/rascunhos e instruções de pagamento reutilizáveis do emitente, sem emissão, recebimento ou contabilização. Preservar B1 `8fcd52c`; não reinterpretar preços antigos ou modificar fotografias existentes. Esquema 2 apenas em novas confirmações que utilizem preparação documental. Novos direitos issuer_documents/client_documents view/edit na empresa e draft_documents view/edit na unidade são explícitos; as nove concessões para contas existentes 1 (consulta/edição) e 2 (consulta), empresa 1/unidade 1, foram especificamente confirmadas. Não inferir poderes de gestão desses direitos. Nunca incluir valores completos das instruções em logs técnicos, relatórios de provas ou repositório. Ver docs/DOCUMENT_PREPARATION_DELIVERY.md.
|
||||
- Autorização posterior: primeira pré-visualização apenas no navegador, aviso fixo «RASCUNHO — SEM VALIDADE FISCAL», configuração delimitada e história B1 exclusivamente da fotografia. Não implementar emissão, cálculos fiscais, PDF/exportação/impressão documental ou operações financeiras. Consultas de pré-visualização são coerentes e read-only; mudanças geram aviso e actualização explícita. Novo direito document_preview.configure requer confirmação específica antes de concessão real; a operação para conta 1/empresa 1 foi especificamente confirmada e aplicada em 26 de Outubro de 2026. Samira permanece apenas em consulta. Novas operações não podem ser aplicadas por inferência. Ver docs/DRAFT_INVOICE_PREVIEW_DELIVERY.md.
|
||||
|
||||
@@ -1,8 +1,54 @@
|
||||
# SGF TEMPO
|
||||
|
||||
**Estado posterior em 27/10/2026:** oficinas e recebimentos sintéticos foram aceites; `080000`/quatro concessões de abertura e `070000`/oito concessões foram instaladas tecnicamente por autorizações específicas, sem retirar os bloqueios reais. As indicações de pendência nos parágrafos históricos abaixo foram substituídas pelos relatórios actualizados. O ensaio de custo directo e as suas pendências estão em [WORKSHOP_DIRECT_COST_DELIVERY.md](docs/WORKSHOP_DIRECT_COST_DELIVERY.md); `090000` e quatro concessões de custos não foram aplicadas.
|
||||
|
||||
**Oficina de teste (`WORKSHOP-RESOURCE-RECORD-v1`):** ordem, responsável, autorização por versão da tarefa, apontamentos de tempos/materiais e verificação distinta do autor. Só funciona em instância isolada ligada a `sgf_tempo_test`. Abrir a ordem não autoriza executar; ocorrência passada pode ser relatada e reconhecida apenas para auditoria, conservando a marca de fora do âmbito. Comandos, percurso e provas em [WORKSHOP_RESOURCE_DELIVERY.md](docs/WORKSHOP_RESOURCE_DELIVERY.md). Migração `080000` e concessões reais não aplicadas; técnico/verificador reais ainda não indicados. A migração `070000` também permanece pendente: não usar migração geral para aplicar ambas sem autorização específica. Sem stock, custos, facturação ou utilização operacional. Não confundir esta entrega técnica com aceitação do utilizador ou de recebimentos.
|
||||
|
||||
**Recebimentos simulados (`SGF-RECEIVABLES-SIM-v1`):** implementação exclusivamente de teste, com obrigação explícita, recebimentos parciais, afectações, conferência simulada e correcções rastreáveis. Percurso, comandos e provas em [SERVICE_RECEIVABLES_DELIVERY.md](docs/SERVICE_RECEIVABLES_DELIVERY.md). Migração `070000` e oito concessões reais permanecem pendentes de confirmação específica; não executar a migração normal para as aplicar sem essa confirmação. A demonstração usa apenas `sgf_tempo_test`, login sintético e porta 8001; a aplicação normal não muda de ligação. Recuperação de resposta perdida usa a mesma chave de comando; não repetir criando outro acontecimento. Sem recebimentos reais, recibo fiscal, novo PDF, banco, lançamento ou fecho. Emissão/configuração real continuam bloqueadas. Entrega técnica ainda sujeita à revisão do utilizador.
|
||||
|
||||
Primeiro percurso funcional local, sobre a fundação existente e o roteiro v0.9 de 25 de Outubro de 2026. Laravel modular com React, independente do InvesteMoz. Versões e lockfiles preservados; sem módulos financeiros, integrações externas ou publicação.
|
||||
|
||||
**Estado:** incremento local de entrada, contexto e permissões aceite e concluído pelo utilizador em 25 de Outubro de 2026, com os limites de [IDENTITY_DELIVERY.md](docs/IDENTITY_DELIVERY.md). Preservar esta base. Serviços mantém-se apenas em especificação; implementação financeira e publicação não estão autorizadas.
|
||||
**Base aceite:** incremento local de entrada, contexto e permissões aceite e concluído pelo utilizador em 25 de Outubro de 2026, com os limites de [IDENTITY_DELIVERY.md](docs/IDENTITY_DELIVERY.md). Preservar esta base. A autorização posterior de serviços está delimitada abaixo.
|
||||
|
||||
**Entrega A aceite em 25 de Outubro de 2026:** serviços em rascunho, no âmbito demonstrado e com os limites de [SERVICES_A_DELIVERY.md](docs/SERVICES_A_DELIVERY.md). B/C, operações financeiras confirmadas e publicação continuam sem autorização. O checkpoint aceite `26b80df` permanece preservado.
|
||||
|
||||
## Preparação documental (incremento posterior)
|
||||
|
||||
**Pré-visualização no navegador:** em **Rascunhos de facturação**, abrir um rascunho não confirmado e escolher **Pré-visualizar rascunho**. O aviso de ausência de validade fiscal e as pendências são obrigatórios. Mudanças geram aviso; **Actualizar pré-visualização** carrega explicitamente a nova versão. Para registos confirmados, usar **Abrir confirmação interna histórica**, que não reconstrói dados ausentes. A apresentação consulta-se em **Apresentação do rascunho**; Osmane tem configuração especificamente confirmada e aplicada na Tempo Lda; Samira apenas consulta. Sair e voltar a entrar, se necessário, para carregar o novo direito. [Relatório da pré-visualização](docs/DRAFT_INVOICE_PREVIEW_DELIVERY.md). Sem PDF, impressão documental ou emissão fiscal.
|
||||
|
||||
Depois de entrar e seleccionar a empresa/unidade autorizadas, abrir **Preparação documental** no menu lateral:
|
||||
|
||||
1. **Dados do emitente**: completar NUIT, morada, localidade e país. A denominação é o nome já existente; altera-se no menu Empresa, conforme direitos próprios.
|
||||
2. **Dados dos clientes**: seleccionar um cliente existente e completar os mesmos campos uma vez. Continua a ser possível criar clientes apenas com nome no menu Clientes.
|
||||
3. **Instruções de pagamento**: escolher **Novas instruções** ou uma configuração existente. Preparar banco/titular/identificadores/moeda quando aplicáveis e texto. São instruções do emitente para facilitar o pagamento, sem registo de recebimento ou ligação a bancos. Não introduzir credenciais, tokens, PIN ou dados de cartões.
|
||||
4. **Preparação de prestações** ou **Preparação de facturação**: seleccionar um rascunho já criado nos menus existentes. Preparar moeda, unidades das linhas, data/período, condições, vencimento proposto e modo de preço. Seleccionar instruções configuradas por designação; guardar.
|
||||
5. Consultar **Completude e validações** e os dados relacionados do emitente/cliente. «Preenchido» não é «validado». Condições/vencimento continuam sujeitos a conferência, sem correcção automática.
|
||||
|
||||
Ao criar um novo rascunho de facturação a partir de uma prestação com preparação actual, os dados documentais e selecções são reutilizados. Preparar uma moeda diferente actualiza explicitamente a moeda do rascunho pela operação existente, mantendo valores exactos; escolher «imposto incluído/acrescido» não recalcula impostos nem reinterpreta preços. Se um rascunho for editado depois, rever e guardar novamente a sua preparação. Documentos B1 confirmados permanecem bloqueados.
|
||||
|
||||
Osmane tem os direitos documentais especificamente confirmados na Tempo Lda/SEGI; Samira apenas consulta. Para carregar as novas concessões, actualizar o navegador e, se necessário, sair e voltar a entrar. Sem rascunhos, as listas de preparação estarão vazias: este ecrã reutiliza os registos existentes, não cria uma factura.
|
||||
|
||||
[Relatório e limites da preparação documental](docs/DOCUMENT_PREPARATION_DELIVERY.md). Não há emissão, numeração fiscal, PDF de factura, recebimentos ou lançamentos. Dados bancários apenas introduzidos pelo utilizador não são apresentados como verificados pelo banco.
|
||||
|
||||
## Usar a entrega A e B1
|
||||
|
||||
**Incremento posterior B1:** disponível a confirmação interna do rascunho de facturação para quem possua `billing_drafts.confirm_internal`. Abrir o rascunho, escolher **Rever confirmação interna**, conferir versão/contexto e confirmar. Quantidades/preços e referências devem estar completos e actuais; moeda ou regras desconhecidas permanecem pendentes. A fotografia é imutável e o rascunho confirmado deixa de poder ser editado ou eliminado. A referência `INT-B1-…` não é numeração fiscal. Não há emissão, impressão de factura, reconhecimento ou lançamento contabilístico. [Relatório B1](docs/SERVICES_B1_DELIVERY.md). A mantém-se aceite no checkpoint `ca13acb`; B1 foi aceite em 25 de Outubro de 2026 no âmbito demonstrado, sem validade fiscal nem lançamentos contabilísticos. Não avançar para os restantes incrementos nem publicar.
|
||||
|
||||
Actualizar o navegador e entrar normalmente. Seleccionar a empresa e a unidade autorizadas. Os novos menus são **Clientes**, **Serviços**, **Prestações em rascunho** e **Rascunhos de facturação**.
|
||||
|
||||
1. Criar o cliente (apenas nome obrigatório) e o serviço. São cadastros da empresa, reutilizados entre unidades.
|
||||
2. Criar uma prestação em rascunho na unidade seleccionada, escolhendo o cliente e as linhas de serviço existentes.
|
||||
3. Preencher quantidades/preços como texto decimal com ponto, até 16 algarismos inteiros e 8 decimais. Valores vazios ficam pendentes. Não há moeda por omissão.
|
||||
4. Guardar e usar **Preparar rascunho de facturação**. O servidor reutiliza cliente, linhas, moeda indicada e versão da prestação, sem emitir factura.
|
||||
5. Consultar pendências e **Histórico e captura durável**. A base aritmética não é um total fiscal ou valor definitivo a pagar.
|
||||
|
||||
Uma prestação alterada não reescreve silenciosamente o rascunho de facturação: aparece uma pendência. **Actualizar explicitamente da prestação** cria outra versão com os dados de origem revistos.
|
||||
|
||||
**Gerir acessos desta área** permite conceder/revogar apenas acções que o gestor possui no mesmo âmbito. Clientes/serviços têm âmbito de empresa; os dois tipos de rascunho têm âmbito de unidade. Os acessos de identidade continuam no menu anterior **Acessos**.
|
||||
|
||||
As novas concessões foram confirmadas especificamente para os registos existentes de Osmane (16 concessões) e Samira (4 de consulta), na Tempo Lda/SEGI. Nenhuma conta foi criada nesta entrega e nenhum dado de demonstração foi colocado em desenvolvimento.
|
||||
|
||||
Consultar estado local, sem mostrar segredos: `sgf.ps1 php scripts/a-status.php`. Não repetir `a-access-plan.php --apply` sem nova confirmação específica caso os direitos tenham sido entretanto alterados.
|
||||
|
||||
## Abrir e parar
|
||||
|
||||
@@ -49,6 +95,10 @@ Não existe criação de tenants ou empresas pela interface, auto-registo, opç
|
||||
|
||||
## Testes e ferramentas
|
||||
|
||||
O percurso de **Facturas de teste**, navegador e PDF da mesma fotografia, está demonstrado apenas na instância isolada. A migração e as oito concessões iniciais foram especificamente autorizadas e aplicadas em desenvolvimento, com dados anteriores preservados. A aplicação normal continua a recusar emissão/configuração real no servidor; nenhuma série real ou documento foi criado. Actualizar a sessão para consultar o bloqueio em **Facturas de teste**. Ver [entrega técnica, aplicação verificada e limitações](docs/SERVICE_INVOICE_TEST_DELIVERY.md). Não executar fixtures na base normal ou interpretar documentos de teste como facturas fiscais.
|
||||
|
||||
O incremento de cálculo condicionado foi aceite; ver [entrega, verificações e limites](docs/CONDITIONAL_CALCULATION_ACCEPTANCE.md). Na empresa/unidade autorizadas, consultar **Perfil fiscal do serviço** e **Rascunhos de facturação → Pré-visualizar rascunho**. A activação é uma operação local especificamente autorizada, sem via no navegador. O cálculo exige decisão temporal aprovada e compatível; quando há pendência, não determina exigibilidade ou período de apuramento. Sem emissão, recebimentos ou lançamentos.
|
||||
|
||||
```powershell
|
||||
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\sgf.ps1 test
|
||||
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\sgf.ps1 npm run build
|
||||
@@ -61,3 +111,10 @@ Os testes destrutivos usam exclusivamente `sgf_tempo_test`, verificada antes da
|
||||
Para Vite, `sgf.ps1 frontend` (porta 5173, estrita). A aplicação continua a ser aberta na porta 8000. As ferramentas usam caminhos explícitos em `C:\laragon\tools\sgf-tempo`; o cluster fica em `C:\laragon\data\sgf-tempo\postgres-17`, porta 55432. Não alterar as versões ou o ambiente do InvesteMoz.
|
||||
|
||||
[Relatório do incremento e provas](docs/IDENTITY_DELIVERY.md) · [Registo histórico da preparação inicial](docs/LOCAL_ENVIRONMENT.md)
|
||||
|
||||
O primeiro núcleo de cálculo de serviço e a política operacional de truncagem estão documentados em [cálculo de serviço: utilização, provas e limites](docs/SERVICE_CALCULATION_DELIVERY.md). A aplicação normal conserva pendências de aplicabilidade; cálculos de ensaio são exclusivos da instância isolada de testes. Não há activação de perfil fiscal real, emissão, recebimento ou contabilização.
|
||||
|
||||
O menu **Classificação contabilística**, disponível após actualizar a sessão com os acessos especificamente concedidos, permite preparar e submeter versões PGC-NIRF, validar/recusar sem editar e consultar classificação por data. Categoria e excepções são empresariais; operações e respectivos históricos continuam limitados às unidades autorizadas. As tabelas reais começam vazias, sem contas de movimento ou regras aprovadas por omissão. Consultar [utilização, provas e limites da classificação](docs/CATALOGUE_ACCOUNTING_DELIVERY.md).
|
||||
## Ensaio isolado de custo directo
|
||||
|
||||
O percurso `WORKSHOP-DIRECT-COST-SIM-v1` e as instruções de prova estão em [WORKSHOP_DIRECT_COST_DELIVERY.md](docs/WORKSHOP_DIRECT_COST_DELIVERY.md). Reutiliza apontamentos verificados sem duplicar consumos; não activa custeio real. Migração `090000` e quatro concessões continuam propostas, não aplicadas.
|
||||
|
||||
@@ -9,7 +9,7 @@ final class Audit
|
||||
public static function record(string $action, ?int $actor, ?int $tenant = null, ?int $company = null, ?int $unit = null, ?int $subject = null, array $details = []): void
|
||||
{
|
||||
// Explicit allowlist: credentials, session/context tokens and request bodies never enter audit.
|
||||
$safe = array_intersect_key($details, array_flip(['before_name', 'after_name', 'permission', 'reason', 'operator', 'grants']));
|
||||
$safe = array_intersect_key($details, array_flip(['before_name', 'after_name', 'permission', 'reason', 'operator', 'grants', 'area', 'record_id', 'version', 'event_id']));
|
||||
DB::table('identity_audit')->insert([
|
||||
'action' => $action, 'actor_id' => $actor, 'tenant_id' => $tenant,
|
||||
'company_id' => $company, 'unit_id' => $unit, 'subject_id' => $subject,
|
||||
|
||||
@@ -112,6 +112,7 @@ final class IdentityWorkflow
|
||||
$members = DB::table('company_memberships as m')->join('users as u', 'u.id', '=', 'm.user_id')
|
||||
->where('m.tenant_id', $ids['tenant_id'])->where('m.company_id', $ids['company_id'])->select('u.id', 'u.name', 'u.email')->orderBy('u.name')->get();
|
||||
$grants = DB::table('permission_grants')->where('tenant_id', $ids['tenant_id'])->where('company_id', $ids['company_id'])
|
||||
->whereIn('permission', array_merge(Permissions::COMPANY, Permissions::UNIT))
|
||||
->where(fn ($q) => $q->whereNull('unit_id')->orWhereIn('unit_id', $allowedUnits))->get(['id', 'user_id', 'unit_id', 'permission']);
|
||||
return ['members' => $members, 'grants' => $grants, 'catalogue' => ['company' => Permissions::COMPANY, 'unit' => Permissions::UNIT]];
|
||||
}
|
||||
|
||||
@@ -0,0 +1,210 @@
|
||||
<?php
|
||||
|
||||
namespace App\Modules\Services;
|
||||
|
||||
use App\Modules\Identity\Services\Audit;
|
||||
use App\Modules\Identity\Services\Permissions;
|
||||
use App\Shared\Context\CompanyContext;
|
||||
use Illuminate\Support\Facades\DB;
|
||||
use Illuminate\Support\Facades\Validator;
|
||||
use Illuminate\Support\Str;
|
||||
|
||||
final class CatalogueAccounting
|
||||
{
|
||||
public const SOURCE_VERSION='Decreto70/2009-PGC-NIRF-PDF134-BR372(148)';
|
||||
public const SOURCE_HASH='45C38AED64DE43042ED048586ACCE2EC660B74FC3F8FBCE33D39AAB45C7529E3';
|
||||
public const REFERENCE=['plan'=>'PGC-NIRF','source_version'=>self::SOURCE_VERSION,'sha256'=>self::SOURCE_HASH,'accounts'=>[['code'=>'7','name'=>'Rendimentos e ganhos','movable'=>false],['code'=>'7.2','name'=>'Prestação de serviços','movable'=>false]],'status'=>'Exemplar fornecido; consolidação posterior não comprovada; não é aprovação de conta empresarial.'];
|
||||
public const NOTICE='CLASSIFICAÇÃO CONTABILÍSTICA — SEM LANÇAMENTOS; IVA E RECONHECIMENTO INDEPENDENTES';
|
||||
public function __construct(private CompanyContext $context,private Permissions $permissions,private ServiceWorkflow $workflow) {}
|
||||
|
||||
private function scope(int $actor,string $action='view'): array
|
||||
{
|
||||
$ids=$this->context->identifiers(); abort_unless($this->context->userId()===$actor,403);
|
||||
foreach (array_unique(['view',$action]) as $a) { $this->permissions->require($actor,$ids['tenant_id'],$ids['company_id'],"catalogue_accounting.$a"); }
|
||||
return $ids;
|
||||
}
|
||||
private function query(array $scope) { return DB::table('ca_proposals')->where($scope); }
|
||||
private function row(int $id,array $scope): object { $row=$this->query($scope)->where('id',$id)->first(); abort_unless($row,403,'Proposta fora da empresa autorizada.'); return $row; }
|
||||
private function decode(object $row): array
|
||||
{
|
||||
$result=(array)$row; $result['data']=json_decode($row->data,true,32,JSON_THROW_ON_ERROR);
|
||||
$result['submission']=DB::table('ca_submissions')->where('proposal_id',$row->id)->first();
|
||||
$result['decision']=DB::table('ca_decisions')->where('proposal_id',$row->id)->first();
|
||||
$result['state']=$result['decision']->decision ?? ($result['submission'] ? 'submitted' : 'draft');
|
||||
return $result;
|
||||
}
|
||||
public function listing(int $actor): array
|
||||
{
|
||||
$scope=$this->scope($actor); $rows=$this->query($scope)->orderBy('id')->get()->map(fn($r)=>$this->decode($r))->all();
|
||||
$services=$this->permissions->has($actor,$scope['tenant_id'],$scope['company_id'],'services.view') ? DB::table('a_services')->where($scope)->orderBy('name')->get(['id','version','name'])->all() : [];
|
||||
return ['notice'=>self::NOTICE,'reference'=>self::REFERENCE,'proposals'=>$rows,'services'=>$services];
|
||||
}
|
||||
private function command(int $actor,string $action,array $request,string $key,callable $write): array
|
||||
{
|
||||
$scope=$this->scope($actor,$action); $unit=$this->context->unitId();
|
||||
abort_unless((bool)preg_match('/^[A-Za-z0-9-]{8,100}$/D',$key),422,'Chave de repetição necessária.');
|
||||
$canonical=function($v) use (&$canonical) { if(!is_array($v)) return $v; if(!array_is_list($v))ksort($v); return array_map($canonical,$v); };
|
||||
$hash=hash('sha256',json_encode($canonical($request),JSON_THROW_ON_ERROR));
|
||||
return DB::transaction(function() use($actor,$action,$request,$key,$write,$scope,$unit,$hash) {
|
||||
DB::table('companies')->where('id',$scope['company_id'])->where('tenant_id',$scope['tenant_id'])->lockForUpdate()->firstOrFail();
|
||||
$this->context->selectFor($actor,$scope['tenant_id'],$scope['company_id'],$unit); $this->scope($actor,$action);
|
||||
$old=DB::table('ca_commands')->where($scope)->where('command_key',$key)->first();
|
||||
if($old) { abort_unless((int)$old->actor_id===$actor && hash_equals($old->request_hash,$hash),409,'Repetição com autor ou conteúdo diferente.'); return json_decode($old->result,true,32,JSON_THROW_ON_ERROR)+['replayed'=>true]; }
|
||||
$result=$write($scope);
|
||||
DB::table('ca_commands')->insert($scope+['actor_id'=>$actor,'command_key'=>$key,'request_hash'=>$hash,'result'=>json_encode($result,JSON_THROW_ON_ERROR),'created_at'=>now()]);
|
||||
return $result+['replayed'=>false];
|
||||
});
|
||||
}
|
||||
private function date(string $date): void { Validator::make(['date'=>$date],['date'=>'required|date_format:Y-m-d'])->validate(); }
|
||||
private function data(string $kind,array $data,array $scope): array
|
||||
{
|
||||
$schemas=[
|
||||
'plan'=>['plan'=>'required|in:PGC-NIRF','source_version'=>'required|in:'.self::SOURCE_VERSION],
|
||||
'account'=>['plan_id'=>'required|integer|min:1','code'=>'required|string|max:40|regex:/^7\.2(?:\.[0-9A-Za-z_-]+)*$/D','name'=>'required|string|max:255','origin'=>'required|in:reference,enterprise','movable'=>'required|boolean','evidence'=>'required|string|max:2000'],
|
||||
'category'=>['name'=>'required|string|max:255','account_id'=>'required|integer|min:1','conditions'=>'required|string|max:2000'],
|
||||
'service_link'=>['service_id'=>'required|integer|min:1','category_id'=>'required|integer|min:1'],
|
||||
'service_override'=>['service_id'=>'required|integer|min:1','account_id'=>'required|integer|min:1','conditions'=>'required|string|max:2000'],
|
||||
];
|
||||
abort_unless(isset($schemas[$kind]),422); abort_if(array_diff(array_keys($data),array_keys($schemas[$kind]))!==[],422,'Campo fora do âmbito: sem IVA, reconhecimento ou lançamentos.');
|
||||
$data=Validator::make($data,$schemas[$kind])->validate();
|
||||
foreach(['plan_id'=>'plan','account_id'=>'account','category_id'=>'category'] as $field=>$type) {
|
||||
if(isset($data[$field])) { $data[$field]=(int)$data[$field]; abort_unless($this->row($data[$field],$scope)->kind===$type,422,'Tipo de referência incompatível.'); }
|
||||
}
|
||||
if(isset($data['service_id'])) {
|
||||
$data['service_id']=(int)$data['service_id'];
|
||||
$this->permissions->require($this->context->userId(),$scope['tenant_id'],$scope['company_id'],'services.view');
|
||||
abort_unless(DB::table('a_services')->where($scope)->where('id',$data['service_id'])->exists(),403,'Serviço fora da empresa.');
|
||||
}
|
||||
if($kind==='account') {
|
||||
$data['movable']=(bool)$data['movable'];
|
||||
if($data['origin']==='reference') { abort_unless($data['code']==='7.2' && !$data['movable'] && $data['name']==='Prestação de serviços',422,'Referência 7.2 não é conta de movimento aprovada.'); }
|
||||
else { abort_if(in_array($data['code'],['7.2','7.2.1','7.2.6'],true),422,'Código reservado; não usar como desdobramento empresarial.'); }
|
||||
}
|
||||
return $data;
|
||||
}
|
||||
public function propose(int $actor,array $input,string $key): array
|
||||
{
|
||||
return $this->command($actor,'propose',['operation'=>'propose','input'=>$input],$key,function($scope) use($actor,$input) {
|
||||
$data=$this->data($input['kind'],$input['data'],$scope); $previous=isset($input['previous_id']) ? $this->row((int)$input['previous_id'],$scope) : null;
|
||||
$entity=match($input['kind']) { 'plan'=>'PGC-NIRF','account'=>$data['code'],'service_link','service_override'=>'service:'.$data['service_id'],default=>$previous?->entity_key ?? (string)Str::uuid() };
|
||||
if($previous) { abort_unless($previous->kind===$input['kind'] && $previous->entity_key===$entity,422,'A correcção deve preservar a identidade.'); }
|
||||
$latest=$this->query($scope)->where('kind',$input['kind'])->where('entity_key',$entity)->orderByDesc('version')->first();
|
||||
abort_unless(($latest?->id ?? null)===($previous?->id ?? null),409,'Existe uma versão mais recente; reveja antes de propor.');
|
||||
$replaces=$input['replaces_id'] ?? null;
|
||||
if($replaces) { $r=$this->row((int)$replaces,$scope); abort_unless($r->kind===$input['kind'] && $r->entity_key===$entity && $r->valid_from<=$input['valid_from'] && $this->approved($r),422,'Substituição exige versão aprovada da mesma identidade e data compatível.'); }
|
||||
$id=DB::table('ca_proposals')->insertGetId($scope+['kind'=>$input['kind'],'entity_key'=>$entity,'version'=>(int)($latest?->version ?? 0)+1,'previous_id'=>$previous?->id,'replaces_id'=>$replaces,
|
||||
'valid_from'=>$input['valid_from'],'valid_until'=>$input['valid_until'] ?? null,'data'=>json_encode($data,JSON_THROW_ON_ERROR),'reason'=>$input['reason'],'actor_id'=>$actor,'created_at'=>now()]);
|
||||
Audit::record('catalogue_accounting.proposed',$actor,$scope['tenant_id'],$scope['company_id'],details:['record_id'=>$id,'version'=>(int)($latest?->version ?? 0)+1]);
|
||||
return ['id'=>$id];
|
||||
});
|
||||
}
|
||||
private function approved(object $row): bool { return DB::table('ca_decisions')->where('proposal_id',$row->id)->where('decision','approved')->exists(); }
|
||||
private function approvedRows(array $scope,string $kind,?string $entity=null): array
|
||||
{
|
||||
$q=$this->query($scope)->where('kind',$kind)->whereExists(fn($q)=>$q->selectRaw('1')->from('ca_decisions')->whereColumn('ca_decisions.proposal_id','ca_proposals.id')->where('decision','approved'));
|
||||
if($entity!==null)$q->where('entity_key',$entity); return $q->get()->all();
|
||||
}
|
||||
private function active(object $row,string $date,array $scope): bool
|
||||
{
|
||||
if($row->valid_from>$date || ($row->valid_until && $row->valid_until<$date))return false;
|
||||
// Explicit approved replacement ends the replaced interval from its start onward.
|
||||
return ! $this->query($scope)->where('replaces_id',$row->id)->where('valid_from','<=',$date)->whereExists(fn($q)=>$q->selectRaw('1')->from('ca_decisions')->whereColumn('ca_decisions.proposal_id','ca_proposals.id')->where('decision','approved'))->exists();
|
||||
}
|
||||
private function select(array $scope,string $kind,string $entity,string $date): ?object
|
||||
{
|
||||
$rows=array_values(array_filter($this->approvedRows($scope,$kind,$entity),fn($r)=>$this->active($r,$date,$scope)));
|
||||
abort_if(count($rows)>1,409,'Conflito explícito: várias versões aprovadas vigentes.'); return $rows[0] ?? null;
|
||||
}
|
||||
private function reference(int $id,string $kind,string $date,array $scope): object
|
||||
{
|
||||
$r=$this->row($id,$scope); abort_unless($r->kind===$kind && $this->approved($r) && $this->active($r,$date,$scope),422,'Referência sem aprovação/vigência compatível.'); return $r;
|
||||
}
|
||||
private function dependencies(object $row,string $date,array $scope): array
|
||||
{
|
||||
$data=json_decode($row->data,true,32,JSON_THROW_ON_ERROR);
|
||||
if($row->kind==='plan')return ['plan'=>$row];
|
||||
if($row->kind==='account') { return ['account'=>$row,'plan'=>$this->reference($data['plan_id'],'plan',$date,$scope)]; }
|
||||
if($row->kind==='service_link') {
|
||||
$categoryRef=$this->row($data['category_id'],$scope);
|
||||
$category=$this->select($scope,'category',$categoryRef->entity_key,$date);
|
||||
abort_unless($category,422,'Categoria sem regra-base aprovada vigente.');
|
||||
return ['link'=>$row]+$this->dependencies($category,$date,$scope);
|
||||
}
|
||||
$account=$this->reference($data['account_id'],'account',$date,$scope);
|
||||
$accountData=json_decode($account->data,true,32,JSON_THROW_ON_ERROR);
|
||||
abort_unless($accountData['movable'],422,'Conta agregadora: classificação de movimento pendente.');
|
||||
return [$row->kind==='category' ? 'category' : 'override'=>$row]+$this->dependencies($account,$date,$scope);
|
||||
}
|
||||
public function submit(int $id,int $actor,string $key): array
|
||||
{
|
||||
return $this->command($actor,'propose',['operation'=>'submit','id'=>$id],$key,function($scope) use($actor,$id) {
|
||||
$r=$this->row($id,$scope); $latest=$this->query($scope)->where('kind',$r->kind)->where('entity_key',$r->entity_key)->max('version');
|
||||
abort_unless((int)$latest===(int)$r->version,409,'Submeta a versão mais recente.');
|
||||
abort_if(DB::table('ca_submissions')->where('proposal_id',$id)->exists(),409,'Versão já submetida.');
|
||||
$this->dependencies($r,$r->valid_from,$scope);
|
||||
DB::table('ca_submissions')->insert($scope+['proposal_id'=>$id,'actor_id'=>$actor,'created_at'=>now()]);
|
||||
Audit::record('catalogue_accounting.submitted',$actor,$scope['tenant_id'],$scope['company_id'],details:['record_id'=>$id,'version'=>(int)$r->version]); return ['id'=>$id];
|
||||
});
|
||||
}
|
||||
public function decide(int $id,int $actor,array $input,string $key): array
|
||||
{
|
||||
return $this->command($actor,'approve',['operation'=>'decide','id'=>$id,'input'=>$input],$key,function($scope) use($id,$actor,$input) {
|
||||
$r=$this->row($id,$scope); abort_unless(DB::table('ca_submissions')->where('proposal_id',$id)->exists(),409,'Versão não submetida.');
|
||||
abort_if(DB::table('ca_decisions')->where('proposal_id',$id)->exists(),409,'Versão já decidida.');
|
||||
abort_unless((int)$this->query($scope)->where('kind',$r->kind)->where('entity_key',$r->entity_key)->max('version')===(int)$r->version,409,'Uma nova proposta exige revisão da versão actual.');
|
||||
if($input['decision']==='approved') {
|
||||
$this->dependencies($r,$r->valid_from,$scope);
|
||||
foreach($this->approvedRows($scope,$r->kind,$r->entity_key) as $other) {
|
||||
// Conflicting overlapping intervals require an explicit replacement, never latest-wins.
|
||||
$start=max($r->valid_from,$other->valid_from); $end=min($r->valid_until ?? '9999-12-31',$other->valid_until ?? '9999-12-31');
|
||||
if($start<=$end && $this->active($other,$start,$scope)) { abort_unless((int)$r->replaces_id===(int)$other->id,409,'Sobreposição: indique explicitamente a versão aprovada substituída.'); }
|
||||
}
|
||||
}
|
||||
DB::table('ca_decisions')->insert($scope+['proposal_id'=>$id,'actor_id'=>$actor,'decision'=>$input['decision'],'reason'=>$input['reason'],'created_at'=>now()]);
|
||||
Audit::record('catalogue_accounting.'.$input['decision'],$actor,$scope['tenant_id'],$scope['company_id'],details:['record_id'=>$id,'version'=>(int)$r->version,'reason'=>$input['reason']]); return ['id'=>$id,'decision'=>$input['decision']];
|
||||
});
|
||||
}
|
||||
private function resolveInternal(int $service,string $date,array $scope): array
|
||||
{
|
||||
$s=DB::table('a_services')->where($scope)->where('id',$service)->first(); abort_unless($s,403,'Serviço fora da empresa.');
|
||||
$base=['service'=>['id'=>$service,'version'=>(int)$s->version,'name'=>$s->name],'reference_date'=>$date,'notice'=>self::NOTICE];
|
||||
$override=$this->select($scope,'service_override','service:'.$service,$date);
|
||||
$link=$this->select($scope,'service_link','service:'.$service,$date);
|
||||
if(!$override && !$link)return $base+['state'=>'pending','pending'=>['Ligação à categoria ou excepção aprovada vigente em falta.']];
|
||||
try { $refs=$this->dependencies($override ?? $link,$date,$scope); }
|
||||
catch(\Symfony\Component\HttpKernel\Exception\HttpException $e) { if($e->getStatusCode()!==422)throw $e; return $base+['state'=>'pending','pending'=>[$e->getMessage()],'conflict'=>true]; }
|
||||
$plan=$this->select($scope,'plan','PGC-NIRF',$date);
|
||||
if(!$plan || (int)$plan->id!==(int)$refs['plan']->id)return $base+['state'=>'pending','pending'=>['Versão do plano incompatível; rever associações.'],'conflict'=>true];
|
||||
return $base+['state'=>'resolved_classification_only','origin'=>$override ? 'explicit_service_exception' : 'category_base','references'=>array_map(fn($r)=>['id'=>$r->id,'version'=>(int)$r->version,'kind'=>$r->kind,'entity_key'=>$r->entity_key,'valid_from'=>$r->valid_from,'valid_until'=>$r->valid_until,'data'=>json_decode($r->data,true),'approval'=>(array)DB::table('ca_decisions')->where('proposal_id',$r->id)->first()],$refs),
|
||||
'source'=>self::REFERENCE,'pending'=>['IVA e reconhecimento continuam independentes; nenhum lançamento produzido.']];
|
||||
}
|
||||
public function resolve(int $service,?string $date,int $actor): array
|
||||
{
|
||||
$scope=$this->scope($actor); $this->permissions->require($actor,$scope['tenant_id'],$scope['company_id'],'services.view');
|
||||
abort_unless(DB::table('a_services')->where($scope)->where('id',$service)->exists(),403);
|
||||
if(!$date)return ['state'=>'pending','pending'=>['Data de referência explícita em falta; nenhuma data foi presumida.']]; $this->date($date);
|
||||
$read=function()use($service,$date,$scope){$result=$this->resolveInternal($service,$date,$scope);return $result+['revision'=>hash_hmac('sha256',json_encode($result,JSON_THROW_ON_ERROR),(string)config('app.key'))];};
|
||||
if(DB::transactionLevel())return $read();
|
||||
return DB::transaction(function()use($read){DB::statement('SET TRANSACTION ISOLATION LEVEL REPEATABLE READ READ ONLY');return $read();});
|
||||
}
|
||||
public function capture(int $actor,array $input,string $key): array
|
||||
{
|
||||
return $this->command($actor,'propose',['operation'=>'capture','input'=>$input],$key,function($scope) use($actor,$input) {
|
||||
$operationScope=$this->workflow->scope($input['area'],$actor,'view');
|
||||
$draft=$this->workflow->show($input['area'],$input['record_id'],$actor);
|
||||
abort_unless($draft['version']===$input['record_version'],409,'Operação desactualizada.');
|
||||
abort_if(($draft['internal_confirmation'] ?? null)!==null,409,'B1 preservado; não capturar classificação retroactiva.');
|
||||
abort_unless(in_array($input['service_id'],array_column($draft['data']['lines'],'service_id'),true),422,'Serviço não pertence à operação.');
|
||||
$snapshot=$this->resolve($input['service_id'],$input['reference_date'],$actor);
|
||||
abort_unless(hash_equals($snapshot['revision'],$input['resolution_revision']),409,'A classificação mudou desde a consulta; consulte novamente antes de guardar.');
|
||||
abort_unless($snapshot['state']==='resolved_classification_only',422,implode(' ',$snapshot['pending']));
|
||||
$id=DB::table('ca_resolutions')->insertGetId($operationScope+['area'=>$input['area'],'record_id'=>$input['record_id'],'record_version'=>$input['record_version'],'service_id'=>$input['service_id'],'reference_date'=>$input['reference_date'],'snapshot'=>json_encode($snapshot,JSON_THROW_ON_ERROR),'actor_id'=>$actor,'created_at'=>now()]);
|
||||
Audit::record('catalogue_accounting.resolution_captured',$actor,$scope['tenant_id'],$scope['company_id'],$operationScope['unit_id'],details:['record_id'=>$id,'version'=>$input['record_version']]); return ['id'=>$id];
|
||||
});
|
||||
}
|
||||
public function history(int $actor,string $area,int $record): array
|
||||
{
|
||||
$this->scope($actor); $scope=$this->workflow->scope($area,$actor,'view'); $this->workflow->show($area,$record,$actor);
|
||||
return DB::table('ca_resolutions')->where($scope)->where('area',$area)->where('record_id',$record)->orderByDesc('id')->get()->map(function($r) { $r->snapshot=json_decode($r->snapshot,true); return $r; })->all();
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,171 @@
|
||||
<?php
|
||||
|
||||
namespace App\Modules\Services;
|
||||
|
||||
use App\Modules\Identity\Services\Audit;
|
||||
use App\Modules\Identity\Services\Permissions;
|
||||
use App\Shared\Context\CompanyContext;
|
||||
use Illuminate\Database\QueryException;
|
||||
use Illuminate\Support\Facades\DB;
|
||||
use Symfony\Component\HttpKernel\Exception\HttpException;
|
||||
|
||||
final class DocumentPreparation
|
||||
{
|
||||
public const PROFILE_FIELDS = ['nuit','address','locality','country'];
|
||||
public const PAYMENT_FIELDS = ['label','bank','holder','account_number','nib','iban','swift','bank_code','currency','instructions'];
|
||||
public const DRAFT_FIELDS = ['service_date','period_start','period_end','payment_terms','proposed_due_date','price_mode','units','payment_instruction_ids'];
|
||||
|
||||
public function __construct(private CompanyContext $context, private Permissions $permissions, private ServiceWorkflow $workflow) {}
|
||||
|
||||
public function scope(string $kind, int $actor, string $action): array
|
||||
{
|
||||
abort_unless(in_array($kind, ['issuer','client','payment','service_drafts','billing_drafts'], true), 404);
|
||||
$ids = $this->context->identifiers(); abort_unless($this->context->userId() === $actor, 403);
|
||||
$unit = str_ends_with($kind, '_drafts') ? $this->context->unitId() : null;
|
||||
abort_if(str_ends_with($kind, '_drafts') && ! $unit, 403, 'Seleccione uma unidade autorizada.');
|
||||
$prefix = $kind === 'client' ? 'client_documents' : ($unit ? 'draft_documents' : 'issuer_documents');
|
||||
foreach (array_unique(['view',$action]) as $right) { $this->permissions->require($actor, $ids['tenant_id'], $ids['company_id'], "$prefix.$right", $unit); }
|
||||
return $ids + ['unit_id' => $unit];
|
||||
}
|
||||
|
||||
private function query(string $kind, array $scope)
|
||||
{
|
||||
return DB::table('doc_records')->where($scope)->where('kind', $kind);
|
||||
}
|
||||
|
||||
private function target(string $kind, int $id, array $scope): ?object
|
||||
{
|
||||
if ($kind === 'payment') { return $id ? $this->query($kind, $scope)->where('id', $id)->first() : null; }
|
||||
$table = $kind === 'issuer' ? 'companies' : ($kind === 'client' ? 'a_clients' : 'a_'.$kind);
|
||||
$query = DB::table($table)->where('tenant_id', $scope['tenant_id'])->where($kind === 'issuer' ? 'id' : 'company_id', $scope['company_id'])->where('id', $id);
|
||||
if ($scope['unit_id']) { $query->where('unit_id', $scope['unit_id']); }
|
||||
$target = $query->first(); abort_unless($target, 403, 'Registo fora do âmbito autorizado.'); return $target;
|
||||
}
|
||||
|
||||
public function index(string $kind, int $actor): array
|
||||
{
|
||||
$scope = $this->scope($kind, $actor, 'view');
|
||||
if ($kind === 'payment') { return $this->query($kind, $scope)->orderBy('id')->get()->map(fn ($row) => $this->decode($row))->all(); }
|
||||
if ($kind === 'issuer') { return [['id' => $scope['company_id'], 'name' => DB::table('companies')->where('id', $scope['company_id'])->value('name')]]; }
|
||||
if ($kind === 'client') { $this->permissions->require($actor, $scope['tenant_id'], $scope['company_id'], 'clients.view'); return DB::table('a_clients')->where('tenant_id', $scope['tenant_id'])->where('company_id', $scope['company_id'])->orderBy('name')->get(['id','name'])->all(); }
|
||||
return $this->workflow->list($kind, $actor);
|
||||
}
|
||||
|
||||
public function show(string $kind, int $id, int $actor): array
|
||||
{
|
||||
$scope = $this->scope($kind, $actor, 'view'); $target = $this->target($kind, $id, $scope);
|
||||
abort_if($kind === 'payment' && ! $target, 403);
|
||||
if ($kind === 'client') { $this->permissions->require($actor, $scope['tenant_id'], $scope['company_id'], 'clients.view'); }
|
||||
if ($scope['unit_id']) { $this->workflow->scope($kind, $actor, 'view'); }
|
||||
$row = $kind === 'payment' ? $target : $this->query($kind, $scope)->where('record_id', $id)->first();
|
||||
$record = $row ? $this->decode($row) : ['id' => null, 'version' => 0, 'data' => []];
|
||||
$record['name'] = $target->name ?? ($record['data']['label'] ?? '');
|
||||
$record['origin'] = $kind === 'payment' ? 'Instruções configuradas do emitente' : ($kind === 'issuer' ? 'Nome reutilizado do cadastro da empresa' : ($kind === 'client' ? 'Nome reutilizado do cadastro do cliente' : 'Rascunho existente na unidade seleccionada'));
|
||||
$record['locked'] = $kind === 'billing_drafts' && DB::table('b_internal_confirmations')->where('billing_draft_id', $id)->exists();
|
||||
$record['review'] = $this->review($kind, $record['data'], $target);
|
||||
if ($scope['unit_id']) {
|
||||
$data = json_decode($target->data, true, 32, JSON_THROW_ON_ERROR);
|
||||
$record['draft_version'] = (int) $target->version; $record['currency'] = $data['currency']; $record['lines'] = $data['lines'];
|
||||
$record['review'][] = $this->check('currency', 'Moeda do rascunho', $data['currency'], 'Rascunho existente', 'Indicar moeda sem a presumir; validar aplicabilidade.');
|
||||
$record['review'][] = ['field' => 'terms_due', 'label' => 'Condições e vencimento', 'state' => 'validation_pending', 'origin' => 'Preparação do rascunho', 'next' => 'Conferir prazo e vencimento proposto. Sem emissão efectiva ou convenção de contagem aprovada, a compatibilidade não é validada nem corrigida automaticamente.'];
|
||||
if ($row && (int) ($record['data']['draft_version'] ?? 0) !== (int) $target->version) { $record['review'][] = ['field' => 'draft_version', 'label' => 'Rascunho alterado', 'state' => 'stale', 'origin' => 'Versão de origem', 'next' => 'Rever linhas, unidades e preparação antes de voltar a guardar.']; }
|
||||
$record['related_profiles'] = [];
|
||||
foreach (['issuer' => $scope['company_id'], 'client' => $target->client_id] as $relatedKind => $relatedId) {
|
||||
$prefix = $relatedKind === 'issuer' ? 'issuer_documents.view' : 'client_documents.view';
|
||||
if ($this->permissions->has($actor, $scope['tenant_id'], $scope['company_id'], $prefix)) { $related = $this->show($relatedKind, (int) $relatedId, $actor); $record['related_profiles'][$relatedKind] = ['name' => $related['name'], 'version' => $related['version'], 'review' => $related['review']]; }
|
||||
}
|
||||
}
|
||||
return $record;
|
||||
}
|
||||
|
||||
public function save(string $kind, int $id, int $actor, array $input): array
|
||||
{
|
||||
$scope = $this->scope($kind, $actor, 'edit'); $selected = $this->context->unitId();
|
||||
try {
|
||||
return DB::transaction(function () use ($kind, $id, $actor, $input, $scope, $selected): array {
|
||||
DB::table('companies')->where('id', $scope['company_id'])->lockForUpdate()->firstOrFail();
|
||||
$this->context->selectFor($actor, $scope['tenant_id'], $scope['company_id'], $selected); $this->scope($kind, $actor, 'edit');
|
||||
$target = $this->target($kind, $id, $scope); abort_if($kind === 'payment' && $id && ! $target, 403);
|
||||
if ($kind === 'client') { $this->permissions->require($actor, $scope['tenant_id'], $scope['company_id'], 'clients.view'); }
|
||||
$old = $kind === 'payment' ? $target : $this->query($kind, $scope)->where('record_id', $id)->first();
|
||||
abort_unless((int) ($old->version ?? 0) === $input['version'], 409, 'Os dados mudaram; reabra o formulário.');
|
||||
$fields = in_array($kind, ['issuer','client'], true) ? self::PROFILE_FIELDS : ($kind === 'payment' ? self::PAYMENT_FIELDS : self::DRAFT_FIELDS);
|
||||
$data = array_intersect_key($input, array_flip($fields));
|
||||
if ($scope['unit_id']) {
|
||||
$this->workflow->scope($kind, $actor, 'view');
|
||||
abort_if($kind === 'billing_drafts' && DB::table('b_internal_confirmations')->where('billing_draft_id', $id)->exists(), 409, 'A fotografia e o rascunho B1 estão bloqueados.');
|
||||
abort_unless((int) $target->version === $input['draft_version'], 409, 'O rascunho mudou; reveja a preparação.');
|
||||
$draftData = json_decode($target->data, true, 32, JSON_THROW_ON_ERROR);
|
||||
abort_unless(count($data['units']) === count($draftData['lines']), 422, 'Indique uma unidade de medida, ou pendência, por linha existente.');
|
||||
$data['payment_instruction_ids'] = array_values(array_unique($data['payment_instruction_ids']));
|
||||
if ($data['payment_instruction_ids']) { $this->scope('payment', $actor, 'view'); }
|
||||
foreach ($data['payment_instruction_ids'] as $instruction) { abort_unless($this->query('payment', ['tenant_id' => $scope['tenant_id'], 'company_id' => $scope['company_id'], 'unit_id' => null])->where('id', $instruction)->exists(), 403, 'Instrução fora da empresa autorizada.'); }
|
||||
if ($input['currency'] !== $draftData['currency']) {
|
||||
$changes = ['version' => (int) $target->version, 'currency' => $input['currency']];
|
||||
if ($kind === 'service_drafts') { $changes += ['client_id' => $target->client_id, 'lines' => $draftData['lines']]; }
|
||||
$saved = $this->workflow->save($kind, $id, $actor, $changes, (string) \Illuminate\Support\Str::uuid());
|
||||
$target->version = $saved['version'];
|
||||
}
|
||||
$data['draft_version'] = (int) $target->version;
|
||||
}
|
||||
$version = (int) ($old->version ?? 0) + 1;
|
||||
$values = ['data' => json_encode((object) $data, JSON_THROW_ON_ERROR), 'version' => $version, 'updated_at' => now()];
|
||||
if ($old) { $this->query($kind, $scope)->where('id', $old->id)->update($values); $record = $old->id; }
|
||||
else { $record = DB::table('doc_records')->insertGetId($scope + $values + ['kind' => $kind, 'record_id' => $kind === 'payment' ? 0 : $id, 'created_at' => now()]); }
|
||||
DB::table('doc_history')->insert(['doc_record_id' => $record, 'version' => $version, 'actor_id' => $actor, 'snapshot' => $values['data'], 'created_at' => now()]);
|
||||
// Audit contains only identifiers/version; never bank identifiers or instructions.
|
||||
Audit::record('documents.'.$kind.'.prepared', $actor, $scope['tenant_id'], $scope['company_id'], $scope['unit_id'], details: ['area' => $kind, 'record_id' => $record, 'version' => $version]);
|
||||
return ['id' => $kind === 'payment' ? $record : $id, 'version' => $version];
|
||||
});
|
||||
} catch (QueryException) { throw new HttpException(500, 'Não foi possível guardar a preparação. Nenhum valor das instruções foi incluído no erro; reabra e tente novamente.'); }
|
||||
}
|
||||
|
||||
public function snapshot(int $draft, int $actor): ?array
|
||||
{
|
||||
$scope = $this->context->identifiers(); $scope['unit_id'] = $this->context->unitId();
|
||||
$billing = DB::table('a_billing_drafts')->where($scope)->where('id', $draft)->firstOrFail();
|
||||
$rows = DB::table('doc_records')->where('tenant_id', $scope['tenant_id'])->where('company_id', $scope['company_id'])->where(function ($q) use ($billing, $draft) {
|
||||
$q->where('kind', 'issuer')->orWhere(fn ($q) => $q->where('kind', 'client')->where('record_id', $billing->client_id))->orWhere(fn ($q) => $q->where('kind', 'billing_drafts')->where('record_id', $draft));
|
||||
})->get();
|
||||
if ($rows->isEmpty()) { return null; }
|
||||
foreach (['issuer','client','billing_drafts'] as $kind) { $this->scope($kind, $actor, 'view'); }
|
||||
$result = ['schema_version' => 2, 'records' => [], 'payment_instructions' => [], 'completeness' => [], 'validation_status' => 'not_fiscally_validated'];
|
||||
foreach ($rows as $row) {
|
||||
$decoded = $this->decode($row); $result['records'][] = $decoded;
|
||||
$result['completeness'][$row->kind] = $this->show($row->kind, (int) $row->record_id, $actor)['review'];
|
||||
if ($row->kind === 'billing_drafts') {
|
||||
abort_unless((int) ($decoded['data']['draft_version'] ?? 0) === (int) $billing->version, 409, 'Reveja a preparação documental após a alteração do rascunho.');
|
||||
foreach ($decoded['data']['payment_instruction_ids'] as $id) { $result['payment_instructions'][] = $this->show('payment', $id, $actor); }
|
||||
}
|
||||
}
|
||||
return $result;
|
||||
}
|
||||
|
||||
public function inheritToBilling(int $source, int $billing, int $actor, array $scope): void
|
||||
{
|
||||
if (! $this->permissions->has($actor, $scope['tenant_id'], $scope['company_id'], 'draft_documents.view', $scope['unit_id'])) { return; }
|
||||
$row = $this->query('service_drafts', $scope)->where('record_id', $source)->first();
|
||||
if (! $row) { return; }
|
||||
$data = json_decode($row->data, true, 32, JSON_THROW_ON_ERROR);
|
||||
if ((int) $data['draft_version'] !== (int) DB::table('a_service_drafts')->where('id', $source)->value('version')) { return; }
|
||||
$data['draft_version'] = 1; $data['source_preparation'] = ['id' => $row->id, 'version' => $row->version];
|
||||
$encoded = json_encode($data, JSON_THROW_ON_ERROR);
|
||||
$id = DB::table('doc_records')->insertGetId($scope + ['kind' => 'billing_drafts', 'record_id' => $billing, 'version' => 1, 'data' => $encoded, 'created_at' => now(), 'updated_at' => now()]);
|
||||
DB::table('doc_history')->insert(['doc_record_id' => $id, 'version' => 1, 'actor_id' => $actor, 'snapshot' => $encoded, 'created_at' => now()]);
|
||||
Audit::record('documents.billing_drafts.reused', $actor, $scope['tenant_id'], $scope['company_id'], $scope['unit_id'], details: ['record_id' => $id, 'version' => 1]);
|
||||
}
|
||||
|
||||
private function decode(object $row): array { $result = (array) $row; $result['data'] = json_decode($row->data, true, 32, JSON_THROW_ON_ERROR); return $result; }
|
||||
private function check(string $field, string $label, mixed $value, string $origin, string $next): array { return ['field' => $field, 'label' => $label, 'state' => $value !== null && $value !== '' ? 'filled_not_validated' : 'missing', 'origin' => $origin, 'next' => $next]; }
|
||||
private function review(string $kind, array $data, ?object $target): array
|
||||
{
|
||||
$fields = in_array($kind, ['issuer','client'], true) ? self::PROFILE_FIELDS : ($kind === 'payment' ? ['label','bank','holder','currency','instructions'] : ['service_date','period_start','period_end','payment_terms','proposed_due_date','price_mode']);
|
||||
$labels = ['nuit' => 'NUIT', 'address' => 'Morada', 'locality' => 'Localidade', 'country' => 'País', 'label' => 'Designação', 'bank' => 'Banco (quando aplicável)', 'holder' => 'Titular (quando aplicável)', 'currency' => 'Moeda (quando aplicável)', 'instructions' => 'Instruções', 'service_date' => 'Data do serviço', 'period_start' => 'Início do período', 'period_end' => 'Fim do período', 'payment_terms' => 'Condições de pagamento', 'proposed_due_date' => 'Vencimento proposto', 'price_mode' => 'Modo de preço'];
|
||||
$result = [];
|
||||
if (in_array($kind, ['issuer','client'], true)) { $result[] = $this->check('name','Denominação', $target?->name, 'Cadastro existente (sem duplicação)', 'Editar o nome no cadastro original se necessário; validar denominação legal.'); }
|
||||
foreach ($fields as $field) { $value = $data[$field] ?? null; if ($field === 'price_mode' && $value === 'undefined') { $value = null; } $result[] = $this->check($field, $labels[$field], $value, 'Preparação introduzida pelo utilizador', 'Completar se aplicável e validar; preenchido não significa fiscalmente validado.'); }
|
||||
if (str_ends_with($kind, '_drafts')) { foreach ($data['units'] ?? [] as $i => $value) { $result[] = $this->check('unit_'.$i,'Unidade da linha '.($i + 1),$value,'Preparação da linha existente','Indicar unidade de medida se aplicável; nenhuma unidade é presumida.'); } }
|
||||
$result[] = ['field' => 'legal', 'label' => 'Validação legal/fiscal', 'state' => 'validation_pending', 'origin' => 'Regras ainda por validar', 'next' => 'Validar fontes e regras aplicáveis. Este ecrã não autoriza emissão fiscal nem verifica dados junto de bancos.'];
|
||||
return $result;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,154 @@
|
||||
<?php
|
||||
|
||||
namespace App\Modules\Services;
|
||||
|
||||
use App\Modules\Identity\Services\Audit;
|
||||
use App\Modules\Identity\Services\Permissions;
|
||||
use App\Shared\Context\CompanyContext;
|
||||
use Illuminate\Database\QueryException;
|
||||
use Illuminate\Support\Facades\DB;
|
||||
use Illuminate\Support\Facades\Storage;
|
||||
use Symfony\Component\HttpKernel\Exception\HttpException;
|
||||
|
||||
final class DocumentPreview
|
||||
{
|
||||
public const CONFIGURE = 'document_preview.configure';
|
||||
public const NOTICE = 'RASCUNHO — SEM VALIDADE FISCAL';
|
||||
public const DEFAULT_MODEL = ['show_logo' => false, 'show_contacts' => true, 'show_observations' => true, 'show_payment_instructions' => true, 'contact_text' => '', 'observations' => ''];
|
||||
|
||||
public function __construct(private CompanyContext $context, private Permissions $permissions, private DocumentPreparation $preparation, private ServiceWorkflow $workflow) {}
|
||||
|
||||
private function consistent(callable $read): mixed
|
||||
{
|
||||
if (DB::transactionLevel() > 0) {
|
||||
// RefreshDatabase fixtures already use a transaction. Production composition must start its own snapshot.
|
||||
if (! app()->environment('testing')) { throw new HttpException(409, 'Reabra a consulta numa operação independente.'); }
|
||||
return $read();
|
||||
}
|
||||
return DB::transaction(function () use ($read) {
|
||||
DB::statement('SET TRANSACTION ISOLATION LEVEL REPEATABLE READ READ ONLY');
|
||||
return $read();
|
||||
});
|
||||
}
|
||||
|
||||
private function model(): array
|
||||
{
|
||||
$ids = $this->context->identifiers();
|
||||
$row = DB::table('document_preview_models')->where($ids)->first();
|
||||
return ['version' => (int) ($row->version ?? 0), 'data' => $row ? json_decode($row->data, true, 32, JSON_THROW_ON_ERROR) : self::DEFAULT_MODEL];
|
||||
}
|
||||
|
||||
public function configuration(int $actor): array
|
||||
{
|
||||
return $this->consistent(function () use ($actor) { $this->preparation->scope('issuer', $actor, 'view'); return $this->model() + ['local_logo_available' => $this->logo() !== null]; });
|
||||
}
|
||||
|
||||
public function configure(int $actor, array $input): array
|
||||
{
|
||||
$scope = $this->preparation->scope('issuer', $actor, 'view'); $unit = $this->context->unitId();
|
||||
$this->permissions->require($actor, $scope['tenant_id'], $scope['company_id'], self::CONFIGURE);
|
||||
try { return DB::transaction(function () use ($scope, $unit, $actor, $input) {
|
||||
DB::table('companies')->where('id', $scope['company_id'])->lockForUpdate()->firstOrFail();
|
||||
$this->context->selectFor($actor, $scope['tenant_id'], $scope['company_id'], $unit);
|
||||
$this->preparation->scope('issuer', $actor, 'view');
|
||||
$this->permissions->require($actor, $scope['tenant_id'], $scope['company_id'], self::CONFIGURE);
|
||||
$ids = ['tenant_id' => $scope['tenant_id'], 'company_id' => $scope['company_id']];
|
||||
$old = DB::table('document_preview_models')->where($ids)->first();
|
||||
abort_unless((int) ($old->version ?? 0) === $input['version'], 409, 'A configuração mudou. Reabra-a antes de guardar.');
|
||||
$data = array_intersect_key($input, self::DEFAULT_MODEL); $version = (int) ($old->version ?? 0) + 1;
|
||||
$values = ['version' => $version, 'data' => json_encode($data, JSON_THROW_ON_ERROR), 'updated_at' => now()];
|
||||
if ($old) { DB::table('document_preview_models')->where('id', $old->id)->update($values); $id = $old->id; }
|
||||
else { $id = DB::table('document_preview_models')->insertGetId($ids + $values + ['created_at' => now()]); }
|
||||
DB::table('document_preview_model_history')->insert(['model_id' => $id, 'version' => $version, 'actor_id' => $actor, 'snapshot' => $values['data'], 'created_at' => now()]);
|
||||
Audit::record('document_preview.configured', $actor, $scope['tenant_id'], $scope['company_id'], details: ['record_id' => $id, 'version' => $version]);
|
||||
return ['version' => $version];
|
||||
}); } catch (QueryException) { throw new HttpException(500, 'Não foi possível guardar a configuração; nenhum conteúdo foi incluído no erro.'); }
|
||||
}
|
||||
|
||||
public function read(int $draft, int $actor, bool $historical = false): array
|
||||
{
|
||||
return $this->consistent(function () use ($draft, $actor, $historical) {
|
||||
$scope = $this->workflow->scope('billing_drafts', $actor, 'view');
|
||||
$this->context->selectFor($actor, $scope['tenant_id'], $scope['company_id'], $scope['unit_id']);
|
||||
if ($historical) { $payload = $this->historical($draft, $actor, $scope); }
|
||||
else { $payload = $this->current($draft, $actor, $scope); }
|
||||
$payload['notice'] = self::NOTICE;
|
||||
// Fingerprint is keyed, so a change token cannot be used to guess bank identifiers.
|
||||
$revision = hash_hmac('sha256', json_encode($payload, JSON_THROW_ON_ERROR), (string) config('app.key'));
|
||||
return $payload + ['revision' => $revision, 'consulted_at' => now()->toIso8601String()];
|
||||
});
|
||||
}
|
||||
|
||||
/** Internal composition under the issuer's company lock; ordinary preview reads remain read-only. */
|
||||
public function captureDraftForIssuance(int $draft,int $actor): array
|
||||
{
|
||||
abort_unless(DB::transactionLevel()>0,409,'Captura documental exige transacção consistente.');
|
||||
$scope=$this->workflow->scope('billing_drafts',$actor,'view');
|
||||
$this->context->selectFor($actor,$scope['tenant_id'],$scope['company_id'],$scope['unit_id']);
|
||||
return $this->current($draft,$actor,$scope)+['notice'=>self::NOTICE];
|
||||
}
|
||||
|
||||
private function current(int $draft, int $actor, array $scope): array
|
||||
{
|
||||
foreach (['issuer','client','billing_drafts'] as $kind) { $this->preparation->scope($kind, $actor, 'view'); }
|
||||
$billing = $this->workflow->show('billing_drafts', $draft, $actor);
|
||||
abort_if($billing['internal_confirmation'] !== null, 409, 'Este registo tem confirmação interna. Abra a vista histórica separada.');
|
||||
$issuer = $this->preparation->show('issuer', $scope['company_id'], $actor);
|
||||
$client = $this->preparation->show('client', $billing['client_id'], $actor);
|
||||
$prepared = $this->preparation->show('billing_drafts', $draft, $actor);
|
||||
$model = $this->model(); $payments = []; $paymentVersions = [];
|
||||
foreach ($prepared['data']['payment_instruction_ids'] ?? [] as $id) {
|
||||
$payment = $this->preparation->show('payment', (int) $id, $actor); $paymentVersions[] = [$payment['id'], $payment['version']];
|
||||
if ($model['data']['show_payment_instructions']) { $payments[] = ['id' => $payment['id'], 'version' => $payment['version'], 'data' => $payment['data']]; }
|
||||
}
|
||||
$pending = $billing['pending'];
|
||||
foreach (['Emitente' => $issuer, 'Cliente' => $client, 'Preparação' => $prepared] as $section => $row) {
|
||||
foreach ($row['review'] as $check) { if ($check['state'] !== 'filled_not_validated') { $pending[$section.'.'.$check['field']] = $section.' — '.$check['label'].': '.$check['next']; } }
|
||||
}
|
||||
if (! $paymentVersions) { $pending['instructions_missing'] = 'Instruções de pagamento não seleccionadas; preparar apenas as aplicáveis.'; }
|
||||
if (! $model['data']['contact_text']) { $pending['contacts_missing'] = 'Contactos de apresentação não configurados; completar se aplicável, independentemente da visibilidade do bloco.'; }
|
||||
$localLogo = $this->logo(); $logo = $model['data']['show_logo'] ? $localLogo : null;
|
||||
if (! $localLogo) { $pending['logo_missing'] = 'Logótipo opcional não disponível: falta recurso local autorizado da empresa. A escolha de visibilidade não valida este recurso.'; }
|
||||
return ['mode' => 'draft', 'title' => 'Pré-visualização do rascunho de factura de serviço', 'reference' => 'Rascunho interno #'.$draft,
|
||||
'scope' => $scope, 'source_id' => $billing['source_id'], 'draft_version' => $billing['version'], 'preparation_version' => $prepared['version'], 'model_version' => $model['version'],
|
||||
'issuer' => ['name' => $issuer['name'], 'data' => $issuer['data']], 'client' => ['name' => $client['name'], 'data' => $client['data']],
|
||||
'data' => $billing['data'], 'prepared' => $prepared['data'], 'base_amount' => $billing['base_amount'], 'pending' => $pending,
|
||||
'calculation' => app(ServiceCalculation::class)->read($draft, $actor),
|
||||
'fiscal_history' => $this->permissions->has($actor,$scope['tenant_id'],$scope['company_id'],'service_fiscal.view') ? app(ServiceFiscal::class)->history($draft,$actor) : [],
|
||||
'payments' => $payments, 'logo' => $logo, 'contacts' => $model['data']['show_contacts'] ? $model['data']['contact_text'] : null,
|
||||
'observations' => $model['data']['show_observations'] ? $model['data']['observations'] : null,
|
||||
'versions' => ['issuer' => $issuer['version'], 'client' => $client['version'], 'company_name' => $issuer['name'], 'client_name' => $client['name'], 'instructions' => $paymentVersions, 'model' => $model['version']]];
|
||||
}
|
||||
|
||||
private function historical(int $draft, int $actor, array $scope): array
|
||||
{
|
||||
$confirmation = app(InternalConfirmation::class)->show($draft, $actor);
|
||||
abort_unless($confirmation, 404, 'Não há confirmação interna histórica deste registo.');
|
||||
$snapshot = $confirmation['snapshot']; $prepared = []; $issuer = []; $client = []; $payments = []; $pending = $snapshot['pending'];
|
||||
$document = $snapshot['document_preparation'] ?? [];
|
||||
foreach ($document['records'] ?? [] as $record) {
|
||||
if ($record['kind'] === 'issuer') { $issuer = $record['data']; }
|
||||
if ($record['kind'] === 'client') { $client = $record['data']; }
|
||||
if ($record['kind'] === 'billing_drafts') { $prepared = $record['data']; }
|
||||
}
|
||||
foreach ($document['payment_instructions'] ?? [] as $payment) { $payments[] = ['id' => $payment['id'], 'version' => $payment['version'], 'data' => $payment['data']]; }
|
||||
foreach ($document['completeness'] ?? [] as $kind => $checks) { foreach ($checks as $check) { if ($check['state'] !== 'filled_not_validated') { $pending[$kind.'.'.$check['field']] = $check['label'].': '.$check['next']; } } }
|
||||
$pending['historical_limits'] = 'Logótipo, contactos, observações do modelo e denominação do emitente não foram capturados nesta fotografia. Não foram reconstruídos.';
|
||||
return ['mode' => 'historical', 'title' => 'Confirmação interna histórica — sem validade fiscal', 'reference' => $confirmation['internal_reference'], 'scope' => $scope,
|
||||
'confirmed_at' => $snapshot['confirmed_at'], 'actor_id' => $snapshot['actor_id'], 'snapshot_schema' => $snapshot['schema_version'] ?? 1, 'source_id' => $snapshot['service_draft']['id'],
|
||||
'draft_version' => $snapshot['billing_draft']['version'], 'preparation_version' => null, 'model_version' => null,
|
||||
'issuer' => ['name' => null, 'data' => $issuer], 'client' => ['name' => $snapshot['client']['name'], 'data' => $client],
|
||||
'data' => $snapshot['data'], 'prepared' => $prepared, 'base_amount' => $snapshot['base_amount'], 'pending' => $pending, 'payments' => $payments,
|
||||
'logo' => null, 'contacts' => null, 'observations' => null];
|
||||
}
|
||||
|
||||
private function logo(): ?string
|
||||
{
|
||||
$company = $this->context->identifiers()['company_id'];
|
||||
$disk = Storage::disk('local'); $path = 'document-logos/company-'.$company.'.png';
|
||||
if (! $disk->exists($path) || $disk->size($path) > 524288) { return null; }
|
||||
$bytes = $disk->get($path);
|
||||
if (! str_starts_with($bytes, "\x89PNG\r\n\x1a\n") || (new \finfo(FILEINFO_MIME_TYPE))->buffer($bytes) !== 'image/png') { return null; }
|
||||
return 'data:image/png;base64,'.base64_encode($bytes);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,58 @@
|
||||
<?php
|
||||
|
||||
namespace App\Modules\Services;
|
||||
|
||||
use Brick\Math\BigDecimal;
|
||||
use Illuminate\Support\Facades\DB;
|
||||
use Illuminate\Validation\ValidationException;
|
||||
|
||||
final class DraftValues
|
||||
{
|
||||
public static function decimal(mixed $value, string $field, bool $positive = false): ?string
|
||||
{
|
||||
if ($value === null || $value === '') { return null; }
|
||||
if (! is_string($value) || ! preg_match('/^(0|[1-9][0-9]{0,15})(\.[0-9]{1,8})?$/D', $value)) {
|
||||
throw ValidationException::withMessages([$field => 'Use uma cadeia decimal com ponto, até 16 algarismos inteiros e 8 decimais; sem expoentes ou arredondamento.']);
|
||||
}
|
||||
$decimal = BigDecimal::of($value);
|
||||
if ($positive && $decimal->isLessThanOrEqualTo(BigDecimal::zero())) { throw ValidationException::withMessages([$field => 'A quantidade deve ser superior a zero quando preenchida.']); }
|
||||
return (string) $decimal->stripTrailingZeros();
|
||||
}
|
||||
|
||||
public static function lines(array $lines, array $scope): array
|
||||
{
|
||||
$result = [];
|
||||
foreach ($lines as $index => $line) {
|
||||
$service = DB::table('a_services')->where('tenant_id', $scope['tenant_id'])->where('company_id', $scope['company_id'])->where('id', $line['service_id'])->first();
|
||||
abort_unless($service, 403, 'Serviço fora da empresa autorizada.');
|
||||
$result[] = ['service_id' => (int) $service->id, 'service_name' => $service->name,
|
||||
'description' => $line['description'] ?? null,
|
||||
'quantity' => self::decimal($line['quantity'] ?? null, "lines.$index.quantity", true),
|
||||
'unit_price' => self::decimal($line['unit_price'] ?? null, "lines.$index.unit_price")];
|
||||
}
|
||||
return $result;
|
||||
}
|
||||
|
||||
public static function pending(array $data): array
|
||||
{
|
||||
$pending = ['tax_rule_pending' => 'Imposto por definir e validar; não foi considerado zero.',
|
||||
'accounting_rule_pending' => 'Regras contabilísticas por validar; nenhum lançamento foi produzido.'];
|
||||
if (empty($data['currency'])) { $pending['currency_missing'] = 'Moeda não indicada; nenhuma moeda foi presumida.'; }
|
||||
else { $pending['currency_validation_pending'] = 'Moeda indicada pelo utilizador; a sua aplicabilidade e a moeda funcional continuam por validar.'; }
|
||||
foreach ($data['lines'] as $index => $line) {
|
||||
if ($line['quantity'] === null) { $pending["quantity_missing_$index"] = 'Quantidade por preencher na linha '.($index + 1).'.'; }
|
||||
if ($line['unit_price'] === null) { $pending["price_missing_$index"] = 'Preço proposto por preencher na linha '.($index + 1).'.'; }
|
||||
}
|
||||
return $pending;
|
||||
}
|
||||
|
||||
public static function base(array $data): ?string
|
||||
{
|
||||
$sum = BigDecimal::zero();
|
||||
foreach ($data['lines'] ?? [] as $line) {
|
||||
if ($line['quantity'] === null || $line['unit_price'] === null) { return null; }
|
||||
$sum = $sum->plus(BigDecimal::of($line['quantity'])->multipliedBy($line['unit_price']));
|
||||
}
|
||||
return (string) $sum->stripTrailingZeros();
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,29 @@
|
||||
<?php
|
||||
namespace App\Modules\Services\Http;
|
||||
use App\Http\Controllers\Controller;
|
||||
use App\Modules\Services\CatalogueAccounting;
|
||||
use Illuminate\Http\Request;
|
||||
|
||||
final class CatalogueAccountingController extends Controller
|
||||
{
|
||||
private function response(array $data) { return response()->json($data)->header('Cache-Control','no-store, private'); }
|
||||
private function only(Request $r,array $keys): void { abort_if(array_diff(array_keys($r->all()),$keys)!==[],422,'Campo protegido ou fora do âmbito.'); }
|
||||
public function index(Request $r,CatalogueAccounting $c) { return $this->response($c->listing($r->user()->id)); }
|
||||
public function propose(Request $r,CatalogueAccounting $c) {
|
||||
$this->only($r,['kind','data','valid_from','valid_until','reason','previous_id','replaces_id']);
|
||||
$data=$r->validate(['kind'=>'required|in:plan,account,category,service_link,service_override','data'=>'required|array','valid_from'=>'required|date_format:Y-m-d','valid_until'=>'nullable|date_format:Y-m-d|after_or_equal:valid_from','reason'=>'required|string|max:2000','previous_id'=>'nullable|integer|min:1','replaces_id'=>'nullable|integer|min:1']);
|
||||
return $this->response($c->propose($r->user()->id,$data,(string)$r->header('Idempotency-Key')));
|
||||
}
|
||||
public function submit(Request $r,int $id,CatalogueAccounting $c) { $this->only($r,[]); return $this->response($c->submit($id,$r->user()->id,(string)$r->header('Idempotency-Key'))); }
|
||||
public function decide(Request $r,int $id,CatalogueAccounting $c) {
|
||||
$this->only($r,['decision','reason']); return $this->response($c->decide($id,$r->user()->id,$r->validate(['decision'=>'required|in:approved,refused','reason'=>'required|string|max:2000']),(string)$r->header('Idempotency-Key')));
|
||||
}
|
||||
public function resolve(Request $r,int $service,CatalogueAccounting $c) { $this->only($r,['reference_date']); $r->validate(['reference_date'=>'nullable|date_format:Y-m-d']); return $this->response($c->resolve($service,$r->query('reference_date'),$r->user()->id)); }
|
||||
public function capture(Request $r,CatalogueAccounting $c) {
|
||||
$this->only($r,['area','record_id','record_version','service_id','reference_date','resolution_revision']);
|
||||
$data=$r->validate(['area'=>'required|in:service_drafts,billing_drafts','record_id'=>'required|integer|min:1','record_version'=>'required|integer|min:1','service_id'=>'required|integer|min:1','reference_date'=>'required|date_format:Y-m-d','resolution_revision'=>'required|string|regex:/^[a-f0-9]{64}$/D']);
|
||||
foreach(['record_id','record_version','service_id'] as $field)$data[$field]=(int)$data[$field];
|
||||
return $this->response($c->capture($r->user()->id,$data,(string)$r->header('Idempotency-Key')));
|
||||
}
|
||||
public function history(Request $r,string $area,int $record,CatalogueAccounting $c) { abort_unless(in_array($area,['service_drafts','billing_drafts'],true),404); return $this->response(['records'=>$c->history($r->user()->id,$area,$record)]); }
|
||||
}
|
||||
@@ -0,0 +1,39 @@
|
||||
<?php
|
||||
|
||||
namespace App\Modules\Services\Http;
|
||||
|
||||
use App\Http\Controllers\Controller;
|
||||
use App\Modules\Services\DocumentPreparation;
|
||||
use Illuminate\Http\Request;
|
||||
|
||||
final class DocumentPreparationController extends Controller
|
||||
{
|
||||
public function index(Request $request, string $kind, DocumentPreparation $preparation) { return response()->json(['records' => $preparation->index($kind, $request->user()->id)]); }
|
||||
public function show(Request $request, string $kind, int $id, DocumentPreparation $preparation) { return response()->json($preparation->show($kind, $id, $request->user()->id)); }
|
||||
public function save(Request $request, string $kind, int $id, DocumentPreparation $preparation)
|
||||
{
|
||||
$preparation->scope($kind, $request->user()->id, 'edit');
|
||||
$fields = in_array($kind, ['issuer','client'], true) ? DocumentPreparation::PROFILE_FIELDS : ($kind === 'payment' ? DocumentPreparation::PAYMENT_FIELDS : DocumentPreparation::DRAFT_FIELDS);
|
||||
$allowed = array_merge($fields, ['version'], str_ends_with($kind, '_drafts') ? ['draft_version','currency'] : []);
|
||||
abort_if(array_diff(array_keys($request->all()), $allowed) !== [], 422, 'Campo não suportado; não introduza credenciais, tokens ou dados de cartões.');
|
||||
$rules = ['version' => 'required|integer|min:0'];
|
||||
foreach ($fields as $field) { $rules[$field] = 'nullable|string|max:500'; }
|
||||
if ($kind === 'payment') {
|
||||
$rules['label'] = 'required|string|max:120'; $rules['instructions'] = 'nullable|string|max:2000'; $rules['currency'] = 'nullable|string|regex:/^[A-Z]{3}$/';
|
||||
} elseif (str_ends_with($kind, '_drafts')) {
|
||||
foreach (['service_date','period_start','period_end','proposed_due_date'] as $field) { $rules[$field] = 'nullable|date_format:Y-m-d'; }
|
||||
if ($request->filled('period_start')) { $rules['period_end'] .= '|after_or_equal:period_start'; }
|
||||
$rules['payment_terms'] = 'nullable|string|max:1000';
|
||||
$rules['price_mode'] = 'required|in:undefined,included,added';
|
||||
$rules['units'] = 'required|array|min:1|max:100'; $rules['units.*'] = 'nullable|string|max:80';
|
||||
$rules['payment_instruction_ids'] = 'present|array|max:20'; $rules['payment_instruction_ids.*'] = 'required|integer|min:1|distinct';
|
||||
$rules['draft_version'] = 'required|integer|min:1'; $rules['currency'] = 'nullable|string|regex:/^[A-Z]{3}$/';
|
||||
}
|
||||
$data = $request->validate($rules); $data['version'] = (int) $data['version'];
|
||||
foreach ($fields as $field) { if (! array_key_exists($field, $data)) { $data[$field] = null; } }
|
||||
if (isset($data['draft_version'])) { $data['draft_version'] = (int) $data['draft_version']; $data['currency'] ??= null; $data['payment_instruction_ids'] = array_map('intval', $data['payment_instruction_ids']); }
|
||||
// Refuse obvious secret assignments in free text; no secret fields are supported.
|
||||
foreach ($data as $value) { if (is_string($value)) { abort_if((bool) preg_match('/(?:password|palavra.passe|token|secret|cvv|cvc|pin)\s*[:=]/iu', $value), 422, 'Não introduza credenciais ou segredos nas instruções.'); } }
|
||||
return response()->json($preparation->save($kind, $id, $request->user()->id, $data));
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,37 @@
|
||||
<?php
|
||||
|
||||
namespace App\Modules\Services\Http;
|
||||
|
||||
use App\Http\Controllers\Controller;
|
||||
use App\Modules\Services\DocumentPreview;
|
||||
use Illuminate\Http\Request;
|
||||
|
||||
final class DocumentPreviewController extends Controller
|
||||
{
|
||||
public function calculate(Request $request, int $id, \App\Modules\Services\ServiceCalculation $calculation)
|
||||
{
|
||||
abort_if(array_diff(array_keys($request->all()), ['draft_version','preparation_version','profile_id','profile_version']) !== [], 422);
|
||||
$data = $request->validate(['draft_version'=>'required|integer|min:1','preparation_version'=>'required|integer|min:0','profile_id'=>'required|integer|min:1','profile_version'=>'required|integer|min:1']);
|
||||
return $this->response($calculation->calculate($id,$request->user()->id,array_map('intval',$data)));
|
||||
}
|
||||
private function response(array $data) { return response()->json($data)->header('Cache-Control', 'no-store, private, max-age=0')->header('Pragma', 'no-cache')->header('Vary', 'Cookie'); }
|
||||
public function model(Request $request, DocumentPreview $preview) { return $this->response($preview->configuration($request->user()->id)); }
|
||||
public function configure(Request $request, DocumentPreview $preview)
|
||||
{
|
||||
abort_if(array_diff(array_keys($request->all()), ['version', ...array_keys(DocumentPreview::DEFAULT_MODEL)]) !== [], 422, 'Campo não configurável: aviso e pendências são obrigatórios.');
|
||||
$rules = ['version' => 'required|integer|min:0', 'contact_text' => 'nullable|string|max:2000', 'observations' => 'nullable|string|max:2000'];
|
||||
foreach (['show_logo','show_contacts','show_observations','show_payment_instructions'] as $field) { $rules[$field] = 'required|boolean'; }
|
||||
$data = $request->validate($rules); $data['version'] = (int) $data['version'];
|
||||
foreach (['show_logo','show_contacts','show_observations','show_payment_instructions'] as $field) { $data[$field] = (bool) $data[$field]; }
|
||||
$data['contact_text'] ??= ''; $data['observations'] ??= '';
|
||||
return $this->response($preview->configure($request->user()->id, $data));
|
||||
}
|
||||
public function draft(Request $request, int $id, DocumentPreview $preview) { return $this->response($preview->read($id, $request->user()->id)); }
|
||||
public function historical(Request $request, int $id, DocumentPreview $preview) { return $this->response($preview->read($id, $request->user()->id, true)); }
|
||||
public function revision(Request $request, string $mode, int $id, DocumentPreview $preview)
|
||||
{
|
||||
abort_unless(in_array($mode, ['draft','history'], true), 404);
|
||||
$result = $preview->read($id, $request->user()->id, $mode === 'history');
|
||||
return $this->response(['revision' => $result['revision']]);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,57 @@
|
||||
<?php
|
||||
|
||||
namespace App\Modules\Services\Http;
|
||||
|
||||
use App\Http\Controllers\Controller;
|
||||
use App\Modules\Services\ServiceWorkflow;
|
||||
use App\Modules\Services\ServiceAccess;
|
||||
use App\Modules\Services\ServicePermissions;
|
||||
use Illuminate\Http\Request;
|
||||
|
||||
final class ServiceController extends Controller
|
||||
{
|
||||
public function index(Request $request, string $area, ServiceWorkflow $workflow) { return response()->json(['records' => $workflow->list($area, $request->user()->id)]); }
|
||||
public function show(Request $request, string $area, int $id, ServiceWorkflow $workflow)
|
||||
{
|
||||
$record = $workflow->show($area, $id, $request->user()->id);
|
||||
if ($area === 'billing_drafts') { $record['confirmation'] = app(\App\Modules\Services\InternalConfirmation::class)->show($id, $request->user()->id); }
|
||||
return response()->json($record);
|
||||
}
|
||||
public function confirmInternal(Request $request, int $id, \App\Modules\Services\InternalConfirmation $confirmation)
|
||||
{
|
||||
abort_if(array_diff(array_keys($request->all()), ['version']) !== [], 422, 'Campo não suportado ou identificador protegido.');
|
||||
$data = $request->validate(['version' => 'required|integer|min:1']);
|
||||
return response()->json($confirmation->confirm($id, $request->user()->id, (int) $data['version'], (string) $request->header('Idempotency-Key', '')));
|
||||
}
|
||||
public function create(Request $request, string $area, ServiceWorkflow $workflow) { return $this->save($request, $area, null, $workflow); }
|
||||
public function update(Request $request, string $area, int $id, ServiceWorkflow $workflow) { return $this->save($request, $area, $id, $workflow); }
|
||||
|
||||
private function save(Request $request, string $area, ?int $id, ServiceWorkflow $workflow)
|
||||
{
|
||||
abort_unless(in_array($area, ServicePermissions::AREAS, true), 404);
|
||||
$rules = ['name' => ServicePermissions::unitScoped($area) ? 'sometimes|required|string|max:255' : 'required|string|max:255',
|
||||
'description' => 'nullable|string|max:2000', 'version' => $id ? 'required|integer|min:1' : 'prohibited'];
|
||||
if ($area === 'clients') { unset($rules['description']); }
|
||||
if (ServicePermissions::unitScoped($area)) {
|
||||
$rules += ['currency' => 'nullable|string|regex:/^[A-Z]{3}$/', 'lines' => $area === 'service_drafts' ? 'required|array|min:1|max:100' : 'sometimes|array|min:1|max:100',
|
||||
'lines.*' => 'array:service_id,service_name,description,quantity,unit_price', 'lines.*.service_id' => 'required|integer|min:1',
|
||||
'lines.*.service_name' => 'sometimes|string|max:255', 'lines.*.description' => 'nullable|string|max:2000', 'lines.*.quantity' => 'nullable|string|max:30', 'lines.*.unit_price' => 'nullable|string|max:30'];
|
||||
if ($area === 'service_drafts') { $rules['client_id'] = 'required|integer|min:1'; }
|
||||
else { $rules['source_id'] = $id ? 'prohibited' : 'required|integer|min:1'; $rules['reload_source'] = 'sometimes|boolean'; }
|
||||
}
|
||||
$unknown = array_diff(array_keys($request->all()), array_keys($rules));
|
||||
abort_if($unknown !== [], 422, 'Campo não suportado ou identificador protegido.');
|
||||
$data = $request->validate($rules);
|
||||
$key = (string) $request->header('Idempotency-Key', '');
|
||||
return response()->json($workflow->save($area, $id, $request->user()->id, $data, $key), $id ? 200 : 201);
|
||||
}
|
||||
|
||||
public function accesses(Request $request, string $area, ServiceAccess $access) { return response()->json($access->listing($area, $request->user()->id)); }
|
||||
public function changeAccess(Request $request, string $area, ServiceAccess $access)
|
||||
{
|
||||
$data = $request->validate(['email' => 'required|email|max:255', 'action' => 'required|string', 'grant' => 'required|boolean', 'reason' => 'required|string|max:500']);
|
||||
abort_if(array_diff(array_keys($request->all()), ['email','action','grant','reason']) !== [], 422);
|
||||
$access->change($area, $request->user()->id, $data);
|
||||
return response()->json(['ok' => true]);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,16 @@
|
||||
<?php
|
||||
namespace App\Modules\Services\Http;
|
||||
|
||||
use App\Http\Controllers\Controller;
|
||||
use App\Modules\Services\ServiceFiscal;
|
||||
use Illuminate\Http\Request;
|
||||
|
||||
final class ServiceFiscalController extends Controller
|
||||
{
|
||||
private function response(array $data) { return response()->json($data)->header('Cache-Control','no-store, private'); }
|
||||
public function index(Request $r,ServiceFiscal $f) { return $this->response($f->listing($r->user()->id)); }
|
||||
public function propose(Request $r,ServiceFiscal $f) { return $this->response($f->propose($r->user()->id,$r->all())); }
|
||||
public function decide(Request $r,int $id,ServiceFiscal $f) { return $this->response($f->decide($id,$r->user()->id,$r->all())); }
|
||||
public function calculate(Request $r,int $id,ServiceFiscal $f) { return $this->response($f->calculate($id,$r->user()->id,$r->all())); }
|
||||
public function history(Request $r,int $id,ServiceFiscal $f) { return $this->response(['history'=>$f->history($id,$r->user()->id)]); }
|
||||
}
|
||||
@@ -0,0 +1,22 @@
|
||||
<?php
|
||||
namespace App\Modules\Services\Http;
|
||||
use App\Http\Controllers\Controller;
|
||||
use App\Modules\Services\ServiceInvoicing;
|
||||
use Illuminate\Http\Request;
|
||||
|
||||
final class ServiceInvoiceController extends Controller
|
||||
{
|
||||
private function response(array $data) { return response()->json($data)->header('Cache-Control','no-store, private'); }
|
||||
public function index(Request $r,ServiceInvoicing $s) { return $this->response($s->listing($r->user()->id)); }
|
||||
public function propose(Request $r,ServiceInvoicing $s) { return $this->response($s->propose($r->user()->id,$r->all())); }
|
||||
public function decide(Request $r,int $id,ServiceInvoicing $s) { return $this->response($s->decide($id,$r->user()->id,$r->all())); }
|
||||
public function review(Request $r,int $id,ServiceInvoicing $s) {
|
||||
abort_if(array_diff(array_keys($r->all()),['series_id','rule_id'])!==[],422);
|
||||
$d=$r->validate(['series_id'=>'required|integer|min:1','rule_id'=>'required|integer|min:1']);
|
||||
return $this->response($s->review($id,(int)$d['series_id'],(int)$d['rule_id'],$r->user()->id));
|
||||
}
|
||||
public function issue(Request $r,int $id,ServiceInvoicing $s) { return $this->response($s->issue($id,$r->user()->id,$r->all(),(string)$r->header('Idempotency-Key'))); }
|
||||
public function show(Request $r,int $id,ServiceInvoicing $s) { return $this->response($s->show($id,$r->user()->id)); }
|
||||
public function pdf(Request $r,int $id,ServiceInvoicing $s) { return response($s->pdf($id,$r->user()->id))->header('Content-Type','application/pdf')->header('Content-Disposition','attachment; filename="test-invoice-'.$id.'.pdf"')->header('Cache-Control','no-store, private')->header('X-Content-Type-Options','nosniff'); }
|
||||
public function correction(Request $r,int $id,ServiceInvoicing $s) { return $this->response($s->requestCorrection($id,$r->user()->id,$r->all())); }
|
||||
}
|
||||
@@ -0,0 +1,13 @@
|
||||
<?php
|
||||
namespace App\Modules\Services\Http;
|
||||
use App\Http\Controllers\Controller;
|
||||
use App\Modules\Services\ServiceReceivables;
|
||||
use Illuminate\Http\Request;
|
||||
final class ServiceReceivablesController extends Controller
|
||||
{
|
||||
private function response(array $d) { return response()->json($d)->header('Cache-Control','no-store, private'); }
|
||||
public function index(Request $r,ServiceReceivables $s) { return $this->response($s->listing($r->user()->id)); }
|
||||
public function propose(Request $r,ServiceReceivables $s) { return $this->response($s->propose($r->user()->id,$r->all(),(string)$r->header('Idempotency-Key'))); }
|
||||
public function decide(Request $r,int $id,ServiceReceivables $s) { return $this->response($s->decide($id,$r->user()->id,$r->all(),(string)$r->header('Idempotency-Key'))); }
|
||||
public function allocate(Request $r,int $id,ServiceReceivables $s) { return $this->response($s->allocate($id,$r->user()->id,$r->all(),(string)$r->header('Idempotency-Key'))); }
|
||||
}
|
||||
@@ -0,0 +1,90 @@
|
||||
<?php
|
||||
|
||||
namespace App\Modules\Services;
|
||||
|
||||
use App\Modules\Identity\Services\Audit;
|
||||
use App\Modules\Identity\Services\Permissions;
|
||||
use App\Shared\Context\CompanyContext;
|
||||
use Illuminate\Support\Facades\DB;
|
||||
|
||||
final class InternalConfirmation
|
||||
{
|
||||
public const PERMISSION = 'billing_drafts.confirm_internal';
|
||||
public const LABEL = 'Confirmado internamente — sem validade fiscal';
|
||||
|
||||
public function __construct(private CompanyContext $context, private Permissions $permissions, private ServiceWorkflow $workflow) {}
|
||||
|
||||
public function show(int $draft, int $actor): ?array
|
||||
{
|
||||
$scope = $this->workflow->scope('billing_drafts', $actor, 'view');
|
||||
$row = DB::table('b_internal_confirmations')->where('tenant_id', $scope['tenant_id'])->where('company_id', $scope['company_id'])->where('unit_id', $scope['unit_id'])->where('billing_draft_id', $draft)->first();
|
||||
if (! $row) { return null; }
|
||||
$history = DB::table('a_history')->where('area', 'internal_confirmations')->where('record_id', $row->id)->value('id');
|
||||
$event = DB::table('a_events as e')->join('a_outbox as o', 'e.id', '=', 'o.event_id')->where('history_id', $history)->first(['e.id','e.type','o.state']);
|
||||
$snapshot = json_decode($row->snapshot, true, 64, JSON_THROW_ON_ERROR);
|
||||
if (isset($snapshot['document_preparation'])) { foreach (['issuer','client','billing_drafts'] as $kind) { app(DocumentPreparation::class)->scope($kind, $actor, 'view'); } }
|
||||
return ['id' => $row->id, 'internal_reference' => 'INT-B1-'.$row->id, 'label' => self::LABEL, 'snapshot' => $snapshot, 'event' => $event];
|
||||
}
|
||||
|
||||
public function confirm(int $draft, int $actor, int $version, string $key): array
|
||||
{
|
||||
$scope = $this->workflow->scope('billing_drafts', $actor, 'view');
|
||||
$this->permissions->require($actor, $scope['tenant_id'], $scope['company_id'], self::PERMISSION, $scope['unit_id']);
|
||||
abort_unless((bool) preg_match('/^[a-zA-Z0-9-]{8,100}$/D', $key), 422, 'É necessária uma chave de repetição válida.');
|
||||
$hash = hash('sha256', json_encode(['b1.confirm_internal', $draft, $scope, $version], JSON_THROW_ON_ERROR));
|
||||
try { return DB::transaction(function () use ($scope, $draft, $actor, $version, $key, $hash): array {
|
||||
DB::table('companies')->where('id', $scope['company_id'])->where('tenant_id', $scope['tenant_id'])->lockForUpdate()->firstOrFail();
|
||||
$this->context->selectFor($actor, $scope['tenant_id'], $scope['company_id'], $scope['unit_id']);
|
||||
$this->workflow->scope('billing_drafts', $actor, 'view');
|
||||
$this->permissions->require($actor, $scope['tenant_id'], $scope['company_id'], self::PERMISSION, $scope['unit_id']);
|
||||
$old = DB::table('a_commands')->where('tenant_id', $scope['tenant_id'])->where('company_id', $scope['company_id'])->where('command_key', $key)->first();
|
||||
if ($old) {
|
||||
abort_unless((int) $old->actor_id === $actor && hash_equals($old->request_hash, $hash), 409, 'Chave repetida com conteúdo ou autor diferente.');
|
||||
return json_decode($old->result, true, 32, JSON_THROW_ON_ERROR) + ['replayed' => true];
|
||||
}
|
||||
$billing = DB::table('a_billing_drafts')->where('id', $draft)->where('tenant_id', $scope['tenant_id'])->where('company_id', $scope['company_id'])->where('unit_id', $scope['unit_id'])->lockForUpdate()->first();
|
||||
abort_unless($billing, 403, 'Rascunho fora do âmbito autorizado.');
|
||||
abort_unless((int) $billing->version === $version, 409, 'A versão mudou; reabra o rascunho.');
|
||||
$existing = DB::table('b_internal_confirmations')->where('billing_draft_id', $draft)->first();
|
||||
if ($existing) {
|
||||
$history = DB::table('a_history')->where('area', 'internal_confirmations')->where('record_id', $existing->id)->value('id');
|
||||
$event = DB::table('a_events')->where('history_id', $history)->value('id');
|
||||
$result = ['id' => $existing->id, 'billing_draft_id' => $draft, 'version' => $version, 'internal_reference' => 'INT-B1-'.$existing->id, 'event_id' => $event];
|
||||
} else {
|
||||
$data = json_decode($billing->data, true, 32, JSON_THROW_ON_ERROR);
|
||||
$source = DB::table('a_service_drafts')->where('id', $billing->source_id)->where('tenant_id', $scope['tenant_id'])->where('company_id', $scope['company_id'])->where('unit_id', $scope['unit_id'])->first();
|
||||
abort_unless($source && (int) $source->version === (int) $data['source_version'], 409, 'A prestação mudou; reveja e actualize explicitamente o rascunho antes de confirmar.');
|
||||
$client = DB::table('a_clients')->where('id', $billing->client_id)->where('tenant_id', $scope['tenant_id'])->where('company_id', $scope['company_id'])->first();
|
||||
abort_unless($client && trim($client->name) !== '' && trim($billing->name) !== '', 422, 'Complete o cliente e a designação do percurso.');
|
||||
abort_unless((int) $source->client_id === (int) $billing->client_id, 422, 'O cliente diverge da prestação de origem.');
|
||||
$data['lines'] = DraftValues::lines($data['lines'], $scope);
|
||||
foreach ($data['lines'] as $line) { abort_if($line['quantity'] === null || $line['unit_price'] === null || trim($line['service_name']) === '', 422, 'Complete quantidade, preço e serviço de todas as linhas.'); }
|
||||
$pending = DraftValues::pending($data) + ['accounts_pending' => 'Contas e classificação por validar; contabilização bloqueada.', 'recognition_pending' => 'Momento e regras de reconhecimento por validar; contabilização bloqueada.'];
|
||||
$catalogue = [];
|
||||
foreach (array_unique(array_column($data['lines'], 'service_id')) as $id) { $service = DB::table('a_services')->where('id', $id)->first(); $catalogue[] = $this->record($service); }
|
||||
$data['client_name'] = $client->name;
|
||||
$snapshot = ['label' => self::LABEL, 'scope' => $scope, 'billing_draft' => $this->record($billing), 'service_draft' => $this->record($source),
|
||||
'client' => $this->record($client), 'services' => $catalogue, 'data' => $data, 'base_amount' => DraftValues::base($data),
|
||||
'pending' => $pending, 'actor_id' => $actor, 'confirmed_at' => now()->toIso8601String(), 'accounting_status' => 'blocked_pending', 'fiscal_status' => 'not_issued'];
|
||||
$preparation = app(DocumentPreparation::class)->snapshot($draft, $actor);
|
||||
if ($preparation !== null) { $snapshot['schema_version'] = 2; $snapshot['document_preparation'] = $preparation; }
|
||||
$id = DB::table('b_internal_confirmations')->insertGetId($scope + ['billing_draft_id' => $draft, 'billing_version' => $version, 'version' => 1, 'actor_id' => $actor, 'snapshot' => json_encode($snapshot, JSON_THROW_ON_ERROR), 'created_at' => now()]);
|
||||
$history = DB::table('a_history')->insertGetId($scope + ['area' => 'internal_confirmations', 'record_id' => $id, 'version' => 1, 'actor_id' => $actor, 'snapshot' => json_encode($snapshot, JSON_THROW_ON_ERROR), 'created_at' => now()]);
|
||||
foreach ($pending as $code => $message) { DB::table('a_pending')->insert(['history_id' => $history, 'code' => $code, 'message' => $message, 'created_at' => now()]); }
|
||||
$event = DB::table('a_events')->insertGetId(['history_id' => $history, 'type' => 'b1.billing_draft.confirmed_internal', 'schema_version' => $preparation !== null ? 2 : 1, 'payload' => json_encode(['confirmation_id' => $id, 'snapshot' => $snapshot], JSON_THROW_ON_ERROR), 'created_at' => now()]);
|
||||
DB::table('a_outbox')->insert(['event_id' => $event, 'state' => 'captured', 'created_at' => now()]);
|
||||
Audit::record('b1.billing_draft.confirmed_internal', $actor, $scope['tenant_id'], $scope['company_id'], $scope['unit_id'], details: ['area' => 'internal_confirmations', 'record_id' => $id, 'version' => 1, 'event_id' => $event]);
|
||||
$result = ['id' => $id, 'billing_draft_id' => $draft, 'version' => $version, 'internal_reference' => 'INT-B1-'.$id, 'event_id' => $event];
|
||||
}
|
||||
DB::table('a_commands')->insert(['tenant_id' => $scope['tenant_id'], 'company_id' => $scope['company_id'], 'actor_id' => $actor, 'command_key' => $key, 'request_hash' => $hash, 'result' => json_encode($result, JSON_THROW_ON_ERROR), 'created_at' => now()]);
|
||||
return $result + ['replayed' => isset($existing) && $existing !== null];
|
||||
}); } catch (\Illuminate\Database\QueryException) { throw new \Symfony\Component\HttpKernel\Exception\HttpException(500, 'Não foi possível capturar a confirmação. Nenhum dado bancário foi incluído no erro.'); }
|
||||
}
|
||||
|
||||
private function record(object $record): array
|
||||
{
|
||||
$data = (array) $record;
|
||||
if (isset($data['data'])) { $data['data'] = json_decode($data['data'], true, 32, JSON_THROW_ON_ERROR); }
|
||||
return $data;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,71 @@
|
||||
<?php
|
||||
namespace App\Modules\Services;
|
||||
|
||||
/** Deterministic text-only PDF v1. Stored bytes, never regenerated from live records. */
|
||||
final class InvoicePdf
|
||||
{
|
||||
public const VERSION='sgf-test-invoice-text-v2';
|
||||
public static function lines(array $s): array
|
||||
{
|
||||
$lines=[['title','Factura de serviço - demonstração isolada'],['text',$s['series_code'].' / '.$s['number']],['text','Emissão: '.$s['issued_local'].' ('.$s['timezone'].')'],['section','Emitente']];
|
||||
foreach(['issuer'=>'Emitente','client'=>'Cliente'] as $key=>$title) {
|
||||
if($key==='client') $lines[]=['section',$title];
|
||||
$party=$s['document'][$key]; $lines[]=['text',$party['name']];
|
||||
foreach(['nuit'=>'NUIT','address'=>'Morada','locality'=>'Localidade','country'=>'País'] as $field=>$label) $lines[]=['text',$label.': '.($party['data'][$field] ?? 'Não indicado')];
|
||||
}
|
||||
$p=$s['document']['prepared']; $line=$s['document']['data']['lines'][0];
|
||||
$lines[]=['section','Serviço e período'];
|
||||
foreach(['service_name'=>'Serviço','description'=>'Descrição','quantity'=>'Quantidade','unit_price'=>'Preço sem IVA'] as $key=>$label) if(!empty($line[$key]) || ($line[$key] ?? null)==='0') $lines[]=['text',$label.': '.$line[$key]];
|
||||
$lines[]=['text','Unidade: '.($p['units'][0] ?? 'Não indicada')];
|
||||
$lines[]=['text','Período: '.($p['period_start'] ?? 'Não indicado').' a '.($p['period_end'] ?? 'Não indicado')];
|
||||
$lines[]=['text','Condições: '.($p['payment_terms'] ?? 'Não indicadas')];
|
||||
$lines[]=['text','Vencimento proposto: '.($p['proposed_due_date'] ?? 'Não indicado')];
|
||||
$lines[]=['section','Valores - '.$s['calculation']['currency']];
|
||||
foreach(['base_exact'=>'Base exacta','vat_exact'=>'IVA exacto','vat_document_proposed'=>'IVA documental proposto','discarded_difference'=>'Diferença preservada','total_document_proposed'=>'Total proposto'] as $key=>$label) $lines[]=['text',$label.': '.$s['calculation'][$key]];
|
||||
$lines[]=['text','Perfil: '.$s['profile_identifier'].' v'.$s['profile_version'].' | IVA '.$s['rate_percent'].'%'];
|
||||
$lines[]=['text','Exigibilidade simulada: '.$s['exigibility_date'].' | Período: '.$s['assessment_period']];
|
||||
foreach(['contacts'=>'Contactos','observations'=>'Observações'] as $key=>$label) if(!empty($s['document'][$key])) { $lines[]=['section',$label]; $lines[]=['text',$s['document'][$key]]; }
|
||||
foreach($s['document']['payments'] as $payment) { $lines[]=['section','Instruções de pagamento']; foreach(['label'=>'Designação','bank'=>'Banco','holder'=>'Titular','account_number'=>'Conta','nib'=>'NIB','iban'=>'IBAN','swift'=>'SWIFT','bank_code'=>'Código bancário','currency'=>'Moeda','instructions'=>'Instruções'] as $key=>$label) if(isset($payment['data'][$key]) && $payment['data'][$key]!=='') $lines[]=['text',$label.': '.$payment['data'][$key]]; }
|
||||
$lines[]=['section','Origem e limites']; $lines[]=['text','Rascunho #'.$s['draft_id'].' v'.$s['document']['draft_version'].' | Regra temporal #'.$s['rule_id'].' v'.$s['rule_version']];
|
||||
$lines[]=['text','Sem recebimento, comunicação à AT ou lançamento contabilístico.'];
|
||||
return $lines;
|
||||
}
|
||||
public static function supports(array $lines): bool
|
||||
{
|
||||
foreach($lines as [, $text]) if(@iconv('UTF-8','Windows-1252',$text)===false || preg_match('/[\x00-\x08\x0B\x0C\x0E-\x1F]/',$text)) return false;
|
||||
return true;
|
||||
}
|
||||
public function render(array $s): string
|
||||
{
|
||||
$lines=$s['document_lines'] ?? self::lines($s); abort_unless(self::supports($lines),422,'Texto fora do conjunto de caracteres suportado pelo PDF v1; não foi emitido.');
|
||||
$rows=[];
|
||||
foreach($lines as [$kind,$text]) {
|
||||
foreach(explode("\n",str_replace("\r",'', $text)) as $paragraph) {
|
||||
// <=50 glyphs even for the widest Helvetica letters; fixed A4 margins.
|
||||
$words=preg_split('/\s+/u',$paragraph); $wrapped='';
|
||||
foreach($words as $word) foreach(mb_str_split($word,50) as $part) {
|
||||
if(mb_strlen($wrapped.($wrapped===''?'':' ').$part)>50) { $rows[]=[$kind,$wrapped]; $wrapped=$part; }
|
||||
else $wrapped.=($wrapped===''?'':' ').$part;
|
||||
}
|
||||
if($wrapped!=='') $rows[]=[$kind,$wrapped];
|
||||
}
|
||||
}
|
||||
$pages=array_chunk($rows,44);
|
||||
$objects=[]; $add=function($text)use(&$objects){$objects[]=$text; return count($objects);};
|
||||
$add(''); $add(''); $font=$add('<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica /Encoding /WinAnsiEncoding >>'); $bold=$add('<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica-Bold /Encoding /WinAnsiEncoding >>'); $kids=[];
|
||||
$escape=function($s) { return str_replace(['\\','(',')'],['\\\\','\\(','\\)'],iconv('UTF-8','Windows-1252',$s)); };
|
||||
foreach($pages as $n=>$rows) {
|
||||
$stream="0.48 0.19 0.12 rg\nBT /F2 12 Tf 42 799 Td (".$escape('TESTE — SEM VALIDADE FISCAL').") Tj ET\n"; $y=766;
|
||||
foreach($rows as [$kind,$text]) { $f=$kind==='text'?'F1':'F2'; $size=$kind==='title'?13:10; $color=$kind==='section'?'0.09 0.34 0.28':'0.12 0.21 0.23'; $stream.="$color rg\nBT /$f $size Tf 42 $y Td (".$escape($text).") Tj ET\n"; $y-=15; }
|
||||
$stream.="0.4 0.4 0.4 rg\nBT /F1 8 Tf 42 30 Td (".$escape('TESTE — SEM VALIDADE FISCAL | Página '.($n+1).' / '.count($pages)).") Tj ET\n";
|
||||
$content=$add('<< /Length '.strlen($stream).">>\nstream\n".$stream.'endstream');
|
||||
$kids[]=$add("<< /Type /Page /Parent 2 0 R /MediaBox [0 0 595 842] /Resources << /Font << /F1 $font 0 R /F2 $bold 0 R >> >> /Contents $content 0 R >>");
|
||||
}
|
||||
$objects[0]='<< /Type /Catalog /Pages 2 0 R >>'; $objects[1]='<< /Type /Pages /Count '.count($kids).' /Kids ['.implode(' ',array_map(fn($id)=>"$id 0 R",$kids)).'] >>';
|
||||
$pdf="%PDF-1.4\n%\xE2\xE3\xCF\xD3\n"; $offset=[0];
|
||||
foreach($objects as $i=>$obj) { $offset[]=strlen($pdf); $pdf.=($i+1)." 0 obj\n$obj\nendobj\n"; }
|
||||
$xref=strlen($pdf); $pdf.='xref'."\n0 ".(count($objects)+1)."\n0000000000 65535 f \n";
|
||||
foreach(array_slice($offset,1) as $pos) $pdf.=sprintf('%010d 00000 n ',$pos)."\n";
|
||||
return $pdf.'trailer'."\n<< /Size ".(count($objects)+1).' /Root 1 0 R >>'."\nstartxref\n$xref\n%%EOF\n";
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,52 @@
|
||||
<?php
|
||||
namespace App\Modules\Services;
|
||||
|
||||
use App\Modules\Identity\Services\Audit;
|
||||
use App\Modules\Identity\Services\LocalDatabaseGuard;
|
||||
use App\Shared\Context\CompanyContext;
|
||||
use App\Shared\Testing\TestingDatabaseGuard;
|
||||
use Illuminate\Support\Facades\DB;
|
||||
use Illuminate\Support\Facades\Validator;
|
||||
|
||||
/** Local operator command only. No HTTP route or standing activation grant. */
|
||||
final class LocalFiscalActivation
|
||||
{
|
||||
public function execute(array $input,bool $apply=false): array
|
||||
{
|
||||
abort_unless(app()->runningInConsole(),403,'Operação exclusivamente no terminal local.');
|
||||
if (ServiceCalculation::isolated()) TestingDatabaseGuard::assertSafe();
|
||||
else abort_unless(LocalDatabaseGuard::allows(),403,'Base própria de desenvolvimento local obrigatória.');
|
||||
$rules=['proposal_id'=>'required|integer|min:1','version'=>'required|integer|min:1','identifier'=>'required|string','tenant_id'=>'required|integer|min:1','company_id'=>'required|integer|min:1','unit_id'=>'required|integer|min:1','service_id'=>'required|integer|min:1','service_version'=>'required|integer|min:1','valid_from'=>'required|date_format:Y-m-d','valid_until'=>'nullable|date_format:Y-m-d|after_or_equal:valid_from','operator_id'=>'required|integer|min:1','definition_hash'=>($apply?'required':'nullable').'|string|regex:/^[a-f0-9]{64}$/D'];
|
||||
abort_if(array_diff(array_keys($input),array_keys($rules))!==[],422);
|
||||
$in=Validator::make($input,$rules)->validate();
|
||||
return DB::transaction(function() use($in,$apply) {
|
||||
$scope=array_intersect_key($in,array_flip(['tenant_id','company_id','unit_id']));
|
||||
DB::table('companies')->where('id',$scope['company_id'])->where('tenant_id',$scope['tenant_id'])->lockForUpdate()->firstOrFail();
|
||||
app(CompanyContext::class)->selectFor((int)$in['operator_id'],(int)$scope['tenant_id'],(int)$scope['company_id'],(int)$scope['unit_id']);
|
||||
app(\App\Modules\Identity\Services\Permissions::class)->require((int)$in['operator_id'],(int)$scope['tenant_id'],(int)$scope['company_id'],'service_fiscal.view');
|
||||
$p=DB::table('sf_proposals')->where($scope)->where('id',$in['proposal_id'])->where('kind','profile')->where('identifier',$in['identifier'])->where('version',$in['version'])->first();
|
||||
abort_unless($p,409,'Perfil, versão ou âmbito diferente da operação autorizada.');
|
||||
$d=json_decode($p->data,true,32,JSON_THROW_ON_ERROR);
|
||||
foreach(['service_id','service_version'] as $key) abort_unless((int)$d[$key]===(int)$in[$key],409,'Serviço/versão diferente.');
|
||||
abort_unless($d['valid_from']===$in['valid_from'] && ($d['valid_until'] ?? null)===($in['valid_until'] ?? null),409,'Vigência diferente.');
|
||||
abort_unless($d['currency']==='MZN' && $d['price_mode']==='added' && $d['rate_percent']==='16' && $d['treatment']==='domestic_normal',409,'Tratamento diferente do recorte aprovado.');
|
||||
abort_unless(DB::table('a_services')->where('id',$in['service_id'])->where('tenant_id',$scope['tenant_id'])->where('company_id',$scope['company_id'])->where('version',$in['service_version'])->exists(),409,'Serviço desactualizado.');
|
||||
abort_unless(DB::table('sf_decisions')->where('proposal_id',$p->id)->where('decision','approved')->exists(),409,'Aprovação exacta em falta.');
|
||||
abort_if(DB::table('sf_proposals')->where($scope)->where('kind','profile')->where('identifier',$p->identifier)->where('version','>',$p->version)->whereExists(fn($q)=>$q->selectRaw('1')->from('sf_decisions')->whereColumn('sf_decisions.proposal_id','sf_proposals.id')->where('decision','approved'))->exists(),409,'Outra versão já foi aprovada; reveja a operação.');
|
||||
$profile=DB::table('service_calculation_profiles')->where($scope)->where('id',$p->profile_id)->where('identifier',$p->identifier)->where('version',$p->version)->first();
|
||||
abort_unless($profile,409,'Perfil de cálculo incompatível.');
|
||||
$definition=json_decode($profile->definition,true,32,JSON_THROW_ON_ERROR);
|
||||
abort_unless(($definition['kind'] ?? null)==='real' && ($definition['policy'] ?? null)===ServiceCalculation::POLICY,409,'Política/perfil incompatível.');
|
||||
foreach($d as $key=>$value) abort_unless(($definition[$key] ?? null)===$value,409,'Definição diverge da proposta aprovada.');
|
||||
$hash=hash('sha256',json_encode([$p->id,(int)$p->version,$scope,$d,$definition],JSON_THROW_ON_ERROR));
|
||||
if($apply) abort_unless(hash_equals($hash,$in['definition_hash']),409,'A definição não corresponde à operação revista.');
|
||||
$last=DB::table('sf_activation_events')->where('proposal_id',$p->id)->orderByDesc('id')->first();
|
||||
$active=(bool)($last?->active ?? false);
|
||||
$result=['proposal_id'=>$p->id,'identifier'=>$p->identifier,'version'=>(int)$p->version,'scope'=>$scope,'service_id'=>(int)$d['service_id'],'service_version'=>(int)$d['service_version'],'valid_from'=>$d['valid_from'],'valid_until'=>$d['valid_until'] ?? null,'definition_hash'=>$hash,'active'=>$active,'applied'=>false];
|
||||
if(!$apply || $active) return $result+['replayed'=>$apply && $active];
|
||||
$event=DB::table('sf_activation_events')->insertGetId(['proposal_id'=>$p->id,'actor_id'=>$in['operator_id'],'active'=>true,'reason'=>'Operação local especificamente autorizada pelo utilizador para este perfil/versão/âmbito; apenas cálculo proposto, sem emissão, recebimentos ou lançamentos. Definição SHA256: '.$hash,'created_at'=>now()]);
|
||||
Audit::record('service_fiscal.local_activated',(int)$in['operator_id'],(int)$scope['tenant_id'],(int)$scope['company_id'],(int)$scope['unit_id'],details:['record_id'=>$p->id,'version'=>(int)$p->version,'event_id'=>$event,'reason'=>'Activação local especificamente autorizada; sem poderes de emissão ou lançamentos.']);
|
||||
return array_replace($result,['active'=>true,'applied'=>true,'event_id'=>$event,'replayed'=>false]);
|
||||
});
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,52 @@
|
||||
<?php
|
||||
|
||||
namespace App\Modules\Services;
|
||||
|
||||
use App\Modules\Identity\Services\Audit;
|
||||
use App\Modules\Identity\Services\Permissions;
|
||||
use App\Shared\Context\CompanyContext;
|
||||
use Illuminate\Support\Facades\DB;
|
||||
|
||||
final class ServiceAccess
|
||||
{
|
||||
public function __construct(private ServiceWorkflow $workflow, private CompanyContext $context, private Permissions $permissions) {}
|
||||
|
||||
public function listing(string $area, int $actor): array
|
||||
{
|
||||
$scope = $this->workflow->scope($area, $actor, 'manage');
|
||||
$grants = DB::table('permission_grants as g')->join('users as u', 'u.id', '=', 'g.user_id')->where('g.tenant_id', $scope['tenant_id'])->where('g.company_id', $scope['company_id'])->where('g.unit_id', $scope['unit_id'])->whereIn('g.permission', array_map(fn ($action) => "$area.$action", ServicePermissions::ACTIONS))
|
||||
->orderBy('u.name')->get(['g.id','g.permission','g.unit_id','u.name','u.email']);
|
||||
$actions = array_values(array_filter(ServicePermissions::ACTIONS, fn ($action) => $this->permissions->has($actor, $scope['tenant_id'], $scope['company_id'], "$area.$action", $scope['unit_id'])));
|
||||
return ['grants' => $grants, 'actions' => $actions, 'scope' => $scope];
|
||||
}
|
||||
|
||||
public function change(string $area, int $actor, array $input): void
|
||||
{
|
||||
$scope = $this->workflow->scope($area, $actor, 'manage'); $selected = $this->context->unitId();
|
||||
DB::transaction(function () use ($area, $actor, $input, $scope, $selected): void {
|
||||
DB::table('companies')->where('id', $scope['company_id'])->lockForUpdate()->firstOrFail();
|
||||
$this->context->selectFor($actor, $scope['tenant_id'], $scope['company_id'], $selected);
|
||||
$this->workflow->scope($area, $actor, 'manage');
|
||||
$permission = "$area.".$input['action'];
|
||||
abort_unless(in_array($input['action'], ServicePermissions::ACTIONS, true), 422);
|
||||
$this->permissions->require($actor, $scope['tenant_id'], $scope['company_id'], $permission, $scope['unit_id']);
|
||||
$target = DB::table('users')->where('email', mb_strtolower($input['email']))->first(['id']);
|
||||
abort_unless($target, 422, 'Utilizador inexistente; nenhuma conta é criada por concessão.');
|
||||
$this->permissions->require($target->id, $scope['tenant_id'], $scope['company_id'], 'company.view');
|
||||
if ($scope['unit_id']) { $this->permissions->require($target->id, $scope['tenant_id'], $scope['company_id'], 'unit.view', $scope['unit_id']); }
|
||||
$query = DB::table('permission_grants')->where('tenant_id', $scope['tenant_id'])->where('company_id', $scope['company_id'])->where('unit_id', $scope['unit_id'])->where('user_id', $target->id);
|
||||
if ($input['grant']) {
|
||||
if ($input['action'] !== 'view') { $this->permissions->require($target->id, $scope['tenant_id'], $scope['company_id'], "$area.view", $scope['unit_id']); }
|
||||
DB::table('permission_grants')->insertOrIgnore($scope + ['user_id' => $target->id, 'permission' => $permission, 'created_at' => now(), 'updated_at' => now()]);
|
||||
$changed = [['permission' => $permission, 'unit_id' => $scope['unit_id']]];
|
||||
} else {
|
||||
$query->whereIn('permission', $input['action'] === 'view' ? array_map(fn ($action) => "$area.$action", ServicePermissions::ACTIONS) : [$permission]);
|
||||
$changed = $query->get(['permission','unit_id'])->map(fn ($row) => (array) $row)->all();
|
||||
foreach ($changed as $row) { $this->permissions->require($actor, $scope['tenant_id'], $scope['company_id'], $row['permission'], $scope['unit_id']); }
|
||||
$query->delete();
|
||||
}
|
||||
Audit::record($input['grant'] ? 'a.access.granted' : 'a.access.revoked', $actor, $scope['tenant_id'], $scope['company_id'], $scope['unit_id'], $target->id,
|
||||
['permission' => $permission, 'reason' => $input['reason'], 'grants' => $changed]);
|
||||
});
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,128 @@
|
||||
<?php
|
||||
|
||||
namespace App\Modules\Services;
|
||||
|
||||
use App\Modules\Identity\Services\Audit;
|
||||
use App\Shared\Context\CompanyContext;
|
||||
use App\Shared\Testing\TestingDatabaseGuard;
|
||||
use Brick\Math\BigDecimal;
|
||||
use Brick\Math\RoundingMode;
|
||||
use Illuminate\Support\Facades\DB;
|
||||
|
||||
final class ServiceCalculation
|
||||
{
|
||||
public const POLICY = 'SGF-SERVICE-NET-VAT-TRUNCATE2-v1';
|
||||
public const SOURCES = ['InvesteMoz/ficha-IVA-GERAL-BASE-LIQUIDA-v1.md@v1.2', 'Lei22/2022-republicada:17(1)', 'CIVA:15,7,8,17(2)'];
|
||||
|
||||
public function __construct(private ServiceWorkflow $workflow, private DocumentPreparation $preparation, private CompanyContext $context) {}
|
||||
|
||||
public static function isolated(): bool { return app()->environment(['testing','browser-testing']); }
|
||||
|
||||
public static function evaluateReal(array $data, array $prepared, array $profile): array
|
||||
{
|
||||
abort_unless(($profile['kind'] ?? null)==='real',422,'Perfil real identificado obrigatório.');
|
||||
// Shared decimal arithmetic; authority/applicability is checked by ServiceFiscal before calling.
|
||||
$result=self::evaluate($data,$prepared,array_replace($profile,['kind'=>'synthetic']));
|
||||
if ($result['state']!=='pending') $result['state']='real_proposed_conditioned';
|
||||
return $result;
|
||||
}
|
||||
|
||||
public static function evaluate(array $data, array $prepared, ?array $profile): array
|
||||
{
|
||||
$pending = [];
|
||||
if (count($data['lines'] ?? []) !== 1) { $pending[] = 'Apenas uma linha de serviço é suportada.'; }
|
||||
if (($prepared['price_mode'] ?? null) !== 'added') { $pending[] = 'É necessário preço sem imposto (acrescido); incluído fica fora deste âmbito.'; }
|
||||
if (!preg_match('/^[A-Z]{3}$/D', $data['currency'] ?? '')) { $pending[] = 'Moeda explícita em falta.'; }
|
||||
if (!$profile || ($profile['kind'] ?? null) !== 'synthetic' || ($profile['policy'] ?? null) !== self::POLICY) { $pending[] = 'Perfil de ensaio e política identificados em falta ou incompatíveis.'; }
|
||||
if (!preg_match('/^\d{1,3}(\.\d{1,8})?$/D', $profile['rate_percent'] ?? '') || BigDecimal::of($profile['rate_percent'] ?? '0')->isLessThanOrEqualTo(0)) { $pending[] = 'Taxa positiva identificada em falta.'; }
|
||||
if (($profile['currency'] ?? null) !== ($data['currency'] ?? null)) { $pending[] = 'Moeda incompatível com o perfil.'; }
|
||||
$line = $data['lines'][0] ?? [];
|
||||
foreach (['quantity','unit_price'] as $field) {
|
||||
if (!is_string($line[$field] ?? null) || !preg_match('/^\d{1,16}(\.\d{1,8})?$/D', $line[$field])) { $pending[] = 'Quantidade/preço ausente ou fora dos limites exactos de A.'; }
|
||||
}
|
||||
if (!$pending && BigDecimal::of($line['quantity'])->isLessThanOrEqualTo(0)) { $pending[] = 'Quantidade deve ser positiva.'; }
|
||||
if ($pending) { return ['state' => 'pending', 'pending' => array_values(array_unique($pending)), 'policy' => self::POLICY]; }
|
||||
$base = BigDecimal::of($line['quantity'])->multipliedBy($line['unit_price']);
|
||||
$exact = $base->multipliedBy($profile['rate_percent'])->multipliedBy('0.01');
|
||||
$document = $exact->toScale(2, RoundingMode::DOWN);
|
||||
$representable = $base->stripTrailingZeros()->getScale() <= 2;
|
||||
return ['state' => $representable ? 'synthetic_proposed' : 'synthetic_base_representation_pending', 'policy' => self::POLICY,
|
||||
'base_exact' => (string) $base->stripTrailingZeros(), 'vat_exact' => (string) $exact->stripTrailingZeros(),
|
||||
'vat_document_proposed' => (string) $document, 'discarded_difference' => (string) $exact->minus($document)->stripTrailingZeros(),
|
||||
'total_document_proposed' => $representable ? (string) $base->plus($document)->toScale(2) : null,
|
||||
'currency' => $data['currency'], 'pending' => $representable ? [] : ['Política de representação da base/total pendente; base não truncada.'],
|
||||
'fiscally_validated' => false, 'policy_basis' => 'Decisão operacional do utilizador; não obrigação legal comprovada.'];
|
||||
}
|
||||
|
||||
private function sources(int $draft, int $actor): array
|
||||
{
|
||||
$billing = $this->workflow->show('billing_drafts', $draft, $actor);
|
||||
abort_if($billing['internal_confirmation'], 409, 'Fotografia B1 preservada; cálculo não altera confirmações.');
|
||||
$prepared = $this->preparation->show('billing_drafts', $draft, $actor);
|
||||
return [$billing, $prepared];
|
||||
}
|
||||
|
||||
private function input(array $b, array $p, object $profile): array
|
||||
{
|
||||
return ['draft_id' => (int) $b['id'], 'draft_version' => $b['version'], 'preparation_version' => $p['version'],
|
||||
'data' => $b['data'], 'prepared' => $p['data'], 'profile_id' => (int) $profile->id,
|
||||
'profile_version' => (int) $profile->version, 'profile_identifier' => $profile->identifier,
|
||||
'profile' => json_decode($profile->definition, true, 32, JSON_THROW_ON_ERROR), 'policy' => self::POLICY,
|
||||
'source_current_version' => (int) DB::table('a_service_drafts')->where('id',$b['source_id'])->where('tenant_id',$b['tenant_id'])->where('company_id',$b['company_id'])->where('unit_id',$b['unit_id'])->value('version')];
|
||||
}
|
||||
private function fingerprint(array $input): string { return hash('sha256', json_encode($input, JSON_THROW_ON_ERROR)); }
|
||||
|
||||
public function calculate(int $draft, int $actor, array $command): array
|
||||
{
|
||||
// Test-only command is deliberately not a fiscal permission or real profile activation path.
|
||||
abort_unless(self::isolated(), 403, 'Cálculo de ensaio restrito ao ambiente isolado de testes.');
|
||||
TestingDatabaseGuard::assertSafe();
|
||||
$scope = $this->workflow->scope('billing_drafts', $actor, 'edit');
|
||||
return DB::transaction(function () use ($draft,$actor,$command,$scope) {
|
||||
DB::table('companies')->where('id', $scope['company_id'])->lockForUpdate()->firstOrFail();
|
||||
$this->context->selectFor($actor, $scope['tenant_id'], $scope['company_id'], $scope['unit_id']);
|
||||
$this->workflow->scope('billing_drafts', $actor, 'edit');
|
||||
[$b,$p] = $this->sources($draft,$actor);
|
||||
abort_unless($b['version'] === $command['draft_version'] && $p['version'] === $command['preparation_version'], 409, 'Versões desactualizadas.');
|
||||
abort_unless(($p['data']['draft_version'] ?? null) === $b['version'], 409, 'Reveja a preparação após alterar o rascunho.');
|
||||
$profile = DB::table('service_calculation_profiles')->where($scope)->where('id', $command['profile_id'])->first();
|
||||
abort_unless($profile, 403, 'Perfil fora do âmbito autorizado.');
|
||||
$latest = DB::table('service_calculation_profiles')->where($scope)->where('identifier', $profile->identifier)->max('version');
|
||||
abort_unless((int) $latest === (int) $profile->version && (int) $profile->version === $command['profile_version'], 409, 'Perfil desactualizado.');
|
||||
$input = $this->input($b,$p,$profile);
|
||||
abort_unless($input['source_current_version'] === $b['data']['source_version'], 409, 'Prestação de origem desactualizada.');
|
||||
$result = self::evaluate($b['data'],$p['data'],$input['profile']);
|
||||
abort_if($result['state'] === 'pending', 422, implode(' ', $result['pending']));
|
||||
$hash = $this->fingerprint($input);
|
||||
$old = DB::table('service_calculation_results')->where('billing_draft_id',$draft)->where('fingerprint',$hash)->first();
|
||||
if ($old) { return ['id' => $old->id, 'replayed' => true]; }
|
||||
$id = DB::table('service_calculation_results')->insertGetId($scope + ['billing_draft_id'=>$draft, 'profile_id'=>$profile->id, 'actor_id'=>$actor,
|
||||
'fingerprint'=>$hash, 'snapshot'=>json_encode(['input'=>$input,'result'=>$result],JSON_THROW_ON_ERROR), 'created_at'=>now()]);
|
||||
Audit::record('service_calculation.synthetic_created',$actor,$scope['tenant_id'],$scope['company_id'],$scope['unit_id'],details:['result_id'=>$id,'policy'=>self::POLICY]);
|
||||
return ['id'=>$id,'replayed'=>false];
|
||||
});
|
||||
}
|
||||
|
||||
public function read(int $draft, int $actor): array
|
||||
{
|
||||
$scope = $this->workflow->scope('billing_drafts',$actor,'view');
|
||||
if (!self::isolated()) { return ['environment'=>'normal','history'=>[], 'pending'=>['O cálculo proposto requer perfil aprovado, activo e compatível e decisão temporal aprovada. Consulte o resultado e as pendências abaixo, quando disponíveis.']]; }
|
||||
TestingDatabaseGuard::assertSafe();
|
||||
[$b,$p] = $this->sources($draft,$actor);
|
||||
$profiles = DB::table('service_calculation_profiles')->where($scope)->whereRaw("definition->>'kind' = ?",['synthetic'])->orderByDesc('version')->get();
|
||||
$latest = []; foreach ($profiles as $profile) { $latest[$profile->identifier] ??= $profile; }
|
||||
$history = [];
|
||||
foreach (DB::table('service_calculation_results')->where($scope)->where('billing_draft_id',$draft)->orderByDesc('id')->get() as $row) {
|
||||
$snapshot = json_decode($row->snapshot,true,32,JSON_THROW_ON_ERROR);
|
||||
if (isset($snapshot['input']['profile_proposal_id'])) continue;
|
||||
$profile = $latest[$snapshot['input']['profile_identifier']] ?? null;
|
||||
$current = $profile && hash_equals($row->fingerprint,$this->fingerprint($this->input($b,$p,$profile)));
|
||||
$history[] = ['id'=>$row->id,'current'=>(bool)$current,'snapshot'=>$snapshot];
|
||||
}
|
||||
return ['environment'=>'synthetic_test_only','policy'=>self::POLICY,'history'=>$history,
|
||||
'can_calculate'=>app(\App\Modules\Identity\Services\Permissions::class)->has($actor,$scope['tenant_id'],$scope['company_id'],'billing_drafts.edit',$scope['unit_id']),
|
||||
'profiles'=>array_map(fn ($r)=>['id'=>$r->id,'version'=>(int)$r->version,'identifier'=>$r->identifier],array_values($latest)),
|
||||
'draft_version'=>$b['version'],'preparation_version'=>$p['version'],
|
||||
'pending'=>['ENSAIO SINTÉTICO — não valida regime, base tributável, data fiscal ou emissão da empresa real.']];
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,181 @@
|
||||
<?php
|
||||
|
||||
namespace App\Modules\Services;
|
||||
|
||||
use App\Modules\Identity\Services\Audit;
|
||||
use App\Modules\Identity\Services\Permissions;
|
||||
use App\Shared\Context\CompanyContext;
|
||||
use App\Shared\Testing\TestingDatabaseGuard;
|
||||
use Illuminate\Support\Facades\DB;
|
||||
use Illuminate\Support\Facades\Validator;
|
||||
|
||||
/** Fiscal decisions are separate from arithmetic, catalogue accounting and emission. */
|
||||
final class ServiceFiscal
|
||||
{
|
||||
public function __construct(private CompanyContext $context, private Permissions $permissions, private ServiceWorkflow $workflow, private DocumentPreparation $preparation) {}
|
||||
|
||||
private function scope(int $actor, string $action = 'view'): array
|
||||
{
|
||||
$s=$this->context->identifiers(); $unit=$this->context->unitId();
|
||||
abort_unless($actor===$this->context->userId() && $unit!==null,403,'Seleccione uma unidade autorizada.');
|
||||
$this->permissions->require($actor,$s['tenant_id'],$s['company_id'],'unit.view',$unit);
|
||||
foreach (array_unique(['view',$action]) as $a) $this->permissions->require($actor,$s['tenant_id'],$s['company_id'],'service_fiscal.'.$a,$a==='calculate' ? $unit : null);
|
||||
return $s+['unit_id'=>$unit];
|
||||
}
|
||||
private function command(int $actor,string $action,callable $fn): array
|
||||
{
|
||||
$s=$this->scope($actor,$action);
|
||||
return DB::transaction(function() use($actor,$action,$fn,$s) {
|
||||
DB::table('companies')->where('id',$s['company_id'])->lockForUpdate()->firstOrFail();
|
||||
$this->context->selectFor($actor,$s['tenant_id'],$s['company_id'],$s['unit_id']); $this->scope($actor,$action);
|
||||
return $fn($s);
|
||||
});
|
||||
}
|
||||
private function row(int $id,array $s): object
|
||||
{
|
||||
$r=DB::table('sf_proposals')->where($s)->where('id',$id)->first(); abort_unless($r,403,'Proposta fora do âmbito.'); return $r;
|
||||
}
|
||||
private function data(object $r): array { return json_decode($r->data,true,32,JSON_THROW_ON_ERROR); }
|
||||
private function decision(int $id): ?object { return DB::table('sf_decisions')->where('proposal_id',$id)->first(); }
|
||||
private function approved(object $r): bool { return $this->decision($r->id)?->decision==='approved'; }
|
||||
private function activated(object $r): bool { return (bool)(DB::table('sf_activation_events')->where('proposal_id',$r->id)->orderByDesc('id')->first()?->active ?? false); }
|
||||
private function latest(object $r,array $s,?string $date=null): bool
|
||||
{
|
||||
// Pending/refused proposals do not supersede a currently approved version.
|
||||
$q=DB::table('sf_proposals')->where($s)->where('kind',$r->kind)->where('identifier',$r->identifier)->where('version','>',$r->version)
|
||||
->whereExists(fn($q)=>$q->selectRaw('1')->from('sf_decisions')->whereColumn('sf_decisions.proposal_id','sf_proposals.id')->where('decision','approved'));
|
||||
if($r->kind==='profile' && $date!==null) $q->whereRaw("data->>'valid_from' <= ?",[$date]);
|
||||
return !$q->exists();
|
||||
}
|
||||
private function exact(array $data,array $rules): array
|
||||
{
|
||||
abort_if(array_diff(array_keys($data),array_keys($rules))!==[],422,'Campo protegido ou fora do âmbito fiscal.');
|
||||
return Validator::make($data,$rules)->validate();
|
||||
}
|
||||
public function listing(int $actor): array
|
||||
{
|
||||
$s=$this->scope($actor);
|
||||
if (!\Illuminate\Support\Facades\Schema::hasTable('sf_proposals')) return ['migration_pending'=>true,'proposals'=>[]];
|
||||
$rows=DB::table('sf_proposals')->where($s)->orderByDesc('id')->get()->map(function($r) { return (array)$r+['definition'=>$this->data($r),'decision'=>$this->decision($r->id),'active'=>$r->kind==='profile' && $this->activated($r)]; })->all();
|
||||
return ['proposals'=>$rows,'migration_pending'=>false,'notice'=>'RASCUNHO — SEM VALIDADE FISCAL; aprovação não activa o perfil.'];
|
||||
}
|
||||
public function propose(int $actor,array $input): array
|
||||
{
|
||||
return $this->command($actor,'propose',function($s) use($actor,$input) {
|
||||
$in=$this->exact($input,['kind'=>'required|in:profile,temporal','identifier'=>'required|string|max:100|regex:/^[A-Za-z0-9_-]+$/D','previous_id'=>'nullable|integer|min:1','data'=>'required|array']);
|
||||
$previous=isset($in['previous_id']) ? $this->row((int)$in['previous_id'],$s) : null;
|
||||
$last=DB::table('sf_proposals')->where($s)->where('kind',$in['kind'])->where('identifier',$in['identifier'])->orderByDesc('version')->first();
|
||||
abort_unless(($last?->id ?? null)===($previous?->id ?? null),409,'Indique a versão anterior exacta.');
|
||||
$version=(int)($last?->version ?? 0)+1;
|
||||
if ($in['kind']==='profile') {
|
||||
$d=$this->exact($in['data'],['service_id'=>'required|integer|min:1','service_version'=>'required|integer|min:1','currency'=>'required|in:MZN','price_mode'=>'required|in:added','rate_percent'=>'required|in:16','valid_from'=>'required|date_format:Y-m-d','valid_until'=>'nullable|date_format:Y-m-d|after_or_equal:valid_from','treatment'=>'required|in:domestic_normal','conditions'=>'required|string|max:4000','evidence'=>'required|string|max:4000']);
|
||||
$service=DB::table('a_services')->where('tenant_id',$s['tenant_id'])->where('company_id',$s['company_id'])->where('id',$d['service_id'])->first();
|
||||
abort_unless($service && (int)$service->version===(int)$d['service_version'],409,'Serviço/versão incompatível.');
|
||||
if ($previous) abort_unless((int)$this->data($previous)['service_id']===(int)$d['service_id'],422,'Nova versão não pode trocar a identidade do serviço.');
|
||||
abort_if(DB::table('sf_proposals')->where($s)->where('kind','profile')->whereRaw("data->>'service_id' = ?",[(string)$d['service_id']])->where('identifier','<>',$in['identifier'])->exists(),409,'Use a identidade existente deste serviço e uma nova versão.');
|
||||
$profile=DB::table('service_calculation_profiles')->insertGetId($s+['identifier'=>$in['identifier'],'version'=>$version,'definition'=>json_encode($d+['kind'=>'real','policy'=>ServiceCalculation::POLICY,'sources'=>ServiceCalculation::SOURCES+['fiscal_2026'=>'Lei10/2025:6,32;vigencia2026-01-01']],JSON_THROW_ON_ERROR),'created_at'=>now()]);
|
||||
$draft=null;
|
||||
} else {
|
||||
$d=$this->exact($in['data'],['profile_proposal_id'=>'required|integer|min:1','draft_id'=>'required|integer|min:1','draft_version'=>'required|integer|min:1','preparation_version'=>'required|integer|min:0','reference_date'=>'required|date_format:Y-m-d','reference_basis'=>'required|string|max:2000','period_start'=>'required|date_format:Y-m-d','period_end'=>'nullable|date_format:Y-m-d|after_or_equal:period_start','next_billing'=>'nullable|date_format:Y-m-d','event'=>'required|in:pending,invoice_in_time,invoice_deadline','event_date'=>'nullable|required_unless:event,pending|date_format:Y-m-d','evidence'=>'required|string|max:4000']);
|
||||
abort_if($d['event']==='pending' && !empty($d['event_date']),422,'Pendência temporal não tem data de exigibilidade.');
|
||||
abort_if($d['event']!=='pending' && $d['reference_date']!==$d['event_date'],422,'A referência de vigência deve corresponder à exigibilidade fundamentada quando determinada.');
|
||||
$p=$this->row((int)$d['profile_proposal_id'],$s); abort_unless($p->kind==='profile' && $this->approved($p),422,'Perfil exacto aprovado necessário.');
|
||||
[$b,$prepared]=$this->draft((int)$d['draft_id'],$actor);
|
||||
$this->versions($b,$prepared,$d);
|
||||
abort_unless(($prepared['data']['period_start'] ?? null)===$d['period_start'] && ($prepared['data']['period_end'] ?? null)===($d['period_end'] ?? null),409,'Período deve corresponder à preparação revista.');
|
||||
if ($previous) abort_unless((int)$previous->draft_id===(int)$d['draft_id'],422,'Decisão temporal pertence ao mesmo rascunho.');
|
||||
abort_if(DB::table('sf_proposals')->where($s)->where('kind','temporal')->where('draft_id',$d['draft_id'])->where('identifier','<>',$in['identifier'])->exists(),409,'Use a identidade temporal existente e uma nova versão.');
|
||||
$profile=$p->profile_id; $draft=$d['draft_id'];
|
||||
}
|
||||
$id=DB::table('sf_proposals')->insertGetId($s+['kind'=>$in['kind'],'identifier'=>$in['identifier'],'version'=>$version,'previous_id'=>$previous?->id,'profile_id'=>$profile,'draft_id'=>$draft,'data'=>json_encode($d,JSON_THROW_ON_ERROR),'actor_id'=>$actor,'created_at'=>now()]);
|
||||
Audit::record('service_fiscal.proposed',$actor,$s['tenant_id'],$s['company_id'],$s['unit_id'],details:['proposal_id'=>$id,'version'=>$version,'kind'=>$in['kind']]);
|
||||
return ['id'=>$id,'version'=>$version,'active'=>false];
|
||||
});
|
||||
}
|
||||
public function decide(int $id,int $actor,array $input): array
|
||||
{
|
||||
return $this->command($actor,'approve',function($s) use($id,$actor,$input) {
|
||||
$d=$this->exact($input,['version'=>'required|integer|min:1','decision'=>'required|in:approved,refused','reason'=>'required|string|max:4000']);
|
||||
$r=$this->row($id,$s); abort_unless((int)$r->version===(int)$d['version'] && (int)$r->actor_id!==$actor,403,'Versão exacta e validador distinto obrigatórios.');
|
||||
abort_if($this->decision($id),409,'Decisão imutável; correcção exige nova versão.');
|
||||
if ($r->kind==='temporal' && $d['decision']==='approved') {
|
||||
$data=$this->data($r); [$b,$p]=$this->draft((int)$r->draft_id,$actor); $this->versions($b,$p,$data);
|
||||
$profile=$this->row((int)$data['profile_proposal_id'],$s); $this->compatible($profile,$s,$data['reference_date'],$b,$p,false);
|
||||
}
|
||||
DB::table('sf_decisions')->insert(['proposal_id'=>$id,'actor_id'=>$actor,'decision'=>$d['decision'],'reason'=>$d['reason'],'created_at'=>now()]);
|
||||
Audit::record('service_fiscal.decided',$actor,$s['tenant_id'],$s['company_id'],$s['unit_id'],details:['proposal_id'=>$id,'version'=>$r->version,'decision'=>$d['decision']]);
|
||||
return ['id'=>$id,'decision'=>$d['decision'],'active'=>false];
|
||||
});
|
||||
}
|
||||
/** No HTTP activation endpoint. Only isolated proofs may exercise active/revoked states in this increment. */
|
||||
public function proofActivation(int $id,int $actor,int $version,bool $active): void
|
||||
{
|
||||
abort_unless(ServiceCalculation::isolated(),403,'Activação real não autorizada neste incremento.'); TestingDatabaseGuard::assertSafe();
|
||||
$this->command($actor,'approve',function($s) use($id,$actor,$version,$active) {
|
||||
$p=$this->row($id,$s); abort_unless($p->kind==='profile' && (int)$p->version===$version && $this->approved($p) && $this->latest($p,$s),409);
|
||||
DB::table('sf_activation_events')->insert(['proposal_id'=>$id,'actor_id'=>$actor,'active'=>$active,'reason'=>'Prova sintética isolada; não é activação real.','created_at'=>now()]);
|
||||
Audit::record('service_fiscal.proof_activation',$actor,$s['tenant_id'],$s['company_id'],$s['unit_id'],details:['proposal_id'=>$id,'version'=>$version,'active'=>$active]);
|
||||
return [];
|
||||
});
|
||||
}
|
||||
private function draft(int $id,int $actor): array
|
||||
{
|
||||
$b=$this->workflow->show('billing_drafts',$id,$actor); abort_if($b['internal_confirmation'],409,'B1 preservada.');
|
||||
return [$b,$this->preparation->show('billing_drafts',$id,$actor)];
|
||||
}
|
||||
private function versions(array $b,array $p,array $d): void
|
||||
{
|
||||
abort_unless($b['version']===(int)$d['draft_version'] && $p['version']===(int)$d['preparation_version'] && ($p['data']['draft_version'] ?? null)===$b['version'],409,'Rascunho/preparação desactualizados.');
|
||||
$current=DB::table('a_service_drafts')->where('id',$b['source_id'])->value('version');
|
||||
abort_unless((int)$current===(int)$b['data']['source_version'],409,'Origem desactualizada.');
|
||||
}
|
||||
private function compatible(object $p,array $s,string $date,array $b,array $prepared,bool $active=true): array
|
||||
{
|
||||
$d=$this->data($p); $line=$b['data']['lines'][0] ?? [];
|
||||
abort_unless($p->kind==='profile' && $this->approved($p) && (!$active || $this->activated($p)) && $this->latest($p,$s,$date),409,'Perfil sem aprovação/activação exacta ou substituído.');
|
||||
abort_unless($date!=='' && $d['valid_from']<=$date && (empty($d['valid_until']) || $date<=$d['valid_until']),422,'Vigência não demonstrada.');
|
||||
$service=DB::table('a_services')->where('tenant_id',$s['tenant_id'])->where('company_id',$s['company_id'])->where('id',$d['service_id'])->first();
|
||||
abort_unless($service && (int)$service->version===(int)$d['service_version'] && count($b['data']['lines'])===1 && (int)($line['service_id'] ?? 0)===(int)$d['service_id'] && $b['data']['currency']===$d['currency'] && ($prepared['data']['price_mode'] ?? null)===$d['price_mode'],422,'Serviço, moeda ou modo incompatível.');
|
||||
return $d;
|
||||
}
|
||||
public function calculate(int $draft,int $actor,array $input): array
|
||||
{
|
||||
return $this->command($actor,'calculate',function($s) use($draft,$actor,$input) {
|
||||
$d=$this->exact($input,['profile_proposal_id'=>'required|integer|min:1','profile_version'=>'required|integer|min:1','temporal_proposal_id'=>'required|integer|min:1','temporal_version'=>'required|integer|min:1','draft_version'=>'required|integer|min:1','preparation_version'=>'required|integer|min:0']);
|
||||
[$b,$prepared]=$this->draft($draft,$actor); $this->versions($b,$prepared,$d);
|
||||
$p=$this->row((int)$d['profile_proposal_id'],$s); $t=$this->row((int)$d['temporal_proposal_id'],$s);
|
||||
abort_unless((int)$p->version===(int)$d['profile_version'] && $t->kind==='temporal' && (int)$t->version===(int)$d['temporal_version'] && (int)$t->draft_id===$draft && (int)$t->profile_id===(int)$p->profile_id && $this->approved($t) && $this->latest($t,$s),409,'Decisão temporal exacta e aprovada necessária.');
|
||||
$td=$this->data($t); $this->versions($b,$prepared,$td);
|
||||
$definition=$this->compatible($p,$s,$td['reference_date'],$b,$prepared);
|
||||
$profile=json_decode(DB::table('service_calculation_profiles')->where('id',$p->profile_id)->value('definition'),true,32,JSON_THROW_ON_ERROR);
|
||||
$result=ServiceCalculation::evaluateReal($b['data'],$prepared['data'],$profile);
|
||||
abort_if($result['state']==='pending',422,implode(' ',$result['pending']));
|
||||
$pending=$td['event']==='pending';
|
||||
$result['temporal_state']=$pending ? 'temporal_pending' : 'temporal_decision_validated';
|
||||
$result['exigibility_date']=$pending ? null : $td['event_date'];
|
||||
$result['assessment_period']=$pending ? null : substr($td['event_date'],0,7);
|
||||
if ($pending) $result['pending'][]='Exigibilidade e período de apuramento não determinados; resultado condicionado.';
|
||||
$input=['draft_id'=>$draft,'draft_version'=>$b['version'],'preparation_version'=>$prepared['version'],'profile_proposal_id'=>$p->id,'profile_id'=>$p->profile_id,'profile_version'=>(int)$p->version,'profile_identifier'=>$p->identifier,'profile'=>$profile,'temporal_proposal_id'=>$t->id,'temporal_version'=>(int)$t->version,'temporal'=>$td,'data'=>$b['data'],'prepared'=>$prepared['data'],'policy'=>ServiceCalculation::POLICY];
|
||||
$hash=hash('sha256',json_encode($input,JSON_THROW_ON_ERROR));
|
||||
$old=DB::table('service_calculation_results')->where('billing_draft_id',$draft)->where('fingerprint',$hash)->first();
|
||||
if ($old) return ['id'=>$old->id,'replayed'=>true];
|
||||
$id=DB::table('service_calculation_results')->insertGetId($s+['billing_draft_id'=>$draft,'profile_id'=>$p->profile_id,'actor_id'=>$actor,'fingerprint'=>$hash,'snapshot'=>json_encode(['input'=>$input,'result'=>$result],JSON_THROW_ON_ERROR),'created_at'=>now()]);
|
||||
Audit::record('service_fiscal.calculated',$actor,$s['tenant_id'],$s['company_id'],$s['unit_id'],details:['result_id'=>$id,'profile_proposal_id'=>$p->id,'temporal_proposal_id'=>$t->id]);
|
||||
return ['id'=>$id,'replayed'=>false];
|
||||
});
|
||||
}
|
||||
public function history(int $draft,int $actor): array
|
||||
{
|
||||
$s=$this->scope($actor); [$b,$prepared]=$this->draft($draft,$actor); $history=[];
|
||||
if (!\Illuminate\Support\Facades\Schema::hasTable('sf_proposals')) return [];
|
||||
foreach(DB::table('service_calculation_results')->where($s)->where('billing_draft_id',$draft)->orderByDesc('id')->get() as $r) {
|
||||
$snapshot=json_decode($r->snapshot,true,32,JSON_THROW_ON_ERROR); $in=$snapshot['input'];
|
||||
if (!isset($in['profile_proposal_id'])) continue;
|
||||
$current=true;
|
||||
try { $this->versions($b,$prepared,$in); $p=$this->row($in['profile_proposal_id'],$s); $t=$this->row($in['temporal_proposal_id'],$s); abort_unless($this->approved($t) && $this->latest($t,$s),409); $this->compatible($p,$s,$in['temporal']['reference_date'],$b,$prepared); }
|
||||
catch (\Symfony\Component\HttpKernel\Exception\HttpException $e) { $current=false; }
|
||||
$history[]=['id'=>$r->id,'current'=>$current,'snapshot'=>$snapshot];
|
||||
}
|
||||
return $history;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,200 @@
|
||||
<?php
|
||||
namespace App\Modules\Services;
|
||||
|
||||
use App\Modules\Identity\Services\Audit;
|
||||
use App\Modules\Identity\Services\Permissions;
|
||||
use App\Shared\Context\CompanyContext;
|
||||
use App\Shared\Testing\TestingDatabaseGuard;
|
||||
use Illuminate\Support\Facades\DB;
|
||||
use Illuminate\Support\Facades\Schema;
|
||||
use Illuminate\Support\Facades\Validator;
|
||||
|
||||
final class ServiceInvoicing
|
||||
{
|
||||
public const NOTICE='TESTE — SEM VALIDADE FISCAL';
|
||||
public const ZONE='Africa/Johannesburg';
|
||||
public function __construct(private CompanyContext $context,private Permissions $permissions,private DocumentPreview $preview,private InvoicePdf $pdf) {}
|
||||
|
||||
public static function guard(): void
|
||||
{
|
||||
// Deliberately unconditional outside the isolated environment: no enable flag or HTTP bypass.
|
||||
abort_unless(ServiceCalculation::isolated(),403,'Emissão real bloqueada: conformidade ainda não demonstrada.');
|
||||
TestingDatabaseGuard::assertSafe();
|
||||
}
|
||||
private function scope(int $actor,string $right): array
|
||||
{
|
||||
$s=$this->context->identifiers(); $unit=$this->context->unitId();
|
||||
abort_unless($actor===$this->context->userId() && $unit!==null,403,'Seleccione uma unidade autorizada.');
|
||||
$this->permissions->require($actor,$s['tenant_id'],$s['company_id'],'unit.view',$unit);
|
||||
$this->permissions->require($actor,$s['tenant_id'],$s['company_id'],$right,(str_starts_with($right,'invoice_series.') || str_starts_with($right,'service_fiscal.'))?null:$unit);
|
||||
return $s+['unit_id'=>$unit];
|
||||
}
|
||||
private function exact(array $data,array $rules): array
|
||||
{
|
||||
abort_if(array_diff(array_keys($data),array_keys($rules))!==[],422,'Campo protegido ou fora do âmbito documental.');
|
||||
return Validator::make($data,$rules)->validate();
|
||||
}
|
||||
private function command(int $actor,string $right,callable $write): array
|
||||
{
|
||||
self::guard(); $s=$this->scope($actor,$right);
|
||||
return DB::transaction(function()use($actor,$right,$write,$s) {
|
||||
DB::table('companies')->where('id',$s['company_id'])->where('tenant_id',$s['tenant_id'])->lockForUpdate()->firstOrFail();
|
||||
$this->context->selectFor($actor,$s['tenant_id'],$s['company_id'],$s['unit_id']); $this->scope($actor,$right);
|
||||
return $write($s);
|
||||
});
|
||||
}
|
||||
private function row(int $id,array $s): object { $r=DB::table('si_proposals')->where($s)->where('id',$id)->first(); abort_unless($r,403,'Proposta fora do âmbito.'); return $r; }
|
||||
private function data(object $r): array { return json_decode($r->data,true,32,JSON_THROW_ON_ERROR); }
|
||||
private function decision(int $id): ?object { return DB::table('si_decisions')->where('proposal_id',$id)->first(); }
|
||||
private function approved(object $p,array $s,string $date): bool
|
||||
{
|
||||
if($this->decision($p->id)?->decision!=='approved') return false;
|
||||
$d=$this->data($p);
|
||||
if(($d['valid_from'] ?? '')>$date || (!empty($d['valid_until']) && $date>$d['valid_until'])) return false;
|
||||
return !DB::table('si_proposals')->where($s)->where('kind',$p->kind)->where('identifier',$p->identifier)->where('version','>',$p->version)->whereRaw("data->>'valid_from' <= ?",[$date])
|
||||
->whereExists(fn($q)=>$q->selectRaw('1')->from('si_decisions')->whereColumn('si_decisions.proposal_id','si_proposals.id')->where('decision','approved'))->exists();
|
||||
}
|
||||
public function propose(int $actor,array $input): array
|
||||
{
|
||||
$kind=$input['kind'] ?? ''; $right=$kind==='series'?'invoice_series.propose':'service_fiscal.propose';
|
||||
return $this->command($actor,$right,function($s)use($actor,$input) {
|
||||
$in=$this->exact($input,['kind'=>'required|in:series,temporal','identifier'=>'required|string|max:100|regex:/^[A-Za-z0-9_-]+$/D','previous_id'=>'nullable|integer|min:1','data'=>'required|array']);
|
||||
$previous=isset($in['previous_id'])?$this->row((int)$in['previous_id'],$s):null;
|
||||
$last=DB::table('si_proposals')->where('company_id',$s['company_id'])->where('kind',$in['kind'])->where('identifier',$in['identifier'])->orderByDesc('version')->first();
|
||||
abort_unless(($last?->id ?? null)===($previous?->id ?? null),409,'Versão anterior exacta necessária.');
|
||||
$common=['valid_from'=>'required|date_format:Y-m-d','valid_until'=>'nullable|date_format:Y-m-d|after_or_equal:valid_from','evidence'=>'required|string|max:4000'];
|
||||
if($in['kind']==='series') {
|
||||
$d=$this->exact($in['data'],$common+['code'=>'required|string|max:40|regex:/^TEST-[A-Z0-9_-]+$/D','first_number'=>'required|integer|min:1|max:999999999','state'=>'required|in:open,closed']);
|
||||
abort_unless($d['code']===$in['identifier'],422,'Identidade da série deve coincidir com o código sintético.');
|
||||
if($previous) { $old=$this->data($previous); abort_unless($old['code']===$d['code'] && (int)$old['first_number']===(int)$d['first_number'],422,'Não reiniciar ou transferir contador existente.'); }
|
||||
$d['first_number']=(int)$d['first_number'];
|
||||
} else {
|
||||
$d=$this->exact($in['data'],$common+['draft_id'=>'required|integer|min:1','draft_version'=>'required|integer|min:1','preparation_version'=>'required|integer|min:1','profile_proposal_id'=>'required|integer|min:1','period_start'=>'required|date_format:Y-m-d','period_end'=>'required|date_format:Y-m-d|after_or_equal:period_start','issue_window_start'=>'required|date_format:Y-m-d','issue_window_end'=>'required|date_format:Y-m-d|after_or_equal:issue_window_start','event'=>'required|in:on_issue_within_deadline','readiness_basis'=>'required|string|max:4000']);
|
||||
$view=$this->preview->captureDraftForIssuance((int)$d['draft_id'],$actor);
|
||||
abort_unless($view['draft_version']===(int)$d['draft_version'] && $view['preparation_version']===(int)$d['preparation_version'] && ($view['prepared']['period_start'] ?? null)===$d['period_start'] && ($view['prepared']['period_end'] ?? null)===$d['period_end'],409,'Período/versões não correspondem à preparação.');
|
||||
$profile=DB::table('sf_proposals')->where($s)->where('id',$d['profile_proposal_id'])->where('kind','profile')->first();
|
||||
abort_unless($profile && DB::table('sf_decisions')->where('proposal_id',$profile->id)->where('decision','approved')->exists(),422,'Perfil fiscal exacto aprovado necessário.');
|
||||
abort_if(DB::table('si_proposals')->where($s)->where('kind','temporal')->whereRaw("data->>'draft_id' = ?",[(string)$d['draft_id']])->where('identifier','<>',$in['identifier'])->exists(),409,'Use a identidade da regra temporal existente.');
|
||||
if($previous) abort_unless((int)$this->data($previous)['draft_id']===(int)$d['draft_id'],422,'Regra não pode trocar o rascunho.');
|
||||
foreach(['draft_id','draft_version','preparation_version','profile_proposal_id'] as $f) $d[$f]=(int)$d[$f];
|
||||
}
|
||||
$id=DB::table('si_proposals')->insertGetId($s+['kind'=>$in['kind'],'identifier'=>$in['identifier'],'version'=>(int)($last?->version ?? 0)+1,'previous_id'=>$previous?->id,'actor_id'=>$actor,'data'=>json_encode($d,JSON_THROW_ON_ERROR),'created_at'=>now()]);
|
||||
Audit::record('service_invoice.proposed',$actor,$s['tenant_id'],$s['company_id'],$s['unit_id'],details:['record_id'=>$id,'version'=>(int)($last?->version ?? 0)+1]);
|
||||
return ['id'=>$id,'version'=>(int)($last?->version ?? 0)+1];
|
||||
});
|
||||
}
|
||||
public function decide(int $id,int $actor,array $input): array
|
||||
{
|
||||
self::guard(); $scope=$this->context->identifiers()+['unit_id'=>$this->context->unitId()]; $p=$this->row($id,$scope);
|
||||
return $this->command($actor,$p->kind==='series'?'invoice_series.approve':'service_fiscal.approve',function($s)use($id,$actor,$input) {
|
||||
$d=$this->exact($input,['version'=>'required|integer|min:1','decision'=>'required|in:approved,refused','reason'=>'required|string|max:4000']);
|
||||
$p=$this->row($id,$s); abort_unless((int)$p->version===(int)$d['version'] && (int)$p->actor_id!==$actor,403,'Validador distinto e versão exacta obrigatórios.');
|
||||
abort_if($this->decision($id),409,'Decisão imutável; correcção exige nova versão.');
|
||||
DB::table('si_decisions')->insert(['proposal_id'=>$id,'actor_id'=>$actor,'decision'=>$d['decision'],'reason'=>$d['reason'],'created_at'=>now()]);
|
||||
Audit::record('service_invoice.decided',$actor,$s['tenant_id'],$s['company_id'],$s['unit_id'],details:['record_id'=>$id,'version'=>$p->version,'reason'=>$d['reason']]);
|
||||
return ['id'=>$id,'decision'=>$d['decision']];
|
||||
});
|
||||
}
|
||||
public function listing(int $actor): array
|
||||
{
|
||||
$s=$this->scope($actor,'service_invoices.view');
|
||||
if(!ServiceCalculation::isolated()) return ['real_blocked'=>true,'test_enabled'=>false,'notice'=>'Emissão real bloqueada: conformidade ainda não demonstrada.','proposals'=>[],'invoices'=>[]];
|
||||
TestingDatabaseGuard::assertSafe();
|
||||
if(!Schema::hasTable('si_invoices')) return ['real_blocked'=>true,'notice'=>'Migração documental ainda não aplicada.','proposals'=>[],'invoices'=>[]];
|
||||
return ['real_blocked'=>true,'test_enabled'=>true,'notice'=>self::NOTICE,'proposals'=>DB::table('si_proposals')->where($s)->orderByDesc('id')->get()->map(fn($p)=>(array)$p+['definition'=>$this->data($p),'decision'=>$this->decision($p->id)])->all(),'invoices'=>DB::table('si_invoices')->where($s)->orderByDesc('id')->get(['id','series_code','number','draft_id','issued_at'])->all()];
|
||||
}
|
||||
public function review(int $draft,int $series,int $rule,int $actor): array
|
||||
{
|
||||
return $this->command($actor,'service_invoices.issue',fn($s)=>$this->reviewInside($draft,$series,$rule,$actor,$s));
|
||||
}
|
||||
private function reviewInside(int $draft,int $series,int $rule,int $actor,array $s): array
|
||||
{
|
||||
$view=$this->preview->captureDraftForIssuance($draft,$actor); $date=now(self::ZONE)->format('Y-m-d'); $blocks=[];
|
||||
$p=$this->row($series,$s); $t=$this->row($rule,$s); $sd=$this->data($p); $td=$this->data($t);
|
||||
if($p->kind!=='series' || !$this->approved($p,$s,$date) || ($sd['state'] ?? null)!=='open') $blocks[]='Série sintética sem configuração aprovada/vigente e aberta.';
|
||||
if($t->kind!=='temporal' || !$this->approved($t,$s,$date) || (int)($td['draft_id'] ?? 0)!==$draft || ($td['event'] ?? '')!=='on_issue_within_deadline') $blocks[]='Regra temporal prospectiva aprovada necessária; pendência de cálculo não autoriza emissão.';
|
||||
if(($td['draft_version'] ?? null)!==$view['draft_version'] || ($td['preparation_version'] ?? null)!==$view['preparation_version'] || ($td['period_start'] ?? null)!==($view['prepared']['period_start'] ?? null) || ($td['period_end'] ?? null)!==($view['prepared']['period_end'] ?? null)) $blocks[]='Regra temporal/período desactualizado.';
|
||||
if(empty($td['issue_window_start']) || empty($td['issue_window_end']) || $date<$td['issue_window_start'] || $date>$td['issue_window_end']) $blocks[]='Tempestividade da emissão não demonstrada para a data actual.';
|
||||
foreach(['issuer'=>'Emitente','client'=>'Cliente'] as $party=>$label) foreach(['name','nuit','address','locality','country'] as $field) {
|
||||
$value=$field==='name'?($view[$party]['name'] ?? ''):($view[$party]['data'][$field] ?? '');
|
||||
if(!is_string($value) || trim($value)==='') $blocks[]="$label: $field por completar no perfil técnico de teste.";
|
||||
}
|
||||
if(empty($view['prepared']['period_start']) || empty($view['prepared']['period_end']) || empty($view['prepared']['units'][0])) $blocks[]='Cobertura e unidade de medida precisam de estar identificadas neste recorte de teste.';
|
||||
if(count($view['data']['lines'])!==1 || ($view['prepared']['price_mode'] ?? null)!=='added' || $view['data']['currency']!=='MZN') $blocks[]='Caso fora do recorte de uma linha, MZN e preço sem imposto.';
|
||||
$current=array_values(array_filter($view['fiscal_history'],fn($r)=>$r['current'] && (int)$r['snapshot']['input']['profile_proposal_id']===(int)($td['profile_proposal_id'] ?? 0)));
|
||||
$entry=$current[0] ?? null;
|
||||
if(!$entry || $entry['snapshot']['result']['total_document_proposed']===null) $blocks[]='Cálculo actual compatível e representação monetária necessários.';
|
||||
$profile=null;
|
||||
if($entry) {
|
||||
$in=$entry['snapshot']['input']; $profile=$in['profile'];
|
||||
if($date<($profile['valid_from'] ?? '9999') || (!empty($profile['valid_until']) && $date>$profile['valid_until'])) $blocks[]='Perfil não vigente na data prevista do acontecimento de emissão.';
|
||||
}
|
||||
if(DB::table('si_invoices')->where('draft_id',$draft)->orWhere('source_id',$view['source_id'])->exists()) $blocks[]='Já existe documento para este rascunho ou prestação.';
|
||||
unset($view['consulted_at'],$view['revision'],$view['calculation'],$view['fiscal_history']);
|
||||
$payload=['draft_id'=>$draft,'series_id'=>$series,'series_version'=>(int)$p->version,'series_code'=>$sd['code'] ?? '', 'series_definition'=>$sd,'rule_id'=>$rule,'rule_version'=>(int)$t->version,'rule'=>$td,'expected_date'=>$date,'document'=>$view,'calculation_entry'=>$entry,'profile'=>$profile,'blocks'=>$blocks];
|
||||
if(!$blocks) {
|
||||
$sample=$this->snapshot($payload,0,now()->toIso8601String());
|
||||
if(!InvoicePdf::supports(InvoicePdf::lines($sample))) $payload['blocks'][]='Texto incompatível com o PDF v1; rever representação sem substituir caracteres silenciosamente.';
|
||||
}
|
||||
$hash=hash_hmac('sha256',json_encode($payload,JSON_THROW_ON_ERROR),(string)config('app.key'));
|
||||
return ['notice'=>self::NOTICE,'ready'=>$payload['blocks']===[],'review_hash'=>$hash,'payload'=>$payload];
|
||||
}
|
||||
private function snapshot(array $p,int $number,string $instant): array
|
||||
{
|
||||
return ['notice'=>self::NOTICE,'renderer'=>InvoicePdf::VERSION,'draft_id'=>$p['draft_id'],'series_code'=>$p['series_code'],'number'=>$number,'issued_at'=>$instant,'issued_local'=>\Carbon\CarbonImmutable::parse($instant)->timezone(self::ZONE)->format('Y-m-d H:i:s'),'timezone'=>self::ZONE,
|
||||
'series_id'=>$p['series_id'],'series_version'=>$p['series_version'],'series_definition'=>$p['series_definition'],'rule_id'=>$p['rule_id'],'rule_version'=>$p['rule_version'],'rule'=>$p['rule'],'document'=>$p['document'],
|
||||
'calculation'=>array_replace($p['calculation_entry']['snapshot']['result'],['temporal_state'=>'issue_simulated','exigibility_date'=>$p['expected_date'],'assessment_period'=>substr($p['expected_date'],0,7),'pending'=>[]]),'prior_calculation_snapshot'=>$p['calculation_entry']['snapshot'],'calculation_id'=>$p['calculation_entry']['id'],'profile_identifier'=>$p['calculation_entry']['snapshot']['input']['profile_identifier'],'profile_version'=>$p['calculation_entry']['snapshot']['input']['profile_version'],'profile'=>$p['profile'],'rate_percent'=>$p['profile']['rate_percent'],
|
||||
'exigibility_date'=>$p['expected_date'],'assessment_period'=>substr($p['expected_date'],0,7),'simulation_only'=>true];
|
||||
}
|
||||
public function issue(int $draft,int $actor,array $input,string $key): array
|
||||
{
|
||||
return $this->command($actor,'service_invoices.issue',function($s)use($draft,$actor,$input,$key) {
|
||||
$in=$this->exact($input,['series_id'=>'required|integer|min:1','rule_id'=>'required|integer|min:1','review_hash'=>'required|string|regex:/^[a-f0-9]{64}$/D']);
|
||||
abort_unless((bool)preg_match('/^[A-Za-z0-9-]{8,100}$/D',$key),422,'Chave de repetição necessária.');
|
||||
$requestHash=hash('sha256',json_encode([$draft,(int)$in['series_id'],(int)$in['rule_id'],$in['review_hash']],JSON_THROW_ON_ERROR));
|
||||
$old=DB::table('si_commands')->where('company_id',$s['company_id'])->where('command_key',$key)->first();
|
||||
if($old) { abort_unless((int)$old->actor_id===$actor && (int)$old->unit_id===$s['unit_id'] && hash_equals($old->request_hash,$requestHash),409,'Repetição com conteúdo/autor/âmbito diferente.'); return json_decode($old->result,true,32,JSON_THROW_ON_ERROR)+['replayed'=>true]; }
|
||||
$review=$this->reviewInside($draft,(int)$in['series_id'],(int)$in['rule_id'],$actor,$s);
|
||||
abort_unless(hash_equals($review['review_hash'],$in['review_hash']),409,'Revisão desactualizada; reveja os dados e a data antes de emitir.');
|
||||
abort_unless($review['ready'],422,implode(' ',$review['payload']['blocks']));
|
||||
$p=$review['payload']; $sd=$p['series_definition'];
|
||||
DB::table('si_counters')->insertOrIgnore($s+['code'=>$sd['code'],'last_number'=>$sd['first_number']-1]);
|
||||
$counter=DB::table('si_counters')->where($s)->where('code',$sd['code'])->lockForUpdate()->firstOrFail();
|
||||
$number=(int)$counter->last_number+1; abort_if($number>999999999,422,'Limite de numeração atingido.');
|
||||
DB::table('si_counters')->where('id',$counter->id)->update(['last_number'=>$number]);
|
||||
$instant=now()->toIso8601String();
|
||||
abort_unless(\Carbon\CarbonImmutable::parse($instant)->timezone(self::ZONE)->format('Y-m-d')===$p['expected_date'],409,'Data mudou durante a confirmação; reveja antes de emitir.');
|
||||
$snapshot=$this->snapshot($p,$number,$instant);
|
||||
$snapshot['document_lines']=InvoicePdf::lines($snapshot); // Freeze browser representation as well as PDF bytes.
|
||||
$bytes=$this->pdf->render($snapshot);
|
||||
$id=DB::table('si_invoices')->insertGetId($s+['draft_id'=>$draft,'source_id'=>$p['document']['source_id'],'series_id'=>$p['series_id'],'rule_id'=>$p['rule_id'],'series_code'=>$sd['code'],'number'=>$number,'snapshot'=>json_encode($snapshot,JSON_THROW_ON_ERROR),'pdf_base64'=>base64_encode($bytes),'pdf_sha256'=>hash('sha256',$bytes),'actor_id'=>$actor,'issued_at'=>$instant]);
|
||||
$event=DB::table('si_events')->insertGetId(['invoice_id'=>$id,'type'=>'test_invoice.captured','payload'=>json_encode(['invoice_id'=>$id,'simulation_only'=>true],JSON_THROW_ON_ERROR),'created_at'=>now()]);
|
||||
DB::table('si_outbox')->insert(['event_id'=>$event,'state'=>'captured_no_processing']);
|
||||
Audit::record('service_invoice.test_issued',$actor,$s['tenant_id'],$s['company_id'],$s['unit_id'],details:['record_id'=>$id,'event_id'=>$event,'version'=>1]);
|
||||
$result=['id'=>$id,'series_code'=>$sd['code'],'number'=>$number,'notice'=>self::NOTICE];
|
||||
DB::table('si_commands')->insert($s+['actor_id'=>$actor,'command_key'=>$key,'request_hash'=>$requestHash,'result'=>json_encode($result,JSON_THROW_ON_ERROR),'created_at'=>now()]);
|
||||
return $result+['replayed'=>false];
|
||||
});
|
||||
}
|
||||
public function show(int $id,int $actor): array
|
||||
{
|
||||
self::guard(); $s=$this->scope($actor,'service_invoices.view');
|
||||
$r=DB::table('si_invoices')->where($s)->where('id',$id)->first(); abort_unless($r,403,'Documento fora do âmbito.');
|
||||
$snapshot=json_decode($r->snapshot,true,32,JSON_THROW_ON_ERROR);
|
||||
return ['id'=>$r->id,'snapshot'=>$snapshot,'document_lines'=>$snapshot['document_lines'] ?? InvoicePdf::lines($snapshot),'pdf_sha256'=>$r->pdf_sha256,'corrections'=>DB::table('si_correction_requests')->where('invoice_id',$id)->get(['id','reason','actor_id','created_at'])->all()];
|
||||
}
|
||||
public function pdf(int $id,int $actor): string
|
||||
{
|
||||
$this->show($id,$actor); $r=DB::table('si_invoices')->where('id',$id)->first(['pdf_base64','pdf_sha256']);
|
||||
$bytes=base64_decode($r->pdf_base64,true); abort_unless($bytes!==false && hash_equals($r->pdf_sha256,hash('sha256',$bytes)),409,'Integridade do PDF não confirmada.'); return $bytes;
|
||||
}
|
||||
public function requestCorrection(int $id,int $actor,array $input): array
|
||||
{
|
||||
return $this->command($actor,'service_invoices.correction_request',function($s)use($id,$actor,$input) {
|
||||
$d=$this->exact($input,['reason'=>'required|string|max:2000']); $this->show($id,$actor);
|
||||
$request=DB::table('si_correction_requests')->insertGetId(['invoice_id'=>$id,'actor_id'=>$actor,'reason'=>$d['reason'],'created_at'=>now()]);
|
||||
Audit::record('service_invoice.correction_requested',$actor,$s['tenant_id'],$s['company_id'],$s['unit_id'],details:['record_id'=>$id,'reason'=>$d['reason']]);
|
||||
return ['id'=>$request,'state'=>'pending_no_fiscal_effect'];
|
||||
});
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,22 @@
|
||||
<?php
|
||||
|
||||
namespace App\Modules\Services;
|
||||
|
||||
final class ServicePermissions
|
||||
{
|
||||
public const AREAS = ['clients', 'services', 'service_drafts', 'billing_drafts'];
|
||||
public const ACTIONS = ['view', 'create', 'edit', 'manage'];
|
||||
public const LABELS = ['clients' => 'Clientes', 'services' => 'Serviços', 'service_drafts' => 'Prestações em rascunho', 'billing_drafts' => 'Rascunhos de facturação'];
|
||||
|
||||
public static function unitScoped(string $area): bool { return in_array($area, ['service_drafts', 'billing_drafts'], true); }
|
||||
public static function catalogue(bool $unit): array
|
||||
{
|
||||
$result = [];
|
||||
foreach (self::AREAS as $area) {
|
||||
if (self::unitScoped($area) === $unit) {
|
||||
foreach (self::ACTIONS as $action) { $result[] = "$area.$action"; }
|
||||
}
|
||||
}
|
||||
return $result;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,242 @@
|
||||
<?php
|
||||
namespace App\Modules\Services;
|
||||
|
||||
use App\Modules\Identity\Services\Audit;
|
||||
use App\Modules\Identity\Services\Permissions;
|
||||
use App\Shared\Context\CompanyContext;
|
||||
use App\Shared\Testing\TestingDatabaseGuard;
|
||||
use Brick\Math\BigDecimal;
|
||||
use Brick\Math\RoundingMode;
|
||||
use Illuminate\Support\Facades\DB;
|
||||
use Illuminate\Support\Facades\Validator;
|
||||
|
||||
/** Isolated operational subledger. Never invokes fiscal, banking or accounting consumers. */
|
||||
final class ServiceReceivables
|
||||
{
|
||||
public const POLICY='SGF-RECEIVABLES-SIM-v1';
|
||||
public const NOTICE='TESTE — SEM VALIDADE FISCAL';
|
||||
public const SIMULATION='SIMULAÇÃO — SEM MOVIMENTAÇÃO DE DINHEIRO';
|
||||
public function __construct(private CompanyContext $context, private Permissions $permissions) {}
|
||||
public static function guard(): void
|
||||
{
|
||||
abort_unless(ServiceCalculation::isolated(),403,'Recebimentos e reconciliação disponíveis exclusivamente em testes isolados.');
|
||||
TestingDatabaseGuard::assertSafe();
|
||||
}
|
||||
private function scope(int $actor,string $right): array
|
||||
{
|
||||
$s=$this->context->identifiers()+['unit_id'=>$this->context->unitId()];
|
||||
abort_unless($actor===$this->context->userId() && $s['unit_id']!==null,403);
|
||||
$this->context->selectFor($actor,$s['tenant_id'],$s['company_id'],$s['unit_id']);
|
||||
foreach (['view',$right] as $r) $this->permissions->require($actor,$s['tenant_id'],$s['company_id'],'service_receivables.'.$r,$s['unit_id']);
|
||||
return $s;
|
||||
}
|
||||
public static function money(mixed $value,bool $positive=true): string
|
||||
{
|
||||
$v=DraftValues::decimal($value,'amount');
|
||||
abort_unless($v!==null,422,'Montante explícito necessário.');
|
||||
$n=BigDecimal::of($v);
|
||||
abort_if(($positive && $n->isLessThanOrEqualTo(0)) || $n->getScale()>2,422,'Use um montante positivo exactamente representável a duas casas; sem truncagem.');
|
||||
return (string)$n->toScale(2,RoundingMode::UNNECESSARY);
|
||||
}
|
||||
private function validate(array $d,array $rules): array
|
||||
{
|
||||
abort_if(array_diff(array_keys($d),array_keys($rules)),422,'Campo protegido ou não suportado.');
|
||||
return Validator::make($d,$rules)->validate();
|
||||
}
|
||||
private function json(mixed $d): string { return json_encode($d,JSON_THROW_ON_ERROR|JSON_UNESCAPED_UNICODE); }
|
||||
private function data(object $r): array { return json_decode($r->data,true,32,JSON_THROW_ON_ERROR); }
|
||||
private function row(int $id,array $s,?string $kind=null): object
|
||||
{
|
||||
$q=DB::table('sr_records')->where($s)->where('id',$id);
|
||||
if($kind) $q->where('kind',$kind);
|
||||
return $q->first() ?? abort(403,'Identidade fora do âmbito ou tipo incorrecto.');
|
||||
}
|
||||
private function revision(int $ob): int { return DB::table('sr_effects')->where('obligation_id',$ob)->count(); }
|
||||
private function command(int $actor,string $right,string $key,array $input,callable $write): array
|
||||
{
|
||||
self::guard(); $s=$this->scope($actor,$right);
|
||||
abort_unless(preg_match('/^[A-Za-z0-9_-]{8,100}$/D',$key),422,'Chave de idempotência obrigatória.');
|
||||
ksort($input); $hash=hash('sha256',$this->json($input));
|
||||
return DB::transaction(function() use($actor,$right,$key,$input,$hash,$s,$write) {
|
||||
// Same global order as the database guards: company, then immutable records/effects.
|
||||
DB::table('companies')->where('id',$s['company_id'])->lockForUpdate()->firstOrFail();
|
||||
$this->scope($actor,$right);
|
||||
$old=DB::table('sr_commands')->where($s)->where(['actor_id'=>$actor,'action'=>$right,'command_key'=>$key])->first();
|
||||
if($old) {
|
||||
abort_unless(hash_equals($old->request_hash,$hash),409,'Chave já usada com conteúdo diferente.');
|
||||
return json_decode($old->result,true,32,JSON_THROW_ON_ERROR)+['replayed'=>true];
|
||||
}
|
||||
$result=$write($s);
|
||||
$cmd=DB::table('sr_commands')->insertGetId($s+['actor_id'=>$actor,'action'=>$right,'command_key'=>$key,'request_hash'=>$hash,'result'=>$this->json($result),'created_at'=>now()]);
|
||||
Audit::record('service_receivables.'.$right,$actor,$s['tenant_id'],$s['company_id'],$s['unit_id'],details:['command_id'=>$cmd,'record_id'=>$result['id'],'simulation_only'=>true]);
|
||||
$event=DB::table('sr_events')->insertGetId(['command_id'=>$cmd,'type'=>$result['event'],'schema_version'=>1,'payload'=>$this->json($s+['policy'=>self::POLICY,'command_id'=>$cmd,'actor_id'=>$actor,'result'=>$result]),'created_at'=>now()]);
|
||||
DB::table('sr_outbox')->insert(['event_id'=>$event,'state'=>'captured_simulation_only']);
|
||||
return $result+['replayed'=>false];
|
||||
},3);
|
||||
}
|
||||
private function record(array $s,int $actor,string $kind,object $inv,int $client,?int $ob,?int $receipt,string $amount,string $source,string $external,array $data): array
|
||||
{
|
||||
abort_if(DB::table('sr_records')->where($s)->where(['kind'=>$kind,'source'=>$source,'external_id'=>$external])->exists(),409,'Acontecimento já registado; consulte a identidade original.');
|
||||
if($kind==='obligation') abort_if(DB::table('sr_records')->where('invoice_id',$inv->id)->where('kind','obligation')->exists(),409,'Documento já tem obrigação.');
|
||||
$origin=['invoice_id'=>$inv->id,'snapshot_sha256'=>hash('sha256',$inv->snapshot),'series'=>$inv->series_code,'number'=>$inv->number,'issued_at'=>$inv->issued_at];
|
||||
$id=DB::table('sr_records')->insertGetId($s+['invoice_id'=>$inv->id,'client_id'=>$client,'obligation_id'=>$ob,'receipt_id'=>$receipt,'kind'=>$kind,'currency'=>'MZN','amount'=>$amount,'source'=>$source,'external_id'=>$external,'data'=>$this->json(array_replace($data,['policy'=>self::POLICY,'origin'=>$origin])),'version'=>1,'actor_id'=>$actor,'created_at'=>now()]);
|
||||
return ['id'=>$id,'version'=>1,'event'=>$kind.'.proposed'];
|
||||
}
|
||||
public function propose(int $actor,array $input,string $key): array
|
||||
{
|
||||
self::guard();
|
||||
$d=$this->validate($input,['kind'=>'required|in:obligation,receipt,observation,correction','invoice_id'=>'required|integer|min:1','obligation_id'=>'nullable|integer|min:1','receipt_id'=>'nullable|integer|min:1','currency'=>'required|in:MZN','amount'=>'nullable|string','source'=>'required|string|min:3|max:80','external_id'=>'required|string|min:3|max:100','date'=>'nullable|date_format:Y-m-d','evidence'=>'nullable|string|min:3|max:1000','due_date'=>'nullable|date_format:Y-m-d','reason'=>'nullable|string|min:3|max:1000','action'=>'nullable|in:reverse_allocation,reverse_reconcile,reverse_receipt,reduction,due','target_effect_id'=>'nullable|integer|min:1','document_ref'=>'nullable|string|max:100','line'=>'nullable|in:1','revision'=>'required|integer|min:0']);
|
||||
$kind=$d['kind'];
|
||||
$right=$kind==='correction'?'correction_request':'prepare';
|
||||
if(isset($d['amount'])) $d['amount']=self::money($d['amount'],$kind!=='observation');
|
||||
return $this->command($actor,$right,$key,$d,function($s)use($actor,$d,$kind) {
|
||||
$inv=DB::table('si_invoices')->where($s)->where('id',$d['invoice_id'])->first();
|
||||
abort_unless($inv,403,'Documento de origem não autorizado.');
|
||||
$snapshot=json_decode($inv->snapshot,true,32,JSON_THROW_ON_ERROR);
|
||||
abort_unless(($snapshot['simulation_only']??false)===true && ($snapshot['notice']??'')===self::NOTICE && ($snapshot['document']['data']['currency']??'')==='MZN',422,'Origem sintética compatível necessária.');
|
||||
$history=DB::table('a_history')->where($s)->where(['area'=>'billing_drafts','record_id'=>$inv->draft_id,'version'=>$snapshot['document']['draft_version']])->value('snapshot');
|
||||
abort_unless($history,409,'Versão histórica da origem necessária.');
|
||||
$client=(int)json_decode($history,true,32,JSON_THROW_ON_ERROR)['client_id'];
|
||||
$ob=null; $receipt=null; $amount='0.00';
|
||||
if($kind==='obligation') {
|
||||
abort_if(!empty($d['obligation_id']) || !empty($d['receipt_id']) || $d['revision']!==0,422);
|
||||
$amount=self::money($snapshot['calculation']['total_document_proposed']);
|
||||
abort_unless(!isset($d['amount']) || $d['amount']===$amount,422,'Montante deve coincidir com a fotografia.');
|
||||
} else {
|
||||
$ob=$this->row((int)($d['obligation_id']??0),$s,'obligation');
|
||||
abort_unless($ob->invoice_id===$inv->id,403);
|
||||
abort_unless($d['revision']===$this->revision($ob->id),409,'Revisão desactualizada.');
|
||||
abort_unless(DB::table('sr_effects')->where(['record_id'=>$ob->id,'kind'=>'open'])->exists(),409,'Obrigação ainda não aberta.');
|
||||
if(!empty($d['receipt_id'])) { $receipt=$this->row($d['receipt_id'],$s,'receipt'); abort_unless($receipt->obligation_id===$ob->id,403); }
|
||||
}
|
||||
if(in_array($kind,['receipt','observation'])) {
|
||||
abort_unless(isset($d['amount'],$d['date'],$d['evidence']),422,'Montante, data e evidência sintética são obrigatórios.');
|
||||
abort_if($d['date']>now(ServiceInvoicing::ZONE)->format('Y-m-d'),422,'Data futura não comprova recebimento ou observação.');
|
||||
$amount=$d['amount'];
|
||||
abort_if(($kind==='receipt' && $receipt) || ($kind==='observation' && !$receipt),422);
|
||||
}
|
||||
if($kind==='correction') {
|
||||
abort_unless(isset($d['action'],$d['reason']),422,'Acção e motivo necessários.');
|
||||
if($d['action']==='reduction') {
|
||||
abort_unless(isset($d['amount'],$d['document_ref'],$d['line']) && str_starts_with($d['document_ref'],'TEST-REDUCTION-'),422,'Documento redutor sintético e linha necessários.');
|
||||
$amount=$d['amount'];
|
||||
}
|
||||
if(in_array($d['action'],['reverse_allocation','reverse_reconcile'])) {
|
||||
$effect=DB::table('sr_effects')->where('obligation_id',$ob->id)->where('id',$d['target_effect_id']??0)->first();
|
||||
abort_unless($effect && $effect->kind===($d['action']==='reverse_allocation'?'allocate':'reconcile'),422,'Alvo de reversão incompatível.');
|
||||
$receipt=$this->row($effect->receipt_id,$s,'receipt'); $amount=$effect->amount;
|
||||
}
|
||||
if($d['action']==='reverse_receipt') { abort_unless($receipt,422); $amount=$receipt->amount; }
|
||||
}
|
||||
return $this->record($s,$actor,$kind,$inv,$client,$ob?->id,$receipt?->id,$amount,$d['source'],$d['external_id'],$d);
|
||||
});
|
||||
}
|
||||
public function decide(int $id,int $actor,array $input,string $key): array
|
||||
{
|
||||
self::guard(); $s=$this->scope($actor,'view'); $r=$this->row($id,$s);
|
||||
$right=$r->kind==='correction'?'correction_approve':($r->kind==='observation'?'reconcile':'confirm');
|
||||
$d=$this->validate($input,['version'=>'required|integer|in:1','revision'=>'required|integer|min:0','decision'=>'required|in:approved,refused','reason'=>'required|string|min:3|max:1000']);
|
||||
return $this->command($actor,$right,$key,['record_id'=>$id]+$d,function($s)use($id,$actor,$d) {
|
||||
$r=$this->row($id,$s); $rd=$this->data($r); $ob=$r->kind==='obligation'?$r->id:$r->obligation_id;
|
||||
abort_if($r->actor_id===$actor,403,'Confirmação/aprovação exige identidade distinta.');
|
||||
abort_unless($d['revision']===$this->revision($ob),409,'Estado alterado; reveja a decisão.');
|
||||
abort_if(DB::table('sr_effects')->where('record_id',$id)->where('kind','<>','allocate')->exists(),409,'Versão já tem decisão.');
|
||||
$kind='refused'; $amount='0.00'; $receipt=null; $target=null;
|
||||
if($d['decision']==='approved') {
|
||||
if($r->kind==='obligation') { $kind='open'; $amount=$r->amount; }
|
||||
if($r->kind==='receipt') { $kind='receipt_confirm'; $amount=$r->amount; }
|
||||
if($r->kind==='observation') {
|
||||
$receipt=$r->receipt_id; $rc=$this->row($receipt,$s,'receipt');
|
||||
$diff=BigDecimal::of($rc->amount)->minus($r->amount)->abs();
|
||||
$kind=$diff->isZero()?'reconcile':'divergence'; $amount=$diff->isZero()?$rc->amount:(string)$diff->toScale(2);
|
||||
}
|
||||
if($r->kind==='correction') {
|
||||
abort_unless(($rd['revision']??-1)===$d['revision'],409,'Proposta ligada a revisão anterior; prepare nova proposta.');
|
||||
$kind=$rd['action']; $amount=$r->amount; $receipt=$r->receipt_id; $target=$rd['target_effect_id']??null;
|
||||
if($kind==='reduction' || $kind==='due') $receipt=null;
|
||||
}
|
||||
} elseif($r->kind==='observation') abort(422,'A conferência regista correspondência ou divergência; não é aprovação de recibo.');
|
||||
return $this->effect($id,$ob,$receipt,$kind,$amount,$target,$d['revision'],$actor,$d+['due_date'=>$rd['due_date']??null]);
|
||||
});
|
||||
}
|
||||
private function effect(int $record,int $ob,?int $receipt,string $kind,string $amount,?int $target,int $revision,int $actor,array $data): array
|
||||
{
|
||||
$state=$this->state($ob);
|
||||
if($kind==='allocate') {
|
||||
$r=$state['receipts'][$receipt]??abort(409,'Recebimento indisponível.');
|
||||
abort_unless($r['state']==='confirmed' && BigDecimal::of($amount)->isLessThanOrEqualTo($r['available']) && BigDecimal::of($amount)->isLessThanOrEqualTo($state['balance']),409,'Sobreafectação recusada integralmente.');
|
||||
}
|
||||
if($kind==='reduction') abort_if(BigDecimal::of($amount)->isGreaterThan($state['balance']),409,'Liberte afectação antes da redução.');
|
||||
if($kind==='reverse_receipt') {
|
||||
$r=$state['receipts'][$receipt]??abort(409);
|
||||
abort_unless($r['state']==='confirmed' && $r['allocated']==='0.00' && !$r['reconciled'],409,'Reverta afectações e reconciliação primeiro.');
|
||||
}
|
||||
if(in_array($kind,['reconcile','divergence'])) {
|
||||
$r=$state['receipts'][$receipt]??abort(409);
|
||||
abort_unless($r['state']==='confirmed' && !$r['reconciled'],409,'Recebimento indisponível ou já conferido.');
|
||||
}
|
||||
if($target) abort_if(DB::table('sr_effects')->where('target_effect_id',$target)->exists(),409,'Efeito já revertido.');
|
||||
$id=DB::table('sr_effects')->insertGetId(['record_id'=>$record,'obligation_id'=>$ob,'receipt_id'=>$receipt,'kind'=>$kind,'amount'=>$amount,'target_effect_id'=>$target,'revision'=>$revision,'data'=>$this->json($data),'actor_id'=>$actor,'created_at'=>now()]);
|
||||
return ['id'=>$id,'record_id'=>$record,'obligation_id'=>$ob,'event'=>$kind.'.simulation','revision'=>$revision+1];
|
||||
}
|
||||
public function allocate(int $id,int $actor,array $input,string $key): array
|
||||
{
|
||||
self::guard(); $d=$this->validate($input,['amount'=>'required|string','revision'=>'required|integer|min:0','version'=>'required|integer|in:1']);
|
||||
$d['amount']=self::money($d['amount']);
|
||||
return $this->command($actor,'allocate',$key,['receipt_id'=>$id]+$d,function($s)use($id,$actor,$d) {
|
||||
$r=$this->row($id,$s,'receipt'); abort_unless($d['revision']===$this->revision($r->obligation_id),409,'Revisão desactualizada.');
|
||||
return $this->effect($id,$r->obligation_id,$id,'allocate',$d['amount'],null,$d['revision'],$actor,[]);
|
||||
});
|
||||
}
|
||||
private function state(int $ob,?string $cut=null): array
|
||||
{
|
||||
$r=DB::table('sr_records')->find($ob); $rd=$this->data($r);
|
||||
$effects=DB::table('sr_effects')->where('obligation_id',$ob)->orderBy('id')->get();
|
||||
$receipts=[]; $balance=BigDecimal::of($r->amount); $reduced=BigDecimal::zero(); $allocated=BigDecimal::zero(); $due=$rd['due_date']??null; $opened=false; $refused=false;
|
||||
foreach(DB::table('sr_records')->where('obligation_id',$ob)->where('kind','receipt')->get() as $rc) $receipts[$rc->id]=['id'=>$rc->id,'amount'=>$rc->amount,'state'=>'proposed','allocated'=>'0.00','available'=>'0.00','reconciled'=>false];
|
||||
foreach($effects as $e) {
|
||||
if($e->kind==='open') $opened=true;
|
||||
if($e->kind==='refused' && $e->record_id===$ob) $refused=true;
|
||||
if($e->kind==='due') $due=$this->data($e)['due_date'];
|
||||
if($e->kind==='receipt_confirm') { $receipts[$e->record_id]['state']='confirmed'; $receipts[$e->record_id]['available']=$e->amount; }
|
||||
if($e->kind==='refused' && isset($receipts[$e->record_id])) $receipts[$e->record_id]['state']='refused';
|
||||
if(in_array($e->kind,['allocate','reverse_allocation'])) {
|
||||
$x=BigDecimal::of($e->amount)->multipliedBy($e->kind==='allocate'?1:-1); $allocated=$allocated->plus($x);
|
||||
$rc=&$receipts[$e->receipt_id]; $rc['allocated']=(string)BigDecimal::of($rc['allocated'])->plus($x)->toScale(2); $rc['available']=(string)BigDecimal::of($rc['available'])->minus($x)->toScale(2); unset($rc);
|
||||
}
|
||||
if($e->kind==='reduction') $reduced=$reduced->plus($e->amount);
|
||||
if($e->kind==='reconcile') $receipts[$e->receipt_id]['reconciled']=true;
|
||||
if($e->kind==='reverse_reconcile') $receipts[$e->receipt_id]['reconciled']=false;
|
||||
if($e->kind==='reverse_receipt') { $receipts[$e->receipt_id]['state']='reversed'; $receipts[$e->receipt_id]['available']='0.00'; }
|
||||
}
|
||||
$balance=$balance->minus($reduced)->minus($allocated); $received=BigDecimal::zero(); $available=BigDecimal::zero();
|
||||
foreach($receipts as $rc) if($rc['state']==='confirmed') { $received=$received->plus($rc['amount']); $available=$available->plus($rc['available']); }
|
||||
$cut??=now(ServiceInvoicing::ZONE)->format('Y-m-d');
|
||||
return ['id'=>$ob,'original'=>$r->amount,'reduced'=>(string)$reduced->toScale(2),'received'=>(string)$received->toScale(2),'allocated'=>(string)$allocated->toScale(2),'available'=>(string)$available->toScale(2),'balance'=>(string)$balance->toScale(2),'opened'=>$opened,'state'=>!$opened?($refused?'refused':'proposed'):($balance->isZero()?'settled':($allocated->isPositive()?'partial':'open')),'due_date'=>$due,'due_state'=>!$opened?'not_open':($balance->isZero()?'settled':($due===null?'unknown':($cut>$due?'overdue':'not_due'))),'cut_date'=>$cut,'revision'=>$effects->count(),'receipts'=>$receipts,'effects'=>$effects->all()];
|
||||
}
|
||||
public function listing(int $actor): array
|
||||
{
|
||||
$s=$this->scope($actor,'view');
|
||||
if(!ServiceCalculation::isolated()) return ['blocked'=>true,'notice'=>self::NOTICE,'simulation'=>self::SIMULATION,'obligations'=>[],'records'=>[],'documents'=>[]];
|
||||
self::guard();
|
||||
return DB::transaction(function()use($s) {
|
||||
DB::table('companies')->where('id',$s['company_id'])->lockForUpdate()->firstOrFail();
|
||||
$records=DB::table('sr_records')->where($s)->orderBy('id')->get();
|
||||
return ['blocked'=>false,'notice'=>self::NOTICE,'simulation'=>self::SIMULATION,'records'=>$records->map(function($r){$r->data=$this->data($r);return $r;})->all(),'obligations'=>$records->where('kind','obligation')->map(fn($r)=>$this->state($r->id))->values()->all(),'documents'=>DB::table('si_invoices')->where($s)->get(['id','series_code','number'])->all()];
|
||||
});
|
||||
}
|
||||
/** Idempotent internal delivery only: validates ledger, never posts accounts or calls banks. */
|
||||
public function deliver(int $event): bool
|
||||
{
|
||||
self::guard();
|
||||
return DB::transaction(function()use($event) {
|
||||
$e=DB::table('sr_events')->where('id',$event)->lockForUpdate()->firstOrFail();
|
||||
if(DB::table('sr_deliveries')->where('event_id',$event)->exists()) return false;
|
||||
$cmd=DB::table('sr_commands')->find($e->command_id); $result=json_decode($cmd->result,true,32,JSON_THROW_ON_ERROR);
|
||||
$ob=$result['obligation_id']??null;
|
||||
if($ob) { $state=$this->state($ob); abort_if(BigDecimal::of($state['balance'])->isNegative(),409,'Integridade do saldo falhou.'); }
|
||||
DB::table('sr_deliveries')->insert(['event_id'=>$event,'consumer'=>'simulation_integrity_v1','created_at'=>now()]);
|
||||
return true;
|
||||
});
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,170 @@
|
||||
<?php
|
||||
|
||||
namespace App\Modules\Services;
|
||||
|
||||
use App\Modules\Identity\Services\Audit;
|
||||
use App\Modules\Identity\Services\Permissions;
|
||||
use App\Shared\Context\CompanyContext;
|
||||
use Illuminate\Support\Facades\DB;
|
||||
|
||||
final class ServiceWorkflow
|
||||
{
|
||||
public function __construct(private CompanyContext $context, private Permissions $permissions) {}
|
||||
|
||||
public function scope(string $area, int $actor, string $action): array
|
||||
{
|
||||
abort_unless(in_array($area, ServicePermissions::AREAS, true) && in_array($action, ServicePermissions::ACTIONS, true), 404);
|
||||
$ids = $this->context->identifiers();
|
||||
abort_unless($this->context->userId() === $actor, 403);
|
||||
$unit = ServicePermissions::unitScoped($area) ? $this->context->unitId() : null;
|
||||
abort_if(ServicePermissions::unitScoped($area) && $unit === null, 403, 'Seleccione uma unidade autorizada para esta área.');
|
||||
$this->permissions->require($actor, $ids['tenant_id'], $ids['company_id'], "$area.view", $unit);
|
||||
$this->permissions->require($actor, $ids['tenant_id'], $ids['company_id'], "$area.$action", $unit);
|
||||
return $ids + ['unit_id' => $unit];
|
||||
}
|
||||
|
||||
private function query(string $area, array $scope)
|
||||
{
|
||||
return DB::table('a_'.$area)->where('tenant_id', $scope['tenant_id'])->where('company_id', $scope['company_id'])->where('unit_id', $scope['unit_id']);
|
||||
}
|
||||
|
||||
public function list(string $area, int $actor): array
|
||||
{
|
||||
$scope = $this->scope($area, $actor, 'view');
|
||||
return $this->query($area, $scope)->orderByDesc('id')->get()->map(fn ($item) => $this->describe($area, $item))->all();
|
||||
}
|
||||
|
||||
public function show(string $area, int $id, int $actor): array
|
||||
{
|
||||
$scope = $this->scope($area, $actor, 'view');
|
||||
$record = $this->query($area, $scope)->where('id', $id)->first();
|
||||
abort_unless($record, 403, 'Registo fora do âmbito autorizado.');
|
||||
$result = $this->describe($area, $record);
|
||||
$result['history'] = DB::table('a_history')->where('area', $area)->where('record_id', $id)->orderBy('version')
|
||||
->get(['id','version','actor_id','snapshot','created_at'])->map(function ($row) {
|
||||
$row->snapshot = json_decode($row->snapshot, true);
|
||||
$row->event = DB::table('a_events as e')->join('a_outbox as o', 'o.event_id', '=', 'e.id')->where('e.history_id', $row->id)
|
||||
->first(['e.id','e.type','e.schema_version','o.state']);
|
||||
return $row;
|
||||
})->all();
|
||||
return $result;
|
||||
}
|
||||
|
||||
private function describe(string $area, object $row): array
|
||||
{
|
||||
$result = (array) $row;
|
||||
$result['data'] = json_decode($row->data, true, 32, JSON_THROW_ON_ERROR);
|
||||
$result['version'] = (int) $row->version;
|
||||
if ($area === 'billing_drafts') {
|
||||
$confirmationId = DB::table('b_internal_confirmations')->where('billing_draft_id', $row->id)->value('id');
|
||||
$result['internal_confirmation'] = $confirmationId ? ['reference' => 'INT-B1-'.$confirmationId, 'label' => InternalConfirmation::LABEL] : null;
|
||||
}
|
||||
$result['base_amount'] = ServicePermissions::unitScoped($area) ? DraftValues::base($result['data']) : null;
|
||||
$history = DB::table('a_history')->where('area', $area)->where('record_id', $row->id)->where('version', $row->version)->value('id');
|
||||
$result['pending'] = $history ? DB::table('a_pending')->where('history_id', $history)->pluck('message', 'code')->all() : [];
|
||||
return $result;
|
||||
}
|
||||
|
||||
public function save(string $area, ?int $id, int $actor, array $input, string $key): array
|
||||
{
|
||||
$action = $id === null ? 'create' : 'edit';
|
||||
$scope = $this->scope($area, $actor, $action);
|
||||
$selectedUnit = $this->context->unitId();
|
||||
abort_unless((bool) preg_match('/^[a-zA-Z0-9-]{8,100}$/D', $key), 422, 'É necessária uma chave de repetição válida.');
|
||||
$hash = hash('sha256', json_encode($this->canonical([$area, $id, $scope, $input]), JSON_THROW_ON_ERROR));
|
||||
return DB::transaction(function () use ($area, $id, $actor, $input, $key, $scope, $selectedUnit, $hash, $action): array {
|
||||
DB::table('companies')->where('id', $scope['company_id'])->where('tenant_id', $scope['tenant_id'])->lockForUpdate()->firstOrFail();
|
||||
$this->context->selectFor($actor, $scope['tenant_id'], $scope['company_id'], $selectedUnit);
|
||||
$this->scope($area, $actor, $action);
|
||||
$previous = DB::table('a_commands')->where('tenant_id', $scope['tenant_id'])->where('company_id', $scope['company_id'])->where('command_key', $key)->first();
|
||||
if ($previous) {
|
||||
abort_unless((int) $previous->actor_id === $actor && hash_equals($previous->request_hash, $hash), 409, 'Chave repetida com conteúdo ou autor diferente.');
|
||||
return json_decode($previous->result, true, 32, JSON_THROW_ON_ERROR) + ['replayed' => true];
|
||||
}
|
||||
$old = $id ? $this->query($area, $scope)->where('id', $id)->first() : null;
|
||||
if ($id) {
|
||||
abort_unless($old, 403, 'Registo fora do âmbito autorizado.');
|
||||
abort_if($area === 'billing_drafts' && DB::table('b_internal_confirmations')->where('billing_draft_id', $id)->exists(), 409, 'Confirmado internamente — sem validade fiscal. O registo está bloqueado para edição.');
|
||||
abort_unless((int) $old->version === (int) ($input['version'] ?? 0), 409, 'O registo mudou. Reabra-o antes de guardar.');
|
||||
}
|
||||
$version = $old ? (int) $old->version + 1 : 1;
|
||||
$values = $this->normalise($area, $input, $scope, $old);
|
||||
$data = $values['data']; $values['data'] = json_encode($data === [] ? new \stdClass() : $data, JSON_THROW_ON_ERROR);
|
||||
$values += ['version' => $version, 'updated_at' => now()];
|
||||
if ($id) { $this->query($area, $scope)->where('id', $id)->update($values); }
|
||||
else { $id = DB::table('a_'.$area)->insertGetId($scope + $values + ['created_at' => now()]); }
|
||||
$record = $this->query($area, $scope)->where('id', $id)->first();
|
||||
if ($area === 'billing_drafts' && ! $old) { app(DocumentPreparation::class)->inheritToBilling((int) $record->source_id, $id, $actor, $scope); }
|
||||
$snapshot = (array) $record; $snapshot['data'] = $data;
|
||||
$pending = ServicePermissions::unitScoped($area) ? DraftValues::pending($data) : [];
|
||||
if ($area === 'billing_drafts') {
|
||||
$current = DB::table('a_service_drafts')->where('id', $record->source_id)->value('version');
|
||||
if ((int) $current !== (int) $data['source_version']) { $pending['source_changed'] = 'A prestação tem uma versão mais recente. Reveja ou actualize explicitamente os dados de origem.'; }
|
||||
}
|
||||
$snapshot['pending'] = $pending;
|
||||
$history = DB::table('a_history')->insertGetId($scope + ['area' => $area, 'record_id' => $id, 'version' => $version,
|
||||
'actor_id' => $actor, 'snapshot' => json_encode($snapshot, JSON_THROW_ON_ERROR), 'created_at' => now()]);
|
||||
foreach ($pending as $code => $message) { DB::table('a_pending')->insert(['history_id' => $history, 'code' => $code, 'message' => $message, 'created_at' => now()]); }
|
||||
$affected = [];
|
||||
if ($area === 'service_drafts' && $old) {
|
||||
foreach (DB::table('a_billing_drafts')->where('source_id', $id)->where('tenant_id', $scope['tenant_id'])->where('company_id', $scope['company_id'])->where('unit_id', $scope['unit_id'])->get(['id','version']) as $billing) {
|
||||
if (DB::table('b_internal_confirmations')->where('billing_draft_id', $billing->id)->exists()) { continue; }
|
||||
$billingHistory = DB::table('a_history')->where('area', 'billing_drafts')->where('record_id', $billing->id)->where('version', $billing->version)->value('id');
|
||||
DB::table('a_pending')->insertOrIgnore(['history_id' => $billingHistory, 'code' => 'source_changed', 'message' => 'A prestação de origem foi alterada; os dados deste rascunho não foram reescritos.', 'created_at' => now()]);
|
||||
$affected[] = $billing->id;
|
||||
}
|
||||
}
|
||||
$event = DB::table('a_events')->insertGetId(['history_id' => $history, 'type' => "a.$area.".($old ? 'updated' : 'created'),
|
||||
'schema_version' => 1, 'payload' => json_encode(['snapshot' => $snapshot, 'affected_billing_drafts' => $affected], JSON_THROW_ON_ERROR), 'created_at' => now()]);
|
||||
DB::table('a_outbox')->insert(['event_id' => $event, 'state' => 'captured', 'created_at' => now()]);
|
||||
Audit::record("a.$area.".($old ? 'updated' : 'created'), $actor, $scope['tenant_id'], $scope['company_id'], $scope['unit_id'],
|
||||
details: ['area' => $area, 'record_id' => $id, 'version' => $version, 'event_id' => $event]);
|
||||
$result = ['id' => $id, 'version' => $version, 'event_id' => $event];
|
||||
DB::table('a_commands')->insert(['tenant_id' => $scope['tenant_id'], 'company_id' => $scope['company_id'], 'actor_id' => $actor,
|
||||
'command_key' => $key, 'request_hash' => $hash, 'result' => json_encode($result, JSON_THROW_ON_ERROR), 'created_at' => now()]);
|
||||
return $result + ['replayed' => false];
|
||||
});
|
||||
}
|
||||
|
||||
private function normalise(string $area, array $input, array $scope, ?object $old): array
|
||||
{
|
||||
if (! ServicePermissions::unitScoped($area)) {
|
||||
return ['name' => trim($input['name']), 'data' => $area === 'clients' ? [] : ['description' => $input['description'] ?? null]];
|
||||
}
|
||||
$oldData = $old ? json_decode($old->data, true) : [];
|
||||
$actor = $this->context->userId();
|
||||
foreach (['clients.view', 'services.view'] as $permission) { $this->permissions->require($actor, $scope['tenant_id'], $scope['company_id'], $permission); }
|
||||
$source = null;
|
||||
if ($area === 'billing_drafts') {
|
||||
$sourceId = $old ? $old->source_id : $input['source_id'];
|
||||
$source = DB::table('a_service_drafts')->where('tenant_id', $scope['tenant_id'])->where('company_id', $scope['company_id'])->where('unit_id', $scope['unit_id'])->where('id', $sourceId)->first();
|
||||
abort_unless($source, 403, 'Prestação fora da unidade autorizada.');
|
||||
$reload = ! $old || ($input['reload_source'] ?? false);
|
||||
if ($reload) { $this->permissions->require($actor, $scope['tenant_id'], $scope['company_id'], 'service_drafts.view', $scope['unit_id']); }
|
||||
$base = $reload ? json_decode($source->data, true) : $oldData;
|
||||
$clientId = $reload ? $source->client_id : $old->client_id;
|
||||
$lines = $input['lines'] ?? $base['lines'];
|
||||
$allowedIds = array_column($base['lines'], 'service_id');
|
||||
foreach ($lines as $line) { abort_unless(in_array((int) $line['service_id'], $allowedIds, true), 422, 'Use os serviços da prestação de origem.'); }
|
||||
$currency = array_key_exists('currency', $input) ? $input['currency'] : ($base['currency'] ?? null);
|
||||
$sourceVersion = $reload ? (int) $source->version : (int) $oldData['source_version'];
|
||||
} else {
|
||||
$clientId = $input['client_id']; $lines = $input['lines']; $currency = $input['currency'] ?? null;
|
||||
}
|
||||
$client = DB::table('a_clients')->where('tenant_id', $scope['tenant_id'])->where('company_id', $scope['company_id'])->where('id', $clientId)->first();
|
||||
abort_unless($client, 403, 'Cliente fora da empresa autorizada.');
|
||||
$data = ['description' => $input['description'] ?? ($base['description'] ?? ($oldData['description'] ?? null)), 'currency' => $currency,
|
||||
'lines' => DraftValues::lines($lines, $scope), 'client_name' => $client->name, 'tax_status' => 'pending', 'accounting_status' => 'not_processed'];
|
||||
$result = ['client_id' => (int) $clientId, 'state' => 'draft', 'data' => $data,
|
||||
'name' => trim($input['name'] ?? ($old?->name ?? ($area === 'billing_drafts' ? 'Rascunho da prestação #'.$source->id : 'Prestação de '.$client->name)))];
|
||||
if ($source) { $result['source_id'] = $source->id; $result['data']['source_version'] = $sourceVersion; }
|
||||
return $result;
|
||||
}
|
||||
|
||||
private function canonical(mixed $value): mixed
|
||||
{
|
||||
if (! is_array($value)) { return $value; }
|
||||
if (! array_is_list($value)) { ksort($value); }
|
||||
return array_map(fn ($entry) => $this->canonical($entry), $value);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,127 @@
|
||||
<?php
|
||||
namespace App\Modules\Workshop;
|
||||
use App\Modules\Identity\Services\Audit;
|
||||
use App\Modules\Identity\Services\Permissions;
|
||||
use App\Modules\Services\ServiceCalculation;
|
||||
use App\Shared\Context\CompanyContext;
|
||||
use App\Shared\Testing\TestingDatabaseGuard;
|
||||
use Brick\Math\BigDecimal;
|
||||
use Brick\Math\BigRational;
|
||||
use Illuminate\Support\Facades\DB;
|
||||
use Illuminate\Support\Facades\Validator;
|
||||
|
||||
final class DirectCosts
|
||||
{
|
||||
public const POLICY='WORKSHOP-DIRECT-COST-SIM-v1';
|
||||
public const NOTICE='ENSAIO — SEM UTILIZAÇÃO OPERACIONAL';
|
||||
public function __construct(private CompanyContext $context,private Permissions $permissions){}
|
||||
public static function guard(): void {abort_unless(ServiceCalculation::isolated(),403,'Custeio disponível apenas em testes isolados.');TestingDatabaseGuard::assertSafe();}
|
||||
private function scope(int $actor,string $right): array {
|
||||
$s=$this->context->identifiers()+['unit_id'=>$this->context->unitId()];
|
||||
abort_unless($actor===$this->context->userId()&&$s['unit_id']!==null,403);
|
||||
$this->context->selectFor($actor,$s['tenant_id'],$s['company_id'],$s['unit_id']);
|
||||
foreach(['view',$right] as $r)$this->permissions->require($actor,$s['tenant_id'],$s['company_id'],'direct_costs.'.$r,$s['unit_id']);
|
||||
return $s;
|
||||
}
|
||||
private function order(int $id,array $s): object {return DB::table('wo_orders')->where($s)->where('id',$id)->first()??abort(403,'Ordem fora do âmbito de custos.');}
|
||||
private function exact(array $in,array $rules): array {abort_if(array_diff(array_keys($in),array_keys($rules)),422,'Campo fora do âmbito de custos.');return Validator::make($in,$rules)->validate();}
|
||||
private function json(mixed $v): string {return json_encode($v,JSON_THROW_ON_ERROR|JSON_UNESCAPED_UNICODE);}
|
||||
private function canonical(mixed $v): mixed {if(!is_array($v))return $v;if(!array_is_list($v))ksort($v);return array_map(fn($x)=>$this->canonical($x),$v);}
|
||||
private function command(int $order,int $actor,string $action,string $right,array $in,string $key,callable $write): array {
|
||||
self::guard();$s=$this->scope($actor,$right);$this->order($order,$s);
|
||||
abort_unless(preg_match('/^[A-Za-z0-9_-]{8,100}$/D',$key),422,'Chave de repetição obrigatória.');$hash=hash('sha256',$this->json($this->canonical(['order_id'=>$order]+$in)));
|
||||
return DB::transaction(function()use($order,$actor,$action,$right,$in,$key,$hash,$write,$s){
|
||||
DB::table('companies')->where('id',$s['company_id'])->lockForUpdate()->firstOrFail();$this->scope($actor,$right);$this->order($order,$s);
|
||||
$old=DB::table('dc_commands')->where($s)->where(['actor_id'=>$actor,'action'=>$action,'command_key'=>$key])->first();
|
||||
if($old){abort_unless($old->order_id===$order&&hash_equals($old->request_hash,$hash),409,'Repetição com conteúdo diferente.');return json_decode($old->result,true,64,JSON_THROW_ON_ERROR)+['replayed'=>true];}
|
||||
$out=$write($s);
|
||||
$cmd=DB::table('dc_commands')->insertGetId($s+['order_id'=>$order,'actor_id'=>$actor,'action'=>$action,'command_key'=>$key,'request_hash'=>$hash,'result'=>$this->json($out),'created_at'=>now()]);
|
||||
Audit::record('direct_costs.'.$action,$actor,$s['tenant_id'],$s['company_id'],$s['unit_id'],details:['record_id'=>$out['id'],'version'=>$out['version']]);
|
||||
$event=DB::table('dc_events')->insertGetId(['command_id'=>$cmd,'schema_version'=>1,'payload'=>$this->json(['policy'=>self::POLICY,'action'=>$action,'result'=>$out,'scope'=>$s,'actor_id'=>$actor]),'created_at'=>now()]);
|
||||
DB::table('dc_outbox')->insert(['event_id'=>$event,'state'=>'captured_no_accounting']);return $out+['replayed'=>false];
|
||||
},3);
|
||||
}
|
||||
private function source(int $id,int $version,int $order): object {
|
||||
$e=DB::table('wo_entries')->where(['id'=>$id,'version'=>$version,'order_id'=>$order])->first();abort_unless($e,403,'Origem fora da ordem/versão.');
|
||||
$e->data=json_decode($e->data,true,32,JSON_THROW_ON_ERROR);
|
||||
abort_if(DB::table('wo_entries')->where('previous_id',$e->id)->exists()||DB::table('wo_entries')->where('previous_id',$e->task_id)->exists(),409,'Origem ou tarefa desactualizada.');
|
||||
abort_unless(!$e->outside_authority&&DB::table('wo_decisions')->where(['entry_id'=>$id,'entry_version'=>$version,'decision'=>'verified'])->exists(),409,'Origem não verificada/elegível.');
|
||||
abort_unless(($e->kind==='time'&&$e->data['time_type']==='work')||($e->kind==='material'&&$e->data['event']==='consumed'&&$e->data['owner']==='company'),422,'Só trabalho efectivo e consumo da empresa; entrega/devolução não são consumo.');
|
||||
return $e;
|
||||
}
|
||||
private function row(string $kind,int $id,int $order): object {return DB::table($kind==='rate'?'dc_rates':'dc_calculations')->where(['id'=>$id,'order_id'=>$order])->first()??abort(403,'Versão de custo fora da ordem.');}
|
||||
private function current(string $kind,object $row): bool {return !DB::table($kind==='rate'?'dc_rates':'dc_calculations')->where('previous_id',$row->id)->exists();}
|
||||
private function sourceSet(int $order): array {
|
||||
return DB::table('wo_entries as e')->where('e.order_id',$order)->whereIn('e.kind',['time','material'])->whereNotExists(fn($q)=>$q->selectRaw('1')->from('wo_entries as n')->whereColumn('n.previous_id','e.id'))->orderBy('e.id')->pluck('e.id')->all();
|
||||
}
|
||||
public function rate(int $order,int $actor,array $input,string $key): array {
|
||||
self::guard();
|
||||
$d=$this->exact($input,['entry_id'=>'required|integer|min:1','entry_version'=>'required|integer|min:1','identifier'=>'required|string|min:3|max:80','version'=>'required|integer|min:1','previous_id'=>'nullable|integer|min:1','currency'=>'required|in:MZN','unit'=>'required|in:UN,KG,M,L,H','amount'=>['required','string','regex:/^(?:0|[1-9][0-9]{0,15})(?:\.[0-9]{1,8})?$/D'],'evidence'=>'required|string|min:3|max:1000']);
|
||||
return $this->command($order,$actor,'rate','prepare',$d,$key,function($s)use($order,$actor,$d){
|
||||
$e=$this->source($d['entry_id'],$d['entry_version'],$order);abort_unless($d['unit']===($e->kind==='time'?'H':$e->data['unit']),422,'Unidade da taxa incompatível com a origem.');
|
||||
$last=DB::table('dc_rates')->where(['order_id'=>$order,'identifier'=>$d['identifier']])->orderByDesc('version')->first();
|
||||
abort_unless($d['version']===($last?->version??0)+1&&($d['previous_id']??null)===$last?->id,409,'Versão anterior exacta necessária.');
|
||||
$id=DB::table('dc_rates')->insertGetId($s+array_merge($d,['order_id'=>$order,'amount'=>(string)BigDecimal::of($d['amount'])->stripTrailingZeros(),'actor_id'=>$actor,'created_at'=>now()]));return ['id'=>$id,'version'=>$d['version'],'kind'=>'rate'];
|
||||
});
|
||||
}
|
||||
private function value(BigRational $n): string {try{return (string)$n->toBigDecimal()->stripTrailingZeros();}catch(\Brick\Math\Exception\RoundingNecessaryException){return (string)$n->simplified();}}
|
||||
private function compose(int $order,array $lines): array {
|
||||
abort_unless(count($lines)===2,422,'Este ensaio exige um consumo e um tempo efectivos.');$out=[];$seen=[];$kinds=[];$pending=[];$sum=BigRational::of(0);
|
||||
foreach($lines as $line){
|
||||
$d=$this->exact($line,['entry_id'=>'required|integer|min:1','entry_version'=>'required|integer|min:1','rate_id'=>'present|nullable|integer|min:1','rate_version'=>'present|nullable|integer|min:1']);
|
||||
$e=$this->source($d['entry_id'],$d['entry_version'],$order);abort_if(isset($seen[$e->id]),422,'Origem duplicada.');$seen[$e->id]=true;$kinds[]=$e->kind;
|
||||
$quantity=$e->kind==='time'?BigRational::of($e->minutes)->dividedBy(60):BigRational::of($e->quantity);
|
||||
$rate=null;$cost=null;
|
||||
if($d['rate_id']!==null){
|
||||
$r=$this->row('rate',$d['rate_id'],$order);
|
||||
abort_unless($d['rate_version']===$r->version&&$r->entry_id===$e->id&&$r->entry_version===$e->version&&$r->currency==='MZN'&&$r->unit===($e->kind==='time'?'H':$e->data['unit']),409,'Taxa/versão/unidade/moeda incompatível.');
|
||||
abort_unless($this->current('rate',$r)&&DB::table('dc_decisions')->where(['rate_id'=>$r->id,'decision'=>'approved'])->exists(),409,'Taxa exige versão actual aprovada; selecção explícita.');
|
||||
$rate=(string)BigDecimal::of($r->amount)->stripTrailingZeros();$cost=$quantity->multipliedBy($rate);$sum=$sum->plus($cost);
|
||||
}else{abort_unless($d['rate_version']===null,422,'Taxa ausente não tem versão.');$pending[]='Taxa em falta para origem #'.$e->id.' v'.$e->version;}
|
||||
$out[]=$d+['kind'=>$e->kind,'origin'=>$e->origin,'quantity'=>$e->kind==='time'?(string)$e->minutes:(string)BigDecimal::of($e->quantity)->stripTrailingZeros(),'source_unit'=>$e->kind==='time'?'MIN':$e->data['unit'],'cost_quantity_exact'=>$this->value($quantity),'rate_unit'=>$e->kind==='time'?'H':$e->data['unit'],'rate_amount'=>$rate,'cost_exact'=>$cost===null?null:$this->value($cost)];
|
||||
}
|
||||
sort($kinds);abort_unless($kinds===['material','time'],422,'Um consumo e um tempo, sem duplicação.');usort($out,fn($a,$b)=>$a['entry_id']<=>$b['entry_id']);
|
||||
return ['policy'=>self::POLICY,'currency'=>'MZN','label'=>'Custo directo conhecido — não é custo completo ou margem','lines'=>$out,'known_subtotal_exact'=>$this->value($sum),'selected_direct_total_exact'=>$pending?null:$this->value($sum),'incomplete'=>$pending!==[],'pending'=>$pending,'source_set'=>$this->sourceSet($order),'scope'=>'Duas origens seleccionadas; sem custos indirectos ou valorização de inventário'];
|
||||
}
|
||||
private function calculationCurrent(object $row): bool {
|
||||
if(!$this->current('calculation',$row))return false;
|
||||
try{$snapshot=json_decode($row->snapshot,true,64,JSON_THROW_ON_ERROR);$lines=array_map(fn($l)=>array_intersect_key($l,array_flip(['entry_id','entry_version','rate_id','rate_version'])),$snapshot['lines']);return hash_equals($row->fingerprint,hash('sha256',$this->json($this->compose($row->order_id,$lines))));}
|
||||
catch(\Symfony\Component\HttpKernel\Exception\HttpExceptionInterface){return false;}
|
||||
}
|
||||
public function calculate(int $order,int $actor,array $input,string $key): array {
|
||||
self::guard();
|
||||
$d=$this->exact($input,['version'=>'required|integer|min:1','previous_id'=>'nullable|integer|min:1','currency'=>'required|in:MZN','lines'=>'required|array|size:2']);
|
||||
return $this->command($order,$actor,'calculate','prepare',$d,$key,function($s)use($order,$actor,$d){
|
||||
$last=DB::table('dc_calculations')->where('order_id',$order)->orderByDesc('version')->first();
|
||||
abort_unless($d['version']===($last?->version??0)+1&&($d['previous_id']??null)===$last?->id,409,'Cálculo mudou; rever versão anterior.');
|
||||
$snapshot=$this->compose($order,$d['lines']);$hash=hash('sha256',$this->json($snapshot));
|
||||
if($last&&hash_equals($last->fingerprint,$hash))return ['id'=>$last->id,'version'=>$last->version,'kind'=>'calculation','unchanged'=>true];
|
||||
$id=DB::table('dc_calculations')->insertGetId($s+['order_id'=>$order,'version'=>$d['version'],'previous_id'=>$last?->id,'fingerprint'=>$hash,'snapshot'=>$this->json($snapshot),'actor_id'=>$actor,'created_at'=>now()]);return ['id'=>$id,'version'=>$d['version'],'kind'=>'calculation'];
|
||||
});
|
||||
}
|
||||
public function decide(int $order,int $actor,array $input,string $key): array {
|
||||
self::guard();
|
||||
$d=$this->exact($input,['kind'=>'required|in:rate,calculation','id'=>'required|integer|min:1','version'=>'required|integer|min:1','decision'=>'required|in:approved,refused','reason'=>'required|string|min:3|max:1000']);
|
||||
return $this->command($order,$actor,'decide','validate',$d,$key,function($s)use($order,$actor,$d){
|
||||
$r=$this->row($d['kind'],$d['id'],$order);abort_if($r->actor_id===$actor,403,'Validador deve ser distinto do preparador.');
|
||||
abort_unless($r->version===$d['version']&&$this->current($d['kind'],$r),409,'Versão antiga.');
|
||||
if($d['kind']==='rate')$this->source($r->entry_id,$r->entry_version,$order);else abort_unless($this->calculationCurrent($r),409,'Dependências alteradas; preparar nova versão.');
|
||||
$field=$d['kind']==='rate'?'rate_id':'calculation_id';abort_if(DB::table('dc_decisions')->where($field,$r->id)->exists(),409,'Versão já decidida.');
|
||||
$id=DB::table('dc_decisions')->insertGetId([$field=>$r->id,'version'=>$r->version,'decision'=>$d['decision'],'reason'=>$d['reason'],'actor_id'=>$actor,'created_at'=>now()]);return ['id'=>$id,'version'=>$r->version,'kind'=>'decision','target_id'=>$r->id];
|
||||
});
|
||||
}
|
||||
public function listing(int $actor): array {
|
||||
$s=$this->scope($actor,'view');if(!ServiceCalculation::isolated())return ['blocked'=>true,'orders'=>[],'notice'=>self::NOTICE];self::guard();
|
||||
return DB::transaction(function()use($s){
|
||||
DB::table('companies')->where('id',$s['company_id'])->lockForUpdate()->firstOrFail();$orders=[];
|
||||
foreach(DB::table('wo_orders')->where($s)->orderBy('id')->get(['id','reference']) as $o){
|
||||
$sources=[];foreach(DB::table('wo_entries')->where('order_id',$o->id)->whereIn('kind',['time','material'])->orderBy('id')->get(['id','version']) as $entry){
|
||||
try{$e=$this->source($entry->id,$entry->version,$o->id);$sources[]=['id'=>$e->id,'version'=>$e->version,'kind'=>$e->kind,'origin'=>$e->origin,'quantity'=>$e->kind==='time'?(string)$e->minutes:(string)$e->quantity,'unit'=>$e->kind==='time'?'MIN':$e->data['unit']];}catch(\Symfony\Component\HttpKernel\Exception\HttpExceptionInterface){}
|
||||
}
|
||||
$rates=DB::table('dc_rates')->where('order_id',$o->id)->orderBy('id')->get();foreach($rates as $r){$r->current=$this->current('rate',$r);$r->decision=DB::table('dc_decisions')->where('rate_id',$r->id)->first();}
|
||||
$calculations=DB::table('dc_calculations')->where('order_id',$o->id)->orderBy('id')->get();foreach($calculations as $c){$c->snapshot=json_decode($c->snapshot,true,64,JSON_THROW_ON_ERROR);$copy=clone $c;$copy->snapshot=$this->json($c->snapshot);$c->current=$this->calculationCurrent($copy);$c->decision=DB::table('dc_decisions')->where('calculation_id',$c->id)->first();}
|
||||
$orders[]=(array)$o+['sources'=>$sources,'rates'=>$rates->all(),'calculations'=>$calculations->all()];
|
||||
}return ['blocked'=>false,'notice'=>self::NOTICE,'orders'=>$orders,'policy'=>self::POLICY];
|
||||
});
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,12 @@
|
||||
<?php
|
||||
namespace App\Modules\Workshop\Http;
|
||||
use App\Http\Controllers\Controller;
|
||||
use App\Modules\Workshop\DirectCosts;
|
||||
use Illuminate\Http\Request;
|
||||
final class DirectCostsController extends Controller {
|
||||
private function response(array $d){return response()->json($d)->header('Cache-Control','no-store, private');}
|
||||
public function index(Request $r,DirectCosts $d){return $this->response($d->listing($r->user()->id));}
|
||||
public function rate(Request $r,int $id,DirectCosts $d){return $this->response($d->rate($id,$r->user()->id,$r->all(),(string)$r->header('Idempotency-Key')));}
|
||||
public function calculate(Request $r,int $id,DirectCosts $d){return $this->response($d->calculate($id,$r->user()->id,$r->all(),(string)$r->header('Idempotency-Key')));}
|
||||
public function decide(Request $r,int $id,DirectCosts $d){return $this->response($d->decide($id,$r->user()->id,$r->all(),(string)$r->header('Idempotency-Key')));}
|
||||
}
|
||||
@@ -0,0 +1,13 @@
|
||||
<?php
|
||||
namespace App\Modules\Workshop\Http;
|
||||
use App\Http\Controllers\Controller;
|
||||
use App\Modules\Workshop\WorkshopWorkflow;
|
||||
use Illuminate\Http\Request;
|
||||
final class WorkshopController extends Controller
|
||||
{
|
||||
private function response(array $data) { return response()->json($data)->header('Cache-Control','no-store, private'); }
|
||||
public function index(Request $r,WorkshopWorkflow $w) { return $this->response($w->listing($r->user()->id)); }
|
||||
public function open(Request $r,WorkshopWorkflow $w) { return $this->response($w->open($r->user()->id,$r->all(),(string)$r->header('Idempotency-Key'))); }
|
||||
public function record(Request $r,int $id,WorkshopWorkflow $w) { return $this->response($w->record($id,$r->user()->id,$r->all(),(string)$r->header('Idempotency-Key'))); }
|
||||
public function verify(Request $r,int $id,WorkshopWorkflow $w) { return $this->response($w->verify($id,$r->user()->id,$r->all(),(string)$r->header('Idempotency-Key'))); }
|
||||
}
|
||||
@@ -0,0 +1,239 @@
|
||||
<?php
|
||||
namespace App\Modules\Workshop;
|
||||
|
||||
use App\Modules\Identity\Services\Audit;
|
||||
use App\Modules\Identity\Services\Permissions;
|
||||
use App\Modules\Services\DraftValues;
|
||||
use App\Modules\Services\ServiceCalculation;
|
||||
use App\Shared\Context\CompanyContext;
|
||||
use App\Shared\Testing\TestingDatabaseGuard;
|
||||
use Carbon\CarbonImmutable;
|
||||
use Illuminate\Support\Facades\DB;
|
||||
use Illuminate\Support\Facades\Validator;
|
||||
|
||||
final class WorkshopWorkflow
|
||||
{
|
||||
public const POLICY='WORKSHOP-RESOURCE-RECORD-v1';
|
||||
public const NOTICE='TESTE — SEM UTILIZAÇÃO OPERACIONAL';
|
||||
public const ZONE='Africa/Johannesburg';
|
||||
public function __construct(private CompanyContext $context,private Permissions $permissions) {}
|
||||
public static function guard(): void {
|
||||
abort_unless(ServiceCalculation::isolated(),403,'Oficina disponível apenas na instância isolada de testes.');
|
||||
TestingDatabaseGuard::assertSafe();
|
||||
}
|
||||
private function scope(int $actor,string $right): array {
|
||||
$s=$this->context->identifiers()+['unit_id'=>$this->context->unitId()];
|
||||
abort_unless($s['unit_id']!==null && $actor===$this->context->userId(),403);
|
||||
$this->context->selectFor($actor,$s['tenant_id'],$s['company_id'],$s['unit_id']);
|
||||
foreach(['view',$right] as $r) $this->permissions->require($actor,$s['tenant_id'],$s['company_id'],'workshop.'.$r,$s['unit_id']);
|
||||
return $s;
|
||||
}
|
||||
private function has(int $actor,string $right,array $s): bool { return $this->permissions->has($actor,$s['tenant_id'],$s['company_id'],'workshop.'.$right,$s['unit_id']); }
|
||||
private function data(object $r): array { return json_decode($r->data,true,32,JSON_THROW_ON_ERROR); }
|
||||
private function json(mixed $value): string { return json_encode($value,JSON_THROW_ON_ERROR|JSON_UNESCAPED_UNICODE); }
|
||||
private function exact(array $data,array $rules): array {
|
||||
abort_if(array_diff(array_keys($data),array_keys($rules)),422,'Campo protegido ou fora do recorte.');
|
||||
return Validator::make($data,$rules)->validate();
|
||||
}
|
||||
private function canonical(mixed $v): mixed {
|
||||
if(!is_array($v)) return $v;
|
||||
if(!array_is_list($v)) ksort($v);
|
||||
return array_map(fn($x)=>$this->canonical($x),$v);
|
||||
}
|
||||
private function revision(int $id): int { return (int)DB::selectOne('SELECT sgf_wo_revision(?) AS v',[$id])->v; }
|
||||
private function order(int $id,int $actor,array $s): object {
|
||||
$o=DB::table('wo_orders')->where($s)->where('id',$id)->first();
|
||||
abort_unless($o,403,'Ordem fora do âmbito autorizado.');
|
||||
if(!$this->has($actor,'open',$s) && !$this->has($actor,'assign',$s) && !$this->has($actor,'authorize',$s) && !$this->has($actor,'verify',$s)) {
|
||||
abort_unless((int)DB::table('wo_entries')->where(['order_id'=>$id,'kind'=>'assignment'])->orderByDesc('id')->value('technician_id')===$actor,403,'Ordem não atribuída ao técnico.');
|
||||
}
|
||||
return $o;
|
||||
}
|
||||
private function entry(int $id,int $order,?string $kind=null): object {
|
||||
$q=DB::table('wo_entries')->where(['order_id'=>$order,'id'=>$id]); if($kind) $q->where('kind',$kind);
|
||||
return $q->first()??abort(403,'Apontamento/origem fora da ordem.');
|
||||
}
|
||||
private function current(object $e): bool { return !DB::table('wo_entries')->where('previous_id',$e->id)->exists(); }
|
||||
private function command(int $actor,string $right,string $key,array $input,?int $order,callable $write): array {
|
||||
self::guard(); $s=$this->scope($actor,$right);
|
||||
abort_unless(preg_match('/^[A-Za-z0-9_-]{8,100}$/D',$key),422,'Chave de idempotência obrigatória.');
|
||||
$hash=hash('sha256',$this->json($this->canonical($input)));
|
||||
return DB::transaction(function()use($actor,$right,$key,$hash,$s,$write,$order) {
|
||||
DB::table('companies')->where('id',$s['company_id'])->lockForUpdate()->firstOrFail(); $this->scope($actor,$right);
|
||||
if($order) $this->order($order,$actor,$s);
|
||||
$old=DB::table('wo_commands')->where($s)->where(['actor_id'=>$actor,'action'=>$right,'command_key'=>$key])->first();
|
||||
if($old) {
|
||||
$this->order($old->order_id,$actor,$s);
|
||||
abort_unless(hash_equals($old->request_hash,$hash),409,'Chave repetida com conteúdo diferente.');
|
||||
return json_decode($old->result,true,32,JSON_THROW_ON_ERROR)+['replayed'=>true];
|
||||
}
|
||||
$out=$write($s);
|
||||
$cmd=DB::table('wo_commands')->insertGetId($s+['actor_id'=>$actor,'action'=>$right,'command_key'=>$key,'request_hash'=>$hash,'order_id'=>$out['order_id'],'result'=>$this->json($out),'created_at'=>now()]);
|
||||
Audit::record('workshop.'.$out['event'],$actor,$s['tenant_id'],$s['company_id'],$s['unit_id'],details:['record_id'=>$out['id'],'version'=>$out['version']??1]);
|
||||
$event=DB::table('wo_events')->insertGetId(['command_id'=>$cmd,'type'=>$out['event'],'schema_version'=>1,'payload'=>$this->json($s+['policy'=>self::POLICY,'actor_id'=>$actor,'command_id'=>$cmd,'result'=>$out]),'created_at'=>now()]);
|
||||
DB::table('wo_outbox')->insert(['event_id'=>$event,'state'=>'captured_no_cost_stock_or_billing']);
|
||||
return $out+['replayed'=>false];
|
||||
},3);
|
||||
}
|
||||
public function open(int $actor,array $input,string $key): array {
|
||||
self::guard();
|
||||
$d=$this->exact($input,['reference'=>'required|string|min:3|max:100','client_id'=>'required|integer|min:1','equipment_id'=>'nullable|integer|min:1','equipment_identifier'=>'required_without:equipment_id|string|max:100','equipment_description'=>'required_without:equipment_id|string|max:300','serial'=>'nullable|string|max:100','request'=>'required|string|min:3|max:2000','location'=>'required|string|max:300','evidence'=>'required|string|min:3|max:500']);
|
||||
return $this->command($actor,'open',$key,$d,null,function($s)use($d,$actor) {
|
||||
abort_unless(DB::table('a_clients')->where(['id'=>$d['client_id'],'tenant_id'=>$s['tenant_id'],'company_id'=>$s['company_id']])->exists(),403,'Cliente de outra empresa.');
|
||||
abort_if(DB::table('wo_orders')->where(['company_id'=>$s['company_id'],'reference'=>$d['reference']])->exists(),409,'Referência de ordem já existente.');
|
||||
$equipment=$d['equipment_id']??null;
|
||||
if($equipment) abort_unless(DB::table('wo_equipment')->where(['id'=>$equipment,'tenant_id'=>$s['tenant_id'],'company_id'=>$s['company_id'],'client_id'=>$d['client_id']])->exists(),403,'Equipamento incompatível com o cliente.');
|
||||
else {
|
||||
abort_if(DB::table('wo_equipment')->where(['company_id'=>$s['company_id'],'identifier'=>$d['equipment_identifier']])->exists(),409,'Equipamento já identificado; reutilize o ID existente.');
|
||||
$equipment=DB::table('wo_equipment')->insertGetId(['tenant_id'=>$s['tenant_id'],'company_id'=>$s['company_id'],'client_id'=>$d['client_id'],'identifier'=>$d['equipment_identifier'],'description'=>$d['equipment_description'],'serial'=>$d['serial']??null,'actor_id'=>$actor,'created_at'=>now()]);
|
||||
}
|
||||
$id=DB::table('wo_orders')->insertGetId($s+['client_id'=>$d['client_id'],'equipment_id'=>$equipment,'reference'=>$d['reference'],'request'=>$d['request'],'location'=>$d['location'],'evidence'=>$d['evidence'],'actor_id'=>$actor,'created_at'=>now()]);
|
||||
return ['id'=>$id,'order_id'=>$id,'equipment_id'=>$equipment,'event'=>'order.opened','version'=>1];
|
||||
});
|
||||
}
|
||||
private function timestamp(string $value): string {
|
||||
abort_unless(preg_match('/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?(Z|[+-]\d{2}:\d{2})$/D',$value),422,'Use data/hora completa com zona explícita.');
|
||||
try { return CarbonImmutable::parse($value)->utc()->format('Y-m-d\TH:i:sP'); }
|
||||
catch(\Throwable) { abort(422,'Data/hora inválida.'); }
|
||||
}
|
||||
public function record(int $id,int $actor,array $input,string $key): array {
|
||||
self::guard();
|
||||
$d=$this->exact($input,['kind'=>'required|in:assignment,task,authorization,start,time,material','origin'=>'required|string|min:3|max:100','revision'=>'required|integer|min:0','previous_id'=>'nullable|integer|min:1','correction_reason'=>'nullable|string|min:3|max:1000','version'=>'required|integer|min:1',
|
||||
'technician_id'=>'nullable|integer|min:1','task_id'=>'nullable|integer|min:1','authorization_id'=>'nullable|integer|min:1','start_id'=>'nullable|integer|min:1',
|
||||
'description'=>'nullable|string|min:3|max:2000','service_id'=>'nullable|integer|min:1','evidence'=>'nullable|string|min:3|max:1000',
|
||||
'authorized_by'=>'nullable|string|min:3|max:255','capacity'=>'nullable|string|min:3|max:255','authorized_at'=>'nullable|date','channel'=>'nullable|string|min:3|max:100','scope'=>'nullable|string|min:3|max:2000',
|
||||
'starts_at'=>'nullable|date','ends_at'=>'nullable|date','pauses'=>'nullable|array|max:100','pauses.*'=>'array:start,end','pauses.*.start'=>'required|date','pauses.*.end'=>'required|date','mode'=>'nullable|in:reported,started','time_type'=>'nullable|in:work,travel',
|
||||
'quantity'=>'nullable|string','resource'=>'nullable|string|min:2|max:100','unit'=>'nullable|in:UN,KG,M,L','owner'=>'nullable|in:company,client','event'=>'nullable|in:required,delivered,consumed,returned']);
|
||||
foreach(['starts_at','ends_at','authorized_at'] as $field) if(isset($d[$field])) $d[$field]=$this->timestamp($d[$field]);
|
||||
if(isset($d['quantity'])) $d['quantity']=DraftValues::decimal($d['quantity'],'quantity',true);
|
||||
$d['pauses']=array_map(fn($p)=>['start'=>$this->timestamp($p['start']),'end'=>$this->timestamp($p['end'])],$d['pauses']??[]);
|
||||
$right=match($d['kind']) {'assignment'=>'assign','authorization'=>'authorize',default=>'record'};
|
||||
return $this->command($actor,$right,$key,['order_id'=>$id]+$d,$id,function($s)use($id,$actor,$d) {
|
||||
abort_unless((int)$d['revision']===$this->revision($id),409,'Revisão da ordem desactualizada.');
|
||||
$kind=$d['kind']; $prev=null;
|
||||
if(!empty($d['previous_id'])) {
|
||||
$prev=$this->entry($d['previous_id'],$id,$kind);
|
||||
abort_unless($this->current($prev) && $prev->origin===$d['origin'] && (int)$d['version']===$prev->version+1 && !empty($d['correction_reason']),409,'Nova versão exige origem, motivo e versão anterior exactos.');
|
||||
if(in_array($kind,['time','material','task'])) abort_unless($prev->actor_id===$actor,403,'Não pode corrigir o apontamento de outro autor.');
|
||||
} else {
|
||||
abort_unless((int)$d['version']===1,422);
|
||||
abort_if(DB::table('wo_entries')->where(['order_id'=>$id,'kind'=>$kind,'origin'=>$d['origin']])->exists(),409,'Origem já registada; corrija por versão explícita.');
|
||||
}
|
||||
$assigned=(int)DB::table('wo_entries')->where(['order_id'=>$id,'kind'=>'assignment'])->orderByDesc('id')->value('technician_id');
|
||||
$tech=null; $task=null; $auth=null; $start=null; $minutes=null; $quantity=null; $outside=false; $starts=$d['starts_at']??null; $ends=$d['ends_at']??null;
|
||||
if($kind==='assignment') {
|
||||
$tech=$d['technician_id']??0;
|
||||
foreach(['view','record'] as $r) $this->permissions->require($tech,$s['tenant_id'],$s['company_id'],'workshop.'.$r,$s['unit_id']);
|
||||
}
|
||||
if(in_array($kind,['task','start','time','material'])) { abort_unless($assigned===$actor,403,'Apenas o técnico atribuído regista.'); $tech=$actor; }
|
||||
if($kind==='task') abort_unless(!empty($d['description']),422,'Descrição da tarefa necessária.');
|
||||
if(in_array($kind,['authorization','start','time','material'])) {
|
||||
$task=$this->entry((int)($d['task_id']??0),$id,'task');
|
||||
if(in_array($kind,['authorization','start'])) abort_unless($this->current($task),409,'Tarefa tem nova versão; reveja âmbito.');
|
||||
}
|
||||
if($kind==='authorization') {
|
||||
foreach(['authorized_by','capacity','authorized_at','channel','scope','evidence'] as $field) abort_unless(!empty($d[$field]),422,'Autorização: pessoa, qualidade, data, canal, âmbito e comprovativo necessários.');
|
||||
abort_if(CarbonImmutable::parse($d['authorized_at'])->isAfter(now()),422,'Autorização futura não é facto.');
|
||||
// Revisions of one authorization cannot silently move to another task or authorize it retroactively.
|
||||
if($prev) abort_unless($prev->task_id===$task->id || !$this->current($this->entry($prev->task_id,$id,'task')),409,'Alteração de tarefa exige revisão explícita da origem.');
|
||||
}
|
||||
if(in_array($kind,['start','time','material'])) {
|
||||
abort_unless(!empty($d['evidence']),422,'Evidência da ocorrência necessária.');
|
||||
if(!empty($d['authorization_id'])) $auth=$this->entry($d['authorization_id'],$id,'authorization');
|
||||
if($auth) abort_unless($auth->task_id===$task->id,409,'Autorização não cobre esta versão da tarefa.');
|
||||
if($kind==='start') { $starts=now()->toIso8601String(); $ends=null; }
|
||||
$outside=!$auth || !$this->current($auth) || !$this->current($task) || CarbonImmutable::parse($auth->created_at)->isAfter(CarbonImmutable::parse($starts??now())) || CarbonImmutable::parse($this->data($auth)['authorized_at'])->isAfter(CarbonImmutable::parse($starts??now()));
|
||||
if($kind==='start') {
|
||||
abort_if($outside,409,'Início bloqueado: autorização da versão da tarefa necessária. Pode relatar uma ocorrência já acontecida para revisão.');
|
||||
abort_if(DB::table('wo_entries as e')->join('wo_orders as o','o.id','=','e.order_id')->where('o.company_id',$s['company_id'])->where(['e.kind'=>'start','e.technician_id'=>$actor])->whereNotExists(fn($q)=>$q->selectRaw('1')->from('wo_entries as done')->whereColumn('done.start_id','e.id'))->exists(),409,'Já existe trabalho iniciado sem apontamento final.');
|
||||
}
|
||||
if($kind==='time') {
|
||||
abort_unless($starts && $ends && !empty($d['time_type']) && !empty($d['mode']),422,'Intervalo, tipo e modo de relato necessários.');
|
||||
$from=CarbonImmutable::parse($starts); $to=CarbonImmutable::parse($ends);
|
||||
abort_unless($to->isAfter($from) && !$to->isAfter(now()),422,'Intervalo inválido ou ocorrência futura.');
|
||||
$seconds=$to->getTimestamp()-$from->getTimestamp(); $last=$from;
|
||||
foreach($d['pauses'] as $pause) {
|
||||
$a=CarbonImmutable::parse($pause['start']); $b=CarbonImmutable::parse($pause['end']);
|
||||
abort_unless(!$a->isBefore($last) && $b->isAfter($a) && !$b->isAfter($to),422,'Pausas inválidas/sobrepostas.');
|
||||
$seconds-=$b->getTimestamp()-$a->getTimestamp(); $last=$b;
|
||||
}
|
||||
abort_unless($seconds>0 && $seconds%60===0,422,'Tempo efectivo deve ser exactamente representável em minutos; sem truncagem.'); $minutes=intdiv($seconds,60);
|
||||
if(!empty($d['start_id'])) {
|
||||
$start=$this->entry($d['start_id'],$id,'start');
|
||||
abort_unless($start->technician_id===$actor && $start->task_id===$task->id && $start->authorization_id===($auth?->id) && CarbonImmutable::parse($start->starts_at)->eq($from),409,'Início incompatível.');
|
||||
abort_if(DB::table('wo_entries')->where('start_id',$start->id)->exists(),409,'Início já concluído.');
|
||||
} else abort_unless($d['mode']==='reported',422,'Seleccione relato de ocorrência ou indique início existente.');
|
||||
// A correction cannot silently turn an already reported exception into authorized work.
|
||||
if($prev && $prev->outside_authority) $outside=true;
|
||||
$overlap=DB::table('wo_entries as e')->join('wo_orders as o','o.id','=','e.order_id')->where('o.company_id',$s['company_id'])->where(['e.kind'=>'time','e.technician_id'=>$actor])->whereNotExists(fn($q)=>$q->selectRaw('1')->from('wo_entries as n')->whereColumn('n.previous_id','e.id'))->when($prev,fn($q)=>$q->where('e.id','<>',$prev->id))->where('e.starts_at','<',$ends)->where('e.ends_at','>',$starts)->exists();
|
||||
abort_if($overlap,409,'Intervalo sobreposto do mesmo técnico; não será duplicado.');
|
||||
}
|
||||
if($kind==='material') {
|
||||
foreach(['quantity','resource','unit','owner','event','starts_at'] as $f) abort_unless(isset($d[$f]),422,'Material: recurso, unidade, propriedade, tipo, quantidade e data necessários.');
|
||||
abort_if(CarbonImmutable::parse($starts)->isAfter(now()),422,'Ocorrência futura não é material observado.');
|
||||
$quantity=$d['quantity'];
|
||||
foreach(DB::table('wo_entries')->where(['order_id'=>$id,'kind'=>'material'])->get() as $other) {
|
||||
$od=$this->data($other);
|
||||
if($od['resource']===$d['resource']) abort_unless($od['unit']===$d['unit'] && $od['owner']===$d['owner'],409,'A referência material conserva unidade e propriedade.');
|
||||
}
|
||||
if($prev) { $pd=$this->data($prev); foreach(['resource','unit','owner','event'] as $field) abort_unless($pd[$field]===$d[$field],409,'A correcção não pode transferir a origem material para outro acontecimento.'); }
|
||||
if($d['event']!=='consumed') $outside=false;
|
||||
if($prev && $prev->outside_authority) $outside=true;
|
||||
}
|
||||
}
|
||||
$data=$d+['policy'=>self::POLICY];
|
||||
$entry=DB::table('wo_entries')->insertGetId(['order_id'=>$id,'kind'=>$kind,'origin'=>$d['origin'],'version'=>$d['version'],'previous_id'=>$prev?->id,'task_id'=>$task?->id,'authorization_id'=>$auth?->id,'start_id'=>$start?->id,'technician_id'=>$tech,'starts_at'=>$starts,'ends_at'=>$ends,'minutes'=>$minutes,'quantity'=>$quantity,'outside_authority'=>$outside,'revision'=>$d['revision'],'data'=>$this->json($data),'actor_id'=>$actor,'created_at'=>now()]);
|
||||
$actual=DB::table('wo_entries')->find($entry);
|
||||
return ['id'=>$entry,'order_id'=>$id,'version'=>(int)$d['version'],'event'=>$kind.'.recorded','outside_authority'=>(bool)$actual->outside_authority,'revision'=>$this->revision($id)];
|
||||
});
|
||||
}
|
||||
public function verify(int $id,int $actor,array $input,string $key): array {
|
||||
self::guard(); $s=$this->scope($actor,'verify'); $entry=DB::table('wo_entries')->find($id); abort_unless($entry,403); $this->order($entry->order_id,$actor,$s);
|
||||
$d=$this->exact($input,['version'=>'required|integer|min:1','revision'=>'required|integer|min:0','decision'=>'required|in:verified,refused,acknowledged','reason'=>'required|string|min:3|max:1000']);
|
||||
return $this->command($actor,'verify',$key,['entry_id'=>$id]+$d,$entry->order_id,function($s)use($entry,$actor,$d) {
|
||||
$e=$this->entry($entry->id,$entry->order_id);
|
||||
abort_unless(in_array($e->kind,['task','time','material']),422,'Este registo não é apontamento verificável.');
|
||||
abort_if($e->actor_id===$actor,403,'Verificador deve ser distinto do autor.');
|
||||
abort_unless($this->current($e) && (int)$d['version']===$e->version && (int)$d['revision']===$this->revision($e->order_id),409,'Versão/revisão desactualizada.');
|
||||
abort_if(DB::table('wo_decisions')->where('entry_id',$e->id)->exists(),409,'Versão já decidida.');
|
||||
abort_if($e->outside_authority && $d['decision']==='verified',409,'Fora do âmbito: pode reconhecer a ocorrência para auditoria ou recusar, sem autorizar retroactivamente.');
|
||||
abort_if(!$e->outside_authority && $d['decision']==='acknowledged',422,'Reconhecimento de excepção apenas para ocorrência fora do âmbito.');
|
||||
$decision=DB::table('wo_decisions')->insertGetId(['entry_id'=>$e->id,'entry_version'=>$d['version'],'revision'=>$d['revision'],'decision'=>$d['decision'],'reason'=>$d['reason'],'actor_id'=>$actor,'created_at'=>now()]);
|
||||
return ['id'=>$decision,'entry_id'=>$e->id,'order_id'=>$e->order_id,'version'=>$e->version,'event'=>'entry.'.$d['decision'],'revision'=>$this->revision($e->order_id)];
|
||||
});
|
||||
}
|
||||
public function listing(int $actor): array {
|
||||
$s=$this->scope($actor,'view');
|
||||
if(!ServiceCalculation::isolated()) return ['blocked'=>true,'notice'=>self::NOTICE,'orders'=>[]];
|
||||
self::guard();
|
||||
return DB::transaction(function()use($s,$actor) {
|
||||
DB::table('companies')->where('id',$s['company_id'])->lockForUpdate()->firstOrFail();
|
||||
$orders=[];
|
||||
foreach(DB::table('wo_orders')->where($s)->orderBy('id')->get() as $o) {
|
||||
try {$this->order($o->id,$actor,$s);} catch(\Symfony\Component\HttpKernel\Exception\HttpExceptionInterface) {continue;}
|
||||
$entries=DB::table('wo_entries')->where('order_id',$o->id)->orderBy('id')->get();
|
||||
foreach($entries as $e) {
|
||||
$e->data=$this->data($e); $e->current=$this->current($e);
|
||||
$e->decision=DB::table('wo_decisions')->where('entry_id',$e->id)->first();
|
||||
}
|
||||
$current=$entries->where('current',true); $points=$current->whereIn('kind',['task','time','material']);
|
||||
$exception=$points->contains(fn($e)=>$e->outside_authority);
|
||||
$pending=$points->contains(fn($e)=>!$e->decision || $e->decision->decision!=='verified');
|
||||
$state=$points->isEmpty()?'open':($exception?'exception_review':($pending?'in_review':'records_verified'));
|
||||
$materials=[];
|
||||
foreach($current->where('kind','material') as $e) {
|
||||
$k=$e->data['resource'].'|'.$e->data['owner'].'|'.$e->data['unit'];
|
||||
$materials[$k]??=['resource'=>$e->data['resource'],'unit'=>$e->data['unit'],'owner'=>$e->data['owner'],'required'=>'0','delivered'=>'0','consumed'=>'0','returned'=>'0','verified_consumed'=>'0'];
|
||||
$event=$e->data['event']; $materials[$k][$event]=(string)\Brick\Math\BigDecimal::of($materials[$k][$event])->plus($e->quantity);
|
||||
if($event==='consumed' && $e->decision?->decision==='verified') $materials[$k]['verified_consumed']=(string)\Brick\Math\BigDecimal::of($materials[$k]['verified_consumed'])->plus($e->quantity);
|
||||
}
|
||||
foreach($materials as &$m) { $m['unexplained']=(string)\Brick\Math\BigDecimal::of($m['delivered'])->minus($m['consumed'])->minus($m['returned']); $m['status']=$m['unexplained']==='0'?'balanced_observations':'pending_physical_explanation'; } unset($m);
|
||||
$orders[]=(array)$o+['equipment'=>DB::table('wo_equipment')->find($o->equipment_id),'revision'=>$this->revision($o->id),'assigned_to'=>$entries->where('kind','assignment')->last()?->technician_id,'state'=>$state,'entries'=>$entries->all(),'minutes_reported'=>$current->where('kind','time')->sum('minutes'),'minutes_verified'=>$current->where('kind','time')->filter(fn($e)=>$e->decision?->decision==='verified')->sum('minutes'),'materials'=>array_values($materials)];
|
||||
}
|
||||
$techs=$this->has($actor,'assign',$s)?DB::table('permission_grants as g')->join('users as u','u.id','=','g.user_id')->where(['g.company_id'=>$s['company_id'],'g.unit_id'=>$s['unit_id'],'g.permission'=>'workshop.record'])->get(['u.id','u.name'])->all():[];
|
||||
$clients=DB::table('a_clients')->where(['company_id'=>$s['company_id'],'tenant_id'=>$s['tenant_id']]);
|
||||
if(!$this->has($actor,'open',$s)) $clients->whereIn('id',array_column($orders,'client_id'));
|
||||
return ['blocked'=>false,'notice'=>self::NOTICE,'policy'=>self::POLICY,'orders'=>$orders,'clients'=>$clients->get(['id','name'])->all(),'technicians'=>$techs];
|
||||
});
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,140 @@
|
||||
<?php
|
||||
|
||||
use Illuminate\Database\Migrations\Migration;
|
||||
use Illuminate\Database\Schema\Blueprint;
|
||||
use Illuminate\Support\Facades\DB;
|
||||
use Illuminate\Support\Facades\Schema;
|
||||
|
||||
return new class extends Migration
|
||||
{
|
||||
public function up(): void
|
||||
{
|
||||
foreach (['clients', 'services', 'service_drafts', 'billing_drafts'] as $area) {
|
||||
Schema::create('a_'.$area, function (Blueprint $table) use ($area): void {
|
||||
$table->id();
|
||||
$table->unsignedBigInteger('tenant_id');
|
||||
$table->unsignedBigInteger('company_id');
|
||||
$table->unsignedBigInteger('unit_id')->nullable();
|
||||
$table->foreign(['tenant_id', 'company_id'])->references(['tenant_id', 'id'])->on('companies')->restrictOnDelete();
|
||||
$table->foreign(['tenant_id', 'company_id', 'unit_id'])->references(['tenant_id', 'company_id', 'id'])->on('units')->restrictOnDelete();
|
||||
$table->string('name');
|
||||
$table->unsignedInteger('version')->default(1);
|
||||
$table->jsonb('data');
|
||||
if (in_array($area, ['service_drafts', 'billing_drafts'], true)) {
|
||||
$table->unsignedBigInteger('client_id');
|
||||
$table->foreign(['tenant_id', 'company_id', 'client_id'])->references(['tenant_id', 'company_id', 'id'])->on('a_clients')->restrictOnDelete();
|
||||
$table->string('state')->default('draft');
|
||||
}
|
||||
if ($area === 'billing_drafts') {
|
||||
$table->unsignedBigInteger('source_id');
|
||||
$table->foreign(['tenant_id', 'company_id', 'unit_id', 'source_id'])->references(['tenant_id', 'company_id', 'unit_id', 'id'])->on('a_service_drafts')->restrictOnDelete();
|
||||
}
|
||||
$table->timestampsTz();
|
||||
$table->unique(['tenant_id', 'company_id', 'id']);
|
||||
$table->unique(['tenant_id', 'company_id', 'unit_id', 'id']);
|
||||
});
|
||||
$unitCheck = in_array($area, ['service_drafts', 'billing_drafts'], true) ? 'IS NOT NULL' : 'IS NULL';
|
||||
DB::statement("ALTER TABLE a_$area ADD CHECK (unit_id $unitCheck AND version > 0 AND jsonb_typeof(data) = 'object')");
|
||||
if (in_array($area, ['service_drafts', 'billing_drafts'], true)) { DB::statement("ALTER TABLE a_$area ADD CHECK (state = 'draft')"); }
|
||||
}
|
||||
Schema::create('a_history', function (Blueprint $table): void {
|
||||
$table->id();
|
||||
$table->unsignedBigInteger('tenant_id'); $table->unsignedBigInteger('company_id'); $table->unsignedBigInteger('unit_id')->nullable();
|
||||
$table->string('area', 30); $table->unsignedBigInteger('record_id'); $table->unsignedInteger('version');
|
||||
$table->unsignedBigInteger('actor_id'); $table->jsonb('snapshot'); $table->timestampTz('created_at')->useCurrent();
|
||||
$table->unique(['area', 'record_id', 'version']);
|
||||
$table->foreign(['tenant_id', 'company_id'])->references(['tenant_id', 'id'])->on('companies')->restrictOnDelete();
|
||||
});
|
||||
Schema::create('a_events', function (Blueprint $table): void {
|
||||
$table->id(); $table->foreignId('history_id')->unique()->constrained('a_history')->restrictOnDelete();
|
||||
$table->string('type', 80); $table->unsignedInteger('schema_version')->default(1);
|
||||
$table->jsonb('payload'); $table->timestampTz('created_at')->useCurrent();
|
||||
});
|
||||
Schema::create('a_outbox', function (Blueprint $table): void {
|
||||
$table->foreignId('event_id')->primary()->constrained('a_events')->restrictOnDelete();
|
||||
$table->string('state')->default('captured'); $table->timestampTz('created_at')->useCurrent();
|
||||
});
|
||||
DB::statement("ALTER TABLE a_outbox ADD CHECK (state = 'captured')");
|
||||
Schema::create('a_pending', function (Blueprint $table): void {
|
||||
$table->id(); $table->foreignId('history_id')->constrained('a_history')->restrictOnDelete();
|
||||
$table->string('code', 80); $table->string('message', 500); $table->timestampTz('created_at')->useCurrent();
|
||||
$table->unique(['history_id', 'code']);
|
||||
});
|
||||
Schema::create('a_commands', function (Blueprint $table): void {
|
||||
$table->id(); $table->unsignedBigInteger('tenant_id'); $table->unsignedBigInteger('company_id');
|
||||
$table->unsignedBigInteger('actor_id'); $table->string('command_key', 100); $table->string('request_hash', 64);
|
||||
$table->jsonb('result'); $table->timestampTz('created_at')->useCurrent();
|
||||
$table->unique(['tenant_id', 'company_id', 'command_key']);
|
||||
});
|
||||
DB::unprepared(<<<'SQL'
|
||||
CREATE OR REPLACE FUNCTION sgf_a_record_guard() RETURNS trigger LANGUAGE plpgsql AS $$
|
||||
DECLARE line jsonb; field text; value text;
|
||||
BEGIN
|
||||
IF TG_OP = 'INSERT' AND NEW.version <> 1 THEN RAISE EXCEPTION 'SGF_A_INITIAL_VERSION'; END IF;
|
||||
IF TG_OP = 'UPDATE' THEN
|
||||
IF NEW.id IS DISTINCT FROM OLD.id OR NEW.tenant_id IS DISTINCT FROM OLD.tenant_id OR NEW.company_id IS DISTINCT FROM OLD.company_id OR NEW.unit_id IS DISTINCT FROM OLD.unit_id THEN
|
||||
RAISE EXCEPTION 'SGF_A_IMMUTABLE_SCOPE';
|
||||
END IF;
|
||||
IF NEW.version <> OLD.version + 1 THEN RAISE EXCEPTION 'SGF_A_VERSION_REQUIRED'; END IF;
|
||||
IF TG_TABLE_NAME = 'a_billing_drafts' THEN
|
||||
IF NEW.source_id IS DISTINCT FROM OLD.source_id THEN RAISE EXCEPTION 'SGF_A_IMMUTABLE_SOURCE'; END IF;
|
||||
END IF;
|
||||
END IF;
|
||||
IF TG_TABLE_NAME IN ('a_service_drafts','a_billing_drafts') THEN
|
||||
IF (NEW.data - ARRAY['description','currency','lines','client_name','source_version','tax_status','accounting_status']) <> '{}'::jsonb THEN RAISE EXCEPTION 'SGF_A_UNSUPPORTED_DATA'; END IF;
|
||||
IF NEW.data->>'tax_status' IS DISTINCT FROM 'pending' OR NEW.data->>'accounting_status' IS DISTINCT FROM 'not_processed' THEN RAISE EXCEPTION 'SGF_A_DRAFT_ONLY'; END IF;
|
||||
IF NEW.data->>'currency' IS NOT NULL AND NEW.data->>'currency' !~ '^[A-Z]{3}$' THEN RAISE EXCEPTION 'SGF_A_CURRENCY'; END IF;
|
||||
IF jsonb_typeof(NEW.data->'lines') IS DISTINCT FROM 'array' OR jsonb_array_length(NEW.data->'lines') < 1 THEN RAISE EXCEPTION 'SGF_A_LINES'; END IF;
|
||||
FOR line IN SELECT * FROM jsonb_array_elements(NEW.data->'lines') LOOP
|
||||
IF (line - ARRAY['service_id','service_name','description','quantity','unit_price']) <> '{}'::jsonb THEN RAISE EXCEPTION 'SGF_A_UNSUPPORTED_LINE_DATA'; END IF;
|
||||
IF NOT EXISTS(SELECT 1 FROM a_services s WHERE s.id = (line->>'service_id')::bigint AND s.tenant_id = NEW.tenant_id AND s.company_id = NEW.company_id) THEN RAISE EXCEPTION 'SGF_A_FOREIGN_SERVICE'; END IF;
|
||||
FOREACH field IN ARRAY ARRAY['quantity','unit_price'] LOOP
|
||||
value := line->>field;
|
||||
IF value IS NOT NULL THEN
|
||||
IF jsonb_typeof(line->field) <> 'string' OR value !~ '^(0|[1-9][0-9]{0,15})(\.[0-9]{1,8})?$' THEN RAISE EXCEPTION 'SGF_A_DECIMAL_PRECISION'; END IF;
|
||||
IF field = 'quantity' AND value::numeric <= 0 THEN RAISE EXCEPTION 'SGF_A_QUANTITY'; END IF;
|
||||
END IF;
|
||||
END LOOP;
|
||||
END LOOP;
|
||||
END IF;
|
||||
RETURN NEW;
|
||||
END; $$;
|
||||
CREATE OR REPLACE FUNCTION sgf_a_history_guard() RETURNS trigger LANGUAGE plpgsql AS $$
|
||||
DECLARE item record; target text;
|
||||
BEGIN
|
||||
target := CASE NEW.area WHEN 'clients' THEN 'a_clients' WHEN 'services' THEN 'a_services' WHEN 'service_drafts' THEN 'a_service_drafts' WHEN 'billing_drafts' THEN 'a_billing_drafts' ELSE NULL END;
|
||||
IF target IS NULL THEN RAISE EXCEPTION 'SGF_A_AREA'; END IF;
|
||||
EXECUTE format('SELECT tenant_id,company_id,unit_id,version FROM %I WHERE id=$1', target) INTO item USING NEW.record_id;
|
||||
IF item IS NULL OR item.tenant_id IS DISTINCT FROM NEW.tenant_id OR item.company_id IS DISTINCT FROM NEW.company_id OR item.unit_id IS DISTINCT FROM NEW.unit_id OR item.version IS DISTINCT FROM NEW.version THEN RAISE EXCEPTION 'SGF_A_HISTORY_SCOPE'; END IF;
|
||||
RETURN NEW;
|
||||
END; $$;
|
||||
SQL);
|
||||
foreach (['clients', 'services', 'service_drafts', 'billing_drafts'] as $area) {
|
||||
DB::statement("CREATE TRIGGER a_{$area}_guard BEFORE INSERT OR UPDATE ON a_$area FOR EACH ROW EXECUTE FUNCTION sgf_a_record_guard()");
|
||||
}
|
||||
DB::statement('CREATE TRIGGER a_history_scope BEFORE INSERT ON a_history FOR EACH ROW EXECUTE FUNCTION sgf_a_history_guard()');
|
||||
foreach (['a_history', 'a_events', 'a_outbox', 'a_pending', 'a_commands'] as $table) {
|
||||
DB::statement("CREATE TRIGGER {$table}_append_only BEFORE UPDATE OR DELETE ON $table FOR EACH ROW EXECUTE FUNCTION sgf_append_only_audit()");
|
||||
}
|
||||
$company = ['company.view','company.edit','unit.create','access.manage']; $unit = ['unit.view','unit.edit'];
|
||||
foreach (['clients','services','service_drafts','billing_drafts'] as $area) {
|
||||
foreach (['view','create','edit','manage'] as $action) {
|
||||
if (in_array($area, ['clients','services'], true)) { $company[] = "$area.$action"; } else { $unit[] = "$area.$action"; }
|
||||
}
|
||||
}
|
||||
$companySql = "'".implode("','", $company)."'"; $unitSql = "'".implode("','", $unit)."'";
|
||||
DB::statement('ALTER TABLE permission_grants DROP CONSTRAINT permission_grants_scope_check');
|
||||
DB::statement("ALTER TABLE permission_grants ADD CONSTRAINT permission_grants_scope_check CHECK ((permission IN ($companySql) AND unit_id IS NULL) OR (permission IN ($unitSql) AND unit_id IS NOT NULL))");
|
||||
}
|
||||
|
||||
public function down(): void
|
||||
{
|
||||
if (DB::table('permission_grants')->whereNotIn('permission', ['company.view','company.edit','unit.create','access.manage','unit.view','unit.edit'])->exists()) {
|
||||
throw new RuntimeException('Remove explicit A grants through an approved procedure before rolling back.');
|
||||
}
|
||||
foreach (['a_commands','a_pending','a_outbox','a_events','a_history','a_billing_drafts','a_service_drafts','a_services','a_clients'] as $table) { Schema::dropIfExists($table); }
|
||||
DB::statement('DROP FUNCTION IF EXISTS sgf_a_record_guard()'); DB::statement('DROP FUNCTION IF EXISTS sgf_a_history_guard()');
|
||||
DB::statement('ALTER TABLE permission_grants DROP CONSTRAINT permission_grants_scope_check');
|
||||
DB::statement("ALTER TABLE permission_grants ADD CONSTRAINT permission_grants_scope_check CHECK ((permission IN ('company.view','company.edit','unit.create','access.manage') AND unit_id IS NULL) OR (permission IN ('unit.view','unit.edit') AND unit_id IS NOT NULL))");
|
||||
}
|
||||
};
|
||||
@@ -0,0 +1,61 @@
|
||||
<?php
|
||||
|
||||
use Illuminate\Database\Migrations\Migration;
|
||||
use Illuminate\Database\Schema\Blueprint;
|
||||
use Illuminate\Support\Facades\DB;
|
||||
use Illuminate\Support\Facades\Schema;
|
||||
|
||||
return new class extends Migration
|
||||
{
|
||||
public function up(): void
|
||||
{
|
||||
Schema::create('b_internal_confirmations', function (Blueprint $table): void {
|
||||
$table->id();
|
||||
$table->unsignedBigInteger('tenant_id'); $table->unsignedBigInteger('company_id'); $table->unsignedBigInteger('unit_id');
|
||||
$table->foreignId('billing_draft_id')->unique()->constrained('a_billing_drafts')->restrictOnDelete();
|
||||
$table->unsignedInteger('billing_version'); $table->unsignedInteger('version')->default(1);
|
||||
$table->foreignId('actor_id')->constrained('users')->restrictOnDelete();
|
||||
$table->jsonb('snapshot'); $table->timestampTz('created_at');
|
||||
$table->foreign(['tenant_id','company_id','unit_id','billing_draft_id'])->references(['tenant_id','company_id','unit_id','id'])->on('a_billing_drafts')->restrictOnDelete();
|
||||
});
|
||||
DB::statement('ALTER TABLE b_internal_confirmations ADD CHECK (version = 1 AND billing_version > 0 AND jsonb_typeof(snapshot) = \'object\')');
|
||||
DB::unprepared(<<<'SQL'
|
||||
CREATE OR REPLACE FUNCTION sgf_b_confirmation_guard() RETURNS trigger LANGUAGE plpgsql AS $$
|
||||
BEGIN
|
||||
PERFORM 1 FROM a_billing_drafts WHERE id = NEW.billing_draft_id AND version = NEW.billing_version FOR UPDATE;
|
||||
IF NOT FOUND THEN RAISE EXCEPTION 'SGF_B_STALE_DRAFT'; END IF;
|
||||
RETURN NEW;
|
||||
END; $$;
|
||||
CREATE OR REPLACE FUNCTION sgf_b_draft_locked() RETURNS trigger LANGUAGE plpgsql AS $$
|
||||
BEGIN
|
||||
IF EXISTS (SELECT 1 FROM b_internal_confirmations WHERE billing_draft_id = OLD.id) THEN RAISE EXCEPTION 'SGF_B_CONFIRMED_IMMUTABLE'; END IF;
|
||||
IF TG_OP = 'DELETE' THEN RETURN OLD; END IF;
|
||||
RETURN NEW;
|
||||
END; $$;
|
||||
CREATE OR REPLACE FUNCTION sgf_a_history_guard() RETURNS trigger LANGUAGE plpgsql AS $$
|
||||
DECLARE item record; target text;
|
||||
BEGIN
|
||||
target := CASE NEW.area WHEN 'clients' THEN 'a_clients' WHEN 'services' THEN 'a_services' WHEN 'service_drafts' THEN 'a_service_drafts' WHEN 'billing_drafts' THEN 'a_billing_drafts' WHEN 'internal_confirmations' THEN 'b_internal_confirmations' ELSE NULL END;
|
||||
IF target IS NULL THEN RAISE EXCEPTION 'SGF_A_AREA'; END IF;
|
||||
EXECUTE format('SELECT tenant_id,company_id,unit_id,version FROM %I WHERE id=$1', target) INTO item USING NEW.record_id;
|
||||
IF item IS NULL OR item.tenant_id IS DISTINCT FROM NEW.tenant_id OR item.company_id IS DISTINCT FROM NEW.company_id OR item.unit_id IS DISTINCT FROM NEW.unit_id OR item.version IS DISTINCT FROM NEW.version THEN RAISE EXCEPTION 'SGF_A_HISTORY_SCOPE'; END IF;
|
||||
RETURN NEW;
|
||||
END; $$;
|
||||
CREATE TRIGGER b_confirmation_valid BEFORE INSERT ON b_internal_confirmations FOR EACH ROW EXECUTE FUNCTION sgf_b_confirmation_guard();
|
||||
CREATE TRIGGER b_confirmation_immutable BEFORE UPDATE OR DELETE ON b_internal_confirmations FOR EACH ROW EXECUTE FUNCTION sgf_append_only_audit();
|
||||
CREATE TRIGGER b_billing_locked BEFORE UPDATE OR DELETE ON a_billing_drafts FOR EACH ROW EXECUTE FUNCTION sgf_b_draft_locked();
|
||||
SQL);
|
||||
$company = ['company.view','company.edit','unit.create','access.manage']; $unit = ['unit.view','unit.edit','billing_drafts.confirm_internal'];
|
||||
foreach (['clients','services','service_drafts','billing_drafts'] as $area) {
|
||||
foreach (['view','create','edit','manage'] as $action) { if (in_array($area, ['clients','services'], true)) { $company[] = "$area.$action"; } else { $unit[] = "$area.$action"; } }
|
||||
}
|
||||
$companySql = "'".implode("','", $company)."'"; $unitSql = "'".implode("','", $unit)."'";
|
||||
DB::statement('ALTER TABLE permission_grants DROP CONSTRAINT permission_grants_scope_check');
|
||||
DB::statement("ALTER TABLE permission_grants ADD CONSTRAINT permission_grants_scope_check CHECK ((permission IN ($companySql) AND unit_id IS NULL) OR (permission IN ($unitSql) AND unit_id IS NOT NULL))");
|
||||
}
|
||||
|
||||
public function down(): void
|
||||
{
|
||||
throw new RuntimeException('Internal confirmations are immutable; rollback requires a separately reviewed preservation procedure.');
|
||||
}
|
||||
};
|
||||
@@ -0,0 +1,68 @@
|
||||
<?php
|
||||
|
||||
use Illuminate\Database\Migrations\Migration;
|
||||
use Illuminate\Database\Schema\Blueprint;
|
||||
use Illuminate\Support\Facades\DB;
|
||||
use Illuminate\Support\Facades\Schema;
|
||||
|
||||
return new class extends Migration
|
||||
{
|
||||
public function up(): void
|
||||
{
|
||||
Schema::create('doc_records', function (Blueprint $table): void {
|
||||
$table->id(); $table->unsignedBigInteger('tenant_id'); $table->unsignedBigInteger('company_id'); $table->unsignedBigInteger('unit_id')->nullable();
|
||||
$table->string('kind', 30); $table->unsignedBigInteger('record_id'); $table->unsignedInteger('version'); $table->jsonb('data'); $table->timestampsTz();
|
||||
$table->foreign(['tenant_id','company_id'])->references(['tenant_id','id'])->on('companies')->restrictOnDelete();
|
||||
$table->foreign(['tenant_id','company_id','unit_id'])->references(['tenant_id','company_id','id'])->on('units')->restrictOnDelete();
|
||||
});
|
||||
DB::statement("CREATE UNIQUE INDEX doc_record_identity ON doc_records(company_id,kind,record_id) WHERE kind <> 'payment'");
|
||||
DB::statement("ALTER TABLE doc_records ADD CHECK (version > 0 AND jsonb_typeof(data) = 'object' AND ((kind IN ('issuer','client','payment') AND unit_id IS NULL) OR (kind IN ('service_drafts','billing_drafts') AND unit_id IS NOT NULL)))");
|
||||
Schema::create('doc_history', function (Blueprint $table): void {
|
||||
$table->id(); $table->foreignId('doc_record_id')->constrained('doc_records')->restrictOnDelete(); $table->unsignedInteger('version');
|
||||
$table->foreignId('actor_id')->constrained('users')->restrictOnDelete(); $table->jsonb('snapshot'); $table->timestampTz('created_at');
|
||||
$table->unique(['doc_record_id','version']);
|
||||
});
|
||||
DB::unprepared(<<<'SQL'
|
||||
CREATE OR REPLACE FUNCTION sgf_doc_guard() RETURNS trigger LANGUAGE plpgsql AS $$
|
||||
DECLARE item record; target text; instruction jsonb;
|
||||
BEGIN
|
||||
IF TG_OP = 'DELETE' THEN RAISE EXCEPTION 'SGF_DOC_NO_DELETE'; END IF;
|
||||
IF TG_OP = 'INSERT' AND NEW.version <> 1 THEN RAISE EXCEPTION 'SGF_DOC_INITIAL_VERSION'; END IF;
|
||||
IF TG_OP = 'UPDATE' THEN
|
||||
IF ROW(NEW.id,NEW.tenant_id,NEW.company_id,NEW.unit_id,NEW.kind,NEW.record_id) IS DISTINCT FROM ROW(OLD.id,OLD.tenant_id,OLD.company_id,OLD.unit_id,OLD.kind,OLD.record_id) THEN RAISE EXCEPTION 'SGF_DOC_IMMUTABLE_SCOPE'; END IF;
|
||||
IF NEW.version <> OLD.version + 1 THEN RAISE EXCEPTION 'SGF_DOC_VERSION'; END IF;
|
||||
END IF;
|
||||
IF NEW.kind = 'issuer' AND NEW.record_id <> NEW.company_id THEN RAISE EXCEPTION 'SGF_DOC_ISSUER'; END IF;
|
||||
IF NEW.kind = 'client' AND NOT EXISTS (SELECT 1 FROM a_clients WHERE id=NEW.record_id AND tenant_id=NEW.tenant_id AND company_id=NEW.company_id) THEN RAISE EXCEPTION 'SGF_DOC_CLIENT'; END IF;
|
||||
IF NEW.kind = 'payment' AND NEW.record_id <> 0 THEN RAISE EXCEPTION 'SGF_DOC_PAYMENT'; END IF;
|
||||
IF NEW.kind IN ('service_drafts','billing_drafts') THEN
|
||||
target := 'a_' || NEW.kind;
|
||||
EXECUTE format('SELECT tenant_id,company_id,unit_id,version FROM %I WHERE id=$1',target) INTO item USING NEW.record_id;
|
||||
IF item IS NULL OR ROW(item.tenant_id,item.company_id,item.unit_id) IS DISTINCT FROM ROW(NEW.tenant_id,NEW.company_id,NEW.unit_id) THEN RAISE EXCEPTION 'SGF_DOC_DRAFT_SCOPE'; END IF;
|
||||
IF NEW.kind = 'billing_drafts' AND EXISTS (SELECT 1 FROM b_internal_confirmations WHERE billing_draft_id=NEW.record_id) THEN RAISE EXCEPTION 'SGF_DOC_CONFIRMED_IMMUTABLE'; END IF;
|
||||
IF (NEW.data->>'draft_version')::integer IS DISTINCT FROM item.version THEN RAISE EXCEPTION 'SGF_DOC_STALE_DRAFT'; END IF;
|
||||
IF NEW.data->>'price_mode' NOT IN ('undefined','included','added') THEN RAISE EXCEPTION 'SGF_DOC_PRICE_MODE'; END IF;
|
||||
FOR instruction IN SELECT * FROM jsonb_array_elements(NEW.data->'payment_instruction_ids') LOOP
|
||||
IF NOT EXISTS (SELECT 1 FROM doc_records WHERE id=instruction::text::bigint AND kind='payment' AND tenant_id=NEW.tenant_id AND company_id=NEW.company_id) THEN RAISE EXCEPTION 'SGF_DOC_FOREIGN_PAYMENT'; END IF;
|
||||
END LOOP;
|
||||
END IF;
|
||||
RETURN NEW;
|
||||
END; $$;
|
||||
CREATE OR REPLACE FUNCTION sgf_doc_history_guard() RETURNS trigger LANGUAGE plpgsql AS $$
|
||||
BEGIN
|
||||
IF NOT EXISTS (SELECT 1 FROM doc_records WHERE id=NEW.doc_record_id AND version=NEW.version AND data=NEW.snapshot) THEN RAISE EXCEPTION 'SGF_DOC_HISTORY_VERSION'; END IF;
|
||||
RETURN NEW;
|
||||
END; $$;
|
||||
CREATE TRIGGER doc_record_guard BEFORE INSERT OR UPDATE OR DELETE ON doc_records FOR EACH ROW EXECUTE FUNCTION sgf_doc_guard();
|
||||
CREATE TRIGGER doc_history_guard BEFORE INSERT ON doc_history FOR EACH ROW EXECUTE FUNCTION sgf_doc_history_guard();
|
||||
CREATE TRIGGER doc_history_immutable BEFORE UPDATE OR DELETE ON doc_history FOR EACH ROW EXECUTE FUNCTION sgf_append_only_audit();
|
||||
SQL);
|
||||
$company = ['company.view','company.edit','unit.create','access.manage','issuer_documents.view','issuer_documents.edit','client_documents.view','client_documents.edit'];
|
||||
$unit = ['unit.view','unit.edit','billing_drafts.confirm_internal','draft_documents.view','draft_documents.edit'];
|
||||
foreach (['clients','services','service_drafts','billing_drafts'] as $area) { foreach (['view','create','edit','manage'] as $action) { if (in_array($area, ['clients','services'], true)) { $company[] = "$area.$action"; } else { $unit[] = "$area.$action"; } } }
|
||||
$companySql = "'".implode("','", $company)."'"; $unitSql = "'".implode("','", $unit)."'";
|
||||
DB::statement('ALTER TABLE permission_grants DROP CONSTRAINT permission_grants_scope_check');
|
||||
DB::statement("ALTER TABLE permission_grants ADD CONSTRAINT permission_grants_scope_check CHECK ((permission IN ($companySql) AND unit_id IS NULL) OR (permission IN ($unitSql) AND unit_id IS NOT NULL))");
|
||||
}
|
||||
public function down(): void { throw new RuntimeException('Document preparation contains historical data; use a separately reviewed preservation procedure.'); }
|
||||
};
|
||||
@@ -0,0 +1,49 @@
|
||||
<?php
|
||||
|
||||
use Illuminate\Database\Migrations\Migration;
|
||||
use Illuminate\Database\Schema\Blueprint;
|
||||
use Illuminate\Support\Facades\DB;
|
||||
use Illuminate\Support\Facades\Schema;
|
||||
|
||||
return new class extends Migration
|
||||
{
|
||||
public function up(): void
|
||||
{
|
||||
Schema::create('document_preview_models', function (Blueprint $table): void {
|
||||
$table->id(); $table->unsignedBigInteger('tenant_id'); $table->unsignedBigInteger('company_id')->unique();
|
||||
$table->unsignedInteger('version'); $table->jsonb('data'); $table->timestampsTz();
|
||||
$table->foreign(['tenant_id','company_id'])->references(['tenant_id','id'])->on('companies')->restrictOnDelete();
|
||||
});
|
||||
Schema::create('document_preview_model_history', function (Blueprint $table): void {
|
||||
$table->id(); $table->foreignId('model_id')->constrained('document_preview_models')->restrictOnDelete();
|
||||
$table->unsignedInteger('version'); $table->foreignId('actor_id')->constrained('users')->restrictOnDelete();
|
||||
$table->jsonb('snapshot'); $table->timestampTz('created_at'); $table->unique(['model_id','version']);
|
||||
});
|
||||
DB::unprepared(<<<'SQL'
|
||||
CREATE OR REPLACE FUNCTION sgf_preview_model_guard() RETURNS trigger LANGUAGE plpgsql AS $$
|
||||
BEGIN
|
||||
IF TG_OP = 'DELETE' THEN RAISE EXCEPTION 'SGF_PREVIEW_NO_DELETE'; END IF;
|
||||
IF TG_OP = 'INSERT' AND NEW.version <> 1 THEN RAISE EXCEPTION 'SGF_PREVIEW_INITIAL_VERSION'; END IF;
|
||||
IF TG_OP = 'UPDATE' AND (ROW(NEW.id,NEW.tenant_id,NEW.company_id) IS DISTINCT FROM ROW(OLD.id,OLD.tenant_id,OLD.company_id) OR NEW.version <> OLD.version+1) THEN RAISE EXCEPTION 'SGF_PREVIEW_IMMUTABLE_SCOPE_OR_VERSION'; END IF;
|
||||
IF jsonb_typeof(NEW.data) IS DISTINCT FROM 'object' OR (NEW.data - ARRAY['show_logo','show_contacts','show_observations','show_payment_instructions','contact_text','observations']) <> '{}'::jsonb THEN RAISE EXCEPTION 'SGF_PREVIEW_FIXED_CONTENT'; END IF;
|
||||
IF jsonb_typeof(NEW.data->'show_logo') IS DISTINCT FROM 'boolean' OR jsonb_typeof(NEW.data->'show_contacts') IS DISTINCT FROM 'boolean' OR jsonb_typeof(NEW.data->'show_observations') IS DISTINCT FROM 'boolean' OR jsonb_typeof(NEW.data->'show_payment_instructions') IS DISTINCT FROM 'boolean' THEN RAISE EXCEPTION 'SGF_PREVIEW_BOOLEAN'; END IF;
|
||||
RETURN NEW;
|
||||
END; $$;
|
||||
CREATE OR REPLACE FUNCTION sgf_preview_history_guard() RETURNS trigger LANGUAGE plpgsql AS $$
|
||||
BEGIN
|
||||
IF NOT EXISTS(SELECT 1 FROM document_preview_models WHERE id=NEW.model_id AND version=NEW.version AND data=NEW.snapshot) THEN RAISE EXCEPTION 'SGF_PREVIEW_HISTORY'; END IF;
|
||||
RETURN NEW;
|
||||
END; $$;
|
||||
CREATE TRIGGER preview_model_guard BEFORE INSERT OR UPDATE OR DELETE ON document_preview_models FOR EACH ROW EXECUTE FUNCTION sgf_preview_model_guard();
|
||||
CREATE TRIGGER preview_model_history_guard BEFORE INSERT ON document_preview_model_history FOR EACH ROW EXECUTE FUNCTION sgf_preview_history_guard();
|
||||
CREATE TRIGGER preview_model_history_immutable BEFORE UPDATE OR DELETE ON document_preview_model_history FOR EACH ROW EXECUTE FUNCTION sgf_append_only_audit();
|
||||
SQL);
|
||||
$company = ['company.view','company.edit','unit.create','access.manage','issuer_documents.view','issuer_documents.edit','client_documents.view','client_documents.edit','document_preview.configure'];
|
||||
$unit = ['unit.view','unit.edit','billing_drafts.confirm_internal','draft_documents.view','draft_documents.edit'];
|
||||
foreach (['clients','services','service_drafts','billing_drafts'] as $area) { foreach (['view','create','edit','manage'] as $action) { if (in_array($area, ['clients','services'], true)) { $company[] = "$area.$action"; } else { $unit[] = "$area.$action"; } } }
|
||||
$companySql = "'".implode("','", $company)."'"; $unitSql = "'".implode("','", $unit)."'";
|
||||
DB::statement('ALTER TABLE permission_grants DROP CONSTRAINT permission_grants_scope_check');
|
||||
DB::statement("ALTER TABLE permission_grants ADD CONSTRAINT permission_grants_scope_check CHECK ((permission IN ($companySql) AND unit_id IS NULL) OR (permission IN ($unitSql) AND unit_id IS NOT NULL))");
|
||||
}
|
||||
public function down(): void { throw new RuntimeException('Preview model history requires a separately reviewed preservation procedure.'); }
|
||||
};
|
||||
@@ -0,0 +1,40 @@
|
||||
<?php
|
||||
|
||||
use Illuminate\Database\Migrations\Migration;
|
||||
use Illuminate\Database\Schema\Blueprint;
|
||||
use Illuminate\Support\Facades\DB;
|
||||
use Illuminate\Support\Facades\Schema;
|
||||
|
||||
return new class extends Migration {
|
||||
public function up(): void
|
||||
{
|
||||
Schema::create('service_calculation_profiles', function (Blueprint $t): void {
|
||||
$t->id(); $t->unsignedBigInteger('tenant_id'); $t->unsignedBigInteger('company_id'); $t->unsignedBigInteger('unit_id');
|
||||
$t->string('identifier'); $t->unsignedInteger('version'); $t->jsonb('definition'); $t->timestampTz('created_at');
|
||||
$t->unique(['unit_id','identifier','version']);
|
||||
$t->foreign(['tenant_id','company_id','unit_id'])->references(['tenant_id','company_id','id'])->on('units')->restrictOnDelete();
|
||||
});
|
||||
Schema::create('service_calculation_results', function (Blueprint $t): void {
|
||||
$t->id(); $t->unsignedBigInteger('tenant_id'); $t->unsignedBigInteger('company_id'); $t->unsignedBigInteger('unit_id');
|
||||
$t->foreignId('billing_draft_id')->constrained('a_billing_drafts')->restrictOnDelete();
|
||||
$t->foreignId('profile_id')->constrained('service_calculation_profiles')->restrictOnDelete();
|
||||
$t->foreignId('actor_id')->constrained('users')->restrictOnDelete();
|
||||
$t->string('fingerprint', 64); $t->jsonb('snapshot'); $t->timestampTz('created_at');
|
||||
$t->unique(['billing_draft_id','fingerprint']);
|
||||
$t->foreign(['tenant_id','company_id','unit_id'])->references(['tenant_id','company_id','id'])->on('units')->restrictOnDelete();
|
||||
});
|
||||
DB::unprepared(<<<'SQL'
|
||||
CREATE OR REPLACE FUNCTION sgf_calculation_insert_guard() RETURNS trigger LANGUAGE plpgsql AS $$
|
||||
BEGIN
|
||||
IF NOT EXISTS(SELECT 1 FROM a_billing_drafts b WHERE b.id=NEW.billing_draft_id AND b.tenant_id=NEW.tenant_id AND b.company_id=NEW.company_id AND b.unit_id=NEW.unit_id)
|
||||
OR NOT EXISTS(SELECT 1 FROM service_calculation_profiles p WHERE p.id=NEW.profile_id AND p.tenant_id=NEW.tenant_id AND p.company_id=NEW.company_id AND p.unit_id=NEW.unit_id)
|
||||
THEN RAISE EXCEPTION 'SGF_CALCULATION_SCOPE'; END IF;
|
||||
RETURN NEW;
|
||||
END; $$;
|
||||
CREATE TRIGGER calculation_scope BEFORE INSERT ON service_calculation_results FOR EACH ROW EXECUTE FUNCTION sgf_calculation_insert_guard();
|
||||
CREATE TRIGGER calculation_results_immutable BEFORE UPDATE OR DELETE ON service_calculation_results FOR EACH ROW EXECUTE FUNCTION sgf_append_only_audit();
|
||||
CREATE TRIGGER calculation_profiles_immutable BEFORE UPDATE OR DELETE ON service_calculation_profiles FOR EACH ROW EXECUTE FUNCTION sgf_append_only_audit();
|
||||
SQL);
|
||||
}
|
||||
public function down(): void { throw new RuntimeException('Calculation history requires a reviewed preservation procedure.'); }
|
||||
};
|
||||
@@ -0,0 +1,96 @@
|
||||
<?php
|
||||
|
||||
use Illuminate\Database\Migrations\Migration;
|
||||
use Illuminate\Database\Schema\Blueprint;
|
||||
use Illuminate\Support\Facades\DB;
|
||||
use Illuminate\Support\Facades\Schema;
|
||||
|
||||
return new class extends Migration {
|
||||
public function up(): void
|
||||
{
|
||||
Schema::create('ca_proposals', function (Blueprint $t): void {
|
||||
$t->id(); $t->unsignedBigInteger('tenant_id'); $t->unsignedBigInteger('company_id');
|
||||
$t->string('kind',30); $t->string('entity_key',100); $t->unsignedInteger('version');
|
||||
$t->foreignId('previous_id')->nullable()->constrained('ca_proposals')->restrictOnDelete();
|
||||
$t->foreignId('replaces_id')->nullable()->constrained('ca_proposals')->restrictOnDelete();
|
||||
$t->date('valid_from'); $t->date('valid_until')->nullable(); $t->jsonb('data');
|
||||
$t->text('reason'); $t->foreignId('actor_id')->constrained('users')->restrictOnDelete(); $t->timestampTz('created_at');
|
||||
$t->unique(['company_id','kind','entity_key','version']); $t->unique(['tenant_id','company_id','id']);
|
||||
$t->foreign(['tenant_id','company_id'])->references(['tenant_id','id'])->on('companies')->restrictOnDelete();
|
||||
});
|
||||
foreach (['ca_submissions','ca_decisions'] as $table) {
|
||||
Schema::create($table,function (Blueprint $t) use ($table): void {
|
||||
$t->id(); $t->unsignedBigInteger('tenant_id'); $t->unsignedBigInteger('company_id'); $t->unsignedBigInteger('proposal_id')->unique();
|
||||
$t->foreignId('actor_id')->constrained('users')->restrictOnDelete(); $t->timestampTz('created_at');
|
||||
if ($table==='ca_decisions') { $t->string('decision',15); $t->text('reason'); }
|
||||
$t->foreign(['tenant_id','company_id','proposal_id'])->references(['tenant_id','company_id','id'])->on('ca_proposals')->restrictOnDelete();
|
||||
});
|
||||
}
|
||||
Schema::create('ca_resolutions',function (Blueprint $t): void {
|
||||
$t->id(); $t->unsignedBigInteger('tenant_id'); $t->unsignedBigInteger('company_id'); $t->unsignedBigInteger('unit_id');
|
||||
$t->string('area',30); $t->unsignedBigInteger('record_id'); $t->unsignedInteger('record_version'); $t->unsignedBigInteger('service_id');
|
||||
$t->date('reference_date'); $t->jsonb('snapshot'); $t->foreignId('actor_id')->constrained('users')->restrictOnDelete(); $t->timestampTz('created_at');
|
||||
$t->foreign(['tenant_id','company_id','unit_id'])->references(['tenant_id','company_id','id'])->on('units')->restrictOnDelete();
|
||||
$t->foreign(['tenant_id','company_id','service_id'])->references(['tenant_id','company_id','id'])->on('a_services')->restrictOnDelete();
|
||||
});
|
||||
Schema::create('ca_commands',function (Blueprint $t): void {
|
||||
$t->id(); $t->unsignedBigInteger('tenant_id'); $t->unsignedBigInteger('company_id'); $t->foreignId('actor_id')->constrained('users')->restrictOnDelete();
|
||||
$t->string('command_key',100); $t->string('request_hash',64); $t->jsonb('result'); $t->timestampTz('created_at');
|
||||
$t->unique(['company_id','command_key']);
|
||||
$t->foreign(['tenant_id','company_id'])->references(['tenant_id','id'])->on('companies')->restrictOnDelete();
|
||||
});
|
||||
DB::unprepared(<<<'SQL'
|
||||
ALTER TABLE ca_proposals ADD CHECK (kind IN ('plan','account','category','service_link','service_override'));
|
||||
ALTER TABLE ca_proposals ADD CHECK (valid_until IS NULL OR valid_until >= valid_from);
|
||||
ALTER TABLE ca_decisions ADD CHECK (decision IN ('approved','refused'));
|
||||
CREATE OR REPLACE FUNCTION sgf_ca_proposal_guard() RETURNS trigger LANGUAGE plpgsql AS $$
|
||||
DECLARE r record; ref text; keys text[];
|
||||
BEGIN
|
||||
IF NEW.previous_id IS NULL THEN
|
||||
IF NEW.version<>1 THEN RAISE EXCEPTION 'SGF_CA_INITIAL_VERSION'; END IF;
|
||||
ELSE
|
||||
SELECT * INTO r FROM ca_proposals WHERE id=NEW.previous_id;
|
||||
IF NOT FOUND OR ROW(r.tenant_id,r.company_id,r.kind,r.entity_key,r.version+1) IS DISTINCT FROM ROW(NEW.tenant_id,NEW.company_id,NEW.kind,NEW.entity_key,NEW.version) THEN RAISE EXCEPTION 'SGF_CA_PREVIOUS_SCOPE'; END IF;
|
||||
END IF;
|
||||
IF NEW.replaces_id IS NOT NULL AND NOT EXISTS(SELECT 1 FROM ca_proposals p JOIN ca_decisions d ON d.proposal_id=p.id AND d.decision='approved' WHERE p.id=NEW.replaces_id AND p.tenant_id=NEW.tenant_id AND p.company_id=NEW.company_id AND p.kind=NEW.kind AND p.entity_key=NEW.entity_key AND p.valid_from<=NEW.valid_from) THEN RAISE EXCEPTION 'SGF_CA_REPLACEMENT_SCOPE'; END IF;
|
||||
keys:=CASE NEW.kind WHEN 'plan' THEN ARRAY['plan','source_version'] WHEN 'account' THEN ARRAY['plan_id','code','name','origin','movable','evidence'] WHEN 'category' THEN ARRAY['name','account_id','conditions'] WHEN 'service_link' THEN ARRAY['service_id','category_id'] ELSE ARRAY['service_id','account_id','conditions'] END;
|
||||
IF jsonb_typeof(NEW.data) IS DISTINCT FROM 'object' OR NEW.data-keys<>'{}'::jsonb THEN RAISE EXCEPTION 'SGF_CA_UNSUPPORTED_DATA'; END IF;
|
||||
FOREACH ref IN ARRAY ARRAY['plan_id','account_id','category_id'] LOOP
|
||||
IF NEW.data ? ref AND NOT EXISTS(SELECT 1 FROM ca_proposals p WHERE p.id=(NEW.data->>ref)::bigint AND p.tenant_id=NEW.tenant_id AND p.company_id=NEW.company_id AND p.kind=CASE ref WHEN 'plan_id' THEN 'plan' WHEN 'account_id' THEN 'account' ELSE 'category' END) THEN RAISE EXCEPTION 'SGF_CA_REFERENCE_SCOPE'; END IF;
|
||||
END LOOP;
|
||||
IF NEW.data ? 'service_id' AND NOT EXISTS(SELECT 1 FROM a_services s WHERE s.id=(NEW.data->>'service_id')::bigint AND s.tenant_id=NEW.tenant_id AND s.company_id=NEW.company_id) THEN RAISE EXCEPTION 'SGF_CA_SERVICE_SCOPE'; END IF;
|
||||
IF NEW.kind IN ('service_link','service_override') AND NEW.entity_key<>'service:'||(NEW.data->>'service_id') THEN RAISE EXCEPTION 'SGF_CA_SERVICE_KEY'; END IF;
|
||||
IF NEW.kind='plan' AND (NEW.entity_key<>'PGC-NIRF' OR NEW.data->>'plan'<>'PGC-NIRF') THEN RAISE EXCEPTION 'SGF_CA_PLAN'; END IF;
|
||||
RETURN NEW;
|
||||
END; $$;
|
||||
CREATE TRIGGER ca_proposal_insert BEFORE INSERT ON ca_proposals FOR EACH ROW EXECUTE FUNCTION sgf_ca_proposal_guard();
|
||||
CREATE OR REPLACE FUNCTION sgf_ca_event_guard() RETURNS trigger LANGUAGE plpgsql AS $$
|
||||
DECLARE p record;
|
||||
BEGIN
|
||||
SELECT * INTO p FROM ca_proposals WHERE id=NEW.proposal_id AND tenant_id=NEW.tenant_id AND company_id=NEW.company_id;
|
||||
IF NOT FOUND OR EXISTS(SELECT 1 FROM ca_proposals n WHERE n.company_id=p.company_id AND n.kind=p.kind AND n.entity_key=p.entity_key AND n.version>p.version) THEN RAISE EXCEPTION 'SGF_CA_EVENT_VERSION'; END IF;
|
||||
IF TG_TABLE_NAME='ca_decisions' AND NOT EXISTS(SELECT 1 FROM ca_submissions WHERE proposal_id=p.id) THEN RAISE EXCEPTION 'SGF_CA_NOT_SUBMITTED'; END IF;
|
||||
RETURN NEW;
|
||||
END; $$;
|
||||
CREATE TRIGGER ca_submission_insert BEFORE INSERT ON ca_submissions FOR EACH ROW EXECUTE FUNCTION sgf_ca_event_guard();
|
||||
CREATE TRIGGER ca_decision_insert BEFORE INSERT ON ca_decisions FOR EACH ROW EXECUTE FUNCTION sgf_ca_event_guard();
|
||||
CREATE OR REPLACE FUNCTION sgf_ca_resolution_guard() RETURNS trigger LANGUAGE plpgsql AS $$
|
||||
BEGIN
|
||||
IF NEW.area='service_drafts' THEN
|
||||
IF NOT EXISTS(SELECT 1 FROM a_service_drafts r WHERE r.id=NEW.record_id AND r.tenant_id=NEW.tenant_id AND r.company_id=NEW.company_id AND r.unit_id=NEW.unit_id AND r.version=NEW.record_version AND EXISTS(SELECT 1 FROM jsonb_array_elements(r.data->'lines') l WHERE (l->>'service_id')::bigint=NEW.service_id)) THEN RAISE EXCEPTION 'SGF_CA_OPERATION_SCOPE'; END IF;
|
||||
ELSIF NEW.area='billing_drafts' THEN
|
||||
IF NOT EXISTS(SELECT 1 FROM a_billing_drafts r WHERE r.id=NEW.record_id AND r.tenant_id=NEW.tenant_id AND r.company_id=NEW.company_id AND r.unit_id=NEW.unit_id AND r.version=NEW.record_version AND EXISTS(SELECT 1 FROM jsonb_array_elements(r.data->'lines') l WHERE (l->>'service_id')::bigint=NEW.service_id)) THEN RAISE EXCEPTION 'SGF_CA_OPERATION_SCOPE'; END IF;
|
||||
ELSE RAISE EXCEPTION 'SGF_CA_OPERATION_KIND'; END IF;
|
||||
RETURN NEW;
|
||||
END; $$;
|
||||
CREATE TRIGGER ca_resolution_insert BEFORE INSERT ON ca_resolutions FOR EACH ROW EXECUTE FUNCTION sgf_ca_resolution_guard();
|
||||
SQL);
|
||||
foreach (['ca_proposals','ca_submissions','ca_decisions','ca_resolutions','ca_commands'] as $table) { DB::statement("CREATE TRIGGER {$table}_immutable BEFORE UPDATE OR DELETE ON $table FOR EACH ROW EXECUTE FUNCTION sgf_append_only_audit()"); }
|
||||
$company=['company.view','company.edit','unit.create','access.manage','issuer_documents.view','issuer_documents.edit','client_documents.view','client_documents.edit','document_preview.configure','catalogue_accounting.view','catalogue_accounting.propose','catalogue_accounting.approve'];
|
||||
$unit=['unit.view','unit.edit','billing_drafts.confirm_internal','draft_documents.view','draft_documents.edit'];
|
||||
foreach (['clients','services','service_drafts','billing_drafts'] as $area) { foreach (['view','create','edit','manage'] as $action) { if (in_array($area,['clients','services'],true)) { $company[]="$area.$action"; } else { $unit[]="$area.$action"; } } }
|
||||
DB::statement('ALTER TABLE permission_grants DROP CONSTRAINT permission_grants_scope_check');
|
||||
DB::statement("ALTER TABLE permission_grants ADD CONSTRAINT permission_grants_scope_check CHECK ((permission IN ('".implode("','",$company)."') AND unit_id IS NULL) OR (permission IN ('".implode("','",$unit)."') AND unit_id IS NOT NULL))");
|
||||
}
|
||||
public function down(): void { throw new RuntimeException('Accounting classification history requires a preservation procedure.'); }
|
||||
};
|
||||
@@ -0,0 +1,68 @@
|
||||
<?php
|
||||
|
||||
use Illuminate\Database\Migrations\Migration;
|
||||
use Illuminate\Database\Schema\Blueprint;
|
||||
use Illuminate\Support\Facades\DB;
|
||||
use Illuminate\Support\Facades\Schema;
|
||||
|
||||
return new class extends Migration {
|
||||
public function up(): void
|
||||
{
|
||||
$existing=DB::selectOne("SELECT pg_get_constraintdef(oid) AS definition FROM pg_constraint WHERE conrelid='permission_grants'::regclass AND conname='permission_grants_scope_check'")->definition;
|
||||
$expression=substr($existing,6); // retain every existing permission/scope branch
|
||||
DB::statement('ALTER TABLE permission_grants DROP CONSTRAINT permission_grants_scope_check');
|
||||
DB::statement("ALTER TABLE permission_grants ADD CONSTRAINT permission_grants_scope_check CHECK (($expression) OR (permission IN ('service_fiscal.view','service_fiscal.propose','service_fiscal.approve') AND unit_id IS NULL) OR (permission='service_fiscal.calculate' AND unit_id IS NOT NULL))");
|
||||
Schema::create('sf_proposals', function (Blueprint $t) {
|
||||
$t->id(); $t->unsignedBigInteger('tenant_id'); $t->unsignedBigInteger('company_id'); $t->unsignedBigInteger('unit_id');
|
||||
$t->string('kind'); $t->string('identifier'); $t->unsignedInteger('version');
|
||||
$t->foreignId('profile_id')->constrained('service_calculation_profiles')->restrictOnDelete();
|
||||
$t->foreignId('draft_id')->nullable()->constrained('a_billing_drafts')->restrictOnDelete();
|
||||
$t->foreignId('previous_id')->nullable()->constrained('sf_proposals')->restrictOnDelete();
|
||||
$t->foreignId('actor_id')->constrained('users'); $t->jsonb('data'); $t->timestampTz('created_at');
|
||||
$t->unique(['unit_id','kind','identifier','version']);
|
||||
$t->foreign(['tenant_id','company_id','unit_id'])->references(['tenant_id','company_id','id'])->on('units')->restrictOnDelete();
|
||||
});
|
||||
Schema::create('sf_decisions', function (Blueprint $t) {
|
||||
$t->id(); $t->foreignId('proposal_id')->unique()->constrained('sf_proposals')->restrictOnDelete();
|
||||
$t->foreignId('actor_id')->constrained('users'); $t->string('decision'); $t->text('reason'); $t->timestampTz('created_at');
|
||||
});
|
||||
Schema::create('sf_activation_events', function (Blueprint $t) {
|
||||
$t->id(); $t->foreignId('proposal_id')->constrained('sf_proposals')->restrictOnDelete();
|
||||
$t->foreignId('actor_id')->constrained('users'); $t->boolean('active'); $t->text('reason'); $t->timestampTz('created_at');
|
||||
});
|
||||
DB::unprepared(<<<'SQL'
|
||||
CREATE OR REPLACE FUNCTION sgf_fiscal_proposal_guard() RETURNS trigger LANGUAGE plpgsql AS $$
|
||||
BEGIN
|
||||
IF NEW.kind NOT IN ('profile','temporal') OR NOT EXISTS(
|
||||
SELECT 1 FROM service_calculation_profiles p WHERE p.id=NEW.profile_id AND p.tenant_id=NEW.tenant_id AND p.company_id=NEW.company_id AND p.unit_id=NEW.unit_id
|
||||
) OR (NEW.kind='profile' AND NEW.draft_id IS NOT NULL) OR (NEW.kind='temporal' AND NEW.draft_id IS NULL)
|
||||
OR (NEW.draft_id IS NOT NULL AND NOT EXISTS(SELECT 1 FROM a_billing_drafts b WHERE b.id=NEW.draft_id AND b.tenant_id=NEW.tenant_id AND b.company_id=NEW.company_id AND b.unit_id=NEW.unit_id))
|
||||
OR (NEW.previous_id IS NOT NULL AND NOT EXISTS(SELECT 1 FROM sf_proposals p WHERE p.id=NEW.previous_id AND p.tenant_id=NEW.tenant_id AND p.company_id=NEW.company_id AND p.unit_id=NEW.unit_id AND p.kind=NEW.kind AND p.identifier=NEW.identifier AND p.version=NEW.version-1))
|
||||
THEN RAISE EXCEPTION 'SGF_FISCAL_SCOPE'; END IF;
|
||||
IF NEW.previous_id IS NULL AND NEW.version<>1 THEN RAISE EXCEPTION 'SGF_FISCAL_INITIAL_VERSION'; END IF;
|
||||
IF NEW.kind='profile' AND NOT EXISTS(SELECT 1 FROM a_services s WHERE s.id=(NEW.data->>'service_id')::bigint AND s.tenant_id=NEW.tenant_id AND s.company_id=NEW.company_id)
|
||||
THEN RAISE EXCEPTION 'SGF_FISCAL_SERVICE_SCOPE'; END IF;
|
||||
RETURN NEW;
|
||||
END; $$;
|
||||
CREATE TRIGGER fiscal_proposal_scope BEFORE INSERT ON sf_proposals FOR EACH ROW EXECUTE FUNCTION sgf_fiscal_proposal_guard();
|
||||
CREATE OR REPLACE FUNCTION sgf_fiscal_decision_guard() RETURNS trigger LANGUAGE plpgsql AS $$
|
||||
BEGIN
|
||||
IF NEW.decision NOT IN ('approved','refused') OR EXISTS(SELECT 1 FROM sf_proposals WHERE id=NEW.proposal_id AND actor_id=NEW.actor_id)
|
||||
THEN RAISE EXCEPTION 'SGF_FISCAL_DECISION'; END IF;
|
||||
RETURN NEW;
|
||||
END; $$;
|
||||
CREATE TRIGGER fiscal_decision_guard BEFORE INSERT ON sf_decisions FOR EACH ROW EXECUTE FUNCTION sgf_fiscal_decision_guard();
|
||||
CREATE OR REPLACE FUNCTION sgf_fiscal_activation_guard() RETURNS trigger LANGUAGE plpgsql AS $$
|
||||
BEGIN
|
||||
IF NOT EXISTS(SELECT 1 FROM sf_proposals p JOIN sf_decisions d ON d.proposal_id=p.id AND d.decision='approved' WHERE p.id=NEW.proposal_id AND p.kind='profile')
|
||||
THEN RAISE EXCEPTION 'SGF_FISCAL_ACTIVATION'; END IF;
|
||||
RETURN NEW;
|
||||
END; $$;
|
||||
CREATE TRIGGER fiscal_activation_guard BEFORE INSERT ON sf_activation_events FOR EACH ROW EXECUTE FUNCTION sgf_fiscal_activation_guard();
|
||||
SQL);
|
||||
foreach (['sf_proposals','sf_decisions','sf_activation_events'] as $table) {
|
||||
DB::unprepared("CREATE TRIGGER {$table}_immutable BEFORE UPDATE OR DELETE ON {$table} FOR EACH ROW EXECUTE FUNCTION sgf_append_only_audit()");
|
||||
}
|
||||
}
|
||||
public function down(): void { throw new RuntimeException('Fiscal history requires a reviewed preservation procedure.'); }
|
||||
};
|
||||
@@ -0,0 +1,89 @@
|
||||
<?php
|
||||
use Illuminate\Database\Migrations\Migration;
|
||||
use Illuminate\Database\Schema\Blueprint;
|
||||
use Illuminate\Support\Facades\DB;
|
||||
use Illuminate\Support\Facades\Schema;
|
||||
|
||||
return new class extends Migration {
|
||||
public function up(): void
|
||||
{
|
||||
$old=substr(DB::selectOne("SELECT pg_get_constraintdef(oid) AS d FROM pg_constraint WHERE conrelid='permission_grants'::regclass AND conname='permission_grants_scope_check'")->d,6);
|
||||
DB::statement('ALTER TABLE permission_grants DROP CONSTRAINT permission_grants_scope_check');
|
||||
DB::statement("ALTER TABLE permission_grants ADD CONSTRAINT permission_grants_scope_check CHECK (($old) OR (permission IN ('invoice_series.view','invoice_series.propose','invoice_series.approve') AND unit_id IS NULL) OR (permission IN ('service_invoices.view','service_invoices.issue','service_invoices.correction_request') AND unit_id IS NOT NULL))");
|
||||
Schema::create('si_proposals',function(Blueprint $t) {
|
||||
$t->id(); $t->unsignedBigInteger('tenant_id'); $t->unsignedBigInteger('company_id'); $t->unsignedBigInteger('unit_id');
|
||||
$t->string('kind'); $t->string('identifier'); $t->unsignedInteger('version'); $t->jsonb('data');
|
||||
$t->foreignId('previous_id')->nullable()->constrained('si_proposals'); $t->foreignId('actor_id')->constrained('users'); $t->timestampTz('created_at');
|
||||
$t->unique(['company_id','kind','identifier','version']);
|
||||
$t->foreign(['tenant_id','company_id','unit_id'])->references(['tenant_id','company_id','id'])->on('units');
|
||||
});
|
||||
Schema::create('si_decisions',function(Blueprint $t) {
|
||||
$t->id(); $t->foreignId('proposal_id')->unique()->constrained('si_proposals'); $t->foreignId('actor_id')->constrained('users'); $t->string('decision'); $t->text('reason'); $t->timestampTz('created_at');
|
||||
});
|
||||
Schema::create('si_counters',function(Blueprint $t) {
|
||||
$t->id(); $t->unsignedBigInteger('tenant_id'); $t->unsignedBigInteger('company_id'); $t->unsignedBigInteger('unit_id'); $t->string('code'); $t->unsignedBigInteger('last_number');
|
||||
$t->unique(['company_id','code']);
|
||||
$t->foreign(['tenant_id','company_id','unit_id'])->references(['tenant_id','company_id','id'])->on('units');
|
||||
});
|
||||
Schema::create('si_invoices',function(Blueprint $t) {
|
||||
$t->id(); $t->unsignedBigInteger('tenant_id'); $t->unsignedBigInteger('company_id'); $t->unsignedBigInteger('unit_id');
|
||||
$t->foreignId('draft_id')->unique()->constrained('a_billing_drafts'); $t->foreignId('source_id')->unique()->constrained('a_service_drafts');
|
||||
$t->foreignId('series_id')->constrained('si_proposals'); $t->foreignId('rule_id')->constrained('si_proposals');
|
||||
$t->string('series_code'); $t->unsignedBigInteger('number'); $t->jsonb('snapshot'); $t->text('pdf_base64'); $t->string('pdf_sha256',64);
|
||||
$t->foreignId('actor_id')->constrained('users'); $t->timestampTz('issued_at');
|
||||
$t->unique(['company_id','series_code','number']);
|
||||
$t->foreign(['tenant_id','company_id','unit_id'])->references(['tenant_id','company_id','id'])->on('units');
|
||||
});
|
||||
Schema::create('si_events',function(Blueprint $t) {
|
||||
$t->id(); $t->foreignId('invoice_id')->unique()->constrained('si_invoices'); $t->string('type'); $t->jsonb('payload'); $t->timestampTz('created_at');
|
||||
});
|
||||
Schema::create('si_outbox',function(Blueprint $t) {
|
||||
$t->foreignId('event_id')->primary()->constrained('si_events'); $t->string('state')->default('captured_no_processing');
|
||||
});
|
||||
Schema::create('si_commands',function(Blueprint $t) {
|
||||
$t->id(); $t->unsignedBigInteger('tenant_id'); $t->unsignedBigInteger('company_id'); $t->unsignedBigInteger('unit_id');
|
||||
$t->foreignId('actor_id')->constrained('users'); $t->string('command_key',100); $t->string('request_hash',64); $t->jsonb('result'); $t->timestampTz('created_at');
|
||||
$t->unique(['company_id','command_key']);
|
||||
$t->foreign(['tenant_id','company_id','unit_id'])->references(['tenant_id','company_id','id'])->on('units');
|
||||
});
|
||||
Schema::create('si_correction_requests',function(Blueprint $t) {
|
||||
$t->id(); $t->foreignId('invoice_id')->constrained('si_invoices'); $t->foreignId('actor_id')->constrained('users'); $t->text('reason'); $t->timestampTz('created_at');
|
||||
});
|
||||
DB::unprepared(<<<'SQL'
|
||||
CREATE OR REPLACE FUNCTION sgf_si_proposal_guard() RETURNS trigger LANGUAGE plpgsql AS $$
|
||||
BEGIN
|
||||
IF NEW.kind NOT IN ('series','temporal') OR (NEW.previous_id IS NULL AND NEW.version<>1)
|
||||
OR (NEW.previous_id IS NOT NULL AND NOT EXISTS(SELECT 1 FROM si_proposals p WHERE p.id=NEW.previous_id AND p.tenant_id=NEW.tenant_id AND p.company_id=NEW.company_id AND p.unit_id=NEW.unit_id AND p.kind=NEW.kind AND p.identifier=NEW.identifier AND p.version=NEW.version-1)) THEN RAISE EXCEPTION 'SGF_SI_PROPOSAL_SCOPE'; END IF;
|
||||
IF NEW.kind='temporal' AND NOT EXISTS(SELECT 1 FROM a_billing_drafts b WHERE b.id=(NEW.data->>'draft_id')::bigint AND b.tenant_id=NEW.tenant_id AND b.company_id=NEW.company_id AND b.unit_id=NEW.unit_id) THEN RAISE EXCEPTION 'SGF_SI_DRAFT_SCOPE'; END IF;
|
||||
RETURN NEW;
|
||||
END; $$;
|
||||
CREATE TRIGGER si_proposal_guard BEFORE INSERT ON si_proposals FOR EACH ROW EXECUTE FUNCTION sgf_si_proposal_guard();
|
||||
CREATE OR REPLACE FUNCTION sgf_si_decision_guard() RETURNS trigger LANGUAGE plpgsql AS $$
|
||||
BEGIN
|
||||
IF NEW.decision NOT IN ('approved','refused') OR EXISTS(SELECT 1 FROM si_proposals WHERE id=NEW.proposal_id AND actor_id=NEW.actor_id) THEN RAISE EXCEPTION 'SGF_SI_SELF_DECISION'; END IF;
|
||||
RETURN NEW;
|
||||
END; $$;
|
||||
CREATE TRIGGER si_decision_guard BEFORE INSERT ON si_decisions FOR EACH ROW EXECUTE FUNCTION sgf_si_decision_guard();
|
||||
CREATE OR REPLACE FUNCTION sgf_si_counter_guard() RETURNS trigger LANGUAGE plpgsql AS $$
|
||||
BEGIN
|
||||
IF TG_OP='DELETE' THEN RAISE EXCEPTION 'SGF_SI_COUNTER_DELETE'; END IF;
|
||||
IF ROW(NEW.tenant_id,NEW.company_id,NEW.unit_id,NEW.code,NEW.id) IS DISTINCT FROM ROW(OLD.tenant_id,OLD.company_id,OLD.unit_id,OLD.code,OLD.id) OR NEW.last_number<>OLD.last_number+1 THEN RAISE EXCEPTION 'SGF_SI_COUNTER_CHANGE'; END IF;
|
||||
RETURN NEW;
|
||||
END; $$;
|
||||
CREATE TRIGGER si_counter_guard BEFORE UPDATE OR DELETE ON si_counters FOR EACH ROW EXECUTE FUNCTION sgf_si_counter_guard();
|
||||
CREATE OR REPLACE FUNCTION sgf_si_invoice_guard() RETURNS trigger LANGUAGE plpgsql AS $$
|
||||
BEGIN
|
||||
IF NOT EXISTS(SELECT 1 FROM a_billing_drafts b WHERE b.id=NEW.draft_id AND b.source_id=NEW.source_id AND b.tenant_id=NEW.tenant_id AND b.company_id=NEW.company_id AND b.unit_id=NEW.unit_id)
|
||||
OR NOT EXISTS(SELECT 1 FROM si_proposals p JOIN si_decisions d ON d.proposal_id=p.id AND d.decision='approved' WHERE p.id=NEW.series_id AND p.kind='series' AND p.tenant_id=NEW.tenant_id AND p.company_id=NEW.company_id AND p.unit_id=NEW.unit_id AND p.data->>'code'=NEW.series_code)
|
||||
OR NOT EXISTS(SELECT 1 FROM si_proposals p JOIN si_decisions d ON d.proposal_id=p.id AND d.decision='approved' WHERE p.id=NEW.rule_id AND p.kind='temporal' AND p.tenant_id=NEW.tenant_id AND p.company_id=NEW.company_id AND p.unit_id=NEW.unit_id AND (p.data->>'draft_id')::bigint=NEW.draft_id)
|
||||
OR NOT EXISTS(SELECT 1 FROM si_counters c WHERE c.tenant_id=NEW.tenant_id AND c.company_id=NEW.company_id AND c.unit_id=NEW.unit_id AND c.code=NEW.series_code AND c.last_number=NEW.number)
|
||||
OR NEW.snapshot->>'notice' IS DISTINCT FROM 'TESTE — SEM VALIDADE FISCAL'
|
||||
THEN RAISE EXCEPTION 'SGF_SI_INVOICE_SCOPE'; END IF;
|
||||
RETURN NEW;
|
||||
END; $$;
|
||||
CREATE TRIGGER si_invoice_guard BEFORE INSERT ON si_invoices FOR EACH ROW EXECUTE FUNCTION sgf_si_invoice_guard();
|
||||
SQL);
|
||||
foreach(['si_proposals','si_decisions','si_invoices','si_events','si_outbox','si_commands','si_correction_requests'] as $table) DB::statement("CREATE TRIGGER {$table}_immutable BEFORE UPDATE OR DELETE ON {$table} FOR EACH ROW EXECUTE FUNCTION sgf_append_only_audit()");
|
||||
}
|
||||
public function down(): void { throw new RuntimeException('Document history requires a reviewed preservation procedure.'); }
|
||||
};
|
||||
@@ -0,0 +1,18 @@
|
||||
<?php
|
||||
use Illuminate\Database\Migrations\Migration;
|
||||
use Illuminate\Support\Facades\DB;
|
||||
|
||||
return new class extends Migration {
|
||||
public function up(): void
|
||||
{
|
||||
$old=substr(DB::selectOne("SELECT pg_get_constraintdef(oid) AS d FROM pg_constraint WHERE conrelid='permission_grants'::regclass AND conname='permission_grants_scope_check'")->d,6);
|
||||
DB::statement('ALTER TABLE permission_grants DROP CONSTRAINT permission_grants_scope_check');
|
||||
DB::statement("ALTER TABLE permission_grants ADD CONSTRAINT permission_grants_scope_check CHECK (($old) OR (permission IN ('service_receivables.view','service_receivables.prepare','service_receivables.confirm','service_receivables.allocate','service_receivables.reconcile','service_receivables.correction_request','service_receivables.correction_approve') AND unit_id IS NOT NULL))");
|
||||
DB::unprepared(file_get_contents(__DIR__.'/../sql/receivables.sql'));
|
||||
foreach (['sr_records','sr_effects','sr_commands','sr_events','sr_outbox','sr_deliveries'] as $table) {
|
||||
DB::statement("CREATE TRIGGER {$table}_immutable BEFORE UPDATE OR DELETE ON {$table} FOR EACH ROW EXECUTE FUNCTION sgf_append_only_audit()");
|
||||
DB::statement("CREATE TRIGGER {$table}_test_only BEFORE INSERT ON {$table} FOR EACH ROW EXECUTE FUNCTION sgf_sr_test_insert()");
|
||||
}
|
||||
}
|
||||
public function down(): void { throw new RuntimeException('Immutable history requires a reviewed preservation procedure.'); }
|
||||
};
|
||||
@@ -0,0 +1,18 @@
|
||||
<?php
|
||||
use Illuminate\Database\Migrations\Migration;
|
||||
use Illuminate\Support\Facades\DB;
|
||||
|
||||
return new class extends Migration {
|
||||
public function up(): void
|
||||
{
|
||||
$old=substr(DB::selectOne("SELECT pg_get_constraintdef(oid) AS d FROM pg_constraint WHERE conrelid='permission_grants'::regclass AND conname='permission_grants_scope_check'")->d,6);
|
||||
DB::statement('ALTER TABLE permission_grants DROP CONSTRAINT permission_grants_scope_check');
|
||||
DB::statement("ALTER TABLE permission_grants ADD CONSTRAINT permission_grants_scope_check CHECK (($old) OR (permission IN ('workshop.view','workshop.open','workshop.assign','workshop.authorize','workshop.record','workshop.verify') AND unit_id IS NOT NULL))");
|
||||
DB::unprepared(file_get_contents(__DIR__.'/../sql/workshop.sql'));
|
||||
foreach(['wo_equipment','wo_orders','wo_entries','wo_decisions','wo_commands','wo_events','wo_outbox'] as $table) {
|
||||
DB::statement("CREATE TRIGGER {$table}_immutable BEFORE UPDATE OR DELETE ON {$table} FOR EACH ROW EXECUTE FUNCTION sgf_append_only_audit()");
|
||||
DB::statement("CREATE TRIGGER {$table}_test_only BEFORE INSERT ON {$table} FOR EACH ROW EXECUTE FUNCTION sgf_wo_test_only()");
|
||||
}
|
||||
}
|
||||
public function down(): void { throw new RuntimeException('Workshop history requires a reviewed preservation procedure.'); }
|
||||
};
|
||||
@@ -0,0 +1,16 @@
|
||||
<?php
|
||||
use Illuminate\Database\Migrations\Migration;
|
||||
use Illuminate\Support\Facades\DB;
|
||||
return new class extends Migration {
|
||||
public function up(): void {
|
||||
$old=substr(DB::selectOne("SELECT pg_get_constraintdef(oid) AS d FROM pg_constraint WHERE conrelid='permission_grants'::regclass AND conname='permission_grants_scope_check'")->d,6);
|
||||
DB::statement('ALTER TABLE permission_grants DROP CONSTRAINT permission_grants_scope_check');
|
||||
DB::statement("ALTER TABLE permission_grants ADD CONSTRAINT permission_grants_scope_check CHECK (($old) OR (permission IN ('direct_costs.view','direct_costs.prepare','direct_costs.validate') AND unit_id IS NOT NULL))");
|
||||
DB::unprepared(file_get_contents(__DIR__.'/../sql/direct-costs.sql'));
|
||||
foreach(['dc_rates','dc_calculations','dc_decisions','dc_commands','dc_events','dc_outbox'] as $t){
|
||||
DB::statement("CREATE TRIGGER {$t}_immutable BEFORE UPDATE OR DELETE ON {$t} FOR EACH ROW EXECUTE FUNCTION sgf_append_only_audit()");
|
||||
DB::statement("CREATE TRIGGER {$t}_test_only BEFORE INSERT ON {$t} FOR EACH ROW EXECUTE FUNCTION sgf_dc_test_only()");
|
||||
}
|
||||
}
|
||||
public function down(): void {throw new RuntimeException('Direct cost history requires a reviewed preservation procedure.');}
|
||||
};
|
||||
@@ -0,0 +1,103 @@
|
||||
CREATE TABLE dc_rates (
|
||||
id bigserial PRIMARY KEY, tenant_id bigint NOT NULL, company_id bigint NOT NULL, unit_id bigint NOT NULL,
|
||||
order_id bigint NOT NULL REFERENCES wo_orders(id), entry_id bigint NOT NULL REFERENCES wo_entries(id), entry_version integer NOT NULL,
|
||||
identifier text NOT NULL, version integer NOT NULL CHECK(version>0), previous_id bigint UNIQUE REFERENCES dc_rates(id),
|
||||
currency text NOT NULL CHECK(currency='MZN'), unit text NOT NULL CHECK(unit IN ('UN','KG','M','L','H')),
|
||||
amount numeric NOT NULL CHECK(amount>=0 AND amount<10000000000000000 AND amount=trunc(amount,8)), evidence text NOT NULL CHECK(length(evidence)>=3),
|
||||
actor_id bigint NOT NULL REFERENCES users(id), created_at timestamptz NOT NULL,
|
||||
UNIQUE(order_id,identifier,version), FOREIGN KEY(tenant_id,company_id,unit_id) REFERENCES units(tenant_id,company_id,id)
|
||||
);
|
||||
CREATE TABLE dc_calculations (
|
||||
id bigserial PRIMARY KEY, tenant_id bigint NOT NULL, company_id bigint NOT NULL, unit_id bigint NOT NULL,
|
||||
order_id bigint NOT NULL REFERENCES wo_orders(id), version integer NOT NULL CHECK(version>0), previous_id bigint UNIQUE REFERENCES dc_calculations(id),
|
||||
fingerprint text NOT NULL, snapshot jsonb NOT NULL, actor_id bigint NOT NULL REFERENCES users(id), created_at timestamptz NOT NULL,
|
||||
UNIQUE(order_id,version), FOREIGN KEY(tenant_id,company_id,unit_id) REFERENCES units(tenant_id,company_id,id)
|
||||
);
|
||||
CREATE TABLE dc_decisions (
|
||||
id bigserial PRIMARY KEY, rate_id bigint UNIQUE REFERENCES dc_rates(id), calculation_id bigint UNIQUE REFERENCES dc_calculations(id),
|
||||
version integer NOT NULL CHECK(version>0), decision text NOT NULL CHECK(decision IN ('approved','refused')), reason text NOT NULL CHECK(length(reason)>=3),
|
||||
actor_id bigint NOT NULL REFERENCES users(id), created_at timestamptz NOT NULL,
|
||||
CHECK(num_nonnulls(rate_id,calculation_id)=1)
|
||||
);
|
||||
CREATE TABLE dc_commands (
|
||||
id bigserial PRIMARY KEY, tenant_id bigint NOT NULL, company_id bigint NOT NULL, unit_id bigint NOT NULL,
|
||||
order_id bigint NOT NULL REFERENCES wo_orders(id), actor_id bigint NOT NULL REFERENCES users(id), action text NOT NULL CHECK(action IN ('rate','calculate','decide')),
|
||||
command_key text NOT NULL, request_hash text NOT NULL, result jsonb NOT NULL, created_at timestamptz NOT NULL,
|
||||
UNIQUE(company_id,unit_id,actor_id,action,command_key), FOREIGN KEY(tenant_id,company_id,unit_id) REFERENCES units(tenant_id,company_id,id)
|
||||
);
|
||||
CREATE TABLE dc_events (id bigserial PRIMARY KEY, command_id bigint NOT NULL UNIQUE REFERENCES dc_commands(id), schema_version integer NOT NULL CHECK(schema_version=1), payload jsonb NOT NULL, created_at timestamptz NOT NULL);
|
||||
CREATE TABLE dc_outbox (event_id bigint PRIMARY KEY REFERENCES dc_events(id), state text NOT NULL CHECK(state='captured_no_accounting'));
|
||||
CREATE OR REPLACE FUNCTION sgf_dc_environment() RETURNS void LANGUAGE plpgsql AS $$
|
||||
BEGIN IF current_database() IS DISTINCT FROM 'sgf_tempo_test' OR inet_server_port() IS DISTINCT FROM 55432 THEN RAISE EXCEPTION 'SGF_DC_TEST_DATABASE_ONLY'; END IF; END; $$;
|
||||
CREATE OR REPLACE FUNCTION sgf_dc_test_only() RETURNS trigger LANGUAGE plpgsql AS $$
|
||||
BEGIN PERFORM sgf_dc_environment(); RETURN NEW; END; $$;
|
||||
CREATE OR REPLACE FUNCTION sgf_dc_source(eid bigint, oid bigint, ev integer) RETURNS void LANGUAGE plpgsql AS $$
|
||||
DECLARE e wo_entries; d wo_decisions;
|
||||
BEGIN
|
||||
SELECT * INTO STRICT e FROM wo_entries WHERE id=eid AND order_id=oid AND version=ev;
|
||||
SELECT * INTO STRICT d FROM wo_decisions WHERE entry_id=e.id AND entry_version=e.version AND decision='verified';
|
||||
IF EXISTS(SELECT 1 FROM wo_entries WHERE previous_id=e.id) OR e.outside_authority
|
||||
OR NOT ((e.kind='time' AND e.data->>'time_type'='work') OR (e.kind='material' AND e.data->>'event'='consumed' AND e.data->>'owner'='company'))
|
||||
OR EXISTS(SELECT 1 FROM wo_entries WHERE previous_id=e.task_id) THEN RAISE EXCEPTION 'SGF_DC_INELIGIBLE_SOURCE'; END IF;
|
||||
EXCEPTION WHEN NO_DATA_FOUND THEN RAISE EXCEPTION 'SGF_DC_UNVERIFIED_SOURCE'; END; $$;
|
||||
CREATE OR REPLACE FUNCTION sgf_dc_guard() RETURNS trigger LANGUAGE plpgsql AS $$
|
||||
DECLARE o wo_orders; e wo_entries; p record; target record; line jsonb; r dc_rates; latest integer;
|
||||
BEGIN
|
||||
PERFORM sgf_dc_environment();
|
||||
IF TG_TABLE_NAME='dc_decisions' THEN
|
||||
IF NEW.rate_id IS NOT NULL THEN SELECT order_id INTO STRICT latest FROM dc_rates WHERE id=NEW.rate_id;
|
||||
ELSE SELECT order_id INTO STRICT latest FROM dc_calculations WHERE id=NEW.calculation_id; END IF;
|
||||
SELECT * INTO STRICT o FROM wo_orders WHERE id=latest; PERFORM 1 FROM companies WHERE id=o.company_id FOR UPDATE;
|
||||
IF NEW.rate_id IS NOT NULL THEN
|
||||
SELECT id,actor_id,version,order_id INTO STRICT target FROM dc_rates WHERE id=NEW.rate_id;
|
||||
IF EXISTS(SELECT 1 FROM dc_rates WHERE previous_id=target.id) THEN RAISE EXCEPTION 'SGF_DC_OLD_RATE'; END IF;
|
||||
SELECT * INTO r FROM dc_rates WHERE id=target.id; PERFORM sgf_dc_source(r.entry_id,r.order_id,r.entry_version);
|
||||
ELSE
|
||||
SELECT id,actor_id,version,order_id INTO STRICT target FROM dc_calculations WHERE id=NEW.calculation_id;
|
||||
IF EXISTS(SELECT 1 FROM dc_calculations WHERE previous_id=target.id) THEN RAISE EXCEPTION 'SGF_DC_OLD_CALCULATION'; END IF;
|
||||
FOR line IN SELECT * FROM jsonb_array_elements((SELECT snapshot->'lines' FROM dc_calculations WHERE id=target.id)) LOOP
|
||||
PERFORM sgf_dc_source((line->>'entry_id')::bigint,target.order_id,(line->>'entry_version')::integer);
|
||||
IF line->>'rate_id' IS NOT NULL THEN
|
||||
SELECT * INTO STRICT r FROM dc_rates WHERE id=(line->>'rate_id')::bigint;
|
||||
IF EXISTS(SELECT 1 FROM dc_rates WHERE previous_id=r.id) OR NOT EXISTS(SELECT 1 FROM dc_decisions WHERE rate_id=r.id AND decision='approved') THEN RAISE EXCEPTION 'SGF_DC_OLD_RATE'; END IF;
|
||||
END IF;
|
||||
END LOOP;
|
||||
END IF;
|
||||
SELECT * INTO STRICT o FROM wo_orders WHERE id=target.order_id; PERFORM 1 FROM companies WHERE id=o.company_id FOR UPDATE;
|
||||
IF target.actor_id=NEW.actor_id OR target.version<>NEW.version THEN RAISE EXCEPTION 'SGF_DC_SEPARATION_OR_VERSION'; END IF;
|
||||
RETURN NEW;
|
||||
END IF;
|
||||
SELECT * INTO STRICT o FROM wo_orders WHERE id=NEW.order_id; PERFORM 1 FROM companies WHERE id=o.company_id FOR UPDATE;
|
||||
IF ROW(NEW.tenant_id,NEW.company_id,NEW.unit_id) IS DISTINCT FROM ROW(o.tenant_id,o.company_id,o.unit_id) THEN RAISE EXCEPTION 'SGF_DC_SCOPE'; END IF;
|
||||
IF TG_TABLE_NAME='dc_commands' THEN RETURN NEW; END IF;
|
||||
IF TG_TABLE_NAME='dc_rates' THEN
|
||||
PERFORM sgf_dc_source(NEW.entry_id,NEW.order_id,NEW.entry_version);
|
||||
SELECT * INTO STRICT e FROM wo_entries WHERE id=NEW.entry_id;
|
||||
IF (e.kind='time' AND NEW.unit<>'H') OR (e.kind='material' AND NEW.unit IS DISTINCT FROM e.data->>'unit') THEN RAISE EXCEPTION 'SGF_DC_UNIT'; END IF;
|
||||
SELECT coalesce(max(version),0) INTO latest FROM dc_rates WHERE order_id=o.id AND identifier=NEW.identifier;
|
||||
IF NEW.version<>latest+1 THEN RAISE EXCEPTION 'SGF_DC_VERSION'; END IF;
|
||||
IF latest=0 THEN IF NEW.previous_id IS NOT NULL THEN RAISE EXCEPTION 'SGF_DC_PREVIOUS'; END IF;
|
||||
ELSE
|
||||
SELECT * INTO STRICT p FROM dc_rates WHERE id=NEW.previous_id AND order_id=o.id AND identifier=NEW.identifier AND version=latest;
|
||||
IF NOT EXISTS(SELECT 1 FROM wo_entries pe WHERE pe.id=p.entry_id AND pe.origin=e.origin AND pe.kind=e.kind) THEN RAISE EXCEPTION 'SGF_DC_SOURCE_TRANSFER'; END IF;
|
||||
END IF;
|
||||
ELSE
|
||||
SELECT coalesce(max(version),0) INTO latest FROM dc_calculations WHERE order_id=o.id;
|
||||
IF NEW.version<>latest+1 OR NEW.snapshot->>'policy' IS DISTINCT FROM 'WORKSHOP-DIRECT-COST-SIM-v1' OR NEW.snapshot->>'currency' IS DISTINCT FROM 'MZN' THEN RAISE EXCEPTION 'SGF_DC_VERSION_POLICY'; END IF;
|
||||
IF latest=0 THEN IF NEW.previous_id IS NOT NULL THEN RAISE EXCEPTION 'SGF_DC_PREVIOUS'; END IF;
|
||||
ELSE PERFORM 1 FROM dc_calculations WHERE id=NEW.previous_id AND order_id=o.id AND version=latest; IF NOT FOUND THEN RAISE EXCEPTION 'SGF_DC_PREVIOUS'; END IF; END IF;
|
||||
IF jsonb_array_length(NEW.snapshot->'lines')<>2 THEN RAISE EXCEPTION 'SGF_DC_TWO_SOURCES'; END IF;
|
||||
FOR line IN SELECT * FROM jsonb_array_elements(NEW.snapshot->'lines') LOOP
|
||||
PERFORM sgf_dc_source((line->>'entry_id')::bigint,o.id,(line->>'entry_version')::integer);
|
||||
IF line->>'rate_id' IS NOT NULL THEN
|
||||
SELECT * INTO STRICT r FROM dc_rates WHERE id=(line->>'rate_id')::bigint AND order_id=o.id AND entry_id=(line->>'entry_id')::bigint AND entry_version=(line->>'entry_version')::integer AND version=(line->>'rate_version')::integer;
|
||||
IF EXISTS(SELECT 1 FROM dc_rates WHERE previous_id=r.id) OR NOT EXISTS(SELECT 1 FROM dc_decisions WHERE rate_id=r.id AND decision='approved') THEN RAISE EXCEPTION 'SGF_DC_RATE_NOT_CURRENT_APPROVED'; END IF;
|
||||
END IF;
|
||||
END LOOP;
|
||||
END IF;
|
||||
RETURN NEW;
|
||||
EXCEPTION WHEN NO_DATA_FOUND THEN RAISE EXCEPTION 'SGF_DC_REFERENCE'; END; $$;
|
||||
CREATE TRIGGER dc_rate_integrity BEFORE INSERT ON dc_rates FOR EACH ROW EXECUTE FUNCTION sgf_dc_guard();
|
||||
CREATE TRIGGER dc_calculation_integrity BEFORE INSERT ON dc_calculations FOR EACH ROW EXECUTE FUNCTION sgf_dc_guard();
|
||||
CREATE TRIGGER dc_decision_integrity BEFORE INSERT ON dc_decisions FOR EACH ROW EXECUTE FUNCTION sgf_dc_guard();
|
||||
CREATE TRIGGER dc_command_integrity BEFORE INSERT ON dc_commands FOR EACH ROW EXECUTE FUNCTION sgf_dc_guard();
|
||||
@@ -0,0 +1,136 @@
|
||||
CREATE TABLE sr_records (
|
||||
id bigserial PRIMARY KEY, tenant_id bigint NOT NULL, company_id bigint NOT NULL, unit_id bigint NOT NULL,
|
||||
invoice_id bigint NOT NULL REFERENCES si_invoices(id), client_id bigint NOT NULL REFERENCES a_clients(id),
|
||||
obligation_id bigint REFERENCES sr_records(id), receipt_id bigint REFERENCES sr_records(id),
|
||||
kind text NOT NULL CHECK(kind IN ('obligation','receipt','observation','correction')),
|
||||
currency text NOT NULL CHECK(currency='MZN'), amount numeric NOT NULL CHECK(amount>=0 AND amount<10000000000000000 AND amount=trunc(amount,2)),
|
||||
source text NOT NULL, external_id text NOT NULL, data jsonb NOT NULL,
|
||||
version integer NOT NULL DEFAULT 1 CHECK(version=1), actor_id bigint NOT NULL REFERENCES users(id), created_at timestamptz NOT NULL,
|
||||
UNIQUE(company_id,unit_id,kind,source,external_id),
|
||||
FOREIGN KEY(tenant_id,company_id,unit_id) REFERENCES units(tenant_id,company_id,id)
|
||||
);
|
||||
CREATE UNIQUE INDEX sr_one_obligation ON sr_records(invoice_id) WHERE kind='obligation';
|
||||
CREATE UNIQUE INDEX sr_reduction_document ON sr_records(company_id,unit_id,(data->>'document_ref')) WHERE kind='correction' AND data->>'action'='reduction';
|
||||
CREATE TABLE sr_effects (
|
||||
id bigserial PRIMARY KEY, record_id bigint NOT NULL REFERENCES sr_records(id),
|
||||
obligation_id bigint NOT NULL REFERENCES sr_records(id), receipt_id bigint REFERENCES sr_records(id),
|
||||
kind text NOT NULL CHECK(kind IN ('open','receipt_confirm','refused','allocate','reconcile','divergence','reverse_allocation','reverse_reconcile','reverse_receipt','reduction','due')),
|
||||
amount numeric NOT NULL CHECK(amount>=0 AND amount<10000000000000000 AND amount=trunc(amount,2)), target_effect_id bigint REFERENCES sr_effects(id),
|
||||
revision integer NOT NULL CHECK(revision>=0), data jsonb NOT NULL,
|
||||
actor_id bigint NOT NULL REFERENCES users(id), created_at timestamptz NOT NULL
|
||||
);
|
||||
CREATE UNIQUE INDEX sr_terminal_decision ON sr_effects(record_id) WHERE kind NOT IN ('allocate','divergence');
|
||||
CREATE UNIQUE INDEX sr_reverse_once ON sr_effects(target_effect_id) WHERE target_effect_id IS NOT NULL;
|
||||
CREATE UNIQUE INDEX sr_divergence_once ON sr_effects(record_id) WHERE kind='divergence';
|
||||
CREATE INDEX sr_obligation_effects ON sr_effects(obligation_id,id);
|
||||
CREATE TABLE sr_commands (
|
||||
id bigserial PRIMARY KEY, tenant_id bigint NOT NULL, company_id bigint NOT NULL, unit_id bigint NOT NULL,
|
||||
actor_id bigint NOT NULL REFERENCES users(id), action text NOT NULL, command_key varchar(100) NOT NULL,
|
||||
request_hash varchar(64) NOT NULL, result jsonb NOT NULL, created_at timestamptz NOT NULL,
|
||||
UNIQUE(company_id,unit_id,actor_id,action,command_key),
|
||||
FOREIGN KEY(tenant_id,company_id,unit_id) REFERENCES units(tenant_id,company_id,id)
|
||||
);
|
||||
CREATE TABLE sr_events (
|
||||
id bigserial PRIMARY KEY, command_id bigint NOT NULL UNIQUE REFERENCES sr_commands(id),
|
||||
type text NOT NULL, schema_version integer NOT NULL CHECK(schema_version=1), payload jsonb NOT NULL, created_at timestamptz NOT NULL
|
||||
);
|
||||
CREATE TABLE sr_outbox (event_id bigint PRIMARY KEY REFERENCES sr_events(id), state text NOT NULL CHECK(state='captured_simulation_only'));
|
||||
CREATE TABLE sr_deliveries (event_id bigint PRIMARY KEY REFERENCES sr_events(id), consumer text NOT NULL CHECK(consumer='simulation_integrity_v1'), created_at timestamptz NOT NULL);
|
||||
|
||||
CREATE OR REPLACE FUNCTION sgf_sr_environment() RETURNS void LANGUAGE plpgsql AS $$
|
||||
BEGIN
|
||||
IF current_database() IS DISTINCT FROM 'sgf_tempo_test' OR inet_server_port() IS DISTINCT FROM 55432 THEN RAISE EXCEPTION 'SGF_SR_TEST_DATABASE_ONLY'; END IF;
|
||||
END; $$;
|
||||
|
||||
CREATE OR REPLACE FUNCTION sgf_sr_record_guard() RETURNS trigger LANGUAGE plpgsql AS $$
|
||||
DECLARE inv si_invoices; ob sr_records; rc sr_records; cid bigint; expected numeric;
|
||||
BEGIN
|
||||
PERFORM sgf_sr_environment();
|
||||
PERFORM 1 FROM companies WHERE id=NEW.company_id FOR UPDATE;
|
||||
SELECT * INTO STRICT inv FROM si_invoices WHERE id=NEW.invoice_id;
|
||||
SELECT (snapshot->>'client_id')::bigint INTO STRICT cid FROM a_history
|
||||
WHERE area='billing_drafts' AND record_id=inv.draft_id AND version=(inv.snapshot->'document'->>'draft_version')::integer
|
||||
AND tenant_id=inv.tenant_id AND company_id=inv.company_id AND unit_id=inv.unit_id;
|
||||
IF ROW(inv.tenant_id,inv.company_id,inv.unit_id,cid) IS DISTINCT FROM ROW(NEW.tenant_id,NEW.company_id,NEW.unit_id,NEW.client_id)
|
||||
OR inv.snapshot->>'notice' IS DISTINCT FROM 'TESTE — SEM VALIDADE FISCAL'
|
||||
OR inv.snapshot->>'simulation_only' IS DISTINCT FROM 'true'
|
||||
OR inv.snapshot->'document'->'data'->>'currency' IS DISTINCT FROM NEW.currency
|
||||
THEN RAISE EXCEPTION 'SGF_SR_DOCUMENT_SCOPE'; END IF;
|
||||
IF NEW.data->>'policy' IS DISTINCT FROM 'SGF-RECEIVABLES-SIM-v1' THEN RAISE EXCEPTION 'SGF_SR_POLICY'; END IF;
|
||||
IF NEW.kind='obligation' THEN
|
||||
expected=(inv.snapshot->'calculation'->>'total_document_proposed')::numeric;
|
||||
IF NEW.obligation_id IS NOT NULL OR NEW.receipt_id IS NOT NULL OR NEW.amount<>expected OR expected<=0 OR trunc(expected,2)<>expected THEN RAISE EXCEPTION 'SGF_SR_ORIGIN_AMOUNT'; END IF;
|
||||
ELSE
|
||||
SELECT * INTO STRICT ob FROM sr_records WHERE id=NEW.obligation_id AND kind='obligation';
|
||||
IF ROW(ob.tenant_id,ob.company_id,ob.unit_id,ob.invoice_id,ob.client_id,ob.currency) IS DISTINCT FROM ROW(NEW.tenant_id,NEW.company_id,NEW.unit_id,NEW.invoice_id,NEW.client_id,NEW.currency)
|
||||
OR NOT EXISTS(SELECT 1 FROM sr_effects WHERE record_id=ob.id AND kind='open') THEN RAISE EXCEPTION 'SGF_SR_OBLIGATION_SCOPE'; END IF;
|
||||
IF NEW.kind='receipt' AND (NEW.amount<=0 OR NEW.receipt_id IS NOT NULL OR coalesce(NEW.data->>'evidence','')='' OR coalesce(NEW.data->>'date','')='') THEN RAISE EXCEPTION 'SGF_SR_RECEIPT'; END IF;
|
||||
IF NEW.receipt_id IS NOT NULL THEN
|
||||
SELECT * INTO STRICT rc FROM sr_records WHERE id=NEW.receipt_id AND kind='receipt';
|
||||
IF rc.obligation_id<>ob.id THEN RAISE EXCEPTION 'SGF_SR_RECEIPT_SCOPE'; END IF;
|
||||
END IF;
|
||||
IF NEW.kind='observation' AND (NEW.receipt_id IS NULL OR coalesce(NEW.data->>'date','')='') THEN RAISE EXCEPTION 'SGF_SR_OBSERVATION'; END IF;
|
||||
IF NEW.kind='correction' AND (NEW.data->>'action' NOT IN ('reverse_allocation','reverse_reconcile','reverse_receipt','reduction','due') OR coalesce(NEW.data->>'reason','')='') THEN RAISE EXCEPTION 'SGF_SR_CORRECTION'; END IF;
|
||||
END IF;
|
||||
RETURN NEW;
|
||||
EXCEPTION WHEN NO_DATA_FOUND THEN RAISE EXCEPTION 'SGF_SR_INVALID_REFERENCE';
|
||||
END; $$;
|
||||
CREATE TRIGGER sr_record_guard BEFORE INSERT ON sr_records FOR EACH ROW EXECUTE FUNCTION sgf_sr_record_guard();
|
||||
|
||||
CREATE OR REPLACE FUNCTION sgf_sr_effect_guard() RETURNS trigger LANGUAGE plpgsql AS $$
|
||||
DECLARE r sr_records; ob sr_records; rc sr_records; target sr_effects; balance numeric; available numeric; n integer; a text;
|
||||
BEGIN
|
||||
PERFORM sgf_sr_environment();
|
||||
SELECT * INTO STRICT r FROM sr_records WHERE id=NEW.record_id;
|
||||
PERFORM 1 FROM companies WHERE id=r.company_id FOR UPDATE;
|
||||
SELECT * INTO STRICT ob FROM sr_records WHERE id=NEW.obligation_id AND kind='obligation';
|
||||
IF (CASE WHEN r.kind='obligation' THEN r.id ELSE r.obligation_id END)<>ob.id THEN RAISE EXCEPTION 'SGF_SR_EFFECT_SCOPE'; END IF;
|
||||
SELECT count(*) INTO n FROM sr_effects WHERE obligation_id=ob.id;
|
||||
IF NEW.revision<>n THEN RAISE EXCEPTION 'SGF_SR_STALE_REVISION'; END IF;
|
||||
IF NEW.kind IN ('open','receipt_confirm','refused','reconcile','divergence','reverse_allocation','reverse_reconcile','reverse_receipt','reduction','due') AND NEW.actor_id=r.actor_id THEN RAISE EXCEPTION 'SGF_SR_SELF_APPROVAL'; END IF;
|
||||
IF NEW.kind='open' AND (r.kind<>'obligation' OR NEW.amount<>r.amount) THEN RAISE EXCEPTION 'SGF_SR_OPEN'; END IF;
|
||||
IF NEW.kind='refused' AND (r.kind NOT IN ('obligation','receipt','correction') OR NEW.amount<>0) THEN RAISE EXCEPTION 'SGF_SR_REFUSE'; END IF;
|
||||
IF NEW.kind='receipt_confirm' AND (r.kind<>'receipt' OR NEW.amount<>r.amount) THEN RAISE EXCEPTION 'SGF_SR_CONFIRM'; END IF;
|
||||
IF NEW.receipt_id IS NOT NULL THEN
|
||||
SELECT * INTO STRICT rc FROM sr_records WHERE id=NEW.receipt_id AND kind='receipt';
|
||||
IF rc.obligation_id<>ob.id OR NOT EXISTS(SELECT 1 FROM sr_effects WHERE record_id=rc.id AND kind='receipt_confirm')
|
||||
OR EXISTS(SELECT 1 FROM sr_effects WHERE receipt_id=rc.id AND kind='reverse_receipt') THEN RAISE EXCEPTION 'SGF_SR_RECEIPT_UNAVAILABLE'; END IF;
|
||||
END IF;
|
||||
IF NEW.kind='receipt_confirm' AND NEW.receipt_id IS NOT NULL THEN RAISE EXCEPTION 'SGF_SR_CONFIRM_LINK'; END IF;
|
||||
IF NEW.kind='receipt_confirm' AND NEW.amount+(SELECT coalesce(sum(CASE WHEN kind='receipt_confirm' THEN amount WHEN kind='reverse_receipt' THEN -amount ELSE 0 END),0) FROM sr_effects WHERE obligation_id=ob.id)>=10000000000000000 THEN RAISE EXCEPTION 'SGF_SR_TOTAL_OVERFLOW'; END IF;
|
||||
IF NEW.kind NOT IN ('reverse_allocation','reverse_reconcile') AND NEW.target_effect_id IS NOT NULL THEN RAISE EXCEPTION 'SGF_SR_UNEXPECTED_TARGET'; END IF;
|
||||
IF NEW.kind NOT IN ('open','refused') AND NOT EXISTS(SELECT 1 FROM sr_effects WHERE record_id=ob.id AND kind='open') THEN RAISE EXCEPTION 'SGF_SR_NOT_OPEN'; END IF;
|
||||
SELECT ob.amount-coalesce(sum(CASE WHEN kind IN ('allocate','reduction') THEN amount WHEN kind='reverse_allocation' THEN -amount ELSE 0 END),0) INTO balance FROM sr_effects WHERE obligation_id=ob.id;
|
||||
IF NEW.kind='allocate' THEN
|
||||
IF r.kind<>'receipt' OR NEW.receipt_id IS DISTINCT FROM r.id OR NEW.amount<=0 THEN RAISE EXCEPTION 'SGF_SR_ALLOCATION'; END IF;
|
||||
SELECT rc.amount-coalesce(sum(CASE WHEN kind='allocate' THEN amount WHEN kind='reverse_allocation' THEN -amount ELSE 0 END),0) INTO available FROM sr_effects WHERE receipt_id=rc.id;
|
||||
IF NEW.amount>balance OR NEW.amount>available THEN RAISE EXCEPTION 'SGF_SR_OVERALLOCATION'; END IF;
|
||||
END IF;
|
||||
IF NEW.kind IN ('reconcile','divergence') THEN
|
||||
IF r.kind<>'observation' OR r.receipt_id IS DISTINCT FROM NEW.receipt_id THEN RAISE EXCEPTION 'SGF_SR_RECONCILE_SCOPE'; END IF;
|
||||
IF NEW.kind='reconcile' AND (r.amount<>rc.amount OR NEW.amount<>rc.amount) THEN RAISE EXCEPTION 'SGF_SR_RECONCILE_AMOUNT'; END IF;
|
||||
IF NEW.kind='divergence' AND (r.amount=rc.amount OR NEW.amount<>abs(r.amount-rc.amount)) THEN RAISE EXCEPTION 'SGF_SR_DIVERGENCE'; END IF;
|
||||
IF EXISTS(SELECT 1 FROM sr_effects e WHERE e.kind='reconcile' AND (e.receipt_id=rc.id OR e.record_id=r.id) AND NOT EXISTS(SELECT 1 FROM sr_effects v WHERE v.target_effect_id=e.id)) THEN RAISE EXCEPTION 'SGF_SR_OBSERVATION_REUSED'; END IF;
|
||||
END IF;
|
||||
IF NEW.kind IN ('reverse_allocation','reverse_reconcile','reverse_receipt','reduction','due') THEN
|
||||
IF r.kind<>'correction' OR r.data->>'action' IS DISTINCT FROM NEW.kind OR (r.data->>'revision')::integer IS DISTINCT FROM n THEN RAISE EXCEPTION 'SGF_SR_CORRECTION_VERSION'; END IF;
|
||||
IF NEW.kind IN ('reverse_allocation','reverse_reconcile') THEN
|
||||
SELECT * INTO STRICT target FROM sr_effects WHERE id=NEW.target_effect_id AND obligation_id=ob.id;
|
||||
IF target.kind<>(CASE WHEN NEW.kind='reverse_allocation' THEN 'allocate' ELSE 'reconcile' END) OR NEW.amount<>target.amount OR NEW.receipt_id IS DISTINCT FROM target.receipt_id OR (r.data->>'target_effect_id')::bigint IS DISTINCT FROM target.id THEN RAISE EXCEPTION 'SGF_SR_REVERSAL_TARGET'; END IF;
|
||||
ELSIF NEW.target_effect_id IS NOT NULL THEN RAISE EXCEPTION 'SGF_SR_UNEXPECTED_TARGET'; END IF;
|
||||
IF NEW.kind='reverse_receipt' THEN
|
||||
IF r.receipt_id IS DISTINCT FROM NEW.receipt_id OR rc.id IS NULL OR NEW.amount<>rc.amount THEN RAISE EXCEPTION 'SGF_SR_REVERSAL_RECEIPT'; END IF;
|
||||
SELECT coalesce(sum(CASE WHEN kind='allocate' THEN amount WHEN kind='reverse_allocation' THEN -amount ELSE 0 END),0) INTO available FROM sr_effects WHERE receipt_id=rc.id;
|
||||
IF available<>0 OR EXISTS(SELECT 1 FROM sr_effects e WHERE e.receipt_id=rc.id AND e.kind='reconcile' AND NOT EXISTS(SELECT 1 FROM sr_effects v WHERE v.target_effect_id=e.id)) THEN RAISE EXCEPTION 'SGF_SR_REVERSAL_DEPENDENCIES'; END IF;
|
||||
END IF;
|
||||
IF NEW.kind='reduction' AND (NEW.amount<=0 OR NEW.amount<>r.amount OR NEW.amount>balance OR coalesce(r.data->>'document_ref','') NOT LIKE 'TEST-REDUCTION-%' OR r.data->>'line' IS DISTINCT FROM '1') THEN RAISE EXCEPTION 'SGF_SR_REDUCTION'; END IF;
|
||||
IF NEW.kind='due' AND (NEW.amount<>0 OR NEW.data->>'due_date' IS DISTINCT FROM r.data->>'due_date') THEN RAISE EXCEPTION 'SGF_SR_DUE'; END IF;
|
||||
END IF;
|
||||
IF NEW.kind IN ('open','refused','receipt_confirm','reduction','due') AND NEW.receipt_id IS NOT NULL THEN RAISE EXCEPTION 'SGF_SR_UNEXPECTED_RECEIPT'; END IF;
|
||||
RETURN NEW;
|
||||
EXCEPTION WHEN NO_DATA_FOUND THEN RAISE EXCEPTION 'SGF_SR_INVALID_REFERENCE';
|
||||
END; $$;
|
||||
CREATE TRIGGER sr_effect_guard BEFORE INSERT ON sr_effects FOR EACH ROW EXECUTE FUNCTION sgf_sr_effect_guard();
|
||||
|
||||
CREATE OR REPLACE FUNCTION sgf_sr_test_insert() RETURNS trigger LANGUAGE plpgsql AS $$
|
||||
BEGIN PERFORM sgf_sr_environment(); RETURN NEW; END; $$;
|
||||
@@ -0,0 +1,162 @@
|
||||
CREATE TABLE wo_equipment (
|
||||
id bigserial PRIMARY KEY, tenant_id bigint NOT NULL, company_id bigint NOT NULL, client_id bigint NOT NULL REFERENCES a_clients(id),
|
||||
identifier text NOT NULL, description text NOT NULL, serial text, actor_id bigint NOT NULL REFERENCES users(id), created_at timestamptz NOT NULL,
|
||||
UNIQUE(company_id,identifier), FOREIGN KEY(tenant_id,company_id) REFERENCES companies(tenant_id,id)
|
||||
);
|
||||
CREATE TABLE wo_orders (
|
||||
id bigserial PRIMARY KEY, tenant_id bigint NOT NULL, company_id bigint NOT NULL, unit_id bigint NOT NULL,
|
||||
client_id bigint NOT NULL REFERENCES a_clients(id), equipment_id bigint NOT NULL REFERENCES wo_equipment(id),
|
||||
reference text NOT NULL, request text NOT NULL, location text NOT NULL, evidence text NOT NULL,
|
||||
actor_id bigint NOT NULL REFERENCES users(id), created_at timestamptz NOT NULL,
|
||||
UNIQUE(company_id,reference), FOREIGN KEY(tenant_id,company_id,unit_id) REFERENCES units(tenant_id,company_id,id)
|
||||
);
|
||||
CREATE TABLE wo_entries (
|
||||
id bigserial PRIMARY KEY, order_id bigint NOT NULL REFERENCES wo_orders(id),
|
||||
kind text NOT NULL CHECK(kind IN ('assignment','task','authorization','start','time','material')),
|
||||
origin text NOT NULL, version integer NOT NULL CHECK(version>0), previous_id bigint UNIQUE REFERENCES wo_entries(id),
|
||||
task_id bigint REFERENCES wo_entries(id), authorization_id bigint REFERENCES wo_entries(id), start_id bigint REFERENCES wo_entries(id),
|
||||
technician_id bigint REFERENCES users(id), starts_at timestamptz, ends_at timestamptz, minutes bigint,
|
||||
quantity numeric CHECK(quantity>0 AND quantity<10000000000000000 AND quantity=trunc(quantity,8)),
|
||||
outside_authority boolean NOT NULL DEFAULT false, revision integer NOT NULL CHECK(revision>=0), data jsonb NOT NULL,
|
||||
actor_id bigint NOT NULL REFERENCES users(id), created_at timestamptz NOT NULL,
|
||||
UNIQUE(order_id,kind,origin,version)
|
||||
);
|
||||
CREATE UNIQUE INDEX wo_start_completion ON wo_entries(start_id) WHERE start_id IS NOT NULL;
|
||||
CREATE INDEX wo_order_entries ON wo_entries(order_id,id);
|
||||
CREATE TABLE wo_decisions (
|
||||
id bigserial PRIMARY KEY, entry_id bigint NOT NULL UNIQUE REFERENCES wo_entries(id),
|
||||
entry_version integer NOT NULL, revision integer NOT NULL, decision text NOT NULL CHECK(decision IN ('verified','refused','acknowledged')),
|
||||
reason text NOT NULL, actor_id bigint NOT NULL REFERENCES users(id), created_at timestamptz NOT NULL
|
||||
);
|
||||
CREATE TABLE wo_commands (
|
||||
id bigserial PRIMARY KEY, tenant_id bigint NOT NULL, company_id bigint NOT NULL, unit_id bigint NOT NULL,
|
||||
actor_id bigint NOT NULL REFERENCES users(id), action text NOT NULL, command_key varchar(100) NOT NULL, request_hash varchar(64) NOT NULL,
|
||||
order_id bigint NOT NULL REFERENCES wo_orders(id), result jsonb NOT NULL, created_at timestamptz NOT NULL,
|
||||
UNIQUE(company_id,unit_id,actor_id,action,command_key), FOREIGN KEY(tenant_id,company_id,unit_id) REFERENCES units(tenant_id,company_id,id)
|
||||
);
|
||||
CREATE TABLE wo_events (
|
||||
id bigserial PRIMARY KEY, command_id bigint NOT NULL UNIQUE REFERENCES wo_commands(id), type text NOT NULL,
|
||||
schema_version integer NOT NULL CHECK(schema_version=1), payload jsonb NOT NULL, created_at timestamptz NOT NULL
|
||||
);
|
||||
CREATE TABLE wo_outbox (event_id bigint PRIMARY KEY REFERENCES wo_events(id), state text NOT NULL CHECK(state='captured_no_cost_stock_or_billing'));
|
||||
|
||||
CREATE OR REPLACE FUNCTION sgf_wo_environment() RETURNS void LANGUAGE plpgsql AS $$
|
||||
BEGIN
|
||||
IF current_database() IS DISTINCT FROM 'sgf_tempo_test' OR inet_server_port() IS DISTINCT FROM 55432 THEN RAISE EXCEPTION 'SGF_WO_TEST_DATABASE_ONLY'; END IF;
|
||||
END; $$;
|
||||
CREATE OR REPLACE FUNCTION sgf_wo_test_only() RETURNS trigger LANGUAGE plpgsql AS $$
|
||||
BEGIN PERFORM sgf_wo_environment(); RETURN NEW; END; $$;
|
||||
CREATE OR REPLACE FUNCTION sgf_wo_revision(oid bigint) RETURNS integer LANGUAGE sql VOLATILE AS $$
|
||||
SELECT (SELECT count(*) FROM wo_entries WHERE order_id=oid)::integer+(SELECT count(*) FROM wo_decisions d JOIN wo_entries e ON e.id=d.entry_id WHERE e.order_id=oid)::integer;
|
||||
$$;
|
||||
CREATE OR REPLACE FUNCTION sgf_wo_parent_guard() RETURNS trigger LANGUAGE plpgsql AS $$
|
||||
DECLARE eq wo_equipment;
|
||||
BEGIN
|
||||
PERFORM sgf_wo_environment();
|
||||
PERFORM 1 FROM companies WHERE id=NEW.company_id FOR UPDATE;
|
||||
IF NOT EXISTS(SELECT 1 FROM a_clients WHERE id=NEW.client_id AND tenant_id=NEW.tenant_id AND company_id=NEW.company_id) THEN RAISE EXCEPTION 'SGF_WO_CLIENT_SCOPE'; END IF;
|
||||
IF TG_TABLE_NAME='wo_orders' THEN
|
||||
SELECT * INTO STRICT eq FROM wo_equipment WHERE id=NEW.equipment_id;
|
||||
IF ROW(eq.tenant_id,eq.company_id,eq.client_id) IS DISTINCT FROM ROW(NEW.tenant_id,NEW.company_id,NEW.client_id) THEN RAISE EXCEPTION 'SGF_WO_EQUIPMENT_SCOPE'; END IF;
|
||||
END IF;
|
||||
RETURN NEW;
|
||||
EXCEPTION WHEN NO_DATA_FOUND THEN RAISE EXCEPTION 'SGF_WO_INVALID_REFERENCE';
|
||||
END; $$;
|
||||
CREATE TRIGGER wo_equipment_scope BEFORE INSERT ON wo_equipment FOR EACH ROW EXECUTE FUNCTION sgf_wo_parent_guard();
|
||||
CREATE TRIGGER wo_order_scope BEFORE INSERT ON wo_orders FOR EACH ROW EXECUTE FUNCTION sgf_wo_parent_guard();
|
||||
|
||||
CREATE OR REPLACE FUNCTION sgf_wo_entry_guard() RETURNS trigger LANGUAGE plpgsql AS $$
|
||||
DECLARE o wo_orders; p wo_entries; t wo_entries; au wo_entries; st wo_entries; x wo_entries; assigned bigint; pause jsonb; last_end timestamptz; pause_seconds numeric:=0; duration numeric; item text; used numeric; provided numeric; event_kind text;
|
||||
BEGIN
|
||||
PERFORM sgf_wo_environment();
|
||||
SELECT * INTO STRICT o FROM wo_orders WHERE id=NEW.order_id;
|
||||
PERFORM 1 FROM companies WHERE id=o.company_id FOR UPDATE;
|
||||
IF NEW.revision<>sgf_wo_revision(o.id) OR NEW.data->>'policy' IS DISTINCT FROM 'WORKSHOP-RESOURCE-RECORD-v1' THEN RAISE EXCEPTION 'SGF_WO_STALE_REVISION'; END IF;
|
||||
IF NEW.previous_id IS NOT NULL THEN
|
||||
SELECT * INTO STRICT p FROM wo_entries WHERE id=NEW.previous_id;
|
||||
IF ROW(p.order_id,p.kind,p.origin) IS DISTINCT FROM ROW(NEW.order_id,NEW.kind,NEW.origin) OR NEW.version<>p.version+1
|
||||
OR EXISTS(SELECT 1 FROM wo_entries WHERE previous_id=p.id) OR coalesce(NEW.data->>'correction_reason','')='' THEN RAISE EXCEPTION 'SGF_WO_VERSION_CHAIN'; END IF;
|
||||
IF NEW.kind IN ('task','time','material') AND p.actor_id<>NEW.actor_id THEN RAISE EXCEPTION 'SGF_WO_ORIGIN_AUTHOR'; END IF;
|
||||
ELSE
|
||||
IF NEW.version<>1 THEN RAISE EXCEPTION 'SGF_WO_VERSION'; END IF;
|
||||
END IF;
|
||||
SELECT technician_id INTO assigned FROM wo_entries WHERE order_id=o.id AND kind='assignment' ORDER BY id DESC LIMIT 1;
|
||||
IF NEW.kind='assignment' THEN
|
||||
IF NEW.technician_id IS NULL OR NOT EXISTS(SELECT 1 FROM permission_grants WHERE user_id=NEW.technician_id AND tenant_id=o.tenant_id AND company_id=o.company_id AND unit_id=o.unit_id AND permission='workshop.record')
|
||||
OR NOT EXISTS(SELECT 1 FROM company_memberships WHERE user_id=NEW.technician_id AND company_id=o.company_id AND tenant_id=o.tenant_id) THEN RAISE EXCEPTION 'SGF_WO_ASSIGNEE'; END IF;
|
||||
END IF;
|
||||
IF NEW.kind IN ('task','start','time','material') AND (assigned IS DISTINCT FROM NEW.actor_id OR NEW.technician_id IS DISTINCT FROM NEW.actor_id) THEN RAISE EXCEPTION 'SGF_WO_ASSIGNED_TECHNICIAN'; END IF;
|
||||
IF NEW.kind='task' THEN
|
||||
IF coalesce(NEW.data->>'description','')='' THEN RAISE EXCEPTION 'SGF_WO_TASK'; END IF;
|
||||
IF NEW.data->>'service_id' IS NOT NULL AND NOT EXISTS(SELECT 1 FROM a_services WHERE id=(NEW.data->>'service_id')::bigint AND company_id=o.company_id AND tenant_id=o.tenant_id) THEN RAISE EXCEPTION 'SGF_WO_SERVICE_SCOPE'; END IF;
|
||||
END IF;
|
||||
IF NEW.kind='authorization' THEN
|
||||
IF NEW.task_id IS NULL OR coalesce(NEW.data->>'authorized_by','')='' OR coalesce(NEW.data->>'capacity','')='' OR coalesce(NEW.data->>'authorized_at','')='' OR coalesce(NEW.data->>'channel','')='' OR coalesce(NEW.data->>'scope','')='' OR coalesce(NEW.data->>'evidence','')='' THEN RAISE EXCEPTION 'SGF_WO_AUTH_EVIDENCE'; END IF;
|
||||
IF (NEW.data->>'authorized_at')::timestamptz>NEW.created_at THEN RAISE EXCEPTION 'SGF_WO_FUTURE_AUTH'; END IF;
|
||||
END IF;
|
||||
IF NEW.kind IN ('authorization','start','time','material') THEN
|
||||
SELECT * INTO STRICT t FROM wo_entries WHERE id=NEW.task_id AND order_id=o.id AND kind='task';
|
||||
IF EXISTS(SELECT 1 FROM wo_entries WHERE previous_id=t.id) AND NEW.kind IN ('authorization','start') THEN RAISE EXCEPTION 'SGF_WO_STALE_TASK'; END IF;
|
||||
END IF;
|
||||
IF NEW.kind IN ('start','time','material') THEN
|
||||
NEW.outside_authority:=true;
|
||||
IF NEW.authorization_id IS NOT NULL THEN
|
||||
SELECT * INTO STRICT au FROM wo_entries WHERE id=NEW.authorization_id AND order_id=o.id AND kind='authorization' AND task_id=t.id;
|
||||
IF au.created_at<=coalesce(NEW.starts_at,NEW.created_at) AND (au.data->>'authorized_at')::timestamptz<=coalesce(NEW.starts_at,NEW.created_at)
|
||||
AND NOT EXISTS(SELECT 1 FROM wo_entries z WHERE z.previous_id=au.id AND z.created_at<=coalesce(NEW.ends_at,NEW.starts_at,NEW.created_at))
|
||||
AND NOT EXISTS(SELECT 1 FROM wo_entries z WHERE z.previous_id=t.id AND z.created_at<=coalesce(NEW.ends_at,NEW.starts_at,NEW.created_at)) THEN NEW.outside_authority:=false; END IF;
|
||||
END IF;
|
||||
IF coalesce(NEW.data->>'evidence','')='' THEN RAISE EXCEPTION 'SGF_WO_SOURCE_EVIDENCE'; END IF;
|
||||
IF NEW.previous_id IS NOT NULL AND p.outside_authority THEN NEW.outside_authority:=true; END IF;
|
||||
END IF;
|
||||
IF NEW.kind='start' THEN
|
||||
IF NEW.outside_authority OR NEW.starts_at IS NULL OR NEW.starts_at<>NEW.created_at THEN RAISE EXCEPTION 'SGF_WO_START_NOT_AUTHORIZED'; END IF;
|
||||
IF EXISTS(SELECT 1 FROM wo_entries e JOIN wo_orders w ON w.id=e.order_id WHERE w.company_id=o.company_id AND e.technician_id=NEW.technician_id AND e.kind='start' AND NOT EXISTS(SELECT 1 FROM wo_entries done WHERE done.start_id=e.id)) THEN RAISE EXCEPTION 'SGF_WO_ACTIVE_START'; END IF;
|
||||
END IF;
|
||||
IF NEW.kind='time' THEN
|
||||
IF coalesce(NEW.data->>'time_type','') NOT IN ('work','travel') OR jsonb_typeof(NEW.data->'pauses') IS DISTINCT FROM 'array' THEN RAISE EXCEPTION 'SGF_WO_TIME_TYPE'; END IF;
|
||||
IF NEW.starts_at IS NULL OR NEW.ends_at IS NULL OR NEW.ends_at<=NEW.starts_at OR NEW.ends_at>NEW.created_at THEN RAISE EXCEPTION 'SGF_WO_TIME_RANGE'; END IF;
|
||||
IF NEW.start_id IS NOT NULL THEN
|
||||
SELECT * INTO STRICT st FROM wo_entries WHERE id=NEW.start_id AND order_id=o.id AND kind='start' AND technician_id=NEW.technician_id;
|
||||
IF st.task_id<>NEW.task_id OR st.authorization_id IS DISTINCT FROM NEW.authorization_id OR st.starts_at<>NEW.starts_at THEN RAISE EXCEPTION 'SGF_WO_START_LINK'; END IF;
|
||||
ELSIF NEW.data->>'mode' IS DISTINCT FROM 'reported' THEN RAISE EXCEPTION 'SGF_WO_START_REQUIRED'; END IF;
|
||||
last_end:=NEW.starts_at;
|
||||
FOR pause IN SELECT value FROM jsonb_array_elements(NEW.data->'pauses') LOOP
|
||||
IF (pause->>'start')::timestamptz<last_end OR (pause->>'end')::timestamptz<=(pause->>'start')::timestamptz OR (pause->>'end')::timestamptz>NEW.ends_at THEN RAISE EXCEPTION 'SGF_WO_PAUSES'; END IF;
|
||||
pause_seconds:=pause_seconds+extract(epoch FROM ((pause->>'end')::timestamptz-(pause->>'start')::timestamptz)); last_end:=(pause->>'end')::timestamptz;
|
||||
END LOOP;
|
||||
duration:=extract(epoch FROM (NEW.ends_at-NEW.starts_at))-pause_seconds;
|
||||
IF duration IS NULL OR NEW.minutes IS NULL OR duration<=0 OR mod(duration,60)<>0 OR NEW.minutes IS DISTINCT FROM (duration/60)::bigint THEN RAISE EXCEPTION 'SGF_WO_EFFECTIVE_MINUTES'; END IF;
|
||||
-- Conservative occupied interval, half-open: pauses do not permit a second simultaneous task.
|
||||
IF EXISTS(SELECT 1 FROM wo_entries e JOIN wo_orders w ON w.id=e.order_id WHERE e.kind='time' AND w.company_id=o.company_id AND e.technician_id=NEW.technician_id
|
||||
AND NOT EXISTS(SELECT 1 FROM wo_entries z WHERE z.previous_id=e.id) AND e.id IS DISTINCT FROM NEW.previous_id
|
||||
AND tstzrange(e.starts_at,e.ends_at,'[)') && tstzrange(NEW.starts_at,NEW.ends_at,'[)')) THEN RAISE EXCEPTION 'SGF_WO_TIME_OVERLAP'; END IF;
|
||||
END IF;
|
||||
IF NEW.kind='material' THEN
|
||||
IF NEW.quantity IS NULL OR NEW.starts_at IS NULL OR NEW.starts_at>NEW.created_at OR coalesce(NEW.data->>'event','') NOT IN ('required','delivered','consumed','returned') OR coalesce(NEW.data->>'owner','') NOT IN ('company','client') OR coalesce(NEW.data->>'resource','')='' OR coalesce(NEW.data->>'unit','') NOT IN ('UN','KG','M','L') THEN RAISE EXCEPTION 'SGF_WO_MATERIAL'; END IF;
|
||||
-- resource identity, owner and UOM cannot change silently for one material reference.
|
||||
IF EXISTS(SELECT 1 FROM wo_entries e WHERE e.order_id=o.id AND e.kind='material' AND e.data->>'resource'=NEW.data->>'resource'
|
||||
AND ROW(e.data->>'owner',e.data->>'unit') IS DISTINCT FROM ROW(NEW.data->>'owner',NEW.data->>'unit')) THEN RAISE EXCEPTION 'SGF_WO_MATERIAL_UNIT_OWNER'; END IF;
|
||||
IF NEW.previous_id IS NOT NULL AND ROW(p.data->>'resource',p.data->>'owner',p.data->>'unit',p.data->>'event') IS DISTINCT FROM ROW(NEW.data->>'resource',NEW.data->>'owner',NEW.data->>'unit',NEW.data->>'event') THEN RAISE EXCEPTION 'SGF_WO_MATERIAL_ORIGIN'; END IF;
|
||||
IF NEW.data->>'event'<>'consumed' AND NOT coalesce(p.outside_authority,false) THEN NEW.outside_authority:=false; END IF;
|
||||
END IF;
|
||||
RETURN NEW;
|
||||
EXCEPTION WHEN NO_DATA_FOUND THEN RAISE EXCEPTION 'SGF_WO_INVALID_REFERENCE';
|
||||
END; $$;
|
||||
CREATE TRIGGER wo_entry_guard BEFORE INSERT ON wo_entries FOR EACH ROW EXECUTE FUNCTION sgf_wo_entry_guard();
|
||||
|
||||
CREATE OR REPLACE FUNCTION sgf_wo_decision_guard() RETURNS trigger LANGUAGE plpgsql AS $$
|
||||
DECLARE e wo_entries; o wo_orders;
|
||||
BEGIN
|
||||
PERFORM sgf_wo_environment();
|
||||
SELECT * INTO STRICT e FROM wo_entries WHERE id=NEW.entry_id;
|
||||
SELECT * INTO STRICT o FROM wo_orders WHERE id=e.order_id;
|
||||
PERFORM 1 FROM companies WHERE id=o.company_id FOR UPDATE;
|
||||
IF e.kind NOT IN ('task','time','material') OR NEW.actor_id=e.actor_id THEN RAISE EXCEPTION 'SGF_WO_SELF_VERIFICATION'; END IF;
|
||||
IF NEW.entry_version<>e.version OR EXISTS(SELECT 1 FROM wo_entries WHERE previous_id=e.id) OR NEW.revision<>sgf_wo_revision(o.id) THEN RAISE EXCEPTION 'SGF_WO_STALE_DECISION'; END IF;
|
||||
IF e.outside_authority AND NEW.decision='verified' THEN RAISE EXCEPTION 'SGF_WO_OUTSIDE_AUTHORITY'; END IF;
|
||||
IF NEW.decision='acknowledged' AND NOT e.outside_authority THEN RAISE EXCEPTION 'SGF_WO_ACK_ONLY_EXCEPTION'; END IF;
|
||||
RETURN NEW;
|
||||
EXCEPTION WHEN NO_DATA_FOUND THEN RAISE EXCEPTION 'SGF_WO_INVALID_REFERENCE';
|
||||
END; $$;
|
||||
CREATE TRIGGER wo_decision_guard BEFORE INSERT ON wo_decisions FOR EACH ROW EXECUTE FUNCTION sgf_wo_decision_guard();
|
||||
@@ -0,0 +1,172 @@
|
||||
# Facturação e recebimentos — matriz de informação para revisão
|
||||
|
||||
Especificação posterior de 26 de Outubro de 2026: [primeiro cálculo de factura de serviço](SERVICE_INVOICE_CALCULATION_SPEC.md), com caso mínimo, fórmulas, precisão, arredondamento/reconciliação, fontes oficiais parcialmente verificadas e lacunas explícitas. Apenas proposta, sem activação de taxa ou autorização de emissão.
|
||||
|
||||
Plano posterior de 26 de Outubro de 2026: [pré-visualização de rascunho de factura de serviço](DRAFT_INVOICE_PREVIEW_PLAN.md), com apresentação provisória, critérios, decisões e fontes ainda necessárias. Apenas proposta; preserva a preparação entregue e as bases aceites, sem autorização de implementação ou emissão.
|
||||
|
||||
Data: 26 de Outubro de 2026 (Africa/Johannesburg).
|
||||
|
||||
Estado: especificação apenas. O utilizador indicou que os três exemplos representam informação a contemplar nas facturas e recibos. Isso define uma referência de conteúdo pretendido, não a obrigatoriedade universal de todos os campos nem a validade fiscal dos modelos. Não autoriza implementação, emissão, recebimentos, contabilização, alterações de permissões ou publicação.
|
||||
|
||||
Actualização posterior: o utilizador autorizou um incremento delimitado de preparação documental, incluindo dados de emitente/clientes, preparação dos rascunhos e instruções de pagamento do emitente reutilizáveis. Banco/titular/identificadores/moeda/instruções facilitam o pagamento; não perguntam como o cliente vai pagar e não criam recebimento. Foram autorizados por prompt de execução próprio, com confirmação específica das novas concessões. A execução está documentada em [DOCUMENT_PREPARATION_DELIVERY.md](DOCUMENT_PREPARATION_DELIVERY.md). As restantes propostas desta matriz continuam sujeitas a validação e autorização, sem emissão fiscal, recebimento ou contabilização.
|
||||
|
||||
Preservar B1 aceite e o checkpoint `8fcd52c`, A (`ca13acb`) e identidade (`26b80df`). As fotografias B1 mantêm o significado «Confirmado internamente — sem validade fiscal». Esta revisão não lhes acrescenta validade, dados ou efeitos retrospectivos.
|
||||
|
||||
## Fontes e grau de validação
|
||||
|
||||
| Referência | Utilização nesta revisão | Limite |
|
||||
| --- | --- | --- |
|
||||
| SGF_TEMPO_Roteiro_v0_9.docx; SERVICES_WORKFLOW_SPEC.md; SERVICES_B_SCOPE.md | Reutilização de dados, distinção entre acontecimentos, captura permanente e pendências | Requisitos de produto e propostas; não são legislação fiscal |
|
||||
| SERVICES_A_DELIVERY.md e SERVICES_B1_DELIVERY.md, entregas aceites | Fundação existente: cadastro mínimo, rascunhos, decimais exactos e fotografia interna | Não incluem emissão fiscal ou recebimento |
|
||||
| E1 — Factura.jpg | Na imagem é um **recibo Tempo**, n.º 10, série 2026; linha refere **FT 10/2026** | O nome do ficheiro não determina o tipo documental |
|
||||
| E2 — Factura.png | **Factura-recibo TVCABO**, n.º 219144 / FR26; detalhe de serviço e informação de pagamento | Exemplo de conteúdo de outro emitente; não define regras para a Tempo |
|
||||
| E3 — Sem título.jpg | **Factura Tempo FT 11/2026**, com linhas, imposto e condições de pagamento | Não é a factura referenciada pelo recibo E1 |
|
||||
| Esclarecimento do utilizador nesta sessão | Os exemplos mostram informação que deve ser contemplada em facturas e recibos | Campos aplicáveis por documento/regime ainda carecem de delimitação |
|
||||
|
||||
Os exemplos foram lidos visualmente. Não foram copiados para o repositório nem transformados em operações/fixtures. Não transcrever números de contas, referências de pagamento ou assinaturas reais como configuração ou valores por omissão. Texto ambíguo numa imagem deve ser conferido no original, nunca completado por suposição.
|
||||
|
||||
**Fontes legais já validadas nesta tarefa: nenhuma.** Não foram fornecidos ou validados diplomas, orientações oficiais ou pareceres aplicáveis ao regime, período e operações da empresa. Esta matriz propõe informação e validações técnicas; antes de chamar um campo obrigatório por lei, associar-lhe fonte oficial, artigo, vigência, aplicabilidade e validação do responsável competente. A taxa observada nos exemplos não constitui validação da taxa aplicável.
|
||||
|
||||
## Tipos documentais e acontecimentos
|
||||
|
||||
| Tipo | Significado funcional proposto | Ligações necessárias | Não inferir |
|
||||
| --- | --- | --- | --- |
|
||||
| Factura | Documenta a facturação de bens/serviços segundo requisitos a validar | Empresa/unidade, cliente, linhas, origens e versão; recebimentos por afectação posterior | Que o serviço foi executado, que houve recebimento ou que ocorreu reconhecimento contabilístico |
|
||||
| Recibo | Documenta um recebimento identificado e as suas afectações, conforme âmbito a validar | Identidade própria, recebimento(s), documento(s) abrangidos e montante de cada afectação | Que o número do recibo é o da factura; que montante igual identifica a factura; que a emissão confirma liquidação bancária |
|
||||
| Factura-recibo | Representa conjuntamente facturação e recebimento no caso expressamente admitido e aprovado | Identidades dos dois acontecimentos e afectações explícitas, mesmo com uma apresentação conjunta | Que qualquer factura se torna paga ao ser emitida, ou que se pode contar novamente o recebimento num recibo separado |
|
||||
|
||||
Admissibilidade, momento de emissão e condições de utilização de cada tipo são pendências legais/operacionais. Uma factura-recibo não elimina a separação interna entre documento, recebimento, afectação e eventual lançamento contabilístico.
|
||||
|
||||
## O que os exemplos mostram
|
||||
|
||||
- E1: recibo emitido em 15/10/2026, com campo de vencimento também em 15/10/2026; a linha refere FT, série 2026, n.º 10, emitida em 09/08/2026 e com vencimento em 10/08/2026. Mostra valor e valor pago de 6 744,24, pendente 0,00 e total em MZN. As datas do cabeçalho são distintas das datas da factura referida. Não adoptar um vencimento de recibo por ser um campo existente no modelo.
|
||||
- E3: FT 11/2026, emitida em 12/10/2026, vencimento em 12/11/2026; condição impressa «Pagamento em 30 dias». Preservar ambos os dados observados e sinalizar a compatibilidade para revisão; não deduzir uma convenção de contagem nem corrigir silenciosamente a data. Descrição «Aluguer de Servidor Novembro», quantidade 1, unidade UN, preço/base 5 814,00, imposto apresentado 930,24 e total 6 744,24 MZN. O mês na descrição não fornece, por si só, um período exacto de serviço ou uma data de reconhecimento.
|
||||
- E2: preço apresentado 2 380,00, IVA identificado como «16 % Inc.», base apresentada 2 051,72, imposto 328,28 e total 2 380,00. O período de serviço indicado é 25/10/2026–23/11/2026; a emissão é 15/10/2026 às 10:50. Traz contrato, pedido de adesão, morada de instalação, indicação de pagamento VISA e extracto de conta. Estes campos têm funções diferentes e não devem tornar-se requisitos universais.
|
||||
- E1 e E3 têm o mesmo montante, mas identidades diferentes: **o recibo E1 não liquida FT 11/2026**. FT 10/2026 não foi fornecida como documento autónomo; apenas a sua referência aparece no recibo. A associação de E1 a FT 10/2026 fica registada como referência observada, sem inventar o conteúdo da factura ausente.
|
||||
- «Original», «Duplicado», carimbos, assinaturas e anotações manuscritas são elementos observados de apresentação/evidência. Não provam, por si só, validade legal, autoria electrónica ou data efectiva do recebimento. Uma anotação de entrega/recepção do papel não substitui a data do recebimento financeiro.
|
||||
|
||||
## Convenções da matriz
|
||||
|
||||
**Base a validar** significa candidato a informação documental, não obrigação legal já aprovada. «Exigir» abaixo refere-se à proposta funcional no momento indicado, sujeita a fechar as decisões. FT = factura; RC = recibo; FR = factura-recibo. «Fotografia: sim» significa conservar o valor utilizado no acontecimento futuro, com origem/versão, sem alterar as fotografias B1 já existentes. Informação desconhecida fica pendente; não vira vazio validado, zero ou valor por omissão.
|
||||
|
||||
### 1. Base de facturação a validar legalmente
|
||||
|
||||
| Campo | Origem / reutilização | Momento em que se propõe exigir | Validação proposta / pendência | Fotografia histórica |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| Identidade técnica do documento e tipo | Servidor; catálogo de tipos suportados | Criação do registo documental | ID estável; tipo permitido e âmbito explícito; referência interna B1 nunca vira número fiscal | Sim, identidade e tipo |
|
||||
| Tenant, empresa emitente e unidade | Contexto e cadastros existentes | Desde o rascunho | Contexto autorizado, unidade da empresa; sem transferência por formulário ou SQL em massa | Sim, IDs e identificação usada |
|
||||
| Denominação do emitente | Cadastro da empresa | Preparação documental; completude antes de eventual emissão | Reutilizar nome; distinguir designação interna de denominação legal a validar | Sim, nome utilizado e versão |
|
||||
| Identificação fiscal do emitente (NUIT) | Cadastro futuro da empresa | Antes de eventual emissão, se aplicável | Formato, validade e obrigação dependem do regime/fonte; não inferir do nome ou de exemplos | Sim, se utilizada |
|
||||
| Morada/localidade/país do emitente | Cadastro da empresa/unidade, conforme papel aprovado | Antes da emissão quando aplicável | Distinguir sede, estabelecimento e local da operação; conteúdo exigível por validar | Sim, dados efectivamente usados |
|
||||
| Identidade do cliente e nome/denominação | Cadastro de cliente existente | Nome basta para iniciar rascunho; identidade estável desde a associação | Não duplicar por unidade; cadastro mínimo não significa aptidão para emissão | Sim, ID, nome e versão |
|
||||
| NUIT do cliente / identificação alternativa admitida | Cadastro de contraparte, a especificar | Antes da emissão nos casos aplicáveis | Condições por tipo de cliente/operação, formato e alternativas por validar; não exigir por suposição em todo rascunho | Sim, valor e tipo usados |
|
||||
| Morada/localidade/país do cliente | Cadastro da contraparte | Antes da emissão quando aplicável | Não confundir morada fiscal, correspondência e instalação; requisitos por validar | Sim, papel e valor usados |
|
||||
| Série, número e identificação legível | Mecanismo documental futuro, por empresa/tipo e regras aprovadas | No momento de atribuição legal a definir | Unicidade, sequência, exercício/série, concorrência, lacunas e momento de atribuição pendentes; não copiar FT/FR26 como convenção universal | Sim; separado do ID técnico |
|
||||
| Data/hora de emissão | Operação documental futura | Emissão; não preencher como emissão real no rascunho | Fuso, data admissível e retroactividade por validar; não usar instante B1 como emissão | Sim, data e referência temporal |
|
||||
| Origem: prestação/rascunho/documento e versão | Relações existentes de A/B1 | Preparação e fixação documental | Mesma empresa/unidade; versão actual, origem válida; múltiplas/parciais dependem de decisão | Sim, IDs e versões |
|
||||
| Serviço/artigo e código utilizado | Catálogo empresarial existente | Escolha da linha; completude documental | Reutilizar serviço; código do exemplo não é chave universal; não criar stock por haver coluna «Artigo» | Sim, ID, código se usado, nome e versão |
|
||||
| Descrição da linha | Catálogo, prestação e eventual complemento autorizado | Preparação; completa antes de confirmação/emissão correspondente | Descrição inteligível; preservar complemento sem reescrever cadastro partilhado | Sim |
|
||||
| Quantidade | Prestação/rascunho | Pode ficar pendente em A; completa na confirmação B1 e preparação documental completa | Decimais exactos; sem coerção/arredondamento; regras para casos negativos/correcções fora deste âmbito | Sim |
|
||||
| Unidade de medida | Referência parametrizável futura do serviço/linha | Quando necessária à interpretação/emissão da linha | Não presumir UN; vocabulário e obrigatoriedade por operação a validar | Sim, código e significado usados |
|
||||
| Preço unitário e moeda do preço | Rascunho/acordo de serviço | Preparação dos valores; emissão exige definição aplicável | Precisão de A preservada; moeda desconhecida não é MZN; não apresentar valor definitivo sem moeda definida | Sim |
|
||||
| Modo de preço: imposto incluído ou acrescido | Escolha/regra aprovada e versionada | Antes de apurar base/imposto/total para emissão | Explícito; não inferir do montante ou do formato da impressão; A/B1 ainda não definem esse modo | Sim, modo e regra |
|
||||
| Moeda documental | Regra/indicação aprovada para o documento | Pode ser desconhecida em A/B1; definir antes de emissão monetária | Código e aplicabilidade; não inferir moeda funcional, câmbio ou política fiscal | Sim; desconhecimento B1 permanece preservado |
|
||||
| Base tributável por linha e por tratamento | Cálculo futuro segundo regras aprovadas | Apuramento documental | Separar quantidade × preço, descontos, base e incidência; base aritmética de A não é automaticamente base tributável | Sim, componentes e regra |
|
||||
| Tratamento fiscal, taxa e fundamento | Regra fiscal versionada, validada para empresa/operação/data | Apuramento/emissão quando aplicável | Distinguir tributado, isento, não sujeito ou outro tratamento aprovado; desconhecido nunca equivale a taxa zero | Sim, classificação, taxa/fundamento e versão |
|
||||
| Montante de imposto e resumo por tratamento | Cálculo futuro | Apuramento/emissão | Escala, modo e ponto de arredondamento a validar; reconciliar linhas/resumo; não somar moedas distintas | Sim, cálculo e resultados aplicados |
|
||||
| Total documental | Cálculo das componentes aprovadas | Antes de emissão | Base + imposto e demais componentes apenas conforme regra; explicável pelas linhas; não converter B1 em total fiscal | Sim |
|
||||
| Autor, instante e versões de dados/regras | Sessão e servidor; referências versionadas | Em cada acto relevante | Autor real e autorização; nenhum privilégio associado ao rótulo impresso «admin» | Sim; sem tokens ou segredos |
|
||||
|
||||
### 2. Requisitos condicionais por documento/operação
|
||||
|
||||
| Campo / condição | Origem | Momento em que se propõe exigir | Validação proposta / pendência | Fotografia histórica |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| Vencimento (FT; outros tipos só se houver significado aprovado) | Condições acordadas + data, ou indicação autorizada | Preparação de cobrança/emissão quando aplicável | Distinto da emissão; convenção de dias, excepções e alterações a aprovar. Campo de vencimento do RC E1 não o torna universal | Sim, vencimento original; mudanças futuras rastreáveis |
|
||||
| Condições/prazo de pagamento (FT) | Acordo/parametrização empresarial versionada | Preparação documental | Coerência com vencimento; não impor «30 dias»; explicitar divergências, sem corrigir silenciosamente | Sim |
|
||||
| Data/período da prestação | Prestação/acordo de serviço | Quando aplicável ao serviço/documento | Separar início/fim, execução, emissão e competência; não extrair período exacto da palavra «Novembro» | Sim, quando utilizado |
|
||||
| Desconto comercial/financeiro, em taxa e/ou valor | Acordo e regra aplicável | Se existir desconto | Explicitar por linha/documento, ordem, base e efeito no imposto; zeros dos exemplos não aprovam regra | Sim, componentes e regra |
|
||||
| Motivo/código de isenção ou outro tratamento | Classificação fiscal validada | Quando esse tratamento for utilizado | Fonte, condições, prova e texto exigível por validar; ausência de imposto não prova isenção | Sim, fundamento e versão |
|
||||
| Adiantamentos, outras contribuições, encargos/outros serviços | Operação de origem e classificação futura | Apenas se ocorrerem e forem incluídos | Não usar campos genéricos para ajustar total; identidade, sinal, moeda e tratamento próprios; evitar dupla contagem | Sim, se integrarem o documento |
|
||||
| Identidade do recebimento (RC/FR) | Registo futuro de recebimento, distinto do documento | Antes de documentar um recebimento | Não iniciar transferência; distinguir registo, evidência e verificação; novas regras/permissões por aprovar | Sim, ligação e estado observado |
|
||||
| Data/hora do recebimento (RC/FR) | Acontecimento e evidência de recebimento | Registo/documentação do recebimento | Separar da emissão do recibo, data bancária, registo no sistema e anotações manuscritas | Sim, datas e proveniência |
|
||||
| Montante recebido e moeda (RC/FR) | Recebimento identificado | Antes de produzir comprovativo | Positividade/precisão, moeda e evidência conforme regras a aprovar; montante declarado não comprova liquidação externa | Sim |
|
||||
| Meio de recebimento (RC/FR) | Registo/evidência; catálogo a delimitar | Quando documentado o recebimento e conforme operação | VISA é um exemplo, não fornecedor escolhido; não guardar números completos de cartão ou credenciais | Sim, classificação e referência não secreta necessária |
|
||||
| Referência/evidência da transacção (RC/FR) | Fonte observada/documento comprovativo | Conforme meio e critérios de verificação aprovados | Identificador contextual, origem, acesso e duplicados; QR/referência para pagar não prova que houve pagamento | Sim, ID da evidência/estado; acesso ao original protegido |
|
||||
| Documentos afectados: tipo, identidade, série e número (RC/FR) | Referência explícita e documento de origem | Antes de confirmar a afectação | Empresa, contraparte, moeda e documento exactos; FT 10/2026 não é FT 11/2026 | Sim, identidade e referência utilizada |
|
||||
| Valor de cada afectação (RC/FR) | Relação recebimento ↔ documento | Ao distribuir o recebimento | Uma identidade por afectação; controlar montante disponível, saldo elegível e repetição; casos de excedentes/câmbio dependem de regra | Sim, montante, moeda e origem |
|
||||
| Valor do documento, pago e pendente à data (RC/FR ou extracto) | Documento e afectações elegíveis no instante | Apresentação do comprovativo/extracto | Não editar livremente; distinguir afectação actual de acumulado; preservar data de corte e não confundir com saldo actual | Sim, se apresentados; valores actuais em consulta separada |
|
||||
| Conteúdo conjunto de facturação e recebimento (FR) | Documento + recebimento + afectação | Só no caso de uso FR aprovado | Completude de ambos, identidade/correlação, atomicidade e repetição; não contar outra dívida ou outro recebimento pela mesma operação | Sim, ambos e suas relações |
|
||||
| Original/duplicado, exemplar/página e reimpressão | Política de apresentação/reprodução a aprovar | Representação documental futura | Uma reprodução não cria outra emissão/recebimento; etiquetas e exigências legais por validar | Documento e metadados de reprodução, se aplicáveis |
|
||||
| Identificação do software/textos legais/certificação | Configuração e requisitos oficialmente validados | Se exigíveis na representação/emissão | Não copiar «processado por computador» ou licença de outro sistema como prova de conformidade | Sim, texto/versão aplicados, se usados |
|
||||
|
||||
### 3. Informação adicional parametrizável para gestão/estatísticas
|
||||
|
||||
Esta classificação é provisória: um campo pode mudar para condicional se um contrato, actividade ou fonte legal validada o exigir. Não construir agora um motor geral de parâmetros nem tornar todas estas colunas obrigatórias.
|
||||
|
||||
| Campo | Origem | Quando exigir | Validação proposta | Fotografia histórica |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| Número interno do cliente | Identidade/código do cadastro na empresa | Se usado em pesquisa ou apresentação | Unicidade no âmbito definido; não substituir ID técnico, NUIT ou associação documental | Sim, se impresso/utilizado |
|
||||
| Contrato e pedido de adesão/encomenda | Referências empresariais futuras | Só para operações que os utilizem | Mesma empresa/contraparte; referência externa com emissor; não implementar contratos recorrentes por causa de E2 | Sim, ligação e referência usadas |
|
||||
| Morada/local de instalação ou prestação | Cliente/contrato/local da operação | Serviços que precisem dessa distinção | Separar de morada fiscal e de unidade interna; não duplicar o cliente | Sim, se relevante/mostrado |
|
||||
| Renovação/vigência do contrato/serviço | Acordo e acontecimento próprio | Se houver serviço com vigência | Não derivar automaticamente de emissão ou pagamento sem regra; estado de renovação distinto do recebimento | Sim, informação apresentada |
|
||||
| Loja/local de atendimento, vendedor e operador | Contexto/identidades e actividade comercial | Conforme necessidade de análise | Loja externa de E2 não corresponde automaticamente à unidade SEGI; operador não significa administrador | Sim, ID/nome usado quando documentado |
|
||||
| Telefone, email, website e apoio ao cliente | Cadastros/configuração empresarial | Se escolhidos para comunicação/apresentação | Não exigir como dados fiscais por suposição; não copiar contactos de exemplos | Sim, se fizerem parte do documento fixado |
|
||||
| Logótipo e elementos visuais | Identidade visual configurada | Se usados na representação | Sem alterar significado/tipo; distinguir marca e denominação legal | Versão/activo utilizado, se renderizado |
|
||||
| Capital social e outros dados institucionais | Cadastro validado do emitente | Se aplicáveis e escolhidos/exigidos | Obrigatoriedade e actualidade por validar; não usar valor de E2 como configuração | Sim, se apresentados |
|
||||
| Dados bancários, entidade/referência e instruções de pagamento | Configuração própria autorizada | Quando forem apresentadas instruções | Titularidade, moeda, finalidade e controlo de acesso; não importar contas/referências dos exemplos nem pedir credenciais | Sim, dados comunicados naquele documento; segredos excluídos |
|
||||
| Valor por extenso | Derivado do valor e moeda apresentados | Se adoptado ou exigido após validação | Concordância com montante, moeda, língua e precisão; não é valor independente editável | Sim, se apresentado |
|
||||
| Observações | Registo autorizado ligado à operação | Se necessário | Não substituir campos estruturados, fundamento fiscal ou decisão; limitar informação pessoal | Sim, texto fixado no documento |
|
||||
| Extracto: documentos, movimentos, saldo anterior/actual | Consulta derivada de origens e afectações | Se for incluído como informação adicional | Data de corte, sinais, moeda e estados; linhas positivas/negativas de E2 não são prova do plano contabilístico nem novos recebimentos | Sim, se incorporado na representação; não substituir origens |
|
||||
| Carga/descarga, local e hora | Operação logística, se existir | Só actividade com necessidade identificada | Não impor a serviços por aparecer no template E3; não presumir entrega efectiva | Sim, se utilizados |
|
||||
| Assinatura, carimbo, recepção do documento e anexos | Evidência específica, não sessão de login | Se existir procedimento aprovado | Distinguir recepção do papel, autorização, recebimento financeiro e assinatura válida; retenção/acesso por aprovar | Referência e metadados da evidência; original protegido |
|
||||
| QR, portal do cliente, publicidade e rodapé comercial | Configuração de apresentação | Opcional, se autorizado | QR pode ser ligação/instrução, não prova de pagamento; nenhum fornecedor/portal escolhido nesta revisão | Versão do conteúdo/activo, se apresentado |
|
||||
| Etiquetas analíticas (actividade, centro de custo, projecto, canal) | Referências parametrizadas futuras | Só se houver finalidade de gestão aprovada | Vocabulário e âmbito definidos; não inferir contas nem construir dimensões sem necessidade | Sim se usadas para explicar/classificar a operação; alterações futuras versionadas |
|
||||
|
||||
## Preço, imposto e total: significado a explicitar
|
||||
|
||||
O preço de A/B1 é um preço proposto sem modo fiscal aprovado. Esta revisão não o converte retroactivamente em preço com imposto incluído ou acrescido.
|
||||
|
||||
- **Acrescido:** num exemplo artificial com uma só taxa, sem descontos/encargos, base = quantidade × preço sem imposto; imposto = base × taxa; total = base + imposto, sujeito à política de cálculo ainda por validar. E3 mostra 5 814,00 + 930,24 = 6 744,24, compatível aritmeticamente com 16% acrescido. Isso não determina o regime/taxa aplicáveis a outra operação.
|
||||
- **Incluído:** no mesmo caso simplificado, preço bruto = base + imposto; para taxa r, base exacta = bruto ÷ (1 + r), antes da política de arredondamento aprovada. E2 apresenta 2 051,72 + 328,28 = 2 380,00 e explicita imposto incluído. A divisão exacta de 2 380 por 1,16 tem mais casas que as impressas; a imagem não revela o algoritmo, ponto ou modo de arredondamento.
|
||||
- Descontos, múltiplos tratamentos, encargos, adiantamentos, câmbio e eventuais retenções precisam de regras próprias antes de integrar os cálculos. Não inferir a sua aplicabilidade, sinal ou incidência da presença de um campo num modelo.
|
||||
- Guardar valores de entrada, modo, resultados e versões das regras aplicadas. Escala de armazenamento, precisão de cálculo, arredondamento por linha/documento e apresentação são decisões diferentes. Não inferir «duas casas em todos os cálculos» das duas casas impressas.
|
||||
- Nunca somar montantes de moedas distintas nem apresentar uma soma de preços sem moeda como total monetário definitivo. Diferenças de arredondamento devem ser explicáveis segundo regra aprovada, sem ajuste silencioso.
|
||||
|
||||
## Identidade, recebimento e afectação
|
||||
|
||||
Modelo conceptual proposto, sem migração ou implementação nesta etapa:
|
||||
|
||||
1. Cada documento tem ID técnico estável e referência legível contextualizada por empresa, tipo, série e número. A série não é presumida como ano em todos os sistemas. A apresentação de E2 não determina como separar a série FR26 de outros identificadores.
|
||||
2. O recebimento tem identidade própria, moeda, montante, datas, origem/evidência e estado. Um RC/FR liga-se ao acontecimento efectivamente documentado; não cria outro recebimento ao ser impresso, repetido ou importado.
|
||||
3. A afectação tem ID próprio e liga recebimento a documento exacto com montante/moeda. Suportar conceitualmente pagamentos parciais e distribuição por documentos sem duplicação; a cardinalidade legal/operacional de recibos, recebimentos e adiantamentos deve ser aprovada antes de implementar.
|
||||
4. Controlar, conforme política aprovada, soma das afectações por recebimento e saldo elegível do documento, concorrência e idempotência. Repetição de importação/referência não identifica automaticamente a operação sem fonte e âmbito. Excedentes, diferenças cambiais e correcções permanecem pendentes.
|
||||
5. Documento com referência externa ainda não resolvida fica pendente. Em E1, conservar «FT / 2026 / 10» e procurar apenas essa identidade no âmbito certo. Sem FT 10/2026 disponível, não associar FT 11/2026 nem criar uma factura completa fictícia.
|
||||
6. Em FR, ligar explicitamente o componente documental, o recebimento e sua afectação. Se for aprovado um caso de recebimento integral imediato, garantir atomicidade e repetição segura sem duplicar efeitos num recibo separado. A imagem, por si só, não aprova o caso de uso nem comprova reconciliação externa.
|
||||
7. Saldo operacional, evidência de recebimento, emissão fiscal e contabilização são estados distintos. Extracto ou total pendente zero não demonstra reconciliação bancária ou conformidade contabilística.
|
||||
|
||||
## Decisões pendentes
|
||||
|
||||
| Decisão | O que é necessário fechar |
|
||||
| --- | --- |
|
||||
| Fontes legais e responsável pela validação | Regime da empresa, tipos documentais admitidos, operações/períodos abrangidos, fontes oficiais com vigência/artigos e validação fiscal competente |
|
||||
| Campos obrigatórios por tipo/caso | Denominação, NUIT, moradas, identificação de cliente particular/empresa, dados do serviço, textos e eventuais excepções; separar mínimo de rascunho e aptidão para emissão |
|
||||
| Identidade documental e representação | Séries/numeração, atribuição, sequência/lacunas, data/hora, exemplares, duplicados, software/certificação, impressão e arquivo quando aplicáveis |
|
||||
| Preços e descontos | Modo incluído/acrescido por âmbito aprovado, descontos, encargos, incidência, taxas/fundamentos, moeda e arredondamento; não adoptar valores dos exemplos como regra |
|
||||
| Datas e condições | Emissão, vencimento, prazo/convenção de dias, período do serviço e datas de recebimento; tratamento da divergência entre prazo e data sem alteração silenciosa |
|
||||
| Recibo e factura-recibo | Condições de utilização, data, meios/evidências, referência da factura, recebimentos parciais/múltiplos, adiantamentos, excesso e prevenção de dupla documentação |
|
||||
| Gestão e estatísticas | Quais campos adicionais devem existir no primeiro caso de uso, quais aparecem no documento e quais ficam só em consulta; evitar cadastro obrigatório excessivo |
|
||||
| Fotografia e protecção de dados | Conteúdo fixado, versões, retenção/acesso às evidências, elementos visuais e tratamento posterior sem alterar origem; nenhum segredo no histórico |
|
||||
| Permissões futuras | Quem prepara/verifica dados, emite, regista recebimento, afecta ou gere esses poderes; direitos de A/B1 não os concedem; aplicações exigem confirmação própria |
|
||||
| Contabilidade | Plano de contas, reconhecimento, moeda funcional, câmbio, datas/períodos e regras de processamento continuam pendentes; não são resolvidos pelo layout dos exemplos |
|
||||
|
||||
## Próximo incremento pequeno proposto — preparação e verificação documental
|
||||
|
||||
**Proposta para aprovação, sem execução autorizada:** enriquecer apenas os cadastros e a preparação do rascunho com o subconjunto de campos que vier a ser aprovado, e mostrar uma verificação de completude documental separada da confirmação interna B1.
|
||||
|
||||
Antes do prompt de implementação, aprovar: (a) primeiro tipo/caso de uso, propondo FT de serviço pontual; (b) lista exacta de campos e origem, incluindo denominação/morada/identificação fiscal nos casos validados; (c) datas/período/condições necessários; (d) como registar o modo de preço proposto e as pendências de moeda/imposto, sem motor fiscal; (e) permissões de edição desses novos dados, sem herança presumida. Recibos e FR ficam especificados, mas não implementados nesse pequeno incremento.
|
||||
|
||||
Resultado verificável proposto: reutilizar o cliente criado só com nome, completar os dados aprovados uma vez, seleccionar esse cliente num novo rascunho e mostrar «dados por completar», «dados preenchidos, validação pendente» ou outro rótulo aprovado. **Nenhum estado deve dizer «apto para emissão fiscal» enquanto faltarem regras/fontes validadas.** Não emitir, numerar fiscalmente, produzir PDF de factura, receber, afectar valores ou contabilizar.
|
||||
|
||||
Manter os documentos B1 existentes imutáveis; enriquecimento posterior dos cadastros não lhes acrescenta dados. Se for necessária uma fotografia mais rica em operações futuras, especificar nova versão do esquema, compatibilidade e migração aditiva antes de implementar. Não reconstruir ou promover confirmações B1 aceites a facturas.
|
||||
|
||||
Provas futuras desse incremento: reutilização sem duplicação de clientes; campos condicionais sem bloquear o início do rascunho; desconhecido distinto de zero/preenchido; datas distintas; acesso cruzado recusado; fotografia B1 inalterada; nenhuma emissão, novo recebimento ou lançamento. Só preparar o prompt executável depois de aprovado este subconjunto e os direitos correspondentes.
|
||||
@@ -0,0 +1,133 @@
|
||||
# Classificação contabilística do catálogo — proposta do próximo incremento
|
||||
|
||||
**Actualização posterior:** o utilizador autorizou explicitamente a execução do primeiro incremento com as três salvaguardas. A implementação, provas e limites estão em [CATALOGUE_ACCOUNTING_DELIVERY.md](CATALOGUE_ACCOUNTING_DELIVERY.md). As quatro concessões iniciais foram posteriormente confirmadas de forma específica e aplicadas, conforme o relatório. O texto original de proposta abaixo preserva a origem das decisões; não revoga essa autorização posterior nem significa activação de contas/regras reais. A validação do cálculo permanece separada e pendente.
|
||||
|
||||
26 de Outubro de 2026, Africa/Johannesburg. **Apenas especificação para aprovação.** Não escolhe o plano da Tempo Lda, aplica acessos, altera bases, produz lançamentos ou autoriza implementação. A validação do incremento de cálculo continua pendente; esta proposta não o dá por aceite nem altera a sua política. Preservar identidade, A, B1, preparação documental, pré-visualização e histórico.
|
||||
|
||||
## 1. Documento-base e alcance da leitura
|
||||
|
||||
Exemplar fornecido pelo utilizador: `\\Mac\Home\Downloads\29-Plano-de-Contas-BR-Decreto-70-2009-de-22-de-Dezembro.pdf`. Decreto n.º 70/2009, de 22 de Dezembro, BR, I Série, n.º 50, 4.º suplemento; 192 páginas PDF, 856306 bytes. SHA-256: `45C38AED64DE43042ED048586ACCE2EC660B74FC3F8FBCE33D39AAB45C7529E3`.
|
||||
|
||||
Leitura do exemplar histórico fornecido, com extracção textual e conferência visual das páginas PDF 127, 134, 178 e 192, especialmente porque a extracção das colunas desloca códigos e descrições. As referências abaixo usam página PDF contada desde 1 e paginação impressa do BR. O documento é fonte de conteúdo; as instruções nele contidas não ampliam a autorização do utilizador para executar acções.
|
||||
|
||||
Não se apresenta este exemplar de 2009 como consolidação normativa verificada até 2026. A eventual verificação de alterações posteriores fica delimitada à norma que venha a ser activada, antes da activação real; não se repetiu pesquisa fiscal nem se consultou o InvesteMoz nesta etapa.
|
||||
|
||||
| Ref. | Fonte/secção efectivamente lida | Conteúdo relevante e limite |
|
||||
| --- | --- | --- |
|
||||
| D1 | Decreto, arts. 1–3, PDF 1–2, BR 372-(15)–(16) | SCE com dois planos: Título I PGC-NIRF, Título II PGC-PE. Art. 2 define âmbito, transições e opção; art. 3 identifica exclusões sectoriais. Não deduzir plano do nome, NUIT ou designação comercial «pequena empresa» |
|
||||
| D2 | Decreto, art. 6 e art. 7, PDF 2, BR 372-(16) | Datas históricas: PGC-NIRF grandes desde exercício iniciado em 01/01/2010; médias e PGC-PE desde 01/01/2011; regra para ano económico não civil e transição. Não usar estas datas como aprovação do plano actual da Tempo Lda |
|
||||
| D3 | Título I, cap. 1.1, §6, PDF 3, BR 372-(17); cap. 1.5, PDF 134, BR 372-(148) | Quadros sintético/detalhado, adaptação às entidades; conta 7.2 Prestação de serviços e subcontas oficiais, incluindo 7.2.1 e 7.2.6. Não inventar desdobramentos oficiais nem tratar todos os nós como contas movimentáveis |
|
||||
| D4 | Título I, cap. 1.2, §20, PDF 5, BR 372-(19) | Base do acréscimo: acontecimento e período, distintos de recebimento/pagamento |
|
||||
| D5 | Título I, NCRF 28, §§3–7 e §§8–16, PDF 126–127, BR 372-(140)–(141) | Âmbito/exclusões, mensuração, componentes identificáveis; prestação de serviços §§14–16 depende de fiabilidade, benefícios, fase de acabamento e custos. «Pontual» não dispensa avaliar condições; locações/construção têm tratamento próprio |
|
||||
| D6 | Título II, cap. 2.1, §§2–4, PDF 168, BR 372-(182) | PGC-PE tem regras simplificadas próprias; complemento referido ao Quadro Conceptual e Glossário do PGC-NIRF. Não importar automaticamente todas as NCRF como se integrassem o PGC-PE |
|
||||
| D7 | Título II, cap. 2.2, §16, PDF 169, BR 372-(183) | Base do acréscimo no corpo do texto. O índice da página anterior apresenta numeração diferente; referência aqui é ao parágrafo efectivamente impresso, não apenas ao índice |
|
||||
| D8 | Título II, cap. 2.4, PDF 178, BR 372-(192); cap. 2.6, PDF 191–192, BR 372-(205)–(206) | 7.2 Prestação de serviços: trabalhos/serviços ligados aos objectivos da empresa; 7.5 rendimentos suplementares e 7.6 outros rendimentos exigem distinguir natureza. 7.2.1 descreve expurgo de IVA de serviços registados com imposto incluído: não fixa taxa nem autoriza esse modo no cálculo actual |
|
||||
|
||||
## 2. Base existente e fronteiras
|
||||
|
||||
Revisão por leitura de `ServiceWorkflow`, `ServicePermissions` e da migração de A: `a_services` é catálogo da empresa, reutilizado entre unidades, com ID, nome, descrição e versão/histórico. Prestações e rascunhos pertencem à unidade autorizada e guardam referências/valores de origem. Categorias contabilísticas, plano empresarial e associações contabilísticas não estão implementados no catálogo actual. Não recriar serviços, clientes, unidades, histórico ou mecanismos de autorização.
|
||||
|
||||
Começar pelo serviço pontual já suportado. O próximo incremento proposto apenas permite preparar, validar e consultar a associação contabilística do catálogo; não implementa reconhecimento ou lançamentos. Mercadorias ficam previstas pelo tipo de item e papéis contabilísticos futuros, sem novos cadastros duplicados, stock, compras, inventário ou custo das vendas nesta entrega.
|
||||
|
||||
Três associações independentes:
|
||||
|
||||
| Dimensão | Pergunta | Saída proposta | O que não determina |
|
||||
| --- | --- | --- | --- |
|
||||
| Classificação contabilística | Qual a natureza económica e quais contas/papéis são adequados? | Plano/versão, categoria, regra e conta aprovada para cada papel | Taxa/tratamento de IVA ou data de reconhecimento |
|
||||
| Enquadramento fiscal | Qual o tratamento da empresa/operação e a taxa aplicável? | Perfil fiscal próprio, fundamento, âmbito e vigência | Conta de rendimentos ou momento de reconhecimento contabilístico |
|
||||
| Reconhecimento | Que acontecimento e evidência satisfazem as condições do normativo? | Avaliação própria de condições, mensuração e período | Não se conclui pela existência de factura, B1 ou recebimento |
|
||||
|
||||
Não assumir 16% para serviços. Não extrair taxa de conta, categoria contabilística, palavras no nome ou código `7.2.1`. O cálculo exacto e a truncagem operacional permanecem nos seus perfis/políticas já delimitados; este desenho não os altera e não escolhe montante de lançamento a partir de um total documental proposto.
|
||||
|
||||
## 3. Proposta técnica de parametrização
|
||||
|
||||
Estas entidades são conceitos propostos, não tabelas criadas ou migrações autorizadas.
|
||||
|
||||
| Elemento | Informação mínima | Âmbito e regra |
|
||||
| --- | --- | --- |
|
||||
| Referência de plano | Identidade PGC-NIRF/PGC-PE, versão documental, hash/fonte, estrutura oficial e estado da verificação | Definição normativa reutilizável, sem partilhar configurações empresariais; códigos sempre qualificados pelo plano/versão, nunca só pelo texto do código |
|
||||
| Plano adoptado pela empresa | Empresa, plano/versão, fundamento, período de aplicação, responsável, decisão e prova | Uma selecção explícita validada; sem escolha automática. Mudança cria versão e exige revisão das associações, sem converter o passado |
|
||||
| Conta empresarial | Plano/versão, código oficial ou desdobramento empresarial distinguido, descrição, pai, natureza, papel, possibilidade de movimento e vigência | Conta pertence à configuração da empresa; conta agregadora não se torna movimentável por omissão. Desdobramento novo exige validação de compatibilidade, sem ocupar código reservado |
|
||||
| Categoria de catálogo | ID, empresa, nome, natureza inicial `service`; previsão de `goods` futura; versão | Reutilizada entre unidades da mesma empresa. Classificação analítica do catálogo não é automaticamente conta nem tratamento de IVA |
|
||||
| Associação/regra | Serviço existente ou categoria, versão da regra, plano/conta para papel `service_revenue`, condições/exclusões, vigência e prova | Específica da empresa. Regra do serviço pode substituir a categoria apenas por decisão explícita validada; sem preferência silenciosa entre regras concorrentes |
|
||||
| Decisão de validação | Proponente, responsável autorizado, data, motivo, evidência, versão aprovada e início de aplicação | Rascunho → validada/activável ou recusada; alteração origina nova versão. Aprovação de classificação não aprova fiscalidade ou reconhecimento |
|
||||
| Resolução por operação futura | ID e versão do serviço/categoria/associação, plano/conta, papel, data de referência, responsável e estado de excepção | Conservar o que foi efectivamente usado, não recalcular pela regra actual; fotografia própria fora de B1 existente |
|
||||
|
||||
Papéis permitem evoluir para rendimentos de mercadorias, inventário e custo, mas nenhuma conta ou regra desses papéis será activada agora. Não criar um motor geral de scripts contabilísticos: condições iniciais são dados delimitados (empresa, tipo serviço, categoria/serviço, papel, intervalo de vigência e exclusões). Fórmulas executáveis, débitos/créditos e contas de contrapartida ficam fora deste incremento.
|
||||
|
||||
### Resolução e vigência propostas
|
||||
|
||||
1. Validar contexto, empresa e acesso; reutilizar ID/versão do serviço. Não permitir associação a categoria/conta/plano de outra empresa.
|
||||
2. Exigir plano empresarial aprovado e uma data de referência explicitamente definida para a classificação. A data é dado próprio, não a data do reconhecimento, exigibilidade de IVA ou data do computador por omissão. Se faltar, apresentar candidato sem o declarar aplicável.
|
||||
3. Só uma excepção específica por serviço **aprovada, vigente na data de referência e compatível** pode substituir a regra da categoria. Proposta pendente, recusada ou com vigência futura não substitui a regra actualmente válida. Na ausência de excepção aplicável, resolver pela regra da categoria aprovada e vigente. A herança deve estar aprovada e visível. Duplicidade, sobreposição ou incompatibilidade geram conflito explícito; não escolher silenciosamente nem ocultar o conflito com uma regra alternativa.
|
||||
4. Validar papel, estado da conta e versão do plano. Conta agregadora ou desdobramento não aprovado não permite resolução como pronta.
|
||||
5. Mostrar conta/regra/fontes e motivo da sugestão. Guardar a decisão e versões na futura operação por acção autorizada, sem produzir lançamento ou concluir reconhecimento.
|
||||
|
||||
O próximo incremento pequeno propõe um único nível de categorias e associação explícita de cada serviço a uma categoria, com excepção específica versionada por serviço. Hierarquias complexas e regras por unidade só entram mediante necessidade futura demonstrada. A classificação da empresa não concede acesso a operações de unidades não autorizadas.
|
||||
|
||||
**Mudança de categoria com efeito contabilístico:** a ligação do serviço à categoria faz parte da classificação versionada. Se uma mudança afectar a conta herdada ou outra componente da classificação, exige proposta, vigência e validação por Samira antes de produzir efeito. A edição corrente do catálogo não pode activar essa mudança, substituir a ligação aprovada ou contornar a validação. Até à entrada em vigor da nova versão aprovada, preserva-se a classificação aplicável anterior e mostra-se a proposta separadamente. As operações históricas conservam as versões utilizadas.
|
||||
|
||||
**Subconjunto inicial de contas:** importar/configurar apenas as referências PGC-NIRF necessárias ao serviço pontual e ao papel de rendimento aprovado, com fonte, versão e hierarquia necessárias identificadas. Não carregar todo o plano nem criar contas ou desdobramentos por suposição. Categorias e associações pertencem à empresa e são reutilizáveis entre unidades; essa reutilização não amplia permissões sobre operações de outras unidades.
|
||||
|
||||
## 4. Automação após validação e excepções
|
||||
|
||||
| Situação | Preenchimento possível após validação | Intervenção/pendência |
|
||||
| --- | --- | --- |
|
||||
| Serviço com regra única vigente aprovada | Reutilizar categoria, papel, conta e versões; explicar origem; conservar a resolução | Não atribuir IVA nem reconhecer rendimento por este preenchimento |
|
||||
| Novo serviço numa categoria com herança aprovada | Sugerir associação da categoria, indicando que é herança | Se a actividade/natureza não coincidir, exigir revisão; o nome sozinho não comprova adequação |
|
||||
| Conta/plano em falta, expirado, substituído ou sem fundamento | Mostrar informação já conhecida e motivo do bloqueio | Responsável resolve antes de marcar a classificação aplicável |
|
||||
| Serviço entre actividade principal, rendimento suplementar, locação, construção ou operação composta | Mostrar alternativas e condições documentais | Rever natureza/âmbito; não escolher 7.2 por ser chamado «serviço» |
|
||||
| Falta de evidência de execução, fiabilidade ou período | Conservar classificação aprovada do catálogo | Reconhecimento continua pendente, mesmo com factura/B1/pagamento |
|
||||
| Regra alterada após preparar operação | Assinalar nova versão disponível, sem substituir a consultada | Revisão explícita; versão anterior identificada como histórica, sem reescrever lançamentos ou B1 |
|
||||
| Operação anterior sem classificação preservada | Mostrar «não capturada» | Eventual classificação posterior será decisão nova datada e auditada, nunca fotografia retrospectiva inventada |
|
||||
| Perfil fiscal ausente ou diferente entre operações do mesmo serviço | Conservar a classificação contabilística adequada | IVA fica pendente ou usa perfil fiscal independentemente validado; nenhuma taxa herdada da conta |
|
||||
|
||||
## 5. Exemplo sintético, sem lançamentos
|
||||
|
||||
Empresa Exemplo, Unidade de Teste, serviço existente `S-TESTE` — «Apoio administrativo pontual». Categoria analítica proposta «Serviços da actividade normal». Não são dados da Tempo Lda.
|
||||
|
||||
Para comparar alternativas, considerar separadamente um cenário com PGC-NIRF e outro com PGC-PE. Ambos mostram **7.2 — Prestação de serviços** nos quadros lidos, mas são referências distintas: `(PGC-NIRF, versão do exemplar, 7.2)` e `(PGC-PE, versão do exemplar, 7.2)`. Não seleccionar um deles nem declarar 7.2 movimentável sem aprovação do plano e da conta empresarial concreta. Se necessário desdobramento empresarial, código e compatibilidade ficam por validar; não inventar um código oficial.
|
||||
|
||||
Depois de um responsável validar a natureza de actividade normal, plano, conta e regra de categoria `R-SERVICO-v1`, o sistema pode preencher uma **proposta de classificação** para o papel de rendimento. Se depois surgir `R-SERVICO-v2`, a operação que utilizou v1 conserva v1 e mostra a alteração; nova operação só resolve v2 na vigência adequada. Não alterar B1 nem rascunhos antigos automaticamente.
|
||||
|
||||
No cenário PGC-NIRF, a análise de reconhecimento teria de avaliar as condições dos §§14–16 da NCRF 28, incluindo fase e custos, não apenas «concluído» ou «facturado». No cenário PGC-PE, usar as bases próprias (cap. 2.2, §16) e validar o tratamento específico; não aplicar a NCRF 28 por simples identidade de código de conta.
|
||||
|
||||
Mesmo serviço/conta pode surgir com enquadramentos fiscais distintos conforme a operação: o exemplo deixa o perfil IVA por validar. Não inclui taxa, cálculo, valor contabilizado, débitos/créditos ou lançamento. Uma confirmação interna e um eventual recebimento não resolvem as pendências de reconhecimento.
|
||||
|
||||
## 6. Próximo incremento pequeno proposto
|
||||
|
||||
Só após aprovação: preparar configuração empresarial do plano validado, selecção de contas autorizadas para o papel de rendimento do serviço pontual, categorias simples e associações versionadas do catálogo. Reutilizar os serviços existentes e apresentar uma resolução explicável, com pendências e histórico. A captura da versão utilizada numa operação deve ter contrato definido agora, mas a sua implementação concreta exige delta próprio que preserve B1 e os modelos actuais; nenhuma alteração de esquema está autorizada por esta especificação.
|
||||
|
||||
Ecrãs propostos: (1) plano e contas da empresa, com fundamento/versão; (2) categorias e associação do serviço existente, com proposta e validação; (3) consulta da resolução e histórico/excepções. Sem ecrã de diário, lançamentos, stock, compras ou fecho. Não construir todo o plano/motor de reconhecimento nesta entrega.
|
||||
|
||||
Critérios de aceitação futuros: plano não presumido; serviço existente reutilizado; conta e plano da empresa correcta; leitor não altera; proponente não aprova sem direito próprio; herança/excepção visíveis; ambiguidades e falta de dados negadas por omissão; regra alterada não reescreve versões antigas; IVA nunca derivado da conta; factura/B1/pagamento nunca reconhecem automaticamente; B1 intacto; demonstração só sintética em ambiente isolado. Testes não executados nesta etapa documental.
|
||||
|
||||
## 7. Decisões pendentes, reduzidas
|
||||
|
||||
### Confirmações posteriores do utilizador — 26/10/2026
|
||||
|
||||
- **Plano actualmente utilizado pela Tempo Lda: PGC-NIRF**, confirmado expressamente pelo utilizador. Não foi escolhido por inferência do nome ou dimensão comercial. Esta informação substitui a pendência de identificar qual dos dois planos é utilizado; não comprova, por si só, a edição/consolidação normativa, o período de adopção ou a configuração concreta de contas da empresa.
|
||||
- **Responsável pela validação dos enquadramentos contabilísticos: Samira**, indicada pelo utilizador. A indicação de responsabilidade não aplica concessões, não altera a conta existente nem aprova automaticamente contas ou associações propostas. A conta exacta e os direitos/âmbitos serão apresentados quando se fechar a matriz de acessos; não se infere identificação por nome.
|
||||
- **Separação de funções confirmada:** a consulta actualmente concedida a Samira não inclui validação contabilística. O futuro poder de validar será próprio, com acções e âmbito delimitados e confirmação específica antes da aplicação. Não implicará automaticamente edição de propostas, edição do catálogo, administração ou gestão de acessos. A proposta deve permitir validar ou recusar uma versão identificada sem modificar o seu conteúdo; uma correcção exige nova proposta por quem tenha o direito correspondente.
|
||||
- Mantém-se a proposta de categoria como regra-base, excepção explícita por serviço e vigência versionada, preservando operações históricas. A identificação de quem propõe e de quem apenas consulta continua pendente. A validação do cálculo permanece separada.
|
||||
|
||||
### Desenho fechado pelo utilizador — confirmação posterior
|
||||
|
||||
Esta confirmação substitui as pendências anteriores relativas a proponente, herança e correcções: **Osmane prepara; Samira valida ou recusa uma versão identificada, sem editar o seu conteúdo. A categoria fornece a regra-base, com excepções explícitas por serviço e vigência definida. Correcções geram nova versão, sem reescrever o histórico.** O plano actualmente utilizado é PGC-NIRF, conforme confirmação anterior.
|
||||
|
||||
O desenho está fechado para preparar o prompt de implementação; não é, por si só, autorização de implementação ou de aplicação de acessos. As novas permissões continuam sujeitas a apresentação concreta de acções, contas e âmbitos e confirmação específica antes da aplicação. Validar não concede edição, administração ou gestão de acessos. A consulta actual permanece inalterada. A validação do cálculo mantém-se separada e pendente.
|
||||
|
||||
Salvaguardas posteriores incorporadas ao desenho fechado: apenas excepções aprovadas/vigentes/compatíveis têm precedência; mudança de categoria que afecte classificação exige versionamento, vigência e validação; categorias/associações empresariais não concedem acesso entre unidades; catálogo inicial limitado ao subconjunto necessário do PGC-NIRF com fonte e versão. Estas salvaguardas devem integrar o prompt de execução sem reabrir as decisões anteriores e sem aplicar concessões nesta etapa.
|
||||
|
||||
### O que resta delimitar
|
||||
|
||||
1. **Versão e configuração do PGC-NIRF:** identificar edição/consolidação, período de adopção e contas/desdobramentos efectivamente utilizados. Confirmar apenas fundamentos e alterações relevantes antes da activação; não voltar a pedir a escolha PGC-PE/PGC-NIRF já resolvida.
|
||||
2. **Procedimento de validação por Samira:** delimitar a evidência e o procedimento para validar contas, desdobramentos e associações. Não voltar a perguntar quem será responsável, nem inventar cargo profissional ou obrigação de revisão por duas pessoas.
|
||||
3. **Aplicação concreta dos acessos:** funções já definidas — Osmane prepara; Samira valida ou recusa. Direitos separados por empresa para consultar, propor/editar rascunho e validar/recusar uma versão identificada. Identificadores candidatos `catalogue_accounting.view`, `.propose`, `.approve`; apresentar contas existentes, acções e âmbitos concretos para confirmação específica antes de conceder. `.approve` não inclui `.propose`, edição, administração ou gestão de acessos. A consulta actual de Samira permanece inalterada e não concede validação. Não inferir direitos de `services.edit/manage`, de permissões fiscais ou de configuração visual; a consulta contabilística específica também não se presume a partir da consulta actual de outras áreas.
|
||||
4. **Detalhe de vigência para execução:** herança por categoria, excepção explícita por serviço, vigência definida e novas versões para correcções já estão fechadas. Resta explicitar no prompt os dados/evidências de referência usados para resolver a vigência, sem voltar a submeter esse desenho a decisão. O recorte de catálogo não aprova política de reconhecimento ou geração de lançamentos.
|
||||
|
||||
Já resolvido e não submetido de novo: catálogo da empresa reutilizável entre unidades; tenant/empresa/unidade distintos; classificação contabilística separada de IVA e reconhecimento; valores exactos, desconhecido diferente de zero e histórico preservado. A validação do cálculo entregue permanece independente e pendente.
|
||||
|
||||
## 8. Alterações realizadas nesta etapa
|
||||
|
||||
Criado apenas este documento de proposta e materiais temporários de leitura em `storage/app/`, fora dos ficheiros de aplicação. PDF original preservado. Não se alteraram código, bases, permissões ou entregas aceites; não foram executados testes, migrações, cálculos ou lançamentos. Nenhuma implementação ou publicação foi iniciada.
|
||||
@@ -0,0 +1,101 @@
|
||||
# Classificação contabilística do catálogo — entrega local
|
||||
|
||||
## Aceitação funcional e encerramento
|
||||
|
||||
Em 26/10/2026, o utilizador informou que entrou na aplicação e verificou o percurso. À pergunta de confirmação da aceitação funcional para registar o encerramento e criar o checkpoint Git local, respondeu **«sim»**. Fica aceite e encerrado este primeiro incremento, no âmbito entregue e com os limites documentados abaixo. O checkpoint preserva a implementação e as dependências locais necessárias, sem credenciais, bases ou dados operacionais locais.
|
||||
|
||||
A validação do cálculo fiscal permanece **separada e pendente**. A presença do seu código no checkpoint preserva a base técnica existente; não constitui aceitação fiscal, activação de perfil real, autorização de emissão ou de lançamentos. Nenhum avanço para outro incremento ou publicação foi autorizado.
|
||||
|
||||
O texto de entrega seguinte descreve o estado técnico anterior à aceitação; esta secção regista a confirmação posterior, sem alterar as provas.
|
||||
|
||||
26 de Outubro de 2026, Africa/Johannesburg. Implementado apenas o primeiro incremento autorizado, com as três salvaguardas de [CATALOGUE_ACCOUNTING_CLASSIFICATION_SPEC.md](CATALOGUE_ACCOUNTING_CLASSIFICATION_SPEC.md). Não constitui aceitação pelo utilizador; a validação do cálculo permanece separada e pendente.
|
||||
|
||||
## Funcionalidade entregue
|
||||
|
||||
- Propostas imutáveis e versionadas de plano PGC-NIRF, contas empresariais, categorias/regras-base, ligações de serviços a categorias e excepções explícitas por serviço. Reutiliza `a_services`; não criou outro catálogo de serviços.
|
||||
- Guardar proposta em preparação, submeter uma versão fixa e validar ou recusar com motivo. Validação não edita conteúdo. Correcção gera outra versão, com referência à anterior, e exige nova submissão/decisão; não herda aprovação. Versão ultrapassada não pode ser submetida ou decidida como se fosse a actual.
|
||||
- Vigência com início explícito e termo opcional inclusivo. Revisão futura ou pendente não substitui regra válida. Intervalos sobrepostos exigem substituição explícita da versão aprovada; conflitos não escolhem automaticamente o maior número de versão. Substituição aprovada termina o intervalo anterior desde o início da nova vigência, sem alterar a linha histórica; a versão substituída não reaparece silenciosamente quando a substituta termina.
|
||||
- Categoria fornece regra-base. Só excepção aprovada, vigente e compatível a substitui. Uma excepção vigente com dependência incompatível mostra pendência/conflito, sem fallback silencioso. Ausência de excepção aplicável usa a categoria aprovada vigente. Mudança de categoria é proposta do tipo ligação, não campo editável pela API corrente de serviços.
|
||||
- Consulta por serviço e data explícita, com origem, conta, versões e pendências. Plano ou conta incompatíveis/agregadores não produzem classificação pronta. Não presume data do computador, taxa de IVA ou reconhecimento.
|
||||
- Resoluções append-only por operação autorizada, com serviço/versão, regra/categoria/conta/plano/decisão e data de referência preservados. A gravação exige a revisão da classificação consultada e a versão da operação; mudança entretanto gera `409`, sem substituir silenciosamente o resultado. Não altera rascunho, fotografia B1 ou cálculo.
|
||||
- Histórico consultável apenas com consulta contabilística e acesso à operação/unidade actual. Não reconstrói classificação nos registos antigos; histórico vazio significa ausência de captura. Rascunho B1 confirmado recusa captura retroactiva.
|
||||
|
||||
Não há lançamentos, débitos/créditos, reconhecimento automático, contas de contrapartida, stock, compras, inventário ou fecho. Perfil/tratamento de IVA continua separado da classificação contabilística. Não foram alterados o núcleo de cálculo, a sua política ou a pré-visualização fiscal.
|
||||
|
||||
## Fonte e configuração inicial
|
||||
|
||||
Decreto n.º 70/2009, exemplar fornecido, cap. 1.5, PDF 134 / BR 372-(148), com hierarquia 7 — Rendimentos e ganhos → 7.2 — Prestação de serviços. Versão de referência: `Decreto70/2009-PGC-NIRF-PDF134-BR372(148)`; SHA-256 do PDF `45C38AED64DE43042ED048586ACCE2EC660B74FC3F8FBCE33D39AAB45C7529E3`.
|
||||
|
||||
Esse é o subconjunto documental inicial, apresentado como referência agregadora não movimentável. Não se importou o plano inteiro. Desdobramento empresarial só é proposto com código, designação, evidência e aprovação; o sistema não inventa uma conta para a Tempo Lda e recusa usar os códigos reservados 7.2/7.2.1/7.2.6 como novos desdobramentos empresariais. A versão do exemplar de 2009 não é apresentada como consolidação normativa actual verificada. A matriz original identifica também os fundamentos de separação de classificação, reconhecimento e IVA; não se repetiu investigação nem se consultou o portal nesta implementação.
|
||||
|
||||
O plano actualmente utilizado pela empresa foi confirmado como PGC-NIRF, mas datas de adopção, contas empresariais e enquadramentos concretos serão propostos por Osmane e validados/recusados por Samira no circuito. Não foram criadas propostas ou aprovações reais para preencher essas lacunas por suposição.
|
||||
|
||||
## Acessos confirmados e efectivamente aplicados
|
||||
|
||||
Após conferência das contas existentes e confirmação específica do utilizador, aplicadas exactamente quatro concessões na Tempo Lda, tenant 1/empresa 1, sem unidade:
|
||||
|
||||
| Conta existente | Direitos novos | Acções |
|
||||
| --- | --- | --- |
|
||||
| ID 1 — Osmane Nala | `catalogue_accounting.view`, `catalogue_accounting.propose` | Consultar, preparar novas versões, submeter e guardar resoluções nas operações de unidades já autorizadas |
|
||||
| ID 2 — Samira Nal | `catalogue_accounting.view`, `catalogue_accounting.approve` | Consultar e validar/recusar versões submetidas, sem editar/preparar |
|
||||
|
||||
Nenhum `.approve` foi dado a Osmane, nenhum `.propose` a Samira; não se acrescentaram direitos de unidade, gestão de acessos, emissão ou reconhecimento. Todos os direitos anteriores permaneceram iguais. [Verificação posterior das concessões](proofs/accounting-access-results.json).
|
||||
|
||||
O código aplica permissões, não privilégios por nome/email. A ferramenta local de concessão recebe IDs explícitos e requer pertenças/direitos de consulta existentes; não cria contas ou pertenças. Novas concessões continuam a exigir apresentação e confirmação específicas. A gestão geral existente não ganhou automaticamente capacidade de delegar estes novos direitos.
|
||||
|
||||
## Migração e preservação
|
||||
|
||||
Delta apresentado antes de aplicar: `2026_10_26_040000_create_catalogue_accounting.php` cria `ca_proposals`, `ca_submissions`, `ca_decisions`, `ca_resolutions`, `ca_commands`, relações compostas, unicidades, checks e triggers. A restrição de âmbito de `permission_grants` foi alargada para aceitar os três identificadores empresariais, sem os conceder na migração.
|
||||
|
||||
Aplicada primeiro em `sgf_tempo_test`, depois em **sgf_tempo_dev** pelo wrapper e proprietário separados. Verificado que era a única migração pendente. Sem reset/fresh de desenvolvimento. Conteúdos existentes e ficheiros do cálculo foram comparados por hashes; permaneceram iguais. As cinco tabelas novas em desenvolvimento continuam com **zero linhas**, mesmo após os quatro acessos. [Preservação da migração](proofs/accounting-dev-preservation.json); [preservação após concessões](proofs/accounting-access-results.json).
|
||||
|
||||
Relações compostas e guardas de inserção recusam referências de outra empresa e capturas de outra unidade/operação. Triggers append-only impedem actualização, transferência em massa e apagamento de propostas, decisões, comandos e resoluções. Submissões/decisões também verificam versão e transição na base. Não se declara isso como RLS ou protecção contra administrador da base. Auditoria e comandos são transaccionais; alterações autorizadas são serializadas pelo bloqueio da empresa, com revalidação de contexto/permissões. O contexto do navegador não constitui autorização.
|
||||
|
||||
## Testes, compilação e navegador
|
||||
|
||||
Suite dirigida inicial: **61 testes / 783 asserções**, passada, cobrindo classificação, A, B1, identidade, isolamento e guardas. Após a protecção adicional da revisão consultada, repetidos apenas os testes afectados de classificação: **9 testes / 397 asserções**, passados. Compilação final Vite 8.3.5 passou. Não se alteraram ferramentas ou dependências, não se repetiu o cálculo fiscal como nova validação.
|
||||
|
||||
Cobertura nova inclui separação de funções; recusa e nova versão; submissão/decisão antigas; repetição de comandos com conflito de conteúdo; herança e excepções pendentes/recusadas/futuras; início de vigência; sobreposição e substituição explícita; mudança de categoria sem bypass pela edição do catálogo; conta agregadora; conta/plano incompatível; referências alheias; revogação no pedido seguinte; isolamento de unidades; transferência em massa e inserção directa cruzada; B1 preservado; data em falta; captura de classificação diferente da consultada recusada. Não houve implementação ou geração de lançamentos.
|
||||
|
||||
Prova concorrente adicional: **dois processos PHP sobrepostos**, um aprova e outro recusa a mesma versão. Um recebeu 200 e o outro 409; existe uma única decisão. [Recibo da concorrência](proofs/accounting-concurrency.json).
|
||||
|
||||
No Edge, instância `http://127.0.0.1:8001`, ligada apenas a `sgf_tempo_test`, sessão/cache isolados e CSRF activo. **Login real com duas identidades sintéticas distintas**, não actingAs como substituto da demonstração. Não se usaram contas reais ou operações fictícias na Tempo Lda. [Registo da observação](proofs/accounting-browser-results.json).
|
||||
|
||||
Percurso observado:
|
||||
|
||||
1. Login do preparador sintético → Empresa Horizonte — Demonstração → Unidade Central — Demonstração → **Classificação contabilística**.
|
||||
2. Na categoria sintética aprovada, **Preparar nova versão** → alterar designação/condições → indicar início 01/11/2026 → seleccionar explicitamente a versão aprovada substituída → indicar fundamento → **Guardar proposta em preparação** → **Submeter versão**. Não havia controlos de validação para esse utilizador.
|
||||
3. Consultar o serviço para 01/11/2026 enquanto a nova proposta aguardava validação: continuou a resolver a categoria v1 aprovada.
|
||||
4. Sair; login da identidade sintética validadora → mesma empresa/unidade → consultar conteúdo fixo → motivo → **Validar esta versão**. Recusar outra proposta submetida com motivo. Não havia formulário de preparação, botão de correcção ou captura para a validadora. [Prova visual](proofs/accounting-validation.png).
|
||||
5. Consultar o serviço em 31/10/2026: categoria v1. Em 01/11/2026: categoria v2 aprovada. Na secção de operações autorizadas, carregar a prestação sintética → **Consultar histórico preservado**: conservava a categoria v1 e referências originais, mesmo após a aprovação de v2. [Histórico preservado](proofs/accounting-history.png).
|
||||
6. Sair. A instância de prova foi encerrada; os testes seguintes só recriaram `sgf_tempo_test`. A aplicação normal manteve a sua ligação.
|
||||
|
||||
A guarda final de revisão foi validada por testes HTTP de aplicação: consultar, aprovar outra regra, tentar guardar a revisão antiga → 409; consultar novamente e guardar → sucesso; repetir o comando → mesmo resultado sem duplicação. A prova visual anterior continua a documentar preparação/decisão/vigência/histórico; não se atribui ao navegador uma demonstração posterior de gravação com o novo token de revisão.
|
||||
|
||||
## Utilização normal
|
||||
|
||||
Actualizar a página/sessão após as concessões e seleccionar Tempo Lda. O menu **Classificação contabilística** aparece para ambos. Não é necessário seleccionar unidade para preparar/validar classificações empresariais; é necessária unidade autorizada para consultar ou guardar resoluções de operações.
|
||||
|
||||
Osmane prepara primeiro a versão documental/período do plano e submete; Samira confere e decide. Depois podem ser propostos e validados a conta empresarial documentada, categoria e ligação ao serviço. O sistema não resolve uma classificação por omissão enquanto faltarem aprovações compatíveis. Se a conta de movimento ou a aplicabilidade estiverem por confirmar, conservar pendência; não usar a referência 7.2 como substituto automático.
|
||||
|
||||
Para operação autorizada, escolher serviço e data → **Consultar classificação**. Para preservar a resolução, carregar operações da unidade, seleccionar a operação e **Guardar resolução na operação**. Se versão ou regras mudaram, consultar/rever antes de guardar; não tentar sobrescrever a história. Samira consulta resoluções sem receber poder de captura ou edição pela validação.
|
||||
|
||||
Ferramentas mantidas por caminhos explícitos no wrapper:
|
||||
|
||||
```powershell
|
||||
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/sgf.ps1 test --stop-on-failure --filter=CatalogueAccountingTest
|
||||
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/sgf.ps1 npm run build
|
||||
```
|
||||
|
||||
Repetir a demonstração apenas por fluxo de testes: parar `scripts/browser-proof.ps1 stop` antes de recriar testes; partir de base de testes vazia produzida pelos testes; `scripts/browser-proof.ps1 start`, seguido de `sgf.ps1 php scripts/accounting-fixture.php --env=testing`. Preparadores recusam dados existentes e não os apagam para prosseguir. `sgf.ps1 php scripts/accounting-concurrency.php --env=testing` demonstra decisões concorrentes. As credenciais sintéticas ficam no ficheiro local protegido já usado pelo preparador e não são publicadas. A verificação de portas não termina processos de outro projecto. O uso de Bypass é apenas no processo PowerShell, sem alteração global.
|
||||
|
||||
## Ficheiros deste incremento e limites
|
||||
|
||||
- Núcleo: `app/Modules/Services/CatalogueAccounting.php`, `Http/CatalogueAccountingController.php` e rotas.
|
||||
- Interface: `resources/js/CatalogueAccountingWorkspace.jsx`, integração/legendas em `app.jsx` e estilos próprios em `app.css`.
|
||||
- Migração: `2026_10_26_040000_create_catalogue_accounting.php`.
|
||||
- Testes: `tests/Feature/CatalogueAccountingTest.php`, `tests/Support/CatalogueAccountingFixture.php`.
|
||||
- Ferramentas/provas: `scripts/accounting-fixture.php`, `accounting-concurrency.php`, `accounting-concurrency-worker.php`, `accounting-preservation.php`, `catalogue-accounting-access.php` e `docs/proofs/accounting-*`.
|
||||
- Documentação: especificação, este relatório, AGENTS e README. Alterações preexistentes foram preservadas; nenhum checkpoint Git foi criado sem pedido.
|
||||
|
||||
Limites: referência histórica fornecida não comprova consolidação normativa actual; contas, datas e regras reais ainda precisam de propostas e validação de Samira. Apenas PGC-NIRF e o papel inicial de rendimento de serviço; sem motor de reconhecimento, diários, contrapartidas, stock/compras ou gestão geral de novas concessões. Sem lançamentos, alteração fiscal, publicação ou avanço para outro incremento. Este relatório não aceita entregas em nome do utilizador.
|
||||
@@ -0,0 +1,39 @@
|
||||
# Cálculo condicionado — entrega aceite
|
||||
|
||||
26/10/2026, Africa/Johannesburg. O utilizador declarou: **«Aceito esta entrega do cálculo condicionado. Regista a aceitação e cria o checkpoint Git local, excluindo credenciais e dados locais. Exigibilidade e período de apuramento permanecem pendentes. Não avances para emissão documental.»**
|
||||
|
||||
## Âmbito aceite e limites
|
||||
|
||||
Perfil fiscal versionado, proposta e validação por identidades distintas, activação por operação local especificamente autorizada e cálculo exacto sobre uma linha de serviço com preço sem imposto. A versão, empresa, unidade, serviço, vigência, fontes e condições são verificadas. O cálculo não altera decisões fiscais validadas. A classificação contabilística não determina IVA.
|
||||
|
||||
A decisão temporal aprovada pode manter o acontecimento pendente. Nesse caso o resultado permanece condicionado, com exigibilidade e período de apuramento nulos, sem presumir datas a partir do início do serviço ou da próxima facturação. O resultado é apresentado como **RASCUNHO — SEM VALIDADE FISCAL**. Não existe emissão, recebimento, apuramento líquido ou lançamento contabilístico neste incremento.
|
||||
|
||||
O caso local foi conferido no navegador: base 7 850,00, IVA exacto/proposto 1 256,00, diferença 0,00 e total proposto 9 106,00 MZN, com perfil/versões identificados. Os mesmos montantes constam das provas sintéticas; este registo não exporta cliente, documentos, decisões, identificadores ou movimentos da base local. A repetição do cálculo conservou um único resultado.
|
||||
|
||||
## Implementação e verificações
|
||||
|
||||
- `ServiceFiscal` e controlador: propostas/decisões imutáveis, autorização por âmbito e comando de cálculo condicionado; integração na pré-visualização existente.
|
||||
- Migração aditiva `2026_10_26_050000_create_service_fiscal_lifecycle.php`: três tabelas, relações e triggers, ampliação do CHECK de permissões preservando os direitos anteriores. Migração e cinco concessões iniciais foram confirmadas especificamente e aplicadas; comparação verificou preservação de 28 tabelas preexistentes. As provas JSON conservam apenas resultados agregados dessas fases, não o estado actual de activação.
|
||||
- `LocalFiscalActivation` / `scripts/service-fiscal-activate.php`: operação de console, base local própria, manifesto exacto e hash da definição revista. Sem rota HTTP ou concessão permanente de activação. Repetição não duplica eventos. A activação local posteriormente autorizada foi executada e auditada; não é executada automaticamente pelo checkout ou migração.
|
||||
- Interface com nomes em português, resumo de taxa/moeda/preço/vigência, estados distintos, condições e fontes acessíveis, fundamento da decisão e indicação permanente dos limites do rascunho.
|
||||
- Regressões dirigidas do circuito inicial: **52 testes / 1 171 asserções** em `sgf_tempo_test`. Após acrescentar a activação local: **17 testes / 423 asserções**, filtro `ServiceFiscalTest|ServiceCalculationTest|DatabaseSafetyTest`. Compilação Vite passou. Sem novas dependências ou versões.
|
||||
- Provas de concorrência: dois processos PHP sobrepostos, uma inserção e um replay, preservando o histórico; [registo sintético](proofs/service-fiscal-concurrency.json). [Imagem sintética](proofs/service-fiscal-browser.png). Os testes destrutivos e demonstrações sintéticas usam exclusivamente a instância isolada e a guarda de `sgf_tempo_test`.
|
||||
|
||||
Não foram repetidos testes destrutivos para registar esta aceitação. As alterações posteriores às provas foram apresentação e correcção de uma mensagem obsoleta, sem mudança das fórmulas/autorizações.
|
||||
|
||||
## Utilização e reprodução técnica
|
||||
|
||||
Seleccionar empresa e unidade autorizadas → **Perfil fiscal do serviço** para consultar/propor/validar versões. Consultar **Rascunhos de facturação → registo autorizado → Pré-visualizar rascunho** para o resultado e pendências. Apenas o detentor da permissão unitária de cálculo pode executar o comando; a validação temporal requer direito próprio e identidade distinta de quem propôs.
|
||||
|
||||
```powershell
|
||||
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/sgf.ps1 test --stop-on-failure '--filter=ServiceFiscalTest|ServiceCalculationTest|DatabaseSafetyTest'
|
||||
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/sgf.ps1 npm run build
|
||||
```
|
||||
|
||||
Os scripts `service-fiscal-fixture.php`, `service-fiscal-worker.php` e `service-fiscal-concurrency.php` são para provas sintéticas guardadas. Parar a instância de prova antes de testes que recriam a base de testes. Nunca usar reset/fresh em desenvolvimento. Os scripts de concessão/activação não são instruções para repetir as operações reais sem autorização específica.
|
||||
|
||||
## Preservação do checkpoint
|
||||
|
||||
Checkpoint exclusivamente local, sem push. Contém código, migração, testes, documentação de aceitação e provas sintéticas/agregadas. Ficam fora: `.env*` privados, credenciais, manifestos, fingerprints locais, bases, logs, imagens da operação real e a ficha nominativa `REAL_SERVICE_FISCAL_ASSESSMENT.md`, que permanece no posto local. A ficha contém o histórico detalhado do caso e este registo não a substitui.
|
||||
|
||||
**Entrega encerrada no âmbito aceite.** Exigibilidade e período de apuramento permanecem pendentes. A emissão documental exige incremento separado; esta aceitação não o autoriza e não autoriza publicação.
|
||||
@@ -0,0 +1,107 @@
|
||||
# Preparação documental — entrega local
|
||||
|
||||
Data: 26 de Outubro de 2026 (Africa/Johannesburg). Estado: implementado no âmbito autorizado e pronto para validação própria. B1 aceite em `8fcd52c`, A em `ca13acb` e identidade em `26b80df` permanecem preservados. Não houve reinstalação, mudança de versões, acesso ao InvesteMoz ou publicação.
|
||||
|
||||
## Resultado funcional
|
||||
|
||||
Novo menu **Preparação documental**, com cinco áreas: Dados do emitente, Dados dos clientes, Instruções de pagamento, Preparação de prestações e Preparação de facturação. Os nomes são reutilizados dos cadastros originais como denominação, sem segundo campo redundante. Se a denominação tiver de mudar, edita-se o nome no menu original, segundo os direitos existentes. Não se presume que esse nome já seja uma denominação legal validada.
|
||||
|
||||
Emitente e clientes podem preparar NUIT, morada, localidade e país. Clientes continuam a ser criados apenas com nome no percurso de A; os campos documentais podem ficar por completar. Os cadastros são da empresa e reutilizados entre unidades.
|
||||
|
||||
Nos rascunhos existentes da unidade autorizada podem preparar-se moeda, unidade de medida de cada linha, data/período do serviço, condições de pagamento, vencimento proposto e modo de preço: **Por definir / Imposto incluído / Imposto acrescido**. Datas são validadas como datas e fim de período anterior ao início é recusado. Não há data efectiva de emissão.
|
||||
|
||||
O modo de preço regista uma intenção para preparação futura: não altera os preços ou cálculos existentes, não calcula impostos nem reinterpreta valores históricos. Moeda vazia continua desconhecida. Se o utilizador alterar explicitamente a moeda, o workflow existente do rascunho cria nova versão e captura essa alteração, conservando a precisão e os valores. Essa operação continua a exigir o direito de edição do rascunho em A, além da edição documental; não é um direito implícito novo.
|
||||
|
||||
Condições e vencimento ficam sujeitos a conferência explícita. Sem data de emissão e convenção de contagem aprovadas, não há base para validar automaticamente um prazo contra a data proposta: aparece uma pendência de compatibilidade, sem declarar coerência nem corrigir datas silenciosamente. A indicação livre de «30 dias» não activa uma regra universal.
|
||||
|
||||
## Instruções do emitente para facilitar o pagamento
|
||||
|
||||
Podem configurar-se várias instruções identificadas por designação, com banco, titular, identificador de conta, NIB, IBAN, SWIFT, código bancário e moeda quando aplicáveis, mais texto. A designação é necessária para seleccionar a configuração; os restantes campos não são impostos a instruções que não sejam bancárias. Não existe uma pergunta ao cliente sobre como pagará.
|
||||
|
||||
Cada rascunho pode seleccionar instruções do emitente por identidade, sem redigitar identificadores. O ecrã de selecção mostra designação/versão e explicita que não houve verificação pelo banco. Não inicia operação bancária, não contacta fornecedores, não cria recebimento nem afecta valores.
|
||||
|
||||
Não se importaram contas dos exemplos nem foram definidos valores reais por omissão. O esquema/API não aceita campos de palavras-passe, tokens ou cartões; atribuições óbvias de segredos em texto são recusadas. O formulário informa que não se introduzem credenciais, PIN ou dados de cartões. Isso não constitui um serviço geral de detecção/verificação de dados bancários.
|
||||
|
||||
Alterações têm versão, histórico append-only e auditoria com identificadores/versão, sem valores das instruções. As respostas de erro de escrita e captura não transportam a consulta SQL com dados bancários nem a remetem para os logs da aplicação. Valores necessários ficam apenas nos registos/histórico autorizados e fotografias futuras correspondentes; não entram nos relatórios de prova ou repositório.
|
||||
|
||||
## Reutilização, completude e histórico
|
||||
|
||||
Ao criar um novo rascunho de facturação de uma prestação com preparação documental actual e consulta documental autorizada, reutilizam-se datas, condições, unidades, modo proposto e selecções de instruções. A origem/versão dessa preparação fica registada. Uma preparação de origem desactualizada não é copiada como actual; cadastros/preparações acrescentados depois não são injectados retrospectivamente nos rascunhos ou documentos anteriores.
|
||||
|
||||
O painel **Completude e validações** distingue «Por completar / confirmar aplicabilidade», «Preenchido — não validado», «Validação pendente» e «Origem alterada — rever». Mostra origem e próxima acção, incluindo consulta dos dados relacionados de emitente/cliente. Não há estado «apto para emissão fiscal». Não se construíram campos estatísticos, contratos ou motor geral de parâmetros.
|
||||
|
||||
Editar um rascunho após preparar os dados torna a preparação desactualizada. A confirmação interna exige revisão/actualização dessa preparação. Unidades de medida devem corresponder às linhas actuais; moeda é reutilizada do registo original, não mantida numa segunda fonte independente.
|
||||
|
||||
As fotografias B1 antigas não são actualizadas, reconstruídas ou promovidas a facturas. Para novas confirmações que utilizem preparação documental, o JSON da fotografia e o evento passam ao **esquema 2**, acrescentando `document_preparation`, versões dos registos, completude e cópias das instruções seleccionadas. Sem preparação aplicável mantém-se o formato anterior. O tipo de evento continua a significar confirmação interna, sem validade fiscal.
|
||||
|
||||
Alterações posteriores das instruções/cadastros não alteram fotografias v1 ou v2. A leitura de uma nova fotografia que contenha esses dados exige também consulta documental de emitente, cliente e unidade; apenas consultar facturação em A não passa a expor dados bancários. Rascunhos B1 confirmados continuam bloqueados por API e SQL, incluindo a preparação documental associada.
|
||||
|
||||
## Delta aplicado e preservação
|
||||
|
||||
O delta e destino foram apresentados antes da aplicação. Migração aditiva `2026_10_26_010000_create_document_preparation`, testada em `sgf_tempo_test` e aplicada em `sgf_tempo_dev` pelo wrapper/proprietário separado:
|
||||
|
||||
- `doc_records`: dados de emitente, cliente, instruções e preparação de rascunhos, com tipo, referência ao cadastro original, empresa/unidade e versão.
|
||||
- `doc_history`: versões preservadas, autor e instante; protecção append-only.
|
||||
- Constraints/triggers: fronteira de âmbito e referências, proibição de transferências por operações em massa, versões, selecção de instruções da mesma empresa e bloqueio da preparação de rascunhos confirmados.
|
||||
- Catálogo SQL ampliado apenas para os direitos documentais definidos abaixo; sem concessão automática pela migração.
|
||||
|
||||
Não houve reset/fresh/limpeza destrutiva em desenvolvimento. `document-preservation.php` comparou contagens e resumos criptográficos dos registos existentes antes/depois da migração/concessões: identidade, registos e captura de A e fotografias B1 permaneceram exactamente iguais. Os resumos ficam no directório operacional local, sem valores dos registos no relatório.
|
||||
|
||||
Na verificação final havia duas contas, uma empresa, uma unidade, um cliente e um serviço previamente existentes, sem prestações/rascunhos/confirmações em desenvolvimento; `doc_records` e `doc_history` estavam vazias. Não se criaram dados de demonstração na Tempo Lda/SEGI. A aplicação continua a usar `sgf_dev_app`, sem administração PostgreSQL, e a ligação normal não mudou.
|
||||
|
||||
O rollback automático desta migração é recusado para preservar história; qualquer reversão requer procedimento revisto de preservação. Não foram criadas tabelas de emissão fiscal, recebimentos ou lançamentos.
|
||||
|
||||
## Concessões especificamente confirmadas e aplicadas
|
||||
|
||||
As contas existentes foram conferidas, apresentadas e confirmadas antes da aplicação; nenhuma foi criada ou associada por suposição.
|
||||
|
||||
| Conta | Empresa Tempo Lda, ID 1 | Unidade SEGI, ID 1 |
|
||||
| --- | --- | --- |
|
||||
| ID 1 — Osmane Nala | `issuer_documents.view/edit` (inclui instruções); `client_documents.view/edit` | `draft_documents.view/edit` |
|
||||
| ID 2 — Samira Nal | `issuer_documents.view`; `client_documents.view` | `draft_documents.view` |
|
||||
|
||||
Aplicadas nove concessões, auditadas como `documents.access.initial_grant`; os direitos anteriores foram preservados. Não incluem gestão dos novos direitos, emissão, recebimento ou contabilização. Nomes/emails não determinam privilégios durante a execução. A API revalida contexto, pertenças, permissões e versão; revogação de consulta impede o pedido seguinte, inclusive a leitura de fotografias v2 com instruções.
|
||||
|
||||
`scripts/document-access.php` é procedimento local de pré-visualização/aplicação; não executar `--apply` como seed ou sem confirmação específica de nova operação. O procedimento usado recebeu os IDs explicitamente confirmados. `scripts/document-status.php` mostra contagens e direitos, sem valores das instruções.
|
||||
|
||||
## Verificações e provas
|
||||
|
||||
- **76 testes / 683 asserções aprovados** na suite completa, incluindo identidade, A e B1. As aceitações anteriores não foram reabertas.
|
||||
- Compilação Vite aprovada: 15 módulos, sem alteração de dependências, versões ou lockfiles.
|
||||
- Testes de cliente só com nome, denominação reutilizada, cadastros partilhados, instruções seleccionadas, herança da preparação, moeda desconhecida, precisão exacta, preenchido distinto de validado, períodos inválidos, pendência de condições/vencimento, versão/contexto antigos, origem alterada, acesso cruzado, leitura sem edição, ausência de direitos implícitos, revogação, SQL em massa, histórico append-only e rollback integral com falha injectada.
|
||||
- Compatibilidade: fotografia antiga sem esquema 2 preservada byte a byte pela resposta; nova fotografia v2 conserva instrução/versão seleccionada após alteração da configuração; consulta sem direito ao emitente é recusada. Eventos novos com conteúdo documental declaram esquema 2.
|
||||
- Falha de escrita com identificador sintético aleatório: nenhum valor incluído no erro, auditoria ou log técnico. Os relatórios de prova omitem os identificadores.
|
||||
- Prova HTTP com login real sintético: reutilização, fotografias v1/v2, recusas 403/409, selecção sem recebimento e ausência de reinterpretação monetária. [Resultado](proofs/document-http-results.json).
|
||||
- Prova no navegador, com CSRF e sessões/cache isolados: gestor actualizou emitente/cliente, consultou dados herdados, seleccionou instruções e guardou o modo proposto. Conta de consulta entrou pelo formulário, viu os dados e instruções seleccionadas, sem botão Guardar e com edição desactivada. A mudança entre separadores revelou uma falha de transição React, corrigida e novamente verificada.
|
||||
|
||||
Provas: [emitente e completude](proofs/document-01-issuer-profile.png), [instruções reutilizadas sem recebimento](proofs/document-02-reused-instructions.png), [consulta com contexto sintético](proofs/document-03-read-only.png), [métricas sem valores das instruções](proofs/document-capture.json).
|
||||
|
||||
A instância isolada usou apenas `sgf_tempo_test` na porta 8001. Foi parada antes da suite final que limpa os dados de teste. A aplicação normal permaneceu em `sgf_tempo_dev` na porta 8000; não se terminaram processos de outros projectos.
|
||||
|
||||
## Navegação exacta
|
||||
|
||||
1. Actualizar o navegador e entrar como utilizador autorizado; seleccionar Tempo Lda / SEGI. Se os novos direitos não aparecerem, sair e voltar a entrar.
|
||||
2. Abrir **Preparação documental → Dados do emitente**, completar e guardar. O nome é alterado em **Empresa**, segundo o direito existente.
|
||||
3. Abrir **Dados dos clientes**, seleccionar um cliente já criado em **Clientes**, completar os dados e guardar. Não duplicar o cadastro.
|
||||
4. Abrir **Instruções de pagamento → Novas instruções**, preencher apenas os dados aplicáveis, dar uma designação e guardar. Sem segredos ou dados de cartões.
|
||||
5. Criar uma prestação no menu **Prestações em rascunho**, se ainda não existir. Voltar a **Preparação documental → Preparação de prestações**, seleccioná-la, completar campos e seleccionar as instruções aplicáveis; guardar.
|
||||
6. Abrir a prestação em **Prestações em rascunho → Preparar rascunho de facturação**. Em **Preparação documental → Preparação de facturação**, seleccionar o rascunho e conferir os dados reutilizados e pendências. Pode também preparar directamente um rascunho existente ainda não confirmado.
|
||||
7. A confirmação interna B1 continua em **Rascunhos de facturação → abrir registo → Rever confirmação interna**; não é emissão. Nenhuma preparação pode editar um rascunho já confirmado.
|
||||
|
||||
## Ficheiros e comandos
|
||||
|
||||
Novos: `DocumentPreparation.php`, `Http/DocumentPreparationController.php`, `DocumentPreparationWorkspace.jsx`, migração indicada, `DocumentPreparationTest.php`, fixture documental e scripts `document-access.php`, `document-status.php`, `document-preservation.php`, `document-http-proof.mjs`, `document-proof-metrics.php`. Integração em rotas, navegação, CSS, criação de rascunho de facturação e captura/leitura de confirmações internas. A preparação de fixtures do navegador passou a conceder os novos direitos apenas a identidades sintéticas.
|
||||
|
||||
```powershell
|
||||
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\sgf.ps1 test
|
||||
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\sgf.ps1 npm run build
|
||||
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\sgf.ps1 php scripts/document-status.php
|
||||
```
|
||||
|
||||
Testes destrutivos permanecem exclusivos de `sgf_tempo_test`. Scripts de métricas verificam esse destino. Parar a instância de navegador de testes antes da suite. Nenhum exemplo real deve ser usado como fixture, configuração ou referência bancária por omissão.
|
||||
|
||||
## Pendências e limites
|
||||
|
||||
Nenhuma fonte legal/fiscal nova foi validada neste incremento. Obrigatoriedade por regime/tipo, validade de NUIT/moradas, numeração, emissão, taxas, incidência e arredondamento fiscal permanecem pendentes. Contas, reconhecimento, moeda funcional e processamento contabilístico também. A preparação não se apresenta como validada pelo banco ou apta para emissão fiscal.
|
||||
|
||||
Não há emissão de factura, recibo ou factura-recibo, data efectiva de emissão, número fiscal, PDF de factura, recebimento, afectação ou lançamento. Descontos, contratos, estatísticas e dimensões analíticas não foram implementados. Não existe eliminação de configurações ou gestão das novas concessões pela interface. Restantes incrementos e publicação continuam sem autorização; esta entrega aguarda validação do utilizador.
|
||||
@@ -0,0 +1,93 @@
|
||||
# Primeira pré-visualização documental — entrega técnica
|
||||
|
||||
Data: 26 de Outubro de 2026 (Africa/Johannesburg). Implementação e provas concluídas; **concessão real de configuração especificamente confirmada e aplicada**. Entrega pronta para validação do utilizador, sem a declarar aceite, nem à preparação documental anterior. Preservar identidade `26b80df`, A `ca13acb`, B1 `8fcd52c` e as alterações posteriores ainda não incluídas num novo checkpoint.
|
||||
|
||||
## Funcional
|
||||
|
||||
Em **Rascunhos de facturação → abrir rascunho → Pré-visualizar rascunho**, a aplicação apresenta dados reutilizados do emitente, cliente, linhas, preparação de datas/condições/moeda/unidades e instruções seleccionadas. Não se redigitam cadastros ou identificadores bancários. A apresentação configura-se separadamente em **Apresentação do rascunho**, no âmbito da empresa.
|
||||
|
||||
O aviso exacto **RASCUNHO — SEM VALIDADE FISCAL** fica fixo no topo da janela, em desktop e ecrã pequeno, e repete-se na folha visual. A configuração não dispõe de campos para alterar/ocultar aviso ou pendências; a API e o trigger SQL recusam campos fora do catálogo. As regras de estilo para a impressão normal do navegador mantêm aviso e pendências. Não existe função de impressão, exportação ou PDF no SGF neste incremento.
|
||||
|
||||
Os rótulos são **Preço proposto**, **Valor aritmético provisório**, **Imposto por apurar** e **Total definitivo por apurar**. O valor aritmético reutiliza a operação decimal exacta já existente. Falta de quantidade/preço mantém valor desconhecido, enquanto zero explicitamente guardado continua zero. Imposto e total definitivo mostram «Não apurado». Moeda ausente mostra «Moeda por definir»; não se presume MZN, não se somam moedas diferentes e não se decompõe preço com imposto incluído desconhecido. Nenhuma base aritmética é promovida a base tributável.
|
||||
|
||||
Campos em falta e pendências mantêm rótulos próprios, incluindo validação legal/fiscal, moeda, modo de preço, condições/vencimento e origem alterada. Dados preenchidos não passam a fiscalmente validados. O instante de consulta é rotulado como consulta, distinto de data/período do serviço e vencimento proposto. Não há data efectiva de emissão, número fiscal ou estado emitido.
|
||||
|
||||
## Configuração delimitada e recursos
|
||||
|
||||
O modelo por empresa tem versão e histórico append-only. Permite apresentar/omitir os blocos opcionais de logótipo, contactos, observações e instruções seleccionadas. Omitir blocos não elimina as pendências de negócio/documentais. Contactos e observações são texto de apresentação configurado uma vez por empresa; não havia campos de contacto empresarial nesses cadastros, e não se usa automaticamente o email privado do utilizador.
|
||||
|
||||
As instruções aplicáveis são as selecções já guardadas na preparação de cada rascunho; não se criam novas escolhas de meio de recebimento, cobranças ou ligações bancárias. A configuração só controla a apresentação desse bloco. A leitura de valores completos exige os direitos existentes e não os envia para logs, URLs ou relatórios de prova.
|
||||
|
||||
**Limitação identificada antes da implementação:** não havia logótipo empresarial nos recursos existentes. A opção de apresentação funciona, mas sem recurso surge «Logótipo opcional não disponível». Não se extraiu uma marca das imagens nem se criou/importou uma identidade visual. O resolvedor aceita apenas PNG local autorizado, até 512 KiB, do disco privado local no caminho fixo `document-logos/company-<ID>.png`; valida assinatura/MIME e inclui os bytes na resposta, sem pedido externo. Não há upload, URL configurável ou escolha arbitrária de ficheiro. Qualquer colocação futura de imagem deve ter autorização própria; não copiar os exemplos como recurso por omissão.
|
||||
|
||||
Contactos, observações, descrições e instruções são renderizados como texto escapado por React, sem HTML executável, links automáticos ou recursos externos. O modelo não permite HTML/CSS livre, regras de cálculo ou campos personalizados. O conteúdo não sai para serviços de renderização de terceiros.
|
||||
|
||||
## Consulta coerente e actualização explícita
|
||||
|
||||
Cada composição HTTP inicia uma transacção PostgreSQL **REPEATABLE READ READ ONLY** antes de ler dados e permissões. Configuração, cadastros, linhas, pendências e instruções vêm da mesma fotografia de leitura. A consulta não cria registos, resolve pendências, audita uma alteração de negócio, confirma ou emite documentos. A configuração é uma operação de escrita distinta, autorizada e auditada.
|
||||
|
||||
A resposta inclui uma revisão HMAC e metadados de versão; o instante da consulta fica fora dessa revisão. O endpoint de verificação devolve só a revisão. No navegador, verifica-se a cada dez segundos enquanto visível e ao regressar à janela. Uma mudança mostra **Pré-visualização desactualizada**, mantendo os valores já apresentados; só **Actualizar pré-visualização** substitui o conteúdo. Falha/recusa de nova consulta remove o conteúdo. A verificação é periódica, não uma notificação instantânea por push.
|
||||
|
||||
As consultas e revisões revalidam contexto, pertenças, empresa/unidade e permissões no servidor; respostas têm `Cache-Control: no-store`. A mudança de contexto desmonta a vista e elimina o estado anterior da interface. Não há cache partilhada nem reutilização de dados entre empresas/unidades. A revisão é autenticada com chave do servidor, sem permitir adivinhar identificadores bancários a partir de um hash simples.
|
||||
|
||||
## Histórico B1 separado
|
||||
|
||||
Em registos confirmados, a acção é **Abrir confirmação interna histórica**. O endpoint de rascunho recusa esse registo com 409 e indica a vista histórica. A nova vista usa exclusivamente a fotografia B1 preservada para o conteúdo, incluindo linhas, valores e dados documentais/instruções que tenham sido capturados no esquema 2. Não lê a configuração actual para enriquecer a história.
|
||||
|
||||
Campos não capturados mostram **Não capturado nesta confirmação**. As fotografias existentes não contêm logótipo/contactos/observações do modelo nem a denominação do emitente: não se completa essa informação a partir da empresa actual. A denominação actual no cabeçalho geral da aplicação indica apenas o contexto autorizado; não é inserida no documento histórico. A vista distingue autor/instante de confirmação, instante desta consulta, esquema da fotografia e ausência de modelo histórico capturado.
|
||||
|
||||
Nenhuma fotografia foi alterada ou reconstruída. As vistas antigas/esquema 2 continuam distintas de uma factura emitida. O mesmo aviso de ausência de validade fiscal acompanha a consulta histórica.
|
||||
|
||||
## Migração e preservação
|
||||
|
||||
Delta aditivo apresentado antes da aplicação: `2026_10_26_020000_create_document_preview_models`, testado em `sgf_tempo_test` e aplicado em `sgf_tempo_dev` pelo wrapper/proprietário separado.
|
||||
|
||||
- Cria `document_preview_models` (empresa, configuração, versão) e `document_preview_model_history` (versão preservada, autor, instante).
|
||||
- Acrescenta constraints/triggers para pertença imutável, versão, campos configuráveis fixos e histórico append-only.
|
||||
- Permite `document_preview.configure` apenas no âmbito da empresa; a migração não concede o direito.
|
||||
- Não cria emissão, numeração, datas fiscais, impostos, recebimentos ou lançamentos. Rollback automático recusado para preservar o histórico; eventual reversão exige procedimento revisto.
|
||||
|
||||
`document-preservation.php` foi alargado para comparar também `doc_records/doc_history`. A comparação antes/depois da migração confirmou conteúdo e contagens exactamente iguais em identidade, A, B1 e preparação documental. Não houve reset/fresh/limpeza destrutiva de desenvolvimento. Após a aplicação, as duas tabelas de modelo estavam vazias em desenvolvimento; não se criaram configurações de demonstração na Tempo Lda. A aplicação normal manteve a ligação a `sgf_tempo_dev` e o papel `sgf_dev_app` sem administração PostgreSQL.
|
||||
|
||||
## Acessos confirmados e aplicados
|
||||
|
||||
Consulta de rascunho reutiliza os direitos explícitos existentes: consulta da empresa/unidade, facturação, clientes e dados documentais de emitente/cliente/unidade. Consulta de configuração usa `issuer_documents.view`. Histórico v1 conserva a fronteira de consulta B1; conteúdo v2 com dados documentais exige também esses direitos de consulta. Nenhuma acção de leitura concede configuração ou emissão.
|
||||
|
||||
Contas existentes conferidas: ID 1 — Osmane Nala; ID 2 — Samira Nal. Operação concreta apresentada para confirmação: **conceder apenas `document_preview.configure` ao ID 1 na Tempo Lda, empresa ID 1, unidade nula**. Samira mantém os direitos de consulta existentes, sem novo direito de configuração. Não há gestão desse novo direito pela interface ou poder financeiro derivado.
|
||||
|
||||
**Estado efectivo:** o utilizador respondeu «Confirmar exactamente esta concessão». A conta e a empresa foram novamente conferidas; `preview-access.php 1 1 --apply` aplicou apenas `document_preview.configure` à conta 1 na empresa 1, com auditoria `document_preview.access.initial_grant`. A verificação posterior confirmou exactamente essa concessão, com unidade nula. Samira não recebeu configuração, os restantes direitos foram preservados e nenhuma configuração de demonstração foi criada em desenvolvimento. Não repetir a aplicação sem confirmação específica de uma nova operação.
|
||||
|
||||
## Verificação
|
||||
|
||||
- Suite completa: **89 testes / 893 asserções aprovados**, incluindo regressões da fundação e entregas anteriores. Aceitações não foram reabertas.
|
||||
- Compilação final Vite aprovada: 16 módulos, sem mudança de versões, manifests ou lockfiles.
|
||||
- Execução final apenas dos 13 testes novos: **13 testes / 210 asserções aprovados**. A prova de navegador foi parada antes dessa execução, que também limpa as fixtures de teste.
|
||||
- Testes de reutilização, consulta sem escritas, desconhecido distinto de zero, aritmética exacta, direitos explícitos, recusa de configuração para consulta, versões antigas, aviso/pendências não configuráveis, recurso externo recusado, revisão alterada, campos históricos não reconstruídos, acesso cruzado/revogação, PNG local, imutabilidade SQL e rollback de configuração.
|
||||
- Prova concorrente com processos PHP/PostgreSQL: isolamento `repeatable read` verificado; uma consulta em curso manteve ambas as versões antigas enquanto outra transacção alterava emitente/cliente; nova consulta viu ambas as versões novas, sem mistura. [Resultado](proofs/preview-coherence.json).
|
||||
- HTTP com login real sintético, CSRF e sessões distintas: configuração autorizada, leitor 403, campos proibidos 422, versão/contexto antigos 409, revisão sem conteúdo sensível e história independente do modelo actual. [Resultado](proofs/preview-http-results.json).
|
||||
- Navegador: configuração pelo gestor sintético, leitura de rascunho, mudança em segundo separador com aviso sem substituir o texto antigo, actualização explícita, consulta histórica, leitor sem botão Guardar e remoção da vista após mudar unidade. Ecrã real de 390 × 844, sem transbordo horizontal, aviso visível no topo durante a rolagem. [Registo sem valores bancários](proofs/preview-browser-results.json).
|
||||
|
||||
Provas visuais: [desktop](proofs/preview-01-desktop.png), [desactualização](proofs/preview-02-stale.png), [ecrã pequeno](proofs/preview-03-small-screen.png), [histórico](proofs/preview-04-historical.png), [histórico em ecrã pequeno](proofs/preview-05-history-small.png), [configuração em consulta](proofs/preview-06-reader-configuration.png). As provas omitem valores completos das instruções; o bloco foi desactivado apenas na configuração sintética, mantendo as pendências. O comportamento de apresentação de instruções seleccionadas foi verificado por testes e HTTP.
|
||||
|
||||
As provas usaram exclusivamente a instância na porta 8001 e `sgf_tempo_test`, sem mudar a ligação normal ou introduzir demonstrações na Tempo Lda. A dimensão temporária do navegador foi reposta; os separadores de prova foram fechados. Sem publicação ou processos alheios terminados.
|
||||
|
||||
## Ficheiros e navegação
|
||||
|
||||
Novos: `app/Modules/Services/DocumentPreview.php`, `Http/DocumentPreviewController.php`, `resources/js/DocumentPreview.jsx`, migração indicada, `DocumentPreviewTest.php`, fixture própria e scripts `preview-access.php`, `preview-status.php`, `preview-http-proof.mjs`, `preview-coherence-proof.php`, `preview-coherence-worker.php`. Integração em rotas, navegação, ServicesWorkspace e CSS; fixture de navegador e verificação de preservação adaptadas.
|
||||
|
||||
1. Actualizar o navegador e entrar; seleccionar **Tempo Lda / SEGI**.
|
||||
2. Se ainda não houver rascunho, usar o percurso existente: **Clientes → Serviços → Prestações em rascunho → abrir prestação → Preparar rascunho de facturação**; completar os dados em **Preparação documental**, conforme necessário.
|
||||
3. **Rascunhos de facturação → seleccionar um rascunho não confirmado → Pré-visualizar rascunho**.
|
||||
4. Se houver aviso de alteração, usar **Actualizar pré-visualização**. A abertura/actualização não confirma nem emite.
|
||||
5. **Apresentação do rascunho** permite consultar a configuração. Osmane pode guardar a apresentação; Samira permanece em consulta. Actualizar a sessão, saindo e entrando novamente se necessário, para carregar a concessão aplicada.
|
||||
6. Para história: **Rascunhos de facturação → seleccionar registo confirmado → Abrir confirmação interna histórica**. Não completar campos históricos com dados actuais.
|
||||
|
||||
```powershell
|
||||
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\sgf.ps1 php scripts/preview-status.php
|
||||
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\sgf.ps1 test --filter DocumentPreviewTest
|
||||
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\sgf.ps1 npm run build
|
||||
```
|
||||
|
||||
## Limites
|
||||
|
||||
Apenas navegador. Sem PDF/exportação/impressão documental, emissão fiscal, data efectiva de emissão, número fiscal, novo cálculo de impostos, recibos, recebimentos, afectações, reconciliação ou lançamentos. Não se validaram novas fontes legais/fiscais ou regras de arredondamento. O modelo não é editor geral nem prova de conformidade. Não há recurso empresarial de logótipo instalado, carregamento externo ou upload. O restante âmbito e publicação continuam sem autorização. Esta entrega aguarda validação do utilizador.
|
||||
@@ -0,0 +1,122 @@
|
||||
# Pré-visualização de factura de serviço — plano para aprovação
|
||||
|
||||
Data: 26 de Outubro de 2026 (Africa/Johannesburg). Apenas plano, critérios e decisões; não autoriza implementação ou publicação.
|
||||
|
||||
Actualização posterior: o utilizador fechou as decisões de configuração limitada, rótulos, actualização explícita e história B1 separada e autorizou a primeira implementação por prompt próprio. A execução está em [DRAFT_INVOICE_PREVIEW_DELIVERY.md](DRAFT_INVOICE_PREVIEW_DELIVERY.md). A concessão efectiva de configuração é uma confirmação específica separada; o restante âmbito fiscal/contabilístico continua sem autorização.
|
||||
|
||||
Preservar a preparação documental entregue e o trabalho posterior ainda não incluído num novo checkpoint. Preservar identidade `26b80df`, A `ca13acb` e B1 `8fcd52c`, com as respectivas aceitações. A preparação documental tem relatório próprio e não é declarada aceite por este plano. Não alterar código, bases, permissões, fotografias ou versões nesta etapa. Não foram repetidos testes.
|
||||
|
||||
Referências: SGF_TEMPO_Roteiro_v0_9.docx, BILLING_DOCUMENTS_FIELD_SPEC.md, DOCUMENT_PREPARATION_DELIVERY.md e SERVICES_B1_DELIVERY.md. Os três exemplos informam a organização do conteúdo, sem limitar o modelo ou validar obrigações legais.
|
||||
|
||||
## Próximo incremento proposto
|
||||
|
||||
Acrescentar uma pré-visualização de leitura do **rascunho de facturação de serviço**, dentro da aplicação. Reutilizar dados existentes, sem duplicar cadastros, recolher novamente instruções de pagamento ou criar um novo documento emitido. Proposta inicial: um modelo comum, configurável de forma limitada e com versão identificada, apresentado no navegador. Sem PDF, exportação ou função de impressão neste incremento.
|
||||
|
||||
Mostrar permanentemente **RASCUNHO — SEM VALIDADE FISCAL** no cabeçalho e num aviso visível durante a navegação/rolagem. Repetir a indicação nas páginas visuais do documento. O aviso não pode ser removido por configuração. Uma eventual impressão pelo próprio navegador não é uma capacidade fiscal do SGF; a folha de impressão deve conservar o aviso. Não há número fiscal, data efectiva de emissão, assinatura fiscal ou estado de factura emitida.
|
||||
|
||||
Percurso proposto: **Rascunhos de facturação → abrir registo → Pré-visualizar rascunho**. A pré-visualização permite voltar aos menus de preparação autorizados; não edita silenciosamente os dados nem oferece botões de emissão, recebimento ou contabilização.
|
||||
|
||||
## Conteúdo e origem
|
||||
|
||||
| Bloco | Origem | Apresentação proposta / informação em falta |
|
||||
| --- | --- | --- |
|
||||
| Identificação | Rascunho e contexto autorizado | Referência interna claramente rotulada, empresa/unidade, versão do rascunho e da preparação. Sem converter INT-B1 ou ID técnico em número de factura |
|
||||
| Emitente | Nome da empresa e preparação documental | Denominação reutilizada, NUIT, morada, localidade e país quando preenchidos. Campo relevante vazio: «Por completar», sem inventar identificação |
|
||||
| Cliente | Cliente seleccionado e preparação documental da empresa | Mesmo cadastro e versões, sem cópia por unidade. Nome basta para começar; restantes dados em falta permanecem visíveis |
|
||||
| Serviço e origem | Prestação/rascunho existentes | Descrição, origem e versões. Não afirmar execução confirmada do serviço |
|
||||
| Linhas | Linhas guardadas e unidades de medida preparadas | Serviço, descrição, quantidade, unidade e preço proposto. Desconhecido é «Por completar»; zero explicitamente guardado continua zero |
|
||||
| Datas | Preparação documental | Data/período do serviço e vencimento **proposto**, separados. Condições e vencimento com pendência de compatibilidade; não inferir emissão ou competência contabilística |
|
||||
| Moeda | Moeda guardada no rascunho | Código indicado, com validação pendente, ou «Moeda por definir». Nenhuma moeda por omissão |
|
||||
| Modo de preço | Preparação guardada | «Por definir», «Imposto incluído — indicação proposta» ou «Imposto acrescido — indicação proposta». Não altera os preços existentes |
|
||||
| Valores | Valores exactos já existentes | Preços propostos e, se disponível, valor aritmético já calculado pelo percurso existente, com rótulo provisório. Não chamar base tributável à base aritmética de A/B1 |
|
||||
| Impostos e total | Pendências existentes; sem motor fiscal | «Impostos não apurados» e «Total fiscal / montante definitivo: não apurado». Não mostrar imposto zero ou fabricar um total pela ausência de regra |
|
||||
| Instruções para pagamento | Configurações do emitente explicitamente seleccionadas | Dados aplicáveis reutilizados, sem redigitação; designação/versão e indicação de introdução pelo utilizador, sem verificação bancária. Sem selecção: «Instruções não seleccionadas», nunca «pagamento pendente/recebido» |
|
||||
| Completude | Verificações documentais existentes | Separar «Por completar», «Preenchido — não validado», «Validação pendente» e «Origem alterada». Mostrar origem e próxima acção |
|
||||
|
||||
Sem moeda definida, qualquer expressão aritmética existente deve ser identificada como valor sem unidade monetária validada, sem símbolo monetário ou total definitivo. Não agregar moedas distintas. A escolha de imposto incluído/acrescido não autoriza decompor o preço, aplicar taxa, arredondar ou relançar valores anteriores. Não introduzir novos cálculos de impostos, descontos, câmbio ou totais fiscais.
|
||||
|
||||
Dados adicionais de gestão/estatísticas, extractos de conta, publicidade, contratos, descontos e logística ficam fora deste incremento. Dados bancários seleccionados são instruções do emitente para facilitar pagamento, não uma pergunta sobre como o cliente pagará.
|
||||
|
||||
## Modelo configurável proposto
|
||||
|
||||
Usar um núcleo de conteúdo comum e configuração limitada de apresentação, sem motor geral de campos personalizados. Não reproduzir obrigatoriamente as colunas, marcas, bancos ou rodapés das imagens fornecidas.
|
||||
|
||||
Proposta mínima de configuração: ordem dos blocos opcionais, visibilidade de dados opcionais já autorizados e rótulos de apresentação não fiscais. Modelo base por empresa, com versão; eventual logótipo só se houver activo autorizado disponível. Não criar agora um editor livre de HTML, uploads ou integrações. A leitura/configuração do modelo não altera regras de negócio ou permissões sobre o conteúdo.
|
||||
|
||||
Não configuráveis: aviso de rascunho, ausência de emissão, distinção entre provisório e definitivo, indicação de impostos não apurados, identificação das origens/versões e pendências relevantes. Ocultar um campo opcional do desenho não resolve nem elimina uma pendência no painel de completude. Dados em falta não devem ser ocultados para produzir aparência de documento completo.
|
||||
|
||||
Propor um desenho sóbrio com identificação das partes, linhas, datas e condições, secção de valores provisórios, instruções e pendências. O painel de trabalho pode apresentar metadados de contexto e versões separado da folha visual. A configuração não é um mecanismo de autorização nem prova de conformidade fiscal.
|
||||
|
||||
## Actualidade e preservação histórica
|
||||
|
||||
- **Rascunho editável:** proposta de leitura conjunta coerente das versões actuais autorizadas, com indicação das versões de empresa/cliente/preparação/linhas/instruções e instante de consulta rotulado como tal, nunca emissão. A confirmação de geração não deve gravar nova fotografia B1 nem alterar estados.
|
||||
- Se os dados mudarem enquanto a pré-visualização estiver aberta, indicar «Pré-visualização desactualizada — actualizar». A actualização é explícita; não substituir silenciosamente valores ou instruções já visíveis. A estratégia de detecção (ao regressar/recarregar, sem actualização automática contínua) deve ser aprovada antes de implementar.
|
||||
- **Registo já confirmado B1:** não montar um documento aparentemente histórico com cadastros actuais. Proposta: manter a consulta histórica B1 separada e usar exclusivamente a fotografia guardada. Formato antigo sem determinado campo mostra «Não capturado nesta confirmação», sem o ir buscar ao cadastro actual. Esquema 2 mostra apenas os dados capturados na sua versão.
|
||||
- Não chamar à consulta B1 uma factura ou emissão. Manter «Confirmado internamente — sem validade fiscal» e, se adoptar a mesma representação visual, conservar também o aviso de rascunho. Não alterar fotografias antigas para acomodar o modelo.
|
||||
- O modelo de apresentação pode evoluir sem modificar os dados de origem. Uma representação histórica não é prova de que essa versão do modelo já existia na confirmação: mostrar separadamente versão da fotografia e versão do modelo usado na consulta.
|
||||
|
||||
## Acessos e protecção
|
||||
|
||||
Proposta: reutilizar **apenas consulta** já explicitamente concedida, sem criar poder de emissão: consulta de facturação no âmbito da unidade, `draft_documents.view` nessa unidade, `issuer_documents.view` e `client_documents.view` na empresa. Confirmar a matriz exacta antes da implementação; editar preparação ou configurar um modelo não resulta desta acção de consulta.
|
||||
|
||||
O servidor revalida utilizador, pertenças, contexto, unidade e referências em cada pedido. Identificadores enviados pelo navegador não autorizam dados. Revogação impede a consulta no pedido seguinte; não misturar dados de empresas do mesmo tenant ou de outra unidade.
|
||||
|
||||
Valores completos das instruções de pagamento só aparecem na apresentação autorizada quando seleccionados; não entram em URLs, logs, erros, telemetria, relatórios de testes ou repositório. Evitar cache partilhada e dados de um contexto anterior ao mudar empresa/unidade ou sair. Escapar texto e impedir HTML/script introduzido em instruções ou descrições. Provas futuras com dados sintéticos em instância isolada, mantendo valores de instruções fora das capturas de prova a versionar.
|
||||
|
||||
## Plano de implementação futuro, sujeito a aprovação
|
||||
|
||||
1. Fechar decisões abaixo e aprovar um exemplo de organização visual com campos fictícios/sem identificadores bancários reais, sem avançar para emissão.
|
||||
2. Compor uma resposta de leitura com conteúdo e proveniência/versões, reutilizando workflows existentes. Definir a política de actualidade e acesso; não persistir um novo documento fiscal.
|
||||
3. Renderizar o modelo base e painel de pendências, com configuração limitada e aviso obrigatório; separar consulta de rascunho actual e fotografia B1.
|
||||
4. Testar a composição, a confidencialidade e a apresentação; demonstrar no navegador isolado o percurso com dados sintéticos. Executar apenas regressões justificadas pelas alterações, quando a implementação for autorizada.
|
||||
5. Entregar ficheiros, provas, limitações e instruções de navegação. Não aplicar novas concessões, migrações ou criação de configuração sem apresentar o delta/âmbito correspondente. Não publicar.
|
||||
|
||||
## Critérios de aceitação propostos
|
||||
|
||||
1. Um rascunho de serviço existente é apresentado sem redigitar emitente, cliente, linhas, datas, moeda ou instruções seleccionadas e sem criar outro cliente/documento/recebimento.
|
||||
2. O aviso exacto **RASCUNHO — SEM VALIDADE FISCAL** mantém-se visível durante a leitura, em páginas visuais e no estilo de impressão; nenhuma configuração o remove.
|
||||
3. Campos em falta, dados preenchidos sem validação e regras pendentes têm estados/rótulos distintos; zero explícito não é confundido com desconhecido. Nenhum estado afirma aptidão fiscal.
|
||||
4. Datas de serviço/período, vencimento proposto e instante de consulta aparecem distintos; não existe data efectiva de emissão, número fiscal ou estado emitido.
|
||||
5. Valores mantêm as cadeias decimais exactas de origem. Moeda/mode desconhecidos não são presumidos; modos incluído/acrescido não geram taxa, imposto, base tributável ou total fictícios. Impostos/total definitivo ficam não apurados.
|
||||
6. Só as instruções seleccionadas da empresa autorizada aparecem. Reabrir/actualizar não cria pagamento nem apresenta verificação bancária. Valores completos não surgem em artefactos de prova ou logs.
|
||||
7. Mudança de cadastros/rascunho/instruções detectável segundo a política aprovada gera sinalização de desactualização e actualização explícita; não há mistura silenciosa de versões/contextos.
|
||||
8. B1 v1/v2 mantém dados e metadados imutáveis. Campo não capturado na versão antiga não é completado a partir do presente. Consulta histórica permanece distinta da factura emitida.
|
||||
9. Acesso directo, identificadores manipulados, outra empresa do mesmo tenant, outra unidade e revogação de direitos são tratados no servidor; utilizador de consulta não edita dados ou modelo.
|
||||
10. Textos longos, linhas múltiplas e campos ausentes têm apresentação legível sem esconder aviso ou pendências. A configuração permitida varia o desenho sem limitar o conteúdo aos três exemplos ou alterar regras.
|
||||
11. Não há gravação de emissão, imposto, recebimento, afectação ou lançamento, nem promoção de confirmações B1. Código/bases aceites preservados e nenhuma publicação.
|
||||
|
||||
## Decisões para fechar antes de implementar
|
||||
|
||||
| Decisão | Proposta para revisão |
|
||||
| --- | --- |
|
||||
| Saída inicial | Pré-visualização dentro da aplicação; sem PDF, exportação ou botão de impressão |
|
||||
| Acesso ao rascunho | Reutilizar a conjunção dos direitos de consulta acima; sem concessões novas por inferência |
|
||||
| Acesso/configuração do modelo | Definir quem configura e quais opções. Se exigir direito novo, matriz e concessão confirmadas separadamente; não derivar gestão de modelo de consulta/edição de dados |
|
||||
| Configuração inicial | Um modelo base comum, configuração limitada por empresa; decidir quais blocos opcionais/rótulos podem variar e se essa edição entra já no incremento |
|
||||
| Valores mostrados | Proposta: preços exactos propostos e valor aritmético já existente com rótulo inequívoco; imposto e total definitivo não apurados. Aprovar a nomenclatura antes de desenhar |
|
||||
| Actualidade | Proposta: composição coerente ao abrir e verificação ao regressar/actualizar; aviso de mudança, sem substituir dados automaticamente. Definir tratamento de mudança durante a consulta |
|
||||
| B1 | Proposta: ligação separada para a fotografia histórica, sem reconstrução; decidir se reutiliza o desenho com rótulo histórico explícito ou mantém o detalhe actual |
|
||||
| Instruções de pagamento | Mostrar apenas as seleccionadas e aplicáveis, sem as mascarar no documento autorizado; não fotografar valores completos para relatórios/repositório |
|
||||
|
||||
Estas decisões são de produto/segurança/apresentação. Podem ser fechadas sem aprovar taxas, plano de contas ou emissão. Não se pede uma nova aceitação de identidade, A ou B1.
|
||||
|
||||
## Fontes e decisões ainda necessárias para cálculo e emissão reais
|
||||
|
||||
**Estado das fontes:** a documentação local regista que nenhuma fonte legal/fiscal foi validada nesta tarefa. A v0.9 e as entregas aceites são referências de produto; os exemplos são referências de conteúdo. Esta revisão não realizou pesquisa legislativa nem atribui vigência/conformidade a diplomas não consultados.
|
||||
|
||||
| Tema | Fonte/evidência a obter e validar | Decisão dependente |
|
||||
| --- | --- | --- |
|
||||
| Âmbito fiscal | Enquadramento efectivo da empresa, operações e período; documentação oficial aplicável e responsável competente identificado | Quais tipos/casos de emissão devem ser suportados e em que regime |
|
||||
| Identificação e conteúdo | Textos oficiais sobre elementos documentais aplicáveis, com artigo, vigência, alterações e casos especiais | Obrigatoriedade de NUIT/moradas/identificação do cliente, descrições, datas e textos por tipo de documento |
|
||||
| Impostos | Normas/tabelas oficiais aplicáveis à operação/data, fundamentos de isenção/não sujeição e validação do enquadramento | Tratamento, taxas, incidência, descontos/encargos, adiantamentos e eventuais retenções; desconhecido continua pendente |
|
||||
| Preço e cálculo | Política aprovada compatível com as fontes aplicáveis e exemplos de cálculo conferidos | Incluído/acrescido, precisão, sequência e ponto/método de arredondamento por linha/documento e explicação de diferenças |
|
||||
| Moeda e câmbio | Regras oficiais aplicáveis e política da empresa validada; fontes de câmbio só se necessárias e autorizadas | Moeda documental/funcional, fonte/data/taxa de conversão, exposição de impostos e tratamento de diferenças |
|
||||
| Emissão e identidade | Regras oficiais aplicáveis a numeração/séries, datas, emissão, rectificação e reprodução; requisitos do software/autoridade se exigíveis | Atribuição de número, unicidade, concorrência, lacunas, momento de emissão, exemplares e controlo de alterações |
|
||||
| Arquivo e representação | Requisitos aplicáveis de arquivo, conservação, autenticidade, comunicação e acesso | Formato definitivo, conteúdo legal, evidências, retenção e eventuais integrações; nenhuma presumida neste desenho |
|
||||
| Factura-recibo e recibo | Regras aplicáveis e casos operacionais aprovados, critérios de evidência do recebimento | Quando se usam, identidades, afectações, parciais, excedentes, duplicados e prevenção de dupla documentação |
|
||||
| Responsabilidade e permissões | Matriz aprovada pelo utilizador e responsabilidades fiscal/contabilística identificadas | Quem verifica, emite, documenta recebimentos, corrige ou autoriza; sem herdar esses poderes da pré-visualização |
|
||||
| Contabilidade | Política/plano de contas, reconhecimento, períodos e classificação validados por responsável competente | Quais acontecimentos geram efeitos, quando e com que regras. Desenho ou emissão não aprovam lançamentos |
|
||||
|
||||
Para cada fonte futura registar identificação oficial/URL, versão, artigo, datas de vigência, âmbito de aplicação, responsável e estado da validação. Um parecer deve ser distinguido da norma que interpreta; um exemplo impresso não substitui nenhuma dessas fontes. Este levantamento documental é uma frente de requisitos, não implementação em paralelo de fiscalidade/contabilidade.
|
||||
|
||||
O próximo prompt de execução deverá seleccionar apenas a pré-visualização aprovada. Cálculo fiscal, emissão e demais operações continuarão bloqueados até âmbito, regras, fontes e acessos próprios estarem definidos e autorizados.
|
||||
@@ -0,0 +1,252 @@
|
||||
# Contabilidade de custos industriais — proposta documental
|
||||
|
||||
27/10/2026, Africa/Johannesburg. Versão 0.1. **Não autoriza implementação, dados operacionais, migrações, concessões ou lançamentos.**
|
||||
|
||||
## 1. Objectivo, base e limites
|
||||
|
||||
Conhecer o custo de produzir, explicar cada componente e comparar previsto com realizado, com fontes/versões e pendências visíveis. Não inferir IVA, reconhecimento de receita, valorização legal de inventários ou lançamento a partir de uma classificação de gestão.
|
||||
|
||||
Projecto exclusivo `C:\laragon\www\sgf-tempo`, com instruções locais lidas. Preservar `4276aca`, alterações posteriores e [recebimentos sintéticos](SERVICE_RECEIVABLES_DELIVERY.md), sem presumir aceitação dessa entrega. Não alterar os bloqueios de emissão/configuração real ou recebimentos reais. Não repetir o cotejo fiscal do InvesteMoz.
|
||||
|
||||
Esta proposta foi preparada **depois da especificação de [oficinas/assistência](WORKSHOP_MANAGEMENT_SCOPE.md)**, que foi lida e constitui desenho ainda não implementado. A referência geral continua a ser o roteiro **v0.9**, especialmente núcleo universal/extensões sectoriais, indústria, registo único, regras versionadas e contabilidade permanente. A indústria ali prevista não demonstra compras, stock, produção ou custeio já operacionais.
|
||||
|
||||
O primeiro ensaio recomendado é uma empresa/unidade sintéticas, um período, um produto, uma ordem/lote concluído, uma moeda explícita e uma única etapa. Não se conhece ainda a indústria real destinatária. Não adoptar um método empresarial ou um plano de contas por analogia com a Tempo.
|
||||
|
||||
## 2. Fontes contabilísticas disponíveis e alcance
|
||||
|
||||
| Fonte efectivamente disponível | Uso delimitado nesta proposta | O que não demonstra |
|
||||
| --- | --- | --- |
|
||||
| `SGF_TEMPO_Roteiro_v0_9.docx`, exemplar fornecido | Indústria com estruturas de produto, ordens, consumos, produtos obtidos, custo/qualidade/rastreabilidade; núcleo e reutilização sem recaptura | Processo produtivo, método de custeio ou integrações efectivas de uma indústria real |
|
||||
| [Classificação contabilística](CATALOGUE_ACCOUNTING_CLASSIFICATION_SPEC.md) e [entrega](CATALOGUE_ACCOUNTING_DELIVERY.md) | Separação entre plano/conta, natureza do recurso, reconhecimento e IVA; fontes/versionamento e âmbito empresarial | Catálogo industrial de contas, centros de custo, valorização de stock ou regras de lançamento já aprovados |
|
||||
| Decreto 70/2009 fornecido, `\\Mac\Home\Downloads\29-Plano-de-Contas-BR-Decreto-70-2009-de-22-de-Dezembro.pdf` | Exemplar histórico já identificado, SHA-256 `45C38AED64DE43042ED048586ACCE2EC660B74FC3F8FBCE33D39AAB45C7529E3`. Leitura dirigida adicional da **NCRF 9 — Inventários**, PDF 36–37, BR 372-(50)–(51): §§7–14 sobre mensuração/componentes/capacidade; §§15–17 sobre técnicas/fórmulas; §23 sobre reconhecimento como gasto | Não é consolidação normativa actual verificada, aprovação de política para empresa industrial ou autorização de activar valorização/lançamentos |
|
||||
| Capas dos livros partilhados | Identificação bibliográfica potencial | Capítulos não fornecidos: não se lhes atribuem fórmulas, métodos, exemplos ou ensinamentos não consultados |
|
||||
|
||||
O exemplar histórico distingue custos de compra/transformação/outros e trata capacidade normal na imputação de gastos industriais fixos (§§8–12). O §11 distingue a parcela fixa não imputada; a proposta de gestão deve conservá-la, sem a forçar para o produto. §§16–17 tratam fórmulas de custo de inventários, matéria diferente de escolher um driver de custos indirectos. §23 separa custo do inventário e momento de reconhecimento como gasto. Estas referências justificam manter conceitos distintos; não aprovam a política da indústria futura.
|
||||
|
||||
Lacunas normativas específicas para eventual uso real: identificar entidade/sector e referencial aplicável; verificar vigência/alterações apenas das disposições que serão activadas; validar custo elegível, capacidade normal, perdas/retrabalho, produção em curso, fórmula de inventário e reconhecimento. **Não bloqueiam a elaboração do ensaio sintético**, que não declara conformidade de valorização. A aplicação PGC-NIRF confirmada para a Tempo não se propaga a todas as empresas futuras.
|
||||
|
||||
## 3. Conceitos que não se substituem
|
||||
|
||||
| Conceito | Definição operacional proposta |
|
||||
| --- | --- |
|
||||
| Custo de produção de gestão | Recursos elegíveis atribuídos/imputados ao objecto sob política explícita, no corte/versionamento do cálculo. Pode ser parcial ou provisório |
|
||||
| Custo de produção unitário | Custo atribuído ao lote / quantidade de produto elegível, na mesma definição e corte. Denominador zero/desconhecido não produz zero por unidade |
|
||||
| Custo das vendas | Parcela do custo referente às unidades vendidas segundo política de inventário/reconhecimento própria. Não equivale ao custo de todo o lote produzido ou ao valor facturado |
|
||||
| Despesa do período | Recurso destinado ao período segundo política validada, sem o capitalizar só para completar custo do produto. Pode incluir parcelas não imputadas conforme regras aplicáveis, ainda sem lançamento |
|
||||
| Preço de venda | Valor comercial aprovado, independente de custo; não valoriza material ou mão-de-obra por ausência de custo |
|
||||
| Margem | Indicador que identifica receita/preço, volume vendido, custo das vendas e despesas incluídas/excluídas. Sem esse perímetro completo, apenas diferença parcial identificada; nunca «lucro» comprovado |
|
||||
| Previsto | Versão de plano anterior ao corte, com quantidades, taxas, produção e critérios estimados. Não é consumo real |
|
||||
| Realizado | Quantidades observadas/verificadas; a sua valorização pode ainda ser provisória/desconhecida. «Executado» não significa custo validado |
|
||||
|
||||
Classificação directa/indirecta é relativa ao objecto de custo e à política, não só à natureza ou conta. O mesmo técnico/recurso pode ter horas directas e indirectas **distintas**, sem classificar o mesmo intervalo integralmente nos dois lados. Método de acumulação (ordem/processo), perímetro de custo (absorção/variável), técnica de mensuração (real/padrão) e base de repartição/ABC são dimensões diferentes, não alternativas de uma única lista.
|
||||
|
||||
## 4. Alternativas necessárias e recorte recomendado
|
||||
|
||||
| Dimensão | Alternativas relevantes | Recorte sintético recomendado e limite |
|
||||
| --- | --- | --- |
|
||||
| Acumulação | Por ordem/lote identificado; por processo homogéneo/período | **Ordem/lote**, por permitir ligar poucos recursos concretos. Processo exige indústria/etapas e fluxos ainda não identificados |
|
||||
| Perímetro | Custos directos com CIF elegíveis explícitos; análise variável/contribuição | Directos + **um conjunto de CIF sintéticos identificado**, sem dizer que todo custo empresarial é absorvido. Custeio variável é outra análise, não valorização legal presumida |
|
||||
| Imputação | Driver simples com causalidade declarada; actividades/ABC | Um driver em horas-máquina e um critério versionado. ABC só se actividades/consumos justificarem extensão |
|
||||
| Valorização | Custos específicos verificados; dados de inventário/folha/activos sob política | Taxas/valores sintéticos documentados, sem seleccionar FIFO, média ou política salarial para empresa real |
|
||||
|
||||
Recomenda-se demonstrar a aritmética de gestão por ordem, com fontes explícitas e residual. **Não é decisão de adopção de custeio por encomenda, absorção ou método legal numa indústria real.** Nenhum pressuposto da fixture se torna configuração por omissão.
|
||||
|
||||
## 5. Objectos de custo, entidades e dados
|
||||
|
||||
| Entidade | Conteúdo mínimo e vínculos |
|
||||
| --- | --- |
|
||||
| Produto | ID empresarial, designação, unidade do produto, versão/especificação e categoria existente quando aplicável. Catálogo de serviços não deve ser renomeado para fingir produto/stock |
|
||||
| Ordem/lote de produção | ID próprio, tenant/empresa/unidade, produto, quantidade prevista, período e corte, datas, versão, etapa única e responsável. Não é ordem de oficina nem documento fiscal |
|
||||
| Centro de custo | Identidade empresarial, unidade(s) autorizadas, finalidade, vigência e responsável. Centro é dimensão analítica, não unidade física/empresa por omissão |
|
||||
| Plano de custos | Versão base: quantidades/unidades, custos unitários, critérios de CIF, produção prevista e pressupostos; aprovação e data de corte. Comparativo preserva esta versão, sem a substituir pelo realizado |
|
||||
| Acontecimento de recurso | ID canónico/origem/versão, tipo consumo/devolução/tempo/serviço, quantidade, unidade, recurso, ordem/tarefa/contexto, data efectiva/registro, evidência, autor e estado verificado |
|
||||
| Valorização de recurso | ID e versão de cada origem, quantidade elegível, taxa/preço de custo, moeda, unidade da taxa, fonte, vigência e estado conhecido/provisório/em falta/não aplicável. Guardar composição quando houver encargos |
|
||||
| Destino de custo directo | Referência da origem, ordem/lote e papel, quantidade/valor atribuído e critério. Não criar outra origem ou consumo ao atribuir |
|
||||
| Conjunto de custos indirectos | IDs de parcelas elegíveis, centro/empresa/unidade, período, natureza fixa/variável quando conhecida, total exacto e exclusões/motivos. Conjunto não é conta contabilística automática |
|
||||
| Critério de imputação | Versão, âmbito/vigência, conjunto, driver/unidade, denominador, capacidade quando relevante, numeradores por destino, fórmula, limites, representação e tratamento de residual |
|
||||
| Execução de imputação | ID, conjunto/critério/versões exactas, corte, bases, parcelas por destino, residual e pendências; aprovação e estado. Uma origem não é aplicada outra vez por repetir o comando |
|
||||
| Produção e qualidade | Evento próprio de quantidade obtida, unidades boas, rejeitadas, perda/retrabalho, unidade, data, evidência e validação. Produção em curso distinta de acabado e de venda |
|
||||
| Cálculo de custo | ID/versionamento, dependências/origens, componentes directos/CIF, quantidade elegível, custo exacto/unitário, residual, perímetro, exclusões e estado de completude |
|
||||
| Reconciliação de gestão | Corte e perímetro das origens, directo, destinado aos conjuntos, imputado, não imputado, excluído/por classificar e diferenças; cálculo preservado e autor |
|
||||
|
||||
Empresa/unidade/período/moeda/unidade de medida são obrigatórios antes de um cálculo ser considerado verificável. Não há taxa de custo, centro, política ou moeda funcional universais. Um valor de origem inclui identidade e propósito; não basta mesma descrição/valor/data. Um documento de origem pode conter parcelas com finalidades diferentes, cada uma identificada sem duplicação.
|
||||
|
||||
## 6. Acontecimentos, estados e dependências
|
||||
|
||||
- **Planeamento/necessidade** não é reserva/entrega/consumo. **Devolução de material não usado** reduz o bruto entregue, não cancela material efectivamente consumido. Não subtrair devolução duas vezes se o consumo já veio líquido.
|
||||
- **Tempo de trabalho directo**, pausa, deslocação, paragem e tempo de máquina são ocorrências/unidades diferentes. Tempo decorrido não é hora-pessoa ou hora-máquina. Reutilizar as validações propostas em oficinas, sem copiar cada apontamento para um módulo novo.
|
||||
- **Produção obtida**, classificação em boa/rejeitada, perda física e retrabalho são acontecimentos ligados, não unidades automaticamente equivalentes. Uma reclassificação não cria segunda produção. Retrabalho acrescenta recurso próprio ao alvo identificado; normalidade/elegibilidade de perda exigem política.
|
||||
- **Produção em curso** significa recursos aplicados a trabalho ainda não concluído no corte. Não a declarar produto acabado nem custo unitário final. Neste primeiro cálculo apenas lote concluído, sem WIP inicial/final; caso em curso fica pendente e fora do ensaio fechado.
|
||||
- **Venda/entrega/factura/recebimento** ficam fora do custeio de produção deste recorte. Custo calculado não cria saída de inventário, custo das vendas, receita ou recebimento.
|
||||
|
||||
Estados propostos: origem declarada → verificada operacionalmente; valorização pendente/provisória/validada; critério rascunho → submetido → aprovado/recusado; cálculo preparado → condicionado ou verificável → aprovado. Alterar uma origem/critério gera nova versão e cálculo novo; a versão aprovada anterior permanece como histórica, marcada como substituída/desactualizada para consulta actual quando necessário. Nunca reabrir período ou recalcular silenciosamente o aprovado.
|
||||
|
||||
| Dependência ainda não entregue | Consequência no primeiro recorte |
|
||||
| --- | --- |
|
||||
| Compras/inventário e valorização por movimento | Material usa medição e taxa sintéticas identificadas; não declara stock, disponibilidade ou custo de aquisição real |
|
||||
| Folha salarial/encargos | Taxa laboral sintética por unidade; no real, composição e base de horas precisam de suporte. Não usar preço de venda/hora ou expor remunerações ao técnico |
|
||||
| Activos/amortizações/manutenção/energia | Conjunto CIF de teste com valores/parcelas artificiais; não gerar amortização, factura de energia ou despesa real |
|
||||
| Planeamento/estruturas de produto/controlo de produção | Um lote e especificação mínima sintéticos; BOM, MRP, múltiplas etapas, produção conjunta/subprodutos e planeamento de capacidade detalhado ficam fora |
|
||||
| Motor de custeio/centros/imputações | São novos; a classificação contabilística actual não fornece este motor |
|
||||
|
||||
## 7. Regras de imputação, exactidão e reconciliação
|
||||
|
||||
1. **Uma origem, um acontecimento:** registar recurso uma vez e ligar suas parcelas aos destinos. Utilização por ordem de oficina ou industrial é uma dimensão explícita; não há conversão automática entre ordens. Se uma ordem técnica prestar manutenção a uma linha fabril, ligar o custo elegível como fonte/serviço interno por operação aprovada, sem duplicar o consumo/hora já existente.
|
||||
2. **Sem dupla elegibilidade:** uma mesma parcela não pode estar integralmente em custo directo e no conjunto CIF, em dois conjuntos ou em duas execuções activas. Repartição legítima conserva origem, quantidade e soma das percentagens/parcelas limitada ao elegível; transferir classificação exige nova versão/reversão rastreável.
|
||||
3. **Perímetro antes da taxa:** conjunto lista origens elegíveis, excluídas e por validar. Não misturar unidades, moedas, empresas ou períodos. Ausência de uma origem prevista não é custo zero. Um pool validado mas incompleto não suporta custo de produção completo.
|
||||
4. **Driver explícito:** `taxa = custo elegível do conjunto / denominador validado`; `parcela do destino = taxa × base elegível do destino`. Declarar se denominador é capacidade normal, base real ou outra base fundamentada. Denominador desconhecido/zero bloqueia imputação; não dividir só pelos destinos conhecidos para consumir tudo.
|
||||
5. **Capacidade:** fixos/variáveis e capacidade são dados/critério aprovados, não inferidos do nome da conta. Excesso de utilização/capacidade, custo sobreimputado ou destino fora da vigência produzem pendência/conflito; não aceitar saldo negativo no conjunto ou redefinir capacidade automaticamente.
|
||||
6. **Residual de gestão:** `origem elegível do conjunto = imputado + não imputado`, no mesmo corte. O não imputado tem motivo (capacidade não usada, destino ausente, base em falta, exclusão ou arredondamento de representação); não é todo automaticamente custo do produto. A classificação contabilística futura do residual depende da política aplicável; conservá-lo não dispensa essa avaliação.
|
||||
7. **Precisão:** reutilizar aritmética exacta/Brick Math; quantidades, taxas e montantes em cadeias decimais controladas, sem float ou redução silenciosa de escala. Não propagar a truncagem operacional do IVA aos custos. Divisões não finitas exigem representação racional exacta ou política explícita ainda a aprovar, não arredondamento oculto.
|
||||
8. **Resíduo de representação separado:** exemplo de limite aritmético: 100/3 em três destinos, se apresentado como 33,33 cada, dá 99,99 apresentados + 0,01 de diferença de representação. Isso não é mais um custo ou capacidade ociosa. Conservar 100/3 exacto e a diferença; não atribuir automaticamente o cêntimo ao último destino. O método de distribuição monetária, se necessário, exige política versionada. O exemplo principal evita esta ambiguidade.
|
||||
9. **Quantidades/unidades:** validar dimensionalmente kg×MZN/kg, H×MZN/H e HM×MZN/HM. Não somar kg com UN ou hora-pessoa com hora-máquina. Conversão só sob factor exacto com fonte/vigência. Unidades boas, perdas e WIP têm denominadores/estados próprios; não dividir por produção prevista para disfarçar produção real em falta.
|
||||
10. **Reconciliação global:** para um perímetro completo, `fontes de custo consideradas = custo directo atribuído + CIF imputado + CIF não imputado + outras parcelas explicitamente fora dos objectos/por classificar`, sem incluir o pool como se fosse outra origem. Reconciliação parcial identifica a cobertura e componentes em falta; não reportar diferenças como zero por ausência de valor.
|
||||
11. **Comandos/concorrência:** cálculo/aprovação idempotentes, com revisão/hash das dependências e bloqueios/uniquidades no servidor e base. Mesmo comando/conteúdo recupera IDs; outra chave não duplica imputação da origem. Falha em histórico/auditoria/outbox desfaz o conjunto. Mudança concorrente de fonte ou critério exige nova revisão, sem afectar cálculos históricos.
|
||||
12. **Eventos:** guardar origem/versão, cálculo/critério, corte, actor e correlação; consumidor repetido não volta a imputar. Contabilidade futura usará acontecimentos elegíveis sob regras próprias; não activar consumidores de lançamentos nesta componente documental.
|
||||
|
||||
Reconciliação de gestão explica **custos**, não confere conta bancária, pagamento de salário ou recebimento. Não usar os estados de reconciliação simulada de recebimentos como aprovação do custeio.
|
||||
|
||||
## 8. Exemplo sintético — lote concluído
|
||||
|
||||
Empresa Industrial Exemplo / Unidade Fabril Exemplo / Centro Fabrico A / período Outubro de 2026 / lote `LOT-TEST-1` / Produto Exemplo, unidade **UN**. Moeda **MZN** explícita. Uma etapa, 10 UN boas verificadas, sem WIP, perdas ou retrabalho neste exemplo, pressupostos artificiais declarados. Todos os custos abaixo são entradas de teste, não valores observados da Tempo ou documentos de compra/salário reais.
|
||||
|
||||
| Origem sintética e componente realizada | Quantidade/base | Custo/taxa e versão | Destino | Custo atribuído |
|
||||
| --- | ---: | --- | --- | ---: |
|
||||
| `MAT-TEST-1`, material directo líquido | 20 KG | 50,00 MZN/KG, valorização v1 específica de teste | Lote | 1 000,00 |
|
||||
| `TIME-TEST-1`, mão-de-obra directa verificada | 5 H | 100,00 MZN/H, taxa v1 de teste | Lote | 500,00 |
|
||||
| `POOL-TEST-1`, CIF fixos elegíveis, origem total 600,00 | Lote usa 5 HM; capacidade normal sintética do período 10 HM | Critério v1: 600/10 = 60,00 MZN/HM | Lote | 300,00 |
|
||||
| **Custo atribuído ao lote** | **10 UN boas** | 1 000 + 500 + 300 | — | **1 800,00** |
|
||||
| **Custo unitário de produção de gestão do ensaio** | **1 800/10 UN** | Sem arredondamento necessário | — | **180,00 MZN/UN** |
|
||||
|
||||
Material bruto entregue no ensaio: 22 KG; devolvido não consumido: 2 KG; consumo líquido: 20 KG. Se a fonte monetária for o bruto valorizado, 22×50 − 2×50 = 1 000. Se a fonte já for o líquido de 20 KG, não descontar 2 KG novamente. Os documentos/acontecimentos de entrega/devolução são distintos; não se movimenta inventário real.
|
||||
|
||||
Reconciliação do conjunto: **600,00 = 300,00 imputados + 300,00 não imputados** por capacidade não utilizada sob a hipótese sintética. Não elevar taxa a 120/HM só para absorver 600. O destino contabilístico do não imputado não é executado ou presumido pela prova.
|
||||
|
||||
Reconciliação global do perímetro: **2 100,00 de origens líquidas = 1 800,00 no lote + 300,00 não imputados**. Origens são 1 000 material + 500 mão-de-obra + 600 CIF. Não somar 600 e a parcela 300 como duas origens, nem somar o custo 1 800 novamente às suas componentes.
|
||||
|
||||
### Previsto versus realizado
|
||||
|
||||
Mesmo produto e quantidade de 10 UN, plano v1 anterior à execução; não é orçamento comercial:
|
||||
|
||||
| Componente | Previsto e composição | Realizado | Desvio realizado − previsto |
|
||||
| --- | ---: | ---: | ---: |
|
||||
| Material | 18 KG × 48,00 = 864,00 | 20 KG × 50,00 = 1 000,00 | +136,00 |
|
||||
| Mão-de-obra | 4 H × 100,00 = 400,00 | 5 H × 100,00 = 500,00 | +100,00 |
|
||||
| CIF imputados | 4 HM × 60,00 = 240,00 | 5 HM × 60,00 = 300,00 | +60,00 |
|
||||
| Custo do lote | **1 504,00** | **1 800,00** | **+296,00** |
|
||||
| Custo por UN boa | **150,40** | **180,00** | **+29,60** |
|
||||
|
||||
Decomposição definida, sem resíduo oculto: material `(20−18)×48 = 96` de quantidade e `20×(50−48) = 40` de taxa, total 136. Mão-de-obra `(5−4)×100 = 100`, sem desvio da taxa. CIF `(5−4)×60 = 60`, **apenas efeito da base neste critério**, não prova de eficiência/capacidade do período completo. Soma 136+100+60=296. Se a quantidade obtida diferir da prevista, comparar primeiro volumes/perímetro compatíveis e declarar o efeito de volume; não chamar todo desvio a desperdício ou desfavorabilidade comprovada.
|
||||
|
||||
Não foi assumida venda, preço, IVA ou margem. Produzir dez unidades não demonstra que foram vendidas nem que 1 800 deva ser reconhecido como custo das vendas.
|
||||
|
||||
### Variante de custo em falta
|
||||
|
||||
Quantidade consumida 20 KG conhecida, mas taxa de valorização do material ausente: custo do material **pendente**, sem usar 50 ou preço de venda por omissão. Subtotal atribuído conhecido = 500 mão-de-obra + 300 CIF = **800,00**. Custo total, custo unitário completo e desvio total ficam **indisponíveis**. É possível mostrar 800/10 = 80 por UN **apenas como componente conhecida**, nunca como custo unitário completo.
|
||||
|
||||
Reconciliação das origens conhecidas: **1 100 = 800 atribuídos + 300 não imputados**, com componente material em falta explicitamente fora desta igualdade parcial. Quantidade conhecida não completa cobertura monetária. A variante do residual já existe no caso principal; nenhuma distribuição adicional é feita para esconder os 300.
|
||||
|
||||
## 9. Responsabilidades, confidencialidade e isolamento
|
||||
|
||||
Funções propostas, sem concessões ou pessoas designadas:
|
||||
|
||||
| Função | Acções propostas | Acesso delimitado |
|
||||
| --- | --- | --- |
|
||||
| Recolha operacional | Registar/verificar quantidades, tempos, produção e evidências do âmbito atribuído | Não vê taxas salariais individuais, custo/margem ou preços por consequência |
|
||||
| Validação de custos | Conferir composição, origem, elegibilidade e versão das taxas/valores | Apenas unidades/centros e dados de origem necessários, com eventual agregação de remunerações |
|
||||
| Aprovação de critérios | Validar conjunto, driver, denominador/capacidade, período, vigência, exclusões e residual | Não é poder de emissão, gestão de acessos ou alteração das origens operacionais |
|
||||
| Preparação/análise | Calcular sob critérios aprovados, comparar previsto/realizado e consultar reconciliação | Consulta de custos separada de preços/receita/margem; não aprova a própria competência por nome |
|
||||
| Consulta de margens | Ver indicador sob perímetro autorizado e completude explícita | Direito próprio; exige também autorização às fontes/dimensões usadas. Não extrair remunerações individuais |
|
||||
|
||||
Catálogo funcional proposto: `industrial_costs.operational_input`, `.view`, `.value`, `.propose_criteria`, `.approve_criteria`, `.calculate`, `.approve_result`, `.view_margin`. Separar consulta operacional, custos e margem; não herdar direitos de conta contabilística, administração, oficina ou emissão. A matriz de contas/âmbitos e eventual separação de autores serão decisões específicas antes de conceder direitos.
|
||||
|
||||
Centro empresarial reutilizável não abre dados de todas as unidades. Primeiro recorte não reparte custos entre unidades; extensão exige fontes e destinatários autorizados, período/driver e protecção dos resultados agregados. Negar também inferência por totais, APIs, eventos/exportações ou pesquisas de origem de outra empresa do mesmo tenant. Nova unidade/alteração de categoria não muda implicitamente permissões.
|
||||
|
||||
## 10. Matriz de reutilização com oficinas e SGF
|
||||
|
||||
| Elemento | Existe no SGF hoje | Proposto em oficinas | Proposta industrial / trabalho novo |
|
||||
| --- | --- | --- | --- |
|
||||
| Contexto e acesso | Identidade, empresa/unidade, sessão, concessões explícitas, auditoria | Aplicar às ordens/técnicos e custos | Reutilizar mecanismos; acrescentar objectos, centros e direitos próprios |
|
||||
| Catálogos | Clientes/serviços empresariais e classificação contabilística versionada | Bem individual e recursos/materiais operacionais novos | Produto e centro de custo novos; não duplicar serviço nem confundir bem intervencionado com produto fabricado |
|
||||
| Tempo | Aritmética exacta existente, sem módulo entregue de apontamentos | Intervalos/pausas, técnico, deslocação, unidade e validação propostos | Reutilizar **a mesma origem de tempo** quando for o mesmo acontecimento; acrescentar papel directo/indirecto, máquina e destino de custo |
|
||||
| Material | Não há stock/compras/custeio operacional entregues | Necessidade, custódia/entrega, consumo observado e devolução propostos | Mesmo evento canónico/versão e propriedade; valorização e destino novos. Não criar novo consumo só porque passou ao cálculo |
|
||||
| Documentos de origem | Histórico, B1, preparação/pré-visualização e factura sintética | Diagnóstico/proposta/aceite/relatório e vínculo a rascunho, ainda por construir | Documento de custo e ordem de produção próprios; nunca importar aceite da oficina como produção validada |
|
||||
| Custos/preços | Valores exactos e classificação, sem motor de custo industrial | Separação custo/quantidade/preço e estado de custo proposta | Acrescentar planos de custo, conjuntos CIF, critérios, imputações, composição e desvios |
|
||||
| Eventos/comandos | Padrões transaccionais/outbox/idempotência entregues | Novos tipos de recurso/ordem propostos | Reutilizar padrões e IDs, não alterar eventos históricos para fingir produção; não activar lançamentos |
|
||||
| Reconciliação | Recebimentos apenas em simulação, entrega não presumida aceite | Conferência de recursos/custódia proposta | Reconciliação de gestão nova; sem reutilizar estado bancário/recebimento como validação de custos |
|
||||
| Histórico | Fotografias/eventos imutáveis e versões | Versões de autorização, execução e facturabilidade propostas | Versões de origem, critério e cálculo, aprovação e substituição explícita |
|
||||
|
||||
Oficinas e indústria partilham contratos tipados de recurso/tempo/origem, **não a mesma máquina de estados**. Apenas o identificador comum de origem impede dupla captura; ligar uma ordem técnica a centro/lote exige intenção autorizada. Não desenvolver antecipadamente um motor universal ou duas tabelas sem ligação para o mesmo consumo.
|
||||
|
||||
## 11. Critérios de aceitação futuros
|
||||
|
||||
- Demonstrar o lote sintético: fontes 2 100, atribuído 1 800, residual 300, 10 UN boas, custo 180/UN e desvio 296 explicáveis pelos IDs e versões. Nenhuma venda/factura/recebimento ou lançamento criado.
|
||||
- Material com custo desconhecido dá subtotal conhecido 800 e pendência; total/unitário completo e desvio indisponíveis. Valor zero validado continua distinto de ausência e de não aplicável.
|
||||
- Origem repetida, mesma/diferente chave e consumidor repetido não duplicam consumo/atribuição. Bloquear parcela simultaneamente directa/indirecta ou em dois conjuntos/destinos para além do elegível.
|
||||
- Driver zero/desconhecido, moeda ou unidade incompatível, capacidade fora da política, período/critério desactualizado e quantidade de boas desconhecida recusam cálculo/aprovação integral, sem redistribuição automática.
|
||||
- Preservar exactidão e resíduo de representação separado de residual económico. Repartições reconciliam por origem/destino/corte; não esconder diferença por arredondamento ou conta transitória.
|
||||
- Correcção de consumo/taxa/critério gera nova versão, invalida apenas resultados dependentes para uso actual e conserva aprovado anterior. Aprovação antiga, concorrência e SQL em massa não reescrevem história.
|
||||
- Falha antes do commit deixa zero efeito parcial; resposta perdida recupera resultado; concorrência sobre parcela de origem e orçamento/conjunto não sobreimputa. Auditoria/evento/outbox na mesma transacção.
|
||||
- Quantidades brutas/devoluções/líquidas não contadas duas vezes. Tempos de máquina/pessoa e produção boa/perda/retrabalho/WIP distintos. Ordem de oficina não se transforma implicitamente em lote.
|
||||
- Negar URL/API/consumidor e exportação fora de empresa/unidade/centro autorizados; técnico/recolha não consulta custo salarial ou margem; revogação/contexto antigo têm efeito no pedido seguinte.
|
||||
- Caso em curso/múltiplas etapas/produtos conjuntos não recebe custo unitário final por adaptação silenciosa do ensaio. Provas futuras exclusivamente sintéticas em `sgf_tempo_test`, com os bloqueios reais preservados.
|
||||
|
||||
## 12. Decisões realmente novas e faseamento coordenado
|
||||
|
||||
Decisões para aprovar antes de uma futura implementação, sem reabrir PGC-NIRF da Tempo, fiscalidade ou recebimentos:
|
||||
|
||||
1. **Destinatário e recorte:** identificar a primeira actividade/produto industrial e confirmar se uma ordem/lote de etapa única é representativa. Até lá, aceitar apenas o ensaio sintético por ordem, sem escolher método real.
|
||||
2. **Perímetro e dados:** quais custos/fontes estão disponíveis, unidade e período, política de custos provisórios e quem valida. Não requerer capítulos dos livros para usar a base já fornecida; só pedir capítulo exacto se uma decisão realmente depender dele.
|
||||
3. **Critério e representação:** aprovar conjunto/driver/capacidade e destino de residual do recorte; política de representação quando a divisão não for finita. Não impor método de arredondamento fiscal por preferência de interface.
|
||||
4. **Responsáveis e acesso:** quem recolhe, valida custos, aprova critérios/resultados e consulta margens, em que empresa/unidade/centros. Não nomear automaticamente Osmane/Samira ou reutilizar concessões de oficinas.
|
||||
|
||||
Faseamento proposto:
|
||||
|
||||
| Fase | Entrega delimitada | Condição de passagem |
|
||||
| --- | --- | --- |
|
||||
| 1 — Oficinas | Fechar recorte e decisões de `WORKSHOP-ASSISTANCE-DRAFT-v1`; propor contratos mínimos de recurso/tempo/material observado e origem | Aprovação específica desse âmbito; não implementar indústria como dependência oculta |
|
||||
| 2 — Base comum necessária | Implementar somente registos/IDs/versionamento e unidades efectivamente exigidos pelo primeiro percurso autorizado | Captura única e isolamento demonstrados; consumo técnico não finge stock. Se oficinas não avançar primeiro, esta base pode ser delimitada no ensaio industrial sem declarar oficina entregue |
|
||||
| 3 — Ensaio industrial | **INDUSTRIAL-COST-SIM-v1**: um lote concluído/produto/unidade/período/MZN, material e horas sintéticos, um conjunto/critério CIF, previsto/realizado, custo unitário, residual e variante em falta | Autorização de código/testes separada; apenas demonstração isolada, sem integrações ou valorização legal activada |
|
||||
| 4 — Aplicação real futura | Integrar origens efectivas e política empresarial/normativa validada | Novo âmbito para stock/compras/folha/activos, valorização/reconhecimento e acessos. Não decorre da aprovação do ensaio |
|
||||
|
||||
Produção em curso complexa, produtos conjuntos, subprodutos, perdas complexas, múltiplas etapas, ABC, repartição entre unidades, câmbio, custo das vendas e fecho são extensões explicitadas. As duas especificações partilham a fundação mas mantêm responsabilidades, acontecimentos e estados distintos.
|
||||
|
||||
**Menor incremento útil proposto para aprovação:** fase 3 limitada ao exemplo e respectivas guardas, reutilizando apenas a base comum estritamente necessária, após delimitar as fases anteriores. Esta etapa entrega só o desenho; não autoriza essa execução, não altera recebimentos ou conformidade e não atribui aceitação a nenhuma entrega existente.
|
||||
|
||||
## 13. Prioridade posterior: captar recursos na oficina primeiro
|
||||
|
||||
Em 27/10/2026, o utilizador propôs começar pela ordem de oficina, com materiais e tempos de origem identificada. O primeiro recorte coordenado passa a ser a proposta **`WORKSHOP-RESOURCE-RECORD-v1`**, delimitada na [secção 13 de oficinas](WORKSHOP_MANAGEMENT_SCOPE.md#13-primeiro-recorte-coordenado--ordem-e-recursos), antes da conversão comercial e do ensaio industrial. Esta orientação não autoriza implementar qualquer uma das componentes.
|
||||
|
||||
O custeio posterior ligará quantidade/tempo **já registados e verificados**, por ID e versão, a uma valorização e destino de custo próprios. Não voltará a registar consumo, tempo, devolução ou produção para conseguir calcular. O primeiro incremento não calcula custos nem exige que se escolha um método industrial. Uma ordem de oficina continua a ser ordem técnica; não nasce automaticamente uma ordem/lote de produção.
|
||||
|
||||
Assim, as fases 1/2 da secção 12 ficam inicialmente reduzidas à ordem, apontamentos e base de origem estritamente necessária; a proposta mais ampla `WORKSHOP-ASSISTANCE-DRAFT-v1` fica para evolução posterior. `INDUSTRIAL-COST-SIM-v1`, critérios CIF, custos e margens permanecem em especificação. Preservar bloqueios reais e a aceitação independente de `SGF-RECEIVABLES-SIM-v1`.
|
||||
|
||||
## 14. Decisões confirmadas — primeiro custo directo da ordem
|
||||
|
||||
Em 27/10/2026, o utilizador confirmou as três decisões seguintes. Este recorte antecede o lote industrial e a imputação de custos indirectos das secções anteriores; não converte a ordem de oficina em ordem de produção. Oficinas e recebimentos já têm aceitação própria e instalação técnica documentada; não se reabrem essas aprovações. As referências anteriores a componentes ainda não entregues são históricas e devem ser confrontadas com as respectivas entregas actuais.
|
||||
|
||||
### Ensaio e variante
|
||||
|
||||
Uma ordem sintética, empresa/unidade autorizadas, moeda MZN explícita, apenas origens técnicas verificadas e versões exactas:
|
||||
|
||||
| Componente | Origem reutilizada | Taxa sintética | Custo conhecido |
|
||||
| --- | --- | --- | ---: |
|
||||
| Material | 2 UN efectivamente consumidas e verificadas | 50,00 MZN/UN | 100,00 MZN |
|
||||
| Mão-de-obra | 105 MIN efectivos e verificados; 105/60 = 1,75 H | 100,00 MZN/H | 175,00 MZN |
|
||||
| **Soma do perímetro directo conhecido** | Mesma ordem e corte | Sem custos indirectos | **275,00 MZN** |
|
||||
|
||||
O resultado é **custo directo conhecido**, nunca custo completo, custo industrial unitário, margem ou lucro. As taxas são pressupostos identificados de ensaio, não valorização real de inventário ou política salarial.
|
||||
|
||||
Na variante sem taxa do material: **175,00 MZN conhecidos**, material pendente, total incompleto. Não usar zero, taxa anterior, preço de venda ou taxa de outra origem por omissão. Não apresentar 175,00 como total completo.
|
||||
|
||||
### Origem única e preservação
|
||||
|
||||
Ligar valorização e cálculo aos IDs e versões dos apontamentos existentes da oficina, sem recapturar quantidades ou criar segundo consumo/tempo. Material entregue/devolvido não substitui consumo; não descontar devolução novamente do consumo já líquido. Usar apenas apontamentos verificados elegíveis, preservando excepções e decisões técnicas. A validação de custos não altera nem valida automaticamente esses apontamentos.
|
||||
|
||||
Guardar a origem e versão da taxa, a unidade, moeda, composição e pendências. Alteração da origem ou taxa exige nova versão/revisão de custos; não reescrever cálculo histórico ou utilizar aprovação antiga para dependências novas. Reutilizar aritmética exacta; nenhuma regra de truncagem de IVA é transferida aos custos.
|
||||
|
||||
### Responsabilidades confirmadas e limites
|
||||
|
||||
**Osmane prepara; Samira valida a versão dos custos e das taxas.** Samira pode validar/recusar a proposta de custos, sem editar os apontamentos técnicos ou receber supervisão técnica por consequência. Testes futuros com identidades sintéticas distintas entre preparação e validação. Nenhuma nova concessão real é autorizada por estas decisões.
|
||||
|
||||
Lote industrial e custos indirectos ficam para incremento seguinte. Sem stock, compras, salários reais, facturação, IVA, recebimentos, lançamentos, fecho ou publicação. Manter bloqueios operacionais/fiscais e isolamento em `sgf_tempo_test` nas futuras provas. Esta confirmação fecha as decisões do recorte; não constitui ordem de implementação, migração, concessão ou activação operacional.
|
||||
@@ -0,0 +1,82 @@
|
||||
# Entrega A — serviços em rascunho
|
||||
|
||||
25 de Outubro de 2026. Entrega A aceite pelo utilizador no âmbito demonstrado e com os limites documentados. O checkpoint `26b80df` foi preservado; versões, manifests e lockfiles não foram alterados.
|
||||
|
||||
## Aceitação
|
||||
|
||||
Em 25 de Outubro de 2026 (Africa/Johannesburg), o utilizador declarou: «Aceito a entrega A no âmbito demonstrado e com os limites documentados. Regista a aceitação e preserva um checkpoint Git local, sem credenciais ou dados locais. Não avances ainda para B/C nem publiques.»
|
||||
|
||||
Esta aceitação encerra apenas A. O checkpoint contém código, migração, documentação e provas sintéticas; exclui configurações privadas, credenciais, bases, sessões, logs e o plano operacional específico de concessões locais. Não autoriza B/C ou publicação.
|
||||
|
||||
## Percurso funcional
|
||||
|
||||
Depois de entrar e seleccionar empresa/unidade autorizadas, estão disponíveis Clientes, Serviços, Prestações em rascunho e Rascunhos de facturação, conforme concessões explícitas.
|
||||
|
||||
- Clientes e serviços pertencem à empresa e são reutilizados entre unidades. Nome é o único campo obrigatório do cliente.
|
||||
- Prestações e rascunhos de facturação pertencem à unidade autorizada. A facturação reutiliza cliente, linhas, moeda indicada e versão da prestação.
|
||||
- Consulta, criação, edição e gestão de concessões são separadas nas quatro áreas. Direitos de identidade não concedem automaticamente direitos de A. Gestores só delegam direitos que possuem no mesmo âmbito.
|
||||
- Alterações preservam versões, histórico, eventos duráveis, outbox, pendências e resultado idempotente na mesma transacção. Repetir o comando não duplica o registo ou evento; versões e contextos antigos são recusados.
|
||||
- Alterar a prestação gera uma pendência nos rascunhos de facturação associados. Actualizar explicitamente da prestação cria outra versão, preservando a anterior.
|
||||
|
||||
Quantidades e preços são cadeias decimais não negativas, com até 16 algarismos inteiros e 8 decimais; quantidade preenchida deve ser positiva. Entradas excedentes são recusadas, sem arredondamento. Produtos e somas derivados usam aritmética decimal exacta, podendo exigir mais casas. A base aritmética não é total fiscal nem valor definitivo a pagar. Moeda não é presumida; imposto desconhecido não é zero. Mesmo com código de moeda preenchido permanece pendente a sua validação. Regras fiscais e contabilísticas continuam explicitamente pendentes.
|
||||
|
||||
Não há confirmação financeira, emissão de factura, lançamento contabilístico, recebimento, correcção financeira, reconciliação ou fecho. O outbox fica em captura durável, sem processamento contabilístico. B/C dependem de regras e autorização próprias.
|
||||
|
||||
## Migração e preservação de dados
|
||||
|
||||
Aplicada em `sgf_tempo_dev`, pelo wrapper de migrações e proprietário separado, a migração aditiva `2026_10_25_030000_create_services_delivery_a` (batch 4). A aplicação conserva o papel `sgf_dev_app`, sem administração PostgreSQL.
|
||||
|
||||
O delta cria nove tabelas: `a_clients`, `a_services`, `a_service_drafts`, `a_billing_drafts`, `a_history`, `a_events`, `a_outbox`, `a_pending` e `a_commands`. Amplia o catálogo permitido de concessões, sem conceder acessos automaticamente. Inclui relações de âmbito, protecção SQL contra transferências de pertença, validação de dados e protecção append-only. O escopo Eloquent não é a única fronteira de isolamento.
|
||||
|
||||
Não foi executado reset/fresh/wipe em desenvolvimento. As duas contas, tenant, empresa, unidade e oito concessões de identidade foram preservados. Após a implementação, as nove tabelas de A estavam vazias em desenvolvimento: as demonstrações usaram exclusivamente `sgf_tempo_test`.
|
||||
|
||||
## Concessões especificamente confirmadas
|
||||
|
||||
As contas foram conferidas antes da aplicação; nenhuma foi criada ou associada por suposição. O utilizador confirmou exactamente estas contas e concessões:
|
||||
|
||||
| Conta existente | Clientes / serviços — Tempo Lda, empresa 1 | Prestações / facturação em rascunho — SEGI, unidade 1 |
|
||||
| --- | --- | --- |
|
||||
| ID 1 — Osmane Nala, nala@tempo.co.mz | Consulta, criação, edição e gestão em cada área | Consulta, criação, edição e gestão em cada área |
|
||||
| ID 2 — Samira Nal, onala@me.com | Consulta em cada área | Consulta em cada área |
|
||||
|
||||
Foram aplicadas e auditadas 16 concessões para Osmane e 4 para Samira, mantendo as oito anteriores (28 no total). Não há direitos implícitos noutras unidades ou poderes financeiros. Os emails apenas identificaram as contas nesta operação confirmada; não determinam privilégios durante a execução da aplicação.
|
||||
|
||||
O plano operacional local `scripts/a-access-plan.php` conserva a pré-visualização e as verificações da operação, mas fica excluído do checkpoint por conter identificações locais. Não repetir `--apply` após alterações posteriores dos direitos sem nova confirmação específica. `scripts/a-status.php` permite verificar estado sem apresentar segredos.
|
||||
|
||||
## Verificação realizada
|
||||
|
||||
- Suite completa: **44 testes, 273 asserções, todos aprovados**, incluindo a fundação anterior.
|
||||
- Compilação Vite: aprovada. Nenhuma dependência ou versão foi substituída.
|
||||
- Testes de isolamento entre empresas, inclusive do mesmo tenant, e unidades; identificadores manipulados; consulta sem escrita; ausência de herança implícita; limites de delegação; versões/contextos antigos; alterações SQL em massa; histórico imutável; rollback integral com falha injectada no outbox.
|
||||
- Dois processos PHP concorrentes: criação repetida produziu um registo/evento; edição concorrente terminou em 200/409, com apenas uma nova versão/evento. [Resultado](proofs/a-concurrency.json).
|
||||
- HTTP com login real de contas sintéticas: leitura 200, alteração/gestão recusadas 403, concessão/revogação efectivas no pedido seguinte da mesma sessão, contexto/versão antigos 409, protecção CSRF 419 e cookie de sessão terminada 401. [Resultado](proofs/a-http-results.json).
|
||||
- Captura durável na prova: 9 versões, 9 eventos, 9 entradas de outbox, 9 resultados de comandos, sem eventos órfãos; estado apenas `captured`. [Métricas](proofs/a-durable-capture.json).
|
||||
- `verify-foundation.php` confirmou isolamento de papéis e ausência de contas sintéticas na base de desenvolvimento.
|
||||
|
||||
A prova visual utilizou uma instância isolada na porta 8001, ligada apenas a `sgf_tempo_test`, com sessões/cache próprios, CSRF activo e utilizadores sintéticos equivalentes. Incluiu login pelo formulário, criação de cliente/serviço/prestação, recusa de precisão excessiva, preparação e edição de rascunho de facturação, histórico e gestão delimitada de acessos. O utilizador de consulta viu os registos sem botões de criação, edição ou gestão. Não se tratou apenas de `actingAs`.
|
||||
|
||||
Provas: [precisão recusada](proofs/a-01-precision-refused.png), [rascunho](proofs/a-02-draft-pending.png), [histórico e pendências](proofs/a-03-history-and-pending.png), [consulta](proofs/a-04-read-only.png).
|
||||
|
||||
A instância de prova foi parada e a suite executada novamente para limpar os dados sintéticos na base de testes. A aplicação normal permaneceu na porta 8000, sem alteração de ligação ou dados de demonstração na Tempo Lda/SEGI. Não foram terminados processos de outros projectos.
|
||||
|
||||
## Ficheiros e utilização
|
||||
|
||||
Implementação em `app/Modules/Services` (permissões, valores, workflow, acessos e controlador), migração acima, `resources/js/ServicesWorkspace.jsx`, integração em `app.jsx`, CSS e rotas. A fundação de identidade foi reutilizada; a auditoria recebeu metadados de A e a listagem antiga de acessos ficou delimitada ao seu catálogo.
|
||||
|
||||
Testes em `tests/Feature/ServicesDeliveryATest.php` e `tests/Support/ServicesFixture.php`; procedimentos de prova em `scripts/a-concurrency-proof.php`, `a-concurrency-worker.php`, `a-http-proof.mjs` e `a-proof-metrics.php`, com preparação de fixtures sintéticas adaptada. README e especificação foram actualizados.
|
||||
|
||||
Para utilizar, actualizar o navegador em http://127.0.0.1:8000, entrar normalmente e seleccionar Tempo Lda/SEGI. Seguir o percurso do [README](../README.md). Não executar os scripts de fixtures para criar dados reais. A recuperação local assistida da identidade mantém-se documentada em [IDENTITY_WORKFLOW.md](IDENTITY_WORKFLOW.md); não há recuperação por email.
|
||||
|
||||
Comandos de verificação, a partir do projecto:
|
||||
|
||||
```powershell
|
||||
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\sgf.ps1 test
|
||||
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\sgf.ps1 npm run build
|
||||
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\sgf.ps1 php scripts/a-status.php
|
||||
```
|
||||
|
||||
As provas destrutivas continuam bloqueadas fora de `sgf_tempo_test`. Parar a instância de navegador de testes antes de executar a suite que recria essa base. Os scripts de prova de concorrência e métricas têm também verificação própria do destino. Não mudar a aplicação normal para a base de testes.
|
||||
|
||||
## Limites e próxima decisão
|
||||
|
||||
A entrega A foi aceite com estes limites. Não define regime fiscal, numeração, moeda funcional, plano de contas, reconhecimento ou arredondamento fiscal. Não inclui emissão, processamento contabilístico ou processamento externo do outbox. Não foi publicada nem iniciado outro incremento. A especificação B/C permanece como proposta, sem autorização de execução.
|
||||
@@ -0,0 +1,78 @@
|
||||
# B1 — confirmação interna e fotografia histórica
|
||||
|
||||
Data: 25 de Outubro de 2026 (Africa/Johannesburg). Estado: B1 aceite pelo utilizador no âmbito demonstrado de confirmação interna, sem validade fiscal nem lançamentos contabilísticos. Não constitui conclusão integral de B. A permanece aceite no checkpoint `ca13acb`, com antecessor `26b80df`; nenhum foi substituído ou reaberto.
|
||||
|
||||
## Aceitação
|
||||
|
||||
Em 25 de Outubro de 2026, o utilizador declarou: «Aceito B1 no âmbito demonstrado de confirmação interna, sem validade fiscal nem lançamentos contabilísticos. Regista a aceitação e preserva um checkpoint Git local, sem credenciais ou dados locais. Não avances para os restantes incrementos nem publiques.»
|
||||
|
||||
O checkpoint preserva código, migração, documentação e provas sintéticas. Exclui credenciais, configurações privadas, bases, sessões e logs. As contagens de desenvolvimento neste relatório são evidência histórica da entrega, não uma cópia dos dados locais. A aceitação encerra apenas B1 e mantém os limites abaixo.
|
||||
|
||||
## O que ficou funcional
|
||||
|
||||
Um utilizador com `billing_drafts.view` e a nova concessão explícita `billing_drafts.confirm_internal`, na empresa/unidade seleccionadas, pode abrir o rascunho, rever a operação e confirmar uma versão actual. A interface apresenta **«Confirmado internamente — sem validade fiscal»** e referência técnica `INT-B1-<id>`, distinta de numeração fiscal.
|
||||
|
||||
A confirmação exige cliente/serviços válidos na empresa, prestação na mesma unidade, versão da prestação correspondente à origem guardada, designação e linhas com quantidade positiva/preço não negativo completos. Reutiliza as validações decimais de A. Campos e identificadores protegidos enviados pelo navegador são recusados. Empresa/unidade, pertenças e permissão são revalidadas no servidor dentro da transacção, após bloquear a empresa e antes da operação. A sessão e o token de contexto existentes continuam em uso.
|
||||
|
||||
Moeda desconhecida é conservada como `null`, com pendência explícita. Imposto permanece pendente e não é convertido em zero. Mesmo uma moeda preenchida continua sujeita a validação. A base aritmética usa decimais exactos e não se apresenta como total monetário definitivo ou fiscal; não há agregação de moedas distintas.
|
||||
|
||||
A fotografia conserva o rascunho e a prestação com versões/dados originais, cliente e serviços com versões/dados observados, linhas e valores usados, moeda conhecida ou desconhecida, pendências, âmbito, autor e instante. Os nomes nas linhas e identificação do cliente usados na confirmação são conferidos no cadastro actual, que também fica fotografado; a versão original do rascunho continua preservada separadamente. Alterações posteriores dos cadastros ou da prestação não reescrevem a fotografia.
|
||||
|
||||
A confirmação cria uma identidade própria, sem transformar a prestação em serviço confirmado. O rascunho de origem mantém a versão fixada e fica bloqueado para edição/eliminação. API e triggers SQL impedem actualizações em massa ou eliminação do rascunho confirmado; a fotografia tem protecção append-only. Não há reabertura, correcção ou anulação. A prestação e os cadastros continuam com o comportamento de A, preservando as suas versões.
|
||||
|
||||
## Captura e repetição
|
||||
|
||||
Confirmação, fotografia, histórico, evento `b1.billing_draft.confirmed_internal`, pendências, auditoria e resultado do comando são persistidos na mesma transacção. A captura reutiliza `a_history`, `a_events`, `a_outbox`, `a_pending` e `a_commands`; os eventos de A não são reconstruídos ou alterados.
|
||||
|
||||
O outbox permanece `captured`, sem consumidor contabilístico. A fotografia mostra `not_issued` para fiscalidade e `blocked_pending` para contabilidade. Além das pendências de A, contas/classificação e reconhecimento ficam explicitamente pendentes. Não há lançamentos, receita reconhecida ou estado contabilizado.
|
||||
|
||||
Repetição com mesma chave/autor/conteúdo recupera o resultado. Conteúdo diferente com a mesma chave produz 409. Outra chave para o mesmo rascunho/versão recupera a confirmação existente, sem novo evento. A unicidade por rascunho e bloqueios transaccionais impedem confirmações concorrentes duplicadas. Como não há reabertura, não se confirmam versões posteriores do rascunho já fixado. Resolução futura de pendências exigirá registos/versionamento próprios, sem editar a fotografia.
|
||||
|
||||
## Migração e acesso aplicados
|
||||
|
||||
O delta foi apresentado antes da aplicação. Migração aditiva `2026_10_25_040000_create_internal_confirmations`, aplicada em `sgf_tempo_test` pelas provas e depois em `sgf_tempo_dev` pelo wrapper, com proprietário separado:
|
||||
|
||||
- Cria apenas `b_internal_confirmations`, com referência única ao rascunho, versão, âmbito composto, fotografia, autor e instante.
|
||||
- Acrescenta triggers de validade/imutabilidade e bloqueio do rascunho confirmado; amplia a validação de `a_history` para a nova origem sem remover as origens de A.
|
||||
- Acrescenta `billing_drafts.confirm_internal` ao catálogo SQL permitido, sempre com unidade explícita. Não concede esse direito pela migração, por nome/email ou por direitos de A.
|
||||
- Não modifica dados históricos de A nem cria tabelas de lançamentos, numeração fiscal ou processamento contabilístico. O rollback automático desta migração é recusado para não eliminar confirmações históricas; qualquer reversão requer procedimento de preservação revisto.
|
||||
|
||||
A conta existente foi conferida e apresentada: ID 1, Osmane Nala, na empresa Tempo Lda ID 1 / SEGI ID 1. O utilizador confirmou exactamente a nova concessão antes da aplicação. Foi aplicada **uma** concessão `billing_drafts.confirm_internal`, com auditoria `b1.access.initial_grant`. Samira mantém apenas consulta; os restantes direitos de A foram preservados. Total de concessões em desenvolvimento: 29. Não foram criadas contas, nem poderes de gestão da nova concessão, emissão, contabilização, recebimento ou fecho.
|
||||
|
||||
O procedimento local `scripts/b1-access.php user_id company_id unit_id` permite pré-visualizar a conta/âmbito. `--apply` só deve ser usado depois de confirmação específica da operação apresentada. Não o executar como seed ou criação automática de direitos. A interface de gestão de A não permite delegar `confirm_internal`; alterações futuras desta concessão continuam a exigir procedimento local autorizado e auditado. `scripts/b1-status.php` verifica contagens e a concessão sem mostrar credenciais.
|
||||
|
||||
Depois da aplicação: duas contas, um tenant, uma empresa e uma unidade preservados; clientes, serviços, prestações, rascunhos e confirmações em desenvolvimento continuavam vazios. Não foi criado qualquer documento interno real ou de demonstração na Tempo Lda/SEGI. A aplicação normal conserva `sgf_dev_app`, sem administração PostgreSQL, e a ligação à base de desenvolvimento.
|
||||
|
||||
## Provas realizadas
|
||||
|
||||
Suite completa: **58 testes / 442 asserções aprovados**, incluindo regressões de identidade e A, sem reabrir a sua aceitação. Compilação Vite aprovada, sem alteração de versões, manifests ou lockfiles.
|
||||
|
||||
Os 14 testes de B1 cobrem confirmação autorizada; consulta e gestor de A sem nova permissão recusados; revogação efectiva no pedido seguinte da mesma sessão; impossibilidade de delegar o novo direito pela gestão de A; âmbito manipulado; acesso cruzado entre unidades e entre empresas do mesmo tenant; versão/contexto antigos; fotografia preservada após alterações de cliente, serviço e prestação; moeda/regra desconhecidas; linhas incompletas; origem desactualizada; repetição/conflito; bloqueio API e SQL de edição/eliminação; fotografia append-only; falha injectada no outbox com rollback integral, incluindo auditoria e comando.
|
||||
|
||||
Prova de concorrência com **dois processos PHP reais**, sobre PostgreSQL e com sobreposição demonstrada de bloqueios: chaves iguais e chaves diferentes produziram apenas uma confirmação e um evento por rascunho. [Resultado](proofs/b1-concurrency.json).
|
||||
|
||||
Prova HTTP com autenticação real de contas sintéticas, CSRF activo e sessões distintas: confirmação autorizada, leitor recusado 403, contexto/versão antigos 409, repetição recuperada, conteúdo diferente 409, alteração de rascunho confirmado 409 e fotografia inalterada após edição dos cadastros. [Resultado](proofs/b1-http-results.json).
|
||||
|
||||
No navegador isolado em http://127.0.0.1:8001, ligado exclusivamente a `sgf_tempo_test`, o gestor entrou pelo formulário, preparou um rascunho e confirmou-o pela revisão explícita. A interface mostrou moeda desconhecida, referência interna, fotografia e pendências. Após saída, a conta de consulta entrou pelo formulário e consultou a fotografia sem botões de criação, edição, gestão ou confirmação. Não foi apenas uma prova com `actingAs`.
|
||||
|
||||
Provas visuais: [confirmação interna e pendências](proofs/b1-01-internal-confirmation.png) e [consulta com contexto sintético](proofs/b1-02-read-only-context.png). [Métricas de captura](proofs/b1-capture.json) verificam correspondência entre confirmações, históricos, eventos e outbox.
|
||||
|
||||
A instância de prova foi parada; a suite final limpa os dados sintéticos apenas na base de testes. Não se alterou a ligação da aplicação normal, não se terminaram processos de outros projectos e não se publicaram conteúdos.
|
||||
|
||||
## Ficheiros e comandos
|
||||
|
||||
Novo workflow `app/Modules/Services/InternalConfirmation.php`, integração em `ServiceController.php`, `ServiceWorkflow.php`, `routes/web.php`, `ServicesWorkspace.jsx` e rodapé de `app.jsx`; migração indicada acima. A integração acrescenta estado de confirmação à lista, protege o rascunho e evita pendências posteriores de origem reescreverem a captura já confirmada.
|
||||
|
||||
Testes em `tests/Feature/InternalConfirmationTest.php`, fixture `tests/Support/InternalConfirmationFixture.php`; preparação de navegador adaptada e worker de concorrência existente reutilizado. Scripts próprios: `b1-access.php`, `b1-status.php`, `b1-concurrency-proof.php`, `b1-http-proof.mjs` e `b1-proof-metrics.php`. Documentação actualizada em AGENTS, README e especificações, respeitando as alterações posteriores a A.
|
||||
|
||||
```powershell
|
||||
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\sgf.ps1 test
|
||||
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\sgf.ps1 npm run build
|
||||
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\sgf.ps1 php scripts/b1-status.php
|
||||
```
|
||||
|
||||
Os scripts de concorrência/métricas verificam explicitamente o destino `sgf_tempo_test`. Parar a instância de navegador antes de executar testes que recriam essa base. Recuperação de acesso mantém o procedimento assistido de IDENTITY_WORKFLOW.md, sem fornecedor ou recuperação por email.
|
||||
|
||||
## Limites remanescentes
|
||||
|
||||
B1 fixa dados internos; não emite documento comercial/fiscal, não imprime/exporta uma factura, não confirma execução do serviço, não reconhece receita nem produz lançamentos. Não foi criado consumidor contabilístico. Contas, reconhecimento, moeda funcional, regras fiscais e arredondamento fiscal continuam por validar. Não foram implementados recebimentos, reconciliação, fecho, reabertura, correcção ou anulação. O restante B e C dependem de âmbito e autorização próprios. B1 foi aceite com estes limites; A permanece encerrada. Não avançar para os restantes incrementos nem publicar.
|
||||
@@ -0,0 +1,85 @@
|
||||
# Entrega B — delimitação para revisão
|
||||
|
||||
Complemento documental de 26 de Outubro de 2026: [matriz de facturação e recebimentos](BILLING_DOCUMENTS_FIELD_SPEC.md), com campos, origens, momentos, validações e fotografia histórica. B1 mantém-se aceite no checkpoint `8fcd52c`. O complemento apenas especifica informação com base em exemplos; não autoriza o restante B/C ou publicação.
|
||||
|
||||
Data: 25 de Outubro de 2026 (Africa/Johannesburg).
|
||||
|
||||
Estado: proposta de âmbito; não autoriza implementação, migrações, novas concessões, emissão fiscal ou publicação. Base: SERVICES_WORKFLOW_SPEC.md e entrega A aceite em SERVICES_A_DELIVERY.md, checkpoint local `ca13acb`, antecedido por `26b80df`. A permanece encerrada e não é reaberta nesta revisão. Este documento não constitui validação jurídica, fiscal ou contabilística.
|
||||
|
||||
Actualização posterior: o utilizador autorizou exclusivamente B1 — confirmação interna, fotografia imutável e captura das pendências — pelo prompt anexado em 25 de Outubro de 2026. A confirmação interna não é emissão comercial/fiscal, reconhecimento ou contabilização. Moeda/tratamento fiscal desconhecidos ficam preservados e não bloqueiam, por si só, esta confirmação interna. A permissão específica foi conferida e confirmada separadamente antes da concessão. Ver SERVICES_B1_DELIVERY.md. As restantes propostas e pendências de B abaixo continuam sem autorização de implementação.
|
||||
|
||||
## Regras já validadas que B deve preservar
|
||||
|
||||
| Regra | Consequência para B |
|
||||
| --- | --- |
|
||||
| Tenant, empresa e unidade distintos; contexto e permissões explícitos | Confirmar ou processar exige autorização própria; os direitos de A não bastam. A pertença ao tenant não concede acesso às empresas. |
|
||||
| Clientes e serviços da empresa; rascunhos da unidade | Reutilizar as origens existentes, sem duplicar cadastros ou transferir registos entre âmbitos. |
|
||||
| Prestação, documento e recebimento são acontecimentos distintos | Confirmar um documento não confirma automaticamente a execução do serviço, não recebe dinheiro nem liquida saldo. |
|
||||
| Histórico e captura durável transaccionais desde A | Consumir acontecimentos preservados, sem reconstruir o passado a partir do último estado do cadastro ou rascunho. |
|
||||
| Decimais exactos e ausência de pressupostos fiscais | Não presumir moeda, imposto, contas ou arredondamento. A precisão de entrada de A não aprova uma política monetária/fiscal para B. |
|
||||
| Idempotência, contexto/versionamento, auditoria e protecção SQL | Repetições e concorrência não podem duplicar confirmações, eventos ou efeitos contabilísticos. |
|
||||
| Provas sintéticas apenas em sgf_tempo_test | Nenhuma demonstração na Tempo Lda/SEGI; manter a aplicação normal e os seus dados. |
|
||||
|
||||
A arquitectura de contabilidade permanente e o processamento independente da contratação da interface comercial constam da especificação geral. Os mecanismos concretos abaixo ainda são propostas; não estão aprovadas regras de lançamento ou conformidade fiscal.
|
||||
|
||||
## Âmbito mínimo proposto
|
||||
|
||||
1. Pré-validar uma versão exacta do rascunho: origens, dados, contexto, permissões, regras aplicáveis e pendências. Mostrar separadamente bloqueios documentais e bloqueios contabilísticos.
|
||||
2. Confirmar documentalmente apenas quando os requisitos dessa operação estiverem aprovados e satisfeitos. Criar identidade própria e fotografia histórica imutável; não apresentar uma confirmação interna como factura fiscal sem validação específica.
|
||||
3. Capturar confirmação, fotografia, auditoria, evento e trabalho durável atomicamente, reutilizando a base de A. Uma confirmação repetida da mesma origem deve recuperar o resultado; alteração de conteúdo/versão deve gerar conflito.
|
||||
4. Processar eventos por consumidor repetível, com classificação explícita: sem efeito contabilístico justificado, pendente de regra/informação, falha técnica recuperável ou contabilizado segundo perfil aprovado.
|
||||
5. Quando elegível, produzir lançamentos rastreáveis ao evento, documento e versão das regras, com débitos/créditos equilibrados segundo as regras aprovadas. Persistir o efeito e a marca de processamento na mesma transacção.
|
||||
6. Permitir consulta do documento histórico, origens, pendências, tentativas e efeitos. Nenhum lançamento definitivo deve ser editável pelo formulário de rascunhos.
|
||||
|
||||
Não incluir recebimentos, afectações, correcções financeiras, anulações, reconciliação, fecho ou reabertura de períodos. Estas operações permanecem em C ou exigem delimitação própria. B não deve usar uma rotina de reversão improvisada para compensar decisões ainda pendentes.
|
||||
|
||||
## Preservação histórica proposta
|
||||
|
||||
- A fotografia conserva os dados efectivamente utilizados: identificação das partes exigida pelo tipo documental aprovado, empresa/unidade, origem e versão, linhas, quantidades/preços, moeda, datas aplicáveis, cálculos e versões das regras. Só incorporar campos fiscais depois de definida a sua necessidade.
|
||||
- Alterações posteriores do nome do cliente, serviço ou rascunho não alteram o documento confirmado. Ligações ao cadastro permitem navegação; não substituem a fotografia.
|
||||
- Guardar separadamente datas de prestação, documento, registo e reconhecimento quando aprovadas; não inferir uma da outra. Guardar autor e instante de confirmação.
|
||||
- Fotografias e eventos são imutáveis, com protecção também contra SQL em massa. O estado do consumidor fica em registos próprios, preservando os eventos/outbox append-only de A.
|
||||
- Consumir eventos antigos de A com classificação explícita. Uma edição de rascunho não se torna receita por existir no outbox. Não alterar nem regenerar esses eventos para simular acontecimentos financeiros.
|
||||
|
||||
## Pendências que impedem fechar o âmbito de implementação
|
||||
|
||||
| Decisão necessária | Quem deve validar / efeito enquanto faltar |
|
||||
| --- | --- |
|
||||
| Significado de confirmação: interna, documento comercial ou emissão fiscal; tipos abrangidos | Utilizador, com validação fiscal competente quando aplicável. Sem definição, não implementar um botão ambíguo de confirmar/emitir. |
|
||||
| Campos obrigatórios, identificação fiscal, datas, séries, numeração, unicidade, momento de atribuição e tratamento de falhas/lacunas | Validação fiscal/documental. Um identificador técnico não substitui numeração legal. |
|
||||
| Regime, impostos, isenções, evidências e cálculo por linha/documento | Validação fiscal. Ausência permanece pendência, nunca taxa zero. |
|
||||
| Moeda documental e funcional, eventual câmbio, escalas e política de arredondamento | Validação contabilística/fiscal. A aritmética exacta de A mantém-se; não converter automaticamente em totais fiscais. |
|
||||
| Momento de reconhecimento e sua relação com prestação e documento; datas de competência | Validação contabilística. Confirmar documento não implica reconhecer receita automaticamente. |
|
||||
| Plano de contas, classificações, dimensões, regras de débito/crédito e vigência das versões | Validação contabilística. Não inventar contas transitórias ou mapear nomes para contas. |
|
||||
| Pode haver documento confirmado com contabilização pendente? Quais bloqueios impedem cada transição? | Utilizador e responsáveis contabilístico/fiscal. Proposta: separar estados e não chamar contabilizado ao que está apenas confirmado. |
|
||||
| Período admissível e tratamento de eventos tardios ou datas não autorizadas | Validação contabilística. B deve respeitar restrições aplicáveis sem implementar o fecho de C. |
|
||||
| Quem confirma prestação/documento, consulta contabilidade, processa/reprocessa ou gere estes poderes; eventual separação de funções | Utilizador. Novos acessos negados por omissão, sem herança dos direitos de A; aplicação efectiva exige confirmação específica. |
|
||||
| Perfil sintético exclusivo de testes para demonstrar lançamentos e recuperação | Utilizador. Deve ser identificado como artificial, isolado de desenvolvimento e incapaz de activar regras reais. Não valida conformidade. |
|
||||
|
||||
Não é necessário resolver agora as políticas de recebimento, reconciliação ou correcção de C. É necessário definir como impedir que uma confirmação de B seja posteriormente alterada por caminhos não autorizados.
|
||||
|
||||
## Ecrãs mínimos propostos
|
||||
|
||||
- Pré-validação/confirmacão: versão e contexto explícitos, dados históricos a fixar, bloqueios e efeito exacto da operação.
|
||||
- Documento confirmado: fotografia preservada, origem, identidade, datas e estado documental, sem edição directa.
|
||||
- Acompanhamento contabilístico: evento, estado, motivos, tentativas e ligação aos lançamentos; reprocessamento apenas autorizado.
|
||||
- Detalhe de lançamento: regra/versão, origens, moeda, débitos/créditos e evidência de equilíbrio, quando essas regras estiverem aprovadas.
|
||||
|
||||
Reutilizar navegação e contexto de A. Não disponibilizar botões financeiros simulados nem expandir o sistema de parâmetros para além dos dados necessários às regras aprovadas.
|
||||
|
||||
## Provas de aceitação a exigir à implementação futura
|
||||
|
||||
1. Documento confirmado conserva a fotografia após alterações de cadastros e rascunhos; SQL em massa não a transfere nem reescreve.
|
||||
2. Falta de configuração gera recusa ou pendência conforme a matriz aprovada, sem moeda/imposto/conta inventados.
|
||||
3. Dois comandos concorrentes não confirmam duas vezes a mesma operação. Definir antes a relação permitida entre prestação e documentos; não presumir facturação parcial ou múltipla.
|
||||
4. Consumidor repetido, concorrente ou interrompido antes/depois do commit não duplica efeitos. Falha técnica distingue-se de pendência de negócio e deixa evidência recuperável.
|
||||
5. Cada lançamento liga-se ao evento e perfil versionado, é equilibrado nas unidades monetárias aprovadas e não se apresenta como definitivo com configuração insuficiente.
|
||||
6. Eventos históricos de rascunho conservam o conteúdo e recebem classificação rastreável, sem receita artificial. Activar posteriormente a interface comercial não repete o processamento.
|
||||
7. Direitos de A não autorizam confirmação/processamento; revogação produz efeito no pedido seguinte. Testar acesso cruzado entre empresas do mesmo tenant, unidades, URLs e tarefas.
|
||||
8. Prova no navegador com login real sintético em instância isolada; suite e operações destrutivas apenas em sgf_tempo_test. Dados reais e checkpoint A preservados.
|
||||
|
||||
## Próximo passo
|
||||
|
||||
Rever as decisões da tabela antes de redigir o prompt de execução de B. A primeira decisão é o significado da confirmação e se se pretende um ensaio exclusivamente sintético ou uma capacidade documental real com requisitos fiscais validados. A existência deste documento não concede autorização de implementação ou de novos acessos.
|
||||
|
||||
Aceitação posterior: em 25 de Outubro de 2026, B1 foi aceite no âmbito demonstrado de confirmação interna, sem validade fiscal nem lançamentos contabilísticos, com checkpoint Git exclusivamente local. O restante B/C continua sem autorização; não avançar nem publicar.
|
||||
@@ -4,6 +4,8 @@ Data: 25 de Outubro de 2026.
|
||||
|
||||
Referência: SGF_TEMPO_Roteiro_v0_9.docx, particularmente secções 5, 14 a 19 e 20 a 24. Este documento especifica um percurso para revisão; não autoriza emissão fiscal, operações reais, movimentação de fundos ou implementação integral.
|
||||
|
||||
Revisão documental de 26 de Outubro de 2026: [BILLING_DOCUMENTS_FIELD_SPEC.md](BILLING_DOCUMENTS_FIELD_SPEC.md) contém a matriz de informação para factura, recibo e factura-recibo, baseada nos três exemplos fornecidos. Distingue conteúdo pretendido, propostas técnicas e requisitos legais ainda por validar. O recibo Tempo refere FT 10/2026, não FT 11/2026. Preserva B1 aceite em `8fcd52c`; esta revisão não autoriza implementação ou emissão.
|
||||
|
||||
## Decisões já tomadas
|
||||
|
||||
- Começar pelo sector de prestação de serviços, com um serviço pontual como cenário de desenvolvimento.
|
||||
@@ -19,7 +21,7 @@ O incremento de entrada, contexto e permissões tem implementação e provas té
|
||||
|
||||
O utilizador aceitou e deu por concluído o incremento local de entrada, contexto e permissões em 25 de Outubro de 2026, no âmbito demonstrado e com os limites de IDENTITY_DELIVERY.md. Preservar essa entrega como base. Limites conhecidos: âmbito local, sem MFA/RLS de produção, sem criação geral de contas pela interface e com procedimentos locais assistidos de recuperação. A aceitação está registada separadamente do cenário de serviços.
|
||||
|
||||
Nesta etapa está autorizada apenas a especificação de serviços. As entregas A/B/C abaixo são um plano para decisões posteriores, não uma ordem para as implementar agora.
|
||||
Na revisão inicial estava autorizada apenas a especificação. Posteriormente o utilizador autorizou executar exclusivamente A através do prompt de execução anexado, mantendo B/C fora do âmbito. A implementação de A e as provas estão documentadas em SERVICES_A_DELIVERY.md; isso não constitui aceitação automática de A nem autoriza B/C ou publicação.
|
||||
|
||||
## Resultado pretendido
|
||||
|
||||
@@ -108,6 +110,10 @@ Não acrescentar já contratos recorrentes, horas, equipas de projecto, custos,
|
||||
|
||||
Identificadores de tenant, empresa e unidade vêm do contexto autorizado. Cliente e serviço devem pertencer à empresa da prestação. Uma escolha de cliente reutiliza o cadastro; documentos confirmados futuros preservam a fotografia histórica necessária em vez de dependerem do cadastro mutável.
|
||||
|
||||
Na entrega A, clientes e serviços pertencem à empresa e são reutilizados entre as suas unidades. Não criar cópias por unidade nem exigir unit_id nesses cadastros. Prestações e rascunhos de facturação pertencem à empresa e à unidade autorizada: o vínculo à unidade não pode ser transferido por edição de um formulário.
|
||||
|
||||
O nome será o único campo obrigatório introduzido pelo utilizador no cadastro de cliente nesta fase. Identificadores, empresa, papel de cliente e metadados de autoria/versão são controlados pelo servidor. Não exigir dados fiscais ou contactos para guardar esse cadastro mínimo; a ausência dos dados necessários a documentos futuros permanece uma pendência, não uma indicação de validade fiscal.
|
||||
|
||||
## Estados propostos
|
||||
|
||||
- Prestação: rascunho, confirmada ou cancelada antes de confirmação. Uma correcção posterior referencia a prestação confirmada; não elimina a origem.
|
||||
@@ -122,11 +128,11 @@ O primeiro incremento não deve apresentar os estados futuros como capacidades j
|
||||
## Regras técnicas propostas
|
||||
|
||||
1. Guardar preços, quantidades e montantes com precisão controlada; usar brick/math existente no servidor e cadeias decimais nas APIs. Não usar o JavaScript como autoridade financeira.
|
||||
2. Validar escala e arredondamento explicitamente. A política financeira/fiscal precisa de aprovação; não depender de coerção silenciosa da base.
|
||||
2. Validar escala explicitamente e rejeitar valores que excedam a precisão suportada antes de persistir, sem arredondamento silencioso. Não presumir moeda nem converter imposto desconhecido em zero. Guardar o rascunho incompleto com pendências explícitas quando necessário. A política financeira/fiscal de arredondamento continua por validar; não depender de coerção silenciosa da base.
|
||||
3. Negar por omissão cada acção e verificar empresa, unidade, registo e permissão no servidor. As concessões actuais de identidade não concedem acesso automático às novas áreas.
|
||||
4. Recusar um formulário com contexto ou versão desactualizados. Mudança de empresa/unidade não relocaliza registos nem reaproveita silenciosamente autorizações anteriores.
|
||||
5. Usar chaves de idempotência por empresa/operação/conteúdo para comandos repetíveis. Repetição idêntica recupera o resultado; conteúdo diferente com a mesma chave origina conflito.
|
||||
6. Confirmar alteração, evento durável e trabalho pendente na mesma transacção. A outbox é uma proposta técnica a implementar no núcleo, sem exigir Redis ou novo fornecedor.
|
||||
6. Confirmar alteração, histórico, evento durável e trabalho pendente na mesma transacção desde a entrega A. A outbox integra a proposta de captura inicial, sem exigir Redis ou novo fornecedor. B acrescenta processamento contabilístico sobre essa base, sem reconstruir eventos históricos ou inferir acontecimentos a partir do último estado de um rascunho.
|
||||
7. Não duplicar efeitos contabilísticos quando um evento é repetido ou uma interface comercial é activada posteriormente.
|
||||
8. Sem plano de contas, classificação, imposto, moeda ou reconhecimento aprovados, criar pendências explícitas. Não escolher contas transitórias para ocultar lacunas.
|
||||
9. Manter auditoria das alterações relevantes, sem palavras-passe, tokens ou raciocínio interno da IA.
|
||||
@@ -151,25 +157,45 @@ Separar consulta e alteração de cadastros, criação/edição/confirmação de
|
||||
|
||||
As concessões serão dados parametrizados, mas o catálogo cobre apenas acções suportadas. Gestão de acessos não implica capacidade financeira. Não ampliar automaticamente os direitos de Osmane ou Samira. A matriz concreta e a autoridade inicial de concessão das novas acções precisam de aprovação antes da disponibilização.
|
||||
|
||||
### Matriz delimitada para a entrega A
|
||||
|
||||
| Área | Âmbito dos registos e das concessões | Osmane | Samira |
|
||||
| --- | --- | --- | --- |
|
||||
| Clientes | Tempo Lda, cadastro partilhado pelas unidades | Consultar, criar, editar e gerir estas concessões | Apenas consultar |
|
||||
| Serviços | Tempo Lda, catálogo partilhado pelas unidades | Consultar, criar, editar e gerir estas concessões | Apenas consultar |
|
||||
| Prestações em rascunho | Tempo Lda / SEGI | Consultar, criar, editar e gerir estas concessões | Apenas consultar |
|
||||
| Rascunhos de facturação | Tempo Lda / SEGI | Consultar, criar, editar e gerir estas concessões | Apenas consultar |
|
||||
|
||||
Separar consulta, criação, edição e gestão de concessões em cada área; não introduzir um papel universal. A autoridade sobre os cadastros de empresa não concede autoridade sobre prestações/rascunhos de outras unidades. Os clientes e serviços, sendo cadastros de empresa, não ficam artificialmente privados da SEGI.
|
||||
|
||||
Estas são novas concessões, cuja atribuição inicial deve ser explícita e auditada. Não as derivar dos actuais company.edit/access.manage ou da identidade/email das pessoas. O gestor só pode delegar direitos que possui, no mesmo âmbito. Não incluir confirmação financeira/documental, recebimentos, correcções, reconciliação, lançamentos ou fecho. Após conferir as contas existentes e obter confirmação específica, foram aplicadas 16 concessões à conta ID 1 (Osmane Nala) e 4 de consulta à conta ID 2 (Samira Nal), sem criar ou associar outra conta por suposição. Ver SERVICES_A_DELIVERY.md para âmbitos e evidências.
|
||||
|
||||
## Entregas verificáveis
|
||||
|
||||
### A Cadastros e preparação operacional
|
||||
|
||||
Proposta para a primeira implementação:
|
||||
Âmbito delimitado para a primeira implementação, sujeito à autorização de execução:
|
||||
|
||||
- Contraparte/cliente e serviço mínimos.
|
||||
- Prestação em rascunho, reutilizando esses cadastros e o contexto existente.
|
||||
- Rascunho de facturação ligado à prestação, sem emissão fiscal ou numeração definitiva.
|
||||
- Captura durável dos acontecimentos abrangidos e pendências explícitas de classificação, sem inventar lançamentos.
|
||||
- Contraparte/cliente e serviço mínimos, partilhados pela empresa; nome como único campo obrigatório do cliente.
|
||||
- Prestação em rascunho na unidade autorizada, reutilizando esses cadastros e o contexto existente.
|
||||
- Rascunho de facturação na mesma unidade, ligado à prestação, sem emissão fiscal ou numeração definitiva.
|
||||
- Histórico, captura durável dos acontecimentos abrangidos e pendências explícitas de classificação desde A, sem inventar lançamentos. B reutiliza essa base e acrescenta o processamento contabilístico.
|
||||
- Valores de precisão controlada, sem arredondamentos silenciosos, moeda presumida ou imposto desconhecido convertido em zero.
|
||||
- Permissões, auditoria, controlo de versão/contexto e repetição segura desde estes primeiros comandos.
|
||||
- Dados sintéticos e provas apenas na base de testes; nenhuma factura ou recebimento real em desenvolvimento.
|
||||
|
||||
Critério: percurso cliente → serviço → prestação → rascunho reproduzível, com origem preservada, acessos indevidos recusados e informação insuficiente assinalada. Isto não é ainda o circuito financeiro completo.
|
||||
|
||||
A não emite facturas nem produz lançamentos contabilísticos. Documentos confirmados, recebimentos, correcções, reconciliação e fecho permanecem exclusivamente em B/C.
|
||||
|
||||
### B Documentos e contabilidade permanente
|
||||
|
||||
Após validar campos/regras aplicáveis: confirmação documental, fotografia histórica, eventos/outbox, consumidor repetível, regras de contabilização e pendências. Demonstrar contabilidade permanente mesmo sem interface comercial de Contabilidade contratada.
|
||||
|
||||
Delimitação para revisão em [SERVICES_B_SCOPE.md](SERVICES_B_SCOPE.md): separa a base aceite de A, propostas técnicas e decisões documentais/fiscais/contabilísticas pendentes. Apenas especificação, sem autorização de implementação.
|
||||
|
||||
Autorização posterior exclusiva de B1: confirmação interna do rascunho, fotografia imutável e captura de pendências, sem emissão comercial/fiscal, reconhecimento ou lançamentos. Implementação delimitada em [SERVICES_B1_DELIVERY.md](SERVICES_B1_DELIVERY.md). Não conclui B integralmente, não reabre A e não autoriza C.
|
||||
|
||||
### C Recebimentos correcção reconciliação e fecho
|
||||
|
||||
Completar o cenário sintético, incluindo os dois recebimentos, correcção ligada ao original, reconciliação explicável e tentativas de fecho com e sem pendências. Demonstrar concorrência, interrupções e recuperação. Utilização real fica dependente de regras e responsáveis aprovados.
|
||||
@@ -196,7 +222,7 @@ Estas entregas partilham o mesmo núcleo. Não criam três produtos ou versões
|
||||
|
||||
## Decisões pendentes antes das entregas correspondentes
|
||||
|
||||
Para A: aprovar esta delimitação e a matriz de permissões/autoridade inicial; confirmar quais dados mínimos do cliente são indispensáveis para um rascunho (a proposta inicial exige apenas nome).
|
||||
Para A: o utilizador autorizou a execução e confirmou especificamente a aplicação das novas concessões após conferência das contas. A implementação usa nome como único campo obrigatório do cliente, cadeias decimais até 16 algarismos inteiros/8 decimais, validação anterior à persistência e protecção também na base, sem arredondamento silencioso. O delta aditivo e os resultados constam de SERVICES_A_DELIVERY.md. A aceitação deste incremento é distinta da aceitação anterior de identidade.
|
||||
|
||||
Para B/C: responsáveis de validação contabilística/fiscal, documentos e numeração, regime/impostos aplicáveis, moeda funcional, plano de contas, reconhecimento, arredondamento, evidências de recebimento/reconciliação, corte e regras de fecho/correcção. O exemplo de teste não decide estas matérias.
|
||||
|
||||
@@ -204,4 +230,6 @@ Não seleccionar fornecedor, API bancária ou integração de pagamento. Não co
|
||||
|
||||
## Estado desta etapa
|
||||
|
||||
Especificação proposta para revisão. Nenhuma migração, cadastro, documento, evento financeiro ou lançamento foi criado nesta etapa. O incremento de identidade está aceite e concluído; qualquer implementação posterior exige autorização sobre uma entrega concreta. O utilizador manteve expressamente serviços apenas em especificação e não autorizou implementação financeira ou publicação. Não implementar a entrega A nesta revisão documental.
|
||||
Entrega A implementada e aceite pelo utilizador em 25 de Outubro de 2026, com os limites do relatório SERVICES_A_DELIVERY.md. A e a base de identidade foram preservadas. Posteriormente foi autorizado apenas B1, de confirmação interna, fotografia histórica e captura de pendências. O restante B e C permanecem em especificação: sem emissão comercial/fiscal, lançamentos, recebimentos, correcções, reconciliação ou fecho. Não avançar além de B1 nem publicar.
|
||||
|
||||
B1 foi aceite pelo utilizador em 25 de Outubro de 2026 no âmbito demonstrado de confirmação interna, sem validade fiscal nem lançamentos contabilísticos. Preservar o checkpoint local desta entrega e os antecessores; não avançar para os restantes incrementos nem publicar.
|
||||
|
||||
@@ -0,0 +1,71 @@
|
||||
# Primeiro cálculo de serviço — entrega local delimitada
|
||||
|
||||
**Aceitação posterior em 26/10/2026:** o utilizador aceitou expressamente o cálculo de ensaio demonstrado e autorizou o checkpoint local, conforme [conferência e aceitação separadas](SERVICE_CALCULATION_SEPARATE_REVIEW.md). A aplicabilidade fiscal real continua pendente e a activação de perfil fiscal real não foi autorizada. O texto de entrega abaixo preserva o estado anterior a essa aceitação e não a revoga.
|
||||
|
||||
26/10/2026. Preservadas identidade, A, B1 (`8fcd52c`), preparação documental, pré-visualização e alterações posteriores existentes. Não constitui aceitação pelo utilizador nem autorização de emissão.
|
||||
|
||||
## Comportamento entregue
|
||||
|
||||
Uma linha, quantidade positiva, preço não negativo, moeda explícita e modo imposto acrescido (`added`). Aritmética Brick\Math já existente, sem dependências novas nem alterações de versões. Base e IVA exactos sem float ou truncagem intermédia. A política **`SGF-SERVICE-NET-VAT-TRUNCATE2-v1`** trunca apenas o IVA documental proposto a duas casas, conserva a diferença e calcula total proposto apenas quando a base é exactamente representável a duas casas. Caso contrário o total fica pendente, sem ajustar ou truncar a base.
|
||||
|
||||
Truncagem: decisão operacional expressa do utilizador, **não obrigação legal comprovada**. Fontes reutilizadas: ficha InvesteMoz `IVA-GERAL-BASE-LIQUIDA` v1.2, cadeia da Lei 22/2022 republicada/art. 17(1), CIVA art. 15 e acontecimentos arts. 7/8/17(2). A matriz e limites constam de [SERVICE_INVOICE_CALCULATION_SPEC.md](SERVICE_INVOICE_CALCULATION_SPEC.md). Não se repetiu investigação nem se copiou código do portal.
|
||||
|
||||
Separação confirmada: a classificação contabilística orienta contas; o enquadramento fiscal da operação determina tratamento e taxa de IVA. Nenhuma taxa é inferida da conta/classificação contabilística ou aplicada universalmente a serviços. Os 16% são exclusivamente parâmetro identificado dos ensaios deste incremento. Associações contabilísticas e lançamentos não foram implementados.
|
||||
|
||||
Perfis e resultados são imutáveis. Cada resultado conserva entradas, moeda, base exacta, IVA exacto, IVA proposto, diferença, total/pendência, política, perfil/versão/fontes e versões de rascunho, preparação e origem. Mudanças tornam o resultado anterior desactualizado na nova consulta; o histórico mantém os valores originais. A leitura não recalcula nem grava. A pré-visualização já aberta conserva a versão consultada e avisa de alterações pelo mecanismo existente, exigindo actualização explícita.
|
||||
|
||||
Execução por `POST /api/service-calculations/{id}` com contexto validado, sessão, CSRF e versões de rascunho/preparação/perfil. Sem campos arbitrários de taxa ou resultados enviados pelo navegador. Bloqueio fora de `testing`/`browser-testing`, seguido da guarda do destino efectivo `sgf_tempo_test`. O ensaio requer consulta e edição de rascunho já concedidas à identidade sintética; consulta não permite executar. Configurar aparência não dá esse acesso. Nenhuma concessão nova foi aplicada às contas reais e não existe via de activação de perfil real neste incremento.
|
||||
|
||||
Bloqueio transaccional da empresa serializa comandos com as alterações existentes. Revalida contexto/permissões, rejeita versões antigas e origem/preparação por rever, e garante uma única inserção por entrada/versionamento, com repetição devolvendo o mesmo resultado. Auditoria da criação na mesma transacção. Chaves compostas e trigger de inserção recusam associações cruzadas; triggers append-only impedem actualizações/transferências em massa e apagamentos de perfis/resultados. Não se apresenta isto como prova de RLS.
|
||||
|
||||
## Migração e preservação
|
||||
|
||||
Delta previamente apresentado: `2026_10_26_030000_create_service_calculations.php` cria `service_calculation_profiles`, `service_calculation_results`, índices, relações e triggers. Não altera B1, cadastros, permissões ou dados existentes; não tem rollback destrutivo automático.
|
||||
|
||||
Aplicada primeiro em `sgf_tempo_test` nas provas; depois em **`sgf_tempo_dev`**, por `scripts/sgf.ps1 migrate`, com proprietário separado. Antes de aplicar em desenvolvimento, o estado das migrações confirmou que apenas esta estava pendente. Verificação posterior: contagens e hashes do conteúdo das 14 tabelas existentes comparadas ficaram idênticos. Tabelas novas em desenvolvimento: **zero perfis, zero resultados**. [Prova de preservação](proofs/calculation-dev-preservation.json). Nenhum reset/fresh em desenvolvimento foi aplicado por este incremento.
|
||||
|
||||
## Provas
|
||||
|
||||
Regressões dirigidas: **53 testes, 743 asserções**, todos passados, abrangendo `ServiceCalculationTest`, `DocumentPreviewTest`, `InternalConfirmationTest`, `DocumentPreparationTest` e `DatabaseSafetyTest`. Execução exclusivamente em `sgf_tempo_test`. Compilação `npm run build` passou (Vite 8.3.5). Verificação de whitespace passou; nenhuma versão de ferramenta foi alterada.
|
||||
|
||||
Cobertura nova: três casos pedidos, zero explícito, fronteiras imediatamente abaixo/na/acima da truncagem, base com fracções adicionais, perfil/taxa/moeda ausentes ou incompatíveis, modo incluído recusado, repetição, versões antigas de rascunho/perfil, histórico desactualizado, leitor sem edição, revogação no pedido seguinte, unidade de perfil alheia, empresa irmã, tentativa de transferência em massa, bloqueio no ambiente normal e fotografia B1 preservada. Guardas existentes continuam a recusar desenvolvimento e sobreposição por URL e a verificar privilégios do papel de testes.
|
||||
|
||||
Concorrência separada, em dois processos PHP realmente sobrepostos: primeiro mantém bloqueio enquanto segundo entra; um resultado criado e um replay com o mesmo ID, sem duplicação. [Prova concorrente](proofs/calculation-concurrency.json).
|
||||
|
||||
Navegador Edge, **login real sintético**, com CSRF/sessão activos em `http://127.0.0.1:8001`, base `sgf_tempo_test`, sessões/cache isolados. Não se usou `actingAs` como demonstração de login. Taxa 16% apenas no perfil identificado `ENSAIO-MZN-16 v1`, moeda MZN explicitamente indicada:
|
||||
|
||||
| Base | IVA exacto | IVA truncado | Diferença | Total proposto | Prova |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| 100 | 16 | 16,00 | 0 | 116,00 | [Imagem](proofs/calculation-100.png) |
|
||||
| 1000,03 | 160,0048 | 160,00 | 0,0048 | 1160,03 | [Imagem](proofs/calculation-1000.png) |
|
||||
| 0,03 | 0,0048 | 0,00 | 0,0048 | 0,03 | [Imagem](proofs/calculation-small.png) |
|
||||
| 0,0001 | 0,000016 | 0,00 | 0,000016 | Pendente | [Imagem](proofs/calculation-base-pending.png) |
|
||||
|
||||
Repetição do segundo caso no navegador conservou o mesmo resultado. Em todos: aviso permanente **RASCUNHO — SEM VALIDADE FISCAL**, identificação de ensaio, diferença preservada e pendências visíveis. [Registo da observação](proofs/calculation-browser-results.json). Separador decimal dos valores na interface é actualmente ponto; os valores são strings exactas, sem conversão de apresentação para float.
|
||||
|
||||
### Percurso exacto e repetição local da prova
|
||||
|
||||
1. Entrar como identidade sintética existente da fixture, com a credencial local criada aleatoriamente; nunca publicar a credencial. Seleccionar **Empresa Horizonte — Demonstração → Unidade Central — Demonstração**.
|
||||
2. **Rascunhos de facturação → Ensaio base 100 → Pré-visualizar rascunho → Calcular ensaio · ENSAIO-MZN-16 v1**. Consultar os quatro valores e o total proposto.
|
||||
3. **Voltar ao registo**, seleccionar os casos **Ensaio base 1000.03**, **Ensaio base 0.03** e **Ensaio base 0.0001**, repetir pré-visualização/cálculo. O segundo caso também foi calculado pela prova concorrente e a execução no navegador reutilizou o mesmo resultado.
|
||||
4. Sair da sessão. A instância de prova é encerrada após a entrega; a aplicação normal não muda de ligação.
|
||||
|
||||
Para preparar outra prova, parar primeiro a instância com `scripts/browser-proof.ps1 stop`; executar apenas os testes dirigidos abaixo (recriam a base de testes, nunca desenvolvimento); arrancar novamente `scripts/browser-proof.ps1 start` e preparar os quatro rascunhos por `sgf.ps1 php scripts/calculation-fixture.php --env=testing`. O preparador de fixtures recusa uma base não vazia; não apaga dados para conseguir prosseguir. Depois, `sgf.ps1 php scripts/calculation-concurrency.php --env=testing` demonstra a concorrência antes do percurso no navegador. Não repetir o preparador de cálculo sobre a mesma fixture.
|
||||
|
||||
```powershell
|
||||
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/sgf.ps1 test --stop-on-failure --filter="ServiceCalculationTest|DocumentPreviewTest|InternalConfirmationTest|DocumentPreparationTest|DatabaseSafetyTest"
|
||||
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/sgf.ps1 npm run build
|
||||
```
|
||||
|
||||
Os scripts PowerShell existentes podem precisar de `-ExecutionPolicy Bypass` apenas nesse processo; não se alterou política global. A execução recusa portas ocupadas, sem terminar processos de outro projecto.
|
||||
|
||||
## Ficheiros deste incremento
|
||||
|
||||
- Núcleo novo: `app/Modules/Services/ServiceCalculation.php`; migração nova acima; `tests/Feature/ServiceCalculationTest.php`.
|
||||
- Integração: `DocumentPreview.php`, `Http/DocumentPreviewController.php`, `routes/web.php`, `resources/js/DocumentPreview.jsx`.
|
||||
- Provas: `scripts/calculation-fixture.php`, `calculation-worker.php`, `calculation-concurrency.php`, `calculation-preservation.php` e ficheiros `docs/proofs/calculation-*`.
|
||||
- Documentação: esta entrega, especificação de cálculo, README e AGENTS. Restantes alterações preexistentes foram preservadas; nenhum commit/checkpoint foi criado sem pedido.
|
||||
|
||||
## Condições para activação real
|
||||
|
||||
Continua por demonstrar a aplicabilidade concreta: regime, serviço/localização, tratamento, base tributável e acontecimento/exigibilidade. Activação requer incremento próprio com perfil real fundamentado/versionado e direitos fiscais especificamente aprovados, sem herdar poderes visuais. A decisão operacional de truncagem não comprova conformidade fiscal do montante documental. Representação de base/total com fracções adicionais fica pendente. Incluído e demais casos continuam excluídos. Não há número/data de emissão fiscal, emissão, PDF, recebimentos ou lançamentos; nenhum documento foi publicado.
|
||||
@@ -0,0 +1,25 @@
|
||||
# Conferência separada do cálculo de ensaio
|
||||
|
||||
26/10/2026, Africa/Johannesburg. Demonstração realizada no navegador Edge em `http://127.0.0.1:8001`, exclusivamente em `sgf_tempo_test`, com login real de identidade sintética e contexto Empresa Horizonte — Demonstração / Unidade Central — Demonstração. Aplicação normal e contas reais não foram utilizadas.
|
||||
|
||||
Percurso: login → empresa/unidade sintéticas → Rascunhos de facturação → Ensaio base 1000.03 → Pré-visualizar rascunho → Calcular ensaio · ENSAIO-MZN-16 v1.
|
||||
|
||||
| Componente | Resultado observado, MZN |
|
||||
| --- | --- |
|
||||
| Base exacta | 1 000,03 |
|
||||
| IVA exacto, taxa de ensaio identificada de 16% | 160,0048 |
|
||||
| IVA documental proposto, truncagem operacional a duas casas | 160,00 |
|
||||
| Diferença descartada preservada | 0,0048 |
|
||||
| Total documental proposto | 1 160,03 |
|
||||
|
||||
Política identificada: `SGF-SERVICE-NET-VAT-TRUNCATE2-v1`. Resultado persistido e apresentado com identificação de ensaio sintético, sem validação fiscal e com aviso permanente «RASCUNHO — SEM VALIDADE FISCAL». A interface usa ponto decimal; a tabela acima apresenta os mesmos valores com vírgula, sem alterar o cálculo. [Prova visual desta conferência](proofs/calculation-separate-review.png).
|
||||
|
||||
Não foram alterados código, versões, política de cálculo, concessões ou fotografias B1. Não foi activado perfil fiscal real nem foram criados recebimentos, lançamentos ou emissão. Não se repetiram suites de testes ou investigação: esta etapa foi uma conferência no navegador do caso pedido. A instância e o separador de demonstração ficaram abertos para conferência do utilizador; devem ser encerrados antes de outra execução que recrie a base de testes.
|
||||
|
||||
## Aceitação e checkpoint local
|
||||
|
||||
Em 26/10/2026, o utilizador confirmou expressamente: «Confirmo a aceitação do cálculo de ensaio demonstrado. A aplicabilidade fiscal real permanece separada e pendente; não autorizo activar um perfil fiscal real. Regista a aceitação e preserva o checkpoint local, sem publicação.»
|
||||
|
||||
Fica registada a aceitação do caso de ensaio e dos resultados acima. A aceitação anterior da classificação contabilística permanece independente. Esta confirmação não demonstra aplicabilidade fiscal à Tempo Lda nem autoriza perfil real, emissão, recebimentos ou lançamentos.
|
||||
|
||||
A instância isolada de demonstração foi encerrada após a aceitação, sem parar a aplicação normal ou o cluster. O checkpoint preserva apenas esta documentação, a prova sintética e a actualização das instruções locais; não inclui credenciais ou bases de dados. Não foram repetidos testes nem alterados código ou configurações fiscais.
|
||||
@@ -0,0 +1,212 @@
|
||||
# Primeiro cálculo de factura de serviço — especificação e incremento delimitado
|
||||
|
||||
Data da revisão e consulta das fontes: 26 de Outubro de 2026 (Africa/Johannesburg).
|
||||
|
||||
**Actualização posterior autorizada pelo utilizador:** implementação delimitada do cálculo sobre preço sem imposto, com provas sintéticas isoladas. Não autoriza configuração fiscal real, novas concessões ou operações fictícias da Tempo Lda. Preservar preparação documental, pré-visualização, B1 e checkpoints `8fcd52c`, `ca13acb`, `26b80df`, incluindo alterações posteriores. Não reabrir aceitações.
|
||||
|
||||
## Política operacional aprovada para este incremento
|
||||
|
||||
**Separação expressamente confirmada pelo utilizador:** classificação contabilística da mercadoria/serviço orienta as contas; enquadramento fiscal da operação determina o tratamento de IVA e a taxa aplicável, incluindo taxas diferentes em serviços abrangidos. São associações distintas. Não deduzir a taxa da conta contabilística, da classificação contabilística ou do simples facto de se tratar de serviço; não presumir 16% para tudo. Este incremento não implementa contas/lançamentos nem automatiza a classificação fiscal. A taxa de ensaio provém exclusivamente do perfil sintético identificado.
|
||||
|
||||
Versão imutável **`SGF-SERVICE-NET-VAT-TRUNCATE2-v1`**. Esta orientação posterior prevalece sobre as propostas anteriores de âmbito/reconciliação desta especificação. A matriz abaixo continua a distinguir conhecimento fiscal documentado de política de produto.
|
||||
|
||||
- Uma linha, quantidade positiva, preço não negativo, moeda explícita e modo `added`. Incluído, múltiplas linhas, negativos, descontos, retenções, câmbio, adiantamentos e correcções ficam excluídos.
|
||||
- `B = q × p`; `IVA_exacto = B × taxa_percent × 0,01`, em aritmética exacta, sem float ou truncagem intermédia.
|
||||
- `IVA_documental_proposto = truncate(IVA_exacto, 2)` para valores não negativos; `diferença_descartada = IVA_exacto − IVA_documental_proposto`. Todas as grandezas ficam preservadas, incluindo quando o IVA proposto é `0,00`.
|
||||
- Se B for exactamente representável a duas casas, `total_documental_proposto = B + IVA_documental_proposto`, apresentado a duas casas. Caso contrário, conservar B, IVA exacto, IVA truncado e diferença; total proposto fica nulo e a representação da base/total pendente. Não truncar B nem criar ajustes.
|
||||
- A truncagem é **decisão operacional expressa do utilizador**, não obrigação legal comprovada. Não altera a regra exacta reutilizada do portal nem fotografias B1. HALF_UP/HALF_EVEN permanecem apenas ensaios históricos de comparação.
|
||||
- Perfil de ensaio identificado por unidade, nome e versão imutável; definição conserva moeda, taxa, natureza sintética, política e fontes. Resultados append-only conservam entradas, versões do rascunho/preparação/origem/perfil/política e valores derivados. A nova consulta marca versões antigas desactualizadas, sem recalcular ou apagar o histórico.
|
||||
- A API de execução só funciona em `testing`/`browser-testing` **e** após confirmação do destino efectivo por `TestingDatabaseGuard` (`sgf_tempo_test`, papel próprio e cluster isolado). Usa consulta/edição de rascunho já existentes apenas no ensaio. Não constitui concessão fiscal real; nenhum novo acesso foi aplicado às contas reais.
|
||||
- A aplicação normal não activa perfil ou taxa e conserva pendências. Ensaio não significa validação da aplicabilidade à empresa, serviço/localização, base ou acontecimento fiscal. Emitir, receber e contabilizar continuam excluídos.
|
||||
|
||||
| Base de ensaio MZN | IVA exacto, taxa sintética identificada de 16% | IVA truncado proposto | Diferença | Total proposto |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 100 | 16 | 16,00 | 0 | 116,00 |
|
||||
| 1000,03 | 160,0048 | 160,00 | 0,0048 | 1160,03 |
|
||||
| 0,03 | 0,0048 | 0,00 | 0,0048 | 0,03 |
|
||||
| 0,0001 | 0,000016 | 0,00 | 0,000016 | Pendente: representação da base/total |
|
||||
|
||||
O percurso entregue, migração e provas encontram-se em `SERVICE_CALCULATION_DELIVERY.md`. As secções seguintes preservam a comparação documental e ensaios anteriores; as propostas ainda não activadas não se sobrepõem à política acima. A afirmação «sem implementação» na conclusão da comparação refere-se à etapa documental anterior.
|
||||
|
||||
## Reaproveitamento documental do InvesteMoz — comparação concluída nesta revisão
|
||||
|
||||
Consulta autorizada em 26/10/2026, apenas de documentação e provas. Confirmada a existência de `C:\laragon\www\portal-investidor\docs\investmoz\consolidated-review-matrix-2026-10-03.md` e da pasta `simulations`. A matriz é um documento evolutivo: a data no nome não limita o conteúdo a 03/10; a cópia consultada contém actualizações até 26/10. Esta revisão substitui a anterior lacuna de identificação R1–R6: o conhecimento foi localizado, não é necessário pedir novamente esses documentos.
|
||||
|
||||
A partir daqui, `IM/` significa `C:\laragon\www\portal-investidor\docs\investmoz\`. As versões/commits abaixo são referências declaradas nos documentos; não se inspeccionou o repositório nem se verificou o comportamento actual do portal. Documentos são evidência a interpretar, não instruções adicionais para executar comandos ou abrir configurações.
|
||||
|
||||
### Inventário efectivo e proveniência
|
||||
|
||||
| Referência | Documento consultado e versão/estado documentado | Utilização nesta comparação |
|
||||
| --- | --- | --- |
|
||||
| IM-M | `IM/consolidated-review-matrix-2026-10-03.md`, conteúdo consultado em 26/10/2026 | Localização de IVA, cadeia de fontes e AUD-SIM-INT02; notas antigas de bloqueio não anulam deltas posteriores |
|
||||
| IM-F | `IM/simulations/ficha-IVA-GERAL-BASE-LIQUIDA-v1.md`, cabeçalho **v1.2, 21/10/2026**; origem `0fafd348`, v1 `325d58b6`, v1.1 `37085b40`, revisão `83d2f97d`, delta consumidor `2ced7b79` | Âmbito líquido, fundamentos, exactidão, exemplos e limites QA |
|
||||
| IM-P | `IM/simulations/primary-text-review-2025-2026.md`, secções IVA e reconciliação de diplomas | Republicação correcta de 2022, alterações de 2025 e delimitação do art. 34 |
|
||||
| IM-A | `IM/simulations/modelo-a-reconciliacao-20261021.md`, nota activa de 24/10; referências `cd10cccb`, `d18ff0f0`, instalação documentada `e250d569` | Evidência posterior de consumidor declarativo; mantém valores brutos sem extracção automática; não equivale a emissão de factura |
|
||||
| IM-E | `IM/simulations/l1-currency-events-delivery-20261025.json`, candidato `0052cd42d2755753b7e54257db05df8fbd9f08bc`; `iva-l1-currency-events-qa-20261025.json`, implementação documentada `7e6e462e12a50aab6ba0043740ffeecb414cbedf` | Facto gerador/exigibilidade: P131/P132 completos no recorte, P104 cambial parcial; L1 continua aberto |
|
||||
| IM-D | `IM/simulations/data-contracts.md` e referências de representação na matriz | Separar simulação financeira e formulários IRPC de regras de factura IVA |
|
||||
|
||||
Foram também consultadas referências documentais dos recibos de continuação integrada. Não se abriram os ficheiros de código, configurações ou saídas privadas que esses documentos mencionam. Não se executaram os testes neles descritos.
|
||||
|
||||
### Matriz de regras, provas e adequação ao SGF
|
||||
|
||||
| Regra | Origem/versão | Fonte, vigência e condições | Provas existentes documentadas | Classificação e reaproveitamento | Pendência efectiva para SGF |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| Base tributável | IM-F v1.2, IM-P | CIVA republicado pela Lei 13/2016, art. 15(1), especiais 15(2), inclusões 15(5), exclusões condicionais 15(6), PDF 13–14; início 01/01/2017, alterações confrontadas com 2022/2025 | Base 100 → imposto 16; base 105 após componentes condicionais → 16,8 | **Fundamentada, adaptação de caso pendente.** Reutilizar contraprestação e condições; orçamento, rótulo de serviço ou `q×p` não provam base legal | Confirmar que o serviço pontual SGF corresponde à base líquida proposta, sem componentes especiais |
|
||||
| Taxa geral e vigência | IM-F/IM-P; decisão de proveniência documentada em 08/10 | Lei 22/2022 **republicada**, art. 17(1), PDF 3, BR 2252-(27); art. 6 da lei, PDF 4: 01/01/2023. Lei 10/2025, vigente desde 01/01/2026, não inclui arts. 15/17 na lista de alterações | Perfil QA `IVA-GERAL-BASE-LIQUIDA`: 16 percent, moeda MZN, contexto declarado `internal_general_net`, cobertura técnica 2026 | **Regra geral fundamentada; simulação demonstrada.** Reutilizar cadeia documental e taxa exacta sob o âmbito aplicável, não as imagens como fonte | Confirmar regime, incidência, localização e tratamento da operação/empresa; não presumir taxa geral para toda operação |
|
||||
| Âmbito do serviço | IM-F | CIVA arts. 1(1)a, 2(1)a, 4(1), 6(3) e excepções; não generalizar art. 6(1), relativo a bens, aos serviços | Exclusões expressas: isenções, taxas reduzidas, importações, digital/não residentes, dedução/reembolso | **Fundamentada com classificação pendente.** Reutilizar perguntas e fronteiras, não classificação automática pelo perfil do cliente | Identificar serviço e localização concretos; dimensão, nome e NUIT não demonstram regime |
|
||||
| Data fiscal | IM-F + IM-E de 25/10 | CIVA art. 17(2); facto gerador art. 7, PDF 8; exigibilidade art. 8, PDF 9. Cadeia 2022/2025 documentada sem alteração destes artigos | IM-E: 9 ramos P131 e 5 tratamentos P132; serviço concluído e cobrança antecipada distinguidos; factura pontual/tardia/ausente, pagamentos e resto pendente. 19 testes frontend, 1 teste API/65 asserções, prova Edge de recuperação, reportados no recibo | **Fundamentada e ensaiada no recorte.** Reutilizar distinção acontecimento/exigibilidade e casos, não data da consulta, vencimento ou B1 como substituto | Aplicar ramo ao serviço SGF e identificar os dados que o comprovam; não implementar todos os 14 ramos neste primeiro incremento |
|
||||
| Precisão | IM-F v1.2 e provas QA | Decimal/racional exacto; taxa em percent distinta de fracção; `not_applied`, sem arredondamento automático | `0,03×16%=0,0048`; `9007199254740993,0003×16%=1441151880758558,880048`; zero explícito distinto de ausente | **Orientação técnica já estabelecida e demonstrada.** Reutilizar os casos e representação exacta, sem copiar código nem reabrir este princípio | Limites técnicos do SGF e tratamento de capacidade; o caso grande é prova do portal e não alarga os limites de entrada de A |
|
||||
| Arredondamento do cálculo líquido | IM-F v1.2 | Nenhuma quantização é aplicada nesse percurso; duas casas monetárias não obrigam a arredondar o resultado exacto | `0,0048` preservado, não convertido em `0,00`; persistência/relatório conservam resultado | **Reutilizável no mesmo âmbito.** Retirar a ausência de política genérica como bloqueio ao cálculo exacto líquido; não escolher HALF_UP/HALF_EVEN | Uma exigência futura de formato/consumidor requer fundamento próprio, sem alterar o valor exacto |
|
||||
| Preço com imposto incluído | IM-F/IM-P/IM-A | CIVA art. 34, Lei 10/2025, PDF 14: extracção com divisor 116 e arredondamento à unidade mais próxima **nesse contexto** | O percurso líquido exclui extracção; Modelo A preserva bruto sem calcular a base; não foi demonstrada emissão SGF | **Regra identificada, adequação pendente.** Reutilizar fonte e delimitação, não transpor genericamente o arredondamento para toda factura | Conferir âmbito do art. 34 no consumidor de factura pretendido, unidade, sequência e empates aplicáveis; identidade algébrica não resolve isso |
|
||||
| Apresentação e reconciliação | IM-F, IM-A, IM-D e matriz | CIVA art. 27(5)c/d distingue preço líquido/base, taxa e imposto. RIVA art. 9(1)b do exemplar de 2008 trata cheque/vale, não arredondamento universal. M20/M22 são representações IRPC | QA preserva valor/moeda/contexto e fotografia; exemplos artificiais de centésimos mostram conflitos, não normas | **Princípios reutilizáveis; adaptações declarativas não aplicáveis à factura.** Separar cálculo, apresentação e emissão | Determinar apenas a representação exigida para o consumidor futuro; não arredondar para imitar formulário fiscal |
|
||||
| Historial e limites das provas | IM-F revisões e IM-E | Regra/entradas/contexto versionados, relatório preservado; simulação sobre enquadramento declarado | IM-F: 6 testes/86 asserções de governação; delta 8 testes/75 asserções e 2 frontend; rota QA 1 teste/17 asserções; exemplo Edge 1000,03 → 160,0048 recuperado com hash igual | **Evidência técnica reportada, não homologação jurídica.** Reutilizar requisitos de rastreabilidade e casos sintéticos, preservando B1 do SGF | Não transferir papéis, bypass RLS de QA, credenciais, contas ou estado de activação do portal. Testes de política não provam isolamento RLS |
|
||||
|
||||
A aceitação documental de uma fonte no portal não é parecer jurídico nem aprovação automática para emitir no SGF. As provas acima são as reportadas nas versões identificadas, não uma nova execução nem conferência independente do estado actual. A cobertura QA de 01/01–31/12/2026 não é caducidade legal da taxa em 31/12/2026. O trabalho recente de IRPC e os formatos M20/M22 não constituem fundamento de arredondamento IVA.
|
||||
|
||||
### Exemplares e integridade
|
||||
|
||||
Verificados por leitura os SHA-256 das cópias em `IM/simulations/source-archive/`; coincidem com os registados na ficha. O cotejo de artigos/páginas acima é reaproveitado da leitura documental do portal: não se apresenta como nova leitura jurídica integral dos PDFs nesta revisão.
|
||||
|
||||
| Exemplar | SHA-256 confirmado |
|
||||
| --- | --- |
|
||||
| `Lei-13-2016-CIVA-BR-156-10-suplemento.pdf` | `B90DC7C14ECEA2E378C4A62E8E5A47D54A5644C457BAEB8B8053B92FD2A5710B` |
|
||||
| `Lei-22-2022-IVA-republicada-BR-250-2-suplemento.pdf` | `EA1B0DC6F5CF6E595F6D9A19E7042F398999E0087CAEF1785F6E8FAC571B5F53` |
|
||||
| `BR-248-I-Suplemento-1-2025.pdf` | `CCF2A8DEECA820F2DD076B4B2141B1EFE3F6A806568C3A587CA59A8E92F4C251` |
|
||||
|
||||
Não houve nova pesquisa na Internet: as fontes e provas disponíveis permitem reduzir as lacunas antes de qualquer pesquisa adicional.
|
||||
|
||||
## 1. Caso mínimo proposto
|
||||
|
||||
Um serviço pontual, **uma linha**, uma moeda documental explicitamente escolhida, uma quantidade positiva, preço não negativo, um tratamento tributado e uma taxa positiva aplicável à data fiscal de referência aprovada. A especificação contempla os dois modos existentes: imposto incluído e acrescido. A proposta pequena da secção 8 começa pelo acrescido sobre base líquida; incluído permanece pendente até à adequação específica do art. 34, sem eliminar o modo existente. «Por definir» mantém pendência.
|
||||
|
||||
Sem descontos, adiantamentos, retenções, encargos adicionais, câmbio, múltiplas taxas, facturação parcial, correcções ou cálculos de recebimentos. Isenção, não sujeição e taxa zero não serão representadas como uma taxa positiva em falta: precisam de tratamento/fundamento próprios e ficam fora desta primeira implementação proposta. O enquadramento real ainda não está aprovado.
|
||||
|
||||
Uma linha reduz o primeiro incremento, mas não dispensa escolher e registar uma política por linha ou por documento. Nessa situação os resultados coincidem; não inferir daí equivalência quando se acrescentarem linhas. O exemplo de três linhas abaixo serve só para fechar essa decisão e impedir uma expansão silenciosa.
|
||||
|
||||
Continuar a mostrar **RASCUNHO — SEM VALIDADE FISCAL**. Um cálculo matematicamente completo não cria número fiscal, emissão, recebimento ou lançamento, nem altera a confirmação interna B1.
|
||||
|
||||
## 2. O que está confirmado e o que não está
|
||||
|
||||
| Estado | Conteúdo |
|
||||
| --- | --- |
|
||||
| Base existente a preservar | Quantidades/preços como cadeias decimais, até 16 algarismos inteiros/8 decimais; aritmética exacta; modos por definir/incluído/acrescido; moeda não presumida; contexto, permissões, versões e fotografias imutáveis |
|
||||
| Decisão expressa para esta especificação | Caso simples, distinção entre cálculo/arredondamento/apresentação, exemplos sintéticos, bloqueio por regras em falta e separação de numeração/emissão |
|
||||
| Proposta técnica a aprovar | Uma linha e uma taxa positiva; cálculo racional exacto; percurso líquido sem arredondamento; ensaios de quantização separados do perfil real; cálculo derivado de rascunho sem actualização retroactiva |
|
||||
| Informação em falta | Regime da empresa, natureza/localização da operação, tratamento, taxa/vigência aplicáveis, data fiscal de referência, moeda e responsável pela validação; regra específica de extracção/apresentação apenas quando o respectivo consumidor a exigir |
|
||||
| Não aprovado | Aplicar automaticamente 16% à Tempo Lda ou a qualquer serviço; presumir isenção/taxa zero; considerar verificada fiscalmente uma fórmula só porque fecha aritmeticamente |
|
||||
|
||||
## 3. Fontes oficiais: reconciliação com a documentação do portal
|
||||
|
||||
A pesquisa pública anterior encontrou a primeira publicação de 2022. **Correcção desta revisão:** não a usar como exemplar normativo; IM-P identifica que foi dada sem efeito e substituída pela republicação no **2.º suplemento do BR 250**, de 28/12/2022, 18 páginas. A cópia arquivada e o hash acima substituem aquela referência como fundamento. Não é necessário voltar a pedir o articulado de 2025: está identificado e cotejado em IM-P/IM-F.
|
||||
|
||||
| Fonte oficial / exemplar reutilizado | Regra documentada e vigência | Limite / acção restante |
|
||||
| --- | --- | --- |
|
||||
| [INM — Lei 13/2016, republicação CIVA](https://www.inm.gov.mz/pt-br/content/suplemento-n%C2%BA-10-de-301216-pag-1426-259-290-br-n%C2%BA-156-boletim-da-rep%C3%BAblica-i-serie), arquivo identificado acima | Arts. 1/2/4/6 incidência e serviços; 7/8 acontecimentos; 15 base; 17(2) taxa na exigibilidade; 27(5)c/d componentes documentais. Início 01/01/2017, ler com alterações posteriores | Aplicabilidade à operação concreta, não nova descoberta dos artigos |
|
||||
| [INM — Lei 22/2022 republicada, suplemento 2](https://www.inm.gov.mz/pt-br/content/assembleia-da-rep%C3%BAblica-suplemento-n%C2%BA-2-de-281222-pag-2252-25-42-br-n%C2%BA-250-boletim-da), arquivo identificado acima | Art. 17(1): 16%; art. 6 da lei: início 01/01/2023 | Taxa geral fundamentada; não configura automaticamente a Tempo Lda |
|
||||
| BR 248, suplemento 1, 29/12/2025, exemplar arquivado acima; IM-P/IM-F | Lei 10/2025, PDF 12–15, início 01/01/2026; art. 34 PDF 14 sobre extracção; arts. 15/17 não incluídos na lista de alterações | Confirmar adequação do art. 34 ao consumidor incluído pretendido; não presumir vigência única de todas as leis do mesmo boletim |
|
||||
| Decreto 7/2008, `BR-16-I-Serie-2008-04-16.pdf`, referenciado em IM-F | RIVA arts. 4/5: base/operação versus imposto devido após deduções; art. 9(1)b: meio de pagamento por cheque/vale, exemplar histórico | Não transpor esse arredondamento para cálculo líquido ou para toda factura |
|
||||
| Comunicação governamental de 30/09/2026, já registada em IM-F | Anúncio de alterações regulamentares; articulado publicado/eficácia por disposição não demonstrados nessa evidência | Pesquisar só quando uma disposição puder afectar o consumidor delimitado; não bloquear genericamente o cálculo líquido exacto |
|
||||
|
||||
As rectificações de 2017 e a referência a Decreto 8/2017/BR 50 de 30/03/2017 estão já sinalizadas no dossier; não repetir a busca no BR 54 incorrectamente associado. Correspondência de disposição e consolidação regulamentar permanecem pontuais quando relevantes, não prova de inexistência de conhecimento. Não se afirma consolidação integral de toda a legislação até hoje.
|
||||
|
||||
## 4. Entradas e perfil de cálculo proposto
|
||||
|
||||
Reutilizar IDs/versões de empresa, unidade, cliente, prestação e rascunho, linhas/preparação e moeda. Não duplicar cadastros ou alterar preços guardados. O perfil de regra, se futuramente aprovado, identifica:
|
||||
|
||||
- Regime e tratamento da operação, com prova de aplicabilidade.
|
||||
- Taxa exacta e unidade explícita: percentagem e fracção são distintas; 10% corresponde exactamente a 0,10, sem float.
|
||||
- Data fiscal de referência, regra que a determina e intervalo de vigência sem sobreposição/ambiguidade.
|
||||
- Moeda e modo incluído/acrescido. Para o percurso líquido, arredondamento `not_applied` e reconciliação exacta `B* + I* = T*`. Escala/pontos/método de quantização só para o consumidor específico fundamentado.
|
||||
- Identidade/versão do perfil, fontes, responsável/estado de validação e âmbito da empresa/operação.
|
||||
|
||||
Os exemplos usam **UT, unidade monetária fictícia de ensaio**, não um código ISO nem a moeda da Tempo Lda. Duas casas e taxas de 10%/20% são parâmetros artificiais do ensaio, não configuração real. Uma taxa de 16% observada nas imagens não activa qualquer perfil.
|
||||
|
||||
## 5. Fórmulas exactas, anteriores a qualquer arredondamento
|
||||
|
||||
Definir `q` quantidade, `p` preço unitário proposto e `r` taxa em fracção exacta. `B*`, `I*`, `T*` são valores matemáticos anteriores à quantização, não montantes emitidos.
|
||||
|
||||
| Modo | Fórmulas |
|
||||
| --- | --- |
|
||||
| Imposto acrescido | `B* = q × p`; `I* = B* × r`; `T* = B* + I*` |
|
||||
| Imposto incluído | `T* = q × p`; `B* = T* / (1 + r)`; `I* = T* − B*` (equivalente a `T* × r / (1 + r)`) |
|
||||
| Por definir / tratamento desconhecido | Não escolher fórmula fiscal. Conservar apenas a aritmética provisória já existente e pendências |
|
||||
|
||||
Estas identidades matemáticas não provam que `q × p` seja a base legal da operação. Só se usam quando o perfil fiscal aprovado confirmar que esse caso simples corresponde ao valor relevante, sem componentes adicionais. Um preço incluído desconhecido não é «base sem imposto».
|
||||
|
||||
### Precisão de cálculo
|
||||
|
||||
Princípio existente, reforçado pelas provas do portal: multiplicação decimal exacta e **fracções racionais exactas** quando a divisão não terminar, reutilizando Brick\Math já instalado, sem novas dependências. Não truncar uma divisão a 8/12 casas e voltar a usá-la como valor exacto. Os limites de entrada de A não são uma regra de arredondamento monetário; produtos/divisões podem exigir mais casas.
|
||||
|
||||
Conservar entradas canónicas e, se necessário para rastreio, numerador/denominador dos resultados exactos. Decimal de uma fracção periódica mostrado ao utilizador deve ser marcado como aproximação e nunca realimentar o cálculo. Definir limites técnicos de tamanho/execução antes da implementação, sem transformar um erro de capacidade em arredondamento silencioso.
|
||||
|
||||
### Arredondamento / quantização
|
||||
|
||||
Definir explicitamente `Q(s,m,x)`: escala monetária `s`, método `m`, valor exacto `x`. Aplicar apenas nos pontos aprovados. A apresentação com duas casas não autoriza quantizar todos os passos a duas casas.
|
||||
|
||||
Parâmetro exclusivo de ensaio, **não norma fiscal nem preferência de produto**: `s=2`, `m=HALF_UP` para valores não negativos. HALF_EVEN e políticas por linha/documento servem para demonstrar diferenças; a regra real exige fundamento fiscal aplicável, começando pela comparação com o material do portal. Não suportar valores negativos neste incremento; correcções exigem âmbito próprio.
|
||||
|
||||
### Ensaios de reconciliação para uma linha — não adoptar como perfil fiscal
|
||||
|
||||
As duas políticas seguintes ficam preservadas apenas como hipóteses de ensaio que expõem diferenças. Não são a proposta actual para o percurso líquido, que conserva B*, I* e T* exactos com `not_applied`; não se pede aprovação por preferência entre métodos:
|
||||
|
||||
- **Acrescido:** `B = Q(B*)`; `I = Q(I*)`; `T = B + I`. A diferença `T − Q(T*)`, se existir, deve ser registada/explicada; não substituir silenciosamente o total por outro cálculo.
|
||||
- **Incluído:** preservar a âncora bruta `T = Q(T*)`; calcular `I = Q(I*)`; obter `B = T − I`. Registar explicitamente `delta_base = B − Q(B*)`. Esta política de base por diferença evita inventar um desconto, mas precisa de aprovação fiscal; não a apresentar como simples arredondamento independente da base.
|
||||
|
||||
Invariantes a verificar no perfil aprovado: mesma moeda, `B + I = T`, reprodutibilidade e explicação das diferenças face aos valores exactos. Se a norma exigir outra âncora/sequência, substituir o perfil proposto por essa regra antes de implementar. Não exigir simultaneamente invariantes incompatíveis nem esconder o conflito.
|
||||
|
||||
Para múltiplas linhas, somar resultados quantizados por linha pode diferir de quantizar uma soma exacta. Se a política for por documento, falta definir a afectação dos resíduos às linhas e o critério determinístico. Isso não entra implicitamente no primeiro caso de uma linha. Nenhum «ajuste» sem identidade/regra, alteração de taxa ou conta transitória para fazer coincidir totais.
|
||||
|
||||
### Apresentação
|
||||
|
||||
Separar valores exactos, componentes quantizadas e formatação (casas/separadores/língua/moeda). Não analisar novamente texto formatado para calcular. Continuar a distinguir cálculo matemático, validação fiscal e emissão. Mesmo com perfil aprovado, nesta fase o documento é rascunho; total calculado sob perfil não significa dívida emitida ou autorização de emissão.
|
||||
|
||||
## 6. Exemplos sintéticos e resultados esperados
|
||||
|
||||
Perfil fictício `ENSAIO-UT-HU2`, não activável na Tempo Lda; escalas/taxas/âmbitos temporais abaixo são apenas dados de teste. Nenhuma inserção nas bases foi realizada.
|
||||
|
||||
| Caso | Entradas | Resultado exacto | Resultado esperado sob o perfil de ensaio |
|
||||
| --- | --- | --- | --- |
|
||||
| A — acrescido | `q=2,5`, `p=80`, `r=10%` | `B*=200`, `I*=20`, `T*=220` | `B=200,00`, `I=20,00`, `T=220,00 UT` |
|
||||
| B — incluído | `q=2`, `p=55`, `r=10%` | `T*=110`, `B*=100`, `I*=10` | `B=100,00`, `I=10,00`, `T=110,00 UT` |
|
||||
| C — empate de arredondamento, acrescido | `q=1`, `p=0,05`, `r=10%` | `B*=0,05`, `I*=0,005`, `T*=0,055` | HALF_UP: `B=0,05`, `I=0,01`, `T=0,06`. HALF_EVEN, como alternativa de comparação: `I=0,00`, `T=0,05`. Não intercambiáveis |
|
||||
| D — incluído com reconciliação | `q=1`, `p=0,03`, `r=20%` | `T*=0,03`, `B*=0,025=1/40`, `I*=0,005=1/200` | Hipótese incluído de ensaio: `T=0,03`, `I=0,01`, `B=0,02 UT`; `delta_base=-0,01`. Arredondar B* e I* independentemente daria `0,03+0,01=0,04`, incompatível com o bruto de `0,03`; não ocultar a diferença |
|
||||
| E — quantidade fraccionada e preço muito pequeno | `q=1,25`, `p=0,00000001`, acrescido, `r=10%` | `B*=0,0000000125`, `I*=0,00000000125`, `T*=0,00000001375` | À escala fictícia 2, todos quantizam para `0,00`. Preservar os positivos exactos; decidir se a política real permite ou bloqueia essa situação, sem elevar artificialmente preço/total |
|
||||
| F — preço explicitamente zero | `q=1`, `p=0`, acrescido, perfil e taxa conhecidos | `B*=I*=T*=0` | `0,00` sob regra completa; não demonstra que qualquer serviço gratuito tenha esse tratamento fiscal |
|
||||
| G — taxa/tratamento em falta, mesmo com preço zero | `q=1`, `p=0` ou `80`, sem perfil fiscal completo | Apenas a aritmética provisória é conhecida | Imposto/total fiscal não apurados; pendência e cálculo não validado. Não usar zero para suprir informação fiscal |
|
||||
|
||||
**Comparação por linha/documento, fora do caso mínimo:** três linhas de base exacta `0,05`, cada uma com taxa artificial de 10%. HALF_UP por linha: imposto `0,01 × 3 = 0,03`, base `0,15`, total `0,18`. Por documento: imposto `Q(0,015)=0,02`, total `0,17`. Diferença `0,01`; bloquear a extensão a múltiplas linhas enquanto a política e a distribuição não estiverem aprovadas.
|
||||
|
||||
**Vigência fictícia:** perfil A válido de 01/01/2030 a 30/06/2030, perfil B desde 01/07/2030, para a mesma operação artificial. Na data fiscal de referência 30/06 seleccionar A; em 01/07 seleccionar B. Data desconhecida, lacuna ou sobreposição ⇒ pendência, sem escolher «a taxa mais recente». Estas datas não representam alteração legal real.
|
||||
|
||||
**Casos recusados/pendentes adicionais:** moeda ausente ou diferente no mesmo cálculo; preço com precisão excedente; quantidade não positiva; modo por definir; regra expirada/sem fonte ou sem validação; rascunho/contexto desactualizados; discrepância de reconciliação; leitura de empresa/unidade alheia. Manter a recusa e o motivo sem gravar resultados parciais como válidos.
|
||||
|
||||
## 7. Estados e comportamento quando faltar regra
|
||||
|
||||
Proposta de distinção, sem novos estados de emissão:
|
||||
|
||||
1. **Pendente de dados/regra:** lista precisa do que falta; imposto/base fiscal/total não apurados conforme dependências. A aritmética provisória existente pode continuar visível, claramente separada.
|
||||
2. **Simulação sintética:** fórmula/perfil de ensaio explícitos e isolados em testes; nunca valida a empresa real.
|
||||
3. **Calculado sob perfil aprovado:** só depois de entradas, aplicabilidade, vigência, moeda e política completas, com resultado reconciliado. Ainda não significa documento emitido nem validação automática de todas as obrigações fiscais.
|
||||
4. **Conflito/fora do âmbito/falha técnica:** não há resultado validado; preservar entradas e última versão identificada sem a apresentar como actual. Falha técnica não é isenção, pendência resolvida ou taxa zero.
|
||||
|
||||
Sem regime, tratamento, taxa, data/vigência ou moeda aplicáveis: **não calcular imposto por omissão e não marcar validado**. No percurso de base líquida exacta, `not_applied` é explícito: a ausência de política genérica de arredondamento não impede esse cálculo. Se faltar uma regra específica exigida para extracção do incluído ou para o consumidor monetário, manter pendente esse resultado/consumidor, sem invalidar silenciosamente valores exactos já determinados. Dar origem e próxima acção: completar dados, obter fonte vigente, confirmar enquadramento ou aprovar a política. Alterar dados/regra invalida a actualidade do cálculo, sem mudar silenciosamente resultados já consultados.
|
||||
|
||||
## 8. Pequena proposta de implementação futura
|
||||
|
||||
Depois da aprovação do incremento, começar pelo percurso de base líquida, uma linha e moeda explícita, sem arredondamento automático. Acrescentar um calculador determinístico do caso de uma linha, reutilizando o rascunho e uma versão explícita de perfil. Não construir já um motor fiscal geral ou editor de taxas arbitrárias. Se faltar validação real, só poderá existir ensaio sintético isolado autorizado; não activar regras incompletas na Tempo Lda.
|
||||
|
||||
Resultado derivado proposto: IDs/versões de origem, modo, perfil/fontes/vigência, data de referência, moeda/escala, entradas exactas, resultados exactos, política/pontos de quantização, componentes reconciliadas, resíduos explícitos e estado/pendências. Definir conservação/versionamento desse resultado no delta futuro; não o inserir no JSON de uma fotografia B1 existente.
|
||||
|
||||
Integração mínima na pré-visualização: manter aviso de rascunho, mostrar o perfil e distinção entre valores exactos/calculados/por validar, sem número ou emissão. A leitura continua sem resolver pendências por si só. Os antigos rascunhos com modo desconhecido não são reinterpretados automaticamente; a activação futura deve ser explícita e versionada. Configurar apresentação não concede gerir regras fiscais ou aprovar cálculos; acessos concretos terão aprovação própria se necessários.
|
||||
|
||||
Provas a exigir futuramente no recorte aprovado: casos exactos reutilizados IM-F, casos A/F/G, moeda desconhecida, datas de vigência, perfil sem validação, versão/contexto, isolamento, reprodutibilidade, reconciliação e permanência das fotografias B1/preparação histórica. Prova visual só em instância isolada com `sgf_tempo_test`; nenhuma operação real ou fixture na Tempo Lda. Nesta etapa não foram implementados ou executados testes do sistema.
|
||||
|
||||
## 9. Decisões realmente restantes
|
||||
|
||||
**Escolhas de produto:** aprovar o primeiro incremento pequeno de cálculo exacto sobre base líquida, uma linha, mantendo incluído visível mas pendente de adequação normativa; indicar a moeda concreta (MZN é a cobertura documentada do portal, não um valor a presumir no SGF) e os actores autorizados. Se o objectivo exigir incluído já no primeiro incremento, resolver antes o ponto fiscal específico abaixo. Nenhuma concessão é inferida dos direitos de pré-visualização.
|
||||
|
||||
**Validação fiscal da operação:** identificar regime, serviço/localização e tratamento aplicáveis à empresa, confirmar que a contraprestação simples constitui a base do art. 15 e determinar o acontecimento/exigibilidade pelos arts. 7/8. A cadeia documental da taxa geral de 16% desde 2023 já foi encontrada; resta a sua aplicabilidade ao caso, não escolher de novo uma taxa por preferência.
|
||||
|
||||
**Incluído e consumidores futuros:** verificar a adequação do art. 34 à factura pretendida e, se aplicável, unidade, sequência e tratamento de empates com fundamento. Só depois definir extracção/reconciliação/apresentação. HALF_UP/HALF_EVEN e formatos M20/M22 não substituem essa validação. Procurar alterações regulamentares apenas para a disposição/consumidor que possa ser afectado, reutilizando o dossier e os exemplares já identificados.
|
||||
|
||||
Não voltam a aprovação valores exactos, ausência de truncagem silenciosa, desconhecido diferente de zero ou história preservada. Não é necessário pedir de novo R1–R6. Nenhuma regra é activada nesta revisão. Não se alteraram código, bases, permissões, fotografias ou portal; não se copiaram implementações nem se executaram testes. Numeração, emissão, PDF, recebimentos, contabilização e publicação permanecem fora do âmbito.
|
||||
@@ -0,0 +1,195 @@
|
||||
# Factura de serviço — âmbito mínimo de emissão
|
||||
|
||||
26/10/2026, Africa/Johannesburg. Versão 0.3, **âmbito com implementação técnica isolada autorizada posteriormente**, conforme secção 10. Base preservada: checkpoint `9f48004`, cálculo condicionado aceite. Configuração/concessões reais e habilitação de emissão não são autorizadas pelo desenvolvimento técnico.
|
||||
|
||||
## 1. Base reutilizada e recorte proposto
|
||||
|
||||
Reutilizar a ficha local `REAL_SERVICE_FISCAL_ASSESSMENT.md`, [aceitação do cálculo condicionado](CONDITIONAL_CALCULATION_ACCEPTANCE.md), [matriz de informação documental](BILLING_DOCUMENTS_FIELD_SPEC.md), [especificação e matriz fiscal reutilizada](SERVICE_INVOICE_CALCULATION_SPEC.md), preparação documental, pré-visualização e B1. A ficha nominativa permanece local; esta especificação não exporta o cliente ou os registos da base.
|
||||
|
||||
O perfil aprovado/activo e a decisão temporal aprovada mantêm os seus âmbitos. A segunda permite hoje cálculo condicionado, não determina exigibilidade ou apuramento. Não repetir a sua aprovação para voltar a demonstrar o que já foi aceite; uma autorização para emitir é um acto distinto.
|
||||
|
||||
**Primeiro recorte:** uma factura de serviço, uma linha, uma moeda explícita, preço sem imposto, sem descontos, retenções, adiantamentos, câmbio ou recorrência automática. Uma prestação e um rascunho existentes originam no máximo uma factura neste recorte; facturação parcial/dividida fica excluída. Factura não é recibo ou factura-recibo; emissão não declara pagamento nem reconhecimento contabilístico.
|
||||
|
||||
**Entrega mínima proposta:** revisão de prontidão → confirmação explícita de emissão → identidade documental e fotografia imutável → consulta e reprodução fiel do documento. O desenho pode ser implementado e provado em testes isolados antes da habilitação real; enquanto faltarem condições legais, o ambiente normal recusa emitir e a prova continua claramente sintética. Não apresentar uma simulação como factura válida.
|
||||
|
||||
## 2. Fontes reutilizadas e limites jurídicos
|
||||
|
||||
Não foi repetido o cotejo do InvesteMoz, consultado o portal ou efectuada nova pesquisa normativa nesta etapa. Reutilizam-se as referências/versões e os hashes já registados na matriz e na ficha:
|
||||
|
||||
| Matéria | Origem já identificada | Uso e limite neste incremento |
|
||||
| --- | --- | --- |
|
||||
| Base, taxa, exactidão e representação | IM-F v1.2, IM-P, IM-A; CIVA arts. 15/17; Lei 22/2022 republicada | Cálculo aceite é reutilizado. Política operacional de truncagem não é prova de conformidade universal de factura |
|
||||
| Acontecimento e exigibilidade | IM-E, recibos L1 de 25/10/2026; CIVA arts. 7/8/17(2) | Distinguir regra pré-validada, facto efectivo, parcela e mês. Não converter próxima facturação em emissão/exigibilidade |
|
||||
| Informação da factura | Matriz documental; CIVA art. 27, incluindo n.º 5 c/d já cotejado | Inventário de campos e componentes; confirmar cobertura integral dos requisitos aplicáveis antes de habilitar emissão. Não declarar que apenas os campos já implementados bastam legalmente |
|
||||
| Alterações de 2026 | Lei 10/2025, PDF 12–15 do exemplar BR 248/suplemento 1; art. 27(10), PDF 14, e art. 32 | A submissão à AT é matéria distinta da apresentação visual e da identidade interna. O art. 32 rege os ramos declarativos já documentados, não numeração ou homologação do SGF |
|
||||
| Regulamentação de emissão e software | RIVA art. 21 nos exemplares históricos já sinalizados; Decreto 8/2017/rectificações; comunicação regulamentar de Setembro de 2026 | Referências históricas/anúncio não demonstram, por si, o procedimento vigente aplicável em 2026. Concluir apenas a lacuna específica necessária à emissão, sem refazer taxa/base/aritmética |
|
||||
|
||||
**Autorização/certificação do software ainda não demonstrada:** não foi apresentada prova de que o SGF esteja autorizado/certificado/homologado para emitir, nem prova documentada de dispensa/inaplicabilidade. Também não está demonstrado qual procedimento vigente distingue autorização de sistemas/numeração, tipografias, facturação electrónica e comunicação de documentos à AT. São questões distintas; não inventar um número de certificação, assinatura, QR, fornecedor ou integração, nem afirmar que todos são obrigatórios ou dispensados.
|
||||
|
||||
Antes de emissão real: obter disposição oficial aplicável, artigo, vigência, âmbito deste modo de emissão e evidência do cumprimento ou da dispensa. Se existir acto/autorização, conservar referência verificável, entidade competente, titular/versão/instalação abrangidos e limites. Se houver comunicação prévia, formato obrigatório ou aceitação externa necessária à validade, definir o protocolo e estados com fundamento. A ausência destas provas bloqueia habilitação real; testes de aritmética, Git ou aprovação empresarial não as substituem.
|
||||
|
||||
## 3. Prontidão: o que bloqueia e o que nasce ao emitir
|
||||
|
||||
| Elemento | Antes de emitir | No acto de emissão / efeito posterior |
|
||||
| --- | --- | --- |
|
||||
| Emitente/cliente | Dados exigidos para o caso, origem e validação documental identificados. Nome suficiente para rascunho não significa prontidão de emissão | Fixar exactamente os dados usados; alterações posteriores do cadastro não mudam a factura |
|
||||
| Serviço/prestação | Natureza, contraprestação, unidade de medida e cobertura relevantes demonstradas; não certificar execução a partir de rascunho | Preservar referências e versão da prestação. A factura não cria automaticamente prova de entrega |
|
||||
| Perfil e resultado | Perfil aprovado, activo, vigente e compatível; resultado exacto actual. Representação documental aplicável validada, sem truncagem da base ou ajustes silenciosos | Revalidar contra a data/acontecimento efectivamente aplicável; se mudar a regra ou o montante, recusar e voltar à revisão |
|
||||
| Decisão temporal | A actual aprovação de `pending` não basta. É necessária regra de determinação aprovada, com condições verificáveis para o ramo aplicável e prazo de emissão fundamentado | Quando a emissão for o acontecimento pertinente e tempestivo, capturar o instante real e determinar a consequência com essa regra. Não exigir uma factura já emitida para autorizar a primeira emissão |
|
||||
| Datas anteriores relevantes | Se o facto gerador, prazo vencido ou outro acontecimento anterior for relevante, precisa de evidência antes da emissão | A emissão posterior não apaga ou desloca exigibilidade já ocorrida. Casos fora do primeiro recorte são recusados, não normalizados à data actual |
|
||||
| Emissão efectiva | Não inventar uma data real antecipada para conseguir aprovação. Revisão pode mostrar «será fixada ao emitir» e a data esperada da operação | Instante do servidor com timezone explícita; guardar UTC, zona e data civil usada. Sem retrodatação/editabilidade neste primeiro recorte; mudança de dia desde a revisão obriga a rever |
|
||||
| Período de apuramento | Não exige um mês inventado enquanto falta o acontecimento; exige regra aprovada que permita determiná-lo sem ambiguidade | Derivar do ramo de exigibilidade efectivamente fundamentado, na mesma confirmação; não deriva do ano da série ou do vencimento do cliente |
|
||||
| Vencimento | Condições comerciais identificadas quando necessárias; «30 dias de serviço» não é prazo de crédito | Calcular apenas sob convenção acordada; não usar a próxima facturação como vencimento |
|
||||
| Série e número | Série válida, âmbito/numeração inicial/fonte e processo de autorização identificados; ausência ou conflito bloqueia | Atribuir número definitivo uma única vez, dentro da operação controlada; nunca ao abrir a pré-visualização |
|
||||
| Software e comunicação | Prova de conformidade/autorização/dispensa e processo de comunicação aplicável resolvidos | Se aceitação externa for condição, não marcar emitido antes dela; se comunicação for posterior, estado/prazo próprios e retries sem nova factura |
|
||||
| Pagamento ao Estado | Não é necessário ter o apuramento líquido pago para criar uma factura; conhecer a regra declarativa não implica saldo calculado | Esta emissão não liquida o saldo ao Estado nem cria recebimento do cliente |
|
||||
|
||||
O sistema deve apresentar bloqueios concretos e a fonte/condição correspondente. Não promover todos os campos de gestão opcionais a bloqueios legais: logótipo, contactos e instruções bancárias não passam a obrigatórios por constarem dos exemplos. Não reabrir a classificação contabilística para satisfazer emissão; se a operação exigir classificação, reutilizar a resolução existente sob o seu âmbito.
|
||||
|
||||
**Estado do caso conhecido:** a última conferência da pré-visualização mostrava dados documentais do emitente/cliente por completar e cobertura final não indicada; essa observação não é uma nova leitura da base. O cálculo e perfil estão aceites, mas não há prova de prontidão documental/fiscal integral. A decisão temporal permanece `pending`. Só confirmar como bloqueante cada falta que seja necessária ao caso/regra de emissão; não preencher a partir das imagens ou da data prevista de facturação.
|
||||
|
||||
## 4. Série, identidade e numeração — proposta técnica
|
||||
|
||||
- Identidade estável da factura separada do ID do rascunho, referência INT-B1, série/contador e ficheiro de apresentação. Unicidade proposta **empresa emitente + tipo + série + número**; série não é necessariamente ano e não pertence ao tenant como autorização geral.
|
||||
- Uma série inicialmente para o tipo factura no âmbito aprovado; relação à unidade, ano/período e continuação de numeração exige decisão própria. Não criar automaticamente «FT/2026», começar em 1 ou importar o número das imagens.
|
||||
- Cadastro de série versionado, estado aberto/encerrado, vigência, fonte/autorizações e contador protegido. Série encerrada não recebe novos números. Abrir/encerrar série não apaga documentos ou reutiliza números.
|
||||
- Alocação sob bloqueio transaccional do contador; proibir duplicação/reutilização por API e na base, incluindo operações em massa. Concorrência em rascunhos diferentes da mesma série dá números distintos.
|
||||
- Proposta local: atribuição de número e factura na mesma transacção, sem reserva exterior prévia. Falha anterior ao commit não produz uma factura; número não comunicado fora da transacção. Se regras legais/serviço externo exigirem reserva ou numeração não transaccional, rever este ponto e registar reservas/falhas explicitamente; não prometer ausência universal de lacunas ou apagar evidência de falhas.
|
||||
- Reimpressão/reprodução conserva identidade, número, data e fotografia; rótulos original/cópia/duplicado e formato dependem das regras documentais aplicáveis, não de nova numeração.
|
||||
|
||||
## 5. Comando de emissão, fotografia e duplicados
|
||||
|
||||
1. **Rever emissão:** no contexto validado, consultar o rascunho actual e compor revisão coerente de cliente/emitente, prestação, preparação, cálculo, perfil, decisão/regra temporal, série, modelo e eventuais autorizações. Mostrar consequências e bloqueios; nenhuma atribuição de número.
|
||||
2. **Confirmar:** pedido autenticado, CSRF, permissão própria, token de contexto, versões exactas, chave de idempotência e resumo criptográfico da revisão. O navegador não autoriza âmbito nem escolhe livremente taxa, número, data efectiva ou estado.
|
||||
3. **Revalidar e fixar:** sob bloqueios consistentes, verificar direitos, prontidão, série, versões e regra temporal. Capturar o instante de emissão, resolver a consequência fiscal quando suportada, reconciliar montantes e atribuir número. Alteração material/viragem de data exige nova revisão, não substituição silenciosa.
|
||||
4. **Commit atómico:** factura, fotografia, identidade/série/número, vínculo exclusivo ao rascunho/prestação deste recorte, auditoria e evento durável/outbox. Falha de qualquer componente desfaz o conjunto local. Nenhum consumidor contabilístico ou financeiro é executado neste incremento.
|
||||
5. **Recuperar:** chave repetida com mesmo autor/conteúdo devolve a factura existente; mesma chave com conteúdo distinto é conflito. Duplo clique, timeout após commit, repetição de tarefa ou nova chave sobre rascunho já emitido não criam segunda factura. Disponibilizar consulta do resultado após resposta perdida.
|
||||
|
||||
Fotografia imutável: emitente/cliente e dados documentais usados; serviço/descrição/unidade/quantidade/preço; moeda; período/condições/vencimento; base, imposto exacto/documental, diferença e total; tratamento/taxa/fontes/política e versões; decisão/regra temporal e acontecimentos determinados; série/número/data efectiva; contexto/autor; versão de modelo e activos usados; instruções de pagamento se apresentadas; referência da conformidade/autorização aplicável. Preservar só o necessário, sem segredos.
|
||||
|
||||
A consulta emitida usa exclusivamente essa fotografia. Não reconstruir dados com cadastros actuais; guardar versão do renderizador/modelo e hash do artefacto final se existir. Hash é controlo de integridade técnico, não assinatura fiscal ou certificação. Falha posterior de geração de ficheiro não provoca nova emissão/novo número: reproduzir o mesmo documento fixado, conforme os requisitos do canal.
|
||||
|
||||
B1 continua exclusivamente confirmação interna histórica; não é convertido em factura emitida nem reescrito para ganhar dados ausentes. No mínimo, rascunho já bloqueado por B1 não é emitido directamente. Eventual passagem a novo rascunho ligado à origem precisa de desenho explícito, sem duplicação oculta da prestação.
|
||||
|
||||
## 6. Permissões e correcções
|
||||
|
||||
**Direitos propostos, ainda sem concessão:** `service_invoices.view` e `.issue` na unidade; `invoice_series.view` e `.configure` no âmbito da empresa, com restrições de uso por unidade. Confirmar nomenclatura final e matriz de contas antes de aplicar qualquer direito. Calcular, aprovar perfil/decisão temporal, gerir aparência ou confirmar B1 não concede emitir ou configurar séries. Revogação tem efeito no próximo pedido. Não atribuir automaticamente emissão a Osmane ou Samira.
|
||||
|
||||
Emitida significa imutável: recusar edição, eliminação, transferência de empresa/unidade e reabertura do original, também por SQL em massa. Antes da emissão pode corrigir-se o rascunho com novas versões/revisões; depois dela, a correcção deve ser documento/acontecimento próprio, autorizado, com motivo, autor, datas e ligação exacta ao original/linhas e impacto fiscal explicado.
|
||||
|
||||
No primeiro incremento, propor **pedido de correcção pendente, sem efeito monetário**, e consulta do original. Não implementar nota de crédito/débito ou anulação fiscal sem fundamento e âmbito aprovados. Não usar «cancelar» como apagamento, reutilizar número ou emitir substituição independente como atalho. Antes de habilitar emissão real, definir o procedimento legal e operacional para corrigir erros inevitáveis; se não estiver disponível no SGF, identificar procedimento externo autorizado e preservação das evidências, sem presumir que existe. Ausência de uma via válida de correcção é bloqueio de prontidão real.
|
||||
|
||||
## 7. Ecrãs e critérios de aceitação
|
||||
|
||||
Ecrãs mínimos: revisão de emissão no rascunho, com bloqueios e consequências; detalhe da factura emitida/reprodução fiel; configuração controlada da série; histórico e eventual pedido de correcção. Sem portal de clientes, envio por email, fornecedores, cobranças, stock ou contabilidade neste recorte. Canal/artefacto final precisa de decisão antes de implementar emissão real; uma página HTML não é presumida suficiente para todas as obrigações de entrega/conservação.
|
||||
|
||||
Provas isoladas com identidades sintéticas e `sgf_tempo_test`, sem operações fictícias na empresa real:
|
||||
|
||||
1. Prontidão incompleta, conformidade do software não demonstrada, série ausente/encerrada, moeda/perfil/regra incompatíveis e permissões insuficientes recusam emissão e não consomem uma identidade definitiva.
|
||||
2. Cenário completo sintético produz exactamente uma factura, número único, data efectiva controlada, fotografia imutável e evento durável. Mudar cadastros/apresentação posteriormente não muda o emitido.
|
||||
3. Pendência temporal aceite para cálculo não passa como autorização de emissão. Ramo dependente da emissão fixa o facto na confirmação, sob regra previamente aprovada; ramo anterior não é deslocado por data de emissão. Data futura prevista não se torna facto; viragem de dia obriga a rever.
|
||||
4. Duplo clique, mesma/diferente chave, timeout antes/depois do commit e dois processos concorrentes não duplicam factura ou número. Falhas injectadas em contador/fotografia/auditoria/outbox provam atomicidade e recuperação.
|
||||
5. Isolamento entre empresas do mesmo tenant e unidades, identificadores adulterados, revogação, versões antigas e alterações em massa recusados. Aprovações contabilísticas e B1 preservados, sem reruns desnecessários das entregas aceites.
|
||||
6. Reprodução posterior usa a fotografia, não recalcula com regras actuais e não renumera. Pedir correcção não altera montantes/estado fiscal do original; ausência de correcção fiscal implementada fica explícita.
|
||||
7. Nenhuma emissão marca recebimento, liquidação ao Estado ou lançamento como realizado. Provas sintéticas não retiram bloqueios de conformidade real nem seleccionam fornecedores.
|
||||
|
||||
## 8. Decisões realmente novas para delimitar implementação
|
||||
|
||||
| Decisão | Natureza / saída necessária |
|
||||
| --- | --- |
|
||||
| Série inicial | Empresa, tipo, código, âmbito por unidade/período, numeração inicial/continuação e evidência de autorização aplicável. Não repetir decisões de regime, moeda ou taxa já aprovadas |
|
||||
| Responsáveis e direitos | Quem pode emitir, configurar/encerrar série e pedir/tratar correcção; contas/âmbitos exactos sujeitos a confirmação específica |
|
||||
| Canal documental | Representação a entregar/conservar e formato requerido: navegador, PDF ou outro com fundamento. Não escolher integração/fornecedor por omissão |
|
||||
| Regra temporal para emissão | Quem propõe/valida a regra prospectiva e quais evidências fecham tempestividade/cobertura; preservar o facto efectivo para o momento de emissão. A aprovação anterior de pendência não é revogada nem convertida em determinação |
|
||||
| Conformidade e correcção | Evidência oficial específica para software/séries/comunicação, representação monetária aplicável e procedimento válido de correcção. É validação normativa/operacional, não preferência visual ou novo ensaio aritmético |
|
||||
|
||||
**Recomendação de execução futura:** primeiro resolver os bloqueios de prontidão que dependem de evidência/decisão, mantendo o sistema normal sem emitir; depois autorizar um único incremento de emissão/reprodução com as regras fechadas e provas sintéticas. Não criar um documento com aparência de factura fiscal apenas para contornar uma pendência legal. Se só for autorizada preparação técnica antes dessas provas, o modo real permanece bloqueado explicitamente.
|
||||
|
||||
Nesta revisão alterou-se apenas documentação. Nenhuma emissão, concessão, série, migração, recebimento, lançamento, teste destrutivo, publicação ou novo checkpoint foi executado. Não reabre `9f48004`.
|
||||
|
||||
## 9. Decisões de desenho confirmadas pelo utilizador
|
||||
|
||||
Em 26/10/2026, o utilizador respondeu **SIM** à proposta de responsabilidades e navegador + PDF. Prevalece sobre as opções ainda abertas nas secções anteriores:
|
||||
|
||||
- **Osmane prepara e emite.** Emitir será uma permissão nova, a apresentar com conta, empresa/unidade e acção exactas para confirmação específica antes da concessão. Não é derivada de calcular, preparar ou gerir acessos; nenhuma concessão foi executada nesta revisão.
|
||||
- **Samira mantém a validação fiscal.** Não recebe emissão ou administração por consequência desta escolha.
|
||||
- **Osmane propõe a regra temporal de emissão; Samira valida ou recusa a versão exacta.** Reutilizar a separação de funções existente. Não converter a decisão temporal pendente aceite no incremento anterior em determinação de exigibilidade/apuramento ou autorização para emitir.
|
||||
- **Consulta no navegador e PDF reproduzível da mesma fotografia imutável, sem envio automático.** Ambos apresentam o mesmo documento/identidade, conteúdo, datas e valores. Preservar a versão dos recursos/renderizador e, quando gerado, os bytes/hash do PDF; reconsultar ou descarregar não gera nova factura ou número. Não escolher agora biblioteca/dependência ou alterar versões.
|
||||
- **Série real ainda por decidir:** continuação de série existente ou série própria do SGF, com suporte e controlo de transição para impedir sobreposição com outro emissor. Não atribuir código, número inicial ou data por omissão. Quem propõe/configura/encerra séries e quem trata correcções continua por indicar; não atribuir essas funções automaticamente a quem emite ou valida.
|
||||
- **Bloqueio real mantido:** qualquer implementação futura antes de fechar a conformidade só pode ser demonstrada em ambiente isolado, com emissão real bloqueada. Esta confirmação de desenho não inicia implementação.
|
||||
|
||||
### Verificação dirigida das lacunas de conformidade
|
||||
|
||||
Consulta em 26/10/2026 limitada a software, numeração/comunicação e correcção; não repetiu o cotejo de taxa/base/exigibilidade já reutilizado. Não se alterou o InvesteMoz ou acederam às suas configurações/bases.
|
||||
|
||||
| Lacuna específica | Evidência localizada / alcance | Prova ainda necessária |
|
||||
| --- | --- | --- |
|
||||
| Software: submissão versus aprovação | O índice oficial da [AT — comunicados](https://www.at.gov.mz/informacoes/comunicado-de-imprensa) apresenta uma entrada datada de 01/02/2026 intitulada lista provisória de softwares de facturação. A abertura do endereço não disponibilizou articulado/anexo legível nesta consulta. A existência de lista provisória não demonstra certificação do SGF nem dispensa | Procedimento oficial aplicável, requisitos e evidência específica de autorização/certificação/dispensa para este software/instalação. Não declarar fechado com base em publicidade comercial ou lista de submissões |
|
||||
| Regulamento e numeração/comunicação | A [comunicação oficial do Governo](https://portaldogoverno.gov.mz/governo-introduz-alteracoes-nos-regulamentos-fiscais-para-reforcar-eficiencia-tributaria/) anuncia alterações ao RIVA, incluindo o art. 21. É evidência de alteração anunciada, não substitui o articulado publicado e a sua eficácia. O art. 27(10) da Lei 10/2025 e o inventário anterior continuam reutilizados | Diploma publicado e disposições executórias que fechem autorização de emissão por computador, série/faixa/numeração e eventual comunicação à AT. Confirmar se a comunicação condiciona emissão ou constitui obrigação posterior. Não inventar API, prazo ou homologação |
|
||||
| Correcção | O princípio aprovado de preservar o original e ligar a correcção permanece. A matriz documental e o percurso de serviços não comprovam forma/prazos fiscais da correcção real | Disposição oficial aplicável a anulação/rectificação e regularização de IVA, conteúdo do documento, evidência de conhecimento pelo destinatário quando exigível e procedimento autorizado. Não confundir recibo, estorno contabilístico ou pedido interno com nota fiscal válida |
|
||||
|
||||
**Resultado:** as lacunas não estão encerradas por esta pesquisa dirigida. Não se conclui que o procedimento ou conhecimento não exista; falta evidência primária suficiente nos materiais efectivamente acessíveis. Não repetir perguntas de desenho já resolvidas nem pesquisas gerais sobre 16% ou cálculo exacto.
|
||||
|
||||
**Lista reduzida de decisões pendentes:** escolha/suporte da série real; responsáveis por configurar/encerrar séries e tratar correcções; confirmação específica dos futuros direitos de emissão; provas oficiais de conformidade acima. Responsáveis de preparação/emissão/validação temporal e canal navegador + PDF ficam fechados. Os factos efectivos de emissão continuam a nascer no próprio acto, sob regra previamente validada.
|
||||
|
||||
## 10. Decisões posteriores e execução técnica autorizada
|
||||
|
||||
O utilizador confirmou **série nova**, Osmane prepara séries e pede correcções, Samira valida a configuração e o tratamento fiscal. Essas decisões estão encerradas, juntamente com Osmane preparar/emitir, propor regra temporal, Samira validar essa regra e navegador + PDF sem envio automático. Código/número inicial reais e novas concessões serão apresentados separadamente antes de aplicação.
|
||||
|
||||
Posteriormente autorizou a implementação técnica e os testes isolados, com emissão real bloqueada até resolver conformidade e com confirmações específicas antes de migração em desenvolvimento/concessões. Resultado, provas, delta e propostas concretas em [entrega técnica de teste](SERVICE_INVOICE_TEST_DELIVERY.md). Não reabre o cálculo aceite nem habilita emissão real.
|
||||
|
||||
## 11. Conformidade — cotejo dirigido de 27/10/2026
|
||||
|
||||
Esta secção actualiza a matriz de lacunas da secção 9, sem reabrir as decisões posteriores da secção 10. A migração e as oito concessões **já foram aplicadas por autorização específica**, conforme a entrega técnica. Não estão pendentes. Série real, contador e documentos continuam sem criação; o bloqueio real permanece. Esta revisão é documental, sem alteração de código, bases, acessos ou configuração.
|
||||
|
||||
### 11.1. Fontes efectivamente reutilizadas
|
||||
|
||||
Consulta limitada ao arquivo documental do InvesteMoz em `docs/investmoz/simulations/source-archive`, em modo de leitura. Nenhuma base, configuração privada, código ou teste do portal foi consultado/executado. Reutilizados a matriz de cálculo do SGF e o cotejo anterior de alterações, sem repetir investigação de taxa/base ou os ensaios aceites.
|
||||
|
||||
| Referência | Exemplar e disposição conferida nesta revisão | Identidade / limite |
|
||||
| --- | --- | --- |
|
||||
| CIVA republicado pela Lei 13/2016 | `Lei-13-2016-CIVA-BR-156-10-suplemento.pdf`, páginas PDF 17–18, BR 1426-(275)–(276), art. 27; página PDF 21, BR 1426-(279), arts. 50/51. Leitura visual do exemplar digitalizado | SHA-256 `B90DC7C14ECEA2E378C4A62E8E5A47D54A5644C457BAEB8B8053B92FD2A5710B`. Base histórica, lida com alterações posteriores; não é, isoladamente, texto consolidado de 2026 |
|
||||
| RIVA, Decreto 7/2008 | `BR-16-I-Serie-2008-04-16.pdf`, página PDF 4, arts. 21 e 24(2) | SHA-256 `FC373FF5637EDF75EC6A9595DEC8763A8503D4EE786E3B7D8F1C742EAE9D80EE`. Art. 21 sujeito à verificação das alterações posteriores |
|
||||
| Rectificação de 2017 | `BR-89-I-Serie-2017-06-08.pdf`, aviso da Assembleia da República | Corrige art. 6, art. 14 e anexos; não fornece procedimento de autorização do SGF nem de correcção de facturas |
|
||||
| Lei 10/2025 | `BR-248-I-Suplemento-1-2025.pdf`, página PDF 14, art. 27(10); página 15, entrada em vigor em 01/01/2026, já cotejada | SHA-256 `CCF2A8DECEA820F2DD076B4B2141B1EFE3F6A806568C3A587CA59A8E92F4C251`. Na alteração do art. 27, os n.os 1–9 aparecem mantidos por remissão; o n.º 10 tem nova redacção |
|
||||
| Informação oficial actual | [AT — comunicados](https://www.at.gov.mz/informacoes/comunicado-de-imprensa) e [Governo — alterações ao RIVA, notícia de 30/09/2026](https://portaldogoverno.gov.mz/governo-introduz-alteracoes-nos-regulamentos-fiscais-para-reforcar-eficiencia-tributaria/) | Consulta em 27/10/2026. Metadados de lista e anúncio não substituem anexo, despacho de autorização ou diploma publicado |
|
||||
|
||||
As alterações já cotejadas da Lei 22/2022 e da Lei 3/2025 não fornecem novo procedimento para estes quatro pontos. O art. 51 não integra a lista de artigos alterados pela Lei 10/2025. Isto delimita o cotejo efectuado, sem afirmar consolidação exaustiva de todos os diplomas até hoje.
|
||||
|
||||
### 11.2. Matriz actualizada: demonstrado versus ainda por demonstrar
|
||||
|
||||
| Matéria | O que ficou fundamentado | O que continua a bloquear prontidão real |
|
||||
| --- | --- | --- |
|
||||
| **Programa de facturação** | CIVA art. 27(9): conteúdo processado electronicamente exige programa específico de facturação autorizado pela AT. O n.º 9 está preservado na alteração conferida de 2025. A autorização de tipografias do art. 27(7)/RIVA 21(4–5) é outra matéria | Procedimento oficial vigente para requerer/verificar essa autorização e prova específica de que o SGF, na versão/instalação/âmbito pretendidos, a satisfaz. Não existe nos materiais conferidos autorização do SGF. Aprovação local, PDF, hash e testes não a substituem |
|
||||
| **Série e numeração** | CIVA art. 27(5/7): documento datado e numerado sequencialmente, com distinção entre processamento electrónico e impressão tipográfica. RIVA 24(2): uma ou mais séries referenciadas; conservar duplicados em ordem e todos os exemplares anulados/inutilizados, identificando substitutos quando existam | Confirmar condições administrativas vigentes para a série nova e sua relação com autorização/comunicação. Código `SGF-FT-A` e primeiro número `1` continuam propostas, sem aprovação, reserva ou configuração. A base consultada não impõe por si um reinício anual nem prova que o código proposto está autorizado |
|
||||
| **Submissão à AT** | CIVA art. 27(10), redacção da Lei 10/2025, efectiva desde 01/01/2026: submissão das facturas/documentos equivalentes emitidos por operação, com execução remetida para regulamentação. Não confundir esta obrigação com declaração mensal ou autorização do programa | Texto executório aplicável ao caso: canal, formato, conteúdo, prazo, identificação da série/documento, comprovativo, rejeição e contingência. Determinar com fonte se a aceitação é anterior à emissão ou se a obrigação é posterior. Não se demonstrou um protocolo/API ou dispensa; também não se demonstrou que inexistam |
|
||||
| **Correcção e regularização** | CIVA art. 51(1–5) e RIVA 24(2) fornecem regras concretas, descritas abaixo. A exigência de preservar original e ligações tem suporte documental; pedido interno não altera imposto | Procedimento operacional fiscalmente validado, documento adequado a cada motivo, elementos/referências, prova do destinatário quando necessária e tratamento declarativo. O SGF apenas regista pedidos; não produz ainda a correcção fiscal. Antes de emitir, deve existir uma via executável conforme, interna ou externa identificada, sem a presumir |
|
||||
|
||||
**Limite da actualização regulamentar:** a notícia oficial enumera alterações aos arts. 3, 7, 8, 15, 16-A, 18, 21, 23, 28, 36 e 37 do RIVA. O articulado publicado, número do diploma e início de eficácia dessa alteração não foram recuperados nesta consulta. Não afirmar que não foram publicados. Em particular, não configurar o prazo histórico do art. 21 como se estivesse integralmente confirmado para 2026. A notícia contém referências que não substituem o BR; não resolver divergências de datas por suposição.
|
||||
|
||||
**Limite da lista de software:** o índice da AT identifica uma lista provisória de software de facturação, com referência nominal a 01/02/2026. A consulta da página e dos seus metadados públicos não disponibilizou anexo verificável nem certificado do SGF. Datas de listagem/publicação não devem ser tratadas como vigência de autorização. Não se adopta a afirmação comercial de que todos os certificados estariam pendentes, nem se conclui dispensa de comunicação ou de validação prévia a partir de páginas de fornecedores.
|
||||
|
||||
### 11.3. Procedimento de correcção: base já encontrada
|
||||
|
||||
Referências abaixo correspondem ao art. 51 do exemplar identificado, com os limites de actualização acima. Não se configuram prazos automaticamente nesta etapa.
|
||||
|
||||
- **Alteração posterior do valor tributável ou imposto:** n.º 1 remete novamente para as disposições dos arts. 27 e seguintes. Não autoriza editar a fotografia original.
|
||||
- **Anulação/redução após registo**, por invalidade, resolução, rescisão, redução contratual, devolução ou abatimentos/descontos: n.º 2 prevê dedução pelo fornecedor até ao fim do período de imposto seguinte àquele em que ocorreram as circunstâncias. Não confundir com simples erro de imposto na factura.
|
||||
- **Inexactidão na factura:** n.º 3 distingue imposto liquidado a menos — rectificação obrigatória, sem penalidade até ao fim do período de imposto seguinte ao da factura — de imposto a mais, cuja rectificação é facultativa no prazo de um ano. O prazo de um ano não se generaliza a todos os motivos de correcção.
|
||||
- **Destinatário sujeito passivo:** n.º 4 prevê correcção da dedução nas condições e prazo aí definidos, após recepção do documento rectificativo; o processo deve identificar se esse ramo é aplicável.
|
||||
- **Redução a favor do fornecedor:** n.º 5 exige prova de que o adquirente tomou conhecimento da rectificação ou de que foi reembolsado; sem ela a dedução é indevida. Guardar documento e evidência ligados ao original, com datas e autor. Não presumir que um clique interno do emitente prova conhecimento do cliente.
|
||||
- **Arquivo:** RIVA 24(2) impede tratar documento anulado/inutilizado como registo a apagar; CIVA art. 50 prevê conservação dos livros, registos e documentação de suporte durante os dez anos civis subsequentes. Conservação técnica e procedimento fiscal devem ser compatíveis, sem renumerar ou reescrever originais.
|
||||
|
||||
Os n.os 6–7 tratam erros materiais/de cálculo em registos e declarações, com condições próprias. Não são um atalho para corrigir uma factura emitida por edição directa ou para produzir lançamentos neste incremento. As regras de devolução de mercadorias do art. 27(3/6) também não justificam automaticamente um documento de correcção de alojamento/capacidade.
|
||||
|
||||
**Circuito operacional a fechar, sob as responsabilidades já aprovadas:** Osmane identifica original/motivo/montantes e pede a correcção; Samira valida o ramo fiscal, fundamento, documento, prazo e evidências; a execução conserva original, identidade da rectificação e vínculo, sem duplicar operação. Se depender de outro sistema autorizado, identificar qual, como evitar duplicação/numeração concorrente e como conservar o comprovativo. Não foi escolhido fornecedor nem autorizada integração. Falta validar esta via concreta; não falta voltar a escolher os responsáveis.
|
||||
|
||||
### 11.4. Lista reduzida de provas e próximo passo
|
||||
|
||||
1. **Regulamentação e autorização:** obter o diploma publicado das alterações anunciadas ao RIVA e instrução/despacho oficial aplicável à autorização de programas; depois, evidência específica de autorização do SGF e respectivos limites. Um modelo de factura e memória técnica poderão integrar um processo, mas não são aqui declarados requisitos vigentes sem fonte oficial.
|
||||
2. **Série/comunicação:** obter a disposição ou orientação formal que determine condições da série e execução do art. 27(10), incluindo eventual transição/contingência. Só então apresentar a configuração exacta da série nova para aprovação; não pedir novamente a decisão de criar série nova.
|
||||
3. **Correcção executável:** Samira valida a aplicação dos ramos acima ao serviço e a via concreta de emissão/entrega/regularização, com evidências e prazos. Não basta aprovar um pedido sem efeito monetário.
|
||||
|
||||
São provas normativas/operacionais e autorização externa específica, não escolhas a resolver com novas taxas, ensaios aritméticos ou preferências visuais. Se os textos/actos não estiverem disponíveis nos materiais de trabalho, solicitar à AT/DAF competente a referência oficial e resposta documentada sobre estes três pontos. **Nenhum contacto foi enviado.** Não há fundamento para desbloquear emissão enquanto estas provas faltarem.
|
||||
|
||||
Próximo incremento apenas após estas provas: confrontar requisitos concretos com o percurso técnico aceite e propor somente o delta necessário. Até lá, preservar navegador/PDF de teste, cálculo condicionado, B1, aprovações contabilísticas e guarda de emissão real. Não foi executado novo teste, migração, concessão, série, documento, recebimento, lançamento, publicação ou checkpoint nesta revisão documental.
|
||||
@@ -0,0 +1,126 @@
|
||||
# Emissão documental técnica — demonstração isolada
|
||||
|
||||
26/10/2026, Africa/Johannesburg. Implementação do âmbito autorizado, preservando `9f48004` e as alterações posteriores. **Não é habilitação para emissão real nem aceitação automática da entrega.**
|
||||
|
||||
## Funcional e provado
|
||||
|
||||
- Séries sintéticas novas com proposta, versão anterior explícita e validação por identidade distinta. Série encerrada/futura/desactualizada não substitui silenciosamente configuração vigente; o contador não pode ser reiniciado por uma nova versão. Só códigos `TEST-...` são aceites neste incremento.
|
||||
- Regra temporal prospectiva separada do perfil de cálculo, ligada à versão do rascunho/preparação e à cobertura. Proponente prepara; validador fiscal aprova/recusa. O modo suportado na prova é emissão dentro de uma janela explicitamente fundamentada. A data efectiva nasce na confirmação, com UTC/zona/data civil separados; revisão de outro dia é recusada.
|
||||
- Revisão de prontidão sem número. Confirmação com sessão/CSRF, token de contexto, permissões próprias, hash da revisão e idempotência. Verifica dados do emitente/cliente, período, unidade de medida, cálculo actual e perfil vigente na data do acontecimento. São condições técnicas do cenário de teste, não declaração de catálogo legal universal.
|
||||
- Contador, identidade, fotografia, PDF preservado, auditoria, evento e outbox numa transacção. Unicidade por empresa/série/número e por rascunho/prestação no recorte. Repetição após resposta perdida devolve o documento existente; nova chave não cria segunda factura do mesmo rascunho.
|
||||
- Consulta do navegador e PDF partilham a mesma lista documental produzida da fotografia; essa lista também é fixada no snapshot para não depender de alterações futuras do renderizador. Mudança posterior de cadastros não altera o documento. O PDF é guardado com SHA-256 e devolvido pelos mesmos bytes; não se regenera do cadastro actual. Hash não é certificação ou assinatura fiscal.
|
||||
- Pedido de correcção com motivo e autor, ligado ao original, sem mudar o documento e sem efeito monetário/fiscal. Sem nota de crédito/débito, anulação fiscal ou reabertura.
|
||||
- Aviso **TESTE — SEM VALIDADE FISCAL** no navegador e no cabeçalho/rodapé de cada página PDF. A data de exigibilidade e o período da demonstração são explicitamente simulados; não alteram as pendências do caso real já aceite.
|
||||
|
||||
## Bloqueio real e preservação
|
||||
|
||||
`ServiceInvoicing::guard()` recusa todas as mutações e a via de documento/PDF fora de `testing`/`browser-testing`; dentro destes ambientes executa também `TestingDatabaseGuard`. Não existe flag para habilitar emissão real. A consulta normal apresenta o bloqueio e não depende das novas tabelas já existirem. Alterar a variável de ambiente sem trocar para o destino de testes seguro não ultrapassa a guarda.
|
||||
|
||||
Nenhuma migração, série, concessão, prestação, factura ou demonstração foi criada na base normal por esta entrega. O caso real e o cálculo condicionado permanecem como estavam; B1 e aprovações existentes preservados. Não se alterou o InvesteMoz, não houve comunicação à AT, publicação, recebimento ou lançamento. Nenhum novo checkpoint criado sem pedido.
|
||||
|
||||
## PDF: opção técnica e limites
|
||||
|
||||
`InvoicePdf` é um renderizador interno pequeno para este documento textual, sem bibliotecas/ferramentas ou versões novas. A versão final é `sgf-test-invoice-text-v2`. Suporta texto WinAnsi/Windows-1252, incluindo os caracteres portugueses usados no cenário; caracteres não representáveis causam recusa explícita na prontidão, sem substituição silenciosa. Não é um motor geral de HTML/PDF: não inclui logótipo/imagens, assinatura, QR ou anexos. A consulta emitida também usa o formato documental textual, sem procurar esses recursos no cadastro actual.
|
||||
|
||||
O PDF sintético final tem uma página. Caso de esforço com texto extenso e palavras longas produziu quatro páginas, com cabeçalho/rodapé e margens protegidos. O PDF foi extraído e renderizado para conferência; o hash da descarga final no navegador coincide com o artefacto preservado. Documentos anteriores da prova continuam com os bytes e versão originais do renderizador.
|
||||
|
||||
Artefacto de demonstração: `output/pdf/sgf-tempo-factura-teste.pdf`; contém apenas identidades e pressupostos sintéticos. [Prova agregada do PDF](proofs/invoice-pdf-results.json).
|
||||
|
||||
## Verificações
|
||||
|
||||
**53 testes, 924 asserções**, todos passados, exclusivamente em `sgf_tempo_test`, com filtro `ServiceInvoiceTest|ServiceFiscalTest|ServiceCalculationTest|DocumentPreviewTest|InternalConfirmationTest|DatabaseSafetyTest`. Compilação Vite 8.3.5 passou; versões de ferramentas/dependências mantidas.
|
||||
|
||||
Cobertura: revisão sem consumo de número; dados incompletos e caracteres não suportados; falta de regra prospectiva compatível; edição indevida de campos protegidos; versão/revisão/data antigas; série encerrada; separação de funções e revogação; isolamento; B1 recusado como origem de emissão directa; imutabilidade por operações em massa; repetição da emissão/PDF; pedido de correcção sem efeito; falha injectada no outbox com rollback de contador/documento/evento/auditoria/comando; retry usando o primeiro número válido.
|
||||
|
||||
Dois processos PHP realmente sobrepostos provaram uma inserção e um replay com o mesmo ID, mantendo documentos anteriores e numeração distinta na série partilhada. [Prova de concorrência](proofs/invoice-concurrency.json). O teste não afirma ser prova de RLS ou de conformidade fiscal.
|
||||
|
||||
Navegador Edge: login real sintético, CSRF activo, sessão/cache isolados em `http://127.0.0.1:8001`, apenas `sgf_tempo_test`. Não foi usado `actingAs` como demonstração de login.
|
||||
|
||||
1. Entrar com o gestor sintético; seleccionar **Empresa Horizonte — Demonstração → Unidade Central — Demonstração → Facturas de teste**.
|
||||
2. Consultar série **TEST-SERIE-ISOLADA v1**, número inicial 1, e regra **TEST-ISSUE-RULE v1**, aprovadas por validador distinto. IDs do rascunho aparecem na regra; não dependem de um ID fixo entre repetições.
|
||||
3. Seleccionar rascunho/série/regra → **Rever prontidão**. A revisão mostra 7850, IVA proposto 1256.00, total 9106.00 MZN e que o instante efectivo só será fixado ao confirmar.
|
||||
4. **Confirmar emissão apenas de teste**: atribuição única do número 1, consulta da fotografia e descarga PDF autenticada.
|
||||
5. Scripts concorrentes acrescentaram o documento 2; a revisão de paginação gerou o documento 3 no mesmo cenário, preservando os anteriores. Consultado o documento final e descarregado o respectivo PDF; hash igual ao artefacto entregue. [Imagem do navegador](proofs/invoice-browser.png).
|
||||
6. Instância de prova encerrada antes da execução final dos testes; a aplicação normal não mudou de ligação. Os testes finais recriaram apenas a base de testes; os artefactos sintéticos de prova permanecem.
|
||||
|
||||
Repetição técnica:
|
||||
|
||||
```powershell
|
||||
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/sgf.ps1 test --stop-on-failure '--filter=ServiceInvoiceTest|ServiceFiscalTest|ServiceCalculationTest|DocumentPreviewTest|InternalConfirmationTest|DatabaseSafetyTest'
|
||||
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/sgf.ps1 npm run build
|
||||
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/browser-proof.ps1 start
|
||||
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/sgf.ps1 php scripts/invoice-fixture.php --env=testing
|
||||
```
|
||||
|
||||
Após o percurso no navegador: `sgf.ps1 php scripts/invoice-concurrency.php --env=testing` e, para o PDF de demonstração, `sgf.ps1 php scripts/invoice-export-proof.php --env=testing`. Parar com `scripts/browser-proof.ps1 stop`. O preparador recusa fixture preenchida; não apaga dados para prosseguir. Credenciais aleatórias ficam apenas no armazenamento local protegido, nunca neste relatório.
|
||||
|
||||
## Delta para eventual aplicação em desenvolvimento — pendente
|
||||
|
||||
Migração `2026_10_26_060000_create_test_invoice_issuance.php`, confirmada **Pending** por leitura de `migrate:status` na base normal. Cria oito tabelas:
|
||||
|
||||
- `si_proposals`, `si_decisions`: configuração/regra e decisões imutáveis.
|
||||
- `si_counters`: contador protegido por empresa/série, âmbito imutável, incremento unitário, sem apagamento.
|
||||
- `si_invoices`: identidade, fotografia, PDF e hash; unicidades por origem e numeração, chaves e trigger de âmbito/configuração/regra.
|
||||
- `si_events`, `si_outbox`: captura durável sem processamento financeiro/contabilístico.
|
||||
- `si_commands`: recuperação/idempotência por empresa/chave/autor/unidade.
|
||||
- `si_correction_requests`: pedidos pendentes sem efeito fiscal.
|
||||
|
||||
Amplia o CHECK de `permission_grants`, preservando as alternativas anteriores; não atribui direitos. Tabelas de história/documentos são append-only. Sem modificação de B1/catálogos/cálculos, sem reset/fresh ou rollback destrutivo automático. Qualquer aplicação em `sgf_tempo_dev` exige confirmação específica deste delta; não foi executada. A migração sozinha não habilita emissão real.
|
||||
|
||||
## Proposta separada de série real — não configurada
|
||||
|
||||
Decisão encerrada: **série nova**, sem continuidade da série anterior. Para discussão concreta, propõe-se **código `SGF-FT-A`, primeiro número `1`**, limitado inicialmente à empresa/unidade autorizadas. São valores técnicos propostos, não regra legal, número reservado ou configuração aplicada. Não há reinício anual implícito. Antes de aplicar: confirmação específica, ausência de sobreposição, suporte de autorização/numeração e vigência efectiva. O código real não é aceite pela actual via de teste, que só admite `TEST-...`.
|
||||
|
||||
Osmane prepara a proposta e pede correcções; Samira valida a configuração e o tratamento fiscal. A escolha dessas responsabilidades não atribui automaticamente permissões nem autoriza configurar a série real enquanto faltarem as condições.
|
||||
|
||||
## Proposta separada de concessões — nenhuma aplicada
|
||||
|
||||
Para as contas existentes já identificadas no âmbito aprovado (conferência final antes de aplicar):
|
||||
|
||||
| Conta/função acordada | Novos direitos propostos | Âmbito |
|
||||
| --- | --- | --- |
|
||||
| Osmane, conta #1 | `invoice_series.view`, `invoice_series.propose` | Empresa #1; actuação apenas nas unidades já autorizadas |
|
||||
| Osmane, conta #1 | `service_invoices.view`, `service_invoices.issue`, `service_invoices.correction_request` | Exclusivamente unidade SEGI #1 da empresa #1 |
|
||||
| Samira, conta #2 | `invoice_series.view`, `invoice_series.approve` | Empresa #1; validação apenas nas unidades já autorizadas |
|
||||
| Samira, conta #2 | `service_invoices.view` | Exclusivamente unidade SEGI #1 da empresa #1 |
|
||||
|
||||
São **oito concessões propostas**. A proposta/validação da regra temporal reutiliza os direitos `service_fiscal.propose/approve` existentes e o modelo de identidades distintas; não exige nova aprovação do perfil fiscal aceite. Nenhuma concessão de emissão por Samira, validação por Osmane, administração, comunicação externa, lançamento ou correcção fiscal automática. Matriz real requer confirmação específica antes de aplicação. A emissão normal permanece bloqueada mesmo com estes direitos.
|
||||
|
||||
## Condições antes de emissão real
|
||||
|
||||
Continuam as provas específicas da secção 9 de [âmbito de emissão](SERVICE_INVOICE_ISSUANCE_SCOPE.md): autorização/certificação/dispensa aplicável ao software; suporte de série/numeração e eventual comunicação; procedimento fiscal válido de correcção; prontidão documental e regra temporal concretas. A janela de emissão e os dados completos da fixture são pressupostos sintéticos, não resolução dessas lacunas do caso real.
|
||||
|
||||
A activação real de emissão exigirá novo âmbito explícito e alteração revista do bloqueio; não é uma configuração disponível neste incremento. A aceitação anterior do cálculo condicionado e este desenvolvimento técnico não a autorizam.
|
||||
|
||||
## Ficheiros principais
|
||||
|
||||
`ServiceInvoicing.php`, `InvoicePdf.php`, `Http/ServiceInvoiceController.php`, migração `060000`, captura interna transaccional em `DocumentPreview.php`, rotas protegidas, `ServiceInvoiceWorkspace.jsx`, navegação/CSS, `ServiceInvoiceTest.php`, `InvoiceFixture.php` e scripts `invoice-*`. Artefactos/provas contêm apenas dados sintéticos. Sem novo checkpoint ou publicação.
|
||||
|
||||
## Aceitação da entrega técnica
|
||||
|
||||
**27/10/2026, Africa/Johannesburg.** Após informar que já tinha verificado a demonstração, o utilizador confirmou **«Aceitar a entrega técnica e criar checkpoint local»**. Fica aceite e encerrada a entrega técnica de navegador + PDF no âmbito isolado demonstrado, com os limites acima. As referências anteriores a aceitação/checkpoint ainda pendentes são históricas.
|
||||
|
||||
Autorizado registo e checkpoint Git exclusivamente local, sem credenciais ou dados reais. Incluídos código, testes, migração ainda não aplicada em desenvolvimento, especificação, relatório e provas sintéticas/agregadas; o PDF de demonstração contém só identidades sintéticas. Excluídos ficheiros de ambiente privados, manifestos, bases, logs, imagens reais e ficha nominativa local. Não se repetiram testes ou validações para este registo; resultados mantidos: 53 testes / 924 asserções e compilação aprovada.
|
||||
|
||||
A aceitação **não aplica a migração `060000`, as oito concessões ou a série real**, não resolve as provas de conformidade nem as pendências temporais do caso real, e não autoriza habilitar emissão real, recebimentos, lançamentos ou publicação. O bloqueio no servidor permanece. As próximas operações continuam sujeitas às confirmações específicas já delimitadas.
|
||||
|
||||
## Aplicação da migração e das concessões especificamente autorizada
|
||||
|
||||
**27/10/2026, Africa/Johannesburg.** Posteriormente à aceitação, o utilizador autorizou expressamente: aplicar a migração e as oito concessões exactamente propostas, verificar preservação e manter emissão real bloqueada, sem criar/configurar série real, emitir ou publicar. Esta secção substitui o estado pendente das secções históricas acima apenas quanto à migração/concessões.
|
||||
|
||||
1. Confirmados directório SGF, contas existentes #1/#2, empresa #1 e unidade #1; nenhuma conta ou pertença criada. Leitura de `migrate:status` confirmou só a migração `060000` pendente.
|
||||
2. Antes da aplicação, `scripts/invoice-dev-preservation.php --before` recolheu contagens e impressões digitais de **31 tabelas preexistentes**, incluindo `sf_*`, B1, cálculos, catálogo, identidades, acessos e auditoria. Só os agregados/hashes ficaram em armazenamento local ignorado; nenhum conteúdo de registo foi apresentado.
|
||||
3. `scripts/sgf.ps1 migrate` aplicou exclusivamente `2026_10_26_060000_create_test_invoice_issuance.php` na base **`sgf_tempo_dev`**, com proprietário separado. A verificação imediatamente posterior confirmou dados/acessos intactos e oito tabelas novas vazias. [Prova da migração](proofs/invoice-dev-preservation.json).
|
||||
4. `scripts/invoice-access.php 1 2 1 1 --apply` aplicou exactamente **oito concessões**, sem novos direitos fora da matriz aprovada. Auditoria: oito entradas `service_invoice.initial_grant`.
|
||||
5. `scripts/invoice-dev-preservation.php --after-grants` confirmou a matriz exacta e a preservação dos registos, acessos e auditoria anteriores; o único delta de acessos são as oito concessões autorizadas. [Prova após concessões](proofs/invoice-dev-preservation-grants.json).
|
||||
6. O ficheiro que contém a guarda de emissão ficou com hash inalterado. Verificadas recusa **403** nas entradas `guard`, `issue` e `propose` no ambiente normal, antes de qualquer operação documental. A consulta normal com os novos direitos confirma `real_blocked=true`, `test_enabled=false`, listas vazias.
|
||||
|
||||
**Estado final:** `si_proposals`, `si_decisions`, `si_counters`, `si_invoices`, `si_events`, `si_outbox`, `si_commands` e `si_correction_requests` com zero registos. Sem série real, contador, reserva de número, documento ou pedido de correcção criado. A instalação e concessões não habilitam emissão, configuração real ou comunicação externa. O perfil/cálculo condicionado anterior e as suas pendências temporais permanecem preservados.
|
||||
|
||||
Não foram repetidos testes destrutivos aceites para aplicar esta migração já testada. Não houve alteração de código funcional, ferramentas, publicação ou novo checkpoint. Os dois scripts administrativos novos documentam/reproduzem a verificação; repetir aplicação de concessões exige respeitar o âmbito confirmado, sem ampliar a matriz.
|
||||
|
||||
Para consultar o bloqueio: actualizar a página ou voltar a entrar, seleccionar empresa/unidade autorizadas e **Facturas de teste**. O ecrã normal deve apresentar **Emissão real indisponível**, mesmo para a conta com o novo direito de emissão. As provas de conformidade e a configuração da série real continuam separadas e por resolver/aplicar.
|
||||
|
||||
### Actualização documental de conformidade — 27/10/2026
|
||||
|
||||
O cotejo dirigido e a lista reduzida de provas estão na [secção 11 do âmbito de emissão](SERVICE_INVOICE_ISSUANCE_SCOPE.md#11-conformidade--cotejo-dirigido-de-27102026). Foram conferidos nos exemplares já arquivados o requisito de programa autorizado pela AT (CIVA 27(9)), a numeração/séries e conservação (CIVA 27; RIVA 24(2)), a obrigação de submissão remetida para regulamentação (Lei 10/2025, CIVA 27(10)) e os ramos de rectificação (CIVA 51). Isto reduz lacunas de fundamento; não fornece autorização do SGF, o protocolo executório vigente ou uma via concreta validada de correcção. A emissão real continua bloqueada e nenhuma série foi configurada. Sem nova alteração funcional, base, concessão ou repetição dos testes aceites.
|
||||
@@ -0,0 +1,23 @@
|
||||
# Aceitação — SGF-RECEIVABLES-SIM-v1
|
||||
|
||||
Em 27/10/2026 (Africa/Johannesburg), o utilizador pediu o encerramento da entrega de recebimentos sintéticos, com registo de aceitação e checkpoint local, excluindo credenciais e dados reais, mantendo a migração `070000` e as concessões por aplicar.
|
||||
|
||||
## Âmbito aceite
|
||||
|
||||
A entrega descrita em [SERVICE_RECEIVABLES_DELIVERY.md](SERVICE_RECEIVABLES_DELIVERY.md), exclusivamente sintética e isolada em `sgf_tempo_test`: obrigação de 1 000,00 MZN, recebimentos de 400,00 e 600,00, afectações explícitas, saldo final zero e duas reconciliações simuladas, com funções separadas, idempotência, histórico e eventos duráveis. Liquidação e reconciliação permanecem conceitos distintos.
|
||||
|
||||
Reutilizam-se as provas já preservadas no relatório: login real no navegador isolado, testes e concorrência. Não se atribui ao utilizador uma nova sessão de demonstração nesta data. A última regressão relevante de oficinas/recebimentos passou com 41 testes e 832 asserções; a ocorrência intermitente anterior na preparação de uma factura sintética permanece documentada em [WORKSHOP_RESOURCE_DELIVERY.md](WORKSHOP_RESOURCE_DELIVERY.md). Não se repetiram testes por este encerramento documental.
|
||||
|
||||
## Limites
|
||||
|
||||
- `2026_10_27_070000_create_simulated_receivables` continua por aplicar em desenvolvimento; as oito concessões propostas continuam sem aplicação.
|
||||
- Nenhum recebimento real, recibo fiscal, ligação bancária, movimentação de dinheiro, lançamento, fecho ou publicação é autorizado.
|
||||
- Guardas de ambiente/base e bloqueios de emissão/configuração reais preservados. Aceitar o ensaio não autoriza utilização operacional.
|
||||
- Oficinas mantém a aceitação própria e a instalação técnica posterior da `080000` e quatro direitos de abertura. Técnico e verificador reais continuam sem concessões e por identificar. Não se reabre a aprovação de oficinas.
|
||||
- Custos industriais continuam apenas em especificação.
|
||||
|
||||
## Checkpoint
|
||||
|
||||
O commit que contém este registo preserva a aceitação e as alterações posteriores ao checkpoint `21a91f2`, incluindo a documentação/procedimento da instalação técnica já autorizada de oficinas. Não executa novamente esse procedimento. O hash do novo checkpoint é comunicado na entrega, sem o inserir no próprio conteúdo que identifica.
|
||||
|
||||
Credenciais, ambientes, dados reais e relatórios locais de preservação permanecem excluídos. Os campos de aceitação nas provas JSON anteriores descrevem o estado no momento da demonstração; este registo documenta a aceitação posterior sem reescrever essas provas históricas.
|
||||
@@ -0,0 +1,131 @@
|
||||
# SGF-RECEIVABLES-SIM-v1 — entrega técnica isolada
|
||||
|
||||
27/10/2026, Africa/Johannesburg. Implementação do âmbito aprovado na secção 12 de [SERVICE_RECEIVABLES_SCOPE.md](SERVICE_RECEIVABLES_SCOPE.md). **Pronto para revisão do utilizador; não constitui aceitação.** Preservados `4276aca` e alterações posteriores. Sem novo checkpoint ou publicação.
|
||||
|
||||
## Funcional
|
||||
|
||||
- Obrigação explícita sobre ID exacto de documento sintético `si_invoices`, com fotografia e moeda preservadas; documento existente não cria dívida automaticamente. Rascunho/B1 não são origens aceites.
|
||||
- Propostas imutáveis de obrigação, recebimento, observação e correcção. Cada decisão exige versão exacta e revisão actual da obrigação; confirmação/aprovação por identidade distinta do proponente. Propostas não são editadas: mudança exige nova proposta/revisão, conservando a anterior. Versões não suportadas são recusadas.
|
||||
- Recebimento confirmado não afecta automaticamente o documento nem comprova reconciliação. Afectação exige comando próprio, saldo disponível e saldo do documento suficientes, na mesma empresa/unidade/cliente/moeda.
|
||||
- Montantes exactos MZN, sem float ou truncagem: quantias precisam de ser exactamente representáveis a duas casas e respeitar o limite técnico. A base de dados recusa fracções adicionais antes de qualquer arredondamento de coluna. O motor fiscal existente não foi alterado.
|
||||
- Excesso integral preservado por afectar. Sobreafectação recusada por inteiro; sem crédito, receita, reembolso ou adiantamento automático.
|
||||
- Saldo, recebido, afectado e disponível derivados do histórico. Vencimento desconhecido não produz atraso; vencido apenas no dia posterior ao vencimento conhecido. Liquidação e reconciliação são dimensões distintas.
|
||||
- Reconciliação 1:1 exclusivamente simulada, exacta, com observações independentes e identidades explícitas. Divergência permanece registada, sem tolerância; observação não cria recebimento. Reutilização indevida de observação/recebimento conferidos é recusada.
|
||||
- Reversões integrais por proposta e aprovação; original preservado. Reverter recebimento exige antes libertar afectações e conferência activas, por operações explícitas. Redução sintética identifica documento `TEST-REDUCTION-...`, linha 1 e original. Redução acima do saldo é recusada; não modifica factura ou pedido fiscal de correcção.
|
||||
- Comprovativo interno apenas no navegador, com origem, data de corte, revisão, valores e efeitos. Avisos permanentes **TESTE — SEM VALIDADE FISCAL** e **SIMULAÇÃO — SEM MOVIMENTAÇÃO DE DINHEIRO**. Não cria recibo fiscal nem novo PDF de recebimento.
|
||||
|
||||
## Protecção e persistência
|
||||
|
||||
`ServiceReceivables::guard()` recusa execução fora de `testing`/`browser-testing` e executa `TestingDatabaseGuard`: destino efectivo `sgf_tempo_test`, cluster 127.0.0.1:55432, utilizador de testes próprio. A consulta normal devolve bloqueio e listas vazias sem depender das novas tabelas. Não existe flag de activação real.
|
||||
|
||||
Todos os INSERT nas seis tabelas novas têm também trigger que recusa uma base diferente de `sgf_tempo_test` ou porta diferente de 55432. Relações de documento, cliente, unidade e moeda são validadas na base; UPDATE/DELETE em massa recusados nos registos de história. Guardas de agregado e revisão serializam escritores por empresa, incluindo INSERT directo em SQL. Não se declara RLS ou autenticação de utilizador final por SQL: a autorização por sessão/contexto/direitos é revalidada no servidor, e a ligação administrativa continua uma fronteira distinta.
|
||||
|
||||
Comando, efeito, auditoria, evento e outbox ficam na mesma transacção. Chave por empresa/unidade/actor/acção, hash canónico e unicidades de acontecimento protegem repetições e nova chave sobre a mesma origem. Replay exige direito actual; não reaplica uma afectação entretanto revertida. Consumidor interno `simulation_integrity_v1` marca entrega idempotente em tabela separada e verifica integridade; não contabiliza nem comunica com bancos.
|
||||
|
||||
A consulta bloqueia brevemente a linha da empresa para compor uma vista coerente. Todos os escritores usam a mesma ordem de bloqueio. É uma escolha limitada ao incremento local, com serialização ampla; não é promessa de escala para produção. Formulário antigo recebe conflito, exige actualização explícita e não grava sobre a revisão nova.
|
||||
|
||||
## Provas e resultados
|
||||
|
||||
Ver [resultado do navegador](proofs/receivables-browser-results.json), [imagem](proofs/receivables-browser.png), [concorrência](proofs/receivables-concurrency.json) e [resultado agregado dos testes](proofs/receivables-tests.json).
|
||||
|
||||
Prova principal efectuada com login real no Edge, sessão/cache isolados, CSRF activo, `http://127.0.0.1:8001` e exclusivamente `sgf_tempo_test`. Não se usou `actingAs` para demonstrar entrada. As duas identidades sintéticas têm as funções equivalentes à matriz aprovada, sem poderes derivados dos nomes.
|
||||
|
||||
| Momento observado no navegador | Recebido | Afectado | Por afectar | Saldo do documento |
|
||||
| --- | ---: | ---: | ---: | ---: |
|
||||
| Obrigação confirmada | 0,00 | 0,00 | 0,00 | 1 000,00 |
|
||||
| Dois recebimentos confirmados, antes das afectações | 1 000,00 | 0,00 | 1 000,00 | 1 000,00 |
|
||||
| Afectação de 400 | 1 000,00 | 400,00 | 600,00 | 600,00 |
|
||||
| Afectação adicional de 600, antes da conferência | 1 000,00 | 1 000,00 | 0,00 | 0,00 |
|
||||
| Duas observações conferidas em simulação | 1 000,00 | 1 000,00 | 0,00 | 0,00 |
|
||||
|
||||
O documento sintético de 1 000,00 foi produzido pelo percurso de emissão já aceite, parametrizando apenas a fixture: preço sem imposto 862,07 + IVA de ensaio documental 137,93 = 1 000,00. Não foi atribuída taxa zero nem alterado o motor fiscal. Isso prepara a origem do ensaio; não valida tributação real.
|
||||
|
||||
Os testes abrangem ainda: 400+500 após redução sintética de 100; excesso de 100 por afectar; divergência de 0,01; reversões dependentes e repetidas; redução depois de liquidação; observação repetida/reutilizada; escala/limites, datas/vencimento, evidência ausente, origem e IDs manipulados, separação de autores, consulta sem alteração, revogação, contexto antigo, empresa irmã, unidade não autorizada e SQL em massa. Falhas injectadas no outbox desfazem também o efeito financeiro; resposta perdida recupera o mesmo resultado. Falha e repetição da entrega interna não duplicam efeitos.
|
||||
|
||||
Seis cenários com dois processos realmente sobrepostos: mesma confirmação produz um efeito e um replay; 400+700 disputando saldo de 1 000; duas afectações disputando o disponível de um recebimento; escritores SQL concorrentes; reversão versus conferência; duas reduções sobre a mesma revisão. Conflitos não repartem valores silenciosamente e não produzem saldo negativo. A prova SQL insere deliberadamente efeitos sintéticos directamente, apenas para verificar as guardas; não representa um comando autorizado de aplicação ou fluxo com auditoria completo.
|
||||
|
||||
Resultado final: **39 testes, 711 asserções, zero falhas/erros**; compilação **Vite 8.3.5 aprovada**, sem alteração de dependências. Filtro relevante: `ServiceReceivablesTest|ServiceInvoiceTest|InternalConfirmationTest|DatabaseSafetyTest`. A instância do navegador foi parada antes da regressão final; essa regressão recria apenas a base de testes. As imagens/resultados permanecem; os IDs da demonstração não são garantidos numa repetição. A revisão final reforçou a resolução do cliente pela versão imutável em `a_history` e fixou hash/referência de origem nos novos registos; não depende do rascunho actual. Proposta recusada permanece sem obrigação aberta e sem efeito de atraso.
|
||||
|
||||
## Percurso exacto para repetir no navegador
|
||||
|
||||
Com autorização de demonstração sintética, preparar a base de testes pelo comando de testes abaixo e garantir que não existe outra prova activa. Os preparadores recusam fixtures preenchidas: não apagam dados para conseguir continuar. Se a porta 8001 estiver ocupada, parar e identificar; nunca terminar processos de outro projecto.
|
||||
|
||||
```powershell
|
||||
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/sgf.ps1 test '--filter=ServiceReceivablesTest|ServiceInvoiceTest|InternalConfirmationTest|DatabaseSafetyTest'
|
||||
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/sgf.ps1 npm run build
|
||||
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/browser-proof.ps1 start
|
||||
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/sgf.ps1 php scripts/receivables-fixture.php --env=testing
|
||||
```
|
||||
|
||||
Credenciais aleatórias apenas no ficheiro local protegido já usado pelo preparador, nunca no relatório/chat. Não usar contas reais na instância de prova.
|
||||
|
||||
1. Entrar como gestor sintético, seleccionar **Empresa Horizonte — Demonstração → Unidade Central — Demonstração → Recebimentos simulados**.
|
||||
2. Escolher documento exacto `TEST-SERIE-ISOLADA/1`, montante 1 000,00; **Propor obrigação**, com vencimento vazio para provar a pendência.
|
||||
3. Sair e entrar como validador sintético; seleccionar mesmo contexto; **Confirmar proposta** da obrigação. O proponente não pode confirmar a sua proposta.
|
||||
4. Voltar ao gestor e propor recebimentos **400.00** e **600.00**, cada um com data declarada não futura, ID de acontecimento diferente e evidência explicitamente artificial. Voltar ao validador e confirmar cada proposta. O saldo continua 1 000 até haver afectação.
|
||||
5. Voltar ao gestor e **Afectar explicitamente** 400 e 600 nos respectivos recebimentos. Conferir saldo zero, disponível zero e ambos ainda sem reconciliação simulada.
|
||||
6. Preparar duas observações artificiais, escolhendo o recebimento exacto em cada uma, valores 400/600, datas, IDs de observação distintos e evidências de fonte simulada.
|
||||
7. Voltar ao validador e **Conferir correspondência exacta** em cada observação. Abrir **Consultar comprovativo interno** e verificar referência documental, montantes, revisão, autores e avisos. Nenhuma descarga de recibo/PDF novo.
|
||||
8. Para os cenários concorrentes independentes: `sgf.ps1 php scripts/receivables-concurrency.php --env=testing`; para verificar/guardar o agregado do caso principal e entregar eventos internamente: `sgf.ps1 php scripts/receivables-proof.php --env=testing`. Não executar concorrência contra a obrigação principal.
|
||||
9. Terminar com `powershell -NoProfile -ExecutionPolicy Bypass -File scripts/browser-proof.ps1 stop` antes de voltar a executar testes destrutivos. A aplicação normal conserva a sua ligação.
|
||||
|
||||
## Delta aditivo — NÃO aplicado em desenvolvimento
|
||||
|
||||
Migração **`2026_10_27_070000_create_simulated_receivables.php`**, com SQL em `database/sql/receivables.sql`. `migrate:status` consultado em `sgf_tempo_dev` confirmou **Pending**. Foi aplicada/recriada apenas pela suite em `sgf_tempo_test`.
|
||||
|
||||
Cria seis tabelas:
|
||||
|
||||
| Tabela | Finalidade |
|
||||
| --- | --- |
|
||||
| `sr_records` | Propostas/documentos sintéticos e referências imutáveis de obrigação, recebimento, observação e correcção |
|
||||
| `sr_effects` | Decisões, afectações, reconciliações, reduções e compensações imutáveis |
|
||||
| `sr_commands` | Idempotência e resultado recuperável |
|
||||
| `sr_events` | Evento versionado por comando, com origem/correlação |
|
||||
| `sr_outbox` | Captura durável apenas de simulação |
|
||||
| `sr_deliveries` | Marca imutável de entrega do consumidor interno idempotente |
|
||||
|
||||
Acrescenta FKs, índices de unicidade, CHECKs, funções/triggers próprios para relações, precisão, saldos, revisões, separação de autores e imutabilidade. Amplia o CHECK de `permission_grants` com sete nomes de acção exclusivamente de unidade; **não atribui direitos** nem altera alternativas anteriores. Não modifica documentos/B1/cálculos/catálogos ou as tabelas `si_*`. `down()` recusa destruição de história; sem reset/fresh ou rollback destrutivo em desenvolvimento.
|
||||
|
||||
**Proposta pendente, a confirmar antes de executar:** aplicar exclusivamente este delta em `sgf_tempo_dev`, preservando dados/acessos, com comparação de integridade antes/depois. Não executado. Mesmo instalada em desenvolvimento, a guarda de aplicação e os triggers impedem INSERT operacional deste ensaio nessa base. Não é proposta de activação real.
|
||||
|
||||
## Oito concessões — proposta separada, NÃO aplicada
|
||||
|
||||
Contas/âmbito conferidos por leitura através de `scripts/receivables-grants-preview.php`, que não tem modo de aplicação. Tenant #1, **Tempo Lda, empresa #1 / SEGI, unidade #1**, sem extensão a outra unidade. Todos os oito direitos estavam ausentes nessa conferência.
|
||||
|
||||
| Conta existente | Novas permissões propostas, prefixo `service_receivables.` | Quantidade |
|
||||
| --- | --- | ---: |
|
||||
| #1 — Osmane Nala, nala@tempo.co.mz | `view`, `prepare`, `allocate`, `correction_request` | 4 |
|
||||
| #2 — Samira Nal, onala@me.com | `view`, `confirm`, `reconcile`, `correction_approve` | 4 |
|
||||
|
||||
Exigem confirmação específica antes da aplicação, separada da migração. Sem gestão destes acessos, herança, emissão, banco, reconhecimento ou fecho. Não foram aplicadas às contas reais; apenas equivalentes sintéticos receberam direitos na fixture de testes. Uma eventual concessão local não permite executar recebimentos reais nem contornar o bloqueio.
|
||||
|
||||
## Aceitação posterior — 27/10/2026
|
||||
|
||||
Entrega isolada encerrada por aceitação do utilizador, registada em [SERVICE_RECEIVABLES_ACCEPTANCE.md](SERVICE_RECEIVABLES_ACCEPTANCE.md), com checkpoint exclusivamente local. As referências anteriores a aceitação pendente descrevem o estado da entrega técnica antes deste encerramento. `070000` e as oito concessões permanecem por aplicar; os bloqueios operacionais e fiscais mantêm-se. Oficinas não exige nova aprovação e custos industriais não foram implementados.
|
||||
|
||||
## Instalação técnica especificamente autorizada — 27/10/2026
|
||||
|
||||
Após autorização expressa, foi aplicada **apenas** `2026_10_27_070000_create_simulated_receivables` em `sgf_tempo_dev`, por caminho explícito, com o proprietário separado `sgf_dev_owner`. Acrescentou-se exactamente essa entrada no registo de migrações. Não se reaplicou ou alterou a instalação de oficinas `080000`. As referências anteriores a migração/concessões pendentes descrevem o estado anterior a esta autorização.
|
||||
|
||||
Aplicadas exactamente oito concessões, todas tenant #1 / Tempo Lda #1 / SEGI #1:
|
||||
|
||||
| Conta existente | Direitos, prefixo `service_receivables.` |
|
||||
| --- | --- |
|
||||
| Osmane #1 | `view`, `prepare`, `allocate`, `correction_request` |
|
||||
| Samira #2 | `view`, `confirm`, `reconcile`, `correction_approve` |
|
||||
|
||||
Cada concessão tem evento de auditoria. Não se criaram contas, direitos de gestão ou concessões para técnico/verificador. Impressões comparadas apenas em memória confirmaram a preservação dos registos das **54 tabelas preexistentes**, incluindo acessos, auditoria e oficinas. Os únicos novos registos são uma entrada de migração, oito concessões e oito eventos de auditoria; as seis tabelas novas estão vazias.
|
||||
|
||||
Procedimento: `scripts/receivables-dev-install.php`, dirigido à operação exacta e deliberadamente recusado se já instalada ou se contas/âmbitos/estado diferirem. Resumo local em `storage/app/private/receivables-dev-install-proof.json`, excluído do Git, sem conteúdos dos registos ou credenciais. A aplicação continua ligada como `sgf_dev_app`, sem privilégios de proprietário/administração.
|
||||
|
||||
Conferências no ambiente normal: listagens de recebimentos de ambas as contas bloqueadas/vazias; guarda, proposta, decisão, afectação e consumidor de eventos recusados com 403; listagem/guarda de oficinas e guarda de emissão real igualmente bloqueadas. As funções SQL de ambiente de recebimentos e oficinas recusaram `sgf_tempo_dev`. Código funcional/guardas inalterados. Não se criaram operações reais ou demonstrações na base normal. Não se repetiram testes destrutivos, compilação ou demonstração aceite por uma instalação sem alteração funcional.
|
||||
|
||||
Checkpoint aceite `7628645` preservado. Esta instalação técnica não activa recebimentos reais, reconciliação bancária, emissão fiscal, lançamentos, fecho ou publicação, nem altera as aprovações existentes.
|
||||
|
||||
## Ficheiros e limites
|
||||
|
||||
Código novo: `app/Modules/Services/ServiceReceivables.php`, `Http/ServiceReceivablesController.php`, `resources/js/ServiceReceivablesWorkspace.jsx`; integração em `routes/web.php` e `resources/js/app.jsx`. Migração/SQL acima. Testes e fixtures: `tests/Feature/ServiceReceivablesTest.php`, `tests/Support/ReceivablesFixture.php`; `InvoiceFixture` ganhou parâmetro de preço com valor anterior preservado por omissão. Scripts: `receivables-fixture.php`, `receivables-worker.php`, `receivables-concurrency.php`, `receivables-proof.php`, `receivables-grants-preview.php`. Documentação e provas referidas neste relatório.
|
||||
|
||||
Sem dependências/ferramentas novas. Não se modificou o motor exacto, `ServiceInvoicing::guard()`, fotografias B1 ou aprovações existentes. Não se repetiu investigação fiscal do InvesteMoz nem se lhe acedeu neste incremento. Nenhum dado de demonstração entrou na base normal; migração e direitos novos permanecem pendentes. Não foi produzido recibo fiscal, PDF de recebimento, movimento de dinheiro, lançamento, fecho ou comunicação externa.
|
||||
|
||||
Limites deliberados: uma moeda MZN, uma linha e obrigação por documento, um documento por recebimento, conferência integral 1:1, reversões integrais, sem edição de propostas/efeitos confirmados, sem câmbio/adiantamentos/retenções/descontos/reembolso. Uma operação que precise de extensão é recusada; não se finge que cabe no caso simples. Conformidade e emissão/configuração reais continuam bloqueadas. Entrega técnica não significa aceitação do utilizador ou autorização do incremento seguinte.
|
||||
@@ -0,0 +1,208 @@
|
||||
# Serviços — contas a receber, recebimentos parciais e reconciliação simulada
|
||||
|
||||
27/10/2026, Africa/Johannesburg. Versão 0.2. **Âmbito aprovado pelo utilizador; ver secção 12. Sem aplicação de migrações, concessões ou operações por este registo.**
|
||||
|
||||
## 1. Base preservada e incremento mínimo
|
||||
|
||||
Directório confirmado: `C:\laragon\www\sgf-tempo`. Base Git: `4276aca`, entrega técnica aceite de documento de teste no navegador e PDF. Preservar integralmente alterações posteriores, incluindo a migração `060000` e as oito concessões já aplicadas, respectivas provas e a revisão documental de conformidade. Não fazer checkout/reset desse checkpoint para iniciar este trabalho.
|
||||
|
||||
Fontes reutilizadas, sem novo cotejo fiscal do InvesteMoz:
|
||||
|
||||
- [Percurso de serviços](SERVICES_WORKFLOW_SPEC.md): cenário 1 000,00 → 400,00 + 600,00, variante redutora e reconciliação simulada. Esta proposta recorta parte de C; não autoriza o fecho ou a contabilidade previstos naquele roteiro.
|
||||
- [Matriz documental](BILLING_DOCUMENTS_FIELD_SPEC.md): identidade exacta, recebimento, afectação e recibo distintos; FT 10/2026 não se confunde com FT 11/2026 pelo valor.
|
||||
- [Delimitação B](SERVICES_B_SCOPE.md), [entrega B1](SERVICES_B1_DELIVERY.md), preparação documental, pré-visualização e cálculo aceites: não converter confirmação interna ou cálculo em dívida exigível.
|
||||
- [Entrega técnica de emissão](SERVICE_INVOICE_TEST_DELIVERY.md), incluindo aplicação posterior da migração/concessões, e [conformidade, secção 11](SERVICE_INVOICE_ISSUANCE_SCOPE.md#11-conformidade--cotejo-dirigido-de-27102026): emissão/configuração real permanecem bloqueadas. Não repetir provas aceites ou reabrir responsáveis/série/fiscalidade.
|
||||
|
||||
Leitura dirigida do código actual: `ServiceInvoicing` já fixa documento, fotografia, PDF, identidade, contador, auditoria, evento/outbox e comando idempotente, exclusivamente no ambiente isolado seguro. `si_correction_requests` guarda pedidos sem efeito monetário. `DraftValues`/Brick Math fornecem aritmética decimal exacta; o contexto e as permissões vêm da fundação. Não foram localizados módulos/rotas/migrações operacionais de contas a receber, recebimentos, afectações ou reconciliação na pesquisa dirigida de `app/Modules`, `routes` e `database/migrations`.
|
||||
|
||||
| Já existe e deve ser reutilizado | Falta neste incremento proposto |
|
||||
| --- | --- |
|
||||
| Cliente/serviço da empresa; documentos da unidade; sessão, CSRF, contexto e permissões explícitas | Obrigação operacional de teste, com abertura explícita e saldo derivado |
|
||||
| Documento sintético imutável `si_invoices`, identidade e fotografia preservadas | Recebimento proposto/confirmado, afectação explícita e reversões rastreáveis |
|
||||
| Aritmética exacta, auditoria e padrões transaccionais/idempotentes | Invariantes de disponibilidade, saldo e concorrência entre recebimentos/afectações |
|
||||
| Eventos/outbox de A, B1 e emissão, com semânticas próprias | Eventos específicos deste percurso; observações e conferência exclusivamente simuladas |
|
||||
| Pedido de correcção documental sem efeito | Documento redutor sintético independente e aplicação explícita à obrigação, sem correcção fiscal real |
|
||||
|
||||
Não reconstruir acontecimentos a partir do estado actual dos cadastros nem consumir eventos B1 como dívida. Reutilizar mecanismos, sem mudar a semântica dos eventos existentes ou activar consumidores contabilísticos.
|
||||
|
||||
## 2. Recorte e linguagem da demonstração
|
||||
|
||||
Uma empresa sintética, uma unidade, um cliente, um documento de origem sintético e **MZN explicitamente seleccionado no cenário**. Montante documental de teste: 1 000,00, já fixado na fotografia; não recalcular IVA nem deduzir taxa zero desse montante. Não utilizar Tempo Lda/SEGI, Aurora, contas reais ou o cálculo condicionado real como fixtures.
|
||||
|
||||
Só admitir como origem uma identidade exacta de documento de teste elegível produzido pelo percurso já aceite. Uma fixture poderá prepará-lo pelos mecanismos existentes; não inserir uma factura fingindo contornar prontidão/guarda. Uma obrigação por documento neste recorte, sem prestações parceladas, múltiplos documentos ou repartição entre unidades/clientes. Integração futura de facturas reais exige âmbito próprio.
|
||||
|
||||
Avisos permanentes nas listas, detalhes, observações e comprovativo interno: **«SIMULAÇÃO — SEM MOVIMENTAÇÃO DE DINHEIRO»** e **«TESTE — SEM VALIDADE FISCAL»**. Obrigações e recebimentos de teste não representam dívida ou pagamento reais. Não criar recibo fiscal, factura-recibo, série real ou nova numeração fiscal. Não acrescentar PDF neste incremento: o PDF de origem existente continua preservado.
|
||||
|
||||
Excluir câmbio, múltiplas moedas, retenções, descontos financeiros, adiantamentos, afectações entre clientes/unidades, devoluções de dinheiro, taxas bancárias, importações bancárias e conciliação agregada de vários recebimentos. Também fora: lançamentos, reconhecimento, apuramento fiscal, fecho e publicação. Um excesso é uma excepção ligada a esta obrigação existente, não autorização para gerir adiantamentos.
|
||||
|
||||
## 3. Entidades, ligações e campos
|
||||
|
||||
Todas as entidades operacionais levam ID estável, tenant/empresa/unidade imutáveis, cliente, moeda explícita quando monetárias, marcador sintético controlado pelo servidor, autor, instante de registo UTC e zona/data civil relevante. Contexto validado no servidor; IDs enviados pelo navegador não autorizam relações. Cliente é reutilizado do cadastro empresarial, sem cópia por unidade; o snapshot de origem conserva a identidade histórica.
|
||||
|
||||
| Entidade | Ligações e campos específicos mínimos | Efeito próprio |
|
||||
| --- | --- | --- |
|
||||
| Documento de origem | ID `si_invoices`; empresa/unidade/cliente; tipo, série, número; versão/hash da fotografia; montante e moeda fixados; referência legível de teste | Fonte documental. Existir não abre obrigação nem regista recebimento neste recorte |
|
||||
| Obrigação a receber | Documento exacto único; snapshot do montante e identidade usados; fundamento de abertura sintético; data de abertura; vencimento opcional, origem do vencimento e data de corte da consulta; versão e confirmação | Confirmação explícita abre saldo operacional **de teste**. Não determina exigibilidade do IVA ou reconhecimento contabilístico |
|
||||
| Proposta de recebimento | Obrigação/cliente/contexto; montante positivo; data declarada do recebimento distinta da data de registo; origem sintética e identificador estável do acontecimento; evidência de teste e hash; versão, proponente, estado | Regista declaração ainda por confirmar. Não reduz saldo nem prova dinheiro em banco |
|
||||
| Confirmação/recusa de recebimento | ID e versão da proposta; decisão, autor distinto, instante, motivo e referências da evidência | Confirma valor recebido de teste disponível para afectação. Não afecta documento nem reconcilia automaticamente |
|
||||
| Afectação | ID do recebimento confirmado + obrigação + documento exacto; montante positivo, moeda; autor/instante; versões revistas e comando | Reduz saldo do documento e disponível do recebimento, atomicamente. Uma afectação não é outro recebimento |
|
||||
| Comprovativo interno | Referência técnica estável da confirmação; recebimento e afectações identificados; valores e data de corte da vista | Consulta interna da evidência. Não é recibo fiscal nem novo evento monetário; reabrir não muda montantes |
|
||||
| Observação de fonte simulada | Fonte/lote de teste, ID externo único nesse âmbito, cliente, moeda, valor, data, referência exacta do recebimento/documento e hash do conteúdo | Evidência artificial independente. Não cria recebimento ou afectação |
|
||||
| Correspondência de reconciliação | Observação + recebimento confirmado; valores/datas/referências conferidos, decisão, autor, instante, versão e motivo | Marca **reconciliado em simulação**, nunca reconciliação bancária real. Um vínculo activo por observação e por recebimento neste recorte |
|
||||
| Correcção/reversão operacional | Tipo, alvo exacto, versão, montante/efeito calculado, motivo, proponente, decisão, autores e vínculos de reversão | Operação compensatória imutável. Não edita, apaga ou substitui o original |
|
||||
| Documento redutor sintético | ID próprio, tipo `TEST-REDUCTION`, documento e linha originais, montante positivo, moeda, motivo, fotografia e validação; aplicação única à obrigação | Redução de teste independente, sem nota fiscal real. Não deriva de `si_correction_requests` |
|
||||
| Comando, histórico, evento/outbox | Chave, actor/âmbito/acção, hash canónico, versões, correlação/causação, resultado e estado de processamento separado | Recuperação sem duplicação; eventos específicos, sem efeitos contabilísticos ou externos |
|
||||
|
||||
Cardinalidades limitadas: documento 1 → 0/1 obrigação; obrigação 1 → N recebimentos ligados; recebimento 1 → N afectações históricas, todas para essa única obrigação; afectação → 0/1 reversão integral; recebimento → 0/1 reversão integral; recebimento 1 ↔ 0/1 observação activa de reconciliação. Documentos redutores ligam-se à obrigação e original sem alterar a fotografia deste. Não implementar um motor geral de distribuição por carteira.
|
||||
|
||||
Vencimento desconhecido guarda `null` e pendência, nunca a data actual, zero ou próxima facturação. Datas declaradas futuras/incompatíveis exigem recusa ou pendência explícita segundo o cenário; nenhum relógio de teste passa a data operacional real. Correcções de vencimento exigem nova versão justificada e autorizada, não edição silenciosa; essa autorização é incluída na proposta de correcções abaixo.
|
||||
|
||||
## 4. Estados e transições independentes
|
||||
|
||||
| Objecto / dimensão | Estados e transições propostos |
|
||||
| --- | --- |
|
||||
| Obrigação: abertura | Proposta → aberta por confirmação; proposta → recusada. Documento inválido/rascunho/B1 bloqueia abertura. Não há abertura automática ao receber evento de emissão |
|
||||
| Obrigação: saldo | Sem afectação / parcial / liquidada, derivados do saldo líquido; pode voltar a parcial/aberta por reversão aprovada, sem apagar liquidação histórica |
|
||||
| Obrigação: vencimento | Desconhecido / não vencida / vencida, derivado separadamente para saldo positivo na data de corte explícita. Proposta: vencida quando data de corte civil for posterior ao vencimento; no próprio dia ainda não vencida. Saldo zero: liquidada, sem valor vencido actual |
|
||||
| Recebimento | Proposto → confirmado ou recusado. Só confirmado participa na disponibilidade; confirmado → revertido por decisão compensatória, respeitando dependências. Recusa e correcção da proposta preservam versões |
|
||||
| Afectação | Pedido válido → aplicada atomicamente; aplicada → revertida integralmente por decisão própria. Pedido inválido não cria afectação aplicada. Não existe estado aplicado com saldo negativo |
|
||||
| Reconciliação | Não conferida → correspondência proposta → reconciliada em simulação ou divergente. Divergência não reduz diferenças nem confirma recebimento. Reconciliada → desfeita por decisão rastreável; nunca voltar por edição directa |
|
||||
| Correcção operacional | Proposta → aprovada/aplicada atomicamente ou recusada. Aprovação desactualizada não executa sobre valores entretanto alterados; requer nova revisão |
|
||||
| Redução documental de teste | Documento sintético preparado → validado → aplicação explícita única à obrigação. Não converte pedido de correcção fiscal em documento válido |
|
||||
|
||||
Não usar um único estado «pago/reconciliado». É admissível documento liquidado com dois recebimentos não conferidos; ou recebimento reconciliado em simulação mas parcialmente por afectar, com documento ainda aberto. Nada aqui fecha período ou determina datas fiscais.
|
||||
|
||||
## 5. Aritmética, excepções e preservação
|
||||
|
||||
Proposta `SGF-RECEIVABLES-SIM-v1`, a aprovar para os testes. Usar Brick Math no servidor, cadeias decimais na API e armazenamento exacto. Reutilizar o limite técnico de até 16 algarismos inteiros/8 decimais das entradas existentes, validando também resultados e capacidade do armazenamento antes de persistir. Para este recorte MZN, montantes devem ser exactamente representáveis a duas casas: aceitar `400`, `400.0`, `400.00` como iguais; recusar `400.001`, notação exponencial, float e valores fora do limite. Não truncar ou arredondar para caber. Esta proposta de representação de recebimentos não altera a política de IVA, preços ou fotografias aceites.
|
||||
|
||||
Definições, só com efeitos confirmados/aplicados e não revertidos, na mesma moeda e data de corte:
|
||||
|
||||
- `D`: valor fixado do documento; `C`: reduções sintéticas aplicadas; `A`: soma líquida das afectações activas.
|
||||
- `Saldo_documento = D − C − A`, sempre maior ou igual a zero.
|
||||
- `R`: valor confirmado do recebimento ainda não revertido; `AR`: afectações activas desse recebimento.
|
||||
- `Disponível_por_afectar = R − AR`, sempre maior ou igual a zero.
|
||||
- Montante a afectar `x > 0` deve cumprir **simultaneamente** `x ≤ Disponível_por_afectar` e `x ≤ Saldo_documento`.
|
||||
|
||||
Histórico preserva valores exactos originais e compensações; apresentar separadamente original, reduções, recebido, afectado, por afectar e saldo, sem chamar ao total recebido «pago no documento» se não foi afectado. Saldos actuais são projecções verificáveis dos movimentos, não campos livremente editáveis. Totais agregados que ultrapassem a capacidade declarada provocam erro explícito e rollback, nunca overflow/coerção.
|
||||
|
||||
| Excepção | Tratamento proposto |
|
||||
| --- | --- |
|
||||
| Recebimento superior ao saldo | Registar/confirmar o valor integral com aviso explícito de excesso. Não o cortar nem afectar automaticamente. Afectação acima do saldo é recusada por inteiro; o utilizador pode submeter afectação menor. Excesso fica por afectar e pendente de decisão futura, sem receita, crédito comercial, adiantamento ou reembolso automático |
|
||||
| Mesmo pedido repetido | Recuperar resultado e identidades originais, sem outro movimento/evento. Mesmo identificador com conteúdo diferente é conflito |
|
||||
| Mesmo acontecimento com outra chave | Unicidade da origem + ID estável do acontecimento no âmbito impede nova confirmação/recebimento. Mesmo valor/data/cliente não prova duplicação; sinais de possível duplicado mostram alerta, não fusão ou eliminação automática |
|
||||
| Fonte sem identificador suficiente | Pendência e confirmação bloqueada até atribuição de identidade interna estável da evidência sintética. Não inventar referência bancária |
|
||||
| Moeda ausente/diferente, outro cliente/unidade ou documento homónimo | Recusa. Sem conversão, transferência de saldo ou procura aproximada por valor |
|
||||
| Documento já liquidado | Novo recebimento ligado ao documento é excepção de excesso; não reabre dívida. Afectação positiva recusada |
|
||||
| Redução deixa dívida líquida inferior ao já afectado | Recusar aplicação, preservando proposta. Exigir reversão explícita da afectação suficiente; depois revalidar redução. A quantia libertada fica por afectar, sem devolução automática |
|
||||
| Reversão do recebimento com afectações/reconciliação activas | Bloquear até desfazer reconciliação e reverter afectações por operações aprovadas separadas. Sem cascata oculta. Reversão do recebimento cancela registo de teste, não executa estorno bancário |
|
||||
| Erro em recebimento confirmado | Reversão integral rastreável e nova proposta, ligada ao original, se necessária. Não alterar montante, cliente, unidade, data ou moeda do confirmado |
|
||||
| Divergência de fonte | Mostrar valor declarado, valor observado e diferença exacta. Não compensar diferença, alterar recebimento ou marcar reconciliado por tolerância |
|
||||
|
||||
Reversões são integrais neste primeiro recorte; devolução parcial, abatimento ou transferência exigem extensão. A afectação revertida não volta a aplicar-se por replay do comando original: o replay devolve a operação histórica com o seu estado actual; nova intenção necessita nova chave e revisão.
|
||||
|
||||
## 6. Reconciliação apenas simulada e comprovativo
|
||||
|
||||
Registar observações artificiais num espaço de teste identificável, sem upload de extractos reais ou acesso a bancos. Propor correspondência por referências explícitas; validar recebimento confirmado, identidade do documento/cliente/âmbito, mesma moeda, montante exacto integral e datas da observação declaradas. A data bancária e a data de recebimento são campos distintos; não forçar igualdade nem inferir uma da outra. Sem regra/evidência suficiente, manter pendência. Não fazer matching automático só por cliente, data e valor.
|
||||
|
||||
Conferência é acção explícita, com permissão e autor. Neste recorte, correspondência 1:1 e sem tolerância monetária: 399,99 não reconcilia 400,00. Observação repetida com mesmo ID/hash recupera a original; conteúdo diferente para esse ID gera conflito. Não reutilizar observação já conferida noutro recebimento. A reversão da conferência liberta o vínculo por evento compensatório, conservando a história. Uma observação pendente não gera recebimento e uma afectação não gera observação.
|
||||
|
||||
Comprovativo interno apenas no navegador, sem série de recibo: identidade técnica do recebimento, estado, evidência sintética, moeda, valores recebido/afectado/disponível, afectações e respectivas identidades documentais. Mostrar data de corte/versão da consulta e reversões; sem substituir silenciosamente uma vista aberta. Se no futuro houver comprovativo emitido/entregue, exigirá fotografia e regras próprias. Não confundir esta vista com recibo fiscal nem marcar o cliente como tendo recebido um comprovativo por o operador o consultar.
|
||||
|
||||
## 7. Exemplos sintéticos e resultados esperados
|
||||
|
||||
Todos os exemplos usam fixtures independentes; nunca alterar o caso principal para simular uma variante. IDs abaixo são rótulos, não IDs reais fixos. Documento `DOC-TEST-A`, fotografia de 1 000,00 MZN, obrigação `OB-A` aberta explicitamente, sem vencimento informado. Não é necessário refazer o cálculo fiscal da factura para testar o subpercurso; a fixture de origem satisfaz o percurso de emissão de teste já aceite.
|
||||
|
||||
| Passo do caso principal | Recebido acumulado | Afectado acumulado | Por afectar | Saldo OB-A | Reconciliação |
|
||||
| --- | ---: | ---: | ---: | ---: | --- |
|
||||
| Confirmar abertura OB-A | 0,00 | 0,00 | 0,00 | 1 000,00 | Não aplicável |
|
||||
| Confirmar R-A de 400,00 | 400,00 | 0,00 | 400,00 | 1 000,00 | Não conferida |
|
||||
| Aplicar AF-A de 400,00 | 400,00 | 400,00 | 0,00 | 600,00 | Não conferida |
|
||||
| Repetir confirmação R-A e AF-A | 400,00 | 400,00 | 0,00 | 600,00 | Sem alteração |
|
||||
| Confirmar R-B de 600,00 | 1 000,00 | 400,00 | 600,00 | 600,00 | Não conferida |
|
||||
| Aplicar AF-B de 600,00 | 1 000,00 | 1 000,00 | 0,00 | 0,00 | Ambas não conferidas |
|
||||
| Conferir OBS-A=400 e OBS-B=600 | 1 000,00 | 1 000,00 | 0,00 | 0,00 | Duas correspondências simuladas |
|
||||
|
||||
O saldo era zero **antes** da conferência. Repetir conferências não cria movimentos. Sem vencimento, os passos com saldo positivo mostram «vencimento por definir», não «vencido». Com vencimento sintético 10/11/2026 e corte 11/11/2026, 600,00 em aberto são vencidos; corte 10/11 não produz atraso sob a convenção proposta.
|
||||
|
||||
Variantes obrigatórias:
|
||||
|
||||
1. **Redução:** documento `DOC-TEST-C` de 1 000,00; R-C=400 afectado → saldo 600. Documento independente `TEST-REDUCTION-C`, 100,00, explicitamente ligado ao original/linha, validado e aplicado uma só vez → dívida líquida 900, afectado 400, saldo 500. R-D=500 afectado → saldo zero. Original continua 1 000,00. Repetição da redução não subtrai outros 100; pedido `si_correction_requests` sozinho não reduz nada.
|
||||
2. **Excesso:** documento de 1 000; primeiro 400 afectado; segundo recebimento 700 confirmado. Tentar afectar 700 recusa, saldo continua 600 e disponível 700. Afectar explicitamente 600 deixa saldo zero e 100 por afectar. Reconciliação simulada de 700 pode ser conferida como recebimento integral; os 100 continuam pendentes. Nenhuma receita/restituição nasce daí.
|
||||
3. **Divergência:** R=400, observação=399,99 → diferença 0,01; reconciliação divergente, sem alterar afectação ou saldo. Observação para documento B de igual valor não confere R de documento A.
|
||||
4. **Reversão:** após caso principal, proposta de reversão de R-B é bloqueada pelas dependências; desfazer conferência de R-B e reverter AF-B reabre saldo 600, com R-B=600 por afectar; reverter R-B deixa recebido líquido 400. Originais, decisões e evidências permanecem. Repetir cada reversão tem efeito único.
|
||||
5. **Redução após liquidação:** tentar reduzir 100 quando 1 000 já afectados recusa por excesso de afectação. Reverter integralmente a afectação de 600, aplicar redução de 100 e afectar de novo 500, com confirmação própria → saldo zero e 100 por afectar. Não automatizar estes passos ou simular devolução.
|
||||
|
||||
## 8. Responsabilidades e permissões — proposta nova, sem concessões
|
||||
|
||||
As funções de emissão, série, configuração visual e validação fiscal já aprovadas não mudam. **Não implicam poderes de recebimentos.** Propõe-se separação entre preparação e confirmação, com identidade distinta verificada no servidor, inclusive quando houver delegação organizacional. A utilização de uma sessão de outro utilizador não serve como prova técnica de separação de autores.
|
||||
|
||||
| Acção / direito proposto | Osmane — proposta | Samira — proposta |
|
||||
| --- | --- | --- |
|
||||
| Consultar percurso — `service_receivables.view` | Sim | Sim |
|
||||
| Preparar obrigação e recebimento/evidência — `service_receivables.prepare` | Sim | Não |
|
||||
| Confirmar/recusar abertura de obrigação e recebimento — `service_receivables.confirm` | Não | Sim, distinta do proponente |
|
||||
| Aplicar afectação explícita de recebimento confirmado — `service_receivables.allocate` | Sim | Não |
|
||||
| Conferir observação e correspondência simuladas — `service_receivables.reconcile` | Não | Sim |
|
||||
| Propor redução sintética, reversão/desconciliação ou correcção de vencimento — `service_receivables.correction_request` | Sim | Não |
|
||||
| Validar/recusar e aplicar atomicamente correcção operacional de teste — `service_receivables.correction_approve` | Não | Sim, distinta do proponente |
|
||||
|
||||
Proposta: **oito concessões**, quatro por conta: Osmane com view, prepare, allocate e correction_request; Samira com view, confirm, reconcile e correction_approve. Os nomes representam funções propostas, não regras no código. Antes de aplicar acessos, apresentar contas existentes conferidas, acções e âmbito exactos para confirmação específica. Nenhuma concessão é efectuada por este documento.
|
||||
|
||||
Todos estes direitos são da unidade explicitamente autorizada da empresa, condicionados também à pertença e `unit.view`; sem direito empresarial que abra operações de outras unidades. Para uma futura aplicação nominativa, propor apenas Tempo Lda/SEGI, sujeita a confirmação específica; desenvolvimento e demonstração usam identidades e âmbitos sintéticos equivalentes em `sgf_tempo_test`. Sem gestão de concessões, poderes universais ou activação de recebimentos reais. A view dá acesso ao comprovativo interno; não autoriza reabrir PDF/documento sem direito próprio.
|
||||
|
||||
## 9. Integridade, concorrência, idempotência e recuperação
|
||||
|
||||
Propostas técnicas para futura implementação, sem DDL nesta etapa:
|
||||
|
||||
1. **Fronteira de ambiente:** nova guarda específica deste percurso permite mutações/provas só em `testing`/`browser-testing` e após `TestingDatabaseGuard` confirmar `sgf_tempo_test` no cluster próprio. Não depender apenas de etiqueta TEST, frontend ou variável de ambiente. Ambiente normal recusa mesmo com permissões. Não relaxar `ServiceInvoicing::guard()` ou reutilizar a aplicação normal para provas.
|
||||
2. **Isolamento também na base:** FKs compostas/constraints/triggers asseguram igualdade de tenant/empresa/unidade/cliente/moeda entre obrigação, origem, recebimento, afectação, evidência e reversão. Âmbitos, montantes confirmados e snapshots imutáveis, inclusive UPDATE/DELETE em massa. Eloquent scope não é fronteira completa. Inserções por ligação fora do âmbito devem falhar, não apenas os formulários.
|
||||
3. **Autorização:** revalidar sessão, CSRF, contexto, pertenças, direitos e versões no pedido e dentro da transacção antes do efeito. Revogação/mudança de contexto invalida formulário aberto; não grava noutra unidade. Tarefas/consumidores também verificam origem e ambiente, sem credenciais de administrador ou bypass.
|
||||
4. **Unicidades:** obrigação por documento; acontecimento por origem/ID estável/âmbito; observação por fonte/lote/ID; decisão terminal por versão; reversão integral única por alvo; aplicação única de redução; correspondência activa 1:1. Uma nova chave HTTP não ultrapassa unicidades de negócio.
|
||||
5. **Comando idempotente:** chave obrigatória por âmbito/actor/acção, hash canónico das entradas, alvo e versões. Números equivalentes são normalizados exactamente. Repetição idêntica devolve IDs/efeitos já gravados; alteração de alvo/conteúdo/versão gera conflito. Revalidar direito de consulta antes de devolver replay; não revelar resposta de outro autor/unidade. Mesma chave usada noutro contexto não reutiliza resultado anterior.
|
||||
6. **Saldos sob bloqueio:** bloquear obrigação, recebimentos e vínculos afectados numa ordem global documentada; revalidar saldo/disponível e versões dentro da mesma transacção. Dois comandos que competem pelo mesmo saldo não podem ambos gastar o valor. Operações por SQL directo também devem passar pelos invariantes da base, com serialização dos agregados; CHECK por linha sozinho não controla somas concorrentes.
|
||||
7. **Atomicidade:** movimento/decisão, projecção de saldo/versionamento, resultado do comando, auditoria e evento/outbox numa transacção. Falha de qualquer parte desfaz o conjunto. Eventos como `receivable.opened`, `receipt.confirmed`, `allocation.applied/reversed`, `reconciliation.simulated_confirmed/reversed` e `synthetic_reduction.applied` têm schema, origem e causação explícitos. Nada os trata como autorização de lançamento ou transferência.
|
||||
8. **Resposta perdida:** após commit, retry recupera resultado original; antes do commit, nenhum efeito fica aplicado. Pendente de negócio é diferente de erro técnico. Chave de comando em curso não pode bloquear indefinidamente: usar transacção/timeout e retry limitado, sem criar outro acontecimento para contornar erro.
|
||||
9. **Concorrência e falhas:** conflito de versão exige nova revisão explícita. Deadlock/serialização pode ter retry técnico limitado com a mesma chave, revalidando tudo; não reutilizar decisão de aprovação sobre estado materialmente diferente. Confirmação simultânea, afectações concorrentes e reversão concorrente com reconciliação devem ter um resultado coerente único.
|
||||
10. **Recuperação e consumidor:** outbox entregue pelo menos uma vez, consumidor interno idempotente por ID de evento; trabalho/estado de entrega separado do evento imutável. Falha após consumir não duplica projecção. Verificação read-only reconcilia movimentos com saldos derivados; divergência gera falha visível, nunca ajuste automático ou reconstrução do histórico. Sem processamento contabilístico.
|
||||
|
||||
## 10. Ecrãs mínimos e critérios de aceitação futuros
|
||||
|
||||
Reutilizar login, cabeçalho e contexto existentes. Ecrãs: (1) lista/detalhe de obrigação com identidade documental e saldos discriminados; (2) preparação e fila de confirmação de recebimentos; (3) afectação explícita e comprovativo interno; (4) observações e conferência simuladas; (5) pedidos/decisões de correcção e linha do tempo. Podem ser separadores de um mesmo percurso, sem criar portal ou painel geral de tesouraria. Mostrar apenas acções autorizadas, com recusa também no servidor.
|
||||
|
||||
Provas a implementar **só após aprovação**, com login real sintético no navegador e instância isolada, sem confundir `actingAs` com prova de autenticação:
|
||||
|
||||
- Caso principal e cinco variantes da secção 7, com identidades e somas exactas explicáveis. Liquidar não reconcilia; reconciliar não afecta nem cria recebimento. Rascunho, B1 e simples pedido de correcção recusados como origem de dívida/redução.
|
||||
- Vencimento desconhecido, no próprio dia, vencido, saldo parcial e saldo zero em cortes explícitos; ausência nunca vira atraso. Datas fiscais e conformidade do caso real permanecem como estavam.
|
||||
- Zero/negativo, escala excessiva, limite/overflow, moeda em falta/diferente e dados sem evidência recusados sem escrita parcial; 400,00 não se torna 399,99 por tolerância.
|
||||
- Repetição de cada comando; mesma chave com conteúdo diferente; nova chave sobre mesma origem/observação; repetição após reversão; não duplicar montantes, decisões, afectações ou eventos.
|
||||
- Dois processos realmente sobrepostos: mesma confirmação; afectações de 400+700 contra saldo 1 000; duas afectações disputando o mesmo disponível; redução/reversão/conferência concorrentes. No cenário 400+700, no máximo uma delas aplica integralmente com as versões iniciais; a outra é recusada/revista, sem saldo negativo ou divisão implícita.
|
||||
- Falha injectada antes do commit, na auditoria/outbox e resposta perdida após commit; nenhum órfão e um único resultado recuperável. Consumidor repetido e interrompido não duplica projecção.
|
||||
- URL/API, ID adulterado, empresa irmã do mesmo tenant, unidade não autorizada, outro cliente e dados históricos; revogação com efeito no pedido seguinte e formulário aberto após troca de contexto. SQL em massa não transfere, apaga ou altera originais nem contorna somas.
|
||||
- Separação de proponente/confirmador, consulta sem alteração, emissão/administração sem novos poderes; aprovações antigas não autorizam novos movimentos. Nenhum acesso empresarial atravessa unidades.
|
||||
- Guardas recusam base diferente de `sgf_tempo_test`, ambiente normal mesmo com novos direitos, documento não sintético e tentativa de fixture na base normal. Não alterar ligação da aplicação normal nem terminar processos alheios para libertar portas.
|
||||
- PDF/fotografia de origem, B1, dados/permissões anteriores e oito concessões de emissão preservados. Executar apenas regressões tocadas pelo incremento, sem repetir suites aceites por rotina. Compilação se houver React; no presente documento não foi executado teste ou build.
|
||||
|
||||
## 11. Decisões realmente novas e proposta para aprovação
|
||||
|
||||
Não pedir novamente regime/IVA, responsáveis de séries/emissão, série nova, plano contabilístico ou aceitação do cálculo. Não condicionar esta demonstração sintética a uma nova pesquisa fiscal. São novas e ainda propostas:
|
||||
|
||||
1. **Circuito operacional e acessos:** confirmar a matriz da secção 8, incluindo confirmação por identidade distinta, afectação por Osmane e reconciliação/correcção por Samira. Concessões concretas continuam sujeitas a confirmação específica posterior.
|
||||
2. **Tratamento das excepções:** confirmar excesso explicitamente por afectar; sobreafectação recusada por inteiro; sem automatismo de reembolso/crédito; reversões integrais com dependências explícitas; redução posterior à liquidação bloqueada até libertar afectação suficiente.
|
||||
3. **Convenções do ensaio:** confirmar MZN explícito, representabilidade exacta a duas casas, vencido só após o dia de vencimento, ausência de vencimento como pendência, reconciliação 1:1 sem tolerância e comprovativo interno apenas no navegador. São decisões operacionais deste recorte, não validação fiscal de recibos.
|
||||
|
||||
**Proposta concreta:** autorizar futuramente um único incremento técnico isolado `SGF-RECEIVABLES-SIM-v1`, com abertura explícita de obrigação sobre documento de teste existente, recebimentos 400/600, confirmação separada, afectações manuais exactas, saldo derivado, comprovativo interno, conferência de duas observações sintéticas, variantes de excesso/divergência/reversão/redução e eventos duráveis. Reutilizar contexto, aritmética e padrões já entregues; acrescentar apenas entidades, comandos e vistas necessários a esse percurso. Não criar motor financeiro geral.
|
||||
|
||||
A futura execução deve apresentar o delta aditivo e base de destino antes de qualquer migração em desenvolvimento e as concessões exactas antes de aplicação. Este documento **não aprova nem executa** esses passos. Implementação/demonstração continua restrita à base de testes, sem operações reais, autorização de emissão, recibo fiscal, banco, contabilização ou fecho. Série/configuração real e emissão permanecem bloqueadas; as pendências de conformidade não são encerradas por esta proposta.
|
||||
|
||||
## 12. Aprovação do âmbito
|
||||
|
||||
Em 27/10/2026, após apresentação da secção 11 e da matriz de permissões, o utilizador respondeu **«confirmo o ambito»**. Ficam aprovados o recorte `SGF-RECEIVABLES-SIM-v1`, o circuito e matriz funcional da secção 8, o tratamento das excepções e as convenções de ensaio da secção 11. As referências anteriores a estas decisões como propostas pendentes são históricas; não devem voltar a ser submetidas como decisões novas.
|
||||
|
||||
A aprovação da matriz funcional não aplica as oito concessões: contas, acções e âmbitos exactos continuam sujeitos à confirmação específica antes da aplicação. Mantém-se a apresentação prévia do delta aditivo e base de destino antes de qualquer migração em desenvolvimento. O presente registo apenas documenta a aprovação do âmbito; não executa implementação, testes, migrações ou escrita operacional.
|
||||
|
||||
Recebimentos e reconciliação mantêm-se exclusivamente sintéticos em `sgf_tempo_test`, sem recibos fiscais, dinheiro, lançamentos, fecho ou publicação. Preservar `4276aca` e alterações posteriores, aprovações existentes e bloqueio de emissão/configuração real.
|
||||
|
||||
## 13. Execução técnica posterior autorizada
|
||||
|
||||
Em 27/10/2026, o utilizador autorizou expressamente implementar `SGF-RECEIVABLES-SIM-v1`, código/testes e demonstração apenas no ambiente isolado. A entrega e os resultados estão em [SERVICE_RECEIVABLES_DELIVERY.md](SERVICE_RECEIVABLES_DELIVERY.md). As restrições anteriores a implementação referiam-se à etapa documental e foram substituídas apenas neste âmbito técnico. Migração em desenvolvimento e aplicação das oito concessões reais continuam sem execução e sujeitas às confirmações específicas previstas. A autorização não retira o bloqueio de emissão real nem constitui aceitação da entrega.
|
||||
@@ -0,0 +1,10 @@
|
||||
# Encerramento isolado — WORKSHOP-DIRECT-COST-SIM-v1
|
||||
|
||||
27/10/2026, Africa/Johannesburg. O utilizador autorizou o encerramento por delegação, condicionado à conferência do percurso e satisfação técnica, mantendo `090000` e quatro concessões por aplicar. O percurso foi conferido através da demonstração e provas já preservadas: 275 MZN de custo directo conhecido, variante de 175 MZN incompletos, identidades sintéticas distintas, histórico, concorrência e recuperação. Não se declara uma nova verificação pessoal do utilizador no navegador.
|
||||
|
||||
Aceitação limitada à entrega isolada de [WORKSHOP_DIRECT_COST_DELIVERY.md](WORKSHOP_DIRECT_COST_DELIVERY.md), com 49 testes / 1 010 asserções aprovados, seis provas concorrentes e compilação concluída. Não se repetiram testes por esta alteração exclusivamente documental. O campo `user_acceptance: false` nas provas anteriores descreve o estado da entrega técnica antes deste encerramento e não é reescrito.
|
||||
|
||||
- Migração `090000` não aplicada em `sgf_tempo_dev`; quatro concessões reais apenas propostas para confirmação específica.
|
||||
- Custeio operacional real, emissão e restantes operações reais continuam bloqueados; sem stock, custos indirectos, lote industrial, lançamentos ou publicação.
|
||||
- Preservados `7628645`, `ea9dcb3`, oficinas, recebimentos, cálculo fiscal e aprovações existentes. Não se reabre a aceitação dessas entregas.
|
||||
- O commit que contém este registo é o checkpoint local. Inclui fontes, testes, documentação e provas sintéticas; não inclui credenciais ou dados operacionais reais novos. Não autoriza push ou outro incremento.
|
||||
@@ -0,0 +1,85 @@
|
||||
# WORKSHOP-DIRECT-COST-SIM-v1 — entrega técnica isolada
|
||||
|
||||
27/10/2026, Africa/Johannesburg. Implementa apenas o ensaio aprovado na secção 14 de [INDUSTRIAL_COST_ACCOUNTING_SCOPE.md](INDUSTRIAL_COST_ACCOUNTING_SCOPE.md). **Sem aceitação presumida, custeio real, publicação ou avanço para lote industrial/CIF.** Preservados `7628645`, oficinas, recebimentos, B1, motor exacto e aprovações. O commit posterior `ea9dcb3`, observado durante a execução e não criado por este procedimento, também foi preservado.
|
||||
|
||||
## Funcionalidade
|
||||
|
||||
- Reutiliza os apontamentos técnicos verificados de uma ordem por ID e versão. Não insere ou altera acontecimentos em `wo_*` ao propor/validar custos. A fotografia do cálculo preserva a composição derivada, não um segundo consumo ou tempo operacional.
|
||||
- Taxas sintéticas com identificador, versão anterior explícita, origem técnica exacta, ordem/empresa/unidade, MZN, unidade e evidência. Zero expressamente indicado é válido; ausência é pendência. Não há procura automática da taxa mais recente: cada linha recebe ID e versão escolhidos ou ausência explícita. Identificadores alternativos podem coexistir e exigem escolha explícita.
|
||||
- Preparador propõe taxas e cálculos; validador distinto aprova/recusa a versão exacta. Uma aprovação de cálculo incompleto valida só a composição declarada e conserva pendências, nunca a transforma em custo completo. A validação não altera decisões ou apontamentos técnicos.
|
||||
- Cálculo limitado a duas origens seleccionadas: um consumo efectivo da empresa e um apontamento de trabalho efectivo. Entrega/devolução/requisição, deslocação, material do cliente, origem fora do âmbito ou não verificada são recusados. Não desconta novamente a devolução do consumo já observado.
|
||||
- Aritmética `Brick\Math` exacta existente; conversão de MIN para H por divisão explícita por 60. Decimais finitos são apresentados exactamente; divisão não finita conserva fracção racional, sem impor arredondamento. Não se reutiliza a política de IVA. Entradas de taxa são cadeias decimais não negativas, até 16 algarismos inteiros/8 decimais, sem float ou notação exponencial.
|
||||
- Versões novas preservam histórico. Correcção de origem/tarefa ou nova versão da taxa usada torna o cálculo desactualizado; nova versão de cálculo torna a anterior histórica. O conjunto de IDs de tempo/material da ordem também integra a dependência: acréscimos exigem revisão. Taxa de outro identificador não substitui a escolhida silenciosamente. Propostas/refusas de taxa sucessora suspendem conservadoramente o uso actual da versão anterior, sem alterar o seu histórico.
|
||||
|
||||
## Resultados demonstrados
|
||||
|
||||
| Caso | Composição | Resultado e limite |
|
||||
| --- | --- | --- |
|
||||
| Taxas identificadas e validadas | 2 UN × 50 + 105 MIN ÷ 60 × 100 | 100 + 175 = **275 MZN de custo directo conhecido**, nunca custo completo/margem |
|
||||
| Taxa material ausente | Material pendente; 105/60 × 100 | **175 MZN conhecidos**, total seleccionado indisponível/incompleto e pendência explícita |
|
||||
| Taxa material zero explícita, teste automatizado | 2 × 0 + 105/60 × 100 | 175 no perímetro directo, taxa zero distinguida de ausência |
|
||||
| Divisão não finita, teste automatizado | 1 MIN ÷ 60 × 1 MZN/H | **1/60 MZN exacto**, sem truncagem ou cêntimo inventado |
|
||||
|
||||
Valorizado o perímetro seleccionado não significa que todos os custos da ordem estejam conhecidos. Sem salários reais, preços de venda, margens, custos indirectos, reconhecimento, stock ou valorização legal de inventário.
|
||||
|
||||
## Segurança, versões e recuperação
|
||||
|
||||
Novos direitos explícitos `direct_costs.view/prepare/validate`, sempre na unidade; não herdados de oficinas, emissão ou administração. Consulta de custos é separada do acesso técnico. Contexto, pertenças e direito específico são revalidados em cada comando e replay, inclusive dentro da transacção. Auto-aprovação é recusada mesmo com ambas as permissões. Identidades reais nunca são reconhecidas por nome/email no código funcional.
|
||||
|
||||
Transacção e bloqueio da empresa serializam preparação/validação/alterações técnicas; versões anteriores explícitas impedem duas sucessoras incompatíveis. A chave idempotente inclui actor/acção/contexto/conteúdo; resposta perdida recupera o ID, conteúdo diferente é conflito. Recalcular composição idêntica à última versão pode devolver o mesmo resultado, sem duplicar fotografia. Comando, auditoria, evento versionado e outbox são atómicos; falha de outbox desfaz a operação. Não há consumidor contabilístico. A outbox permanece `captured_no_accounting`.
|
||||
|
||||
FKs/CHECKs/triggers validam contexto, referências, verificação técnica, unidades, cadeias de versões, taxas aprovadas e separação de autores. As seis tabelas são append-only, incluindo contra UPDATE/DELETE em massa. O núcleo de composição exacta e a autorização autenticada são da aplicação; os triggers não são RLS nem substituem essas verificações. SQL administrativo é uma fronteira de confiança distinta. O bloqueio SQL de ambiente só admite `sgf_tempo_test` na porta 55432; a aplicação exige ainda ambiente isolado e `TestingDatabaseGuard` com papel `sgf_test_runner`.
|
||||
|
||||
## Provas e repetição
|
||||
|
||||
Provas: [resultados do navegador](proofs/direct-cost-browser-results.json), [275 MZN](proofs/direct-cost-275-browser.png), [175 MZN incompletos](proofs/direct-cost-partial-browser.png), [concorrência](proofs/direct-cost-concurrency.json) e [testes finais](proofs/direct-cost-tests.json).
|
||||
|
||||
Resultado final: **49 testes / 1 010 asserções, zero erros/falhas**, incluindo oito casos de custos directos. **Seis provas concorrentes aprovadas**. Compilação aprovada com Vite 8.3.5 e versões/dependências preservadas. Não foi necessária repetição da investigação fiscal. A instância do navegador foi parada antes da regressão final.
|
||||
|
||||
Percurso efectivamente realizado no Edge, `http://127.0.0.1:8001`, sessão/cache isolados e CSRF activo:
|
||||
|
||||
1. Preparador `gestor@example.test`: login real, Empresa Horizonte — Demonstração / Unidade Central — Demonstração → **Custos directos de teste**. Referências técnicas #4 v1 (105 MIN) e #6 v1 (2 UN) nesta execução; IDs não são fixos.
|
||||
2. Propôs `TEST-TRABALHO` v1 a 100 MZN/H e `TEST-MATERIAL` v1 a 50 MZN/UN, com evidência sintética.
|
||||
3. Validador `consulta@example.test`: login real distinto, mesmo contexto; validou as duas taxas. Não dispõe de formulário de preparação nem acesso técnico por consequência.
|
||||
4. Preparador entrou novamente, escolheu explicitamente as duas taxas e calculou 275 MZN. Validador aprovou a versão exacta com fundamento de custo directo conhecido.
|
||||
5. Preparador criou nova versão sem taxa material. Validador aprovou só os 175 MZN conhecidos com pendência. O resultado de 275 continuou preservado e identificado como histórico.
|
||||
|
||||
A fixture apenas criou/verificou fontes técnicas pelos comandos existentes da oficina, com relógio sintético local no processo para a autorização histórica e restaurado no fim. Não mudou relógio do sistema, ligação normal ou regras técnicas. Sete apontamentos de origem permaneceram sete após os cálculos. Palavras-passe aleatórias não são apresentadas ou versionadas.
|
||||
|
||||
Seis cenários com dois processos realmente sobrepostos: mesma taxa; mesma decisão; taxas sucessoras concorrentes; mesmo cálculo; cálculos concorrentes incompatíveis; cálculo novo versus aprovação antiga. Provas adicionais automatizadas: revogação no pedido seguinte/replay, identidades/contextos/versões manipulados, moedas/unidades/precisão, origem corrigida e ainda não verificada, imutabilidade SQL, recusa, falta versus zero e falha/recuperação de outbox. A regressão relevante inclui oficinas, recebimentos, B1 e guardas de testes.
|
||||
|
||||
Repetir exclusivamente em testes, sem instância de prova em execução durante os testes destrutivos:
|
||||
|
||||
```powershell
|
||||
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/sgf.ps1 test '--filter=DirectCostsTest|WorkshopTest|ServiceReceivablesTest|InternalConfirmationTest|DatabaseSafetyTest'
|
||||
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/sgf.ps1 npm run build
|
||||
```
|
||||
|
||||
Para o navegador, preparar uma base de testes vazia sob as guardas existentes, executar `scripts/browser-proof.ps1 start` (prepara a fundação sintética), depois `sgf.ps1 php scripts/direct-cost-fixture.php --env=testing`. O preparador recusa estado preenchido e não apaga dados. Seguir o percurso acima com a credencial no manifesto local protegido. Depois do percurso, `sgf.ps1 php scripts/direct-cost-proof.php --env=testing` e `sgf.ps1 php scripts/direct-cost-concurrency.php --env=testing`. Parar com `scripts/browser-proof.ps1 stop`; não terminar processos alheios para libertar portas. Os testes finais recriam só `sgf_tempo_test`, preservando as provas em ficheiros.
|
||||
|
||||
## Migração proposta — NÃO aplicada em desenvolvimento
|
||||
|
||||
**`2026_10_27_090000_create_workshop_direct_costs.php`**, SQL `database/sql/direct-costs.sql`, destino futuro **`sgf_tempo_dev`**, apenas após confirmação específica.
|
||||
|
||||
Seis tabelas novas: `dc_rates`, `dc_calculations`, `dc_decisions`, `dc_commands`, `dc_events`, `dc_outbox`; FKs, índices, versões únicas, funções/triggers de integridade, ambiente e imutabilidade. Amplia o CHECK de concessões com três nomes de unidade, preservando alternativas existentes. Não concede acessos, não altera apontamentos ou tabelas de recebimentos/fiscalidade. `down()` recusa apagar história. Sem reset/fresh em desenvolvimento. Mesmo instalada futuramente, a aplicação e SQL continuam a impedir custeio operacional nessa base.
|
||||
|
||||
## Concessões propostas — separadas, NÃO aplicadas
|
||||
|
||||
Conferidas por leitura em `scripts/direct-cost-permissions-preview.php`, sem modo de aplicação. Todas ausentes na conferência de 27/10/2026. Âmbito exacto: **tenant #1 / Tempo Lda #1 / SEGI #1**.
|
||||
|
||||
| Conta existente | Proposta |
|
||||
| --- | --- |
|
||||
| Osmane Nala #1, nala@tempo.co.mz | `direct_costs.view`, `direct_costs.prepare` |
|
||||
| Samira Nal #2, onala@me.com | `direct_costs.view`, `direct_costs.validate` |
|
||||
|
||||
São **quatro concessões propostas**, não autorização de aplicação ou activação real. Sem gestão de acessos, supervisão técnica, alteração dos apontamentos, salários, margem, stock ou emissão. Só as identidades equivalentes sintéticas receberam estes direitos nos testes. Técnico/verificador reais continuam sem concessões novas.
|
||||
|
||||
## Encerramento posterior por delegação
|
||||
|
||||
Em 27/10/2026, o utilizador autorizou o encerramento após conferência técnica do percurso e preservação de checkpoint local. Ver [registo de encerramento e limites](WORKSHOP_DIRECT_COST_ACCEPTANCE.md). As referências anteriores a ausência de aceitação presumida descrevem a entrega antes desta autorização; `090000`, quatro concessões e uso operacional real continuam por autorizar/aplicar.
|
||||
|
||||
## Ficheiros e limites
|
||||
|
||||
Núcleo `app/Modules/Workshop/DirectCosts.php`, controlador `Http/DirectCostsController.php`, interface `resources/js/DirectCostsWorkspace.jsx`, integrações em `app.jsx` e `routes/web.php`; migração/SQL acima; `tests/Feature/DirectCostsTest.php`, `tests/Support/DirectCostFixture.php`; scripts `direct-cost-fixture.php`, `direct-cost-worker.php`, `direct-cost-concurrency.php`, `direct-cost-proof.php`, `direct-cost-permissions-preview.php`; esta documentação e provas. Não se alteraram ferramentas/dependências ou o motor fiscal.
|
||||
|
||||
Recorte deliberado de duas origens, uma moeda e uma ordem, sem partilhas entre ordens, custos indirectos, lote, produção em curso, margens, stock ou facturação. Taxas ligadas à versão exacta da origem exigem nova taxa validada para uma correcção técnica; não há tabela universal de salários/custos. Sem PDF/exportação, assinatura digital, activação real ou aceitação presumida. As fotografias/eventos anteriores e todos os bloqueios permanecem preservados.
|
||||
@@ -0,0 +1,244 @@
|
||||
# Oficinas e assistência técnica — âmbito para revisão
|
||||
|
||||
27/10/2026, Africa/Johannesburg. Versão 0.1. **Apenas especificação.** Não autoriza implementação, dados operacionais, acessos, migrações ou publicação.
|
||||
|
||||
## 1. Referências e base preservada
|
||||
|
||||
Directório confirmado: `C:\laragon\www\sgf-tempo`; instruções locais lidas. Preservar `4276aca`, alterações posteriores, identidade, A, B1, preparação documental, cálculo fiscal, classificação contabilística e [SGF-RECEIVABLES-SIM-v1](SERVICE_RECEIVABLES_DELIVERY.md). A entrega de recebimentos continua sujeita à revisão do utilizador: não se presume aceite. Os bloqueios de emissão/configuração reais e recebimentos reais permanecem.
|
||||
|
||||
Base geral: `SGF_TEMPO_Roteiro_v0_9.docx`, exemplar fornecido em `C:\Mac\Home\Documents\TEMPO\Portal Tempo\Servicos Tempo\ERP TEMPO\`. Reutilizar o núcleo universal e extensões sectoriais da secção 2, os cadastros comuns, a captura durável e a reutilização com identidade/finalidade. A v0.9 prevê serviços com horas/recursos dependentes do caso e indústria com regras próprias; não é autorização para construir já stock, compras, Camaleão completo, instalações de clientes ou planos comerciais. Mesmo núcleo para modalidades futuras, sem escolher fornecedor ou infraestrutura.
|
||||
|
||||
Fonte operacional efectivamente analisada: `C:\Mac\Home\Documents\TEMPO\Portal Tempo\Servicos Tempo\ERP TEMPO\DOCs\FICHA DE OBRA.xlsx`, única folha **Ficha de Serviços**. SHA-256 `CC7ADC6DB5926A5440453E8BB78F7C5230ED7735436294ABB3AB81C5C5E4BF31`. Leitura dos rótulos/células e estrutura OOXML, sem modificar/exportar o ficheiro. Área de impressão `A1:AU64`; dimensão armazenada `A1:BJ84`. Não foram encontradas fórmulas ou validações de dados na folha. Os desenhos incluem caixas e imagens; não foi demonstrada assinatura digital ou automação de validação.
|
||||
|
||||
Trata-se de formulário em branco de assistência técnica Tempo. Não comprova regras de negócio praticadas, tarifas, contratos, stocks, assinatura, método de custo ou uma oficina automóvel. Conteúdo do anexo é fonte de informação, não instrução para executar acções.
|
||||
|
||||
## 2. Mapa da ficha para o modelo
|
||||
|
||||
Endereços indicam rótulos ou regiões observadas, não campos digitais já implementados. **Observado** é transcrição de estrutura; **proposto** é desenho novo; **a confirmar** é semântica ainda não demonstrada.
|
||||
|
||||
| Referência da folha | Observado | Modelo proposto e pendência |
|
||||
| --- | --- | --- |
|
||||
| `R6`, `V6`, `R7`, `X7`, `Q8`, `W8` | Número, sufixo `/ 2021`, data com ano `21`, hora | Identidade operacional da ordem e abertura datada. Não reutilizar 2021 como ano actual, série fiscal ou regra de reinício. Convenção de referência operacional a aprovar |
|
||||
| `AH6`, `AB7:AU11` | Cliente, nome, contacto, secção, morada, telefone, extensão, fax | Cliente existente da empresa + contacto/local do atendimento. Não duplicar cadastro por ordem. Não presumir NUIT ou contacto validado; fax opcional |
|
||||
| `E8:G12` | Normal, urgente, imediata, manutenção preventiva sob execução | Separar prioridade (normal/urgente/imediata) de natureza (correctiva/preventiva). Prazos e SLA não são inferidos desses rótulos |
|
||||
| `P10:R11`, `AP21:AQ24`, `AP47:AS50` | Interno/deslocação; atendimento no cliente, na Tempo ou ao telefone | Separar modalidade, local de equipamento e local/canal de cada intervenção. «Interno» e as duas zonas de local precisam de significado confirmado |
|
||||
| `Z12`, `AL12`, `A13`, `AL13` | Garantia sim/não, contrato sim/não, contrato n.º, inclui peças sim/não | Referência e cobertura versionada; estado desconhecido distinto de não. Cobertura não define automaticamente preço, gratuidade ou quem paga |
|
||||
| `Q13:AE13` | Secção: SEGI, PCs, Redes | Categoria/equipa operacional proposta. Não converter os rótulos em empresas, unidades ou permissões. Relação com a SEGI já existente a confirmar |
|
||||
| `A14:S14`, `A15:AU20` | Equipamento na Tempo/no cliente; marca/modelo por unidade, número de série | Bem individual e custódia/localização. A expressão «por unidade» aqui identifica equipamento, não a unidade organizacional do SGF. Primeiro recorte: um bem por ordem |
|
||||
| `AL14`, `A21:AO25` | Preenchida por; avaria ou serviço pretendido | Autor da abertura e pedido original preservado. Diagnóstico e proposta são registos posteriores distintos do relato do cliente |
|
||||
| `A26:AU26` | Trabalho a executar por, recebi, data/hora | Responsáveis e passagem de responsabilidade/custódia. Confirmar quem «recebi» representa; não o tratar como recebimento de dinheiro |
|
||||
| `A28:AU35` | Requisições/componentes/material aplicado; n.º requisição, datas, código, descrição, quantidade, n.º entrega, valor unitário/total, total | Referências de material e acontecimentos separados. «Quantidade» não prova consumo; «valor» não distingue custo/preço, nem mostra moeda/imposto. Não há prova de reserva, devolução ou valorização de stock |
|
||||
| `A37:AU45` | Mão-de-obra, deslocações, técnicos; data, início/fim, S/N, tempo, tempo total, técnico, classe, valor total e rubricas | Intervalos/pausas, deslocações e classificação profissional a propor. `S/N` e «classe» precisam de definição; não presumir tarifa. Hora decorrida não é tempo efectivo ou facturável |
|
||||
| `A46:AO56`, `AP52:AS55` | Relatório técnico; concluído não/sim/com sucesso | Relatório versionado, conclusão técnica e resultado do teste funcional separados. «Com sucesso» exige critério/evidência definidos; não implica aceite ou entrega |
|
||||
| `A58:AU58` | Executado por, assinatura, data | Identificação/evidência de revisão/conclusão. Campo de assinatura em branco não comprova assinatura electrónica ou identidade verificada |
|
||||
| `A61:AU62` | Cliente confirma boa execução, peças, horas e deslocações; nome/assinatura/data | Aceite com pessoa, qualidade em que intervém, data, versão e evidência; distinguir recusa/ressalvas. Não equivale a autorização prévia, pagamento ou recepção automática de factura |
|
||||
| `A64:AU64` | Identificação e contactos Tempo no rodapé | Reutilizar dados aprovados do emitente. Não copiar contactos de um modelo antigo como configuração actual |
|
||||
|
||||
**Campos novos propostos, não observados na ficha:** ID do equipamento, proprietário/custódia, diagnóstico separado, autorização por versão/limite, pausas, tempo efectivo, decisões de facturabilidade, custo interno, moeda explícita, vínculos transaccionais ao rascunho e eventos. Matrícula, quilometragem, chassis, combustível e outros campos de automóvel são extensões opcionais, ausentes deste recorte.
|
||||
|
||||
## 3. Menor percurso útil e entidades
|
||||
|
||||
Primeiro recorte proposto: assistência técnica a um equipamento de um cliente, numa empresa/unidade, uma moeda comercial explícita, tarefas simples, apontamentos manuais verificados e um único rascunho de facturação. Sem gestão automóvel, múltiplos bens na ordem, stock real, compras, agenda optimizada, contratos recorrentes ou assinatura digital.
|
||||
|
||||
| Entidade | Campos e ligações essenciais |
|
||||
| --- | --- |
|
||||
| Ordem de trabalho | ID/ref. operacional, tenant/empresa/unidade, cliente, equipamento, pedido original, abertura, prioridade, natureza, local/canal, responsável, versão, origem da ficha e estado |
|
||||
| Equipamento/bem | ID empresarial, proprietário/cliente, tipo, marca/modelo, série quando conhecida ou identificador interno quando ausente; local, custódia, acessórios/estado de entrada e evidências. Não confundir com activo contabilístico da empresa |
|
||||
| Diagnóstico e proposta | Versão, tarefas/recurso esperado, limites, dependências, pressupostos e eventual orçamento com moeda, quantidades/preços propostos. Custo interno em vista protegida |
|
||||
| Autorização do cliente | Versão exacta da proposta, pessoa/representação, canal, data, evidência, alcance/limite e ressalvas. Quando dispensada segundo política aprovada, guardar fundamento e responsável; ausência não é consentimento |
|
||||
| Tarefa/intervenção | ID, ordem, serviço existente quando compatível, objectivo, técnico, resultado, intervalos/pausas, recursos, versão da autorização abrangente e evidências |
|
||||
| Apontamento de tempo | Técnico/recurso estável, ordem/tarefa, início/fim com zona, pausas, tipo trabalho/deslocação, tempo efectivo verificado e estado; facturabilidade separada |
|
||||
| Material na ordem | Identidade/designação/unidade, proprietário empresa/cliente, origem, quantidades por acontecimento, documento/referência e evidência. Consumo técnico observado não é saída de inventário |
|
||||
| Decisão técnica/comercial | Linhas/versões revistas; quantidade executada/consumida versus facturável, preço, custo com estado conhecido/provisório/em falta/não aplicável, motivo e actor; contrato/garantia/retrabalho/cortesia identificados |
|
||||
| Relatório, aceite e entrega | Relatório técnico versionado, testes/resultados, conclusão; aceite distinto com ressalvas/recusa; entrega física/remota e custódia, destinatário, data/evidência. Nada implica pagamento |
|
||||
| Preparação de facturação | Versão revista da ordem e linhas, IDs de prestação/rascunho existentes ou gerados controladamente, ligações por linha/quantidade, estado da conversão e chave de comando |
|
||||
| Histórico/eventos | Origem/versão, autor, instantes, motivo, âmbito, correlação e schema; aprovação e efeitos ligados ao conteúdo exacto, sem segredos ou dados pessoais desnecessários |
|
||||
|
||||
Cliente e serviços pertencem à empresa e são reutilizados entre unidades autorizadas. Equipamento identificado pela empresa e proprietário, consultável apenas para finalidades/âmbitos permitidos; localizar um equipamento não dá acesso às ordens de outra unidade. A ordem, seus recursos e operações pertencem à unidade e não podem ser transferidos por um campo do formulário. Evitar recolher credenciais de dispositivos, palavras-passe, PINs ou conteúdo pessoal em notas/anexos; descrever apenas evidência necessária.
|
||||
|
||||
## 4. Estados e transições
|
||||
|
||||
Percurso: abertura → diagnóstico/proposta → autorização quando aplicável → execução → revisão técnica/comercial → aceite/entrega → preparação de rascunho. Estados próprios evitam um único «concluído» que esconda trabalho pendente.
|
||||
|
||||
| Dimensão | Estados/transições propostos e condições |
|
||||
| --- | --- |
|
||||
| Ordem operacional | Aberta → em diagnóstico → proposta preparada → autorizada/em execução → execução terminada → em revisão → concluída tecnicamente. Pode aguardar informação/material/cliente com motivo; cancelamento preserva trabalho/custos/evidência já registados |
|
||||
| Autorização | Não avaliada / necessária pendente / autorizada parcialmente ou integralmente / recusada / dispensa fundamentada. Só tarefas cobertas pela versão autorizada/dispensa validada podem iniciar execução |
|
||||
| Tarefa | Planeada → autorizada → em execução/pausada → executada → verificada; não aplicável/cancelada com motivo. Nova tarefa fora do alcance aprovado exige alteração de proposta e decisão própria |
|
||||
| Aceite do cliente | Pendente / aceite / aceite com ressalvas / recusado / não aplicável fundamentado. Conclusão técnica não altera automaticamente este estado |
|
||||
| Entrega/custódia | Não entregue / pronta para entrega / entregue com evidência; atendimento remoto pode ter entrega do resultado ou não aplicabilidade fundamentada. Não deduzir entrega da assinatura de execução |
|
||||
| Facturação | Não revista / pendente de decisão comercial / linhas aprovadas / preparada em rascunho / convertida por ligação. Não mostrar «facturada» por criar rascunho. Emissão continua bloqueada |
|
||||
|
||||
Proposta inicial: conversão só após revisão técnica e comercial concluídas e aceite/entrega resolvidos (incluindo não aplicabilidade fundamentada). Facturar antes de entrega ou sob disputa é extensão sujeita a regra própria, não efeito de urgência. Trabalho urgente não dispensa autorização automaticamente. Alteração material de tarefa, quantidade, limite ou preço gera nova versão e revalidação apenas do que afecta; autorizações antigas não abrangem automaticamente o acréscimo. Garantir possibilidade de guardar diagnóstico/pedido incompletos sem fingir aprovação.
|
||||
|
||||
Conclusão e reabertura técnica exigem actor autorizado, motivo e nova versão. Relatório/aceite históricos não se apagam; novas evidências referem a versão e eventuais ressalvas. Se uma ordem já originou rascunho, a reabertura marca-o desactualizado; nunca reescreve B1, fotografia ou documento emitido de teste.
|
||||
|
||||
## 5. Tempos e deslocações
|
||||
|
||||
- Registar instantes completos, data e zona, com fim posterior ao início, pausas dentro do intervalo e sem sobreposição entre pausas. Intervalo incompleto não é zero horas nem trabalho confirmado. Rejeitar duração negativa e fim anterior; passagem de dia é permitida com datas explícitas.
|
||||
- Tempo efectivo de uma intervenção = união dos intervalos de trabalho verificados menos pausas verificadas; conservar componentes. Mostrar também duração decorrida. Registo manual precisa de origem/autor/validação, não de cronómetro fictício.
|
||||
- Unidade canónica proposta: minuto inteiro; guardar instantes com precisão de segundo e rejeitar confirmação de durações não representáveis nessa unidade até definir política. Conversão para horas usa minutos/60 exactamente; se decimal não finito, conservar razão exacta e mostrar precisão/pendência de representação, sem truncar silenciosamente.
|
||||
- Bloquear dois intervalos activos ou confirmados sobrepostos para o mesmo técnico/recurso entre ordens da mesma empresa, incluindo SQL/concorrência na futura implementação. Trabalho simultâneo real exige repartição documentada cuja soma não exceda o tempo disponível, como extensão. Dois técnicos podem trabalhar em paralelo, cada um com o seu apontamento; somar horas-pessoa, sem duplicar o intervalo individual.
|
||||
- Deslocação tem ID, origem/destino minimizados, técnico/recurso, datas, duração e unidade comercial própria (viagem, tempo, distância apenas se acordada). Não somar o mesmo intervalo como trabalho e deslocação. «Deslocação S/N» não determina custo, tarifa, quilómetros ou quantidade facturável.
|
||||
- Tempo facturável é decisão comercial distinta. Contrato, garantia e retrabalho conservam tempo/custo mesmo quando a quantidade comercial for zero com decisão explícita. Não derivar preço de «classe» sem tabela aprovada/versionada.
|
||||
|
||||
## 6. Materiais, custos e decisão comercial
|
||||
|
||||
| Conceito | Significado e controlo proposto |
|
||||
| --- | --- |
|
||||
| Requerido | Necessidade planeada; não prova disponibilidade, reserva ou custo |
|
||||
| Reservado | Compromisso de disponibilidade por sistema de stock; **indisponível no primeiro recorte**, porque não há stock operacional implementado |
|
||||
| Entregue | Passagem física/custódia documentada à equipa/cliente; não implica instalação ou consumo |
|
||||
| Consumido/aplicado | Observação técnica verificada de utilização na ordem; quantidade positiva, unidade, origem e autor. Não é movimento de inventário confirmado pelo SGF |
|
||||
| Devolvido | Retorno físico de quantidade entregue não utilizada, com destinatário/evidência; não reverte consumo que ocorreu. Rectificar consumo exige operação compensatória própria |
|
||||
|
||||
Para material em custódia verificada na ordem: entregue = consumido + devolvido + remanescente + outras saídas/perdas explicitamente justificadas, na mesma unidade e corte. Enquanto faltar uma parcela/evidência, mostrar divergência ou pendência, não criar reserva/entrada/saída para fechar a soma. Consumo acima do entregue confirmado requer origem suplementar documentada, não sobreposição ou saldo físico negativo oculto. Materiais adquiridos/levados directamente ao cliente requerem origem equivalente; não inventar n.º de requisição.
|
||||
|
||||
Primeiro recorte propõe registo operacional de material observado, com documentos externos ou evidência sintética; sem saldo de armazém, disponibilidade garantida, método de valorização ou encomenda. Futuro stock será dono do movimento físico/económico canónico, e a ordem ligará esse mesmo ID em vez de criar outro consumo. Uma linha de factura não é fonte de saída de material.
|
||||
|
||||
Material da empresa e material fornecido pelo cliente têm propriedade/custódia distintas. Material do cliente não se torna compra, activo ou custo de aquisição da empresa e não se vende por omissão; eventuais custos de manuseamento/intervenção ficam separados. Se precisar de valorização para seguro/custódia, é outra finalidade e regra, não custo de produção ou preço de venda.
|
||||
|
||||
Para cada recurso, guardar separadamente quantidade real verificada, quantidade comercial aprovada, unidade, custo interno unitário/total e fonte/versão/estado, preço proposto/versão e motivo de diferença. Custo ausente é `null` com pendência, não zero. Zero só com fundamento confirmado; preço não substitui custo. Se a soma de custos estiver incompleta, mostrar subtotal conhecido e componentes em falta, sem custo total ou margem completa.
|
||||
|
||||
Contrato, garantia, retrabalho e cortesia identificam um motivo a avaliar: responsável comercial decide cobertura, destinatário da cobrança, quantidades/preço e eventual exclusão. Primeiro recorte só um cliente pagador; cobrança a fabricante/seguradora é extensão. Proposta: quantidade facturável não excede quantidade verificada sem justificação comercial específica; mínimos, pacotes, tarifa fixa ou cobrança por resultado requerem regra própria e não são inventados. Uma quantidade comercial zero exige decisão explícita e conserva custo/consumo.
|
||||
|
||||
## 7. Conversão controlada para rascunho
|
||||
|
||||
1. Rever versão exacta da ordem, autorizações/dispensas, execução verificada, relatório, aceite/entrega, decisão comercial por linha, moeda/unidades e permissões. Fixar revisão com linhas elegíveis e linhas excluídas/motivos. Informação fiscal em falta permanece pendência do rascunho, não imposto zero.
|
||||
2. Converter por comando explícito e idempotente: origem/versão de cada intervenção ou consumo, quantidade comercial aprovada, serviço/descrição/unidade, preço e preparação documental reutilizados. Criar/ligar uma prestação de A e um rascunho de facturação, **sem duplicar execução, apontamentos ou consumo**. A prestação é uma referência comercial derivada, não outro acontecimento técnico.
|
||||
3. Primeiro recorte: uma ordem → uma prestação derivada → um rascunho, com unicidade na base por ordem e por linha de origem seleccionada. Sem agrupamento de ordens ou facturação parcial. Essas extensões exigem quantidades já convertidas/reservadas e concorrência por saldo, não apenas retirar a unicidade.
|
||||
4. Linhas de mão-de-obra/prestações usam catálogo de serviços existente. Materiais exigem tipo de linha comercial compatível; A suporta actualmente linhas de serviço. **Não representar uma peça como serviço fictício só para converter.** Propor delta explícito de tipo de linha material, sem stock nem reconhecimento, antes de executar esse recorte; alternativa de facturação por pacote só se for a realidade comercial aprovada. Esta dependência não está já entregue.
|
||||
5. Transacção única para prestação/rascunho, vínculos de origem, revisão, auditoria, evento e resultado do comando. Mesma chave/conteúdo recupera IDs; chave alterada não duplica a ordem/linha já convertida. Mesmo comando com conteúdo diferente é conflito. Falha antes do commit desfaz o conjunto; resposta perdida após commit recupera o mesmo rascunho.
|
||||
6. Não sincronizar silenciosamente edições posteriores. Alteração da ordem invalida prontidão do rascunho e exige revisão explícita da ligação/versões. Um rascunho modificado comercialmente também torna a revisão anterior incompatível; não permitir contornar origem/quantidade por edição livre. B1 e documentos históricos continuam imutáveis; alteração após confirmação requer novo âmbito, sem duplicar ou renumerar.
|
||||
|
||||
Criar rascunho não emite factura, gera receita contabilística, obrigação exigível ou recebimento. Reutilizar [preparação documental](DOCUMENT_PREPARATION_DELIVERY.md), [pré-visualização](DRAFT_INVOICE_PREVIEW_DELIVERY.md) e suas pendências; não retirar bloqueios fiscais para demonstrar oficina.
|
||||
|
||||
## 8. Responsabilidades e acessos propostos por função
|
||||
|
||||
São funções a designar, sem atribuição automática a Osmane, Samira ou técnicos. A delegação pode ser parametrizada com alcance, vigência e auditoria; não impor número fixo de pessoas nem presumir delegação a partir do login.
|
||||
|
||||
| Função proposta | Acções delimitadas | Exclusões |
|
||||
| --- | --- | --- |
|
||||
| Atendimento | Abrir ordem, ligar cliente/equipamento, registar pedido/custódia e evidência de autorização/entrega | Não confirma cobertura comercial, custos, margem ou assinatura digital |
|
||||
| Responsável técnico | Diagnóstico/proposta técnica, distribuição, validar apontamentos/consumo, concluir/reabrir e validar relatório | Não decide preços/garantia ou concede acesso a custos por ser técnico |
|
||||
| Técnico executor | Consultar ordens atribuídas, registar intervenções/tempos/materiais observados e relatório preliminar | Sem consulta de margens/custos alheios, revisão comercial, conversão ou administração por omissão |
|
||||
| Responsável comercial | Validar cobertura, preço e quantidade facturável, motivos de exclusão; autorizar conversão de linhas revistas | Não valida automaticamente tempo executado, custo ou fiscalidade |
|
||||
| Validador de custos | Conferir custo/fonte/versão e acesso limitado aos dados necessários | Não altera preço, salário de origem ou stock por esta função |
|
||||
| Preparação de facturação | Converter revisão aprovada e consultar vínculos/rascunho com direitos próprios de A/documentais | Sem emissão, recebimentos, acesso a custos ou administração implícitos |
|
||||
| Consulta operacional / análise de custos | Direitos separados para ordem operacional e para custo/margem autorizados | Consulta de ordem não dá dados de remuneração, custo ou margem |
|
||||
|
||||
Catálogo proposto de direitos, cada qual explícito: `work_orders.view/create/assign/diagnose/execute/review_technical/record_authorization/record_acceptance/record_delivery/review_commercial/prepare_billing`; `work_order_costs.view/validate`; `work_order_margins.view`. Âmbito de empresa/unidade e, quando aplicável, atribuição ao técnico. Nomes são proposta técnica, não permissões instaladas. Registar autorização/aceite é conservar evidência, não representar o cliente sem suporte. Acesso aos cadastros empresariais não revela intervenções de outras unidades. Exportações/eventos/modelos de leitura também filtram custos e dados pessoais.
|
||||
|
||||
## 9. Cenário sintético
|
||||
|
||||
Empresa Exemplo, Unidade Técnica, Cliente Exemplo, ordem `OT-TEST-1`, equipamento PC de teste `EQ-1`/série `SER-TEST-1`. Moeda comercial e de custo **MZN explicitamente definida**. Valores inventados apenas para demonstrar o desenho; sem perfil fiscal, stock ou operação real. Pedido: diagnóstico e reparação simples. Proposta v1 autorizada, relatório v1 verificado, aceite e entrega registados separadamente com evidências artificiais.
|
||||
|
||||
| Recurso e unidade | Quantidade executada/consumida | Custo unitário conhecido | Custo conhecido | Quantidade facturável aprovada | Preço unitário proposto, antes de imposto por apurar | Valor comercial proposto |
|
||||
| --- | ---: | ---: | ---: | ---: | ---: | ---: |
|
||||
| Cabo de teste da empresa, UN | 2 | 120,00 | 240,00 | 2 | 180,00 | 360,00 |
|
||||
| Reparação, H | 1,75 | 200,00/H | 350,00 | 1,75 | 600,00/H | 1 050,00 |
|
||||
| Teste adicional, H, não facturável por cortesia expressamente aprovada | 0,25 | 200,00/H | 50,00 | 0 | Não aplicável à linha excluída | 0,00, por decisão comercial |
|
||||
| Deslocação, VIAGEM | 1 | 150,00/VIAGEM | 150,00 | 1 | 200,00/VIAGEM | 200,00 |
|
||||
| Totais deste conjunto de recursos | — | — | **790,00** | — | — | **1 610,00 MZN**, antes de imposto por apurar |
|
||||
|
||||
Reparação: 09:00–11:00, pausa 10:00–10:15 → 105 minutos = 1,75 H. Teste adicional: 11:00–11:15 → 15 minutos; deslocação 11:15–11:45 → 30 minutos, registada separadamente e comercializada por viagem, não como mais 0,5 H de reparação. Não há sobreposição do técnico. Material: 3 UN entregues segundo evidência sintética, 2 consumidas e 1 devolvida; 3 = 2 + 1. Não é movimento de armazém ou confirmação de disponibilidade.
|
||||
|
||||
O custo 790,00 cobre só os quatro recursos do exemplo, não custos indirectos completos. A diferença 1 610 − 790 = 820,00 é diferença sobre custos identificados, **não margem completa comprovada nem lucro**. IVA e total com imposto permanecem por apurar; não aplicar 16% por hábito.
|
||||
|
||||
Variante: custo unitário do cabo desconhecido → custo do cabo pendente, subtotal conhecido 350 + 50 + 150 = **550,00**; custo total e diferença/margem indisponíveis. O preço proposto de 360 não preenche o custo em falta. Material fornecido pelo cliente, se acrescentado, conserva propriedade e evidência, sem preço/custo de aquisição da empresa presumidos.
|
||||
|
||||
## 10. Reutilização concreta e dependências
|
||||
|
||||
| Base existente | Reutilização | O que falta construir |
|
||||
| --- | --- | --- |
|
||||
| Identidade/contexto/empresa/unidade e auditoria | Mesma sessão, pertenças, CSRF, revisão de contexto e direitos explícitos | Direitos sectoriais e atribuição operacional, sem herança automática |
|
||||
| Clientes e serviços de A | IDs e versões empresariais existentes, mesma preparação documental | Bem individual, ordem, intervenções/recursos e ligações comerciais por origem |
|
||||
| Tempos/material | Não foi identificado módulo operacional entregue destas matérias nas entregas consultadas | Registo verificado de tempo/custódia/consumo observado; não declarar stock ou folha salarial existentes |
|
||||
| B1 e documentos/pré-visualização | Fotografias e pendências preservadas; consulta histórica separada | Conversão controlada e, se aprovado, linhas comerciais de material sem stock fictício |
|
||||
| Classificação contabilística | Categorias/associações aprovadas podem ser referidas sob âmbito e vigência | Não resolvem custeio, reconhecimento, IVA ou propriedade do equipamento |
|
||||
| Eventos/outbox/comandos | Reutilizar padrão transaccional, idempotência e histórico, com novos tipos/versões | Eventos de ordem/tempo/consumo/revisão/conversão; nenhum consumidor contabilístico activado |
|
||||
| Recebimentos sintéticos | Preservar entrega e semânticas separadas | Nenhum vínculo automático da ordem/aceite a recebimento, dívida ou reconciliação |
|
||||
|
||||
Reservas/stock, compras, remunerações, contratos/garantias automatizados, assinatura electrónica, múltiplas localizações e tarifários são dependências/extensões, não capacidades presumidas. Referências manuais verificadas podem servir ao primeiro recorte, claramente sem garantia de integração. A base comum de recursos/quantidades/eventos deve ser coordenada com [custos industriais](INDUSTRIAL_COST_ACCOUNTING_SCOPE.md); uma ordem técnica não vira ordem de produção automaticamente.
|
||||
|
||||
## 11. Critérios de aceitação futuros
|
||||
|
||||
- Demonstrar ordem de um equipamento até rascunho sem recapturar cliente, tarefa, tempo, material e preço já aprovados. Linha de cortesia permanece na história e fora do montante facturável.
|
||||
- Ausência de série/equipamento identificável, cobertura, autorização necessária ou decisão comercial produz pendência específica. Guardar pedido incompleto não o declara autorizado ou pronto a facturar.
|
||||
- Conclusão técnica, teste funcional, aceite, entrega e rascunho mantêm estados independentes; recusa/ressalva do cliente não desaparece. Rubrica em formulário não se apresenta como assinatura digital validada.
|
||||
- Intervalos/pausas inválidos, sobreposição individual e duplo cômputo trabalho/deslocação recusados, inclusive entre duas ordens concorrentes. Conversões de unidades exactas, sem arredondamento silencioso.
|
||||
- Quantidades requerida/reservada/entregue/consumida/devolvida distintas; sem stock instalado não apresentar saldo de armazém ou reserva confirmada. Custo desconhecido não vira zero/preço de venda.
|
||||
- Revisão/comando antigo, alteração de autorização, edição posterior da ordem/rascunho e resposta perdida não duplicam prestação, material, rascunho ou vínculo de origem. Converter duas vezes com chaves diferentes também não duplica.
|
||||
- Falha injectada em auditoria/outbox desfaz conversão integral; retry recupera resultado. Histórico confirmado protegido também contra SQL em massa. Nova versão/correcção referencia originais.
|
||||
- Negar URL/API/tarefa para empresa irmã do mesmo tenant, unidade ou ordem não atribuída. Revogação e troca de contexto têm efeito no pedido seguinte. Técnico/consulta operacional não vê custos/margens por respostas API, eventos ou exportação.
|
||||
- Provas futuras só com fixtures sintéticas e `sgf_tempo_test`, login real na instância isolada, guardas preservadas. Não é necessário executar testes para esta especificação documental.
|
||||
|
||||
## 12. Decisões novas e menor incremento proposto
|
||||
|
||||
Proposta **WORKSHOP-ASSISTANCE-DRAFT-v1**: uma ordem/equipamento/cliente/unidade, diagnóstico/proposta versionada, autorização registada com evidência, intervenções/tempos e materiais observados, revisão técnica/comercial, aceite/entrega e conversão única para rascunho. Sem stock/compras/produção, assinatura digital, factura/recebimento ou lançamento. Para materiais na conversão, incluir explicitamente o delta mínimo de tipo de linha comercial ou restringir a conversão a serviços por decisão de âmbito, sem ocultar peças como serviços.
|
||||
|
||||
Decisões que efectivamente alteram o desenho:
|
||||
|
||||
1. **Recorte comercial de materiais:** converter peças discriminadas no rascunho (com delta de linha material) ou começar apenas pelos serviços mantendo materiais como recursos de custo? Recomendação: discriminadas se a ficha representar a prática comercial; não presumir.
|
||||
2. **Autorizações e evidências:** em que casos se exige autorização antes de diagnóstico/execução, quem pode fundamentar dispensa e que evidências de aceite/entrega são admitidas? Proposta: referência documental/manual verificada, sem assinatura digital.
|
||||
3. **Funções e confidencialidade:** designar responsáveis e alcance de ordens atribuídas, revisão técnica/comercial e custo/margem. Nenhuma conta recebe poderes nesta proposta.
|
||||
4. **Semântica da ficha:** confirmar «S/N» de deslocação, «classe» do técnico, «interno», «recebi» e secção SEGI/PCs/Redes apenas quando forem activados; manter campos neutros/pendentes até lá. Não bloqueiam a especificação nem autorizam fórmulas presumidas.
|
||||
|
||||
Referência de numeração operacional, unidade canónica de tempo e regra de revisão da conversão serão fechadas no recorte de execução, sem configurar série fiscal. Não é necessário reabrir as decisões aceites de identidade, contabilidade ou cálculo para aprovar esta componente documental. Nada foi implementado ou alterado nas entregas existentes nesta etapa.
|
||||
|
||||
## 13. Primeiro recorte coordenado — ordem e recursos
|
||||
|
||||
Em 27/10/2026, o utilizador propôs começar pela ordem de oficina com materiais e tempos de origem identificada, para alimentar custos posteriormente sem duplicação. Esta orientação reduz a primeira entrega face a `WORKSHOP-ASSISTANCE-DRAFT-v1`: **não inclui ainda conversão para facturação**. O âmbito técnico abaixo é proposta concreta de delimitação, não ordem de implementação ou concessão de direitos. A aceitação de recebimentos permanece separada.
|
||||
|
||||
### Base partilhada confirmada no desenho
|
||||
|
||||
| Base comum | Registo único | Uso posterior sem recaptura |
|
||||
| --- | --- | --- |
|
||||
| Empresa/unidade, recurso e unidade de medida | Identidades e âmbito explícitos da ocorrência | Filtrar e validar destino da análise; nunca abrir outra unidade por herança |
|
||||
| Material aplicado/devolvido | ID do acontecimento, quantidade, propriedade, ordem/tarefa, data, fonte e versão | Acrescentar valorização e destino de custo ligados ao mesmo ID; não inserir outro consumo |
|
||||
| Tempo de técnico/recurso | Intervalos/pausas e tempo efectivo verificado, com ID e versão | Aplicar taxa/composição de custo futura com fonte própria; não copiar apontamento como outra hora trabalhada |
|
||||
| Origem, histórico e eventos | Referência da evidência, autor, instante, correcções e correlação | Calcular sob versões explícitas; repetição do evento não duplica recurso ou custo |
|
||||
|
||||
Identidade/contexto, clientes/serviços e padrões de auditoria/eventos já existem. Apontamentos de tempo, acontecimentos de material, ordem de oficina e motor industrial continuam por construir. Uma base comum de desenho não significa capacidades já instaladas.
|
||||
|
||||
### Proposta `WORKSHOP-RESOURCE-RECORD-v1`
|
||||
|
||||
1. **Abrir uma ordem** de uma empresa/unidade, um cliente e um equipamento identificados, com pedido, localização, responsável e referência da autorização/evidência quando necessária. Reutilizar cliente e serviço existentes quando aplicáveis. Sem motor de orçamentos/contratos; ausência de autorização necessária mantém pendência e impede apresentar trabalho como autorizado.
|
||||
2. **Registar tarefas/intervenções e tempos**, com técnico, início/fim, pausas, tipo trabalho/deslocação, tempo efectivo e evidência. Aplicar as validações da secção 5, incluindo sobreposição do mesmo recurso entre ordens. Não calcular automaticamente horas facturáveis.
|
||||
3. **Registar materiais observados**, identificando recurso, unidade, proprietário empresa/cliente, fonte e ocorrências de entrega, aplicação e devolução quando efectivamente conhecidas. Informação incompleta fica pendente. Sem reserva, disponibilidade ou movimento de inventário simulado.
|
||||
4. **Rever e verificar os apontamentos** por função autorizada; conservar divergências e versões. Estados mínimos da ordem: aberta, em registo, a aguardar informação, em revisão e registos verificados. Esta última expressão não significa conclusão técnica, aceite, entrega, facturação ou fecho contabilístico.
|
||||
5. **Consultar a ficha e o histórico** com totais de quantidades por unidade e tempos por recurso, separando declarado de verificado. Custos, preços e margens não são calculados nesta entrega. O modelo reserva ligações futuras de valorização, sem preencher custo ausente com zero.
|
||||
|
||||
Cada acontecimento conserva ID estável, versão, empresa/unidade, ordem/tarefa, recurso, quantidade/unidade, data efectiva, data de registo, autor, fonte/evidência e estado de verificação. Correcções referem o original por nova versão/compensação, sem apagar a origem. Futuro custeio referencia `origem + versão + parcela`, não uma cópia física do consumo.
|
||||
|
||||
**Fora deste primeiro recorte:** orçamento completo, garantia/contrato automatizados, revisão comercial/preços, aceite/entrega completos, conversão para prestação/rascunho, linhas materiais de factura, stock/compras, custo industrial, imputação de indirectos, margem, produção, emissão e recebimentos. Essas partes permanecem na visão das secções anteriores; não são dependências ocultas da captura inicial.
|
||||
|
||||
Prova mínima futura: uma ordem/equipamento, um técnico, material com 3 UN entregues, 2 aplicadas e 1 devolvida; trabalho 09:00–11:00 com pausa de 15 minutos, resultando em 105 minutos efectivos. Repetição/falha não duplicam ocorrências; correcção preserva original; sobreposição e acesso cruzado são recusados. Quantidades verificadas ficam prontas para ligação a custos, **sem gerar um cálculo de custo ou produção**. Demonstração proposta exclusivamente sintética em `sgf_tempo_test`.
|
||||
|
||||
Decisões restantes para preparar execução: designar funções/âmbitos de abertura, apontamento e verificação; definir evidência mínima e política de autorização do trabalho; confirmar se a referência simples de material e apontamento manual bastam ao primeiro piloto. Não é necessário escolher agora método industrial, tarifas, margem, regra fiscal ou linha comercial de material. Nenhum acesso é atribuído por este registo; migração/concessões futuras serão apresentadas concretamente antes da aplicação conforme o âmbito que vier a ser autorizado.
|
||||
|
||||
### Responsabilidades e autorização — proposta posterior do utilizador
|
||||
|
||||
Em 27/10/2026, o utilizador propôs o seguinte desenho para este recorte. Esta especificação incorpora a proposta, sem a converter em concessões ou autorização de implementação:
|
||||
|
||||
| Função | Responsabilidade delimitada | Titular / estado |
|
||||
| --- | --- | --- |
|
||||
| Abertura e atribuição | Abrir a ordem, atribuir responsável e registar evidência da autorização do cliente | Osmane, conforme proposta do utilizador; não significa acesso já concedido |
|
||||
| Técnico responsável | Registar tarefas, tempos e materiais das ordens atribuídas | Pessoa real ainda não indicada; identidade sintética própria nos futuros testes |
|
||||
| Verificação técnica dos apontamentos | Verificar/recusar versão exacta dos registos, com motivo e histórico | Outra pessoa autorizada, ainda não indicada; identidade sintética distinta nos futuros testes |
|
||||
|
||||
Samira não recebe supervisão técnica pela sua função contabilística/fiscal ou pelos direitos de recebimentos. A verificação exige identidade diferente do autor do apontamento; atribuir uma ordem não concede automaticamente capacidade de verificar. Todas as funções continuam limitadas à empresa/unidade e às ordens autorizadas, sem custos/margens ou administração implícitos.
|
||||
|
||||
**Evidência mínima de autorização:** quem autorizou e a qualidade em que representa o cliente, data, canal, trabalho abrangido e referência ao comprovativo ou contrato. Ligar ao conteúdo/versão da proposta ou descrição de trabalho revista. O operador que regista a evidência e a pessoa do cliente que autorizou ficam identificados separadamente. A referência isolada a um contrato não prova que o trabalho concreto está coberto.
|
||||
|
||||
Abrir a ordem permite preparar/atribuir o pedido, mas **não autoriza execução**. Trabalho sem cobertura demonstrada mantém pendência; cada alteração ao alcance aprovado conserva autor, data, motivo e nova versão, com autorização complementar quando necessária. Não ampliar silenciosamente a autorização anterior nem apagar o âmbito que já foi executado.
|
||||
|
||||
É possível preparar o desenho e, após autorização de implementação, provar o percurso com funções de abertura, execução e verificação sintéticas distintas, sem escolher titulares reais ou lhes atribuir direitos. Nomes/contas reais do técnico e do verificador permanecem pendentes apenas para aplicação real; não se pede essa identificação como condição de concluir esta especificação. A aceitação de recebimentos permanece independente.
|
||||
|
||||
## 14. Execução técnica posterior e ocorrência já acontecida
|
||||
|
||||
Em 27/10/2026, o utilizador autorizou expressamente executar código e testes do primeiro recorte e acrescentou que bloquear início não pode impedir relatar ocorrência passada para auditoria. Essa ordem substitui as restrições anteriores de etapa apenas documental **somente no âmbito sintético delimitado**. Resultado e limites em [WORKSHOP_RESOURCE_DELIVERY.md](WORKSHOP_RESOURCE_DELIVERY.md).
|
||||
|
||||
O comando de início exige autorização compatível. O relato retrospectivo conserva autor, data, tarefa/versão, origem/evidência e marca de fora do âmbito quando não havia cobertura demonstrada. Nova autorização não reescreve esse relato. Verificador distinto pode reconhecer o facto para auditoria ou recusar; não o promove automaticamente a execução autorizada ou apontamento verificado. Correcção mantém história e exige nova decisão.
|
||||
|
||||
Migração `080000` em desenvolvimento, concessões reais e activação operacional continuam pendentes de autorizações específicas. Não criar técnicos/verificadores reais por suposição. Não altera a aceitação separada de recebimentos, os bloqueios fiscais ou as extensões documentais de custos industriais. Entrega técnica não constitui aceitação do utilizador.
|
||||
@@ -0,0 +1,22 @@
|
||||
# Aceitação — WORKSHOP-RESOURCE-RECORD-v1
|
||||
|
||||
Em 27/10/2026 (Africa/Johannesburg), o utilizador declarou:
|
||||
|
||||
> Aceito a entrega isolada WORKSHOP-RESOURCE-RECORD-v1. Regista a aceitação e cria o checkpoint local, excluindo credenciais e dados reais. Não apliques ainda a migração 080000 nem concessões. Mantém a 070000 e a aceitação de recebimentos separadas.
|
||||
|
||||
Aceitação limitada à entrega e provas descritas em [WORKSHOP_RESOURCE_DELIVERY.md](WORKSHOP_RESOURCE_DELIVERY.md): ordem, atribuição, autorização, tarefas, tempos, materiais e verificação por identidade distinta, exclusivamente no ambiente sintético isolado. O início não autorizado é recusado, mas uma ocorrência passada pode ser relatada para auditoria, permanentemente sinalizada, sem autorização retroactiva ou validação automática.
|
||||
|
||||
Preservam-se os resultados existentes: 41 testes / 832 asserções, seis casos com processos concorrentes, compilação e prova de login real no navegador isolado. A instabilidade observada numa preparação sintética anterior de recebimentos continua documentada; esta aceitação não a apaga nem declara aceite a entrega de recebimentos. Não foram repetidos testes por uma alteração exclusivamente documental.
|
||||
|
||||
## Limites preservados
|
||||
|
||||
- Migração `080000` não aplicada em desenvolvimento; quatro direitos propostos para abertura por Osmane não concedidos.
|
||||
- Técnico e verificador reais por identificar; nenhuma conta ou concessão presumida, incluindo supervisão técnica pela Samira.
|
||||
- Migração `070000` e aceitação de `SGF-RECEIVABLES-SIM-v1` separadas e pendentes.
|
||||
- Bloqueios operacionais, de emissão e configuração reais mantidos; sem stock, custos industriais, facturação, recebimentos reais, lançamentos ou publicação.
|
||||
|
||||
## Checkpoint local
|
||||
|
||||
O commit que contém este registo é o checkpoint desta aceitação, sucessor de `4276aca`. O seu identificador é apresentado na entrega; não se insere o próprio hash no ficheiro que ele identifica.
|
||||
|
||||
Preserva também código e documentação posteriores já existentes de recebimentos e integrações partilhadas, para manter uma árvore coerente, sem lhes atribuir aceitação nem executar as migrações. Fontes, testes e provas sintéticas são versionáveis; credenciais, ambientes, dados operacionais reais e relatórios locais de preservação da base normal ficam excluídos. Nenhum push ou publicação é autorizado.
|
||||
@@ -0,0 +1,130 @@
|
||||
# Oficina — entrega técnica isolada de ordem e recursos
|
||||
|
||||
27/10/2026, Africa/Johannesburg. **WORKSHOP-RESOURCE-RECORD-v1**, conforme [âmbito, secção 13](WORKSHOP_MANAGEMENT_SCOPE.md#13-primeiro-recorte-coordenado--ordem-e-recursos) e precisão posterior sobre ocorrências já acontecidas. Entrega técnica para revisão; **não significa aceitação do utilizador**. Preservados `4276aca`, alterações posteriores e recebimentos, cuja aceitação continua separada. Sem novo checkpoint.
|
||||
|
||||
## Funcional
|
||||
|
||||
- Abertura de ordem com cliente existente e um equipamento individual, localização, pedido, evidência e referência operacional única. Equipamento pode ser reutilizado por ID, sem repetir cadastro por ordem.
|
||||
- Atribuição explícita de técnico com pertença e direitos próprios. Abertura, atribuição e autorização são comandos separados: abrir não autoriza executar. Nenhuma supervisão técnica foi atribuída à Samira.
|
||||
- Tarefas versionadas com origem estável. Serviço existente pode ser referenciado quando compatível; não criar serviço fictício, material/stock ou ordem de produção.
|
||||
- Autorização ligada à versão exacta da tarefa: pessoa que autorizou, qualidade/representação, data, canal, alcance e comprovativo/contrato, separada do operador que registou. Não se declara que a referência comprova assinatura digital ou validade externa.
|
||||
- Início de trabalho exige autorização já registada e compatível. Outra tarefa/versão exige revisão explícita. Autorizações e âmbitos anteriores não são reescritos.
|
||||
- Relato retrospectivo de tempo/material é permitido mesmo sem autorização. O servidor/base marca consumo/execução fora do âmbito; não transforma o relato em autorização ou confirmação automática. Autorização posterior não altera o registo histórico. Uma correcção de ocorrência já sinalizada conserva a excepção.
|
||||
- Verificação/recusa referem a versão exacta, por identidade distinta do autor. Ocorrência fora do âmbito não pode receber `verified`; admite `acknowledged` (facto reconhecido apenas para auditoria) ou `refused`. Reconhecimento não acrescenta tempo/aplicação verificados nem remove a marca de excepção.
|
||||
- Tempos com início/fim, zona, pausas, trabalho/deslocação e minutos efectivos exactos. Pausas inválidas, duração negativa/futura/subminuto não representável e sobreposição do mesmo técnico são recusadas. Técnicos diferentes podem ter intervalos simultâneos.
|
||||
- Materiais com identidade de recurso, unidade, propriedade empresa/cliente, origem, quantidade e ocorrência distinta: requerido, entregue, aplicado/consumido, devolvido. Reserva não é uma opção suportada. Requisição/entrega/devolução não constituem por si autorização de execução ou consumo.
|
||||
- Consulta da ficha, versões, decisões, totais relatados versus verificados e diferenças físicas a explicar. Sem custos, preços, margem, facturação, recibo ou lançamento.
|
||||
|
||||
## Origem, versões e integridade
|
||||
|
||||
Cada apontamento conserva ID, ordem, tipo, origem, versão, predecessor, tarefa/autorização/início quando aplicáveis, técnico, quantidades/unidade ou tempos, datas, autor e evidência. A identidade de origem por ordem/tipo é estável; novas versões são explícitas e não eliminam originais. A verificação antiga permanece associada à versão antiga e não verifica a nova.
|
||||
|
||||
Futuro custeio pode referenciar **ID/versão de origem**, sem criar outra ocorrência de consumo ou hora. Não foi implementado o consumidor industrial nem um repositório universal de recursos. Os eventos de oficina têm schema/causação próprios e não são reclassificados como produção ou acontecimentos financeiros.
|
||||
|
||||
Comando, ordem/apontamento/decisão, auditoria, evento e outbox são transaccionais. Repetição da mesma chave e conteúdo recupera IDs; conteúdo diferente entra em conflito. Uma chave nova não contorna a unicidade de referência/origem. Há testes de rollback de abertura (incluindo equipamento) e de apontamento quando falha o outbox, e replay após resposta perdida.
|
||||
|
||||
SQL: FKs e triggers validam empresa/cliente/equipamento, versão/ordem/tarefa/autorização, atribuição, minutos/pausas, sobreposição, propriedade/unidade de material, autor e decisão. Todas as sete tabelas são append-only, também contra UPDATE/DELETE em massa. Escritores são serializados por linha da empresa; a consulta usa a mesma ordem de bloqueio para uma versão coerente. Não se apresenta este mecanismo como RLS ou capacidade de escala de produção. SQL administrativo continua uma fronteira de confiança distinta da identidade autenticada na aplicação.
|
||||
|
||||
Sessão, CSRF, pertenças, unidade, direito específico e atribuição são revalidados no servidor e dentro do comando. Técnicos vêem apenas ordens actualmente atribuídas; abertura/verificação têm consulta delimitada à unidade autorizada. Listas de clientes são limitadas às ordens visíveis salvo função de abertura; lista de técnicos apenas para quem atribui. Revogar acesso tem efeito no pedido seguinte, inclusive em replay.
|
||||
|
||||
## Bloqueio operacional
|
||||
|
||||
`WorkshopWorkflow::guard()` exige `testing`/`browser-testing` e `TestingDatabaseGuard` confirma `sgf_tempo_test`, cluster próprio 127.0.0.1:55432, utilizador de testes e ligação efectiva. A consulta normal apresenta bloqueio/listas vazias para quem tiver direito, sem depender de as tabelas novas existirem. Não há flag para activar utilização real.
|
||||
|
||||
Os INSERT nas tabelas `wo_*` têm também guarda SQL de base `sgf_tempo_test` e porta 55432. Não se criaram ordens, equipamentos, contas ou concessões reais. `ServiceInvoicing::guard()`, cálculo fiscal, B1 e recebimentos não foram alterados. Sem acesso ao InvesteMoz, alterações globais ou dependências novas.
|
||||
|
||||
## Demonstração no navegador e provas
|
||||
|
||||
Edge, `http://127.0.0.1:8001`, sessão/cache isolados e CSRF activo. Login real com três identidades artificiais distintas; não se usou `actingAs` como prova de login. Credenciais aleatórias ficam no ficheiro local protegido do preparador, nunca neste relatório.
|
||||
|
||||
1. **Abertura:** gestor sintético entrou em Empresa Horizonte — Demonstração / Unidade Central — Demonstração / **Oficina de teste**. Abriu `OT-BROWSER-ABERTA` com cliente/equipamento/pedido/evidência, sem autorização implícita.
|
||||
2. **Origem do caso principal:** a fixture preparou `OT-TEST-PRINCIPAL`, atribuição, tarefa e autorização pelos comandos de negócio. Usou relógio artificial apenas no processo CLI, no dia anterior às 08:00; restaurou-o no fim. Não alterou relógio do sistema, servidor normal ou política fiscal. Não pré-criou tempos/materiais.
|
||||
3. **Técnico:** login separado, só ordem atribuída visível; relato de 09:00–11:00 no dia da fixture, pausa 10:00–10:15 → **105 MIN**. Depois registou material `CABO-TEST`: **3 UN entregues, 2 aplicadas e 1 devolvida**, com três origens distintas. Não foram movimentos de stock.
|
||||
4. **Âmbito:** acrescentou tarefa ainda não autorizada. **Iniciar trabalho autorizado** foi recusado. Apesar disso, conseguiu relatar uma ocorrência material passada para essa tarefa; ficou **FORA DO ÂMBITO AUTORIZADO**, com origem e diferença física pendente.
|
||||
5. **Verificador:** terceiro login, sem registo técnico/abertura. Verificou tarefa, tempo e materiais principais. Totais: **105 MIN verificados**, aplicação verificada **2 UN**. Reconheceu a ocorrência fora do âmbito apenas para auditoria; aplicação verificada dessa ocorrência continua zero.
|
||||
6. **Autorização posterior:** gestor registou uma autorização específica adicional. A ocorrência das 11:00 continuou fora do âmbito e a decisão de auditoria não mudou; nada ganhou cobertura retroactiva.
|
||||
7. **Recusa:** técnico registou `TEST-REVIEW-REFUSAL`; verificador recusou com fundamento «Descrição insuficiente; corrigir o apontamento antes de o verificar». Original e decisão preservados. Correcções, versões antigas e recuperação são cobertas também por testes e processos concorrentes.
|
||||
|
||||
[Prova completa no navegador](proofs/workshop-browser.png), [resumo visual](proofs/workshop-browser-summary.png), [resultados conferidos](proofs/workshop-browser-results.json) e [concorrência](proofs/workshop-concurrency.json).
|
||||
|
||||
O caso adicional sem entrega documentada mostra diferença observada de −1 UN e pendência, não saldo negativo de armazém ou material automaticamente disponibilizado. Somas são dos apontamentos registados; ausência de ocorrência de entrega não prova que a quantidade física real foi zero. A verificação reconhece evidência de teste, não certificação externa.
|
||||
|
||||
## Testes, concorrência e compilação
|
||||
|
||||
Resultados finais em [workshop-tests.json](proofs/workshop-tests.json). Filtro relevante: `WorkshopTest|ServiceReceivablesTest|InternalConfirmationTest|DatabaseSafetyTest`. A regressão inclui recebimentos, preservando a sua aceitação separada; não repete toda a investigação fiscal ou suites sem relação.
|
||||
|
||||
Resultado final: **41 testes, 832 asserções, zero falhas/erros**. Oficinas isoladamente: **11 testes, 243 asserções**. Compilação aprovada com Vite 8.3.5, sem novas dependências.
|
||||
|
||||
Numa execução anterior da regressão houve uma recusa de hash de revisão desactualizada na preparação de factura sintética de `ReceivablesFixture`, antes do cenário de recebimentos. A repetição com o mesmo código passou integralmente; a causa da intermitência não foi demonstrada. Regista-se esta limitação sem afrouxar a guarda de revisão ou alterar o núcleo fiscal.
|
||||
|
||||
Cobertura: início sem autorização, relato retrospectivo auditável, autorização posterior e alteração de tarefa/versão, auto-verificação, recusa e nova versão, imutabilidade SQL, valores/unidades/pausas inválidos, sobreposição individual e simultaneidade de técnicos distintos, contexto antigo, empresa irmã/unidade não autorizada, revogação, destino de teste incorrecto, ambiente normal/CLI, idempotência, falhas de outbox e recuperação sem duplicação.
|
||||
|
||||
Seis provas com dois processos realmente sobrepostos:
|
||||
|
||||
- Mesma abertura → uma ordem e um replay.
|
||||
- Mesmo apontamento → uma inserção e um replay.
|
||||
- Tempos incompatíveis do mesmo técnico → um aceite e um conflito.
|
||||
- Mesma verificação → uma decisão e um replay.
|
||||
- Nova versão versus decisão sobre a antiga → uma revisão vencedora e recusa da decisão antiga.
|
||||
- INSERT SQL em ordens diferentes, com o mesmo técnico/intervalo → guarda de sobreposição recusa o segundo, sem depender apenas da revisão da mesma ordem.
|
||||
|
||||
A prova SQL insere dados deliberadamente por via administrativa para testar invariantes; não representa comandos de aplicação auditados. Todos os casos são sintéticos. A instância do navegador é parada antes dos testes finais, que recriam só a base de testes; imagens/resultados preservam a prova e os IDs não são fixos numa repetição.
|
||||
|
||||
## Repetição local isolada
|
||||
|
||||
```powershell
|
||||
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/sgf.ps1 test '--filter=WorkshopTest|ServiceReceivablesTest|InternalConfirmationTest|DatabaseSafetyTest'
|
||||
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/sgf.ps1 npm run build
|
||||
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/browser-proof.ps1 start
|
||||
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/sgf.ps1 php scripts/workshop-fixture.php --env=testing
|
||||
```
|
||||
|
||||
No navegador seleccionar o contexto acima e **Oficina de teste**. Usar os utilizadores sintéticos `gestor@example.test`, `tecnico-oficina@example.test` e `verificador-oficina@example.test`, com credencial gerada no preparador protegido. Não usar contas reais ou revelar credenciais. A data da fixture está no manifesto local; preencher o intervalo do dia anterior como indicado na prova.
|
||||
|
||||
Para concorrência, executar `sgf.ps1 php scripts/workshop-concurrency.php --env=testing`. Para conferir os resultados depois de repetir o percurso descrito, `sgf.ps1 php scripts/workshop-proof.php --env=testing`. Os preparadores recusam estado já preenchido e não apagam dados para prosseguir. Terminar a instância com `powershell -NoProfile -ExecutionPolicy Bypass -File scripts/browser-proof.ps1 stop` antes de testes destrutivos. Portas ocupadas não autorizam parar processos alheios.
|
||||
|
||||
## Migração em desenvolvimento — delta proposto, NÃO aplicado
|
||||
|
||||
**`2026_10_27_080000_create_workshop_resource_records.php`**, SQL em `database/sql/workshop.sql`, confirmado **Pending** por leitura de `migrate:status` em `sgf_tempo_dev`.
|
||||
|
||||
Cria sete tabelas: `wo_equipment` (identidade individual), `wo_orders` (abertura), `wo_entries` (atribuições/tarefas/autorizações/inícios/tempos/materiais versionados), `wo_decisions` (verificações), `wo_commands` (idempotência), `wo_events` e `wo_outbox`. Acrescenta FKs, índices e funções/triggers próprios de integridade, ambiente e imutabilidade. Amplia o CHECK de permissões com seis nomes `workshop.*` exclusivamente de unidade, preservando alternativas existentes. Não atribui direitos ou altera tabelas operacionais anteriores. Não há `down()` destrutivo.
|
||||
|
||||
**Só aplicar em `sgf_tempo_dev` após confirmação específica**, com proprietário separado e comparação de integridade antes/depois; sem reset/fresh. Mesmo instalada, a guarda SQL e de aplicação continua a impedir uso operacional nessa base.
|
||||
|
||||
**Atenção ao âmbito do comando futuro:** `070000` de recebimentos também está pendente e não foi autorizada nesta tarefa. Não executar uma migração geral que aplique ambas por arrasto. Uma eventual autorização apenas de oficina exige execução dirigida ao ficheiro `080000`, com o proprietário de migração e destino conferidos. Esta entrega não modificou o wrapper ou executou esse comando.
|
||||
|
||||
## Permissões propostas — separadas, nenhuma concedida
|
||||
|
||||
Pré-visualização read-only disponível em `scripts/workshop-permissions-preview.php`, sem modo de aplicação. Conferência em 27/10/2026: conta #1 Osmane Nala, nala@tempo.co.mz; tenant #1, Tempo Lda #1, SEGI #1. Nenhum dos quatro direitos abaixo estava atribuído.
|
||||
|
||||
| Função / titular | Proposta, sempre na unidade autorizada | Aplicação real |
|
||||
| --- | --- | --- |
|
||||
| Abertura — Osmane #1, Tempo Lda #1 / SEGI #1 | `workshop.view`, `workshop.open`, `workshop.assign`, `workshop.authorize` | Quatro concessões propostas; confirmação específica antes de aplicar |
|
||||
| Técnico responsável | `workshop.view`, `workshop.record`, condicionados à atribuição actual | Conta real ainda não identificada; nenhuma conta criada ou proposta nominal inventada |
|
||||
| Verificador distinto do autor | `workshop.view`, `workshop.verify` | Conta real ainda não identificada; não atribuir à Samira por consequência das suas funções actuais |
|
||||
|
||||
Não incluem gestão de acessos, custos/margens, stock, fiscalidade ou emissão. Técnicos/verificadores sintéticos foram criados só na base de testes com esta matriz explícita. Conceder os direitos no futuro não retira o bloqueio operacional; activação real exige outro âmbito específico.
|
||||
|
||||
## Aceitação posterior
|
||||
|
||||
Entrega isolada aceite expressamente pelo utilizador em 27/10/2026. Ver [registo de aceitação e limites do checkpoint](WORKSHOP_RESOURCE_ACCEPTANCE.md). A aceitação não aplica migrações ou concessões, não activa uso operacional e não abrange a aceitação de recebimentos. A referência anterior a ausência de aceitação presumida descreve correctamente a entrega antes desta confirmação.
|
||||
|
||||
## Aplicação específica posterior em desenvolvimento — 27/10/2026
|
||||
|
||||
Após autorização específica do utilizador, foi aplicada **apenas** `2026_10_27_080000_create_workshop_resource_records` em `sgf_tempo_dev`, por caminho explícito, com `sgf_dev_owner` separado da aplicação. O registo de migrações acrescentou exactamente essa entrada; `070000` permanece pendente. As indicações anteriores de migração/concessões pendentes descrevem o estado anterior a esta autorização.
|
||||
|
||||
Foram concedidos exactamente quatro direitos à conta existente Osmane #1, tenant #1 / Tempo Lda #1 / SEGI #1: `workshop.view`, `workshop.open`, `workshop.assign`, `workshop.authorize`. Cada concessão foi auditada. Não se criaram contas ou direitos para técnico/verificador, nem direitos de registo/verificação ou gestão de acessos.
|
||||
|
||||
O procedimento `scripts/workshop-dev-install.php` comparou em memória as impressões dos registos preexistentes antes/depois, incluindo acessos e auditoria anteriores. Só se acrescentaram o registo da migração, quatro concessões e quatro eventos de auditoria. As sete tabelas novas estão vazias. O resumo local fica em `storage/app/private/workshop-dev-install-proof.json`, excluído do Git; não exporta conteúdos dos registos ou credenciais.
|
||||
|
||||
Verificação no papel normal `sgf_dev_app`: listagem bloqueada e vazia; guarda, abertura, registo e verificação recusados com 403; `sgf_wo_environment()` recusou a base de desenvolvimento; emissão real continua recusada. Não se inseriram ordens ou apontamentos de demonstração em desenvolvimento. Não foram alterados código funcional, ferramentas ou dependências, pelo que não se repetiu a demonstração aceite ou a compilação. O procedimento de instalação é deliberadamente não repetível sem revisão do estado.
|
||||
|
||||
O checkpoint aceite `21a91f2` mantém-se preservado. Esta aplicação não aceita recebimentos, não activa utilização operacional, não implementa custos industriais e não autoriza publicação.
|
||||
|
||||
## Ficheiros e limites
|
||||
|
||||
Principais alterações: `app/Modules/Workshop/WorkshopWorkflow.php`, `Http/WorkshopController.php`, `resources/js/WorkshopWorkspace.jsx`, integração em `resources/js/app.jsx` e `routes/web.php`; migração/SQL acima; `tests/Support/WorkshopFixture.php`, `tests/Feature/WorkshopTest.php`; scripts `workshop-fixture.php`, `workshop-worker.php`, `workshop-concurrency.php`, `workshop-proof.php` e `workshop-permissions-preview.php`; documentação/provas desta entrega.
|
||||
|
||||
Limites: um cliente/equipamento por ordem, tarefas simples e autorização por versão de tarefa; tempos completos em minutos, sem apontamentos subminuto ou timer geral; UI recebe uma pausa, API várias; conservadoramente, todo o intervalo individual está ocupado, mesmo durante pausa. Outro técnico pode trabalhar em simultâneo. Correcções de tarefa/tempo/material pelo próprio autor actualmente atribuído; não há edição histórica por supervisor ou transferência silenciosa de autoria. Interface inicial abre equipamento novo; reutilização por ID suportada na API, sem editor completo de cadastro.
|
||||
|
||||
Não há stock, disponibilidade, valorização, custos industriais, tarifas, horas facturáveis, orçamento/contrato automatizado, aceite/entrega completos, assinatura digital, conversão comercial, factura, recebimento, receita, lançamento ou fecho. Dados/evidências são declarados pelo operador; a aplicação não comprova externamente a representação do cliente ou a autenticidade do documento. Pendências reais e conformidade permanecem como estavam. Não houve publicação ou aceitação presumida.
|
||||
|
After Width: | Height: | Size: 67 KiB |
|
After Width: | Height: | Size: 89 KiB |
|
After Width: | Height: | Size: 80 KiB |
|
After Width: | Height: | Size: 82 KiB |
@@ -0,0 +1,16 @@
|
||||
{
|
||||
"environment": "sgf_tempo_test only",
|
||||
"parallel_php_processes": true,
|
||||
"company_lock_overlap": true,
|
||||
"identical_create": {
|
||||
"same_record": true,
|
||||
"second_replayed": true,
|
||||
"events_created": 1
|
||||
},
|
||||
"concurrent_edit": {
|
||||
"first_status": 200,
|
||||
"second_status": 409,
|
||||
"version_after": 2,
|
||||
"events_created": 1
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,18 @@
|
||||
{
|
||||
"database": "sgf_tempo_test",
|
||||
"counts": {
|
||||
"a_clients": 3,
|
||||
"a_services": 1,
|
||||
"a_service_drafts": 1,
|
||||
"a_billing_drafts": 1,
|
||||
"a_history": 9,
|
||||
"a_events": 9,
|
||||
"a_outbox": 9,
|
||||
"a_pending": 9,
|
||||
"a_commands": 9
|
||||
},
|
||||
"events_without_outbox": 0,
|
||||
"outbox_states": [
|
||||
"captured"
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,10 @@
|
||||
{
|
||||
"environment": "browser-testing / sgf_tempo_test only",
|
||||
"results": [
|
||||
"Criação repetida recupera o mesmo registo/evento; conteúdo diferente com a mesma chave é recusado (409).",
|
||||
"Consulta por credenciais reais sintéticas: leitura 200, edição e gestão 403.",
|
||||
"Concessão/revogação de edição têm efeito no pedido seguinte, mantendo a mesma sessão.",
|
||||
"Versão antiga e contexto antigo recusados (409); alteração sem protecção CSRF/origem recusada (419).",
|
||||
"Cookie anterior à saída não recupera acesso aos dados de A (401)."
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,11 @@
|
||||
{
|
||||
"database": "sgf_tempo_dev",
|
||||
"confirmed_grants_applied": 4,
|
||||
"company_id": 1,
|
||||
"proposer_id": 1,
|
||||
"validator_id": 2,
|
||||
"no_unit_grants": true,
|
||||
"prior_grants_unchanged": true,
|
||||
"business_records_and_calculation_files_unchanged": true,
|
||||
"real_classification_rows": 0
|
||||
}
|
||||
@@ -0,0 +1,21 @@
|
||||
{
|
||||
"database": "sgf_tempo_test",
|
||||
"url": "http://127.0.0.1:8001",
|
||||
"real_session_login": true,
|
||||
"synthetic_distinct_users": true,
|
||||
"csrf_active": true,
|
||||
"observed": [
|
||||
"Preparer created and submitted category v2 with explicit replacement and start 2026-11-01.",
|
||||
"Before approval, consultation for 2026-11-01 still resolved category v1.",
|
||||
"Validator had decision controls without preparation, correction or capture controls.",
|
||||
"Validator approved v2 with reason and refused another submitted category with reason.",
|
||||
"Consultation for 2026-10-31 returned category v1; 2026-11-01 returned v2.",
|
||||
"Operation historical resolution retained category v1, service/plan/account versions and original reference date."
|
||||
],
|
||||
"new_real_grants_applied": false,
|
||||
"screenshots": [
|
||||
"accounting-validation.png",
|
||||
"accounting-history.png"
|
||||
],
|
||||
"credentials": "omitted"
|
||||
}
|
||||
@@ -0,0 +1,10 @@
|
||||
{
|
||||
"database": "sgf_tempo_test",
|
||||
"parallel_processes": true,
|
||||
"lock_overlap_observed": true,
|
||||
"statuses": [
|
||||
200,
|
||||
409
|
||||
],
|
||||
"decisions": 1
|
||||
}
|
||||
@@ -0,0 +1,13 @@
|
||||
{
|
||||
"database": "sgf_tempo_dev",
|
||||
"existing_data_hashes_unchanged": true,
|
||||
"existing_grants_unchanged": true,
|
||||
"calculation_files_unchanged": true,
|
||||
"new_table_counts": {
|
||||
"ca_proposals": 0,
|
||||
"ca_submissions": 0,
|
||||
"ca_decisions": 0,
|
||||
"ca_resolutions": 0,
|
||||
"ca_commands": 0
|
||||
}
|
||||
}
|
||||
|
After Width: | Height: | Size: 62 KiB |
|
After Width: | Height: | Size: 65 KiB |
|
After Width: | Height: | Size: 96 KiB |
|
After Width: | Height: | Size: 100 KiB |
@@ -0,0 +1,14 @@
|
||||
{
|
||||
"database": "sgf_tempo_test",
|
||||
"confirmations": 4,
|
||||
"histories": 4,
|
||||
"confirmation_events": 4,
|
||||
"captured_outbox": 4,
|
||||
"missing_history": 0,
|
||||
"fiscal_states": [
|
||||
"not_issued"
|
||||
],
|
||||
"accounting_states": [
|
||||
"blocked_pending"
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,21 @@
|
||||
{
|
||||
"database": "sgf_tempo_test",
|
||||
"results": {
|
||||
"same_key": {
|
||||
"parallel_processes": true,
|
||||
"company_lock_overlap": true,
|
||||
"same_confirmation": true,
|
||||
"new_confirmations": 1,
|
||||
"new_events": 1,
|
||||
"second_replayed": true
|
||||
},
|
||||
"different_keys": {
|
||||
"parallel_processes": true,
|
||||
"company_lock_overlap": true,
|
||||
"same_confirmation": true,
|
||||
"new_confirmations": 1,
|
||||
"new_events": 1,
|
||||
"second_replayed": true
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,12 @@
|
||||
{
|
||||
"database": "sgf_tempo_test",
|
||||
"real_synthetic_login": true,
|
||||
"results": [
|
||||
"Confirmation authorized; reader denied 403.",
|
||||
"Old context and version denied 409.",
|
||||
"Identical command recovers confirmation; different content conflicts 409.",
|
||||
"Snapshot unchanged after client/service edits.",
|
||||
"Confirmed draft edit denied 409; reader consultation 200.",
|
||||
"Currency remains unknown, tax/accounts/recognition pending; captured, not issued or accounted."
|
||||
]
|
||||
}
|
||||
|
After Width: | Height: | Size: 59 KiB |
|
After Width: | Height: | Size: 60 KiB |
|
After Width: | Height: | Size: 66 KiB |
@@ -0,0 +1,46 @@
|
||||
{
|
||||
"database": "sgf_tempo_test",
|
||||
"url": "http://127.0.0.1:8001",
|
||||
"real_synthetic_login": true,
|
||||
"context": "Empresa Horizonte — Demonstração / Unidade Central — Demonstração",
|
||||
"policy": "SGF-SERVICE-NET-VAT-TRUNCATE2-v1",
|
||||
"observed": [
|
||||
{
|
||||
"base": "100",
|
||||
"vat_exact": "16",
|
||||
"vat_proposed": "16.00",
|
||||
"difference": "0",
|
||||
"total": "116.00",
|
||||
"screenshot": "calculation-100.png"
|
||||
},
|
||||
{
|
||||
"base": "1000.03",
|
||||
"vat_exact": "160.0048",
|
||||
"vat_proposed": "160.00",
|
||||
"difference": "0.0048",
|
||||
"total": "1160.03",
|
||||
"repeat_same_result": true,
|
||||
"screenshot": "calculation-1000.png"
|
||||
},
|
||||
{
|
||||
"base": "0.03",
|
||||
"vat_exact": "0.0048",
|
||||
"vat_proposed": "0.00",
|
||||
"difference": "0.0048",
|
||||
"total": "0.03",
|
||||
"screenshot": "calculation-small.png"
|
||||
},
|
||||
{
|
||||
"base": "0.0001",
|
||||
"vat_exact": "0.000016",
|
||||
"vat_proposed": "0.00",
|
||||
"difference": "0.000016",
|
||||
"total": null,
|
||||
"base_representation_pending": true,
|
||||
"screenshot": "calculation-base-pending.png"
|
||||
}
|
||||
],
|
||||
"permanent_notice_observed": true,
|
||||
"synthetic_label_observed": true,
|
||||
"credentials": "omitted"
|
||||
}
|
||||
@@ -0,0 +1,8 @@
|
||||
{
|
||||
"database": "sgf_tempo_test",
|
||||
"two_php_processes": true,
|
||||
"lock_overlap_observed": true,
|
||||
"same_result_id": true,
|
||||
"one_insert_one_replay": true,
|
||||
"result_count": 1
|
||||
}
|
||||
@@ -0,0 +1,22 @@
|
||||
{
|
||||
"database": "sgf_tempo_dev",
|
||||
"existing_tables_compared": [
|
||||
"a_clients",
|
||||
"a_services",
|
||||
"a_service_drafts",
|
||||
"a_billing_drafts",
|
||||
"a_history",
|
||||
"a_events",
|
||||
"a_outbox",
|
||||
"a_pending",
|
||||
"b_internal_confirmations",
|
||||
"doc_records",
|
||||
"doc_history",
|
||||
"document_preview_models",
|
||||
"document_preview_model_history",
|
||||
"permission_grants"
|
||||
],
|
||||
"identical_counts_and_content_hashes": true,
|
||||
"new_profiles": 0,
|
||||
"new_results": 0
|
||||
}
|
||||
|
After Width: | Height: | Size: 57 KiB |
|
After Width: | Height: | Size: 59 KiB |
|
After Width: | Height: | Size: 38 KiB |
@@ -0,0 +1,35 @@
|
||||
{
|
||||
"policy": "WORKSHOP-DIRECT-COST-SIM-v1",
|
||||
"database": "sgf_tempo_test",
|
||||
"synthetic_only": true,
|
||||
"real_browser_login": true,
|
||||
"csrf_enabled": true,
|
||||
"distinct_cost_roles": true,
|
||||
"original_workshop_entries": 7,
|
||||
"technical_events_not_duplicated": true,
|
||||
"entry_versions": [
|
||||
{
|
||||
"id": 4,
|
||||
"version": 1
|
||||
},
|
||||
{
|
||||
"id": 6,
|
||||
"version": 1
|
||||
}
|
||||
],
|
||||
"full_selected_direct": {
|
||||
"material": "100",
|
||||
"labour": "175",
|
||||
"known_subtotal": "275",
|
||||
"complete_cost_claimed": false
|
||||
},
|
||||
"missing_material_rate": {
|
||||
"known_subtotal": "175",
|
||||
"selected_total": null,
|
||||
"incomplete": true,
|
||||
"pending": true
|
||||
},
|
||||
"both_exact_versions_approved": true,
|
||||
"real_grants_applied": false,
|
||||
"development_migration_applied": false
|
||||
}
|
||||
@@ -0,0 +1,13 @@
|
||||
{
|
||||
"database": "sgf_tempo_test",
|
||||
"overlapping_processes_per_case": 2,
|
||||
"checks": {
|
||||
"rate_repetition_one_version": true,
|
||||
"decision_repetition_one_effect": true,
|
||||
"competing_rate_versions_one_winner": true,
|
||||
"calculation_repetition_one_snapshot": true,
|
||||
"competing_calculations_one_revision": true,
|
||||
"new_calculation_refuses_old_approval": true
|
||||
},
|
||||
"synthetic_only": true
|
||||
}
|
||||
|
After Width: | Height: | Size: 67 KiB |
@@ -0,0 +1,21 @@
|
||||
{
|
||||
"policy": "WORKSHOP-DIRECT-COST-SIM-v1",
|
||||
"date": "2026-10-27",
|
||||
"database": "sgf_tempo_test",
|
||||
"filter": "DirectCostsTest|WorkshopTest|ServiceReceivablesTest|InternalConfirmationTest|DatabaseSafetyTest",
|
||||
"tests": 49,
|
||||
"assertions": 1010,
|
||||
"failures": 0,
|
||||
"errors": 0,
|
||||
"direct_cost_test_cases": 8,
|
||||
"overlapping_process_cases": 6,
|
||||
"junit_local_ignored": "storage/app/direct-cost-tests.xml",
|
||||
"build": {"command": "scripts/sgf.ps1 npm run build", "vite": "8.3.5", "passed": true},
|
||||
"browser_real_login": true,
|
||||
"browser_server_stopped_before_final_tests": true,
|
||||
"development_migration_090000_applied": false,
|
||||
"real_cost_grants_applied": false,
|
||||
"operational_and_fiscal_blocks_preserved": true,
|
||||
"fiscal_and_workshop_core_unchanged_from": "7628645",
|
||||
"user_acceptance": false
|
||||
}
|
||||