Vocabulary Документация проекта

Vocabulary — исходный контекст

Марина хочет создать веб-приложение для заучивания английских и латинских слов для сына Лёши (13 лет, 7 класс Gymnasium). Оно должно работать на телефоне, планшете и ноутбуке, Лёша занимается в нём сам примерно по 10 минут в день.

Сейчас

Есть простое самописное приложение с карточками «знаю / не знаю», слова прогоняются по кругу.

Проблема

Принятые решения

Режимы и данные

Игра

Мотивация

Отложено — не входит в MVP

Открытые вопросы из исходного обсуждения

Дополнения от 20.11.2026

Публикация и приоритет устройств

Agent.md — правила работы над Vocabulary

Назначение проекта

Vocabulary — mobile-first веб-приложение для самостоятельного ежедневного заучивания Лёшей английских и латинских слов. Оно должно объективно проверять знания, не заставлять повторять уже знакомое и возвращать сложные слова в следующие дни.

Пользователи:

Источники правды

Перед изменениями прочитай в таком порядке:

  1. Info.md — исходная постановка и формулировки Марины;
  2. Spec.md — требования и критерии приёмки;
  3. Desigions.md — принятые и временные решения;
  4. Tasks.md — порядок реализации и текущее состояние.

Исходники старого интерфейса сохранены в legacy/, а извлечённая из них база — в data/legacy-vocabulary.json. Старую игровую механику не переносить: она служит только референсом данных.

Если документы расходятся, приоритет: последнее подтверждённое решение пользователя → Desigions.md → Spec.md → Info.md. Не превращай временное решение в подтверждённое без согласования.

Продуктовые принципы

UX и доступность

Данные, безопасность и AI

Инженерный процесс

Definition of Done для функции

Функция считается готовой, когда:

Spec.md — спецификация Vocabulary MVP

1. Цель

Сделать веб-приложение, в котором Лёша самостоятельно за примерно 10 минут в день:

  1. быстро отсеивает слова, которые действительно знает;
  2. объективно подтверждает часть ответов «знаю»;
  3. повторяет сомнительные и незнакомые слова до завершения бандла;
  4. встречает сложные слова снова в следующие дни;
  5. получает понятный прогресс и лёгкую игровую награду.

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

2. Границы MVP

Входит

Не входит

3. Роли и навигация

Alex

После запомненного входа видит:

Интерфейс и игровые тексты — на немецком. Рабочие подписи трёх кнопок до отдельного UX-решения: Weiß ich, Unsicher, Weiß ich nicht; внутреннее название loading не показывается пользователю.

Parent

Видит:

Родительский интерфейс — на русском.

4. Основные сущности данных

User

Language

Unit

Bundle

Word

Связь слова и бандла должна позволять не дублировать одну словарную запись при повторном появлении и при этом хранить её участие в разных бандлах.

ImportJob

Session / SessionItem / Attempt

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

RewardCard / UserCard

RewardCard хранит футболиста, изображение и служебный идентификатор. UserCard хранит дату получения и бандл-источник. В MVP повторное выпадение допустимо или запрещено согласно решению D-014 в Desigions.md.

5. Импорт слов

  1. Parent выбирает язык, вводит unit и выбирает 1–10 фото.
  2. Сервер проверяет число, тип и размер файлов, сохраняет их вне публичного каталога.
  3. Создаётся фоновая задача Terra/Codex headless.
  4. Распознавание возвращает пары немецкое → английское/латинское, сохраняя пометки о неуверенности.
  5. Parent видит таблицу проверки: может исправить, удалить, добавить строку и отметить сомнительное место.
  6. При подтверждении создаётся один новый draft-бандл и слова/связи с ним.
  7. Только после явной активации бандл доступен Alex.
  8. При сбое можно повторить обработку без повторной загрузки и без создания дублей.

Критерии приёмки:

6. Игровая сессия

6.1 Старт

6.2 Карточка

На карточке показано немецкое значение. Иностранное слово скрыто. Доступны три крупные кнопки:

Термин «лоадинг» — продуктовое имя механики; немецкую подпись подтверждает Марина.

6.3 План проверок «знаю»

6.4 Ввод ответа

