SGF/docs/WORKSHOP_BILLING_DELIVERY.md

# Oficina → rascunho — entrega técnica em verificação

**Actualização posterior:** `110000` e sete concessões do orçamento foram entretanto aplicadas por autorização específica separada em 28/10/2026, preservando `120000` e todos os bloqueios. Ver [registo de aplicação do orçamento](INDUSTRIAL_BUDGET_DELIVERY.md). As menções abaixo à sua instalação pendente são históricas; não decorreu desta aplicação qualquer utilização real.

## Aplicação técnica especificamente autorizada — 28/10/2026

Após apresentação da migração, destino e seis concessões exactas, o utilizador confirmou «autorizo». Executado `scripts/sgf.ps1 php scripts/workshop-billing-dev-install.php --apply-confirmed-120000-and-six-grants`. Apenas `2026_10_28_120000_create_workshop_billing_drafts.php` aplicada em `sgf_tempo_dev`/55432 por ligação temporária `sgf_dev_owner`, sem superutilizador, criação de bases/papéis ou bypass RLS. A aplicação mantém `sgf_dev_app`. Migração e concessões verificadas na mesma transacção de instalação; ligação de proprietário removida da configuração em memória no fim.

- 74 tabelas preexistentes conferidas por contagens/impressões digitais, sem exportar conteúdos; dados, acessos e migrações anteriores preservados. Apenas uma entrada no histórico de migrações, seis concessões e seis entradas de auditoria acrescentadas.
- Tenant #1 / Tempo Lda #1 / SEGI #1: conta #1 `workshop_billing.view`, `workshop_billing.prepare`, `workshop_billing.generate`; conta #2 `workshop_billing.view`, `workshop_billing.review`, `workshop.view`. Contas/pertenças e pré-requisitos existentes conferidos, sem nomes/emails ou credenciais no instalador. Nenhum direito de verificação técnica ou supervisão atribuído.
- Sete tabelas `wb_*` novas vazias; nenhum cliente, ordem, origem, preço, proposta, decisão comercial, prestação ou rascunho criado em desenvolvimento.
- Listagens das duas contas permanecem bloqueadas, sem ordens de conversão. Guarda, preparação, revisão e geração recusam com 403; também recusam as guardas de oficinas, custo directo, custo industrial, recebimentos e emissão. Guardas SQL de ambiente industrial/oficina/custo directo/recebimentos recusam desenvolvimento, incluindo a guarda usada pelas sete tabelas novas.
- `110000` permanece não aplicada e fora do caminho executado. As sete concessões do orçamento continuam separadas, sem autorização de aplicação.
- Fontes funcionais/guardas preservadas. Sintaxe do instalador aprovada; verificações de preservação e bloqueios executadas antes do commit transaccional e repetidas com o papel da aplicação após a instalação. Sem repetir testes que recriam a fixture manual aceite.

Prova local em `storage/app/private/workshop-billing-dev-install-proof.json`, sem conteúdos de registos ou credenciais; não incluída no repositório. Aceitação `3932b94` e respectivas limitações de capturas permanecem preservadas. As referências abaixo a `120000`/seis concessões não aplicadas são históricas. Esta instalação não habilita utilização real, confirmação, emissão, stock, recebimentos, lançamentos ou publicação. Nenhum novo checkpoint é declarado por esta actualização.

**Aceitação posterior de 28/10/2026:** utilizador aceitou a entrega com a limitação de capturas e autorizou checkpoint exclusivamente local. Ver [WORKSHOP_BILLING_ACCEPTANCE.md](WORKSHOP_BILLING_ACCEPTANCE.md). As referências abaixo a aceitação/checkpoint pendentes são históricas; nenhuma prova pendente passa a realizada. `120000`, seis concessões e uso real continuam por autorizar.

## Percurso manual de geração relatado e reconciliado

**Conferência manual posterior do destino e dos acessos:** o utilizador enviou o detalhe do rascunho #4, origem prestação #8 v1, moeda MZN, linhas 2 × 75 e 1,75 × 200, base aritmética 500 e pendências fiscais/contabilísticas preservadas. Na consulta como Samira sintética, enviou também o destino sem edição/confirmação e a página específica Oficina → rascunho com proposta revista #1 v1 e geração existente, sem formulário de preparação ou botão de geração. Esta observação conclui os passos manuais pendentes descritos abaixo, segundo os textos enviados pelo utilizador; não equivale a captura inspeccionada ou automação recuperada. Não houve autorização de confirmação B1 ou emissão. Aceitação e checkpoint continuam pendentes.

