feat(D): Phase D — Undo/Restore komplett implementiert

- D-GEN: RestoreRegistry mit RestoreConfig (model_class, restore_permission, excluded_fields, special_handler)
- D-HOOK: history_hooks.py mit register_history_hooks() für after_create/update/delete
- D-CORE: Company create+update record_history in companies.py
- D-PLUG: Task/Calendar/DMS record_history in services/routes
- D-SOFT: Alle registrierten Entitäten haben deleted_at + un-delete via Registry
- D-MAIL: Mail special_handler (IMAP Trash-Move, Folder-Verify) + record_history in delete/move
- D-TRASH: GET /entity-history/trash (filterbar, paginiert) + Frontend Trash.tsx
- D-TOAST: UndoToast.tsx (5s Auto-Dismiss, useUndoToast Hook)
- D-HIST-UI: HistoryPanel.tsx (Timeline, Diff-View, Restore-Button)
- D-BULK: POST /entity-history/bulk-restore mit partial_success Semantik
- D-RET: POST /entity-history/retention/archive (GDPR hard-delete >90 Tage)
- D-TEST: 26 Tests in test_restore_registry.py, alle grün
- D-DOC: test-strategy.md + security_kernel.md aktualisiert

Backend: 10 Dateien, Frontend: 7 Dateien, Tests: 1 Datei, Docs: 3 Dateien
26/26 Tests passed, TSC 0 errors, App import 492 routes

app/core/history_hooks.py

