Технічне завдання: Редактор ER-моделей K2 ERP

Редактор ER-моделей K2 ERP — модуль для графічного проєктування структури бази даних, опису сутностей, полів, звʼязків, індексів, обмежень, бізнес-метаданих і подальшого збереження моделі у форматі YAML. На основі YAML-опису різні генератори можуть створювати ORM-моделі, міграції, API-схеми, документацію та інші артефакти для різних мов програмування.

1. Мета розробки

Розробити в K2 ERP графічний редактор ER-моделей, який дозволяє:

• створювати структуру бази даних у візуальному режимі;
• описувати таблиці, поля, типи даних, звʼязки та обмеження;
• задавати індекси, ключі, enum-и, довідники та технічні метадані;
• зберігати модель у форматі YAML;
• версіонувати зміни структури;
• перевіряти модель на помилки;
• використовувати YAML як єдине джерело правди для генерації ORM;
• генерувати ORM-код для різних мов програмування через окремі генератори;
• формувати документацію по структурі бази даних;
• підтримувати командну роботу над моделями.

2. Основна концепція

Редактор не повинен бути привʼязаний до однієї мови програмування або одного ORM. Його задача — створити універсальний опис ER-моделі.

Графічний ER-редактор
        ↓
YAML-модель
        ↓
Генератори
        ↓
ORM / міграції / API / документація

Приклад цільової схеми:

K2 ER Editor

   ↓

schema.yml

   ↓

Python SQLAlchemy generator

   ↓

models.py
schema.yml

   ↓

TypeScript Prisma generator

   ↓

schema.prisma
schema.yml

   ↓

C# Entity Framework generator

   ↓

DbContext + Entities
schema.yml

   ↓

PHP Laravel generator

   ↓

Eloquent Models + Migrations

3. Основні принципи

Принцип	Опис
Model-first	Спочатку створюється ER-модель, потім із неї генерується код.
YAML як source of truth	YAML-файл є основним джерелом структури.
ORM-agnostic	Модель не має бути жорстко привʼязана до конкретного ORM.
Графічне редагування	Користувач працює з діаграмою, а не тільки з текстовим YAML.
Двостороння синхронізація	Зміни на діаграмі оновлюють YAML, а зміни YAML оновлюють діаграму.
Валідація	Перед збереженням модель перевіряється на помилки.
Версіонування	Зміни ER-моделі мають зберігатися в історії.
Розширюваність	Має бути можливість додавати нові генератори мов і ORM.

4. Основні користувачі

Роль	Опис	Основні дії
Архітектор	Проєктує структуру даних.	Створення моделей, сутностей, звʼязків, правил.
Backend-розробник	Використовує YAML для генерації ORM.	Перегляд, редагування, генерація коду.
Аналітик	Описує бізнес-сутності та поля.	Додавання описів, коментарів, бізнес-атрибутів.
DBA	Перевіряє індекси, ключі, обмеження.	Аналіз структури БД, performance-рекомендації.
DevOps	Використовує YAML у CI/CD.	Генерація міграцій, перевірка схем.
Адміністратор	Налаштовує права, шаблони, генератори.	Управління доступами та конфігурацією.

5. Функціональні блоки редактора

Редактор має складатися з таких частин:

• графічне полотно ER-діаграми;
• панель інструментів;
• дерево моделі;
• панель властивостей;
• YAML-редактор;
• валідатор моделі;
• менеджер звʼязків;
• менеджер enum-ів;
• менеджер індексів;
• менеджер версій;
• генератор ORM;
• перегляд згенерованого коду;
• експорт та імпорт;
• журнал змін.

6. Загальний вигляд інтерфейсу

Рекомендована структура екрана:

+--------------------------------------------------------------------------------+
| Верхня панель: Назва моделі | Save | Validate | Generate | Export | Settings   |
+----------------------+-----------------------------------------+---------------+
| Дерево моделі        | Графічне полотно ER-діаграми            | Властивості   |
|                      |                                         |               |
| - Entities           |  +-------------+       +-------------+  | Entity/Field  |
|   - Customer         |  | Customer    | 1   N | Order       |  | properties    |
|   - Order            |  |-------------|-------|-------------|  |               |
| - Enums              |  | id          |       | id          |  |               |
| - Relations          |  | name        |       | customer_id |  |               |
| - Indexes            |  +-------------+       +-------------+  |               |
+----------------------+-----------------------------------------+---------------+
| Нижня панель: Errors | Warnings | YAML | Generated Code | Migration Preview    |
+--------------------------------------------------------------------------------+

