feat(oa): add training-dir workflow and save flow for OnlineAcademy runner
Introduce a simpler training-based workflow for the OnlineAcademy Playwright runner. Changes included: - support --training-dir and automatic loading of content.md and training.json - support --env-file so OA credentials no longer need manual shell sourcing - resolve asset paths relative to the training directory - improve human-readable review and execute output with step-by-step progress - keep the browser open after execute when no save flag is used - add optional --save flow that clicks 'Opslaan als' and then chooses 'Concept' - add a concrete user guide for preparing and running training imports - update handover documentation to reflect the current repo structure and workflow - align the repo around trainings/<name>/content.md, training.json and assets/ - remove reliance on older pilot/test material in the documented main flow
This commit is contained in:
@@ -0,0 +1,492 @@
|
||||
# Gebruikershandleiding Import Naar OnlineAcademy
|
||||
|
||||
Deze handleiding beschrijft een eenvoudige en vaste werkwijze voor het aanleveren en importeren van een training op basis van markdown.
|
||||
|
||||
Het doel is dat je per training altijd dezelfde structuur gebruikt, zodat je niet hoeft te onthouden:
|
||||
|
||||
- waar bestanden moeten staan
|
||||
- hoe afbeeldingen gekoppeld worden
|
||||
- waar de URL moet worden ingevuld
|
||||
- hoe je eerst een controle uitvoert en daarna pas de echte import start
|
||||
|
||||
## 1. Wat moet ik op macOS installeren?
|
||||
|
||||
Om de robotisering te gebruiken heb je op macOS het volgende nodig:
|
||||
|
||||
- Terminal
|
||||
- Node.js
|
||||
- npm
|
||||
- de projectmap `/Users/nico/skillstown`
|
||||
|
||||
### Node.js installeren
|
||||
|
||||
Controleer eerst of Node.js al aanwezig is:
|
||||
|
||||
```bash
|
||||
node -v
|
||||
npm -v
|
||||
```
|
||||
|
||||
Als beide opdrachten een versienummer tonen, dan is Node.js al goed geïnstalleerd.
|
||||
|
||||
Als dat niet zo is, installeer dan:
|
||||
|
||||
1. Node.js LTS via de officiële website
|
||||
2. daarna opnieuw controleren met `node -v` en `npm -v`
|
||||
|
||||
Praktisch minimum:
|
||||
|
||||
- gebruik een recente LTS-versie van Node.js
|
||||
|
||||
### Playwright-dependencies installeren
|
||||
|
||||
Ga daarna in Terminal naar de projectmap:
|
||||
|
||||
```bash
|
||||
cd /Users/nico/skillstown
|
||||
```
|
||||
|
||||
Installeer vervolgens de benodigde pakketten:
|
||||
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
Als dit klaar is, is de lokale omgeving gereed.
|
||||
|
||||
## 2. Waar zet ik mijn OnlineAcademy login neer?
|
||||
|
||||
De runner heeft twee inloggegevens nodig:
|
||||
|
||||
- `OA_EMAIL`
|
||||
- `OA_PASSWORD`
|
||||
|
||||
Zet deze in een lokaal `.env` bestand in de projectmap:
|
||||
|
||||
`/Users/nico/skillstown/.env`
|
||||
|
||||
Voorbeeld:
|
||||
|
||||
```dotenv
|
||||
OA_EMAIL=jouw.email@voorbeeld.nl
|
||||
OA_PASSWORD=jouwWachtwoordHier
|
||||
```
|
||||
|
||||
Belangrijk:
|
||||
|
||||
- het bestand heet precies `.env`
|
||||
- het staat in de hoofdmap van het project
|
||||
- zonder dit bestand kan de runner niet inloggen
|
||||
|
||||
### Moet ik `.env` nog handmatig laden?
|
||||
|
||||
Nee, dat hoeft niet meer als je `--env-file` gebruikt.
|
||||
|
||||
De runner kan het `.env` bestand zelf inlezen.
|
||||
|
||||
Gebruik dus gewoon:
|
||||
|
||||
```bash
|
||||
cd /Users/nico/skillstown
|
||||
node onlineacademy-playwright-runner.mjs \
|
||||
--training-dir trainings/intro-sql \
|
||||
--env-file .env
|
||||
```
|
||||
|
||||
Alleen als je geen `--env-file` gebruikt, moet je nog handmatig variabelen laden.
|
||||
|
||||
Als de runner geen credentials kan vinden, krijg je een foutmelding zoals:
|
||||
|
||||
`Zet OA_EMAIL en OA_PASSWORD in .env of in de omgeving.`
|
||||
|
||||
## 3. Waar maak ik de map aan?
|
||||
|
||||
Maak de trainingsmap altijd aan in deze hoofdmap:
|
||||
|
||||
`/Users/nico/skillstown/trainings/`
|
||||
|
||||
Elke training krijgt daar een eigen submap.
|
||||
|
||||
Voorbeeld:
|
||||
|
||||
- `/Users/nico/skillstown/trainings/sql-basics-01/`
|
||||
- `/Users/nico/skillstown/trainings/excel-gevorderd/`
|
||||
- `/Users/nico/skillstown/trainings/pilot-hoofdstuk-04/`
|
||||
|
||||
Gebruik bij voorkeur een korte en herkenbare mapnaam, zonder rare tekens.
|
||||
|
||||
Aanbevolen stijl:
|
||||
|
||||
- alleen kleine letters
|
||||
- woorden gescheiden met `-`
|
||||
|
||||
Voorbeeld:
|
||||
|
||||
`/Users/nico/skillstown/trainings/intro-sql/`
|
||||
|
||||
## 4. Welke bestanden moeten daarin staan?
|
||||
|
||||
Elke trainingsmap bevat precies deze onderdelen:
|
||||
|
||||
- `content.md`
|
||||
- `training.json`
|
||||
- `assets/`
|
||||
|
||||
De structuur is dus:
|
||||
|
||||
```text
|
||||
trainings/
|
||||
intro-sql/
|
||||
content.md
|
||||
training.json
|
||||
assets/
|
||||
```
|
||||
|
||||
## 5. Wat is `content.md`?
|
||||
|
||||
`content.md` is het hoofdbestand met de inhoud van de training.
|
||||
|
||||
Hierin staat:
|
||||
|
||||
- hoofdstukken
|
||||
- pagina's
|
||||
- tekstblokken
|
||||
- vragen
|
||||
- tabellen
|
||||
- verwijzingen naar afbeeldingen
|
||||
|
||||
De afspraak is:
|
||||
|
||||
- de inhoud staat altijd in `content.md`
|
||||
- de bestandsnaam is dus niet vrij, maar vast
|
||||
|
||||
Dat voorkomt verwarring.
|
||||
|
||||
## 6. Wat is `assets/`?
|
||||
|
||||
`assets/` is de map voor alle bijbehorende bestanden die vanuit de markdown nodig zijn.
|
||||
|
||||
Denk aan:
|
||||
|
||||
- afbeeldingen
|
||||
- screenshots
|
||||
- illustraties
|
||||
|
||||
Dus:
|
||||
|
||||
- `assets/` is geen apart systeemonderdeel
|
||||
- het is gewoon een submap binnen de trainingsmap
|
||||
|
||||
Voorbeeld:
|
||||
|
||||
```text
|
||||
trainings/
|
||||
intro-sql/
|
||||
content.md
|
||||
training.json
|
||||
assets/
|
||||
query-voorbeeld.png
|
||||
joins-overzicht.png
|
||||
database-schema.jpg
|
||||
```
|
||||
|
||||
## 7. Hoe verwijs ik in de markdown naar bestanden in `assets/`?
|
||||
|
||||
Gebruik in de markdown altijd relatieve paden vanaf `content.md`.
|
||||
|
||||
Dus verwijs naar bestanden als:
|
||||
|
||||
- `assets/query-voorbeeld.png`
|
||||
- `assets/joins-overzicht.png`
|
||||
|
||||
Niet doen:
|
||||
|
||||
- absolute paden zoals `/Users/nico/...`
|
||||
- bestanden buiten de trainingsmap
|
||||
|
||||
De werkafspraak is:
|
||||
|
||||
- alles wat de training nodig heeft staat in de eigen trainingsmap
|
||||
- alle afbeeldingen staan in `assets/`
|
||||
|
||||
## 8. Wat is `training.json`?
|
||||
|
||||
`training.json` is het configuratiebestand van die ene training.
|
||||
|
||||
Daarin staat niet de inhoud, maar alleen de instellingen die nodig zijn om de import te draaien.
|
||||
|
||||
De belangrijkste instelling is:
|
||||
|
||||
- de OnlineAcademy edit-URL
|
||||
|
||||
`training.json` staat dus hier:
|
||||
|
||||
`/Users/nico/skillstown/trainings/<naam-van-de-training>/training.json`
|
||||
|
||||
Voorbeeld:
|
||||
|
||||
`/Users/nico/skillstown/trainings/intro-sql/training.json`
|
||||
|
||||
## 9. Wat zet ik in `training.json`?
|
||||
|
||||
Minimaal alleen de URL.
|
||||
|
||||
Voorbeeld:
|
||||
|
||||
```json
|
||||
{
|
||||
"url": "https://create.onlineacademy.nl/.../edit?idsVersion=6"
|
||||
}
|
||||
```
|
||||
|
||||
Je hoeft hier dus geen markdown of afbeeldingen in te zetten. Alleen de doel-URL van de training.
|
||||
|
||||
## 10. Volledig voorbeeld van een trainingsmap
|
||||
|
||||
```text
|
||||
/Users/nico/skillstown/trainings/intro-sql/
|
||||
content.md
|
||||
training.json
|
||||
assets/
|
||||
query-voorbeeld.png
|
||||
joins-overzicht.png
|
||||
```
|
||||
|
||||
Met:
|
||||
|
||||
- `content.md` voor de inhoud
|
||||
- `training.json` voor de URL
|
||||
- `assets/` voor de afbeeldingen
|
||||
|
||||
## 11. Hoe start ik de import?
|
||||
|
||||
De import start je vanuit de terminal, in de hoofdmap van het project:
|
||||
|
||||
`/Users/nico/skillstown`
|
||||
|
||||
Je hoeft dus niet op een knop te drukken. De import wordt gestart met één commando.
|
||||
|
||||
Er zijn twee modi:
|
||||
|
||||
- reviewmodus
|
||||
- uitvoermodus
|
||||
|
||||
Binnen de uitvoermodus zijn er twee varianten:
|
||||
|
||||
- uitvoeren zonder opslaan
|
||||
- uitvoeren en daarna `Opslaan als` klikken
|
||||
|
||||
## 12. Hoe start ik alleen de reviewmodus?
|
||||
|
||||
Gebruik reviewmodus om eerst te controleren of:
|
||||
|
||||
- het `.env` bestand gevonden wordt
|
||||
- de login werkt
|
||||
- de juiste training wordt geopend
|
||||
- de markdown kan worden gelezen
|
||||
- de afbeeldingen gevonden worden
|
||||
- de structuur logisch is
|
||||
|
||||
Commando:
|
||||
|
||||
```bash
|
||||
node onlineacademy-playwright-runner.mjs \
|
||||
--training-dir trainings/intro-sql \
|
||||
--env-file .env
|
||||
```
|
||||
|
||||
Wat gebeurt er in reviewmodus:
|
||||
|
||||
- de browser opent
|
||||
- er wordt ingelogd
|
||||
- de URL wordt automatisch uit `training.json` gelezen
|
||||
- de doelpagina wordt geopend
|
||||
- er wordt een controle uitgevoerd
|
||||
- er worden screenshots en controlegegevens opgeslagen
|
||||
- er worden nog geen muterende importacties uitgevoerd
|
||||
|
||||
Belangrijk:
|
||||
|
||||
- zonder `--execute` blijft de runner in reviewmodus
|
||||
|
||||
## 13. Hoe start ik de echte import?
|
||||
|
||||
Als de review goed is, start je dezelfde opdracht opnieuw, maar dan met `--execute`.
|
||||
|
||||
### Variant A: uitvoeren zonder opslaan
|
||||
|
||||
```bash
|
||||
node onlineacademy-playwright-runner.mjs \
|
||||
--training-dir trainings/intro-sql \
|
||||
--env-file .env \
|
||||
--execute
|
||||
```
|
||||
|
||||
Wat gebeurt er dan:
|
||||
|
||||
- de browser opent
|
||||
- de training wordt geopend
|
||||
- pagina's en blokken worden in de editor opgebouwd
|
||||
- de runner vult de inhoud in op basis van `content.md`
|
||||
- de runner stopt daarna op het reviewpunt
|
||||
- het scherm blijft open zodat je kunt controleren wat er is ingevoerd
|
||||
- de inhoud is nog niet opgeslagen
|
||||
|
||||
### Variant B: uitvoeren en daarna opslaan
|
||||
|
||||
Gebruik hiervoor de extra flag `--save`.
|
||||
|
||||
Commando:
|
||||
|
||||
```bash
|
||||
node onlineacademy-playwright-runner.mjs \
|
||||
--training-dir trainings/intro-sql \
|
||||
--env-file .env \
|
||||
--execute \
|
||||
--save
|
||||
```
|
||||
|
||||
Wat gebeurt er dan:
|
||||
|
||||
- de browser opent
|
||||
- de training wordt geopend
|
||||
- pagina's en blokken worden in de editor opgebouwd
|
||||
- de runner vult de inhoud in op basis van `content.md`
|
||||
- de runner klikt daarna op de knop `Opslaan als`
|
||||
- de runner kiest daarna in de popup de optie `Concept`
|
||||
|
||||
## 14. Hoe weet ik of de review goed is?
|
||||
|
||||
De review is goed als:
|
||||
|
||||
- de juiste OnlineAcademy-training opent
|
||||
- de runner zonder foutmelding door de controle komt
|
||||
- de screenshots laten zien dat je in de editor zit
|
||||
- de markdown en assets correct gevonden zijn
|
||||
|
||||
Je hoeft dus niet technisch te beoordelen wat er intern gebeurt. Je kijkt vooral naar:
|
||||
|
||||
- opent de juiste training
|
||||
- zie ik de editor
|
||||
- ontbreken er geen bestanden
|
||||
- krijg ik geen foutmelding
|
||||
|
||||
## 15. Hoe weet ik wat ik moet verbeteren als de review niet goed is?
|
||||
|
||||
Als de review niet goed is, kijk je eerst naar vier dingen:
|
||||
|
||||
1. Bevat `.env` de velden `OA_EMAIL` en `OA_PASSWORD`?
|
||||
2. Klopt de URL in `training.json`?
|
||||
3. Bestaat `content.md` echt in de trainingsmap?
|
||||
4. Bestaan alle bestanden in `assets/` waarnaar de markdown verwijst?
|
||||
|
||||
De meest voorkomende oorzaken zijn:
|
||||
|
||||
- `.env` ontbreekt
|
||||
- `OA_EMAIL` of `OA_PASSWORD` ontbreekt
|
||||
- verkeerde URL
|
||||
- typefout in bestandsnaam
|
||||
- afbeelding staat niet in `assets/`
|
||||
- markdown verwijst naar een bestand dat niet bestaat
|
||||
- inhoud gebruikt een bloktype dat nog niet ondersteund is
|
||||
|
||||
Praktische werkwijze:
|
||||
|
||||
1. Lees de foutmelding.
|
||||
2. Controleer de trainingsmap.
|
||||
3. Controleer `.env`.
|
||||
4. Corrigeer `content.md`, `training.json` of `assets/`.
|
||||
5. Start opnieuw in reviewmodus.
|
||||
6. Pas als de review goed is, draai je `--execute`.
|
||||
|
||||
## 16. Waar vind ik de controlebestanden en screenshots terug?
|
||||
|
||||
De runner slaat resultaten op in `artifacts/`.
|
||||
|
||||
Daar vind je onder andere:
|
||||
|
||||
- screenshots
|
||||
- plan-overzicht
|
||||
- validatie-uitvoer
|
||||
- foutstatus bij mislukte runs
|
||||
|
||||
Dat helpt om achteraf te zien:
|
||||
|
||||
- wat er geopend is
|
||||
- hoe ver de runner kwam
|
||||
- waar het mogelijk misging
|
||||
|
||||
## 17. Welke uitvoer zie ik in de terminal?
|
||||
|
||||
De runner geeft tijdens een run korte voortgangsmeldingen, bijvoorbeeld:
|
||||
|
||||
- `[STAP] Voorbereiden`
|
||||
- `[STAP] Browser openen`
|
||||
- `[STAP] Inloggen`
|
||||
- `[STAP] Editor controleren`
|
||||
- `[STAP] Inhoud opbouwen`
|
||||
- `[INFO] Hoofdstuk 1 van 1: ...`
|
||||
- `[INFO] Pagina 3 van 8: ...`
|
||||
- `[INFO] Blok 2 van 4: image - ...`
|
||||
- `[STAP] Resultaat`
|
||||
|
||||
Bij een geslaagde execute-run zie je nu:
|
||||
|
||||
- `Execute-run afgerond tot het reviewpunt.`
|
||||
- `De inhoud is opgebouwd in de editor.`
|
||||
- `Er is nog niet opgeslagen.`
|
||||
|
||||
Dat betekent:
|
||||
|
||||
- de invoer is uitgevoerd
|
||||
- de inhoud staat in de editor
|
||||
- de inhoud is nog niet definitief bewaard in OnlineAcademy
|
||||
|
||||
Bij een execute-run met `--save` zie je:
|
||||
|
||||
- `Execute-run afgerond.`
|
||||
- `De runner heeft op 'Opslaan als' geklikt en daarna 'Concept' gekozen.`
|
||||
|
||||
Dat betekent:
|
||||
|
||||
- de invoer is uitgevoerd
|
||||
- de runner heeft de save-flow bediend
|
||||
- je moet in de browser nog controleren of OnlineAcademy die actie zichtbaar bevestigt
|
||||
|
||||
## 18. Aanbevolen vaste werkwijze per training
|
||||
|
||||
Gebruik steeds deze volgorde:
|
||||
|
||||
1. Installeer Node.js en voer `npm install` uit.
|
||||
2. Maak `.env` aan in `/Users/nico/skillstown/`.
|
||||
3. Maak een map aan in `trainings/`.
|
||||
4. Zet de inhoud in `content.md`.
|
||||
5. Zet alle afbeeldingen in `assets/`.
|
||||
6. Zet de doel-URL in `training.json`.
|
||||
7. Start eerst de reviewmodus met `--training-dir` en `--env-file`.
|
||||
8. Controleer of de juiste training opent en of er geen fouten zijn.
|
||||
9. Start daarna de uitvoermodus met `--execute`.
|
||||
10. Voeg `--save` alleen toe als de runner ook echt op `Opslaan als` moet klikken.
|
||||
|
||||
## 19. Samenvatting
|
||||
|
||||
De vaste afspraak is:
|
||||
|
||||
- Node.js en `npm install` zijn vooraf geregeld
|
||||
- inloggegevens staan in `.env`
|
||||
- elke training staat in een eigen map onder `trainings/`
|
||||
- de inhoud staat in `content.md`
|
||||
- de URL staat in `training.json`
|
||||
- de afbeeldingen staan in `assets/`
|
||||
- eerst review draaien met `--training-dir` en `--env-file`
|
||||
- daarna pas `--execute`
|
||||
- voeg alleen `--save` toe als de runner aan het eind op `Opslaan als` moet klikken
|
||||
|
||||
De standaardstructuur is:
|
||||
|
||||
```text
|
||||
/Users/nico/skillstown/trainings/<trainingsnaam>/
|
||||
content.md
|
||||
training.json
|
||||
assets/
|
||||
```
|
||||
Reference in New Issue
Block a user