СТАТУС СИСТЕМЫ: АКТИВНА
ИНДЕКС АРХИТЕКТУРЫ: 9.4 / 10
УЗЕЛ: arch.casedigestai.com
⚡ Аудит системной архитектуры и оценка надежности

Автоматизированный конвейер распознавания многотомных судебных дел и юридической документации на русском языке, разработанный по методологии Spec-Driven Development (SDD). Система выполняет потоковый рендеринг страниц высокого разрешения, дословное извлечение кириллического текста (OCR), структурирование сложных таблиц в многостраничные книги Excel, детекцию и нарезку фототаблиц с нормализованными координатами, а также защитную остановку на нетекстовых технических схемах и чертежах.

Оценка архитектуры
9.4/ 10
Высокая тестируемость и дисциплина SDD
Спецификации ядра
9модулей
100% трассируемость к требованиям
Тестовое покрытие
122теста
112 успешных, 10 offline-пропусков
Поддерживаемые OCR-движки
3бэкенда
Nemotron, Gemma, Claude
Конституционные правила
12инвариантов
C-01 — C-12 строго соблюдаются
✦ Ключевые архитектурные преимущества
Подтверждено кодом
  • ✓
    Управление через Spec-Driven Development (SDD): Любое функциональное изменение начинается с формальных спецификаций (specs/<capability>/spec.md) с трассируемыми требованиями (REQ-*), валидируемыми автоматическими регрессионными тестами.
  • ✓
    Однонаправленная слоистая архитектура: Полное соответствие правилам docs/architecture.md. CLI-раннер изолирован от ядра распознавания, адаптеры моделей абстрагированы, внешние ресурсы инжектируются извне.
  • ✓
    Отказоустойчивый каскад моделей: Гибридная поддержка моделей OpenRouter: первичные бесплатные квоты (:free) с автоматическим переключением на гарантированные платные шлюзы при насыщении лимитов или 429 ошибках.
  • ✓
    Изоляция контекста и управление памятью: Каждая страница обрабатывается в отдельной turn-сессии без накопления контекста диалога. Рендеринг и сохранение чанками по 20 страниц предотвращают утечки оперативной памяти.
  • ✓
    Гарантия целостности при прерывании (SIGINT): Перехватчик сигнала прерывания атомарно удаляет неполные выходные файлы текущей страницы с кодом возврата 130, сохраняя 100% корректность ранее обработанных листов.
⚠ Уязвимости и точки роста
Требуют внимания
  • !
    V-01: Отсутствие авторизации (Локальный запуск): Текущий CLI рассчитан на доверенную рабочую станцию с чтением ключей из .env. При миграции на веб-сервер критически необходима интеграция Google OAuth 2.0 + TOTP 2FA.
  • !
    V-02: Ручной перезапуск при остановке на чертежах: При обнаружении нетекстовых графиков конвейер завершается с кодом 3. В веб-версии требуется интерактивное окно разрешения (пропуск, разметка, вырезание).
  • !
    V-03: Лимиты OpenRouter на бесплатных тарифах: Высокая частота запросов на nvidia/nemotron-3.5-super-vl:free приводит к задержкам шлюза. Необходим пул запасных ключей и экспоненциальный бэкофф.
  • !
    V-04: Объем временного дискового пространства: Рендеринг сотен страниц в 150 DPI создает гигабайты временных изображений. Решение: стриминг в Google Drive и автоматическая ротация кэша.
⚖ Соответствие конституционным правилам (docs/constitution.md)
12 инвариантов
Правило Формулировка инварианта Механизм соблюдения в коде Статус проверки
C-01 Изоляция секретов Ключи API загружаются через переменные окружения, запрещены в коде и репозитории Соблюдено
C-02 Трассируемость SDD Каждое требование связано с приемочным тестом в tests/test_*.py Соблюдено
C-03 Дословность текста Запрет на галлюцинации, исправление опечаток оригинала и перевод кириллицы Соблюдено
C-04 Отказ от инструментов OCR-сессия выполняется в изолированном контексте turn без внешних тулов Соблюдено
C-05 Защита чертежей Аварийная остановка с кодом 3 при наличии схем/графиков для защиты от искажений Соблюдено
C-06 Атомарность очистки Удаление незавершенных файлов при прерывании SIGINT (Ctrl+C) Соблюдено
🏛 Архитектурная схема и послойное разделение системы
High-Level Design

