Цифрова платформа управління агропідприємством — комплексне рішення для обліку складу, полів, агрооперацій, техніки, економіки та аналітики сільськогосподарського підприємства.
- Можливості
- Технологічний стек
- Архітектура
- Швидкий старт
- Demo Guide
- Конфігурація
- API
- Тести
- CI/CD
- Документація
- Contributing
- Ліцензія
| Модуль | Опис |
|---|---|
| Склад | Склади та товари, прихід / витрата / переміщення, інвентаризація, партійний облік (FIFO/FEFO), залишки та історія рухів |
| Поля | Карта полів з площею та кадастровими даними, поточна культура, історія культур, урожайність, планування сівозміни |
| Агрооперації | Посів, удобрення, ЗЗР, обробіток, збирання. Прив'язка ресурсів і техніки, автоматичне списання ресурсів при завершенні операції |
| Техніка | Парк техніки, журнал наробітку, облік заправок, статуси (активна / в ремонті / списана), зведена картка |
| Економіка | Облік витрат по категоріях із прив'язкою до полів та агрооперацій. Від'ємна сума = дохід |
| Аналітика | Зведений Dashboard, витрата ресурсів у розрізі дат і полів, ефективність полів |
| HR | Персонал, посади, норми виходу, облік відпрацьованого часу |
| Зерносховище | Облік прийому, відвантаження та залишків зерна по культурах |
| Продажі | Реестр угод, покупці, відвантаження із зерносховища |
| Шар | Технології |
|---|---|
| Backend | .NET 8, ASP.NET Core Web API, EF Core 8, PostgreSQL 16 + PostGIS, MediatR, FluentValidation, Serilog, JWT |
| Frontend | React 18, TypeScript, Vite, Ant Design 5, Zustand, React Query, Recharts, Leaflet |
| Тести | xUnit, Testcontainers, Moq |
| Інфраструктура | Docker, Docker Compose, GitHub Actions, Nginx, Let's Encrypt |
Проект побудований за принципами Clean Architecture з підходом CQRS + MediatR:
src/
├── AgroPlatform.Domain/ — Доменні сутності, enum-и
├── AgroPlatform.Application/ — CQRS команди / запити, DTO, валідатори, інтерфейси
├── AgroPlatform.Infrastructure/ — EF Core, PostgreSQL, Identity, JWT, перехоплювачі
└── AgroPlatform.Api/ — Контролери, middleware, Swagger, SignalR Hubs
frontend/
├── src/api/ — Axios + React Query клієнт
├── src/components/ — Спільні UI-компоненти
├── src/pages/ — Сторінки модулів
├── src/stores/ — Zustand стани
├── src/types/ — TypeScript інтерфейси
└── src/i18n/ — Локалізація (uk.ts, en.ts)
tests/
├── AgroPlatform.UnitTests/ — Юніт-тести
└── AgroPlatform.IntegrationTests/ — Інтеграційні тести (Testcontainers)
Ключові паттерни:
- Всі сутності наслідують
AuditableEntity(TenantId,IsDeleted,CreatedAtUtc,UpdatedAtUtc) - Мультиорендність через заголовок
X-Tenant-Id - М'яке видалення через прапор
IsDeleted - Оптимістичне блокування через
RowVersionнаStockBalance
git clone https://github.com/barach6662001-bit/AgroPlatform.git
cd AgroPlatform
docker-compose up --build -d| Сервіс | URL |
|---|---|
| Frontend | http://localhost:3000 |
| API | http://localhost:8080 |
| Swagger | http://localhost:8080/swagger |
Міграції та seed-дані застосовуються автоматично при першому запуску (AUTO_MIGRATE=true).
Після першого запуску база заповнюється демо-даними автоматично:
| Поле | Значення |
|---|---|
demo@agro.local |
|
| Пароль | DemoPass1 |
| Tenant ID | aaaaaaaa-0000-0000-0000-000000000001 |
На сторінці входу є кнопка «Увійти як Demo» для одноклікового входу.
Demo-середовище містить повний реалістичний dataset «Агро-Демо ТОВ»:
- 7 полів (490.5 га) — пшениця, соняшник, кукурудза, ріпак, ячмінь, пар
- 3 склади з залишками (насіння, добрива, ЗЗР, паливо)
- 2 зерносховища з 3 партіями зерна (536 т) та журналом рухів
- 5 одиниць техніки — John Deere 8R 310, Claas Lexion 770, Amazone UX 5200 та ін.
- 7 агрооперацій — посів, збирання, ЗЗР, добрива (з прив'язкою техніки та ресурсів)
- 12 записів витрат (~1.07 млн UAH) та 5 продажів (~5.38 млн UAH)
- 4 співробітники з журналами роботи та виплатами зарплати
- Права доступу — рольова матриця (Administrator / Agronomist / Manager)
- Аудит-лог — 4 записи змін сутностей
Демо-дані seed-яться один раз ідемпотентно. Перезапуск контейнерів не дублює дані.
# 1. Підняти тільки PostgreSQL
docker-compose up -d postgres
# 2. Застосувати міграції
dotnet ef database update \
--project src/AgroPlatform.Infrastructure \
--startup-project src/AgroPlatform.Api
# 3. Запустити API
dotnet run --project src/AgroPlatform.Api
# API: http://localhost:5224
# Swagger: http://localhost:5224/swaggercd frontend
npm install
npm run dev
# Frontend: http://localhost:3000За замовчуванням
vite.config.tsпроксує/apiнаhttp://localhost:8080.
Для локального .NET (порт 5224) додайтеfrontend/.env.development.local:VITE_API_URL=http://localhost:5224
POST /api/auth/register— зареєструватисяPOST /api/auth/login— отримати JWT-токен- Натиснути Authorize 🔒 → вставити токен (без
Bearer) - Додати заголовок
X-Tenant-Id: <uuid>до запитів (детальніше — docs/tenancy.md)
Детальна документація для демонстрації продукту: docs/demo.md
| Walkthrough | Тривалість | Аудиторія |
|---|---|---|
| 7-хвилинний | ~7 хв | Інвестори, C-level |
| 20-хвилинний | ~20 хв | Технічні директори, потенційні клієнти |
Ключові кроки 7-хвилинного walkthrough:
- Вхід → Dashboard (KPI, активні операції, сповіщення)
- Поля → Захід-1 (посів, збирання, витрати)
- Агрооперації → завершена операція збирання
- Зерносховище → партії зерна та рухи
- Економіка → витрати, P&L по полях, бюджет
- Аудит → зміни системних записів
| Змінна | Опис | За замовчуванням |
|---|---|---|
ConnectionStrings__DefaultConnection |
PostgreSQL connection string | див. docker-compose.yml |
JwtSettings__Key |
HMAC ключ підпису JWT (≥ 32 символи) | placeholder у docker-compose |
JwtSettings__Issuer |
Видавець JWT | Agrotech |
JwtSettings__Audience |
Аудиторія JWT | Agrotech |
Cors__AllowedOrigins__0 |
Дозволений CORS origin | http://localhost:3000 |
Swagger__Enabled |
Увімкнути Swagger поза Development | false |
AUTO_MIGRATE |
Автоматично застосовувати міграції при старті | false |
AttachmentStorage__RootPath |
Кореневий каталог для локального зберігання вкладень | App_Data/attachments |
RateLimiting__ReadPermitLimit |
Ліміт GET-запитів / вікно | 100 |
RateLimiting__WritePermitLimit |
Ліміт POST/PUT/DELETE / вікно | 30 |
Важливо: Замініть
JwtSettings__Keyна надійний секрет (≥ 32 символи) перед деплоєм.
Зразок файлу конфігурації: .env.example
Всі list-ендпоінти підтримують пагінацію:
?page=1&pageSize=20
Показати повну таблицю ендпоінтів
| Метод | URL | Опис |
|---|---|---|
| Аутентифікація | ||
| POST | /api/auth/register |
Реєстрація |
| POST | /api/auth/login |
Отримати JWT-токен |
| Склад | ||
| POST | /api/warehouses |
Створити склад |
| GET | /api/warehouses |
Список складів |
| POST | /api/warehouses/items |
Створити товар |
| GET | /api/warehouses/items |
Список товарів |
| POST | /api/warehouses/receipt |
Прихід на склад |
| POST | /api/warehouses/issue |
Витрата зі складу |
| POST | /api/warehouses/transfer |
Переміщення між складами |
| POST | /api/warehouses/inventory |
Інвентаризація |
| GET | /api/warehouses/balances |
Залишки |
| GET | /api/warehouses/moves |
Історія рухів |
| Поля | ||
| POST | /api/fields |
Створити поле |
| GET | /api/fields |
Список полів |
| GET | /api/fields/{id} |
Картка поля |
| PUT | /api/fields/{id} |
Оновити поле |
| DELETE | /api/fields/{id} |
Видалити поле |
| POST | /api/fields/assign-crop |
Призначити культуру |
| PUT | /api/fields/crop-history/{id}/yield |
Оновити врожайність |
| POST | /api/fields/rotation-plans |
Планувати сівозміну |
| DELETE | /api/fields/rotation-plans/{id} |
Видалити план сівозміни |
| Агрооперації | ||
| POST | /api/agro-operations |
Створити операцію |
| GET | /api/agro-operations |
Список операцій |
| GET | /api/agro-operations/{id} |
Картка операції |
| PUT | /api/agro-operations/{id} |
Оновити операцію |
| POST | /api/agro-operations/{id}/complete |
Завершити операцію |
| DELETE | /api/agro-operations/{id} |
Видалити операцію |
| POST | /api/agro-operations/{id}/resources |
Додати ресурс |
| PUT | /api/agro-operations/resources/{id}/actual |
Оновити факт витрати ресурсу |
| DELETE | /api/agro-operations/resources/{id} |
Прибрати ресурс |
| POST | /api/agro-operations/{id}/machinery |
Прив'язати техніку |
| PUT | /api/agro-operations/machinery/{id} |
Оновити техніку операції |
| DELETE | /api/agro-operations/machinery/{id} |
Прибрати техніку з операції |
| Техніка | ||
| POST | /api/machinery |
Створити техніку |
| GET | /api/machinery |
Список техніки |
| GET | /api/machinery/summary |
Зведення по парку |
| GET | /api/machinery/{id} |
Картка техніки |
| PUT | /api/machinery/{id} |
Оновити техніку |
| DELETE | /api/machinery/{id} |
Видалити техніку |
| POST | /api/machinery/{id}/work-logs |
Записати наробіток |
| POST | /api/machinery/{id}/fuel-logs |
Записати заправку |
| Економіка | ||
| POST | /api/economics/cost-records |
Записати витрату |
| GET | /api/economics/cost-records |
Список витрат |
| DELETE | /api/economics/cost-records/{id} |
Видалити витрату |
| Аналітика | ||
| GET | /api/analytics/dashboard |
Зведений Dashboard |
| GET | /api/analytics/resource-consumption |
Витрата ресурсів |
| GET | /api/analytics/field-efficiency |
Ефективність полів |
| Health Checks | ||
| GET | /health/live |
Liveness probe |
| GET | /health/ready |
Readiness probe (перевіряє БД) |
Повна інтерактивна документація: Swagger UI за адресою /swagger (увімкнено в Development та Docker).
# Всі тести
dotnet test
# Тільки юніт-тести
dotnet test tests/AgroPlatform.UnitTests
# Тільки інтеграційні (потрібен Docker)
dotnet test tests/AgroPlatform.IntegrationTests# Backend
dotnet build --configuration Release
# Frontend (type-check)
cd frontend && npx tsc --noEmit
# Публікація API
dotnet publish src/AgroPlatform.Api --configuration Release --output ./publish/apiGitHub Actions запускається на кожен push до main та на кожен Pull Request:
| Крок | Опис |
|---|---|
| Restore | Відновлення NuGet-залежностей (з кешем) |
| Build | Збірка всього рішення в конфігурації Release |
| Backend tests | Юніт + інтеграційні тести (Testcontainers) |
| Frontend tests | Vitest, ESLint, TypeScript type-check, Docker build dry-run |
| Lockfile guard | Перевірка синхронізації package-lock.json з package.json |
| Vulnerability scan | dotnet list package --vulnerable |
| Artifacts | Результати тестів, покриття коду, API-артефакт (7 днів) |
CD: workflow Deploy to Production публікує Docker-образи до GitHub Container Registry (ghcr.io) та запускає деплой через ручний тригер з підтвердженням через GitHub Environment production.
Для деплою в продакшен налаштуйте GitHub Secrets у Settings → Secrets and variables → Actions:
| Секрет | Опис |
|---|---|
POSTGRES_PASSWORD |
Пароль бази даних PostgreSQL |
JWT_KEY |
Ключ підпису JWT (мінімум 32 символи) |
DOMAIN |
Домен для TLS-сертифіката (Let's Encrypt) |
EMAIL |
Email для реєстрації в Let's Encrypt |
CORS_ORIGIN |
URL фронтенда, дозволений CORS-політикою |
Детально: docs/production-secrets.md
Повна документація: barach6662001-bit.github.io/AgroPlatform
| Документ | Опис |
|---|---|
| docs/demo.md | Demo Guide — credentials, startup, 7-хв та 20-хв walkthrough |
| docs/api.md | Довідник по API |
| docs/architecture.md | Архітектурні рішення |
| docs/auth.md | Аутентифікація та авторизація |
| docs/tenancy.md | Мультиорендність |
| docs/deployment.md | Керівництво по деплою |
| docs/development.md | Налаштування середовища розробки |
| docs/local-development.md | Локальна розробка в Codespace |
| docs/backup-restore.md | Резервне копіювання та відновлення |
| docs/production-secrets.md | Секрети для продакшену |
| docs/branch-protection.md | Захист гілок |
Дивись CONTRIBUTING.md — workflow гілок, вимоги до PR, CI-перевірки, конвенції коміт-повідомлень.
Автоматичне очищення гілок:
- при злитті PR — гілка видаляється автоматично
- щотижня (неділя, 03:00 UTC) — видаляються залишені злиті гілки
MIT — див. LICENSE.