Delivery Dashboard
Дашборд для анализа задач, синхронизированных из Jira Cloud.
Структура
ai-delivery-copilot/
├── backend/ # Node.js + Express API
│ ├── server.js
│ ├── db.js # Postgres pool + schema creation
│ ├── package.json
│ ├── lib/
│ │ ├── jiraAuth.js # token storage + refresh
│ │ └── problemIssues.js # блокеры/aging-WIP, shared by the Dashboard widget + Задачи filter
│ └── routes/
│ ├── auth.js # GET /api/auth/login, /api/auth/callback (Jira OAuth)
│ ├── jira.js # sync/status/issues/fields/field-mapping/tasks/team-roles/wip-limits
│ ├── teams.js # GET /api/teams, /api/teams/filters
│ ├── sprints.js # GET /api/sprints/report, /api/sprints/filters
│ ├── dashboard.js # GET/POST /api/dashboard/widgets, GET /api/dashboard/attention
│ └── reports.js # GET /api/reports/status, POST /api/reports/summary, POST /api/reports/export
├── frontend/ # React + Vite + Tailwind
│ ├── package.json
│ ├── index.html
│ ├── src/
│ │ ├── main.jsx
│ │ ├── App.jsx
│ │ ├── api.js
│ │ ├── index.css
│ │ ├── useSharedFilters.js
│ │ └── components/
│ │ ├── TopNav.jsx
│ │ ├── Dashboard.jsx
│ │ ├── WidgetDrilldown.jsx
│ │ ├── Tasks.jsx
│ │ ├── Teams.jsx
│ │ ├── Sprints.jsx
│ │ ├── TaskDetailPanel.jsx
│ │ ├── FilterBar.jsx
│ │ ├── MultiSelectFilter.jsx
│ │ ├── StatusBadge.jsx
│ │ ├── Settings.jsx
│ │ ├── TeamRoles.jsx
│ │ ├── WipLimitsModal.jsx
│ │ ├── WidgetMenu.jsx
│ │ ├── WidgetLibraryModal.jsx
│ │ ├── AttentionWidget.jsx
│ │ ├── Reports.jsx
│ │ ├── SyncHistory.jsx
│ │ ├── JiraPanel.jsx
│ │ └── FieldMapping.jsx
│ └── public/
│ └── index.html
└── README.md
Запуск
Backend
cd backend
npm install
npm start
Сервер поднимется на http://localhost:5000.
На macOS порт 5000 может быть занят системным AirPlay Receiver (ControlCenter). Если при старте видите EADDRINUSE, либо отключите AirPlay Receiver в System Settings → General → AirDrop & Handoff, либо запустите backend с другим портом: PORT=5050 npm start (и поменяйте /api proxy в frontend/vite.config.js соответственно).
Frontend
cd frontend
npm install
npm run dev
Приложение поднимется на http://localhost:3000 (запросы к /api/* проксируются на backend).
Примечания
frontend/public/index.html — статический шаблон по требованиям структуры; фактический entry point для Vite — frontend/index.html.
Деплой backend на Vercel
backend/server.js экспортирует app (Express-приложение), а app.listen() вызывается только при локальном запуске (require.main === module) — при импорте Vercel как serverless-функции listen не выполняется.
backend/vercel.json направляет все запросы в server.js через @vercel/node.
Настройки в панели Vercel: Root Directory — backend, Framework Preset — Other.
Интеграция с Jira Cloud (OAuth 2.0)
Как это работает
-
Авторизация — GET /api/auth/login редиректит пользователя на страницу согласия Jira (auth.atlassian.com/authorize), защищено CSRF-параметром state в HttpOnly-куке. GET /api/auth/callback обменивает код на access_token/refresh_token, запрашивает cloud_id сайта через accessible-resources, сохраняет токены в таблице jira_tokens (одна активная запись, при повторном подключении перезаписывается) и редиректит обратно на фронтенд с ?jira=connected (по умолчанию — https://ai-delivery-copilot.vercel.app, переопределяется через FRONTEND_URL). Фронтенд (App.jsx) читает этот параметр при первом рендере, сразу показывает статус «подключено» и сообщение «Jira успешно подключена», затем убирает параметр из URL через history.replaceState и всё равно уточняет статус через GET /api/jira/status.
-
Синхронизация — POST /api/jira/sync берёт актуальный access token (автоматически обновляя его через refresh_token, если истёк), запрашивает issues проекта SCRUM через POST .../rest/api/3/search/jql (актуальный endpoint — старый /rest/api/3/search Atlassian удалила, он отвечает 410 Gone) и для каждой issue делает UPSERT в таблицу issues: если issue_key уже есть — сравнивает поля status, assignee, sprint, priority со старыми значениями и при изменении пишет запись в issue_history, затем обновляет строку; если issue новая — создаёт запись. Существующие записи никогда не удаляются автоматически (is_deleted зарезервировано для будущей логики). last_synced_at обновляется для каждой обработанной issue. Пагинация — курсорная (nextPageToken/isLast), а не startAt/total, как было в старом API; fetchAllIssues в routes/jira.js листает страницы, пока не встретит isLast: true или пустой nextPageToken.
- считаются точно, а не эвристикой: ; — время от первого выхода статуса из категории «To Do» до резолюции, за вычетом любого времени обратно в «Done» (реплей истории статусов, а не разница «первый вход в работу — резолюция»). Считается время после первого выхода из «To Do», независимо от категории — в т.ч. промежуточные статусы вида «Готово к QA», которые в конкретном workflow классифицированы как «To Do» по колонке доски, а не «In Progress»; reopen учитывается честно (обе рабочие растяжки суммируются, Done-разрыв между ними — нет). Оба поля — , пока issue не резолвнута. (сколько раз статус уходил из категории Done обратно) считается независимо от текущего состояния резолюции. Для этого на каждую issue дополнительно запрашивается (курсор / или офсет / — источники по этому эндпоинту расходятся в формате, поэтому в поддерживает оба) плюс один общий запрос за весь sync, чтобы сопоставить исторические статусы из changelog с категорией.
«Зависимости между командами» (раздел «Команды»)
Заменяет прежнюю заглушку «Скоро». Считается в той же computeTeamsReport() (routes/teams.js), что и остальной экран «Команды», из уже имеющейся таблицы issue_links (заведена ранее для «блокеров» в «Спринтах»/«Требует внимания» — отдельной миграции для этой задачи не потребовалось).
- Берутся только связи
is blocked by, где команда заблокированной задачи и команда задачи-блокера различаются; связь, у которой блокирующая задача уже status_category = done, считается неактивной и не учитывается.
- Группировка — по паре (кто ждёт → кого ждёт): «Задач» — число таких связей, «Макс. ожидание» — самый долгий срок среди активных блокеров пары, считается от
created_at блокирующей задачи (то же допущение, что и у остальных «блокерных» расчётов в приложении: issue_links пересобирается заново при каждом sync, отдельного «заблокирован с такого-то момента» не хранится).
- Фильтр «Команда» страницы «Команды» — особый случай: он ограничивает, какие СТРОКИ основной таблицы показывать, но для этого блока применяется как OR к обеим сторонам пары (иначе выбор одной команды прятал бы половину зависимости, где она выступает блокирующей, а не ждущей стороной). Фильтр «Проект» применяется так же — по любой из сторон. Фильтр «Спринт» на этот блок не влияет (как и на
blockersCount в основной таблице).
- Клик по строке — переход в «Задачи» с фильтром Команда = «кто ждёт» + Проблема = «Блокер» (тот же фильтр «Проблема», что и у виджета «Требует внимания»).
Раздел «Отчёты»
Четыре фиксированных шаблона, переключаемых через сайдбар «Шаблоны» (Reports.jsx — просто локальный useState, без сохранения истории: каждый рендерится заново при выборе). Блока «Мои отчёты» (сохранённые версии) нет — отдельная задача на будущее.
GET /api/reports/status считает весь отчёт заново на каждый запрос: период — из общего фильтра «Период» (если он «Всё время», берутся последние 7 дней), Проект/Команда/Тип/Статус/Приоритет — из того же общего набора фильтров, что и Дашборд/Задачи.- «План vs факт по командам» переиспользует ровно ту же агрегацию, что и экран «Команды» —
computeTeamsReport() вынесена из routes/teams.js в отдельную функцию (расширенную типом/статусом/приоритетом фильтрами, которых у самого экрана «Команды» нет) и импортируется в reports.js, чтобы План/Факт SP и health-статус команды не могли разойтись между двумя экранами. Комментарий в таблице — производная от 3-сигнальной health-модели (перегруз/риск/без рисков/недостаточно данных) плюс % багов.
- Резюме для стейкхолдеров генерируется автоматически (закрыто/взято SP, худшая по health команда, самый долгий активный блокер — через
computeProblemIssues(), тот же движок, что у виджета «Требует внимания»), но полностью редактируется вручную в textarea. Правка сохраняется в report_summary_draft, ключ — periodKey (диапазон дат + выбранные проекты), так что у разных периодов/проектов свои черновики и они не перетирают друг друга.
- «Динамика доставки» — сумма
story_points завершённых задач по неделям (8 недель по умолчанию, не настраивается), последняя (текущая, возможно неполная) неделя отрисовывается серым баром вместо синего.
- Экспорт — только CSV (кнопка называется «CSV / XLSX», как в макете, но реального XLSX нет — та же договорённость, что и у экспорта в «Задачах»):
POST /api/reports/export собирает файл из уже отрендеренных на экране данных (резюме + обе таблицы), а не пересчитывает их заново — экспорт не может разойтись с тем, что видит пользователь.
- Кнопки «PDF»/«Ссылка» и блок «Расписание и получатели» (авторассылка) из макета сознательно не реализованы.
«Итоги спринта» (GET /api/reports/sprint-summary, SprintSummaryReport.jsx) — переиспользует computeSprintReport(), вынесенную из routes/sprints.js (тот же рефакторинг-паттерн, что и computeTeamsReport), включая её burndown/forecast/scope-creep математику и новое поле selectedIssues (сырые строки выбранного спринта — нужны только отчёту, сам экран «Спринты» читает лишь агрегаты). Дефолтный спринт для отчёта — последний завершённый, а не активный (в отличие от самого экрана «Спринты», где по умолчанию активный) — это два разных, намеренно разных дефолта. KPI-тренды считаются относительно среднего по предыдущим 2-3 спринтам (та же ±10% граница good/risk, что и везде в приложении). «Scope creep %» — та же метрика (доля СЧЁТА задач, а не SP), что уже показана на экране «Спринты», не отдельная. «Перенесённые задачи» для активного спринта — тот же список «ещё не Done», что и для закрытого, просто с другой подписью («прогноз» вместо «не завершены») — по спринту нет вероятностной модели по каждой задаче, а агрегатный прогноз (forecastPct/lagSp) уже есть в KPI. «Топ-3 самых долгих» — единая метрика duration (cycle_time для done, иначе today−started_at), задачи без обоих — исключены, а не приравнены к нулю.
«Качество и баги» (GET /api/reports/quality, QualityReport.jsx) — период по умолчанию 8 недель (56 дней), если общий фильтр «Период» = «Всё время» (та же схема, что у DEFAULT_PERIOD_DAYS в «Статусе доставки»). «% багов по неделям» бакетируется по created_at (та же логика бакетинга по дате события, что у Throughput/«Динамики доставки» на дашборде, а не «сколько багов было открыто на тот момент»). «Топ задач по количеству багов» — рабочее предположение подтверждено перед реализацией: issue_links хранит связи ЛЮБОГО типа (не только «blocked by» — extractIssueLinks в routes/jira.js сохраняет весь issuelinks без фильтрации), так что баг считается привязанным к задаче через связь любого link_type между Bug и не-Bug; поскольку Jira отражает связь с обеих сторон, пары дедуплицируются через Set до подсчёта.
«Здоровье команд» (сайдбар называет его «Квартальный обзор», как в макете) (GET /api/reports/teams-health, TeamsHealthReport.jsx) — целиком переиспользует computeTeamsReport(): health-статус, сработавшие сигналы (WIP/Cycle Time/Velocity) и peopleLoad берутся оттуда без пересчёта, только сплющиваются в общую таблицу по всем командам. «Тренд Velocity» использует doneSp (сделано, а не взято) из sprintChart по последним закрытым спринтам; тренд = отношение среднего по последним 2 к среднему по предыдущим (до 3), с той же ±10% границей.
Не реализован пункт 3.5 («Изменения с прошлого периода») — явно оговоренный в задаче как «пропусти, если технически сложно, не упрощай». WIP-сигнал health-модели — это всегда живой снимок текущих задач (сколько сейчас indeterminate), у которого нет исторической записи; чтобы посчитать «здоровье на конец прошлого периода», пришлось бы строить параллельный, параметризованный по произвольной дате движок (WIP — реконструкция по issue_status_events, спринты — фильтр по complete_date, cycle time — сдвинутое окно), который рискует незаметно разойтись с живым расчётом в «Командах» — а в этом проекте принципиально ни разу не допускалось, чтобы два экрана считали одно и то же по-разному. Сообщение об этом показано прямо на экране отчёта.
Три новых виджета дашборда + структура страницы в 2 колонки
- «Задачи по командам» (
GET /api/dashboard/teams-summary) — Всего/В работе/Готово/Cycle по каждой команде + бейдж «Тренд». Тренд сравнивает средний cycle time команды за ТЕКУЩИЙ период (Период дашборда, либо 30 дней по умолчанию, если он «Всё время» — та же эвристика, что и у сигнала «Отставание cycle time» в «Командах») с её ЖЕ историческим (всё время) средним: лучше >10% → «хорошо», хуже на 10-30% → «риск», хуже >30% ИЛИ SP взятых в текущем спринте выше среднего за 3 предыдущих закрытых спринта более чем на 10% → «перегруз» (SP-сигнал переиспользует computeTeamsReport() из «Команд», чтобы не считать историю спринтов дважды). Меньше 3 завершённых задач в периоде — бейдж не показывается (прочерк). Первые 4 команды на дашборде, «Показать все →» открывает виджет на весь экран.
- «Throughput по неделям» (
GET /api/dashboard/throughput) — количество задач, перешедших в done-категорию, по календарным неделям (пн-вс, из issue_status_events — последний переход в done, а не resolved_at, на случай reopen+повторного закрытия), последние 7 недель, подписи столбцов — только рабочие дни (пн-пт). Текущая (незавершённая) неделя — серый столбец. Осознанно игнорирует фильтр «Период» дашборда — 7-недельный тренд и, скажем, «последние 7 дней» логически конфликтуют, а обрезка тренда до Периода свела бы виджет к одному-двум столбцам; Проект/Команда/Тип/Статус/Приоритет по-прежнему применяются.
- «Burndown спринта» — переиспользует существующий
GET /api/sprints/report (тот же эндпоинт, что и экран «Спринты») и общий компонент BurndownChart.jsx (вынесен из Sprints.jsx), так что математика гарантированно не может разойтись между экраном и виджетом. Селектор спринта по умолчанию — активный, иначе последний закрытый. Только в этом виджете (не на экране «Спринты», который остался однoспринтовым без изменений) селектор — мультиселект: при выборе 2+ спринтов виджет переключается в режим сравнения (MultiSprintBurndownChart.jsx) — по одному GET-запросу к /api/sprints/report на каждый выбранный спринт (параллельно), без изменений самого эндпоинта. Ось X — собственный относительный день каждого спринта (dayIndex из ответа, уже был относительным), поэтому спринты с разными датами старта сопоставимы. Линия «факт» каждого спринта нормализована к % от его же взятого объёма (actualSp / kpis.takenSp × 100), а не к абсолютным SP — иначе спринт с большим объёмом визуально доминировал бы независимо от того, насколько он «на графике». Идеальная линия в режиме сравнения не показывается: единая прямая 100%→0% была бы некорректна для спринтов разной длительности при общей оси «относительный день», а по одной идеальной линии на каждый спринт — ровно то визуальное нагромождение, от которого просили уйти; выбран более простой вариант без идеальных линий, о чём явно сказано пользователю. При ровно одном выбранном спринте поведение полностью прежнее (одна линия факта + идеал + «отставание N SP»).
UX/UI-консистентность (виджеты, заголовки, фильтры, Настройки)
- Виджеты дашборда одной высоты + внутренний скролл: изначально высота выравнивалась через grid row-stretch (
align-items: stretch по умолчанию) — это уравнивало виджеты только ВНУТРИ одной строки, из-за чего разные строки получались разной высоты. Заменено на единую фиксированную высоту для всех виджетов сразу, независимо от строки — DASHBOARD_WIDGET_HEIGHT_CLASS (h-[320px], подобрана по компактному виджету «Throughput по неделям») в dashboardWidgetLayout.js, применяется одинаково во всех 5 виджет-компонентах через widgetHeightClass(fullScreen). Сетка теперь с items-start, чтобы grid-stretch не накладывался поверх. Каждая карточка — flex flex-col с телом flex-1 min-h-0 overflow-y-auto: сама карточка не может вырасти выше фиксированной высоты, скроллится только содержимое, заголовок и иконки управления всегда остаются на месте. В полноэкранном режиме (fullScreen) фиксированная высота не применяется — модалка и так даёт виджету достаточно места.
- Виджет «Карточки статистики» удалён полностью — из каталога библиотеки, из дефолтного сида (
db.js теперь сеет только by_status/by_team/by_type), и с уже существующих дашбордов через одноразовую миграцию (DELETE FROM dashboard_widgets WHERE widget_type = 'stats_cards', идемпотентна, выполняется при каждом ensureSchema()).
SectionHeader.jsx — общий заголовок раздела (название + «Последняя синхронизация с Jira» + кнопка обычной синхронизации, самодостаточный по состоянию синхронизации через useSyncProgress), применён на Дашборде/Задачах/Команде/Спринтах/Отчётах. «Полная пересинхронизация» убрана из заголовков и перенесена в Настройки → «Подключение Jira».- Единый набор фильтров (
FilterBar.jsx): Проект/Команда/Тип/Статус/Приоритет/Период — теперь одинаковый на Дашборде/Задачах/Команде/Отчётах (экран «Команды» лишился собственного фильтра «Спринт» и получил вместо него полный общий набор — computeTeamsReport() и так уже сам резолвит «последний спринт» команды, отдельный ручной выбор спринта был избыточен). «Проблема» на Задачах переименована в «Проблемы». Спринты (4.3) — исключение, как и раньше: только Спринт + Команда, отдельное несвязанное состояние (плюс убран лишний фильтр «Тип задачи», который туда когда-то добавили).
- Период с произвольным диапазоном (
PeriodFilter.jsx + ): пресеты (7/30/90 дней/всё время) или свои даты. теперь может быть , тогда / («YYYY-MM-DD») задают границы. — общий бэкенд-резолвер, используется одинаково в (задачи), (Команды), (виджеты «Требует внимания»/«Задачи по командам») и (все отчёты) — так что «Период» не может означать разное в разных местах.
Настраиваемые пороги метрик («Метрики и SLA»)
Каждое число, которое раньше было захардкожено где-то в бэкенде (порог "зависшей" задачи, множители 3-сигнальной health-модели, границы загрузки людей, порог "зависла на ревью"), теперь хранится в таблице metric_thresholds (key TEXT PRIMARY KEY, value NUMERIC) и правится из Настройки → «Метрики и SLA» — MetricThresholdsSettings.jsx, без отдельной кнопки «Сохранить» (каждое поле сохраняется само, с debounce 500мс, как остальные настройки в проекте).
- backend/lib/metricThresholds.js — единственное место с полным списком из 9 ключей, их значениями по умолчанию и русскими label/description для UI.
getThresholds() возвращает {key: number}, подставляя дефолт для любого ключа, которого почему-то нет в таблице (не блокирует остальную логику отсутствующей строкой); setThreshold()/resetThresholds() — точечное изменение и полный сброс к дефолтам.
db.js сеет все 9 строк дефолтами при первом запуске (ON CONFLICT DO NOTHING — на существующей инсталляции ничего не меняет, только добавляет отсутствующее); поведение приложения после обновления не меняется, пока пользователь сам не поменяет значение в UI.- Кто читает эти пороги:
lib/problemIssues.js (aging_wip_ratio_threshold — тот же движок, что у виджета «Требует внимания» и фильтра «Проблема» на Задачах), routes/teams.js (все три health-сигнала + их пороги для "риск"/"перегруз" + workload_normal_max/workload_at_limit_max для «Загрузки людей» — используется и экраном «Команды», и Отчётами, которые переиспользуют computeTeamsReport()), routes/sprints.js (review_stuck_days_threshold для риска «висит на ревью»). Все четыре места вызывают getThresholds() один раз в начале своей функции и передают дальше как обычные переменные — ни одного из этих чисел в коде больше не осталось захардкоженным.
health_risk_signal_count/health_overload_signal_count: раньше это была жёстко зашитая лесенка 0 сигналов → норма, 1 → риск, 2+ → перегруз; теперь health = triggeredCount >= overloadCount ? 'overload' : triggeredCount >= riskCount ? 'risk' : 'normal' — общий случай, корректный при любых значениях overloadCount >= riskCount >= 1 (порядок дефолтов сохраняет прежнее поведение один-в-один).
Переменные окружения (backend)
| Переменная | Назначение |
|---|
DATABASE_URL | строка подключения к Postgres (например, Neon) — уже подключена |
JIRA_CLIENT_ID | Client ID OAuth 2.0 (3LO) приложения в Atlassian Developer Console |
JIRA_CLIENT_SECRET | Client Secret того же приложения |
JIRA_CALLBACK_URL | URL обратного вызова, должен точно совпадать со значением в настройках приложения, например https://ai-delivery-copilot-backend.vercel.app/api/auth/callback |
FRONTEND_URL (опционально) | куда /api/auth/callback редиректит после успешной авторизации (добавляется ?jira=connected); по умолчанию https://ai-delivery-copilot.vercel.app — задайте, если фронтенд развёрнут на другом домене или для локальной разработки |
В приложении Jira нужно включить OAuth 2.0 (3LO) и выдать API-scopes read:jira-work, read:jira-user, offline_access (последний обязателен для получения refresh_token).
Ограничения текущей реализации
- Sprint/Team/Story Points зависят от того, настроен ли маппинг через UI «Настройки полей» — без него эти поля синкаются как
null (Team — как labels). Значения из Jira извлекаются универсальным хелпером extractFieldValue в routes/jira.js, который умеет доставать имя/value из объекта, брать последний элемент массива (актуально для Sprint — Jira отдаёт историю всех спринтов issue) или число.
- started_at — по-прежнему эвристика («первый раз статус стал не To Do»), не из changelog; используется только для отображения, не для расчёта cycle time (тот теперь считается по полной истории статусов — см. выше).
- Формат ответа
GET /rest/api/3/issue/{key}/changelog — точную структуру (курсорная или офсетная пагинация, ключ values или histories) не удалось верифицировать против реальной Jira: официальная документация Atlassian отдаёт JS-рендерящуюся SPA, не читаемую через обычный fetch, а сторонние источники (форумы, блоги) расходятся между собой. fetchChangelog написан защитно — поддерживает оба варианта — но стоит перепроверить на первом реальном sync с продовым Jira-сайтом.
- Категоризация статусов (backend и
StatusBadge.jsx) сравнивается по statusCategory.key (new/indeterminate/done) — единственное локале-независимое значение; .name локализуется под пользователя так же, как и имя конкретного статуса (обнаружено и исправлено на реальном русскоязычном сайте — было первопричиной бага с cycle_time = 0).
- Если после этого фикса уже засинканные issues всё ещё показывают старое значение —
updated в Jira не изменился с прошлого sync, и оптимизация «не трогать changelog, если ничего не менялось» отдаёт закешированное значение из БД. Пересинкуйте с POST /api/jira/sync?force=1, чтобы пересчитать все issues независимо от updated.
- Схема БД создаётся автоматически при первом обращении к любому Jira-эндпоинту (
CREATE TABLE IF NOT EXISTS / ALTER TABLE ... ADD COLUMN IF NOT EXISTS в db.js) — отдельного шага миграции не требуется.
- Маппинг полей общий на всё приложение (по
cloud_id, без пользовательских аккаунтов) — это согласуется с тем, что и Jira-подключение в текущей реализации одно на всё приложение (одна строка в ).