Система следует строгому однонаправленному многослойному паттерну в соответствии с docs/architecture.md. Внешние ресурсы (файловая система, LLM-модели, сетевой стек) изолированы и инжектируются извне. Ядро обработки полностью отвязано от интерфейсов входа.

УРОВЕНЬ 1: ОРКЕСТРАЦИЯ CLI И ЗАПУСК ТОМОВ src/run_volumes.sh (Диапазон FROM..TO) pdf_image_ocr.py CLI (_cli_main, sys.argv, аргументы) УРОВЕНЬ 2: ЯДРО КОНВЕЙЕРА РАСПОЗНАВАНИЯ (src/pdf_image_ocr.py) Рендеринг и нарезка PyMuPDF (fitz) 150 DPI • PNG / JPEG Чанки по 20 страниц Пайплайн страницы Детекция отказа / Кириллица До 3 повторных попыток Защитная остановка на чертежах Экстракторы контента Экспорт таблиц в openpyxl (.xlsx) Нарезка фототаблиц (PIL / bbox) Дословный текст (.txt) УРОВЕНЬ 3: АДАПТЕРЫ МОДЕЛЕЙ И ШЛЮЗ OpenRouterClient (httpx.Client) Каскад: nemotron:free → nemotron (paid) Альтернативы: gemma:free / claude-3-5-sonnet УРОВЕНЬ 4: ФАЙЛОВАЯ СИСТЕМА И АРТЕФАКТЫ Локальная ФС: sources/ & data/ Каталоги по 20 листов: {vol}_{chunk}/ Артефакты: .png, .jpg, .txt, .xlsx, .json, .log УПРАВЛЯЮЩИЙ КОНТУР: SPEC-DRIVEN DEVELOPMENT (SDD) И ТЕСТЫ Спецификации: specs/text-ocr • specs/table-export • specs/photo-handling • specs/non-text-handling • specs/volume-runner Конституция: docs/constitution.md (C-01 — C-12) • Архитектурные правила: docs/architecture.md • Тесты: tests/test_*.py (122 теста)
1. Уровень оркестрации

Скрипт src/run_volumes.sh управляет пакетным последовательным выполнением томов с остановкой при первой ошибке (fail-fast).

2. Ядро конвейера

Модуль src/pdf_image_ocr.py объединяет рендеринг через PyMuPDF, распознавание страниц, валидацию и парсинг артефактов.

3. Шлюз OpenRouter

Адаптер OpenRouterClient обеспечивает отказоустойчивый роутинг запросов с автоматическим переключением на резервные платные шлюзы.

⚡ Полный жизненный цикл обработки документа
Page State Machine

Пошаговый цикл обработки каждой отдельной страницы дела через конвейер распознавания: рендеринг, детекция ошибок, повторные попытки, ветвление артефактов и атомарный откат.

Исходный PDF sources/vol_003.pdf Рендеринг страниц PyMuPDF → PNG + JPG Мультимодельный OCR Nemotron / Gemma / Claude Проверка отказа До 3 попыток повтора Повтор < 3 попыток ЧЕРТЕЖ / СХЕМА Защитная остановка (код 3) Табличные листы Книга Excel (vol_003_237.xlsx) Обычный текст Дословный файл .txt Фототаблицы Нарезка фото + описание Завершение страницы Фиксация в каталоге чанка (003_012/)
1. Рендеринг и изоляция

Исходный PDF конвертируется по 20 листов в PNG и JPEG с разрешением 150 DPI. Чанкование предотвращает переполнение памяти процесса.

2. Защита от галлюцинаций

Паттерны фраз-отказов («I cannot read», «As an AI») или английский комментарий триггерят повторный запрос (до 3 раз) с автоматическим переключением шлюза.

3. Ветвление экстракторов

Текст направляется в .txt, таблицы преобразуются в полноценный .xlsx с сохранением чисел, а фотографии вырезаются в отдельные JPG.

🧩 Функциональные блоки и спецификации системы (SDD)
9 возможностей в specs/

Каждая возможность системы представляет собой автономный модуль поведения с формальными критериями приемки WHEN / THEN и автоматизированным набором тестов pytest.

