Complete backend MVP

docs/API_SPEC.md

@@ -25,21 +25,39 @@ Authorization: Bearer <token>
 ## Reports
 - `POST /reports`: create a report.
 - `GET /reports`: list reports with optional `status`, `category_id`, `area_id`.
+- `GET /operator/reports/assigned`: list reports assigned to the current operator.
+- `GET /operator/reports/open`: list open unassigned reports.
+- `GET /operator/reports/others`: list reports assigned to other operators.
 - `GET /reports/{id}`: report detail.
+- `GET /reports/{id}/intervention-summary`: operator-facing report summary with
+  citizen contact data, media and latest messages.
 - `PATCH /reports/{id}/status`: update status.
 - `POST /reports/{id}/take`: operator/admin takes an open report.
 - `POST /reports/{id}/messages`: write a report message.
 - `GET /reports/{id}/messages`: list report messages.
+- `POST /reports/{id}/messages/{message_id}/flags`: flag a message for moderation.
 - `POST /reports/{id}/assignments`: assign a team.
 - `POST /reports/{id}/feedback`: add citizen feedback.
+- `POST /reports/{id}/flags`: flag a report for moderation.
 - `POST /reports/{id}/media`: upload up to five multipart media files. Supported
   types are JPEG, PNG, WebP, MP4, WebM and QuickTime.
 
+## User
+- `GET /notifications`: list authenticated user notifications.
+- `PATCH /notifications/{id}/read`: mark one notification as read.
+- `GET /me/rewards`: return current points and reward event history.
+
 ## Admin Reference Data
 - `GET|POST /admin/categories`
 - `GET|POST /admin/areas`
 - `GET|POST /admin/teams`
 - `GET /admin/stats/overview`
+- `GET /admin/moderation`: list moderation flags with optional `status`.
+- `PATCH /admin/moderation/{id}`: resolve or dismiss a moderation flag, optionally
+  rejecting the related report.
 - `GET /admin/users`
 - `PATCH /admin/users/{id}/roles`
 - `PATCH /admin/users/{id}/ban`
+
+## Public Data
+- `GET /open-data/reports`: anonymized resolved/closed report export.

docs/DATABASE_SCHEMA.md

@@ -1,6 +1,6 @@
 # Visione Database Schema
 
-The schema is stored in `migrations/001_initial_schema.sql`.
+The schema is stored in ordered SQL migrations under `migrations/`.
 
 Persistence currently uses `drogon::orm::DbClient` with raw parameterized SQL.
 The project does not use Drogon generated models or `Mapper<T>` while the schema
@@ -23,6 +23,9 @@ Important tables:
 - `messages`: citizen/operator report conversation.
 - `feedback`: citizen rating and comment after resolution.
 - `reward_events`: indirect gamification points ledger.
+- `notifications`: local in-app notifications for status changes, messages and
+  reward events.
+- `moderation_flags`: report/message review queue for abusive or invalid content.
 
 GeoJSON is intentionally used instead of MySQL Spatial in milestone 1 to keep
 the local setup simple and portable.

docs/LLM_CONTEXT.md

@@ -3,8 +3,9 @@
 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 reports, assign teams, update status and chat with citizens.
-Admins manage roles, users, areas, teams and reference data.
+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.
 
 The project runs locally on the host machine. Docker is used only for external
 services such as MySQL and MailHog. Real production deployment and Dockerizing
@@ -17,5 +18,5 @@ Important conventions:
 - 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` and `docs/MILESTONE_03.md`
-  describe what has been implemented and what comes next.
+- `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.

docs/MILESTONE_04.md

@@ -0,0 +1,22 @@
+# Milestone 04: Backend Completion
+
+## Implemented in this milestone
+- Added operator queues for assigned reports, open unassigned reports and reports
+  assigned to other operators.
+- Added an operator intervention summary with report data, citizen contact data,
+  media and latest messages.
+- Added local in-app notifications for status changes, team assignment, report
+  messages and reward events.
+- Added citizen reward ledger APIs and automatic points for resolved reports.
+- Added report/message moderation flags with admin/operator review and optional
+  report rejection.
+- Expanded admin statistics with category, team, monthly and segmented
+  resolution-time aggregates.
+- Added anonymized public open-data report export.
+- Updated the manual OpenAPI contract for the new backend routes.
+
+## Intentionally not implemented
+- Real CIE/SPID integration.
+- Real SMS, Telegram, WhatsApp or production SMTP notification delivery.
+- Route optimization for intervention teams.
+- Frontend-specific pages outside the Streamlit API lab.

docs/PROJECT_SPEC.md

@@ -36,13 +36,15 @@ Valid milestone 2 transitions:
 ## MVP Scope
 - Local auth with email OTP delivered through MailHog.
 - MySQL persistence with migrations and seed data.
-- Report creation/list/detail/status/message/assignment/feedback flows.
+- Report creation/list/detail/status/message/assignment/feedback/moderation flows.
 - Area polygons stored as GeoJSON and matched by backend logic.
-- Basic stats for administration.
+- Operator queues for assigned, open and other-operator reports.
+- Local in-app notifications and reward points ledger.
+- Public anonymized open-data report export.
+- Basic and segmented stats for administration.
 
-## Out of Scope for Milestone 1
+## Out of Scope for the Local Backend MVP
 - Real CIE integration.
 - Real SMTP provider, SMS, Telegram or WhatsApp notifications.
 - Route optimization.
-- Public open data export.
 - Full Docker packaging of the backend.