# Ответ Опуса — isolated training page / feedback storage

Дата: 26.06.2026 | Ответ на вопросы по отдельной странице "обучения" для проекта «Сверка договоров».

## Контекст

- Стек: Lucee/CFML 6.0, файловая маршрутизация (`teach.cfm` → `/teach`), PostgreSQL `baza`.
- Рабочий compare-пайплайн не трогаем: новая фича должна жить полностью изолированно.
- Цель: отдельная страница с тем же UI-скелетом, что и compare results, но с возможностью оставлять замечания по строкам таблицы операций и сохранять их в БД для дальнейшего анализа агентом.

## 1. Минимальная схема `feedback`

Для MVP достаточно плоских колонок для агрегации и `JSONB` для значений:

```sql
CREATE TABLE IF NOT EXISTS feedback (
    id             UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    created_at     TIMESTAMPTZ DEFAULT now(),

    contract_id    UUID,
    supplement_id  UUID,
    event_seq      INTEGER,        -- NULL для missed/document

    scope          TEXT NOT NULL,  -- 'row' | 'missed' | 'document'
    verdict        TEXT NOT NULL,  -- 'correct' | 'error'
    error_type     TEXT,           -- wrong_price|wrong_qty|wrong_name|wrong_date|extra_row|missed_row|wrong_action|wrong_mode
    field          TEXT,           -- price|qty|sum|name|date_start|action|mode

    service_name   TEXT,
    llm_value      JSONB,
    correct_value  JSONB,

    prompt_version TEXT,
    doc_mode       TEXT,           -- partial | full_replace
    comment        TEXT
);
CREATE INDEX IF NOT EXISTS idx_feedback_error  ON feedback(error_type);
CREATE INDEX IF NOT EXISTS idx_feedback_prompt ON feedback(prompt_version);
```

Рекомендуемый фиксированный набор `error_type`:
`wrong_price, wrong_qty, wrong_name, wrong_date, extra_row, missed_row, wrong_action, wrong_mode`.

## 2. UI первой версии vs отложить

### В MVP

- Колонка `⚠` у каждой строки таблицы операций с мини-формой: выбор `error_type` + опционально правильное значение + комментарий.
- Кнопка `[✓ всё верно]` на карточке ДС для положительного сигнала (`scope=document, verdict=correct`).
- Кнопка `[➕ пропущена позиция]` для случая, когда позиция была пропущена (`scope=missed`).

### Отложить

- Инлайн-редактирование значений прямо в ячейках.
- Статистика и дашборды на самой странице.
- Модерация замечаний, роли, удаление чужих записей.
- Разбор новых загрузок на этой странице; работать только по уже разобранным документам из БД.

## 3. Связь с исходной операцией

Правильная связь — логическая, без FK и без вмешательства в рабочий pipeline: `(contract_id, supplement_id, event_seq)`.

Почему так:

- `spec_events` уже хранит операции как `spec_events(contract_id, supplement_id, seq, action, new_values, ...)`.
- `feedback` просто повторяет эти значения как обычные поля.
- Без FK исключается риск связать feedback с жизненным циклом боевых событий или сломать вставки при повторном разборе.

Если `event_seq` когда-то переедет из-за пересборки данных, в `llm_value` / `correct_value` нужно сохранять снимок операции (`action` + `new_values`), чтобы замечание оставалось интерпретируемым.

## 4. `prompt_version`

Версию промпта хранить нужно, иначе нельзя считать регрессию между изменениями.

Но сейчас результат разбора не штампуется версией промпта, поэтому для MVP предлагается практический компромисс:

- `/teach` при сохранении замечания пишет текущую активную версию промпта из БД.
- Это честно помечается как версия на момент проверки, а не на момент исходного разбора.
- Правильная фиксация `prompt_version` в результате разбора — отдельная задача основного pipeline, не часть isolated feedback flow.

## 5. Что исключить

### PII / обезличивание

- Не хранить название/ИНН клиента, номер договора, ФИО, подписантов, реквизиты, email, телефоны.
- Не хранить оригинальный текст документа и байты файла.

### Изоляция рабочих данных

- Не использовать `ALTER` существующих таблиц.
- Не добавлять FK, триггеры или write-логики в `spec_events`, `spec_current`, `contracts`, `supplements`.
- `/teach` должен писать только в `feedback` через отдельный параметризованный endpoint.

## Итог

Опус подтвердил, что MVP должен быть:

1. Отдельной страницей с тем же UX-скелетом, что и compare results.
2. Отдельным write endpoint и отдельной таблицей `feedback`.
3. Полностью изолированным от рабочего compare-пайплайна.
4. Приспособленным для SQL-аналитики агентом через плоские колонки + `JSONB`.

Главный принцип: это не online-training, а сбор структурированного feedback для последующего анализа и планирования изменений.