# Notatki konsultanta — Dokumentacja implementacji

## Data: 2026-04-13

## Zakres zmian

### Projekty zmodyfikowane/rozbudowane:
- **api** — źródło logiki biznesowej i danych
- **consultant** — interfejs mobilny konsultanta
- **admin** — zarządzanie słownikami + przeglądanie notatek

---

## Model danych (DDL)

Plik migracji: `agent-workspace/consultant/migration_consultant_notes.sql`

### Nowe tabele:
| Tabela | Opis |
|--------|------|
| `consultant_note_type` | Słownik kategorii notatek (code, name, is_active, sort_order) |
| `consultant_note` | Główna notatka — problem/zgłoszenie do sklepu |
| `consultant_note_comment` | Komentarze w obrębie notatki |
| `file_attachment` | Zdjęcia (reużyta, related_type=`consultant_note_comment`) |

### Soft delete:
- `consultant_note.deleted_at` — soft delete notatki
- `consultant_note_comment.deleted_at` — soft delete komentarza

---

## API (`api`)

### Nowe endpointy

#### Sklepy dla konsultanta
| Metoda | URL | Opis |
|--------|-----|------|
| GET | `/consultant/shops` | Lista wszystkich sklepów (id, name, city) |

#### Typy notatek
| Metoda | URL | Opis |
|--------|-----|------|
| GET | `/consultant/note-types` | Aktywne typy notatek |
| GET | `/admin/consultant-note-types` | Wszystkie typy (admin) |
| POST | `/admin/consultant-note-types` | Utwórz typ |
| PATCH | `/admin/consultant-note-types/{id}` | Aktualizuj typ |
| DELETE | `/admin/consultant-note-types/{id}` | Deaktywuj typ |

#### Notatki
| Metoda | URL | Opis |
|--------|-----|------|
| GET | `/consultant/shops/{shopId}/notes` | Lista notatek sklepu |
| POST | `/consultant/shops/{shopId}/notes` | Utwórz notatkę |
| GET | `/consultant/notes/{id}` | Notatka z komentarzami + presigned URL |
| DELETE | `/consultant/notes/{id}` | Soft delete notatki |

#### Komentarze
| Metoda | URL | Opis |
|--------|-----|------|
| POST | `/consultant/notes/{noteId}/comments` | Dodaj komentarz (multipart: content, photos[]) |
| DELETE | `/consultant/comments/{id}` | Soft delete komentarza |

#### Admin — przeglądanie
| Metoda | URL | Opis |
|--------|-----|------|
| GET | `/admin/consultant/shops/{shopId}/notes` | Notatki sklepu (z usuniętymi) |
| GET | `/admin/consultant/notes/{id}` | Szczegóły notatki |

### Nowe pliki API:
```
api/app/Controllers/Consultant/
  ConsultantShopController.php
  ConsultantNoteController.php
  AdminConsultantNoteTypeController.php
  AdminConsultantNoteViewController.php
api/app/Services/Consultant/
  ConsultantNoteService.php
  ConsultantNotePhotoService.php
api/app/Repositories/Consultant/
  ConsultantNoteTypeRepository.php
  ConsultantNoteRepository.php
  ConsultantNoteCommentRepository.php
api/v1/Routes/Consultant/
  ConsultantRoutes.php
```

---

## Consultant (`consultant`)

### Przepływ użytkownika:
1. Dashboard → kafelek "Notatki"
2. `/shops` → lista wszystkich sklepów
3. `/shops/{shopId}/notes` → lista notatek dla sklepu + przycisk "Nowa notatka"
4. `/shops/{shopId}/notes/new` → formularz (kategoria + treść)
5. `/notes/{id}` → szczegóły notatki + lista komentarzy + formularz nowego komentarza (z max 4 zdjęciami)

### Nowe pliki consultant:
```
consultant/src/app/Repositories/Shop/ShopRepository.php
consultant/src/app/Repositories/Note/NoteRepository.php
consultant/src/app/Services/Shop/ShopService.php
consultant/src/app/Services/Note/NoteService.php
consultant/src/app/Http/Controllers/Shop/ShopController.php
consultant/src/app/Http/Controllers/Note/NoteController.php
consultant/src/app/Views/shop/list.twig
consultant/src/app/Views/note/list.twig
consultant/src/app/Views/note/create.twig
consultant/src/app/Views/note/detail.twig
consultant/src/core/Bootstrap/Routes/Shop/ShopRoutes.php
consultant/src/core/Bootstrap/Routes/Note/NoteRoutes.php
```

---

## Admin (`admin`)

### Nowe URL:
| URL | Opis |
|-----|------|
| GET `/consultant-note-types` | Lista typów notatek |
| GET/POST `/consultant-note-types/new` | Dodaj typ |
| GET/POST `/consultant-note-types/{id}/edit` | Edytuj typ |
| DELETE `/ajax/consultant-note-types/{id}` | Deaktywuj (AJAX) |
| GET `/consultant-notes/shops/{shopId}` | Notatki sklepu |
| GET `/consultant-notes/{id}` | Szczegóły notatki |

### Nowe pliki admin:
```
admin/repositories/Consultant/ConsultantNoteTypeRepository.php
admin/repositories/Consultant/ConsultantNoteRepository.php
admin/services/Consultant/ConsultantNoteTypeService.php
admin/services/Consultant/ConsultantNoteService.php
admin/controllers/Consultant/NoteTypeController.php
admin/controllers/Consultant/NoteController.php
admin/core/Routes/Consultant/ConsultantRoutes.php
admin/views/consultant/note_type/overview.twig
admin/views/consultant/note_type/form.twig
admin/views/consultant/note/list.twig
admin/views/consultant/note/detail.twig
```

---

## Ograniczenia i zasady

### Zdjęcia:
- Max **4 zdjęcia** per komentarz
- Max rozmiar: **10 MB** per plik
- Formaty: jpg, png, webp, gif
- Przechowywanie: Cloudflare R2 via `R2FileService`
- Metadane w `file_attachment` (`related_type='consultant_note_comment'`)

### Dostęp (MVP):
- Konsultant widzi **wszystkie sklepy** sieci
- Konsultant może tworzyć notatki i komentarze tylko w swoim imieniu
- Admin może **przeglądać** notatki (read-only)

### Routing consultant — zmiana POST na DELETE:
- Nie używamy `DELETE` w formularzach HTML — zamiast tego `POST /notes/{id}/delete`
- FastRoute obsługuje named parameters PHP 8 named args w `call_user_func_array`

---

## Wymagane akcje przy wdrożeniu

1. **Uruchom migrację SQL** z pliku `agent-workspace/consultant/migration_consultant_notes.sql`
2. Upewnij się, że tabela `file_attachment` istnieje (wymagana dla zdjęć)
3. Zmienne środowiskowe R2 muszą być skonfigurowane (`R2_ACCESS_KEY`, `R2_SECRET_KEY`, `R2_BUCKET`, `R2_ENDPOINT`)