SGF/docs/SERVICES_WORKFLOW_SPEC.md

# Primeiro percurso operacional de serviços

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.
- Reutilizar a fundação existente: tenant, empresa, unidade, utilizador, sessão, contexto, concessões e auditoria.
- Preservar independência do InvesteMoz, versões instaladas e separação entre desenvolvimento e testes.
- Usar dados sintéticos nas provas, sem os inserir como operações da Tempo Lda/SEGI.

As entidades, estados, limites e entregas abaixo são propostas técnicas. Valores de teste não são preços comerciais, taxas fiscais ou regras contabilísticas aprovadas.

## Condição antes da implementação seguinte

O incremento de entrada, contexto e permissões tem implementação e provas técnicas documentadas em IDENTITY_DELIVERY.md. A verificação por leitura confirmou uma única SEGI, os direitos de gestão de Osmane na Tempo Lda e apenas company.view/unit.view para Samira na Tempo Lda/SEGI. A última suite executada passou com 30 testes e 117 asserções; não foi repetida nesta revisão documental.

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.

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

Um utilizador autorizado escolhe um cliente e um serviço, regista a prestação, prepara a facturação, acompanha recebimentos parciais e uma correcção e consegue explicar o saldo pelas origens. Os acontecimentos alimentam captura contabilística permanente, incluindo pendências. Reconciliação e fecho só são apresentados como concluídos quando cumprirem os controlos aprovados.

Percurso de referência:

Cliente → serviço → prestação → documento de facturação → recebimento parcial → correcção → segundo recebimento → reconciliação → fecho.

Os acontecimentos têm identidades e estados próprios. A prestação não é uma factura e uma factura não comprova recebimento. Registar um recebimento não inicia pagamento, transferência ou débito bancário.

| Acontecimento | Significado | O que não demonstra por si só |
| --- | --- | --- |
| Serviço prestado | Registo do trabalho realizado, cliente, conteúdo, unidade e data da prestação | Factura emitida, pagamento recebido ou reconhecimento contabilístico aprovado |
| Factura | Documento de cobrança com identidade, data, linhas e regras próprias | Serviço concluído ou dinheiro recebido |
| Recebimento | Observação/registo de um valor recebido, com origem/evidência e afectação | Emissão de factura, liquidação confirmada pela fonte ou reconciliação concluída |

Conservar separadamente datas, estados, identificadores e relações desses três acontecimentos. Não criar os três como efeito implícito de um único botão.

## Cenário sintético de aceitação

Entidades exclusivamente de teste: Empresa Exemplo de Serviços, Unidade de Teste, Cliente Exemplo e Serviço Pontual de Teste. Não utilizar os nomes, contas ou operações reais da Tempo Lda como fixtures.

Para demonstrar as relações e a aritmética do sub-razão, usar o seguinte exemplo em MZN. O valor 1 000,00 é um montante de referência artificial do teste; não significa preço aprovado, tributação nula ou montante fiscal já apurado.

### Caso principal liquidação por dois recebimentos

| Acontecimento | Valor do teste | Saldo aritmético por receber |
| --- | ---: | ---: |
| Documento de referência do serviço | 1 000,00 | 1 000,00 |
| Recebimento parcial afectado ao documento | 400,00 | 600,00 |
| Segundo recebimento afectado ao documento | 600,00 | 0,00 |

Resultado: 1 000,00 − 400,00 − 600,00 = 0,00. Cada recebimento tem identidade e afectação próprias. Repetir qualquer comando/importação ou processá-lo em concorrência não pode acrescentar outra afectação nem reduzir novamente o saldo. Mudar o conteúdo mantendo a mesma chave de repetição deve produzir conflito.

### Variante de correcção redutora

Reiniciar o cenário apenas com fixtures de teste próprias, sem alterar o caso principal nem a factura original. Ensaiar uma redução de 100,00 numa linha do documento, identificando documento e linha de origem, identidade da correcção, montante, data, autor e motivo sintético.

