Release v4928.1.4.2 stable

docs/CLIENTFLOW_V33_NOTES.md

@@ -0,0 +1,120 @@
+# ClientFlow v3.3 — HTMX manual e operação Jasmin mais estável
+
+Esta versão é incremental sobre a v3.2 e foca-se em remover o comportamento visual estranho causado pelo auto-refresh do cartão **Documentos Jasmin**.
+
+## Alterações principais
+
+### 1. Documentos Jasmin sem auto-refresh
+
+Foi removido o polling HTMX automático do cartão de Documentos Jasmin.
+
+Antes:
+
+```html
+hx-trigger="every 10s"
+```
+
+Agora:
+
+- o cartão não se reconstrói sozinho;
+- existe botão **Atualizar estado**;
+- os botões **Criar orçamento** e **Converter em fatura** continuam a atualizar o cartão uma vez após o clique;
+- o operador controla quando quer atualizar o estado.
+
+Fluxo esperado:
+
+```text
+[Criar orçamento]
+→ cria item na outbox
+→ mostra feedback imediato
+→ timer/worker processa
+→ operador clica [Atualizar estado]
+→ vê orçamento criado ou erro
+```
+
+### 2. Feedback visível após ações Jasmin
+
+Os botões continuam a devolver mensagens visíveis no cartão:
+
+- Pedido de orçamento enviado para a outbox Jasmin.
+- Pedido de fatura enviado para a outbox Jasmin.
+- Erros de validação antes de criar a outbox.
+
+### 3. Outbox Jasmin visível na oportunidade
+
+O cartão de Documentos Jasmin continua a mostrar as ações da outbox associadas à oportunidade:
+
+- action type;
+- estado;
+- erro resumido;
+- botão **Reprocessar** para itens pendentes/falhados.
+
+### 4. Validação antes de criar orçamento
+
+Mantém-se a validação preventiva:
+
+- cliente associado;
+- NIF válido;
+- nome fiscal;
+- morada/código postal/cidade quando o cliente ainda não existe no Jasmin;
+- pelo menos uma linha de produto;
+- todas as linhas com `jasmin_sales_item`;
+- preço unitário maior que zero.
+
+### 5. SKU/Odoo separado de artigo Jasmin
+
+Mantém-se a regra introduzida na v3.1/v3.2:
+
+```text
+products.sku = código interno/Odoo
+products.jasmin_sales_item = artigo Jasmin
+opportunity_items.sku = código interno/Odoo
+opportunity_items.jasmin_sales_item = artigo Jasmin usado no orçamento
+```
+
+A criação de orçamento usa `jasmin_sales_item`, não o SKU Odoo.
+
+## Deploy
+
+Aplicar como nas versões anteriores:
+
+```bash
+rsync -avz --delete \
+  --exclude ".env" \
+  --exclude ".venv/" \
+  --exclude "venv/" \
+  --exclude "__pycache__/" \
+  --exclude ".git/" \
+  --exclude "*.db" \
+  --exclude "*.log" \
+  --exclude "uploads/" \
+  ./ plx@alarmsys:/mnt/ssd/home/plx/clientflow_backend/
+```
+
+Depois no remoto:
+
+```bash
+cd /mnt/ssd/home/plx/clientflow_backend
+source .venv/bin/activate
+python -m py_compile app/*.py scripts/*.py
+sudo systemctl restart clientflow-api
+```
+
+## Nota operacional
+
+O botão **Atualizar estado** não processa a outbox. Ele apenas recarrega o cartão.
+
+Para processar automaticamente, manter ativo o timer systemd da outbox Jasmin:
+
+```bash
+systemctl list-timers | grep clientflow-outbox-jasmin
+```
+
+Ou processar manualmente:
+
+```bash
+JASMIN_OUTBOX_ENABLED=true \
+OUTBOX_TARGET_SYSTEM=jasmin \
+OUTBOX_DRY_RUN=false \
+python scripts/process_outbox.py
+```