# Feature: isolated teaching flow on VM

Дата: 26.06.2026 | Переход от обсуждения идеи feedback-learning к реальному isolated-flow на VM.

## Что решили

- Lucee-mordа не трогаем.
- Новая страница обучения живёт на VM по прямому URL.
- Рабочий compare pipeline не меняем.
- Feedback пишется только в отдельную таблицу `feedback`.
- Для аналитики сохраняем `prompt_version` и `model_name`.
- Значения по умолчанию берём из VM metadata endpoint / env, а не из Lucee.

## Что сделано

### 1. Изолированный Flask blueprint

Добавлен новый blueprint `teach_bp` в VM-слой:
- `/teach` — отдельная страница обучения.
- `/teach/api/meta` — дефолтные метаданные для страницы.
- `/teach/api/contracts` — список договоров и допников.
- `/teach/api/context` — текущие строки спецификации и предыдущие строки для выбранного допника.
- `/teach/api/feedback` — чтение и запись feedback.

Файлы:
- [contracts-app/site/teach.py](../../contracts-app/site/teach.py)
- [contracts-app/site/app.py](../../contracts-app/site/app.py)

### 2. Отдельная таблица feedback

Добавлена таблица `feedback` в DDL приложения. В ней хранятся:
- `contract_id`
- `supplement_id`
- `event_seq`
- `scope`
- `verdict`
- `error_type`
- `field`
- `service_name`
- `llm_value`
- `correct_value`
- `prompt_version`
- `model_name`
- `doc_mode`
- `comment`

Файл:
- [contracts-app/site/schema.py](../../contracts-app/site/schema.py)

### 3. Teach UI

Добавлена отдельная страница:
- список договоров и допников слева;
- таблица строк спецификации справа;
- кнопка `⚠` у строки для замечания;
- кнопка `✓ Всё верно`;
- кнопка `➕ Пропущена позиция`;
- отдельная форма для комментария и correct value;
- автоматический bootstrap metadata через `/teach/api/meta`.

Файл:
- [contracts-app/site/templates/teach.html](../../contracts-app/site/templates/teach.html)

### 4. Метаданные обучения

Сделан безопасный fallback:
- `prompt_version` по умолчанию: `vm-teach-v1`
- `model_name` по умолчанию: `gpt-oss-120b`
- можно переопределить через URL: `?prompt_version=...&model=...`
- можно переопределить через env:
  - `TEACH_PROMPT_VERSION`
  - `TEACH_MODEL_NAME`

### 5. Миграции без риска

Чтобы не ломать уже существующую БД, добавлены:
- `ALTER TABLE feedback ADD COLUMN IF NOT EXISTS prompt_version TEXT`
- `ALTER TABLE feedback ADD COLUMN IF NOT EXISTS model_name TEXT`

## Проверки

Синтаксис VM-файлов проверен через `python3 -m py_compile`:
- `app.py`
- `teach.py`
- `schema.py`
- `db.py`
- `api.py`
- `upload.py`
- `extractor.py`
- `differ.py`
- `test_routes.py`

Ошибок нет.

## Что важно не перепутать

- Старая Lucee-морда не нужна для этой фичи.
- Обучение открывается по прямому URL на VM.
- Никакого вмешательства в compare/upload pipeline нет.
- `feedback` — отдельная аналитическая шина, не часть боевого event sourcing.

## Что ещё осталось

- Подключить реальный smoke-test к VM endpoint'ам и проверить insert/select на живой БД.
- Если нужно, сделать отдельный read-only список накопленного feedback для агента.
- При желании можно later подтянуть prompt/model metadata не из URL/env, а из отдельной VM-конфигурации.

## Ключевые файлы

- [contracts-app/site/app.py](../../contracts-app/site/app.py)
- [contracts-app/site/schema.py](../../contracts-app/site/schema.py)
- [contracts-app/site/teach.py](../../contracts-app/site/teach.py)
- [contracts-app/site/templates/teach.html](../../contracts-app/site/templates/teach.html)
- [contracts-app/site/llm_client.py](../../contracts-app/site/llm_client.py)
- [contracts-app/site/extractor.py](../../contracts-app/site/extractor.py)