# Plan Projektu Fuzzel - Klient Android dla Fizzy

## 1. Aktualny Stan Projektu

### Architektura
- **Platforma**: Android Native (Kotlin + Jetpack Compose)
- **Wzorzec**: Clean Architecture (Domain, Data, Presentation)
- **DI**: Hilt
- **Networking**: Retrofit 2.9.0 + Moshi + OkHttp 4.12.0
- **UI**: Material Design 3, Jetpack Compose
- **Min SDK**: 26, Target SDK: 34

### Zaimplementowane Funkcjonalności

| Obszar | Status | Uwagi |
|--------|--------|-------|
| Autentykacja Magic Link | ✅ Gotowe | Pełny flow email → kod → token |
| Personal Access Token | ✅ Gotowe | Bezpośrednie logowanie tokenem |
| Multi-account | ✅ Gotowe | Encrypted storage, przełączanie kont |
| Lista boardów | ✅ Gotowe | CRUD, wyszukiwanie |
| Widok Kanban | ✅ Gotowe | Kolumny, karty, drag&drop |
| Swimlanes (Triage/Not Now/Done) | ✅ Gotowe | Wirtualne kolumny |
| Karty CRUD | ✅ Gotowe | Tworzenie, edycja, usuwanie |
| Akcje na kartach | ✅ Gotowe | Close/reopen, priority, watch, triage, defer |
| Kolumny CRUD | ✅ Gotowe | Dodawanie, edycja, usuwanie |
| Steps | ✅ Gotowe | CRUD + toggle completion |
| Comments | ✅ Gotowe | CRUD |
| Reactions | ⚠️ Częściowe | Add działa, remove ma bug (emoji vs reactionId) |
| Tags | ⚠️ Częściowe | Wyświetlanie OK, add/remove wymaga poprawy |
| Assignees | ⚠️ Częściowe | Add działa, remove niekompletne |
| Notifications | ✅ Gotowe | Lista, mark read/unread, bulk |
| Settings | ✅ Gotowe | Theme mode |

---

## 2. Brakujące Funkcjonalności vs API

### 2.1 Nieimplementowane Endpointy API

| Endpoint | Opis | Priorytet |
|----------|------|-----------|
| `GET /cards?tag_ids[]=...` | Filtrowanie kart po tagach | Wysoki |
| `GET /cards?assignee_ids[]=...` | Filtrowanie kart po assignees | Wysoki |
| `GET /cards?terms[]=...` | Wyszukiwanie kart tekstowe | Wysoki |
| `GET /cards?creation=...` | Filtrowanie po dacie utworzenia | Średni |
| `GET /cards?closure=...` | Filtrowanie po dacie zamknięcia | Średni |
| `DELETE /cards/{n}/image` | Usuwanie obrazka nagłówkowego karty | Niski |
| `GET /:account/users` | Lista użytkowników konta | Wysoki |
| `GET /:account/users/{id}` | Szczegóły użytkownika | Średni |
| `PUT /:account/users/{id}` | Aktualizacja profilu użytkownika | Niski |
| Paginacja (`Link` header) | Obsługa dużych zbiorów danych | Wysoki |
| ETag caching | Optymalizacja requestów (304 Not Modified) | Średni |
| File uploads (multipart) | Załączniki, avatary, obrazki | Wysoki |
| Rich text (HTML + ActionText) | Formatowany opis karty/komentarza | Średni |

### 2.2 Bugi i Niekompletne Implementacje

| Problem | Lokalizacja | Opis |
|---------|-------------|------|
| Reakcje - usuwanie | `CardDetailViewModel` | Używa emoji zamiast reactionId |
| Tagi - dodawanie | `CardDetailViewModel` | Używa tagId zamiast prawidłowego lookup |
| Assignees - usuwanie | `CardRepository` | Endpoint niejasny w dokumentacji, stub |
| Reakcje - GET | `FizzyApiService` | Brak endpointu do pobierania listy reakcji |

---

## 3. Wymagania dla Parytetu z Wersją Webową (1:1)

### 3.1 UI - Widok Kanban