6.5 Очки

Событие Очки
«знаю» без проверки +1
«знаю» с верной проверкой +3
«знаю» с неверной проверкой −10
«лоадинг» с верным ответом +2
«лоадинг» с неверным ответом 0
«не знаю» 0

6.6 Возврат в круг и завершение

6.7 Прогресс и мотивация

7. Долгосрочное обучение — правило MVP

Используется простая объяснимая модель, подтверждённая Мариной:

Это правило должно быть изолировано в конфигурации/доменном сервисе, чтобы его можно было изменить без миграции истории попыток.

8. Статистика parent

MVP показывает:

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

9. Нефункциональные требования

10. События аналитики MVP

Хранить доменные события без стороннего трекера:

Главные продуктовые показатели: медианная длительность сессии, доля завершённых бандлов, доля ошибочных «знаю», число слов, которые возвращаются в следующие дни, и удержание без принудительных streak-механик.

11. Сквозные критерии приёмки MVP

MVP готов к семейному использованию, если:

  1. Parent загружает фото, исправляет результат и активирует бандл без работы с базой/терминалом.
  2. Alex на телефоне входит один раз, выбирает язык и завершает бандл с корректными кругами, VAR и очками.
  3. Перезагрузка страницы не теряет сессию и не дублирует очки/награду.
  4. Сложные слова появляются в разминке в другой день, а история объясняет почему.
  5. English и Latein не смешивают данные, темы и автодополнение.
  6. Parent видит статистику и может вернуть слово в изучение.
  7. Завершение бандла ровно один раз выдаёт карточку.
  8. Интерфейс пригоден на телефоне, планшете и ноутбуке.
  9. База резервируется, приложение поднимается после рестарта VPS и работает через HTTPS на Softdock.

Desigions.md — журнал решений

Имя файла сохранено в написании, которое задала Марина. Статусы: принято, временно, открыто, отложено.

D-001. Один адаптивный веб-интерфейс

D-002. Две серверные роли

D-003. Языки разделены

D-004. Немецкий — вопрос, иностранный — ответ

D-005. Три самооценки

D-006. Скрытая проверка «знаю»

D-007. VAR после ошибки

D-008. Система очков

D-009. Повтор внутри сессии

D-010. Завершение слова в текущем бандле

D-011. Сравнение ответа

D-012. Долгосрочный статус и сложность

D-013. Разминка

D-014. Футбольные карточки

D-015. Мотивационная реакция

D-016. Импорт через Terra/Codex headless

D-017. Human-in-the-loop для OCR

D-018. Изображения распечаток

D-019. Стек приложения

D-020. Публикация

D-021. Часовой пояс дня

D-022. Отложенные функции

D-023. Перенос слов из старого приложения

Подтверждения Марины от 20.11.2026

Все восемь первоначальных вопросов закрыты. Настоящие изображения карточек будут загружены позже; до этого используются плейсхолдеры.

Tasks.md — план реализации Vocabulary

Легенда

0. Продуктовая фиксация

1. Аудит и технический фундамент

Результат этапа: пустое, но запускаемое приложение с тестами и зафиксированной архитектурой.

2. UX-прототип

Результат этапа: согласованный кликабельный или HTML-прототип ключевого потока.

3. База и авторизация

Результат этапа: обе роли входят и видят только разрешённые экраны/API.

4. Словарь и бандлы parent

Результат этапа: parent может полностью подготовить бандл вручную.

5. Игровой движок

Обязательные тест-кейсы:

Результат этапа: весь бандл можно честно пройти на мобильном экране.

6. Междневное обучение

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

7. OCR через Codex headless

Результат этапа: родитель превращает фотографии в проверенный бандл без терминала.

8. Награды и коллекция

Результат этапа: завершение бандла даёт одну карточку, коллекция сохраняется.

9. Статистика parent

Результат этапа: Марина видит, что Лёша делал и какие слова требуют внимания.

10. Качество и пилот

Результат этапа: подтверждено, что реальная сессия укладывается примерно в 10 минут и не раздражает.

11. Деплой Softdock

Результат этапа: приложение стабильно доступно на Softdock и переживает перезапуск VPS.

После MVP — backlog