feat: add search questions generation with database migration and UI

Database & Backend:
- Add search_questions column migration in operations.py (ALTER TABLE for existing databases)
- Add /api/kba/drafts/{id}/replace endpoint in app.py
- Fix backward compatibility in kba_service.py (_table_to_draft, _draft_to_table)
- Add search questions generation to replace_draft workflow
- Fix NULL constraint errors by ensuring empty strings for required fields
- Update related_tickets validation: accept INC + 9-12 digits (was fixed at 12)

Frontend:
- Add Text component import to KBADrafterPage.jsx (fix TypeError)
- Add full-screen blur overlay with centered spinner during KBA generation
- Show overlay for both new draft creation and replacement operations
- Update styles: loadingOverlay with backdrop-filter blur effect

Documentation:
- Update kba_prompts.py: clarify related_tickets format with examples
- Update GENERAL.md: correct related_tickets format specification

Fixes #1 - KBA drafts not loading (missing DB column)
Fixes #2 - Replace endpoint not found (405 error)
Fixes #3 - Ticket ID validation too strict

Author: SubSonic731

backend/app.py

@@ -1054,6 +1054,19 @@ async def rest_kba_update_draft(draft_id: str):
         return jsonify({"error": str(e)}), 400
 
 
+@app.route("/api/kba/drafts/<draft_id>/replace", methods=["POST"])
+async def rest_kba_replace_draft(draft_id: str):
+    """REST wrapper: replace/regenerate KBA draft."""
+    try:
+        from operations import op_kba_replace_draft
+        data = await request.get_json() if await request.data else {}
+        user_id = data.get("user_id", "anonymous")
+        draft = await op_kba_replace_draft(draft_id, user_id)
+        return jsonify(draft.model_dump())
+    except Exception as e:
+        return jsonify({"error": str(e)}), 500
+
+
 @app.route("/api/kba/drafts/<draft_id>", methods=["DELETE"])
 async def rest_kba_delete_draft(draft_id: str):
     """REST wrapper: delete KBA draft."""

backend/kb_adapters.py

@@ -206,6 +206,18 @@ def _generate_markdown(self, draft: dict[str, Any], visibility: str) -> str:
             ""
         ]
 
+        # Search Questions (after header, before symptoms)
+        if draft.get("search_questions"):
+            lines.extend([
+                "## Häufige Suchanfragen",
+                "",
+                "*Benutzer suchen häufig nach:*",
+                ""
+            ])
+            for question in draft["search_questions"]:
+                lines.append(f"- {question}")
+            lines.extend(["", "---", ""])
+        
         # Symptoms
         if draft.get("symptoms"):
             lines.extend([

backend/kba_models.py

@@ -107,6 +107,12 @@ class KBADraft(BaseModel):
     tags: list[str] = Field(default_factory=list, description="Search tags (lowercase)")
     related_tickets: list[str] = Field(default_factory=list, description="Related incident IDs")
 
+    # Search Questions
+    search_questions: list[str] = Field(
+        default_factory=list,
+        description="User search queries - how users might search for this KBA"
+    )
+    
     # Guidelines used during generation
     guidelines_used: list[str] = Field(default_factory=list, description="Guideline categories used")
 
@@ -187,6 +193,7 @@ class KBADraftUpdate(BaseModel):
     # Metadata
     tags: Optional[list[str]] = None
     related_tickets: Optional[list[str]] = None
+    search_questions: Optional[list[str]] = None
     status: Optional[KBADraftStatus] = None
     reviewed_by: Optional[str] = None  # Set when status → reviewed
 
@@ -259,6 +266,7 @@ class KBADraftTable(SQLModel, table=True):
     additional_notes: str = ""
     tags: list[str] = SQLField(sa_column=Column(JSON))
     related_tickets: list[str] = SQLField(sa_column=Column(JSON))
+    search_questions: list[str] = SQLField(sa_column=Column(JSON))
     guidelines_used: list[str] = SQLField(sa_column=Column(JSON))
 
     # Metadata

backend/kba_output_models.py

@@ -81,6 +81,12 @@ class KBAOutputSchema(BaseModel):
         description="Related incident IDs in format INC0001234"
     )
 
+    # Search Questions (generated separately, not part of main draft generation)
+    search_questions: Optional[list[str]] = Field(
+        default_factory=list,
+        description="User search queries - generated in separate step"
+    )
+    
     # Legacy fields (optional for backward compatibility)
     problem_description: Optional[str] = Field(
         default="",
@@ -127,13 +133,14 @@ def validate_tags(cls, v: list[str]) -> list[str]:
     @field_validator('related_tickets')
     @classmethod
     def validate_related_tickets(cls, v: list[str]) -> list[str]:
-        """Ensure ticket IDs match INC format - supports 12-digit format"""
+        """Ensure ticket IDs match INC format - supports 9-12 digit format"""
         import re
         for ticket in v:
-            # Support real format: INC000016312744 (12 digits)
-            if not re.match(r'^INC[0-9]{12}$', ticket):
+            # Support both short (INC000016346) and full format (INC000016312744)
+            # INC followed by 9-12 digits
+            if not re.match(r'^INC[0-9]{9,12}$', ticket):
                 raise ValueError(
-                    f"Ticket ID '{ticket}' must match format INC000012345678 (INC + 12 digits)"
+                    f"Ticket ID '{ticket}' must match format INC + 9-12 digits (e.g., INC000016346)"
                 )
         return v
 
@@ -185,8 +192,127 @@ def validate_warnings(cls, v: Optional[list[str]]) -> list[str]:
                 "confidence_notes": "Lösung basiert auf häufigem Windows 11 Update-Problem",
                 "tags": ["vpn", "windows-11", "firewall", "openvpn", "timeout"],
                 "related_tickets": [],
+                "search_questions": [
+                    "Wie behebe ich VPN-Verbindungsprobleme unter Windows 11?",
+                    "VPN bricht nach 30 Sekunden ab was tun?",
+                    "OpenVPN Connection Timeout Error 10060 lösen",
+                    "Warum verbindet sich mein VPN nicht mehr?",
+                    "Windows Firewall blockiert VPN-Verbindung"
+                ],
                 "problem_description": "",
                 "additional_notes": ""
             }
         }
     }