| Element | Status | Do zrobienia |
|---------|--------|--------------|
| Kolumny z kartami | ✅ | - |
| Drag & drop kart | ✅ | - |
| Triage swimlane | ✅ | - |
| Not Now swimlane | ✅ | - |
| Done swimlane | ✅ | - |
| Kolory kolumn (user-defined) | ⚠️ | Dodać obsługę `color` z API |
| Limity kart w kolumnie (WIP) | ❌ | API może to wspierać |
| Reordering kolumn | ❌ | Brak w API (sprawdzić) |
| Bulk card actions | ❌ | Zaznaczanie wielu kart |

### 3.2 UI - Szczegóły Karty

| Element | Status | Do zrobienia |
|---------|--------|--------------|
| Tytuł + opis | ✅ | - |
| Status badge | ✅ | - |
| Priority (golden) | ✅ | - |
| Watch | ✅ | - |
| Tags | ⚠️ | Poprawić add/remove |
| Assignees + avatary | ⚠️ | Poprawić remove, dodać prawdziwe avatary |
| Steps z progress | ✅ | - |
| Comments | ✅ | - |
| Reactions na comments | ⚠️ | Naprawić usuwanie |
| Activity log | ❌ | Placeholder w UI |
| Obrazek nagłówkowy | ❌ | Brak obsługi |
| Załączniki | ❌ | Brak obsługi |
| Rich text rendering | ❌ | Tylko plain text |
| Due date | ❌ | Sprawdzić czy API wspiera |
| Triage date display | ⚠️ | API bierze column_id, nie date |

### 3.3 UI - Board List

| Element | Status | Do zrobienia |
|---------|--------|--------------|
| Lista boardów | ✅ | - |
| Wyszukiwanie | ✅ | - |
| Tworzenie/edycja/usuwanie | ✅ | - |
| Board stats | ⚠️ | Pokazuje tylko podstawowe info |
| Board members | ❌ | Nie wyświetla użytkowników |
| Sortowanie | ❌ | Brak opcji sortowania |

### 3.4 UI - Notifications

| Element | Status | Do zrobienia |
|---------|--------|--------------|
| Lista powiadomień | ✅ | - |
| Mark read/unread | ✅ | - |
| Mark all read | ✅ | - |
| Notification grouping | ❌ | Brak grupowania |
| Deep link do karty | ⚠️ | Podstawowa nawigacja |

---

## 4. Plan Implementacji - Priorytety

### Faza 1: Naprawy Krytyczne (Wysoki Priorytet)

1. **Naprawa reakcji**
   - Dodać `GET /comments/{id}/reactions` do pobierania listy z ID
   - Użyć `reaction.id` zamiast `emoji` przy usuwaniu
   - Pliki: `FizzyApiService.kt`, `CommentDto.kt`, `CardDetailViewModel.kt`

2. **Naprawa tagów**
   - Poprawić flow add/remove tag
   - Użyć prawidłowego `tagging_id` przy usuwaniu
   - Pliki: `CardRepository.kt`, `CardDetailViewModel.kt`

3. **Naprawa assignees**
   - Zbadać API dla remove assignment (toggle?)
   - Implementować prawidłowe usuwanie
   - Pliki: `FizzyApiService.kt`, `CardRepository.kt`

### Faza 2: Filtrowanie i Wyszukiwanie

4. **Zaawansowane filtrowanie kart**
   - Dodać parametry query: `tag_ids[]`, `assignee_ids[]`, `terms[]`
   - UI: FilterChips w Kanban toolbar
   - Pliki: `FizzyApiService.kt`, `CardRepository.kt`, `KanbanViewModel.kt`

5. **Wyszukiwanie globalne**
   - Wyszukiwanie po wszystkich boardach
   - UI: SearchBar w głównym ekranie
   - Nowy feature: `feature/search/`

### Faza 3: Paginacja i Caching

6. **Paginacja**
   - Parser dla `Link` header z `rel="next"`
   - Infinite scroll w listach
   - Pliki: `NetworkModule.kt`, wszystkie repozytoria

7. **ETag Caching**
   - OkHttp interceptor dla `If-None-Match`
   - Cache storage
   - Pliki: `NetworkModule.kt`, `AuthInterceptor.kt`

### Faza 4: Rich Content

