03 — User Journeys (Rooms Module)
- 1. Journey: Create a room (Org Admin)
- 2. Journey: Find a room for timetable planning (Coordinator)
- 3. Journey: Edit a room — code conflict (Admin)
- 4. Journey: Delete a room (Admin)
- 5. Journey: Book a room
(planned)— forward-looking - 6. Journey: Offline / error handling (all)
End-to-end journeys through the Rooms module, each step mapped to the implemented API (
src/modules/rooms/**). Markings:(planned)= not in code yet,(forward-looking)= future surface,(proposed)= client-side contract.
1. Journey: Create a room (Org Admin)
| # | Step | Screen | API / source |
|---|---|---|---|
| 1 | Admin opens Room List (/rooms), taps FAB "New room" | Room Editor (create) | — |
| 2 | Fills name, code, capacity, type, building, facilities | Room Editor | CreateRoomDto fields (create-room.dto.ts:11-38) |
| 3 | Client validates: required name/code, capacity ≥ 1 (proposed) | Room Editor | server: @IsString/@IsNumber only (OQ-7) |
| 4 | Submits → POST /api/v1/rooms | Room Editor (loading) | rooms.controller.ts:24-28 |
| 5a | 201 → navigates to Room Detail, snackbar "Room created" | Room Detail | rooms.service.ts:18-23 |
| 5b | 409 duplicate code → inline error under code field, form kept | Room Editor | rooms.service.ts:19-21 |
| 5c | 400 → field errors mapped from envelope details[] | Room Editor | 00-shared/07 |
2. Journey: Find a room for timetable planning (Coordinator)
| # | Step | Screen | API / source |
|---|---|---|---|
| 1 | Opens /rooms | Room List | GET /api/v1/rooms?page=1&limit=20 (rooms.controller.ts:30-34) |
| 2 | Filters by type/building/capacity — client-side only today (proposed); server filter (planned) (OQ-3) | Room List (filter chips) | no query params in code |
| 3 | Scans cards for capacity badge; scrolls → hasNext → page+1 | Room List (infinite scroll) | pagination-query.dto.ts:32-39 |
| 4 | Taps room → detail with facilities list | Room Detail | GET /api/v1/rooms/:id (rooms.controller.ts:36-40) |
| 5 | Adds room to timetable entry | Timetable module (planned) | IMPLEMENTATION_PLAN.md:227 |
3. Journey: Edit a room — code conflict (Admin)
| # | Step | Screen | API / source |
|---|---|---|---|
| 1 | Opens /:id/edit, changes code to one that exists | Room Editor (edit) | PATCH rooms.controller.ts:42-46 |
| 2 | Gap: no 409 — $set runs, unique index raises E11000 → 500 (OQ-1) | Room Editor (error) | rooms.service.ts:42-46; room.schema.ts:38 |
| 3 | Server fix (planned): pre-check code → 409 "already exists", inline field error | Room Editor | — |
| 4 | Client today (proposed): block submit on duplicate-code async check, show inline hint | Room Editor | — |
| 5 | Success → snackbar + detail refreshed (version incremented, base.repository.ts:57-66) | Room Detail | — |
4. Journey: Delete a room (Admin)
| # | Step | Screen | API / source |
|---|---|---|---|
| 1 | Room Detail → menu → "Delete room" | Confirm dialog | — |
| 2 | Typed/confirm → DELETE /api/v1/rooms/:id | dialog (loading) | rooms.controller.ts:48-52 |
| 3a | 200 → row removed locally, snackbar "Room deleted" (soft delete) | Room List | rooms.service.ts:48-51; base.repository.ts:68-74 |
| 3b | 404 → snackbar "Room not found" (already deleted) | Room List | rooms.service.ts:50 |
| 4 | Gap: no in-use guard — deleting a room referenced by timetable/bookings succeeds silently (OQ-4); warning (planned) | — | rooms.service.ts:48-51 |
| 5 | Audit: deletedAt/deletedBy recorded | — | base.schema.ts:23-27 |
5. Journey: Book a room (planned) — forward-looking
| # | Step | Screen | API / source |
|---|---|---|---|
| 1 | Room Detail → "Book" (button (planned)) | Booking sheet | bookings module (planned) |
| 2 | Pick date/time slot; availability from booking module | Booking sheet | (planned) |
| 3 | Attendee scans QR at venue door → room info + session | QR screen (forward-looking) | (forward-looking) |
| 4 | Analytics (proposed): utilization per room → insights | Analytics (proposed) | (proposed) |
6. Journey: Offline / error handling (all)
- Reads: last-good cache + offline banner; writes blocked with "You're offline" (no module offline queue) — per 00-shared/06 §3.6.
- 401 → refresh → replay → session expiry.
- 403 (future server RBAC) → hide route/redirect to 403 screen (client already gates by
rooms.*perms — OQ-2).