docs(biochem): отметить выполненными Фазу 0 (ядро/DRY) и Фазу 1 (3D VSEPR)
This commit is contained in:
Maxim Dolgolyov
@@ -0,0 +1,142 @@
|
||||
# Биохимия — мощный апгрейд модуля
|
||||
|
||||
Цель: превратить модуль из «красивого 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.
|
||||
Reference in New Issue
Block a user