diff --git a/Codex-Project-Index.md b/Codex-Project-Index.md index 9138da6..5d1e4e0 100644 --- a/Codex-Project-Index.md +++ b/Codex-Project-Index.md @@ -6,3 +6,6 @@ This page is generated from repository and product-directory project files. - [Repo-README](Repo-README) - `/mnt/DATA/git/govoplan-campaign/README.md` - [Repo-docs-CAMPAIGN-DELIVERY-RUNBOOK](Repo-docs-CAMPAIGN-DELIVERY-RUNBOOK) - `/mnt/DATA/git/govoplan-campaign/docs/CAMPAIGN_DELIVERY_RUNBOOK.md` +- [Repo-docs-EXAMPLE-CAMPAIGNS-AND-RELEASE-CHECKLIST](Repo-docs-EXAMPLE-CAMPAIGNS-AND-RELEASE-CHECKLIST) - `/mnt/DATA/git/govoplan-campaign/docs/EXAMPLE_CAMPAIGNS_AND_RELEASE_CHECKLIST.md` +- [Repo-docs-RECIPIENT-ADDRESS-BOUNDARY](Repo-docs-RECIPIENT-ADDRESS-BOUNDARY) - `/mnt/DATA/git/govoplan-campaign/docs/RECIPIENT_ADDRESS_BOUNDARY.md` +- [Repo-docs-RECIPIENT-IMPORT-GUIDE](Repo-docs-RECIPIENT-IMPORT-GUIDE) - `/mnt/DATA/git/govoplan-campaign/docs/RECIPIENT_IMPORT_GUIDE.md` diff --git a/Repo-README.md b/Repo-README.md index d4a686d..c8e2123 100644 --- a/Repo-README.md +++ b/Repo-README.md @@ -1,4 +1,4 @@ - + > Mirrored from `/mnt/DATA/git/govoplan-campaign/README.md`. > Origin: `repository`. @@ -35,6 +35,19 @@ Files and mail are optional module integrations declared in the campaign manifes Backend optional behavior is accessed through core-provided capabilities, not direct required imports. WebUI optional behavior uses core module metadata/capabilities so campaign pages can build and run without files or mail WebUI packages installed. +Campaign also provides narrow kernel capabilities so other modules and core +services can cooperate without importing campaign internals: + +- `campaigns.access` for campaign share/existence checks +- `campaigns.mailPolicyContext` for campaign-scoped mail policy and owner + context +- `campaigns.policyContext` for retention/policy provenance +- `campaigns.deliveryTasks` for queued send and append-to-Sent workers +- `campaigns.retention` for campaign-owned retention cleanup + +Keep these capability payloads narrow: stable ids, policy payloads, and task +results only. + ## Development Install through the core environment: @@ -71,6 +84,11 @@ Platform RBAC and governance rules are documented in `govoplan-core/docs/`. ## Operations - [Campaign delivery runbook](docs/CAMPAIGN_DELIVERY_RUNBOOK.md) covers queueing, local vs Celery operation, retries, reconciliation, reports, and the live SMTP/IMAP test checklist. +- [Recipient import guide](docs/RECIPIENT_IMPORT_GUIDE.md) covers user/admin workflows, mapping profiles, validation, and import evidence. +- [Recipient and address boundary](docs/RECIPIENT_ADDRESS_BOUNDARY.md) defines the split between campaign-local recipients and future reusable address management. +- [Example campaigns and release checklist](docs/EXAMPLE_CAMPAIGNS_AND_RELEASE_CHECKLIST.md) defines the maintained example scenarios and release gates. +- [Campaign examples](examples/README.md) is the credential-free scenario catalogue that release fixtures must follow. +- [SMTP/IMAP test bed](dev/mail-testbed/README.md) provides the GreenMail Docker Compose setup and transport smoke for dedicated non-production delivery tests. ## Release packaging diff --git a/Repo-docs-CAMPAIGN-DELIVERY-RUNBOOK.md b/Repo-docs-CAMPAIGN-DELIVERY-RUNBOOK.md index c629014..0892898 100644 --- a/Repo-docs-CAMPAIGN-DELIVERY-RUNBOOK.md +++ b/Repo-docs-CAMPAIGN-DELIVERY-RUNBOOK.md @@ -1,4 +1,4 @@ - + > Mirrored from `/mnt/DATA/git/govoplan-campaign/docs/CAMPAIGN_DELIVERY_RUNBOOK.md`. > Origin: `repository`. @@ -22,6 +22,8 @@ been validated, built, reviewed, and locked. ## Before First Live Use - Use dedicated non-production SMTP/IMAP credentials. +- Start the repository test bed in `dev/mail-testbed/` when a local + production-like SMTP/IMAP server is sufficient. - Use a dedicated mailbox/folder for append-to-Sent tests. - Confirm policy allows the SMTP host, envelope sender, recipients, and optional IMAP append target. @@ -30,6 +32,23 @@ been validated, built, reviewed, and locked. - Keep the report page open during tests; it is the operational source of truth for attempts, outcomes, and reconciliation. +## Deliverability Preflight + +Before the first live send for a sender domain or mail-server profile: + +- Confirm the selected SMTP identity matches the visible From/envelope sender + policy. +- Confirm SPF, DKIM, and DMARC are handled by the sending infrastructure or + documented as out of scope for the selected test environment. +- Confirm rate limits are explicitly set for the expected provider and recipient + volume. +- Confirm bounce/reply/notification addresses are monitored by an operational + mailbox or intentionally disabled. +- Confirm large attachments and password-protected ZIPs are acceptable for the + recipient systems. +- Confirm owner transfer or policy changes force profile reselection and + revalidation before live delivery. + ## Queue And Send 1. Validate the version with file checks enabled. @@ -80,5 +99,7 @@ bed where possible: - Accepted and unknown jobs must not appear in retry selections. - Reconciled accepted jobs must remain protected from resend. - Reconciled not-sent jobs must appear only as explicit retry candidates. -- The final report should include SMTP attempts, IMAP append attempts, and any - reconciliation notes before the campaign is considered operationally closed. +- The final CSV export should include message id, resolved envelope headers, + attachment evidence, EML reference/checksum, latest SMTP response/error, and + latest IMAP folder/error before the campaign is considered operationally + closed. diff --git a/Repo-docs-EXAMPLE-CAMPAIGNS-AND-RELEASE-CHECKLIST.md b/Repo-docs-EXAMPLE-CAMPAIGNS-AND-RELEASE-CHECKLIST.md new file mode 100644 index 0000000..af4ee30 --- /dev/null +++ b/Repo-docs-EXAMPLE-CAMPAIGNS-AND-RELEASE-CHECKLIST.md @@ -0,0 +1,83 @@ + + +> Mirrored from `/mnt/DATA/git/govoplan-campaign/docs/EXAMPLE_CAMPAIGNS_AND_RELEASE_CHECKLIST.md`. +> Origin: `repository`. +> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context. + +--- +# Example Campaigns And Release Checklist + +This document defines the campaign examples and release gates that should be +kept working before a GovOPlaN Campaign release is tagged. + +## Example Campaign Set + +Maintain fixtures or guided examples for these scenarios. The canonical +scenario catalogue lives in `examples/README.md`; committed fixture files should +be added under `examples/` only when they validate against the current campaign +schema and are safe to run in non-production environments. + +- simple announcement with one active recipient and no attachments +- multi-recipient message with To, CC, BCC, Reply-To, bounce, and disposition + notification fields +- campaign with global attachments and recipient-specific attachment rules +- campaign with password-protected ZIP attachments +- campaign using a reusable mail profile from the mail module +- campaign using inline SMTP/IMAP settings where policy allows campaign-local + settings +- campaign with validation warnings that may be sent only after explicit review +- campaign with blocked recipients or attachment errors that must not be sent +- mock delivery campaign that captures SMTP and IMAP append messages in the mail + development mailbox +- real non-production delivery campaign against the GreenMail test bed + +## Fixture Rules + +- Examples must not contain production recipient data or production credentials. +- Attachment examples should use deterministic small files and checksums. +- Secret values must be represented through saved-credential placeholders or + secret references. +- Examples that require optional modules must declare the required modules and + capabilities in their README or fixture metadata. +- Examples must stay valid when files or mail modules are physically absent, + with optional behavior disabled instead of import failures. + +## Release Gates + +Before tagging a campaign release: + +- Review `examples/README.md` and update the scenario catalogue when a release + adds or removes delivery behavior. +- Run core module permutation tests with campaign installed both with and + without files/mail. +- Validate and build each maintained example campaign. +- Run the mock delivery example when the mail development mailbox capability is + enabled. +- Run the GreenMail SMTP/IMAP smoke for a non-production real delivery path. +- Confirm reusable mail profile selection is revalidated after campaign owner + transfer. +- Confirm inline SMTP/IMAP settings are hidden or blocked when policy disables + campaign-local mail settings. +- Confirm delivery reports include SMTP outcome, IMAP append outcome, latest + error, generated EML reference, and attachment evidence. +- Confirm retries cannot resend messages already accepted by SMTP unless an + explicit reconciliation path allows it. + +## Ownership Transfer Check + +Reusable user/group mail profiles are owner-context-sensitive. When campaign +ownership changes, the editable current version must require profile reselection +and validation before live delivery. A locked delivery-final version should not +be silently rewritten. + +## Delivery Checklist + +Use the Review & Send preflight panel and the delivery runbook together: + +1. Validate and resolve all blocking policy/data issues. +2. Build exact messages. +3. Review warnings, generated recipients, body content, and attachment evidence. +4. Run mock delivery if available for the release channel. +5. Test SMTP and IMAP settings against non-production infrastructure. +6. Send only after queue, rate limit, and append-to-Sent behavior are understood. +7. Reconcile failed, unknown, or pending jobs from the report/audit surfaces. diff --git a/Repo-docs-RECIPIENT-ADDRESS-BOUNDARY.md b/Repo-docs-RECIPIENT-ADDRESS-BOUNDARY.md new file mode 100644 index 0000000..763c43f --- /dev/null +++ b/Repo-docs-RECIPIENT-ADDRESS-BOUNDARY.md @@ -0,0 +1,71 @@ + + +> Mirrored from `/mnt/DATA/git/govoplan-campaign/docs/RECIPIENT_ADDRESS_BOUNDARY.md`. +> Origin: `repository`. +> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context. + +--- +# Recipient And Address Management Boundary + +Campaigns currently own campaign-local recipient entries because sending and +reporting need a frozen recipient snapshot. Long-lived address management is a +separate domain and should move to `govoplan-addresses`. + +## `govoplan-campaign` Owns + +- campaign-local recipient entries +- campaign-local recipient import mapping and validation +- message addressing for a concrete campaign version +- send/build/report evidence for the exact recipients used +- campaign-local exclusions, warnings, and review status +- recipient-specific attachment and template evidence + +Campaign data is immutable once a version is built for sending. Later address +book changes must not rewrite historical campaign evidence. + +## `govoplan-addresses` Should Own + +- Adrema-style address management +- reusable person, organization, household, and postal-address records +- reusable email address lists and segments +- postal-letter recipient views +- consent, legal-basis, and communication-preference metadata +- deduplication and merge workflows +- import/export of reusable address directories +- address quality checks and change history + +The addresses module should provide stable DTOs and capabilities that campaigns, +mail, forms, reporting, portal, and postbox modules can consume without direct +imports. + +## Integration Contract + +The campaign module should ask the platform whether the addresses module is +installed. When present, campaign can offer address-source choices through a +capability such as `addresses.recipientSource`. + +The capability should return snapshots, not live ORM objects: + +- selected source id and display label +- normalized recipient rows +- provenance fields for source, segment, legal basis, and import time +- update markers so campaigns can show whether a draft is based on stale source + data + +Campaign stores the resolved snapshot in the campaign version. It may keep a +reference to the address source for traceability, but the built campaign remains +auditable even if the address source changes later. + +## Non-Goals For Campaign + +Campaign should not become the global address book. It should not own: + +- deduplication across campaigns +- consent lifecycle +- master-data merge policy +- address-directory permissions beyond campaign use +- postal address normalization +- reusable segmentation rules + +Those belong in `govoplan-addresses` or a dedicated records/identity module when +the domain needs stronger governance. diff --git a/Repo-docs-RECIPIENT-IMPORT-GUIDE.md b/Repo-docs-RECIPIENT-IMPORT-GUIDE.md new file mode 100644 index 0000000..e7f04a6 --- /dev/null +++ b/Repo-docs-RECIPIENT-IMPORT-GUIDE.md @@ -0,0 +1,94 @@ + + +> Mirrored from `/mnt/DATA/git/govoplan-campaign/docs/RECIPIENT_IMPORT_GUIDE.md`. +> Origin: `repository`. +> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context. + +--- +# Recipient Import Guide + +Recipient import lets campaign authors turn spreadsheet-like source data into +campaign-local recipient entries. It is intentionally campaign-local today: +reusable address books and Adrema-style address management belong in the future +`govoplan-addresses` module. + +## Supported Inputs + +The current importer is designed for tabular data with a header row. CSV and +spreadsheet-derived tables should be normalized before import so the campaign UI +sees: + +- column headers +- row values +- source filename and sheet name when available +- a stable ordered and unordered header fingerprint + +Avoid importing production secrets or credentials as recipient fields. Recipient +custom fields may be used in templates and reports, so they should be treated as +campaign data. + +## Mapping Fields + +Common headers are detected automatically: + +- `email`, `e_mail`, `mail`, `to`, `to_email`, `recipient`, + `recipient_email` +- `name`, `full_name`, `recipient_name`, `to_name` +- `id`, `entry_id`, `recipient_id` + +Authors can map columns to address fields: + +- `from` +- `to` +- `cc` +- `bcc` +- `reply_to` + +Rows without a valid `to` address should remain visible with validation issues +instead of disappearing silently. Authors should be able to fix the source file, +adjust the mapping, or exclude the row before building the campaign. + +## Mapping Profiles + +Mapping profiles save a known column layout so repeated imports can reuse the +same mapping. The importer stores ordered and unordered header fingerprints so a +profile can distinguish exact column order from equivalent column sets. + +Administrators should curate shared profiles only for stable recurring sources. +Campaign-local profiles are acceptable for one-off work and experiments. + +## User Workflow + +1. Open the campaign recipient/data import screen. +2. Upload or paste a tabular source. +3. Review detected headers and preview rows. +4. Pick or adjust a mapping profile. +5. Confirm validation issues, exclusions, and generated recipient ids. +6. Import into the campaign draft. +7. Build messages and review recipient-specific evidence before sending. + +## Admin Workflow + +Administrators should: + +- define naming conventions for recurring mapping profiles +- verify that imported fields have a lawful processing basis for the campaign +- keep reusable address-directory ownership out of campaigns until + `govoplan-addresses` owns that domain +- use campaign reports and audit evidence to trace which source produced which + recipient entries +- remove obsolete shared profiles when an upstream source layout changes + +## Evidence Expectations + +The campaign should preserve enough evidence to explain a send: + +- source filename and sheet name where available +- header fingerprints +- mapping profile id/name when used +- row number or source id +- validation status and exclusion reason +- final recipient addresses used for the built message + +The evidence should be available in reports without requiring the original +source file to be reprocessed.