>ŁADOWANIE // PROJECT DETAILS

PARSING ARCHITECTURE, DIAGRAMS & API ENDPOINTS

>ŁADOWANIE // ŁADOWANIE

INICJALIZACJA WIDOKU

Powrót do projektów

Zobacz na GitHubie

Ukończonogopostgresgingolang-migratevalidatorlogrusdocker

System Nagród w Akcjach

Księga finansowa i backend nagród akcyjnych wdrażający księgowość podwójnego zapisu z dokładną wyceną w INR.

Problem i rozwiązanie

Zarządzanie nagrodami kapitałowymi wymaga bezwzględnej spójności transakcyjnej oraz odporności na awarie zewnętrznych źródeł cen.

Funkcje

Niezmienna księga transakcji podwójnego zapisu
Wycena w INR w czasie rzeczywistym z mechanizmami awaryjnymi
Automatyczne nabywanie uprawnień (vesting) i korekty akcji
Pełna ścieżka audytu spełniająca wymogi finansowe
Gwarancja spójności transakcyjnej z PostgreSQL

Stos technologiczny

Technologia	Wersja	Cel	Dlaczego wybrano
Go	1.25.1	Język programowania	Solidna biblioteka standardowa, prymitywy współbieżności, szybka kompilacja
Gin	1.11.0	Framework HTTP, routing, middleware	Wysoka wydajność, wsparcie middleware, aktywna społeczność
PostgreSQL	17	Baza danych relacyjna	Zaawansowane funkcje SQL (widoki, LATERAL, kolumny generowane, ENUM)
golang-migrate	v4.19.0	Migracje bazy danych	Prosty runner migracji oparty na plikach
logrus	1.9.3	Logowanie strukturalne	Ustrukturyzowane pola i logowanie z poziomami
go-sqlmock	v1.5.2	Mockowanie bazy na potrzeby testów	Symuluje SQL w testach jednostkowych bez prawdziwej bazy
lib/pq	v1.10.9	Sterownik PostgreSQL	Sprawdzony w boju, natywne wsparcie PostgreSQL
Docker	—	Konteneryzacja	Powtarzalne buildy, izolowane środowiska

Architektura

Docker Compose

Gin HTTP Server

:8080

Handlers

Reward, Adjustment, Today, Historical, Stats, Portfolio

PriceService Worker Pool

PriceCache

in-memory RWMutex

RandomPriceFetcher

PostgreSQL 17

:5432

7 Tables

3 Views

today_rewards, historical_rewards, user_portfolio

2 ENUMs

Główne komponenty

Serwer HTTP Gin z middleware RequestID do śledzenia żądań
Handler nagród z wzorcem idempotencji opartym na SAVEPOINT
Handler korekt z blokowaniem na poziomie wiersza SELECT FOR UPDATE
Handlery odczytu (today, historical, portfolio, stats) odpytujące widoki PostgreSQL
Usługa PriceService w tle z pulą 5 goroutine i semaforem 3 miejsc dla bazy

Odporność systemu

Cache PriceCache w pamięci z RWMutex dla obciążeń z przewagą odczytów
Kontrola współbieżności oparta na CAS zapobiega kaskadowym opóźnieniom aktualizacji
Odzyskiwanie po panice w workerach aktualizacji cen zapobiega awariom procesu
Łagodne zamykanie HTTP z 10-sekundowym limitem opróżniania
Opakowanie transakcyjne z odroczonym rollbackiem dla wszystkich operacji zapisu

Struktura projektu

cmd

stocky-api

main.goPunkt wejścia: konfiguracja bazy, migracje, zadanie w tle, serwer HTTP, łagodne zamykanie

internal

config

database

migrations

handlers

stocky

jobs

price_updater.goPriceService w tle z pulą workerów, cache, ponawianiem i symulowanym fetcherem

storage

models

utils

Punkty końcowe API

Stocky API (port 8080)

