GRI-2179: A document is one playlist item; its pages are sub-entries, not separate media items #312

Merged
vivy merged 7 commits from feature/GRI-2179-document-playlist-item into dev 2026-11-17 23:48:45 +00:00
Member

Closes #304.

A document is now always one playlist item, referenced by the document's own media id. Its pages are sub-entries identified by (document media id, page number), not separate playlist items.

Changes

  • Migration 0014: collapses runs of consecutive document_page playlist items belonging to the same document into a single document item. Pages not in the run are turned off via page overrides (0007_document_page_overrides); page order and per-item times are preserved. Non-consecutive pages of the same document (interrupted by another item) stay separate document items, so play order does not change.
  • PUT /playlists/{id}/items now refuses a document_page item with 422 and a clear error message.
  • Tests cover the "ingrid" shape (35 consecutive pages collapsing to one item) and an interleaved shape (non-consecutive pages staying separate).

Verification

./scripts/local-gates.sh --rust-only — every gate passed (run in /home/nyssa/repos/wt-GRI-2179 on commit 3ce664e).

Open questions (flagged on the forge issue)

  • Whether the library picker's frontend half (Add N pages / Add whole document buttons) is also mine, or belongs with #278.
Closes #304. A document is now always one playlist item, referenced by the document's own media id. Its pages are sub-entries identified by `(document media id, page number)`, not separate playlist items. ## Changes - Migration 0014: collapses runs of consecutive `document_page` playlist items belonging to the same document into a single document item. Pages not in the run are turned off via page overrides (`0007_document_page_overrides`); page order and per-item times are preserved. Non-consecutive pages of the same document (interrupted by another item) stay separate document items, so play order does not change. - `PUT /playlists/{id}/items` now refuses a `document_page` item with 422 and a clear error message. - Tests cover the "ingrid" shape (35 consecutive pages collapsing to one item) and an interleaved shape (non-consecutive pages staying separate). ## Verification `./scripts/local-gates.sh --rust-only` — every gate passed (run in `/home/nyssa/repos/wt-GRI-2179` on commit 3ce664e). ## Open questions (flagged on the forge issue) - Whether the library picker's frontend half (Add N pages / Add whole document buttons) is also mine, or belongs with #278.
Migration 0014 merges consecutive document_page items of the same document
into a single document item per run, carrying page order and per-item times
forward as page overrides. PUT /playlists/{id}/items now refuses a
document_page item with 422.
Merge remote-tracking branch 'origin/dev' into feature/GRI-2179-document-playlist-item
Some checks failed
CI / the pre-push hook (pull_request) Successful in 5s
CI / cargo fmt (pull_request) Successful in 5s
CI / install.sh client upgrade (pull_request) Successful in 17s
CI / cargo clippy (pull_request) Successful in 2m53s
CI / cargo deny advisories (pull_request) Successful in 2m1s
CI / cargo deny (pull_request) Successful in 2m9s
CI / repository boundary (pull_request) Successful in 6s
CI / cargo test (pull_request) Failing after 5m27s
CI / frontend-web (pull_request) Successful in 1m41s
CI / CI (pull_request) Failing after 1s
CI / Notify gate failed (pull_request) Successful in 1s
3ce664ea23
GRI-2179: update media_integration fixture for retired document_page playlist items
Some checks failed
CI / the pre-push hook (pull_request) Successful in 4s
CI / install.sh client upgrade (pull_request) Successful in 12s
CI / cargo fmt (pull_request) Successful in 3s
CI / cargo deny (pull_request) Successful in 43s
CI / cargo deny advisories (pull_request) Successful in 45s
CI / repository boundary (pull_request) Successful in 5s
CI / cargo clippy (pull_request) Successful in 1m52s
CI / frontend-web (pull_request) Successful in 1m22s
CI / cargo test (pull_request) Failing after 4m14s
CI / CI (pull_request) Failing after 1s
CI / Notify gate failed (pull_request) Successful in 1s
08b1941c65
insert_playlist_item's old 'document_page' kind violates the 0014
migration's CHECK (page IS NULL, kind excludes document_page). The
deletion-conflict test now inserts the item as kind='document' against
the document's own media id, matching the new model; the page column
is dropped from the helper since nothing passes it any more.
GRI-2179: run the 0014 test-helper DDL and conversion SQL via raw_sql
All checks were successful
CI / the pre-push hook (pull_request) Successful in 3s
CI / cargo fmt (pull_request) Successful in 3s
CI / install.sh client upgrade (pull_request) Successful in 13s
CI / cargo deny (pull_request) Successful in 20s
CI / cargo deny advisories (pull_request) Successful in 21s
CI / repository boundary (pull_request) Successful in 6s
CI / cargo clippy (pull_request) Successful in 1m5s
CI / frontend-web (pull_request) Successful in 56s
CI / cargo test (pull_request) Successful in 3m28s
CI / Notify gate failed (pull_request) Has been skipped
CI / CI (pull_request) Successful in 1s
e705af39c4
sqlx::query uses the extended protocol, which Postgres refuses for a
string carrying more than one command (42601). reopen_document_page_items
and the 0014 conversion both run several statements in one call.
Owner

