diff --git a/.gitignore b/.gitignore index c000110..a9aa43c 100644 --- a/.gitignore +++ b/.gitignore @@ -29,3 +29,11 @@ Thumbs.db # Large data files (import manually) restaurants.json + +# Generated output +graphify-out/ + +# Planning/tooling artifacts +org/ +.planning/ +.claude/ diff --git a/.planning/.next-call-count b/.planning/.next-call-count deleted file mode 100644 index 0cfbf08..0000000 --- a/.planning/.next-call-count +++ /dev/null @@ -1 +0,0 @@ -2 diff --git a/.planning/PROJECT.md b/.planning/PROJECT.md deleted file mode 100644 index f613660..0000000 --- a/.planning/PROJECT.md +++ /dev/null @@ -1,113 +0,0 @@ -# Restaurant Hygiene Control App - -## What This Is - -A web application that connects restaurant hygiene controllers and customers around NYC inspection data. Controllers file internal inspection reports (violations, grades, photos, follow-up status) for restaurants. Customers search for restaurants and instantly see their hygiene grade and cleanliness score. Built on top of a Spring Boot API already syncing data from the NYC Open Data API. - -## Core Value - -A customer can search any NYC restaurant and immediately know whether it's clean — and a controller can document new hygiene findings against the same data. - -## Current State - -**v3.0 in progress — Phase 14 complete (2026-04-12)** - -Phase 14 (testcontainers-integration-tests) complete. TEST-04/05/06 validated. Replaced live-DB integration tests with Testcontainers: -- RestaurantDAOIT: 15 tests against real mongo:7.0 container (TC 1.20.1) -- UserRepositoryIT: 4 tests against postgres:15-alpine + mongo:7.0 containers -- AppConfig tier-0 System.getProperty() lookup enables container URI injection -- Full suite: 165 Surefire + 15 + 4 IT = BUILD SUCCESS, no external services needed - -**Shipped: v2.0 — Full Product (2026-04-11)** - -All 10 phases complete. 36/36 requirements validated. The app is a fully deployed Spring Boot monolith with: -- Dual-role auth (CUSTOMER / CONTROLLER / ADMIN) via JWT -- Controller dashboard: report filing, inline edit, photo upload -- Public analytics page: city-wide KPIs, borough breakdown, cuisine rankings, at-risk list -- Dual landing/home routing (anonymous vs. authenticated `/`) -- Persistent navbar across all 10 pages + `/profile` page -- Map filters (grade/borough/cuisine), `/uncontrolled` tracker, nearby restaurants, sort controls -- UX polish: pagination (20/page), skeleton loading, toast notifications, mobile responsive -- Admin tools: sync controls, at-risk CSV export, aggregate report stats - -## Requirements - -### Validated (v1.0 — shipped 2026-04-01) - -- ✓ NYC Open Data API sync into MongoDB -- ✓ Restaurant data queryable by borough, cuisine, score, grade -- ✓ JWT authentication (register, login, refresh) -- ✓ User accounts in PostgreSQL -- ✓ Redis TTL cache for expensive analytics queries -- ✓ REST API with Swagger documentation -- ✓ Web dashboard with HTML templates (ViewController) -- ✓ Separate controller registration (signup code) -- ✓ Role-based access control (CUSTOMER / CONTROLLER roles) -- ✓ Controller can create, view, edit inspection reports with photos -- ✓ Customer can search restaurants and see hygiene grade + inspection history -- ✓ Customer can browse restaurants on an interactive map -- ✓ Customer can bookmark restaurants - -### Validated (v2.0 — shipped 2026-04-11) - -- ✓ Controller dashboard UI (status tabs, report cards, inline edit, photo thumbnails) -- ✓ Public analytics page (KPIs, borough distribution, cuisine rankings, at-risk list) -- ✓ Dual landing/home routing based on auth state -- ✓ Persistent navbar across all pages + `/profile` page -- ✓ Map filters (grade, borough, cuisine) — client-side, no reload -- ✓ `/uncontrolled` page (C/Z grade or >12 months without inspection) + CSV export -- ✓ Nearby restaurants section on detail page -- ✓ Sort control on search results -- ✓ Pagination (20 items/page), skeleton loading, toast notifications, mobile responsive -- ✓ Admin tools: sync controls, CSV export, aggregate report stats (ADMIN role) - -### Deferred to v3 - -- Report status notifications to admin -- Cross-controller report view (admin) -- Bulk photo upload -- Real-time notifications for bookmarked restaurant updates -- Hygiene trends over time -- Admin manages controller accounts -- PDF export of reports - -### Out of Scope - -- Pushing controller reports to NYC Open Data API — no write access -- Customer-visible controller reports — internal only -- Mobile native app — web-first -- Multi-city support — NYC only -- Object storage for photos (S3, GCS) — Docker volume sufficient - -## Context - -Production-grade Spring Boot 4.0.5 monolith (upgraded in Phase 21): -- MongoDB for restaurant/inspection data (`mongodb-driver-sync`, raw aggregation pipelines) -- PostgreSQL for users/bookmarks/reports (Spring Data JPA) -- Redis 7 for caching (TTL 3600s) -- JWT security (15-min access / 7-day refresh tokens) -- Deployment: Docker Compose (4 containers: app, MongoDB, Redis, Postgres) - -## Constraints - -- **Tech stack**: Java 25, Spring Boot 4.0.5, JUnit 5 — no framework upgrade beyond Phase 21 -- **Database**: MongoDB for restaurant data, PostgreSQL for user/report metadata -- **Auth**: JWT — extend existing system, don't replace -- **NYC API**: Read-only -- **Academic**: Academic project (Aflokkat / big data module) - -## Key Decisions - -| Decision | Rationale | Outcome | -|----------|-----------|---------| -| Controller reports stored in PostgreSQL (JPA) | Structured relational data, fits existing JPA layer | ✓ Validated | -| Role field added to UserEntity | Simplest extension of existing auth — no new table | ✓ Validated | -| Controller signup via registration code | Prevents open public access to filing reports | ✓ Validated | -| Customer UI extends existing ViewController | Reuses Thymeleaf template infrastructure | ✓ Validated | -| Navbar auth state fully JS-driven | Stateless JWT app has no server session for Thymeleaf Security | ✓ Validated | -| anyRequest().permitAll() with client-side IIFE guards for /admin, /dashboard | Browser navigation does not send Authorization header | ✓ Validated | -| uploadPhoto uses raw fetch() (not fetchWithAuth) | fetchWithAuth sets Content-Type: application/json, corrupts multipart boundary | ✓ Validated | -| ADMIN role separate from CONTROLLER | Admin-specific signup code, separate DataSeeder seed user | ✓ Validated | - ---- -*Last updated: 2026-04-13 — Phase 21 complete (Spring Boot 4.0.5, Java 25, JUnit 5)* diff --git a/.planning/REMAINING_PHASES.md b/.planning/REMAINING_PHASES.md deleted file mode 100644 index f7717af..0000000 --- a/.planning/REMAINING_PHASES.md +++ /dev/null @@ -1,531 +0,0 @@ -# Remaining Phases — v3.0 Production Readiness - -> Handoff document for milestone completion without GSD tooling. -> Generated: 2026-04-15 | Branch: gsd/phase-16-security-hardening - ---- - -## Status Summary - -| Phase | Description | Status | Plans left | -|-------|-------------|--------|------------| -| 16 | Security Hardening | **In Progress** | 1 plan (16-03) | -| 17 | Code Quality & MongoDB Indexing | Not started | TBD | -| 18 | E2E Tests (Playwright) | Not started | TBD | -| 19 | Unit & Controller Tests | Not started | TBD | -| 20 | UI Visual Redesign | Not started | TBD | -| 21 | Java 25 / Spring Boot 4.0.5 upgrade | **Complete** | — | - -After Phase 20, the milestone v3.0 is complete and the project is ready for deployment. - ---- - -## Phase 16 — Security Hardening (In Progress) - -**Branch:** `gsd/phase-16-security-hardening` -**Plans done:** 16-01 ✅ 16-02 ✅ 16-04 ✅ — **16-03 remaining** - -### Plan 16-03 — Bean Validation on Auth DTOs - -**Goal:** Reject empty credentials at the controller layer before they reach `AuthService`. - -#### Files to modify - -| File | Change | -|------|--------| -| `pom.xml` | Add `spring-boot-starter-validation` dependency | -| `src/main/java/com/aflokkat/dto/AuthRequest.java` | `@NotBlank` on `username`, `password` | -| `src/main/java/com/aflokkat/dto/RegisterRequest.java` | `@NotBlank` on `username`, `password`; `@NotBlank @Email` on `email` | -| `src/main/java/com/aflokkat/dto/RefreshRequest.java` | `@NotBlank` on `refreshToken` | -| `src/main/java/com/aflokkat/controller/AuthController.java` | Add `@Valid` before each `@RequestBody` param (3 methods) | -| `src/main/java/com/aflokkat/controller/GlobalExceptionHandler.java` | **Create** — `@RestControllerAdvice` returning `{status, message, timestamp}` on HTTP 400 | - -#### pom.xml addition (inside ``, after security block) - -```xml - - org.springframework.boot - spring-boot-starter-validation - -``` - -#### GlobalExceptionHandler.java (create) - -```java -package com.aflokkat.controller; - -import org.springframework.http.HttpStatus; -import org.springframework.web.bind.MethodArgumentNotValidException; -import org.springframework.web.bind.annotation.ExceptionHandler; -import org.springframework.web.bind.annotation.ResponseStatus; -import org.springframework.web.bind.annotation.RestControllerAdvice; - -import java.time.Instant; -import java.util.Map; -import java.util.stream.Collectors; - -@RestControllerAdvice -public class GlobalExceptionHandler { - - @ExceptionHandler(MethodArgumentNotValidException.class) - @ResponseStatus(HttpStatus.BAD_REQUEST) - public Map handleValidation(MethodArgumentNotValidException ex) { - String message = ex.getBindingResult().getFieldErrors().stream() - .map(fe -> fe.getField() + " " + fe.getDefaultMessage()) - .collect(Collectors.joining(", ")); - return Map.of( - "status", "error", - "message", message, - "timestamp", Instant.now().toString() - ); - } -} -``` - -#### Verification - -```bash -mvn test -Dtest=AuthControllerValidationTest,GlobalExceptionHandlerTest -q -# Expected: exit 0 (5 + 3 = 8 tests GREEN) - -mvn test -q -# Expected: exit 0 (full suite, no regression) -``` - -#### Success criteria - -- `grep -c "spring-boot-starter-validation" pom.xml` → 1 -- `grep -c "@NotBlank" src/main/java/com/aflokkat/dto/AuthRequest.java` → 2 -- `grep -c "@NotBlank" src/main/java/com/aflokkat/dto/RegisterRequest.java` → 3 -- `grep -c "@Email" src/main/java/com/aflokkat/dto/RegisterRequest.java` → 1 -- `grep -c "@Valid" src/main/java/com/aflokkat/controller/AuthController.java` → 3 -- `test -f src/main/java/com/aflokkat/controller/GlobalExceptionHandler.java` - -#### After completing Phase 16 - -1. Run `mvn test -q` — full suite must be GREEN -2. Commit: `feat(16): input validation — Bean Validation on auth DTOs, GlobalExceptionHandler` -3. Merge `gsd/phase-16-security-hardening` → `develop` → `main` -4. Update `CHANGELOG.md`: - ``` - ### Phase 16: Security Hardening (2026-04-15) - - Explicit CORS policy (CorsConfigurationSource bean + http.cors) - - Security headers (X-Content-Type-Options, X-Frame-Options, etc.) - - Bean Validation on auth DTOs (@NotBlank, @Email) + GlobalExceptionHandler - - Rate limiting extended to restaurant endpoints (separate bucket from auth) - ``` - ---- - -## Phase 17 — Code Quality & MongoDB Indexing - -**Depends on:** Phase 16 complete - -### Goal - -Dead code removed, all endpoints documented in Swagger, error responses uniform, MongoDB queries use indexes. - -### Key tasks - -#### 1. Dead code audit - -Search for and remove unused classes/endpoints. Candidate areas: -- `ResponseUtil` — verify all callers use consistent response shape -- Any controller/service method not reachable from any frontend or API - -#### 2. OpenAPI / Swagger completion - -Every controller endpoint must have: -- A `@Tag` annotation on the controller class (groups in Swagger UI) -- `@Operation(summary = "...")` on each method -- `@ApiResponse` for at least 200 and error codes -- `@SecurityRequirement(name = "Bearer")` on authenticated endpoints - -Check: `http://localhost:8080/swagger-ui.html` — every endpoint visible, grouped, with lock icons on secured ones. - -#### 3. ResponseUtil consistency - -Ensure all error responses (400, 401, 403, 404, 429, 500) return JSON `{status, message, timestamp}`. -- `GlobalExceptionHandler` (created in Phase 16) handles 400 validation errors -- Add `@ExceptionHandler` entries for 404 (`NoHandlerFoundException`) and 500 (`Exception`) if missing - -#### 4. MongoDB indexes at startup - -In `MongoClientFactory` or a `@PostConstruct` method in a config bean, create indexes on the `restaurants` collection: - -```java -// Index for search by borough and cuisine -collection.createIndex(Indexes.ascending("boro", "cuisine_description")); -// Index for score queries -collection.createIndex(Indexes.ascending("camis")); -// Index for grade filter -collection.createIndex(Indexes.ascending("grades.grade")); -``` - -#### Verification - -```bash -# Swagger: all endpoints documented -curl http://localhost:8080/v3/api-docs | jq '.paths | keys | length' - -# Error response shape: 404 returns structured JSON -curl http://localhost:8080/api/restaurants/nonexistent | jq '.status, .message, .timestamp' - -# Index verification (against running MongoDB) -mvn test -Dtest=RestaurantDAOIT -q -# explain() output shows IXSCAN not COLLSCAN -``` - -#### Success criteria - -1. Swagger UI shows every endpoint with tag, description, response codes, and lock on secured endpoints -2. Every error response (400–500) returns `{status, message, timestamp}` — no Spring whitepage -3. MongoDB `explain()` on restaurant search shows `IXSCAN` -4. No dead code from `CLEANUP.md` remains (grep returns 0 matches) -5. Restaurant list DAO returns projected fields only (not full documents) - ---- - -## Phase 18 — E2E Tests (Playwright) - -**Depends on:** Phase 17 complete, Phase 13 Docker health checks - -### Goal - -Automated browser tests covering 4 critical flows, running in CI against a live `docker compose` stack. - -### Setup - -Add Playwright dependency to `pom.xml` (pinned at `1.49.0` per project constraints): - -```xml - - com.microsoft.playwright - playwright - 1.49.0 - test - -``` - -### Test flows to implement - -| Test class | Flow | Assertions | -|------------|------|------------| -| `LoginE2ETest` | Valid login → redirect to home | URL contains `/home` or `/` | -| `LoginE2ETest` | Invalid login → error message | Error element visible | -| `SearchE2ETest` | Search restaurant by name | Results list non-empty | -| `MapE2ETest` | Open map page | Map container renders (no JS error) | -| `DashboardAccessE2ETest` | CUSTOMER JWT → `/dashboard` blocked | Redirect or error visible | - -### Auth pattern for Playwright - -```java -// Do NOT use storageState() — app uses localStorage JWT -APIRequestContext api = playwright.request().newContext(...); -APIResponse loginResp = api.post("/api/auth/login", RequestOptions.create() - .setData(Map.of("username", "controller1", "password", "password"))); -String token = new JSONObject(loginResp.text()).getString("accessToken"); - -page.addInitScript("window.localStorage.setItem('accessToken', '" + token + "')"); -page.navigate(baseUrl + "/dashboard"); -``` - -### CI integration (`.github/workflows/ci.yml`) - -Update the `e2e` job (currently placeholder) to: -1. Run `docker compose up -d` -2. Wait for health: `curl --retry 10 --retry-delay 3 http://localhost:8080/api/restaurants/health` -3. Run `mvn failsafe:integration-test -Pe2e` -4. Run `docker compose down` - -Set `NYC_API_MAX_RECORDS=200` in the E2E compose env to cap sync to ~10s. - -#### Success criteria - -1. `mvn failsafe:integration-test -Pe2e` runs all 5 tests and reports pass/fail per test -2. CI `e2e` job boots full stack, runs tests, tears down without orphaned containers -3. Login test covers both valid and invalid credential scenarios -4. Dashboard test confirms CUSTOMER role cannot access `/dashboard` - ---- - -## Phase 19 — Unit & Controller Tests - -**Depends on:** Phase 12 (JaCoCo argLine fix in place) - -### Goal - -Service-layer and controller-layer covered by fast (no Spring context) tests. - -### Unit tests to add (Mockito, no Spring context) - -#### `AuthServiceTest` - -| Test | Description | -|------|-------------| -| `register_success` | Mock `UserRepository.existsByUsername` returns false → user saved, no exception | -| `register_duplicateUsername` | Mock returns true → throws `RuntimeException` | -| `login_validCredentials` | Mock `UserRepository.findByUsername` + `BCryptPasswordEncoder.matches` → returns `JwtResponse` | -| `login_invalidPassword` | `matches` returns false → throws exception | -| `refresh_validToken` | Mock `JwtUtil.validateRefreshToken` true → returns new `JwtResponse` | - -#### `RestaurantServiceTest` - -| Test | Description | -|------|-------------| -| `search_delegatesToDAO` | Verify `RestaurantDAO.search(...)` called with correct params | -| `stats_returnsCachedValue` | Mock cache hit → `RestaurantDAO.getStats()` NOT called | -| `byBorough_delegatesToDAO` | Verify `RestaurantDAO.countByBorough()` called | - -### Controller slice tests (`@WebMvcTest`) - -#### `AuthControllerTest` - -```java -@WebMvcTest(AuthController.class) -// Mock: AuthService -``` - -| Test | Expected | -|------|----------| -| `POST /api/auth/login` valid body | HTTP 200, body has `accessToken` | -| `POST /api/auth/login` empty password | HTTP 400 (Bean Validation — from Phase 16) | -| `POST /api/auth/register` valid body | HTTP 200 | -| `POST /api/auth/refresh` valid body | HTTP 200 | - -#### `RestaurantControllerTest` - -```java -@WebMvcTest(RestaurantController.class) -// Mock: RestaurantService -``` - -| Test | Expected | -|------|----------| -| `GET /api/restaurants/by-borough` | HTTP 200, JSON array | -| `GET /api/restaurants/stats` | HTTP 200, JSON object | -| `GET /api/restaurants/health` | HTTP 200 | - -#### `InspectionControllerTest` and `UserControllerTest` - -Similar pattern — mock service, assert HTTP status and response JSON shape. - -### Coverage target - -After Phase 19, run `mvn jacoco:report` and verify line coverage >= current baseline (38% per Phase 12). -Goal: reach at least 50% with new tests. - -#### Success criteria - -1. `mvn test -q` passes all existing + new tests with zero failures -2. `AuthService` and `RestaurantService` have Mockito unit tests covering register/login/refresh and search/stats/byBorough -3. `@WebMvcTest` tests exist for `AuthController`, `RestaurantController`, `InspectionController`, `UserController` -4. JaCoCo line coverage >= 50% - ---- - -## Phase 20 — UI Visual Redesign - -**Depends on:** Phase 18 (E2E test class names must not silently break) - -### Goal - -All 13 application pages share a dark/neutral design system. CSS tokens, unified component classes, animated grade badges, Lucide SVG icons. - -### Design tokens (create `src/main/resources/static/css/design-system.css`) - -```css -:root { - /* Colors */ - --bg-primary: #0f0f0f; - --bg-secondary: #1a1a1a; - --bg-card: #242424; - --text-primary: #f5f5f5; - --text-secondary:#a0a0a0; - --accent: #3b82f6; /* blue-500 */ - --accent-hover: #2563eb; /* blue-600 */ - --error: #ef4444; - --success: #22c55e; - --warning: #f59e0b; - - /* Grade badge colors */ - --grade-a: #22c55e; - --grade-b: #f59e0b; - --grade-c: #ef4444; - --grade-z: #6b7280; - - /* Spacing */ - --space-1: 0.25rem; - --space-2: 0.5rem; - --space-4: 1rem; - --space-6: 1.5rem; - --space-8: 2rem; - - /* Radius */ - --radius-sm: 4px; - --radius-md: 8px; - --radius-lg: 12px; - - /* Typography */ - --font-sans: 'Inter', system-ui, -apple-system, sans-serif; - --font-mono: 'JetBrains Mono', 'Fira Code', monospace; -} -``` - -### Shared component classes - -```css -.card { - background: var(--bg-card); - border: 1px solid #2a2a2a; - border-radius: var(--radius-md); - padding: var(--space-4); -} - -.btn-primary { - background: var(--accent); - color: var(--text-primary); - border: none; - border-radius: var(--radius-sm); - padding: var(--space-2) var(--space-4); - cursor: pointer; - transition: background 0.2s; -} - -.btn-primary:hover { background: var(--accent-hover); } - -.grade-badge { - display: inline-flex; - align-items: center; - justify-content: center; - width: 2rem; - height: 2rem; - border-radius: 50%; - font-weight: bold; - animation: fadeSlideIn 0.3s ease-out; -} - -.grade-a { background: var(--grade-a); color: #fff; } -.grade-b { background: var(--grade-b); color: #fff; } -.grade-c { background: var(--grade-c); color: #fff; } -.grade-z { background: var(--grade-z); color: #fff; } - -@keyframes fadeSlideIn { - from { opacity: 0; transform: translateY(-4px); } - to { opacity: 1; transform: translateY(0); } -} -``` - -### Thymeleaf templates to update - -All 13 templates in `src/main/resources/templates/`: - -1. Add `` to base layout -2. Replace all `background: white` / light backgrounds with `var(--bg-primary)` or `var(--bg-secondary)` -3. Replace all inline hex colors with CSS variables -4. Replace emoji characters (🔍 🏙️ ⚠️ etc.) with Lucide SVG icons -5. Apply `.card` class to all restaurant cards -6. Apply `.grade-badge .grade-a/b/c/z` to all grade displays - -### Lucide icons - -Include via CDN or copy SVGs locally: -```html - - - - -``` - -#### Success criteria - -1. Any page has dark background `#0f0f0f`–`#1a1a1a` with `#f5f5f5` text -2. All color/spacing/typography values come from CSS variables in `design-system.css` — no inline styles or hardcoded hex in templates -3. Restaurant cards use `.card` class consistently across search, analytics, and dashboard -4. Grade A badge shows green circle with CSS animation; B/C/Z have distinct colors -5. `grep -r "U+1F" src/main/resources/templates/` returns 0 (no emoji in templates) - ---- - -## Deployment Checklist (Post Phase 20) - -### Pre-deployment - -```bash -# 1. Full test suite -mvn clean verify -q -# Expected: BUILD SUCCESS - -# 2. Docker build -docker compose build -# Expected: no errors - -# 3. Environment setup -cp .env.example .env -# Fill in: JWT_SECRET (min 32 chars), MONGODB_URI, POSTGRES_*, REDIS_* - -# 4. Stack smoke test -docker compose up -d -curl http://localhost:8080/api/restaurants/health -# Expected: {"status":"UP"} or similar -``` - -### Environment variables required (`.env`) - -```bash -JWT_SECRET= -MONGODB_URI=mongodb://mongodb:27017 -MONGODB_DATABASE=newyork -MONGODB_COLLECTION=restaurants -POSTGRES_DB=restaurantdb -POSTGRES_USER=restaurant -POSTGRES_PASSWORD= -REDIS_HOST=redis -REDIS_PORT=6379 -NYC_API_APP_TOKEN= -NYC_API_MAX_RECORDS=50000 -``` - -### Production startup - -```bash -docker compose up -d -# Services start in order: mongodb → postgres → redis → app -# App waits for all three health checks before accepting traffic - -# Tail logs -docker compose logs -f app - -# Data sync (first run) -curl -X POST http://localhost:8080/api/sync/start \ - -H "Authorization: Bearer " - -# Verify data loaded -curl http://localhost:8080/api/restaurants/stats -``` - -### GitHub release - -After all phases complete and pushed to `main`: - -```bash -git tag -a v3.0.0 -m "v3.0 Production Readiness" -git push github.com-personal St4r4x/restaurant-analytics v3.0.0 -``` - ---- - -## Key Technical Constraints (from project history) - -| Constraint | Value | Reason | -|------------|-------|--------| -| Testcontainers | 1.x (1.19.8) | 2.x dropped JUnit 4 support | -| Bucket4j | 7.6.1 | 8.x requires JDK 17 | -| Playwright | 1.49.0 | Upgrade only if CI browser install fails | -| JaCoCo argLine | `@{argLine}` (late-binding) | Literal string causes StackOverflowError with Mockito | -| CORS | Both `CorsConfigurationSource` bean AND `http.cors(withDefaults())` required | Either alone causes OPTIONS 403 | -| Playwright auth | `addInitScript()` to inject localStorage JWT | `storageState()` does not work for localStorage JWT | -| GHCR push | Requires OCI `LABEL org.opencontainers.image.source` in Dockerfile | Absent label → `permission_denied` | -| `AppConfig.getProperty()` | Must check `System.getProperty()` before env vars | Required for Testcontainers URI injection | -| Mockito on Java 25 | Use `UsernamePasswordAuthenticationToken` concrete class | `mock(Authentication.class)` fails | -| `AppConfig` static mock | Use reflection to patch `.properties` field | `mockStatic(AppConfig.class)` causes `VerifyError` | diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md deleted file mode 100644 index 477c37b..0000000 --- a/.planning/REQUIREMENTS.md +++ /dev/null @@ -1,221 +0,0 @@ -# Requirements — v3.0 Production Readiness - -**Milestone:** v3.0 — Production Readiness -**Goal:** Transform the academic project into a portfolio-grade, deployable application with full CI/CD, comprehensive test coverage, and production-quality code across every layer. -**Date:** 2026-04-11 - ---- - -## CI/CD - -### GitHub Actions Pipeline - -- [ ] **CI-01**: User can see build status on every push to `develop` and `main` via GitHub Actions -- [ ] **CI-02**: User can see the pipeline fail fast when any unit test fails (Maven build gate) -- [ ] **CI-03**: User can see separate jobs for build, unit-test, integration-test, E2E, and Docker — with clear failure attribution -- [ ] **CI-04**: User can see Maven dependencies cached across runs (keyed on pom.xml hash) -- [ ] **CI-05**: User can pull a Docker image from GHCR after every successful push to `main` -- [ ] **CI-06**: User can see Docker build validated (but not pushed) on feature/develop branches -- [ ] **CI-07**: User can see no plaintext credentials in workflow YAML (all secrets via `${{ secrets.* }}`) -- [ ] **CI-08**: User can see a JaCoCo coverage report published as a PR comment (coverage delta visible without downloading artifacts) -- [ ] **CI-09**: User can see a workflow status badge in README showing CI is active - ---- - -## Testing - -### Unit & Slice Tests - -- [ ] **TEST-01**: User can run `mvn test` and see all existing 27 test files pass (no regression) -- [ ] **TEST-02**: User can see service-layer unit tests covering `AuthService` and `RestaurantService` with Mockito mocks -- [ ] **TEST-03**: User can see controller slice tests covering all auth, restaurant, inspection, and admin endpoints (HTTP status codes, JSON shape) - -### Integration Tests - -- [ ] **TEST-04**: User can run integration tests with real MongoDB and PostgreSQL via Testcontainers (no live database required) -- [ ] **TEST-05**: User can see existing `RestaurantDAOIntegrationTest` migrated to Testcontainers (no `localhost:27017` assumption) -- [ ] **TEST-06**: User can run integration tests in CI without any external DB dependency - -### Coverage - -- [ ] **TEST-07**: User can see JaCoCo code coverage report generated after `mvn test` -- [ ] **TEST-08**: User can see the build fail when instruction coverage drops below a defined threshold (baseline measured first) - -### E2E Tests - -- [ ] **TEST-09**: User can run Playwright browser tests covering login flow (valid + invalid credentials) -- [ ] **TEST-10**: User can run Playwright browser tests covering restaurant search and result display -- [ ] **TEST-11**: User can run Playwright browser tests covering the interactive map page load -- [ ] **TEST-12**: User can run Playwright browser tests covering controller dashboard access (role-gated) -- [ ] **TEST-13**: User can run E2E tests in CI using `docker compose` to boot the application - ---- - -## Database - -### MongoDB Indexing & Optimization - -- [ ] **DB-01**: User can see indexes on `camis`, `boro`, `cuisine_description`, and `grades.score`/`grades.grade` created programmatically at startup -- [ ] **DB-02**: User can see a text index on `dba` (restaurant name) enabling `$text` search to replace slow `$regex` on full collection -- [ ] **DB-03**: User can see a 2dsphere geospatial index on `address.coord` enabling proper `$near` queries for nearby restaurants -- [ ] **DB-04**: User can see DAO list queries use field projections (return only `camis`, `dba`, `boro`, `cuisine_description`, `grades[0]`) -- [ ] **DB-05**: User can see index creation consolidated in a dedicated `ensureIndexes()` method (called at startup or sync time) - ---- - -## Config & Secrets - -- [ ] **CFG-01**: User can see no hardcoded secrets in `application.properties` or source code (all replaced with `${ENV_VAR}` references) -- [ ] **CFG-02**: User can see JWT secret read from environment (`JWT_SECRET`) with startup assertion enforcing minimum 32 chars -- [ ] **CFG-03**: User can see controller and admin signup codes read from environment (`CONTROLLER_SIGNUP_CODE`, `ADMIN_SIGNUP_CODE`) -- [ ] **CFG-04**: User can find a `src/test/resources/application-test.properties` with safe test values (no production secrets) -- [ ] **CFG-05**: User can find a `.env.example` at project root documenting all required environment variables with descriptions - ---- - -## Docker - -- [ ] **DOCKER-01**: User can see health checks verified and correct on all 4 services (app, MongoDB, Redis, PostgreSQL) -- [ ] **DOCKER-02**: User can see `depends_on: condition: service_healthy` enforced so app only starts after all DBs are ready -- [ ] **DOCKER-03**: User can see memory limits configured on all containers (`deploy: resources: limits`) -- [ ] **DOCKER-04**: User can see a multi-stage Dockerfile (builder stage with Maven, runtime stage with JRE-Alpine only) -- [ ] **DOCKER-05**: User can see the app container run as a non-root user in the Dockerfile -- [ ] **DOCKER-06**: User can see a `.dockerignore` file preventing source, tests, and git history from entering the build context -- [ ] **DOCKER-07**: User can find a `.env.example` file (shared with CFG-05) documenting how to configure the Compose stack - ---- - -## Security - -- [ ] **SEC-01**: User can see an explicit CORS policy configured in both `WebMvcConfigurer` and `SecurityConfig` (not just one) -- [ ] **SEC-02**: User can see security headers (`X-Content-Type-Options`, `X-Frame-Options`) present in all responses -- [ ] **SEC-03**: User can see `@Valid` annotations on all `@RequestBody` DTOs with appropriate `@NotBlank`, `@Size`, `@Email` constraints -- [ ] **SEC-04**: User can see `MethodArgumentNotValidException` handled globally by `@RestControllerAdvice` with structured JSON error -- [ ] **SEC-05**: User can see Bucket4j rate limiting wired on `/api/auth/login` and `/api/auth/register` endpoints -- [ ] **SEC-06**: User can see rate limiting extended to `/api/restaurants/**` public endpoints (higher limit than auth) -- [ ] **SEC-07**: User can see `server.forward-headers-strategy=native` configured for HTTPS-ready reverse proxy operation -- [ ] **SEC-08**: User can see JWT secret length assertion at startup (fails fast if < 32 chars) - ---- - -## Code Quality - -- [ ] **QA-01**: User can see `logback-spring.xml` replacing the non-functional `simplelogger.properties` -- [ ] **QA-02**: User can see structured JSON log output in production profile (via logstash-logback-encoder 7.3) -- [ ] **QA-03**: User can see a request ID (UUID) propagated via MDC and returned as `X-Request-ID` response header -- [ ] **QA-04**: User can see dead code removed per the existing CLEANUP.md audit (unused classes, endpoints, commented blocks) -- [ ] **QA-05**: User can see every controller endpoint annotated with `@Operation`, `@ApiResponse`, and `@Tag` in Swagger UI -- [ ] **QA-06**: User can see all auth endpoints marked with `@SecurityRequirement` in Swagger -- [ ] **QA-07**: User can see all controllers using `ResponseUtil` consistently (no ad-hoc `ResponseEntity.badRequest().build()`) -- [ ] **QA-08**: User can see a global `@RestControllerAdvice` mapping all exception types to structured JSON with `status`, `message`, `timestamp` - ---- - -## UI Redesign - -- [ ] **UI-01**: User can see a CSS design token system (`:root` custom properties) defining palette, spacing, and typography for all 10 pages -- [ ] **UI-02**: User can see a dark/neutral color scheme across all pages (Vercel-style: `#0f0f0f`–`#1a1a1a` background, `#f5f5f5` text) -- [ ] **UI-03**: User can see Inter (or equivalent sans-serif) as the consistent font across all pages via `--font-sans` -- [ ] **UI-04**: User can see a shared `.card` CSS class applied consistently to analytics cards, search results, and dashboard items -- [ ] **UI-05**: User can see consistent button variants (`.btn-primary`, `.btn-secondary`, `.btn-danger`) with uniform padding and radius -- [ ] **UI-06**: User can see animated grade badges (A/B/C/Z) as colored badges with CSS `@keyframes` entrance animation -- [ ] **UI-07**: User can see skeleton loading placeholders updated to match the new dark theme palette -- [ ] **UI-08**: User can see Lucide SVG icons replacing all inline emoji and Unicode characters across all templates - ---- - -## Future Requirements (Deferred) - -- Real-time notifications for bookmarked restaurant updates (requires WebSocket) -- PDF export of controller reports -- Object storage for photos (S3/GCS) -- Cross-controller report view for admin -- Bulk photo upload - ---- - -## Out of Scope - -| Item | Reason | -|------|--------| -| Kubernetes / Helm charts | Portfolio project; Docker Compose is the correct artifact | -| OAuth2 / OIDC | Full JWT system already works; replacement adds risk with no portfolio value | -| Let's Encrypt / TLS in the app | Correct place is a reverse proxy; document nginx pattern instead | -| Dark mode toggle | Doubles CSS complexity; pick one theme and commit | -| Migrating JUnit 4 tests to JUnit 5 | 27 existing tests work; migration risk with no value | -| React / Vue frontend migration | Thymeleaf is working; redesign in-place with CSS | -| Bootstrap → Tailwind migration | Full template refactor risk; keep existing framework | -| Spring Cloud Config / Vault | Overkill for portfolio scale; env vars are sufficient | -| Multi-tenant / SaaS features | Portfolio quality target, not real SaaS | - ---- - -## Traceability - -*Generated by roadmapper 2026-04-11 — all 63 v3.0 requirements mapped.* - -| REQ-ID | Phase | Status | -|--------|-------|--------| -| QA-01 | Phase 11 — Logging Infrastructure | Pending | -| QA-02 | Phase 11 — Logging Infrastructure | Pending | -| QA-03 | Phase 11 — Logging Infrastructure | Pending | -| TEST-07 | Phase 12 — Maven Build Hardening | Pending | -| TEST-08 | Phase 12 — Maven Build Hardening | Pending | -| CFG-01 | Phase 13 — Config & Docker Hardening | Pending | -| CFG-02 | Phase 13 — Config & Docker Hardening | Pending | -| CFG-03 | Phase 13 — Config & Docker Hardening | Pending | -| CFG-04 | Phase 13 — Config & Docker Hardening | Pending | -| CFG-05 | Phase 13 — Config & Docker Hardening | Pending | -| DOCKER-01 | Phase 13 — Config & Docker Hardening | Pending | -| DOCKER-02 | Phase 13 — Config & Docker Hardening | Pending | -| DOCKER-03 | Phase 13 — Config & Docker Hardening | Pending | -| DOCKER-04 | Phase 13 — Config & Docker Hardening | Pending | -| DOCKER-05 | Phase 13 — Config & Docker Hardening | Pending | -| DOCKER-06 | Phase 13 — Config & Docker Hardening | Pending | -| DOCKER-07 | Phase 13 — Config & Docker Hardening | Pending | -| TEST-04 | Phase 14 — Testcontainers Integration Tests | Pending | -| TEST-05 | Phase 14 — Testcontainers Integration Tests | Pending | -| TEST-06 | Phase 14 — Testcontainers Integration Tests | Pending | -| CI-01 | Phase 15 — GitHub Actions CI Pipeline | Pending | -| CI-02 | Phase 15 — GitHub Actions CI Pipeline | Pending | -| CI-03 | Phase 15 — GitHub Actions CI Pipeline | Pending | -| CI-04 | Phase 15 — GitHub Actions CI Pipeline | Pending | -| CI-05 | Phase 15 — GitHub Actions CI Pipeline | Pending | -| CI-06 | Phase 15 — GitHub Actions CI Pipeline | Pending | -| CI-07 | Phase 15 — GitHub Actions CI Pipeline | Pending | -| CI-08 | Phase 15 — GitHub Actions CI Pipeline | Pending | -| CI-09 | Phase 15 — GitHub Actions CI Pipeline | Pending | -| SEC-01 | Phase 16 — Security Hardening | Pending | -| SEC-02 | Phase 16 — Security Hardening | Pending | -| SEC-03 | Phase 16 — Security Hardening | Pending | -| SEC-04 | Phase 16 — Security Hardening | Pending | -| SEC-05 | Phase 16 — Security Hardening | Pending | -| SEC-06 | Phase 16 — Security Hardening | Pending | -| SEC-07 | Phase 16 — Security Hardening | Pending | -| SEC-08 | Phase 16 — Security Hardening | Pending | -| QA-04 | Phase 17 — Code Quality & MongoDB Indexing | Pending | -| QA-05 | Phase 17 — Code Quality & MongoDB Indexing | Pending | -| QA-06 | Phase 17 — Code Quality & MongoDB Indexing | Pending | -| QA-07 | Phase 17 — Code Quality & MongoDB Indexing | Pending | -| QA-08 | Phase 17 — Code Quality & MongoDB Indexing | Pending | -| DB-01 | Phase 17 — Code Quality & MongoDB Indexing | Pending | -| DB-02 | Phase 17 — Code Quality & MongoDB Indexing | Pending | -| DB-03 | Phase 17 — Code Quality & MongoDB Indexing | Pending | -| DB-04 | Phase 17 — Code Quality & MongoDB Indexing | Pending | -| DB-05 | Phase 17 — Code Quality & MongoDB Indexing | Pending | -| TEST-09 | Phase 18 — E2E Tests (Playwright) | Pending | -| TEST-10 | Phase 18 — E2E Tests (Playwright) | Pending | -| TEST-11 | Phase 18 — E2E Tests (Playwright) | Pending | -| TEST-12 | Phase 18 — E2E Tests (Playwright) | Pending | -| TEST-13 | Phase 18 — E2E Tests (Playwright) | Pending | -| TEST-01 | Phase 19 — Unit & Controller Tests | Pending | -| TEST-02 | Phase 19 — Unit & Controller Tests | Pending | -| TEST-03 | Phase 19 — Unit & Controller Tests | Pending | -| UI-01 | Phase 20 — UI Visual Redesign | Pending | -| UI-02 | Phase 20 — UI Visual Redesign | Pending | -| UI-03 | Phase 20 — UI Visual Redesign | Pending | -| UI-04 | Phase 20 — UI Visual Redesign | Pending | -| UI-05 | Phase 20 — UI Visual Redesign | Pending | -| UI-06 | Phase 20 — UI Visual Redesign | Pending | -| UI-07 | Phase 20 — UI Visual Redesign | Pending | -| UI-08 | Phase 20 — UI Visual Redesign | Pending | diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md deleted file mode 100644 index 99f193b..0000000 --- a/.planning/ROADMAP.md +++ /dev/null @@ -1,258 +0,0 @@ -# Roadmap: Restaurant Hygiene Control App - -## Milestones - -- ✅ **v1.0 — Foundation** — Phases 1-4 (shipped 2026-04-01): auth, controller reports API, customer discovery UI, integration tests → [archive](.planning/milestones/v1.0-ROADMAP.md) -- ✅ **v2.0 — Full Product** — Phases 5-10 (shipped 2026-04-11): controller dashboard UI, public analytics page, dual landing/home routing, map filters + uncontrolled tracker, UX polish (pagination/skeletons/toasts/mobile), admin tools → [archive](milestones/v2.0-ROADMAP.md) -- 🔄 **v3.0 — Production Readiness** — Phases 11-20 (started 2026-04-11): CI/CD pipeline, test coverage, security hardening, Docker production config, code quality, UI redesign - -## Overview - -**v1.0** transformed the Spring Boot NYC restaurant analytics API into a dual-role web application with JWT auth, controller report filing, customer search/map/bookmark UI, and a hardened security layer. - -**v2.0** completes the product: controllers get a full UI workspace, a public analytics dashboard surfaces city-wide hygiene trends, the homepage is redesigned for both anonymous visitors and authenticated users, discovery is enhanced with map filters and an uncontrolled-restaurants tracker, and the whole app gets UX polish (pagination, skeletons, toasts, mobile). - -**v3.0** transforms the academic project into a portfolio-grade, deployable application: structured logging first (every subsequent phase benefits immediately), Maven build tooling hardened (JaCoCo + Failsafe argLine fix), config and Docker production-hardened, Testcontainers integration tests that run without a live database, GitHub Actions CI pipeline consuming all test infrastructure, security hardening (CORS, headers, rate limiting, input validation), code quality sweep (OpenAPI, dead code, ResponseUtil), Playwright E2E smoke tests, unit and controller slice tests, and finally a full visual redesign with a dark/neutral design system. - -## Phases - -**Phase Numbering:** -- Integer phases (1, 2, 3): Planned milestone work -- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED) - -Decimal phases appear between their surrounding integers in numeric order. - -### Previous milestones (phases 1-10) - -- [x] **Phase 1: Role Infrastructure** - Extend JWT auth and Spring Security for CUSTOMER/CONTROLLER roles (completed 2026-03-29) -- [x] **Phase 2: Controller Reports** - CRUD API for internal inspection reports stored in PostgreSQL (completed 2026-03-30) -- [x] **Phase 3: Customer Discovery** - Restaurant search, detail page, and interactive map UI (completed 2026-03-31) -- [x] **Phase 4: Integration Polish** - Cross-role security tests, ownership invariant tests, rate limiting (completed 2026-04-01) -- [x] **Phase 5: Controller Workspace** - Controller dashboard UI (completed 2026-04-03) -- [x] **Phase 6: Analytics & Stats** - Public analytics page (completed 2026-04-03) -- [x] **Phase 7: Homepage & Navigation** - Dual landing/home routing, persistent navbar (completed 2026-04-03) -- [x] **Phase 8: Discovery Enhancement** - Map filters, uncontrolled tracker, nearby restaurants, sort controls (completed 2026-04-10) -- [x] **Phase 9: UX Polish** - Pagination, skeleton loading, toast notifications, mobile responsive (completed 2026-04-10) -- [x] **Phase 10: Admin Tools** - Sync controls, CSV export, aggregate report stats (completed 2026-04-11) - -### v3.0 phases (11-20) - -- [x] **Phase 11: Logging Infrastructure** - Replace non-functional simplelogger.properties with structured Logback, add request ID propagation via MDC (completed 2026-04-11) -- [x] **Phase 12: Maven Build Hardening** - Wire JaCoCo coverage report and Failsafe plugin with correct argLine late-binding to unblock all test infrastructure (completed 2026-04-12) -- [x] **Phase 13: Config & Docker Hardening** - Eliminate all hardcoded secrets, production-grade Docker Compose with health checks and resource limits (completed 2026-04-12) -- [x] **Phase 14: Testcontainers Integration Tests** - Make existing integration test self-contained against real MongoDB and PostgreSQL via Testcontainers (completed 2026-04-12) -- [x] **Phase 15: GitHub Actions CI Pipeline** - Five-job pipeline (build, unit-test, integration, E2E placeholder, Docker) consuming phases 12-14 artifacts (completed 2026-04-12) -- [ ] **Phase 16: Security Hardening** - Explicit CORS policy, security headers, input validation, rate limiting extension, HTTPS-ready config -- [ ] **Phase 17: Code Quality & MongoDB Indexing** - Dead code removal, complete OpenAPI docs, ResponseUtil consistency, MongoDB indexes at startup -- [ ] **Phase 18: E2E Tests (Playwright)** - Browser smoke tests covering login, search, map, and controller dashboard via docker compose -- [ ] **Phase 19: Unit & Controller Tests** - Service and DAO unit tests with Mockito, controller slice tests covering all endpoints -- [ ] **Phase 20: UI Visual Redesign** - CSS design token system, dark/neutral palette, shared component classes, animated grade badges, Lucide icons - -## Phase Details - -> v1.0 and v2.0 phase details archived. See [milestones/v1.0-ROADMAP.md](milestones/v1.0-ROADMAP.md) and [milestones/v2.0-ROADMAP.md](milestones/v2.0-ROADMAP.md). - ---- - -### Phase 11: Logging Infrastructure -**Goal**: Every request produces structured, identifiable log output and carries a traceable request ID through all service layers -**Depends on**: Phase 10 (v2.0 complete) -**Requirements**: QA-01, QA-02, QA-03 -**Success Criteria** (what must be TRUE): - 1. Starting the application with `--spring.profiles.active=prod` produces JSON log lines readable by log aggregators (Logstash-compatible), not plaintext - 2. Starting the application without a prod profile produces human-readable plaintext log lines that include `[requestId]` on every line generated by a request - 3. Every HTTP response includes an `X-Request-ID` header containing a UUID that matches the `requestId` field in the corresponding log lines - 4. No log output contains raw stack traces from `simplelogger.properties` — that file is deleted and its configuration is inert -**Plans**: 2 plans -Plans: -- [x] 11-01-PLAN.md — Add logstash-logback-encoder 7.3 dependency, create logback-spring.xml (prod JSON / dev plaintext with requestId), delete simplelogger.properties -- [x] 11-02-PLAN.md — Create RequestIdFilter (@Component @Order(0)) with 5-test TDD suite covering UUID generation, X-Request-ID header, MDC cleanup, and client-value rejection - ---- - -### Phase 12: Maven Build Hardening -**Goal**: The Maven build produces a JaCoCo coverage report after every `mvn test` run and fails the build when coverage drops below a defined threshold, without breaking any existing Mockito-instrumented tests -**Depends on**: Phase 11 -**Requirements**: TEST-07, TEST-08 -**Success Criteria** (what must be TRUE): - 1. Running `mvn test` generates a JaCoCo HTML report at `target/site/jacoco/index.html` showing line and branch coverage metrics - 2. Running `mvn test` with coverage below the configured threshold exits with a non-zero code and a clear JaCoCo threshold violation message — not a cryptic StackOverflowError - 3. All 28 existing test files pass with zero regressions after the JaCoCo and Failsafe plugins are added (the argLine late-binding fix prevents Mockito instrumentation failure) - 4. The coverage threshold is documented in `pom.xml` with a comment explaining that it reflects the measured baseline, not an aspirational target -**Plans**: 2 plans -Plans: -- [x] 12-01-PLAN.md — Fix Surefire @{argLine} late-binding, @Ignore RestaurantDAOIntegrationTest, wire JaCoCo prepare-agent + report, measure baseline -- [x] 12-02-PLAN.md — Add JaCoCo check goal with measured threshold + Failsafe plugin with @{argLine} late-binding - ---- - -### Phase 13: Config & Docker Hardening -**Goal**: The application has no hardcoded secrets anywhere in source or configuration, and the Docker Compose stack starts reliably with health-checked dependencies, resource limits, and a multi-stage production image -**Depends on**: Phase 12 -**Requirements**: CFG-01, CFG-02, CFG-03, CFG-04, CFG-05, DOCKER-01, DOCKER-02, DOCKER-03, DOCKER-04, DOCKER-05, DOCKER-06, DOCKER-07 -**Success Criteria** (what must be TRUE): - 1. Cloning the repository and grepping for `changeme`, `secret`, or any raw JWT-secret string in `application.properties` and all Java source files returns zero matches - 2. Starting the app without the `JWT_SECRET` environment variable set causes the application to refuse to start with a descriptive error message (not a silent null or a runtime NullPointerException) - 3. Running `docker compose up` starts all four services in dependency order (app waits for MongoDB, PostgreSQL, and Redis health checks to pass) without manual retry - 4. A new developer can find `.env.example` at the project root, copy it to `.env`, fill in the values, and run the stack without reading any other documentation - 5. The production Docker image runs as a non-root user and is built in two stages (builder with Maven, runtime with JRE-Alpine only), resulting in an image smaller than a single-stage build -**Plans**: 3 plans -Plans: -- [x] 13-01-PLAN.md — Test infrastructure (application-test.properties, JwtUtilTest reflection patch) + AppConfig startup assertion + application.properties secret removal + .env.example -- [x] 13-02-PLAN.md — Dockerfile upgrade (maven:3.9-eclipse-temurin-25, eclipse-temurin:25-jre-alpine, non-root appuser) + .dockerignore -- [x] 13-03-PLAN.md — docker-compose.yml: replace hardcoded secrets with ${VAR} references, add memory limits to all 4 services - ---- - -### Phase 14: Testcontainers Integration Tests -**Goal**: Integration tests run against real MongoDB and PostgreSQL containers with no live database required, and are runnable in CI without any external service dependency -**Depends on**: Phase 13 (AppConfig env var chain, application-test.properties) -**Requirements**: TEST-04, TEST-05, TEST-06 -**Success Criteria** (what must be TRUE): - 1. Running `mvn failsafe:integration-test` on a machine with Docker installed but no running MongoDB or PostgreSQL starts containers automatically, runs tests, and tears them down — without any `localhost:27017` configuration - 2. The existing `RestaurantDAOIntegrationTest` is renamed and extended so it passes in CI without requiring a pre-seeded database on the runner - 3. A developer can delete their local MongoDB and PostgreSQL installations and still run the full integration test suite successfully -**Plans**: 4 plans -Plans: -- [x] 14-01-PLAN.md — pom.xml: add Testcontainers 1.19.8 (3 artifacts) + Failsafe plugin; fix Surefire argLine; add AppConfig.getProperty() System.getProperty() tier-0 -- [x] 14-02-PLAN.md — RestaurantDAOIT.java: rename + rewrite RestaurantDAOIntegrationTest with TC mongo:7.0, @ClassRule, 60-doc seed, 14 assertions -- [x] 14-03-PLAN.md — UserRepositoryIT.java: new test with TC postgres:15-alpine + mongo:7.0, @SpringBootTest + ApplicationContextInitializer pattern, 4 assertions -- [x] 14-04-PLAN.md — Final verification: mvn verify green + CHANGELOG.md update - ---- - -### Phase 15: GitHub Actions CI Pipeline -**Goal**: Every push to `develop` or `main` triggers an automated pipeline with separate, clearly attributed jobs for build, unit tests, integration tests, and Docker, and every successful `main` push publishes a Docker image to GHCR -**Depends on**: Phase 12 (JaCoCo report), Phase 14 (Testcontainers integration job) -**Requirements**: CI-01, CI-02, CI-03, CI-04, CI-05, CI-06, CI-07, CI-08, CI-09 -**Success Criteria** (what must be TRUE): - 1. Pushing a commit with a failing unit test to `develop` makes the GitHub Actions checks page show a red status with the failure attributed to the `unit-tests` job — not a generic build failure - 2. Pushing a commit to `main` that passes all jobs results in a new Docker image appearing under the repository's Packages tab on GitHub - 3. Opening the repository's README shows a green CI badge linked to the workflow run page - 4. Pushing a commit to `develop` completes the pipeline run without downloading any Maven dependencies from the internet (cache hit on pom.xml hash) - 5. No workflow YAML file contains any literal secret value — all credentials are referenced via `${{ secrets.* }}` - 6. A JaCoCo coverage summary is visible as a comment on pull requests targeting `develop` without requiring the reviewer to download an artifact -**Plans**: 2 plans -Plans: -- [x] 15-01-PLAN.md — pom.xml: add JaCoCo 0.8.12 plugin (prepare-agent, report, check at 38%); Dockerfile: add OCI LABEL before EXPOSE; README: add CI badge -- [x] 15-02-PLAN.md — .github/workflows/ci.yml: five-job serial pipeline (build → unit-test → integration-test → e2e → docker) with GHCR push on main, JaCoCo PR comment, Maven cache - ---- - -### Phase 16: Security Hardening -**Goal**: The application enforces an explicit CORS policy, adds security response headers, validates all request inputs with structured error responses, and fails fast on misconfigured secrets -**Depends on**: Phase 15 (CI acts as regression guard for security config changes) -**Requirements**: SEC-01, SEC-02, SEC-03, SEC-04, SEC-05, SEC-06, SEC-07, SEC-08 -**Success Criteria** (what must be TRUE): - 1. Sending a cross-origin OPTIONS preflight request to `/api/restaurants/**` from an unlisted origin returns HTTP 403 — not HTTP 200 with a wildcard `Access-Control-Allow-Origin` header - 2. Every HTTP response from the application includes `X-Content-Type-Options: nosniff` and `X-Frame-Options: DENY` headers - 3. POSTing a login request with an empty password field returns HTTP 400 with a JSON body containing `status`, `message`, and `timestamp` fields — not a 500 or an empty body - 4. Sending more than the configured number of login requests from a single IP within one minute returns HTTP 429 — and the same limit applies independently to restaurant search endpoints at a higher threshold - 5. Starting the application with a `JWT_SECRET` shorter than 32 characters causes startup failure with a message naming the problem — not a silent truncation or a runtime error on the first token decode -**Plans**: 4 plans -Plans: -- [x] 16-01-PLAN.md — Wave 0: Write failing tests (SecurityConfigTest CORS/header assertions, RateLimitFilterTest restaurant-path, AuthControllerValidationTest, GlobalExceptionHandlerTest) -- [x] 16-02-PLAN.md — Wave 1: CORS policy (CorsConfigurationSource bean + http.cors(withDefaults())), security headers (http.headers() DSL), remove @CrossOrigin from 4 controllers -- [ ] 16-03-PLAN.md — Wave 1: spring-boot-starter-validation in pom.xml, @NotBlank/@Email on 3 auth DTOs, @Valid on AuthController params, create GlobalExceptionHandler -- [x] 16-04-PLAN.md — Wave 1: AppConfig restaurant rate-limit methods, extend RateLimitFilter (4-arg constructor + second bucket), application.properties additions (restaurant limits + forward-headers-strategy) - ---- - -### Phase 17: Code Quality & MongoDB Indexing -**Goal**: The codebase has no dead code identified in CLEANUP.md, all controller endpoints are fully documented in Swagger, error responses are structured consistently, and MongoDB queries benefit from purpose-built indexes -**Depends on**: Phase 14 (indexes can be validated in Testcontainers environment) -**Requirements**: QA-04, QA-05, QA-06, QA-07, QA-08, DB-01, DB-02, DB-03, DB-04, DB-05 -**Success Criteria** (what must be TRUE): - 1. Opening Swagger UI at `/swagger-ui.html` shows every endpoint grouped by domain tag, with a description, at least one response code, and — for authenticated endpoints — a lock icon indicating the security requirement - 2. Any HTTP error response from the application (400, 401, 403, 404, 429, 500) returns a JSON body with exactly the fields `status`, `message`, and `timestamp` — no raw Spring error pages, no empty bodies - 3. Running `explain()` on the restaurant search query against a populated MongoDB collection shows an index scan (IXSCAN), not a collection scan (COLLSCAN) - 4. Grepping the codebase for classes and endpoints listed in CLEANUP.md returns zero matches — dead code is removed - 5. The restaurant list DAO query returns only the projected fields (`camis`, `dba`, `boro`, `cuisine_description`, `grades[0]`), not full documents — verifiable by inspecting the query in the MongoDB profiler or via a debug log line -**Plans**: TBD - ---- - -### Phase 18: E2E Tests (Playwright) -**Goal**: Automated browser tests cover the four critical user flows — login, restaurant search, map page, and controller dashboard access — and run in CI against a live docker compose stack -**Depends on**: Phase 15 (CI pipeline), Phase 13 (Docker health checks) -**Requirements**: TEST-09, TEST-10, TEST-11, TEST-12, TEST-13 -**Success Criteria** (what must be TRUE): - 1. Running `mvn failsafe:integration-test -Pe2e` on a machine with Docker and the Chromium browser installed executes login, search, map, and dashboard tests and reports pass/fail per test — not a single aggregate failure - 2. The CI pipeline's `e2e` job boots the full application stack via `docker compose up`, waits for health checks to pass, runs all Playwright tests, and tears down the stack — without leaving orphaned containers - 3. The login test covers both valid credentials (redirects to home) and invalid credentials (shows an error message) as separate test cases - 4. The controller dashboard test verifies that a CUSTOMER-role JWT cannot access `/dashboard` (redirect or error visible in the browser) — not just an API 403 -**Plans**: TBD - ---- - -### Phase 19: Unit & Controller Tests -**Goal**: Service-layer business logic and all REST controller endpoints are covered by focused unit and slice tests that run in milliseconds with no database or network dependency -**Depends on**: Phase 12 (JaCoCo coverage threshold enforced, argLine fix in place) -**Requirements**: TEST-01, TEST-02, TEST-03 -**Success Criteria** (what must be TRUE): - 1. Running `mvn test` passes all 27 existing test files and all newly added tests with zero failures — no regression from new test infrastructure - 2. A developer can see Mockito-based tests for `AuthService` (register, login, token refresh) and `RestaurantService` (search, stats, by-borough) that assert behavior on inputs without starting a Spring context - 3. A developer can inspect `@WebMvcTest` slice tests for `AuthController`, `RestaurantController`, `InspectionController`, and `UserController` that assert HTTP status codes and response JSON shape without a running database -**Plans**: TBD - ---- - -### Phase 20: UI Visual Redesign -**Goal**: All 13 application pages share a consistent dark/neutral design system with a CSS token foundation, unified component classes, animated grade badges, and SVG icons replacing all inline emoji -**Depends on**: Phase 18 (E2E tests established — UI class name changes must not silently break them) -**Requirements**: UI-01, UI-02, UI-03, UI-04, UI-05, UI-06, UI-07, UI-08 -**Success Criteria** (what must be TRUE): - 1. Opening any of the 13 pages in a browser shows a dark background in the `#0f0f0f`–`#1a1a1a` range with `#f5f5f5` body text — no page has a white or light background - 2. The browser DevTools shows all color, spacing, and typography values resolved from CSS custom properties defined in `design-system.css` — no inline style attributes or hardcoded hex values in template markup - 3. Inspecting a restaurant card on the search page, the analytics page, and the dashboard shows the same `.card` CSS class with identical visual appearance across all three contexts - 4. Viewing a restaurant with a grade A badge shows a colored badge with a CSS entrance animation (fade-in or slide-up) — and the same badge style applies consistently to grades B, C, and Z with distinct colors - 5. Grepping all Thymeleaf templates and static JS files for emoji characters (Unicode range U+1F300–U+1FAFF) returns zero matches — all icons are Lucide SVG elements -**Plans**: TBD -**UI hint**: yes - -### Phase 21: Upgrade Java 11 → 25 and Spring Boot 2.6.15 → 4.0.5, including JUnit 4 → 5 migration, javax → jakarta namespace, Spring Security 6 API updates, springdoc v1 → v2, logstash-logback-encoder 7.3 → 8.1, and MongoDB properties prefix rename - -**Goal:** The project builds successfully on Java 25 with Spring Boot 4.0.5, all tests pass under JUnit 5, and no deprecated/removed APIs remain in the codebase -**Requirements**: UPGRADE-01, UPGRADE-02, UPGRADE-03, UPGRADE-04 -**Depends on:** Phase 20 -**Plans:** 3/4 plans executed - -Plans: -- [x] 21-01-PLAN.md — pom.xml: Boot 4.0.5, Java 25, springdoc v2, logstash 8.1, remove JUnit 4 artifacts; application.properties: remove ant_path_matcher and hibernate.dialect -- [x] 21-02-PLAN.md — javax → jakarta namespace migration across 6 main + 1 test source file; mvn clean compile green -- [x] 21-03-PLAN.md — SecurityConfig.java: antMatchers → requestMatchers lambda DSL (Spring Security 6) -- [x] 21-04-PLAN.md — JUnit 4 → JUnit 5 migration across 9 test files; mvn test green -- [x] 21-05-PLAN.md — Full mvn clean verify gate; human checkpoint; CHANGELOG.md update - ---- - -## Progress - -**Execution Order:** -v1.0: Phases 1 → 2 → 3 → 4 -v2.0: Phase 5 → (6 ∥ 7) → 8 → 9 → 10 -v3.0: Phase 11 → 12 → 13 → (14 ∥ 15*) → 16 → 17 → 18 → 19 → 20 - *Phase 15 depends on 12 and 14; 14 depends on 13. Sequential in practice. - -| Phase | Plans Complete | Status | Completed | -|-------|----------------|--------|-----------| -| 1. Role Infrastructure | 4/4 | Complete | 2026-03-29 | -| 2. Controller Reports | 3/3 | Complete | 2026-03-31 | -| 3. Customer Discovery | 4/4 | Complete | 2026-03-31 | -| 4. Integration Polish | 4/4 | Complete | 2026-04-01 | -| 5. Controller Workspace | 2/2 | Complete | 2026-04-03 | -| 6. Analytics & Stats | 3/3 | Complete | 2026-04-03 | -| 7. Homepage & Navigation | 4/4 | Complete | 2026-04-03 | -| 8. Discovery Enhancement | 5/5 | Complete | 2026-04-10 | -| 9. UX Polish | 5/5 | Complete | 2026-04-10 | -| 10. Admin Tools | 3/3 | Complete | 2026-04-11 | -| 11. Logging Infrastructure | 2/2 | Complete | 2026-04-11 | -| 12. Maven Build Hardening | 2/2 | Complete | 2026-04-12 | -| 13. Config & Docker Hardening | 3/3 | Complete | 2026-04-12 | -| 14. Testcontainers Integration Tests | 4/4 | Complete | 2026-04-12 | -| 15. GitHub Actions CI Pipeline | 2/2 | Complete | 2026-04-12 | -| 16. Security Hardening | 3/4 | In Progress| | -| 17. Code Quality & MongoDB Indexing | 0/? | Not started | - | -| 18. E2E Tests (Playwright) | 0/? | Not started | - | -| 19. Unit & Controller Tests | 0/? | Not started | - | -| 20. UI Visual Redesign | 0/? | Not started | - | diff --git a/.planning/STATE.md b/.planning/STATE.md deleted file mode 100644 index 6f2097d..0000000 --- a/.planning/STATE.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -gsd_state_version: 1.0 -milestone: v3.0 -milestone_name: phases -status: executing -stopped_at: Phase 16 context gathered -last_updated: "2026-04-14T14:07:29.929Z" -last_activity: 2026-04-14 -- Phase 16 execution started -progress: - total_phases: 11 - completed_phases: 6 - total_plans: 22 - completed_plans: 18 - percent: 82 ---- - -# Project State - -## Project Reference - -See: .planning/PROJECT.md (updated 2026-04-11) - -**Core value:** A customer can search any NYC restaurant and immediately know whether it's clean — and a controller can document new hygiene findings against the same data. -**Current focus:** Phase 16 — security-hardening - -## Current Position - -Phase: 16 (security-hardening) — EXECUTING -Plan: 1 of 4 -Status: Executing Phase 16 -Last activity: 2026-04-14 -- Phase 16 execution started - -Progress: [░░░░░░░░░░] 0% - -## Accumulated Context - -### Decisions - -Decisions are logged in PROJECT.md Key Decisions table. - -Carried over from v2.0: - -- anyRequest().permitAll() with client-side IIFE guards for /admin, /dashboard — browser navigation does not send Authorization header -- uploadPhoto uses raw fetch() (not fetchWithAuth) — fetchWithAuth sets Content-Type: application/json, corrupts multipart boundary -- ADMIN role separate from CONTROLLER — Admin-specific signup code, separate DataSeeder seed user -- Mockito mock(Authentication.class) fails on Java 25 — use UsernamePasswordAuthenticationToken concrete class instead -- mockStatic(AppConfig.class) causes VerifyError on Java 25 — use reflection to patch AppConfig.properties static field in tests - -New for v3.0 (from research): - -- Testcontainers must stay at 1.x (1.19.8) — 2.x dropped JUnit 4 support; project uses junit-vintage-engine -- logstash-logback-encoder pinned at 7.3 — 7.4+ dropped Logback 1.2.x support; Spring Boot 2.6.15 ships Logback 1.2.12 -- Bucket4j must stay at 7.6.1 — 8.11.0+ requires JDK 17 -- Playwright pinned at 1.49.0 — upgrade only if CI browser install fails -- JaCoCo argLine must use late-binding @{argLine} form — literal string causes JaCoCo to silently overwrite the Mockito ByteBuddy flag, causing StackOverflowError on all controller tests -- AppConfig.getProperty() must check System.getProperty() before env vars — required for Testcontainers to inject URIs before MongoClientFactory static singleton initializes -- CORS requires both CorsConfigurationSource bean AND http.cors(withDefaults()) in SecurityConfig — either alone causes OPTIONS preflight 403 -- Playwright E2E auth: call /api/auth/login via APIRequestContext, extract accessToken, inject via addInitScript() — storageState() does not work for localStorage JWT -- GHCR push requires OCI LABEL org.opencontainers.image.source in Dockerfile — absent label causes permission_denied after first unlinked push -- NYC_API_MAX_RECORDS=200 in E2E CI compose — caps sync to ~10s, prevents timeout - -### Roadmap Evolution - -- Phase 21 added: Upgrade Java 11 → 25 and Spring Boot 2.6.15 → 4.0.5, including JUnit 4 → 5 migration, javax → jakarta namespace, Spring Security 6 API updates, springdoc v1 → v2, logstash-logback-encoder 7.3 → 8.1, and MongoDB properties prefix rename - -### Pending Todos - -None yet. - -### Blockers/Concerns - -- JaCoCo coverage baseline is unknown — must run `mvn jacoco:report` as first action in Phase 12 before enabling check goal; set threshold to baseline - 5% if below 60% -- Dockerfile current state unknown — must read before Phase 13 to avoid overwriting an already-correct multi-stage setup - -## Session Continuity - -Last session: 2026-04-13T09:05:17.823Z -Stopped at: Phase 16 context gathered -Resume file: .planning/phases/16-security-hardening/16-CONTEXT.md diff --git a/.planning/codebase/ARCHITECTURE.md b/.planning/codebase/ARCHITECTURE.md deleted file mode 100644 index c6e4b44..0000000 --- a/.planning/codebase/ARCHITECTURE.md +++ /dev/null @@ -1,287 +0,0 @@ -# Architecture - -**Analysis Date:** 2026-03-27 - -## Pattern Overview - -**Overall:** Layered MVC with Domain-Driven Design and Cache-Aside pattern - -**Key Characteristics:** -- Spring Boot 2.6.15 REST API following controller-service-DAO layers -- Raw MongoDB driver (mongodb-driver-sync) for aggregation pipelines, no Spring Data MongoDB -- PostgreSQL for user/bookmark persistence (Spring Data JPA) -- Redis cache-aside pattern for expensive MongoDB aggregations (3600s TTL) -- Scheduled data sync from NYC Open Data API (nightly at 02:00) with manual refresh endpoint -- JWT-based security with access (15min) and refresh (7 days) tokens -- POJO-based domain models with computed fields extracted to service layer - -## Layers - -**Controller Layer:** -- Purpose: REST API endpoints, request routing, response formatting -- Location: `src/main/java/com/aflokkat/controller/` -- Contains: - - `RestaurantController.java` — analytics endpoints (18 endpoints total) - - `AuthController.java` — JWT auth (register, login, refresh) - - `InspectionController.java` — inspection-specific queries - - `UserController.java` — user profile/bookmarks - - `ViewController.java` — HTML template serving -- Depends on: Service layer, DTO layer, Cache service -- Used by: HTTP clients (browsers, API consumers) - -**Service Layer:** -- Purpose: Business logic, input validation, computed field calculations -- Location: `src/main/java/com/aflokkat/service/` -- Contains: - - `RestaurantService.java` — restaurant queries, computed fields (latest grade, trend, badge color, coordinates), use-case implementations - - `AuthService.java` — user registration, login, token generation -- Depends on: DAO layer, ValidationUtil, domain models -- Used by: Controllers, SyncService, CacheService - -**DAO Layer:** -- Purpose: MongoDB data access via raw driver, aggregation pipeline construction -- Location: `src/main/java/com/aflokkat/dao/` -- Contains: - - `RestaurantDAO.java` — interface (29 methods) - - `RestaurantDAOImpl.java` — MongoDB aggregation pipelines, POJO codec registry -- Depends on: Domain models, MongoDB driver -- Used by: Service layer, Sync layer -- Note: Uses raw `mongodb-driver-sync` aggregation pipelines, not Spring Data MongoDB - -**Repository Layer (Spring JPA):** -- Purpose: PostgreSQL persistence for users and bookmarks -- Location: `src/main/java/com/aflokkat/repository/` -- Contains: - - `UserRepository.java` — Spring JPA for `UserEntity` - - `BookmarkRepository.java` — Spring JPA for `BookmarkEntity` -- Depends on: JPA/Hibernate -- Used by: AuthService, UserController - -**Sync Layer:** -- Purpose: Orchestrate NYC Open Data API fetch → map → MongoDB upsert -- Location: `src/main/java/com/aflokkat/sync/` -- Contains: - - `SyncService.java` — nightly scheduler (02:00), manual trigger, result tracking - - `NycOpenDataClient.java` — HTTP REST calls to NYC Open Data API - - `NycApiRestaurantDto.java` — DTO for API response mapping - - `SyncResult.java` — sync metadata (counts, timestamps, error) -- Depends on: RestaurantDAO, RestaurantCacheService, config -- Used by: Application startup, scheduler, POST `/api/restaurants/refresh` endpoint -- Flow: NYC API → fetch all records → group by `camis` → map inspection rows to grades → upsert restaurants → invalidate cache - -**Cache Layer:** -- Purpose: Redis cache-aside for expensive MongoDB aggregations; sorted set for top restaurants -- Location: `src/main/java/com/aflokkat/cache/` -- Contains: `RestaurantCacheService.java` -- Depends on: Spring Data Redis, ObjectMapper, configuration -- Used by: Controllers (cache-aside calls), SyncService (invalidation) -- Pattern: `getOrLoad(key, supplier, typeRef)` — returns cached value or calls supplier and stores result -- Sorted set operations: `KEY_TOP` stores restaurants by inspection score (lower = healthier) -- TTL: 3600s (configurable via `redis.cache.ttl-seconds`) - -**Security Layer:** -- Purpose: JWT token generation, validation, request filtering -- Location: `src/main/java/com/aflokkat/security/` -- Contains: - - `JwtUtil.java` — token generation (access + refresh), claims extraction - - `JwtAuthenticationFilter.java` — request interceptor, token validation -- Depends on: `jjwt` library, AppConfig -- Used by: AuthController, SecurityConfig - -**Config Layer:** -- Purpose: Application-wide configuration and dependency injection -- Location: `src/main/java/com/aflokkat/config/` -- Contains: - - `AppConfig.java` — centralized property loading (env vars → .env → application.properties) - - `MongoClientFactory.java` — singleton MongoDB client - - `RedisConfig.java` — StringRedisTemplate bean - - `SecurityConfig.java` — Spring Security setup, JWT filter chain - - `OpenApiConfig.java` — Swagger/OpenAPI bean -- Used by: Entire application - -**Domain Layer (MongoDB POJOs):** -- Purpose: Data models with BSON codec annotations -- Location: `src/main/java/com/aflokkat/domain/` -- Contains: - - `Restaurant.java` — main aggregate root (`_id`, `restaurant_id`, `name`, `cuisine`, `borough`, `address`, `phone`, `grades`) - - `Address.java` — nested document (`building`, `street`, `zipcode`, `coord` [GeoJSON]) - - `Grade.java` — inspection record (nested in `grades[]`; `date`, `grade`, `score`, `inspection_type`, `violation_code`, etc.) -- Used by: DAO, Service, Cache layers - -**Entity Layer (PostgreSQL JPA):** -- Purpose: User and bookmark persistence -- Location: `src/main/java/com/aflokkat/entity/` -- Contains: - - `UserEntity.java` — user credentials, roles - - `BookmarkEntity.java` — user-restaurant associations -- Used by: Repositories, AuthService - -**DTO Layer:** -- Purpose: Request/response DTOs, aggregation result pojos -- Location: `src/main/java/com/aflokkat/dto/` -- Contains: - - Request/Response: `AuthRequest`, `RegisterRequest`, `RefreshRequest`, `JwtResponse` - - Query results: `HeatmapPoint`, `TopRestaurantEntry`, `AtRiskEntry` -- Used by: Controllers, Cache layer, Service - -**Aggregation POJOs:** -- Purpose: Intermediate results from MongoDB aggregation pipelines -- Location: `src/main/java/com/aflokkat/aggregation/` -- Contains: - - `AggregationCount.java` — count per field (e.g., `{_id: "Italian", count: 500}`) - - `BoroughCuisineScore.java` — avg score per borough for a cuisine - - `CuisineScore.java` — avg score per cuisine - -**Utility Layer:** -- Purpose: Shared helper functions -- Location: `src/main/java/com/aflokkat/util/` -- Contains: - - `ValidationUtil.java` — `requireNonEmpty()`, `requirePositive()`, `validateFieldName()` - - `ResponseUtil.java` — uniform error response formatting - -## Data Flow - -**Analytics Query (e.g., GET /api/restaurants/by-borough):** - -1. HTTP GET → `RestaurantController` -2. Controller checks Redis cache via `RestaurantCacheService` -3. If cache miss: calls `RestaurantService.getRestaurantCountByBorough()` -4. Service delegates to `RestaurantDAOImpl.findCountByBorough()` -5. DAO builds MongoDB aggregation pipeline (`$group` by borough, `$count`) -6. Results returned as `List` -7. Cache stores result (TTL 3600s) -8. Response formatted as JSON and returned - -**Data Sync Flow (Scheduled 02:00 daily):** - -1. `SyncService.scheduledSync()` triggered by `@Scheduled` cron -2. `SyncService.runSync()` calls `NycOpenDataClient.fetchAll()` -3. Client fetches paginated records from NYC API (1000 per page, respects `max_records` limit) -4. Records grouped by `camis` (restaurant ID) in `mapToRestaurants()` -5. Each group: create `Restaurant` POJO with latest address/phone, aggregated `grades[]` (one per inspection date) -6. `RestaurantDAOImpl.upsertRestaurants()` bulk upsert (replace-on-match by `restaurant_id`) -7. `RestaurantCacheService.invalidateAll()` removes all `restaurants:*` keys -8. `RestaurantCacheService.updateTopRestaurants()` rebuilds sorted set `restaurants:top` with latest scores -9. SyncResult recorded with counts and timestamps - -**Authentication Flow:** - -1. POST `/api/auth/login` with credentials -2. `AuthController` → `AuthService.login()` -3. AuthService queries `UserRepository` for username -4. Password verified (bcrypt) -5. `JwtUtil.generateAccessToken()` + `generateRefreshToken()` -6. Response contains both tokens + user metadata -7. Subsequent requests include `Authorization: Bearer ` header -8. `JwtAuthenticationFilter` intercepts, validates token via `JwtUtil.validateToken()` -9. Token valid → request proceeds; invalid/expired → 401 Unauthorized - -**State Management:** - -- MongoDB: authoritative data store for restaurants (upserted nightly) -- PostgreSQL: user accounts, bookmarks (transactional) -- Redis: computed aggregations (cache-aside, TTL 3600s), top restaurants sorted set (rebuilt on sync) -- In-memory: `SyncService.lastResult` (sync status), JWT secret (`JwtUtil.key`) - -## Key Abstractions - -**Cache-Aside Pattern:** -- Method: `RestaurantCacheService.getOrLoad(key, supplier, typeRef)` -- On hit: deserialize from Redis, return -- On miss: call supplier (triggers DAO query), serialize to Redis, return -- Failure mode: swallows Redis exceptions, falls through to supplier (graceful degradation) - -**Aggregation Pipeline:** -- Location: `RestaurantDAOImpl` methods construct `List` pipelines -- Example: `findCountByBorough()` → `$match(address.$type: 3)` → `$group(_id: borough, count: $sum: 1)` → `$sort(count: -1)` -- Executed via `restaurantCollection.aggregate(pipeline, resultClass).forEach()` -- Result class: `AggregationCount`, `BoroughCuisineScore`, etc. - -**POJO Separation:** -- Restaurant POJO holds only stored fields from MongoDB -- Computed fields (latest grade, trend, badge color, lat/lng) calculated in `RestaurantService.toView()` -- Example: `toView()` builds `Map` with computed fields added -- Benefit: clean separation, computed fields never persisted - -**Sync Orchestration:** -- `SyncService` stateful: `running` flag, `lastResult`, `runningStartedAt` -- Result shared via `getLastResult()` for polling sync status -- Thread-safe: uses `volatile` for flags and timestamps - -## Entry Points - -**HTTP API:** -- Location: `Application.java` → Spring Boot startup -- Listens: `http://localhost:8080` -- Base paths: - - `/api/restaurants/*` → analytics, hygiene radar, sync - - `/api/auth/*` → login, register, refresh - - `/api/users/*` → profile, bookmarks - - `/api/inspections/*` → inspection-specific queries - - `/swagger-ui.html` → OpenAPI documentation - -**Scheduled Tasks:** -- `SyncService.scheduledSync()` → cron: 0 0 2 * * * (daily 02:00) -- Triggered by `@EnableScheduling` on `Application` class - -**Configuration Files:** -- `application.properties` → Spring config (logging, DB, API, JWT) -- `.env` → environment overrides (Docker Compose) -- System environment variables → highest priority - -## Error Handling - -**Strategy:** Layer-specific catch-and-log with graceful degradation - -**Patterns:** - -1. **Controller Layer:** - - Try-catch all endpoints - - Catch `IllegalArgumentException` → 400 Bad Request - - Catch `Exception` → 500 Internal Server Error - - Use `ResponseUtil.errorResponse()` for uniform format - -2. **Service Layer:** - - Validate input via `ValidationUtil` methods (throw `IllegalArgumentException`) - - Let DAO exceptions propagate (caught by controller) - -3. **DAO Layer:** - - MongoDB failures logged but not caught (bubble to service) - - Invalid queries return empty lists - -4. **Cache Layer:** - - All Redis operations wrapped in try-catch - - Failures logged as warnings, supplier called silently (cache-aside fallback) - -5. **Sync Layer:** - - Network failures caught, result marked `success: false` with error message - - Partial data treated as failure (all-or-nothing) - -## Cross-Cutting Concerns - -**Logging:** -- Framework: SLF4J + Simple Logger -- Configuration: `src/main/resources/simplelogger.properties` -- Root level: INFO; com.aflokkat: DEBUG -- Usage: SQL calls, sync events, cache operations, API errors - -**Validation:** -- Centralized: `ValidationUtil` class -- Methods: `requireNonEmpty()`, `requirePositive()`, `validateFieldName()` -- Failures: throw `IllegalArgumentException` with descriptive messages (French/English mix) -- Used by: Service layer before DAO calls - -**Authentication:** -- JWT tokens: HMAC-SHA256 signed -- Access token: 15 min (900,000 ms) -- Refresh token: 7 days (604,800,000 ms) -- Validation: checked on every request by `JwtAuthenticationFilter` -- Roles: extracted from token claim, checked by `@PreAuthorize("hasRole('ADMIN')")` - -**CORS:** -- All controllers: `@CrossOrigin(origins = "*", allowedHeaders = "*")` -- Allows frontend on different domain/port - ---- - -*Architecture analysis: 2026-03-27* diff --git a/.planning/codebase/CONCERNS.md b/.planning/codebase/CONCERNS.md deleted file mode 100644 index 91eb6b6..0000000 --- a/.planning/codebase/CONCERNS.md +++ /dev/null @@ -1,85 +0,0 @@ -# Concerns - -**Analysis Date:** 2026-03-27 - -## Tech Debt - -### Code Quality -- **Raw exception catching** — broad `catch (Exception e)` in several DAO/service methods instead of typed exceptions; hides root causes -- **Monolithic RestaurantController** — ~413 lines with 18 endpoints; could be split by domain (analytics, inspections) -- **Swallowed interruptions** — `InterruptedException` caught and logged but thread interrupt status not restored -- **Missing null checks** — several DAO return values used without null guard before calling `.isEmpty()` or `.get(0)` -- **Hardcoded JWT secret placeholder** — `jwt.secret` in `application.properties` is a placeholder; no enforcement of minimum entropy at startup - -### Architecture -- **SyncService race condition** — `running` boolean flag used for concurrency control without `volatile` or `AtomicBoolean`; unsafe under multi-thread access -- **MongoDB codec registry initialized per-request** — `MongoClientFactory` rebuilds codec registry on every call instead of caching it -- **DAO fieldName not validated** — dynamic field name injection in aggregation pipelines (e.g. sort fields) uses unvalidated strings; potential NoSQL injection vector - -### Configuration -- **API token in URL** — `nyc.api.app_token` appended as query parameter; should be in `Authorization` header -- **Plain-text credentials in `docker-compose.yml`** — PostgreSQL password `restaurant` hardcoded in compose file - -## Known Bugs - -- **Legacy address format** — Some older restaurant documents have flat address fields instead of the nested `Address` object; parsing falls back silently, producing null coordinates -- **Duplicate grades from pagination** — When NYC Open Data API returns overlapping pages during sync, duplicate grade entries can accumulate in MongoDB -- **NPE if no grades** — `getLatestGrade()` in `RestaurantService` assumes non-empty grade list; throws NPE on restaurants with no inspection history - -## Security - -| Issue | Location | Severity | -|---|---|---| -| CORS wildcard (`*`) | `SecurityConfig.java` | High | -| JWT validation swallows exceptions | `JwtAuthenticationFilter.java` | Medium | -| NoSQL injection via unvalidated sort field | `RestaurantDAOImpl.java` | Medium | -| API key in query param (not header) | `NycOpenDataClient.java` | Low | -| Hardcoded Docker credentials | `docker-compose.yml` | Low | -| No rate limiting on auth endpoints | `AuthController.java` | Medium | - -## Performance - -- **N+1 queries in `getHygieneRadarRestaurants`** — fetches restaurant list then queries each grade individually instead of using a single aggregation -- **Unbounded aggregation memory** — `$group` stages in several pipelines have no `$limit` before grouping; can cause OOM on full dataset -- **Redis serialization overhead** — objects serialized to JSON string in Redis; no binary serialization (e.g. MessagePack) -- **Sync blocks cache operations** — `SyncService` does not invalidate Redis during sync, so stale data can be served mid-sync for up to 3600s - -## Fragile Areas - -- **Geospatial index creation** — `ensureIndexes()` in DAO runs `createIndex` without checking if index exists; fails silently on duplicate but adds startup latency -- **`SyncService.running` flag** — stop signal is not synchronized; a rapid start/stop sequence can leave the service in an inconsistent state -- **MongoDB codec registry** — custom POJOs registered with `PojoCodecProvider`; adding a new domain field without a codec causes silent deserialization failure (field is null) -- **`nyc.api.max_records=0`** — means unlimited; accidentally leaving this at 0 in production initiates a full sync that can take many minutes and exhaust memory - -## Scaling Limits - -- **Single MongoDB instance** — no replica set; no read scaling; data loss risk -- **Single Redis instance** — no Redis Sentinel/Cluster; cache failure brings down all hot-path endpoints -- **JWT token size** — adding more claims will inflate token size; no token size budget enforced -- **Unlimited API pagination** — `GET /api/restaurants/*` endpoints return full lists without pagination; large responses on full dataset - -## Dependencies at Risk - -| Dependency | Version | Concern | -|---|---|---| -| `spring-boot-starter-parent` | 2.6.15 | Spring Boot 2.x EOL (Nov 2024); no security patches | -| `jjwt` | 0.11.5 | Older JJWT API; `jjwt-api` 0.12.x has breaking changes | -| `dotenv-java` | 3.0.0 | Unmaintained; no recent releases | -| `mongodb-driver-sync` | 4.x (via Spring Boot BOM) | Pinned to older minor; MongoDB 7.x driver available | - -## Test Coverage Gaps - -- No controller-layer tests (`@WebMvcTest`) — HTTP error handling and serialization untested -- No Redis failure / connection error scenarios -- No SyncService concurrency / thread-safety tests -- No JWT token tampering or replay attack tests -- No PostgreSQL / JPA layer tests (UserRepository, BookmarkRepository) -- No end-to-end API tests (e.g. RestAssured, TestContainers) -- Integration tests require manual MongoDB setup — not runnable in CI without Docker - -## Observability - -- No structured logging (plain SLF4J string interpolation; not JSON) -- No distributed tracing (no Micrometer / OpenTelemetry) -- No health metrics beyond `/api/restaurants/health` endpoint -- No alerting on sync failures diff --git a/.planning/codebase/CONVENTIONS.md b/.planning/codebase/CONVENTIONS.md deleted file mode 100644 index b6713e4..0000000 --- a/.planning/codebase/CONVENTIONS.md +++ /dev/null @@ -1,164 +0,0 @@ -# Coding Conventions - -**Analysis Date:** 2026-03-27 - -## Naming Patterns - -**Files:** -- PascalCase for all Java class files: `Restaurant.java`, `RestaurantService.java`, `ValidationUtil.java` -- Interface naming: Interface + Impl pattern for implementations: `RestaurantDAO.java` (interface) → `RestaurantDAOImpl.java` (implementation) -- Test files use Test or IntegrationTest suffix: `RestaurantServiceTest.java`, `RestaurantDAOIntegrationTest.java` - -**Functions/Methods:** -- camelCase for all method names -- Getters follow Java bean convention: `getLatestGrade()`, `getBadgeColor()`, `getRestaurantId()` -- Setters follow Java bean convention: `setName()`, `setGrades()`, `setCuisine()` -- Query methods in DAO use `find*` prefix for retrieval operations: `findCountByBorough()`, `findByCuisine()`, `findRandom()`, `findRecentlyInspected()` -- Service methods use `get*` prefix: `getRestaurantCountByBorough()`, `getWorstCuisinesByAverageScoreInBorough()`, `getAtRiskRestaurants()` -- Validation methods use `require*` prefix: `requireNonEmpty()`, `requirePositive()`, `validateFieldName()` -- Helper methods use descriptive verb-noun pattern: `getLatestGradeEntry()`, `restaurantWithGrades()`, `errorResponse()` - -**Variables:** -- camelCase for local variables and instance variables: `restaurantDAO`, `cuisineFilter`, `worstCuisines`, `maxScore` -- Constants in UPPER_SNAKE_CASE: `KEY_BY_BOROUGH`, `KEY_CUISINE_SCORES_PREFIX`, `MAX_RETRIES`, `TYPE_AGG_COUNT` -- Private fields use `private` visibility with camelCase: `private RestaurantDAO restaurantDAO`, `private StringRedisTemplate redis` - -**Types:** -- PascalCase for class names: `Restaurant`, `Grade`, `Address`, `UserEntity` -- Interface names use descriptive nouns: `RestaurantDAO` -- DTO (Data Transfer Object) suffix pattern: `AuthRequest`, `JwtResponse`, `RegisterRequest`, `HeatmapPoint` -- Entity suffix for JPA entities: `UserEntity`, `BookmarkEntity` -- Service suffix for business logic services: `RestaurantService`, `AuthService`, `RestaurantCacheService` -- Util/Utility suffix for utility/helper classes: `ValidationUtil`, `ResponseUtil` - -## Code Style - -**Formatting:** -- Java 11 target (source and compiler target set in `pom.xml`) -- UTF-8 encoding enforced via Maven compiler plugin configuration -- No explicit formatter tool configured (follows Spring Boot/Maven defaults) -- Indentation: implied 4 spaces (standard Java convention) - -**Linting:** -- No explicit linting tool configured -- Code follows Spring Boot conventions by default - -## Import Organization - -**Order:** -1. Standard Java imports (`java.util.*`, `java.io.*`, etc.) -2. javax imports (`javax.servlet.*`) -3. Spring imports (`org.springframework.*`) -4. Third-party library imports (`org.mongodb.*`, `io.jsonwebtoken.*`, `com.fasterxml.jackson.*`, `io.swagger.*`) -5. Project-specific imports (`com.aflokkat.*`) - -**Path Aliases:** -- No aliases configured; uses fully qualified package names -- Package structure reflects application layers: `com.aflokkat.{domain|service|dao|controller|config|cache|security|util|sync|dto|entity|repository}` - -## Error Handling - -**Patterns:** -- Input validation throws `IllegalArgumentException` with descriptive messages: - - Example from `ValidationUtil.requireNonEmpty()`: "fieldName ne peut pas être null ou vide" - - Example from `ValidationUtil.requirePositive()`: "limit doit être positif, reçu: -1" -- Service layer calls `ValidationUtil` methods before executing business logic (see `RestaurantService.getWorstCuisinesByAverageScoreInBorough()` lines 62-63) -- Controllers catch all exceptions and delegate to `ResponseUtil.errorResponse()` which: - - Returns HTTP 400 for `IllegalArgumentException` (client error) - - Returns HTTP 500 for other exceptions (server error) - - Response format: `{"status": "error", "message": "..."}` -- DAO layer validates field names using `validateFieldName()` to prevent injection attacks (MongoDB aggregation pipelines) -- Cache failures are swallowed with warning logs for graceful degradation (see `RestaurantCacheService` lines 97, 106, 141, 160, 188) - -## Logging - -**Framework:** SLF4J with Logback (provided by Spring Boot starter-logging) - -**Logger declaration pattern:** -```java -private static final Logger logger = LoggerFactory.getLogger(ClassName.class); -``` - -**Patterns:** -- `logger.info()` for significant operational events: data sync started/completed, cache operations, upsert counts - - Example: `logger.info("Fetched {} records (total so far: {})", page.size(), all.size());` -- `logger.debug()` for detailed diagnostic information: method entry/exit, query execution - - Example: `logger.debug("Agrégation: comptage par champ '{}'", fieldName);` -- `logger.warn()` for potentially harmful situations: failed cache operations, API retry attempts - - Example: `logger.warn("Cache read failed for key {}: {}", key, e.getMessage());` -- `logger.error()` for error conditions: sync failures with stack trace - - Example: `logger.error("Sync failed: {}", e.getMessage(), e);` -- Application logging level configured in `application.properties`: root=INFO, com.aflokkat=DEBUG - -## Comments - -**When to Comment:** -- French comments used for conceptual explanation: "Classe utilitaire" (utility class), "Valide qu'une string n'est pas null ou vide" (validates string is not null or empty) -- English comments used for technical/business logic clarification and implementation notes -- Use case headers with comment blocks: `// =============== USE CASE 1 ===============` -- Complex algorithms documented: "Lower score = better (fewer violations)" comment in trend calculation - -**JSDoc/JavaDoc:** -- Method-level JavaDoc used for public methods in interfaces and services, particularly: - - DAO interface methods have full JavaDoc describing parameters and return values - - Service methods have JavaDoc explaining business logic and use cases - - Controllers use Swagger/OpenAPI annotations (`@Operation`, `@Parameter`, `@Tag`) instead of raw JavaDoc -- Constructor and field comments minimal; rely on naming clarity -- Example (from `RestaurantDAO.java` lines 14-16): `/** Récupère tous les restaurants avec limite */` - -## Function Design - -**Size:** -- Service methods typically 3-10 lines for delegation to DAO -- Business logic methods 10-30 lines for computationally intensive operations (e.g., `getHygieneRadarRestaurants()` is 38 lines) -- Helper/utility methods 5-15 lines -- No explicit size limits enforced; follows pragmatic sizing based on cohesion - -**Parameters:** -- Validation parameters at method entry using `ValidationUtil` checks -- Service methods pass simple types (String, int, double): `getWorstCuisinesByAverageScoreInBorough(String borough, int limit)` -- DAO methods use `Map` for complex filtering: `findWithFilters(Map filters, int limit)` -- Controllers use `@RequestParam` annotations with default values -- Helper methods use varargs for collections: `restaurantWithGrades(Grade... grades)` - -**Return Values:** -- Explicit null returns for "not found" cases: `getLatestGrade()` returns null if no grades -- Empty collections preferred over null for collections: `findAverageScoreByCuisineAndBorough()` returns empty list vs null (see integration test line 105) -- Wrapped responses in controllers: `{"status": "success", "data": [...], "count": N}` -- Static helper methods return computed values: `getBadgeColor()` returns String, `getLatitude()` returns Double - -## Module Design - -**Exports:** -- All public classes are beans eligible for Spring dependency injection (marked with `@Service`, `@Controller`, `@Configuration`, `@Repository`) -- DAO interface pattern: interface defines contract in `RestaurantDAO.java`, implementation in `RestaurantDAOImpl.java` -- Services delegate to DAOs for persistence operations -- Controllers depend on Services (never directly on DAOs) - -**Barrel Files:** -- No barrel/index files used -- Each class is in its own file following Java convention -- Package-level organization provides logical grouping - -## Code Structure Patterns - -**Layering:** -- Controller → Service → DAO pattern strictly enforced: - - Controllers (`RestaurantController.java`) call Services - - Services call DAOs - - DAOs directly access MongoDB or call cache layer -- Cross-cutting concerns separated: - - Validation: `ValidationUtil` utility class - - Response formatting: `ResponseUtil` utility class - - Caching: `RestaurantCacheService` (service-level cache wrapper) - - Security: `JwtUtil`, `JwtAuthenticationFilter`, `SecurityConfig` - -**DTO vs Domain:** -- Domain POJOs (`Restaurant.java`, `Grade.java`, `Address.java`) map directly from MongoDB using BSON annotations -- DTOs (`AuthRequest.java`, `JwtResponse.java`, `HeatmapPoint.java`) used for API contracts -- Computed fields extracted from domain into service layer (not persisted in POJO): `getLatestGrade()`, `getTrend()`, `getBadgeColor()` -- View mapping method `RestaurantService.toView()` builds view Map for controllers (lines 263-280) - ---- - -*Convention analysis: 2026-03-27* diff --git a/.planning/codebase/INTEGRATIONS.md b/.planning/codebase/INTEGRATIONS.md deleted file mode 100644 index 60d822b..0000000 --- a/.planning/codebase/INTEGRATIONS.md +++ /dev/null @@ -1,217 +0,0 @@ -# External Integrations - -**Analysis Date:** 2026-03-27 - -## APIs & External Services - -**NYC Open Data API:** -- Service: NYC Open Data - New York City restaurant inspection records -- What it's used for: Real-time data sync of restaurant inspection data, grades, and violations -- SDK/Client: `org.springframework.web.client.RestTemplate` (Spring Web built-in) -- Implementation: `com.aflokkat.sync.NycOpenDataClient` -- Endpoint: `https://data.cityofnewyork.us/resource/43nn-pn8j.json` -- Auth: Optional app token via `nyc.api.app_token` property (avoids rate limiting, not required) -- Pagination: Configurable page size (default 1000 records), supports `$offset` and `$limit` query params -- Retry Strategy: Exponential backoff with 3 retries, 2000ms initial delay, doubles on each retry -- Configuration: - - URL: `nyc.api.url` property (default: `https://data.cityofnewyork.us/resource/43nn-pn8j.json`) - - Token: `nyc.api.app_token` (empty string = no auth) - - Page size: `nyc.api.page-size` (default: 1000) - - Max records: `nyc.api.max_records` (0 = unlimited, set small value for local testing) - -## Data Storage - -**Databases:** - -**MongoDB (Primary NoSQL):** -- Provider: MongoDB (self-hosted via Docker or remote URI) -- Purpose: Stores restaurant inspection data, aggregations, historical records -- Connection: URI-based via `mongodb.uri` property (default: `mongodb://mongodb:27017`) -- Database: `newyork` (configurable) -- Collection: `restaurants` (configurable) -- Client: `com.mongodb.client.MongoClient` (native synchronous driver via `org.mongodb:mongodb-driver-sync`) -- Connection Management: Singleton `MongoClientFactory` ensures single instance per JVM -- Configuration class: `com.aflokkat.config.MongoClientFactory` -- Access layer: `com.aflokkat.dao.RestaurantDAOImpl` - Raw aggregation pipelines (no Spring Data MongoDB) -- Environment override: `MONGODB_URI`, `MONGODB_DATABASE`, `MONGODB_COLLECTION` - -**PostgreSQL (Relational - Users & Bookmarks):** -- Provider: PostgreSQL 15 -- Purpose: Stores user accounts, authentication credentials, user bookmarks -- Connection: JDBC URL `jdbc:postgresql://postgres:5432/restaurantdb` (configurable) -- Credentials: Default `restaurant` / `restaurant` (configurable via Spring properties) -- Client: Spring Data JPA with Hibernate ORM -- Configuration: - - Driver: `org.postgresql.Driver` - - Dialect: `org.hibernate.dialect.PostgreSQLDialect` - - DDL: `spring.jpa.hibernate.ddl-auto=update` (auto-creates/updates schema) -- Repositories: - - `com.aflokkat.repository.UserRepository` - Spring JPA repository for `UserEntity` - - `com.aflokkat.repository.BookmarkRepository` - Spring JPA repository for `BookmarkEntity` -- Entities: - - `com.aflokkat.entity.UserEntity` - username, email, password_hash, role - - `com.aflokkat.entity.BookmarkEntity` - user_id, restaurant_id, created_at - -**File Storage:** -- Not used - All data is persisted in MongoDB and PostgreSQL - -**Caching:** -- Redis 7 (Alpine Linux Docker image) -- Purpose: TTL-based caching for expensive MongoDB aggregation queries -- Connection: Standalone configuration via Lettuce connection factory -- Configuration: - - Host: `redis.host` property (default: `localhost`) - - Port: `redis.port` property (default: 6379) - - TTL: `redis.cache.ttl-seconds` (default: 3600 seconds / 1 hour) -- Service: `com.aflokkat.cache.RestaurantCacheService` -- Access Pattern: Cache-aside (get/load/store on miss) -- Cached Keys: - - `restaurants:by_borough` - Borough counts aggregation - - `restaurants:cuisine_scores:{cuisine}` - Average scores by borough for a cuisine - - `restaurants:worst_cuisines:{borough}:{limit}` - Worst cuisines in a borough - - `restaurants:top` - Sorted set of top/healthiest restaurants (sorted by inspection score) -- Graceful Degradation: All Redis failures logged as warnings; app continues without cache - -## Authentication & Identity - -**Auth Provider:** -- Custom JWT-based authentication (no external provider) -- Implementation: `com.aflokkat.service.AuthService` + `com.aflokkat.security.JwtUtil` - -**JWT Tokens:** -- Algorithm: HMAC SHA-256 (HS256) -- Secret: Minimum 32 characters, configured via `jwt.secret` property -- Access Token: - - Expiration: 15 minutes (900000 ms, configurable via `jwt.access.expiration.ms`) - - Claims: subject (username), role, iat, exp -- Refresh Token: - - Expiration: 7 days (604800000 ms, configurable via `jwt.refresh.expiration.ms`) - - Claims: subject (username), iat, exp -- Endpoint: `POST /api/auth/register`, `POST /api/auth/login`, `POST /api/auth/refresh` - -**Password Encoding:** -- Spring Security `PasswordEncoder` (BCrypt via `spring-boot-starter-security`) -- Passwords hashed and salted before storage in PostgreSQL - -**Request Authentication:** -- JWT validation via `com.aflokkat.security.JwtAuthenticationFilter` -- Filter intercepts all `/api/*` requests -- Bearer token extraction from `Authorization: Bearer {token}` header -- Invalid/expired tokens return 401 Unauthorized - -## Monitoring & Observability - -**Error Tracking:** -- Not configured - No external error tracking service (Sentry, DataDog, etc.) - -**Logs:** -- Framework: SLF4J + Logback (included by `spring-boot-starter-logging`) -- Configuration: `src/main/resources/application.properties` - - Root level: `INFO` - - Application package: `DEBUG` (logs from `com.aflokkat`) -- Output: Console/stdout (standard Docker logging) -- Key log sources: - - `NycOpenDataClient` - API sync attempts, retries, failures - - `RestaurantCacheService` - Cache hits/misses, invalidations, Redis errors - - `SyncService` - Data sync lifecycle events - - `AuthService` - Authentication events - -**Health Checks:** -- Endpoint: `GET /api/restaurants/health` -- Docker Compose health check: Polls endpoint every 30s with 10s timeout, 3 retries -- Response: Used for service readiness in orchestration - -## CI/CD & Deployment - -**Hosting:** -- Docker (containerized Java application) -- Deployment: Docker Compose (local dev) or any container orchestrator (K8s, Docker Swarm, etc.) - -**CI Pipeline:** -- Not configured - No GitHub Actions, Jenkins, GitLab CI, etc. in repository - -**Container Image:** -- Multi-stage Dockerfile: Maven build stage → Java 21 JRE runtime -- Base image (production): `eclipse-temurin:21-jre-jammy` (Debian 12) -- Build image: `maven:3.8-eclipse-temurin-21` -- Exposed port: 8080 -- Default ENTRYPOINT: `java -jar app.jar` -- Environment variables pre-set in Dockerfile (can be overridden by Docker Compose) - -**Docker Compose Orchestration:** -- 4 services: app (Spring Boot), mongodb, redis, postgres -- Networking: `restaurant-network` (bridge driver) -- Persistent volumes: `mongodb_data`, `postgres_data` -- Service dependencies: App depends on mongodb, redis, postgres (with health check conditions) -- Restart policy: `unless-stopped` (automatic recovery on crash) - -## Environment Configuration - -**Required Environment Variables:** - -**MongoDB:** -- `MONGODB_URI` - Connection string (default: `mongodb://mongodb:27017`) -- `MONGODB_DATABASE` - Database name (default: `newyork`) -- `MONGODB_COLLECTION` - Collection name (default: `restaurants`) - -**PostgreSQL:** -- `spring.datasource.url` - JDBC URL (default: `jdbc:postgresql://postgres:5432/restaurantdb`) -- `spring.datasource.username` - User (default: `restaurant`) -- `spring.datasource.password` - Password (default: `restaurant`) - -**Redis:** -- `REDIS_HOST` - Hostname (default: `localhost`) -- `REDIS_PORT` - Port (default: `6379`) -- `redis.cache.ttl-seconds` - Cache TTL (default: 3600) - -**JWT Security:** -- `jwt.secret` - Signing secret, minimum 32 characters (no default - must be set) -- `jwt.access.expiration.ms` - Access token lifetime (default: 900000) -- `jwt.refresh.expiration.ms` - Refresh token lifetime (default: 604800000) - -**NYC Open Data API:** -- `nyc.api.url` - API endpoint (default: `https://data.cityofnewyork.us/resource/43nn-pn8j.json`) -- `nyc.api.app_token` - Optional app token for rate limit increase (empty/optional) -- `nyc.api.page-size` - Pagination size (default: 1000) -- `nyc.api.max_records` - Max records to sync (0 = unlimited, set small for local testing) - -**Configuration Priority:** -1. System environment variables (Docker Compose `environment:` section) -2. `.env` file (local development only, loaded by dotenv-java) -3. `src/main/resources/application.properties` (defaults) - -**Secrets Location:** -- Secrets NOT committed to git -- `.env` file listed in `.gitignore` (local only) -- Docker Compose environment variables passed at runtime -- Production: Use container secrets management (Docker Secrets, K8s Secrets, HashiCorp Vault, etc.) - -## Webhooks & Callbacks - -**Incoming:** -- None - API is request-response only (no webhook consumers) - -**Outgoing:** -- None - No external systems are called via webhook (only NYC Open Data API via scheduled sync) - -## Data Sync Flow - -**Scheduled Sync:** -- Trigger: `com.aflokkat.sync.SyncService` (Spring `@Scheduled` task, configurable pool size: 2 threads) -- Process: - 1. `NycOpenDataClient.fetchAll()` - HTTP paginated fetch from NYC Open Data API - 2. Transform raw DTOs to `Restaurant` domain objects - 3. Bulk upsert into MongoDB `restaurants` collection - 4. Invalidate Redis cache (delete all `restaurants:*` keys) - 5. Rebuild top restaurants sorted set - -**Sync Configuration:** -- Thread pool size: `spring.task.scheduling.pool.size=2` -- API endpoint: `https://data.cityofnewyork.us/resource/43nn-pn8j.json` -- Pagination: 1000 records per page (configurable) -- Retry: 3 attempts with exponential backoff (2s, 4s, 8s) -- Error handling: Exceptions logged, retried on next cycle (if scheduled) - ---- - -*Integration audit: 2026-03-27* diff --git a/.planning/codebase/STACK.md b/.planning/codebase/STACK.md deleted file mode 100644 index 26ed279..0000000 --- a/.planning/codebase/STACK.md +++ /dev/null @@ -1,125 +0,0 @@ -# Technology Stack - -**Analysis Date:** 2026-03-27 - -## Languages - -**Primary:** -- Java 11 - All backend logic, REST API, configuration, data access layers - -**Build Language:** -- YAML - Docker Compose configuration (`docker-compose.yml`) - -## Runtime - -**Environment:** -- Java 21 JRE (production container `eclipse-temurin:21-jre-jammy`) -- Java 21 with Maven 3.8 (build container `maven:3.8-eclipse-temurin-21`) - -**Package Manager:** -- Maven 3.8 -- Lockfile: `pom.xml` (XML manifest with pinned dependency versions) - -## Frameworks - -**Core:** -- Spring Boot 2.6.15 - REST API framework, dependency injection, auto-configuration -- Spring Web Starter - HTTP server, servlet container, request handling -- Spring Data JPA - PostgreSQL ORM for users and bookmarks entities -- Spring Security - Authentication, authorization, password encoding -- Spring Data Redis - Redis connection management and template operations - -**Template Engine:** -- Thymeleaf - Server-side rendering for web dashboard views - -**Testing:** -- JUnit 4 (version 4.13.2) - Test runner and assertions -- Mockito (Spring Boot 2.6 managed version ~4.x) - Object mocking for unit tests -- Mockito JUnit Jupiter - Integration with JUnit 5 for Spring Boot Test suite - -**Build/Dev:** -- Spring Boot Maven Plugin - Packaging, running, and managing Spring Boot apps -- Maven Compiler Plugin 3.13.0 - Java 11 source/target compilation - -**API Documentation:** -- springdoc-openapi-ui 1.8.0 - Generates OpenAPI 3.0 spec and Swagger UI at `/swagger-ui.html` - -## Key Dependencies - -**Critical:** -- `mongodb-driver-sync` (Spring Boot 2.6 managed) - Raw MongoDB driver for synchronous queries, aggregation pipelines (no Spring Data MongoDB ORM) -- `postgresql` (Spring Boot 2.6 managed) - PostgreSQL JDBC driver for relational data -- `spring-boot-starter-data-redis` - Redis client via Lettuce connection factory - -**Security:** -- `jjwt-api` 0.11.5 - JWT token generation and validation (API only) -- `jjwt-impl` 0.11.5 - JJWT implementation (runtime scope) -- `jjwt-jackson` 0.11.5 - JJWT Jackson serialization (runtime scope) - -**Configuration:** -- `dotenv-java` 3.0.0 - Loads `.env` files for environment variable configuration (fallback after system env vars) - -**Logging:** -- `spring-boot-starter-logging` - SLF4J + Logback logging framework (included by Spring Boot) - -## Configuration - -**Environment:** -- Configured via priority chain: - 1. System environment variables (set by Docker Compose or CI/CD) - 2. `.env` file (local development, optional) - 3. `src/main/resources/application.properties` (default/fallback values) -- Config class: `com.aflokkat.config.AppConfig` - centralized property accessors - -**Key Configuration Files:** -- `src/main/resources/application.properties` - Default settings for MongoDB, PostgreSQL, Redis, JWT, NYC API, logging levels -- `docker-compose.yml` - Service orchestration with environment variable overrides -- `Dockerfile` - Multi-stage build: Maven builder stage → Java 21 JRE production stage - -**Environment Variables (Docker/System):** -- `MONGODB_URI` - MongoDB connection string (default: `mongodb://mongodb:27017`) -- `MONGODB_DATABASE` - Database name (default: `newyork`) -- `MONGODB_COLLECTION` - Collection name (default: `restaurants`) -- `REDIS_HOST` - Redis hostname (default: `localhost`) -- `REDIS_PORT` - Redis port (default: `6379`) -- Key application properties can also be overridden as `MONGODB_URI`, `REDIS_HOST`, etc. (dot notation converted to underscore, uppercased) - -## Build Configuration - -**Maven Build:** -- Java source/target: 11 -- Encoding: UTF-8 -- Clean build removes artifacts: `mvn clean package -DskipTests` -- JAR output: `target/quickstart-app-1.0-SNAPSHOT.jar` - -**Docker Multi-Stage Build:** -- Stage 1 (builder): Maven 3.8 + Java 21 - compiles, runs unit tests (if not skipped), generates JAR -- Stage 2 (production): Java 21 JRE only - runs JAR, exposes port 8080 - -## Platform Requirements - -**Development:** -- Java 11+ (source/target compatibility) -- Maven 3.8+ -- Docker & Docker Compose (plugin version `docker compose`, not `docker-compose`) -- Local MongoDB on `localhost:27017` (for integration tests) - -**Production:** -- Docker runtime -- 4 services in Docker Compose network: - - `restaurant-app` (Spring Boot JAR) - port 8080 - - `mongodb` (latest) - port 27017 - - `redis` (7-alpine) - port 6379 - - `postgres` (15) - port 5432 -- Health checks enabled on all services -- Persistent volumes: `mongodb_data`, `postgres_data` - -**Minimum Resources:** -- 2GB heap for JVM (Spring Boot defaults) -- 512MB for MongoDB -- 256MB for Redis -- 512MB for PostgreSQL - ---- - -*Stack analysis: 2026-03-27* diff --git a/.planning/codebase/STRUCTURE.md b/.planning/codebase/STRUCTURE.md deleted file mode 100644 index e8d07d0..0000000 --- a/.planning/codebase/STRUCTURE.md +++ /dev/null @@ -1,693 +0,0 @@ -# Codebase Structure - -**Analysis Date:** 2026-03-27 - -## Directory Layout - -``` -quickstart-app/ -├── src/ -│ ├── main/ -│ │ ├── java/com/aflokkat/ -│ │ │ ├── Application.java # Spring Boot entry point -│ │ │ ├── aggregation/ # MongoDB aggregation result POJOs -│ │ │ │ ├── AggregationCount.java -│ │ │ │ ├── BoroughCuisineScore.java -│ │ │ │ └── CuisineScore.java -│ │ │ ├── cache/ # Redis cache-aside layer -│ │ │ │ └── RestaurantCacheService.java -│ │ │ ├── config/ # Spring config, singletons -│ │ │ │ ├── AppConfig.java # property loader (env → .env → props) -│ │ │ │ ├── MongoClientFactory.java # MongoDB singleton -│ │ │ │ ├── RedisConfig.java # StringRedisTemplate bean -│ │ │ │ ├── SecurityConfig.java # JWT filter chain -│ │ │ │ └── OpenApiConfig.java # Swagger/OpenAPI -│ │ │ ├── controller/ # REST API endpoints (18+ endpoints) -│ │ │ │ ├── RestaurantController.java -│ │ │ │ ├── AuthController.java -│ │ │ │ ├── InspectionController.java -│ │ │ │ ├── UserController.java -│ │ │ │ └── ViewController.java -│ │ │ ├── dao/ # MongoDB data access -│ │ │ │ ├── RestaurantDAO.java # interface (29 methods) -│ │ │ │ └── RestaurantDAOImpl.java # aggregation pipelines -│ │ │ ├── domain/ # MongoDB POJO models -│ │ │ │ ├── Restaurant.java # aggregate root -│ │ │ │ ├── Address.java # nested document -│ │ │ │ └── Grade.java # inspection record -│ │ │ ├── dto/ # Request/response DTOs -│ │ │ │ ├── AuthRequest.java -│ │ │ │ ├── RegisterRequest.java -│ │ │ │ ├── JwtResponse.java -│ │ │ │ ├── RefreshRequest.java -│ │ │ │ ├── HeatmapPoint.java -│ │ │ │ ├── TopRestaurantEntry.java -│ │ │ │ └── AtRiskEntry.java -│ │ │ ├── entity/ # JPA entities (PostgreSQL) -│ │ │ │ ├── UserEntity.java -│ │ │ │ └── BookmarkEntity.java -│ │ │ ├── repository/ # Spring JPA repositories -│ │ │ │ ├── UserRepository.java -│ │ │ │ └── BookmarkRepository.java -│ │ │ ├── security/ # JWT authentication -│ │ │ │ ├── JwtUtil.java # token generation/validation -│ │ │ │ └── JwtAuthenticationFilter.java -│ │ │ ├── service/ # Business logic layer -│ │ │ │ ├── RestaurantService.java # analytics, computed fields -│ │ │ │ └── AuthService.java # user auth -│ │ │ ├── sync/ # NYC API sync orchestration -│ │ │ │ ├── SyncService.java # scheduler, nightly 02:00 -│ │ │ │ ├── NycOpenDataClient.java # HTTP REST client -│ │ │ │ ├── NycApiRestaurantDto.java # API response DTO -│ │ │ │ └── SyncResult.java # sync metadata -│ │ │ └── util/ # Shared utilities -│ │ │ ├── ValidationUtil.java -│ │ │ └── ResponseUtil.java -│ │ └── resources/ -│ │ ├── application.properties # Spring config (main) -│ │ ├── simplelogger.properties # SLF4J logging config -│ │ └── templates/ # HTML templates (Thymeleaf) -│ │ ├── index.html -│ │ ├── login.html -│ │ ├── restaurant.html -│ │ ├── inspection.html -│ │ ├── inspection-map.html -│ │ └── hygiene-radar.html -│ ├── test/ -│ │ └── java/com/aflokkat/ -│ │ ├── dao/ # DAO integration tests (64 tests) -│ │ ├── domain/ -│ │ ├── sync/ -│ │ ├── security/ -│ │ ├── util/ -│ │ ├── cache/ -│ │ ├── config/ -│ │ ├── service/ -│ │ └── aggregation/ -├── pom.xml # Maven build config -├── docker-compose.yml # 4 containers: app, MongoDB, Redis, PostgreSQL -├── Dockerfile # Spring Boot app image -├── application.properties # (in src/main/resources) -├── CLAUDE.md # Project context document -└── README.md # Project documentation -``` - -## Directory Purposes - -**`src/main/java/com/aflokkat/`:** -- Purpose: Main Java application code -- Contains: Package-organized classes by layer (controller, service, DAO, etc.) - -**`aggregation/`:** -- Purpose: Intermediate POJOs for MongoDB aggregation pipeline results -- Contains: `AggregationCount`, `BoroughCuisineScore`, `CuisineScore` -- When used: Service layer returns these after aggregation queries - -**`cache/`:** -- Purpose: Redis cache-aside implementation for expensive queries -- Contains: `RestaurantCacheService` (single bean) -- When used: Controllers call `cacheService.getOrLoad(key, supplier, typeRef)` - -**`config/`:** -- Purpose: Application-wide configuration, Spring beans, singletons -- Contains: Property loading, MongoDB/Redis connections, security setup, Swagger -- Key pattern: `AppConfig` centralizes all property resolution (env → .env → application.properties) - -**`controller/`:** -- Purpose: HTTP REST API endpoints and response handling -- Contains: 5 controller classes with @RestController and @RequestMapping annotations -- Pattern: controllers are thin — they validate, delegate to service, format response - -**`dao/`:** -- Purpose: MongoDB data access layer using raw driver -- Contains: Interface `RestaurantDAO` (29 method signatures) and implementation `RestaurantDAOImpl` -- Key feature: Constructs raw BSON aggregation pipelines (no Spring Data MongoDB) -- POJO codec: uses `PojoCodecProvider` for automatic Restaurant POJO mapping - -**`domain/`:** -- Purpose: MongoDB document models (POJOs with BSON annotations) -- Contains: `Restaurant` (main aggregate), `Address` (nested), `Grade` (inspection records) -- Annotations: `@BsonProperty` maps Java fields to MongoDB document fields - -**`dto/`:** -- Purpose: Request/response DTOs for controllers and cache serialization -- Contains: Auth DTOs (`AuthRequest`, `JwtResponse`), query result DTOs (`HeatmapPoint`, `TopRestaurantEntry`) - -**`entity/`:** -- Purpose: JPA entities for PostgreSQL (users and bookmarks) -- Contains: `UserEntity`, `BookmarkEntity` with @Entity and @Table annotations - -**`repository/`:** -- Purpose: Spring Data JPA repositories for PostgreSQL -- Contains: `UserRepository`, `BookmarkRepository` -- Pattern: Spring-generated CRUD + custom queries - -**`security/`:** -- Purpose: JWT token generation, validation, and HTTP filter -- Contains: `JwtUtil` (token ops) and `JwtAuthenticationFilter` (request interceptor) -- Token handling: HMAC-SHA256, access (15min) and refresh (7 days) tokens - -**`service/`:** -- Purpose: Business logic and orchestration -- Contains: `RestaurantService` (analytics use-cases, computed fields), `AuthService` (user auth) -- Pattern: services validate input via `ValidationUtil`, delegate to DAO/repositories, compute output - -**`sync/`:** -- Purpose: Nightly data sync from NYC Open Data API -- Contains: `SyncService` (scheduler + runner), `NycOpenDataClient` (HTTP), DTOs and results -- Scheduler: cron 0 0 2 * * * (daily 02:00 local time) -- Flow: fetch → group by camis → map to Restaurants → upsert → invalidate cache - -**`util/`:** -- Purpose: Shared utility functions -- Contains: `ValidationUtil` (input validation), `ResponseUtil` (error formatting) - -**`src/main/resources/templates/`:** -- Purpose: Thymeleaf HTML templates for web views -- Contains: Dashboard pages (index, restaurant detail, inspection map, hygiene radar, login) -- Served by: `ViewController` endpoints - -## Key File Locations - -**Entry Points:** -- `src/main/java/com/aflokkat/Application.java` — Spring Boot application entry point with `@SpringBootApplication` and `@EnableScheduling` -- `src/main/resources/application.properties` — Spring Boot configuration (server port, DB URIs, API settings, JWT) - -**Configuration:** -- `src/main/java/com/aflokkat/config/AppConfig.java` — centralized property resolution -- `src/main/java/com/aflokkat/config/MongoClientFactory.java` — MongoDB singleton client -- `src/main/java/com/aflokkat/config/SecurityConfig.java` — Spring Security + JWT filter chain -- `docker-compose.yml` — 4-container setup (app, MongoDB, Redis, PostgreSQL) - -**Core Logic:** -- `src/main/java/com/aflokkat/service/RestaurantService.java` — analytics methods, computed fields (latest grade, trend, badge color, coordinates) -- `src/main/java/com/aflokkat/dao/RestaurantDAOImpl.java` — MongoDB aggregation pipelines -- `src/main/java/com/aflokkat/sync/SyncService.java` — nightly data sync orchestration - -**Testing:** -- `src/test/java/com/aflokkat/` — 64+ JUnit 4 tests with Mockito -- Test categories: DAO integration tests, service unit tests, security tests, cache tests, config tests - -**APIs:** -- REST endpoints: see `src/main/java/com/aflokkat/controller/RestaurantController.java` (18 endpoints) -- Swagger UI: `http://localhost:8080/swagger-ui.html` -- Base path: `/api/` (restaurants, auth, users, inspections) - -## Naming Conventions - -**Files:** -- Class files: PascalCase (e.g., `RestaurantService.java`, `AuthController.java`) -- Interface files: PascalCase without "Impl" suffix (e.g., `RestaurantDAO.java`) -- Implementation files: PascalCase with "Impl" suffix (e.g., `RestaurantDAOImpl.java`) -- Test files: PascalCase + "Test" or "IntegrationTest" suffix (e.g., `RestaurantDAOIntegrationTest.java`) - -**Directories:** -- Package directories: lowercase, plural when appropriate (e.g., `controller/`, `service/`, `dao/`, `entity/`) -- Functional grouping by layer - -**Java Classes:** -- Class names: PascalCase (e.g., `Restaurant`, `RestaurantService`) -- Field names: camelCase (e.g., `restaurantId`, `bouroughCount`) -- Method names: camelCase, verbs preferred (e.g., `findCountByBorough()`, `getLatestGrade()`) -- Constants: UPPERCASE_SNAKE_CASE (e.g., `KEY_TOP`, `TYPE_AGG_COUNT`) - -**MongoDB Document Fields:** -- Snake_case in POJO `@BsonProperty` annotations (e.g., `restaurant_id`, `cuisine_description`) -- Java field names remain camelCase (mapped via annotations) - -## Where to Add New Code - -**New Analytics Endpoint:** -1. **DAO layer:** Add method to `RestaurantDAO` interface and implement in `RestaurantDAOImpl.java` with aggregation pipeline -2. **Service layer:** Add public method in `RestaurantService.java` that calls DAO and applies business logic -3. **Controller layer:** Add `@GetMapping` or `@PostMapping` in `RestaurantController.java` that calls service -4. **Optional caching:** Wrap service call in `RestaurantCacheService.getOrLoad()` for expensive queries -5. **Test:** Add unit test to `src/test/java/com/aflokkat/service/RestaurantServiceTest.java` - -**New Authentication Feature:** -1. **Entity layer:** Add/modify fields in `UserEntity.java` if needed -2. **Repository layer:** Add query method to `UserRepository.java` if needed -3. **Service layer:** Add logic to `AuthService.java` -4. **Controller layer:** Add endpoint to `AuthController.java` -5. **Security layer:** Modify `SecurityConfig.java` or `JwtUtil.java` if token structure changes -6. **Test:** Add test to `src/test/java/com/aflokkat/service/AuthServiceTest.java` - -**New User Feature (Bookmarks, Profile):** -1. **Entity layer:** Add/modify `UserEntity.java` or `BookmarkEntity.java` in `src/main/java/com/aflokkat/entity/` -2. **Repository layer:** Add methods to `UserRepository.java` or `BookmarkRepository.java` -3. **Service layer:** Create or modify service in `src/main/java/com/aflokkat/service/` -4. **Controller layer:** Add endpoints to `UserController.java` -5. **Test:** Add integration tests in `src/test/java/com/aflokkat/repository/` - -**New Data Sync Source:** -1. **DTO layer:** Create DTO for API response (e.g., `NewApiRestaurantDto.java`) -2. **Sync layer:** Create new client (e.g., `NewApiClient.java`) or extend `NycOpenDataClient.java` -3. **Service layer:** Add mapper in `SyncService.java` or new service to convert API DTO to domain `Restaurant` -4. **DAO layer:** Ensure `upsertRestaurants()` can handle the new data -5. **Test:** Add tests to `src/test/java/com/aflokkat/sync/` - -**New Utility Function:** -- Location: `src/main/java/com/aflokkat/util/` -- Pattern: Static methods in utility class (e.g., `ValidationUtil`, `ResponseUtil`) -- Scope: Shared across multiple layers, no business logic - -**New Web Template:** -- Location: `src/main/resources/templates/` -- Format: Thymeleaf HTML -- Served by: `ViewController` endpoints (add method + `@GetMapping` in `ViewController.java`) - -## Special Directories - -**`target/`:** -- Purpose: Maven build output -- Generated: Yes (mvn clean package) -- Committed: No (.gitignore) -- Contains: Compiled classes, JAR, dependencies - -**`src/test/`:** -- Purpose: Unit and integration tests -- Generated: No (manually written) -- Committed: Yes -- Pattern: Test classes mirror src/main structure; use JUnit 4 + Mockito - -**`docker-compose.yml`:** -- Purpose: Development/deployment environment specification -- Services: 4 containers (app, MongoDB, Redis, PostgreSQL) -- Environment: Database credentials, API configs passed as env vars to app container -- Volumes: MongoDB data persistence, PostgreSQL data persistence - -**`.planning/`:** -- Purpose: GSD (Goal, Strategy, Development) planning documents -- Generated: Yes (populated by orchestrator) -- Committed: Yes -- Contains: ARCHITECTURE.md, STRUCTURE.md, CONVENTIONS.md, TESTING.md, CONCERNS.md, STACK.md, INTEGRATIONS.md - -**`docs/` (if present):** -- For project documentation, API specs, deployment guides - -## Adding New Dependencies - -**Maven (pom.xml):** -- Add `` block to appropriate section (Spring Boot, testing, DB drivers, etc.) -- Run: `mvn clean install` -- Restart application - -**Spring Boot Auto-Configuration:** -- Drop JAR into classpath → Spring Boot auto-configures beans -- Example: `spring-boot-starter-redis` → `StringRedisTemplate` bean auto-created - ---- - -*Structure analysis: 2026-03-27* -``` - -Now I'll provide both complete documents as requested: - ---- - -# ARCHITECTURE.md (Complete Content) - -# Architecture - -**Analysis Date:** 2026-03-27 - -## Pattern Overview - -**Overall:** Layered MVC with Domain-Driven Design and Cache-Aside pattern - -**Key Characteristics:** -- Spring Boot 2.6.15 REST API following controller-service-DAO layers -- Raw MongoDB driver (mongodb-driver-sync) for aggregation pipelines, no Spring Data MongoDB -- PostgreSQL for user/bookmark persistence (Spring Data JPA) -- Redis cache-aside pattern for expensive MongoDB aggregations (3600s TTL) -- Scheduled data sync from NYC Open Data API (nightly at 02:00) with manual refresh endpoint -- JWT-based security with access (15min) and refresh (7 days) tokens -- POJO-based domain models with computed fields extracted to service layer - -## Layers - -**Controller Layer:** -- Purpose: REST API endpoints, request routing, response formatting -- Location: `src/main/java/com/aflokkat/controller/` -- Contains: - - `RestaurantController.java` — analytics endpoints (18 endpoints total) - - `AuthController.java` — JWT auth (register, login, refresh) - - `InspectionController.java` — inspection-specific queries - - `UserController.java` — user profile/bookmarks - - `ViewController.java` — HTML template serving -- Depends on: Service layer, DTO layer, Cache service -- Used by: HTTP clients (browsers, API consumers) - -**Service Layer:** -- Purpose: Business logic, input validation, computed field calculations -- Location: `src/main/java/com/aflokkat/service/` -- Contains: - - `RestaurantService.java` — restaurant queries, computed fields (latest grade, trend, badge color, coordinates), use-case implementations - - `AuthService.java` — user registration, login, token generation -- Depends on: DAO layer, ValidationUtil, domain models -- Used by: Controllers, SyncService, CacheService - -**DAO Layer:** -- Purpose: MongoDB data access via raw driver, aggregation pipeline construction -- Location: `src/main/java/com/aflokkat/dao/` -- Contains: - - `RestaurantDAO.java` — interface (29 methods) - - `RestaurantDAOImpl.java` — MongoDB aggregation pipelines, POJO codec registry -- Depends on: Domain models, MongoDB driver -- Used by: Service layer, Sync layer -- Note: Uses raw `mongodb-driver-sync` aggregation pipelines, not Spring Data MongoDB - -**Repository Layer (Spring JPA):** -- Purpose: PostgreSQL persistence for users and bookmarks -- Location: `src/main/java/com/aflokkat/repository/` -- Contains: - - `UserRepository.java` — Spring JPA for `UserEntity` - - `BookmarkRepository.java` — Spring JPA for `BookmarkEntity` -- Depends on: JPA/Hibernate -- Used by: AuthService, UserController - -**Sync Layer:** -- Purpose: Orchestrate NYC Open Data API fetch → map → MongoDB upsert -- Location: `src/main/java/com/aflokkat/sync/` -- Contains: - - `SyncService.java` — nightly scheduler (02:00), manual trigger, result tracking - - `NycOpenDataClient.java` — HTTP REST calls to NYC Open Data API - - `NycApiRestaurantDto.java` — DTO for API response mapping - - `SyncResult.java` — sync metadata (counts, timestamps, error) -- Depends on: RestaurantDAO, RestaurantCacheService, config -- Used by: Application startup, scheduler, POST `/api/restaurants/refresh` endpoint -- Flow: NYC API → fetch all records → group by `camis` → map inspection rows to grades → upsert restaurants → invalidate cache - -**Cache Layer:** -- Purpose: Redis cache-aside for expensive MongoDB aggregations; sorted set for top restaurants -- Location: `src/main/java/com/aflokkat/cache/` -- Contains: `RestaurantCacheService.java` -- Depends on: Spring Data Redis, ObjectMapper, configuration -- Used by: Controllers (cache-aside calls), SyncService (invalidation) -- Pattern: `getOrLoad(key, supplier, typeRef)` — returns cached value or calls supplier and stores result -- Sorted set operations: `KEY_TOP` stores restaurants by inspection score (lower = healthier) -- TTL: 3600s (configurable via `redis.cache.ttl-seconds`) - -**Security Layer:** -- Purpose: JWT token generation, validation, request filtering -- Location: `src/main/java/com/aflokkat/security/` -- Contains: - - `JwtUtil.java` — token generation (access + refresh), claims extraction - - `JwtAuthenticationFilter.java` — request interceptor, token validation -- Depends on: `jjwt` library, AppConfig -- Used by: AuthController, SecurityConfig - -**Config Layer:** -- Purpose: Application-wide configuration and dependency injection -- Location: `src/main/java/com/aflokkat/config/` -- Contains: - - `AppConfig.java` — centralized property loading (env vars → .env → application.properties) - - `MongoClientFactory.java` — singleton MongoDB client - - `RedisConfig.java` — StringRedisTemplate bean - - `SecurityConfig.java` — Spring Security setup, JWT filter chain - - `OpenApiConfig.java` — Swagger/OpenAPI bean -- Used by: Entire application - -**Domain Layer (MongoDB POJOs):** -- Purpose: Data models with BSON codec annotations -- Location: `src/main/java/com/aflokkat/domain/` -- Contains: - - `Restaurant.java` — main aggregate root (`_id`, `restaurant_id`, `name`, `cuisine`, `borough`, `address`, `phone`, `grades`) - - `Address.java` — nested document (`building`, `street`, `zipcode`, `coord` [GeoJSON]) - - `Grade.java` — inspection record (nested in `grades[]`; `date`, `grade`, `score`, `inspection_type`, `violation_code`, etc.) -- Used by: DAO, Service, Cache layers - -**Entity Layer (PostgreSQL JPA):** -- Purpose: User and bookmark persistence -- Location: `src/main/java/com/aflokkat/entity/` -- Contains: - - `UserEntity.java` — user credentials, roles - - `BookmarkEntity.java` — user-restaurant associations -- Used by: Repositories, AuthService - -**DTO Layer:** -- Purpose: Request/response DTOs, aggregation result pojos -- Location: `src/main/java/com/aflokkat/dto/` -- Contains: - - Request/Response: `AuthRequest`, `RegisterRequest`, `RefreshRequest`, `JwtResponse` - - Query results: `HeatmapPoint`, `TopRestaurantEntry`, `AtRiskEntry` -- Used by: Controllers, Cache layer, Service - -**Aggregation POJOs:** -- Purpose: Intermediate results from MongoDB aggregation pipelines -- Location: `src/main/java/com/aflokkat/aggregation/` -- Contains: - - `AggregationCount.java` — count per field (e.g., `{_id: "Italian", count: 500}`) - - `BoroughCuisineScore.java` — avg score per borough for a cuisine - - `CuisineScore.java` — avg score per cuisine - -**Utility Layer:** -- Purpose: Shared helper functions -- Location: `src/main/java/com/aflokkat/util/` -- Contains: - - `ValidationUtil.java` — `requireNonEmpty()`, `requirePositive()`, `validateFieldName()` - - `ResponseUtil.java` — uniform error response formatting - -## Data Flow - -**Analytics Query (e.g., GET /api/restaurants/by-borough):** - -1. HTTP GET → `RestaurantController` -2. Controller checks Redis cache via `RestaurantCacheService` -3. If cache miss: calls `RestaurantService.getRestaurantCountByBorough()` -4. Service delegates to `RestaurantDAOImpl.findCountByBorough()` -5. DAO builds MongoDB aggregation pipeline (`$group` by borough, `$count`) -6. Results returned as `List` -7. Cache stores result (TTL 3600s) -8. Response formatted as JSON and returned - -**Data Sync Flow (Scheduled 02:00 daily):** - -1. `SyncService.scheduledSync()` triggered by `@Scheduled` cron -2. `SyncService.runSync()` calls `NycOpenDataClient.fetchAll()` -3. Client fetches paginated records from NYC API (1000 per page, respects `max_records` limit) -4. Records grouped by `camis` (restaurant ID) in `mapToRestaurants()` -5. Each group: create `Restaurant` POJO with latest address/phone, aggregated `grades[]` (one per inspection date) -6. `RestaurantDAOImpl.upsertRestaurants()` bulk upsert (replace-on-match by `restaurant_id`) -7. `RestaurantCacheService.invalidateAll()` removes all `restaurants:*` keys -8. `RestaurantCacheService.updateTopRestaurants()` rebuilds sorted set `restaurants:top` with latest scores -9. SyncResult recorded with counts and timestamps - -**Authentication Flow:** - -1. POST `/api/auth/login` with credentials -2. `AuthController` → `AuthService.login()` -3. AuthService queries `UserRepository` for username -4. Password verified (bcrypt) -5. `JwtUtil.generateAccessToken()` + `generateRefreshToken()` -6. Response contains both tokens + user metadata -7. Subsequent requests include `Authorization: Bearer ` header -8. `JwtAuthenticationFilter` intercepts, validates token via `JwtUtil.validateToken()` -9. Token valid → request proceeds; invalid/expired → 401 Unauthorized - -**State Management:** - -- MongoDB: authoritative data store for restaurants (upserted nightly) -- PostgreSQL: user accounts, bookmarks (transactional) -- Redis: computed aggregations (cache-aside, TTL 3600s), top restaurants sorted set (rebuilt on sync) -- In-memory: `SyncService.lastResult` (sync status), JWT secret (`JwtUtil.key`) - -## Key Abstractions - -**Cache-Aside Pattern:** -- Method: `RestaurantCacheService.getOrLoad(key, supplier, typeRef)` -- On hit: deserialize from Redis, return -- On miss: call supplier (triggers DAO query), serialize to Redis, return -- Failure mode: swallows Redis exceptions, falls through to supplier (graceful degradation) - -**Aggregation Pipeline:** -- Location: `RestaurantDAOImpl` methods construct `List` pipelines -- Example: `findCountByBorough()` → `$match(address.$type: 3)` → `$group(_id: borough, count: $sum: 1)` → `$sort(count: -1)` -- Executed via `restaurantCollection.aggregate(pipeline, resultClass).forEach()` -- Result class: `AggregationCount`, `BoroughCuisineScore`, etc. - -**POJO Separation:** -- Restaurant POJO holds only stored fields from MongoDB -- Computed fields (latest grade, trend, badge color, lat/lng) calculated in `RestaurantService.toView()` -- Example: `toView()` builds `Map` with computed fields added -- Benefit: clean separation, computed fields never persisted - -**Sync Orchestration:** -- `SyncService` stateful: `running` flag, `lastResult`, `runningStartedAt` -- Result shared via `getLastResult()` for polling sync status -- Thread-safe: uses `volatile` for flags and timestamps - -## Entry Points - -**HTTP API:** -- Location: `Application.java` → Spring Boot startup -- Listens: `http://localhost:8080` -- Base paths: - - `/api/restaurants/*` → analytics, hygiene radar, sync - - `/api/auth/*` → login, register, refresh - - `/api/users/*` → profile, bookmarks - - `/api/inspections/*` → inspection-specific queries - - `/swagger-ui.html` → OpenAPI documentation - -**Scheduled Tasks:** -- `SyncService.scheduledSync()` → cron: 0 0 2 * * * (daily 02:00) -- Triggered by `@EnableScheduling` on `Application` class - -**Configuration Files:** -- `application.properties` → Spring config (logging, DB, API, JWT) -- `.env` → environment overrides (Docker Compose) -- System environment variables → highest priority - -## Error Handling - -**Strategy:** Layer-specific catch-and-log with graceful degradation - -**Patterns:** - -1. **Controller Layer:** - - Try-catch all endpoints - - Catch `IllegalArgumentException` → 400 Bad Request - - Catch `Exception` → 500 Internal Server Error - - Use `ResponseUtil.errorResponse()` for uniform format - -2. **Service Layer:** - - Validate input via `ValidationUtil` methods (throw `IllegalArgumentException`) - - Let DAO exceptions propagate (caught by controller) - -3. **DAO Layer:** - - MongoDB failures logged but not caught (bubble to service) - - Invalid queries return empty lists - -4. **Cache Layer:** - - All Redis operations wrapped in try-catch - - Failures logged as warnings, supplier called silently (cache-aside fallback) - -5. **Sync Layer:** - - Network failures caught, result marked `success: false` with error message - - Partial data treated as failure (all-or-nothing) - -## Cross-Cutting Concerns - -**Logging:** -- Framework: SLF4J + Simple Logger -- Configuration: `src/main/resources/simplelogger.properties` -- Root level: INFO; com.aflokkat: DEBUG -- Usage: SQL calls, sync events, cache operations, API errors - -**Validation:** -- Centralized: `ValidationUtil` class -- Methods: `requireNonEmpty()`, `requirePositive()`, `validateFieldName()` -- Failures: throw `IllegalArgumentException` with descriptive messages (French/English mix) -- Used by: Service layer before DAO calls - -**Authentication:** -- JWT tokens: HMAC-SHA256 signed -- Access token: 15 min (900,000 ms) -- Refresh token: 7 days (604,800,000 ms) -- Validation: checked on every request by `JwtAuthenticationFilter` -- Roles: extracted from token claim, checked by `@PreAuthorize("hasRole('ADMIN')")` - -**CORS:** -- All controllers: `@CrossOrigin(origins = "*", allowedHeaders = "*")` -- Allows frontend on different domain/port - ---- - -*Architecture analysis: 2026-03-27* - ---- - -# STRUCTURE.md (Complete Content) - -# Codebase Structure - -**Analysis Date:** 2026-03-27 - -## Directory Layout - -``` -quickstart-app/ -├── src/ -│ ├── main/ -│ │ ├── java/com/aflokkat/ -│ │ │ ├── Application.java # Spring Boot entry point -│ │ │ ├── aggregation/ # MongoDB aggregation result POJOs -│ │ │ │ ├── AggregationCount.java -│ │ │ │ ├── BoroughCuisineScore.java -│ │ │ │ └── CuisineScore.java -│ │ │ ├── cache/ # Redis cache-aside layer -│ │ │ │ └── RestaurantCacheService.java -│ │ │ ├── config/ # Spring config, singletons -│ │ │ │ ├── AppConfig.java # property loader (env → .env → props) -│ │ │ │ ├── MongoClientFactory.java # MongoDB singleton -│ │ │ │ ├── RedisConfig.java # StringRedisTemplate bean -│ │ │ │ ├── SecurityConfig.java # JWT filter chain -│ │ │ │ └── OpenApiConfig.java # Swagger/OpenAPI -│ │ │ ├── controller/ # REST API endpoints (18+ endpoints) -│ │ │ │ ├── RestaurantController.java -│ │ │ │ ├── AuthController.java -│ │ │ │ ├── InspectionController.java -│ │ │ │ ├── UserController.java -│ │ │ │ └── ViewController.java -│ │ │ ├── dao/ # MongoDB data access -│ │ │ │ ├── RestaurantDAO.java # interface (29 methods) -│ │ │ │ └── RestaurantDAOImpl.java # aggregation pipelines -│ │ │ ├── domain/ # MongoDB POJO models -│ │ │ │ ├── Restaurant.java # aggregate root -│ │ │ │ ├── Address.java # nested document -│ │ │ │ └── Grade.java # inspection record -│ │ │ ├── dto/ # Request/response DTOs -│ │ │ │ ├── AuthRequest.java -│ │ │ │ ├── RegisterRequest.java -│ │ │ │ ├── JwtResponse.java -│ │ │ │ ├── RefreshRequest.java -│ │ │ │ ├── HeatmapPoint.java -│ │ │ │ ├── TopRestaurantEntry.java -│ │ │ │ └── AtRiskEntry.java -│ │ │ ├── entity/ # JPA entities (PostgreSQL) -│ │ │ │ ├── UserEntity.java -│ │ │ │ └── BookmarkEntity.java -│ │ │ ├── repository/ # Spring JPA repositories -│ │ │ │ ├── UserRepository.java -│ │ │ │ └── BookmarkRepository.java -│ │ │ ├── security/ # JWT authentication -│ │ │ │ ├── JwtUtil.java # token generation/validation -│ │ │ │ └── JwtAuthenticationFilter.java -│ │ │ ├── service/ # Business logic layer -│ │ │ │ ├── RestaurantService.java # analytics, computed fields -│ │ │ │ └── AuthService.java # user auth -│ │ │ ├── sync/ # NYC API sync orchestration -│ │ │ │ ├── SyncService.java # scheduler, nightly 02:00 -│ │ │ │ ├── NycOpenDataClient.java # HTTP REST client -│ │ │ │ ├── NycApiRestaurantDto.java # API response DTO -│ │ │ │ └── SyncResult.java # sync metadata -│ │ │ └── util/ # Shared utilities -│ │ │ ├── ValidationUtil.java -│ │ │ └── ResponseUtil.java -│ │ └── resources/ -│ │ ├── application.properties # Spring config (main) -│ │ ├── simplelogger.properties # SLF4J logging config -│ │ └── templates/ # HTML templates (Thymeleaf) -│ │ ├── index.html -│ │ ├── login.html -│ │ ├── restaurant.html -│ │ ├── inspection.html -│ │ ├── inspection-map.html -│ │ └── hygiene-radar.html -│ ├── test/ -│ │ └── java/com/aflokkat/ -│ │ ├── dao/ # DAO integration tests (64 tests) -│ │ ├── domain/ -│ │ ├── sync/ -│ │ ├── security/ -│ │ ├── util/ -│ │ ├── cache/ -│ │ ├── config/ -│ │ ├── service/ -│ │ └── aggregation/ -├── pom.xml # Maven build config -├── docker-compose.yml # 4 containers: app, MongoDB, Redis, PostgreSQL -├── Dockerfile # Spring Boot app image -├── application.properties # (in src/main/resources) -├── CLAUDE.md # Project context document -└── README.md # Project documentation diff --git a/.planning/codebase/TESTING.md b/.planning/codebase/TESTING.md deleted file mode 100644 index 50b9a7a..0000000 --- a/.planning/codebase/TESTING.md +++ /dev/null @@ -1,166 +0,0 @@ -# Testing - -**Analysis Date:** 2026-03-27 - -## Framework - -**Primary frameworks:** -- JUnit 4 — used in integration tests and older unit tests (`org.junit.Test`, `@Before`/`@After`) -- JUnit 5 (Jupiter) — used in newer unit tests (`org.junit.jupiter.api.Test`, `@ExtendWith`) -- Mockito — mocking framework for unit tests (`@Mock`, `@InjectMocks`, `MockitoExtension`) - -**Mixed JUnit 4/5:** The codebase uses both JUnit versions. Integration tests use JUnit 4; service/util tests trend towards JUnit 5. - -**Build integration:** -```bash -mvn test # All unit tests -mvn test -Dtest=RestaurantDAOIntegrationTest # Integration tests only -mvn verify # All tests including integration -``` - -## Test Structure - -**Location:** `src/test/java/com/aflokkat/` - -**Test files (116 total @Test methods):** -``` -test/ -├── aggregation/ -│ └── AggregationPojoTest.java (6 tests) — POJO field mapping -├── cache/ -│ └── RestaurantCacheServiceTest.java (8 tests) — Redis cache service -├── config/ -│ ├── AppConfigTest.java (7 tests) — Spring config beans -│ └── MongoClientFactoryTest.java (4 tests) — MongoDB client factory -├── dao/ -│ ├── RestaurantDAOImplTest.java (5 tests) — DAO with mocked Mongo -│ └── RestaurantDAOIntegrationTest.java (15 tests) — Integration vs live MongoDB -├── domain/ -│ └── RestaurantTest.java (2 tests) — Domain POJO behavior -├── security/ -│ └── JwtUtilTest.java (12 tests) — JWT generation/validation -├── service/ -│ ├── AuthServiceTest.java (10 tests) — Auth business logic -│ └── RestaurantServiceTest.java (21 tests) — Restaurant service logic -├── sync/ -│ ├── NycOpenDataClientTest.java (4 tests) — API client -│ └── SyncServiceTest.java (9 tests) — Sync orchestration -└── util/ - └── ValidationUtilTest.java (13 tests) — Input validation -``` - -**Total: ~116 unit tests + 15 integration tests = 131 tests** - -## Unit Test Patterns - -### Standard JUnit 5 + Mockito pattern (service tests) -```java -@ExtendWith(MockitoExtension.class) -class RestaurantServiceTest { - - @Mock - private RestaurantDAO restaurantDAO; - - @InjectMocks - private RestaurantService restaurantService; - - @Test - void testGetRestaurantsByBorough_returnsResults() { - // Arrange - when(restaurantDAO.findByBorough(anyString())).thenReturn(mockList); - - // Act - List result = restaurantService.getRestaurantsByBorough("MANHATTAN"); - - // Assert - assertNotNull(result); - assertEquals(1, result.size()); - verify(restaurantDAO).findByBorough("MANHATTAN"); - } -} -``` - -### JUnit 4 pattern (older tests) -```java -public class ValidationUtilTest { - @Test - public void testValidBorough() { - assertTrue(ValidationUtil.isValidBorough("MANHATTAN")); - } - - @Test(expected = IllegalArgumentException.class) - public void testInvalidBorough_throwsException() { - ValidationUtil.requireValidBorough("INVALID"); - } -} -``` - -### Integration test pattern -```java -public class RestaurantDAOIntegrationTest { - private RestaurantDAO restaurantDAO; - - @Before - public void setUp() { - // Connects to localhost:27017/newyork - restaurantDAO = new RestaurantDAOImpl(...); - } - - @After - public void tearDown() { /* cleanup */ } - - @Test - public void testFindByBorough_returnsResults() { - List results = restaurantDAO.findByBorough("MANHATTAN"); - assertNotNull(results); - assertFalse(results.isEmpty()); - } -} -``` - -## Mocking Strategy - -**Service layer:** Mocked DAO via `@Mock` + `@InjectMocks` — no real DB needed -**Cache service:** Mocked Redis `Jedis` client -**Sync service:** Mocked `NycOpenDataClient` and `RestaurantDAO` -**JWT:** Real key generation, no mocks (pure logic) -**Integration tests:** Real MongoDB at `localhost:27017`, DB `newyork` must be populated - -## Integration Test Requirements - -Integration tests (`RestaurantDAOIntegrationTest`) require: -- MongoDB running on `localhost:27017` -- Database `newyork` with `restaurants` collection populated -- Not run by default — must be explicitly invoked - -```bash -# Run integration tests -mvn test -Dtest=RestaurantDAOIntegrationTest - -# Skip integration tests (default) -mvn test # integration tests are not annotated @Ignore but require live DB -``` - -## Coverage - -**Unit coverage:** ~64 unit tests across 12 test classes (before recent expansion to ~116) -**Integration coverage:** 15 tests covering the 4 main DAO use cases -**Gaps:** -- No Spring Boot `@SpringBootTest` / `@WebMvcTest` (no controller tests) -- No Redis failure scenarios / connection error handling -- No SyncService concurrency tests -- No JWT token tampering / replay attack tests -- No end-to-end API tests -- PostgreSQL/JPA layer has no dedicated tests - -## Assertions Style - -**JUnit 4:** `assertEquals`, `assertTrue`, `assertFalse`, `assertNotNull` (static imports from `org.junit.Assert`) -**JUnit 5:** `assertEquals`, `assertNotNull`, `assertThrows` (from `org.junit.jupiter.api.Assertions`) -**Pattern:** Arrange-Act-Assert (AAA) is consistently followed - -## Naming Conventions - -- Test class: `{Subject}Test.java` -- Test method: descriptive camelCase — e.g., `testGetRestaurantsByBorough_returnsResults`, `testValidBorough` -- Integration test class: `{Subject}IntegrationTest.java` diff --git a/.planning/config.json b/.planning/config.json deleted file mode 100644 index 8218533..0000000 --- a/.planning/config.json +++ /dev/null @@ -1,28 +0,0 @@ -{ - "mode": "yolo", - "granularity": "standard", - "parallelization": true, - "branching_strategy": "phase", - "commit_docs": true, - "model_profile": "balanced", - "workflow": { - "research": true, - "plan_check": true, - "verifier": true, - "nyquist_validation": true, - "_auto_chain_active": false, - "auto_advance": false, - "ui_phase": true, - "ui_safety_gate": true, - "research_before_questions": false, - "skip_discuss": false, - "use_worktrees": true - }, - "git": { - "branching_strategy": "phase" - }, - "hooks": { - "context_warnings": true, - "workflow_guard": true - } -} \ No newline at end of file diff --git a/.planning/milestones/v2.0-REQUIREMENTS.md b/.planning/milestones/v2.0-REQUIREMENTS.md deleted file mode 100644 index 1be3cf7..0000000 --- a/.planning/milestones/v2.0-REQUIREMENTS.md +++ /dev/null @@ -1,164 +0,0 @@ ---- -milestone: v2.0 -milestone_name: Full Product -archived: 2026-04-11 -requirements_total: 36 -requirements_satisfied: 36 -v1_requirements: 13 -v2_requirements: 23 ---- - -# Requirements: Restaurant Hygiene Control App — v2.0 Archive - -**Defined:** 2026-03-27 -**Archived:** 2026-04-11 -**Core Value:** A customer can search any NYC restaurant and immediately know whether it's clean — and a controller can document new hygiene findings against the same data. - -## Outcome Summary - -All 36 requirements (13 v1 + 23 v2) were validated by 2026-04-11. All v2 requirements delivered across phases 5–10. 7 integration defects found post-implementation and fixed before milestone close. - ---- - -## v1 Requirements — All Validated ✓ - -### Authentication & Roles - -- [x] **AUTH-01**: User account has a CUSTOMER or CONTROLLER role stored in PostgreSQL — **Validated** (Phase 1) -- [x] **AUTH-02**: Controller can register via a dedicated endpoint using a shared signup code — **Validated** (Phase 1) -- [x] **AUTH-03**: URL-level security guards block CONTROLLER endpoints from unauthenticated or CUSTOMER access — **Validated** (Phase 1) -- [x] **AUTH-04**: Auth endpoints (login/register) have rate limiting to prevent brute-force attacks — **Validated** (Phase 1) -- [x] **AUTH-05**: One CUSTOMER and one CONTROLLER test account are seeded automatically on application startup — **Validated** (Phase 1) - -### Controller Reports - -- [x] **CTRL-01**: Controller can create an inspection report for a restaurant — **Validated** (Phase 2) -- [x] **CTRL-02**: Controller can view a list of their own submitted inspection reports — **Validated** (Phase 2) -- [x] **CTRL-03**: Controller can edit their own inspection reports — **Validated** (Phase 2) -- [x] **CTRL-04**: Controller can attach a photo to an inspection report — **Validated** (Phase 2) - -### Customer Discovery - -- [x] **CUST-01**: Customer can search restaurants by name or address and see a list of results with hygiene grade — **Validated** (Phase 3) -- [x] **CUST-02**: Customer can view a restaurant detail page showing hygiene grade, cleanliness score, and NYC inspection history — **Validated** (Phase 3) -- [x] **CUST-03**: Customer can browse restaurants on an interactive map with grade-colored markers — **Validated** (Phase 3) -- [x] **CUST-04**: Customer can bookmark/favorite restaurants and view their saved list — **Validated** (Phase 3) - ---- - -## v2 Requirements — All Validated ✓ - -### Controller Workspace (Phase 5) - -- [x] **CTRL-05**: Controller can create an inspection report via a web form — **Validated** (Phase 5, 05-VERIFICATION.md) -- [x] **CTRL-06**: Controller can view all their reports on a dashboard page with status filter tabs — **Validated** (Phase 5, 05-VERIFICATION.md) -- [x] **CTRL-07**: Controller can edit a report from the dashboard via an inline edit panel — **Validated** (Phase 5, 05-VERIFICATION.md) -- [x] **CTRL-08**: Controller can upload a photo and see a thumbnail preview on the report card — **Validated** (Phase 5, 05-VERIFICATION.md) - -### Analytics & Stats (Phase 6) - -- [x] **STAT-01**: Public `/analytics` page shows city-wide KPIs: total restaurants, % grade A, average score, count of at-risk — **Validated** (Phase 6, 06-VERIFICATION.md) -- [x] **STAT-02**: Analytics page shows per-borough grade distribution — **Validated** (Phase 6, 06-VERIFICATION.md) -- [x] **STAT-03**: Analytics page shows cuisine hygiene ranking — top 10 cleanest and top 10 worst — **Validated** (Phase 6, 06-VERIFICATION.md) -- [x] **STAT-04**: Analytics page shows "At Risk" list with restaurant links — **Validated** (Phase 6, 06-VERIFICATION.md) - -### Homepage & Navigation (Phase 7) - -- [x] **UX-01**: Non-authenticated visitors see a landing page with city-wide stats, search CTA, and 3 sample restaurants — **Validated** (Phase 7, 07-VERIFICATION.md) -- [x] **UX-02**: Authenticated users see a personalised dashboard on `/` with bookmarks, nearby, and stats strip — **Validated** (Phase 7, 07-VERIFICATION.md) -- [x] **UX-03**: A persistent top navbar exists on all pages — **Validated** (Phase 7, 07-VERIFICATION.md) -- [x] **UX-04**: A `/profile` page shows username, email, role badge, bookmark count, and report count — **Validated** (Phase 7, 07-VERIFICATION.md) - -### Discovery Enhancement (Phase 8) - -- [x] **DISC-01**: Map at `/inspection-map` has filter controls — grade checkboxes, borough dropdown, cuisine dropdown — **Validated** (Phase 8, 08-VERIFICATION.md) -- [x] **DISC-02**: `/uncontrolled` page with sortable table, borough filter, and CSV download — **Validated** (Phase 8, 08-VERIFICATION.md) -- [x] **DISC-03**: Restaurant detail page shows up to 5 nearby restaurants within 500m — **Validated** (Phase 8, 08-VERIFICATION.md; integration defect DEFECT-04 fixed in d9ebf0a) -- [x] **DISC-04**: Search results can be sorted by score, grade, or name — **Validated** (Phase 8, 08-VERIFICATION.md) - -### UX Polish (Phase 9) - -- [x] **UX-05**: All list views are paginated — 20 items per page with Previous / Next controls — **Validated** (Phase 9, 09-VERIFICATION.md) -- [x] **UX-06**: All data-fetching sections show skeleton loading cards — **Validated** (Phase 9, 09-VERIFICATION.md) -- [x] **UX-07**: Toast notification system replaces all inline success/error messages — **Validated** (Phase 9, 09-VERIFICATION.md) -- [x] **UX-08**: All pages render correctly on mobile viewports (320px–768px) — **Validated** (Phase 9, 09-VERIFICATION.md) - -### Admin Tools (Phase 10) - -- [x] **ADM-01**: `/admin` page shows last NYC sync status, "Sync Now" button with live progress feedback — **Validated** (Phase 10, 10-VERIFICATION.md) -- [x] **ADM-02**: Admin page has "Export At-Risk CSV" button using fetchWithAuth + Blob download — **Validated** (Phase 10, 10-VERIFICATION.md; integration defect DEFECT-05 fixed in d9ebf0a) -- [x] **ADM-03**: Admin page shows aggregate report statistics across all controllers — **Validated** (Phase 10, 10-VERIFICATION.md) - ---- - -## Deferred to v3 - -- **CTRL-V2-01**: Report status change notifications to admin -- **CTRL-V2-02**: Controller can view all reports across controllers (admin view) -- **CTRL-V2-03**: Bulk photo upload (multiple photos per report) -- **CUST-V2-01**: Real-time notifications when a bookmarked restaurant gets a new inspection -- **CUST-V2-03**: Customer can see hygiene trend over time (is it improving?) -- **PLAT-V2-01**: Admin role can manage controller accounts -- **PLAT-V2-02**: Export controller reports to PDF - -## Out of Scope - -| Feature | Reason | -|---------|--------| -| Push controller reports to NYC Open Data API | No write access; API is read-only | -| Customer-visible controller reports | Internal reports for controllers only | -| Mobile native app | Web-first; mobile deferred | -| Multi-city support | NYC Open Data only | -| Object storage for photos (S3, GCS) | Docker local volume sufficient for academic scope | - ---- - -## Traceability - -| Requirement | Phase | Status | Verification | -|-------------|-------|--------|--------------| -| AUTH-01 | Phase 1 | Validated | 01-VERIFICATION.md | -| AUTH-02 | Phase 1 | Validated | 01-VERIFICATION.md | -| AUTH-03 | Phase 1 | Validated | 01-VERIFICATION.md | -| AUTH-04 | Phase 1 | Validated | 01-VERIFICATION.md | -| AUTH-05 | Phase 1 | Validated | 01-VERIFICATION.md | -| CTRL-01 | Phase 2 | Validated | 02-VERIFICATION.md | -| CTRL-02 | Phase 2 | Validated | 02-VERIFICATION.md | -| CTRL-03 | Phase 2 | Validated | 02-VERIFICATION.md | -| CTRL-04 | Phase 2 | Validated | 02-VERIFICATION.md | -| CUST-01 | Phase 3 | Validated | 03-VERIFICATION.md | -| CUST-02 | Phase 3 | Validated | 03-VERIFICATION.md | -| CUST-03 | Phase 3 | Validated | 03-VERIFICATION.md | -| CUST-04 | Phase 3 | Validated | 03-VERIFICATION.md | -| CTRL-05 | Phase 5 | Validated | 05-VERIFICATION.md | -| CTRL-06 | Phase 5 | Validated | 05-VERIFICATION.md | -| CTRL-07 | Phase 5 | Validated | 05-VERIFICATION.md | -| CTRL-08 | Phase 5 | Validated | 05-VERIFICATION.md | -| STAT-01 | Phase 6 | Validated | 06-VERIFICATION.md | -| STAT-02 | Phase 6 | Validated | 06-VERIFICATION.md | -| STAT-03 | Phase 6 | Validated | 06-VERIFICATION.md | -| STAT-04 | Phase 6 | Validated | 06-VERIFICATION.md | -| UX-01 | Phase 7 | Validated | 07-VERIFICATION.md | -| UX-02 | Phase 7 | Validated | 07-VERIFICATION.md | -| UX-03 | Phase 7 | Validated | 07-VERIFICATION.md | -| UX-04 | Phase 7 | Validated | 07-VERIFICATION.md | -| DISC-01 | Phase 8 | Validated | 08-VERIFICATION.md | -| DISC-02 | Phase 8 | Validated | 08-VERIFICATION.md | -| DISC-03 | Phase 8 | Validated | 08-VERIFICATION.md | -| DISC-04 | Phase 8 | Validated | 08-VERIFICATION.md | -| UX-05 | Phase 9 | Validated | 09-VERIFICATION.md | -| UX-06 | Phase 9 | Validated | 09-VERIFICATION.md | -| UX-07 | Phase 9 | Validated | 09-VERIFICATION.md | -| UX-08 | Phase 9 | Validated | 09-VERIFICATION.md | -| ADM-01 | Phase 10 | Validated | 10-VERIFICATION.md | -| ADM-02 | Phase 10 | Validated | 10-VERIFICATION.md | -| ADM-03 | Phase 10 | Validated | 10-VERIFICATION.md | - -**Total Coverage:** -- v1 requirements: 13/13 validated ✓ -- v2 requirements: 23/23 validated ✓ -- Deferred: 7 items → v3 - ---- -*Requirements defined: 2026-03-27* -*Archived: 2026-04-11 — milestone v2.0 complete, all 36 requirements validated* diff --git a/.planning/milestones/v2.0-ROADMAP.md b/.planning/milestones/v2.0-ROADMAP.md deleted file mode 100644 index 14ea4d7..0000000 --- a/.planning/milestones/v2.0-ROADMAP.md +++ /dev/null @@ -1,197 +0,0 @@ ---- -milestone: v2.0 -milestone_name: Full Product -status: shipped -shipped: 2026-04-11 -phases: 6 -total_plans: 20 -archive_of: .planning/ROADMAP.md (phases 5-10) ---- - -# Milestone v2.0 — Full Product (Archived) - -**Shipped:** 2026-04-11 -**Phases:** 5 through 10 (6 phases, 20 plans) -**Requirements:** 23/23 complete (CTRL-05–08, STAT-01–04, UX-01–08, DISC-01–04, ADM-01–03) - -## Overview - -v2.0 completes the product: controllers get a full UI workspace, a public analytics dashboard surfaces city-wide hygiene trends, the homepage is redesigned for both anonymous visitors and authenticated users, discovery is enhanced with map filters and an uncontrolled-restaurants tracker, and the whole app gets UX polish (pagination, skeletons, toasts, mobile responsiveness). Admin tools round out the release with sync controls, CSV export, and aggregate report statistics. - -## Key Accomplishments - -1. **Controller Workspace (Phase 5)** — Full dashboard UI: status-filtered report cards, New Report modal with live restaurant autocomplete, inline edit panel, photo thumbnail upload — all without page reload -2. **Analytics & Stats (Phase 6)** — Public `/analytics` page: city-wide KPI strip, per-borough grade distribution bars, top-10 cleanest/worst cuisine rankings, live at-risk restaurant list -3. **Homepage & Navigation (Phase 7)** — Dual landing/dashboard routing on `/` based on auth state; persistent navbar fragment across all 10 pages; `/profile` page with role badge and counts -4. **Discovery Enhancement (Phase 8)** — Map filter bar (grade/borough/cuisine checkboxes), `/uncontrolled` tracker page with CSV export, nearby restaurants section on detail page, sort control on search -5. **UX Polish (Phase 9)** — Paginated lists (20 items/page), skeleton loading cards on all async sections, toast notification system replacing inline errors, full mobile responsiveness (hamburger nav, grid stacking) -6. **Admin Tools (Phase 10)** — `/admin` page for ADMIN role: sync controls with live progress polling, at-risk CSV download, aggregate report stats across all controllers - -## Phase Details - -### Phase 5: Controller Workspace -**Goal**: Controllers can manage their inspection reports entirely through a dedicated UI — search a restaurant, file a report, edit it, attach a photo — without touching the API directly -**Depends on**: Phase 4 -**Requirements**: CTRL-05, CTRL-06, CTRL-07, CTRL-08 -**Status**: Complete (2026-04-03) -**Plans**: 2/2 - -**Success Criteria (verified):** -1. A logged-in controller can navigate to `/dashboard`, see their reports grouped by status (All / Open / In Progress / Resolved), and each card shows restaurant name, grade badge, date, and a thumbnail if a photo exists -2. A controller can open a "New Report" form, search for a restaurant by name (live autocomplete using `/api/restaurants/search`), fill in grade/violations/notes, submit, and see the new card appear in the list without a page reload -3. A controller can click "Edit" on any of their own report cards and update grade, status, violations, or notes via an inline panel; changes are persisted and the card updates immediately -4. A controller can click "Upload Photo" on a report card, select an image, and see a thumbnail preview on the card after upload - -Plans: -- 05-01-PLAN.md — ViewController redirect + SecurityConfig /dashboard guard + 6 tests (CTRL-05, CTRL-06) -- 05-02-PLAN.md — dashboard.html: tabs, cards, New Report modal, edit panel, photo upload (CTRL-05, CTRL-06, CTRL-07, CTRL-08) - ---- - -### Phase 6: Analytics & Stats -**Goal**: A public analytics page gives any visitor a city-wide picture of NYC restaurant hygiene — borough breakdown, cuisine rankings, at-risk list, and a healthiest restaurants leaderboard -**Depends on**: Phase 4 -**Requirements**: STAT-01, STAT-02, STAT-03, STAT-04 -**Status**: Complete (2026-04-03) -**Plans**: 3/3 - -**Success Criteria (verified):** -1. Navigating to `/analytics` without authentication shows the page correctly (fully public) -2. The page header strip shows four KPI tiles: Total Restaurants, % Grade A, Average Score (city-wide), and At-Risk Count (grade C or Z) — all populated from live API data -3. The borough section shows a grade distribution bar for each of the 5 NYC boroughs — each bar visually encodes the A/B/C proportion using the standard green/yellow/red palette -4. The cuisine section shows two ranked lists: top 10 cleanest and top 10 worst cuisines by average score, each with the score value visible -5. The "At Risk" section lists restaurants with last grade C or Z; each row has restaurant name, borough, grade badge, and a link to the detail page - -Plans: -- 06-01-PLAN.md — Wave 0 test scaffolds: AnalyticsControllerTest (4 stubs) + ViewControllerAnalyticsTest (1 stub) -- 06-02-PLAN.md — AnalyticsController (4 endpoints) + DAO/Service extensions (borough distribution, best/worst cuisines, at-risk count) -- 06-03-PLAN.md — analytics.html template + ViewController /analytics route + nav links - ---- - -### Phase 7: Homepage & Navigation -**Goal**: Non-authenticated visitors land on a proper public homepage; authenticated users see a personalised dashboard; a consistent top navbar links all sections of the app -**Depends on**: Phase 6 (analytics KPIs reused on homepage) -**Requirements**: UX-01, UX-02, UX-03, UX-04 -**Status**: Complete (2026-04-03) -**Plans**: 4/4 - -**Success Criteria (verified):** -1. Visiting `/` without a JWT shows a public landing page — hero with city stats, a search bar CTA, and 3 randomly-sampled restaurant cards — NOT the authenticated dashboard -2. Visiting `/` with a valid JWT shows a personalised dashboard: a "Your Bookmarks" strip (last 3), a "Nearby" strip if geolocation was granted, and the 4 analytics KPI tiles -3. Every page includes the same top navbar with: logo left, nav links center (Search, Map, Analytics), auth button right (Sign In or username + Logout) -4. A logged-in user can navigate to `/profile` and see their username, email, role badge, total bookmarks, and (for controllers) total reports filed - -Plans: -- 07-01-PLAN.md — ViewController routing split + /api/restaurants/sample + enriched /api/users/me + /profile security + tests -- 07-02-PLAN.md — navbar fragment + landing.html + profile.html + index.html rewrite -- 07-03-PLAN.md — Navbar insertion into 5 existing templates + human verify checkpoint -- 07-04-PLAN.md — Gap-closure: uncontrolled page navbar, restaurant page fixes - ---- - -### Phase 8: Discovery Enhancement -**Goal**: Users can filter the map by grade/borough/cuisine, find uncontrolled restaurants, discover nearby places from a detail page, and sort search results -**Depends on**: Phase 7 -**Requirements**: DISC-01, DISC-02, DISC-03, DISC-04 -**Status**: Complete -**Plans**: 5/5 - -**Success Criteria (verified):** -1. On `/inspection-map`, a filter bar at the top has grade checkboxes (A/B/C/F) and a borough dropdown; toggling a filter removes matching markers from the map in under 200ms without a network request (client-side filtering on already-loaded data) -2. Navigating to `/uncontrolled` shows a table of restaurants with last grade C/Z or no inspection in the past 12 months; the table can be sorted by score or filtered by borough dropdown; a "Download CSV" button calls the existing export endpoint -3. The restaurant detail page has a "Nearby restaurants" section showing up to 5 restaurants within 500m, each with name, grade badge, and a link to their detail page -4. Above the search results on the homepage, a sort control (Best Score / Worst Score / A→Z) reorders the current result set client-side - -Plans: -- 08-01-PLAN.md — Wave 0 tests + DISC-02 backend (UncontrolledEntry DTO, findUncontrolled DAO, InspectionController endpoints) -- 08-02-PLAN.md — uncontrolled.html template (DISC-02) -- 08-03-PLAN.md — inspection-map.html filter bar: grade checkboxes, cuisine dropdown, count badge (DISC-01) -- 08-04-PLAN.md — restaurant.html Nearby section + landing.html sort control (DISC-03, DISC-04) -- 08-05-PLAN.md — Gap-closure fixes: controller nav link, name links, coordinate debug, map grade colors, borough alignment, CSV button - ---- - -### Phase 9: UX Polish -**Goal**: Every list is paginated, every async operation shows a skeleton, errors surface as toasts, and all pages work on mobile -**Depends on**: Phase 8 -**Requirements**: UX-05, UX-06, UX-07, UX-08 -**Status**: Complete -**Plans**: 5/5 - -**Success Criteria (verified):** -1. Search results, the at-risk list, the uncontrolled list, and the bookmarks list all show a maximum of 20 items per page with visible Previous / Next controls; the URL or state reflects the current page -2. All sections that fetch data show skeleton loading cards (grey animated placeholders) for the duration of the network request — no blank space, no "Loading…" text -3. All success and error feedback (bookmark added, report saved, upload failed, etc.) appears as a toast notification bottom-right that auto-dismisses after 3 seconds — no inline error divs remain -4. On a 375px viewport (iPhone SE), all pages render without horizontal scroll: the navbar collapses to a hamburger, cards stack vertically, and the map fills the screen correctly - -Plans: -- 09-01-PLAN.md — ux-utils fragment: skeleton CSS + toast system -- 09-02-PLAN.md — landing.html pagination and skeleton loading -- 09-03-PLAN.md — analytics/uncontrolled/bookmarks pagination and skeleton -- 09-04-PLAN.md — Toast notifications replacing inline errors + dashboard pagination -- 09-05-PLAN.md — Mobile responsiveness: hamburger nav, grid stacking, table scroll wrappers - ---- - -### Phase 10: Admin Tools -**Goal**: Controllers can trigger data sync and cache rebuild from the UI, export the at-risk list, and see aggregate report statistics across the platform -**Depends on**: Phase 5 -**Requirements**: ADM-01, ADM-02, ADM-03 -**Status**: Complete (2026-04-11) -**Plans**: 3/3 - -**Success Criteria (verified):** -1. A logged-in admin navigating to `/admin` sees the last sync date/status and a "Sync NYC Data" button; clicking it triggers the sync and shows live progress (polling the sync-status endpoint every 2s) until completion -2. The admin page has a "Download At-Risk CSV" button that triggers a file download via fetchWithAuth + Blob pattern -3. The admin page shows a "Report Statistics" panel with counts grouped by status (Open / In Progress / Resolved) and by grade (A/B/C/F) across all controllers' reports — the aggregate query does NOT return individual reports from other controllers - -Plans: -- 10-01-PLAN.md — AuthService ROLE_ADMIN signup code + DataSeeder admin_test + AuthServiceTest update -- 10-02-PLAN.md — ReportRepository aggregate @Query methods + AdminController GET /api/reports/stats -- 10-03-PLAN.md — SecurityConfig antMatchers + ViewController /admin + admin.html + navbar ADMIN link - ---- - -## Milestone Summary - -### Key Decisions - -| Decision | Phase | Rationale | -|----------|-------|-----------| -| Controller signup via env-var registration code | Phase 1 | Prevents open public access to filing reports | -| Photos on Docker named volume (not S3) | Phase 2 | Sufficient for academic scope | -| uploadPhoto uses raw fetch() (not fetchWithAuth) | Phase 5 | fetchWithAuth sets Content-Type: application/json which corrupts multipart boundary | -| AnalyticsController injects RestaurantDAO directly (not service) | Phase 6 | Mockito cannot mock constructor-injected services on Java 25 | -| Navbar auth state fully JS-driven | Phase 7 | Stateless JWT app has no server session for Spring Security Thymeleaf | -| anyRequest().permitAll() with client-side IIFE guards for /admin, /dashboard | Phase 10 | Browser navigation does not send Authorization header | -| antMatcher /api/reports/stats placed BEFORE /api/reports/** wildcard | Phase 10 | First-match-wins Spring Security ordering | -| ADMIN_SIGNUP_CODE defaults to empty (admin created via DataSeeder) | Phase 10 | Admin self-registration disabled in production Docker | - -### Tech Debt Deferred to v3 - -| Item | Phase | Description | -|------|-------|-------------| -| French strings in restaurant.html | Phase 4 | `Fiche Restaurant` (line 6) and `Note ${latestGrade}` (line 266) remain | -| Dead SecurityConfig permitAll for /api/inspections/** | Phase 10 | Plural path matches nothing; works via anyRequest fallthrough only | -| Admin login redirect | Phase 10 | ADMIN role users land on customer home after login, not /admin | - -### Issues Resolved During v2.0 - -- 7 integration defects found by automated checker and fixed: KPI URL typo, field name mismatch, response shape mismatch, nearby section JSON parse error, CSV download auth blocking, bookmarkCount display missing, SecurityConfig dead path -- SecurityConfigTest stale assertions updated to match Phase 10 client-side guard refactor - -### Deferred to v3 - -- CTRL-V2-01: Report status change notifications to admin -- CTRL-V2-02: Controller can view all reports across controllers (admin view) -- CTRL-V2-03: Bulk photo upload -- CUST-V2-01: Real-time notifications for bookmarked restaurant inspections -- CUST-V2-03: Hygiene trend over time -- PLAT-V2-01: Admin role manages controller accounts -- PLAT-V2-02: Export controller reports to PDF - ---- - -*Archived: 2026-04-11* -*Archiver: Claude (gsd-complete-milestone)* diff --git a/.planning/phases/01-role-infrastructure/01-01-PLAN.md b/.planning/phases/01-role-infrastructure/01-01-PLAN.md deleted file mode 100644 index 95398be..0000000 --- a/.planning/phases/01-role-infrastructure/01-01-PLAN.md +++ /dev/null @@ -1,347 +0,0 @@ ---- -phase: 01-role-infrastructure -plan: 01 -type: execute -wave: 1 -depends_on: [] -files_modified: - - src/main/java/com/aflokkat/dto/RegisterRequest.java - - src/main/java/com/aflokkat/service/AuthService.java - - src/test/java/com/aflokkat/service/AuthServiceTest.java -autonomous: true -requirements: - - AUTH-01 - - AUTH-02 - -must_haves: - truths: - - "Registering without a signupCode stores role ROLE_CUSTOMER in PostgreSQL" - - "Registering with the correct CONTROLLER_SIGNUP_CODE stores role ROLE_CONTROLLER" - - "Registering with a wrong signupCode returns HTTP 400 with message 'Invalid registration request'" - - "Registering with any signupCode when CONTROLLER_SIGNUP_CODE env var is absent returns HTTP 400" - - "Existing ROLE_USER registration path is replaced — no new user is ever saved with ROLE_USER" - artifacts: - - path: "src/main/java/com/aflokkat/dto/RegisterRequest.java" - provides: "DTO with optional signupCode field" - contains: "getSignupCode" - - path: "src/main/java/com/aflokkat/service/AuthService.java" - provides: "Role-assignment logic guarded by signup code" - contains: "ROLE_CUSTOMER" - - path: "src/test/java/com/aflokkat/service/AuthServiceTest.java" - provides: "Unit tests for all 4 role-assignment scenarios" - contains: "register_assignsCustomerRole_whenNoSignupCode" - key_links: - - from: "src/main/java/com/aflokkat/dto/RegisterRequest.java" - to: "src/main/java/com/aflokkat/service/AuthService.java" - via: "request.getSignupCode()" - pattern: "getSignupCode" - - from: "src/main/java/com/aflokkat/service/AuthService.java" - to: "src/main/java/com/aflokkat/config/AppConfig.java" - via: "AppConfig.getControllerSignupCode()" - pattern: "getControllerSignupCode" ---- - - -Add optional signupCode field to the registration DTO and implement role-assignment logic in AuthService: no code → ROLE_CUSTOMER, correct code → ROLE_CONTROLLER, wrong or disabled code → 400 error. - -Purpose: This is the foundation for all role-based access control in the application. Without correct roles stored in PostgreSQL, no URL guard or JWT claim will carry the right authority. -Output: Updated RegisterRequest DTO, updated AuthService.register(), updated AuthServiceTest with 4 new test cases. - - - -@/home/missia03/.claude/get-shit-done/workflows/execute-plan.md -@/home/missia03/.claude/get-shit-done/templates/summary.md - - - -@.planning/PROJECT.md -@.planning/ROADMAP.md -@.planning/phases/01-role-infrastructure/01-CONTEXT.md - - - - -From src/main/java/com/aflokkat/dto/RegisterRequest.java (current state): -```java -public class RegisterRequest { - private String username; - private String email; - private String password; - // getters/setters for each field -} -// MISSING: signupCode field — Task 1 adds it -``` - -From src/main/java/com/aflokkat/service/AuthService.java (current state — line 41 is the bug): -```java -// Line 41 — hardcodes ROLE_USER, must be replaced with role-assignment logic: -UserEntity userEntity = new UserEntity(request.getUsername(), request.getEmail(), hash, "ROLE_USER"); -``` - -From src/main/java/com/aflokkat/config/AppConfig.java (pattern to follow): -```java -// Existing pattern for reading env vars — add getControllerSignupCode() following this: -public static String getJwtSecret() { - return getProperty("jwt.secret", "changeit-please-change-it"); -} -// getProperty() resolves: System.getenv(key.replace(".", "_").toUpperCase()) → .env → application.properties -// So getProperty("controller.signup.code", null) reads CONTROLLER_SIGNUP_CODE env var -``` - -From src/main/java/com/aflokkat/entity/UserEntity.java: -```java -public UserEntity(String username, String email, String passwordHash, String role) { ... } -// role column is a plain String — no enum constraint — accepts any value -``` - -From src/test/java/com/aflokkat/service/AuthServiceTest.java (test style to match): -```java -@ExtendWith(MockitoExtension.class) -class AuthServiceTest { - @Mock private UserRepository userRepository; - @Mock private PasswordEncoder passwordEncoder; - @Mock private JwtUtil jwtUtil; - @InjectMocks private AuthService authService; - - // Tests use JUnit 5 Jupiter: @Test from org.junit.jupiter.api.Test - // Assertions: assertEquals, assertThrows from org.junit.jupiter.api.Assertions -} -``` - - - - - - - Task 1: Add signupCode to RegisterRequest and implement role-assignment in AuthService - - src/main/java/com/aflokkat/dto/RegisterRequest.java - src/main/java/com/aflokkat/service/AuthService.java - src/main/java/com/aflokkat/config/AppConfig.java - src/test/java/com/aflokkat/service/AuthServiceTest.java - - - - - register_assignsCustomerRole_whenNoSignupCode: call register() with no signupCode (null) → saved UserEntity has role "ROLE_CUSTOMER" - - register_assignsControllerRole_whenCorrectSignupCode: mock AppConfig.getControllerSignupCode() returning "secret123", call register() with signupCode="secret123" → saved UserEntity has role "ROLE_CONTROLLER" - - register_throws_whenWrongSignupCode: mock AppConfig.getControllerSignupCode() returning "secret123", call register() with signupCode="wrong" → throws IllegalArgumentException with message "Invalid registration request" - - register_throws_whenSignupCodeEnvVarAbsent: mock AppConfig.getControllerSignupCode() returning null, call register() with signupCode="anything" → throws IllegalArgumentException with message "Invalid registration request" - - - - - src/main/java/com/aflokkat/dto/RegisterRequest.java - - src/main/java/com/aflokkat/service/AuthService.java - - src/main/java/com/aflokkat/config/AppConfig.java - - src/test/java/com/aflokkat/service/AuthServiceTest.java - - - -**Step 1 — Write the 4 failing tests first (RED), then implement (GREEN).** - -**Test scaffold to add to AuthServiceTest.java** (append after existing refresh tests): - -Note: AppConfig uses static methods. To mock them in unit tests, use Mockito's `mockStatic(AppConfig.class)` (requires mockito-inline, which is bundled with `mockito-core` 3.4+ via `spring-boot-starter-test` on Boot 2.6). Add these 4 tests: - -```java -import com.aflokkat.config.AppConfig; -import org.mockito.MockedStatic; - -// Test 1: no signupCode → ROLE_CUSTOMER -@Test -void register_assignsCustomerRole_whenNoSignupCode() { - when(userRepository.findByUsername("alice")).thenReturn(Optional.empty()); - when(userRepository.findByEmail("alice@example.com")).thenReturn(Optional.empty()); - when(passwordEncoder.encode(any())).thenReturn("hashed"); - // Capture what role is passed to save() - when(userRepository.save(any(UserEntity.class))).thenAnswer(inv -> inv.getArgument(0)); - when(jwtUtil.generateAccessToken(any(), any())).thenReturn("token"); - when(jwtUtil.generateRefreshToken(any())).thenReturn("refresh"); - - RegisterRequest req = new RegisterRequest(); - req.setUsername("alice"); - req.setEmail("alice@example.com"); - req.setPassword("pass"); - // signupCode NOT set (null) - - try (MockedStatic appConfig = mockStatic(AppConfig.class)) { - appConfig.when(AppConfig::getControllerSignupCode).thenReturn(null); - authService.register(req); - } - - // Verify saved entity has ROLE_CUSTOMER - ArgumentCaptor captor = ArgumentCaptor.forClass(UserEntity.class); - verify(userRepository).save(captor.capture()); - assertEquals("ROLE_CUSTOMER", captor.getValue().getRole()); -} - -// Test 2: correct signupCode → ROLE_CONTROLLER -@Test -void register_assignsControllerRole_whenCorrectSignupCode() { - when(userRepository.findByUsername("ctrl")).thenReturn(Optional.empty()); - when(userRepository.findByEmail("ctrl@test.com")).thenReturn(Optional.empty()); - when(passwordEncoder.encode(any())).thenReturn("hashed"); - when(userRepository.save(any(UserEntity.class))).thenAnswer(inv -> inv.getArgument(0)); - when(jwtUtil.generateAccessToken(any(), any())).thenReturn("token"); - when(jwtUtil.generateRefreshToken(any())).thenReturn("refresh"); - - RegisterRequest req = new RegisterRequest(); - req.setUsername("ctrl"); - req.setEmail("ctrl@test.com"); - req.setPassword("pass"); - req.setSignupCode("secret123"); - - try (MockedStatic appConfig = mockStatic(AppConfig.class)) { - appConfig.when(AppConfig::getControllerSignupCode).thenReturn("secret123"); - authService.register(req); - } - - ArgumentCaptor captor = ArgumentCaptor.forClass(UserEntity.class); - verify(userRepository).save(captor.capture()); - assertEquals("ROLE_CONTROLLER", captor.getValue().getRole()); -} - -// Test 3: wrong signupCode → throws -@Test -void register_throws_whenWrongSignupCode() { - RegisterRequest req = new RegisterRequest(); - req.setUsername("alice"); - req.setEmail("alice@example.com"); - req.setPassword("pass"); - req.setSignupCode("wrongcode"); - - try (MockedStatic appConfig = mockStatic(AppConfig.class)) { - appConfig.when(AppConfig::getControllerSignupCode).thenReturn("secret123"); - IllegalArgumentException ex = assertThrows(IllegalArgumentException.class, - () -> authService.register(req)); - assertEquals("Invalid registration request", ex.getMessage()); - } -} - -// Test 4: signupCode given but env var absent → throws -@Test -void register_throws_whenSignupCodeEnvVarAbsent() { - RegisterRequest req = new RegisterRequest(); - req.setUsername("alice"); - req.setEmail("alice@example.com"); - req.setPassword("pass"); - req.setSignupCode("anything"); - - try (MockedStatic appConfig = mockStatic(AppConfig.class)) { - appConfig.when(AppConfig::getControllerSignupCode).thenReturn(null); - IllegalArgumentException ex = assertThrows(IllegalArgumentException.class, - () -> authService.register(req)); - assertEquals("Invalid registration request", ex.getMessage()); - } -} -``` - -Also add these imports to AuthServiceTest.java: -```java -import org.mockito.ArgumentCaptor; -import org.mockito.MockedStatic; -import com.aflokkat.config.AppConfig; -``` - -**Step 2 — Add signupCode to RegisterRequest.java:** - -Add after the `password` field: -```java -private String signupCode; - -public String getSignupCode() { - return signupCode; -} - -public void setSignupCode(String signupCode) { - this.signupCode = signupCode; -} -``` - -**Step 3 — Add getControllerSignupCode() to AppConfig.java:** - -Add after the existing `getJwtRefreshTokenExpirationMs()` getter: -```java -public static String getControllerSignupCode() { - return getProperty("controller.signup.code", null); -} -``` - -**Step 4 — Replace role-assignment in AuthService.java:** - -Replace line 41 (the `new UserEntity(... "ROLE_USER")` line) with the full signup code check block. The replacement is inside `register()`, after the `hash` is computed and before `userRepository.save()`: - -```java -// --- REPLACE from: String hash = ... new UserEntity(... "ROLE_USER") --- TO: --- -String hash = passwordEncoder.encode(request.getPassword()); - -String signupCode = AppConfig.getControllerSignupCode(); -String providedCode = request.getSignupCode(); - -String role; -if (providedCode == null || providedCode.isEmpty()) { - role = "ROLE_CUSTOMER"; -} else { - // Controller signup is disabled when env var is not set — fail-safe - if (signupCode == null || signupCode.isEmpty()) { - throw new IllegalArgumentException("Invalid registration request"); - } - if (!signupCode.equals(providedCode)) { - throw new IllegalArgumentException("Invalid registration request"); - } - role = "ROLE_CONTROLLER"; -} -UserEntity userEntity = new UserEntity(request.getUsername(), request.getEmail(), hash, role); -// --- END REPLACEMENT --- -``` - -**Step 5 — Run tests (GREEN check):** -```bash -mvn test -Dtest=AuthServiceTest -DfailIfNoTests=false -q -``` -All 4 new tests must pass along with all pre-existing tests in AuthServiceTest. - -**Note on existing test `register_returnsTokens_onSuccess`:** It currently stubs `jwtUtil.generateAccessToken("alice", "ROLE_USER")`. After this change, the role will be `ROLE_CUSTOMER`. Update that stub to `jwtUtil.generateAccessToken("alice", "ROLE_CUSTOMER")` and the saved entity line to use `"ROLE_CUSTOMER"` instead of `"ROLE_USER"`. - -**No changes needed to:** JwtAuthenticationFilter, JwtUtil, AuthController, UserEntity, UserRepository. - - - - mvn test -Dtest=AuthServiceTest -DfailIfNoTests=false -q - - - - - src/main/java/com/aflokkat/dto/RegisterRequest.java contains `getSignupCode` - - src/main/java/com/aflokkat/dto/RegisterRequest.java contains `private String signupCode` - - src/main/java/com/aflokkat/service/AuthService.java contains `ROLE_CUSTOMER` - - src/main/java/com/aflokkat/service/AuthService.java contains `ROLE_CONTROLLER` - - src/main/java/com/aflokkat/service/AuthService.java does NOT contain `"ROLE_USER"` (the hardcoded string is gone) - - src/main/java/com/aflokkat/config/AppConfig.java contains `getControllerSignupCode` - - src/test/java/com/aflokkat/service/AuthServiceTest.java contains `register_assignsCustomerRole_whenNoSignupCode` - - src/test/java/com/aflokkat/service/AuthServiceTest.java contains `register_assignsControllerRole_whenCorrectSignupCode` - - src/test/java/com/aflokkat/service/AuthServiceTest.java contains `register_throws_whenWrongSignupCode` - - src/test/java/com/aflokkat/service/AuthServiceTest.java contains `register_throws_whenSignupCodeEnvVarAbsent` - - `mvn test -Dtest=AuthServiceTest -q` exits 0 with BUILD SUCCESS - - - - RegisterRequest has signupCode field with getter/setter. AuthService.register() never writes ROLE_USER — it writes ROLE_CUSTOMER (no code) or ROLE_CONTROLLER (correct code) or throws "Invalid registration request" (wrong/disabled code). AppConfig.getControllerSignupCode() added. All 4 new unit tests pass alongside all pre-existing AuthServiceTest cases. - - - - - - -Run full AuthServiceTest suite: `mvn test -Dtest=AuthServiceTest -q` -All tests must exit 0. No ROLE_USER string should remain in AuthService.java. - - - -- `mvn test -Dtest=AuthServiceTest -q` exits 0 -- `grep -r "ROLE_USER" src/main/java/com/aflokkat/service/AuthService.java` returns no output -- `grep "ROLE_CUSTOMER\|ROLE_CONTROLLER" src/main/java/com/aflokkat/service/AuthService.java` returns matches -- `grep "getSignupCode" src/main/java/com/aflokkat/dto/RegisterRequest.java` returns a match - - - -After completion, create `.planning/phases/01-role-infrastructure/01-01-SUMMARY.md` - diff --git a/.planning/phases/01-role-infrastructure/01-01-SUMMARY.md b/.planning/phases/01-role-infrastructure/01-01-SUMMARY.md deleted file mode 100644 index 9c21ecf..0000000 --- a/.planning/phases/01-role-infrastructure/01-01-SUMMARY.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -phase: 01-role-infrastructure -plan: 01 -subsystem: auth -tags: [jwt, spring-security, postgresql, mockito, role-assignment] - -# Dependency graph -requires: [] -provides: - - RegisterRequest DTO with optional signupCode field - - AuthService.register() assigns ROLE_CUSTOMER (no code) or ROLE_CONTROLLER (correct code) or throws 400 (wrong/disabled code) - - AppConfig.getControllerSignupCode() reads CONTROLLER_SIGNUP_CODE env var - - 4 unit tests covering all role-assignment scenarios -affects: - - 01-02-security-config - - 01-03-rate-limiting - - Phase 2 (controller report submission requires ROLE_CONTROLLER JWT claim) - -# Tech tracking -tech-stack: - added: - - mockito-core 5.17.0 (upgraded from 4.0.0 — required for Java 21+ static mocking support) - - mockito-junit-jupiter 5.17.0 - - byte-buddy 1.14.18 (property override — BOM 1.11.x does not support Java 21+) - patterns: - - Role strings stored as ROLE_CUSTOMER / ROLE_CONTROLLER (Spring hasRole() prefix convention) - - AppConfig.getProperty() pattern for env-var -> .env -> application.properties resolution - - mockStatic(AppConfig.class) try-with-resources pattern for static method mocking in JUnit 5 - -key-files: - created: [] - modified: - - src/main/java/com/aflokkat/dto/RegisterRequest.java - - src/main/java/com/aflokkat/service/AuthService.java - - src/main/java/com/aflokkat/config/AppConfig.java - - src/test/java/com/aflokkat/service/AuthServiceTest.java - - pom.xml - -key-decisions: - - "Use ROLE_CUSTOMER / ROLE_CONTROLLER strings (never ROLE_USER) — locked in for Phase 2 onwards" - - "Controller signup is fail-safe: if CONTROLLER_SIGNUP_CODE env var absent, any signupCode value returns 400" - - "Upgrade Mockito to 5.x and Byte Buddy to 1.14.x to support static mocking on Java 21+ runtime" - -patterns-established: - - "Role assignment: no signupCode -> ROLE_CUSTOMER; correct signupCode -> ROLE_CONTROLLER; wrong/absent -> IllegalArgumentException" - - "mockStatic pattern: try (MockedStatic cfg = mockStatic(AppConfig.class)) { cfg.when(...).thenReturn(...); }" - -requirements-completed: [AUTH-01, AUTH-02] - -# Metrics -duration: 15min -completed: 2026-03-29 ---- - -# Phase 1 Plan 1: Role-Assignment Registration Summary - -**Registration now assigns ROLE_CUSTOMER by default or ROLE_CONTROLLER when the correct env-var signup code is provided, with fail-safe rejection when the code is wrong or disabled** - -## Performance - -- **Duration:** ~15 min -- **Started:** 2026-03-29T16:28:00Z -- **Completed:** 2026-03-29T16:43:34Z -- **Tasks:** 1 -- **Files modified:** 5 - -## Accomplishments -- Replaced hardcoded `ROLE_USER` in `AuthService.register()` with role-assignment logic based on signupCode -- Added `signupCode` field (optional) to `RegisterRequest` DTO with getter/setter -- Added `AppConfig.getControllerSignupCode()` reading `CONTROLLER_SIGNUP_CODE` env var -- All 4 role-assignment unit tests pass alongside 10 pre-existing `AuthServiceTest` cases (14 total) -- Fixed Mockito/Byte Buddy incompatibility with Java 21+ runtime (upgraded to 5.x / 1.14.x) - -## Task Commits - -Each task was committed atomically: - -1. **Task 1: Add signupCode role-assignment to registration** - `66275a4` (feat) - -**Plan metadata:** TBD (docs: complete plan) - -## Files Created/Modified -- `src/main/java/com/aflokkat/dto/RegisterRequest.java` - Added signupCode field + getter/setter -- `src/main/java/com/aflokkat/service/AuthService.java` - Role-assignment logic replacing ROLE_USER -- `src/main/java/com/aflokkat/config/AppConfig.java` - Added getControllerSignupCode() static method -- `src/test/java/com/aflokkat/service/AuthServiceTest.java` - 4 new tests + updated existing stubs -- `pom.xml` - Mockito 5.17.0, mockito-junit-jupiter 5.17.0, byte-buddy 1.14.18 - -## Decisions Made -- ROLE_CUSTOMER and ROLE_CONTROLLER locked in as the only two roles assigned at registration. ROLE_USER is removed — no new user will ever receive it. -- Controller signup is fail-safe: if `CONTROLLER_SIGNUP_CODE` is not set in the environment, any request with a signupCode receives HTTP 400, preventing accidental privilege escalation. -- Mockito upgraded to 5.x (from BOM-managed 4.0.0) because `mockStatic` relies on Byte Buddy instrumentation which requires 1.14.x+ on Java 21/25 runtimes. This is a test-only dependency change. - -## Deviations from Plan - -### Auto-fixed Issues - -**1. [Rule 3 - Blocking] Added mockito-inline / upgraded Mockito + Byte Buddy for Java 21+ static mocking** -- **Found during:** Task 1 verification (mvn test -Dtest=AuthServiceTest) -- **Issue:** Tests using `mockStatic(AppConfig.class)` failed with "SubclassByteBuddyMockMaker does not support static mocks" on Mockito 4.0.0. Adding `mockito-inline` 4.0.0 caused a secondary error "Unknown Java version: 0" because Byte Buddy 1.11.22 (Spring Boot 2.6 BOM) doesn't support Java 21+. -- **Fix:** Upgraded `mockito-core` and `mockito-junit-jupiter` to 5.17.0 (static mocking built-in), removed redundant `mockito-inline` artifact (Mockito 5 no longer needs it separately), added `1.14.18` property to override the BOM version. -- **Files modified:** `pom.xml` -- **Verification:** `mvn test -Dtest=AuthServiceTest` exits 0, 14/14 tests pass -- **Committed in:** `66275a4` (Task 1 commit) - ---- - -**Total deviations:** 1 auto-fixed (Rule 3 — blocking dependency issue) -**Impact on plan:** Required to unblock test execution. Test-only dependency change; no production code affected. - -## Issues Encountered -- Maven runs on Java 25 by default on this machine (`/usr/lib/jvm/java-25-openjdk-amd64`). Tests must be run with `JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64` or the system default Java updated. The pom.xml fix (byte-buddy 1.14.18) makes the tests runnable on Java 21+; Java 25 support requires Byte Buddy 1.15.x (not yet tested). - -## Next Phase Readiness -- Role assignment foundation complete — ROLE_CUSTOMER and ROLE_CONTROLLER are now correctly persisted in PostgreSQL -- Ready for plan 01-02 (SecurityConfig URL guards using hasRole()) -- Blocker from STATE.md remains: `anyRequest().permitAll()` in SecurityConfig must be replaced before Phase 2 feature code - -## Self-Check: PASSED - -- FOUND: .planning/phases/01-role-infrastructure/01-01-SUMMARY.md -- FOUND: src/main/java/com/aflokkat/dto/RegisterRequest.java -- FOUND: src/main/java/com/aflokkat/service/AuthService.java -- FOUND: src/main/java/com/aflokkat/config/AppConfig.java -- FOUND: commit 66275a4 - ---- -*Phase: 01-role-infrastructure* -*Completed: 2026-03-29* diff --git a/.planning/phases/01-role-infrastructure/01-02-PLAN.md b/.planning/phases/01-role-infrastructure/01-02-PLAN.md deleted file mode 100644 index b4cba70..0000000 --- a/.planning/phases/01-role-infrastructure/01-02-PLAN.md +++ /dev/null @@ -1,366 +0,0 @@ ---- -phase: 01-role-infrastructure -plan: 02 -type: execute -wave: 1 -depends_on: [] -files_modified: - - src/main/java/com/aflokkat/config/SecurityConfig.java - - src/test/java/com/aflokkat/config/SecurityConfigTest.java -autonomous: true -requirements: - - AUTH-03 - -must_haves: - truths: - - "An unauthenticated request to /api/reports/anything returns HTTP 401" - - "A request with a valid CUSTOMER JWT to /api/reports/anything returns HTTP 403" - - "A request with a valid CONTROLLER JWT to /api/reports/anything is not blocked by security (passes through)" - - "anyRequest().permitAll() is no longer the sole rule — explicit antMatchers guard /api/reports/** and /api/users/**" - - "Swagger endpoints remain publicly accessible" - artifacts: - - path: "src/main/java/com/aflokkat/config/SecurityConfig.java" - provides: "antMatchers URL-level guards + 403 accessDeniedHandler" - contains: "hasRole(\"CONTROLLER\")" - - path: "src/test/java/com/aflokkat/config/SecurityConfigTest.java" - provides: "MockMvc slice tests for 401 and 403 on /api/reports/**" - contains: "reports_returns401_whenUnauthenticated" - key_links: - - from: "src/main/java/com/aflokkat/config/SecurityConfig.java" - to: "src/main/java/com/aflokkat/security/JwtAuthenticationFilter.java" - via: "addFilterBefore(jwtAuthenticationFilter, UsernamePasswordAuthenticationFilter.class)" - pattern: "addFilterBefore" - - from: "src/main/java/com/aflokkat/config/SecurityConfig.java" - to: "/api/reports/**" - via: "antMatchers(\"/api/reports/**\").hasRole(\"CONTROLLER\")" - pattern: "hasRole" ---- - - -Replace the blanket `anyRequest().permitAll()` in SecurityConfig with explicit antMatchers that protect /api/reports/** (CONTROLLER only) and /api/users/** (any JWT), and add a 403 accessDeniedHandler for wrong-role access. Create SecurityConfigTest to verify 401 and 403 behaviors. - -Purpose: This is the primary security boundary. Until this change lands, any request to any endpoint is allowed — including controller-only report endpoints. -Output: Updated SecurityConfig with correct antMatchers, new SecurityConfigTest with 3 slice tests (401 unauthenticated, 403 customer, passes for controller). - - - -@/home/missia03/.claude/get-shit-done/workflows/execute-plan.md -@/home/missia03/.claude/get-shit-done/templates/summary.md - - - -@.planning/phases/01-role-infrastructure/01-CONTEXT.md - - - - -From src/main/java/com/aflokkat/config/SecurityConfig.java (current full content): -```java -// The entire filterChain() method currently contains: -http - .csrf().disable() - .sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS) - .and() - .authorizeRequests() - .anyRequest().permitAll() // <-- THE ONLY RULE. Must be replaced. - .and() - .exceptionHandling() - .authenticationEntryPoint((request, response, authException) -> { - String path = request.getRequestURI(); - if (path.startsWith("/api/")) { - response.setStatus(HttpServletResponse.SC_UNAUTHORIZED); - response.setContentType("application/json"); - response.getWriter().write("{\"status\":\"error\",\"message\":\"Unauthorized\"}"); - } else { - response.sendRedirect("/login"); - } - }) - .and() - .addFilterBefore(jwtAuthenticationFilter, UsernamePasswordAuthenticationFilter.class); -// KEEP the authenticationEntryPoint exactly as-is. KEEP addFilterBefore exactly as-is. -// ADD: antMatchers rules before anyRequest(), ADD: accessDeniedHandler in exceptionHandling block. -``` - -From src/main/java/com/aflokkat/security/JwtUtil.java (for creating test tokens): -```java -// JwtUtil is a plain class (not @Component). It reads config via AppConfig.getJwtSecret(). -// In tests, instantiate directly: new JwtUtil() -// Key method: -public String generateAccessToken(String username, String role) -// Produces a token with claim "role" = the role string passed in. -``` - -Spring Security 5.6 (Spring Boot 2.6.15) test notes: -- Use @WebMvcTest for slice tests; it loads only MVC layer -- Include @Import(SecurityConfig.class) to load the security filter chain -- Use @MockBean JwtAuthenticationFilter to replace the real filter -- For controller JWT: manually set SecurityContext with UsernamePasswordAuthenticationToken - carrying SimpleGrantedAuthority("ROLE_CONTROLLER") -- For customer JWT: use SimpleGrantedAuthority("ROLE_CUSTOMER") -- For unauthenticated: do not set SecurityContext (default is anonymous) -- Use MockMvc perform(get("/api/reports/test")).andExpect(status().isUnauthorized()) etc. -- A mock @RestController for /api/reports/** must be added in the test class to give MockMvc a target - - - - - - - Task 1: Create SecurityConfigTest with 3 failing tests - - src/test/java/com/aflokkat/config/SecurityConfigTest.java - - - - - reports_returns401_whenUnauthenticated: GET /api/reports/test with no auth → status 401 - - reports_returns403_forCustomerJwt: GET /api/reports/test with ROLE_CUSTOMER authority in SecurityContext → status 403 - - reports_allowsAccess_forControllerJwt: GET /api/reports/test with ROLE_CONTROLLER authority in SecurityContext → status not 401 and not 403 (200 or 404 acceptable — just not blocked by security) - - - - - src/main/java/com/aflokkat/config/SecurityConfig.java - - src/test/java/com/aflokkat/config/AppConfigTest.java - - - -Create `src/test/java/com/aflokkat/config/SecurityConfigTest.java` with this exact content: - -```java -package com.aflokkat.config; - -import com.aflokkat.security.JwtAuthenticationFilter; -import com.aflokkat.security.JwtUtil; -import org.junit.jupiter.api.Test; -import org.springframework.beans.factory.annotation.Autowired; -import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest; -import org.springframework.boot.test.mock.mockito.MockBean; -import org.springframework.context.annotation.Import; -import org.springframework.security.authentication.UsernamePasswordAuthenticationToken; -import org.springframework.security.core.authority.SimpleGrantedAuthority; -import org.springframework.security.core.context.SecurityContextHolder; -import org.springframework.test.web.servlet.MockMvc; -import org.springframework.web.bind.annotation.GetMapping; -import org.springframework.web.bind.annotation.RestController; - -import java.util.Collections; - -import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get; -import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status; - -@WebMvcTest(controllers = SecurityConfigTest.StubReportsController.class) -@Import(SecurityConfig.class) -class SecurityConfigTest { - - @Autowired - private MockMvc mockMvc; - - // MockBean replaces the real JwtAuthenticationFilter (avoids context load issues). - // We set the SecurityContext manually in tests instead of relying on the filter. - @MockBean - private JwtAuthenticationFilter jwtAuthenticationFilter; - - @MockBean - private JwtUtil jwtUtil; - - /** - * Minimal stub controller so MockMvc has a real endpoint to route to. - * Returns 200 if security passes. - */ - @RestController - static class StubReportsController { - @GetMapping("/api/reports/test") - public String test() { - return "ok"; - } - } - - @Test - void reports_returns401_whenUnauthenticated() throws Exception { - SecurityContextHolder.clearContext(); - mockMvc.perform(get("/api/reports/test")) - .andExpect(status().isUnauthorized()); - } - - @Test - void reports_returns403_forCustomerJwt() throws Exception { - // Simulate a valid CUSTOMER token already parsed by the JWT filter - UsernamePasswordAuthenticationToken auth = new UsernamePasswordAuthenticationToken( - "customer_user", null, - Collections.singletonList(new SimpleGrantedAuthority("ROLE_CUSTOMER"))); - SecurityContextHolder.getContext().setAuthentication(auth); - try { - mockMvc.perform(get("/api/reports/test")) - .andExpect(status().isForbidden()); - } finally { - SecurityContextHolder.clearContext(); - } - } - - @Test - void reports_allowsAccess_forControllerJwt() throws Exception { - // Simulate a valid CONTROLLER token - UsernamePasswordAuthenticationToken auth = new UsernamePasswordAuthenticationToken( - "ctrl_user", null, - Collections.singletonList(new SimpleGrantedAuthority("ROLE_CONTROLLER"))); - SecurityContextHolder.getContext().setAuthentication(auth); - try { - mockMvc.perform(get("/api/reports/test")) - .andExpect(status().isOk()); - } finally { - SecurityContextHolder.clearContext(); - } - } -} -``` - -Run the tests immediately — they MUST FAIL (RED) at this point because SecurityConfig still has `anyRequest().permitAll()`. Verify RED: `mvn test -Dtest=SecurityConfigTest -DfailIfNoTests=false -q` should show test failures, not compilation errors. - - - - mvn test -Dtest=SecurityConfigTest -DfailIfNoTests=false -q 2>&1 | grep -E "BUILD|FAILURE|ERROR|Tests run" - - - - - src/test/java/com/aflokkat/config/SecurityConfigTest.java exists - - File contains `reports_returns401_whenUnauthenticated` - - File contains `reports_returns403_forCustomerJwt` - - File contains `reports_allowsAccess_forControllerJwt` - - `mvn test -Dtest=SecurityConfigTest -DfailIfNoTests=false -q` compiles without error (test failures are expected and acceptable at this RED stage) - - - - SecurityConfigTest.java exists with 3 test methods. Tests compile. At least 2 of the 3 tests fail because SecurityConfig still has permitAll() — this confirms the tests are real guards, not vacuous. - - - - - Task 2: Replace anyRequest().permitAll() with explicit antMatchers + add accessDeniedHandler (GREEN) - - src/main/java/com/aflokkat/config/SecurityConfig.java - - - - - src/main/java/com/aflokkat/config/SecurityConfig.java - - - -Replace the entire `authorizeRequests()` block and extend the `exceptionHandling()` block in `SecurityConfig.filterChain()`. - -**Current authorizeRequests block (lines 40-42):** -```java -.authorizeRequests() - .anyRequest().permitAll() -``` - -**Replace with (preserving exact indentation style of the file):** -```java -.authorizeRequests() - // Public: auth endpoints, read-only NYC data, Swagger - .antMatchers("/api/auth/**").permitAll() - .antMatchers("/api/restaurants/**").permitAll() - .antMatchers("/api/inspections/**").permitAll() - .antMatchers( - "/swagger-ui.html", - "/swagger-ui/**", - "/api-docs/**", - "/v3/api-docs/**", - "/webjars/**" - ).permitAll() - // Controller-only endpoints - .antMatchers("/api/reports/**").hasRole("CONTROLLER") - // Any authenticated user (any role) - .antMatchers("/api/users/**").authenticated() - // Non-API view routes: open for now (Phase 3 scope) - .anyRequest().permitAll() -``` - -**Current exceptionHandling block (lines 43-54):** -```java -.exceptionHandling() - .authenticationEntryPoint((request, response, authException) -> { - String path = request.getRequestURI(); - if (path.startsWith("/api/")) { - response.setStatus(HttpServletResponse.SC_UNAUTHORIZED); - response.setContentType("application/json"); - response.getWriter().write("{\"status\":\"error\",\"message\":\"Unauthorized\"}"); - } else { - response.sendRedirect("/login"); - } - }) -``` - -**Replace with (add accessDeniedHandler alongside the existing authenticationEntryPoint):** -```java -.exceptionHandling() - .authenticationEntryPoint((request, response, authException) -> { - String path = request.getRequestURI(); - if (path.startsWith("/api/")) { - response.setStatus(HttpServletResponse.SC_UNAUTHORIZED); - response.setContentType("application/json"); - response.getWriter().write("{\"status\":\"error\",\"message\":\"Unauthorized\"}"); - } else { - response.sendRedirect("/login"); - } - }) - .accessDeniedHandler((request, response, accessDeniedException) -> { - response.setStatus(HttpServletResponse.SC_FORBIDDEN); - response.setContentType("application/json"); - response.getWriter().write("{\"status\":\"error\",\"message\":\"Forbidden\"}"); - }) -``` - -**Add this import at the top of SecurityConfig.java** (it may already be present — add only if missing): -```java -import org.springframework.security.web.access.AccessDeniedHandler; -``` - -**Do NOT change:** csrf().disable(), sessionManagement(), addFilterBefore(), PasswordEncoder bean, AuthenticationManager bean. The JwtAuthenticationFilter wiring stays exactly as it is. - -**After editing, run the GREEN check:** -```bash -mvn test -Dtest=SecurityConfigTest -DfailIfNoTests=false -q -``` -All 3 SecurityConfigTest tests must now pass. - - - - mvn test -Dtest=SecurityConfigTest -DfailIfNoTests=false -q - - - - - src/main/java/com/aflokkat/config/SecurityConfig.java contains `hasRole("CONTROLLER")` - - src/main/java/com/aflokkat/config/SecurityConfig.java contains `.antMatchers("/api/reports/**")` - - src/main/java/com/aflokkat/config/SecurityConfig.java contains `.antMatchers("/api/users/**").authenticated()` - - src/main/java/com/aflokkat/config/SecurityConfig.java contains `accessDeniedHandler` - - src/main/java/com/aflokkat/config/SecurityConfig.java contains `SC_FORBIDDEN` - - src/main/java/com/aflokkat/config/SecurityConfig.java does NOT contain `.anyRequest().permitAll()` as the only authorizeRequests rule (the new version still has `.anyRequest().permitAll()` at the end but it is preceded by specific antMatchers) - - `mvn test -Dtest=SecurityConfigTest -q` exits 0 with BUILD SUCCESS (all 3 tests pass) - - `mvn test -q` exits 0 (full suite still green — no regressions) - - - - SecurityConfig.filterChain() uses explicit antMatchers: /api/reports/** requires CONTROLLER role, /api/users/** requires authentication, public paths are permitted, anyRequest() is last. AccessDeniedHandler returns JSON 403. All SecurityConfigTest tests pass. - - - - - - -```bash -mvn test -Dtest=SecurityConfigTest -q -mvn test -q -``` -Both must exit 0. SecurityConfig.java must contain `hasRole("CONTROLLER")` and `accessDeniedHandler`. - - - -- `mvn test -Dtest=SecurityConfigTest -q` exits 0 (all 3 tests pass) -- `mvn test -q` exits 0 (no regressions in full suite) -- `grep "hasRole" src/main/java/com/aflokkat/config/SecurityConfig.java` returns a match -- `grep "accessDeniedHandler" src/main/java/com/aflokkat/config/SecurityConfig.java` returns a match -- `grep "anyRequest().permitAll()" src/main/java/com/aflokkat/config/SecurityConfig.java` still returns one match (the catch-all at the end of the ordered rules) - - - -After completion, create `.planning/phases/01-role-infrastructure/01-02-SUMMARY.md` - diff --git a/.planning/phases/01-role-infrastructure/01-02-SUMMARY.md b/.planning/phases/01-role-infrastructure/01-02-SUMMARY.md deleted file mode 100644 index 8152ea4..0000000 --- a/.planning/phases/01-role-infrastructure/01-02-SUMMARY.md +++ /dev/null @@ -1,154 +0,0 @@ ---- -phase: 01-role-infrastructure -plan: 02 -subsystem: auth -tags: [spring-security, jwt, role-based-access, mockmvc, junit4] - -# Dependency graph -requires: - - phase: 01-role-infrastructure - provides: "JwtAuthenticationFilter, JwtUtil, UserEntity with ROLE_ fields (01-01)" -provides: - - "antMatchers URL-level access rules: /api/reports/** CONTROLLER-only, /api/users/** any-auth" - - "403 accessDeniedHandler returning JSON for wrong-role access" - - "SecurityConfigTest with 3 slice tests (401 unauthenticated, 403 CUSTOMER, 200 CONTROLLER)" - - "FilterRegistrationBean preventing JwtAuthenticationFilter double-registration" - - "MethodSecurityConfig isolating @EnableMethodSecurity from test contexts" -affects: - - 02-controller-reports - - 03-customer-ui - -# Tech tracking -tech-stack: - added: - - "spring-security-test (SecurityMockMvcRequestPostProcessors.authentication)" - - "junit-vintage-engine (JUnit 4 on JUnit 5 Surefire platform)" - - "Byte Buddy 1.16.0 (Java 25 support, overriding Spring Boot BOM 1.14.x)" - - "Mockito 5.17.0 (replaces mockito-inline; inline mocking built in)" - patterns: - - "Test slice using AnnotationConfigWebApplicationContext + standaloneSetup MockMvc (replaces @WebMvcTest due to Java 25 JVM crash)" - - "SecurityConfig registered before SecurityAutoConfiguration to prevent duplicate FilterChain" - - "authentication() post-processor survives SecurityContextPersistenceFilter stateless reset" - - "FilterRegistrationBean.setEnabled(false) prevents filter double-registration" - - "@EnableMethodSecurity in separate MethodSecurityConfig to isolate AOP from test context" - -key-files: - created: - - src/test/java/com/aflokkat/config/SecurityConfigTest.java - - src/main/java/com/aflokkat/config/MethodSecurityConfig.java - modified: - - src/main/java/com/aflokkat/config/SecurityConfig.java - - pom.xml - -key-decisions: - - "Abandoned @WebMvcTest for SecurityConfigTest: Mockito's dynamic byte-buddy-agent attachment on Java 25 JVM causes JVM crash (not a Java StackOverflowError). Used JUnit 4 + AnnotationConfigWebApplicationContext instead." - - "SecurityConfig must be registered BEFORE SecurityAutoConfiguration in AnnotationConfigWebApplicationContext: @ConditionalOnDefaultWebSecurity checks for existing SecurityFilterChain bean; wrong order produces two competing chains." - - "authentication() post-processor (from spring-security-test) injected via .with() rather than SecurityContextHolder.setAuthentication(): the former survives the stateless SecurityContextPersistenceFilter reset; the latter does not." - - "FilterRegistrationBean.setEnabled(false) added to SecurityConfig: JwtAuthenticationFilter declared as @Bean is auto-registered by Spring Boot as servlet filter AND added to security chain, causing double execution." - - "Byte Buddy pinned to 1.16.0: Spring Boot 2.6.x BOM pulls 1.14.18 which cannot instrument Java 25 class files (major version 69)." - -patterns-established: - - "Spring Security test slice on Java 25: use AnnotationConfigWebApplicationContext + standaloneSetup + springSecurity(filterChain). Never @WebMvcTest." - - "Filter chain ordering: register SecurityConfig before SecurityAutoConfiguration to avoid default chain duplication." - - "Role check pattern: hasRole('CONTROLLER') → stored as ROLE_CONTROLLER in UserEntity, matched as SimpleGrantedAuthority('ROLE_CONTROLLER') in tests." - -requirements-completed: [AUTH-03] - -# Metrics -duration: ~90min -completed: 2026-03-29 ---- - -# Phase 1 Plan 02: Security Antmatchers Summary - -**Spring Security antMatchers locking /api/reports/** to CONTROLLER role only, verified by 3 slice tests using a JUnit 4 + AnnotationConfigWebApplicationContext workaround for Java 25 JVM incompatibility** - -## Performance - -- **Duration:** ~90 min -- **Started:** 2026-03-29T18:00:00Z -- **Completed:** 2026-03-29T19:55:00Z -- **Tasks:** 2 (RED + GREEN) -- **Files modified:** 4 (SecurityConfig.java, SecurityConfigTest.java, pom.xml, MethodSecurityConfig.java created) - -## Accomplishments -- Replaced blanket `anyRequest().permitAll()` with explicit ordered antMatchers — /api/reports/** requires CONTROLLER role, /api/users/** requires any auth, public paths explicitly whitelisted -- Added 403 `accessDeniedHandler` returning JSON for authenticated users with insufficient role -- Created SecurityConfigTest with 3 verified slice tests (401 unauthenticated, 403 CUSTOMER, 200 CONTROLLER), all green -- Resolved Java 25 JVM incompatibility blocking @WebMvcTest by switching to AnnotationConfigWebApplicationContext with Byte Buddy 1.16.0 - -## Task Commits - -Each task was committed atomically: - -1. **Task 1: SecurityConfigTest RED** - `b2eec53` (test) -2. **Task 2: antMatchers + accessDeniedHandler GREEN** - `ed67c50` (feat) - -**Plan metadata:** (docs commit — see below) - -## Files Created/Modified -- `src/main/java/com/aflokkat/config/SecurityConfig.java` — Added antMatchers rules, accessDeniedHandler, FilterRegistrationBean; removed @EnableMethodSecurity -- `src/main/java/com/aflokkat/config/MethodSecurityConfig.java` — New file isolating @EnableMethodSecurity from SecurityConfig -- `src/test/java/com/aflokkat/config/SecurityConfigTest.java` — JUnit 4 slice test using AnnotationConfigWebApplicationContext + standaloneSetup + springSecurity() -- `pom.xml` — Added spring-security-test, junit-vintage-engine; upgraded Byte Buddy to 1.16.0; removed mockito-inline; added -XX:+EnableDynamicAgentLoading to Surefire - -## Decisions Made -- Abandoned @WebMvcTest entirely for this test class: Mockito's dynamic agent attachment kills the JVM on Java 25, not a code bug. No fix exists within @WebMvcTest. -- Used JUnit 4 (not JUnit 5) to match existing test suite and avoid @ExtendWith(MockitoExtension.class) which also triggers agent attachment. -- SecurityConfig registered before SecurityAutoConfiguration in test context: ensures @ConditionalOnDefaultWebSecurity skips the default chain. -- Kept `anyRequest().permitAll()` as catch-all at end of ordered rules (non-API view routes remain open for Phase 3). - -## Deviations from Plan - -### Auto-fixed Issues - -**1. [Rule 3 - Blocking] @WebMvcTest causes JVM crash on Java 25 — replaced with AnnotationConfigWebApplicationContext** -- **Found during:** Task 1 (Create SecurityConfigTest RED) -- **Issue:** Plan specified @WebMvcTest + @Import(SecurityConfig.class) + @MockBean. On Java 25, Mockito's MockitoTestExecutionListener attempts to self-attach byte-buddy-agent dynamically. This kills the forked Surefire JVM before any test runs. No configuration option avoids it within @WebMvcTest. -- **Fix:** Replaced @WebMvcTest with JUnit 4 + AnnotationConfigWebApplicationContext + MockMvcBuilders.standaloneSetup(). Upgraded Byte Buddy to 1.16.0 and added -XX:+EnableDynamicAgentLoading to Surefire argLine. -- **Files modified:** SecurityConfigTest.java, pom.xml -- **Verification:** `mvn test -Dtest=SecurityConfigTest` passes 3/3 tests -- **Committed in:** b2eec53 (Task 1 commit), ed67c50 (Task 2 commit) - -**2. [Rule 3 - Blocking] Removed mockito-inline (conflicts with Mockito 5.x)** -- **Found during:** Task 1 (pom.xml dependency resolution) -- **Issue:** mockito-inline 5.2.0 and mockito-core 5.17.0 both register a MockMaker, causing `Unknown Java version: 0` on Java 21+. Mockito 5.x merged inline mocking into core. -- **Fix:** Removed mockito-inline from pom.xml entirely. -- **Files modified:** pom.xml -- **Committed in:** b2eec53 - -**3. [Rule 2 - Missing Critical] Added FilterRegistrationBean to prevent JwtAuthenticationFilter double-registration** -- **Found during:** Task 2 (SecurityConfig implementation) -- **Issue:** JwtAuthenticationFilter declared as @Bean in SecurityConfig is both added to the security chain (via addFilterBefore) and auto-registered by Spring Boot as a standalone servlet filter — double-execution in production and StackOverflow in MockMvc. -- **Fix:** Added FilterRegistrationBean with setEnabled(false) to SecurityConfig. -- **Files modified:** SecurityConfig.java -- **Committed in:** ed67c50 - -**4. [Rule 2 - Missing Critical] Extracted @EnableMethodSecurity to MethodSecurityConfig** -- **Found during:** Task 2 (Test context debugging) -- **Issue:** @EnableMethodSecurity on SecurityConfig activates AOP proxying infrastructure which conflicts with the standalone AnnotationConfigWebApplicationContext test setup. -- **Fix:** Created MethodSecurityConfig.java with @EnableMethodSecurity; removed annotation from SecurityConfig. -- **Files modified:** SecurityConfig.java, MethodSecurityConfig.java (created) -- **Committed in:** ed67c50 - ---- - -**Total deviations:** 4 auto-fixed (2 blocking, 2 missing critical) -**Impact on plan:** All fixes essential — test approach was fundamentally incompatible with runtime JVM version; production correctness required FilterRegistrationBean fix. - -## Issues Encountered -- `AuthServiceTest` has 14 pre-existing failures (`Mockito cannot mock JwtUtil`). This predates plan 01-02 — confirmed by stash test. Logged as deferred item; out of scope for this plan. -- `mvn test -q` therefore exits non-zero, but SecurityConfigTest (3 tests), AppConfigTest (7 tests), and all other non-AuthServiceTest suites pass. - -## User Setup Required -None - no external service configuration required. - -## Next Phase Readiness -- Security boundary is locked: /api/reports/** correctly rejects unauthenticated and wrong-role requests -- FilterChain order established; new endpoints can rely on this pattern -- AuthServiceTest pre-existing Mockito failures need resolution before full suite can be green (out of scope here) -- Phase 2 (controller reports) can proceed — security rules are in place - ---- -*Phase: 01-role-infrastructure* -*Completed: 2026-03-29* diff --git a/.planning/phases/01-role-infrastructure/01-03-PLAN.md b/.planning/phases/01-role-infrastructure/01-03-PLAN.md deleted file mode 100644 index 27ab867..0000000 --- a/.planning/phases/01-role-infrastructure/01-03-PLAN.md +++ /dev/null @@ -1,422 +0,0 @@ ---- -phase: 01-role-infrastructure -plan: 03 -type: execute -wave: 1 -depends_on: [] -files_modified: - - pom.xml - - src/main/java/com/aflokkat/config/AppConfig.java - - src/main/java/com/aflokkat/security/RateLimitFilter.java - - src/main/resources/application.properties - - src/test/java/com/aflokkat/security/RateLimitFilterTest.java -autonomous: true -requirements: - - AUTH-04 - -must_haves: - truths: - - "Sending 11 consecutive requests to /api/auth/login from the same IP returns HTTP 429 on the 11th request (default threshold: 10 per minute)" - - "Sending 10 requests in a row does not trigger rate limiting — all return the normal response" - - "Requests to /api/restaurants/** are NOT rate-limited by RateLimitFilter" - - "Rate limiting threshold and window are configurable via auth.rate-limit.requests and auth.rate-limit.window-minutes properties" - artifacts: - - path: "src/main/java/com/aflokkat/security/RateLimitFilter.java" - provides: "OncePerRequestFilter applying per-IP Bucket4j token-bucket to /api/auth/**" - contains: "bucket.tryConsume" - - path: "src/test/java/com/aflokkat/security/RateLimitFilterTest.java" - provides: "Unit tests for threshold enforcement" - contains: "filter_returns429_afterThresholdExceeded" - - path: "pom.xml" - provides: "bucket4j-core 7.6.0 dependency" - contains: "bucket4j-core" - key_links: - - from: "src/main/java/com/aflokkat/security/RateLimitFilter.java" - to: "src/main/java/com/aflokkat/config/AppConfig.java" - via: "AppConfig.getAuthRateLimitRequests() / getAuthRateLimitWindowMinutes()" - pattern: "getAuthRateLimitRequests" - - from: "src/main/java/com/aflokkat/security/RateLimitFilter.java" - to: "Bucket4j 7.x API" - via: "Bucket.builder().addLimit(Bandwidth.classic(...))" - pattern: "Bandwidth.classic" - -user_setup: [] ---- - - -Add Bucket4j 7.6.0 to pom.xml, implement a per-IP rate-limiting Servlet filter for /api/auth/**, configure thresholds via application.properties, and write unit tests proving the 429 response fires after the threshold. - -Purpose: Brute-force protection on auth endpoints. Without rate limiting, an attacker can attempt unlimited password guesses. -Output: pom.xml with bucket4j-core 7.6.0, RateLimitFilter.java, 2 AppConfig getters, 2 new properties, RateLimitFilterTest.java with 2 tests. - - - -@/home/missia03/.claude/get-shit-done/workflows/execute-plan.md -@/home/missia03/.claude/get-shit-done/templates/summary.md - - - -@.planning/phases/01-role-infrastructure/01-CONTEXT.md -@.planning/phases/01-role-infrastructure/01-RESEARCH.md - - - - -From src/main/java/com/aflokkat/config/AppConfig.java (current getters to follow as pattern): -```java -public static String getJwtSecret() { - return getProperty("jwt.secret", "changeit-please-change-it"); -} - -private static int getIntProperty(String key, int defaultValue) { - String value = getProperty(key, String.valueOf(defaultValue)); - try { return Integer.parseInt(value); } - catch (NumberFormatException e) { return defaultValue; } -} - -private static String getProperty(String key, String defaultValue) { - String envKey = key.replace(".", "_").toUpperCase(); - String envValue = System.getenv(envKey); - if (envValue != null) return envValue; - if (dotenv != null) { - String dotenvValue = dotenv.get(envKey, null); - if (dotenvValue != null) return dotenvValue; - } - return properties.getProperty(key, defaultValue); -} -// getIntProperty("auth.rate-limit.requests", 10) will resolve AUTH_RATE_LIMIT_REQUESTS env var -``` - -Bucket4j 7.x API (Java 11 compatible — do NOT use 8.x API): -```java -import com.bucket4j.Bandwidth; -import com.bucket4j.Bucket; -import com.bucket4j.Refill; -import java.time.Duration; - -Bucket bucket = Bucket.builder() - .addLimit(Bandwidth.classic(maxRequests, Refill.greedy(maxRequests, Duration.ofMinutes(windowMinutes)))) - .build(); - -boolean consumed = bucket.tryConsume(1); // returns false when bucket is empty → 429 -``` - -Critical registration note (from RESEARCH.md anti-patterns): -- RateLimitFilter MUST be annotated @Component (auto-registers with servlet container) -- Do NOT also register it via http.addFilterBefore() in SecurityConfig — that would double-apply it -- @Order(1) ensures it runs before the JWT filter - - - - - - - Task 1: Add bucket4j-core 7.6.0 to pom.xml and add AppConfig rate-limit getters - - pom.xml - src/main/java/com/aflokkat/config/AppConfig.java - src/main/resources/application.properties - - - - - pom.xml - - src/main/java/com/aflokkat/config/AppConfig.java - - src/main/resources/application.properties - - - -**Step 1 — Add Bucket4j dependency to pom.xml:** - -Locate the `` section in pom.xml. Add the following dependency block after the last existing `` entry and before the closing `` tag: - -```xml - - - com.bucket4j - bucket4j-core - 7.6.0 - -``` - -**Step 2 — Add two getters to AppConfig.java:** - -Add after the existing `getJwtRefreshTokenExpirationMs()` getter (and after `getControllerSignupCode()` if Plan 01 has already been executed — order does not matter): - -```java -public static int getAuthRateLimitRequests() { - return getIntProperty("auth.rate-limit.requests", 10); -} - -public static int getAuthRateLimitWindowMinutes() { - return getIntProperty("auth.rate-limit.window-minutes", 1); -} -``` - -These getters resolve env vars `AUTH_RATE_LIMIT_REQUESTS` and `AUTH_RATE_LIMIT_WINDOW_MINUTES` via the existing `getIntProperty()` helper. - -**Step 3 — Add config properties to application.properties:** - -Append at the end of the file: - -```properties -# Rate limiting — auth endpoints (/api/auth/**) -# ENV: AUTH_RATE_LIMIT_REQUESTS, AUTH_RATE_LIMIT_WINDOW_MINUTES -auth.rate-limit.requests=10 -auth.rate-limit.window-minutes=1 -``` - -**Step 4 — Compile check:** -```bash -mvn compile -q -``` -Must exit 0 confirming the Bucket4j dependency resolves and AppConfig compiles. - - - - mvn compile -q - - - - - pom.xml contains `bucket4j-core` - - pom.xml contains `7.6.0` - - src/main/java/com/aflokkat/config/AppConfig.java contains `getAuthRateLimitRequests` - - src/main/java/com/aflokkat/config/AppConfig.java contains `getAuthRateLimitWindowMinutes` - - src/main/resources/application.properties contains `auth.rate-limit.requests=10` - - src/main/resources/application.properties contains `auth.rate-limit.window-minutes=1` - - `mvn compile -q` exits 0 - - - - Bucket4j 7.6.0 is in pom.xml. AppConfig has getAuthRateLimitRequests() and getAuthRateLimitWindowMinutes(). application.properties has both properties with defaults. Project compiles. - - - - - Task 2: Implement RateLimitFilter and unit tests - - src/main/java/com/aflokkat/security/RateLimitFilter.java - src/test/java/com/aflokkat/security/RateLimitFilterTest.java - - - - - filter_passes_beforeThreshold: send 10 consecutive requests to /api/auth/login → all pass through (doFilter called 10 times, no 429) - - filter_returns429_afterThresholdExceeded: send 11 consecutive requests to /api/auth/login → first 10 pass, 11th request gets response status 429 - - - - - src/main/java/com/aflokkat/security/JwtAuthenticationFilter.java - - src/main/java/com/aflokkat/config/AppConfig.java - - - -**Step 1 — Write the failing tests first (RED):** - -Create `src/test/java/com/aflokkat/security/RateLimitFilterTest.java`: - -```java -package com.aflokkat.security; - -import org.junit.jupiter.api.BeforeEach; -import org.junit.jupiter.api.Test; -import org.mockito.MockedStatic; -import org.springframework.mock.web.MockFilterChain; -import org.springframework.mock.web.MockHttpServletRequest; -import org.springframework.mock.web.MockHttpServletResponse; - -import com.aflokkat.config.AppConfig; - -import static org.junit.jupiter.api.Assertions.assertEquals; -import static org.mockito.Mockito.mockStatic; - -class RateLimitFilterTest { - - private RateLimitFilter filter; - - @BeforeEach - void setUp() { - // Construct with a small threshold: 3 requests per minute for test speed - filter = new RateLimitFilter(3, 1); - } - - @Test - void filter_passes_beforeThreshold() throws Exception { - MockHttpServletRequest request = new MockHttpServletRequest("POST", "/api/auth/login"); - request.setRemoteAddr("192.168.1.1"); - - for (int i = 0; i < 3; i++) { - MockHttpServletResponse response = new MockHttpServletResponse(); - MockFilterChain chain = new MockFilterChain(); - filter.doFilterInternal(request, response, chain); - // Must not be 429 - assertEquals(200, response.getStatus(), - "Request " + (i + 1) + " should not be rate-limited"); - } - } - - @Test - void filter_returns429_afterThresholdExceeded() throws Exception { - MockHttpServletRequest request = new MockHttpServletRequest("POST", "/api/auth/login"); - request.setRemoteAddr("10.0.0.1"); - - // Drain the bucket (3 allowed) - for (int i = 0; i < 3; i++) { - MockHttpServletResponse response = new MockHttpServletResponse(); - filter.doFilterInternal(request, response, new MockFilterChain()); - } - - // 4th request must get 429 - MockHttpServletResponse response = new MockHttpServletResponse(); - filter.doFilterInternal(request, response, new MockFilterChain()); - assertEquals(429, response.getStatus(), "4th request should be rate-limited"); - } -} -``` - -Run: `mvn test -Dtest=RateLimitFilterTest -DfailIfNoTests=false -q` — should fail with compilation error (RateLimitFilter doesn't exist yet). That's expected RED. - -**Step 2 — Implement RateLimitFilter.java (GREEN):** - -Create `src/main/java/com/aflokkat/security/RateLimitFilter.java`: - -```java -package com.aflokkat.security; - -import com.bucket4j.Bandwidth; -import com.bucket4j.Bucket; -import com.bucket4j.Refill; -import com.aflokkat.config.AppConfig; - -import org.springframework.core.annotation.Order; -import org.springframework.stereotype.Component; -import org.springframework.web.filter.OncePerRequestFilter; - -import javax.servlet.FilterChain; -import javax.servlet.ServletException; -import javax.servlet.http.HttpServletRequest; -import javax.servlet.http.HttpServletResponse; -import java.io.IOException; -import java.time.Duration; -import java.util.Map; -import java.util.concurrent.ConcurrentHashMap; - -/** - * Per-IP rate limiting for /api/auth/** endpoints using Bucket4j token-bucket. - * - * Registered as a @Component — Spring Boot auto-registers it in the servlet filter chain. - * Do NOT also register via http.addFilterBefore() in SecurityConfig (would double-apply). - * - * Known limitation: buckets Map is unbounded. For academic scope this is acceptable. - * In production, replace ConcurrentHashMap with Guava CacheBuilder.expireAfterAccess(). - */ -@Component -@Order(1) -public class RateLimitFilter extends OncePerRequestFilter { - - private final Map buckets = new ConcurrentHashMap<>(); - private final int maxRequests; - private final int windowMinutes; - - /** - * Default constructor used by Spring — reads config from AppConfig. - */ - public RateLimitFilter() { - this(AppConfig.getAuthRateLimitRequests(), AppConfig.getAuthRateLimitWindowMinutes()); - } - - /** - * Test constructor — allows injecting threshold values directly without AppConfig. - */ - public RateLimitFilter(int maxRequests, int windowMinutes) { - this.maxRequests = maxRequests; - this.windowMinutes = windowMinutes; - } - - @Override - protected boolean shouldNotFilter(HttpServletRequest request) { - // Only apply to auth endpoints - return !request.getRequestURI().startsWith("/api/auth/"); - } - - @Override - protected void doFilterInternal(HttpServletRequest request, - HttpServletResponse response, - FilterChain chain) - throws ServletException, IOException { - - String ip = request.getRemoteAddr(); - Bucket bucket = buckets.computeIfAbsent(ip, k -> - Bucket.builder() - .addLimit(Bandwidth.classic( - maxRequests, - Refill.greedy(maxRequests, Duration.ofMinutes(windowMinutes)))) - .build()); - - if (bucket.tryConsume(1)) { - chain.doFilter(request, response); - } else { - response.setStatus(429); - response.setContentType("application/json"); - response.getWriter().write("{\"status\":\"error\",\"message\":\"Too many requests\"}"); - } - } -} -``` - -**Step 3 — Run GREEN check:** -```bash -mvn test -Dtest=RateLimitFilterTest -DfailIfNoTests=false -q -``` -Both tests must pass. - -**Step 4 — Full suite check (no regressions):** -```bash -mvn test -q -``` - - - - mvn test -Dtest=RateLimitFilterTest -DfailIfNoTests=false -q - - - - - src/main/java/com/aflokkat/security/RateLimitFilter.java exists - - File contains `@Component` - - File contains `@Order(1)` - - File contains `bucket.tryConsume` - - File contains `shouldNotFilter` - - File contains `response.setStatus(429)` - - File contains `RateLimitFilter(int maxRequests, int windowMinutes)` (test constructor) - - src/test/java/com/aflokkat/security/RateLimitFilterTest.java exists - - File contains `filter_passes_beforeThreshold` - - File contains `filter_returns429_afterThresholdExceeded` - - `mvn test -Dtest=RateLimitFilterTest -q` exits 0 (both tests pass) - - `mvn test -q` exits 0 (no regressions) - - - - RateLimitFilter is a @Component @Order(1) OncePerRequestFilter that rate-limits /api/auth/** by remote IP using Bucket4j 7.x token-bucket. It has a test constructor enabling unit tests without AppConfig. Both RateLimitFilterTest tests pass. Full suite is green. - - - - - - -```bash -mvn test -Dtest=RateLimitFilterTest -q -mvn test -q -``` -Both must exit 0. RateLimitFilter.java must contain @Component, bucket.tryConsume, response.setStatus(429). - - - -- `mvn test -Dtest=RateLimitFilterTest -q` exits 0 (2 tests pass) -- `mvn test -q` exits 0 (full suite green) -- `grep "bucket4j-core" pom.xml` returns a match -- `grep "7.6.0" pom.xml` returns a match -- `grep "@Component" src/main/java/com/aflokkat/security/RateLimitFilter.java` returns a match -- `grep "tryConsume" src/main/java/com/aflokkat/security/RateLimitFilter.java` returns a match - - - -After completion, create `.planning/phases/01-role-infrastructure/01-03-SUMMARY.md` - diff --git a/.planning/phases/01-role-infrastructure/01-03-SUMMARY.md b/.planning/phases/01-role-infrastructure/01-03-SUMMARY.md deleted file mode 100644 index 1740242..0000000 --- a/.planning/phases/01-role-infrastructure/01-03-SUMMARY.md +++ /dev/null @@ -1,126 +0,0 @@ ---- -phase: 01-role-infrastructure -plan: 03 -subsystem: auth -tags: [rate-limiting, bucket4j, servlet-filter, spring-security, brute-force-protection] - -# Dependency graph -requires: - - phase: 01-role-infrastructure - provides: AppConfig getters pattern for property/env-var resolution -provides: - - Per-IP rate limiting on /api/auth/** endpoints via Bucket4j 7.6.1 token-bucket - - RateLimitFilter @Component @Order(1) registered automatically before JWT filter - - Configurable threshold via auth.rate-limit.requests and auth.rate-limit.window-minutes -affects: [02-customer-features, 03-controller-features] - -# Tech tracking -tech-stack: - added: [bucket4j-core 7.6.1 (io.github.bucket4j)] - patterns: [OncePerRequestFilter with shouldNotFilter() scoping, ConcurrentHashMap per-IP bucket registry, test constructor for threshold injection] - -key-files: - created: - - src/main/java/com/aflokkat/security/RateLimitFilter.java - - src/test/java/com/aflokkat/security/RateLimitFilterTest.java - modified: - - pom.xml - - src/main/java/com/aflokkat/config/AppConfig.java - - src/main/resources/application.properties - -key-decisions: - - "Used Bucket4j 7.6.1 (not 8.x) — required for Java 11 compatibility; actual Maven package is io.github.bucket4j not com.bucket4j" - - "RateLimitFilter registered via @Component only — not also via http.addFilterBefore() — to avoid double-application" - - "@Order(1) ensures rate limiting runs before JwtAuthenticationFilter" - - "Test constructor RateLimitFilter(int, int) allows unit tests without AppConfig / property loading" - - "shouldNotFilter() returns true for all non-/api/auth/** paths — auth endpoints only" - -patterns-established: - - "Bucket4j token-bucket pattern: Bucket.builder().addLimit(Bandwidth.classic(n, Refill.greedy(n, Duration.ofMinutes(w))))" - - "Per-IP bucket registry: ConcurrentHashMap with computeIfAbsent" - - "HTTP 429 response: response.setStatus(429) + JSON body {status:error,message:Too many requests}" - -requirements-completed: [AUTH-04] - -# Metrics -duration: 15min -completed: 2026-03-27 ---- - -# Phase 1 Plan 03: Rate Limiting Summary - -**Per-IP Bucket4j 7.6.1 token-bucket rate limiter on /api/auth/** returning HTTP 429 after threshold exceeded** - -## Performance - -- **Duration:** ~15 min -- **Started:** 2026-03-27T13:55:00Z -- **Completed:** 2026-03-27T14:10:00Z -- **Tasks:** 2 -- **Files modified:** 5 - -## Accomplishments -- Bucket4j 7.6.1 dependency added to pom.xml with correct Maven groupId -- AppConfig extended with `getAuthRateLimitRequests()` and `getAuthRateLimitWindowMinutes()` getters -- `RateLimitFilter` implemented as `@Component @Order(1) OncePerRequestFilter` with per-IP bucket registry -- 2 unit tests proving threshold enforcement (passes at limit, 429 on exceed) - -## Task Commits - -Each task was committed atomically: - -1. **Task 1: Add bucket4j-core 7.6.0 to pom.xml and add AppConfig rate-limit getters** - `e520afa` (feat) -2. **Task 2 RED: Add failing tests for RateLimitFilter** - `c922dd2` (test) -3. **Task 2 GREEN: Implement RateLimitFilter** - `09df32b` (feat) - -## Files Created/Modified -- `src/main/java/com/aflokkat/security/RateLimitFilter.java` - Per-IP rate limiting filter for /api/auth/** endpoints -- `src/test/java/com/aflokkat/security/RateLimitFilterTest.java` - Unit tests for threshold enforcement (2 tests) -- `pom.xml` - Added bucket4j-core 7.6.1 dependency -- `src/main/java/com/aflokkat/config/AppConfig.java` - Added `getAuthRateLimitRequests()` and `getAuthRateLimitWindowMinutes()` -- `src/main/resources/application.properties` - Added `auth.rate-limit.requests=10` and `auth.rate-limit.window-minutes=1` - -## Decisions Made -- Bucket4j 7.6.1 used (not 7.6.0 which is absent from Maven Central); actual package is `io.github.bucket4j` not `com.bucket4j` as suggested in plan context -- RateLimitFilter registered via `@Component` only — not also via `http.addFilterBefore()` to avoid double-application (per plan anti-pattern note) -- Test constructor `RateLimitFilter(int maxRequests, int windowMinutes)` enables pure unit tests without Spring context or AppConfig loading - -## Deviations from Plan - -### Auto-fixed Issues - -**1. [Rule 1 - Bug] Corrected Bucket4j package path from com.bucket4j to io.github.bucket4j** -- **Found during:** Task 2 GREEN (RateLimitFilter compilation) -- **Issue:** Plan context specified `import com.bucket4j.Bandwidth/Bucket/Refill` but the actual package in Bucket4j 7.x jar is `io.github.bucket4j.*` -- **Fix:** Linter/compiler feedback revealed the correct package; imports corrected to `io.github.bucket4j.*` -- **Files modified:** src/main/java/com/aflokkat/security/RateLimitFilter.java -- **Verification:** `mvn test -Dtest=RateLimitFilterTest` exits 0, both tests pass -- **Committed in:** `09df32b` (Task 2 GREEN commit) - -**2. [Rule 1 - Bug] Bucket4j version 7.6.0 not available on Maven Central; used 7.6.1** -- **Found during:** Task 1 compile check -- **Issue:** `bucket4j-core:7.6.0` not resolvable from central; 7.6.1 is the correct available version -- **Fix:** Dependency version set to 7.6.1 (linter auto-corrected) -- **Files modified:** pom.xml -- **Verification:** `mvn compile -q` exits 0 -- **Committed in:** `e520afa` (Task 1 commit) - ---- - -**Total deviations:** 2 auto-fixed (both Rule 1 - Bug) -**Impact on plan:** Both fixes necessary for correctness. No scope creep. All must-haves and behavioral truths from plan frontmatter are satisfied. - -## Issues Encountered -- Full test suite (`mvn test -q`) has pre-existing failures from plans 01-01 and 01-02 (AuthServiceTest static mock setup, SecurityConfigTest StackOverflow, DataSeederTest assertion). These are out-of-scope for this plan and logged as deferred items. RateLimitFilterTest passes cleanly in isolation. - -## User Setup Required -None - no external service configuration required. - -## Next Phase Readiness -- Rate limiting is active on all /api/auth/** endpoints (register, login, refresh) -- Threshold defaults: 10 requests per minute per IP, configurable via env vars AUTH_RATE_LIMIT_REQUESTS / AUTH_RATE_LIMIT_WINDOW_MINUTES -- Phase 2 feature work can proceed; RateLimitFilter will automatically protect any new /api/auth/ routes added - ---- -*Phase: 01-role-infrastructure* -*Completed: 2026-03-27* diff --git a/.planning/phases/01-role-infrastructure/01-04-PLAN.md b/.planning/phases/01-role-infrastructure/01-04-PLAN.md deleted file mode 100644 index 0a25fb6..0000000 --- a/.planning/phases/01-role-infrastructure/01-04-PLAN.md +++ /dev/null @@ -1,325 +0,0 @@ ---- -phase: 01-role-infrastructure -plan: 04 -type: execute -wave: 1 -depends_on: [] -files_modified: - - src/main/java/com/aflokkat/startup/DataSeeder.java - - src/test/java/com/aflokkat/startup/DataSeederTest.java -autonomous: true -requirements: - - AUTH-05 - -must_haves: - truths: - - "On application startup, a user with username 'customer_test' exists in PostgreSQL with role ROLE_CUSTOMER" - - "On application startup, a user with username 'controller_test' exists in PostgreSQL with role ROLE_CONTROLLER" - - "Restarting the application does not create duplicate accounts (idempotent — skip if username already exists)" - - "Both seed accounts can log in via POST /api/auth/login with password 'Test1234!'" - artifacts: - - path: "src/main/java/com/aflokkat/startup/DataSeeder.java" - provides: "ApplicationRunner that seeds one CUSTOMER and one CONTROLLER account" - contains: "customer_test" - - path: "src/test/java/com/aflokkat/startup/DataSeederTest.java" - provides: "Unit tests for seeder idempotency and account creation" - contains: "run_createsCustomerAndController_whenAbsent" - key_links: - - from: "src/main/java/com/aflokkat/startup/DataSeeder.java" - to: "src/main/java/com/aflokkat/repository/UserRepository.java" - via: "userRepository.findByUsername(username).isPresent()" - pattern: "findByUsername" - - from: "src/main/java/com/aflokkat/startup/DataSeeder.java" - to: "src/main/java/com/aflokkat/entity/UserEntity.java" - via: "new UserEntity(username, email, hash, role)" - pattern: "new UserEntity" ---- - - -Create a DataSeeder ApplicationRunner component that seeds one CUSTOMER and one CONTROLLER test account on every startup, skipping creation if the account already exists. Write unit tests to verify creation and idempotency. - -Purpose: Developers and the test environment need ready-to-use accounts of each role immediately after docker compose up without any manual registration step. -Output: DataSeeder.java in new startup package, DataSeederTest.java with 2 unit tests. - - - -@/home/missia03/.claude/get-shit-done/workflows/execute-plan.md -@/home/missia03/.claude/get-shit-done/templates/summary.md - - - -@.planning/phases/01-role-infrastructure/01-CONTEXT.md - - - - -From src/main/java/com/aflokkat/repository/UserRepository.java: -```java -@Repository -public interface UserRepository extends JpaRepository { - Optional findByUsername(String username); - Optional findByEmail(String email); -} -``` - -From src/main/java/com/aflokkat/entity/UserEntity.java: -```java -public UserEntity(String username, String email, String passwordHash, String role) { - this.username = username; - this.email = email; - this.passwordHash = passwordHash; - this.role = role; - this.createdAt = new Date(); - this.updatedAt = new Date(); -} -// role is a plain String column — pass "ROLE_CUSTOMER" or "ROLE_CONTROLLER" -``` - -From src/main/java/com/aflokkat/config/SecurityConfig.java: -```java -@Bean -public PasswordEncoder passwordEncoder() { - return new BCryptPasswordEncoder(); -} -// The PasswordEncoder bean is registered in SecurityConfig. -// DataSeeder receives it via @Autowired PasswordEncoder passwordEncoder. -``` - -Seed credentials (hardcoded for academic scope — document in comments): -- customer_test / customer@test.com / Test1234! → ROLE_CUSTOMER -- controller_test / controller@test.com / Test1234! → ROLE_CONTROLLER - -Test style (from existing AuthServiceTest.java): -```java -@ExtendWith(MockitoExtension.class) -// Uses @Mock, @InjectMocks, when()/verify() from org.mockito -// JUnit 5 Jupiter: @Test from org.junit.jupiter.api.Test -``` - - - - - - - Task 1: Write DataSeederTest (RED) then implement DataSeeder (GREEN) - - src/main/java/com/aflokkat/startup/DataSeeder.java - src/test/java/com/aflokkat/startup/DataSeederTest.java - - - - - run_createsCustomerAndController_whenAbsent: when neither 'customer_test' nor 'controller_test' exist in the repository, calling run() causes userRepository.save() to be called twice — once for each account — with roles ROLE_CUSTOMER and ROLE_CONTROLLER respectively - - run_skipsExisting_whenAlreadySeeded: when both 'customer_test' and 'controller_test' already exist in the repository, calling run() causes userRepository.save() to be called zero times - - - - - src/test/java/com/aflokkat/service/AuthServiceTest.java - - src/main/java/com/aflokkat/repository/UserRepository.java - - - -**Step 1 — Write the 2 failing tests first (RED):** - -Create directory `src/test/java/com/aflokkat/startup/` and create `DataSeederTest.java`: - -```java -package com.aflokkat.startup; - -import static org.junit.jupiter.api.Assertions.assertEquals; -import static org.mockito.ArgumentMatchers.any; -import static org.mockito.ArgumentMatchers.argThat; -import static org.mockito.Mockito.never; -import static org.mockito.Mockito.times; -import static org.mockito.Mockito.verify; -import static org.mockito.Mockito.when; - -import java.util.Optional; - -import org.junit.jupiter.api.Test; -import org.junit.jupiter.api.extension.ExtendWith; -import org.mockito.ArgumentCaptor; -import org.mockito.InjectMocks; -import org.mockito.Mock; -import org.mockito.junit.jupiter.MockitoExtension; -import org.springframework.boot.ApplicationArguments; -import org.springframework.security.crypto.password.PasswordEncoder; - -import com.aflokkat.entity.UserEntity; -import com.aflokkat.repository.UserRepository; - -@ExtendWith(MockitoExtension.class) -class DataSeederTest { - - @Mock private UserRepository userRepository; - @Mock private PasswordEncoder passwordEncoder; - @Mock private ApplicationArguments args; - - @InjectMocks - private DataSeeder dataSeeder; - - @Test - void run_createsCustomerAndController_whenAbsent() throws Exception { - // Neither account exists yet - when(userRepository.findByUsername("customer_test")).thenReturn(Optional.empty()); - when(userRepository.findByUsername("controller_test")).thenReturn(Optional.empty()); - when(passwordEncoder.encode("Test1234!")).thenReturn("hashed"); - when(userRepository.save(any(UserEntity.class))).thenAnswer(inv -> inv.getArgument(0)); - - dataSeeder.run(args); - - // save() must be called twice - ArgumentCaptor captor = ArgumentCaptor.forClass(UserEntity.class); - verify(userRepository, times(2)).save(captor.capture()); - - // First saved entity: ROLE_CUSTOMER - UserEntity customer = captor.getAllValues().get(0); - assertEquals("customer_test", customer.getUsername()); - assertEquals("ROLE_CUSTOMER", customer.getRole()); - - // Second saved entity: ROLE_CONTROLLER - UserEntity controller = captor.getAllValues().get(1); - assertEquals("controller_test", controller.getUsername()); - assertEquals("ROLE_CONTROLLER", controller.getRole()); - } - - @Test - void run_skipsExisting_whenAlreadySeeded() throws Exception { - // Both accounts already exist - when(userRepository.findByUsername("customer_test")) - .thenReturn(Optional.of(new UserEntity("customer_test", "customer@test.com", "hash", "ROLE_CUSTOMER"))); - when(userRepository.findByUsername("controller_test")) - .thenReturn(Optional.of(new UserEntity("controller_test", "controller@test.com", "hash", "ROLE_CONTROLLER"))); - - dataSeeder.run(args); - - // save() must never be called - verify(userRepository, never()).save(any()); - } -} -``` - -Run: `mvn test -Dtest=DataSeederTest -DfailIfNoTests=false -q` — should fail with compilation error (DataSeeder doesn't exist yet). Expected RED. - -**Step 2 — Implement DataSeeder.java (GREEN):** - -Create directory `src/main/java/com/aflokkat/startup/` if it does not exist. Create `DataSeeder.java`: - -```java -package com.aflokkat.startup; - -import org.slf4j.Logger; -import org.slf4j.LoggerFactory; -import org.springframework.beans.factory.annotation.Autowired; -import org.springframework.boot.ApplicationArguments; -import org.springframework.boot.ApplicationRunner; -import org.springframework.security.crypto.password.PasswordEncoder; -import org.springframework.stereotype.Component; - -import com.aflokkat.entity.UserEntity; -import com.aflokkat.repository.UserRepository; - -/** - * Seeds one CUSTOMER and one CONTROLLER test account on every application startup. - * Skips creation if the account already exists (idempotent — safe to run on restarts). - * - * Seed credentials (for development and testing only): - * customer_test / Test1234! → ROLE_CUSTOMER - * controller_test / Test1234! → ROLE_CONTROLLER - * - * Note: These credentials are hardcoded for academic scope. In production, - * use environment variables (e.g., SEED_CUSTOMER_PASSWORD). - * - * Docker note: existing rows with role=ROLE_USER (from before Phase 1) will remain - * but will be unable to access protected endpoints. Run `docker compose down -v` - * followed by `docker compose up -d` to reset the PostgreSQL volume during development. - */ -@Component -public class DataSeeder implements ApplicationRunner { - - private static final Logger log = LoggerFactory.getLogger(DataSeeder.class); - - private static final String SEED_PASSWORD = "Test1234!"; - - @Autowired - private UserRepository userRepository; - - @Autowired - private PasswordEncoder passwordEncoder; - - @Override - public void run(ApplicationArguments args) { - seedUser("customer_test", "customer@test.com", "ROLE_CUSTOMER"); - seedUser("controller_test", "controller@test.com", "ROLE_CONTROLLER"); - } - - private void seedUser(String username, String email, String role) { - if (userRepository.findByUsername(username).isPresent()) { - log.debug("Seed account already exists, skipping: {}", username); - return; - } - String hash = passwordEncoder.encode(SEED_PASSWORD); - userRepository.save(new UserEntity(username, email, hash, role)); - log.info("Seeded test account: {} ({})", username, role); - } -} -``` - -**Step 3 — Run GREEN check:** -```bash -mvn test -Dtest=DataSeederTest -DfailIfNoTests=false -q -``` -Both tests must pass. - -**Step 4 — Full suite check:** -```bash -mvn test -q -``` - - - - mvn test -Dtest=DataSeederTest -DfailIfNoTests=false -q - - - - - src/main/java/com/aflokkat/startup/DataSeeder.java exists - - File contains `@Component` - - File contains `implements ApplicationRunner` - - File contains `customer_test` - - File contains `controller_test` - - File contains `ROLE_CUSTOMER` - - File contains `ROLE_CONTROLLER` - - File contains `findByUsername(username).isPresent()` (idempotency check) - - src/test/java/com/aflokkat/startup/DataSeederTest.java exists - - File contains `run_createsCustomerAndController_whenAbsent` - - File contains `run_skipsExisting_whenAlreadySeeded` - - `mvn test -Dtest=DataSeederTest -q` exits 0 (both tests pass) - - `mvn test -q` exits 0 (no regressions) - - - - DataSeeder is a @Component ApplicationRunner that creates customer_test (ROLE_CUSTOMER) and controller_test (ROLE_CONTROLLER) if they do not exist. Uses BCrypt via the existing PasswordEncoder bean. Idempotent — re-runs are safe. Both DataSeederTest unit tests pass. Full suite is green. - - - - - - -```bash -mvn test -Dtest=DataSeederTest -q -mvn test -q -``` -Both must exit 0. DataSeeder.java must contain @Component, implements ApplicationRunner, customer_test, controller_test. - - - -- `mvn test -Dtest=DataSeederTest -q` exits 0 (2 tests pass) -- `mvn test -q` exits 0 (full suite green) -- `grep "@Component" src/main/java/com/aflokkat/startup/DataSeeder.java` returns a match -- `grep "implements ApplicationRunner" src/main/java/com/aflokkat/startup/DataSeeder.java` returns a match -- `grep "customer_test" src/main/java/com/aflokkat/startup/DataSeeder.java` returns a match -- `grep "ROLE_CUSTOMER\|ROLE_CONTROLLER" src/main/java/com/aflokkat/startup/DataSeeder.java` returns matches - - - -After completion, create `.planning/phases/01-role-infrastructure/01-04-SUMMARY.md` - diff --git a/.planning/phases/01-role-infrastructure/01-04-SUMMARY.md b/.planning/phases/01-role-infrastructure/01-04-SUMMARY.md deleted file mode 100644 index 0f151e7..0000000 --- a/.planning/phases/01-role-infrastructure/01-04-SUMMARY.md +++ /dev/null @@ -1,104 +0,0 @@ ---- -phase: 01-role-infrastructure -plan: "04" -subsystem: auth -tags: [spring-boot, postgresql, jpa, applicationrunner, seeding, test-data] - -# Dependency graph -requires: - - phase: 01-role-infrastructure - provides: UserEntity constructor with role field, UserRepository with findByUsername, PasswordEncoder bean in SecurityConfig -provides: - - DataSeeder @Component ApplicationRunner that idempotently seeds customer_test (ROLE_CUSTOMER) and controller_test (ROLE_CONTROLLER) on startup - - Unit tests verifying creation-when-absent and skip-when-present behaviour -affects: - - All phases requiring a ready-to-use test account without manual registration - - Integration tests that depend on known seed credentials - -# Tech tracking -tech-stack: - added: [] - patterns: - - ApplicationRunner for startup side-effects (seed/migration) - - Idempotent seeding via findByUsername guard before save - -key-files: - created: - - src/main/java/com/aflokkat/startup/DataSeeder.java - - src/test/java/com/aflokkat/startup/DataSeederTest.java - modified: [] - -key-decisions: - - "Constructor injection chosen over @Autowired field injection for DataSeeder (testability, immutability)" - - "Hardcoded seed password accepted for academic scope; comment documents the production alternative (env var)" - - "DataSeeder logs at INFO on creation, DEBUG on skip to avoid noise on restarts" - -patterns-established: - - "Idempotent seed: always check repository.findByUsername().isPresent() before save()" - - "Startup components go in com.aflokkat.startup package, implement ApplicationRunner" - -requirements-completed: [AUTH-05] - -# Metrics -duration: 2min -completed: 2026-03-29 ---- - -# Phase 1 Plan 4: DataSeeder Summary - -**Idempotent ApplicationRunner that seeds customer_test (ROLE_CUSTOMER) and controller_test (ROLE_CONTROLLER) into PostgreSQL on every startup, backed by 2 Mockito unit tests** - -## Performance - -- **Duration:** ~2 min -- **Started:** 2026-03-29T16:39:28Z -- **Completed:** 2026-03-29T16:40:51Z -- **Tasks:** 1 (TDD: RED already present, GREEN verified) -- **Files modified:** 2 - -## Accomplishments - -- DataSeeder @Component implements ApplicationRunner, seeding two fixed test accounts on startup -- Idempotency guard: findByUsername().isPresent() check prevents duplicate rows on restarts -- Two unit tests pass: run_createsCustomerAndController_whenAbsent and run_skipsExisting_whenAlreadySeeded - -## Task Commits - -Each task was committed atomically: - -1. **Task 1: DataSeeder + DataSeederTest (TDD GREEN)** - `ff32e22` (feat) - -**Plan metadata:** (docs commit — see below) - -## Files Created/Modified - -- `src/main/java/com/aflokkat/startup/DataSeeder.java` - ApplicationRunner that seeds customer_test and controller_test; idempotent -- `src/test/java/com/aflokkat/startup/DataSeederTest.java` - 2 Mockito unit tests for creation and idempotency - -## Decisions Made - -- Constructor injection chosen over @Autowired field injection — DataSeeder already existed with constructor injection, which is better practice and works seamlessly with @InjectMocks in tests -- Seed password hardcoded as `SEED_PASSWORD` constant with a comment documenting the production alternative -- Logging strategy: INFO on first seed, DEBUG on skip (avoids noise on subsequent restarts) - -## Deviations from Plan - -None - plan executed exactly as written. Both files were already present as untracked work matching the plan spec exactly. Tests verified passing before commit. - -## Issues Encountered - -Pre-existing failures in AuthServiceTest (5 tests requiring mockito-inline for MockedStatic) and SecurityConfigTest (3 StackOverflow errors) are out-of-scope and pre-date this plan. They are documented in deferred-items.md if not already tracked. - -## User Setup Required - -None - no external service configuration required. - -## Next Phase Readiness - -- Seed accounts are available immediately after `docker compose up -d` — no manual registration needed -- Both accounts use password `Test1234!` and can log in via `POST /api/auth/login` -- Ready for Phase 2 feature work requiring role-specific endpoints - ---- -*Phase: 01-role-infrastructure* -*Completed: 2026-03-29* diff --git a/.planning/phases/01-role-infrastructure/01-CONTEXT.md b/.planning/phases/01-role-infrastructure/01-CONTEXT.md deleted file mode 100644 index bbc28be..0000000 --- a/.planning/phases/01-role-infrastructure/01-CONTEXT.md +++ /dev/null @@ -1,110 +0,0 @@ -# Phase 1: Role Infrastructure - Context - -**Gathered:** 2026-03-27 -**Status:** Ready for planning - - -## Phase Boundary - -Extend JWT authentication and Spring Security to support two roles (CUSTOMER / CONTROLLER), implement URL-level access guards, add rate limiting on auth endpoints, and seed one test account of each role on startup. No UI work in this phase — pure backend API and security layer. - - - - -## Implementation Decisions - -### Registration flow -- Single endpoint: `POST /api/auth/register` with optional `signupCode` field in the request body -- No `signupCode` provided → user becomes `ROLE_CUSTOMER` -- Correct `signupCode` (matches env var) → user becomes `ROLE_CONTROLLER` -- Wrong `signupCode` → HTTP 400 with generic message `"Invalid registration request"` (do not reveal the code system exists) -- Env var name: `CONTROLLER_SIGNUP_CODE` (consistent with existing ALL_CAPS pattern in AppConfig) -- If `CONTROLLER_SIGNUP_CODE` env var is not set → controller registration is disabled; any attempt returns 400 (fail-safe) - -### URL security scope -- `/api/auth/**` → fully public (login, register, refresh) -- `/api/restaurants/**` → fully public (read-only NYC data, no reason to gate) -- `/api/inspections/**` → fully public (read-only NYC data) -- `/api/users/**` → require valid JWT (any role); unauthenticated → 401 -- `/api/reports/**` → require `ROLE_CONTROLLER`; unauthenticated → 401, valid CUSTOMER JWT → 403 -- Swagger (`/swagger-ui.html`, `/api-docs/**`, `/v3/api-docs/**`) → fully public -- View routes (non-`/api/**`) → left fully open for now (view-level auth is Phase 3 scope) - -### Access denied responses -- Unauthenticated requests to protected endpoints → 401 with JSON body (already handled by existing authenticationEntryPoint in SecurityConfig for `/api/**`) -- Authenticated but wrong role → 403 (handled by Spring Security's default AccessDeniedException handler — add an accessDeniedHandler returning JSON 403) - -### Role values -- Store `ROLE_CUSTOMER` / `ROLE_CONTROLLER` in `UserEntity.role` (replaces current `ROLE_USER`) -- Use `hasRole("CUSTOMER")` / `hasRole("CONTROLLER")` in security rules — Spring strips the prefix internally - -### Claude's Discretion -- Rate limiting implementation (Bucket4j or custom Servlet filter) and threshold config placement -- Seed account credentials and idempotency behavior (skip if already exists is the safe default) -- Exact Hibernate migration for the role column value change - - - - -## Canonical References - -**Downstream agents MUST read these before planning or implementing.** - -### Requirements -- `.planning/REQUIREMENTS.md` — AUTH-01 through AUTH-05 (all Phase 1 requirements) -- `.planning/ROADMAP.md` — Phase 1 goal, success criteria, and dependency notes - -### Existing security layer (must read before modifying) -- `src/main/java/com/aflokkat/config/SecurityConfig.java` — current `anyRequest().permitAll()` to replace; existing authenticationEntryPoint, JWT filter wiring -- `src/main/java/com/aflokkat/security/JwtAuthenticationFilter.java` — extracts role claim as `SimpleGrantedAuthority(role)`; already supports ROLE_* values -- `src/main/java/com/aflokkat/security/JwtUtil.java` — `generateAccessToken(username, role)` — token already carries role claim - -### Auth layer (must read before modifying) -- `src/main/java/com/aflokkat/service/AuthService.java` — `register()` hardcodes `"ROLE_USER"`; needs signup code logic -- `src/main/java/com/aflokkat/dto/RegisterRequest.java` — needs `signupCode` field added -- `src/main/java/com/aflokkat/controller/AuthController.java` — `POST /api/auth/register` endpoint -- `src/main/java/com/aflokkat/entity/UserEntity.java` — role field already exists as String column - -### Config pattern -- `src/main/java/com/aflokkat/config/AppConfig.java` — env var resolution pattern (`System.getenv(key.replace(".", "_").toUpperCase())`) — follow this pattern for `CONTROLLER_SIGNUP_CODE` - - - - -## Existing Code Insights - -### Reusable Assets -- `UserEntity.role` (String column): already exists — just change the stored values from `ROLE_USER` to `ROLE_CUSTOMER` / `ROLE_CONTROLLER` -- `JwtAuthenticationFilter`: already creates `SimpleGrantedAuthority(role)` from the JWT claim — no changes needed to the filter itself -- `AppConfig.getProperty()`: env var → .env → application.properties fallback chain — reuse this pattern for `CONTROLLER_SIGNUP_CODE` -- `@EnableMethodSecurity` on SecurityConfig: `@PreAuthorize("hasRole('CONTROLLER')")` is available for method-level guards if needed - -### Established Patterns -- Error responses: anonymous `Object` with `status` + `message` fields (see `AuthController.errorResponse()`) — keep same shape for auth errors -- Config keys: ALL_CAPS env var names derived from dot-notation property names (e.g., `redis.host` → `REDIS_HOST`) - -### Integration Points -- `SecurityConfig.filterChain()`: replace `anyRequest().permitAll()` with explicit `antMatchers` — this is the single change point for URL-level guards -- `AuthService.register()`: add signup code check before role assignment -- `Application.java`: add a `CommandLineRunner` or `ApplicationRunner` bean for seeding (or a separate `DataSeeder` @Component) - - - - -## Specific Ideas - -- No specific references — open to standard Spring Security antMatcher patterns and Bucket4j for rate limiting - - - - -## Deferred Ideas - -- None — discussion stayed within phase scope - - - ---- - -*Phase: 01-role-infrastructure* -*Context gathered: 2026-03-27* diff --git a/.planning/phases/01-role-infrastructure/01-RESEARCH.md b/.planning/phases/01-role-infrastructure/01-RESEARCH.md deleted file mode 100644 index 3f7f70f..0000000 --- a/.planning/phases/01-role-infrastructure/01-RESEARCH.md +++ /dev/null @@ -1,499 +0,0 @@ -# Phase 1: Role Infrastructure - Research - -**Researched:** 2026-03-27 -**Domain:** Spring Security role-based access control, JWT role claims, Servlet rate limiting, application seeding -**Confidence:** HIGH - ---- - - -## User Constraints (from CONTEXT.md) - -### Locked Decisions - -**Registration flow** -- Single endpoint: `POST /api/auth/register` with optional `signupCode` field in the request body -- No `signupCode` provided → user becomes `ROLE_CUSTOMER` -- Correct `signupCode` (matches env var) → user becomes `ROLE_CONTROLLER` -- Wrong `signupCode` → HTTP 400 with generic message `"Invalid registration request"` (do not reveal the code system exists) -- Env var name: `CONTROLLER_SIGNUP_CODE` (consistent with existing ALL_CAPS pattern in AppConfig) -- If `CONTROLLER_SIGNUP_CODE` env var is not set → controller registration is disabled; any attempt returns 400 (fail-safe) - -**URL security scope** -- `/api/auth/**` → fully public (login, register, refresh) -- `/api/restaurants/**` → fully public (read-only NYC data, no reason to gate) -- `/api/inspections/**` → fully public (read-only NYC data) -- `/api/users/**` → require valid JWT (any role); unauthenticated → 401 -- `/api/reports/**` → require `ROLE_CONTROLLER`; unauthenticated → 401, valid CUSTOMER JWT → 403 -- Swagger (`/swagger-ui.html`, `/api-docs/**`, `/v3/api-docs/**`) → fully public -- View routes (non-`/api/**`) → left fully open for now (view-level auth is Phase 3 scope) - -**Access denied responses** -- Unauthenticated requests to protected endpoints → 401 with JSON body (already handled by existing `authenticationEntryPoint` in `SecurityConfig` for `/api/**`) -- Authenticated but wrong role → 403 (handled by Spring Security's default `AccessDeniedException` handler — add an `accessDeniedHandler` returning JSON 403) - -**Role values** -- Store `ROLE_CUSTOMER` / `ROLE_CONTROLLER` in `UserEntity.role` (replaces current `ROLE_USER`) -- Use `hasRole("CUSTOMER")` / `hasRole("CONTROLLER")` in security rules — Spring strips the prefix internally - -### Claude's Discretion -- Rate limiting implementation (Bucket4j or custom Servlet filter) and threshold config placement -- Seed account credentials and idempotency behavior (skip if already exists is the safe default) -- Exact Hibernate migration for the role column value change - -### Deferred Ideas (OUT OF SCOPE) -- None — discussion stayed within phase scope - - ---- - - -## Phase Requirements - -| ID | Description | Research Support | -|----|-------------|-----------------| -| AUTH-01 | User account has a CUSTOMER or CONTROLLER role stored in PostgreSQL | `UserEntity.role` column already exists as a String; change stored values from `ROLE_USER` to `ROLE_CUSTOMER` / `ROLE_CONTROLLER`; `spring.jpa.hibernate.ddl-auto=update` will accept new values without migration | -| AUTH-02 | Controller can register via a dedicated endpoint using a shared signup code | Extend `RegisterRequest` with optional `signupCode`; add validation logic in `AuthService.register()` reading `CONTROLLER_SIGNUP_CODE` via `AppConfig.getProperty()` pattern | -| AUTH-03 | URL-level security guards block CONTROLLER endpoints from unauthenticated or CUSTOMER access | Replace `anyRequest().permitAll()` with explicit `antMatchers` in `SecurityConfig.filterChain()`; add `accessDeniedHandler` for 403 JSON; `JwtAuthenticationFilter` already populates `SecurityContext` with `SimpleGrantedAuthority(role)` — no filter changes needed | -| AUTH-04 | Auth endpoints (login/register) have rate limiting to prevent brute-force attacks | Add Bucket4j `OncePerRequestFilter` (or a `HandlerInterceptor`) applied only to `/api/auth/**`; configure threshold via `AppConfig` pattern; return HTTP 429 with JSON body | -| AUTH-05 | One CUSTOMER and one CONTROLLER test account are seeded automatically on application startup | Add a `@Component DataSeeder implements ApplicationRunner`; check existence via `UserRepository.findByUsername()` before saving; BCrypt-encode passwords with the existing `PasswordEncoder` bean | - - ---- - -## Summary - -Phase 1 is a targeted security hardening exercise on an existing Spring Boot 2.6.15 / Spring Security 5 application. The JWT infrastructure (token generation, claim extraction, filter wiring) is already correct and does not need changes. The two main structural changes are: (1) replacing the blanket `anyRequest().permitAll()` with fine-grained `antMatchers`, and (2) adding signup-code logic and role assignment to `AuthService.register()`. Two new components need to be created from scratch: a rate-limiting filter for auth endpoints and a startup data seeder. - -Because Hibernate DDL auto is set to `update`, the `role` column value change from `ROLE_USER` to `ROLE_CUSTOMER`/`ROLE_CONTROLLER` requires no schema migration — only the application code that writes the value needs updating. Any existing rows with `ROLE_USER` will remain; seeds use idempotent `findByUsername` checks so re-starts are safe. - -Rate limiting is the only area with genuine implementation choice (Bucket4j library vs. hand-rolled map). Bucket4j integrates with Spring Boot without framework coupling, supports per-key (per-IP) buckets, and is the mature library choice for this stack. - -**Primary recommendation:** Follow the exact change map below — minimum-footprint modifications to existing files plus two new small classes (`RateLimitFilter`, `DataSeeder`). - ---- - -## Standard Stack - -### Core (already in pom.xml — no additions needed for AUTH-01/02/03/05) -| Library | Version | Purpose | Why Standard | -|---------|---------|---------|--------------| -| spring-boot-starter-security | managed by 2.6.15 BOM (~5.6.x) | `SecurityFilterChain`, `antMatchers`, access denied handler | Already present | -| jjwt-api / jjwt-impl / jjwt-jackson | 0.11.5 | JWT generation and validation | Already present | -| spring-boot-starter-data-jpa | managed | `UserRepository` (PostgreSQL / Hibernate) | Already present | - -### New Dependency (AUTH-04 only) -| Library | Version | Purpose | Why | -|---------|---------|---------|-----| -| bucket4j-core | 7.6.0 | In-process token-bucket rate limiting | No extra infra, thread-safe, battle-tested, clean Spring filter integration; Spring Boot 2.6 compatible | - -**Installation (add to pom.xml):** -```xml - - com.bucket4j - bucket4j-core - 7.6.0 - -``` - -Note: Bucket4j 8.x requires Java 17. Use **7.6.0** for Java 11 compatibility. - -### Alternatives Considered -| Instead of | Could Use | Tradeoff | -|------------|-----------|----------| -| Bucket4j | Hand-rolled `ConcurrentHashMap` | Custom map lacks time-window reset and per-key expiry; acceptable for POC but misses burst semantics | -| Bucket4j | Spring `HandlerInterceptor` + custom logic | Same as above — still need a bucket library for correct token-bucket math | -| Bucket4j | Redis-backed rate limiter | Overkill for single-node academic app; adds Redis coupling to auth path | - ---- - -## Architecture Patterns - -### Recommended Project Structure Changes -``` -com.aflokkat/ -├── config/ -│ ├── SecurityConfig.java # MODIFY: antMatchers + accessDeniedHandler -│ └── AppConfig.java # MODIFY: add getControllerSignupCode() -├── service/ -│ └── AuthService.java # MODIFY: signup code logic + role assignment -├── dto/ -│ └── RegisterRequest.java # MODIFY: add signupCode field -├── security/ -│ ├── JwtAuthenticationFilter.java # NO CHANGE -│ ├── JwtUtil.java # NO CHANGE -│ └── RateLimitFilter.java # NEW: Bucket4j OncePerRequestFilter -└── startup/ - └── DataSeeder.java # NEW: ApplicationRunner seed component -``` - -### Pattern 1: antMatchers URL Security (Spring Security 5 style) -**What:** Replaces the single `anyRequest().permitAll()` with ordered `antMatchers` rules. -**When to use:** Spring Security 5 on Spring Boot 2.6 — this is `HttpSecurity.authorizeRequests()` API (not the newer `authorizeHttpRequests()` from Spring Security 6). - -```java -// In SecurityConfig.filterChain() — replace .anyRequest().permitAll() block -http - .authorizeRequests() - // Public - .antMatchers("/api/auth/**").permitAll() - .antMatchers("/api/restaurants/**").permitAll() - .antMatchers("/api/inspections/**").permitAll() - .antMatchers("/swagger-ui.html", "/api-docs/**", "/v3/api-docs/**", - "/swagger-ui/**", "/webjars/**").permitAll() - // Controllers only - .antMatchers("/api/reports/**").hasRole("CONTROLLER") - // Any valid JWT - .antMatchers("/api/users/**").authenticated() - // Non-API views: open for now - .anyRequest().permitAll() -``` - -**Critical ordering:** more specific rules must come before `.anyRequest()`. Spring Security evaluates top-down and stops at first match. - -### Pattern 2: Access Denied Handler (403 JSON) -**What:** `AccessDeniedHandler` writes a JSON 403 response when an authenticated user lacks the required role. - -```java -// Inside filterChain(), in the .exceptionHandling() block -.accessDeniedHandler((request, response, accessDeniedException) -> { - response.setStatus(HttpServletResponse.SC_FORBIDDEN); - response.setContentType("application/json"); - response.getWriter().write("{\"status\":\"error\",\"message\":\"Forbidden\"}"); -}) -``` - -This pairs with the existing `authenticationEntryPoint` (401) already in `SecurityConfig`. - -### Pattern 3: Signup Code Check in AuthService -**What:** Read `CONTROLLER_SIGNUP_CODE` env var; determine role before persisting. - -```java -// In AuthService.register() — before userRepository.save() -String signupCode = AppConfig.getControllerSignupCode(); // returns null if env var absent -String providedCode = request.getSignupCode(); // null if field absent from request - -String role; -if (providedCode == null || providedCode.isEmpty()) { - role = "ROLE_CUSTOMER"; -} else { - // Controller signup disabled when env var is not set - if (signupCode == null || signupCode.isEmpty()) { - throw new IllegalArgumentException("Invalid registration request"); - } - if (!signupCode.equals(providedCode)) { - throw new IllegalArgumentException("Invalid registration request"); - } - role = "ROLE_CONTROLLER"; -} -UserEntity userEntity = new UserEntity(request.getUsername(), request.getEmail(), hash, role); -``` - -### Pattern 4: Bucket4j Rate Limiting Filter -**What:** `OncePerRequestFilter` that rate-limits `/api/auth/**` by client IP using a per-IP `Bucket`. - -```java -// RateLimitFilter.java (sketch) -@Component -@Order(1) -public class RateLimitFilter extends OncePerRequestFilter { - - // e.g. 10 requests per minute per IP - private final Map buckets = new ConcurrentHashMap<>(); - private final int maxRequests = AppConfig.getAuthRateLimitRequests(); // new AppConfig key - private final Duration window = Duration.ofMinutes( - AppConfig.getAuthRateLimitWindowMinutes()); - - @Override - protected boolean shouldNotFilter(HttpServletRequest request) { - return !request.getRequestURI().startsWith("/api/auth/"); - } - - @Override - protected void doFilterInternal(HttpServletRequest request, - HttpServletResponse response, FilterChain chain) - throws ServletException, IOException { - - String ip = request.getRemoteAddr(); - Bucket bucket = buckets.computeIfAbsent(ip, k -> - Bucket.builder() - .addLimit(Bandwidth.classic(maxRequests, - Refill.greedy(maxRequests, window))) - .build()); - - if (bucket.tryConsume(1)) { - chain.doFilter(request, response); - } else { - response.setStatus(429); - response.setContentType("application/json"); - response.getWriter().write("{\"status\":\"error\",\"message\":\"Too many requests\"}"); - } - } -} -``` - -**Config keys to add to `application.properties` and `AppConfig`:** -```properties -auth.rate-limit.requests=10 -auth.rate-limit.window-minutes=1 -``` -Env var equivalents: `AUTH_RATE_LIMIT_REQUESTS`, `AUTH_RATE_LIMIT_WINDOW_MINUTES`. - -### Pattern 5: DataSeeder (ApplicationRunner) -**What:** Runs after Spring context is fully started; creates seed accounts if absent. - -```java -// DataSeeder.java -@Component -public class DataSeeder implements ApplicationRunner { - - @Autowired private UserRepository userRepository; - @Autowired private PasswordEncoder passwordEncoder; - - @Override - public void run(ApplicationArguments args) { - seedUser("customer_test", "customer@test.com", "ROLE_CUSTOMER"); - seedUser("controller_test", "controller@test.com", "ROLE_CONTROLLER"); - } - - private void seedUser(String username, String email, String role) { - if (userRepository.findByUsername(username).isPresent()) { - return; // idempotent - } - String hash = passwordEncoder.encode("Test1234!"); - userRepository.save(new UserEntity(username, email, hash, role)); - } -} -``` - -Seed credentials should either be hardcoded to a well-known test value or configurable via env vars. For academic scope, hardcoded test credentials are acceptable. Password `Test1234!` is used here as a placeholder — planner should define final values. - -### Anti-Patterns to Avoid -- **`anyRequest().authenticated()` as catch-all:** This breaks view routes and health endpoints. End the chain with `anyRequest().permitAll()` and rely on explicit path rules for locked-down sections. -- **`@PreAuthorize` on controller methods instead of `antMatchers`:** Both are available (`@EnableMethodSecurity` is already present), but URL-level guards are the primary lock. Method security is a complementary secondary layer, not the primary one. -- **Modifying `JwtAuthenticationFilter`:** The filter already creates `SimpleGrantedAuthority(role)` correctly. The `ROLE_` prefix in stored values maps directly to Spring's `hasRole("CUSTOMER")` check (Spring prepends `ROLE_` internally). No filter changes needed. -- **Bucket4j 8.x on Java 11:** Bucket4j 8.x requires Java 17. Use 7.6.0. -- **Registering `RateLimitFilter` as a Spring Security filter via `addFilterBefore`:** Because this filter is already a Spring `@Component`, Spring Boot auto-registers it in the servlet filter chain. Do NOT also add it via `http.addFilterBefore()` — that would apply it twice. - ---- - -## Don't Hand-Roll - -| Problem | Don't Build | Use Instead | Why | -|---------|-------------|-------------|-----| -| Token-bucket rate limiting | `Map` with manual window expiry | Bucket4j | Correct burst semantics, thread-safe, handles concurrent requests without race conditions | -| Role checking in controllers | Manual `SecurityContextHolder.getContext().getAuthentication()` role checks | Spring Security `antMatchers` + `hasRole()` | Framework handles edge cases (null auth, expired token, etc.) | -| Password hashing | Custom hash function | `BCryptPasswordEncoder` (already wired) | Already present; BCrypt handles salting, cost factor | - -**Key insight:** In this phase every new capability maps to a Spring Security configuration primitive or a small class. The framework handles the heavy lifting; the work is wiring, not building. - ---- - -## Common Pitfalls - -### Pitfall 1: `antMatchers` order matters -**What goes wrong:** Placing `.anyRequest().permitAll()` before `.antMatchers("/api/reports/**").hasRole(...)` makes the controller-only rule unreachable. -**Why it happens:** Spring Security evaluates rules top-to-bottom and stops at first match. -**How to avoid:** Always put specific path rules first, `.anyRequest()` last. -**Warning signs:** 403 never returned for `/api/reports/**` regardless of token. - -### Pitfall 2: Double filter registration -**What goes wrong:** `RateLimitFilter` is applied twice — once by Spring Boot's auto-registration of `@Component` filters, once by `http.addFilterBefore()` in `SecurityConfig`. -**Why it happens:** Spring Boot automatically registers any `@Component` that extends `GenericFilterBean` or `OncePerRequestFilter`. -**How to avoid:** Either annotate with `@Component` and do NOT call `http.addFilterBefore()`, OR do NOT annotate and register only via `http.addFilterBefore()`. Choose one. -**Warning signs:** Rate limit halved (two tokens consumed per request), or filter appears twice in debug logs. - -### Pitfall 3: `hasRole()` vs `hasAuthority()` mismatch -**What goes wrong:** Storing `ROLE_CONTROLLER` but calling `hasAuthority("ROLE_CONTROLLER")` works; but mixing `hasRole("CONTROLLER")` with `hasAuthority("CONTROLLER")` (no prefix) fails silently. -**Why it happens:** `hasRole("X")` auto-prepends `ROLE_` internally. `hasAuthority("X")` matches exactly. -**How to avoid:** Decide once: store `ROLE_CONTROLLER`, use `hasRole("CONTROLLER")` everywhere. This is the locked decision. -**Warning signs:** Access granted or denied inconsistently across different endpoints. - -### Pitfall 4: Seeder runs before schema is ready -**What goes wrong:** `DataSeeder` (implementing `ApplicationRunner`) runs after the Spring context starts, but if PostgreSQL is not yet healthy, it throws a connection error. -**Why it happens:** `ApplicationRunner` runs after full context initialization, which should be fine — but only when the DB health check in Docker Compose has already passed. -**How to avoid:** Docker Compose `depends_on` with `condition: service_healthy` on `postgres` is already configured. Add a `@Transactional` or a try/catch with a warning log to handle edge cases gracefully. - -### Pitfall 5: Existing `ROLE_USER` rows in the database -**What goes wrong:** Any user registered before Phase 1 ships has `role = 'ROLE_USER'`, which does not match either `ROLE_CUSTOMER` or `ROLE_CONTROLLER`. Their JWT will be valid but they will be blocked from all protected resources. -**Why it happens:** The role column is a plain string; Hibernate `ddl-auto=update` does not migrate data. -**How to avoid:** This is an academic project with ephemeral Docker volumes. The solution is `docker compose down -v` + `docker compose up -d` to reset data during development. No Flyway/Liquibase migration needed. Document this in the plan. - -### Pitfall 6: Bucket4j `ConcurrentHashMap` growing unbounded -**What goes wrong:** The per-IP bucket map grows forever if the app runs for days (every unique IP ever seen occupies memory). -**Why it happens:** `ConcurrentHashMap` has no eviction. -**How to avoid:** For academic scope, this is acceptable. If eviction is desired, use Guava `CacheBuilder.newBuilder().expireAfterAccess(1, TimeUnit.HOURS).build()`. Flag this as a known limitation. - ---- - -## Code Examples - -### Verified: SecurityConfig antMatchers (Spring Security 5 / Spring Boot 2.6) -```java -// Uses .authorizeRequests() — the Spring Security 5 API -// Spring Boot 2.6.x includes Spring Security 5.6.x -http - .csrf().disable() - .sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS) - .and() - .authorizeRequests() - .antMatchers("/api/auth/**").permitAll() - .antMatchers("/api/restaurants/**").permitAll() - .antMatchers("/api/inspections/**").permitAll() - .antMatchers("/swagger-ui.html", "/api-docs/**", "/v3/api-docs/**", - "/swagger-ui/**", "/webjars/**").permitAll() - .antMatchers("/api/reports/**").hasRole("CONTROLLER") - .antMatchers("/api/users/**").authenticated() - .anyRequest().permitAll() - .and() - .exceptionHandling() - .authenticationEntryPoint(/* existing 401 handler */) - .accessDeniedHandler((req, res, ex) -> { - res.setStatus(HttpServletResponse.SC_FORBIDDEN); - res.setContentType("application/json"); - res.getWriter().write("{\"status\":\"error\",\"message\":\"Forbidden\"}"); - }) - .and() - .addFilterBefore(jwtAuthenticationFilter, UsernamePasswordAuthenticationFilter.class); -``` - -### Verified: AppConfig extension pattern (follows existing code) -```java -// AppConfig.java — add alongside existing getters -public static String getControllerSignupCode() { - // Returns null if CONTROLLER_SIGNUP_CODE is not set in env or application.properties - return getProperty("controller.signup.code", null); -} - -public static int getAuthRateLimitRequests() { - return getIntProperty("auth.rate-limit.requests", 10); -} - -public static int getAuthRateLimitWindowMinutes() { - return getIntProperty("auth.rate-limit.window-minutes", 1); -} -``` - -### Verified: Bucket4j 7.x API (Java 11 compatible) -```java -// Bucket creation in Bucket4j 7.x -import com.bucket4j.Bandwidth; -import com.bucket4j.Bucket; -import com.bucket4j.Refill; -import java.time.Duration; - -Bucket bucket = Bucket.builder() - .addLimit(Bandwidth.classic(maxRequests, Refill.greedy(maxRequests, Duration.ofMinutes(1)))) - .build(); - -// Try to consume a token -if (bucket.tryConsume(1)) { - // proceed -} else { - // return 429 -} -``` - ---- - -## State of the Art - -| Old Approach | Current Approach | When Changed | Impact | -|--------------|------------------|--------------|--------| -| `WebSecurityConfigurerAdapter` extends | `SecurityFilterChain` @Bean | Spring Security 5.7 / Boot 2.7 | Already using new style — no action needed | -| `authorizeHttpRequests()` | `authorizeRequests()` | Spring Security 6 removed old API | This app uses Boot 2.6 / Security 5.6 — `authorizeRequests()` is correct here | -| `antMatchers` | `requestMatchers` | Spring Security 6 | Use `antMatchers` on Security 5.6 | - -**Deprecated/outdated:** -- `WebSecurityConfigurerAdapter`: replaced by `SecurityFilterChain` bean — already done correctly in the project. -- `authorizeHttpRequests()` + `requestMatchers()`: these are the Spring Security 6 APIs. Do NOT use them here; the project is on 5.6. - ---- - -## Open Questions - -1. **Seed account passwords** - - What we know: `DataSeeder` needs to encode and store passwords - - What's unclear: Should passwords be configurable env vars or hardcoded test values? - - Recommendation: Hardcode a known test password (e.g., `Test1234!`) for academic scope; document the credentials in a test README or comments. Optionally add `SEED_CUSTOMER_PASSWORD` / `SEED_CONTROLLER_PASSWORD` env vars following the `AppConfig` pattern if the planner wants configurability. - -2. **Rate limit threshold values** - - What we know: Threshold must be configurable (from CONTEXT.md discretion) - - What's unclear: Exact default numbers (requests per window) - - Recommendation: Default to 10 requests per 1-minute window per IP for auth endpoints. This is conservative but functional for an academic app. - -3. **ConcurrentHashMap bucket eviction** - - What we know: Unbounded map is a memory concern for long-running instances - - What's unclear: Whether the academic scope warrants the fix - - Recommendation: Flag as known limitation; do not add Guava dependency just for this. A comment in the code is sufficient. - ---- - -## Validation Architecture - -### Test Framework -| Property | Value | -|----------|-------| -| Framework | JUnit 5 (Jupiter) via `spring-boot-starter-test` + JUnit 4 via explicit dependency | -| Config file | None — Maven Surefire picks up both via the BOM | -| Quick run command | `mvn test -Dtest=AuthServiceTest,JwtUtilTest -DfailIfNoTests=false` | -| Full suite command | `mvn test` | - -Note: Existing tests use JUnit 5 (`@ExtendWith(MockitoExtension.class)`, `@Test` from `org.junit.jupiter`) despite JUnit 4 being listed in pom.xml. The `spring-boot-starter-test` BOM manages JUnit 5 automatically. - -### Phase Requirements → Test Map - -| Req ID | Behavior | Test Type | Automated Command | File Exists? | -|--------|----------|-----------|-------------------|-------------| -| AUTH-01 | `register()` stores `ROLE_CUSTOMER` when no signup code given | unit | `mvn test -Dtest=AuthServiceTest#register_assignsCustomerRole_whenNoSignupCode` | ❌ Wave 0 | -| AUTH-01 | `register()` stores `ROLE_CONTROLLER` when correct code given | unit | `mvn test -Dtest=AuthServiceTest#register_assignsControllerRole_whenCorrectSignupCode` | ❌ Wave 0 | -| AUTH-02 | `register()` throws when wrong signup code given | unit | `mvn test -Dtest=AuthServiceTest#register_throws_whenWrongSignupCode` | ❌ Wave 0 | -| AUTH-02 | `register()` throws when signup code given but env var not set | unit | `mvn test -Dtest=AuthServiceTest#register_throws_whenSignupCodeEnvVarAbsent` | ❌ Wave 0 | -| AUTH-03 | `/api/reports/**` returns 401 for unauthenticated request | unit/slice | `mvn test -Dtest=SecurityConfigTest#reports_returns401_whenUnauthenticated` | ❌ Wave 0 | -| AUTH-03 | `/api/reports/**` returns 403 for CUSTOMER JWT | unit/slice | `mvn test -Dtest=SecurityConfigTest#reports_returns403_forCustomerJwt` | ❌ Wave 0 | -| AUTH-03 | `/api/reports/**` returns 200 (or non-4xx) for CONTROLLER JWT | unit/slice | `mvn test -Dtest=SecurityConfigTest#reports_allowsAccess_forControllerJwt` | ❌ Wave 0 | -| AUTH-04 | RateLimitFilter returns 429 after threshold exceeded | unit | `mvn test -Dtest=RateLimitFilterTest#filter_returns429_afterThresholdExceeded` | ❌ Wave 0 | -| AUTH-04 | RateLimitFilter passes through before threshold | unit | `mvn test -Dtest=RateLimitFilterTest#filter_passes_beforeThreshold` | ❌ Wave 0 | -| AUTH-05 | DataSeeder creates seed accounts on startup | unit | `mvn test -Dtest=DataSeederTest#run_createsCustomerAndController_whenAbsent` | ❌ Wave 0 | -| AUTH-05 | DataSeeder is idempotent (no duplicate on re-run) | unit | `mvn test -Dtest=DataSeederTest#run_skipsExisting_whenAlreadySeeded` | ❌ Wave 0 | - -### Sampling Rate -- **Per task commit:** `mvn test -Dtest=AuthServiceTest,JwtUtilTest -DfailIfNoTests=false` -- **Per wave merge:** `mvn test` -- **Phase gate:** Full suite green before `/gsd:verify-work` - -### Wave 0 Gaps -- [ ] `src/test/java/com/aflokkat/service/AuthServiceTest.java` — extend existing file with new role-assignment test cases (AUTH-01, AUTH-02) -- [ ] `src/test/java/com/aflokkat/config/SecurityConfigTest.java` — new `@WebMvcTest`-style slice test for URL guards (AUTH-03); note: requires MockMvc + test security config -- [ ] `src/test/java/com/aflokkat/security/RateLimitFilterTest.java` — new unit test for rate limit filter (AUTH-04) -- [ ] `src/test/java/com/aflokkat/startup/DataSeederTest.java` — new Mockito unit test for DataSeeder (AUTH-05) - -**Note on SecurityConfigTest:** `@WebMvcTest` with Spring Security requires `@WithMockUser` or custom `SecurityMockMvcConfigurer` to inject test JWTs. The test must use `@Import(SecurityConfig.class)` and mock the `JwtAuthenticationFilter`. This is the most complex test to wire. - ---- - -## Sources - -### Primary (HIGH confidence) -- Direct code inspection of `SecurityConfig.java`, `JwtAuthenticationFilter.java`, `JwtUtil.java`, `AuthService.java`, `AppConfig.java`, `RegisterRequest.java`, `UserEntity.java`, `AuthController.java` — all in project source -- Spring Boot 2.6.15 / Spring Security 5.6.x — confirmed via `pom.xml` parent `spring-boot-starter-parent:2.6.15` -- pom.xml dependency list — confirms jjwt 0.11.5, springdoc 1.8.0, JUnit 4.13.2, no Bucket4j currently present - -### Secondary (MEDIUM confidence) -- Bucket4j 7.x Java 11 compatibility — known from library documentation; 8.x requires Java 17 is a well-documented breaking change -- Spring Security `authorizeRequests()` vs `authorizeHttpRequests()` API split — documented in Spring Security 5.6 migration guide and 6.0 release notes - -### Tertiary (LOW confidence) -- None — all claims supported by project source inspection or well-established Spring Security documentation - ---- - -## Metadata - -**Confidence breakdown:** -- Standard stack: HIGH — verified against pom.xml; only new dependency is Bucket4j 7.6.0 -- Architecture: HIGH — based on direct code reading of all referenced files; patterns are standard Spring Security 5 idioms -- Pitfalls: HIGH — derived from actual code inspection (existing filter wiring, ddl-auto=update, @Component registration behavior) - -**Research date:** 2026-03-27 -**Valid until:** 2026-06-27 (Spring Boot 2.6 is stable; Bucket4j 7.x API is stable) diff --git a/.planning/phases/01-role-infrastructure/01-VALIDATION.md b/.planning/phases/01-role-infrastructure/01-VALIDATION.md deleted file mode 100644 index b9b3aec..0000000 --- a/.planning/phases/01-role-infrastructure/01-VALIDATION.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -phase: 1 -slug: role-infrastructure -status: draft -nyquist_compliant: false -wave_0_complete: false -created: 2026-03-27 ---- - -# Phase 1 — Validation Strategy - -> Per-phase validation contract for feedback sampling during execution. - ---- - -## Test Infrastructure - -| Property | Value | -|----------|-------| -| **Framework** | JUnit 4 + Mockito (existing) | -| **Config file** | `pom.xml` (existing) | -| **Quick run command** | `mvn test -pl . -Dtest=AuthServiceTest,JwtUtilTest -q` | -| **Full suite command** | `mvn test -q` | -| **Estimated runtime** | ~30 seconds | - ---- - -## Sampling Rate - -- **After every task commit:** Run `mvn test -pl . -Dtest=AuthServiceTest,JwtUtilTest -q` -- **After every plan wave:** Run `mvn test -q` -- **Before `/gsd:verify-work`:** Full suite must be green -- **Max feedback latency:** 30 seconds - ---- - -## Per-Task Verification Map - -| Task ID | Plan | Wave | Requirement | Test Type | Automated Command | File Exists | Status | -|---------|------|------|-------------|-----------|-------------------|-------------|--------| -| 1-01-01 | 01 | 1 | AUTH-01 | unit | `mvn test -Dtest=AuthServiceTest -q` | ✅ | ⬜ pending | -| 1-01-02 | 01 | 1 | AUTH-02 | unit | `mvn test -Dtest=AuthServiceTest -q` | ✅ | ⬜ pending | -| 1-01-03 | 01 | 1 | AUTH-03 | unit | `mvn test -Dtest=SecurityConfigTest -q` | ❌ W0 | ⬜ pending | -| 1-01-04 | 01 | 1 | AUTH-04 | unit | `mvn test -Dtest=RateLimitFilterTest -q` | ❌ W0 | ⬜ pending | -| 1-01-05 | 01 | 1 | AUTH-05 | unit | `mvn test -Dtest=DataSeederTest -q` | ❌ W0 | ⬜ pending | - -*Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky* - ---- - -## Wave 0 Requirements - -- [ ] `src/test/java/com/aflokkat/config/SecurityConfigTest.java` — stubs for AUTH-03 (antMatcher rules) -- [ ] `src/test/java/com/aflokkat/security/RateLimitFilterTest.java` — stubs for AUTH-04 (rate limiting) -- [ ] `src/test/java/com/aflokkat/DataSeederTest.java` — stubs for AUTH-05 (seeded accounts) - -*Existing infrastructure covers AUTH-01 and AUTH-02 via `AuthServiceTest`.* - ---- - -## Manual-Only Verifications - -| Behavior | Requirement | Why Manual | Test Instructions | -|----------|-------------|------------|-------------------| -| HTTP 429 returned on 11th request to /api/auth/login | AUTH-04 | Requires running app + HTTP client to send burst requests | `for i in $(seq 1 11); do curl -s -o /dev/null -w "%{http_code}\n" -X POST http://localhost:8080/api/auth/login -H 'Content-Type: application/json' -d '{"username":"x","password":"x"}'; done` | -| Seeded accounts can log in immediately after startup | AUTH-05 | Requires running Docker Compose stack | `curl -s -X POST http://localhost:8080/api/auth/login -d '{"username":"customer_test","password":"Test1234!"}' \| grep accessToken` | - ---- - -## Validation Sign-Off - -- [ ] All tasks have `` verify or Wave 0 dependencies -- [ ] Sampling continuity: no 3 consecutive tasks without automated verify -- [ ] Wave 0 covers all MISSING references -- [ ] No watch-mode flags -- [ ] Feedback latency < 30s -- [ ] `nyquist_compliant: true` set in frontmatter - -**Approval:** pending diff --git a/.planning/phases/02-controller-reports/02-01-PLAN.md b/.planning/phases/02-controller-reports/02-01-PLAN.md deleted file mode 100644 index dc0202f..0000000 --- a/.planning/phases/02-controller-reports/02-01-PLAN.md +++ /dev/null @@ -1,482 +0,0 @@ ---- -phase: 02-controller-reports -plan: "01" -type: execute -wave: 1 -depends_on: [] -files_modified: - - src/main/java/com/aflokkat/entity/InspectionReportEntity.java - - src/main/java/com/aflokkat/entity/Grade.java - - src/main/java/com/aflokkat/entity/Status.java - - src/main/java/com/aflokkat/repository/ReportRepository.java - - src/main/java/com/aflokkat/dto/ReportRequest.java - - src/main/java/com/aflokkat/controller/ReportController.java - - src/test/java/com/aflokkat/controller/ReportControllerTest.java -autonomous: true -requirements: [CTRL-01, CTRL-02] - -must_haves: - truths: - - "A controller can POST to /api/reports with a restaurantId, grade, status, violationCodes, and notes and receive the saved report enriched with restaurantName and borough" - - "A controller can GET /api/reports and receive only their own reports (not other controllers' reports)" - - "GET /api/reports?status=OPEN returns only OPEN reports for the authenticated controller; omitting the param returns all" - - "The inspection_reports table is created automatically in PostgreSQL on application startup" - - "All report endpoints return 401 for unauthenticated requests and 403 for CUSTOMER JWT requests (SecurityConfig guard already in place)" - artifacts: - - path: "src/main/java/com/aflokkat/entity/InspectionReportEntity.java" - provides: "JPA entity mapping to inspection_reports table" - contains: "@Table(name = \"inspection_reports\")" - - path: "src/main/java/com/aflokkat/entity/Grade.java" - provides: "Grade enum A/B/C/F" - exports: ["Grade"] - - path: "src/main/java/com/aflokkat/entity/Status.java" - provides: "Status enum OPEN/IN_PROGRESS/RESOLVED" - exports: ["Status"] - - path: "src/main/java/com/aflokkat/repository/ReportRepository.java" - provides: "JPA repository with findByUserId and findByUserIdAndStatus" - exports: ["ReportRepository"] - - path: "src/main/java/com/aflokkat/dto/ReportRequest.java" - provides: "POST + PATCH request body DTO" - exports: ["ReportRequest"] - - path: "src/main/java/com/aflokkat/controller/ReportController.java" - provides: "POST /api/reports and GET /api/reports endpoints" - exports: ["ReportController"] - - path: "src/test/java/com/aflokkat/controller/ReportControllerTest.java" - provides: "Unit tests for CTRL-01 through CTRL-04 (stub file, methods filled per plan)" - key_links: - - from: "ReportController.createReport()" - to: "reportRepository.save()" - via: "InspectionReportEntity construction" - pattern: "reportRepository\\.save\\(" - - from: "ReportController.listReports()" - to: "reportRepository.findByUserId / findByUserIdAndStatus" - via: "getCurrentUser().getId()" - pattern: "findByUserId\\|findByUserIdAndStatus" - - from: "ReportController.toResponseMap()" - to: "restaurantDAO.findByRestaurantId()" - via: "entity.getRestaurantId()" - pattern: "restaurantDAO\\.findByRestaurantId" ---- - - -Create the JPA data layer (entity, enums, repository, DTO) and implement POST + GET list endpoints for inspection reports. - -Purpose: CTRL-01 and CTRL-02 require a persisted report entity and two read/write endpoints. This plan creates everything consumed by plans 02 and 03. -Output: inspection_reports table auto-created in PostgreSQL; POST /api/reports creates a report; GET /api/reports returns the caller's reports with MongoDB enrichment; test scaffold compiled and Wave 0 test stubs passing. - - - -@/home/missia03/.claude/get-shit-done/workflows/execute-plan.md -@/home/missia03/.claude/get-shit-done/templates/summary.md - - - -@.planning/PROJECT.md -@.planning/ROADMAP.md -@.planning/STATE.md -@.planning/phases/02-controller-reports/02-CONTEXT.md -@.planning/phases/02-controller-reports/02-RESEARCH.md - - - - -From src/main/java/com/aflokkat/entity/BookmarkEntity.java (template for InspectionReportEntity): -```java -@Entity -@Table(name = "bookmarks", - uniqueConstraints = @UniqueConstraint(columnNames = {"user_id", "restaurant_id"})) -public class BookmarkEntity { - @Id @GeneratedValue(strategy = GenerationType.IDENTITY) - private Long id; - - @ManyToOne(fetch = FetchType.LAZY) - @JoinColumn(name = "user_id", nullable = false) - private UserEntity user; - - @Column(name = "restaurant_id", nullable = false) - private String restaurantId; - - @Column(name = "created_at") - private Date createdAt = new Date(); - // getters/setters -} -``` - -From src/main/java/com/aflokkat/repository/BookmarkRepository.java (template for ReportRepository): -```java -@Repository -public interface BookmarkRepository extends JpaRepository { - List findByUserId(Long userId); - Optional findByUserIdAndRestaurantId(Long userId, String restaurantId); - boolean existsByUserIdAndRestaurantId(Long userId, String restaurantId); - void deleteByUserIdAndRestaurantId(Long userId, String restaurantId); -} -``` - -From src/main/java/com/aflokkat/entity/UserEntity.java: -```java -public class UserEntity { - private Long id; // FK target for InspectionReportEntity.user_id - private String username; - private String role; // "ROLE_CONTROLLER" / "ROLE_CUSTOMER" - public Long getId() { return id; } - public String getUsername() { return username; } -} -``` - -From src/main/java/com/aflokkat/controller/UserController.java (getCurrentUser() pattern): -```java -@Autowired private UserRepository userRepository; -@Autowired private RestaurantDAO restaurantDAO; - -private UserEntity getCurrentUser() { - String username = SecurityContextHolder.getContext().getAuthentication().getName(); - return userRepository.findByUsername(username) - .orElseThrow(() -> new IllegalArgumentException("User not found")); -} -``` - -From src/main/java/com/aflokkat/util/ResponseUtil.java: -```java -public static ResponseEntity> errorResponse(Exception e) { - int status = (e instanceof IllegalArgumentException) ? 400 : 500; - Map response = new HashMap<>(); - response.put("status", "error"); - response.put("message", e.getMessage()); - return ResponseEntity.status(status).body(response); -} -``` - -From src/main/java/com/aflokkat/dao/RestaurantDAO.java: -```java -Restaurant findByRestaurantId(String restaurantId); // returns null if not found -``` - -From src/main/java/com/aflokkat/domain/Restaurant.java — required fields: -```java -public String getName(); // maps to restaurantName in response -public String getBorough(); // maps to borough in response -``` - - - - - - - Task 1: Wave 0 — Entity, enums, repository, DTO, and test scaffold - - src/main/java/com/aflokkat/entity/InspectionReportEntity.java, - src/main/java/com/aflokkat/entity/Grade.java, - src/main/java/com/aflokkat/entity/Status.java, - src/main/java/com/aflokkat/repository/ReportRepository.java, - src/main/java/com/aflokkat/dto/ReportRequest.java, - src/test/java/com/aflokkat/controller/ReportControllerTest.java - - - - src/main/java/com/aflokkat/entity/BookmarkEntity.java (structural template — replicate @ManyToOne, @JoinColumn, @Column patterns exactly) - - src/main/java/com/aflokkat/repository/BookmarkRepository.java (interface template — derived query naming) - - src/main/java/com/aflokkat/entity/UserEntity.java (FK target — Long id type) - - src/test/java/com/aflokkat/service/AuthServiceTest.java (established test pattern — @ExtendWith(MockitoExtension.class), JUnit 5, Mockito 5) - - pom.xml (confirm mockito-core version and surefire config before writing test imports) - - - - Test compiles with @ExtendWith(MockitoExtension.class) and mocks for ReportRepository, RestaurantDAO, UserRepository - - All test method stubs (createReport_*, listReports_*, patchReport_*, photoUpload_*) exist as @Test with fail("not implemented") or Assumptions.abort() so they FAIL intentionally at this stage - - mvn test -Dtest=ReportControllerTest runs without compilation errors; test methods are found but fail (RED state) - - - Create the following six files in exact order (each must compile before the next): - - 1. src/main/java/com/aflokkat/entity/Grade.java - ```java - package com.aflokkat.entity; - public enum Grade { A, B, C, F } - ``` - - 2. src/main/java/com/aflokkat/entity/Status.java - ```java - package com.aflokkat.entity; - public enum Status { OPEN, IN_PROGRESS, RESOLVED } - ``` - - 3. src/main/java/com/aflokkat/entity/InspectionReportEntity.java — replicate the exact @ManyToOne + @JoinColumn + @Column pattern from BookmarkEntity. Table name: "inspection_reports". Fields: - - Long id (@Id @GeneratedValue IDENTITY) - - UserEntity user (@ManyToOne FetchType.LAZY, @JoinColumn name="user_id" nullable=false) - - String restaurantId (@Column name="restaurant_id" nullable=false) - - Grade grade (@Enumerated EnumType.STRING, @Column nullable=false) - - Status status (@Enumerated EnumType.STRING, @Column nullable=false) - - String violationCodes (@Column columnDefinition="TEXT") — nullable - - String notes (@Column columnDefinition="TEXT") — nullable - - String photoPath (@Column columnDefinition="TEXT") — nullable - - Date createdAt (@Column name="created_at") - - Date updatedAt (@Column name="updated_at") - - Default constructor, all-field getters and setters. - - Initialize createdAt and updatedAt to new Date() at declaration. - - 4. src/main/java/com/aflokkat/repository/ReportRepository.java — replicate BookmarkRepository structure: - ```java - package com.aflokkat.repository; - import com.aflokkat.entity.InspectionReportEntity; - import com.aflokkat.entity.Status; - import org.springframework.data.jpa.repository.JpaRepository; - import org.springframework.stereotype.Repository; - import java.util.List; - - @Repository - public interface ReportRepository extends JpaRepository { - List findByUserId(Long userId); - List findByUserIdAndStatus(Long userId, Status status); - } - ``` - - 5. src/main/java/com/aflokkat/dto/ReportRequest.java — single DTO for both POST body and PATCH body: - ```java - package com.aflokkat.dto; - import com.aflokkat.entity.Grade; - import com.aflokkat.entity.Status; - - public class ReportRequest { - private String restaurantId; // required for POST; ignored for PATCH - private Grade grade; // required for POST; optional for PATCH (null = unchanged) - private Status status; // optional for POST (defaults to OPEN); optional for PATCH - private String violationCodes; // optional - private String notes; // optional - // getters and setters for all fields - } - ``` - - 6. src/test/java/com/aflokkat/controller/ReportControllerTest.java — Wave 0 scaffold using the Java 25-safe pattern (NEVER @WebMvcTest): - ```java - package com.aflokkat.controller; - - import com.aflokkat.dao.RestaurantDAO; - import com.aflokkat.repository.ReportRepository; - import com.aflokkat.repository.UserRepository; - import org.junit.jupiter.api.Test; - import org.junit.jupiter.api.extension.ExtendWith; - import org.mockito.Mock; - import org.mockito.junit.jupiter.MockitoExtension; - - import static org.junit.jupiter.api.Assumptions.abort; - - @ExtendWith(MockitoExtension.class) - class ReportControllerTest { - - @Mock private ReportRepository reportRepository; - @Mock private RestaurantDAO restaurantDAO; - @Mock private UserRepository userRepository; - - // ── CTRL-01: create report ───────────────────────────────────────────── - @Test void createReport_returns201WithEnrichedData_onValidRequest() { abort("not implemented"); } - @Test void createReport_returns400_whenRestaurantIdMissing() { abort("not implemented"); } - @Test void createReport_enrichesWithNullFields_whenRestaurantNotInMongo() { abort("not implemented"); } - - // ── CTRL-02: list reports ────────────────────────────────────────────── - @Test void listReports_returnsOnlyCallerReports_notOtherControllers() { abort("not implemented"); } - @Test void listReports_filtersByStatus_whenStatusParamPresent() { abort("not implemented"); } - @Test void listReports_returnsAll_whenStatusParamAbsent() { abort("not implemented"); } - - // ── CTRL-03: patch report ────────────────────────────────────────────── - @Test void patchReport_updatesOwnedReport_andReturns200() { abort("not implemented"); } - @Test void patchReport_returns403_whenNotOwner() { abort("not implemented"); } - @Test void patchReport_appliesOnlyNonNullFields_leavingOthersUnchanged() { abort("not implemented"); } - - // ── CTRL-04: photo upload ────────────────────────────────────────────── - @Test void photoUpload_savesFileAndUpdatesPhotoPath() { abort("not implemented"); } - @Test void photoUpload_returns404_whenReportNotFound() { abort("not implemented"); } - @Test void getPhoto_streamsFileWithCorrectContentType() { abort("not implemented"); } - } - ``` - - - cd /home/missia03/Aflokkat/big_data/quickstart-app && mvn test -Dtest=ReportControllerTest -pl . 2>&1 | tail -20 - - - - All six files exist and compile without errors. - - mvn test -Dtest=ReportControllerTest runs: 12 test methods are found; all abort (TestAbortedException, not compilation failures). - - mvn compile produces BUILD SUCCESS with no errors referencing any of the new files. - - - - - Task 2: POST /api/reports and GET /api/reports endpoints + fill CTRL-01/02 tests - - src/main/java/com/aflokkat/controller/ReportController.java, - src/test/java/com/aflokkat/controller/ReportControllerTest.java - - - - src/main/java/com/aflokkat/controller/UserController.java (getCurrentUser() pattern, @Autowired field injection, ResponseUtil usage, response shape {"status":"success","data":...,"count":...}) - - src/main/java/com/aflokkat/util/ResponseUtil.java (errorResponse signature — maps IllegalArgumentException to 400, everything else to 500; NEVER throw for 403) - - src/main/java/com/aflokkat/entity/InspectionReportEntity.java (just created in Task 1 — read before touching) - - src/main/java/com/aflokkat/repository/ReportRepository.java (just created in Task 1) - - src/main/java/com/aflokkat/config/SecurityConfig.java (confirm /api/reports/** requires ROLE_CONTROLLER — no changes needed, just verify) - - - - createReport_returns201WithEnrichedData_onValidRequest: POST with restaurantId="R1", grade=A, status=OPEN → mock save returns entity with id=1L → mock restaurantDAO.findByRestaurantId("R1") returns Restaurant(name="Joe's", borough="Manhattan") → response contains id=1, restaurantName="Joe's", borough="Manhattan", grade="A", status="OPEN" - - createReport_returns400_whenRestaurantIdMissing: POST with restaurantId=null → IllegalArgumentException thrown → 400 response with {"status":"error","message":"restaurantId is required"} - - createReport_enrichesWithNullFields_whenRestaurantNotInMongo: POST with restaurantId="UNKNOWN" → restaurantDAO returns null → response contains restaurantName=null, borough=null (no exception thrown) - - listReports_returnsOnlyCallerReports_notOtherControllers: getCurrentUser() returns user with id=42L → reportRepository.findByUserId(42L) returns [entity1, entity2] → response count=2 - - listReports_filtersByStatus_whenStatusParamPresent: status=OPEN param → reportRepository.findByUserIdAndStatus(42L, Status.OPEN) called (not findByUserId) - - listReports_returnsAll_whenStatusParamAbsent: no status param → reportRepository.findByUserId(42L) called (not findByUserIdAndStatus) - - - First, write the GREEN test implementations for createReport_* and listReports_* in ReportControllerTest.java using MockMvc standaloneSetup (same pattern as Phase 1 SecurityConfigTest — NOT @WebMvcTest). - - Then create src/main/java/com/aflokkat/controller/ReportController.java: - - ```java - package com.aflokkat.controller; - - import com.aflokkat.dao.RestaurantDAO; - import com.aflokkat.domain.Restaurant; - import com.aflokkat.dto.ReportRequest; - import com.aflokkat.entity.InspectionReportEntity; - import com.aflokkat.entity.Status; - import com.aflokkat.entity.UserEntity; - import com.aflokkat.repository.ReportRepository; - import com.aflokkat.repository.UserRepository; - import com.aflokkat.util.ResponseUtil; - import org.springframework.beans.factory.annotation.Autowired; - import org.springframework.http.HttpStatus; - import org.springframework.http.ResponseEntity; - import org.springframework.security.core.context.SecurityContextHolder; - import org.springframework.transaction.annotation.Transactional; - import org.springframework.web.bind.annotation.*; - - import java.util.*; - - @RestController - @RequestMapping("/api/reports") - public class ReportController { - - @Autowired private ReportRepository reportRepository; - @Autowired private RestaurantDAO restaurantDAO; - @Autowired private UserRepository userRepository; - - // ── Auth helper ──────────────────────────────────────────────────────── - private UserEntity getCurrentUser() { - String username = SecurityContextHolder.getContext().getAuthentication().getName(); - return userRepository.findByUsername(username) - .orElseThrow(() -> new IllegalArgumentException("User not found")); - } - - // ── Response helper ──────────────────────────────────────────────────── - private Map toResponseMap(InspectionReportEntity entity) { - Restaurant restaurant = restaurantDAO.findByRestaurantId(entity.getRestaurantId()); - Map data = new HashMap<>(); - data.put("id", entity.getId()); - data.put("restaurantId", entity.getRestaurantId()); - data.put("restaurantName", restaurant != null ? restaurant.getName() : null); - data.put("borough", restaurant != null ? restaurant.getBorough() : null); - data.put("grade", entity.getGrade()); - data.put("status", entity.getStatus()); - data.put("violationCodes", entity.getViolationCodes()); - data.put("notes", entity.getNotes()); - data.put("photoPath", entity.getPhotoPath() != null - ? "/api/reports/" + entity.getId() + "/photo" : null); - data.put("createdAt", entity.getCreatedAt()); - data.put("updatedAt", entity.getUpdatedAt()); - return data; - } - - // ── POST /api/reports ────────────────────────────────────────────────── - @PostMapping - public ResponseEntity> createReport(@RequestBody ReportRequest req) { - try { - if (req.getRestaurantId() == null || req.getRestaurantId().isBlank()) { - throw new IllegalArgumentException("restaurantId is required"); - } - if (req.getGrade() == null) { - throw new IllegalArgumentException("grade is required"); - } - UserEntity currentUser = getCurrentUser(); - - InspectionReportEntity report = new InspectionReportEntity(); - report.setUser(currentUser); - report.setRestaurantId(req.getRestaurantId()); - report.setGrade(req.getGrade()); - report.setStatus(req.getStatus() != null ? req.getStatus() : Status.OPEN); - report.setViolationCodes(req.getViolationCodes()); - report.setNotes(req.getNotes()); - report.setCreatedAt(new Date()); - report.setUpdatedAt(new Date()); - - InspectionReportEntity saved = reportRepository.save(report); - - Map response = new HashMap<>(); - response.put("status", "success"); - response.put("data", toResponseMap(saved)); - return ResponseEntity.status(HttpStatus.CREATED).body(response); - } catch (Exception e) { - return ResponseUtil.errorResponse(e); - } - } - - // ── GET /api/reports ─────────────────────────────────────────────────── - @GetMapping - @Transactional - public ResponseEntity> listReports( - @RequestParam(required = false) Status status) { - try { - UserEntity currentUser = getCurrentUser(); - List entities = (status != null) - ? reportRepository.findByUserIdAndStatus(currentUser.getId(), status) - : reportRepository.findByUserId(currentUser.getId()); - - List> data = new ArrayList<>(); - for (InspectionReportEntity e : entities) { - data.add(toResponseMap(e)); - } - Map response = new HashMap<>(); - response.put("status", "success"); - response.put("data", data); - response.put("count", data.size()); - return ResponseEntity.ok(response); - } catch (Exception e) { - return ResponseUtil.errorResponse(e); - } - } - } - ``` - - Key implementation rules: - - @Autowired on fields (not constructor), matching UserController pattern - - @Transactional on listReports() to prevent LazyInitializationException when toResponseMap() accesses entity fields after the initial load - - photoPath in toResponseMap() must return the URL path "/api/reports/{id}/photo", NOT the raw disk path - - status defaults to Status.OPEN on creation if req.getStatus() is null - - ResponseUtil.errorResponse() handles all 400/500 cases; manual ResponseEntity.status(FORBIDDEN) handles 403 in Plan 02 - - - cd /home/missia03/Aflokkat/big_data/quickstart-app && mvn test -Dtest=ReportControllerTest#createReport*+listReports* -pl . 2>&1 | tail -30 - - - - ReportController.java exists with POST and GET endpoints. - - mvn test -Dtest=ReportControllerTest#createReport* runs 3 tests; all pass (GREEN). - - mvn test -Dtest=ReportControllerTest#listReports* runs 3 tests; all pass (GREEN). - - mvn compile produces BUILD SUCCESS. - - patchReport_* and photoUpload_* tests remain aborted (not yet failing due to missing implementation — that is correct). - - - - - - -After both tasks complete: -- mvn test -Dtest=ReportControllerTest passes 6 tests (createReport_* + listReports_*); remaining 6 abort cleanly -- mvn test (full suite) produces BUILD SUCCESS — no regressions in Phase 1 tests -- grep -r "inspection_reports" src/main/java finds the @Table annotation in InspectionReportEntity.java -- grep -r "findByUserIdAndStatus" src/main/java finds ReportRepository.java -- grep -r "toResponseMap" src/main/java finds ReportController.java - - - -- InspectionReportEntity, Grade, Status, ReportRepository, ReportRequest, ReportController all exist and compile -- POST /api/reports creates a report and returns {"status":"success","data":{...enriched...}} with HTTP 201 -- GET /api/reports returns {"status":"success","data":[...],"count":N} with only the authenticated controller's reports -- GET /api/reports?status=OPEN delegates to findByUserIdAndStatus; no param delegates to findByUserId -- Full test suite green — no Phase 1 regressions - - - -After completion, create `.planning/phases/02-controller-reports/02-01-SUMMARY.md` - diff --git a/.planning/phases/02-controller-reports/02-01-SUMMARY.md b/.planning/phases/02-controller-reports/02-01-SUMMARY.md deleted file mode 100644 index 5cb0314..0000000 --- a/.planning/phases/02-controller-reports/02-01-SUMMARY.md +++ /dev/null @@ -1,145 +0,0 @@ ---- -phase: 02-controller-reports -plan: "01" -subsystem: api -tags: [spring-boot, jpa, postgresql, mockito, junit5, mockmvc] - -# Dependency graph -requires: - - phase: 01-role-infrastructure - provides: UserEntity (FK target), UserRepository, SecurityConfig with /api/reports hasRole(CONTROLLER), JPA config - -provides: - - InspectionReportEntity JPA entity (inspection_reports table, auto-created on startup) - - Grade enum (A/B/C/F) and Status enum (OPEN/IN_PROGRESS/RESOLVED) in com.aflokkat.entity - - ReportRepository with findByUserId and findByUserIdAndStatus - - ReportRequest DTO for POST and PATCH bodies - - ReportController: POST /api/reports (201 + enriched) and GET /api/reports (list with MongoDB enrichment) - - ReportControllerTest: 6 GREEN tests (CTRL-01, CTRL-02) + 6 aborting stubs (CTRL-03, CTRL-04) - -affects: - - 02-02 (PATCH /api/reports/{id} — fills patchReport_* stubs) - - 02-03 (photo upload — fills photoUpload_* stubs) - -# Tech tracking -tech-stack: - added: [] - patterns: - - "@InjectMocks + MockMvcBuilders.standaloneSetup() for controller unit tests (no @WebMvcTest)" - - "assumeTrue(false) for TDD RED stubs on JUnit 5.8.2 (abort(String) not available until 5.9)" - - "@ManyToOne FetchType.LAZY + @JoinColumn for FK-to-UserEntity pattern (matches BookmarkEntity)" - - "@Enumerated(EnumType.STRING) for Grade and Status columns" - - "@Transactional on listReports() to prevent LazyInitializationException" - -key-files: - created: - - src/main/java/com/aflokkat/entity/Grade.java - - src/main/java/com/aflokkat/entity/Status.java - - src/main/java/com/aflokkat/entity/InspectionReportEntity.java - - src/main/java/com/aflokkat/repository/ReportRepository.java - - src/main/java/com/aflokkat/dto/ReportRequest.java - - src/main/java/com/aflokkat/controller/ReportController.java - - src/test/java/com/aflokkat/controller/ReportControllerTest.java - modified: [] - -key-decisions: - - "assumeTrue(false) used instead of Assumptions.abort(String) — abort(String) was added in JUnit 5.9.0, project uses 5.8.2 via Spring Boot 2.6.15 BOM" - - "Grade enum placed in com.aflokkat.entity (not com.aflokkat.domain) to avoid collision with existing com.aflokkat.domain.Grade (MongoDB POJO)" - -patterns-established: - - "Controller unit test pattern: @InjectMocks on controller + MockMvcBuilders.standaloneSetup + SecurityContextHolder manual auth setup" - - "TDD stub pattern for JUnit 5.8.2: assumeTrue(false, message) in @Test methods" - -requirements-completed: [CTRL-01, CTRL-02] - -# Metrics -duration: 18min -completed: 2026-03-30 ---- - -# Phase 02 Plan 01: Controller Reports Data Layer and POST/GET Endpoints Summary - -**JPA inspection_reports table (Grade/Status enums), ReportRepository, and POST+GET /api/reports endpoints with MongoDB enrichment — 6 CTRL-01/02 tests GREEN, 6 CTRL-03/04 stubs aborting** - -## Performance - -- **Duration:** 18 min -- **Started:** 2026-03-30T13:04:20Z -- **Completed:** 2026-03-30T13:22:57Z -- **Tasks:** 2 -- **Files modified:** 7 - -## Accomplishments -- Created complete JPA data layer: Grade enum, Status enum, InspectionReportEntity (@Table inspection_reports), ReportRepository (findByUserId + findByUserIdAndStatus), ReportRequest DTO -- Implemented POST /api/reports (creates report with status defaulting to OPEN, HTTP 201, enriched with restaurantName/borough from MongoDB) -- Implemented GET /api/reports (lists caller's own reports, delegates to findByUserIdAndStatus when ?status= param present, toResponseMap for enrichment) -- 6 CTRL-01/02 tests passing GREEN; 6 CTRL-03/04 stubs cleanly aborting; 56 total unit tests pass with no regressions - -## Task Commits - -Each task was committed atomically: - -1. **Task 1: Wave 0 — Entity, enums, repository, DTO, and test scaffold** - `7668998` (test) -2. **Task 2: POST /api/reports and GET /api/reports endpoints + fill CTRL-01/02 tests** - `cfa052b` (feat) - -**Plan metadata:** _(docs commit — added below after state updates)_ - -_Note: TDD tasks may have multiple commits (test -> feat -> refactor)_ - -## Files Created/Modified -- `src/main/java/com/aflokkat/entity/Grade.java` - Grade enum (A/B/C/F) for inspection reports -- `src/main/java/com/aflokkat/entity/Status.java` - Status enum (OPEN/IN_PROGRESS/RESOLVED) -- `src/main/java/com/aflokkat/entity/InspectionReportEntity.java` - JPA entity mapped to inspection_reports table -- `src/main/java/com/aflokkat/repository/ReportRepository.java` - JPA repository with findByUserId and findByUserIdAndStatus -- `src/main/java/com/aflokkat/dto/ReportRequest.java` - POST/PATCH request body DTO -- `src/main/java/com/aflokkat/controller/ReportController.java` - POST /api/reports and GET /api/reports endpoints -- `src/test/java/com/aflokkat/controller/ReportControllerTest.java` - 12 tests (6 GREEN + 6 aborting stubs) - -## Decisions Made -- `assumeTrue(false)` used instead of `Assumptions.abort(String)` — `abort(String)` was introduced in JUnit 5.9.0, but the project is on 5.8.2 via Spring Boot 2.6.15 BOM; `assumeTrue(false)` achieves identical TestAbortedException behavior. -- `Grade` enum placed in `com.aflokkat.entity` (not `com.aflokkat.domain`) to avoid collision with the existing `com.aflokkat.domain.Grade` MongoDB POJO class. - -## Deviations from Plan - -### Auto-fixed Issues - -**1. [Rule 3 - Blocking] Fixed missing static import for abort(String) — replaced with assumeTrue(false)** -- **Found during:** Task 1 (test scaffold compilation) -- **Issue:** Plan scaffold used `import static org.junit.jupiter.api.Assumptions.abort` and called `abort("not implemented")`. JUnit 5.8.2 does not have `Assumptions.abort(String)` — that method was added in JUnit 5.9.0. -- **Fix:** Replaced all `abort("not implemented")` calls with `assumeTrue(false, "not implemented")`. Behavior is identical: test is aborted with TestAbortedException (counted as "Skipped"). -- **Files modified:** `src/test/java/com/aflokkat/controller/ReportControllerTest.java` -- **Verification:** `mvn test -Dtest=ReportControllerTest` shows 12 tests, 0 failures, 12 skipped (RED state confirmed). -- **Committed in:** 7668998 (Task 1 commit) - -**2. [Rule 3 - Blocking] Fixed ResultMatcher chaining .or() not available in Spring Boot 2.6.15 test library** -- **Found during:** Task 2 (GREEN test compilation) -- **Issue:** Test used `.andExpect(jsonPath("$.data.restaurantName").doesNotExist().or(...))` — the `.or()` combinator on `ResultMatcher` doesn't exist in Spring Boot 2.6.15's spring-test library. -- **Fix:** Simplified assertion to `jsonPath("$.data.restaurantName").value(nullValue())` — the JSON serializer outputs `"restaurantName": null` when the value is null, so the assertion is correct and more direct. -- **Files modified:** `src/test/java/com/aflokkat/controller/ReportControllerTest.java` -- **Verification:** 6 CTRL-01/02 tests pass GREEN after fix. -- **Committed in:** cfa052b (Task 2 commit) - ---- - -**Total deviations:** 2 auto-fixed (2 blocking — JUnit API version mismatch, MockMvc API mismatch) -**Impact on plan:** Both auto-fixes necessary to compile and run tests. No scope creep; behavioral contract unchanged. - -## Issues Encountered -- Full `mvn test` suite hung/timed out — likely due to integration test or network-bound test (RestaurantDAOIntegrationTest, NycOpenDataClientTest). Regression verification was done by running a named subset of 56 unit tests: AuthServiceTest, ReportControllerTest, SecurityConfigTest, ValidationUtilTest, DataSeederTest, JwtUtilTest — all passed. - -## User Setup Required -None - no external service configuration required. - -## Next Phase Readiness -- inspection_reports table auto-created by Hibernate on next application startup -- POST /api/reports and GET /api/reports are ready to test end-to-end -- ReportControllerTest has 6 aborting stubs ready for Plan 02 (PATCH) and Plan 03 (photo upload) to fill in -- SecurityConfig already has `/api/reports/**` guarded by `hasRole("CONTROLLER")` — 401/403 behavior tested in SecurityConfigTest - ---- -*Phase: 02-controller-reports* -*Completed: 2026-03-30* - -## Self-Check: PASSED - -All files exist on disk. Both task commits (7668998, cfa052b) confirmed in git history. diff --git a/.planning/phases/02-controller-reports/02-02-PLAN.md b/.planning/phases/02-controller-reports/02-02-PLAN.md deleted file mode 100644 index 6e4f00f..0000000 --- a/.planning/phases/02-controller-reports/02-02-PLAN.md +++ /dev/null @@ -1,227 +0,0 @@ ---- -phase: 02-controller-reports -plan: "02" -type: execute -wave: 2 -depends_on: ["02-01"] -files_modified: - - src/main/java/com/aflokkat/controller/ReportController.java - - src/test/java/com/aflokkat/controller/ReportControllerTest.java -autonomous: true -requirements: [CTRL-03] - -must_haves: - truths: - - "A controller can PATCH /api/reports/{id} and update grade, status, violationCodes, notes on a report they own" - - "Only non-null fields in the PATCH body are applied; null fields are left unchanged on the entity" - - "A controller attempting to PATCH a report owned by another controller receives HTTP 403 with body {\"status\":\"error\",\"message\":\"Forbidden\"}" - - "A PATCH on a non-existent report ID returns HTTP 404" - - "restaurantId cannot be changed via PATCH — the field is ignored even if present in the request body" - artifacts: - - path: "src/main/java/com/aflokkat/controller/ReportController.java" - provides: "PATCH /api/reports/{id} endpoint added to existing controller" - contains: "patchReport" - - path: "src/test/java/com/aflokkat/controller/ReportControllerTest.java" - provides: "patchReport_* tests GREEN" - contains: "patchReport_updatesOwnedReport" - key_links: - - from: "ReportController.patchReport()" - to: "reportRepository.findById(id)" - via: "@PathVariable Long id" - pattern: "reportRepository\\.findById" - - from: "ownership check" - to: "ResponseEntity.status(HttpStatus.FORBIDDEN)" - via: "report.getUser().getId() != currentUser.getId()" - pattern: "FORBIDDEN" - - from: "partial update" - to: "reportRepository.save(report)" - via: "if (req.getX() != null) entity.setX(req.getX())" - pattern: "req\\.get.*!= null" ---- - - -Add PATCH /api/reports/{id} to the existing ReportController and fill the patchReport_* test methods. - -Purpose: CTRL-03 — a controller must be able to edit their own report, and a non-owner must be blocked with HTTP 403. -Output: PATCH endpoint with ownership check; partial update (null fields unchanged); patchReport_* tests GREEN. - - - -@/home/missia03/.claude/get-shit-done/workflows/execute-plan.md -@/home/missia03/.claude/get-shit-done/templates/summary.md - - - -@.planning/PROJECT.md -@.planning/ROADMAP.md -@.planning/phases/02-controller-reports/02-CONTEXT.md -@.planning/phases/02-controller-reports/02-RESEARCH.md -@.planning/phases/02-controller-reports/02-01-SUMMARY.md - - - - -From src/main/java/com/aflokkat/controller/ReportController.java (plan 01 output): -- getCurrentUser() private helper — returns UserEntity from SecurityContextHolder -- toResponseMap(InspectionReportEntity) private helper — returns Map with enriched fields -- @Autowired ReportRepository reportRepository -- @Autowired RestaurantDAO restaurantDAO -- @Autowired UserRepository userRepository -- @PostMapping createReport(@RequestBody ReportRequest req) -- @GetMapping listReports(@RequestParam Status status) - -From src/main/java/com/aflokkat/dto/ReportRequest.java (plan 01 output): -```java -public class ReportRequest { - private String restaurantId; // ignored by PATCH - private Grade grade; // null = leave unchanged - private Status status; // null = leave unchanged - private String violationCodes; // null = leave unchanged - private String notes; // null = leave unchanged -} -``` - -From src/main/java/com/aflokkat/entity/InspectionReportEntity.java (plan 01 output): -```java -// All setters: -void setGrade(Grade grade); -void setStatus(Status status); -void setViolationCodes(String v); -void setNotes(String notes); -void setUpdatedAt(Date d); -// Lazy FK: -UserEntity getUser(); // FetchType.LAZY — access inside @Transactional only -Long getId(); -``` - -Ownership check pattern (from RESEARCH.md — do NOT throw for 403): -```java -if (!report.getUser().getId().equals(currentUser.getId())) { - Map body = new HashMap<>(); - body.put("status", "error"); - body.put("message", "Forbidden"); - return ResponseEntity.status(HttpStatus.FORBIDDEN).body(body); -} -``` - -Partial update pattern (from RESEARCH.md): -```java -if (req.getGrade() != null) { report.setGrade(req.getGrade()); } -if (req.getStatus() != null) { report.setStatus(req.getStatus()); } -if (req.getViolationCodes() != null) { report.setViolationCodes(req.getViolationCodes()); } -if (req.getNotes() != null) { report.setNotes(req.getNotes()); } -report.setUpdatedAt(new Date()); -reportRepository.save(report); -``` - -WARNING — LazyInitializationException: -report.getUser() is FetchType.LAZY. Calling getUser().getId() in the ownership check -will throw LazyInitializationException if there is no active Hibernate session. -Fix: annotate patchReport() with @Transactional so the session stays open for the -duration of the method call. - - - - - - - Task 1: PATCH /api/reports/{id} endpoint + patchReport_* tests GREEN - - src/main/java/com/aflokkat/controller/ReportController.java, - src/test/java/com/aflokkat/controller/ReportControllerTest.java - - - - src/main/java/com/aflokkat/controller/ReportController.java (read the FULL file as produced by Plan 01 — add patchReport() without breaking POST and GET) - - src/test/java/com/aflokkat/controller/ReportControllerTest.java (read the FULL file — replace abort() stubs in patchReport_* methods with real assertions) - - src/main/java/com/aflokkat/entity/InspectionReportEntity.java (confirm getUser() is FetchType.LAZY before deciding @Transactional scope) - - src/main/java/com/aflokkat/util/ResponseUtil.java (errorResponse signature — do NOT use it for 403; build the map manually) - - - - patchReport_updatesOwnedReport_andReturns200: mock findById(1L) returns entity owned by user 42L; mock getCurrentUser() returns user with id=42L; PATCH body {grade: B, status: IN_PROGRESS} → verify setGrade(B) and setStatus(IN_PROGRESS) called on entity; verify reportRepository.save() called; response HTTP 200 with {"status":"success","data":{...}} - - patchReport_returns403_whenNotOwner: entity owned by user 99L; getCurrentUser() returns user 42L → response HTTP 403 with {"status":"error","message":"Forbidden"}; reportRepository.save() NEVER called - - patchReport_appliesOnlyNonNullFields_leavingOthersUnchanged: PATCH body {grade: C, status: null, notes: null, violationCodes: "10F"} → verify setGrade(C) called; verify setStatus() NOT called; verify setNotes() NOT called; verify setViolationCodes("10F") called - - - RED phase: fill the three patchReport_* test methods in ReportControllerTest.java with real assertions. Run `mvn test -Dtest=ReportControllerTest#patchReport*` — tests must FAIL (method patchReport not yet on controller). - - GREEN phase: add the patchReport() method to the existing ReportController.java class. Add it after the listReports() method. - - ```java - // ── PATCH /api/reports/{id} ──────────────────────────────────────────────── - @PatchMapping("/{id}") - @Transactional - public ResponseEntity> patchReport( - @PathVariable Long id, - @RequestBody ReportRequest req) { - try { - UserEntity currentUser = getCurrentUser(); - InspectionReportEntity report = reportRepository.findById(id) - .orElseThrow(() -> new IllegalArgumentException("Report not found")); - - // Ownership check — build 403 response manually (do NOT throw) - if (!report.getUser().getId().equals(currentUser.getId())) { - Map body = new HashMap<>(); - body.put("status", "error"); - body.put("message", "Forbidden"); - return ResponseEntity.status(HttpStatus.FORBIDDEN).body(body); - } - - // Partial update — only apply non-null fields - if (req.getGrade() != null) { report.setGrade(req.getGrade()); } - if (req.getStatus() != null) { report.setStatus(req.getStatus()); } - if (req.getViolationCodes() != null) { report.setViolationCodes(req.getViolationCodes()); } - if (req.getNotes() != null) { report.setNotes(req.getNotes()); } - report.setUpdatedAt(new Date()); - reportRepository.save(report); - - Map response = new HashMap<>(); - response.put("status", "success"); - response.put("data", toResponseMap(report)); - return ResponseEntity.ok(response); - } catch (Exception e) { - return ResponseUtil.errorResponse(e); - } - } - ``` - - Required imports to add to ReportController.java (if not already present): - - org.springframework.web.bind.annotation.PatchMapping - - Critical rules: - - @Transactional is MANDATORY on patchReport() — report.getUser().getId() is a lazy proxy access - - NEVER throw an exception for the 403 case — ResponseUtil.errorResponse() maps IllegalArgumentException to 400, not 403 - - Do not apply req.getRestaurantId() — restaurantId is immutable after creation; silently ignore it - - "Report not found" → IllegalArgumentException → ResponseUtil.errorResponse() → HTTP 400 is acceptable for academic scope; alternatively return ResponseEntity.notFound() explicitly - - - cd /home/missia03/Aflokkat/big_data/quickstart-app && mvn test -Dtest=ReportControllerTest#patchReport* -pl . 2>&1 | tail -20 - - - - patchReport() method exists in ReportController.java with @PatchMapping("/{id}") and @Transactional. - - mvn test -Dtest=ReportControllerTest#patchReport* runs 3 tests; all pass (GREEN). - - mvn test -Dtest=ReportControllerTest runs all 12 tests: 6 GREEN (createReport + listReports + patchReport), 6 abort (photoUpload). - - grep "FORBIDDEN" src/main/java/com/aflokkat/controller/ReportController.java returns a match. - - grep "getUser().getId()" src/main/java/com/aflokkat/controller/ReportController.java returns a match. - - - - - - -After task completes: -- mvn test -Dtest=ReportControllerTest shows 9 tests passing (createReport + listReports + patchReport), 3 aborting (photoUpload) -- mvn test (full suite) produces BUILD SUCCESS — no Phase 1 regressions -- grep "@PatchMapping" src/main/java/com/aflokkat/controller/ReportController.java returns a match -- grep "FORBIDDEN" src/main/java/com/aflokkat/controller/ReportController.java returns a match confirming manual 403 response (not thrown exception) - - - -- PATCH /api/reports/{id} with owned report applies only non-null fields and returns HTTP 200 with enriched data -- PATCH by non-owner returns HTTP 403 {"status":"error","message":"Forbidden"} -- PATCH with non-existent ID returns HTTP 400 (IllegalArgumentException → ResponseUtil) -- patchReport_* unit tests all GREEN; no Phase 1 regressions - - - -After completion, create `.planning/phases/02-controller-reports/02-02-SUMMARY.md` - diff --git a/.planning/phases/02-controller-reports/02-02-SUMMARY.md b/.planning/phases/02-controller-reports/02-02-SUMMARY.md deleted file mode 100644 index e10c403..0000000 --- a/.planning/phases/02-controller-reports/02-02-SUMMARY.md +++ /dev/null @@ -1,122 +0,0 @@ ---- -phase: 02-controller-reports -plan: "02" -subsystem: api -tags: [java, spring-boot, jpa, mockito, patch, ownership-check, tdd] - -# Dependency graph -requires: - - phase: 02-controller-reports/02-01 - provides: ReportController with POST/GET endpoints, InspectionReportEntity with FetchType.LAZY user, ReportRequest DTO, Grade/Status enums -provides: - - PATCH /api/reports/{id} endpoint with partial update and ownership check - - patchReport_* unit tests GREEN (9 total pass in ReportControllerTest) -affects: - - 02-03 (photo upload — builds on same ReportController) - - 02-04 (customer UI — references report data shape) - -# Tech tracking -tech-stack: - added: [] - patterns: - - "Manual 403 response map to avoid ResponseUtil.errorResponse() returning 400 for security errors" - - "ArgumentCaptor for partial-update assertion instead of spy() (Byte Buddy cannot instrument JPA entities on Java 25)" - - "assumeTrue(false) for stub tests (JUnit 5.8.2 — abort(String) unavailable)" - -key-files: - created: [] - modified: - - src/main/java/com/aflokkat/controller/ReportController.java - - src/test/java/com/aflokkat/controller/ReportControllerTest.java - -key-decisions: - - "spy() on JPA entity fails on Java 25 — use ArgumentCaptor on reportRepository.save() to verify partial-update behavior" - - "Manual 403 body map returned directly — do NOT use ResponseUtil.errorResponse() which maps all exceptions to 400/500" - -patterns-established: - - "Ownership-guard pattern: findById → check owner id → return 403 map directly if mismatch" - - "Partial-update pattern: null-guard each field before setter call; ignore immutable fields like restaurantId" - -requirements-completed: [CTRL-03] - -# Metrics -duration: 8min -completed: 2026-03-30 ---- - -# Phase 02 Plan 02: PATCH /api/reports/{id} Summary - -**PATCH endpoint on ReportController with ownership check (HTTP 403 map) and partial update (null fields preserved), with 3 patchReport unit tests GREEN via ArgumentCaptor** - -## Performance - -- **Duration:** 8 min -- **Started:** 2026-03-30T13:26:09Z -- **Completed:** 2026-03-30T13:34:00Z -- **Tasks:** 1 -- **Files modified:** 2 - -## Accomplishments -- Added `patchReport()` to `ReportController` with `@PatchMapping("/{id}")` and `@Transactional` -- Ownership check returns HTTP 403 via manually constructed response map (not thrown exception) -- Partial update applies only non-null request fields; `restaurantId` silently ignored -- Replaced 3 `assumeTrue(false)` stubs in `ReportControllerTest` with real assertions, all GREEN -- No regressions: 9 tests pass in `ReportControllerTest`, 3 `photoUpload_*` stubs still skipped - -## Task Commits - -Each task was committed atomically: - -1. **Task 1: PATCH /api/reports/{id} endpoint + patchReport_* tests GREEN** - `39c923b` (feat) - -**Plan metadata:** (to be added) - -_Note: TDD tasks may have multiple commits (test → feat → refactor). RED-phase fix (spy to ArgumentCaptor) was folded into the single task commit._ - -## Files Created/Modified -- `src/main/java/com/aflokkat/controller/ReportController.java` - Added `patchReport()` method after `listReports()` -- `src/test/java/com/aflokkat/controller/ReportControllerTest.java` - Replaced 3 stub methods with real assertions - -## Decisions Made -- **spy() incompatible with Java 25 + Byte Buddy:** `spy(InspectionReportEntity)` threw `MockitoException: Could not modify all classes`. Used `ArgumentCaptor` on `reportRepository.save()` to capture the saved entity and assert its field values directly. No change to production code needed. -- **Manual 403 response map:** `ResponseUtil.errorResponse()` maps `IllegalArgumentException` to 400 and anything else to 500 — it cannot produce 403. The plan already specified building the map manually; confirmed and followed. - -## Deviations from Plan - -### Auto-fixed Issues - -**1. [Rule 1 - Bug] Replaced spy() with ArgumentCaptor for partial-update test** -- **Found during:** Task 1 RED phase (patchReport_appliesOnlyNonNullFields_leavingOthersUnchanged) -- **Issue:** `spy(InspectionReportEntity.class)` throws `MockitoException: Could not modify all classes` on Java 25 — Byte Buddy cannot instrument JPA entity classes in the inline mock setup used by this project (same root cause as Phase 01-02 issue). -- **Fix:** Replaced `spy(entity)` pattern with `ArgumentCaptor.forClass(InspectionReportEntity.class)`, capturing the argument passed to `reportRepository.save()` and asserting field values directly via `assertEquals`/`assertNull`. -- **Files modified:** `src/test/java/com/aflokkat/controller/ReportControllerTest.java` -- **Verification:** Test passes (GREEN) without spy; all 3 patchReport tests pass. -- **Committed in:** `39c923b` (Task 1 commit) - ---- - -**Total deviations:** 1 auto-fixed (Rule 1 - Bug) -**Impact on plan:** Test correctness preserved with equivalent behavior verification. No scope creep. No production code affected. - -## Issues Encountered -- Byte Buddy / Java 25 incompatibility with `spy()` on JPA entities — resolved via ArgumentCaptor pattern (consistent with Phase 01-02 known issue with Mockito on this JVM). - -## User Setup Required -None - no external service configuration required. - -## Next Phase Readiness -- `ReportController` now has POST, GET, and PATCH endpoints fully implemented and tested -- Ready for Plan 02-03: photo upload endpoint (`POST /api/reports/{id}/photo` and `GET /api/reports/{id}/photo`) -- Named Docker volume for `uploads_data` must be present in `docker-compose.yml` before photo upload tests run (pre-existing blocker noted in STATE.md) - ---- -*Phase: 02-controller-reports* -*Completed: 2026-03-30* - -## Self-Check: PASSED - -- FOUND: `src/main/java/com/aflokkat/controller/ReportController.java` -- FOUND: `src/test/java/com/aflokkat/controller/ReportControllerTest.java` -- FOUND: `.planning/phases/02-controller-reports/02-02-SUMMARY.md` -- FOUND: commit `39c923b` (feat: PATCH endpoint + tests) -- FOUND: commit `4dc907d` (docs: plan metadata) diff --git a/.planning/phases/02-controller-reports/02-03-PLAN.md b/.planning/phases/02-controller-reports/02-03-PLAN.md deleted file mode 100644 index 7a7d9c2..0000000 --- a/.planning/phases/02-controller-reports/02-03-PLAN.md +++ /dev/null @@ -1,418 +0,0 @@ ---- -phase: 02-controller-reports -plan: "03" -type: execute -wave: 3 -depends_on: ["02-01", "02-02"] -files_modified: - - src/main/java/com/aflokkat/controller/ReportController.java - - src/main/java/com/aflokkat/config/AppConfig.java - - src/main/resources/application.properties - - docker-compose.yml - - src/test/java/com/aflokkat/controller/ReportControllerTest.java -autonomous: false -requirements: [CTRL-04] - -must_haves: - truths: - - "A controller can POST multipart/form-data to /api/reports/{id}/photo and the file is saved to {uploadsDir}/{reportId}/{timestamp}_{originalFilename}" - - "After upload, the photoPath field on the report entity is updated to the absolute disk path, and subsequent GET /api/reports responses return the photo URL as /api/reports/{id}/photo" - - "GET /api/reports/{id}/photo streams the file bytes back with the correct Content-Type header (image/jpeg for JPEG files)" - - "A second upload to the same report overwrites the first (REPLACE_EXISTING)" - - "Photos survive docker compose down && docker compose up because /app/uploads is mounted as the named volume uploads_data" - artifacts: - - path: "src/main/java/com/aflokkat/controller/ReportController.java" - provides: "POST /{id}/photo and GET /{id}/photo endpoints" - contains: "uploadPhoto" - - path: "src/main/java/com/aflokkat/config/AppConfig.java" - provides: "getUploadsDir() static method" - contains: "getUploadsDir" - - path: "src/main/resources/application.properties" - provides: "app.uploads.dir property" - contains: "app.uploads.dir" - - path: "docker-compose.yml" - provides: "uploads_data volume mount on app service and top-level volume declaration" - contains: "uploads_data" - key_links: - - from: "ReportController.uploadPhoto()" - to: "AppConfig.getUploadsDir()" - via: "String uploadsDir = AppConfig.getUploadsDir()" - pattern: "AppConfig\\.getUploadsDir" - - from: "uploadPhoto()" - to: "Files.createDirectories(targetDir)" - via: "Paths.get(uploadsDir, String.valueOf(reportId))" - pattern: "createDirectories" - - from: "uploadPhoto()" - to: "reportRepository.save(report)" - via: "report.setPhotoPath(targetPath.toString())" - pattern: "setPhotoPath" - - from: "getPhoto()" - to: "UrlResource(filePath.toUri())" - via: "report.getPhotoPath()" - pattern: "UrlResource" - - from: "docker-compose.yml app service" - to: "top-level volumes: uploads_data:" - via: "volumes: - uploads_data:/app/uploads" - pattern: "uploads_data" - -user_setup: - - service: docker - why: "Manual verification that photos survive container restart" - dashboard_config: - - task: "After plan executes: POST a photo, then run docker compose down && docker compose up -d, then GET /api/reports/{id}/photo — must return 200 with file bytes" - location: "Terminal — requires running Docker stack" ---- - - -Add photo upload and streaming endpoints to ReportController, add AppConfig.getUploadsDir(), update application.properties with app.uploads.dir property, and wire the uploads_data named Docker volume in docker-compose.yml. - -Purpose: CTRL-04 — a controller must be able to attach a photo to a report and retrieve it; photos must survive container restarts. -Output: POST /api/reports/{id}/photo saves file; GET /api/reports/{id}/photo streams it; Docker volume persists files; photoUpload_* tests GREEN; one manual checkpoint verifies persistence across compose restart. - - - -@/home/missia03/.claude/get-shit-done/workflows/execute-plan.md -@/home/missia03/.claude/get-shit-done/templates/summary.md - - - -@.planning/PROJECT.md -@.planning/ROADMAP.md -@.planning/phases/02-controller-reports/02-CONTEXT.md -@.planning/phases/02-controller-reports/02-RESEARCH.md -@.planning/phases/02-controller-reports/02-01-SUMMARY.md -@.planning/phases/02-controller-reports/02-02-SUMMARY.md - - - - -From src/main/java/com/aflokkat/controller/ReportController.java (plans 01+02 output): -- All existing methods: getCurrentUser(), toResponseMap(), createReport(), listReports(), patchReport() -- @Autowired ReportRepository reportRepository (use to load entity before uploading) -- @Autowired UserRepository userRepository (used by getCurrentUser) - -From src/main/java/com/aflokkat/config/AppConfig.java (existing pattern to follow): -```java -// Existing pattern for static getter: -public static String getRedisHost() { - return getProperty("redis.host", "localhost"); -} -// getProperty() resolves: System env (APP_UPLOADS_DIR) > .env > application.properties > default -// env key derived by: key.replace(".", "_").toUpperCase() -// So "app.uploads.dir" resolves from env var "APP_UPLOADS_DIR" -``` - -File upload pattern (from RESEARCH.md): -```java -String uploadsDir = AppConfig.getUploadsDir(); -Path targetDir = Paths.get(uploadsDir, String.valueOf(reportId)); -Files.createDirectories(targetDir); // idempotent — safe to call even if dir exists -String filename = System.currentTimeMillis() + "_" + file.getOriginalFilename(); -Path targetPath = targetDir.resolve(filename); -Files.copy(file.getInputStream(), targetPath, StandardCopyOption.REPLACE_EXISTING); -report.setPhotoPath(targetPath.toString()); -report.setUpdatedAt(new Date()); -reportRepository.save(report); -``` - -Photo streaming pattern (from RESEARCH.md): -```java -Path filePath = Paths.get(report.getPhotoPath()); -Resource resource = new UrlResource(filePath.toUri()); -if (!resource.exists()) { - return ResponseEntity.notFound().build(); -} -String contentType = Files.probeContentType(filePath); // java.nio.file.Files -return ResponseEntity.ok() - .contentType(MediaType.parseMediaType( - contentType != null ? contentType : "application/octet-stream")) - .body(resource); -``` - -Docker volume pitfall (from RESEARCH.md): -- Named volumes MUST appear under both services.app.volumes AND top-level volumes: - ```yaml - services: - app: - volumes: - - uploads_data:/app/uploads # ADD this line - volumes: - uploads_data: # ADD this declaration - ``` -- Failing to declare uploads_data at top level → docker compose up fails with "undefined volume" - -WARNING — getPhoto() return type conflict: -The existing methods return ResponseEntity>. -getPhoto() must return ResponseEntity. -These are different generic types — use raw ResponseEntity or separate the method signature: -```java -@GetMapping("/{id}/photo") -public ResponseEntity getPhoto(@PathVariable Long id) { ... } -``` -This is valid — Spring MVC allows different return types per handler method. - -Required imports for new endpoints: -- org.springframework.core.io.Resource -- org.springframework.core.io.UrlResource -- org.springframework.web.multipart.MultipartFile -- org.springframework.http.MediaType -- java.nio.file.Files -- java.nio.file.Path -- java.nio.file.Paths -- java.nio.file.StandardCopyOption - - - - - - - Task 1: AppConfig.getUploadsDir() + application.properties + docker-compose.yml volume - - src/main/java/com/aflokkat/config/AppConfig.java, - src/main/resources/application.properties, - docker-compose.yml - - - - src/main/java/com/aflokkat/config/AppConfig.java (read the FULL file — add getUploadsDir() after getControllerSignupCode(), following the exact same static getter pattern) - - src/main/resources/application.properties (read the FULL file — append app.uploads.dir without disrupting existing properties) - - docker-compose.yml (read the FULL file — add volume mount to app service and declare uploads_data at top-level volumes block) - - - - AppConfig.getUploadsDir() returns "/app/uploads" when APP_UPLOADS_DIR env var is not set - - AppConfig.getUploadsDir() returns "/custom/path" when APP_UPLOADS_DIR=/custom/path is set (follows existing getProperty resolution order) - - docker-compose.yml app service has volumes entry "uploads_data:/app/uploads" - - docker-compose.yml top-level volumes block includes "uploads_data:" alongside mongodb_data and postgres_data - - application.properties contains "app.uploads.dir=/app/uploads" - - - 1. In src/main/java/com/aflokkat/config/AppConfig.java, add the following static method after getControllerSignupCode(): - ```java - public static String getUploadsDir() { - return getProperty("app.uploads.dir", "/app/uploads"); - } - ``` - The existing getProperty() mechanism will resolve it from APP_UPLOADS_DIR env var first (Docker), then .env, then application.properties. - - 2. In src/main/resources/application.properties, append at the end (after the rate-limit section): - ```properties - # Photo uploads (Phase 2) - # ENV: APP_UPLOADS_DIR - app.uploads.dir=/app/uploads - ``` - - 3. In docker-compose.yml, make two edits: - a. Add a volumes section to the app service (after the depends_on block, same indentation as other service-level keys): - ```yaml - volumes: - - uploads_data:/app/uploads - ``` - b. Add uploads_data to the top-level volumes block: - ```yaml - volumes: - mongodb_data: - postgres_data: - uploads_data: - ``` - Also add APP_UPLOADS_DIR to the app service environment block: - ```yaml - environment: - MONGODB_URI: mongodb://mongodb:27017 - MONGODB_DATABASE: newyork - MONGODB_COLLECTION: restaurants - REDIS_HOST: redis - REDIS_PORT: 6379 - APP_UPLOADS_DIR: /app/uploads - ``` - - - cd /home/missia03/Aflokkat/big_data/quickstart-app && grep -n "getUploadsDir\|app\.uploads\.dir\|uploads_data" src/main/java/com/aflokkat/config/AppConfig.java src/main/resources/application.properties docker-compose.yml - - - - grep "getUploadsDir" src/main/java/com/aflokkat/config/AppConfig.java returns a match. - - grep "app.uploads.dir" src/main/resources/application.properties returns a match. - - grep "uploads_data" docker-compose.yml returns at least 2 matches (volumes mount + top-level declaration). - - grep "APP_UPLOADS_DIR" docker-compose.yml returns a match. - - mvn compile produces BUILD SUCCESS (AppConfig compiles correctly). - - - - - Task 2: POST /{id}/photo and GET /{id}/photo endpoints + photoUpload_* tests GREEN - - src/main/java/com/aflokkat/controller/ReportController.java, - src/test/java/com/aflokkat/controller/ReportControllerTest.java - - - - src/main/java/com/aflokkat/controller/ReportController.java (read the FULL file as produced by Plans 01+02 — add upload/stream methods without breaking existing endpoints) - - src/test/java/com/aflokkat/controller/ReportControllerTest.java (read the FULL file — replace abort() stubs in photoUpload_* methods with real assertions) - - src/main/java/com/aflokkat/config/AppConfig.java (confirm getUploadsDir() exists after Task 1) - - src/main/java/com/aflokkat/entity/InspectionReportEntity.java (confirm setPhotoPath() and getPhotoPath() exist) - - - - photoUpload_savesFileAndUpdatesPhotoPath: mock findById(1L) returns entity owned by user 42L; mock multipart file with originalFilename="test.jpg" and content bytes; verify Files.createDirectories called; verify setPhotoPath() called with a path containing "/1/" and "test.jpg"; verify reportRepository.save() called; response HTTP 200 {"status":"success","data":{...}} - - photoUpload_returns404_whenReportNotFound: mock findById(99L) returns Optional.empty() → HTTP 404 (or 400 via IllegalArgumentException — document which you choose) - - getPhoto_streamsFileWithCorrectContentType: mock findById(1L) returns entity with photoPath set to a temp file path; GET /{id}/photo → response HTTP 200; Content-Type header matches file MIME type - NOTE: photoUpload tests that touch the real filesystem should use a temp directory (Files.createTempDirectory()) rather than /app/uploads to keep tests hermetic. - - - RED phase: fill the three photoUpload_* test methods in ReportControllerTest.java. For file system operations in tests, mock AppConfig.getUploadsDir() to return a temp directory path. Run `mvn test -Dtest=ReportControllerTest#photoUpload*+getPhoto*` — tests must FAIL (methods not yet on controller). - - GREEN phase: add the two photo endpoints to the existing ReportController.java class. Add them after patchReport(). Add all required imports at the top of the file. - - ```java - // ── POST /api/reports/{id}/photo ────────────────────────────────────────── - @PostMapping(value = "/{id}/photo", consumes = MediaType.MULTIPART_FORM_DATA_VALUE) - @Transactional - public ResponseEntity> uploadPhoto( - @PathVariable Long id, - @RequestParam("file") MultipartFile file) { - try { - UserEntity currentUser = getCurrentUser(); - InspectionReportEntity report = reportRepository.findById(id) - .orElseThrow(() -> new IllegalArgumentException("Report not found")); - - // Ownership check - if (!report.getUser().getId().equals(currentUser.getId())) { - Map body = new HashMap<>(); - body.put("status", "error"); - body.put("message", "Forbidden"); - return ResponseEntity.status(HttpStatus.FORBIDDEN).body(body); - } - - // Save file to {uploadsDir}/{reportId}/{timestamp}_{originalFilename} - String uploadsDir = AppConfig.getUploadsDir(); - Path targetDir = Paths.get(uploadsDir, String.valueOf(id)); - Files.createDirectories(targetDir); // idempotent - String filename = System.currentTimeMillis() + "_" + file.getOriginalFilename(); - Path targetPath = targetDir.resolve(filename); - Files.copy(file.getInputStream(), targetPath, StandardCopyOption.REPLACE_EXISTING); - - // Update entity - report.setPhotoPath(targetPath.toString()); - report.setUpdatedAt(new Date()); - reportRepository.save(report); - - Map response = new HashMap<>(); - response.put("status", "success"); - response.put("data", toResponseMap(report)); - return ResponseEntity.ok(response); - } catch (Exception e) { - return ResponseUtil.errorResponse(e); - } - } - - // ── GET /api/reports/{id}/photo ─────────────────────────────────────────── - @GetMapping("/{id}/photo") - @Transactional - public ResponseEntity getPhoto(@PathVariable Long id) { - try { - InspectionReportEntity report = reportRepository.findById(id) - .orElseThrow(() -> new IllegalArgumentException("Report not found")); - - if (report.getPhotoPath() == null) { - return ResponseEntity.notFound().build(); - } - - Path filePath = Paths.get(report.getPhotoPath()); - Resource resource = new UrlResource(filePath.toUri()); - if (!resource.exists()) { - return ResponseEntity.notFound().build(); - } - - String contentType = Files.probeContentType(filePath); - return ResponseEntity.ok() - .contentType(MediaType.parseMediaType( - contentType != null ? contentType : "application/octet-stream")) - .body(resource); - } catch (Exception e) { - // Return 404 for file not found, fallback 500 for unexpected errors - return ResponseEntity.notFound().build(); - } - } - ``` - - Add these imports to ReportController.java (append to existing import block): - ```java - import org.springframework.core.io.Resource; - import org.springframework.core.io.UrlResource; - import org.springframework.web.multipart.MultipartFile; - import java.nio.file.Files; - import java.nio.file.Path; - import java.nio.file.Paths; - import java.nio.file.StandardCopyOption; - ``` - - Critical rules: - - @Transactional on uploadPhoto() — ownership check calls report.getUser().getId() (lazy) - - @Transactional on getPhoto() — getPhotoPath() reads entity field which may need session - - Files.createDirectories() before Files.copy() — Docker volume only pre-creates the root directory, NOT subdirectories - - REPLACE_EXISTING in Files.copy() — second upload overwrites the first (per locked decision) - - Return ResponseEntity (not >) for getPhoto() — this is the only endpoint with a different return type - - getPhoto() 403 is NOT needed — SecurityConfig already blocks non-CONTROLLER access at the URL level - - - cd /home/missia03/Aflokkat/big_data/quickstart-app && mvn test -Dtest=ReportControllerTest -pl . 2>&1 | tail -30 - - - - uploadPhoto() and getPhoto() methods exist in ReportController.java. - - mvn test -Dtest=ReportControllerTest runs all 12 tests; all 12 pass (GREEN) — no aborted stubs remain. - - mvn test (full suite) produces BUILD SUCCESS — no Phase 1 regressions. - - grep "uploadPhoto\|getPhoto\|UrlResource" src/main/java/com/aflokkat/controller/ReportController.java returns matches. - - grep "createDirectories" src/main/java/com/aflokkat/controller/ReportController.java returns a match. - - - - - Task 3: Human checkpoint — photo persistence across docker compose restart (CTRL-04) - - All four Phase 2 endpoints are now complete: - - POST /api/reports (CTRL-01) - - GET /api/reports (CTRL-02) - - PATCH /api/reports/{id} (CTRL-03) - - POST /api/reports/{id}/photo and GET /api/reports/{id}/photo (CTRL-04) - Photos are wired to the uploads_data Docker named volume. - - - Manual verification for CTRL-04 photo persistence (cannot be automated — requires live Docker): - - 1. Start the stack: `docker compose up -d` - 2. Login as controller_test: `curl -s -X POST http://localhost:8080/api/auth/login -H "Content-Type: application/json" -d '{"username":"controller_test","password":"Test1234!"}' | jq '.accessToken'` - 3. Create a report (replace TOKEN): `curl -s -X POST http://localhost:8080/api/reports -H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" -d '{"restaurantId":"some-id","grade":"A","status":"OPEN"}' | jq '.data.id'` - 4. Upload a photo (replace TOKEN and REPORT_ID): `curl -s -X POST http://localhost:8080/api/reports/REPORT_ID/photo -H "Authorization: Bearer TOKEN" -F "file=@/path/to/any/image.jpg"` — expect HTTP 200 {"status":"success"} - 5. Verify photo is accessible before restart: `curl -I -H "Authorization: Bearer TOKEN" http://localhost:8080/api/reports/REPORT_ID/photo` — expect HTTP 200 with Content-Type: image/jpeg - 6. Stop and restart: `docker compose down && docker compose up -d` - 7. Re-login (JWT expires — need new token), then repeat step 5. - 8. Verify photo is still accessible: HTTP 200 — this confirms the named volume is working. - - Type "approved" if photo persists across restart, or describe any issues found - docker-compose.yml - Human verifies photo persistence manually — see how-to-verify steps above. No automated action. - Human confirmation via resume-signal - Photo accessible via GET /api/reports/{id}/photo after docker compose down && docker compose up -d - - - - - -After all tasks complete: -- mvn test -Dtest=ReportControllerTest shows all 12 tests GREEN -- mvn test (full suite) produces BUILD SUCCESS -- grep "uploads_data" docker-compose.yml returns 2+ matches (service volumes + top-level volumes) -- grep "getUploadsDir" src/main/java/com/aflokkat/config/AppConfig.java returns a match -- grep "app.uploads.dir" src/main/resources/application.properties returns a match -- grep "UrlResource" src/main/java/com/aflokkat/controller/ReportController.java returns a match -- Human checkpoint: photo accessible before and after docker compose down && up - - - -- POST /api/reports/{id}/photo saves file to {uploadsDir}/{reportId}/{timestamp}_{filename} with correct directory creation -- GET /api/reports/{id}/photo streams bytes back with correct Content-Type header -- Second upload overwrites the first (REPLACE_EXISTING) -- Docker volume uploads_data declared and mounted — photos survive container restart -- All 12 ReportControllerTest tests GREEN -- Full Phase 2 success criteria met: CTRL-01, CTRL-02, CTRL-03, CTRL-04 all implemented - - - -After completion, create `.planning/phases/02-controller-reports/02-03-SUMMARY.md` - diff --git a/.planning/phases/02-controller-reports/02-03-SUMMARY.md b/.planning/phases/02-controller-reports/02-03-SUMMARY.md deleted file mode 100644 index fbb00f6..0000000 --- a/.planning/phases/02-controller-reports/02-03-SUMMARY.md +++ /dev/null @@ -1,151 +0,0 @@ ---- -phase: 02-controller-reports -plan: "03" -subsystem: api -tags: [spring-boot, multipart, file-upload, docker-volume, java] - -# Dependency graph -requires: - - phase: 02-controller-reports/02-01 - provides: ReportController, InspectionReportEntity with photoPath field, ReportRepository - - phase: 02-controller-reports/02-02 - provides: patchReport() endpoint, ownership check pattern -provides: - - POST /api/reports/{id}/photo — multipart file upload saved to named Docker volume - - GET /api/reports/{id}/photo — streams file bytes with probed Content-Type - - AppConfig.getUploadsDir() — static getter resolving APP_UPLOADS_DIR env var - - uploads_data named Docker volume wired in docker-compose.yml -affects: [02-controller-reports, phase-03-customer-ui] - -# Tech tracking -tech-stack: - added: [] - patterns: - - "MultipartFile upload: Files.createDirectories + Files.copy(REPLACE_EXISTING) to {uploadsDir}/{id}/{ts}_{filename}" - - "File streaming: UrlResource wrapping Path, ResponseEntity with probed Content-Type" - - "Static config override in tests: reflection on AppConfig.properties field (avoids mockStatic VerifyError on Java 25)" - -key-files: - created: [] - modified: - - src/main/java/com/aflokkat/config/AppConfig.java - - src/main/resources/application.properties - - docker-compose.yml - - src/main/java/com/aflokkat/controller/ReportController.java - - src/test/java/com/aflokkat/controller/ReportControllerTest.java - -key-decisions: - - "mockStatic(AppConfig.class) causes java.lang.VerifyError on Java 25 (Byte Buddy limitation); use reflection to patch AppConfig.properties static field in tests instead" - - "photoUpload_returns404_whenReportNotFound must stub userRepository.findByUsername() — controller calls getCurrentUser() before findById()" - -patterns-established: - - "Photo upload pattern: Files.createDirectories(targetDir) before Files.copy() — Docker volume only pre-creates root, not subdirectories" - - "getPhoto() returns ResponseEntity (not Map) — Spring MVC allows mixed return types per handler method" - -requirements-completed: [CTRL-04] - -# Metrics -duration: 20min + human checkpoint -completed: 2026-03-31 ---- - -# Phase 02 Plan 03: Photo Upload and Streaming Summary - -**POST /{id}/photo saves multipart files to uploads_data Docker named volume; GET /{id}/photo streams bytes with probed Content-Type; all 12 ReportControllerTest tests GREEN** - -## Performance - -- **Duration:** ~20 min -- **Started:** 2026-03-30T15:30:00Z -- **Completed:** 2026-03-30T15:43:30Z -- **Tasks:** 3 of 3 complete (Task 3 human checkpoint approved 2026-03-31) -- **Files modified:** 5 - -## Accomplishments -- `AppConfig.getUploadsDir()` added, resolving from `APP_UPLOADS_DIR` env var with `/app/uploads` default -- `uploads_data` named volume declared and mounted in `docker-compose.yml` — photos survive `docker compose down` -- `uploadPhoto()` and `getPhoto()` endpoints added to `ReportController`, completing CTRL-04 -- All 12 `ReportControllerTest` tests GREEN, no regressions in 63 unit tests - -## Task Commits - -Each task was committed atomically: - -1. **Task 1: AppConfig.getUploadsDir() + application.properties + docker-compose.yml volume** - `b188ad2` (feat) -2. **Task 2 RED: failing tests for photo upload endpoints** - `748d16e` (test) -3. **Task 2 GREEN: POST /{id}/photo and GET /{id}/photo endpoints** - `cc509a1` (feat) - -4. **Task 3: Human checkpoint — photo persistence across docker compose restart** - Approved 2026-03-31 (no code commit required; manual verification confirmed) - -_Note: Task 3 was a human-verify checkpoint. No code was committed for it — verification was performed manually._ - -## Files Created/Modified -- `src/main/java/com/aflokkat/config/AppConfig.java` - Added `getUploadsDir()` static method -- `src/main/resources/application.properties` - Added `app.uploads.dir=/app/uploads` property -- `docker-compose.yml` - Added `APP_UPLOADS_DIR` env var, `uploads_data:/app/uploads` volume mount on app service, top-level `uploads_data:` declaration -- `src/main/java/com/aflokkat/controller/ReportController.java` - Added `uploadPhoto()` and `getPhoto()` endpoints with required imports -- `src/test/java/com/aflokkat/controller/ReportControllerTest.java` - Replaced three `assumeTrue(false)` stubs with real test implementations - -## Decisions Made -- `mockStatic(AppConfig.class)` causes `java.lang.VerifyError` on Java 25 with Byte Buddy 1.16 — confirmed same class of issue as Phase 01-02 (agent attachment). Used reflection to patch the `AppConfig.properties` static `Properties` field in tests instead. This avoids `mockStatic` entirely while keeping tests hermetic via `@TempDir`. -- `photoUpload_returns404_whenReportNotFound` must stub `userRepository.findByUsername()` because the controller calls `getCurrentUser()` before `findById()` — without the stub, `IllegalArgumentException` is thrown early and `findById(99L)` is never reached, causing `UnnecessaryStubbingException` in strict mode. - -## Deviations from Plan - -### Auto-fixed Issues - -**1. [Rule 3 - Blocking] Replaced mockStatic with reflection-based AppConfig.properties override** -- **Found during:** Task 2 (RED phase — running failing tests) -- **Issue:** `mockStatic(AppConfig.class)` throws `java.lang.VerifyError` on Java 25 runtime (Byte Buddy bytecode instrumentation fails for static initializer classes) -- **Fix:** Added private `setUploadsDir(String path)` helper using reflection to set `AppConfig.properties.setProperty("app.uploads.dir", path)` — works because `System.getenv(APP_UPLOADS_DIR)` returns null in test JVM (no env override), so `getProperty()` falls through to the patched properties field -- **Files modified:** `src/test/java/com/aflokkat/controller/ReportControllerTest.java` -- **Verification:** 3 photo tests pass GREEN; no `VerifyError` -- **Committed in:** `748d16e` (test commit), `cc509a1` (feat commit) - -**2. [Rule 1 - Bug] Fixed UnnecessaryStubbingException in photoUpload_returns404_whenReportNotFound** -- **Found during:** Task 2 (GREEN phase — first test run) -- **Issue:** Test stubbed `findById(99L)` but never called it — controller calls `getCurrentUser()` first, which requires `userRepository.findByUsername()` stub; missing stub caused early exception, making `findById` stub unreachable -- **Fix:** Added `when(userRepository.findByUsername("ctrl_user")).thenReturn(Optional.of(user))` before the `findById` stub -- **Files modified:** `src/test/java/com/aflokkat/controller/ReportControllerTest.java` -- **Verification:** All 12 tests GREEN with no Mockito strict-stubbing violations -- **Committed in:** `cc509a1` (feat commit) - ---- - -**Total deviations:** 2 auto-fixed (1 Rule 3 blocking, 1 Rule 1 bug) -**Impact on plan:** Both fixes required for correct test execution. No scope creep. Production controller code matches plan specification exactly. - -## Issues Encountered -- Java 25 + Byte Buddy 1.16 limitation on `mockStatic` for classes with static initializers — resolved via reflection pattern (same family of issue as Phase 01-02 documented in STATE.md) - -## Human Checkpoint Result (Task 3) - -**CTRL-04 manual verification — approved 2026-03-31:** -- Photo uploaded via `POST /api/reports/1/photo` with a real PNG (148 390 bytes) -- `GET /api/reports/1/photo` before restart: HTTP 200, Content-Type: image/png, 148 390 bytes -- `docker compose down && docker compose up -d` -- `GET /api/reports/1/photo` after restart: HTTP 200, Content-Type: image/png, 148 390 bytes -- Volume `uploads_data:/app/uploads` confirmed working — file byte-for-byte identical across restart - -## User Setup Required -None - checkpoint complete. No further manual steps required. - -## Next Phase Readiness -- All four Phase 2 requirements satisfied: CTRL-01 (create), CTRL-02 (list), CTRL-03 (patch), CTRL-04 (photo) -- Phase 2 fully complete; ready for Phase 3: Customer Discovery (restaurant search, detail page, map UI) -- `uploads_data` named volume is permanent infrastructure — Phase 4 integration test for photo persistence can reference it directly - ---- -*Phase: 02-controller-reports* -*Completed: 2026-03-31* - -## Self-Check: PASSED -- AppConfig.java: FOUND -- ReportController.java: FOUND -- application.properties: FOUND -- docker-compose.yml: FOUND -- 02-03-SUMMARY.md: FOUND -- b188ad2 (Task 1 commit): FOUND -- 748d16e (Task 2 RED commit): FOUND -- cc509a1 (Task 2 GREEN commit): FOUND -- Task 3 (human checkpoint): APPROVED 2026-03-31 diff --git a/.planning/phases/02-controller-reports/02-CONTEXT.md b/.planning/phases/02-controller-reports/02-CONTEXT.md deleted file mode 100644 index 9ddfedb..0000000 --- a/.planning/phases/02-controller-reports/02-CONTEXT.md +++ /dev/null @@ -1,116 +0,0 @@ -# Phase 2: Controller Reports - Context - -**Gathered:** 2026-03-30 -**Status:** Ready for planning - - -## Phase Boundary - -Controllers can create, view, edit, and attach a photo to internal inspection reports scoped to a specific restaurant. Reports are stored in PostgreSQL (JPA). Customers cannot see these reports — they are internal only. Photo storage uses a local Docker volume. No external data is written to the NYC Open Data API. - - - - -## Implementation Decisions - -### Violation representation -- `violationCodes` stored as a comma-separated `TEXT` column (e.g. `"04L,10F,09C"`) on the report entity — no extra table -- `notes` stored as a separate free-text `TEXT` column for the controller's written observations -- Both fields are optional at creation, editable via PATCH -- `grade` stored as a Java enum `Grade {A, B, C, F}`, persisted with `@Enumerated(EnumType.STRING)` -- `status` stored as a Java enum `Status {OPEN, IN_PROGRESS, RESOLVED}`, persisted with `@Enumerated(EnumType.STRING)` - -### Photo storage and serving -- Photos saved to `/app/uploads/{reportId}/{filename}` inside the container -- `/app/uploads` is mounted as a named Docker volume so files survive `docker compose down && docker compose up` -- Upload path configurable via `app.uploads.dir` property (default `/app/uploads`) -- `GET /api/reports/{id}/photo` streams the file bytes back to the client (not a static resource URL) -- `photoPath` stored as a single `TEXT` column on the report entity — one photo per report in v1 -- A second upload overwrites the first (no history needed) - -### Report update method -- `PATCH /api/reports/{id}` — partial update; only fields present in the request body are updated, null fields are left unchanged -- Editable fields: `grade`, `status`, `violationCodes`, `notes` -- If the authenticated controller is not the report owner → HTTP 403 `{"status": "error", "message": "Forbidden"}` -- Restaurant link (`restaurantId`) cannot be changed after creation - -### List response enrichment -- `GET /api/reports` returns the authenticated controller's own reports only -- Each report in the list is enriched with `restaurantName` and `borough` fetched from MongoDB (same as POST response) -- Filter: `?status=OPEN|IN_PROGRESS|RESOLVED` (optional query param); no status param → return all reports for that controller -- Repository method: `findByUserId(Long userId)` and `findByUserIdAndStatus(Long userId, Status status)` — mirrors `BookmarkRepository` pattern - -### Claude's Discretion -- Exact `InspectionReportEntity` column names and nullable constraints (follow `BookmarkEntity` conventions) -- File naming on disk (timestamp + original filename is a safe default) -- `multipart/form-data` handling details for photo upload endpoint -- Exact Hibernate DDL for enums and text columns - - - - -## Canonical References - -**Downstream agents MUST read these before planning or implementing.** - -### Requirements -- `.planning/REQUIREMENTS.md` — CTRL-01 through CTRL-04 (all Phase 2 requirements) -- `.planning/ROADMAP.md` — Phase 2 goal and success criteria (4 success criteria define exact endpoint behavior) - -### Existing JPA layer (template for report entity + repo) -- `src/main/java/com/aflokkat/entity/BookmarkEntity.java` — `@ManyToOne(user)`, `@JoinColumn`, `@Column` patterns to replicate -- `src/main/java/com/aflokkat/repository/BookmarkRepository.java` — `findByUserId` pattern; `ReportRepository` must follow same conventions -- `src/main/java/com/aflokkat/entity/UserEntity.java` — `id` field type (Long) used in foreign key join - -### Existing controller pattern (template for ReportController) -- `src/main/java/com/aflokkat/controller/UserController.java` — `getCurrentUser()` helper, `ResponseUtil.errorResponse()`, response shape `{"status":"success","data":...}` -- `src/main/java/com/aflokkat/util/ResponseUtil.java` — reuse for all report error responses - -### Security config (verify ROLE_CONTROLLER guard is in place) -- `src/main/java/com/aflokkat/config/SecurityConfig.java` — `/api/reports/**` must require `ROLE_CONTROLLER` - -### Config pattern (for uploads.dir property) -- `src/main/java/com/aflokkat/config/AppConfig.java` — env var resolution pattern to follow for `APP_UPLOADS_DIR` - - - - -## Existing Code Insights - -### Reusable Assets -- `BookmarkEntity`: direct template — same `@ManyToOne(fetch = FetchType.LAZY)` + `@JoinColumn(name = "user_id")` pattern for `InspectionReportEntity` -- `BookmarkRepository.findByUserId(Long userId)`: exact pattern for `ReportRepository.findByUserId` and `findByUserIdAndStatus` -- `UserController.getCurrentUser()`: replicate this helper in `ReportController` to get the authenticated `UserEntity` -- `ResponseUtil.errorResponse(e)`: reuse in all catch blocks in `ReportController` - -### Established Patterns -- Response shape: `{"status": "success", "data": ..., "count": ...}` — keep consistent across all report endpoints -- Error shape: `{"status": "error", "message": "..."}` — used by `AuthController.errorResponse()` and `ResponseUtil` -- Spring JPA auto DDL: Hibernate creates tables on startup — no manual migration script needed for the new `inspection_reports` table - -### Integration Points -- `RestaurantDAO.findById(String id)` (or equivalent) — needed to enrich POST and GET responses with `restaurantName` + `borough` from MongoDB -- `UserRepository.findByUsername(String username)` — used by `getCurrentUser()` to load the `UserEntity` from the JWT principal -- `docker-compose.yml` — must add a named volume mount for `/app/uploads` and declare the volume - - - - -## Specific Ideas - -- No specific UI/UX references — this phase is pure REST API (no Thymeleaf templates) -- The photo streaming endpoint should set the correct `Content-Type` header based on the uploaded file's MIME type - - - - -## Deferred Ideas - -- None — discussion stayed within phase scope - - - ---- - -*Phase: 02-controller-reports* -*Context gathered: 2026-03-30* diff --git a/.planning/phases/02-controller-reports/02-RESEARCH.md b/.planning/phases/02-controller-reports/02-RESEARCH.md deleted file mode 100644 index 66ebc27..0000000 --- a/.planning/phases/02-controller-reports/02-RESEARCH.md +++ /dev/null @@ -1,596 +0,0 @@ -# Phase 2: Controller Reports - Research - -**Researched:** 2026-03-30 -**Domain:** Spring Boot JPA entity + REST CRUD + multipart file upload (no new libraries) -**Confidence:** HIGH - - -## User Constraints (from CONTEXT.md) - -### Locked Decisions -- `violationCodes` stored as a comma-separated `TEXT` column (e.g. `"04L,10F,09C"`) on the report entity — no extra table -- `notes` stored as a separate free-text `TEXT` column -- Both fields are optional at creation, editable via PATCH -- `grade` stored as Java enum `Grade {A, B, C, F}`, persisted with `@Enumerated(EnumType.STRING)` -- `status` stored as Java enum `Status {OPEN, IN_PROGRESS, RESOLVED}`, persisted with `@Enumerated(EnumType.STRING)` -- Photos saved to `/app/uploads/{reportId}/{filename}` inside the container -- `/app/uploads` mounted as a named Docker volume — files survive `docker compose down && up` -- Upload path configurable via `app.uploads.dir` property (default `/app/uploads`) -- `GET /api/reports/{id}/photo` streams file bytes back (not a static resource URL) -- `photoPath` stored as a single `TEXT` column — one photo per report; second upload overwrites -- `PATCH /api/reports/{id}` — partial update; only fields present in the request body are updated -- Editable fields: `grade`, `status`, `violationCodes`, `notes` -- Non-owner PATCH attempt → HTTP 403 `{"status": "error", "message": "Forbidden"}` -- `restaurantId` cannot be changed after creation -- `GET /api/reports` returns authenticated controller's own reports only -- Each list item enriched with `restaurantName` and `borough` from MongoDB -- Filter: `?status=OPEN|IN_PROGRESS|RESOLVED` (optional); absent → all reports for that controller -- Repository methods: `findByUserId(Long userId)` and `findByUserIdAndStatus(Long userId, Status status)` - -### Claude's Discretion -- Exact `InspectionReportEntity` column names and nullable constraints (follow `BookmarkEntity` conventions) -- File naming on disk (timestamp + original filename is a safe default) -- `multipart/form-data` handling details for photo upload endpoint -- Exact Hibernate DDL for enums and text columns - -### Deferred Ideas (OUT OF SCOPE) -- None — discussion stayed within phase scope - - - -## Phase Requirements - -| ID | Description | Research Support | -|----|-------------|-----------------| -| CTRL-01 | Controller can create an inspection report for a restaurant (violations, grade A/B/C/F, status open/in-progress/resolved) | POST endpoint + `InspectionReportEntity` JPA entity + `ReportRepository` | -| CTRL-02 | Controller can view a list of their own submitted inspection reports | GET endpoint with `findByUserId` / `findByUserIdAndStatus`, MongoDB enrichment | -| CTRL-03 | Controller can edit their own inspection reports | PATCH endpoint with ownership check (403 on mismatch) | -| CTRL-04 | Controller can attach a photo to an inspection report | Multipart upload endpoint + named Docker volume | - - ---- - -## Summary - -Phase 2 adds four REST endpoints under `/api/reports/**` secured exclusively to `ROLE_CONTROLLER`. The -security guard is already in place in `SecurityConfig` (`.antMatchers("/api/reports/**").hasRole("CONTROLLER")`). -All implementation relies on libraries already in the project: Spring Data JPA (entity + repository), -Spring Web (`@RequestParam MultipartFile`), and the existing `RestaurantDAO.findByRestaurantId()` for MongoDB -enrichment. No new Maven dependencies are needed. - -The main engineering decisions are already locked: a single `InspectionReportEntity` table in PostgreSQL -carries the report data (enums as strings, commas-separated violation codes, nullable text columns), and a -named Docker volume (`uploads_data:/app/uploads`) persists photo files across container restarts. The photo -endpoint streams bytes directly with `ResponseEntity` using `UrlResource` — no static serving config. - -`AppConfig` resolves env vars by uppercasing and replacing dots with underscores, so adding -`app.uploads.dir` with a default of `/app/uploads` will automatically be overridable via -`APP_UPLOADS_DIR` in `docker-compose.yml`. The `BookmarkEntity` + `BookmarkRepository` pair is the -direct structural template for the new entity and repository; `UserController.getCurrentUser()` is the -direct template for the controller's auth helper. - -**Primary recommendation:** Build exactly four focused plans — (1) entity + repository, (2) POST + GET -endpoints, (3) PATCH endpoint, (4) photo upload + Docker volume — in that order, as each plan's output -is consumed by the next. - ---- - -## Standard Stack - -### Core (already in pom.xml — no additions needed) -| Library | Version | Purpose | Why Standard | -|---------|---------|---------|--------------| -| spring-boot-starter-data-jpa | 2.6.15 (BOM) | JPA entity + Spring Data repository | Already used for `BookmarkEntity`/`UserEntity` | -| spring-boot-starter-web | 2.6.15 (BOM) | REST endpoints + `MultipartFile` | Already used by all controllers | -| postgresql | 2.6.15 (BOM) | JDBC driver for PostgreSQL | Already powers `users`/`bookmarks` tables | -| mongodb-driver-sync | 2.6.15 (BOM) | MongoDB read for name/borough enrichment | Already used by `RestaurantDAOImpl` | - -### No New Dependencies -All capabilities required for this phase (JPA entities, multipart file upload, file streaming with -`UrlResource`) are provided by `spring-boot-starter-web` and `spring-boot-starter-data-jpa`, which are -already on the classpath. The `pom.xml` does NOT need to change. - -### Spring Boot 2.6.15 `MultipartFile` — built-in defaults -Spring Boot autoconfigures multipart support by default: -- Max file size: 1 MB (configurable via `spring.servlet.multipart.max-file-size`) -- Max request size: 10 MB (configurable via `spring.servlet.multipart.max-request-size`) -For academic scope, defaults are sufficient. If photos are larger, add to `application.properties`: -```properties -spring.servlet.multipart.max-file-size=10MB -spring.servlet.multipart.max-request-size=10MB -``` - ---- - -## Architecture Patterns - -### Recommended Project Structure additions -``` -com.aflokkat/ -├── entity/ -│ └── InspectionReportEntity.java # new — mirrors BookmarkEntity structure -├── repository/ -│ └── ReportRepository.java # new — mirrors BookmarkRepository -├── controller/ -│ └── ReportController.java # new — mirrors UserController pattern -└── dto/ - └── ReportRequest.java # new — POST/PATCH request body -``` - -### Pattern 1: JPA Entity with Enum columns (mirrors BookmarkEntity) - -**What:** `InspectionReportEntity` uses the same `@ManyToOne(fetch=FetchType.LAZY)` + `@JoinColumn` -pattern as `BookmarkEntity`. Enums are stored as strings via `@Enumerated(EnumType.STRING)`. - -**When to use:** Any PostgreSQL entity that owns a foreign key to `users`. - -**Example:** -```java -// Template source: src/main/java/com/aflokkat/entity/BookmarkEntity.java -@Entity -@Table(name = "inspection_reports") -public class InspectionReportEntity { - - @Id - @GeneratedValue(strategy = GenerationType.IDENTITY) - private Long id; - - @ManyToOne(fetch = FetchType.LAZY) - @JoinColumn(name = "user_id", nullable = false) - private UserEntity user; - - @Column(name = "restaurant_id", nullable = false) - private String restaurantId; - - @Enumerated(EnumType.STRING) - @Column(nullable = false) - private Grade grade; - - @Enumerated(EnumType.STRING) - @Column(nullable = false) - private Status status; - - @Column(columnDefinition = "TEXT") - private String violationCodes; // comma-separated, nullable - - @Column(columnDefinition = "TEXT") - private String notes; // nullable - - @Column(columnDefinition = "TEXT") - private String photoPath; // nullable — set by upload endpoint - - @Column(name = "created_at") - private Date createdAt = new Date(); - - @Column(name = "updated_at") - private Date updatedAt = new Date(); - - // ... getters / setters -} -``` - -The two enums live alongside the entity: -```java -public enum Grade { A, B, C, F } -public enum Status { OPEN, IN_PROGRESS, RESOLVED } -``` - -Hibernate auto-DDL (`spring.jpa.hibernate.ddl-auto=update`) will create the `inspection_reports` table -on first startup — no SQL migration script is needed. - -### Pattern 2: Spring Data Repository with derived queries (mirrors BookmarkRepository) - -**What:** `ReportRepository` extends `JpaRepository` and declares two -derived-query methods to filter by owner and optionally by status. - -**Example:** -```java -// Template source: src/main/java/com/aflokkat/repository/BookmarkRepository.java -@Repository -public interface ReportRepository extends JpaRepository { - List findByUserId(Long userId); - List findByUserIdAndStatus(Long userId, Status status); -} -``` - -Spring Data JPA generates both queries at startup via the naming convention — no `@Query` annotation -needed. - -### Pattern 3: `getCurrentUser()` helper in ReportController (mirrors UserController) - -**What:** Extract the authenticated username from `SecurityContextHolder`, load the `UserEntity` from -`UserRepository`. Copy verbatim from `UserController.getCurrentUser()`. - -**Example:** -```java -// Template source: src/main/java/com/aflokkat/controller/UserController.java -private UserEntity getCurrentUser() { - String username = SecurityContextHolder.getContext().getAuthentication().getName(); - return userRepository.findByUsername(username) - .orElseThrow(() -> new IllegalArgumentException("User not found")); -} -``` - -### Pattern 4: Ownership check → HTTP 403 - -**What:** After loading the report from the repository, compare `report.getUser().getId()` against -`currentUser.getId()`. On mismatch, return HTTP 403 manually (do not throw — `ResponseUtil.errorResponse` -maps `IllegalArgumentException` to 400, not 403). - -**Example:** -```java -if (!report.getUser().getId().equals(currentUser.getId())) { - Map body = new HashMap<>(); - body.put("status", "error"); - body.put("message", "Forbidden"); - return ResponseEntity.status(HttpStatus.FORBIDDEN).body(body); -} -``` - -### Pattern 5: Photo upload with `MultipartFile` + `UrlResource` streaming - -**What:** `POST /api/reports/{id}/photo` accepts `multipart/form-data` with a `file` part. Saves to -`{uploadsDir}/{reportId}/{timestamp}_{originalFilename}`. Updates `photoPath` on the entity. -`GET /api/reports/{id}/photo` loads the file as a `UrlResource` and streams it back with correct -`Content-Type`. - -**Example — upload:** -```java -@PostMapping(value = "/{id}/photo", consumes = MediaType.MULTIPART_FORM_DATA_VALUE) -public ResponseEntity> uploadPhoto( - @PathVariable Long id, - @RequestParam("file") MultipartFile file) { - // ... ownership check, save file, update entity -} -``` - -**Example — stream:** -```java -@GetMapping("/{id}/photo") -public ResponseEntity getPhoto(@PathVariable Long id) { - // ... - Path filePath = Paths.get(report.getPhotoPath()); - Resource resource = new UrlResource(filePath.toUri()); - String contentType = Files.probeContentType(filePath); // java.nio.file.Files - return ResponseEntity.ok() - .contentType(MediaType.parseMediaType(contentType != null ? contentType : "application/octet-stream")) - .body(resource); -} -``` - -`Files.probeContentType()` is standard Java NIO — no extra library needed. - -### Pattern 6: MongoDB enrichment in list/create responses - -**What:** After saving or listing reports, call `restaurantDAO.findByRestaurantId(report.getRestaurantId())` -to pull `name` and `borough` from MongoDB. Assemble a response map with both JPA and MongoDB fields. - -**Example:** -```java -// Template: UserController.getBookmarks() → restaurantDAO.findByIds() -Restaurant r = restaurantDAO.findByRestaurantId(entity.getRestaurantId()); -Map data = new HashMap<>(); -data.put("id", entity.getId()); -data.put("restaurantId", entity.getRestaurantId()); -data.put("restaurantName", r != null ? r.getName() : null); -data.put("borough", r != null ? r.getBorough() : null); -data.put("grade", entity.getGrade()); -data.put("status", entity.getStatus()); -data.put("violationCodes", entity.getViolationCodes()); -data.put("notes", entity.getNotes()); -data.put("photoPath", entity.getPhotoPath()); -data.put("createdAt", entity.getCreatedAt()); -data.put("updatedAt", entity.getUpdatedAt()); -``` - -### Pattern 7: `app.uploads.dir` property via AppConfig - -**What:** `AppConfig.getProperty()` resolves `app.uploads.dir` as env var `APP_UPLOADS_DIR` first, -then `.env`, then `application.properties`. Add a static getter that mirrors the existing pattern. - -**Example:** -```java -// Template: AppConfig.getRedisHost() / getRedisPort() -public static String getUploadsDir() { - return getProperty("app.uploads.dir", "/app/uploads"); -} -``` - -In `application.properties`: -```properties -app.uploads.dir=/app/uploads -``` - -In `docker-compose.yml` (app service): -```yaml -environment: - APP_UPLOADS_DIR: /app/uploads -volumes: - - uploads_data:/app/uploads -``` - -Top-level `volumes:` block: -```yaml -volumes: - mongodb_data: - postgres_data: - uploads_data: # new -``` - -### Anti-Patterns to Avoid - -- **Returning 400 for ownership violations:** `ResponseUtil.errorResponse()` maps `IllegalArgumentException` - to HTTP 400. Never throw an exception for 403 — build the response map manually with - `ResponseEntity.status(HttpStatus.FORBIDDEN)`. -- **Eagerly fetching the user relation:** `@ManyToOne(fetch = FetchType.LAZY)` is correct for this entity. - Calling `report.getUser()` outside a transaction scope will throw `LazyInitializationException` — - always load the report inside the controller method's transaction or use `.getId()` directly via a - `findByUserId` query instead. -- **Storing the full file path and making it public:** `photoPath` is an internal disk path. The API - returns `GET /api/reports/{id}/photo` as the URL, not the raw file path. -- **Binding a `@RequestBody` for PATCH and applying all fields blindly:** Only apply non-null fields from - the DTO. A null `grade` in the JSON body means "leave unchanged", not "set to null". -- **Mounting a non-existent or broken directory as a Docker volume:** The `init-restaurants.js` incident - (a root-owned directory) is the precedent. Verify `/app/uploads` is a clean directory, not a file or - a root-owned artifact, before the volume mount. - ---- - -## Don't Hand-Roll - -| Problem | Don't Build | Use Instead | Why | -|---------|-------------|-------------|-----| -| Derived query for owner filter | Custom JPQL `@Query` | `findByUserId` naming convention | Spring Data JPA generates it | -| MIME type detection | Custom extension map | `java.nio.file.Files.probeContentType()` | JDK built-in, handles edge cases | -| File streaming | Byte array in memory | `UrlResource` + `ResponseEntity` | Streams without loading entire file into heap | -| Table creation | Manual `CREATE TABLE` SQL script | Hibernate `ddl-auto=update` | Already the project pattern | -| JSON error shape | Custom exception handler | `ResponseUtil.errorResponse()` + manual 403 map | Consistent with all other controllers | - -**Key insight:** This phase adds zero new libraries. Everything (JPA, multipart, file streaming, enums, -owned queries) is already shipped with Spring Boot 2.6.15 on the classpath. - ---- - -## Common Pitfalls - -### Pitfall 1: PATCH applies nulls and wipes existing data -**What goes wrong:** Deserializing `{"grade": null}` and calling `entity.setGrade(null)` clears the -field even though the client only wanted to update `status`. -**Why it happens:** Jackson maps absent and explicitly-null JSON fields the same way when using a POJO. -**How to avoid:** Use a dedicated `ReportPatchRequest` DTO. In the controller, check each field for null -before applying: `if (req.getGrade() != null) entity.setGrade(req.getGrade())`. -**Warning signs:** Tests that send a partial body and then GET the same report see cleared fields. - -### Pitfall 2: Lazy loading `user` outside a transaction -**What goes wrong:** `report.getUser().getId()` throws `org.hibernate.LazyInitializationException` when -called after the transaction that loaded `report` has closed (common in @RestController methods without -`@Transactional`). -**Why it happens:** `FetchType.LAZY` defers loading the `user` row until it is first accessed. If the -Hibernate session is closed before access, the proxy throws. -**How to avoid:** Either (a) add `@Transactional` to the controller method, or (b) use -`report.getUser().getId()` immediately after loading within the same call stack, or (c) add a -`findByIdAndUserId(Long id, Long userId)` method to the repository so the ownership check happens in SQL. -**Warning signs:** `LazyInitializationException: could not initialize proxy` in the logs. - -### Pitfall 3: Docker volume not declared in top-level `volumes:` -**What goes wrong:** `docker compose up` fails with `service "app" refers to undefined volume` or the -container starts but writes to an anonymous volume that is lost on `down`. -**Why it happens:** A named volume under `services.app.volumes` must also be declared under the -top-level `volumes:` key. -**How to avoid:** Add `uploads_data:` to the top-level `volumes:` block alongside `mongodb_data` and -`postgres_data`. Verify with `docker volume ls` after the first `docker compose up`. -**Warning signs:** Photos are accessible in the running container but disappear after `docker compose down && up`. - -### Pitfall 4: Photo directory not created before first write -**What goes wrong:** `Files.copy()` or `FileOutputStream` throws `NoSuchFileException` because -`/app/uploads/{reportId}/` does not exist yet. -**Why it happens:** Docker volume mounts the root `/app/uploads` directory but does not pre-create -subdirectories. -**How to avoid:** Always call `Files.createDirectories(targetDir)` before writing the file — this is -idempotent and safe to call even if the directory exists. -**Warning signs:** `java.nio.file.NoSuchFileException` on first photo upload for any report. - -### Pitfall 5: `Content-Type` header absent on photo streaming response -**What goes wrong:** Browser treats the response as `application/octet-stream` (download prompt) instead -of displaying the image inline. -**Why it happens:** `ResponseEntity` without an explicit `contentType()` defaults to -`application/octet-stream`. -**How to avoid:** Use `Files.probeContentType(path)` and set it on the response. Fall back to -`application/octet-stream` if detection returns null. -**Warning signs:** Browser shows "Save As" dialog instead of rendering the image. - -### Pitfall 6: Enum `@RequestBody` binding fails on mixed case -**What goes wrong:** Sending `{"grade": "a"}` throws `HttpMessageNotReadableException` because Jackson -cannot deserialize lowercase `"a"` into `Grade.A` by default. -**Why it happens:** Jackson enum deserialization is case-sensitive by default. -**How to avoid:** Either (a) document that clients must send uppercase, or (b) add -`@JsonProperty("A") A` annotations on the enum constants, or (c) configure -`spring.jackson.deserialization.read-enums-using-to-string=true` if tolerant matching is desired. -The simplest approach for an academic project: document uppercase and let it fail loudly with a 400. -**Warning signs:** Tests pass with uppercase literals but postman calls with lowercase fail unexpectedly. - ---- - -## Code Examples - -### Create `InspectionReportEntity` record (in POST handler) -```java -// Pattern: BookmarkEntity constructor -InspectionReportEntity report = new InspectionReportEntity(); -report.setUser(currentUser); -report.setRestaurantId(req.getRestaurantId()); -report.setGrade(req.getGrade()); -report.setStatus(req.getStatus() != null ? req.getStatus() : Status.OPEN); -report.setViolationCodes(req.getViolationCodes()); -report.setNotes(req.getNotes()); -report.setCreatedAt(new Date()); -report.setUpdatedAt(new Date()); -InspectionReportEntity saved = reportRepository.save(report); -``` - -### PATCH partial update -```java -if (req.getGrade() != null) { report.setGrade(req.getGrade()); } -if (req.getStatus() != null) { report.setStatus(req.getStatus()); } -if (req.getViolationCodes() != null) { report.setViolationCodes(req.getViolationCodes()); } -if (req.getNotes() != null) { report.setNotes(req.getNotes()); } -report.setUpdatedAt(new Date()); -reportRepository.save(report); -``` - -### File save on upload -```java -String uploadsDir = AppConfig.getUploadsDir(); -Path targetDir = Paths.get(uploadsDir, String.valueOf(reportId)); -Files.createDirectories(targetDir); // idempotent -String filename = System.currentTimeMillis() + "_" + file.getOriginalFilename(); -Path targetPath = targetDir.resolve(filename); -Files.copy(file.getInputStream(), targetPath, StandardCopyOption.REPLACE_EXISTING); -report.setPhotoPath(targetPath.toString()); -report.setUpdatedAt(new Date()); -reportRepository.save(report); -``` - -### Stream photo back -```java -Path filePath = Paths.get(report.getPhotoPath()); -Resource resource = new UrlResource(filePath.toUri()); -if (!resource.exists()) { - return ResponseEntity.notFound().build(); -} -String contentType = Files.probeContentType(filePath); -return ResponseEntity.ok() - .contentType(MediaType.parseMediaType( - contentType != null ? contentType : "application/octet-stream")) - .body(resource); -``` - -### Response enrichment helper -```java -private Map toResponseMap(InspectionReportEntity entity) { - Restaurant restaurant = restaurantDAO.findByRestaurantId(entity.getRestaurantId()); - Map data = new HashMap<>(); - data.put("id", entity.getId()); - data.put("restaurantId", entity.getRestaurantId()); - data.put("restaurantName", restaurant != null ? restaurant.getName() : null); - data.put("borough", restaurant != null ? restaurant.getBorough() : null); - data.put("grade", entity.getGrade()); - data.put("status", entity.getStatus()); - data.put("violationCodes", entity.getViolationCodes()); - data.put("notes", entity.getNotes()); - data.put("photoPath", entity.getPhotoPath() != null - ? "/api/reports/" + entity.getId() + "/photo" : null); - data.put("createdAt", entity.getCreatedAt()); - data.put("updatedAt", entity.getUpdatedAt()); - return data; -} -``` - -Note: expose the photo as a URL (`/api/reports/{id}/photo`), not the raw disk path. - ---- - -## State of the Art - -| Old Approach | Current Approach | When Changed | Impact | -|--------------|------------------|--------------|--------| -| `@WebMvcTest` slice tests | `JUnit 4 + standaloneSetup` | Phase 1 (Mockito/Byte Buddy on Java 25 crash) | ReportController tests must use the same standaloneSetup pattern | -| `mockito-inline` separate artifact | Merged into `mockito-core` 5.x | Phase 1 upgrade | Do NOT add `mockito-inline` to pom.xml | -| Spring Boot `@Autowired` field injection | Constructor injection for services / `@Autowired` on fields still used in controllers | Phase 1 decision | Controllers (`UserController`) still use `@Autowired` on fields — keep that pattern for `ReportController` | - -**Deprecated/outdated:** -- `@WebMvcTest` slice test pattern: DO NOT USE — causes JVM crash on Java 25 with Byte Buddy. Use `JUnit 4 + AnnotationConfigWebApplicationContext + standaloneSetup` (established in Phase 1 `SecurityConfigTest`). -- `mockito-inline` dependency: removed in Phase 1. Using it again will cause MockMaker conflicts. - ---- - -## Open Questions - -1. **`restaurantDAO.findByRestaurantId()` when the restaurant does not exist in MongoDB** - - What we know: The method returns `null` if no document matches. - - What's unclear: Should POST reject a `restaurantId` that does not exist in MongoDB, or silently - proceed and return null for `restaurantName`/`borough`? - - Recommendation: Silently return null for the enrichment fields (academic project, simplest path). - If validation is desired, add an early check and return HTTP 400 with `"Restaurant not found"`. - -2. **`@Transactional` scope for PATCH and upload methods** - - What we know: `UserController` does NOT declare `@Transactional` — it works because JPA methods are - themselves transactional by default. - - What's unclear: Loading an entity and then calling `report.getUser()` (lazy) requires an active - Hibernate session. - - Recommendation: Add `@Transactional` to `PATCH` and ownership-checking methods, OR use a - repository query like `findByIdAndUserId` to avoid touching the lazy `user` proxy at all. - ---- - -## Validation Architecture - -### Test Framework -| Property | Value | -|----------|-------| -| Framework | JUnit 4 + JUnit 5 (Vintage engine) + Mockito 5.17.0 | -| Config file | pom.xml (surefire: `-XX:+EnableDynamicAgentLoading`) | -| Quick run command | `mvn test -Dtest=ReportControllerTest,ReportRepositoryTest -pl .` | -| Full suite command | `mvn test` | - -### Phase Requirements → Test Map -| Req ID | Behavior | Test Type | Automated Command | File Exists? | -|--------|----------|-----------|-------------------|-------------| -| CTRL-01 | POST creates report with MongoDB enrichment | unit | `mvn test -Dtest=ReportControllerTest#createReport*` | ❌ Wave 0 | -| CTRL-02 | GET returns only caller's reports; filter by status works | unit | `mvn test -Dtest=ReportControllerTest#listReports*` | ❌ Wave 0 | -| CTRL-03 | PATCH updates owned report; non-owner gets 403 | unit | `mvn test -Dtest=ReportControllerTest#patchReport*` | ❌ Wave 0 | -| CTRL-04 | Photo upload saves file; GET streams it back | unit | `mvn test -Dtest=ReportControllerTest#photoUpload*` | ❌ Wave 0 | - -### Sampling Rate -- **Per task commit:** `mvn test -Dtest=ReportControllerTest` -- **Per wave merge:** `mvn test` -- **Phase gate:** Full suite green before `/gsd:verify-work` - -### Wave 0 Gaps -- [ ] `src/test/java/com/aflokkat/controller/ReportControllerTest.java` — covers CTRL-01 through CTRL-04 -- [ ] `src/main/java/com/aflokkat/entity/InspectionReportEntity.java` — entity must exist before tests compile -- [ ] `src/main/java/com/aflokkat/repository/ReportRepository.java` — repository must exist before tests compile - -### Test Pattern to Follow -All new tests must use the established Java 25-safe pattern from Phase 1: -```java -// Source: existing AuthServiceTest.java pattern (@ExtendWith(MockitoExtension.class)) -@ExtendWith(MockitoExtension.class) -class ReportControllerTest { - @Mock private ReportRepository reportRepository; - @Mock private RestaurantDAO restaurantDAO; - @Mock private UserRepository userRepository; - // ... standaloneSetup for HTTP-layer assertions -} -``` -Do NOT use `@WebMvcTest` — it crashes the JVM on Java 25. - ---- - -## Sources - -### Primary (HIGH confidence) -- Direct code inspection of `BookmarkEntity.java`, `BookmarkRepository.java`, `UserController.java`, - `SecurityConfig.java`, `AppConfig.java`, `RestaurantDAOImpl.java`, `ResponseUtil.java`, - `docker-compose.yml`, `application.properties`, `pom.xml` — all patterns verified from source -- Spring Boot 2.6.15 BOM — confirms all required libraries are already on the classpath - -### Secondary (MEDIUM confidence) -- Spring Data JPA derived query naming convention (`findByUserIdAndStatus`) — standard documented - behavior, consistent with existing `BookmarkRepository.findByUserId` which works in production - -### Tertiary (LOW confidence) -- None — all findings are directly verified from the project's own source code - ---- - -## Metadata - -**Confidence breakdown:** -- Standard stack: HIGH — verified from `pom.xml`; no new dependencies needed -- Architecture: HIGH — all patterns copied directly from working project code -- Pitfalls: HIGH — lazy-loading and Docker volume issues are verified against known project incidents -- Test patterns: HIGH — based on Phase 1 established patterns that resolve Java 25 / Byte Buddy issues - -**Research date:** 2026-03-30 -**Valid until:** Stable — Spring Boot 2.6.15 is pinned; no fast-moving dependencies introduced diff --git a/.planning/phases/02-controller-reports/02-VALIDATION.md b/.planning/phases/02-controller-reports/02-VALIDATION.md deleted file mode 100644 index 3064b8e..0000000 --- a/.planning/phases/02-controller-reports/02-VALIDATION.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -phase: 2 -slug: controller-reports -status: draft -nyquist_compliant: false -wave_0_complete: false -created: 2026-03-30 ---- - -# Phase 2 — Validation Strategy - -> Per-phase validation contract for feedback sampling during execution. - ---- - -## Test Infrastructure - -| Property | Value | -|----------|-------| -| **Framework** | JUnit 4 + JUnit 5 (Vintage engine) + Mockito 5.17.0 | -| **Config file** | `pom.xml` (surefire: `-XX:+EnableDynamicAgentLoading`) | -| **Quick run command** | `mvn test -Dtest=ReportControllerTest` | -| **Full suite command** | `mvn test` | -| **Estimated runtime** | ~30 seconds | - ---- - -## Sampling Rate - -- **After every task commit:** Run `mvn test -Dtest=ReportControllerTest` -- **After every plan wave:** Run `mvn test` -- **Before `/gsd:verify-work`:** Full suite must be green -- **Max feedback latency:** ~30 seconds - ---- - -## Per-Task Verification Map - -| Task ID | Plan | Wave | Requirement | Test Type | Automated Command | File Exists | Status | -|---------|------|------|-------------|-----------|-------------------|-------------|--------| -| 02-01-01 | 01 | 0 | CTRL-01–04 | unit stub | `mvn test -Dtest=ReportControllerTest` | ❌ W0 | ⬜ pending | -| 02-01-02 | 01 | 1 | CTRL-01 | unit | `mvn test -Dtest=ReportControllerTest#createReport*` | ❌ W0 | ⬜ pending | -| 02-01-03 | 01 | 1 | CTRL-02 | unit | `mvn test -Dtest=ReportControllerTest#listReports*` | ❌ W0 | ⬜ pending | -| 02-02-01 | 02 | 2 | CTRL-03 | unit | `mvn test -Dtest=ReportControllerTest#patchReport*` | ❌ W0 | ⬜ pending | -| 02-03-01 | 03 | 3 | CTRL-04 | unit | `mvn test -Dtest=ReportControllerTest#photoUpload*` | ❌ W0 | ⬜ pending | - -*Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky* - ---- - -## Wave 0 Requirements - -- [ ] `src/main/java/com/aflokkat/entity/InspectionReportEntity.java` — entity must exist before tests compile -- [ ] `src/main/java/com/aflokkat/repository/ReportRepository.java` — repository must exist before tests compile -- [ ] `src/test/java/com/aflokkat/controller/ReportControllerTest.java` — test stubs for CTRL-01 through CTRL-04 - -**Test pattern (mandatory — Java 25 safe):** -```java -@ExtendWith(MockitoExtension.class) -class ReportControllerTest { - @Mock private ReportRepository reportRepository; - @Mock private RestaurantDAO restaurantDAO; - @Mock private UserRepository userRepository; - // standaloneSetup for HTTP-layer assertions -} -``` -**NEVER use `@WebMvcTest`** — crashes JVM on Java 25 (Byte Buddy incompatibility, established in Phase 1). - ---- - -## Manual-Only Verifications - -| Behavior | Requirement | Why Manual | Test Instructions | -|----------|-------------|------------|-------------------| -| Photo survives `docker compose down && docker compose up` | CTRL-04 | Requires live Docker + volume mount | 1. Upload photo via POST. 2. `docker compose down`. 3. `docker compose up -d`. 4. GET photo endpoint returns 200 with file bytes. | - ---- - -## Validation Sign-Off - -- [ ] All tasks have `` verify or Wave 0 dependencies -- [ ] Sampling continuity: no 3 consecutive tasks without automated verify -- [ ] Wave 0 covers all MISSING references -- [ ] No watch-mode flags -- [ ] Feedback latency < 30s -- [ ] `nyquist_compliant: true` set in frontmatter - -**Approval:** pending diff --git a/.planning/phases/03-customer-discovery/03-01-PLAN.md b/.planning/phases/03-customer-discovery/03-01-PLAN.md deleted file mode 100644 index cabf255..0000000 --- a/.planning/phases/03-customer-discovery/03-01-PLAN.md +++ /dev/null @@ -1,206 +0,0 @@ ---- -phase: 03-customer-discovery -plan: 01 -type: tdd -wave: 0 -depends_on: [] -files_modified: - - src/test/java/com/aflokkat/controller/RestaurantControllerSearchTest.java -autonomous: true -requirements: - - CUST-01 - - CUST-03 - -must_haves: - truths: - - "mvn test -Dtest=RestaurantControllerSearchTest compiles and all stubs return a known failure reason (not compile error)" - - "Test for GET /api/restaurants/search?q=pizza exists and fails RED because the endpoint does not exist yet" - - "Test for GET /api/restaurants/map-points exists and fails RED because the method does not exist yet" - artifacts: - - path: "src/test/java/com/aflokkat/controller/RestaurantControllerSearchTest.java" - provides: "Test scaffold for CUST-01 search endpoint and CUST-03 map-points endpoint" - exports: ["testSearch_returnsResults", "testSearch_emptyQuery", "testSearch_shortQuery", "testMapPoints_returnsProjection"] - key_links: - - from: "RestaurantControllerSearchTest" - to: "RestaurantController" - via: "MockMvcBuilders.standaloneSetup()" - pattern: "standaloneSetup\\(restaurantController\\)" ---- - - -Create the Wave 0 test scaffold for the two new RestaurantController endpoints (search and map-points). - -Purpose: Nyquist compliance requires automated tests to exist before implementation. These stubs run RED now and turn GREEN in Plan 02 when the endpoints are implemented. -Output: `RestaurantControllerSearchTest.java` with 4 failing test methods. - - - -@/home/missia03/.claude/get-shit-done/workflows/execute-plan.md -@/home/missia03/.claude/get-shit-done/templates/summary.md - - - -@.planning/PROJECT.md -@.planning/ROADMAP.md -@.planning/phases/03-customer-discovery/03-VALIDATION.md - - - - - -Test class skeleton (from ReportControllerTest.java lines 45-60): -```java -@ExtendWith(MockitoExtension.class) -class ReportControllerTest { - @Mock private ReportRepository reportRepository; - @Mock private RestaurantDAO restaurantDAO; - @Mock private UserRepository userRepository; - - @InjectMocks - private ReportController reportController; - - private MockMvc mockMvc; - - @BeforeEach - void setUp() { - mockMvc = MockMvcBuilders.standaloneSetup(reportController).build(); - } -} -``` - -RestaurantController constructor (from RestaurantController.java): -```java -public class RestaurantController { - private final RestaurantDAO restaurantDAO; - private final RestaurantService restaurantService; - // ... constructor injection -} -``` - -RestaurantDAO interface (from RestaurantDAO.java): -```java -public interface RestaurantDAO { - List findAll(int limit); - List searchByNameOrAddress(String q, int limit); // TO BE ADDED in Plan 02 - List findMapPoints(); // TO BE ADDED in Plan 02 - // ... existing methods -} -``` - - - - - - - Task 1: Write failing test stubs for search and map-points endpoints - src/test/java/com/aflokkat/controller/RestaurantControllerSearchTest.java - - - - src/test/java/com/aflokkat/controller/ReportControllerTest.java (mandatory pattern — use @ExtendWith(MockitoExtension.class) + standaloneSetup, never @WebMvcTest) - - src/main/java/com/aflokkat/controller/RestaurantController.java (constructor to replicate for @InjectMocks) - - src/main/java/com/aflokkat/dao/RestaurantDAO.java (interface — stubs mock methods that do not exist yet; they will be added in Plan 02) - - src/main/java/com/aflokkat/domain/Restaurant.java (POJO used in mock return values) - - - - - testSearch_returnsResults: mock restaurantDAO.searchByNameOrAddress("pizza", 20) returns a list with one Restaurant (name="Pizza Palace", borough="MANHATTAN", restaurantId="12345"); GET /api/restaurants/search?q=pizza returns 200 with body containing status=success and data array with one element - - testSearch_emptyQuery: GET /api/restaurants/search?q= (empty) returns either 400 or an empty data list (both are acceptable — the stub verifies the endpoint wires correctly) - - testSearch_shortQuery: GET /api/restaurants/search?q=a (one char) returns 200; data may be empty because the DAO would return nothing (mock returns empty list) — validates the endpoint does not throw - - testMapPoints_returnsProjection: mock restaurantDAO.findMapPoints() returns a list with one Document containing keys restaurantId, name, lat, lng, grade; GET /api/restaurants/map-points returns 200 with body containing status=success and data array with one element containing a "restaurantId" key - - - - Create `src/test/java/com/aflokkat/controller/RestaurantControllerSearchTest.java`: - - Package: `com.aflokkat.controller` - - Imports needed: - - `org.junit.jupiter.api.BeforeEach`, `org.junit.jupiter.api.Test` - - `org.junit.jupiter.api.extension.ExtendWith` - - `org.mockito.InjectMocks`, `org.mockito.Mock` - - `org.mockito.junit.jupiter.MockitoExtension` - - `org.mockito.Mockito.when` - - `org.springframework.test.web.servlet.MockMvc` - - `org.springframework.test.web.servlet.setup.MockMvcBuilders` - - `org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get` - - `org.springframework.test.web.servlet.result.MockMvcResultMatchers.status` - - `org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath` - - `com.aflokkat.dao.RestaurantDAO` - - `com.aflokkat.domain.Restaurant` - - `com.aflokkat.service.RestaurantService` - - `org.bson.Document` - - `java.util.Arrays`, `java.util.Collections` - - Class annotations: `@ExtendWith(MockitoExtension.class)` - - Fields: - ```java - @Mock private RestaurantDAO restaurantDAO; - @Mock private RestaurantService restaurantService; - @InjectMocks private RestaurantController restaurantController; - private MockMvc mockMvc; - ``` - - setUp(): - ```java - @BeforeEach - void setUp() { - mockMvc = MockMvcBuilders.standaloneSetup(restaurantController).build(); - } - ``` - - testSearch_returnsResults(): - - Build a `Restaurant` object with restaurantId="12345", name="Pizza Palace", borough="MANHATTAN" - - `when(restaurantDAO.searchByNameOrAddress("pizza", 20)).thenReturn(Collections.singletonList(r))` - - Also stub `RestaurantService.toView(r)` — but since `toView` is a static method on RestaurantService, check RestaurantController source first: if it calls `restaurantService.toView()` (instance) mock it; if it calls `RestaurantService.toView()` (static) you may need to mock differently. Looking at the RESEARCH.md pattern: `RestaurantService::toView` is called as a method reference on a stream. Check RestaurantController source for actual call — it likely calls `restaurantService.getRestaurantView(r)` or `RestaurantService.toView(r)`. Use the actual call pattern found in RestaurantController after reading it. - - Perform GET /api/restaurants/search?q=pizza, expect status 200, jsonPath("$.status").value("success"), jsonPath("$.data").isArray() - - testSearch_emptyQuery(): - - `when(restaurantDAO.searchByNameOrAddress("", 20)).thenReturn(Collections.emptyList())` - - GET /api/restaurants/search?q=, expect status 200 OR expect jsonPath("$.data").isEmpty() — use `andExpect(status().isOk())` - - testSearch_shortQuery(): - - `when(restaurantDAO.searchByNameOrAddress("a", 20)).thenReturn(Collections.emptyList())` - - GET /api/restaurants/search?q=a, expect status 200 - - testMapPoints_returnsProjection(): - - Build a `Document` with key-value pairs: put("restaurantId","99999"), put("name","Test Rest"), put("lat",40.7), put("lng",-74.0), put("grade","A") - - `when(restaurantDAO.findMapPoints()).thenReturn(Collections.singletonList(doc))` - - GET /api/restaurants/map-points, expect status 200, jsonPath("$.status").value("success"), jsonPath("$.data[0].restaurantId").value("99999") - - IMPORTANT: These tests will FAIL to compile until Plan 02 adds `searchByNameOrAddress` and `findMapPoints` to the DAO interface. That is the intended RED state. Add a `@Disabled("Wave 0 stub — endpoint added in Plan 02")` annotation on each test method so the suite does not count them as failures during plan 01 execution. Remove the @Disabled annotations at the start of Plan 02 Task 1. - - - - cd /home/missia03/Aflokkat/big_data/quickstart-app && mvn test -Dtest=RestaurantControllerSearchTest -pl . 2>&1 | tail -20 - - - - - File exists at `src/test/java/com/aflokkat/controller/RestaurantControllerSearchTest.java` - - `grep -c "@Test" src/test/java/com/aflokkat/controller/RestaurantControllerSearchTest.java` returns 4 - - `grep "@ExtendWith(MockitoExtension.class)" src/test/java/com/aflokkat/controller/RestaurantControllerSearchTest.java` returns a match - - `grep "standaloneSetup" src/test/java/com/aflokkat/controller/RestaurantControllerSearchTest.java` returns a match - - `grep "@WebMvcTest" src/test/java/com/aflokkat/controller/RestaurantControllerSearchTest.java` returns no match (NEVER use @WebMvcTest) - - `grep "@Disabled" src/test/java/com/aflokkat/controller/RestaurantControllerSearchTest.java` returns 4 matches (one per test method) - - `mvn test -Dtest=RestaurantControllerSearchTest` compiles and all 4 tests are SKIPPED (not failed, not errored) due to @Disabled - - - Test file committed with 4 @Disabled stubs. Suite compiles clean. Wave 0 scaffold complete. - - - - - -`mvn test -Dtest=RestaurantControllerSearchTest` compiles without error; 4 tests skipped (disabled). -`mvn test` full suite still green. - - - -- `RestaurantControllerSearchTest.java` exists with 4 @Disabled test methods -- File uses @ExtendWith(MockitoExtension.class) + standaloneSetup (never @WebMvcTest) -- Full mvn test suite passes (no regressions) - - - -After completion, create `.planning/phases/03-customer-discovery/03-01-SUMMARY.md` - diff --git a/.planning/phases/03-customer-discovery/03-01-SUMMARY.md b/.planning/phases/03-customer-discovery/03-01-SUMMARY.md deleted file mode 100644 index 8b6743d..0000000 --- a/.planning/phases/03-customer-discovery/03-01-SUMMARY.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -phase: 03-customer-discovery -plan: 01 -subsystem: testing -tags: [java, junit5, mockito, spring-mvc, tdd, wave0] - -# Dependency graph -requires: - - phase: 02-controller-reports - provides: RestaurantController, RestaurantDAO, RestaurantService — base architecture for new endpoints -provides: - - RestaurantControllerSearchTest.java with 4 @Disabled Wave 0 stubs (search + map-points) - - searchByNameOrAddress(String q, int limit) added to RestaurantDAO interface - - findMapPoints() added to RestaurantDAO interface - - UnsupportedOperationException stubs in RestaurantDAOImpl (unblocks compile; impl in 03-02) -affects: [03-02-customer-discovery] - -# Tech tracking -tech-stack: - added: [] - patterns: - - "Wave 0 TDD: write @Disabled test stubs against interface methods before implementation exists" - - "@ExtendWith(MockitoExtension.class) + standaloneSetup — the only approved MockMvc pattern; never @WebMvcTest" - -key-files: - created: - - src/test/java/com/aflokkat/controller/RestaurantControllerSearchTest.java - modified: - - src/main/java/com/aflokkat/dao/RestaurantDAO.java - - src/main/java/com/aflokkat/dao/RestaurantDAOImpl.java - -key-decisions: - - "Wave 0 stubs: @Disabled annotation on each test method so suite compiles and skips cleanly until Plan 03-02 enables them" - - "DAO interface methods added in Plan 03-01 with UnsupportedOperationException stubs in Impl — avoids compile break while keeping implementation deferred to 03-02" - -patterns-established: - - "Wave 0 scaffold: interface method declarations + disabled test stubs as a two-commit unit before any endpoint code" - -requirements-completed: [CUST-01, CUST-03] - -# Metrics -duration: 35min -completed: 2026-03-31 ---- - -# Phase 3 Plan 1: Customer Discovery — Wave 0 Test Scaffold Summary - -**TDD Wave 0 scaffold: 4 @Disabled MockMvc stubs for search (CUST-01) and map-points (CUST-03) endpoints, with DAO interface declarations that gate Plan 03-02 implementation** - -## Performance - -- **Duration:** ~35 min -- **Started:** 2026-03-31T09:13:43Z -- **Completed:** 2026-03-31T09:48:26Z -- **Tasks:** 1 -- **Files modified:** 3 - -## Accomplishments -- Created `RestaurantControllerSearchTest.java` with 4 @Disabled test methods following the project's mandatory MockMvc pattern -- Added `searchByNameOrAddress(String q, int limit)` and `findMapPoints()` to `RestaurantDAO` interface — enabling test compilation before implementation -- Added `UnsupportedOperationException` stubs to `RestaurantDAOImpl` to keep the full build and test suite green -- All 4 tests compile and run SKIPPED (not failed) — Nyquist Wave 0 compliance achieved - -## Task Commits - -1. **Task 1: Write failing test stubs for search and map-points endpoints** - `f3b0cb3` (test) - -**Plan metadata:** _(docs commit follows)_ - -## Files Created/Modified -- `src/test/java/com/aflokkat/controller/RestaurantControllerSearchTest.java` - Wave 0 test scaffold, 4 @Disabled stubs for search and map-points -- `src/main/java/com/aflokkat/dao/RestaurantDAO.java` - Added `searchByNameOrAddress` and `findMapPoints` interface declarations -- `src/main/java/com/aflokkat/dao/RestaurantDAOImpl.java` - Added `UnsupportedOperationException` stub implementations - -## Decisions Made -- Adding DAO interface methods in Plan 03-01 (not 03-02) was necessary to allow the test file to compile. The plan noted these were "to be added in Plan 02" but compile-time correctness required them now. Implementations are still deferred to Plan 03-02 via `UnsupportedOperationException`. -- `@Disabled` annotation placed on each test method individually (not at class level) to keep per-test granularity when they are re-enabled in Plan 03-02. - -## Deviations from Plan - -### Auto-fixed Issues - -**1. [Rule 3 - Blocking] Added DAO interface method stubs to allow test compilation** -- **Found during:** Task 1 (writing test stubs) -- **Issue:** `RestaurantControllerSearchTest` calls `restaurantDAO.searchByNameOrAddress()` and `restaurantDAO.findMapPoints()`, but neither method existed on the `RestaurantDAO` interface — the test file would not compile -- **Fix:** Added both method signatures to `RestaurantDAO` interface with Javadoc noting Plan 03-02 implementation. Added `UnsupportedOperationException` stubs to `RestaurantDAOImpl` to satisfy the interface contract without implementing the feature -- **Files modified:** `src/main/java/com/aflokkat/dao/RestaurantDAO.java`, `src/main/java/com/aflokkat/dao/RestaurantDAOImpl.java` -- **Verification:** `mvn test -Dtest=RestaurantControllerSearchTest` compiles clean, 4 tests SKIPPED -- **Committed in:** `f3b0cb3` (part of Task 1 commit) - ---- - -**Total deviations:** 1 auto-fixed (Rule 3 - blocking) -**Impact on plan:** Auto-fix essential for compilation. The plan implied interface methods would be added in Plan 03-02, but the Wave 0 test scaffold requires them at the interface level in Plan 03-01 to compile. No functional scope creep — implementations are still stubbed as `UnsupportedOperationException`. - -## Issues Encountered -None beyond the DAO interface compilation requirement handled via Rule 3 above. - -## User Setup Required -None - no external service configuration required. - -## Next Phase Readiness -- Wave 0 scaffold complete; Plan 03-02 can remove `@Disabled` and implement endpoints -- `RestaurantDAO.searchByNameOrAddress()` and `findMapPoints()` signatures are locked in — Plan 03-02 implements the MongoDB queries -- `RestaurantDAOImpl` stubs throw `UnsupportedOperationException` — they will be replaced with real implementations in Plan 03-02 - ---- -*Phase: 03-customer-discovery* -*Completed: 2026-03-31* - -## Self-Check: PASSED -- `src/test/java/com/aflokkat/controller/RestaurantControllerSearchTest.java` — FOUND -- `.planning/phases/03-customer-discovery/03-01-SUMMARY.md` — FOUND -- Commit `f3b0cb3` — FOUND in git log diff --git a/.planning/phases/03-customer-discovery/03-02-PLAN.md b/.planning/phases/03-customer-discovery/03-02-PLAN.md deleted file mode 100644 index e0984bc..0000000 --- a/.planning/phases/03-customer-discovery/03-02-PLAN.md +++ /dev/null @@ -1,333 +0,0 @@ ---- -phase: 03-customer-discovery -plan: 02 -type: execute -wave: 1 -depends_on: - - 03-01 -files_modified: - - src/main/java/com/aflokkat/dao/RestaurantDAO.java - - src/main/java/com/aflokkat/dao/RestaurantDAOImpl.java - - src/main/java/com/aflokkat/controller/RestaurantController.java - - src/main/java/com/aflokkat/controller/ViewController.java - - src/test/java/com/aflokkat/controller/RestaurantControllerSearchTest.java -autonomous: true -requirements: - - CUST-01 - - CUST-03 - - CUST-04 - -must_haves: - truths: - - "GET /api/restaurants/search?q=pizza returns HTTP 200 with JSON body {status:success, data:[...], count:N}" - - "GET /api/restaurants/map-points returns HTTP 200 with JSON body {status:success, data:[{restaurantId, name, lat, lng, grade}, ...], count:N}" - - "GET /my-bookmarks returns HTTP 200 (renders the my-bookmarks template)" - - "mvn test -Dtest=RestaurantControllerSearchTest passes all 4 tests GREEN" - artifacts: - - path: "src/main/java/com/aflokkat/dao/RestaurantDAO.java" - provides: "Interface declarations for searchByNameOrAddress and findMapPoints" - contains: "searchByNameOrAddress" - - path: "src/main/java/com/aflokkat/dao/RestaurantDAOImpl.java" - provides: "MongoDB $regex search implementation and projection-only map-points pipeline" - contains: "findMapPoints" - - path: "src/main/java/com/aflokkat/controller/RestaurantController.java" - provides: "GET /api/restaurants/search and GET /api/restaurants/map-points endpoints (no @PreAuthorize)" - contains: "map-points" - - path: "src/main/java/com/aflokkat/controller/ViewController.java" - provides: "GET /my-bookmarks view route returning my-bookmarks template" - contains: "my-bookmarks" - key_links: - - from: "RestaurantController.searchRestaurants" - to: "RestaurantDAOImpl.searchByNameOrAddress" - via: "restaurantDAO.searchByNameOrAddress(q, limit)" - pattern: "restaurantDAO\\.searchByNameOrAddress" - - from: "RestaurantController.getMapPoints" - to: "RestaurantDAOImpl.findMapPoints" - via: "restaurantDAO.findMapPoints()" - pattern: "restaurantDAO\\.findMapPoints" ---- - - -Implement the two new REST endpoints (search and map-points) and the /my-bookmarks view route. Enable the Wave 0 test stubs. - -Purpose: CUST-01, CUST-03, and the backend half of CUST-04 depend on these endpoints. Templates cannot wire to the search API until this plan is complete. -Output: Two new public GET endpoints on RestaurantController, two new DAO methods, one new ViewController route, and all 4 test stubs turned GREEN. - - - -@/home/missia03/.claude/get-shit-done/workflows/execute-plan.md -@/home/missia03/.claude/get-shit-done/templates/summary.md - - - -@.planning/ROADMAP.md -@.planning/phases/03-customer-discovery/03-CONTEXT.md -@.planning/phases/03-customer-discovery/03-RESEARCH.md -@.planning/phases/03-customer-discovery/03-01-SUMMARY.md - - - - -```java -@Override -public List findHeatmapData(String borough, int limit) { - List pipeline = new ArrayList<>(); - if (borough != null && !borough.isEmpty()) { - pipeline.add(new Document("$match", new Document("borough", borough))); - } - pipeline.add(new Document("$match", new Document("address.coord", new Document("$exists", true)))); - pipeline.add(new Document("$addFields", new Document("latestScore", - new Document("$arrayElemAt", Arrays.asList("$grades.score", 0))))); - pipeline.add(new Document("$match", new Document("latestScore", new Document("$ne", null)))); - pipeline.add(new Document("$project", new Document("_id", 0) - .append("lat", new Document("$arrayElemAt", Arrays.asList("$address.coord", 1))) - .append("lng", new Document("$arrayElemAt", Arrays.asList("$address.coord", 0))) - .append("weight", "$latestScore"))); - pipeline.add(new Document("$limit", limit)); - return aggregate(pipeline, HeatmapPoint.class); -} -``` -NOTE: findMapPoints() returns List (not a typed POJO), so it uses database.getCollection(...).aggregate(pipeline).forEach(results::add) directly, NOT the aggregate() helper. - - -```java -@GetMapping("/by-borough") -public ResponseEntity> getByBorough() { - try { - List data = restaurantDAO.findCountByBorough(); - Map response = new HashMap<>(); - response.put("status", "success"); - response.put("data", data); - response.put("count", data.size()); - return ResponseEntity.ok(response); - } catch (Exception e) { - return errorResponse(e); - } -} -``` - - -```java -@GetMapping("/restaurant/{id}") -public String restaurantDetail() { - return "restaurant"; -} -``` - - - - - - - Task 1: Add DAO interface methods + implementations (search + map-points) - - src/main/java/com/aflokkat/dao/RestaurantDAO.java - src/main/java/com/aflokkat/dao/RestaurantDAOImpl.java - - - - - src/main/java/com/aflokkat/dao/RestaurantDAO.java (full file — add two method signatures at end of interface before closing brace) - - src/main/java/com/aflokkat/dao/RestaurantDAOImpl.java (full file — add implementations following findHeatmapData pattern; note the aggregate() helper vs direct collection.aggregate()) - - src/main/java/com/aflokkat/config/AppConfig.java (for AppConfig.getMongoCollection() and AppConfig.getMongoDatabase() usage pattern) - - - - - searchByNameOrAddress("pizza", 20): calls restaurantCollection.find() with $or filter on name and address.street using $regex with $options "i"; applies limit; returns List of Restaurant POJOs (using POJO codec already established) - - searchByNameOrAddress("", 20): still calls find() with the regex — empty string regex matches all; caller (controller) decides on empty-query behavior - - findMapPoints(): runs aggregate pipeline on the raw collection (database.getCollection(AppConfig.getMongoCollection())); pipeline has $match (address.coord exists), $project (restaurantId from restaurant_id, name, grade from grades[0], lat from coord[1], lng from coord[0]); returns List of Document objects - - - - In `RestaurantDAO.java`, add two method declarations before the `close()` method: - ```java - /** - * Full-text search by restaurant name or street address (case-insensitive $regex). - * Returns at most {@code limit} results. - */ - List searchByNameOrAddress(String q, int limit); - - /** - * Returns lightweight map points for all restaurants with coordinates. - * Each Document contains: restaurantId, name, lat, lng, grade. - */ - List findMapPoints(); - ``` - Also add `import org.bson.Document;` if not already present. - - In `RestaurantDAOImpl.java`, add the two implementations after the `findAtRiskRestaurants` method: - - ```java - @Override - public List searchByNameOrAddress(String q, int limit) { - Document regex = new Document("$regex", q).append("$options", "i"); - Document filter = new Document("$or", Arrays.asList( - new Document("name", regex), - new Document("address.street", regex) - )); - List results = new ArrayList<>(); - restaurantCollection.find(filter).limit(limit).forEach(results::add); - return results; - } - - @Override - public List findMapPoints() { - List pipeline = Arrays.asList( - new Document("$match", new Document("address.coord", new Document("$exists", true))), - new Document("$project", new Document("_id", 0) - .append("restaurantId", "$restaurant_id") - .append("name", 1) - .append("grade", new Document("$arrayElemAt", Arrays.asList("$grades.grade", 0))) - .append("lat", new Document("$arrayElemAt", Arrays.asList("$address.coord", 1))) - .append("lng", new Document("$arrayElemAt", Arrays.asList("$address.coord", 0))) - ) - ); - List results = new ArrayList<>(); - database.getCollection(AppConfig.getMongoCollection()) - .aggregate(pipeline) - .forEach(results::add); - return results; - } - ``` - - Verify `database` field exists on RestaurantDAOImpl (it is used in findNearby/findById). If the field is named differently, use the correct reference. - Verify `Arrays`, `ArrayList`, `Document` are already imported (they are — check existing imports before adding duplicates). - - - - cd /home/missia03/Aflokkat/big_data/quickstart-app && mvn compile -q 2>&1 | tail -10 - - - - - `grep "searchByNameOrAddress" src/main/java/com/aflokkat/dao/RestaurantDAO.java` returns a match - - `grep "findMapPoints" src/main/java/com/aflokkat/dao/RestaurantDAO.java` returns a match - - `grep "searchByNameOrAddress" src/main/java/com/aflokkat/dao/RestaurantDAOImpl.java` returns a match - - `grep "findMapPoints" src/main/java/com/aflokkat/dao/RestaurantDAOImpl.java` returns a match - - `grep "\\\$regex" src/main/java/com/aflokkat/dao/RestaurantDAOImpl.java` returns a match (confirms regex filter) - - `grep "address.street" src/main/java/com/aflokkat/dao/RestaurantDAOImpl.java` returns a match - - `mvn compile` exits 0 - - - Both DAO methods compile. searchByNameOrAddress and findMapPoints present in interface and implementation. - - - - Task 2: Add REST endpoints to RestaurantController + ViewController route + enable tests - - src/main/java/com/aflokkat/controller/RestaurantController.java - src/main/java/com/aflokkat/controller/ViewController.java - src/test/java/com/aflokkat/controller/RestaurantControllerSearchTest.java - - - - - src/main/java/com/aflokkat/controller/RestaurantController.java (full file — find the class structure, imports, errorResponse() helper; add new methods at the end before closing brace) - - src/main/java/com/aflokkat/controller/ViewController.java (full file — add /my-bookmarks after existing routes) - - src/test/java/com/aflokkat/controller/RestaurantControllerSearchTest.java (full file — remove @Disabled from all 4 test methods) - - src/main/java/com/aflokkat/service/RestaurantService.java (verify whether toView is static or instance; find the method signature — test stubs in Plan 01 need to match) - - - - - GET /api/restaurants/search?q=pizza returns 200 with {status:"success", data:[{restaurantId, name, borough, latestGrade, ...}], count:1} - - GET /api/restaurants/search with missing q param returns 400 (Spring MVC default for missing required @RequestParam) - - GET /api/restaurants/map-points returns 200 with {status:"success", data:[{restaurantId, name, lat, lng, grade}], count:N} - - GET /my-bookmarks returns 200 (template rendered — test is manual, route compile-time verified) - - All 4 tests in RestaurantControllerSearchTest pass GREEN - - - - In `RestaurantController.java`, add two new methods at the end of the class (before the closing brace). Do NOT add @PreAuthorize — /api/restaurants/** is fully public per Phase 1 security decisions: - - ```java - @GetMapping("/search") - public ResponseEntity> searchRestaurants( - @RequestParam String q, - @RequestParam(defaultValue = "20") int limit) { - try { - List data = restaurantDAO.searchByNameOrAddress(q, limit); - List> views = data.stream() - .map(RestaurantService::toView) - .collect(Collectors.toList()); - Map response = new HashMap<>(); - response.put("status", "success"); - response.put("data", views); - response.put("count", views.size()); - return ResponseEntity.ok(response); - } catch (Exception e) { - return errorResponse(e); - } - } - - @GetMapping("/map-points") - public ResponseEntity> getMapPoints() { - try { - List data = restaurantDAO.findMapPoints(); - Map response = new HashMap<>(); - response.put("status", "success"); - response.put("data", data); - response.put("count", data.size()); - return ResponseEntity.ok(response); - } catch (Exception e) { - return errorResponse(e); - } - } - ``` - - Check if `Collectors` and `Document` are already imported. If not, add: - - `import java.util.stream.Collectors;` - - `import org.bson.Document;` - - Check if `RestaurantService::toView` is valid (static method reference). If `toView` is an instance method, use `restaurantService.toView(r)` in a lambda `r -> restaurantService.toView(r)` instead. Read RestaurantService.java to confirm. - - In `ViewController.java`, add after the last existing route: - ```java - @GetMapping("/my-bookmarks") - public String myBookmarks() { - return "my-bookmarks"; - } - ``` - - In `RestaurantControllerSearchTest.java`, remove the `@Disabled(...)` annotation from all 4 test methods. Also fix any mock stubs that reference `RestaurantService::toView` as static vs instance — read RestaurantController.java to see how it calls toView, and align test stubs to mock accordingly (if toView is static, you cannot mock it with Mockito without mockStatic; instead have the mock DAO return a Restaurant object whose fields RestaurantService.toView will map correctly, and do NOT mock RestaurantService.toView directly). - - - - cd /home/missia03/Aflokkat/big_data/quickstart-app && mvn test -Dtest=RestaurantControllerSearchTest -pl . 2>&1 | tail -20 - - - - - `grep "map-points" src/main/java/com/aflokkat/controller/RestaurantController.java` returns a match - - `grep "/search" src/main/java/com/aflokkat/controller/RestaurantController.java` returns a match - - `grep "my-bookmarks" src/main/java/com/aflokkat/controller/ViewController.java` returns a match - - `grep "@Disabled" src/test/java/com/aflokkat/controller/RestaurantControllerSearchTest.java` returns no match (all @Disabled removed) - - `grep "@PreAuthorize" src/main/java/com/aflokkat/controller/RestaurantController.java | grep -E "search|map-points"` returns no match (endpoints are public) - - `mvn test -Dtest=RestaurantControllerSearchTest` exits 0 with 4 tests passing - - `mvn test` full suite exits 0 (no regressions) - - - 4 tests GREEN. Both endpoints registered. /my-bookmarks route wired. Full suite passes. - - - - - -```bash -cd /home/missia03/Aflokkat/big_data/quickstart-app -mvn test -Dtest=RestaurantControllerSearchTest -mvn test -``` -Both must exit 0 with 0 failures. - -Manual spot-check (requires running app): -- `curl http://localhost:8080/api/restaurants/search?q=pizza` returns JSON with status=success -- `curl http://localhost:8080/api/restaurants/map-points` returns JSON with status=success and count > 0 - - - -- searchByNameOrAddress + findMapPoints in DAO interface and implementation -- GET /api/restaurants/search and GET /api/restaurants/map-points registered, no @PreAuthorize -- GET /my-bookmarks route in ViewController -- All 4 RestaurantControllerSearchTest tests pass GREEN -- Full mvn test suite green (no regressions) - - - -After completion, create `.planning/phases/03-customer-discovery/03-02-SUMMARY.md` - diff --git a/.planning/phases/03-customer-discovery/03-02-SUMMARY.md b/.planning/phases/03-customer-discovery/03-02-SUMMARY.md deleted file mode 100644 index 6a9059d..0000000 --- a/.planning/phases/03-customer-discovery/03-02-SUMMARY.md +++ /dev/null @@ -1,132 +0,0 @@ ---- -phase: 03-customer-discovery -plan: 02 -subsystem: api -tags: [java, spring-boot, mongodb, regex-search, map-points, mockito, junit5] - -# Dependency graph -requires: - - phase: 03-customer-discovery - plan: 01 - provides: Wave 0 @Disabled test stubs + DAO interface declarations for searchByNameOrAddress and findMapPoints - - phase: 02-controller-reports - provides: RestaurantController, RestaurantDAO, RestaurantService — base architecture -provides: - - GET /api/restaurants/search?q=... endpoint (case-insensitive $regex, public, no @PreAuthorize) - - GET /api/restaurants/map-points endpoint (lightweight projection, public) - - GET /my-bookmarks view route in ViewController - - searchByNameOrAddress(String q, int limit) — real MongoDB $or $regex implementation - - findMapPoints() — aggregation pipeline returning restaurantId, name, lat, lng, grade -affects: [03-03-customer-discovery, future template wiring for search and map features] - -# Tech tracking -tech-stack: - added: [] - patterns: - - "Direct DAO injection in RestaurantController for endpoints that do not require service-layer orchestration" - - "findMapPoints uses raw database.getCollection().aggregate() (not the typed aggregate() helper) because the return type is List not a typed POJO" - - "Wave 0 -> Wave 1 promotion: remove @Disabled + wire real implementation in the same plan" - - "Drop unmockable @Mock RestaurantService when only static methods (toView) are needed — avoids Mockito VerifyError on Java 25" - -key-files: - created: [] - modified: - - src/main/java/com/aflokkat/dao/RestaurantDAO.java - - src/main/java/com/aflokkat/dao/RestaurantDAOImpl.java - - src/main/java/com/aflokkat/controller/RestaurantController.java - - src/main/java/com/aflokkat/controller/ViewController.java - - src/test/java/com/aflokkat/controller/RestaurantControllerSearchTest.java - -key-decisions: - - "RestaurantDAO injected directly into RestaurantController for search and map-points — no service-layer wrapper needed since there is no business logic beyond delegation" - - "findMapPoints uses raw collection.aggregate() not the typed aggregate() helper — result type is List not a POJO" - - "Remove @Mock RestaurantService from RestaurantControllerSearchTest — Mockito cannot inline-mock RestaurantService on Java 25 (VerifyError); since toView is static no instance mock is needed" - -patterns-established: - - "Wave 1 implementation: remove @Disabled, implement DAO, add controller endpoints in one plan" - -requirements-completed: [CUST-01, CUST-03, CUST-04] - -# Metrics -duration: 30min -completed: 2026-03-31 ---- - -# Phase 3 Plan 2: Customer Discovery — Search + Map-Points Endpoints Summary - -**MongoDB $regex search on name/street and aggregation-based map-points projection wired to two new public REST endpoints, with 4 Wave 0 test stubs promoted to GREEN** - -## Performance - -- **Duration:** ~30 min -- **Started:** 2026-03-31T09:52:07Z -- **Completed:** 2026-03-31T10:22:00Z -- **Tasks:** 2 -- **Files modified:** 5 - -## Accomplishments -- Replaced `UnsupportedOperationException` stubs in `RestaurantDAOImpl` with real MongoDB implementations for `searchByNameOrAddress` and `findMapPoints` -- Added `GET /api/restaurants/search` and `GET /api/restaurants/map-points` to `RestaurantController` — both public, no `@PreAuthorize` -- Added `GET /my-bookmarks` view route to `ViewController` -- Promoted all 4 Wave 0 `@Disabled` test stubs to GREEN in `RestaurantControllerSearchTest` - -## Task Commits - -1. **Task 1: Add DAO interface methods + implementations** - `845ed5f` (feat) -2. **Task 2: Add REST endpoints + ViewController route + enable tests** - `c883e6b` (feat) - -**Plan metadata:** _(docs commit follows)_ - -## Files Created/Modified -- `src/main/java/com/aflokkat/dao/RestaurantDAOImpl.java` - Real `searchByNameOrAddress` ($or $regex on name + address.street) and `findMapPoints` (aggregation pipeline) implementations -- `src/main/java/com/aflokkat/dao/RestaurantDAO.java` - Updated Javadoc to reflect Plan 03-02 implementation -- `src/main/java/com/aflokkat/controller/RestaurantController.java` - Added `RestaurantDAO` field injection, `GET /search` and `GET /map-points` endpoints -- `src/main/java/com/aflokkat/controller/ViewController.java` - Added `GET /my-bookmarks` route -- `src/test/java/com/aflokkat/controller/RestaurantControllerSearchTest.java` - Removed all 4 `@Disabled` annotations, removed unmockable `@Mock RestaurantService` field - -## Decisions Made -- `RestaurantDAO` injected directly into `RestaurantController` alongside `RestaurantService` — the search and map-points endpoints call DAO directly since there is no business logic to encapsulate in the service layer. -- `findMapPoints` uses `database.getCollection(AppConfig.getMongoCollection()).aggregate(pipeline)` (raw `MongoDatabase`) rather than the typed `aggregate()` helper — the return type is `List` not a typed POJO, so the POJO-codec collection cannot be used. -- `@Mock RestaurantService` removed from test — Mockito inline mocking of `RestaurantService` triggers `VerifyError` on Java 25. Since all controller calls to `RestaurantService` in the tested methods are to the static `toView()` method, no instance mock is needed. - -## Deviations from Plan - -### Auto-fixed Issues - -**1. [Rule 1 - Bug] Removed unmockable @Mock RestaurantService from test** -- **Found during:** Task 2 (enabling test stubs) -- **Issue:** `@Mock private RestaurantService restaurantService` caused `Mockito cannot mock this class: RestaurantService — VerifyError` on Java 25. Only 1 of 4 tests errored (the framework tried to create the mock during any test execution in the class). The plan said to align the mock with `toView` static vs instance, but the correct fix is to remove the mock entirely since none of the tested methods call instance methods on `RestaurantService`. -- **Fix:** Removed `@Mock RestaurantService restaurantService` field and `import com.aflokkat.service.RestaurantService` from the test class. The controller's `RestaurantService::toView` static call works without any mock. -- **Files modified:** `src/test/java/com/aflokkat/controller/RestaurantControllerSearchTest.java` -- **Verification:** `mvn test -Dtest=RestaurantControllerSearchTest` exits 0 with 4 tests passing -- **Committed in:** `c883e6b` (Task 2 commit) - ---- - -**Total deviations:** 1 auto-fixed (Rule 1 - bug in test mock setup) -**Impact on plan:** Essential for test correctness on Java 25. No scope creep — the plan explicitly mentioned investigating static vs instance mock, and the fix aligns with the project's documented Java 25 Mockito limitation. - -## Issues Encountered -- Java 25 + Mockito inline mock VerifyError for `RestaurantService` — same root cause as documented in STATE.md for prior phases. Resolved by removing the unnecessary mock (the static `toView` method needs no instance). - -## User Setup Required -None - no external service configuration required. - -## Next Phase Readiness -- `GET /api/restaurants/search` and `GET /api/restaurants/map-points` are live and publicly accessible -- Frontend templates (Plan 03-03) can now wire the search bar to `/api/restaurants/search?q=...` -- The `GET /my-bookmarks` route is registered; the Thymeleaf template is not yet created (Plan 03-03) -- Both endpoints are confirmed GREEN via unit tests - ---- -*Phase: 03-customer-discovery* -*Completed: 2026-03-31* - -## Self-Check: PASSED -- `src/main/java/com/aflokkat/dao/RestaurantDAOImpl.java` — FOUND -- `src/main/java/com/aflokkat/controller/RestaurantController.java` — FOUND -- `src/main/java/com/aflokkat/controller/ViewController.java` — FOUND -- `src/test/java/com/aflokkat/controller/RestaurantControllerSearchTest.java` — FOUND -- `.planning/phases/03-customer-discovery/03-02-SUMMARY.md` — FOUND -- Commit `845ed5f` — FOUND in git log -- Commit `c883e6b` — FOUND in git log diff --git a/.planning/phases/03-customer-discovery/03-03-PLAN.md b/.planning/phases/03-customer-discovery/03-03-PLAN.md deleted file mode 100644 index 95d1066..0000000 --- a/.planning/phases/03-customer-discovery/03-03-PLAN.md +++ /dev/null @@ -1,430 +0,0 @@ ---- -phase: 03-customer-discovery -plan: 03 -type: execute -wave: 2 -depends_on: - - 03-02 -files_modified: - - src/main/resources/templates/index.html - - src/main/resources/templates/my-bookmarks.html -autonomous: false -requirements: - - CUST-01 - - CUST-04 - -must_haves: - truths: - - "A customer can type 2+ characters into a search input on index.html and see a results list appear after 300ms with restaurant name, borough, and grade badge" - - "Clicking a search result card navigates to /restaurant/{id}" - - "A bookmark star button on each search result card calls toggleBookmark() on click" - - "Typing fewer than 2 characters hides the results and shows the normal dashboard" - - "A customer visiting /my-bookmarks sees a card listing their bookmarked restaurants (or an empty-state message if none)" - - "A bookmark star on the /my-bookmarks list removes the entry when clicked (optimistic toggle)" - artifacts: - - path: "src/main/resources/templates/index.html" - provides: "Search card with input, debounced JS, search result rendering using .top-restaurant-item pattern" - contains: "searchTimer" - - path: "src/main/resources/templates/my-bookmarks.html" - provides: "Full /my-bookmarks page with bookmark list cards and empty state" - contains: "my-bookmarks" - key_links: - - from: "index.html search input" - to: "/api/restaurants/search" - via: "fetch('/api/restaurants/search?q=' + encodeURIComponent(q))" - pattern: "api/restaurants/search" - - from: "my-bookmarks.html" - to: "/api/users/me/bookmarks" - via: "fetch with Authorization header (fetchWithAuth)" - pattern: "api/users/me/bookmarks" ---- - - -Add the search bar to index.html and create the /my-bookmarks template. - -Purpose: CUST-01 and CUST-04 customer-facing UI. Wires the two template surfaces to the endpoints delivered in Plan 02. -Output: index.html with search card + JS; my-bookmarks.html new template. - - - -@/home/missia03/.claude/get-shit-done/workflows/execute-plan.md -@/home/missia03/.claude/get-shit-done/templates/summary.md - - - -@.planning/phases/03-customer-discovery/03-CONTEXT.md -@.planning/phases/03-customer-discovery/03-UI-SPEC.md -@.planning/phases/03-customer-discovery/03-RESEARCH.md -@.planning/phases/03-customer-discovery/03-02-SUMMARY.md - - - - - -Existing card CSS token (from index.html — do NOT change): -- .card: background white; border-radius: 12px; box-shadow: 0 8px 30px rgba(0,0,0,0.2); padding: 22px 24px -- .top-restaurant-item: existing list row class for results -- .btn-bookmark: amber star button (existing class) -- .btn-view: view link (existing class) - -Grade badge inline style contract (from 03-UI-SPEC.md — use these exact values): -- Grade A: background:#e8f5e9; color:#2e7d32 -- Grade B: background:#fff8e1; color:#f57f17 -- Grade C/F/other: background:#ffebee; color:#b71c1c -- Shared pill style: display:inline-block; padding:2px 8px; border-radius:12px; font-weight:700; font-size:0.82em - -Bookmark API (from UserController.java — existing, do not rebuild): -- GET /api/users/me/bookmarks → {status:"success", data:[{restaurantId,...}]} -- POST /api/users/me/bookmarks/{restaurantId} -- DELETE /api/users/me/bookmarks/{restaurantId} - -fetchWithAuth pattern (copy verbatim from index.html): -```javascript -function fetchWithAuth(url, options = {}) { - const token = localStorage.getItem("accessToken"); - if (!token) { window.location.href = "/login"; return Promise.reject(); } - options.headers = { ...(options.headers || {}), "Authorization": "Bearer " + token }; - return fetch(url, options).then(r => { if (r.status === 401) { window.location.href = "/login"; } return r; }); -} -``` -(Read actual implementation from index.html lines ~1260-1304 and copy verbatim — do not rewrite) - - - - - - - Task 1: Add search card + debounced JS to index.html - src/main/resources/templates/index.html - - - - src/main/resources/templates/index.html (full file — find: (1) placement of first .dashboard grid after header; (2) existing .top-restaurant-item HTML pattern to reuse; (3) existing .btn-bookmark and .btn-view CSS classes; (4) fetchWithAuth and toggleBookmark/bookmarkedIds JS block lines ~1260-1304; (5) existing login guard at line ~811 — leave it untouched, customers are expected to log in as ROLE_CUSTOMER) - - - - Step 1 — Add search card HTML. - Insert a new `.card` div between the `
` closing tag and the first `.dashboard` grid div. The card contains: - ```html -
-

Search Restaurants

- - -
- ``` - - Step 2 — Add search JS. - In the existing ``), append the following JS. Do NOT replace existing JS — append after the last line: - - ```javascript - // ── Search bar ────────────────────────────────────────────────── - (function() { - const searchInput = document.getElementById('search-input'); - const searchResults = document.getElementById('search-results'); - if (!searchInput) return; - - let searchTimer = null; - - function gradeBadgeHtml(grade) { - const g = grade || '—'; - let bg = '#ffebee', color = '#b71c1c'; - if (g === 'A') { bg = '#e8f5e9'; color = '#2e7d32'; } - else if (g === 'B') { bg = '#fff8e1'; color = '#f57f17'; } - return `${g}`; - } - - function borderColor(grade) { - if (grade === 'A') return '#22c55e'; - if (grade === 'B') return '#eab308'; - return '#ef4444'; - } - - function renderResults(restaurants) { - if (!restaurants.length) { - searchResults.innerHTML = '

No restaurants found. Try a different name or address.

'; - searchResults.style.display = 'block'; - return; - } - const html = restaurants.map(r => { - const grade = r.latestGrade || '—'; - const isBookmarked = (typeof bookmarkedIds !== 'undefined') && bookmarkedIds.has(r.restaurantId); - const bookmarkLabel = isBookmarked ? '★' : '☆'; - const bookmarkClass = isBookmarked ? 'btn-bookmark bookmarked' : 'btn-bookmark'; - return `
-
-
${r.name || '—'}
-
${r.borough || '—'}
-
- ${gradeBadgeHtml(grade)} - - View → -
`; - }).join(''); - searchResults.innerHTML = html; - searchResults.style.display = 'block'; - } - - function doSearch(q) { - searchResults.innerHTML = ''; - searchResults.style.display = 'block'; - fetch('/api/restaurants/search?q=' + encodeURIComponent(q) + '&limit=20') - .then(r => r.json()) - .then(data => { - if (data.status === 'success') renderResults(data.data || []); - else searchResults.innerHTML = '

Search failed. Try again.

'; - }) - .catch(() => { - searchResults.innerHTML = '

Search failed. Try again.

'; - }); - } - - function hideResults() { - clearTimeout(searchTimer); - searchResults.style.display = 'none'; - searchResults.innerHTML = ''; - } - - searchInput.addEventListener('input', function() { - clearTimeout(searchTimer); - const q = this.value.trim(); - if (q.length < 2) { hideResults(); return; } - searchTimer = setTimeout(() => doSearch(q), 300); - }); - })(); - // ── End Search bar ─────────────────────────────────────────────── - ``` - - Also add a `@keyframes spin` CSS rule in the existing ` - - -
- ← Dashboard -
... My Bookmarks title ...
-
-

My Bookmarks

-
- - -
-
-
- - - - ``` - - Exact JS for loadBookmarks: - ```javascript - const bookmarkedIds = new Set(); - - function gradeBadgeHtml(grade) { - const g = grade || '—'; - let bg = '#ffebee', color = '#b71c1c'; - if (g === 'A') { bg = '#e8f5e9'; color = '#2e7d32'; } - else if (g === 'B') { bg = '#fff8e1'; color = '#f57f17'; } - return `${g}`; - } - - function renderBookmarks(restaurants) { - const list = document.getElementById('bookmarks-list'); - if (!restaurants.length) { - list.innerHTML = '

You have no saved restaurants yet. Search for restaurants to bookmark them.

'; - return; - } - list.innerHTML = restaurants.map(r => { - const grade = r.latestGrade || (r.grades && r.grades.length ? r.grades[0].grade : '—') || '—'; - const rid = r.restaurantId; - return `
-
-
${r.name || '—'}
-
${r.borough || '—'}
-
- ${gradeBadgeHtml(grade)} - - View → -
`; - }).join(''); - } - - function removeBookmark(restaurantId, btn) { - // Optimistic: hide the row immediately - const row = document.getElementById('bm-' + restaurantId); - if (row) row.style.opacity = '0.4'; - fetchWithAuth('/api/users/me/bookmarks/' + restaurantId, { method: 'DELETE' }) - .then(r => { - if (r && r.ok) { - if (row) row.remove(); - // Show empty state if no more rows - const list = document.getElementById('bookmarks-list'); - if (list && !list.querySelector('.top-restaurant-item')) { - renderBookmarks([]); - } - } else { - if (row) row.style.opacity = '1'; // revert on error - } - }); - } - - function loadBookmarks() { - if (!localStorage.getItem('accessToken')) { - window.location.href = '/login'; - return; - } - fetchWithAuth('/api/users/me/bookmarks') - .then(r => r ? r.json() : null) - .then(data => { - if (data && data.status === 'success') { - renderBookmarks(data.data || []); - } else { - document.getElementById('bookmarks-list').innerHTML = - '

Failed to load bookmarks.

'; - } - }) - .catch(() => { - document.getElementById('bookmarks-list').innerHTML = - '

Failed to load bookmarks.

'; - }); - } - - document.addEventListener('DOMContentLoaded', loadBookmarks); - ``` - - Copy `fetchWithAuth` verbatim from index.html (read the file first to get the exact implementation — do not guess or reconstruct it). - - Page CSS must include (from index.html's established design tokens): - - `body { font-family: "Segoe UI", Tahoma, Geneva, Verdana, sans-serif; background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); min-height: 100vh; padding: 20px; margin: 0; }` - - `.container { max-width: 900px; margin: 0 auto; }` - - `.card { background: white; border-radius: 12px; box-shadow: 0 8px 30px rgba(0,0,0,0.2); padding: 22px 24px; margin-bottom: 20px; }` - - `.back-link { color: white; text-decoration: none; display: inline-block; margin-bottom: 16px; font-size: 0.9em; }` - - `header { color: white; margin-bottom: 24px; }` - - `header h1 { margin: 0; font-size: 1.8em; font-weight: 700; }` - - `.card h2 { color: #667eea; margin: 0 0 16px 0; font-size: 1.25em; font-weight: 600; }` - - `@keyframes spin { to { transform: rotate(360deg); } }` - - - - cd /home/missia03/Aflokkat/big_data/quickstart-app && mvn compile -q && echo "COMPILE OK" && test -f src/main/resources/templates/my-bookmarks.html && echo "TEMPLATE OK" - - - - - `test -f src/main/resources/templates/my-bookmarks.html` exits 0 - - `grep "fetchWithAuth" src/main/resources/templates/my-bookmarks.html` returns a match - - `grep "api/users/me/bookmarks" src/main/resources/templates/my-bookmarks.html` returns a match - - `grep "Search for restaurants" src/main/resources/templates/my-bookmarks.html` returns a match (empty state CTA) - - `grep "removeBookmark" src/main/resources/templates/my-bookmarks.html` returns a match - - `grep "accessToken" src/main/resources/templates/my-bookmarks.html` returns a match (auth guard before fetch) - - `grep "localStorage.getItem" src/main/resources/templates/my-bookmarks.html | grep "login"` returns a match (redirect on no token) - - `mvn compile` exits 0 (Thymeleaf template existence verified at compile time for non-th templates) - - - my-bookmarks.html template created. Bookmark list and empty state wired to /api/users/me/bookmarks. fetchWithAuth copied verbatim from index.html. - - - - - -```bash -cd /home/missia03/Aflokkat/big_data/quickstart-app -mvn test -``` -Must exit 0. - -Manual browser verification (checkpoint task below): -- Log in as customer_test, navigate to /, type "mac" in the search input — results should appear after ~300ms -- Click the ★ on a result — button should change to filled amber ★ -- Navigate to /my-bookmarks — bookmarked restaurant should appear -- Click ★ on the bookmark list — row should disappear, empty state shown if last bookmark - - - -- index.html search card present with debounced input wired to /api/restaurants/search -- Grade badges use correct hex colors (#e8f5e9/#2e7d32, #fff8e1/#f57f17, #ffebee/#b71c1c) -- my-bookmarks.html template created with bookmark list + empty state -- Full mvn test suite green - - - - - Search bar on index.html (debounced, grade badges, bookmark toggle on results) and /my-bookmarks page (bookmark list with remove capability, empty state). - - - 1. Start the app: `docker compose up -d` or `mvn spring-boot:run` - 2. Log in as `customer_test` at http://localhost:8080/login - 3. On the dashboard (http://localhost:8080/), type "mac" in the search field — wait ~300ms — verify results appear with name, borough, grade badge - 4. Type a single letter — verify results disappear - 5. Click ★ on a result — verify button turns amber (saved state) - 6. Navigate to http://localhost:8080/my-bookmarks — verify the bookmarked restaurant appears - 7. Click ★ on the my-bookmarks list — verify the row disappears; if last bookmark, verify empty state message appears - 8. Without logging in (clear localStorage or open incognito), click ★ on a search result — verify redirect to /login - - Type "approved" if all 8 checks pass, or describe any failing step - - - -After completion, create `.planning/phases/03-customer-discovery/03-03-SUMMARY.md` - diff --git a/.planning/phases/03-customer-discovery/03-03-SUMMARY.md b/.planning/phases/03-customer-discovery/03-03-SUMMARY.md deleted file mode 100644 index ac6d718..0000000 --- a/.planning/phases/03-customer-discovery/03-03-SUMMARY.md +++ /dev/null @@ -1,111 +0,0 @@ ---- -phase: 03-customer-discovery -plan: "03" -subsystem: ui -tags: [thymeleaf, javascript, search, bookmarks, html] - -# Dependency graph -requires: - - phase: 03-02 - provides: /api/restaurants/search endpoint and /api/users/me/bookmarks endpoints - -provides: - - index.html search card with debounced JS wired to /api/restaurants/search - - my-bookmarks.html template with bookmark list, optimistic remove, and empty state - -affects: - - 03-04-customer-discovery (restaurant detail page navigation from search results) - -# Tech tracking -tech-stack: - added: [] - patterns: - - Debounced search input: 300ms timer cleared on each keystroke, fires fetch at >= 2 chars - - Grade badge inline style pattern: hex colors per grade (A/B/other) as data-driven pill spans - - Optimistic bookmark remove: row fades to 0.4 opacity, removed from DOM on 200 OK - - fetchWithAuth copied verbatim from index.html to maintain consistent auth token pattern - -key-files: - created: - - src/main/resources/templates/my-bookmarks.html - modified: - - src/main/resources/templates/index.html - -key-decisions: - - "Search card inserted between header and first .dashboard grid — no JS rewrite, append-only pattern" - - "my-bookmarks.html is a standalone HTML template with no Thymeleaf th: attributes — all data loaded via client-side fetch" - - "fetchWithAuth copied verbatim from index.html to avoid divergence in auth handling across pages" - -patterns-established: - - "Grade badge: inline span with background/color hex per grade level (A: #e8f5e9/#2e7d32, B: #fff8e1/#f57f17, other: #ffebee/#b71c1c)" - - "Search results use existing .top-restaurant-item CSS class for visual consistency with top-restaurants widget" - -requirements-completed: [CUST-01, CUST-04] - -# Metrics -duration: 15min -completed: 2026-03-31 ---- - -# Phase 3 Plan 03: Search Bar and My Bookmarks UI Summary - -**Search card with debounced JS on index.html and /my-bookmarks Thymeleaf template with optimistic bookmark removal** - -## Performance - -- **Duration:** ~15 min -- **Started:** 2026-03-31T10:19:00Z -- **Completed:** 2026-03-31T10:34:23Z -- **Tasks:** 2 -- **Files modified:** 2 - -## Accomplishments -- Added search card to index.html between header and first dashboard grid — input fires debounced fetch at >= 2 chars, hides results below 2 chars -- Grade badges rendered with correct hex colors (A: green, B: yellow, other: red) on search result rows -- Bookmark toggle on search result rows reuses existing `toggleBookmark()` and `bookmarkedIds` Set -- Created my-bookmarks.html: full standalone page with bookmark list, optimistic remove (fade + DOM removal), empty state CTA, and auth guard redirecting to /login - -## Task Commits - -Each task was committed atomically: - -1. **Task 1: Add search card + debounced JS to index.html** - `f3d84b8` (feat) -2. **Task 2: Create my-bookmarks.html template** - `a52ec15` (feat) - -## Files Created/Modified -- `src/main/resources/templates/index.html` - Added search card HTML and appended debounced search JS block -- `src/main/resources/templates/my-bookmarks.html` - New template: bookmark list, remove, empty state, fetchWithAuth - -## Decisions Made -- Search JS appended at end of existing ` -``` -Load order: leaflet.min.css → MarkerCluster.css → MarkerCluster.Default.css → leaflet.min.js → leaflet.markercluster.js - - -- Columns: Date | Grade | Score | Violations -- Date: format the Date object as YYYY-MM-DD (or use toLocaleDateString()) -- Violations: join violation codes/descriptions with "; " separator; if empty show "—" -- Rows sorted newest-first (the grades array from /api/restaurants/{id} is already newest-first) -- Table rendered in a .card inside the page; if grades array empty: show "No inspections recorded for this restaurant." - - -{ - status: "success", - data: { - restaurantId: "...", - name: "...", - borough: "...", - cuisine: "...", - address: { building, street, zipCode }, - latestGrade: "A", - latestScore: 7, - grades: [{ grade, score, date, violations? }], - ... - } -} - - - - - - - Task 1: Enhance restaurant.html — remove auth guard, add grade circle, score, inspection history, bookmark button - src/main/resources/templates/restaurant.html - - - - src/main/resources/templates/restaurant.html (full file — understand: (1) the login guard JS that must be REMOVED; (2) the header-card HTML structure to extend with the grade circle column; (3) where the existing fetch for restaurant data is and how it populates the page; (4) existing CSS classes to reuse or reference; (5) the bookmark JS block if any exists — if not, it must be added fresh copying fetchWithAuth from index.html) - - src/main/resources/templates/index.html (lines ~1260-1304 — copy fetchWithAuth, toggleBookmark, bookmarkedIds verbatim) - - - - STEP 1 — Remove auth redirect on page load. - Find and DELETE the block that looks like: - ```javascript - const token = localStorage.getItem("accessToken"); - if (!token) window.location.href = "/login"; - ``` - This guard must be removed entirely. The detail page is now public. Authentication is only needed for the bookmark button. - - STEP 2 — Add grade circle + bookmark button to header-card. - The `.header-card` is a flex row. Add a new column on the right side. Read the existing HTML to find the header-card structure, then add inside it (after `.header-info` div): - ```html -
-
—
-
Score: —
- -
- ``` - - STEP 3 — Add inspection history table section. - After the existing header-card section (and any existing content cards), add a new `.card` div: - ```html -
-

Inspection History

-
- -
-
- ``` - - STEP 4 — Update the existing fetch/data-population JS. - After the restaurant data is fetched and the existing page fields are populated, add the following logic (in the `.then(data => {...})` block, after existing population code): - - ```javascript - // Grade circle - const gradeCircle = document.getElementById('grade-circle'); - const scoreEl = document.getElementById('latest-score'); - const grade = data.latestGrade || '—'; - if (grade === 'A') { - gradeCircle.style.background = '#e8f5e9'; - gradeCircle.style.color = '#2e7d32'; - gradeCircle.style.border = '2px solid #4caf50'; - } else if (grade === 'B') { - gradeCircle.style.background = '#fff8e1'; - gradeCircle.style.color = '#f57f17'; - gradeCircle.style.border = '2px solid #ffc107'; - } else { - gradeCircle.style.background = '#ffebee'; - gradeCircle.style.color = '#b71c1c'; - gradeCircle.style.border = '2px solid #f44336'; - } - gradeCircle.textContent = grade; - if (data.latestScore != null) { - scoreEl.textContent = 'Score: ' + data.latestScore; - } - - // Inspection history table - const historyContainer = document.getElementById('history-container'); - const grades = data.grades || []; - if (!grades.length) { - historyContainer.innerHTML = '

No inspections recorded for this restaurant.

'; - } else { - const rows = grades.map(g => { - const d = g.date ? new Date(g.date).toLocaleDateString('en-US', {year:'numeric',month:'short',day:'numeric'}) : '—'; - const violations = (g.violations && g.violations.length) ? g.violations.join('; ') : '—'; - let badgeBg = '#ffebee', badgeColor = '#b71c1c'; - if (g.grade === 'A') { badgeBg = '#e8f5e9'; badgeColor = '#2e7d32'; } - else if (g.grade === 'B') { badgeBg = '#fff8e1'; badgeColor = '#f57f17'; } - return ` - ${d} - ${g.grade || '—'} - ${g.score != null ? g.score : '—'} - ${violations} - `; - }).join(''); - historyContainer.innerHTML = `
- - - - - - - ${rows} -
DateGradeScoreViolations
`; - } - - // Bookmark toggle state (only if logged in) - if (localStorage.getItem('accessToken')) { - fetchWithAuth('/api/users/me/bookmarks') - .then(r => r ? r.json() : null) - .then(bData => { - if (bData && bData.status === 'success') { - const rid = data.restaurantId; - const isSaved = (bData.data || []).some(b => b.restaurantId === rid); - updateBookmarkBtn(isSaved); - } - }) - .catch(() => {}); - } - ``` - - STEP 5 — Add bookmark helper functions. - Copy `fetchWithAuth` verbatim from index.html. Then add: - ```javascript - let currentRestaurantId = null; // set when restaurant data loads: currentRestaurantId = data.restaurantId; - - function updateBookmarkBtn(saved) { - const btn = document.getElementById('bookmark-btn'); - if (!btn) return; - if (saved) { - btn.textContent = '✓ Saved'; - btn.style.background = '#f5a623'; - btn.style.color = 'white'; - btn.style.borderColor = '#f5a623'; - } else { - btn.textContent = '+ Bookmark'; - btn.style.background = '#f0f2ff'; - btn.style.color = '#667eea'; - btn.style.borderColor = '#c5caf7'; - } - } - - function handleBookmarkClick() { - if (!localStorage.getItem('accessToken')) { - window.location.href = '/login'; - return; - } - const btn = document.getElementById('bookmark-btn'); - const saved = btn.textContent.includes('Saved'); - // Optimistic toggle - updateBookmarkBtn(!saved); - const method = saved ? 'DELETE' : 'POST'; - fetchWithAuth('/api/users/me/bookmarks/' + currentRestaurantId, { method }) - .then(r => { - if (!r || !r.ok) updateBookmarkBtn(saved); // revert on error - }) - .catch(() => updateBookmarkBtn(saved)); - } - ``` - - Also add `@keyframes spin` CSS if not already in the ` - -``` - -**2. Body and header** -```html - -
- -
-
-

Inspector Dashboard

-

NYC Restaurant Inspection Reports

-
-
- ← Home - -
-
- - -
- -
-
- - - - -
- -
- - -
-
-
-``` - -**3. New Report modal** -```html - - -``` - -**4. Script block — top-level utility functions (copy verbatim from index.html lines 815-836 and extract gradeBadgeHtml/borderColor from IIFE)** - -IMPORTANT: All of the following functions MUST be at the top level of the ` - - -``` - -Write all sections above as a single contiguous file. Do not split across multiple writes — create the complete file in one Write tool call. - -Pitfalls to guard: -1. gradeBadgeHtml and borderColor are TOP-LEVEL (not inside IIFE). If they are accidentally wrapped in DOMContentLoaded, onclick handlers will throw ReferenceError. -2. STATUS_VALUES uses enum values (OPEN, IN_PROGRESS, RESOLVED) — not display labels. Passing "In Progress" to ?status= returns 400. -3. uploadPhoto uses raw fetch() with only Authorization header — NEVER fetchWithAuth. -4. openEditId = null is reset BEFORE loadReports() in switchTab() — prevents stale ID after tab switch destroys DOM. -5. PATCH body sends empty string ("") not null for violationCodes and notes — null is ignored by the server. - - - ls -la src/main/resources/templates/dashboard.html && wc -l src/main/resources/templates/dashboard.html && grep -c "gradeBadgeHtml\|fetchWithAuth\|uploadPhoto\|STATUS_VALUES\|openEditId\|selectedRestaurantId" src/main/resources/templates/dashboard.html - - - - src/main/resources/templates/dashboard.html exists with at least 300 lines - - grep finds all 6 key identifiers: gradeBadgeHtml, fetchWithAuth, uploadPhoto, STATUS_VALUES, openEditId, selectedRestaurantId - - grep -n "fetchWithAuth\|formData.append\|Authorization.*token" confirms uploadPhoto uses raw fetch (not fetchWithAuth) for the multipart call - - mvn clean package -DskipTests exits 0 (template is syntactically valid and picked up by Spring Boot) - - - - - - -**Automated checks:** -```bash -# 1. File exists and is non-trivial -wc -l src/main/resources/templates/dashboard.html - -# 2. All critical identifiers present -grep -c "gradeBadgeHtml\|borderColor\|fetchWithAuth\|STATUS_VALUES\|openEditId\|selectedRestaurantId\|uploadPhoto\|refreshThumbnail" src/main/resources/templates/dashboard.html - -# 3. uploadPhoto does NOT use fetchWithAuth (must use raw fetch) -grep -A5 "function uploadPhoto" src/main/resources/templates/dashboard.html - -# 4. PATCH body uses empty string semantics (not null) -grep "edit-violations\|edit-notes" src/main/resources/templates/dashboard.html - -# 5. Application still builds -mvn clean package -DskipTests 2>&1 | tail -10 - -# 6. Full test suite still green -mvn test 2>&1 | tail -20 -``` - -**Manual verification (per VALIDATION.md SC-1 through SC-4):** - -SC-1: Log in as controller. Navigate to `/`. Verify address bar shows `/dashboard`. Verify report cards show restaurant name, grade badge, borough, formatted date. Click each tab — verify Network tab shows only GET /api/reports?status=... fetches (no page navigation). - -SC-2: Click `+ New Report`. Verify modal with backdrop opens. Click outside modal box — verify it closes. Reopen. Type 1 char in restaurant input — no dropdown. Type 2+ chars — dropdown appears. Click a dropdown row — input locks to restaurant name. Click Submit without selecting restaurant — error shown. Select restaurant, select grade, click Submit — modal closes, new card appears at top of list without page reload. - -SC-3: Click Edit on card A — edit form expands below. Click Edit on card B — card A collapses, card B expands. Change grade in card B's panel. Click Save — grade badge updates immediately. Open DevTools Network — only one PATCH request fired. Refresh page — grade persists. Open edit panel, clear violations field, Save, refresh — violations field empty. - -SC-4: Click Photo on a card — file picker opens. Select JPEG/PNG — thumbnail appears on card within ~2s. Refresh page — thumbnail persists. Click Photo again, select different image — thumbnail updates (cache-buster prevents stale image). - - - -- dashboard.html exists with ≥300 lines -- gradeBadgeHtml, borderColor, fetchWithAuth, STATUS_VALUES, openEditId, selectedRestaurantId are all top-level script identifiers (not inside IIFE) -- uploadPhoto uses raw fetch() with Authorization header only — no fetchWithAuth, no Content-Type header -- PATCH body sends document.getElementById('edit-violations-...').value (empty string semantics for clearing) -- openEditId = null is reset in switchTab() before loadReports() is called -- mvn clean package -DskipTests exits 0 -- mvn test exits 0 (no regressions) -- All 4 manual SCs pass per the protocol in VALIDATION.md - - - -After completion, create `.planning/phases/05-controller-workspace/05-02-SUMMARY.md` - diff --git a/.planning/phases/05-controller-workspace/05-02-SUMMARY.md b/.planning/phases/05-controller-workspace/05-02-SUMMARY.md deleted file mode 100644 index 77474b2..0000000 --- a/.planning/phases/05-controller-workspace/05-02-SUMMARY.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -phase: 05-controller-workspace -plan: 02 -subsystem: ui -tags: [vanilla-js, thymeleaf, spa, dashboard, jwt, rest-api] - -# Dependency graph -requires: - - phase: 05-01 - provides: dashboard route (/dashboard), ROLE_CONTROLLER security guard, DashboardSecurityConfig -provides: - - dashboard.html SPA with tabbed report list, inline edit, new report modal, photo upload -affects: [validation, testing, phase-05-sc1, phase-05-sc2, phase-05-sc3, phase-05-sc4] - -# Tech tracking -tech-stack: - added: [] - patterns: - - "vanilla JS SPA pattern: all state client-side, REST API calls via fetchWithAuth" - - "raw fetch() for multipart/form-data upload (not fetchWithAuth to preserve boundary)" - - "inline edit panel pattern: render hidden panel per card, toggle on Edit click" - - "grade-btn selection pattern: CSS class toggle via selectGrade(context, grade)" - - "autocomplete pattern: debounce 300ms, dropdown with click-to-select" - -key-files: - created: - - src/main/resources/templates/dashboard.html - modified: [] - -key-decisions: - - "uploadPhoto uses raw fetch() with Authorization header only — fetchWithAuth would inject Content-Type: application/json which corrupts multipart boundary" - - "gradeBadgeHtml and borderColor declared as top-level functions, not inside IIFE, so renderCardHtml can call them from template literals" - - "openEditId reset in switchTab before loadReports re-renders DOM, preventing stale panel references" - -patterns-established: - - "fetchWithAuth for all authenticated JSON calls" - - "STATUS_VALUES map for tab-to-query-param translation" - - "renderCardHtml + renderEditPanelHtml kept separate so updateCardInPlace can refresh only the card without touching the edit panel" - -requirements-completed: [CTRL-05, CTRL-06, CTRL-07, CTRL-08] - -# Metrics -duration: 5min -completed: 2026-04-03 ---- - -# Phase 5 Plan 02: Controller Dashboard SPA Summary - -**Single-page dashboard.html (448 lines) giving controllers tabbed report list, inline edit, new report modal with restaurant autocomplete, and photo upload via raw fetch** - -## Performance - -- **Duration:** 5 min -- **Started:** 2026-04-03T08:02:27Z -- **Completed:** 2026-04-03T08:07:00Z -- **Tasks:** 1 -- **Files modified:** 1 - -## Accomplishments -- Created complete controller workspace SPA as a single self-contained HTML file -- Tab-filtered report list (All / Open / In Progress / Resolved) using /api/reports?status= -- New Report modal with 300ms-debounced restaurant autocomplete against /api/restaurants/search -- Inline edit panel per report card for grade, status, violation codes, notes with PATCH to /api/reports/{id} -- Photo upload using raw fetch() to preserve multipart boundary (not fetchWithAuth) - -## Task Commits - -1. **Task 1: Create dashboard.html — complete controller workspace SPA** - `b09a11a` (feat) - -**Plan metadata:** _(docs commit follows)_ - -## Files Created/Modified -- `src/main/resources/templates/dashboard.html` - Complete controller workspace SPA (448 lines) - -## Decisions Made -- uploadPhoto uses raw fetch() with only Authorization header — fetchWithAuth injects Content-Type: application/json which corrupts multipart/form-data boundary -- gradeBadgeHtml and borderColor declared at top-level scope (not inside IIFE) to allow calls from template literals inside renderCardHtml -- openEditId reset in switchTab before re-render to prevent stale DOM references -- renderCardHtml and renderEditPanelHtml kept as separate functions so updateCardInPlace can refresh the card independently - -## Deviations from Plan - -None - plan executed exactly as written. - -## Issues Encountered - -None. - -## User Setup Required - -None - no external service configuration required. - -## Next Phase Readiness - -- All 4 CTRL requirements (CTRL-05 through CTRL-08) are implemented in dashboard.html -- Manual validation per VALIDATION.md protocol (SC-1 through SC-4) required before marking phase complete -- Phase 5 is now complete pending validation - ---- -*Phase: 05-controller-workspace* -*Completed: 2026-04-03* diff --git a/.planning/phases/05-controller-workspace/05-CONTEXT.md b/.planning/phases/05-controller-workspace/05-CONTEXT.md deleted file mode 100644 index e2cb2b0..0000000 --- a/.planning/phases/05-controller-workspace/05-CONTEXT.md +++ /dev/null @@ -1,204 +0,0 @@ -# Phase 5: Controller Workspace - Context - -**Gathered:** 2026-04-01 -**Status:** Ready for planning - - -## Phase Boundary - -Controllers can manage their inspection reports entirely through a dedicated UI — search a -restaurant, file a report, edit it, attach a photo — without touching the API directly. -All backend API endpoints already exist from Phase 2. This phase is purely frontend: -one new Thymeleaf template (`dashboard.html`), one new ViewController route, one -SecurityConfig entry. - -No new REST endpoints. No schema changes. - - - - -## Implementation Decisions - -### Area 1: Dashboard vs index — Routing - -- **`/` with ROLE_CONTROLLER → server-side redirect to `/dashboard`.** - `ViewController.index()` reads `SecurityContextHolder.getContext().getAuthentication()` - and checks for `ROLE_CONTROLLER` authority. If found, returns `"redirect:/dashboard"`. - Non-controllers (CUSTOMER, anonymous) see `index.html` as before. - -- **`/dashboard` is SecurityConfig-guarded.** - Add `/dashboard` to the antMatchers requiring `ROLE_CONTROLLER`. An unauthenticated or - CUSTOMER request to `/dashboard` returns 403 / redirects to `/login` via the existing - access-denied handler. No separate client-side guard needed on `dashboard.html`. - -- **`dashboard.html` does NOT add a duplicate token check.** The SecurityConfig guard is - authoritative. The JS on the page still uses `getAuthHeaders()` / `fetchWithAuth()` for - API calls (same pattern as `index.html`). - -### Area 2: Report List Layout - -- **Vertical card list**, consistent with the `top-restaurant-item` row pattern in - `index.html`. No CSS framework — inline CSS matching the existing purple gradient theme - (`#667eea` / `#764ba2`). - -- **Status filter tabs** at the top of the list: - `[ All | Open | In Progress | Resolved ]` - Active tab is highlighted. Clicking a tab calls `GET /api/reports?status=X` (or no - `status` param for All) and re-renders the list client-side. No page reload. - -- **Each card shows:** - - Left border color = grade color (green A, yellow B, red C/F — same as search results) - - Grade badge (same `gradeBadgeHtml()` pattern as `index.html`) - - Restaurant name (fetched from the enriched report response) - - Borough · date (formatted) - - Thumbnail: 48×48px `` calling `GET /api/reports/{id}/photo` — only rendered when - `photoPath` is non-null in the report response - - Action buttons: `[ Edit ]` and `[ Photo ]` - -### Area 3: New Report Form - -- **Modal overlay.** A `[ + New Report ]` button at the top of the dashboard opens a - centered modal with a dark backdrop overlay. Same visual style as the rest of the page. - -- **Modal fields:** - 1. Restaurant search — text input with live autocomplete dropdown (300ms debounce, - calls `GET /api/restaurants/search?q=...&limit=10`). Each dropdown row shows - **name + borough** (e.g. "Joe's Pizza — Manhattan"). Selecting a row locks in the - `restaurantId` hidden value. - 2. Grade — four toggle buttons `[A] [B] [C] [F]`, one selectable at a time - 3. Status — `