Aerotech Docflow

Локальный Python-модуль для сканирования документов через NAPS2, формирования имени файла и безопасного сохранения PDF в архив.

Эта версия — clean main: стабильное ядро проекта с минимальным локальным HTTP API, но без внешних интеграций, очереди заданий и воркера.

Текущий стабильный контур

NAPS2 / выбранный профиль сканера
  → app.scanner
  → C:\AerotechDocflow-Example\incoming\PF_*.pdf
  → app.document_flow
  → app.storage
  → C:\AerotechDocflow-Example\archive\ГОД\ТИП\ТИП_ГГГГММДД_НОМЕР_TASK_ID.pdf

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

• запуск NAPS2 через профиль или прямой eSCL;
• file lock сканера C:\AerotechDocflow-Example\incoming\.scanner.lock;
• защита от Ctrl+C, timeout и зависшего NAPS2;
• аварийный карантин частичных runtime-файлов;
• атомарный перенос через .tmp;
• резервирование финального имени через .reserve;
• файловая идемпотентность без SQLite;
• месячные TXT-логи;
• диагностика восстановления после сбоев;
• автономный постоянный Windows-updater с manifest, health-check и rollback;
• unit-тесты без физического сканера;
• manual-тесты для Epson/NAPS2.
• безопасный импорт единственного вложения задачи Planfix с сохранением формата;

Что намеренно не входит в clean main

• внешний HTTP API и публичный веб-сервер;
• произвольные внешние интеграции, кроме ограниченного импорта вложения Planfix;
• внешний tunnel / Cloudflare / ngrok;
• очередь заданий и воркер для нескольких операторов;
• OCR;
• загрузка файлов во внешние системы;
• боевая авторизация/HMAC.

Эти части должны добавляться позже отдельными ветками/этапами, чтобы не загрязнять стабильное ядро.

Установка

cd C:\path\to\aerotech-docflow
py -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

Для установки на другие Windows-устройства реализованы единый config.toml, CLI, PyInstaller onedir-сборка и запуск через WinSW как Windows-служба. Полная инструкция: docs/10_WINDOWS_INSTALLATION_AND_SERVICE.md. Короткая чистая установка с удалением предыдущей попытки: docs/11_CLEAN_INSTALLATION.md.

Release ZIP собирается одной командой и содержит только заменяемую программную часть:

.\scripts\build_release.ps1 `
  -Version "1.3.0" `
  -ConfigSchema 2 `
  -WinSWPath "C:\Tools\WinSW-x64.exe"

Постоянные AerotechUpdater.exe и AerotechUpdaterSetup.exe собираются отдельно через scripts\build_updater.ps1; updater не входит в ZIP приложения и не обращается к интернету.

Основные команды из исходного кода:

python -m app.cli --config .\config.toml show-config
python -m app.cli --config .\config.toml preflight
python -m app.cli --config .\config.toml diagnose
python -m app.cli --config .\config.toml run

В готовой сборке python -m app.cli заменяется на app\aerotech-docflow.exe.

pypdf является обязательной защитой целостности PDF. Если библиотека отсутствует или PDF не удаётся строго разобрать, документ не переносится в архив.

Финальная публикация PDF использует атомарный hard link без перезаписи. Рабочий архив должен находиться на файловой системе Windows, поддерживающей hard links (рекомендуется NTFS). Если NAPS2 не удалось остановить после timeout/прерывания, .scanner.lock намеренно сохраняется до ручной диагностики.

Основные команды

Приватные конфигурации

В Git хранятся только обезличенные шаблоны:

• .env.example — пример переменных окружения для development;
• config.example.toml — development-пример TOML;
• packaging/config.production.example.toml — production-шаблон для сборки.

Рабочие .env, config.toml, config.production.toml, их резервные копии, ключи, сертификаты, логи, PDF, idempotency/runtime-данные и service XML игнорируются. Скопируйте подходящий .example-файл, заполните локальную копию и никогда не добавляйте её в Git.

Локальный API

Установить зависимости и запустить сервер:

pip install -r requirements.txt
python -m app.run_local_api

Сервер слушает только 127.0.0.1:8000. Проверка состояния не обращается к сканеру:

curl http://127.0.0.1:8000/health

Перед первым запуском на реальном архиве включите DOCFLOW_ENV=production, заполните обязательные параметры из docs/01_CONFIGURATION.md и выполните:

python -m app.preflight

Preflight не запускает NAPS2 и не пишет в архив. Production-сервер не стартует на archive_test, при отсутствующем корне архива или без точного подтверждения DOCFLOW_ARCHIVE_CONFIRMATION.

Запуск сканирования из PowerShell:

Invoke-RestMethod `
  -Method Post `
  -Uri "http://127.0.0.1:8000/scan" `
  -ContentType "application/json" `
  -Body '{
    "task_id": "53243",
    "doc_type": "НКЛ",
    "document_datetime": "25-07-2026",
    "document_number": "001",
    "scanner_profile": "MY_NAPS2_PROFILE",
    "idempotency_key": "planfix_53243_НКЛ_001"
  }'

Дата документа приходит из Planfix строго как ДД-ММ-ГГГГ. Имя скана и импортированного файла: ТИП_ГГГГММДД_НОМЕР_TASK_ID.ext.

POST /scan синхронно ждёт завершения текущего document_flow и возвращает имя готового файла. POST /import скачивает единственный файл задачи Planfix и требует заголовок X-Docflow-Token. Очереди и туннеля в этой версии нет; локальный сервер по-прежнему слушает только 127.0.0.1.

Проверить unit-тесты без сканера:

python -m tests.unit.run_all_unit_tests

Проверить диагностику сканера:

python -m tests.manual.run_scanner_recovery_diagnostics

Выполнить реальное сканирование через профиль NAPS2:

python -m tests.manual.run_scan_epson_profile

Выполнить реальное сканирование прямым eSCL:

python -m tests.manual.run_scan_epson_escl_duplex

Документация

• docs/guide/README.md — полное руководство пользователя, оператора и администратора.
• docs/00_OVERVIEW.md — архитектура и состав проекта.
• docs/01_CONFIGURATION.md — переменные окружения и настройки NAPS2.
• docs/02_OPERATIONS.md — рабочие команды оператора/администратора.
• docs/03_TESTING.md — структура тестов.
• docs/04_FAILURE_RECOVERY.md — восстановление после аварий.
• docs/05_STORAGE_AND_IDEMPOTENCY.md — архив, .tmp, .reserve, идемпотентность.
• docs/06_LOCAL_API.md — контракт и эксплуатация локального HTTP API.
• docs/07_ACCEPTANCE_TESTING.md — приёмка перед production с логами и доказательствами.
• docs/08_RELEASE_CANDIDATE_2026-07-16.md — исправления, найденные при приёмке, и статус release candidate.
• docs/09_PRODUCTION_ARCHIVE_HARDENING.md — fail-closed защита реального архива и оставшиеся условия допуска.
• docs/10_WINDOWS_INSTALLATION_AND_SERVICE.md — TOML-конфигурация, EXE-сборка, WinSW-служба, установка, обновление и диагностика.
• docs/11_CLEAN_INSTALLATION.md — чистая установка на текущий компьютер по шагам.
• docs/13_PRODUCTION_BASELINE_1.4.9.md — актуальная production-версия, контрольные суммы и границы подтверждённых параметров.
• docs/99_CLEAN_MAIN.md — как сделать эту чистую версию веткой main.

Структура проекта

app/
  document_flow.py
  idempotency.py
  incoming_cleanup.py
  locks.py
  monthly_file_logging.py
  naming.py
  scanner.py
  scanner_recovery.py
  storage.py

tests/
  unit/
  manual/

docs/