# Биохимия — мощный апгрейд модуля

Цель: превратить модуль из «красивого 2D-конструктора с захардкоженными данными» в **настоящую химическую лабораторию**: реальная 3D-геометрия молекул (VSEPR), химический движок (полярность, гибридизация, дипольный момент, баланс реакций), данные из БД вместо хардкода, расширенная геймификация.

Стек/правила: vanilla JS + canvas (БЕЗ тяжёлых либ — как STEREO_3D и OPTICS), Express, `node:sqlite` (`DatabaseSync`), `window.LS.biochem*`. Эмоджи запрещены — только inline SVG `.ic`. Поиск — `ast-index`. После каждой фазы — коммит изменённых файлов + push.

Файлы модуля:
- Frontend: `frontend/biochem.html` (2070, редактор), `biochem-library.html` (648), `biochem-pathways.html` (1240), `biochem-properties.html` (590), `biochem-reactions.html` (823)
- Backend: `backend/src/controllers/biochemController.js` (276), `backend/src/routes/biochem.js` (18)
- API: `js/api.js` (`biochem*` методы), БД: таблицы `bio_*` в `migrations/000_baseline.sql`

Статус: [ ] todo · [~] в работе · [x] готово

---

## Текущее состояние (база отсчёта)

- БД: 105 молекул (inorganic 41 / biomolecule 38 / organic 25 / aminoacid 1), 27 реакций (synthesis/decomposition/hydrolysis/combustion/redox/exchange/acid_base), 57 challenge-ов, 11 элементов (C,Ca,Cl,Fe,H,Mg,N,Na,O,P,S).
- **Атомы хранят только `{id,s,x,y}`** — z нет. `bonds_json` = `{f,t,o}` (from/to/order).
- Валидация: `hillFormula` + `valencyIssues` (лимит `MAX_V`). Полярность/класс — эвристика на фронте.
- Challenge-типы в контроллере: build/identify/formula/classify/complete/balance/match — но в БД реально только build/formula/identify.
- Пути метаболизма и физсвойства — хардкод в HTML, без API.

---

## Фаза 0 — Общее ядро `biochem-core.js` (DRY-фундамент) — [~]

Без этого каждая следующая фаза множит дублирование. Извлечь общий модуль, подключить во всех 5 страницах.

- [x] 0.1 Создан `frontend/js/biochem-core.js` (`window.BIO`): реестр `ELEMENTS`
  (цвет/масса/валентность/электроотрицательность/ковалентный+вдв радиусы/валентные
  электроны), `hillFormula`/`molarMass`/`parseFormula`/`dbe`, нормализация
  связей `bF/bT/bO`, `render2D`, `vsepr`, `render3D`, `safe`, `RING_TEMPLATES`.
- [x] 0.2 library/properties/reactions переведены на `BIO.render2D`; удалены
  дубль-таблицы `ELEM_COLORS/CPK` и `hexToRgb/cpkColor` (~250 строк). _(pathways —
  в Фазе 4, там нет структурного рендера молекул.)_
- [x] 0.3 Фикс бага [biochem.html](frontend/biochem.html) `getBondSum` (`b.o || b.order` → `b.order||b.o||1`); в ядре единая нормализация `bF/bT/bO`.
- [ ] 0.4 Базовая обработка ошибок API: общий `BIO.safe(fn)` есть в ядре; осталось
  применить во всех async-вызовах страниц (сейчас точечно).

---

## Фаза 1 — Реальная 3D-геометрия молекул (VSEPR) — [x] ⭐ главный рычаг

Сейчас «3D» проецировал плоские `x,y`. Сделана настоящая 3D-геометрия по ОЭПВО/VSEPR + canvas-рендер ball-and-stick с глубиной и светом.

- [x] 1.1 Генератор `BIO.vsepr(atoms,bonds)` (в ядре, client-side — без задержки сети,
  работает на всех страницах): стерические домены (σ-связи + неподелённые пары из
  валентных электронов), геометрии linear/trigonal/tetrahedral/pyramidal/bent/
  octahedral/trig-bipy, BFS-укладка с поворотом идеальных направлений (Родригес),
  длины связей по ковалентным радиусам. Возврат `atoms3d`, `perAtom`, `shape`,
  `hybridization`, `angle`. _Проверено: H₂O угловая, CH₄ тетраэдр 109.5°, CO₂
  линейная 180°, NH₃ пирамидальная._
- [~] 1.2 Серверный кэш геометрии (`041`/`geometry_json`) — **отложено**: VSEPR
  считается мгновенно в браузере, round-trip не нужен. Вернуться при необходимости.
- [x] 1.3 `BIO.render3D(ctx, atoms3d, bonds, cam, opts)`: painter-сортировка по глубине,
  сферы с радиальным градиентом, кратные связи, режим space-filling (VDW). Инерция/
  auto-spin переиспользованы из biochem.html.
- [x] 1.4 Встроено в [biochem.html](frontend/biochem.html): фейковый 3D заменён; в панель свойств
  добавлены форма, гибридизация, валентный угол.
