DTL2025/alabuga
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
7ab327a088
alabuga/Подробное ТЗ.md
danilgryaznev ce3d1e70f5 Add specificatioms
2025-09-21 18:13:36 +02:00

15 KiB
Raw Blame History

Задание для группы разработки

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), Мана, Ранг, Артефакты, Компетенции, Миссии, Ветвление, Бортовой журнал.