feat: document Week 4 backend changes including 404 and BAD_REQUEST handling, user read endpoint, and OpenAPI updates

Author: ArchILLtect

docs/weekly-plan/week-4/week-4-checkout-backend.md

@@ -0,0 +1,73 @@
+# Week 4 Checkout Summary — Backend
+
+## Overview (Week 4 — late October)
+1. ### Standardized NOT_FOUND semantics
+   - Introduced `ResourceNotFoundException` in the common layer and mapped it in `GlobalExceptionHandler` to HTTP 404 with error code `NOT_FOUND`.
+   - Services throw the exception; controllers remain thin and rely on the centralized handler.
+   - Added tests: service unit test for missing user and WebMvc test asserting the 404 envelope.
+
+2. ### BAD_REQUEST mapping coverage
+   - Added a focused WebMvc test to assert `IllegalArgumentException` is translated to HTTP 400 with `{ "error": "BAD_REQUEST" }`.
+   - Keeps error envelope consistent and prevents controller-specific ad hoc responses.
+
+3. ### Endpoint hardening for future admin/public profiles
+   - Added a gated user read endpoint `GET /users/{id}` returning `PublicUserDto` (no email or sensitive fields).
+   - Endpoint is disabled by default; enable with `sameboat.endpoints.user-read=true`.
+   - Access control: only the authenticated user (self) or `ADMIN` may fetch. Tests are present but disabled until the feature is enabled for real environments.
+
+4. ### OpenAPI & Docs
+   - Updated `openapi/sameboat.yaml` to include `/api/version` and a reusable `ErrorResponse` schema enumerating current error codes (`UNAUTHENTICATED`, `BAD_CREDENTIALS`, `SESSION_EXPIRED`, `VALIDATION_ERROR`, `BAD_REQUEST`, `RATE_LIMITED`, `NOT_FOUND`, `INTERNAL_ERROR`).
+   - `docs/Architecture.md`: added a Week 4 Backend Summary with the above items.
+   - README: added Week 4 highlights, Windows `mvn` quoting note, and included `NOT_FOUND` in error catalog table.
+
+5. ### Tests & Quality Gates
+   - All tests pass locally (migration Testcontainers profile skipped without Docker).
+   - JaCoCo instruction coverage: ~84% total (gate ≥ 70% remains green).
+
+## Key Decisions & Rationale
+- Centralize 404 behavior via a domain exception to reduce controller boilerplate and ensure consistent envelopes.
+- Keep cross-user reads gated and least-privilege by default; only self or `ADMIN` can fetch when feature is enabled.
+- Public profile DTO excludes email to reduce PII exposure; future public profile endpoint can reuse the same DTO or an even slimmer one.
+
+## What Went Well
+- Layering preserved (Controller → Service → Repository). Controllers remain thin and secure.
+- Focused tests captured envelope behavior for both NOT_FOUND and BAD_REQUEST without bloating integration suites.
+- OpenAPI is back in sync, making frontend consumption clearer.
+
+## What I Struggled With
+- Security slices in WebMvc tests required explicit authentication setup; solved with `@WithMockUser` or session cookie when appropriate.
+- Property-gated endpoint meant careful test enable/disable to keep the suite green by default.
+
+## Suggested Next Steps (Backend)
+- When bringing up the admin console:
+  - Enable `sameboat.endpoints.user-read=true` in admin/staging environments.
+  - Add role-based method security (`@EnableMethodSecurity`) and migrate inline checks to `@PreAuthorize`.
+  - Add integration tests for `403` (non-self, non-admin) and `200` for admin fetching other users.
+- Consider adding a dedicated public profile route (e.g., `/profiles/{id}`) with no auth but constrained DTO.
+- Continue ratcheting coverage toward 75% by adding small unit tests (e.g., more `UserService` edge cases, filter behaviors).
+
+## Verification (Local)
+- Run fast tests (Windows cmd):
+```cmd
+mvn "-Dskip.migration.test=false" test
+```
+- Full verify (tests + coverage gate):
+```cmd
+mvn "-Dskip.migration.test=false" verify
+```
+- Optional migration schema test (requires Docker/Testcontainers):
+```cmd
+mvn -Pwith-migration-test test
+```
+
+## Checklist (Backend Focus)
+- [x] ResourceNotFoundException + 404 mapping in GlobalExceptionHandler
+- [x] Service method throws on missing resource and unit test
+- [x] WebMvc test for NOT_FOUND envelope
+- [x] Focused BAD_REQUEST mapping test (`IllegalArgumentException`)
+- [x] OpenAPI sync with `/api/version` and error schema
+- [x] Architecture.md Week 4 summary
+- [x] README updated (Week 4 highlights, Windows mvn note, error catalog includes NOT_FOUND)
+- [x] Coverage gate ≥ 70% (current ~84%)
+- [x] Gated `GET /users/{id}` returning `PublicUserDto`; access: self or ADMIN; disabled by default
+

