Backend Implementation — ESWF DOP Framework¶

Кроки імплементації¶

Крок 1. Створення Django проекту та встановлення залежностей¶

cd backend
python -m venv venv
source venv/Scripts/activate  # Windows
pip install -r requirements.txt

requirements.txt — основні пакети: - Django 5.1 — web-фреймворк - djangorestframework 3.15 — REST API - djangorestframework-simplejwt — JWT аутентифікація - django-cors-headers — CORS для React dev server - django-filter — фільтрація queryset через URL параметри - drf-spectacular — автогенерація OpenAPI schema + Swagger UI - python-dotenv — змінні середовища з .env - psycopg2-binary — PostgreSQL драйвер (production) - Pillow — робота з зображеннями (ImageField)

Створення Django apps:

django-admin startproject eswf .
python manage.py startapp core
python manage.py startapp essentials
python manage.py startapp fleet
python manage.py startapp logistic
python manage.py startapp registers
python manage.py startapp eswf_chat
python manage.py startapp news
python manage.py startapp shop

8 Django apps створено відповідно до модульної архітектури з todo.md

Крок 2. Налаштування Django Settings (split settings)¶

Структура: eswf/settings/__init__.py → base.py / development.py / production.py

base.py — спільні налаштування: - AUTH_USER_MODEL = 'core.User' — кастомна модель користувача - REST_FRAMEWORK — JWT auth, пагінація (50 записів), django-filter - SIMPLE_JWT — access token 60 хв, refresh 7 днів, ротація - SPECTACULAR_SETTINGS — API документація "ESWF DOP API v1.0.0" - TIME_ZONE = 'Europe/Kyiv' - Middleware: SecurityMiddleware → SessionMiddleware → CorsMiddleware → TenantMiddleware

development.py — SQLite, DEBUG=True, CORS_ALLOW_ALL_ORIGINS=True

production.py — PostgreSQL, DEBUG=False, змінні з .env

Split settings дозволяє мати різні конфігурації для dev/prod без if/else в одному файлі

Крок 3. Core Module — Базові абстрактні моделі¶

core/models/tenant.py — Tenant - Організація/компанія — корінь мультитенантності - Поля: name, code (unique), is_active

core/models/user.py — User(AbstractUser) - Розширена модель користувача з прив'язкою до тенанта - Додаткові поля: middle_name, phone, position, avatar, language (en/ua), is_tenant_admin

core/models/audit.py — AuditLog - Логування всіх змін: хто, коли, що змінив - Поля: action (create/update/delete), entity_type, entity_id, changes (JSON), ip_address - Індекс по (tenant, entity_type, entity_id) для швидкого пошуку

core/models/base.py — Абстрактні базові моделі: | Модель | Призначення | Ключові поля | |--------|-------------|--------------| | TenantAwareModel | Базова для всіх даних з ізоляцією по тенанту | tenant, created_at, updated_at, created_by, updated_by | | MasterDataModel | Довідники (каталоги) | code, name, name_ua, is_active, description | | HierarchicalMasterDataModel | Ієрархічні довідники (дерево) | parent (self FK), is_group | | TransactionModel | Документи з workflow | number, date, status (draft→approved→posted→cancelled) | | RegisterModel | Журнали та леджери | date, document_type, document_id |

Кожна конкретна модель успадковується від одного з цих абстрактних класів — DRY принцип

Крок 4. Core Module — Universal Data + Metadata Mechanism¶

Центральна архітектурна ідея ESWF: один API повертає і дані, і метаопис таблиці.

core/registry.py — EntityRegistry - Словник entityCode → {model, serializer, permissions, search_fields} - Кожний модуль реєструє свої моделі в apps.py → ready() - Метод register(code, model, serializer=None) — якщо serializer=None, генерується автоматично - 41 entity зареєстровано з усіх модулів

core/metadata.py — EntityMetadataProvider - Автоматична генерація metadata JSON з Django model fields - Маппінг Django field types → metadata types (CharField→string, ForeignKey→reference, etc.) - Автодетекція: hierarchy (self FK), subtables (_subtables attr), entity type (MasterData/Transaction/Register) - Генерує: fields[], subtables[], actions[], defaultSort, searchFields, parentField

core/views/universal.py — UniversalViewSet - Єдиний ViewSet для CRUD будь-якої зареєстрованої entity - URL: /api/v1/data/{entityCode}/ та /api/v1/data/{entityCode}/{id}/ - Підтримка: tenant isolation, search, filters (?filter[status]=active), sorting, hierarchy mode, pagination (?pageSize=50) - Auto-assign tenant, created_by, updated_by при створенні/оновленні

