Release v4928.1.4.2 stable

docs/CLIENTFLOW_V31_NOTES.md

@@ -0,0 +1,109 @@
+# ClientFlow v3.1 — correções Jasmin/Packlink
+
+Esta versão é incremental sobre a v3 e corrige os pontos encontrados nos testes remotos.
+
+## Alterações principais
+
+### Produtos
+
+Agora existe separação entre:
+
+- `sku`: código interno/Odoo;
+- `jasmin_sales_item`: artigo de venda no Jasmin.
+
+Exemplo:
+
+```text
+sku = ODOO-1
+jasmin_sales_item = CARREGADOR_MONO_7KW
+```
+
+As tabelas recebem colunas novas de forma aditiva:
+
+```sql
+ALTER TABLE products ADD COLUMN IF NOT EXISTS jasmin_sales_item TEXT;
+ALTER TABLE opportunity_items ADD COLUMN IF NOT EXISTS jasmin_sales_item TEXT;
+ALTER TABLE order_items ADD COLUMN IF NOT EXISTS jasmin_sales_item TEXT;
+```
+
+Quando uma linha é adicionada à oportunidade a partir do catálogo, `opportunity_items.jasmin_sales_item` é copiado do produto.
+
+A criação de orçamento Jasmin usa esta prioridade:
+
+```text
+metadata.jasmin_sales_item
+opportunity_items.jasmin_sales_item
+JASMIN_DEFAULT_SALES_ITEM
+sku
+```
+
+Assim o SKU Odoo deixa de ser usado como artigo Jasmin, exceto como fallback.
+
+### Documentos Jasmin
+
+Depois de criar orçamento/fatura, o serviço faz um `GET` ao Jasmin para tentar preencher:
+
+- `document_type`
+- `serie`
+- `series_number`
+- `document_number`
+- `total_amount`
+- `currency`
+
+Isto melhora a tabela `commercial_documents` e a visualização na oportunidade.
+
+### UI da oportunidade
+
+- O formulário **Adicionar produto** saiu da área técnica e passou para o cartão **Produtos**.
+- Os botões **Criar orçamento** e **Converter em fatura** mostram mensagem de feedback informando que o pedido foi enviado para a outbox.
+- A tabela de produtos mostra SKU/Odoo e artigo Jasmin separadamente.
+
+### Timers systemd
+
+Foram adicionados exemplos em `deploy/systemd/`:
+
+- `clientflow-outbox-jasmin.service`
+- `clientflow-outbox-jasmin.timer`
+- `clientflow-outbox-packlink.service`
+- `clientflow-outbox-packlink.timer`
+
+Instalação Jasmin:
+
+```bash
+sudo cp deploy/systemd/clientflow-outbox-jasmin.* /etc/systemd/system/
+sudo systemctl daemon-reload
+sudo systemctl enable --now clientflow-outbox-jasmin.timer
+systemctl list-timers | grep clientflow
+```
+
+O timer Jasmin processa outbox a cada 1 minuto.
+
+## Verificações após deploy
+
+```bash
+cd /mnt/ssd/home/plx/clientflow_backend
+source .venv/bin/activate
+python -m py_compile app/*.py scripts/*.py
+python -m pytest -q
+sudo systemctl restart clientflow-api
+sudo systemctl status clientflow-api --no-pager
+```
+
+## Migração prática de produtos existentes
+
+Depois do deploy, ir a `/products/{id}` e preencher **Artigo Jasmin** para cada produto usado em documentos.
+
+Para corrigir via SQL/Python um produto específico:
+
+```bash
+python - <<'PY'
+from sqlalchemy import text
+from app.db import engine
+with engine.begin() as conn:
+    conn.execute(text("""
+        UPDATE products
+        SET jasmin_sales_item = 'CARREGADOR_MONO_7KW', updated_at = now()
+        WHERE sku = 'ODOO-1'
+    """))
+PY
+```