71 lines
3.2 KiB
Markdown
71 lines
3.2 KiB
Markdown
# Logboek
|
|
|
|
Bijgehouden tijdens de bouw. Per blok: wat ik deed, waarom, wat ik heb laten
|
|
vallen.
|
|
|
|
## Opzet (avond dag 1)
|
|
|
|
Wat ik deed:
|
|
|
|
- Afspraken vastgelegd in AGENTS.md (architectuur, naamgeving, wanneer
|
|
commentaar, wat de linters afdwingen).
|
|
- Backend-skelet: Python 3.13 + FastAPI via uv, mappenstructuur volgens
|
|
ports-and-adapters (domain / ports / adapters / pipeline / api), config
|
|
met alleen de app-mode (demo of live), health-endpoint met een smoke test.
|
|
- Frontend-skelet: Vue 3 + TypeScript via Vite, met eslint, prettier en
|
|
vue-tsc.
|
|
- docker-compose die 1 image bouwt: frontend-build en API samen op dezelfde
|
|
poort. De poort ligt vast omdat de geregistreerde Spotify redirect-URI
|
|
moet kloppen.
|
|
- CI op elke push: ruff, mypy, pytest voor de backend; typecheck, lint en
|
|
build voor de frontend. Groen vanaf de eerste commit.
|
|
- Repo op eigen Forgejo met een mirror naar GitHub.
|
|
|
|
Waarom:
|
|
|
|
- Structuur eerst, dan blijft elke volgende stap klein en controleerbaar.
|
|
- `docker compose up` is het opleverbare, dus dat werkt vanaf het begin van development.
|
|
- Alles Engels behalve dit logboek; ik volg de taal van de opdracht.
|
|
|
|
Wat ik heb laten vallen of uitgesteld:
|
|
|
|
- Domainmodellen, protocollen, prompts, pipeline-instellingen en het
|
|
frontend-typecontract bewust nog niet neergezet. Die ontstaan in de stap
|
|
waar ze horen. Ik probeer op die manier bewust vroeg drift en dode code te voorkomen.
|
|
- Geen apart beslisdocument. De motivering staat in de README en hier.
|
|
|
|
## Spotify-koppeling (ochtend dag 2)
|
|
|
|
Wat ik deed:
|
|
|
|
- Login via Spotify met PKCE en cookie-sessies: tokens blijven server-side, de browser krijgt alleen een opaque HttpOnly cookie.
|
|
- Dunne async client op de Spotify Web API met per-endpoint retrybeleid:
|
|
leesacties herhalen maximaal 1 keer en alleen binnen een grens
|
|
(Retry-After), schrijfacties op playlists nooit.
|
|
- Token-refresh is single-flight: parallelle requests delen 1 refresh in
|
|
plaats van er allemaal zelf een te starten.
|
|
- Mapping van Spotify-JSON naar eigen modellen op 1 plek; kapotte items
|
|
vallen weg in plaats van dat ze de app breken.
|
|
- Getypeerde fouten en 12 transport- en routetests op een mock transport.
|
|
- Na een eerste review de login-flow uit de routes getrokken naar een eigen
|
|
module (routes zijn nu dunne doorgeefluiken) en het retrybeleid herschreven
|
|
naar een lineaire keten van losse regels in plaats van een loop met flags;
|
|
foutdetails uit de Spotify-body worden meegenomen in de getypeerde fouten
|
|
en quota-uitputting wordt apart herkend en nooit opnieuw geprobeerd.
|
|
- Daarna het API-contract vastgelegd: request-schema en de gestreamde
|
|
events (metadata / track / warning / error / done), gespiegeld in
|
|
TypeScript.
|
|
|
|
Waarom:
|
|
|
|
- Schrijfacties blind herhalen kan dubbele playlist-items opleveren; dat
|
|
risico sluit ik structureel uit in het retrybeleid.
|
|
- Het contract eerst bevriezen maakt parallel werken aan frontend en
|
|
pipeline mogelijk zonder elkaar te breken.
|
|
|
|
Wat ik heb laten vallen of uitgesteld:
|
|
|
|
- De naam-naar-ID cache en de port-interfaces doorgeschoven naar de
|
|
pipeline-stap; daar bestaat het ontwerp pas echt.
|
|
- OpenAPI-codegen voor het contract overwogen en afgewezen: de kern van dit
|
|
contract is de event-stream en die modelleert OpenAPI niet.
|