Достижения и командные челленджи

Достижения и командные челленджи — это поверхность прогресса в Mockarty, включаемая по желанию. Она отвечает на два вопроса: «сколько я здесь сделал» и «что я попробовал впервые» — а для команды: «сколько нас до этого дошло». Это фундамент: движок измерения и его правила, а не система очков или рейтингов.

Только по желанию. О вас ничего не измеряется, пока вы это не включите, а выключение это прекращает. См. Включение и выключение.

Что измеряется, а что — нет

Прогресс читается из работы, которую платформа уже записала. Второго учёта нет: достижение никогда не считает то, чего не подтвердил прогон, мок или перехваченный запрос.

Все входы, которые может читать достижение, перечислены в одном месте, и список закрыт. Две категории входов отклоняются намеренно, и отказ называет правило:

Для достижения категории «обучение» правило строже: его можно получить только за то, что вы сделали — за завершённый прогон, — но не за то, чем вы владеете. Владеть сотней моков — это накопление; впервые запустить контрактный тест — это обучение.

Достижение, называющее несуществующий вход, тоже отклоняется. Ни в одном из случаев оно не выдаётся молча ни за что, и ни в одном из случаев оно не выдаётся молча всем.

Как считается прогресс

Числа защищают два свойства, и оба видны снаружи:

• Разная работа, а не попытки. Один завершённый прогон — это один прогон, сколько бы раз платформу о нём ни спросили. Повторные запросы одного и того же не могут поднять число.
• Измерено — или не измерено. Но не выдуманный ноль. Если вход прочитать нельзя, поверхность это и говорит, а не показывает 0 из 10. Ноль — это измерение, и Mockarty его не выдумывает.

Достижения и командные челленджи

Достижение — личная запись: список входов, «сколько достаточно» для каждого и, необязательно, скользящее окно («за последние 30 дней»). Своего окна у него нет.

Командный челлендж — то же измерение, но с началом, концом и жизненным циклом (черновик, активен, завершён). Его счёт считает только включившихся: коллега, не включивший отслеживание, не попадает ни в числитель, ни в знаменатель. Счёт всегда идёт рядом с числом включившихся, чтобы «3» нельзя было прочитать как «все».

Оба вида делят одно пространство имён имён, поэтому одно и то же имя никогда не означает две разные цели.

Определение неизменяемо

Достижение или челлендж нельзя отредактировать. Это намеренно: правка на месте задним числом изменила бы то, что люди уже заработали против него.

Чтобы изменить цель, отозвите её и создайте новую. Отзыв освобождает имя, а уже полученные награды сохраняются — это факты о прошлом, и удаление переписало бы его.

Включение и выключение

Отслеживание прогресса выключено, пока вы его не включите, и оно всегда про вас: чужую запись нельзя ни прочитать, ни закрыть — даже владельцу пространства.

• Включение запускает (или возобновляет) ваше отслеживание. Оно идемпотентно — повторный запрос ничего не меняет.
• Выключение его прекращает и скрывает ваш прогресс от вас. Уже полученные награды сохраняются, а не удаляются.
• Повторное включение возобновляет вместе с уже сделанной работой, потому что прогресс читается из записи, а не хранится.

Пока вы не включились, чтение прогресса отвечает «не включено», а не строкой нулей — так «я не включал» и «я включил, но пока ничего не произошло» никогда не выглядят одинаково.

Работа с API

Все маршруты привязаны к пространству имён и требуют токен с доступом к нему. Замените $MOCKARTY_API_TOKEN и sandbox на свои.

Посмотреть, что можно измерять

curl http://localhost:5770/api/v1/namespaces/sandbox/gamification/catalogue \
  -H "Authorization: Bearer $MOCKARTY_API_TOKEN"

Ответ перечисляет каждый вход с allowed: true (с классом доказательства, способом подсчёта и наличием окна) и каждый отклонённый вход с правилом, которое его отклоняет. Прочитайте это прежде, чем что-то определять — это полный словарь.

Определить достижение

Определять, что измеряет пространство, — действие уровня владельца: участник не должен решать, по чему измеряют его коллег.

curl -X POST http://localhost:5770/api/v1/namespaces/sandbox/gamification/definitions \
  -H "Authorization: Bearer $MOCKARTY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "first-test-plan-week",
    "title": "Три прогона тест-плана за неделю",
    "description": "Засчитываются три завершённых прогона тест-плана за последние семь дней.",
    "category": "progress",
    "kind": "achievement",
    "idempotency_key": "define-first-test-plan-week",
    "terms": [
      {"source": "run.test_plan.settled", "threshold": 3, "window_days": 7}
    ]
  }'

idempotency_key делает вызов безопасным к повтору: тот же ключ от того же человека даёт то же определение, а не дубликат. key, уже занятый живым определением, отклоняется — сперва отзовите старое.

Отказы конкретны, и это самая полезная часть:

Список и отзыв определений

curl http://localhost:5770/api/v1/namespaces/sandbox/gamification/definitions \
  -H "Authorization: Bearer $MOCKARTY_API_TOKEN"

curl -X DELETE http://localhost:5770/api/v1/namespaces/sandbox/gamification/definitions/first-test-plan-week \
  -H "Authorization: Bearer $MOCKARTY_API_TOKEN"

Включить, прочитать прогресс, выключить

curl -X POST http://localhost:5770/api/v1/namespaces/sandbox/gamification/enrolment \
  -H "Authorization: Bearer $MOCKARTY_API_TOKEN"

curl http://localhost:5770/api/v1/namespaces/sandbox/gamification/progress \
  -H "Authorization: Bearer $MOCKARTY_API_TOKEN"

curl -X DELETE http://localhost:5770/api/v1/namespaces/sandbox/gamification/enrolment \
  -H "Authorization: Bearer $MOCKARTY_API_TOKEN"

progress возвращает, включено ли у вас отслеживание, насколько близко каждое достижение, что вы заработали и командные челленджи пространства. Каждый терм несёт собственное показание и признак «измерено», поэтому частично читаемое достижение сообщается честно, а не округляется до числа.

Закрыть награду

curl -X POST http://localhost:5770/api/v1/namespaces/sandbox/gamification/awards/first-test-plan-week \
  -H "Authorization: Bearer $MOCKARTY_API_TOKEN"

Отправлять нечего: сервер сам перечитывает запись и решает. Вы не можете наградить себя за то, чего не сделали.

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

Командные челленджи

curl http://localhost:5770/api/v1/namespaces/sandbox/gamification/challenges \
  -H "Authorization: Bearer $MOCKARTY_API_TOKEN"

Каждый челлендж сообщает earned_members (включившиеся, получившие его внутри окна) вместе с enrolled_members (сколько людей включились вообще).

Кому что можно

Определение и отзыв пишутся в журнал аудита, включая то, какие входы читает определение. Награды — нет: это ваша собственная запись, а не изменение полномочий над кем-то другим.