Changes between Initial Version and Version 1 of Availability

Timestamp:

03/02/26 13:35:28 (3 weeks ago)

Author:

202033

Comment:

--

Availability

@@ +1 @@
+= Додавање на достапност (Availability Window)
+
+== Актери
+ * Администратор на салон
+
+== Опис
+Администраторот додава „прозорец на достапност“ за одреден датум, со почетно и крајно време, или го означува денот како затворен. Овие записи во табелата `availability` подоцна се користат за пресметка на можните термини за закажување.
+
+== Сценарио
+
+1. Администраторот ја отвора страницата за распоред на салонот `/admin/schedule` и го гледа формуларот **„Add Availability Window“** со полиња:
+   * Date (датум),
+   * Start Time (почетно време),
+   * End Time (крајно време),
+   * Closed (означува дека денот/прозорецот е затворен за закажување).
+
+2. Администраторот ги пополнува датумот, почетното и крајното време, и по потреба го означува полето „Closed“, потоа клика на копчето **„Add“**.
+
+3. Системот проверува дали корисникот е најавен и дали има администраторска улога.  
+   Прво се вчитуваат податоците за најавениот корисник:
+
+{{{
+SELECT user_id, full_name, email, phone
+FROM "User"
+WHERE user_id = $1;
+}}}
+
+   Потоа се вчитуваат неговите улоги:
+
+{{{
+SELECT r.name
+FROM UserRole ur
+JOIN Role r ON ur.role_id = r.role_id
+WHERE ur.user_id = $1;
+}}}
+
+   Дополнително се проверува дали постои запис со улога „admin“ за тој корисник:
+
+{{{
+SELECT 1
+FROM userrole ur
+JOIN role r ON r.role_id = ur.role_id
+WHERE ur.user_id = $1
+  AND LOWER(r.name) = 'admin'
+LIMIT 1;
+}}}
+
+   Ако корисникот не е администратор, системот го одбива барањето и не додава нов прозорец на достапност.
+
+4. Доколку корисникот е администратор, системот ја повикува функцијата `sp_admin_add_availability` која ја обработува логиката за додавање на нов прозорец на достапност:
+
+{{{
+SELECT sp_admin_add_availability($1::date, $2::time, $3::time, $4::boolean) AS availability_id;
+}}}
+
+   Параметрите се:
+   * `$1` – датум (`p_date`),
+   * `$2` – почетно време (`p_start`),
+   * `$3` – крајно време (`p_end`),
+   * `$4` – дали прозорецот е затворен (`p_is_closed`).
+
+5. Во функцијата `sp_admin_add_availability`, системот најпрво проверува дали веќе постои прозорец на достапност со ист датум и ист временски опсег:
+
+{{{
+SELECT 1 INTO v_exists
+FROM availability
+WHERE date = p_date
+  AND start_time = p_start
+  AND end_time = p_end
+LIMIT 1;
+}}}
+
+   Ако веќе постои таков запис, функцијата фрла грешка и не се додава нов запис (се избегнуваат дупликати).
+
+6. За нов валиден прозорец на достапност, функцијата внесува запис во табелата `availability`:
+
+{{{
+INSERT INTO availability (date, start_time, end_time, is_closed)
+VALUES (p_date, p_start, p_end, p_is_closed)
+RETURNING availability_id INTO v_availability_id;
+}}}
+
+   Табелата `availability` е дефинирана со следното ограничување за валидност на временскиот опсег:
+
+{{{
+CREATE TABLE availability (
+  availability_id integer GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
+  date date NOT NULL,
+  start_time time NOT NULL,
+  end_time time NOT NULL,
+  is_closed boolean NOT NULL DEFAULT false,
+  CONSTRAINT availability_end_after_start CHECK (end_time > start_time)
+);
+}}}
+
+   Дополнително, постои и уникатно ограничување за прозорецот:
+
+{{{
+CREATE UNIQUE INDEX IF NOT EXISTS idx_availability_unique_window
+  ON availability (date, start_time, end_time);
+}}}
+
+   Со ова се осигурува дека:
+   * `end_time` секогаш е поголемо од `start_time`, и
+   * не може да постојат два идентични прозорци (ист датум, ист почеток и ист крај).
+
+7. По успешното додавање на прозорецот на достапност, системот го пренасочува администраторот назад на `/admin/schedule` и преку погледот `v_admin_availability_by_date` ги прикажува сите прозорци на достапност по датуми:
+
+{{{
+SELECT
+  date,
+  availability_id,
+  start_time,
+  end_time,
+  is_closed
+FROM v_admin_availability_by_date
+ORDER BY date ASC, start_time ASC;
+}}}
+== Резултат
+Новиот прозорец на достапност е успешно додаден во системот. Овие записи подоцна се користат за динамичка пресметка на слободни термини за закажување преку функцијата `fn_available_slots`.
+
+
+== Врска со пресметка на слободни термини (available slots)
+
+Прозорците на достапност внесени во табелата `availability` не креираат термински слотови директно при додавање.  
+Наместо тоа, тие се користат подоцна, кога корисникот ќе избере датум за закажување, преку посебна функција во базата `fn_available_slots`.
+
+За избраниот датум и листа на услуги, системот ги пресметува слободните термини со повик на:
+
+{{{
+SELECT
+  to_char(start_time, 'YYYY-MM-DD"T"HH24:MI:SS') AS start_time,
+  to_char(end_time, 'YYYY-MM-DD"T"HH24:MI:SS') AS end_time
+FROM fn_available_slots($1::date, $2::int[]);
+}}}
+
+Функцијата `fn_available_slots` ги користи прозорците од `availability` (каде `is_closed = false`) и, со помош на `generate_series`, ги дели на интервали (пр. на 15 минути), при тоа исклучувајќи ги термините кои веќе се зафатени со постоечки закажани appointments.
+
+Оваа функционалност ќе биде детално опишана во посебен use-case за **закажување термин од страна на корисник**.