commit 4631de53913f277cc006c29ea88d37acd1f6b90c Author: Antigravity Date: Tue Sep 22 12:51:36 2026 +0000 docs(init): initialize repository, roadmap plan, and pedagogical guide for network english diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..6364c5b --- /dev/null +++ b/.gitignore @@ -0,0 +1,35 @@ +# Python +__pycache__/ +*.py[cod] +*$py.class +.venv/ +venv/ +ENV/ + +# Database +*.sqlite3 +*.sqlite +*.db +*.db-journal +*.db-wal +*.db-shm + +# Environment & Secret variables +.env +.env.local +*.secret + +# Logs +*.log +logs/ + +# Backups +*.bak +backups/ + +# OS / Editor +.DS_Store +Thumbs.db +.idea/ +.vscode/ +*.swp diff --git a/PEDAGOGY.md b/PEDAGOGY.md new file mode 100644 index 0000000..0c01b5c --- /dev/null +++ b/PEDAGOGY.md @@ -0,0 +1,76 @@ +# Методология и педагогическая концепция проекта + +> **Цель**: Быстро, качественно и без стресса вывести чтение и понимание технической англоязычной литературы (RFC, вендорная документация Cisco/Juniper, Linux networking, сетевые протоколы) на уровень свободного владения. + +--- + +## 1. В чём главная проблема традиционного подхода? + +Студенты и инженеры, читая техническую документацию, регулярно сталкиваются с двумя ловушками: + +1. **Разрыв фокуса (Context Switching Friction)**: + Встретив незнакомое слово (*deprecate*, *overhead*, *stale*, *propagate*), инженер переключается в переводчик, читает перевод, возвращается к тексту. Теряется мысль статьи, процесс чтения превращается в мучение. +2. **«Кладбище слов» (Passive Word Graveyard)**: + Если слово записывается в блокнот или текстовый файл, оно никогда не повторяется по правильной кривой памяти. Пассивный список из 100 слов бесполезен: через неделю мозг помнит максимум 10–15% из них. +3. **Изолированный перевод без доменного контекста**: + В сетевых технологиях слова имеют специфические значения: + - *Stale* (не «чёрствый», а «устаревший/неактуальный маршрут»); + - *Drop* (не просто «уронить», а «отбросить пакет»); + - *Graceful* (не «изящный», а «корректный/штатный останов сервиса без потери данных»); + - *Flapping* (не «хлопанье крыльями», а «нестабильное падение и подъем интерфейса/маршрута»). + +--- + +## 2. Пять золотых правил методики + +### Правило 1. Лексический подход и коллокации (The Lexical Approach) +*Мозг думает не отдельными словами, а блоками (chunks).* +- Не учите изолированное `overhead` — учите `encapsulation overhead`. +- Не учите изолированное `handshake` — учите `three-way handshake`. +- Не учите изолированное `bottleneck` — учите `throughput bottleneck`. +В сервисе сохраняется не просто голое слово, а **готовое терминологическое словосочетание**. + +### Правило 2. Контекстный якорь (Contextual Anchoring) +*Память работает через ассоциации.* +Когда вы сохраняете слово вместе с реальным предложением из статьи или RFC: +> *"The router drops the packet due to TTL expiration."* +Ваш мозг связывает слово `drop` с конкретным сетевым процессом (TTL, router, packet). При повторении вы мгновенно вспоминаете живую ситуацию, а не абстрактный перевод. + +### Правило 3. Аудиальный и фонетический якорь (Phonetic Anchor) +*Нельзя знать слово «только глазами».* +Инженеры часто произносят термины неправильно: +- *route* — `/ruːt/` или `/raʊt/` +- *cache* — `/kæʃ/` (а не «кеш-е») +- *queue* — `/kjuː/` +- *latency* — `/ˈleɪ.tən.si/` +- *chassis* — `/ˈʃæsi/` (а не «шассис») +- *tuple* — `/ˈtʌpəl/` (а не «тьюпл») +Сервис сразу предоставляет **нативную аудио-озвучку** и **международную транскрипцию IPA**. Это формирует уверенность для общения с зарубежными коллегами и прохождения технических собеседований. + +### Правило 4. Интервальные повторения (SRS / SM-2) +*Кривая забывания Германа Эббингауза неумолима: за первые 24 часа стирается до 70% новой информации.* +Алгоритм интервальных повторений (SuperMemo SM-2, лежащий в основе Anki) показывает карточку **ровно в тот момент, когда мозг готов её забыть**: +- День 1 (первое знакомство) +- День 2 (+1 день) +- День 5 (+3 дня) +- День 12 (+7 дней) +- День 28 (+16 дней) +- День 65 (+37 дней) +**Результат**: 5–7 минут повторений в день гарантируют 95%+ долговременного удержания без переутомления и «зубрёжки». + +### Правило 5. Активное припоминание (Active Recall) вместо иллюзии знания +Просто перечитывать список слов — это иллюзия («Да, я вроде это знаю»). Настоящее запоминание происходит только тогда, когда мозгу приходится **напрячься и вспомнить**: +- **Прямая карточка**: видишь английский термин + слушаешь аудио $\rightarrow$ вспоминаешь значение и контекст. +- **Обратная карточка**: видишь русский технический смысл $\rightarrow$ формулируешь правильный английский термин. +- **Cloze Deletion (Пропуски)**: *"The router [_____] the packet due to TTL expiration"* $\rightarrow$ подставляешь пропущенное слово. + +--- + +## 3. Рекомендации студенту по ежедневной практике + +1. **Не сохраняйте всё подряд**: + Сохраняйте только те слова и обороты, которые реально мешают пониманию мысли автора или встречаются вам повторно. Оптимальный темп — от 5 до 15 новых качественных карточек в день. +2. **Всегда вставляйте предложение-источник**: + В поле ввода достаточно скопировать предложение целиком или слово + предложение. +3. **Утренний / вечерний спринт (3-5 минут)**: + Открывайте сервис с телефона или рабочего компьютера раз в день для прохождения очереди карточек, готовых к повторению по алгоритму SRS. diff --git a/PLAN.md b/PLAN.md new file mode 100644 index 0000000..beea0a6 --- /dev/null +++ b/PLAN.md @@ -0,0 +1,124 @@ +# План развития проекта 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. **Удобство**: Управление полностью доступно с клавиатуры (без необходимости тянуться к мыши). diff --git a/README.md b/README.md new file mode 100644 index 0000000..c24a399 --- /dev/null +++ b/README.md @@ -0,0 +1,57 @@ +# Notes (notes.qpid.pro) + +> **Персональный тренажёр и словарь технического английского языка для сетевого инженера.** +> Создан для быстрого снятия языкового барьера при чтении RFC, документации Cisco/Juniper, Linux networking и технических статей. + +--- + +## 🎯 Миссия проекта +При чтении технической документации постоянные переключения на переводчик выбивают из мысли, а ручная запись слов в блокнот превращается в «кладбище информации». + +Проект решает эту проблему по принципу **«автомата Калашникова»**: +1. **Мгновенный поиск и перевод** без отвлечения от чтения. +2. **Контекстный якорь**: сохранение слова вместе с живым предложением из документации. +3. **Фонетическое закрепление**: нативное произношение (US/UK) и транскрипция IPA, чтобы говорить на митингах уверенно. +4. **Интервальные повторения (SRS / SM-2)**: умная система карточек (как в Anki), напоминая слова ровно тогда, когда мозг готов их забыть. + +--- + +## 📂 Документация проекта + +- 📋 [**План функционала и архитектура (PLAN.md)**](file:///home/kopri/notes.qpid.pro/PLAN.md) — детальный роадмап от базового MVP до умных тренажёров памяти. +- 🎓 [**Методология и педагогика (PEDAGOGY.md)**](file:///home/kopri/notes.qpid.pro/PEDAGOGY.md) — руководство по эффективному изучению сетевого английского: почему изолированные слова не работают, сила лексических связок (chunks), алгоритм SM-2. + +--- + +## 🛠 Технический стек + +- **Backend**: Python 3.12 (FastAPI / Uvicorn) +- **Database**: SQLite (WAL mode, надёжность и быстрые снимки) +- **Frontend**: Vanilla HTML5 / Modern CSS / 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) + +--- + +## 🚀 Быстрый старт (Разработка) + +```bash +# Клонирование / переход в каталог проекта: +cd /home/kopri/notes.qpid.pro + +# Создание виртуального окружения Python: +python3 -m venv venv +source venv/bin/activate + +# Запуск будет доступен после развертывания Фазы 1 +``` + +--- + +## 🌐 Информация о сервере и инфраструктуре + +- **URL сервиса**: [https://notes.qpid.pro](https://notes.qpid.pro) +- **IP-адрес сервера**: `31.77.203.213` +- **Каталог на сервере**: `/home/kopri/notes.qpid.pro` +- **Git Remote**: `http://127.0.0.1:3000/Antigravity/notes-qpid-pro.git` (зеркалируется в Gitea)