feat: implement self-contained module architecture (Phase 1 & 2)

Phase 1 - Foundation:
- Add app/modules/contracts/ with Protocol definitions for cross-module
  communication (ServiceProtocol, ContentServiceProtocol, MediaServiceProtocol)
- Enhance app/modules/base.py ModuleDefinition with self-contained module
  support (is_self_contained, services_path, models_path, etc.)
- Update app/templates_config.py with multi-directory template loading
  using Jinja2 ChoiceLoader for module templates

Phase 2 - CMS Pilot Module:
- Migrate CMS service to app/modules/cms/services/content_page_service.py
- Create app/modules/cms/exceptions.py with CMS-specific exceptions
- Configure app/modules/cms/models/ to re-export ContentPage from canonical
  location (models.database) to avoid circular imports
- Update cms_module definition with is_self_contained=True and paths
- Add backwards compatibility shims with deprecation warnings:
  - app/services/content_page_service.py -> app.modules.cms.services
  - app/exceptions/content_page.py -> app.modules.cms.exceptions

Note: SQLAlchemy models remain in models/database/ as the canonical location
to avoid circular imports at startup time. Module model packages re-export
from the canonical location.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

app/modules/cms/__init__.py

@@ -2,8 +2,13 @@
 """
 CMS Module - Content Management System.
 
+This is a SELF-CONTAINED module that includes:
+- Services: content_page_service (business logic)
+- Models: ContentPage (database model)
+- Exceptions: ContentPageNotFoundException, etc.
+
 This module provides:
-- Content pages management
+- Content pages management (three-tier: platform, vendor default, vendor override)
 - Media library
 - Vendor themes
 - SEO tools
@@ -15,6 +20,16 @@ Routes:
 Menu Items:
 - Admin: content-pages, vendor-themes
 - Vendor: content-pages, media
+
+Usage:
+    # Preferred: Import from module directly
+    from app.modules.cms.services import content_page_service
+    from app.modules.cms.models import ContentPage
+    from app.modules.cms.exceptions import ContentPageNotFoundException
+
+    # Legacy: Still works via re-export shims (deprecated)
+    from app.services.content_page_service import content_page_service
+    from models.database.content_page import ContentPage
 """
 
 from app.modules.cms.definition import cms_module

app/modules/cms/definition.py

@@ -3,7 +3,15 @@
 CMS module definition.
 
 Defines the CMS module including its features, menu items,
