docs: update README, PLAN, TODO, MENTOR_CONTEXT with full implemented functionality and architecture

2026-10-07 15:20:44 +03:00
1 parent c89b0d6238
commit 03c692fe43
@@ -1,175 +1,111 @@
-# План развития проекта Notes (notes.qpid.pro)
+# План развития и архитектурная дорожная карта: Study Qpid (study.qpid.pro)

-> **Принцип проектирования**: *«Работает как автомат Калашникова»* — сверхнадёжно, мгновенно, защищено для публичного интернета, без раздутых зависимостей и постоянного ручного обслуживания.
+> **Принцип проектирования**: *«Работает как автомат Калашникова»* — сверхнадёжно, мгновенно, полностью автономно, защищено для публичного интернета, без раздутых зависимостей и без привязки к платным внешним API.

 ---

-## 1. Архитектура и защита системы
+## 1. Архитектура системы

-Сервис разворачивается на публичном сервере с белым IP (`31.77.203.213`). Вся система проектируется с учётом сетевой безопасности и изоляции личных данных.
+Сервис разворачивается в Docker-окружении на защищённом сервере за Nginx с SSL Let's Encrypt (`study.qpid.pro`).

 ```
 ┌─────────────────────────────────────────────────────────────┐
-│                       notes.qpid.pro                        │
+│                       study.qpid.pro                        │
 │            Nginx (HTTPS / Let's Encrypt / Security Headers) │
 └──────────────────────────────┬──────────────────────────────┘
-                               │ proxy_pass :8002
+                               │ proxy_pass 127.0.0.1:8002
 ┌──────────────────────────────▼──────────────────────────────┐
-│                    Слой безопасности (Auth)                 │
-│  • Аутентификация: сессионные токены (HTTP-only cookies)    │
-│  • Хэширование паролей: PBKDF2-HMAC-SHA256 (соль + 100k)   │
-│  • Защита от перебора (Rate Limiter: макс 5 попыток/мин)    │
-│  • Закрытый доступ: все эндпоинты требуют авторизации       │
+│             Docker Container: study-qpid-pro                │
+│                                                             │
+│  • FastAPI Lifespan & Security Middlewares (GZip, Headers)  │
+│  • Модульные APIRouters (auth, cards, srs, reader, etc.)    │
+│  • SQLite WAL + mmap I/O (транзакции, 0.01ms чтение)        │
+│  • Локальный Piper Neural TTS (чистый нативный голос VITS)  │
+│  • Вынесенные JSON-датасеты (data/seeds/)                   │
+│  • Модульные CSS-стили (7 предметных таблиц + PWA SW v6.7)  │
 └──────────────────────────────┬──────────────────────────────┘
-                               │
+                               │ http://ollama:11434 (Keep-Alive 120s)
 ┌──────────────────────────────▼──────────────────────────────┐
-│                    Backend: Python 3.12                     │
-│    FastAPI / Uvicorn + SQLite (WAL mode) + Dictionary APIs  │
-└──────────────────────────────┬──────────────────────────────┘
-                               │
-       ┌───────────────────────┴───────────────────────┐
-       ▼                                               ▼
-┌─────────────────────────────┐         ┌─────────────────────────────┐
-│     Внешние открытые API    │         │      Локальная БД SQLite    │
-│ • Free Dictionary API       │         │ • users (аккаунт, пароль)   │
-│   (IPA, audio, definitions) │         │ • vocabulary_cards          │
-│ • MyMemory / Translation    │         │ • sessions (активные входы) │
-│   (русский перевод фразы)   │         │ • tags & categories         │
-└─────────────────────────────┘         └─────────────────────────────┘
+│              Docker Container: study-ollama                 │
+│  • Qwen 2.5 3B Instruct (контекстный перевод предложений    │
+│    и педагогический дебрифинг уроков)                       │
+└─────────────────────────────────────────────────────────────┘
 ```

