feat(#359): W4a Phase 1 — Import/Export Contribution-Architektur Kern

- Format-Registry (app/core/importexport_registry.py): FormatHandler-Protokoll,
  available_for() Schnittmenge, Singleton + Testing-Reset
- importexport_formats-Plugin (csv/json/xlsx), lifecycle-korrekt: on_activate
  registriert Handler in der Core-Registry, on_deactivate unregistriert
- ContactsContract: importexport-Beitrag (ie_*-Methoden) — Contacts besitzt
  seine Import/Export-Fachlogik jetzt selbst
- import_export_service.py: generische Engine, delegiert generisch ueber
  registry.list_discovered() an den besitzenden Contract (keine hartcodierten
  Plugin-Namen mehr); Signaturen identisch
- Funktionserhalt bewiesen: 45/45 import_export-Suite passed (inkl.
  Fehler-Multiplizitaet: 2 failed rows -> 3 total_errors, erreicht via
  ie_required-Weitergabe + ie_row_valid-Nur-contacts-Early-Return)

fixes #359 (Phase 1)

app/plugins/builtins/contacts/contracts.py

@@ -106,6 +106,203 @@ class ContactsContract:
             c.deleted_at = datetime.now(UTC)
         return {"contacts_soft_deleted": len(contacts)}
 
+    # ─── Import/Export contribution (W4a, Spec #359) ───
+    # The contacts plugin owns its import/export domain logic; the core
+    # orchestrator resolves formats via the format registry and enforces
+    # the security policy (sensitive filter, tenant scoping, audit).
+
+    IE_COLUMNS = {
+        "contacts": ["firstname", "surname", "email", "phone", "mobile", "function", "department"],
+        "companies": ["name", "industry", "phone", "email", "website"],
+    }
+    IE_TARGET_FIELDS = {
+        "contacts": ["firstname", "surname", "email", "phone", "mobile", "function", "department"],
+        "companies": ["name", "industry", "phone", "email", "website"],
+    }
+    IE_VALIDATORS = {
+        "contacts": {"email": {"type": "email"}},
+        "companies": {"email": {"type": "email"}, "website": {"type": "url"}},
+    }
+
+    @staticmethod
+    def importexport_entities() -> list[str]:
+        """Entity types offered by this plugin's import/export."""
+        return ["contacts", "companies"]
+
+    @staticmethod
+    def importexport_formats() -> list[str]:
+        """File formats this plugin's import/export supports."""
+        return ["csv", "json", "xlsx"]
+
+    @staticmethod
+    def ie_columns(entity_type: str) -> list[str]:
+        return list(ContactsContract.IE_COLUMNS[entity_type])
+
+    @staticmethod
+    def ie_target_fields(entity_type: str) -> list[str]:
+        return list(ContactsContract.IE_TARGET_FIELDS[entity_type])
+
+    @staticmethod
+    def ie_validators(entity_type: str) -> dict[str, dict]:
+        return dict(ContactsContract.IE_VALIDATORS[entity_type])
+
+    @staticmethod
+    def ie_normalize_row(entity_type: str, row: dict[str, str]) -> dict[str, str]:
+        """Normalize an imported row to unified field names."""
+        if entity_type == "contacts":
+            firstname = (row.get("firstname") or row.get("first_name") or "").strip()
+            surname = (row.get("surname") or row.get("last_name") or "").strip()
+            row["firstname"] = firstname
+            row["surname"] = surname
+            if "email" not in row and "email_address" in row:
+                row["email"] = row["email_address"]
+            if "mobile" not in row and "phone_2" in row:
+                row["mobile"] = row["phone_2"]
+            if "function" not in row and "position" in row:
+                row["function"] = row["position"]
+            return row
+        name = (row.get("name") or row.get("company") or row.get("company_name") or "").strip()
+        row["name"] = name
+        if "email" not in row and "email_address" in row:
+            row["email"] = row["email_address"]
+        if "website" not in row and "url" in row:
+            row["website"] = row["url"]
+        if "website" not in row and "homepage" in row:
+            row["website"] = row["homepage"]
+        return row
+
+    @staticmethod
+    def ie_required(entity_type: str) -> list[str]:
+        """Required columns enforced by generic validate_row (old semantics)."""
+        return ["name"] if entity_type == "companies" else []
+
+    @staticmethod
+    def ie_row_valid(entity_type: str, row: dict[str, str]) -> tuple[bool, str]:
+        """Early either-or check for contacts only.
+
+        NOTE: companies' required-name check must NOT happen here —
+        generic validate_row(row, ['name'], validators) must see the row
+        so a missing name AND an invalid email yield two errors (as the
+        original semantics did).
+        """
+        if entity_type == "contacts":
+            if not row.get("firstname") and not row.get("surname"):
+                return False, "Missing required field: firstname or surname"
+        return True, ""
+
+    @staticmethod
+    async def ie_fetch_rows(
+        db: AsyncSession,
+        tenant_id: Any,
+        entity_type: str,
+        user_id: Any = None,
+        is_system_admin: bool = False,
+    ) -> tuple[list[str], list[dict[str, Any]]]:
+        """Fetch export rows (headers + row dicts), visibility-filtered."""
+        q = select(Contact).where(
+            Contact.tenant_id == tenant_id,
+            Contact.deleted_at.is_(None),
+        )
+        if entity_type == "companies":
+            q = q.where(Contact.type == "company").order_by(Contact.name)
+        else:
+            q = q.order_by(Contact.surname, Contact.firstname)
+        if user_id:
+            q = await apply_visibility_filter(
+                db, q, "contact", Contact, user_id, tenant_id, is_system_admin
+            )
+        records = (await db.execute(q)).scalars().all()
+        if entity_type == "companies":
+            headers = ["id", "type", "name", "email", "phone", "website", "city", "postalcode", "country"]
+            rows = [
+                {
+                    "id": str(c.id),
+                    "type": c.type or "company",
+                    "name": c.name or "",
+                    "email": c.email_1 or "",
+                    "phone": c.phone_1 or "",
+                    "website": c.website or "",
+                    "city": c.mailing_city or "",
+                    "postalcode": c.mailing_postalcode or "",
+                    "country": c.mailing_country or "",
+                }
+                for c in records
+            ]
+        else:
+            headers = ["id", "type", "firstname", "surname", "name", "email", "phone", "mobile", "city", "postalcode", "country"]
+            rows = [
+                {
+                    "id": str(c.id),
+                    "type": c.type or "person",
+                    "firstname": c.firstname or "",
+                    "surname": c.surname or "",
+                    "name": c.name or "",
+                    "email": c.email_1 or "",
+                    "phone": c.phone_1 or "",
+                    "mobile": c.phone_2 or "",
+                    "city": c.mailing_city or "",
+                    "postalcode": c.mailing_postalcode or "",
+                    "country": c.mailing_country or "",
+                }
+                for c in records
+            ]
+        return headers, rows
+
+    @staticmethod
+    async def ie_persist_row(
+        db: AsyncSession,
+        tenant_id: Any,
+        user_id: Any,
+        entity_type: str,
+        row: dict[str, str],
+    ) -> dict[str, Any]:
+        """Persist one imported row as Contact; returns the serialized record."""
+        from app.core.audit import log_audit
+        from app.services.contact_service import _serialize_contact
+
+        if entity_type == "companies":
+            contact = Contact(
+                tenant_id=tenant_id,
+                type="company",
+                name=row["name"].strip(),
+                displayname=row["name"].strip(),
+                email_1=row.get("email", "").strip() or None,
+                phone_1=row.get("phone", "").strip() or None,
+                website=row.get("website", "").strip() or None,
+                owner_id=user_id,
+                created_by=user_id,
+                updated_by=user_id,
+            )
+        else:
+            contact = Contact(
+                tenant_id=tenant_id,
+                type="person",
+                firstname=row["firstname"].strip() or None,
+                surname=row["surname"].strip() or None,
+                displayname=f"{row['firstname']} {row['surname']}".strip(),
+                email_1=row.get("email", "").strip() or None,
+                phone_1=row.get("phone", "").strip() or None,
+                phone_2=row.get("mobile", "").strip() or None,
+                owner_id=user_id,
+                created_by=user_id,
+                updated_by=user_id,
+            )
+        db.add(contact)
+        await db.flush()
+        await log_audit(
+            db,
+            tenant_id,
+            user_id,
+            "import",
+            "contact",
+            contact.id,
+            changes={
+                "type": entity_type.rstrip("s"),
+                "name": contact.name or f"{contact.firstname} {contact.surname}",
+            },
+        )
+        return _serialize_contact(contact)
+
     @classmethod
     def get_function(cls, name: str):
         """Return a callable exposed by this contract, or None if absent."""

app/plugins/builtins/importexport_formats/__init__.py

@@ -0,0 +1,5 @@
+"""Import/export formats plugin — provides the standard file formats."""
+
+from app.plugins.builtins.importexport_formats.plugin import ImportExportFormatsPlugin
+
+__all__ = ["ImportExportFormatsPlugin"]

app/plugins/builtins/importexport_formats/formats.py

@@ -0,0 +1,48 @@
+"""Standard format handlers — thin wrappers around the core helpers.
+
+No business logic here: parse/serialize only. Business logic (columns,
+normalization, validation, persistence) lives in the entity module's
+contract contribution (e.g. ContactsContract.importexport).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from app.services import import_export_helpers as helpers
+
+
+class CsvFormat:
+    format_id = "csv"
+
+    @staticmethod
+    def parse(filename: str, content: bytes) -> list[dict[str, Any]]:
+        return helpers.parse_csv(content)
+
+    @staticmethod
+    def serialize(rows: list[dict[str, Any]], headers: list[str]) -> bytes:
+        return helpers.write_csv(rows, headers)
+
+
+class JsonFormat:
+    format_id = "json"
+
+    @staticmethod
+    def parse(filename: str, content: bytes) -> list[dict[str, Any]]:
+        return helpers.parse_json(content)
+
+    @staticmethod
+    def serialize(rows: list[dict[str, Any]], headers: list[str]) -> bytes:
+        return helpers.write_json(rows)
+
+
+class XlsxFormat:
+    format_id = "xlsx"
+
+    @staticmethod
+    def parse(filename: str, content: bytes) -> list[dict[str, Any]]:
+        return helpers.parse_xlsx(content)
+
+    @staticmethod
+    def serialize(rows: list[dict[str, Any]], headers: list[str]) -> bytes:
+        return helpers.write_xlsx(rows, headers)

app/plugins/builtins/importexport_formats/plugin.py

@@ -0,0 +1,52 @@
+"""Import/export formats plugin — provides standard file formats as plugins.
+
+Part of the W4a contribution architecture (Spec #359): file formats live in
+this plugin instead of being hardcoded in the core orchestrator. New formats
+(e.g. PDF later) are added as additional format plugins without touching the
+core.
+
+Lifecycle: registers the bundled handlers (csv, json, xlsx) in the core
+format registry on activate, unregisters them on deactivate.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from app.core.importexport_registry import get_format_registry
+from app.plugins.base import BasePlugin
+from app.plugins.builtins.importexport_formats.formats import CsvFormat, JsonFormat, XlsxFormat
+from app.plugins.manifest import PluginManifest
+
+
+class ImportExportFormatsPlugin(BasePlugin):
+    """Bundles the standard import/export file formats."""
+
+    manifest = PluginManifest(
+        name="importexport_formats",
+        version="1.0.0",
+        display_name="Import/Export Formate",
+        description="Standard-Formate für Import/Export: CSV, JSON, XLSX.",
+        dependencies=[],
+        routes=[],
+        events=[],
+        migrations=[],
+        permissions=[],
+        is_core=True,
+    )
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._handlers: list[Any] = [CsvFormat(), JsonFormat(), XlsxFormat()]
+
+    async def on_activate(self, db, service_container, event_bus) -> None:
+        await super().on_activate(db, service_container, event_bus)
+        registry = get_format_registry()
+        for handler in self._handlers:
+            registry.register(handler)
+
+    async def on_deactivate(self, db, service_container, event_bus) -> None:
+        await super().on_deactivate(db, service_container, event_bus)
+        registry = get_format_registry()
+        for handler in self._handlers:
+            registry.unregister(handler.format_id)