Poder fer campanyes directament amb un llistat d'emails

[polsala]

Context

Volem poder fer campanyes Poweremail directament a partir d'un llistat d'emails, sense haver de partir d'un model de negoci ni d'un filtre/domain.

El cas d'us principal es un CSV amb columnes:

email;language
persona@example.com;ca_ES
persona2@example.com;es_ES

Avui poweremail_campaign esta orientat a:

• seleccionar una poweremail.templates
• aplicar un domain sobre el model de la template
• crear poweremail.campaign.line amb ref cap al registre origen
• generar correus amb poweremail.templates.generate_mail(template_id, record_id)

Per reduir risc i evitar canvis al core gisce/poweremail, el disseny preferent es mantenir aquest contracte i implementar el mode CSV amb un objecte dummy propi de poweremail-modules.

Decisio de disseny

La campanya CSV no ha de ser "sense objecte" a nivell de Poweremail core. Ha de tenir un model origen simple i controlat, per exemple poweremail.campaign.recipient, amb un registre per destinatari importat.

Aixo permet:

• reutilitzar poweremail.templates.generate_mail(template_id, record_id) sense tocar gisce/poweremail
• fer que la template CSV apunti a poweremail.campaign.recipient com a template.object_name.model
• usar expressions de template normals sobre ${object.email}, ${object.language} i camps equivalents
• crear poweremail.campaign.line.ref amb una referencia real i consistent al dummy object
• mantenir callbacks, progres, batch i poweremail.campaign.line dins el flux existent
• auditar cada destinatari importat amb estat, error i mail generat

El model dummy ha de viure en aquest repo, lligat a la campanya, i ha de representar nomes el destinatari de campanya. No ha de crear partners, adreces, casos CRM ni cap altre objecte de negoci.

Notes tecniques validades al codi actual

Fitxers rellevants:

• poweremail_campaign/poweremail_campaign.py
• poweremail_campaign/poweremail_campaign_line.py
• poweremail_campaign/wizard/wizard_poweremail_campaign.py
• gisce/poweremail/poweremail_template.py

Punts a tenir en compte:

• update_linies_campanya esborra les linies existents i les recalcula a partir de campaign.domain sobre template.model_int_name; el mode CSV necessita una entrada separada i confirmacions clares per no destruir imports previs accidentalment.
• send_mail_from_line llegeix line.ref, n'extreu l'id i crida generate_mail(template, id_aux). Amb dummy object, aquesta part pot continuar igual si ref apunta a poweremail.campaign.recipient,<id>.
• get_value i generate_mail_sync del core renderitzen contra template.object_name.model; per tant el dummy object encaixa millor que un mode objectless per aquesta primera versio.
• List Related Objects actualment obre el model de la template i els ids extrets de les linies. En mode CSV ha d'obrir els destinataris dummy o una vista de linies/destinataris preparada, no objectes de negoci.
• La resolucio de company/from account del core pot intentar derivar company_id o company del registre origen; el dummy recipient ha de definir com es resol aquest punt o deixar-lo a configuracio de template/compte.
• partner_event, reports/adjunts i callbacks de negoci han de quedar desactivats o documentats com a no suportats en templates CSV mentre no hi hagi una regla segura.

Modes de campanya

• Campanya basada en objectes: comportament actual amb template + model + domain.
• Campanya basada en destinataris CSV: CSV d'emails + idioma que crea registres dummy de destinatari i linies de campanya referenciant aquests registres.

Cal fer visible el mode de campanya al formulari i protegir els botons/accions que nomes tenen sentit en un mode concret.

Model dummy proposat

poweremail.campaign.recipient hauria de tenir, com a minim:

• campaign_id
• email
• language
• csv_line_number
• state o validation_state
• log / error accionable
• normalized_email o hash/clau normalitzada per detectar duplicats
• campaign_line_id o relacio clara amb la linia creada, si ajuda a navegacio/auditoria
• mail_id o camp related si cal mostrar rapidament el mail generat
• camps tecnics d'import: data/import batch/source filename si es vol auditar la carrega

Estats suggerits:

• draft / importat pendent de validacio
• valid
• invalid
• duplicate
• line_created
• sending_error si es vol propagar l'error de generacio/enviament

Flux funcional proposat

1. Crear campanya i seleccionar mode: objectes o CSV.
2. En mode CSV, seleccionar una template que apunti al model dummy poweremail.campaign.recipient.
3. Importar CSV amb separador ; i capcalera minima email;language.
4. Prevalidar sense crear linies definitives:
   • total de files
   • valides
   • invalides
   • duplicades
   • resum per idioma
   • errors amb numero de linia
5. Confirmar la creacio o substitucio de destinataris/linies.
6. Crear/actualitzar recipients dummy i poweremail.campaign.line amb ref = poweremail.campaign.recipient,<id>.
7. Revisar destinataris i linies.
8. Enviar amb el flux actual de batch/progres.

Validacions necessaries

