first commit
This commit is contained in:
Beyhan Oğur
272
docs/IMPLEMENTATION.md
Normal file
272
docs/IMPLEMENTATION.md
Normal file
@@ -0,0 +1,272 @@
|
||||
# Implementation Notes
|
||||
|
||||
Bu belge projede su ana kadar yapilan implementasyonlari teknik olarak ozetler.
|
||||
|
||||
## 1. Genel Mimari
|
||||
|
||||
Proje Axum tabanli bir API olarak calisir.
|
||||
|
||||
Baslica moduller:
|
||||
|
||||
- `src/main.rs` -> uygulama bootstrap
|
||||
- `src/app/` -> router birlestirme ve OpenAPI
|
||||
- `src/auth/` -> register/login/refresh/logout/me akisi
|
||||
- `src/images/` -> image upload, process, listeleme ve variant stream akisi
|
||||
- `src/entities/` -> SeaORM entity tanimlari
|
||||
- `src/migration/` -> migration dosyalari
|
||||
- `src/state/` -> `AppState`, JWT ayarlari, DB init
|
||||
- `src/error/` -> unified `ApiError`
|
||||
- `src/tests/` -> endpoint testleri
|
||||
|
||||
Katman mantigi:
|
||||
|
||||
- `controller` -> HTTP request parsing / response
|
||||
- `service` -> business logic
|
||||
- `repository` -> DB / fs / token source erisimi
|
||||
- `processor` -> image decode/resize/encode
|
||||
- `dto` -> request/response tasiyicilari
|
||||
- `model` -> domain enum ve tipler
|
||||
|
||||
## 2. Auth Sistemi
|
||||
|
||||
Account sistemi JWT access + refresh token mantigi ile calisir.
|
||||
|
||||
Mevcut endpointler:
|
||||
|
||||
- `POST /api/v1/auth/register`
|
||||
- `POST /api/v1/auth/login`
|
||||
- `POST /api/v1/auth/refresh`
|
||||
- `POST /api/v1/auth/logout`
|
||||
- `GET /api/v1/auth/me`
|
||||
|
||||
Davranis:
|
||||
|
||||
- sifreler `argon2` ile hashlenir
|
||||
- access / refresh token `jsonwebtoken` ile uretilir
|
||||
- refresh token session'lari:
|
||||
- DB varsa `refresh_tokens` tablosu
|
||||
- DB yoksa in-memory fallback
|
||||
|
||||
## 3. Images Modulu
|
||||
|
||||
Images modulu su endpointleri sunar:
|
||||
|
||||
- `GET /api/v1/images/process`
|
||||
- `POST /api/v1/images/process`
|
||||
- `GET /api/v1/images`
|
||||
- `GET /api/v1/images/{id}/variant`
|
||||
|
||||
### 3.1 GET /api/v1/images/process
|
||||
|
||||
Bu endpoint query parametrelerini dogrular ve donusum metadata'si uretir.
|
||||
|
||||
Desteklenen parametreler:
|
||||
|
||||
- `width` / `w`
|
||||
- `height` / `h`
|
||||
- `format`
|
||||
- `quality`
|
||||
- `crop`
|
||||
|
||||
Default degerler:
|
||||
|
||||
- `format = webp`
|
||||
- `crop = cover`
|
||||
- `quality = 80`
|
||||
|
||||
### 3.2 POST /api/v1/images/process
|
||||
|
||||
Bu endpoint multipart form-data ile dosya kabul eder.
|
||||
|
||||
Beklenen alanlar:
|
||||
|
||||
- `file`
|
||||
- `width`
|
||||
- `height`
|
||||
- `format`
|
||||
- `quality`
|
||||
- `crop`
|
||||
|
||||
Akis:
|
||||
|
||||
1. bearer token okunur
|
||||
2. token validate edilir
|
||||
3. multipart file byte olarak okunur
|
||||
4. orijinal dosya `uploads/originals` altina kaydedilir
|
||||
5. image decode edilir
|
||||
6. gerekirse resize uygulanir
|
||||
7. istenen output format'a encode edilir
|
||||
8. islenmis varyant `uploads/variants` altina kaydedilir
|
||||
9. DB varsa metadata `images` ve `image_variants` tablolarina yazilir
|
||||
10. response olarak metadata donulur
|
||||
|
||||
### 3.3 GET /api/v1/images
|
||||
|
||||
Bu endpoint DB uzerinden image metadata listesi doner.
|
||||
|
||||
Not:
|
||||
|
||||
- DB yoksa `503 Service Unavailable` doner
|
||||
- response, her image icin latest variant bilgisini de icerebilir
|
||||
|
||||
### 3.4 GET /api/v1/images/{id}/variant
|
||||
|
||||
Bu endpoint ilgili image kaydinin en son varyant dosyasini binary olarak stream eder.
|
||||
|
||||
Not:
|
||||
|
||||
- DB gerektirir
|
||||
- son varyant secimi `created_at desc` sirasina gore yapilir
|
||||
|
||||
## 4. Desteklenen Formatlar
|
||||
|
||||
Model tarafinda desteklenen formatlar:
|
||||
|
||||
- `avif`
|
||||
- `png`
|
||||
- `jpg`
|
||||
- `jpeg`
|
||||
- `webp`
|
||||
|
||||
Processor tarafinda gercek encode akisi vardir.
|
||||
|
||||
Not:
|
||||
|
||||
- input decode basarisizsa su an fallback davranisi source bytes donusumu yerine ham byte ile devam etmeye calisabilir veya hata doner; bu kisim ileride daha da sertlestirilebilir
|
||||
- `crop` enum'u dogrulaniyor fakat su an gercek crop stratejileri tam uygulanmiyor; mevcut implementasyon daha cok resize + format convert seviyesinde
|
||||
|
||||
## 5. Token Dogrulama
|
||||
|
||||
Image endpointleri icin bearer token zorunludur.
|
||||
|
||||
Su an iki yol desteklenir:
|
||||
|
||||
1. `IMAGE_ACCESS_TOKEN` env degeri ile gelen dev token
|
||||
2. mevcut auth sisteminden uretilmis JWT access token
|
||||
|
||||
Bu davranis gecis sureci icindir.
|
||||
|
||||
Hedef mimari:
|
||||
|
||||
- Redis tabanli image token validation
|
||||
- namespaced key yapisi, or. `image:token:{token}`
|
||||
|
||||
## 6. Storage Davranisi
|
||||
|
||||
Varsayilan env ayarlari:
|
||||
|
||||
- `IMAGE_UPLOAD_DIR=uploads/originals`
|
||||
- `IMAGE_VARIANT_DIR=uploads/variants`
|
||||
|
||||
Yuklenen orijinal dosya:
|
||||
|
||||
- `uploads/originals/<uuid>.<ext>`
|
||||
|
||||
Uretilen varyant dosya:
|
||||
|
||||
- `uploads/variants/<uuid>.<target-ext>`
|
||||
|
||||
Onemli not:
|
||||
|
||||
- su an response icinde `stored_path` donuluyor
|
||||
- bu, mevcut implementasyonda debugging ve kontrol kolayligi icin acik
|
||||
- hedef uretim mimarisinde raw path expose etmek yerine `image_id` veya signed access token tercih edilmelidir
|
||||
|
||||
## 7. DB ve Migration Yapisi
|
||||
|
||||
### 7.1 Auth Tablolari
|
||||
|
||||
Migration:
|
||||
|
||||
- `m20260409_000001_create_auth_tables`
|
||||
|
||||
Tablolar:
|
||||
|
||||
- `users`
|
||||
- `refresh_tokens`
|
||||
|
||||
### 7.2 Images Tablolari
|
||||
|
||||
Migration:
|
||||
|
||||
- `m20260409_000002_create_image_tables`
|
||||
|
||||
Tablolar:
|
||||
|
||||
- `images`
|
||||
- `image_variants`
|
||||
|
||||
Iliskiler:
|
||||
|
||||
- `users (1) -> (N) images`
|
||||
- `images (1) -> (N) image_variants`
|
||||
|
||||
### 7.3 Migration Calisma Akisi
|
||||
|
||||
`src/state/mod.rs` icinde DB baglantisi varsa uygulama acilisinda `Migrator::up` cagrilir.
|
||||
|
||||
Yani:
|
||||
|
||||
- DB varsa migration'lar otomatik kontrol edilir
|
||||
- DB baglantisi yoksa app fallback modda acilabilir
|
||||
|
||||
## 8. Swagger / OpenAPI
|
||||
|
||||
Swagger UI:
|
||||
|
||||
- `GET /swagger-ui`
|
||||
|
||||
OpenAPI JSON:
|
||||
|
||||
- `GET /api-docs/openapi.json`
|
||||
|
||||
Swagger'a ekli alanlar:
|
||||
|
||||
- auth endpointleri
|
||||
- image process GET
|
||||
- image upload POST (multipart form-data)
|
||||
- image list
|
||||
- image variant stream
|
||||
|
||||
## 9. Env Degiskenleri
|
||||
|
||||
Temel env degiskenleri:
|
||||
|
||||
- `DATABASE_URL`
|
||||
- `JWT_SECRET`
|
||||
- `JWT_ISSUER`
|
||||
- `ACCESS_TOKEN_TTL_SECS`
|
||||
- `REFRESH_TOKEN_TTL_SECS`
|
||||
- `ENABLE_SWAGGER_UI`
|
||||
- `IMAGE_ACCESS_TOKEN`
|
||||
- `IMAGE_UPLOAD_DIR`
|
||||
- `IMAGE_VARIANT_DIR`
|
||||
- `DB_REQUIRED`
|
||||
|
||||
## 10. Mevcut Sinirlar / Sonraki Adimlar
|
||||
|
||||
Su an sistem calisir durumda ama halen gelistirilebilir alanlar var:
|
||||
|
||||
1. Redis tabanli gercek image token repository
|
||||
2. gercek crop stratejileri (`cover`, `contain`, `center` vs.)
|
||||
3. image cache / variant cache
|
||||
4. raw path expose etmek yerine guvenli public serving
|
||||
5. `GET /api/v1/images/{id}/variant` icin format/width/height/crop bazli secim
|
||||
6. islenmis varyantlar icin duplicate-onleme / cache-aside stratejisi
|
||||
7. local fs yerine object storage destegi
|
||||
|
||||
## 11. Windows Build
|
||||
|
||||
Repo icinde `win.sh` scripti bulunur.
|
||||
|
||||
Amaci:
|
||||
|
||||
- `x86_64-pc-windows-gnu` target eklemek
|
||||
- linker config hazirlamak
|
||||
- Windows release build almak
|
||||
|
||||
Script:
|
||||
|
||||
- `.cargo/config.toml` olusturabilir
|
||||
- `cargo build --target x86_64-pc-windows-gnu --release` calistirir
|
||||
|
||||
Reference in New Issue
Block a user