# Galileo Kanban - Developer Documentation / Vývojářská dokumentace

[English Version](#english) | [Česká verze](#čeština)

---

<a id="english"></a>
## 🇬🇧 English: Advanced Developer Documentation

This document serves as an exhaustive breakdown of the Galileo Kanban source code, giving you the blueprints needed to extend the application with new features seamlessly.

### 1. Database Schema Overview
The entire application binds to a relational standard model supporting SQLite processing or MySQL. The core tables typically generated via `database.sql` include:
- `users`: ID, username, email, password_hash, role (admin/user), mobile_token, is_active.
- `boards`: ID, title, description, created_at.
- `board_users`: Cross-reference table deciding who has access. Stores `board_id`, `user_id`, and `role` (owner/editor/viewer).
- `columns`: ID, board_id, title, sort_order.
- `tasks`: ID, column_id, title, description, assigned_to (user_id), due_date, sort_order.
- `task_comments`: ID, task_id, user_id, content, created_at.
- `board_chat` & `messages`: Stores chat messages scoped to a board or 1-to-1 DMs respectively.

### 2. Frontend Communication (`assets/js/api.js`)
All communication from the frontend to the backend is strictly handled through the `KanbanAPI` class instantiated globally as `window.api`. It acts as an abstraction over standard ES6 `fetch()`.

**Here is the exact functional map of `window.api`:**

**Authentication (`api/auth.php`)**
- `api.login(username, password)` -> `POST auth.php?action=login`
- `api.register(username, email, password)` -> `POST auth.php?action=register`
- `api.logout()` -> `POST auth.php?action=logout`
- `api.forgotPassword(usernameOrEmail)` -> `POST auth.php?action=forgot_password`
- `api.resetPassword(token, newPassword)` -> `POST auth.php?action=reset_password`
- `api.checkSession()` -> `GET auth.php?action=me`

**Boards (`api/boards.php`)**
- `api.getBoards()` -> `GET boards.php`
- `api.createBoard(title, desc, defaultCols)` -> `POST boards.php`
- `api.updateBoard(id, title, desc)` -> `PUT boards.php`
- `api.moveBoard(boardId, newPosition)` -> `PUT boards.php {action: 'move'}`
- `api.deleteBoard(id)` -> `DELETE boards.php`

**Columns (`api/columns.php`)**
- `api.getColumns(boardId)` -> `GET columns.php?board_id=...`
- `api.createColumn(boardId, title)` -> `POST columns.php`
- `api.updateColumn(id, title)` -> `PUT columns.php`
- `api.updateColumnPos(positionsArr)` -> `PUT columns.php` (processes array of IDs mapped to positions)
- `api.deleteColumn(id)` -> `DELETE columns.php`

**Tasks (`api/tasks.php`)**
- `api.getTasks(boardId)` -> `GET tasks.php?board_id=...`
- `api.createTask(columnId, title, desc, assignedTo, dueDate)` -> `POST tasks.php`
- `api.updateTask(id, title, desc, assignedTo, dueDate)` -> `PUT tasks.php {action: 'update'}`
- `api.moveTask(taskId, newColId, newPos)` -> `PUT tasks.php {action: 'move'}`
- `api.deleteTask(id)` -> `DELETE tasks.php`

**Collaboration & Chat (`comments.php`, `messages.php`, `teams.php`, `board_chat.php`)**
- `api.getTaskComments(taskId)` and `api.addTaskComment(taskId, content)` -> `comments.php`
- `api.getDMContacts()`, `api.sendDirectMessage(receiverId, content) `, `api.deleteChat(userId)` -> `messages.php`
- `api.getBoardChat(boardId)`, `api.sendBoardChat(boardId, content)` -> `board_chat.php`
- `api.searchUsers(query)` -> `GET users.php?search=query`
- `api.getTeam(boardId)`, `api.addTeamMember(boardId, userId, role)`, `api.updateTeamMemberRole(...)` -> `teams.php`

**Admin Controls (`api/admin.php`)**
- *All admin calls are routed through `admin.php` starting with `api.admin...` methods.*
- `api.adminGetUsers()`, `api.adminToggleActive(userId, isActive)`, `api.adminChangePassword(userId, newPassword)`, `api.adminDeleteUser(userId, newOwnerId)`

### 3. Modifying Frontend Render Logic (`app.js`)
`app.js` listens to user actions and parses the JSON delivered by `api.js`.
1. **DOM Events:** It binds listeners via `document.getElementById('id').addEventListener('click', ...)`.
2. **Re-rendering:** Unlike modern VDOM frameworks (React/Vue), `app.js` explicitly constructs HTML structures using JS template literals `` `<div>${data.title}</div>` `` and pushes them into parent containers using `.innerHTML = ...` or `.insertAdjacentHTML`.
3. **i18n Translation Engine:** You will notice `window.i18n.t("key_name")` surrounding strings in `app.js`. When parsing API responses, `api.js` automatically attempts to translate `data.message` via the globally loaded translation dictionary before returning the Promise rejection/resolution.

### 4. How to add a new Feature (Example: Task Priorities)
1. **Modify Schema:** In your DB, `ALTER TABLE tasks ADD COLUMN priority VARCHAR(50) DEFAULT 'Low';`.
2. **Modify Backend:** In `api/tasks.php` inside the `if ($_SERVER['REQUEST_METHOD'] === 'POST')` block, capture `$data['priority']`. Bind it in the `$stmt->execute([...])` array.
3. **Modify `api.js`:** Update `async createTask(...)` to accept a `priority` parameter and append it to the body JSON.
4. **Modify `app.js`:** 
   - Add a `<select name="priority">` to your `index.php` Task Modal.
   - Edit the function drawing tasks to render a badge `<span class="badge ${task.priority}">` based on the fetched data.

---

<a id="čeština"></a>
## 🇨🇿 Čeština: Vývojářská dokumentace (Pokročilá & Extrémně detailní)

Tento dokument je kompletním rozcestníkem k API vrstvě celého Kanbanu. Slouží vývojářům, kteří hodlají celý systém modifikovat či do něj přidávat rozsáhlé funkce.

### 1. Rozložení Databáze (Struktura tabulek)
Základním kamenem Kanbanu je pevně typované databázové jádro. Z `database.sql` byste měli znát primární relační tabulky:
- `users`: Účetní záznamy uživatelů (obsahuje i `mobile_token` pro Android login logiku).
- `boards` a `board_users`: Definují samotnou nástěnku a takzvanou N:N propojovací vazbu na uživatele s definovanou rolí (`role: owner/editor/viewer`).
- `columns` a `tasks`: Stěžejní tabulky pro strukturu úkolů. Každá obsahuje `sort_order` sloupeček pro zachování přesného pořadí po provedení Drag&Drop události.
- Komunikační moduly ukládají záznamy do tabulek `task_comments`, `messages` (soukromé inbox 1v1 zprávy) a `board_chat` (celoprojektový nástěnkový chat).

### 2. Mapa Frontendové Komunikace (`assets/js/api.js`)
Kanban nevyužívá slepé odesílání formulářů do prázdna, ale sofistikovanou AJAX/Fetch vrstvu. Ta je celá obsažena ve třídě `KanbanAPI` (`window.api`). Než začnete psát jakýkoli modul do `app.js`, zkontrolujte si tuto API kuchařku:

**Přihlašování a účet (`api/auth.php`)**
- `api.login(username, password)`: Odesílá klasický POST request. Pokud máte v `config.php` aktivované LDAP ověření, backend to právě v tuto chvíli detekuje a překlene databázové heslo.
- `api.forgotPassword(email)`: Spouští SMTP proces odeslání linku na obnovu hesla.
- `api.checkSession()`: GET dotaz kontrolující platnost `PHPSESSID`. Vrátí profil nebo 401.

**Nástěnky (`api/boards.php`)**
- `api.getBoards()`: Stáhne pouze nástěnky navázané na přihlášeného uživatele (JOIN operace přes `board_users`).
- `api.createBoard(title, desc)`, `api.updateBoard()`, `api.deleteBoard()`: Standardní CRUD manipulace chráněné autorizací čtoucí z `$_SESSION['user_id']`.

**Sloupce (`api/columns.php`)**
- `api.updateColumnPos(positionsArr)`: Velmi unikátní funkce volaná s obsahem `[{id:1, pos:0}, {id:2, pos:1}]`. Spouští se vždy ihned po dokončení uchopení sloupce myší. Backend projde pole smyčkou a aktualizuje v db číselné zátěže.

**Úkoly (`api/tasks.php`)**
- `api.createTask(...)`: Vytváří novou kartu. Parametry zahrnují mimo textu i `assignedTo` (přidělený uživatel) a `dueDate`.
- `api.moveTask(taskId, newColumnId, newPosition)`: PUT volání se spouští při Drag&Drop kartičky do nového sloupce. API backend přesune FK klíč `column_id` úkolu a zároveň přeskládá `sort_order` pole zbylým kartám v cílovém sloupci, aby "udělaly místo".

**Oprávnění a administrace**
- Sdílení (nastavení cizím lidem roli `viewer/editor`) děláte přes funkce `api.addTeamMember()` (soubor `teams.php`).
- Správa celé instalace (tzv. právo boha) prochází kompletně z funkcí třídy pod namespace `api.admin...()` odkazujících se na jediný bezpečný bod `api/admin.php`. Ten neomylně vyhodí útočníka se statusem 403, pokud nemá v tabulce uživatelů u svého profilu natvrdo vepsanou roli `admin`. 

### 3. Logika vykreslování DOMu a šablon
Uživatelské prostředí se drží klasického přístupu:
1. `index.php` drží prázdnou sadu `<div>` elementů a skrytých vyskakovacích (`modal hidden`) oken.
2. `app.js` udělá fetch pomocí funkcí výše popsaných. 
3. Datovou response ze serveru vezme JavaScript a prožene iterací (`forEach`), kde do proměnných vloží HTML zástupce: `` `<h2>${column.title}</h2>` `` a naservíruje je do prohlížečového stromu DOMu pomocí `.innerHTML`.
4. V případě, kdy serverová `api.js` vrstva hodí Error (stav 400 nebo 500), API zachytí JSON chybovou hlášku a automaticky se ji přes funkci `window.i18n.t(data.message)` pokusí přeložit z lokálního slovníku `cs.json`, aby uživatel viděl lokalizovaný "Špatné heslo" namísto surové databázové chyby. Uvidíte to na řádku 25 souboru `api.js`.
