Maxim Dolgolyov
231 lines
17 KiB
Markdown
231 lines
17 KiB
Markdown
# План: визуальное оформление и улучшение интерактивов — Физика 9
|
||
|
||
**Цель:** довести Физику 9 до качества Физики 8/10/11 — единый стиль, плавные анимации, читаемые подписи, тёмная тема, удалить Font Awesome, отрефакторить «голые» канвасы.
|
||
|
||
**Исходное состояние:** 5 глав (`physics_9_ch1..ch5.html`) + монолитный `phys9_legacy.js` (5952 строк) + 36 параграфов + 5 финалов + 12 ЛР. Legacy-код — это извлечённый монолит, всё внутри IIFE, симуляции на `<canvas>` без масштаба, цвета и подписи в стиле «школьная тетрадь».
|
||
|
||
---
|
||
|
||
## 📊 Аудит текущего состояния
|
||
|
||
### Что уже работает (после фиксов сегодня)
|
||
- Контент глав отображается, навигация по § работает.
|
||
- Подключён `phys9_legacy.js` во все 5 ch-файлов.
|
||
- Хуки `ensureBuilt` инжектят блок задач из POOLS[pN] под каждый §.
|
||
- Экспорт `window.POOLS`, `window.STATE`, `window.startAnim*`, `window.upd*`, `window.draw*`.
|
||
- Все 36 пулов `TASKS_P1..P36 + TASKS_HARD` доступны.
|
||
|
||
### Что не так визуально
|
||
| # | Проблема | Где | Влияние |
|
||
|---|----------|-----|---------|
|
||
| 1 | **Font Awesome** иконки (`fas fa-*`) — нарушение проектной политики «только inline SVG `.ic`» | `phys9_legacy.js` (8 мест) + ch1 (1) | Несогласованность с остальным каталогом |
|
||
| 2 | **30+ канвасов без масштаба** — `cv1..cv30` рисуются по px-координатам, не подписаны единицами, цвета случайные | `phys9_legacy.js` все `upd*` / `draw*` | Не читаются на мобильных, выглядят «школьно» |
|
||
| 3 | **Нет цветовой кодировки** по типу величины (масса, скорость, сила) | везде | Учащийся не отличает кинематические/динамические величины |
|
||
| 4 | **Тёмная тема не покрывает legacy-элементы** — стрелки, оси, текст всегда чёрные | canvas-рендер в legacy | На тёмной теме нечитаемо |
|
||
| 5 | **Подписи на канвасах**: `Arial 12px`, мелко, не масштабируется | `ctx.font = '12px sans-serif'` | Плохо на больших экранах и на мобильных |
|
||
| 6 | **Кнопки-управление симуляциями** разнородные: где `<button class="btn">`, где `<input type="range">` без подписей | разные параграфы | Нет единого UX |
|
||
| 7 | **Анимации без паузы / сброса** — startAnim1, startAnim15 запускаются автоматически, остановить нельзя | `phys9_legacy.js:start*` | Жжёт CPU на фоне |
|
||
| 8 | **Графики $T(t)$, $v(t)$ нарисованы вручную** через `lineTo` — без сетки, без подписей осей в СИ | `upd9`, `upd11`, `upd13` | Бесполезны для понимания |
|
||
| 9 | **Нет «3 видов задач»** — есть только пул задач из POOLS, нет калькуляторов и DnD-сортировок (как в Физике 8/10) | архитектура | Меньше вовлечения |
|
||
| 10 | **CSS-перегружен** — есть `.fcard`, `.formula-grid`, `.section-title`, `.para-hero`, `.ph-tag`, `.ph-tags`, `.ph-formula` — устаревшая визуальная стилистика | inline `<style>` в ch1..ch5 | Тяжело сопровождать |
|
||
| 11 | **Финалы** глав (`final1..final5`) — заглушки без интегрированных боссов и ачивок | builders в ch | Нет «магистра» главы |
|
||
| 12 | **ЛР 1-12 в ch5** — ссылаются на `cvLab11`, но `drawLab11` пишет напрямую координаты грузов в граммах с маленькими подписями | `phys9_legacy.js` | Не похоже на «лабораторный отчёт» |
|
||
|
||
---
|
||
|
||
## 🎨 Целевой облик (как у Физики 8/10/11)
|
||
|
||
1. **SVG-канвасы вместо `<canvas>`** где можно — векторные, масштабируемые, темнее/светлее по теме.
|
||
2. **Цветовая кодировка:**
|
||
- Скорость $\vec v$ — голубой `#0891b2`
|
||
- Ускорение $\vec a$ — оранжевый `#ea580c`
|
||
- Сила $\vec F$ — зелёный `#10b981`
|
||
- Масса/тело — серый `#475569`
|
||
- Сила тяжести — синий `#2563eb`
|
||
- Сила трения — фиолетовый `#7c3aed`
|
||
3. **Хелперы** общие с другими физиками: `phys.js` (`drawArrow`, `axes2D`, `plotFunc`).
|
||
4. **Каждый интерактив:**
|
||
- Slider'ы с подписями единиц (м/с, м/с², Н)
|
||
- Кнопки **Пауза / Сброс**
|
||
- `cancelAnimationFrame` при unmount
|
||
- Текстовая «выкладка» текущих значений в `.score-display`
|
||
5. **Тёмная тема:** SVG использует `currentColor` или CSS-переменные, не хардкод `#000`.
|
||
6. **Финал главы:** шпаргалка + 5-10 интегрированных боссов + ачивка `master_chN`.
|
||
|
||
---
|
||
|
||
## 🚀 Фазы реализации
|
||
|
||
### Phase 0 — Аудит и подготовка (1 коммит)
|
||
- [ ] Список всех 30+ канвасов с описанием: что симулирует, какие параметры, какой §
|
||
- [ ] Список всех `upd*` / `draw*` / `startAnim*` с их вход/выход
|
||
- [ ] Решение: какие canvas → SVG, какие оставить (большие частицы/тысячи точек)
|
||
- [ ] Перечислить все `fa-*` → план замены на inline SVG `.ic`
|
||
- [ ] Документ: `plans/textbooks-9/PHYS9_INTERACTIVES_INVENTORY.md`
|
||
|
||
### Phase 1 — Удаление Font Awesome из физики 9 (1 коммит)
|
||
- [ ] Заменить все 8 вхождений `<i class="fas fa-*">` в `phys9_legacy.js` на inline SVG
|
||
- [ ] Заменить 1 вхождение в `physics_9_ch1.html`
|
||
- [ ] Удалить `<link rel=stylesheet ... font-awesome>` из ch-страниц
|
||
- [ ] Smoke-test: открыть все 5 ch — иконки сохранились
|
||
|
||
### Phase 2 — Цветовая кодировка и легенда (1 коммит)
|
||
- [ ] Создать `frontend/js/phys9_palette.js` — единый объект `PHYS9_COLORS`
|
||
- [ ] Перенести жёстко закодированные цвета (`fillStyle = '#xxx'`) на ссылки `PHYS9_COLORS.velocity` и т.д.
|
||
- [ ] Создать `frontend/css/phys9-canvas.css` — переменные для тёмной темы
|
||
- [ ] Использовать `getComputedStyle` для текущего цвета (поддержка тёмной темы автоматом)
|
||
|
||
### Phase 3 — Стандарт SVG-визуализации (3-5 коммитов)
|
||
Большинство канвасов — это статические сцены: брусок + сила + стрелка. Их можно перевести на SVG.
|
||
|
||
**Канвасы-кандидаты на SVG:**
|
||
- §3 `drawArrow3` — вектор силы (просто SVG `<line>` + `<polygon>`)
|
||
- §10 `upd10` (касательная/нормальная скорость)
|
||
- §11 `upd11` (равноуск. движение, графики $v(t)$, $s(t)$)
|
||
- §19 `drawSpring19` (пружина)
|
||
- §20 `drawFriction20` (брусок + трение)
|
||
- §23 `drawGravity23` (сила тяжести)
|
||
- §24 `drawElevator24` (лифт + вес)
|
||
- §25 `drawSeesaw25` (рычаг)
|
||
- §26 `drawLever26` (рычаг 2-го рода)
|
||
- §28 `drawEquilibrium28` (рычаг + плечи)
|
||
- §29 `drawArchimedes29` (плавание тел)
|
||
- §30 `drawShip30` (корабль)
|
||
|
||
**Оставить на canvas (анимации с многими точками):**
|
||
- §1 `startAnim1` — Броуновское движение, 30+ частиц
|
||
- §15 `startAnim15` — гравитация / движение планет
|
||
- §17 `startAnim17` — равномерное движение по окружности
|
||
- §22 `drawAngularThrow22` — баллистика с траекторией
|
||
|
||
Каждый SVG-перенос:
|
||
- 1 коммит на 2-3 канваса
|
||
- Использовать `phys.js` хелперы (`drawArrow`, `axes2D`, `plotFunc`)
|
||
- Сохранить функцию-обёртку с тем же именем, чтобы legacy кнопки `onclick="upd23()"` продолжали работать
|
||
|
||
### Phase 4 — Графики $T(t)$, $v(t)$, $s(t)$ через `phys.js` (2 коммита)
|
||
- [ ] §9 — графики координаты от времени
|
||
- [ ] §11 — равноуск. движение, $v$-$t$, $s$-$t$
|
||
- [ ] §13 — графики ускорения
|
||
- [ ] §14 — графики $v$ при разных $a$
|
||
|
||
Унифицировать оси (СИ, шкала, надписи), цвета (`PHYS9_COLORS`), легенду.
|
||
|
||
### Phase 5 — Тёмная тема для всех визуализаций (1 коммит)
|
||
- [ ] Все SVG: использовать `currentColor` / CSS-переменные
|
||
- [ ] Canvas: проверять `document.documentElement.classList.contains('dark')` и менять `ctx.strokeStyle`
|
||
- [ ] Сетка + оси: `var(--border)` вместо `#ccc`
|
||
- [ ] Текстовые подписи: `var(--text)` вместо `#000`
|
||
|
||
### Phase 6 — Управление симуляциями (2 коммита)
|
||
- [ ] Все `startAnim*` получают кнопки **Пауза/Запуск/Сброс**
|
||
- [ ] При смене параграфа (`goTo`) — отменять текущие `requestAnimationFrame`
|
||
- [ ] Slider'ы — с подписями единиц (м/с, °, кг)
|
||
- [ ] Текстовая выкладка: `.score-display` с текущими значениями
|
||
|
||
### Phase 7 — Калькуляторы и DnD как в Физике 8/10 (3-5 коммитов)
|
||
В монолите Физики 9 нет калькуляторов и DnD-сортировок — только пулы задач. Это упущение.
|
||
|
||
**Добавить для каждой главы 1-2 калькулятора:**
|
||
- Глава 1: калькулятор $s = v_0 t + at^2/2$ + DnD «равномерное / равноуск.»
|
||
- Глава 2: калькулятор $F = ma$ + DnD «причина / следствие»
|
||
- Глава 3: калькулятор плечей рычага + DnD «выигрыш в силе / расстоянии»
|
||
- Глава 4: калькулятор Архимеда + DnD «плавает / тонет»
|
||
- Глава 5: калькулятор периода маятника + DnD «механ. / эл. колебания»
|
||
|
||
Каждый — отдельная `<div class="wg">` карточка под секцией §, как в Физике 8.
|
||
|
||
### Phase 8 — Финалы глав (5 коммитов, по 1 на главу)
|
||
Сейчас `final1..final5` — пустышки. Сделать как у Физики 8:
|
||
- Шпаргалка по главе (6-10 формул)
|
||
- 5-10 интегрированных боссов (числовые задачи с подсказками)
|
||
- Ачивка `physics9_chN_master` (+50 XP)
|
||
- Кнопка перехода к следующей главе
|
||
|
||
### Phase 9 — Лабораторный практикум ch5 (1-2 коммита)
|
||
12 ЛР сейчас — голые таблицы. Сделать как у Физики 8:
|
||
- Цель работы (карточка)
|
||
- Оборудование (список)
|
||
- Ход работы (нумерованный)
|
||
- Виртуальная установка (SVG-симуляция)
|
||
- Таблица измерений с автозаполнением
|
||
- Калькулятор результата
|
||
- Кнопка «Сдать работу (+30 XP)»
|
||
- Ачивка `physics9_lab_master` (+50 XP) после всех 12
|
||
|
||
### Phase 10 — Респонсивность и a11y (1 коммит)
|
||
- [ ] Все SVG/canvas с `width:100%;height:auto;max-width:600px`
|
||
- [ ] Шрифты подписей: `clamp(11px, 1vw, 14px)`
|
||
- [ ] `aria-label` на интерактивных SVG-элементах
|
||
- [ ] `role="img"` на статических SVG
|
||
|
||
### Phase 11 — Удаление legacy CSS (1 коммит)
|
||
- [ ] Перенести стили `.fcard`, `.formula-grid`, `.section-title`, `.para-hero`, `.ph-tag`, `.ph-tags`, `.ph-formula` в `frontend/css/phys9-theme.css`
|
||
- [ ] Удалить дублирование из 5 ch-файлов (CSS сейчас инлайн в каждом)
|
||
- [ ] Подключить общий файл
|
||
|
||
### Phase 12 — Полное ревью + KaTeX-аудит (1 коммит)
|
||
- [ ] Smoke-test всех 36 § в браузере (light + dark)
|
||
- [ ] KaTeX-аудит: `[^\\]\\[a-zA-Z]{2,}` в JS-блоках (одинарный backslash где не надо)
|
||
- [ ] JS parse-check всех 5 ch + legacy.js
|
||
- [ ] Проверка: ни одного `console.log/warn/error` debug-вызова в hot-path
|
||
|
||
---
|
||
|
||
## 📦 Оценка объёма
|
||
|
||
| Phase | Коммитов | LOC изм. | Приоритет |
|
||
|-------|----------|----------|-----------|
|
||
| 0 — Аудит | 1 | 300 (документ) | КРИТИЧНО |
|
||
| 1 — Удаление FA | 1 | ~30 | КРИТИЧНО |
|
||
| 2 — Цветовая кодировка | 1 | ~200 | ВЫСОКО |
|
||
| 3 — SVG визуализация | 5 | ~1500 | ВЫСОКО |
|
||
| 4 — Графики | 2 | ~400 | ВЫСОКО |
|
||
| 5 — Тёмная тема | 1 | ~200 | СРЕДНЕ |
|
||
| 6 — Управление симуляциями | 2 | ~300 | СРЕДНЕ |
|
||
| 7 — Калькуляторы / DnD | 5 | ~1500 | СРЕДНЕ |
|
||
| 8 — Финалы глав | 5 | ~1000 | ВЫСОКО |
|
||
| 9 — ЛР практикум | 2 | ~600 | СРЕДНЕ |
|
||
| 10 — Респонсив / a11y | 1 | ~200 | НИЗКО |
|
||
| 11 — Очистка CSS | 1 | ~100 (-) | НИЗКО |
|
||
| 12 — Финальное ревью | 1 | ~50 | КРИТИЧНО |
|
||
| **Итого** | **~28 коммитов** | **~6 400 LOC** | |
|
||
|
||
---
|
||
|
||
## ⚠️ Архитектурное предупреждение
|
||
|
||
`phys9_legacy.js` **генерируется** скриптом [backend/scripts/extract_phys9_legacy.cjs](backend/scripts/extract_phys9_legacy.cjs) из монолита `physics_9.html`. **Все ручные правки исчезнут**, если кто-то запустит экстрактор повторно.
|
||
|
||
**Два пути:**
|
||
|
||
**Путь A (быстрый, hacky):** править `phys9_legacy.js` напрямую и заморозить экстрактор (переименовать с пометкой `DO_NOT_RUN_anymore.cjs`).
|
||
|
||
**Путь B (правильный, долгий):** переписать ch1..ch5 на конвенцию Физики 8/10:
|
||
- Каждый параграф — `build_pN()` в inline `<script>`, без legacy
|
||
- POOLS_PN перенести в каждую главу-файл как локальный объект
|
||
- Удалить `phys9_legacy.js` целиком
|
||
- Тогда хелперы из `phys.js` будут использоваться нативно
|
||
|
||
**Рекомендация:** для критичных фиксов (Phase 1, 2, 8, 12) — путь B, в новой архитектуре. Для остальных — путь A, с заморозкой экстрактора.
|
||
|
||
---
|
||
|
||
## 🎬 Запуск
|
||
|
||
1. **Phase 0** — сделать инвентаризацию (`PHYS9_INTERACTIVES_INVENTORY.md`).
|
||
2. **Phase 1** — удалить Font Awesome (быстрая победа, заметна сразу).
|
||
3. Решить путь A или B.
|
||
4. Если B — начать с ch1 (большой объём — 14 §, можно как pilot).
|
||
5. Дальше по приоритету: финалы → SVG-визуализации → калькуляторы.
|
||
|
||
После Phase 1-3 курс уже будет выглядеть «как остальные учебники проекта». Phase 4-9 — углубление качества. Phase 10-12 — полировка.
|
||
|
||
---
|
||
|
||
## 🔗 Связанные документы
|
||
|
||
- [PLAN_PHYSICS_9.md](PLAN_PHYSICS_9.md) — исходный план учебника
|
||
- [PLAN_PHYSICS_8.md](../textbooks-8/PLAN_PHYSICS_8.md) — образец архитектуры
|
||
- [PLAN_PHYSICS_10.md](../textbooks-10/PLAN_PHYSICS_10.md) — образец визуализации (canvas + SVG)
|