# AI First Layer GUI — Подробный гайд пользователя

Дата: 23.03.2026  
Контур: `X:\1C\NDC_1C\llm_normalizer`  
Назначение: локальный GUI и backend для нормализации бухгалтерских запросов через OpenAI token

---

## 1. Что это за система

`AI First Layer GUI` — это не чат-бот с финальными бухгалтерскими ответами.  
Это **semantic front-end**: слой, который переводит живой запрос бухгалтера в строгий структурированный JSON (`normalized_query_v1`), чтобы дальше этот JSON использовал deterministic router/оркестрация.

Цепочка:

`Пользователь -> GUI -> backend-proxy -> OpenAI Responses API -> normalized JSON -> route_hint summary -> trace/history`

---

## 2. Из чего состоит система

1. `frontend` (React + TypeScript + Vite) — русифицированный UI.
2. `backend` (Node.js + Express) — прокси к OpenAI, валидация схемы, trace/eval.
3. `data/traces` — история нормализаций.
4. `data/presets` — сохраненные prompt-пресеты.
5. `data/eval_cases` — eval-кейсы и отчеты.

---

## 3. Быстрый запуск

### 3.1 Рекомендуемый способ (из одной папки в VS Code)

Открой папку:

`X:\1C\NDC_1C\llm_normalizer`

Дальше:

1. `Terminal -> Run Task -> NDC: Install All` (первый запуск).
2. `Terminal -> Run Task -> NDC: Dev All (Backend + Frontend)`.

Открой:

- GUI: `http://localhost:5174`
- Backend health: `http://localhost:8787/api/health`

### 3.2 Терминалом (без Tasks)

```powershell
cd X:\1C\NDC_1C\llm_normalizer
start-dev.cmd
```

или:

```powershell
cd X:\1C\NDC_1C\llm_normalizer
npm.cmd run dev:all
```

---

## 4. Главный сценарий использования

1. В панели **Подключение OpenAI** вставь API key и проверь связь.
2. В панели **Prompt Manager** выбери/подгрузи preset или отредактируй prompt-ы вручную.
3. В панели **Запрос пользователя** вставь живой бухгалтерский вопрос.
4. Нажми `Normalize`.
5. Проверь результат во вкладках `Normalized JSON`, `Route hint summary`, `Validation`.
6. При необходимости сохрани кейс: `Normalize + Save as test case`.
7. Открой историю и сравни trace между попытками.

---

## 5. Подробно по каждому блоку GUI

## 5.1 Connection Panel (Подключение OpenAI)

### Поля

| Поле | Что вводить | Для чего |
|---|---|---|
| `OpenAI API Key` | реальный ключ формата `sk-...` | backend использует ключ для вызова Responses API |
| `Model ID` | обычно `gpt-4o-mini` | модель normalizer-а |
| `Base URL` | обычно `https://api.openai.com/v1` | endpoint OpenAI API |
| `Temperature` | чаще `0` или `0.1` | стабильность/вариативность нормализации |
| `Max output tokens` | обычно `500-900` | лимит длины ответа модели |

### Кнопки

| Кнопка | Что делает |
|---|---|
| `Сохранить локальную конфигурацию` | сохраняет в localStorage только model/baseUrl/temperature/maxOutputTokens (без API key) |
| `Проверить подключение` | вызывает `POST /api/openai/test-connection`, проверяет доступ к модели |

### Рекомендация на старт

- `Model ID`: `gpt-4o-mini`
- `Temperature`: `0`
- `Max output tokens`: `700`

---

## 5.2 Prompt Manager

Это управляемая prompt-архитектура из 3 уровней + служебные поля.

### Поля

| Поле | Что писать | Практический смысл |
|---|---|---|
| `Системный prompt` | жесткие правила поведения модели | запрещает модели давать финальный бизнес-ответ |
| `Developer / Instruction prompt` | правила классификации, flags, route_hint | задает “инженерную логику” нормализации |
| `Domain prompt` | словарь бухгалтерских формулировок/счетов/паттернов | повышает доменную точность |
| `Schema notes` | ограничения схемы, важные enum/required | снижает риск невалидного JSON |
| `Few-shot examples` | пары “вопрос -> ожидаемый JSON фрагмент” | стабилизирует поведение на сложных формулировках |

### Управление пресетами

| Элемент | Что делает |
|---|---|
| dropdown `Выберите preset` | список сохраненных пресетов + default |
| `Загрузить preset` | подставляет выбранные prompt-ы в поля |
| `Сохранить preset` | сохраняет текущие prompt-ы в `data/presets` |
| `Diff с предыдущим` | показывает текстовую дельту относительно последнего загруженного |
| `Сбросить к default` | возвращает дефолтный набор prompt-ов |

---

## 5.3 User Query Panel (Запрос пользователя)

### Поля

| Поле | Что вводить | Для чего |
|---|---|---|
| `Raw user question` | живой вопрос бухгалтера “как есть” | основной вход normalizer-а |
| `Optional period context` | период, если хочешь явно подсказать (`2020-06`) | стабилизирует `period_scope` |
| `Optional business context` | краткая доп. рамка (например “предзакрытие июня”) | помогает интерпретации |
| `Optional expected route` | ожидаемый route для проверки | используется в eval/trace |

### Переключатель

| Переключатель | Когда использовать |
|---|---|
| `Mock-режим (без вызова OpenAI)` | когда тестируешь UI/поток без токена и без внешних запросов |

### Кнопки

| Кнопка | Что делает |
|---|---|
| `Normalize` | запускает нормализацию и возвращает structured output |
| `Normalize + Save as test case` | дополнительно сохраняет кейс в `data/eval_cases` |

