61 lines
7.5 KiB
Markdown
61 lines
7.5 KiB
Markdown
## Why
|
||
|
||
Карточка задачи (`/app/issues/{key}`, change `web-app` #21) — отдельная страница: уход со списка или доски теряет
|
||
контекст, а сама карточка плохо читается — поля одного веса, связи без темы и статуса связанной задачи, входящие связи
|
||
записаны «X → тип → эта задача», техническая таблица команд на виду, форма заметок занимает пол-экрана. Комментариев
|
||
задачи из Jira в карточке нет: хаб их не хранит, агент их не читает.
|
||
|
||
Решения владельца 15.10.2026 (brainstorming, jira-hub#37):
|
||
- карточку открывают, чтобы быстро понять состояние задачи (статус, кто, срок, что осталось) и разобраться в связях
|
||
(что держит задачу, что ждёт её); в карточке нужны комментарии задачи из Jira с возможностью их скрыть;
|
||
- карточка открывается модальным окном поверх того места, откуда её открыли (список «Задачи» или доска), у окна свой
|
||
адрес `/app/issues/{key}`; переходы по связям — внутри окна, «назад» браузера возвращает к прежней карточке;
|
||
- раскладка карточки — по разделу 1 дизайна (шапка состояния, связи по смыслу, заметки в режиме чтения, комментарии,
|
||
второстепенное внизу); визуальные макеты не нужны, раскладку предлагает агент;
|
||
- комментарии — два change по репозиториям, сначала агент: jira-agent v10 (aep/jira-agent#27) передаёт комментарии в
|
||
состоянии задачи, jira-hub (#37) хранит, отдаёт и показывает их. Требования к агенту по заведённому порядку живут в
|
||
этом change (`specs/agent`), решения агентской части — в `jira-agent/openspec/changes/agent-v10-comments/design.md`.
|
||
|
||
## What Changes
|
||
|
||
- **Агент v10** (`AGENT_VERSION = 10`): `refresh` запрашивает в том же `search` поле `comment`; по каждой задаче
|
||
передаёт `comments: [{id, author, created, updated, body}]` (автор — отображаемое имя, иначе логин; текст как есть);
|
||
если Jira отдала не все комментарии задачи — дочитывание через `GET /issue/{key}/comment`. Выкатка самообновлением.
|
||
- **Хаб, данные**: таблица `issue_comment`, схема базы v2 → v3 (копия базы перед миграцией — как сейчас). Присланные
|
||
комментарии задачи заменяют её прежние; задача без поля `comments` (агент до v10) свои комментарии не теряет.
|
||
Неверная форма комментария — 422 на всю пачку `POST /agent/state`.
|
||
- **Хаб, API**: `GET /issues/{key}` дополнительно отдаёт `comments` (новые сверху), у связей — `summary` и `status`
|
||
связанной задачи (`null`, если её нет в зеркале), `epic_summary`. Прежние поля не меняются.
|
||
- **MCP**: инструмент `issue` показывает 5 последних комментариев и «ещё N».
|
||
- **Веб-приложение**:
|
||
- карточка задачи — модальное окно (`<dialog>`) поверх списка «Задачи» или доски; адрес `/app/issues/{key}`; прямой
|
||
адрес открывает окно поверх списка задач без фильтров; закрытие (✕, Esc, щелчок по фону) возвращает туда, откуда
|
||
открыли, и «назад» после закрытия карточку не открывает;
|
||
- новая раскладка: шапка (ключ, статус Jira, статус по факту, тема, исполнитель · срок · спринт · эпик по имени,
|
||
«Открыть в Jira», ✕); связи по группам «Зависит от», «Блокирует», «Связана с», «Прочие» с темой и статусом;
|
||
описание свёрнуто до 8 строк; комментарии со «Скрыть/Показать», выбор запоминается в браузере; заметки в режиме
|
||
чтения с «Править»; «Прочие поля»; «Команды моста» свёрнуты;
|
||
- после сохранения заметки доска под окном показывает новые «вид работы» и «статус по факту».
|
||
- Спеки: `agent` — MODIFIED «Чтение состояния»; `data-model` — MODIFIED «Схема базы хаба», «Зеркало задачи»; `hub-api` —
|
||
MODIFIED «Маршруты агента», «Маршруты интерфейсов»; `mcp` — MODIFIED «Инструменты»; `web-app` — MODIFIED «Оболочка и
|
||
адреса», «Доска связей», «Список задач», «Карточка задачи», «Служебные заметки».
|
||
|
||
## Non-Goals
|
||
|
||
- Запись в Jira из карточки (правка полей, статуса, добавление комментариев) — следующий change `viewer-edit`.
|
||
- Разбор разметки Jira (wiki) в описании и комментариях: текст показывается как есть, с переносами строк.
|
||
- Комментарии в списке задач, на доске и в `GET /board`.
|
||
- Изменения поведения доски, кроме открытия карточки окном и обновления заметки под окном.
|
||
- Хранение истории правок комментариев: в зеркале — последнее состояние из Jira.
|
||
|
||
## Impact
|
||
|
||
- jira-agent: `src/agent.py` (`STATE_FIELDS`, `to_state`, дочитывание комментариев), тесты `tests/test_refresh.py`,
|
||
фейк `tests/fake_jira.py`; `AGENT_VERSION = 10`; публикация `jira-hub agent publish` после merge.
|
||
- jira-hub: `db.py` (v3, `issue_comment`), `mirror.py` (`apply_state`, `get_issue`), `api.py` (`h_agent_state`
|
||
валидация), `mcp_server.py` (`issue`), тесты; `web/src/routes.tsx`, `shell/Layout.tsx`, `issues/*` (окно, раскладка,
|
||
заметки), `board/components/Card.tsx` (ссылка «ⓘ»), `api/types.ts`, `api/queries.ts`, e2e; фикстура тестового хаба
|
||
с описанием, комментариями и командами.
|
||
- Порядок выкатки: агент v10 (любой хаб принимает его состояние — лишнее поле `comments` нынешний хаб пропускает), затем
|
||
хаб; комментарии появляются после первого `refresh` агента v10.
|