Технічне завдання: Редактор ER-моделей K2 ERP
Редактор має вміти порівнювати дві версії YAML-моделі й формувати характеристика змін.; |}
25.2.; Поля audit log
У майбутніх версіях бажано підтримати командну роботу.; |Перегляд, редагування, генерація коду.;
{| class="wikitable"
4.; користувач системи має змогу згенерувати Python SQLAlchemy-моделі.; |-
|composite
|Складений індекс по кількох полях.; 5.; Створює звʼязок Customer 1 → N Order.;=== 9.2.; Підтримувані типи даних ===
!Обовʼязкова
1.; Приклади дій, які мають підтримувати undo:
Для ризикових змін потрібно показувати попередження.; користувач системи має змогу створити сутність на діаграмі.; |json / jsonb
|- |enum |Перелік значень.; Реалізувати import YAML.; |- |Індекс для FK |Warning
|FK-поля рекомендовано індексувати.;
default_schema: public
</syntaxhighlight>
=== Етап 5.; 38.5.; Валідація ===
{| class="wikitable"
== 11.; Індекси ==
{| class="wikitable"
2.; |Critical.; Реалізувати YAML editor.; |Migration preview і high-risk warnings.; length: 50
type: string
|-
|name
|string
|Так
|Технічна назва сутності.; |-
|POST
|/api/er-models/import
|Імпорт моделі.; type: table
=== 29.2. Fields ===
5.; field_case: snake_case
!Ризик
=== 35.3.; Робота з полями ===
Ключові вимоги:
14.; |Low.; Кожна сутність на діаграмі має відображатися як блок:<pre>
15.; |text
|-
|date
|Дата.;=== 38.2.; Етап 2.; Базовий редактор ===
fields:
2.; |-
|Клік по полю
|Відкриття властивостей поля.; ↓
label: Confirmed
!характеристика
+-----------------------------+
!Обовʼязкове
== 21.; Пошук і навігація ==
scale: 2
schema_v2.yml
↓
7.;
| Верхня панель: Назва моделі | Save | Validate | Generate | Export | Settings |
default: draft
| Дерево моделі | Графічне полотно ER-діаграми | Властивості | | | | | | - Entities | +-------------+ +-------------+ | Entity/Field | | - Customer | | Customer | 1 N | Order | | properties | | - Order | |-------------|-------|-------------| | | | - Enums | | id | | id | | | | - Relations | | name | | customer_id | | | | - Indexes | +-------------+ +-------------+ | |
34. MVP
| Нижня панель: Errors | Warnings | YAML | Generated Code | Migration Preview |
default_schema: public
↓
Редактор має мати можливість автономно додавати типові системні поля:
* створювати сутності;
* переміщувати сутності;
* змінювати розміри блоків;
* створювати звʼязки drag-and-drop;
* групувати сутності по доменах;
* масштабувати діаграму;
* переміщувати полотно;
* автономно розкладати схему;
* фільтрувати видимі сутності;
* шукати сутності та поля;
* підсвічувати залежності;
* відкривати властивості сутності, поля або звʼязку.; |stock_movements, account_entries.; платформа знаходить дублікати назв сутностей.; |-
|created_at
|Дата зміни.; indexes:
{| class="wikitable"
model_name: Customer
entities: !характеристика |- |entity_case |Формат назв сутностей.; |- |status |enum
|draft, review, approved, released, archived.; |High.; Згенерований код можна переглянути перед завантаженням.; Приклад цільової схеми:
ORM / міграції / API / документація
default: 0 type: uuidSQLAlchemy models
↓!характеристика
fields: ↓ expression: "amount >= 0"=== 7.2.; Дії на полотні ===
3.; |idx_.; |- |backref |string |Ні |Назва зворотного звʼязку для ORM.; 5.; |- |description |text |Ні |характеристика призначення сутності.; - email
- name: status label: CRMenums: {| class="wikitable" == 3.; Основні принципи == == 6.; Загальний вигляд інтерфейсу == {| class="wikitable" 3.; Change field orders.amount decimal(10,2) → decimal(12,2) === 14.3.; Приклад повної YAML-моделі ===
C# Entity Framework generator {| class="wikitable"
naming_strategy: snake_case type: check=== 10.1.; Типи звʼязків === Функції:
=== 29.3. Relations === 2.; |- |fields |list |Так |Список полів.; |- |column |string |Ні |Назва колонки в БД, якщо відрізняється від name.; Обробка помилок генерації.;</syntaxhighlight> Приклад:<syntaxhighlight lang="yaml"> 6.; |- |fields |list |Список полів.;=== 35.1.; Створення моделі ===
generate_indexes: true primary_key: true - name: sales5.; |- |not_null |Заборона null.; Повний reverse engineering складних БД.; |- |Drag від поля до іншої сутності |Створення звʼязку.; |- |Валідність enum |Error |Поле enum має посилатися на існуючий enum.; |- |action |Тип дії.;== 28.; конфігурація naming strategy == 5.; |customers, orders.; |- |type |enum |Так |table, view, dictionary, document, register, system.; CI/CD генерує ORM та міграції.; - cancelled
fields:!Тип {| class="wikitable" === 35.7.; Генерація === !; |- |unique |Унікальний індекс.; schema_v1.yml
table: orders use_mapped_column: true== 25. Audit log == 4.; Створює сутність Order.; |- |deprecated |boolean |Чи значення застаріле.; |date |- |datetime
|Дата та час.;
- name: OrderStatus
!Приклад
- name: chk_orders_amount_positive
Розробити в K2 ERP графічний редактор ER-моделей, який надає можливість: 4.; |- |icon |Іконка сутності.; |- |field_case |Формат назв полів.; |users, roles, audit_log.; Зберігає версію 0.1.0.; |smallint |- |decimal |Точне десяткове число.; Реалізувати графічне полотно.; користувач системи має змогу створити нову ER-модель.; |- |register |Регістр або журнал рухів.; Статуси draft/review/approved/released.; description: Example ER model for K2 ERP 4.; 2.; користувач системи має змогу додати поля.; !характеристика
- value: paid
- додати поле;
- редагувати поле;
- видалити поле;
- змінити порядок;
- позначити primary key;
- позначити unique;
- позначити indexed;
- зробити nullable / not nullable;
- вибрати enum;
- вибрати reference.; Приклад модулів:
indexed: true
|- |Diagram-first |користувач системи редагує графічну діаграму, YAML оновлюється автономно.; Порівняння версій.; |}
- name: name
Редактор має підтримувати такі обмеження:
- графічне полотно ER-діаграми;
- панель інструментів;
- дерево моделі;
- панель властивостей;
- YAML-редактор;
- валідатор моделі;
- менеджер звʼязків;
- менеджер enum-ів;
- менеджер індексів;
- менеджер версій;
- генератор ORM;
- перегляд згенерованого коду;
- експорт та імпорт;
- журнал змін.; - name: sales
label: Order
16.; Валідація моделі
schema.yml |- |Унікальність entity.name |Error |Не має змогу бути двох сутностей з однаковою назвою.; |- |label |string |Людинозрозуміла назва.; PHP Laravel generator
Приклад YAML:
== 33.; Нефункціональні вимоги ==
{| class="wikitable"
!Режим
4.; 8.; |-
|enum
|reference
|Ні
|Посилання на enum.;=== Етап 6.; 38.6.; Генерація ===
4.; |-
|PHP Laravel Eloquent
|Низький
|Models, migrations.; ↓
платформа має:
!Тип
!характеристика
== 2.; Основна концепція ==
Сутність відповідає таблиці, колекції або ORM-класу.; |-
|color
|Колір модуля або сутності.;=== 18.2.; Типи змін ===
<pre>
</pre>
|-
|primary_key
|Первинний ключ.; Генерація Python SQLAlchemy.; |-
|description
|text
|характеристика.; |-
|order
|integer
|Порядок відображення.; |-
|required
|boolean
|Ні
|Чи звʼязок обовʼязковий.; |}
↓
!Приклад
values:
search_fields:
== 9.; Поля сутності ==
|-
|uuid
|UUID-ідентифікатор.; +-----------------------------+
== 13.; Enum-и ==
3.; 5.; |numeric(15,2)
|-
|reference
|Посилання на іншу сутність.; !Поле
== 12.; Обмеження ==
5.; Коментарі на діаграмі.; |Category → Parent Category.; |-
|PUT
|/api/er-models/{id}
|Оновити модель.; |-
|YAML-first
|користувач системи редагує YAML, діаграма перебудовується після валідації.;
Laravel Eloquent models
27. Collaboration
- пошук сутності за назвою;
- пошук поля;
- пошук таблиці;
- пошук enum;
- пошук звʼязків;
- фільтр за модулем;
- фільтр за типом сутності;
- фільтр за помилками валідації;
- перехід від поля FK до повʼязаної сутності;
- підсвічування усіх звʼязків вибраної сутності.; |-
|self_reference |Посилання сутності на саму себе.; |}
color: red- мова програмування;
- ORM;
- output path;
- naming strategy;
- чи генерувати міграції;
- чи генерувати relationships;
- чи генерувати validation schemas;
- чи генерувати DTO;
- чи перезаписувати файли;
- чи використовувати partial classes / custom blocks.; |-
| Адміністратор | - | generated | boolean | Ні | Генерація міграцій, перевірка схем.; |- | review | Обовʼязкова валідація перед збереженням.; |- | IDX | - | one_to_many | Один запис має багато дочірніх записів.;
- name: number |
характеристика
4.; |High.; |} enabled: true Редактор має підтримувати імпорт із: constraints: 4.; Індекси.; +--------------------------------------------------------------------------------+ |
Обмеження
↓ 17.1.; Основна ідеяaudit: true - name: phone type: decimal table: customers 3.;=== 8.1.; Поля сутності === |
Тип
- name 26. Undo / Redodjango: 3.; |boolean | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| string | - | form_view | Які поля показувати у формі.; !Тип
1.; |- |
POST | /api/er-models | - | module | string | Ні | компонент K2 ERP, до якого належить сутність.; користувач системи має змогу задати nullable.; Додає модулі crm і sales.;== 37.; Ризики ==
Етап 4.; 38.4.; YAML10.; default_id_type: uuid 18.; Генерація міграцій |
Обовʼязкове
3.; version: 1 7.3.; Відображення сутності+ Add table customers |
Поле
module: crm color: gray schema.yml 2.; |- |
type | enum | Так | - | FK | - | created_at | datetime | Дата створення.; !Тип
- name: Customer 8.; Сутностіtype: string generator-typescript-prisma |
Поле | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| id | uuid | ID версії.; * live collaboration;
|
fulltext | - | Унікальність field.name | Error | У сутності не має змогу бути двох полів з однаковою назвою.; relation_mode: foreignKeys
33.2.; Надійність- name: idx_customers_email |
DBA
Приклад YAML:2.; |-
|model_id
|uuid
|Посилання на модель.; |-
|RO
|Read-only field.; |Створення моделей, сутностей, звʼязків, правил.; 2.; migration plan
{| class="wikitable"
1.; ↓
project:
default_id_type: uuid
=== 25.1.; Що логувати ===
!Тип
6.; Помилки генерації показуються користувачу.; Enum-и.; |-
|POST
|/api/er-models/{id}/validate
|Провалідувати модель.; |-
|on_update
|enum
|Ні
|restrict, cascade, set_null, no_action.; |-
|type
|enum
|Так
|Тип даних.; графічного проєктування структури бази даних забезпечується через '''Редактор ER-моделей K2 ERP''' — компонент; додатково реалізовано опису сутностей.; Реалізувати панель властивостей.;=== 9.1.; Основні властивості поля ===
== 19.; Версіонування моделей ==
module: crm
type: enum
5.; !характеристика
- name: crm
4.; |-
|table_case
|Формат назв таблиць.; |-
|Великі моделі будуть повільно відкриватися
|Поганий UX.; {| class="wikitable"
=== 35.5. YAML ===
label: Draft
4.;=== 22.2.; MVP імпорту ===
* не втрачати зміни при оновленні сторінки, якщо є собою autosave;
* показувати конфлікти при одночасному редагуванні;
* не дозволяти зберегти невалідну модель як released;
* мати резервне збереження draft-версії;
* вести audit log.; Перевірка унікальності сутностей.; |Users ↔ Roles.; Поля:
<pre>
label: Paid
{| class="wikitable"
- name: customer_id
</pre>
== 31.; API редактора ==
name: k2_erp
<pre>
length: 255
=== 22.1.; Джерела імпорту ===
!Приклад БД
13.; Невалідну модель не можна перевести в released.; |numeric(12,2)
|-
|float
|Число з плаваючою точкою.; |-
|Видалення поля призведе до втрати даних
|Ризик production-інциденту.; Потрібно зберігати історію змін.; Реалізувати enum-и.; |-
|C# Entity Framework
|Середній
|Entity classes, DbContext.; |-
|label
|string
|Людинозрозуміла назва.; length: 50
* імпорт YAML;
* імпорт із існуючої PostgreSQL БД;
* імпорт SQL DDL у базовому режимі.; |-
|from_field
|string
|Так
|Поле FK.; |-
|POST
|/api/er-models/{id}/export
|Експорт моделі.; |-
|approved
|Затверджено.; Узгодити набір типів даних.; |-
|Info
|Інформаційне повідомлення.; 3.; |-
|to_entity
|string
|Так
|Цільова сутність.; |-
|current_version_id
|uuid
|Поточна реліз.; table_args: []
foreign_key_prefix: fk_
display_field: name
label: K2 ERP
Python SQLAlchemy generator
generated: true
<pre>
reference:
index_prefix: idx_
== 20.; Робота з модулями K2 ERP ==
project:
color: green
Приклад YAML:<syntaxhighlight lang="yaml">
Приклад:<pre>
1.; |-
|many_to_one
|Багато записів належать одному запису.; |}
naming:
required: true
generators:
prisma:
order: 30
|-
|name
|string
|Назва індексу.; |-
|Версіонування
|Зміни ER-моделі мають зберігатися в історії.; Якщо користувач системи редагує YAML, він спочатку проходить парсинг.; Автоматична оптимізація індексів.; base_class: Base
== 30. UI metadata ==
!Тип
=== 10.3.; Візуальне відображення звʼязків ===
orm:
2.; |-
|to_field
|string
|Так
|Зазвичай primary key.; ↓
Редактор має підтримувати:
</pre>
3.; list_view:
<pre>
!Поле
indexed: true
table_case: snake_case
</pre>
1.;== 14.; YAML-формат моделі ==
Редактор ER-моделей K2 ERP має стати центральним інструментом для проєктування структури даних.; користувач системи має змогу задати default.;=== 35.6.; Валідація ===
Потрібно:
+ Add field customers.email
generator-php-laravel
!характеристика
{| class="wikitable"
1.; |-
|deleted_at
|datetime
|Дата мʼякого видалення.; |Додавання описів, коментарів, бізнес-атрибутів.; |}
- value: cancelled
=== Етап 3.; 38.3.; Звʼязки та enum-и ===
{| class="wikitable"
!характеристика
!Тип
↓ compare
- value: draft
User N ─────── N Role
{| class="wikitable"
!Тип
type: string
* General;
* Fields;
* Relations;
* Indexes;
* Constraints;
* ORM;
* UI metadata;
* Audit;
* YAML Preview.; |-
|Подвійний клік по сутності
|Відкриття повної картки сутності.; платформа знаходить дублікати полів.; |-
|Видалено поле
|Drop email.; |}
<pre>
2.; |-
|Унікальність table
|Error
|Дві сутності не можуть мати одну таблицю, крім спеціальних випадків.; nullable: false
Для MVP достатньо:
!Тип
=== 13.1.; Призначення ===
- name: prisma
=== 29.5. ORM ===
== 4.; Основні користувачі ==
nullable: false
!Поле
label: Order status
modules:
generator-csharp-ef
!Наслідок
↓
label: CRM
Кожна сутність має мати поле `module`.; |-
|Користувачі зламають модель через YAML-редактор
|Неможливо згенерувати код.; |foreign key
|}
Приклад:<syntaxhighlight lang="yaml">
9.; Створює сутність Customer.; Якщо YAML невалідний — показується помилка з рядком і полем.; |-
|schema
|string
|Ні
|Схема БД, як ілюстрація public, sales, crm.; |-
|soft_delete
|boolean
|Ні
|Чи використовувати мʼяке видалення.; |-
|archived
|Архівна реліз.; YAML можна імпортувати назад.; користувач системи має змогу додати поле.; Merge конфліктів.; unique: true
- email
{| class="wikitable"
10.; |-
|GET
|/api/er-models/{id}/versions
|Отримати версії.; Модель зберігається в K2 ERP.; користувач системи має змогу задати unique та index.;<pre>
label: Sales
!характеристика
backref: orders
Редактор має дозволяти задавати метадані для автоматичної генерації UI.; |-
|scale
|integer
|Ні
|Кількість знаків після коми.; expression: "amount >= 0"
Редактор має підтримувати правила іменування.; На основі YAML-опису різні генератори можуть створювати ORM-моделі, міграції, API-схеми, документацію і інші артефакти для різних мов програмування.; |-
|from_entity
|string
|Так
|Початкова сутність.; Помилки YAML показуються користувачу.; Генерація SQL DDL.;<pre>
!Рівень ризику
<syntaxhighlight lang="yaml">
8.; Реалізувати FK-звʼязки.; ↓
|-
|PK
|Primary key.; |}
!Архітектор
generator-python-sqlalchemy
=== 17.2.; Підтримувані генератори в MVP ===
</pre>
↓
- name: chk_order_amount_positive
== 10.; Звʼязки між сутностями ==
YAML-файл має бути:
3.; |-
|partial
|Частковий індекс з умовою.; |-
|DBA
|Перевіряє індекси, ключі, обмеження.; |-
|version
|integer
|реліз запису для optimistic locking.; |Order → Customer.; платформа попереджає про FK без індексу.; length: 255
schema.yml
3.; schema.yml
</pre>
|-
|table
|Звичайна таблиця.; |-
|system
|Системна таблиця.;</pre>
- name: id
* перевіряти права доступу;
* обмежувати генерацію коду тільки авторизованим користувачам;
* не дозволяти виконання довільного коду з YAML;
* перевіряти YAML на небезпечні конструкції;
* логувати імпорт та експорт моделей.; |-
|default
|string / number / expression
|Ні
|Значення за замовчуванням.; |integer
|-
|bigint
|Велике ціле число.; !Позначення
- name: crm
↓
=== 35.4.; Робота зі звʼязками ===
{| class="wikitable"
!Перегляд
Функції:
entity: Customer
to_entity: Customer
Для MVP достатньо реалізувати створення сутностей, полів, звʼязків, enum-ів, YAML import/export, базову валідацію, SQL DDL generator і Python SQLAlchemy generator.; version: 1
nullable: true
Функції:
<pre>
!характеристика
</pre>
<pre>
{| class="wikitable"
</pre>
|-
|Перегляд моделі
|Так
|Так
|Так
|Так
|Так
|Так
|-
|Створення сутностей
|Так
|Так
|Ні
|Так
|Так
|Ні
|-
|Редагування полів
|Так
|Так
|Частково
|Так
|Так
|Ні
|-
|Редагування описів
|Так
|Так
|Так
|Так
|Так
|Ні
|-
|Видалення сутностей
|Так
|Ні
|Ні
|Так
|Так
|Ні
|-
|Затвердження версії
|Так
|Ні
|Ні
|Так
|Так
|Ні
|-
|Генерація ORM
|Так
|Так
|Ні
|Так
|Так
|Ні
|-
|конфігурація генераторів
|Так
|Ні
|Ні
|Ні
|Так
|Ні
|}
=== 38.7.; Етап 7.; Версіонування та audit ===
Редактор має підтримувати:
YAML-модель
* створення сутності;
* видалення сутності;
* перейменування сутності;
* додавання поля;
* видалення поля;
* зміну типу поля;
* зміну nullable;
* зміну primary key;
* створення звʼязку;
* видалення звʼязку;
* зміну індексу;
* зміну enum;
* імпорт;
* експорт;
* генерацію ORM;
* затвердження версії.; |Customer → Orders.; |-
|default
|Значення за замовчуванням.; Додає поля id, name, email, phone.; користувач системи має змогу задати primary key.;</pre>
- customer_id
!Адміністратор
python_sqlalchemy:
!Аналітик
schema.yml
+----------------------+-----------------------------------------+---------------+
!Принцип
order: 40
order: 20
- name
== 38.; Рекомендований план реалізації ==
=== 35.2.; Робота з сутностями ===
!Поле
=== 11.1.; Типи індексів ===
constraints:
=== 16.2.; Рівні повідомлень ===
type: many_to_one
- phone
unique: true
!характеристика
1.; |-
|readonly
|boolean
|Ні
|Чи поле read-only.; |-
|dictionary
|Довідник.; - email
nullable: false
{| class="wikitable"
indexes:
!Метод
nullable: false
5.; |Аналіз структури БД, performance-рекомендації.; output: ./generated/prisma
|-
|YAML стане занадто ORM-специфічним
|Втрата універсальності.; Архітектор створює модель “K2 Sales Model”.; |-
|unique
|Унікальність.; |uuid
|-
|integer
|Ціле число.; provider: postgresql
== 24.; Права доступу ==
|
Статус | Тип
label: Customer 15.1.; Правила синхронізації |
Тип | Поле
TypeScript Prisma generator settings: type: uuid |
характеристика
На діаграмі потрібно показувати кардинальність: entity_case: PascalCase
Приклад check-constraint:<pre>
=== 19.1.; Вимоги ===
Редактор не повинен бути привʼязаний до однієї мови програмування або одного ORM.; |-
|document
|Документ ERP.; |-
|DEF
|Default value.; Генерує SQLAlchemy-моделі.; |-
|Двостороння синхронізація
|Зміни на діаграмі оновлюють YAML, а зміни YAML оновлюють діаграму.; |-
|created_at
|datetime
|Дата створення.; Перевірка індексів.; |-
|GET
|/api/er-models/{id}
|Отримати модель.; Передає YAML у репозиторій.; |-
|object_name
|Назва обʼєкта.; Кожна зміна на діаграмі оновлює внутрішню модель.; |-
|GET
|/api/er-models
|Список моделей.; |-
|checksum
|string
|Хеш YAML.; |-
|display_field
|Головне поле для відображення.; on_update: cascade
!Поле
|-
|draft
|Чернетка.; |-
|POST
|/api/er-models/{id}/generate
|Запустити генерацію.;
Enum застосовується для полів із фіксованим набором значень.; Завантаження результату.; |- |
object_type | Так.; |- | reference | reference | Ні | customer_balance_view.; enabled: true
- paid
|