feat(psa): add PSA abstraction layer — base types, exceptions, abstract interface

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

backend/app/services/psa/base.py

@@ -0,0 +1,68 @@
+"""Abstract base class for PSA provider implementations."""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from .types import (
+    ConnectionTestResult,
+    PSATicket,
+    PSANote,
+    PSAStatus,
+    PSACompany,
+    PSAMember,
+    PSAConfiguration,
+)
+
+
+class PSAProvider(ABC):
+    """Abstract base for PSA integrations (ConnectWise, Autotask, etc.)."""
+
+    @abstractmethod
+    async def test_connection(self) -> ConnectionTestResult:
+        ...
+
+    @abstractmethod
+    async def get_ticket(self, ticket_id: str) -> PSATicket:
+        ...
+
+    @abstractmethod
+    async def search_tickets(self, query: str, **filters) -> list[PSATicket]:
+        ...
+
+    @abstractmethod
+    async def post_note(
+        self,
+        ticket_id: str,
+        text: str,
+        note_type: str,
+        member_id: str | None = None,
+    ) -> PSANote:
+        ...
+
+    @abstractmethod
+    async def update_ticket_status(
+        self,
+        ticket_id: str,
+        status_id: int,
+    ) -> PSATicket:
+        ...
+
+    @abstractmethod
+    async def get_ticket_statuses(self, board_id: int) -> list[PSAStatus]:
+        ...
+
+    @abstractmethod
+    async def list_companies(self, **filters) -> list[PSACompany]:
+        ...
+
+    @abstractmethod
+    async def get_company(self, company_id: str) -> PSACompany:
+        ...
+
+    @abstractmethod
+    async def list_members(self) -> list[PSAMember]:
+        ...
+
+    @abstractmethod
+    async def get_ticket_configurations(self, ticket_id: str) -> list[PSAConfiguration]:
+        ...