feat(timetable): give the generator its activities from learniq or from two uploaded sheets

[rubenvdlinde]

Timetable generator, section 2: the generator gets its activities from learniq or from two uploaded sheets

Base: development (19711e0).

Change: timetabling-generator (DECISIONS row 17), section 2 of 9 (tasks 2.1 to 2.3). The change stays open; no row moves yet.

What changes

• OCA\Planninq\Event\TimetableActivitiesQueryEvent (typed event, ADR-041, contract version 1): planninq asks for the activities and rooms of an academic year; the app that owns the hour plan answers with answer(app, activities, rooms). Nothing in planninq calls learniq directly.
• OCA\Planninq\Timetabling\SolverInput: the plain input of one run (period keys, rooms, lessons, wishes, source, reason). toArray() is what a timetableScenario keeps under input.
• lib/Service/TimetableInputBuilder.php: dispatches the event; an unanswered event falls back to the uploaded sheets; with neither the input is empty with the reason "No activities: learniq did not answer and no CSV was uploaded". One lesson per weekly lesson (3A:Maths:1), the period keys of the stored week grid, wishes reduced to the fields the solver reads plus their id.
• lib/Service/TimetableCsvParser.php: two sheets. Rooms: reference, capacity, type. Activities: group, subject, teacher, lessons per week, lesson length, room type. Comma or semicolon. Refused with the line number: a wrong header, an empty cell, a count that is not a whole number of 1 or more, a room type that is not on the rooms sheet.
• POST /apps/planninq/api/timetable/input/upload (admin only): both sheets as text; any refused line keeps nothing and returns every refusal; a good upload returns the counts.
• Task 2.3: the learniq listener contract is drafted for Ruben (build-all for-ruben/learniq-timetable-activities-event.md), not filed.

No screen yet: the upload button belongs to the generate dialog (section 5).

Tests

• TimetableInputBuilderTest (4): an answered event becomes five lessons, forty periods and the wish with its id, and the resulting SolverInput inside a queued scenario passes OpenRegister's validator against the real timetableScenario fragment; an unanswered event with no upload gives the empty input and the reason; uploaded sheets are the fallback; the periods follow a stored narrower grid.
• TimetableCsvParserTest (4): a good sheet; a wrong header; each refusal names its line (whole numbers, empty cells, unknown room type); room capacity must be a whole number.
• TimetableInputControllerTest (3): an admin upload is kept; a non-admin is refused with 403 and nothing is kept; a refused line keeps nothing.

Red first, against the section 1 head: the three test classes failed (classes missing). Log in the lane files.

Verification

At head (development 19711e0): composer check:strict 1 on 43b983d (phpcs: two lines over 150 characters), then fixed; phpcs on the changed files 0; lint, phpmd, psalm, phpstan 0; PHPUnit 500 (7 skipped). No frontend, l10n or schema change. CI-shaped Hydra gates (hydra-gates@main, full coverage): ALL applicable gates passed.

Live check

1. As an admin, POST /apps/planninq/api/timetable/input/upload with rooms reference,capacity,type\nB12,30,classroom and activities group,subject,teacher,lessons per week,lesson length,room type\n3A,Maths,noor,2,1,classroom: 200 with rooms 1, activities 1, lessons 2.
2. The same with lessons per week two: 400, "Line 2: lessons per week must be a whole number of 1 or more.", and the earlier upload is still stored.
3. As a non-admin: 403.

Inherited: the non-required Newman, PHPUnit (pgsql) and Quality Report jobs have been red on every PR since #758.

🤖 Generated with Claude Code

[github-actions]

Quality Report — ConductionNL/planninq @ 6db7c94

Check	PHP	Vue	Security	License	Tests
lint	✅
phpcs	✅
phpmd	✅
psalm	✅
phpstan	✅
phpmetrics	✅
eslint		✅
stylelint		✅
build		✅
check-manifest		✅
check-l10n-js		✅
check-schema-l10n		✅
composer			✅	✅ 107/107
npm			✅	✅ 646/646
app:check-code	⏭️
info.xml	✅
REUSE	❌
lockfile sync		✅
PHPUnit					❌
Newman					❌
Playwright					⏭️ deferred: E2E runs locally and on the promotion path only. This pull request targets development, so the suite is asked once per promotion into beta and main rather than once per push per open pull request. Run it on any branch from the Actions tab, or locally with npx playwright test.
Hydra gates					✅

---

Quality workflow — 2026-09-29 22:19 UTC

Download the full PDF report from the workflow artifacts.