team-planner/ROADMAP.md

# План разработки Team Planner

> **Это основной источник истины для всех планов по проекту.**
> Обновляй этот файл при изменении планов или завершении задач.

---

## Обзор фаз

| Фаза | Название | Статус | Описание |
|------|----------|--------|----------|
| 0 | Инициализация | ✅ Завершена | Настройка проектов, инфраструктура |
| 1 | Базовый функционал | ✅ Завершена | CRUD идей, таблица, редактирование |
| 1.5 | Авторизация | ✅ Завершена | Keycloak, JWT, защита API |
| 2 | Расширенный функционал | ✅ Завершена | Drag&Drop, цвета, комментарии, команда |
| 3 | AI-интеграция | ✅ Завершена | Оценка времени, рекомендации |
| 3.1 | Генерация мини-ТЗ | ✅ Завершена | Генерация, редактирование, история ТЗ |
| 4 | Права доступа | 📋 Планируется | Гранулярные права, панель админа |
| 5 | Аудит и история | 📋 Планируется | Логирование действий, восстановление |
| 6 | Real-time и WebSocket | 📋 Планируется | Многопользовательская работа |
| 7 | Темная тема | 📋 Планируется | Переключение светлая/тёмная |
| 8 | Экспорт | 📋 Планируется | Экспорт идеи в DOCX |

---

## Фаза 0: Инициализация ✅

### Backend
- [x] Создать NestJS проект (`nest new backend`)
- [x] Настроить TypeORM + PostgreSQL
- [x] Создать docker-compose для PostgreSQL
- [x] Настроить базовую структуру модулей
- [x] Добавить глобальную валидацию (class-validator)
- [x] Настроить CORS

### Frontend
- [x] Создать React проект (Vite + TypeScript)
- [x] Установить и настроить MUI
- [x] Установить Zustand
- [x] Установить TanStack Table
- [x] Установить dnd-kit
- [x] Настроить Axios + React Query
- [x] Создать базовую структуру папок

### Инфраструктура
- [x] Создать общий docker-compose
- [ ] Настроить ESLint + Prettier для обоих проектов

---

## Фаза 1: Базовый функционал ✅

### Backend — Модуль Ideas
- [x] Создать сущность Idea (entity)
- [x] Создать DTO (CreateIdeaDto, UpdateIdeaDto, QueryIdeasDto)
- [x] Реализовать IdeasService
- [x] Реализовать IdeasController
  - [x] GET /api/ideas (с пагинацией, фильтрами, сортировкой)
  - [x] POST /api/ideas
  - [x] PATCH /api/ideas/:id
  - [x] DELETE /api/ideas/:id
- [x] Добавить валидацию
- [x] E2E тесты (Playwright)

### Frontend — Таблица идей
- [x] Создать типы (types/idea.ts)
- [x] Создать API-сервис (services/ideas.ts)
- [x] Создать Zustand store (store/ideas.ts)
- [x] Создать компонент IdeasTable
  - [x] Отображение колонок
  - [x] Пагинация
  - [x] Сортировка (клик по заголовку)
- [x] Создать компоненты фильтров
  - [x] Фильтр по статусу
  - [x] Фильтр по приоритету
  - [x] Фильтр по модулю
  - [x] Текстовый поиск
- [x] Inline-редактирование ячеек
  - [x] Double-click для редактирования
  - [x] Автосохранение при blur/Enter
  - [x] Оптимистичные обновления
- [x] Создать модалку создания идеи
- [x] Добавить skeleton loader
- [x] Добавить empty state
- [x] Удаление идей
- [x] Локализация интерфейса на русский язык

---

## Фаза 1.5: Авторизация ✅

> **Keycloak интеграция для защиты приложения**

### Настройка Keycloak (auth.vigdorov.ru)
- [x] Создать realm `team-planner`
- [x] Создать client `team-planner-frontend` (public, PKCE)
- [x] Настроить Valid Redirect URIs
- [x] Создать тестового пользователя

### Backend — Auth модуль
- [x] Установить passport, passport-jwt, jwks-rsa
- [x] Создать JwtStrategy (валидация через JWKS)
- [x] Создать JwtAuthGuard (глобальный guard)
- [x] Создать @Public() декоратор
- [x] Добавить env переменные (KEYCLOAK_REALM_URL)
- [x] Защитить все endpoints (кроме /health)

