@opengis/fastify-table 1.1.45 → 1.1.47

package/docs/templates/select.md

@@ -0,0 +1,90 @@
+# Select
+
+Зберігаються файли у форматі .sql. Принцип виклику відрізняється від класифікаторів - запит значень йде у базу даних до конкретної таблиці.
+ В папці `server/templates/select`
+
+Складається з 1 або 2-х файлів
+
+1. `select.sql`   - SQL запит
+2. `select.json`  - Налаштування select
+
+```sql
+select conformity from data_barlessness.entrance_group
+```
+
+## Налаштування + Оптимізація
+
+```json
+{
+ "db": "geo_atu",           // інша база
+
+ // для оптимізації
+ "only": "sql",  // sql, redis
+ "searchColumn": "name_nominative,katottg", // колонки пошуку 
+ "minLengthSql": 4,       // 
+ "limit": 20,             // максимальний ліміт пошуку
+ "count": 0,              // загальна кількість число, не буде робити запит кількості
+ "minLength": 4           // мінімальна кількість символів пошуку
+}
+```
+
+::: details Приклад `edrato.atu.katottg`
+
+```sql
+select atu_id,
+      coalesce(edrato.atu_full_name(atu_id),'')||coalesce(' #'||katottg,''),  
+      name_nominative, 
+      katottg
+      from edrato.atu a 
+      where version=(select max(version) from edrato.atu where atu_id=a.atu_id)
+```
+
+---
+
+```json
+{
+    "only": "sql",
+    "searchColumn1": "name_nominative,katottg",
+    "limit": 2,
+    "minLength": 4
+}
+```
+
+:::
+
+::: warning
+
+1. Якщо запит працює більше 100ms - це баг і треба робити оптимізацію.
+2. searchColumn - пошук має бути по нативній колонці щоб індекс спрацював. Порядок searchColumn = `searchColumn`  || колонка `search` || колонка `text`
+3. не намагатись загаянти статистику в пошук
+:::
+
+## Використання API
+
+Викликається через команду [suggest](../api/fastify-table/table/suggest.md) `/api/suggest/{name}` на конкретному порталі.
+
+Повертаються значення **id** та **text**. Приклад:
+
+```json
+{
+  "limit": 50,
+  "count": 2,
+  "mode": "array",
+  "time": 2,
+  "data": [
+    {
+        "id": "1",
+        "text": "Комунальна"
+    },
+    {
+        "id": "2",
+        "text": "Державна"
+    },
+    {
+        "id": "3",
+        "text": "Приватна"
+    }
+ ]
+}
+
+```

package/docs/templates/table.md

