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 при этом не затрагивались.