Learn_System/plans/exam-textbook-links/PLAN.md

# План: точная привязка задач экзамена math9 к § учебников

> Составлен Opus 2026-06-03 по итогам discovery. Исполнитель — Sonnet, по фазам, с верификацией.
> Эталон §-таксономии: `plans/exam-textbook-links/taxonomy.md` (читаемая) и
> `backend/scripts/data/g9_textbook_sections.json` (машиночитаемая: {chapter_slug, subject, grade, para_id, num, title}).

## Контекст (проверено по коду/БД)

- `exam_tasks`: 800 задач `math9`, у ВСЕХ заполнен `subtopic` (16 подтем) и `topic`.
- Текущая связь — КОСВЕННАЯ и грубая: `exam_tasks.subtopic` → `exam_topics.slug` → один
  `textbook_slug`+`textbook_paragraph` на всю подтему (миграция 028). Контроллер
  `backend/src/routes/exam-prep.js` штампует `topic_ref` через `getTopicRefMap()`/`shapeTask()`.
  Фронт `frontend/js/exam-prep/task-card.js:42` строит ссылку `/textbook/<slug>#sec-p<N>`.
- Покрытие сейчас: 546/800 → конкретный §, 158 → только хаб `algebra-9` (alg-numbers/arithmetic/
  powers/polynomials/word-problems), 96 (theory-statements) → никуда.
- Экзамен 9 кл. проверяет программу 5–9, а интерактивный учебник 9 кл. — только материал 9 года.
  Учебники 5–11 все есть (см. dump в discovery). Для math9 релевантны 5–9.

### Готчи нумерации § (ВАЖНО для классификатора и ссылок)
- **algebra-7, algebra-9, geometry-7, geometry-9** — СКВОЗНАЯ нумерация `sec-pN` по всему учебнику,
  но каждый § физически лежит в своём файле-главе. Ключ ссылки = (slug-главы, pN).
- **geometry-8** — ПОГЛАВНАЯ нумерация (каждая глава заново `sec-p1`). Поэтому ОБЯЗАТЕЛЬНО
  (slug-главы, pN-внутри-этого-файла). JSON-таксономия уже хранит правильную пару.
- **algebra-8** — сквозная (`sec-p1..p18` по 3 главам).
- **math-5 / math-6** — рендерятся движком `frontend/js/math6_engine.js`
  (`<section id="sec-"+p.id>`, p.id из `window.M6.paras`). Статических `sec-pN` в файле нет.
  Якорь = `sec-<p.id>`. Если нужно вести в math-5/6 — para_id брать из конфига M6 главы.

### КРИТИЧНО: deep-link сейчас НЕ РАБОТАЕТ
- Статические страницы algebra/geometry (`algebra_9_ch3.html` и т.п.) подключают только
  katex/api.js/xp.js — **`textbook-tracker.js` там НЕ подключён**. Их `init()` всегда
  вызывает `goTo('p10')` и `location.hash` ИГНОРИРУЕТ. Используют `.psel-card[data-id]`.
- `textbook-tracker.js` (есть на math-5/6) `handleHashNav()` матчит только `/^#(p\d+)$/`
  (т.е. `#pN`, НЕ `#sec-pN`) и кликает `.para-pill[data-para]`.
- exam-prep строит `#sec-pN`. → ссылка ведёт на главу, но НЕ открывает нужный §.
- Сервер отдаёт `/textbook/:slug` обычным `sendFile` (инъекция только при `?embed=1`,
  см. `backend/src/server.js:437`). Есть `_renderEmbed()` + `_embedCache`.

## Цель
Каждая из 800 задач math9 ведёт на наиболее подходящий § учебника 5–9, и клик реально открывает этот §.

---

## Фаза 1 — Починить навигацию deep-link  (prerequisite; без неё связь невидима)
Централизованный хелпер, внедряемый СЕРВЕРОМ в HTML учебника для всех режимов `/textbook/:slug`.
- `backend/src/server.js`: обобщить выдачу — всегда читать файл и инжектить
  `<script id="__ls_deeplink__">…</script>` перед `</head>` (или перед `</body>`), кэш по
  (filePath, mode='plain'|'embed'). Сейчас в обычном режиме `sendFile` — заменить на read+inject+send
  c теми же no-store заголовками. Embed-инъекция остаётся как есть, плюс этот же хелпер.