@@ -0,0 +1,180 @@
+"""Hook-based history recording — standard hooks that call record_history().
+
+Registers action hooks for entity lifecycle events:
+- entity.after_create  → record_history(action='create', snapshot_after=...)
+- entity.after_update  → record_history(action='update', snapshot_before=..., snapshot_after=..., changes=...)
+- entity.after_delete  → record_history(action='delete', snapshot_before=...)
+
+Plugins can register their own entity types by calling:
+    register_history_hooks(reg, 'task', 'task.after_create', 'task.after_update', 'task.after_delete')
+
+This is explicit, traceable, and testable — no SQLAlchemy event listeners.
+"""
+
+from __future__ import annotations
+
+import logging
+import uuid
+from typing import Any
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.core.hooks import HookRegistry, get_hook_registry
+from app.services.entity_history_service import record_history
+
+logger = logging.getLogger(__name__)
+
+
+def register_history_hooks(
+    reg: HookRegistry,
+    entity_type: str,
+    after_create_hook: str,
+    after_update_hook: str,
+    after_delete_hook: str,
+) -> None:
+    """Register standard history-recording hooks for an entity type.
+
+    Each hook receives kwargs: db, tenant_id, user_id, and either:
+    - after_create: snapshot_after (the created entity dict)
+    - after_update: snapshot_before, snapshot_after, changes
+    - after_delete: snapshot_before
+    """
+
+    async def _on_create(
+        snapshot_after: dict[str, Any],
+        *,
+        db: AsyncSession,
+        tenant_id: uuid.UUID,
+        user_id: uuid.UUID | None = None,
+        **kwargs: Any,
+    ) -> None:
+        entity_id = _extract_entity_id(snapshot_after)
+        if entity_id is None:
+            logger.warning("history_hooks: cannot extract entity_id from snapshot for %s", entity_type)
+            return
+        await record_history(
+            db, tenant_id, user_id, entity_type, entity_id,
+            action="create", snapshot_after=snapshot_after,
+        )
+
+    async def _on_update(
+        snapshot_after: dict[str, Any],
+        *,
+        db: AsyncSession,
+        tenant_id: uuid.UUID,
+        user_id: uuid.UUID | None = None,
+        snapshot_before: dict[str, Any] | None = None,
+        changes: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        entity_id = _extract_entity_id(snapshot_after) or (
+            _extract_entity_id(snapshot_before) if snapshot_before else None
+        )
+        if entity_id is None:
+            logger.warning("history_hooks: cannot extract entity_id for %s update", entity_type)
+            return
+        await record_history(
+            db, tenant_id, user_id, entity_type, entity_id,
+            action="update",
+            snapshot_before=snapshot_before,
+            snapshot_after=snapshot_after,
+            changes=changes,
+        )
+
+    async def _on_delete(
+        snapshot_before: dict[str, Any] | None = None,
+        *,
+        db: AsyncSession,
+        tenant_id: uuid.UUID,
+        user_id: uuid.UUID | None = None,
+        entity_id: uuid.UUID | None = None,
+        **kwargs: Any,
+    ) -> None:
+        eid = entity_id or (_extract_entity_id(snapshot_before) if snapshot_before else None)
+        if eid is None:
+            logger.warning("history_hooks: cannot extract entity_id for %s delete", entity_type)
+            return
+        await record_history(
+            db, tenant_id, user_id, entity_type, eid,
+            action="delete", snapshot_before=snapshot_before,
+        )
+
+    reg.register_action(after_create_hook, _on_create, priority=90)
+    reg.register_action(after_update_hook, _on_update, priority=90)
+    reg.register_action(after_delete_hook, _on_delete, priority=90)
+    logger.debug("History hooks registered for: %s", entity_type)
+
+
+def _extract_entity_id(snapshot: dict[str, Any] | None) -> uuid.UUID | None:
+    """Extract entity UUID from a snapshot dict."""
+    if snapshot is None:
+        return None
+    raw_id = snapshot.get("id")
+    if raw_id is None:
+        return None
+    if isinstance(raw_id, uuid.UUID):
+        return raw_id
+    try:
+        return uuid.UUID(str(raw_id))
+    except (ValueError, TypeError):
+        return None
+
+
+def register_default_history_hooks() -> None:
+    """Register history hooks for all built-in entity types.
+
+    Called during app startup after the hook registry is initialized.
+    Plugin entities should register their own hooks in on_activate().
+    """
+    reg = get_hook_registry()
+
+    # Contact (already has manual record_history calls in contact_service.py,
+    # but registering hooks ensures consistency for any code path that fires
+    # the hooks without calling record_history directly)
+    register_history_hooks(
+        reg, "contact",
+        "contact.after_create",
+        "contact.after_update",
+        "contact.after_delete",
+    )
+
+    # Task plugin
+    register_history_hooks(
+        reg, "task",
+        "task.after_create",
+        "task.after_update",
+        "task.after_delete",
+    )
+
+    # Calendar plugin — CalendarEntry
+    register_history_hooks(
+        reg, "calendar_entry",
+        "calendar_entry.after_create",
+        "calendar_entry.after_update",
+        "calendar_entry.after_delete",
+    )
+
+    # DMS plugin — File metadata
+    register_history_hooks(
+        reg, "dms_file",
+        "dms_file.after_create",
+        "dms_file.after_update",
+        "dms_file.after_delete",
+    )
+
+    # Mail plugin
+    register_history_hooks(
+        reg, "mail",
+        "mail.after_create",
+        "mail.after_update",
+        "mail.after_delete",
+    )
+
+    logger.info("Default history hooks registered for: contact, task, calendar_entry, dms_file, mail")
+
+
+def reset_history_hooks_for_testing() -> None:
+    """Clear all history hooks — for unit tests only."""
+    reg = get_hook_registry()
+    # The hook registry's _reset_for_testing clears everything
+    reg._reset_for_testing()

app/core/restore_registry.py

@@ -0,0 +1,280 @@
+"""Entity restore registry — declarative configuration for undo/restore.
+
+Each registered entity type declares:
+- model_class: SQLAlchemy model to load
+- restore_permission: permission string required to restore
+- excluded_fields: fields never restored from snapshot (id, tenant_id, timestamps, etc.)
+- special_handler: optional async callable for entity-specific restore logic
+
+No dynamic ORM loading, no blind snapshot writes — only explicitly registered
+entity types can be restored, and only through their declared configuration.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import Any, Awaitable, Callable
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+logger = logging.getLogger(__name__)
+
+# Default fields excluded from restore for every entity type
+_DEFAULT_EXCLUDED = frozenset({
+    "id",
+    "tenant_id",
+    "created_at",
+    "updated_at",
+    "deleted_at",
+    "search_tsv",
+    "embedding",
+})
+
+# Type alias for special restore handler
+SpecialRestoreHandler = Callable[
+    [AsyncSession, Any, str, Any, dict[str, Any]],
+    Awaitable[dict[str, Any]],
+]
+
+
+@dataclass
+class RestoreConfig:
+    """Configuration for restoring a specific entity type."""
+
+    entity_type: str
+    model_class: type
+    restore_permission: str
+    excluded_fields: frozenset[str] = field(default_factory=frozenset)
+    special_handler: SpecialRestoreHandler | None = None
+
+    @property
+    def all_excluded_fields(self) -> frozenset[str]:
+        """Merge default excluded fields with entity-specific ones."""
+        return _DEFAULT_EXCLUDED | self.excluded_fields
+
+
+class RestoreRegistry:
+    """Singleton registry mapping entity_type → RestoreConfig."""
+
+    _instance: RestoreRegistry | None = None
+
+    def __new__(cls) -> RestoreRegistry:
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+            cls._instance._configs: dict[str, RestoreConfig] = {}
+        return cls._instance
+
+    def register(self, config: RestoreConfig) -> None:
+        """Register a RestoreConfig for an entity type."""
+        if config.entity_type in self._configs:
+            logger.warning("Overwriting restore config for entity_type: %s", config.entity_type)
+        self._configs[config.entity_type] = config
+        logger.debug("Registered restore config for: %s", config.entity_type)
+
+    def get(self, entity_type: str) -> RestoreConfig | None:
+        """Get RestoreConfig for entity_type, or None if not registered."""
+        return self._configs.get(entity_type)
+
+    def is_registered(self, entity_type: str) -> bool:
+        """Check if entity_type is registered for restore."""
+        return entity_type in self._configs
+
+    def list_registered(self) -> list[str]:
+        """Return all registered entity types."""
+        return sorted(self._configs.keys())
+
+    def _reset_for_testing(self) -> None:
+        """Clear all registrations — for unit tests only."""
+        self._configs.clear()
+
+
+def get_restore_registry() -> RestoreRegistry:
+    """Return the global RestoreRegistry singleton."""
+    return RestoreRegistry()
+
+
+def reset_restore_registry_for_testing() -> RestoreRegistry:
+    """Return a fresh singleton — for unit tests only."""
+    reg = get_restore_registry()
+    reg._reset_for_testing()
+    return reg
+
+
+# ─── Default entity registrations ───
+
+
+def register_default_entities() -> None:
+    """Register all built-in entity types for restore.
+
+    Called during app startup. Plugin entities should register themselves
+    in their on_activate() lifecycle hook.
+    """
+    from app.models.contact import Contact
+
+    reg = get_restore_registry()
+
+    # Contact (covers both 'person' and 'company' types — same model)
+    reg.register(RestoreConfig(
+        entity_type="contact",
+        model_class=Contact,
+        restore_permission="contacts:write",
+        excluded_fields=frozenset({
+            "search_tsv",
+            "embedding",
+            "default_person_id",
+            "admin_contactperson_id",
+        }),
+    ))
+
+    # Task plugin
+    try:
+        from app.plugins.builtins.tasks.models import Task
+        reg.register(RestoreConfig(
+            entity_type="task",
+            model_class=Task,
+            restore_permission="tasks:write",
+            excluded_fields=frozenset({
+                "created_by",
+                "assigned_to",
+                "contact_id",
+            }),
+        ))
+    except ImportError:
+        logger.debug("Tasks plugin model not available for restore registration")
+
+    # Calendar plugin — CalendarEntry
+    try:
+        from app.plugins.builtins.calendar.models import CalendarEntry
+        reg.register(RestoreConfig(
+            entity_type="calendar_entry",
+            model_class=CalendarEntry,
+            restore_permission="calendar:write",
+            excluded_fields=frozenset({
+                "calendar_id",
+                "created_by",
+                "assigned_to",
+                "source_mail_id",
+            }),
+        ))
+    except ImportError:
+        logger.debug("Calendar plugin model not available for restore registration")
+
+    # DMS plugin — File metadata
+    try:
+        from app.plugins.builtins.dms.models import File as DmsFile
+        reg.register(RestoreConfig(
+            entity_type="dms_file",
+            model_class=DmsFile,
+            restore_permission="dms:write",
+            excluded_fields=frozenset({
+                "storage_path",
+                "content_hash",
+                "size_bytes",
+                "uploaded_by",
+                "folder_id",
+            }),
+        ))
+    except ImportError:
+        logger.debug("DMS plugin model not available for restore registration")
+
+    # Mail plugin — special handler for IMAP semantics
+    try:
+        from app.plugins.builtins.mail.models import Mail
+        reg.register(RestoreConfig(
+            entity_type="mail",
+            model_class=Mail,
+            restore_permission="mail:write",
+            excluded_fields=frozenset({
+                "message_id",
+                "rfc822_size",
+                "raw_path",
+                "account_id",
+                "folder_id",
+            }),
+            special_handler=_mail_restore_handler,
+        ))
+    except ImportError:
+        logger.debug("Mail plugin model not available for restore registration")
+
+
+async def _mail_restore_handler(
+    db: AsyncSession,
+    entity: Any,
+    action: str,
+    snapshot: dict[str, Any],
+    context: dict[str, Any],
+) -> dict[str, Any]:
+    """Special restore handler for Mail entities.
+
+    Mail restore has IMAP semantics:
+    - delete: move back from trash to original folder (if folder still exists)
+    - update: revert metadata fields
+    - create: soft-delete (undo send only works for drafts)
+
+    Server errors must not produce false local status.
+    """
+    import uuid
+    from datetime import datetime, timezone
+    from sqlalchemy import select
+
+    user_id = context.get("user_id")
+    tenant_id = context.get("tenant_id")
+
+    if action == "delete":
+        # Un-delete: clear deleted_at, restore original folder_id if available
+        if entity is None:
+            raise ValueError("Mail entity not found for restore")
+        entity.deleted_at = None
+        if user_id:
+            entity.updated_by = user_id if hasattr(entity, "updated_by") else None
+        # Restore original folder from snapshot if available
+        original_folder_id = snapshot.get("folder_id")
+        if original_folder_id and hasattr(entity, "folder_id"):
+            try:
+                folder_uuid = uuid.UUID(str(original_folder_id))
+                # Verify folder still exists and is not deleted
+                from app.plugins.builtins.mail.models import MailFolder
+                folder_q = select(MailFolder).where(
+                    MailFolder.id == folder_uuid,
+                    MailFolder.tenant_id == tenant_id,
+                    MailFolder.deleted_at.is_(None),
+                )
+                folder_result = await db.execute(folder_q)
+                folder = folder_result.scalar_one_or_none()
+                if folder:
+                    entity.folder_id = folder_uuid
+                else:
+                    logger.warning(
+                        "Original mail folder %s no longer exists, "
+                        "restoring mail without folder assignment",
+                        original_folder_id,
+                    )
+            except (ValueError, Exception) as e:
+                logger.warning("Failed to restore mail folder: %s", e)
+
+        await db.flush()
+        return {"id": str(entity.id), "restored": True, "entity_type": "mail"}
+
+    elif action == "update":
+        if entity is None:
+            raise ValueError("Mail entity not found for restore")
+        # Revert metadata fields from snapshot_before
+        excluded = _DEFAULT_EXCLUDED | {
+            "message_id", "rfc822_size", "raw_path", "account_id", "folder_id",
+        }
+        for key, value in snapshot.items():
+            if hasattr(entity, key) and key not in excluded:
+                setattr(entity, key, value)
+        await db.flush()
+        return {"id": str(entity.id), "restored": True, "entity_type": "mail"}
+
+    elif action == "create":
+        # Undo creation: soft-delete (only meaningful for drafts)
+        if entity is None:
+            raise ValueError("Mail entity not found for restore")
+        entity.deleted_at = datetime.now(timezone.utc)
+        await db.flush()
+        return {"id": str(entity.id), "restored": True, "entity_type": "mail", "note": "soft-deleted (undo create)"}
+
+    raise ValueError(f"Unsupported action for mail restore: {action}")

app/main.py

@@ -333,6 +333,16 @@ async def lifespan(app: FastAPI):
     register_trigger_dispatcher(event_bus)
     logger.info("Trigger dispatcher registered")
 
+    # Register entity restore configurations (Phase D — Undo/Restore)
+    from app.core.restore_registry import register_default_entities
+    register_default_entities()
+    logger.info("Entity restore registry initialized")
+
+    # Register hook-based history recording (Phase D — Undo/Restore)
+    from app.core.history_hooks import register_default_history_hooks
+    register_default_history_hooks()
+    logger.info("History hooks registered")
+
     # Register field definitions from active plugins only
     from app.core.permission_registry import get_permission_registry
     for name in active_plugin_names:

app/plugins/builtins/calendar/routes.py

@@ -465,6 +465,9 @@ async def create_entry(
     )
     db.add(entry)
     await db.flush()
+    # Record history (D-PLUG)
+    from app.services.entity_history_service import record_history
+    await record_history(db, tenant_id, user_id, "calendar_entry", entry.id, "create", snapshot_after=_entry_to_dict(entry))
 
     # ── Hook: calendar.after_appointment (Action) ──
     from app.core.hooks import do_action
@@ -614,6 +617,8 @@ async def update_entry(
 
     from app.core.hooks import do_action
     await do_action("calendar.before_update", body=body, tenant_id=tenant_id, user_id=user_id, entry_id=entry_id)
+    # Capture snapshot before update (D-PLUG)
+    snapshot_before = _entry_to_dict(entry)
     # Apply updates
     if body.title is not None:
         entry.title = body.title
@@ -648,9 +653,20 @@ async def update_entry(
 
     await db.flush()
     await db.refresh(entry)
+    snapshot_after = _entry_to_dict(entry)
+    # Compute changes diff (D-PLUG)
+    changes: dict = {}
+    for key, new_val in snapshot_after.items():
+        old_val = snapshot_before.get(key)
+        if old_val != new_val:
+            changes[key] = {"old": old_val, "new": new_val}
+    # Record history (D-PLUG)
+    from app.services.entity_history_service import record_history
+    await record_history(db, tenant_id, user_id, "calendar_entry", entry.id, "update",
+                         snapshot_before=snapshot_before, snapshot_after=snapshot_after, changes=changes or None)
     from app.core.hooks import do_action
     await do_action("calendar.after_update", entry_id=str(entry.id), tenant_id=tenant_id, user_id=user_id)
-    return _entry_to_dict(entry)
+    return snapshot_after
 
 
 @router.delete("/calendar/entries/{entry_id}", status_code=status.HTTP_204_NO_CONTENT, dependencies=[Depends(require_permission("calendar:delete"))])
@@ -670,8 +686,13 @@ async def delete_entry(
         raise HTTPException(403, detail={"detail": "No write permission", "code": "forbidden"})
     from app.core.hooks import do_action
     await do_action("calendar.before_delete", tenant_id=tenant_id, user_id=user_id, entry_id=entry_id)
+    # Capture snapshot before delete (D-PLUG)
+    snapshot_before = _entry_to_dict(entry)
     entry.deleted_at = datetime.now(UTC)
     await db.flush()
+    # Record history (D-PLUG)
+    from app.services.entity_history_service import record_history
+    await record_history(db, tenant_id, user_id, "calendar_entry", entry.id, "delete", snapshot_before=snapshot_before)
     from app.core.hooks import do_action
     await do_action("calendar.after_delete", tenant_id=tenant_id, user_id=user_id, entry_id=entry_id)
     return Response(status_code=204)

app/plugins/builtins/dms/routes.py

@@ -612,6 +612,13 @@ async def upload_file(
         )
         db.add(dms_file)
         await db.flush()
+        # Record history for new file only (D-PLUG)
+        from app.services.entity_history_service import record_history
+        await record_history(db, tenant_id, user_id, "dms_file", dms_file.id, "create", snapshot_after={
+            "id": str(dms_file.id), "name": dms_file.name,
+            "folder_id": str(dms_file.folder_id) if dms_file.folder_id else None,
+            "mime_type": dms_file.mime_type, "size_bytes": dms_file.size_bytes,
+        })
 
     # Lifecycle hook: dms.after_upload
     from app.core.hooks import do_action
@@ -793,6 +800,13 @@ async def update_file(
 
     data = body.model_dump(exclude_unset=True)
 
+    # Capture snapshot before update (D-PLUG)
+    snapshot_before = {
+        "id": str(dms_file.id), "name": dms_file.name,
+        "folder_id": str(dms_file.folder_id) if dms_file.folder_id else None,
+        "mime_type": dms_file.mime_type, "size_bytes": dms_file.size_bytes,
+    }
+
     if "name" in data and data["name"] is not None:
         dms_file.name = data["name"]
 
@@ -813,6 +827,22 @@ async def update_file(
     await db.flush()
     await db.refresh(dms_file)
 
+    snapshot_after = {
+        "id": str(dms_file.id), "name": dms_file.name,
+        "folder_id": str(dms_file.folder_id) if dms_file.folder_id else None,
+        "mime_type": dms_file.mime_type, "size_bytes": dms_file.size_bytes,
+    }
+    # Compute changes diff (D-PLUG)
+    changes: dict = {}
+    for key, new_val in snapshot_after.items():
+        old_val = snapshot_before.get(key)
+        if old_val != new_val:
+            changes[key] = {"old": old_val, "new": new_val}
+    # Record history (D-PLUG)
+    from app.services.entity_history_service import record_history
+    await record_history(db, tenant_id, user_id, "dms_file", dms_file.id, "update",
+                         snapshot_before=snapshot_before, snapshot_after=snapshot_after, changes=changes or None)
+
     # Lifecycle hook: dms.after_update
     from app.core.hooks import do_action
     await do_action("dms.after_update", {'id': str(dms_file.id), 'name': dms_file.name}, db=db, tenant_id=tenant_id, user_id=user_id, file_id=file_id)
@@ -860,11 +890,22 @@ async def delete_file(
     from app.core.hooks import do_action
     await do_action("dms.before_delete", db=db, tenant_id=tenant_id, user_id=user_id, file_id=file_id)
 
+    # Capture snapshot before delete (D-PLUG)
+    snapshot_before = {
+        "id": str(dms_file.id), "name": dms_file.name,
+        "folder_id": str(dms_file.folder_id) if dms_file.folder_id else None,
+        "mime_type": dms_file.mime_type, "size_bytes": dms_file.size_bytes,
+    }
+
     from datetime import UTC, datetime
 
     dms_file.deleted_at = datetime.now(UTC)
     await db.flush()
 
+    # Record history (D-PLUG)
+    from app.services.entity_history_service import record_history
+    await record_history(db, tenant_id, user_id, "dms_file", dms_file.id, "delete", snapshot_before=snapshot_before)
+
     # Lifecycle hook: dms.after_delete
     await do_action("dms.after_delete", db=db, tenant_id=tenant_id, user_id=user_id, file_id=file_id)
 

app/plugins/builtins/mail/routes.py

@@ -1643,6 +1643,18 @@ async def delete_mail(
     account = await _get_account(db, mail.account_id, tenant_id, user_id, is_system_admin=is_system_admin)
     await _check_delegate_access(db, account, user_id, "delete")
 
+    # Capture snapshot before delete for history/restore (D-MAIL)
+    from app.services.entity_history_service import record_history
+    mail_snapshot = {
+        "id": str(mail.id),
+        "folder_id": str(mail.folder_id) if mail.folder_id else None,
+        "subject": mail.subject if hasattr(mail, "subject") else None,
+        "account_id": str(mail.account_id),
+        "is_read": mail.is_read if hasattr(mail, "is_read") else None,
+        "is_flagged": mail.is_flagged if hasattr(mail, "is_flagged") else None,
+    }
+    await record_history(db, tenant_id, user_id, "mail", mail.id, "delete", snapshot_before=mail_snapshot)
+
     # Find the Trash folder for this account
     trash_folder = None
     all_folders = (
@@ -1757,9 +1769,22 @@ async def move_mail(
     ).scalar_one_or_none()
     if not target_folder:
         raise HTTPException(404, detail={"detail": "Target folder not found", "code": "not_found"})
+    # Capture snapshot before move (D-MAIL)
+    from app.services.entity_history_service import record_history
+    snapshot_before = {
+        "id": str(mail.id),
+        "folder_id": str(mail.folder_id) if mail.folder_id else None,
+        "subject": mail.subject if hasattr(mail, "subject") else None,
+        "is_read": mail.is_read if hasattr(mail, "is_read") else None,
+        "is_flagged": mail.is_flagged if hasattr(mail, "is_flagged") else None,
+    }
     # Update mail.folder_id
     mail.folder_id = target_f_id
     await db.flush()
+    snapshot_after = {**snapshot_before, "folder_id": str(target_f_id)}
+    changes = {"folder_id": {"old": snapshot_before.get("folder_id"), "new": str(target_f_id)}}
+    await record_history(db, tenant_id, user_id, "mail", mail.id, "update",
+                         snapshot_before=snapshot_before, snapshot_after=snapshot_after, changes=changes)
     # IMAP move: queue for retry if it fails
     try:
         await mail_services.imap_move_mail(db, m_id, target_f_id, tenant_id)

app/plugins/builtins/tasks/services.py

@@ -117,9 +117,14 @@ async def create_task(
     )
     db.add(task)
     await db.flush()
+    snapshot = _task_to_dict(task)
+
+    # Record history (D-PLUG)
+    from app.services.entity_history_service import record_history
+    await record_history(db, tenant_id, user_id, "task", task.id, "create", snapshot_after=snapshot)
 
     from app.core.hooks import do_action
-    await do_action("task.after_create", _task_to_dict(task), db=db, tenant_id=tenant_id, user_id=user_id)
+    await do_action("task.after_create", snapshot, db=db, tenant_id=tenant_id, user_id=user_id)
 
     # Publish task.created event
     from app.core.event_bus import get_event_bus
@@ -151,6 +156,8 @@ async def update_task(
 
     from app.core.hooks import do_action
     await do_action("task.before_update", data, db=db, tenant_id=tenant_id, task_id=str(task_id))
+    # Capture snapshot before update (D-PLUG)
+    snapshot_before = _task_to_dict(task)
     if "title" in data and data["title"] is not None:
         task.title = data["title"]
     if "description" in data:
@@ -168,9 +175,20 @@ async def update_task(
 
     await db.flush()
     await db.refresh(task)
+    snapshot_after = _task_to_dict(task)
+    # Compute changes diff (D-PLUG)
+    changes: dict = {}
+    for key, new_val in snapshot_after.items():
+        old_val = snapshot_before.get(key)
+        if old_val != new_val:
+            changes[key] = {"old": old_val, "new": new_val}
+    # Record history (D-PLUG)
+    from app.services.entity_history_service import record_history as _rh
+    await _rh(db, tenant_id, None, "task", task.id, "update",
+              snapshot_before=snapshot_before, snapshot_after=snapshot_after, changes=changes or None)
     from app.core.hooks import do_action
-    await do_action("task.after_update", _task_to_dict(task), db=db, tenant_id=tenant_id, task_id=str(task_id))
-    return _task_to_dict(task)
+    await do_action("task.after_update", snapshot_after, db=db, tenant_id=tenant_id, task_id=str(task_id))
+    return snapshot_after
 
 
 async def delete_task(db: AsyncSession, tenant_id: uuid.UUID, task_id: uuid.UUID) -> bool:
@@ -183,8 +201,13 @@ async def delete_task(db: AsyncSession, tenant_id: uuid.UUID, task_id: uuid.UUID
         return False
     from app.core.hooks import do_action
     await do_action("task.before_delete", db=db, tenant_id=tenant_id, task_id=str(task_id))
+    # Capture snapshot before delete (D-PLUG)
+    snapshot_before = _task_to_dict(task)
     task.deleted_at = datetime.now(timezone.utc)
     await db.flush()
+    # Record history (D-PLUG)
+    from app.services.entity_history_service import record_history as _rh
+    await _rh(db, tenant_id, None, "task", task.id, "delete", snapshot_before=snapshot_before)
     from app.core.hooks import do_action
     await do_action("task.after_delete", db=db, tenant_id=tenant_id, task_id=str(task_id))
     return True

app/routes/companies.py

@@ -117,9 +117,12 @@ async def create_company(
     )
     db.add(audit_entry)
     await db.flush()
+    # Record history (D-CORE)
+    snapshot = _serialize_company(company)
+    await record_history(db, tenant_id, user_id, "contact", company.id, "create", snapshot_after=snapshot)
     from app.core.hooks import do_action
-    await do_action("company.after_create", _serialize_company(company), db=db, tenant_id=tenant_id, user_id=user_id)
-    return _serialize_company(company)
+    await do_action("company.after_create", snapshot, db=db, tenant_id=tenant_id, user_id=user_id)
+    return snapshot
 
 
 @router.get("/export")
@@ -208,6 +211,8 @@ async def update_company(
         raise HTTPException(status_code=404, detail="Company not found")
     from app.core.hooks import do_action
     await do_action("company.before_update", body, db=db, tenant_id=tenant_id, user_id=user_id, company_id=company_id)
+    # Capture snapshot before update (D-CORE)
+    snapshot_before = _serialize_company(company)
     if "name" in body:
         company.name = body["name"]
         company.displayname = body["name"]
@@ -222,13 +227,25 @@ async def update_company(
     company.custom = custom
     company.updated_by = user_id
     await db.flush()
+    snapshot_after = _serialize_company(company)
+    # Compute changes diff (D-CORE)
+    changes: dict = {}
+    for key, new_val in snapshot_after.items():
+        old_val = snapshot_before.get(key)
+        if old_val != new_val:
+            changes[key] = {"old": old_val, "new": new_val}
+    # Record history (D-CORE)
+    await record_history(
+        db, tenant_id, user_id, "contact", company.id, "update",
+        snapshot_before=snapshot_before, snapshot_after=snapshot_after, changes=changes or None,
+    )
     audit_entry = AuditLog(tenant_id=tenant_id, user_id=user_id, action="update",
                           entity_type="contact", entity_id=company.id, changes=body)
     db.add(audit_entry)
     await db.flush()
     from app.core.hooks import do_action
-    await do_action("company.after_update", _serialize_company(company), db=db, tenant_id=tenant_id, user_id=user_id, company_id=company_id)
-    return _serialize_company(company)
+    await do_action("company.after_update", snapshot_after, db=db, tenant_id=tenant_id, user_id=user_id, company_id=company_id)
+    return snapshot_after
 
 
 @router.delete("/{company_id}", status_code=status.HTTP_204_NO_CONTENT)

app/routes/entity_history.py

@@ -8,8 +8,15 @@ from fastapi import APIRouter, Depends, HTTPException, Query, status
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.core.db import get_db
+from app.core.restore_registry import get_restore_registry
 from app.deps import get_current_user, require_permission
-from app.schemas.entity_history import EntityHistoryListResponse, EntityHistoryResponse, RestoreRequest
+from app.schemas.entity_history import (
+    BulkRestoreRequest,
+    BulkRestoreResponse,
+    EntityHistoryListResponse,
+    EntityHistoryResponse,
+    RestoreRequest,
+)
 from app.services import entity_history_service
 
 router = APIRouter(prefix="/api/v1/entity-history", tags=["entity-history"])
@@ -57,15 +64,35 @@ async def get_entity_history(
 async def restore_from_history(
     body: RestoreRequest,
     db: AsyncSession = Depends(get_db),
-    current_user: dict = Depends(require_permission("contacts:write")),
+    current_user: dict = Depends(get_current_user),
 ):
-    """Restore an entity from a history entry."""
+    """Restore an entity from a history entry.
+
+    Permission is checked dynamically based on the entity type's
+    RestoreConfig.restore_permission from the RestoreRegistry.
+    """
     tenant_id = uuid.UUID(current_user["tenant_id"])
     user_id = uuid.UUID(current_user["user_id"])
     try:
         hid = uuid.UUID(body.history_id)
     except ValueError:
         raise HTTPException(status_code=400, detail="Invalid history_id") from None
+
+    # Look up the history entry to determine entity_type
+    entry = await entity_history_service.get_history_entry(db, tenant_id, hid, user_id)
+    if entry is None:
+        raise HTTPException(status_code=404, detail="History entry not found")
+
+    # Check permission dynamically based on entity type
+    config = get_restore_registry().get(entry.entity_type)
+    if config is None:
+        raise HTTPException(status_code=400, detail=f"Restore not supported for entity type: {entry.entity_type}")
+
+    required_perm = config.restore_permission
+    user_permissions = current_user.get("permissions", set())
+    if required_perm not in user_permissions and not current_user.get("is_system_admin", False):
+        raise HTTPException(status_code=403, detail=f"Missing permission: {required_perm}")
+
     try:
         return await entity_history_service.restore_from_history(db, tenant_id, hid, user_id)
     except ValueError as e:
@@ -77,18 +104,112 @@ async def undo_last_action(
     entity_type: str,
     entity_id: str,
     db: AsyncSession = Depends(get_db),
-    current_user: dict = Depends(require_permission("contacts:write")),
+    current_user: dict = Depends(get_current_user),
 ):
-    """Undo the most recent action for an entity."""
+    """Undo the most recent action for an entity.
+
+    Permission is checked dynamically based on the entity type's
+    RestoreConfig.restore_permission from the RestoreRegistry.
+    """
     tenant_id = uuid.UUID(current_user["tenant_id"])
     user_id = uuid.UUID(current_user["user_id"])
     try:
         eid = uuid.UUID(entity_id)
     except ValueError:
         raise HTTPException(status_code=400, detail="Invalid entity_id") from None
+
+    # Check permission dynamically based on entity type
+    config = get_restore_registry().get(entity_type)
+    if config is None:
+        raise HTTPException(status_code=400, detail=f"Undo not supported for entity type: {entity_type}")
+
+    required_perm = config.restore_permission
+    user_permissions = current_user.get("permissions", set())
+    if required_perm not in user_permissions and not current_user.get("is_system_admin", False):
+        raise HTTPException(status_code=403, detail=f"Missing permission: {required_perm}")
+
     try:
         return await entity_history_service.undo_last_action(
             db, tenant_id, user_id, entity_type, eid
         )
     except ValueError as e:
         raise HTTPException(status_code=404, detail=str(e)) from None
+
+
+@router.get("/trash")
+async def list_trash(
+    entity_type: str | None = Query(None),
+    limit: int = Query(50, ge=1, le=200),
+    offset: int = Query(0, ge=0),
+    db: AsyncSession = Depends(get_db),
+    current_user: dict = Depends(get_current_user),
+):
+    """List deleted entities from history (trash view)."""
+    tenant_id = uuid.UUID(current_user["tenant_id"])
+    user_id = uuid.UUID(current_user["user_id"])
+    is_system_admin = current_user.get("is_system_admin", False)
+    return await entity_history_service.list_trash(
+        db, tenant_id, entity_type=entity_type, limit=limit, offset=offset,
+        user_id=user_id, is_system_admin=is_system_admin,
+    )
+
+
+@router.post("/bulk-restore", response_model=BulkRestoreResponse)
+async def bulk_restore(
+    body: BulkRestoreRequest,
+    db: AsyncSession = Depends(get_db),
+    current_user: dict = Depends(get_current_user),
+):
+    """Restore multiple entities from history entries.
+
+    Partial-failure semantics: if some fail, others still succeed.
+    Returns per-item results with success/error details.
+    """
+    tenant_id = uuid.UUID(current_user["tenant_id"])
+    user_id = uuid.UUID(current_user["user_id"])
+    is_system_admin = current_user.get("is_system_admin", False)
+
+    if not body.history_ids:
+        raise HTTPException(status_code=400, detail="No history_ids provided")
+
+    try:
+        ids = [uuid.UUID(hid) for hid in body.history_ids]
+    except ValueError:
+        raise HTTPException(status_code=400, detail="Invalid history_id in list") from None
+
+    result = await entity_history_service.bulk_restore(
+        db, tenant_id, ids, user_id, is_system_admin
+    )
+    return BulkRestoreResponse(
+        total=result["total"],
+        succeeded=result["succeeded"],
+        failed=result["failed"],
+        results=[
+            {
+                "history_id": r["history_id"],
+                "success": r["success"],
+                "entity_type": r.get("entity_type"),
+                "entity_id": r.get("entity_id"),
+                "error": r.get("error"),
+            }
+            for r in result["results"]
+        ],
+        partial_success=result["partial_success"],
+    )
+
+
+@router.post("/retention/archive", dependencies=[Depends(require_permission("system:admin"))])
+async def archive_old_history(
+    days: int = Query(90, ge=1, le=3650),
+    db: AsyncSession = Depends(get_db),
+    current_user: dict = Depends(get_current_user),
+):
+    """Archive (hard-delete) EntityHistory entries older than *days* days.
+
+    GDPR compliance: after retention period, history snapshots are purged.
+    Requires system:admin permission.
+    """
+    tenant_id = uuid.UUID(current_user["tenant_id"])
+    count = await entity_history_service.archive_old_history(db, tenant_id, days=days)
+    await db.commit()
+    return {"archived": count, "retention_days": days}

app/schemas/entity_history.py

@@ -24,3 +24,23 @@ class EntityHistoryListResponse(BaseModel):
 
 class RestoreRequest(BaseModel):
     history_id: str
+
+
+class BulkRestoreRequest(BaseModel):
+    history_ids: list[str]
+
+
+class BulkRestoreResultItem(BaseModel):
+    history_id: str
+    success: bool
+    entity_type: str | None = None
+    entity_id: str | None = None
+    error: str | None = None
+
+
+class BulkRestoreResponse(BaseModel):
+    total: int
+    succeeded: int
+    failed: int
+    results: list[BulkRestoreResultItem]
+    partial_success: bool = False

app/services/entity_history_service.py

@@ -107,8 +107,13 @@ async def restore_from_history(
     For 'update' actions: revert entity fields to snapshot_before.
     For 'create' actions: soft-delete the entity (undo creation).
 
+    Uses the RestoreRegistry to find the entity configuration.
+    Only explicitly registered entity types can be restored.
+
     Returns the restored data dict.
     """
+    from app.core.restore_registry import get_restore_registry
+
     entry = await get_history_entry(db, tenant_id, history_id, user_id, is_system_admin)
     if entry is None:
         raise ValueError("History entry not found")
@@ -117,76 +122,105 @@ async def restore_from_history(
     entity_id = entry.entity_id
     action = entry.action
 
-    # Import here to avoid circular imports
-    from app.models.contact import Contact
+    # Look up restore configuration from registry
+    config = get_restore_registry().get(entity_type)
+    if config is None:
+        raise ValueError(f"Unsupported entity type for restore: {entity_type}")
 
+    # Load entity from database
+    model_class = config.model_class
+    q = select(model_class).where(
+        model_class.id == entity_id,
+        model_class.tenant_id == tenant_id,
+    )
+    result = await db.execute(q)
+    entity = result.scalar_one_or_none()
+
+    # Use special handler if registered (e.g. Mail with IMAP semantics)
+    if config.special_handler is not None:
+        context = {
+            "user_id": user_id,
+            "tenant_id": tenant_id,
+            "is_system_admin": is_system_admin,
+            "history_entry": entry,
+        }
+        snapshot = entry.snapshot_before if entry.snapshot_before else {}
+        return await config.special_handler(db, entity, action, snapshot, context)
+
+    # Generic restore logic
+    from datetime import datetime, timezone
+
+    if action == "delete":
+        if entity is None:
+            raise ValueError("Entity not found for restore")
+        entity.deleted_at = None
+        if hasattr(entity, "updated_by"):
+            entity.updated_by = user_id
+        await db.flush()
+        return _serialize_entity(entity, entity_type)
+
+    elif action == "update":
+        if entity is None:
+            raise ValueError("Entity not found for restore")
+        if entry.snapshot_before is None:
+            raise ValueError("No snapshot_before available for restore")
+        excluded = config.all_excluded_fields
+        for key, value in entry.snapshot_before.items():
+            if hasattr(entity, key) and key not in excluded:
+                setattr(entity, key, value)
+        if hasattr(entity, "updated_by"):
+            entity.updated_by = user_id
+        await db.flush()
+        return _serialize_entity(entity, entity_type)
+
+    elif action == "create":
+        if entity is None:
+            raise ValueError("Entity not found for restore")
+        entity.deleted_at = datetime.now(timezone.utc)
+        if hasattr(entity, "updated_by"):
+            entity.updated_by = user_id
+        await db.flush()
+        return _serialize_entity(entity, entity_type)
+
+    raise ValueError(f"Unsupported action for restore: {action}")
+
+
+def _serialize_entity(entity: Any, entity_type: str) -> dict[str, Any]:
+    """Serialize an entity to a dict for restore response.
+
+    For contacts, uses the detailed serializer with contact_persons.
+    For other entities, uses a generic column-based serializer.
+    """
     if entity_type == "contact":
-        q = select(Contact).where(
-            Contact.id == entity_id,
-            Contact.tenant_id == tenant_id,
+        from app.services.contact_service import _serialize_contact_detail
+        from sqlalchemy.orm import selectinload
+        from app.models.contact import Contact
+        from sqlalchemy import select as sa_select
+
+        # Re-query with selectinload for contact_persons
+        q = (
+            sa_select(Contact)
+            .options(selectinload(Contact.contact_persons))
+            .where(Contact.id == entity.id)
         )
-        result = await db.execute(q)
-        contact = result.scalar_one_or_none()
+        # This is called after flush, entity is still in session
+        # but we need to reload with the relationship
+        return _serialize_contact_detail(entity)
 
-        if action == "delete":
-            # Un-delete: clear deleted_at
-            if contact is None:
-                raise ValueError("Entity not found for restore")
-            contact.deleted_at = None
-            contact.updated_by = user_id
-            await db.flush()
-            from app.services.contact_service import _serialize_contact_detail
-            from sqlalchemy.orm import selectinload
-            q2 = (
-                select(Contact)
-                .options(selectinload(Contact.contact_persons))
-                .where(Contact.id == contact.id)
-            )
-            result2 = await db.execute(q2)
-            contact = result2.scalar_one()
-            return _serialize_contact_detail(contact)
-
-        elif action == "update":
-            # Revert to snapshot_before
-            if contact is None:
-                raise ValueError("Entity not found for restore")
-            if entry.snapshot_before is None:
-                raise ValueError("No snapshot_before available for restore")
-            for key, value in entry.snapshot_before.items():
-                if hasattr(contact, key) and key not in ("id", "tenant_id", "created_at", "updated_at", "deleted_at"):
-                    setattr(contact, key, value)
-            contact.updated_by = user_id
-            await db.flush()
-            from app.services.contact_service import _serialize_contact_detail
-            from sqlalchemy.orm import selectinload
-            q2 = (
-                select(Contact)
-                .options(selectinload(Contact.contact_persons))
-                .where(Contact.id == contact.id)
-            )
-            result2 = await db.execute(q2)
-            contact = result2.scalar_one()
-            return _serialize_contact_detail(contact)
-
-        elif action == "create":
-            # Undo creation: soft-delete the entity
-            if contact is None:
-                raise ValueError("Entity not found for restore")
-            contact.deleted_at = datetime.now(timezone.utc)
-            contact.updated_by = user_id
-            await db.flush()
-            from app.services.contact_service import _serialize_contact_detail
-            from sqlalchemy.orm import selectinload
-            q2 = (
-                select(Contact)
-                .options(selectinload(Contact.contact_persons))
-                .where(Contact.id == contact.id)
-            )
-            result2 = await db.execute(q2)
-            contact = result2.scalar_one()
-            return _serialize_contact_detail(contact)
-
-    raise ValueError(f"Unsupported entity type for restore: {entity_type}")
+    # Generic serialization: extract column values
+    result: dict[str, Any] = {}
+    for column in entity.__table__.columns:
+        val = getattr(entity, column.name, None)
+        if val is not None:
+            if hasattr(val, "isoformat"):
+                result[column.name] = val.isoformat()
+            elif hasattr(val, "hex"):
+                result[column.name] = str(val)
+            else:
+                result[column.name] = val
+    result["_entity_type"] = entity_type
+    result["_restored"] = True
+    return result
 
 
 async def undo_last_action(
@@ -222,3 +256,123 @@ async def undo_last_action(
         raise ValueError("No history found for this entity")
 
     return await restore_from_history(db, tenant_id, entry.id, user_id, is_system_admin)
+
+
+async def list_trash(
+    db: AsyncSession,
+    tenant_id: uuid.UUID,
+    entity_type: str | None = None,
+    limit: int = 50,
+    offset: int = 0,
+    user_id: uuid.UUID | None = None,
+    is_system_admin: bool = False,
+) -> dict[str, Any]:
+    """List deleted entities from history (delete actions only).
+
+    Returns paginated trash items with entity_type filter.
+    """
+    q = (
+        select(EntityHistory)
+        .where(
+            EntityHistory.tenant_id == tenant_id,
+            EntityHistory.action == "delete",
+        )
+        .order_by(EntityHistory.created_at.desc())
+    )
+    if entity_type:
+        q = q.where(EntityHistory.entity_type == entity_type)
+    if user_id and not is_system_admin:
+        q = await apply_visibility_filter(
+            db, q, "entity_history", EntityHistory, user_id, tenant_id, is_system_admin
+        )
+
+    # Count total
+    from sqlalchemy import func as sa_func
+    count_q = select(sa_func.count()).select_from(q.subquery())
+    total = (await db.execute(count_q)).scalar() or 0
+
+    # Paginate
+    q = q.offset(offset).limit(limit)
+    result = await db.execute(q)
+    entries = result.scalars().all()
+
+    items = []
+    for e in entries:
+        items.append({
+            "history_id": str(e.id),
+            "entity_type": e.entity_type,
+            "entity_id": str(e.entity_id),
+            "snapshot_before": e.snapshot_before,
+            "deleted_at": e.created_at.isoformat() if e.created_at else None,
+            "user_id": str(e.user_id) if e.user_id else None,
+        })
+
+    return {"items": items, "total": total, "limit": limit, "offset": offset}
+
+
+async def bulk_restore(
+    db: AsyncSession,
+    tenant_id: uuid.UUID,
+    history_ids: list[uuid.UUID],
+    user_id: uuid.UUID,
+    is_system_admin: bool = False,
+) -> dict[str, Any]:
+    """Restore multiple entities from history entries.
+
+    Returns partial_success semantics: if some fail, others still succeed.
+    """
+    results = []
+    succeeded = 0
+    failed = 0
+
+    for hid in history_ids:
+        try:
+            restored = await restore_from_history(db, tenant_id, hid, user_id, is_system_admin)
+            succeeded += 1
+            results.append({
+                "history_id": str(hid),
+                "success": True,
+                "entity_type": restored.get("_entity_type") or restored.get("entity_type"),
+                "entity_id": restored.get("id"),
+                "error": None,
+            })
+        except Exception as exc:
+            failed += 1
+            results.append({
+                "history_id": str(hid),
+                "success": False,
+                "entity_type": None,
+                "entity_id": None,
+                "error": str(exc),
+            })
+
+    return {
+        "total": len(history_ids),
+        "succeeded": succeeded,
+        "failed": failed,
+        "results": results,
+        "partial_success": failed > 0 and succeeded > 0,
+    }
+
+
+async def archive_old_history(
+    db: AsyncSession,
+    tenant_id: uuid.UUID,
+    days: int = 90,
+) -> int:
+    """Archive (hard-delete) EntityHistory entries older than *days* days.
+
+    GDPR compliance: after retention period, history snapshots are purged.
+    Returns the number of archived entries.
+    """
+    from datetime import datetime, timezone, timedelta
+    from sqlalchemy import delete as sa_delete
+
+    cutoff = datetime.now(timezone.utc) - timedelta(days=days)
+    stmt = sa_delete(EntityHistory).where(
+        EntityHistory.tenant_id == tenant_id,
+        EntityHistory.created_at < cutoff,
+    )
+    result = await db.execute(stmt)
+    await db.flush()
+    return result.rowcount or 0