Event-Driven Portfolio Platform (Transactions Service)

Backend di esempio per gestire transazioni BUY/SELL con FastAPI + SQLModel. Questa repo contiene il servizio transazioni, docker-compose per Postgres e la documentazione di dominio/roadmap.

Prerequisiti

• Python >= 3.11 (per sviluppo locale)
• Docker Desktop (per eseguire API + Postgres via compose)

Setup rapido

# dalla root del repo
python -m venv .venv
.\.venv\Scripts\Activate.ps1      # PowerShell su Windows
pip install -r requirements-dev.txt

Avvio con Docker Compose

docker compose up --build

• Postgres ha healthcheck; l'API parte quando il DB e' pronto.
• Variabili: DATABASE_URL gia' impostata in .env.example/transactions.env.
• Swagger UI: http://localhost:8000/docs
• Pool DB con pool_pre_ping=True per riusare le connessioni anche se il DB si riavvia.
• Logging: middleware HTTP logga in JSON con request_id, metodo, path, status e durata in ms. Esempio:

{"asctime": "...", "levelname": "INFO", "name": "transactions_service", "message": "request", "request_id": "uuid", "method": "POST", "path": "/transactions", "status_code": 200, "duration_ms": 5.2}

• Idempotenza: nelle POST puoi impostare l'header Idempotency-Key (es. demo-1) per ottenere lo stesso id su retry; in Swagger compare tra i Parameters quando l'API è aggiornata.

Avvio locale senza container

set DATABASE_URL=postgresql://postgres:postgres@localhost:5432/transactions  # adatta se necessario
cd services/transaction
uvicorn app.main:app --reload

Test

cd services/transaction
pytest

• Coprono invarianti (quantity>0, date future, sell oltre posseduto) e API POST/GET. Usano SQLite in-memory, non serve Postgres.

Makefile (scorciatoie)

• make up / make down / make logs
• make test (da root, lancia pytest nel servizio)
• make build (docker compose build)

Script PowerShell (cartella scripts/)

• scripts\up.ps1 (usa -Build per forzare build): .\scripts\up.ps1 -Build
• scripts\down.ps1: .\scripts\down.ps1
• scripts\logs.ps1: .\scripts\logs.ps1
• scripts\test.ps1: .\scripts\test.ps1
• scripts\start-all.ps1: avvia Docker, migrazioni e frontend in automatico.

API Portfolio

• Import CSV: endpoint POST /imports/transactions (upload file CSV, vedi docs/sample-portfolio.csv).
• Portfolio: GET /portfolio, GET /portfolio/metrics, GET /portfolio/allocation.

Frontend (mini UI React)

cd frontend
npm install
npm run dev

• UI su http://localhost:5173
• API su http://localhost:8000 (configurabile con VITE_API_BASE_URL)
• Vite aggiornato a v7.x dopo npm audit fix --force.

Documentazione utile

• Roadmap: portfolio-event-driven-roadmap.md
• Stato e note backend: docs/stato-progetto-e-note-backend.md
• Panoramica codice: docs/code-overview.md
• Modello di dominio: docs/domain-model.md
• Quickstart dettagliato: docs/quickstart.md
• Playbook backend: docs/backend-engineer-playbook.md