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,123 @@
+# Ответ Опуса — режим «исправление ошибок / обучение»
+
+Дата: 26.06.2025 | В ответ на обсуждение feedback-цикла.
+
+---
+
+## Суть
+
+Режим: **юзер загружает документы → система выдаёт результат → юзер правит ошибки → правки сохраняются**.
+
+Это не «обучение модели», а **накопление эталонных данных** (golden dataset) через естественный интерфейс исправления. Юзер не размечает абстрактно — он правит конкретный неверный результат.
+
+## Что уже есть под это
+
+- LLM возвращает поток операций: `ADD` / `UPDATE` / `DELETE` / `UNRESOLVED`
+- Применяются через событийную модель (`apply_events.cfm`)
+- Правка юзера = **исправленный поток операций**
+- Разница «LLM выдал» vs «юзер поправил» = **чистый сигнал ошибки**
+
+## Три уровня (не путать)
+
+| Уровень | Что | Когда |
+|---------|-----|-------|
+| **Регрессия** | Правки → golden-набор → прогон промпта → % ошибок | Сразу |
+| **Prompt-learning** | Анализ частых ошибок → правка промпта (few-shot/глоссарий) | Периодически |
+| **Fine-tuning** | Дообучение модели на сотнях/тысячах примеров | Не сейчас |
+
+## Чего НЕ делать
+
+- **Автоматически вкручивать правки в промпт** — переобучение, конфликты, рост токенов
+- Правильно: правки → накопитель → куратор анализирует агрегаты → batch-обновление промпта → регрессия
+
+## Что заложить в дизайн
+
+1. **Структурировать тип ошибки:** «пропущена строка», «неверная цена», «UPDATE вместо ADD», «ложный дубликат»
+2. **Версия промпта** при каждом результате — чтобы знать актуальность ошибки
+3. **Конфиденциальность** — реальные договоры с реквизитами копятся в БД, обсудить с заказчиком
+
+---
+
+**Решение:** отложить. Позже вернуться и спроектировать.
+
+---
+
+# Часть 2 — Конкретный UI для отметки ошибок
+
+Дата: 26.06.2025 | Опус изучил реальный вывод (карточка + таблица операций) и предложил привязку к элементам интерфейса.
+
+## Привязка: не к абзацам, а к строкам таблицы операций
+
+Результат — **таблица операций** (`Действие / Услуга / Цена / Кол-во / Сумма / Дата`), а не текст-простыня. Замечание цепляется к строке таблицы, а не к абзацу исходника.
+
+### Как выглядит (на реальном примере)
+
+```
+✓ допник-1-XXX002-01200_3.docx — 2 оп., partial (14с)        [✓ всё верно]
+2 ~0 -0
+
+Действие  Услуга                                  Цена       Кол-во  Сумма      Дата         ⚠
+ADD       WAF: Positive Technologies, в составе…  104021.67  1       104021.67  2026-03-30   [⚠]
+ADD       Облачный диск Valo Cloud, в составе…    68700      1       68700      2026-02-01   [⚠]
+
+                                          [ ➕ Система пропустила позицию ]
+```
+
+### Клик по `[⚠]` → мини-форма под строкой
+
+```
+Тип ошибки:  ( ) неверная цена/сумма
+             ( ) неверное кол-во
+             ( ) неверное наименование услуги
+             (•) лишняя строка — этой операции быть не должно
+             ( ) неверное действие (должно быть UPDATE/DELETE, а не ADD)
+             ( ) неверная дата
+Правильное значение: [_____________]  (необязательно)
+Комментарий:         [_____________]  (необязательно)
+                                              [ Сохранить ]
+```
+
+### `[✓ всё верно]` — вверху карточки
+
+Один клик = положительный сигнал, без расписывания.
+
+### `[➕ Система пропустила позицию]` — под таблицей
+
+Для случая, когда услуга была в документе, но LLM её не извлекла. Открывает форму ввода пропущенной строки.
+
+## Что уходит в базу (обезличенно)
+
+```
+operation: ADD
+service:   "Облачный диск Valo Cloud, в составе…"   ← без названия клиента
+field:     price
+llm_value: 68700
+correct:   68000
+error_type: wrong_price
+prompt_version: v1.0.178
+```
+
+Никаких названий компаний, ФИО, № договора — только структура услуги и числа.
+
+## Почему так, а не поле у каждого абзаца
+
+- Реальный вывод — **таблица**, а не текст. Абзацев нет, есть операции
+- Привязка к операции даёт агрегацию по типу ошибки
+- Готовая дельта «LLM выдала X → правильно Y» как обучающий сигнал
+- Ровная укладка в событийную модель (`apply_events.cfm`)
+
+---
+
+**Решение:** отложить. Ждать «делай» для реализации.
+
+---
+
+# Часть 3 — Текст для заказчика
+
+**Этап опытной эксплуатации (обучение системы)**
+
+На первое время предлагаем режим проверки: вы загружаете реальные документы, система выдаёт результат, а вы отмечаете ошибки — что распознано неверно (пропущена строка, неверная цена, неправильное сопоставление и т.п.).
+
+Эти отметки **в обезличенном виде** (без названий компаний, ФИО, реквизитов и иных персональных данных) накапливаются в базе и используются для дальнейшей настройки и обучения системы.
+
+Это позволит откалибровать сервис на ваших реальных договорах, а не на тестовых примерах, и системно повышать точность.