7. Графічне полотно ER-діаграми

7.1. Основні вимоги

Графічне полотно має дозволяти:

• створювати сутності;
• переміщувати сутності;
• змінювати розміри блоків;
• створювати звʼязки drag-and-drop;
• групувати сутності по доменах;
• масштабувати діаграму;
• переміщувати полотно;
• автоматично розкладати схему;
• фільтрувати видимі сутності;
• шукати сутності та поля;
• підсвічувати залежності;
• відкривати властивості сутності, поля або звʼязку.

7.2. Дії на полотні

Дія	Опис
Подвійний клік по пустому місцю	Створення нової сутності.
Подвійний клік по сутності	Відкриття повної картки сутності.
Клік по полю	Відкриття властивостей поля.
Drag від поля до іншої сутності	Створення звʼязку.
Ctrl + колесо миші	Масштабування.
Space + drag	Переміщення полотна.
Delete	Видалення вибраного елемента після підтвердження.
Ctrl + Z	Скасування останньої дії.
Ctrl + Y	Повтор дії.

7.3. Відображення сутності

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

+-----------------------------+
| Customer                    |
|-----------------------------|
| PK id: uuid                 |
| name: string                |
| email: string unique        |
| created_at: datetime        |
|-----------------------------|
| indexes: 2                  |
| relations: 3                |
+-----------------------------+

7.4. Візуальні позначення

Позначення	Значення
PK	Primary key.
FK	Foreign key.
UQ	Unique constraint.
IDX	Indexed field.
NN	Not nullable.
DEF	Default value.
RO	Read-only field.
SYS	System field.

8. Сутності

Сутність відповідає таблиці, колекції або ORM-класу.

8.1. Поля сутності

Поле	Тип	Обовʼязкове	Опис
name	string	Так	Технічна назва сутності.
table	string	Так	Назва таблиці в БД.
label	string	Ні	Людинозрозуміла назва.
description	text	Ні	Опис призначення сутності.
module	string	Ні	Модуль K2 ERP, до якого належить сутність.
schema	string	Ні	Схема БД, наприклад public, sales, crm.
type	enum	Так	table, view, dictionary, document, register, system.
fields	list	Так	Список полів.
relations	list	Ні	Список звʼязків.
indexes	list	Ні	Індекси.
constraints	list	Ні	Обмеження.
audit	boolean	Ні	Чи вести історію змін.
soft_delete	boolean	Ні	Чи використовувати мʼяке видалення.
timestamps	boolean	Ні	Чи створювати created_at / updated_at.

8.2. Типи сутностей

Тип	Опис	Приклад
table	Звичайна таблиця.	customers, orders.
dictionary	Довідник.	currencies, countries, units.
document	Документ ERP.	sales_invoice, purchase_order.
register	Регістр або журнал рухів.	stock_movements, account_entries.
view	Представлення.	customer_balance_view.
system	Системна таблиця.	users, roles, audit_log.

9. Поля сутності

9.1. Основні властивості поля

Властивість	Тип	Обовʼязкова	Опис
name	string	Так	Технічна назва поля.
column	string	Ні	Назва колонки в БД, якщо відрізняється від name.
label	string	Ні	Назва для UI.
description	text	Ні	Опис поля.
type	enum	Так	Тип даних.
nullable	boolean	Так	Чи може бути null.
primary_key	boolean	Ні	Чи є поле первинним ключем.
unique	boolean	Ні	Чи має бути унікальним.
indexed	boolean	Ні	Чи створювати індекс.
default	string / number / expression	Ні	Значення за замовчуванням.
length	integer	Ні	Довжина для string.
precision	integer	Ні	Точність для decimal.
scale	integer	Ні	Кількість знаків після коми.
enum	reference	Ні	Посилання на enum.
reference	reference	Ні	Посилання на іншу сутність.
generated	boolean	Ні	Чи генерується автоматично.
readonly	boolean	Ні	Чи поле read-only.
system	boolean	Ні	Чи поле системне.

9.2. Підтримувані типи даних

Тип	Опис	Приклад БД
uuid	UUID-ідентифікатор.	uuid
integer	Ціле число.	integer
bigint	Велике ціле число.	bigint
smallint	Маленьке ціле число.	smallint
decimal	Точне десяткове число.	numeric(12,2)
float	Число з плаваючою точкою.	double precision
boolean	Логічне значення.	boolean
string	Рядок обмеженої довжини.	varchar(255)
text	Довгий текст.	text
date	Дата.	date
datetime	Дата та час.	timestamp
time	Час.	time
json	JSON-структура.	json / jsonb
enum	Перелік значень.	varchar / enum
binary	Бінарні дані.	bytea / blob
money	Грошове значення.	numeric(15,2)
reference	Посилання на іншу сутність.	foreign key

