Antigravity/notes-qpid-pro
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1db9356e0c2f6eaf3ab7dc4e8be228053c77a6d4
notes-qpid-pro/PLAN.md
T

17 KiB
Raw Blame History

План развития проекта Notes (notes.qpid.pro)

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

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

Сервис разворачивается на публичном сервере с белым IP (31.77.203.213). Вся система проектируется с учётом сетевой безопасности и изоляции личных данных.

┌─────────────────────────────────────────────────────────────┐
│                       notes.qpid.pro                        │
│            Nginx (HTTPS / Let's Encrypt / Security Headers) │
└──────────────────────────────┬──────────────────────────────┘
                               │ proxy_pass :8002
┌──────────────────────────────▼──────────────────────────────┐
│                    Слой безопасности (Auth)                 │
│  • Аутентификация: сессионные токены (HTTP-only cookies)    │
│  • Хэширование паролей: PBKDF2-HMAC-SHA256 (соль + 100k)   │
│  • Защита от перебора (Rate Limiter: макс 5 попыток/мин)    │
│  • Закрытый доступ: все эндпоинты требуют авторизации       │
└──────────────────────────────┬──────────────────────────────┘
                               │
┌──────────────────────────────▼──────────────────────────────┐
│                    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         │
└─────────────────────────────┘         └─────────────────────────────┘

Выбор технологий:

  • Безопасность: Защищённые сессии (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. Этапы реализации (Roadmap)

Этап 1 (Текущая итерация): Безопасное ядро (MVP) — Общий английский, перевод и фиксация

Цель: создать защищённый, сверхбыстрый и надёжный персональный словарь для повседневного и профессионального английского языка.

  • 1.1. Модуль защиты и авторизации:
    • Страница авторизации (минималистичный дизайн, вход по логину и паролю).
    • Защита всех API эндпоинтов: неавторизованные запросы блокируются (401 Unauthorized).
    • Надежное хранение паролей в SQLite (PBKDF2-HMAC-SHA256 с уникальной солью).
    • Rate Limiter на эндпоинт /api/login (не более 5 неудачных попыток в минуту с IP).
    • Сессии через зашифрованные HttpOnly cookie.
    • Кнопка «Выйти из аккаунта» в шапке сервиса.
  • 1.2. Быстрый поиск и каскадный перевод (General & Idiomatic English):
    • Строка поиска в фокусе сразу при открытии страницы.
    • Поддержка любых форм языка:
      • Отдельные слова (существительные, глаголы, прилагательные);
      • Фразовые глаголы (run into, figure out, call off);
      • Идиомы и разговорные фразы (once in a blue moon, take for granted);
      • Предложения целиком (из книг, сериалов, документации).
    • Автоматическое получение:
      • Фонетической транскрипции (IPA);
      • Нативного аудио-произношения (US/UK);
      • Частей речи и толкования на английском;
      • Русского перевода.
    • Кэширование словарных запросов в локальной базе для мгновенных повторных ответов.
  • 1.3. Контекстное сохранение слова в 1 клик:
    • Горячие клавиши:
      • Enter — мгновенный перевод;
      • Ctrl + Enter (или Cmd + Enter) — мгновенное сохранение в словарь;
      • Esc — очистить ввод;
      • Ctrl + P или клик на динамик — прослушать произношение.
    • Возможность подправить перевод перед сохранением под свой контекст.
    • Поле для ввода контекстного предложения (где встретилось слово/выражение).
    • Выбор/ввод тегов (#general, #phrasal-verb, #idiom, #daily, #networking).
  • 1.4. Журнал личного словаря (History & Words List):
    • Хронологическая лента всех сохраненных слов с датой и временем.
    • Живой поиск по английским словам, русскому переводу и контексту.
    • Фильтр по тегам в один клик.
    • Воспроизведение аудио прямо из списка.
    • Удаление / редактирование карточек.
  • 1.5. Инфраструктурное развертывание:
    • Конфигурация Nginx для notes.qpid.pro с proxy на бэкенд (127.0.0.1:8002).
    • Systemd-сервис для автозапуска и перезапуска при сбоях.

Этап 2: Организация, теги, экспорт и PWA

Цель: гибкое управление растущим словарным запасом и удобство на мобильных.

  • 2.1. Расширенная организация и контроль качества:
    • Коллекции и папки (например, «Разговорный», «Работа», «Книги/Сериалы», «Сети/IT»).
    • Быстрое массовое тегирование и групповые действия (удаление, перемещение).
    • Контроль и предотвращение дубликатов (Duplicate Prevention & Merging):
      • Проверка при вводе и сохранении (case-insensitive trim).
      • Уведомление, если слово/фраза уже есть в словаре.
      • Возможность дописать новый контекстный пример / значение к существующей карточке вместо пложения дублей или перейти к её редактированию.
  • 2.2. Экспорт данных:
    • Экспорт базы в CSV (UTF-8 BOM), JSON, Markdown.
    • Экспорт в колоду Anki (.tsv) с аудио, контекстными предложениями и поддержкой Cloze deletion ({{c1::word}}).
  • 2.3. PWA (Progressive Web App):
    • Установка на экран смартфона (iOS / Android) как нативное приложение.
    • Service Worker, Web Manifest, оффлайн-кэш статики.

Этап 3: Встроенный тренажер интервальных повторений (SRS / SM-2)

Цель: перевод слов из пассивного словаря в активную долговременную память.

  • 3.1. Движок SuperMemo-2 (SM-2) & Умная выборка:
    • Расчет интервалов забывания Эббингауза: Again, Hard, Good, Easy.
    • Умный микс дня (Daily Quiz Mix): баланс сессии (до 10 новых + 10 интервальных повторений + 5 проблемных слов в разнобой).
    • Детектор трудных слов (Leeches): автоматическая маркировка слов с частыми ошибками и их приоритетное подмешивание.
  • 3.2. Режим Flashcards:
    • Двусторонняя карточка En \rightarrow Ru и Ru \rightarrow EN с нативной озвучкой, подсказкой контекста и горячими клавишами Space, 1..4.
  • 3.3. Режим Multiple Choice Quiz (4 варианта ответа):
    • Выбор правильного перевода среди 4 вариантов со случайными дистракторами из базы.
    • Мгновенная проверка, подсветка цветом (зеленый/красный) и горячие клавиши 1..4.
  • 3.4. Режим активного набора (Active Typing / Ru \rightarrow En):
    • Видишь русский перевод / контекст с пропуском \rightarrow вводишь английское слово с клавиатуры (прокачка моторной памяти и спеллинга).
  • 3.5. Режим Cloze Deletion (Контекстные пропуски):
    • Заполнение пропущенного слова прямо в живом предложении.
  • 3.6. Аудио-тренажёр (Dictation):
    • Слушаем слово \rightarrow печатаем правильный спеллинг.

Этап 4: Интеллектуальный помощник и аналитика

Цель: отслеживание динамики и поддержка мотивации.

  • 4.1. Статистика, Daily Streak и Календарь активности:
    • Сетка активности за 180 дней с градацией интенсивности (серый, салатовый, зеленый, изумрудный).
    • Учёт непрерывных дней занятий (Daily Streak 🔥) и рекорда серии.
    • Сегментированный прогресс-бар стадий освоения (Новые, В процессе, Закрепление, Выучено).
    • Оценка уровня владения языком (A1 - C1) по объёму активного словаря.
    • Процент точности запоминания (Retention Rate %).
  • 4.2. Быстрый захват из браузера:
    • Букмарклет для выделения текста на любой странице и отправки в словарь.
  • 4.3. Честный и строгий расчёт уровня CEFR (Active Vocabulary & Retention Weighting):
    • Расчёт уровня владения исключительно по активным выученным словам (стадии Mastered и Review в алгоритме SM-2), исключая пассивные добавленные карточки, которые ещё не прошли интервальные повторения.
    • Корректирующий коэффициент точности: учёт Retention Rate %, чтобы уровень отражал реальную память, а не просто количество выписанных слов.
    • Индикатор пути к следующему уровню (например: «До уровня B2 осталось закрепить 142 слова»).

Этап 5: Интерактивная Читалка & Библиотека (Interactive Reader & Source-based Learning)

Цель: чтение живых книг, статей и документации с мгновенным клик-переводом и авто-тегированием источников.

  • 5.1. Хранилище текстов и парсер форматов (Bookshelf & Document Engine):
    • Поддержка форматов: вставка текста из буфера, .txt, .md, электронные книги .epub (с разбивкой по главам и сохранением позиции чтения).
    • Умная очистка веб-статей от лишней верстки и рекламы (Reader view).
  • 5.2. Автоматическое тегирование источников (Source & Metadata Auto-tagging):
    • Каждое слово, сохранённое из книги/статьи, автоматически получает теги источника:
      • Название произведения (например, #fight-club, #the-martian, #designing-data-intensive-apps).
      • Тип/жанр материала (например, #novel, #tech-article, #documentation, #cybersecurity).
      • Автор / Источник (например, #author:chuck-palahniuk, #cloudflare-blog).
    • Автоматический захват предложения-контекста, в котором слово встретилось в книге.
  • 5.3. Запуск тестов и тренировок по источникам и тегам (Tag-scoped SRS Quizzes):
    • Возможность запустить любую тренировку (Карточки, 4 варианта ответа, Набор слова, Диктант) строго по словам конкретной книги, статьи или автора.
    • Быстрый запуск из читалки: «Повторить все 35 новых слов из Fight Club» прямо во время или после прочтения главы.
  • 5.4. Интерактивный клик-перевод и подсветка (Interactive Reader Layer):
    • Клик по любому слову \rightarrow моментальный перевод, транскрипция, нативное аудио и кнопка «+ В словарь» в 1 клик.
    • Выделение фраз/связок (chunks) мышкой или тапом с литературным переводом всего выражения.
    • Подсветка в тексте книги уже выученных (mastered) и изучаемых (learning) слов.
Reference in new issue View Git Blame Copy Permalink