feat(page-history): интеграция редизайна окна истории — плотный список + мини-календарь heatmap #568
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: vvzvlad/gitmost#568
Reference in New Issue
Block a user
Delete Branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Проблема / Цель
Есть готовый прототип редизайна окна «Page history» —
NewDesign/PageHistoryModal.tsx(Mantine v7, светлая/тёмная, полноразмерная модалка). Идея: слева — панель навигации (мини-календарь-heatmap + плотный список ревизий: одна ревизия = одна строкаглиф · время · автор · [SAVED]), справа — отрендеренная версия страницы с подсветкой изменений; все контролы (Highlight changes, навигация по диффу N/M, Restore) — в одну строку шапки. Агентские ревизии визуально отличаются квадратным глифом роли + «via <кто запустил>».Нужно натянуть визуал на существующую систему истории (
IPageHistory, реальные запросы, restore, права, diff) с минимумом изменений бэка. Единственное реальное изменение бэка — новый дешёвый агрегат «число ревизий по дням» под heatmap (решение принято человеком, см. «Решённые развилки»). Всё остальное — переиспользование существующего поведения. Всё в одной ишью.Для кого: авторы/редакторы страниц, которые разбирают историю правок (в т.ч. агентских — Корректор/Фактчекер из
agent-roles-catalog).Контекст и исследование
Существующая подсистема (переиспользуем, не переписываем механику):
useMediaQuery; мобайл = history-modal-mobile.tsx. Десктоп-тело: history-modal-body.tsx (слеваHistoryList, справаHistoryView+ плавающая панель Highlight changes + N/M).useInfiniteQueryс пагинацией (догрузка страниц поIntersectionObserver,gcTime:0), фильтр «Only versions» черезhistoryKindMeta(kind).version; выбор ставитactiveHistoryIdAtom+activeHistoryPrevIdAtom = resolvePrevSnapshotId(ПОЛНЫЙ_список, id)(не по отфильтрованному/сгруппированному!).historyKindMeta:manual→Saved(blue,version),agent→Agent version(violet,version),boundary/idle/null→Autosave(gray, не version, opacity .55); провенансAgentAvatarStackприlastUpdatedSource==='agent' && agent.IPageHistory:id, title, content?, createdAt(string), lastUpdatedBy, contributors?[], kind?('manual'|'agent'|'idle'|'boundary'|null), lastUpdatedSource?, lastUpdatedAiChatId?, agent?/launcher?(#300). Два ортогональных сигнала:lastUpdatedSource==='agent'= идентичность автора (в т.ч. у агентского автосейва),kind= интенциональность (version vs autosave).HistoryEditor(content, title, previousContent); дифф считается selected↔предыдущий снапшот. Навигация:highlightChangesAtom,diffCountsAtom,useDiffNavigation(scrollViewportRef)(ref — viewport ПРАВОЙ панели; якоряdata-diff-indexэмититHistoryEditor).handleRestoreгрузит снапшот в живые редакторы (mainEditor/titleEditor.setContent) через confirm-модалку («Any changes not versioned will be lost») и гейт CASLspaceAbility.can(Manage, Page) → canRestore. (@Post('/pages/restore')— это восстановление из корзины, не сюда.)@Post('/history'),@Post('/history/info'),@Post('/history/time'). Последний (page-history.service.tscomputeWorkTime) — per-day рабочее время (#395,activeMs/agentMs), черезfindTimelineByPageId(дешёвая проекция безcontent) +bucketByDay(sessions, tz);tz→RangeError→400. Числа ревизий по дням он НЕ отдаёт.Расхождения прототипа ↔ кода (закрываются адаптером/минимальным бэком):
onRestore: api.restore(rev.id). Реально restore — загрузка в редактор + confirm + CASL (переиспользуем).saved: boolean+ один бейджSAVED. Оставляем именно так: бейдж SAVED только дляmanual; агентские версии маркируются глифом роли (не отдельным бейджем — он бы дублировал глиф), автосейвы приглушены без бейджа.calendar.days[].count= число ревизий за день. В системе такого агрегата нет → добавляем (см. дизайн, часть D).dayGroup/atLabelпредформатированы вызывающим. Считаем на клиенте в браузерном tz.Дизайн
Принцип: механику (запросы, дифф, restore, права, пагинация) переиспользуем; меняем компоновку десктоп-окна и плотность строк; добавляем один дешёвый агрегат под heatmap. Мобайл, work-time/TimeWorkedModal — вне scope.
A. Каркас окна (десктоп)
history-modal-desktop.tsx) с одно-строчной шапкой (заголовок, лейбл выбранной версии, тумблер Highlight changes + N/M-навигация по диффу, кнопка Restore, закрытие) и телом «левая навигация 280px | правый рендер версии». В history-modal.tsx десктоп-ветку переключаем на новый body; мобильную ветку (history-modal-mobile.tsx) не трогаем.HistoryView/HistoryEditor, управляемые существующими атомами (activeHistoryIdAtom/activeHistoryPrevIdAtom). Дифф-навигацию — существующимиhighlightChangesAtom/diffCountsAtom/useDiffNavigation;viewportRefправойScrollAreaпрокинуть вuseDiffNavigation(как сейчас в body).resolvePrevSnapshotId(ПОЛНЫЙ плоский список, id). Группировка по дням — чисто презентационная; вresolvePrevSnapshotIdпо-прежнему передаём плоскийhistoryItems, НЕ сгруппированный/отфильтрованный.B. Плотная строка ревизии (адаптер
IPageHistory → строка)atLabel= время;dayISO(YYYY-MM-DDв браузерном tz) — стабильный ключ строки для группировки и jump-to-day;dayGroupLabel= Today/Yesterday/«Mon 12 Jul» (i18n) — только для показа.lastUpdatedSource==='agent' && item.agent→ квадратный глиф роли (agent.name) + «vialauncher?.name»; иначе круглый аватарlastUpdatedBy. (Плотная строка — один аватар; мульти-контрибьюторный стек в плотном списке опускаем осознанно.)SAVEDприkind==='manual'. Агентские версии — без бейджа (глиф уже отличает). Не-version (autosave/boundary/idle/null) — приглушены (opacityкак сейчас), без бейджа.data-day={dayISO}-якорь; леваяScrollAreaполучаетviewportRef— для скролла из календаря (часть E).historyKindMeta(kind).version, manual+agent).C. Restore
useHistoryRestore:confirmRestore(confirm-модалка) + гейтcanRestore(CASL Manage Page) + загрузка снапшота в редакторы. НаивныйonRestoreпрототипа НЕ используем.!canRestoreили выбран новейший снапшот (historyItems[0]— список грузится newest-first, поэтому индекс 0 — глобально новейший даже при пагинации).D. Серверный агрегат «число ревизий по дням» (единственное изменение бэка)
POST /pages/history/day-counts{ pageId, tz }→[{ dayISO, count }]за всю историю за один запрос (без параметраmonth— это убирает повторный full-scan на каждую смену месяца и валидацию месяца).findTimelineByPageId(безcontent) + новый чистый tz-aware per-day count-баркетер, переиспользующий уже протестированное tz-ядро: экспортироватьzonedDayStart/isoDayизwork-time/bucket-by-day.tsи строить счётчик какcreatedAt → isoDay(zonedDayStart(ms, tz), tz) → tally(единый источник DST/дней сbucketByDay, без копипасты).kind ∈ {manual, agent}) — тогда крашеный день в heatmap всегда имеет видимую цель в списке и совпадает с фильтром «Only versions» (см. критерий 6).validateCanView, как/historyи/history/time). Неверныйtz(RangeErrorизIntl) → 400 (как/history/time).E. Мини-календарь + jump-to-day
MiniCalendarиз прототипа + хукusePageHistoryDayCounts(pageId, tz);tz— единый браузерный (Intl.DateTimeFormat().resolvedOptions().timeZone), тот же, что используется для клиентской группировки по дням (часть B) — иначе счётчики календаря разъедутся с днями списка.countиз агрегата (version-ревизии). Навигация месяцев prev/next/today — чисто клиентская (данные за всю историю уже загружены; режем по месяцу локально).dayISO(не по отображаемому лейблу — он относительный и без года), скроллим кdata-day-якорю в левойScrollArea.fetchNextPage()с корректной границей: список newest-first, поэтому тянем страницы, покаdayISOсамой старой загруженной строки не станет<= targetDayISOилиhasNextPage===false. Не «N страниц». Если день так и не достигнут (исчерпали пагинацию) — no-op + короткий тост, без бесконечного цикла.Policy-константы:
heat()), оставляем.manual+agent).Затрагиваемые файлы (примерно):
history-modal-desktop.tsx(порт каркаса + шапки из прототипа); новая плотнаяRevisionRow+ адаптер (dayISO, глиф, бейдж SAVED);MiniCalendar(порт);work-time-стиль сервис/хукusePageHistoryDayCounts; правкаhistory-modal.tsx(десктоп-ветка). ПереиспользуемHistoryView/HistoryEditor,useDiffNavigation,useHistoryReset,resolvePrevSnapshotId,useHistoryRestore,historyKindMeta, атомы.@Post('/pages/history/day-counts')вpage.controller.ts; методcomputeDayCountsвpage-history.service.ts; новый чистый баркетер + экспортzonedDayStart/isoDayизwork-time/bucket-by-day.ts; юнит-тесты баркетера.NewDesign/PageHistoryModal.tsx(исходник-прототип, в корне жить не должен).Границы scope
Не входит: мобильная модалка (
history-modal-mobile.tsx) — без изменений; редизайн work-time/TimeWorkedModal.tsx— отдельно; серверный history-restore-API (restore остаётся клиентским); мульти-контрибьюторный стек в плотной строке (осознанно опущен). Живое обновление heatmap при поступлении новых ревизий во время открытого окна — не требуется (счётчики тянутся при открытии).Критерии приёмки
Проверяемо на стенде (страница с ручными, агентскими и авто-ревизиями):
lastUpdatedBy.SAVEDтолько уmanual; агентские версии — без бейджа (видны глифом); автосейвы приглушены без бейджа.!canRestore.POST /pages/history/day-counts {pageId, tz}отдаёт[{dayISO,count}]за всю историю; неверныйtz→ 400; неавторизованный просмотр → 403; счётчик дня == числу version-строк этого дня в том же tz.dayISOстарейшей строки), а не фиксированным числом; недостижимый день → no-op + тост, без зацикливания.Отказы и наблюдаемость
day-countsупал (400 неверный tz / 5xx / сеть): heatmap показывает пустую сетку (fail-open, без блокировки списка), список и restore работают. Не роняем окно.tz— явный 400 (RangeErrorизIntl), как у/history/time; невалидный день/пустой месяц — пустые ячейки.Совместимость и миграции
Решённые развилки
SAVED(manual); агентские версии маркируются глифом, отдельный «Agent version»-бейдж не вводим (дублировал бы глиф). Кто решил: человек.useHistoryRestore(confirm+CASL),useDiffNavigation, мобильную модалку не трогаем.lastUpdatedSource==='agent', бейдж поkind(дизайн-решение по итогам разбора — иначе агентский автосейв терял бы агентскую идентичность).Связи
/history/time, work-time-ядро и tz-баркетинг — переиспользуемbucket-by-day), #300 (provenance-стек агента).TimeWorkedModal.tsx(отдельный прототип, отдельная ишью).