wave-spectr/docs/tz.md

Техническое задание (ТЗ) на разработку PWA «HarmoniX»

1. Общие сведения и назначение

Цель проекта — создать локальное одностраничное веб-приложение (PWA) для демонстрации физического сложения гармонических колебаний (теорема Фурье), амплитудно-частотного спектра и влияния нелинейных преобразований (клиппинга) на форму сигнала и его звучание. Актуальная версия: v21.0 Stable.

2. Стек технологий и архитектурные ограничения

• Разработка ведется строго на чистом HTML5, CSS3 (CSS Variables, Flexbox, Grid) и JavaScript (Vanilla JS).
• Запрещено использование любых сторонних библиотек и фреймворков.
• Отрисовка всех графиков реализуется исключительно через HTML5 <canvas>.
• Генерация физического звука и системных эффектов реализуется через встроенный Web Audio API.

3. Архитектура экранов (Routing)

Приложение работает без перезагрузки страниц и состоит из следующих состояний:

• Welcome Screen: Стартовая страница с анимированным градиентным логотипом. Эффект круглого морфинга (перетекающая капля).
• Mode Select: Промежуточный экран выбора режима работы (Базовый, Академический, PRO).
• Main Dashboard: Основная рабочая сетка графиков формата 2x2, которая динамически занимает все доступное пространство экрана (flex-grow).
• Sidebar (Боковая навигационная панель): Выдвижное меню (off-canvas), активируемое по кнопке "☰". Включает переключатель тем, загрузку локального изображения, фильтры и настройки "Жидкого стекла".

4. Структура основного интерфейса (Сетка 2x2)

4.1. Левая верхняя часть (Базовое колебание)

• Динамический график выбранного базового гармонического колебания.

4.2. Левая нижняя часть (Управление)

• Выведены теоретические формулы: y = A*cos(wt + θ) и ν = 1/T.
• Система независимых вкладок (V1, V2, V3) с сохранением настроек амплитуды и частоты.
• Настройка ползунками range частоты (от 0 до 20 кГц) и амплитуды (0-100%).
• Переключатель шага настройки частоты: 10 Гц и 100 Гц.
• Инструменты: Кнопка вывода звука, Кнопка микрофона (захват аудио), Кнопка клиппинга, Кнопка сброса.
• Информационная безопасность: Модуль "Виброакустическая защита (ТЗИ)" с генерацией маскирующего белого шума в аудиоканал.

4.3. Правая верхняя часть (Сумма колебаний)

• Текст теоремы Фурье и график результирующего сложного колебания.

4.4. Правая нижняя часть (Спектр)

• Столбчатая диаграмма амплитудно-частотной характеристики. Координатная разметка по оси X.

5. Требования к UI/UX и адаптивности

• Масштабирование: canvas завернуты во врапперы с поддержкой ручного изменения размера (resize: both и ползунок в меню). Перерисовка привязана к ResizeObserver.
• Кастомизация: Загрузка фонового изображения и графических фильтров через backdrop-filter.
• Современный дизайн: Эффект Glassmorphism. Кнопки используют "волновую геометрию" (асимметричные border-radius: 18px 6px). Для защиты белого текста от сливания с фоном применяется глубокая контрастная обводка (text-shadow).
• Локализация (i18n): Динамический перевод интерфейса на английский язык без перезагрузки документа.

6. Модуль тестирования (Testing Module)

• База данных: 30 вопросов в JSON. Случайное перемешивание вопросов и ответов (Math.random).
• Режимы: Экспресс (5), Стандарт (15), Полный курс (30), Ультра Профи (50).
• Навигация: Пошаговый слайдер вопросов без скролла. "Умная лента таймера", меняющая цвет от зеленого к красному.
• Итоги: Динамический расчет процентов в виде анимированного SVG-кольца (Count-up). Прямые ссылки на Wikipedia для разбора ошибок.

Структура интерфейса (БОЛЕЕ СТАРЫЕ ВЕРСИИ: v2.6 - v14.0)

В приложении реализовано 4 блока, точно соответствующих записям в конспекте:

1. Левая верхняя часть: График выбранного базового гармонического колебания.
2. Левая нижняя часть (Управление):
   • Выведены формулы: y = A*cos(wt + θ), V = 1/T.
   • Настройка частоты (до 20 кГц) и амплитуды.
   • Переключатель шага частоты: 10 Гц и 100 Гц.
   • Вкладки (V1, V2, V3) — для каждого колебания сохраняются свои настройки.
   • Кнопка вывода звука на динамик.
   • Кнопка нелинейного преобразования (Клиппинг).
   • (NEW) Кнопка «Сбросить все» для быстрого возврата к стандартным параметрам.
3. Правая верхняя часть (Теорема Фурье):
   • Текст теоремы о том, что любое колебание может быть представлено в виде суммы.
   • Результирующий график суммы волн.
4. Правая нижняя часть (Спектр):
   • Отображение амплитудно-частотной характеристики.
   • (NEW) Добавлена координатная разметка по оси X (5кГц, 10кГц, 15кГц).
   • Демонстрация появления паразитных гармоник при включении искажений.