### Frontend — AuthProvider
- [x] Установить keycloak-js
- [x] Создать keycloak.ts сервис
- [x] Создать AuthProvider компонент
  - [x] onLoad: 'login-required'
  - [x] PKCE (S256)
  - [x] Автообновление токена
- [x] Добавить interceptors в api.ts
  - [x] Authorization header
  - [x] Обработка 401
- [x] Обернуть App в AuthProvider

---

## Фаза 2: Расширенный функционал ✅

### Backend — Дополнения
- [x] PATCH /api/ideas/reorder (изменение порядка)
- [x] Модуль Comments
  - [x] Сущность Comment
  - [x] GET /api/ideas/:id/comments
  - [x] POST /api/ideas/:id/comments
  - [x] DELETE /api/comments/:id
- [x] Модуль Team
  - [x] Сущность TeamMember
  - [x] CRUD endpoints
  - [x] GET /api/team/summary

### Frontend — Drag & Drop ✅
- [x] Интегрировать dnd-kit в таблицу
- [x] Drag handle в первой колонке
- [x] Визуальная индикация при перетаскивании (DragOverlay)
- [x] Сохранение порядка на сервер (оптимистичные обновления)
- [x] Сортировка по order по умолчанию

### Frontend — Цветовая маркировка ✅
- [x] Добавить поле color в таблицу
- [x] Цветовой фон строки
- [x] Picker для выбора цвета
- [x] Фильтр по цвету

### Frontend — Комментарии ✅
- [x] Раскрывающаяся панель под строкой
- [x] Список комментариев
- [x] Форма добавления комментария
- [x] Удаление комментариев

### Frontend — Управление командой ✅
- [x] Страница /team (табы навигации)
- [x] Сводка по ролям
- [x] Таблица участников
- [x] Модалка добавления/редактирования
- [x] Матрица производительности (время на задачи по сложности)

### E2E тестирование ✅
- [x] Playwright тесты для Фазы 1 (17 тестов)
- [x] Playwright тесты для Фазы 2 (37 тестов)
- [x] data-testid во всех компонентах
- [x] Гайд E2E_TESTING.md

---

## Фаза 3: AI-интеграция ✅

### Backend — Модуль AI
- [x] Интегрировать ai-proxy service
- [x] POST /api/ai/estimate
  - [x] Получить идею и состав команды
  - [x] Сформировать промпт
  - [x] Отправить запрос в AI
  - [x] Распарсить ответ
  - [x] Сохранить оценку
- [ ] Rate limiting для AI-запросов (опционально)

### Frontend — AI-оценка
- [x] Кнопка "Оценить AI" в строке/детали идеи
- [x] Модалка с результатом оценки
  - [x] Общее время
  - [x] Сложность
  - [x] Разбивка по ролям
  - [x] Рекомендации
- [x] Отображение оценки в таблице
- [x] Loading state для AI-запросов

---

## Фаза 3.1: Генерация мини-ТЗ ✅

> **Генерация технического задания с помощью AI + история версий**

### Backend — Расширение модуля AI
- [x] Добавить поля в Idea entity (specification, specificationGeneratedAt)
- [x] Миграция для новых полей
- [x] POST /api/ai/generate-specification
  - [x] Получить идею
  - [x] Сформировать промпт для генерации ТЗ
  - [x] Отправить запрос в AI
  - [x] Сохранить результат
- [x] Обновить POST /api/ai/estimate — учитывать ТЗ в промпте
- [x] Добавить specification в UpdateIdeaDto

### Backend — История ТЗ
- [x] SpecificationHistory entity
- [x] Миграция для specification_history таблицы
- [x] GET /api/ai/specification-history/:ideaId
- [x] DELETE /api/ai/specification-history/:historyId
- [x] POST /api/ai/specification-history/:historyId/restore
- [x] Автосохранение старого ТЗ в историю при перегенерации

### Backend — Комментарии в AI-промптах
- [x] Включить комментарии к идее в промпт генерации ТЗ
- [x] Включить комментарии к идее в промпт оценки трудозатрат

### Frontend — Модалка ТЗ
- [x] Новый компонент SpecificationModal
  - [x] Режим генерации (loading → результат)
  - [x] Режим просмотра
  - [x] Режим редактирования
  - [x] Markdown-рендеринг (react-markdown)
