Referans · metot-metot
apps/api — Public API
Her tip için görev + metot metot ne yaptığı + hangi arayüzlere bağlı. Katmanlar: FinevoConnect.Yos.Api (giriş) → FinevoConnect.Yos.Application (servis) → FinevoConnect.Yos.Infrastructure (DB/güvenlik/entegrasyon).
Boru hattı: CorrelationId → ExceptionHandling → RequestLogging → LocaleResolution → Authentication → Authorization → ValidationFilter/IdempotencyFilter → Controller.
Controller'lar
AuthControllerFinevoConnect.Yos.Api/ControllersKayıt/token uçları — hepsi IAuthService'e delege eder. Ayrı login yok; register hem kayıt hem giriştir.
Register(req, appKey) | X-App-Key başlığı + userKey/customerNo alır. Kullanıcı yoksa oluşturur, varsa mevcut kullanıcı için token çifti döner. Token gerekmez. |
Refresh(req) | Yenileme token'ı ile yeni erişim token'ı. |
Logout(req) | Kullanıcının yenileme token'larını iptal eder (JWT gerekir). |
Me() | Oturumdaki kullanıcının profilini (userKey, customerNo, görünen ad, dil) döner. |
Bağlı: IAuthService
HhsConnectionsControllerFinevoConnect.Yos.Api/ControllersRıza akışı uçları.
Create(req) | Yeni banka bağlantısı (rıza) başlatır; redirect'te authorizationUrl döner. |
GetById(id, fresh) | Bağlantı detayı; fresh=true ise canlı durum senkronu. |
Callback(query) | GKD onay dönüşü (state+consentStatus+authCode); token gerekmez. |
Delete(id) | Rızayı iptal eder (gerekirse HHS'e cancel niyeti). |
Bağlı: IHhsConnectionService
AccountsController / CardsController / TransactionsControllerFinevoConnect.Yos.Api/ControllersHesap/kart/işlem okuma uçları; hepsi ?fresh=true destekler (canlı sorgu).
List(fresh) / GetById | Bağlı tüm bankalardan liste/detay; fresh=true → LiveRefreshCoordinator. |
Transactions(id, cursor) | İmleç sayfalama; yalnız ilk sayfada canlı tazeleme. |
Detail(id) [Cards] | Kart detayı: limit/borç + puan + taksit birleştirir. |
Bağlı: IAccountAggregationService, ICardService, ITransactionService
PaymentOrders / Recurring / ForwardDated ControllersFinevoConnect.Yos.Api/ControllersÖdeme aileleri; Create'te Idempotency-Key; her ödeme standalone rıza.
Create(req, Idempotency-Key) | Ödeme emri/talimatı oluşturur; onay akışı başlar. |
List / GetById(fresh) | Sayfalı liste + durum (fresh=true canlı). |
Callback(query) | Ödeme onay dönüşü → aktivasyon niyeti. |
Cancel/Delete(id) | İptal (iptal-edilebilirlik kontrolüyle). |
Bağlı: IPaymentOrderService, IRecurringPaymentService, IForwardDatedPaymentService
HhsController / HealthControllerFinevoConnect.Yos.Api/ControllersBanka listesi + sağlık.
List / GetByCode | Etkin bankaların listesi/detayı. |
Live / Ready | Liveness (ayakta mı) / readiness (DB bağlı mı). |
Bağlı: IHhsRegistryService
Middleware & Filter'lar
CorrelationIdMiddlewareFinevoConnect.Yos.Api/Middlewareİzlenebilirlik kimliği.
InvokeAsync | IIdGenerator ile 32-hex correlation_id üretir, HttpContext.Items'e koyar ve Serilog LogContext'e push eder → isteğin tüm logları bu id'yi taşır. |
Bağlı: IIdGenerator
ExceptionHandlingMiddlewareFinevoConnect.Yos.Api/MiddlewareTek merkezî hata dönüştürücü.
InvokeAsync | Sonraki middleware'leri try/catch ile sarar; hata yakalanınca HandleAsync çağırır. |
Map(ex) | Exception tipi → (HTTP status, error code): ValidationException→400, NotFoundException→404, ConflictException→409, BusinessRuleException→422, OhvpsIntegrationException→503, HhsAuthorizationUrlUnavailable→504, diğer→500. |
HandleAsync | ErrorLocalizer ile dile göre başlık/detay alır, RFC 7807 ProblemDetails (code+traceId) yazar; 5xx→LogError, 4xx→LogInformation (log_kind=error). |
Bağlı: IErrorLocalizer
RequestLoggingMiddlewareFinevoConnect.Yos.Api/Middlewareİstek/yanıt logu.
InvokeAsync | İstek gövdesini buffer'lar, yanıt gövdesini MemoryStream ile yakalar; method/path/status/süre + gövdeler (LogScrubber ile redakte) loglar (log_kind=request); asla isteği bozmaz. |
Bağlı: ICurrentUser
LocaleResolutionMiddlewareFinevoConnect.Yos.Api/MiddlewareDil çözümü.
InvokeAsync / ResolveLocale | ?lang veya Accept-Language → desteklenen dil (tr/en); HttpContext.Items[locale] + CurrentUICulture; Content-Language yanıt başlığı. |
ValidationFilterFinevoConnect.Yos.Api/FiltersGirdi doğrulama.
OnActionExecutionAsync | Action argümanları için IValidator<T> bulur+çalıştırır; hata varsa ValidationException (400 + alan-bazlı) fırlatır. |
Bağlı: FluentValidation
IdempotencyFilterFinevoConnect.Yos.Api/FiltersYazma tekrar koruması.
OnActionExecutionAsync | POST/PUT/PATCH/DELETE'te Idempotency-Key + gövde-hash'i; mevcut+tamamlanmış → cache yanıtı döner; TryReserve (unique) → çalıştır → CompleteAsync; hata → ReleaseAsync (TOCTOU guard). |
Bağlı: IIdempotencyStore, IFeatureFlags
Uygulama servisleri
HhsConnectionServiceFinevoConnect.Yos.Application/HhsConnectionsRıza yaşam döngüsünün API tarafı.
CreateAsync | HHS'i çözer, izinleri doğrular (OhvpsPermissionRules), aktif rıza kontrolü; yeni HhsConnection + izinler + ConsentCreate niyeti AYNI tx'te; redirect ise TriggerAndAwaitAuthorizationUrlAsync. |
TriggerAndAwaitAuthorizationUrlAsync | Hangfire immediate trigger atar, batch'in authorizationUrl'i DB'ye yazmasını bounded-poll ile bekler (~5sn); gelmezse 504. |
GetByIdAsync | Bağlantıyı okur; fresh ise LiveRefreshCoordinator (ConnectionStatus kind) ile canlı durum; Reloaded ise DetachAll+yeniden oku. |
HandleCallbackAsync | GkdCallbackProcessor ile state tüketir, onay-echo doğrular, AuthorizationComplete niyeti + immediate trigger. |
DeleteAsync | MarkCancelled + gerekirse ConsentCancel niyeti. |
Bağlı: ISyncIntentService, ILiveRefreshCoordinator, IGkdCallbackProcessor, IHhsResolver, ITokenProtector
AccountAggregationServiceFinevoConnect.Yos.Application/AccountsÇok-banka hesap birleştirme + canlı tazeleme.
ListAsync(userId, fresh) | Kullanıcının hesaplarını okur; bağlı bağlantılar için BuildAccountLiveQueries kurar; LiveRefreshCoordinator.ResolveAsync ile canlı/cache; Reloaded ise DB'den yeniden okur; Freshness+AsOf ile döner. |
GetByIdAsync | Tek hesap + canlı tazeleme sonucu. |
RefreshAsync | Bağlı tüm bağlantılara refresh niyeti + immediate trigger (elle yenileme). |
Bağlı: IAccountRepository, ILiveRefreshCoordinator, ISyncIntentService
CardServiceFinevoConnect.Yos.Application/CardsKart + detay/işlem/puan/taksit.
ListAsync / GetByIdAsync | Kart izni (CardInfo) kontrolü + canlı sorgu (Cards kind). |
GetDetailAsync | BuildDetailItemAsync ile CardDetail+CardPoints+CardInstallments birleştirir; CardDetail kind canlı. |
ListTransactionsAsync | İmleç sayfalama; yalnız ilk sayfada CardTransactions canlı. |
BuildCardLiveQueriesAsync | Bağlı+izinli ise LiveQueryRequest üretir; değilse boş (cache). |
Bağlı: ICardRepository (+detail/point/installment), ILiveRefreshCoordinator
PaymentOrderServiceFinevoConnect.Yos.Application/PaymentOrdersÖdeme emri (standalone rıza).
CreateAsync | Tutar/IBAN doğrular; YENİ ConsentType.Payment bağlantı + PaymentOrder + PaymentOrderSubmit niyeti + PaymentOrderCreatedEvent outbox — hepsi Serializable tx; redirect ise authorizationUrl bounded-wait. |
GetByIdAsync | Ödeme + fresh ise durum canlı senkronu (odmStm→paymentSystem). |
HandleCallbackAsync | GkdCallbackProcessor → PaymentOrderAuthorizationComplete niyeti. |
Bağlı: IPaymentOrderRepository, IOutboxStore, ILiveRefreshCoordinator
SyncIntentServiceFinevoConnect.Yos.Application/SyncIntentsNiyet kuyruğa yazma.
EnqueueAsync<TPayload> | GroupId'yi hedef bağlantıdan çözer (FindGroupIdByIdAsync → rıza-sabit), TraceId'yi Activity'den alır, payload'ı JSON'a serialize eder, SyncIntent kaydını AddAsync (SaveChanges çağıran servise ait — tx-içi). |
Bağlı: ISyncIntentRepository, IHhsConnectionRepository, IRequestCorrelation
Ortak (koordinatör/callback/yardımcı)
LiveRefreshCoordinatorFinevoConnect.Yos.Application/Common/LiveRefreshCanlı/cache kararının tek yeri (ADR-YOS-051/063).
ResolveAsync(fresh, asOf, enqueueIntents, buildLiveQueries) | asOf tazelik penceresi içindeyse Cached döner. fresh + buildLiveQueries varsa → ResolveViaLiveQueryAsync. Aksi/autonomous → intent+trigger yolu. |
ResolveViaLiveQueryAsync | buildLiveQueries() ile istek listesi üretir; her biri için ILiveQueryClient.QueryAsync (senkron batch RPC); hepsi başarılı→Live+Reloaded; herhangi başarısız→autonomous intent kick + Stale+Refreshing. |
TriggerAndAwaitRefreshAsync | UserRequested niyet(ler)i + immediate trigger; niyet durumunu ~30sn bounded-poll; Consumed→Live, Failed/timeout→Stale (eski/fallback yol). |
KickBackgroundRefreshAsync | Autonomous niyet + trigger; beklemeden döner (arka plan tazeleme). |
Bağlı: ILiveQueryClient, ISyncIntentRepository, IBackgroundJobClient
GkdCallbackProcessorFinevoConnect.Yos.Application/Common/GkdOrtak GKD callback işleme.
ProcessAsync<TEntity> | state ile kaynağı tüketir (ConsumeByStateCode), onay-echo doğrular (değilse hata), aktivasyon niyetini stage eder, commit sonrası FireImmediateTrigger. |
FireImmediateTrigger | Hangfire ISyncIntentImmediateTrigger enqueue; enqueue hatası yutulur (IExceptionLogger'a bir kez loglanır) — kullanıcıya hızlı 2xx. |
Bağlı: IBackgroundJobClient, IExceptionLogger
LogScrubberFinevoConnect.Yos.Application/Common/LoggingHassas veri redaksiyonu (saf yardımcı).
Scrub(input) | Bearer/JWT/sk-/AWS/IBAN/TCKN/VKN/PAN regex'leri + JSON alan-bazlı (password/token/secret/cvv/identityValue → [REDACTED]). Enricher tarafından her string log property'sine uygulanır. |
ErrorLocalizerFinevoConnect.Yos.Application/LocalizationÇok-dilli hata metni.
Localize(code, locale) | FrozenDictionary'den kod+dil ile başlık/detay; dilde yoksa tr fallback; kod hiç yoksa kodu döner (LocalizationIntegrityCheck boot-gate). |
Altyapı (DB/güvenlik/entegrasyon)
LiveQueryClientFinevoConnect.Yos.Infrastructure.IntegrationE canlı-okuma senkron istemcisi.
QueryAsync(req) | Named HttpClient ile POST /internal/live-query + X-Internal-Secret; 15sn timeout; 200→LiveQueryResponse parse; hata/timeout/non-200→{Success=false, Outcome=unreachable} (fırlatmaz — çağıran cache'e düşer). |
Bağlı: IHttpClientFactory (batch-live-query)
UnitOfWorkFinevoConnect.Yos.Infrastructure/Persistenceİşlem sınırı.
SaveChangesAsync / TrySaveChangesAsync | Kaydet; Try* DbUpdateConcurrencyException'ı yakalayıp false döner (kaybeden tx no-op). |
DetachAll | Change-tracker'ı temizler — canlı-okuma sonrası batch'in yazdığı taze veriyi görmek için. |
BeginTransactionAsync(level) | Serializable tx (ödeme create atomikliği). |
Bağlı: AppDbContext
IdempotencyStoreFinevoConnect.Yos.Infrastructure/Persistence/StoresYazma tekrar koruması.
FindAsync / TryReserveAsync | Var mı bak; yoksa unique-constraint ile rezerve et (yarış güvenli). |
CompleteAsync / ReleaseAsync | Yanıtı yaz (tamamlandı) / hata olursa kaydı sil. |
Bağlı: AppDbContext, IClock
DataProtectorTokenProtectorFinevoConnect.Yos.Infrastructure/SecurityAt-rest şifreleme.
ProtectToken / UnprotectToken | HHS token'ı şifrele/çöz (purpose yos.hhs.token). |
ProtectIdentity / UnprotectIdentity | TCKN/VKN/IBAN şifrele/çöz (purpose yos.pii.identity). Anahtar halkası batch ile paylaşımlı. |
Bağlı: IDataProtectionProvider
JwtTokenGeneratorFinevoConnect.Yos.Infrastructure/Security/AuthJWT üretimi.
GenerateAccessToken(user) | Kullanıcı claim'leri + kısa ömür (dk); imzalı erişim token'ı. |
GenerateRefreshToken / HashRefreshToken | Rastgele yenileme token'ı + SHA256 hash (DB'de hash saklanır). |
Bağlı: JwtOptions
HhsResolver / SystemClock / ConfigurationFeatureFlagsFinevoConnect.Yos.InfrastructureYardımcılar.
HhsResolver.ResolveAsync | HHS kodu → entity (MemoryCache 15dk). |
SystemClock.Now | Europe/Istanbul saatli DateTimeOffset. |
FeatureFlags.IsEnabled(key) | IdempotencyEnforcement/EnableMtls/EnableJws/AutoEventSubscription. |
Bağlı: IMemoryCache, IConfiguration