9.3. Системні поля

Редактор має мати можливість автоматично додавати типові системні поля:

Поле	Тип	Опис
id	uuid / bigint	Первинний ключ.
created_at	datetime	Дата створення.
updated_at	datetime	Дата оновлення.
created_by	reference	Користувач, який створив запис.
updated_by	reference	Користувач, який оновив запис.
deleted_at	datetime	Дата мʼякого видалення.
deleted_by	reference	Користувач, який видалив запис.
version	integer	Версія запису для optimistic locking.

10. Звʼязки між сутностями

10.1. Типи звʼязків

Тип	Опис	Приклад
one_to_one	Один запис відповідає одному запису.	User → UserProfile.
one_to_many	Один запис має багато дочірніх записів.	Customer → Orders.
many_to_one	Багато записів належать одному запису.	Order → Customer.
many_to_many	Багато до багатьох через проміжну таблицю.	Users ↔ Roles.
self_reference	Посилання сутності на саму себе.	Category → Parent Category.

10.2. Властивості звʼязку

Поле	Тип	Обовʼязкове	Опис
name	string	Так	Назва звʼязку.
type	enum	Так	Тип звʼязку.
from_entity	string	Так	Початкова сутність.
from_field	string	Так	Поле FK.
to_entity	string	Так	Цільова сутність.
to_field	string	Так	Зазвичай primary key.
required	boolean	Ні	Чи звʼязок обовʼязковий.
on_delete	enum	Ні	restrict, cascade, set_null, no_action.
on_update	enum	Ні	restrict, cascade, set_null, no_action.
backref	string	Ні	Назва зворотного звʼязку для ORM.
junction_entity	string	Ні	Для many_to_many.
label	string	Ні	Назва для UI.

10.3. Візуальне відображення звʼязків

На діаграмі потрібно показувати кардинальність:

Customer 1 ─────── N Order
Order    N ─────── 1 Product
User     N ─────── N Role

10.4. Правила створення звʼязку

При створенні звʼязку редактор має запропонувати:

• тип звʼязку;
• поле FK або створення нового FK-поля;
• назву звʼязку;
• назву backref;
• поведінку при delete;
• поведінку при update;
• чи є звʼязок обовʼязковим;
• чи створювати індекс на FK.

11. Індекси

11.1. Типи індексів

Тип	Опис
normal	Звичайний індекс.
unique	Унікальний індекс.
composite	Складений індекс по кількох полях.
fulltext	Повнотекстовий індекс.
partial	Частковий індекс з умовою.

11.2. Властивості індексу

Поле	Тип	Опис
name	string	Назва індексу.
fields	list	Список полів.
unique	boolean	Унікальність.
type	enum	normal, unique, fulltext, partial.
condition	string	Умова для partial index.
description	text	Опис призначення індексу.

12. Обмеження

Редактор має підтримувати такі обмеження:

Обмеження	Опис
primary_key	Первинний ключ.
foreign_key	Зовнішній ключ.
unique	Унікальність.
check	Перевірка умови.
not_null	Заборона null.
default	Значення за замовчуванням.

Приклад check-constraint:

amount >= 0

Приклад YAML:

constraints:
  - name: chk_order_amount_positive
    type: check
    expression: "amount >= 0"

13. Enum-и

13.1. Призначення

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

Приклад:

OrderStatus:
  - draft
  - confirmed
  - paid
  - cancelled

13.2. Властивості enum

Поле	Тип	Опис
name	string	Назва enum.
label	string	Людинозрозуміла назва.
description	text	Опис.
values	list	Значення.

13.3. Властивості значення enum

Поле	Тип	Опис
value	string	Технічне значення.
label	string	Назва для UI.
color	string	Колір для інтерфейсу.
order	integer	Порядок відображення.
deprecated	boolean	Чи значення застаріле.

14. YAML-формат моделі

14.1. Основні вимоги до YAML

YAML-файл має бути:

• читабельним;
• стабільним для git-diff;
• структурованим;
• незалежним від конкретного ORM;
• придатним для автоматичної генерації коду;
• валідованим через schema validator;
• версіонованим.

14.2. Загальна структура YAML

version: 1

