Learn_System/plans/BIOCHEM_UPGRADE.md

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

Цель: превратить модуль из «красивого 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 страницах.

• 0.1 Создан frontend/js/biochem-core.js (window.BIO): реестр ELEMENTS (цвет/масса/валентность/электроотрицательность/ковалентный+вдв радиусы/валентные электроны), hillFormula/molarMass/parseFormula/dbe, нормализация связей bF/bT/bO, render2D, vsepr, render3D, safe, RING_TEMPLATES.
• 0.2 library/properties/reactions переведены на BIO.render2D; удалены дубль-таблицы ELEM_COLORS/CPK и hexToRgb/cpkColor (~250 строк). (pathways — в Фазе 4, там нет структурного рендера молекул.)
• 0.3 Фикс бага 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 с глубиной и светом.

• 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 не нужен. Вернуться при необходимости.
• 1.3 BIO.render3D(ctx, atoms3d, bonds, cam, opts): painter-сортировка по глубине, сферы с радиальным градиентом, кратные связи, режим space-filling (VDW). Инерция/ auto-spin переиспользованы из biochem.html.
• 1.4 Встроено в biochem.html: фейковый 3D заменён; в панель свойств добавлены форма, гибридизация, валентный угол.
• 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»), используется и в редакторе, и на сервере.

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

---

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

Сделано (тег biochem-phase3): BIO.balance(reactants,products) — балансировка через матрицу «элемент×вещество» + дробный Гаусс (RREF) + НОК/НОД (client-side, вместо серверного balance.js). В 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₃.

• 3.1 BIO.balance (client-side: матрица элементов → целочисленное решение Гаусс+НОК).
• 3.2 Миграция: добавить коэффициенты в bio_reactions (reactant_coef/product_coef JSON или stoich_json); пересидировать 27 реакций сбалансированными.
• 3.3 В 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: рендер из 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 — довести до конца и расширить вызовы.

• 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 при сравнении 2+ молекул — столбчатый график молярных масс (canvas) + экспорт таблицы в CSV (UTF-8 BOM). Уход от хардкода PHYS_PROPS (6.1) и круговая долей (6.3) — отложены.

• 6.1 Убрать хардкод PHYS_PROPS (15 молекул) — тянуть вычисляемые (масса, DBE, диполь, доли элементов) из /analyze; справочные (T_пл/T_кип/растворимость) — в новую таблицу bio_mol_props.
• 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).

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