- [x] Кнопка ТЗ в колонке actions
  - [x] Серая — ТЗ нет
  - [x] Синяя — ТЗ есть
  - [x] Spinner — генерация
- [x] Хук useGenerateSpecification
- [x] API метод generateSpecification

### Frontend — История ТЗ
- [x] Табы "Текущее ТЗ" / "История" (при наличии истории)
- [x] Список исторических версий с датами
- [x] Просмотр исторической версии
- [x] Восстановление версии из истории
- [x] Удаление версии из истории
- [x] Хуки useSpecificationHistory, useDeleteSpecificationHistoryItem, useRestoreSpecificationFromHistory

### E2E тестирование
- [x] Генерация ТЗ для идеи
- [x] Просмотр существующего ТЗ
- [x] Редактирование и сохранение ТЗ
- [x] data-testid для новых компонентов

---

## Фаза 4: Права доступа 📋

> **Гранулярная система прав доступа и панель администратора**

### Backend — Модуль Permissions
- [ ] User entity (userId, email, name, lastLogin)
- [ ] UserPermissions entity (связь с User, все права как boolean поля)
- [ ] Миграции для users и user_permissions
- [ ] PermissionsService (getMyPermissions, getUsersWithPermissions, updateUserPermissions)
- [ ] PermissionsController
  - [ ] GET /api/permissions/me
  - [ ] GET /api/permissions/users (admin only)
  - [ ] PATCH /api/permissions/:userId (admin only)
- [ ] PermissionsGuard (проверка прав на endpoints)
- [ ] @RequirePermission() декоратор
- [ ] Env: ADMIN_EMAIL из K8s Secret
- [ ] Middleware: создание User при первом входе (только view_ideas)

### Backend — Защита существующих endpoints
- [ ] IdeasController — проверка create_ideas, edit_own/any_ideas, delete_own/any_ideas
- [ ] CommentsController — проверка add_comments, delete_own/any_comments
- [ ] AiController — проверка request_ai_estimate, request_ai_specification
- [ ] TeamController — проверка manage_team, manage_roles

### Frontend — Панель администратора
- [ ] AdminPage компонент
- [ ] PermissionsTable — таблица пользователей с чекбоксами прав
- [ ] usePermissions хуки (useMyPermissions, useUsersPermissions, useUpdatePermissions)
- [ ] Скрытие/отключение кнопок на основе прав
- [ ] Роутинг: /admin (только для админа)

### Backend — Автор идеи
- [ ] Добавить поле authorId, authorName в Idea entity
- [ ] Миграция для новых полей
- [ ] Автозаполнение при создании идеи
- [ ] Запрет изменения автора в UpdateIdeaDto

### Frontend — Отображение автора
- [ ] Колонка "Автор" в таблице идей
- [ ] Отображение автора в деталях идеи

### E2E тестирование
- [ ] Тесты прав доступа
- [ ] Тесты панели администратора
- [ ] Тесты автора идеи

---

## Фаза 5: Аудит и история 📋

> **Логирование всех действий с возможностью восстановления**

### Backend — Модуль Audit
- [ ] AuditLog entity (userId, userName, action, entityType, entityId, oldValue, newValue, timestamp)
- [ ] Миграция для audit_log таблицы
- [ ] AuditService
  - [ ] log(action, entityType, entityId, oldValue, newValue)
  - [ ] getAuditLog(filters, pagination)
  - [ ] restore(auditId)
  - [ ] cleanup(olderThanDays)
- [ ] AuditController
  - [ ] GET /api/audit
  - [ ] POST /api/audit/:id/restore
  - [ ] GET /api/audit/settings
  - [ ] PATCH /api/audit/settings
- [ ] Интеграция AuditService во все сервисы (Ideas, Comments, Team, AI)
- [ ] Cron job для очистки старых записей (@nestjs/schedule)
- [ ] Env: AUDIT_RETENTION_DAYS

### Frontend — Страница истории
- [ ] AuditPage компонент
- [ ] AuditLogTable с фильтрами
- [ ] AuditDetailModal (просмотр diff)
- [ ] Кнопка "Восстановить" для удалённых сущностей
- [ ] useAudit хуки

### Frontend — Настройки аудита (в админ-панели)
- [ ] Поле "Срок хранения истории" в AdminPage
- [ ] useAuditSettings хук