Metoda	Trasa	Cel
GET	/health	Kontrola stanu — zwraca {status: OK}
POST	/api/v1/reward	Utwórz nagrodę — idempotentnie, transakcyjnie, z obliczaniem opłat
POST	/api/v1/adjustments/:id	Zastosuj korektę — blokowanie wiersza, wpisy księgowe według typu
GET	/api/v1/today-stocks/:userId	Dzisiejsze nagrody z widoku today_rewards
GET	/api/v1/historical-inr/:userId	Historyczna wycena w INR — paginowana, z mnożnikami zdarzeń
GET	/api/v1/stats/:userId	Podsumowanie statystyk — dzisiejsze nagrody + łączna wartość portfela
GET	/api/v1/portfolio/:userId	Szczegóły portfela — paginowane, filtrowane pod kątem wycofania z giełdy

Projekt bazy danych

users

4 cols

idPK

serial

username

varchar

created_at

timestamp

rewards

6 cols

idPK

serial

user_id

int

stock_symbol

varchar

quantity

numeric(18,6)

idempotency_key

varchar

reward_date

date

ledger

6 cols

idPK

serial

reward_id

int

entry_type

ledger_entry_type

stock_symbol

varchar

quantity

numeric(18,6)

amount

numeric(18,4)

adjustments

6 cols

idPK

serial

reward_id

int

adjustment_type

varchar

delta_quantity

numeric(18,6)

delta_amount

numeric(18,4)

reason

varchar

stock_prices

4 cols

idPK

serial

stock_symbol

varchar

price

numeric(18,4)

updated_at

timestamp

stock_price_history

4 cols

idPK

serial

stock_symbol

varchar

price

numeric(18,4)

date

stock_events

6 cols

idPK

serial

stock_symbol

varchar

event_type

stock_event_type

ratio_num

numeric(18,6)

ratio_den

numeric(18,6)

new_symbol

varchar

users

Kolumna	Typ	Uwagi
idPK	SERIAL	Generowane automatycznie
username	VARCHAR(50)	NOT NULL, UNIQUE
email	VARCHAR(100)	NOT NULL, UNIQUE
created_at	TIMESTAMP	Domyślnie: NOW()

Konta użytkowników. Zasilone jednym użytkownikiem testowym.

rewards

Kolumna	Typ	Uwagi
idPK	SERIAL	Generowane automatycznie
user_id	INT	FK → users(id) ON DELETE CASCADE
stock_symbol	VARCHAR(20)	NOT NULL
quantity	NUMERIC(18,6)	NOT NULL, wartość ujemna = odwrócenie
idempotency_key	VARCHAR(64)	UNIQUE, dopuszcza NULL
reward_date	DATE	GENERATED ALWAYS AS (created_at::DATE) STORED

Główne zdarzenia nagród. Unikalność na (user_id, stock_symbol, reward_date) z wariantem ignorującym wielkość liter.

ledger

Kolumna	Typ	Uwagi
idPK	SERIAL	Generowane automatycznie
reward_id	INT	FK → rewards(id) ON DELETE CASCADE
entry_type	ledger_entry_type	ENUM: stock_units, inr_outflow, fees, brokerage_fee, stt_fee, gst_fee
stock_symbol	VARCHAR(20)	Dopuszcza NULL
quantity	NUMERIC(18,6)	Dopuszcza NULL
amount	NUMERIC(18,4)	Dopuszcza NULL

Księga podwójnego zapisu. Każda nagroda generuje od 2 do 5 wpisów.

stock_prices

Kolumna	Typ	Uwagi
idPK	SERIAL	Generowane automatycznie
stock_symbol	VARCHAR(20)	UNIQUE
price	NUMERIC(18,4)	Bieżąca cena
updated_at	TIMESTAMP	Aktualizowane przez PriceService

Ostatnia znana cena akcji. Aktualizowana przez PriceService w tle.

stock_price_history

Kolumna	Typ	Uwagi
idPK	SERIAL	Generowane automatycznie
stock_symbol	VARCHAR(20)	NOT NULL
price	NUMERIC(18,4)	NOT NULL
date	DATE	NOT NULL, UNIQUE z stock_symbol

Dzienne migawki cen do wyceny historycznej. Wstawiane/aktualizowane przez PriceService.

stock_events