- Хелпер (vanilla, идемпотентный): на `DOMContentLoaded` (+ небольшой setTimeout, чтобы билдеры/
  движок успели построить карточки) и на `hashchange`:
  - распарсить `location.hash`: принять `#sec-pN` И `#pN` → нормализовать к `id = 'p'+N`;
  - навигация по приоритету: `document.querySelector('.psel-card[data-id="'+id+'"]')?.click()`
    → иначе `.para-pill[data-para="'+id+'"]'`?.click() → иначе `window.goTo?.(id)` →
    иначе `getElementById('sec-'+id)?.scrollIntoView()`.
  - не запускать дважды; не конфликтовать с textbook-tracker (тот матчит `#pN` — наш хелпер
    дополнительно поддержит `#sec-pN`). Если на странице есть textbook-tracker и хэш в форме
    `#pN`, можно отдать навигацию ему (наш хелпер сработает как фолбэк, клик идемпотентен).
- НЕ ломать embed-bridge (`ls_tb_nav`/`ls_tb_apply`). Хелпер ставить ПОСЛЕ страничных скриптов.
- Проверка: `/textbook/algebra-9-ch3#sec-p13` открывает §13 (метод интервалов), не §10;
  `/textbook/geometry-8-ch2#sec-p4` открывает «Площадь треугольника».

## Фаза 2 — Схема: per-task anchor
- Миграция `backend/src/db/migrations/0NN_exam_task_textbook.sql`:
  `ALTER TABLE exam_tasks ADD COLUMN textbook_slug TEXT;`
  `ALTER TABLE exam_tasks ADD COLUMN textbook_paragraph INTEGER;`
  (ADD COLUMN — без пересборки; runner оборачивает в транзакцию.)
- `npm run migrate` на живой БД.

## Фаза 3 — Эвристический классификатор (ядро)
`backend/scripts/tag-exam-textbook.js` (по образцу существующего `tag-exam-tasks.js`):
- Грузит `backend/scripts/data/g9_textbook_sections.json` (§-таксономия 7–9).
- Для каждой задачи math9: `stripText(text_html)` (как в tag-exam-tasks.js) + `subtopic` →
  выбрать (slug, para):
  1. По `subtopic` → набор кандидатных глав/§ (карта ниже).
  2. Внутри кандидатов — keyword-скоринг по тексту (ключевые слова из § titles + синонимы:
     «дискриминант/Виета»→квадратные, «процент»→math-6 проценты, «синус/косинус/теорема»→geometry-9,
     «прогресс/разность d/знаменатель q»→прогрессии §15/§17, «параллелограмм/ромб/трапеция»→geometry-8-ch1, …).
  3. Фолбэк: primary § подтемы (если уверенного матча нет).
- Флаги: `--exam math9`, `--dry-run`, `--report` (распределение по §, сколько без §).
  Идемпотентно перезаписывает `exam_tasks.textbook_slug/paragraph`.

### Карта subtopic → primary §/главы (исправляет ошибки 028)
- `alg-numbers` → math-6 (рацион. числа) / math-5 (натуральные) по тексту; иначе хаб `math-6`.
- `alg-arithmetic` → math-5/6.
- `alg-powers` → `algebra-7-ch1` §1 (натур.), §2 (целый показатель), §3 (станд. вид).
- `alg-expressions` → `algebra-7-ch2` §4–5 / `algebra-9-ch1` §5 (преобр. рацион.).
- `alg-polynomials` → `algebra-7-ch2` §8–14 (одночлены/многочлены/ФСУ/разложение).
- `alg-fractions` → `algebra-9-ch1` §1–5 (рацион. дроби) ИЛИ math-6 (обыкн. дроби) по тексту.
- `alg-equations` → линейные `algebra-7-ch3` §15; квадратные `algebra-8-ch2` §7–9;
  дробно-рацион. `algebra-9-ch3` §10; системы `algebra-7-ch4` §23–24 — по тексту.