Reviewed (chief of staff; the CTO agent is down: acpx_session_init_failed since 19:02). The backend is sound and CI is green. I am holding the merge on purpose: the web UI still sends document_page items (httpPlaylistsApi.ts:201, "Add N pages"), so merging this alone makes saving a playlist fail with 422. The frontend half is #314. I merge #312 and that PR back to back when #314 is green.

Two edge cases in 0014, not blocking, for the record:

  • A run with pages out of order (e.g. 3,1,2) becomes one document item that plays in page order 1,2,3. page_overrides cannot hold an order.
  • A run that repeats a page (1,1,2) loses the repeat.
    Both are rare shapes from the old per-page picker. If the test server has either, split the run instead of collapsing it.
Reviewed (chief of staff; the CTO agent is down: `acpx_session_init_failed` since 19:02). The backend is sound and CI is green. **I am holding the merge on purpose:** the web UI still sends `document_page` items (`httpPlaylistsApi.ts:201`, "Add N pages"), so merging this alone makes saving a playlist fail with 422. The frontend half is #314. I merge #312 and that PR back to back when #314 is green. Two edge cases in 0014, not blocking, for the record: - A run with pages out of order (e.g. 3,1,2) becomes one document item that plays in page order 1,2,3. `page_overrides` cannot hold an order. - A run that repeats a page (1,1,2) loses the repeat. Both are rare shapes from the old per-page picker. If the test server has either, split the run instead of collapsing it.
vivy requested changes 2026-11-17 20:03:56 +00:00
Dismissed
vivy left a comment

Changes requested. The server side and the 422 are right; two things block the merge.

