Ответ Опуса — 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 для значений:

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 должен быть:

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

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

6.4 KiB Raw Blame History Unescape Escape