From 03c692fe4389cfc7be96ea45313a1a301c28d413 Mon Sep 17 00:00:00 2001 From: Antigravity Date: Wed, 7 Oct 2026 15:20:44 +0300 Subject: [PATCH] docs: update README, PLAN, TODO, MENTOR_CONTEXT with full implemented functionality and architecture --- .gitignore | 1 + GEMINI.md | 8 +- MENTOR_CONTEXT.md | 70 +++++-------- PLAN.md | 248 +++++++++++++++++----------------------------- README.md | 231 ++++++++++++++++++++++++++++++++++++------ TODO.md | 33 +++++- 6 files changed, 351 insertions(+), 240 deletions(-) diff --git a/.gitignore b/.gitignore index 5f6cce3..ef22bac 100644 --- a/.gitignore +++ b/.gitignore @@ -19,6 +19,7 @@ data/audio_cache/ data/*.db data/*.db-wal data/*.db-shm +data/*.backup* # Environment & Secret variables .env diff --git a/GEMINI.md b/GEMINI.md index a12545a..f33fb50 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -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. diff --git a/MENTOR_CONTEXT.md b/MENTOR_CONTEXT.md index fc1413e..5cae50c 100644 --- a/MENTOR_CONTEXT.md +++ b/MENTOR_CONTEXT.md @@ -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 | diff --git a/PLAN.md b/PLAN.md index 2bbffd9..1e02e34 100644 --- a/PLAN.md +++ b/PLAN.md @@ -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. **Адаптивные интервалы по времени суток**: + - Учёт утренних и вечерних окон повторения в сессионном раннере для максимальной концентрации. diff --git a/README.md b/README.md index a9d83d0..552e348 100644 --- a/README.md +++ b/README.md @@ -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% открытый исходный код без проприетарных платных облачных зависимостей. diff --git a/TODO.md b/TODO.md index d814850..abab95d 100644 --- a/TODO.md +++ b/TODO.md @@ -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: пассивный залог, косвенная речь, модальные глаголы). ---