Kolumna	Typ	Uwagi
idPK	SERIAL	Generowane automatycznie
stock_symbol	VARCHAR(20)	NOT NULL
event_type	stock_event_type	ENUM: split, bonus, merge, delist
ratio_num	NUMERIC(18,6)	Licznik mnożnika
ratio_den	NUMERIC(18,6)	Mianownik mnożnika
new_symbol	VARCHAR(20)	Dla fuzji
effective_date	TIMESTAMP	NOT NULL

Operacje korporacyjne. ratio_num/ratio_den definiuje mnożnik (np. split 2:1).

adjustments

Kolumna	Typ	Uwagi
idPK	SERIAL	Generowane automatycznie
reward_id	INT	FK → rewards(id) ON DELETE CASCADE
adjustment_type	VARCHAR(64)	reward_reversal, fee_refund, manual_correction
delta_quantity	NUMERIC(18,6)	NOT NULL
delta_amount	NUMERIC(18,4)	NOT NULL
reason	VARCHAR(255)	Dopuszcza NULL

Modyfikacje istniejących nagród z blokowaniem na poziomie wiersza.

Jeden-do-wielu: users→rewards (CASCADE), rewards→ledger (CASCADE), rewards→adjustments (CASCADE). Niejawne odwołania krzyżowe: rewards.stock_symbol ↔ stock_prices.stock_symbol (przez UPPER()), rewards.stock_symbol ↔ stock_events.stock_symbol (mnożniki zdarzeń). Brak formalnego FK między rewards a stock_prices/stock_events; egzekwowane na poziomie widoków.

Kluczowe decyzje projektowe

Widoki SQL do agregacji

Decyzja: Złożone obliczenia portfela/historyczne są zaimplementowane jako widoki PostgreSQL zamiast w kodzie aplikacji

Dlaczego: Zmniejsza złożoność aplikacji; wykorzystuje optymalizator zapytań PostgreSQL; jedno źródło prawdy dla obliczeń

Korzyści: Spójne obliczenia we wszystkich endpointach; baza efektywnie obsługuje JOIN-y i agregacje

Kompromisy: Widoki mogą być wolne przy dużych zbiorach danych; trudniejsze w debugowaniu niż kod aplikacji; zależność od PostgreSQL

Iloczyn logarytmiczny dla mnożników

Decyzja: Użycie EXP(SUM(LN(ratio))) do obliczania skumulowanych mnożników operacji korporacyjnych

Dlaczego: Unika przepełnienia/niedomiaru zmiennoprzecinkowego przy kumulacji wielu zdarzeń

Korzyści: Stabilne numerycznie; obsługuje dowolną liczbę zdarzeń

Kompromisy: Mniej czytelne niż bezpośrednie mnożenie; wymaga dodatnich współczynników

Architektura tylko z handlerami (bez warstwy usług)

Decyzja: Logika biznesowa znajduje się bezpośrednio w handlerach, bez osobnej warstwy usług

Dlaczego: Prostsze dla małego projektu; mniej plików i abstrakcji do utrzymania

Korzyści: Mało boilerplate'u; łatwe śledzenie przepływu żądania

Kompromisy: Trudniejsze ponowne użycie logiki; silne sprzężenie HTTP i dostępu do danych; trudniejsze niezależne testowanie logiki biznesowej

Symulowany fetcher cen

Decyzja: Użycie RandomPriceFetcher zamiast rzeczywistego API danych rynkowych

Dlaczego: Środowisko deweloperskie/testowe; brak potrzeby zarządzania kluczami API

Korzyści: Zero zewnętrznych zależności; niemal deterministyczne zachowanie

Kompromisy: Nieprzygotowane do produkcji; wartości portfela są bez znaczenia; trzeba zastąpić przy realnym wdrożeniu

Idempotencja oparta na SAVEPOINT

Decyzja: Użycie SAVEPOINT PostgreSQL do obsługi idempotencji bez przerywania zewnętrznej transakcji

Dlaczego: Zapewnia bezpieczeństwo ponowień bez zewnętrznej usługi idempotencji

Korzyści: Zaawansowana idempotencja w transakcji działająca w ramach ograniczeń PostgreSQL

Kompromisy: Złożona obsługa błędów; narzut SAVEPOINT

Brak uwierzytelniania/autoryzacji

