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

docs(plan): update roadmap with security layer (auth, sessions, rate-limit) and general english scope

Browse Source
This commit is contained in:
Antigravity
2026-09-22 13:09:18 +00:00
parent 4631de5391
commit 4dbc53890a
3 changed files with 152 additions and 159 deletions
Download Patch File Download Diff File Expand all files Collapse all files
PLAN.md
+89 -77
View File
@@ -1,18 +1,28 @@
# План развития проекта Notes (notes.qpid.pro)
> **Принцип проектирования**: *«Работает как автомат Калашникова»* — сверхнадёжно, мгновенно, без раздутых зависимостей и необходимости постоянного ручного обслуживания.
> **Принцип проектирования**: *«Работает как автомат Калашникова»* — сверхнадёжно, мгновенно, защищено для публичного интернета, без раздутых зависимостей и постоянного ручного обслуживания.
---
## 1. Архитектура и стек решений
## 1. Архитектура и защита системы
Сервис разворачивается на публичном сервере с белым IP (`31.77.203.213`). Вся система проектируется с учётом сетевой безопасности и изоляции личных данных.
```
┌─────────────────────────────────────────────────────────────┐
│ notes.qpid.pro │
│ (Nginx Reverse Proxy + Let's Encrypt) │
│ 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 │
└──────────────────────────────┬──────────────────────────────┘
@@ -21,104 +31,106 @@
▼ ▼
┌─────────────────────────────┐ ┌─────────────────────────────┐
│ Внешние открытые API │ │ Локальная БД SQLite │
│ • Free Dictionary API │ │ • vocabulary_cards │
│ (IPA, audio, definitions) │ │ • search_history │
│ • MyMemory / Context Trans. │ │ • srs_reviews (SM-2) │
│ (перевод на русский) │ │ • tags & categories │
│ • Free Dictionary API │ │ • users (аккаунт, пароль) │
│ (IPA, audio, definitions) │ │ • vocabulary_cards │
│ • MyMemory / Translation │ │ • sessions (активные входы) │
│ (русский перевод фразы) │ │ • tags & categories │
└─────────────────────────────┘ └─────────────────────────────┘
```
### Выбор технологий:
- **Backend**: Python 3.12 + FastAPI (асинхронный, лёгкий, типизированный, мгновенный запуск).
- **База данных**: SQLite в режиме `WAL` (Write-Ahead Logging). Полная транзакционность, нулевые затраты на администрирование, бэкап копированием одного файла.
- **Frontend**: Vanilla ES6+ / Modern CSS / HTML5. Без тяжелых бандлеров и node_modules. Адаптивный мобильный интерфейс (PWA), оффлайн-кэш на LocalStorage/CacheStorage, поддержка хоткеев.
- **Безопасность**: Защищённые сессии (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 Translated API*: качественный перевод фраз и предложений на русский язык.
1. *Free Dictionary API* (`api.dictionaryapi.dev`): фонетическая транскрипция IPA, аудио-произношение нативных дикторов (US/UK), части речи, толкования и примеры.
2. *MyMemory Translation API*: литературный перевод фраз, идиом и предложений на русский язык.
---
## 2. Этапы реализации (Roadmap)
### Этап 1: Ядро системы (MVP) — Быстрый поиск, перевод и фиксация
*Цель: закрыть боль переключения контекста при чтении документации.*
### Этап 1 (Текущая итерация): Безопасное ядро (MVP) — Общий английский, перевод и фиксация
*Цель: создать защищённый, сверхбыстрый и надёжный персональный словарь для повседневного и профессионального английского языка.*
- [ ] **1.1. Базовый интерфейс ввода**:
- Строка поиска в фокусе при открытии страницы.
- [ ] **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` (или пробел на карточке) — воспроизвести аудио-произношение.
- [ ] **1.2. Каскадный переводчик (Backend API)**:
- Автоопределение ввода: отдельное слово или предложение/фраза.
- Запрос словарных данных (транскрипция, аудио mp3, толкование, русский перевод).
- Кэширование запросов в локальной SQLite для мгновенного повторного показа.
- [ ] **1.3. Контекстное сохранение**:
- Поле для ввода контекстного предложения (откуда взято слово).
- Быстрый выбор тега (по умолчанию `#networking`, `#general`, `#protocol`).
- Возможность подправить перевод перед сохранением.
- [ ] **1.4. Журнал истории и база слов**:
- Хронологическая лента сохраненных слов с датой и временем.
- Поиск и фильтрация по сохранённым словам.
- Мгновенное удаление / редактирование.
- `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: Организация, теги и экспорт
*Цель: структурирование профессионального глоссария инженера.*
### Этап 2: Организация, теги, экспорт и PWA
*Цель: гибкое управление растущим словарным запасом и удобство на мобильных.*
- [ ] **2.1. Система тегов и коллекций**:
- Тегирование по направлениям: `#routing`, `#switching`, `#security`, `#bgp`, `#linux-kernel`, `#troubleshooting`.
- Фильтрация в один клик.
- [ ] **2.1. Расширенная организация**:
- Коллекции и папки (например, «Разговорный», «Работа», «Книги/Сериалы», «Сети/IT»).
- Быстрое массовое тегирование.
- [ ] **2.2. Экспорт данных**:
- Экспорт в CSV / Markdown.
- Экспорт готовой колоды для Anki (`.csv` / `.apkg`) с аудио и контекстом.
- Резервное копирование базы данных в 1 клик.
- Экспорт базы в CSV / JSON / Markdown.
- Экспорт в колоду Anki (`.apkg` / `.csv`) с аудио и контекстными предложениями.
- Резервное копирование SQLite в один клик.
- [ ] **2.3. PWA (Progressive Web App)**:
- Возможность установки на смартфон / десктоп как самостоятельное приложение.
- Работа со списком слов в режиме оффлайн.
- Установка на экран смартфона (iOS / Android) как нативное приложение.
- Оффлайн-доступ к сохранённым словам.
---
### Этап 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)**:
- Сервис проигрывает произношение термина, пользователь печатает его на слух.
- [ ] **3.1. Движок SuperMemo-2 (SM-2)**:
- Расчет интервалов забывания Эббингауза: `Again`, `Hard`, `Good`, `Easy`.
- Очередь на сегодня: карточки, готовые к повторению.
- [ ] **3.2. Режим Flashcards**:
- Карточка En $\rightarrow$ Ru и Ru $\rightarrow$ En с озвучкой.
- [ ] **3.3. Режим Cloze Deletion (Пропуски)**:
- Заполнение пропущенного слова прямо в живом предложении.
- [ ] **3.4. Аудио-тренажёр (Dictation)**:
- Слушаем слово $\rightarrow$ печатаем правильный спеллинг.
---
### Этап 4: Профессиональный инструментарий сетевого инженера
*Цель: превратить сервис в персонального ментора по сетевому английскому.*
### Этап 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. **Удобство**: Управление полностью доступно с клавиатуры (без необходимости тянуться к мыши).
- [ ] **4.1. Статистика и Daily Streak**:
- Учёт непрерывных дней занятий.
- График роста активного словарного запаса по уровням (A1-C1).
- [ ] **4.2. Быстрый захват из браузера**:
- Букмарклет для выделения текста на любой странице и отправки в словарь.