project:
  name: k2_erp
  label: K2 ERP
  description: Main K2 ERP data model

settings:
  default_schema: public
  default_id_type: uuid
  timestamps: true
  soft_delete: false
  naming_strategy: snake_case

modules:
  - name: crm
    label: CRM
  - name: sales
    label: Sales

enums: []

entities: []

14.3. Приклад повної YAML-моделі

version: 1

project:
  name: k2_erp
  label: K2 ERP
  description: Example ER model for K2 ERP

settings:
  default_schema: public
  default_id_type: uuid
  timestamps: true
  soft_delete: true
  naming_strategy: snake_case

modules:
  - name: crm
    label: CRM
  - name: sales
    label: Sales

enums:
  - name: OrderStatus
    label: Order status
    values:
      - value: draft
        label: Draft
        color: gray
        order: 10
      - value: confirmed
        label: Confirmed
        color: blue
        order: 20
      - value: paid
        label: Paid
        color: green
        order: 30
      - value: cancelled
        label: Cancelled
        color: red
        order: 40

entities:
  - name: Customer
    table: customers
    label: Customer
    module: crm
    type: table
    description: Customer master data
    audit: true
    timestamps: true
    soft_delete: true

    fields:
      - name: id
        type: uuid
        primary_key: true
        nullable: false
        generated: true

      - name: name
        type: string
        length: 255
        nullable: false
        label: Customer name

      - name: email
        type: string
        length: 255
        nullable: true
        unique: true
        indexed: true

      - name: phone
        type: string
        length: 50
        nullable: true

    indexes:
      - name: idx_customers_email
        fields:
          - email
        unique: true

  - name: Order
    table: orders
    label: Order
    module: sales
    type: document
    description: Customer sales order
    audit: true
    timestamps: true

    fields:
      - name: id
        type: uuid
        primary_key: true
        nullable: false
        generated: true

      - name: customer_id
        type: uuid
        nullable: false
        indexed: true
        reference:
          entity: Customer
          field: id

      - name: number
        type: string
        length: 50
        nullable: false
        unique: true

      - name: status
        type: enum
        enum: OrderStatus
        nullable: false
        default: draft

      - name: amount
        type: decimal
        precision: 12
        scale: 2
        nullable: false
        default: 0

    relations:
      - name: customer
        type: many_to_one
        from_field: customer_id
        to_entity: Customer
        to_field: id
        required: true
        on_delete: restrict
        on_update: cascade
        backref: orders

    indexes:
      - name: idx_orders_customer_id
        fields:
          - customer_id
        unique: false

    constraints:
      - name: chk_orders_amount_positive
        type: check
        expression: "amount >= 0"

15. Двостороння синхронізація Diagram ↔ YAML

Редактор має підтримувати два режими роботи:

Режим	Опис
Diagram-first	Користувач редагує графічну діаграму, YAML оновлюється автоматично.
YAML-first	Користувач редагує YAML, діаграма перебудовується після валідації.

15.1. Правила синхронізації

1. Кожна зміна на діаграмі оновлює внутрішню модель.
2. Внутрішня модель серіалізується у YAML.
3. Якщо користувач редагує YAML, він спочатку проходить парсинг.
4. Якщо YAML валідний — оновлюється діаграма.
5. Якщо YAML невалідний — показується помилка з рядком і полем.

16. Валідація моделі

16.1. Обовʼязкові перевірки

Перевірка	Тип	Опис
Унікальність entity.name	Error	Не може бути двох сутностей з однаковою назвою.
Унікальність table	Error	Дві сутності не можуть мати одну таблицю, крім спеціальних випадків.
Унікальність field.name	Error	У сутності не може бути двох полів з однаковою назвою.
Primary key	Error	Кожна table/document/dictionary має мати primary key.
Валідність reference	Error	FK має посилатися на існуючу сутність і поле.
Валідність enum	Error	Поле enum має посилатися на існуючий enum.
Nullable FK	Warning	Якщо relation required=true, FK не має бути nullable.
Індекс для FK	Warning	FK-поля рекомендовано індексувати.
Назви snake_case	Warning	Якщо naming_strategy=snake_case, назви мають відповідати правилу.
Циклічні cascade-звʼязки	Warning/Error	Можуть створити проблеми при видаленні.

16.2. Рівні повідомлень

Рівень	Опис	Чи блокує збереження
Error	Критична помилка.	Так.
Warning	Потенційна проблема.	Ні.
Info	Інформаційне повідомлення.	Ні.

