Додавање на достапност (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 за закажување термин од страна на корисник.