Changes between Version 2 and Version 3 of DatabaseProgramming

Timestamp:

05/26/26 15:05:23 (26 hours ago)

Author:

231511

Comment:

--

DatabaseProgramming

@@ -632 +632 @@
 8. **Заклучок:**  
 `trg_researcher_access_project_match` обезбедува логичка конзистентност помеѓу истражувачките барања, предметите и конзерваторските проекти. Овој тригер спречува сериозни грешки во пристапот и ја зајакнува безбедноста и точноста на системот.
+= Функции =
+
+
+=== Функција 1: Ажурирање на наслов на археолошки предмет (update_object_title) ===
+
+1. **Намена:**  
+Функцијата `update_object_title` е наменета за контролирано ажурирање на насловот на археолошки предмет во табелата `Objects`. Нејзината основна цел е да овозможи промена на називот на предметот, но само доколку новиот наслов е валиден и не е празен.
+
+2. **Случај на употреба:**  
+Во системот за управување со културно-археолошко наследство, насловот на предметот претставува еден од најважните идентификациски податоци. При каталогизација или дополнителна научна обработка може да се утврди дека претходниот назив на предметот не е доволно прецизен, па е потребно негово ажурирање.
+
+На пример, предмет кој првично бил внесен како „Фрагмент“ подоцна може да биде прецизно идентификуван како „Керамички фрагмент од амфора“.
+
+3. **Причина за употреба на функција:**  
+Избрана е функција наместо директен `UPDATE` затоа што е потребна дополнителна валидација пред да се изврши промената. Функцијата проверува дали новиот наслов е `NULL` или празен текст. Доколку е празен, операцијата се прекинува.
+
+Со ова се спречува внесување невалидни или бескорисни вредности во едно од клучните полиња на табелата `Objects`.
+
+4. **Имплементација:**  
+
+Функцијата прима два параметри:
+
+ * `obj_id` – идентификатор на предметот кој треба да се ажурира
+ * `new_title` – новиот наслов на предметот
+
+Валидацијата се врши со:
+
+{{{
+IF new_title IS NULL OR LENGTH(TRIM(new_title)) = 0 THEN
+    RAISE EXCEPTION 'Насловот не смее да биде празен.';
+END IF;
+}}}
+
+Потоа се извршува ажурирање:
+
+{{{
+UPDATE Objects
+SET title = new_title
+WHERE object_id = obj_id;
+}}}
+
+Доколку не е пронајден предмет со дадениот ID, функцијата враќа грешка:
+
+{{{
+RAISE EXCEPTION 'Објект со ID % не е пронајден.', obj_id;
+}}}
+
+5. **Логика на работа:**  
+Функцијата најпрво ја валидира новата вредност, потоа го ажурира предметот и на крај проверува дали навистина бил пронајден запис за ажурирање. На овој начин се покриваат две можни грешки:
+
+ * празен или невалиден наслов
+ * непостоечки предмет
+
+6. **Бизнис логика:**  
+Оваа функција ја имплементира потребата за точна и контролирана музејска евиденција. Во систем каде предметите се користат во изложби, публикации, конзерваторски проекти и истражувачки пристапи, насловот мора да биде валиден и јасен.
+
+Без оваа функција, би можело да се внесе празен назив, што би довело до проблеми во каталогизацијата, пребарувањето и прикажувањето на предметите во апликацијата.
+
+7. **Пример на употреба:**
+
+{{{
+SELECT update_object_title(
+    100,
+    'Ажуриран археолошки предмет'
+);
+}}}
+
+8. **Заклучок:**  
+`update_object_title` овозможува безбедно и контролирано ажурирање на насловите на археолошките предмети. Таа ја подобрува точноста на податоците и спречува внесување невалидни вредности во основниот каталог на предмети.
+
+
+
+=== Функција 2: Додавање нов археолошки локалитет (add_site) ===
+
+1. **Намена:**  
+Функцијата `add_site` е наменета за внесување нов археолошки локалитет во табелата `Sites`. Нејзината цел е да овозможи стандардизиран внес на локалитет со сите основни географски, административни и описни информации.
+
+2. **Случај на употреба:**  
+Кога археолозите или институциите откриваат или документираат нов локалитет, потребно е тој да биде внесен во системот со податоци за тип на локалитет, регион, година на откривање, заштитен статус, координати, општина и опис.
+
+Ова е основен чекор во системот, бидејќи предметите и фрагментите понатаму се поврзуваат со конкретен локалитет.
+
+3. **Причина за употреба на функција:**  
+Избрана е функција за да се централизира внесувањето на локалитети и да се избегне директно пишување `INSERT` прашалници во апликацијата. Со тоа се добива појасен и поконтролиран начин на додавање нови археолошки локации.
+
+Дополнително, табелата `Sites` веќе содржи ограничувања за координати, странски клучеви и уникатност, а функцијата го користи тој модел за да внесе само структурирани податоци.
+
+4. **Имплементација:**  
+
+Функцијата прима:
+
+ * `p_name` – име на локалитет
+ * `p_site_type_id` – тип на локалитет
+ * `p_region_id` – регион
+ * `p_year` – година на откривање
+ * `p_protection_status_id` – заштитен статус
+ * `p_latitude` – географска ширина
+ * `p_longitude` – географска должина
+ * `p_municipality_id` – општина
+ * `p_description` – опис на локалитетот
+
+Функцијата внесува запис во `Sites`:
+
+{{{
+INSERT INTO Sites(
+    site_name,
+    site_type_id,
+    region_id,
+    discovery_year,
+    protection_status_id,
+    latitude,
+    longitude,
+    municipality_id,
+    description
+)
+VALUES (...);
+}}}
+
+5. **Логика на работа:**  
+Функцијата ги зема параметрите добиени од корисникот или апликацијата и ги внесува во табелата `Sites`. Дополнителните проверки за валидност на регионот, типот, статусот и координатите се обезбедуваат преку constraints дефинирани во самата табела.
+
+6. **Бизнис логика:**  
+Оваа функција ја поддржува основната функционалност за евиденција на археолошки локалитети. Бидејќи секој предмет и фрагмент мора да има археолошки контекст, правилното внесување на локалитети е клучно за целиот систем.
+
+Локалитетот не е само географска точка, туку претставува основа за:
+ * поврзување на предмети
+ * поврзување на фрагменти
+ * анализа по региони
+ * следење на заштитени културни добра
+ * планирање на идни истражувања
+
+7. **Пример на употреба:**
+
+{{{
+SELECT add_site(
+    'Градиште - Нов локалитет',
+    1,
+    1,
+    2024,
+    1,
+    41.995000,
+    21.431000,
+    1,
+    'Нов археолошки локалитет со остатоци од антички период.'
+);
+}}}
+
+8. **Заклучок:**  
+`add_site` овозможува стандардизиран внес на археолошки локалитети и ја поддржува основната структура на системот. Со неа се обезбедува локалитетите да се внесуваат на контролиран начин и да бидат подготвени за поврзување со предмети, фрагменти и институционални анализи.
+
+
+
+=== Функција 3: Проверка дали предмет е достапен за работа (is_object_available) ===
+
+1. **Намена:**  
+Функцијата `is_object_available` е наменета за проверка дали одреден археолошки предмет е достапен за конзерваторска или реставраторска работа.
+
+2. **Случај на употреба:**  
+Во системот, предметите можат да имаат различни статуси. Некои предмети можат да бидат изложени, депонирани или веќе да се наоѓаат на конзервација. Пред да се внесе нов третман, потребно е да се провери дали предметот е во состојба која дозволува дополнителна обработка.
+
+Оваа функција директно се користи од процедурата `add_treatment`.
+
+3. **Причина за употреба на функција:**  
+Избрана е функција затоа што проверката дали предметот е достапен може да се користи на повеќе места во системот. Наместо истата логика да се повторува во повеќе процедури или апликациски функции, таа е централизирана во една database функција.
+
+4. **Имплементација:**  
+
+Функцијата прима:
+
+ * `p_object_id` – идентификатор на предметот
+
+Најпрво го чита тековниот статус:
+
+{{{
+SELECT current_status_id
+INTO v_status
+FROM Objects
+WHERE object_id = p_object_id;
+}}}
+
+Ако предметот не постои:
+
+{{{
+IF NOT FOUND THEN
+    RETURN FALSE;
+END IF;
+}}}
+
+Ако статусот е 3:
+
+{{{
+IF v_status = 3 THEN
+    RETURN FALSE;
+END IF;
+}}}
+
+Во спротивно враќа:
+
+{{{
+RETURN TRUE;
+}}}
+
+5. **Логика на работа:**  
+Функцијата враќа `BOOLEAN` вредност:
+
+ * `TRUE` – предметот е достапен за работа
+ * `FALSE` – предметот не постои или не е достапен
+
+Статусот `3` во системот се користи за предмети кои се „На конзервација“, односно веќе се во процес на обработка и не треба паралелно да се отвора нов третман.
+
+6. **Бизнис логика:**  
+Оваа функција ја имплементира контролата на конзерваторскиот workflow. Во реален музејски контекст, не смее ист предмет неконтролирано да се обработува повеќепати или да се внесе третман врз предмет кој веќе е во активна конзервација.
+
+Со ова се спречува:
+ * дуплирање третмани
+ * паралелна обработка на ист предмет
+ * неконзистентна документација
+ * погрешно планирање на конзерваторски активности
+
+7. **Пример на употреба:**
+
+{{{
+SELECT is_object_available(804822);
+}}}
+
+8. **Заклучок:**  
+`is_object_available` е клучна помошна функција за проверка на достапноста на предметите. Таа обезбедува правилна контрола на третманите и ја спречува апликацијата да дозволи невалидни конзерваторски операции.
+
+
+
+=== Функција 4: Додавање третман и автоматски лог на извршител (add_treatment) ===
+
+1. **Намена:**  
+Функцијата `add_treatment` е наменета за додавање нов конзерваторски третман врз археолошки предмет и автоматско креирање почетен запис во `Treatment_Step_Log`.
+
+2. **Случај на употреба:**  
+Кога конзерватор започнува третман врз предмет, не е доволно само да се внесе запис во `Treatments`. Потребно е и да се документира кој корисник ја започнал интервенцијата и да се креира почетен чекор во дневникот на третманот.
+
+Ова е важно за следење на одговорност, историја на интервенции и професионална документација.
+
+3. **Причина за употреба на функција:**  
+Избрана е функција затоа што операцијата вклучува повеќе чекори:
+
+ * проверка дали предметот постои
+ * внесување нов третман во `Treatments`
+ * земање на новиот `treatment_id`
+ * внесување почетен лог во `Treatment_Step_Log`
+
+Ова не може ефикасно и безбедно да се изведе со еден обичен `INSERT`.
+
+4. **Имплементација:**  
+
+Функцијата прима:
+
+ * `p_object_id`
+ * `p_description`
+ * `p_user_id`
+
+Прво проверува дали предметот постои:
+
+{{{
+IF NOT EXISTS (
+    SELECT 1 FROM Objects WHERE object_id = p_object_id
+) THEN
+    RAISE EXCEPTION 'Објектот не постои';
+END IF;
+}}}
+
+Потоа внесува третман:
+
+{{{
+INSERT INTO Treatments(object_id, treatment_date, description)
+VALUES (p_object_id, CURRENT_DATE, p_description)
+RETURNING treatment_id INTO v_treatment_id;
+}}}
+
+Потоа внесува почетен чекор:
+
+{{{
+INSERT INTO Treatment_Step_Log(
+    treatment_id,
+    step_number,
+    step_description,
+    performed_by_user
+)
+VALUES (
+    v_treatment_id,
+    1,
+    'Initial treatment',
+    p_user_id
+);
+}}}
+
+5. **Логика на работа:**  
+Функцијата работи како автоматизиран workflow за започнување третман. Откако ќе се внесе третманот, веднаш се креира и првиот чекор во дневникот на третманот.
+
+Со ова се обезбедува секој третман да има почетна документација и поврзан корисник.
+
+6. **Бизнис логика:**  
+Во систем за културно наследство, секоја реставраторска интервенција мора да биде документирана. Не е доволно да се знае дека третман постои; мора да се знае и кој го започнал и кога.
+
+Оваа функција обезбедува:
+ * трага на одговорност
+ * почетна документација за третман
+ * поврзување на третманот со корисник
+ * намалување на човечки грешки при внесување
+
+7. **Пример на употреба:**
+
+{{{
+SELECT add_treatment(
+    804822,
+    'Механичко чистење на површински наслој',
+    10
+);
+}}}
+
+8. **Заклучок:**  
+`add_treatment` е важна функција за автоматизирање на конзерваторскиот процес. Таа овозможува третманот и неговиот почетен лог да се креираат заедно, што ја подобрува точноста и комплетноста на документацијата.
+
+
+
+=== Функција 5: Проверка на истражувачки пристап (has_access) ===
+
+1. **Намена:**  
+Функцијата `has_access` е наменета за проверка дали одреден корисник има одобрен пристап до конкретен археолошки предмет.
+
+2. **Случај на употреба:**  
+Во системот, истражувачите не треба автоматски да имаат пристап до сите предмети. Пристапот се контролира преку табелата `Researcher_Access`, каде за секој корисник, предмет и институција се чува статусот на барањето.
+
+Оваа функција се користи кога апликацијата треба да одлучи дали да му дозволи на корисникот да гледа или обработува информации за конкретен предмет.
+
+3. **Причина за употреба на функција:**  
+Избрана е функција затоа што проверката на пристап е логика која може често да се користи во апликацијата. Наместо секојпат да се пишува ист `SELECT EXISTS`, логиката е централизирана во една функција.
+
+4. **Имплементација:**  
+
+Функцијата прима:
+
+ * `p_user_id`
+ * `p_object_id`
+
+Проверува дали постои запис во `Researcher_Access` со:
+
+ * ист корисник
+ * ист предмет
+ * статус `access_status_id = 6`
+
+{{{
+RETURN EXISTS (
+    SELECT 1
+    FROM Researcher_Access
+    WHERE user_id = p_user_id
+      AND object_id = p_object_id
+      AND access_status_id = 6
+);
+}}}
+
+5. **Логика на работа:**  
+Функцијата враќа:
+
+ * `TRUE` ако корисникот има одобрен пристап
+ * `FALSE` ако нема одобрен пристап
+
+Статусот `6` се користи за „Одобрено“.
+
+6. **Бизнис логика:**  
+Оваа функција ја имплементира контролата на пристап до чувствителни археолошки информации. Кај културното наследство, податоците за предметите може да бидат ограничени поради научна вредност, безбедност, институционална сопственост или заштитен статус.
+
+Со оваа функција системот може лесно да провери дали корисникот има право да работи со предметот.
+
+7. **Пример на употреба:**
+
+{{{
+SELECT has_access(
+    10,
+    804822
+);
+}}}
+
+8. **Заклучок:**  
+`has_access` претставува важна безбедносна функција која овозможува контролиран пристап до предметите. Таа ја централизира логиката за дозволи и ја поедноставува имплементацијата во апликацијата.
+
+
+
+=== Функција 6: Броење автори по публикација (count_authors) ===
+
+1. **Намена:**  
+Функцијата `count_authors` е наменета за пресметување на бројот на автори поврзани со одредена научна публикација.
+
+2. **Случај на употреба:**  
+Во системот, публикациите можат да имаат повеќе автори. Релацијата помеѓу публикации и автори е реализирана преку табелата `Publication_Authors`.
+
+При библиографски преглед, извештаи или валидација, може да биде потребно да се знае колку автори има една публикација.
+
+3. **Причина за употреба на функција:**  
+Избрана е функција затоа што ова е едноставна, но често корисна агрегатна операција. Наместо апликацијата постојано да извршува `COUNT(*)` врз junction табелата, логиката се централизира во база.
+
+4. **Имплементација:**  
+
+Функцијата прима:
+
+ * `p_publication_id`
+
+Потоа го брои бројот на записи:
+
+{{{
+SELECT COUNT(*)
+INTO v_count
+FROM Publication_Authors
+WHERE publication_id = p_publication_id;
+}}}
+
+и го враќа резултатот.
+
+5. **Логика на работа:**  
+Функцијата пребарува колку автори се поврзани со дадена публикација преку `publication_id`.
+
+Резултатот е цел број (`INT`).
+
+6. **Бизнис логика:**  
+Оваа функција ја поддржува научната и библиографската евиденција. Во археолошки контекст, публикациите често се резултат на тимска работа, па бројот на автори е важен за:
+
+ * библиографски извештаи
+ * проверка на авторство
+ * академска статистика
+ * прикажување детали за публикации
+
+7. **Пример на употреба:**
+
+{{{
+SELECT count_authors(100);
+}}}
+
+8. **Заклучок:**  
+`count_authors` овозможува едноставна и централизирана пресметка на бројот на автори за публикација. Таа ја поддржува научната евиденција и ја поедноставува работата со библиографски податоци.
+
+
+
+=== Функција 7: Автоматска проценка на важност на предмет (object_importance) ===
+
+1. **Намена:**  
+Функцијата `object_importance` е наменета за автоматска пресметка на индикатор за важност на археолошки предмет.
+
+2. **Случај на употреба:**  
+Во системот, некои предмети имаат поголема институционална или научна важност од други. Предмет кој има повеќе третмани и се појавува во повеќе научни публикации може да се смета за поважен, бидејќи е повеќе истражуван, документиран или конзерваторски значаен.
+
+3. **Причина за употреба на функција:**  
+Избрана е функција затоа што важноста на предметот не е директно поле во табелата `Objects`, туку се пресметува врз основа на поврзани податоци од други табели:
+
+ * `Treatments`
+ * `Object_Publication`
+
+Функцијата овозможува оваа пресметка да се изврши динамички кога е потребно.
+
+4. **Имплементација:**  
+
+Функцијата прима:
+
+ * `p_object_id`
+
+Прво го брои бројот на третмани:
+
+{{{
+SELECT COUNT(*) INTO v_treatments
+FROM Treatments
+WHERE object_id = p_object_id;
+}}}
+
+Потоа го брои бројот на публикации:
+
+{{{
+SELECT COUNT(*) INTO v_publications
+FROM Object_Publication
+WHERE object_id = p_object_id;
+}}}
+
+На крај враќа пресметана вредност:
+
+{{{
+RETURN (v_treatments * 2) + (v_publications * 3);
+}}}
+
+5. **Логика на работа:**  
+Функцијата користи тежинска формула:
+
+ * секој третман носи 2 поени
+ * секоја публикација носи 3 поени
+
+Публикациите имаат поголема тежина бидејќи укажуваат на научна обработка и истражувачка вредност на предметот.
+
+6. **Бизнис логика:**  
+Оваа функција ја имплементира потребата од приоритизација на предмети. Во музејски и археолошки системи, институциите често треба да одлучат кои предмети се поважни за:
+
+ * понатамошна конзервација
+ * дигитализација
+ * изложување
+ * научна обработка
+ * институционални извештаи
+
+Со оваа функција може автоматски да се пресмета релативна важност на предметот според неговата историја на третмани и публикации.
+
+7. **Пример на употреба:**
+
+{{{
+SELECT object_importance(804822);
+}}}
+
+8. **Заклучок:**  
+`object_importance` обезбедува едноставен механизам за проценка на значајноста на археолошките предмети. Таа помага при анализа и приоритизација на културното наследство врз основа на реални податоци од системот.
+
+
+
+=== Функција 8: Приказ на основни детали за предмет (find_object_details) ===
+
+1. **Намена:**  
+Функцијата `find_object_details` е наменета за враќање основни информации за конкретен археолошки предмет.
+
+2. **Случај на употреба:**  
+Кога корисникот пребарува предмет во системот, често е потребно брзо да се прикажат основните детали: насловот на предметот, кој го пронашол и на кој локалитет е пронајден.
+
+Оваа функција овозможува таков краток и структуриран приказ.
+
+3. **Причина за употреба на функција:**  
+Избрана е функција затоа што ги обединува податоците од повеќе табели во еден повик:
+
+ * `Objects`
+ * `Users`
+ * `Sites`
+
+Наместо апликацијата секојпат да пишува `JOIN` прашалник, функцијата обезбедува повторно употреблива логика.
+
+4. **Имплементација:**  
+
+Функцијата прима:
+
+ * `p_object_id`
+
+Враќа табела со следните полиња:
+
+ * `object_id`
+ * `title`
+ * `found_by`
+ * `site_name`
+
+Имплементацијата користи:
+
+{{{
+LEFT JOIN Users u ON o.found_by_user_id = u.user_id
+JOIN Sites s ON o.site_id = s.site_id
+}}}
+
+`LEFT JOIN` со `Users` е важен затоа што предметот може да нема внесен корисник кој го пронашол, но сепак треба да се прикаже.
+
+5. **Логика на работа:**  
+Функцијата пребарува предмет според неговиот `object_id` и враќа комбиниран резултат со информации од поврзаните табели.
+
+6. **Бизнис логика:**  
+Оваа функција ја поддржува основната навигација и пребарување во системот. Во контекст на културно наследство, секој предмет мора да биде разгледуван заедно со неговиот археолошки контекст.
+
+Затоа е важно за предметот веднаш да се знае:
+
+ * кој е предметот
+ * каде е пронајден
+ * кој го евидентирал или пронашол
+
+7. **Пример на употреба:**
+
+{{{
+SELECT *
+FROM find_object_details(804822);
+}}}
+
+8. **Заклучок:**  
+`find_object_details` овозможува брз и јасен приказ на основни информации за археолошки предмет. Таа ја поедноставува апликациската логика и овозможува подобро поврзување на предметите со нивниот локалитет и корисничка евиденција.