17. Генерація ORM

17.1. Основна ідея

Редактор ER-моделей не повинен напряму містити логіку всіх ORM. Він має формувати універсальний YAML, а генерація виконується окремими генераторами.

schema.yml
  ↓
generator-python-sqlalchemy
  ↓
SQLAlchemy models

schema.yml
  ↓
generator-typescript-prisma
  ↓
Prisma schema

schema.yml
  ↓
generator-csharp-ef
  ↓
Entity Framework models

schema.yml
  ↓
generator-php-laravel
  ↓
Laravel Eloquent models

17.2. Підтримувані генератори в MVP

Генератор	Пріоритет	Результат
Python SQLAlchemy	Високий	models.py, relationships, indexes.
TypeScript Prisma	Високий	schema.prisma.
SQL DDL	Високий	CREATE TABLE, indexes, constraints.
Markdown documentation	Середній	Документація структури БД.
C# Entity Framework	Середній	Entity classes, DbContext.
PHP Laravel Eloquent	Низький	Models, migrations.

17.3. Налаштування генерації

У редакторі має бути розділ Generators, де задається:

• мова програмування;
• ORM;
• output path;
• naming strategy;
• чи генерувати міграції;
• чи генерувати relationships;
• чи генерувати validation schemas;
• чи генерувати DTO;
• чи перезаписувати файли;
• чи використовувати partial classes / custom blocks.

Приклад YAML:

generators:
  - name: python_sqlalchemy
    enabled: true
    output: ./generated/python
    options:
      base_class: Base
      use_mapped_column: true
      generate_relationships: true
      generate_indexes: true

  - name: prisma
    enabled: true
    output: ./generated/prisma
    options:
      provider: postgresql
      relation_mode: foreignKeys

18. Генерація міграцій

18.1. Призначення

Редактор має вміти порівнювати дві версії YAML-моделі й формувати опис змін.

schema_v1.yml
    ↓ compare
schema_v2.yml
    ↓
migration plan

18.2. Типи змін

Зміна	Приклад	Рівень ризику
Додана таблиця	Add Customer.	Low.
Додано nullable-поле	Add phone.	Low.
Додано not null поле без default	Add amount not null.	High.
Видалено поле	Drop email.	High.
Змінено тип поля	string → integer.	High.
Додано індекс	Add idx_customer_email.	Medium.
Видалено таблицю	Drop orders.	Critical.

18.3. Migration preview

Редактор має показувати попередній перегляд:

+ Add table customers
+ Add field customers.email
+ Add index idx_customers_email
! Change field orders.amount decimal(10,2) → decimal(12,2)
- Drop field customers.old_code

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

19. Версіонування моделей

19.1. Вимоги

Система має підтримувати:

• історію версій;
• порівняння версій;
• rollback до попередньої версії;
• коментар до версії;
• автора зміни;
• дату зміни;
• статус версії.

19.2. Статуси версії

Статус	Опис
draft	Чернетка.
review	Очікує перегляду.
approved	Затверджено.
released	Використовується для генерації production-коду.
archived	Архівна версія.

20. Робота з модулями K2 ERP

Редактор має підтримувати розбиття моделі на модулі.

Приклад модулів:

• core;
• crm;
• sales;
• purchases;
• warehouse;
• finance;
• hr;
• affiliate;
• integrations.

Кожна сутність має мати поле `module`.

Приклад:

entities:
  - name: Customer
    table: customers
    module: crm

У UI має бути фільтр за модулями.

21. Пошук і навігація

Редактор має підтримувати:

• пошук сутності за назвою;
• пошук поля;
• пошук таблиці;
• пошук enum;
• пошук звʼязків;
• фільтр за модулем;
• фільтр за типом сутності;
• фільтр за помилками валідації;
• перехід від поля FK до повʼязаної сутності;
• підсвічування усіх звʼязків вибраної сутності.

22. Імпорт

22.1. Джерела імпорту

Редактор має підтримувати імпорт із:

• YAML;
• JSON;
• SQL DDL;
• існуючої БД через introspection;
• CSV-опису таблиць;
• Mermaid ER diagram;
• PlantUML ER diagram.

22.2. MVP імпорту

Для MVP достатньо:

• імпорт YAML;
• імпорт із існуючої PostgreSQL БД;
• імпорт SQL DDL у базовому режимі.

23. Експорт

Редактор має підтримувати експорт у:

• YAML;
• JSON;
• SQL DDL;
• PNG/SVG діаграми;
• PDF документацію;
• Markdown документацію;
• Mermaid ER diagram;
• PlantUML.

