593 lines
32 KiB
Python
593 lines
32 KiB
Python
from __future__ import annotations
|
|
|
|
from pathlib import Path
|
|
|
|
from govoplan_core.core.access import CAPABILITY_AUTH_PERMISSION_EVALUATOR, CAPABILITY_AUTH_PRINCIPAL_RESOLVER
|
|
from govoplan_core.core.campaigns import (
|
|
CAPABILITY_CAMPAIGNS_ACCESS,
|
|
CAPABILITY_CAMPAIGNS_DELIVERY_TASKS,
|
|
CAPABILITY_CAMPAIGNS_MAIL_POLICY_CONTEXT,
|
|
CAPABILITY_CAMPAIGNS_POLICY_CONTEXT,
|
|
CAPABILITY_CAMPAIGNS_RETENTION,
|
|
)
|
|
from govoplan_core.core.module_guards import drop_table_retirement_provider, persistent_table_uninstall_guard
|
|
from govoplan_core.core.modules import (
|
|
DocumentationCondition,
|
|
DocumentationLink,
|
|
DocumentationTopic,
|
|
FrontendModule,
|
|
MigrationSpec,
|
|
ModuleContext,
|
|
ModuleInterfaceProvider,
|
|
ModuleInterfaceRequirement,
|
|
ModuleManifest,
|
|
NavItem,
|
|
PermissionDefinition,
|
|
RoleTemplate,
|
|
)
|
|
from govoplan_core.db.base import Base
|
|
from govoplan_campaign.backend.change_tracking import register_campaign_change_tracking
|
|
from govoplan_campaign.backend.db import models as campaign_models # noqa: F401 - populate Campaign ORM metadata
|
|
from govoplan_campaign.backend.documentation import CAMPAIGN_USER_DOCUMENTATION, documentation_topics
|
|
|
|
register_campaign_change_tracking()
|
|
|
|
|
|
def _permission(scope: str, label: str, description: str, category: str) -> PermissionDefinition:
|
|
module_id, resource, action = scope.split(":", 2)
|
|
return PermissionDefinition(
|
|
scope=scope,
|
|
label=label,
|
|
description=description,
|
|
category=category,
|
|
level="tenant",
|
|
module_id=module_id,
|
|
resource=resource,
|
|
action=action,
|
|
)
|
|
|
|
|
|
PERMISSIONS = (
|
|
_permission("campaigns:campaign:read", "View campaigns", "Open campaign metadata, versions and permitted message summaries.", "Campaigns"),
|
|
_permission("campaigns:campaign:create", "Create campaigns", "Create new campaigns in an accessible tenant scope.", "Campaigns"),
|
|
_permission("campaigns:campaign:update", "Edit campaigns", "Edit current working campaign versions.", "Campaigns"),
|
|
_permission("campaigns:campaign:copy", "Copy campaigns", "Create campaigns or working versions from existing campaigns.", "Campaigns"),
|
|
_permission("campaigns:campaign:archive", "Archive campaigns", "Archive campaigns without destroying audit evidence.", "Campaigns"),
|
|
_permission("campaigns:campaign:delete", "Delete campaigns", "Delete draft-only campaigns where retention policy allows it.", "Campaigns"),
|
|
_permission("campaigns:campaign:share", "Share campaigns", "Grant or revoke explicit campaign access.", "Campaigns"),
|
|
_permission("campaigns:campaign:validate", "Validate campaigns", "Run technical validation and manage validation locks.", "Campaigns"),
|
|
_permission("campaigns:campaign:build", "Build campaigns", "Build exact messages and attachment evidence.", "Campaigns"),
|
|
_permission("campaigns:campaign:review", "Complete campaign review", "Record review completion and the exact built messages inspected.", "Campaigns"),
|
|
_permission("campaigns:campaign:send_test", "Mock-send campaigns", "Use mock delivery and verification tools.", "Campaigns"),
|
|
_permission("campaigns:campaign:queue", "Queue campaigns", "Place approved executions into the delivery queue.", "Campaigns"),
|
|
_permission("campaigns:campaign:control", "Control delivery", "Pause, resume or cancel queued and sending jobs.", "Campaigns"),
|
|
_permission("campaigns:campaign:send", "Send campaigns", "Start real SMTP delivery.", "Campaigns"),
|
|
_permission("campaigns:campaign:retry", "Retry delivery", "Retry failed or unattempted delivery jobs.", "Campaigns"),
|
|
_permission("campaigns:campaign:reconcile", "Reconcile delivery", "Resolve outcome-unknown SMTP or IMAP attempts after inspection.", "Campaigns"),
|
|
_permission("campaigns:diagnostic:read", "View campaign diagnostics", "Inspect worker claims and internal storage locators for campaign delivery troubleshooting.", "Campaign operations"),
|
|
_permission("campaigns:recipient:read", "View recipients", "Read recipient lists and recipient-specific campaign data.", "Recipients"),
|
|
_permission("campaigns:recipient:write", "Edit recipients", "Create and edit recipient rows and field values.", "Recipients"),
|
|
_permission("campaigns:recipient:import", "Import recipients", "Bulk-import recipient lists.", "Recipients"),
|
|
_permission("campaigns:recipient:export", "Export recipients", "Export recipient data and reports.", "Recipients"),
|
|
_permission("campaigns:report:read", "View reports", "View campaign delivery reports and aggregate outcomes.", "Reports"),
|
|
_permission("campaigns:report:export", "Export reports", "Download detailed campaign reports.", "Reports"),
|
|
_permission("campaigns:report:send", "Send reports", "Email campaign reports to configured recipients.", "Reports"),
|
|
)
|
|
|
|
ROLE_TEMPLATES = (
|
|
RoleTemplate(
|
|
slug="campaign_manager",
|
|
name="Campaign manager",
|
|
description="Prepare, validate and build campaigns without approving real delivery.",
|
|
permissions=(
|
|
"campaigns:campaign:read",
|
|
"campaigns:campaign:create",
|
|
"campaigns:campaign:update",
|
|
"campaigns:campaign:copy",
|
|
"campaigns:campaign:validate",
|
|
"campaigns:campaign:build",
|
|
"campaigns:recipient:read",
|
|
"campaigns:recipient:write",
|
|
"campaigns:recipient:import",
|
|
"campaigns:report:read",
|
|
),
|
|
),
|
|
RoleTemplate(
|
|
slug="campaign_reviewer",
|
|
name="Campaign reviewer",
|
|
description="Inspect prepared campaign messages and record review completion.",
|
|
permissions=(
|
|
"campaigns:campaign:read",
|
|
"campaigns:campaign:validate",
|
|
"campaigns:campaign:review",
|
|
"campaigns:recipient:read",
|
|
"campaigns:report:read",
|
|
),
|
|
),
|
|
RoleTemplate(
|
|
slug="campaign_sender",
|
|
name="Campaign sender",
|
|
description="Queue, test, control, send and reconcile prepared campaigns.",
|
|
permissions=(
|
|
"campaigns:campaign:read",
|
|
"campaigns:campaign:send_test",
|
|
"campaigns:campaign:queue",
|
|
"campaigns:campaign:control",
|
|
"campaigns:campaign:send",
|
|
"campaigns:campaign:retry",
|
|
"campaigns:campaign:reconcile",
|
|
"campaigns:diagnostic:read",
|
|
"campaigns:recipient:read",
|
|
"campaigns:report:read",
|
|
"campaigns:report:send",
|
|
),
|
|
),
|
|
)
|
|
|
|
|
|
def _tenant_summary(session, tenant_id: str) -> dict[str, int]:
|
|
from govoplan_campaign.backend.db.models import Campaign
|
|
|
|
return {"campaigns": session.query(Campaign).filter(Campaign.tenant_id == tenant_id).count()}
|
|
|
|
|
|
def _campaigns_router(context: ModuleContext):
|
|
from govoplan_campaign.backend.runtime import configure_runtime
|
|
|
|
configure_runtime(registry=context.registry, settings=context.settings)
|
|
from fastapi import APIRouter
|
|
from govoplan_campaign.backend.router import router
|
|
from govoplan_campaign.backend.schema_router import router as schema_router
|
|
|
|
aggregate = APIRouter()
|
|
aggregate.include_router(router)
|
|
aggregate.include_router(schema_router)
|
|
return aggregate
|
|
|
|
|
|
manifest = ModuleManifest(
|
|
id="campaigns",
|
|
name="Campaigns",
|
|
version="0.1.9",
|
|
required_capabilities=(CAPABILITY_AUTH_PRINCIPAL_RESOLVER, CAPABILITY_AUTH_PERMISSION_EVALUATOR),
|
|
optional_dependencies=("files", "mail", "notifications", "addresses"),
|
|
provides_interfaces=(
|
|
ModuleInterfaceProvider(name="campaigns.access", version="0.1.6"),
|
|
ModuleInterfaceProvider(name="campaigns.delivery_tasks", version="0.1.6"),
|
|
ModuleInterfaceProvider(name="campaigns.mail_policy_context", version="0.1.6"),
|
|
ModuleInterfaceProvider(name="campaigns.policy_context", version="0.1.6"),
|
|
ModuleInterfaceProvider(name="campaigns.retention", version="0.1.6"),
|
|
),
|
|
requires_interfaces=(
|
|
ModuleInterfaceRequirement(
|
|
name="files.campaign_attachments",
|
|
version_min="0.1.0",
|
|
version_max_exclusive="0.2.0",
|
|
optional=True,
|
|
),
|
|
ModuleInterfaceRequirement(
|
|
name="mail.campaign_delivery",
|
|
version_min="0.2.0",
|
|
version_max_exclusive="0.3.0",
|
|
optional=True,
|
|
),
|
|
ModuleInterfaceRequirement(
|
|
name="addresses.lookup",
|
|
version_min="0.1.0",
|
|
version_max_exclusive="0.2.0",
|
|
optional=True,
|
|
),
|
|
ModuleInterfaceRequirement(
|
|
name="addresses.recipient_source",
|
|
version_min="0.1.0",
|
|
version_max_exclusive="0.2.0",
|
|
optional=True,
|
|
),
|
|
),
|
|
permissions=PERMISSIONS,
|
|
route_factory=_campaigns_router,
|
|
role_templates=ROLE_TEMPLATES,
|
|
tenant_summary_providers=(_tenant_summary,),
|
|
nav_items=(
|
|
NavItem(path="/campaigns", label="Campaigns", icon="campaign", required_any=("campaigns:campaign:read",), order=20),
|
|
NavItem(
|
|
path="/operator",
|
|
label="Operator Queue",
|
|
icon="radio-tower",
|
|
required_any=(
|
|
"campaigns:campaign:queue",
|
|
"campaigns:campaign:retry",
|
|
"campaigns:campaign:reconcile",
|
|
"campaigns:campaign:control",
|
|
"campaigns:campaign:send",
|
|
),
|
|
order=30,
|
|
),
|
|
NavItem(path="/reports", label="Reports", icon="clipboard-pen-line", required_any=("campaigns:report:read",), order=70),
|
|
),
|
|
frontend=FrontendModule(
|
|
module_id="campaigns",
|
|
package_name="@govoplan/campaign-webui",
|
|
nav_items=(
|
|
NavItem(path="/campaigns", label="Campaigns", icon="campaign", required_any=("campaigns:campaign:read",), order=20),
|
|
NavItem(
|
|
path="/operator",
|
|
label="Operator Queue",
|
|
icon="radio-tower",
|
|
required_any=(
|
|
"campaigns:campaign:queue",
|
|
"campaigns:campaign:retry",
|
|
"campaigns:campaign:reconcile",
|
|
"campaigns:campaign:control",
|
|
"campaigns:campaign:send",
|
|
),
|
|
order=30,
|
|
),
|
|
NavItem(path="/reports", label="Reports", icon="clipboard-pen-line", required_any=("campaigns:report:read",), order=70),
|
|
NavItem(path="/templates", label="Templates", icon="layout-template", order=90),
|
|
),
|
|
),
|
|
migration_spec=MigrationSpec(
|
|
module_id="campaigns",
|
|
metadata=Base.metadata,
|
|
script_location=str(Path(__file__).with_name("migrations") / "versions"),
|
|
retirement_supported=True,
|
|
retirement_provider=drop_table_retirement_provider(
|
|
campaign_models.Campaign,
|
|
campaign_models.CampaignShare,
|
|
campaign_models.RecipientImportMappingProfile,
|
|
campaign_models.CampaignVersion,
|
|
campaign_models.CampaignJob,
|
|
campaign_models.CampaignIssue,
|
|
campaign_models.AttachmentBlob,
|
|
campaign_models.AttachmentInstance,
|
|
campaign_models.SendAttempt,
|
|
campaign_models.ImapAppendAttempt,
|
|
label="Campaigns",
|
|
),
|
|
retirement_notes="Destructive retirement drops campaign-owned database tables after the installer captures a database snapshot.",
|
|
),
|
|
uninstall_guard_providers=(
|
|
persistent_table_uninstall_guard(
|
|
campaign_models.Campaign,
|
|
campaign_models.CampaignShare,
|
|
campaign_models.RecipientImportMappingProfile,
|
|
campaign_models.CampaignVersion,
|
|
campaign_models.CampaignJob,
|
|
campaign_models.CampaignIssue,
|
|
campaign_models.AttachmentBlob,
|
|
campaign_models.AttachmentInstance,
|
|
campaign_models.SendAttempt,
|
|
campaign_models.ImapAppendAttempt,
|
|
label="Campaigns",
|
|
),
|
|
),
|
|
documentation=(
|
|
*CAMPAIGN_USER_DOCUMENTATION,
|
|
DocumentationTopic(
|
|
id="campaigns.mail-profile-user-journey",
|
|
title="Choose a Mail profile for campaign delivery",
|
|
summary="Campaigns reference an authorized Mail profile and never store SMTP/IMAP settings or credentials.",
|
|
body="Open the campaign Mail settings, select an available profile, test it through Mail, and save. Validation and delivery recheck profile authorization. A changed transport identity requires a new validation and build.",
|
|
layer="available",
|
|
documentation_types=("user",),
|
|
audience=("campaign_manager", "campaign_reviewer", "campaign_sender"),
|
|
order=46,
|
|
conditions=(
|
|
DocumentationCondition(
|
|
required_modules=("campaigns", "mail"),
|
|
required_scopes=("campaigns:campaign:update", "mail:profile:use"),
|
|
),
|
|
),
|
|
links=(
|
|
DocumentationLink(label="Campaigns", href="/campaigns", kind="runtime"),
|
|
DocumentationLink(label="Mail profiles", href="/settings?section=mail-profiles", kind="runtime"),
|
|
DocumentationLink(label="Campaign handbook", href="govoplan-campaign/docs/CAMPAIGN_HANDBOOK.md", kind="repository"),
|
|
),
|
|
related_modules=("mail",),
|
|
unlocks=("Profile-backed SMTP delivery and optional IMAP append-to-Sent.",),
|
|
metadata={
|
|
"kind": "workflow",
|
|
"route": "/campaigns/{campaign_id}/mail-settings",
|
|
"screen": "Campaign Mail settings",
|
|
"help_contexts": ["campaign.server-settings"],
|
|
"prerequisites": [
|
|
"Campaign and Mail are installed.",
|
|
"You may edit the current campaign version and use at least one authorized Mail profile.",
|
|
],
|
|
"steps": [
|
|
"Open the campaign and go to Mail settings.",
|
|
"Select an available Mail profile; Campaign stores only its stable identifier.",
|
|
"Test SMTP and, when configured, IMAP through the Mail module.",
|
|
"Save, validate, and build the campaign before queueing delivery.",
|
|
],
|
|
"outcome": "The editable campaign version references an authorized Mail-owned delivery profile without copying transport settings or credentials.",
|
|
"verification": "Reopen Mail settings, confirm the selected profile, then run validation and verify that the build completes without profile-drift errors.",
|
|
"related_topic_ids": [
|
|
"campaigns.mail-profile-governance",
|
|
"campaigns.mail-profile-operations",
|
|
"mail.profile-ownership-and-consumers",
|
|
],
|
|
},
|
|
),
|
|
DocumentationTopic(
|
|
id="campaigns.mail-profile-governance",
|
|
title="Govern Campaign-to-Mail profile references",
|
|
summary="Mail owns transport definitions and encrypted credentials; Campaign owns only the selected profile reference and delivery evidence.",
|
|
body="Grant mail:profile:use to campaign authors, constrain profile availability through Mail policy, and keep effective credential inheritance enabled. Inline transport fields are rejected. Legacy records remain unchanged until an explicit, audited profile migration creates or updates an editable version.",
|
|
layer="configured",
|
|
documentation_types=("admin",),
|
|
audience=("tenant_admin", "mail_admin", "campaign_admin"),
|
|
order=47,
|
|
conditions=(
|
|
DocumentationCondition(
|
|
required_modules=("campaigns", "mail"),
|
|
any_scopes=("mail:profile:write", "admin:policies:read", "system:settings:read"),
|
|
),
|
|
),
|
|
links=(
|
|
DocumentationLink(label="Mail profiles", href="/settings?section=mail-profiles", kind="runtime"),
|
|
DocumentationLink(label="Campaign schema", href="/api/v1/campaigns/schema", kind="api"),
|
|
DocumentationLink(label="Mail profile boundary", href="govoplan-campaign/docs/MAIL_PROFILE_BOUNDARY.md", kind="repository"),
|
|
),
|
|
related_modules=("mail", "access"),
|
|
unlocks=("Auditable, reusable transport configuration across campaigns.",),
|
|
metadata={
|
|
"kind": "reference",
|
|
"route": "/campaigns/{campaign_id}/mail-policy",
|
|
"screen": "Campaign Mail policy",
|
|
"section": "Profile authorization and credential inheritance",
|
|
"related_topic_ids": [
|
|
"campaigns.mail-profile-user-journey",
|
|
"campaigns.mail-profile-operations",
|
|
"mail.profile-ownership-and-consumers",
|
|
],
|
|
},
|
|
),
|
|
DocumentationTopic(
|
|
id="campaigns.mail-profile-operations",
|
|
title="Operate profile-backed campaign delivery",
|
|
summary="Workers re-authorize and resolve Mail profiles at execution time while Campaign retains only opaque Mail-owned revisions and outcomes.",
|
|
body="A legacy snapshot, unauthorized or inactive profile, profile-reference mismatch, or changed SMTP/IMAP transport revision stops delivery. Preserve the record, migrate or correct the profile selection, revalidate, rebuild, and only then queue again. Password-only rotation remains possible without copying secrets into Campaign. Uncertain SMTP and IMAP effects remain blocked until an evidence-backed operator reconciliation.",
|
|
layer="configured",
|
|
documentation_types=("admin",),
|
|
audience=("campaign_sender", "campaign_operator", "mail_admin"),
|
|
order=48,
|
|
conditions=(
|
|
DocumentationCondition(
|
|
required_modules=("campaigns", "mail"),
|
|
any_scopes=("campaigns:diagnostic:read", "campaigns:campaign:reconcile", "mail:profile:test"),
|
|
),
|
|
),
|
|
links=(
|
|
DocumentationLink(label="Campaign operator queue", href="/operator", kind="runtime"),
|
|
DocumentationLink(label="Campaign reports", href="/reports", kind="runtime"),
|
|
DocumentationLink(label="Campaign delivery runbook", href="govoplan-campaign/docs/CAMPAIGN_DELIVERY_RUNBOOK.md", kind="repository"),
|
|
),
|
|
related_modules=("mail", "audit"),
|
|
unlocks=("Fail-closed recovery without exposing Mail credentials.",),
|
|
metadata={
|
|
"kind": "reference",
|
|
"route": "/operator",
|
|
"screen": "Campaign operator queue",
|
|
"section": "Profile-backed delivery recovery",
|
|
"related_topic_ids": [
|
|
"campaigns.mail-profile-user-journey",
|
|
"campaigns.mail-profile-governance",
|
|
"mail.profile-ownership-and-consumers",
|
|
],
|
|
},
|
|
),
|
|
DocumentationTopic(
|
|
id="campaigns.workflow.prepare-validate-and-build",
|
|
title="Prepare, validate, and build a campaign",
|
|
summary="Turn governed recipient, template, attachment, and Mail-profile inputs into exact built messages for review.",
|
|
body="Prepare each input in its owning surface, resolve every blocking validation issue, and build exact recipient messages before review. Campaign freezes recipient and attachment evidence for the selected version; later source changes do not silently alter that build.",
|
|
layer="configured",
|
|
documentation_types=("user",),
|
|
audience=("campaign_manager", "campaign_author"),
|
|
order=49,
|
|
conditions=(
|
|
DocumentationCondition(
|
|
required_modules=("campaigns",),
|
|
required_scopes=("campaigns:campaign:update", "campaigns:campaign:validate", "campaigns:campaign:build"),
|
|
),
|
|
),
|
|
links=(
|
|
DocumentationLink(label="Campaigns", href="/campaigns", kind="runtime"),
|
|
DocumentationLink(label="Campaign handbook", href="govoplan-campaign/docs/CAMPAIGN_HANDBOOK.md", kind="repository"),
|
|
DocumentationLink(label="Recipient import guide", href="govoplan-campaign/docs/RECIPIENT_IMPORT_GUIDE.md", kind="repository"),
|
|
),
|
|
related_modules=("addresses", "files", "mail"),
|
|
unlocks=("A reviewable build whose exact recipient-specific effects can be inspected before delivery.",),
|
|
metadata={
|
|
"kind": "workflow",
|
|
"route": "/campaigns/{campaign_id}/global-settings",
|
|
"screen": "Campaign workspace",
|
|
"help_contexts": [
|
|
"campaign.overview",
|
|
"campaign.settings",
|
|
"campaign.fields",
|
|
"campaign.template",
|
|
"campaign.attachments",
|
|
"campaign.recipients",
|
|
"campaign.recipient-data",
|
|
"campaign.server-settings",
|
|
"campaign.global-settings",
|
|
"campaign.review-send",
|
|
"campaign.json",
|
|
],
|
|
"prerequisites": [
|
|
"The campaign has an owner and a clear communication purpose.",
|
|
"You may edit, validate, and build the selected campaign version.",
|
|
"Optional source modules needed by this campaign are installed and authorized.",
|
|
],
|
|
"steps": [
|
|
"Set campaign-wide fields and purpose, then define the recipient fields and templates.",
|
|
"Import or select recipients and inspect provenance, exclusions, and review-required rows.",
|
|
"Select managed attachment versions and an authorized Mail profile when those capabilities are used.",
|
|
"Validate the relevant sections and resolve every blocker without hiding warnings.",
|
|
"Build the selected version and inspect representative and exceptional rendered messages.",
|
|
],
|
|
"outcome": "The selected version has exact built messages and frozen source evidence ready for an independent review.",
|
|
"verification": "Open Review, confirm the build belongs to the intended version, and inspect counts, warnings, recipients, addressing, rendered content, and attachment evidence.",
|
|
"related_topic_ids": [
|
|
"campaigns.workflow.complete-review",
|
|
"campaigns.mail-profile-user-journey",
|
|
"files.workflow.import-managed-snapshot",
|
|
],
|
|
},
|
|
),
|
|
DocumentationTopic(
|
|
id="campaigns.workflow.complete-review",
|
|
title="Inspect built messages and complete review",
|
|
summary="Review the exact immutable candidate and record which built messages were inspected before delivery is enabled.",
|
|
body="Review completion records the inspected message keys for the selected build. The current baseline does not persist a separate approve/reject decision or review reason, so do not present completion as a richer decision record. Any material input or non-secret transport-identity change requires validation and a new build.",
|
|
layer="configured",
|
|
documentation_types=("user",),
|
|
audience=("campaign_reviewer",),
|
|
order=50,
|
|
conditions=(
|
|
DocumentationCondition(
|
|
required_modules=("campaigns",),
|
|
required_scopes=("campaigns:campaign:read", "campaigns:campaign:review"),
|
|
),
|
|
),
|
|
links=(
|
|
DocumentationLink(label="Campaigns", href="/campaigns", kind="runtime"),
|
|
DocumentationLink(label="Campaign handbook", href="govoplan-campaign/docs/CAMPAIGN_HANDBOOK.md", kind="repository"),
|
|
),
|
|
related_modules=("files", "mail"),
|
|
unlocks=("An attributable review-completion record for the exact built messages inspected.",),
|
|
metadata={
|
|
"kind": "workflow",
|
|
"route": "/campaigns/{campaign_id}/review",
|
|
"screen": "Review and send",
|
|
"help_contexts": ["campaign.review-send"],
|
|
"prerequisites": [
|
|
"The selected campaign version is validated and built.",
|
|
"You may read the campaign and complete its review.",
|
|
],
|
|
"steps": [
|
|
"Confirm the campaign, owner, selected version, recipient count, warnings, and exclusions.",
|
|
"Inspect representative and exceptional messages, addressing, templates, and attachment evidence.",
|
|
"Confirm that the selected Mail profile is suitable and authorized for the current context.",
|
|
"Record review completion for the exact message keys inspected.",
|
|
],
|
|
"outcome": "The reviewed build is eligible for a separately authorized queue or send action.",
|
|
"verification": "Reload Review and confirm completion is tied to the same version and message build; changed inputs must invalidate or supersede it.",
|
|
"related_topic_ids": [
|
|
"campaigns.workflow.prepare-validate-and-build",
|
|
"campaigns.workflow.retry-and-reconcile",
|
|
],
|
|
},
|
|
),
|
|
DocumentationTopic(
|
|
id="campaigns.workflow.retry-and-reconcile",
|
|
title="Retry only known failures and reconcile uncertain effects",
|
|
summary="Keep safe-to-retry failures separate from SMTP or IMAP effects whose outcome is unknown.",
|
|
body="A retry creates new attempt evidence and is valid only for an explicitly eligible state. Never blindly retry an unknown SMTP or IMAP effect. Inspect external evidence, reconcile SMTP as accepted or not sent, and reconcile IMAP as appended or not appended; repairing Sent never resends accepted SMTP mail.",
|
|
layer="evidence",
|
|
documentation_types=("admin", "user"),
|
|
audience=("campaign_sender", "campaign_operator"),
|
|
order=51,
|
|
conditions=(
|
|
DocumentationCondition(
|
|
required_modules=("campaigns",),
|
|
any_scopes=("campaigns:campaign:retry", "campaigns:campaign:reconcile", "campaigns:diagnostic:read"),
|
|
),
|
|
),
|
|
links=(
|
|
DocumentationLink(label="Campaign operator queue", href="/operator", kind="runtime"),
|
|
DocumentationLink(label="Campaign delivery runbook", href="govoplan-campaign/docs/CAMPAIGN_DELIVERY_RUNBOOK.md", kind="repository"),
|
|
),
|
|
related_modules=("mail", "audit"),
|
|
unlocks=("Evidence-backed recovery without accidental duplicate external effects.",),
|
|
metadata={
|
|
"kind": "workflow",
|
|
"route": "/operator",
|
|
"screen": "Campaign operator queue",
|
|
"help_contexts": ["campaign.review-send", "campaign.report", "campaign.audit"],
|
|
"prerequisites": [
|
|
"You may perform the selected retry or reconciliation action.",
|
|
"Provider, mailbox, worker, and campaign evidence has been preserved.",
|
|
],
|
|
"steps": [
|
|
"Classify the job and latest SMTP and IMAP attempts independently.",
|
|
"Retry only an explicitly temporary, permanent-with-override, or unattempted eligible state.",
|
|
"For an unknown effect, inspect provider or mailbox evidence and record the factual reconciliation with a note.",
|
|
"Verify the resulting protected state before allowing more work for that job.",
|
|
],
|
|
"outcome": "Every investigated job is either protected as effected, explicitly retryable, or still visibly unresolved.",
|
|
"verification": "Confirm the previous attempt remains in history, a retry has a new attempt number, and no accepted SMTP effect was repeated to repair IMAP state.",
|
|
"related_topic_ids": [
|
|
"campaigns.mail-profile-operations",
|
|
"campaigns.reference.composition-assurance",
|
|
],
|
|
},
|
|
),
|
|
DocumentationTopic(
|
|
id="campaigns.reference.composition-assurance",
|
|
title="Assure the Campaign reference composition",
|
|
summary="Release Campaign only with aligned contracts, role-safe surfaces, durable effect evidence, optional-module isolation, and recoverable data.",
|
|
body="Campaign is a reference composition only when Core, Mail, Files, Addresses, workers, storage, policies, and documentation are tested in the exact installed combination. Normal readers see business state rather than paths, storage keys, worker claims, or raw provider diagnostics; diagnostic and export authority remain separate.",
|
|
layer="evidence",
|
|
documentation_types=("admin",),
|
|
audience=("platform_operator", "security_reviewer", "release_reviewer", "integrator"),
|
|
order=52,
|
|
conditions=(
|
|
DocumentationCondition(
|
|
required_modules=("campaigns",),
|
|
any_scopes=("campaigns:diagnostic:read", "campaigns:report:read", "system:settings:read", "admin:modules:read"),
|
|
),
|
|
),
|
|
links=(
|
|
DocumentationLink(label="Campaign handbook", href="govoplan-campaign/docs/CAMPAIGN_HANDBOOK.md", kind="repository"),
|
|
DocumentationLink(label="Reference examples and release checklist", href="govoplan-campaign/docs/EXAMPLE_CAMPAIGNS_AND_RELEASE_CHECKLIST.md", kind="repository"),
|
|
),
|
|
related_modules=("mail", "files", "addresses", "audit"),
|
|
unlocks=("A repeatable, supportable Campaign demonstration rather than an unverified module assembly.",),
|
|
metadata={
|
|
"kind": "reference",
|
|
"route": "/campaigns",
|
|
"screen": "Campaign reference composition",
|
|
"section": "Release, security, integration, and recovery assurance",
|
|
"verification": "Run the maintained examples, module-permutation tests, migration and restore drills, target SMTP/IMAP checks, version-alignment gate, WebUI/i18n checks, and full security audit for the pinned composition.",
|
|
"related_topic_ids": [
|
|
"campaigns.workflow.prepare-validate-and-build",
|
|
"campaigns.workflow.complete-review",
|
|
"campaigns.workflow.retry-and-reconcile",
|
|
"mail.reference.credentials-egress-retirement",
|
|
],
|
|
},
|
|
),
|
|
),
|
|
documentation_providers=(documentation_topics,),
|
|
capability_factories={
|
|
CAPABILITY_CAMPAIGNS_ACCESS: lambda context: __import__(
|
|
"govoplan_campaign.backend.capabilities",
|
|
fromlist=["access_capability"],
|
|
).access_capability(context),
|
|
CAPABILITY_CAMPAIGNS_DELIVERY_TASKS: lambda context: __import__(
|
|
"govoplan_campaign.backend.capabilities",
|
|
fromlist=["delivery_tasks_capability"],
|
|
).delivery_tasks_capability(context),
|
|
CAPABILITY_CAMPAIGNS_MAIL_POLICY_CONTEXT: lambda context: __import__(
|
|
"govoplan_campaign.backend.capabilities",
|
|
fromlist=["mail_policy_context_capability"],
|
|
).mail_policy_context_capability(context),
|
|
CAPABILITY_CAMPAIGNS_POLICY_CONTEXT: lambda context: __import__(
|
|
"govoplan_campaign.backend.capabilities",
|
|
fromlist=["policy_context_capability"],
|
|
).policy_context_capability(context),
|
|
CAPABILITY_CAMPAIGNS_RETENTION: lambda context: __import__(
|
|
"govoplan_campaign.backend.capabilities",
|
|
fromlist=["retention_capability"],
|
|
).retention_capability(context),
|
|
},
|
|
)
|
|
|
|
|
|
def get_manifest() -> ModuleManifest:
|
|
return manifest
|