Класи та команди K2 ERP Python

Класи та команди K2 ERP Python — це технічна документація для розробників, які працюють із Python-версією K2 ERP, створюють компоненти, підключають системні класи, використовують API, пишуть документацію, тести та допоміжні JavaScript-функції.

Документ описує загальні вимоги до компонентів K2 ERP, базові системні класи, структуру компонентів, правила документування та приклади використання окремих класів.

Коротко. Компонент K2 ERP має бути не просто набором Python-файлів. Він повинен мати зрозумілу структуру, моделі, роути, API, залежності, документацію, історію змін, тести, локалізації, приклади та ресурси.

Призначення документа

Ця сторінка потрібна для того, щоб розробники K2 ERP працювали з компонентами в єдиному стилі.

Документація допомагає зрозуміти:

• як має виглядати структура компоненти;
• які файли є обов’язковими;
• де зберігати моделі, роути, хуки й додаткові об’єкти;
• як описувати залежності;
• як оформлювати документацію для користувачів і розробників;
• які базові класи доступні в ядрі K2 ERP;
• як використовувати системні API;
• які JavaScript-допоміжні функції доступні для інтерфейсу.

Генерація документації з docstring

Для автоматичної генерації HTML-документації з docstring можна використовувати стандартний інструмент `pydoc`.

Приклад команди:

pydoc -w k2/k2obj.py

де:

k2/k2obj.py

— шлях до Python-файлу від кореня проєкту.

Важливо. Щоб автоматична документація була корисною, класи й методи потрібно описувати зрозумілими docstring-коментарями, а не залишати код без пояснень.

Вимоги до компоненти K2 ERP

Компонента K2 ERP повинна мати стандартизовану структуру. Це потрібно для того, щоб систему можна було оновлювати, документувати, тестувати й підключати до інших модулів без ручного хаосу.

Основні частини компоненти:

Частина	Призначення
models.py	ORM-структури та моделі бази даних компоненти
views.py	Головний клас компоненти, роути та API
objects/	Додаткові класи, від яких залежить функціонал компоненти
hooks.py	Хуки для розширення або зміни стандартної поведінки системи
requirements-components.txt	Залежності від інших компонент K2 ERP
requirements.txt	Python-залежності компоненти
README.md	Опис цілі компоненти, способу використання та важливих приміток
history.txt	Історія змін, написана зрозумілою для користувача мовою
doc/	Документація, схеми, бізнес-процеси та інструкції
tests/	Юніт-тести компоненти
examples/	Приклади використання компоненти
widgets/	Віджети, дашборди та візуальні елементи
languages/	Локалізації та переклади
static/	Зображення, стилі, JavaScript, текстові ресурси
templates/	Шаблони компоненти
yml/	YML-конфігурації

Залежності компоненти

Якщо компонента залежить від інших компонент K2 ERP, ці залежності потрібно вказати у файлі:

requirements-components.txt

Приклад:

k2log==2.0.0.2
k2grid==2.0.4.1
k2form==2.0.1.27

Python-залежності, якщо вони потрібні, вказуються у файлі:

requirements.txt

Документація компоненти

Компонента повинна мати документацію для різних груп користувачів.

Каталог	Що зберігається
doc/schema	Структура бази даних, зокрема SQL Power Architect-схеми
doc/business_processes	Бізнес-процеси та схеми роботи у форматі Draw.io
doc/user_manual	Інструкція користувача
doc/developer_documentation	Документація для розробників, згенерована автоматично з коментарів
doc/additional_developer_docs	Додаткова документація для розробників

Інструкція користувача повинна автоматично підтягуватися системою документації K2 ERP, створюючи окремий розділ документації для встановленого продукту.

Локалізації

У K2 ERP використовуються щонайменше українська та англійська мови.

Файли перекладів зберігаються у структурі:

/languages/en/LC_MESSAGES/messages.po
/languages/en/LC_MESSAGES/messages.mo

Ядро K2 ERP має підтримувати роботу з перекладами та давати можливість покращувати локалізацію стороннім користувачам або розробникам.

Ресурси компоненти

Ресурси компоненти зберігаються у стандартних каталогах:

Каталог	Призначення
/static	Зображення, тексти, JavaScript, CSS та інші статичні ресурси
/static/img	Іконки та зображення компоненти
/templates	Шаблони компоненти
/yml	YML-конфігурації
/data	Дані компоненти, якщо вони потрібні

Шаблони мають бути розроблені так, щоб не конфліктувати з глобальними шаблонами системи.

Принцип. Компонента повинна бути самодостатньою, але не повинна ламати глобальну структуру K2 ERP.

Авторство

У компоненті має бути вказане авторство.

Для компонент K2 використовується стандартний формат:

Copyright © 2000-2025 К2®, Rudiuk Serhii. All rights reserved.

Якщо компоненту створює сторонній розробник, потрібно вказати інформацію про такого розробника.

Приклад структури компоненти

Нижче наведено приклад типової структури компоненти K2 ERP.

components/
└── k2adm/
    ├── k2adm/
    │   ├── data/
    │   ├── languages/
    │   ├── static/
    │   ├── templates/
    │   ├── yml/
    │   ├── tests/
    │   ├── examples/
    │   ├── widgets/
    │   ├── objects/
    │   ├── users/
    │   │   └── users.py
    │   ├── roles/
    │   │   └── roles.py
    │   ├── __init__.py
    │   ├── forms.py
    │   ├── history.txt
    │   ├── hooks.py
    │   ├── models.py
    │   └── views.py
    ├── __init__.py
    ├── doc/
    │   ├── schema/
    │   ├── business_processes/
    │   ├── user_manual/
    │   ├── developer_documentation/
    │   └── additional_developer_docs/
    ├── history.txt
    ├── requirements-components.txt
    ├── requirements.txt
    └── setup.py

Системні класи

Системні класи K2 ERP забезпечують базову роботу ядра, об’єктів, безпеки, шляхів, даних, налаштувань, повідомлень, перекладів і оновлень.

Основні системні класи:

Клас	Призначення
K2	Ядро системи K2 ERP
K2Obj	Базовий клас для об’єктів системи
K2admin_menus	Формування меню для конкретного користувача
k2data	Робота з даними
k2datasync	Синхронізація даних
k2logging	Логування повідомлень і помилок
k2mail	Робота з поштою
k2notifications	Сповіщення користувачів
k2path	Пошук шляхів у системі
k2secur	Безпека та доступи
k2settings	Налаштування системи
k2trans	Переклади
k2upd	Оновлення

Клас K2

K2 — це ядро системи K2 ERP.

Клас відповідає за базові параметри домену, підключення до бази даних, мову, поточного користувача, список компонентів, налаштування, доступи, сесії та службові методи.

Основні властивості класу

Властивість	Опис
domain_name	Назва домену
domain_protocol	Протокол домену
domain	Поточний домен
port	Порт
db	Підключення до бази даних
default_language	Мова за замовчуванням

Основні властивості інстансу

Властивість	Опис
self.secur	Підключення класу безпеки
self.path	Підключення класу пошуку шляхів
self.data	Підключення класу синхронізації даних
self.settings	Підключення класу налаштувань
self.notifications	Підключення класу сповіщень

Приклади використання K2

Отримати домен:

K2().domain

Отримати поточного користувача:

K2().get_current_user()

Отримати id поточного контрагента:

K2().get_user_counterparts_id()

Отримати список встановлених компонент:

K2().component_list()

Отримати назву поточного проєкту:

K2().get_user_project_name()

Створити користувача на рівні бази даних:

K2().create_db_role(user_name, password)

Згенерувати ID:

id = K2.generate_id()

Отримати права поточного користувача:

usr_perm = K2().get_user_permissions()

Визначити платформу:

K2.get_platform()

Знайти YML-файл:

yml_path = K2.search_yml('users')

Основні методи K2