@@ -0,0 +1,162 @@
+---
+title: Таблиця
+---
+
+# Таблиця
+
+Використовується для виводу інформації з бази даних. В папці `server/templates/table`
+
+::: info
+Рекомендовано створювати окремі таблиці для виводу інформації до адміністративної, публічної частини та для виводу об'єктів на карту
+:::
+
+## Основні параметри **таблиці**
+
+Таблиця формується у форматі `.json` та має бути розташована у відповідній папці `templates/table/{file}.json`
+
+Нижче наведено приклад файлу таблиці інтерфейсу:
+
+``` json
+{
+    "table": "billing.service",             // Таблиця БД, з якої беруться дані    
+    "query": "service_name is not null",    // Фільтрування даних 
+    "sqlColumns": "*",    // Віддає у об'єкті rows усі колонки із таблиці, використовується коли треба кастомну компоненту вивести як колонку в таблиці, щоб у цю компоненту передати усі колонки таблиці, і їх не прописувати в масиві columns
+
+    "order":  "cdate",                    // колонка для сортування
+    
+    "key": "service_id",                    // ID таблиці БД
+    
+    "limit": 5,                             // Обмеження по кількості об'єктів
+    
+    "form": "web.customize_menu.form",  // Форма
+
+    "columns": [                         // Колонки таблиці та їхні налаштування
+        {
+            "ua": "Назва",                  // Назва для відображення користувачам
+            "meta": "title",                // Тип стандартизованого поля
+            "format": "text",               // Тип даних
+            "name": "service_name",         // Колонка таблиці Бд
+            "data": "service_name_cls",     // Назва класифікатора/селекта
+        },
+        {
+            "ua": "Контактні дані",         // Заголовок колонки
+            "name": "email",                // Колонка таблиці із цього шаблону
+            "format": "custom",             // Форматування даних
+            "componentName": "admin-users-contacts" //Кастомна компонента vue для колонки
+         }
+    ],
+
+    "filterList": [                        // Фільтри таблиці
+        {
+            "ua": "Назва",                  // Підпис фільтру 
+            "name": "service_name",         // Колонка таблиці
+            "type": "Check"                 // Тип фільтру
+        }
+    ],
+
+    "filterInline": [                       // Фільтри таблиці
+        {
+            "ua": "Назва",                  // Підпис фільтру 
+            "name": "service_name",         // Колонка таблиці
+            "type": "Check"                 // Тип фільтру
+        }
+    ],
+    
+    "filterState": [                   // Фільтри статусу
+        {
+            "sql": "status=1",         // sql
+            "name": "archive",         // назва ключ або номер 1
+            "ua": "Підпис",            // підпис
+        }
+    ],
+
+    "filterCustom": [                   // Фільтри користувача
+        {
+            "sql": "status=1",          // Підпис фільтру 
+            "name": "archive",         // ключ  або номер 1       
+            "ua": "Підпис",            // підпис        
+        }
+    ],
+    
+    "meta":{
+        "cls": {
+            "service_id": "billing.service_id",
+            "service_status": "billing.service_status"
+        },                        // присвоєння колонкам класифікаторів для виведення даних (альтернатива columns)
+        "bbox": "geom",           // колонка для пошуку по BBOX
+        "search":"name,address",  // колоноки, за якими відбувається пошук 
+        "title":"service_name",     // колонка статус
+        "key":"service_key",         // колонка ключ / code
+        "status":"service_status",  // колонка статус
+        "type":"service_type",       // колонка тип
+        "address":"address",       // колонки адрес
+        "image":"image"              // аватар, іконка і т.д.
+    } 
+}
+```
+
+- [Детально про фільтри](./filters.md)
+
+## Format
+
+| Формат                          | Опис  |
+| ------------------------  | --------------- |
+| text                       | по замовчюванню     |
+| select                     | з класифікатора     |
+| tags                       | у вигляді label     |
+| badge                      | label з кольором    |
+| age                        | час     |
+| html                       | свій шаблон    |
+| number                     | число     |
+| boolean                    | switcher     |
+
+::: details Основні параметри **колонки**
+
+- `ua` - Назва українською для відображення користувачам
+- `format` - тип даних. Допустимі значення: `text`, `select`, `age`, `date`, `html`, `boolean`, `geom`, badge, tags, `number`
+- `meta` - стандартизоване поле. Допустимі значення: `key`, `title`, `status`, `description`, `type`, category, `image`, `priority`, `teaser`, `start`, `end`, `deadline`, `address`
+- `hidden` - приховати колонку зі стандартного вигляду. Допустимі значення: `true`, `false`
+- `editable` - швидке редагування значення поля. Допустимі значення: `true`, `false`
+- `data` - довідник, з якого беруться значення даних по колонці. Вказується назва селекту чи класифікатора.
+
+:::
+
+:::details Поле meta (стандартизоване поле)
+
+Застосовуються для поля **meta**. Полегшують вивід даних в компоненти за даними від API.
+
+Також може визначатися автоматично - за назвами колонок.
+
+Перелік полів meta:
+
+1. `key`    - Код / номер
+2. `title`   - Назва
+3. `status` - Статус
+4. `description` - Повний опис
+5. `type` - Тип
+6. `category` - Категорія/Розділ
+7. `image` - Зображення
+8. `priority` - Пріоритет
+9. `teaser` - Короткий опис
+10. `start` - Дата початку
+11. `end` - Дата закінчення
+12. `deadline` - Дедлайн (очікувана дата завершення)
+13. `address` - Адреса
+14. `bbox` - BBOX
+15. `cls` - Форматування даних за доп. класифікаторів
+
+:::
+
+:::details Службові колонки
+
+При створенні таблиці потрібно створювати службові колонки:
+
+| Підпис колонки                                 | Назва  | Тип                               |
+| ------------------------------------------- | --------------- | ---------------------------------- |
+| Дата створення                              | cdate           | date_trunc('seconds'::text, now()) |
+| Користувач, що востаннє відредагував об'єкт | editor_id       | text                               |
+| Дата редагування                            | editor_date     | timestamp without time zone        |
+| Файли                                       | files           | json                               |
+| Користувач, який створив                    | uid             | text                               |
+
+:::