8. **File Uploads**
   - Multipart request handling
   - Avatary użytkowników (zamiast inicjałów)
   - Obrazki nagłówkowe kart
   - Pliki: `FizzyApiService.kt`, nowy `FileUploadRepository.kt`

9. **Rich Text**
   - HTML rendering w opisach i komentarzach
   - Compose HTML renderer lub WebView
   - Pliki: `CardDetailScreen.kt`, nowy `RichTextContent.kt`

### Faza 5: Parytet UI

10. **Activity Log**
    - Nowy endpoint (jeśli dostępny w API)
    - Timeline UI w CardDetailScreen
    - Pliki: `CardDetailScreen.kt`, `CardDetailViewModel.kt`

11. **Board Members**
    - Wyświetlanie użytkowników boarda
    - Zarządzanie dostępem
    - Pliki: `BoardDetailScreen.kt` (nowy), `UserRepository.kt`

12. **Offline Support**
    - Room database dla cache
    - Sync queue dla operacji offline
    - Nowy moduł: `data/local/database/`

---

## 5. Szczegóły Techniczne API

### Struktura URL
```
{base_url}/{account_slug}/{resource}.json
```

### Autentykacja
- Header: `Authorization: Bearer {token}`
- Session token lub Personal Access Token

### Parametry Listowania Kart
```
GET /cards.json?
  board_ids[]=uuid1&board_ids[]=uuid2    # filtr boardów
  tag_ids[]=uuid1&tag_ids[]=uuid2        # filtr tagów
  assignee_ids[]=uuid1                    # filtr assignees
  indexed_by=all|closed|not_now           # status kart
  creation=today|this_week|last_week      # data utworzenia
  closure=today|this_week|last_week       # data zamknięcia
  terms[]=word1&terms[]=word2             # wyszukiwanie tekstowe
```

### Paginacja
- Response header: `Link: <url>; rel="next"`
- Parsować URL i fetchować następną stronę

### Caching
- Response header: `ETag: "abc123"`
- Request header: `If-None-Match: "abc123"`
- Response 304 = dane niezmienione

### Wrapping Request/Response
```json
// Create request
{ "card": { "title": "...", "description": "..." } }

// Response
{ "card": { "id": "...", "number": 123, ... } }
```

---

## 6. Pliki Kluczowe do Modyfikacji

| Plik | Zmiany |
|------|--------|
| `FizzyApiService.kt` | Nowe endpointy, parametry query |
| `CardDto.kt` | Pola dla attachments, obrazki |
| `CardRepository.kt` | Filtrowanie, paginacja |
| `KanbanViewModel.kt` | Filtry UI, bulk actions |
| `CardDetailViewModel.kt` | Naprawy reakcji/tagów |
| `NetworkModule.kt` | ETag interceptor, cache |
| `BoardListScreen.kt` | Sortowanie, search |

---

## 7. Weryfikacja Zmian

### Testy Manualne
1. Zaloguj się przez Magic Link
2. Utwórz board, dodaj kolumny i karty
3. Przetestuj drag & drop między kolumnami
4. Otwórz szczegóły karty - dodaj/usuń tagi, assignees
5. Dodaj komentarz, dodaj/usuń reakcję
6. Zamknij i otwórz ponownie kartę
7. Sprawdź powiadomienia

### Testy API
1. Porównaj response API z DTO mapping
2. Zweryfikuj error handling (401, 403, 404, 422)
3. Sprawdź paginację na dużych zbiorach

### Porównanie z Web
1. Otwórz tę samą tablicę w web i w aplikacji
2. Porównaj wyświetlanie kart 1:1
3. Sprawdź wszystkie akcje dostępne w web

---

## 8. Podsumowanie Priorytetów

| Priorytet | Zadanie | Effort |
|-----------|---------|--------|
| 🔴 Krytyczny | Naprawa reakcji, tagów, assignees | Mały |
| 🟠 Wysoki | Filtrowanie kart, paginacja | Średni |
| 🟡 Średni | ETag caching, rich text | Średni |
| 🟢 Niski | File uploads, activity log, offline | Duży |

---

*Plan utworzony: 2026-01-19*
*Wersja: 1.0*