03 - User Journeys (Houses Module)

• Journey 1 - Set up the house system (house admin)
• Journey 2 - Assign houses to new students (registrar)
• Journey 3 - Run inter-house event (teacher, forward-looking)
• Journey 4 - Retire a house (house admin)
• Journey 5 - Find a student's house (parent/student, forward-looking)
• Journey map

End-to-end journeys through the Houses module, mapped to exact endpoints. Each journey lists the screens (05), the API calls (12) and the state flow (13). Anything that requires a capability the backend does not expose is flagged (planned) / (forward-looking).

Journey 1 - Set up the house system (house admin)

Trigger: New academic year; school wants 4 color-coded houses.

1. Open Houses list (05 §1) → HouseListCubit.load() → GET /houses?page=1&limit=20 (houses.controller.ts:30-34). Empty state.
2. Tap New house → editor sheet (05 §3) → fill name, code, color, motto.
3. Submit → POST /houses (houses.controller.ts:24-28). Duplicate code → 409 House code "X" already exists. (houses.service.ts:19-21) shown inline.
4. Repeat for 3 more houses; list refreshes (natural createdAt order - backend applies no sort, houses.service.ts:30).
5. Edit a color next day → PATCH /houses/:id (houses.controller.ts:42-46). Note: PATCH reuses CreateHouseDto - name and code are required in the body (create-house.dto.ts:4-11), so the client must send the full set.

Exit criteria: 4 houses visible with distinct color cards.

Journey 2 - Assign houses to new students (registrar)

Trigger: Admission batch arrives; each student needs a house.

1. Create student with houseId → POST /students (student.controller.ts:38); field houseId optional IsMongoId (create-student.dto.ts:39-42).
2. Verify assignment: open student → house color shown (client resolves the house via cached list from GET /houses, 13 §6).
3. Wrong house? Update student → PATCH /students/:id with houseId (student.controller.ts:56, update-student.dto.ts:45-48).

Exit criteria: student record shows the house; house detail member count changes after refetch ((planned) server filter - today the client filters the students list, 09 §G1).

Journey 3 - Run inter-house event (teacher, forward-looking)

Trigger: Sports day; teacher needs house rosters and wants to see points.

1. Open house detail (05 §2) → GET /houses/:id (houses.controller.ts:36-40)
   • members (client join today, (planned) GET /houses/:id/members).
2. See per-house member counts; plan events.
3. Points & leaderboard: not available - no field/endpoint (planned); QR check-in (forward-looking).

Exit criteria: roster correct; gap logged to backend backlog.

Journey 4 - Retire a house (house admin)

Trigger: House discontinued mid-year.

1. Open detail → Delete → confirm dialog.
2. DELETE /houses/:id → soft delete (houses.service.ts:51-54, base.schema.ts:19-27).
3. Guard check: backend does NOT check assigned students (no 409) - students keep a dangling houseId (student.schema.ts:41-42) and the house vanishes from lists. Client must warn before delete and offer to clear houseId on members (planned) server-side cascade; QA coverage in 14 §4.

Exit criteria: house gone from list; admin notified of the reassignment debt.

Journey 5 - Find a student's house (parent/student, forward-looking)

Trigger: Parent wants to see child's house.

1. Child profile → house card (from student.houseId → GET /houses/:id).
2. Tap → house detail with color, motto, members (read-only).

Exit criteria: correct house shown; no write access.

Journey map

flowchart LR
    A[House list] -->|New| B[House editor]
    B -->|POST /houses| A
    A -->|tap| C[House detail]
    C -->|PATCH| B
    C -->|DELETE| A
    C -->|members planned| D[Member roster]
    E[Student form] -->|houseId POST/PATCH /students| C