Decyzja: Wszystkie endpointy są publicznie dostępne bez auth

Dlaczego: Projekt deweloperski/demo; uwierzytelnianie ma zostać dodane później (np. przez bramę API)

Korzyści: Prostsza implementacja; łatwiejsze testowanie

Kompromisy: Nieodpowiednie do produkcji; dowolny klient może tworzyć nagrody lub stosować korekty

Testy

Standardowe testy Go + go-sqlmock v1.5.2•19 testów jednostkowych

Co jest testowane

Handler nagród: idempotencja NULL, nieprawidłowy JSON, zerowa/ujemna ilość, normalizacja, idempotentne ponowienie (8 testów)
Handler korekt: nieprawidłowy ID nagrody, nieprawidłowy JSON, nieprawidłowy typ, zachowanie księgi przy odwróceniu (4 testy)
Handler historyczny: nieprawidłowy userId, nieprawidłowy limit (2 testy)
Handler portfela: nieprawidłowy userId, nieprawidłowy offset, filtr wycofania z giełdy ignorujący wielkość liter (3 testy)
Handler dzisiejszy: nieprawidłowy userId (1 test)
Handler statystyk: nieprawidłowy userId (1 test)

Brakujące pokrycie

Testy integracyjne z prawdziwym PostgreSQL
Testy handlerów odczytu z weryfikacją rzeczywistych danych
Testy aktualizatora cen w tle (ścieżki błędów, paniki, ponowienia)
Testy równoczesnego przetwarzania korekt
Testy scenariuszy rollbacku transakcji
Testy przypadków brzegowych paginacji

Kluczowe wyzwania

Computing cumulative corporate event multipliers (splits, bonuses) using logarithmic aggregation in SQL views
Idempotent reward creation without external state — SAVEPOINT-based pattern with pq.Error inspection
Case-insensitive stock symbol matching across application and database layers
Race condition prevention in adjustments using FOR UPDATE row locking with dual application+database checks
Missing historical prices causing rewards to be invisible in historical views

Kluczowe wnioski

Transactional consistency using Go & PostgreSQL with proper rollback patterns
Advanced SQL techniques: LATERAL subqueries, EXP(SUM(LN())) for numerical stability
Worker pool concurrency with buffered channel semaphores for controlled DB writes
SAVEPOINT-based idempotency for retry-safe operations within transactions
Trade-offs of handler-only architecture vs service layer separation

>ŁADOWANIE // PROJECT DETAILS

PARSING ARCHITECTURE, DIAGRAMS & API ENDPOINTS

Powrót do projektów

Zobacz na GitHubie

Ukończonogopostgresgingolang-migratevalidatorlogrusdocker

System Nagród w Akcjach

Księga finansowa i backend nagród akcyjnych wdrażający księgowość podwójnego zapisu z dokładną wyceną w INR.

Problem i rozwiązanie

Zarządzanie nagrodami kapitałowymi wymaga bezwzględnej spójności transakcyjnej oraz odporności na awarie zewnętrznych źródeł cen.

Funkcje

Niezmienna księga transakcji podwójnego zapisu
Wycena w INR w czasie rzeczywistym z mechanizmami awaryjnymi
Automatyczne nabywanie uprawnień (vesting) i korekty akcji
Pełna ścieżka audytu spełniająca wymogi finansowe
Gwarancja spójności transakcyjnej z PostgreSQL

Stos technologiczny

Technologia	Wersja	Cel	Dlaczego wybrano
Go	1.25.1	Język programowania	Solidna biblioteka standardowa, prymitywy współbieżności, szybka kompilacja
Gin	1.11.0	Framework HTTP, routing, middleware	Wysoka wydajność, wsparcie middleware, aktywna społeczność
PostgreSQL	17	Baza danych relacyjna	Zaawansowane funkcje SQL (widoki, LATERAL, kolumny generowane, ENUM)
golang-migrate	v4.19.0	Migracje bazy danych	Prosty runner migracji oparty na plikach
logrus	1.9.3	Logowanie strukturalne	Ustrukturyzowane pola i logowanie z poziomami
go-sqlmock	v1.5.2	Mockowanie bazy na potrzeby testów	Symuluje SQL w testach jednostkowych bez prawdziwej bazy
lib/pq	v1.10.9	Sterownik PostgreSQL	Sprawdzony w boju, natywne wsparcie PostgreSQL
Docker	—	Konteneryzacja	Powtarzalne buildy, izolowane środowiska

