Kronon

Enterprise Accounting Operating System. Специализированная CRM/ERP система для управления процессами бухгалтерского аутсорсинга (Республика Беларусь).

---

📖 О проекте

Kronon — это не просто CRM. Это операционная система для бухгалтерской фирмы, разработанная для замены хаоса из Excel-таблиц, бумажных стикеров и разрозненных мессенджеров.

Система спроектирована с учетом специфики законодательства РБ (УНП, Налоговый кодекс) и ориентирована на строгие дедлайны отчетности. Главная цель — минимизация человеческого фактора и автоматизация рутины.

🚀 Ключевые возможности (Roadmap)

• Умный реестр клиентов: Карточки Юр.лиц и ИП с валидацией УНП, отслеживанием систем налогообложения (УСН, ОСН, Единый налог) и сроков действия ключей ЭЦП.
• Автоматический календарь задач: Генерация задач (НДС, ФСЗН, ПУ-3) на основе профиля клиента. Система сама знает, когда кому сдавать отчет.
• Google Sheets Sync: Двусторонняя синхронизация данных. Клиенты видят свои налоги в привычных таблицах, бухгалтеры работают в интерфейсе системы.
• Документооборот 2.0: Загрузка "первички" через Telegram-бот с автоматической привязкой к клиенту.
• Биллинг: Автоматический подсчет стоимости обслуживания на основе количества операций и сложности учета.
• Безопасность: Разграничение прав доступа (Object Level Permissions) — бухгалтер видит только своих клиентов.

---

🛠 Технический стек

Проект построен на базе Clean Architecture и 12-Factor App методологий.

Backend & Core

• Python 3.14 — Язык разработки.
• Django 6.0 — Основной фреймворк (Admin, ORM, Auth).
• Django Ninja — Высокопроизводительный асинхронный API (FastAPI-like experience).
• Pydantic V2 — Валидация данных и сериализация.
• Celery — Асинхронные задачи и периодические процессы.

Data & Storage

• PostgreSQL 18.1 — Основная БД. Используются новые фичи: UUIDv7 (сортируемые UUID) и Async I/O.
• Redis 7 — Кэширование, брокер сообщений для Celery.
• PgBouncer — Пулер соединений для работы под высокой нагрузкой (Transaction pooling).

DevOps & Infrastructure

• Docker & Docker Compose — Контейнеризация. Multi-stage, оптимизация слоев, запуск от non-root пользователя.
• Nginx / Whitenoise — Раздача статики и Reverse Proxy.
• GitHub Actions — CI/CD пайплайны (Linter, Type Check, Tests, Migration Check).
• Make — Автоматизация рутинных команд.

Quality Assurance

• Mypy (Strict Mode) — Строгая статическая типизация.
• Ruff — Линтинг и форматирование.
• Pytest — Модульное и интеграционное тестирование.
• Pre-commit hooks — Гарантия качества кода перед коммитом (Bandit, Ruff, Checkers).

---

🏗 Архитектура

Проект следует принципам Modular Monolith. Бизнес-логика разделена на изолированные приложения (apps/), что позволяет в будущем легко выносить модули в микросервисы.

kronon/
├── apps/               # Бизнес-домены
│   ├── users/          # Кастомная модель пользователя, роли, отделы
│   ├── clients/        # (WIP) Управление контрагентами
│   └── common/         # Общие утилиты и абстракции
├── config/             # Конфигурация Django (Settings, ASGI, WSGI)
├── docker/             # Dockerfiles, Entrypoints, Configs
├── scripts/            # Служебные скрипты
├── tests/              # Глобальные тесты
└── manage.py           # Точка входа

Environment Diagram

graph TD
    subgraph "Local Development (Port 5432)"
        A[App: runserver] -->|Direct| B[(Postgres: kronon_db)]
        A -->|Cache| C[(Redis: DB 1)]
    end

    subgraph "Parallel Testing (Port 5433)"
        T[Pytest-xdist] -->|Workers| D[(Postgres: RAM Disk)]
        D -->|Auto-create| D1[(test_db_gw0)]
        D -->|Auto-create| D2[(test_db_gw1)]
    end

    subgraph "Production (Port 6432)"
        P[Gunicorn/Uvicorn] -->|Pool| E[PgBouncer]
        E -->|Transaction| F[(Postgres: Prod)]
    end

