17 KiB
17 KiB
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
Решённые вопросы
-
Нужна ли многопользовательская работа и разграничение прав? ДА — см. разделы 5 (Права доступа) и 7 (Многопользовательская работа)
-
Требуется ли история изменений (audit log)? ДА — см. раздел 6 (История действий)
-
Нужен ли экспорт данных? ДА — экспорт отдельной идеи в DOCX (см. раздел 1.6)
-
Интеграция с внешними системами (Jira, Trello)? НЕТ — не требуется