docs/weekly-plan/week-4/week-4-plan-backend.md

@@ -0,0 +1,21 @@
+# Week 4 – Backend Plan (Checklist)
+
+Context: Backend-only items extracted from the Week 4 plan. Status as of 2025-10-29.
+
+## Done
+- [x] Environment onboarding: `.env.example` present at repo root and referenced in README (copy to `.env` for local runs).
+- [x] CI pipeline (BACKEND_CI_GUARD): `.github/workflows/backend-ci.yml` runs migration immutability check, `mvn verify` (unit + integration tests), JaCoCo coverage gate (≥ 70%), and a Flyway schema test profile step.
+- [x] Auth hardening: password complexity validation, in-memory login rate limiting returning `RATE_LIMITED` on abuse, and scheduled session pruning job.
+- [x] Public endpoints: `GET /health`, `GET /actuator/health`, and `GET /api/version` implemented and covered by integration tests.
+- [x] Profiles & CORS: `dev` vs `prod` profiles with secure cookie/domains in prod; CORS allowlist configured (credentials enabled, no wildcards).
+- [x] Flyway migrations: schema aligned with `UserEntity` (e.g., timezone column) via a new migration; historical migrations protected by immutability scripts.
+- [x] NOT_FOUND mapping: Added `ResourceNotFoundException`, mapped to 404 in `GlobalExceptionHandler`, service method `UserService.getByIdOrThrow(UUID)`, gated `GET /users/{id}` uses it when enabled; tests added (service + WebMvc 404 envelope).
+- [x] BAD_REQUEST mapping test: Focused WebMvc test asserting `IllegalArgumentException` → `{ "error": "BAD_REQUEST" }`.
+- [x] OpenAPI sync: `openapi/sameboat.yaml` updated to include `/api/version` and `ErrorResponse` schema with current error codes; brief Week 4 backend summary added to `docs/Architecture.md`.
+- [x] Coverage gate: verified JaCoCo ≥ 70% (current ~84%).
+
+## Left (Backend-focused)
+- [ ] None for Week 4. Carryovers: raise coverage target to 75% in a future cycle; enable gated `/users/{id}` when admin/public profile work lands.
+
+## Scope Notes
+- Excluded (frontend-only): health polling backoff/pause, reduced-motion accessibility controls, debug panel utilities, identicon fallback, and visibility-driven session refresh.

docs/weekly-plan/week-4/week-4-plan-draft.md

@@ -16,6 +16,27 @@ Theme (Proposed): Quality hardening, accessibility polish, developer ergonomics,
 | Visual polish (avatars)               | Clarity in demos                  | Deterministic identicon fallback implemented                 |
 | Session freshness                     | Better long-lived tab UX          | Visibility change triggers conditional refresh               |
 
+## Week 4 Status Checklist (as of 2025-10-29)
+
+Notes:
+- This repository is the backend (Spring Boot). Several Week 4 items target the frontend app (Vite/React) and its CI; those remain pending here and should be tracked/completed in the frontend repo.
+- BACKEND_CI_GUARD respected: main backend CI workflow exists at `.github/workflows/backend-ci.yml`.
+
+Done
+- [x] Environment onboarding (backend scope): `.env.example` is present at repo root and referenced in README “Run locally” section (copy `.env.example` → `.env`).
+- [x] CI (backend scope): Backend CI already runs tests (`mvn verify`) and fails on red; coverage gate enforced (JaCoCo ≥ 70%).
+
+Left (to be completed, mostly frontend scope unless noted)
+- [ ] Testing & CI (frontend): Add `npm test` step to the frontend CI (`frontend-ci.yml`) before build; add routing/auth UI tests listed below.
+- [ ] Health polling resilience (frontend): pause-on-error, exponential backoff, debug surface for failure streak/last success.
+- [ ] Accessibility / Motion control (frontend): central reduced‑motion preference, gate animations, document approach in `Architecture.md` (Week 4 section).
+- [ ] Developer control utilities (frontend): debug panel interval override, failure/backoff display, “Force full auth refresh” button.
+- [ ] Visual / UX polish (frontend): deterministic identicon fallback, copy‑to‑clipboard user ID, spacing sweep.
+- [ ] Session freshness (frontend): `visibilitychange`-based conditional refresh with overlap safeguards.
+- [ ] Documentation: Add Week 4 summary in `docs/Architecture.md`; update any week‑3 links if metrics scripts change; consider short CHANGELOG segment if scope grows.
+
+---
+
 ## Detailed Tasks (Initial Backlog)
 
 ### 1. Testing & CI