Em 28/10/2026, o utilizador enviou os textos da proposta #1 v1, da revisão aprovada e da geração: ordem #1 → proposta #1 v1 → prestação #8 → rascunho de facturação #4. Material #6 v1, 2 UN × 75 = 150 MZN; trabalho #4 v1, 1,75 H × 200 = 350 MZN. Referência `WORKSHOP-SALES-SYNTHETIC-v1`, soma 500 MZN sem imposto. Relato evidencia alternância entre conta revisora sem botão de geração e preparador com botão; confirmação explícita da ausência dos formulários na revisora ainda não foi solicitada novamente como facto concluído.

Executado `scripts/sgf.ps1 php scripts/workshop-billing-manual-verify.php --env=browser-testing` em consulta read-only: confirmou geração única, duas utilizações canónicas, origens verificadas, versão exacta revista por identidade distinta, linhas do destino correspondentes à proposta, prestação/rascunho em estado draft, 500 MZN, imposto pendente, contabilidade não processada e nenhuma confirmação B1 deste rascunho. Nenhum dado ou credencial alterado. Ver [resultado estruturado](proofs/workshop-billing-manual-results.json).

Limites: textos enviados pelo utilizador e reconciliação técnica, sem capturas recebidas ou automação recuperada. Consulta visual do rascunho destino e confirmação explícita dos formulários ausentes na revisora continuam separadas; não se presumem aceitação ou checkpoint. As referências abaixo a percurso manual ainda não executado descrevem a preparação histórica.

## Correcção durante a prova manual — mensagem de validação

Na tentativa manual seguinte, o utilizador indicou ausência de resposta. Consulta read-only confirmou zero propostas/revisões/gerações: nenhuma submissão foi registada. Corrigida lacuna de feedback: a validação nativa do fundamento podia impedir a execução do handler sem mensagem da aplicação. O formulário passa a usar a validação explícita já testada; erros são trazidos para a zona visível e sucesso informa ID/versão. Falha de recarga após gravação é distinguida de falha da submissão, com instrução de não resubmeter. Substituído o placeholder que podia ser confundido com fonte já preenchida. Não se afirma qual campo concreto faltava no navegador do utilizador. Compilação aprovada; sem alteração de base ou credenciais. Novo script `workshop-billing-status.php` apenas para estado sintético read-only.

O utilizador encontrou `validation.required` ao submeter. O texto enviado não permitia identificar qual campo faltou; não se presume que a proposta tenha sido criada. Acrescentada validação local das origens seleccionadas, serviço, preço, fonte e fundamento, com mensagens por ID de origem antes de enviar. Servidor passou a fornecer mensagens portuguesas com nomes de campos, mantendo as regras. Não se preenchem preços/serviços automaticamente; zero explícito continua válido. Novo auxiliar `resources/js/workshopBillingProposal.js` e verificação `scripts/workshop-billing-form-check.mjs`, aprovada para omissões, zero e valores exactos. Compilação e sintaxe PHP aprovadas. Base, propostas e credenciais não alteradas; testes destrutivos não repetidos durante a prova manual activa. Sem aceitação/checkpoint.

**Estado final das verificações técnicas:** regressão completa 175 testes / 3 094 asserções sem falhas; após acrescentar protecção contra segundo rascunho pelo percurso normal, 24 testes / 271 asserções afectados e 14 testes / 156 asserções de A aprovados. Não somar estas execuções como casos distintos. Seis casos novos de conversão, cinco provas concorrentes e compilação aprovados. Ver [resumo exacto](proofs/workshop-billing-tests.json). Menções abaixo à regressão em execução são históricas. Prova manual no navegador ainda pendente, sem aceitação/checkpoint.

28/10/2026. `WORKSHOP-BILLING-DRAFT-SIM-v1`, [âmbito e decisões](WORKSHOP_BILLING_DRAFT_SCOPE.md), autorizado pelo utilizador após confirmar preços sintéticos. Preservados `04870f0`, `090b7da`, alterações posteriores e entregas aceites. **Sem aceitação presumida ou checkpoint de encerramento.** Nada aplicado em desenvolvimento.

## Percurso implementado