Architektura

Docker Compose

Gin HTTP Server

:8080

Handlers

Reward, Adjustment, Today, Historical, Stats, Portfolio

PriceService Worker Pool

PriceCache

in-memory RWMutex

RandomPriceFetcher

PostgreSQL 17

:5432

7 Tables

3 Views

today_rewards, historical_rewards, user_portfolio

2 ENUMs

Główne komponenty

Serwer HTTP Gin z middleware RequestID do śledzenia żądań
Handler nagród z wzorcem idempotencji opartym na SAVEPOINT
Handler korekt z blokowaniem na poziomie wiersza SELECT FOR UPDATE
Handlery odczytu (today, historical, portfolio, stats) odpytujące widoki PostgreSQL
Usługa PriceService w tle z pulą 5 goroutine i semaforem 3 miejsc dla bazy

Odporność systemu

Cache PriceCache w pamięci z RWMutex dla obciążeń z przewagą odczytów
Kontrola współbieżności oparta na CAS zapobiega kaskadowym opóźnieniom aktualizacji
Odzyskiwanie po panice w workerach aktualizacji cen zapobiega awariom procesu
Łagodne zamykanie HTTP z 10-sekundowym limitem opróżniania
Opakowanie transakcyjne z odroczonym rollbackiem dla wszystkich operacji zapisu

Struktura projektu

cmd

stocky-api

main.goPunkt wejścia: konfiguracja bazy, migracje, zadanie w tle, serwer HTTP, łagodne zamykanie

internal

config

database

migrations

handlers

stocky

jobs

price_updater.goPriceService w tle z pulą workerów, cache, ponawianiem i symulowanym fetcherem

storage

models

utils

Punkty końcowe API

Stocky API (port 8080)

Metoda	Trasa	Cel
GET	/health	Kontrola stanu — zwraca {status: OK}
POST	/api/v1/reward	Utwórz nagrodę — idempotentnie, transakcyjnie, z obliczaniem opłat
POST	/api/v1/adjustments/:id	Zastosuj korektę — blokowanie wiersza, wpisy księgowe według typu
GET	/api/v1/today-stocks/:userId	Dzisiejsze nagrody z widoku today_rewards
GET	/api/v1/historical-inr/:userId	Historyczna wycena w INR — paginowana, z mnożnikami zdarzeń
GET	/api/v1/stats/:userId	Podsumowanie statystyk — dzisiejsze nagrody + łączna wartość portfela
GET	/api/v1/portfolio/:userId	Szczegóły portfela — paginowane, filtrowane pod kątem wycofania z giełdy

Projekt bazy danych

users

4 cols

idPK

serial

username

varchar

created_at

timestamp

rewards

6 cols

idPK

serial

user_id

int

stock_symbol

varchar

quantity

numeric(18,6)

idempotency_key

varchar

reward_date

date

ledger

6 cols

idPK

serial

reward_id

int

entry_type

ledger_entry_type

stock_symbol

varchar

quantity

numeric(18,6)

amount

numeric(18,4)

adjustments

6 cols

idPK

serial

reward_id

int

adjustment_type

varchar

delta_quantity

numeric(18,6)

delta_amount

numeric(18,4)

reason

varchar

stock_prices

4 cols

idPK

serial

stock_symbol

varchar

price

numeric(18,4)

updated_at

timestamp

stock_price_history

4 cols

idPK

serial

stock_symbol

varchar

price

numeric(18,4)

date

stock_events

6 cols

idPK

serial

stock_symbol

varchar

event_type

stock_event_type

ratio_num

numeric(18,6)

ratio_den

numeric(18,6)

new_symbol

varchar

users

Kolumna	Typ	Uwagi
idPK	SERIAL	Generowane automatycznie
username	VARCHAR(50)	NOT NULL, UNIQUE
email	VARCHAR(100)	NOT NULL, UNIQUE
created_at	TIMESTAMP	Domyślnie: NOW()