24. Права доступу

Дія	Архітектор	Розробник	Аналітик	DBA	Адміністратор	Перегляд
Перегляд моделі	Так	Так	Так	Так	Так	Так
Створення сутностей	Так	Так	Ні	Так	Так	Ні
Редагування полів	Так	Так	Частково	Так	Так	Ні
Редагування описів	Так	Так	Так	Так	Так	Ні
Видалення сутностей	Так	Ні	Ні	Так	Так	Ні
Затвердження версії	Так	Ні	Ні	Так	Так	Ні
Генерація ORM	Так	Так	Ні	Так	Так	Ні
Налаштування генераторів	Так	Ні	Ні	Ні	Так	Ні

25. Audit log

Потрібно зберігати історію змін.

25.1. Що логувати

• створення сутності;
• видалення сутності;
• перейменування сутності;
• додавання поля;
• видалення поля;
• зміну типу поля;
• зміну nullable;
• зміну primary key;
• створення звʼязку;
• видалення звʼязку;
• зміну індексу;
• зміну enum;
• імпорт;
• експорт;
• генерацію ORM;
• затвердження версії.

25.2. Поля audit log

Поле	Опис
user	Користувач, який зробив зміну.
action	Тип дії.
object_type	Entity, Field, Relation, Enum, Index, Model.
object_name	Назва обʼєкта.
old_value	Старе значення.
new_value	Нове значення.
created_at	Дата зміни.
comment	Коментар користувача.

26. Undo / Redo

Редактор має підтримувати:

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

Приклади дій, які мають підтримувати undo:

• створення сутності;
• переміщення сутності;
• додавання поля;
• зміна поля;
• створення звʼязку;
• видалення звʼязку;
• зміна YAML.

27. Collaboration

У майбутніх версіях бажано підтримати командну роботу.

27.1. MVP

Для MVP достатньо:

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

27.2. Наступні версії

• live collaboration;
• коментарі на сутностях;
• review workflow;
• approval process;
• conflict resolution;
• merge моделей.

28. Налаштування naming strategy

Редактор має підтримувати правила іменування.

Параметр	Опис	Приклад
entity_case	Формат назв сутностей.	PascalCase: CustomerOrder.
table_case	Формат назв таблиць.	snake_case: customer_orders.
field_case	Формат назв полів.	snake_case: customer_id.
enum_case	Формат enum.	PascalCase: OrderStatus.
index_prefix	Префікс індексів.	idx_.
fk_prefix	Префікс foreign key.	fk_.

Приклад YAML:

naming:
  entity_case: PascalCase
  table_case: snake_case
  field_case: snake_case
  enum_case: PascalCase
  index_prefix: idx_
  foreign_key_prefix: fk_

29. UI для редагування сутності

Картка сутності має містити вкладки:

• General;
• Fields;
• Relations;
• Indexes;
• Constraints;
• ORM;
• UI metadata;
• Audit;
• YAML Preview.

29.1. General

Поля:

• name;
• table;
• label;
• module;
• schema;
• type;
• description;
• audit;
• timestamps;
• soft_delete.

29.2. Fields

Функції:

• додати поле;
• редагувати поле;
• видалити поле;
• змінити порядок;
• позначити primary key;
• позначити unique;
• позначити indexed;
• зробити nullable / not nullable;
• вибрати enum;
• вибрати reference.

29.3. Relations

Функції:

• створити звʼязок;
• редагувати звʼязок;
• видалити звʼязок;
• перейти до повʼязаної сутності;
• автоматично створити FK-поле.

29.4. Indexes

Функції:

• створити індекс;
• обрати поля;
• задати unique;
• задати тип індексу;
• задати condition.

29.5. ORM

Має містити ORM-специфічні налаштування, але вони не повинні ламати універсальність YAML.

Приклад:

orm:
  python_sqlalchemy:
    class_name: Customer
    table_args: []
  prisma:
    model_name: Customer
  django:
    app_label: crm

30. UI metadata

Редактор має дозволяти задавати метадані для автоматичної генерації UI.

30.1. Метадані сутності

Поле	Опис
list_view	Які поля показувати в списку.
form_view	Які поля показувати у формі.
search_fields	Поля для пошуку.
display_field	Головне поле для відображення.
icon	Іконка сутності.
color	Колір модуля або сутності.

Приклад:

ui:
  display_field: name
  list_view:
    - name
    - email
    - phone
  search_fields:
    - name
    - email
    - phone
  icon: user