-### Выбор технологий:
- **Безопасность**: Защищённые сессии (Signed HTTP-only cookie `SameSite=Lax`, `Secure`). Защита от CSRF, XSS и брутфорс-атак через встроенный rate limiter.
- **Backend**: Python 3.12 + FastAPI (асинхронный, легковесный, моментальный старт).
- **База данных**: SQLite в режиме `WAL` (Write-Ahead Logging). Идеальная транзакционная надежность, автономность, бэкап в один файл.
- **Frontend**: Чистый Vanilla ES6+ / Modern CSS / HTML5. Мгновенная загрузка (< 50 мс), оффлайн-кэш, адаптивность (смартфон + десктоп), поддержка хоткеев.
- **Внешние API (Zero-cost & Open)**:
-  1. *Free Dictionary API* (`api.dictionaryapi.dev`): фонетическая транскрипция IPA, аудио-произношение нативных дикторов (US/UK), части речи, толкования и примеры.
-  2. *MyMemory Translation API*: литературный перевод фраз, идиом и предложений на русский язык.
+---
+
+## 2. Реализованные этапы развития (Completed Roadmap)
+
+### ✅ Этап 1: Защищённое ядро (MVP) и базовый словарь
+- [x] Авторизация на сессионных куках (`HttpOnly`, `SameSite=Lax`, `Secure`).
+- [x] Хэширование паролей `PBKDF2-HMAC-SHA256` с уникальной солью на пользователя.
+- [x] Rate limiting для предотвращения атак перебором.
+- [x] Офлайн-словарь (140k+ записей) с каскадным переводом.
+- [x] Сохранение слов с контекстным предложением и горячими клавишами (`Ctrl+Enter`).
+- [x] Журнал личного словаря, поиск, фильтрация по тегам и коллекциям.
+
+### ✅ Этап 2: Организация, экспорт и PWA
+- [x] Коллекции и теги, разбивка слов по категориям.
+- [x] Пакетные операции над карточками (массовое перемещение, удаление, добавление тегов).
+- [x] Экспорт данных в форматы: CSV, JSON, Anki TSV и Markdown.
+- [x] PWA-манифест и Service Worker для офлайн-доступа к приложению.
+
+### ✅ Этап 3: Алгоритм интервальных повторений (SRS SM-2) и тренажер
+- [x] Реализация математической модели SuperMemo SM-2 (Ease Factor, Repetitions, Intervals).
+- [x] 3D-флип карточки с градацией оценок (Снова, Трудно, Хорошо, Легко).
+- [x] Режим Smart Quiz (выбор из 4 вариантов с дистракторами из той же части речи).
+- [x] Режим активного ввода (Active Typing) с набором английского слова по русскому переводу.
+- [x] Smart Daily Mix: сбалансированная подборка (10 новых + 10 повторов + 5 проблемных слов).
+- [x] Детекция проблемных слов (Leeches) и повторный фокус на них.
+- [x] Аналитика: календарь активности (Heatmap 180 дней), стрик дней, процент удержания (Retention Rate), оценка уровня CEFR.
+
+### ✅ Этап 4: Интерактивная читалка и книжная полка
+- [x] Поддержка книг и документов: EPUB, PDF, TXT, Markdown (`.md`).
+- [x] Автоматический сборщик стандартов IETF RFC по номеру или URL.
+- [x] Интеграция с Wikipedia: автономная загрузка статей с очисткой верстки под тайм-бюджет.
+- [x] Интерактивный клик-перевод каждого слова с выводом контекста.
+- [x] Добавление слова и цитаты в словарь в 1 клик прямо из текста.
+- [x] Непрерывное чтение (continuous scroll) с карточками перехода между главами.
+- [x] Темы оформления (Light, Dark, Sepia, Night, Parchment, Hacker) и типографика.
+
+### ✅ Этап 5: Автономный локальный ИИ (Ollama) и нейро-озвучка (Piper)
+- [x] Развертывание локального контейнера Ollama с моделью `qwen2.5:3b`.
+- [x] Контекстный перевод предложений с учетом целевого слова и сохранением в кэш SQLite.
+- [x] Локальный VITS-синтез речи Piper TTS (US Lessac, RU Dmitri) с нулевой задержкой.
+- [x] Фоновое пред-кэширование произношения слов и предложений при добавлении в словарь.
+- [x] Тренажёр аудирования (Listening) с проверкой понимания.
+
+### ✅ Этап 6: Грамматика Murphy & Тестирование CEFR
+- [x] 260 интерактивных заданий Cloze Tap по международным уровням A1–B2.
+- [x] Автоматическая gap-ингестия: отправка ошибочных слов из тестов в активный тренажёр SRS.
+- [x] Фоновый воркер майнинга тестов из загруженной литературы.
+- [x] 15 базовых юнитов грамматики Murphy с формулами и теорией.
+- [x] Синхронизация с рукописным бумажным конспектом.
+
+### ✅ Этап 7: Конструктор комплексного урока & Сессионный раннер
+- [x] Единый конструктор ежедневного урока: блоки слов (Flashcards/Quiz/Typing/Dictation), грамматики, аудирования, чтения.
+- [x] Встроенные готовые шаблоны (Экспресс, Сбалансированный, Глубокий, Аудио+Чтение).
+- [x] Адаптивный подбор темы грамматики («Самая слабая тема по ошибкам», «Предыдущая тема»).
+- [x] Сквозная телеметрия ошибок сессии и интеллектуальный ИИ-дебрифинг от Qwen 2.5 3B.
+- [x] Детерминированный фолбэк для мгновенного завершения сессии при выключенной Ollama.
+
+### ✅ Этап 8: Глубокий технический рефакторинг и оптимизация (Beta-refactor)
+- [x] **Этап 1 рефакторинга**: Удаление мертвого кода (`parse_text`), оптимизация SQL в фоновых задачах.
+- [x] **Этап 2 рефакторинга**: Вынос 3 100+ строк захардкоженных датасетов в `data/seeds/*.json`.
+- [x] **Этап 3 рефакторинга**: Keep-Alive пул соединений для Ollama (120s), офлайн-лемматизация в словаре.
+- [x] **Этап 4 рефакторинга**: Модуляризация бэкенда (`app/main.py` сокращён с 2 240 до 142 строк, создано 11 APIRouters).
+- [x] **Этап 5 рефакторинга**: Модуляризация CSS (`style.css` 8 746 строк разделен на 7 предметных файлов, обновлён прекэш SW v6.7).
+- [x] 100% покрытие авто-тестами: 44/44 тестов проходят в Docker.

 ---

