feat(campaign): govern attachment reuse

src/govoplan_campaign/backend/attachments/reuse.py

@@ -0,0 +1,184 @@
+from __future__ import annotations
+
+import hashlib
+from collections import defaultdict
+from dataclasses import dataclass
+from pathlib import Path
+
+from govoplan_campaign.backend.campaign.models import (
+    AttachmentReuseAction,
+    AttachmentReuseAllowance,
+    AttachmentReusePolicy,
+)
+from govoplan_campaign.backend.messages.models import MessageDraft, MessageIssue
+
+
+@dataclass(frozen=True, slots=True)
+class _AttachmentUse:
+    message: MessageDraft
+    message_key: str
+    recipient_key: tuple[str, ...]
+    source_identity: str
+    file_name: str
+
+
+@dataclass(slots=True)
+class AttachmentReuseEvaluation:
+    report: dict[str, object]
+    issues_by_entry_index: dict[int, list[MessageIssue]]
+
+
+def evaluate_attachment_reuse(
+    messages: list[MessageDraft],
+    *,
+    policy: AttachmentReusePolicy,
+) -> AttachmentReuseEvaluation:
+    """Evaluate repeated resolved-file use without exposing source paths.
+
+    A use is one resolved file occurrence in one attachment rule. The same
+    source file can therefore be detected both across built messages and when
+    two rules add it to one message. Allowed findings remain in the build
+    protocol; policy violations additionally become recipient-level issues.
+    """
+
+    uses_by_source: dict[str, list[_AttachmentUse]] = defaultdict(list)
+    for message in messages:
+        if not message.active:
+            continue
+        message_key = str(message.entry_id or message.entry_index)
+        recipient_key = _recipient_key(message, fallback=message_key)
+        for attachment in message.attachments:
+            for match in attachment.matches:
+                source_identity = _source_identity(match)
+                uses_by_source[source_identity].append(
+                    _AttachmentUse(
+                        message=message,
+                        message_key=message_key,
+                        recipient_key=recipient_key,
+                        source_identity=source_identity,
+                        file_name=Path(match).name,
+                    )
+                )
+
+    findings: list[dict[str, object]] = []
+    issues_by_entry_index: dict[int, list[MessageIssue]] = defaultdict(list)
+    affected_entry_indexes: set[int] = set()
+    allowed_count = 0
+    violation_count = 0
+
+    for source_identity, uses in sorted(uses_by_source.items()):
+        if len(uses) < 2:
+            continue
+        fingerprint = hashlib.sha256(source_identity.encode("utf-8")).hexdigest()
+        message_keys = {item.message_key for item in uses}
+        recipient_keys = {item.recipient_key for item in uses}
+        allowed, explanation = _is_allowed(
+            policy,
+            message_count=len(message_keys),
+            recipient_count=len(recipient_keys),
+        )
+        disposition = "allowed" if allowed else policy.action.value
+        finding = {
+            "file_fingerprint": fingerprint,
+            "file_name": uses[0].file_name,
+            "use_count": len(uses),
+            "message_count": len(message_keys),
+            "recipient_count": len(recipient_keys),
+            "disposition": disposition,
+            "explanation": explanation,
+        }
+        findings.append(finding)
+        if allowed:
+            allowed_count += 1
+            continue
+
+        violation_count += 1
+        behavior = _issue_behavior(policy.action)
+        severity = (
+            "error" if policy.action == AttachmentReuseAction.BLOCK else "warning"
+        )
+        for use in _unique_message_uses(uses):
+            affected_entry_indexes.add(use.message.entry_index)
+            issues_by_entry_index[use.message.entry_index].append(
+                MessageIssue(
+                    severity=severity,
+                    code="duplicate_attachment_reuse",
+                    message=(
+                        f"Attachment {use.file_name!r} is reused {len(uses)} times "
+                        f"across {len(message_keys)} built message(s); the configured "
+                        f"policy requires {disposition}."
+                    ),
+                    behavior=behavior,
+                    source="attachments:reuse_policy",
+                    details={
+                        **finding,
+                        "policy": policy.model_dump(mode="json"),
+                    },
+                )
+            )
+
+    return AttachmentReuseEvaluation(
+        report={
+            "contract_version": "1",
+            "policy": policy.model_dump(mode="json"),
+            "duplicate_file_count": len(findings),
+            "allowed_file_count": allowed_count,
+            "violation_file_count": violation_count,
+            "affected_message_count": len(affected_entry_indexes),
+            "findings": findings,
+        },
+        issues_by_entry_index=dict(issues_by_entry_index),
+    )
+
+
+def _source_identity(value: str) -> str:
+    return str(Path(value).resolve(strict=False))
+
+
+def _recipient_key(message: MessageDraft, *, fallback: str) -> tuple[str, ...]:
+    addresses = message.to or message.bcc or message.cc
+    normalized = sorted(
+        {
+            item.email.strip().casefold()
+            for item in addresses
+            if item.email and item.email.strip()
+        }
+    )
+    return tuple(normalized) if normalized else (f"entry:{fallback}",)
+
+
+def _is_allowed(
+    policy: AttachmentReusePolicy,
+    *,
+    message_count: int,
+    recipient_count: int,
+) -> tuple[bool, str]:
+    if policy.action == AttachmentReuseAction.ALLOW:
+        return True, "The campaign policy explicitly allows attachment reuse."
+    if (
+        policy.allow_within == AttachmentReuseAllowance.SAME_MESSAGE
+        and message_count == 1
+    ):
+        return True, "Reuse is confined to one built message as allowed by policy."
+    if (
+        policy.allow_within == AttachmentReuseAllowance.SAME_RECIPIENT
+        and recipient_count == 1
+    ):
+        return True, "Reuse is confined to one recipient as allowed by policy."
+    return False, (
+        "Reuse crosses the configured allowance and is handled by the "
+        f"{policy.action.value} policy."
+    )
+
+
+def _issue_behavior(action: AttachmentReuseAction) -> str:
+    if action == AttachmentReuseAction.REVIEW:
+        return "ask"
+    return action.value
+
+
+def _unique_message_uses(uses: list[_AttachmentUse]) -> list[_AttachmentUse]:
+    unique: dict[int, _AttachmentUse] = {}
+    for use in uses:
+        unique.setdefault(use.message.entry_index, use)
+    return list(unique.values())