-and route configurations.
+route configurations, and self-contained component paths.
+
+This is a self-contained module with:
+- Services: app.modules.cms.services
+- Models: app.modules.cms.models
+- Exceptions: app.modules.cms.exceptions
+
+Templates remain in core (app/templates/admin/) for now due to
+admin/base.html inheritance dependency.
 """
 
 from app.modules.base import ModuleDefinition
@@ -24,7 +32,7 @@ def _get_vendor_router():
     return vendor_router
 
 
-# CMS module definition
+# CMS module definition - Self-contained module (pilot)
 cms_module = ModuleDefinition(
     code="cms",
     name="Content Management",
@@ -48,6 +56,13 @@ cms_module = ModuleDefinition(
         ],
     },
     is_core=False,
+    # Self-contained module configuration
+    is_self_contained=True,
+    services_path="app.modules.cms.services",
+    models_path="app.modules.cms.models",
+    exceptions_path="app.modules.cms.exceptions",
+    # Templates remain in core for now (admin/content-pages*.html)
+    templates_path=None,
 )
 
 

app/modules/cms/exceptions.py

@@ -0,0 +1,110 @@
+# app/modules/cms/exceptions.py
+"""
+CMS Module Exceptions
+
+These exceptions are raised by the CMS module service layer
+and converted to HTTP responses by the global exception handler.
+"""
+
+from app.exceptions.base import (
+    AuthorizationException,
+    BusinessLogicException,
+    ConflictException,
+    ResourceNotFoundException,
+    ValidationException,
+)
+
+
+class ContentPageNotFoundException(ResourceNotFoundException):
+    """Raised when a content page is not found."""
+
+    def __init__(self, identifier: str | int | None = None):
+        if identifier:
+            message = f"Content page not found: {identifier}"
+        else:
+            message = "Content page not found"
+        super().__init__(
+            message=message,
+            resource_type="content_page",
+            identifier=str(identifier) if identifier else "unknown",
+        )
+
+
+class ContentPageAlreadyExistsException(ConflictException):
+    """Raised when a content page with the same slug already exists."""
+
+    def __init__(self, slug: str, vendor_id: int | None = None):
+        if vendor_id:
+            message = f"Content page with slug '{slug}' already exists for this vendor"
+        else:
+            message = f"Platform content page with slug '{slug}' already exists"
+        super().__init__(message=message)
+
+
+class ContentPageSlugReservedException(ValidationException):
+    """Raised when trying to use a reserved slug."""
+
+    def __init__(self, slug: str):
+        super().__init__(
+            message=f"Content page slug '{slug}' is reserved",
+            field="slug",
+            value=slug,
+        )
+
+
+class ContentPageNotPublishedException(BusinessLogicException):
+    """Raised when trying to access an unpublished content page."""
+
+    def __init__(self, slug: str):
+        super().__init__(message=f"Content page '{slug}' is not published")
+
+
+class UnauthorizedContentPageAccessException(AuthorizationException):
+    """Raised when a user tries to access/modify a content page they don't own."""
+
+    def __init__(self, action: str = "access"):
+        super().__init__(
+            message=f"Cannot {action} content pages from other vendors",
+            error_code="CONTENT_PAGE_ACCESS_DENIED",
+            details={"required_permission": f"content_page:{action}"},
+        )
+
+
+class VendorNotAssociatedException(AuthorizationException):
+    """Raised when a user is not associated with a vendor."""
+
+    def __init__(self):
+        super().__init__(
+            message="User is not associated with a vendor",
+            error_code="VENDOR_NOT_ASSOCIATED",
+            details={"required_permission": "vendor:member"},
+        )
+
+
+class ContentPageValidationException(ValidationException):
+    """Raised when content page data validation fails."""
+
+    def __init__(self, field: str, message: str, value: str | None = None):
+        super().__init__(message=message, field=field, value=value)
+
+
+class MediaNotFoundException(ResourceNotFoundException):
+    """Raised when a media item is not found."""
+
+    def __init__(self, identifier: str | int | None = None):
+        if identifier:
+            message = f"Media item not found: {identifier}"
+        else:
+            message = "Media item not found"
+        super().__init__(
+            message=message,
+            resource_type="media",
+            identifier=str(identifier) if identifier else "unknown",
+        )
+
+
+class MediaUploadException(BusinessLogicException):
+    """Raised when a media upload fails."""
+
+    def __init__(self, reason: str):
+        super().__init__(message=f"Media upload failed: {reason}")

app/modules/cms/models/__init__.py

@@ -0,0 +1,20 @@
+# app/modules/cms/models/__init__.py
+"""
+CMS module database models.
+
+This package re-exports the ContentPage model from its canonical location
+in models.database. SQLAlchemy models must remain in a single location to
+avoid circular imports at startup time.
+
+Usage:
+    from app.modules.cms.models import ContentPage
+
+The canonical model is at: models.database.content_page.ContentPage
+"""
+
+# Import from canonical location to avoid circular imports
+from models.database.content_page import ContentPage
+
+__all__ = [
+    "ContentPage",
+]

app/modules/cms/services/__init__.py

@@ -0,0 +1,16 @@
+# app/modules/cms/services/__init__.py
+"""
+CMS module services.
+
+This package contains all business logic for the CMS module.
+"""
+
+from app.modules.cms.services.content_page_service import (
+    ContentPageService,
+    content_page_service,
+)
+
+__all__ = [
+    "ContentPageService",
+    "content_page_service",
+]