Sync wiki from project files
@@ -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-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-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`
|
||||||
|
|||||||
@@ -1,4 +1,4 @@
|
|||||||
<!-- codex-wiki-sync:68ca87c22d6904a6c13ed735 -->
|
<!-- codex-wiki-sync:df5f8929065e25dec9d0042c -->
|
||||||
|
|
||||||
> Mirrored from `/mnt/DATA/git/govoplan-campaign/README.md`.
|
> Mirrored from `/mnt/DATA/git/govoplan-campaign/README.md`.
|
||||||
> Origin: `repository`.
|
> 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.
|
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
|
## Development
|
||||||
|
|
||||||
Install through the core environment:
|
Install through the core environment:
|
||||||
@@ -71,6 +84,11 @@ Platform RBAC and governance rules are documented in `govoplan-core/docs/`.
|
|||||||
## Operations
|
## 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.
|
- [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
|
## Release packaging
|
||||||
|
|
||||||
|
|||||||
@@ -1,4 +1,4 @@
|
|||||||
<!-- codex-wiki-sync:cb6acffba8b788d578627d6c -->
|
<!-- codex-wiki-sync:78ae6d85ea87bbee66d840be -->
|
||||||
|
|
||||||
> Mirrored from `/mnt/DATA/git/govoplan-campaign/docs/CAMPAIGN_DELIVERY_RUNBOOK.md`.
|
> Mirrored from `/mnt/DATA/git/govoplan-campaign/docs/CAMPAIGN_DELIVERY_RUNBOOK.md`.
|
||||||
> Origin: `repository`.
|
> Origin: `repository`.
|
||||||
@@ -22,6 +22,8 @@ been validated, built, reviewed, and locked.
|
|||||||
## Before First Live Use
|
## Before First Live Use
|
||||||
|
|
||||||
- Use dedicated non-production SMTP/IMAP credentials.
|
- 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.
|
- Use a dedicated mailbox/folder for append-to-Sent tests.
|
||||||
- Confirm policy allows the SMTP host, envelope sender, recipients, and optional
|
- Confirm policy allows the SMTP host, envelope sender, recipients, and optional
|
||||||
IMAP append target.
|
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
|
- Keep the report page open during tests; it is the operational source of truth
|
||||||
for attempts, outcomes, and reconciliation.
|
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
|
## Queue And Send
|
||||||
|
|
||||||
1. Validate the version with file checks enabled.
|
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.
|
- Accepted and unknown jobs must not appear in retry selections.
|
||||||
- Reconciled accepted jobs must remain protected from resend.
|
- Reconciled accepted jobs must remain protected from resend.
|
||||||
- Reconciled not-sent jobs must appear only as explicit retry candidates.
|
- Reconciled not-sent jobs must appear only as explicit retry candidates.
|
||||||
- The final report should include SMTP attempts, IMAP append attempts, and any
|
- The final CSV export should include message id, resolved envelope headers,
|
||||||
reconciliation notes before the campaign is considered operationally closed.
|
attachment evidence, EML reference/checksum, latest SMTP response/error, and
|
||||||
|
latest IMAP folder/error before the campaign is considered operationally
|
||||||
|
closed.
|
||||||
|
|||||||
83
Repo-docs-EXAMPLE-CAMPAIGNS-AND-RELEASE-CHECKLIST.md
Normal file
83
Repo-docs-EXAMPLE-CAMPAIGNS-AND-RELEASE-CHECKLIST.md
Normal file
@@ -0,0 +1,83 @@
|
|||||||
|
<!-- codex-wiki-sync:195e5c4496c29869d7f4754f -->
|
||||||
|
|
||||||
|
> 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.
|
||||||
71
Repo-docs-RECIPIENT-ADDRESS-BOUNDARY.md
Normal file
71
Repo-docs-RECIPIENT-ADDRESS-BOUNDARY.md
Normal file
@@ -0,0 +1,71 @@
|
|||||||
|
<!-- codex-wiki-sync:5a6278c6a4d418ed38146d19 -->
|
||||||
|
|
||||||
|
> 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.
|
||||||
94
Repo-docs-RECIPIENT-IMPORT-GUIDE.md
Normal file
94
Repo-docs-RECIPIENT-IMPORT-GUIDE.md
Normal file
@@ -0,0 +1,94 @@
|
|||||||
|
<!-- codex-wiki-sync:aecb03fa6c6443652f4da9f6 -->
|
||||||
|
|
||||||
|
> 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.
|
||||||
Reference in New Issue
Block a user