Konta użytkowników. Zasilone jednym użytkownikiem testowym.

rewards

Kolumna	Typ	Uwagi
idPK	SERIAL	Generowane automatycznie
user_id	INT	FK → users(id) ON DELETE CASCADE
stock_symbol	VARCHAR(20)	NOT NULL
quantity	NUMERIC(18,6)	NOT NULL, wartość ujemna = odwrócenie
idempotency_key	VARCHAR(64)	UNIQUE, dopuszcza NULL
reward_date	DATE	GENERATED ALWAYS AS (created_at::DATE) STORED

Główne zdarzenia nagród. Unikalność na (user_id, stock_symbol, reward_date) z wariantem ignorującym wielkość liter.

ledger

Kolumna	Typ	Uwagi
idPK	SERIAL	Generowane automatycznie
reward_id	INT	FK → rewards(id) ON DELETE CASCADE
entry_type	ledger_entry_type	ENUM: stock_units, inr_outflow, fees, brokerage_fee, stt_fee, gst_fee
stock_symbol	VARCHAR(20)	Dopuszcza NULL
quantity	NUMERIC(18,6)	Dopuszcza NULL
amount	NUMERIC(18,4)	Dopuszcza NULL

Księga podwójnego zapisu. Każda nagroda generuje od 2 do 5 wpisów.

stock_prices

Kolumna	Typ	Uwagi
idPK	SERIAL	Generowane automatycznie
stock_symbol	VARCHAR(20)	UNIQUE
price	NUMERIC(18,4)	Bieżąca cena
updated_at	TIMESTAMP	Aktualizowane przez PriceService

Ostatnia znana cena akcji. Aktualizowana przez PriceService w tle.

stock_price_history

Kolumna	Typ	Uwagi
idPK	SERIAL	Generowane automatycznie
stock_symbol	VARCHAR(20)	NOT NULL
price	NUMERIC(18,4)	NOT NULL
date	DATE	NOT NULL, UNIQUE z stock_symbol

Dzienne migawki cen do wyceny historycznej. Wstawiane/aktualizowane przez PriceService.

stock_events

Kolumna	Typ	Uwagi
idPK	SERIAL	Generowane automatycznie
stock_symbol	VARCHAR(20)	NOT NULL
event_type	stock_event_type	ENUM: split, bonus, merge, delist
ratio_num	NUMERIC(18,6)	Licznik mnożnika
ratio_den	NUMERIC(18,6)	Mianownik mnożnika
new_symbol	VARCHAR(20)	Dla fuzji
effective_date	TIMESTAMP	NOT NULL

Operacje korporacyjne. ratio_num/ratio_den definiuje mnożnik (np. split 2:1).

adjustments

Kolumna	Typ	Uwagi
idPK	SERIAL	Generowane automatycznie
reward_id	INT	FK → rewards(id) ON DELETE CASCADE
adjustment_type	VARCHAR(64)	reward_reversal, fee_refund, manual_correction
delta_quantity	NUMERIC(18,6)	NOT NULL
delta_amount	NUMERIC(18,4)	NOT NULL
reason	VARCHAR(255)	Dopuszcza NULL

Modyfikacje istniejących nagród z blokowaniem na poziomie wiersza.

Kluczowe decyzje projektowe

Widoki SQL do agregacji

Decyzja: Złożone obliczenia portfela/historyczne są zaimplementowane jako widoki PostgreSQL zamiast w kodzie aplikacji

Dlaczego: Zmniejsza złożoność aplikacji; wykorzystuje optymalizator zapytań PostgreSQL; jedno źródło prawdy dla obliczeń

Korzyści: Spójne obliczenia we wszystkich endpointach; baza efektywnie obsługuje JOIN-y i agregacje

Kompromisy: Widoki mogą być wolne przy dużych zbiorach danych; trudniejsze w debugowaniu niż kod aplikacji; zależność od PostgreSQL

Iloczyn logarytmiczny dla mnożników

Decyzja: Użycie EXP(SUM(LN(ratio))) do obliczania skumulowanych mnożników operacji korporacyjnych

Dlaczego: Unika przepełnienia/niedomiaru zmiennoprzecinkowego przy kumulacji wielu zdarzeń