---

## 5.4 Output Panel (вкладки результата)

| Вкладка | Что показывает | Как использовать |
|---|---|---|
| `Normalized JSON` | итоговый валидированный JSON | основной артефакт для router |
| `Raw model output` | сырой ответ модели | диагностика prompt/schema проблем |
| `Route hint summary` | краткий срез intent/route/flags | быстрый контроль маршрутизации |
| `Validation` | статус schema validation и ошибки | сразу видно валиден ли контракт |
| `Logs` | клиентские события UI | оперативная диагностика шага |

---

## 5.5 Runtime Metrics Panel

Показывает:

- `trace_id`
- `request_started_at`
- `request_finished_at`
- `latency_ms`
- `input_tokens / output_tokens / total_tokens`
- `validation_status`
- `prompt_version`
- `schema_version`

Как читать:

1. `validation_status = passed` — можно использовать JSON в downstream пайплайне.
2. Если latency резко растет — обычно слишком длинный prompt/few-shot.
3. `total_tokens` нужен для контроля стоимости.

---

## 5.6 History Panel

Показывает список прошлых нормализаций:

- короткий вопрос,
- route hint,
- validation pass/fail,
- модель,
- timestamp.

Клик по записи открывает полный trace (`GET /api/history/:trace_id`) и подгружает данные в Output.

---

## 5.7 NDC Run Monitor

Это отдельный совместимый слой под будущую интеграцию в `dc_node`.

Что можно делать:

1. `Запустить run` -> `POST /api/accounting-agent/v1/runs/start`
2. `Завершить выбранный run` -> `POST /api/accounting-agent/v1/runs/finish`
3. Смотреть список `runs`, их статусы и trace выбранного `runId`.

Канон статусов:

`NONE`, `QUEUED`, `RUNNING`, `DONE`, `ERROR`, `STALE`, `CANCELLED`

---

## 6. Что и где сохраняется

| Данные | Где |
|---|---|
| Traces нормализации | `X:\1C\NDC_1C\llm_normalizer\data\traces` |
| Prompt presets | `X:\1C\NDC_1C\llm_normalizer\data\presets` |
| Eval cases / reports | `X:\1C\NDC_1C\llm_normalizer\data\eval_cases` |

Важно:

1. API key не сохраняется в localStorage.
2. API key не возвращается в frontend-ответах.
3. В trace ключ редактируется (redacted).

---

## 7. Как правильно заполнять поля на практике

## 7.1 Минимальный рабочий набор

1. `OpenAI API Key`: вставить валидный ключ.
2. `Model ID`: `gpt-4o-mini`.
3. `Raw user question`: живой вопрос.
4. Остальные поля оставить по default.
5. Нажать `Normalize`.

## 7.2 Если много ошибок в Validation

1. Уменьши свободу модели: `Temperature = 0`.
2. Уточни `Developer prompt` и `Schema notes`.
3. Добавь few-shot примеры под твой класс вопросов.
4. Повтори `Normalize` и сравни через `History`.

## 7.3 Если route_hint “плывет”

1. Явно добавь `expected route` в Query Panel.
2. В domain/developer prompt пропиши контр-примеры.
3. Сохрани новый preset и гони серию через `POST /api/eval/run`.

---

## 8. Частые проблемы и решения

| Симптом | Причина | Что делать |
|---|---|---|
| `Ошибка подключения` | ключ неверный/ограничен, неверный base URL | проверить key, model, URL через `Test connection` |
| `validation.passed = false` | модель вернула JSON вне схемы | ужесточить prompt, проверить schema notes, повторить |
| пустой `Normalized JSON` | parse/validation fail | смотреть `Raw model output` + `Validation` |
| высокая latency | слишком тяжелые prompt/few-shot | сократить prompt и few-shot |
| VS Code не стартует npm | PowerShell policy в Windows | использовать `npm.cmd` и готовые Tasks |

---

## 9. API-карта (для интеграции)

Normalizer:

- `POST /api/openai/test-connection`
- `POST /api/normalize`
- `POST /api/eval/run`
- `GET /api/history`
- `GET /api/history/:trace_id`
- `POST /api/presets/save`
- `GET /api/presets`

NDC Integration namespace:

- `POST /api/accounting-agent/v1/runs/start`
- `POST /api/accounting-agent/v1/runs/finish`
- `GET /api/accounting-agent/v1/runs`
- `GET /api/accounting-agent/v1/runs/:runId`
- `POST /api/accounting-agent/v1/tasks/enqueue`
- `POST /api/accounting-agent/v1/tasks/claim`
- `POST /api/accounting-agent/v1/tasks/:taskId/complete`
- `POST /api/accounting-agent/v1/tasks/:taskId/error`
- `GET /api/accounting-agent/v1/results`
- `GET /api/accounting-agent/v1/trace/run/:runId`
- `GET /api/accounting-agent/v1/health`

---

## 10. Чек-лист перед рабочей сессией

1. Backend и frontend подняты.
2. `Test connection` успешен.
3. Выбран корректный preset.
4. Запрос содержит минимум необходимого контекста (вопрос + период при необходимости).
5. После `Normalize` проверен `Validation`.
6. Trace сохранен и виден в History.

---

## 11. Главное правило эксплуатации

`LLM в этом контуре — нормализатор, а не исполнитель бизнес-логики.`

То есть:

1. LLM структурирует, классифицирует, предлагает route hint.
2. Финальные бухгалтерские выводы и оркестрация остаются в основном контуре NDC.