Возможность Файл спецификации Ключевые требования (REQ) Файл теста Статус
text-ocr specs/text-ocr/spec.md
• R-text-ocr-01: Изолированная turn-сессия на страницу, без тулов, среднее усилие
• R-text-ocr-02: Дословная кириллическая транскрипция без перевода на английский
tests/test_text_ocr.py Реализовано
table-export specs/table-export/spec.md
• R-table-export-01: Табличные страницы не останавливают конвейер
• R-table-export-02: Создание файла vol<V>_<P>.xlsx на каждую страницу с таблицей
• R-table-export-03: Числовое форматирование ячеек; указатель таблицы в .txt
tests/test_table_export.py Реализовано
photo-handling specs/photo-handling/spec.md
• R-photo-handling-01: Фототаблицы не останавливают общий цикл
• R-photo-handling-02: Нарезка снимков в page<P>_<N>.jpg по координатам
• R-photo-handling-03: Транскрипция печатного текста и описание фото на русском языке
tests/test_photo_pages.py Реализовано
non-text-handling specs/non-text-handling/spec.md
• R-non-text-handling-01: Остановка с кодом 3 на чертежах, схемах и графиках
• R-non-text-handling-02: Штампы, печати и рукописные заметки транскрибируются как есть
tests/test_non_text_stop.py Реализовано
page-rendering specs/page-rendering/spec.md
• R-page-rendering-01: Рендеринг каждой страницы в PNG и JPEG с 150 DPI
• R-page-rendering-02: Группировка страниц по подкаталогам (макс. 20 на папку)
tests/test_text_ocr.py Реализовано
answer-retry specs/answer-retry/spec.md
• R-answer-retry-01: Детекция фраз-отказов, английских реплик и сбоев JSON
• R-answer-retry-02: До 3 попыток повторного запроса перед генерацией ошибки
tests/test_text_ocr.py Реализовано
interrupt-cleanup specs/interrupt-cleanup/spec.md
• R-interrupt-cleanup-01: SIGINT удаляет неполные выходные файлы с кодом 130
• R-interrupt-cleanup-02: Ранее завершенные страницы сохраняются без повреждений
tests/test_interrupt_cleanup.py Реализовано
volume-runner specs/volume-runner/spec.md
• R-volume-runner-01: Последовательная обработка диапазона FROM..TO
• R-volume-runner-02: Аварийная остановка при первой же ошибке (код 1 или 3)
• R-volume-runner-03: Проброс параметров CLI (--resume, --engine)
tests/test_volume_runner.py Реализовано
run-logging specs/run-logging/spec.md
• R-run-logging-01: Создание файла лога с меткой времени в каталоге logs/
• R-run-logging-02: Уровень INFO в консоль терминала, подробный DEBUG в файл
tests/test_text_ocr.py Реализовано
🧠 Стратегия OCR-движков и каскадирование OpenRouter
Архитектура моделей

Система предоставляет гибридную поддержку мультимодельных бэкендов. По умолчанию запросы идут в OpenRouter с нулевой стоимостью на бесплатных тарифах и автоматическим каскадным переключением на гарантированные платные шлюзы при лимитах частоты или 429 ответах.

Идентификатор Флаг CLI Основной уровень (Бесплатный) Резервный уровень (Платный) Протокол и авторизация
nemotron По умолчанию --engine nemotron nvidia/nemotron-3.5-super-vl:free nvidia/nemotron-3.5-super-vl (Платный) OpenRouter HTTP API via httpx (Bearer-токен)
gemma Альтернатива --engine gemma google/gemma-3-27b-it:free google/gemma-3-27b-it (Платный) OpenRouter HTTP API via httpx (Bearer-токен)
claude Макс. точность --engine claude claude-3-5-sonnet-20241022 Резерв недоступен (Прямой вызов) Прямой SDK Anthropic (ANTHROPIC_API_KEY)
⚡ Механизм каскадного переключения (Fallback Cascade)
  • • Шаг 1: Отправка страницы на бесплатный шлюз (:free).
  • • Шаг 2: При получении HTTP 429, 502, 503 или таймаута — немедленный повтор на платном шлюзе без :free.
  • • Шаг 3: При сохранении ошибки — экспоненциальный бэкофф с задержкой до 3 попыток.
  • • Шаг 4: При отказе модели или некириллическом выводе — перегенерация промпта.
🛡 Валидация вывода модели
  • • Детекция английских реплик: Проверка отсутствия галлюцинаций («Here is the text...»).
  • • Валидация JSON: Строгий парсинг блоков <tables> и <photos>.
  • • Контроль символов: Защита от перевода кириллицы на латиницу.
  • • Координатная сетка: Нормализация рамок фото (ymin, xmin, ymax, xmax в масштабе 0–1000).
📁 Карта структуры репозитория и таксономия файлов
Таксономия проекта

