Learn_System/plans/my-materials/PLAN.md

# План развития «Мои материалы»

> Составлен Opus 2026-06-04. Базис уже есть: `student_materials(kind board|note|link|image,
> title, body, url, source_session_id, source_title, created_at)`, API `/api/materials`
> (GET/POST/DELETE) + `LS.listMaterials/saveMaterial/deleteMaterial`, страница `/my-materials`,
> модуль `/js/board-clip.js` (сохранение страницы/фрагмента доски), сохранение из `my-lessons.html`
> и живого урока `classroom.html`. См. [[reference_student_materials]].

Следующая миграция: **061**. Готчи: новый `:id`-роут → пометить `// @public-by-design` (route-auth lint);
большие HTML-файлы — только Edit; без эмодзи; коммит поимённо + push; перезапуск сервера при правке backend.

---

## Фаза 1 — Переименование, правка, создание заметки  (S, фундамент)
Базовые операции над материалом + личный блокнот.
- **Backend:** `PATCH /api/materials/:id` (поля: title, body, collection_id, tags) с проверкой владельца;
  пометить `@public-by-design`. Хелпер `LS.updateMaterial(id, data)`.
- **Frontend `/my-materials`:** инлайн-правка заголовка; модалка правки текста заметки; кнопка
  **«+ Заметка»** (создать заметку с нуля → POST kind='note'). Карточкам — меню (правка/удалить).
- Зависимостей нет. Делается первым.

## Фаза 2 — Коллекции (папки) + поиск/фильтры  (M, организация)
Решение: **коллекции (папки)** как основной примитив + свободный поиск + фильтр по типу.
Теги — опциональный стретч (поле `tags TEXT`, чипы), если понадобится.
- **Миграция 061:** `material_collections(id, user_id, name, color, sort_order, created_at)` +
  `ALTER student_materials ADD COLUMN collection_id INTEGER REFERENCES material_collections(id) ON DELETE SET NULL`
  (+ опц. `ADD COLUMN tags TEXT`).
- **Backend:** CRUD коллекций `GET/POST/PATCH/DELETE /api/materials/collections`; перенос материала —
  через `PATCH /api/materials/:id {collection_id}`; список `GET /api/materials?collection=ID`.
- **Frontend:** слева/сверху список коллекций (создать/переименовать/цвет/удалить), «Переместить в…»
  на карточке, фильтр по коллекции + поиск по тексту + фильтр по типу (клиент, данных немного).
- Делается после Ф1 (нужна перед «универсальным буфером», иначе всё свалится в одну кучу).

## Фаза 3 — Универсальный буфер «Сохранить к себе»  ⭐ (M–L, стратегически)
Кнопка «В мои материалы» по всей платформе. Общий клиентский модуль + поэтапная разводка по источникам.
- **Модуль `/js/material-save.js`:** `MaterialSave.note({title,body,...})`, `.link({title,url})`,
  `.image({title,blobOrUrl})`, и `MaterialSave.button(opts)` (готовая кнопка). Поверх `LS.saveMaterial`.
  Везде проставлять `source_title` (откуда сохранено).
- **Источники (по убыванию ценности, разводить инкрементально):**
  1. Учебник (`/textbook/...`): «В мои материалы» на § → kind='link' (`/textbook/slug#sec-pN`), на рисунок/
     выделенный фрагмент → kind='image'/'note'.
  2. Экзамен (exam-prep): сохранить задачу+решение → kind='note' (html в body) или 'link' на задачу.
  3. Лаборатория/симуляция, флешкарты, вложения чата урока → link/image.
- **Kinds:** переиспользуем существующие (note/link/image), чтобы не трогать CHECK. Новый kind — только
  при явной нужде (тогда миграция-пересборка CHECK).
- Делать: модуль + 2–3 топ-источника (учебник, экзамен, ссылка) в первой итерации; остальное — добивать.

## Фаза 4 — Редактирование и аннотации  (M, синергия с SVG-рисовалкой)
Рисовать поверх сохранённого изображения и создавать рисунки.
- **`/js/svg-draw.js`:** добавить `opts.bgImage` (рисунок-подложка) + при экспорте компоновать
  подложку + вектор в один PNG (offscreen canvas).
- **Frontend `/my-materials`:** на image-карточке «Аннотировать» → модалка SvgDraw(bgImage=url) →
  сохранить как НОВЫЙ материал (kind='image'). Кнопка «Создать рисунок» (пустой холст → image).
- Подпись/комментарий к материалу — уже покрывается правкой title/body из Ф1.
- Зависит от Ф1 (правка) и существующих svg-draw.js/svg-sanitize.js.

## Фаза 5 — Учебная интеграция  (M)
Превратить материал в инструмент повторения.
- **«В флешкарты»:** из заметки создать карточку (front=title, back=body) в выбранной/личной колоде —
  через существующий API флешкард (decks/cards). Из image — карточка с картинкой.
- **«Учить из материалов»:** лёгкий режим перелистывания заметок/карточек.
- (Полноценный SRS — отдельная инициатива из экзамена; здесь не блокер.)
- Зависит от API флешкард (проверить контракт).

## Фаза 6 — Учитель: своя коллекция + «раздатка»  (S + M–L)
- **6a (S): своя коллекция учителю.** Подключить `board-clip.js` в `lesson-history.html` (страница
  учителя) → кнопки «Область»/«К себе» учителю. Раздел «Мои материалы» уже user-agnostic (показать
  пункт сайдбара и учителю). Быстрый вин, можно сделать рано.
- **6b (M–L): «Раздатка» — отправить материал ученику/классу.**
  - Модель: **копия при отправке** (проще и согласуется с «у каждого своя копия»): `POST /api/materials/:id/share
    {classId|userId}` → вставляет копию в `student_materials` получателям (source_title='Раздатка: <учитель>').
    Без новой таблицы шеринга. (Альтернатива — таблица `material_shares` со ссылкой; копия проще.)
  - Уведомление получателям через существующую систему (`emit`/notifications).
  - Frontend: на материале учителя «Раздать» → выбор класса/ученика.

---

## Рекомендованный порядок
**1 → 2 → 3 → 6a (быстрый вин) → 4 → 5 → 6b.**
Ф1 (правка/заметки) и Ф2 (коллекции+поиск) — фундамент; Ф3 (универсальный буфер) — главный стратегический
шаг, но после Ф2 (иначе захламит); 6a дешёвый — можно вклинить рано; 4/5 — обогащение; 6b (раздатка) — крупное, в конце.

## Сквозные риски / заметки
- **Хранилище:** изображения идут в `/api/files`; универсальный буфер + раздатка-копии множат файлы —
  заложить (позже) учёт/лимиты/чистку.
- **Route-auth lint:** новые `:id`-роуты (PATCH, share) пометить `@public-by-design` + проверка владельца.
- **CHECK kind:** держимся в note/link/image, чтобы не пересобирать таблицу.
- **Тесты:** добавить `materials.test.js` (CRUD + collections + share-копия + проверка владельца).
- **Разрешения:** create-note/правка — любой авторизованный (свои); раздатка — teacher/admin.