Selecção integral de apontamentos actuais de tempo efectivo e materiais consumidos da empresa, com tarefa actual verificada, origem/versionamento e decisão técnica identificados. Recusa entrega/devolução, material do cliente, origem pendente/recusada/obsoleta ou fora de autorização. Só dados da empresa/unidade seleccionadas; consulta comercial não atribui verificação técnica. Quantidades derivam da origem: 105 MIN → 1,75 H; 2 UN consumidas permanecem 2, sem descontar novamente devoluções.

Preparador liga cada origem a serviço de catálogo por ID/versão, preço comercial e fonte explícitos. Preço desconhecido impede proposta/geração, zero explícito é distinto. Moeda MZN, cliente da ordem conferido, catálogo e cliente versionados. A proposta guarda composição e fundamento/exclusões e é imutável; sucessora explícita requer nova revisão. Identidade distinta aprova/recusa versão exacta. Mudança da origem/tarefa/cadastro/cliente torna proposta desactualizada, sem escolha automática de sucessora ou aprovação herdada.

Ensaio aprovado como hipótese: `WORKSHOP-SALES-SYNTHETIC-v1`, preços sem imposto de 200 MZN/H e 75 MZN/UN. Soma exacta: 350 + 150 = **500 MZN**. Não são tarifas reais nem derivação do custo interno de 275 MZN; imposto/aplicabilidade continuam pendentes, sem chamar 500 de total fiscal ou quantia exigível. Aritmética exacta; fracção que não caiba no contrato decimal 16/8 do rascunho é recusada, sem arredondamento silencioso.

Geração reutiliza `ServiceWorkflow` e cria prestação de origem e rascunho de facturação na mesma transacção; a prestação é necessária pelo contrato existente. Não cria duas utilizações técnicas/comerciais. Vínculo único da origem canónica por ordem, geração única por ordem e referências exactas à proposta, apontamentos e versões. Chave idempotente recupera o mesmo destino; conteúdo diferente é conflito. Bloqueio de empresa serializa revisões e geração; auditoria/evento/outbox atómicos, rollback sem rascunhos ou vínculos órfãos. Nenhuma confirmação B1 automática.

Rascunhos gerados não podem ser editados/apagados directamente no SQL; aplicação responde com 409 ao tentar edição pelo fluxo existente. Correcção/cancelamento comercial não integra este recorte; uma origem utilizada não é libertada por edição ou nova versão técnica. Histórico preservado, sem reescrever fotografias B1. Propostas com origens alteradas ficam sinalizadas; os rascunhos gerados conservam a composição original e exigem circuito próprio de correcção antes de reutilização comercial.

Também bloqueada a criação de outro rascunho pelo percurso A usando a prestação já convertida: recusa 409 na aplicação e trigger de INSERT no SQL. A primeira geração ocorre atomicamente antes do registo final do vínculo; depois disso, não há caminho alternativo autorizado para reaproveitar essa prestação como segundo destino. Revogação de direitos de criação de destino é verificada também antes de recuperar um replay da geração.

## Interface e prova

Novo destino **Oficinas → Oficina → rascunho**, só com `workshop_billing.view`. Atalhos na página inicial por direitos explícitos de preparação/revisão, sem contagens fictícias. Revisor consulta proposta e toma decisão, sem formulário de preparação/geração. Preparador escolhe serviços/preços, submete, depois gera a partir da versão aprovada. Interface mostra IDs de prestação/rascunho, sem validade fiscal e fiscalidade pendente.

Regressão inicial relevante: **41 testes / 660 asserções aprovados**, incluindo quatro testes iniciais de conversão e regressões de oficinas/custo directo/B1/guardas. Acrescentados casos de sucessão, catálogo alterado e revogação de criação do destino no replay; regressão completa final em execução. Compilação aprovada, Vite 8.3.5, sem alterações de dependências. Cinco cenários concorrentes com processos sobrepostos aprovados em [workshop-billing-concurrency.json](proofs/workshop-billing-concurrency.json): proposta repetida, propostas sucessoras concorrentes, revisão repetida, geração repetida e geração com novas chaves já utilizada. Uma geração, dois vínculos canónicos.

