Skip to content

MODULARIZATION_PLAN.md

Latest commit

 

History

History
95 lines (65 loc) · 8.03 KB

MODULARIZATION_PLAN.md

File metadata and controls

95 lines (65 loc) · 8.03 KB
Raw

План модульного перехода uDream

Статус

План M1–M5 завершён и опубликован. Текущая поддерживаемая версия приложения — v23.8.0.

Документ сохраняется как запись принятого архитектурного решения и границ выполненной миграции. Новые этапы не должны продолжать нумерацию M1–M5 без отдельного утверждённого плана.

Решение

uDream остаётся статическим приложением на JavaScript, GitHub Pages и PWA.

Используются нативные ES Modules, JSDoc и // @ts-check. TypeScript, фреймворк, bundler, сервер и runtime-зависимости не вводятся. package.json нужен для версии приложения и запуска встроенного Node.js test runner и не участвует в браузерной сборке.

Цели

  • уменьшить связанность монолитного script.js;
  • защитить поиск, историю, настройки, представление и PWA регрессионными тестами;
  • сохранить работающее поведение и внешний вид;
  • не затрагивать активную базу и сохранённые версии;
  • оставить сайт запускаемым напрямую с GitHub Pages без build-шага.

Завершённые этапы

M1 — поиск и тестовый каркас ✅

  • чистая логика поиска и автодополнения выделена в src/search.js;
  • сохранена и затем уточнена семантика строгих режимов поиска и релевантности;
  • добавлены тесты режимов symbol, aliases, desc, tags, all;
  • основной скрипт подключён как ES module;
  • модуль включён в PWA-кеш.

M2 — данные и состояние ✅

  • загрузка и fallback JSON выделены в src/data.js;
  • ручной JSON-файл разбирается той же проверяемой функцией;
  • начальные значения и чтение сохранённых настроек выделены в src/state.js;
  • формат и содержимое активной базы не изменялись.

M3 — история и локальные настройки ✅

  • история переходов, окно хлебных крошек и группировка полной истории выделены в src/history.js;
  • чтение и запись строк, переключателей и JSON в localStorage выделены в src/storage.js;
  • повреждённая сохранённая история безопасно заменяется пустой и больше не блокирует запуск;
  • добавлены тесты навигации, сериализации и восстановления настроек.

M4 — представление и локализация ✅

  • словарь, нормализация языка и справка выделены в src/i18n.js;
  • построение карточки, списков, истории, тегов, статистики и материалов для системного sharing выделено в src/presentation.js;
  • текущие классы и структура интерактивных элементов сохранены, чтобы не менять визуальное поведение;
  • добавлены проверки локализации, HTML-экранирования и враждебного вручную загруженного JSON.

Зафиксированное security-уточнение M4

Первоначальный план предполагал только перенос представления. Предварительный аудит показал, что прежний escapeHtml не экранировал кавычки в data-* атрибутах, а Marked разрешал HTML из заметок вручную загруженного JSON. Активная база содержит 4 086 непустых однострочных заметок без используемой Markdown-разметки и raw HTML, поэтому M4 безопасно заменил их вывод на экранированный plain text с абзацами и переносами строк и удалил Marked. Это намеренное усиление границы импортируемых данных без изменения активного контента.

M5 — PWA и стили ✅

  • регистрация Service Worker выделена в src/pwa.js и покрыта тестами;
  • встроенный CSS оставлен в index.html, поскольку отдельное разделение не требовалось для цели M5;
  • установка PWA и offline reload подтверждены на Android без локального сервера и интернета;
  • последующий релиз v23.8.0 расширил модуль обновлением версии, немедленной активацией Service Worker и установочным баннером.

Итоговая архитектурная граница

После M1–M5 отдельно тестируются:

  • поиск;
  • загрузка данных;
  • начальное состояние;
  • история;
  • localStorage;
  • локализация;
  • безопасное представление;
  • PWA-регистрация и обновление.

script.js остаётся оркестратором браузерного интерфейса. Его дальнейшее разделение допускается только при конкретной пользе, а не ради формальной модульности.

Сохранённые правила миграции

  1. Один этап — один Pull Request и один uNews-патчноут.
  2. Этап не должен без необходимости одновременно менять архитектуру, данные и пользовательское поведение.
  3. versions/v3.0.0/ и _archive/ не изменяются как обычная часть рефакторинга.
  4. При каждом изменении runtime-файлов обновляются список PWA-кеша и CACHE_NAME.
  5. Перед объединением обязательны npm test, node scripts/validate-project.mjs и GitHub Actions.
  6. TypeScript рассматривается только при доказанной необходимости, если JSDoc и @ts-check перестанут обеспечивать достаточную безопасность.
  7. Любое отклонение от утверждённого плана сначала фиксируется в документации.
  8. Варианты баз и переводов не перезаписываются и не удаляются при архитектурных изменениях.

Следующая серия

Следующая рекомендуемая серия называется D1 и относится не к продолжению модульного рефакторинга, а к происхождению данных и архитектуре нескольких наборов.

Её границы определены в docs/PRODUCT_VISION.md и ROADMAP.md. Первый этап D1 является исследованием и проектированием и не должен изменять активные 4 086 записей.