docs: архитектурный анализ + History + gitignore (2026-06-27)

2026-06-27 13:00:18 +04:00
parent 4a21d77f51
commit 82c5c075f1
154 changed files with 4789 additions and 1443 deletions
@@ -0,0 +1,115 @@
+# 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)