tracker

6.7 KB

1. # Franchises and timelines (tracker.worldapi.org#19, mission 020 (old 066))
3. Creator: "we have franchises, and timelines, and some franchises have multiple timelines ... make them sortable by timeline or
4. release date at shows the release date of the last episode counts. in a show or movie page we show a franchise widget with
5. < Prequel | TimelineName | Sequel > and if the timeline is part of a franchise that franchise is above it and when you click on
6. it you get the franchise index." Names: "Franchise", "Timeline"; navigation `/franchises`.
8. ## Data (`franchises.hl`, new tables — nothing in `shows.db` changes)
10. | Table | Fields |
11. |---|---|
12. | `franchises.db` (`!slug`) | `name`, `slug`, `shortId` (always null for now), `summary`, `created` |
13. | `timelines.db` (`!slug`) | `name`, `slug`, `franchise` (@id or null), `order` [show @id …] (in-world order), `source` (`tmdb`/`editor`), `tmdbCollection` (TMDB id or null), `created` |
14. | `collectionchecks.db` | pk = the movie's show @id; `collection` (TMDB id or null), `why` (`collection`, `collection known`, `no collection`, `TMDB 404`, `collection 404`), `at` — the seed's progress |
16. * Slugs like the shows' urlSegment: `Star Trek — Prime` → `Star-Trek-Prime`; taken → `-2`, `-3`; never `edit`.
17. * A title may be in several timelines → one widget per timeline. `byShow` (show @id → [timeline @id]) is built at start
18. (`ensureFranchises`, one scan) and kept current by every edit.
19. * Inspect: the pages (`/franchises` lists every timeline with its count), or a small .hl script opening
20. `new MPackDB(file = '<copy>/timelines.db', primaryKey = '@id', indexes = ['!slug'])` + `find(null, null)` — ONLY on a copy
21. or with the app stopped (opening a table rewrites its files, hybriel#40).
23. ## Ordering
25. * **Timeline** = `order` as edited (the seed: TMDB collection parts by `release_date`).
26. * **Release** = a movie's `release`; a SERIES' LAST episode: the newest one already out (≤ today, UTC), else the newest
27. announced one, else the series' own `release`. No date → last. Equal dates keep the timeline order. Shown per row as
28. `1996-11-18` / `last episode 2020-06-15`.
29. * Franchise index: its timelines oldest first (by their earliest release).
30. * Public like all lists (mission 010 (old 054)): pages and prequel/sequel links skip titles that are not `adult == false`; the editor
31. shows every title.
33. ## Pages
35. | Route | Component | |
36. |---|---|---|
37. | `/franchises` | `components/franchises.hl` | franchises (→ index, n timelines), then the timelines without one (TMDB collections) with n titles; creator: "Edit" |
38. | `/franchises/<slug>` | `components/franchise.hl` | the index: name, summary, each timeline a header (name → its page, count, `Timeline | Release` toggle) + its rows |
39. | `/timelines/<slug>` | `components/franchise.hl` | one timeline, its franchise above it; creator: "Edit" |
40. | `/franchises/edit` | `components/franchiseedit.hl` | creator: new franchise (name, summary), new timeline (name → its editor), find a timeline by name |
41. | `/timelines/<slug>/edit` | `components/timelineedit.hl` | creator: franchise chips (None + all; a tap attaches), rows ↑ ↓ ✕, "Add titles" (search.hl index) |
42. | widget on `/shows/<slug>` | `components/franchisewidget.hl` | composed by `components/show.hl` under the header: franchise above, `‹ Prequel | name | Sequel ›`, the title under each side, a missing side greyed out (`span.off`) |
44. The sort toggle is client-only (`flatRows` is pure; both orders come with the page). One flat row list (`head`/`item`
45. rows) instead of a nested for (hybriel#86).
47. **Editor = the creator only**: `isEditorSession` = the signed-in user's ident id is in `TRACKER_EDITORS` (default `az5b2`).
48. Every editing face (`fedCreateFranchise`, `fedCreateTimeline`, `tedSetFranchise`, `tedMove`, `tedRemove`, `tedAdd`) checks it
49. again server-side; `fedFindTimelines` / `tedSearch` are public reads. Not built: rename/delete of franchises or timelines,
50. editing a franchise's summary (open point).
52. ## The seed (TMDB movie collections)
54. In the app, own `every(0.1)` clock (`project.hl collectionTick` → `franchises.hl seedStep`), ONE movie per step:
56. 1. `GET /movie/<tmdbId>` → `belongs_to_collection` (none → check row `no collection`; 404 → `TMDB 404`; other failure →
57. back of the queue, ≤ 2 retries per start).
58. 2. A collection seen before (`collectionsDone`, from check rows + timelines) → just a check row, no further request.
59. 3. Else `GET /collection/<id>` → parts sorted by `release_date`, mapped to OUR non-adult movies by tmdbId. **≥ 2 → one
60. timeline** (`source = 'tmdb'`, no franchise); < 2 → none (`small`). Every matched part gets a check row at once, so its
61. own details request is never made.
63. Pause after a step: 260 ms × requests made (≤ 40 / 10 s, like the adult backfill). Waits while the daily sync or the adult
64. backfill runs. Queue at start = every movie with a tmdbId, `adult != true`, without a check row → resumes after a restart;
65. nothing to do → one log line. Persisted every `TRACKER_COLLECTIONS_PERSIST_EVERY` (25) steps and at the end. A hand-edited
66. timeline is never touched. Log: `collections: start, N movies to check`, every `TRACKER_COLLECTIONS_LOG_EVERY` (500)
67. `collections: pos/N movies, checked= timelines= titles= small= noCollection= notFound= requests= errors= retries= seconds=`,
68. `collections done: …`. `TRACKER_COLLECTIONS=0` switches it off (off too without `TMDB_READ_TOKEN`).
70. Re-seed (e.g. after many imports): delete `collectionchecks.db*` with the app stopped — existing collection timelines are
71. skipped (their `tmdbCollection` is known); NEW parts of an existing collection are not added (open point).
73. Real data: STATUS.md, ticket #19.
75. ## Test
77. * Gate: `tests/franchises.mjs` (own storage `.scratch/franchise-store`, fixture `tests/seed-franchises.hl` on top of
78. `tests/seed-show.hl`, fake TMDB `collections`): seed + resume + pacing, widget (ends, client-side Sequel click, franchise
79. above), `/franchises`, index sort both ways (series by last episode), editor only for `TRACKER_EDITORS`, 390/1280 no
80. sideways scroll, screenshots with `TRACKER_GATE_SHOTS`.
81. * `tests/browser.mjs` runs with `TRACKER_COLLECTIONS=0` (its fake TMDB request counts must not see the seed).
82. * Real data: `tests/realdata-066.mjs` (procedure in STATUS.md).
84. ## Since the merge (mission 023 (old 070))
86. * Headings are #20's typed ones: "Franchises" (blueLight), "Franchise | <name>", "Timeline | <name>" (greenLight), also on the
87. timeline editor. Title links use `shows.hl titlePath` (`/movies/…`, `/series/…`, `/shows/…`).
88. * The seed waits for the daily sync, the adult backfill, the details repair, the kind backfill AND the credits job (one TMDB
89. pacing at a time): on the first start after the deploy it runs last (~32–37 min after the kind backfill's ~16–21 min).