API-moduulit — Frontpics

Kaikki API-reitit ovat polun /api/v1 alla. Autentikointi käyttää JWT-tokenia ja roolipohjaisia guard-suojauksia. Pyyntöjen validointi tehdään pääosin packages/shared-paketin Zod-skeemoilla.

Auth — /auth

Metodi	Polku	Auth	Kuvaus
POST	/auth/register	Julkinen	Rekisteröi käyttäjän ja luo roolikohtaiset perustiedot.
POST	/auth/login	Julkinen	Palauttaa access tokenin ja asettaa refresh-cookien.
POST	/auth/refresh	Cookie	Kierrättää refresh tokenin ja palauttaa uuden access tokenin.
POST	/auth/logout	JWT/cookie	Mitätöi refresh tokenin ja tyhjentää cookien.
POST	/auth/verify-email	Julkinen	Vahvistaa sähköpostin.
POST	/auth/forgot-password	Julkinen	Lähettää salasanan palautuslinkin.
POST	/auth/reset-password	Julkinen	Asettaa uuden salasanan tokenilla.

JWT-validointi palauttaa { id, email, role }. Käytä user.id.

Images — /images

Metodi	Polku	Auth	Kuvaus
GET	/images	Julkinen/JWT valinnainen	Aktiivisten kuvien selaus, haku, suodattimet, lajittelu ja ostotila.
GET	/images/:id	Julkinen/JWT valinnainen	Kuvan tiedot, tiedostot, tagit, sijainti ja ostotiedot.
GET	/images/map-pins	Julkinen/JWT valinnainen	Karttapinnit kuville, joilla on koordinaatit.
GET	/images/mine	Kuvaaja	Kuvaajan omat kuvat.
PATCH	/images/:id	Omistaja/admin	Metatietojen muokkaus.
DELETE	/images/:id	Omistaja/admin	Kuvan poisto sääntöjen mukaan.
GET	/images/:id/download/:orderItemId	Ostaja/admin/moderaattori	Allekirjoitettu latausosoite ja toimistobrändi.

Tärkeitä kenttiä ovat Image.basePriceCredits, Image.status, ImageFile.cdnUrl, ImageFile.fileSizeBytes, Location.latitude ja Location.longitude.

Upload — /upload

Metodi	Polku	Auth	Kuvaus
POST	/upload/presigned	Kuvaaja/admin/moderaattori	Luo presigned-upload-osoitteet.
POST	/upload/check-duplicates	Kuvaaja/admin/moderaattori	Tarkistaa SHA-256-duplikaatit.
POST	/upload/confirm	Kuvaaja/admin/moderaattori	Luo kuvat, sijainnit, tagit ja käsittelyjonot.
GET	/upload/status/:jobId	JWT	Käsittelyn tila.

Lataus käyttää EXIF-GPS:ää, osoitehakua, geokoodausta ja manuaalisia koordinaatteja.

Orders — /orders

Metodi	Polku	Auth	Kuvaus
POST	/orders	Ostaja	Ostaa yhden tai useamman kuvan atomisesti.
GET	/orders	Ostaja	Omat tilaukset.
GET	/orders/:id	Omistaja	Tilauksen tiedot ja latauslinkit.

Ostopyyntö voi sisältää buyerReference-kentän laskutusta varten.

Payouts — /payouts

Metodi	Polku	Auth	Kuvaus
POST	/payouts/request	Kuvaaja	Pyytää pankkisiirtotilitystä.
GET	/payouts	Kuvaaja	Omat tilitykset.

Säännöt:

• vähimmäistilitys 50 krediittiä;
• profiilissa täytyy olla bankIban ja bankAccountHolder;
• vain yksi pending tai processing-tilitys kerrallaan;
• note, reference ja billingReference hyväksytään kuvaajan viitteeksi;
• pyydetyt krediitit varataan/vähennetään heti.

Shooting Requests — /shooting-requests

Metodi	Polku	Auth	Kuvaus
POST	/shooting-requests	Ostaja	Luo maksuttoman kuvaustilauksen.
GET	/shooting-requests/open	Kuvaaja/admin	Avoimet kuvauskeikat.
GET	/shooting-requests/my-orders	Ostaja	Ostajan omat pyynnöt.
GET	/shooting-requests/my-claims	Kuvaaja	Kuvaajan ottamat keikat.
GET	/shooting-requests/cost	Ostaja/admin	Nykyinen kustannus, toistaiseksi 0.
POST	/shooting-requests/:id/claim	Kuvaaja	Ottaa avoimen keikan.
POST	/shooting-requests/:id/complete	Valittu kuvaaja	Merkitsee keikan valmiiksi.

Luo-pyyntö hyväksyy osoitekentät sekä valinnaiset latitude ja longitude. Jos koordinaatit puuttuvat, API käyttää samaa rakenteista geokoodausta kuin latausvirta. Keikan valmistuminen hyvittää kuvaajan lompakkoa, mutta ei luo tilitystä automaattisesti.

Admin — /admin

Metodi	Polku	Kuvaus
GET	/admin/stats	Dashboard-tilastot.
GET	/admin/action-counts	Numeromerkit: kuvat, sähköpostit, palautteet, tilitykset.
GET	/admin/users	Käyttäjälista.
GET	/admin/images/pending	Moderointijono.
GET	/admin/images	Kaikki kuvat suodattimilla.
PATCH	/admin/images/:id/approve	Hyväksyy kuvan.
PATCH	/admin/images/:id/reject	Hylkää kuvan.
GET	/admin/payouts	Tilitykset, pankkitiedot ja kuvaajan viite.
PATCH	/admin/payouts/:id/process	Merkitsee maksetuksi ja tallentaa maksun viitteen.
PATCH	/admin/payouts/:id/reject	Hylkää tilityksen ja palauttaa krediitit.

Muut moduulit kattavat palautteet, saapuvat sähköpostit, laskut, brändit, tagit, asetukset ja järjestelmädiagnostiikan.