sdlc-hub/openspec/changes/archive/2026-10-22-attachment-fetch/proposal.md

Why

Тестировщики прикладывают к ошибкам AURORA файлы: скриншоты, выгрузки в Excel (ОСВ), иногда PDF и JSON. Владелец разбирает ошибки в чате с Claude, и Claude должен сам открыть эти файлы. Сейчас мост файлы из Jira не забирает совсем: зеркало не знает даже, что у задачи есть вложения (агент умеет только загружать файл в Jira — ensure_attachment, change bug-and-attachments).

Решения владельца 22.10.2026 (brainstorming, jira-hub#83, jira-agent#43):

• при синхронизации — только список вложений (имя, размер, автор, дата), сами файлы автоматически не тянутся;
• файл — по запросу: агент скачивает нужное вложение из Jira и отдаёт хабу;
• где: в MCP (Claude получает путь к локальному файлу и открывает его) и в веб-приложении (кнопка «Скачать»);
• из комментария: файлы, на которые ссылается комментарий тестировщика, видны и скачиваются прямо у комментария — в карточке, в MCP issue и comment, а не только в общем списке задачи;
• предел 10 МБ на файл, как у загрузки; крупнее — скачивать в Jira руками;
• превью скриншотов в карточке не делаем: для него файлы пришлось бы качать заранее.

What Changes

• Список вложений в зеркале. Агент v14 в refresh добавляет поле attachment к search и шлёт у каждой задачи attachments (id, имя, размер, тип, автор, дата) без содержимого. Хаб хранит их в новой таблице issue_attachment (схема v6), заменяя список задачи целиком, как комментарии.
• Ссылки из текста. Хаб находит в описании и комментариях вики-ссылки на вложения (!имя!, !имя|…!, [^имя]) и отдаёт у комментария attachment_ids, у задачи — description_attachment_ids.
• Команда fetch_attachment. Хаб ставит её по запросу интерфейса отдельным пакетом без хвостового refresh; агент читает вложение в Jira, скачивает содержимое и отдаёт хабу новым маршрутом POST /agent/files; хаб кладёт файл в хранилище files/ (то же, что для загрузки; уборка через 30 дней) и запоминает в attachment_file.
• API. GET /attachments/{id} (с состоянием none / fetching / ready / failed), POST /attachments/{id}/fetch (одна команда на вложение, сколько бы раз ни просили), GET /attachments/{id}/content (файл с исходным именем). GET /issues/{key} отдаёт вложения и ссылки на них.
• MCP. issue и comment показывают вложения; новый инструмент attachment скачивает файл (ждёт агента до wait_seconds) и отвечает путём к локальной копии с исходным именем в <данные хаба>/downloads/<id>/.
• Веб. В карточке раздел «Вложения (N)», плашки файлов под комментарием, ссылки на вложения в отрендеренном тексте — все скачивают файл одной кнопкой; «Загружается…», пока агент везёт файл.

Non-Goals

• Превью картинок в карточке и показ !картинка! картинкой.
• Скачивание файлов больше 10 МБ — только ссылка на Jira.
• Автоматическая подкачка файлов (заранее, при синхронизации, по подписке).
• Удаление и переименование вложений в Jira из моста.
• Привязка файла к комментарию по автору и времени — только по ссылке в тексте.

Anti-Goals

• Синхронизация стала тяжелее: при refresh агент качает содержимое вложений или делает лишние вызовы Jira на задачу.
• Учётные данные Jira уходят на адрес не из base_url агента (адрес content из ответа Jira).
• Повторные нажатия и параллельные запросы из веба и MCP ставят несколько одинаковых скачиваний.
• Claude получает файл без имени и расширения и не может его открыть.
• Старый агент (≤ v13) или старый хаб ломают синхронизацию.