**Navegador:** a automação do Edge já estava bloqueada, sem nova tentativa ou afirmação de recuperação. Nenhuma captura ou execução manual deste novo percurso é declarada. Preparação para prova manual, quando houver instância de teste vazia sob as guardas e nenhum teste destrutivo em execução:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/browser-proof.ps1 start -Port 8002
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/sgf.ps1 php scripts/workshop-billing-fixture.php --env=testing
```

Fixture cria ordem/recursos sintéticos com verificação por técnico/verificador distintos dos papéis comerciais. Não preenche proposta/revisão/geração. Usar contas sintéticas do manifesto protegido fora do repositório; não exibir ou copiar palavras-passe para provas. Preparador selecciona o tempo e consumo, serviços exactos, preços 200/75 e referência acima; revisor entra separadamente e aprova versão exacta; preparador gera prestação/rascunho; conferir 500 MZN, estados pendentes e rastreabilidade no destino. Não correr testes que recriam a base enquanto essa prova estiver activa; parar apenas a instância SGF por `scripts/browser-proof.ps1 stop`.

Instância manual efectivamente preparada em 8002 após os testes finais, com ambiente confirmado por HTTP em [workshop-billing-environment.json](proofs/workshop-billing-environment.json). Entrada: `gestor@example.test` (preparação/geração) e `consulta@example.test` (revisão), mesmo contexto sintético. Instruções de entrada apenas em `C:\laragon\data\sgf-tempo\secrets\workshop-billing-manual-entry.txt`, fora do repositório, ACL do utilizador local/SYSTEM. Não usar as credenciais anteriores de outro ensaio. Nenhum passo manual foi declarado realizado; a instância permanece ligada para essa prova. Seleccionar o serviço «Serviço comercial exclusivamente sintético» e a sua versão apresentada. O validador comercial não recebeu direitos de verificação técnica.

## Migração e concessões apenas propostas

Migração **`2026_10_28_120000_create_workshop_billing_drafts.php`**, SQL `database/sql/workshop-billing.sql`, destino futuro **sgf_tempo_dev / 127.0.0.1:55432**, por caminho exclusivo com `sgf_dev_owner`; aplicação mantém `sgf_dev_app`. Depende da fundação/oficinas e guarda SQL de testes já existentes. Cria sete tabelas: `wb_proposals`, `wb_decisions`, `wb_generations`, `wb_claims`, `wb_commands`, `wb_events`, `wb_outbox`; índices, FKs, triggers de ambiente/imutabilidade, cadeia/revisão, vínculo único e protecção condicional dos rascunhos ligados. Amplia CHECK com quatro nomes de direitos; não atribui concessões. `down()` recusa destruição de história. Guardas da aplicação e INSERT nas sete tabelas mantêm uso restrito a `sgf_tempo_test`/55432; sem opção de activação real. SQL não é RLS nem uma segunda implementação do motor comercial completo.

Consulta `scripts/workshop-billing-permissions-preview.php` confirmou migração ausente, conversão real recusada e as seis concessões abaixo ausentes. **Não aplicadas**, exigem autorização específica separada. Todas: **tenant #1 / Tempo Lda #1 / SEGI #1**.

| Conta existente | Direitos propostos |
| --- | --- |
| Osmane #1 | `workshop_billing.view`, `workshop_billing.prepare`, `workshop_billing.generate` |
| Samira #2 | `workshop_billing.view`, `workshop_billing.review`, `workshop.view` |

`workshop.view` para Samira é consulta técnica necessária à revisão comercial; não inclui `workshop.verify`, apontamentos, supervisão ou gestão de acessos. Os direitos de consulta empresarial de clientes/serviços das duas contas e os de consulta/criação de prestações/rascunhos da conta #1 já existem e foram conferidos; não são reaplicados ou derivados de custos. `110000` e sete concessões do orçamento permanecem separadas e pendentes.

## Ficheiros e limitações

Novos: `app/Modules/Workshop/WorkshopBilling.php`, controlador em `Http/WorkshopBillingController.php`, migração/SQL, `resources/js/WorkshopBillingWorkspace.jsx`, testes/fixture `WorkshopBillingTest.php`/`WorkshopBillingFixture.php`, scripts `workshop-billing-fixture.php`, `workshop-billing-worker.php`, `workshop-billing-concurrency.php`, `workshop-billing-permissions-preview.php`, documentação/provas. Integrações no router, navegação/página inicial e protecção de edição em `ServiceWorkflow.php`.

Uma ordem/cliente/MZN, selecção integral, um destino, cobrança por tempo efectivo e material consumido da empresa. Sem tarefa a preço fixo, repartição parcial, descontos, margens, stock, emissão, cálculos fiscais novos, recebimentos, lançamentos, publicação ou utilização real. Correcção/cancelamento de rascunhos ligados bloqueados até circuito próprio. Prova visual e aceitação continuam separadas; nenhuma pendência é promovida a prova realizada.