feat(sim-builder): фаза 3 — БД custom_sims + CRUD API с валидацией спеки и проверкой владения

plans/sim-builder/phase-3-persistence-api.md

@@ -1,6 +1,6 @@
 # Phase 3: БД + API (custom_sims)
 
-**Status:** ⬜ Not Started
+**Status:** ✅ Implemented (в рабочем дереве, не закоммичено — коммит за оркестратором)
 **Parent plan:** [PLAN.md](./PLAN.md)
 **Domain:** backend
 
@@ -9,19 +9,27 @@
 серверная валидация спеки. После фазы спека сохраняется/грузится/удаляется через API.
 
 ## Tasks
-- [ ] Миграция `backend/src/db/migrations/0NN_custom_sims.sql` (следующий свободный номер):
-  таблица `custom_sims` (id, owner_id FK users ON DELETE CASCADE, title, description, subject,
-  grade, cat, spec_json TEXT, status TEXT 'draft|published' DEFAULT 'draft', version INT,
-  created_at, updated_at) + индекс по owner_id, status.
-- [ ] Контроллер `backend/src/controllers/customSimController.js`: list (own + published), get,
-  create, update, remove. Владение проверяется на mutate (owner или admin).
-- [ ] Серверная валидация спеки `validateSpec(spec)`: размер JSON, `specVersion`, лимиты
-  (число params/objects, глубина строк-выражений), типы объектов из whitelist, строки-подписи
-  обрезаются/санитизируются. Отказ с 400 при нарушении. ⛔ Никакого исполнения спеки на сервере.
-- [ ] Роуты `backend/src/routes/customSims.js`: `GET /api/custom-sims` (свои+published),
-  `GET /api/custom-sims/:id`, `POST /` (teacher/admin), `PUT /:id`, `DELETE /:id`. Смонтировать в server.js под authMiddleware + фича-гейт при необходимости.
-- [ ] Клиент `js/api.js`: `customSimsList/Get/Create/Update/Delete` + добавить в `window.LS`.
-- [ ] Тесты `backend/tests/custom-sims.test.js`: CRUD, ownership (403 чужой), валидация (400 кривая спека). Использовать `seedRow()` паттерн (устойчив к дрейфу схемы).
+- [x] Миграция `backend/src/db/migrations/071_custom_sims.sql`: таблица `custom_sims`
+  (id PK AUTOINCREMENT, owner_id FK users ON DELETE CASCADE, title, description, subject,
+  grade, cat, spec_json TEXT NOT NULL, status TEXT 'draft|published' DEFAULT 'draft',
+  version INT DEFAULT 1, created_at, updated_at) + индексы idx_custom_sims_owner / _status.
+  Идемпотентна (CREATE TABLE/INDEX IF NOT EXISTS).
+- [x] Контроллер `backend/src/controllers/customSimController.js`: list (own + чужой published),
+  get (own ИЛИ published), create (через роут teacher/admin), update, remove. Владение
+  проверяется на каждой мутации (owner ИЛИ admin → иначе 403; нет строки → 404). version++ на update.
+- [x] Серверная валидация спеки `validateSpec(spec)`: размер JSON (≤200KB), `specVersion`=1,
+  лимиты (params≤50, objects≤200, walls≤20, springs≤50, expr≤500 симв., глубина≤8, points≤1000),
+  типы объектов из whitelist (point|segment|vector|circle|rect|polyline|path|label|plot|readout),
+  physics (restitution 0..1, dt 1/2000..1/30, body.mass>0), строки-подписи (text/label/unit/meta/
+  drag.param/param.label) санитизируются как текст (escape &<>, обрезка). Возврат {ok,error?,clean?}.
+  ⛔ Спека НЕ исполняется на сервере (нет eval/Function/SimExpr).
+- [x] Роуты `backend/src/routes/customSims.js`: router-level `authMiddleware` (read auth-only);
+  `GET /` + `GET /:id` (видимость в хендлере); `POST /`, `PUT /:id`, `DELETE /:id` — inline
+  `requireRole('teacher','admin')`. Смонтировано в server.js: `app.use('/api/custom-sims', ...)`.
+- [x] Клиент `js/api.js`: `customSimsList/Get/Create/Update/Delete` → `req(...)` + добавлены в `window.LS`.
+- [x] Тесты `backend/tests/custom-sims.test.js` (24/24 pass): CRUD happy-path, ownership (чужой
+  PUT/DELETE → 403), get чужой draft → 403, get чужой published → 200, admin override, 404,
+  validateSpec (12 кейсов отказа 400), санитизация. Монтирует роут на shared test-app (как lab-links).
 
 ## Files to Modify/Create
 - `backend/src/db/migrations/0NN_custom_sims.sql` (new)
