feat(diagnostics): send a bug report to a private Gitea issue tracker (E16 S4)

- admin config group "Bug reports": Gitea address, repository, token (secret),
  and "Check the connection" — the repository must answer, take issues and
  be PRIVATE (a report carries its reporter's log); checked on every send too
- POST /api/debug-sessions/{id}/issue sends the SAVED draft: create the issue,
  upload each file on its own request (the measured API), then show the
  screenshots inline; progress is kept in the draft, so a send that stops
  half-way keeps its issue and the retry sends only what is missing; 5 new
  issues an hour per user; audited as issue_create
- the composer: Create issue (only where a tracker is set up, naming the
  repository), a partial-send banner with retry, and a Preview — the tracker's
  own rendering in a sandboxed frame, or the zip's markdown without one
- the recorder's refusals answer in the localized family (debug_session_*,
  screenshot_*, issue(s)_*), not bare codes the UI could only call generic
- a tracker refusal logs the status only: its message can quote the title back

backend/app/routes/debug_sessions.py

@@ -20,12 +20,15 @@ from sqlalchemy import select
 from sqlalchemy.exc import IntegrityError
 from sqlalchemy.orm import Session
 
-from app import debugsession, logs, logsink
+from app import audit, debugsession, logs, logsink
+from app.audit import AuditAction
 from app.auth import require_human
 from app.db import get_db
-from app.issues import bundle
+from app.issues import bundle, gitea
+from app.ratelimit import RateLimiter
+from app.refusal import refused
 from app.models import DebugScreenshot, DebugSession, User
-from app.routes._common import capped_body, not_found, owned_or_404
+from app.routes._common import capped_body, issue_refused, not_found, owned_or_404
 from app.utils import iso
 
 router = APIRouter(prefix="/api/debug-sessions", tags=["diagnostics"])
@@ -58,7 +61,7 @@ def start_session(
         db.rollback()
         session = debugsession.open_session(db, user)
         if session is None:
-            raise HTTPException(status_code=409, detail={"code": "session_conflict"})
+            raise refused(409, "debug_session_conflict") from None
     # The rest of THIS request is part of the session too.
     level, until = debugsession.level_for(user, session)
     logs.set_user(user.id, level, until, session.id)
@@ -139,7 +142,7 @@ def save_draft(
     session = owned_or_404(db, DebugSession, sid, user, what="debug_session")
     if session.issue_url is not None:
         # Sent: the issue is on the tracker now, and a draft edited after it would say otherwise.
-        raise HTTPException(status_code=409, detail={"code": "already_sent"})
+        raise refused(409, "issue_already_sent")
     if len(json.dumps(body.form, ensure_ascii=False).encode()) > FORM_MAX_BYTES:
         raise HTTPException(status_code=413, detail={"code": "too_large"})
     debugsession.save_draft(session, body.model_dump())
@@ -167,6 +170,72 @@ def export_session(
     )
 
 
+# --- the issue tracker (S4) -----------------------------------------------------------------
+# Issues a user may OPEN per hour — finishing a half-sent one is not counted. The composer sends one
+# at a time; this is room for a bad afternoon, not a pace anything legitimate keeps up.
+_new_issues = RateLimiter(max_events=5, window_seconds=3600)
+
+
+@router.post("/{sid}/issue")
+def send_issue(
+    sid: str, user: User = Depends(require_human), db: Session = Depends(get_db)
+) -> dict:
+    """Send the session's issue to the tracker — from the SAVED draft, as the export is built — or
+    finish a send that stopped half-way (the issue exists; only what is missing is sent)."""
+    session = owned_or_404(db, DebugSession, sid, user, what="debug_session")
+    new = session.issue_url is None
+    if not new and not gitea.pending(session):
+        return {"ok": True, "session": _view(db, session)}
+    if new:
+        if not ((session.draft or {}).get("title") or "").strip():
+            raise refused(422, "issue_title_required")
+        if not _new_issues.allow(str(user.id)):
+            raise refused(429, "issues_rate_limited")
+    try:
+        gitea.deliver(db, session)
+    except gitea.GiteaError as exc:
+        # Keep what did happen: an issue created before an upload failed stays linked, and the
+        # retry sends only the files still missing.
+        _record_created(db, user, session, new)
+        db.commit()
+        raise issue_refused(exc) from None
+    _record_created(db, user, session, new)
+    db.commit()
+    return {"ok": True, "session": _view(db, session)}
+
+
+def _record_created(db: Session, user: User, session: DebugSession, new: bool) -> None:
+    if new and session.issue_url:
+        audit.record(
+            db,
+            user.id,
+            AuditAction.ISSUE_CREATE,
+            target_type="debug_session",
+            target_id=session.id,
+            summary=session.issue_url,
+        )
+
+
+class PreviewIn(BaseModel):
+    text: str = Field(max_length=50_000)
+
+
+@router.post("/{sid}/preview")
+def preview_issue(
+    sid: str,
+    body: PreviewIn,
+    user: User = Depends(require_human),
+    db: Session = Depends(get_db),
+) -> dict:
+    """The body as the tracker will render it. Gitea sanitises its own output; the composer still
+    shows it in a sandboxed frame, never in the app's own document."""
+    owned_or_404(db, DebugSession, sid, user, what="debug_session")
+    try:
+        return {"ok": True, "html": gitea.preview(db, body.text)}
+    except gitea.GiteaError as exc:
+        raise issue_refused(exc) from None
+
+
 # --- screenshots ---------------------------------------------------------------------------
 def _shot_view(shot: DebugScreenshot) -> dict:
     return {"id": shot.id, "mime": shot.mime, "size": shot.size, "created_at": iso(shot.created_at)}
@@ -201,13 +270,23 @@ def add_screenshot(
     try:
         shot = debugsession.add_screenshot(db, session, data)
     except debugsession.ScreenshotRefused as exc:
-        raise HTTPException(
-            status_code=422, detail={"code": "screenshot_refused", "reason": exc.code}
-        ) from exc
+        raise _screenshot_refused(exc.code) from None
     db.commit()
     return {"ok": True, "screenshot": _shot_view(shot)}
 
 
+def _screenshot_refused(code: str) -> HTTPException:
+    # Literal reasons, one per case: the frontend's contract test reads them to require a sentence
+    # for each in both languages.
+    if code == "already_sent":
+        return refused(409, "screenshot_already_sent")
+    if code == "too_many":
+        return refused(422, "screenshot_too_many", limit=debugsession.SCREENSHOTS_MAX)
+    if code == "empty":
+        return refused(422, "screenshot_empty")
+    return refused(422, "screenshot_not_an_image")
+
+
 def _session_screenshot(db: Session, sid: str, shot_id: int, user: User) -> DebugScreenshot:
     session = owned_or_404(db, DebugSession, sid, user, what="debug_session")
     shot = db.get(DebugScreenshot, shot_id)