# 260323_ACCOUNTING_AGENT_GUI_INTEGRATION_GUIDELINES

Дата: 23.03.2026 (MSK)
Контур: NodeDC (`dc_node`) / бухгалтерский агент (черновой GUI + временный монолитный backend)
Статус: интеграционные рекомендации для внешнего разработчика

---

## 1. Цель документа

Зафиксировать единые требования к GUI и backend бухгалтерского агента, который разрабатывается изолированно, чтобы:

1. интеграция в текущий `Node.js`-проект прошла без болезненных переделок;
2. архитектура оставалась совместимой с текущей моделью NodeDC (`UI -> runtime -> OPS`);
3. переход с временного монолита на будущую runtime-оркестрацию был обратимым и предсказуемым.

---

## 2. Базовые принципы (обязательные)

1. Сначала совместимость, потом скорость: любое быстрое решение допускается только если не ломает будущую интеграцию.
2. GUI и backend делаются как изолируемый модуль, а не как форк всей платформы.
3. Контракты API/событий/статусов должны быть стабильными с первой версии.
4. Нельзя смешивать UI-логику, runtime-логику исполнения и слой хранения в один неразделимый блок.
5. Пользовательская терминология в интерфейсе: использовать `NDC` (не `N8N`) в текстах UI.
6. Технические идентификаторы не переименовывать: routes, env vars, payload keys, event names, internal symbols остаются техническими.

---

## 3. Технологический профиль (что нужно соблюдать)

### 3.1 Frontend

1. Совместимый стек: `React 18` + `TypeScript` + подход, совместимый с `Vite`.
2. Архитектурно: компонентный UI с разделением на контейнеры данных и презентационные блоки.
3. Все сетевые вызовы через единый API-клиент-слой (не `fetch` хаотично по компонентам).
4. Состояние:
   - локальное UI-состояние отдельно;
   - серверное состояние отдельно (runs, statuses, results, trace).

### 3.2 Backend

1. Совместимый стек: `Node.js` + `Express` + JSON API.
2. Формат тела запроса: поддержка `application/json` и `application/*+json`.
3. Для хранения/аналитики ориентироваться на модель, совместимую с Postgres-онтологией (`session/run/result/event`).
4. Временный runtime монолитный, но за абстракцией (см. раздел 8).

### 3.3 Форматы

1. Время только в `ISO 8601`.
2. Денежные поля и суммы: явная валюта + числовой формат без двусмысленностей.
3. Ошибки API: структурированный ответ с `code`, `message`, `details`.
4. Любой статус должен быть машинно-читаемым и человеко-понятным.

---

## 4. Архитектурные границы ответственности

1. GUI отвечает за:
   - запуск/остановку;
   - отображение состояния;
   - фильтры/настройки;
   - операторские действия.
2. Backend отвечает за:
   - исполнение сценария;
   - очередь и жизненный цикл задач;
   - запись результатов и ошибок;
   - выдачу данных для монитора.
3. Слой данных отвечает за:
   - историчность;
   - идемпотентность результатов;
   - диагностируемость событий.
4. GUI не должен содержать тяжелую бизнес-обработку бухгалтерских документов/очередей.

---

## 5. Минимальный API-контракт (для безболезненной интеграции)

Рекомендуется выделить отдельный namespace, например `/api/accounting-agent/*`, и зафиксировать минимум:

1. `POST /runs/start`
   - старт сессии/прогона;
   - возвращает `sessionId`, `runId`, `status`.
2. `POST /runs/finish`
   - нормализованное завершение `DONE/FAILED/CANCELLED`;
   - причина/метаданные ошибки при неуспехе.
3. `GET /runs`
   - список прогонов с фильтрами.
4. `GET /runs/:runId`
   - карточка прогона + агрегированный статус.
5. `POST /tasks/enqueue`
   - постановка бухгалтерской задачи в очередь.
6. `POST /tasks/claim` (или эквивалент)
   - получение следующей задачи worker-частью.
7. `POST /tasks/:taskId/complete`
   - успешное завершение с результатом.
8. `POST /tasks/:taskId/error`
   - завершение с нормализованной ошибкой.
9. `GET /results`
   - витрина результатов для GUI/монитора.
10. `GET /trace/run/:runId`
   - лента событий для диагностики.
11. `GET /health`
   - техническое здоровье сервиса.

Важно:

1. Контракты payload фиксируются версией (`v1`) и не ломаются без явной миграции.
2. Поля `sessionId/runId/taskId` обязательны в событиях и логах.

---

## 6. Канон статусов и жизненного цикла

Единый словарь статусов для GUI и backend:

1. `NONE`
2. `QUEUED`
3. `RUNNING`
4. `DONE`
5. `ERROR`
6. `STALE`
7. `CANCELLED`