core/views/metadata.py — MetadataView - GET /api/v1/metadata/{entityCode}/ — метадані конкретної entity - GET /api/v1/metadata/ — список всіх зареєстрованих entity codes

core/serializers.py — auto_serializer_factory(model) - Динамічне створення ModelSerializer для моделей без явного serializer

Frontend запитує metadata → автоматично будує UI (таблицю, форму, фільтри). Кастомні компоненти потрібні лише для складної бізнес-логіки.

Крок 5. Core Module — Middleware, Permissions, Auth¶

core/middleware/tenant.py — TenantMiddleware - Прив'язує request.tenant на основі authenticated user - Весь подальший код фільтрує дані по request.tenant

core/permissions/roles.py: - IsTenantUser — користувач належить до тенанту - IsTenantAdmin — адміністратор тенанту

core/views/auth.py — Auth endpoints: - POST /api/v1/auth/login/ — логін, повертає JWT access+refresh + user info - POST /api/v1/auth/refresh/ — оновлення access token (SimpleJWT) - POST /api/v1/auth/logout/ — інвалідація refresh token - GET /api/v1/auth/me/ — поточний користувач

Крок 6. Essentials Module — 22 моделі базового обліку¶

Master Data — Goods Accounting (5 моделей): | Модель | entityCode | Особливості | |--------|-----------|-------------| | Item + ItemComponent | items | subtable: components (inline), поля: item_type, article, barcode, price, vat_rate | | Unit | units | Простий довідник | | Warehouse | warehouses | + responsible (Person FK) | | ExpenseItem | expenseItems | hierarchy: true (HierarchicalMasterDataModel) | | PriceType | priceTypes | + currency FK, is_default |

Master Data — Cash Accounting (4 моделі): | Модель | entityCode | Особливості | |--------|-----------|-------------| | Currency | currencies | symbol, iso_code, rate | | Cashbox | cashboxes | currency, responsible | | Bank | banks | mfo, swift, address | | SettlementAccount | settlementAccounts | iban, bank FK, currency FK, organization FK |

Master Data — Organizational Structure (8 моделей): | Модель | entityCode | Особливості | |--------|-----------|-------------| | Client | clients | client_type (company/individual), edrpou, inn, is_supplier, is_buyer | | BusinessOperation | businessOperations | debit_account, credit_account (ChartOfAccounts FK) | | ChartOfAccounts | chartOfAccounts | hierarchy: true, account_type (active/passive), allow_currency | | Organization | organizations | full_name, edrpou, director, accountant | | Contract | contracts | client FK, date_start/end, amount, currency | | Department | departments | Простий довідник | | Person | persons | last_name, first_name, middle_name, inn, date_of_birth | | BusinessDirection | businessDirections | Простий довідник |

Transactional Data (3 моделі): | Модель | entityCode | Особливості | |--------|-----------|-------------| | Invoice + InvoiceLine | invoices | subtable: lines (inline), total_amount, vat_amount, payment_due_date | | IncomingPayment | incomingPayments | payment_type (cash/bank), cashbox/settlement_account FK | | DocumentOperation | documentOperations | debit/credit account, amount, currency |

Journals (2 моделі): | Модель | entityCode | Особливості | |--------|-----------|-------------| | CashJournal | cashJournal | operation_type (income/expense), cashbox, amount | | InventoryJournal | inventoryJournal | operation_type (receipt/shipment/transfer/write_off), item, quantity |

Serializers: окремі файли для master_data, transactions, journals — кожна модель має свій ModelSerializer

Views: TenantFilterMixin — загальний mixin для фільтрації по тенанту + auto-assign tenant/user при create/update. Кожний ViewSet має search_fields, filterset_fields, ordering_fields.

Entity Registration: в essentials/apps.py → ready() — всі 22 entity зареєстровані в EntityRegistry з відповідними serializer та search_fields.

Essentials — найбільший модуль (22 моделі). Покриває: товари, гроші, оргструктуру, документи, журнали.

Крок 7. Fleet Module — 15 моделей транспортного обліку¶

Master Data — Operational (5 моделей): | Модель | entityCode | Особливості | |--------|-----------|-------------| | Vehicle + OdometerReading + VehicleComponent | vehicles | hierarchy: true, 2 subtables (related), license_plate, vin, fuel consumption norm | | Driver | drivers | person FK, license_number/category/expiry, user FK (для мобільного) | | Route + RouteWaypoint | routes | subtable: waypoints (inline), distance, estimated_time, origin/destination | | LocationPoint | locationPoints | address, city, country, latitude/longitude (GPS) | | Country | countries | iso_code |

