From 742231564d39d408c25a7e8799ddc4b0290d89a2 Mon Sep 17 00:00:00 2001 From: itecnologys Date: Wed, 7 Oct 2026 10:29:16 +0000 Subject: [PATCH] docs: Rently cycle spec 2026-10-07-r1 Co-Authored-By: Claude Opus 5.5 --- Infra-Network/SPEC-CLOSING-TILL-CYCLE.md | 118 +++++++++++++++++++++++ 1 file changed, 118 insertions(+) create mode 100644 Infra-Network/SPEC-CLOSING-TILL-CYCLE.md diff --git a/Infra-Network/SPEC-CLOSING-TILL-CYCLE.md b/Infra-Network/SPEC-CLOSING-TILL-CYCLE.md new file mode 100644 index 0000000..b686cde --- /dev/null +++ b/Infra-Network/SPEC-CLOSING-TILL-CYCLE.md @@ -0,0 +1,118 @@ +# SPEC — Ciclo EOD → Closing Till → Remittance Pack → HO (definitiva) + +**Status:** DEFINITIVA — aprovada por Roger em 2026-10-07 (blocos 1 e 2) +**Rules version:** `CYCLE_RULES_VERSION = 2026-10-07-r1` +**Substitui:** `SPEC-CLOSING-TILL-FREEZE-ARCHIVE.md` (2026-10-01-r1), `RULE-CLOSING-TILL-AFTER-CUT-LOCKED.md`, `releases/011.2026.md` (2026-10-06-r1) e `.cursor/rules/eow-cycle-start-rules.mdc` naquilo que contradizem esta spec. +**Implementação:** ⏳ ainda não implementada — PRD corre `2026-10-01-r1`. Implementar em TEST, validar com Roger, depois PRD. + +--- + +## 1. Visão geral + +``` +Dia a dia Dia de fecho EOW – Closing Till EOW Remittance Pack HO +Save statement ─▶ Save EOD for Closing Till ─▶ Cycle Start → Apply → Draft ─▶ Freeze TEMPORÁRIO ─▶ Pack → Official Draft ─▶ Approve ROI → Send to HO +(editável) (linha de corte) (nada trava) (trava valores, reversível) (CONGELADO DEFINITIVO) +``` + +O congelamento **definitivo** acontece **só** no **Send to HO**. + +--- + +## 2. Regras + +### R1 — Save statement (dia a dia, EOD Transactions) +- Ao fim do dia o operador clica **Save statement** → cria um ficheiro EOD (cards *Saved EOD file* e *Recent saved EOD files*). +- Pode salvar **várias vezes** no mesmo dia (correcções, lançamentos esquecidos). +- O ficheiro fica **editável** (não imutável) enquanto o ciclo a que pertence não foi enviado ao HO. + +### R2 — Save EOD for Closing Till (dia de fecho: quinta ou outro dia escolhido) +- Faz o mesmo que o Save statement **e** marca a hora do clique, colocando a **linha de corte** após o último lançamento: + - **before-cut** (00:00 → corte) = este ciclo; + - **after-cut** (corte → 23:59) = próximo ciclo. +- Um **Save statement** no dia de fecho **depois** do corte gera/actualiza o **after-cut** (próximo ciclo). +- **Segundo clique no mesmo dia:** avisar *"Já existe uma linha de corte neste dia (HH:MM). Deseja criar uma nova?"* + - Se o EOW **ainda não foi enviado**: o novo corte **substitui** o ficheiro final da semana no Cycle Start e o processo recomeça (drafts anteriores ficam desactualizados). + - Se existir **freeze temporário** activo: pedir primeiro para o libertar (R5). + - Se o EOW **já foi enviado**: bloquear. + +### R3 — Week EOD files (Cycle Start) — EOW Closing Till +Lista **todos** os ficheiros do ciclo aberto: +1. o **after-cut** do último fecho (semana anterior); +2. o ficheiro de **cada dia** entre os fechos — **só o save mais recente** de cada dia; +3. o **before-cut** do dia de fecho actual (até à hora do clique). + +- Ficheiros do ciclo aberto **nunca** aparecem como *used · immutable*. +- O dia de fecho dividido não mostra o ficheiro de dia inteiro (só before/after). +- Ficheiros de ciclos já enviados não aparecem. +- Nada vem pré-seleccionado; *used · applied* só depois de marcar + **Apply start & preview**. + +### R4 — Apply start & preview / Generate draft +- **Apply start & preview** une os ficheiros marcados num **ficheiro único** (preview). Pode repetir-se. +- **Generate draft** gera um draft a partir de uma selecção de cada vez. +- Pode haver **vários drafts**; **os drafts não trancam ficheiros** (os mesmos ficheiros podem estar em vários drafts). Só um será usado; os outros ficam para leitura e podem ser apagados. + +### R5 — Freeze temporário (Closing Till) — OBRIGATÓRIO antes do Remittance Pack +- O operador escolhe **um** draft e faz **Freeze** → estado **Temporarily frozen**. +- Trava os ficheiros e valores desse pacote, para que o envelope e o pack batam com o que vai ser enviado (edições nesses dias ficam bloqueadas com mensagem). +- **O operador pode libertar** (Unfreeze) enquanto não houver envio — volta a draft e terá de refazer as etapas seguintes. +- O Unfreeze **não apaga** a linha de corte (o corte pertence ao *Save EOD for Closing Till*, R2). +- Selo na UI: **"Temporarily frozen"** (nunca "FROZEN — immutable" antes do envio). + +### R6 — EOW Remittance Pack +- **Pack Summary** mostra o montante do pacote em freeze temporário. +- Operador preenche os dados do **envelope** e gera **previews** da revisão (quantos quiser; os não usados podem ser apagados e não ficam congelados). +- **Create Official Draft** → fica disponível em **3. Approve selected ROI**. +- **Aviso obrigatório:** se não houver pacote em freeze temporário, mostrar no topo do Remittance Pack: + > *"Ainda não existe um Closing Till em Freeze temporário. Volte a EOW – Closing Till, escolha o draft e clique em Freeze antes de montar o pack."* + — e desactivar *Create Official Draft* até existir. + +### R7 — Approve selected ROI → Send to HO (congelamento DEFINITIVO) +- Neste momento os ficheiros do pacote (incluindo o **before-cut**) passam a **Frozen · Sent**: imutáveis, indisponíveis para novos ciclos. +- O **after-cut** **não** fica congelado — pertence ao próximo ciclo (R3.1). +- Depois do envio **só o admin** pode reverter, como excepção registada em auditoria (motivo obrigatório). + +### R8 — Lançamentos atrasados em dias enviados +- Por regra **nada entra** nos ficheiros imutáveis/enviados. Um lançamento num dia já enviado é bloqueado. +- **Futuro (fora desta entrega):** módulo / conta de **Correcção Contabilística** para registar esses casos no ciclo seguinte, com rasto. + +--- + +## 3. Estados + +| Estado | Onde | Ficheiros travados? | Quem reverte | +|--------|------|---------------------|--------------| +| Ficheiro EOD salvo | EOD Transactions | Não | — | +| Draft (vários) | Closing Till | Não | apagar draft | +| **Temporarily frozen** (1 por ciclo) | Closing Till | Sim (valores do pacote) | **operador** (Unfreeze) | +| Official draft / previews | Remittance Pack | Sim (herda o freeze) | operador (apagar / unfreeze) | +| **Frozen · Sent** | após Send to HO | **Sim, definitivo** | **só admin** (excepção auditada) | + +--- + +## 4. Diferenças face ao sistema actual (2026-10-01-r1 em PRD) + +| Ponto | Hoje | Esta spec | +|-------|------|-----------| +| Ficheiros no Cycle Start | só `for_eow=1` | todos os Save statement (mais recente por dia) + before/after-cut | +| Draft tranca ficheiros | sim (`eod_ids_held_by_draft_or_freeze`) | **não** | +| Freeze | "FROZEN — immutable" | **Temporarily frozen**, reversível pelo operador | +| Unfreeze | só admin; apaga a linha de corte | operador; **mantém** o corte | +| Imutável definitivo | no Freeze | no **Send to HO** | +| After-cut do fecho anterior | preso no freeze (ex.: EOD-20261001-37722C €129) | aberto para o próximo ciclo | +| Corte | carimbado pelo Freeze | carimbado pelo **Save EOD for Closing Till** | +| 2.º clique no dia de fecho | sem tratamento | aviso + substituir enquanto não enviado | +| Remittance Pack sem freeze | sem aviso | aviso + Create Official Draft desactivado | + +--- + +## 5. Notas de implementação (TEST primeiro) + +- `eow_report.list_eod_choices`: listar todos os EOD do ciclo aberto (último save por dia), excluir só os de ciclos **enviados**. +- `eod_ids_held_by_draft_or_freeze` → passa a "held by **sent**" (e "temporarily frozen" só para bloquear edição, não a listagem). +- `freeze_eow_draft`: não acrescentar o after-cut à lista do pacote; não carimbar corte (R2 já o fez). +- `unfreeze_eow_report`: permitir operador quando não enviado; não limpar `closing_till_cut`; admin com motivo depois do envio. +- `eod_report`: *Save EOD for Closing Till* gera before/after + aviso de 2.º clique. +- Remittance Pack (frontend + API): aviso R6 e bloqueio de *Create Official Draft*. +- Testes de regressão: reescrever `tests/test_eow_cycle_start_rules.py` para esta versão. +- Ao implementar: actualizar `.cursor/rules/eow-cycle-start-rules.mdc` para apontar para esta spec.