# Eventsa — Backend Patch 02: Registration & Attendance Scope

**Base:** `eventsa-backend-p0-fixed-2026-09-16`, AFTER `eventsa-backend-patch-01-site-content.zip`.
**Frontend:** compatible with `eventsa-frontend` through Patch 10. This ZIP contains ONLY Backend files.

## What changes

1. `attendees` / `Attendee` administrative endpoints: tenant site enforced by the server; `super` may view all sites or filter to one. Validates page sizes; fixes omitted `status` filter so it no longer erroneously becomes `null`.
2. `attendeesApi`: participant/judge sees only their own registrations, ignoring any client-supplied user identity. Administrative callers receive the scoped administrative view.
3. `createAttendee`: only tenant/super may administratively create. Selected user, program, and Site must match; user/program must be active; duplicate requests are rejected. This DOES NOT implement customer checkout, online payment validation, or companion purchases.
4. `updateAttendee`: only status can change. `removeAttendee`: soft-disable instead of deleting financial/audit history.
5. `scans` / `scan`: manager-only reads, server site scope and validated page bounds. `createScan` checks confirmed registration, site, selected program and check-in/check-out order. Generic update/delete are disabled to protect records.
6. `userTimelines`: scoped to the logged-in administrator's site. The global `timelines` query is now reserved for `super` accounts.
7. Timeline attendance mutations validate actual registration and program, enforce site and staff role, disallow a second open entry and checkout without a preceding entry. Bulk operations are awaited rather than launching unobserved async callbacks. Unscoped generic timeline create/update/delete are disabled.
8. No new npm dependency and no DB migration. Existing GraphQL operation names and primary shapes remain the same.

## Installation (Mac / Windows via VS Code Terminal)

**BACK UP the Backend and PostgreSQL DB first.** Extract into the existing Backend directory, NOT `eventsa-frontend`:

```bash
cd "/PATH/TO/eventsa-backend-p0-fixed-2026-09-16"
unzip -o "$HOME/Downloads/eventsa-backend-patch-02-registration-attendance.zip" -d .
npm run build
npm run test:regression -- --runTestsByPath regression/registration-attendance-scope.spec.ts
npm run start:dev
```

Before restarting any running Backend process, shut it down normally. Do not run migrations; none are included.

## Critical manual checks

- Tenant A: open `/office/attendees` and `/office/attendance`, confirm they show only A's records.
- Tenant A: request B's `siteid`, attendee ID, or scan ID: access must be denied.
- Participant: `attendeesApi` must return only their own registrations. Manager-only list and attendance writes must be denied.
- Staff: recording attendance requires an active registration for exactly the chosen seminar/workshop/service and the same Site. Duplicate check-in, checkout without prior check-in, invalid type and cross-site attendees must be denied.
- Existing Office reporting must still read `userTimelines` correctly. Global `timelines` is super-only.
- Ordinary `removeAttendee` now deactivates the registration; it no longer erases the record. Generic `createTimeline`, `updateTimeline`, `removeTimeline`, `updateScan`, `removeScan` intentionally deny the request.

## Known limits — do not claim production readiness yet

- Older purchase paths (`buyEvent`, `buySeminar`, `buyWorkshop`, `buyService` and related code) may still reach the internal `AttendeesService.create()` and need a **separate payment/stock/tenant audit**. This patch **does not enable customer checkout**. No paid registration must be treated as final before verified payment.
- One direct `createScan` call records an audit scan, not a matching timeline session. Use dedicated `checkin`/`checkout` for accurate time-based attendance reports.
- Check-in and scan writes are not yet one database transaction, and duplicate registrations are not protected by a database unique constraint. Concurrent/parallel requests need further hardening.
- Bulk attendance validates the whole request first but is not atomic; an unexpected DB failure can leave a partial batch. Run on staging before production.
- Unit-like static/behavior checks done for patch generation are **not substitutes** for NestJS compilation, full Jest regression, and DB-backed integration tests on your environment.

## Patch file inventory

```
src/auth/registration-scope.ts                  NEW
src/atendees/atendees.service.ts                 REPLACE
src/atendees/atendees.resolver.ts                REPLACE
src/atendees/atendees.api.resolver.ts            REPLACE
src/atendees/atendees.module.ts                  REPLACE
src/scans/scans.service.ts                       REPLACE
src/scans/scans.resolver.ts                      REPLACE
src/scans/scans.module.ts                        REPLACE
src/timelines/timelines.service.ts               REPLACE
src/timelines/timelines.resolver.ts              REPLACE
regression/registration-attendance-scope.spec.ts NEW
```

No file from Backend Patch 01 is replaced in this ZIP.