BlueGit

projects-timfalken-com verhalenboek

Files

verhalenboek
README.md

Verhalenboek

Een verhalenboek: elke kalenderdag heeft een titel en precies drie verhalen. Lezers zien wat ze al gelezen hebben. Een beheerder vult het boek, met de hand of via een API-sleutel. Inloggen gaat via auth.timfalken.com.

De applicatie staat in web/. Lokaal:

php -S 127.0.0.1:8080 -t web web/router.php

Open http://127.0.0.1:8080. Je bent automatisch test_user_1 en daarmee beheerder. Onder Instellingen wissel je naar test_user_2, een gewone lezer.

Publieke URL

Microchess staat op https://projects.timfalken.com/microchess omdat die map de FTP-map onder de site projects.timfalken.com is. Hier is de CI-variabele projectftp gelijk aan $timftproot/verhaaltjesboek. Dezelfde afleiding geeft:

https://projects.timfalken.com/verhaaltjesboek

Wat Tim moet instellen

Deploy naar master zet de code op de server, maar raakt data/ niet aan. Daarin blijven de database, sessies en het geheim staan. Bij de eerste paginabezoek maakt de app data/config.php aan als dat bestand er nog niet is. Een bestaand bestand wordt nooit overschreven.

1. Zet de code op master (de pipeline test eerst, en uploadt daarna alleen bij een groene master). 2. Open eenmaal https://projects.timfalken.com/verhaaltjesboek zodat data/config.php ontstaat. Het bestand staat op de server in de FTP-map verhaaltjesboek/data/config.php (projectftp + /data/config.php). 3. Registreer bij https://auth.timfalken.com/admin het callback-pad op het domein projects.timfalken.com:

  • client_id: projects.timfalken.com (het domein van de publieke URL, hetzelfde domein als microchess)
  • callback-pad: /verhaaltjesboek/callback.php
  • Voeg alleen dat pad toe. Genereer het clientgeheim niet opnieuw als microchess hetzelfde domein al gebruikt: een nieuw geheim maakt de andere site stuk. Kopieer het bestaande geheim.

4. Vul op de server data/config.php in. Dit bestand wordt niet gecommit en niet geüpload. Laat key_secret staan: die maakt de app zelf aan (64 hexadecimale tekens) en versleutelt daarmee API-sleutels, zodat een beheerder ze later opnieuw kan tonen. Ontbreekt hij, dan vult de app hem één keer aan zonder de andere velden te wissen.

<?php
return [
    'base_url' => 'https://projects.timfalken.com/verhaaltjesboek',
    'client_id' => 'projects.timfalken.com',
    'client_secret' => 'het-geheim-uit-admin',
    'key_secret' => 'blijft-de-gegenereerde-waarde',
];

Lege velden voor URL en client vallen terug op VERHALENBOEK_BASE_URL, VERHALENBOEK_CLIENT_ID en VERHALENBOEK_CLIENT_SECRET. Een ingevuld veld wint van de omgeving. base_url mag een submap bevatten en heeft geen slash aan het eind. key_secret komt niet uit de omgeving.

5. Log als eerste zelf in. Die eerste gebruiker wordt beheerder. Iedereen daarna is lezer. Het account-id en de gebruikersnaam komen uit /api/me. E-mail wordt niet gelezen en niet opgeslagen. Onder Beheer zie je alle gebruikers. Daar maak je iemand anders beheerder, of haal je die rol weer weg. Je kunt je eigen beheerdersrol niet uitzetten, zodat er altijd minstens één beheerder blijft. 6. Maak onder Sleutels een API-sleutel voor de schrijver-agent. De volledige sleutel (vb_…) verschijnt meteen, en daarna opnieuw als je op die sleutel tikt. Alleen een ingelogde beheerder ziet dat; de lijst en de export tonen alleen het voorvoegsel.

De OAuth-flow is dezelfde als bij microchess: state, code wisselen op de server via POST /oauth/token, daarna GET /api/me, verlengen via POST /api/session/extend, en afmelden via POST /api/logout. Het bearer-token van het account blijft in de PHP-sessie en komt niet in JavaScript.

Leesstatus

Een dag wordt gelezen zodra de dagpagina opent, niet pas onderaan. Korte verhalen passen vaak op één scherm, dus "onderaan" is dan hetzelfde als openen, of het gebeurt juist nooit. Opnieuw openen houdt de dag gelezen. Per ongeluk geopend? Houd de dag in het overzicht ingedrukt (telefoon) of klik met de rechtermuisknop (desktop) en kies ongelezen. Het standaardmenu en tekstselectie blijven tijdens die handeling uit.

Verderlezen opent de vroegste ongelezen dag van het hele boek, ook als die buiten de week valt die je nu ziet. Het aantal ongelezen dagen is hetzelfde totaal, zodat het klopt met die knop. Standaard volgen kleuren het systeem; het lettertype is een serif. Licht, donker, serif, schreefloos en rond worden per gebruiker op de server bewaard.

Weekoverzicht

Het overzicht toont één kalenderweek, maandag tot en met zondag. Dagen zonder verhaal blijven weg. Zonder #/week/JJJJ-MM-DD opent het overzicht de week van de laatst gelezen dag: de dag die je het laatst hebt geopend. Zonder leesgeschiedenis is dat de week van de nieuwste dag, of de huidige kalenderweek als het boek nog leeg is. Vorige week en Volgende week staan boven de lijst, met het bereik erbij, bijvoorbeeld 5–11 oktober 2026.

