BlueGit

projects-timfalken-com verhalenboek

Files

verhalenboek / README.md

README.md

feat: voeg Verhalenboek toe met dagen, leesvoortgang en schrijf-API
timfa project_87242033_bot_b167a9be22027ad5a4b431d0ad8426c6 · pushed by timfa · 6 weeks ago
799da657 History
README.md 7.2 KiB Download Raw

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:

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

Lege velden 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.

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. 6. Maak onder Sleutels een API-sleutel voor de schrijver-agent. De volledige sleutel (vb_…) verschijnt één keer.

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. Standaard volgen kleuren het systeem; het lettertype is een serif. Licht, donker, serif, schreefloos en rond worden per gebruiker op de server bewaard.

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.
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.

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.

Source
1# Verhalenboek
2
3Een 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](https://auth.timfalken.com).
4
5De applicatie staat in [`web/`](web/). Lokaal:
6
7```sh
8php -S 127.0.0.1:8080 -t web web/router.php
9```
10
11Open 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.
12
13## Publieke URL
14
15Microchess 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:
16
17**https://projects.timfalken.com/verhaaltjesboek**
18
19## Wat Tim moet instellen
20
21Deploy 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.
22
231. Zet de code op `master` (de pipeline test eerst, en uploadt daarna alleen bij een groene `master`).
242. 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`).
253. Registreer bij https://auth.timfalken.com/admin het callback-pad op het domein `projects.timfalken.com`:
26 - **client_id:** `projects.timfalken.com` (het domein van de publieke URL, hetzelfde domein als microchess)
27 - **callback-pad:** `/verhaaltjesboek/callback.php`
28 - 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.
294. Vul op de server `data/config.php` in. Dit bestand wordt niet gecommit en niet geüpload:
30
31```php
32<?php
33return [
34 'base_url' => 'https://projects.timfalken.com/verhaaltjesboek',
35 'client_id' => 'projects.timfalken.com',
36 'client_secret' => 'het-geheim-uit-admin',
37];
38```
39
40Lege velden 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.
41
425. 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.
436. Maak onder **Sleutels** een API-sleutel voor de schrijver-agent. De volledige sleutel (`vb_…`) verschijnt één keer.
44
45De 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.
46
47## Leesstatus
48
49Een 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.
50
51**Verderlezen** opent de vroegste ongelezen dag. Standaard volgen kleuren het systeem; het lettertype is een serif. Licht, donker, serif, schreefloos en rond worden per gebruiker op de server bewaard.
52
53## API
54
55Schrijven 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.
56
57`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.
58
59`GET /api.php/days/gaps` geeft, tussen de eerste en de laatste dag:
60
61- `missing`: kalenderdagen zonder dagrecord (verwijderd of nooit geschreven)
62- `incomplete`: dagen die bestaan maar geen drie verhalen meer hebben, met `missingPositions`
63
64Een 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.
65
66```sh
67curl -sS -X POST \
68 -H 'Authorization: Bearer vb_JOUW_SLEUTEL' \
69 -H 'Accept: application/json' \
70 -H 'Content-Type: application/json' \
71 -d '{"date":"2026-10-05","title":"De herfstwind","stories":[
72 {"title":"Ochtend","paragraphs":["De wind stond al vroeg aan de deur."]},
73 {"title":"Middag","paragraphs":["Op het plein joeg een krant zichzelf achterna."]},
74 {"title":"Avond","paragraphs":["Het licht in de keuken bleef aan."]}
75 ]}' \
76 'https://projects.timfalken.com/verhaaltjesboek/api.php/days'
77
78curl -sS -H 'Authorization: Bearer vb_JOUW_SLEUTEL' \
79 'https://projects.timfalken.com/verhaaltjesboek/api.php/days/latest'
80
81curl -sS -H 'Authorization: Bearer vb_JOUW_SLEUTEL' \
82 'https://projects.timfalken.com/verhaaltjesboek/api.php/days/gaps'
83```
84
85| Methode | Pad | Betekenis |
86| --- | --- | --- |
87| GET | `/days` | Dagen, oudste eerst. Een ingelogde lezer ziet ook `read`. |
88| GET | `/days/latest` | Nieuwste geschreven datum. |
89| GET | `/days/gaps` | Gaten en onvolledige dagen. |
90| GET | `/days/JJJJ-MM-DD` | Dag, verhalen, `previous` en `next`. |
91| POST | `/days` | Nieuwe dag met precies drie verhalen. 201, of 409 als de datum bezet is. |
92| PUT | `/days/JJJJ-MM-DD` | Titel en/of vervanging door precies drie verhalen. |
93| DELETE | `/days/JJJJ-MM-DD` | Dag weg. |
94| POST | `/days/JJJJ-MM-DD/stories` | Verhaal erbij zolang er minder dan drie zijn. |
95| PUT | `/days/JJJJ-MM-DD/stories/1` | Plek 1, 2 of 3 bijwerken. |
96| DELETE | `/days/JJJJ-MM-DD/stories/2` | Eén verhaal weg; de andere plekken blijven. |
97| POST / DELETE | `/days/JJJJ-MM-DD/read` | Alleen een ingelogde lezer. |
98| PUT | `/me/settings` | `theme`: `system`, `light` of `dark`. `font`: `serif`, `sans` of `rounded`. |
99| GET | `/me/export` | Eigen gegevens als JSON. |
100
101Fouten zijn `{"error":"…"}`. Validatie die de drie-verhalenregel raakt geeft 422. De menselijke uitleg met dezelfde voorbeelden staat op `docs.php`.
102
103## Deploy
104
105`.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`](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.
106
107Benodigde CI-variabelen, al aanwezig in dit project: `timftphost`, `timftpuser`, `timftppassword`, `timftproot`, `projectftp` (`$timftproot/verhaaltjesboek`).
108
109## Tests
110
111```sh
112find web -name '*.php' -not -path '*/artifacts/*' -print0 | xargs -0 -n1 php -l
113php web/tests/storybook.php
114python3 web/tests/startup.py
115python3 web/tests/integration.py
116node --check web/assets/app.js
117python3 ci/test_deploy.py
118```
119
120De API-tests draaien een kopie onder `web/tests/artifacts/` en laten de echte database met rust.