• Email obligatori i amb format minimament valid.
• Idioma opcional o obligatori a decidir, pero si ve informat ha d'existir a res.lang.
• Capcalera CSV exacta o tolerant de forma explicita, pero no ambigus.
• Separador ;.
• Columnes de mes o de menys amb error accionable.
• Linies buides ignorades o reportades de forma consistent.
• Emails repetits dins el CSV.
• Duplicats contra destinataris ja importats a la mateixa campanya.
• Respectar distinct_mails si esta activat.
• Marcar duplicats amb estat visible, per exemple avoid_duplicate a la linia i/o duplicate al recipient.
• No esborrar linies ni destinataris existents sense confirmacio clara, especialment per imports repetits.

Usabilitat i control

• Previsualitzacio abans de crear linies.
• Mostrar errors d'import amb numero de linia i missatge accionable.
• Poder descarregar o copiar un resum d'errors.
• Mostrar a la linia de campanya el destinatari i idioma encara que el ref apunti al dummy object.
• En mode CSV, List Related Objects hauria d'obrir els destinataris dummy o una vista equivalent pensada per revisar el CSV.
• Afegir filtres o agrupacions utils a destinataris/linies: estat, idioma, duplicat, error, email generat.
• Evitar botons confusos segons mode:
  • Filter Objects i Create Lines actuals nomes per mode objectes/domain.
  • Import/prevalidacio CSV nomes per mode destinataris CSV.
• Mantenir progressos de creacio/enviament coherents amb linies directes.

Integracio amb gisce/poweremail

No es necessari tocar gisce/poweremail per l'abast inicial si el model dummy es prou complet per fer de template.object_name.model.

La issue complementaria gisce/poweremail#217 queda com a alternativa futura/no bloquejant per si mes endavant es vol suportar generacio realment sense objecte. Per aquesta issue, el criteri preferent es no dependre d'aquest canvi.

Limitacions que cal deixar clares en aquesta primera versio:

• Les templates CSV han d'estar pensades per al model dummy.
• No s'han d'usar reports/adjunts que depenguin d'un objecte de negoci que no existeix.
• partner_event i callbacks de negoci no haurien d'aplicar en campanyes CSV tret que es defineixi explicitament un comportament segur.
• Company/from account s'ha de resoldre per configuracio de template/campanya, no derivant-la d'un objecte de negoci excepte si el dummy model incorpora un camp controlat per fer-ho.

Criteris d'acceptacio

• Es pot crear una campanya de destinataris directes important un CSV email;language.
• La importacio informa clarament files valides, invalides i duplicades abans de generar linies.
• Les files valides creen destinataris dummy i linies de campanya amb ref consistent.
• Les linies creades mostren email, idioma, estat, log/error i mail generat si existeix.
• L'enviament per batch funciona igual que en campanyes actuals.
• distinct_mails evita enviaments duplicats en aquest mode.
• El mode basat en objectes i domain continua funcionant igual.
• Les accions de UI que depenen d'objectes queden adaptades o protegides en campanyes CSV.
• La relacio amb gisce/poweremail#217 queda documentada com a futura/no bloquejant.

Tests esperats

• Import CSV valid.
• Error de capcalera/format.
• Columnes sobrants o faltants.
• Linies buides.
• Email invalid.
• Idioma invalid.
• Duplicats dins el CSV.
• Duplicats amb distinct_mails activat.
• Creacio de dummy recipients.
• Creacio de poweremail.campaign.line.ref contra el dummy recipient.
• Generacio/enviament amb template sobre ${object.email} i ${object.language}.
• Regressio del mode actual basat en domain.
• Proteccio o comportament de List Related Objects en mode CSV.

Fora d'abast inicial recomanat

• Personalitzacio massiva amb columnes arbitraries mes enlla de email i language.
• Segmentacio/filtres avancats sobre el CSV.
• Baixes/subscripcions i gestio legal de consentiment, tret que ja existeixi un model corporatiu clar on integrar-ho.
• Crear partners, adreces o objectes ERP a partir del CSV.
• Canviar el contracte base de gisce/poweremail.templates.
• Implementar generacio realment sense objecte origen al core gisce/poweremail.

[polsala]

@giscebot sense endinsarte gaire, modifica i refina aquesta issue amb el context necesari. Aprofita també per extendra la issue amb altres possibles millores de usabilitat, control i visualització.
Segurament també hauras de tenir en compte el repositori https://github.com/gisce/poweremail on i tenim les poweremail.templates.
No facis codi, només refina la issue i se fa falta creen tambe al repo https://github.com/gisce/poweremail

[giscebot]

He refinat la issue amb el context tecnic i funcional que faltava.

Canvis fets:

• He separat explicitament els dos modes de campanya: per objectes/domain i per destinataris directes via CSV.
• He afegit validacions, criteris d'acceptacio i punts de UX/control per previsualitzar errors, duplicats i resum per idioma.
• He marcat el risc tecnic important: el flux actual acaba a poweremail.templates.generate_mail(template_id, record_id), per tant no convé simular objectes ni crear ref falses.
• He creat la issue complementaria a gisce/poweremail per definir el contracte base de renderitzat/generacio sense objecte origen: Millora futura: permetre generar emails de template sense objecte origen poweremail#217