Op de dagpagina blijven Vorige dag en Volgende dag de aangrenzende geschreven dagen. Die knoppen springen niet naar een andere week.

API

Schrijven kan met een Bearer-sleutel of, in de browser, als beheerder. Een volledige dag heeft precies drie verhalen, elk met een titel en minstens één alinea. De volgorde in de lijst is plek 1, 2 en 3.

GET /api.php/days/latest is de nieuwste datum die nog een dagrecord heeft, ook als daar een verhaal uit verwijderd is (complete is dan false). Ontbreekt er nog niets, dan is het antwoord 404.

GET /api.php/days/gaps geeft, tussen de eerste en de laatste dag:

  • missing: kalenderdagen zonder dagrecord (verwijderd of nooit geschreven)
  • incomplete: dagen die bestaan maar geen drie verhalen meer hebben, met missingPositions

Een onvolledige dag staat niet óók in missing. Staat een datum in missing, maak hem met POST. Staat hij in incomplete, vul de plek of vervang de dag met PUT en precies drie verhalen.

curl -sS -X POST \
  -H 'Authorization: Bearer vb_JOUW_SLEUTEL' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{"date":"2026-10-05","title":"De herfstwind","stories":[
    {"title":"Ochtend","paragraphs":["De wind stond al vroeg aan de deur."]},
    {"title":"Middag","paragraphs":["Op het plein joeg een krant zichzelf achterna."]},
    {"title":"Avond","paragraphs":["Het licht in de keuken bleef aan."]}
  ]}' \
  'https://projects.timfalken.com/verhaaltjesboek/api.php/days'

curl -sS -H 'Authorization: Bearer vb_JOUW_SLEUTEL' \
  'https://projects.timfalken.com/verhaaltjesboek/api.php/days/latest'

curl -sS -H 'Authorization: Bearer vb_JOUW_SLEUTEL' \
  'https://projects.timfalken.com/verhaaltjesboek/api.php/days/gaps'
MethodePadBetekenis
GET/daysDagen, oudste eerst. Een ingelogde lezer ziet ook read. Daarnaast lastRead, week (maandag–zondag, met previous, next en label) en weekDays. ?week=JJJJ-MM-DD kiest een week; zonder die parameter is het de week van lastRead, anders van de nieuwste dag, anders van ?today= of vandaag.
GET/days/latestNieuwste geschreven datum.
GET/days/gapsGaten en onvolledige dagen.
GET/days/JJJJ-MM-DDDag, verhalen, previous en next.
POST/daysNieuwe dag met precies drie verhalen. 201, of 409 als de datum bezet is.
PUT/days/JJJJ-MM-DDTitel en/of vervanging door precies drie verhalen.
DELETE/days/JJJJ-MM-DDDag weg.
POST/days/JJJJ-MM-DD/storiesVerhaal erbij zolang er minder dan drie zijn.
PUT/days/JJJJ-MM-DD/stories/1Plek 1, 2 of 3 bijwerken.
DELETE/days/JJJJ-MM-DD/stories/2Eén verhaal weg; de andere plekken blijven.
POST / DELETE/days/JJJJ-MM-DD/readAlleen een ingelogde lezer.
PUT/me/settingstheme: system, light of dark. font: serif, sans of rounded.
GET/me/exportEigen gegevens als JSON.

Fouten zijn {"error":"…"}. Validatie die de drie-verhalenregel raakt geeft 422. De menselijke uitleg met dezelfde voorbeelden staat op docs.php.

Een 401 (geen header, verkeerd formaat, of een onbekende/ingetrokken sleutel) zet WWW-Authenticate: Bearer en voegt how_to_authenticate toe, met dezelfde tekst in hint. Die tekst noemt het geval, de header Authorization: Bearer vb_…, Sleutels op {base_url}/#/sleutels, en een link naar docs.php. Een 403 omdat een lezer iets doet dat een sleutel of beheerder vereist, heeft die uitleg ook, zonder WWW-Authenticate. Sleutels zelf beheren kan alleen in de beheerderssessie. Een 403 door een ongeldige CSRF-header blijft alleen {"error":"…"}.

curl -sS -D - -o - \
  'https://projects.timfalken.com/verhaaltjesboek/api.php/days/latest'

GET /api.php/keys/{id} geeft de volledige sleutel terug aan een ingelogde beheerder. Opzoeken bij een verzoek blijft een hash op token_hash.

Deploy

.gitlab-ci.yml is die van microchess: PHP-syntax, domeintests, API-tests, een JavaScript-syntaxcheck, en een echte FTP-fixture. Alleen master uploadt, en nooit tegelijk met een andere productie-deploy. ci/deploy.py spiegelt web/ met lftp en slaat data/ (database, WAL, config.php, sessies) over, zowel bij upload als bij verwijderen. data/.htaccess wordt apart gezet. tests/, router.php en README.md gaan niet mee.

Benodigde CI-variabelen, al aanwezig in dit project: timftphost, timftpuser, timftppassword, timftproot, projectftp ($timftproot/verhaaltjesboek).

Tests

find web -name '*.php' -not -path '*/artifacts/*' -print0 | xargs -0 -n1 php -l
php web/tests/storybook.php
python3 web/tests/startup.py
python3 web/tests/integration.py
node --check web/assets/app.js
python3 ci/test_deploy.py

De API-tests draaien een kopie onder web/tests/artifacts/ en laten de echte database met rust.