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-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`.
|
||||
> 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
|
||||
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
<!-- codex-wiki-sync:cb6acffba8b788d578627d6c -->
|
||||
<!-- codex-wiki-sync:78ae6d85ea87bbee66d840be -->
|
||||
|
||||
> 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.
|
||||
|
||||
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