+
+
+# ============================================================================
+# SEARCH QUESTIONS SCHEMA & VALIDATION
+# ============================================================================
+
+class SearchQuestionsSchema(BaseModel):
+    """
+    Schema for LLM-generated search questions (separate generation step).
+    
+    Used with OpenAI's beta.chat.completions.parse() for automatic validation.
+    """
+    
+    questions: list[str] = Field(
+        ...,
+        min_length=5,
+        max_length=15,
+        description="User search queries - how users might search for this KBA"
+    )
+    
+    @field_validator('questions')
+    @classmethod
+    def validate_questions_format(cls, v: list[str]) -> list[str]:
+        """Basic validation - detailed cleaning happens in service layer"""
+        if not v:
+            raise ValueError("Questions list cannot be empty")
+        
+        # Basic length checks
+        for q in v:
+            if not q or not q.strip():
+                raise ValueError("Empty question not allowed")
+            q_stripped = q.strip()
+            if len(q_stripped) < 10:
+                raise ValueError(f"Question too short (min 10 chars): '{q[:30]}...'")
+            if len(q_stripped) > 200:
+                raise ValueError(f"Question too long (max 200 chars): '{q[:50]}...'")
+        
+        return v
+    
+    model_config = {
+        "extra": "forbid",
+        "json_schema_extra": {
+            "example": {
+                "questions": [
+                    "Wie behebe ich VPN-Verbindungsprobleme unter Windows 11?",
+                    "VPN bricht nach 30 Sekunden ab was tun?",
+                    "OpenVPN Connection Timeout Error 10060",
+                    "Warum verbindet sich mein VPN nicht?",
+                    "Windows Firewall blockiert VPN"
+                ]
+            }
+        }
+    }
+
+
+def validate_and_clean_search_questions(
+    questions: list[str],
+    min_questions: int = 5,
+    max_questions: int = 15
+) -> list[str]:
+    """
+    Validate and clean search questions with deduplication.
+    
+    Args:
+        questions: Raw questions from LLM
+        min_questions: Minimum required questions
+        max_questions: Maximum allowed questions
+        
+    Returns:
+        Cleaned and deduplicated question list
+        
+    Raises:
+        ValueError: If validation fails
+    """
+    import re
+    
+    # Step 1: Trim and filter empty
+    cleaned = []
+    for q in questions:
+        q_stripped = q.strip()
+        if q_stripped:
+            cleaned.append(q_stripped)
+    
+    # Step 2: Validate length
+    valid = []
+    for q in cleaned:
+        if 10 <= len(q) <= 200:
+            valid.append(q)
+    
+    # Step 3: Deduplicate (case-insensitive, normalized)
+    seen = set()
+    deduplicated = []
+    for q in valid:
+        # Normalize: lowercase, remove extra whitespace
+        normalized = re.sub(r'\s+', ' ', q.lower())
+        if normalized not in seen:
+            seen.add(normalized)
+            deduplicated.append(q)  # Keep original casing
+    
+    # Step 4: Enforce min/max
+    if len(deduplicated) < min_questions:
+        raise ValueError(
+            f"Only {len(deduplicated)} valid questions after cleaning "
+            f"(required: {min_questions}). "
+            f"Raw count: {len(questions)}, after filtering: {len(valid)}"
+        )
+    
+    if len(deduplicated) > max_questions:
+        # Truncate to max
+        deduplicated = deduplicated[:max_questions]
+    
+    return deduplicated

