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

Цель: превратить модуль из «красивого 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 — Химический движок (свойства из структуры) — [ ]

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

- [ ] 2.1 `backend/src/services/chem.js`:
  - Полярность связей по разнице электроотрицательностей; **дипольный момент** молекулы (вектор-сумма с учётом 3D-геометрии из Фазы 1) → polar/nonpolar обоснованно.
  - Частичные заряды (упрощённый Gasteiger / EN-метод) для раскраски атомов.
  - DBE (степень ненасыщенности), молярная масса, массовые доли элементов.
  - Гибридизация центра, классификация функциональных групп через SMARTS-подобные паттерны (вынести из хардкода фронта).
- [ ] 2.2 API `POST /api/biochem/analyze` (atoms,bonds → {formula, mass, dbe, dipole, polarity, charges, groups, hybridization}). Заменить фронтовую эвристику.
- [ ] 2.3 В редакторе: тепловая карта частичных зарядов (toggle), стрелка диполя в 3D, панель «геометрия и полярность».
- [ ] 2.4 Расширенная валидация: вместо «лимит превышен» — подсказки («у C занято 5 связей, максимум 4», «кислород обычно 2 связи»).

---

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

- [ ] 3.1 Авто-балансировщик `backend/src/services/balance.js`: матрица элементов → целочисленное решение (Гаусс + НОК). Эндпойнт `POST /api/biochem/balance`.
- [ ] 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 и геймификация — [ ]

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

- [ ] 5.1 Реально засидировать недостающие типы challenge: balance (drag-коэффициенты), match, classify, complete (контроллер их уже поддерживает, данных в БД нет).
- [ ] 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 — Свойства и анализ: вычисления + графики — [ ]

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

---

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

- [ ] 7.1 Парсер SMILES (подмножество: цепи, ветви `()`, кольца-цифры, кратность) → atoms/bonds; поле ввода в редакторе.
- [ ] 7.2 Экспорт молекулы: PNG (2D/3D), JSON, ссылка-share `/biochem?smiles=...`.
- [ ] 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.