-## 2. Этапы реализации (Roadmap)
-
-### Этап 1 (Текущая итерация): Безопасное ядро (MVP) — Общий английский, перевод и фиксация
-*Цель: создать защищённый, сверхбыстрый и надёжный персональный словарь для повседневного и профессионального английского языка.*
-
- [x] **1.1. Модуль защиты и авторизации**:
-  - Страница авторизации (минималистичный дизайн, вход по логину и паролю).
-  - Защита всех API эндпоинтов: неавторизованные запросы блокируются (`401 Unauthorized`).
-  - Надежное хранение паролей в SQLite (`PBKDF2-HMAC-SHA256` с уникальной солью).
-  - Rate Limiter на эндпоинт `/api/login` (не более 5 неудачных попыток в минуту с IP).
-  - Сессии через зашифрованные `HttpOnly` cookie.
-  - Кнопка «Выйти из аккаунта» в шапке сервиса.
- [x] **1.2. Быстрый поиск и каскадный перевод (General & Idiomatic English)**:
-  - Строка поиска в фокусе сразу при открытии страницы.
-  - Поддержка любых форм языка:
-    - Отдельные слова (существительные, глаголы, прилагательные);
-    - Фразовые глаголы (*run into*, *figure out*, *call off*);
-    - Идиомы и разговорные фразы (*once in a blue moon*, *take for granted*);
-    - Предложения целиком (из книг, сериалов, документации).
-  - Автоматическое получение:
-    - Фонетической транскрипции (IPA);
-    - Нативного аудио-произношения (US/UK);
-    - Частей речи и толкования на английском;
-    - Русского перевода.
-  - Кэширование словарных запросов в локальной базе для мгновенных повторных ответов.
- [x] **1.3. Контекстное сохранение слова в 1 клик**:
-  - Горячие клавиши:
-    - `Enter` — мгновенный перевод;
-    - `Ctrl + Enter` (или `Cmd + Enter`) — мгновенное сохранение в словарь;
-    - `Esc` — очистить ввод;
-    - `Ctrl + P` или клик на динамик — прослушать произношение.
-  - Возможность подправить перевод перед сохранением под свой контекст.
-  - Поле для ввода контекстного предложения (где встретилось слово/выражение).
-  - Выбор/ввод тегов (`#general`, `#phrasal-verb`, `#idiom`, `#daily`, `#networking`).
- [x] **1.4. Журнал личного словаря (History & Words List)**:
-  - Хронологическая лента всех сохраненных слов с датой и временем.
-  - Живой поиск по английским словам, русскому переводу и контексту.
-  - Фильтр по тегам в один клик.
-  - Воспроизведение аудио прямо из списка.
-  - Удаление / редактирование карточек.
- [x] **1.5. Инфраструктурное развертывание**:
-  - Конфигурация Nginx для `notes.qpid.pro` с proxy на бэкенд (`127.0.0.1:8002`).
-  - Systemd-сервис для автозапуска и перезапуска при сбоях.
-
---
-
-### Этап 2: Организация, теги, экспорт и PWA
-*Цель: гибкое управление растущим словарным запасом и удобство на мобильных.*
-
- [x] **2.1. Расширенная организация и контроль качества**:
-  - Коллекции и папки (например, «Разговорный», «Работа», «Книги/Сериалы», «Сети/IT»).
-  - Быстрое массовое тегирование и групповые действия (удаление, перемещение).
-  - **Контроль и предотвращение дубликатов (Duplicate Prevention & Merging)**:
-    - Проверка при вводе и сохранении (case-insensitive trim).
-    - Уведомление, если слово/фраза уже есть в словаре.
-    - Возможность дописать новый контекстный пример / значение к существующей карточке вместо пложения дублей или перейти к её редактированию.
- [x] **2.2. Экспорт данных**:
-  - Экспорт базы в CSV (UTF-8 BOM), JSON, Markdown.
-  - Экспорт в колоду Anki (`.tsv`) с аудио, контекстными предложениями и поддержкой Cloze deletion (`{{c1::word}}`).
- [x] **2.3. PWA (Progressive Web App)**:
-  - Установка на экран смартфона (iOS / Android) как нативное приложение.
-  - Service Worker, Web Manifest, оффлайн-кэш статики.
-
---
-
-### Этап 3: Встроенный тренажер интервальных повторений (SRS / SM-2)
-*Цель: перевод слов из пассивного словаря в активную долговременную память.*
-
- [x] **3.1. Движок SuperMemo-2 (SM-2) & Умная выборка**:
-  - Расчет интервалов забывания Эббингауза: `Again`, `Hard`, `Good`, `Easy`.
-  - **Умный микс дня (Daily Quiz Mix)**: баланс сессии (до 10 новых + 10 интервальных повторений + 5 проблемных слов в разнобой).
-  - **Детектор трудных слов (Leeches)**: автоматическая маркировка слов с частыми ошибками и их приоритетное подмешивание.
- [x] **3.2. Режим Flashcards**:
-  - Двусторонняя карточка En $\rightarrow$ Ru и Ru $\rightarrow$ EN с нативной озвучкой, подсказкой контекста и горячими клавишами `Space`, `1..4`.
- [x] **3.3. Режим Multiple Choice Quiz (4 варианта ответа)**:
-  - Выбор правильного перевода среди 4 вариантов со случайными дистракторами из базы.
-  - Мгновенная проверка, подсветка цветом (зеленый/красный) и горячие клавиши `1..4`.
- [x] **3.4. Режим активного набора (Active Typing / Ru $\rightarrow$ En)**:
-  - Видишь русский перевод / контекст с пропуском $\rightarrow$ вводишь английское слово с клавиатуры (прокачка моторной памяти и спеллинга).
- [x] **3.5. Режим Cloze Deletion (Контекстные пропуски)**:
-  - Заполнение пропущенного слова прямо в живом предложении.
- [x] **3.6. Аудио-тренажёр (Dictation)**:
-  - Слушаем слово $\rightarrow$ печатаем правильный спеллинг.
-
---
-
-### Этап 4: Интеллектуальный помощник и аналитика
-*Цель: отслеживание динамики и поддержка мотивации.*
-
- [x] **4.1. Статистика, Daily Streak и Календарь активности**:
-  - Сетка активности за 180 дней с градацией интенсивности (серый, салатовый, зеленый, изумрудный).
-  - Учёт непрерывных дней занятий (Daily Streak 🔥) и рекорда серии.
-  - Сегментированный прогресс-бар стадий освоения (Новые, В процессе, Закрепление, Выучено).
-  - Оценка уровня владения языком (A1 - C1) по объёму активного словаря.
-  - Процент точности запоминания (Retention Rate %).
- [ ] **4.2. Быстрый захват из браузера**:
-  - Букмарклет для выделения текста на любой странице и отправки в словарь.
- [x] **4.3. Честный и строгий расчёт уровня CEFR (Active Vocabulary & Retention Weighting)**:
-  - Расчёт уровня владения исключительно по **активным выученным словам** (стадии `Mastered` и `Review` в алгоритме SM-2), исключая пассивные добавленные карточки, которые ещё не прошли интервальные повторения.
-  - Корректирующий коэффициент точности: учёт Retention Rate %, чтобы уровень отражал реальную память, а не просто количество выписанных слов.
-  - Индикатор пути к следующему уровню (например: «*До уровня B2 осталось закрепить 142 слова*»).
-
---
-
-### Этап 5: Интерактивная Читалка & Библиотека (Interactive Reader & Source-based Learning)
-*Цель: чтение живых книг, статей и документации с мгновенным клик-переводом и авто-тегированием источников.*
-
- [x] **5.1. Хранилище текстов и парсер форматов (Bookshelf & Document Engine)**:
-  - Поддержка форматов: вставка текста из буфера, `.txt`, `.md`, электронные книги `.epub` (с разбивкой по главам и сохранением позиции чтения).
-  - Умная очистка веб-статей от лишней верстки и рекламы (Reader view).
- [x] **5.2. Автоматическое тегирование источников (Source & Metadata Auto-tagging)**:
-  - Каждое слово, сохранённое из книги/статьи, автоматически получает теги источника:
-    - Название произведения (например, `#fight-club`, `#the-martian`, `#designing-data-intensive-apps`).
-    - Тип/жанр материала (например, `#novel`, `#tech-article`, `#documentation`, `#cybersecurity`).
-    - Автор / Источник (например, `#author:chuck-palahniuk`, `#cloudflare-blog`).
-  - Автоматический захват предложения-контекста, в котором слово встретилось в книге.
- [x] **5.3. Запуск тестов и тренировок по источникам и тегам (Tag-scoped SRS Quizzes)**:
-  - Возможность запустить любую тренировку (Карточки, 4 варианта ответа, Набор слова, Диктант) **строго по словам конкретной книги, статьи или автора**.
-  - Быстрый запуск из читалки: *«Повторить все 35 новых слов из Fight Club»* прямо во время или после прочтения главы.
- [x] **5.4. Интерактивный клик-перевод и подсветка (Interactive Reader Layer)**:
-  - Клик по любому слову $\rightarrow$ моментальный перевод, транскрипция, нативное аудио и кнопка «+ В словарь» в 1 клик.
-  - Выделение фраз/связок (chunks) мышкой или тапом с литературным переводом всего выражения.
-  - Подсветка в тексте книги уже выученных (`mastered`) и изучаемых (`learning`) слов.
+## 3. Ближайшие планы и вектор развития (Future Enhancements)

+1. **Браузерный букмарклет для захвата слов**:
+   - Минималистичный JS-скрипт для браузера, позволяющий по клику отправить выделенное слово и контекст страницы в личный словарь `study.qpid.pro`.
+2. **HTML5 Web Speech API fallback**:
+   - Дополнительный запасной канал озвучивания через встроенный `window.speechSynthesis` при мобильном режиме без связи.
+3. **Расширение библиотеки Murphy**:
+   - Постепенное расширение учебных юнитов грамматики с 15 до 30+ тем (Passive Voice, Reported Speech, Phrasal Verbs in Context).
+4. **Адаптивные интервалы по времени суток**:
+   - Учёт утренних и вечерних окон повторения в сессионном раннере для максимальной концентрации.