Loading

Key Features:

• Isolation: Среды полностью разделены по портам (5432 vs 5433), что исключает затирание данных при тестах.
• Performance: Тестовая база работает в RAM (tmpfs) с отключенным fsync, что дает хороший буст скорости.
• Scalability: Готовность к Production через PgBouncer и лимиты ресурсов Docker.

🔒 Data Integrity and Audit

sequenceDiagram
    participant User as Пользователь/API
    participant Django as Django App
    participant DB as PostgreSQL (Triggers)
    participant History as Audit Log (ClientEventProxy)

    User->>Django: POST /api/clients/ (Update Name)
    Django->>DB: UPDATE "clients_client" SET name='New Name'

    Note over DB: Транзакция БД началась
    DB->>DB: Вызов триггера pghistory
    DB->>History: INSERT INTO "clients_clientevent" (old_data, new_data, user_id)
    Note over DB: Транзакция БД завершена

    DB-->>Django: Success
    Django-->>User: 200 OK (Data Updated & Logged)

Loading

sequenceDiagram
    participant S as Service Layer
    participant C as pghistory.context
    participant DB as PostgreSQL (Triggers)
    participant Log as ClientEventProxy Table

    Note over S: Начинаем обновление Клиента
    S->>C: Enter Context (user_id=019c..., ip='1.2.3.4')
    C->>C: Store in Async ContextVar

    S->>DB: UPDATE clients SET status='active'

    Note over DB: Триггер срабатывает внутри транзакции
    DB->>Log: INSERT Event + Link to Context metadata

    S->>C: Exit Context
    Note over S: Транзакция COMMIT

Loading

Key Features:

• Reliability: Триггеры Postgres сработают всегда.
• Atomic Operations: Аудит записывается в той же транзакции, что и данные. Нет риска, что данные обновились, а лог не записался.
• Performance: Логирование происходит на стороне БД, не нагружая Python-воркеры тяжелой логикой сериализации.

🕵 Triagram search

graph LR
    subgraph "Search Engine (PostgreSQL 18)"
        Input[User Search Query] --> Query[ILIKE %query%]
        Query --> Index{GIN Trigram Index}
        Index -->|Fast Scan| Result[Matched Clients]
    end

Loading

High Performance: Молниеносный поиск по клиентам, благодаря GIN-индексам на основе Trigram.

---

💻 Локальный запуск (DX)

Уделено огромное внимание Developer Experience. Развертывание проекта занимает 1 минуту.

Предварительные требования

• Docker & Docker Compose
• Python 3.14 & Poetry (для локальной разработки)
• Make (рекомендуется)

Быстрый старт

1. Клонирование репозитория:

   git clone https://github.com/Nicksok2413/Kronon.git
   cd Kronon

2. Настройка окружения: Скопируйте пример файла конфигурации и заполните его своими данными (SECRET_KEY, логины, пароли):

   cp .env.example .env

   ⚠️ Важно: Обязательно сгенерируйте надежные SECRET_KEY, DB_PASSWORD, ADMIN_EMAIL и ADMIN_PASSWORD.

3. Запуск инфраструктуры (Docker):

   make up

   Поднимет PostgreSQL, Redis, PgBouncer и само приложение.

4. Применение миграций и создание суперпользователя:

   make migrate
   make superuser

5. Доступ:

   • Админка: http://localhost:8000/admin
   • API Docs: http://localhost:8000/api/docs

Полезные команды

Весь процесс управления завернут в удобный Makefile:

• make install — Установить зависимости локально.
• make run — Запустить сервер разработки (локально).
• make test — Запустить тесты.
• make check-all — Запустить полный цикл проверок (Linter + Mypy + Tests).
• make logs — Смотреть логи контейнеров.

---

🤝 Вклад в проект (Contributing)

Проект придерживается строгих стандартов качества.

1. Весь код должен быть типизирован (Strict Mypy).
2. Docstrings обязательны (Google Style).
3. 100% покрытие тестами новой бизнес-логики.
4. Перед коммитом pre-commit хуки должны проходить успешно.

---

📄 Лицензия

Proprietary Software. All rights reserved. Developed for internal use by "Kronon Accounting".