| Acontecimento | Valor do teste | Saldo aritmético por receber |
| --- | ---: | ---: |
| Documento original preservado | 1 000,00 | 1 000,00 |
| Primeiro recebimento | 400,00 | 600,00 |
| Correcção redutora independente | 100,00 | 500,00 |
| Segundo recebimento | 500,00 | 0,00 |

Resultado: 1 000,00 − 100,00 − 400,00 − 500,00 = 0,00. A correcção não apaga nem altera silenciosamente o original. A forma documental legal da correcção permanece por validar.

Este cenário distingue três provas: saldo operacional explicado, contabilização válida e fecho válido. A primeira não demonstra automaticamente as outras duas. Um perfil artificial de cálculo/contabilização, se aprovado para ensaio, será exclusivo de testes, identificado como sintético e impossibilitado de activar regras reais em desenvolvimento.

### Reconciliação exclusivamente simulada

Comparar os dois recebimentos/afectações com duas observações de fonte sintética, identificadas como simulação e contendo identificador, documento de referência, moeda, montante, data e estado de teste. Uma observação repetida não cria outro recebimento. Demonstrar correspondência individual e total, além de uma variante com divergência que permanece pendente.

Não consultar bancos, iniciar pagamentos, transferir fundos, executar débitos ou apresentar observações artificiais como extractos reais. A prova demonstra o mecanismo e os controlos incluídos, não integração ou liquidação bancária real.

## Significado de fecho neste cenário

Fecho significa o encerramento controlado de um período contabilístico de teste, com evidência preservada. Não significa apenas terminar o formulário, marcar a prestação como concluída ou obter saldo por receber igual a zero. Não é submissão fiscal ou bancária.

O fecho proposto deve:

1. Identificar empresa, período, corte e versões de regras/dados consideradas.
2. Verificar que os acontecimentos elegíveis foram capturados, processados e ligados aos documentos/afectações, sem efeitos perdidos ou repetidos.
3. Conferir o sub-razão, a reconciliação simulada e os lançamentos necessários, com débitos/créditos e saldos explicáveis sob um perfil de teste explicitamente aprovado.
4. Recusar encerramento integral se houver pendência material, divergência, classificação em falta ou configuração insuficiente. Mostrar o motivo sem inventar uma conta/regra.
5. Preservar evidências e actor responsável, passar de aberto para em fecho/encerrado conforme validações e impedir gravações concorrentes no período encerrado.

Eventos tardios ou correcções posteriores não reabrem nem reescrevem o período automaticamente. O tratamento deve ser uma operação autorizada segundo política ainda por validar. Sem perfil contabilístico suficientemente definido, a prova esperada é a recusa fundamentada do fecho; não uma conclusão artificial de conformidade.

## Dados mínimos propostos

| Entidade | Dados e vínculos iniciais |
| --- | --- |
| Contraparte com papel de cliente | Identificador estável, empresa, nome e papel de cliente; não duplicar o futuro cadastro de fornecedor |
| Serviço | Identificador, empresa, nome e descrição; sem preço comercial ou regra fiscal por omissão |
| Prestação | Empresa, unidade, cliente, linhas de serviço, descrição, quantidade, data da prestação e estado |
| Rascunho de facturação | Origem da prestação, cliente, empresa/unidade, moeda, linhas, preços propostos, versões e pendências |
| Documento confirmado futuro | Identidade própria e fotografia dos dados/regras efectivamente aplicados; numeração e validade dependem de decisão |
| Recebimento futuro | Identidade, empresa, cliente, data, moeda, montante, origem/evidência, estado e afectações aos documentos |
| Correcção futura | Referência ao original, linhas/valores abrangidos, motivo, autor e efeitos aprovados |
| Evento durável | Identidade, origem/versionamento, empresa/unidade, instante, tipo, correlação e processamento |
| Pendência contabilística | Evento, informação/regra em falta, estado, motivo e historial de resolução |

