Until now the 'gamification' feature flag did nothing: it had no row in
app_settings, the admin couldn't toggle it, awardXP/awardCoins ignored
it, and the CSS only hid three dashboard widgets — XP bars in textbooks
stayed visible regardless.
Phase 1 closes every hole.
Backend (source of truth):
• migration 029 seeds feature_gamification_enabled=1
• new isGamificationEnabled() helper in gamification/_shared.js with a
30s cache + invalidateGamificationCache() for instant admin toggles
• awardXP / awardCoins / updateStreak / unlockAchievement /
checkAchievements all bail out when the flag is off
• /api/gamification/* and /api/shop/* (user routes) return 404 when
disabled; admin routes remain open so the switch itself is reachable
• adminController.updateFeatures gains 'gamification' in the allow-list
and invalidates the cache on flip
Frontend:
• LS.isGamificationEnabled() (synchronous, populated by loadFeatures)
so xp.js + applyCosmetics can bail without a round-trip
• xp.js load/add/flush become no-ops when the flag is off
• applyCosmetics skips the round-trip when off
• CSS .no-gamification rule expanded to cover .hero-xp-badge, .po-xp,
.xp-card, .xp-bar, #frames-section, and a universal [data-gamified]
hook for future blocks
Textbooks (Variant 2 of the plan):
• backend/scripts/wrap_textbook_xp.py — idempotent script that adds
data-gamified to 167 XP tags across 63 textbook files (chapters +
hubs, all subjects/grades). Single CSS rule now hides everything.
Verified end-to-end: with the flag off, awardXP/awardCoins write nothing;
flipping back restores normal behavior.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- migration 014: parent_slug column + algebra-8 hub row +
rename old algebra-8 → algebra-8-ch1 (progress сохраняется
через стабильный textbook_id=3)
- backend/routes/textbooks.js: GET / фильтрует parent_slug IS NULL;
aggregated progress для хабов; новый GET /:slug/children
- algebra_8_hub.html: новая хаб-страница с 3 карточками глав,
hero с общим прогрессом, XP-бейдж, ссылки на главы
- algebra_8/ch2/ch3: кнопки cross-chapter заменены на
одну «К алгебре 8» в шапке
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Раньше: алгебра 1 и 2 главы хранили прогресс только в localStorage,
поэтому каталог /textbooks показывал 0/N прочитано и кнопку 'Открыть'
даже после активной работы с учебником.
Теперь обе главы шлют POST /api/textbooks/:slug/progress:
- markLastPara(id) — при каждом goTo(); сервер запоминает last_para,
каталог показывает кнопку 'Продолжить'.
- markParaRead(id) — когда STATE.progress[key] первый раз ≥ 50%
(внутрипараграфный прогресс достаточен); сервер добавляет id в
paragraphs_read[], каталог показывает '1/7 прочитано'.
- Дебаунс 600мс — несколько быстрых переходов схлопываются в один POST.
- keepalive:true + beforeunload-flush, чтобы последний переход не
потерялся при закрытии вкладки.
- loadServerReadState() при init() — если на другом устройстве уже
прочитаны параграфы, локальный STATE.progress поднимается до 100%
для них (визуально совпадает с каталогом).
Slug: 'algebra-8' для ch1, 'algebra-8-ch2' для ch2.
- backend: POST /api/gamification/self-award (rate-limited, validated)
- frontend/js/xp.js: load/add/flush/on клиент, ~150 LOC, дебаунс 300мс,
keepalive fetch на unload/visibilitychange hidden
- algebra_8.html и algebra_8_ch2.html: XP_LEVELS заменён на единую
формулу с сервером; addXp/loadProgress подключены к window.LS.xp
- При первой загрузке: merge max(local, server); далее сервер — источник
правды
Раньше: каждая глава хранила XP отдельно (algebra8_ch1_xp +
algebra8_ch2_xp), формулы уровня были разные (дискретная таблица в
ch1, формула sqrt в ch2), визуально XP-карты различались.
Теперь:
- Один ключ localStorage: 'algebra8_xp' для обеих глав.
- При первой загрузке (в любой главе) — single-shot миграция:
если новый ключ отсутствует, суммирует старые ch1 + ch2 и
сохраняет под единый ключ. Старые ключи не удаляются (на всякий).
- Единая таблица уровней XP_LEVELS = [0, 50, 120, 220, 350, 520,
740, 1000, 1300, 1700, 2200] (11 уровней, MAX = Ур. 11).
- Единые функции calcLevel(xp) и _xpForLevel(lv).
- XP-карта в сайдбаре главы 2 теперь идентична главе 1:
градиент acc→pri-soft, .xp-card-title, .xp-bar, .xp-fill, .xp-nums.
- Hero badge «★ Ур. N · NN XP» добавлен в hero обоих глав.
- addXp в ch2: при повышении уровня — popup с номером уровня + confetti.
- addXp в ch1: refreshProgressUI вызывается, чтобы обновлять hero
badge сразу после начисления.
- SIDEBARS.final2: убрал stub 'будет в Wave 4', добавил 5 строк по
финалу (7 боссов, типы заданий, награда, практика, серия).
- XP card в сайдбаре: уровень (Lv N), текущий XP, прогресс-бар до
следующего уровня, остаток XP. Формула: Lv = floor(sqrt(xp/50)).
- XP badge в hero (рядом с прогрессом): жёлто-розовая пилюля
«★ Lv N · NN XP», обновляется при каждом addXp.
- TIPS: 7 советов (по одному на каждый §+финал). В сайдбаре отдельная
карточка «Подсказка» с жёлтым градиентом — контекстная под текущий
параграф.
- refreshProgressUI: после изменения XP пересобирает сайдбар, чтобы
карточки опыта/совета оставались актуальными.
Универсальный хелпер setupSorter(cfg) с pointer-events:
- desktop: тащим карточку → подсветка целевого ящика → отпускаем = поставлено
- touch / mobile: тап по карточке (становится "armed") → тап по ящику = поставлено
- × кнопка на placed-чипе → возврат в pool
- drop за пределы ящика на сам pool тоже возвращает чип
- threshold 8px — клик не превращается в drag случайно
Стили: .dnd-chip с cursor:grab/active grabbing, .armed shadow,
.dragging opacity, .drop-box.over подсветка с лёгким scale.
Применено к:
- § 7 INT 2 (полное / неполное / не квадратное) — 8 уравнений
- § 10 INT 5 (раскладывается / не раскладывается) — 8 трёхчленов
- § 11 INT 5 (движение / работа / числа / геометрия) — 8 задач,
columnLayout:true для длинных текстов
Старые «лесенки кнопок Полн./Неполн./Не квадр.» удалены — теперь
один-клик-затем-один-клик или drag. § 12 INT 4 оставлен как
<select> (другой паттерн: одна метка для нескольких уравнений).
Три «пошаговых» решателя дампили все шаги сразу при первом клике.
Переписаны на прогрессивное раскрытие:
- § 8 INT 5 «Пошаговый решатель» (квадратное)
- § 10 INT 2 «Пошаговый разлагатель»
- § 12 INT 1 «Решатель биквадратного»
Паттерн: Старт → шаги собираются в массив, idx=0 → Дальше (1/N) →
каждый шаг — отдельный блок с border-left и fadeIn. По окончании —
кнопка «Готово», начисление достижения и confetti. Кнопка «Сначала»
сбрасывает к Старту.
Ещё: § 8 INT 4 — $D = b^2 - 4ac$ показывался буквально с долларами,
потому что использовался textContent + renderMath на чужом элементе.
Заменено на innerHTML + renderMath на правильный узел.
- Слайдеры (.sliders label): убран flex-direction:column, который раскладывал
KaTeX-span / '=' / <b> / <input> на 4 строки. Теперь label = block,
всё на одной строке, slider — на следующей.
- .wg-help: вместо мелкого курсива — полноценный hint-box с жёлтым
градиентом, левой полосой и круглым «?» слева. Совпадает по визуалу
с главой 1.
- Шпаргалка: добавлена кнопка «Шпаргалка» в шапке, на узких экранах
(≤980px) col-side превращается в выезжающий справа drawer с
backdrop'ом, открывается по кнопке/закрывается по клику вне или Esc.
- initSidebarToggle() вызывается из init().
Maxim Dolgolyov