Learn_System/plans/my-materials/PLAN_V2.md

«Мои материалы» — v2: харднинг и доводка

Составлен Opus 2026-06-13. Базовый план (PLAN.md, Фазы 1–6) полностью реализован. Его раздел «Сквозные риски» отложил ровно то, что закрывает этот план: учёт/лимиты/чистку хранилища и materials.test.js. Источник истины по текущему состоянию — код (studentMaterialsController.js, materials.js, my-materials.html, board-clip.js, material-save.js) и reference_student_materials.

Готчи проекта: новый :id-роут → // @public-by-design + проверка владельца; большие HTML — только Edit; без эмодзи (inline SVG .ic); коммит поимённо + push; перезапуск сервера при правке backend; ветка feature/sim-builder в рабочем дереве — НЕ коммитить чужие правки, только свои файлы.

---

Фаза 1 — Целостность и безопасность (backend, фундамент) ✅ цель этого захода

1. Ссылочно-подсчётная чистка файлов. DELETE /:id и смена url (аннотация) сейчас оставляют файл в uploads/materials/ сиротой. share копирует url дословно → несколько строк ссылаются на ОДИН файл, поэтому unlink только когда на url не ссылается ни одна строка. Хелпер releaseFileForUrl(url) вызывается ПОСЛЕ delete/update.
2. Allowlist схемы URL. create/update принимали любой url → link со схемой javascript: рендерится как рабочий <a href> (раздача делает это вектором учитель→ученики). Хелпер safeUrl: только http(s):// или app-relative /… (не //host); иначе 400.
3. Квота на пользователя. Колонка bytes (мигр. 073), счёт SUM(bytes)/COUNT(*). Лимит по числу материалов — в create(); лимит по байтам — в uploadPersonalFile (до приёма файла). Конфигурируемо через MATERIALS_MAX_ITEMS / MATERIALS_MAX_BYTES (для тестов — низкий потолок).
4. backend/tests/materials.test.js — CRUD, владелец (403/404), коллекции, share-копия + роль/owner, валидация URL, лимит числа, ссылочная чистка (прямой вызов хелпера на временном файле).

Фаза 2 — Производительность ✅ (частично)

• ✅ GET /api/materials отдаёт обрезанный body (первые 1000 симв.) + флаг body_trunc; полный текст — ленивый GET /api/materials/:id (getOne, owner-only). Клиент ensureFullBody() подгружает перед просмотром/правкой/флешкартой (иначе правка сохранила бы усечённый текст).
• ⬜ Пагинация/keyset — отложено (клиент пока фильтрует в памяти; включить при росте объёмов).
• ⬜ Серверные миниатюры board/image — отложено (нужна обработка картинок; пока loading=lazy).

Фаза 3 — Доводка заложенных фич ✅

• ✅ UI тегов: ввод в модалках создания/правки + чипы на карточке (клик → фильтр) + пилюля активного фильтра.
• ✅ Ссылка «открыть исходный урок» на карточке (/my-lessons?session=<id>, есть source_session_id).
• ✅ Цвет папки (палитра 8 пресетов, тинт иконки в рейле) + сортировка папок «Выше/Ниже» в модалке правки (нормализует sort_order к индексам). safeColor гейтит inline-style инъекцию (только hex).

Фаза 4 — UX ✅

• ✅ Варианты сортировки (новые/старые/имя/тип) — селект в тулбаре.
• ✅ Множественный выбор (чекбокс на карточке) + панель массовых действий (переместить/удалить, reuse per-item API).
• ✅ Живое превью KaTeX в редакторе заметки (oninput → mmPreview → mathHtml).

Статус

Сделано и проверено: Ф1 целиком (16 backend-тестов), Ф2/Ф3/Ф4 ✅ (headless-смоук my-materials.html: синтаксис + рендер карточек с deep-link/тегами/чекбоксом + фильтр по тегу + bulk-bar + тинт папки). Осталось ⬜ (инфра, отложено): пагинация/keyset списка, серверные миниатюры board/image.

---

Порядок

Ф1 (этот заход) → Ф2 → Ф3 → Ф4. Ф1 — серверный фундамент (риск-возврат, без него фронт-фичи множат мусор). Дальше преимущественно фронтенд my-materials.html + точечные ручки API.