team-planner/REQUIREMENTS.md

# Team Planner - Требования к приложению

## Описание продукта

Приложение для команды разработки, позволяющее собирать бэклог идей, приоритизировать его, проводить брейнштормы, оценивать задачи и оставлять комментарии.

---

## Функциональные требования

### 1. Управление идеями

#### 1.1 Список идей
Таблица со следующими полями для каждой идеи:

| Поле | Описание | Тип |
|------|----------|-----|
| Статус | Текущее состояние идеи (Новая, В обсуждении, Одобрена, В работе, Готово, Отклонена) | Enum |
| Приоритет | Важность идеи (Критический, Высокий, Средний, Низкий) | Enum |
| Модуль | Где реализуется (Frontend, Backend, AI, Mobile, Infrastructure, Other) | Enum/Multi-select |
| Суть идеи | Краткое описание идеи | Text |
| Для кого | Целевая аудитория / пользователь | Text |
| Какую боль решает | Проблема, которую решает идея | Text |
| Роль AI | Что делает ИИ в рамках этой идеи (если применимо) | Text |
| Способ проверки | Быстрый способ валидации идеи / MVP | Text |
| Комментарии | Обсуждение и заметки | Text (список комментариев) |
| Цвет | Цветовая маркировка строки | Color |
| Оценка времени | AI-генерируемая оценка трудозатрат | Calculated |

#### 1.2 Автор идеи
- При создании идеи автоматически сохраняется автор (текущий пользователь)
- Автора идеи изменить нельзя (поле readonly)
- Отображение автора в таблице и детальном просмотре

#### 1.3 Редактирование идей
- **Полный просмотр**: пользователь может просмотреть ВСЕ поля идеи (включая pain, aiRole, verificationMethod)
- **Полное редактирование**: пользователь может отредактировать ВСЕ редактируемые поля идеи
- **Inline-редактирование**: возможность редактировать любое поле прямо в таблице двойным кликом
- **Детальный просмотр**: модалка с полной информацией об идее
  - Открывается в **режиме просмотра** (readonly)
  - Кнопка "Редактировать" переводит в **режим редактирования**
  - Кнопка "Сохранить" сохраняет изменения
  - Кнопка "Отмена" отменяет изменения
- **Column visibility**: возможность скрыть/показать колонки таблицы
- **Быстрое изменение статуса и приоритета** через dropdown
- **Автосохранение** изменений (для inline-редактирования)

#### 1.4 Drag & Drop
- Перемещение идей в списке для ручной сортировки
- Визуальная индикация при перетаскивании
- Сохранение порядка после перемещения

#### 1.5 Цветовая маркировка
- Возможность назначить цвет строке для визуального выделения
- Предустановленная палитра цветов
- Фильтрация по цвету

#### 1.6 Экспорт идеи
- Экспорт отдельной идеи в формате DOCX
- Включает: название, описание, статус, приоритет, модуль, целевую аудиторию, боль, роль AI, способ проверки
- Если есть AI-оценка — включается в документ (общее время, сложность, разбивка по ролям, рекомендации)
- Если есть ТЗ — включается в документ (markdown рендерится как форматированный текст)
- Комментарии к идее включаются в документ (автор, дата, текст)

### 2. Сортировка и фильтрация

#### 2.1 Сортировка
- По любому полю (клик на заголовок колонки)
- Множественная сортировка (Shift + клик)
- Сохранение настроек сортировки

#### 2.2 Фильтры
- Фильтр по статусу
- Фильтр по приоритету
- Фильтр по модулю
- Фильтр по цвету
- Текстовый поиск по всем полям
- Сохранение пресетов фильтров

### 3. AI-оценка времени

#### 3.1 Управление командой
- Список членов команды с ролями:
  - Backend-разработчик
  - Frontend-разработчик
  - AI/ML-инженер
  - Аналитик
  - Тестировщик (QA)
  - DevOps
  - Дизайнер
  - Project Manager