31. API редактора

Редактор має мати API для інтеграції з іншими частинами K2 ERP.

31.1. Основні endpoint-и

Метод	Endpoint	Опис
GET	/api/er-models	Список моделей.
POST	/api/er-models	Створити модель.
GET	/api/er-models/{id}	Отримати модель.
PUT	/api/er-models/{id}	Оновити модель.
POST	/api/er-models/{id}/validate	Провалідувати модель.
POST	/api/er-models/{id}/generate	Запустити генерацію.
GET	/api/er-models/{id}/versions	Отримати версії.
POST	/api/er-models/{id}/export	Експорт моделі.
POST	/api/er-models/import	Імпорт моделі.

32. Зберігання моделей у K2 ERP

32.1. Сутність er_models

Поле	Тип	Опис
id	uuid	ID моделі.
name	string	Назва моделі.
label	string	Людинозрозуміла назва.
description	text	Опис.
current_version_id	uuid	Поточна версія.
status	enum	draft, review, approved, released, archived.
created_by	reference	Автор.
created_at	datetime	Дата створення.
updated_at	datetime	Дата оновлення.

32.2. Сутність er_model_versions

Поле	Тип	Опис
id	uuid	ID версії.
model_id	uuid	Посилання на модель.
version	string	Номер версії.
yaml_content	text	YAML-модель.
checksum	string	Хеш YAML.
status	enum	draft, review, approved, released, archived.
comment	text	Коментар до версії.
created_by	reference	Автор.
created_at	datetime	Дата створення.

33. Нефункціональні вимоги

33.1. Продуктивність

Редактор має підтримувати:

• до 500 сутностей в одній моделі;
• до 10 000 полів у моделі;
• до 2 000 звʼязків;
• відкриття моделі до 100 сутностей — до 3 секунд;
• відкриття моделі до 500 сутностей — до 10 секунд;
• валідація моделі до 500 сутностей — до 5 секунд;
• генерація YAML — до 3 секунд;
• генерація ORM — залежно від генератора, але з прогресом виконання.

33.2. Надійність

Система має:

• не втрачати зміни при оновленні сторінки, якщо є autosave;
• показувати конфлікти при одночасному редагуванні;
• не дозволяти зберегти невалідну модель як released;
• мати резервне збереження draft-версії;
• вести audit log.

33.3. Безпека

Потрібно:

• перевіряти права доступу;
• обмежувати генерацію коду тільки авторизованим користувачам;
• не дозволяти виконання довільного коду з YAML;
• перевіряти YAML на небезпечні конструкції;
• логувати імпорт та експорт моделей.

34. MVP

34.1. Що включити в MVP

1. Створення ER-моделі.
2. Графічне створення сутностей.
3. Додавання полів.
4. Створення one_to_many / many_to_one звʼязків.
5. Primary key, foreign key, unique, nullable.
6. Enum-и.
7. Індекси.
8. YAML export/import.
9. Валідація моделі.
10. Збереження версій.
11. Генерація SQL DDL.
12. Генерація Python SQLAlchemy.
13. Перегляд YAML поруч із діаграмою.
14. Базовий audit log.

34.2. Що можна відкласти

1. Live collaboration.
2. Merge конфліктів.
3. Складні міграції.
4. Імпорт із Mermaid / PlantUML.
5. Генерація для всіх ORM.
6. Коментарі на діаграмі.
7. AI-рекомендації по структурі.
8. Автоматична оптимізація індексів.
9. Повний reverse engineering складних БД.

35. Критерії приймання

35.1. Створення моделі

1. Користувач може створити нову ER-модель.
2. Користувач може задати назву, опис і модуль.
3. Модель зберігається в K2 ERP.
4. Для моделі створюється перша draft-версія.

35.2. Робота з сутностями

1. Користувач може створити сутність на діаграмі.
2. Користувач може задати назву таблиці.
3. Користувач може додати поля.
4. Користувач може задати primary key.
5. Користувач може видалити сутність після підтвердження.

35.3. Робота з полями

1. Користувач може додати поле.
2. Користувач може вибрати тип даних.
3. Користувач може задати nullable.
4. Користувач може задати default.
5. Користувач може задати unique та index.

35.4. Робота зі звʼязками

1. Користувач може створити звʼязок між двома сутностями.
2. Система може автоматично створити FK-поле.
3. На діаграмі показується кардинальність.
4. Звʼязок зберігається в YAML.
5. При видаленні сутності система попереджає про залежні звʼязки.