Цель проекта: Создать локальное одностраничное веб-приложение (PWA) для демонстрации физических принципов сложения гармонических колебаний (теорема Фурье), амплитудно-частотного спектра и влияния нелинейных преобразований (клиппинга) на форму сигнала и его звучание.

Требования к стеку:

• Разработка ведется на чистом HTML, CSS, JavaScript (Vanilla JS).
• Запрещено использование сторонних библиотек и фреймворков.
• Генерация звука реализуется через встроенный Web Audio API.
• Отрисовка графиков реализуется через HTML5 <canvas>.

Структура интерфейса (Сетка 2x2):

1. Левая верхняя панель (Базовое колебание): Динамический график выбранной пользователем гармонической волны.
2. Левая нижняя панель (Управление):
   • Вывод теоретических формул: y = A*cos(wt + θ) и V = 1/T.
   • Система вкладок (V1, V2, V3) для независимой настройки трех разных волн.
   • Ползунки управления: Частота (от 0 до 20 кГц) и Амплитуда (0-100%).
   • Переключатель шага настройки частоты (10 Гц / 100 Гц).
   • Кнопка активации Web Audio API («Вывод на динамике»).
   • Кнопка добавления нелинейного искажения (Клиппинга).
   • Кнопка «Сбросить все».
3. Правая верхняя панель (Сумма колебаний): Текстовое описание теоремы Фурье и график результирующего (сложного) колебания, полученного путем сложения волн из вкладок V1, V2 и V3. При активации клиппинга график должен обрезать пики по оси Y.
4. Правая нижняя панель (Амплитудно-частотный спектр): Столбчатая диаграмма частот. При включении нелинейного преобразования должны программно отрисовываться дополнительные (паразитные) гармоники.

1.2: Интерактивная модель Фурье

1. Назначение и стек технологий

• Тип: Одностраничное PWA приложение.
• Стек: HTML5, CSS3 (CSS Variables, Flexbox, Grid), JavaScript (Canvas API, Web Audio API). Без фреймворков.
• Цель: Изучение сложения механических волн, теоремы Фурье, спектрограмм и нелинейных искажений (клиппинга).

2. Архитектура интерфейса (UI/UX)

Приложение состоит из 5 основных блоков:

1. Плавающее меню кастомизации (Top Bar):
   • Переключение предустановленных тем (Базовая, Темная, Неон).
   • Загрузка пользовательского фонового изображения из файловой системы.
   • Применение графических фильтров к фону (Размытие, Ч/Б, Сепия, Инверсия) через backdrop-filter.
2. Панель 1 (Левый верх): Визуализация базового гармонического колебания на Canvas.
3. Панель 2 (Левый низ): Панель управления. Ползунки range для настройки частоты (до 20 кГц) и амплитуды. Система вкладок (V1, V2, V3).
4. Панель 3 (Правый верх): График сложного колебания (сумма гармоник).
5. Панель 4 (Правый низ): Амплитудно-частотный спектр с отрисовкой паразитных гармоник.
6. Масштабирование компонентов: Все графические блоки canvas завернуты во врапперы с поддержкой ручного изменения размера (resize: both). Перерисовка графиков привязана к ResizeObserver, что исключает растягивание пикселей при изменении соотношения сторон элемента.

7. Брендирование: Текстовые логотипы используют CSS-градиенты (linear-gradient с анимацией background-position), имитируя неоновое свечение на приветственном экране.

   Архитектура экранов (Routing)

8. Welcome Screen: Стартовая страница с градиентным логотипом.

9. Main Dashboard: Основная сетка графиков 2х2. Занимает все пространство экрана (flex-grow).

10. Sidebar (Боковая навигационная панель): Выдвижное меню (off-canvas), активируемое по кнопке "☰". Включает в себя переключатель тем, список онлайн-фонов, загрузку локального изображения и фильтры.

11. Тестирование (Modal): Геймифицированный тест. Содержит базу на 30 вопросов. Три режима сложности: Легкий (5), Средний (15), Сложный (30). Динамический расчет процентов, система звукового поощрения (Win/Lose) и навигационные кнопки "Выйти" / "Рестарт".

    3. Требования к интерактивному аудио (UI Audio)

    Помимо основного физического звука, интерфейс должен иметь звуковой отклик:

12. Кнопки: Короткие синтезированные звуки (beep) при нажатии и наведении (hover). Звук подтверждения действия и звук ошибки/сброса.

13. Ползунки (Range): Динамическое изменение тональности UI-звука при перетаскивании ползунка (частота звука зависит от текущего значения value ползунка).

14. Реализация: Отдельный независимый экземпляр AudioContext, чтобы системные звуки интерфейса не смешивались с физической демонстрацией частот.

4. Тестирование (Testing Module):

Модальное окно без нумерации. Содержит базу данных вопросов в JSON. При запуске алгоритм перемешивает как порядок вопросов, так и порядок ответов. Присутствует кнопка «Начать сначала» для повторного прохождения.

• Проверка геймифицирована: правильные варианты подсвечиваются зелёным со звуком колокольчика (ding), неверные — красным со звуком зуммера (buzz). Итоговый результат сопровождается музыкой (победной или проигрышной).