first commit

README.md

@@ -0,0 +1,549 @@
+# Руководство пользователя LLM Kanban
+
+---
+
+## Аннотация
+
+Настоящий документ является руководством пользователя информационной системы **LLM Kanban** — веб-приложения для управления задачами, выполняемыми большими языковыми моделями (LLM), по принципу канбан-доски.
+
+Документ предназначен для операторов, ревьюеров и администраторов системы, использующих её для постановки задач LLM-агентам, контроля их выполнения, ревью результатов и учёта стоимости вычислений.
+
+В руководстве описаны область применения, условия эксплуатации, порядок установки и запуска клиентской части, основные пользовательские операции, типовые аварийные ситуации и способы их устранения.
+
+---
+
+# Содержание
+
+- [Руководство пользователя LLM Kanban](#руководство-пользователя-llm-kanban)
+  - [Аннотация](#аннотация)
+- [Содержание](#содержание)
+- [1 Введение](#1-введение)
+  - [1.1 Область применения](#11-область-применения)
+  - [1.2 Краткое описание возможностей](#12-краткое-описание-возможностей)
+  - [1.3 Уровень подготовки пользователя](#13-уровень-подготовки-пользователя)
+  - [1.4 Перечень эксплуатационной документации](#14-перечень-эксплуатационной-документации)
+- [2 Назначение и условия применения](#2-назначение-и-условия-применения)
+  - [2.1 Назначение системы](#21-назначение-системы)
+  - [2.2 Условия применения](#22-условия-применения)
+  - [2.3 Минимальные требования](#23-минимальные-требования)
+- [3 Подготовка к работе](#3-подготовка-к-работе)
+  - [3.1 Состав и содержание дистрибутива](#31-состав-и-содержание-дистрибутива)
+  - [3.2 Запуск программы](#32-запуск-программы)
+  - [3.3 Проверка работоспособности](#33-проверка-работоспособности)
+- [4 Описание операций](#4-описание-операций)
+  - [4.1 Авторизация пользователя](#41-авторизация-пользователя)
+  - [4.2 Просмотр канбан-доски](#42-просмотр-канбан-доски)
+  - [4.3 Создание задачи](#43-создание-задачи)
+  - [4.4 Назначение LLM-агента](#44-назначение-llm-агента)
+  - [4.5 Запуск задачи на выполнение](#45-запуск-задачи-на-выполнение)
+  - [4.6 Перемещение задачи между колонками](#46-перемещение-задачи-между-колонками)
+  - [4.7 Ревью результата](#47-ревью-результата)
+  - [4.8 Просмотр истории выполнения](#48-просмотр-истории-выполнения)
+  - [4.9 Управление LLM-агентами](#49-управление-llm-агентами)
+  - [4.10 Управление пользователями](#410-управление-пользователями)
+  - [4.11 Просмотр учёта стоимости](#411-просмотр-учёта-стоимости)
+  - [4.12 Выход из системы](#412-выход-из-системы)
+- [5 Аварийные ситуации](#5-аварийные-ситуации)
+- [6 Рекомендации по освоению](#6-рекомендации-по-освоению)
+- [7 Термины и сокращения](#7-термины-и-сокращения)
+- [8 Контакты](#8-контакты)
+- [Лист регистрации изменений](#лист-регистрации-изменений)
+
+---
+
+# 1 Введение
+
+## 1.1 Область применения
+
+Система **LLM Kanban** применяется в организациях, использующих большие языковые модели (LLM) от внешних провайдеров (Anthropic, OpenAI, Google) для автоматизации интеллектуальной обработки текстовых задач: подготовки документов, анализа данных, генерации кода, перевода, реферирования и других подобных операций.
+
+Система обеспечивает:
+
+- централизованную постановку задач LLM-агентам;
+- визуальное отслеживание состояния задач на канбан-доске;
+- управление учётными записями LLM-провайдеров;
+- ревью полученных результатов с возможностью повторного запуска;
+- ведение журнала аудита всех действий пользователей;
+- учёт стоимости выполненных запросов.
+
+Типичные сценарии использования:
+
+- постановка оператором задачи на генерацию текста, переводимая агентом Claude или GPT-5;
+- ревью полученного ответа специалистом-ревьюером;
+- администрирование набора подключённых моделей и их тарифов;
+- анализ совокупных расходов на LLM за отчётный период.
+
+## 1.2 Краткое описание возможностей
+
+Система LLM Kanban предоставляет следующие возможности:
+
+- создание, редактирование и удаление задач;
+- визуальное представление задач в виде канбан-доски с колонками `Backlog`, `In Prompt`, `Processing`, `Review`, `Done`, `Failed`;
+- перемещение задач между колонками методом drag-and-drop;
+- выбор LLM-агента из списка подключённых;
+- автоматическая постановка задачи в очередь выполнения через брокер Redis;
+- получение и сохранение ответа LLM-провайдера;
+- ревью и утверждение или отклонение результата;
+- автоматический возврат задачи в `Backlog` при отклонении;
+- ведение журнала аудита (`audit_log`) с фиксацией каждого изменения;
+- учёт стоимости каждого запроса в журнале `cost_ledger`;
+- управление пользователями и их ролями (доступно администратору);
+- управление LLM-агентами: добавление, отключение, изменение тарифа (доступно администратору);
+- разграничение доступа к данным средствами Row Level Security (RLS) PostgreSQL.
+
+## 1.3 Уровень подготовки пользователя
+
+Пользователь должен обладать:
+
+- базовыми навыками работы с персональным компьютером;
+- базовыми навыками работы с веб-браузером;
+- общим пониманием принципов работы канбан-методологии;
+- общим пониманием принципов работы LLM (формулирование промптов, ограничения по числу токенов).
+
+Для администраторов дополнительно требуется:
+
+- понимание разграничения ролей в информационных системах;
+- знание принципов учёта стоимости вычислений на основе токенов.
+
+## 1.4 Перечень эксплуатационной документации
+
+При эксплуатации системы рекомендуется использовать документы, перечисленные в таблице 1.
+
+Таблица 1 – Перечень эксплуатационной документации
+
+| Документ | Назначение |
+|:---------|:-----------|
+| Руководство пользователя | Полное описание работы с системой LLM Kanban (настоящий документ) |
+| Руководство администратора | Описание установки и конфигурирования серверной части |
+| Руководство программиста | Описание GraphQL-схемы API и интеграции внешних сервисов |
+| Описание архитектуры | Описание программно-аппаратной архитектуры по ГОСТ Р 57100-2025 |
+
+---
+
+# 2 Назначение и условия применения
+
+## 2.1 Назначение системы
+
+Система LLM Kanban предназначена для автоматизации процессов оркестрации задач, выполняемых большими языковыми моделями, и для контроля их выполнения по принципу канбан-доски.
+
+Основные задачи системы:
+
+- централизованная постановка и хранение задач LLM;
+- автоматический подбор и вызов LLM-агента по заданным критериям;
+- визуальный контроль состояния задач;
+- ревью и утверждение результатов уполномоченным сотрудником;
+- ведение полного журнала аудита;
+- учёт стоимости в разрезе пользователя, агента, отчётного периода.
+
+## 2.2 Условия применения
+
+Система предназначена для работы в режиме многопользовательского доступа через локальную сеть или сеть Интернет. Серверная часть размещается в защищённой подсети и доступна клиентам по протоколу HTTPS.
+
+Для работы с системой пользователю необходимо:
+
+- наличие учётной записи в системе с присвоенной ролью;
+- стабильное подключение к сети с пропускной способностью не ниже 1 Мбит/с;
+- современный веб-браузер, поддерживающий стандарт ECMAScript 2022 и протокол WebSocket.
+
+## 2.3 Минимальные требования
+
+Минимальные требования к рабочему месту пользователя приведены в таблице 2.
+
+Таблица 2 – Минимальные требования к рабочему месту пользователя
+
+| Компонент | Требования |
+|:----------|:-----------|
+| Операционная система | Windows 10, macOS 12, Ubuntu 22.04 и выше |
+| Оперативная память | От 4 ГБ |
+| Свободное место на диске | От 200 МБ |
+| Браузер | Chrome 120+, Firefox 120+, Edge 120+, Safari 17+ |
+| Разрешение экрана | От 1366×768 пикселей |
+| Подключение к сети | От 1 Мбит/с |
+
+Минимальные требования к серверной части приведены в руководстве администратора.
+
+---
+
+# 3 Подготовка к работе
+
+## 3.1 Состав и содержание дистрибутива
+
+Клиентская часть системы является веб-приложением и не требует установки на рабочее место пользователя. Доступ осуществляется через веб-браузер по адресу, предоставленному администратором (например, `https://llm-kanban.example.org`).
+
+Серверная часть распространяется в виде Docker-контейнеров и устанавливается администратором согласно руководству администратора.
+
+## 3.2 Запуск программы
+
+Для запуска клиентской части пользователю необходимо:
+
+1. Открыть веб-браузер.
+2. В адресной строке ввести URL системы, предоставленный администратором.
+3. Дождаться загрузки экрана авторизации.
+
+После загрузки на экране отображается форма входа, как показано на рисунке 1.
+
+*Рисунок 1 – Экран авторизации*
+
+## 3.3 Проверка работоспособности
+
+Для проверки корректной работы системы необходимо последовательно выполнить операции, приведённые в таблице 3.
+
+Таблица 3 – Проверка работоспособности
+
+| № | Действие | Ожидаемый результат |
+|:-:|:---------|:--------------------|
+| 1 | Открыть URL системы | Отображается экран авторизации |
+| 2 | Ввести корректные учётные данные и нажать «Войти» | Выполняется переход на канбан-доску |
+| 3 | Открыть колонку `Backlog` | Список задач загружается без ошибок |
+| 4 | Открыть раздел «Агенты» | Отображается список подключённых LLM-агентов |
+| 5 | Выйти из системы | Выполняется возврат на экран авторизации |
+
+Если на любом из шагов возникла ошибка, следует обратиться к разделу [5 Аварийные ситуации](#5-аварийные-ситуации).
+
+---
+
+# 4 Описание операций
+
+## 4.1 Авторизация пользователя
+
+При обращении к системе отображается экран авторизации.
+
+Для входа в систему необходимо:
+
+1. Ввести адрес электронной почты в поле «Email».
+2. Ввести пароль в поле «Пароль».
+3. Нажать кнопку **«Войти»**.
+
+При успешной авторизации выполняется следующее:
+
+- система генерирует JWT-токен доступа сроком действия 1 час;
+- токен сохраняется в защищённом хранилище браузера;
+- одновременно создаётся сессия в Redis с ключом вида `session:{token}` и временем жизни 3600 секунд;
+- выполняется переход на канбан-доску;
+- в журнал `audit_log` записывается событие входа.
+
+Если данные введены неверно, отображается сообщение:
+
+> Неверный email или пароль
+
+При повторном открытии системы в том же браузере вход выполняется автоматически, пока действителен сохранённый токен.
+
+Внешний вид экрана авторизации представлен на рисунке 1.
+
+*Рисунок 1 – Экран авторизации*
+
+## 4.2 Просмотр канбан-доски
+
+После авторизации пользователь попадает на главный экран — канбан-доску.
+
+Доска содержит шесть колонок:
+
+а) `Backlog` — новые и отклонённые задачи, ожидающие назначения;
+
+б) `In Prompt` — задачи с назначенным агентом, ожидающие запуска;
+
+в) `Processing` — задачи, обрабатываемые LLM-агентом в настоящий момент;
+
+г) `Review` — задачи с полученным ответом, ожидающие ревью;
+
+д) `Done` — задачи, ревью которых завершено успешно;
+
+е) `Failed` — задачи, выполнение которых завершилось ошибкой.
+
+Каждая задача представлена карточкой с краткой информацией:
+
+- идентификатор задачи;
+- заголовок промпта (первые 80 символов);
+- приоритет (`low`, `medium`, `high`);
+- имя назначенного агента (если назначен);
+- автор задачи.
+
+Состав отображаемых задач зависит от роли пользователя и определяется политикой Row Level Security:
+
+- оператор видит только свои задачи;
+- ревьюер дополнительно видит задачи в статусе `Review`;
+- администратор видит все задачи.
+
+Общий вид канбан-доски представлен на рисунке 2.
+
+*Рисунок 2 – Главный экран. Канбан-доска*
+
+## 4.3 Создание задачи
+
+Для создания новой задачи необходимо нажать кнопку **«Создать задачу»** в верхней части канбан-доски. После нажатия открывается форма создания задачи.
+
+Пользователь должен заполнить поля, перечисленные в таблице 4.
+
+Таблица 4 – Поля формы создания задачи
+
+| Поле | Обязательность | Описание |
+|:-----|:---------------|:---------|
+| Промпт | Обязательное | Текст задачи для LLM-агента, до 16 000 символов |
+| Приоритет | Обязательное | Одно из значений: `low`, `medium`, `high` |
+| Агент | Необязательное | LLM-агент из списка подключённых |
+| Контекстные файлы | Необязательное | Прикрепляемые файлы формата PDF, TXT, MD общим объёмом до 10 МБ |
+
+После заполнения формы необходимо нажать кнопку **«Сохранить»**. Для отмены операции используется кнопка **«Отмена»**.
+
+При успешном сохранении выполняется следующее:
+
+- в таблицу `tasks` PostgreSQL вставляется новая запись со статусом `backlog`;
+- в журнал `audit_log` записывается событие создания;
+- прикреплённые файлы сохраняются в MongoDB-коллекции `task_artifacts`;
+- карточка задачи появляется в колонке `Backlog`.
+
+Если агент при создании не выбран, задача остаётся в `Backlog` до его назначения. Если агент выбран, задача автоматически переводится в колонку `In Prompt`.
+
+## 4.4 Назначение LLM-агента
+
+Для назначения агента задаче в колонке `Backlog` необходимо:
+
+1. Открыть карточку задачи нажатием на неё.
+2. В поле «Агент» выбрать одно из значений выпадающего списка.
+3. Нажать кнопку **«Сохранить»**.
+
+При выборе агента отображается информация:
+
+- название модели;
+- лимит токенов на запрос;
+- стоимость 1000 входных и 1000 выходных токенов;
+- провайдер (Anthropic, OpenAI или Google).
+
+После сохранения задача автоматически перемещается в колонку `In Prompt`.
+
+## 4.5 Запуск задачи на выполнение
+
+Для запуска задачи на выполнение LLM-агентом необходимо:
+
+1. Открыть карточку задачи в колонке `In Prompt`.
+2. Нажать кнопку **«Запустить»**.
+
+После нажатия выполняется следующая последовательность действий:
+
+1. Карточка задачи перемещается в колонку `Processing`.
+2. В очередь Redis `queue:llm-calls` добавляется команда на вызов LLM-провайдера.
+3. Worker-процесс извлекает команду из очереди и обращается к API провайдера.
+4. По завершении запроса ответ сохраняется в `task_artifacts` MongoDB.
+5. В журнал `cost_ledger` записывается стоимость, рассчитанная по числу входных и выходных токенов.
+6. Карточка автоматически перемещается в колонку `Review`.
+
+В случае ошибки выполнения карточка перемещается в колонку `Failed`, а в журнал `audit_log` записывается причина отказа.
+
+Прогресс выполнения отображается в реальном времени средствами GraphQL Subscriptions через канал `events:tasks`.
+
+## 4.6 Перемещение задачи между колонками
+
+Перемещение задач между колонками выполняется методом drag-and-drop. Допустимые переходы между статусами определяются конечным автоматом, представленным на рисунке 3.
+
+*Рисунок 3 – Диаграмма состояний задачи*
+
+Допустимые ручные переходы приведены в таблице 5.
+
+Таблица 5 – Допустимые ручные переходы между колонками
+
+| Из колонки | В колонку | Условие | Доступно роли |
+|:-----------|:----------|:--------|:--------------|
+| Backlog | In Prompt | Назначен агент | Оператор, Администратор |
+| In Prompt | Backlog | — | Оператор, Администратор |
+| Review | Done | Ответ утверждён | Ревьюер, Администратор |
+| Review | Backlog | Ответ отклонён | Ревьюер, Администратор |
+| Failed | Backlog | Повторная попытка | Оператор, Администратор |
+
+Прочие переходы выполняются автоматически и через интерфейс drag-and-drop недоступны.
+
+## 4.7 Ревью результата
+
+Задачи в колонке `Review` доступны для проверки пользователям с ролью «ревьюер» или «администратор».
+
+Для проведения ревью необходимо:
+
+1. Открыть карточку задачи в колонке `Review`.
+2. Ознакомиться с исходным промптом, контекстными файлами и ответом LLM-агента.
+3. Нажать кнопку **«Утвердить»** или **«Отклонить»**.
+
+При нажатии **«Утвердить»**:
+
+- статус задачи изменяется на `done`;
+- карточка перемещается в колонку `Done`;
+- в журнал `audit_log` записывается событие утверждения.
+
+При нажатии **«Отклонить»**:
+
+- открывается диалоговое окно с полем «Причина отклонения»;
+- после ввода причины и подтверждения статус задачи изменяется на `backlog`;
+- карточка перемещается в колонку `Backlog`;
+- значение поля `retry_count` задачи увеличивается на единицу;
+- в журнал `audit_log` записывается событие отклонения с указанной причиной.
+
+## 4.8 Просмотр истории выполнения
+
+Для просмотра истории действий по задаче необходимо:
+
+1. Открыть карточку задачи.
+2. Перейти на вкладку **«История»**.
+
+На вкладке отображается хронологический список событий из коллекции `task_events` MongoDB. Для каждого события указаны:
+
+- дата и время;
+- тип события (`created`, `assigned`, `started`, `completed`, `approved`, `rejected`, `failed`);
+- автор события;
+- дополнительные данные в формате JSON.
+
+История доступна для просмотра в рамках прав, определённых политикой RLS.
+
+## 4.9 Управление LLM-агентами
+
+Раздел **«Агенты»** доступен только пользователям с ролью «администратор».
+
+В разделе отображается список подключённых LLM-агентов. Для каждого агента указаны:
+
+- провайдер;
+- название модели;
+- лимит токенов;
+- стоимость 1000 входных и 1000 выходных токенов;
+- статус активности.
+
+Доступные операции:
+
+а) **Добавление агента** — нажатием кнопки **«Добавить агент»** открывается форма ввода параметров нового агента, включая API-ключ. Ключ сохраняется в зашифрованном виде в поле `encrypted_api_key`;
+
+б) **Редактирование агента** — нажатием на строку агента открывается форма редактирования параметров;
+
+в) **Отключение агента** — переключателем «Активен» агент переводится в неактивное состояние. Неактивные агенты недоступны для выбора при создании задач, но связанные с ними записи `cost_ledger` сохраняются;
+
+г) **Удаление агента** — недоступно из соображений целостности учётных данных. Используется отключение.
+
+## 4.10 Управление пользователями
+
+Раздел **«Пользователи»** доступен только пользователям с ролью «администратор».
+
+В разделе отображается список зарегистрированных пользователей. Для каждого указаны:
+
+- идентификатор;
+- email;
+- ФИО;
+- роль (`operator`, `reviewer`, `admin`);
+- статус активности.
+
+Доступные операции:
+
+а) **Добавление пользователя** — заполнение формы с указанием email, ФИО, роли и начального пароля. Пароль сохраняется в виде хеша Argon2;
+
+б) **Изменение роли** — выбор нового значения роли из выпадающего списка;
+
+в) **Блокировка пользователя** — переключение поля `is_active` в значение «ложь». Заблокированный пользователь не может авторизоваться, но его задачи и записи `audit_log` сохраняются;
+
+г) **Сброс пароля** — генерация нового временного пароля, отображаемого администратору один раз.
+
+## 4.11 Просмотр учёта стоимости
+
+Раздел **«Учёт стоимости»** доступен пользователям с ролью «ревьюер» или «администратор».
+
+В разделе отображается таблица записей `cost_ledger`. Для каждой записи указаны:
+
+- идентификатор задачи;
+- агент;
+- число входных и выходных токенов;
+- стоимость в условных единицах;
+- отчётный период.
+
+Доступные операции:
+
+а) фильтрация по агенту, пользователю, периоду;
+
+б) группировка по агенту, пользователю или периоду с подсчётом суммы;
+
+в) экспорт результатов в формат CSV.
+
+## 4.12 Выход из системы
+
+Для выхода из системы необходимо:
+
+1. Нажать на имя пользователя в правом верхнем углу.
+2. В открывшемся меню выбрать пункт **«Выйти»**.
+
+При выходе выполняется следующее:
+
+- JWT-токен удаляется из хранилища браузера;
+- ключ `session:{token}` удаляется из Redis;
+- в журнал `audit_log` записывается событие выхода;
+- выполняется переход на экран авторизации.
+
+---
+
+# 5 Аварийные ситуации
+
+Типовые аварийные ситуации и рекомендации по их устранению приведены в таблице 6.
+
+Таблица 6 – Аварийные ситуации
+
+| Сообщение или симптом | Возможная причина | Рекомендация |
+|:----------------------|:------------------|:-------------|
+| «Неверный email или пароль» | Опечатка во вводе либо учётная запись заблокирована | Проверить раскладку клавиатуры, обратиться к администратору |
+| «Срок действия сессии истёк» | Истёк срок действия JWT-токена (1 ч) | Повторно выполнить вход в систему |
+| «Доступ запрещён» | У роли нет прав на запрошенное действие | Обратиться к администратору для уточнения прав |
+| «Превышен лимит запросов» | Превышен лимит rate-limit для пользователя или агента | Подождать восстановления квоты согласно политике (60/120/300 запросов в минуту) |
+| «Ошибка обращения к LLM-провайдеру» | Внешний API недоступен или ключ недействителен | Сообщить администратору; задача переводится в `Failed` |
+| «Задача превысила лимит токенов» | Размер промпта или ожидаемого ответа превышает `token_limit` агента | Уменьшить размер промпта или выбрать агента с большим лимитом |
+| Канбан-доска не загружается | Отсутствует подключение к серверу | Проверить соединение с сетью; обновить страницу |
+| Карточка не перемещается между колонками | Запрещённый переход согласно конечному автомату | См. таблицу 5 |
+| Файл не загружается | Превышен размер 10 МБ либо неподдерживаемый формат | Использовать форматы PDF, TXT, MD; уменьшить размер |
+
+При возникновении нештатной ситуации, не описанной в таблице 6, необходимо обратиться в службу технической поддержки (см. раздел [8 Контакты](#8-контакты)).
+
+---
+
+# 6 Рекомендации по освоению
+
+Для эффективного освоения системы LLM Kanban рекомендуется:
+
+- начать работу с тестовых задач с агентом наименьшей стоимости;
+- формулировать промпты максимально конкретно, указывая желаемый формат ответа;
+- использовать поле «Приоритет» для упорядочивания работы команды;
+- регулярно отклонять некорректные результаты для повышения качества возможных доработок промпта;
+- использовать раздел «Учёт стоимости» для контроля расходов;
+- администраторам — отключать неиспользуемые агенты, чтобы не загромождать выпадающий список выбора;
+- обращать внимание на значение `retry_count`: его рост может означать, что промпт сформулирован неудачно.
+
+---
+
+# 7 Термины и сокращения
+
+Перечень применяемых терминов и сокращений приведён в таблице 7.
+
+Таблица 7 – Термины и сокращения
+
+| Термин | Значение |
+|:-------|:---------|
+| LLM | Large Language Model — большая языковая модель |
+| API | Application Programming Interface — программный интерфейс приложения |
+| JWT | JSON Web Token — стандарт защищённой передачи утверждений |
+| RLS | Row Level Security — построчное разграничение доступа в PostgreSQL |
+| CRUD | Create, Read, Update, Delete — операции создания, чтения, изменения и удаления |
+| Worker | Серверный процесс, обрабатывающий очередь задач |
+| Промпт | Текстовое задание, передаваемое LLM-агенту на вход |
+| Токен | Минимальная единица обработки текста LLM, используемая для тарификации |
+| Канбан | Метод визуального управления задачами с использованием доски и карточек |
+| Drag-and-drop | Способ перемещения объекта интерфейса путём захвата мышью |
+| Ревью | Проверка результата выполнения задачи уполномоченным пользователем |
+| Backlog | Колонка канбан-доски с задачами, ожидающими назначения |
+
+---
+
+# 8 Контакты
+
+Служба технической поддержки системы:
+
+- электронная почта: `support@llm-kanban.example.org`;
+- Telegram: `@llm_kanban_support`;
+- репозиторий проекта: `https://gogs.itiscaf.ru/romanov_da/llm-kanban`.
+
+Часы работы службы поддержки: с 09:00 до 18:00 по московскому времени, в рабочие дни.
+
+---
+
+# Лист регистрации изменений
+
+| № | Дата | Раздел | Изменение | Автор |
+|:-:|:-----|:-------|:----------|:------|
+| 1 | 22.05.2026 | Все разделы | Создание документа | Романов Д. А. |