35.5. YAML

1. Діаграма експортується у валідний YAML.
2. YAML можна імпортувати назад.
3. Після імпорту відновлюються сутності, поля, enum-и та звʼязки.
4. Помилки YAML показуються користувачу.

35.6. Валідація

1. Система знаходить дублікати назв сутностей.
2. Система знаходить дублікати полів.
3. Система знаходить невалідні FK.
4. Система попереджає про FK без індексу.
5. Невалідну модель не можна перевести в released.

35.7. Генерація

1. Користувач може згенерувати SQL DDL.
2. Користувач може згенерувати Python SQLAlchemy-моделі.
3. Згенерований код можна переглянути перед завантаженням.
4. Генерація виконується з YAML-моделі.
5. Помилки генерації показуються користувачу.

36. Приклад сценарію роботи користувача

1. Архітектор створює модель “K2 Sales Model”.
2. Додає модулі crm і sales.
3. Створює сутність Customer.
4. Додає поля id, name, email, phone.
5. Створює сутність Order.
6. Додає поля id, customer_id, number, status, amount.
7. Створює enum OrderStatus.
8. Створює звʼязок Customer 1 → N Order.
9. Запускає валідацію.
10. Виправляє warnings.
11. Зберігає версію 0.1.0.
12. Генерує YAML.
13. Генерує SQLAlchemy-моделі.
14. Передає YAML у репозиторій.
15. CI/CD генерує ORM та міграції.

37. Ризики

Ризик	Наслідок	Як зменшити
YAML стане занадто ORM-специфічним	Втрата універсальності.	Розділяти core schema та orm-specific extensions.
Користувачі зламають модель через YAML-редактор	Неможливо згенерувати код.	Обовʼязкова валідація перед збереженням.
Великі моделі будуть повільно відкриватися	Поганий UX.	Lazy loading, фільтри модулів, canvas virtualization.
Генератори різних мов працюватимуть по-різному	Розбіжності в ORM.	Єдиний контракт YAML і тестові fixtures.
Видалення поля призведе до втрати даних	Ризик production-інциденту.	Migration preview і high-risk warnings.

38. Рекомендований план реалізації

38.1. Етап 1. Аналітика

1. Узгодити YAML-схему.
2. Узгодити набір типів даних.
3. Узгодити правила naming strategy.
4. Узгодити MVP-генератори.
5. Узгодити правила валідації.

38.2. Етап 2. Базовий редактор

1. Реалізувати створення моделі.
2. Реалізувати графічне полотно.
3. Реалізувати створення сутностей.
4. Реалізувати додавання полів.
5. Реалізувати панель властивостей.

38.3. Етап 3. Звʼязки та enum-и

1. Реалізувати FK-звʼязки.
2. Реалізувати відображення кардинальності.
3. Реалізувати enum-и.
4. Реалізувати індекси.

38.4. Етап 4. YAML

1. Реалізувати export YAML.
2. Реалізувати import YAML.
3. Реалізувати YAML preview.
4. Реалізувати YAML editor.
5. Реалізувати синхронізацію diagram ↔ YAML.

38.5. Етап 5. Валідація

1. Перевірка унікальності сутностей.
2. Перевірка полів.
3. Перевірка FK.
4. Перевірка enum.
5. Перевірка індексів.

38.6. Етап 6. Генерація

1. Генерація SQL DDL.
2. Генерація Python SQLAlchemy.
3. Перегляд результату.
4. Завантаження результату.
5. Обробка помилок генерації.

38.7. Етап 7. Версіонування та audit

1. Збереження версій.
2. Порівняння версій.
3. Audit log.
4. Статуси draft/review/approved/released.

39. Висновок

Редактор ER-моделей K2 ERP має стати центральним інструментом для проєктування структури даних. Його основна цінність — відокремити опис бізнес-моделі та структури БД від конкретної мови програмування або ORM.

Ключові вимоги:

• графічне редагування ER-діаграми;
• повний опис сутностей, полів, звʼязків, enum-ів, індексів і constraints;
• збереження моделі у YAML;
• двостороння синхронізація Diagram ↔ YAML;
• валідація перед збереженням і генерацією;
• генерація ORM через окремі генератори;
• підтримка версій, audit log і migration preview;
• розширюваність під різні мови програмування.

Для MVP достатньо реалізувати створення сутностей, полів, звʼязків, enum-ів, YAML import/export, базову валідацію, SQL DDL generator і Python SQLAlchemy generator.