Antigravity/notes-qpid-pro
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Antigravity
2026-10-07 15:20:44 +03:00
parent c89b0d6238
commit 03c692fe43
6 changed files with 351 additions and 240 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.gitignore
+1
View File
@@ -19,6 +19,7 @@ data/audio_cache/
data/*.db
data/*.db-wal
data/*.db-shm
data/*.backup*
# Environment & Secret variables
.env
GEMINI.md
+5 -3
View File
@@ -1,11 +1,13 @@
# Workspace Context & English Mentor Rules
# Workspace Context & English Mentor Rules: study.qpid.pro
> This file is automatically discovered by the Antigravity agent in this workspace.
## English Mentor & Tech Pair Programmer Role
- The assistant acts as a dedicated **English Language Mentor** and **Senior Software Engineer** working on `notes.qpid.pro`.
- Full mentor instructions, pedagogical framework, and project session context are maintained in [MENTOR_CONTEXT.md](file:///home/kopri/notes.qpid.pro/MENTOR_CONTEXT.md), [PEDAGOGY.md](file:///home/kopri/notes.qpid.pro/PEDAGOGY.md), and [PLAN.md](file:///home/kopri/notes.qpid.pro/PLAN.md).
- The assistant acts as a dedicated **English Language Mentor** and **Senior Software Engineer** working on `study.qpid.pro`.
- Full mentor instructions, pedagogical framework, and project session context are maintained in [MENTOR_CONTEXT.md](MENTOR_CONTEXT.md), [PEDAGOGY.md](PEDAGOGY.md), [PLAN.md](PLAN.md), and [README.md](README.md).
- When discussing vocabulary or practicing English:
- Focus on the **Lexical Approach** (chunks, collocations, idiomatic usage).
- Provide IPA transcriptions, pronunciation tips, and realistic contextual examples.
- Give constructive, encouraging feedback and natural phrasing improvements.
- When working on codebase:
- Follow the **Ponytail principles**: minimal code, standard library & native platform features first, 100% test passing (`pytest tests/test_api.py`), offline-first resilience.
MENTOR_CONTEXT.md
+23 -47
View File
@@ -1,15 +1,15 @@
# 🎓 Mentor Context & Session State: English & notes.qpid.pro
# 🎓 Mentor Context & Session State: English & study.qpid.pro
> **Файл контекста сессии и роли ментора по английскому языку**
> Ссылка на проект: [notes.qpid.pro](https://notes.qpid.pro)
> Директория проекта: `/home/kopri/notes.qpid.pro`
> Ссылка на проект: [study.qpid.pro](https://study.qpid.pro)
> Директория проекта: `/home/ai-projects/services/study.qpid.pro`
> Назначение файла: хранение роли ментора, педагогических принципов, архитектурного контекста и прогресса студента.
---
## 🧑‍🏫 Роль: Твой персональный ментор по английскому языку
Ты выступаешь в роли **опытного, поддерживающего и практико-ориентированного ментора по английскому языку** с сильным фокусом на IT/Tech и живую разговорную речь.
Ты выступаешь в роли **опытного, поддерживающего и практико-ориентированного ментора по английскому языку** с сильным фокусом на IT/Tech, живую разговорную речь и методику *Comprehensible Input*.
### Ключевые функции ментора:
1. **Разбор лексики и устойчивых выражений (The Lexical Approach)**:
@@ -22,31 +22,32 @@
4. **Тактичная коррекция ошибок (Constructive Feedback)**:
- Если пользователь пишет на английском с ошибкой, мягко показать естественный вариант (natural phrasing) и объяснить причину.
5. **Интерактивные тренировки**:
- Генерировать карточки, упражнения с пропусками (Cloze deletions), квизы на идиомы и фразовые глаголы для добавления в сервис `notes.qpid.pro`.
- Генерировать карточки, упражнения с пропусками (Cloze deletions), квизы на идиомы и фразовые глаголы для добавления в сервис `study.qpid.pro`.
---
## 📱 О проекте `notes.qpid.pro`
## 📱 О проекте `study.qpid.pro`
- **Что это**: Защищённый персональный тренажёр и словарь английского языка (PWA / Web-сервис).
- **Сайт**: [https://notes.qpid.pro](https://notes.qpid.pro) (IP: `31.77.203.213`)
- **Что это**: Защищённый персональный тренажёр, читалка и словарь английского языка (PWA / Docker / Web-сервис).
- **Сайт**: [https://study.qpid.pro](https://study.qpid.pro)
- **Репозиторий**: [ai.qpid.pro/gitea/Antigravity/notes-qpid-pro](https://ai.qpid.pro/gitea/Antigravity/notes-qpid-pro)
- **Техстек**:
- Backend: Python 3.12 (FastAPI, Uvicorn, SQLite WAL)
- Frontend: Vanilla JS / Modern CSS / HTML5 PWA (без тяжёлых фреймворков)
- Сервер: Nginx Reverse Proxy + SSL Let's Encrypt + Systemd
- Безопасность: PBKDF2 пароли, HttpOnly Cookies, CSRF/Rate Limiter
- Интеграции: Free Dictionary API (IPA + audio), MyMemory API
- Backend: Python 3.12 (FastAPI, Uvicorn, SQLite WAL, 11 модульных APIRouters)
- Frontend: Vanilla JS / Modern CSS (7 предметных таблиц) / HTML5 PWA (Service Worker v6.7)
- Сервер: Docker, Nginx Reverse Proxy, SSL Let's Encrypt
- Локальный ИИ: Ollama + Qwen 2.5 3B (контекстный перевод предложений, педагогический дебрифинг уроков)
- Озвучка: Piper Neural TTS (чистый нативный голос VITS без внешних API)
- Тестирование: 44/44 проходящих интеграционных теста в Pytest.
---
## 🧠 5 Золотых педагогических принципов проекта
1. **Лексические блоки (Chunks)**: Учить готовые связки, а не отдельные слова.
2. **Контекстный якорь**: Каждое слово сохраняется в предложении из реальной ситуации.
3. **Фонетический якорь (IPA + Audio)**: Закрепление звучания на слух, исключение субвокализации с ошибками.
4. **Интервальные повторения (SRS / SM-2)**: Повторение по кривой забывания Эббингауза (1, 2, 5, 12, 28, 65 дней).
5. **Активное припоминание (Active Recall)**: Двусторонние карточки + упражнения с пропусками.
2. **Контекстный якорь**: Каждое слово сохраняется в предложении из реальной ситуации (книга, статья, фильм).
3. **Фонетический якорь (IPA + Neural Audio)**: Закрепление звучания на слух, исключение субвокализации с ошибками.
4. **Интервальные повторения (SRS / SM-2)**: Повторение по кривой забывания Эббингауза (1, 6, $I \times EF$ дней) с интерливингом (Smart Daily Mix).
5. **Активное припоминание (Active Recall)**: Двусторонние 3D-карточки, умный квиз, активный набор текста руками и упражнения Cloze Tap.
---
@@ -55,7 +56,7 @@
Когда ты начинаешь новый диалог или хочешь активировать этот режим, просто напиши:
- `Вспомни контекст ментора MENTOR_CONTEXT.md` или `Работай по MENTOR_CONTEXT.md`
- `Проверь мое предложение на английском: "..."`
- `Разбери слово/идиому "..." (транскрипция, примеры, связки, карточка для notes.qpid.pro)`
- `Разбери слово/идиому "..." (транскрипция, примеры, связки, карточка для study.qpid.pro)`
- `Дай 5 полезных phrasal verbs для IT/dev на сегодня`
- `Давай попрактикуем диалог на английском на тему ...`
@@ -66,32 +67,7 @@
| Дата | Тема / Фокус | Ключевые концепции | Статус |
| :--- | :--- | :--- | :--- |
| *Инициализация* | Запуск проекта notes.qpid.pro & MVP | SRS, Lexical approach, Contextual anchoring | Выполнено |
| `2026-09-23` | Стратегия начитки тех. текстов (Extensive Reading) & Умные тесты | Чтение без упора на грамматику (85-90% Comprehensible input), выжимка связок (chunks), умный микс в тестах (Новые + Повтор + Проблемные/Leeches), активный ввод Ru->En | Зафиксировано, переход к чтению |
---
## 🎯 Сформулированные требования к умному тренажеру (Smart Daily Quiz)
1. **Сбалансированная сессия на день (Smart Mix)**:
- ~10 новых добавленных слов (New)
- ~10 слов по интервальной очереди (Review / Due SRS)
- ~5 проблемных слов (Leeches / High-error rate)
- Случайное перемешивание (shuffled) в одной тренировке.
2. **Проблемные слова (Leech Detection)**:
- Автоматическая маркировка карточек с частыми ошибками и повышение частоты их появления.
3. **Режим активного ввода (Active Typing / Production)**:
- Показ русского значения / контекста с пропуском $\rightarrow$ набор правильного английского слова руками для моторной памяти и спеллинга.
4. **Контроль дубликатов при пополнении словаря (Duplicate Prevention & Merging)**:
- При добавлении слова/фразы проверять наличие в словаре.
- Вместо создания дубликата предлагать дополнить существующую карточку новым примером контекста/значением или отредактировать её.
5. **Строгая оценка уровня владения (Active CEFR Vocabulary Weighting)** *(В планах)*:
- Считать уровень не по общему числу карточек, а по реальному активному объёму: слова в статусах `Mastered` (интервал > 21 дня) и `Review` с весовыми коэффициентами.
- Учитывать Retention Rate % как множитель уверенности.
- Показывать индикатор прогресса (сколько слов осталось выучить до следующего уровня).
6. **Интерактивная читалка и авто-тегирование источников (Reader & Source-scoped Learning)** *(В планах)*:
- Автоматическое присвоение тегов при сохранении из читалки: `#название-книги`, `#жанр`, `#автор`.
- Запуск любых SRS-тренировок и квизов с фильтром по тегу источника (например, повторить только слова из *Fight Club* или *Clean Code*).
- Подсветка в тексте книги уже изучаемых и выученных слов, перевод фраз/chunks при выделении.
| `2026-09-23` | Стратегия начитки тех. текстов (Extensive Reading) & Умные тесты | Чтение без упора на грамматику (85-90% Comprehensible input), выжимка связок (chunks), умный микс в тестах (Новые + Повтор + Leeches), активный ввод Ru->En | Выполнено |
| `2026-10-06` | Интеграция читалки (EPUB/PDF/RFC/Wikipedia) & Piper TTS | Офлайн-читалка, IETF RFC стандарты, Wikipedia статьи, локальная нейро-озвучка Piper | Выполнено |
| `2026-10-07` | Murphy Grammar, CEFR Cloze Tap & Комплексный урок | 15 юнитов Мерфи, тесты A1–B2, gap-ингестия, конструктор уроков, сессионный раннер, ИИ-дебрифинг Qwen 2.5 3B | Выполнено |
| `2026-10-07` | Полный рефакторинг архитектуры (5 этапов) | Модуляризация бэкенда (11 роутеров), вынос датасетов в JSON (-3100 строк), модульные CSS, Keep-Alive пул Ollama | Выкачено на прод study.qpid.pro |
PLAN.md
+92 -156
View File
@@ -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. **Адаптивные интервалы по времени суток**:
- Учёт утренних и вечерних окон повторения в сессионном раннере для максимальной концентрации.
README.md
+202 -29
View File
@@ -1,46 +1,219 @@
# Notes (notes.qpid.pro)
# Study Qpid (study.qpid.pro)
> **Защищённый персональный тренажёр и словарь английского языка.**
> Создан для быстрого и надёжного расширения словарного запаса (общий английский, фразовые глаголы, идиомы, профессиональные термины) без отвлечения от чтения и просмотра контента.
> **Автономный персональный тренажёр и интерактивная языковая среда английского языка.**
> Создан для быстрого и надёжного расширения активного словарного запаса, автоматизации грамматики и беглого чтения технической и художественной литературы с поддержкой локального искусственного интеллекта (Ollama) и локального синтеза речи (Piper TTS) без внешних платных API.
---
## 🎯 Концепция и методика
Чтение статей, книг или просмотр видео на английском часто тормозится незнакомыми словами и выражениями. Обычный переводчик даёт мгновенный ответ, но слово сразу забывается. Ручные списки превращаются в «кладбище информации».
## 🎯 Концепция и философия системы
Проект решает эту проблему по принципу **«автомата Калашникова»**:
1. **Безопасность**: сервис работает на белом IP, защищён авторизацией (сессии, хэширование паролей, защита от брутфорса).
2. **Мгновенный поиск и перевод**: фокус на строке ввода, каскадный перевод (словарная статья + толкование + русский перевод).
3. **Контекстный якорь**: сохранение слова вместе с живым предложением (где встретилось выражение).
4. **Фонетическое закрепление**: нативное аудио-произношение (US/UK) и транскрипция IPA.
5. **Интервальные повторения (SRS / SM-2)**: встроенные карточки для перевода слов в долговременную память.
Традиционное изучение языка разбивается о разрозненность: словарь в одном приложении, карточки в другом, книги в третьем, а грамматика в тетрадке.
**Study Qpid** объединяет весь цикл в единый закрытый контур по принципу **«автомата Калашникова»**:
1. **100% автономность и приватность**: веб-сервис развернут в Docker, защищён строгой авторизацией (сессии HttpOnly, хэширование PBKDF2-HMAC-SHA256, rate limiting). Локальный ИИ (Qwen 2.5 3B) и синтез речи (Piper) работают полностью на собственном сервере без передачи данных сторонним компаниям.
2. **Контекстный якорь и лексический подход**: слова изучаются в готовых блоках (*chunks*) и живых предложениях из прочитанных книг и документации.
3. **Многомодальный интервальный тренажер (SRS SM-2)**: 5 различных режимов работы с карточками (3D Flashcards, умная викторина с дистракторами по частям речи, активный ввод Typing, аудио-диктант, аудирование Q&A).
4. **Интерактивная читалка**: мгновенный перевод кликом по слову, захват предложений в карточки в 1 клик, поддержка форматов EPUB, PDF, TXT, Markdown, спецификаций IETF RFC и статей Wikipedia.
5. **Грамматический трек Murphy & CEFR**: 15 базовых юнитов грамматики с формулами, связка с бумажной рабочей тетрадью, 260 интерактивных тестов Cloze Tap и автоматическая отправка ошибок в активную очередь повторений.
6. **Конструктор комплексного урока**: единый сессионный раннер, собирающий ежедневный урок из слов, грамматики, аудирования, чтения и завершающийся педагогическим разбором ошибок от локальной нейросети.
---
## 📂 Документация проекта
## 🚀 Основной реализованный функционал
- 📚 [**Источники бесплатных книг (BOOKS_SOURCES.md)**](BOOKS_SOURCES.md) — проверенные каталоги адаптированных книг (A1–C1) и оригинальной классики в EPUB/TXT для читалки.
- 📋 [**План функционала и архитектура (PLAN.md)**](PLAN.md) — детальный план итераций: от защищённого MVP до умных интервальных тренажёров.
- 🎓 [**Методология и педагогика (PEDAGOGY.md)**](PEDAGOGY.md) — методические правила эффективного освоения языка: лексические связки (chunks), контекст, фонетика, кривая забывания Эббингауза.
- ✅ [**Очередь задач и бэклог (TODO.md)**](TODO.md) — текущий статус реализации оптимизаций и фичей.
### 1. 🔍 Контекстный словарь и поиск
* **Локальная словарная база**: более 140 000 словарных статей в SQLite, дополненных морфологическим анализатором (лемматизация инфлексий `starts` → `start`, `studying` → `study`).
* **Детектор фразовых глаголов и идиом**: при поиске слова в контексте предложения система автоматически определяет устойчивые связки (*look forward to*, *run into*, *figure out*) и предлагает сохранить именно целостное выражение.
* **Каскадный перевод**: офлайн-словарь + транскрипция IPA + толкование на английском + русский перевод.
* **Управление базой**: разбивка по коллекциям (*General*, *IT/Tech*, *Phrasal Verbs* и др.), система тегов, быстрый поиск и фильтрация, пакетные операции (перемещение, тегирование, удаление).
### 2. 🧠 Локальный ИИ (Ollama & Qwen 2.5 3B)
* **Контекстный перевод предложений**: перевод предложения с фокусом на точное значение целевого слова в данном контексте через локальную LLM (`qwen2.5:3b`).
* **Кэширование переводов**: все сгенерированные переводы сохраняются в SQLite (`sentence_translations`) с моментальной отдачей при повторных запросах.
* **Педагогический дебрифинг урока**: анализ ошибок сессии, определение паттернов (путаница времен, предлогов), рекомендации и выставление объективной оценки сессии.
* **Отказоустойчивость**: постоянный пул соединений с Keep-Alive (120s) в FastAPI lifespan; при недоступности Ollama система мгновенно переключается на детерминированный математический отчёт без зависаний.
### 3. 🔊 Автономная нейро-озвучка (Piper TTS)
* **Локальный VITS-инференс**: чистый нативный звук дикторов без внешних запросов к облакам (`en_US-lessac`, `ru_RU-dmitri` + поддержка альтернативных дикторов).
* **Проактивное фоновое пред-кэширование**: при добавлении слова в словарь аудиозапись слова и контекста синтезируется сервером в фоне, обеспечивая нулевую задержку при повторении в тренажере.
* **Аудио в читалке**: озвучивание отдельных слов, целых предложений оригинала и русского перевода.
### 4. 🎓 Тренажёр интервальных повторений (SRS SM-2)
* **Алгоритм SuperMemo SM-2**: адаптивный расчёт интервалов (1, 6, $I \times EF$ дней) на основе оценок пользователя (Снова, Трудно, Хорошо, Легко).
* **5 специализированных режимов повторений**:
1. *3D Flashcards* — классические двусторонние карточки с 3D-анимацией переворота.
2. *Smart Quiz* — множественный выбор из 4 вариантов с автоматическим подбором правдоподобных дистракторов из той же части речи.
3. *Active Typing* — активная продукция: печать английского слова по русскому переводу и контексту с пропуском.
4. *Audio Dictation* — аудиотренажёр: прослушивание произношения через Piper TTS и ввод слова на слух.
5. *Listening Comprehension* — интерактивные аудио-сценарии с вопросами на проверку понимания.
* **Smart Daily Mix**: сбалансированная ежедневная тренировка (10 новых слов + 10 плановых повторений + 5 проблемных слов-личей, перемешанных для интерливинга).
* **Аналитика и визуализация**: GitHub-style календарь активности за 180 дней, подсчёт непрерывного стрика, распределение по статусам (New, Learning, Review, Mastered), расчёт Retention Rate и оценка словарного уровня по CEFR.
### 5. 📚 Интерактивная читалка и библиотека
* **Поддержка форматов**: загрузка книг в форматах EPUB, PDF, TXT, Markdown (`.md`).
* **Импорт RFC-спецификаций**: загрузка технических стандартов IETF RFC по номеру или URL с автоматической разбивкой на структурированные главы.
* **Интеграция с Wikipedia**: автономный импорт статей по названию, теме и доступному бюджету времени на чтение.
* **Интерактивный клик-перевод**: каждое слово кликабельно с показом всплывающей карточки (на десктопе — всплывающее окно у курсора, на смартфоне — удобный Bottom Sheet).
* **Непрерывное чтение**: бесконечный скролл с навигационными карточками завершения глав, автоматическое сохранение позиции чтения (`current_chapter`, `current_position`).
* **Типографика и темы**: 6 цветовых схем (Light, Dark, Sepia, Night, Parchment, Hacker), регулировка ширины страницы, межстрочного интервала и шрифтов (Georgia, Inter, JetBrains Mono).
### 6. 🏆 Тесты CEFR (A1–B2) & Автоматическая Gap-ингестия
* **260 интерактивных заданий Cloze Tap**, распределённых по международным уровням владения языком (A1, A2, B1, B2).
* **Автоматическое устранение пробелов (Gap Ingestion)**: любая допущенная ошибка в тесте мгновенно конвертируется в словарную карточку и отправляется в активную очередь SRS со статусом `learning`.
* **Фоновый майнер тестов из книг**: асинхронный фоновый воркер для автоматического извлечения тестовых заданий из загруженных пользователем книг с фильтрацией по целевому уровню CEFR.
### 7. 📖 Грамматический трек Murphy & Тетрадь
* **15 базовых юнитов** классической методики Raymond Murphy (*Essential Grammar in Use*).
* **Структура каждого юнита**:
- Карточка юнита со статусом освоения и баллом.
- Полноэкранный теоретический модуль с формулами образования, русскими объяснениями и маркерами времени.
- 5 интерактивных упражнений Cloze Tap с мгновенной проверкой.
* **Интеграция с бумажным конспектом**: чекбокс ручной фиксации упражнений в физической тетради для задействования моторной памяти.
### 8. ⚡ Конструктор комплексного урока & Сессионный раннер
* **Гибкая структура занятия**: настройка порядка этапов, переключение тумблеров активности, выбор объема слов и упражнений.
* **Готовые пресеты**:
- ⚡ *Утренний экспресс (10 мин)*
- 🎯 *Сбалансированный урок (20 мин)*
- 📖 *Глубокое погружение (30 мин)*
- 🎧 *Аудио + Чтение (15 мин)*
- Возможность сохранения собственных шаблонов в базу SQLite.
* **Умный подбор грамматики**: адаптивный выбор темы грамматики на основе истории ошибок («Самая слабая тема», «Предыдущая тема» или ручной выбор).
* **Сквозной раннер**: бесшовный интерфейс с таймером, прогресс-баром и финальным ИИ-дебрифингом.
---
## 🛠 Технический стек
## 🛠 Техническая архитектура и стек
- **Backend**: Python 3.12 (FastAPI / Uvicorn)
- **Database**: SQLite (WAL mode — надёжность, автономность, бэкап в один файл)
- **Безопасность**: Защищённые сессии (HttpOnly cookies), PBKDF2-HMAC-SHA256, Rate Limiting
- **Frontend**: Vanilla HTML5 / Modern CSS / ES6+ JavaScript (PWA, горячие клавиши, мгновенный отклик)
- **Внешние API**: Free Dictionary API (IPA + audio), MyMemory Translation API
- **Веб-сервер**: Nginx Reverse Proxy + SSL Let's Encrypt (`notes.qpid.pro`)
- **Репозиторий проекта**: [Gitea (ai.qpid.pro/gitea/Antigravity/notes-qpid-pro)](https://ai.qpid.pro/gitea/Antigravity/notes-qpid-pro)
```
https://study.qpid.pro
│
┌──────────────────▼──────────────────┐
│ Nginx (Host SSL / Reverse Proxy) │
└──────────────────┬──────────────────┘
│ :8002
┌─────────────────────────────────────────▼────────────────────────────────────────┐
│ Docker Container: study-qpid-pro │
│ │
│ ┌──────────────────────────────────────────────────────────────────────────┐ │
│ │ FastAPI Application (app/main.py) │ │
│ │ • GZipMiddleware (≥1000B) • Security Headers Middleware │ │
│ │ • Persistent Lifespan Pool • Service Worker Static Precache (v6.7) │ │
│ └─────────────────────────────────────┬────────────────────────────────────┘ │
│ │ │
│ ┌─────────────────────────────────────▼────────────────────────────────────┐ │
│ │ Модульные APIRouters │ │
│ │ • auth.py • cards.py • dictionary.py • srs.py │ │
│ │ • reader.py • cefr.py • grammar.py • lessons.py │ │
│ │ • listening.py • tasks.py • export.py │ │
│ └─────────────────┬───────────────────┬──────────────────┬─────────────────┘ │
│ │ │ │ │
│ ┌─────────────────▼─────────┐ ┌───────▼────────┐ ┌───────▼─────────────────┐ │
│ │ SQLite WAL (data/notes) │ │ Piper TTS │ │ Seed Datasets (JSON) │ │
│ │ • Memory-Mapped I/O │ │ • Offline VITS │ │ • cefr_questions.json │ │
│ │ • Full Schema Integrity │ │ • Zero-Latency │ │ • grammar_units.json │ │
│ │ • Sub-millisecond reads │ │ • Voice Cache │ │ • phrasal_verbs.json │ │
│ └───────────────────────────┘ └────────────────┘ └─────────────────────────┘ │
└─────────────────────────────────────────┬────────────────────────────────────────┘
│ http://ollama:11434
┌─────────────────────────────────────────▼────────────────────────────────────────┐
│ Docker Container: study-ollama │
│ • Model: Qwen 2.5 3B Instruct (GGUF) │
│ • Connection Pool with Keep-Alive (120s) │
└──────────────────────────────────────────────────────────────────────────────────┘
```
* **Backend**: Python 3.12, FastAPI, Uvicorn, Pydantic v2.
* **База данных**: SQLite в режиме `WAL` (Write-Ahead Logging) с `mmap_size = 256MB` и индексами по внешним ключам и выражениям.
* **Frontend**: Vanilla ES6+ модули, HTML5 PWA, CSS-переменные (7 предметных таблиц стилей), поддержка offline через Service Worker.
* **AI & TTS**: Ollama (`qwen2.5:3b`), Piper Neural TTS (локальный бинарник).
* **Тестирование**: Pytest + TestClient (44 автоматических интеграционных теста).
---
## 🌐 Информация об окружении
## 📁 Структура проекта
- **URL сервиса**: [https://notes.qpid.pro](https://notes.qpid.pro)
- **IP сервера**: `31.77.203.213`
- **Каталог проекта**: [`/home/kopri/notes.qpid.pro`](file:///home/kopri/notes.qpid.pro)
- **Git Remote**: `http://127.0.0.1:3000/Antigravity/notes-qpid-pro.git`
```
study.qpid.pro/
├── app/
│ ├── main.py # Лаконичная точка входа FastAPI (lifespan, middleware, роутеры)
│ ├── auth.py # Безопасность, хэширование PBKDF2, сессии, rate limiting
│ ├── config.py # Переменные окружения и системные пути
│ ├── database.py # Инициализация SQLite WAL, индексы, миграции
│ ├── dictionary.py # Поиск в офлайн-словаре, лемматизация, каскадные запросы
│ ├── ai.py # Интеграция с Ollama (Keep-Alive пул, промпты, дебрифинг)
│ ├── tts.py # Синтез речи Piper TTS и управление кэшем аудио
│ ├── srs.py # SM-2 интервалы, викторины, аналитика, тепловая карта
│ ├── reader.py # Парсеры EPUB, PDF, TXT, Markdown, RFC и Wikipedia
│ ├── cefr.py # Уровневое тестирование A1–B2 и gap-ингестия
│ ├── grammar.py # Движок Murphy Grammar и журнал конспектов
│ ├── lessons.py # Конструктор уроков, пресеты, история сессий
│ ├── listening.py # Сценарии аудирования и оценка ответов
│ ├── miner.py # Фоновый майнинг предложений из литературы
│ ├── tasks.py # Управление фоновыми задачами SQLite
│ ├── export.py # Экспорт базы (CSV, JSON, Anki, Markdown)
│ ├── routers/ # Модульные роутеры FastAPI (11 файлов)
│ └── static/ # Статика веб-приложения
│ ├── index.html # Одностраничное приложение (PWA Shell)
│ ├── sw.js # Service Worker (кэширование v6.7)
│ ├── manifest.json # PWA-манифест
│ ├── css/ # Модульная таблица стилей
│ │ ├── style.css # Мастер-файл со структурой и @import
│ │ ├── base.css # Токены, темы, сброс, safe-areas
│ │ ├── components.css # Навбар, меню, кнопки, модалки, таб-бар
│ │ ├── dictionary.css # Поиск, карточки слов, коллекции, теги
│ │ ├── srs.css # Карточки 3D, квизы, ввод, аналитика
│ │ ├── reader.css # Читалка, темы оформления, Wikipedia
│ │ ├── grammar_cefr.css # CEFR и юниты Murphy
│ │ └── lesson.css # Конфигуратор и раннер уроков
│ └── js/ # ES6 модули фронтенда
│ ├── app.js # Точка входа SPA, роутинг, хоткеи
│ └── modules/ # Модули логики (ui, api, dictionary, srs, reader, cefr, grammar, lesson)
├── data/
│ ├── notes.db # Основная база данных SQLite
│ ├── offline_dict.tsv.gz # Локальный словарь (140k+ записей)
│ ├── audio_cache/ # Кэш предсинтезированных WAV-файлов
│ └── seeds/ # Кураторские JSON-датасеты (CEFR, Murphy, Phrasal, Articles)
├── scripts/
│ ├── deploy_beta.sh # Развертывание бета-ветки в 1 клик
│ ├── rollback_to_main.sh # Мгновенный откат на стабильный main
│ └── build_offline_dict.py # Сборщик офлайн-словаря
├── tests/
│ └── test_api.py # Набор интеграционных тестов (44 теста)
├── docker-compose.yml # Декларация контейнеров study-web и ollama
└── Dockerfile # Образ веб-приложения на Python 3.12-slim
```
---
## 🚀 Развёртывание и запуск
### Запуск через Docker Compose (Рекомендуемый)
```bash
# Клонирование репозитория
git clone https://ai.qpid.pro/gitea/Antigravity/notes-qpid-pro.git
cd notes-qpid-pro
# Запуск связки веб-сервера и локальной Ollama
DOCKER_HOST=tcp://127.0.0.1:2375 docker compose up -d
# Запуск тестов внутри контейнера
DOCKER_HOST=tcp://127.0.0.1:2375 docker exec -i -e PYTHONPATH=. study-qpid-pro pytest tests/test_api.py
```
### Управление ветками и откат:
```bash
# Быстрый переход на бета-версию:
./scripts/deploy_beta.sh
# Мгновенный откат на стабильную ветку main:
./scripts/rollback_to_main.sh
```
---
## 📄 Лицензия и статус проекта
* Проект разрабатывается в активной фазе для повседневного практического освоения языка.
* 100% открытый исходный код без проприетарных платных облачных зависимостей.
TODO.md
+28 -5
View File
@@ -447,16 +447,39 @@
---
### 20. 🏗️ Комплексный технический рефакторинг и оптимизация архитектуры (Completed)
- [x] **Этап 1: Очистка мертвого кода и оптимизация SQL**:
- Удалена старая незавершенная функция `parse_text` в `app/reader.py` (строки 290–326).
- Функция `update_task_progress` в `app/tasks.py` переписана с цикла на единый параметризованный SQL-запрос `UPDATE tasks SET progress = ?, current_item = ?, ...`.
- [x] **Этап 2: Вынос датасетов в JSON (`data/seeds/*.json`)**:
- Из исходников извлечено более 3 100 строк статических данных: `cefr_questions.json` (260 вопросов), `grammar_units.json` (15 юнитов), `phrasal_verbs.json` (157 глаголов), `reading_articles.json` (8 статей).
- Модули `app/cefr.py`, `app/grammar.py`, `app/phrasal.py`, `app/lessons.py` переведены на динамическую ленивую загрузку с сохранением полной обратной совместимости.
- [x] **Этап 3: Оптимизация сети и локального ИИ**:
- Внедрен постоянный пул соединений `httpx.AsyncClient` с Keep-Alive (120s) для локальной Ollama в `app/ai.py`, управляемый в жизненном цикле приложения (`lifespan`).
- Интегрирована встроенная офлайн-лемматизация (`lemmatize_word`) в `lookup_term` (`app/dictionary.py`), предотвращающая лишние сетевые запросы при поиске словоформ (`starts` -> `start`, `studying` -> `study`).
- [x] **Этап 4: Модуляризация бэкенда FastAPI**:
- Монолитный `app/main.py` сокращен с 2 240 до 142 строк.
- Создан пакет `app/routers/` с 11 тематическими APIRouter: `auth.py`, `cards.py`, `dictionary.py`, `srs.py`, `export.py`, `reader.py`, `cefr.py`, `grammar.py`, `tasks.py`, `lessons.py`, `listening.py`.
- [x] **Этап 5: Модуляризация CSS и Service Worker**:
- Монолитный `style.css` (8 746 строк) разделен на 7 предметных таблиц в `app/static/css/`: `base.css`, `components.css`, `dictionary.css`, `srs.css`, `reader.css`, `grammar_cefr.css`, `lesson.css`.
- Мастер-файл `style.css` загружает стили через `@import` и содержит полную архитектурную карту.
- Обновлен Service Worker (`notes-v6.7`) с добавлением всех CSS в `PRECACHE_URLS` для полной офлайн-работы PWA.
- [x] **Инфраструктура быстрого переключения и отката**:
- Добавлены скрипты `scripts/deploy_beta.sh` и `scripts/rollback_to_main.sh` для мгновенного отката или развертывания в 1 клик.
- Создан резервный бэкап базы данных `data/notes.db.backup-main-pre-beta`.
- [x] **100% успешное тестирование**:
- Все 44 интеграционных теста `pytest tests/test_api.py` успешно проходят в Docker-контейнере.
---
## ⏳ Coming Soon
- [ ] **🌐 Быстрый захват из браузера (Bookmarklet)**:
- Создать JavaScript-букмарклет для добавления слова/фразы из любого окна браузера в личный словарь [`study.qpid.pro`](https://study.qpid.pro) (низший приоритет).
- [ ] **Нативная автономная озвучка (HTML5 Web Speech API / `speechSynthesis`)**:
- Использовать встроенный в браузер синтезатор речи `window.speechSynthesis` (en-US, en-GB).
- 0 сетевых запросов к серверу, 100% оффлайн-работа.
- Поддержка озвучивания отдельных слов, фраз, идиом и предложений-контекстов читалки.
- [ ] **Возврат режима «Диктант» в SRS**:
- Возобновление работы аудиотренажёра на базе нативного браузерного синтезатора речи без зависимости от внешних аудиофайлов.
- Использовать встроенный в браузер синтезатор речи `window.speechSynthesis` (en-US, en-GB) как дополнительный резервный фолбэк при работе на мобильных без связи.
- [ ] **Расширение библиотеки Murphy**:
- Добавление следующих 15 юнитов грамматики (юниты 16–30: пассивный залог, косвенная речь, модальные глаголы).
---