feat: DSE parser + matcher — textblock references in scan findings

- dse_parser.py: HTML → structured sections (heading, number, content, parent)
  Uses heading hierarchy (h1-h4) with regex fallback
- dse_matcher.py: matches detected services against DSE sections
  Exact name → provider → category matching with insertion point suggestion
- agent_scan_routes: TextReference model in findings (original text,
  section, paragraph, correction type, insert_after)

Enables showing: "Google Analytics not found in DSE, insert after
Section 2.4 Cookies und Tracking"

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

backend-compliance/compliance/api/agent_scan_routes.py

@@ -16,6 +16,8 @@ from pydantic import BaseModel
 from compliance.services.website_scanner import scan_website, DetectedService
 from compliance.services.dse_service_extractor import extract_dse_services, compare_services
 from compliance.services.smtp_sender import send_email
+from compliance.services.dse_parser import parse_dse
+from compliance.services.dse_matcher import build_text_references, TextReference
 
 logger = logging.getLogger(__name__)
 
@@ -49,11 +51,27 @@ class ServiceInfo(BaseModel):
     status: str  # "ok", "undocumented", "outdated"
 
 
+class TextReferenceModel(BaseModel):
+    found: bool = False
+    source_url: str = ""
+    document_type: str = "Datenschutzerklaerung"
+    section_heading: str = ""
+    section_number: str = ""
+    parent_section: str = ""
+    paragraph_index: int = 0
+    original_text: str = ""
+    issue: str = ""
+    correction_type: str = ""
+    correction_text: str = ""
+    insert_after: str = ""
+
+
 class ScanFinding(BaseModel):
     code: str
     severity: str
     text: str
     correction: str = ""
+    text_reference: TextReferenceModel | None = None
 
 
 class ScanResponse(BaseModel):
@@ -87,14 +105,22 @@ async def scan_website_endpoint(req: ScanRequest):
     dse_services = await extract_dse_services(dse_text) if dse_text else []
     logger.info("DSE mentions %d services", len(dse_services))
 
-    # Step 4: SOLL/IST comparison
+    # Step 4: Parse DSE into structured sections
+    dse_html = await _fetch_dse_html(req.url, scan.pages_scanned)
+    dse_sections = parse_dse(dse_html, req.url) if dse_html else []
+    logger.info("Parsed %d DSE sections", len(dse_sections))
+
+    # Step 5: SOLL/IST comparison
     detected_dicts = [_service_to_dict(s) for s in scan.detected_services]
     comparison = compare_services(detected_dicts, dse_services)
 
-    # Step 5: Generate findings
-    services_info, findings = _build_findings(comparison, scan, is_live)
+    # Step 6: Build TextReferences for each detected service
+    text_refs = build_text_references(detected_dicts, dse_services, dse_sections, req.url)
 
-    # Step 6: Generate corrections for pre-launch mode
+    # Step 7: Generate findings with text references
+    services_info, findings = _build_findings(comparison, scan, is_live, text_refs)
+
+    # Step 8: Generate corrections for pre-launch mode
     if not is_live and findings:
         await _add_corrections(findings, dse_text)
 
@@ -149,6 +175,24 @@ async def _fetch_dse_text(url: str, scanned_pages: list[str]) -> str:
         return ""
 
 
+async def _fetch_dse_html(url: str, scanned_pages: list[str]) -> str:
+    """Fetch the raw HTML of the privacy policy page (for structured parsing)."""
+    import re
+    dse_url = None
+    for page in scanned_pages:
+        if re.search(r"datenschutz|privacy|dsgvo", page, re.IGNORECASE):
+            dse_url = page
+            break
+    if not dse_url:
+        dse_url = url
+    try:
+        async with httpx.AsyncClient(timeout=15.0, follow_redirects=True) as client:
+            resp = await client.get(dse_url, headers={"User-Agent": "BreakPilot-Compliance-Agent/1.0"})
+            return resp.text
+    except Exception:
+        return ""
+
+
 def _service_to_dict(svc: DetectedService) -> dict:
     return {
         "id": svc.id, "name": svc.name, "category": svc.category,
@@ -159,11 +203,25 @@ def _service_to_dict(svc: DetectedService) -> dict:
 
 
 def _build_findings(
-    comparison: dict, scan, is_live: bool,
+    comparison: dict, scan, is_live: bool, text_refs: dict | None = None,
 ) -> tuple[list[ServiceInfo], list[ScanFinding]]:
     """Build service info list and findings from comparison."""
     services = []
     findings = []
+    text_refs = text_refs or {}
+
+    def _get_ref(svc_id: str) -> TextReferenceModel | None:
+        ref = text_refs.get(svc_id)
+        if not ref:
+            return None
+        return TextReferenceModel(
+            found=ref.found, source_url=ref.source_url,
+            document_type=ref.document_type, section_heading=ref.section_heading,
+            section_number=ref.section_number, parent_section=ref.parent_section,
+            paragraph_index=ref.paragraph_index, original_text=ref.original_text,
+            issue=ref.issue, correction_type=ref.correction_type,
+            correction_text=ref.correction_text, insert_after=ref.insert_after,
+        )
 
     # Undocumented services (on website, NOT in DSE)
     for svc in comparison["undocumented"]:
@@ -175,12 +233,14 @@ def _build_findings(
             legal_ref=svc.get("legal_ref", ""), in_dse=False, status="undocumented",
         ))
         severity = "HIGH" if is_live else "MEDIUM"
+        ref = _get_ref(svc.get("id", ""))
         findings.append(ScanFinding(
             code=f"DSE-MISSING-{svc['id'].upper()}",
             severity=severity,
             text=f"{svc['name']} ({svc.get('provider', '')}, {svc.get('country', '')}) "
                  f"ist auf der Website eingebunden aber NICHT in der Datenschutzerklaerung "
                  f"dokumentiert (Art. 13 DSGVO).",
+            text_reference=ref,
         ))
 
     # Documented services (OK)