From 1c511f9c66c6f2c0494a897ce7189b2251fbbbec Mon Sep 17 00:00:00 2001
From: Alexei Karpenko <karpen_ko@hotmail.com>
Date: Thu, 11 Dec 2025 11:42:31 +0100
Subject: [PATCH] Projektarbeit controller: added comments

---
 .../api/frontend/v1/stv/Projektarbeit.php     | 55 ++++++++++++++++---
 1 file changed, 46 insertions(+), 9 deletions(-)

diff --git a/application/controllers/api/frontend/v1/stv/Projektarbeit.php b/application/controllers/api/frontend/v1/stv/Projektarbeit.php
index 1752cee92..db7d99752 100644
--- a/application/controllers/api/frontend/v1/stv/Projektarbeit.php
+++ b/application/controllers/api/frontend/v1/stv/Projektarbeit.php
@@ -47,6 +47,9 @@ class Projektarbeit extends FHCAPI_Controller
 		$this->load->library('PermissionLib');
 	}
 
+	/**
+	 * Get projekt works for a uid.
+	 */
 	public function getProjektarbeit()
 	{
 		$student_uid = $this->input->get('uid');
@@ -78,6 +81,9 @@ class Projektarbeit extends FHCAPI_Controller
 		$this->terminateWithSuccess($projektarbeiten);
 	}
 
+	/**
+	 * Load a single Projektarbeit by id.
+	 */
 	public function loadProjektarbeit()
 	{
 		$projektarbeit_id = $this->input->get('projektarbeit_id');
@@ -100,6 +106,9 @@ class Projektarbeit extends FHCAPI_Controller
 		$this->terminateWithSuccess(current($data));
 	}
 
+	/**
+	 * Inwert a Projektarbeit.
+	 */
 	public function insertProjektarbeit()
 	{
 		$student_uid = $this->input->post('uid');
@@ -127,6 +136,9 @@ class Projektarbeit extends FHCAPI_Controller
 		$this->terminateWithSuccess($data);
 	}
 
+	/**
+	 * Update a Projektarbeit by ID.
+	 */
 	public function updateProjektarbeit()
 	{
 		$projektarbeit_id = $this->input->post('projektarbeit_id');
@@ -156,6 +168,9 @@ class Projektarbeit extends FHCAPI_Controller
 		$this->terminateWithSuccess($data);
 	}
 
+	/**
+	 * Delete Projektarbeit by ID after validation.
+	 */
 	public function deleteProjektarbeit()
 	{
 		$projektarbeit_id = $this->input->post('projektarbeit_id');
@@ -184,6 +199,9 @@ class Projektarbeit extends FHCAPI_Controller
 		return $this->terminateWithSuccess(current(getData($result)) ? : null);
 	}
 
+	/**
+	 * Get all active projekt work types.
+	 */
 	public function getTypenProjektarbeit()
 	{
 		$result = $this->ProjekttypModel->loadWhere(['aktiv' => true]);
@@ -193,6 +211,9 @@ class Projektarbeit extends FHCAPI_Controller
 		return $this->terminateWithSuccess(hasData($result) ? getData($result) : []);
 	}
 
+	/**
+	 * Gets companies by search string.
+	 */
 	public function getFirmen()
 	{
 		$searchString = $this->input->get('searchString');
@@ -207,6 +228,9 @@ class Projektarbeit extends FHCAPI_Controller
 		return $this->terminateWithSuccess(hasData($result) ? getData($result) : []);
 	}
 
+	/**
+	 * Get Lehrveranstaltungen by params, incling lehreinheiten for a specific Studiensemester..
+	 */
 	public function getLehrveranstaltungen()
 	{
 		$student_uid = $this->input->get('student_uid');
@@ -217,6 +241,7 @@ class Projektarbeit extends FHCAPI_Controller
 		if (!isset($student_uid)) $this->terminateWithError($this->p->t('ui', 'error_missingId', ['id'=> 'Student UID']), self::ERROR_TYPE_GENERAL);
 		if (!isset($studiensemester_kurzbz)) $this->terminateWithError('Studiensemster missing', self::ERROR_TYPE_GENERAL);
 
+		// get Lvs
 		$lvsResult = $this->LehrveranstaltungModel->getLvsForProjektarbeit($student_uid, $studiengang_kz, $additional_lehrveranstaltung_id);
 
 		if (isError($lvsResult)) return $this->terminateWithError($lvsResult, self::ERROR_TYPE_GENERAL);
@@ -225,6 +250,7 @@ class Projektarbeit extends FHCAPI_Controller
 
 		foreach ($lvs as $lv)
 		{
+			// add Lehreinheiten for each Lv for the semester
 			$lehreinheiten = $this->LehreinheitModel->getLesForLv(
 				$lv->lehrveranstaltung_id, $studiensemester_kurzbz
 			);
@@ -249,6 +275,9 @@ class Projektarbeit extends FHCAPI_Controller
 		return $this->terminateWithSuccess($lvs);
 	}
 
+	/**
+	 * Get all noten.
+	 */
 	public function getNoten()
 	{
 		$result = $this->NoteModel->load();
@@ -258,6 +287,9 @@ class Projektarbeit extends FHCAPI_Controller
 		return $this->terminateWithSuccess(hasData($result) ? getData($result) : []);
 	}
 
+	/**
+	 * Get all Studiensemester, sorted.
+	 */
 	public function getStudiensemester()
 	{
 		$this->StudiensemesterModel->addOrder('start', 'DESC');
@@ -269,9 +301,9 @@ class Projektarbeit extends FHCAPI_Controller
 	}
 
 	/**
-	 *
-	 * @param
-	 * @return object success or error
+	 * Validate Projektarbeit data.
+	 * @param formData
+	 * @return bool true if data valid
 	 */
 	private function _validate($formData)
 	{
@@ -302,9 +334,9 @@ class Projektarbeit extends FHCAPI_Controller
 	}
 
 	/**
-	 * 
-	 * @param
-	 * @return object success or error
+	 * Extract Projektarbeit data from passed form data.
+	 * @param formData
+	 * @return array
 	 */
 	private function _getProjektarbeitArr($formData)
 	{
@@ -326,9 +358,9 @@ class Projektarbeit extends FHCAPI_Controller
 	}
 
 	/**
-	 *
-	 * @param
-	 * @return object success or error
+	 * Check if deletion of a Projektarbeit is possible.
+	 * @param $projektarbeit_id
+	 * @return object success if deletion possible, error otherwise.
 	 */
 	private function _validateDelete($projektarbeit_id)
 	{
@@ -349,6 +381,11 @@ class Projektarbeit extends FHCAPI_Controller
 		return success();
 	}
 
+	/**
+	 * Checks permissions for a student.
+	 * @param $student_uid
+	 * @return bool true if authorized
+	 */
 	private function _hasBerechtigungForStudent($student_uid)
 	{
 		if (!$student_uid)