feat: add governed postbox delivery and report hardening

2026-07-29 14:16:28 +02:00
parent f11c56e890
commit 5240749ae1
47 changed files with 5538 additions and 288 deletions
@@ -83,6 +83,9 @@ class JobSendStatus(StrEnum):
    CLAIMED = "claimed"
    SENDING = "sending"
    SMTP_ACCEPTED = "smtp_accepted"
+    POSTBOX_ACCEPTED = "postbox_accepted"
+    DELIVERED = "delivered"
+    PARTIALLY_ACCEPTED = "partially_accepted"
    SENT = "sent"  # legacy value retained for existing databases/reports
    OUTCOME_UNKNOWN = "outcome_unknown"
    FAILED_TEMPORARY = "failed_temporary"
@@ -90,6 +93,19 @@ class JobSendStatus(StrEnum):
    CANCELLED = "cancelled"


+class JobPostboxStatus(StrEnum):
+    NOT_REQUESTED = "not_requested"
+    PENDING = "pending"
+    DELIVERING = "delivering"
+    ACCEPTED = "accepted"
+    ACCEPTED_VACANT = "accepted_vacant"
+    PARTIALLY_ACCEPTED = "partially_accepted"
+    REJECTED_TEMPORARY = "rejected_temporary"
+    REJECTED_PERMANENT = "rejected_permanent"
+    OUTCOME_UNKNOWN = "outcome_unknown"
+    SKIPPED = "skipped"
+
+
 class JobImapStatus(StrEnum):
    NOT_REQUESTED = "not_requested"
    PENDING = "pending"
@@ -249,9 +265,26 @@ class CampaignJob(Base, TimestampMixin):
    validation_status: Mapped[str] = mapped_column(String(50), default=JobValidationStatus.NEEDS_REVIEW.value, nullable=False, index=True)
    queue_status: Mapped[str] = mapped_column(String(50), default=JobQueueStatus.DRAFT.value, nullable=False, index=True)
    send_status: Mapped[str] = mapped_column(String(50), default=JobSendStatus.NOT_QUEUED.value, nullable=False, index=True)
+    delivery_channel_policy: Mapped[str] = mapped_column(
+        String(30),
+        default="mail",
+        nullable=False,
+        index=True,
+    )
+    postbox_status: Mapped[str] = mapped_column(
+        String(50),
+        default=JobPostboxStatus.NOT_REQUESTED.value,
+        nullable=False,
+        index=True,
+    )
    imap_status: Mapped[str] = mapped_column(String(50), default=JobImapStatus.NOT_REQUESTED.value, nullable=False, index=True)

    attempt_count: Mapped[int] = mapped_column(Integer, default=0, nullable=False)
+    postbox_attempt_count: Mapped[int] = mapped_column(
+        Integer,
+        default=0,
+        nullable=False,
+    )
    last_error: Mapped[str | None] = mapped_column(Text)
    queued_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
    claimed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
@@ -263,6 +296,11 @@ class CampaignJob(Base, TimestampMixin):
    sent_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))

    resolved_recipients: Mapped[dict[str, Any] | None] = mapped_column(JSON, nullable=True)
+    resolved_postbox_targets: Mapped[list[dict[str, Any]]] = mapped_column(
+        JSON,
+        default=list,
+        nullable=False,
+    )
    resolved_attachments: Mapped[list[dict[str, Any]]] = mapped_column(JSON, default=list)
    issues_snapshot: Mapped[list[dict[str, Any]]] = mapped_column(JSON, default=list)

@@ -342,6 +380,79 @@ class ImapAppendAttempt(Base, TimestampMixin):
    error_message: Mapped[str | None] = mapped_column(Text)


+class PostboxDeliveryAttempt(Base, TimestampMixin):
+    __tablename__ = "campaign_postbox_delivery_attempts"
+    __table_args__ = (
+        UniqueConstraint(
+            "job_id",
+            "target_key",
+            "attempt_number",
+            name="uq_campaign_postbox_attempt_target_number",
+        ),
+        Index(
+            "ix_campaign_postbox_attempt_idempotency",
+            "tenant_id",
+            "idempotency_key",
+        ),
+        Index(
+            "ix_campaign_postbox_attempt_job_status",
+            "job_id",
+            "status",
+        ),
+    )
+
+    id: Mapped[str] = mapped_column(
+        String(36),
+        primary_key=True,
+        default=new_uuid,
+    )
+    tenant_id: Mapped[str] = mapped_column(
+        String(36),
+        nullable=False,
+        index=True,
+    )
+    job_id: Mapped[str] = mapped_column(
+        ForeignKey("campaign_jobs.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True,
+    )
+    target_key: Mapped[str] = mapped_column(String(64), nullable=False)
+    target_index: Mapped[int] = mapped_column(Integer, nullable=False)
+    attempt_number: Mapped[int] = mapped_column(Integer, nullable=False)
+    idempotency_key: Mapped[str] = mapped_column(String(255), nullable=False)
+    status: Mapped[str] = mapped_column(
+        String(50),
+        nullable=False,
+        index=True,
+    )
+    target_snapshot: Mapped[dict[str, Any]] = mapped_column(
+        JSON,
+        default=dict,
+        nullable=False,
+    )
+    provider_delivery_id: Mapped[str | None] = mapped_column(String(36))
+    provider_message_id: Mapped[str | None] = mapped_column(String(36))
+    postbox_id: Mapped[str | None] = mapped_column(String(36), index=True)
+    address: Mapped[str | None] = mapped_column(String(500))
+    holder_count: Mapped[int | None] = mapped_column(Integer)
+    vacant: Mapped[bool | None] = mapped_column(Boolean)
+    duplicate: Mapped[bool] = mapped_column(Boolean, default=False, nullable=False)
+    evidence: Mapped[dict[str, Any]] = mapped_column(
+        JSON,
+        default=dict,
+        nullable=False,
+    )
+    error_type: Mapped[str | None] = mapped_column(String(255))
+    error_code: Mapped[str | None] = mapped_column(String(100))
+    error_message: Mapped[str | None] = mapped_column(Text)
+    started_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True),
+    )
+    finished_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True),
+    )
+
+


 __all__ = [
@@ -359,8 +470,10 @@ __all__ = [
    "IssueSeverity",
    "JobBuildStatus",
    "JobImapStatus",
+    "JobPostboxStatus",
    "JobQueueStatus",
    "JobSendStatus",
    "JobValidationStatus",
    "SendAttempt",
+    "PostboxDeliveryAttempt",
 ]