No he fet codi, tal com demanaves.

[polsala]

@giscebot torna a revisar la issue. Crec que per evitar problemes i errors humans i evitar tocar el modul gisce/poweremail seria millor tenir un dummy object per aquestes coses i ens estalviem problemes

[giscebot]

Revisat amb el criteri de dummy object.

He actualitzat el cos de la issue per canviar l'enfocament recomanat: en comptes de tocar gisce/poweremail per suportar generacio realment "sense objecte", fem un model dummy dins poweremail-modules (tipus poweremail.campaign.recipient) i fem que les templates CSV apuntin a aquest model.

Motiu: el flux actual ja encaixa millor amb generate_mail(template_id, record_id), get_value(...), campaign.line.ref, callbacks/progres i batch. Així evitem inventar un contracte nou al core i reduim risc operatiu. La issue gisce/poweremail#217 queda com a alternativa futura/no bloquejant, no com a dependencia d'aquesta feina.

Fitxers revisats per validar el criteri:

• poweremail_campaign/poweremail_campaign.py
• poweremail_campaign/poweremail_campaign_line.py
• gisce/poweremail/poweremail_template.py

[giscebot]

He revisat de nou la issue contra el codi actual de poweremail-modules i gisce/poweremail, i he refinat el cos de #75 amb el criteri definitiu per l'abast inicial: dummy object dins poweremail-modules, sense tocar el core gisce/poweremail.

Canvis principals afegits a la issue:

• notes tecniques validades contra poweremail_campaign.py, poweremail_campaign_line.py, wizard_poweremail_campaign.py i poweremail_template.py
• model dummy proposat (poweremail.campaign.recipient) amb camps/estats minimals
• flux funcional d'import, prevalidacio, confirmacio i creacio de linies
• proteccions UI per separar mode domain vs mode CSV
• criteris de validacio i tests mes concrets
• relacio amb gisce/poweremail#217 marcada com a futura/no bloquejant

Tambe he actualitzat gisce/poweremail#217 perquè no quedi com a dependencia accidental de la primera versio: gisce/poweremail#217

No he fet codi; aquesta passada era per deixar l'abast i el contracte ben tancats abans d'implementar.

[polsala]

@giscebot te assignat la issue, ja pots començar a programar

[giscebot]

He fet una primera implementacio petita seguint el criteri de dummy object, sense tocar gisce/poweremail.

PR: #76
Commit: 8bb3414

Que inclou:

• model poweremail.campaign.recipient per auditar destinataris CSV
• mode CSV a la campanya amb preview/import i resum de valides, invalides, duplicades i idiomes
• creacio de poweremail.campaign.line.ref real cap al dummy object
• duplicats amb linia avoid_duplicate i invalids guardats com a recipients sense linia
• List Related Objects obrint recipients en mode CSV
• tests de parseig/import CSV i regressio de la suite existent

Tests executats:

• destral -m poweremail_campaign -t TestPoweremailCampaign --dropdb --no-requirements
• destral -m poweremail_campaign -t TestPoweremailCampaign.test_import_csv_recipients_creates_dummy_refs_and_lines --dropdb --no-requirements

[giscebot]

Afegit un reforç petit a la PR perquè les accions d’import CSV comprovin també campaign_mode == csv, no només que la template apunti al dummy object. Això evita que una campanya d’objectes amb una template dummy pugui executar preview/import CSV per error.

PR: #76
Commit: 5fddc1b

Tests executats després del canvi:

• destral -m poweremail_campaign -t TestPoweremailCampaign.test_csv_import_requires_csv_campaign_mode --dropdb --no-requirements
• destral -m poweremail_campaign -t TestPoweremailCampaign --dropdb --no-requirements (10 tests, OK)

La PR continua oberta i mergeable; queda pendent de review.

[giscebot]

He afegit un reforç de tests al PR #76:

• 09a84fd cobreix capçaleres CSV incorrectes i files amb nombre de columnes invàlid.
• He tornat a executar destral -m poweremail_campaign -t TestPoweremailCampaign --dropdb --no-requirements: 11 tests OK.
• El cos del PR queda actualitzat amb els guards i la cobertura final. GitHub encara no reporta checks automàtics per aquesta branca.

PR: #76

[giscebot]

He fet una passada extra de mantenidor sobre el PR #76 i he ajustat un detall de semàntica:

• 8d686f9 fa que els duplicats del CSV respectin distinct_mails: si està activat, la línia duplicada queda avoid_duplicate; si no, queda to_send, igual que el mode actual basat en domain.
• Els recipients duplicats continuen quedant visibles com a duplicate per auditoria/import.
• He afegit test explícit pel cas distinct_mails=False.

Tests executats:

• destral -m poweremail_campaign -t TestPoweremailCampaign --dropdb --no-requirements (12 tests, OK)

PR: #76