Master Data — Maintenance (3 моделі): | Модель | entityCode | |--------|-----------| | MaintenanceType | maintenanceTypes | interval_km, interval_days | | TransportComponent | transportComponents | Простий довідник (шини, акумулятори тощо) | | RepairUnit | repairUnits | Простий довідник (двигуни, КПП тощо) |

Master Data — Fuel (1 модель): | Модель | entityCode | |--------|-----------| | FuelType | fuelTypes | Простий довідник |

Transactional Data (4 моделі): | Модель | entityCode | Особливості | |--------|-----------|-------------| | Waybill | waybills | vehicle, driver, route, odometer start/end, fuel start/end/issued/consumed | | Order | orders | client, cargo_description, weight, volume, loading/delivery date, price | | TransportInvoice | transportInvoices | sender, receiver, carrier, cargo, weight, declared_value | | MaintenanceRecord | maintenanceRecords | vehicle, maintenance_type, cost, next_maintenance_date/odometer |

Subtable endpoints: - GET /api/v1/fleet/vehicles/{id}/odometer-readings/ - GET /api/v1/fleet/vehicles/{id}/components/ - GET /api/v1/fleet/routes/{id}/waypoints/

Fleet — демонстраційний модуль з повним набором: довідники, документи, subtables, hierarchy

Крок 8. Logistic Module — 2 моделі розширеної логістики¶

Модель	entityCode	Особливості
`LogisticOrder`	logisticOrders	priority (low/medium/high/urgent), origin/destination, planned/actual date
`RouteSheet`	routeSheets	vehicle, driver, route, departure/arrival, total_distance, total_stops

Logistic розширює Fleet для управління логістичними задачами та маршрутними листами

Крок 9. Registers Module — 4 cross-module реєстри¶

Леджери (підсумкові залишки): | Модель | entityCode | Особливості | |--------|-----------|-------------| | CashLedger | cashLedger | cashbox/settlement_account, debit, credit, balance | | InventoryLedger | inventoryLedger | item, warehouse, quantity, amount |

Журнали (хронологічний облік): | Модель | entityCode | Особливості | |--------|-----------|-------------| | CashJournal | regCashJournal | operation_type, cashbox, client, amount | | InventoryJournal | regInventoryJournal | operation_type, item, warehouse, quantity |

Registers — окрема секція, записи створюються автоматично при проведенні документів

Крок 10. News Module — блог/новини¶

Модель	Опис
`Category`	Категорії статей (slug, order)
`Tag`	Теги (slug)
`Article`	Стаття: title/content (EN+UA), excerpt, image, status (draft/published/archived), views_count

API: публічний доступ на читання (AllowAny), адмін для створення/редагування - GET /api/v1/news/articles/ — список (тільки published для не-адмінів) - GET /api/v1/news/articles/{slug}/ — деталі + інкремент views_count - GET /api/v1/news/categories/, /api/v1/news/tags/

News API обслуговує frontend news.eswf.dev, lookup по slug для SEO-friendly URL

Крок 11. Shop Module — магазин модулів¶

Модель	Опис
`Product`	Модуль/додаток: name, slug, code, pricing (free/paid/subscription), price, status
`ShopOrder` + `ShopOrderItem`	Замовлення на покупку модулів
`License`	Ліцензія: tenant, product, is_active, expires_at

API: - GET /api/v1/shop/products/ — каталог (публічний) - POST /api/v1/shop/orders/ — створення замовлення (authenticated) - GET /api/v1/shop/licenses/ — ліцензії тенанту

Shop — App Store для ESWF модулів, обслуговує shop.eswf.dev

Крок 12. ESWF-Chat Module — AI-помічник¶

Модель	Опис
`ChatSession`	Сесія чату: user, tenant, title, model_name (LLM provider)
`Message`	Повідомлення: role (user/assistant/system), content, tool_calls, tool_results, tokens_used

API: - GET /api/v1/chat/sessions/ — список сесій - POST /api/v1/chat/sessions/{id}/messages/ — відправка повідомлення (placeholder для OpenRouter)

Поки що placeholder відповідь. Реальна інтеграція з OpenRouter (Claude, GPT-4o, Llama) — наступний крок.

Крок 13. Головний URL routing + API Documentation¶

eswf/urls.py — модульна маршрутизація:

