feat(products): streamed export service + TEL-3 + EmptyCatalog (PUC-9, §9.1)

backend/app/domains/products/__init__.py

@@ -11,6 +11,7 @@ from pathlib import Path
 from .errors import (
     DraftExpired,
     DraftNotFound,
+    EmptyCatalog,
     FileRejected,
     NothingToApply,
     PreviewStale,
@@ -21,6 +22,7 @@ from .models import MAX_DATA_ROWS, MAX_FILE_BYTES
 from .service import (
     confirm_draft,
     discard_draft,
+    export_catalog,
     get_draft,
     get_draft_records,
     get_run,
@@ -34,8 +36,8 @@ SAMPLE_CSV_PATH = Path(__file__).parent / "sample.csv"
 
 __all__ = [
     "ProductsError", "FileRejected", "DraftNotFound", "DraftExpired",
-    "PreviewStale", "NothingToApply", "RunNotFound",
+    "PreviewStale", "NothingToApply", "RunNotFound", "EmptyCatalog",
     "MAX_DATA_ROWS", "MAX_FILE_BYTES", "SAMPLE_CSV_PATH",
     "import_validate", "get_draft", "get_draft_records", "discard_draft",
-    "confirm_draft", "list_runs", "get_run", "summary",
+    "confirm_draft", "list_runs", "get_run", "summary", "export_catalog",
 ]

backend/app/domains/products/errors.py

@@ -35,3 +35,7 @@ class NothingToApply(ProductsError):
 
 class RunNotFound(ProductsError):
     """No such import run for this storefront."""
+
+
+class EmptyCatalog(ProductsError):
+    """PUC-9: nothing to export (no products, or none matching the status filter)."""

backend/app/domains/products/service.py

@@ -7,14 +7,22 @@ writes exactly one row — the import_draft. TEL events per §9.1.
 from __future__ import annotations
 
 import time
+from collections.abc import Iterator
 from datetime import datetime, timezone
 
 import psycopg
 
 from app.platform import telemetry
 
-from . import codec, diff, repo, validate
-from .errors import DraftExpired, DraftNotFound, NothingToApply, PreviewStale, RunNotFound
+from . import codec, diff, repo, serialize, validate
+from .errors import (
+    DraftExpired,
+    DraftNotFound,
+    EmptyCatalog,
+    NothingToApply,
+    PreviewStale,
+    RunNotFound,
+)
 
 
 def import_validate(conn: psycopg.Connection, storefront_id: int, account_id: int,
@@ -218,6 +226,34 @@ def get_run(conn: psycopg.Connection, storefront_id: int, run_id: int) -> dict:
     return run
 
 
+def export_catalog(
+    conn: psycopg.Connection, storefront_id: int, status_filter: str
+) -> Iterator[str]:
+    """Stream the storefront's catalog as canonical CSV (PUC-9; INV-12 codec).
+
+    Read-only: builds the snapshot, then streams the serializer over it. TEL-3
+    is emitted once the stream is exhausted, with the product count and elapsed
+    time. Raises EmptyCatalog before yielding anything if the (filtered) catalog
+    is empty, so the BFF can answer 409 cleanly with no partial body.
+    """
+    started = time.monotonic()
+    snapshot = repo.export_catalog(conn, storefront_id, status_filter)
+    if not snapshot:
+        raise EmptyCatalog()
+
+    def _stream() -> Iterator[str]:
+        yield from serialize.catalog_to_csv(snapshot)
+        telemetry.emit(
+            "catalog_exported",
+            storefront_id=storefront_id,
+            status_filter=status_filter,
+            product_count=len(snapshot),
+            duration_ms=int((time.monotonic() - started) * 1000),
+        )
+
+    return _stream()
+
+
 def summary(conn: psycopg.Connection, storefront_id: int) -> dict:
     """The products dashboard counts (§6.4)."""
     return {