- Количество сотрудников каждой роли

#### 3.2 Матрица производительности
Для каждого сотрудника/роли указывается время на задачи разной сложности:

| Сложность | Описание | Пример времени |
|-----------|----------|----------------|
| Trivial | Тривиальная задача | 1-2 часа |
| Easy | Лёгкая задача | 0.5-1 день |
| Medium | Средняя задача | 2-3 дня |
| Hard | Сложная задача | 1-2 недели |
| Epic | Эпик / большая фича | 2-4 недели |

#### 3.3 AI-функционал
- Анализ описания идеи
- Определение необходимых ролей для реализации
- Оценка сложности для каждой роли
- Расчёт общего времени с учётом состава команды
- Рекомендации по оптимизации

#### 3.4 Генерация мини-ТЗ
- **Генерация ТЗ**: создание структурированного технического задания на основе описания идеи
- **Структура ТЗ**: цель, функциональные требования, технические требования, критерии приёмки, зависимости и риски
- **Сохранение**: ТЗ сохраняется в базе данных для повторного использования
- **Просмотр**: возможность просмотреть сохранённое ТЗ по клику на кнопку
- **Редактирование**: возможность изменить сгенерированное ТЗ вручную
- **Интеграция с оценкой**: AI-оценка времени учитывает ТЗ для более точного расчёта

### 4. Комментарии

- Добавление комментариев к идее
- Ответы на комментарии (треды)
- Упоминание участников (@mention)
- История комментариев

### 5. Система прав доступа

#### 5.1 Роли пользователей
- **Администратор** — единственный пользователь с полными правами, логин задаётся в секретах кластера (K8s Secret)
- **Обычный пользователь** — новый пользователь после первого входа получает только права на просмотр
- Администратор может изменять права любого пользователя (кроме себя)

#### 5.2 Гранулярные права доступа
Каждое право настраивается отдельно:

| Право | Описание |
|-------|----------|
| `view_ideas` | Просмотр списка идей (по умолчанию: ✅) |
| `create_ideas` | Создание новых идей |
| `edit_own_ideas` | Редактирование своих идей |
| `edit_any_ideas` | Редактирование чужих идей |
| `delete_own_ideas` | Удаление своих идей |
| `delete_any_ideas` | Удаление чужих идей |
| `reorder_ideas` | Изменение порядка идей (drag & drop) |
| `add_comments` | Добавление комментариев |
| `delete_own_comments` | Удаление своих комментариев |
| `delete_any_comments` | Удаление чужих комментариев |
| `request_ai_estimate` | Запрос AI-оценки трудозатрат |
| `request_ai_specification` | Запрос AI-генерации ТЗ |
| `edit_specification` | Редактирование ТЗ |
| `delete_ai_generations` | Удаление AI-генераций (оценки, ТЗ) |
| `manage_team` | Управление командой (добавление/удаление участников) |
| `manage_roles` | Управление ролями команды |
| `export_ideas` | Экспорт идей в документы |
| `view_audit_log` | Просмотр истории действий |

#### 5.3 Панель администратора
- Доступна только администратору
- Таблица пользователей с их правами
- Чекбоксы для включения/выключения каждого права
- Применение изменений сохраняется немедленно

### 6. История действий (Аудит)

#### 6.1 Логирование действий
- Любые манипуляции с данными фиксируются: создание, редактирование, удаление идей, генерации AI, комментарии
- Сохраняется: кто сделал, что сделал, когда, старое значение, новое значение

#### 6.2 Формат записи аудита
| Поле | Описание |
|------|----------|
| id | Уникальный идентификатор записи |
| userId | ID пользователя |
| userName | Имя пользователя |
| action | Тип действия (create, update, delete, generate, restore) |
| entityType | Тип сущности (idea, comment, specification, estimate, team_member) |
| entityId | ID сущности |
| oldValue | Значение до изменения (JSON) |
| newValue | Значение после изменения (JSON) |
| timestamp | Дата и время действия |

