feat(crm): catálogos Clientes/Prospectos (enriquecido) y Proveedores + direcciones/documentos

Alinea el dominio al spec de catálogos:
- accounts (Clientes/Prospectos): tipo registro/persona, CURP, clasificación
  comercial, bloque fiscal (régimen, CFDI, pago, crédito), auditoría, notas internas
- suppliers (Proveedores): clasificación múltiple, cobertura, países/puertos/
  aeropuertos/aduanas (JSON), fiscal
- addresses y documents: tablas compartidas con FK a cliente o proveedor
- contacts enriquecidos (extensión, whatsapp, área, flags "recibe…", supplier_id)
- migración a7b8c9d0e1f2 (ALTER + CREATE) con downgrade completo
- permisos supplier/address/document; seed de datos actualizado
- 39 tests pytest en verde

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

backend/api/v1/modules/crm/contacts/service.py

@@ -4,29 +4,47 @@ from fastapi import HTTPException, status
 from sqlalchemy.orm import Session
 
 from ..accounts.models import Account
+from ..suppliers.models import Supplier
 from .dto import ContactCreate, ContactUpdate
 from .models import Contact
 
 
-def _validate_account(db: Session, account_id: int | None, tenant_id: int, company_id: int) -> None:
-    """Verifica que la cuenta referenciada exista dentro del tenant/company."""
-    if account_id is None:
-        return
-    exists = (
-        db.query(Account.id)
-        .filter(
-            Account.id == account_id,
-            Account.tenant_id == tenant_id,
-            Account.company_id == company_id,
-            Account.deleted_at.is_(None),
+def _validate_parent(db: Session, data: dict, tenant_id: int, company_id: int) -> None:
+    """Verifica que el cliente/proveedor referenciado exista en el tenant/company."""
+    account_id = data.get("account_id")
+    if account_id is not None:
+        exists = (
+            db.query(Account.id)
+            .filter(
+                Account.id == account_id,
+                Account.tenant_id == tenant_id,
+                Account.company_id == company_id,
+                Account.deleted_at.is_(None),
+            )
+            .first()
         )
-        .first()
-    )
-    if not exists:
-        raise HTTPException(
-            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
-            detail="La cuenta asociada no existe",
+        if not exists:
+            raise HTTPException(
+                status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+                detail="El cliente asociado no existe",
+            )
+    supplier_id = data.get("supplier_id")
+    if supplier_id is not None:
+        exists = (
+            db.query(Supplier.id)
+            .filter(
+                Supplier.id == supplier_id,
+                Supplier.tenant_id == tenant_id,
+                Supplier.company_id == company_id,
+                Supplier.deleted_at.is_(None),
+            )
+            .first()
         )
+        if not exists:
+            raise HTTPException(
+                status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+                detail="El proveedor asociado no existe",
+            )
 
 
 def get_contacts(
@@ -35,6 +53,7 @@ def get_contacts(
     company_id: int,
     search: str | None = None,
     account_id: int | None = None,
+    supplier_id: int | None = None,
 ) -> list[Contact]:
     query = db.query(Contact).filter(
         Contact.tenant_id == tenant_id,
@@ -43,6 +62,8 @@ def get_contacts(
     )
     if account_id is not None:
         query = query.filter(Contact.account_id == account_id)
+    if supplier_id is not None:
+        query = query.filter(Contact.supplier_id == supplier_id)
     if search:
         pattern = f"%{search}%"
         query = query.filter(
@@ -70,8 +91,9 @@ def get_contact(db: Session, contact_id: int, tenant_id: int, company_id: int) -
 
 
 def create_contact(db: Session, payload: ContactCreate, tenant_id: int, company_id: int) -> Contact:
-    _validate_account(db, payload.account_id, tenant_id, company_id)
-    contact = Contact(**payload.model_dump(), tenant_id=tenant_id, company_id=company_id)
+    data = payload.model_dump()
+    _validate_parent(db, data, tenant_id, company_id)
+    contact = Contact(**data, tenant_id=tenant_id, company_id=company_id)
     db.add(contact)
     db.commit()
     db.refresh(contact)
@@ -83,8 +105,7 @@ def update_contact(
 ) -> Contact:
     contact = get_contact(db, contact_id, tenant_id, company_id)
     data = payload.model_dump(exclude_unset=True)
-    if "account_id" in data:
-        _validate_account(db, data["account_id"], tenant_id, company_id)
+    _validate_parent(db, data, tenant_id, company_id)
     for field, value in data.items():
         setattr(contact, field, value)
     db.commit()