DocFlow — Документообіг служби списання

Локальний десктоп-додаток для документообігу служби списання. PyQt6 + SQLite, без серверної частини. Файли користувача зберігаються в data/files/, метадані — в data/docflow.db.

Версія: 1.1.0 · Стадія: MVP (single-admin). Документообіг працює end-to-end: імпорт, версіонування з гілками, відкат, теги CRUD, експорт у zip, аудит-лог, фільтри, вбудована довідка. Один користувач — «Адмін» (перевизначити: DOCFLOW_USER env var).

---

Стек

• Python 3.11+
• PyQt6 — UI
• SQLite (stdlib sqlite3, без ORM, схема v2)
• ruff — лінт + формат
• mypy (strict) — типи
• pytest + pytest-qt — тести
• pre-commit — git-гачки
• pyinstaller — збирання .exe під Windows

Архітектура (layered)

src/docflow/
├── domain/          # Сутності та доменні помилки. Без зовнішніх імпортів.
├── application/     # Інтерфейси репозиторіїв + use-cases (command/query) + DTO.
├── infrastructure/  # SQLite-репозиторії, FileStorage, міграції.
├── presentation/    # PyQt6-вікна, віджети, діалоги, QSS/QPainter-стилі.
└── main/            # Config, DI-фабрика, entry-point, seed.
docs/
├── help.md          # Користувацька довідка (F1 у додатку).
└── about.md         # Короткий "Про DocFlow".

Залежності: presentation → application ← infrastructure ← (domain). Деталі правил коду — у CLAUDE.md у корені репо Documentar/.

Модель даних (схема v2)

Document          ← логічна сутність з ім'ям, описом, тегами
  ├─ Branch       ← Git-подібна гілка (main, draft-Q1, …)
  ├─ DocumentFile ← фізичний blob у storage (sha1, size, UUID-шлях)
  └─ DocumentVersion ← мітка (v1.0/d1.0), повідомлення, parent_id, → file_id

Кілька DocumentVersion можуть посилатися на той самий DocumentFile — завдяки цьому revert і branch (copy from parent) не дублюють blob на диску. Дедуплікація працює і при імпорті того ж файлу (matching sha1).

Міграція v1→v2 виконується автоматично при відкритті старої БД (див. infrastructure/db/schema.py).

Запуск (локально)

cd docflow
make setup                           # створює .venv, ставить залежності, pre-commit hooks
make run                             # або: PYTHONPATH=src .venv/bin/python -m docflow.main.app

На першому запуску БД та data/files/ будуть створені автоматично, плюс заллються 9 тегів і 10 демо-документів, щоб UI не був порожнім.

DOCFLOW_USER=Іван make run — переозначити ім'я користувача в аудит-логу.

Команди Makefile

Команда	Що робить
make setup	venv + deps + pre-commit hooks (повний bootstrap)
make venv	Створює .venv/
make install	Встановлює залежності (dev)
make install-hooks	Ставить pre-commit гачки в .git/hooks
make pre-commit-all	Прогнати pre-commit по всіх файлах
make run	Запускає додаток
make lint	ruff check
make fmt	ruff format
make typecheck	mypy --strict
make test	pytest
make build-exe	Збирає .exe через PyInstaller (Windows)
make clean	Чистить кеші та збірки

Що вже працює (MVP)

Документи (CRUD):

• Імпорт із drag & drop або файл-пікера (docx, xlsx, xls, pdf)
• Картка документа: метадані (тип, шлях, sha1, розмір, версій, гілок), теги, опис, останні версії, останні дії
• Редагування назви/опису через діалог «Редагувати картку»
• Видалення з підтвердженням і каскадом (всі версії + файли)
• Відкриття у зовнішньому редакторі (QDesktopServices.openUrl)

Версіонування (Git-style):

• CreateVersion — нова версія у поточній гілці (v1.0 → v1.1)
• CreateBranch — нова гілка з двома опціями джерела:
  • «Скопіювати поточну версію» (за замовчуванням) — reuse file_id, без копіювання blob на диску
  • «Завантажити новий файл» — нова версія з новим вмістом
• RevertToVersion — відкат із збереженням історії (новий коміт із file_id старої версії — дедуплікація)
• Дерево версій: гілки зліва, коміти центр, панель деталей справа

Теги:

• CRUD у Tag Manager (назва, колір з 7 опцій, опис)
• Прикріплення/відкріплення з картки документа
• Підбір існуючого або створення нового з пікера прямо з картки
• Фільтр документів за тегом із sidebar
• Pill-форма chip-ів через custom QPainter (TagChip) — однакова на будь-якій ширині

Пошук / сортування:

• Live-пошук по назві файла (toolbar) — case-insensitive для кирилиці (ігор знаходить «Ігоря»)
• Фільтр за тегом (клік у sidebar)
• Сортування таблиці по будь-якому стовпцю

Експорт / аудит:

• Експорт документа в zip: manifest.json + усі версії, namespace по гілках (versions/main/v1.0.docx, versions/draft-Q1/d1.0.docx)
• Експорт окремої версії з правильним розширенням та ім'ям {назва}_{label}.{ext}
• Журнал дій із фільтрами і пошуком; експорт у CSV
• Аудит-записи з кольоровими chip-мітами

Довідка:

• F1 або ? у toolbar → HelpDialog із бічним TOC, що читає docs/help.md
• Довідка → Про DocFlow… → AboutDialog із docs/about.md
• Markdown-файли редагуються незалежно — без перекомпіляції

Шорткати

Клавіша	Дія
Ctrl+N	Додати новий документ
Ctrl+Q	Вийти
F1	Відкрити довідку

Що буде наступним кроком (не critical для MVP)

• Розширений діалог пошуку (wildcard, дати, типи, теги include/exclude) — макет є
• Пагінація / lazy-loading для дуже великих репозиторіїв (>500 документів)
• Зв'язки між документами (на основі / доповнення / джерело даних)
• Сторінка налаштувань (шлях зберігання, користувач, тема)
• Юніт- та інтеграційні тести (структура tests/ готова)
• Custom-painted Git-graph із лініями (зараз — плоский список комітів)

Структура data/

data/
├── docflow.db        # SQLite-БД (не комітимо)
└── files/            # Фізичні blob-и за типом/роком/місяцем
    └── docx/2026/05/<uuid>.docx

Папка data/ — повна резервна копія. Її можна архівувати, переносити на інший комп'ютер; додаток підхопить її при наступному запуску.

Файли, які не можна редагувати без узгодження

• pyproject.toml, requirements*.txt — версії та залежності
• src/docflow/infrastructure/db/schema.py — БД-схема (нові міграції — окремими функціями, як _migrate_v1_to_v2)

Деталі по правилах розробки — у ../CLAUDE.md.