- [x] 1.5 3D-превью: тумблер 2D/3D в детальной панели библиотеки и на карточках
  сравнения в properties (вращение + подпись геометрии).

---

## Фаза 2 — Химический движок (свойства из структуры) — [x]

> Сделано client-side в `BIO` (для всех страниц, без сервера; тег `biochem-phase2`):
> `partialCharges` (по ЭО на связях), `dipole` (вектор q·r по 3D VSEPR), `polarity`
> (по диполю), `massFractions`, `functionalGroups`, `analyze` — заменили фронт-эвристику.
> Тумблер **δ±** в редакторе: тепловая карта зарядов (синий δ+/красный δ−) в 2D+3D +
> стрелка диполя; число диполя в панели свойств.
> _Проверено: H₂O O=−0.52/H=+0.26; CO₂/CH₄/CCl₄ диполь 0 → неполярны; H₂O/CHCl₃ полярны._

Считать химию, а не хранить класс строкой.

> Серверный срез (тег `biochem-phase2-server`): `backend/src/services/chem.js`
> **переиспользует то же ядро** `biochem-core.js` (сделан dual-export: браузер
> `window.BIO` + Node `module.exports`) — без дублирования химии. Эндпоинт
> `POST /api/biochem/analyze` отдаёт {formula, mass, dbe, geometry, polarity,
> dipole, charges, groups, massFractions, valency}; `/validate` переведён на
> ядро (плюс чинит баг формата связей b.o/order). 2.4: `BIO.valency` с
> подсказками («Углерод (C): занято 5 связей, максимум 4 — убери 1»),
> используется и в редакторе, и на сервере.

- [x] 2.1 `backend/src/services/chem.js`: переиспользует ядро `BIO` (полярность/диполь по 3D-VSEPR, частичные заряды, DBE/масса/массовые доли, гибридизация, функциональные группы) — без дубля логики на сервере.
- [x] 2.2 API `POST /api/biochem/analyze` (atoms,bonds → {formula, mass, dbe, dipole, polarity, charges, groups, hybridization, valency}). Живой анализ в редакторе оставлен client-side (мгновенно); сервер — авторитетный расчёт + валидация на сохранении.
- [x] 2.3 В редакторе: тепловая карта частичных зарядов (toggle), стрелка диполя в 3D, панель «геометрия и полярность».
- [x] 2.4 Расширенная валидация: `BIO.valency` даёт подсказки («Углерод (C): занято 5 связей, максимум 4 — убери 1») вместо «лимит превышен»; единая логика в редакторе и на сервере.

---

## Фаза 3 — Реакции: стехиометрия, баланс, энергетика — [~]

> Сделано (тег `biochem-phase3`): `BIO.balance(reactants,products)` — балансировка
> через матрицу «элемент×вещество» + дробный Гаусс (RREF) + НОК/НОД (client-side,
> вместо серверного `balance.js`). В [biochem-reactions.html](frontend/biochem-reactions.html) при развороте карточки:
> энергетический профиль (реагенты→ПС→продукты) из `energy_kj` + бейдж проверки
> баланса. Миграция коэффициентов в БД (3.2) и механизм (3.5) — отложены.
> _Проверено: 2H₂+O₂→2H₂O, CH₄+2O₂→…, 4Fe+3O₂→2Fe₂O₃, фотосинтез 6/6/1/6, Ca(OH)₂+2HCl, N₂+3H₂→2NH₃._

- [x] 3.1 `BIO.balance` (client-side: матрица элементов → целочисленное решение Гаусс+НОК).
- [ ] 3.2 Миграция: добавить коэффициенты в `bio_reactions` (`reactant_coef`/`product_coef` JSON или `stoich_json`); пересидировать 27 реакций сбалансированными.
- [ ] 3.3 В [biochem-reactions.html](frontend/biochem-reactions.html): показывать сбалансированное уравнение с коэффициентами, проверку сохранения массы/атомов.
- [ ] 3.4 Энергетическая диаграмма реакции (reactants → переходное состояние → products) из `energy_kj` — мини-canvas-график, экзо/эндо подпись ΔH.
- [ ] 3.5 (опц.) Поле `mechanism_json` — пошаговый механизм с подсветкой разрываемых/образуемых связей.

---

## Фаза 4 — Метаболические пути из БД — [ ]

Снять хардкод (700+ строк в HTML), сделать расширяемым и с прогрессом.

- [ ] 4.1 Миграция `042_bio_pathways.sql`: `bio_pathways(id,slug,name,description)`, `bio_pathway_nodes(pathway_id,molecule_id?,label,formula,x,y,kind)`, `bio_pathway_edges(from_node,to_node,enzyme,delta)`, `bio_pathway_steps(pathway_id,order_n,node_id,quiz_json)`, `bio_user_pathway(user_id,pathway_id,step,done_at)`.
- [ ] 4.2 Сидер: перенести 4 существующих пути (гликолиз, цикл Кребса, β-окисление, синтез белка) + добавить глюконеогенез/липогенез/пентозофосфатный.
- [ ] 4.3 API: `GET /api/biochem/pathways`, `GET /pathways/:slug`, `POST /pathways/:slug/progress`.
- [ ] 4.4 [biochem-pathways.html](frontend/biochem-pathways.html): рендер из API; сохранение прогресса Learn-режима на пользователя; иерархическая укладка узлов (sugiyama-lite), чтобы не перекрывались.
- [ ] 4.5 Награда за пройденный путь (XP + ачивка), отметка пройденных путей.