#### 6.3 Просмотр истории
- Страница истории действий (только для админа или пользователей с правом `view_audit_log`)
- Фильтрация по пользователю, типу действия, типу сущности, дате
- Возможность просмотра diff (что изменилось)
- Восстановление удалённых данных из аудита

#### 6.4 Настройки хранения
- Срок хранения истории настраивается администратором
- По умолчанию: 30 дней
- Автоматическая очистка старых записей по cron job

### 7. Многопользовательская работа

#### 7.1 Real-time обновления (WebSocket)
- Автоматическое обновление данных у всех пользователей при изменениях
- События: создание/редактирование/удаление идей, новые комментарии, изменение порядка
- Визуальная индикация изменений другими пользователями

#### 7.2 Конкурентное редактирование
- При попытке редактировать идею, которую редактирует другой пользователь — предупреждение
- Показ кто сейчас редактирует запись
- Оптимистичная блокировка с version/updatedAt

#### 7.3 Присутствие пользователей
- Показ онлайн пользователей
- Аватары/иконки пользователей, работающих с приложением

### 8. Темная тема

#### 8.1 Переключение темы
- Переключатель светлая/тёмная тема в header
- Автоопределение системной темы (prefers-color-scheme)
- Сохранение выбора в localStorage

#### 8.2 Цветовая схема
- Все компоненты поддерживают обе темы
- Цвета статусов, приоритетов и маркировки адаптированы для тёмной темы
- MUI theme provider с dark mode

---

## Технические требования

### Backend (NestJS)

#### Стек технологий
- **Framework**: NestJS
- **Language**: TypeScript
- **Database**: PostgreSQL
- **ORM**: TypeORM
- **API**: REST + WebSocket (для real-time обновлений)
- **WebSocket**: @nestjs/websockets + Socket.io
- **AI Integration**: ai-proxy service тут лежит гайд по интеграции /Users/vigdorov/dev/gptunnel-service/INTEGRATION.md
- **Document Generation**: docx (для экспорта)
- **Cron Jobs**: @nestjs/schedule (для очистки аудита)

### Frontend (React + TypeScript)

#### Стек технологий
- **Framework**: React 18+
- **Language**: TypeScript
- **State Management**: Zustand
- **UI Library**: MUI
- **Table**: TanStack Table (react-table)
- **Drag & Drop**: dnd-kit / react-beautiful-dnd
- **HTTP Client**: Axios / React Query
- **Styling**: Tailwind CSS / CSS Modules

## Нефункциональные требования

### Производительность
- Виртуализация списка при большом количестве идей (1000+)
- Оптимистичные обновления UI
- Кэширование данных

### UX
- Отзывчивый интерфейс (< 100ms на действие)
- Keyboard shortcuts для частых операций
- Responsive design (desktop-first)

### Безопасность
- Валидация входных данных
- Rate limiting для AI-запросов
- Проверка прав доступа на каждом endpoint
- Защита от конкурентных изменений (оптимистичная блокировка)

### Авторизация и авторизация
- **Keycloak** (auth.vigdorov.ru) — внешний Identity Provider
- Авторизация через редиректы на стандартную форму Keycloak
- Authorization Code Flow + PKCE
- JWT токены с валидацией через JWKS
- Автоматическое обновление токенов
- Защита всех API endpoints (кроме /health)
- **Гранулярные права доступа** — см. раздел 5
- **Администратор** определяется через K8s Secret `ADMIN_EMAIL`

---

## Решённые вопросы

1. Нужна ли многопользовательская работа и разграничение прав?
**ДА** — см. разделы 5 (Права доступа) и 7 (Многопользовательская работа)

2. Требуется ли история изменений (audit log)?
**ДА** — см. раздел 6 (История действий)

3. Нужен ли экспорт данных?
**ДА** — экспорт отдельной идеи в DOCX (см. раздел 1.6)

4. Интеграция с внешними системами (Jira, Trello)?
**НЕТ** — не требуется