src/govoplan_campaign/backend/campaign/models.py

@@ -474,6 +474,24 @@ class ResidualFileMode(StrEnum):
     ATTACH = "attach"
 
 
+class AttachmentReuseAction(StrEnum):
+    ALLOW = "allow"
+    WARN = "warn"
+    REVIEW = "review"
+    BLOCK = "block"
+
+
+class AttachmentReuseAllowance(StrEnum):
+    NONE = "none"
+    SAME_RECIPIENT = "same_recipient"
+    SAME_MESSAGE = "same_message"
+
+
+class AttachmentReusePolicy(StrictModel):
+    action: AttachmentReuseAction = AttachmentReuseAction.ALLOW
+    allow_within: AttachmentReuseAllowance = AttachmentReuseAllowance.NONE
+
+
 class ResidualFileDispositionConfig(StrictModel):
     mode: ResidualFileMode = ResidualFileMode.NONE
     recipient: RecipientConfig | None = None
@@ -533,6 +551,9 @@ class AttachmentsConfig(StrictModel):
     global_: list[AttachmentConfig] = Field(default_factory=list, alias="global")
     missing_behavior: Behavior = Behavior.WARN
     ambiguous_behavior: Behavior = Behavior.ASK
+    reuse_policy: AttachmentReusePolicy = Field(
+        default_factory=AttachmentReusePolicy
+    )
     residual_files: ResidualFileDispositionConfig = Field(
         default_factory=ResidualFileDispositionConfig
     )