Метод	Призначення
component_list()	Пошук встановлених компонент
get_current_user()	Повертає об’єкт поточного користувача
get_user_counterparts_id()	Пошук id поточного контрагента
get_user_counterparts_name()	Пошук назви поточного контрагента
get_user_project_id()	Пошук id поточного проєкту користувача
get_user_project_name()	Пошук назви поточного проєкту користувача
get_user_storage_id()	Пошук id поточного складу
get_user_stoages_name()	Пошук назви поточного складу
get_user_structural_division_id()	Пошук id поточного підрозділу
get_user_structural_division_id_tree()	Пошук підрозділів за ієрархією
get_menu_url()	Повертає список URL активних пунктів меню
search_menu_items()	Пошук пунктів меню
search_menu_items_category()	Пошук категорій пунктів меню
search_static_files()	Пошук статичних файлів
url_map()	Робота з картою URL

Методи роботи з базою даних і сесіями

Метод	Призначення
init_db()	Підключення db_uri для вибраної бази даних
init_db_custom(key)	Підключення custom db_uri за ключем
init_db_uri()	Пошук і ініціалізація файлу підключення до бази даних
init_db_uri_custom()	Зчитування підключень із db_custom.yml
init_db_uri_user()	Ініціалізація підключення до БД для поточного користувача
init_db_user()	Підключення db_uri для користувача
create_db_role(user_name, password)	Створення користувача на рівні БД
drop_db_role(user_name)	Видалення користувача на рівні БД
kill_user_sessions(target_username)	Завершення сесій користувача на рівні БД

Методи авторизації користувачів

Метод	Призначення
add_authorized_users(user_id, login)	Додає користувача до списку авторизованих
check_authorized_users(user_id)	Перевіряє, чи користувач активний
check_logout_users(user_id)	Перевіряє користувачів, що вийшли
dell_authorized_users(user_id)	Видаляє користувача зі списку авторизованих
get_authorized_users()	Отримує список авторизованих користувачів

Методи класу K2

Метод	Призначення
generate_id()	Генерація ID
compare_versions(version1, version2)	Порівняння версій
get_platform()	Визначення операційної системи
get_locale()	Визначення поточної мови
get_locale_id()	Визначення id поточної мови
get_active_lang_list()	Отримання списку активних мов
get_user_role(user_id)	Отримання roleid користувача
get_current_user_role_name()	Отримання role name поточного користувача
get_path_abs(caller_file)	Абсолютний шлях до файлу, в якому виконується код
get_path_to_root(caller_file)	Відносний шлях до кореня
search_yml(name_yml)	Пошук YML-файлу в каталогах компонент
search_comp_names()	Пошук ідентифікаторів компонент
load_babel_translation_directories()	Завантаження перекладів

Приклад отримання абсолютного шляху:

K2.get_path_abs(__file__)

Приклад отримання відносного шляху до кореня:

K2.get_path_to_root(__file__)

Логування та повідомлення K2

K2 має методи для збереження, завантаження та відправлення повідомлень користувачу.

Основний метод:

K2.logging_message(status, message, page_url=None, show_message=True)

Приклади:

K2.logging_message(K2.log_error, 'Operation completed with error.')

K2.logging_message(
    status=K2.log_success,
    message='Operation completed successfully.',
    page_url='/kadm/users',
    show_message=False
)

Метод може зберігати повідомлення в журналі та відправляти його клієнту через Socket.IO.

Права користувача

Метод:

K2().get_user_permissions()

повертає права поточного користувача для URL, до якого він звертається.

Результат містить roleid та прапорці доступу, зокрема:

• r — читання;
• w — запис;
• i — вставка;
• d — видалення;
• c — створення;
• exp — експорт;
• imp — імпорт;
• del_ — відновлення;
• settable — налаштування таблиці;
• cutpast — вирізати / вставити;
• enable — доступність;
• active — активність.

Приклад:

current_user_permissions = K2().get_user_permissions()

Клас K2Obj

K2Obj — базовий клас для об’єктів системи K2 ERP.

Від нього наслідуються об’єкти, які використовують стандартну логіку системи: конфігурації, YML, grids, форми, параметри, кнопки, джерела даних і розширення.

Основні властивості класу

Властивість	Опис
name	Назва компоненти
version	Версія компоненти

Основні властивості інстансу

Властивість	Опис
self._name_yml	Назва конфігураційного YML-файлу
self._name_yml_tree	Назва YML-файлу з деревом
self._new_buttons	Нові кнопки
self._name_yml_master	Майстер-конфігурація
self._send_params	Параметри для конфігураційного файлу
self._send_group_params	Параметри групи
self._report_id	ID звіту
self._data_source	Джерела даних
self._off_buttons	Кнопки, які потрібно вимкнути
self._row_selection	Вибір рядка