@@ -42,10 +50,47 @@
 - Не делать blanket `router.use(requireRole('admin'))` — read-роуты auth-only, мутации — inline requireRole.
 
 ## Review Checklist
-- [ ] Все задачи выполнены
-- [ ] Ownership и валидация спеки покрыты тестами
-- [ ] Миграция идемпотентна (IF NOT EXISTS / INSERT OR IGNORE где надо)
-- [ ] `npm run lint:routes` чисто; тесты в пределах baseline
+- [x] Все задачи выполнены
+- [x] Ownership и валидация спеки покрыты тестами (24/24)
+- [x] Миграция идемпотентна (CREATE TABLE/INDEX IF NOT EXISTS)
+- [x] `npm run lint:routes` чисто (0 unprotected, baseline 0); тесты в пределах baseline
 
 ## Handoff to Next Phase
-<!-- Заполняет реализатор -->
+
+### Что реализовано (Phase 3)
+- **Миграция 071** `custom_sims` (применена к живой БД `npm run migrate` без ошибок).
+- **API `/api/custom-sims`** (смонтировано в `backend/src/server.js` после `/api/materials`):
+  | Метод | Путь | Доступ | Ответ |
+  |-------|------|--------|-------|
+  | GET | `/api/custom-sims` | auth | `{ sims:[{id,owner_id,title,description,subject,grade,cat,status,version,created_at,updated_at}] }` (свои любого статуса + чужие published; БЕЗ spec) |
+  | GET | `/api/custom-sims/:id` | auth (own ИЛИ published) | `{ sim:{...meta, spec} }` (spec уже распарсен из JSON); чужой draft → 403, нет → 404 |
+  | POST | `/api/custom-sims` | teacher/admin | `201 { id }`; принимает `{ title?, description?, subject?, grade?, cat?, status?, spec }`; кривая спека → 400 |
+  | PUT | `/api/custom-sims/:id` | owner/admin | `200 { ok:true }`; любое поле опц.; `spec` валидируется заново и version++; 403/404 |
+  | DELETE | `/api/custom-sims/:id` | owner/admin | `200 { ok:true }`; 403/404 |
+- **Клиентские методы** (`js/api.js` → `window.LS`): `customSimsList()`, `customSimGet(id)`,
+  `customSimCreate(data)`, `customSimUpdate(id, data)`, `customSimDelete(id)`.
+
+### Форма записи `custom_sims`
+`id`, `owner_id`(FK users CASCADE), `title`, `description`, `subject`, `grade`(INT), `cat`
+(math|phys|chem|bio|game|NULL), `spec_json`(TEXT — валидированный JSON), `status`(draft|published,
+деф. draft), `version`(INT, ++ на каждом update со spec), `created_at`, `updated_at`.
+
+### validateSpec — контракт для Ф4 (билдер)
+Билдер должен слать в `spec` объект формата v1 (specVersion:1, meta, viewport, params[], objects[],
+physics?). Сервер вернёт **400** при: spec не объект; specVersion≠1; >200KB JSON; глубина >8;
+params>50; objects>200; walls>20; springs>50; строка-выражение >500 симв.; недопустимый type
+объекта (вне whitelist point|segment|vector|circle|rect|polyline|path|label|plot|readout);
+restitution вне 0..1; dt вне 1/2000..1/30; body.mass≤0. Текстовые поля (`text`,`label`,`unit`,
+`meta.title/desc`, `param.label/unit/name`, `drag.param/paramY`, `id`) **обрезаются и
+экранируются** (`& < >` → entities) — билдер получит обратно очищенную спеку в `GET /:id`.
+⚠️ Не использовать имя param `e` (зарезервировано в SimExpr — см. Ф2).
+
+### На Ф4 (билдер: какие поля шлёт/получает)
+- **Создание**: `LS.customSimCreate({ title, description?, subject?, grade?, cat?, status?, spec })`
+  → `{ id }`. После — `LS.customSimUpdate(id, { spec, status:'published' })` для публикации.
+- **Загрузка для редактирования**: `LS.customSimGet(id)` → `{ sim }`, где `sim.spec` — готовый
+  объект для монтирования в `SimEngine.mount(host, sim.spec)`.
+- **Список «мои/опубликованные»**: `LS.customSimsList()` → `{ sims }` (метаданные без spec; spec
+  тянуть лениво по `customSimGet`).
+- Билдер должен учитывать, что сервер вернёт спеку **санитизированной** (escaped-текст) — для
+  KaTeX/canvas это безопасно, но при сравнении «до/после» учитывать экранирование.