package/docs/utils/cron/addCron.md

@@ -0,0 +1,29 @@
+# addCron
+
+## Опис
+
+Додає планувальник
+
+## Параметри
+
+```js
+import updateParcelObjectGeometry from './cron/updateParcelObjectGeometry.js';
+
+export default async function app(fastify, opts) {
+  // cron after core init
+  fastify.addHook('onReady', () => {
+    fastify.addCron(updateParcelObjectGeometry, 60 * 60 * 24, fastify);
+  });
+}
+```
+
+:::tabs
+== params
+
+| Параметр | Тип             | Опис                                              |
+| -------- | --------------- | ------------------------------------------------- |
+| func     | Object          | Функція, яка буде викликатись планувальником      |
+| interval | String / Number | Інтервал часу між запусками                       |
+| fastify  | Object          | Передача параметрів, в т.ч. funcs, log, config    |
+
+:::

package/docs/utils/crud/dataInsert.md

@@ -0,0 +1,52 @@
+# dataInsert
+
+## Опис
+
+Імпорт даних у таблицю
+
+```js
+dataInsert({ table, data });
+```
+
+## Параметри 
+
+::: tabs
+==params
+
+| Параметр | Тип    | Опис    |
+| -------- | ------ | ------- |
+| table    | String | Таблиця |
+| data     | String | Дані    |
+:::
+
+## Приклад 
+
+```js
+dataInsert({
+  table: "data_user.work", data: {
+    type_work: "2",
+    number_services: "25",
+  }
+})
+```
+
+## Відповідь
+
+:::details Приклад відповіді
+
+```js
+{
+  id_work: "3342501119648597051",
+  type_work: 2,
+  date_in: null,
+  date_out: null,
+  number_services: "25",
+  number_order: null,
+  shop: null,
+  geom: null,
+  editor_id: null,
+  uid: null,
+  editor_date: null,
+}
+```
+:::

package/docs/utils/crud/dataUpdate.md

@@ -0,0 +1,53 @@
+# dataUpdate
+
+## Опис
+
+Оновлення даних у таблиці
+
+```js
+dataUpdate({table, id, data});
+```
+
+## Параметри 
+
+::: tabs
+==params
+
+| Параметр | Тип    | Опис                |
+| -------- | ------ | ------------------- |
+| table    | String | Таблиця             |
+| id       | String | Ідентифікатор рядка |
+| data     | Object | Дані для оновлення  |
+:::
+
+## Приклад 
+
+```js
+dataUpdate({
+  table: 'data_user.work', id: '3342439977240757305', data: {
+    type_work: "2",
+    number_services: "25",
+  }
+})
+```
+
+## Відповідь
+
+:::details Приклад відповіді
+
+```js
+{
+  id_work: "3342439977240757305",
+  type_work: 2,
+  date_in: null,
+  date_out: null,
+  number_services: "25",
+  number_order: null,
+  shop: null,
+  geom: null,
+  editor_id: null,
+  uid: null,
+  editor_date: "2024-04-09T12:22:09.000Z",
+}
+```
+:::

package/docs/utils/crud/getOpt.md

