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

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

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

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

== 2. Основна концепція ==
Редактор не повинен бути привʼязаний до однієї мови програмування або одного ORM. Його задача — створити універсальний опис ER-моделі.<pre>
Графічний ER-редактор
        ↓
YAML-модель
        ↓
Генератори
        ↓
ORM / міграції / API / документація
</pre>Приклад цільової схеми:<pre>
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
</pre>

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

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

== 5. Функціональні блоки редактора ==
Редактор має складатися з таких частин:

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

== 6. Загальний вигляд інтерфейсу ==
Рекомендована структура екрана:<pre>
+--------------------------------------------------------------------------------+
| Верхня панель: Назва моделі | 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    |
+--------------------------------------------------------------------------------+
</pre>

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

=== 7.1. Основні вимоги ===
Графічне полотно має дозволяти:

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

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

=== 7.3. Відображення сутності ===
Кожна сутність на діаграмі має відображатися як блок:<pre>
+-----------------------------+
| Customer                    |
|-----------------------------|
| PK id: uuid                 |
| name: string                |
| email: string unique        |
| created_at: datetime        |
|-----------------------------|
| indexes: 2                  |
| relations: 3                |
+-----------------------------+
</pre>

=== 7.4. Візуальні позначення ===
{| class="wikitable"
!Позначення
!Значення
|-
|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. Поля сутності ===
{| class="wikitable"
!Поле
!Тип
!Обовʼязкове
!Опис
|-
|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. Типи сутностей ===
{| class="wikitable"
!Тип
!Опис
!Приклад
|-
|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. Основні властивості поля ===
{| class="wikitable"
!Властивість
!Тип
!Обовʼязкова
!Опис
|-
|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. Підтримувані типи даних ===
{| class="wikitable"
!Тип
!Опис
!Приклад БД
|-
|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. Системні поля ===
Редактор має мати можливість автоматично додавати типові системні поля:
{| class="wikitable"
!Поле
!Тип
!Опис
|-
|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. Типи звʼязків ===
{| class="wikitable"
!Тип
!Опис
!Приклад
|-
|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. Властивості звʼязку ===
{| class="wikitable"
!Поле
!Тип
!Обовʼязкове
!Опис
|-
|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. Візуальне відображення звʼязків ===
На діаграмі потрібно показувати кардинальність:<pre>
Customer 1 ─────── N Order
Order    N ─────── 1 Product
User     N ─────── N Role
</pre>

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

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

== 11. Індекси ==

=== 11.1. Типи індексів ===
{| class="wikitable"
!Тип
!Опис
|-
|normal
|Звичайний індекс.
|-
|unique
|Унікальний індекс.
|-
|composite
|Складений індекс по кількох полях.
|-
|fulltext
|Повнотекстовий індекс.
|-
|partial
|Частковий індекс з умовою.
|}

=== 11.2. Властивості індексу ===
{| class="wikitable"
!Поле
!Тип
!Опис
|-
|name
|string
|Назва індексу.
|-
|fields
|list
|Список полів.
|-
|unique
|boolean
|Унікальність.
|-
|type
|enum
|normal, unique, fulltext, partial.
|-
|condition
|string
|Умова для partial index.
|-
|description
|text
|Опис призначення індексу.
|}

== 12. Обмеження ==
Редактор має підтримувати такі обмеження:
{| class="wikitable"
!Обмеження
!Опис
|-
|primary_key
|Первинний ключ.
|-
|foreign_key
|Зовнішній ключ.
|-
|unique
|Унікальність.
|-
|check
|Перевірка умови.
|-
|not_null
|Заборона null.
|-
|default
|Значення за замовчуванням.
|}
Приклад check-constraint:<pre>
amount >= 0
</pre>Приклад YAML:<syntaxhighlight lang="yaml">
constraints:
  - name: chk_order_amount_positive
    type: check
    expression: "amount >= 0"
</syntaxhighlight>

== 13. Enum-и ==

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

Приклад:<pre>
OrderStatus:
  - draft
  - confirmed
  - paid
  - cancelled
</pre>

=== 13.2. Властивості enum ===
{| class="wikitable"
!Поле
!Тип
!Опис
|-
|name
|string
|Назва enum.
|-
|label
|string
|Людинозрозуміла назва.
|-
|description
|text
|Опис.
|-
|values
|list
|Значення.
|}

=== 13.3. Властивості значення enum ===
{| class="wikitable"
!Поле
!Тип
!Опис
|-
|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 ===
<syntaxhighlight lang="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: []
</syntaxhighlight>

=== 14.3. Приклад повної YAML-моделі ===
<syntaxhighlight lang="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"
</syntaxhighlight>

== 15. Двостороння синхронізація Diagram ↔ YAML ==
Редактор має підтримувати два режими роботи:
{| class="wikitable"
!Режим
!Опис
|-
|Diagram-first
|Користувач редагує графічну діаграму, YAML оновлюється автоматично.
|-
|YAML-first
|Користувач редагує YAML, діаграма перебудовується після валідації.
|}

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

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

=== 16.1. Обовʼязкові перевірки ===
{| class="wikitable"
!Перевірка
!Тип
!Опис
|-
|Унікальність 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. Рівні повідомлень ===
{| class="wikitable"
!Рівень
!Опис
!Чи блокує збереження
|-
|Error
|Критична помилка.
|Так.
|-
|Warning
|Потенційна проблема.
|Ні.
|-
|Info
|Інформаційне повідомлення.
|Ні.
|}

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

=== 17.1. Основна ідея ===
Редактор ER-моделей не повинен напряму містити логіку всіх ORM. Він має формувати універсальний YAML, а генерація виконується окремими генераторами.<pre>
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
</pre>

=== 17.2. Підтримувані генератори в MVP ===
{| class="wikitable"
!Генератор
!Пріоритет
!Результат
|-
|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:<syntaxhighlight lang="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
</syntaxhighlight>

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

=== 18.1. Призначення ===
Редактор має вміти порівнювати дві версії YAML-моделі й формувати опис змін.<pre>
schema_v1.yml
    ↓ compare
schema_v2.yml
    ↓
migration plan
</pre>

=== 18.2. Типи змін ===
{| class="wikitable"
!Зміна
!Приклад
!Рівень ризику
|-
|Додана таблиця
|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 ===
Редактор має показувати попередній перегляд:<pre>
+ 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
</pre>Для ризикових змін потрібно показувати попередження.

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

=== 19.1. Вимоги ===
Система має підтримувати:

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

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

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

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

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

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

Приклад:<syntaxhighlight lang="yaml">
entities:
  - name: Customer
    table: customers
    module: crm
</syntaxhighlight>У 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. Права доступу ==
{| class="wikitable"
!Дія
!Архітектор
!Розробник
!Аналітик
!DBA
!Адміністратор
!Перегляд
|-
|Перегляд моделі
|Так
|Так
|Так
|Так
|Так
|Так
|-
|Створення сутностей
|Так
|Так
|Ні
|Так
|Так
|Ні
|-
|Редагування полів
|Так
|Так
|Частково
|Так
|Так
|Ні
|-
|Редагування описів
|Так
|Так
|Так
|Так
|Так
|Ні
|-
|Видалення сутностей
|Так
|Ні
|Ні
|Так
|Так
|Ні
|-
|Затвердження версії
|Так
|Ні
|Ні
|Так
|Так
|Ні
|-
|Генерація ORM
|Так
|Так
|Ні
|Так
|Так
|Ні
|-
|Налаштування генераторів
|Так
|Ні
|Ні
|Ні
|Так
|Ні
|}

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

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

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

=== 25.2. Поля audit log ===
{| class="wikitable"
!Поле
!Опис
|-
|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 ==
Редактор має підтримувати правила іменування.
{| class="wikitable"
!Параметр
!Опис
!Приклад
|-
|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:<syntaxhighlight lang="yaml">
naming:
  entity_case: PascalCase
  table_case: snake_case
  field_case: snake_case
  enum_case: PascalCase
  index_prefix: idx_
  foreign_key_prefix: fk_
</syntaxhighlight>

== 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.

Приклад:<syntaxhighlight lang="yaml">
orm:
  python_sqlalchemy:
    class_name: Customer
    table_args: []
  prisma:
    model_name: Customer
  django:
    app_label: crm
</syntaxhighlight>

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

=== 30.1. Метадані сутності ===
{| class="wikitable"
!Поле
!Опис
|-
|list_view
|Які поля показувати в списку.
|-
|form_view
|Які поля показувати у формі.
|-
|search_fields
|Поля для пошуку.
|-
|display_field
|Головне поле для відображення.
|-
|icon
|Іконка сутності.
|-
|color
|Колір модуля або сутності.
|}
Приклад:<syntaxhighlight lang="yaml">
ui:
  display_field: name
  list_view:
    - name
    - email
    - phone
  search_fields:
    - name
    - email
    - phone
  icon: user
</syntaxhighlight>

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

=== 31.1. Основні endpoint-и ===
{| class="wikitable"
!Метод
!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 ===
{| class="wikitable"
!Поле
!Тип
!Опис
|-
|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 ===
{| class="wikitable"
!Поле
!Тип
!Опис
|-
|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 ===
<pre>
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.
</pre>

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

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

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

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

=== 35.3. Робота з полями ===
<pre>
1. Користувач може додати поле.
2. Користувач може вибрати тип даних.
3. Користувач може задати nullable.
4. Користувач може задати default.
5. Користувач може задати unique та index.
</pre>

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

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

=== 35.6. Валідація ===
<pre>
1. Система знаходить дублікати назв сутностей.
2. Система знаходить дублікати полів.
3. Система знаходить невалідні FK.
4. Система попереджає про FK без індексу.
5. Невалідну модель не можна перевести в released.
</pre>

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

== 36. Приклад сценарію роботи користувача ==
<pre>
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 та міграції.
</pre>

== 37. Ризики ==
{| class="wikitable"
!Ризик
!Наслідок
!Як зменшити
|-
|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. Аналітика ===
<pre>
1. Узгодити YAML-схему.
2. Узгодити набір типів даних.
3. Узгодити правила naming strategy.
4. Узгодити MVP-генератори.
5. Узгодити правила валідації.
</pre>

=== 38.2. Етап 2. Базовий редактор ===
<pre>
1. Реалізувати створення моделі.
2. Реалізувати графічне полотно.
3. Реалізувати створення сутностей.
4. Реалізувати додавання полів.
5. Реалізувати панель властивостей.
</pre>

=== 38.3. Етап 3. Звʼязки та enum-и ===
<pre>
1. Реалізувати FK-звʼязки.
2. Реалізувати відображення кардинальності.
3. Реалізувати enum-и.
4. Реалізувати індекси.
</pre>

=== 38.4. Етап 4. YAML ===
<pre>
1. Реалізувати export YAML.
2. Реалізувати import YAML.
3. Реалізувати YAML preview.
4. Реалізувати YAML editor.
5. Реалізувати синхронізацію diagram ↔ YAML.
</pre>

=== 38.5. Етап 5. Валідація ===
<pre>
1. Перевірка унікальності сутностей.
2. Перевірка полів.
3. Перевірка FK.
4. Перевірка enum.
5. Перевірка індексів.
</pre>

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

=== 38.7. Етап 7. Версіонування та audit ===
<pre>
1. Збереження версій.
2. Порівняння версій.
3. Audit log.
4. Статуси draft/review/approved/released.
</pre>

== 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.