---

## Фаза 5 — Challenges и геймификация — [~]

> Сделано: `backend/scripts/seed_biochem_challenges.js` (идемпотентно) засидировал
> 16 заданий недостающих типов — **balance 5, match 3, classify 4, complete 4**.
> Все 7 фильтров в UI редактора теперь с данными; контроллер их уже валидирует,
> XP начисляется. data_json совпадает с UI (balance: reactants/products/coefficients;
> match: pairs; classify/complete: target/equation/choices/answer).
> Осталось: drag-and-drop (5.2), 3D-build (5.3), адаптивность (5.4), ачивки bc_* (5.5).

Слоты ачивок `bc_5_challenges`/`bc_20_challenges` уже есть в `_shared.js` — довести до конца и расширить вызовы.

- [x] 5.1 Засидированы типы challenge: balance, match, classify, complete (16 заданий, идемпотентный сидер).
- [ ] 5.2 UI drag-and-drop для balance/match (сейчас только выбор/ввод).
- [ ] 5.3 3D-build challenge: собрать молекулу и проверить не только формулу, но и связность/геометрию.
- [ ] 5.4 Адаптивная сложность + «задача дня»; streak по биохимии.
- [ ] 5.5 Привязать ачивки `bc_5_challenges`/`bc_20_challenges` (и новые: «собрал АТФ», «сбалансировал 10 реакций», «прошёл цикл Кребса») к событиям; проверить начисление в `gamificationController`.

---

## Фаза 6 — Свойства и анализ: вычисления + графики — [~]

> Сделано (тег `biochem-phase6`): в [biochem-properties.html](frontend/biochem-properties.html) при сравнении 2+
> молекул — столбчатый график молярных масс (canvas) + экспорт таблицы в CSV
> (UTF-8 BOM). Уход от хардкода `PHYS_PROPS` (6.1) и круговая долей (6.3) — отложены.

- [ ] 6.1 Убрать хардкод `PHYS_PROPS` (15 молекул) — тянуть вычисляемые (масса, DBE, диполь, доли элементов) из `/analyze`; справочные (T_пл/T_кип/растворимость) — в новую таблицу `bio_mol_props`.
- [x] 6.2 График сравнения молярных масс (bar, canvas) + экспорт CSV. _(scatter масса·T_кип и PNG — позже.)_
- [ ] 6.3 Доп. свойства: массовая доля элементов (круговая), кислотность/основность класса, окислитель/восстановитель.

---

## Фаза 7 — Импорт/экспорт и полировка — [~]

> Сделано (теги `biochem-phase7`/`biochem-latest`): `BIO.parseSmiles` (учебное
> подмножество: атомы верх. регистра, связи -=#, ветви, циклы, неявные H,
> 2D-укладка), `BIO.toJSON`/`download`. В редакторе — поле SMILES + Импорт,
> экспорт PNG/JSON. Регресс-тесты `backend/tests/biochem-core.test.js` (8/8 pass:
> формулы, VSEPR, заряды, полярность, баланс, SMILES, analyze).

- [x] 7.1 Парсер SMILES (цепи, ветви `()`, кольца-цифры, кратность `-=#`) → atoms/bonds; поле ввода в редакторе.
- [x] 7.2 Экспорт молекулы: PNG (текущий 2D/3D холст), JSON. _(share-ссылка `?smiles=` — позже.)_
- [x] 7.5 Регресс-тесты ядра (`node --test`, 8 тестов). _(перенесён из плана ниже.)_
- [ ] 7.3 Перф: кэш `biochemGetMolecules` (общий стор), throttle поиска/фильтров, LOD для thumbnail больших молекул (АТФ и т.п.).
- [ ] 7.4 Мобайл/a11y: читаемый sidebar на ≤768px, фокус-навигация, aria для canvas-инструментов.
- [ ] 7.5 Регресс-тесты: `backend/tests/biochem.test.js` — VSEPR, баланс, analyze, фиче-флаг `requireFeature('biochem')`.

---

## Порядок приоритетов

1. **Фаза 0** (фундамент, разблокирует остальное) → **Фаза 1** (3D — главный визуальный/обучающий скачок) → **Фаза 2** (химия из структуры).
2. Затем **Фаза 3** (реакции) и **Фаза 4** (пути) — наибольшая образовательная ценность.
3. **Фазы 5–7** — геймификация, аналитика, импорт/полировка.

Минимальный «вау»-срез, если нужен быстрый результат: **Фаза 0 + Фаза 1** дают настоящую 3D-молекулу с формой и углами вместо плоской проекции.

---
История: создан 2026-05-30.