Основні методи K2Obj

Метод	Призначення
__init__()	Ініціалізація об’єкта
content()	Формування контенту
create_names_yml()	Створення назв YML-конфігурацій
search_class_prop()	Пошук властивостей для розширення класу
select_grid()	Вибір grid
show_grid()	Відображення grid

Класи компонент

Класи компонент реалізують функціональність конкретних модулів K2 ERP.

Основні приклади:

Клас	Призначення
K2Site	Робота з сайтом
K2Grid	Робота з таблицями та grid-компонентами
K2WMS	Складські процеси та WMS
K2CRM	CRM-функціональність
K2DocsCRM	Документи CRM
K2Report	Звіти та друковані форми
K2ReportEmbed	Вбудовування звітів у вебсторінки
K2ReportDesigner	Конструктор звітів і дашбордів
K2Production	Виробничі процеси
K2LogbookTMDoc	Логбук технічного обслуговування
K2EquipmentFunction	Робота з обладнанням

Клас K2UpdateRemainder

K2UpdateRemainder відповідає за оновлення залишків на основі даних, отриманих від клієнтів.

Клас обробляє дані з логів, створює або оновлює записи про залишки товарів і керує їхніми статусами.

Статуси залишків

Статус	Значення
new	Нові залишки, отримані в поточному оновленні
stable	Підтверджені залишки, доступні користувачам
old	Застарілі дані, що підлягають видаленню

Основні методи

Метод	Призначення
update_pub_sub_remainder()	Оновлює залишки на основі даних Pub/Sub
_insert_new_pub_sub_nomenclature(session, nomenclature_data)	Додає нову номенклатуру, якщо її ще немає

Клас K2CRM

K2CRM — клас CRM-модуля K2 ERP.

Він забезпечує роботу з лідами, замовленнями, рахунками, звітами та налаштуваннями CRM.

Клас наслідується від K2Obj, тому використовує базові властивості та методи системних об’єктів K2 ERP.

Клас K2DocsCRM

K2DocsCRM — частина CRM-модуля, яка відповідає за роботу з документами та даними CRM.

Клас також наслідується від K2Obj.

Основні атрибути

Атрибут	Призначення
database	База даних через глобальний об’єкт K2.db
time_zone	Часовий пояс системи через K2.timezone
domain	Поточний домен через K2.domain

Основні методи K2DocsCRM

Метод	Призначення
create_contact()	Створює контакт на основі даних ліда
check_lead()	Перевіряє, чи існує контакт із заданим телефоном
crm_data(route, data)	Отримує дані для друкованих форм CRM
process_options()	Обробляє параметри JSON-запиту й налаштовує об’єкти K2Grid

Метод create_contact()

create_contact() створює контакт на основі даних існуючого ліда.

Логіка роботи:

1. отримує JSON із lead_id;
2. перевіряє, чи передано lead_id;
3. шукає лід у таблиці k2lead;
4. створює запис у таблиці k2contacts;
5. у разі помилки скасовує транзакцію та повертає опис помилки.

Метод check_lead()

check_lead() перевіряє, чи існує контакт із заданим номером телефону в таблиці k2contacts.

Якщо контакт знайдено, метод оновлює дані ліда: ім’я, прізвище, email та lead_id. Якщо контакт не знайдено, відповідні поля очищаються.

Метод crm_data(route, data)

crm_data() отримує дані з таблиць бази для формування друкованих форм документів у CRM.

Метод збирає дані по товарах, організації, контрагенту, складу, договору, відповідальній особі та клієнту, після чого повертає результат у JSON-форматі.

Метод process_options()

process_options() обробляє JSON-запит і налаштовує K2Grid залежно від значення параметра name.

Приклади сценаріїв:

Значення name	Дія
k2doc_rows_detail	Створює grid для деталізації рядків документа, вимикає зайві кнопки, передає row_id і storage_id
k2doc_move	Створює grid руху документа, вимикає кнопки додавання, редагування, видалення та друку