src/govoplan_campaign/backend/documentation.py

@@ -452,6 +452,40 @@ CAMPAIGN_USER_DOCUMENTATION = (
         ),
         related_modules=("files",),
     ),
+    _workflow_topic(
+        topic_id="campaigns.workflow.control-attachment-reuse",
+        title="Control repeated campaign attachment use",
+        summary="Choose whether one resolved file may be reused, produces a warning, requires a reasoned review decision, or blocks delivery.",
+        body="Attachment reuse is a campaign-owned policy. The action can allow and record every repeated file, warn, require explicit review, or block affected messages. An optional exception permits reuse confined to one recipient or one built message. Every repeated-file finding is represented in the build protocol by a path-safe fingerprint, display filename, use count, message count, disposition, and explanation. Review decisions require a reason, bind to the exact message and build fingerprint, and remain available in campaign protocol and audit evidence. Changing the policy requires a new validation and build; it never rewrites historical evidence.",
+        order=35,
+        audience=("campaign_manager", "campaign_author", "campaign_reviewer", "administrator"),
+        required_scopes=("campaigns:campaign:read", "campaigns:campaign:update", "campaigns:campaign:build", "campaigns:campaign:review"),
+        route="/campaigns/{campaign_id}/files",
+        screen="Attachments",
+        help_contexts=("campaign.attachments", "campaign.attachments.reuse-policy"),
+        prerequisites=(
+            "Decide which repeated use is acceptable for the campaign's purpose and recipients.",
+            "The current campaign version is editable when changing the policy.",
+        ),
+        steps=(
+            "Open Attachments and choose Allow, Warn, Require explicit review, or Block delivery.",
+            "Optionally allow reuse only within the same recipient or the same built message.",
+            "Save, validate, and build the campaign, then inspect the repeated-file summary and affected messages.",
+            "For Review findings, open every affected message and record an explicit reason; for Block findings, correct the rules or policy and rebuild.",
+        ),
+        outcome="A campaign build whose repeated attachment use is governed and reviewable under an explicit policy.",
+        verification="Review and send shows the configured action and boundary, repeated-file counts and dispositions; affected messages show warning, review, or blocked state as configured.",
+        related_topic_ids=("campaigns.workflow.use-managed-attachments", "campaigns.workflow.prepare-validate-and-build"),
+        translations={
+            "de": {
+                "title": "Wiederholte Verwendung von Kampagnenanhängen steuern",
+                "summary": "Festlegen, ob dieselbe aufgelöste Datei wiederverwendet werden darf, eine Warnung erzeugt, eine begründete Prüfentscheidung erfordert oder den Versand sperrt.",
+                "body": "Die Wiederverwendung von Anhängen wird durch eine kampagneneigene Richtlinie gesteuert. Die Aktion kann jede Wiederverwendung zulassen und protokollieren, warnen, eine ausdrückliche Prüfung verlangen oder betroffene Nachrichten sperren. Optional darf die Wiederverwendung innerhalb desselben Empfängers oder derselben erzeugten Nachricht ausgenommen werden. Jeder Befund erscheint mit pfadsicherem Fingerabdruck, Anzeigename, Verwendungs- und Nachrichtenanzahl, Ergebnis und Begründung im Build-Protokoll. Prüfentscheidungen benötigen eine Begründung, sind an Nachricht und Build-Fingerabdruck gebunden und bleiben in Protokoll und Auditnachweis erhalten. Eine Richtlinienänderung erfordert eine neue Validierung und einen neuen Build und verändert keine historischen Nachweise.",
+                "outcome": "Ein Kampagnen-Build, dessen wiederholte Anhangsverwendung durch eine ausdrückliche Richtlinie gesteuert und prüfbar ist.",
+                "verification": "Prüfen und senden zeigt Aktion, Ausnahmegrenze, Anzahlen und Ergebnisse; betroffene Nachrichten tragen entsprechend Warn-, Prüf- oder Sperrstatus.",
+            }
+        },
+    ),
     _workflow_topic(
         topic_id="campaigns.workflow.route-unassigned-files",
         title="Review and route unassigned campaign files",

src/govoplan_campaign/backend/messages/builder.py

@@ -19,6 +19,7 @@ from govoplan_campaign.backend.attachments.resolver import (
     effective_send_without_attachments_behavior,
     resolve_entry_attachments,
 )
+from govoplan_campaign.backend.attachments.reuse import evaluate_attachment_reuse
 from govoplan_campaign.backend.campaign.addressing import effective_address_lists, formatted_recipient
 from govoplan_campaign.backend.campaign.entries import load_campaign_entries
 from govoplan_campaign.backend.campaign.field_values import ignored_entry_field_overrides
@@ -1149,6 +1150,28 @@ def _apply_campaign_level_issues(built_messages: list[BuiltMessage], issues: lis
                 status = _apply_behavior(status, issue.behavior)
         built.draft.validation_status = status
 
+
+def _apply_attachment_reuse_policy(
+    config: CampaignConfig,
+    built_messages: list[BuiltMessage],
+) -> dict[str, object]:
+    evaluation = evaluate_attachment_reuse(
+        [built.draft for built in built_messages],
+        policy=config.attachments.reuse_policy,
+    )
+    for built in built_messages:
+        issues = evaluation.issues_by_entry_index.get(built.draft.entry_index, [])
+        if not issues:
+            continue
+        built.draft.issues.extend(issues)
+        for issue in issues:
+            if issue.behavior:
+                built.draft.validation_status = _apply_behavior(
+                    built.draft.validation_status,
+                    issue.behavior,
+                )
+    return evaluation.report
+
 def build_campaign_messages(
     config: CampaignConfig,
     *,
@@ -1203,6 +1226,10 @@ def build_campaign_messages(
         )
         if residual_message is not None:
             built_messages.append(residual_message)
+        attachment_reuse = _apply_attachment_reuse_policy(
+            config,
+            built_messages,
+        )
 
     rules_resolved = sum(len(built.draft.attachments) for built in built_messages)
     report = CampaignBuildReport(
@@ -1216,6 +1243,7 @@ def build_campaign_messages(
             duration_ms=(time.perf_counter() - started) * 1000,
             rules_resolved=rules_resolved,
         ),
+        attachment_reuse=attachment_reuse,
         residual_file_disposition=_residual_file_disposition_evidence(
             config=config,
             residual_groups=residual_groups,

src/govoplan_campaign/backend/messages/models.py

@@ -117,6 +117,7 @@ class CampaignBuildReport(BaseModel):
     inactive_entries_count: int = 0
     messages: list[MessageDraft] = Field(default_factory=list)
     attachment_resolution_profile: dict[str, object] = Field(default_factory=dict)
+    attachment_reuse: dict[str, object] = Field(default_factory=dict)
     residual_file_disposition: dict[str, object] = Field(default_factory=dict)
 
     @property

src/govoplan_campaign/backend/routes/versions.py

@@ -594,6 +594,7 @@ def set_version_review_state(
                 "inspection_complete": payload.inspection_complete,
                 "reviewed_message_count": len(payload.reviewed_message_keys),
                 "issue_decision_count": len(payload.issue_decisions),
+                "issue_decisions": _review_decision_audit_evidence(version),
             },
             commit=True,
         )
@@ -879,6 +880,9 @@ def build_version(
                 "residual_file_disposition": _residual_file_audit_evidence(
                     result.get("residual_file_disposition")
                 ),
+                "attachment_reuse": _attachment_reuse_audit_evidence(
+                    result.get("attachment_reuse")
+                ),
             },
             commit=True,
         )
@@ -925,3 +929,54 @@ def _residual_file_audit_evidence(value: object) -> dict[str, object]:
             "residual_file_count",
         )
     }
+
+
+def _attachment_reuse_audit_evidence(value: object) -> dict[str, object]:
+    if not isinstance(value, dict):
+        return {}
+    policy = value.get("policy")
+    return {
+        "contract_version": value.get("contract_version"),
+        "policy": dict(policy) if isinstance(policy, dict) else {},
+        "duplicate_file_count": value.get("duplicate_file_count"),
+        "allowed_file_count": value.get("allowed_file_count"),
+        "violation_file_count": value.get("violation_file_count"),
+        "affected_message_count": value.get("affected_message_count"),
+    }
+
+
+def _review_decision_audit_evidence(
+    version: CampaignVersion,
+) -> dict[str, object]:
+    editor_state = version.editor_state if isinstance(version.editor_state, dict) else {}
+    review_state = editor_state.get("review_send")
+    if not isinstance(review_state, dict):
+        return {}
+    raw_decisions = review_state.get("issue_decisions")
+    decisions = [item for item in raw_decisions or [] if isinstance(item, dict)]
+    evidence = [
+        {
+            "decision": item.get("decision"),
+            "issue_codes": sorted(
+                str(code) for code in item.get("issue_codes") or [] if code
+            ),
+            "issue_fingerprint": item.get("issue_fingerprint"),
+            "message_sha256": item.get("message_sha256"),
+            "reason_recorded": bool(str(item.get("reason") or "").strip()),
+        }
+        for item in decisions
+    ]
+    return {
+        "count": len(evidence),
+        "with_reason_count": sum(
+            1 for item in evidence if item["reason_recorded"]
+        ),
+        "issue_codes": sorted(
+            {
+                code
+                for item in evidence
+                for code in item["issue_codes"]
+            }
+        ),
+        "evidence_sha256": _canonical_sha256(evidence),
+    }

src/govoplan_campaign/backend/schema/campaign.schema.json

@@ -372,6 +372,10 @@
           ],
           "default": "ask"
         },
