Створення модулів K2 ERP
Створення модулів K2 ERP — це процес розробки, підключення, версіонування, тестування та завантаження компонент у систему оновлення K2 ERP або K2 Cloud ERP.
У технічній інструкції для розробників K2 Cloud ERP використовується термін компонента. У wiki-статтях для бізнес-користувачів це часто називають модулем K2 ERP, але для розробника важливо розуміти: модуль у користувацькому сенсі зазвичай реалізується через одну або кілька компонент у коді.
Компонента може мати власний каталог, власний Git-репозиторій, файл версії, історію змін, список файлів для оновлення та правила ігнорування службових файлів. Для роботи зі списком компонент у проєкті використовується скрипт auto_update, який копіюється в корінь проєкту на рівні з файлом app.py. У його файлі settings.py додаються потрібні компоненти, а команда python git_cmd.py clone клонує актуальні версії компонент і перейменовує каталоги поточних версій. :contentReference[oaicite:3]{index=3}
Що таке модуль K2 ERP
Модуль K2 ERP — це функціональна частина системи, яка додає або розширює можливості платформи.
Для користувача модуль може виглядати як окремий напрям роботи: CRM, документообіг, склад, виробництво, фінанси, оновлення, сайт, адміністрування або інший функціональний блок.
Для розробника модуль зазвичай пов’язаний із компонентами в структурі проєкту. Компонента може мати окремий каталог у папці:
components
Наприклад:
components/k2site components/k2adm components/k2update
Компоненти можуть підключатися до віддалених Git-репозиторіїв, оновлюватися, комітитися, пушитися, версіонуватися й завантажуватися на сервер оновлення.
Модуль і компонента: різниця для розробника
У бізнес-описах зазвичай говорять «модуль». У технічній інструкції розробника частіше використовується слово «компонента».
Модуль — це функціональна одиниця з погляду користувача.
Компонента — це технічна одиниця з погляду коду, Git-репозиторію, версії та системи оновлення.
Наприклад, користувацький модуль може складатися з кількох компонент, а одна компонента може забезпечувати частину функціональності більшого модуля.
Передумови для створення модуля
Перед створенням або підключенням нового модуля потрібно мати локально розгорнутий робочий проєкт K2 Cloud ERP.
Згідно з інструкцією розробників, спочатку копіюється існуючий проєкт по FTP, потім у каталозі /K2CloudERP запускається first_run для налаштування параметрів віртуального середовища, після чого у файлі /K2CloudERP/cfg/k2/k2/k2cfg.py змінюється domain_protocol з https на http, а додаток запускається через run.sh або run.bat. :contentReference[oaicite:4]{index=4}
Для Linux перший запуск:
bash first_run.sh
Для Windows:
./first_run.bat
Запуск додатку в Linux:
bash run.sh
Запуск додатку у Windows:
./run.bat
Середовище розробки
Для розробки модулів K2 ERP використовується PyCharm.
У Linux PyCharm можна встановити через snap:
sudo rm /etc/apt/preferences.d/nosnap.pref sudo apt update sudo apt install snapd sudo snap install pycharm-community --classic pycharm-community
Також можна завантажити архів із сайту JetBrains, розпакувати його, перейти в папку bin і запустити:
./pycharm.sh
Якщо виникає помилка запуску, встановлюється JRE/JDK:
sudo apt update sudo apt install default-jdk
Після відкриття проєкту в PyCharm потрібно налаштувати Python Interpreter: у правому нижньому куті вибрати Python Interpreter, далі Add new Interpreter, у полі Location вказати шлях до папки venv, а в полі Base Interpreter — шлях до виконуваного Python-файлу поточного середовища. :contentReference[oaicite:5]{index=5}
Ручна активація віртуального середовища в Linux:
source venv/bin/activate
У Windows:
.\venv\Scripts\activate
Git для модулів K2 ERP
Для створення й підтримки модулів потрібен Git.
Встановлення Git у Linux:
sudo apt update sudo apt install git
Після встановлення потрібно налаштувати користувача:
git config --global user.name "Ваше Ім'я" git config --global user.email "ваша_електронна_пошта@example.com"
Для авторизації через SSH створюється ключ:
ssh-keygen -t rsa -b 4096 -C "ваша_електронна_пошта@example.com"
Потім запускається ssh-agent:
eval "$(ssh-agent -s)"
Ключ додається командою:
ssh-add ~/.ssh/id_rsa
Публічний ключ можна переглянути командою:
cat ~/.ssh/id_rsa.pub
Після цього ключ копіюється й додається у віддалений репозиторій. :contentReference[oaicite:6]{index=6}
Варіант 1. Створення або підключення модуля через auto_update
Для списку компонент використовується скрипт:
auto_update
Каталог зі скриптом потрібно скопіювати в корінь проєкту на рівні з виконуваним файлом:
app.py
У технічній інструкції вказано такий шлях до каталогу auto_update:
https://git.corp2.eu/k2erp/python/k2/base/client/auto_update
Після копіювання потрібно перейти в каталог:
cd auto_update
Далі відкривається файл:
settings.py
У словник додаються ключі з потрібними компонентами. Повний список компонент знаходиться у файлі:
settings_example.py
Після налаштування виконується команда:
python git_cmd.py clone
Ця команда клонує актуальні версії компонент і перейменовує каталоги поточних версій компонент. :contentReference[oaicite:7]{index=7}
Варіант 2. Підключення однієї компоненти вручну
Якщо потрібно підключити одну компоненту вручну, потрібно перейти в каталог цієї компоненти.
Наприклад, для компоненти k2site:
cd components/k2site
Далі ініціалізується Git у поточній директорії:
git init
Створюється локальна гілка main і виконується перемикання на неї:
git checkout -b main
За потреби можна перемкнутися на іншу локальну гілку:
git checkout master
Далі додається віддалений репозиторій. Для прикладу k2site:
git remote add origin http://git.corp2.eu/k2erp/python/k2/base/site/k2site.git
Перевірка підключеного репозиторію:
git remote -v
Отримання даних із віддаленого репозиторію без зміни поточної робочої гілки:
git fetch origin
Отримання даних із віддаленого репозиторію з автоматичним об’єднанням із поточною локальною гілкою:
git pull origin main
Перевірка змін локальної копії компоненти:
git status
Такий підхід використовується, коли потрібно працювати не з усім списком компонент, а з конкретною компонентою. :contentReference[oaicite:8]{index=8}
Структура нової компоненти
Нова компонента має бути розміщена в каталозі:
components
Типовий шлях:
components/назва_компоненти
Для нової компоненти бажано мати:
setup.py history.txt .gitignore
Також у компоненті можуть бути службові каталоги, Python-файли, шаблони, статичні файли, налаштування, міграції, документація й інші елементи залежно від призначення модуля.
Назва компоненти має бути зрозумілою, стабільною і не конфліктувати з існуючими компонентами.
setup.py компоненти
Файл:
setup.py
використовується для опису версії компоненти.
Перед завантаженням нової версії компоненти потрібно змінити версію у файлі setup.py у корені каталогу компоненти. В інструкції розробників вказано, що змінюється рядок 5, поле version. Наприклад: :contentReference[oaicite:9]{index=9}
version=2.0.4.43
Також вказується тип версії:
version_type='stable'
або testing-версія:
version_type='testing'
stable використовується для стабільної версії.
testing або beta використовується для тестової версії.
history.txt компоненти
Файл:
history.txt
містить опис змін компоненти.
Після зміни версії у setup.py потрібно додати опис змін у history.txt у корені каталогу компоненти. Опис додається одним рядком.
Приклад:
2.0.4.43 - додавання додаткового поля в форму реєстрації
Це потрібно для того, щоб було зрозуміло, що саме змінилося в новій версії компоненти. :contentReference[oaicite:10]{index=10}
Коміт змін модуля через auto_update
Якщо використовується auto_update, коміт змін виконується автоматизовано.
Потрібно перейти в каталог:
cd auto_update
Клонування компонент із віддаленого сервера:
python git_cmd.py clone
Перевірка статусу:
python git_cmd.py status
Коміт змін:
python git_cmd.py commit
Отримання змін із віддаленого сервера:
python git_cmd.py pull
Пуш змін на віддалений репозиторій:
python git_cmd.py push
Ці команди наведені в інструкції як автоматичний спосіб роботи зі змінами компонент через auto_update. :contentReference[oaicite:11]{index=11}
Ручний коміт змін модуля
Якщо зміни комітяться вручну, спочатку потрібно перевірити статус:
git status
Потім додати зміни:
git add .
Виконати коміт:
git commit -m "Назва комміту"
Запушити зміни на віддалений репозиторій:
git push
Під час подальшої роботи зміни з віддаленого репозиторію отримуються командою:
git pull
Цей ручний сценарій також наведений у технічній інструкції розробників. :contentReference[oaicite:12]{index=12}
Налаштування завантаження модуля на сервер оновлення
Після створення або зміни компоненти потрібно налаштувати завантаження на сервер оновлення.
Для цього відкривається папка:
builder/config
У файлі:
component-list.txt
потрібно додати список компонент, які будуть завантажуватися на сервер оновлення.
Кожна компонента додається з нового рядка.
Приклад:
components/k2update components/k2adm components/k2site
Саме такий приклад наведений в інструкції розробників. :contentReference[oaicite:13]{index=13}
Налаштування ignore для компоненти
У папці:
builder/config/ignore
потрібно створити файл із назвою компоненти.
Наприклад:
k2site.txt
У цей файл додаються файли й папки, які не потрібно завантажувати на сервер оновлення.
Приклад:
__pycache__ .gitignore .git ej2.min.js
Це потрібно, щоб у пакет оновлення не потрапляли службові файли, локальні Git-дані, кеші або файли, які не мають бути доставлені на сервер оновлення. :contentReference[oaicite:14]{index=14}
token.txt для сервера оновлення
У файлі:
token.txt
потрібно додати токен доступу до сервера оновлення.
Цей токен використовується під час завантаження компонент у систему оновлення.
Файл із токеном не можна передавати стороннім особам, публікувати в репозиторії або зберігати в неконтрольованому місці.
Завантаження нової версії модуля в систему оновлення
Для завантаження нової версії компоненти потрібно виконати кілька дій.
Спочатку змінити версію у файлі:
setup.py
Потім додати опис змін у файл:
history.txt
Далі перейти в корінь додатку на рівні з виконуваним файлом:
app.py
В інструкції використовується команда:
cd k2
Після цього компоненти, додані у файлі:
builder/config/component-list.txt
завантажуються командою:
python k2update_push.py
Це основна команда для завантаження нової версії компоненти в систему оновлення. :contentReference[oaicite:15]{index=15}
Тестування модуля на deb1-deb3
Після завантаження нової версії компоненти потрібно оновити змінені версії компонент на тестових доменах:
deb1 deb2 deb3
Після оновлення потрібно протестувати функціонал.
Тестування має підтвердити, що компонента працює коректно, нові зміни не ламають існуючі сценарії, залежності не конфліктують, а модуль можна готувати до подальшого використання.
Цей крок також є завершальним пунктом інструкції розробників. :contentReference[oaicite:16]{index=16}
Типовий порядок створення нового модуля K2 ERP
| Крок | Дія |
|---|---|
| 1 | Локально розгорнути робочий проєкт K2 Cloud ERP. |
| 2 | Відкрити проєкт у PyCharm і налаштувати Python Interpreter. |
| 3 | Встановити й налаштувати Git. |
| 4 | Створити каталог нової компоненти в папці components або підключити існуючу компоненту. |
| 5 | Підключити віддалений Git-репозиторій вручну або через auto_update. |
| 6 | Розробити функціональність модуля. |
| 7 | Перевірити зміни локально через запуск K2 Cloud ERP. |
| 8 | Закомітити зміни через auto_update або вручну. |
| 9 | Додати компоненту в builder/config/component-list.txt. |
| 10 | Налаштувати ignore-файл для компоненти. |
| 11 | Змінити версію в setup.py. |
| 12 | Додати опис змін у history.txt. |
| 13 | Завантажити компоненту через python k2update_push.py. |
| 14 | Оновити компоненту на deb1-deb3 і протестувати функціонал. |
Мінімальний чеклист компоненти
| Елемент | Для чого потрібен |
|---|---|
| Каталог у components | Місце розміщення коду компоненти. |
| Git-репозиторій | Версіонування, спільна робота й передача змін. |
| setup.py | Версія компоненти та тип версії: stable або testing. |
| history.txt | Опис змін у новій версії. |
| component-list.txt | Список компонент, які завантажуються на сервер оновлення. |
| ignore-файл | Список файлів і папок, які не потрібно завантажувати. |
| token.txt | Токен доступу до сервера оновлення. |
| k2update_push.py | Скрипт завантаження компонент у систему оновлення. |
| deb1-deb3 | Тестові домени для перевірки оновленої компоненти. |
Типові помилки під час створення модулів
Найчастіша помилка — створити код компоненти, але не підключити її до Git-репозиторію або не додати в список компонент для оновлення.
Друга помилка — змінити код, але не оновити версію в setup.py.
Третя помилка — не додати опис змін у history.txt. Через це складніше зрозуміти, що саме було змінено в новій версії.
Четверта помилка — не налаштувати ignore-файл. У такому разі на сервер оновлення можуть потрапити зайві службові файли, наприклад __pycache__ або .git.
П’ята помилка — не протестувати компоненту на тестових доменах deb1-deb3 після завантаження.
Безпека під час роботи з модулями
Під час створення модулів K2 ERP потрібно уважно ставитися до доступів, токенів і репозиторіїв.
Файл:
token.txt
містить токен доступу до сервера оновлення, тому його не можна публікувати у відкритому доступі.
SSH-ключі, паролі, токени, адреси внутрішніх репозиторіїв і службові доступи мають зберігатися контрольовано.
Перед завантаженням компоненти потрібно перевірити, що в пакет оновлення не потрапляють локальні файли, кеші, тестові дані, тимчасові конфігурації або приватні ключі.
Коротко
| Питання | Відповідь |
|---|---|
| Що створюється? | Модуль або компонента K2 ERP. |
| Де розміщується код? | У каталозі components. |
| Як підключати компоненти? | Через auto_update або вручну через Git. |
| Як клонувати компоненти через auto_update? | python git_cmd.py clone |
| Як перевірити статус? | git status або python git_cmd.py status |
| Як закомітити зміни? | git commit -m "Назва комміту" або python git_cmd.py commit |
| Де змінюється версія? | У файлі setup.py. |
| Де описуються зміни? | У файлі history.txt. |
| Де задається список компонент для оновлення? | У builder/config/component-list.txt. |
| Як завантажити компоненту? | python k2update_push.py |
| Де тестувати? | На тестових доменах deb1, deb2 і deb3. |