ОргКонтур

ИИ-помощник для анализа организационной структуры и функций при реорганизации. Проект для хакатона, трек «Казахтелеком».

ОргКонтур сравнивает два комплекта организационных документов — «до» и «после» изменений. Он помогает аналитикам, специалистам по организационному развитию и внутреннему контролю понять, кому переданы обязанности, какие функции изменились и где могли возникнуть пробелы, дублирование или конфликт интересов.

Результат — сопоставление функций и подразделений, выводы с цитатами из документов и заключение для проверки человеком. Выводы рекомендательные: отсутствие соответствия в загруженных документах не доказывает исчезновение функции из компании.

Что реализовано

• Загрузка двух редакций: несколько файлов TXT, DOCX, XLSX и PDF с текстовым слоем; просмотр извлечённых фрагментов и поиск по ним.
• Извлечение структуры и функций: подразделения и должности; для функции — владелец, действие, объект, область ответственности и источник.
• Сравнение подразделений: сохранение, создание, преобразование и отсутствие найденного соответствия в новой редакции.
• Сопоставление функций: сохранение, передача, изменение, разделение, отсутствие найденного соответствия и отдельный статус недостаточности данных. Функции редакции «после» без соответствия «до» также попадают в результаты.
• Поиск потенциальных рисков: потеря функции, дублирование и конфликт интересов, в том числе самопроверка.
• Проверка источников: карточки с цитатами и расположением фрагментов; серверная проверка существования источников и соответствия цитат тексту. Для отсутствующих или неоднозначных соответствий показывается область поиска и кандидаты для проверки.
• Рабочее место аналитика: обзор результатов, сравнение функций, полный реестр, фильтры, риски, история проектов; подтверждение или отклонение выводов с комментарием.
• Заключение и экспорт: DOCX, Markdown, CSV и JSON с учётом решений аналитика.
• Два варианта хранения: память процесса для локального демо или MongoDB с GridFS для постоянного хранения результатов.

Как работает решение

1. Пользователь загружает документы в группы «До» и «После» либо выбирает встроенный пример.
2. Сервер разбирает файлы на адресованные фрагменты: пункты, строки, строки таблиц, страницы PDF.
3. После запуска анализа OpenAI извлекает функции и подразделения, сравнивает редакции и предлагает потенциальные риски. Обработка идёт в фоне; интерфейс показывает текущий этап.
4. Сервер проверяет ссылки на источники, цитаты и полноту сопоставления, формирует результаты и заключение.
5. Аналитик открывает выводы, сверяет исходные формулировки, сохраняет решение и комментарий.
6. Результат можно открыть из истории или выгрузить в нужном формате.

Интерфейс запускает режим openai. На сервере также есть лексический режим baseline для воспроизводимых проверок без внешнего API; это не полноценная замена смысловому ИИ-анализу.

Технологии

Компонент	Технологии и назначение
Интерфейс	TypeScript, React, Vite, CSS; иконки Lucide React
Сервер	Python, FastAPI, Uvicorn; Pydantic и pydantic-settings для схем и настроек
ИИ	OpenAI Python SDK, Responses API, структурированные ответы по Pydantic-схемам
Модель по умолчанию	gpt-4.1-mini; настраивается через OPENAI_MODEL
Чтение документов	pypdf, python-docx, openpyxl; TXT в UTF-8
Хранение	Память процесса или MongoDB / GridFS через PyMongo
Проверки	pytest, FastAPI TestClient; TypeScript и production-сборка Vite

Для ИИ-анализа нужны доступ к выбранной модели, действующий ключ OpenAI и доступная квота API. MongoDB необязательна для локального запуска. Наличие зависимости mongodb в корневом package.json не означает отдельный Node.js-сервер: реализованный backend написан на Python.

Архитектура

Браузер: React
    │ HTTP /api — загрузка, запуск, опрос состояния, решения, экспорт
    ▼
FastAPI ──► парсеры документов ──► аналитический конвейер
    │                                │
    │                                ├─ OpenAI Responses API
    │                                │  или BaselineProvider для проверок
    │                                └─ проверка источников и формирование отчёта
    ▼
MemoryStore или MongoDB / GridFS

Vite при локальном запуске проксирует /api на http://127.0.0.1:8000. Сервер запускает анализ через ThreadPoolExecutor с одним рабочим потоком. Клиент получает состояние проекта периодическими GET-запросами.

