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,93 @@
+# Teach flow VM smoke tests
+
+Дата: 26.06.2026 | Проверка isolated teaching flow на VM после внедрения.
+
+## Что проверяли
+
+Проверялся Flask-слой VM через test client с подменой DB-слоя, чтобы подтвердить поведение новых endpoints без риска для боевой БД.
+
+### Проверенные маршруты
+
+- `GET /teach`
+- `GET /teach/api/meta`
+- `GET /teach/api/contracts`
+- `GET /teach/api/context?supplement_id=...`
+- `POST /teach/api/feedback`
+- `GET /teach/api/feedback?contract_id=...&supplement_id=...`
+
+## Результат smoke-test
+
+Все маршруты вернули `200 OK` в mocked окружении.
+
+### `/teach`
+
+- Страница отдала HTML с заголовком `Сверка договоров — обучение`.
+
+### `/teach/api/meta`
+
+Вернуло дефолтные метаданные:
+
+```json
+{
+  "ok": true,
+  "prompt_version": "vm-teach-v1",
+  "model_name": "gpt-oss-120b"
+}
+```
+
+### `/teach/api/contracts`
+
+Вернуло список договоров и допников в ожидаемой структуре:
+- `contract_id`
+- `contract_number`
+- `client`
+- `date_signed`
+- `supplements[]`
+
+### `/teach/api/context`
+
+Вернуло:
+- `supplement`
+- `current_rows`
+- `previous_rows`
+
+### `POST /teach/api/feedback`
+
+Проверена запись feedback со значениями:
+- `scope = row`
+- `verdict = error`
+- `error_type = wrong_price`
+- `field = price`
+- `llm_value` и `correct_value` как JSON
+- `prompt_version = vm-teach-v1`
+- `model_name = gpt-oss-120b`
+- `doc_mode = amendment`
+
+Запись успешно ушла в mock cursor и commit был вызван.
+
+### `GET /teach/api/feedback`
+
+Возвратил сохранённую запись в читаемом JSON виде.
+
+## Что всплыло по окружению
+
+Во время проверки не хватало runtime-зависимостей в VM-venv:
+- `python-dotenv`
+- `Flask`
+- `psycopg2-binary`
+- `httpx`
+- `pdfplumber`
+- `python-docx`
+- `redis`
+
+Эти пакеты были установлены в VM-venv, после чего smoke-test прошёл.
+
+## Вывод
+
+Isolated teaching flow на VM не только компилируется, но и проходит mocked smoke-test по основным endpoint'ам:
+- чтение метаданных,
+- загрузка списка договоров,
+- загрузка контекста допника,
+- запись и чтение feedback.
+
+Старый Lucee-frontend и основной compare pipeline при этом не затрагивались.
@@ -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)