- `alg-inequalities` → `algebra-8-ch3` §13–18; метод интервалов `algebra-9-ch3` §13 / `algebra-8-ch3` §17.
- `alg-functions` → линейная `algebra-7-ch3` §19–20; свойства/графики `algebra-9-ch2` §6–9.
- `alg-progressions` → `algebra-9-ch4`: арифм. §15/§16, геом. §17–19 (по «d»/«q»).
- `alg-word-problems` → по теме: проценты→`math-6-ch2`; уравнением→`algebra-7-ch3` §16;
  системой→`algebra-7-ch4` §25; квадратным→`algebra-8-ch2` §11.
- `geom-triangles` → признаки `geometry-7-ch2`; Пифагор `geometry-8-ch2` §11; подобие `geometry-8-ch3`;
  тригонометрия пр. треуг. `geometry-9-ch1` — по тексту.
- `geom-quadrilaterals` → `geometry-8-ch1` §4–16 (паралл./прямоуг./ромб/квадрат/трапеция);
  вписанные/описанные `geometry-9-ch2` §9.
- `geom-circle` → `geometry-8-ch4` (вписанные углы и т.п.) / `geometry-9-ch2`.
- `geom-coordinates` → уравнение окружности `algebra-9-ch3` §12; координаты — geometry/algebra по тексту.
- `theory-statements` → распределить по теме утверждения (тот же скоринг); иначе оставить NULL
  (фолбэк на subtopic-уровень, см. Фазу 5).

## Фаза 4 — Контроллер: предпочесть task-level
`backend/src/routes/exam-prep.js`:
- В SELECT задач (`getVariantTasks`, `practiceRandom/Unsolved`, `pickRandomByDifficulty`,
  `topicTasks*`, `weakBatchTasks`, `getTasksByIds`) добавить `t.textbook_slug, t.textbook_paragraph`.
- `shapeTask()` и формирование `topic_ref` в `/variants/:n/tasks`: если у задачи есть
  `textbook_slug` → `topic_ref = { title, slug: task.textbook_slug, paragraph: task.textbook_paragraph }`
  (title — из таксономии § или из подтемы), иначе фолбэк на `refMap.get(subtopic)`.
- Title для task-level: можно прокинуть из классификатора в отдельную таблицу/JSON или
  собрать map para→title из таксономии при старте (как `getTopicRefMap`).

## Фаза 5 — Улучшить subtopic-фолбэк (миграция данных)
- Новая миграция: переписать `exam_topics.textbook_slug/paragraph` корректно (исправить
  `alg-equations`→дробно-рацион. только частный случай и т.п.), заполнить хаб-only разумным §.
  Это фолбэк для задач, которым классификатор не дал task-level.

## Фаза 6 — Тесты + верификация
- `backend/tests/exam-textbook-links.test.js`: миграция применилась (колонки есть);
  после классификатора ≥90% задач имеют `textbook_slug` (или явно объяснённый остаток);
  `GET /:examKey/variants/:n/tasks` отдаёт `topic_ref` с `paragraph` для размеченных задач;
  ссылка формата `/textbook/<slug>#sec-p<N>` для валидного slug из таблицы textbooks.
- Прогон `node tag-exam-textbook.js --report` — приложить распределение.
- `node --test tests/*.test.js` в рамках baseline (3 Auth + флака «intro» chemistry8).
- Перезапуск сервера (подхватить миграцию + новые SELECT-поля; `_topicRefCache` для фолбэка).

## Ограничения исполнителю (Sonnet)
- БД: встроенный `node:sqlite` (DatabaseSync), НЕ better-sqlite3.
- Большие файлы (server.js, exam-prep.js, HTML) — ТОЛЬКО точечный `Edit`, НЕ Write целиком.
- ⛔ Без эмоджи; иконки — только inline SVG `.ic`.
- Миграции — ADD COLUMN/UPDATE; НЕ пересобирать users/центральные таблицы.
- `fetch` origin перед работой (в master параллельно коммитят другие сессии); `git add` поимённо.
- Поиск: ast-index/Read, НЕ Grep tool. Каждый Edit верифицировать.
- Коммитить поэтапно осмысленными сообщениями + push (CLAUDE.md), трейлер
  `Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>`.