Путь	Содержимое
frontend/src/App.tsx	Рабочая область и связь экранов
frontend/src/components/	Загрузка, результаты, сравнение, источники и проверка выводов
frontend/src/hooks/useAnalysis.ts	Запросы к API, состояние проекта, опрос прогресса и история
frontend/src/styles/	Стили интерфейса и анимации
backend/app/main.py	HTTP API, фоновый запуск, обработка ошибок и экспорт
backend/app/parsers.py	Разбор файлов с сохранением адресов источников
backend/app/pipeline.py	Этапы анализа и формирование заключения
backend/app/provider.py	Интеграция с OpenAI
backend/app/baseline.py	Лексический провайдер для проверок
backend/app/evidence.py	Привязка и проверка цитат
backend/app/schemas.py, config.py	Контракты данных и настройки
backend/app/memory_storage.py, storage.py	Хранение проектов, результатов и решений
backend/tests/test_mvp.py	Автоматические проверки
data/samples/	Две пары документов и ожидания контрольного примера

Основные методы API

Метод	Назначение
GET /api/health	Состояние хранилища и настройки ИИ
POST /api/projects	Создание проекта из multipart-полей before и after
POST /api/projects/sample?kind=control	Загрузка контрольного примера; второй вариант — organizer
GET /api/projects	История проектов
GET /api/projects/{id}	Документы, состояние, результаты и решения
POST /api/projects/{id}/analyze	Запуск с телом {"mode":"openai"} или {"mode":"baseline"}
PUT /api/projects/{id}/findings/{fid}/review	Решение pending, confirmed или rejected и комментарий
GET /api/projects/{id}/export?format=docx	Экспорт; также доступны md, csv, json

Интерактивная документация после запуска: Swagger UI.

Установка и запуск

Требования

• Python 3.11+ как рекомендуемая среда запуска.
• Node.js 20.19+ в ветке 20 либо 22.12+ — согласно требованиям установленного Vite; npm.
• Для смыслового анализа — ключ OpenAI и интернет. Для локального режима baseline ключ не нужен.
• Свободные порты 3000 и 8000.

1. Получить проект

git clone https://github.com/BAITC-Hacks/hack-528e4c67-sixsevensquad.git
cd hack-528e4c67-sixsevensquad

2. Установить зависимости

Windows, PowerShell:

python -m venv backend/.venv
.\backend\.venv\Scripts\python.exe -m pip install -r backend/requirements.txt
npm --prefix frontend ci

Linux / macOS:

python3 -m venv backend/.venv
backend/.venv/bin/python -m pip install -r backend/requirements.txt
npm --prefix frontend ci

Команды выполняются из корня репозитория. npm install в корне не устанавливает зависимости интерфейса — они находятся в frontend/.

3. Настроить окружение

Создайте файл .env в корне репозитория и заполните его. Если файл уже есть, сохраните существующие настройки. В текущем репозитории .env.example пустой; используйте шаблон ниже:

OPENAI_API_KEY=ваш_ключ_OpenAI
OPENAI_MODEL=gpt-4.1-mini
KONTUR_STORAGE=memory
KONTUR_MAX_CHARS=250000
KONTUR_MAX_CALLS=80

Для проверки только через baseline строку OPENAI_API_KEY можно не задавать. Ключ читает backend; помещать его в переменные VITE_* не нужно. .env исключён из Git.

Постоянное хранение включается дополнительно:

KONTUR_STORAGE=mongodb
MONGODB_URI=mongodb://127.0.0.1:27017
MONGODB_DATABASE=kontur

MongoDB должна быть запущена и доступна отдельно. При использовании облачного кластера укажите его URI и настройте сетевой доступ. После изменения .env перезапустите API.

4. Запустить сервер и интерфейс

В первом терминале, из корня репозитория:

Windows:

.\backend\.venv\Scripts\python.exe -m uvicorn backend.app.main:app --reload --host 127.0.0.1 --port 8000

Linux / macOS:

backend/.venv/bin/python -m uvicorn backend.app.main:app --reload --host 127.0.0.1 --port 8000

Во втором терминале, также из корня:

npm --prefix frontend run dev -- --host 127.0.0.1 --strictPort

Откройте ОргКонтур. Проверка API: health.

На Linux/macOS вместо двух команд запуска можно использовать bash dev.sh: скрипт рассчитан на окружение backend/.venv/bin/ и уже установленные зависимости.

Сборка интерфейса

npm --prefix frontend run build
npm --prefix frontend run preview -- --host 127.0.0.1 --port 4173

Сборка появится в frontend/dist/, локальный просмотр — на http://127.0.0.1:4173. Backend должен работать отдельно. preview предназначен для проверки сборки; для публичного размещения потребуется настроить раздачу файлов и маршрутизацию /api к backend.

Как проверить решение жюри

Сценарий с OpenAI

