feat: update API documentation and project specifications

docs/LLM_CONTEXT.md

@@ -1,22 +1,120 @@
 # Visione Backend LLM Context
 
-Visione is a C++20/Drogon backend for a municipal urban issue reporting system.
-Citizens create reports with category, position, address, description and media
-attachments.
-Operators manage report queues, assign teams, update status, chat with citizens
-and use intervention summaries.
-Admins manage roles, users, areas, teams, reference data, moderation and stats.
+## What This Repo Is
+Visione is C++20 + Drogon backend for urban issue reporting.
 
-The project runs locally on the host machine. Docker is used only for external
-services such as MySQL and Mailpit. Real production deployment and Dockerizing
-the backend are later delivery tasks.
+Core actors:
+- `citizen`: creates and follows reports
+- `operator`: manages report lifecycle on platform
+- `admin`: manages users/reference data and approves moderation
 
-Important conventions:
+External intervention teams are off-platform. They receive summary through
+public revocable link generated by operator/admin.
 
-- Code and database identifiers are English.
-- The webapp is Italian-facing, so labels or seeded category names may be Italian.
-- Use Drogon references from `/home/gabdevele/Projects/snitchitaly/backend/drogon`
-  and `https://drogonframework.github.io/drogon-docs/`.
-- `AGENTS.md` is the durable agent instruction entrypoint.
-- `docs/MILESTONE_01.md`, `docs/MILESTONE_02.md`, `docs/MILESTONE_03.md` and
-  `docs/MILESTONE_04.md` describe what has been implemented and what comes next.
+## Environment
+- Local backend runs outside Docker.
+- Docker is only for local dependencies like MySQL and Mailpit.
+- Primary commands:
+  - configure: `cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug`
+  - build: `cmake --build build`
+  - test: `ctest --test-dir build --output-on-failure`
+  - openapi: `cmake --build build --target openapi`
+
+## High-Signal Conventions
+- Code, DB identifiers, API fields, comments: English.
+- User-facing labels may be Italian.
+- Keep controller thin, service owns business logic.
+- Use parameterized SQL only.
+- Prefer current code over old assumptions. Route truth is in controller headers.
+
+## Current Auth Model
+- Registration creates `citizen`.
+- Login paths:
+  - OTP email via Mailpit
+  - password fallback
+- Auth token: bearer token from `api_tokens`
+- Banned users cannot authenticate.
+- `must_change_password` blocks most protected operator/admin flows until changed.
+
+## Current Report Workflow
+### Citizen flow
+1. Register/login.
+2. `POST /reports` with category, coordinates, address, description, optional media array.
+3. Backend infers `area_id` by GeoJSON polygon match when possible.
+4. Report starts `OPEN`, status history row inserted.
+5. Citizen can:
+   - list own reports
+   - read detail/history/media
+   - chat on own report
+   - upload more media up to 5 total
+   - read notifications
+   - read rewards
+   - leave feedback only when report is `RESOLVED`
+
+### Operator flow
+1. Read queues:
+   - `/operator/reports/open`
+   - `/operator/reports/assigned`
+   - `/operator/reports/others`
+2. Optional `POST /reports/{id}/take`:
+   `OPEN -> UNDER_REVIEW`, owner becomes operator.
+3. `POST /reports/{id}/assignments`:
+   - if report `OPEN`, operator can assign directly without `take`
+   - owner becomes operator if report had no owner
+   - status becomes `ASSIGNED`
+   - current active assignment closes, new one inserted
+4. Continue status flow:
+   - `ASSIGNED -> IN_PROGRESS -> RESOLVED -> CLOSED`
+   - rejection path to `REJECTED`, then `CLOSED`
+5. Operator can chat with citizen on owned report.
+6. Operator can create moderation flags for report/message on owned report.
+7. Operator can request team suggestions and generate/revoke public intervention link.
+
+### Admin flow
+- Create/update categories, areas, teams
+- List users, edit roles, ban/unban
+- Read stats
+- Review moderation queue and resolve/dismiss flags
+- Optionally reject report during moderation resolution
+
+## Team Model
+- `teams` are external intervention squads, not platform users.
+- `assignments` is history of which external team was assigned.
+- `report_category_team_categories` maps report categories to compatible team categories.
+- `GET /reports/{id}/team-suggestions` returns recommended active teams by:
+  - mapped team category
+  - same area first
+  - area-less team as fallback
+- `POST /reports/{id}/intervention-link` creates revocable public link.
+- `GET /interventions/{token}` returns public summary for field team:
+  report data, location, media, assigned team, masked citizen identity, phone.
+
+## Current Notifications / Rewards / Moderation
+- Notifications: local in-app only.
+- Reward points: awarded once per `(report_id, reason)`.
+- Moderation:
+  - operator creates flag
+  - admin resolves/dismisses
+  - admin may reject report during moderation decision
+
+## Important Behavioral Truths
+- Owner on platform is always `reports.assigned_operator_id`, not team.
+- Feedback does not auto-close report.
+- Public areas list is anonymous.
+- Report categories require auth.
+- Team list requires operator/admin auth.
+- Moderation approval is admin-only.
+- Public intervention token invalid/revoked/scoped-out returns `404`.
+
+## Files To Read First
+- `docs/API_SPEC.md`
+- `docs/ARCHITECTURE.md`
+- `docs/openapi/visione.openapi.yaml`
+- `controllers/*.h`
+- `services/*.cc`
+- `migrations/*.sql`
+
+## External References
+- Local Drogon source: `/home/gabdevele/Projects/snitchitaly/backend/drogon`
+- Drogon docs: `https://drogonframework.github.io/drogon-docs/`
+- Durable agent instructions: `AGENTS.md`