@@ -0,0 +1,34 @@
+# getOpt
+
+## Опис
+
+Функція призначена для отримання опцій (налаштувань) за токеном. Повертає json.
+
+```js
+getOpt(token)
+```
+
+## Параметри 
+
+::: tabs
+==params
+
+| Параметр | Тип    | Опис  |
+| -------- | ------ | ----- |
+| token    | String | Токен |
+:::
+
+## Приклад 
+
+```js
+getOpt('UfTTVsVKxBXchKlzRKIg')
+```
+
+## Відповідь
+
+:::details Приклад відповіді
+
+```json
+"data_user.work"
+```
+:::

package/docs/utils/crud/isFileExists.md

@@ -0,0 +1,38 @@
+# isFileExists
+
+## Опис
+
+Перевірка чи існує файл
+
+```js
+isFileExists(filepath);
+```
+
+## Параметри 
+
+::: tabs
+==params
+
+| Параметр | Тип    | Опис    |
+| -------- | ------ | ------- |
+| filepath    | String | Шлях до файлу |
+:::
+
+## Приклад 
+
+```js
+isFileExists('test.txt')
+```
+
+## Відповідь
+
+:::details Приклад відповіді
+
+```js
+true
+```
+---
+```js
+false
+```
+:::

package/docs/utils/crud/setOpt.md

@@ -0,0 +1,38 @@
+# setOpt
+
+## Опис
+
+Функція призначена для збереження опцій (налаштувань) в базі даних Redis.
+Повертає токен за вхідними параметрами
+
+```js
+setOpt(opt)
+```
+
+## Параметри 
+
+Якщо параметри представлені у вигляді об'єкта, вони конвертуються в JSON-рядок перед обчисленням хешу. Якщо параметри представлені у вигляді рядка, вони використовуються напряму для обчислення хешу
+
+::: tabs
+==params
+
+| Параметр | Тип             | Опис                      |
+| -------- | --------------- | ------------------------- |
+| opt   | Object / String | Параметри для збереження. |
+:::
+
+## Приклад 
+
+```js
+setOpt('data_user.work')
+```
+
+## Відповідь
+
+::: details Приклад відповіді
+
+```
+opt:UfTTVsVKxBXchKlzRKIg
+```
+
+:::

package/docs/utils/hook/addHook.md