Korzyści: Stabilne numerycznie; obsługuje dowolną liczbę zdarzeń

Kompromisy: Mniej czytelne niż bezpośrednie mnożenie; wymaga dodatnich współczynników

Architektura tylko z handlerami (bez warstwy usług)

Decyzja: Logika biznesowa znajduje się bezpośrednio w handlerach, bez osobnej warstwy usług

Dlaczego: Prostsze dla małego projektu; mniej plików i abstrakcji do utrzymania

Korzyści: Mało boilerplate'u; łatwe śledzenie przepływu żądania

Kompromisy: Trudniejsze ponowne użycie logiki; silne sprzężenie HTTP i dostępu do danych; trudniejsze niezależne testowanie logiki biznesowej

Symulowany fetcher cen

Decyzja: Użycie RandomPriceFetcher zamiast rzeczywistego API danych rynkowych

Dlaczego: Środowisko deweloperskie/testowe; brak potrzeby zarządzania kluczami API

Korzyści: Zero zewnętrznych zależności; niemal deterministyczne zachowanie

Kompromisy: Nieprzygotowane do produkcji; wartości portfela są bez znaczenia; trzeba zastąpić przy realnym wdrożeniu

Idempotencja oparta na SAVEPOINT

Decyzja: Użycie SAVEPOINT PostgreSQL do obsługi idempotencji bez przerywania zewnętrznej transakcji

Dlaczego: Zapewnia bezpieczeństwo ponowień bez zewnętrznej usługi idempotencji

Korzyści: Zaawansowana idempotencja w transakcji działająca w ramach ograniczeń PostgreSQL

Kompromisy: Złożona obsługa błędów; narzut SAVEPOINT

Brak uwierzytelniania/autoryzacji

Decyzja: Wszystkie endpointy są publicznie dostępne bez auth

Dlaczego: Projekt deweloperski/demo; uwierzytelnianie ma zostać dodane później (np. przez bramę API)

Korzyści: Prostsza implementacja; łatwiejsze testowanie

Kompromisy: Nieodpowiednie do produkcji; dowolny klient może tworzyć nagrody lub stosować korekty

Testy

Standardowe testy Go + go-sqlmock v1.5.2•19 testów jednostkowych

Co jest testowane

Handler nagród: idempotencja NULL, nieprawidłowy JSON, zerowa/ujemna ilość, normalizacja, idempotentne ponowienie (8 testów)
Handler korekt: nieprawidłowy ID nagrody, nieprawidłowy JSON, nieprawidłowy typ, zachowanie księgi przy odwróceniu (4 testy)
Handler historyczny: nieprawidłowy userId, nieprawidłowy limit (2 testy)
Handler portfela: nieprawidłowy userId, nieprawidłowy offset, filtr wycofania z giełdy ignorujący wielkość liter (3 testy)
Handler dzisiejszy: nieprawidłowy userId (1 test)
Handler statystyk: nieprawidłowy userId (1 test)

Brakujące pokrycie

Testy integracyjne z prawdziwym PostgreSQL
Testy handlerów odczytu z weryfikacją rzeczywistych danych
Testy aktualizatora cen w tle (ścieżki błędów, paniki, ponowienia)
Testy równoczesnego przetwarzania korekt
Testy scenariuszy rollbacku transakcji
Testy przypadków brzegowych paginacji

Kluczowe wyzwania

Computing cumulative corporate event multipliers (splits, bonuses) using logarithmic aggregation in SQL views
Idempotent reward creation without external state — SAVEPOINT-based pattern with pq.Error inspection
Case-insensitive stock symbol matching across application and database layers
Race condition prevention in adjustments using FOR UPDATE row locking with dual application+database checks
Missing historical prices causing rewards to be invisible in historical views

Kluczowe wnioski

Transactional consistency using Go & PostgreSQL with proper rollback patterns
Advanced SQL techniques: LATERAL subqueries, EXP(SUM(LN())) for numerical stability
Worker pool concurrency with buffered channel semaphores for controlled DB writes
SAVEPOINT-based idempotency for retry-safe operations within transactions
Trade-offs of handler-only architecture vs service layer separation