236 lines
15 KiB
Markdown
236 lines
15 KiB
Markdown
# Задание для группы разработки
|
||
|
||
## 0. Назначение документа
|
||
Сформулировать состав работ, критерии приёмки и артефакты по разработке мотивационного модуля геймификации для кадровой системы. Документ служит рабочим ТЗ для команды разработки.
|
||
|
||
---
|
||
|
||
## 1. Цели и ключевые показатели
|
||
**Цель:** связать разрозненные задачи кандидатов и сотрудников в прозрачные «миссии» с прогрессом и целями, повысить вовлечённость.
|
||
|
||
**KPI пилота:**
|
||
- ≥70% пользователей, начавших онбординг, завершают хотя бы 1 миссию.
|
||
- ≥50% пользователей, выполнивших 2+ миссии, поднимают ранг хотя бы на 1 уровень.
|
||
- Время до «осязаемой награды» (опыт/мана/артефакт) ≤ 3 шага.
|
||
|
||
---
|
||
|
||
## 2. Объём работ (Scope)
|
||
### 2.1 Пользовательские функции (Mobile‑first)
|
||
1) **Ранги**: линейная шкала; авто‑повышение по 3 условиям (опыт, ключевые миссии, уровни компетенций).
|
||
2) **Миссии**: каталог по категориям (Квесты, Рекрутинг, Лекторий, Симулятор); карточка миссии; выполнение с возможностью загрузки файла/ссылки.
|
||
3) **Ветвление**: миссии объединяются в «ветки»/цепочки; пользователь видит прогресс по ветке.
|
||
4) **Бортовой журнал**: хронология действий, прогресса, наград; еженедельные/месячные/годовые топы.
|
||
5) **Компетенции**: экран навыков с уровнями; прокачка от миссий.
|
||
6) **Хранилище (магазин)**: трата «маны/кредитов» на призы/бонусы; история покупок.
|
||
7) **Артефакты**: коллекция с карточками артефактов (изображение, название, описание, редкость).
|
||
8) **Онбординг и лор**: короткие сюжетные вставки, объясняющие механику и «космический» контекст.
|
||
|
||
### 2.2 Функции для HR/Организатора (Desktop)
|
||
1) **Конструктор миссий**: поля (название, описание, опыт, мана, доступность по рангу, эффекты на компетенции, артефакт по итогу).
|
||
2) **Редактор веток**: визуальная связь миссий; статусы, приоритеты.
|
||
3) **Управление рангами**: правила повышения (порог опыта, обязательные миссии, уровни компетенций).
|
||
4) **Модерация**: очередь подтверждений с прикреплёнными файлами/ссылками.
|
||
5) **Артефакты**: CRUD + атрибуты артефактов.
|
||
6) **Статистика**: конверсии по миссиям/веткам/пользователям; выгрузки.
|
||
|
||
### 2.3 Интеграции и API
|
||
- SSO/аутентификация: JWT; интеграция с внешним порталом (на этапе пилота — мок).
|
||
- Источники задач (пул миссий из внешних систем) — мок‑адаптер.
|
||
- Публичный API: чтение миссий, выполнение, прогресс, лидерборды.
|
||
- Webhooks: события выполнения/рангап/покупка.
|
||
|
||
**Вне scope пилота:** расчёт денежной стоимости призов, платежи, сквозная поставка мерча.
|
||
|
||
---
|
||
|
||
## 3. Ограничения и допущения
|
||
- Пилот: один сценарий e2e «кандидат получает оффер»; одна ветка (3–5 миссий), 2–3 ранга, 5–7 компетенций, 2–3 артефакта, 3–5 товаров.
|
||
- Данные и интеграции — замоканы; реальная интеграция после пилота.
|
||
- Темизация «космос»: палитра/иконки/фон; переключаемые темы.
|
||
|
||
---
|
||
|
||
## 4. Архитектура и стек
|
||
**Фронтенд:** React + TypeScript, Router, Zustand/Redux Toolkit; CSS‑модули или CSS‑in‑JS; Mobile‑first для пользователя, Desktop для HR.
|
||
|
||
**Бэкенд:** Python (FastAPI либо Django), БД: SQLite (пилот) → PostgreSQL (прод); JWT; миграции.
|
||
|
||
**Сервис прогресса (Rule Engine):** отдельный модуль, реагирующий на события и проверяющий 3 условия ранга.
|
||
|
||
**Событийная шина:** минимально — таблица/очередь; в перспективе — брокер.
|
||
|
||
**Файлы:** объектное хранилище (локально — каталог + антивирус‑сканер), подписанные ссылки.
|
||
|
||
**Обсервабилити:** логирование (структурированное), метрики (RPS, p95), трассировки.
|
||
|
||
---
|
||
|
||
## 5. Доменная модель (черновик)
|
||
**User**(id, role, rank_id, xp, mana, created_at)
|
||
|
||
**Rank**(id, name, order, xp_required, meta)
|
||
|
||
**RankRule**(rank_id, required_missions[], required_competency_levels{competency_id:level})
|
||
|
||
**Competency**(id, name, desc)
|
||
|
||
**UserCompetency**(user_id, competency_id, level, progress)
|
||
|
||
**Mission**(id, title, description, category, min_rank_id, rewards{x p, mana, artifact_id?}, effects{competency_id:delta})
|
||
|
||
**Branch**(id, name, desc)
|
||
|
||
**BranchEdge**(branch_id, mission_id, next_mission_id?)
|
||
|
||
**MissionSubmission**(id, mission_id, user_id, payload{file/url/text}, status)
|
||
|
||
**Artifact**(id, image_url, name, description, rarity)
|
||
|
||
**StoreItem**(id, name, price_mana, stock?, meta)
|
||
|
||
**Order**(id, user_id, item_id, status)
|
||
|
||
**JournalEntry**(id, user_id, type, payload, created_at)
|
||
|
||
— связи: User→Rank (M:1); User↔Competency (M:N); Branch↔Mission (M:N через Edge);
|
||
|
||
---
|
||
|
||
## 6. API (MVP)
|
||
### Публичное API (пользователь)
|
||
- `GET /api/me` — профиль, прогресс, текущий ранг.
|
||
- `GET /api/missions?rank=...&branch=...` — список.
|
||
- `GET /api/missions/{id}` — карточка миссии.
|
||
- `POST /api/missions/{id}/submit` — выполнение (файл/ссылка/форм‑данные).
|
||
- `GET /api/journal` — бортовой журнал, топы (?period=week|month|year).
|
||
- `GET /api/skills` — компетенции пользователя.
|
||
- `GET /api/store/items` — каталог; `POST /api/store/purchase` — покупка.
|
||
|
||
### Админ API (HR)
|
||
- `CRUD /api/admin/missions`, `/api/admin/branches`, `/api/admin/ranks`, `/api/admin/competencies`, `/api/admin/artifacts`.
|
||
- `GET /api/admin/moderation` → очередь; `POST /api/admin/submissions/{id}/approve|reject`.
|
||
- `GET /api/admin/analytics/*` — агрегаты по конверсиям.
|
||
|
||
**Контракты:** спецификация OpenAPI 3.1 (в репозитории `/openapi.yaml`).
|
||
|
||
---
|
||
|
||
## 7. НФТ (Нефункциональные требования)
|
||
- **Производительность:** p95 отклик API ≤ 200 мс при 100 RPS (пилот); начальная нагрузка 1k MAU.
|
||
- **Доступность:** 99,0% в неделю (пилот).
|
||
- **Адаптивность:** мобильные экраны ≥320 px; HR‑панель ≥1024 px.
|
||
- **Доступность (a11y):** соответствие WCAG 2.2 AA ключевых пользовательских потоков.
|
||
- **Безопасность:** базовый уровень соответствия (OWASP ASVS Level 2): аутентификация, управление сессиями, авторизация по ролям, валидация входных данных, безопасное хранение файлов, защита от XSS/CSRF/SQLi, журнал аудита админ‑действий.
|
||
- **Качество продукта:** ориентироваться на характеристики ISO/IEC 25010 (функциональная пригодность, надёжность, производительность, удобство, безопасность, сопровождаемость и др.).
|
||
|
||
---
|
||
|
||
## 8. UX/UI
|
||
- Космическая тема: палитра, фон, иконки; нейминг рангов.
|
||
- Экран пользователя: цель, прогресс‑бар до следующего ранга, доступные ветки и миссии, быстрый старт.
|
||
- Экран HR: конструктор миссий (формы), редактор веток, модерация, аналитика.
|
||
|
||
Артефакты дизайн‑системы: палитра, типографика, кнопки, карточки, формы, тосты, прогресс‑бар, модальные окна.
|
||
|
||
---
|
||
|
||
## 9. Приёмка (Definition of Done)
|
||
- Реализованы фичи разделов 2.1–2.2 (MVP‑объём).
|
||
- Покрытие интеграционными тестами ключевых сценариев; unit‑тесты Rule Engine.
|
||
- Линтеры и форматтеры подключены; CI выполняет тесты и линт.
|
||
- Сгенерирован `openapi.yaml`; README с инструкциями; сид‑данные.
|
||
- Демонстрация e2e «кандидат получает оффер» на стенде.
|
||
|
||
---
|
||
|
||
## 10. Критерии приёмки (Gherkin, выборочно)
|
||
**Сценарий: Авто‑повышение ранга по 3 условиям**
|
||
```
|
||
Given у пользователя ранг R0 и 0 XP
|
||
And есть правило повышения до R1: XP≥500, миссии [M1, M2], компетенции {Aналитика≥1, Общение≥1}
|
||
When пользователь завершает M1 и M2 и набирает ≥500 XP
|
||
And уровни компетенций удовлетворяют порогам
|
||
Then система повышает ранг до R1
|
||
And в журнал добавляется запись о рангапе
|
||
```
|
||
|
||
**Сценарий: Выполнение миссии с модерацией**
|
||
```
|
||
Given миссия M3 требует загрузки файла и модерации
|
||
When пользователь отправляет отчёт
|
||
Then запись попадает в очередь модерации со статусом “На проверке”
|
||
When HR одобряет отчёт
|
||
Then пользователь получает награды (XP, мана, артефакт?) и эффекты на компетенции
|
||
And в журнале фиксируется операция
|
||
```
|
||
|
||
**Сценарий: Покупка в магазине**
|
||
```
|
||
Given у пользователя 150 маны и товар T ценой 100
|
||
When пользователь оформляет покупку T
|
||
Then списывается 100 маны
|
||
And создаётся заказ в статусе “Ожидает выдачи”
|
||
```
|
||
|
||
**Сценарий: Ветвление миссий**
|
||
```
|
||
Given ветка B: M1 -> M2 -> M3
|
||
When пользователь завершает M1
|
||
Then M2 становится доступной
|
||
```
|
||
|
||
---
|
||
|
||
## 11. Тестирование
|
||
- **Unit:** правила рангов, расчёт наград, транзакции маной.
|
||
- **Интеграционное:** миссии→журнал, модерация, покупки.
|
||
- **E2E:** ключевой пользовательский сценарий.
|
||
- **Безопасность:** статический анализ, базовые проверки ASVS L2.
|
||
- **Доступность:** линтеры a11y, ручные проверки по чек‑листу AA.
|
||
|
||
---
|
||
|
||
## 12. CI/CD и качество
|
||
- GitHub Actions: линт, тесты, сборка докер‑образов.
|
||
- Превью‑развёртывания для PR (frontend + backend).
|
||
- Теги релизов, CHANGELOG, семантическое версионирование.
|
||
|
||
---
|
||
|
||
## 13. Сид‑данные (минимум)
|
||
- 2–3 ранга (примерные названия), пороги XP и требования.
|
||
- 1 ветка на 3–5 миссий (микс категорий).
|
||
- 5–7 компетенций с базовыми уровнями.
|
||
- 2–3 артефакта разной редкости.
|
||
- 3–5 товаров магазина.
|
||
- 3 тестовых пользователя (Кандидат, HR, Организатор).
|
||
|
||
---
|
||
|
||
## 14. План работ (ориентир, 2 спринта по 2 недели)
|
||
**Спринт 1:** доменная модель, CRUD миссий/веток/артефактов, подача списка миссий, выполнение без модерации, журнал, магазин (чтение/покупка), сид‑данные, базовый UI.
|
||
|
||
**Спринт 2:** Rule Engine (3 условия ранга), модерация, топы, аналитика HR (минимум), онбординг/лор, шлифовка UX, а11y, подготовка к демо.
|
||
|
||
---
|
||
|
||
## 15. Риски
|
||
- Сложность правил рангов → изоляция в Rule Engine + тесты.
|
||
- Нагрузочные пики (рейтинги) → кэширование/агрегаты.
|
||
- Мошенничество (накрутка) → rate‑limit, аудиты, дедупликация событий.
|
||
|
||
---
|
||
|
||
## 16. Артефакты, которые нужно предоставить
|
||
- Код (frontend/backend), Docker‑композ, сид‑данные.
|
||
- OpenAPI 3.1 спецификация.
|
||
- README: запуск, архитектура, ограничения, ссылки на стенд.
|
||
- Демо‑скрипт e2e и видео/скринкаст.
|
||
|
||
---
|
||
|
||
## 17. Глоссарий
|
||
Пользователь, HR, Организатор, Опыт (XP), Мана, Ранг, Артефакты, Компетенции, Миссии, Ветвление, Бортовой журнал.
|
||
|