= Functions, Procedures, Triggers =

== Процедури ==

Процедурите ги опфаќаат операциите за договори, нарачки, достави, рецензии и лојалност. Припаѓаат на шемата `kbnteam`, се напишани на PL/pgSQL и се повикуваат со `CALL`. Проверките и промените на податоците се извршуваат во рамки на тековната трансакција.

=== Договори ===

||= Процедура ||= Намена ||= Директно изменети табели ||
|| [#pr_activate_or_renew_contract pr_activate_or_renew_contract] || Активирање или обновување договор || `contract` ||

=== Нарачки и фактурирање ===

||= Процедура ||= Намена ||= Директно изменети табели ||
|| [#pr_create_company_order pr_create_company_order] || Создавање компаниска нарачка || `company_order` ||
|| [#pr_create_customer_order pr_create_customer_order] || Создавање клиентска нарачка || `customer_order` ||
|| [#pr_add_order_item pr_add_order_item] || Додавање јадење или пијалак || `order_meal`, `order_drink`, `customer_order` ||
|| [#pr_remove_order_item pr_remove_order_item] || Отстранување јадење или пијалак || `order_meal`, `order_drink`, `customer_order` ||
|| [#pr_submit_customer_order pr_submit_customer_order] || Поднесување клиентска нарачка || `customer_order` ||
|| [#pr_change_order_status pr_change_order_status] || Промена на статус на нарачка || `customer_order` ||
|| [#pr_finalize_company_order pr_finalize_company_order] || Финализирање и фактурирање || `customer_order`, `invoice` ||

=== Достави ===

||= Процедура ||= Намена ||= Директно изменети табели ||
|| [#pr_assign_delivery_to_company_order pr_assign_delivery_to_company_order] || Доделување достава || `delivery`, `company_order` ||
|| [#pr_change_delivery_status pr_change_delivery_status] || Промена на статус на достава || `delivery` ||

=== Рецензии ===

||= Процедура ||= Намена ||= Директно изменети табели ||
|| [#pr_create_order_review pr_create_order_review] || Оценување клиентска нарачка || `review`, `order_review` ||
|| [#pr_create_delivery_review pr_create_delivery_review] || Оценување достава || `review`, `delivery_review` ||

=== Лојалност ===

||= Процедура ||= Намена ||= Директно изменети табели ||
|| [#pr_refresh_customer_loyalty pr_refresh_customer_loyalty] || Освежување лојалност || `customer_loyalty` ||

== Параметри и однесување ==

Параметрите без наведена насока се влезни (IN). Параметарот INOUT е истовремено влезен и излезен. Единствено создавањето компаниска нарачка го враќа новиот идентификатор преку INOUT параметар; останатите процедури немаат излезни параметри.

[[Anchor(pr_activate_or_renew_contract)]]

=== pr_activate_or_renew_contract ===

Проверува дали компанијата и ресторанот постојат и дали периодот е валиден. Кога постои активен договор со период што се преклопува или е непосредно соседен, го проширува неговиот период. Ако нема таков договор, создава нов со статус active. Обновувањето се одбива ако проширениот период се преклопува со друг активен договор.

||= Параметар ||= Тип ||= Насока ||= Стандардна вредност ||= Опис ||
|| `p_company_id` || `INTEGER` || IN || — || Компанија на која се однесува операцијата. ||
|| `p_rest_id` || `INTEGER` || IN || — || Ресторан поврзан со договорот. ||
|| `p_start_date` || `DATE` || IN || — || Почетен датум на договорот. ||
|| `p_end_date` || `DATE` || IN || — || Краен датум на договорот. ||

[[Anchor(pr_create_company_order)]]

=== pr_create_company_order ===

Проверува дали компанијата постои и создава компаниска нарачка без доделена достава. Новиот идентификатор се враќа преку параметарот p_comp_order_id.

||= Параметар ||= Тип ||= Насока ||= Стандардна вредност ||= Опис ||
|| `p_company_id` || `INTEGER` || IN || — || Компанија на која се однесува операцијата. ||
|| `p_comp_order_id` || `INTEGER` || INOUT || `NULL` || Се пополнува со идентификаторот на новата компаниска нарачка. ||

[[Anchor(pr_create_customer_order)]]

=== pr_create_customer_order ===

Проверува дали клиентот и компаниската нарачка постојат и припаѓаат на иста компанија. Не дозволува додавање нарачка кон компаниска нарачка за која веќе има фактура. Создава клиентска нарачка со зададениот статус и почетен износ нула.

||= Параметар ||= Тип ||= Насока ||= Стандардна вредност ||= Опис ||
|| `p_customer_user_id` || `INTEGER` || IN || — || Идентификатор на клиентот. ||
|| `p_comp_order_id` || `INTEGER` || IN || — || Идентификатор на компаниската нарачка. ||
|| `p_o_status_id` || `INTEGER` || IN || — || Почетен статус на клиентската нарачка. ||

[[Anchor(pr_add_order_item)]]

=== pr_add_order_item ===

Го прифаќа типот meal или drink и проверува дали производот постои. За ресторанот на производот е потребен активен договор со компанијата на клиентот на датумот на нарачката. Не дозволува повторно додавање на истиот производ, измена на нарачка со статус completed, cancelled или refunded, ниту измена по фактурирање. По додавањето повторно го пресметува вкупниот износ.

||= Параметар ||= Тип ||= Насока ||= Стандардна вредност ||= Опис ||
|| `p_order_id` || `INTEGER` || IN || — || Идентификатор на клиентската нарачка. ||
|| `p_item_type` || `VARCHAR(10)` || IN || — || Тип на производ: meal или drink. ||
|| `p_item_id` || `INTEGER` || IN || — || Идентификатор на јадењето или пијалакот. ||

[[Anchor(pr_remove_order_item)]]

=== pr_remove_order_item ===

Го отстранува зададениот производ од нарачката и повторно го пресметува износот. Одбива отстранување производ што не е дел од нарачката. Не дозволува измени при статус completed, cancelled или refunded, ниту по фактурирање.

||= Параметар ||= Тип ||= Насока ||= Стандардна вредност ||= Опис ||
|| `p_order_id` || `INTEGER` || IN || — || Идентификатор на клиентската нарачка. ||
|| `p_item_type` || `VARCHAR(10)` || IN || — || Тип на производ: meal или drink. ||
|| `p_item_id` || `INTEGER` || IN || — || Идентификатор на јадењето или пијалакот. ||

[[Anchor(pr_submit_customer_order)]]

=== pr_submit_customer_order ===

Проверува дали нарачката содржи барем едно јадење или пијалак и дали за секој вклучен ресторан постои активен договор на датумот на нарачката. Не дозволува поднесување при статус completed, cancelled или refunded, ниту по фактурирање. Го пресметува износот и го поставува статусот на pending.

||= Параметар ||= Тип ||= Насока ||= Стандардна вредност ||= Опис ||
|| `p_order_id` || `INTEGER` || IN || — || Идентификатор на клиентската нарачка. ||

[[Anchor(pr_change_order_status)]]

=== pr_change_order_status ===

Проверува дали нарачката и новиот статус постојат и дали преминот е дозволен. За completed бара барем еден производ и активни договори со вклучените ресторани на датумот на нарачката, а потоа го пресметува износот. По фактурирање дозволува само премин од completed во refunded. При премин во completed, cancelled или refunded ја повикува процедурата за освежување на лојалноста. Повторно задавање на тековниот статус не предизвикува промена.

||= Параметар ||= Тип ||= Насока ||= Стандардна вредност ||= Опис ||
|| `p_order_id` || `INTEGER` || IN || — || Идентификатор на клиентската нарачка. ||
|| `p_new_status_id` || `INTEGER` || IN || — || Идентификатор на новиот статус. ||

[[Anchor(pr_finalize_company_order)]]

=== pr_finalize_company_order ===

Бара компаниската нарачка да постои, да нема фактура и да содржи клиентски нарачки. Сите клиентски нарачки мора да бидат completed и да содржат барем еден производ. Повторно ги пресметува нивните износи и создава една фактура за компаниската нарачка. Не бара доставата да има статус delivered.

||= Параметар ||= Тип ||= Насока ||= Стандардна вредност ||= Опис ||
|| `p_comp_order_id` || `INTEGER` || IN || — || Идентификатор на компаниската нарачка. ||

[[Anchor(pr_assign_delivery_to_company_order)]]

=== pr_assign_delivery_to_company_order ===

За компаниска нарачка без достава создава нова достава и ја поврзува со нарачката. Проверува дали доставувачот постои и дали неговиот ресторан има активен договор со компанијата на датумот на доставата. Датумот, статусот и забелешките се запишуваат во новата достава.

||= Параметар ||= Тип ||= Насока ||= Стандардна вредност ||= Опис ||
|| `p_comp_order_id` || `INTEGER` || IN || — || Идентификатор на компаниската нарачка. ||
|| `p_driver_user_id` || `INTEGER` || IN || — || Идентификатор на доставувачот. ||
|| `p_d_status_id` || `INTEGER` || IN || — || Почетен статус на доставата. ||
|| `p_delivery_date` || `DATE` || IN || `CURRENT_DATE` || Датум на доставата. ||
|| `p_delivery_notes` || `VARCHAR(255)` || IN || `NULL` || Забелешки за доставата. ||

[[Anchor(pr_change_delivery_status)]]

=== pr_change_delivery_status ===

Проверува дали доставата и новиот статус постојат и дали преминот е дозволен. Статусите assigned, picked up, on the way, delivered и delayed бараат назначен доставувач. За delivered дополнително бара доставата да биде поврзана со компаниска нарачка. Повторно задавање на тековниот статус не предизвикува промена.

||= Параметар ||= Тип ||= Насока ||= Стандардна вредност ||= Опис ||
|| `p_delivery_id` || `INTEGER` || IN || — || Идентификатор на доставата. ||
|| `p_new_status_id` || `INTEGER` || IN || — || Идентификатор на новиот статус. ||

[[Anchor(pr_create_order_review)]]

=== pr_create_order_review ===

Бара завршена нарачка со статус completed, поврзана со зададениот клиент, и проверува дали веќе постои рецензија за неа. Запишува општа оценка и коментар, како и посебни оценки за храната и ресторанот. Оценките се во опсег од 1 до 5.

||= Параметар ||= Тип ||= Насока ||= Стандардна вредност ||= Опис ||
|| `p_order_id` || `INTEGER` || IN || — || Идентификатор на клиентската нарачка. ||
|| `p_customer_user_id` || `INTEGER` || IN || — || Идентификатор на клиентот. ||
|| `p_review_rating` || `INTEGER` || IN || — || Општа оценка од 1 до 5. ||
|| `p_review_comment` || `VARCHAR(255)` || IN || — || Коментар за рецензијата. ||
|| `p_food_rating` || `INTEGER` || IN || — || Оценка за храната од 1 до 5. ||
|| `p_restaurant_rating` || `INTEGER` || IN || — || Оценка за ресторанот од 1 до 5. ||

[[Anchor(pr_create_delivery_review)]]

=== pr_create_delivery_review ===

Бара достава со статус delivered и клиент што има нарачка поврзана со таа достава. Не дозволува втора рецензија за истата достава, независно од клиентот. Запишува општа оценка и коментар, како и оценки за доставувачот и брзината, во опсег од 1 до 5.

||= Параметар ||= Тип ||= Насока ||= Стандардна вредност ||= Опис ||
|| `p_delivery_id` || `INTEGER` || IN || — || Идентификатор на доставата. ||
|| `p_customer_user_id` || `INTEGER` || IN || — || Идентификатор на клиентот. ||
|| `p_review_rating` || `INTEGER` || IN || — || Општа оценка од 1 до 5. ||
|| `p_review_comment` || `VARCHAR(255)` || IN || — || Коментар за рецензијата. ||
|| `p_courier_rating` || `INTEGER` || IN || — || Оценка за доставувачот од 1 до 5. ||
|| `p_speed_rating` || `INTEGER` || IN || — || Оценка за брзината од 1 до 5. ||

[[Anchor(pr_refresh_customer_loyalty)]]

=== pr_refresh_customer_loyalty ===

Ги пресметува поените на клиентот и избира ниво чиј опсег ги содржи поените. При повеќе совпаѓања го избира нивото со најголем долен праг; ако нема совпаѓање, го избира нивото со најмал долен праг. Го користи статусот на лојалност со најмал идентификатор. Создава членство или ги ажурира поените, нивото и статусот на постојното членство.

||= Параметар ||= Тип ||= Насока ||= Стандардна вредност ||= Опис ||
|| `p_customer_user_id` || `INTEGER` || IN || — || Идентификатор на клиентот. ||

== Дозволени промени на статус ==

=== Клиентска нарачка ===

||= Тековен статус ||= Дозволени следни статуси ||
|| `pending` || `on-hold`, `backorder`, `completed`, `cancelled` ||
|| `on-hold` || `pending`, `backorder`, `completed`, `cancelled` ||
|| `backorder` || `pending`, `on-hold`, `completed`, `cancelled` ||
|| `completed` || `refunded` ||
|| `cancelled`, `refunded` || Нема премин во друг статус. ||

Овие премини се однесуваат на [#pr_change_order_status pr_change_order_status]. За нарачка во фактурирана компаниска нарачка е дозволен само преминот completed → refunded. Создавањето нарачка го користи зададениот почетен статус, а поднесувањето ја поставува на pending според сопствените проверки.

=== Достава ===

||= Тековен статус ||= Дозволени следни статуси ||
|| `pending` || `assigned`, `cancelled` ||
|| `assigned` || `picked up`, `delayed`, `failed`, `cancelled` ||
|| `picked up` || `on the way`, `delayed`, `failed`, `cancelled` ||
|| `on the way` || `delivered`, `delayed`, `failed` ||
|| `delayed` || `assigned`, `picked up`, `on the way`, `delivered`, `failed`, `cancelled` ||
|| `delivered`, `failed`, `cancelled` || Нема премин во друг статус. ||

Овие премини се однесуваат на [#pr_change_delivery_status pr_change_delivery_status]. При создавање достава се користи зададениот почетен статус. Во двете процедури за промена на статус, називите се споредуваат без разлика на големината на буквите и повторување на тековниот статус завршува без измена.

== Поврзаност меѓу операциите ==

Компаниската нарачка ги обединува клиентските нарачки на една компанија. Во клиентските нарачки се додаваат производи, се проверуваат договорите и се пресметуваат износите. Завршените нарачки можат да се оценуваат, а компаниската нарачка се финализира со создавање фактура. Доставата има сопствен тек на статуси и може да се оценува откако ќе биде доставена.

=== Помошни пресметки и проверки ===

||= Функција ||= Улога ||
|| `fn_has_active_contract` || Проверува дали за компанијата и ресторанот постои договор со статус active што го опфаќа зададениот датум. ||
|| `fn_calculate_order_total` || Ги собира тековните цени на јадењата и пијалоците во нарачката. ||
|| `fn_calculate_customer_loyalty_points` || Го заокружува надолу збирот на износите на нарачките на клиентот, при што нарачките со статус cancelled придонесуваат со нула. Останатите статуси, вклучително refunded, се вклучени во тековната пресметка. ||

Процедурата [#pr_change_order_status pr_change_order_status] ја повикува [#pr_refresh_customer_loyalty pr_refresh_customer_loyalty] при промена во completed, cancelled или refunded. Освежувањето бара постојни нивоа и статуси на лојалност.