@@ -0,0 +1,74 @@
+# addHook
+
+## Опис
+
+Функція використовується для додавання хуків (функцій-обробників) до списку хуків.
+
+Можна додавати кастомні хуки у файлі `hooks.js`
+
+Всі необхідні параметри передаються явно
+
+На даний момент підтримуються наступні кастомні хуки:
+
+* preData - попередня обробка, можливість блокування доступу
+* afterData - `модифікація` результату, додавання пов'язаних даних тощо
+* preForm - попередня обробка, можливість блокування доступу
+* afterForm - `модифікація` форми, додавання користувацьких полів тощо
+* preTable - попередня обробка, можливість блокування доступу
+* afterTable - `модифікація` результату, додавання пов'язаних даних тощо
+* preTemplate - попередня обробка, можливість блокування доступу [template](https://apidocs.softpro.ua/admin/api/templates/template.html)
+* afterTemplate - `модифікації` payload [template](https://apidocs.softpro.ua/admin/api/templates/template.html)
+* preInsert - попередня обробка, можливість блокування доступу
+* afterInsert - виконання додаткових дій після внесення даних до БД [insert](../../api/crud/insert.md)
+* preUpdate - попередня обробка, можливість блокування доступу
+* afterUpdate - виконання додаткових дій після внесення змін до БД [update](../../api/crud/update.md)
+* preDelete - попередня обробка, можливість блокування доступу
+* afterDelete - виконання додаткових дій після внесення змін до БД [delete](../../api/crud/deleteCrud.md)
+
+Приклади виклику кастомних хуків можна переглянути [тут](./applyHook.md)
+
+## Параметри
+
+```js
+addHook(name, fn);
+```
+
+| Параметр | Тип      | Опис                                          |
+| -------- | -------- | --------------------------------------------- |
+| name     | string   | Назва хука, до якого буде доданий обробник    |
+| fn       | function | Функція-обробник, яку потрібно додати до хука |
+
+## Приклади
+
+:::details
+
+```js
+import { addHook, config, getTemplate, pgClients } from '@opengis/fastify-table/utils.js';
+
+addHook('afterInsert', async ({ table, body = {}, payload: res = {}, user = {} }) => {
+    const { client: pg } = pgClients || {};
+    const { uid } = config?.auth?.disable ? { uid: '1' } : user;
+    if (!uid || !table || !Object.keys(body)?.length) return null;
+
+    const loadTable = await getTemplate('table', table);
+    if (!pg.pk[loadTable?.table || table]) return null;
+    const pk = pg.pk[loadTable?.table || table];
+    const id = res.rows?.[0]?.[pk];
+
+    const { rows: properties = [] } = await pg.query(`select column_id, name, title, format, data from admin.custom_column 
+    where entity=$1 and uid=$2`, [table, uid]);
+
+    if (!id || !properties?.length) return null;
+
+    const q = properties
+        .filter((el) => Object.keys(body).includes(el.name))
+        .map((el) => `insert into crm.extra_data(property_id,property_key,property_entity,object_id,${el.format?.toLowerCase() === 'date' ? 'value_date' : 'value_text'})
+    select '${el.column_id}', '${el.name}', '${table}', '${id}', ${el.format?.toLowerCase() === 'date' ? `'${body[el.name]}'::timestamp without time zone` : `'${body[el.name]}'::text`}`)
+        .join(';\n');
+    return pg.query(q);
+});
+```
+
+:::
+
+Більше прикладів можна переглянути [тут](../../hook/index.md)

package/docs/utils/hook/applyHook.md

@@ -0,0 +1,64 @@
+# applyHook
+
+## Опис
+
+Функція призначена для виклику хуків (функцій-обробників) з певним ім'ям та передачі їм даних та додаткових аргументів.
+
+Хуки можуть бути використані для повернення відповіді. Для цього достатньо повернути `messagge` та `status`
+
+Приклади додавання кастомних хуків можна переглянути [тут](./addHook.md)
+
+## Параметри
+
+```js
+import { applyHook } from '@opengis/fastify-table/utils.js';
+applyHook(name, data);
+```
+
+| Параметр | Тип    | Опис                                                                               |
+| -------- | ------ | ---------------------------------------------------------------------------------- |
+| name     | string | Назва хука, який потрібно викликати                                                |
+| data     | object | Дані, які будуть передані кожному обробнику хука                                   |
+
+## Приклади
+
+:::tabs
+
+==data
+
+```js
+import { applyHook } from '@opengis/fastify-table/utils.js';
+
+export default async function data(req) {
+    const check = await applyHook('preData', { req });
+    if (check?.message && check?.status) {
+        return { message: check?.message, status: check?.status};
+    }
+    const { pg, funcs, query, params, user } = req;
+    const { rows = [] } = await pg.query(`select * from admin.users where 1=1`);
+    const res = { rows };
+    const hookData = await applyHook('afterData', { table, payload: res, user });
+    return hookData || res;
+}
+```
+
+==table
+
+```js
+import { applyHook, getTemplate } from '@opengis/fastify-table/utils.js';
+
+export default async function table(req) {
+    const timeStart = Date.now();
+    const { pg, funcs, query, params, user } = req;
+    const { table } = await getTemplate('table', params?.table);
+    const hookData = await applyHook('preTable', { table: params.table, id: params.id, user });
+    if (hookData?.message && hookData?.status) {
+        return { message: hookData?.message, status: hookData?.status};
+    }
+    const { rows = [] } = await pg.query(`select * from admin.users where 1=1 limit 1`);
+    const afterHookData = await applyHook('afterTable', { table, payload: rows[0], user });
+    return afterHookData || rows[0];
+}
+```
+
+:::