Mara přidává komentář k existujícímu issue — buď automaticky při dedup okně (UC-09001 Flow 2), nebo explicitně při opakovaném výskytu nebo doplňujícím kontextu na žádost usera.

• Komentář přidává výhradně Mara (Phase 1). Admin může komentovat přes triage flow (UC-09004 — resolution_note), ale pro strukturované komentáře používá stejný endpoint s Admin JWT.
• Mara nesmí komentovat cizí issues — issue_id musí patřit reporter_user_id extrahovanému z JWT. Admin JWT: bez omezení.
• Komentář je prostý markdown text. Žádné inline image uploady v Phase 1.

Flow 1 — Mara přidá komentář k existujícímu issue (dedup)

Viz UC-09001 Flow 2 — server přidá auto-komentář při dedup hitu. Tento flow popisuje explicitní volání od Mara.

sequenceDiagram
    actor Mara

    Mara->>Mara: identifikuje existující issue (#ID) jako relevantní k aktuálnímu selhání

    Mara->>+BE: tool: comment_issue(issue_id, body)
    Note over BE: POST /api/issues/{id}/comments<br/>Authorization: Bearer {agentJWT}

    BE->>BE: ověř JWT, extrahuj reporter_user_id

    BE->>DB: SELECT issues WHERE id = ? AND reporter_user_id = ? (non-admin)
    alt issue neexistuje nebo patří jinému userovi
        BE-->>Mara: 404 Not Found
    end

    BE->>DB: INSERT issue_comments (id=UUID, issue_id, author_user_id=<z JWT>,<br/>author_agent=MARA, body, created_at=now())

    BE-->>-Mara: 201 Created { comment_id }

    Mara-->>User: "K existujícímu issue [#ID](url) jsem přidala poznámku o opakování."

Flow 2 — Admin přidá komentář při triage

sequenceDiagram
    actor Admin as Admin (Mirek)

    Admin->>+BE: POST /api/issues/{id}/comments
    Note over BE: Authorization: Bearer {adminJWT}<br/>{ body: "Zkouším reprodukovat — Mirek" }

    BE->>BE: ověř Admin JWT (platform_admin role)

    BE->>DB: SELECT issues WHERE id = ? (bez scope filtru pro admin)
    alt issue neexistuje
        BE-->>Admin: 404 Not Found
    end

    BE->>DB: INSERT issue_comments (author_user_id=<admin userId>,<br/>author_agent=ADMIN, body, created_at=now())

    BE-->>-Admin: 201 Created { comment_id }

Tool API (Mara)

comment_issue(
  issue_id: string,   // UUID existujícího issue
  body: string        // markdown text komentáře
): {
  comment_id: string  // UUID nově vytvořeného komentáře
}

REST API

POST /api/issues/{id}/comments

Autentizace: Agent JWT (Mara) nebo Admin JWT (platform_admin role).

Request:

{
  "body": "Stalo se znovu při deployi projektu demo-app. Kaniko log: `unauthorized: authentication required`. Session ID: abc-123. Workaround: manuální docker login + push funguje."
}

201 Created:

{
  "comment_id": "661f9511-f3ac-52e5-b827-557766551111"
}

400 Bad Request (prázdné body):

{
  "code": "VALIDATION",
  "message": "body must not be blank"
}

404 Not Found (issue neexistuje nebo patří jinému userovi — non-admin):

{
  "code": "NOT_FOUND",
  "message": "Issue not found"
}

401 Unauthorized:

{
  "code": "UNAUTHORIZED",
  "message": "Missing or invalid authentication token"
}

Backend

Validace

author_agent mapping

Test Cases

Frontend (Phase 2 — #82)

Comment box je součástí PlatformIssueDetailScreen.vue (viz UC-09004 FE sekce). Níže jsou specifika samotného input prvku.

Comment box — UX detail

Typ vstupu: Prostý <textarea> (plain text s Markdown syntaxí). Žádný WYSIWYG editor ani toolbar — uživatel píše Markdown ručně. Důvod: konzistentní s Marou, která posílá Markdown; admin i user jsou technicky zdatní.

Formát komentáře: Markdown. Při zobrazení v timeline renderovat (shodně s description na issue detailu).

Limity:

Submit flow:

1. Uživatel vyplní textarea → Submit button se stane enabled.
2. Klik na Submit → POST /api/issues/{id}/comments.
3. Loading state: Submit button disabled + spinner, textarea disabled.
4. 201 Created → nový komentář se přidá na konec timeline (optimistic update nebo refetch) + textarea se vymaže.
5. Chyba → inline error pod textarea (t('issues.comments.submitError') = “Failed to post comment — try again”). Textarea zůstane vyplněná.

Textarea vlastnosti:

• rows="4" (výchozí výška).
• resize: vertical (uživatel může zvětšit).
• Placeholder: t('issues.comments.placeholder').
• aria-label: t('issues.comments.placeholder').

Submit tlačítko:

• Label: t('issues.comments.submit') = “Comment”.
• Disabled pokud: textarea prázdná NEBO počet znaků > 10 000 NEBO probíhá request.
• Pozice: vpravo pod textarea (align-end).

Role-based rozdíl: Žádný — comment box je identický pro ADMIN i USER. Rozdíl je pouze v author_agent claim, který BE nastaví automaticky z JWT. FE neposílá author_agent v requestu.

i18n klíče (přidat do issues sekce):

issues.comments.submitError   = "Failed to post comment — try again" / "Nepodařilo se odeslat komentář — zkus znovu"

(Ostatní klíče pro comment box jsou definovány v UC-09004 FE sekci.)

References

• UC-09001 Report Platform Issue — auto-komentář při dedup hitu
• UC-09002 Search Issues — search predchází comment při dedup flow
• UC-09004 Admin Triage Issue — admin komentuje při triage; resolution_note je odlišný field (na issue, ne v comments tabulce)