Maxim Dolgolyov
50 lines
5.8 KiB
Markdown
50 lines
5.8 KiB
Markdown
# Feature Context: Конструктор симуляций (SimForge)
|
||
|
||
## Current State
|
||
- **Фаза 0 РЕАЛИЗОВАНА** (в рабочем дереве, не закоммичено — коммит за оркестратором). Ветка `feature/sim-builder` от `master`.
|
||
- `frontend/js/labs/_sim_expr.js` → `window.SimExpr` (безопасный движок выражений, без eval/Function; `compile/evaluate/evalSafe/compileValue/parse/tokenize`, whitelist + сравнения/логика/тернарник/multi-var env).
|
||
- `frontend/js/labs/_sim_engine.js` → `window.SimEngine.mount(host, spec) -> { play, pause, reset, setParam, getParam, isRunning, destroy, el }`. Canvas (мир→экран, Y вверх) + KaTeX-оверлей подписей + слайдеры/play/pause/reset. Формат спеки v1 задокументирован в шапке файла.
|
||
- `frontend/js/labs/_sim_adapter.js` → `window.registerSpecSim(spec)` / `window.SimAdapter` — строит манифест LabRegistry (ленивый хост `#sim-spec-host-<id>` в `#lab-sim`).
|
||
- `frontend/js/labs/_sim_demo.js` — демо `customdemo` (бросок тела) за флагом `?simdemo=1` / `?sim=customdemo` / `LAB_SHOW_SPEC_DEMO` / localStorage `lab-spec-demo=1`. Ученикам не светится.
|
||
- Подключение в `frontend/lab.html`: 3 каркасных модуля eager после `_graph_panel.js`, демо после `_register-all.js`. `_sim_deps.js` НЕ тронут.
|
||
- Верификация: `node --check` все 4 файла OK; eval/Function отсутствуют (только в комментариях); эмодзи нет; SimExpr self-test 29/30 (единственный «FAIL» `-2^2=4` — это парити с graph.js).
|
||
- Лаборатория уже декларативна на уровне регистрации: `frontend/js/labs/_registry.js`
|
||
(`LabRegistry.register/get/all/setActive/stop/destroy/resolvePreview`), манифест с
|
||
`open(ctx)/mount(host)/stop/destroy`. ~40 симуляций — рукописные JS-модули в `frontend/js/labs/`.
|
||
- Каталог в БД: миграция `042_lab_sims.sql` (`lab_sims`), роуты `backend/src/routes/lab.js`
|
||
(`GET /api/lab/sims`, PATCH/:id, POST /reorder, links). Привязка к программе: `043_lab_sim_links.sql`.
|
||
|
||
## Архитектурные решения (зафиксированы при планировании)
|
||
- **Спека = JSON-данные.** Версия `specVersion`. Корень: `{ specVersion, meta, viewport, params[], objects[], physics?, plots[], controls }`.
|
||
- **Движок выражений безопасный** — собственный парсер (расширение `y=f(x)` из graph.js):
|
||
токенайзер → AST → eval по окружению `{ params, t, объекты, whitelisted Math fns }`.
|
||
⛔ Без `eval`/`Function`. Whitelist: + - * / ^ %, sin cos tan asin acos atan sqrt abs exp ln log min max floor ceil round sign pi e, сравнения, ?:.
|
||
- **Рантайм** `window.SimEngine.mount(host, spec) -> instance{ play, pause, reset, setParam, destroy }`.
|
||
Рендер: canvas для геометрии/трасс + SVG/absolute-div оверлей для подписей (KaTeX).
|
||
Регистрируется в LabRegistry адаптером (одна функция строит манифест из спеки).
|
||
- **Объект**: `{ id, type, ...props-with-bindings }`. type ∈ point|segment|vector|circle|rect|polyline|path|label|image. Любое числовое свойство может быть числом ИЛИ строкой-выражением.
|
||
- **Физический режим (Фаза 2)**: объект с `body:{ mass, vx, vy, fixed }` интегрируется `_fx_motion`; силы `physics:{ gravity, springs[], collisions, friction, walls }`. Формульный и физический режимы сосуществуют (формульные объекты — кинематические).
|
||
- **Безопасность шаринга**: published-спека валидируется на сервере (размер, схема, глубина AST, число объектов/параметров); подписи-строки санитизируются как svg/текст.
|
||
|
||
## Temporary Workarounds
|
||
- (нет)
|
||
|
||
## Cross-Phase Dependencies
|
||
- Ф1 (графики/drag) зависит от рантайма Ф0.
|
||
- Ф2 (физика) зависит от Ф0 (модель объектов/цикл).
|
||
- Ф4 (билдер) зависит от Ф0–Ф2 (что строить) + Ф3 (куда сохранять).
|
||
- Ф5 (каталог) зависит от Ф3 (БД) + Ф0 (адаптер LabRegistry).
|
||
- Ф6 (раздача) зависит от Ф3+Ф5.
|
||
- Ф7 (доска) зависит от Ф0 (рантайм) + Ф5 (источник sim) + существующего `simOpen/simState`.
|
||
|
||
## Implementation Notes
|
||
- Каждая фаза должна оставлять /lab рабочим (Incremental).
|
||
- Тестировать рантайм Ф0–Ф2 рукописными спеками-фикстурами (без билдера).
|
||
- Reuse > переписывание: сначала смотреть `_fx_motion`, `_graph_panel`, `graph.js`.
|
||
|
||
## RESUME STATE
|
||
- Последний коммит фичи: — (Ф0 реализована, но ещё не закоммичена — ждёт оркестратора)
|
||
- Текущая фаза: Phase 0 — Runtime core (✅ Implemented, pending commit) → дальше Phase 1 — Plots & interactions
|
||
- Режим: Automated / Orchestrator / Incremental
|
||
- Новые публичные API для следующих фаз: `window.SimExpr`, `window.SimEngine.mount`, `window.registerSpecSim` / `window.SimAdapter`. Формат спеки v1 — в шапке `_sim_engine.js` и в handoff phase-0.
|