1. Запустите приложение с заполненным OPENAI_API_KEY.
2. В разделе «Документы» нажмите «Контрольный пример», затем «Начать анализ».
3. Дождитесь завершения. Изучите «Результаты анализа», «Структура» и «Сравнение функций».
4. Сверьте выводы с контрольными ситуациями в data/samples/expected.json: преобразование отдела финансового контроля, отсутствие соответствия для реестра страховых договоров, возможный дубль проверки расходов и самопроверка договоров закупок. Это ожидания для проверки, а не обещание конкретного ответа модели.
5. В разделе «Риски» откройте вывод и его источники. Сравните цитаты «до» и «после», сохраните решение и комментарий.
6. Откройте «Заключение» и скачайте DOCX или CSV. Проверьте сохранённое решение в результатах.
7. Откройте проект через «Историю проектов». Дополнительно повторите анализ для «Пример №8 → №9» или загрузите свои файлы.

Проверка без ключа OpenAI

Серверный режим baseline позволяет проверить весь путь от документов до экспорта без расходов на внешний API:

1. Откройте http://127.0.0.1:8000/docs.
2. Выполните POST /api/projects/sample с kind=control, скопируйте id из ответа.
3. Выполните POST /api/projects/{pid}/analyze, указав этот ID и тело {"mode":"baseline"}.
4. Проверяйте GET /api/projects/{pid} до статуса completed; при failed посмотрите поле error.
5. Откройте http://127.0.0.1:3000/?project=ID_ПРОЕКТА&view=overview, подставив полученный ID. Проверьте источники, сохранение решений и экспорт в интерфейсе.

Этот сценарий проверяет механику приложения и лексические правила. Он не подтверждает качество работы OpenAI. Кнопка «Начать анализ» в интерфейсе использует именно OpenAI.

Автоматические проверки

Тестовые зависимости устанавливаются отдельно: pytest не входит в backend/requirements.txt; для TestClient требуется httpx.

Windows:

.\backend\.venv\Scripts\python.exe -m pip install pytest httpx
.\backend\.venv\Scripts\python.exe -m pytest -q backend/tests
npm --prefix frontend run build

Linux / macOS:

backend/.venv/bin/python -m pip install pytest httpx
backend/.venv/bin/python -m pytest -q backend/tests
npm --prefix frontend run build

В репозитории 12 тестов: разбор документов, привязка и отклонение цитат, контрольные риски и структура, неопределённые соответствия, API, решения аналитика, экспорт и контракт OpenAI-адаптера. Тесты подменяют внешний транспорт и не вызывают реальную модель; интеграция с живой MongoDB ими не проверяется.

Данные и интеграции

• Входные данные: загруженные пользователем организационные документы двух редакций. Автоматического подключения к корпоративным системам нет.
• Примеры: control-before.txt / control-after.txt — синтетический контрольный комплект; organizer-before.txt / organizer-after.txt — встроенный пример №8 → №9. Файл expected.json содержит ориентиры для оценки контрольного комплекта, а не готовый результат анализа.
• OpenAI: сервер отправляет текстовые фрагменты и структурированные каталоги функций в Responses API. Запросы используют store=False; это не означает, что документы остаются исключительно на локальном компьютере.
• MongoDB: необязательное хранилище проектов и решений; результаты анализа сохраняются через GridFS. По умолчанию используется память процесса.
• Внешние нормативные базы и отраслевые источники: не подключены. NVIDIA API в текущем коде не используется.

Ограничения текущей версии

• Нет регистрации, входа, разграничения доступа и изоляции проектов между пользователями. Текущая версия рассчитана на локальную демонстрацию или закрытый контур.
• При KONTUR_STORAGE=memory проекты и решения исчезают после перезапуска API.
• Поддерживаются максимум 12 файлов в комплекте, 10 МБ на файл, по умолчанию 250 000 символов извлечённого текста и 80 вызовов провайдера на анализ. Два последних значения настраиваются через .env.
• Нет OCR: сканы без текстового слоя нужно распознать заранее. Старые DOC/XLS не поддерживаются; требуется DOCX/XLSX. TXT должен быть в UTF-8.
• Проверка цитат подтверждает связь с текстом источника, но не гарантирует правильность смысловой интерпретации или полноту извлечения. Аналитик должен проверять выводы.
• Ответы модели могут различаться; качество и время анализа зависят от документов, модели, сети и квоты. Численные метрики точности на независимом наборе данных в репозитории не представлены.
• Один рабочий поток последовательно выполняет анализы. Распределённой очереди задач и инфраструктуры масштабирования нет.
• Нет автоматической проверки внешних норм и сравнения с другими операторами без предоставленных источников.

Развёрнутая версия

Подтверждённая ссылка на публичную deployed-версию в репозитории отсутствует. Для демонстрации используйте локальный запуск по инструкции выше; адреса 127.0.0.1 доступны только на компьютере, где запущено приложение.