+        "reuse_policy": {
+          "$ref": "#/$defs/attachment_reuse_policy",
+          "description": "Controls whether resolving the same source file more than once is allowed, warned, reviewed, or blocked, with an optional same-recipient or same-message allowance."
+        },
         "residual_files": {
           "$ref": "#/$defs/residual_file_disposition"
         }
@@ -1458,6 +1462,25 @@
       },
       "additionalProperties": false
     },
+    "attachment_reuse_policy": {
+      "type": "object",
+      "properties": {
+        "action": {
+          "type": "string",
+          "enum": ["allow", "warn", "review", "block"],
+          "default": "allow",
+          "description": "Action when one resolved source file is used more than once outside the configured allowance. Review creates an explicit, reasoned review decision."
+        },
+        "allow_within": {
+          "type": "string",
+          "enum": ["none", "same_recipient", "same_message"],
+          "default": "none",
+          "description": "Optional exception that permits reuse confined to one recipient or one built message."
+        }
+      },
+      "additionalProperties": false,
+      "default": {"action": "allow", "allow_within": "none"}
+    },
     "residual_file_disposition": {
       "type": "object",
       "properties": {

src/govoplan_campaign/backend/schema/campaign.schema.ui.json

@@ -61,6 +61,16 @@
     }
   ],
   "fields": {
+    "/attachments/reuse_policy/action": {
+      "label": "Duplicate-file action",
+      "control": "select",
+      "description": "Allow and record, warn, require a reasoned review decision, or block repeated use of the same resolved file."
+    },
+    "/attachments/reuse_policy/allow_within": {
+      "label": "Allowed reuse boundary",
+      "control": "select",
+      "description": "Optionally exempt reuse confined to one recipient or one built message."
+    },
     "/attachments/global[]/message_filename_template": {
       "label": "Direct attachment filename",
       "control": "text",