Физическая организация компонентов репозитория с разделением версионируемого исходного кода, спецификаций и генерируемых артефактов.

cr_case_docs/
├── src/Ядро продакшн-кода
│ ├── pdf_image_ocr.py(1,078 строк) Главный конвейер OCR, рендеринг, экстракторы и CLI
│ ├── run_volumes.shPOSIX-скрипт последовательного пакетного прогона томов
│ └── pyproject.tomlУправление пакетами и зависимостями Python
├── specs/Спецификации Spec-Driven Development (Единый источник правды)
│ ├── INDEX.mdРеестр возможностей и трассировка требований
│ ├── text-ocr/Спецификация базового распознавания текста
│ ├── table-export/Спецификация обработки и экспорта таблиц в Excel
│ ├── photo-handling/Спецификация детекции и нарезки фототаблиц
│ ├── non-text-handling/Спецификация защитной остановки на чертежах
│ └── volume-runner/Спецификация пакетного раннера томов
├── tests/Регрессионные и интеграционные тесты (pytest)
│ ├── test_text_ocr.pyТесты рендеринга, OCR и очистки
│ ├── test_table_export.pyТесты генерации Excel-книг
│ ├── test_photo_pages.pyТесты координат и нарезки фото
│ └── test_non_text_stop.pyТесты остановки на схемах (код 3)
├── docs/Архитектурная документация и регламенты
│ ├── architecture.mdСлоистая архитектурная модель и правила зависимостей
│ ├── constitution.md12 нерушимых конституционных инвариантов
│ └── numbering.mdСхема нумерации подкаталогов и математика страниц
├── sources/Исходные PDF-файлы многотомных дел (vol_001.pdf...)
├── data/Выходные результаты: чанки по 20 листов ({vol}_{chunk}/)
└── logs/Журналы выполнения прогонов с метками времени
🔢 Калькулятор нумерации страниц и имен артефактов
docs/numbering.md

Страницы дел группируются в подпапки по 20 листов. Используйте интерактивный калькулятор для мгновенной конвертации между абсолютными страницами PDF и именами файлов в конвейере.

→ Прямой расчет: Страница PDF → Имена файлов

Математическая формула: (Папка - 1) × 20 + Файл = Страница
Имя подкаталога: 003_012
Изображение страницы: 017.png / 017.jpg
Текстовый файл (.txt): 003_012_017.txt
Книга Excel (при наличии таблиц): vol003_237.xlsx
Префикс нарезки фото: vol003_page237

← Обратный расчет: Имя файла → Страница PDF

Вычисленный том: Том 3 (003)
Индекс подпапки: Папка 12 (012)
Номер файла в папке: Лист 17 (017)
Абсолютная страница PDF: Страница 237
Формула вычисления: (12 - 1) × 20 + 17 = 237
🚀 Дорожная карта и инициатива веб-платформы
docs/web-platform/brief.md

Стратегия эволюции от локального CLI-инструмента к серверному многопользовательскому веб-приложению с авторизацией Google OAuth, двухфакторной аутентификацией TOTP и облачной синхронизацией Google Drive.

🌐 Целевая веб-архитектура
Планируется
  • 1.
    Аутентификация и белый список: Вход через Google OAuth 2.0 в связке с обязательным TOTP (Google Authenticator) и валидацией по разрешенному списку корпоративных email.
  • 2.
    Облачное хранилище через Google Drive: Подключение общих дисков для исходных PDF и зеркалирования архивов распознавания, снимающее ограничения локального хранилища.
  • 3.
    Интерактивное разрешение нетекстовых схем: Веб-интерфейс оператора для обработки остановок на чертежах: предпросмотр, пропуск, аннотирование или ручная нарезка.
  • 4.
    Асинхронная очередь задач: Фоновые воркеры (FastAPI / Celery / Redis) для последовательного выполнения ресурсоемких пайплайнов без блокировки HTTP-сервера.
📋 Предлагаемое разделение спецификаций (SDD)
Эволюция SDD
ID Новая возможность Ключевой фокус разработки
010 OpenRouter OCR Backend Формализация HTTP-клиента OpenRouter и логики каскадного переключения
011 Drive Cloud Storage Интеграция с API Google Drive для потоковой загрузки PDF и выгрузки результатов
012 Authentication Subsystem Google OAuth 2.0 + выпуск и валидация QR-кодов TOTP 2FA
013 Web UI & Job Runner Интерактивная панель мониторинга, запуск томов, обработка чертежей