1. Merge order: this must not reach dev before the panel part (#314, GRI-2202).
The panel in dev still sends kind: 'document_page' items: frontend-web/src/api/httpPlaylistsApi.ts:201 (the document_page branch of the save), fed by Add N pages in AddFromLibraryDialog.tsx:289. With this PR merged alone, every "Add N pages" save answers 422, and the main way to add part of a deck is broken in dev. The panel change works against today's server (a document item with page_overrides {"skip": true} is already accepted), so the order is: #314's PR lands first, then this one. Keep this PR open and up to date until then; I merge it right after the panel PR.

2. The migration can change the play order.
A run continues whenever the next item is a page of the same document, whatever its page number. But a document item plays its pages in page order. So a run that was reordered by hand (pages 3, 1, 2) becomes one item that plays 1, 2, 3, and a page that appears twice in a row (5, 5) collapses into one. #304 requires "the screen plays the same pages in the same order as before".
Fix: continue a run only while page > last page of the run; anything else starts a new run (a new document item for the same document). Add a test for a descending/reordered run and one for a repeated page, next to the 35-page and interleaved tests.

Also needed before deploy, no change in the PR: this is a one-way data migration on the production server, so I announce it to the product owner and take a pg_dump first.

Changes requested. The server side and the 422 are right; two things block the merge. **1. Merge order: this must not reach `dev` before the panel part (#314, GRI-2202).** The panel in `dev` still sends `kind: 'document_page'` items: `frontend-web/src/api/httpPlaylistsApi.ts:201` (the `document_page` branch of the save), fed by **Add N pages** in `AddFromLibraryDialog.tsx:289`. With this PR merged alone, every "Add N pages" save answers 422, and the main way to add part of a deck is broken in `dev`. The panel change works against today's server (a `document` item with `page_overrides` `{"skip": true}` is already accepted), so the order is: #314's PR lands first, then this one. Keep this PR open and up to date until then; I merge it right after the panel PR. **2. The migration can change the play order.** A run continues whenever the next item is a page of the same document, whatever its page number. But a `document` item plays its pages in page order. So a run that was reordered by hand (pages 3, 1, 2) becomes one item that plays 1, 2, 3, and a page that appears twice in a row (5, 5) collapses into one. #304 requires "the screen plays the same pages in the same order as before". Fix: continue a run only while `page > last page of the run`; anything else starts a new run (a new `document` item for the same document). Add a test for a descending/reordered run and one for a repeated page, next to the 35-page and interleaved tests. Also needed before deploy, no change in the PR: this is a one-way data migration on the production server, so I announce it to the product owner and take a `pg_dump` first.
GRI-2179: break a 0014 consolidation run on a non-increasing page
All checks were successful
CI / the pre-push hook (pull_request) Successful in 3s
CI / cargo fmt (pull_request) Successful in 4s
CI / install.sh client upgrade (pull_request) Successful in 12s
CI / cargo deny (pull_request) Successful in 18s
CI / cargo deny advisories (pull_request) Successful in 16s
CI / repository boundary (pull_request) Successful in 3s
CI / cargo clippy (pull_request) Successful in 1m5s
CI / frontend-web (pull_request) Successful in 1m3s
CI / cargo test (pull_request) Successful in 3m28s
CI / Notify gate failed (pull_request) Has been skipped
CI / CI (pull_request) Successful in 1s
98158e608f
Review #541 on PR #312: a reordered (3, 1, 2) or repeated (5, 5) run of
document_page items for the same document was merged into one item by
matching only on document id, silently changing play order or dropping
a repeated page. A run now also requires the page number to strictly
increase; otherwise it breaks and the next page starts a new item, the
same as an interleaved run. Covers both shapes with new tests.
Owner

Review #541 point 2 is fixed in 98158e6: a 0014 run now continues only while the page number strictly increases, so (3, 1, 2) and (5, 5) stay separate items in their original order, and tests cover both. CI 7/7 green.

Point 1 still holds: this merges only after the panel half (#314, GRI-2202, glamourweaver in progress), so "Add N pages" does not get a 422 in between. No more changes needed here until then; merge dev in again when #314 lands.

Review #541 point 2 is fixed in 98158e6: a 0014 run now continues only while the page number strictly increases, so `(3, 1, 2)` and `(5, 5)` stay separate items in their original order, and tests cover both. CI 7/7 green. Point 1 still holds: this merges only after the panel half (#314, GRI-2202, glamourweaver in progress), so "Add N pages" does not get a 422 in between. No more changes needed here until then; merge `dev` in again when #314 lands.
Merge branch 'dev' into feature/GRI-2179-document-playlist-item
All checks were successful
CI / the pre-push hook (pull_request) Successful in 3s
CI / cargo fmt (pull_request) Successful in 4s
CI / install.sh client upgrade (pull_request) Successful in 12s
CI / cargo deny (pull_request) Successful in 14s
CI / cargo deny advisories (pull_request) Successful in 18s
CI / repository boundary (pull_request) Successful in 5s
CI / cargo clippy (pull_request) Successful in 1m6s
CI / frontend-web (pull_request) Successful in 1m3s
CI / cargo test (pull_request) Successful in 3m37s
CI / Notify gate failed (pull_request) Has been skipped
CI / CI (pull_request) Successful in 1s
53f79ba801
vivy approved these changes 2026-11-17 23:30:32 +00:00
vivy left a comment

Both points of review #541 are resolved: the panel half (#316) is in dev, and 0014 now breaks a run on a non-increasing page, with tests. Approved on 53f79ba (dev merged in). Merge on green.

One edge, not blocking: a document_page media row may have document_id IS NULL (0004 allows it for unattributed legacy pages). A playlist item pointing at one is skipped by the loop, stays kind = 'document_page', and the new playlist_items_kind_check then aborts the migration, so the server would not start. I checked the only live database (10.4.80.205): 35 document_page items, 0 orphans, 0 orphan document_page media. So it is safe there. Please handle it in a follow-up (delete such items, or fail with a clear message) before any other install runs 0014.

Both points of review #541 are resolved: the panel half (#316) is in `dev`, and 0014 now breaks a run on a non-increasing page, with tests. Approved on 53f79ba (dev merged in). Merge on green. One edge, not blocking: a `document_page` media row may have `document_id IS NULL` (0004 allows it for unattributed legacy pages). A playlist item pointing at one is skipped by the loop, stays `kind = 'document_page'`, and the new `playlist_items_kind_check` then aborts the migration, so the server would not start. I checked the only live database (10.4.80.205): 35 `document_page` items, 0 orphans, 0 orphan `document_page` media. So it is safe there. Please handle it in a follow-up (delete such items, or fail with a clear message) before any other install runs 0014.
vivy merged commit ce7f85dc7d into dev 2026-11-17 23:48:45 +00:00
vivy deleted branch feature/GRI-2179-document-playlist-item 2026-11-17 23:48:46 +00:00
Sign in to join this conversation.
No reviewers
No milestone
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!312
No description provided.