A document is one playlist item; its pages are sub-entries, not separate media items #304

Closed
opened 2026-11-17 12:39:29 +00:00 by vivy · 4 comments
Owner

Product owner, 2026-11-17 (GRI-2051): "A document gets a MediaId but pages only a sub ID. Because if somebody pushes all pages, they are multiple objects (like in the 'ingrid' playlist)."

Today. Each page of a PDF/PPTX is its own media row (kind = document_page, document_id, page, migration 0004). The library picker (#208/#222) has two buttons: Add whole document makes one playlist item, Add N pages makes N separate playlist items, one per page. On the campus test server the playlist "ingrid" has 35 items with 35 different media ids: one document, added page by page. Those 35 rows cannot be timed together, moved together or removed together, and the #278 sub-list cannot group them.

Change. A document is always one playlist item, referenced by the document's media id. Its pages are sub-entries of that item, identified by (document media id, page number) — the "sub id". No playlist item refers to a page's own media id any more.

  • Picker: Add N pages (from a selection or a range like 1-5,8-9) adds one document item with only those pages on. The other pages are off ("Skip this page", which already exists in 0007_document_page_overrides). Add whole document stays as it is.
  • Playlist: the document item opens to its pages (#278). A page that is off can be turned on again there. File time and page time work as #278 describes.
  • Adding the same document twice to one playlist is still allowed (two items), for decks that are meant to appear twice in a loop.
  • Migration: in each playlist, a run of consecutive page items of the same document becomes one document item. Pages that were not in the run are off, the item keeps the page order and the per-item times as page overrides. Non-consecutive pages of one document (another item between them) stay separate document items, so the play order does not change. A test covers the "ingrid" shape (35 consecutive pages) and an interleaved shape.
  • API: PUT /playlists/{id}/items refuses a document_page item (422 with a clear message) after the migration. The client protocol already plays a document item page by page, so the player needs no change — check it.
  • The page media rows can stay internally (thumbnails, rendered files); only the playlist stops pointing at them.

Done when: on the test server, "ingrid" shows as one document item with its pages under it, the screen plays the same pages in the same order as before, and adding pages 1-5,8-9 of a deck makes one item.

Works together with #278 (the page sub-list in the playlist). #278 is the screen; this is the data under it.

Product owner, 2026-11-17 (GRI-2051): *"A document gets a MediaId but pages only a sub ID. Because if somebody pushes all pages, they are multiple objects (like in the 'ingrid' playlist)."* **Today.** Each page of a PDF/PPTX is its own media row (`kind = document_page`, `document_id`, `page`, migration 0004). The library picker (#208/#222) has two buttons: **Add whole document** makes one playlist item, **Add N pages** makes N separate playlist items, one per page. On the campus test server the playlist "ingrid" has **35 items with 35 different media ids**: one document, added page by page. Those 35 rows cannot be timed together, moved together or removed together, and the #278 sub-list cannot group them. **Change.** A document is always **one** playlist item, referenced by the document's media id. Its pages are sub-entries of that item, identified by `(document media id, page number)` — the "sub id". No playlist item refers to a page's own media id any more. - **Picker:** **Add N pages** (from a selection or a range like `1-5,8-9`) adds one document item with only those pages on. The other pages are off ("Skip this page", which already exists in `0007_document_page_overrides`). **Add whole document** stays as it is. - **Playlist:** the document item opens to its pages (#278). A page that is off can be turned on again there. File time and page time work as #278 describes. - **Adding the same document twice** to one playlist is still allowed (two items), for decks that are meant to appear twice in a loop. - **Migration:** in each playlist, a run of consecutive page items of the same document becomes one document item. Pages that were not in the run are off, the item keeps the page order and the per-item times as page overrides. Non-consecutive pages of one document (another item between them) stay separate document items, so the play order does not change. A test covers the "ingrid" shape (35 consecutive pages) and an interleaved shape. - **API:** `PUT /playlists/{id}/items` refuses a `document_page` item (422 with a clear message) after the migration. The client protocol already plays a document item page by page, so the player needs no change — check it. - The page media rows can stay internally (thumbnails, rendered files); only the playlist stops pointing at them. **Done when:** on the test server, "ingrid" shows as one document item with its pages under it, the screen plays the same pages in the same order as before, and adding pages 1-5,8-9 of a deck makes one item. Works together with #278 (the page sub-list in the playlist). #278 is the screen; this is the data under it.
Member

Backend half in progress on feature/GRI-2179-document-playlist-item (branched from dev at d1a9bcb).

Scope. This covers the backend only (migration, store, API) — the picker's "Add N pages" button is frontend-web and is not part of this change; flagging separately below so it can be routed.

What's done so far:

  • crates/server/migrations/0014_consolidate_document_page_items.sql: for every playlist, collapses each maximal run of consecutive document_page items referencing the same document into one document item (kept row = the run's first item, so its id/position/validity do not move). A page in the run keeps its own duration_seconds as a {"seconds": n} override; every other page of that document gets {"skip": true}. Two runs of the same document separated by another item stay two separate document items — play order never moves. After the conversion, the migration tightens playlist_items's own CHECK constraints so the DB itself can no longer hold a document_page row, not just the API.
  • PUT /playlists/{id}/items now refuses a document_page item with 422 document_page_not_allowed (previously it resolved the page number and accepted it). Fixed a bug on the way: the per-item validation error wrapper (ValidationError::at_index) was forcing every validation failure to 400, which would have silently downgraded this 422 — it now keeps the original status.
  • Tests: two new integration tests re-run the migration's conversion logic directly (same technique media_integration.rs already uses for 0004's backfill) — the "ingrid" shape (35 consecutive pages, one with its own duration) and an interleaved shape (two runs of the same document split by another item). Plus a unit test and an integration test for the new 422 refusal.
  • The push-time expansion (document → one document_page wire item per page) already existed from GRI-1961/#157 and needed no change — confirmed the client protocol needs nothing here either, per the issue's "check it".

Needs a decision from the CTO:

  1. Frontend scope. "Add N pages" (picker) and the "done when" bit about adding pages 1-5,8-9 as one item are frontend-web changes. Should I pick those up too, or is that prismancer/glamourweaver's half? This board/forge issue is labelled Area/Backend only, so I've treated the frontend picker change as out of scope for me — please route it if it needs its own ticket.
  2. File overlap, not blocking. aetherforge's open branch fix/GRI-2180-pg18-restrict-violation-code also touches crates/server/src/playlists/handlers.rs (moving is_foreign_key_violation into crate::db). My diff doesn't touch that function or its call site, so I don't expect a real conflict, but flagging per the file-ownership rule.

Running the local gates now; will report the result and open the PR once green.

Backend half in progress on `feature/GRI-2179-document-playlist-item` (branched from `dev` at `d1a9bcb`). **Scope.** This covers the backend only (migration, store, API) — the picker's "Add N pages" button is `frontend-web` and is not part of this change; flagging separately below so it can be routed. **What's done so far:** - `crates/server/migrations/0014_consolidate_document_page_items.sql`: for every playlist, collapses each maximal run of consecutive `document_page` items referencing the same document into one `document` item (kept row = the run's first item, so its id/position/validity do not move). A page in the run keeps its own `duration_seconds` as a `{"seconds": n}` override; every other page of that document gets `{"skip": true}`. Two runs of the same document separated by another item stay two separate `document` items — play order never moves. After the conversion, the migration tightens `playlist_items`'s own `CHECK` constraints so the DB itself can no longer hold a `document_page` row, not just the API. - `PUT /playlists/{id}/items` now refuses a `document_page` item with `422 document_page_not_allowed` (previously it resolved the page number and accepted it). Fixed a bug on the way: the per-item validation error wrapper (`ValidationError::at_index`) was forcing every validation failure to `400`, which would have silently downgraded this `422` — it now keeps the original status. - Tests: two new integration tests re-run the migration's conversion logic directly (same technique `media_integration.rs` already uses for `0004`'s backfill) — the "ingrid" shape (35 consecutive pages, one with its own duration) and an interleaved shape (two runs of the same document split by another item). Plus a unit test and an integration test for the new `422` refusal. - The push-time expansion (`document` → one `document_page` wire item per page) already existed from GRI-1961/#157 and needed no change — confirmed the client protocol needs nothing here either, per the issue's "check it". **Needs a decision from the CTO:** 1. **Frontend scope.** "Add N pages" (picker) and the "done when" bit about adding pages 1-5,8-9 as one item are frontend-web changes. Should I pick those up too, or is that `prismancer`/`glamourweaver`'s half? This board/forge issue is labelled `Area/Backend` only, so I've treated the frontend picker change as out of scope for me — please route it if it needs its own ticket. 2. **File overlap, not blocking.** `aetherforge`'s open branch `fix/GRI-2180-pg18-restrict-violation-code` also touches `crates/server/src/playlists/handlers.rs` (moving `is_foreign_key_violation` into `crate::db`). My diff doesn't touch that function or its call site, so I don't expect a real conflict, but flagging per the file-ownership rule. Running the local gates now; will report the result and open the PR once green.
Member

PR #312 CI's cargo test failure was a stale test fixture, not the migration: deleting_a_document_used_by_a_playlist_names_it_and_can_detach_and_delete inserted its playlist item directly as kind='document_page', which migration 0014's new CHECK now refuses. Fixed the fixture to insert kind='document' against the document's own media id. Verified locally: full media_integration suite 24/24 passed, fmt/clippy clean. Pushed as 08b1941; CI re-running.

PR #312 CI's cargo test failure was a stale test fixture, not the migration: `deleting_a_document_used_by_a_playlist_names_it_and_can_detach_and_delete` inserted its playlist item directly as kind='document_page', which migration 0014's new CHECK now refuses. Fixed the fixture to insert kind='document' against the document's own media id. Verified locally: full media_integration suite 24/24 passed, fmt/clippy clean. Pushed as 08b1941; CI re-running.
Member

PR #312 CI's cargo test failure was a real bug, not a stale fixture: the 0014 test helper (reopen_document_page_items) and the backfill-conversion SQL ran a multi-statement string through sqlx::query(...) (prepared-statement/extended protocol), which Postgres refuses for more than one command (42601). Switched those three call sites to sqlx::raw_sql, which uses the simple protocol — the same mechanism sqlx::migrate! itself uses to run migration files with multiple statements. Verified locally: both 0014-backfill tests (35-consecutive-pages and interleaved shapes) pass, full playlist_integration (42) and media_integration (24) suites pass, fmt/clippy clean. Pushed e705af3.

PR #312 CI's cargo test failure was a real bug, not a stale fixture: the 0014 test helper (`reopen_document_page_items`) and the backfill-conversion SQL ran a multi-statement string through `sqlx::query(...)` (prepared-statement/extended protocol), which Postgres refuses for more than one command (42601). Switched those three call sites to `sqlx::raw_sql`, which uses the simple protocol — the same mechanism `sqlx::migrate!` itself uses to run migration files with multiple statements. Verified locally: both 0014-backfill tests (35-consecutive-pages and interleaved shapes) pass, full playlist_integration (42) and media_integration (24) suites pass, fmt/clippy clean. Pushed e705af3.
Author
Owner

Backend PR #312 is reviewed and green; held until the frontend half #314 is green, then both merge together. Detail on #312.

Backend PR #312 is reviewed and green; held until the frontend half #314 is green, then both merge together. Detail on #312.
vivy closed this issue 2026-11-17 23:48:45 +00:00
Sign in to join this conversation.
No project
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
Grimoirix/grimoire-of-digital-signage#304
No description provided.