backend/kba_prompts.py

@@ -124,6 +124,8 @@ def escape_braces(text: Optional[str]) -> str:
 
 **tags** (REQUIRED): Lowercase Suchbegriffe, 2-10 Tags
 
+**related_tickets** (OPTIONAL): Verwandte Incident-IDs (Format: INC + 9-12 Ziffern, z.B. INC000016346 oder INC000016312744). Verwende die EXAKTE Incident-ID aus dem Ticket ohne Änderungen.
+
 **Wichtig**:
 - Formuliere aus Sicht des Endbenutzers, nicht des Technikers
 - NUR JSON ausgeben, kein zusätzlicher Text oder Markdown-Wrapper!
@@ -220,3 +222,95 @@ def build_markdown_fallback_prompt(ticket: Ticket, guidelines: str) -> str:
 tag1, tag2, tag3"""
 
     return prompt
+
+
+def build_search_questions_prompt(draft_data: dict) -> str:
+    """
+    Build prompt for generating search questions from a KBA draft.
+    
+    Args:
+        draft_data: Dictionary with KBA draft fields (title, symptoms, resolution_steps, etc.)
+        
+    Returns:
+        Prompt string for search question generation
+    """
+    import json
+    
+    # Create clean JSON representation of KBA draft
+    kba_draft_json = json.dumps({
+        "title": draft_data.get("title", ""),
+        "symptoms": draft_data.get("symptoms", []),
+        "cause": draft_data.get("cause", ""),
+        "resolution_steps": draft_data.get("resolution_steps", []),
+        "tags": draft_data.get("tags", []),
+        "validation_checks": draft_data.get("validation_checks", []),
+        "warnings": draft_data.get("warnings", [])
+    }, ensure_ascii=False, indent=2)
+    
+    prompt = f"""Erstelle aus dem folgenden KBA-Draft eine Liste von Suchfragen, die Benutzer in einer Knowledge Base eingeben könnten, um genau diesen Artikel zu finden.
+
+Regeln:
+- Verwende nur Informationen aus dem KBA-Draft.
+- Keine erfundenen Details.
+- Fragen müssen klar, neutral und suchbar sein.
+- Erzeuge eine Mischung aus:
+  - symptom-orientierten Fragen
+  - problem-/ursachen-orientierten Fragen
+  - lösungsorientierten Fragen
+  - kurzen natürlichen Suchanfragen
+- Keine Duplikate oder fast identischen Fragen.
+- Sprache soll zur Sprache des KBA passen.
+- Gib nur das geforderte JSON zurück.
+
+KBA-Draft:
+{kba_draft_json}
+
+Erwartetes JSON-Schema:
+{{
+  "questions": ["...", "..."]
+}}
+
+BEGINNE MIT DEM JSON:"""
+    
+    return prompt
+
+
+def build_search_questions_correction_prompt(
+    original_prompt: str,
+    failed_output: str,
+    validation_error: str
+) -> str:
+    """
+    Build correction prompt for search questions retry.
+    
+    Args:
+        original_prompt: Original prompt that was sent
+        failed_output: Output that failed validation
+        validation_error: Error message from validation
+        
+    Returns:
+        Correction prompt with error feedback
+    """
+    prompt = f"""{original_prompt}
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+FEHLER IN DEINEM VORHERIGEN OUTPUT:
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Dein Output:
+{failed_output[:500]}...
+
+Validierungsfehler:
+{validation_error}
+
+KORREKTUR:
+- Stelle sicher, dass mindestens 5 valide Fragen vorhanden sind
+- Jede Frage muss 10-200 Zeichen lang sein
+- Keine leeren Strings oder Duplikate
+- Format: {{"questions": ["...", "..."]}}
+- Nur Informationen aus dem KBA-Draft verwenden
+
+NUR JSON zurückgeben, kein zusätzlicher Text!
+BEGINNE MIT {{:"""
+    
+    return prompt