96 lines
4.5 KiB
Markdown
96 lines
4.5 KiB
Markdown
# govoplan-campaign
|
|
|
|
<!-- govoplan-repository-type:start -->
|
|
**Repository type:** module (domain).
|
|
<!-- govoplan-repository-type:end -->
|
|
|
|
GovOPlaN Campaign is the campaign authoring, validation, review, sending-control, and reporting module. It bundles backend campaign APIs with the campaign WebUI package.
|
|
|
|
## Ownership
|
|
|
|
This repository owns:
|
|
|
|
- backend module manifest `campaigns`
|
|
- campaign, recipient, report, and campaign-audit permissions
|
|
- campaign/version/job/issue/send-attempt/append-attempt models and migrations
|
|
- campaign JSON schema, validation, message building, attachment resolution, ZIP handling, reports, queue/control services, and mock-send paths
|
|
- WebUI package `@govoplan/campaign-webui`
|
|
- route contributions for `/campaigns`, `/campaigns/:campaignId/*`, `/operator`, `/reports`, and `/templates`
|
|
|
|
Core owns the auth facade, RBAC/capability contracts, database/session
|
|
primitives, CSRF/API helpers, shell layout, and route rendering. Tenancy is an
|
|
optional platform module for tenant administration and tenant resolver behavior.
|
|
Files and mail own their respective storage and transport capabilities.
|
|
|
|
## Dependencies
|
|
|
|
The module has one required runtime dependency:
|
|
|
|
- `govoplan-core` for platform services, auth, RBAC, DB/session lifecycle, migrations, and WebUI shell integration
|
|
|
|
Files and mail are optional module integrations declared in the campaign manifest:
|
|
|
|
- `govoplan-files` enables managed attachment selection, frozen file-version evidence, and managed-file usage tracking. Without it, campaigns can still use legacy/local attachment paths where configured.
|
|
- `govoplan-mail` enables reusable mail profiles, delivery policy checks, SMTP sending, and IMAP append behavior. Without it, campaigns can still be authored, validated, built, and reported, but real delivery/profile features are unavailable.
|
|
|
|
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:
|
|
|
|
```bash
|
|
cd /mnt/DATA/git/govoplan-core
|
|
./.venv/bin/python -m pip install -r requirements-dev.txt
|
|
```
|
|
|
|
Run the WebUI from the core host:
|
|
|
|
```bash
|
|
cd /mnt/DATA/git/govoplan-core/webui
|
|
PATH=/home/zemion/.nvm/versions/node/v22.22.3/bin:$PATH /home/zemion/.nvm/versions/node/v22.22.3/bin/npm run dev
|
|
```
|
|
|
|
## Module integration
|
|
|
|
Backend entry point:
|
|
|
|
```toml
|
|
[project.entry-points."govoplan.modules"]
|
|
campaigns = "govoplan_campaign.backend.manifest:get_manifest"
|
|
```
|
|
|
|
Frontend package:
|
|
|
|
```text
|
|
@govoplan/campaign-webui
|
|
```
|
|
|
|
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
|
|
|
|
The repository root includes a `package.json` for git-based WebUI installs. It exports the package `@govoplan/campaign-webui` from `webui/src` so release builds can depend on tagged git refs instead of local `file:` paths. Files and mail WebUI packages remain optional product-composition dependencies supplied by the core host build, not required campaign package dependencies.
|