51 lines
5.8 KiB
Markdown
51 lines
5.8 KiB
Markdown
## Why
|
||
|
||
Зеркало хаба хранит только текущее состояние задачи: при каждом обновлении строка `issue` перезаписывается, прежние
|
||
значения теряются. Владелец хочет быстро видеть, **что произошло с задачами за последние часы или за сегодня** — что
|
||
закрылось, у чего поменялось описание, где появился комментарий, у чего сдвинулись сроки, — и **как менялась конкретная
|
||
задача**.
|
||
|
||
Решения владельца 22.10.2026 (brainstorming, jira-hub#70, jira-agent#39):
|
||
- **источник — журнал изменений Jira (changelog)**, который тянет агент: точное время и автор каждого изменения, а не
|
||
разница снимков хаба;
|
||
- **события ленты**: смена статуса (в том числе закрытие), правка описания, новый комментарий, изменение сроков;
|
||
- **регулярно — без отдельного «слепого» запроса**: агент из уже выгруженных задач отбирает изменившиеся с прошлого
|
||
раза (по `updated`) и только по ним тянет журнал;
|
||
- **стартовая загрузка — только незакрытые задачи текущего спринта**, не всё зеркало;
|
||
- **где смотреть**: MCP (спросить Claude «что изменилось за 2 часа») и, позже, веб-приложение — страница «Лента» и
|
||
история в карточке задачи;
|
||
- **веб-приложение в этом change не трогаем**: идёт редизайн (#69), веб-часть — отдельной задачей после него.
|
||
|
||
## What Changes
|
||
|
||
- **Журнал изменений в хабе.** Новая таблица `issue_change` (схема v5): одна строка — одно изменённое поле в одной
|
||
записи журнала Jira (id записи, порядковый номер поля в ней, ключ задачи, время, автор, поле, было/стало). Повторно
|
||
присланные записи отбрасываются по id, поэтому перекрытие окон безопасно. Время комментариев приводится к UTC
|
||
(`issue_comment.created_at`), чтобы ленту можно было резать по времени.
|
||
- **Отметка «с какого момента».** Хаб при выдаче `refresh` дописывает параметр `history`: `{since}` — время начала
|
||
последнего полного прогона, по которому журнал принят, минус запас; если такого прогона нет — `{jql}` стартовой
|
||
загрузки (незакрытые задачи открытых спринтов из базовой JQL).
|
||
- **Агент v13** (отдельный PR в jira-agent): после выгрузки состояния отбирает задачи с `updated >= since` и одним
|
||
`search` с `expand=changelog` на 100 ключей получает их журнал; в режиме стартовой загрузки — отдельный `search` по
|
||
`history.jql`. Записи отправляет хабу новым маршрутом `POST /agent/history`; итог — в результате `refresh`.
|
||
- **Лента в API.** `GET /changes` — события за период (журнал + новые комментарии), с разрезом по проекту, фильтром по
|
||
видам событий и по задаче.
|
||
- **MCP.** Новый инструмент `changes` (лента за период: по умолчанию — с начала сегодняшнего дня; `hours`, `since`,
|
||
`until`, `kinds`, `key`); `issue` показывает 5 последних изменений задачи.
|
||
|
||
## Non-Goals
|
||
|
||
- Веб-приложение: страница «Лента», история в карточке задачи — отдельной задачей после редизайна (#69).
|
||
- Событие «задача создана» в ленте — в журнале Jira его нет; можно добавить позже по `issue.created`.
|
||
- Правка и удаление комментария — их нет в журнале Jira; в ленте только новые комментарии, пока они есть в Jira.
|
||
- История до стартовой загрузки по задачам вне открытых спринтов и по закрытым задачам.
|
||
- Срок хранения, чистка журнала — пока храним всё.
|
||
- Отдельный запрос журнала без `refresh` или своя периодичность — журнал приходит только вместе с обновлением зеркала.
|
||
|
||
## Anti-Goals
|
||
|
||
- Лента молча теряет изменения: например, агент не смог дочитать журнал, а отметка «с какого момента» всё равно
|
||
сдвинулась вперёд.
|
||
- Каждое автообновление тянет журнал всех задач зеркала и заметно замедляет обновление или упирается в лимиты Jira.
|
||
- Старый агент (≤ v12) или сбой чтения журнала ломает обновление зеркала.
|