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

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

---

## 1. Архитектура и стек решений

```
┌─────────────────────────────────────────────────────────────┐
│                       notes.qpid.pro                        │
│             (Nginx Reverse Proxy + Let's Encrypt)           │
└──────────────────────────────┬──────────────────────────────┘
                               │ proxy_pass :8002
┌──────────────────────────────▼──────────────────────────────┐
│                    Backend: Python 3.12                     │
│    FastAPI / Uvicorn + SQLite (WAL mode) + Dictionary APIs  │
└──────────────────────────────┬──────────────────────────────┘
                               │
       ┌───────────────────────┴───────────────────────┐
       ▼                                               ▼
┌─────────────────────────────┐         ┌─────────────────────────────┐
│     Внешние открытые API    │         │      Локальная БД SQLite    │
│ • Free Dictionary API       │         │ • vocabulary_cards          │
│   (IPA, audio, definitions) │         │ • search_history            │
│ • MyMemory / Context Trans. │         │ • srs_reviews (SM-2)        │
│   (перевод на русский)      │         │ • tags & categories         │
└─────────────────────────────┘         └─────────────────────────────┘
```

### Выбор технологий:
- **Backend**: Python 3.12 + FastAPI (асинхронный, лёгкий, типизированный, мгновенный запуск).
- **База данных**: SQLite в режиме `WAL` (Write-Ahead Logging). Полная транзакционность, нулевые затраты на администрирование, бэкап копированием одного файла.
- **Frontend**: Vanilla ES6+ / Modern CSS / HTML5. Без тяжелых бандлеров и node_modules. Адаптивный мобильный интерфейс (PWA), оффлайн-кэш на LocalStorage/CacheStorage, поддержка хоткеев.
- **Внешние API (Zero-cost & Open)**:
  1. *Free Dictionary API* (`api.dictionaryapi.dev`): официальная фонетическая транскрипция IPA, аудио-файлы нативного произношения (US/UK), английские определения и примеры.
  2. *MyMemory Translated API*: качественный перевод фраз и предложений на русский язык.

---

## 2. Этапы реализации (Roadmap)

### Этап 1: Ядро системы (MVP) — Быстрый поиск, перевод и фиксация
*Цель: закрыть боль переключения контекста при чтении документации.*

- [ ] **1.1. Базовый интерфейс ввода**:
  - Строка поиска в фокусе при открытии страницы.
  - Горячие клавиши:
    - `Enter` — мгновенный перевод.
    - `Ctrl + Enter` (или `Cmd + Enter`) — сохранить карточку.
    - `Esc` — очистить поле ввода.
    - `Ctrl + P` (или пробел на карточке) — воспроизвести аудио-произношение.
- [ ] **1.2. Каскадный переводчик (Backend API)**:
  - Автоопределение ввода: отдельное слово или предложение/фраза.
  - Запрос словарных данных (транскрипция, аудио mp3, толкование, русский перевод).
  - Кэширование запросов в локальной SQLite для мгновенного повторного показа.
- [ ] **1.3. Контекстное сохранение**:
  - Поле для ввода контекстного предложения (откуда взято слово).
  - Быстрый выбор тега (по умолчанию `#networking`, `#general`, `#protocol`).
  - Возможность подправить перевод перед сохранением.
- [ ] **1.4. Журнал истории и база слов**:
  - Хронологическая лента сохраненных слов с датой и временем.
  - Поиск и фильтрация по сохранённым словам.
  - Мгновенное удаление / редактирование.

---

### Этап 2: Организация, теги и экспорт
*Цель: структурирование профессионального глоссария инженера.*

- [ ] **2.1. Система тегов и коллекций**:
  - Тегирование по направлениям: `#routing`, `#switching`, `#security`, `#bgp`, `#linux-kernel`, `#troubleshooting`.
  - Фильтрация в один клик.
- [ ] **2.2. Экспорт данных**:
  - Экспорт в CSV / Markdown.
  - Экспорт готовой колоды для Anki (`.csv` / `.apkg`) с аудио и контекстом.
  - Резервное копирование базы данных в 1 клик.
- [ ] **2.3. PWA (Progressive Web App)**:
  - Возможность установки на смартфон / десктоп как самостоятельное приложение.
  - Работа со списком слов в режиме оффлайн.

---

### Этап 3: Встроенный тренажер интервальных повторений (SRS / SM-2)
*Цель: гарантированное запоминание без необходимости устанавливать сторонние программы.*

- [ ] **3.1. Движок алгоритма SuperMemo-2 (SM-2)**:
  - Расчет фактора легкости (Ease Factor, $EF$).
  - Очередь повторений на сегодня: карточки со статусом `Due`.
  - 4 кнопки оценки:
    - `Again` (< 10 минут)
    - `Hard` (+12 часов)
    - `Good` (+1 день $\rightarrow$ +3 дня $\rightarrow$ +7 дней...)
    - `Easy` (+4 дня $\rightarrow$ геометрическая прогрессия)
- [ ] **3.2. Режим карточек (Flashcards)**:
  - Лицевая сторона: английский термин + аудио.
  - Оборотная сторона: русский перевод + контекстное предложение + определение.
- [ ] **3.3. Режим Cloze Deletion (Вставка пропущенного слова)**:
  - Мозг тренируется вспоминать термин прямо в техническом предложении:
    > *"The switch [ ... ] the packet if the VLAN tag is invalid."*
- [ ] **3.4. Аудио-диктант (Active Spelling)**:
  - Сервис проигрывает произношение термина, пользователь печатает его на слух.

---

### Этап 4: Профессиональный инструментарий сетевого инженера
*Цель: превратить сервис в персонального ментора по сетевому английскому.*

- [ ] **4.1. Встроенный сетевой глоссарий и акронимы**:
  - База популярных сетевых акронимов и аббревиатур (MTU, MSS, BFD, ECMP, CIDR, STP, SYN/ACK) с расшифровкой и техническим смыслом.
- [ ] **4.2. Статистика и аналитика прогресса**:
  - Счётчик дней непрерывного обучения (Daily Streak).
  - График объёма активного словарного запаса.
  - Коэффициент удержания памяти (% успешно вспомненных слов).
- [ ] **4.3. Быстрый захват из браузера**:
  - Букмарклет (Bookmarklet) для выделения слова на любой веб-странице документации и мгновенной отправки в `notes.qpid.pro`.

---

## 3. Критерии качества («Автомат Калашникова»)
1. **Скорость**: Открытие страницы $< 100$ мс, поиск $< 300$ мс.
2. **Отказоустойчивость**: Если внешний API словаря недоступен, сервис предлагает ручной ввод без блокировки интерфейса.
3. **Безопасность данных**: Данные хранятся в надежной локальной SQLite, регулярный автоматический snapshot базы.
4. **Удобство**: Управление полностью доступно с клавиатуры (без необходимости тянуться к мыши).