### E2E тестирование
- [ ] Тесты просмотра истории
- [ ] Тесты восстановления
- [ ] Тесты настроек аудита

---

## Фаза 6: Real-time и WebSocket 📋

> **Многопользовательская работа с real-time обновлениями**

### Backend — WebSocket Gateway
- [ ] Установить @nestjs/websockets, socket.io
- [ ] EventsGateway (handleConnection, handleDisconnect)
- [ ] JWT валидация в WebSocket handshake
- [ ] События: idea:created, idea:updated, idea:deleted, ideas:reordered
- [ ] События: comment:created, comment:deleted
- [ ] События: specification:generated, estimate:generated
- [ ] События присутствия: users:online, user:joined, user:left
- [ ] События редактирования: idea:editing, idea:stopEditing
- [ ] Интеграция emit во все сервисы

### Frontend — WebSocket Provider
- [ ] WebSocketProvider компонент (socket.io-client)
- [ ] useWebSocket хук
- [ ] Автоматическая синхронизация React Query при получении событий
- [ ] Reconnect логика

### Frontend — Индикаторы
- [ ] OnlineUsers компонент (список онлайн пользователей)
- [ ] EditingIndicator (кто редактирует идею)
- [ ] Визуальная подсветка изменённых строк

### Frontend — Конкурентное редактирование
- [ ] Предупреждение при попытке редактировать занятую идею
- [ ] Optimistic locking (проверка version/updatedAt)
- [ ] Разрешение конфликтов

### E2E тестирование
- [ ] Тесты real-time обновлений (2 браузера)
- [ ] Тесты присутствия
- [ ] Тесты конкурентного редактирования

---

## Фаза 7: Темная тема 📋

> **Поддержка светлой и тёмной темы интерфейса**

### Frontend — Theme Provider
- [ ] ThemeStore (Zustand) — текущая тема, автоопределение
- [ ] ThemeProvider (MUI createTheme с dark/light mode)
- [ ] Сохранение выбора в localStorage
- [ ] Автоопределение системной темы (prefers-color-scheme)

### Frontend — Цветовые схемы
- [ ] Палитра для тёмной темы (см. ARCHITECTURE.md 5.1)
- [ ] Адаптация цветов статусов и приоритетов
- [ ] Адаптация цветов маркировки строк
- [ ] Адаптация всех компонентов

### Frontend — UI
- [ ] ThemeToggle компонент в header
- [ ] Иконки ☀️/🌙 для переключения

### E2E тестирование
- [ ] Тест переключения темы
- [ ] Визуальный тест тёмной темы

---

## Фаза 8: Экспорт 📋

> **Экспорт идеи в документ DOCX**

### Backend — Модуль Export
- [ ] Установить docx библиотеку
- [ ] ExportService
  - [ ] generateIdeaDocx(ideaId) — генерация DOCX
  - [ ] Включение: название, описание, статус, приоритет, модуль
  - [ ] Включение: целевая аудитория, боль, роль AI, способ проверки
  - [ ] Включение: AI-оценка (если есть)
  - [ ] Включение: ТЗ в markdown → форматированный текст (если есть)
  - [ ] Включение: комментарии (автор, дата, текст)
- [ ] ExportController
  - [ ] GET /api/export/idea/:id

### Frontend — Кнопка экспорта
- [ ] Кнопка экспорта в строке таблицы (⬇️ иконка)
- [ ] useExportIdea хук
- [ ] Скачивание файла через blob

### E2E тестирование
- [ ] Тест экспорта идеи
- [ ] Проверка содержимого DOCX

---

## Backlog (после фаз 4-8)

- [ ] Виртуализация списка (1000+ идей)
- [ ] Keyboard shortcuts
- [ ] Сохранение пресетов фильтров
- [ ] Уведомления (email/push при упоминании)
- [ ] Интеграция с Jira/Trello (опционально)

---

## Принципы разработки

1. **Вертикальная разработка** — делаем полный flow (BE → FE) для каждой фичи
2. **Инкрементальность** — сначала базовое, потом улучшаем
3. **Тестирование** — покрываем критичный функционал E2E тестами (см. [E2E_TESTING.md](E2E_TESTING.md))
4. **Документирование** — обновляем CONTEXT.md после значимых изменений
5. **data-testid** — все новые компоненты сразу получают data-testid для тестов