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
2026-08-13 23:08:29 +02:00
parent 29410f19d3
commit a4d0f0c35d
22 changed files with 2175 additions and 91 deletions
@@ -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()
@@ -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}")