116 lines
4.6 KiB
Markdown
116 lines
4.6 KiB
Markdown
# 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)
|