= Додавање на достапност (Availability Window)

== Актери
 * Администратор на салон

== Опис
Администраторот додава „прозорец на достапност“ за одреден датум, со почетно и крајно време, или го означува денот како затворен. Овие записи во табелата `availability` подоцна се користат за пресметка на можните термини за закажување.

== Сценарио

1. Администраторот ја отвора страницата за распоред на салонот `/admin/schedule` и го гледа формуларот **„Add Availability Window“** со полиња:
   * Date (датум),
   * Start Time (почетно време),
   * End Time (крајно време),
   * Closed (означува дека денот/прозорецот е затворен за закажување).

2. Администраторот ги пополнува датумот, почетното и крајното време, и по потреба го означува полето „Closed“, потоа клика на копчето **„Add“**.

[[Image(availability-1.jpg, width=800px)]]


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;
}}}

[[Image(availability-2.jpg, width=800px)]]

== Резултат
Новиот прозорец на достапност е успешно додаден во системот. Овие записи подоцна се користат за динамичка пресметка на слободни термини за закажување преку функцијата `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 за **закажување термин од страна на корисник**.