JK
>LADDAR // LADDAR
INITIERAR VY
Slutförtgopostgresgingolang-migratevalidatorlogrusdocker
Aktiebelöningssystem
Finansiell huvudbok och aktiebelöningsbackend med dubbel bokföring och exakt INR-värdering.
Problem och lösning
Hantering av aktiebelöningar kräver strikt transaktionsnoggrannhet och feltolerans vid externa API-avbrott.
Funktioner
- Oföränderlig transaktionshuvudbok med dubbel bokföring
- Realtids- och fallback-värdering i INR
- Automatiserad intjäning (vesting) och aktiejusteringar
- Fullständig revisionshistorik för regelefterlevnad
- PostgreSQL transaktionsintegritet
Teknikstack
| Teknik | Version | Syfte | Varför vald |
|---|---|---|---|
| Go | 1.25.1 | Programmeringsspråk | Stark stdlib, concurrency-primitiver, snabb kompilering |
| Gin | 1.11.0 | HTTP-ramverk, routing, middleware | Hög prestanda, middleware-stöd, aktiv community |
| PostgreSQL | 17 | Relationsdatabas | Avancerade SQL-funktioner (vyer, LATERAL, genererade kolumner, ENUM) |
| golang-migrate | v4.19.0 | Databasmigreringar | Enkel filbaserad migrationskörare |
| logrus | 1.9.3 | Strukturerad loggning | Strukturerade fält, nivåbaserad loggning |
| go-sqlmock | v1.5.2 | Databasmockning för tester | Simulerar SQL för enhetstester utan riktig DB |
| lib/pq | v1.10.9 | PostgreSQL-drivrutin | Beprövad, inbyggt PostgreSQL-stöd |
| Docker | — | Containerisering | Reproducerbara byggen, isolerade miljöer |
Arkitektur
Kärnkomponenter
- Gin HTTP-server med RequestID-middleware för spårning av förfrågningar
- Reward-handler med SAVEPOINT-baserat idempotensmönster
- Adjustment-handler med SELECT FOR UPDATE radlåsning
- Läshandlers (today, historical, portfolio, stats) som frågar PostgreSQL-vyer
- Bakgrunds-PriceService med pool på 5 goroutines och 3-slots DB-semafor
Systemets motståndskraft
- In-memory PriceCache med RWMutex för läslunga arbetslaster
- CAS-baserad samtidighetskontroll förhindrar kaskaderande uppdateringsfördröjningar
- Panikåterhämtning i price-updater-arbetare förhindrar processkrascher
- Graceful HTTP-nedstängning med 10 s dräneringstimeout
- Transaktionsomslutning med uppskjuten rollback för alla skrivoperationer
Projektstruktur
cmd
stocky-api
main.go
internal
config
database
migrations
handlers
stocky
jobs
price_updater.go
storage
models
utils
API-slutpunkter
Stocky API (port 8080)
| Metod | Rutt | Syfte |
|---|---|---|
| GET | /health | Hälsokontroll — returnerar {status: OK} |
| POST | /api/v1/reward | Skapa belöning — idempotent, transaktionell, avgiftsberäkning |
| POST | /api/v1/adjustments/:id | Tillämpa justering — radlåsning, redovisningsposter per typ |
| GET | /api/v1/today-stocks/:userId | Dagens belöningar från vyn today_rewards |
| GET | /api/v1/historical-inr/:userId | Historisk INR-värdering — paginerad, händelsemultiplicerad |
| GET | /api/v1/stats/:userId | Statistiköversikt — dagens belöningar + totalt portföljvärde |
| GET | /api/v1/portfolio/:userId | Portföljdetaljer — paginerade, filtrerade för avnotering |
Databasdesign
users
| Kolumn | Typ | Anteckningar |
|---|---|---|
| idPK | SERIAL | Genereras automatiskt |
| username | VARCHAR(50) | NOT NULL, UNIQUE |
| VARCHAR(100) | NOT NULL, UNIQUE | |
| created_at | TIMESTAMP | Standard: NOW() |
Användarkonton. Seedade med en testanvändare.
rewards
| Kolumn | Typ | Anteckningar |
|---|---|---|
| idPK | SERIAL | Genereras automatiskt |
| user_id | INT | FK → users(id) ON DELETE CASCADE |
| stock_symbol | VARCHAR(20) | NOT NULL |
| quantity | NUMERIC(18,6) | NOT NULL, negativt = återföring |
| idempotency_key | VARCHAR(64) | UNIQUE, tillåter NULL |
| reward_date | DATE | GENERATED ALWAYS AS (created_at::DATE) STORED |
Kärnbelöningsevenemang. Unikt på (user_id, stock_symbol, reward_date) med skiftlägesokänslig variant.
ledger
| Kolumn | Typ | Anteckningar |
|---|---|---|
| idPK | SERIAL | Genereras automatiskt |
| 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) | Tillåter NULL |
| quantity | NUMERIC(18,6) | Tillåter NULL |
| amount | NUMERIC(18,4) | Tillåter NULL |
Redovisningsbok med dubbel bokföring. Varje belöning genererar 2–5 poster.
stock_prices
| Kolumn | Typ | Anteckningar |
|---|---|---|
| idPK | SERIAL | Genereras automatiskt |
| stock_symbol | VARCHAR(20) | UNIQUE |
| price | NUMERIC(18,4) | Aktuellt pris |
| updated_at | TIMESTAMP | Uppdateras av PriceService |
Senast kända pris per aktie. Uppdateras av bakgrunds-PriceService.
stock_price_history
| Kolumn | Typ | Anteckningar |
|---|---|---|
| idPK | SERIAL | Genereras automatiskt |
| stock_symbol | VARCHAR(20) | NOT NULL |
| price | NUMERIC(18,4) | NOT NULL |
| date | DATE | NOT NULL, UNIQUE med stock_symbol |
Dagliga prisögonblicksbilder för historisk värdering. Upsertas av PriceService.
stock_events
| Kolumn | Typ | Anteckningar |
|---|---|---|
| idPK | SERIAL | Genereras automatiskt |
| stock_symbol | VARCHAR(20) | NOT NULL |
| event_type | stock_event_type | ENUM: split, bonus, merge, delist |
| ratio_num | NUMERIC(18,6) | Multiplikatorns täljare |
| ratio_den | NUMERIC(18,6) | Multiplikatorns nämnare |
| new_symbol | VARCHAR(20) | För fusioner |
| effective_date | TIMESTAMP | NOT NULL |
Företagshändelser. ratio_num/ratio_den definierar multiplikatorn (t.ex. 2:1-split).
adjustments
| Kolumn | Typ | Anteckningar |
|---|---|---|
| idPK | SERIAL | Genereras automatiskt |
| 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) | Tillåter NULL |
Ändringar av befintliga belöningar med radlåsning.
En-till-många: users→rewards (CASCADE), rewards→ledger (CASCADE), rewards→adjustments (CASCADE). Implicita korsreferenser: rewards.stock_symbol ↔ stock_prices.stock_symbol (via UPPER()), rewards.stock_symbol ↔ stock_events.stock_symbol (händelsemultiplikatorer). Ingen formell FK mellan rewards och stock_prices/stock_events; upprätthålls på vynivå.
Viktiga designbeslut
SQL-vyer för aggregering
Beslut: Komplexa portfölj-/historiska beräkningar implementeras som PostgreSQL-vyer i stället för applikationskod
Varför: Minskar applikationskomplexiteten; utnyttjar PostgreSQLs frågeoptimerare; en enda sanningskälla för beräkningar
Fördelar: Konsekvent beräkning över alla endpoints; databasen hanterar JOIN och aggregering effektivt
Avvägningar: Vyer kan vara långsamma för stora datamängder; svårare att felsöka än applikationskod; bundet till PostgreSQL
Logaritmisk produkt för multiplikatorer
Beslut: Använd EXP(SUM(LN(ratio))) för att beräkna kumulativa multiplikatorer för företagshändelser
Varför: Undviker flyttalsöverflöd/underflöde när många händelser kombineras
Fördelar: Numeriskt stabilt; hanterar ett godtyckligt antal händelser
Avvägningar: Mindre läsbart än direkt multiplikation; kräver positiva förhållanden
Endast-handlers-arkitektur (ingen servicelager)
Beslut: Affärslogiken ligger direkt i handlers utan ett separat servicelager
Varför: Enklare för ett litet projekt; färre filer och abstraktioner att underhålla
Fördelar: Lite boilerplate; lätt att följa förfrågningsflödet
Avvägningar: Svårare att återanvända logik; hård koppling mellan HTTP och dataåtkomst; svårare att testa affärslogik separat
Simulerad prisfetcher
Beslut: Använd RandomPriceFetcher i stället för ett verkligt marknadsdata-API
Varför: Utvecklings-/testmiljö; ingen API-nyckelhantering behövs
Fördelar: Inga externa beroenden; nästan deterministiskt beteende
Avvägningar: Inte produktionsklar; portföljvärden är meningslösa; måste ersättas för verklig driftsättning
SAVEPOINT-baserad idempotens
Beslut: Använd PostgreSQL SAVEPOINTs för att hantera idempotens utan att avbryta den yttre transaktionen
Varför: Möjliggör retry-säkerhet utan extern idempotens-tjänst
Fördelar: Avancerad idempotens inom transaktionen som fungerar inom PostgreSQLs begränsningar
Avvägningar: Komplex felhantering; SAVEPOINT-overhead
Ingen autentisering/auktorisering
Beslut: Alla endpoints är offentligt åtkomliga utan auth
Varför: Utvecklings-/demoprojekt; auth förväntas läggas till senare (t.ex. via API-gateway)
Fördelar: Enklare implementering; enklare testning
Avvägningar: Inte lämpligt för produktion; vilken klient som helst kan skapa belöningar eller tillämpa justeringar
Tester
Go standardtesting + go-sqlmock v1.5.2•19 enhetstester
Vad som testas
- Belöningshandler: NULL-idempotens, ogiltig JSON, noll/negativ kvantitet, normalisering, idempotent retry (8 tester)
- Justeringshandler: ogiltigt belönings-ID, ogiltig JSON, ogiltig typ, redovisningsbeteende vid återföring (4 tester)
- Historikhandler: ogiltig userId, ogiltig limit (2 tester)
- Portföljhandler: ogiltig userId, ogiltig offset, skiftlägesokänsligt avnoteringsfilter (3 tester)
- Dagens handler: ogiltig userId (1 test)
- Statistikhandler: ogiltig userId (1 test)
Saknad täckning
- Integrationstester mot riktig PostgreSQL
- Tester för läshandlers med verifiering av verklig data
- Tester för bakgrundsprisuppdateraren (felsökvägar, paniker, retries)
- Tester för samtidig justeringshantering
- Tester för scenarier med transaktionsrollback
- Tester för pagineringsgränsfall
Viktiga utmaningar
- 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
Viktiga lärdomar
- 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