/admin/                          → Django Admin
/api/schema/                     → OpenAPI schema (JSON/YAML)
/api/docs/                       → Swagger UI
/api/redoc/                      → ReDoc
/api/v1/                         → Core (auth, metadata, universal data)
/api/v1/essentials/              → Essentials module
/api/v1/fleet/                   → Fleet module
/api/v1/logistic/                → Logistic module
/api/v1/registers/               → Registers module
/api/v1/chat/                    → ESWF-Chat
/api/v1/news/                    → News/Blog
/api/v1/shop/                    → App Store

Крок 14. Міграції та перевірка¶

python manage.py makemigrations   # Генерація міграцій для всіх модулів
python manage.py migrate          # Застосування міграцій (SQLite для dev)
python manage.py check            # System check — 0 issues

Результати імплементації¶

Статистика¶

Метрика	Значення
Django apps	8 модулів (core, essentials, fleet, logistic, registers, eswf_chat, news, shop)
Моделі всього	~55 (включаючи subtables та абстрактні)
Entity в EntityRegistry	41 зареєстрованих entity codes
API endpoints	100+ (CRUD для кожної entity + subtables + auth + docs)
Міграції	8 initial migration files, всі застосовані
System check	0 issues

Створені файли по модулях¶

Модуль	Файли
eswf/settings/	`__init__.py`, `base.py`, `development.py`, `production.py`
eswf/	`urls.py` (головний routing)
core/models/	`__init__.py`, `tenant.py`, `user.py`, `audit.py`, `base.py`
core/views/	`__init__.py`, `auth.py`, `universal.py`, `metadata.py`
core/	`registry.py`, `metadata.py`, `serializers.py`, `urls.py`, `admin.py`
core/middleware/	`tenant.py`
core/permissions/	`roles.py`
essentials/models/	18 файлів моделей + `__init__.py`
essentials/serializers/	`master_data.py`, `transactions.py`, `journals.py`
essentials/views/	`master_data.py`, `transactions.py`, `journals.py`
essentials/	`urls.py`, `apps.py` (entity registration)
fleet/models/	13 файлів моделей + `__init__.py`
fleet/	`serializers.py`, `views.py`, `urls.py`, `apps.py`
logistic/models/	`logistic_order.py`, `route_sheet.py`
logistic/	`serializers.py`, `views.py`, `urls.py`, `apps.py`
registers/models/	4 файли моделей
registers/	`serializers.py`, `views.py`, `urls.py`, `apps.py`
news/	`models.py`, `serializers.py`, `views.py`, `urls.py`
shop/	`models.py`, `serializers.py`, `views.py`, `urls.py`
eswf_chat/	`models.py`, `views.py`, `urls.py`

41 зареєстрована Entity¶

banks, businessDirections, businessOperations, cashJournal, cashLedger,
cashboxes, chartOfAccounts, clients, contracts, countries, currencies,
departments, documentOperations, drivers, expenseItems, fuelTypes,
incomingPayments, inventoryJournal, inventoryLedger, invoices, items,
locationPoints, logisticOrders, maintenanceRecords, maintenanceTypes,
orders, organizations, persons, priceTypes, regCashJournal,
regInventoryJournal, repairUnits, routeSheets, routes,
settlementAccounts, transportComponents, transportInvoices, units,
vehicles, warehouses, waybills

Ключові API endpoints (перевірено)¶

✅ /api/v1/auth/login/          → JWT authentication
✅ /api/v1/auth/refresh/        → Token refresh
✅ /api/v1/auth/logout/         → Logout
✅ /api/v1/auth/me/             → Current user
✅ /api/v1/metadata/            → List all entity codes
✅ /api/v1/metadata/{code}/     → Entity metadata (fields, types, actions)
✅ /api/v1/data/{code}/         → Universal CRUD
✅ /api/schema/                 → OpenAPI schema
✅ /api/docs/                   → Swagger UI

Запуск¶

cd backend
source venv/Scripts/activate    # Windows
python manage.py runserver

http://localhost:8000/api/docs/ — Swagger UI (інтерактивна документація)
http://localhost:8000/api/redoc/ — ReDoc (читабельна документація)
http://localhost:8000/admin/ — Django Admin

Наступні кроки¶

~~Backend базова структура~~ ✅
Frontend DOP (React + Mantine + Vite) — config-driven UI
ESWF-Chat — інтеграція з OpenRouter (Claude, GPT-4o)
Mobile — АРМ Водія (React Native / Expo)
Тестування (pytest, RBAC, multi-tenancy isolation)
CI/CD + Docker deployment