Não acrescentar já contratos recorrentes, horas, equipas de projecto, custos, campos fiscais presumidos ou stock. A moeda funcional, precisão e regras de cálculo da empresa não são inferidas do exemplo de teste.

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.
- Facturação: rascunho, com pendências, pronta para validação e confirmada apenas com regras/configuração suficientes. Guardar um rascunho não equivale a emitir factura.
- Cobrança: sem afectação, parcialmente recebida ou saldo liquidado, derivados dos montantes e estados admissíveis, não de um botão livre.
- Recebimento: registado, com evidência por verificar, conciliado ou corrigido por operação rastreável. Os critérios concretos de evidência e liquidação serão aprovados.
- Contabilidade: capturado, pendente, pronto, contabilizado ou sem efeito justificado. Falha técnica fica distinguida de informação em falta.
- Período: aberto, em fecho ou encerrado, sujeito à política a validar.

O primeiro incremento não deve apresentar os estados futuros como capacidades já entregues.

## 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 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, 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.
10. Fecho verifica eventos, pendências, reconciliação e integridade, incluindo concorrência. Um saldo operacional nulo não basta para fechar.

## Ecrãs propostos

Reutilizar a navegação e o cabeçalho de contexto existentes:

- Clientes: pesquisar, consultar e preparar o cadastro mínimo de contraparte com papel de cliente.
- Serviços: pesquisar e manter o catálogo mínimo.
- Prestações: lista, detalhe e formulário com cliente, serviço e origem reutilizados.
- Facturação: rascunho ligado à prestação, valores e pendências visíveis; sem aparência de documento fiscal emitido.
- Detalhe do percurso: linha do tempo de prestação, documentos, recebimentos, correcções e pendências, conforme cada entrega disponibilizada.
- Posteriormente, recebimentos/reconciliação e fecho, depois de aprovadas as regras respectivas.

As interfaces mostram o que está guardado, o que falta e a próxima acção permitida. Não disponibilizar operações de servidor ainda inexistentes através de botões simulados.

## Permissões propostas

Separar consulta e alteração de cadastros, criação/edição/confirmação de prestações, preparação/confirmação de documentos, registo/afectação/correcção de recebimentos, reconciliação e fecho.

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

Âmbito delimitado para a primeira implementação, sujeito à autorização de execução:

- 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.

Demonstrar separadamente o caso principal (400,00 + 600,00 liquidam 1 000,00) e a variante de correcção (400,00 + 500,00 liquidam o saldo líquido de 900,00). A reconciliação é sempre identificada como simulada.

Estas entregas partilham o mesmo núcleo. Não criam três produtos ou versões divergentes.

## Critérios de aceitação

- Cliente/serviço de outra empresa ou unidade não autorizada recusados por URL/API, identificador manipulado ou tarefa.
- Utilizador de consulta não consegue alterar, confirmar, receber, corrigir ou fechar.
- Direitos revogados e contexto alterado produzem recusa no pedido seguinte.
- Um cliente e uma prestação são reutilizados na facturação sem recaptura ou duplicação de cadastros.
- Guardar rascunho, repetir comando e retomar depois de falha não duplica documentos/eventos.
- Documento confirmado futuro conserva dados e regras mesmo que o cadastro seja alterado.
- Os valores do cenário e todas as afectações são explicáveis pelas origens e calculados com decimais controlados.
- Falta de regra fiscal/contabilística gera pendência, não taxa zero, conta inventada ou estado contabilizado.
- Correcção conserva o original, motivo e vínculos, sem edição directa de lançamentos confirmados.
- Falhas antes/depois do commit e dois consumidores concorrentes não deixam efeitos parciais ou duplicados.
- Fecho com lacuna material é recusado; lançamento concorrente não ultrapassa período encerrado.
- Activação posterior de interface de Contabilidade não repete efeitos já produzidos.
- Testes destrutivos continuam restritos a sgf_tempo_test e fixtures não entram como operações da Tempo Lda.

## Decisões pendentes antes das entregas correspondentes

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.

Não seleccionar fornecedor, API bancária ou integração de pagamento. Não construir agora plano comercial, motor geral de parâmetros, IA, sincronização offline ou toda a orquestração Camaleão. As lacunas não justificam codificar valores de negócio fixos como substituto de validação.

## Estado desta etapa

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.