Add guided tours and unify left-to-right hall wall hang.

Visitors walk published tours in a 3D hall with stop notes; curators edit drafts via Tour editor. All galleries (artist, movement, tour) place the first work left of the entrance view and the last on the right. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-16 20:27:36 +03:00
parent 48bd17e985
commit 5ddc3fd7f0
31 changed files with 1890 additions and 124 deletions
@@ -0,0 +1,47 @@
+# Guided tours
+
+Curated walkthroughs of selected paintings. Visitors open **Tours** on the timeline, pick a published tour, and walk a 3D hall (`VirtualGallery` mode `tour`). Opening a frame shows stop notes on painting detail; prev/next follow tour order.
+
+## Status
+
+| Status | Who sees it |
+|--------|-------------|
+| `draft` | Curators only (Tour editor + `GET /api/tours/:id` when signed in) |
+| `published` | Everyone via Tours popup + public API |
+
+Tour stop **body** text is English-only in v1 (stored on `tour_stops.body`). UI chrome is EN/RU via i18n.
+
+## Data model
+
+Migration: `db/migrate-tours.sql` (applied by `npm run dev:migrate`).
+
+| Table | Role |
+|-------|------|
+| `tours` | Title, description, `status`, optional `cover_painting_id` |
+| `tour_stops` | Ordered stops: `tour_id`, `painting_id`, `sort_order`, `body` (unique per tour+painting) |
+
+Included in `scripts/harmonize-db.js` catalog sync.
+
+## Curator editor
+
+Home header → **Tour editor** (curators). Create tours, set draft/published, search-add paintings, reorder, edit stop text, save.
+
+## Visitor flow
+
+1. Timeline → **Tours** → modal of published tours  
+2. Select tour → `GET /api/tours/:id` → winged 3D hall (left wall first → right wall last, stop order preserved)  
+3. Click frame → painting detail with tour notes + stop-ordered navigation  
+4. Back / hall exit → timeline  
+
+Hall hang rules match artist and movement galleries — see [basics.md — Virtual gallery](basics.md#virtual-gallery-3d-halls).
+
+## API
+
+See [API.md](API.md#tours). Audit actions: `tour.create`, `tour.update`, `tour.delete`, `tour.stops`.
+
+## Out of scope (v1)
+
+- Russian tour body translations  
+- Auto-generated / AI tours  
+- Audio or timed slideshow  
+- Editing tours from painting detail