Клас K2Report

K2Report забезпечує генерацію та друк звітів за допомогою API Stimulsoft.

Клас наслідується від K2Obj і є батьківським класом для:

• K2ReportEmbed;
• K2ReportDesigner.

Основні можливості

• створення звітів;
• робота з конструктором звітів;
• управління друкованими формами;
• генерація друкованих документів;
• взаємодія з API Stimulsoft;
• візуалізація та експорт звітів.

Основні методи K2Report

Метод	Призначення
__init__(sql=[])	Ініціалізує клас і отримує шлях до каталогу виклику
create_report(sql=None, data_source=None)	Створює звіт і відображає редактор або переглядач
get_report(file_name)	Отримує звіт за назвою файлу
execute_query(query, params=None)	Виконує SQL-запит
get_report_designer(file_name, design_type_id)	Отримує дизайнер звіту за типом дизайну
add_reports_type(name, data)	Додає тип звіту до групи звітів

Клас K2ReportEmbed

K2ReportEmbed використовується для вбудовування звітів у вебзастосунок.

Клас дозволяє отримувати та відображати звіти з бази даних за їхніми ідентифікаторами.

Ініціалізація

K2ReportEmbed(reports_id: List[str])

де reports_id — список ідентифікаторів звітів.

Основний метод

get_report_data() -> Optional[List[Dict[str, Any]]]

Метод отримує дані звітів із бази даних і формує JSON-структуру для відображення.

Приклад backend Flask

@k2production.route('/test_dashboard', methods=['GET'])
def test_dashboard():
    reports_id = [
        'b452a5ae84f9e92e75eb0467c196fd71',
        '1673a4fab757fb6c5df970fdc6ee680c',
        '49952f397efff44d7ce0e5cb9aa625fb'
    ]

    k2report_embed = K2ReportEmbed(reports_id)

    return render_template(
        'k2dashboard_production/k2dashboard_production.html',
        dashboard_settings=k2report_embed
    )

Приклад Jinja-шаблону

{% extends template_name + '/base.html' %}

{% block content %}
    {% if error %}
        {{ error }}
    {% else %}
        {% include dashboard_settings.template %}
    {% endif %}
{% endblock %}

Клас K2ReportDesigner

K2ReportDesigner надає функціональність для створення, редагування та перегляду звітів і дашбордів.

Клас взаємодіє з базою даних, керує файлами звітів і генерує JSON-дані для подальшого використання.

Основні методи

Метод	Призначення
designer()	Відображає сторінку редагування друкованої форми
viewer()	Відображає сторінку перегляду друкованої форми
dashboard_viewer()	Відображає сторінку перегляду дашборду
dashboard_designer()	Відображає сторінку редагування дашборду
json_data_create(...)	Створює JSON-дані на основі джерел даних і періоду
save_report_id()	Зберігає ідентифікатор і налаштування звіту
mrt_report_create(report_id, design_type_id=None)	Створює MRT-файл звіту на основі шаблону
table_report_data(datasource_value, datasource_keys)	Обробляє SQL-дані для джерел звіту
save_info_report_designer()	Зберігає інформацію про звіт і генерує MRT-файл
data_source_lists_creating(group_reports_id)	Створює списки джерел даних для звіту

Приклад json_data_create()

datasource_value = ["SELECT * FROM table1", "SELECT * FROM table2"]
datasource_keys = ["table1_data", "table2_data"]
datasource_is_counterpart_id = [True, False]
datasource_is_storage_id = [False, True]
period = 1
date_from = "2023-01-01"
date_to = "2023-12-31"

json_data = k2_designer.json_data_create(
    datasource_value,
    datasource_keys,
    datasource_is_counterpart_id,
    datasource_is_storage_id,
    period,
    date_from,
    date_to
)

Клас K2Production

K2Production використовується для виробничих процесів.

У документації клас згадується в контексті схеми вибору обслуговування терміналу.

Клас K2LogbookTMDoc

K2LogbookTMDoc керує логбуком технічного обслуговування.

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

Основні групи методів