Правила:

1. Терминальные статусы (`DONE/ERROR/CANCELLED`) имеют приоритет и не откатываются в `RUNNING`.
2. Повторный запуск не перетирает историю, а создаёт новую сущность запуска/задачи.
3. Для каждого перехода статуса обязателен `updatedAt` и источник изменения (`source`).

---

## 7. Требования к GUI бухгалтерского агента

### 7.1 Что обязательно в первой версии

1. Панель запуска и остановки.
2. Панель прогонов (`runs`) со статусом, временем, инициатором.
3. Панель результатов (`results`) с фильтрами и быстрым поиском.
4. Панель ошибок/исключений.
5. Панель трассировки (`trace`) по выбранному `runId`.
6. Явная индикация: что обновляется в реальном времени, а что по ручному refresh.

### 7.2 UX-правила

1. Никаких скрытых магических фильтров, влияющих на выдачу без отображения в UI.
2. Любое действие пользователя должно иметь видимый эффект: `queued/running/done/error`.
3. Длинные операции не блокируют интерфейс целиком.
4. Ошибки показываются в 2 слоя:
   - коротко для оператора;
   - подробно для диагностики (код, traceId/runId).

### 7.3 Терминология UI

1. Во всех пользовательских текстах использовать `NDC`.
2. Не использовать `N8N` в текстах интерфейса.
3. В техническом коде/маршрутах внутренние названия не переписывать автоматически.

---

## 8. Требования к временному монолитному backend (с прицелом на замену runtime)

Чтобы потом перейти к отдельному runtime/оркестрации без переписывания GUI:

1. Ввести слой-адаптер исполнения (runtime adapter) как отдельный модуль.
2. GUI/backend общаются с этим адаптером через стабильный внутренний контракт.
3. В монолитной версии адаптер реализован локально.
4. В будущей версии адаптер можно заменить на внешний runtime (без смены GUI API).
5. Очередь/ретраи/лимиты должны быть инкапсулированы в backend, а не в GUI.

Минимальные способности адаптера исполнения:

1. `startRun`;
2. `stopRun`;
3. `enqueueTask`;
4. `claimTask`;
5. `completeTask`;
6. `failTask`;
7. `getRunState`;
8. `getRunTrace`.

---

## 9. Наблюдаемость, логирование, диагностика

1. Логи в структурированном формате JSON.
2. Обязательные поля логов: `timestamp`, `level`, `service`, `sessionId`, `runId`, `taskId`, `eventType`.
3. Для ошибок обязательны: `errorCode`, `errorMessage`, `stack` (где применимо).
4. Должна быть возможность получить trace по `runId` без ручного доступа к серверу.
5. Учитывать рабочую таймзону проекта: `Europe/Moscow` в операционных отчётах.

---

## 10. Безопасность и эксплуатационные правила

1. В секретах/ключах не хранить чувствительные данные в открытых логах.
2. Любые внешние интеграции — через конфигурацию окружения, без хардкода.
3. Все потенциально тяжелые операции ограничить по timeout/retry.
4. Обязательны idempotency-защиты для endpoint-ов старта/завершения/записи результатов.

---

## 11. Definition of Done для подрядчика

Задача считается готовой, если выполнено всё:

1. GUI поднимается и работает локально в связке с backend.
2. Есть запуск/остановка/мониторинг прогонов.
3. Статусы и жизненный цикл реализованы по канону раздела 6.
4. API покрывает минимальный контракт раздела 5.
5. Есть trace-диагностика по `runId`.
6. Ошибки и логирование структурированы.
7. Терминология UI приведена к `NDC`.
8. Подтверждена обратимая миграция с монолита на внешний runtime-адаптер без смены UI-контрактов.

---

## 12. Интеграционный чеклист перед вливанием в `dc_node`

1. Совпадает ли словарь статусов с существующим монитором.
2. Присутствуют ли `sessionId/runId` во всех критичных сущностях и событиях.
3. Нет ли скрытых зависимостей GUI от конкретной монолитной реализации runtime.
4. Не дублирует ли модуль существующие механизмы хранения/трассировки.
5. Не конфликтуют ли route-префиксы и форматы ответов с текущим API-паттерном.
6. Можно ли подключить модуль в NodeDC поэтапно (feature flag / scoped rollout).

---

## 13. Короткий итог для разработчика GUI

1. Делай интерфейс и backend как автономный модуль, но по контрактам, совместимым с NodeDC.
2. Сейчас runtime может быть монолитным, но обязан быть спрятан за адаптером.
3. UI должен опираться на стабильные статусы, `run/session`-идентификаторы и наблюдаемую trace-модель.
4. Всё, что пользователь видит, называем через `NDC`.