Група	Методи	Призначення
Відображення логбука	k2logbook_tm(), take_logbook_tm(), edit_logbook_tm()	Відкриття списку, форми та редагування логбука
Планове і позапланове ТО	planned_tm(), unplanned_tm(), create_unplanned_task()	Робота з плановим і позаплановим технічним обслуговуванням
Параметри	write_logbook_params(), read_logbook_params()	Збереження та читання параметрів логбука
Запчастини	pull_spare_parts_data(), spare_parts_check(), take_material_by_qr(), return_material_by_qr()	Робота із запчастинами та матеріалами
Кроки ТО	task_step_form(), save_step(), end_step(), end_step_manager()	Обробка кроків технічного обслуговування
Перевірки	step_image_check(), step_data_check(), detail_check(), equipment_qr_confirmation()	Перевірка зображень, даних, деталей і QR-кодів
Статуси	decline_task(), confirm_task(), send_on_revision_task(), requires_partner(), join_task()	Керування статусами завдань
Звіти та зображення	e_report_logbook(), get_all_employee_image(), get_employee_image(), get_image_logbook()	Звіти та робота із зображеннями логбука

Клас K2EquipmentFunction

K2EquipmentFunction — підклас K2Obj, призначений для роботи з функціональністю обладнання в K2 ERP.

Клас містить методи для обробки запитів на затвердження змін у технічній документації обладнання.

Атрибути

path_class = 'components/k2production/k2production/k2equipment'
file_class = 'k2equipment'

Метод send_approval_request_from_hook()

send_approval_request_from_hook(self, data)

Метод відправляє запит на затвердження змін у технічній карті обладнання.

Очікувані дані:

Поле	Призначення
equipment_type_id	Ідентифікатор типу обладнання
changed_fields	Словник зі зміненими полями та їхніми значеннями

Логіка роботи:

1. перевіряє наявність записів із parentid != '0' у таблиці k2tm_fields;
2. отримує інформацію про тип обладнання з таблиці k2equipment_type;
3. шукає активних затверджувачів у таблиці k2users_for_approval;
4. формує опис змін;
5. формує URL для сторінки затвердження;
6. надсилає повідомлення через K2Notifications.send_approval_request().

Метод повертає JSON-відповідь про успіх або помилку.

K2 ERP JavaScript

У K2 ERP використовуються допоміжні JavaScript-функції для роботи з інтерфейсом, зображеннями, завантаженням і повідомленнями користувачу.

createImageSliderModal()

createImageSliderModal(images, containerId = null)

Створює слайдер зображень у контейнері або модальному вікні.

Параметри:

Параметр	Опис
images	Масив URL-адрес зображень
containerId	Ідентифікатор контейнера для вставки слайдера

Повертає ідентифікатор створеного каруселя або модального вікна. Якщо зображення відсутні, показує повідомлення та повертає null.

showBootstrapLoader()

showBootstrapLoader(containerId)

Додає анімацію завантаження у вказаний контейнер.

removeBootstrapLoader()

removeBootstrapLoader(containerId)

Видаляє анімацію завантаження з контейнера.

showUserAlert()

showUserAlert(message, type = 'light')

Відображає повідомлення користувачу у вигляді Bootstrap Toast.

Параметри:

Параметр	Опис
message	Текст повідомлення
type	Тип повідомлення: primary, success, danger, warning, info, light

Ілюстрації

• 
  Ілюстрація K2 ERP Python

Коротко

Питання	Відповідь
Для кого ця сторінка?	Для розробників K2 ERP Python
Що описує документ?	Вимоги до компонентів, системні класи, API, CRM, звіти, production-класи та JavaScript-утиліти
Який базовий клас системи?	K2
Від чого наслідуються об’єкти системи?	Від K2Obj
Де описуються залежності компонент?	У requirements-components.txt та requirements.txt
Де зберігається документація?	У каталозі doc/
Де зберігаються локалізації?	У каталозі languages/
Які JavaScript-функції описані?	Слайдер зображень, loader, видалення loader та повідомлення користувачу

Див. також

• K2 ERP
• K2 ERP
• Python
• API
• Документація для розробників
• K2 ERP Javascript
• Розгортання системи K2 ERP Python для розробників
• Компоненти K2 ERP
• K2 CRM
• K2 Report
• K2 Production